docs: normalize Mintlify links

docs/RELEASING.md

@@ -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`](/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`](/mac/release)).
 
 6) **Publish (npm)**
 - [ ] Confirm git status is clean; commit and push as needed.

docs/agent.md

@@ -13,11 +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`](https://docs.clawd.bot/agent-workspace)
+Full workspace layout + backup guide: [`docs/agent-workspace.md`](/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`](/configuration)).
 
 ## Bootstrap files (injected)
 
@@ -52,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`](/configuration)).
 
 ## p-mono integration
 
@@ -91,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`](/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.
@@ -109,4 +109,4 @@ At minimum, set:
 
 ---
 
-*Next: [Group Chats](https://docs.clawd.bot/group-messages)* 🦞
+*Next: [Group Chats](/group-messages)* 🦞

docs/android.md

@@ -47,7 +47,7 @@ From the gateway machine:
 dns-sd -B _clawdbot-bridge._tcp local.
 ```
 
-More debugging notes: [`docs/bonjour.md`](https://docs.clawd.bot/bonjour).
+More debugging notes: [`docs/bonjour.md`](/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`](/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`](/camera) for parameters and CLI helpers.

docs/architecture.md

@@ -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`](/macos)).
 - **Agent process (Pi)**  
   - Spawned by the Gateway on demand for `agent` calls; streams events back over the same WS connection.
 - **WebChat**  

docs/bonjour.md

