fix(auth): doctor-migrate anthropic oauth profiles

fix(auth): use anthropic oauth email profile
Use Anthropic OAuth profile email as the profile identifier when available. This fixes cases where Anthropic returns an email-based profile id rather than an explicit id field.
2026-01-07 06:29:43 +00:00 · 2026-01-07 06:19:36 +00:00 · 2026-01-07 06:14:15 +00:00 · 2026-01-07 06:12:56 +00:00 · 2026-01-07 07:05:07 +01:00 · 2026-01-07 06:53:01 +01:00
303 changed files with 12855 additions and 3343 deletions
@@ -5,6 +5,12 @@
 - Tests: colocated `*.test.ts`.
 - Docs: `docs/` (images, queue, Pi config). Built output lives in `dist/`.

+## Docs Linking (Mintlify)
+- Docs are hosted on Mintlify (docs.clawd.bot).
+- Internal doc links in `docs/**/*.md`: root-relative, no `.md`/`.mdx` (example: `[Config](/configuration)`).
+- Section cross-references: use anchors on root-relative paths (example: `[Hooks](/configuration#hooks)`).
+- README (GitHub): keep absolute docs URLs (`https://docs.clawd.bot/...`) so links work on GitHub.
+
 ## Build, Test, and Development Commands
 - Runtime baseline: Node **22+** (keep Node + Bun paths working).
 - Install deps: `pnpm install`
@@ -50,31 +56,34 @@
 - Pi sessions live under `~/.clawdbot/sessions/` by default; the base directory is not configurable.
 - Never commit or publish real phone numbers, videos, or live configuration values. Use obviously fake placeholders in docs, tests, and examples.

+## Troubleshooting
+- Rebrand/migration issues (Clawdis → Clawdbot) or legacy config/service warnings: run `clawdbot doctor` (see `docs/gateway/doctor.md`).
+
 ## Agent-Specific Notes
- Gateway currently runs only as the menubar app (launchctl shows `application.com.steipete.clawdbot.debug.*`), there is no separate LaunchAgent/helper label installed. Restart via the Clawdbot Mac app or `scripts/restart-mac.sh`; to verify/kill use `launchctl print gui/$UID | grep clawdbot` rather than expecting `com.steipete.clawdbot`. **When debugging on macOS, start/stop the gateway via the app, not ad-hoc tmux sessions; kill any temporary tunnels before handoff.**
- macOS logs: use `./scripts/clawlog.sh` (aka `vtlog`) to query unified logs for subsystem `com.steipete.clawdbot`; it supports follow/tail/category filters and expects passwordless sudo for `/usr/bin/log`.
- Also read the shared guardrails at `~/Projects/oracle/AGENTS.md` and `~/Projects/agent-scripts/AGENTS.MD` before making changes; align with any cross-repo rules noted there.
+- Gateway currently runs only as the menubar app; there is no separate LaunchAgent/helper label installed. Restart via the Clawdbot Mac app or `scripts/restart-mac.sh`; to verify/kill use `launchctl print gui/$UID | grep clawdbot` rather than assuming a fixed label. **When debugging on macOS, start/stop the gateway via the app, not ad-hoc tmux sessions; kill any temporary tunnels before handoff.**
+- macOS logs: use `./scripts/clawlog.sh` (aka `vtlog`) to query unified logs for the Clawdbot subsystem; it supports follow/tail/category filters and expects passwordless sudo for `/usr/bin/log`.
+- If shared guardrails are available locally, review them; otherwise follow this repo's guidance.
 - SwiftUI state management (iOS/macOS): prefer the `Observation` framework (`@Observable`, `@Bindable`) over `ObservableObject`/`@StateObject`; don’t introduce new `ObservableObject` unless required for compatibility, and migrate existing usages when touching related code.
 - Connection providers: when adding a new connection, update every UI surface and docs (macOS app, web UI, mobile if applicable, onboarding/overview docs) and add matching status + configuration forms so provider lists and settings stay in sync.
 - **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; 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.
