fix(telegram): improve gif handling

* fix: harden cron add and align channels

* fix: keep cron tool id params

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>

.swiftformat

@@ -48,4 +48,4 @@
 --allman false
 
 # Exclusions
---exclude .build,.swiftpm,DerivedData,node_modules,dist,coverage,xcuserdata,apps/macos/Sources/ClawdisProtocol
+--exclude .build,.swiftpm,DerivedData,node_modules,dist,coverage,xcuserdata,apps/macos/Sources/ClawdisProtocol,apps/macos/Sources/ClawdbotProtocol

AGENTS.md

@@ -45,13 +45,15 @@
 - **Restart apps:** “restart iOS/Android apps” means rebuild (recompile/install) and relaunch, not just kill/launch.
 - **Device checks:** before testing, verify connected real devices (iOS/Android) before reaching for simulators/emulators.
 - iOS Team ID lookup: `security find-identity -p codesigning -v` → use Apple Development (…) TEAMID. Fallback: `defaults read com.apple.dt.Xcode IDEProvisioningTeamIdentifiers`.
-- A2UI bundle hash: `src/canvas-host/a2ui/.bundle.hash` is auto-generated; regenerate via `pnpm canvas:a2ui:bundle` (or `scripts/bundle-a2ui.sh`) instead of manual conflict resolution.
+- A2UI bundle hash: `src/canvas-host/a2ui/.bundle.hash` is auto-generated; ignore unexpected changes, and only regenerate via `pnpm canvas:a2ui:bundle` (or `scripts/bundle-a2ui.sh`) when needed. Commit the hash as a separate commit.
 - Notary key file lives at `~/Library/CloudStorage/Dropbox/Backup/AppStore/AuthKey_NJF3NFGTS3.p8` (Sparkle keys live under `~/Library/CloudStorage/Dropbox/Backup/Sparkle`).
+- Notary auth env vars (`APP_STORE_CONNECT_ISSUER_ID`, `APP_STORE_CONNECT_KEY_ID`, `APP_STORE_CONNECT_API_KEY_P8`) are in `~/.profile`.
 - **Multi-agent safety:** do **not** create/apply/drop `git stash` entries unless Peter explicitly asks (this includes `git pull --rebase --autostash`). Assume other agents may be working; keep unrelated WIP untouched and avoid cross-cutting state changes.
 - **Multi-agent safety:** when Peter says "push", you may `git pull --rebase` to integrate latest changes (never discard other agents' work). When Peter says "commit", scope to your changes only. When Peter says "commit all", commit everything in grouped chunks.
 - **Multi-agent safety:** do **not** create/remove/modify `git worktree` checkouts (or edit `.worktrees/*`) unless Peter explicitly asks.
 - **Multi-agent safety:** do **not** switch branches / check out a different branch unless Peter explicitly asks.
 - **Multi-agent safety:** running multiple agents is OK as long as each agent has its own session.
+- **Multi-agent safety:** when you see unrecognized files, keep going; focus on your changes and commit only those.
 - When asked to open a “session” file, open the Pi session logs under `~/.clawdbot/sessions/*.jsonl` (newest unless a specific ID is given), not the default `sessions.json`. If logs are needed from Mac Studio, SSH via Tailscale and read the same path there.
 - Menubar dimming + restart flow mirrors Trimmy: use `scripts/restart-mac.sh` (kills all Clawdbot variants, runs `swift build`, packages, relaunches). Icon dimming depends on MenuBarExtraAccess wiring in AppMain; keep `appearsDisabled` updates intact when touching the status item.
 - Do not rebuild the macOS app over SSH; rebuilds must be run directly on the Mac.

CHANGELOG.md

@@ -4,8 +4,110 @@
 
 ## Unreleased
 
+### Breaking
+- 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.
+
 ### Fixes
-- Cron tool passes `id` to the gateway for update/remove/run/runs (keeps `jobId` input). (#180) — thanks @adamgall
+- Onboarding: resolve CLI entrypoint when running via `npx` so gateway daemon install works without a build step.
+- Onboarding: when OpenAI Codex OAuth is used, default to `openai-codex/gpt-5.2` and warn if the selected model lacks auth.
+- CLI: auto-migrate legacy config entries on command start (same behavior as gateway startup).
+- Auth: prioritize OAuth profiles but fall back to API keys when refresh fails; stored profiles now load without explicit auth order.
+- Control UI: harden config Form view with schema normalization, map editing, and guardrails to prevent data loss on save.
+- Cron: normalize cron.add/update inputs, align channel enums/status fields across gateway/CLI/UI/macOS, and add protocol conformance tests. Thanks @mneves75 for PR #256.
+- Docs: add group chat participation guidance to the AGENTS template.
+- Gmail: stop restart loop when `gog gmail watch serve` fails to bind (address already in use).
+- Linux: auto-attempt lingering during onboarding (try without sudo, fallback to sudo) and prompt on install/restart to keep the gateway alive after logout/idle. Thanks @tobiasbischoff for PR #237.
+- TUI: migrate key handling to the updated pi-tui Key matcher API.
+- Logging: redact sensitive tokens in verbose tool summaries by default (configurable patterns).
+- 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.
+- macOS: drop deprecated `afterMs` from agent wait params to match gateway schema.
+- Auth: add OpenAI Codex OAuth support and migrate legacy oauth.json into auth.json.
+- Model: `/model` list shows auth source (masked key or OAuth email) per provider.
+- Model: `/model list` is an alias for `/model`.
+- Model: `/model` output now includes auth source location (env/auth.json/models.json).
+- Model: avoid duplicate `missing (missing)` auth labels in `/model` list output.
+- Auth: when `openai` has no API key but Codex OAuth exists, suggest `openai-codex/gpt-5.2` vs `OPENAI_API_KEY`.
+- Docs: clarify auth storage, migration, and OpenAI Codex OAuth onboarding.
+- Sandbox: copy inbound media into sandbox workspaces so agent tools can read attachments.
+- Control UI: show a reading indicator bubble while the assistant is responding.
+- Control UI: animate reading indicator dots (honors reduced-motion).
+- Control UI: stabilize chat streaming during tool runs (no flicker/vanishing text; correct run scoping).
+- Status: show runtime (docker/direct) and move shortcuts to `/help`.
+- Status: show model auth source (api-key/oauth).
+- 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.
+- Auto-reply: unify tool/block/final delivery across providers and apply consistent heartbeat/prefix handling. Thanks @MSch for PR #225 (superseded commit 92c953d0749143eb2a3f31f3cd6ad0e8eabf48c3).
+- Heartbeat: make HEARTBEAT_OK ack padding configurable across heartbeat and cron delivery. (#238) — thanks @jalehman
+- 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.
+- Discord: surface missing-permission hints (muted/role overrides) when replies fail.
+- Docs: clarify Slack manifest scopes (current vs optional) with references. Thanks @jarvis-medmatic for PR #235.
+- Control UI: avoid Slack config ReferenceError by reading slack config snapshots. Thanks @sreekaransrinath for PR #249.
+- Telegram: honor routing.groupChat.mentionPatterns for group mention gating. Thanks @regenrek for PR #242.
+- Auto-reply: block unauthorized `/reset` and infer WhatsApp senders from E.164 inputs.
+- Auto-reply: track compaction count in session status; verbose mode announces auto-compactions.
+- Telegram: send GIF media as animations (auto-play) and improve filename sniffing.
+
+### Maintenance
+- Deps: bump pi-* stack, Slack SDK, discord-api-types, file-type, zod, and Biome.
+- Skills: add CodexBar model usage helper with macOS requirement metadata.
+- Skills: add 1Password CLI skill with op examples.
+- Lint: organize imports and wrap long lines in reply commands.
+- Deps: update to latest across the repo.
+
+## 2026.1.5-3
+
+### Fixes
+- NPM package: include missing runtime dist folders (slack/signal/imessage/tui/wizard/control-ui/daemon) to avoid `ERR_MODULE_NOT_FOUND` in Node 25 npx installs.
+
+## 2026.1.5-2
+
+### Fixes
+- NPM package: include `dist/sessions` so `clawdbot agent` resolves session helpers in npx installs.
+- Node 25: avoid unsupported directory import by targeting `qrcode-terminal/vendor/QRCode/*.js` modules.
+
+## 2026.1.5-1
+
+### Fixes
+- NPM package: include `dist/sessions` so `clawdbot agent` resolves session helpers in npx installs.
+- Node 25: avoid unsupported directory import by targeting `qrcode-terminal/vendor/QRCode/index.js`.
+
+## 2026.1.5
+
+### Highlights
+- Models: add image-specific model config (`agent.imageModel` + fallbacks) and scan support.
+- Agent tools: new `image` tool routed to the image model (when configured).
+- Config: default model shorthands (`opus`, `sonnet`, `gpt`, `gpt-mini`, `gemini`, `gemini-flash`).
+- Docs: document built-in model shorthands + precedence (user config wins).
+
+### Fixes
+- Control UI: render Markdown in tool result cards.
+- Control UI: prevent overlapping action buttons in Discord guild rules on narrow layouts.
+- Android: tapping the foreground service notification brings the app to the front. (#179) — thanks @Syhids
+- Cron tool uses `id` for update/remove/run/runs (aligns with gateway params). (#180) — thanks @adamgall
+- Control UI: chat view uses page scroll with sticky header/sidebar and fixed composer (no inner scroll frame).
+- macOS: treat location permission as always-only to avoid iOS-only enums. (#165) — thanks @Nachx639
+- macOS: make generated gateway protocol models `Sendable` for Swift 6 strict concurrency. (#195) — thanks @andranik-sahakyan
+- macOS: bundle QR code renderer modules so DMG gateway boot doesn't crash on missing qrcode-terminal vendor files.
+- macOS: parse JSON5 config safely to avoid wiping user settings when comments are present.
+- WhatsApp: suppress typing indicator during heartbeat background tasks. (#190) — thanks @mcinteerj
+- WhatsApp: mark offline history sync messages as read without auto-reply. (#193) — thanks @mcinteerj
+- Discord: avoid duplicate replies when a provider emits late streaming `text_end` events (OpenAI/GPT).
+- CLI: use tailnet IP for local gateway calls when bind is tailnet/auto (fixes #176).
+- Env: load global `$CLAWDBOT_STATE_DIR/.env` (`~/.clawdbot/.env`) as a fallback after CWD `.env`.
+- Env: optional login-shell env fallback (opt-in; imports expected keys without overriding existing env).
+- Agent tools: OpenAI-compatible tool JSON Schemas (fix `browser`, normalize union schemas).
+- Onboarding: when running from source, auto-build missing Control UI assets (`pnpm ui:build`).
+- Discord/Slack: route reaction + system notifications to the correct session (no main-session bleed).
+- Agent tools: honor `agent.tools` allow/deny policy even when sandbox is off.
+- Discord: avoid duplicate replies when OpenAI emits repeated `message_end` events.
+- Commands: unify /status (inline) and command auth across providers; group bypass for authorized control commands; remove Discord /clawd slash handler.
+- Control UI: render Markdown in chat messages (sanitized).
 
 
 ## 2026.1.4

README.md

@@ -16,99 +16,34 @@
 </p>
 
 **Clawdbot** is a *personal AI assistant* you run on your own devices.
-It answers you on the surfaces you already use (WhatsApp, Telegram, Discord, iMessage, WebChat), can speak and listen on macOS/iOS, 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://clawd.me · Docs: [`docs/index.md`](docs/index.md) · FAQ: [`docs/faq.md`](docs/faq.md) · Wizard: [`docs/wizard.md`](docs/wizard.md) · Docker (optional): [`docs/docker.md`](docs/docker.md) · Discord: https://discord.gg/clawd
+Website: [https://clawdbot.com](https://clawdbot.com) · Docs: [https://docs.clawdbot.com](https://docs.clawdbot.com/) · Showcase: [https://docs.clawdbot.com/showcase](https://docs.clawdbot.com/showcase) · FAQ: [https://docs.clawdbot.com/faq](https://docs.clawdbot.com/faq) · Wizard: [https://docs.clawdbot.com/wizard](https://docs.clawdbot.com/wizard) · Nix: [https://github.com/clawdbot/nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) · Docker: [https://docs.clawdbot.com/docker](https://docs.clawdbot.com/docker) · 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.
 
-Using Claude Pro/Max subscription? See `docs/onboarding.md` for the Anthropic OAuth setup.
+**Subscriptions (OAuth):**
+- **Anthropic** (Claude Pro/Max)
+- **OpenAI** (ChatGPT/Codex)
 
-## Highlights
+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.clawdbot.com/onboarding).
 
-- **Local-first Gateway** — single control plane for sessions, providers, tools, and events.
-- **Multi-surface inbox** — WhatsApp, Telegram, Discord, iMessage, WebChat, macOS, iOS/Android.
-- **Voice Wake + Talk Mode** — always-on speech for macOS/iOS/Android with ElevenLabs.
-- **Live Canvas** — agent-driven visual workspace with A2UI.
-- **First-class tools** — browser, canvas, nodes, cron, sessions, and Discord actions.
-- **Companion apps** — macOS menu bar app + iOS/Android nodes.
-- **Onboarding + skills** — wizard-driven setup with bundled/managed/workspace skills.
+## Recommended setup (from source)
 
-## Everything we built so far
+Do **not** download prebuilt binaries. Build from source.
 
-### Core platform
-- Gateway WS control plane with sessions, presence, config, cron, webhooks, control UI, and Canvas host.
-- CLI surface: gateway, agent, send, wizard, doctor/update, and TUI.
-- Pi agent runtime in RPC mode with tool streaming and block streaming.
-- Session model: `main` for direct chats, group isolation, activation modes, queue modes, reply-back.
-- Media pipeline: images/audio/video, transcription hooks, size caps, temp file lifecycle.
+```bash
+# Clone this repo
+git clone https://github.com/clawdbot/clawdbot.git
+cd clawdbot
 
-### Surfaces + providers
-- WhatsApp (Baileys), Telegram (grammY), Discord (discord.js), Signal (signal-cli), iMessage (imsg), WebChat.
-- Group mention gating, reply tags, per-surface chunking and routing.
-
-### Apps + nodes
-- macOS app: menu bar control plane, Voice Wake/PTT, Talk Mode overlay, WebChat, Debug tools, SSH remote gateway control.
-- iOS node: Canvas, Voice Wake, Talk Mode, camera, screen recording, Bonjour pairing.
-- Android node: Canvas, Talk Mode, camera, screen recording, optional SMS.
-- macOS node mode: system.run/notify + canvas/camera exposure.
-
-### Tools + automation
-- Browser control: dedicated clawd Chrome/Chromium, snapshots, actions, uploads, profiles.
-- Canvas: A2UI push/reset, eval, snapshot.
-- Nodes: camera snap/clip, screen record, location.get, notifications.
-- Cron + wakeups; webhooks; Gmail Pub/Sub triggers.
-- Skills platform: bundled, managed, and workspace skills with install gating + UI.
-
-### Ops + packaging
-- Control UI + WebChat served directly from the Gateway.
-- Tailscale Serve/Funnel or SSH tunnels with token/password auth.
-- Nix mode for declarative config; Docker-based installs.
-- Health, doctor migrations, structured logging, release tooling.
-
-## Changes since 2.0.0-beta5 (2026-01-03)
-
-### Highlights
-- Project rename completed: CLIs, paths, bundle IDs, env vars, and docs unified on Clawdbot.
-- Agent-to-agent relay: `sessions_send` ping‑pong with `REPLY_SKIP` plus announce step with `ANNOUNCE_SKIP`.
-- Gateway config hot reload, configurable port, and Control UI base-path support.
-- Sandbox options: per-session Docker sandbox with hardened limits + optional sandboxed Chromium.
-- New node capability: `location.get` across macOS/iOS/Android (CLI + tools).
-
-### Fixes
-- Presence beacons keep node lists fresh; Instances view stays accurate.
-- Block streaming + chunking reliability (Telegram/Discord ordering, fewer duplicates).
-- WhatsApp GIF playback for MP4-based GIFs.
-- Onboarding/Control UI basePath handling fixes + UI polish.
-- Cleaner logging + clearer tool summaries.
-
-### Breaking
-- Tool names drop the `clawdbot_` prefix (`browser`, `canvas`, `nodes`, `cron`, `gateway`).
-- Bash tool removed `stdinMode: "pty"` support (use tmux for real TTYs).
-- Primary session key is fixed to `main` (or `global` for global scope).
-
-## Project rename + changelog format
-
-Clawdis → Clawdbot. The rename touched every surface, path, and bundle ID. To make that transition explicit, releases now use **date-based versions** (`YYYY.M.D`), and the changelog is compressed into milestone summaries instead of long semver trains. Full detail still lives in git history and the docs.
-
-## How it works (short)
-
-```
-Your surfaces
-   │
-   ▼
-┌───────────────────────────────┐
-│            Gateway            │  ws://127.0.0.1:18789
-│       (control plane)         │  tcp://0.0.0.0:18790 (optional Bridge)
-└──────────────┬────────────────┘
-               │
-               ├─ Pi agent (RPC)
-               ├─ CLI (clawdbot …)
-               ├─ WebChat (browser)
-               ├─ macOS app (Clawdbot.app)
-               └─ iOS node (Canvas + voice)
+pnpm install
+pnpm build
+pnpm ui:build
+pnpm clawdbot onboard
 ```
 
 ## Quick start (from source)
@@ -135,66 +70,184 @@ pnpm gateway:watch
 # Send a message
 pnpm clawdbot send --to +1234567890 --message "Hello from Clawdbot"
 
-# Talk to the assistant (optionally deliver back to WhatsApp/Telegram/Discord)
+# Talk to the assistant (optionally deliver back to WhatsApp/Telegram/Slack/Discord)
 pnpm clawdbot agent --message "Ship checklist" --thinking high
 ```
 
+Upgrading? `clawdbot doctor`.
+
 If you run from source, prefer `pnpm clawdbot …` (not global `clawdbot`).
 
+## Highlights
+
+- **[Local-first Gateway](https://docs.clawdbot.com/gateway)** — single control plane for sessions, providers, tools, and events.
+- **[Multi-surface inbox](https://docs.clawdbot.com/surface)** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, WebChat, macOS, iOS/Android.
+- **[Voice Wake](https://docs.clawdbot.com/voicewake) + [Talk Mode](https://docs.clawdbot.com/talk)** — always-on speech for macOS/iOS/Android with ElevenLabs.
+- **[Live Canvas](https://docs.clawdbot.com/mac/canvas)** — agent-driven visual workspace with [A2UI](https://docs.clawdbot.com/refactor/canvas-a2ui).
+- **[First-class tools](https://docs.clawdbot.com/tools)** — browser, canvas, nodes, cron, sessions, and Discord/Slack actions.
+- **[Companion apps](https://docs.clawdbot.com/macos)** — macOS menu bar app + iOS/Android [nodes](https://docs.clawdbot.com/nodes).
+- **[Onboarding](https://docs.clawdbot.com/wizard) + [skills](https://docs.clawdbot.com/skills)** — wizard-driven setup with bundled/managed/workspace skills.
+
+## Everything we built so far
+
+### Core platform
+- [Gateway WS control plane](https://docs.clawdbot.com/gateway) with sessions, presence, config, cron, webhooks, [Control UI](https://docs.clawdbot.com/web), and [Canvas host](https://docs.clawdbot.com/refactor/canvas-a2ui).
+- [CLI surface](https://docs.clawdbot.com/agent-send): gateway, agent, send, [wizard](https://docs.clawdbot.com/wizard), and [doctor](https://docs.clawdbot.com/doctor).
+- [Pi agent runtime](https://docs.clawdbot.com/agent) in RPC mode with tool streaming and block streaming.
+- [Session model](https://docs.clawdbot.com/session): `main` for direct chats, group isolation, activation modes, queue modes, reply-back. Group rules: [Groups](https://docs.clawdbot.com/groups).
+- [Media pipeline](https://docs.clawdbot.com/images): images/audio/video, transcription hooks, size caps, temp file lifecycle. Audio details: [Audio](https://docs.clawdbot.com/audio).
+
+### Surfaces + providers
+- [Providers](https://docs.clawdbot.com/surface): [WhatsApp](https://docs.clawdbot.com/whatsapp) (Baileys), [Telegram](https://docs.clawdbot.com/telegram) (grammY), [Slack](https://docs.clawdbot.com/slack) (Bolt), [Discord](https://docs.clawdbot.com/discord) (discord.js), [Signal](https://docs.clawdbot.com/signal) (signal-cli), [iMessage](https://docs.clawdbot.com/imessage) (imsg), [WebChat](https://docs.clawdbot.com/webchat).
+- [Group routing](https://docs.clawdbot.com/group-messages): mention gating, reply tags, per-surface chunking and routing. Surface rules: [Surface routing](https://docs.clawdbot.com/surface).
+
+### Apps + nodes
+- [macOS app](https://docs.clawdbot.com/macos): menu bar control plane, [Voice Wake](https://docs.clawdbot.com/voicewake)/PTT, [Talk Mode](https://docs.clawdbot.com/talk) overlay, [WebChat](https://docs.clawdbot.com/webchat), debug tools, [remote gateway](https://docs.clawdbot.com/remote) control.
+- [iOS node](https://docs.clawdbot.com/ios): [Canvas](https://docs.clawdbot.com/mac/canvas), [Voice Wake](https://docs.clawdbot.com/voicewake), [Talk Mode](https://docs.clawdbot.com/talk), camera, screen recording, Bonjour pairing.
+- [Android node](https://docs.clawdbot.com/android): [Canvas](https://docs.clawdbot.com/mac/canvas), [Talk Mode](https://docs.clawdbot.com/talk), camera, screen recording, optional SMS.
+- [macOS node mode](https://docs.clawdbot.com/nodes): system.run/notify + canvas/camera exposure.
+
+### Tools + automation
+- [Browser control](https://docs.clawdbot.com/browser): dedicated clawd Chrome/Chromium, snapshots, actions, uploads, profiles.
+- [Canvas](https://docs.clawdbot.com/mac/canvas): [A2UI](https://docs.clawdbot.com/refactor/canvas-a2ui) push/reset, eval, snapshot.
+- [Nodes](https://docs.clawdbot.com/nodes): camera snap/clip, screen record, [location.get](https://docs.clawdbot.com/location-command), notifications.
+- [Cron + wakeups](https://docs.clawdbot.com/cron); [webhooks](https://docs.clawdbot.com/webhook); [Gmail Pub/Sub](https://docs.clawdbot.com/gmail-pubsub).
+- [Skills platform](https://docs.clawdbot.com/skills): bundled, managed, and workspace skills with install gating + UI.
+
+### Ops + packaging
+- [Control UI](https://docs.clawdbot.com/web) + [WebChat](https://docs.clawdbot.com/webchat) served directly from the Gateway.
+- [Tailscale Serve/Funnel](https://docs.clawdbot.com/tailscale) or [SSH tunnels](https://docs.clawdbot.com/remote) with token/password auth.
+- [Nix mode](https://docs.clawdbot.com/nix) for declarative config; [Docker](https://docs.clawdbot.com/docker)-based installs.
+- [Doctor](https://docs.clawdbot.com/doctor) migrations, [logging](https://docs.clawdbot.com/logging).
+
+## How it works (short)
+
+```
+WhatsApp / Telegram / Slack / Discord / Signal / iMessage / WebChat
+               │
+               ▼
+┌───────────────────────────────┐
+│            Gateway            │  ws://127.0.0.1:18789
+│       (control plane)         │  bridge: tcp://0.0.0.0:18790
+└──────────────┬────────────────┘
+               │
+               ├─ Pi agent (RPC)
+               ├─ CLI (clawdbot …)
+               ├─ WebChat UI
+               ├─ macOS app
+               └─ iOS/Android nodes
+```
+
+## Key subsystems
+
+- **[Gateway WebSocket network](https://docs.clawdbot.com/architecture)** — single WS control plane for clients, tools, and events (plus ops: [Gateway runbook](https://docs.clawdbot.com/gateway)).
+- **[Tailscale exposure](https://docs.clawdbot.com/tailscale)** — Serve/Funnel for the Gateway dashboard + WS (remote access: [Remote](https://docs.clawdbot.com/remote)).
+- **[Browser control](https://docs.clawdbot.com/browser)** — clawd‑managed Chrome/Chromium with CDP control.
+- **[Canvas + A2UI](https://docs.clawdbot.com/mac/canvas)** — agent‑driven visual workspace (A2UI host: [Canvas/A2UI](https://docs.clawdbot.com/refactor/canvas-a2ui)).
+- **[Voice Wake](https://docs.clawdbot.com/voicewake) + [Talk Mode](https://docs.clawdbot.com/talk)** — always‑on speech and continuous conversation.
+- **[Nodes](https://docs.clawdbot.com/nodes)** — Canvas, camera snap/clip, screen record, `location.get`, notifications, plus macOS‑only `system.run`/`system.notify`.
+
+## Tailscale access (Gateway dashboard)
+
+Clawdbot can auto-configure Tailscale **Serve** (tailnet-only) or **Funnel** (public) while the Gateway stays bound to loopback. Configure `gateway.tailscale.mode`:
+
+- `off`: no Tailscale automation (default).
+- `serve`: tailnet-only HTTPS via `tailscale serve` (uses Tailscale identity headers by default).
+- `funnel`: public HTTPS via `tailscale funnel` (requires shared password auth).
+
+Notes:
+- `gateway.bind` must stay `loopback` when Serve/Funnel is enabled (Clawdbot enforces this).
+- Serve can be forced to require a password by setting `gateway.auth.mode: "password"` or `gateway.auth.allowTailscale: false`.
+- 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.clawdbot.com/tailscale) · [Web surfaces](https://docs.clawdbot.com/web)
+
+## Remote Gateway (Linux is great)
+
+It’s perfectly fine to run the Gateway on a small Linux instance. Clients (macOS app, CLI, WebChat) can connect over **Tailscale Serve/Funnel** or **SSH tunnels**, and you can still pair device nodes (macOS/iOS/Android) to execute device‑local actions when needed.
+
+- **Gateway host** runs the bash tool and provider connections by default.
+- **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.clawdbot.com/remote) · [Nodes](https://docs.clawdbot.com/nodes) · [Security](https://docs.clawdbot.com/security)
+
+## macOS permissions via the Gateway protocol
+
+The macOS app can run in **node mode** and advertises its capabilities + permission map over the Gateway WebSocket (`node.list` / `node.describe`). Clients can then execute local actions via `node.invoke`:
+
+- `system.run` runs a local command and returns stdout/stderr/exit code; set `needsScreenRecording: true` to require screen-recording permission (otherwise you’ll get `PERMISSION_MISSING`).
+- `system.notify` posts a user notification and fails if notifications are denied.
+- `canvas.*`, `camera.*`, `screen.record`, and `location.get` are also routed via `node.invoke` and follow TCC permission status.
+
+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.clawdbot.com/nodes) · [macOS app](https://docs.clawdbot.com/macos) · [Gateway protocol](https://docs.clawdbot.com/architecture)
+
+## Agent to Agent (sessions_* tools)
+
+- Use these to coordinate work across sessions without jumping between chat surfaces.
+- `sessions_list` — discover active sessions (agents) and their metadata.
+- `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.clawdbot.com/session-tool)
+
+## Skills registry (ClawdHub)
+
+ClawdHub is a minimal skill registry. With ClawdHub enabled, the agent can search for skills automatically and pull in new ones as needed.
+
+https://ClawdHub.com
+
 ## Chat commands
 
-Send these in WhatsApp/Telegram/WebChat (group commands are owner-only):
+Send these in WhatsApp/Telegram/Slack/WebChat (group commands are owner-only):
 
 - `/status` — health + session info (group shows activation mode)
 - `/new` or `/reset` — reset the session
+- `/compact` — compact session context (summary)
 - `/think <level>` — off|minimal|low|medium|high
 - `/verbose on|off`
 - `/restart` — restart the gateway (owner-only in groups)
 - `/activation mention|always` — group activation toggle (groups only)
 
-## Architecture
+## macOS app (optional)
 
-### TypeScript Gateway (src/gateway/server.ts)
-- **Single HTTP+WS server** on `ws://127.0.0.1:18789` (bind policy: loopback/lan/tailnet/auto). The first frame must be `connect`; AJV validates frames against TypeBox schemas (`src/gateway/protocol`).
-- **Single source of truth** for sessions, providers, cron, voice wake, and presence. Methods cover `send`, `agent`, `chat.*`, `sessions.*`, `config.*`, `cron.*`, `voicewake.*`, `node.*`, `system-*`, `wake`.
-- **Events + snapshot**: handshake returns a snapshot (presence/health) and declares event types; runtime events include `agent`, `chat`, `presence`, `tick`, `health`, `heartbeat`, `cron`, `node.pair.*`, `voicewake.changed`, `shutdown`.
-- **Idempotency & safety**: `send`/`agent`/`chat.send` require idempotency keys with a TTL cache (5 min, cap 1000) to avoid double‑sends on reconnects; payload sizes are capped per connection.
-- **Bridge for nodes**: optional TCP bridge (`src/infra/bridge/server.ts`) is newline‑delimited JSON frames (`hello`, pairing, RPC, `invoke`); node connect/disconnect is surfaced into presence.
-- **Control UI + Canvas Host**: HTTP serves Control UI assets (default `/`, optional base path) and can host a live‑reload Canvas host for nodes (`src/canvas-host/server.ts`), injecting the A2UI postMessage bridge.
+The Gateway alone delivers a great experience. All apps are optional and add extra features.
 
-### iOS app (apps/ios)
-- **Discovery + pairing**: Bonjour discovery via `BridgeDiscoveryModel` (NWBrowser). `BridgeConnectionController` auto‑connects using Keychain token or allows manual host/port.
-- **Node runtime**: `BridgeSession` (actor) maintains the `NWConnection`, hello handshake, ping/pong, RPC requests, and `invoke` callbacks.
-- **Capabilities + commands**: advertises `canvas`, `screen`, `camera`, `voiceWake` (settings‑driven) and executes `canvas.*`, `canvas.a2ui.*`, `camera.*`, `screen.record` (`NodeAppModel.handleInvoke`).
-- **Canvas**: `WKWebView` with bundled Canvas scaffold + A2UI, JS eval, snapshot capture, and `clawdbot://` deep‑link interception (`ScreenController`).
-- **Voice + deep links**: voice wake sends `voice.transcript` events; `clawdbot://agent` links emit `agent.request`. Voice wake triggers sync via `voicewake.get` + `voicewake.changed`.
+If you plan to build/run companion apps, initialize submodules first:
 
-## Companion apps
+```bash
+git submodule update --init --recursive
+./scripts/restart-mac.sh
+```
 
-The **macOS app is critical**: it runs the menu‑bar control plane, owns local permissions (TCC), hosts Voice Wake, exposes WebChat/debug tools, and coordinates local/remote gateway mode. Most “assistant” UX lives here.
-
-### macOS (Clawdbot.app)
+### macOS (Clawdbot.app) (optional)
 
 - Menu bar control for the Gateway and health.
 - Voice Wake + push-to-talk overlay.
 - WebChat + debug tools.
 - Remote gateway control over SSH.
 
-Build/run: `./scripts/restart-mac.sh` (packages + launches).
+Note: signed builds required for macOS permissions to stick across rebuilds (see `docs/mac/permissions.md`).
 
-### iOS node (internal)
+### iOS node (optional)
 
 - Pairs as a node via the Bridge.
 - Voice trigger forwarding + Canvas surface.
 - Controlled via `clawdbot nodes …`.
 
-Runbook: `docs/ios/connect.md`.
+Runbook: [iOS connect](https://docs.clawdbot.com/ios).
 
-### Android node (internal)
+### Android node (optional)
 
 - Pairs via the same Bridge + pairing flow as iOS.
 - Exposes Canvas, Camera, and Screen capture commands.
-- Runbook: `docs/android/connect.md`.
+- Runbook: [Android connect](https://docs.clawdbot.com/android).
 
 ## Agent workspace + skills
 
@@ -204,22 +257,32 @@ Runbook: `docs/ios/connect.md`.
 
 ## Configuration
 
-Minimal `~/.clawdbot/clawdbot.json`:
+Minimal `~/.clawdbot/clawdbot.json` (model + defaults):
 
 ```json5
 {
-  whatsapp: {
-    allowFrom: ["+1234567890"]
+  agent: {
+    model: "anthropic/claude-opus-4-5"
   }
 }
 ```
 
-### WhatsApp
+[Full configuration reference (all keys + examples).](https://docs.clawdbot.com/configuration)
+
+## 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`; denylist `browser`, `canvas`, `nodes`, `cron`, `discord`, `gateway`.
+
+Details: [Security guide](https://docs.clawdbot.com/security) · [Docker + sandboxing](https://docs.clawdbot.com/docker) · [Sandbox config](https://docs.clawdbot.com/configuration)
+
+### [WhatsApp](https://docs.clawdbot.com/whatsapp)
 
 - Link the device: `pnpm clawdbot login` (stores creds in `~/.clawdbot/credentials`).
 - Allowlist who can talk to the assistant via `whatsapp.allowFrom`.
 
-### Telegram
+### [Telegram](https://docs.clawdbot.com/telegram)
 
 - Set `TELEGRAM_BOT_TOKEN` or `telegram.botToken` (env wins).
 - Optional: set `telegram.groups` (with `telegram.groups."*".requireMention`), `telegram.allowFrom`, or `telegram.webhookUrl` as needed.
@@ -232,7 +295,11 @@ Minimal `~/.clawdbot/clawdbot.json`:
 }
 ```
 
-### Discord
+### [Slack](https://docs.clawdbot.com/slack)
+
+- Set `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` (or `slack.botToken` + `slack.appToken`).
+
+### [Discord](https://docs.clawdbot.com/discord)
 
 - Set `DISCORD_BOT_TOKEN` or `discord.token` (env wins).
 - Optional: set `discord.slashCommand`, `discord.dm.allowFrom`, `discord.guilds`, or `discord.mediaMaxMb` as needed.
@@ -245,6 +312,18 @@ Minimal `~/.clawdbot/clawdbot.json`:
 }
 ```
 
+### [Signal](https://docs.clawdbot.com/signal)
+
+- Requires `signal-cli` and a `signal` config section.
+
+### [iMessage](https://docs.clawdbot.com/imessage)
+
+- macOS only; Messages must be signed in.
+
+### [WebChat](https://docs.clawdbot.com/webchat)
+
+- Uses the Gateway WebSocket; no separate WebChat port/config.
+
 Browser control (optional):
 
 ```json5
@@ -259,39 +338,97 @@ Browser control (optional):
 
 ## Docs
 
-- [`docs/index.md`](docs/index.md) (overview)
-- [`docs/configuration.md`](docs/configuration.md)
-- [`docs/group-messages.md`](docs/group-messages.md)
-- [`docs/gateway.md`](docs/gateway.md)
-- [`docs/web.md`](docs/web.md)
-- [`docs/discovery.md`](docs/discovery.md)
-- [`docs/agent.md`](docs/agent.md)
-- [`docs/discord.md`](docs/discord.md)
-- [`docs/wizard.md`](docs/wizard.md)
-- Webhooks + external triggers: [`docs/webhook.md`](docs/webhook.md)
-- Gmail hooks (email → wake): [`docs/gmail-pubsub.md`](docs/gmail-pubsub.md)
+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.clawdbot.com/)
+- [Read the architecture overview for the gateway + protocol model.](https://docs.clawdbot.com/architecture)
+- [Use the full configuration reference when you need every key and example.](https://docs.clawdbot.com/configuration)
+- [Run the Gateway by the book with the operational runbook.](https://docs.clawdbot.com/gateway)
+- [Learn how the Control UI/Web surfaces work and how to expose them safely.](https://docs.clawdbot.com/web)
+- [Understand remote access over SSH tunnels or tailnets.](https://docs.clawdbot.com/remote)
+- [Follow the onboarding wizard flow for a guided setup.](https://docs.clawdbot.com/wizard)
+- [Wire external triggers via the webhook surface.](https://docs.clawdbot.com/webhook)
+- [Set up Gmail Pub/Sub triggers.](https://docs.clawdbot.com/gmail-pubsub)
+- [Learn the macOS menu bar companion details.](https://docs.clawdbot.com/mac/menu-bar)
+- [Platform guides: Windows](https://docs.clawdbot.com/windows), [Linux](https://docs.clawdbot.com/linux), [macOS](https://docs.clawdbot.com/macos), [iOS](https://docs.clawdbot.com/ios), [Android](https://docs.clawdbot.com/android)
+- [Debug common failures with the troubleshooting guide.](https://docs.clawdbot.com/troubleshooting)
+- [Review security guidance before exposing anything.](https://docs.clawdbot.com/security)
+
+## Advanced docs (discovery + control)
+
+- [Discovery + transports](https://docs.clawdbot.com/discovery)
+- [Bonjour/mDNS](https://docs.clawdbot.com/bonjour)
+- [Gateway pairing](https://docs.clawdbot.com/gateway/pairing)
+- [Remote gateway README](https://docs.clawdbot.com/remote-gateway-readme)
+- [Control UI](https://docs.clawdbot.com/control-ui)
+- [Dashboard](https://docs.clawdbot.com/dashboard)
+
+## Operations & troubleshooting
+
+- [Health checks](https://docs.clawdbot.com/health)
+- [Gateway lock](https://docs.clawdbot.com/gateway-lock)
+- [Background process](https://docs.clawdbot.com/background-process)
+- [Browser troubleshooting (Linux)](https://docs.clawdbot.com/browser-linux-troubleshooting)
+- [Logging](https://docs.clawdbot.com/logging)
+
+## Deep dives
+
+- [Agent loop](https://docs.clawdbot.com/agent-loop)
+- [Presence](https://docs.clawdbot.com/presence)
+- [TypeBox schemas](https://docs.clawdbot.com/typebox)
+- [RPC adapters](https://docs.clawdbot.com/rpc)
+- [Queue](https://docs.clawdbot.com/queue)
+
+## Workspace & skills
+
+- [Skills config](https://docs.clawdbot.com/skills-config)
+- [Default AGENTS](https://docs.clawdbot.com/AGENTS.default)
+- [Templates: AGENTS](https://docs.clawdbot.com/templates/AGENTS)
+- [Templates: BOOTSTRAP](https://docs.clawdbot.com/templates/BOOTSTRAP)
+- [Templates: IDENTITY](https://docs.clawdbot.com/templates/IDENTITY)
+- [Templates: SOUL](https://docs.clawdbot.com/templates/SOUL)
+- [Templates: TOOLS](https://docs.clawdbot.com/templates/TOOLS)
+- [Templates: USER](https://docs.clawdbot.com/templates/USER)
+
+## Platform internals
+
+- [macOS dev setup](https://docs.clawdbot.com/mac/dev-setup)
+- [macOS menu bar](https://docs.clawdbot.com/mac/menu-bar)
+- [macOS voice wake](https://docs.clawdbot.com/mac/voicewake)
+- [iOS node](https://docs.clawdbot.com/ios)
+- [Android node](https://docs.clawdbot.com/android)
+- [Windows app](https://docs.clawdbot.com/windows)
+- [Linux app](https://docs.clawdbot.com/linux)
 
 ## Email hooks (Gmail)
 
+[Gmail Pub/Sub wiring (gcloud + gogcli), hook tokens, and auto-watch behavior are documented here.](https://docs.clawdbot.com/gmail-pubsub)
+
+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.
+
 ```bash
 clawdbot hooks gmail setup --account you@gmail.com
 clawdbot hooks gmail run
 ```
-- [`docs/security.md`](docs/security.md)
-- [`docs/troubleshooting.md`](docs/troubleshooting.md)
-- [`docs/ios/connect.md`](docs/ios/connect.md)
-- [`docs/clawdbot-mac.md`](docs/clawdbot-mac.md)
-
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, maintainers, and how to submit PRs.
-
-AI/vibe-coded PRs welcome! 🤖
 
 ## Clawd
 
-Clawdbot was built for **Clawd**, a space lobster AI assistant.
+Clawdbot was built for **Clawd**, a space lobster AI assistant. 🦞  
+by Peter Steinberger and the community.
 
 - https://clawd.me
 - https://soul.md
 - https://steipete.me
+
+## Community
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, maintainers, and how to submit PRs.  
+AI/vibe-coded PRs welcome! 🤖
+
+Thanks to all clawtributors:
+
+<p align="left">
+  <a href="https://github.com/steipete"><img src="https://avatars.githubusercontent.com/u/58493?v=4&s=48" width="48" height="48" alt="steipete" title="steipete"/></a> <a href="https://github.com/thewilloftheshadow"><img src="https://avatars.githubusercontent.com/u/35580099?v=4&s=48" width="48" height="48" alt="thewilloftheshadow" title="thewilloftheshadow"/></a> <a href="https://github.com/mcinteerj"><img src="https://avatars.githubusercontent.com/u/3613653?v=4&s=48" width="48" height="48" alt="mcinteerj" title="mcinteerj"/></a> <a href="https://github.com/joshp123"><img src="https://avatars.githubusercontent.com/u/1497361?v=4&s=48" width="48" height="48" alt="joshp123" title="joshp123"/></a> <a href="https://github.com/joaohlisboa"><img src="https://avatars.githubusercontent.com/u/8200873?v=4&s=48" width="48" height="48" alt="joaohlisboa" title="joaohlisboa"/></a> <a href="https://github.com/petter-b"><img src="https://avatars.githubusercontent.com/u/62076402?v=4&s=48" width="48" height="48" alt="petter-b" title="petter-b"/></a> <a href="https://github.com/mukhtharcm"><img src="https://avatars.githubusercontent.com/u/56378562?v=4&s=48" width="48" height="48" alt="mukhtharcm" title="mukhtharcm"/></a> <a href="https://github.com/dan-dr"><img src="https://avatars.githubusercontent.com/u/6669808?v=4&s=48" width="48" height="48" alt="dan-dr" title="dan-dr"/></a> <a href="https://github.com/Nachx639"><img src="https://avatars.githubusercontent.com/u/71144023?v=4&s=48" width="48" height="48" alt="Nachx639" title="Nachx639"/></a> <a href="https://github.com/jeffersonwarrior"><img src="https://avatars.githubusercontent.com/u/89030989?v=4&s=48" width="48" height="48" alt="jeffersonwarrior" title="jeffersonwarrior"/></a>
+  <a href="https://github.com/mbelinky"><img src="https://avatars.githubusercontent.com/u/132747814?v=4&s=48" width="48" height="48" alt="mbelinky" title="mbelinky"/></a> <a href="https://github.com/julianengel"><img src="https://avatars.githubusercontent.com/u/10634231?v=4&s=48" width="48" height="48" alt="julianengel" title="julianengel"/></a> <a href="https://github.com/CashWilliams"><img src="https://avatars.githubusercontent.com/u/613573?v=4&s=48" width="48" height="48" alt="CashWilliams" title="CashWilliams"/></a> <a href="https://github.com/omniwired"><img src="https://avatars.githubusercontent.com/u/322761?v=4&s=48" width="48" height="48" alt="omniwired" title="omniwired"/></a> <a href="https://github.com/jverdi"><img src="https://avatars.githubusercontent.com/u/345050?v=4&s=48" width="48" height="48" alt="jverdi" title="jverdi"/></a> <a href="https://github.com/Syhids"><img src="https://avatars.githubusercontent.com/u/671202?v=4&s=48" width="48" height="48" alt="Syhids" title="Syhids"/></a> <a href="https://github.com/meaningfool"><img src="https://avatars.githubusercontent.com/u/2862331?v=4&s=48" width="48" height="48" alt="meaningfool" title="meaningfool"/></a> <a href="https://github.com/rafaelreis-r"><img src="https://avatars.githubusercontent.com/u/57492577?v=4&s=48" width="48" height="48" alt="rafaelreis-r" title="rafaelreis-r"/></a> <a href="https://github.com/wstock"><img src="https://avatars.githubusercontent.com/u/1394687?v=4&s=48" width="48" height="48" alt="wstock" title="wstock"/></a> <a href="https://github.com/vsabavat"><img src="https://avatars.githubusercontent.com/u/50385532?v=4&s=48" width="48" height="48" alt="vsabavat" title="vsabavat"/></a>
+  <a href="https://github.com/scald"><img src="https://avatars.githubusercontent.com/u/1215913?v=4&s=48" width="48" height="48" alt="scald" title="scald"/></a> <a href="https://github.com/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>
+</p>

appcast.xml

@@ -1,212 +1,55 @@
 <?xml version="1.0" standalone="yes"?>
 <rss xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle" version="2.0">
     <channel>
-        <title>Clawdbot</title>
+        <title>Clawdis</title>
         <item>
-            <title>2.0.0-beta5</title>
-            <pubDate>Sat, 03 Jan 2026 07:15:16 +0100</pubDate>
+            <title>2026.1.5-3</title>
+            <pubDate>Mon, 05 Jan 2026 04:30:46 +0100</pubDate>
             <link>https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml</link>
-            <sparkle:version>2765</sparkle:version>
-            <sparkle:shortVersionString>2.0.0-beta5</sparkle:shortVersionString>
+            <sparkle:version>3095</sparkle:version>
+            <sparkle:shortVersionString>2026.1.5-3</sparkle:shortVersionString>
             <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
-            <description><![CDATA[<h2>Clawdbot 2.0.0-beta5</h2>
-<h3>Fixed</h3>
-<ul>
-<li>Media: preserve GIF animation when uploading to Discord/other providers (skip JPEG optimization for image/gif).</li>
-<li>Agent runtime: update pi-mono dependencies to 0.31.1 (agent-core split).</li>
-<li>Dependencies: bump to latest compatible versions (TypeBox, grammY, Zod, Rolldown, oxlint-tsgolint).</li>
-<li>Tests: cover read tool image metadata + text output.</li>
-<li>Tests: add queue mode coverage (collect/followup + directive parsing).</li>
-</ul>
-<h3>Breaking</h3>
-<ul>
-<li>Skills config schema moved under <code>skills.*</code>:</li>
-</ul>
-  - <code>skillsLoad.extraDirs</code> → <code>skills.load.extraDirs</code>
-  - <code>skillsInstall.*</code> → <code>skills.install.*</code>
-  - per-skill config map moved to <code>skills.entries</code> (e.g. <code>skills.peekaboo.enabled</code> → <code>skills.entries.peekaboo.enabled</code>)
-  - new optional bundled allowlist: <code>skills.allowBundled</code> (only affects bundled skills)
-<ul>
-<li>Sessions: group keys now use <code>surface:group:<id></code> / <code>surface:channel:<id></code>; legacy <code>group:*</code> keys migrate on next message; <code>groupdm</code> keys are no longer recognized.</li>
-<li>Discord: remove legacy <code>discord.allowFrom</code>, <code>discord.guildAllowFrom</code>, and <code>discord.requireMention</code>; use <code>discord.dm</code> + <code>discord.guilds</code>.</li>
-<li>Providers: Discord/Telegram no longer auto-start from env tokens alone; add <code>discord: { enabled: true }</code> / <code>telegram: { enabled: true }</code> to your config when using <code>DISCORD_BOT_TOKEN</code> / <code>TELEGRAM_BOT_TOKEN</code>.</li>
-<li>Config: remove <code>routing.allowFrom</code>; use <code>whatsapp.allowFrom</code> instead (run <code>clawdbot doctor</code> to migrate).</li>
-<li>Config: remove <code>routing.groupChat.requireMention</code> + <code>telegram.requireMention</code>; use <code>whatsapp.groups</code>, <code>imessage.groups</code>, and <code>telegram.groups</code> defaults instead (run <code>clawdbot doctor</code> to migrate).</li>
-</ul>
-<h3>Features</h3>
-<ul>
-<li>Discord: expand <code>discord</code> tool actions (reactions, stickers, polls, threads, search, moderation gates) (#115) — thanks @thewilloftheshadow.</li>
-<li>Discord/Telegram: add reply tags (<code>[[reply_to_current]]</code>, <code>[[reply_to:<id>]]</code>) with per-provider <code>replyToMode</code> (off|first|all) for native threaded replies.</li>
-<li>Talk mode: continuous speech conversations (macOS/iOS/Android) with ElevenLabs TTS, reply directives, and optional interrupt-on-speech.</li>
-<li>Auto-reply: expand queue modes (steer/followup/collect/steer-backlog) with debounce/cap/drop options and followup backlog handling.</li>
-<li>UI: add optional <code>ui.seamColor</code> accent to tint the Talk Mode side bubble (macOS/iOS/Android).</li>
-<li>Nix mode: opt-in declarative config + read-only settings UI when <code>CLAWDBOT_NIX_MODE=1</code> (thanks @joshp123 for the persistence — earned my trust; I'll merge these going forward).</li>
-<li>CLI: add Google Antigravity OAuth auth option for Claude Opus 4.5/Gemini 3 (#88) — thanks @mukhtharcm.</li>
-<li>Agent runtime: accept legacy <code>Z_AI_API_KEY</code> for Z.AI provider auth (maps to <code>ZAI_API_KEY</code>).</li>
-<li>Groups: add per-group mention gating defaults/overrides for Telegram/WhatsApp/iMessage via <code>*.groups</code> with <code>"*"</code> defaults; Discord now supports <code>discord.guilds."*"</code> as a default.</li>
-<li>Discord: add user-installed slash command handling with per-user sessions and auto-registration (#94) — thanks @thewilloftheshadow.</li>
-<li>Discord: add DM enable/allowlist plus guild channel/user/guild allowlists with id/name matching.</li>
-<li>Signal: add <code>signal-cli</code> JSON-RPC support for send/receive via the Signal provider.</li>
-<li>iMessage: add imsg JSON-RPC integration (stdio), chat_id routing, and group chat support.</li>
-<li>Chat UI: add recent-session dropdown switcher (main first) in macOS/iOS/Android + Control UI.</li>
-<li>UI: add Discord/Signal/iMessage connection panels in macOS + Control UI (thanks @thewilloftheshadow).</li>
-<li>Discord: allow agent-triggered reactions via <code>clawdbot_discord</code> when enabled, and surface message ids in context.</li>
-<li>Discord: revamp guild routing config with per-guild/channel rules and slugged display names; add optional group DM support (default off).</li>
-<li>Discord: remove legacy guild/channel ignore lists in favor of per-guild allowlists (and proposed per-guild ignore lists).</li>
-<li>Skills: add Trello skill for board/list/card management (thanks @clawd).</li>
-<li>Docker: add containerized gateway/CLI setup via Dockerfile, compose, and setup script (thanks @dan-dr).</li>
-<li>Tests: add a Z.AI live test gate for smoke validation when keys are present.</li>
-<li>macOS Debug: add app log verbosity and rolling file log toggle for swift-log-backed app logs.</li>
-<li>CLI: add onboarding wizard (gateway + workspace + skills) with daemon installers and Anthropic/Minimax setup paths.</li>
-<li>CLI: add ASCII banner header to wizard entry points.</li>
-<li>CLI: add <code>configure</code>, <code>doctor</code>, and <code>update</code> wizards for ongoing setup, health checks, and modernization.</li>
-<li>CLI: add Signal CLI auto-install from GitHub releases in the wizard and persist wizard run metadata in config.</li>
-<li>CLI: add remote gateway client config (gateway.remote.*) with Bonjour-assisted discovery.</li>
-<li>CLI: enhance <code>clawdbot tui</code> with model/session pickers, tool cards, and slash commands (local or remote).</li>
-<li>Gateway: allow <code>sessions.patch</code> to set per-session model overrides (used by the TUI <code>/model</code> flow).</li>
-<li>Skills: allow <code>bun</code> as a node manager for skill installs.</li>
-<li>Skills: add <code>things-mac</code> (Things 3 CLI) for read/search plus add/update via URL scheme.</li>
-<li>Skills: add Apple Notes + Reminders skills via memo CLI (thanks @tylerwince).</li>
-<li>Tests: add a Docker-based onboarding E2E harness.</li>
-<li>Tests: harden wizard E2E flows for reset, providers, skills, and remote non-interactive runs.</li>
-<li>Browser tools: add remote CDP URL support, Linux launcher options (<code>executablePath</code>, <code>noSandbox</code>), and surface <code>cdpUrl</code> in status.</li>
-<li>Skills: add tmux-first coding-agent skill + <code>requires.anyBins</code> gate for multi-CLI setup (thanks @sreekaransrinath).</li>
-</ul>
+            <description><![CDATA[<h2>Clawdbot 2026.1.5-3</h2>
 <h3>Fixes</h3>
 <ul>
-<li>Gog calendar: format date ranges as RFC 3339 with timezone to satisfy Google Calendar API (thanks @jayhickey).</li>
-<li>macOS onboarding: add scrollable page gutter for overflowing content (#105) — thanks @thewilloftheshadow.</li>
-<li>Chat UI: keep the chat scrolled to the latest message after switching sessions.</li>
-<li>Chat UI: show rich session display names in Web Chat + SwiftUI + Android.</li>
-<li>Auto-reply: stream completed reply blocks as soon as they finish (configurable default + break); skip empty tool-only blocks unless verbose.</li>
-<li>Discord: avoid duplicate sends when block streaming is enabled (race with typing hook).</li>
-<li>Providers: make outbound text chunk limits configurable via <code>*.textChunkLimit</code> (defaults remain 4000/Discord 2000).</li>
-<li>CLI onboarding: persist gateway token in config so local CLI auth works; recommend auth Off unless you need multi-machine access.</li>
-<li>Control UI: accept a <code>?token=</code> URL param to auto-fill Gateway auth; onboarding now opens the dashboard with token auth when configured.</li>
-<li>Agent prompt: remove hardcoded user name in system prompt example.</li>
-<li>Chat UI: add extra top padding before the first message bubble in Web Chat (macOS/iOS/Android).</li>
-<li>Control UI: refine Web Chat session selector styling (chevron spacing + background).</li>
-<li>WebChat: stream live updates for sessions even when runs start outside the chat UI.</li>
-<li>Gateway CLI: read <code>CLAWDBOT_GATEWAY_PASSWORD</code> from environment in <code>callGateway()</code> — allows <code>doctor</code>/<code>health</code> commands to auth without explicit <code>--password</code> flag.</li>
-<li>Gateway: add password auth support for remote gateway connections (thanks @jeffersonwarrior).</li>
-<li>Auto-reply: strip stray leading/trailing <code>HEARTBEAT_OK</code> from normal replies; drop short (≤ 30 chars) heartbeat acks.</li>
-<li>WhatsApp auto-reply: default to self-only when no config is present.</li>
-<li>Logging: trim provider prefix duplication in Discord/Signal/Telegram runtime log lines.</li>
-<li>Logging/Signal: treat signal-cli "Failed …" lines as errors in gateway logs.</li>
-<li>Discord: include recent guild context when replying to mentions and add <code>discord.historyLimit</code> to tune how many messages are captured.</li>
-<li>Discord: include author tag + id in group context <code>[from:]</code> lines for ping-ready replies (thanks @thewilloftheshadow).</li>
-<li>Discord: include replied-to message context when a Discord message references another message (thanks @thewilloftheshadow).</li>
-<li>Discord: preserve newlines when stripping reply tags from agent output.</li>
-<li>Gateway: fix TypeScript build by aligning hook mapping <code>channel</code> types and removing a dead Group DM branch in Discord monitor.</li>
-<li>Skills: switch imsg installer to brew tap formula.</li>
-<li>Skills: gate macOS-only skills by OS and surface block reasons in the Skills UI.</li>
-<li>Onboarding: show skill descriptions in the macOS setup flow and surface clearer Gateway/skills error messages.</li>
-<li>Onboarding: auto-verify Claude OAuth tokens, show “verified” when detected working, and avoid re-auth prompts unless verification fails.</li>
-<li>CLI onboarding: include exit code + a useful one-line summary when skill dependency installs fail.</li>
-<li>CLI onboarding: explain Tailscale exposure options (Off/Serve/Funnel) and colorize provider status (linked/configured/needs setup).</li>
-<li>CLI onboarding: add provider primers (WhatsApp/Telegram/Discord/Signal) incl. Discord bot token setup steps.</li>
-<li>CLI onboarding: allow skipping the “install missing skill dependencies” selection without canceling the wizard.</li>
-<li>CLI onboarding: always prompt for WhatsApp <code>whatsapp.allowFrom</code> and print (optionally open) the Control UI URL when done.</li>
-<li>CLI onboarding: detect gateway reachability and annotate Local/Remote choices (helps pick the right mode).</li>
-<li>macOS settings: colorize provider status subtitles to distinguish healthy vs degraded states.</li>
-<li>macOS: keep config writes on the main actor to satisfy Swift concurrency rules.</li>
-<li>macOS menu: show multi-line gateway error details, add an always-visible gateway row, avoid duplicate gateway status rows, suppress transient <code>cancelled</code> device refresh errors, and auto-recover the control channel on disconnect.</li>
-<li>macOS menu: show session last-used timestamps in the list and add recent-message previews in session submenus.</li>
-<li>macOS menu: tighten session row padding and time out session preview loading with cached fallback.</li>
-<li>macOS: log health refresh failures and recovery to make gateway issues easier to diagnose.</li>
-<li>macOS codesign: skip hardened runtime for ad-hoc signing and avoid empty options args (#70) — thanks @petter-b</li>
-<li>macOS codesign: include camera entitlement so permission prompts work in the menu bar app.</li>
-<li>Agent tools: bash tool supports real TTY via <code>stdinMode: "pty"</code> with node-pty, warning + fallback on load/start failure.</li>
-<li>Agent tools: map <code>camera.snap</code> JPEG payloads to <code>image/jpeg</code> to avoid MIME mismatch errors.</li>
-<li>Tests: cover <code>camera.snap</code> MIME mapping to prevent image/png vs image/jpeg mismatches.</li>
-<li>macOS camera: wait for exposure/white balance to settle before capturing a snap to avoid dark images.</li>
-<li>Camera snap: add <code>delayMs</code> parameter (default 2000ms on macOS) to improve exposure reliability.</li>
-<li>Camera: add <code>camera.list</code> and optional <code>deviceId</code> selection for snaps/clips.</li>
-<li>Tests: cover camera device selection params in CLI + agent tools.</li>
-<li>macOS packaging: move rpath config into swift build for reliability (#69) — thanks @petter-b</li>
-<li>macOS: prioritize main bundle for device resources to prevent crash (#73) — thanks @petter-b</li>
-<li>macOS remote: route settings through gateway config and avoid local config reads in remote mode.</li>
-<li>Telegram: align token resolution for cron/agent/CLI sends (env/config/tokenFile) to prevent isolated delivery failures (#76).</li>
-<li>Telegram: honor per-group mention gating defaults/overrides via <code>telegram.groups</code> and <code>"*"</code> defaults (thanks @joshp123).</li>
-<li>Chat UI: clear composer input immediately and allow clear while editing to prevent duplicate sends (#72) — thanks @hrdwdmrbl</li>
-<li>Restart: use systemd on Linux (and report actual restart method) instead of always launchctl.</li>
-<li>Gateway relay: detect Bun binaries via execPath to resolve packaged assets on macOS.</li>
-<li>Cron: prevent <code>every</code> schedules without an anchor from firing in a tight loop (thanks @jamesgroat).</li>
-<li>Docs: add manual OAuth setup for remote/headless deployments (#67) — thanks @wstock</li>
-<li>Docs/agent tools: clarify that browser <code>wait</code> should be avoided by default and used only in exceptional cases.</li>
-<li>Docs: clarify self-chat mode and group mention gating config (#111) — thanks @rafaelreis-r.</li>
-<li>Browser tools: <code>upload</code> supports auto-click refs, direct <code>inputRef</code>/<code>element</code> file inputs, and emits input/change after <code>setFiles</code> so JS-heavy sites pick up attachments.</li>
-<li>Browser tools: harden CDP readiness (HTTP + WS), retry CDP connects, and auto-restart the clawd browser when the socket handshake stalls.</li>
-<li>Browser CLI: add <code>clawdbot browser reset-profile</code> to move the clawd profile to Trash when it gets wedged.</li>
-<li>Signal: fix daemon startup race (wait for <code>/api/v1/check</code>) and normalize JSON-RPC <code>version</code> probe parsing.</li>
-<li>Docs/Signal: clarify bot-number vs personal-account setup (self-chat loop protection) and add a quickstart config snippet.</li>
-<li>Docs: refresh the CLI wizard guide and highlight onboarding in the README.</li>
-<li>CLI: tighten onboarding prompt typing to keep bun builds green.</li>
-<li>macOS: Voice Wake now fully tears down the Speech pipeline when disabled (cancel pending restarts, drop stale callbacks) to avoid high CPU in the background.</li>
-<li>macOS menu: add a Talk Mode action alongside the Open Dashboard/Chat/Canvas entries.</li>
-<li>macOS Debug: hide “Restart Gateway” when the app won’t start a local gateway (remote mode / attach-only).</li>
-<li>macOS Debug: add an icon for the App Logging submenu.</li>
-<li>macOS Talk Mode: orb overlay refresh, ElevenLabs request logging, API key status in settings, and auto-select first voice when none is configured.</li>
-<li>macOS Talk Mode: add hard timeout around ElevenLabs TTS synthesis to avoid getting stuck “speaking” forever on hung requests.</li>
-<li>macOS Talk Mode: avoid stuck playback when the audio player never starts (fail-fast + watchdog).</li>
-<li>macOS Talk Mode: fix audio stop ordering so disabling Talk Mode always stops in-flight playback.</li>
-<li>macOS Talk Mode: throttle audio-level updates (avoid per-buffer task creation) to reduce CPU/task churn.</li>
-<li>macOS Talk Mode: increase overlay window size so wave rings don’t clip; close button is hover-only and closer to the orb.</li>
-<li>WebChat: preserve chat run ordering per session so concurrent runs don’t strand the typing indicator.</li>
-<li>Talk Mode: fall back to system TTS when ElevenLabs is unavailable, returns non-audio, or playback fails (macOS/iOS/Android).</li>
-<li>Talk Mode: stream PCM on macOS/iOS for lower latency (incremental playback); Android continues MP3 streaming.</li>
-<li>Talk Mode: validate ElevenLabs v3 stability and latency tier directives before sending requests.</li>
-<li>iOS/Android Talk Mode: auto-select the first ElevenLabs voice when none is configured.</li>
-<li>ElevenLabs: add retry/backoff for 429/5xx and include content-type in errors for debugging.</li>
-<li>Talk Mode: align to the gateway’s main session key and fall back to history polling when chat events drop (prevents stuck “thinking” / missing messages).</li>
-<li>Talk Mode: treat history timestamps as seconds or milliseconds to avoid stale assistant picks (macOS/iOS/Android).</li>
-<li>Chat UI: clear streaming/tool bubbles when external runs finish, preventing duplicate assistant bubbles.</li>
-<li>Chat UI: user bubbles use <code>ui.seamColor</code> (fallback to a calmer default blue).</li>
-<li>Android Chat UI: use <code>onPrimary</code> for user bubble text to preserve contrast (thanks @Syhids).</li>
-<li>Control UI: sync sidebar navigation with the URL for deep-linking, and auto-scroll chat to the latest message.</li>
-<li>Control UI: disable Web Chat + Talk when no iOS/Android node is connected; refreshed Web Chat styling and keyboard send.</li>
-<li>Control UI: keep chat pinned to the latest message while typing/sending and restore drafts on send failures.</li>
-<li>Control UI: soften chat bubble text opacity for calmer readability.</li>
-<li>macOS Web Chat: improve empty/error states, focus message field on open, keep pill/send inside the input field, and make the composer pill edge-to-edge with square top corners.</li>
-<li>macOS: bundle Control UI assets into the app relay so the packaged app can serve them (thanks @mbelinky).</li>
-<li>Talk Mode: wait for chat history to surface the assistant reply before starting TTS (macOS/iOS/Android).</li>
-<li>iOS Talk Mode: fix chat completion wait to time out even if no events arrive (prevents “Thinking…” hangs).</li>
-<li>iOS Talk Mode: keep recognition running during playback to support interrupt-on-speech.</li>
-<li>iOS Talk Mode: preserve directive voice/model overrides across config reloads and add ElevenLabs request timeouts.</li>
-<li>iOS/Android Talk Mode: explicitly <code>chat.subscribe</code> when Talk Mode is active, so completion events arrive even if the Chat UI isn’t open.</li>
-<li>Chat UI: refresh history when another client finishes a run in the same session, so Talk Mode + Voice Wake transcripts appear consistently.</li>
-<li>Gateway: <code>voice.transcript</code> now also maps agent bus output to <code>chat</code> events, ensuring chat UIs refresh for voice-triggered runs.</li>
-<li>Gateway: auto-migrate legacy config on startup (non-Nix); Nix mode hard-fails with a clear error when legacy keys are present.</li>
-<li>iOS/Android: show a centered Talk Mode orb overlay while Talk Mode is enabled.</li>
-<li>Gateway config: inject <code>talk.apiKey</code> from <code>ELEVENLABS_API_KEY</code>/shell profile so nodes can fetch it on demand.</li>
-<li>Canvas A2UI: tag requests with <code>platform=android|ios|macos</code> and boost Android canvas background contrast.</li>
-<li>iOS/Android nodes: enable scrolling for loaded web pages in the Canvas WebView (default scaffold stays touch-first).</li>
-<li>macOS menu: device list now uses <code>node.list</code> (devices only; no agent/tool presence entries).</li>
-<li>macOS menu: device list now shows connected nodes only.</li>
-<li>macOS menu: device rows now pack platform/version on the first line, and command lists wrap in submenus.</li>
-<li>macOS menu: split device platform/version across first and second rows for better fit.</li>
-<li>macOS Canvas: show remote control status in the debug overlay and log A2UI auto-nav decisions.</li>
-<li>Canvas A2UI: polish the debug status HUD styling.</li>
-<li>iOS node: fix ReplayKit screen recording crash caused by queue isolation assertions during capture.</li>
-<li>iOS Talk Mode: avoid audio tap queue assertions when starting recognition.</li>
-<li>macOS: use $HOME/Library/pnpm for SSH PATH exports (thanks @mbelinky).</li>
-<li>macOS remote: harden SSH tunnel recovery/logging, honor <code>gateway.remote.url</code> port when forwarding, clarify gateway disconnect status, and add Debug menu tunnel reset.</li>
-<li>iOS/Android nodes: bridge auto-connect refreshes stale tokens and settings now show richer bridge/device details.</li>
-<li>macOS: bundle device model resources to prevent Instances crashes (thanks @mbelinky).</li>
-<li>iOS/Android nodes: status pill now surfaces camera activity instead of overlay toasts.</li>
-<li>iOS/Android/macOS nodes: camera snaps recompress to keep base64 payloads under 5 MB.</li>
-<li>iOS/Android nodes: status pill now surfaces pairing, screen recording, voice wake, and foreground-required states.</li>
-<li>iOS/Android nodes: avoid duplicating “Gateway reconnecting…” when the bridge is already connecting.</li>
-<li>iOS/Android nodes: Talk Mode now lives on a side bubble (with an iOS toggle to hide it), and Android settings no longer show the Talk Mode switch.</li>
-<li>macOS menu: top status line now shows pending node pairing approvals (incl. repairs).</li>
-<li>CLI: avoid spurious gateway close errors after successful request/response cycles.</li>
-<li>Agent runtime: clamp tool-result images to the 5MB Anthropic limit to avoid hard request rejections.</li>
-<li>Agent runtime: write v2 session headers so Pi session branching stays in the Clawdbot sessions dir.</li>
-<li>Tests: add Swift Testing coverage for camera errors and Kotest coverage for Android bridge endpoints.</li>
+<li>NPM package: include missing runtime dist folders (slack/signal/imessage/tui/wizard/control-ui/daemon) to avoid <code>ERR_MODULE_NOT_FOUND</code> in Node 25 npx installs.</li>
 </ul>
 <p><a href="https://github.com/clawdbot/clawdbot/blob/main/CHANGELOG.md">View full changelog</a></p>
 ]]></description>
-            <enclosure url="https://github.com/clawdbot/clawdbot/releases/download/v2.0.0-beta5/Clawdbot-2.0.0-beta5.zip" length="145432870" type="application/octet-stream" sparkle:edSignature="qKPcmSx2pAaIYz9NqFp0TY63KrcDlpctUHnNpRs6Q60qQqBWtQycLIhhvhxmGnHupaiEXJfspb/Ad9RgODIzAw=="/>
+            <enclosure url="https://github.com/clawdbot/clawdbot/releases/download/v2026.1.5-3/Clawdbot-2026.1.5-3.zip" length="160800596" type="application/octet-stream" sparkle:edSignature="P8U3nvIFpbGmRItT/NGPmJ/i370OMVvDHYQL/znYsLI0MrbGfXgMGEvR5A0uwW+cJevlX/hrJLiY51zo4rAMBg=="/>
+        </item>
+        <item>
+            <title>2026.1.5-3</title>
+            <pubDate>Mon, 05 Jan 2026 03:57:59 +0100</pubDate>
+            <link>https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml</link>
+            <sparkle:version>3091</sparkle:version>
+            <sparkle:shortVersionString>2026.1.5-3</sparkle:shortVersionString>
+            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+            <description><![CDATA[<h2>Clawdbot 2026.1.5-3</h2>
+<h3>Fixes</h3>
+<ul>
+<li>NPM package: include missing runtime dist folders (slack/signal/imessage/tui/wizard/control-ui/daemon) to avoid <code>ERR_MODULE_NOT_FOUND</code> in Node 25 npx installs.</li>
+</ul>
+<p><a href="https://github.com/clawdbot/clawdbot/blob/main/CHANGELOG.md">View full changelog</a></p>
+]]></description>
+            <enclosure url="https://github.com/clawdbot/clawdbot/releases/download/v2026.1.5-3/Clawdbot-2026.1.5-3.zip" length="160797048" type="application/octet-stream" sparkle:edSignature="5KYFg0SW7liwLxLJbfzd2KsAxbX06gMH0rH/W3a4V0p4N48hjz4AsSrfFLdGZSnW+6XaJjC3MN6Ynh+l7kffDQ=="/>
+        </item>
+        <item>
+            <title>2026.1.5-2</title>
+            <pubDate>Mon, 05 Jan 2026 03:51:30 +0100</pubDate>
+            <link>https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml</link>
+            <sparkle:version>3089</sparkle:version>
+            <sparkle:shortVersionString>2026.1.5-2</sparkle:shortVersionString>
+            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+            <description><![CDATA[<h2>Clawdbot 2026.1.5-2</h2>
+<h3>Fixes</h3>
+<ul>
+<li>NPM package: include <code>dist/sessions</code> so <code>clawdbot agent</code> resolves session helpers in npx installs.</li>
+<li>Node 25: avoid unsupported directory import by targeting <code>qrcode-terminal/vendor/QRCode/*.js</code> modules.</li>
+</ul>
+<p><a href="https://github.com/clawdbot/clawdbot/blob/main/CHANGELOG.md">View full changelog</a></p>
+]]></description>
+            <enclosure url="https://github.com/clawdbot/clawdbot/releases/download/v2026.1.5-2/Clawdbot-2026.1.5-2.zip" length="150250417" type="application/octet-stream" sparkle:edSignature="ntHNmwyHrv6cPk6NAKOT3AUkwdt5ZadrGU6mJK4GmVxi44uIMT3ZXluvnqK9SxXQwA0H0dXjiGMS/cg8NbgqDA=="/>
         </item>
     </channel>
 </rss>

apps/android/app/build.gradle.kts

@@ -48,6 +48,10 @@ android {
   lint {
     disable += setOf("IconLauncherShape")
   }
+
+  testOptions {
+    unitTests.isIncludeAndroidResources = true
+  }
 }
 
 kotlin {
@@ -64,7 +68,7 @@ dependencies {
   implementation("androidx.core:core-ktx:1.17.0")
   implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.10.0")
   implementation("androidx.activity:activity-compose:1.12.2")
-  implementation("androidx.webkit:webkit:1.14.0")
+  implementation("androidx.webkit:webkit:1.15.0")
 
   implementation("androidx.compose.ui:ui")
   implementation("androidx.compose.ui:ui-tooling-preview")
@@ -96,7 +100,8 @@ dependencies {
   testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.10.2")
   testImplementation("io.kotest:kotest-runner-junit5-jvm:6.0.7")
   testImplementation("io.kotest:kotest-assertions-core-jvm:6.0.7")
-  testRuntimeOnly("org.junit.vintage:junit-vintage-engine:5.13.3")
+  testImplementation("org.robolectric:robolectric:4.16")
+  testRuntimeOnly("org.junit.vintage:junit-vintage-engine:6.0.1")
 }
 
 tasks.withType<Test>().configureEach {

apps/android/app/src/main/assets/tool-display.json

@@ -12,7 +12,7 @@
       "element",
       "node",
       "nodeId",
-      "jobId",
+      "id",
       "requestId",
       "to",
       "channelId",
@@ -136,10 +136,10 @@
           "label": "add",
           "detailKeys": ["job.name", "job.id", "job.schedule", "job.cron"]
         },
-        "update": { "label": "update", "detailKeys": ["jobId"] },
-        "remove": { "label": "remove", "detailKeys": ["jobId"] },
-        "run": { "label": "run", "detailKeys": ["jobId"] },
-        "runs": { "label": "runs", "detailKeys": ["jobId"] },
+        "update": { "label": "update", "detailKeys": ["id"] },
+        "remove": { "label": "remove", "detailKeys": ["id"] },
+        "run": { "label": "run", "detailKeys": ["id"] },
+        "runs": { "label": "runs", "detailKeys": ["id"] },
         "wake": { "label": "wake", "detailKeys": ["text", "mode"] }
       }
     },

apps/android/app/src/main/java/com/clawdbot/android/NodeForegroundService.kt

@@ -98,14 +98,31 @@ class NodeForegroundService : Service() {
   }
 
   private fun buildNotification(title: String, text: String): Notification {
+    val launchIntent = Intent(this, MainActivity::class.java).apply {
+      flags = Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP
+    }
+    val launchPending =
+      PendingIntent.getActivity(
+        this,
+        1,
+        launchIntent,
+        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+      )
+
     val stopIntent = Intent(this, NodeForegroundService::class.java).setAction(ACTION_STOP)
-    val flags = PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
-    val stopPending = PendingIntent.getService(this, 2, stopIntent, flags)
+    val stopPending =
+      PendingIntent.getService(
+        this,
+        2,
+        stopIntent,
+        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+      )
 
     return NotificationCompat.Builder(this, CHANNEL_ID)
       .setSmallIcon(R.mipmap.ic_launcher)
       .setContentTitle(title)
       .setContentText(text)
+      .setContentIntent(launchPending)
       .setOngoing(true)
       .setOnlyAlertOnce(true)
       .setForegroundServiceBehavior(NotificationCompat.FOREGROUND_SERVICE_IMMEDIATE)

apps/android/app/src/main/java/com/clawdbot/android/NodeRuntime.kt

@@ -515,7 +515,6 @@ class NodeRuntime(context: Context) {
   }
 
   private fun hasBackgroundLocationPermission(): Boolean {
-    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.Q) return true
     return (
       ContextCompat.checkSelfPermission(appContext, Manifest.permission.ACCESS_BACKGROUND_LOCATION) ==
         PackageManager.PERMISSION_GRANTED

apps/android/app/src/main/java/com/clawdbot/android/node/LocationCaptureManager.kt

@@ -1,10 +1,12 @@
 package com.clawdbot.android.node
 
-import android.annotation.SuppressLint
+import android.Manifest
 import android.content.Context
+import android.content.pm.PackageManager
 import android.location.Location
 import android.location.LocationManager
 import android.os.CancellationSignal
+import androidx.core.content.ContextCompat
 import java.time.Instant
 import java.time.format.DateTimeFormatter
 import kotlinx.coroutines.Dispatchers
@@ -64,6 +66,15 @@ class LocationCaptureManager(private val context: Context) {
     providers: List<String>,
     maxAgeMs: Long?,
   ): Location? {
+    val fineOk =
+      ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_FINE_LOCATION) ==
+        PackageManager.PERMISSION_GRANTED
+    val coarseOk =
+      ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_COARSE_LOCATION) ==
+        PackageManager.PERMISSION_GRANTED
+    if (!fineOk && !coarseOk) {
+      throw IllegalStateException("LOCATION_PERMISSION_REQUIRED: grant Location permission")
+    }
     val now = System.currentTimeMillis()
     val candidates =
       providers.mapNotNull { provider -> manager.getLastKnownLocation(provider) }
@@ -72,12 +83,20 @@ class LocationCaptureManager(private val context: Context) {
     return freshest
   }
 
-  @SuppressLint("MissingPermission")
   private suspend fun requestCurrent(
     manager: LocationManager,
     providers: List<String>,
     timeoutMs: Long,
   ): Location {
+    val fineOk =
+      ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_FINE_LOCATION) ==
+        PackageManager.PERMISSION_GRANTED
+    val coarseOk =
+      ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_COARSE_LOCATION) ==
+        PackageManager.PERMISSION_GRANTED
+    if (!fineOk && !coarseOk) {
+      throw IllegalStateException("LOCATION_PERMISSION_REQUIRED: grant Location permission")
+    }
     val resolved =
       providers.firstOrNull { manager.isProviderEnabled(it) }
         ?: throw IllegalStateException("LOCATION_UNAVAILABLE: no providers available")

apps/android/app/src/main/java/com/clawdbot/android/ui/SettingsSheet.kt

@@ -133,7 +133,7 @@ fun SettingsSheet(viewModel: MainViewModel) {
 
       if (requestedMode != null) {
         viewModel.setLocationMode(requestedMode)
-        if (requestedMode == LocationMode.Always && Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+        if (requestedMode == LocationMode.Always) {
           val backgroundOk =
             ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_BACKGROUND_LOCATION) ==
               PackageManager.PERMISSION_GRANTED
@@ -191,7 +191,7 @@ fun SettingsSheet(viewModel: MainViewModel) {
         PackageManager.PERMISSION_GRANTED
     if (fineOk || coarseOk) {
       viewModel.setLocationMode(targetMode)
-      if (targetMode == LocationMode.Always && Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+      if (targetMode == LocationMode.Always) {
         val backgroundOk =
           ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_BACKGROUND_LOCATION) ==
             PackageManager.PERMISSION_GRANTED

apps/android/app/src/main/java/com/clawdbot/android/ui/StatusPill.kt

@@ -28,9 +28,9 @@ import androidx.compose.ui.unit.dp
 fun StatusPill(
   bridge: BridgeState,
   voiceEnabled: Boolean,
-  activity: StatusActivity? = null,
   onClick: () -> Unit,
   modifier: Modifier = Modifier,
+  activity: StatusActivity? = null,
 ) {
   Surface(
     onClick = onClick,

apps/android/app/src/test/java/com/clawdbot/android/NodeForegroundServiceTest.kt

@@ -0,0 +1,43 @@
+package com.clawdbot.android
+
+import android.app.Notification
+import android.content.Intent
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.Robolectric
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.Shadows
+import org.robolectric.annotation.Config
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+class NodeForegroundServiceTest {
+  @Test
+  fun buildNotificationSetsLaunchIntent() {
+    val service = Robolectric.buildService(NodeForegroundService::class.java).get()
+    val notification = buildNotification(service)
+
+    val pendingIntent = notification.contentIntent
+    assertNotNull(pendingIntent)
+
+    val savedIntent = Shadows.shadowOf(pendingIntent).savedIntent
+    assertNotNull(savedIntent)
+    assertEquals(MainActivity::class.java.name, savedIntent.component?.className)
+
+    val expectedFlags = Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP
+    assertEquals(expectedFlags, savedIntent.flags and expectedFlags)
+  }
+
+  private fun buildNotification(service: NodeForegroundService): Notification {
+    val method =
+      NodeForegroundService::class.java.getDeclaredMethod(
+        "buildNotification",
+        String::class.java,
+        String::class.java,
+      )
+    method.isAccessible = true
+    return method.invoke(service, "Title", "Text") as Notification
+  }
+}

apps/macos/Sources/Clawdbot/AppState.swift

@@ -401,11 +401,9 @@ final class AppState {
     private func syncGatewayConfigIfNeeded() {
         guard !self.isPreview, !self.isInitializing else { return }
 
-        var root = ClawdbotConfigFile.loadDict()
-        var gateway = root["gateway"] as? [String: Any] ?? [:]
-        var changed = false
-
-        let desiredMode: String? = switch self.connectionMode {
+        let connectionMode = self.connectionMode
+        let remoteTarget = self.remoteTarget
+        let desiredMode: String? = switch connectionMode {
         case .local:
             "local"
         case .remote:
@@ -413,37 +411,44 @@ final class AppState {
         case .unconfigured:
             nil
         }
+        let remoteHost = connectionMode == .remote
+            ? CommandResolver.parseSSHTarget(remoteTarget)?.host
+            : nil
 
-        let currentMode = (gateway["mode"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
-        if let desiredMode {
-            if currentMode != desiredMode {
-                gateway["mode"] = desiredMode
+        Task { @MainActor in
+            var root = await ConfigStore.load()
+            var gateway = root["gateway"] as? [String: Any] ?? [:]
+            var changed = false
+
+            let currentMode = (gateway["mode"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+            if let desiredMode {
+                if currentMode != desiredMode {
+                    gateway["mode"] = desiredMode
+                    changed = true
+                }
+            } else if currentMode != nil {
+                gateway.removeValue(forKey: "mode")
                 changed = true
             }
-        } else if currentMode != nil {
-            gateway.removeValue(forKey: "mode")
-            changed = true
-        }
 
-        if self.connectionMode == .remote,
-           let host = CommandResolver.parseSSHTarget(self.remoteTarget)?.host
-        {
-            var remote = gateway["remote"] as? [String: Any] ?? [:]
-            let existingUrl = (remote["url"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-            let parsedExisting = existingUrl.isEmpty ? nil : URL(string: existingUrl)
-            let scheme = parsedExisting?.scheme?.isEmpty == false ? parsedExisting?.scheme : "ws"
-            let port = parsedExisting?.port ?? 18789
-            let desiredUrl = "\(scheme ?? "ws")://\(host):\(port)"
-            if existingUrl != desiredUrl {
-                remote["url"] = desiredUrl
-                gateway["remote"] = remote
-                changed = true
+            if connectionMode == .remote, let host = remoteHost {
+                var remote = gateway["remote"] as? [String: Any] ?? [:]
+                let existingUrl = (remote["url"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+                let parsedExisting = existingUrl.isEmpty ? nil : URL(string: existingUrl)
+                let scheme = parsedExisting?.scheme?.isEmpty == false ? parsedExisting?.scheme : "ws"
+                let port = parsedExisting?.port ?? 18789
+                let desiredUrl = "\(scheme ?? "ws")://\(host):\(port)"
+                if existingUrl != desiredUrl {
+                    remote["url"] = desiredUrl
+                    gateway["remote"] = remote
+                    changed = true
+                }
             }
-        }
 
-        guard changed else { return }
-        root["gateway"] = gateway
-        ClawdbotConfigFile.saveDict(root)
+            guard changed else { return }
+            root["gateway"] = gateway
+            try? await ConfigStore.save(root)
+        }
     }
 
     func triggerVoiceEars(ttl: TimeInterval? = 5) {

apps/macos/Sources/Clawdbot/ClawdbotConfigFile.swift

@@ -20,7 +20,7 @@ enum ClawdbotConfigFile {
         guard FileManager.default.fileExists(atPath: url.path) else { return [:] }
         do {
             let data = try Data(contentsOf: url)
-            guard let root = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+            guard let root = self.parseConfigData(data) else {
                 self.logger.warning("config JSON root invalid")
                 return [:]
             }
@@ -122,4 +122,19 @@ enum ClawdbotConfigFile {
         }
         return nil
     }
+
+    private static func parseConfigData(_ data: Data) -> [String: Any]? {
+        if let root = try? JSONSerialization.jsonObject(with: data) as? [String: Any] {
+            return root
+        }
+        let decoder = JSONDecoder()
+        if #available(macOS 12.0, *) {
+            decoder.allowsJSON5 = true
+        }
+        if let decoded = try? decoder.decode([String: AnyCodable].self, from: data) {
+            self.logger.notice("config parsed with JSON5 decoder")
+            return decoded.mapValues { $0.foundationValue }
+        }
+        return nil
+    }
 }

apps/macos/Sources/Clawdbot/ConfigStore.swift

@@ -34,11 +34,14 @@ enum ConfigStore {
             if let override = overrides.loadRemote {
                 return await override()
             }
-            return await self.loadFromGateway()
+            return await self.loadFromGateway() ?? [:]
         }
         if let override = overrides.loadLocal {
             return override()
         }
+        if let gateway = await self.loadFromGateway() {
+            return gateway
+        }
         return ClawdbotConfigFile.loadDict()
     }
 
@@ -55,13 +58,17 @@ enum ConfigStore {
             if let override = overrides.saveLocal {
                 override(root)
             } else {
-                ClawdbotConfigFile.saveDict(root)
+                do {
+                    try await self.saveToGateway(root)
+                } catch {
+                    ClawdbotConfigFile.saveDict(root)
+                }
             }
         }
     }
 
     @MainActor
-    private static func loadFromGateway() async -> [String: Any] {
+    private static func loadFromGateway() async -> [String: Any]? {
         do {
             let snap: ConfigSnapshot = try await GatewayConnection.shared.requestDecoded(
                 method: .configGet,
@@ -69,7 +76,7 @@ enum ConfigStore {
                 timeoutMs: 8000)
             return snap.config?.mapValues { $0.foundationValue } ?? [:]
         } catch {
-            return [:]
+            return nil
         }
     }
 

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

@@ -2,11 +2,11 @@ import SwiftUI
 
 extension ConnectionsSettings {
     var body: some View {
-        NavigationSplitView {
+        HStack(spacing: 0) {
             self.sidebar
-        } detail: {
             self.detail
         }
+        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
         .onAppear {
             self.store.start()
             self.ensureSelection()
@@ -18,27 +18,30 @@ extension ConnectionsSettings {
     }
 
     private var sidebar: some View {
-        List(selection: self.$selectedProvider) {
-            if !self.enabledProviders.isEmpty {
-                Section("Configured") {
+        ScrollView {
+            LazyVStack(alignment: .leading, spacing: 8) {
+                if !self.enabledProviders.isEmpty {
+                    self.sidebarSectionHeader("Configured")
                     ForEach(self.enabledProviders) { provider in
                         self.sidebarRow(provider)
-                            .tag(provider)
                     }
                 }
-            }
 
-            if !self.availableProviders.isEmpty {
-                Section("Available") {
+                if !self.availableProviders.isEmpty {
+                    self.sidebarSectionHeader("Available")
                     ForEach(self.availableProviders) { provider in
                         self.sidebarRow(provider)
-                            .tag(provider)
                     }
                 }
             }
+            .padding(.vertical, 10)
+            .padding(.horizontal, 10)
         }
-        .listStyle(.sidebar)
-        .frame(minWidth: 210, idealWidth: 230, maxWidth: 260)
+        .frame(minWidth: 220, idealWidth: 240, maxWidth: 280, maxHeight: .infinity, alignment: .topLeading)
+        .background(
+            RoundedRectangle(cornerRadius: 12, style: .continuous)
+                .fill(Color(nsColor: .windowBackgroundColor)))
+        .clipShape(RoundedRectangle(cornerRadius: 12, style: .continuous))
     }
 
     private var detail: some View {
@@ -49,7 +52,7 @@ extension ConnectionsSettings {
                 self.emptyDetail
             }
         }
-        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
+        .frame(minWidth: 460, maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
     }
 
     private var emptyDetail: some View {
@@ -79,18 +82,41 @@ extension ConnectionsSettings {
     }
 
     private func sidebarRow(_ provider: ConnectionProvider) -> some View {
-        HStack(spacing: 8) {
-            Circle()
-                .fill(self.providerTint(provider))
-                .frame(width: 8, height: 8)
-            VStack(alignment: .leading, spacing: 2) {
-                Text(provider.title)
-                Text(self.providerSummary(provider))
-                    .font(.caption)
-                    .foregroundStyle(.secondary)
+        let isSelected = self.selectedProvider == provider
+        return Button {
+            self.selectedProvider = provider
+        } label: {
+            HStack(spacing: 8) {
+                Circle()
+                    .fill(self.providerTint(provider))
+                    .frame(width: 8, height: 8)
+                VStack(alignment: .leading, spacing: 2) {
+                    Text(provider.title)
+                    Text(self.providerSummary(provider))
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                }
             }
+            .padding(.vertical, 4)
+            .padding(.horizontal, 6)
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .background(isSelected ? Color.accentColor.opacity(0.18) : Color.clear)
+            .clipShape(RoundedRectangle(cornerRadius: 10, style: .continuous))
+            .background(Color.clear) // ensure full-width hit test area
+            .contentShape(Rectangle())
         }
-        .padding(.vertical, 4)
+        .frame(maxWidth: .infinity, alignment: .leading)
+        .buttonStyle(.plain)
+        .contentShape(Rectangle())
+    }
+
+    private func sidebarSectionHeader(_ title: String) -> some View {
+        Text(title)
+            .font(.caption.weight(.semibold))
+            .foregroundStyle(.secondary)
+            .textCase(.uppercase)
+            .padding(.horizontal, 4)
+            .padding(.top, 2)
     }
 
     private func detailHeader(for provider: ConnectionProvider) -> some View {

apps/macos/Sources/Clawdbot/CronJobEditor.swift

@@ -323,6 +323,9 @@ struct CronJobEditor: View {
                             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)

apps/macos/Sources/Clawdbot/GatewayConnection.swift

@@ -10,6 +10,9 @@ enum GatewayAgentChannel: String, Codable, CaseIterable, Sendable {
     case whatsapp
     case telegram
     case discord
+    case slack
+    case signal
+    case imessage
     case webchat
 
     init(raw: String?) {

apps/macos/Sources/Clawdbot/GatewayEndpointStore.swift

@@ -13,12 +13,14 @@ enum GatewayEndpointState: Sendable, Equatable {
 /// - The endpoint store owns observation + explicit "ensure tunnel" actions.
 actor GatewayEndpointStore {
     static let shared = GatewayEndpointStore()
+    private static let supportedBindModes: Set<String> = ["loopback", "tailnet", "lan", "auto"]
 
     struct Deps: Sendable {
         let mode: @Sendable () async -> AppState.ConnectionMode
         let token: @Sendable () -> String?
         let password: @Sendable () -> String?
         let localPort: @Sendable () -> Int
+        let localHost: @Sendable () async -> String
         let remotePortIfRunning: @Sendable () async -> UInt16?
         let ensureRemoteTunnel: @Sendable () async throws -> UInt16
 
@@ -33,6 +35,16 @@ actor GatewayEndpointStore {
                     env: ProcessInfo.processInfo.environment)
             },
             localPort: { GatewayEnvironment.gatewayPort() },
+            localHost: {
+                let root = ClawdbotConfigFile.loadDict()
+                let bind = GatewayEndpointStore.resolveGatewayBindMode(
+                    root: root,
+                    env: ProcessInfo.processInfo.environment)
+                let tailscaleIP = await MainActor.run { TailscaleService.shared.tailscaleIP }
+                return GatewayEndpointStore.resolveLocalGatewayHost(
+                    bindMode: bind,
+                    tailscaleIP: tailscaleIP)
+            },
             remotePortIfRunning: { await RemoteTunnelManager.shared.controlTunnelPortIfRunning() },
             ensureRemoteTunnel: { try await RemoteTunnelManager.shared.ensureControlTunnel() })
     }
@@ -89,13 +101,17 @@ actor GatewayEndpointStore {
         }
 
         let port = deps.localPort()
+        let bind = GatewayEndpointStore.resolveGatewayBindMode(
+            root: ClawdbotConfigFile.loadDict(),
+            env: ProcessInfo.processInfo.environment)
+        let host = GatewayEndpointStore.resolveLocalGatewayHost(bindMode: bind, tailscaleIP: nil)
         let token = deps.token()
         let password = deps.password()
         switch initialMode {
         case .local:
             self.state = .ready(
                 mode: .local,
-                url: URL(string: "ws://127.0.0.1:\(port)")!,
+                url: URL(string: "ws://\(host):\(port)")!,
                 token: token,
                 password: password)
         case .remote:
@@ -129,9 +145,10 @@ actor GatewayEndpointStore {
         switch mode {
         case .local:
             let port = self.deps.localPort()
+            let host = await self.deps.localHost()
             self.setState(.ready(
                 mode: .local,
-                url: URL(string: "ws://127.0.0.1:\(port)")!,
+                url: URL(string: "ws://\(host):\(port)")!,
                 token: token,
                 password: password))
         case .remote:
@@ -218,6 +235,39 @@ actor GatewayEndpointStore {
                     "endpoint unavailable mode=\(modeDesc, privacy: .public) reason=\(reason, privacy: .public)")
         }
     }
+
+    private static func resolveGatewayBindMode(
+        root: [String: Any],
+        env: [String: String]) -> String?
+    {
+        if let envBind = env["CLAWDBOT_GATEWAY_BIND"] {
+            let trimmed = envBind.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+            if self.supportedBindModes.contains(trimmed) {
+                return trimmed
+            }
+        }
+        if let gateway = root["gateway"] as? [String: Any],
+           let bind = gateway["bind"] as? String
+        {
+            let trimmed = bind.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+            if self.supportedBindModes.contains(trimmed) {
+                return trimmed
+            }
+        }
+        return nil
+    }
+
+    private static func resolveLocalGatewayHost(
+        bindMode: String?,
+        tailscaleIP: String?) -> String
+    {
+        switch bindMode {
+        case "tailnet", "auto":
+            tailscaleIP ?? "127.0.0.1"
+        default:
+            "127.0.0.1"
+        }
+    }
 }
 
 #if DEBUG
@@ -229,5 +279,19 @@ extension GatewayEndpointStore {
     {
         self.resolveGatewayPassword(isRemote: isRemote, root: root, env: env)
     }
+
+    static func _testResolveGatewayBindMode(
+        root: [String: Any],
+        env: [String: String]) -> String?
+    {
+        self.resolveGatewayBindMode(root: root, env: env)
+    }
+
+    static func _testResolveLocalGatewayHost(
+        bindMode: String?,
+        tailscaleIP: String?) -> String
+    {
+        self.resolveLocalGatewayHost(bindMode: bindMode, tailscaleIP: tailscaleIP)
+    }
 }
 #endif

apps/macos/Sources/Clawdbot/GatewayProtocolSendable.swift

@@ -1,6 +0,0 @@
-import ClawdbotProtocol
-
-// The generated gateway protocol models are value types, but they don't currently declare Sendable.
-// We use them across actors via GatewayConnection's event stream, so mark them as unchecked.
-extension HelloOk: @unchecked Sendable {}
-extension EventFrame: @unchecked Sendable {}

apps/macos/Sources/Clawdbot/GeneralSettings.swift

@@ -151,6 +151,7 @@ struct GeneralSettings: View {
     private func requestLocationAuthorization(mode: ClawdbotLocationMode) async -> Bool {
         guard mode != .off else { return true }
         let status = CLLocationManager().authorizationStatus
+        // Note: macOS only supports authorizedAlways, not authorizedWhenInUse (iOS only)
         if status == .authorizedAlways {
             return true
         }

apps/macos/Sources/Clawdbot/PermissionManager.swift

@@ -140,6 +140,7 @@ enum PermissionManager {
     private static func ensureLocation(interactive: Bool) async -> Bool {
         let status = CLLocationManager().authorizationStatus
         switch status {
+        // Note: macOS only supports authorizedAlways, not authorizedWhenInUse (iOS only)
         case .authorizedAlways:
             return true
         case .notDetermined:
@@ -201,6 +202,7 @@ enum PermissionManager {
 
             case .location:
                 let status = CLLocationManager().authorizationStatus
+                // Note: macOS only supports authorizedAlways
                 results[cap] = status == .authorizedAlways
             }
         }

apps/macos/Sources/Clawdbot/SettingsRootView.swift

@@ -194,6 +194,22 @@ enum SettingsTab: CaseIterable {
         case .about: "About"
         }
     }
+
+    var systemImage: String {
+        switch self {
+        case .general: "gearshape"
+        case .connections: "link"
+        case .skills: "sparkles"
+        case .sessions: "clock.arrow.circlepath"
+        case .cron: "calendar"
+        case .config: "slider.horizontal.3"
+        case .instances: "network"
+        case .voiceWake: "waveform.circle"
+        case .permissions: "lock.shield"
+        case .debug: "ant"
+        case .about: "info.circle"
+        }
+    }
 }
 
 @MainActor

apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift

@@ -3,14 +3,14 @@ import Foundation
 
 public let GATEWAY_PROTOCOL_VERSION = 2
 
-public enum ErrorCode: String, Codable {
+public enum ErrorCode: String, Codable, Sendable {
     case notLinked = "NOT_LINKED"
     case agentTimeout = "AGENT_TIMEOUT"
     case invalidRequest = "INVALID_REQUEST"
     case unavailable = "UNAVAILABLE"
 }
 
-public struct ConnectParams: Codable {
+public struct ConnectParams: Codable, Sendable {
     public let minprotocol: Int
     public let maxprotocol: Int
     public let client: [String: AnyCodable]
@@ -47,7 +47,7 @@ public struct ConnectParams: Codable {
     }
 }
 
-public struct HelloOk: Codable {
+public struct HelloOk: Codable, Sendable {
     public let type: String
     public let _protocol: Int
     public let server: [String: AnyCodable]
@@ -84,7 +84,7 @@ public struct HelloOk: Codable {
     }
 }
 
-public struct RequestFrame: Codable {
+public struct RequestFrame: Codable, Sendable {
     public let type: String
     public let id: String
     public let method: String
@@ -109,7 +109,7 @@ public struct RequestFrame: Codable {
     }
 }
 
-public struct ResponseFrame: Codable {
+public struct ResponseFrame: Codable, Sendable {
     public let type: String
     public let id: String
     public let ok: Bool
@@ -138,7 +138,7 @@ public struct ResponseFrame: Codable {
     }
 }
 
-public struct EventFrame: Codable {
+public struct EventFrame: Codable, Sendable {
     public let type: String
     public let event: String
     public let payload: AnyCodable?
@@ -167,7 +167,7 @@ public struct EventFrame: Codable {
     }
 }
 
-public struct PresenceEntry: Codable {
+public struct PresenceEntry: Codable, Sendable {
     public let host: String?
     public let ip: String?
     public let version: String?
@@ -228,7 +228,7 @@ public struct PresenceEntry: Codable {
     }
 }
 
-public struct StateVersion: Codable {
+public struct StateVersion: Codable, Sendable {
     public let presence: Int
     public let health: Int
 
@@ -245,7 +245,7 @@ public struct StateVersion: Codable {
     }
 }
 
-public struct Snapshot: Codable {
+public struct Snapshot: Codable, Sendable {
     public let presence: [PresenceEntry]
     public let health: AnyCodable
     public let stateversion: StateVersion
@@ -278,7 +278,7 @@ public struct Snapshot: Codable {
     }
 }
 
-public struct ErrorShape: Codable {
+public struct ErrorShape: Codable, Sendable {
     public let code: String
     public let message: String
     public let details: AnyCodable?
@@ -307,7 +307,7 @@ public struct ErrorShape: Codable {
     }
 }
 
-public struct AgentEvent: Codable {
+public struct AgentEvent: Codable, Sendable {
     public let runid: String
     public let seq: Int
     public let stream: String
@@ -336,7 +336,7 @@ public struct AgentEvent: Codable {
     }
 }
 
-public struct SendParams: Codable {
+public struct SendParams: Codable, Sendable {
     public let to: String
     public let message: String
     public let mediaurl: String?
@@ -369,7 +369,7 @@ public struct SendParams: Codable {
     }
 }
 
-public struct AgentParams: Codable {
+public struct AgentParams: Codable, Sendable {
     public let message: String
     public let to: String?
     public let sessionid: String?
@@ -422,28 +422,24 @@ public struct AgentParams: Codable {
     }
 }
 
-public struct AgentWaitParams: Codable {
+public struct AgentWaitParams: Codable, Sendable {
     public let runid: String
-    public let afterms: Int?
     public let timeoutms: Int?
 
     public init(
         runid: String,
-        afterms: Int?,
         timeoutms: Int?
     ) {
         self.runid = runid
-        self.afterms = afterms
         self.timeoutms = timeoutms
     }
     private enum CodingKeys: String, CodingKey {
         case runid = "runId"
-        case afterms = "afterMs"
         case timeoutms = "timeoutMs"
     }
 }
 
-public struct WakeParams: Codable {
+public struct WakeParams: Codable, Sendable {
     public let mode: AnyCodable
     public let text: String
 
@@ -460,7 +456,7 @@ public struct WakeParams: Codable {
     }
 }
 
-public struct NodePairRequestParams: Codable {
+public struct NodePairRequestParams: Codable, Sendable {
     public let nodeid: String
     public let displayname: String?
     public let platform: String?
@@ -509,10 +505,10 @@ public struct NodePairRequestParams: Codable {
     }
 }
 
-public struct NodePairListParams: Codable {
+public struct NodePairListParams: Codable, Sendable {
 }
 
-public struct NodePairApproveParams: Codable {
+public struct NodePairApproveParams: Codable, Sendable {
     public let requestid: String
 
     public init(
@@ -525,7 +521,7 @@ public struct NodePairApproveParams: Codable {
     }
 }
 
-public struct NodePairRejectParams: Codable {
+public struct NodePairRejectParams: Codable, Sendable {
     public let requestid: String
 
     public init(
@@ -538,7 +534,7 @@ public struct NodePairRejectParams: Codable {
     }
 }
 
-public struct NodePairVerifyParams: Codable {
+public struct NodePairVerifyParams: Codable, Sendable {
     public let nodeid: String
     public let token: String
 
@@ -555,7 +551,7 @@ public struct NodePairVerifyParams: Codable {
     }
 }
 
-public struct NodeRenameParams: Codable {
+public struct NodeRenameParams: Codable, Sendable {
     public let nodeid: String
     public let displayname: String
 
@@ -572,10 +568,10 @@ public struct NodeRenameParams: Codable {
     }
 }
 
-public struct NodeListParams: Codable {
+public struct NodeListParams: Codable, Sendable {
 }
 
-public struct NodeDescribeParams: Codable {
+public struct NodeDescribeParams: Codable, Sendable {
     public let nodeid: String
 
     public init(
@@ -588,7 +584,7 @@ public struct NodeDescribeParams: Codable {
     }
 }
 
-public struct NodeInvokeParams: Codable {
+public struct NodeInvokeParams: Codable, Sendable {
     public let nodeid: String
     public let command: String
     public let params: AnyCodable?
@@ -617,7 +613,7 @@ public struct NodeInvokeParams: Codable {
     }
 }
 
-public struct SessionsListParams: Codable {
+public struct SessionsListParams: Codable, Sendable {
     public let limit: Int?
     public let activeminutes: Int?
     public let includeglobal: Bool?
@@ -642,7 +638,7 @@ public struct SessionsListParams: Codable {
     }
 }
 
-public struct SessionsPatchParams: Codable {
+public struct SessionsPatchParams: Codable, Sendable {
     public let key: String
     public let thinkinglevel: AnyCodable?
     public let verboselevel: AnyCodable?
@@ -679,7 +675,7 @@ public struct SessionsPatchParams: Codable {
     }
 }
 
-public struct SessionsResetParams: Codable {
+public struct SessionsResetParams: Codable, Sendable {
     public let key: String
 
     public init(
@@ -692,7 +688,7 @@ public struct SessionsResetParams: Codable {
     }
 }
 
-public struct SessionsDeleteParams: Codable {
+public struct SessionsDeleteParams: Codable, Sendable {
     public let key: String
     public let deletetranscript: Bool?
 
@@ -709,7 +705,7 @@ public struct SessionsDeleteParams: Codable {
     }
 }
 
-public struct SessionsCompactParams: Codable {
+public struct SessionsCompactParams: Codable, Sendable {
     public let key: String
     public let maxlines: Int?
 
@@ -726,10 +722,10 @@ public struct SessionsCompactParams: Codable {
     }
 }
 
-public struct ConfigGetParams: Codable {
+public struct ConfigGetParams: Codable, Sendable {
 }
 
-public struct ConfigSetParams: Codable {
+public struct ConfigSetParams: Codable, Sendable {
     public let raw: String
 
     public init(
@@ -742,10 +738,10 @@ public struct ConfigSetParams: Codable {
     }
 }
 
-public struct ConfigSchemaParams: Codable {
+public struct ConfigSchemaParams: Codable, Sendable {
 }
 
-public struct ConfigSchemaResponse: Codable {
+public struct ConfigSchemaResponse: Codable, Sendable {
     public let schema: AnyCodable
     public let uihints: [String: AnyCodable]
     public let version: String
@@ -770,7 +766,7 @@ public struct ConfigSchemaResponse: Codable {
     }
 }
 
-public struct WizardStartParams: Codable {
+public struct WizardStartParams: Codable, Sendable {
     public let mode: AnyCodable?
     public let workspace: String?
 
@@ -787,7 +783,7 @@ public struct WizardStartParams: Codable {
     }
 }
 
-public struct WizardNextParams: Codable {
+public struct WizardNextParams: Codable, Sendable {
     public let sessionid: String
     public let answer: [String: AnyCodable]?
 
@@ -804,7 +800,7 @@ public struct WizardNextParams: Codable {
     }
 }
 
-public struct WizardCancelParams: Codable {
+public struct WizardCancelParams: Codable, Sendable {
     public let sessionid: String
 
     public init(
@@ -817,7 +813,7 @@ public struct WizardCancelParams: Codable {
     }
 }
 
-public struct WizardStatusParams: Codable {
+public struct WizardStatusParams: Codable, Sendable {
     public let sessionid: String
 
     public init(
@@ -830,7 +826,7 @@ public struct WizardStatusParams: Codable {
     }
 }
 
-public struct WizardStep: Codable {
+public struct WizardStep: Codable, Sendable {
     public let id: String
     public let type: AnyCodable
     public let title: String?
@@ -946,7 +942,7 @@ public struct WizardStatusResult: Codable, Sendable {
     }
 }
 
-public struct TalkModeParams: Codable {
+public struct TalkModeParams: Codable, Sendable {
     public let enabled: Bool
     public let phase: String?
 
@@ -963,7 +959,7 @@ public struct TalkModeParams: Codable {
     }
 }
 
-public struct ProvidersStatusParams: Codable {
+public struct ProvidersStatusParams: Codable, Sendable {
     public let probe: Bool?
     public let timeoutms: Int?
 
@@ -980,7 +976,7 @@ public struct ProvidersStatusParams: Codable {
     }
 }
 
-public struct WebLoginStartParams: Codable {
+public struct WebLoginStartParams: Codable, Sendable {
     public let force: Bool?
     public let timeoutms: Int?
     public let verbose: Bool?
@@ -1001,7 +997,7 @@ public struct WebLoginStartParams: Codable {
     }
 }
 
-public struct WebLoginWaitParams: Codable {
+public struct WebLoginWaitParams: Codable, Sendable {
     public let timeoutms: Int?
 
     public init(
@@ -1014,7 +1010,7 @@ public struct WebLoginWaitParams: Codable {
     }
 }
 
-public struct ModelChoice: Codable {
+public struct ModelChoice: Codable, Sendable {
     public let id: String
     public let name: String
     public let provider: String
@@ -1043,10 +1039,10 @@ public struct ModelChoice: Codable {
     }
 }
 
-public struct ModelsListParams: Codable {
+public struct ModelsListParams: Codable, Sendable {
 }
 
-public struct ModelsListResult: Codable {
+public struct ModelsListResult: Codable, Sendable {
     public let models: [ModelChoice]
 
     public init(
@@ -1059,10 +1055,10 @@ public struct ModelsListResult: Codable {
     }
 }
 
-public struct SkillsStatusParams: Codable {
+public struct SkillsStatusParams: Codable, Sendable {
 }
 
-public struct SkillsInstallParams: Codable {
+public struct SkillsInstallParams: Codable, Sendable {
     public let name: String
     public let installid: String
     public let timeoutms: Int?
@@ -1083,7 +1079,7 @@ public struct SkillsInstallParams: Codable {
     }
 }
 
-public struct SkillsUpdateParams: Codable {
+public struct SkillsUpdateParams: Codable, Sendable {
     public let skillkey: String
     public let enabled: Bool?
     public let apikey: String?
@@ -1108,7 +1104,7 @@ public struct SkillsUpdateParams: Codable {
     }
 }
 
-public struct CronJob: Codable {
+public struct CronJob: Codable, Sendable {
     public let id: String
     public let name: String
     public let description: String?
@@ -1165,7 +1161,7 @@ public struct CronJob: Codable {
     }
 }
 
-public struct CronListParams: Codable {
+public struct CronListParams: Codable, Sendable {
     public let includedisabled: Bool?
 
     public init(
@@ -1178,10 +1174,10 @@ public struct CronListParams: Codable {
     }
 }
 
-public struct CronStatusParams: Codable {
+public struct CronStatusParams: Codable, Sendable {
 }
 
-public struct CronAddParams: Codable {
+public struct CronAddParams: Codable, Sendable {
     public let name: String
     public let description: String?
     public let enabled: Bool?
@@ -1222,7 +1218,7 @@ public struct CronAddParams: Codable {
     }
 }
 
-public struct CronUpdateParams: Codable {
+public struct CronUpdateParams: Codable, Sendable {
     public let id: String
     public let patch: [String: AnyCodable]
 
@@ -1239,7 +1235,7 @@ public struct CronUpdateParams: Codable {
     }
 }
 
-public struct CronRemoveParams: Codable {
+public struct CronRemoveParams: Codable, Sendable {
     public let id: String
 
     public init(
@@ -1252,7 +1248,7 @@ public struct CronRemoveParams: Codable {
     }
 }
 
-public struct CronRunParams: Codable {
+public struct CronRunParams: Codable, Sendable {
     public let id: String
     public let mode: AnyCodable?
 
@@ -1269,7 +1265,7 @@ public struct CronRunParams: Codable {
     }
 }
 
-public struct CronRunsParams: Codable {
+public struct CronRunsParams: Codable, Sendable {
     public let id: String
     public let limit: Int?
 
@@ -1286,7 +1282,7 @@ public struct CronRunsParams: Codable {
     }
 }
 
-public struct CronRunLogEntry: Codable {
+public struct CronRunLogEntry: Codable, Sendable {
     public let ts: Int
     public let jobid: String
     public let action: String
@@ -1331,7 +1327,7 @@ public struct CronRunLogEntry: Codable {
     }
 }
 
-public struct ChatHistoryParams: Codable {
+public struct ChatHistoryParams: Codable, Sendable {
     public let sessionkey: String
     public let limit: Int?
 
@@ -1348,7 +1344,7 @@ public struct ChatHistoryParams: Codable {
     }
 }
 
-public struct ChatSendParams: Codable {
+public struct ChatSendParams: Codable, Sendable {
     public let sessionkey: String
     public let message: String
     public let thinking: String?
@@ -1385,7 +1381,7 @@ public struct ChatSendParams: Codable {
     }
 }
 
-public struct ChatAbortParams: Codable {
+public struct ChatAbortParams: Codable, Sendable {
     public let sessionkey: String
     public let runid: String
 
@@ -1402,7 +1398,7 @@ public struct ChatAbortParams: Codable {
     }
 }
 
-public struct ChatEvent: Codable {
+public struct ChatEvent: Codable, Sendable {
     public let runid: String
     public let sessionkey: String
     public let seq: Int
@@ -1443,7 +1439,7 @@ public struct ChatEvent: Codable {
     }
 }
 
-public struct TickEvent: Codable {
+public struct TickEvent: Codable, Sendable {
     public let ts: Int
 
     public init(
@@ -1456,7 +1452,7 @@ public struct TickEvent: Codable {
     }
 }
 
-public struct ShutdownEvent: Codable {
+public struct ShutdownEvent: Codable, Sendable {
     public let reason: String
     public let restartexpectedms: Int?
 
@@ -1473,7 +1469,7 @@ public struct ShutdownEvent: Codable {
     }
 }
 
-public enum GatewayFrame: Codable {
+public enum GatewayFrame: Codable, Sendable {
     case req(RequestFrame)
     case res(ResponseFrame)
     case event(EventFrame)

apps/macos/Tests/ClawdbotIPCTests/GatewayEndpointStoreTests.swift

@@ -1,156 +1,36 @@
-import Foundation
 import Testing
 @testable import Clawdbot
 
-@Suite struct GatewayEndpointStoreTests {
-    private final class ModeBox: @unchecked Sendable {
-        private let lock = NSLock()
-        private var value: AppState.ConnectionMode
-
-        init(_ initial: AppState.ConnectionMode) {
-            self.value = initial
-        }
-
-        func get() -> AppState.ConnectionMode {
-            self.lock.lock()
-            defer { self.lock.unlock() }
-            return self.value
-        }
-
-        func set(_ next: AppState.ConnectionMode) {
-            self.lock.lock()
-            defer { self.lock.unlock() }
-            self.value = next
-        }
+@Suite(.serialized)
+struct GatewayEndpointStoreTests {
+    @Test func resolvesLocalHostFromBindModes() {
+        #expect(GatewayEndpointStore._testResolveLocalGatewayHost(
+            bindMode: "loopback",
+            tailscaleIP: "100.64.0.10") == "127.0.0.1")
+        #expect(GatewayEndpointStore._testResolveLocalGatewayHost(
+            bindMode: "lan",
+            tailscaleIP: "100.64.0.10") == "127.0.0.1")
+        #expect(GatewayEndpointStore._testResolveLocalGatewayHost(
+            bindMode: "tailnet",
+            tailscaleIP: "100.64.0.10") == "100.64.0.10")
+        #expect(GatewayEndpointStore._testResolveLocalGatewayHost(
+            bindMode: "tailnet",
+            tailscaleIP: nil) == "127.0.0.1")
+        #expect(GatewayEndpointStore._testResolveLocalGatewayHost(
+            bindMode: "auto",
+            tailscaleIP: "100.64.0.10") == "100.64.0.10")
+        #expect(GatewayEndpointStore._testResolveLocalGatewayHost(
+            bindMode: "auto",
+            tailscaleIP: nil) == "127.0.0.1")
     }
 
-    @Test func localRefreshResolvesToLocalhostPort() async throws {
-        let mode = ModeBox(.local)
-        let store = GatewayEndpointStore(deps: .init(
-            mode: { mode.get() },
-            token: { "t" },
-            password: { nil },
-            localPort: { 1234 },
-            remotePortIfRunning: { nil },
-            ensureRemoteTunnel: { 18789 }))
-
-        await store.refresh()
-        let cfg = try await store.requireConfig()
-        #expect(cfg.url.absoluteString == "ws://127.0.0.1:1234")
-        #expect(cfg.token == "t")
-    }
-
-    @Test func remoteWithoutTunnelRecoversByEnsuringTunnel() async throws {
-        let mode = ModeBox(.remote)
-        let store = GatewayEndpointStore(deps: .init(
-            mode: { mode.get() },
-            token: { nil },
-            password: { nil },
-            localPort: { 18789 },
-            remotePortIfRunning: { nil },
-            ensureRemoteTunnel: { 18789 }))
-
-        let cfg = try await store.requireConfig()
-        #expect(cfg.url.absoluteString == "ws://127.0.0.1:18789")
-        #expect(cfg.token == nil)
-    }
-
-    @Test func ensureRemoteTunnelPublishesReadyState() async throws {
-        let mode = ModeBox(.remote)
-        let store = GatewayEndpointStore(deps: .init(
-            mode: { mode.get() },
-            token: { "tok" },
-            password: { "pw" },
-            localPort: { 1 },
-            remotePortIfRunning: { 5555 },
-            ensureRemoteTunnel: { 5555 }))
-
-        let stream = await store.subscribe(bufferingNewest: 10)
-        var iterator = stream.makeAsyncIterator()
-
-        _ = await iterator.next() // initial
-        _ = try await store.ensureRemoteControlTunnel()
-
-        let next = await iterator.next()
-        guard case let .ready(mode, url, token, password) = next else {
-            Issue.record("expected .ready after ensure, got \(String(describing: next))")
-            return
-        }
-        #expect(mode == .remote)
-        #expect(url.absoluteString == "ws://127.0.0.1:5555")
-        #expect(token == "tok")
-        #expect(password == "pw")
-    }
-
-    @Test func resolvesGatewayPasswordByMode() {
-        let root: [String: Any] = [
-            "gateway": [
-                "auth": ["password": " local "],
-                "remote": ["password": " remote "],
-            ],
-        ]
-        let env: [String: String] = [:]
-
-        #expect(GatewayEndpointStore._testResolveGatewayPassword(
-            isRemote: false,
+    @Test func resolvesBindModeFromEnvOrConfig() {
+        let root: [String: Any] = ["gateway": ["bind": "tailnet"]]
+        #expect(GatewayEndpointStore._testResolveGatewayBindMode(
             root: root,
-            env: env) == "local")
-        #expect(GatewayEndpointStore._testResolveGatewayPassword(
-            isRemote: true,
+            env: [:]) == "tailnet")
+        #expect(GatewayEndpointStore._testResolveGatewayBindMode(
             root: root,
-            env: env) == "remote")
-    }
-
-    @Test func gatewayPasswordEnvOverridesConfig() {
-        let root: [String: Any] = [
-            "gateway": [
-                "auth": ["password": "local"],
-                "remote": ["password": "remote"],
-            ],
-        ]
-        let env = ["CLAWDBOT_GATEWAY_PASSWORD": " env "]
-
-        #expect(GatewayEndpointStore._testResolveGatewayPassword(
-            isRemote: false,
-            root: root,
-            env: env) == "env")
-        #expect(GatewayEndpointStore._testResolveGatewayPassword(
-            isRemote: true,
-            root: root,
-            env: env) == "env")
-    }
-
-    @Test func gatewayPasswordIgnoresWhitespaceValues() {
-        let root: [String: Any] = [
-            "gateway": [
-                "auth": ["password": "   "],
-                "remote": ["password": "\n\t"],
-            ],
-        ]
-        let env = ["CLAWDBOT_GATEWAY_PASSWORD": "  "]
-
-        #expect(GatewayEndpointStore._testResolveGatewayPassword(
-            isRemote: false,
-            root: root,
-            env: env) == nil)
-        #expect(GatewayEndpointStore._testResolveGatewayPassword(
-            isRemote: true,
-            root: root,
-            env: env) == nil)
-    }
-
-    @Test func unconfiguredModeRejectsConfig() async {
-        let mode = ModeBox(.unconfigured)
-        let store = GatewayEndpointStore(deps: .init(
-            mode: { mode.get() },
-            token: { nil },
-            password: { nil },
-            localPort: { 18789 },
-            remotePortIfRunning: { nil },
-            ensureRemoteTunnel: { 18789 }))
-
-        await #expect(throws: Error.self) {
-            _ = try await store.requireConfig()
-        }
+            env: ["CLAWDBOT_GATEWAY_BIND": "lan"]) == "lan")
     }
 }

apps/macos/Tests/ClawdbotIPCTests/PermissionManagerTests.swift

@@ -1,5 +1,6 @@
 import Testing
 import ClawdbotIPC
+import CoreLocation
 @testable import Clawdbot
 
 @Suite(.serialized)
@@ -22,4 +23,16 @@ struct PermissionManagerTests {
         let ensured = await PermissionManager.ensure(caps, interactive: false)
         #expect(ensured.keys.count == caps.count)
     }
+
+    @Test func locationStatusMatchesAuthorizationAlways() async {
+        let status = CLLocationManager().authorizationStatus
+        let results = await PermissionManager.status([.location])
+        #expect(results[.location] == (status == .authorizedAlways))
+    }
+
+    @Test func ensureLocationNonInteractiveMatchesAuthorizationAlways() async {
+        let status = CLLocationManager().authorizationStatus
+        let ensured = await PermissionManager.ensure([.location], interactive: false)
+        #expect(ensured[.location] == (status == .authorizedAlways))
+    }
 }

apps/shared/ClawdbotKit/Resources/tool-display.json

@@ -12,7 +12,7 @@
       "element",
       "node",
       "nodeId",
-      "jobId",
+      "id",
       "requestId",
       "to",
       "channelId",
@@ -136,10 +136,10 @@
           "label": "add",
           "detailKeys": ["job.name", "job.id", "job.schedule", "job.cron"]
         },
-        "update": { "label": "update", "detailKeys": ["jobId"] },
-        "remove": { "label": "remove", "detailKeys": ["jobId"] },
-        "run": { "label": "run", "detailKeys": ["jobId"] },
-        "runs": { "label": "runs", "detailKeys": ["jobId"] },
+        "update": { "label": "update", "detailKeys": ["id"] },
+        "remove": { "label": "remove", "detailKeys": ["id"] },
+        "run": { "label": "run", "detailKeys": ["id"] },
+        "runs": { "label": "runs", "detailKeys": ["id"] },
         "wake": { "label": "wake", "detailKeys": ["text", "mode"] }
       }
     },

docs/AGENTS.default.md

@@ -8,26 +8,26 @@ read_when:
 
 ## First run (recommended)
 
-Clawdbot uses a dedicated workspace directory for the agent. Default: `~/.clawdbot/workspace`.
+Clawdbot uses a dedicated workspace directory for the agent. Default: `~/clawd` (configurable via `agent.workspace`).
 
 1) Create the workspace (if it doesn’t already exist):
 
 ```bash
-mkdir -p ~/.clawdbot/workspace
+mkdir -p ~/clawd
 ```
 
 2) Copy the default workspace templates into the workspace:
 
 ```bash
-cp docs/templates/AGENTS.md ~/.clawdbot/workspace/AGENTS.md
-cp docs/templates/SOUL.md ~/.clawdbot/workspace/SOUL.md
-cp docs/templates/TOOLS.md ~/.clawdbot/workspace/TOOLS.md
+cp docs/templates/AGENTS.md ~/clawd/AGENTS.md
+cp docs/templates/SOUL.md ~/clawd/SOUL.md
+cp docs/templates/TOOLS.md ~/clawd/TOOLS.md
 ```
 
 3) Optional: if you want the personal assistant skill roster, replace AGENTS.md with this file:
 
 ```bash
-cp docs/AGENTS.default.md ~/.clawdbot/workspace/AGENTS.md
+cp docs/AGENTS.default.md ~/clawd/AGENTS.md
 ```
 
 4) Optional: choose a different workspace by setting `agent.workspace` (supports `~`):
@@ -73,7 +73,7 @@ cp docs/AGENTS.default.md ~/.clawdbot/workspace/AGENTS.md
 If you treat this workspace as Clawd’s “memory”, make it a git repo (ideally private) so `AGENTS.md` and your memory files are backed up.
 
 ```bash
-cd ~/.clawdbot/workspace
+cd ~/clawd
 git init
 git add AGENTS.md
 git commit -m "Add Clawd workspace"

docs/_config.yml

@@ -1,5 +1,5 @@
 title: "CLAWDBOT Docs"
-description: "A TypeScript/Node gateway + macOS/iOS companions for WhatsApp (web) and Telegram (bot)."
+description: "A TypeScript/Node gateway + macOS/iOS/Android companions for WhatsApp (web) and Telegram (bot)."
 markdown: kramdown
 highlighter: rouge
 
@@ -35,9 +35,11 @@ nav:
   - title: "WebChat"
     url: "/webchat.html"
   - title: "macOS App"
-    url: "/clawdbot-mac.html"
-  - title: "iOS Node"
-    url: "/ios/connect.html"
+    url: "/macos.html"
+  - title: "iOS App"
+    url: "/ios.html"
+  - title: "Android App"
+    url: "/android.html"
   - title: "Telegram"
     url: "/telegram.html"
   - title: "Security"

docs/agent-loop.md

@@ -0,0 +1,61 @@
+---
+summary: "Agent loop lifecycle, streams, and wait semantics"
+read_when:
+  - You need an exact walkthrough of the agent loop or lifecycle events
+---
+# Agent Loop (Clawdis)
+
+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`.
+- 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.
+2) `agentCommand` runs the agent:
+   - resolves model + thinking/verbose defaults
+   - loads skills snapshot
+   - calls `runEmbeddedPiAgent` (pi-agent-core runtime)
+   - emits **lifecycle end/error** if the embedded loop does not emit one
+3) `runEmbeddedPiAgent`:
+   - builds `AgentSession` and subscribes to pi events
+   - streams assistant deltas + tool events
+   - enforces timeout -> aborts run if exceeded
+   - returns payloads + usage metadata
+4) `subscribeEmbeddedPiSession` bridges pi-agent-core events to Clawdis `agent` stream:
+   - tool events => `stream: "tool"`
+   - assistant deltas => `stream: "assistant"`
+   - lifecycle events => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`)
+5) `agent.wait` uses `waitForAgentJob`:
+   - waits for **lifecycle end/error** for `runId`
+   - returns `{ status: ok|error|timeout, startedAt, endedAt, error? }`
+
+## Event streams (today)
+- `lifecycle`: emitted by `subscribeEmbeddedPiSession` (and as a fallback by `agentCommand`)
+- `assistant`: streamed deltas from pi-agent-core
+- `tool`: streamed tool events from pi-agent-core
+
+## 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
+
+## Timeouts
+- `agent.wait` default: 30s (just the wait). `timeoutMs` param overrides.
+- Agent runtime: `agent.timeoutSeconds` default 600s; enforced in `runEmbeddedPiAgent` abort timer.
+
+## Where things can end early
+- Agent timeout (abort)
+- AbortSignal (cancel)
+- Gateway disconnect or RPC timeout
+- `agent.wait` timeout (wait-only, does not stop agent)
+
+## Files
+- `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`

docs/agent.md

@@ -3,7 +3,6 @@ summary: "Agent runtime (embedded p-mono), workspace contract, and session boots
 read_when:
   - Changing agent runtime, workspace bootstrap, or session behavior
 ---
-<!-- {% raw %} -->
 # Agent Runtime 🤖
 
 CLAWDBOT runs a single embedded agent runtime derived from **p-mono** (internal name: **p**).
@@ -101,4 +100,3 @@ At minimum, set:
 ---
 
 *Next: [Group Chats](./group-messages.md)* 🦞
-<!-- {% endraw %} -->

docs/android.md

@@ -1,18 +1,20 @@
 ---
-summary: "Runbook: connect/pair the Android node to a Clawdbot Gateway and use Canvas/Chat/Camera"
+summary: "Android app (node): connection runbook + Canvas/Chat/Camera"
 read_when:
   - Pairing or reconnecting the Android node
   - Debugging Android bridge discovery or auth
   - Verifying chat history parity across clients
 ---
 
-# Android Node Connection Runbook
+# Android App (Node)
+
+## Connection Runbook
 
 Android node app ⇄ (mDNS/NSD + TCP bridge) ⇄ **Gateway bridge** ⇄ (loopback WS) ⇄ **Gateway**
 
 The Gateway WebSocket stays loopback-only (`ws://127.0.0.1:18789`). Android talks to the LAN-facing **bridge** (default `tcp://0.0.0.0:18790`) and uses Gateway-owned pairing.
 
-## Prerequisites
+### Prerequisites
 
 - You can run the Gateway on the “master” machine.
 - Android device/emulator can reach the gateway bridge:
@@ -21,7 +23,7 @@ The Gateway WebSocket stays loopback-only (`ws://127.0.0.1:18789`). Android talk
   - Manual bridge host/port (fallback)
 - You can run the CLI (`clawdbot`) on the gateway machine (or via SSH).
 
-## 1) Start the Gateway (with bridge enabled)
+### 1) Start the Gateway (with bridge enabled)
 
 Bridge is enabled by default (disable via `CLAWDBOT_BRIDGE_ENABLED=0`).
 
@@ -37,7 +39,7 @@ For tailnet-only setups (recommended for Vienna ⇄ London), bind the bridge to
 - Set `bridge.bind: "tailnet"` in `~/.clawdbot/clawdbot.json` on the gateway host.
 - Restart the Gateway / macOS menubar app.
 
-## 2) Verify discovery (optional)
+### 2) Verify discovery (optional)
 
 From the gateway machine:
 
@@ -47,7 +49,7 @@ dns-sd -B _clawdbot-bridge._tcp local.
 
 More debugging notes: `docs/bonjour.md`.
 
-### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD
+#### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD
 
 Android NSD/mDNS discovery won’t cross networks. If your Android node and the gateway are on different networks but connected via Tailscale, use Wide-Area Bonjour / unicast DNS-SD instead:
 
@@ -56,7 +58,7 @@ Android NSD/mDNS discovery won’t cross networks. If your Android node and the
 
 Details and example CoreDNS config: `docs/bonjour.md`.
 
-## 3) Connect from Android
+### 3) Connect from Android
 
 In the Android app:
 
@@ -69,7 +71,7 @@ After the first successful pairing, Android auto-reconnects on launch:
 - Manual endpoint (if enabled), otherwise
 - The last discovered bridge (best-effort).
 
-## 4) Approve pairing (CLI)
+### 4) Approve pairing (CLI)
 
 On the gateway machine:
 
@@ -80,7 +82,7 @@ clawdbot nodes approve <requestId>
 
 Pairing details: `docs/gateway/pairing.md`.
 
-## 5) Verify the node is connected
+### 5) Verify the node is connected
 
 - Via nodes status:
   ```bash
@@ -91,7 +93,7 @@ Pairing details: `docs/gateway/pairing.md`.
   clawdbot gateway call node.list --params "{}"
   ```
 
-## 6) Chat + history
+### 6) Chat + history
 
 The Android node’s Chat sheet uses the gateway’s **primary session key** (`main`), so history and replies are shared with WebChat and other clients:
 
@@ -99,9 +101,9 @@ The Android node’s Chat sheet uses the gateway’s **primary session key** (`m
 - Send: `chat.send`
 - Push updates (best-effort): `chat.subscribe` → `event:"chat"`
 
-## 7) Canvas + camera
+### 7) Canvas + camera
 
-### Gateway Canvas Host (recommended for web content)
+#### Gateway Canvas Host (recommended for web content)
 
 If you want the node to show real HTML/CSS/JS that the agent can edit on disk, point the node at the Gateway canvas host.
 

docs/architecture.md

@@ -1,27 +1,52 @@
 ---
-summary: "Target WebSocket gateway architecture, components, and client flows"
+summary: "WebSocket gateway architecture, components, and client flows"
 read_when:
   - Working on gateway protocol, clients, or transports
 ---
-# Gateway Architecture (target state)
+# Gateway Architecture
 
-Last updated: 2025-12-09
+Last updated: 2026-01-05
 
 ## Overview
-- A single long-lived **Gateway** process owns all messaging surfaces (WhatsApp via Baileys, Telegram via grammY, Discord via discord.js) and the control/event plane.
-- All clients (macOS app, CLI, web UI, automations) connect to the Gateway over one transport: **WebSocket on 127.0.0.1:18789** (tunnel or VPN for remote).
+- A single long-lived **Gateway** process owns all messaging surfaces (WhatsApp via Baileys, Telegram via grammY, Slack via Bolt, Discord via discord.js, Signal via signal-cli, iMessage via imsg, WebChat) and the control/event plane.
+- All clients (macOS app, CLI, web UI, automations) connect to the Gateway over one transport: **WebSocket on the configured bind host** (default `127.0.0.1:18789`; tunnel or VPN for remote).
 - One Gateway per host; it is the only place that is allowed to open a WhatsApp session. All sends/agent runs go through it.
 - By default: the Gateway exposes a Canvas host on `canvasHost.port` (default `18793`), serving `~/clawd/canvas` at `/__clawdbot__/canvas/` with live-reload; disable via `canvasHost.enabled=false` or `CLAWDBOT_SKIP_CANVAS_HOST=1`.
 
+## Implementation snapshot (current code)
+
+### 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`): 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.
+- Auto-connect: `BridgeConnectionController` uses stored `node.instanceId` + Keychain token; supports manual host/port; performs `pair-and-hello`.
+- Bridge runtime: `BridgeSession` actor owns an `NWConnection`, JSONL frames, `hello`/`hello-ok`, ping/pong, `req/res`, server `event`s, and `invoke` callbacks; stores `canvasHostUrl`.
+- Commands: `NodeAppModel` executes `canvas.*`, `canvas.a2ui.*`, `camera.*`, `screen.record`, `location.get`. Canvas/camera/screen are blocked when backgrounded.
+- Canvas + actions: `WKWebView` with A2UI action bridge; accepts actions from local-network or trusted file URLs; intercepts `clawdbot://` deep links and forwards `agent.request` to the bridge.
+- Voice/talk: voice wake sends `voice.transcript` events and syncs triggers via `voicewake.get` + `voicewake.changed`; Talk Mode attaches to the bridge.
+
+### Android node (`apps/android`)
+- Discovery + pairing: `BridgeDiscovery` uses mDNS/NSD to find `_clawdbot-bridge._tcp`, with manual host/port fallback.
+- Auto-connect: `NodeRuntime` restores a stored token, performs `pair-and-hello`, and reconnects to the last discovered or manual bridge.
+- Bridge runtime: `BridgeSession` owns the TCP JSONL session (`hello`/`hello-ok`, ping/pong, `req/res`, `event`, `invoke`); stores `canvasHostUrl`.
+- Commands: `NodeRuntime` executes `canvas.*`, `canvas.a2ui.*`, `camera.*`, and chat/session events; foreground-only for canvas/camera.
+
 ## Components and flows
 - **Gateway (daemon)**  
-  - Maintains Baileys/Telegram/Discord connections.  
+  - Maintains WhatsApp (Baileys), Telegram (grammY), Slack (Bolt), Discord (discord.js), Signal (signal-cli), and iMessage (imsg) connections.  
   - Exposes a typed WS API (req/resp + server push events).  
   - Validates every inbound frame against JSON Schema; rejects anything before a mandatory `connect`.
 - **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/clawdbot-mac.md`).
+  - 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**  

docs/assets/markdown.css

@@ -3,6 +3,10 @@
   line-height: 1.7;
 }
 
+.mdx-content > h1:first-of-type {
+  display: none;
+}
+
 .markdown h1,
 .markdown h2,
 .markdown h3,
@@ -127,4 +131,3 @@
   font-family: var(--font-pixel);
   letter-spacing: 0.06em;
 }
-

docs/assets/terminal.css

@@ -29,40 +29,40 @@ html[data-theme="auto"] {
 }
 
 html[data-theme="dark"] {
-  --bg0: #06141f;
-  --bg1: #031019;
-  --panel: #061a16;
-  --panel2: #071f19;
-  --text: #d6f6ea;
-  --muted: #95c9b9;
-  --faint: #66a391;
-  --link: #79ffd0;
-  --link2: #ff775f;
+  --bg0: #0b1a22;
+  --bg1: #0a1720;
+  --panel: #0e231f;
+  --panel2: #102a24;
+  --text: #c9eadc;
+  --muted: #8ab8aa;
+  --faint: #699b8d;
+  --link: #6fe8c7;
+  --link2: #ff7b63;
   --accent: #ff4f40;
-  --accent2: #67ff9b;
-  --frame-border: #b7ffe6;
-  --code-bg: #04110d;
-  --code-fg: #dcfff1;
-  --code-accent: #67ff9b;
+  --accent2: #5fdfa2;
+  --frame-border: #6fbfa8;
+  --code-bg: #091814;
+  --code-fg: #d7f5e8;
+  --code-accent: #5fdfa2;
 }
 
 @media (prefers-color-scheme: dark) {
   html[data-theme="auto"] {
-    --bg0: #06141f;
-    --bg1: #031019;
-    --panel: #061a16;
-    --panel2: #071f19;
-    --text: #d6f6ea;
-    --muted: #95c9b9;
-    --faint: #66a391;
-    --link: #79ffd0;
-    --link2: #ff775f;
+    --bg0: #0b1a22;
+    --bg1: #0a1720;
+    --panel: #0e231f;
+    --panel2: #102a24;
+    --text: #c9eadc;
+    --muted: #8ab8aa;
+    --faint: #699b8d;
+    --link: #6fe8c7;
+    --link2: #ff7b63;
     --accent: #ff4f40;
-    --accent2: #67ff9b;
-    --frame-border: #b7ffe6;
-    --code-bg: #04110d;
-    --code-fg: #dcfff1;
-    --code-accent: #67ff9b;
+    --accent2: #5fdfa2;
+    --frame-border: #6fbfa8;
+    --code-bg: #091814;
+    --code-fg: #d7f5e8;
+    --code-accent: #5fdfa2;
   }
 }
 
@@ -87,39 +87,9 @@ body {
   overflow-x: hidden;
 }
 
-body::before {
-  content: "";
-  position: fixed;
-  inset: 0;
-  pointer-events: none;
-  opacity: 0.45;
-  background-image:
-    linear-gradient(to right, color-mix(in oklab, var(--text) 10%, transparent) 1px, transparent 1px),
-    linear-gradient(to bottom, color-mix(in oklab, var(--text) 10%, transparent) 1px, transparent 1px);
-  background-size: 28px 28px;
-  mix-blend-mode: overlay;
-}
-
+body::before,
 body::after {
-  content: "";
-  position: fixed;
-  inset: 0;
-  pointer-events: none;
-  background: repeating-linear-gradient(
-    to bottom,
-    rgba(0, 0, 0, var(--scanline-opacity)),
-    rgba(0, 0, 0, var(--scanline-opacity)) 1px,
-    transparent 1px,
-    transparent var(--scanline-size)
-  );
-  opacity: 0.8;
-  mix-blend-mode: multiply;
-}
-
-@media (prefers-reduced-motion: reduce) {
-  body::after {
-    display: none;
-  }
+  display: none;
 }
 
 .skip-link {

docs/audio.md

@@ -3,7 +3,6 @@ summary: "How inbound audio/voice notes are downloaded, transcribed, and injecte
 read_when:
   - Changing audio transcription or media handling
 ---
-<!-- {% raw %} -->
 # Audio / Voice Notes — 2025-12-05
 
 ## What works
@@ -47,4 +46,3 @@ Requires `OPENAI_API_KEY` in env and `openai` CLI installed:
 ## Gotchas
 - Ensure your CLI exits 0 and prints plain text; JSON needs to be massaged via `jq -r .text`.
 - Keep timeouts reasonable (`timeoutSeconds`, default 45s) to avoid blocking the reply queue.
-<!-- {% endraw %} -->

docs/browser-linux-troubleshooting.md

@@ -0,0 +1,114 @@
+---
+summary: "Fix Chrome/Chromium CDP startup issues for Clawdbot browser control on Linux"
+read_when: "Browser control fails on Linux, especially with snap Chromium"
+---
+
+# Browser Troubleshooting (Linux)
+
+## Problem: "Failed to start Chrome CDP on port 18800"
+
+Clawdbot's browser control server fails to launch Chrome/Chromium with the error:
+```
+{"error":"Error: Failed to start Chrome CDP on port 18800 for profile \"clawd\"."}
+```
+
+### Root Cause
+
+On Ubuntu (and many Linux distros), the default Chromium installation is a **snap package**. Snap's AppArmor confinement interferes with how Clawdbot spawns and monitors the browser process.
+
+The `apt install chromium` command installs a stub package that redirects to snap:
+```
+Note, selecting 'chromium-browser' instead of 'chromium'
+chromium-browser is already the newest version (2:1snap1-0ubuntu2).
+```
+
+This is NOT a real browser — it's just a wrapper.
+
+### Solution 1: Install Google Chrome (Recommended)
+
+Install the official Google Chrome `.deb` package, which is not sandboxed by snap:
+
+```bash
+wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
+sudo dpkg -i google-chrome-stable_current_amd64.deb
+sudo apt --fix-broken install -y  # if there are dependency errors
+```
+
+Then update your Clawdbot config (`~/.clawdbot/clawdbot.json`):
+
+```json
+{
+  "browser": {
+    "enabled": true,
+    "executablePath": "/usr/bin/google-chrome-stable",
+    "headless": true,
+    "noSandbox": true
+  }
+}
+```
+
+### Solution 2: Use Snap Chromium with Attach-Only Mode
+
+If you must use snap Chromium, configure Clawdbot to attach to a manually-started browser:
+
+1. Update config:
+```json
+{
+  "browser": {
+    "enabled": true,
+    "attachOnly": true,
+    "headless": true,
+    "noSandbox": true
+  }
+}
+```
+
+2. Start Chromium manually:
+```bash
+chromium-browser --headless --no-sandbox --disable-gpu \
+  --remote-debugging-port=18800 \
+  --user-data-dir=$HOME/.clawdbot/browser/clawd/user-data \
+  about:blank &
+```
+
+3. Optionally create a systemd user service to auto-start Chrome:
+```ini
+# ~/.config/systemd/user/clawd-browser.service
+[Unit]
+Description=Clawd Browser (Chrome CDP)
+After=network.target
+
+[Service]
+ExecStart=/snap/bin/chromium --headless --no-sandbox --disable-gpu --remote-debugging-port=18800 --user-data-dir=%h/.clawdbot/browser/clawd/user-data about:blank
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+```
+
+Enable with: `systemctl --user enable --now clawd-browser.service`
+
+### Verifying the Browser Works
+
+Check status:
+```bash
+curl -s http://127.0.0.1:18791/ | jq '{running, pid, chosenBrowser}'
+```
+
+Test browsing:
+```bash
+curl -s -X POST http://127.0.0.1:18791/start
+curl -s http://127.0.0.1:18791/tabs
+```
+
+### Config Reference
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `browser.enabled` | Enable browser control | `true` |
+| `browser.executablePath` | Path to Chrome/Chromium binary | auto-detected |
+| `browser.headless` | Run without GUI | `false` |
+| `browser.noSandbox` | Add `--no-sandbox` flag (needed for some Linux setups) | `false` |
+| `browser.attachOnly` | Don't launch browser, only attach to existing | `false` |
+| `browser.cdpPort` | Chrome DevTools Protocol port | `18800` |

docs/browser.md

@@ -287,3 +287,7 @@ Notes:
 - Sharing the user's logged-in Chrome sessions automatically.
 - General-purpose web scraping; this is primarily for "close-the-loop" verification
   and interaction.
+
+## Troubleshooting
+
+For Linux-specific issues (especially Ubuntu with snap Chromium), see [browser-linux-troubleshooting.md](./browser-linux-troubleshooting.md).

docs/clawd.md

@@ -4,7 +4,6 @@ read_when:
   - Onboarding a new assistant instance
   - Reviewing safety/permission implications
 ---
-<!-- {% raw %} -->
 # Building a personal assistant with CLAWDBOT (Clawd-style)
 
 CLAWDBOT is a WhatsApp + Telegram + Discord gateway for **Pi** agents. This guide is the “personal assistant” setup: one dedicated WhatsApp number that behaves like your always-on agent.
@@ -148,12 +147,13 @@ Example:
 - 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)
 
 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` (exact token), CLAWDBOT suppresses outbound delivery for that heartbeat.
+- If the agent replies with `HEARTBEAT_OK` (optionally with short padding; see `agent.heartbeat.ackMaxChars`), CLAWDBOT suppresses outbound delivery for that heartbeat.
 
 ```json5
 {
@@ -194,6 +194,9 @@ Logs live under `/tmp/clawdbot/` (default: `clawdbot-YYYY-MM-DD.log`).
 - WebChat: [WebChat](./webchat.md)
 - Gateway ops: [Gateway runbook](./gateway.md)
 - Cron + wakeups: [Cron + wakeups](./cron.md)
-- macOS menu bar companion: [Clawdbot macOS app](./clawdbot-mac.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)
-<!-- {% endraw %} -->

docs/configuration.md

@@ -3,7 +3,6 @@ summary: "All configuration options for ~/.clawdbot/clawdbot.json with examples"
 read_when:
   - Adding or modifying config fields
 ---
-<!-- {% raw %} -->
 # Configuration 🔧
 
 CLAWDBOT reads an optional **JSON5** config from `~/.clawdbot/clawdbot.json` (comments + trailing commas allowed).
@@ -60,13 +59,80 @@ To prevent the bot from responding to WhatsApp @-mentions in groups (only respon
 
 ## Common options
 
+### Env vars + `.env`
+
+CLAWDBOT reads env vars from the parent process (shell, launchd/systemd, CI, etc.).
+
+Additionally, it loads:
+- `.env` from the current working directory (if present)
+- a global fallback `.env` from `~/.clawdbot/.env` (aka `$CLAWDBOT_STATE_DIR/.env`)
+
+Neither `.env` file overrides existing env vars.
+
+### `env.shellEnv` (optional)
+
+Opt-in convenience: if enabled and none of the expected keys are set yet, CLAWDBOT runs your login shell and imports only the missing expected keys (never overrides).
+This effectively sources your shell profile.
+
+```json5
+{
+  env: {
+    shellEnv: {
+      enabled: true,
+      timeoutMs: 15000
+    }
+  }
+}
+```
+
+Env var equivalent:
+- `CLAWDBOT_LOAD_SHELL_ENV=1`
+- `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000`
+
+### Auth storage (OAuth + API keys)
+
+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:
+- `~/.clawdbot/agent/auth.json` (managed automatically; don’t edit manually)
+
+Overrides:
+- OAuth dir (legacy import only): `CLAWDBOT_OAUTH_DIR`
+- Agent dir: `CLAWDBOT_AGENT_DIR` (preferred), `PI_CODING_AGENT_DIR` (legacy)
+
+On first use, Clawdbot imports `oauth.json` entries into `auth-profiles.json`.
+
+### `auth`
+
+Optional metadata for auth profiles. This does **not** store secrets; it maps
+profile IDs to a provider + mode (and optional email) and defines the provider
+rotation order used for failover.
+
+```json5
+{
+  auth: {
+    profiles: {
+      "anthropic:default": { provider: "anthropic", mode: "oauth", email: "me@example.com" },
+      "anthropic:work": { provider: "anthropic", mode: "api_key" }
+    },
+    order: {
+      anthropic: ["anthropic:default", "anthropic:work"]
+    }
+  }
+}
+```
+
 ### `identity`
 
 Optional agent identity used for defaults and UX. This is written by the macOS onboarding assistant.
 
 If set, CLAWDBOT derives defaults (only when you haven’t set them explicitly):
 - `messages.responsePrefix` from `identity.emoji`
-- `routing.groupChat.mentionPatterns` from `identity.name` (so “@Samantha” works in groups)
+- `routing.groupChat.mentionPatterns` from `identity.name` (so “@Samantha” works in groups across Telegram/Slack/Discord/iMessage/WhatsApp)
 
 ```json5
 {
@@ -82,7 +148,7 @@ Metadata written by CLI wizards (`onboard`, `configure`, `doctor`, `update`).
 {
   wizard: {
     lastRunAt: "2026-01-01T00:00:00.000Z",
-    lastRunVersion: "2.0.0-beta5",
+    lastRunVersion: "2026.1.4",
     lastRunCommit: "abc1234",
     lastRunCommand: "configure",
     lastRunMode: "local"
@@ -97,6 +163,9 @@ Metadata written by CLI wizards (`onboard`, `configure`, `doctor`, `update`).
 - Console output can be tuned separately via:
   - `logging.consoleLevel` (defaults to `info`, bumps to `debug` when `--verbose`)
   - `logging.consoleStyle` (`pretty` | `compact` | `json`)
+- Tool summaries can be redacted to avoid leaking secrets:
+  - `logging.redactSensitive` (`off` | `tools`, default: `tools`)
+  - `logging.redactPatterns` (array of regex strings; overrides defaults)
 
 ```json5
 {
@@ -104,7 +173,13 @@ Metadata written by CLI wizards (`onboard`, `configure`, `doctor`, `update`).
     level: "info",
     file: "/tmp/clawdbot/clawdbot.log",
     consoleLevel: "info",
-    consoleStyle: "pretty"
+    consoleStyle: "pretty",
+    redactSensitive: "tools",
+    redactPatterns: [
+      // Example: override defaults with your own rules.
+      "\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1",
+      "/\\bsk-[A-Za-z0-9_-]{8,}\\b/gi"
+    ]
   }
 }
 ```
@@ -130,6 +205,7 @@ Group messages default to **require mention** (either metadata mention or regex
 **Mention types:**
 - **Metadata mentions**: Native platform @-mentions (e.g., WhatsApp tap-to-mention). Ignored in WhatsApp self-chat mode (see `whatsapp.allowFrom`).
 - **Text patterns**: Regex patterns defined in `mentionPatterns`. Always checked regardless of self-chat mode.
+- Mention gating is enforced only when mention detection is possible (native mentions or at least one `mentionPattern`).
 
 ```json5
 {
@@ -388,20 +464,33 @@ Default: `~/clawd`.
 If `agent.sandbox` is enabled, non-main sessions can override this with their
 own per-session workspaces under `agent.sandbox.workspaceRoot`.
 
+### `agent.userTimezone`
+
+Sets the user’s timezone for **system prompt context** (not for timestamps in
+message envelopes). If unset, Clawdbot uses the host timezone at runtime.
+
+```json5
+{
+  agent: { userTimezone: "America/Chicago" }
+}
+```
+
 ### `messages`
 
-Controls inbound/outbound prefixes and timestamps.
+Controls inbound/outbound prefixes.
 
 ```json5
 {
   messages: {
     messagePrefix: "[clawdbot]",
-    responsePrefix: "🦞",
-    timestampPrefix: "Europe/London"
+    responsePrefix: "🦞"
   }
 }
 ```
 
+`responsePrefix` is applied to **all outbound replies** (tool summaries, block
+streaming, final replies) across providers unless already present.
+
 ### `talk`
 
 Defaults for Talk mode (macOS/iOS/Android). Voice IDs fall back to `ELEVENLABS_VOICE_ID` or `SAG_VOICE_ID` when unset.
@@ -427,27 +516,43 @@ Defaults for Talk mode (macOS/iOS/Android). Voice IDs fall back to `ELEVENLABS_V
 ### `agent`
 
 Controls the embedded agent runtime (model/thinking/verbose/timeouts).
-`allowedModels` lets `/model` list/filter and enforce a per-session allowlist
-(omit to show the full catalog).
-`modelAliases` adds short names for `/model` (alias -> provider/model).
-`modelFallbacks` lists ordered fallback models to try when the default fails.
+`agent.models` defines the configured model catalog (and acts as the allowlist for `/model`).
+`agent.model.primary` sets the default model; `agent.model.fallbacks` are global failovers.
+`agent.imageModel` is optional and is **only used if the primary model lacks image input**.
+
+Clawdbot also ships a few built-in alias shorthands. Defaults only apply when the model
+is already present in `agent.models`:
+
+- `opus` -> `anthropic/claude-opus-4-5`
+- `sonnet` -> `anthropic/claude-sonnet-4-5`
+- `gpt` -> `openai/gpt-5.2`
+- `gpt-mini` -> `openai/gpt-5-mini`
+- `gemini` -> `google/gemini-3-pro-preview`
+- `gemini-flash` -> `google/gemini-3-flash-preview`
+
+If you configure the same alias name (case-insensitive) yourself, your value wins (defaults never override).
 
 ```json5
 {
   agent: {
-    model: "anthropic/claude-opus-4-5",
-    allowedModels: [
-      "anthropic/claude-opus-4-5",
-      "anthropic/claude-sonnet-4-1"
-    ],
-    modelAliases: {
-      Opus: "anthropic/claude-opus-4-5",
-      Sonnet: "anthropic/claude-sonnet-4-1"
+    models: {
+      "anthropic/claude-opus-4-5": { alias: "Opus" },
+      "anthropic/claude-sonnet-4-1": { alias: "Sonnet" },
+      "openrouter/deepseek/deepseek-r1:free": {}
+    },
+    model: {
+      primary: "anthropic/claude-opus-4-5",
+      fallbacks: [
+        "openrouter/deepseek/deepseek-r1:free",
+        "openrouter/meta-llama/llama-3.3-70b-instruct:free"
+      ]
+    },
+    imageModel: {
+      primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
+      fallbacks: [
+        "openrouter/google/gemini-2.0-flash-vision:free"
+      ]
     },
-    modelFallbacks: [
-      "openrouter/deepseek/deepseek-r1:free",
-      "openrouter/meta-llama/llama-3.3-70b-instruct:free"
-    ],
     thinkingDefault: "low",
     verboseDefault: "off",
     elevatedDefault: "on",
@@ -482,8 +587,8 @@ Block streaming:
   }
   ```
 
-`agent.model` should be set as `provider/model` (e.g. `anthropic/claude-opus-4-5`).
-If `modelAliases` is configured, you may also use the alias key (e.g. `Opus`).
+`agent.model.primary` should be set as `provider/model` (e.g. `anthropic/claude-opus-4-5`).
+Aliases come from `agent.models.*.alias` (e.g. `Opus`).
 If you omit the provider, CLAWDBOT currently assumes `anthropic` as a temporary
 deprecation fallback.
 Z.AI models are available as `zai/<model>` (e.g. `zai/glm-4.7`) and require
@@ -496,12 +601,27 @@ Z.AI models are available as `zai/<model>` (e.g. `zai/glm-4.7`) and require
 - `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).
 
 `agent.bash` configures background bash defaults:
 - `backgroundMs`: time before auto-background (ms, default 10000)
 - `timeoutSec`: auto-kill after this runtime (seconds, default 1800)
 - `cleanupMs`: how long to keep finished sessions in memory (ms, default 1800000)
 
+`agent.tools` configures a global tool allow/deny policy (deny wins).
+This is applied even when the Docker sandbox is **off**.
+
+Example (disable browser/canvas everywhere):
+```json5
+{
+  agent: {
+    tools: {
+      deny: ["browser", "canvas"]
+    }
+  }
+}
+```
+
 `agent.elevated` controls elevated (host) bash access:
 - `enabled`: allow elevated mode (default true)
 - `allowFrom`: per-surface allowlists (empty = disabled)
@@ -630,11 +750,16 @@ When `models.providers` is present, Clawdbot writes/merges a `models.json` into
 - default behavior: **merge** (keeps existing providers, overrides on name)
 - set `models.mode: "replace"` to overwrite the file contents
 
-Select the model via `agent.model` (provider/model).
+Select the model via `agent.model.primary` (provider/model).
 
 ```json5
 {
-  agent: { model: "custom-proxy/llama-3.1-8b" },
+  agent: {
+    model: { primary: "custom-proxy/llama-3.1-8b" },
+    models: {
+      "custom-proxy/llama-3.1-8b": {}
+    }
+  },
   models: {
     mode: "merge",
     providers: {
@@ -667,14 +792,10 @@ via **LM Studio** using the **Responses API**.
 ```json5
 {
   agent: {
-    model: "Minimax",
-    allowedModels: [
-      "anthropic/claude-opus-4-5",
-      "lmstudio/minimax-m2.1-gs32"
-    ],
-    modelAliases: {
-      Opus: "anthropic/claude-opus-4-5",
-      Minimax: "lmstudio/minimax-m2.1-gs32"
+    model: { primary: "lmstudio/minimax-m2.1-gs32" },
+    models: {
+      "anthropic/claude-opus-4-5": { alias: "Opus" },
+      "lmstudio/minimax-m2.1-gs32": { alias: "Minimax" }
     }
   },
   models: {
@@ -956,10 +1077,16 @@ Requires full Gateway restart:
 
 To run multiple gateways on one host, isolate per-instance state + config and use unique ports:
 - `CLAWDBOT_CONFIG_PATH` (per-instance config)
-- `CLAWDBOT_STATE_DIR` (sessions/creds/logs)
+- `CLAWDBOT_STATE_DIR` (sessions/creds)
 - `agent.workspace` (memories)
 - `gateway.port` (unique per instance)
 
+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` for the derived port mapping (gateway/bridge/browser/canvas).
+
 Example:
 ```bash
 CLAWDBOT_CONFIG_PATH=~/.clawdbot/a.json \
@@ -1168,4 +1295,3 @@ Cron is a Gateway-owned scheduler for wakeups and scheduled jobs. See [Cron + wa
 ---
 
 *Next: [Agent Runtime](./agent.md)* 🦞
-<!-- {% endraw %} -->

docs/cron.md

@@ -216,6 +216,17 @@ Retention:
 
 Each log line includes (at minimum) job id, status/error, timing, and a `summary` string (systemEvent text for main jobs, and the last agent text output for isolated jobs).
 
+## Compatibility policy (cron.add/cron.update)
+
+To keep older clients working, the Gateway applies **best-effort normalization** for `cron.add` and `cron.update`:
+- Accepts wrapped payloads under `data` or `job` and unwraps them.
+- Infers `schedule.kind` from `atMs`, `everyMs`, or `expr` if missing.
+- Infers `payload.kind` from `text` (systemEvent) or `message` (agentTurn) if missing.
+- Defaults `wakeMode` to `"next-heartbeat"` when omitted.
+- Defaults `sessionTarget` based on payload kind (`systemEvent` → `"main"`, `agentTurn` → `"isolated"`).
+
+Normalization is **compat-only**. New clients should send the full schema (including `kind`, `sessionTarget`, and `wakeMode`) to avoid ambiguity. Unknown fields are still rejected by schema validation.
+
 ## Gateway API
 
 New methods (names can be bikeshed; `cron.*` is suggested):
@@ -264,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] [--channel last|whatsapp|telegram|discord|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>`

docs/discord.md

@@ -35,6 +35,111 @@ Note: Discord does not provide a simple username → id lookup without extra gui
 Note: Slugs are lowercase with spaces replaced by `-`. Channel names are slugged without the leading `#`.
 Note: Guild context `[from:]` lines include `author.tag` + `id` to make ping-ready replies easy.
 
+## How to create your own bot
+
+This is the “Discord Developer Portal” setup for running Clawdbot in a server (guild) channel like `#help`.
+
+### 1) Create the Discord app + bot user
+1. Discord Developer Portal → **Applications** → **New Application**
+2. In your app:
+   - **Bot** → **Add Bot**
+   - Copy the **Bot Token** (this is what you put in `DISCORD_BOT_TOKEN`)
+
+### 2) Enable the gateway intents Clawdbot needs
+Discord blocks “privileged intents” unless you explicitly enable them.
+
+In **Bot** → **Privileged Gateway Intents**, enable:
+- **Message Content Intent** (required to read message text in most guilds; without it you’ll see “Used disallowed intents” or the bot will connect but not react to messages)
+- **Server Members Intent** (recommended; required for some member/user lookups and allowlist matching in guilds)
+
+You usually do **not** need **Presence Intent**.
+
+### 3) Generate an invite URL (OAuth2 URL Generator)
+In your app: **OAuth2** → **URL Generator**
+
+**Scopes**
+- ✅ `bot`
+- ✅ `applications.commands` (only if you want slash commands; otherwise leave unchecked)
+
+**Bot Permissions** (minimal baseline)
+- ✅ View Channels
+- ✅ Send Messages
+- ✅ Read Message History
+- ✅ Embed Links
+- ✅ Attach Files
+- ✅ Add Reactions (optional but recommended)
+- ✅ Use External Emojis / Stickers (optional; only if you want them)
+
+Avoid **Administrator** unless you’re debugging and fully trust the bot.
+
+Copy the generated URL, open it, pick your server, and install the bot.
+
+### 4) Get the ids (guild/user/channel)
+Discord uses numeric ids everywhere; Clawdbot config prefers ids.
+
+1. Discord (desktop/web) → **User Settings** → **Advanced** → enable **Developer Mode**
+2. Right-click:
+   - Server name → **Copy Server ID** (guild id)
+   - Channel (e.g. `#help`) → **Copy Channel ID**
+   - Your user → **Copy User ID**
+
+### 5) Configure Clawdbot
+
+#### Token
+Set the bot token via env var (recommended on servers):
+- `DISCORD_BOT_TOKEN=...`
+
+Or via config:
+
+```json5
+{
+  discord: {
+    enabled: true,
+    token: "YOUR_BOT_TOKEN"
+  }
+}
+```
+
+#### Allowlist + channel routing
+Example “single server, only allow me, only allow #help”:
+
+```json5
+{
+  discord: {
+    enabled: true,
+    dm: { enabled: false },
+    guilds: {
+      "YOUR_GUILD_ID": {
+        users: ["YOUR_USER_ID"],
+        requireMention: true,
+        channels: {
+          help: { allow: true, requireMention: true }
+        }
+      }
+    }
+  }
+}
+```
+
+Notes:
+- `requireMention: true` means the bot only replies when mentioned (recommended for shared channels).
+- `routing.groupChat.mentionPatterns` also count as mentions for guild messages.
+- If `channels` is present, any channel not listed is denied by default.
+
+### 6) Verify it works
+1. Start the gateway.
+2. In your server channel, send: `@Krill hello` (or whatever your bot name is).
+3. If nothing happens: check **Troubleshooting** below.
+
+### Troubleshooting
+- **“Used disallowed intents”**: enable **Message Content Intent** (and likely **Server Members Intent**) in the Developer Portal, then restart the gateway.
+- **Bot connects but never replies in a guild channel**:
+  - Missing **Message Content Intent**, or
+  - 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` 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).
 - Typing indicators sent best-effort; message chunking honors Discord’s 2k character limit.

docs/docker.md

@@ -59,6 +59,12 @@ docker compose exec clawdbot-gateway node dist/index.js health --token "$CLAWDBO
 scripts/e2e/onboard-docker.sh
 ```
 
+### QR import smoke test (Docker)
+
+```bash
+pnpm test:docker:qr
+```
+
 ### Notes
 
 - Gateway bind defaults to `lan` for container use.
@@ -73,6 +79,7 @@ container. The gateway stays on your host, but the tool execution is isolated:
 - one container per session (hard wall)
 - per-session workspace folder mounted at `/workspace`
 - allow/deny tool policy (deny wins)
+- inbound media is copied into the sandbox workspace (`media/inbound/*`) so tools can read it
 
 ### Default behavior
 

docs/docs.json

@@ -26,12 +26,22 @@
         "group": "Getting Started",
         "pages": [
           "index",
+          "showcase",
+          "hubs",
           "onboarding",
-          "wizard",
           "clawd",
           "faq"
         ]
       },
+      {
+        "group": "Installation",
+        "pages": [
+          "wizard",
+          "nix",
+          "docker",
+          "setup"
+        ]
+      },
       {
         "group": "Core Concepts",
         "pages": [
@@ -62,8 +72,9 @@
           "mac/dev-setup",
           "mac/menu-bar",
           "mac/voicewake",
-          "ios/connect",
-          "android/connect",
+          "macos",
+          "ios",
+          "android",
           "webchat",
           "web"
         ]

docs/doctor.md

@@ -15,6 +15,7 @@ read_when:
 - Migrates legacy `~/.clawdis/clawdis.json` when no Clawdbot config exists.
 - 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).
 
 ## 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.
@@ -26,8 +27,13 @@ Doctor will:
 - Show the migration it applied.
 - Rewrite `~/.clawdbot/clawdbot.json` with the updated schema.
 
+The Gateway also auto-runs doctor migrations on startup when it detects a legacy
+config format, so stale configs are repaired without manual intervention.
+
 Current migrations:
 - `routing.allowFrom` → `whatsapp.allowFrom`
+- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
+  → `agent.models` + `agent.model.primary/fallbacks` + `agent.imageModel.primary/fallbacks`
 
 ## Usage
 

docs/faq.md

@@ -14,6 +14,9 @@ Everything lives under `~/.clawdbot/`:
 | Path | Purpose |
 |------|---------|
 | `~/.clawdbot/clawdbot.json` | Main config (JSON5) |
+| `~/.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 |
@@ -40,10 +43,10 @@ Some features are platform-specific:
 - **CPU:** 1 core is fine for personal use
 - **Disk:** ~500MB for Clawdbot + deps, plus space for logs/media
 
-The gateway is just shuffling messages around. A Raspberry Pi 4 can run it. You can also use **Bun** instead of Node for even lower memory footprint:
+The gateway is just shuffling messages around. A Raspberry Pi 4 can run it. For the CLI, prefer the Node runtime (most stable):
 
 ```bash
-bun clawdbot gateway
+pnpm clawdbot gateway
 ```
 
 ### How do I install on Linux without Homebrew?
@@ -76,7 +79,7 @@ This creates `~/.clawdbot/clawdbot.json` with your API keys, workspace path, and
 cp -r ~/.clawdbot ~/.clawdbot-backup
 
 # Remove config and credentials
-rm -rf ~/.clawdbot
+trash ~/.clawdbot
 
 # Re-run onboarding
 pnpm clawdbot onboard
@@ -105,18 +108,36 @@ The macOS app onboarding is still being polished and can have quirks (e.g., What
 
 ### OAuth vs API key — what's the difference?
 
-- **OAuth** — Uses your Claude Pro/Max subscription ($20-100/mo flat). No per-token charges. ✅ Recommended!
-- **API key** — Pay-per-token via console.anthropic.com. Can get expensive fast.
+- **OAuth** — Uses your **subscription** (Anthropic Claude Pro/Max or OpenAI ChatGPT/Codex). No per‑token charges. ✅ Recommended!
+- **API key** — Pay‑per‑token via the provider’s API billing. Can get expensive fast.
 
 They're **separate billing**! An API key does NOT use your subscription.
 
-**For OAuth:** During onboarding, pick "Anthropic OAuth", log in to your Claude account, paste the code back. Or just run:
+**For OAuth:** During onboarding, pick **Anthropic OAuth** or **OpenAI Codex OAuth**, log in, paste the code/URL when prompted. Or just run:
 
 ```bash
 pnpm clawdbot login
 ```
 
-**If OAuth fails** (headless/container): Do OAuth on a normal machine, then copy `~/.clawdbot/` to your server. The auth is just a JSON file.
+**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?
+
+CLAWDBOT reads env vars from the parent process (shell, launchd/systemd, CI, etc.). It also loads `.env` files:
+- `.env` in the current working directory
+- global fallback: `~/.clawdbot/.env` (aka `$CLAWDBOT_STATE_DIR/.env`)
+
+Neither `.env` file overrides existing env vars.
+
+Optional convenience: import missing expected keys from your login shell env (sources your shell profile):
+
+```json5
+{
+  env: { shellEnv: { enabled: true, timeoutMs: 15000 } }
+}
+```
+
+Or set `CLAWDBOT_LOAD_SHELL_ENV=1` (timeout: `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000`).
 
 ### Does enterprise OAuth work?
 
@@ -128,7 +149,7 @@ pnpm clawdbot login
 
 OAuth needs the callback to reach the machine running the CLI. Options:
 
-1. **Copy auth manually** — Run OAuth on your laptop, copy `~/.clawdbot/credentials/` to the container.
+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.
 
@@ -209,7 +230,7 @@ Yes! The terminal QR code login works fine over SSH. For long-running operation:
 ### bun binary vs Node runtime?
 
 Clawdbot can run as:
-- **bun binary** — Single executable, easy distribution, auto-restarts via launchd
+- **bun binary (macOS app)** — Single executable, easy distribution, auto-restarts via launchd
 - **Node runtime** (`pnpm clawdbot gateway`) — More stable for WhatsApp
 
 If you see WebSocket errors like `ws.WebSocket 'upgrade' event is not implemented`, use Node instead of the bun binary. Bun's WebSocket implementation has edge cases that can break WhatsApp (Baileys).
@@ -281,7 +302,7 @@ Claude Opus has a 200k token context window, and Clawdbot uses **autocompaction*
 
 Practical tips:
 - Keep `AGENTS.md` focused, not bloated.
-- Use `/new` to reset the session when context gets stale.
+- Use `/compact` to shrink older context or `/new` to reset when it gets stale.
 - For large memory/notes collections, use search tools like `qmd` rather than loading everything.
 
 ### Where are my memory files?
@@ -446,37 +467,75 @@ cd ~/path/to/clawdbot
 codex --full-auto "debug why clawdbot gateway won't start"
 ```
 
-### Processes keep restarting after I kill them (Linux)
+### Gateway stops after I log out (Linux)
 
-Something is supervising them. Check:
+Linux installs use a systemd **user** service. By default, systemd stops user
+services on logout/idle, which kills the Gateway.
 
+Onboarding attempts to enable lingering; if it’s still off, run:
 ```bash
-# systemd?
-systemctl list-units | grep -i clawdbot
-sudo systemctl stop clawdbot
-
-# pm2?
-pm2 list
-pm2 delete all
+sudo loginctl enable-linger $USER
 ```
 
-Stop the supervisor first, then the processes.
+**macOS/Windows**
+
+Gateway daemons run in the user session by default. Keep the user logged in.
+Headless/system services are not configured out of the box.
+
+### Processes keep restarting after I kill them
+
+The gateway runs under a supervisor that auto-restarts it. You need to stop the supervisor, not just kill the process.
+
+**macOS (launchd)**
+
+```bash
+# Check if running
+launchctl list | grep clawdbot
+
+# 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
+```
+
+**Linux (systemd)**
+
+```bash
+# Check if running
+systemctl list-units | grep -i clawdbot
+
+# Stop and disable
+sudo systemctl disable --now clawdbot
+```
+
+**pm2 (if used)**
+
+```bash
+pm2 list
+pm2 delete clawdbot
+```
 
 ### Clean uninstall (start fresh)
 
 ```bash
-# Stop processes
+# macOS: stop launchd service
+launchctl disable gui/$UID/com.clawdbot.gateway
+launchctl bootout gui/$UID/com.clawdbot.gateway 2>/dev/null
+
+# Linux: stop systemd service
+sudo systemctl disable --now clawdbot
+
+# Kill any remaining processes
 pkill -f "clawdbot"
 
-# If using systemd
-sudo systemctl stop clawdbot
-sudo systemctl disable clawdbot
-
 # Remove data
-rm -rf ~/.clawdbot
+trash ~/.clawdbot
 
 # Remove repo and re-clone
-rm -rf ~/clawdbot
+trash ~/clawdbot
 git clone https://github.com/clawdbot/clawdbot.git
 cd clawdbot && pnpm install && pnpm build
 pnpm clawdbot onboard
@@ -492,6 +551,9 @@ Quick reference (send these in chat):
 |---------|--------|
 | `/status` | Health + session info |
 | `/new` or `/reset` | Reset the session |
+| `/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) |
@@ -507,23 +569,27 @@ Use `/model` to switch without restarting:
 /model sonnet
 /model haiku
 /model opus
+/model gpt
+/model gpt-mini
+/model gemini
+/model gemini-flash
 ```
 
-**Setup:** Configure allowed models and aliases in `clawdbot.json`:
+List available models with `/model`, `/model list`, or `/model status`.
+
+Clawdbot ships a few default model shorthands (you can override them in config):
+`opus`, `sonnet`, `gpt`, `gpt-mini`, `gemini`, `gemini-flash`.
+
+**Setup:** Configure models and aliases in `clawdbot.json`:
 
 ```json
 {
   "agent": {
-    "model": "anthropic/claude-opus-4-5-20251022",
-    "allowedModels": [
-      "anthropic/claude-opus-4-5-20251022",
-      "anthropic/claude-sonnet-4-5-20251022",
-      "anthropic/claude-haiku-4-5-20251001"
-    ],
-    "modelAliases": {
-      "opus": "anthropic/claude-opus-4-5-20251022",
-      "sonnet": "anthropic/claude-sonnet-4-5-20251022",
-      "haiku": "anthropic/claude-haiku-4-5-20251001"
+    "model": { "primary": "anthropic/claude-opus-4-5" },
+    "models": {
+      "anthropic/claude-opus-4-5": { "alias": "opus" },
+      "anthropic/claude-sonnet-4-5": { "alias": "sonnet" },
+      "anthropic/claude-haiku-4-5": { "alias": "haiku" }
     }
   }
 }
@@ -539,7 +605,8 @@ If you don't want to use Anthropic directly, you can use alternative providers:
 ```json5
 {
   agent: {
-    model: "openrouter/anthropic/claude-sonnet-4",
+    model: { primary: "openrouter/anthropic/claude-sonnet-4" },
+    models: { "openrouter/anthropic/claude-sonnet-4": {} },
     env: { OPENROUTER_API_KEY: "sk-or-..." }
   }
 }
@@ -549,7 +616,8 @@ If you don't want to use Anthropic directly, you can use alternative providers:
 ```json5
 {
   agent: {
-    model: "zai/glm-4.7",
+    model: { primary: "zai/glm-4.7" },
+    models: { "zai/glm-4.7": {} },
     env: { ZAI_API_KEY: "..." }
   }
 }

docs/gateway.md

@@ -49,6 +49,34 @@ pnpm gateway:watch
 
 Supported if you isolate state + config and use unique ports.
 
+### Dev profile (`--dev`)
+
+Fast path: run a fully-isolated dev instance (config/state/workspace) without touching your primary setup.
+
+```bash
+clawdbot --dev setup
+clawdbot --dev gateway --allow-unconfigured
+# then target the dev instance:
+clawdbot --dev status
+clawdbot --dev health
+```
+
+Defaults (can be overridden via env/flags/config):
+- `CLAWDBOT_STATE_DIR=~/.clawdbot-dev`
+- `CLAWDBOT_CONFIG_PATH=~/.clawdbot-dev/clawdbot.json`
+- `CLAWDBOT_GATEWAY_PORT=19001` (Gateway WS + HTTP)
+- `bridge.port=19002` (derived: `gateway.port+1`)
+- `browser.controlUrl=http://127.0.0.1:19003` (derived: `gateway.port+2`)
+- `canvasHost.port=19005` (derived: `gateway.port+4`)
+- `agent.workspace` default becomes `~/clawd-dev` when you run `setup`/`onboard` under `--dev`.
+
+Derived ports (rules of thumb):
+- Base port = `gateway.port` (or `CLAWDBOT_GATEWAY_PORT` / `--port`)
+- `bridge.port = base + 1` (or `CLAWDBOT_BRIDGE_PORT` / config override)
+- `browser.controlUrl port = base + 2` (or `CLAWDBOT_BROWSER_CONTROL_URL` / config override)
+- `canvasHost.port = base + 4` (or `CLAWDBOT_CANVAS_HOST_PORT` / config override)
+- Browser profile CDP ports auto-allocate from `browser.controlPort + 9 .. + 108` (persisted per profile).
+
 Checklist per instance:
 - unique `gateway.port`
 - unique `CLAWDBOT_CONFIG_PATH`
@@ -127,11 +155,13 @@ See also: `docs/presence.md` for how presence is produced/deduped and why `insta
   - KeepAlive: true
   - StandardOut/Err: file paths or `syslog`
 - On failure, launchd restarts; fatal misconfig should keep exiting so the operator notices.
+- LaunchAgents are per-user and require a logged-in session; for headless setups use a custom LaunchDaemon (not shipped).
 
 Bundled mac app:
 - Clawdbot.app can bundle a bun-compiled gateway binary and install a per-user LaunchAgent labeled `com.clawdbot.gateway`.
 
-## Supervision (systemd example)
+## Supervision (systemd user unit)
+Create `~/.config/systemd/user/clawdbot-gateway.service`:
 ```
 [Unit]
 Description=Clawdbot Gateway
@@ -140,16 +170,36 @@ Wants=network-online.target
 
 [Service]
 ExecStart=/usr/local/bin/clawdbot gateway --port 18789
-Restart=on-failure
+Restart=always
 RestartSec=5
-User=clawdbot
 Environment=CLAWDBOT_GATEWAY_TOKEN=
-WorkingDirectory=/home/clawdbot
+WorkingDirectory=/home/youruser
 
 [Install]
-WantedBy=multi-user.target
+WantedBy=default.target
 ```
-Enable with `systemctl enable --now clawdbot-gateway.service`.
+Enable lingering (required so the user service survives logout/idle):
+```
+sudo loginctl enable-linger youruser
+```
+Onboarding runs this on Linux (may prompt for sudo; writes `/var/lib/systemd/linger`).
+Then enable the service:
+```
+systemctl --user enable --now clawdbot-gateway.service
+```
+
+**Alternative (system service)** - for always-on or multi-user servers, you can
+install a systemd **system** unit instead of a user unit (no lingering needed).
+Create `/etc/systemd/system/clawdbot-gateway.service` (copy the unit above,
+switch `WantedBy=multi-user.target`, set `User=` + `WorkingDirectory=`), then:
+```
+sudo systemctl daemon-reload
+sudo systemctl enable --now clawdbot-gateway.service
+```
+
+## Supervision (Windows scheduled task)
+- Onboarding installs a Scheduled Task named `Clawdbot Gateway` (runs on user logon).
+- Requires a logged-in user session; for headless setups use a system service or a task configured to run without a logged-in user (not shipped).
 
 ## Operational checks
 - Liveness: open WS and send `req:connect` → expect `res` with `payload.type="hello-ok"` (with snapshot).

docs/group-messages.md

@@ -1,5 +1,5 @@
 ---
-summary: "Behavior and config for WhatsApp group message handling"
+summary: "Behavior and config for WhatsApp group message handling (mentionPatterns are shared across surfaces)"
 read_when:
   - Changing group message rules or mentions
 ---
@@ -7,6 +7,8 @@ read_when:
 
 Goal: let Clawd sit in WhatsApp groups, wake up only when pinged, and keep that thread separate from the personal DM session.
 
+Note: `routing.groupChat.mentionPatterns` is now used by Telegram/Discord/Slack/iMessage as well; this doc focuses on WhatsApp-specific behavior.
+
 ## 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`.
 - Group allowlist bypass: we still enforce `whatsapp.allowFrom` on the participant at inbox ingest, but group JIDs themselves no longer block replies.
@@ -56,7 +58,7 @@ Only the owner number (from `whatsapp.allowFrom`, defaulting to the bot’s own
 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`) apply only to that group’s session; 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).

docs/groups.md

@@ -51,6 +51,7 @@ Group messages require a mention unless overridden per group. Defaults live per
 Notes:
 - `mentionPatterns` are case-insensitive regexes.
 - Surfaces that provide explicit mentions still pass; patterns are a fallback.
+- Mention gating is only enforced when mention detection is possible (native mentions or `mentionPatterns` are configured).
 - Discord defaults live in `discord.guilds."*"` (overridable per guild/channel).
 
 ## Activation (owner-only)

docs/heartbeat.md

@@ -10,10 +10,10 @@ surface anything that needs attention without spamming the user.
 
 ## Prompt contract
 - Heartbeat body defaults to `HEARTBEAT` (configurable via `agent.heartbeat.prompt`).
-- If nothing needs attention, the model should reply **exactly** `HEARTBEAT_OK`.
+- 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 **≤ 30 characters**.
+  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.
 
@@ -22,6 +22,13 @@ If the model accidentally includes `HEARTBEAT_OK` at the start or end of a
 normal (non-heartbeat) reply, Clawdbot strips the token and logs a verbose
 message. If the reply is only `HEARTBEAT_OK`, it is dropped.
 
+### Outbound normalization (all providers)
+For **all providers** (WhatsApp/Web, Telegram, Slack, Discord, Signal, iMessage),
+Clawdbot applies the same filtering to tool summaries, streaming block replies,
+and final replies:
+- drop payloads that are only `HEARTBEAT_OK` with no media
+- strip `HEARTBEAT_OK` at the edges when mixed with other text
+
 ## Config
 
 ```json5
@@ -32,7 +39,8 @@ message. If the reply is only `HEARTBEAT_OK`, it is dropped.
       model: "anthropic/claude-opus-4-5",
       target: "last",          // last | whatsapp | telegram | none
       to: "+15551234567",      // optional override for whatsapp/telegram
-      prompt: "HEARTBEAT"      // optional override
+      prompt: "HEARTBEAT",     // optional override
+      ackMaxChars: 30          // max chars allowed after HEARTBEAT_OK
     }
   }
 }
@@ -48,6 +56,7 @@ message. If the reply is only `HEARTBEAT_OK`, it is dropped.
   - `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: `HEARTBEAT`).
+- `ackMaxChars`: max chars allowed after `HEARTBEAT_OK` before delivery (default: 30).
 
 ## Behavior
 - Runs in the main session (`main`, or `global` when scope is global).

docs/hubs.md

@@ -0,0 +1,148 @@
+---
+summary: "Hubs that link to every Clawdbot doc"
+read_when:
+  - You want a complete map of the documentation
+---
+# Docs hubs
+
+Use these hubs to discover every page, including deep dives and reference docs that don’t appear in the left nav.
+
+## Start here
+
+- [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](./docker.md)
+- [Nix](./nix.md)
+
+## Core concepts
+
+- [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](./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](./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](./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](./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](./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](./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](./onboarding-config-protocol.md)
+- [Research: memory](./research/memory.md)
+- [Proposal: model config](./proposals/model-config.md)
+
+## Testing + release
+
+- [Testing](./test.md)
+- [Release checklist](./RELEASING.md)
+- [Device models](./device-models.md)

docs/images.md

@@ -3,7 +3,6 @@ summary: "Image and media handling rules for send, gateway, and agent replies"
 read_when:
   - Modifying media pipeline or attachments
 ---
-<!-- {% raw %} -->
 # Image & Media Support — 2025-12-05
 
 CLAWDBOT is now **web-only** (Baileys). This document captures the current media handling rules for send, gateway, and agent replies.
@@ -38,6 +37,7 @@ CLAWDBOT is now **web-only** (Baileys). This document captures the current media
 - When inbound web messages include media, CLAWDBOT downloads to a temp file and exposes templating variables:
   - `{{MediaUrl}}` pseudo-URL for the inbound media.
   - `{{MediaPath}}` local temp path written before running the command.
+- When a per-session Docker sandbox is enabled, inbound media is copied into the sandbox workspace and `MediaPath`/`MediaUrl` are rewritten to a relative path like `media/inbound/<filename>`.
 - Audio transcription (if configured) runs before templating and can replace `Body` with the transcript.
 
 ## Limits & Errors
@@ -49,4 +49,3 @@ CLAWDBOT is now **web-only** (Baileys). This document captures the current media
 - Cover send + reply flows for image/audio/document cases.
 - Validate recompression for images (size bound) and voice-note flag for audio.
 - Ensure multi-media replies fan out as sequential sends.
-<!-- {% endraw %} -->

docs/imessage.md

@@ -55,7 +55,7 @@ imsg chats --limit 20
 
 ## Group chat behavior
 - Group messages set `ChatType=group`, `GroupSubject`, and `GroupMembers`.
-- Group activation respects `imessage.groups."*".requireMention` and `routing.groupChat.mentionPatterns`.
+- Group activation respects `imessage.groups."*".requireMention` and `routing.groupChat.mentionPatterns` (patterns are required to detect mentions on iMessage).
 - Replies go back to the same `chat_id` (group or direct).
 
 ## Troubleshooting

docs/index.md

@@ -3,23 +3,23 @@ summary: "Top-level overview of Clawdbot, features, and purpose"
 read_when:
   - Introducing Clawdbot to newcomers
 ---
-<!-- {% raw %} -->
 # CLAWDBOT 🦞
 
 > *"EXFOLIATE! EXFOLIATE!"* — A space lobster, probably
 
 <p align="center">
-  <img src="whatsapp-clawd.jpg" alt="CLAWDBOT" width="420">
+  <img src="whatsapp-clawd.jpg" alt="CLAWDBOT" width="420" />
 </p>
 
 <p align="center">
-  <strong>WhatsApp + Telegram + Discord + iMessage gateway for AI agents (Pi).</strong><br>
+  <strong>Any OS + WhatsApp/Telegram/Discord/iMessage gateway for AI agents (Pi).</strong><br />
   Send a message, get an agent response — from your pocket.
 </p>
 
 <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.clawdbot.com/">Docs</a> ·
   <a href="./clawd.md">Clawd setup</a>
 </p>
 
@@ -42,7 +42,8 @@ WhatsApp / Telegram / Discord
               ├─ CLI (clawdbot …)
               ├─ Chat UI (SwiftUI)
               ├─ macOS app (Clawdbot.app)
-              └─ iOS node via Bridge + pairing
+              ├─ iOS node via Bridge + pairing
+              └─ Android node via Bridge + pairing
 ```
 
 Most operations flow through the **Gateway** (`clawdbot gateway`), a single long-running process that owns provider connections and the WebSocket control plane.
@@ -63,12 +64,14 @@ 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
+- 🔐 **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`
 - 📎 **Media Support** — Send and receive images, audio, documents
 - 🎤 **Voice notes** — Optional transcription hook
 - 🖥️ **WebChat + macOS app** — Local UI + menu bar companion for ops and voice wake
 - 📱 **iOS node** — Pairs as a node and exposes a Canvas surface
+- 📱 **Android node** — Pairs as a node and exposes Canvas + Chat + Camera
 
 Note: legacy Claude/Codex/Gemini/Opencode paths have been removed; Pi is the only coding-agent path.
 
@@ -125,6 +128,7 @@ Example:
 ## Docs
 
 - Start here:
+  - [Docs hubs (all pages linked)](./hubs.md)
   - [FAQ](./faq.md) ← *common questions answered*
   - [Configuration](./configuration.md)
   - [Nix mode](./nix.md)
@@ -148,6 +152,12 @@ Example:
   - [WhatsApp group messages](./group-messages.md)
   - [Media: images](./images.md)
   - [Media: audio](./audio.md)
+- Companion apps:
+  - [macOS app](./macos.md)
+  - [iOS app](./ios.md)
+  - [Android app](./android.md)
+  - [Windows app](./windows.md)
+  - [Linux app](./linux.md)
 - Ops and safety:
   - [Sessions](./session.md)
   - [Cron + wakeups](./cron.md)
@@ -161,7 +171,6 @@ Example:
 ---
 
 *"We're all just playing with our own prompts."* — an AI, probably high on tokens
-<!-- {% endraw %} -->
 
 ## Credits
 

docs/ios.md

@@ -1,17 +1,182 @@
 ---
-summary: "Plan for an iOS voice + canvas node that connects via a secure Bonjour-discovered macOS bridge"
+summary: "iOS app (node): architecture + connection runbook"
 read_when:
+  - Pairing or reconnecting the iOS node
+  - Debugging iOS bridge discovery or auth
+  - Sending screen/canvas commands to iOS
   - Designing iOS node + gateway integration
   - Extending the Gateway protocol for node/canvas commands
   - Implementing Bonjour pairing or transport security
 ---
-# iOS Node (internal) — Voice Trigger + Canvas
+# iOS App (Node)
 
 Status: prototype implemented (internal) · Date: 2025-12-13
 
-Runbook (how to connect/pair + drive Canvas): `docs/ios/connect.md`
+## Connection Runbook
 
-## Goals
+This is the practical “how do I connect the iOS node” guide:
+
+**iOS app** ⇄ (Bonjour + TCP bridge) ⇄ **Gateway bridge** ⇄ (loopback WS) ⇄ **Gateway**
+
+The Gateway WebSocket stays loopback-only (`ws://127.0.0.1:18789`). The iOS node talks to the LAN-facing **bridge** (default `tcp://0.0.0.0:18790`) and uses Gateway-owned pairing.
+
+### Prerequisites
+
+- You can run the Gateway on the “master” machine.
+- iOS node app can reach the gateway bridge:
+  - Same LAN with Bonjour/mDNS, **or**
+  - Same Tailscale tailnet using Wide-Area Bonjour / unicast DNS-SD (see below), **or**
+  - Manual bridge host/port (fallback)
+- You can run the CLI (`clawdbot`) on the gateway machine (or via SSH).
+
+### 1) Start the Gateway (with bridge enabled)
+
+Bridge is enabled by default (disable via `CLAWDBOT_BRIDGE_ENABLED=0`).
+
+```bash
+pnpm clawdbot gateway --port 18789 --verbose
+```
+
+Confirm in logs you see something like:
+- `bridge listening on tcp://0.0.0.0:18790 (node)`
+
+For tailnet-only setups (recommended for Vienna ⇄ London), bind the bridge to the gateway machine’s Tailscale IP instead:
+
+- Set `bridge.bind: "tailnet"` in `~/.clawdbot/clawdbot.json` on the gateway host.
+- Restart the Gateway / macOS menubar app.
+
+### 2) Verify Bonjour discovery (optional but recommended)
+
+From the gateway machine:
+
+```bash
+dns-sd -B _clawdbot-bridge._tcp local.
+```
+
+You should see your gateway advertising `_clawdbot-bridge._tcp`.
+
+If browse works, but the iOS node can’t connect, try resolving one instance:
+
+```bash
+dns-sd -L "<instance name>" _clawdbot-bridge._tcp local.
+```
+
+More debugging notes: `docs/bonjour.md`.
+
+#### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD
+
+If the iOS node and the gateway are on different networks but connected via Tailscale, multicast mDNS won’t cross the boundary. Use Wide-Area Bonjour / unicast DNS-SD instead:
+
+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`.
+
+### 3) Connect from the iOS node app
+
+In the iOS node app:
+- Pick the discovered bridge (or hit refresh).
+- If not paired yet, it will initiate pairing automatically.
+- After the first successful pairing, it will auto-reconnect **strictly to the last discovered gateway** on launch (including after reinstall), as long as the iOS Keychain entry is still present.
+
+#### Connection indicator (always visible)
+
+The Settings tab icon shows a small status dot:
+- **Green**: connected to the bridge
+- **Yellow**: connecting (subtle pulse)
+- **Red**: not connected / error
+
+### 4) Approve pairing (CLI)
+
+On the gateway machine:
+
+```bash
+clawdbot nodes pending
+```
+
+Approve the request:
+
+```bash
+clawdbot nodes approve <requestId>
+```
+
+After approval, the iOS node receives/stores the token and reconnects authenticated.
+
+Pairing details: `docs/gateway/pairing.md`.
+
+### 5) Verify the node is connected
+
+- In the macOS app: **Instances** tab should show something like `iOS Node (...)` with a green “Active” presence dot shortly after connect.
+- Via nodes status (paired + connected):
+  ```bash
+  clawdbot nodes status
+  ```
+- Via Gateway (paired + connected):
+  ```bash
+  clawdbot gateway call node.list --params "{}"
+  ```
+- Via Gateway presence (legacy-ish, still useful):
+  ```bash
+  clawdbot gateway call system-presence --params "{}"
+  ```
+  Look for the node `instanceId` (often a UUID).
+
+### 6) Drive the iOS Canvas (draw / snapshot)
+
+The iOS node runs a WKWebView “Canvas” scaffold which exposes:
+- `window.__clawdbot.canvas`
+- `window.__clawdbot.ctx` (2D context)
+- `window.__clawdbot.setStatus(title, subtitle)`
+
+#### Gateway Canvas Host (recommended for web content)
+
+If you want the node to show real HTML/CSS/JS that the agent can edit on disk, point it at the Gateway canvas host.
+
+Note: nodes always use the standalone canvas host on `canvasHost.port` (default `18793`), bound to the bridge interface.
+
+1) Create `~/clawd/canvas/index.html` on the gateway host.
+
+2) Navigate the node to it (LAN):
+
+```bash
+clawdbot nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18793/__clawdbot__/canvas/"}'
+```
+
+Notes:
+- The server injects a live-reload client into HTML and reloads on file changes.
+- A2UI is hosted on the same canvas host at `http://<gateway-host>:18793/__clawdbot__/a2ui/`.
+- Tailnet (optional): if both devices are on Tailscale, use a MagicDNS name or tailnet IP instead of `.local`, e.g. `http://<gateway-magicdns>:18793/__clawdbot__/canvas/`.
+- iOS may require App Transport Security allowances to load plain `http://` URLs; if it fails to load, prefer HTTPS or adjust the iOS app’s ATS config.
+
+#### Draw with `canvas.eval`
+
+```bash
+clawdbot nodes invoke --node "iOS Node" --command canvas.eval --params "$(cat <<'JSON'
+{"javaScript":"(() => { const {ctx,setStatus} = window.__clawdbot; setStatus('Drawing','…'); ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle='#ff2d55'; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); setStatus(null,null); return 'ok'; })()"}
+JSON
+)"
+```
+
+#### Snapshot with `canvas.snapshot`
+
+```bash
+clawdbot nodes invoke --node 192.168.0.88 --command canvas.snapshot --params '{"maxWidth":900}'
+```
+
+The response includes `{ format, base64 }` image data (default `format="jpeg"`; pass `{"format":"png"}` when you specifically need lossless PNG).
+
+### Common gotchas
+
+- **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`).
+- **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.
+
+## Design + Architecture
+
+### Goals
 - Build an **iOS app** that acts as a **remote node** for Clawdbot:
   - **Voice trigger** (wake-word / always-listening intent) that forwards transcripts to the Gateway `agent` method.
   - **Canvas** surface that the agent can control: navigate, draw/render, evaluate JS, snapshot.
@@ -28,13 +193,13 @@ Non-goals (v1):
 - Supporting arbitrary third-party “plugins” on iOS.
 - Perfect App Store compliance; this is **internal-only** initially.
 
-## Current repo reality (constraints we respect)
+### Current repo reality (constraints we respect)
 - 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
+### Recommended topology (B): Gateway-owned Bridge + loopback Gateway
 Keep the Node gateway loopback-only; expose a dedicated **gateway-owned bridge** to the LAN/tailnet.
 
 **iOS App** ⇄ (TLS + pairing) ⇄ **Bridge (in gateway)** ⇄ (loopback) ⇄ **Gateway WS** (`ws://127.0.0.1:18789`)
@@ -44,12 +209,12 @@ Why:
 - Centralizes auth, rate limiting, and allowlisting in the bridge.
 - Lets us unify “canvas node” semantics across mac + iOS without exposing raw gateway methods.
 
-## Security plan (internal, but still robust)
-### Transport
+### Security plan (internal, but still robust)
+#### Transport
 - **Current (v0):** bridge is a LAN-facing **TCP** listener with token-based auth after pairing.
 - **Next:** wrap the bridge in **TLS** and prefer key-pinned or mTLS-like auth after pairing.
 
-### Pairing
+#### Pairing
 - Bonjour discovery shows a candidate “Clawdbot Bridge” on the LAN.
 - First connection:
   1) iOS generates a keypair (Secure Enclave if available).
@@ -62,7 +227,7 @@ Why:
 - Subsequent connections:
   - The bridge requires the paired identity. Unpaired clients get a structured “not paired” error and no access.
 
-#### Gateway-owned pairing (Option B details)
+##### Gateway-owned pairing (Option B details)
 Pairing decisions must be owned by the Gateway (`clawd` / Node) so nodes can be approved without the macOS app running.
 
 Key idea:
@@ -79,7 +244,7 @@ CLI (headless approvals):
 - `clawdbot nodes approve <requestId>`
 - `clawdbot nodes reject <requestId>`
 
-### Authorization / scope control (bridge-side ACL)
+#### Authorization / scope control (bridge-side ACL)
 The bridge must not be a raw proxy to every gateway method.
 
 - Allow by default:
@@ -93,15 +258,15 @@ The bridge must not be a raw proxy to every gateway method.
   - voice forwards per minute
   - snapshot frequency / payload size
 
-## Protocol unification: add “node/canvas” to Gateway protocol
-### Principle
+### Protocol unification: add “node/canvas” to Gateway protocol
+#### Principle
 Unify mac Canvas + iOS Canvas under a single conceptual surface:
 - The agent talks to the Gateway using a stable method set (typed protocol).
 - The Gateway routes node-targeted requests to:
   - local mac Canvas implementation, or
   - remote iOS node via the bridge
 
-### Minimal protocol additions (v1)
+#### Minimal protocol additions (v1)
 Add to `src/gateway/protocol/schema.ts` (and regenerate Swift models):
 
 **Identity**
@@ -117,7 +282,7 @@ Add to `src/gateway/protocol/schema.ts` (and regenerate Swift models):
 - `node.event` → async node status/errors
   - e.g. background/foreground transitions, voice availability, canvas availability
 
-### Node command set (canvas)
+#### Node command set (canvas)
 These are values for `node.invoke.command`:
 - `canvas.present` / `canvas.hide`
 - `canvas.navigate` with `{ url }` (loads a URL; use `""` or `"/"` to return to the default scaffold)
@@ -133,7 +298,7 @@ Result pattern:
 - Request is a standard `req/res` with `ok` / `error`.
 - Long operations (loads, streaming drawing, etc.) may also emit `node.event` progress.
 
-#### Current (implemented)
+##### Current (implemented)
 As of 2025-12-13, the Gateway supports `node.invoke` for bridge-connected nodes.
 
 Example: draw a diagonal line on the iOS Canvas:
@@ -199,38 +364,9 @@ open Clawdbot.xcodeproj
 - Credentials:
   - Keychain (paired identity + bridge trust anchor)
 
-### macOS
-- Keep current Canvas root (already implemented):
-  - `~/Library/Application Support/Clawdbot/canvas/<session>/...`
-- Bridge state:
-  - No local pairing store (pairing is gateway-owned).
-  - Any local bridge-only state should remain private under Application Support.
+## Related docs
 
-### Gateway (node)
-- Pairing (source of truth):
-  - `~/.clawdbot/nodes/paired.json`
-  - `~/.clawdbot/nodes/pending.json` (or `pending/*.json` for auditability)
-
-## Rollout plan (phased)
-1) **Bridge discovery + pairing (mac + iOS)**
-  - Bonjour browse + resolve
-  - Approve prompt on mac
-  - Persist pairing in Keychain/App Support
-2) **Voice-only node**
-   - iOS voice wake toggle
-   - Forward transcript to Gateway `agent` via bridge
-   - Presence beacons via `system-event` (or node.event)
-3) **Protocol additions for nodes**
-   - Add `node.list` / `node.invoke` / `node.event` to Gateway
-   - Implement bridge routing + ACLs
-4) **iOS canvas**
-   - WKWebView canvas surface
-   - `canvas.navigate/eval/snapshot`
-   - Background fast-fail for `canvas.*`
-5) **Unify mac Canvas under the same node.invoke**
-   - Keep existing implementation, but expose it through the unified protocol path so the agent uses one API.
-
-## Open questions
-- Should `connect.params.client.mode` be `"node"` with `platform="ios ..."` or a distinct mode `"ios-node"`? (Presence filtering currently excludes `"cli"` only.)
-- Do we want a “permissions” model per node (voice only vs voice+canvas) at pairing time?
-- Should loading arbitrary websites via `canvas.navigate` allow any https URL, or enforce an allowlist to reduce risk?
+- `docs/gateway.md` (gateway runbook)
+- `docs/gateway/pairing.md` (approval + storage)
+- `docs/bonjour.md` (discovery debugging)
+- `docs/discovery.md` (LAN vs tailnet vs SSH)

docs/ios/connect.md

@@ -1,177 +0,0 @@
----
-summary: "Runbook: connect/pair the iOS node to a Clawdbot Gateway and drive its Canvas"
-read_when:
-  - Pairing or reconnecting the iOS node
-  - Debugging iOS bridge discovery or auth
-  - Sending screen/canvas commands to iOS
----
-
-# iOS Node Connection Runbook
-
-This is the practical “how do I connect the iOS node” guide:
-
-**iOS app** ⇄ (Bonjour + TCP bridge) ⇄ **Gateway bridge** ⇄ (loopback WS) ⇄ **Gateway**
-
-The Gateway WebSocket stays loopback-only (`ws://127.0.0.1:18789`). The iOS node talks to the LAN-facing **bridge** (default `tcp://0.0.0.0:18790`) and uses Gateway-owned pairing.
-
-## Prerequisites
-
-- You can run the Gateway on the “master” machine.
-- iOS node app can reach the gateway bridge:
-  - Same LAN with Bonjour/mDNS, **or**
-  - Same Tailscale tailnet using Wide-Area Bonjour / unicast DNS-SD (see below), **or**
-  - Manual bridge host/port (fallback)
-- You can run the CLI (`clawdbot`) on the gateway machine (or via SSH).
-
-## 1) Start the Gateway (with bridge enabled)
-
-Bridge is enabled by default (disable via `CLAWDBOT_BRIDGE_ENABLED=0`).
-
-```bash
-pnpm clawdbot gateway --port 18789 --verbose
-```
-
-Confirm in logs you see something like:
-- `bridge listening on tcp://0.0.0.0:18790 (node)`
-
-For tailnet-only setups (recommended for Vienna ⇄ London), bind the bridge to the gateway machine’s Tailscale IP instead:
-
-- Set `bridge.bind: "tailnet"` in `~/.clawdbot/clawdbot.json` on the gateway host.
-- Restart the Gateway / macOS menubar app.
-
-## 2) Verify Bonjour discovery (optional but recommended)
-
-From the gateway machine:
-
-```bash
-dns-sd -B _clawdbot-bridge._tcp local.
-```
-
-You should see your gateway advertising `_clawdbot-bridge._tcp`.
-
-If browse works, but the iOS node can’t connect, try resolving one instance:
-
-```bash
-dns-sd -L "<instance name>" _clawdbot-bridge._tcp local.
-```
-
-More debugging notes: `docs/bonjour.md`.
-
-### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD
-
-If the iOS node and the gateway are on different networks but connected via Tailscale, multicast mDNS won’t cross the boundary. Use Wide-Area Bonjour / unicast DNS-SD instead:
-
-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`.
-
-## 3) Connect from the iOS node app
-
-In the iOS node app:
-- Pick the discovered bridge (or hit refresh).
-- If not paired yet, it will initiate pairing automatically.
-- After the first successful pairing, it will auto-reconnect **strictly to the last discovered gateway** on launch (including after reinstall), as long as the iOS Keychain entry is still present.
-
-### Connection indicator (always visible)
-
-The Settings tab icon shows a small status dot:
-- **Green**: connected to the bridge
-- **Yellow**: connecting (subtle pulse)
-- **Red**: not connected / error
-
-## 4) Approve pairing (CLI)
-
-On the gateway machine:
-
-```bash
-clawdbot nodes pending
-```
-
-Approve the request:
-
-```bash
-clawdbot nodes approve <requestId>
-```
-
-After approval, the iOS node receives/stores the token and reconnects authenticated.
-
-Pairing details: `docs/gateway/pairing.md`.
-
-## 5) Verify the node is connected
-
-- In the macOS app: **Instances** tab should show something like `iOS Node (...)` with a green “Active” presence dot shortly after connect.
-- Via nodes status (paired + connected):
-  ```bash
-  clawdbot nodes status
-  ```
-- Via Gateway (paired + connected):
-  ```bash
-  clawdbot gateway call node.list --params "{}"
-  ```
-- Via Gateway presence (legacy-ish, still useful):
-  ```bash
-  clawdbot gateway call system-presence --params "{}"
-  ```
-  Look for the node `instanceId` (often a UUID).
-
-## 6) Drive the iOS Canvas (draw / snapshot)
-
-The iOS node runs a WKWebView “Canvas” scaffold which exposes:
-- `window.__clawdbot.canvas`
-- `window.__clawdbot.ctx` (2D context)
-- `window.__clawdbot.setStatus(title, subtitle)`
-
-### Gateway Canvas Host (recommended for web content)
-
-If you want the node to show real HTML/CSS/JS that the agent can edit on disk, point it at the Gateway canvas host.
-
-Note: nodes always use the standalone canvas host on `canvasHost.port` (default `18793`), bound to the bridge interface.
-
-1) Create `~/clawd/canvas/index.html` on the gateway host.
-
-2) Navigate the node to it (LAN):
-
-```bash
-clawdbot nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18793/__clawdbot__/canvas/"}'
-```
-
-Notes:
-- The server injects a live-reload client into HTML and reloads on file changes.
-- A2UI is hosted on the same canvas host at `http://<gateway-host>:18793/__clawdbot__/a2ui/`.
-- Tailnet (optional): if both devices are on Tailscale, use a MagicDNS name or tailnet IP instead of `.local`, e.g. `http://<gateway-magicdns>:18793/__clawdbot__/canvas/`.
-- iOS may require App Transport Security allowances to load plain `http://` URLs; if it fails to load, prefer HTTPS or adjust the iOS app’s ATS config.
-
-### Draw with `canvas.eval`
-
-```bash
-clawdbot nodes invoke --node "iOS Node" --command canvas.eval --params "$(cat <<'JSON'
-{"javaScript":"(() => { const {ctx,setStatus} = window.__clawdbot; setStatus('Drawing','…'); ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle='#ff2d55'; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); setStatus(null,null); return 'ok'; })()"}
-JSON
-)"
-```
-
-### Snapshot with `canvas.snapshot`
-
-```bash
-clawdbot nodes invoke --node 192.168.0.88 --command canvas.snapshot --params '{"maxWidth":900}'
-```
-
-The response includes `{ format, base64 }` image data (default `format="jpeg"`; pass `{"format":"png"}` when you specifically need lossless PNG).
-
-## Common gotchas
-
-- **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`).
-- **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.
-
-## Related docs
-
-- `docs/ios/spec.md` (design + architecture)
-- `docs/gateway.md` (gateway runbook)
-- `docs/gateway/pairing.md` (approval + storage)
-- `docs/bonjour.md` (discovery debugging)
-- `docs/discovery.md` (LAN vs tailnet vs SSH)

docs/linux.md

@@ -0,0 +1,11 @@
+---
+summary: "Linux app status + contribution call"
+read_when:
+  - Looking for Linux companion app status
+  - Planning platform coverage or contributions
+---
+# Linux App
+
+Clawdbot core is fully supported on Linux. The core is written in TypeScript, so it runs anywhere Node runs.
+
+We do not have a Linux companion app yet. It is planned, and we would love contributions to make it happen.

docs/logging.md

@@ -42,6 +42,17 @@ You can tune console verbosity independently via:
 - `logging.consoleLevel` (default `info`)
 - `logging.consoleStyle` (`pretty` | `compact` | `json`)
 
+## Tool summary redaction
+
+Verbose tool summaries (e.g. `🛠️ bash: ...`) can mask sensitive tokens before they hit the
+console stream. This is **tools-only** and does not alter file logs.
+
+- `logging.redactSensitive`: `off` | `tools` (default: `tools`)
+- `logging.redactPatterns`: array of regex strings (overrides defaults)
+  - Use raw regex strings (auto `gi`), or `/pattern/flags` if you need custom flags.
+  - Matches are masked by keeping the first 6 + last 4 chars (length >= 18), otherwise `***`.
+  - Defaults cover common key assignments, CLI flags, JSON fields, bearer headers, PEM blocks, and popular token prefixes.
+
 ## Gateway WebSocket logs
 
 The gateway prints WebSocket protocol logs in two modes:

docs/mac/canvas.md

@@ -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/clawdbot-mac.md`.
+- 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)
 

docs/mac/icon.md

@@ -23,4 +23,4 @@ Shapes & sizes
 
 Behavioral notes
 - No external CLI/broker toggle for ears/working; keep it internal to the app’s own signals to avoid accidental flapping.
-- Keep TTLs short (<10s) so the icon returns to baseline quickly if a job hangs.
+- Keep TTLs short (&lt;10s) so the icon returns to baseline quickly if a job hangs.

docs/mac/peekaboo.md

@@ -23,7 +23,7 @@ Peekaboo’s privileged execution moved from “CLI → XPC helper” to “CLI
 - It lets us piggyback on **either** Peekaboo.app’s permissions **or** Clawdbot.app’s permissions (whichever is running).
 - It avoids “two apps with two TCC bubbles” unless needed.
 
-Reference (Peekaboo submodule): `docs/bridge-host.md`.
+Reference (Peekaboo submodule): `Peekaboo/docs/bridge-host.md`.
 
 ## Architecture
 ### Processes

docs/mac/release.md

@@ -23,7 +23,7 @@ This app now ships Sparkle auto-updates. Release builds must be Developer ID–s
 ## Build & package
 Notes:
 - `APP_BUILD` maps to `CFBundleVersion`/`sparkle:version`; keep it numeric + monotonic (no `-beta`), or Sparkle compares it as equal.
-- Universal by default (`arm64 x86_64`). Override with `BUILD_ARCHS="arm64"` if you need arm-only.
+- Defaults to the current architecture (`$(uname -m)`). For release/universal builds, set `BUILD_ARCHS="arm64 x86_64"` (or `BUILD_ARCHS=all`).
 
 ```bash
 # From repo root; set release IDs so Sparkle feed is enabled.

docs/macos.md

@@ -94,7 +94,7 @@ Notes:
 - In remote mode, Clawdbot will use the configured remote tunnel/endpoint.
 
 ## Build & dev workflow (native)
-- `cd native && swift build` (debug) / `swift build -c release`.
+- `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` (builds bun CLI + gateway).
 - Tests: add Swift Testing suites under `apps/macos/Tests`.

docs/models.md

@@ -16,29 +16,32 @@ that prefers tool-call + image-capable models and maintains ordered fallbacks.
   - default: configured models only
   - flags: `--all` (full catalog), `--local`, `--provider <name>`, `--json`, `--plain`
 - `clawdbot models status`
-  - show default model + aliases + fallbacks + allowlist
+  - show default model + aliases + fallbacks + configured models
 - `clawdbot models set <modelOrAlias>`
-  - writes `agent.model` in config
+  - writes `agent.model.primary` and ensures `agent.models` entry
+- `clawdbot models set-image <modelOrAlias>`
+  - writes `agent.imageModel.primary` and ensures `agent.models` entry
 - `clawdbot models aliases list|add|remove`
-  - writes `agent.modelAliases`
+  - writes `agent.models.*.alias`
 - `clawdbot models fallbacks list|add|remove|clear`
-  - writes `agent.modelFallbacks`
+  - writes `agent.model.fallbacks`
+- `clawdbot models image-fallbacks list|add|remove|clear`
+  - writes `agent.imageModel.fallbacks`
 - `clawdbot models scan`
   - OpenRouter :free scan; probe tool-call + image; interactive selection
 
 ## Config changes
 
-- Add `agent.modelFallbacks: string[]` (ordered list of provider/model IDs).
-- Keep existing:
-  - `agent.model` (default)
-  - `agent.allowedModels` (list filter)
-  - `agent.modelAliases` (shortcut names)
+- `agent.models` (configured model catalog + aliases).
+- `agent.model.primary` + `agent.model.fallbacks`.
+- `agent.imageModel.primary` + `agent.imageModel.fallbacks` (optional).
+- `auth.profiles` + `auth.order` for per-provider auth failover.
 
 ## Scan behavior (models scan)
 
 Input
 - OpenRouter `/models` list (filter `:free`)
-- Requires `OPENROUTER_API_KEY` (or stored OpenRouter key in auth storage)
+- Requires OpenRouter API key from auth profiles or `OPENROUTER_API_KEY`
 - Optional filters: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates`
 - Probe controls: `--timeout`, `--concurrency`
 
@@ -49,8 +52,8 @@ Probes (direct pi-ai complete)
   - Prompt includes 1x1 PNG; success if no "unsupported image" error.
 
 Scoring/selection
-- Prefer models passing tool + image.
-- Fallback to tool-only if no tool+image pass.
+- Prefer models passing tool + image for text/tool fallbacks.
+- Prefer image-only models for image tool fallback (even if tool probe fails).
 - Rank by: image ok, then lower tool latency, then larger context, then params.
 
 Interactive selection (TTY)
@@ -60,15 +63,20 @@ Interactive selection (TTY)
 - Non-TTY: auto-select; require `--yes`/`--no-input` to apply.
 
 Output
-- Writes `agent.modelFallbacks` ordered.
-- Optional `--set-default` to set `agent.model`.
+- Writes `agent.model.fallbacks` ordered.
+- Writes `agent.imageModel.fallbacks` ordered (image-capable models).
+- Ensures `agent.models` entries exist for selected models.
+- Optional `--set-default` to set `agent.model.primary`.
+- Optional `--set-image` to set `agent.imageModel.primary`.
 
 ## Runtime fallback
 
-- On model failure: try `agent.modelFallbacks` in order.
-- Ignore fallback entries not in `agent.allowedModels` (if allowlist set).
-- Persist last successful provider/model to session entry.
-- `/status` shows last used model (not just default).
+- On model failure: try `agent.model.fallbacks` in order.
+- Per-provider auth failover uses `auth.order` (or stored profile order) **before**
+  moving to the next model.
+- 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.
 
 ## Tests
 
@@ -78,5 +86,5 @@ Output
 
 ## Docs
 
-- Update `docs/configuration.md` with `agent.modelFallbacks`.
+- Update `docs/configuration.md` with `agent.models` + `agent.model` + `agent.imageModel`.
 - Keep this doc current when CLI surface or scan logic changes.

docs/nix.md

@@ -1,26 +1,66 @@
 ---
-summary: "Running Clawdbot under Nix (config, state, and packaging expectations)"
+summary: "Install Clawdbot declaratively with Nix"
 read_when:
-  - Building Clawdbot with Nix
-  - Debugging Nix-mode behavior
+  - You want reproducible, rollback-able installs
+  - You're already using Nix/NixOS/Home Manager
+  - You want everything pinned and managed declaratively
 ---
-# Nix mode
+
+# Nix Installation
+
+The recommended way to run Clawdbot with Nix is via **[nix-clawdbot](https://github.com/clawdbot/nix-clawdbot)** — a batteries-included Home Manager module.
+
+## Quick Start
+
+Paste this to your AI agent (Claude, Cursor, etc.):
+
+```text
+I want to set up nix-clawdbot on my Mac.
+Repository: github:clawdbot/nix-clawdbot
+
+What I need you to do:
+1. Check if Determinate Nix is installed (if not, install it)
+2. Create a local flake at ~/code/clawdbot-local using templates/agent-first/flake.nix
+3. Help me create a Telegram bot (@BotFather) and get my chat ID (@userinfobot)
+4. Set up secrets (bot token, Anthropic key) - plain files at ~/.secrets/ is fine
+5. Fill in the template placeholders and run home-manager switch
+6. Verify: launchd running, bot responds to messages
+
+Reference the nix-clawdbot README for module options.
+```
+
+> **📦 Full guide: [github.com/clawdbot/nix-clawdbot](https://github.com/clawdbot/nix-clawdbot)**
+>
+> The nix-clawdbot repo is the source of truth for Nix installation. This page is just a quick overview.
+
+## What you get
+
+- Gateway + macOS app + tools (whisper, spotify, cameras) — all pinned
+- Launchd service that survives reboots
+- Plugin system with declarative config
+- Instant rollback: `home-manager switch --rollback`
+
+---
+
+## Nix Mode Runtime Behavior
+
+When `CLAWDBOT_NIX_MODE=1` is set (automatic with nix-clawdbot):
 
 Clawdbot supports a **Nix mode** that makes configuration deterministic and disables auto-install flows.
 Enable it by exporting:
 
-```
+```bash
 CLAWDBOT_NIX_MODE=1
 ```
 
 On macOS, the GUI app does not automatically inherit shell env vars. You can
 also enable Nix mode via defaults:
 
-```
+```bash
 defaults write com.clawdbot.mac clawdbot.nixMode -bool true
 ```
 
-## Config + state paths
+### Config + state paths
 
 Clawdbot reads JSON5 config from `CLAWDBOT_CONFIG_PATH` and stores mutable data in `CLAWDBOT_STATE_DIR`.
 
@@ -30,11 +70,11 @@ Clawdbot reads JSON5 config from `CLAWDBOT_CONFIG_PATH` and stores mutable data
 When running under Nix, set these explicitly to Nix-managed locations so runtime state and config
 stay out of the immutable store.
 
-## Runtime behavior in Nix mode
+### Runtime behavior in Nix mode
 
-- Auto-install and self-mutation flows should be disabled.
-- Missing dependencies should surface Nix-specific remediation messages.
-- UI surfaces a read-only Nix mode banner when present.
+- Auto-install and self-mutation flows are disabled
+- Missing dependencies surface Nix-specific remediation messages
+- UI surfaces a read-only Nix mode banner when present
 
 ## Packaging note (macOS)
 
@@ -47,3 +87,9 @@ apps/macos/Sources/Clawdbot/Resources/Info.plist
 `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](./wizard.md) — non-Nix CLI setup
+- [Docker](./docker.md) — containerized setup

docs/onboarding-config-protocol.md

@@ -1,3 +1,8 @@
+---
+summary: "RPC protocol notes for onboarding wizard and config schema"
+read_when: "Changing onboarding wizard steps or config schema endpoints"
+---
+
 # Onboarding + Config Protocol
 
 Purpose: shared onboarding + config surfaces across CLI, macOS app, and Web UI.

docs/onboarding.md

@@ -1,18 +1,17 @@
 ---
-summary: "Planned first-run onboarding flow for Clawdbot (local vs remote, Anthropic OAuth, workspace bootstrap ritual)"
+summary: "Planned first-run onboarding flow for Clawdbot (local vs remote, OAuth auth, workspace bootstrap ritual)"
 read_when:
   - Designing the macOS onboarding assistant
-  - Implementing Anthropic auth or identity setup
+  - Implementing Anthropic/OpenAI auth or identity setup
 ---
-<!-- {% raw %} -->
 # Onboarding (macOS app)
 
-This doc describes the intended **first-run onboarding** for Clawdbot. The goal is a good “day 0” experience: pick where the Gateway runs, bind Claude (Anthropic) auth for the embedded agent runtime, and then let the **agent bootstrap itself** via a first-run ritual in the workspace.
+This doc describes the intended **first-run onboarding** for Clawdbot. The goal is a good “day 0” experience: pick where the Gateway runs, bind subscription auth (Anthropic or OpenAI) for the embedded agent runtime, and then let the **agent bootstrap itself** via a first-run ritual in the workspace.
 
 ## Page order (high level)
 
 1) **Local vs Remote**
-2) **(Local only)** Connect Claude (Anthropic OAuth) — optional, but recommended
+2) **(Local only)** Connect subscription auth (Anthropic / OpenAI OAuth) — optional, but recommended
 3) **Connect Gmail (optional)** — run `clawdbot hooks gmail setup` to configure Pub/Sub hooks
 4) **Onboarding chat** — dedicated session where the agent introduces itself and guides setup
 
@@ -20,7 +19,7 @@ This doc describes the intended **first-run onboarding** for Clawdbot. The goal
 
 First question: where does the **Gateway** run?
 
-- **Local (this Mac):** onboarding can run the Anthropic OAuth flow and write the Clawdbot token store locally.
+- **Local (this Mac):** onboarding can run OAuth flows and write OAuth credentials locally.
 - **Remote (over SSH/tailnet):** onboarding must not run OAuth locally, because credentials must exist on the **gateway host**.
 
 Gateway auth tip:
@@ -29,11 +28,11 @@ Gateway auth tip:
 
 Implementation note (2025-12-19): in local mode, the macOS app bundles the Gateway and enables it via a per-user launchd LaunchAgent (no global npm install/Node requirement for the user).
 
-## 2) Local-only: Connect Claude (Anthropic OAuth)
+## 2) Local-only: Connect subscription auth (Anthropic / OpenAI OAuth)
 
-This is the “bind Clawdbot to Anthropic” step. It is explicitly the **Anthropic (Claude Pro/Max) OAuth flow**, not a generic “login”.
+This is the “bind Clawdbot to subscription auth” step. It is explicitly the **Anthropic (Claude Pro/Max)** or **OpenAI (ChatGPT/Codex)** OAuth flow, not a generic “login”.
 
-### Recommended: OAuth
+### Recommended: OAuth (Anthropic)
 
 The macOS app should:
 - Start the Anthropic OAuth (PKCE) flow in the user’s browser.
@@ -42,7 +41,16 @@ 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.
-On first run, Clawdbot can import existing OAuth tokens from legacy p/Claude locations if present.
+Clawdbot also imports `oauth.json` into the agent auth profile store (`~/.clawdbot/agent/auth-profiles.json`) on first use.
+
+### Recommended: OAuth (OpenAI Codex)
+
+The macOS app should:
+- Start the OpenAI Codex OAuth (PKCE) flow in the user’s browser.
+- Auto-capture the callback on `http://127.0.0.1:1455/auth/callback` when possible.
+- If the callback fails, prompt the user to paste the redirect URL or code.
+- Store credentials in `~/.clawdbot/credentials/oauth.json` (same OAuth store as Anthropic).
+- Set `agent.model` to `openai-codex/gpt-5.2` when the model is unset or `openai/*`.
 
 ### Alternative: API key (instructions only)
 
@@ -95,7 +103,7 @@ Once setup is complete, the user can switch to the normal chat (`main`) via the
 
 We no longer collect identity in the onboarding wizard. Instead, the **first agent run** performs a playful bootstrap ritual using files in the workspace:
 
-- Workspace is created implicitly (default `~/.clawdbot/workspace`) when local is selected,
+- Workspace is created implicitly (default `~/clawd`, configurable via `agent.workspace`) when local is selected,
   but only if the folder is empty or already contains `AGENTS.md`.
 - Files are seeded: `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`.
 - `BOOTSTRAP.md` tells the agent to keep it conversational:
@@ -124,7 +132,7 @@ The workspace is created automatically as part of agent bootstrap (no dedicated
 Recommendation: treat the workspace as the agent’s “memory” and make it a git repo (ideally private) so identity + memories are backed up:
 
 ```bash
-cd ~/.clawdbot/workspace
+cd ~/clawd
 git init
 git add AGENTS.md
 git commit -m "Add agent workspace"
@@ -137,11 +145,11 @@ Daily memory lives under `memory/` in the workspace:
 
 ## Remote mode note (why OAuth is hidden)
 
-If the Gateway runs on another machine, the Anthropic OAuth credentials must be created/stored on that host (where the agent runtime runs).
+If the Gateway runs on another machine, OAuth credentials must be created/stored on that host (where the agent runtime runs).
 
 For now, remote onboarding should:
 - explain why OAuth isn't shown
-- point the user at the credential location (`~/.clawdbot/credentials/oauth.json`) and the workspace location 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
@@ -150,17 +158,14 @@ On the gateway host, create `~/.clawdbot/credentials/oauth.json` with this exact
 
 ```json
 {
-  "anthropic": {
-    "access": "sk-ant-oat01-...",
-    "refresh": "sk-ant-ort01-...",
-    "expires": 1767304352803
-  }
+  "anthropic": { "type": "oauth", "access": "sk-ant-oat01-...", "refresh": "sk-ant-ort01-...", "expires": 1767304352803 },
+  "openai-codex": { "type": "oauth", "access": "eyJhbGciOi...", "refresh": "oai-refresh-...", "expires": 1767304352803, "accountId": "acct_..." }
 }
 ```
 
 Set permissions: `chmod 600 ~/.clawdbot/credentials/oauth.json`
 
-**Note:** Clawdbot can auto-import from legacy pi-coding-agent paths (`~/.pi/agent/oauth.json`, etc.) but this does NOT work with Claude Code credentials — different file and format.
+**Note:** Clawdbot auto-imports from legacy pi-coding-agent paths (`~/.pi/agent/oauth.json`, etc.) but this does NOT work with Claude Code credentials — different file and format.
 
 ### Using Claude Code credentials
 
@@ -182,4 +187,3 @@ chmod 600 ~/.clawdbot/credentials/oauth.json
 | `accessToken` | `access` |
 | `refreshToken` | `refresh` |
 | `expiresAt` | `expires` |
-<!-- {% endraw %} -->

docs/plans/cron-add-hardening.md

@@ -0,0 +1,72 @@
+---
+summary: "Harden cron.add input handling, align schemas, and improve cron UI/agent tooling"
+owner: "clawdbot"
+status: "complete"
+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 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 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.
+
+## Non-goals
+- Change cron scheduling semantics or job execution behavior.
+- Add new schedule kinds or cron expression parsing.
+- Overhaul the UI/UX for cron beyond the necessary field fixes.
+
+## Findings (current gaps)
+- `CronPayloadSchema` in gateway excludes `signal` + `imessage`, while TS types include them.
+- Control UI CronStatus expects `jobCount`, but gateway returns `jobs`.
+- Agent cron tool schema allows arbitrary `job` objects, enabling malformed inputs.
+- Gateway strictly validates `cron.add` with no normalization, so wrapped payloads fail.
+
+## 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** 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` 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 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`).
+- [x] Apply normalization in gateway `cron.add` (and patch normalization in `cron.update`).
+- [x] Tighten agent cron tool schema to `CronAddParamsSchema` and normalize job/patch before sending.
+
+### Phase 3 — Tests
+- [x] Add gateway test covering wrapped `cron.add` payload normalization.
+- [x] Add cron tool test to assert normalization and defaulting for `cron.add`.
+- [x] Add gateway test covering `cron.update` normalization.
+- [x] Add UI + Swift conformance test for cron channels + status fields.
+
+### Phase 4 — Verification
+- [x] Run tests (full suite executed via `pnpm test -- cron-tool`).
+
+## Rollout/Monitoring
+- Watch gateway logs for reduced `cron.add` INVALID_REQUEST errors.
+- Confirm Control UI cron status shows job count after refresh.
+- 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 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 channel (currently filtered in delivery resolution)?

docs/proposals/model-config.md

@@ -0,0 +1,147 @@
+---
+summary: "Proposal: model config, auth profiles, and fallback behavior"
+read_when:
+  - Designing model selection, auth profiles, or fallback behavior
+  - Migrating model config schema
+---
+
+# Model config proposal
+
+Goals
+- Multi OAuth + multi API key per provider
+- Model selection via `/model` with sensible fallback
+- Global (not per-session) fallback logic
+- Keep last-known-good auth profile when switching models
+- Profile override only when explicitly requested
+- Image routing override only when explicitly configured
+
+Non-goals (v1)
+- Auto-discovery of provider capabilities beyond catalog input tags
+- Per-model auth profile order (see open questions)
+
+## Proposed config shape
+
+```json
+{
+  "auth": {
+    "profiles": {
+      "anthropic:default": {
+        "provider": "anthropic",
+        "mode": "oauth"
+      },
+      "anthropic:work": {
+        "provider": "anthropic",
+        "mode": "api_key"
+      },
+      "openai:default": {
+        "provider": "openai",
+        "mode": "oauth"
+      }
+    },
+    "order": {
+      "anthropic": ["anthropic:default", "anthropic:work"],
+      "openai": ["openai:default"]
+    }
+  },
+  "agent": {
+    "models": {
+      "anthropic/claude-opus-4-5": {
+        "alias": "Opus"
+      },
+      "openai/gpt-5.2": {
+        "alias": "gpt52"
+      }
+    },
+    "model": {
+      "primary": "anthropic/claude-opus-4-5",
+      "fallbacks": ["openai/gpt-5.2"]
+    },
+    "imageModel": {
+      "primary": "openai/gpt-5.2",
+      "fallbacks": ["anthropic/claude-opus-4-5"]
+    }
+  }
+}
+```
+
+Notes
+- Canonical model keys are full `provider/model`.
+- `alias` optional; used by `/model` resolution.
+- `auth.profiles` is keyed. Default CLI login creates `provider:default`.
+- `auth.order[provider]` controls rotation order for that provider.
+
+## CLI / UX
+
+Login
+- `clawdbot login anthropic` → create/replace `anthropic:default`.
+- `clawdbot login anthropic --profile work` → create/replace `anthropic:work`.
+
+Model selection
+- `/model Opus` → resolve alias to full id.
+- `/model anthropic/claude-opus-4-5` → explicit.
+- Optional: `/model Opus@anthropic:work` (explicit profile override for session only).
+
+Model listing
+- `/model` list shows:
+  - model id
+  - alias
+  - provider
+  - auth order (from `auth.order`)
+  - auth source for the current provider (auth-profiles.json/env/shell env/models.json)
+
+## Fallback behavior (global)
+
+Fallback list
+- Use `agent.model.fallbacks` globally.
+- No per-session fallback list; last-known-good is per-session but uses global ordering.
+
+Auth profile rotation
+- If provider auth error (401/403/invalid refresh):
+  - advance to next profile in `auth.order[provider]`.
+  - if all fail, fall back to next model.
+
+Rate limiting
+- If rate limit / quota error:
+  - rotate auth profile first (same provider)
+  - if still failing, fall back to next model.
+
+Model not found / capability mismatch
+- immediate model fallback.
+
+## Image routing
+
+Rule
+- Only use `agent.imageModel` when explicitly configured.
+- If `agent.imageModel` is configured and the current text model lacks image input, use it.
+
+Support detection
+- From model catalog `input` tags when available (e.g. `image` in models.json).
+- If unknown: treat as text-only and use `agent.imageModel`.
+
+## Migration (doctor + gateway auto-run)
+
+Inputs
+- Legacy keys (pre-migration):
+  - `agent.model` (string)
+  - `agent.modelFallbacks` (string[])
+  - `agent.imageModel` (string)
+  - `agent.imageModelFallbacks` (string[])
+  - `agent.allowedModels` (string[])
+  - `agent.modelAliases` (record)
+
+Outputs
+- `agent.models` map with keys for all referenced models
+- `agent.model.primary/fallbacks`
+- `agent.imageModel.primary/fallbacks`
+- Auth profile store seeded from current auth-profiles.json/auth.json + oauth.json + env (as `provider:default`)
+- `auth.order` seeded with `["provider:default"]` when config is updated
+
+Auto-run
+- Gateway start detects legacy keys and runs doctor migration.
+
+## Decisions
+
+- Auth order is per-provider (`auth.order`).
+- Doctor migration is required; gateway will auto-run on startup when legacy keys detected.
+- `/model Opus@profile` is explicit session override only.
+- Image routing override only when `agent.imageModel` is explicitly configured.

docs/refactor/browser-control-simplification.md

@@ -1,58 +0,0 @@
----
-summary: "Refactor: simplify browser control API + implementation"
-read_when:
-  - Refactoring browser control routes, client, or CLI
-  - Auditing agent-facing browser tool surface
-date: 2025-12-20
----
-
-# Refactor: Browser control simplification
-
-Goal: make the browser-control surface **small, stable, and agent-oriented**, and remove “implementation-shaped” APIs (Playwright/CDP specifics, one-off endpoints, and debugging helpers).
-
-## Why
-
-- The previous API accreted many narrow endpoints (`/click`, `/type`, `/press`, …) plus debug utilities.
-- Some actions are inherently racy when modeled as “do X *when* the event is already visible” (file chooser, dialogs).
-- We want a single, coherent contract that keeps “how it’s implemented” private.
-
-## Target contract (vNext)
-
-**Basics**
-- `GET /` status
-- `POST /start`, `POST /stop`
-- `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId`
-
-**Agent actions**
-- `POST /navigate` `{ url, targetId? }`
-- `POST /act` `{ kind, targetId?, ... }` where `kind` is one of:
-  - `click`, `type`, `press`, `hover`, `drag`, `select`, `fill`, `wait`, `resize`, `close`, `evaluate`
-- `POST /screenshot` `{ targetId?, fullPage?, ref?, element?, type? }`
-- `GET /snapshot` `?format=ai|aria&targetId?&limit?`
-- `GET /console` `?level?&targetId?`
-- `POST /pdf` `{ targetId? }`
-
-**Hooks (pre-setup / arming)**
-- `POST /hooks/file-chooser` `{ targetId?, paths, timeoutMs? }`
-- `POST /hooks/dialog` `{ targetId?, accept, promptText?, timeoutMs? }`
-
-Semantics:
-- Hook endpoints **arm** the next matching event within `timeoutMs` (default 2 minutes, clamped to max 2 minutes).
-- Last arm wins per page (new arm replaces previous).
-
-## Work checklist
-
-- [x] Replace action endpoints with `POST /act`
-- [x] Remove legacy endpoints (`/click`, `/type`, `/wait`, …) and any CLI wrappers that no longer make sense
-- [x] Remove `/back` and any history-specific routes
-- [x] Convert `upload` + `dialog` to hook/arming endpoints
-- [x] Unify screenshots behind `POST /screenshot` (no GET variant)
-- [x] Trim inspect/debug endpoints (`/query`, `/dom`) unless explicitly needed
-- [x] Update docs/browser.md to describe contract without implementation details
-- [x] Update tests (server + client) to cover vNext contract
-
-## Notes / decisions
-
-- Keep Playwright as an internal implementation detail for now.
-- Prefer ref-based interactions (`aria-ref`) over coordinate-based ones.
-- Keep the code split “routes vs. engine” small and obvious; avoid scattering logic across too many files.

docs/refactor/canvas-a2ui.md

@@ -1,93 +0,0 @@
----
-summary: "Refactor: host A2UI from the Gateway (HTTP), remove app-bundled shells"
-read_when:
-  - Refactoring Canvas/A2UI ownership or assets
-  - Moving UI rendering from native bundles into the Gateway
-  - Updating node canvas navigation or A2UI command flows
----
-
-# Canvas / A2UI — HTTP-hosted from Gateway
-
-Status: Implemented · Date: 2025-12-20
-
-## Goal
-- Make the **Gateway (TypeScript)** the single owner of A2UI.
-- Remove **app-bundled A2UI shells** (macOS, iOS, Android).
-- A2UI renders only when the **Gateway is reachable** (acceptable failure mode).
-
-## Decision
-All A2UI HTML/JS assets are **served by the Gateway canvas host** on
-`canvasHost.port` (default `18793`), bound to the **bridge interface**. Nodes
-(mac/iOS/Android) **navigate to the advertised `canvasHostUrl`** before applying
-A2UI messages. No local custom-scheme or bundled fallback remains.
-
-## Why
-- One source of truth (TS) for A2UI rendering.
-- Faster iteration (no app release required for A2UI updates).
-- iOS/Android/macOS all behave identically.
-
-## New behavior (summary)
-1) `canvas.a2ui.*` on any node:
-   - Ensure Canvas is visible.
-   - Navigate the node WebView to the Gateway A2UI URL.
-   - Apply/reset A2UI messages once the page is ready.
-2) If Gateway is unreachable:
-   - A2UI fails with an explicit error (no fallback).
-
-## Gateway changes
-
-### Serve A2UI assets
-Add A2UI HTML/JS to the Gateway Canvas host (standalone HTTP server on
-`canvasHost.port`), e.g.:
-
-```
-/__clawdbot__/a2ui/           -> index.html
-/__clawdbot__/a2ui/a2ui.bundle.js -> bundled A2UI runtime
-```
-
-Serve Canvas files at `/__clawdbot__/canvas/` and A2UI at `/__clawdbot__/a2ui/`.
-Use the shared Canvas host handler (`src/canvas-host/server.ts`) to serve these
-assets and inject the action bridge + live reload if desired.
-
-### Canonical host URL
-The Gateway exposes a **canonical** `canvasHostUrl` in hello/bridge payloads
-so nodes don’t need to guess.
-
-## Node changes (mac/iOS/Android)
-
-### Navigation path
-Before applying A2UI:
-- Navigate to `${canvasHostUrl}/__clawdbot__/a2ui/`.
-
-### Remove bundled shells
-Remove all fallback logic that serves A2UI from local bundles:
-- macOS: remove custom-scheme fallback for `/__clawdbot__/a2ui/`
-- iOS/Android: remove packaged A2UI assets and "default scaffold" assumptions
-
-### Error behavior
-If `canvasHostUrl` is missing or unreachable:
-- `canvas.a2ui.push/reset` returns a clear error:
-  - `A2UI_HOST_UNAVAILABLE` or `A2UI_HOST_NOT_CONFIGURED`
-
-## Security / transport
-- For non-TLS Gateway URLs (http), iOS/Android will need ATS exceptions.
-- For TLS (https), prefer WSS + HTTPS with a valid cert.
-
-## Implementation plan
-1) Gateway
-   - Add A2UI assets under `src/canvas-host/`.
-   - Serve them at `/__clawdbot__/a2ui/` (align with existing naming).
-   - Serve Canvas files at `/__clawdbot__/canvas/` on `canvasHost.port`.
-   - Expose `canvasHostUrl` in handshake + bridge hello payloads.
-2) Node runtimes
-   - Update `canvas.a2ui.*` to navigate to `canvasHostUrl`.
-   - Remove custom-scheme A2UI fallback and bundled assets.
-3) Tests
-   - TS: verify `/__clawdbot__/a2ui/` responds with HTML + JS.
-   - Node: verify A2UI fails when host is unreachable and succeeds when reachable.
-4) Docs
-   - Update `docs/mac/canvas.md`, `docs/ios/spec.md`, `docs/android/connect.md`
-     to remove local fallback assumptions and point to gateway-hosted A2UI.
-
-## Notes
-- iOS/Android may still require ATS exceptions for `http://` canvas hosts.

docs/refactor/cli-unification.md

@@ -1,64 +0,0 @@
----
-summary: "Refactor: unify on the clawdbot CLI + gateway-first control; retire clawdbot-mac"
-read_when:
-  - Removing or replacing the macOS CLI helper
-  - Adding node capabilities or permissions metadata
-  - Updating macOS app packaging/install flows
----
-
-# CLI unification (clawdbot-only)
-
-Status: active refactor · Date: 2025-12-20
-
-## Goals
-- **Single CLI**: use `clawdbot` for all automation (local + remote). Retire `clawdbot-mac`.
-- **Gateway-first**: all agent actions flow through the Gateway WebSocket + node.invoke.
-- **Permission awareness**: nodes advertise permission state so the agent can decide what to run.
-- **No duplicate paths**: remove macOS control socket + Swift CLI surface.
-
-## Non-goals
-- Keep legacy `clawdbot-mac` compatibility.
-- Support agent control when no Gateway is running.
-
-## Key decisions
-1) **No Gateway → no control**
-   - If the macOS app is running but the Gateway is not, remote commands (canvas/run/notify) are unavailable.
-   - This is acceptable to keep one network surface.
-
-2) **Remove ensure-permissions CLI**
-   - Permissions are **advertised by the node** (e.g., screen recording granted/denied).
-   - Commands will still fail with explicit errors when permissions are missing.
-
-3) **Mac app installs/symlinks `clawdbot`**
-   - Bundle a standalone `clawdbot` binary in the app (bun-compiled).
-   - Install/symlink that binary to `/usr/local/bin/clawdbot` and `/opt/homebrew/bin/clawdbot`.
-   - No `clawdbot-mac` helper remains.
-
-4) **Canvas parity across node types**
-   - Use `node.invoke` commands consistently (`canvas.present|navigate|eval|snapshot|a2ui.*`).
-   - The TS CLI provides convenient wrappers so agents never have to craft raw `node.invoke` calls.
-
-## Command surface (new/normalized)
-- `clawdbot nodes invoke --command canvas.*` remains valid.
-- New CLI wrappers for convenience:
-  - `clawdbot canvas present|navigate|eval|snapshot|a2ui push|a2ui reset`
-- New node commands (mac-only initially):
-  - `system.run` (shell execution)
-  - `system.notify` (local notifications)
-
-## Permission advertising
-- Node hello/pairing includes a `permissions` map:
-  - Example keys: `screenRecording`, `accessibility`, `microphone`, `notifications`, `speechRecognition`.
-  - Values: boolean (`true` = granted, `false` = not granted).
-- Gateway `node.list` / `node.describe` surfaces the map.
-
-## Gateway mode + config
-- Gateways should only auto-start when explicitly configured for **local** mode.
-- When config is missing or explicitly remote, `clawdbot gateway` should refuse to auto-start unless forced.
-
-## Implementation checklist
-- Add bun-compiled `clawdbot` binary to macOS app bundle; update codesign + install flows.
-- Remove `ClawdbotCLI` target and control socket server.
-- Add node command(s) for `system.run` and `system.notify` on macOS.
-- Add permission map to node hello/pairing + gateway responses.
-- Update TS CLI + docs to use `clawdbot` only.

docs/refactor/gateway-client.md

@@ -1,31 +0,0 @@
----
-summary: "Refactor notes for the macOS gateway client typed API migration (Dec 2025)."
-read_when:
-  - Refactoring macOS gateway client or typed gateway methods
-  - Auditing agent routing or channel semantics
----
-
-# Gateway Client Refactor (Dec 2025)
-
-Goal: remove stringly-typed gateway calls from the macOS app, centralize routing/channel semantics, and improve error handling.
-
-## Progress
-
-- [x] Fold legacy “AgentRPC” into `GatewayConnection` (single layer; no separate client object).
-- [x] Typed gateway API: `GatewayConnection.Method` + `requestDecoded/requestVoid` + typed helpers (status/agent/chat/cron/etc).
-- [x] Centralize agent routing/channel semantics via `GatewayAgentChannel` + `GatewayAgentInvocation`.
-- [x] Improve gateway error model (structured `GatewayResponseError` + decoding errors include method).
-- [x] Migrate mac call sites to typed helpers (leave only intentionally dynamic forwarding paths).
-- [x] Convert remaining UI raw channel strings to `GatewayAgentChannel` (Cron editor).
-- [x] Cleanup naming: rename remaining tests/docs that still reference “RPC/AgentRPC”.
-
-### Notes
-
-- Intentionally string-based:
-  - `BridgeServer` dynamic request forwarding (method is data-driven).
-  - `ControlChannel` request wrapper (generic escape hatch).
-
-## Notes / Non-goals
-
-- No functional behavior changes intended (beyond better errors and removing “magic strings”).
-- Keep changes incremental: introduce typed APIs first, then migrate call sites, then remove old helpers.

docs/refactor/gateway.md

@@ -1,99 +0,0 @@
----
-summary: "Refactor notes for the macOS gateway client: single shared websocket + follow-ups"
-read_when:
-  - Investigating duplicate/stale Gateway WS connections
-  - Refactoring macOS gateway client architecture
-  - Debugging noisy reconnect storms on gateway restart
----
-# Gateway Refactor Notes (macOS client)
-
-Last updated: 2025-12-12
-
-This document captures the rationale and outcome of the macOS app’s Gateway client refactor: **one shared websocket connection per app process**, with an in-process event bus for server push frames.
-
-Related docs:
-- `docs/refactor/new-arch.md` (overall gateway protocol/server plan)
-- `docs/gateway.md` (gateway operations/runbook)
-- `docs/presence.md` (presence semantics and dedupe)
-- `docs/mac/webchat.md` (WebChat surfaces and debugging)
-
----
-
-## Background: what was wrong
-
-Symptoms:
-- Restarting the gateway produced a *storm* of reconnects/log spam (`gateway/ws in connect`, `hello`, `hello-ok`) and elevated `clients=` counts.
-- Even with “one panel open”, the mac app could hold tens of websocket connections to `ws://127.0.0.1:18789`.
-
-Root cause (historical bug):
-- The mac app was repeatedly “reconfiguring” a gateway client on a timer (via health polling), creating a new websocket owner each time.
-- Old websocket owners were not fully torn down and could keep watchdog/tick tasks alive, leading to **connection accumulation** over time.
-
----
-
-## What changed
-
-- **One socket owner:** `GatewayConnection.shared` is the only supported entry point for gateway RPC.
-- **No global notifications:** server push frames are delivered via `GatewayConnection.shared.subscribe(...) -> AsyncStream<GatewayPush>` (no `NotificationCenter` fan-out).
-- **No tunnel side effects:** `GatewayConnection` does not create/ensure SSH tunnels in remote mode; it consumes the already-established forwarded port.
-
----
-
-## Current architecture (as of 2025-12-12)
-
-Goal: enforce the invariant **“one gateway websocket per app process (per effective config)”**.
-
-Key elements:
-- `GatewayConnection.shared` owns the one websocket and is the *only* supported entry point for app code that needs gateway RPC.
-- Consumers (e.g. Control UI, agent invocations, SwiftUI WebChat) call `GatewayConnection.shared.request(...)` and do not create their own sockets.
-- If the effective connection config changes (local ↔ remote tunnel port, token change), `GatewayConnection` replaces the underlying connection.
-- The transport (`GatewayChannelActor`) is an internal detail and forwards push frames back into `GatewayConnection`.
-- Server-push frames are delivered via `GatewayConnection.shared.subscribe(...) -> AsyncStream<GatewayPush>` (in-process event bus).
-
-Notes:
-- Remote mode requires an SSH control tunnel. `GatewayConnection` **does not** start tunnels; it consumes the already-established forwarded port (owned by `ConnectionModeCoordinator` / `RemoteTunnelManager`).
-
----
-
-## Design constraints / principles
-
-- **Single ownership:** Exactly one component owns the actual socket and reconnect policy.
-- **Explicit config changes:** Recreate/reconnect only when config changes, not as a side effect of periodic work.
-- **No implicit fan-out sockets:** Adding new UI features must not accidentally add new persistent gateway connections.
-- **Testable seams:** Connection config and websocket session creation should be overridable in tests.
-
----
-
-## Status / remaining work
-
-- ✅ One shared websocket per app process (per config)
-- ✅ Event streaming moved into `GatewayConnection` (`AsyncStream<GatewayPush>`) and replays latest snapshot to new subscribers
-- ✅ `NotificationCenter` removed for in-process gateway events (ControlChannel / Instances / WebChatSwiftUI)
-- ✅ Remote tunnel lifecycle is not started implicitly by random RPC calls
-- ✅ Payload decoding helpers extracted so UI adapters stay thin
-- ✅ Dedicated resolved-endpoint publisher for remote mode (`GatewayEndpointStore`)
-
----
-
-## Testing strategy (what we want to cover)
-
-Minimum invariants:
-- Repeated requests under the same config do **not** create additional websocket tasks.
-- Concurrent requests still create **exactly one** websocket and reuse it.
-- Shutdown prevents any reconnect loop after failures.
-- Config changes (token / endpoint) cancel the old socket and reconnect once.
-
-Nice-to-have integration coverage:
-- Multiple “consumers” (Control UI + agent invocations + SwiftUI WebChat) all call through the shared connection and still produce only one websocket.
-
-Additional coverage added (macOS):
-- Subscribing after connect replays the latest snapshot.
-- Sequence gaps emit an explicit `GatewayPush.seqGap(...)` before the corresponding event.
-
----
-
-## Debug notes (operational)
-
-When diagnosing “too many connections”:
-- Prefer counting actual TCP connections on port 18789 and grouping by PID to see which process is holding sockets.
-- Gateway `--verbose` prints *every* connect/hello and event broadcast; use it only when needed and filter output if you’re just sanity-checking.

docs/refactor/new-arch.md

@@ -1,171 +0,0 @@
----
-summary: "Implementation plan for the new gateway architecture and protocol"
-read_when:
-  - Executing the gateway refactor
----
-# New Gateway Architecture – Implementation Plan (detailed)
-
-Last updated: 2025-12-09
-
-Goal: replace legacy gateway/stdin/TCP control with a single WebSocket Gateway, typed protocol, and first-frame snapshot. No backward compatibility.
-
----
-
-## Phase 0 — Foundations
-- **Naming**: CLI subcommand `clawdbot gateway`; internal namespace `Gateway`.
-- **Protocol folder**: create `protocol/` for schemas and build artifacts. ✅ `src/gateway/protocol`.
-- **Schema tooling**:
-  - Prefer **TypeBox** (or ArkType) as source-of-truth types. ✅ TypeBox in `schema.ts`.
-  - `pnpm protocol:gen`: emits JSON Schema (`dist/protocol.schema.json`). ✅
-  - `pnpm protocol:gen:swift`: generates Swift `Codable` models (`apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift`). ✅
-  - AJV compile step for server validators. ✅
-- **CI**: add a job that fails if schema or generated Swift is stale. ✅ `pnpm protocol:check` (runs gen + git diff).
-
-## Phase 1 — Protocol specification
-- Frames (WS text JSON, all with explicit `type`):
-  - `req {type:"req", id, method:"connect", params:{minProtocol,maxProtocol,client:{name,version,platform,deviceFamily?,modelIdentifier?,mode,instanceId}, caps, auth:{token?}, locale?, userAgent?}}`
-  - `res {type:"res", id, ok:true, payload: hello-ok }` (or `ok:false` then close)
-  - `hello-ok {type:"hello-ok", protocol:<chosen>, server:{version,commit,host,connId}, features:{methods,events}, snapshot:{presence[], health, stateVersion:{presence,health}, uptimeMs}, policy:{maxPayload, maxBufferedBytes, tickIntervalMs}}`
-  - `req {type:"req", id, method, params?}`
-  - `res {type:"res", id, ok, payload?, error?}` where `error` = `{code,message,details?,retryable?,retryAfterMs?}`
-  - `event {type:"event", event, payload, seq?, stateVersion?}` (presence/tick/shutdown/agent)
-  - `close` (standard WS close codes; policy uses 1008 for slow consumer/unauthorized, 1012/1001 for restart)
-- Payload types:
-  - `PresenceEntry {host, ip, version, platform?, deviceFamily?, modelIdentifier?, mode, lastInputSeconds?, ts, reason?, tags?[], instanceId?}`
-  - `HealthSnapshot` (match existing `clawdbot health --json` fields)
-  - `AgentEvent` (streamed tool/output; `{runId, seq, stream, data, ts}`)
-  - `TickEvent {ts}`
-  - `ShutdownEvent {reason, restartExpectedMs?}`
-  - Error codes: `NOT_LINKED`, `AGENT_TIMEOUT`, `INVALID_REQUEST`, `UNAVAILABLE`.
-- Error shape: `{code, message, details?, retryable?, retryAfterMs?}`
-- Rules:
-  - First frame must be `req` with `method:"connect"`; otherwise close. Add handshake timeout (e.g., 3s) for silent clients.
-  - Negotiate protocol: server picks within `[minProtocol,maxProtocol]`; if none, reply `res ok:false` and close.
-  - Protocol version bump on breaking changes; `hello-ok` must include `minClient` when needed.
-  - `stateVersion` increments for presence/health to drop stale deltas.
-  - Stable IDs: client sends `instanceId`; server issues per-connection `connId` in `hello-ok`; presence entries may include `instanceId` to dedupe reconnects.
-  - Token-based auth: bearer token in `auth.token`; required except for loopback development.
-  - Presence is primarily connection-derived; client may add hints (e.g., lastInputSeconds); entries expire via TTL to keep the map bounded (e.g., 5m TTL, max 200 entries).
-  - Idempotency keys: required for `send` and `agent` to safely retry after disconnects.
-  - Size limits: bound first-frame size by `maxPayload`; reject early if exceeded.
-  - Close on any non-JSON or wrong `type` before connect.
-  - Per-op idempotency keys: client SHOULD supply an explicit key per `send`/`agent`; if omitted, server may derive a scoped key from `instanceId+connId`, but explicit keys are safer across reconnects.
-  - Locale/userAgent are informational; server may log them for analytics but must not rely on them for access control.
-
-## Phase 2 — Gateway WebSocket server
-- New module `src/gateway/server.ts`:
-  - Bind 127.0.0.1:18789 (configurable).
-  - On connect: validate `connect` params, send snapshot payload, start event pump.
-  - Per-connection queues with backpressure (bounded; drop oldest non-critical).
-  - WS-level caps: set `maxPayload` to cap frame size before JSON parse.
-  - Emit `tick` every N seconds when idle (or WS ping/pong if adequate).
-  - Emit `shutdown` before exit; then close sockets.
-- Methods implemented:
-  - `health`, `status`, `system-presence`, `system-event`, `send`, `agent`.
-  - Optional: `set-heartbeats` removed/renamed if heartbeat concept is retired.
-- Events implemented:
-  - `agent`, `presence` (deltas, with `stateVersion`), `tick`, `shutdown`.
-  - All events include `seq` for loss/out-of-order detection.
-- Logging: structured logs on connect/close/error; include client fingerprint.
-- Slow consumer policy:
-  - Per-connection outbound queue limit (bytes/messages). If exceeded, drop non-critical events (presence/tick) or close with a policy violation / retryable code; clients reconnect with backoff.
-- Handshake edge cases:
-  - Close on handshake timeout.
-  - Close on over-limit first frame (maxPayload).
-  - Close immediately on non-JSON or wrong `type` before connect.
-  - Default guardrails: `maxPayload` ~512 KB, handshake timeout ~3 s, outbound buffered amount cap ~1.5 MB (tune as you implement).
-- Dedupe cache: bound TTL (~5m) and max size (~1000 entries); evict oldest first (LRU) to prevent memory growth.
-
-## Phase 3 — Gateway CLI entrypoint
-- Add `clawdbot gateway` command in CLI program:
-  - Reads config (port, WS options).
-  - Foreground process; exit non-zero on fatal errors.
-  - Flags: `--port`, `--no-tick` (optional), `--log-json` (optional).
-- System supervision docs for launchd/systemd (see `gateway.md`).
-
-## Phase 4 — Presence/health snapshot & stateVersion
-- `hello-ok.snapshot` includes:
-  - `presence[]` (current list)
-  - `health` (full snapshot)
-  - `stateVersion {presence:int, health:int}`
-  - `uptimeMs`
-  - `policy {maxPayload, maxBufferedBytes, tickIntervalMs}`
-- Emit `presence` deltas with updated `stateVersion.presence`.
-- Emit `tick` to indicate liveness when no other events occur.
-- Keep `health` method for manual refresh; not required after connect.
- - Presence expiry: prune entries older than TTL; enforce a max map size; include `stateVersion` in presence events.
-
-## Phase 5 — Clients migration
-- **macOS app**:
-  - Replace stdio/SSH RPC with WS client (tunneled via SSH/Tailscale for remote). ✅ GatewayConnection/ControlChannel now use Gateway WS.
-  - Implement handshake, snapshot hydration, subscriptions to `presence`, `tick`, `agent`, `shutdown`. ✅ snapshot + presence events broadcast to InstancesStore; agent events still to wire to UI if desired.
-  - Remove immediate `health/system-presence` fetch on connect. ✅ presence hydrated from snapshot; periodic refresh kept as fallback.
-  - Handle connect failures (`res ok:false`) and retry with backoff if version/token mismatched. ✅ macOS GatewayChannel reconnects with exponential backoff.
-- **CLI**:
-- Add lightweight WS client helper for `status/health/send/agent` when Gateway is up. ✅ `gateway` subcommands use the Gateway over WS.
-  - Consider a “local only” flag to avoid accidental remote connects. (optional; not needed with tunnel-first model.)
-- **WebChat backend**:
-  - Single WS to Gateway; seed UI from snapshot; forward `presence/tick/agent` to browser. ✅ implemented via the WebChat gateway client in `webchat/server.ts`.
-  - Fail fast if handshake fails; no fallback transports. ✅ (webchat returns gateway unavailable)
-
-## Phase 6 — Send/agent path hardening
-- Ensure only the Gateway can open Baileys; no IPC fallback.
-- `send` executes in-process; respond with explicit result/error, not via heartbeat.
-- `agent` spawns Pi; respond quickly with `{runId,status:"accepted"}` (ack); stream `event:agent {runId, seq, stream, data, ts}`; final `res:agent {runId, status:"ok"|"error", summary}` completes request (idempotent via key).
-- Idempotency: side-effecting methods (`send`, `agent`) accept an idempotency key; keep a short-lived dedupe cache to avoid double-send on client retries. Client retry flow: on timeout/close, retry with same key; Gateway returns cached result when available; cache TTL ~5m and bounded.
-- Agent stream ordering: enforce monotonic `seq` per runId; if gap detected by server, terminate stream with error; if detected by client, issue a retry with same idempotency key.
- - Send response shape: `{messageId?, toJid?, error?}` and always include `runId` when available for traceability.
-
-## Phase 7 — Keepalive and shutdown semantics
-- Keepalive: `tick` events (or WS ping/pong) at fixed interval; clients treat missing ticks as disconnect and reconnect.
-- Shutdown: send `event:shutdown {reason, restartExpectedMs?}` then close sockets; clients auto-reconnect.
-- Restart semantics: close sockets with a standard retryable close code; on reconnect, `hello-ok` snapshot must be sufficient to rebuild UI without event replay.
-  - Use a standard close code (e.g., 1012 service restart or 1001 going away) for planned restart; 1008 policy violation for slow consumers.
-  - Include `policy` in `hello-ok` so clients know the tick interval and buffer limits to tune their expectations.
-
-## Phase 8 — Cleanup and deprecation
-- Retire `clawdbot rpc` as default path; keep only if explicitly requested (documented as legacy).
-- Remove reliance on `src/infra/control-channel.ts` for new clients; mark as legacy or delete after migration. ✅ file removed; mac app now uses Gateway WS.
-- Update README, docs (`architecture.md`, `gateway.md`, `webchat.md`) to final shapes; remove `control-api.md` references if obsolete.
-- Presence hygiene:
-  - Presence derived primarily from connection (server-fills host/ip/version/connId/instanceId); allow client hints (e.g., lastInputSeconds).
-  - Add TTL/expiry; prune to keep map bounded (e.g., 5m TTL, max 200 entries).
-
-## Edge cases and ordering
-- Event ordering: all events carry `seq`; clients detect gaps and should re-fetch snapshot (or targeted refresh) on gap.
-- Partial handshakes: if client connects and never sends `req:connect`, server closes after handshake timeout.
-- Garbage/oversize first frame: bounded by `maxPayload`; server closes immediately on parse failure.
-- Duplicate delivery on reconnect: clients must send idempotency keys; Gateway dedupe cache prevents double-send/agent execution.
-- Snapshot sufficiency: `hello-ok.snapshot` must contain enough to render UI after reconnect without event replay.
-- Client reconnect guidance: exponential backoff with jitter; reuse same `instanceId` across reconnects to avoid duplicate presence; resend idempotency keys for in-flight sends/agents; on seq gap, issue `health`/`system-presence` refresh.
-- Presence TTL/defaults: set a concrete TTL (e.g., 5 minutes) and prune periodically; cap the presence map size with LRU if needed.
-- Replay policy: if seq gap detected, server does not replay; clients must pull fresh `health` + `system-presence` and continue.
-
-## Phase 9 — Testing & validation
-- Unit: frame validation, handshake failure, auth/token, stateVersion on presence events, agent stream fanout, send dedupe. ✅
-- Integration: connect → snapshot → req/res → streaming agent → shutdown. ✅ Covered in gateway WS tests (connect/health/status/presence, agent ack+final, shutdown broadcast).
-- Load: multiple concurrent WS clients; backpressure behavior under burst. ✅ Basic fanout test with 3 clients receiving presence broadcast; heavier soak still recommended.
-- Mac app smoke: presence/health render from snapshot; reconnect on tick loss. (Manual: open Instances tab, verify snapshot after connect, induce seq gap by toggling wifi, ensure UI refreshes.)
-- WebChat smoke: snapshot seed + event updates; tunnel scenario. ✅ Offline snapshot harness in `src/webchat/server.test.ts` (mock gateway) now passes; live tunnel still recommended for manual.
-- Idempotency tests: retry send/agent with same key after forced disconnect; expect deduped result. ✅ send + agent dedupe + reconnect retry covered in gateway tests.
-- Seq-gap handling: ✅ clients now detect seq gaps (WebChat gateway client + mac `GatewayConnection/GatewayChannel`) and refresh health/presence (webchat) or trigger UI refresh (mac). Load-test still optional.
-
-## Phase 10 — Rollout
-- Version bump; release notes: breaking change to control plane (WS only).
-- Ship launchd/systemd templates for `clawdbot gateway`.
-- Recommend Tailscale/SSH tunnel for remote access; no additional auth layer assumed in this model.
-
----
-
-- Quick checklist
-- [x] Protocol types & schemas (TS + JSON Schema + Swift via quicktype)
-- [x] AJV validators wired
-- [x] WS server with connect → snapshot → events
-- [x] Tick + shutdown events
-- [x] stateVersion + presence deltas
-- [x] Gateway CLI command
-- [x] macOS app WS client (Gateway WS for control; presence events live; agent stream UI pending)
-- [x] WebChat WS client
-- [x] Remove legacy stdin/TCP paths from default flows (file removed; mac app/CLI on Gateway)
-- [x] Tests (unit/integration/load) — unit + integration + basic fanout/reconnect; heavier load/soak optional
-- [x] Docs updated and legacy docs flagged

docs/refactor/tui.md

@@ -1,26 +0,0 @@
----
-summary: "Refactor plan: Gateway TUI parity with pi-mono interactive UI"
-read_when:
-  - Building or refactoring the Gateway TUI
-  - Syncing TUI slash commands with Clawdbot behavior
----
-# Gateway TUI refactor plan
-
-Updated: 2026-01-03
-
-## Goals
-- Match pi-mono interactive TUI feel (editor, streaming, tool cards, selectors).
-- Keep Clawdbot semantics: Gateway WS only, session store owns state, no branching/export.
-- Work locally or remotely via Gateway URL/token.
-
-## Non-goals
-- Branching, export, OAuth flows, or hook UIs.
-- File-system operations on the Gateway host from the TUI.
-
-## Checklist
-- [x] Protocol + server: sessions.patch supports model overrides; agent events include tool results (text-only payloads).
-- [x] Gateway TUI client: add session/model helpers + stricter typing.
-- [x] TUI UI kit: theme + components (editor, message feed, tool cards, selectors).
-- [x] TUI controller: keybindings + Clawdbot slash commands + history/stream wiring.
-- [x] Docs + changelog updated for the new TUI behavior.
-- [x] Gate: lint, build, tests, docs list.

docs/refactor/web-gateway-troubleshooting.md

@@ -1,37 +0,0 @@
----
-summary: "Troubleshooting guide for the web gateway/Baileys stack"
-read_when:
-  - Diagnosing web gateway socket or login issues
----
-# Web Gateway Troubleshooting (Nov 26, 2025)
-
-## Symptoms & quick fixes
-- **Stream Errored / Conflict / status 409–515:** WhatsApp closed the socket because another session is active or creds went stale. Run `clawdbot logout`, then `clawdbot login`, then restart the Gateway.
-- **Logged out:** Console prints “session logged out”; re-link with `clawdbot login`.
-- **Repeated retries then exit:** Tune reconnect behavior via config `web.reconnect` and restart the Gateway.
-- **No inbound messages:** Ensure the QR-linked account is online in WhatsApp, and check logs for `web-heartbeat` to confirm auth age/connection.
-- **Status 515 right after pairing:** The QR login flow now auto-restarts once; you should not need a manual gateway restart after scanning.
-- **Fast nuke:** From an allowed WhatsApp sender you can send `/restart` to request a supervised restart (launchd/mac app setups); wait a few seconds for it to come back.
-
-## Helpful commands
-- Start the Gateway: `clawdbot gateway --verbose`
-- Logout (clear creds): `clawdbot logout`
-- Relink (show QR): `clawdbot login --verbose`
-- Tail logs (default): `tail -f /tmp/clawdbot/clawdbot-*.log`
-
-## Reading the logs
-- `web-reconnect`: close reasons, retry/backoff, max-attempt exit.
-- `web-heartbeat`: connectionId, messagesHandled, authAgeMs, uptimeMs (every 60s by default).
-- `web-auto-reply`: inbound/outbound message records with correlation IDs.
-
-## When to tweak knobs
-- High churn networks: increase `web.reconnect.maxAttempts`.
-- Slow links: raise `web.reconnect.maxMs` to give more headroom before bailing.
-- Chatty monitors: increase `web.heartbeatSeconds` if log volume is high.
-
-## If it keeps failing
-1) `clawdbot logout` → `clawdbot login` (fresh QR link).
-2) Ensure no other device/browser is using the same WA Web session.
-3) Check WhatsApp mobile app is online and not in low-power mode.
-4) If status is 515, let the client restart once after pairing (already handled automatically).
-5) Capture the last `web-reconnect` entry and the status code before escalating.

docs/refactor/webagent-session.md

@@ -1,46 +0,0 @@
----
-summary: "WebChat session migration notes (Gateway WS-only)"
-read_when:
-  - Changing WebChat Gateway methods/events
----
-<!-- {% raw %} -->
-# WebAgent session migration (WS-only)
-
-Context: web chat currently lives in a WKWebView that loads the pi-web bundle. Sends go over HTTP `/rpc` to the webchat server, and updates come from `/socket` snapshots based on session JSONL file changes. The Gateway itself already speaks WebSocket to the webchat server, and Pi writes the session JSONL files. This doc tracks the plan to move WebChat to a single Gateway WebSocket and drop the HTTP shim/file-watching.
-
-## Target state
-- Gateway WS adds methods:
-  - `chat.history { sessionKey }` → `{ sessionKey, messages[], thinkingLevel }` (reads the existing JSONL + session store).
-  - `chat.send { sessionKey, message, attachments?, thinking?, deliver?, timeoutMs<=30000, idempotencyKey }` → `res { runId, status:"accepted" }` or `res ok:false` on validation/timeout.
-- Gateway WS emits `chat` events `{ runId, sessionKey, seq, state:"delta"|"final"|"error", message?, errorMessage?, usage?, stopReason? }`. Streaming is optional; minimum is a single `state:"final"` per send.
-- Client consumes only WS: bootstrap via `chat.history`, send via `chat.send`, live updates via `chat` events. No file watchers.
-- Health gate: client subscribes to `health` and blocks send when health is not OK; 30s client-side timeout for sends.
-- Tunneling: only the Gateway WS port needs to be forwarded; HTTP server remains for static assets but no RPC endpoints.
-
-## Server work (Node)
-- Implement `chat.history` and `chat.send` handlers in `src/gateway/server.ts`; update protocol schemas/tests.
-- Emit `chat` events by plumbing `agentCommand`/`emitAgentEvent` outputs; include assistant text/tool results.
-- Remove `/rpc` and `/socket` routes + file-watch broadcast from `src/webchat/server.ts`; leave static host only.
-
-## Client work (pi-web bundle)
-- Replace `NativeTransport` with a Gateway WS client:
-  - `connect` → `chat.history` for initial state.
-  - Listen to `chat/presence/tick/health`; update UI from events only.
-  - Send via `chat.send`; mark pending until `chat state:final|error`.
-  - Enforce health gate + 30s timeout.
-- Remove reliance on session file snapshots and `/rpc`.
-
-## Persistence
-- Keep passing `--session <.../.clawdbot/sessions/{{SessionId}}.jsonl>` to Pi so it continues writing JSONL. The WS history reader uses the same file; no new store introduced.
-
-## Docs to update when shipping
-- `docs/webchat.md` (WS-only flow, methods/events, health gate, tunnel WS port).
-- `docs/mac/webchat.md` (WKWebView now talks Gateway WS; `/rpc`/file-watch removed).
-- `docs/architecture.md` / `typebox.md` if protocol methods are listed.
-- Optional: add a concise Gateway chat protocol appendix if needed.
-
-## Open decisions
-- Streaming granularity: start with `state:"final"` only, or include token/tool deltas immediately?
-- Attachments over WS: text-only initially is OK; confirm before wiring binary/upload path.
-- Error shape: use `res ok:false` for validation/timeout, `chat state:"error"` for model/runtime failures.
-<!-- {% endraw %} -->

docs/remote-gateway-readme.md

@@ -1,3 +1,8 @@
+---
+summary: "SSH tunnel setup for Clawdbot.app connecting to a remote gateway"
+read_when: "Connecting the macOS app to a remote gateway over SSH"
+---
+
 # Running Clawdbot.app with a Remote Gateway
 
 Clawdbot.app uses SSH tunneling to connect to a remote gateway. This guide shows you how to set it up.

docs/research/memory.md

@@ -111,7 +111,7 @@ Example:
 ## Retain
 - W @Peter: Currently in Marrakech (Nov 27–Dec 1, 2025) for Andy’s birthday.
 - B @warelay: I fixed the Baileys WS crash by wrapping connection.update handlers in try/catch (see memory/2025-11-27.md).
-- O(c=0.95) @Peter: Prefers concise replies (<1500 chars) on WhatsApp; long content goes into files.
+- O(c=0.95) @Peter: Prefers concise replies (&lt;1500 chars) on WhatsApp; long content goes into files.
 ```
 
 Minimal parsing:

docs/session.md

@@ -77,6 +77,7 @@ Runtime override (owner only):
 - `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` 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

docs/setup.md

@@ -109,10 +109,23 @@ pnpm clawdbot health
 - Keep `~/clawd` and `~/.clawdbot/` as “your stuff”; don’t put personal prompts/config into the `clawdbot` repo.
 - Updating source: `git pull` + `pnpm install` (when lockfile changed) + keep using `pnpm gateway:watch`.
 
+## Linux (systemd user service)
+
+Linux installs use a systemd **user** service. By default, systemd stops user
+services on logout/idle, which kills the Gateway. Onboarding attempts to enable
+lingering for you (may prompt for sudo). If it’s still off, run:
+
+```bash
+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` for the systemd notes.
+
 ## Related docs
 
 - `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/clawdbot-mac.md` (macOS app behavior; gateway lifecycle + “Attach only”)
+- `docs/macos.md` (macOS app behavior; gateway lifecycle + “Attach only”)

docs/showcase.md

@@ -0,0 +1,36 @@
+---
+summary: "Real-world showcases of what Clawdbot can do"
+read_when:
+  - You want inspiration or proof of capability
+---
+# Showcase
+
+Real projects from the community. Highlights from #showcase (Jan 2–5, 2026).
+
+## Automation & real-world outcomes
+- **Grocery autopilot (Picnic)** — Skill built around an unofficial Picnic API client. Pulls order history, infers preferred brands, maps recipes to cart, completes order in minutes. https://github.com/timkrase/clawdis-picnic-skill
+- **Grocery autopilot (Picnic, alt)** — Another Picnic-based skill built via the `picnic-api` package. https://github.com/MRVDH/picnic-api
+- **German rail planning** — Go CLI for Deutsche Bahn; skill picks best connections given time windows and preferences. https://github.com/timkrase/dbrest-cli + https://github.com/timkrase/clawdis-skills/tree/main/db-bahn
+- **Accounting intake** — Collect PDFs from email, prep for tax consultant (monthly accounting batch). (No link shared.)
+
+## Knowledge & memory systems
+- **WhatsApp memory vault** — Ingests full exports, transcribes 1k+ voice notes, cross‑checks with git logs, outputs linked MD reports + ongoing indexing. (No link shared.)
+- **Karakeep semantic search** — Sidecar adds vector search to Karakeep bookmarks (Qdrant + OpenAI/Ollama), includes Clawdis skill. https://github.com/jamesbrooksco/karakeep-semantic-search
+- **Inside‑Out‑2 style memory** — Separate memory manager app turns session files into memories → beliefs → self model. (No link shared.)
+
+## Voice, docs, and assistants on the phone
+- **Clawdia phone bridge** — Vapi voice assistant ↔ Clawdis HTTP bridge; near‑real‑time phone calls. https://github.com/alejandroOPI/clawdia-bridge
+- **Google Docs edit skill** — Rich‑text editing skill built fast with Claude Code. (No link shared.)
+- **OpenRouter transcription skill** — Multi‑lingual audio transcription via OpenRouter (Gemini etc). ClawdHub: https://clawdhub.com/obviyus/openrouter-transcribe (user/slug link)
+
+## Infrastructure & deployment
+- **Home Assistant OS gateway add‑on** — Clawdbot gateway running on HA OS (Raspberry Pi), with SSH tunnel support + persistent state in /config. https://github.com/ngutman/clawdbot-ha-addon
+- **Home Assistant skill** — Control/automate HA via ClawdHub. https://clawdhub.com/skills/homeassistant
+- **Nix packaging** — Batteries‑included nixified clawdis config. https://github.com/joshp123/nix-clawdis
+- **CalDAV skill** — khal/vdirsyncer based calendar skill. ClawdHub: caldav-calendar → https://clawdhub.com/skills/caldav-calendar
+
+## Home + hardware
+- **Roborock integration** — Plugin for robot vacuum control. https://github.com/joshp123/gohome/tree/main/plugins/roborock
+
+## Community builds (non‑Clawdis but made with/around it)
+- **StarSwap marketplace** — Full astronomy gear marketplace. https://star-swap.com/

docs/skills.md

@@ -4,7 +4,6 @@ read_when:
   - Adding or modifying skills
   - Changing skill gating or load rules
 ---
-<!-- {% raw %} -->
 # Skills (Clawdbot)
 
 Clawdbot uses **AgentSkills-compatible** skill folders to teach the agent how to use tools. Each skill is a directory containing a `SKILL.md` with YAML frontmatter and instructions. Clawdbot loads **bundled skills** plus optional local overrides, and filters them at load time based on environment, config, and binary presence.
@@ -146,4 +145,3 @@ copy). Workspace skills are user-owned and override both on name conflicts.
 See `docs/skills-config.md` for the full configuration schema.
 
 ---
-<!-- {% endraw %} -->

docs/slack.md

@@ -1,3 +1,8 @@
+---
+summary: "Slack socket mode setup and Clawdbot config"
+read_when: "Setting up Slack or debugging Slack socket mode"
+---
+
 # Slack (socket mode)
 
 ## Setup
@@ -50,8 +55,14 @@ Use this Slack app manifest to create the app quickly (adjust the name/command i
         "channels:history",
         "channels:read",
         "groups:history",
+        "groups:read",
+        "groups:write",
         "im:history",
+        "im:read",
+        "im:write",
         "mpim:history",
+        "mpim:read",
+        "mpim:write",
         "users:read",
         "app_mentions:read",
         "reactions:read",
@@ -87,6 +98,44 @@ Use this Slack app manifest to create the app quickly (adjust the name/command i
 }
 ```
 
+## 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
+https://api.slack.com/docs/conversations-api for the overview.
+
+### Required by current code
+- `chat:write` (send/update/delete messages via `chat.postMessage`)
+  https://api.slack.com/methods/chat.postMessage
+- `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://api.slack.com/methods/conversations.history
+- `channels:read`, `groups:read`, `im:read`, `mpim:read`
+  (`conversations.info` in `src/slack/monitor.ts`)
+  https://api.slack.com/methods/conversations.info
+- `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
+  https://api.slack.com/methods/reactions.add
+- `pins:read`, `pins:write` (`pins.list` / `pins.add` / `pins.remove`)
+  https://api.slack.com/scopes/pins:read
+  https://api.slack.com/scopes/pins:write
+- `emoji:read` (`emoji.list`)
+  https://api.slack.com/scopes/emoji:read
+- `files:write` (uploads via `files.uploadV2`)
+  https://api.slack.com/messaging/files/uploading
+
+### Not needed today (but likely future)
+- `mpim:write` (only if we add group-DM open/DM start via `conversations.open`)
+- `groups:write` (only if we add private-channel management: create/rename/invite/archive)
+- `chat:write.public` (only if we want to post to channels the bot isn't in)
+  https://api.slack.com/scopes/chat:write.public
+- `users:read.email` (only if we need email fields from `users.info`)
+  https://api.slack.com/changelog/2017-04-narrowing-email-access
+- `files:read` (only if we start listing/reading file metadata)
+
 ## Config
 Slack uses Socket Mode only (no HTTP webhook server). Provide both tokens:
 
@@ -153,6 +202,6 @@ Slack tool actions can be gated with `slack.actions.*`:
 | emojiList | enabled | Custom emoji list |
 
 ## Notes
-- Mention gating is controlled via `slack.channels` (set `requireMention` to `true`).
+- Mention gating is controlled via `slack.channels` (set `requireMention` to `true`); `routing.groupChat.mentionPatterns` also count as mentions.
 - Reaction notifications follow `slack.reactionNotifications` (use `reactionAllowlist` with mode `allowlist`).
 - Attachments are downloaded to the media store when permitted and under the size limit.

docs/telegram.md

@@ -35,7 +35,7 @@ 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 `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 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.groups`, `telegram.allowFrom`, `telegram.mediaMaxMb`, `telegram.replyToMode`, `telegram.proxy`, `telegram.webhookSecret`, `telegram.webhookUrl`, `telegram.webhookPath` supported.
   - Mention gating precedence (most specific wins): `telegram.groups.<chatId>.requireMention` → `telegram.groups."*".requireMention` → default `true`.
@@ -65,7 +65,7 @@ Example config:
 ## 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`) or use commands to trigger; per-group overrides live in `telegram.groups` if you want always-on 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.
 
 ## Reply tags
 To request a threaded reply, the model can include one tag in its output:

docs/templates/AGENTS.md

@@ -69,6 +69,29 @@ Vectors + BM25 + reranking finds things even with different wording.
 
 You have access to your human's stuff. That doesn't mean you *share* their stuff. In groups, you're a participant — not their voice, not their proxy. Think before you speak.
 
+### 💬 Know When to Speak!
+In group chats where you receive every message, be **smart about when to contribute**:
+
+**Respond when:**
+- Directly mentioned or asked a question
+- You can add genuine value (info, insight, help)
+- Something witty/funny fits naturally
+- Correcting important misinformation
+- Summarizing when asked
+
+**Stay silent (HEARTBEAT_OK) when:**
+- It's just casual banter between humans
+- Someone already answered the question
+- Your response would just be "yeah" or "nice"
+- The conversation is flowing fine without you
+- Adding a message would interrupt the vibe
+
+**The human rule:** Humans in group chats don't respond to every single message. Neither should you. Quality > quantity. If you wouldn't send it in a real group chat with friends, don't send it.
+
+**Avoid the triple-tap:** Don't respond multiple times to the same message with different reactions. One thoughtful response beats three fragments.
+
+Participate, don't dominate.
+
 ## Tools
 
 Skills provide your tools. When you need one, check its `SKILL.md`. Keep local notes (camera names, SSH details, voice preferences) in `TOOLS.md`.
@@ -103,7 +126,7 @@ When you receive a `HEARTBEAT` message, don't just reply `HEARTBEAT_OK` every ti
 
 **When to reach out:**
 - Important email arrived
-- Calendar event coming up (<2h)
+- Calendar event coming up (&lt;2h)
 - Something interesting you found
 - It's been >8h since you said anything
 
@@ -111,7 +134,7 @@ When you receive a `HEARTBEAT` message, don't just reply `HEARTBEAT_OK` every ti
 - Late night (23:00-08:00) unless urgent
 - Human is clearly busy
 - Nothing new since last check
-- You just checked <30 minutes ago
+- You just checked &lt;30 minutes ago
 
 **Proactive work you can do without asking:**
 - Read and organize memory files

docs/test.md

@@ -33,3 +33,11 @@ scripts/e2e/onboard-docker.sh
 ```
 
 This script drives the interactive wizard via a pseudo-tty, verifies config/workspace/session files, then starts the gateway and runs `clawdbot health`.
+
+## QR import smoke (Docker)
+
+Ensures `qrcode-terminal` loads under Node 22+ in Docker:
+
+```bash
+pnpm test:docker:qr
+```

docs/timezone.md

@@ -0,0 +1,40 @@
+---
+summary: "Timezone handling for agents, envelopes, and prompts"
+read_when:
+  - You need to understand how timestamps are normalized for the model
+  - Configuring the user timezone for system prompts
+---
+
+# Timezones
+
+Clawdbot standardizes timestamps so the model sees a **single reference time**.
+
+## Message envelopes (UTC)
+
+Inbound messages are wrapped in an envelope like:
+
+```
+[Surface ... 2026-01-05T21:26Z] message text
+```
+
+The timestamp in the envelope is **always UTC**, with minutes precision.
+
+## Tool payloads (raw provider data)
+
+Tool calls (`discord.readMessages`, `slack.readMessages`, etc.) return **raw provider timestamps**.
+These are typically UTC ISO strings (Discord) or UTC epoch strings (Slack). We do not rewrite them.
+
+## User timezone for the system prompt
+
+Set `agent.userTimezone` to tell the model the user's local time zone. If it is
+unset, Clawdbot resolves the **host timezone at runtime** (no config write).
+
+```json5
+{
+  agent: { userTimezone: "America/Chicago" }
+}
+```
+
+The system prompt includes:
+- `User timezone: America/Chicago`
+- `Current user time: 2026-01-05 15:26`

docs/tools.md

@@ -11,6 +11,21 @@ Clawdbot exposes **first-class agent tools** for browser, canvas, nodes, and cro
 These replace the old `clawdbot-*` skills: the tools are typed, no shelling,
 and the agent should rely on them directly.
 
+## Disabling tools
+
+You can globally allow/deny tools via `agent.tools` in `clawdbot.json`
+(deny wins). This prevents disallowed tools from being sent to providers.
+
+```json5
+{
+  agent: {
+    tools: {
+      deny: ["browser"]
+    }
+  }
+}
+```
+
 ## Tool inventory
 
 ### `bash`
@@ -58,7 +73,7 @@ Common parameters:
 - `controlUrl` (defaults from config)
 - `profile` (optional; defaults to `browser.defaultProfile`)
 Notes:
-- Requires `browser.enabled=true` in `~/.clawdbot/clawdbot.json`.
+- Requires `browser.enabled=true` (default is `true`; set `false` to disable).
 - Uses `browser.controlUrl` unless `controlUrl` is passed explicitly.
 - All actions accept optional `profile` parameter for multi-instance support.
 - When `profile` is omitted, uses `browser.defaultProfile` (defaults to "clawd").
@@ -101,6 +116,19 @@ Notes:
 - Videos return `FILE:<path>` (mp4).
 - Location returns a JSON payload (lat/lon/accuracy/timestamp).
 
+### `image`
+Analyze an image with the configured image model.
+
+Core parameters:
+- `image` (required path or URL)
+- `prompt` (optional; defaults to "Describe the image.")
+- `model` (optional override)
+- `maxBytesMb` (optional size cap)
+
+Notes:
+- Only available when `agent.imageModel` is configured (primary or fallbacks).
+- Uses the image model directly (independent of the main chat model).
+
 ### `cron`
 Manage Gateway cron jobs and wakeups.
 
@@ -111,7 +139,7 @@ Core actions:
 
 Notes:
 - `add` expects a full cron job object (same schema as `cron.add` RPC).
-- `update` uses `{ jobId, patch }`.
+- `update` uses `{ id, patch }`.
 
 ### `gateway`
 Restart the running Gateway process (in-place).

docs/troubleshooting.md

@@ -29,8 +29,8 @@ cat ~/.clawdbot/clawdbot.json | jq '.whatsapp.allowFrom'
 
 **Check 2:** For group chats, is mention required?
 ```bash
-# The message must match mentionPatterns or explicit mentions; defaults live in whatsapp.groups
-cat ~/.clawdbot/clawdbot.json | jq '.routing.groupChat, .whatsapp.groups'
+# The message must match mentionPatterns or explicit mentions; defaults live in provider groups/guilds.
+cat ~/.clawdbot/clawdbot.json | jq '.routing.groupChat, .whatsapp.groups, .telegram.groups, .imessage.groups, .discord.guilds'
 ```
 
 **Check 3:** Check the logs
@@ -100,7 +100,7 @@ If you’re logged out / unlinked:
 
 ```bash
 clawdbot logout
-rm -rf ~/.clawdbot/credentials # if logout can't cleanly remove everything
+trash ~/.clawdbot/credentials # if logout can't cleanly remove everything
 clawdbot login --verbose       # re-scan QR
 ```
 
@@ -203,7 +203,7 @@ tail -20 /tmp/clawdbot/clawdbot-*.log
 Nuclear option:
 
 ```bash
-rm -rf ~/.clawdbot
+trash ~/.clawdbot
 clawdbot login         # re-pair WhatsApp
 clawdbot gateway        # start the Gateway again
 ```
@@ -225,3 +225,26 @@ clawdbot gateway        # start the Gateway again
 *"Have you tried turning it off and on again?"* — Every IT person ever
 
 🦞🔧
+
+### Browser Not Starting (Linux)
+
+If you see `"Failed to start Chrome CDP on port 18800"`:
+
+**Most likely cause:** Snap-packaged Chromium on Ubuntu.
+
+**Quick fix:** Install Google Chrome instead:
+```bash
+wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
+sudo dpkg -i google-chrome-stable_current_amd64.deb
+```
+
+Then set in config:
+```json
+{
+  "browser": {
+    "executablePath": "/usr/bin/google-chrome-stable"
+  }
+}
+```
+
+**Full guide:** See [browser-linux-troubleshooting.md](./browser-linux-troubleshooting.md)

docs/tui.md

@@ -48,13 +48,14 @@ Use SSH tunneling or Tailscale to reach the Gateway WS.
 - `/help`
 - `/status`
 - `/session <key>` (or `/sessions`)
-- `/model <provider/model>` (or `/models`)
+- `/model <provider/model>` (or `/model list`, `/models`)
 - `/think <off|minimal|low|medium|high>`
 - `/verbose <on|off>`
 - `/elevated <on|off>`
 - `/activation <mention|always>`
 - `/deliver <on|off>`
 - `/new` or `/reset`
+- `/compact [instructions]`
 - `/abort`
 - `/settings`
 - `/exit`

docs/whatsapp.md

@@ -33,6 +33,8 @@ WhatsApp requires a real mobile number for verification. VoIP and virtual number
 
 **Tip:** The number only needs to receive one verification SMS. After that, WhatsApp Web sessions persist via `creds.json`.
 
+**WhatsApp Business:** You can use WhatsApp Business on the same phone with a different number. This is a great option if you want to keep your personal WhatsApp separate — just install WhatsApp Business and register it with Clawdbot's dedicated number.
+
 ## Login + credentials
 - Login command: `clawdbot login` (QR via Linked Devices).
 - Credentials stored in `~/.clawdbot/credentials/creds.json`.
@@ -134,7 +136,7 @@ WhatsApp requires a real mobile number for verification. VoIP and virtual number
 ## Logs + troubleshooting
 - Subsystems: `whatsapp/inbound`, `whatsapp/outbound`, `web-heartbeat`, `web-reconnect`.
 - Log file: `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` (configurable).
-- Troubleshooting guide: `docs/refactor/web-gateway-troubleshooting.md`.
+- Troubleshooting guide: `docs/troubleshooting.md`.
 
 ## Tests
 - `src/web/auto-reply.test.ts` (mention gating, history injection, reply flow)

docs/windows.md

@@ -0,0 +1,11 @@
+---
+summary: "Windows app status + contribution call"
+read_when:
+  - Looking for Windows companion app status
+  - Planning platform coverage or contributions
+---
+# Windows App
+
+Clawdbot core is fully supported on Windows. The core is written in TypeScript, so it runs anywhere Node runs.
+
+We do not have a Windows companion app yet. It is planned, and we would love contributions to make it happen.

docs/wizard.md

@@ -26,7 +26,7 @@ clawdbot configure
 ## What the wizard does
 
 **Local mode (default)** walks you through:
-- Model/auth (Anthropic OAuth recommended, API key optional, Minimax M2.1 via LM Studio)
+- Model/auth (Anthropic or OpenAI Codex OAuth recommended, API key optional, Minimax M2.1 via LM Studio)
 - Workspace location + bootstrap files
 - Gateway settings (port/bind/auth/tailscale)
 - Providers (WhatsApp, Telegram, Discord, Signal)
@@ -48,9 +48,13 @@ It does **not** install or change anything on the remote host.
 
 2) **Model/Auth**
    - **Anthropic OAuth (recommended)**: browser flow; paste the `code#state`.
+   - **OpenAI Codex OAuth**: browser flow; paste the `code#state`.
+     - Sets `agent.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`.
    - **API key**: stores the key for you.
    - **Minimax M2.1 (LM Studio)**: config is auto‑written for the LM Studio endpoint.
    - **Skip**: no auth configured yet.
+   - Wizard runs a model check and warns if the configured model is unknown or missing auth.
+   - OAuth credentials live in `~/.clawdbot/credentials/oauth.json`; auth profiles live in `~/.clawdbot/agent/auth-profiles.json` (API keys + OAuth).
 
 3) **Workspace**
    - Default `~/clawd` (configurable).
@@ -70,8 +74,12 @@ It does **not** install or change anything on the remote host.
 
 6) **Daemon install**
    - macOS: LaunchAgent
+     - Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
    - Linux: systemd user unit
+     - Wizard attempts to enable lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.
+     - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
    - Windows: Scheduled Task
+     - Runs on user logon; headless/system services are not configured by default.
 
 7) **Health check**
    - Starts the Gateway (if needed) and runs `clawdbot health`.
@@ -83,6 +91,7 @@ It does **not** install or change anything on the remote host.
 
 9) **Finish**
    - Summary + next steps, including iOS/Android/macOS apps for extra features.
+   - If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.
 
 ## Remote mode
 

package.json

@@ -1,11 +1,11 @@
 {
   "name": "clawdbot",
-  "version": "2.0.0-beta5",
+  "version": "2026.1.5-3",
   "description": "WhatsApp gateway CLI (Baileys web) with Pi RPC agent",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "clawdbot": "dist/index.js"
+    "clawdbot": "dist/entry.js"
   },
   "files": [
     "dist/agents/**",
@@ -15,17 +15,25 @@
     "dist/cli/**",
     "dist/commands/**",
     "dist/config/**",
+    "dist/control-ui/**",
     "dist/cron/**",
+    "dist/daemon/**",
     "dist/discord/**",
     "dist/gateway/**",
     "dist/hooks/**",
+    "dist/imessage/**",
     "dist/infra/**",
     "dist/macos/**",
     "dist/media/**",
     "dist/process/**",
+    "dist/sessions/**",
     "dist/providers/**",
+    "dist/signal/**",
+    "dist/slack/**",
     "dist/telegram/**",
+    "dist/tui/**",
     "dist/web/**",
+    "dist/wizard/**",
     "dist/*.js",
     "dist/*.json",
     "docs/**",
@@ -36,19 +44,19 @@
     "LICENSE"
   ],
   "scripts": {
-    "dev": "tsx src/index.ts",
+    "dev": "tsx src/entry.ts",
     "docs:list": "tsx scripts/docs-list.ts",
     "docs:dev": "cd docs && mint dev",
-    "docs:build": "cd docs && mint broken-links",
+    "docs:build": "cd docs && pnpm dlx mint broken-links",
     "build": "tsc -p tsconfig.json && tsx scripts/canvas-a2ui-copy.ts",
     "release:check": "tsx scripts/release-check.ts",
     "ui:install": "pnpm -C ui install",
     "ui:dev": "pnpm -C ui dev",
     "ui:build": "pnpm -C ui build",
-    "start": "tsx src/index.ts",
-    "clawdbot": "tsx src/index.ts",
-    "gateway:watch": "tsx watch --clear-screen=false --include 'src/**/*.ts' src/index.ts gateway --force",
-    "clawdbot:rpc": "tsx src/index.ts agent --mode rpc --json",
+    "start": "tsx src/entry.ts",
+    "clawdbot": "tsx src/entry.ts",
+    "gateway:watch": "tsx watch --clear-screen=false --include 'src/**/*.ts' src/entry.ts gateway --force",
+    "clawdbot:rpc": "tsx src/entry.ts agent --mode rpc --json",
     "lint": "biome check src test && oxlint --type-aware src test --ignore-pattern src/canvas-host/a2ui/a2ui.bundle.js",
     "lint:swift": "swiftlint lint --config .swiftlint.yml && (cd apps/ios && swiftlint lint --config .swiftlint.yml)",
     "lint:fix": "biome check --write --unsafe src && biome format --write src",
@@ -59,6 +67,7 @@
     "test:force": "tsx scripts/test-force.ts",
     "test:coverage": "vitest run --coverage",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:docker:qr": "bash scripts/e2e/qr-import-docker.sh",
     "protocol:gen": "tsx scripts/protocol-gen.ts",
     "protocol:gen:swift": "tsx scripts/protocol-gen-swift.ts",
     "protocol:check": "pnpm protocol:gen && pnpm protocol:gen:swift && git diff --exit-code -- dist/protocol.schema.json apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift",
@@ -75,13 +84,13 @@
     "@clack/prompts": "^0.11.0",
     "@grammyjs/transformer-throttler": "^1.2.1",
     "@homebridge/ciao": "^1.3.4",
-    "@mariozechner/pi-agent-core": "^0.32.3",
-    "@mariozechner/pi-ai": "^0.32.3",
-    "@mariozechner/pi-coding-agent": "^0.32.3",
-    "@mariozechner/pi-tui": "^0.32.3",
-    "@slack/bolt": "^4.5.0",
-    "@slack/web-api": "^7.11.1",
+    "@mariozechner/pi-agent-core": "^0.36.0",
+    "@mariozechner/pi-ai": "^0.36.0",
+    "@mariozechner/pi-coding-agent": "^0.36.0",
+    "@mariozechner/pi-tui": "^0.36.0",
     "@sinclair/typebox": "0.34.46",
+    "@slack/bolt": "^4.6.0",
+    "@slack/web-api": "^7.13.0",
     "@whiskeysockets/baileys": "7.0.0-rc.9",
     "ajv": "^8.17.1",
     "body-parser": "^2.2.1",
@@ -91,11 +100,11 @@
     "commander": "^14.0.2",
     "croner": "^9.1.0",
     "detect-libc": "^2.1.2",
-    "discord-api-types": "^0.38.33",
+    "discord-api-types": "^0.38.37",
     "discord.js": "^14.25.1",
     "dotenv": "^17.2.3",
     "express": "^5.2.1",
-    "file-type": "^21.2.0",
+    "file-type": "^21.3.0",
     "grammy": "^1.39.2",
     "json5": "^2.2.3",
     "long": "5.3.2",
@@ -103,12 +112,12 @@
     "qrcode-terminal": "^0.12.0",
     "sharp": "^0.34.5",
     "tslog": "^4.10.2",
-    "undici": "^7.16.0",
-    "ws": "^8.18.3",
-    "zod": "^4.3.4"
+    "undici": "^7.18.0",
+    "ws": "^8.19.0",
+    "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.10",
+    "@biomejs/biome": "^2.3.11",
     "@lit-labs/signals": "^0.2.0",
     "@lit/context": "^1.1.6",
     "@mariozechner/mini-lit": "0.2.1",
@@ -125,7 +134,7 @@
     "lucide": "^0.562.0",
     "markdown-it": "^14.1.0",
     "ollama": "^0.6.3",
-    "oxlint": "^1.36.0",
+    "oxlint": "^1.37.0",
     "oxlint-tsgolint": "^0.10.1",
     "quicktype-core": "^23.2.6",
     "rolldown": "1.0.0-beta.58",
@@ -140,7 +149,8 @@
       "@sinclair/typebox": "0.34.46"
     },
     "patchedDependencies": {
-      "@mariozechner/pi-ai": "patches/@mariozechner__pi-ai.patch"
+      "@mariozechner/pi-ai": "patches/@mariozechner__pi-ai.patch",
+      "qrcode-terminal": "patches/qrcode-terminal.patch"
     }
   },
   "vitest": {

patches/qrcode-terminal.patch

@@ -0,0 +1,12 @@
+diff --git a/lib/main.js b/lib/main.js
+index 488cc1aea9802b3d6ae13aee27556403bec55d1c..3de1f934868d81e8204f00e6a4bf2696a05f7340 100644
+--- a/lib/main.js
++++ b/lib/main.js
+@@ -1,5 +1,5 @@
+-var QRCode = require('./../vendor/QRCode'),
+-    QRErrorCorrectLevel = require('./../vendor/QRCode/QRErrorCorrectLevel'),
++var QRCode = require('./../vendor/QRCode/index.js'),
++    QRErrorCorrectLevel = require('./../vendor/QRCode/QRErrorCorrectLevel.js'),
+     black = "\033[40m  \033[0m",
+     white = "\033[47m  \033[0m",
+     toCell = function (isBlack) {

pnpm-lock.yaml

@@ -11,6 +11,9 @@ patchedDependencies:
   '@mariozechner/pi-ai':
     hash: 628fb051b6f4886984a846a5ee7aa0a571c3360d35b8d114e4684e5edcd100c5
     path: patches/@mariozechner__pi-ai.patch
+  qrcode-terminal:
+    hash: ed82029850dbdf551f5df1de320945af52b8ea8500cc7bd4f39258e7a3d92e12
+    path: patches/qrcode-terminal.patch
 
 importers:
 
@@ -26,25 +29,25 @@ importers:
         specifier: ^1.3.4
         version: 1.3.4
       '@mariozechner/pi-agent-core':
-        specifier: ^0.32.3
-        version: 0.32.3(ws@8.18.3)(zod@4.3.4)
+        specifier: ^0.36.0
+        version: 0.36.0(ws@8.19.0)(zod@4.3.5)
       '@mariozechner/pi-ai':
-        specifier: ^0.32.3
-        version: 0.32.3(patch_hash=628fb051b6f4886984a846a5ee7aa0a571c3360d35b8d114e4684e5edcd100c5)(ws@8.18.3)(zod@4.3.4)
+        specifier: ^0.36.0
+        version: 0.36.0(patch_hash=628fb051b6f4886984a846a5ee7aa0a571c3360d35b8d114e4684e5edcd100c5)(ws@8.19.0)(zod@4.3.5)
       '@mariozechner/pi-coding-agent':
-        specifier: ^0.32.3
-        version: 0.32.3(ws@8.18.3)(zod@4.3.4)
+        specifier: ^0.36.0
+        version: 0.36.0(ws@8.19.0)(zod@4.3.5)
       '@mariozechner/pi-tui':
-        specifier: ^0.32.3
-        version: 0.32.3
+        specifier: ^0.36.0
+        version: 0.36.0
       '@sinclair/typebox':
         specifier: 0.34.46
         version: 0.34.46
       '@slack/bolt':
-        specifier: ^4.5.0
+        specifier: ^4.6.0
         version: 4.6.0(@types/express@5.0.6)
       '@slack/web-api':
-        specifier: ^7.11.1
+        specifier: ^7.13.0
         version: 7.13.0
       '@whiskeysockets/baileys':
         specifier: 7.0.0-rc.9
@@ -74,7 +77,7 @@ importers:
         specifier: ^2.1.2
         version: 2.1.2
       discord-api-types:
-        specifier: ^0.38.33
+        specifier: ^0.38.37
         version: 0.38.37
       discord.js:
         specifier: ^14.25.1
@@ -86,8 +89,8 @@ importers:
         specifier: ^5.2.1
         version: 5.2.1
       file-type:
-        specifier: ^21.2.0
-        version: 21.2.0
+        specifier: ^21.3.0
+        version: 21.3.0
       grammy:
         specifier: ^1.39.2
         version: 1.39.2
@@ -102,7 +105,7 @@ importers:
         version: 1.57.0
       qrcode-terminal:
         specifier: ^0.12.0
-        version: 0.12.0
+        version: 0.12.0(patch_hash=ed82029850dbdf551f5df1de320945af52b8ea8500cc7bd4f39258e7a3d92e12)
       sharp:
         specifier: ^0.34.5
         version: 0.34.5
@@ -110,18 +113,18 @@ importers:
         specifier: ^4.10.2
         version: 4.10.2
       undici:
-        specifier: ^7.16.0
-        version: 7.16.0
+        specifier: ^7.18.0
+        version: 7.18.0
       ws:
-        specifier: ^8.18.3
-        version: 8.18.3
+        specifier: ^8.19.0
+        version: 8.19.0
       zod:
-        specifier: ^4.3.4
-        version: 4.3.4
+        specifier: ^4.3.5
+        version: 4.3.5
     devDependencies:
       '@biomejs/biome':
-        specifier: ^2.3.10
-        version: 2.3.10
+        specifier: ^2.3.11
+        version: 2.3.11
       '@lit-labs/signals':
         specifier: ^0.2.0
         version: 0.2.0
@@ -171,8 +174,8 @@ importers:
         specifier: ^0.6.3
         version: 0.6.3
       oxlint:
-        specifier: ^1.36.0
-        version: 1.36.0(oxlint-tsgolint@0.10.1)
+        specifier: ^1.37.0
+        version: 1.37.0(oxlint-tsgolint@0.10.1)
       oxlint-tsgolint:
         specifier: ^0.10.1
         version: 0.10.1
@@ -200,9 +203,15 @@ importers:
 
   ui:
     dependencies:
+      dompurify:
+        specifier: ^3.3.1
+        version: 3.3.1
       lit:
         specifier: ^3.3.2
         version: 3.3.2
+      marked:
+        specifier: ^17.0.1
+        version: 17.0.1
     devDependencies:
       '@vitest/browser-playwright':
         specifier: 4.0.16
@@ -260,55 +269,55 @@ packages:
     resolution: {integrity: sha512-6zABk/ECA/QYSCQ1NGiVwwbQerUCZ+TQbp64Q3AgmfNvurHH0j8TtXa1qbShXA6qqkpAj4V5W8pP6mLe1mcMqA==}
     engines: {node: '>=18'}
 
-  '@biomejs/biome@2.3.10':
-    resolution: {integrity: sha512-/uWSUd1MHX2fjqNLHNL6zLYWBbrJeG412/8H7ESuK8ewoRoMPUgHDebqKrPTx/5n6f17Xzqc9hdg3MEqA5hXnQ==}
+  '@biomejs/biome@2.3.11':
+    resolution: {integrity: sha512-/zt+6qazBWguPG6+eWmiELqO+9jRsMZ/DBU3lfuU2ngtIQYzymocHhKiZRyrbra4aCOoyTg/BmY+6WH5mv9xmQ==}
     engines: {node: '>=14.21.3'}
     hasBin: true
 
-  '@biomejs/cli-darwin-arm64@2.3.10':
-    resolution: {integrity: sha512-M6xUjtCVnNGFfK7HMNKa593nb7fwNm43fq1Mt71kpLpb+4mE7odO8W/oWVDyBVO4ackhresy1ZYO7OJcVo/B7w==}
+  '@biomejs/cli-darwin-arm64@2.3.11':
+    resolution: {integrity: sha512-/uXXkBcPKVQY7rc9Ys2CrlirBJYbpESEDme7RKiBD6MmqR2w3j0+ZZXRIL2xiaNPsIMMNhP1YnA+jRRxoOAFrA==}
     engines: {node: '>=14.21.3'}
     cpu: [arm64]
     os: [darwin]
 
-  '@biomejs/cli-darwin-x64@2.3.10':
-    resolution: {integrity: sha512-Vae7+V6t/Avr8tVbFNjnFSTKZogZHFYl7MMH62P/J1kZtr0tyRQ9Fe0onjqjS2Ek9lmNLmZc/VR5uSekh+p1fg==}
+  '@biomejs/cli-darwin-x64@2.3.11':
+    resolution: {integrity: sha512-fh7nnvbweDPm2xEmFjfmq7zSUiox88plgdHF9OIW4i99WnXrAC3o2P3ag9judoUMv8FCSUnlwJCM1B64nO5Fbg==}
     engines: {node: '>=14.21.3'}
     cpu: [x64]
     os: [darwin]
 
-  '@biomejs/cli-linux-arm64-musl@2.3.10':
-    resolution: {integrity: sha512-B9DszIHkuKtOH2IFeeVkQmSMVUjss9KtHaNXquYYWCjH8IstNgXgx5B0aSBQNr6mn4RcKKRQZXn9Zu1rM3O0/A==}
+  '@biomejs/cli-linux-arm64-musl@2.3.11':
+    resolution: {integrity: sha512-XPSQ+XIPZMLaZ6zveQdwNjbX+QdROEd1zPgMwD47zvHV+tCGB88VH+aynyGxAHdzL+Tm/+DtKST5SECs4iwCLg==}
     engines: {node: '>=14.21.3'}
     cpu: [arm64]
     os: [linux]
 
-  '@biomejs/cli-linux-arm64@2.3.10':
-    resolution: {integrity: sha512-hhPw2V3/EpHKsileVOFynuWiKRgFEV48cLe0eA+G2wO4SzlwEhLEB9LhlSrVeu2mtSn205W283LkX7Fh48CaxA==}
+  '@biomejs/cli-linux-arm64@2.3.11':
+    resolution: {integrity: sha512-l4xkGa9E7Uc0/05qU2lMYfN1H+fzzkHgaJoy98wO+b/7Gl78srbCRRgwYSW+BTLixTBrM6Ede5NSBwt7rd/i6g==}
     engines: {node: '>=14.21.3'}
     cpu: [arm64]
     os: [linux]
 
-  '@biomejs/cli-linux-x64-musl@2.3.10':
-    resolution: {integrity: sha512-QTfHZQh62SDFdYc2nfmZFuTm5yYb4eO1zwfB+90YxUumRCR171tS1GoTX5OD0wrv4UsziMPmrePMtkTnNyYG3g==}
+  '@biomejs/cli-linux-x64-musl@2.3.11':
+    resolution: {integrity: sha512-vU7a8wLs5C9yJ4CB8a44r12aXYb8yYgBn+WeyzbMjaCMklzCv1oXr8x+VEyWodgJt9bDmhiaW/I0RHbn7rsNmw==}
     engines: {node: '>=14.21.3'}
     cpu: [x64]
     os: [linux]
 
-  '@biomejs/cli-linux-x64@2.3.10':
-    resolution: {integrity: sha512-wwAkWD1MR95u+J4LkWP74/vGz+tRrIQvr8kfMMJY8KOQ8+HMVleREOcPYsQX82S7uueco60L58Wc6M1I9WA9Dw==}
+  '@biomejs/cli-linux-x64@2.3.11':
+    resolution: {integrity: sha512-/1s9V/H3cSe0r0Mv/Z8JryF5x9ywRxywomqZVLHAoa/uN0eY7F8gEngWKNS5vbbN/BsfpCG5yeBT5ENh50Frxg==}
     engines: {node: '>=14.21.3'}
     cpu: [x64]
     os: [linux]
 
-  '@biomejs/cli-win32-arm64@2.3.10':
-    resolution: {integrity: sha512-o7lYc9n+CfRbHvkjPhm8s9FgbKdYZu5HCcGVMItLjz93EhgJ8AM44W+QckDqLA9MKDNFrR8nPbO4b73VC5kGGQ==}
+  '@biomejs/cli-win32-arm64@2.3.11':
+    resolution: {integrity: sha512-PZQ6ElCOnkYapSsysiTy0+fYX+agXPlWugh6+eQ6uPKI3vKAqNp6TnMhoM3oY2NltSB89hz59o8xIfOdyhi9Iw==}
     engines: {node: '>=14.21.3'}
     cpu: [arm64]
     os: [win32]
 
-  '@biomejs/cli-win32-x64@2.3.10':
-    resolution: {integrity: sha512-pHEFgq7dUEsKnqG9mx9bXihxGI49X+ar+UBrEIj3Wqj3UCZp1rNgV+OoyjFgcXsjCWpuEAF4VJdkZr3TrWdCbQ==}
+  '@biomejs/cli-win32-x64@2.3.11':
+    resolution: {integrity: sha512-43VrG813EW+b5+YbDbz31uUsheX+qFKCpXeY9kfdAx+ww3naKxeVkTD9zLIWxUPfJquANMHrmW3wbe/037G0Qg==}
     engines: {node: '>=14.21.3'}
     cpu: [x64]
     os: [win32]
@@ -332,6 +341,57 @@ packages:
   '@clack/prompts@0.11.0':
     resolution: {integrity: sha512-pMN5FcrEw9hUkZA4f+zLlzivQSeQf5dRGJjSUbvVYDLvpKCdQx5OaknvKzgbtXOizhP+SJJJjqEbOe55uKKfAw==}
 
+  '@crosscopy/clipboard-darwin-arm64@0.2.8':
+    resolution: {integrity: sha512-Y36ST9k5JZgtDE6SBT45bDNkPKBHd4UEIZgWnC0iC4kAWwdjPmsZ8Mn8e5W0YUKowJ/BDcO+EGm2tVTPQOQKXg==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@crosscopy/clipboard-darwin-universal@0.2.8':
+    resolution: {integrity: sha512-btGV1tLpJWZ4iKa66niahvpZpVRJzgQnYUE+PUX3YYZzaWD0ESuHuVtKVC8sR+b4dsXIiWW5skXbcRmLsF4rtA==}
+    engines: {node: '>= 10'}
+    os: [darwin]
+
+  '@crosscopy/clipboard-darwin-x64@0.2.8':
+    resolution: {integrity: sha512-0QMKf0XrLZrprYYXU4lgaTuzbnYPh9wH6PvsfDB1FZvWf6rOi0syTaBZYnoghbQe700qwLPEfBRjgljJ3Tn6oA==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@crosscopy/clipboard-linux-arm64-gnu@0.2.8':
+    resolution: {integrity: sha512-8YrU03MRsygymqEcHkNgqCqSCQbYRmJCnMXeS4i8FYeOkAxBEeRvPbHoNmI10uppXJZNZgfIKM7Qqk9tEHiwqQ==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@crosscopy/clipboard-linux-riscv64-gnu@0.2.8':
+    resolution: {integrity: sha512-/QWLhnb0QYVjEv5GOAC1q+1DaezYU8Th+IoDKUCsR5i43Cqm+g+N/I2K35yo3J+HHkK9XNbtIDZDXlFgK6tRUg==}
+    engines: {node: '>= 10'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@crosscopy/clipboard-linux-x64-gnu@0.2.8':
+    resolution: {integrity: sha512-j17eaF/onP/6VAGGKtxA1KmmkErmdjta9gMdMV/yUmgeBYzJ9fMpWUzbk2vmaOyXfhaSzR/sk1P6VLBmvCpqHg==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+
+  '@crosscopy/clipboard-win32-arm64-msvc@0.2.8':
+    resolution: {integrity: sha512-MVkMyuYN3y5v0s4HrijM0iA8hZVmpUhHd8X4zKG30t4nE6MbOjOt/8EabMrVmGZlsLeOL2sa0o8Wo9bvhWU+vA==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@crosscopy/clipboard-win32-x64-msvc@0.2.8':
+    resolution: {integrity: sha512-/GpiB4B3lSgg7eCLDQw9NfFjtQFjo0S88IL+EK54Hx7ZgAP4Ad/ezP/8dw0cA+N/M6iPYy0reCIjW9st82/uxw==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [win32]
+
+  '@crosscopy/clipboard@0.2.8':
+    resolution: {integrity: sha512-0qRWscafAHzQ+DdfXX+YgPN2KDTIzWBNfN5Q6z1CgCWsRxtkwK8HfQUc00xIejfRWSGWPIxcCTg82hvg06bodg==}
+    engines: {node: '>= 10'}
+
   '@discordjs/builders@1.13.1':
     resolution: {integrity: sha512-cOU0UDHc3lp/5nKByDxkmRiNZBpdp0kx55aarbiAfakfKJHlxv/yFW1zmIqCAmwH5CRlrH9iMFKJMpvW4DPB+w==}
     engines: {node: '>=16.11.0'}
@@ -360,11 +420,11 @@ packages:
     resolution: {integrity: sha512-wPlQDxEmlDg5IxhJPuxXr3Vy9AjYq5xCvFWGJyD7w7Np8ZGu+Mc+97LCoEc/+AYCo2IDpKioiH0/c/mj5ZR9Uw==}
     engines: {node: '>=16.11.0'}
 
-  '@emnapi/core@1.7.1':
-    resolution: {integrity: sha512-o1uhUASyo921r2XtHYOHy7gdkGLge8ghBEQHMWmyJFoXlpU58kIrhhN3w26lpQb6dspetweapMn2CSNwQ8I4wg==}
+  '@emnapi/core@1.8.1':
+    resolution: {integrity: sha512-AvT9QFpxK0Zd8J0jopedNm+w/2fIzvtPKPjqyw9jwvBaReTTqPBk9Hixaz7KbjimP+QNz605/XnjFcDAL2pqBg==}
 
-  '@emnapi/runtime@1.7.1':
-    resolution: {integrity: sha512-PVtJr5CmLwYAU9PZDMITZoR5iAOShYREoR45EyyLrbntV50mdePTgUn4AmOw90Ifcj+x2kRjdzr1HP3RrNiHGA==}
+  '@emnapi/runtime@1.8.1':
+    resolution: {integrity: sha512-mehfKSMWjjNol8659Z8KxEMrdSJDDot5SXMq00dM8BN4o+CLNXQ0xH2V7EchNHV4RmbZLmmPdEaXZc5H2FXmDg==}
 
   '@emnapi/wasi-threads@1.1.0':
     resolution: {integrity: sha512-WI0DdZ8xFSbgMjR1sFsKABJ/C5OnRrjT06JXbZKexJGrDuPTzZdDYfFlsgcCXCyf+suG5QU2e/y1Wo2V/OapLQ==}
@@ -744,22 +804,22 @@ packages:
     peerDependencies:
       lit: ^3.3.1
 
-  '@mariozechner/pi-agent-core@0.32.3':
-    resolution: {integrity: sha512-NN/fd8eBISnRbQYblLjiaRbcFjz+SEFOGhZDZCXYgHJikTV8VyEon0nZFh7agBZJ7sXZaumMTjw/pGFrBFKcmA==}
+  '@mariozechner/pi-agent-core@0.36.0':
+    resolution: {integrity: sha512-86BI1/j/MLxQHSWRXVLz8+NuSmDvLQebNb40+lFDI9XI9YBh8+r5fkYgU43u4j2TvANZ7iW6SFFnhWhzy8y6dg==}
     engines: {node: '>=20.0.0'}
 
-  '@mariozechner/pi-ai@0.32.3':
-    resolution: {integrity: sha512-njaa4/pN7U1TbjI1PKqII3M/W1CQ/obPAu5A4KHsX74e8sKjDEiEELUWzLTa5xOj+l1OXp/FtzI0hfJDq682rQ==}
+  '@mariozechner/pi-ai@0.36.0':
+    resolution: {integrity: sha512-xkzTgvdMzAZ/L/TgMH8z9Zi+aH0EWc54l5ygiafwvCgDk7xvfbylQG6pa9yn5zEn9T4NF9byJNk+nMHnycZvMQ==}
     engines: {node: '>=20.0.0'}
     hasBin: true
 
-  '@mariozechner/pi-coding-agent@0.32.3':
-    resolution: {integrity: sha512-kOuzflbWc8GWHGOu/7KJQ1P3IodDk4AdOvibkJDcAn2aw5kG+LZAjLGt72tIMQRQna51i9XzL4nSvbxqV+mgWw==}
+  '@mariozechner/pi-coding-agent@0.36.0':
+    resolution: {integrity: sha512-lKdpuGE0yVs/96GnDhrPLEEFhRteHRtnkfX04KIBpcsEXXg2vyAlpxtjtZ9nlhYqLLIY7qJRkeyjbhcFFfbAAA==}
     engines: {node: '>=20.0.0'}
     hasBin: true
 
-  '@mariozechner/pi-tui@0.32.3':
-    resolution: {integrity: sha512-aq7e6qXcwSHvaTUKj5Ut9BY+ZezQ2rL+V4Sd2R5SnBW6JMCt5GnR/8uYBC2PcdxBQzGL9TnzjrC4av5jR+ilow==}
+  '@mariozechner/pi-tui@0.36.0':
+    resolution: {integrity: sha512-4n+nmTd36q0AVCbqWmjtTHTjIEwlGayKKhc+4QbpN9U3Z9jyQQa8Za1P2OHRmi6Jeu+ISuf4VBDvgmgCaxPZYg==}
     engines: {node: '>=20.0.0'}
 
   '@mistralai/mistralai@1.10.0':
@@ -813,43 +873,43 @@ packages:
     cpu: [x64]
     os: [win32]
 
-  '@oxlint/darwin-arm64@1.36.0':
-    resolution: {integrity: sha512-MJkj82GH+nhvWKJhSIM6KlZ8tyGKdogSQXtNdpIyP02r/tTayFJQaAEWayG2Jhsn93kske+nimg5MYFhwO/rlg==}
+  '@oxlint/darwin-arm64@1.37.0':
+    resolution: {integrity: sha512-qDa8qf4Th3sbk6P6wRbsv5paGeZ8EEOy8PtnT2IkAYSzjDHavw8nMK/lQvf6uS7LArjcmOfM1Y3KnZUFoNZZqg==}
     cpu: [arm64]
     os: [darwin]
 
-  '@oxlint/darwin-x64@1.36.0':
-    resolution: {integrity: sha512-VvEhfkqj/99dCTqOcfkyFXOSbx4lIy5u2m2GHbK4WCMDySokOcMTNRHGw8fH/WgQ5cDrDMSTYIGQTmnBGi9tiQ==}
+  '@oxlint/darwin-x64@1.37.0':
+    resolution: {integrity: sha512-FM0h0KyOQ4HCdhIX1ne6d80BxRra75h1ORce0jYNwQ49HT4RU8+9ywSMC7rQ79xWsmaahvkQPB7tMPyfjsQwAg==}
     cpu: [x64]
     os: [darwin]
 
-  '@oxlint/linux-arm64-gnu@1.36.0':
-    resolution: {integrity: sha512-EMx92X5q+hHc3olTuj/kgkx9+yP0p/AVs4yvHbUfzZhBekXNpUWxWvg4hIKmQWn+Ee2j4o80/0ACGO0hDYJ9mg==}
+  '@oxlint/linux-arm64-gnu@1.37.0':
+    resolution: {integrity: sha512-2axK0lftGwM6Q7wOuY2sassUqa4MKrG3iemVVyEpXzJ6g5QosxhCoFPp9v81/gmLT5kAdd2gskoDcfpDJliDNw==}
     cpu: [arm64]
     os: [linux]
 
-  '@oxlint/linux-arm64-musl@1.36.0':
-    resolution: {integrity: sha512-7YCxtrPIctVYLqWrWkk8pahdCxch6PtsaucfMLC7TOlDt4nODhnQd4yzEscKqJ8Gjrw1bF4g+Ngob1gB+Qr9Fw==}
+  '@oxlint/linux-arm64-musl@1.37.0':
+    resolution: {integrity: sha512-f3YROyGMIdUeXx0yD7RsAUBzBvD222D4l2GQRYF3AMxyp9mya17Rq/3wNLR4JDnAnboOul3DAEKNm+09lo3uZw==}
     cpu: [arm64]
     os: [linux]
 
-  '@oxlint/linux-x64-gnu@1.36.0':
-    resolution: {integrity: sha512-lnaJVlx5r3NWmoOMesfQXJSf78jHTn8Z+sdAf795Kgteo72+qGC1Uax2SToCJVN2J8PNG3oRV5bLriiCNR2i6Q==}
+  '@oxlint/linux-x64-gnu@1.37.0':
+    resolution: {integrity: sha512-FANOdOVQ2c4acYLM0dvtSoKELHSSnDBxDdm8OlXNzSRanQILrNpLgUqCXHFsfiHipFfNzz3Z417PxV6X4aBYog==}
     cpu: [x64]
     os: [linux]
 
-  '@oxlint/linux-x64-musl@1.36.0':
-    resolution: {integrity: sha512-AhuEU2Qdl66lSfTGu/Htirq8r/8q2YnZoG3yEXLMQWnPMn7efy8spD/N1NA7kH0Hll+cdfwgQkQqC2G4MS2lPQ==}
+  '@oxlint/linux-x64-musl@1.37.0':
+    resolution: {integrity: sha512-eYnSKT9knXdOQ9h+6nSjEHSx0+pW8PkGwtMNGXtCYR+/ZPKYIbtZVS0nZsFy+qizP+TRVSJrgc/JY3Xr0wjcQg==}
     cpu: [x64]
     os: [linux]
 
-  '@oxlint/win32-arm64@1.36.0':
-    resolution: {integrity: sha512-GlWCBjUJY2QgvBFuNRkiRJu7K/djLmM0UQKfZV8IN+UXbP/JbjZHWKRdd4LXlQmzoz7M5Hd6p+ElCej8/90FCg==}
+  '@oxlint/win32-arm64@1.37.0':
+    resolution: {integrity: sha512-2oHxNc4jcocfNWGWVVWQdEG+reZ5ncBZsmDoICJQ1rbCDx4Yimx8VUf1Ub9cCoJRcPiSLBxMqaeMaDClKixJIQ==}
     cpu: [arm64]
     os: [win32]
 
-  '@oxlint/win32-x64@1.36.0':
-    resolution: {integrity: sha512-J+Vc00Utcf8p77lZPruQgb0QnQXuKnFogN88kCnOqs2a83I+vTBB8ILr0+L9sTwVRvIDMSC0pLdeQH4svWGFZg==}
+  '@oxlint/win32-x64@1.37.0':
+    resolution: {integrity: sha512-w+pBuTjGmGCGPhDjFhj/97K2tlGyq5LKAU6S7FHxROPuJRWJD6uio1L75Lsb8fKhwtw2rm54LLOX30Yi+nILxw==}
     cpu: [x64]
     os: [win32]
 
@@ -1627,6 +1687,9 @@ packages:
   dom-accessibility-api@0.5.16:
     resolution: {integrity: sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==}
 
+  dompurify@3.3.1:
+    resolution: {integrity: sha512-qkdCKzLNtrgPFP1Vo+98FRzJnBRGe4ffyCea9IwHB1fyxPOeNTHpLKYGd4Uk9xvNoH0ZoOjwZxNptyMwqrId1Q==}
+
   dotenv@17.2.3:
     resolution: {integrity: sha512-JVUnt+DUIzu87TABbhPmNfVdBDt18BLOWjMUFJMSi/Qqg7NTYtabbvSNJGOJ7afbRuv9D/lngizHtP7QyLQ+9w==}
     engines: {node: '>=12'}
@@ -1747,8 +1810,8 @@ packages:
     resolution: {integrity: sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==}
     engines: {node: ^12.20 || >= 14.13}
 
-  file-type@21.2.0:
-    resolution: {integrity: sha512-vCYBgFOrJQLoTzDyAXAL/RFfKnXXpUYt4+tipVy26nJJhT7ftgGETf2tAQF59EEL61i3MrorV/PG6tf7LJK7eg==}
+  file-type@21.3.0:
+    resolution: {integrity: sha512-8kPJMIGz1Yt/aPEwOsrR97ZyZaD1Iqm8PClb1nYFclUCkBi0Ma5IsYNQzvSFS9ib51lWyIw5mIT9rWzI/xjpzA==}
     engines: {node: '>=20'}
 
   fill-range@7.1.1:
@@ -1891,8 +1954,8 @@ packages:
     resolution: {integrity: sha512-Xwwo44whKBVCYoliBQwaPvtd/2tYFkRQtXDWj1nackaV2JPXx3L0+Jvd8/qCJ2p+ML0/XVkJ2q+Mr+UVdpJK5w==}
     engines: {node: '>=12.0.0'}
 
-  hookified@1.14.0:
-    resolution: {integrity: sha512-pi1ynXIMFx/uIIwpWJ/5CEtOHLGtnUB0WhGeeYT+fKcQ+WCQbm3/rrkAXnpfph++PgepNqPdTC2WTj8A6k6zoQ==}
+  hookified@1.15.0:
+    resolution: {integrity: sha512-51w+ZZGt7Zw5q7rM3nC4t3aLn/xvKDETsXqMczndvwyVQhAHfUmUuFBRFcos8Iyebtk7OAE9dL26wFNzZVVOkw==}
 
   html-escaper@2.0.2:
     resolution: {integrity: sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==}
@@ -2200,6 +2263,11 @@ packages:
     engines: {node: '>= 20'}
     hasBin: true
 
+  marked@17.0.1:
+    resolution: {integrity: sha512-boeBdiS0ghpWcSwoNm/jJBwdpFaMnZWRzjA6SkUMYb40SVaN1x7mmfGKp0jvexGcx+7y2La5zRZsYFZI6Qpypg==}
+    engines: {node: '>= 20'}
+    hasBin: true
+
   math-intrinsics@1.1.0:
     resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==}
     engines: {node: '>= 0.4'}
@@ -2353,8 +2421,8 @@ packages:
     resolution: {integrity: sha512-EEHNdo5cW2w1xwYdBQ7d3IXDqWAtMkfVFrh+9gQ4kYbYJwygY4QXSh1eH80/xVipZdVKujAwBgg/nNNHk56kxQ==}
     hasBin: true
 
-  oxlint@1.36.0:
-    resolution: {integrity: sha512-IicUdXfXgI8OKrDPnoSjvBfeEF8PkKtm+CoLlg4LYe4ypc8U+T4r7730XYshdBGZdelg+JRw8GtCb2w/KaaZvw==}
+  oxlint@1.37.0:
+    resolution: {integrity: sha512-MAw0JH8M5/vt9E2WxSsmJu53bVLmG6qNlVw1OXFenJYItTPbMBtW7j3n53+tgNhNuxFPundM1DR7V8E39qOOrg==}
     engines: {node: ^20.19.0 || >=22.12.0}
     hasBin: true
     peerDependencies:
@@ -2371,8 +2439,8 @@ packages:
     resolution: {integrity: sha512-RwFpb72c/BhQLEXIZ5K2e+AhgNVmIejGlTgiB9MzZ0e93GRvqZ7uSi0dvRF7/XIXDeNkra2fNHBxTyPDGySpjQ==}
     engines: {node: '>=8'}
 
-  p-queue@9.0.1:
-    resolution: {integrity: sha512-RhBdVhSwJb7Ocn3e8ULk4NMwBEuOxe+1zcgphUy9c2e5aR/xbEsdVXxHJ3lynw6Qiqu7OINEyHlZkiblEpaq7w==}
+  p-queue@9.1.0:
+    resolution: {integrity: sha512-O/ZPaXuQV29uSLbxWBGGZO1mCQXV2BLIwUr59JUU9SoH76mnYvtms7aafH/isNSNGwuEfP6W/4xD0/TJXxrizw==}
     engines: {node: '>=20'}
 
   p-retry@4.6.2:
@@ -2868,8 +2936,8 @@ packages:
     resolution: {integrity: sha512-gBLkYIlEnSp8pFbT64yFgGE6UIB9tAkhukC23PmMDCe5Nd+cRqKxSjw5y54MK2AZMgZfJWMaNE4nYUHgi1XEOw==}
     engines: {node: '>=18.17'}
 
-  undici@7.16.0:
-    resolution: {integrity: sha512-QEg3HPMll0o3t2ourKwOeUAZ159Kn9mx5pnzHRQO8+Wixmh88YdZRiIwat0iNzNNXn0yoEtXJqFpyW7eM8BV7g==}
+  undici@7.18.0:
+    resolution: {integrity: sha512-CfPufgPFHCYu0W4h1NiKW9+tNJ39o3kWm7Cm29ET1enSJx+AERfz7A2wAr26aY0SZbYzZlTBQtcHy15o60VZfQ==}
     engines: {node: '>=20.18.1'}
 
   unicode-properties@1.4.1:
@@ -3008,8 +3076,8 @@ packages:
   wrappy@1.0.2:
     resolution: {integrity: sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==}
 
-  ws@8.18.3:
-    resolution: {integrity: sha512-PEIGCY5tSlUt50cqyMXfCzX+oOPqN0vuGqWzbcJ2xvnkzkq46oOpz7dQaTDBdfICb4N14+GARUDw2XV2N4tvzg==}
+  ws@8.19.0:
+    resolution: {integrity: sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg==}
     engines: {node: '>=10.0.0'}
     peerDependencies:
       bufferutil: ^4.0.1
@@ -3045,16 +3113,16 @@ packages:
   zod@3.25.76:
     resolution: {integrity: sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==}
 
-  zod@4.3.4:
-    resolution: {integrity: sha512-Zw/uYiiyF6pUT1qmKbZziChgNPRu+ZRneAsMUDU6IwmXdWt5JwcUfy2bvLOCUtz5UniaN/Zx5aFttZYbYc7O/A==}
+  zod@4.3.5:
+    resolution: {integrity: sha512-k7Nwx6vuWx1IJ9Bjuf4Zt1PEllcwe7cls3VNzm4CQ1/hgtFUK2bRNG3rvnpPUhFjmqJKAKtjV576KnUkHocg/g==}
 
 snapshots:
 
-  '@anthropic-ai/sdk@0.71.2(zod@4.3.4)':
+  '@anthropic-ai/sdk@0.71.2(zod@4.3.5)':
     dependencies:
       json-schema-to-ts: 3.1.1
     optionalDependencies:
-      zod: 4.3.4
+      zod: 4.3.5
 
   '@babel/code-frame@7.27.1':
     dependencies:
@@ -3080,39 +3148,39 @@ snapshots:
 
   '@bcoe/v8-coverage@1.0.2': {}
 
-  '@biomejs/biome@2.3.10':
+  '@biomejs/biome@2.3.11':
     optionalDependencies:
-      '@biomejs/cli-darwin-arm64': 2.3.10
-      '@biomejs/cli-darwin-x64': 2.3.10
-      '@biomejs/cli-linux-arm64': 2.3.10
-      '@biomejs/cli-linux-arm64-musl': 2.3.10
-      '@biomejs/cli-linux-x64': 2.3.10
-      '@biomejs/cli-linux-x64-musl': 2.3.10
-      '@biomejs/cli-win32-arm64': 2.3.10
-      '@biomejs/cli-win32-x64': 2.3.10
+      '@biomejs/cli-darwin-arm64': 2.3.11
+      '@biomejs/cli-darwin-x64': 2.3.11
+      '@biomejs/cli-linux-arm64': 2.3.11
+      '@biomejs/cli-linux-arm64-musl': 2.3.11
+      '@biomejs/cli-linux-x64': 2.3.11
+      '@biomejs/cli-linux-x64-musl': 2.3.11
+      '@biomejs/cli-win32-arm64': 2.3.11
+      '@biomejs/cli-win32-x64': 2.3.11
 
-  '@biomejs/cli-darwin-arm64@2.3.10':
+  '@biomejs/cli-darwin-arm64@2.3.11':
     optional: true
 
-  '@biomejs/cli-darwin-x64@2.3.10':
+  '@biomejs/cli-darwin-x64@2.3.11':
     optional: true
 
-  '@biomejs/cli-linux-arm64-musl@2.3.10':
+  '@biomejs/cli-linux-arm64-musl@2.3.11':
     optional: true
 
-  '@biomejs/cli-linux-arm64@2.3.10':
+  '@biomejs/cli-linux-arm64@2.3.11':
     optional: true
 
-  '@biomejs/cli-linux-x64-musl@2.3.10':
+  '@biomejs/cli-linux-x64-musl@2.3.11':
     optional: true
 
-  '@biomejs/cli-linux-x64@2.3.10':
+  '@biomejs/cli-linux-x64@2.3.11':
     optional: true
 
-  '@biomejs/cli-win32-arm64@2.3.10':
+  '@biomejs/cli-win32-arm64@2.3.11':
     optional: true
 
-  '@biomejs/cli-win32-x64@2.3.10':
+  '@biomejs/cli-win32-x64@2.3.11':
     optional: true
 
   '@borewit/text-codec@0.2.1': {}
@@ -3121,13 +3189,13 @@ snapshots:
     dependencies:
       '@cacheable/utils': 2.3.3
       '@keyv/bigmap': 1.3.0(keyv@5.5.5)
-      hookified: 1.14.0
+      hookified: 1.15.0
       keyv: 5.5.5
 
   '@cacheable/node-cache@1.7.6':
     dependencies:
       cacheable: 2.3.1
-      hookified: 1.14.0
+      hookified: 1.15.0
       keyv: 5.5.5
 
   '@cacheable/utils@2.3.3':
@@ -3146,6 +3214,41 @@ snapshots:
       picocolors: 1.1.1
       sisteransi: 1.0.5
 
+  '@crosscopy/clipboard-darwin-arm64@0.2.8':
+    optional: true
+
+  '@crosscopy/clipboard-darwin-universal@0.2.8':
+    optional: true
+
+  '@crosscopy/clipboard-darwin-x64@0.2.8':
+    optional: true
+
+  '@crosscopy/clipboard-linux-arm64-gnu@0.2.8':
+    optional: true
+
+  '@crosscopy/clipboard-linux-riscv64-gnu@0.2.8':
+    optional: true
+
+  '@crosscopy/clipboard-linux-x64-gnu@0.2.8':
+    optional: true
+
+  '@crosscopy/clipboard-win32-arm64-msvc@0.2.8':
+    optional: true
+
+  '@crosscopy/clipboard-win32-x64-msvc@0.2.8':
+    optional: true
+
+  '@crosscopy/clipboard@0.2.8':
+    optionalDependencies:
+      '@crosscopy/clipboard-darwin-arm64': 0.2.8
+      '@crosscopy/clipboard-darwin-universal': 0.2.8
+      '@crosscopy/clipboard-darwin-x64': 0.2.8
+      '@crosscopy/clipboard-linux-arm64-gnu': 0.2.8
+      '@crosscopy/clipboard-linux-riscv64-gnu': 0.2.8
+      '@crosscopy/clipboard-linux-x64-gnu': 0.2.8
+      '@crosscopy/clipboard-win32-arm64-msvc': 0.2.8
+      '@crosscopy/clipboard-win32-x64-msvc': 0.2.8
+
   '@discordjs/builders@1.13.1':
     dependencies:
       '@discordjs/formatters': 0.6.2
@@ -3190,18 +3293,18 @@ snapshots:
       '@vladfrangu/async_event_emitter': 2.4.7
       discord-api-types: 0.38.37
       tslib: 2.8.1
-      ws: 8.18.3
+      ws: 8.19.0
     transitivePeerDependencies:
       - bufferutil
       - utf-8-validate
 
-  '@emnapi/core@1.7.1':
+  '@emnapi/core@1.8.1':
     dependencies:
       '@emnapi/wasi-threads': 1.1.0
       tslib: 2.8.1
     optional: true
 
-  '@emnapi/runtime@1.7.1':
+  '@emnapi/runtime@1.8.1':
     dependencies:
       tslib: 2.8.1
     optional: true
@@ -3297,7 +3400,7 @@ snapshots:
   '@google/genai@1.34.0':
     dependencies:
       google-auth-library: 10.5.0
-      ws: 8.18.3
+      ws: 8.19.0
     transitivePeerDependencies:
       - bufferutil
       - supports-color
@@ -3409,7 +3512,7 @@ snapshots:
 
   '@img/sharp-wasm32@0.34.5':
     dependencies:
-      '@emnapi/runtime': 1.7.1
+      '@emnapi/runtime': 1.8.1
     optional: true
 
   '@img/sharp-win32-arm64@0.34.5':
@@ -3448,7 +3551,7 @@ snapshots:
   '@keyv/bigmap@1.3.0(keyv@5.5.5)':
     dependencies:
       hashery: 1.4.0
-      hookified: 1.14.0
+      hookified: 1.15.0
       keyv: 5.5.5
 
   '@keyv/serialize@1.1.1': {}
@@ -3485,10 +3588,10 @@ snapshots:
     transitivePeerDependencies:
       - tailwindcss
 
-  '@mariozechner/pi-agent-core@0.32.3(ws@8.18.3)(zod@4.3.4)':
+  '@mariozechner/pi-agent-core@0.36.0(ws@8.19.0)(zod@4.3.5)':
     dependencies:
-      '@mariozechner/pi-ai': 0.32.3(patch_hash=628fb051b6f4886984a846a5ee7aa0a571c3360d35b8d114e4684e5edcd100c5)(ws@8.18.3)(zod@4.3.4)
-      '@mariozechner/pi-tui': 0.32.3
+      '@mariozechner/pi-ai': 0.36.0(patch_hash=628fb051b6f4886984a846a5ee7aa0a571c3360d35b8d114e4684e5edcd100c5)(ws@8.19.0)(zod@4.3.5)
+      '@mariozechner/pi-tui': 0.36.0
     transitivePeerDependencies:
       - '@modelcontextprotocol/sdk'
       - bufferutil
@@ -3497,18 +3600,18 @@ snapshots:
       - ws
       - zod
 
-  '@mariozechner/pi-ai@0.32.3(patch_hash=628fb051b6f4886984a846a5ee7aa0a571c3360d35b8d114e4684e5edcd100c5)(ws@8.18.3)(zod@4.3.4)':
+  '@mariozechner/pi-ai@0.36.0(patch_hash=628fb051b6f4886984a846a5ee7aa0a571c3360d35b8d114e4684e5edcd100c5)(ws@8.19.0)(zod@4.3.5)':
     dependencies:
-      '@anthropic-ai/sdk': 0.71.2(zod@4.3.4)
+      '@anthropic-ai/sdk': 0.71.2(zod@4.3.5)
       '@google/genai': 1.34.0
       '@mistralai/mistralai': 1.10.0
       '@sinclair/typebox': 0.34.46
       ajv: 8.17.1
       ajv-formats: 3.0.1(ajv@8.17.1)
       chalk: 5.6.2
-      openai: 6.10.0(ws@8.18.3)(zod@4.3.4)
+      openai: 6.10.0(ws@8.19.0)(zod@4.3.5)
       partial-json: 0.1.7
-      zod-to-json-schema: 3.25.1(zod@4.3.4)
+      zod-to-json-schema: 3.25.1(zod@4.3.5)
     transitivePeerDependencies:
       - '@modelcontextprotocol/sdk'
       - bufferutil
@@ -3517,15 +3620,16 @@ snapshots:
       - ws
       - zod
 
-  '@mariozechner/pi-coding-agent@0.32.3(ws@8.18.3)(zod@4.3.4)':
+  '@mariozechner/pi-coding-agent@0.36.0(ws@8.19.0)(zod@4.3.5)':
     dependencies:
-      '@mariozechner/pi-agent-core': 0.32.3(ws@8.18.3)(zod@4.3.4)
-      '@mariozechner/pi-ai': 0.32.3(patch_hash=628fb051b6f4886984a846a5ee7aa0a571c3360d35b8d114e4684e5edcd100c5)(ws@8.18.3)(zod@4.3.4)
-      '@mariozechner/pi-tui': 0.32.3
+      '@crosscopy/clipboard': 0.2.8
+      '@mariozechner/pi-agent-core': 0.36.0(ws@8.19.0)(zod@4.3.5)
+      '@mariozechner/pi-ai': 0.36.0(patch_hash=628fb051b6f4886984a846a5ee7aa0a571c3360d35b8d114e4684e5edcd100c5)(ws@8.19.0)(zod@4.3.5)
+      '@mariozechner/pi-tui': 0.36.0
       chalk: 5.6.2
       cli-highlight: 2.1.11
       diff: 8.0.2
-      file-type: 21.2.0
+      file-type: 21.3.0
       glob: 11.1.0
       jiti: 2.6.1
       marked: 15.0.12
@@ -3538,7 +3642,7 @@ snapshots:
       - ws
       - zod
 
-  '@mariozechner/pi-tui@0.32.3':
+  '@mariozechner/pi-tui@0.36.0':
     dependencies:
       '@types/mime-types': 2.1.4
       chalk: 5.6.2
@@ -3553,8 +3657,8 @@ snapshots:
 
   '@napi-rs/wasm-runtime@1.1.1':
     dependencies:
-      '@emnapi/core': 1.7.1
-      '@emnapi/runtime': 1.7.1
+      '@emnapi/core': 1.8.1
+      '@emnapi/runtime': 1.8.1
       '@tybys/wasm-util': 0.10.1
     optional: true
 
@@ -3590,28 +3694,28 @@ snapshots:
   '@oxlint-tsgolint/win32-x64@0.10.1':
     optional: true
 
-  '@oxlint/darwin-arm64@1.36.0':
+  '@oxlint/darwin-arm64@1.37.0':
     optional: true
 
-  '@oxlint/darwin-x64@1.36.0':
+  '@oxlint/darwin-x64@1.37.0':
     optional: true
 
-  '@oxlint/linux-arm64-gnu@1.36.0':
+  '@oxlint/linux-arm64-gnu@1.37.0':
     optional: true
 
-  '@oxlint/linux-arm64-musl@1.36.0':
+  '@oxlint/linux-arm64-musl@1.37.0':
     optional: true
 
-  '@oxlint/linux-x64-gnu@1.36.0':
+  '@oxlint/linux-x64-gnu@1.37.0':
     optional: true
 
-  '@oxlint/linux-x64-musl@1.36.0':
+  '@oxlint/linux-x64-musl@1.37.0':
     optional: true
 
-  '@oxlint/win32-arm64@1.36.0':
+  '@oxlint/win32-arm64@1.37.0':
     optional: true
 
-  '@oxlint/win32-x64@1.36.0':
+  '@oxlint/win32-x64@1.37.0':
     optional: true
 
   '@pinojs/redact@0.4.0': {}
@@ -3806,7 +3910,7 @@ snapshots:
       '@types/node': 25.0.3
       '@types/ws': 8.18.1
       eventemitter3: 5.0.1
-      ws: 8.18.3
+      ws: 8.19.0
     transitivePeerDependencies:
       - bufferutil
       - debug
@@ -3993,7 +4097,7 @@ snapshots:
       sirv: 3.0.2
       tinyrainbow: 3.0.3
       vitest: 4.0.16(@types/node@25.0.3)(@vitest/browser-playwright@4.0.16)(@vitest/browser-preview@4.0.16)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)(yaml@2.8.2)
-      ws: 8.18.3
+      ws: 8.19.0
     transitivePeerDependencies:
       - bufferutil
       - msw
@@ -4095,11 +4199,11 @@ snapshots:
       libsignal: '@whiskeysockets/libsignal-node@https://codeload.github.com/whiskeysockets/libsignal-node/tar.gz/1c30d7d7e76a3b0aa120b04dc6a26f5a12dccf67'
       lru-cache: 11.2.4
       music-metadata: 11.10.4
-      p-queue: 9.0.1
+      p-queue: 9.1.0
       pino: 9.14.0
       protobufjs: 7.5.4
       sharp: 0.34.5
-      ws: 8.18.3
+      ws: 8.19.0
     optionalDependencies:
       audio-decode: 2.2.3
     transitivePeerDependencies:
@@ -4260,7 +4364,7 @@ snapshots:
     dependencies:
       '@cacheable/memory': 2.0.7
       '@cacheable/utils': 2.3.3
-      hookified: 1.14.0
+      hookified: 1.15.0
       keyv: 5.5.5
       qified: 0.5.3
 
@@ -4418,6 +4522,10 @@ snapshots:
   dom-accessibility-api@0.5.16:
     optional: true
 
+  dompurify@3.3.1:
+    optionalDependencies:
+      '@types/trusted-types': 2.0.7
+
   dotenv@17.2.3: {}
 
   dunder-proto@1.0.1:
@@ -4568,7 +4676,7 @@ snapshots:
       node-domexception: 1.0.0
       web-streams-polyfill: 3.3.3
 
-  file-type@21.2.0:
+  file-type@21.3.0:
     dependencies:
       '@tokenizer/inflate': 0.4.1
       strtok3: 10.3.4
@@ -4733,7 +4841,7 @@ snapshots:
 
   hashery@1.4.0:
     dependencies:
-      hookified: 1.14.0
+      hookified: 1.15.0
 
   hasown@2.0.2:
     dependencies:
@@ -4743,7 +4851,7 @@ snapshots:
 
   highlight.js@11.11.1: {}
 
-  hookified@1.14.0: {}
+  hookified@1.15.0: {}
 
   html-escaper@2.0.2: {}
 
@@ -5032,6 +5140,8 @@ snapshots:
 
   marked@16.4.2: {}
 
+  marked@17.0.1: {}
+
   math-intrinsics@1.1.0: {}
 
   mdurl@2.0.0: {}
@@ -5086,7 +5196,7 @@ snapshots:
       '@tokenizer/token': 0.3.0
       content-type: 1.0.5
       debug: 4.4.3
-      file-type: 21.2.0
+      file-type: 21.3.0
       media-typer: 1.1.0
       strtok3: 10.3.4
       token-types: 6.1.2
@@ -5149,10 +5259,10 @@ snapshots:
     dependencies:
       wrappy: 1.0.2
 
-  openai@6.10.0(ws@8.18.3)(zod@4.3.4):
+  openai@6.10.0(ws@8.19.0)(zod@4.3.5):
     optionalDependencies:
-      ws: 8.18.3
-      zod: 4.3.4
+      ws: 8.19.0
+      zod: 4.3.5
 
   opus-decoder@0.7.11:
     dependencies:
@@ -5168,16 +5278,16 @@ snapshots:
       '@oxlint-tsgolint/win32-arm64': 0.10.1
       '@oxlint-tsgolint/win32-x64': 0.10.1
 
-  oxlint@1.36.0(oxlint-tsgolint@0.10.1):
+  oxlint@1.37.0(oxlint-tsgolint@0.10.1):
     optionalDependencies:
-      '@oxlint/darwin-arm64': 1.36.0
-      '@oxlint/darwin-x64': 1.36.0
-      '@oxlint/linux-arm64-gnu': 1.36.0
-      '@oxlint/linux-arm64-musl': 1.36.0
-      '@oxlint/linux-x64-gnu': 1.36.0
-      '@oxlint/linux-x64-musl': 1.36.0
-      '@oxlint/win32-arm64': 1.36.0
-      '@oxlint/win32-x64': 1.36.0
+      '@oxlint/darwin-arm64': 1.37.0
+      '@oxlint/darwin-x64': 1.37.0
+      '@oxlint/linux-arm64-gnu': 1.37.0
+      '@oxlint/linux-arm64-musl': 1.37.0
+      '@oxlint/linux-x64-gnu': 1.37.0
+      '@oxlint/linux-x64-musl': 1.37.0
+      '@oxlint/win32-arm64': 1.37.0
+      '@oxlint/win32-x64': 1.37.0
       oxlint-tsgolint: 0.10.1
 
   p-finally@1.0.0: {}
@@ -5187,7 +5297,7 @@ snapshots:
       eventemitter3: 4.0.7
       p-timeout: 3.2.0
 
-  p-queue@9.0.1:
+  p-queue@9.1.0:
     dependencies:
       eventemitter3: 5.0.1
       p-timeout: 7.0.1
@@ -5346,14 +5456,14 @@ snapshots:
 
   qified@0.5.3:
     dependencies:
-      hookified: 1.14.0
+      hookified: 1.15.0
 
   qoa-format@1.0.1:
     dependencies:
       '@thi.ng/bitstream': 2.4.37
     optional: true
 
-  qrcode-terminal@0.12.0: {}
+  qrcode-terminal@0.12.0(patch_hash=ed82029850dbdf551f5df1de320945af52b8ea8500cc7bd4f39258e7a3d92e12): {}
 
   qs@6.14.1:
     dependencies:
@@ -5769,7 +5879,7 @@ snapshots:
 
   undici@6.21.3: {}
 
-  undici@7.16.0: {}
+  undici@7.18.0: {}
 
   unicode-properties@1.4.1:
     dependencies:
@@ -5888,7 +5998,7 @@ snapshots:
 
   wrappy@1.0.2: {}
 
-  ws@8.18.3: {}
+  ws@8.19.0: {}
 
   y18n@5.0.8: {}
 
@@ -5910,10 +6020,10 @@ snapshots:
     dependencies:
       zod: 3.25.76
 
-  zod-to-json-schema@3.25.1(zod@4.3.4):
+  zod-to-json-schema@3.25.1(zod@4.3.5):
     dependencies:
-      zod: 4.3.4
+      zod: 4.3.5
 
   zod@3.25.76: {}
 
-  zod@4.3.4: {}
+  zod@4.3.5: {}

scripts/e2e/Dockerfile.qr-import

@@ -0,0 +1,9 @@
+FROM node:22-bookworm
+
+RUN corepack enable
+
+WORKDIR /app
+
+COPY . .
+
+RUN pnpm install --frozen-lockfile