@@ -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)
+- Discovery policy and transport selection: [`docs/discovery.md`](/discovery)
-- Node pairing + approvals: [`docs/gateway/pairing.md`](https://docs.clawd.bot/gateway/pairing)
+- Node pairing + approvals: [`docs/gateway/pairing.md`](/gateway/pairing)

docs/browser.md

@@ -306,4 +306,4 @@ Notes:
 
 ## Troubleshooting
 
-For Linux-specific issues (especially Ubuntu with snap Chromium), see [browser-linux-troubleshooting](https://docs.clawd.bot/browser-linux-troubleshooting).
+For Linux-specific issues (especially Ubuntu with snap Chromium), see [browser-linux-troubleshooting](/browser-linux-troubleshooting).

docs/clawd.md

@@ -93,7 +93,7 @@ Tip: treat this folder like Clawd’s “memory” and make it a git repo (ideal
 clawdbot setup
 ```
 
-Full workspace layout + backup guide: [`docs/agent-workspace.md`](https://docs.clawd.bot/agent-workspace)
+Full workspace layout + backup guide: [`docs/agent-workspace.md`](/agent-workspace)
 
 Optional: choose a different workspace with `agent.workspace` (supports `~`).
 
@@ -206,12 +206,12 @@ Logs live under `/tmp/clawdbot/` (default: `clawdbot-YYYY-MM-DD.log`).
 
 ## Next steps
 
-- WebChat: [WebChat](https://docs.clawd.bot/webchat)
+- WebChat: [WebChat](/webchat)
-- Gateway ops: [Gateway runbook](https://docs.clawd.bot/gateway)
+- Gateway ops: [Gateway runbook](/gateway)
-- Cron + wakeups: [Cron jobs](https://docs.clawd.bot/cron-jobs)
+- Cron + wakeups: [Cron jobs](/cron-jobs)
-- macOS menu bar companion: [Clawdbot macOS app](https://docs.clawd.bot/macos)
+- macOS menu bar companion: [Clawdbot macOS app](/macos)
-- iOS node app: [iOS app](https://docs.clawd.bot/ios)
+- iOS node app: [iOS app](/ios)
-- Android node app: [Android app](https://docs.clawd.bot/android)
+- Android node app: [Android app](/android)
-- Windows status: [Windows app](https://docs.clawd.bot/windows)
+- Windows status: [Windows app](/windows)
-- Linux status: [Linux app](https://docs.clawd.bot/linux)
+- Linux status: [Linux app](/linux)
-- Security: [Security](https://docs.clawd.bot/security)
+- Security: [Security](/security)

docs/configuration.md

@@ -1286,7 +1286,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
@@ -1482,7 +1482,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 jobs](https://docs.clawd.bot/cron-jobs) for the feature overview and CLI examples.
+Cron is a Gateway-owned scheduler for wakeups and scheduled jobs. See [Cron jobs](/cron-jobs) for the feature overview and CLI examples.
 
 ```json5
 {
@@ -1495,4 +1495,4 @@ Cron is a Gateway-owned scheduler for wakeups and scheduled jobs. See [Cron jobs
 
 ---
 
-*Next: [Agent Runtime](https://docs.clawd.bot/agent)* 🦞
+*Next: [Agent Runtime](/agent)* 🦞

docs/dashboard.md

@@ -9,9 +9,9 @@ The Gateway dashboard is the browser Control UI served at `/` by default
 (override with `gateway.controlUi.basePath`).
 
 Key references:
-- [`docs/control-ui.md`](https://docs.clawd.bot/control-ui) for usage and UI capabilities.
+- [`docs/control-ui.md`](/control-ui) for usage and UI capabilities.
-- [`docs/tailscale.md`](https://docs.clawd.bot/tailscale) for Serve/Funnel automation.
+- [`docs/tailscale.md`](/tailscale) for Serve/Funnel automation.
-- [`docs/web.md`](https://docs.clawd.bot/web) for bind modes and security notes.
+- [`docs/web.md`](/web) for bind modes and security notes.
 
 Authentication is enforced at the WebSocket handshake via `connect.params.auth`
-(token or password). See `gateway.auth` in [`docs/configuration.md`](https://docs.clawd.bot/configuration).
+(token or password). See `gateway.auth` in [`docs/configuration.md`](/configuration).

docs/discord.md

@@ -5,100 +5,293 @@ read_when:
 ---
 # Discord (Bot API)
 
-Updated: 2026-01-06
+Updated: 2025-12-07
 
-Status: production-ready for DMs + guild channels via the Discord gateway.
+Status: ready for DM and guild text channels via the official Discord bot gateway.
 
-## What it is
+## Goals
-- Discord bot provider owned by the Gateway.
+- Talk to Clawdbot via Discord DMs or guild channels.
-- Deterministic routing: replies always go back to Discord.
+- Direct chats collapse into the agent's main session (default `agent:main:main`); guild channels stay isolated as `agent:<agentId>:discord:channel:<channelId>` (display names use `discord:<guildSlug>#<channelSlug>`).
-- DMs share the agent's main session; guild channels are isolated (`discord:channel:<id>`).
+- Group DMs are ignored by default; enable via `discord.dm.groupEnabled` and optionally restrict by `discord.dm.groupChannels`.
+- Keep routing deterministic: replies always go back to the provider they arrived on.
 
-## Setup (fast path)
+## How it works
-1) Create a Discord application + bot.
+1. Create a Discord application → Bot, enable the intents you need (DMs + guild messages + message content), and grab the bot token.
-2) Enable intents: **Message Content** (required), **Server Members** (recommended).
+2. Invite the bot to your server with the permissions required to read/send messages where you want to use it.
-3) Invite the bot to your server with message permissions.
+3. Configure Clawdbot with `DISCORD_BOT_TOKEN` (or `discord.token` in `~/.clawdbot/clawdbot.json`).
-4) Configure the token (env or config) and start the gateway.
+4. Run the gateway; it auto-starts the Discord provider only when a `discord` config section exists **and** the token is set (unless `discord.enabled = false`).
+   - If you prefer env vars, still add `discord: { enabled: true }` to `~/.clawdbot/clawdbot.json` and set `DISCORD_BOT_TOKEN`.
+5. Direct chats: use `user:<id>` (or a `<@id>` mention) when delivering; all turns land in the shared `main` session.
+6. Guild channels: use `channel:<channelId>` for delivery. Mentions are required by default and can be set per guild or per channel.
+7. Direct chats: secure by default via `discord.dm.policy` (default: `"pairing"`). Unknown senders get a pairing code; approve via `clawdbot pairing approve --provider discord <code>`.
+   - To keep old “open to anyone” behavior: set `discord.dm.policy="open"` and `discord.dm.allowFrom=["*"]`.
+   - To hard-allowlist: set `discord.dm.policy="allowlist"` and list senders in `discord.dm.allowFrom`.
+   - To ignore all DMs: set `discord.dm.enabled=false` or `discord.dm.policy="disabled"`.
+8. Group DMs are ignored by default; enable via `discord.dm.groupEnabled` and optionally restrict by `discord.dm.groupChannels`.
+9. Optional guild rules: set `discord.guilds` keyed by guild id (preferred) or slug, with per-channel rules.
+10. Optional native commands: set `commands.native: true` to register native commands in Discord; set `commands.native: false` to clear previously registered native commands. Text commands are controlled by `commands.text` and must be sent as standalone `/...` messages. Use `commands.useAccessGroups: false` to bypass access-group checks for commands.
+    - Full command list + config: [Slash commands](/slash-commands)
+11. Optional guild context history: set `discord.historyLimit` (default 20) to include the last N guild messages as context when replying to a mention. Set `0` to disable.
+12. Reactions: the agent can trigger reactions via the `discord` tool (gated by `discord.actions.*`).
+    - The `discord` tool is only exposed when the current provider is Discord.
+13. Native commands use isolated session keys (`discord:slash:${userId}`) rather than the shared `main` session.
+
+Note: Discord does not provide a simple username → id lookup without extra guild context, so prefer ids or `<@id>` mentions for DM delivery targets.
+Note: Slugs are lowercase with spaces replaced by `-`. Channel names are slugged without the leading `#`.
+Note: Guild context `[from:]` lines include `author.tag` + `id` to make ping-ready replies easy.
+
+## How to create your own bot
+
+This is the “Discord Developer Portal” setup for running Clawdbot in a server (guild) channel like `#help`.
+
+### 1) Create the Discord app + bot user
+1. Discord Developer Portal → **Applications** → **New Application**
+2. In your app:
+   - **Bot** → **Add Bot**
+   - Copy the **Bot Token** (this is what you put in `DISCORD_BOT_TOKEN`)
+
+### 2) Enable the gateway intents Clawdbot needs
+Discord blocks “privileged intents” unless you explicitly enable them.
+
+In **Bot** → **Privileged Gateway Intents**, enable:
+- **Message Content Intent** (required to read message text in most guilds; without it you’ll see “Used disallowed intents” or the bot will connect but not react to messages)
+- **Server Members Intent** (recommended; required for some member/user lookups and allowlist matching in guilds)
+
+You usually do **not** need **Presence Intent**.
+
+### 3) Generate an invite URL (OAuth2 URL Generator)
+In your app: **OAuth2** → **URL Generator**
+
+**Scopes**
+- ✅ `bot`
+- ✅ `applications.commands` (required for native commands)
+
+**Bot Permissions** (minimal baseline)
+- ✅ View Channels
+- ✅ Send Messages
+- ✅ Read Message History
+- ✅ Embed Links
+- ✅ Attach Files
+- ✅ Add Reactions (optional but recommended)
+- ✅ Use External Emojis / Stickers (optional; only if you want them)
+
+Avoid **Administrator** unless you’re debugging and fully trust the bot.
+
+Copy the generated URL, open it, pick your server, and install the bot.
+
+### 4) Get the ids (guild/user/channel)
+Discord uses numeric ids everywhere; Clawdbot config prefers ids.
+
+1. Discord (desktop/web) → **User Settings** → **Advanced** → enable **Developer Mode**
+2. Right-click:
+   - Server name → **Copy Server ID** (guild id)
+   - Channel (e.g. `#help`) → **Copy Channel ID**
+   - Your user → **Copy User ID**
+
+### 5) Configure Clawdbot
+
+#### Token
+Set the bot token via env var (recommended on servers):
+- `DISCORD_BOT_TOKEN=...`
+
+Or via config:
 
-Example:
 ```json5
 {
   discord: {
     enabled: true,
-    token: "YOUR_BOT_TOKEN",
+    token: "YOUR_BOT_TOKEN"
-    dm: { policy: "pairing" },
-    guilds: { "*": { requireMention: true } }
   }
 }
 ```
 
-## Access control (DMs + guilds)
+#### Allowlist + channel routing
-DMs:
+Example “single server, only allow me, only allow #help”:
-- Default: `discord.dm.policy = "pairing"`.
-- Unknown senders receive a pairing code; messages are ignored until approved.
-- Approve via:
-  - `clawdbot pairing list --provider discord`
-  - `clawdbot pairing approve --provider discord <CODE>`
-- Pairing is the default token exchange for Discord DMs. Details: https://docs.clawd.bot/pairing
 
-Guild channels:
+```json5
-- `discord.groupPolicy = open | allowlist | disabled`.
+{
-- `discord.guilds` (per-guild) + `channels` (per-channel) act as allowlists.
+  discord: {
-- Mentions are required by default; override per guild/channel.
+    enabled: true,
+    dm: { enabled: false },
+    guilds: {
+      "YOUR_GUILD_ID": {
+        users: ["YOUR_USER_ID"],
+        requireMention: true,
+        channels: {
+          help: { allow: true, requireMention: true }
+        }
+      }
+    }
+  }
+}
+```
 
-## How it works (behavior)
+Notes:
-- Inbound messages are normalized into the shared provider envelope.
+- `requireMention: true` means the bot only replies when mentioned (recommended for shared channels).
-- Optional guild context history is injected before the current message.
+- `routing.groupChat.mentionPatterns` also count as mentions for guild messages.
-- Replies always route back to the same channel or DM.
+- If `channels` is present, any channel not listed is denied by default.
 
-## Commands + reply threading
+### 6) Verify it works
-- Native commands: `commands.native = true` (registers `/` commands).
+1. Start the gateway.
-- Text commands: `commands.text = true` (standalone `/...` messages).
+2. In your server channel, send: `@Krill hello` (or whatever your bot name is).
-- Threaded replies: controlled by `discord.replyToMode` using reply tags.
+3. If nothing happens: check **Troubleshooting** below.
 
-## Media + limits
+### Troubleshooting
-- Files supported up to `discord.mediaMaxMb` (default 8 MB).
+- **“Used disallowed intents”**: enable **Message Content Intent** (and likely **Server Members Intent**) in the Developer Portal, then restart the gateway.
-- Outbound chunking controlled by `discord.textChunkLimit`.
+- **Bot connects but never replies in a guild channel**:
+  - Missing **Message Content Intent**, or
+  - The bot lacks channel permissions (View/Send/Read History), or
+  - Your config requires mentions and you didn’t mention it, or
+  - Your guild/channel allowlist denies the channel/user.
+- **DMs don’t work**: `discord.dm.enabled=false`, `discord.dm.policy="disabled"`, or you haven’t been approved yet (`discord.dm.policy="pairing"`).
 
-## Delivery targets (CLI/cron)
+## Capabilities & limits
-- DMs: `user:<id>`
+- DMs and guild text channels (threads are treated as separate channels; voice not supported).
-- Guild channels: `channel:<channelId>`
+- Typing indicators sent best-effort; message chunking honors Discord’s 2k character limit.
+- File uploads supported up to the configured `discord.mediaMaxMb` (default 8 MB).
+- Mention-gated guild replies by default to avoid noisy bots.
+- Reply context is injected when a message references another message (quoted content + ids).
+- Native reply threading is **off by default**; enable with `discord.replyToMode` and reply tags.
 
-## Configuration reference (Discord)
+## Config
-Full configuration: https://docs.clawd.bot/configuration
 
-Provider options:
+```json5
-- `discord.enabled`: enable/disable provider startup.
+{
-- `discord.token`: bot token (env: `DISCORD_BOT_TOKEN`).
+  discord: {
-- `discord.groupPolicy`: `open | allowlist | disabled` (default: open).
+    enabled: true,
-- `discord.textChunkLimit`: outbound chunk size (chars).
+    token: "abc.123",
-- `discord.mediaMaxMb`: inbound/outbound media cap (MB).
+    groupPolicy: "open",
-- `discord.historyLimit`: number of recent guild messages injected as context.
+    mediaMaxMb: 8,
-- `discord.replyToMode`: `off | first | all`.
+    actions: {
-- `discord.actions.reactions`: enable reaction tool actions.
+      reactions: true,
-- `discord.actions.stickers`: enable sticker actions.
+      stickers: true,
-- `discord.actions.polls`: enable poll actions.
+      polls: true,
-- `discord.actions.permissions`: enable permission inspection actions.
+      permissions: true,
-- `discord.actions.messages`: enable message read/send/edit/delete actions.
+      messages: true,
-- `discord.actions.threads`: enable thread actions.
+      threads: true,
-- `discord.actions.pins`: enable pin actions.
+      pins: true,
-- `discord.actions.search`: enable search actions.
+      search: true,
-- `discord.actions.memberInfo`: enable member info actions.
+      memberInfo: true,
-- `discord.actions.roleInfo`: enable role info actions.
+      roleInfo: true,
-- `discord.actions.roles`: enable role management actions.
+      roles: false,
-- `discord.actions.channelInfo`: enable channel info actions.
+      channelInfo: true,
-- `discord.actions.voiceStatus`: enable voice status actions.
+      voiceStatus: true,
-- `discord.actions.events`: enable event actions.
+      events: true,
-- `discord.actions.moderation`: enable moderation actions.
+      moderation: false
-- `discord.dm.enabled`: enable/disable DMs.
+    },
-- `discord.dm.policy`: `pairing | allowlist | open | disabled` (default: pairing).
+    replyToMode: "off",
-- `discord.dm.allowFrom`: DM allowlist (ids/usernames). `open` requires `"*"`.
+    dm: {
-- `discord.dm.groupEnabled`: enable group DMs.
+      enabled: true,
-- `discord.dm.groupChannels`: group DM allowlist.
+      policy: "pairing", // pairing | allowlist | open | disabled
-- `discord.guilds`: per-guild rules:
+      allowFrom: ["123456789012345678", "steipete"],
-  - `slug`, `requireMention`, `reactionNotifications`, `users`, `channels.*`.
+      groupEnabled: false,
+      groupChannels: ["clawd-dm"]
+    },
+    guilds: {
+      "*": { requireMention: true },
+      "123456789012345678": {
+        slug: "friends-of-clawd",
+        requireMention: false,
+        reactionNotifications: "own",
+        users: ["987654321098765432", "steipete"],
+        channels: {
+          general: { allow: true },
+          help: { allow: true, requireMention: true }
+        }
+      }
+    }
+  }
+}
+```
 
-Related global options:
+Ack reactions are controlled globally via `messages.ackReaction` +
-- `routing.groupChat.mentionPatterns`.
+`messages.ackReactionScope`.
-- `commands.native`, `commands.text`, `commands.useAccessGroups`.
+
-- `messages.responsePrefix`, `messages.ackReaction`, `messages.ackReactionScope`.
+- `dm.enabled`: set `false` to ignore all DMs (default `true`).
+- `dm.policy`: DM access control (`pairing` recommended). `"open"` requires `dm.allowFrom=["*"]`.
+- `dm.allowFrom`: DM allowlist (user ids or names). Used by `dm.policy="allowlist"` and for `dm.policy="open"` validation.
+- `dm.groupEnabled`: enable group DMs (default `false`).
+- `dm.groupChannels`: optional allowlist for group DM channel ids or slugs.
+- `groupPolicy`: controls guild channel handling (`open|disabled|allowlist`); `allowlist` requires channel allowlists.
+- `guilds`: per-guild rules keyed by guild id (preferred) or slug.
+- `guilds."*"`: default per-guild settings applied when no explicit entry exists.
+- `guilds.<id>.slug`: optional friendly slug used for display names.
+- `guilds.<id>.users`: optional per-guild user allowlist (ids or names).
+- `guilds.<id>.channels`: channel rules (keys are channel slugs or ids).
+- `guilds.<id>.requireMention`: per-guild mention requirement (overridable per channel).
+- `guilds.<id>.reactionNotifications`: reaction system event mode (`off`, `own`, `all`, `allowlist`).
+- `mediaMaxMb`: clamp inbound media saved to disk.
+- `historyLimit`: number of recent guild messages to include as context when replying to a mention (default 20, `0` disables).
+- `actions`: per-action tool gates; omit to allow all (set `false` to disable).
+  - `reactions` (covers react + read reactions)
+  - `stickers`, `polls`, `permissions`, `messages`, `threads`, `pins`, `search`
+  - `memberInfo`, `roleInfo`, `channelInfo`, `voiceStatus`, `events`
+  - `roles` (role add/remove, default `false`)
+  - `moderation` (timeout/kick/ban, default `false`)
+
+Reaction notifications use `guilds.<id>.reactionNotifications`:
+- `off`: no reaction events.
+- `own`: reactions on the bot's own messages (default).
+- `all`: all reactions on all messages.
+- `allowlist`: reactions from `guilds.<id>.users` on all messages (empty list disables).
+
+### Tool action defaults
+
+| Action group | Default | Notes |
+| --- | --- | --- |
+| reactions | enabled | React + list reactions + emojiList |
+| stickers | enabled | Send stickers |
+| polls | enabled | Create polls |
+| permissions | enabled | Channel permission snapshot |
+| messages | enabled | Read/send/edit/delete |
+| threads | enabled | Create/list/reply |
+| pins | enabled | Pin/unpin/list |
+| search | enabled | Message search (preview spec) |
+| memberInfo | enabled | Member info |
+| roleInfo | enabled | Role list |
+| channelInfo | enabled | Channel info + list |
+| voiceStatus | enabled | Voice state lookup |
+| events | enabled | List/create scheduled events |
+| roles | disabled | Role add/remove |
+| moderation | disabled | Timeout/kick/ban |
+- `replyToMode`: `off` (default), `first`, or `all`. Applies only when the model includes a reply tag.
+
+## Reply tags
+To request a threaded reply, the model can include one tag in its output:
+- `[[reply_to_current]]` — reply to the triggering Discord message.
+- `[[reply_to:<id>]]` — reply to a specific message id from context/history.
+Current message ids are appended to prompts as `[message_id: …]`; history entries already include ids.
+
+Behavior is controlled by `discord.replyToMode`:
+- `off`: ignore tags.
+- `first`: only the first outbound chunk/attachment is a reply.
+- `all`: every outbound chunk/attachment is a reply.
+
+Allowlist matching notes:
+- `allowFrom`/`users`/`groupChannels` accept ids, names, tags, or mentions like `<@id>`.
+- Prefixes like `discord:`/`user:` (users) and `channel:` (group DMs) are supported.
+- Use `*` to allow any sender/channel.
+- When `guilds.<id>.channels` is present, channels not listed are denied by default.
+
+Native command notes:
+- The registered commands mirror Clawdbot’s chat commands.
+- Native commands honor the same allowlists as DMs/guild messages (`discord.dm.allowFrom`, `discord.guilds`, per-channel rules).
+
+## Tool actions
+The agent can call `discord` with actions like:
+- `react` / `reactions` (add or list reactions)
+- `sticker`, `poll`, `permissions`
+- `readMessages`, `sendMessage`, `editMessage`, `deleteMessage`
+- `threadCreate`, `threadList`, `threadReply`
+- `pinMessage`, `unpinMessage`, `listPins`
+- `searchMessages`, `memberInfo`, `roleInfo`, `roleAdd`, `roleRemove`, `emojiList`
+- `channelInfo`, `channelList`, `voiceStatus`, `eventList`, `eventCreate`
+- `timeout`, `kick`, `ban`
+
+Discord message ids are surfaced in the injected context (`[discord message id: …]` and history lines) so the agent can target them.
+Emoji can be unicode (e.g., `✅`) or custom emoji syntax like `<:party_blob:1234567890>`.
+
+## Safety & ops
+- Treat the bot token like a password; prefer the `DISCORD_BOT_TOKEN` env var on supervised hosts or lock down the config file permissions.
+- Only grant the bot permissions it needs (typically Read/Send Messages).
+- If the bot is stuck or rate limited, restart the gateway (`clawdbot gateway --force`) after confirming no other processes own the Discord session.

docs/discovery.md

@@ -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`](/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`](/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)

docs/faq.md

@@ -3,7 +3,7 @@ summary: "Frequently asked questions about Clawdbot setup, configuration, and us
 ---
 # FAQ 🦞
 
-Common questions from the community. For detailed configuration, see [Configuration](https://docs.clawd.bot/configuration).
+Common questions from the community. For detailed configuration, see [Configuration](/configuration).
 
 ## Installation & Setup
 
@@ -307,7 +307,7 @@ Per-group activation can be changed by the owner:
 - `/activation mention` — respond only when mentioned (default)
 - `/activation always` — respond to all messages
 
-See [Groups](https://docs.clawd.bot/groups) for details.
+See [Groups](/groups) for details.
 
 ---
 
@@ -344,7 +344,7 @@ cat ~/.clawdbot/clawdbot.json | grep workspace
 - **Telegram** — Via Bot API (grammY).
 - **Discord** — Bot integration.
 - **iMessage** — Via `imsg` CLI (macOS only).
-- **Signal** — Via `signal-cli` (see [Signal](https://docs.clawd.bot/signal)).
+- **Signal** — Via `signal-cli` (see [Signal](/signal)).
 - **WebChat** — Browser-based chat UI.
 
 ### Discord: Bot works in channels but not DMs?
@@ -586,7 +586,7 @@ Quick reference (send these in chat):
 
 Slash commands are owner-only (gated by `whatsapp.allowFrom` and command authorization on other surfaces).
 Commands are only recognized when the entire message is the command (slash required; no plain-text aliases).
-Full list + config: https://docs.clawd.bot/slash-commands
+Full list + config: [Slash commands](/slash-commands)
 
 ### How do I switch models on the fly?
 

docs/gateway.md

@@ -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`](/presence) for how presence is produced/deduped and why `instanceId` matters.
 
 ## Events
 - `agent` — streamed tool/output events from the agent run (seq-tagged).

docs/getting-started.md

@@ -17,7 +17,7 @@ Recommended path: use the **CLI onboarding wizard** (`clawdbot onboard`). It set
 - workspace bootstrap + skills
 - optional background daemon
 
-If you want the deeper reference pages, jump to: [Wizard](https://docs.clawd.bot/wizard), [Setup](https://docs.clawd.bot/setup), [Pairing](https://docs.clawd.bot/pairing), [Security](https://docs.clawd.bot/security).
+If you want the deeper reference pages, jump to: [Wizard](/wizard), [Setup](/setup), [Pairing](/pairing), [Security](/security).
 
 ## 0) Prereqs
 
@@ -66,7 +66,7 @@ What you’ll choose:
 - **Daemon**: optional background install (launchd/systemd/Task Scheduler)
   - **Runtime**: Node (recommended; required for WhatsApp) or Bun (faster, but incompatible with WhatsApp)
 
-Wizard doc: https://docs.clawd.bot/wizard
+Wizard doc: [Wizard](/wizard)
 
 ### Auth: where it lives (important)
 
@@ -103,13 +103,13 @@ bun run clawdbot login
 
 Scan via WhatsApp → Settings → Linked Devices.
 
-WhatsApp doc: https://docs.clawd.bot/whatsapp
+WhatsApp doc: [WhatsApp](/whatsapp)
 
 ### Telegram / Discord / others
 
 The wizard can write tokens/config for you. If you prefer manual config, start with:
-- Telegram: https://docs.clawd.bot/telegram
+- Telegram: [Telegram](/telegram)
-- Discord: https://docs.clawd.bot/discord
+- Discord: [Discord](/discord)
 
 ## 6) DM safety (pairing approvals)
 
@@ -122,7 +122,7 @@ bun run clawdbot pairing list --provider telegram
 bun run clawdbot pairing approve --provider telegram <CODE>
 ```
 
-Pairing doc: https://docs.clawd.bot/pairing
+Pairing doc: [Pairing](/pairing)
 
 ## 7) Verify end-to-end
 
@@ -137,6 +137,6 @@ If `health` shows “no auth configured”, go back to the wizard and set OAuth/
 
 ## Next steps (optional, but great)
 
-- macOS menu bar app + voice wake: https://docs.clawd.bot/macos
+- macOS menu bar app + voice wake: [macOS app](/macos)
-- iOS/Android nodes (Canvas/camera/voice): https://docs.clawd.bot/nodes
+- iOS/Android nodes (Canvas/camera/voice): [Nodes](/nodes)
-- Remote access (SSH tunnel / Tailscale Serve): https://docs.clawd.bot/remote and https://docs.clawd.bot/tailscale
+- Remote access (SSH tunnel / Tailscale Serve): [Remote access](/remote) and [Tailscale](/tailscale)

docs/groups.md

@@ -127,4 +127,4 @@ The agent system prompt includes a group intro on the first turn of a new group
 - Group replies always go back to the same `chat_id`.
 
 ## WhatsApp specifics
-See [`docs/group-messages.md`](https://docs.clawd.bot/group-messages) for WhatsApp-only behavior (history injection, mention handling details).
+See [`docs/group-messages.md`](/group-messages) for WhatsApp-only behavior (history injection, mention handling details).

docs/heartbeat.md

@@ -96,7 +96,7 @@ 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](https://docs.clawd.bot/cron-jobs) when you
+- Scheduled routines (use [Cron jobs](/cron-jobs) when you
   need exact schedules or isolated runs).
 
 ## Wake hook

docs/hubs.md

@@ -9,144 +9,144 @@ Use these hubs to discover every page, including deep dives and reference docs t
 
 ## Start here
 
-- [Index](https://docs.clawd.bot)
+- [Index](/)
-- [Getting Started](https://docs.clawd.bot/getting-started)
+- [Getting Started](/getting-started)
-- [Onboarding](https://docs.clawd.bot/onboarding)
+- [Onboarding](/onboarding)
-- [Wizard](https://docs.clawd.bot/wizard)
+- [Wizard](/wizard)
-- [Setup](https://docs.clawd.bot/setup)
+- [Setup](/setup)
-- [FAQ](https://docs.clawd.bot/faq)
+- [FAQ](/faq)
-- [Configuration](https://docs.clawd.bot/configuration)
+- [Configuration](/configuration)
-- [Clawd (personal assistant)](https://docs.clawd.bot/clawd)
+- [Clawd (personal assistant)](/clawd)
-- [Lore](https://docs.clawd.bot/lore)
+- [Lore](/lore)
 
 ## Installation + distribution
 
-- [Docker](https://docs.clawd.bot/docker)
+- [Docker](/docker)
-- [Nix](https://docs.clawd.bot/nix)
+- [Nix](/nix)
 
 ## Core concepts
 
-- [Architecture](https://docs.clawd.bot/architecture)
+- [Architecture](/architecture)
-- [Agent runtime](https://docs.clawd.bot/agent)
+- [Agent runtime](/agent)
-- [Agent workspace](https://docs.clawd.bot/agent-workspace)
+- [Agent workspace](/agent-workspace)
-- [Agent loop](https://docs.clawd.bot/agent-loop)
+- [Agent loop](/agent-loop)
-- [Multi-agent routing](https://docs.clawd.bot/multi-agent)
+- [Multi-agent routing](/multi-agent)
-- [Sessions](https://docs.clawd.bot/session)
+- [Sessions](/session)
-- [Sessions (alias)](https://docs.clawd.bot/sessions)
+- [Sessions (alias)](/sessions)
-- [Session tools](https://docs.clawd.bot/session-tool)
+- [Session tools](/session-tool)
-- [Queue](https://docs.clawd.bot/queue)
+- [Queue](/queue)
-- [Slash commands](https://docs.clawd.bot/slash-commands)
+- [Slash commands](/slash-commands)
-- [RPC adapters](https://docs.clawd.bot/rpc)
+- [RPC adapters](/rpc)
-- [TypeBox schemas](https://docs.clawd.bot/typebox)
+- [TypeBox schemas](/typebox)
-- [Presence](https://docs.clawd.bot/presence)
+- [Presence](/presence)
-- [Discovery + transports](https://docs.clawd.bot/discovery)
+- [Discovery + transports](/discovery)
-- [Bonjour](https://docs.clawd.bot/bonjour)
+- [Bonjour](/bonjour)
-- [Provider routing](https://docs.clawd.bot/provider-routing)
+- [Provider routing](/provider-routing)
-- [Groups](https://docs.clawd.bot/groups)
+- [Groups](/groups)
-- [Group messages](https://docs.clawd.bot/group-messages)
+- [Group messages](/group-messages)
 
 ## Providers + ingress
 
-- [WhatsApp](https://docs.clawd.bot/whatsapp)
+- [WhatsApp](/whatsapp)
-- [Telegram](https://docs.clawd.bot/telegram)
+- [Telegram](/telegram)
-- [Telegram (grammY notes)](https://docs.clawd.bot/grammy)
+- [Telegram (grammY notes)](/grammy)
-- [Slack](https://docs.clawd.bot/slack)
+- [Slack](/slack)
-- [Discord](https://docs.clawd.bot/discord)
+- [Discord](/discord)
-- [Signal](https://docs.clawd.bot/signal)
+- [Signal](/signal)
-- [iMessage](https://docs.clawd.bot/imessage)
+- [iMessage](/imessage)
-- [WebChat](https://docs.clawd.bot/webchat)
+- [WebChat](/webchat)
-- [Webhooks](https://docs.clawd.bot/webhook)
+- [Webhooks](/webhook)
-- [Gmail Pub/Sub](https://docs.clawd.bot/gmail-pubsub)
+- [Gmail Pub/Sub](/gmail-pubsub)
 
 ## Gateway + operations
 
-- [Gateway runbook](https://docs.clawd.bot/gateway)
+- [Gateway runbook](/gateway)
-- [Gateway pairing](https://docs.clawd.bot/gateway/pairing)
+- [Gateway pairing](/gateway/pairing)
-- [Gateway lock](https://docs.clawd.bot/gateway-lock)
+- [Gateway lock](/gateway-lock)
-- [Background process](https://docs.clawd.bot/background-process)
+- [Background process](/background-process)
-- [Health](https://docs.clawd.bot/health)
+- [Health](/health)
-- [Heartbeat](https://docs.clawd.bot/heartbeat)
+- [Heartbeat](/heartbeat)
-- [Doctor](https://docs.clawd.bot/doctor)
+- [Doctor](/doctor)
-- [Logging](https://docs.clawd.bot/logging)
+- [Logging](/logging)
-- [Dashboard](https://docs.clawd.bot/dashboard)
+- [Dashboard](/dashboard)
-- [Control UI](https://docs.clawd.bot/control-ui)
+- [Control UI](/control-ui)
-- [Remote access](https://docs.clawd.bot/remote)
+- [Remote access](/remote)
-- [Remote gateway README](https://docs.clawd.bot/remote-gateway-readme)
+- [Remote gateway README](/remote-gateway-readme)
-- [Tailscale](https://docs.clawd.bot/tailscale)
+- [Tailscale](/tailscale)
-- [Security](https://docs.clawd.bot/security)
+- [Security](/security)
-- [Troubleshooting](https://docs.clawd.bot/troubleshooting)
+- [Troubleshooting](/troubleshooting)
 
 ## Tools + automation
 
-- [Tools surface](https://docs.clawd.bot/tools)
+- [Tools surface](/tools)
-- [Bash tool](https://docs.clawd.bot/bash)
+- [Bash tool](/bash)
-- [Elevated mode](https://docs.clawd.bot/elevated)
+- [Elevated mode](/elevated)
-- [Cron jobs](https://docs.clawd.bot/cron-jobs)
+- [Cron jobs](/cron-jobs)
-- [Thinking + verbose](https://docs.clawd.bot/thinking)
+- [Thinking + verbose](/thinking)
-- [Models](https://docs.clawd.bot/models)
+- [Models](/models)
-- [Agent send CLI](https://docs.clawd.bot/agent-send)
+- [Agent send CLI](/agent-send)
-- [Terminal UI](https://docs.clawd.bot/tui)
+- [Terminal UI](/tui)
-- [Browser control](https://docs.clawd.bot/browser)
+- [Browser control](/browser)
-- [Browser (Linux troubleshooting)](https://docs.clawd.bot/browser-linux-troubleshooting)
+- [Browser (Linux troubleshooting)](/browser-linux-troubleshooting)
 
 ## Nodes, media, voice
 
-- [Nodes overview](https://docs.clawd.bot/nodes)
+- [Nodes overview](/nodes)
-- [Camera](https://docs.clawd.bot/camera)
+- [Camera](/camera)
-- [Images](https://docs.clawd.bot/images)
+- [Images](/images)
-- [Audio](https://docs.clawd.bot/audio)
+- [Audio](/audio)
-- [Location command](https://docs.clawd.bot/location-command)
+- [Location command](/location-command)
-- [Voice wake](https://docs.clawd.bot/voicewake)
+- [Voice wake](/voicewake)
-- [Talk mode](https://docs.clawd.bot/talk)
+- [Talk mode](/talk)
 
 ## Platforms
 
-- [macOS app overview](https://docs.clawd.bot/macos)
+- [macOS app overview](/macos)
-- [macOS dev setup](https://docs.clawd.bot/mac/dev-setup)
+- [macOS dev setup](/mac/dev-setup)
-- [macOS menu bar](https://docs.clawd.bot/mac/menu-bar)
+- [macOS menu bar](/mac/menu-bar)
-- [macOS voice wake](https://docs.clawd.bot/mac/voicewake)
+- [macOS voice wake](/mac/voicewake)
-- [macOS voice overlay](https://docs.clawd.bot/mac/voice-overlay)
+- [macOS voice overlay](/mac/voice-overlay)
-- [macOS WebChat](https://docs.clawd.bot/mac/webchat)
+- [macOS WebChat](/mac/webchat)
-- [macOS Canvas](https://docs.clawd.bot/mac/canvas)
+- [macOS Canvas](/mac/canvas)
-- [macOS child process](https://docs.clawd.bot/mac/child-process)
+- [macOS child process](/mac/child-process)
-- [macOS health](https://docs.clawd.bot/mac/health)
+- [macOS health](/mac/health)
-- [macOS icon](https://docs.clawd.bot/mac/icon)
+- [macOS icon](/mac/icon)
-- [macOS logging](https://docs.clawd.bot/mac/logging)
+- [macOS logging](/mac/logging)
-- [macOS permissions](https://docs.clawd.bot/mac/permissions)
+- [macOS permissions](/mac/permissions)
-- [macOS remote](https://docs.clawd.bot/mac/remote)
+- [macOS remote](/mac/remote)
-- [macOS signing](https://docs.clawd.bot/mac/signing)
+- [macOS signing](/mac/signing)
-- [macOS release](https://docs.clawd.bot/mac/release)
+- [macOS release](/mac/release)
-- [macOS bun gateway](https://docs.clawd.bot/mac/bun)
+- [macOS bun gateway](/mac/bun)
-- [macOS XPC](https://docs.clawd.bot/mac/xpc)
+- [macOS XPC](/mac/xpc)
-- [macOS skills](https://docs.clawd.bot/mac/skills)
+- [macOS skills](/mac/skills)
-- [macOS Peekaboo plan](https://docs.clawd.bot/mac/peekaboo)
+- [macOS Peekaboo plan](/mac/peekaboo)
-- [iOS node](https://docs.clawd.bot/ios)
+- [iOS node](/ios)
-- [Android node](https://docs.clawd.bot/android)
+- [Android node](/android)
-- [Windows app](https://docs.clawd.bot/windows)
+- [Windows app](/windows)
-- [Linux app](https://docs.clawd.bot/linux)
+- [Linux app](/linux)
-- [Web surfaces](https://docs.clawd.bot/web)
+- [Web surfaces](/web)
 
 ## Workspace + templates
 
-- [Skills](https://docs.clawd.bot/skills)
+- [Skills](/skills)
-- [ClawdHub](https://docs.clawd.bot/clawdhub)
+- [ClawdHub](/clawdhub)
-- [Skills config](https://docs.clawd.bot/skills-config)
+- [Skills config](/skills-config)
-- [Default AGENTS](https://docs.clawd.bot/AGENTS.default)
+- [Default AGENTS](/AGENTS.default)
-- [Templates: AGENTS](https://docs.clawd.bot/templates/AGENTS)
+- [Templates: AGENTS](/templates/AGENTS)
-- [Templates: BOOTSTRAP](https://docs.clawd.bot/templates/BOOTSTRAP)
+- [Templates: BOOTSTRAP](/templates/BOOTSTRAP)
-- [Templates: IDENTITY](https://docs.clawd.bot/templates/IDENTITY)
+- [Templates: IDENTITY](/templates/IDENTITY)
-- [Templates: SOUL](https://docs.clawd.bot/templates/SOUL)
+- [Templates: SOUL](/templates/SOUL)
-- [Templates: TOOLS](https://docs.clawd.bot/templates/TOOLS)
+- [Templates: TOOLS](/templates/TOOLS)
-- [Templates: USER](https://docs.clawd.bot/templates/USER)
+- [Templates: USER](/templates/USER)
 
 ## Experiments + proposals
 
-- [Onboarding config protocol](https://docs.clawd.bot/onboarding-config-protocol)
+- [Onboarding config protocol](/onboarding-config-protocol)
-- [Research: memory](https://docs.clawd.bot/research/memory)
+- [Research: memory](/research/memory)
-- [Proposal: model config](https://docs.clawd.bot/proposals/model-config)
+- [Proposal: model config](/proposals/model-config)
 
 ## Testing + release
 
-- [Testing](https://docs.clawd.bot/test)
+- [Testing](/test)
-- [Release checklist](https://docs.clawd.bot/RELEASING)
+- [Release checklist](/RELEASING)
-- [Device models](https://docs.clawd.bot/device-models)
+- [Device models](/device-models)

docs/imessage.md

@@ -43,7 +43,7 @@ DMs:
 - Approve via:
   - `clawdbot pairing list --provider imessage`
   - `clawdbot pairing approve --provider imessage <CODE>`
-- Pairing is the default token exchange for iMessage DMs. Details: https://docs.clawd.bot/pairing
+- Pairing is the default token exchange for iMessage DMs. Details: [Pairing](/pairing)
 
 Groups:
 - `imessage.groupPolicy = open | allowlist | disabled`.
@@ -71,7 +71,7 @@ imsg chats --limit 20
 ```
 
 ## Configuration reference (iMessage)
-Full configuration: https://docs.clawd.bot/configuration
+Full configuration: [Configuration](/configuration)
 
 Provider options:
 - `imessage.enabled`: enable/disable provider startup.

docs/index.md

@@ -19,8 +19,8 @@ read_when:
 <p align="center">
   <a href="https://github.com/clawdbot/clawdbot">GitHub</a> ·
   <a href="https://github.com/clawdbot/clawdbot/releases">Releases</a> ·
-  <a href="https://docs.clawd.bot">Docs</a> ·
+  <a href="/">Docs</a> ·
-  <a href="https://docs.clawd.bot/clawd">Clawd setup</a>
+  <a href="/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,8 @@ 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
+- **New install from zero:** [Getting started](/getting-started)
-- **Guided setup (recommended):** https://docs.clawd.bot/wizard (`clawdbot onboard`)
+- **Guided setup (recommended):** [Wizard](/wizard) (`clawdbot onboard`)
 
 ## How it works
 
@@ -60,8 +60,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`).
+- **Canvas host**: HTTP file server on `canvasHost.port` (default `18793`), serving `/__clawdbot__/canvas/` for node WebViews; see [`docs/configuration.md`](/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).
+- **Remote use**: SSH tunnel or tailnet/VPN; see [`docs/remote.md`](/remote) and [`docs/discovery.md`](/discovery).
 
 ## Features (high level)
 
@@ -135,45 +135,45 @@ Example:
 ## Docs
 
 - Start here:
-  - [Docs hubs (all pages linked)](https://docs.clawd.bot/hubs)
+  - [Docs hubs (all pages linked)](/hubs)
-  - [FAQ](https://docs.clawd.bot/faq) ← *common questions answered*
+  - [FAQ](/faq) ← *common questions answered*
-  - [Configuration](https://docs.clawd.bot/configuration)
+  - [Configuration](/configuration)
-  - [Slash commands](https://docs.clawd.bot/slash-commands)
+  - [Slash commands](/slash-commands)
-  - [Multi-agent routing](https://docs.clawd.bot/multi-agent)
+  - [Multi-agent routing](/multi-agent)
-  - [Updating / rollback](https://docs.clawd.bot/updating)
+  - [Updating / rollback](/updating)
-  - [Pairing (DM + nodes)](https://docs.clawd.bot/pairing)
+  - [Pairing (DM + nodes)](/pairing)
-  - [Nix mode](https://docs.clawd.bot/nix)
+  - [Nix mode](/nix)
-  - [Clawd personal assistant setup](https://docs.clawd.bot/clawd)
+  - [Clawd personal assistant setup](/clawd)
-  - [Skills](https://docs.clawd.bot/skills)
+  - [Skills](/skills)
-  - [Skills config](https://docs.clawd.bot/skills-config)
+  - [Skills config](/skills-config)
-  - [Workspace templates](https://docs.clawd.bot/templates/AGENTS)
+  - [Workspace templates](/templates/AGENTS)
-  - [RPC adapters](https://docs.clawd.bot/rpc)
+  - [RPC adapters](/rpc)
-  - [Gateway runbook](https://docs.clawd.bot/gateway)
+  - [Gateway runbook](/gateway)
-  - [Nodes (iOS/Android)](https://docs.clawd.bot/nodes)
+  - [Nodes (iOS/Android)](/nodes)
-  - [Web surfaces (Control UI)](https://docs.clawd.bot/web)
+  - [Web surfaces (Control UI)](/web)
-  - [Discovery + transports](https://docs.clawd.bot/discovery)
+  - [Discovery + transports](/discovery)
-  - [Remote access](https://docs.clawd.bot/remote)
+  - [Remote access](/remote)
 - Providers and UX:
-  - [WebChat](https://docs.clawd.bot/webchat)
+  - [WebChat](/webchat)
-  - [Control UI (browser)](https://docs.clawd.bot/control-ui)
+  - [Control UI (browser)](/control-ui)
-  - [Telegram](https://docs.clawd.bot/telegram)
+  - [Telegram](/telegram)
-  - [Discord](https://docs.clawd.bot/discord)
+  - [Discord](/discord)
-  - [iMessage](https://docs.clawd.bot/imessage)
+  - [iMessage](/imessage)
-  - [Groups](https://docs.clawd.bot/groups)
+  - [Groups](/groups)
-  - [WhatsApp group messages](https://docs.clawd.bot/group-messages)
+  - [WhatsApp group messages](/group-messages)
-  - [Media: images](https://docs.clawd.bot/images)
+  - [Media: images](/images)
-  - [Media: audio](https://docs.clawd.bot/audio)
+  - [Media: audio](/audio)
 - Companion apps:
-  - [macOS app](https://docs.clawd.bot/macos)
+  - [macOS app](/macos)
-  - [iOS app](https://docs.clawd.bot/ios)
+  - [iOS app](/ios)
-  - [Android app](https://docs.clawd.bot/android)
+  - [Android app](/android)
-  - [Windows app](https://docs.clawd.bot/windows)
+  - [Windows app](/windows)
-  - [Linux app](https://docs.clawd.bot/linux)
+  - [Linux app](/linux)
 - Ops and safety:
-  - [Sessions](https://docs.clawd.bot/session)
+  - [Sessions](/session)
-  - [Cron jobs](https://docs.clawd.bot/cron-jobs)
+  - [Cron jobs](/cron-jobs)
-  - [Security](https://docs.clawd.bot/security)
+  - [Security](/security)
-  - [Troubleshooting](https://docs.clawd.bot/troubleshooting)
+  - [Troubleshooting](/troubleshooting)
 
 ## The name
 

docs/ios.md

@@ -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`](/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`](/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`](/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)).
+- 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`](/configuration)).
-- macOS “Canvas” is controlled via the Gateway node protocol (`canvas.*`), matching iOS/Android ([`docs/mac/canvas.md`](https://docs.clawd.bot/mac/canvas)).
+- macOS “Canvas” is controlled via the Gateway node protocol (`canvas.*`), matching iOS/Android ([`docs/mac/canvas.md`](/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.md`](/gateway) (gateway runbook)
-- [`docs/gateway/pairing.md`](https://docs.clawd.bot/gateway/pairing) (approval + storage)
+- [`docs/gateway/pairing.md`](/gateway/pairing) (approval + storage)
-- [`docs/bonjour.md`](https://docs.clawd.bot/bonjour) (discovery debugging)
+- [`docs/bonjour.md`](/bonjour) (discovery debugging)
-- [`docs/discovery.md`](https://docs.clawd.bot/discovery) (LAN vs tailnet vs SSH)
+- [`docs/discovery.md`](/discovery) (LAN vs tailnet vs SSH)

docs/mac/canvas.md

@@ -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`](/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`](/macos).
 
 ## Agent commands (current)
 

docs/mac/health.md

@@ -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`](/health) (`clawdbot status`, `clawdbot status --deep`, `clawdbot health --json`) and tail `/tmp/clawdbot/clawdbot-*.log` for `web-heartbeat` / `web-reconnect`.

docs/mac/signing.md

@@ -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`](/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`](/mac/permissions) for recovery steps.
 
 ## Build metadata for About
 

docs/mac/xpc.md

@@ -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`](/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.

docs/macos.md

@@ -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`](/mac/peekaboo)).
   - Installs a single CLI (`clawdbot`) by symlinking the bundled binary.
 
 ## High-level design

docs/model-failover.md

@@ -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`](/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`](/models) for the broader model selection and fallback overview.

docs/models.md

@@ -7,7 +7,7 @@ read_when:
 ---
 # Models CLI plan
 
-See [`docs/model-failover.md`](https://docs.clawd.bot/model-failover) for how auth profiles rotate (OAuth vs API keys), cooldowns, and how that interacts with model fallbacks.
+See [`docs/model-failover.md`](/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.
@@ -83,7 +83,7 @@ Output
 - Image routing uses `agent.imageModel` **only when configured** and the primary
   model lacks image input.
 - Persist last successful provider/model to session entry; auth profile success is global.
-- See [`docs/model-failover.md`](https://docs.clawd.bot/model-failover) for auth profile rotation, cooldowns, and timeout handling.
+- See [`docs/model-failover.md`](/model-failover) for auth profile rotation, cooldowns, and timeout handling.
 
 ## Tests
 
@@ -93,5 +93,5 @@ Output
 
 ## Docs
 
-- Update [`docs/configuration.md`](https://docs.clawd.bot/configuration) with `agent.models` + `agent.model` + `agent.imageModel`.
+- Update [`docs/configuration.md`](/configuration) with `agent.models` + `agent.model` + `agent.imageModel`.
 - Keep this doc current when CLI surface or scan logic changes.

docs/nix.md

@@ -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
+- [Wizard](/wizard) — non-Nix CLI setup
-- [Docker](https://docs.clawd.bot/docker) — containerized setup
+- [Docker](/docker) — containerized setup

docs/nodes.md

@@ -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:
 

docs/pairing.md

@@ -14,13 +14,13 @@ It is used in two places:
 1) **DM pairing** (who is allowed to talk to the bot)
 2) **Node pairing** (which devices/nodes are allowed to join the gateway network)
 
-Security context: https://docs.clawd.bot/security
+Security context: [Security](/security)
 
 ## 1) DM pairing (inbound chat access)
 
 When a provider is configured with DM policy `pairing`, unknown senders get a short code and their message is **not processed** until you approve.
 
-Default DM policies are documented in: https://docs.clawd.bot/security
+Default DM policies are documented in: [Security](/security)
 
 ### Approve a sender
 
@@ -64,7 +64,7 @@ Stored under `~/.clawdbot/nodes/`:
 
 ### Details
 
-Full protocol + design notes: https://docs.clawd.bot/gateway/pairing
+Full protocol + design notes: [Gateway pairing](/gateway/pairing)
 
 ### Source of truth (code)
 
@@ -74,12 +74,12 @@ Full protocol + design notes: https://docs.clawd.bot/gateway/pairing
 
 ## Related docs
 
-- Security model + prompt injection: https://docs.clawd.bot/security
+- Security model + prompt injection: [Security](/security)
-- Updating safely (run doctor): https://docs.clawd.bot/updating
+- Updating safely (run doctor): [Updating](/updating)
 - Provider configs:
-  - Telegram: https://docs.clawd.bot/telegram
+  - Telegram: [Telegram](/telegram)
-  - WhatsApp: https://docs.clawd.bot/whatsapp
+  - WhatsApp: [WhatsApp](/whatsapp)
-  - Signal: https://docs.clawd.bot/signal
+  - Signal: [Signal](/signal)
-  - iMessage: https://docs.clawd.bot/imessage
+  - iMessage: [iMessage](/imessage)
-  - Discord: https://docs.clawd.bot/discord
+  - Discord: [Discord](/discord)
-  - Slack: https://docs.clawd.bot/slack
+  - Slack: [Slack](/slack)

docs/plans/cron-add-hardening.md

@@ -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-jobs.md`](https://docs.clawd.bot/cron-jobs).
+- [x] Document cron compatibility normalization policy in [`docs/cron-jobs.md`](/cron-jobs).
 
 ### Phase 2 — Input normalization + tooling hardening
 - [x] Add shared cron input normalization helpers (`normalizeCronJobCreate`/`normalizeCronJobPatch`).

docs/plans/group-policy-hardening.md

@@ -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/groups.md`](/groups)
-- [`docs/telegram.md`](https://docs.clawd.bot/telegram)
+- [`docs/telegram.md`](/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/groups.md`](/groups) | Docs | Mention `tg:` alias + case-insensitive prefixes |
-| [`docs/telegram.md`](https://docs.clawd.bot/telegram) | Docs | Mention `tg:` alias + case-insensitive prefixes |
+| [`docs/telegram.md`](/telegram) | Docs | Mention `tg:` alias + case-insensitive prefixes |
 
 ---
 

docs/remote.md

@@ -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`](/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`](/mac/remote).

docs/rpc.md

@@ -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`](/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`](/imessage) for setup and addressing (`chat_id` preferred).
 
 ## Adapter guidelines
 - Gateway owns the process (start/stop tied to provider lifecycle).

docs/security.md

@@ -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](/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](/configuration) and [Groups](/groups)
 
 ## Prompt injection (what it is, why it matters)
 
@@ -139,8 +139,8 @@ 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
+- **Run the full Gateway in Docker** (container boundary): [Docker](/docker)
-- **Per-session tool sandbox** (`agent.sandbox`, host gateway + Docker-isolated tools): https://docs.clawd.bot/configuration
+- **Per-session tool sandbox** (`agent.sandbox`, host gateway + Docker-isolated tools): [Configuration](/configuration)
 
 Note: to prevent cross-agent access, keep `perSession: true` so each session gets
 its own container + workspace. `perSession: false` shares a single container.

docs/sessions.md

@@ -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`](/session).

docs/setup.md

@@ -17,7 +17,7 @@ Last updated: 2026-01-01
 ## Prereqs (from source)
 - Node `>=22`
 - `pnpm`
-- Docker (optional; only for containerized setup/e2e — see [`docs/docker.md`](https://docs.clawd.bot/docker))
+- Docker (optional; only for containerized setup/e2e — see [`docs/docker.md`](/docker))
 
 ## Tailoring strategy (so updates don’t hurt)
 
@@ -121,12 +121,12 @@ sudo loginctl enable-linger $USER
 ```
 
 For always-on or multi-user servers, consider a **system** service instead of a
-user service (no lingering needed). See [`docs/gateway.md`](https://docs.clawd.bot/gateway) for the systemd notes.
+user service (no lingering needed). See [`docs/gateway.md`](/gateway) for the systemd notes.
 
 ## Related docs
 
-- [`docs/gateway.md`](https://docs.clawd.bot/gateway) (Gateway runbook; flags, supervision, ports)
+- [`docs/gateway.md`](/gateway) (Gateway runbook; flags, supervision, ports)
-- [`docs/configuration.md`](https://docs.clawd.bot/configuration) (config schema + examples)
+- [`docs/configuration.md`](/configuration) (config schema + examples)
-- [`docs/discord.md`](https://docs.clawd.bot/discord) and [`docs/telegram.md`](https://docs.clawd.bot/telegram) (reply tags + replyToMode settings)
+- [`docs/discord.md`](/discord) and [`docs/telegram.md`](/telegram) (reply tags + replyToMode settings)
-- [`docs/clawd.md`](https://docs.clawd.bot/clawd) (personal assistant setup)
+- [`docs/clawd.md`](/clawd) (personal assistant setup)
-- [`docs/macos.md`](https://docs.clawd.bot/macos) (macOS app behavior; gateway lifecycle + “Attach only”)
+- [`docs/macos.md`](/macos) (macOS app behavior; gateway lifecycle + “Attach only”)

docs/signal.md

@@ -46,7 +46,7 @@ DMs:
 - Approve via:
   - `clawdbot pairing list --provider signal`
   - `clawdbot pairing approve --provider signal <CODE>`
-- Pairing is the default token exchange for Signal DMs. Details: https://docs.clawd.bot/pairing
+- Pairing is the default token exchange for Signal DMs. Details: [Pairing](/pairing)
 
 Groups:
 - `signal.groupPolicy = open | allowlist | disabled`.
@@ -68,7 +68,7 @@ Groups:
 - Usernames: `username:<name>` (if supported by your Signal account).
 
 ## Configuration reference (Signal)
-Full configuration: https://docs.clawd.bot/configuration
+Full configuration: [Configuration](/configuration)
 
 Provider options:
 - `signal.enabled`: enable/disable provider startup.

docs/skills.md

@@ -142,10 +142,10 @@ copy). Workspace skills are user-owned and override both on name conflicts.
 
 ## Config reference
 
-See [`docs/skills-config.md`](https://docs.clawd.bot/skills-config) for the full configuration schema.
+See [`docs/skills-config.md`](/skills-config) for the full configuration schema.
 
 ## Looking for more skills?
 
-Browse [ClawdHub](https://docs.clawd.bot/clawdhub).
+Browse [ClawdHub](/clawdhub).
 
 ---

docs/slack.md

@@ -5,95 +5,221 @@ read_when: "Setting up Slack or debugging Slack socket mode"
 
 # Slack (socket mode)
 
-Updated: 2026-01-06
+## Setup
+1) Create a Slack app (From scratch) in https://api.slack.com/apps.
+2) **Socket Mode** → toggle on. Then go to **Basic Information** → **App-Level Tokens** → **Generate Token and Scopes** with scope `connections:write`. Copy the **App Token** (`xapp-...`).
+3) **OAuth & Permissions** → add bot token scopes (use the manifest below). Click **Install to Workspace**. Copy the **Bot User OAuth Token** (`xoxb-...`).
+4) **Event Subscriptions** → enable events and subscribe to:
+   - `message.*` (includes edits/deletes/thread broadcasts)
+   - `app_mention`
+   - `reaction_added`, `reaction_removed`
+   - `member_joined_channel`, `member_left_channel`
+   - `channel_rename`
+   - `pin_added`, `pin_removed`
+5) Invite the bot to channels you want it to read.
+6) Slash Commands → create `/clawd` if you use `slack.slashCommand`. If you enable `commands.native`, add slash commands for the built-in chat commands (same names as `/help`).
+7) App Home → enable the **Messages Tab** so users can DM the bot.
 
-Status: production-ready for DMs + channels via Slack Socket Mode.
+Use the manifest below so scopes and events stay in sync.
 
-## What it is
+## Manifest (optional)
-- Slack bot provider owned by the Gateway.
+Use this Slack app manifest to create the app quickly (adjust the name/command if you want).
-- Socket Mode only (no inbound HTTP server required).
-- Deterministic routing: replies always go back to Slack.
 
-## Setup (fast path)
+```json
-1) Create a Slack app.
-2) Enable **Socket Mode** and create an **App Token** (`xapp-...`).
-3) Install the app to your workspace and copy the **Bot Token** (`xoxb-...`).
-4) Add required scopes + events (see Slack app manifest if needed).
-5) Configure tokens and start the gateway.
-
-Example:
-```json5
 {
-  slack: {
+  "display_information": {
-    enabled: true,
+    "name": "Clawdbot",
-    botToken: "xoxb-...",
+    "description": "Slack connector for Clawdbot"
-    appToken: "xapp-...",
+  },
-    dm: { policy: "pairing" },
+  "features": {
-    channels: { "#general": { allow: true, requireMention: true } }
+    "bot_user": {
+      "display_name": "Clawdbot",
+      "always_online": false
+    },
+    "app_home": {
+      "messages_tab_enabled": true,
+      "messages_tab_read_only_enabled": false
+    },
+    "slash_commands": [
+      {
+        "command": "/clawd",
+        "description": "Send a message to Clawdbot",
+        "should_escape": false
+      }
+    ]
+  },
+  "oauth_config": {
+    "scopes": {
+      "bot": [
+        "chat:write",
+        "channels:history",
+        "channels:read",
+        "groups:history",
+        "groups:read",
+        "groups:write",
+        "im:history",
+        "im:read",
+        "im:write",
+        "mpim:history",
+        "mpim:read",
+        "mpim:write",
+        "users:read",
+        "app_mentions:read",
+        "reactions:read",
+        "reactions:write",
+        "pins:read",
+        "pins:write",
+        "emoji:read",
+        "commands",
+        "files:read",
+        "files:write"
+      ]
+    }
+  },
+  "settings": {
+    "socket_mode_enabled": true,
+    "event_subscriptions": {
+      "bot_events": [
+        "app_mention",
+        "message.channels",
+        "message.groups",
+        "message.im",
+        "message.mpim",
+        "reaction_added",
+        "reaction_removed",
+        "member_joined_channel",
+        "member_left_channel",
+        "channel_rename",
+        "pin_added",
+        "pin_removed"
+      ]
+    }
   }
 }
 ```
 
-## Access control (DMs + channels)
+If you enable `commands.native`, add one `slash_commands` entry per command you want to expose (matching the `/help` list).
-DMs:
-- Default: `slack.dm.policy = "pairing"`.
-- Unknown senders receive a pairing code; messages are ignored until approved.
-- Approve via:
-  - `clawdbot pairing list --provider slack`
-  - `clawdbot pairing approve --provider slack <CODE>`
-- Pairing is the default token exchange for Slack DMs. Details: https://docs.clawd.bot/pairing
 
-Channels:
+## Scopes (current vs optional)
-- `slack.groupPolicy = open | allowlist | disabled`.
+Slack's Conversations API is type-scoped: you only need the scopes for the
-- `slack.channels` acts as the allowlist when `groupPolicy = allowlist`.
+conversation types you actually touch (channels, groups, im, mpim). See
-- Mentions are required by default unless overridden per channel.
+https://api.slack.com/docs/conversations-api for the overview.
 
-## How it works (behavior)
+### Required by current code
-- Inbound messages are normalized into the shared provider envelope.
+- `chat:write` (send/update/delete messages via `chat.postMessage`)
-- Replies always route back to the same channel or DM.
+  https://api.slack.com/methods/chat.postMessage
-- Threading: replies to a message stay in that thread if it was a thread message.
+- `im:write` (open DMs via `conversations.open` for user DMs)
+  https://api.slack.com/methods/conversations.open
+- `channels:history`, `groups:history`, `im:history`, `mpim:history`
+  (`conversations.history` in [`src/slack/actions.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/slack/actions.ts))
+  https://api.slack.com/methods/conversations.history
+- `channels:read`, `groups:read`, `im:read`, `mpim:read`
+  (`conversations.info` in [`src/slack/monitor.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/slack/monitor.ts))
+  https://api.slack.com/methods/conversations.info
+- `users:read` (`users.info` in [`src/slack/monitor.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/slack/monitor.ts) + [`src/slack/actions.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/slack/actions.ts))
+  https://api.slack.com/methods/users.info
+- `reactions:read`, `reactions:write` (`reactions.get` / `reactions.add`)
+  https://api.slack.com/methods/reactions.get
+  https://api.slack.com/methods/reactions.add
+- `pins:read`, `pins:write` (`pins.list` / `pins.add` / `pins.remove`)
+  https://api.slack.com/scopes/pins:read
+  https://api.slack.com/scopes/pins:write
+- `emoji:read` (`emoji.list`)
+  https://api.slack.com/scopes/emoji:read
+- `files:write` (uploads via `files.uploadV2`)
+  https://api.slack.com/messaging/files/uploading
 
-## Commands
+### Not needed today (but likely future)
-- Text commands: `commands.text = true` (standalone `/...` messages).
+- `mpim:write` (only if we add group-DM open/DM start via `conversations.open`)
-- Slack slash command: configure `slack.slashCommand` (separate from `commands.native`).
+- `groups:write` (only if we add private-channel management: create/rename/invite/archive)
+- `chat:write.public` (only if we want to post to channels the bot isn't in)
+  https://api.slack.com/scopes/chat:write.public
+- `users:read.email` (only if we need email fields from `users.info`)
+  https://api.slack.com/changelog/2017-04-narrowing-email-access
+- `files:read` (only if we start listing/reading file metadata)
 
-## Media + limits
+## Config
-- Files supported up to `slack.mediaMaxMb` (default 20 MB).
+Slack uses Socket Mode only (no HTTP webhook server). Provide both tokens:
-- Outbound chunking controlled by `slack.textChunkLimit`.
 
-## Delivery targets (CLI/cron)
+```json
-- DMs: `user:<id>`
+{
-- Channels: `channel:<id>`
+  "slack": {
+    "enabled": true,
+    "botToken": "xoxb-...",
+    "appToken": "xapp-...",
+    "groupPolicy": "open",
+    "dm": {
+      "enabled": true,
+      "policy": "pairing",
+      "allowFrom": ["U123", "U456", "*"],
+      "groupEnabled": false,
+      "groupChannels": ["G123"]
+    },
+    "channels": {
+      "C123": { "allow": true, "requireMention": true },
+      "#general": { "allow": true, "requireMention": false }
+    },
+    "reactionNotifications": "own",
+    "reactionAllowlist": ["U123"],
+    "actions": {
+      "reactions": true,
+      "messages": true,
+      "pins": true,
+      "memberInfo": true,
+      "emojiList": true
+    },
+    "slashCommand": {
+      "enabled": true,
+      "name": "clawd",
+      "sessionPrefix": "slack:slash",
+      "ephemeral": true
+    },
+    "textChunkLimit": 4000,
+    "mediaMaxMb": 20
+  }
+}
+```
 
-## Configuration reference (Slack)
+Tokens can also be supplied via env vars:
-Full configuration: https://docs.clawd.bot/configuration
+- `SLACK_BOT_TOKEN`
+- `SLACK_APP_TOKEN`
 
-Provider options:
+Ack reactions are controlled globally via `messages.ackReaction` +
-- `slack.enabled`: enable/disable provider startup.
+`messages.ackReactionScope`.
-- `slack.botToken`: bot token (env: `SLACK_BOT_TOKEN`).
-- `slack.appToken`: app token (env: `SLACK_APP_TOKEN`).
-- `slack.groupPolicy`: `open | allowlist | disabled` (default: open).
-- `slack.channels`: channel allowlist + per-channel `requireMention`.
-- `slack.textChunkLimit`: outbound chunk size (chars).
-- `slack.mediaMaxMb`: inbound/outbound media cap (MB).
-- `slack.reactionNotifications`: `off | own | all | allowlist`.
-- `slack.reactionAllowlist`: user allowlist for reaction notifications.
-- `slack.actions.reactions`: enable reaction tool actions.
-- `slack.actions.messages`: enable message read/send/edit/delete actions.
-- `slack.actions.pins`: enable pin actions.
-- `slack.actions.search`: enable search actions.
-- `slack.actions.permissions`: enable permission inspection actions.
-- `slack.actions.memberInfo`: enable member info actions.
-- `slack.actions.channelInfo`: enable channel info actions.
-- `slack.actions.emojiList`: enable emoji list actions.
-- `slack.slashCommand.*`: configure the Slack slash command endpoint (`name`, `sessionPrefix`, `ephemeral`).
-- `slack.dm.enabled`: enable/disable DMs.
-- `slack.dm.policy`: `pairing | allowlist | open | disabled` (default: pairing).
-- `slack.dm.allowFrom`: DM allowlist (ids/usernames). `open` requires `"*"`.
-- `slack.dm.groupEnabled`: enable group DMs.
-- `slack.dm.groupChannels`: group DM allowlist.
 
-Related global options:
+## Sessions + routing
-- `routing.groupChat.mentionPatterns`.
+- DMs share the `main` session (like WhatsApp/Telegram).
-- `commands.text`, `commands.useAccessGroups`.
+- Channels map to `slack:channel:<channelId>` sessions.
-- `messages.responsePrefix`, `messages.ackReaction`, `messages.ackReactionScope`.
+- 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: [Slash commands](/slash-commands)
+
+## DM security (pairing)
+- Default: `slack.dm.policy="pairing"` — unknown DM senders get a pairing code.
+- Approve via: `clawdbot pairing approve --provider slack <code>`.
+- To allow anyone: set `slack.dm.policy="open"` and `slack.dm.allowFrom=["*"]`.
+
+## Group policy
+- `slack.groupPolicy` controls channel handling (`open|disabled|allowlist`).
+- `allowlist` requires channels to be listed in `slack.channels`.
+
+## Delivery targets
+Use these with cron/CLI sends:
+- `user:<id>` for DMs
+- `channel:<id>` for channels
+
+## Tool actions
+Slack tool actions can be gated with `slack.actions.*`:
+
+| Action group | Default | Notes |
+| --- | --- | --- |
+| reactions | enabled | React + list reactions |
+| messages | enabled | Read/send/edit/delete |
+| pins | enabled | Pin/unpin/list |
+| memberInfo | enabled | Member info |
+| emojiList | enabled | Custom emoji list |
+
+## 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`).
+- Attachments are downloaded to the media store when permitted and under the size limit.

docs/telegram.md

@@ -43,7 +43,7 @@ Status: production-ready for bot DMs + groups via grammY. Long-polling by defaul
 - Approve via:
   - `clawdbot pairing list --provider telegram`
   - `clawdbot pairing approve --provider telegram <CODE>`
-- Pairing is the default token exchange used for Telegram DMs. Details: https://docs.clawd.bot/pairing
+- Pairing is the default token exchange used for Telegram DMs. Details: [Pairing](/pairing)
 
 Group gating:
 - `telegram.groupPolicy = open | allowlist | disabled`.
@@ -68,7 +68,7 @@ Controlled by `telegram.replyToMode`:
 - Example: `clawdbot send --provider telegram --to 123456789 "hi"`.
 
 ## Configuration reference (Telegram)
-Full configuration: https://docs.clawd.bot/configuration
+Full configuration: [Configuration](/configuration)
 
 Provider options:
 - `telegram.enabled`: enable/disable provider startup.

docs/thinking.md

@@ -35,7 +35,7 @@ read_when:
 - When verbose is on, agents that emit structured tool results (Pi, other JSON agents) send each tool result back as its own metadata-only message, prefixed with `<emoji> <tool-name>: <arg>` when available (path/command); the tool output itself is not forwarded. These tool summaries are sent as soon as each tool finishes (separate bubbles), not as streaming deltas. If you toggle `/verbose on|off` while a run is in-flight, subsequent tool bubbles honor the new setting.
 
 ## Related
-- Elevated mode docs live in [`docs/elevated.md`](https://docs.clawd.bot/elevated).
+- Elevated mode docs live in [`docs/elevated.md`](/elevated).
 
 ## Heartbeats
 - Heartbeat probe body is the configured heartbeat prompt (default: `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`). Inline directives in a heartbeat message apply as usual (but avoid changing session defaults from heartbeats).

docs/troubleshooting.md

@@ -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](/browser-linux-troubleshooting)

docs/updating.md

@@ -71,7 +71,7 @@ Typical things it does:
 - Detect and migrate older gateway services (launchd/systemd/schtasks) to current Clawdbot services.
 - On Linux, ensure systemd user lingering (so the Gateway survives logout).
 
-Details: https://docs.clawd.bot/doctor
+Details: [Doctor](/doctor)
 
 ## Start / stop / restart the Gateway
 
@@ -88,7 +88,7 @@ If you’re supervised:
 - Linux systemd user service: `systemctl --user restart clawdbot-gateway.service`
 - Windows: restart the `Clawdbot Gateway` Scheduled Task (Task Scheduler)
 
-Runbook + exact service labels: https://docs.clawd.bot/gateway
+Runbook + exact service labels: [Gateway runbook](/gateway)
 
 ## Rollback / pinning (when something breaks)
 
@@ -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](/troubleshooting)
 - Ask in Discord: https://discord.gg/clawd

docs/web.md

@@ -26,7 +26,7 @@ The UI talks directly to the Gateway WS and supports:
 ## Webhooks
 
 When `hooks.enabled=true`, the Gateway also exposes a small webhook endpoint on the same HTTP server.
-See [`docs/configuration.md`](https://docs.clawd.bot/configuration) → `hooks` for auth + payloads.
+See [`docs/configuration.md`](/configuration) → `hooks` for auth + payloads.
 
 ## Config (default-on)
 

docs/webchat.md

@@ -24,7 +24,7 @@ Status: the macOS/iOS SwiftUI chat UI talks directly to the Gateway WebSocket.
 - You do not need to run a separate WebChat server.
 
 ## Configuration reference (WebChat)
-Full configuration: https://docs.clawd.bot/configuration
+Full configuration: [Configuration](/configuration)
 
 Provider options:
 - No dedicated `webchat.*` block. WebChat uses the gateway endpoint + auth settings below.

docs/whatsapp.md

@@ -5,83 +5,152 @@ read_when:
 ---
 # WhatsApp (web provider)
 
-Updated: 2026-01-06
+Updated: 2025-12-23
 
-Status: WhatsApp Web via Baileys. Gateway owns the session(s).
+Status: WhatsApp Web via Baileys only. Gateway owns the session(s).
 
-## What it is
+## Goals
-- WhatsApp Web connection managed by the Gateway.
+- Multiple WhatsApp accounts (multi-account) in one Gateway process.
-- Deterministic routing: replies always return to WhatsApp.
+- Deterministic routing: replies return to WhatsApp, no model routing.
-- DMs share the agent's main session; groups are isolated (`whatsapp:group:<jid>`).
+- Model sees enough context to understand quoted replies.
 
-## Setup (fast path)
+## Architecture (who owns what)
-1) Use a real mobile number (WhatsApp blocks most VoIP numbers).
+- **Gateway** owns the Baileys socket and inbox loop.
-2) Run `clawdbot login` and scan the QR (Linked Devices).
+- **CLI / macOS app** talk to the gateway; no direct Baileys use.
-3) Start the gateway; the WhatsApp provider starts when a linked session exists.
+- **Active listener** is required for outbound sends; otherwise send fails fast.
-4) Lock down DMs and groups (pairing + allowlists are default-safe).
 
-Multi-account:
+## Getting a phone number
-- `clawdbot login --account <id>`
-- Configure `whatsapp.accounts.<id>` for per-account settings.
 
-## Access control (DMs + groups)
+WhatsApp requires a real mobile number for verification. VoIP and virtual numbers are usually blocked.
-DMs:
-- Default: `whatsapp.dmPolicy = "pairing"`.
-- Unknown senders get a pairing code and are ignored until approved.
-- Approve via:
-  - `clawdbot pairing list --provider whatsapp`
-  - `clawdbot pairing approve --provider whatsapp <CODE>`
-- Pairing is the default token exchange for WhatsApp DMs. Details: https://docs.clawd.bot/pairing
 
-Groups:
+**Recommended approaches:**
-- `whatsapp.groupPolicy = open | allowlist | disabled`.
+- **Local eSIM** from your country's mobile carrier (most reliable)
-- `whatsapp.groups` sets per-group defaults and becomes an allowlist when present (use `"*"` to allow all).
+  - Austria: [hot.at](https://www.hot.at)
-- Mention gating defaults to `requireMention: true` unless overridden.
+  - UK: [giffgaff](https://www.giffgaff.com) — free SIM, no contract
+- **Prepaid SIM** — cheap, just needs to receive one SMS for verification
 
-## How it works (behavior)
+**Avoid:** TextNow, Google Voice, most "free SMS" services — WhatsApp blocks these aggressively.
-- Inbound messages are normalized into the shared provider envelope with reply context.
-- Group replies require a mention by default (native mentions or `routing.groupChat.mentionPatterns`).
-- Recent group history can be injected for context (see `routing.groupChat.historyLimit`).
 
-## Reply delivery
+**Tip:** The number only needs to receive one verification SMS. After that, WhatsApp Web sessions persist via `creds.json`.
-- Standard WhatsApp messages (no threaded replies).
-- Text chunking is applied to stay within limits.
 
-## Media
+**WhatsApp Business:** You can use WhatsApp Business on the same phone with a different number. This is a great option if you want to keep your personal WhatsApp separate — just install WhatsApp Business and register it with Clawdbot's dedicated number.
-- Images/video/audio/documents supported.
-- Default cap: 5 MB per item (override via `agent.mediaMaxMb`).
-- Oversize media returns a warning instead of sending.
 
-## Delivery targets (CLI/cron)
+## Login + credentials
-- DMs: E.164 (`+15551234567`).
+- Login command: `clawdbot login` (QR via Linked Devices).
-- Groups: group JID (`12345-678@g.us`).
+- Multi-account login: `clawdbot login --account <id>` (`<id>` = `accountId`).
+- Default account (when `--account` is omitted): `default` if present, otherwise the first configured account id (sorted).
+- Credentials stored in `~/.clawdbot/credentials/whatsapp/<accountId>/creds.json`.
+- Backup copy at `creds.json.bak` (restored on corruption).
+- Legacy compatibility: older installs stored Baileys files directly in `~/.clawdbot/credentials/`.
+- Logout: `clawdbot logout` (or `--account <id>`) deletes WhatsApp auth state (but keeps shared `oauth.json`).
+- Logged-out socket => error instructs re-link.
 
-## Configuration reference (WhatsApp)
+## Inbound flow (DM + group)
-Full configuration: https://docs.clawd.bot/configuration
+- WhatsApp events come from `messages.upsert` (Baileys).
+- Inbox listeners are detached on shutdown to avoid accumulating event handlers in tests/restarts.
+- Status/broadcast chats are ignored.
+- Direct chats use E.164; groups use group JID.
+- **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>`).
+  - 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`).
+  - `allowlist` uses `whatsapp.groupAllowFrom` (fallback: explicit `whatsapp.allowFrom`).
+- **Self-chat mode**: avoids auto read receipts and ignores mention JIDs.
+- Read receipts sent for non-self-chat DMs.
 
-Provider options:
+## Message normalization (what the model sees)
-- `whatsapp.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).
+- `Body` is the current message body with envelope.
-- `whatsapp.allowFrom`: DM allowlist (E.164). `open` requires `"*"`.
+- Quoted reply context is **always appended**:
-- `whatsapp.groupPolicy`: `open | allowlist | disabled` (default: open).
+  ```
-- `whatsapp.groupAllowFrom`: group sender allowlist (E.164).
+  [Replying to +1555 id:ABC123]
-- `whatsapp.groups`: per-group defaults + allowlist (use `"*"` for global defaults).
+  <quoted text or <media:...>>
-- `whatsapp.textChunkLimit`: outbound chunk size (chars).
+  [/Replying]
-- `whatsapp.accounts`: per-account overrides:
+  ```
-  - `whatsapp.accounts.<id>.enabled`
+- Reply metadata also set:
-  - `whatsapp.accounts.<id>.authDir`
+  - `ReplyToId` = stanzaId
-  - `whatsapp.accounts.<id>.dmPolicy`
+  - `ReplyToBody` = quoted body or media placeholder
-  - `whatsapp.accounts.<id>.allowFrom`
+  - `ReplyToSender` = E.164 when known
-  - `whatsapp.accounts.<id>.groupPolicy`
+- Media-only inbound messages use placeholders:
-  - `whatsapp.accounts.<id>.groupAllowFrom`
+  - `<media:image|video|audio|document|sticker>`
-  - `whatsapp.accounts.<id>.groups`
-  - `whatsapp.accounts.<id>.textChunkLimit`
 
-Runtime options (WhatsApp web provider):
+## Groups
-- `web.enabled`: enable/disable provider startup.
+- Groups map to `agent:<agentId>:whatsapp:group:<jid>` sessions.
-- `web.heartbeatSeconds`: gateway heartbeat cadence.
+- Group policy: `whatsapp.groupPolicy = open|disabled|allowlist` (default `open`).
-- `web.reconnect.*`: reconnect backoff (`initialMs`, `maxMs`, `factor`, `jitter`, `maxAttempts`).
+- Activation modes:
+  - `mention` (default): requires @mention or regex match.
+  - `always`: always triggers.
+- `/activation mention|always` is owner-only and must be sent as a standalone message.
+- Owner = `whatsapp.allowFrom` (or self E.164 if unset).
+- **History injection**:
+  - Recent messages (default 50) inserted under:
+    `[Chat messages since your last reply - for context]`
+  - Current message under:
+    `[Current message - respond to this]`
+  - Sender suffix appended: `[from: Name (+E164)]`
+- Group metadata cached 5 min (subject + participants).
 
-Related global options:
+## Reply delivery (threading)
-- `routing.groupChat.mentionPatterns`, `routing.groupChat.historyLimit`.
+- WhatsApp Web sends standard messages (no quoted reply threading in the current gateway).
-- `commands.text`, `commands.useAccessGroups`.
+- Reply tags are ignored on this provider.
-- `messages.responsePrefix`, `messages.ackReaction`, `messages.ackReactionScope`.
+
+## Outbound send (text + media)
+- Uses active web listener; error if gateway not running.
+- Text chunking: 4k max per message.
+- Media:
+  - Image/video/audio/document supported.
+  - Audio sent as PTT; `audio/ogg` => `audio/ogg; codecs=opus`.
+  - Caption only on first media item.
+  - Media fetch supports HTTP(S) and local paths.
+  - Animated GIFs: WhatsApp expects MP4 with `gifPlayback: true` for inline looping.
+    - CLI: `clawdbot send --media <mp4> --gif-playback`
+    - Gateway: `send` params include `gifPlayback: true`
+
+## Media limits + optimization
+- Default cap: 5 MB (per media item).
+- Override: `agent.mediaMaxMb`.
+- Images are auto-optimized to JPEG under cap (resize + quality sweep).
+- Oversize media => error; media reply falls back to text warning.
+
+## Heartbeats
+- **Gateway heartbeat** logs connection health (`web.heartbeatSeconds`, default 60s).
+- **Agent heartbeat** is global (`agent.heartbeat.*`) and runs in the main session.
+  - Uses the configured heartbeat prompt (default: `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`) + `HEARTBEAT_OK` skip behavior.
+  - Delivery defaults to the last used provider (or configured target).
+
+## Reconnect behavior
+- Backoff policy: `web.reconnect`:
+  - `initialMs`, `maxMs`, `factor`, `jitter`, `maxAttempts`.
+- If maxAttempts reached, web monitoring stops (degraded).
+- Logged-out => stop and require re-link.
+
+## Config quick map
+- `whatsapp.dmPolicy` (DM policy: pairing/allowlist/open/disabled).
+- `whatsapp.allowFrom` (DM allowlist).
+- `whatsapp.accounts.<accountId>.*` (per-account settings + optional `authDir`).
+- `whatsapp.groupAllowFrom` (group sender allowlist).
+- `whatsapp.groupPolicy` (group policy).
+- `whatsapp.groups` (group allowlist + mention gating defaults; use `"*"` to allow all)
+- `routing.groupChat.mentionPatterns`
+- `routing.groupChat.historyLimit`
+- `messages.messagePrefix` (inbound prefix)
+- `messages.responsePrefix` (outbound prefix)
+- `agent.mediaMaxMb`
+- `agent.heartbeat.every`
+- `agent.heartbeat.model` (optional override)
+- `agent.heartbeat.target`
+- `agent.heartbeat.to`
+- `session.*` (scope, idle, store, mainKey)
+- `web.enabled` (disable provider startup when false)
+- `web.heartbeatSeconds`
+- `web.reconnect.*`
+
+## Logs + troubleshooting
+- Subsystems: `whatsapp/inbound`, `whatsapp/outbound`, `web-heartbeat`, `web-reconnect`.
+- Log file: `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` (configurable).
+- Troubleshooting guide: [`docs/troubleshooting.md`](/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)
+- [`src/web/monitor-inbox.test.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/web/monitor-inbox.test.ts) (inbound parsing + reply context)
+- [`src/web/outbound.test.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/web/outbound.test.ts) (send mapping + media)

docs/wizard.md

@@ -59,7 +59,7 @@ It does **not** install or change anything on the remote host.
 3) **Workspace**
    - Default `~/clawd` (configurable).
    - Seeds the workspace files needed for the agent bootstrap ritual.
-   - Full workspace layout + backup guide: [`docs/agent-workspace.md`](https://docs.clawd.bot/agent-workspace)
+   - Full workspace layout + backup guide: [`docs/agent-workspace.md`](/agent-workspace)
 
 4) **Gateway**
    - Port, bind, auth mode, tailscale exposure.
@@ -165,7 +165,7 @@ Sessions are stored under `~/.clawdbot/agents/<agentId>/sessions/`.
 
 ## Related docs
 
-- macOS app onboarding: [`docs/onboarding.md`](https://docs.clawd.bot/onboarding)
+- macOS app onboarding: [`docs/onboarding.md`](/onboarding)
-- Config reference: [`docs/configuration.md`](https://docs.clawd.bot/configuration)
+- Config reference: [`docs/configuration.md`](/configuration)
-- Providers: [`docs/whatsapp.md`](https://docs.clawd.bot/whatsapp), [`docs/telegram.md`](https://docs.clawd.bot/telegram), [`docs/discord.md`](https://docs.clawd.bot/discord), [`docs/signal.md`](https://docs.clawd.bot/signal), [`docs/imessage.md`](https://docs.clawd.bot/imessage)
+- Providers: [`docs/whatsapp.md`](/whatsapp), [`docs/telegram.md`](/telegram), [`docs/discord.md`](/discord), [`docs/signal.md`](/signal), [`docs/imessage.md`](/imessage)
-- Skills: [`docs/skills.md`](https://docs.clawd.bot/skills), [`docs/skills-config.md`](https://docs.clawd.bot/skills-config)
+- Skills: [`docs/skills.md`](/skills), [`docs/skills-config.md`](/skills-config)