+- Release signing/notary keys are managed outside the repo; follow internal release docs.
+- Notary auth env vars (`APP_STORE_CONNECT_ISSUER_ID`, `APP_STORE_CONNECT_KEY_ID`, `APP_STORE_CONNECT_API_KEY_P8`) are expected in your environment (per internal release docs).
+- **Multi-agent safety:** do **not** create/apply/drop `git stash` entries unless explicitly requested (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 the user says "push", you may `git pull --rebase` to integrate latest changes (never discard other agents' work). When the user says "commit", scope to your changes only. When the user says "commit all", commit everything in grouped chunks.
+- **Multi-agent safety:** do **not** create/remove/modify `git worktree` checkouts (or edit `.worktrees/*`) unless explicitly requested.
+- **Multi-agent safety:** do **not** switch branches / check out a different branch unless explicitly requested.
 - **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.
+- 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 another machine, 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.
 - Never send streaming/partial replies to external messaging surfaces (WhatsApp, Telegram); only final replies should be delivered there. Streaming/tool events may still go to internal UIs/control channel.
 - Voice wake forwarding tips:
  - Command template should stay `clawdbot-mac agent --message "${text}" --thinking low`; `VoiceWakeForwarder` already shell-escapes `${text}`. Don’t add extra quotes.
-  - launchd PATH is minimal; ensure the app’s launch agent sets PATH to include `/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Users/steipete/Library/pnpm` so `pnpm`/`clawdbot` binaries resolve when invoked via `clawdbot-mac`.
+  - launchd PATH is minimal; ensure the app’s launch agent PATH includes standard system paths plus your pnpm bin (typically `$HOME/Library/pnpm`) so `pnpm`/`clawdbot` binaries resolve when invoked via `clawdbot-mac`.
  - For manual `clawdbot send` messages that include `!`, use the heredoc pattern noted below to avoid the Bash tool’s escaping.

 ## Exclamation Mark Escaping Workaround
@@ -10,30 +10,54 @@
  - New default: DM pairing (`dmPolicy="pairing"` / `discord.dm.policy="pairing"` / `slack.dm.policy="pairing"`).
  - To keep old “open to everyone” behavior: set `dmPolicy="open"` and include `"*"` in the relevant `allowFrom` (Discord/Slack: `discord.dm.allowFrom` / `slack.dm.allowFrom`).
  - Approve requests via `clawdbot pairing list --provider <provider>` + `clawdbot pairing approve --provider <provider> <code>` (Telegram also supports `clawdbot telegram pairing ...`).
+- Sandbox: default `agent.sandbox.scope` to `"agent"` (one container/workspace per agent). Use `"session"` for per-session isolation; `"shared"` disables cross-session isolation.
 - Timestamps in agent envelopes are now UTC (compact `YYYY-MM-DDTHH:mmZ`); removed `messages.timestampPrefix`. Add `agent.userTimezone` to tell the model the user’s local time (system prompt only).
 - Model config schema changes (auth profiles + model lists); doctor auto-migrates and the gateway rewrites legacy configs on startup.
 - Commands: gate all slash commands to authorized senders; add `/compact` to manually compact session context.
 - Groups: `whatsapp.groups`, `telegram.groups`, and `imessage.groups` now act as allowlists when set. Add `"*"` to keep allow-all behavior.

 ### Fixes
- Heartbeat: default interval now 30m with a new default prompt + HEARTBEAT.md template.
+- Pairing: generate DM pairing codes with CSPRNG, expire pending codes after 1 hour, and avoid re-sending codes for already pending requests.
+- Pairing: lock + atomically write pairing stores with 0600 perms and stop logging pairing codes in provider logs.
+- Tools: add Telegram/WhatsApp reaction tools (with per-provider gating). Thanks @zats for PR #353.
+- Tools: unify reaction removal semantics across Discord/Slack/Telegram/WhatsApp and allow WhatsApp reaction routing across accounts.
+- Gateway/CLI: add daemon runtime selection (Node recommended; Bun optional) and document WhatsApp/Baileys Bun WebSocket instability on reconnect.
+- CLI: add `clawdbot docs` live docs search with pretty output.
+- Agent: treat compaction retry AbortError as a fallback trigger without swallowing non-abort errors. Thanks @erikpr1994 for PR #341.
+- Sub-agents: allow `sessions_spawn` model overrides and error on invalid models. Thanks @azade-c for PR #298.
+- Sub-agents: skip invalid model overrides with a warning and keep the run alive; tool exceptions now return tool errors instead of crashing the agent.
+- Heartbeat: default interval 30m; clarified default prompt usage and HEARTBEAT.md template behavior.
 - Onboarding: write auth profiles to the multi-agent path (`~/.clawdbot/agents/main/agent/`) so the gateway finds credentials on first startup. Thanks @minghinmatthewlam for PR #327.
 - Docs: add missing `ui:install` setup step in the README. Thanks @hugobarauna for PR #300.
+- Docs: sanitize AGENTS guidance and add Clawdis migration troubleshooting note. Thanks @buddyh for PR #348.
+- Docs: add ClawdHub guide and hubs link for browsing, install, and sync workflows.
+- Docs: add FAQ for PNPM/Bun lockfile migration warning; link AgentSkills spec + ClawdHub guide (`/clawdhub`) from skills docs.
 - Build: import tool-display JSON as a module instead of runtime file reads. Thanks @mukhtharcm for PR #312.
+- Build: fix macOS packaging QR smoke test for the bun-compiled relay. Thanks @dbhurley for PR #358.
 - Browser: fix `browser snapshot`/`browser act` timeouts under Bun by patching Playwright’s CDP WebSocket selection. Thanks @azade-c for PR #307.
 - Browser: add `--browser-profile` flag and honor profile in tabs routes + browser tool. Thanks @jamesgroat for PR #324.
+- Gmail: include tailscale command exit codes/output when hook setup fails (easier debugging).
 - Telegram: stop typing after tool results. Thanks @AbhisekBasu1 for PR #322.
+- Telegram: include sender identity in group envelope headers. (#336)
+- Telegram: support forum topics with topic-isolated sessions and message_thread_id routing. Thanks @HazAT, @nachoiacovino, @RandyVentures for PR #321/#333/#334.
+- iMessage: ignore disconnect errors during shutdown (avoid unhandled promise rejections). Thanks @antons for PR #359.
 - Messages: stop defaulting ack reactions to 👀 when identity emoji is missing.
 - Auto-reply: require slash for control commands to avoid false triggers in normal text.
+- Auto-reply: add `/reasoning on|off` to expose model reasoning blocks (italic).
+- Auto-reply: place reasoning blocks before the final reply text when appended.
 - Auto-reply: flag error payloads and improve Bun socket error messaging. Thanks @emanuelst for PR #331.
+- Commands: add `/stop` to the registry and route native aborts to the active chat session. Thanks @nachoiacovino for PR #295.
 - Commands: unify native + text chat commands behind `commands.*` config (Discord/Slack/Telegram). Thanks @thewilloftheshadow for PR #275.
 - Auto-reply: treat steer during compaction as a follow-up, queued until compaction completes.
 - Auth: lock auth profile refreshes to avoid multi-instance OAuth logouts; keep credentials on refresh failure.
+- Auth/Doctor: migrate Anthropic OAuth configs from `anthropic:default` → `anthropic:<email>` and surface a doctor hint on refresh failures. Thanks @RandyVentures for PR #361. (#363)
 - Gateway/CLI: stop forcing localhost URL in remote mode so remote gateway config works. Thanks @oswalpalash for PR #293.
 - Onboarding: prompt immediately for OpenAI Codex redirect URL on remote/headless logins.
 - Configure: add OpenAI Codex (ChatGPT OAuth) auth choice (align with onboarding).
 - Doctor: suggest adding the workspace memory system when missing (opt-out via `--no-workspace-suggestions`).
 - Doctor: normalize default workspace path to `~/clawd` (avoid `~/clawdbot`).
+- Doctor: add `--yes` and `--non-interactive` for headless/automation runs (`--non-interactive` only applies safe migrations).
+- Gateway/CLI: auto-migrate legacy sessions + agent state layouts on startup (safe; WhatsApp auth still requires `clawdbot doctor`).
 - Workspace: only create `BOOTSTRAP.md` for brand-new workspaces (don’t recreate after deletion).
 - Build: fix duplicate protocol export, align Codex OAuth options, and add proper-lockfile typings.
 - Build: install Bun in the Dockerfile so `pnpm build` can run Bun scripts. Thanks @loukotal for PR #284.
@@ -50,11 +74,13 @@
 - Gateway: add `gateway stop|restart` helpers and surface launchd/systemd/schtasks stop hints when the gateway is already running.
 - Gateway: honor `agent.timeoutSeconds` for `chat.send` and share timeout defaults across chat/cron/auto-reply. Thanks @MSch for PR #229.
 - Auth: prioritize OAuth profiles but fall back to API keys when refresh fails; stored profiles now load without explicit auth order.
+- Auth/CLI: normalize provider ids and Z.AI aliases across auth profile ordering and models list/status. Thanks @mneves75 for PR #303.
 - 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.
+- Skills: add Linuxbrew paths to gateway PATH bootstrap so the Skills UI can run brew installers under systemd/minimal environments.
 - TUI: migrate key handling to the updated pi-tui Key matcher API.
 - TUI: add `/elev` alias for `/elevated`.
 - Logging: redact sensitive tokens in verbose tool summaries by default (configurable patterns).
@@ -70,6 +96,7 @@
 - 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.
+- Docs: clarify per-session sandbox isolation and `perSession` sharing risks.
 - Sandbox: copy inbound media into sandbox workspaces so agent tools can read attachments.
 - Sandbox: enable session tools in sandboxed sessions with spawned-only visibility by default (opt-in `agent.sandbox.sessionToolsVisibility = "all"`).
 - Control UI: show a reading indicator bubble while the assistant is responding.
@@ -87,6 +114,7 @@
 - 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: centralize tool/block/final dispatch across providers for consistent streaming + heartbeat/prefix handling. Thanks @MSch for PR #225.
+- Routing: route replies back to the originating provider/chat when multiple providers share the same session. Thanks @jalehman for PR #328.
 - Heartbeat: make HEARTBEAT_OK ack padding configurable across heartbeat and cron delivery. (#238) — thanks @jalehman
 - Skills: emit MEDIA token after Nano Banana Pro image generation. Thanks @Iamadig for PR #271.
 - WhatsApp: set sender E.164 for direct chats so owner commands work in DMs.
@@ -95,10 +123,12 @@
 - Slack: fix Slack provider startup under Bun by using a named import for Bolt `App`. Thanks @snopoke for PR #299.
 - Discord: surface missing-permission hints (muted/role overrides) when replies fail.
 - Discord: use channel IDs for DMs instead of user IDs. Thanks @VACInc for PR #261.
+- Discord: treat empty message content as media placeholder so voice messages are not dropped; enables `routing.transcribeAudio`. Thanks @VACInc for PR #339.
 - 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.
 - Auth: rotate across multiple OAuth profiles with cooldown tracking and email-based profile IDs. Thanks @mukhtharcm for PR #269.
 - Auth: fix multi-account OAuth rotation so round-robin alternates instead of pinning to lastGood. Thanks @mukhtharcm for PR #281.
+- Auth: lock auth profile usage updates and fail fast on 429s during rotation. Thanks @mukhtharcm for PR #342.
 - Configure: stop auto-writing `auth.order` for newly added auth profiles (round-robin default unless explicitly pinned).
 - Telegram: honor routing.groupChat.mentionPatterns for group mention gating. Thanks Kevin Kern (@regenrek) for PR #242.
 - Telegram: gate groups via `telegram.groups` allowlist (align with WhatsApp/iMessage). Thanks @kitze for PR #241.
@@ -115,6 +145,7 @@
 - Models: extend `clawdbot models` status output with a masked auth overview (profiles, env sources, and OAuth counts).

 ### Maintenance
+- Skills: add Himalaya email CLI skill. Thanks @dantelex for PR #335.
 - Agent: add `skipBootstrap` config option. Thanks @onutc for PR #292.
 - UI: add favicon.ico derived from the macOS app icon. Thanks @jeffersonwarrior for PR #305.
 - Tooling: replace tsx with bun for TypeScript execution. Thanks @obviyus for PR #278.
@@ -22,7 +22,7 @@ If you want a personal, single-user assistant that feels local, fast, and always

 [Website](https://clawdbot.com) · [Docs](https://docs.clawd.bot) · Getting Started: [https://docs.clawd.bot/getting-started](https://docs.clawd.bot/getting-started) · Updating: [https://docs.clawd.bot/updating](https://docs.clawd.bot/updating) · Showcase: [https://docs.clawd.bot/showcase](https://docs.clawd.bot/showcase) · FAQ: [https://docs.clawd.bot/faq](https://docs.clawd.bot/faq) · Wizard: [https://docs.clawd.bot/wizard](https://docs.clawd.bot/wizard) · Nix: [https://github.com/clawdbot/nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) · Docker: [https://docs.clawd.bot/docker](https://docs.clawd.bot/docker) · Discord: [https://discord.gg/clawd](https://discord.gg/clawd)

-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**.
+Preferred setup: run the onboarding wizard (`clawdbot onboard`). It walks through gateway, workspace, providers, and skills. The CLI wizard is the recommended path and works on **macOS, Linux, and Windows (via WSL2; strongly recommended)**.
 Works with npm, pnpm, or bun.
 New install? Start here: https://docs.clawd.bot/getting-started

@@ -41,21 +41,21 @@ Model note: while any model is supported, I strongly recommend **Anthropic Pro/M

 Do **not** download prebuilt binaries. Run from source.

-Prefer **Bun**. `pnpm` is also supported (see https://docs.clawd.bot/getting-started).
+Prefer `pnpm` for builds from source. Bun is optional for running TypeScript directly.

 ```bash
 # Clone this repo
 git clone https://github.com/clawdbot/clawdbot.git
 cd clawdbot

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

-Note: `bun run clawdbot ...` runs TypeScript directly. `bun run build` produces `dist/` for running via Node / the packaged `clawdbot` binary.
+Note: `pnpm clawdbot ...` runs TypeScript directly (via `tsx`). `pnpm build` produces `dist/` for running via Node / the packaged `clawdbot` binary.

 ## Quick start (TL;DR)

@@ -64,23 +64,23 @@ Runtime: **Node ≥22**.
 Full beginner guide (auth, pairing, providers): https://docs.clawd.bot/getting-started

 ```bash
-bun run clawdbot onboard
+pnpm clawdbot onboard

-bun run clawdbot gateway --port 18789 --verbose
+pnpm clawdbot gateway --port 18789 --verbose

 # Dev loop (auto-reload on TS changes)
-bun run gateway:watch
+pnpm gateway:watch

 # Send a message
-bun run clawdbot send --to +1234567890 --message "Hello from Clawdbot"
+pnpm clawdbot send --to +1234567890 --message "Hello from Clawdbot"

 # Talk to the assistant (optionally deliver back to WhatsApp/Telegram/Slack/Discord)
-bun run clawdbot agent --message "Ship checklist" --thinking high
+pnpm clawdbot agent --message "Ship checklist" --thinking high
 ```

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

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

 ## Security defaults (DM access)

@@ -369,7 +369,7 @@ Use these when you’re past the onboarding flow and want the deeper reference.
 - [Wire external triggers via the webhook surface.](https://docs.clawd.bot/webhook)
 - [Set up Gmail Pub/Sub triggers.](https://docs.clawd.bot/gmail-pubsub)
 - [Learn the macOS menu bar companion details.](https://docs.clawd.bot/mac/menu-bar)
- [Platform guides: Windows](https://docs.clawd.bot/windows), [Linux](https://docs.clawd.bot/linux), [macOS](https://docs.clawd.bot/macos), [iOS](https://docs.clawd.bot/ios), [Android](https://docs.clawd.bot/android)
+- [Platform guides: Windows (WSL2)](https://docs.clawd.bot/windows), [Linux](https://docs.clawd.bot/linux), [macOS](https://docs.clawd.bot/macos), [iOS](https://docs.clawd.bot/ios), [Android](https://docs.clawd.bot/android)
 - [Debug common failures with the troubleshooting guide.](https://docs.clawd.bot/troubleshooting)
 - [Review security guidance before exposing anything.](https://docs.clawd.bot/security)

@@ -416,7 +416,7 @@ Use these when you’re past the onboarding flow and want the deeper reference.
 - [macOS voice wake](https://docs.clawd.bot/mac/voicewake)
 - [iOS node](https://docs.clawd.bot/ios)
 - [Android node](https://docs.clawd.bot/android)
- [Windows app](https://docs.clawd.bot/windows)
+- [Windows (WSL2)](https://docs.clawd.bot/windows)
 - [Linux app](https://docs.clawd.bot/linux)

 ## Email hooks (Gmail)
@@ -453,5 +453,5 @@ Thanks to all clawtributors:
  <a href="https://github.com/azade-c"><img src="https://avatars.githubusercontent.com/u/252790079?v=4&s=48" width="48" height="48" alt="azade-c" title="azade-c"/></a> <a href="https://github.com/andranik-sahakyan"><img src="https://avatars.githubusercontent.com/u/8908029?v=4&s=48" width="48" height="48" alt="andranik-sahakyan" title="andranik-sahakyan"/></a>
  <a href="https://github.com/adamgall"><img src="https://avatars.githubusercontent.com/u/706929?v=4&s=48" width="48" height="48" alt="adamgall" title="adamgall"/></a> <a href="https://github.com/jalehman"><img src="https://avatars.githubusercontent.com/u/550978?v=4&s=48" width="48" height="48" alt="jalehman" title="jalehman"/></a> <a href="https://github.com/jarvis-medmatic"><img src="https://avatars.githubusercontent.com/u/252428873?v=4&s=48" width="48" height="48" alt="jarvis-medmatic" title="jarvis-medmatic"/></a> <a href="https://github.com/mneves75"><img src="https://avatars.githubusercontent.com/u/2423436?v=4&s=48" width="48" height="48" alt="mneves75" title="mneves75"/></a> <a href="https://github.com/regenrek"><img src="https://avatars.githubusercontent.com/u/5182020?v=4&s=48" width="48" height="48" alt="regenrek" title="regenrek"/></a> <a href="https://github.com/tobiasbischoff"><img src="https://avatars.githubusercontent.com/u/711564?v=4&s=48" width="48" height="48" alt="tobiasbischoff" title="tobiasbischoff"/></a> <a href="https://github.com/MSch"><img src="https://avatars.githubusercontent.com/u/7475?v=4&s=48" width="48" height="48" alt="MSch" title="MSch"/></a> <a href="https://github.com/obviyus"><img src="https://avatars.githubusercontent.com/u/22031114?v=4&s=48" width="48" height="48" alt="obviyus" title="obviyus"/></a> <a href="https://github.com/dbhurley"><img src="https://avatars.githubusercontent.com/u/5251425?v=4&s=48" width="48" height="48" alt="dbhurley" title="dbhurley"/></a>
  <a href="https://github.com/Asleep123"><img src="https://avatars.githubusercontent.com/u/122379135?v=4&s=48" width="48" height="48" alt="Asleep123" title="Asleep123"/></a> <a href="https://github.com/Iamadig"><img src="https://avatars.githubusercontent.com/u/102129234?v=4&s=48" width="48" height="48" alt="Iamadig" title="Iamadig"/></a> <a href="https://github.com/imfing"><img src="https://avatars.githubusercontent.com/u/5097752?v=4&s=48" width="48" height="48" alt="imfing" title="imfing"/></a> <a href="https://github.com/kitze"><img src="https://avatars.githubusercontent.com/u/1160594?v=4&s=48" width="48" height="48" alt="kitze" title="kitze"/></a> <a href="https://github.com/nachoiacovino"><img src="https://avatars.githubusercontent.com/u/50103937?v=4&s=48" width="48" height="48" alt="nachoiacovino" title="nachoiacovino"/></a> <a href="https://github.com/VACInc"><img src="https://avatars.githubusercontent.com/u/3279061?v=4&s=48" width="48" height="48" alt="VACInc" title="VACInc"/></a> <a href="https://github.com/cash-echo-bot"><img src="https://avatars.githubusercontent.com/u/252747386?v=4&s=48" width="48" height="48" alt="cash-echo-bot" title="cash-echo-bot"/></a> <a href="https://github.com/claude"><img src="https://avatars.githubusercontent.com/u/81847?v=4&s=48" width="48" height="48" alt="claude" title="claude"/></a> <a href="https://github.com/kiranjd"><img src="https://avatars.githubusercontent.com/u/25822851?v=4&s=48" width="48" height="48" alt="kiranjd" title="kiranjd"/></a> <a href="https://github.com/pcty-nextgen-service-account"><img src="https://avatars.githubusercontent.com/u/112553441?v=4&s=48" width="48" height="48" alt="pcty-nextgen-service-account" title="pcty-nextgen-service-account"/></a> <a href="https://github.com/minghinmatthewlam"><img src="https://avatars.githubusercontent.com/u/14224566?v=4&s=48" width="48" height="48" alt="minghinmatthewlam" title="minghinmatthewlam"/></a>
-  <a href="https://github.com/ngutman"><img src="https://avatars.githubusercontent.com/u/1540134?v=4&s=48" width="48" height="48" alt="ngutman" title="ngutman"/></a> <a href="https://github.com/onutc"><img src="https://avatars.githubusercontent.com/u/152018508?v=4&s=48" width="48" height="48" alt="onutc" title="onutc"/></a> <a href="https://github.com/oswalpalash"><img src="https://avatars.githubusercontent.com/u/6431196?v=4&s=48" width="48" height="48" alt="oswalpalash" title="oswalpalash"/></a> <a href="https://github.com/snopoke"><img src="https://avatars.githubusercontent.com/u/249606?v=4&s=48" width="48" height="48" alt="snopoke" title="snopoke"/></a> <a href="https://github.com/ManuelHettich"><img src="https://avatars.githubusercontent.com/u/17690367?v=4&s=48" width="48" height="48" alt="ManuelHettich" title="ManuelHettich"/></a> <a href="https://github.com/loukotal"><img src="https://avatars.githubusercontent.com/u/18210858?v=4&s=48" width="48" height="48" alt="loukotal" title="loukotal"/></a> <a href="https://github.com/hugobarauna"><img src="https://avatars.githubusercontent.com/u/2719?v=4&s=48" width="48" height="48" alt="hugobarauna" title="hugobarauna"/></a> <a href="https://github.com/AbhisekBasu1"><img src="https://avatars.githubusercontent.com/u/40645221?v=4&s=48" width="48" height="48" alt="AbhisekBasu1" title="AbhisekBasu1"/></a> <a href="https://github.com/emanuelst"><img src="https://avatars.githubusercontent.com/u/9994339?v=4&s=48" width="48" height="48" alt="emanuelst" title="emanuelst"/></a>
+  <a href="https://github.com/ngutman"><img src="https://avatars.githubusercontent.com/u/1540134?v=4&s=48" width="48" height="48" alt="ngutman" title="ngutman"/></a> <a href="https://github.com/onutc"><img src="https://avatars.githubusercontent.com/u/152018508?v=4&s=48" width="48" height="48" alt="onutc" title="onutc"/></a> <a href="https://github.com/oswalpalash"><img src="https://avatars.githubusercontent.com/u/6431196?v=4&s=48" width="48" height="48" alt="oswalpalash" title="oswalpalash"/></a> <a href="https://github.com/snopoke"><img src="https://avatars.githubusercontent.com/u/249606?v=4&s=48" width="48" height="48" alt="snopoke" title="snopoke"/></a> <a href="https://github.com/ManuelHettich"><img src="https://avatars.githubusercontent.com/u/17690367?v=4&s=48" width="48" height="48" alt="ManuelHettich" title="ManuelHettich"/></a> <a href="https://github.com/loukotal"><img src="https://avatars.githubusercontent.com/u/18210858?v=4&s=48" width="48" height="48" alt="loukotal" title="loukotal"/></a> <a href="https://github.com/hugobarauna"><img src="https://avatars.githubusercontent.com/u/2719?v=4&s=48" width="48" height="48" alt="hugobarauna" title="hugobarauna"/></a> <a href="https://github.com/AbhisekBasu1"><img src="https://avatars.githubusercontent.com/u/40645221?v=4&s=48" width="48" height="48" alt="AbhisekBasu1" title="AbhisekBasu1"/></a> <a href="https://github.com/emanuelst"><img src="https://avatars.githubusercontent.com/u/9994339?v=4&s=48" width="48" height="48" alt="emanuelst" title="emanuelst"/></a> <a href="https://github.com/dantelex"><img src="https://avatars.githubusercontent.com/u/631543?v=4&s=48" width="48" height="48" alt="dantelex" title="dantelex"/></a> <a href="https://github.com/erikpr1994"><img src="https://avatars.githubusercontent.com/u/6299331?v=4&s=48" width="48" height="48" alt="erikpr1994" title="erikpr1994"/></a> <a href="https://github.com/antons"><img src="https://avatars.githubusercontent.com/u/129705?v=4&s=48" width="48" height="48" alt="antons" title="antons"/></a> <a href="https://github.com/RandyVentures"><img src="https://avatars.githubusercontent.com/u/149904821?v=4&s=48" width="48" height="48" alt="RandyVentures" title="RandyVentures"/></a>
 </p>
@@ -691,6 +691,7 @@ public struct SessionsPatchParams: Codable, Sendable {
    public let key: String
    public let thinkinglevel: AnyCodable?
    public let verboselevel: AnyCodable?
+    public let reasoninglevel: AnyCodable?
    public let elevatedlevel: AnyCodable?
    public let model: AnyCodable?
    public let spawnedby: AnyCodable?
@@ -701,6 +702,7 @@ public struct SessionsPatchParams: Codable, Sendable {
        key: String,
        thinkinglevel: AnyCodable?,
        verboselevel: AnyCodable?,
+        reasoninglevel: AnyCodable?,
        elevatedlevel: AnyCodable?,
        model: AnyCodable?,
        spawnedby: AnyCodable?,
@@ -710,6 +712,7 @@ public struct SessionsPatchParams: Codable, Sendable {
        self.key = key
        self.thinkinglevel = thinkinglevel
        self.verboselevel = verboselevel
+        self.reasoninglevel = reasoninglevel
        self.elevatedlevel = elevatedlevel
        self.model = model
        self.spawnedby = spawnedby
@@ -720,6 +723,7 @@ public struct SessionsPatchParams: Codable, Sendable {
        case key
        case thinkinglevel = "thinkingLevel"
        case verboselevel = "verboseLevel"
+        case reasoninglevel = "reasoningLevel"
        case elevatedlevel = "elevatedLevel"
        case model
        case spawnedby = "spawnedBy"
@@ -1,20 +1,17 @@
 {
-	"$schema": "https://biomejs.dev/schemas/biome.json",
-	"formatter": {
-		"enabled": true,
-		"indentWidth": 2,
-		"indentStyle": "space"
-	},
-	"files": {
-		"includes": [
-			"src/**/*.ts",
-			"test/**/*.ts"
-		]
-	},
-	"linter": {
-		"enabled": true,
-		"rules": {
-			"recommended": true
-		}
-	}
+  "$schema": "https://biomejs.dev/schemas/biome.json",
+  "formatter": {
+    "enabled": true,
+    "indentWidth": 2,
+    "indentStyle": "space"
+  },
+  "files": {
+    "includes": ["src/**/*.ts", "test/**/*.ts"]
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  }
 }
@@ -23,29 +23,29 @@ nav:
  - title: "Home"
    url: "/"
  - title: "Clawd Setup"
-    url: "/clawd.html"
+    url: "/start/clawd/"
  - title: "Gateway"
-    url: "/gateway.html"
+    url: "/gateway/"
  - title: "Remote"
-    url: "/remote.html"
+    url: "/gateway/remote/"
  - title: "Discovery"
-    url: "/discovery.html"
+    url: "/gateway/discovery/"
  - title: "Configuration"
-    url: "/configuration.html"
+    url: "/gateway/configuration/"
  - title: "WebChat"
-    url: "/webchat.html"
+    url: "/web/webchat/"
  - title: "macOS App"
-    url: "/macos.html"
+    url: "/platforms/macos/"
  - title: "iOS App"
-    url: "/ios.html"
+    url: "/platforms/ios/"
  - title: "Android App"
-    url: "/android.html"
+    url: "/platforms/android/"
  - title: "Telegram"
-    url: "/telegram.html"
+    url: "/providers/telegram/"
  - title: "Security"
-    url: "/security.html"
+    url: "/gateway/security/"
  - title: "Troubleshooting"
-    url: "/troubleshooting.html"
+    url: "/gateway/troubleshooting/"

 kramdown:
  input: GFM
@@ -0,0 +1,132 @@
+---
+summary: "Cron jobs + wakeups for the Gateway scheduler"
+read_when:
+  - Scheduling background jobs or wakeups
+  - Wiring automation that should run with or alongside heartbeats
+---
+# Cron jobs (Gateway scheduler)
+
+Cron runs inside the Gateway and schedules background work so Clawdbot can
+wake itself up, run isolated agent jobs, and deliver reminders on time.
+
+## Update checklist (internal)
+- [x] Audit cron + heartbeat behavior in code
+- [x] Rewrite cron doc as user-facing feature
+- [x] Update heartbeat docs + templates
+- [x] Update cron links in docs
+- [x] Update changelog
+- [x] Run full gate (lint/build/test/docs)
+
+## What cron is
+- **Gateway-owned scheduler** that persists jobs under `~/.clawdbot/cron/`.
+- **Two execution modes**:
+  - **Main session jobs** enqueue `System:` events and rely on the heartbeat runner.
+  - **Isolated jobs** run a dedicated agent turn in `cron:<jobId>` sessions.
+- **Wakeups** are first-class: a job can trigger the next heartbeat or run it now.
+
+## When to use it
+- Recurring reminders: “every weekday at 7:30” or “every 2h.”
+- Background chores: summarize inboxes, check dashboards, watch logs.
+- Automation that should not pollute the main chat history.
+- Scheduled wakeups that drive the heartbeat pipeline.
+
+## Schedules
+Cron supports three schedule kinds:
+- `at`: one-shot timestamp in ms.
+- `every`: fixed interval (ms).
+- `cron`: 5-field cron expression, optional IANA timezone.
+
+Cron expressions use `croner` under the hood. If a timezone is omitted, the
+server’s local timezone is used.
+
+## Job types
+
+### Main session jobs
+Main jobs enqueue a system event and optionally wake the heartbeat runner.
+They **must** use `payload.kind = "systemEvent"`.
+
+- **`wakeMode: "next-heartbeat"`** (default): the event waits for the next
+  scheduled heartbeat.
+- **`wakeMode: "now"`**: the event triggers an immediate heartbeat run.
+
+### Isolated jobs
+Isolated jobs run a dedicated agent turn in session `cron:<jobId>` and can
+optionally deliver a message.
+
+Key behaviors:
+- Prompt is prefixed with `[cron:<jobId> <job name>]` for traceability.
+- A summary is posted to the main session with prefix `Cron` (or
+  `isolation.postToMainPrefix`).
+- `wakeMode: "now"` triggers an immediate heartbeat after posting the summary.
+- `payload.deliver: true` sends output to a provider; otherwise it stays internal.
+
+## Storage & history
+- Job store: `~/.clawdbot/cron/jobs.json` (JSON, Gateway-managed).
+- Run history: `~/.clawdbot/cron/runs/<jobId>.jsonl` (JSONL, auto-pruned).
+- Override store path: `cron.store` in config.
+
+## Configuration
+
+```json5
+{
+  cron: {
+    enabled: true,                // default true
+    store: "~/.clawdbot/cron/jobs.json",
+    maxConcurrentRuns: 1           // default 1
+  }
+}
+```
+
+Disable cron entirely:
+- `cron.enabled: false` (config)
+- or `CLAWDBOT_SKIP_CRON=1` (env)
+
+## CLI quickstart
+
+One-shot reminder (main session, wake immediately):
+```bash
+clawdbot cron add \
+  --name "Calendar check" \
+  --at "20m" \
+  --session main \
+  --system-event "Next heartbeat: check calendar." \
+  --wake now
+```
+
+Recurring isolated job (deliver to WhatsApp):
+```bash
+clawdbot cron add \
+  --name "Morning status" \
+  --cron "0 7 * * *" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --message "Summarize inbox + calendar for today." \
+  --deliver \
+  --provider whatsapp \
+  --to "+15551234567"
+```
+
+Manual run (debug):
+```bash
+clawdbot cron run <jobId> --force
+```
+
+Run history:
+```bash
+clawdbot cron runs --id <jobId> --limit 50
+```
+
+Immediate wake without creating a job:
+```bash
+clawdbot wake --mode now --text "Next heartbeat: check battery."
+```
+
+## API surface (Gateway)
+- `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`
+- `cron.run` (force or due), `cron.runs`
+- `wake` (enqueue system event + optional heartbeat)
+
+## Tips
+- Use **main session jobs** when you want the heartbeat prompt + existing context.
+- Use **isolated jobs** for noisy, frequent, or long-running work.
+- Keep messages short; cron turns are full agent runs and can burn tokens.
@@ -11,10 +11,12 @@ Goal: Gmail watch -> Pub/Sub push -> `gog gmail watch serve` -> Clawdbot webhook

 ## Prereqs

- `gcloud` installed and logged in.
- `gog` (gogcli) installed and authorized for the Gmail account.
- Clawdbot hooks enabled (see [`docs/webhook.md`](https://docs.clawd.bot/webhook)).
- `tailscale` logged in if you want a public HTTPS endpoint via Funnel.
+- `gcloud` installed and logged in ([install guide](https://docs.cloud.google.com/sdk/docs/install-sdk)).
+- `gog` (gogcli) installed and authorized for the Gmail account ([gogcli.sh](https://gogcli.sh/)).
+- Clawdbot hooks enabled (see [`docs/webhook.md`](https://docs.clawd.bot/automation/webhook)).
+- `tailscale` logged in ([tailscale.com](https://tailscale.com/)). Supported setup uses Tailscale Funnel for the public HTTPS endpoint.
+  Other tunnel services can work, but are DIY/unsupported and require manual wiring.
+  Right now, Tailscale is what we support.

 Example hook config (enable Gmail preset mapping):

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

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

 ## Wizard (recommended)

@@ -135,9 +137,10 @@ Notes:

 Recommended: `clawdbot hooks gmail run` wraps the same flow and auto-renews the watch.

-## Expose the handler (dev)
+## Expose the handler (dev, unsupported hack)

-For local testing, tunnel the handler and use the public URL in the push subscription:
+If you insist on a non-Tailscale tunnel, wire it manually and use the public URL in the push
+subscription (unsupported, no guardrails):

 ```bash
 cloudflared tunnel --url http://127.0.0.1:8788 --no-autoupdate
@@ -91,8 +91,9 @@ Mapping options (summary):
 - `hooks.mappings` lets you define `match`, `action`, and templates in config.
 - `hooks.transformsDir` + `transform.module` loads a JS/TS module for custom logic.
 - Use `match.source` to keep a generic ingest endpoint (payload-driven routing).
- TS transforms require a TS loader (e.g. `bun`) or precompiled `.js` at runtime.
+- TS transforms require a TS loader (e.g. `bun` or `tsx`) or precompiled `.js` at runtime.
 - `clawdbot hooks gmail setup` writes `hooks.gmail` config for `clawdbot hooks gmail run`.
+See [`docs/gmail-pubsub.md`](https://docs.clawd.bot/automation/gmail-pubsub) for the full Gmail watch flow.

 ## Responses

@@ -0,0 +1,533 @@
+---
+summary: "CLI reference for clawdbot commands, subcommands, and options"
+read_when:
+  - Adding or modifying CLI commands or options
+  - Documenting new command surfaces
+---
+
+# CLI reference
+
+This page mirrors `src/cli/*` and is the source of truth for CLI behavior.
+If you change the CLI code, update this doc.
+
+## Global flags
+
+- `--dev`: isolate state under `~/.clawdbot-dev` and shift default ports.
+- `--profile <name>`: isolate state under `~/.clawdbot-<name>`.
+- `-V`, `--version`, `-v`: print version and exit.
+
+## Command tree
+
+```
+clawdbot [--dev] [--profile <name>] <command>
+  setup
+  onboard
+  configure (alias: config)
+  update
+  doctor
+  login
+  logout
+  send
+  poll
+  agent
+  status
+  health
+  sessions
+  gateway
+    call
+    health
+    status
+    wake
+    send
+    agent
+    stop
+    restart
+  gateway-daemon
+  models
+    list
+    status
+    set
+    set-image
+    aliases list|add|remove
+    fallbacks list|add|remove|clear
+    image-fallbacks list|add|remove|clear
+    scan
+  wake
+  cron
+    status
+    list
+    add
+    edit
+    rm
+    enable
+    disable
+    runs
+    run
+  nodes
+    status
+    describe
+    list
+    pending
+    approve
+    reject
+    rename
+    invoke
+    run
+    notify
+    camera list|snap|clip
+    canvas snapshot
+    screen record
+    location get
+  canvas
+    snapshot
+    present
+    hide
+    navigate
+    eval
+    a2ui push|reset
+  browser
+    status
+    start
+    stop
+    reset-profile
+    tabs
+    open
+    focus
+    close
+    profiles
+    create-profile
+    delete-profile
+    screenshot
+    snapshot
+    navigate
+    resize
+    click
+    type
+    press
+    hover
+    drag
+    select
+    upload
+    fill
+    dialog
+    wait
+    evaluate
+    console
+    pdf
+  hooks
+    gmail setup|run
+  pairing
+    list
+    approve
+  telegram
+    pairing list|approve
+  docs
+  dns
+    setup
+  tui
+```
+
+## Setup + onboarding
+
+### `setup`
+Initialize config + workspace.
+
+Options:
+- `--workspace <dir>`: agent workspace path (default `~/clawd`).
+- `--wizard`: run the onboarding wizard.
+- `--non-interactive`: run wizard without prompts.
+- `--mode <local|remote>`: wizard mode.
+- `--remote-url <url>`: remote Gateway URL.
+- `--remote-token <token>`: remote Gateway token.
+
+### `onboard`
+Interactive wizard to set up gateway, workspace, and skills.
+
+Options:
+- `--workspace <dir>`
+- `--non-interactive`
+- `--mode <local|remote>`
+- `--auth-choice <oauth|apiKey|minimax|skip>`
+- `--anthropic-api-key <key>`
+- `--gateway-port <port>`
+- `--gateway-bind <loopback|lan|tailnet|auto>`
+- `--gateway-auth <off|token|password>`
+- `--gateway-token <token>`
+- `--gateway-password <password>`
+- `--remote-url <url>`
+- `--remote-token <token>`
+- `--tailscale <off|serve|funnel>`
+- `--tailscale-reset-on-exit`
+- `--install-daemon`
+- `--daemon-runtime <node|bun>`
+- `--skip-skills`
+- `--skip-health`
+- `--node-manager <npm|pnpm|bun>`
+- `--json`
+
+### `configure` / `config`
+Interactive configuration wizard (models, providers, skills, gateway).
+
+### `update`
+Audit and modernize the local configuration.
+
+### `doctor`
+Health checks + quick fixes.
+
+Options:
+- `--no-workspace-suggestions`: disable workspace memory hints.
+
+## Auth + provider helpers
+
+### `login`
+Link a WhatsApp Web account via QR.
+
+Options:
+- `--verbose`
+- `--provider <provider>` (default `whatsapp`)
+- `--account <id>`
+
+### `logout`
+Clear cached WhatsApp Web credentials.
+
+Options:
+- `--provider <provider>`
+- `--account <id>`
+
+### `pairing`
+Approve DM pairing requests across providers.
+
+Subcommands:
+- `pairing list --provider <telegram|signal|imessage|discord|slack|whatsapp> [--json]`
+- `pairing approve --provider <...> <code> [--notify]`
+
+### `telegram pairing`
+Telegram-only pairing helper.
+
+Subcommands:
+- `telegram pairing list [--json]`
+- `telegram pairing approve <code> [--no-notify]`
+
+### `hooks gmail`
+Gmail Pub/Sub hook setup + runner. See [/automation/gmail-pubsub](/automation/gmail-pubsub).
+
+Subcommands:
+- `hooks gmail setup` (requires `--account <email>`; supports `--project`, `--topic`, `--subscription`, `--label`, `--hook-url`, `--hook-token`, `--push-token`, `--bind`, `--port`, `--path`, `--include-body`, `--max-bytes`, `--renew-minutes`, `--tailscale`, `--tailscale-path`, `--push-endpoint`, `--json`)
+- `hooks gmail run` (runtime overrides for the same flags)
+
+### `dns setup`
+Wide-area discovery DNS helper (CoreDNS + Tailscale). See [/gateway/discovery](/gateway/discovery).
+
+Options:
+- `--apply`: install/update CoreDNS config (requires sudo; macOS only).
+
+## Messaging + agent
+
+### `send`
+Send a message through a provider.
+
+Required:
+- `--to <dest>`
+- `--message <text>`
+
+Options:
+- `--media <path-or-url>`
+- `--gif-playback`
+- `--provider <whatsapp|telegram|discord|slack|signal|imessage>`
+- `--account <id>` (WhatsApp)
+- `--dry-run`
+- `--json`
+- `--verbose`
+
+### `poll`
+Create a poll (WhatsApp or Discord).
+
+Required:
+- `--to <id>`
+- `--question <text>`
+- `--option <choice>` (repeat 2-12 times)
+
+Options:
+- `--max-selections <n>`
+- `--duration-hours <n>` (Discord)
+- `--provider <whatsapp|discord>`
+- `--dry-run`
+- `--json`
+- `--verbose`
+
+### `agent`
+Run one agent turn via the Gateway (or `--local` embedded).
+
+Required:
+- `--message <text>`
+
+Options:
+- `--to <dest>` (for session key and optional delivery)
+- `--session-id <id>`
+- `--thinking <off|minimal|low|medium|high>`
+- `--verbose <on|off>`
+- `--provider <whatsapp|telegram|discord|slack|signal|imessage>`
+- `--local`
+- `--deliver`
+- `--json`
+- `--timeout <seconds>`
+
+### `status`
+Show linked session health and recent recipients.
+
+Options:
+- `--json`
+- `--deep` (probe providers)
+- `--timeout <ms>`
+- `--verbose`
+
+### `health`
+Fetch health from the running Gateway.
+
+Options:
+- `--json`
+- `--timeout <ms>`
+- `--verbose`
+
+### `sessions`
+List stored conversation sessions.
+
+Options:
+- `--json`
+- `--verbose`
+- `--store <path>`
+- `--active <minutes>`
+
+## Gateway
+
+### `gateway`
+Run the WebSocket Gateway.
+
+Options:
+- `--port <port>`
+- `--bind <loopback|tailnet|lan|auto>`
+- `--token <token>`
+- `--auth <token|password>`
+- `--password <password>`
+- `--tailscale <off|serve|funnel>`
+- `--tailscale-reset-on-exit`
+- `--allow-unconfigured`
+- `--force` (kill existing listener on port)
+- `--verbose`
+- `--ws-log <auto|full|compact>`
+- `--compact` (alias for `--ws-log compact`)
+
+### `gateway-daemon`
+Run the Gateway as a long-lived daemon (same options as `gateway`, minus `--allow-unconfigured` and `--force`).
+
+### `gateway <subcommand>`
+Gateway RPC helpers (use `--url`, `--token`, `--password`, `--timeout`, `--expect-final` for each).
+
+Subcommands:
+- `gateway call <method> [--params <json>]`
+- `gateway health`
+- `gateway status`
+- `gateway wake --text <text> [--mode now|next-heartbeat]`
+- `gateway send --to <jidOrPhone> --message <text> [--media-url <url>] [--gif-playback] [--idempotency-key <key>]`
+- `gateway agent --message <text> [--to <jidOrPhone>] [--session-id <id>] [--thinking <level>] [--deliver] [--timeout-seconds <n>] [--idempotency-key <key>]`
+- `gateway stop`
+- `gateway restart`
+
+## Models
+
+See [/concepts/models](/concepts/models) for fallback behavior and scanning strategy.
+
+### `models` (root)
+`clawdbot models` is an alias for `models status`.
+
+### `models list`
+Options:
+- `--all`
+- `--local`
+- `--provider <name>`
+- `--json`
+- `--plain`
+
+### `models status`
+Options:
+- `--json`
+- `--plain`
+
+### `models set <model>`
+Set `agent.model.primary`.
+
+### `models set-image <model>`
+Set `agent.imageModel.primary`.
+
+### `models aliases list|add|remove`
+Options:
+- `list`: `--json`, `--plain`
+- `add <alias> <model>`
+- `remove <alias>`
+
+### `models fallbacks list|add|remove|clear`
+Options:
+- `list`: `--json`, `--plain`
+- `add <model>`
+- `remove <model>`
+- `clear`
+
+### `models image-fallbacks list|add|remove|clear`
+Options:
+- `list`: `--json`, `--plain`
+- `add <model>`
+- `remove <model>`
+- `clear`
+
+### `models scan`
+Options:
+- `--min-params <b>`
+- `--max-age-days <days>`
+- `--provider <name>`
+- `--max-candidates <n>`
+- `--timeout <ms>`
+- `--concurrency <n>`
+- `--yes`
+- `--no-input`
+- `--set-default`
+- `--set-image`
+- `--json`
+
+## Cron + wake
+
+### `wake`
+Enqueue a system event and optionally trigger a heartbeat (Gateway RPC).
+
+Required:
+- `--text <text>`
+
+Options:
+- `--mode <now|next-heartbeat>`
+- `--json`
+- `--url`, `--token`, `--timeout`, `--expect-final`
+
+### `cron`
+Manage scheduled jobs (Gateway RPC). See [/automation/cron-jobs](/automation/cron-jobs).
+
+Subcommands:
+- `cron status [--json]`
+- `cron list [--all] [--json]`
+- `cron add` (requires `--name` and exactly one of `--at` | `--every` | `--cron`, and exactly one payload of `--system-event` | `--message`)
+- `cron edit <id>` (patch fields)
+- `cron rm <id>`
+- `cron enable <id>`
+- `cron disable <id>`
+- `cron runs --id <id> [--limit <n>]`
+- `cron run <id> [--force]`
+
+All `cron` commands accept `--url`, `--token`, `--timeout`, `--expect-final`.
+
+## Nodes
+
+`nodes` talks to the Gateway and targets paired nodes. See [/nodes](/nodes).
+
+Common options:
+- `--url`, `--token`, `--timeout`, `--json`
+
+Subcommands:
+- `nodes status`
+- `nodes describe --node <id|name|ip>`
+- `nodes list`
+- `nodes pending`
+- `nodes approve <requestId>`
+- `nodes reject <requestId>`
+- `nodes rename --node <id|name|ip> --name <displayName>`
+- `nodes invoke --node <id|name|ip> --command <command> [--params <json>] [--invoke-timeout <ms>] [--idempotency-key <key>]`
+- `nodes run --node <id|name|ip> [--cwd <path>] [--env KEY=VAL] [--command-timeout <ms>] [--needs-screen-recording] [--invoke-timeout <ms>] <command...>` (mac only)
+- `nodes notify --node <id|name|ip> [--title <text>] [--body <text>] [--sound <name>] [--priority <passive|active|timeSensitive>] [--delivery <system|overlay|auto>] [--invoke-timeout <ms>]` (mac only)
+
+Camera:
+- `nodes camera list --node <id|name|ip>`
+- `nodes camera snap --node <id|name|ip> [--facing front|back|both] [--device-id <id>] [--max-width <px>] [--quality <0-1>] [--delay-ms <ms>] [--invoke-timeout <ms>]`
+- `nodes camera clip --node <id|name|ip> [--facing front|back] [--device-id <id>] [--duration <ms|10s|1m>] [--no-audio] [--invoke-timeout <ms>]`
+
+Canvas + screen:
+- `nodes canvas snapshot --node <id|name|ip> [--format png|jpg|jpeg] [--max-width <px>] [--quality <0-1>] [--invoke-timeout <ms>]`
+- `nodes screen record --node <id|name|ip> [--screen <index>] [--duration <ms|10s>] [--fps <n>] [--no-audio] [--out <path>] [--invoke-timeout <ms>]`
+
+Location:
+- `nodes location get --node <id|name|ip> [--max-age <ms>] [--accuracy <coarse|balanced|precise>] [--location-timeout <ms>] [--invoke-timeout <ms>]`
+
+## Canvas
+
+Canvas RPC helper (top-level wrapper for `node.invoke`). See [/platforms/mac/canvas](/platforms/mac/canvas).
+
+Common options:
+- `--url`, `--token`, `--timeout`, `--json`
+
+Subcommands:
+- `canvas snapshot [--node <id|name|ip>] [--format png|jpg] [--max-width <px>] [--quality <0-1>]`
+- `canvas present [--node <id|name|ip>] [--target <urlOrPath>] [--x <px>] [--y <px>] [--width <px>] [--height <px>]`
+- `canvas hide [--node <id|name|ip>]`
+- `canvas navigate <url> [--node <id|name|ip>]`
+- `canvas eval [<js>] [--js <code>] [--node <id|name|ip>]`
+- `canvas a2ui push (--jsonl <path> | --text <text>) [--node <id|name|ip>]`
+- `canvas a2ui reset [--node <id|name|ip>]`
+
+## Browser
+
+Browser control CLI (dedicated Chrome/Chromium). See [/tools/browser](/tools/browser).
+
+Common options:
+- `--url <controlUrl>`
+- `--browser-profile <name>`
+- `--json`
+
+Manage:
+- `browser status`
+- `browser start`
+- `browser stop`
+- `browser reset-profile`
+- `browser tabs`
+- `browser open <url>`
+- `browser focus <targetId>`
+- `browser close [targetId]`
+- `browser profiles`
+- `browser create-profile --name <name> [--color <hex>] [--cdp-url <url>]`
+- `browser delete-profile --name <name>`
+
+Inspect:
+- `browser screenshot [targetId] [--full-page] [--ref <ref>] [--element <selector>] [--type png|jpeg]`
+- `browser snapshot [--format aria|ai] [--target-id <id>] [--limit <n>] [--out <path>]`
+
+Actions:
+- `browser navigate <url> [--target-id <id>]`
+- `browser resize <width> <height> [--target-id <id>]`
+- `browser click <ref> [--double] [--button <left|right|middle>] [--modifiers <csv>] [--target-id <id>]`
+- `browser type <ref> <text> [--submit] [--slowly] [--target-id <id>]`
+- `browser press <key> [--target-id <id>]`
+- `browser hover <ref> [--target-id <id>]`
+- `browser drag <startRef> <endRef> [--target-id <id>]`
+- `browser select <ref> <values...> [--target-id <id>]`
+- `browser upload <paths...> [--ref <ref>] [--input-ref <ref>] [--element <selector>] [--target-id <id>] [--timeout-ms <ms>]`
+- `browser fill [--fields <json>] [--fields-file <path>] [--target-id <id>]`
+- `browser dialog --accept|--dismiss [--prompt <text>] [--target-id <id>] [--timeout-ms <ms>]`
+- `browser wait [--time <ms>] [--text <value>] [--text-gone <value>] [--target-id <id>]`
+- `browser evaluate --fn <code> [--ref <ref>] [--target-id <id>]`
+- `browser console [--level <error|warn|info>] [--target-id <id>]`
+- `browser pdf [--target-id <id>]`
+
+## Docs search
+
+### `docs [query...]`
+Search the live docs index.
+
+## TUI
+
+### `tui`
+Open the terminal UI connected to the Gateway.
+
+Options:
+- `--url <url>`
+- `--token <token>`
+- `--password <password>`
+- `--session <key>`
+- `--deliver`
+- `--thinking <level>`
+- `--timeout-ms <ms>`
+- `--history-limit <n>`
@@ -0,0 +1,187 @@
+---
+summary: "Agent workspace: location, layout, and backup strategy"
+read_when:
+  - You need to explain the agent workspace or its file layout
+  - You want to back up or migrate an agent workspace
+---
+# Agent workspace
+
+The workspace is the agent's home. It is the only working directory used for
+file tools and for workspace context. Keep it private and treat it as memory.
+
+This is separate from `~/.clawdbot/`, which stores config, credentials, and
+sessions.
+
+## Default location
+
+- Default: `~/clawd`
+- If `CLAWDBOT_PROFILE` is set and not `"default"`, the default becomes
+  `~/clawd-<profile>`.
+- Override in `~/.clawdbot/clawdbot.json`:
+
+```json5
+{
+  agent: {
+    workspace: "~/clawd"
+  }
+}
+```
+
+`clawdbot onboard`, `clawdbot configure`, or `clawdbot setup` will create the
+workspace and seed the bootstrap files if they are missing.
+
+If you already manage the workspace files yourself, you can disable bootstrap
+file creation:
+
+```json5
+{ agent: { skipBootstrap: true } }
+```
+
+## Workspace file map (what each file means)
+
+These are the standard files Clawdbot expects inside the workspace:
+
+- `AGENTS.md`
+  - Operating instructions for the agent and how it should use memory.
+  - Loaded at the start of every session.
+  - Good place for rules, priorities, and "how to behave" details.
+
+- `SOUL.md`
+  - Persona, tone, and boundaries.
+  - Loaded every session.
+
+- `USER.md`
+  - Who the user is and how to address them.
+  - Loaded every session.
+
+- `IDENTITY.md`
+  - The agent's name, vibe, and emoji.
+  - Created/updated during the bootstrap ritual.
+
+- `TOOLS.md`
+  - Notes about your local tools and conventions.
+  - Does not control tool availability; it is only guidance.
+
+- `HEARTBEAT.md`
+  - Optional tiny checklist for heartbeat runs.
+  - Keep it short to avoid token burn.
+
+- `BOOTSTRAP.md`
+  - One-time first-run ritual.
+  - Only created for a brand-new workspace.
+  - Delete it after the ritual is complete.
+
+- `memory/YYYY-MM-DD.md`
+  - Daily memory log (one file per day).
+  - Recommended to read today + yesterday on session start.
+
+- `MEMORY.md` (optional)
+  - Curated long-term memory.
+  - Only load in the main, private session (not shared/group contexts).
+
+- `skills/` (optional)
+  - Workspace-specific skills.
+  - Overrides managed/bundled skills when names collide.
+
+- `canvas/` (optional)
+  - Canvas UI files for node displays (for example `canvas/index.html`).
+
+If any bootstrap file is missing, Clawdbot injects a "missing file" marker into
+the session and continues. `clawdbot setup` can recreate missing defaults
+without overwriting existing files.
+
+## What is NOT in the workspace
+
+These live under `~/.clawdbot/` and should NOT be committed to the workspace repo:
+
+- `~/.clawdbot/clawdbot.json` (config)
+- `~/.clawdbot/credentials/` (OAuth tokens, API keys)
+- `~/.clawdbot/agents/<agentId>/sessions/` (session transcripts + metadata)
+- `~/.clawdbot/skills/` (managed skills)
+
+If you need to migrate sessions or config, copy them separately and keep them
+out of version control.
+
+## Git backup (recommended, private)
+
+Treat the workspace as private memory. Put it in a **private** git repo so it is
+backed up and recoverable.
+
+Run these steps on the machine where the Gateway runs (that is where the
+workspace lives).
+
+### 1) Initialize the repo
+
+```bash
+cd ~/clawd
+git init
+git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
+git commit -m "Add agent workspace"
+```
+
+### 2) Add a private remote (beginner-friendly options)
+
+Option A: GitHub web UI
+
+1. Create a new **private** repository on GitHub.
+2. Do not initialize with a README (avoids merge conflicts).
+3. Copy the HTTPS remote URL.
+4. Add the remote and push:
+
+```bash
+git branch -M main
+git remote add origin <https-url>
+git push -u origin main
+```
+
+Option B: GitHub CLI (`gh`)
+
+```bash
+gh auth login
+gh repo create clawd-workspace --private --source . --remote origin --push
+```
+
+### 3) Ongoing updates
+
+```bash
+git status
+git add .
+git commit -m "Update memory"
+git push
+```
+
+## Do not commit secrets
+
+Even in a private repo, avoid storing secrets in the workspace:
+
+- API keys, OAuth tokens, passwords, or private credentials.
+- Anything under `~/.clawdbot/`.
+- Raw dumps of chats or sensitive attachments.
+
+If you must store sensitive references, use placeholders and keep the real
+secret elsewhere (password manager, environment variables, or `~/.clawdbot/`).
+
+Suggested `.gitignore` starter:
+
+```gitignore
+.DS_Store
+.env
+**/*.key
+**/*.pem
+**/secrets*
+```
+
+## Moving the workspace to a new machine
+
+1. Clone the repo to the desired path (default `~/clawd`).
+2. Set `agent.workspace` to that path in `~/.clawdbot/clawdbot.json`.
+3. Run `clawdbot setup --workspace <path>` to seed any missing files.
+4. If you need sessions, copy `~/.clawdbot/agents/<agentId>/sessions/` from the
+   old machine separately.
+
+## Advanced notes
+
+- Multi-agent routing can use different workspaces per agent. See
+  `docs/provider-routing.md` for routing configuration.
+- If `agent.sandbox` is enabled, non-main sessions can use per-session sandbox
+  workspaces under `agent.sandbox.workspaceRoot`.
@@ -13,9 +13,11 @@ CLAWDBOT uses a single agent workspace directory (`agent.workspace`) as the agen

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

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

 ## Bootstrap files (injected)

@@ -50,7 +52,7 @@ Clawdbot loads skills from three locations (workspace wins on name conflict):
 - Managed/local: `~/.clawdbot/skills`
 - Workspace: `<workspace>/skills`

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

 ## p-mono integration

@@ -89,7 +91,7 @@ message is injected before the next assistant response.

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

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

 ---

-*Next: [Group Chats](https://docs.clawd.bot/group-messages)* 🦞
+*Next: [Group Chats](/concepts/group-messages)* 🦞
@@ -46,7 +46,7 @@ Last updated: 2026-01-05
 - **Clients (mac app / CLI / web admin)**  
  - One WS connection per client.  
  - Send requests (`health`, `status`, `send`, `agent`, `system-presence`, toggles) and subscribe to events (`tick`, `agent`, `presence`, `shutdown`).
-  - On macOS, the app can also be invoked via deep links (`clawdbot://agent?...`) which translate into the same Gateway `agent` request path (see [`docs/macos.md`](https://docs.clawd.bot/macos)).
+  - On macOS, the app can also be invoked via deep links (`clawdbot://agent?...`) which translate into the same Gateway `agent` request path (see [`docs/macos.md`](/platforms/macos)).
 - **Agent process (Pi)**  
  - Spawned by the Gateway on demand for `agent` calls; streams events back over the same WS connection.
 - **WebChat**  
@@ -9,6 +9,7 @@ Clawdbot treats group chats consistently across surfaces: WhatsApp, Telegram, Di

 ## Session keys
 - Group sessions use `agent:<agentId>:<provider>:group:<id>` session keys (rooms/channels use `agent:<agentId>:<provider>:channel:<id>`).
+- Telegram forum topics add `:topic:<threadId>` to the group id so each topic has its own session.
 - Direct chats use the main session (or per-sender if configured).
 - Heartbeats are skipped for group sessions.

@@ -118,6 +119,7 @@ Group inbound payloads set:
 - `GroupSubject` (if known)
 - `GroupMembers` (if known)
 - `WasMentioned` (mention gating result)
+- Telegram forum topics also include `MessageThreadId` and `IsForum`.

 The agent system prompt includes a group intro on the first turn of a new group session.

@@ -127,4 +129,4 @@ The agent system prompt includes a group intro on the first turn of a new group
 - Group replies always go back to the same `chat_id`.

 ## WhatsApp specifics
-See [`docs/group-messages.md`](https://docs.clawd.bot/group-messages) for WhatsApp-only behavior (history injection, mention handling details).
+See [`docs/group-messages.md`](/concepts/group-messages) for WhatsApp-only behavior (history injection, mention handling details).
@@ -85,9 +85,9 @@ timeouts that exhausted profile rotation.

 ## Related config

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

-See [`docs/models.md`](https://docs.clawd.bot/models) for the broader model selection and fallback overview.
+See [`docs/models.md`](/concepts/models) for the broader model selection and fallback overview.
@@ -0,0 +1,108 @@
+---
+summary: "Plan for models CLI: scan, list, aliases, fallbacks, status"
+read_when:
+  - Adding or modifying models CLI (models list/set/scan/aliases/fallbacks)
+  - Changing model fallback behavior or selection UX
+  - Updating model scan probes (tools/images)
+---
+# Models CLI plan
+
+See [`docs/model-failover.md`](/concepts/model-failover) for how auth profiles rotate (OAuth vs API keys), cooldowns, and how that interacts with model fallbacks.
+
+Goal: give clear model visibility + control (configured vs available), plus scan tooling
+that prefers tool-call + image-capable models and maintains ordered fallbacks.
+
+## Model recommendations
+
+Through testing, we’ve found [Claude Opus 4.5](https://www.anthropic.com/claude/opus) is the most useful general-purpose model for anything coding-related. We suggest [GPT-5.2-Codex](https://developers.openai.com/codex/models) for coding and sub-agents. For personal assistant work, nothing comes close to Opus. If you’re going all-in on Claude, we recommend the [Claude Max $200 subscription](https://www.anthropic.com/pricing/).
+
+## Model discussions (community notes)
+
+Anecdotal notes from the Discord thread on January 4–5, 2026. Treat as “what people reported,” not guarantees.
+
+**Reported working well**
+- [Claude Opus 4.5](https://www.anthropic.com/claude/opus): best quality, but expensive and easy to hit limits.
+- [Claude Sonnet 4.5](https://www.anthropic.com/claude/sonnet): solid fallback when Opus caps out.
+- [GLM](https://www.zhipuai.cn/en/): used as a worker model under orchestration.
+- [MiniMax M2.1](https://platform.minimax.io/docs/guides/models-intro): “good enough” fallback for grunt tasks.
+- “Temu-Sonnet” (community shorthand) for MiniMax quality vs Claude Sonnet.
+- [Gemini 3 Pro](https://deepmind.google/en/models/gemini/pro/): some users said it maps Clawdbot structure well.
+
+**Mixed / unclear**
+- [Antigravity](https://blog.google/technology/ai/google-ai-updates-november-2025/) (Claude Opus access): some reported extra Opus quota, pricing/limits unclear.
+
+**Reported weak in Clawdbot**
+- [GPT-5.2-Codex](https://developers.openai.com/codex/models) inside Clawdbot: considered rough for conversation or assistant tasks.
+- [Grok](https://docs.x.ai/docs/models/grok-4): tried, abandoned.
+
+**Tooling note**
+- [Codex CLI](https://developers.openai.com/codex/cli) felt stronger than embedded use.
+
+**Theme**
+- Token burn feels higher than expected in long sessions; people suspect context buildup + tool outputs. Pruning/compaction helps. Check session logs before blaming providers. See [/concepts/session](/concepts/session) and [/concepts/model-failover](/concepts/model-failover).
+
+## Models CLI
+
+See [/cli](/cli) for the full command tree and CLI flags.
+
+## Config changes
+
+- `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 from auth profiles or `OPENROUTER_API_KEY`
+- Optional filters: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates`
+- Probe controls: `--timeout`, `--concurrency`
+
+Probes (direct pi-ai complete)
+- Tool-call probe (required):
+  - Provide a dummy tool, verify tool call emitted.
+- Image probe (preferred):
+  - Prompt includes 1x1 PNG; success if no "unsupported image" error.
+
+Scoring/selection
+- 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)
+- Multiselect list with per-model stats:
+  - model id, tool ok, image ok, median latency, context, inferred params.
+- Pre-select top N (default 6).
+- Non-TTY: auto-select; require `--yes`/`--no-input` to apply.
+
+Output
+- 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.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.
+- See [`docs/model-failover.md`](/concepts/model-failover) for auth profile rotation, cooldowns, and timeout handling.
+
+## Tests
+
+- Unit: scan selection ordering + probe classification.
+- CLI: list/aliases/fallbacks add/remove + scan writes config.
+- Status: shows last used model + fallbacks.
+
+## Docs
+
+- Update [`docs/configuration.md`](/gateway/configuration) with `agent.models` + `agent.model` + `agent.imageModel`.
+- Keep this doc current when CLI surface or scan logic changes.
+- Note provider aliases like `z.ai/*` -> `zai/*` when relevant.
+- Provider ids in model refs are normalized to lowercase.
@@ -16,6 +16,7 @@ Goal: deterministic replies per provider, while supporting multi-agent + multi-a
 - **Canonical direct session (per agent):** direct chats collapse to `agent:<agentId>:<mainKey>` (default `main`). Groups/channels stay isolated per agent:
  - group: `agent:<agentId>:<provider>:group:<id>`
  - channel/room: `agent:<agentId>:<provider>:channel:<id>`
+  - Telegram forum topics: `agent:<agentId>:telegram:group:<chatId>:topic:<threadId>`
 - **Session store:** per-agent store lives under `~/.clawdbot/agents/<agentId>/sessions/sessions.json` (override via `session.store` with `{agentId}` templating). JSONL transcripts live next to it.
 - **WebChat:** attaches to the selected agent’s main session (so desktop reflects cross-provider history for that agent).
 - **Implementation hints:**
@@ -126,15 +126,18 @@ Spawn a sub-agent run in an isolated session and announce the result back to the
 Parameters:
 - `task` (required)
 - `label?` (optional; used for logs/UI)
- `timeoutSeconds?` (default 0; 0 = fire-and-forget)
- `cleanup?` (`delete|keep`, default `delete`)
+- `model?` (optional; overrides the sub-agent model; invalid values error)
+- `timeoutSeconds?` (optional; omit for long-running jobs; if set, Clawdbot aborts the sub-agent when the timeout elapses)
+- `cleanup?` (`delete|keep`, default `keep`)

 Behavior:
- Starts a new `subagent:<uuid>` session with `deliver: false`.
+- Starts a new `agent:<id>:subagent:<uuid>` session with `deliver: false`.
 - Sub-agents default to the full tool set **minus session tools** (configurable via `agent.subagents.tools`).
 - Sub-agents are not allowed to call `sessions_spawn` (no sub-agent → sub-agent spawning).
 - After completion (or best-effort wait), Clawdbot runs a sub-agent **announce step** and posts the result to the requester chat provider.
 - Reply exactly `ANNOUNCE_SKIP` during the announce step to stay silent.
+- Sub-agent sessions are auto-archived after `agent.subagents.archiveAfterMinutes` (default: 60).
+- Announce replies include a stats line (runtime, tokens, sessionKey/sessionId, transcript path, and optional cost).

 ## Sandbox Session Visibility

@@ -25,7 +25,9 @@ All session state is **owned by the gateway** (the “master” Clawdbot). UI cl
 - Direct chats collapse to the per-agent primary key: `agent:<agentId>:<mainKey>`.
  - Multiple phone numbers and providers can map to the same agent main key; they act as transports into one conversation.
 - Group chats isolate state: `agent:<agentId>:<provider>:group:<id>` (rooms/channels use `agent:<agentId>:<provider>:channel:<id>`).
+  - Telegram forum topics append `:topic:<threadId>` to the group id for isolation.
  - Legacy `group:<id>` keys are still recognized for migration.
+  - Inbound contexts may still use `group:<id>`; the provider is inferred from `Provider` and normalized to the canonical `agent:<agentId>:<provider>:group:<id>` form.
 - Other sources:
  - Cron jobs: `cron:<job.id>`
  - Webhooks: `hook:<uuid>` (unless explicitly set by the hook)
@@ -76,8 +78,9 @@ Send these as standalone messages so they register.
 ## Inspecting
 - `pnpm clawdbot status` — shows store path and recent sessions.
 - `pnpm clawdbot sessions --json` — dumps every entry (filter with `--active <minutes>`).
- `pnpm clawdbot gateway call sessions.list --params '{}'` — fetch sessions from the running gateway (use `--url`/`--token` for remote gateway access).
+- `clawdbot gateway call sessions.list --params '{}'` — fetch sessions from the running gateway (use `--url`/`--token` for remote gateway access).
 - Send `/status` as a standalone message in chat to see whether the agent is reachable, how much of the session context is used, current thinking/verbose toggles, and when your WhatsApp web creds were last refreshed (helps spot relink needs).
+- Send `/stop` as a standalone message to abort the current run.
 - Send `/compact` (optional instructions) as a standalone message to summarize older context and free up window space.
 - JSONL transcripts can be opened directly to review full turns.

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

-Canonical session management docs live in [`docs/session.md`](https://docs.clawd.bot/session).
+Canonical session management docs live in [`docs/session.md`](/concepts/session).
@@ -1,385 +0,0 @@
---
-summary: "RFC: Cron jobs + wakeups for Clawd/Clawdbot (main vs isolated sessions)"
-read_when:
-  - Designing scheduled jobs, alarms, or wakeups
-  - Adding Gateway methods or CLI commands for automation
-  - Adjusting heartbeat behavior or session routing
---
-
-# RFC: Cron jobs + wakeups for Clawd
-
-Status: Draft  
-Last updated: 2025-12-13
-
-## Context
-
-Clawdbot already has:
- A **gateway heartbeat runner** that runs the agent with the configured heartbeat prompt (default: `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`) and suppresses `HEARTBEAT_OK` ([`src/infra/heartbeat-runner.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/infra/heartbeat-runner.ts)).
- A lightweight, in-memory **system event queue** (`enqueueSystemEvent`) that is injected into the next **main session** turn (`drainSystemEvents` in [`src/auto-reply/reply.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/auto-reply/reply.ts)).
- A WebSocket **Gateway** daemon that is intended to be always-on ([`docs/gateway.md`](https://docs.clawd.bot/gateway)).
-
-This RFC adds a small “cron job system” so Clawd can schedule future work and reliably wake itself up:
- **Delayed**: run on the *next* normal heartbeat tick
- **Immediate**: run *now* (trigger a heartbeat immediately)
- **Isolated jobs**: optionally run in their own session that does not pollute the main session and can run concurrently (within configured limits).
-
-## Goals
-
- Provide a **persistent job store** and an **in-process scheduler** owned by the Gateway.
- Allow each job to target either:
-  - `sessionTarget: "main"`: inject as `System:` lines and rely on the main heartbeat (or trigger it immediately).
-  - `sessionTarget: "isolated"`: run an agent turn in a dedicated session key (job session), optionally delivering a message and/or posting a summary back to main.
- Expose a stable control surface:
-  - **Gateway methods** (`cron.*`, `wake`) for programmatic usage (mac app, CLI, agents).
-  - **CLI commands** (`clawdbot cron ...`) to add/remove/edit/list and to debug `run`.
- Produce clear, structured **logs** for job lifecycle and execution outcomes.
-
-## Non-goals (v1)
-
- Multi-host distributed scheduling.
- Exactly-once semantics across crashes (we aim for “at-least-once with idempotency hooks”).
- A full Unix-cron parser as the only schedule format (we can support it, but v1 should not require complex cron features to be useful).
-
-## Terminology
-
- **Wake**: a request to ensure the agent gets a turn soon (either right now or next heartbeat).
- **Main session**: the canonical session bucket (default key `"main"`) that receives `System:` events.
- **Isolated session**: a per-job session key (e.g. `cron:<jobId>`) with its own session id / session file.
-
-## User stories
-
- “Remind me in 20 minutes” → add a one-shot job that triggers an immediate heartbeat at T+20m.
- “Every weekday at 7:30, wake me up and start music” → recurring job, isolated session, deliver to WhatsApp.
- “Every hour, check battery; only interrupt me if < 20%” → isolated job that decides whether to deliver; may also post a brief status to main.
- “Next heartbeat, please check calendar” → delayed wake targeting main session.
-
-## Job model
-
-### Storage schema (v1)
-
-Each job is a JSON object with stable keys (unknown keys ignored for forward compatibility):
-
- `id: string` (UUID)
- `name: string` (required)
- `description?: string` (optional)
- `enabled: boolean`
- `createdAtMs: number`
- `updatedAtMs: number`
- `schedule` (one of)
-  - `{"kind":"at","atMs":number}` (one-shot)
-  - `{"kind":"every","everyMs":number,"anchorMs"?:number}` (simple interval)
-  - `{"kind":"cron","expr":string,"tz"?:string}` (optional; see “Schedule parsing”)
- `sessionTarget: "main" | "isolated"`
- `wakeMode: "next-heartbeat" | "now"`
-  - For `sessionTarget:"isolated"`, `wakeMode:"now"` means “run immediately when due”.
-  - For `sessionTarget:"main"`, `wakeMode` controls whether we trigger the heartbeat immediately or just enqueue and wait.
- `payload` (one of)
-  - `{"kind":"systemEvent","text":string}` (enqueue as `System:`)
-  - `{"kind":"agentTurn","message":string,"deliver"?:boolean,"provider"?: "last"|"whatsapp"|"telegram"|"discord"|"signal"|"imessage","to"?:string,"timeoutSeconds"?:number}`
- `isolation` (optional; only meaningful for isolated jobs)
-  - `{"postToMainPrefix"?: string}`
- `runtime` (optional)
-  - `{"maxAttempts"?:number,"retryBackoffMs"?:number}` (best-effort retries; defaults off)
- `state` (runtime-maintained)
-  - `{"nextRunAtMs":number,"lastRunAtMs"?:number,"lastStatus"?: "ok"|"error"|"skipped","lastError"?:string,"lastDurationMs"?:number}`
-
-### Key behavior
-
- `sessionTarget:"main"` jobs always enqueue `payload.kind:"systemEvent"` (directly or derived from `agentTurn` results; see below).
- `sessionTarget:"isolated"` jobs create/use a stable session key: `cron:<jobId>`.
-
-## Storage location
-
-Cron persists everything under `~/.clawdbot/cron/`:
- Job store: `~/.clawdbot/cron/jobs.json`
- Run history: `~/.clawdbot/cron/runs/<jobId>.jsonl`
-
-You can override the job store path via `cron.store` in config.
-
-The scheduler should never require additional configuration for the base directory (Clawdbot already treats `~/.clawdbot` as fixed).
-
-## Enabling
-
-Cron execution is enabled by default inside the Gateway.
-
-To disable it, set:
-
-```json5
-{
-  cron: {
-    enabled: false,
-    // optional:
-    store: "~/.clawdbot/cron/jobs.json",
-    maxConcurrentRuns: 1
-  }
-}
-```
-
-You can also disable scheduling via the environment variable `CLAWDBOT_SKIP_CRON=1`.
-
-## Scheduler design
-
-### Ownership
-
-The Gateway owns:
- the scheduler timer,
- job store reads/writes,
- job execution (enqueue system events and/or agent turns).
-
-This keeps scheduling unified with the always-on process and prevents “two schedulers” when multiple CLIs run.
-
-### Timer strategy
-
- Maintain an in-memory heap/array of enabled jobs keyed by `state.nextRunAtMs`.
- Use a **single `setTimeout`** to wake at the earliest next run.
- On wake:
-  - compute all due jobs (now >= nextRunAtMs),
-  - mark them “in flight” (in memory),
-  - persist updated `state` (at least bump `nextRunAtMs` / `lastRunAtMs`) before starting execution to minimize duplicate runs on crash,
-  - execute jobs (with concurrency limits),
-  - persist final `lastStatus/lastError/lastDurationMs`,
-  - re-arm timer for the next earliest run.
-
-### Schedule parsing
-
-V1 can ship with `at` + `every` without extra deps.
-
-If we add `"kind":"cron"`:
- Use a well-maintained parser (we use `croner`) and support:
-  - 5-field cron (`min hour dom mon dow`) at minimum
-  - optional `tz`
- Store `nextRunAtMs` computed by the parser; re-compute after each run.
-
-## Execution semantics
-
-### Main session jobs
-
-Main session jobs do not run the agent directly by default.
-
-When due:
-1) `enqueueSystemEvent(job.payload.text)` (or a derived message)
-2) If `wakeMode:"now"`, trigger an immediate heartbeat run (see “Heartbeat wake hook”).
-3) Otherwise do nothing else (the next scheduled heartbeat will pick up the system event).
-
-Why: This keeps the main session’s “proactive” behavior centralized in the heartbeat rules and avoids ad-hoc agent turns that might fight with inbound message processing.
-
-### Isolated session jobs
-
-Isolated jobs run an agent turn in a dedicated session key, intended to be separate from main.
-
-When due:
- Build a message body that includes schedule metadata, e.g.:
-  - `"[cron:<jobId>] <job.name>: <payload.message>"`
- Execute via the same agent runner path as other command-mode runs, but pinned to:
-  - `sessionKey = cron:<jobId>`
-  - `sessionId = store[sessionKey].sessionId` (create if missing)
- Optionally deliver output (`payload.deliver === true`) to the configured provider/to.
- Isolated jobs always enqueue a summary system event to the main session when they finish (derived from the last agent text output).
-  - Prefix defaults to `Cron`, and can be customized via `isolation.postToMainPrefix`.
- If `deliver` is omitted/false, nothing is sent to external providers; you still get the main-session summary and can inspect the full isolated transcript in `cron:<jobId>`.
-
-### “Run in parallel to main”
-
-Clawdbot currently serializes command execution through a global in-process queue ([`src/process/command-queue.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/process/command-queue.ts)) to avoid collisions.
-
-To support isolated cron jobs running “in parallel”, we should introduce **lanes** (keyed queues) plus a global concurrency cap:
- Lane `"main"`: inbound auto-replies + main heartbeat.
- Lane `"cron"` (or `cron:<jobId>`): isolated jobs.
- Configurable `cron.maxConcurrentRuns` (default 1 or 2).
-
-This yields:
- isolated jobs can overlap with the main lane (up to cap),
- each lane still preserves ordering for its own work (optional),
- we retain safety knobs to prevent runaway resource contention.
-
-## Heartbeat wake hook (immediate vs next heartbeat)
-
-We need a way for the Gateway (or the scheduler) to request an immediate heartbeat without duplicating heartbeat logic.
-
-Design:
- `startHeartbeatRunner` owns the real heartbeat execution and installs a wake handler.
- Wake hook lives in [`src/infra/heartbeat-wake.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/infra/heartbeat-wake.ts):
-  - `setHeartbeatWakeHandler(fn | null)` installed by the heartbeat runner
-  - `requestHeartbeatNow({ reason, coalesceMs? })`
- If the handler is absent, the request is stored as “pending”; the next time the handler is installed, it runs once.
- Coalesce rapid calls and respect the “skip when queue busy” behavior (retry soon vs dropping).
-
-## Run history log (JSONL)
-
-In addition to normal structured logs, the Gateway writes an append-only run history “ledger” (JSONL) whenever a job finishes. This is intended for quick debugging (“did the job run, when, and what happened?”).
-
-Path rules:
- Run logs are stored per job next to the store: `.../runs/<jobId>.jsonl`.
-
-Retention:
- Best-effort pruning when the file grows beyond ~2MB; keep the newest ~2000 lines.
-
-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):
-
- `wake`
-  - params: `{ mode: "now" | "next-heartbeat", text: string }`
-  - effect: `enqueueSystemEvent(text)`, plus optional immediate heartbeat trigger
-
- `cron.list`
-  - params: optional `{ includeDisabled?: boolean }`
-  - returns: `{ jobs: CronJob[] }`
-
- `cron.add`
-  - params: job payload without `id/state` (server generates and returns created job)
-
- `cron.update`
-  - params: `{ id: string, patch: Partial<CronJobWritableFields> }`
-
- `cron.remove`
-  - params: `{ id: string }`
-
- `cron.run`
-  - params: `{ id: string, mode?: "due" | "force" }` (debugging; does not change schedule unless `force` requires it)
-
- `cron.runs`
-  - params: `{ id: string, limit?: number }`
-  - returns: `{ entries: CronRunLogEntry[] }`
-  - note: `id` is required (runs are stored per-job).
-
-The Gateway should broadcast a `cron` event for UI/debug:
- event: `cron`
-  - payload: `{ jobId, action: "added"|"updated"|"removed"|"started"|"finished", status?, error?, nextRunAtMs? }`
-
-## CLI surface
-
-Add a `cron` command group (all commands should also support `--json` where sensible):
-
- `clawdbot cron list [--json] [--all]`
- `clawdbot cron add ...`
-  - schedule flags:
-    - `--at <iso8601|ms|relative>` (one-shot)
-    - `--every <duration>` (e.g. `10m`, `1h`)
-    - `--cron "<expr>" [--tz "<tz>"]`
-  - target flags:
-    - `--session main|isolated`
-    - `--wake now|next-heartbeat`
-  - payload flags (choose one):
-    - `--system-event "<text>"`
-    - `--message "<agent message>" [--deliver] [--provider last|whatsapp|telegram|discord|slack|signal|imessage] [--to <dest>]`
-
- `clawdbot cron edit <id> ...` (patch-by-flags, non-interactive)
- `clawdbot cron rm <id>`
- `clawdbot cron enable <id>` / `clawdbot cron disable <id>`
- `clawdbot cron run <id> [--force]` (debug)
- `clawdbot cron runs --id <id> [--limit <n>]` (run history)
- `clawdbot cron status` (scheduler enabled + next wake)
-
-Additionally:
- `clawdbot wake --mode now|next-heartbeat --text "<text>"` as a thin wrapper around `wake` for agents to call.
-
-## Examples
-
-### Run once at a specific time
-
-One-shot reminder that targets the main session and triggers a heartbeat immediately at the scheduled time:
-
-```bash
-clawdbot cron add \
-  --at "2025-12-14T07:00:00-08:00" \
-  --session main \
-  --wake now \
-  --system-event "Alarm: wake up (meeting in 30 minutes)."
-```
-
-### Run daily (calendar-accurate)
-
-Daily at 07:00 in a specific timezone (preferred over “every 24h” to avoid DST drift):
-
-```bash
-clawdbot cron add \
-  --cron "0 7 * * *" \
-  --tz "America/Los_Angeles" \
-  --session isolated \
-  --wake now \
-  --message "Daily check: scan calendar + inbox; deliver only if urgent." \
-  --deliver \
-  --provider last
-```
-
-### Run weekly (every Wednesday)
-
-Every Wednesday at 09:00:
-
-```bash
-clawdbot cron add \
-  --cron "0 9 * * 3" \
-  --tz "America/Los_Angeles" \
-  --session isolated \
-  --wake now \
-  --message "Weekly: summarize status and remind me of goals." \
-  --deliver \
-  --provider last
-```
-
-### “Next heartbeat”
-
-Enqueue a note for the main session but let the existing heartbeat cadence pick it up:
-
-```bash
-clawdbot wake --mode next-heartbeat --text "Next heartbeat: check battery + upcoming meetings."
-```
-
-## Logging & observability
-
-Logging requirements:
- Use `getChildLogger({ module: "cron", jobId, runId, name })` for every run.
- Log lifecycle:
-  - store load/save (debug; include job count)
-  - schedule recompute (debug; include nextRunAt)
-  - job start/end (info)
-  - job skipped (info; include reason)
-  - job error (warn; include error + stack where available)
- Emit a concise user-facing line to stdout when running in CLI mode (similar to heartbeat logs).
-
-Suggested log events:
- `cron: scheduler started` (jobCount, nextWakeAt)
- `cron: job started` (jobId, scheduleKind, sessionTarget, wakeMode)
- `cron: job finished` (status, durationMs, nextRunAtMs)
- When `cron.enabled` is false, the Gateway logs `cron: disabled` and jobs will not run automatically (the CLI warns on `cron add`/`cron edit`).
- Use `clawdbot cron status` to confirm the scheduler is enabled and see the next wake time.
-
-## Safety & security
-
- Respect existing allowlists/routing rules: delivery defaults should not send to arbitrary destinations unless explicitly configured.
- Provide a global “kill switch”:
-  - `cron.enabled: boolean` (default `true`).
-  - `gateway method set-heartbeats` already exists; cron should have similar.
- Avoid persistence of sensitive payloads unless requested; job text may contain private content.
-
-## Testing plan (v1)
-
- Unit tests:
-  - schedule computation for `at` and `every`
-  - job store read/write + migration behavior
-  - lane concurrency: main vs cron overlap is bounded
-  - “wake now” coalescing and pending behavior when provider not ready
- Integration tests:
-  - start Gateway with `CLAWDBOT_SKIP_PROVIDERS=1`, add jobs, list/edit/remove
-  - simulate due jobs and assert `enqueueSystemEvent` called + cron events broadcast
-
-## Rollout plan
-
-1) Add the `wake` primitive + heartbeat wake hook (no persistent jobs yet).
-2) Add `cron.*` API and CLI wrappers with `at` + `every`.
-3) Add optional cron expression parsing (`kind:"cron"`) if needed.
-4) Add UI surfacing in WebChat/macOS app (optional).
@@ -20,78 +20,680 @@
      "url": "https://github.com/clawdbot/clawdbot/releases"
    }
  ],
+  "redirects": [
+    {
+      "source": "/cron",
+      "destination": "/cron-jobs"
+    },
+    {
+      "source": "/cron/",
+      "destination": "/cron-jobs"
+    },
+    {
+      "source": "/model",
+      "destination": "/models"
+    },
+    {
+      "source": "/model/",
+      "destination": "/models"
+    },
+    {
+      "source": "/AGENTS.default",
+      "destination": "/reference/AGENTS.default"
+    },
+    {
+      "source": "/RELEASING",
+      "destination": "/reference/RELEASING"
+    },
+    {
+      "source": "/agent",
+      "destination": "/concepts/agent"
+    },
+    {
+      "source": "/agent-loop",
+      "destination": "/concepts/agent-loop"
+    },
+    {
+      "source": "/agent-send",
+      "destination": "/tools/agent-send"
+    },
+    {
+      "source": "/agent-workspace",
+      "destination": "/concepts/agent-workspace"
+    },
+    {
+      "source": "/android",
+      "destination": "/platforms/android"
+    },
+    {
+      "source": "/architecture",
+      "destination": "/concepts/architecture"
+    },
+    {
+      "source": "/audio",
+      "destination": "/nodes/audio"
+    },
+    {
+      "source": "/background-process",
+      "destination": "/gateway/background-process"
+    },
+    {
+      "source": "/bash",
+      "destination": "/tools/bash"
+    },
+    {
+      "source": "/bonjour",
+      "destination": "/gateway/bonjour"
+    },
+    {
+      "source": "/browser",
+      "destination": "/tools/browser"
+    },
+    {
+      "source": "/browser-linux-troubleshooting",
+      "destination": "/tools/browser-linux-troubleshooting"
+    },
+    {
+      "source": "/bun",
+      "destination": "/install/bun"
+    },
+    {
+      "source": "/camera",
+      "destination": "/nodes/camera"
+    },
+    {
+      "source": "/clawd",
+      "destination": "/start/clawd"
+    },
+    {
+      "source": "/clawdhub",
+      "destination": "/tools/clawdhub"
+    },
+    {
+      "source": "/configuration",
+      "destination": "/gateway/configuration"
+    },
+    {
+      "source": "/control-ui",
+      "destination": "/web/control-ui"
+    },
+    {
+      "source": "/cron-jobs",
+      "destination": "/automation/cron-jobs"
+    },
+    {
+      "source": "/dashboard",
+      "destination": "/web/dashboard"
+    },
+    {
+      "source": "/device-models",
+      "destination": "/reference/device-models"
+    },
+    {
+      "source": "/discord",
+      "destination": "/providers/discord"
+    },
+    {
+      "source": "/discovery",
+      "destination": "/gateway/discovery"
+    },
+    {
+      "source": "/docker",
+      "destination": "/install/docker"
+    },
+    {
+      "source": "/doctor",
+      "destination": "/gateway/doctor"
+    },
+    {
+      "source": "/elevated",
+      "destination": "/tools/elevated"
+    },
+    {
+      "source": "/faq",
+      "destination": "/start/faq"
+    },
+    {
+      "source": "/gateway-lock",
+      "destination": "/gateway/gateway-lock"
+    },
+    {
+      "source": "/getting-started",
+      "destination": "/start/getting-started"
+    },
+    {
+      "source": "/gmail-pubsub",
+      "destination": "/automation/gmail-pubsub"
+    },
+    {
+      "source": "/grammy",
+      "destination": "/providers/grammy"
+    },
+    {
+      "source": "/group-messages",
+      "destination": "/concepts/group-messages"
+    },
+    {
+      "source": "/groups",
+      "destination": "/concepts/groups"
+    },
+    {
+      "source": "/health",
+      "destination": "/gateway/health"
+    },
+    {
+      "source": "/heartbeat",
+      "destination": "/gateway/heartbeat"
+    },
+    {
+      "source": "/hubs",
+      "destination": "/start/hubs"
+    },
+    {
+      "source": "/images",
+      "destination": "/nodes/images"
+    },
+    {
+      "source": "/imessage",
+      "destination": "/providers/imessage"
+    },
+    {
+      "source": "/ios",
+      "destination": "/platforms/ios"
+    },
+    {
+      "source": "/linux",
+      "destination": "/platforms/linux"
+    },
+    {
+      "source": "/location",
+      "destination": "/providers/location"
+    },
+    {
+      "source": "/location-command",
+      "destination": "/nodes/location-command"
+    },
+    {
+      "source": "/logging",
+      "destination": "/gateway/logging"
+    },
+    {
+      "source": "/lore",
+      "destination": "/start/lore"
+    },
+    {
+      "source": "/mac/bun",
+      "destination": "/platforms/mac/bun"
+    },
+    {
+      "source": "/mac/canvas",
+      "destination": "/platforms/mac/canvas"
+    },
+    {
+      "source": "/mac/child-process",
+      "destination": "/platforms/mac/child-process"
+    },
+    {
+      "source": "/mac/dev-setup",
+      "destination": "/platforms/mac/dev-setup"
+    },
+    {
+      "source": "/mac/health",
+      "destination": "/platforms/mac/health"
+    },
+    {
+      "source": "/mac/icon",
+      "destination": "/platforms/mac/icon"
+    },
+    {
+      "source": "/mac/logging",
+      "destination": "/platforms/mac/logging"
+    },
+    {
+      "source": "/mac/menu-bar",
+      "destination": "/platforms/mac/menu-bar"
+    },
+    {
+      "source": "/mac/peekaboo",
+      "destination": "/platforms/mac/peekaboo"
+    },
+    {
+      "source": "/mac/permissions",
+      "destination": "/platforms/mac/permissions"
+    },
+    {
+      "source": "/mac/release",
+      "destination": "/platforms/mac/release"
+    },
+    {
+      "source": "/mac/remote",
+      "destination": "/platforms/mac/remote"
+    },
+    {
+      "source": "/mac/signing",
+      "destination": "/platforms/mac/signing"
+    },
+    {
+      "source": "/mac/skills",
+      "destination": "/platforms/mac/skills"
+    },
+    {
+      "source": "/mac/voice-overlay",
+      "destination": "/platforms/mac/voice-overlay"
+    },
+    {
+      "source": "/mac/voicewake",
+      "destination": "/platforms/mac/voicewake"
+    },
+    {
+      "source": "/mac/webchat",
+      "destination": "/platforms/mac/webchat"
+    },
+    {
+      "source": "/mac/xpc",
+      "destination": "/platforms/mac/xpc"
+    },
+    {
+      "source": "/macos",
+      "destination": "/platforms/macos"
+    },
+    {
+      "source": "/model-failover",
+      "destination": "/concepts/model-failover"
+    },
+    {
+      "source": "/models",
+      "destination": "/concepts/models"
+    },
+    {
+      "source": "/multi-agent",
+      "destination": "/concepts/multi-agent"
+    },
+    {
+      "source": "/nix",
+      "destination": "/install/nix"
+    },
+    {
+      "source": "/onboarding",
+      "destination": "/start/onboarding"
+    },
+    {
+      "source": "/onboarding-config-protocol",
+      "destination": "/experiments/onboarding-config-protocol"
+    },
+    {
+      "source": "/pairing",
+      "destination": "/start/pairing"
+    },
+    {
+      "source": "/plans/cron-add-hardening",
+      "destination": "/experiments/plans/cron-add-hardening"
+    },
+    {
+      "source": "/plans/group-policy-hardening",
+      "destination": "/experiments/plans/group-policy-hardening"
+    },
+    {
+      "source": "/poll",
+      "destination": "/automation/poll"
+    },
+    {
+      "source": "/presence",
+      "destination": "/concepts/presence"
+    },
+    {
+      "source": "/proposals/model-config",
+      "destination": "/experiments/proposals/model-config"
+    },
+    {
+      "source": "/provider-routing",
+      "destination": "/concepts/provider-routing"
+    },
+    {
+      "source": "/queue",
+      "destination": "/concepts/queue"
+    },
+    {
+      "source": "/remote",
+      "destination": "/gateway/remote"
+    },
+    {
+      "source": "/remote-gateway-readme",
+      "destination": "/gateway/remote-gateway-readme"
+    },
+    {
+      "source": "/research/memory",
+      "destination": "/experiments/research/memory"
+    },
+    {
+      "source": "/rpc",
+      "destination": "/reference/rpc"
+    },
+    {
+      "source": "/security",
+      "destination": "/gateway/security"
+    },
+    {
+      "source": "/session",
+      "destination": "/concepts/session"
+    },
+    {
+      "source": "/session-tool",
+      "destination": "/concepts/session-tool"
+    },
+    {
+      "source": "/sessions",
+      "destination": "/concepts/sessions"
+    },
+    {
+      "source": "/setup",
+      "destination": "/start/setup"
+    },
+    {
+      "source": "/showcase",
+      "destination": "/start/showcase"
+    },
+    {
+      "source": "/signal",
+      "destination": "/providers/signal"
+    },
+    {
+      "source": "/skills",
+      "destination": "/tools/skills"
+    },
+    {
+      "source": "/skills-config",
+      "destination": "/tools/skills-config"
+    },
+    {
+      "source": "/slack",
+      "destination": "/providers/slack"
+    },
+    {
+      "source": "/slash-commands",
+      "destination": "/tools/slash-commands"
+    },
+    {
+      "source": "/subagents",
+      "destination": "/tools/subagents"
+    },
+    {
+      "source": "/tailscale",
+      "destination": "/gateway/tailscale"
+    },
+    {
+      "source": "/talk",
+      "destination": "/nodes/talk"
+    },
+    {
+      "source": "/telegram",
+      "destination": "/providers/telegram"
+    },
+    {
+      "source": "/templates/AGENTS",
+      "destination": "/reference/templates/AGENTS"
+    },
+    {
+      "source": "/templates/BOOTSTRAP",
+      "destination": "/reference/templates/BOOTSTRAP"
+    },
+    {
+      "source": "/templates/HEARTBEAT",
+      "destination": "/reference/templates/HEARTBEAT"
+    },
+    {
+      "source": "/templates/IDENTITY",
+      "destination": "/reference/templates/IDENTITY"
+    },
+    {
+      "source": "/templates/SOUL",
+      "destination": "/reference/templates/SOUL"
+    },
+    {
+      "source": "/templates/TOOLS",
+      "destination": "/reference/templates/TOOLS"
+    },
+    {
+      "source": "/templates/USER",
+      "destination": "/reference/templates/USER"
+    },
+    {
+      "source": "/test",
+      "destination": "/reference/test"
+    },
+    {
+      "source": "/thinking",
+      "destination": "/tools/thinking"
+    },
+    {
+      "source": "/timezone",
+      "destination": "/concepts/timezone"
+    },
+    {
+      "source": "/troubleshooting",
+      "destination": "/gateway/troubleshooting"
+    },
+    {
+      "source": "/tui",
+      "destination": "/web/tui"
+    },
+    {
+      "source": "/typebox",
+      "destination": "/concepts/typebox"
+    },
+    {
+      "source": "/updating",
+      "destination": "/install/updating"
+    },
+    {
+      "source": "/voicewake",
+      "destination": "/nodes/voicewake"
+    },
+    {
+      "source": "/webchat",
+      "destination": "/web/webchat"
+    },
+    {
+      "source": "/webhook",
+      "destination": "/automation/webhook"
+    },
+    {
+      "source": "/whatsapp",
+      "destination": "/providers/whatsapp"
+    },
+    {
+      "source": "/windows",
+      "destination": "/platforms/windows"
+    },
+    {
+      "source": "/wizard",
+      "destination": "/start/wizard"
+    }
+  ],
  "navigation": {
    "groups": [
      {
        "group": "Start Here",
        "pages": [
-          "getting-started",
-          "wizard",
          "index",
-          "setup",
-          "pairing",
-          "faq",
-          "clawd",
-          "showcase",
-          "hubs",
-          "onboarding"
+          "start/getting-started",
+          "start/wizard",
+          "start/setup",
+          "start/pairing",
+          "start/faq",
+          "start/clawd",
+          "start/showcase",
+          "start/hubs",
+          "start/onboarding",
+          "start/lore"
        ]
      },
      {
-        "group": "Install Options",
+        "group": "Install & Updates",
        "pages": [
-          "nix",
-          "docker"
+          "install/updating",
+          "install/nix",
+          "install/docker",
+          "install/bun"
        ]
      },
      {
        "group": "Core Concepts",
        "pages": [
-          "architecture",
-          "agent",
-          "session",
-          "rpc",
-          "queue",
-          "tools"
+          "concepts/architecture",
+          "concepts/agent",
+          "concepts/agent-loop",
+          "concepts/agent-workspace",
+          "concepts/multi-agent",
+          "concepts/session",
+          "concepts/sessions",
+          "concepts/session-tool",
+          "concepts/presence",
+          "concepts/provider-routing",
+          "concepts/groups",
+          "concepts/group-messages",
+          "concepts/queue",
+          "concepts/models",
+          "concepts/model-failover",
+          "concepts/timezone",
+          "concepts/typebox"
        ]
      },
      {
-        "group": "Gateway & Providers",
+        "group": "Gateway & Ops",
        "pages": [
          "gateway",
          "gateway/pairing",
-          "whatsapp",
-          "telegram",
-          "discord",
-          "imessage",
-          "webhook",
-          "gmail-pubsub"
+          "gateway/gateway-lock",
+          "gateway/configuration",
+          "gateway/background-process",
+          "gateway/health",
+          "gateway/heartbeat",
+          "gateway/doctor",
+          "gateway/logging",
+          "gateway/security",
+          "gateway/troubleshooting",
+          "gateway/remote",
+          "gateway/remote-gateway-readme",
+          "gateway/discovery",
+          "gateway/bonjour",
+          "gateway/tailscale"
+        ]
+      },
+      {
+        "group": "Web & Interfaces",
+        "pages": [
+          "web",
+          "web/control-ui",
+          "web/dashboard",
+          "web/webchat",
+          "web/tui"
+        ]
+      },
+      {
+        "group": "Providers",
+        "pages": [
+          "providers/whatsapp",
+          "providers/telegram",
+          "providers/grammy",
+          "providers/discord",
+          "providers/slack",
+          "providers/signal",
+          "providers/imessage",
+          "providers/location"
+        ]
+      },
+      {
+        "group": "Automation & Hooks",
+        "pages": [
+          "automation/webhook",
+          "automation/gmail-pubsub",
+          "automation/cron-jobs",
+          "automation/poll"
+        ]
+      },
+      {
+        "group": "Tools & Skills",
+        "pages": [
+          "tools",
+          "tools/bash",
+          "tools/elevated",
+          "tools/browser",
+          "tools/browser-linux-troubleshooting",
+          "tools/slash-commands",
+          "tools/thinking",
+          "tools/agent-send",
+          "tools/subagents",
+          "tools/skills",
+          "tools/skills-config",
+          "tools/clawdhub"
+        ]
+      },
+      {
+        "group": "Nodes & Media",
+        "pages": [
+          "nodes",
+          "nodes/camera",
+          "nodes/images",
+          "nodes/audio",
+          "nodes/location-command",
+          "nodes/voicewake",
+          "nodes/talk"
        ]
      },
      {
        "group": "Platforms",
        "pages": [
-          "mac/dev-setup",
-          "mac/menu-bar",
-          "mac/voicewake",
-          "macos",
-          "ios",
-          "android",
-          "webchat",
-          "web"
+          "platforms/macos",
+          "platforms/mac/dev-setup",
+          "platforms/mac/menu-bar",
+          "platforms/mac/voicewake",
+          "platforms/mac/voice-overlay",
+          "platforms/mac/webchat",
+          "platforms/mac/canvas",
+          "platforms/mac/child-process",
+          "platforms/mac/health",
+          "platforms/mac/icon",
+          "platforms/mac/logging",
+          "platforms/mac/permissions",
+          "platforms/mac/remote",
+          "platforms/mac/signing",
+          "platforms/mac/release",
+          "platforms/mac/bun",
+          "platforms/mac/xpc",
+          "platforms/mac/skills",
+          "platforms/mac/peekaboo",
+          "platforms/ios",
+          "platforms/android",
+          "platforms/windows",
+          "platforms/linux"
        ]
      },
      {
-        "group": "Operations",
+        "group": "Reference & Templates",
        "pages": [
-          "doctor",
-          "troubleshooting",
-          "logging",
-          "security",
-          "health",
-          "background-process",
-          "gateway-lock",
-          "remote"
+          "reference/rpc",
+          "reference/device-models",
+          "reference/test",
+          "reference/RELEASING",
+          "reference/AGENTS.default",
+          "reference/templates/AGENTS",
+          "reference/templates/BOOTSTRAP",
+          "reference/templates/HEARTBEAT",
+          "reference/templates/IDENTITY",
+          "reference/templates/SOUL",
+          "reference/templates/TOOLS",
+          "reference/templates/USER"
+        ]
+      },
+      {
+        "group": "Experiments & Proposals",
+        "pages": [
+          "experiments/onboarding-config-protocol",
+          "experiments/plans/cron-add-hardening",
+          "experiments/plans/group-policy-hardening",
+          "experiments/proposals/model-config",
+          "experiments/research/memory"
        ]
      }
    ]
@@ -43,7 +43,7 @@ Recent gateway logs show repeated `cron.add` failures with invalid parameters (m
 - [x] Fix UI CronStatus type to match gateway (`jobs` instead of `jobCount`).
 - [x] Update cron UI provider select to include Discord/Slack/Signal/iMessage.
 - [x] Update macOS CronJobEditor provider picker + enum to include Slack/Signal/iMessage.
- [x] Document cron compatibility normalization policy in [`docs/cron.md`](https://docs.clawd.bot/cron).
+- [x] Document cron compatibility normalization policy in [`docs/cron-jobs.md`](/automation/cron-jobs).

 ### Phase 2 — Input normalization + tooling hardening
 - [x] Add shared cron input normalization helpers (`normalizeCronJobCreate`/`normalizeCronJobPatch`).
@@ -69,8 +69,8 @@ Follow-up hardening work ensures Telegram allowlists behave consistently across
 ### Phase 3: Documentation Updates

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

 **Changes**:
 - Document `tg:` alias and case-insensitive prefixes for Telegram allowlists.
@@ -90,8 +90,8 @@ Follow-up hardening work ensures Telegram allowlists behave consistently across
 |------|-------------|-------------|
 | [`src/telegram/bot.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/telegram/bot.ts) | Fix | Trim allowlist values; strip `telegram:` / `tg:` prefixes case-insensitively |
 | [`src/telegram/bot.test.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/telegram/bot.test.ts) | Test | Add DM + group allowlist coverage for `TG:` prefix + whitespace |
-| [`docs/groups.md`](https://docs.clawd.bot/groups) | Docs | Mention `tg:` alias + case-insensitive prefixes |
-| [`docs/telegram.md`](https://docs.clawd.bot/telegram) | Docs | Mention `tg:` alias + case-insensitive prefixes |
+| [`docs/groups.md`](/concepts/groups) | Docs | Mention `tg:` alias + case-insensitive prefixes |
+| [`docs/telegram.md`](/providers/telegram) | Docs | Mention `tg:` alias + case-insensitive prefixes |

 ---

@@ -155,5 +155,5 @@ Bonjour/DNS-SD often escapes bytes in service instance names as decimal `\\DDD`

 ## Related docs

- Discovery policy and transport selection: [`docs/discovery.md`](https://docs.clawd.bot/discovery)
- Node pairing + approvals: [`docs/gateway/pairing.md`](https://docs.clawd.bot/gateway/pairing)
+- Discovery policy and transport selection: [`docs/discovery.md`](/gateway/discovery)
+- Node pairing + approvals: [`docs/gateway/pairing.md`](/gateway/pairing)
@@ -119,11 +119,11 @@ rotation order used for failover.
 {
  auth: {
    profiles: {
-      "anthropic:default": { provider: "anthropic", mode: "oauth", email: "me@example.com" },
+      "anthropic:me@example.com": { provider: "anthropic", mode: "oauth", email: "me@example.com" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" }
    },
    order: {
-      anthropic: ["anthropic:default", "anthropic:work"]
+      anthropic: ["anthropic:me@example.com", "anthropic:work"]
    }
  }
 }
@@ -195,6 +195,8 @@ Controls how WhatsApp direct chats (DMs) are handled:
 - `"open"`: allow all inbound DMs (**requires** `whatsapp.allowFrom` to include `"*"`)
 - `"disabled"`: ignore all inbound DMs

+Pairing codes expire after 1 hour; the bot only sends a pairing code when a new request is created.
+
 Pairing approvals:
 - `clawdbot pairing list --provider whatsapp`
 - `clawdbot pairing approve --provider whatsapp <code>`
@@ -464,6 +466,7 @@ Set `telegram.enabled: false` to disable automatic startup.
    dmPolicy: "pairing",                 // pairing | allowlist | open | disabled
    allowFrom: ["tg:123456789"],         // optional; "open" requires ["*"]
    groups: { "*": { requireMention: true } },
+    actions: { reactions: true },        // tool action gates (false disables)
    mediaMaxMb: 5,
    proxy: "socks5://localhost:9050",
    webhookUrl: "https://example.com/telegram-webhook",
@@ -629,7 +632,7 @@ Default: `~/clawd`.
 ```

 If `agent.sandbox` is enabled, non-main sessions can override this with their
-own per-session workspaces under `agent.sandbox.workspaceRoot`.
+own per-scope workspaces under `agent.sandbox.workspaceRoot`.

 ### `agent.skipBootstrap`

@@ -754,6 +757,10 @@ If you configure the same alias name (case-insensitive) yourself, your value win
      target: "last"
    },
    maxConcurrent: 3,
+    subagents: {
+      maxConcurrent: 1,
+      archiveAfterMinutes: 60
+    },
    bash: {
      backgroundMs: 10000,
      timeoutSec: 1800,
@@ -791,17 +798,22 @@ Z.AI models are available as `zai/<model>` (e.g. `zai/glm-4.7`) and require
 - `model`: optional override model for heartbeat runs (`provider/model`).
 - `target`: optional delivery provider (`last`, `whatsapp`, `telegram`, `discord`, `slack`, `signal`, `imessage`, `none`). Default: `last`.
 - `to`: optional recipient override (provider-specific id, e.g. E.164 for WhatsApp, chat id for Telegram).
- `prompt`: optional override for the heartbeat body (default: `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`).
+- `prompt`: optional override for the heartbeat body (default: `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`). Overrides are sent verbatim; include a `Read HEARTBEAT.md if exists` line if you still want the file read.
 - `ackMaxChars`: max chars allowed after `HEARTBEAT_OK` before delivery (default: 30).

-Heartbeats run full agent turns. Shorter intervals burn more tokens; adjust `every`
-and/or `model` accordingly.
+Heartbeats run full agent turns. Shorter intervals burn more tokens; be mindful
+of `every`, keep `HEARTBEAT.md` tiny, and/or choose a cheaper `model`.

 `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.subagents` configures sub-agent defaults:
+- `maxConcurrent`: max concurrent sub-agent runs (default 1)
+- `archiveAfterMinutes`: auto-archive sub-agent sessions after N minutes (default 60; set `0` to disable)
+- `tools.allow` / `tools.deny`: per-subagent tool allow/deny policy (deny wins)
+
 `agent.tools` configures a global tool allow/deny policy (deny wins).
 This is applied even when the Docker sandbox is **off**.

@@ -847,24 +859,30 @@ per session key at a time). Default: 1.

 ### `agent.sandbox`

-Optional per-session **Docker sandboxing** for the embedded agent. Intended for
-non-main sessions so they cannot access your host system.
+Optional **Docker sandboxing** for the embedded agent. Intended for non-main
+sessions so they cannot access your host system.

 Defaults (if enabled):
- one container per session
+- scope: `"agent"` (one container + workspace per agent)
 - Debian bookworm-slim based image
- workspace per session under `~/.clawdbot/sandboxes`
+- workspace per agent under `~/.clawdbot/sandboxes`
 - auto-prune: idle > 24h OR age > 7d
 - tools: allow only `bash`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn` (deny wins)
 - optional sandboxed browser (Chromium + CDP, noVNC observer)
 - hardening knobs: `network`, `user`, `pidsLimit`, `memory`, `cpus`, `ulimits`, `seccompProfile`, `apparmorProfile`

+Warning: `scope: "shared"` means a shared container and shared workspace. No
+cross-session isolation. Use `scope: "session"` for per-session isolation.
+
+Legacy: `perSession` is still supported (`true` → `scope: "session"`,
+`false` → `scope: "shared"`).
+
 ```json5
 {
  agent: {
    sandbox: {
      mode: "non-main", // off | non-main | all
-      perSession: true,
+      scope: "agent", // session | agent | shared (agent is default)
      workspaceRoot: "~/.clawdbot/sandboxes",
      docker: {
        image: "clawdbot-sandbox:bookworm-slim",
@@ -978,6 +996,31 @@ Select the model via `agent.model.primary` (provider/model).
 }
 ```

+### Z.AI (GLM-4.7) — provider alias support
+
+Z.AI models are available via the built-in `zai` provider. Set `ZAI_API_KEY`
+in your environment and reference the model by provider/model.
+
+```json5
+{
+  agent: {
+    model: "zai/glm-4.7",
+    allowedModels: ["zai/glm-4.7"]
+  }
+}
+```
+
+Notes:
+- `z.ai/*` and `z-ai/*` are accepted aliases and normalize to `zai/*`.
+- If `ZAI_API_KEY` is missing, requests to `zai/*` will fail with an auth error at runtime.
+- Example error: `No API key found for provider "zai".`
+- Z.AI’s general API endpoint is `https://api.z.ai/api/paas/v4`. The GLM Coding
+  Plan uses the dedicated Coding endpoint `https://api.z.ai/api/coding/paas/v4`.
+  The built-in `zai` provider uses the Coding endpoint. If you need the general
+  endpoint, define a custom provider in `models.providers` with the base URL
+  override (see the custom providers section above).
+- Use a fake placeholder in docs/configs; never commit real API keys.
+
 ### Local models (LM Studio) — recommended setup

 Best current local setup (what we’re running): **MiniMax M2.1** on a beefy Mac Studio
@@ -1191,6 +1234,12 @@ Control UI base path:
 - Examples: `"/ui"`, `"/clawdbot"`, `"/apps/clawdbot"`.
 - Default: root (`/`) (unchanged).

+Related docs:
+- [Control UI](/web/control-ui)
+- [Web overview](/web)
+- [Tailscale](/gateway/tailscale)
+- [Remote access](/gateway/remote)
+
 Notes:
 - `clawdbot gateway` refuses to start unless `gateway.mode` is set to `local` (or you pass the override flag).
 - `gateway.port` controls the single multiplexed port used for WebSocket + HTTP (control UI, hooks, A2UI).
@@ -1283,7 +1332,7 @@ Convenience flags (CLI):
 - `clawdbot --dev …` → uses `~/.clawdbot-dev` + shifts ports from base `19001`
 - `clawdbot --profile <name> …` → uses `~/.clawdbot-<name>` (port via config/env/flags)

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

 Example:
 ```bash
@@ -1479,7 +1528,7 @@ Template placeholders are expanded in `routing.transcribeAudio.command` (and any

 ## Cron (Gateway scheduler)

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

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

 ---

-*Next: [Agent Runtime](https://docs.clawd.bot/agent)* 🦞
+*Next: [Agent Runtime](/concepts/agent)* 🦞
@@ -42,7 +42,7 @@ Target direction:
 - The **gateway** advertises its bridge via Bonjour.
 - Clients browse and show a “pick a gateway” list, then store the chosen endpoint.

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

 #### Current implementation

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

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

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

 ## Transport selection (client policy)

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

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

- Pairing requests are created/approved/rejected in the gateway (see [`docs/gateway/pairing.md`](https://docs.clawd.bot/gateway/pairing)).
+- Pairing requests are created/approved/rejected in the gateway (see [`docs/gateway/pairing.md`](/gateway/pairing)).
 - The bridge enforces:
  - auth (token / keypair)
  - scopes/ACLs (bridge is not a raw proxy to every gateway method)
@@ -14,7 +14,7 @@ read_when:
 - Detects deprecated config keys and offers to migrate them.
 - 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.
+- Detects legacy Clawdis services (launchd/systemd; legacy schtasks for native Windows) and offers to migrate them.
 - On Linux, checks if systemd user lingering is enabled and can enable it (required to keep the Gateway alive after logout).
 - Migrates legacy on-disk state layouts (sessions, agentDir, provider auth dirs) into the current per-agent/per-account structure.

@@ -48,6 +48,7 @@ Doctor can migrate older on-disk layouts into the current structure:
  - to `~/.clawdbot/credentials/whatsapp/<accountId>/...` (default account id: `default`)

 These migrations are best-effort and idempotent; doctor will emit warnings when it leaves any legacy folders behind as backups.
+The Gateway/CLI also auto-migrates the legacy sessions + agent dir on startup so history/auth/models land in the per-agent path without a manual doctor run. WhatsApp auth is intentionally only migrated via `clawdbot doctor`.

 ## Usage

@@ -55,6 +56,20 @@ These migrations are best-effort and idempotent; doctor will emit warnings when
 clawdbot doctor
 ```

+### Headless / automation
+
+```bash
+clawdbot doctor --yes
+```
+
+Accept defaults without prompting (including restart/service/sandbox repair steps when applicable).
+
+```bash
+clawdbot doctor --non-interactive
+```
+
+Run without prompts and only apply safe migrations (config normalization + on-disk state moves). Skips restart/service/sandbox actions that require human confirmation.
+
 If you want to review changes before writing, open the config file first:

 ```bash
@@ -62,6 +77,6 @@ cat ~/.clawdbot/clawdbot.json
 ```

 ## Legacy service migrations
-Doctor checks for older Clawdis gateway services (launchd/systemd/schtasks).
+Doctor checks for older Clawdis gateway services (launchd/systemd/schtasks). WSL2 installs use systemd.
 If found, it offers to remove them and install the Clawdbot service using the current gateway port.
 Remote mode skips the install step, and Nix mode only reports what it finds.
@@ -8,17 +8,28 @@ read_when:
 Heartbeat runs periodic agent turns in the **main session** so the model can
 surface anything that needs attention without spamming the user.

+## Defaults
+- Interval: `30m` (set `agent.heartbeat.every` to change, `0m` disables).
+- Prompt body (configurable via `agent.heartbeat.prompt`):
+  `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`
+- Heartbeat prompt text is sent **verbatim** as the user message. Clawdbot does
+  not append extra body text. The system prompt includes a Heartbeats section
+  and the run is flagged as a heartbeat internally.
+
 ## Prompt contract
- Heartbeat body defaults to: `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.` (configurable via `agent.heartbeat.prompt`).
 - If nothing needs attention, the model should reply `HEARTBEAT_OK`.
 - During heartbeat runs, Clawdbot treats `HEARTBEAT_OK` as an ack when it appears at
  the **start or end** of the reply. Clawdbot strips the token and discards the
  reply if the remaining content is **≤ `ackMaxChars`** (default: 30).
 - If `HEARTBEAT_OK` is in the **middle** of a reply, it is not treated specially.
 - For alerts, do **not** include `HEARTBEAT_OK`; return only the alert text.
- Heartbeat prompt text is sent **verbatim** as the user message. Clawdbot does
-  not append extra body text. The system prompt includes a Heartbeats section
-  and the run is flagged as a heartbeat internally.
+
+## Prompt overrides
+- Overriding `agent.heartbeat.prompt` **replaces** the default body. Nothing is
+  merged for you.
+- If you still want `HEARTBEAT.md` instructions, keep a line like
+  `Read HEARTBEAT.md if exists` in your custom prompt.
+- `HEARTBEAT_OK` handling stays the same; changing the prompt won’t break acks.

 ### Stray `HEARTBEAT_OK` outside heartbeats
 If the model accidentally includes `HEARTBEAT_OK` at the start or end of a
@@ -63,9 +74,9 @@ and final replies:
 - `ackMaxChars`: max chars allowed after `HEARTBEAT_OK` before delivery (default: 30).

 ## Cost awareness
-Heartbeats run full agent turns. Shorter intervals burn more tokens. If you
-don’t need frequent checks, increase `every`, pick a cheaper `model`, or set
-`target: "none"` to keep results internal.
+Heartbeats run full agent turns. Shorter intervals burn more tokens. Be
+intentional about `every`, keep `HEARTBEAT.md` tiny, and consider a cheaper
+`model` or `target: "none"` if you only want internal state updates.

 ## HEARTBEAT.md (optional)
 If a `HEARTBEAT.md` file exists in the workspace, the default prompt tells the
@@ -85,6 +96,8 @@ bloat.
 - Handle mundane tasks (triage inboxes, summarize queues, refresh notes).
 - Nudge on open loops or reminders.
 - Background monitoring (health checks, status polling, low-priority alerts).
+- Scheduled routines (use [Cron jobs](/automation/cron-jobs) when you
+  need exact schedules or isolated runs).

 ## Wake hook
 - The gateway exposes a heartbeat wake hook so cron/jobs/webhooks can request an
@@ -14,11 +14,11 @@ Last updated: 2025-12-09

 ## How to run (local)
 ```bash
-pnpm clawdbot gateway --port 18789
+clawdbot gateway --port 18789
 # for full debug/trace logs in stdio:
-pnpm clawdbot gateway --port 18789 --verbose
+clawdbot gateway --port 18789 --verbose
 # if the port is busy, terminate listeners then start:
-pnpm clawdbot gateway --force
+clawdbot gateway --force
 # dev loop (auto-reload on TS changes):
 pnpm gateway:watch
 ```
@@ -111,7 +111,7 @@ CLAWDBOT_CONFIG_PATH=~/.clawdbot/b.json CLAWDBOT_STATE_DIR=~/.clawdbot-b clawdbo
 - `node.invoke` — invoke a command on a node (e.g. `canvas.*`, `camera.*`).
 - `node.pair.*` — pairing lifecycle (`request`, `list`, `approve`, `reject`, `verify`).

-See also: [`docs/presence.md`](https://docs.clawd.bot/presence) for how presence is produced/deduped and why `instanceId` matters.
+See also: [`docs/presence.md`](/concepts/presence) for how presence is produced/deduped and why `instanceId` matters.

 ## Events
 - `agent` — streamed tool/output events from the agent run (seq-tagged).
@@ -184,7 +184,7 @@ 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`).
+Onboarding runs this on Linux/WSL2 (may prompt for sudo; writes `/var/lib/systemd/linger`).
 Then enable the service:
 ```
 systemctl --user enable --now clawdbot-gateway.service
@@ -199,9 +199,9 @@ 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).
+## Windows (WSL2)
+
+Windows installs should use **WSL2** and follow the Linux systemd section above.

 ## Operational checks
 - Liveness: open WS and send `req:connect` → expect `res` with `payload.type="hello-ok"` (with snapshot).
@@ -219,7 +219,7 @@ sudo systemctl enable --now clawdbot-gateway.service
 - `clawdbot gateway send --to <num> --message "hi" [--media-url ...]` — send via Gateway (idempotent).
 - `clawdbot gateway agent --message "hi" [--to ...]` — run an agent turn (waits for final by default).
 - `clawdbot gateway call <method> --params '{"k":"v"}'` — raw method invoker for debugging.
- `clawdbot gateway stop|restart` — stop/restart the supervised gateway service (launchd/systemd/schtasks).
+- `clawdbot gateway stop|restart` — stop/restart the supervised gateway service (launchd/systemd).
 - Gateway helper subcommands assume a running gateway on `--url`; they no longer auto-spawn one.

 ## Migration guidance
@@ -8,7 +8,7 @@ read_when:
 This repo supports “remote over SSH” by keeping a single Gateway (the master) running on a host (e.g., your Mac Studio) and connecting clients to it.

 - For **operators (you / the macOS app)**: SSH tunneling is the universal fallback.
- For **nodes (iOS/Android and future devices)**: prefer the Gateway **Bridge** when on the same LAN/tailnet (see [`docs/discovery.md`](https://docs.clawd.bot/discovery)).
+- For **nodes (iOS/Android and future devices)**: prefer the Gateway **Bridge** when on the same LAN/tailnet (see [`docs/discovery.md`](/gateway/discovery)).

 ## The core idea

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

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

-Runbook: [`docs/mac/remote.md`](https://docs.clawd.bot/mac/remote).
+Runbook: [`docs/mac/remote.md`](/platforms/mac/remote).
@@ -38,7 +38,7 @@ Clawdbot’s stance:

 All current DM-capable providers support a DM policy (`dmPolicy` or `*.dm.policy`) that gates inbound DMs **before** the message is processed:

- `pairing` (default): unknown senders receive a short pairing code and the bot ignores their message until approved.
+- `pairing` (default): unknown senders receive a short pairing code and the bot ignores their message until approved. Codes expire after 1 hour; repeated DMs won’t resend a code until a new request is created.
 - `allowlist`: unknown senders are blocked (no pairing handshake).
 - `open`: allow anyone to DM (public). **Requires** the provider allowlist to include `"*"` (explicit opt-in).
 - `disabled`: ignore inbound DMs entirely.
@@ -50,7 +50,7 @@ clawdbot pairing list --provider <provider>
 clawdbot pairing approve --provider <provider> <code>
 ```

-Details + files on disk: https://docs.clawd.bot/pairing
+Details + files on disk: [Pairing](/start/pairing)

 ## Allowlists (DM + groups) — terminology

@@ -64,7 +64,7 @@ Clawdbot has two separate “who can trigger me?” layers:
    - `groupPolicy="allowlist"` + `groupAllowFrom`: restrict who can trigger the bot *inside* a group session (WhatsApp/Telegram/Signal/iMessage).
    - `discord.guilds` / `slack.channels`: per-surface allowlists + mention defaults.

-Details: https://docs.clawd.bot/configuration and https://docs.clawd.bot/groups
+Details: [Configuration](/gateway/configuration) and [Groups](/concepts/groups)

 ## Prompt injection (what it is, why it matters)

@@ -75,6 +75,7 @@ Even with strong system prompts, **prompt injection is not solved**. What helps
 - Prefer mention gating in groups; avoid “always-on” bots in public rooms.
 - Treat links and pasted instructions as hostile by default.
 - Run sensitive tool execution in a sandbox; keep secrets out of the agent’s reachable filesystem.
+- **Model choice matters:** we recommend Anthropic Opus 4.5 because it’s quite good at recognizing prompt injections (see [“A step forward on safety”](https://www.anthropic.com/news/claude-opus-4-5)). Using weaker models increases risk.

 ## Lessons Learned (The Hard Way)

@@ -138,8 +139,12 @@ We're considering a `readOnlyMode` flag that prevents the AI from:

 Two complementary approaches:

- **Run the full Gateway in Docker** (container boundary): https://docs.clawd.bot/docker
- **Per-session tool sandbox** (`agent.sandbox`, host gateway + Docker-isolated tools): https://docs.clawd.bot/configuration
+- **Run the full Gateway in Docker** (container boundary): [Docker](/install/docker)
+- **Tool sandbox** (`agent.sandbox`, host gateway + Docker-isolated tools): [Configuration](/gateway/configuration)
+
+Note: to prevent cross-agent access, keep `sandbox.scope` at `"agent"` (default)
+or `"session"` for stricter per-session isolation. `scope: "shared"` uses a
+single container/workspace.

 Important: `agent.elevated` is an explicit escape hatch that runs bash on the host. Keep `agent.elevated.allowFrom` tight and don’t enable it for strangers.

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

-**Full guide:** See [browser-linux-troubleshooting](https://docs.clawd.bot/browser-linux-troubleshooting)
+**Full guide:** See [browser-linux-troubleshooting](/tools/browser-linux-troubleshooting)
@@ -1,150 +0,0 @@
---
-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](https://docs.clawd.bot)
- [Getting Started](https://docs.clawd.bot/getting-started)
- [Onboarding](https://docs.clawd.bot/onboarding)
- [Wizard](https://docs.clawd.bot/wizard)
- [Setup](https://docs.clawd.bot/setup)
- [FAQ](https://docs.clawd.bot/faq)
- [Configuration](https://docs.clawd.bot/configuration)
- [Clawd (personal assistant)](https://docs.clawd.bot/clawd)
- [Lore](https://docs.clawd.bot/lore)
-
-## Installation + distribution
-
- [Docker](https://docs.clawd.bot/docker)
- [Nix](https://docs.clawd.bot/nix)
-
-## Core concepts
-
- [Architecture](https://docs.clawd.bot/architecture)
- [Agent runtime](https://docs.clawd.bot/agent)
- [Agent loop](https://docs.clawd.bot/agent-loop)
- [Multi-agent routing](https://docs.clawd.bot/multi-agent)
- [Sessions](https://docs.clawd.bot/session)
- [Sessions (alias)](https://docs.clawd.bot/sessions)
- [Session tools](https://docs.clawd.bot/session-tool)
- [Queue](https://docs.clawd.bot/queue)
- [Slash commands](https://docs.clawd.bot/slash-commands)
- [RPC adapters](https://docs.clawd.bot/rpc)
- [TypeBox schemas](https://docs.clawd.bot/typebox)
- [Presence](https://docs.clawd.bot/presence)
- [Discovery + transports](https://docs.clawd.bot/discovery)
- [Bonjour](https://docs.clawd.bot/bonjour)
- [Provider routing](https://docs.clawd.bot/provider-routing)
- [Groups](https://docs.clawd.bot/groups)
- [Group messages](https://docs.clawd.bot/group-messages)
-
-## Providers + ingress
-
- [WhatsApp](https://docs.clawd.bot/whatsapp)
- [Telegram](https://docs.clawd.bot/telegram)
- [Telegram (grammY notes)](https://docs.clawd.bot/grammy)
- [Slack](https://docs.clawd.bot/slack)
- [Discord](https://docs.clawd.bot/discord)
- [Signal](https://docs.clawd.bot/signal)
- [iMessage](https://docs.clawd.bot/imessage)
- [WebChat](https://docs.clawd.bot/webchat)
- [Webhooks](https://docs.clawd.bot/webhook)
- [Gmail Pub/Sub](https://docs.clawd.bot/gmail-pubsub)
-
-## Gateway + operations
-
- [Gateway runbook](https://docs.clawd.bot/gateway)
- [Gateway pairing](https://docs.clawd.bot/gateway/pairing)
- [Gateway lock](https://docs.clawd.bot/gateway-lock)
- [Background process](https://docs.clawd.bot/background-process)
- [Health](https://docs.clawd.bot/health)
- [Heartbeat](https://docs.clawd.bot/heartbeat)
- [Doctor](https://docs.clawd.bot/doctor)
- [Logging](https://docs.clawd.bot/logging)
- [Dashboard](https://docs.clawd.bot/dashboard)
- [Control UI](https://docs.clawd.bot/control-ui)
- [Remote access](https://docs.clawd.bot/remote)
- [Remote gateway README](https://docs.clawd.bot/remote-gateway-readme)
- [Tailscale](https://docs.clawd.bot/tailscale)
- [Security](https://docs.clawd.bot/security)
- [Troubleshooting](https://docs.clawd.bot/troubleshooting)
-
-## Tools + automation
-
- [Tools surface](https://docs.clawd.bot/tools)
- [Bash tool](https://docs.clawd.bot/bash)
- [Elevated mode](https://docs.clawd.bot/elevated)
- [Cron + wakeups](https://docs.clawd.bot/cron)
- [Thinking + verbose](https://docs.clawd.bot/thinking)
- [Models](https://docs.clawd.bot/models)
- [Agent send CLI](https://docs.clawd.bot/agent-send)
- [Terminal UI](https://docs.clawd.bot/tui)
- [Browser control](https://docs.clawd.bot/browser)
- [Browser (Linux troubleshooting)](https://docs.clawd.bot/browser-linux-troubleshooting)
-
-## Nodes, media, voice
-
- [Nodes overview](https://docs.clawd.bot/nodes)
- [Camera](https://docs.clawd.bot/camera)
- [Images](https://docs.clawd.bot/images)
- [Audio](https://docs.clawd.bot/audio)
- [Location command](https://docs.clawd.bot/location-command)
- [Voice wake](https://docs.clawd.bot/voicewake)
- [Talk mode](https://docs.clawd.bot/talk)
-
-## Platforms
-
- [macOS app overview](https://docs.clawd.bot/macos)
- [macOS dev setup](https://docs.clawd.bot/mac/dev-setup)
- [macOS menu bar](https://docs.clawd.bot/mac/menu-bar)
- [macOS voice wake](https://docs.clawd.bot/mac/voicewake)
- [macOS voice overlay](https://docs.clawd.bot/mac/voice-overlay)
- [macOS WebChat](https://docs.clawd.bot/mac/webchat)
- [macOS Canvas](https://docs.clawd.bot/mac/canvas)
- [macOS child process](https://docs.clawd.bot/mac/child-process)
- [macOS health](https://docs.clawd.bot/mac/health)
- [macOS icon](https://docs.clawd.bot/mac/icon)
- [macOS logging](https://docs.clawd.bot/mac/logging)
- [macOS permissions](https://docs.clawd.bot/mac/permissions)
- [macOS remote](https://docs.clawd.bot/mac/remote)
- [macOS signing](https://docs.clawd.bot/mac/signing)
- [macOS release](https://docs.clawd.bot/mac/release)
- [macOS bun gateway](https://docs.clawd.bot/mac/bun)
- [macOS XPC](https://docs.clawd.bot/mac/xpc)
- [macOS skills](https://docs.clawd.bot/mac/skills)
- [macOS Peekaboo plan](https://docs.clawd.bot/mac/peekaboo)
- [iOS node](https://docs.clawd.bot/ios)
- [Android node](https://docs.clawd.bot/android)
- [Windows app](https://docs.clawd.bot/windows)
- [Linux app](https://docs.clawd.bot/linux)
- [Web surfaces](https://docs.clawd.bot/web)
-
-## Workspace + templates
-
- [Skills](https://docs.clawd.bot/skills)
- [Skills config](https://docs.clawd.bot/skills-config)
- [Default AGENTS](https://docs.clawd.bot/AGENTS.default)
- [Templates: AGENTS](https://docs.clawd.bot/templates/AGENTS)
- [Templates: BOOTSTRAP](https://docs.clawd.bot/templates/BOOTSTRAP)
- [Templates: IDENTITY](https://docs.clawd.bot/templates/IDENTITY)
- [Templates: SOUL](https://docs.clawd.bot/templates/SOUL)
- [Templates: TOOLS](https://docs.clawd.bot/templates/TOOLS)
- [Templates: USER](https://docs.clawd.bot/templates/USER)
-
-## Experiments + proposals
-
- [Onboarding config protocol](https://docs.clawd.bot/onboarding-config-protocol)
- [Research: memory](https://docs.clawd.bot/research/memory)
- [Proposal: model config](https://docs.clawd.bot/proposals/model-config)
-
-## Testing + release
-
- [Testing](https://docs.clawd.bot/test)
- [Release checklist](https://docs.clawd.bot/RELEASING)
- [Device models](https://docs.clawd.bot/device-models)
@@ -1,94 +0,0 @@
---
-summary: "iMessage support via imsg (JSON-RPC over stdio), setup, and chat_id routing"
-read_when:
-  - Setting up iMessage support
-  - Debugging iMessage send/receive
---
-# iMessage (imsg)
-
-Status: external CLI integration. No daemon.
-
-## Model
- Clawdbot spawns `imsg rpc` as a child process.
- JSON-RPC runs over stdin/stdout (one JSON object per line).
- Gateway owns the process; no TCP port needed.
-
-## Multi-account (Apple IDs)
-
-iMessage “multi-account” in one Gateway process is not currently supported in a meaningful way:
- Messages accounts are owned by the signed-in macOS user session.
- `imsg` reads the local Messages DB and sends via that user’s configured services.
- There isn’t a robust “pick AppleID X as the sender” switch we can depend on.
-
-### Practical approach: multiple gateways on multiple Macs/users
-
-If you need two iMessage identities:
- Run one Gateway on each macOS user/machine that’s signed into the desired Apple ID.
- Connect to the desired Gateway remotely (Tailscale preferred; SSH tunnel is the universal fallback).
-
-See:
- `docs/remote.md` (SSH tunnel to `127.0.0.1:18789`)
- `docs/discovery.md` (bridge vs SSH transport model)
-
-### Could we do “iMessage over SSH” from a single Gateway?
-
-Maybe, but it’s a new design:
- Outbound could theoretically pipe `imsg rpc` over SSH (stdio bridge).
- Inbound still needs a remote watcher (DB polling / event stream) and a transport back to the main Gateway.
-
-That’s closer to “remote provider instances” (or “multi-gateway aggregation”) than a small config tweak.
-
-## Requirements
- macOS with Messages signed in.
- Full Disk Access for Clawdbot + the `imsg` binary (Messages DB access).
- Automation permission for Messages when sending.
-
-## Config
-
-```json5
-{
-  imessage: {
-    enabled: true,
-    cliPath: "imsg",
-    dbPath: "~/Library/Messages/chat.db",
-    dmPolicy: "pairing", // pairing | allowlist | open | disabled
-    allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
-    groupPolicy: "open",
-    groupAllowFrom: ["chat_id:123"],
-    includeAttachments: false,
-    mediaMaxMb: 16,
-    service: "auto",
-    region: "US"
-  }
-}
-```
-
-Notes:
- `allowFrom` accepts handles (phone/email) or `chat_id:<id>` entries.
- Default: `imessage.dmPolicy="pairing"` — unknown DM senders get a pairing code (approve via `clawdbot pairing approve --provider imessage <code>`). `"open"` requires `allowFrom=["*"]`.
- `groupPolicy` controls group handling (`open|disabled|allowlist`).
- `groupAllowFrom` accepts the same entries as `allowFrom`.
- `service` defaults to `auto` (use `imessage` or `sms` to pin).
- `region` is only used for SMS targeting.
-
-## Addressing / targets
-
-Prefer `chat_id` for stable routing:
- `chat_id:123` (preferred)
- `chat_guid:...` (fallback)
- `chat_identifier:...` (fallback)
- direct handles: `imessage:+1555` / `sms:+1555` / `user@example.com`
-
-List chats:
-```
-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` (patterns are required to detect mentions on iMessage). When `imessage.groups` is set, it also acts as a group allowlist; include `"*"` to allow all groups.
- Replies go back to the same `chat_id` (group or direct).
-
-## Troubleshooting
- `clawdbot gateway call providers.status --params '{"probe":true}'`
- Verify `imsg` is on PATH and has access to Messages DB.
@@ -20,7 +20,7 @@ read_when:
  <a href="https://github.com/clawdbot/clawdbot">GitHub</a> ·
  <a href="https://github.com/clawdbot/clawdbot/releases">Releases</a> ·
  <a href="https://docs.clawd.bot">Docs</a> ·
-  <a href="https://docs.clawd.bot/clawd">Clawd setup</a>
+  <a href="https://docs.clawd.bot/start/clawd">Clawd setup</a>
 </p>

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

 ## Start here

- **New install from zero:** https://docs.clawd.bot/getting-started
- **Guided setup (recommended):** https://docs.clawd.bot/wizard (`clawdbot onboard`)
+- **New install from zero:** https://docs.clawd.bot/start/getting-started
+- **Guided setup (recommended):** https://docs.clawd.bot/start/wizard (`clawdbot onboard`)
+- **Open the dashboard (local Gateway):** http://127.0.0.1:18789/ (or http://localhost:18789/)
+
+If the Gateway is running on the same computer, that link opens the browser Control UI
+immediately. If it fails, start the Gateway first: `clawdbot gateway`.
+
+## Dashboard (browser Control UI)
+
+The dashboard is the browser Control UI for chat, config, nodes, sessions, and more.
+Local default: http://127.0.0.1:18789/
+Remote access: https://docs.clawd.bot/web and https://docs.clawd.bot/gateway/tailscale

 ## How it works

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

 ## Features (high level)

@@ -135,45 +145,47 @@ Example:
 ## Docs

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

 ## The name

@@ -7,12 +7,12 @@ read_when:

 # Bun

-Goal: run this repo with **Bun** (preferred) without losing pnpm patch behavior.
+Goal: run this repo with **Bun** (optional) without losing pnpm patch behavior.

 ## Status

- Bun is the preferred local runtime for running TypeScript directly (`bun run …`, `bun --watch …`).
- `pnpm` is still fully supported (and used by some docs tooling).
+- Bun is an optional local runtime for running TypeScript directly (`bun run …`, `bun --watch …`).
+- `pnpm` is the default for builds and remains fully supported (and used by some docs tooling).
 - Bun cannot use `pnpm-lock.yaml` and will ignore it.

 ## Install
@@ -70,22 +70,26 @@ pnpm test:docker:qr
 - Gateway bind defaults to `lan` for container use.
 - The gateway container is the source of truth for sessions (`~/.clawdbot/agents/<agentId>/sessions/`).

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

 ### What it does

 When `agent.sandbox` is enabled, **non-main sessions** run tools inside a Docker
 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`
+- scope: `"agent"` by default (one container + workspace per agent)
+- scope: `"session"` for per-session isolation
+- per-scope 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

+Warning: `scope: "shared"` disables cross-session isolation. All sessions share
+one container and one workspace.
+
 ### Default behavior

 - Image: `clawdbot-sandbox:bookworm-slim`
- One container per session
- Workspace per session under `~/.clawdbot/sandboxes`
+- One container per agent
+- Workspace per agent under `~/.clawdbot/sandboxes`
 - Auto-prune: idle > 24h OR age > 7d
 - Network: `none` by default (explicitly opt-in if you need egress)
 - Default allow: `bash`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`
@@ -98,7 +102,7 @@ container. The gateway stays on your host, but the tool execution is isolated:
  agent: {
    sandbox: {
      mode: "non-main", // off | non-main | all
-      perSession: true,
+      scope: "agent", // session | agent | shared (agent is default)
      workspaceRoot: "~/.clawdbot/sandboxes",
      docker: {
        image: "clawdbot-sandbox:bookworm-slim",
@@ -91,5 +91,5 @@ packaging and Nix builds (which do not rely on a full Xcode toolchain).
 ## Related

 - [nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) — full setup guide
- [Wizard](https://docs.clawd.bot/wizard) — non-Nix CLI setup
- [Docker](https://docs.clawd.bot/docker) — containerized setup
+- [Wizard](/start/wizard) — non-Nix CLI setup
+- [Docker](/install/docker) — containerized setup
@@ -12,7 +12,7 @@ Clawdbot is moving fast (pre “1.0”). Treat updates like shipping infra: upda
 ## Before you update

 - Know how you installed: **npm** (global) vs **from source** (git clone).
- Know how your Gateway is running: **foreground terminal** vs **supervised service** (launchd/systemd/Scheduled Task).
+- Know how your Gateway is running: **foreground terminal** vs **supervised service** (launchd/systemd).
 - Snapshot your tailoring:
  - Config: `~/.clawdbot/clawdbot.json`
  - Credentials: `~/.clawdbot/credentials/`
@@ -68,10 +68,10 @@ Typical things it does:
 - Migrate deprecated config keys / legacy config file locations.
 - Audit DM policies and warn on risky “open” settings.
 - Check Gateway health and can offer to restart.
- Detect and migrate older gateway services (launchd/systemd/schtasks) to current Clawdbot services.
+- Detect and migrate older gateway services (launchd/systemd; legacy schtasks) to current Clawdbot services.
 - On Linux, ensure systemd user lingering (so the Gateway survives logout).

-Details: https://docs.clawd.bot/doctor
+Details: [Doctor](/gateway/doctor)

 ## Start / stop / restart the Gateway

@@ -86,9 +86,9 @@ clawdbot gateway --port 18789
 If you’re supervised:
 - macOS launchd (app-bundled LaunchAgent): `launchctl kickstart -k gui/$UID/com.clawdbot.gateway`
 - Linux systemd user service: `systemctl --user restart clawdbot-gateway.service`
- Windows: restart the `Clawdbot Gateway` Scheduled Task (Task Scheduler)
+- Windows (WSL2): `systemctl --user restart clawdbot-gateway.service`

-Runbook + exact service labels: https://docs.clawd.bot/gateway
+Runbook + exact service labels: [Gateway runbook](/gateway)

 ## Rollback / pinning (when something breaks)

@@ -121,7 +121,7 @@ Then reinstall deps + restart:
 ```bash
 pnpm install
 pnpm build
-pnpm clawdbot gateway restart
+clawdbot gateway restart
 ```

 If you want to go back to latest later:
@@ -134,5 +134,5 @@ git pull
 ## If you’re stuck

 - Run `clawdbot doctor` again and read the output carefully (it often tells you the fix).
- Check: https://docs.clawd.bot/troubleshooting
+- Check: [Troubleshooting](/gateway/troubleshooting)
 - Ask in Discord: https://discord.gg/clawd
@@ -1,93 +0,0 @@
---
-summary: "Plan for models CLI: scan, list, aliases, fallbacks, status"
-read_when:
-  - Adding or modifying models CLI (models list/set/scan/aliases/fallbacks)
-  - Changing model fallback behavior or selection UX
-  - Updating model scan probes (tools/images)
---
-# Models CLI plan
-
-See [`docs/model-failover.md`](https://docs.clawd.bot/model-failover) for how auth profiles rotate (OAuth vs API keys), cooldowns, and how that interacts with model fallbacks.
-
-Goal: give clear model visibility + control (configured vs available), plus scan tooling
-that prefers tool-call + image-capable models and maintains ordered fallbacks.
-
-## Command tree (draft)
-
- `clawdbot models list`
-  - default: configured models only
-  - flags: `--all` (full catalog), `--local`, `--provider <name>`, `--json`, `--plain`
- `clawdbot models status`
-  - show default model + aliases + fallbacks + configured models
- `clawdbot models set <modelOrAlias>`
-  - 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.models.*.alias`
- `clawdbot models fallbacks list|add|remove|clear`
-  - 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
-
- `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 from auth profiles or `OPENROUTER_API_KEY`
- Optional filters: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates`
- Probe controls: `--timeout`, `--concurrency`
-
-Probes (direct pi-ai complete)
- Tool-call probe (required):
-  - Provide a dummy tool, verify tool call emitted.
- Image probe (preferred):
-  - Prompt includes 1x1 PNG; success if no "unsupported image" error.
-
-Scoring/selection
- 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)
- Multiselect list with per-model stats:
-  - model id, tool ok, image ok, median latency, context, inferred params.
- Pre-select top N (default 6).
- Non-TTY: auto-select; require `--yes`/`--no-input` to apply.
-
-Output
- 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.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.
- See [`docs/model-failover.md`](https://docs.clawd.bot/model-failover) for auth profile rotation, cooldowns, and timeout handling.
-
-## Tests
-
- Unit: scan selection ordering + probe classification.
- CLI: list/aliases/fallbacks add/remove + scan writes config.
- Status: shows last used model + fallbacks.
-
-## Docs
-
- Update [`docs/configuration.md`](https://docs.clawd.bot/configuration) with `agent.models` + `agent.model` + `agent.imageModel`.
- Keep this doc current when CLI surface or scan logic changes.
@@ -14,7 +14,7 @@ macOS can also run in **node mode**: the menubar app connects to the Gateway’s

 ## Pairing + status

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

 Quick CLI:

@@ -28,7 +28,7 @@ The Gateway WebSocket stays loopback-only (`ws://127.0.0.1:18789`). Android talk
 Bridge is enabled by default (disable via `CLAWDBOT_BRIDGE_ENABLED=0`).

 ```bash
-pnpm clawdbot gateway --port 18789 --verbose
+clawdbot gateway --port 18789 --verbose
 ```

 Confirm in logs you see something like:
@@ -47,7 +47,7 @@ From the gateway machine:
 dns-sd -B _clawdbot-bridge._tcp local.
 ```

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

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

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

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

 ### 3) Connect from Android

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

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

 ### 5) Verify the node is connected

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

-See [`docs/camera.md`](https://docs.clawd.bot/camera) for parameters and CLI helpers.
+See [`docs/camera.md`](/nodes/camera) for parameters and CLI helpers.
@@ -34,7 +34,7 @@ The Gateway WebSocket stays loopback-only (`ws://127.0.0.1:18789`). The iOS node
 Bridge is enabled by default (disable via `CLAWDBOT_BRIDGE_ENABLED=0`).

 ```bash
-pnpm clawdbot gateway --port 18789 --verbose
+clawdbot gateway --port 18789 --verbose
 ```

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

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

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

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

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

 ### 3) Connect from the iOS node app

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

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

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

 ### 5) Verify the node is connected

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

 - **iOS in background:** all `canvas.*` commands fail fast with `NODE_BACKGROUND_UNAVAILABLE` (bring the iOS node app to foreground).
 - **Return to default scaffold:** `canvas.navigate` with `{"url":""}` or `{"url":"/"}` returns to the built-in scaffold page.
- **mDNS blocked:** some networks block multicast; use a different LAN or plan a tailnet-capable bridge (see [`docs/discovery.md`](https://docs.clawd.bot/discovery)).
+- **mDNS blocked:** some networks block multicast; use a different LAN or plan a tailnet-capable bridge (see [`docs/discovery.md`](/gateway/discovery)).
 - **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.
@@ -195,8 +195,8 @@ Non-goals (v1):

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

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

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

 CLI (headless approvals):
 - `clawdbot nodes pending`
@@ -366,7 +366,7 @@ open Clawdbot.xcodeproj

 ## Related docs

- [`docs/gateway.md`](https://docs.clawd.bot/gateway) (gateway runbook)
- [`docs/gateway/pairing.md`](https://docs.clawd.bot/gateway/pairing) (approval + storage)
- [`docs/bonjour.md`](https://docs.clawd.bot/bonjour) (discovery debugging)
- [`docs/discovery.md`](https://docs.clawd.bot/discovery) (LAN vs tailnet vs SSH)
+- [`docs/gateway.md`](/gateway) (gateway runbook)
+- [`docs/gateway/pairing.md`](/gateway/pairing) (approval + storage)
+- [`docs/bonjour.md`](/gateway/bonjour) (discovery debugging)
+- [`docs/discovery.md`](/gateway/discovery) (LAN vs tailnet vs SSH)
@@ -10,7 +10,7 @@ read_when:

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

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

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

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

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

 ## Agent commands (current)

@@ -25,4 +25,4 @@ How to see whether the WhatsApp Web/Baileys bridge is healthy from the menu bar
 - Cache the last good snapshot and the last error separately to avoid flicker; show the timestamp of each.

 ## When in doubt
- You can still use the CLI flow in [`docs/health.md`](https://docs.clawd.bot/health) (`clawdbot status`, `clawdbot status --deep`, `clawdbot health --json`) and tail `/tmp/clawdbot/clawdbot-*.log` for `web-heartbeat` / `web-reconnect`.
+- You can still use the CLI flow in [`docs/health.md`](/gateway/health) (`clawdbot status`, `clawdbot status --deep`, `clawdbot health --json`) and tail `/tmp/clawdbot/clawdbot-*.log` for `web-heartbeat` / `web-reconnect`.
@@ -9,7 +9,7 @@ This app is usually built from [`scripts/package-mac-app.sh`](https://github.com

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

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

 ## Build metadata for About

@@ -3,7 +3,7 @@ summary: "Voice overlay lifecycle when wake-word and push-to-talk overlap"
 read_when:
  - Adjusting voice overlay behavior
 ---
-## Voice Overlay Lifecycle (macOS)
+# Voice Overlay Lifecycle (macOS)

 Audience: macOS app contributors. Goal: keep the voice overlay predictable when wake-word and push-to-talk overlap.

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

 ### Mach/XPC (future direction)
 - Still optional for internal app services, but **not required** for automation now that node.invoke is the surface.
@@ -13,7 +13,7 @@ Author: steipete · Status: draft spec · Date: 2025-12-20
  - Shows native notifications for Clawdbot/clawdbot events.
  - Owns TCC prompts (Notifications, Accessibility, Screen Recording, Automation/AppleScript, Microphone, Speech Recognition).
  - Runs (or connects to) the **Gateway** and exposes itself as a **node** so agents can reach macOS‑only features.
-  - Hosts **PeekabooBridge** for UI automation (consumed by `peekaboo`; see [`docs/mac/peekaboo.md`](https://docs.clawd.bot/mac/peekaboo)).
+  - Hosts **PeekabooBridge** for UI automation (consumed by `peekaboo`; see [`docs/mac/peekaboo.md`](/platforms/mac/peekaboo)).
  - Installs a single CLI (`clawdbot`) by symlinking the bundled binary.

 ## High-level design
@@ -0,0 +1,73 @@
+---
+summary: "Windows (WSL2) setup + companion app status"
+read_when:
+  - Installing Clawdbot on Windows
+  - Looking for Windows companion app status
+  - Planning platform coverage or contributions
+---
+# Windows (WSL2)
+
+Clawdbot runs on Windows **via WSL2** (Ubuntu recommended). WSL2 is **strongly
+recommended**; native Windows installs are untested and more problematic. Use
+WSL2 and follow the Linux flow inside it.
+
+## How to install this correctly
+
+Start here (official WSL2 guide): https://learn.microsoft.com/windows/wsl/install
+
+### 1) Install WSL2 + Ubuntu
+
+Open PowerShell (Admin):
+
+```powershell
+wsl --install
+# Or pick a distro explicitly:
+wsl --list --online
+wsl --install -d Ubuntu-24.04
+```
+
+Reboot if Windows asks.
+
+### 2) Enable systemd (required for daemon install)
+
+In your WSL terminal:
+
+```bash
+sudo tee /etc/wsl.conf >/dev/null <<'EOF'
+[boot]
+systemd=true
+EOF
+```
+
+Then from PowerShell:
+
+```powershell
+wsl --shutdown
+```
+
+Re-open Ubuntu, then verify:
+
+```bash
+systemctl --user status
+```
+
+### 3) Install Clawdbot (inside WSL)
+
+Follow the Linux Getting Started flow inside WSL:
+
+```bash
+git clone https://github.com/clawdbot/clawdbot.git
+cd clawdbot
+pnpm install
+pnpm ui:install
+pnpm ui:build
+pnpm build
+pnpm clawdbot onboard
+```
+
+Full guide: [Getting Started](/start/getting-started)
+
+## Windows companion app
+
+We do not have a Windows companion app yet. It is planned, and we would love
+contributions to make it happen.
@@ -23,16 +23,17 @@ Status: ready for DM and guild text channels via the official Discord bot gatewa
   - If you prefer env vars, still add `discord: { enabled: true }` to `~/.clawdbot/clawdbot.json` and set `DISCORD_BOT_TOKEN`.
 5. Direct chats: use `user:<id>` (or a `<@id>` mention) when delivering; all turns land in the shared `main` session.
 6. Guild channels: use `channel:<channelId>` for delivery. Mentions are required by default and can be set per guild or per channel.
-7. Direct chats: secure by default via `discord.dm.policy` (default: `"pairing"`). Unknown senders get a pairing code; approve via `clawdbot pairing approve --provider discord <code>`.
+7. Direct chats: secure by default via `discord.dm.policy` (default: `"pairing"`). Unknown senders get a pairing code (expires after 1 hour); approve via `clawdbot pairing approve --provider discord <code>`.
   - To keep old “open to anyone” behavior: set `discord.dm.policy="open"` and `discord.dm.allowFrom=["*"]`.
   - To hard-allowlist: set `discord.dm.policy="allowlist"` and list senders in `discord.dm.allowFrom`.
   - To ignore all DMs: set `discord.dm.enabled=false` or `discord.dm.policy="disabled"`.
 8. Group DMs are ignored by default; enable via `discord.dm.groupEnabled` and optionally restrict by `discord.dm.groupChannels`.
 9. Optional guild rules: set `discord.guilds` keyed by guild id (preferred) or slug, with per-channel rules.
 10. Optional native commands: set `commands.native: true` to register native commands in Discord; set `commands.native: false` to clear previously registered native commands. Text commands are controlled by `commands.text` and must be sent as standalone `/...` messages. Use `commands.useAccessGroups: false` to bypass access-group checks for commands.
-    - Full command list + config: https://docs.clawd.bot/slash-commands
+    - Full command list + config: [Slash commands](/tools/slash-commands)
 11. Optional guild context history: set `discord.historyLimit` (default 20) to include the last N guild messages as context when replying to a mention. Set `0` to disable.
 12. Reactions: the agent can trigger reactions via the `discord` tool (gated by `discord.actions.*`).
+    - Reaction removal semantics: see [/tools/reactions](/tools/reactions).
    - The `discord` tool is only exposed when the current provider is Discord.
 13. Native commands use isolated session keys (`discord:slash:${userId}`) rather than the shared `main` session.

@@ -0,0 +1,93 @@
+---
+summary: "iMessage support via imsg (JSON-RPC over stdio), setup, and chat_id routing"
+read_when:
+  - Setting up iMessage support
+  - Debugging iMessage send/receive
+---
+# iMessage (imsg)
+
+Updated: 2026-01-06
+
+Status: external CLI integration. Gateway spawns `imsg rpc` (JSON-RPC over stdio).
+
+## What it is
+- iMessage provider backed by `imsg` on macOS.
+- Deterministic routing: replies always go back to iMessage.
+- DMs share the agent's main session; groups are isolated (`imessage:group:<chat_id>`).
+
+## Requirements
+- macOS with Messages signed in.
+- Full Disk Access for Clawdbot + `imsg` (Messages DB access).
+- Automation permission when sending.
+
+## Setup (fast path)
+1) Ensure Messages is signed in on this Mac.
+2) Configure iMessage and start the gateway.
+
+Example:
+```json5
+{
+  imessage: {
+    enabled: true,
+    cliPath: "imsg",
+    dmPolicy: "pairing",
+    allowFrom: ["+15555550123"]
+  }
+}
+```
+
+## Access control (DMs + groups)
+DMs:
+- Default: `imessage.dmPolicy = "pairing"`.
+- Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
+- Approve via:
+  - `clawdbot pairing list --provider imessage`
+  - `clawdbot pairing approve --provider imessage <CODE>`
+- Pairing is the default token exchange for iMessage DMs. Details: [Pairing](/start/pairing)
+
+Groups:
+- `imessage.groupPolicy = open | allowlist | disabled`.
+- `imessage.groupAllowFrom` controls who can trigger in groups when `allowlist` is set.
+- Mention gating uses `routing.groupChat.mentionPatterns` (iMessage has no native mention metadata).
+
+## How it works (behavior)
+- `imsg` streams message events; the gateway normalizes them into the shared provider envelope.
+- Replies always route back to the same chat id or handle.
+
+## Media + limits
+- Optional attachment ingestion via `imessage.includeAttachments`.
+- Media cap via `imessage.mediaMaxMb`.
+
+## Addressing / delivery targets
+Prefer `chat_id` for stable routing:
+- `chat_id:123` (preferred)
+- `chat_guid:...`
+- `chat_identifier:...`
+- direct handles: `imessage:+1555` / `sms:+1555` / `user@example.com`
+
+List chats:
+```
+imsg chats --limit 20
+```
+
+## Configuration reference (iMessage)
+Full configuration: [Configuration](/gateway/configuration)
+
+Provider options:
+- `imessage.enabled`: enable/disable provider startup.
+- `imessage.cliPath`: path to `imsg`.
+- `imessage.dbPath`: Messages DB path.
+- `imessage.service`: `imessage | sms | auto`.
+- `imessage.region`: SMS region.
+- `imessage.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).
+- `imessage.allowFrom`: DM allowlist (handles or `chat_id:*`). `open` requires `"*"`.
+- `imessage.groupPolicy`: `open | allowlist | disabled` (default: open).
+- `imessage.groupAllowFrom`: group sender allowlist.
+- `imessage.groups`: per-group defaults + allowlist (use `"*"` for global defaults).
+- `imessage.includeAttachments`: ingest attachments into context.
+- `imessage.mediaMaxMb`: inbound/outbound media cap (MB).
+- `imessage.textChunkLimit`: outbound chunk size (chars).
+
+Related global options:
+- `routing.groupChat.mentionPatterns`.
+- `messages.responsePrefix`.
@@ -0,0 +1,93 @@
+---
+summary: "Signal support via signal-cli (JSON-RPC + SSE), setup, and number model"
+read_when:
+  - Setting up Signal support
+  - Debugging Signal send/receive
+---
+# Signal (signal-cli)
+
+Updated: 2026-01-06
+
+Status: external CLI integration. Gateway talks to `signal-cli` over HTTP JSON-RPC + SSE.
+
+## What it is
+- Signal provider via `signal-cli` (not embedded libsignal).
+- Deterministic routing: replies always go back to Signal.
+- DMs share the agent's main session; groups are isolated (`signal:group:<groupId>`).
+
+## The number model (important)
+- The gateway connects to a **Signal device** (the `signal-cli` account).
+- If you run the bot on **your personal Signal account**, it will ignore your own messages (loop protection).
+- For "I text the bot and it replies," use a **separate bot number**.
+
+## Setup (fast path)
+1) Install `signal-cli` (Java required).
+2) Link a bot account:
+   - `signal-cli link -n "Clawdbot"` then scan the QR in Signal.
+3) Configure Signal and start the gateway.
+
+Example:
+```json5
+{
+  signal: {
+    enabled: true,
+    account: "+15551234567",
+    cliPath: "signal-cli",
+    dmPolicy: "pairing",
+    allowFrom: ["+15557654321"]
+  }
+}
+```
+
+## Access control (DMs + groups)
+DMs:
+- Default: `signal.dmPolicy = "pairing"`.
+- Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
+- Approve via:
+  - `clawdbot pairing list --provider signal`
+  - `clawdbot pairing approve --provider signal <CODE>`
+- Pairing is the default token exchange for Signal DMs. Details: [Pairing](/start/pairing)
+
+Groups:
+- `signal.groupPolicy = open | allowlist | disabled`.
+- `signal.groupAllowFrom` controls who can trigger in groups when `allowlist` is set.
+
+## How it works (behavior)
+- `signal-cli` runs as a daemon; the gateway reads events via SSE.
+- Inbound messages are normalized into the shared provider envelope.
+- Replies always route back to the same number or group.
+
+## Media + limits
+- Attachments supported (base64 fetched from `signal-cli`).
+- Default cap: `signal.mediaMaxMb`.
+- Use `signal.ignoreAttachments` to skip downloading media.
+
+## Delivery targets (CLI/cron)
+- DMs: `signal:+15551234567` (or plain E.164).
+- Groups: `signal:group:<groupId>`.
+- Usernames: `username:<name>` (if supported by your Signal account).
+
+## Configuration reference (Signal)
+Full configuration: [Configuration](/gateway/configuration)
+
+Provider options:
+- `signal.enabled`: enable/disable provider startup.
+- `signal.account`: E.164 for the bot account.
+- `signal.cliPath`: path to `signal-cli`.
+- `signal.httpUrl`: full daemon URL (overrides host/port).
+- `signal.httpHost`, `signal.httpPort`: daemon bind (default 127.0.0.1:8080).
+- `signal.autoStart`: auto-spawn daemon (default true if `httpUrl` unset).
+- `signal.receiveMode`: `on-start | manual`.
+- `signal.ignoreAttachments`: skip attachment downloads.
+- `signal.ignoreStories`: ignore stories from the daemon.
+- `signal.sendReadReceipts`: forward read receipts.
+- `signal.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).
+- `signal.allowFrom`: DM allowlist (E.164). `open` requires `"*"`.
+- `signal.groupPolicy`: `open | allowlist | disabled` (default: open).
+- `signal.groupAllowFrom`: group sender allowlist.
+- `signal.textChunkLimit`: outbound chunk size (chars).
+- `signal.mediaMaxMb`: inbound/outbound media cap (MB).
+
+Related global options:
+- `routing.groupChat.mentionPatterns` (Signal does not support native mentions).
+- `messages.responsePrefix`.
@@ -192,10 +192,10 @@ Ack reactions are controlled globally via `messages.ackReaction` +
 - Channels map to `slack:channel:<channelId>` sessions.
 - Slash commands use `slack:slash:<userId>` sessions.
 - Native command registration is controlled by `commands.native`; text commands require standalone `/...` messages and can be disabled with `commands.text: false`. Slack slash commands are managed in the Slack app and are not removed automatically. Use `commands.useAccessGroups: false` to bypass access-group checks for commands.
- Full command list + config: https://docs.clawd.bot/slash-commands
+- Full command list + config: [Slash commands](/tools/slash-commands)

 ## DM security (pairing)
- Default: `slack.dm.policy="pairing"` — unknown DM senders get a pairing code.
+- Default: `slack.dm.policy="pairing"` — unknown DM senders get a pairing code (expires after 1 hour).
 - Approve via: `clawdbot pairing approve --provider slack <code>`.
 - To allow anyone: set `slack.dm.policy="open"` and `slack.dm.allowFrom=["*"]`.

@@ -222,4 +222,5 @@ Slack tool actions can be gated with `slack.actions.*`:
 ## Notes
 - 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`).
+- For the Slack tool, reaction removal semantics are in [/tools/reactions](/tools/reactions).
 - Attachments are downloaded to the media store when permitted and under the size limit.
@@ -0,0 +1,105 @@
+---
+summary: "Telegram bot support status, capabilities, and configuration"
+read_when:
+  - Working on Telegram features or webhooks
+---
+# Telegram (Bot API)
+
+Updated: 2026-01-06
+
+Status: production-ready for bot DMs + groups via grammY. Long-polling by default; webhook optional.
+
+## What it is
+- A Telegram Bot API provider owned by the Gateway.
+- Deterministic routing: replies go back to Telegram; the model never chooses providers.
+- DMs share the agent's main session; groups stay isolated (`telegram:group:<chatId>`).
+
+## Setup (fast path)
+1) Create a bot with @BotFather and copy the token.
+2) Configure the token (env or config). Example:
+
+```json5
+{
+  telegram: {
+    enabled: true,
+    botToken: "123:abc",
+    dmPolicy: "pairing",
+    groups: { "*": { requireMention: true } }
+  }
+}
+```
+
+3) Start the gateway. Telegram starts when a `telegram` config section exists and a token is resolved.
+4) DM access defaults to pairing. Approve the code when the bot is first contacted.
+5) For groups: add the bot, disable privacy mode (or make it admin), then set `telegram.groups` to control mention gating + allowlists.
+
+## How it works (behavior)
+- Inbound messages are normalized into the shared provider envelope with reply context and media placeholders.
+- Group replies require a mention by default (native @mention or `routing.groupChat.mentionPatterns`).
+- Replies always route back to the same Telegram chat.
+
+## Topics (forum supergroups)
+Telegram forum topics include a `message_thread_id` per message. Clawdbot:
+- Appends `:topic:<threadId>` to the Telegram group session key so each topic is isolated.
+- Sends typing indicators and replies with `message_thread_id` so responses stay in the topic.
+- Exposes `MessageThreadId` + `IsForum` in template context for routing/templating.
+
+## Access control (DMs + groups)
+- Default: `telegram.dmPolicy = "pairing"`. Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
+- Approve via:
+  - `clawdbot pairing list --provider telegram`
+  - `clawdbot pairing approve --provider telegram <CODE>`
+- Pairing is the default token exchange used for Telegram DMs. Details: [Pairing](/start/pairing)
+
+Group gating:
+- `telegram.groupPolicy = open | allowlist | disabled`.
+- `telegram.groups` doubles as a group allowlist when set (include `"*"` to allow all).
+
+## Long-polling vs webhook
+- Default: long-polling (no public URL required).
+- Webhook mode: set `telegram.webhookUrl` (optionally `telegram.webhookSecret` + `telegram.webhookPath`).
+  - The local listener binds to `0.0.0.0:8787` and serves `POST /telegram-webhook` by default.
+  - If your public URL is different, use a reverse proxy and point `telegram.webhookUrl` at the public endpoint.
+
+## Reply threading
+Telegram supports optional threaded replies via tags:
+- `[[reply_to_current]]` -- reply to the triggering message.
+- `[[reply_to:<id>]]` -- reply to a specific message id.
+
+Controlled by `telegram.replyToMode`:
+- `off` (default), `first`, `all`.
+
+## Agent tool (reactions)
+- Tool: `telegram` with `react` action (`chatId`, `messageId`, `emoji`).
+- Reaction removal semantics: see [/tools/reactions](/tools/reactions).
+- Tool gating: `telegram.actions.reactions` (default: enabled).
+
+## Delivery targets (CLI/cron)
+- Use a chat id (`123456789`) or a username (`@name`) as the target.
+- Example: `clawdbot send --provider telegram --to 123456789 "hi"`.
+
+## Configuration reference (Telegram)
+Full configuration: [Configuration](/gateway/configuration)
+
+Provider options:
+- `telegram.enabled`: enable/disable provider startup.
+- `telegram.botToken`: bot token (BotFather).
+- `telegram.tokenFile`: read token from file path.
+- `telegram.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).
+- `telegram.allowFrom`: DM allowlist (ids/usernames). `open` requires `"*"`.
+- `telegram.groupPolicy`: `open | allowlist | disabled` (default: open).
+- `telegram.groupAllowFrom`: group sender allowlist (ids/usernames).
+- `telegram.groups`: per-group defaults + allowlist (use `"*"` for global defaults).
+- `telegram.replyToMode`: `off | first | all`.
+- `telegram.textChunkLimit`: outbound chunk size (chars).
+- `telegram.mediaMaxMb`: inbound/outbound media cap (MB).
+- `telegram.proxy`: proxy URL for Bot API calls (SOCKS/HTTP).
+- `telegram.webhookUrl`: enable webhook mode.
+- `telegram.webhookSecret`: webhook secret (optional).
+- `telegram.webhookPath`: local webhook path (default `/telegram-webhook`).
+- `telegram.actions.reactions`: gate Telegram tool reactions.
+
+Related global options:
+- `routing.groupChat.mentionPatterns` (mention gating patterns).
+- `commands.native`, `commands.text`, `commands.useAccessGroups` (command behavior).
+- `messages.responsePrefix`, `messages.ackReaction`, `messages.ackReactionScope`.
@@ -51,7 +51,7 @@ WhatsApp requires a real mobile number for verification. VoIP and virtual number
 - Status/broadcast chats are ignored.
 - Direct chats use E.164; groups use group JID.
 - **DM policy**: `whatsapp.dmPolicy` controls direct chat access (default: `pairing`).
-  - Pairing: unknown senders get a pairing code (approve via `clawdbot pairing approve --provider whatsapp <code>`).
+  - Pairing: unknown senders get a pairing code (approve via `clawdbot pairing approve --provider whatsapp <code>`; codes expire after 1 hour).
  - Open: requires `whatsapp.allowFrom` to include `"*"`.
  - Self messages are always allowed; “self-chat mode” still requires `whatsapp.allowFrom` to include your own number.
 - **Group policy**: `whatsapp.groupPolicy` controls group handling (`open|disabled|allowlist`).
@@ -94,6 +94,12 @@ WhatsApp requires a real mobile number for verification. VoIP and virtual number
 - WhatsApp Web sends standard messages (no quoted reply threading in the current gateway).
 - Reply tags are ignored on this provider.

+## Agent tool (reactions)
+- Tool: `whatsapp` with `react` action (`chatJid`, `messageId`, `emoji`, optional `remove`).
+- Optional: `participant` (group sender), `fromMe` (reacting to your own message), `accountId` (multi-account).
+- Reaction removal semantics: see [/tools/reactions](/tools/reactions).
+- Tool gating: `whatsapp.actions.reactions` (default: enabled).
+
 ## Outbound send (text + media)
 - Uses active web listener; error if gateway not running.
 - Text chunking: 4k max per message.
@@ -131,6 +137,7 @@ WhatsApp requires a real mobile number for verification. VoIP and virtual number
 - `whatsapp.groupAllowFrom` (group sender allowlist).
 - `whatsapp.groupPolicy` (group policy).
 - `whatsapp.groups` (group allowlist + mention gating defaults; use `"*"` to allow all)
+- `whatsapp.actions.reactions` (gate WhatsApp tool reactions).
 - `routing.groupChat.mentionPatterns`
 - `routing.groupChat.historyLimit`
 - `messages.messagePrefix` (inbound prefix)
@@ -148,7 +155,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/troubleshooting.md`](https://docs.clawd.bot/troubleshooting).
+- Troubleshooting guide: [`docs/troubleshooting.md`](/gateway/troubleshooting).

 ## Tests
 - [`src/web/auto-reply.test.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/web/auto-reply.test.ts) (mention gating, history injection, reply flow)
@@ -19,15 +19,15 @@ mkdir -p ~/clawd
 2) Copy the default workspace templates into the workspace:

 ```bash
-cp docs/templates/AGENTS.md ~/clawd/AGENTS.md
-cp docs/templates/SOUL.md ~/clawd/SOUL.md
-cp docs/templates/TOOLS.md ~/clawd/TOOLS.md
+cp docs/reference/templates/AGENTS.md ~/clawd/AGENTS.md
+cp docs/reference/templates/SOUL.md ~/clawd/SOUL.md
+cp docs/reference/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 ~/clawd/AGENTS.md
+cp docs/reference/AGENTS.default.md ~/clawd/AGENTS.md
 ```

 4) Optional: choose a different workspace by setting `agent.workspace` (supports `~`):
@@ -36,9 +36,9 @@ Use `pnpm` (Node 22+) from the repo root. Keep the working tree clean before tag
 - [ ] Build + sign the macOS app, then zip it for distribution.
 - [ ] Generate the Sparkle appcast (HTML notes via [`scripts/make_appcast.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/make_appcast.sh)) and update `appcast.xml`.
 - [ ] Keep the app zip (and optional dSYM zip) ready to attach to the GitHub release.
- [ ] Follow [`docs/mac/release.md`](https://docs.clawd.bot/mac/release) for the exact commands and required env vars.
+- [ ] Follow [`docs/mac/release.md`](/platforms/mac/release) for the exact commands and required env vars.
  - `APP_BUILD` must be numeric + monotonic (no `-beta`) so Sparkle compares versions correctly.
-  - If notarizing, use the `clawdbot-notary` keychain profile created from App Store Connect API env vars (see [`docs/mac/release.md`](https://docs.clawd.bot/mac/release)).
+  - If notarizing, use the `clawdbot-notary` keychain profile created from App Store Connect API env vars (see [`docs/mac/release.md`](/platforms/mac/release)).

 6) **Publish (npm)**
 - [ ] Confirm git status is clean; commit and push as needed.
@@ -14,7 +14,7 @@ Clawdbot integrates external CLIs via JSON-RPC. Two patterns are used today.
 - Health probe: `/api/v1/check`.
 - Clawdbot owns lifecycle when `signal.autoStart=true`.

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

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

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

 ## Adapter guidelines
 - Gateway owns the process (start/stop tied to provider lifecycle).
Author	SHA1	Message	Date
Peter Steinberger	4fac5a6390	fix(auth): doctor-migrate anthropic oauth profiles	2026-01-07 06:29:43 +00:00
Randy Torres	068ec5fa0a	fix(auth): use anthropic oauth email profile Use Anthropic OAuth profile email as the profile identifier when available. This fixes cases where Anthropic returns an email-based profile id rather than an explicit id field.	2026-01-07 06:19:36 +00:00
Peter Steinberger	86fde78442	chore: sync swift protocol models	2026-01-07 06:14:15 +00:00
Peter Steinberger	50dec39d13	fix: honor sandboxed built-in tools	2026-01-07 06:12:56 +00:00
Peter Steinberger	03928106c7	fix: order reasoning before reply text	2026-01-07 07:05:07 +01:00
Peter Steinberger	75c66acfd8	feat: update subagent announce + archive	2026-01-07 06:53:01 +01:00
Peter Steinberger	1673a221f8	feat: add /reasoning reasoning visibility	2026-01-07 06:17:31 +01:00
Peter Steinberger	cb2a72f8a9	test(routing): add route-reply coverage	2026-01-07 05:07:53 +00:00
Peter Steinberger	3668388912	fix(routing): harden originating reply routing	2026-01-07 05:02:34 +00:00
Josh Lehman	2a2e327cae	style: fix biome formatting	2026-01-07 04:51:33 +00:00
Josh Lehman	5414da9fd4	fix(routing): handle cross-provider messages in collect mode When queued messages come from different providers (Slack + Telegram), process them individually instead of collecting into a single prompt. This ensures each reply routes back to its originating provider. - Add hasCrossProviderItems() to detect multi-provider queues - Skip collect mode when cross-provider detected - Preserve originatingChannel/originatingTo when collecting same-provider	2026-01-07 04:51:33 +00:00
Josh Lehman	2d67ec5bfa	fix(routing): only route to originating channel when cross-provider When OriginatingChannel matches Surface (same provider), use normal dispatcher. Only route via routeReply() when they differ, ensuring cross-provider messages (e.g., Telegram queued while Slack active) get routed back to their origin.	2026-01-07 04:51:33 +00:00
Josh Lehman	9d50ebad7d	feat(routing): route replies to originating channel Implement reply routing based on OriginatingChannel/OriginatingTo fields. This ensures replies go back to the provider where the message originated instead of using the session's lastChannel. Changes: - Add OriginatingChannel/OriginatingTo fields to MsgContext (templating.ts) - Add originatingChannel/originatingTo fields to FollowupRun (queue.ts) - Create route-reply.ts with provider-agnostic router - Update all providers (Telegram, Slack, Discord, Signal, iMessage) to pass originating channel info - Update reply.ts to pass originating channel to followupRun - Update followup-runner.ts to use route-reply for originating channels This addresses the issue where messages from one provider (e.g., Slack) would receive replies on a different provider (e.g., Telegram) because the queue used the last active dispatcher instead of the originating one.	2026-01-07 04:51:33 +00:00
Peter Steinberger	514fcfe77e	fix: harden sub-agent model overrides	2026-01-07 04:48:37 +00:00
Peter Steinberger	12d57da53a	fix: normalize provider aliases in auth order	2026-01-07 05:43:32 +01:00
mneves75	8187baab18	test: format models list alias coverage	2026-01-07 05:31:01 +01:00
mneves75	3550dc294d	fix: normalize z.ai provider ids in auth profiles	2026-01-07 05:31:01 +01:00
mneves75	13c1ce1f05	Docs: update Z.AI configuration	2026-01-07 05:30:46 +01:00
mneves75	8954f7719c	Test: cover z.ai normalization	2026-01-07 05:30:06 +01:00
mneves75	0ddfbf5534	Feat: normalize z.ai provider ids	2026-01-07 05:30:06 +01:00
Peter Steinberger	388796253a	feat(skills): add session-logs skill for searching conversation history Adds jq-based queries for: - Listing sessions by date/size - Searching user/assistant messages - Extracting costs per session and daily totals - Tool usage breakdowns - Cross-session keyword search	2026-01-07 04:13:30 +00:00
Peter Steinberger	42ae2341aa	fix: harden pairing flow	2026-01-07 05:06:04 +01:00
Peter Steinberger	6ffece68b0	fix(doctor): add headless flags + auto-migrate sessions	2026-01-07 04:43:24 +01:00
Peter Steinberger	9c9ae5aa54	fix(imessage): harden abort shutdown	2026-01-07 03:41:23 +00:00
Anton Sotkov	08fc0b3809	fix: imsg unhandled promises	2026-01-07 03:41:23 +00:00
Peter Steinberger	8ef0609f8e	refactor: share reaction schemas and notes	2026-01-07 04:24:11 +01:00
Peter Steinberger	654e14df31	Merge PR #353	2026-01-07 04:18:19 +01:00
Peter Steinberger	073b16a3a0	fix: clean up reaction tooling	2026-01-07 04:16:39 +01:00
Peter Steinberger	3afef2d504	feat: unify provider reaction tools	2026-01-07 04:16:39 +01:00
Sash Zats	551a8d5683	Add WhatsApp reactions support Summary: Test Plan:	2026-01-07 04:16:39 +01:00
Peter Steinberger	aa87d6cee8	refactor(relay): add --smoke entrypoint	2026-01-07 03:12:30 +00:00
Peter Steinberger	59cc15f3cc	fix(relay): guard QR smoke mode	2026-01-07 02:42:55 +00:00
Peter Steinberger	ff102e2afa	Merge PR #358	2026-01-07 02:42:53 +00:00
Peter Steinberger	aa635af6d0	refactor: unify outbound result envelopes	2026-01-07 02:36:05 +00:00
DB Hurley	9d820a628f	fix(relay): implement CLAWDBOT_SMOKE_QR handler for packaging	2026-01-06 21:32:04 -05:00
Peter Steinberger	4bf5f37a44	refactor: streamline outbound payload handling	2026-01-07 02:30:42 +00:00
Peter Steinberger	3fedd0d1d5	fix(outbound): guard optional delivery fields	2026-01-07 02:19:42 +00:00
Peter Steinberger	59502552ae	fix(telegram): import native reply helper	2026-01-07 02:19:42 +00:00
Peter Steinberger	d7bc5b58fc	refactor(telegram): polish topic threading	2026-01-07 02:19:42 +00:00
Peter Steinberger Daniel Griesser Nacho Iacovino Randy Ventures	80112433a5	fix(telegram): support forum topics Co-authored-by: Daniel Griesser <HazAT@users.noreply.github.com> Co-authored-by: Nacho Iacovino <nachoiacovino@users.noreply.github.com> Co-authored-by: Randy Ventures <RandyVentures@users.noreply.github.com>	2026-01-07 02:19:42 +00:00
Peter Steinberger	023a124312	test: cover gmail tailscale error formatting	2026-01-07 03:16:52 +01:00
Sash Zats	8a07093624	Add WhatsApp reactions support Summary: Test Plan:	2026-01-06 21:11:52 -05:00
Peter Steinberger	2986447935	fix: improve gmail tailscale errors	2026-01-07 03:10:35 +01:00
Peter Steinberger	ba317588c0	docs: note community nickname for MiniMax	2026-01-07 03:02:22 +01:00
Peter Steinberger	321db99cc6	docs: add CLI reference and model links	2026-01-07 02:52:41 +01:00
Peter Steinberger	467d4e17fe	feat: add sandbox scope default	2026-01-07 02:52:41 +01:00
Peter Steinberger	4d4e4de915	docs: add changelog for PR #348	2026-01-07 02:52:41 +01:00
Peter Steinberger	15b7560a9b	refactor: reuse gateway output helpers	2026-01-07 01:43:02 +00:00
Peter Steinberger	b88c4e9d20	chore: clean up lint and scratchpad	2026-01-07 01:28:46 +00:00
Peter Steinberger	bc9a3ce32a	refactor: unify outbound delivery formatting	2026-01-07 01:26:09 +00:00
Peter Steinberger	3fbe2963b3	test: align outbound normalization	2026-01-07 01:22:55 +00:00
Peter Steinberger	8ba6473462	style: fix send json indent	2026-01-07 01:21:29 +00:00
Peter Steinberger	dd78c26e6d	style: format direct send json	2026-01-07 01:21:03 +00:00
Peter Steinberger	2ce5df3efc	style: align outbound delivery formatting	2026-01-07 01:20:40 +00:00
Peter Steinberger	aefaed159b	refactor: normalize outbound payload delivery	2026-01-07 01:19:47 +00:00
Peter Steinberger	f171d509bb	refactor: centralize outbound target validation	2026-01-07 01:16:39 +00:00
Peter Steinberger	4fb9293c29	docs: fix internal doc links	2026-01-07 02:15:46 +01:00
buddyh	79fff828e0	Docs: sanitize AGENTS.md guidance	2026-01-07 01:15:37 +00:00
Peter Steinberger	f5938f8114	refactor: unify outbound delivery	2026-01-07 01:13:04 +00:00
Peter Steinberger	1ae5e9a26b	feat: add docs search command	2026-01-07 02:03:06 +01:00
Peter Steinberger	e816991dc5	docs: update changelog and clawtributor list for PR #341	2026-01-07 01:46:37 +01:00
Erik	cd4e2023ab	fix(agent): capture compaction retry AbortError for model fallback Wrap waitForCompactionRetry() in try/catch to capture AbortError that was escaping and bypassing the model fallback mechanism. When a timeout fires, session.abort() causes both session.prompt() and waitForCompactionRetry() to throw AbortError. Previously only the prompt error was captured, allowing the compaction error to escape to model-fallback.ts where it was immediately re-thrown (line 199: isAbortError check), bypassing fallback model attempts. Fixes #313	2026-01-07 01:44:37 +01:00
Peter Steinberger	5da8258614	fix: gateway:watch args	2026-01-07 00:37:32 +00:00
Peter Steinberger	0116184b1c	docs: recommend WSL2 for Windows installs	2026-01-07 01:21:36 +01:00
Peter Steinberger	62112d9978	feat: add onboarding doc links	2026-01-07 01:19:31 +01:00
Peter Steinberger	19c95d0ff7	fix(auth): serialize profile stats updates	2026-01-07 01:06:51 +01:00
Peter Steinberger	96d72ff91e	fix(auth): lock auth profile updates	2026-01-07 01:00:47 +01:00
Muhammed Mukhthar CM	eb5f758f6b	fix(auth): improve multi-account round-robin rotation and 429 handling This commit fixes several issues with multi-account OAuth rotation that were causing slow responses and inefficient account cycling. ## Changes ### 1. Fix usageStats race condition (auth-profiles.ts) The `markAuthProfileUsed`, `markAuthProfileCooldown`, `markAuthProfileGood`, and `clearAuthProfileCooldown` functions were using a stale in-memory store passed as a parameter. Long-running sessions would overwrite usageStats updates from concurrent sessions when saving. Fix: Re-read the store from disk before each update to get fresh usageStats from other sessions, then merge the update. ### 2. Capture AbortError from waitForCompactionRetry (pi-embedded-runner.ts) When a request timed out, `session.abort()` was called which throws an `AbortError`. The code structure was: ```javascript try { await session.prompt(params.prompt); } catch (err) { promptError = err; // Catches AbortError here } await waitForCompactionRetry(); // But THIS also throws AbortError! ``` The second `AbortError` from `waitForCompactionRetry()` escaped and bypassed the rotation/fallback logic entirely. Fix: Wrap `waitForCompactionRetry()` in its own try/catch to capture the error as `promptError`, enabling proper timeout handling. Root cause analysis and fix proposed by @erikpr1994 in #313. Fixes #313 ### 3. Fail fast on 429 rate limits (pi-ai patch) The pi-ai library was retrying 429 errors up to 3 times with exponential backoff before throwing. This meant a rate-limited account would waste 30+ seconds retrying before our rotation code could try the next account. Fix: Patch google-gemini-cli.js to: - Throw immediately on first 429 (no retries) - Not catch and retry 429 errors in the network error handler This allows the caller to rotate to the next account instantly on rate limit. Note: We submitted this fix upstream (https://github.com/badlogic/pi-mono/pull/504) but it was closed without merging. Keeping as a local patch for now. ## Testing With 6 Antigravity accounts configured: - Accounts rotate properly based on lastUsed (round-robin) - 429s trigger immediate rotation to next account - usageStats persist correctly across concurrent sessions - Cooldown tracking works as expected ## Before/After Before: Multiple 429 retries on same account, 30-90s delays After: Instant rotation on 429, responses in seconds	2026-01-07 00:56:32 +01:00
Peter Steinberger	2871657ebe	chore: make bun optional for source builds	2026-01-06 23:48:24 +00:00
Peter Steinberger	db4d0b8e75	docs: reorganize documentation structure	2026-01-07 00:45:46 +01:00
Peter Steinberger	b8db8502aa	docs: note discord voice message fix	2026-01-06 23:36:09 +00:00
VAC	ff200e3993	fix(discord): handle voice messages with empty content Discord voice messages have empty `content` with the audio in attachments. The nullish coalescing operator (`??`) doesn't fall through on empty strings, so voice messages were being dropped as 'empty content'. Changed to logical OR (`\|\|`) so empty string falls through to media placeholder.	2026-01-06 23:35:30 +00:00
Peter Steinberger	44a954b36d	docs: add Mintlify link rules	2026-01-06 23:32:18 +00:00
Peter Steinberger	3c1a2ff451	docs: normalize Mintlify links	2026-01-06 23:32:12 +00:00
Peter Steinberger	e62c8fb55c	docs: clarify gmail pubsub tailscale requirement	2026-01-06 23:28:49 +00:00
Peter Steinberger	d09a5100b6	docs: rewrite provider docs	2026-01-07 00:25:16 +01:00
Peter Steinberger	7214cf39ec	fix: prefer home linuxbrew paths	2026-01-07 00:18:07 +01:00
Peter Steinberger	b57d36f49c	fix(sessions_spawn): hard-fail invalid model overrides	2026-01-06 23:17:35 +00:00
Azade	0429a4b63b	test(sessions_spawn): add test for model parameter	2026-01-06 23:17:35 +00:00
Azade	274f408e6f	feat(sessions_spawn): add model parameter for sub-agent model override	2026-01-06 23:17:35 +00:00
Peter Steinberger	02c9cf0ff4	chore: remove duplicate daemon runtime imports	2026-01-07 00:14:08 +01:00
Peter Steinberger	198515397c	docs(commands): mention /stop	2026-01-06 23:11:57 +00:00
Peter Steinberger	dd0d23cd96	test(commands): add /stop native regression	2026-01-06 23:11:57 +00:00
Peter Steinberger	e0efcda77f	fix(commands): wire /stop across chat commands	2026-01-06 23:11:57 +00:00
Nacho Iacovino	0df7c3addf	feat(telegram): add /stop command to abort running agent Adds a /stop command that: - Can interrupt a running agent session mid-execution - Works in both DMs and group chats (including forum topics) - Uses grammy's bot.command() to run before the main message handler - Returns status: stopped, stop requested, or nothing running Also fixes session key lookup in pi-embedded-runner to use sessionKey instead of sessionId, ensuring /stop finds the correct active run.	2026-01-06 23:11:57 +00:00
Peter Steinberger	5bc3f13b46	feat: colorize models auth key labels	2026-01-07 00:10:01 +01:00
Peter Steinberger	b357746e1c	feat: add richer color to models output	2026-01-07 00:07:50 +01:00
Peter Steinberger	79f813e18e	style: format lint offenders	2026-01-07 00:04:44 +01:00
Peter Steinberger	fb321afa1d	docs: fix himalaya query usage	2026-01-07 00:04:18 +01:00
Peter Steinberger	d99fc89790	docs: add agent workspace guide	2026-01-07 00:04:03 +01:00
Peter Steinberger	0ad74ee941	test: mock select prompt in doctor tests	2026-01-07 00:01:50 +01:00
Peter Steinberger	d6eae275b1	fix: remove duplicate runtime note	2026-01-06 23:55:39 +01:00
Peter Steinberger	86b87682df	docs: refine model recommendation wording	2026-01-06 23:53:53 +01:00
Peter Steinberger	658ca205a9	docs: add model redirect and clarify guidance	2026-01-06 23:52:51 +01:00
Peter Steinberger	6d4cc28c4c	docs: link AgentSkills + ClawdHub guide	2026-01-06 23:51:01 +01:00
Peter Steinberger	55278c1c71	feat: add daemon runtime prompts	2026-01-06 23:51:00 +01:00
Peter Steinberger	edfc71a47e	docs: update model guidance	2026-01-06 23:48:25 +01:00
Peter Steinberger	c920ee1166	Merge branch 'pr-335-merge'	2026-01-06 23:45:35 +01:00
Peter Steinberger	ea216994a1	docs: polish himalaya skill docs	2026-01-06 23:44:06 +01:00
Dante Lex	16243b7edc	fix: simplify install to brew-only Remove cargo install option to avoid confusing the model with multiple installation methods.	2026-01-06 23:41:46 +01:00
Dante Lex	e6d6c822c5	feat: add himalaya email CLI skill Add skill for Himalaya (https://github.com/pimalaya/himalaya), a CLI email client supporting IMAP, SMTP, Notmuch, and Sendmail backends. Includes: - SKILL.md with common operations (list, read, reply, forward, send) - Configuration reference for Gmail, iCloud, and generic IMAP/SMTP - MML (MIME Meta Language) composition guide for attachments Tested with iCloud IMAP account - verified folder listing, email reading, and sending work correctly.	2026-01-06 23:41:46 +01:00
Peter Steinberger	5939363eed	fix: include telegram group sender in envelope headers	2026-01-06 22:34:02 +00:00
Peter Steinberger	825a692390	docs: add cron redirect	2026-01-06 22:32:01 +00:00
Peter Steinberger	8d50d08936	style: format daemon runtime changes	2026-01-06 23:29:38 +01:00
Peter Steinberger	8911a79d7f	docs: rewrite cron jobs guide and heartbeat notes	2026-01-06 22:28:42 +00:00
Peter Steinberger	4e6fcd1678	docs: link bun websocket issue	2026-01-06 23:28:42 +01:00
Peter Steinberger	707f7918bc	feat: add gateway daemon runtime selector	2026-01-06 23:27:58 +01:00
Peter Steinberger	18c43fe462	fix: bootstrap linuxbrew for skills	2026-01-06 23:27:38 +01:00
Peter Steinberger	585a455690	docs: link ClawdHub in hubs	2026-01-06 23:26:59 +01:00
Peter Steinberger	0e35aae4d5	docs: add ClawdHub guide	2026-01-06 23:24:29 +01:00
Peter Steinberger	e05a29395e	docs: clarify perSession isolation	2026-01-06 23:23:47 +01:00
Peter Steinberger	39d2ba78b7	fix(cli): harden pairing provider parse	2026-01-06 22:17:18 +00:00
Peter Steinberger	0931a65ab2	fix: auto-recover from Gemini session corruption Auto-merge after checks.	2026-01-06 22:12:05 +00:00
Peter Steinberger	2771001720	fix(state): auto-migrate legacy agent dir	2026-01-06 22:04:23 +00:00