@poolzin/pool-bot 2026.1.26 → 2026.1.30

package/docs/automation/cron-jobs.md

@@ -17,7 +17,7 @@ cron is the mechanism.
 
 ## TL;DR
 - Cron runs **inside the Gateway** (not inside the model).
-- Jobs persist under `~/.clawdbot/cron/` so restarts don’t lose schedules.
+- Jobs persist under `~/.poolbot/cron/` so restarts don’t lose schedules.
 - Two execution styles:
   - **Main session**: enqueue a system event, then run on the next heartbeat.
   - **Isolated**: run a dedicated agent turn in `cron:<jobId>`, optionally deliver output.
@@ -151,8 +151,8 @@ Prefixed targets like `telegram:...` / `telegram:group:...` are also accepted:
 - `telegram:group:-1001234567890:topic:123`
 
 ## Storage & history
-- Job store: `~/.clawdbot/cron/jobs.json` (Gateway-managed JSON).
-- Run history: `~/.clawdbot/cron/runs/<jobId>.jsonl` (JSONL, auto-pruned).
+- Job store: `~/.poolbot/cron/jobs.json` (Gateway-managed JSON).
+- Run history: `~/.poolbot/cron/runs/<jobId>.jsonl` (JSONL, auto-pruned).
 - Override store path: `cron.store` in config.
 
 ## Configuration
@@ -161,7 +161,7 @@ Prefixed targets like `telegram:...` / `telegram:group:...` are also accepted:
 {
   cron: {
     enabled: true, // default true
-    store: "~/.clawdbot/cron/jobs.json",
+    store: "~/.poolbot/cron/jobs.json",
     maxConcurrentRuns: 1 // default 1
   }
 }
@@ -175,7 +175,7 @@ Disable cron entirely:
 
 One-shot reminder (UTC ISO, auto-delete after success):
 ```bash
-clawdbot cron add \
+poolbot cron add \
   --name "Send reminder" \
   --at "2026-01-12T18:00:00Z" \
   --session main \
@@ -186,7 +186,7 @@ clawdbot cron add \
 
 One-shot reminder (main session, wake immediately):
 ```bash
-clawdbot cron add \
+poolbot cron add \
   --name "Calendar check" \
   --at "20m" \
   --session main \
@@ -196,7 +196,7 @@ clawdbot cron add \
 
 Recurring isolated job (deliver to WhatsApp):
 ```bash
-clawdbot cron add \
+poolbot cron add \
   --name "Morning status" \
   --cron "0 7 * * *" \
   --tz "America/Los_Angeles" \
@@ -209,7 +209,7 @@ clawdbot cron add \
 
 Recurring isolated job (deliver to a Telegram topic):
 ```bash
-clawdbot cron add \
+poolbot cron add \
   --name "Nightly summary (topic)" \
   --cron "0 22 * * *" \
   --tz "America/Los_Angeles" \
@@ -222,7 +222,7 @@ clawdbot cron add \
 
 Isolated job with model and thinking override:
 ```bash
-clawdbot cron add \
+poolbot cron add \
   --name "Deep analysis" \
   --cron "0 6 * * 1" \
   --tz "America/Los_Angeles" \
@@ -237,22 +237,22 @@ clawdbot cron add \
 Agent selection (multi-agent setups):
 ```bash
 # Pin a job to agent "ops" (falls back to default if that agent is missing)
-clawdbot cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
+poolbot cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
 
 # Switch or clear the agent on an existing job
-clawdbot cron edit <jobId> --agent ops
-clawdbot cron edit <jobId> --clear-agent
+poolbot cron edit <jobId> --agent ops
+poolbot cron edit <jobId> --clear-agent
 ```
 ```
 
 Manual run (debug):
 ```bash
-clawdbot cron run <jobId> --force
+poolbot cron run <jobId> --force
 ```
 
 Edit an existing job (patch fields):
 ```bash
-clawdbot cron edit <jobId> \
+poolbot cron edit <jobId> \
   --message "Updated prompt" \
   --model "opus" \
   --thinking low
@@ -260,18 +260,18 @@ clawdbot cron edit <jobId> \
 
 Run history:
 ```bash
-clawdbot cron runs --id <jobId> --limit 50
+poolbot cron runs --id <jobId> --limit 50
 ```
 
 Immediate system event without creating a job:
 ```bash
-clawdbot system event --mode now --text "Next heartbeat: check battery."
+poolbot system event --mode now --text "Next heartbeat: check battery."
 ```
 
 ## Gateway API surface
 - `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`
 - `cron.run` (force or due), `cron.runs`
-For immediate system events without a job, use [`clawdbot system event`](/cli/system).
+For immediate system events without a job, use [`poolbot system event`](/cli/system).
 
 ## Troubleshooting
 

package/docs/automation/cron-vs-heartbeat.md

@@ -95,7 +95,7 @@ Cron jobs run at **exact times** and can run in isolated sessions without affect
 ### Cron example: Daily morning briefing
 
 ```bash
-clawdbot cron add \
+poolbot cron add \
   --name "Morning briefing" \
   --cron "0 7 * * *" \
   --tz "America/New_York" \
@@ -112,7 +112,7 @@ This runs at exactly 7:00 AM New York time, uses Opus for quality, and delivers
 ### Cron example: One-shot reminder
 
 ```bash
-clawdbot cron add \
+poolbot cron add \
   --name "Meeting reminder" \
   --at "20m" \
   --session main \
@@ -168,13 +168,13 @@ The most efficient setup uses **both**:
 **Cron jobs** (precise timing):
 ```bash
 # Daily morning briefing at 7am
-clawdbot cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --deliver
+poolbot cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --deliver
 
 # Weekly project review on Mondays at 9am
-clawdbot cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus
+poolbot cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus
 
 # One-shot reminder
-clawdbot cron add --name "Call back" --at "2h" --session main --system-event "Call back the client" --wake now
+poolbot cron add --name "Call back" --at "2h" --session main --system-event "Call back the client" --wake now
 ```
 
 
@@ -201,7 +201,7 @@ For ad-hoc workflows, call Lobster directly.
 
 - Lobster runs as a **local subprocess** (`lobster` CLI) in tool mode and returns a **JSON envelope**.
 - If the tool returns `needs_approval`, you resume with a `resumeToken` and `approve` flag.
-- The tool is an **optional plugin**; you must allowlist `lobster` in `tools.allow`.
+- The tool is an **optional plugin**; enable it additively via `tools.alsoAllow: ["lobster"]` (recommended).
 - If you pass `lobsterPath`, it must be an **absolute path**.
 
 See [Lobster](/tools/lobster) for full usage and examples.
@@ -226,7 +226,7 @@ Use `--session main` with `--system-event` when you want:
 - No separate isolated run
 
 ```bash
-clawdbot cron add \
+poolbot cron add \
   --name "Check project" \
   --every "4h" \
   --session main \
@@ -243,7 +243,7 @@ Use `--session isolated` when you want:
 - History that doesn't clutter main session
 
 ```bash
-clawdbot cron add \
+poolbot cron add \
   --name "Deep analysis" \
   --cron "0 6 * * 0" \
   --session isolated \

package/docs/automation/gmail-pubsub.md

@@ -1,19 +1,19 @@
 ---
-summary: "Gmail Pub/Sub push wired into Clawdbot webhooks via gogcli"
+summary: "Gmail Pub/Sub push wired into Pool Bot webhooks via gogcli"
 read_when:
-  - Wiring Gmail inbox triggers to Clawdbot
+  - Wiring Gmail inbox triggers to Pool Bot
   - Setting up Pub/Sub push for agent wake
 ---
 
-# Gmail Pub/Sub -> Clawdbot
+# Gmail Pub/Sub -> Pool Bot
 
-Goal: Gmail watch -> Pub/Sub push -> `gog gmail watch serve` -> Clawdbot webhook.
+Goal: Gmail watch -> Pub/Sub push -> `gog gmail watch serve` -> Pool Bot webhook.
 
 ## Prereqs
 
 - `gcloud` installed and logged in ([install guide](https://docs.cloud.google.com/sdk/docs/install-sdk)).
 - `gog` (gogcli) installed and authorized for the Gmail account ([gogcli.sh](https://gogcli.sh/)).
-- Clawdbot hooks enabled (see [Webhooks](/automation/webhook)).
+- Pool Bot hooks enabled (see [Webhooks](/automation/webhook)).
 - `tailscale` logged in ([tailscale.com](https://tailscale.com/)). Supported setup uses Tailscale Funnel for the public HTTPS endpoint.
   Other tunnel services can work, but are DIY/unsupported and require manual wiring.
   Right now, Tailscale is what we support.
@@ -83,25 +83,27 @@ Notes:
 - Per-hook `model`/`thinking` in the mapping still overrides these defaults.
 - Fallback order: `hooks.gmail.model` → `agents.defaults.model.fallbacks` → primary (auth/rate-limit/timeouts).
 - If `agents.defaults.models` is set, the Gmail model must be in the allowlist.
+- Gmail hook content is wrapped with external-content safety boundaries by default.
+  To disable (dangerous), set `hooks.gmail.allowUnsafeExternalContent: true`.
 
 To customize payload handling further, add `hooks.mappings` or a JS/TS transform module
 under `hooks.transformsDir` (see [Webhooks](/automation/webhook)).
 
 ## Wizard (recommended)
 
-Use the Clawdbot helper to wire everything together (installs deps on macOS via brew):
+Use the Pool Bot helper to wire everything together (installs deps on macOS via brew):
 
 ```bash
-clawdbot webhooks gmail setup \
-  --account clawdbot@gmail.com
+poolbot webhooks gmail setup \
+  --account poolbot@gmail.com
 ```
 
 Defaults:
 - Uses Tailscale Funnel for the public push endpoint.
-- Writes `hooks.gmail` config for `clawdbot webhooks gmail run`.
+- Writes `hooks.gmail` config for `poolbot webhooks gmail run`.
 - Enables the Gmail hook preset (`hooks.presets: ["gmail"]`).
 
-Path note: when `tailscale.mode` is enabled, Clawdbot automatically sets
+Path note: when `tailscale.mode` is enabled, Pool Bot automatically sets
 `hooks.gmail.serve.path` to `/` and keeps the public path at
 `hooks.gmail.tailscale.path` (default `/gmail-pubsub`) because Tailscale
 strips the set-path prefix before proxying.
@@ -124,7 +126,7 @@ Gateway auto-start (recommended):
 Manual daemon (starts `gog gmail watch serve` + auto-renew):
 
 ```bash
-clawdbot webhooks gmail run
+poolbot webhooks gmail run
 ```
 
 ## One-time setup
@@ -162,7 +164,7 @@ gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
 
 ```bash
 gog gmail watch start \
-  --account clawdbot@gmail.com \
+  --account poolbot@gmail.com \
   --label INBOX \
   --topic projects/<project-id>/topics/gog-gmail-watch
 ```
@@ -175,7 +177,7 @@ Local example (shared token auth):
 
 ```bash
 gog gmail watch serve \
-  --account clawdbot@gmail.com \
+  --account poolbot@gmail.com \
   --bind 127.0.0.1 \
   --port 8788 \
   --path /gmail-pubsub \
@@ -188,10 +190,10 @@ gog gmail watch serve \
 
 Notes:
 - `--token` protects the push endpoint (`x-gog-token` or `?token=`).
-- `--hook-url` points to Clawdbot `/hooks/gmail` (mapped; isolated run + summary to main).
-- `--include-body` and `--max-bytes` control the body snippet sent to Clawdbot.
+- `--hook-url` points to Pool Bot `/hooks/gmail` (mapped; isolated run + summary to main).
+- `--include-body` and `--max-bytes` control the body snippet sent to Pool Bot.
 
-Recommended: `clawdbot webhooks gmail run` wraps the same flow and auto-renews the watch.
+Recommended: `poolbot webhooks gmail run` wraps the same flow and auto-renews the watch.
 
 ## Expose the handler (advanced, unsupported)
 
@@ -222,8 +224,8 @@ Send a message to the watched inbox:
 
 ```bash
 gog gmail send \
-  --account clawdbot@gmail.com \
-  --to clawdbot@gmail.com \
+  --account poolbot@gmail.com \
+  --to poolbot@gmail.com \
   --subject "watch test" \
   --body "ping"
 ```
@@ -231,8 +233,8 @@ gog gmail send \
 Check watch state and history:
 
 ```bash
-gog gmail watch status --account clawdbot@gmail.com
-gog gmail history --account clawdbot@gmail.com --since <historyId>
+gog gmail watch status --account poolbot@gmail.com
+gog gmail history --account poolbot@gmail.com --since <historyId>
 ```
 
 ## Troubleshooting
@@ -244,7 +246,7 @@ gog gmail history --account clawdbot@gmail.com --since <historyId>
 ## Cleanup
 
 ```bash
-gog gmail watch stop --account clawdbot@gmail.com
+gog gmail watch stop --account poolbot@gmail.com
 gcloud pubsub subscriptions delete gog-gmail-watch-push
 gcloud pubsub topics delete gog-gmail-watch
 ```

package/docs/automation/poll.md

@@ -16,19 +16,19 @@ read_when:
 
 ```bash
 # WhatsApp
-clawdbot message poll --target +15555550123 \
+poolbot message poll --target +15555550123 \
   --poll-question "Lunch today?" --poll-option "Yes" --poll-option "No" --poll-option "Maybe"
-clawdbot message poll --target 123456789@g.us \
+poolbot message poll --target 123456789@g.us \
   --poll-question "Meeting time?" --poll-option "10am" --poll-option "2pm" --poll-option "4pm" --poll-multi
 
 # Discord
-clawdbot message poll --channel discord --target channel:123456789 \
+poolbot message poll --channel discord --target channel:123456789 \
   --poll-question "Snack?" --poll-option "Pizza" --poll-option "Sushi"
-clawdbot message poll --channel discord --target channel:123456789 \
+poolbot message poll --channel discord --target channel:123456789 \
   --poll-question "Plan?" --poll-option "A" --poll-option "B" --poll-duration-hours 48
 
 # MS Teams
-clawdbot message poll --channel msteams --target conversation:19:abc@thread.tacv2 \
+poolbot message poll --channel msteams --target conversation:19:abc@thread.tacv2 \
   --poll-question "Lunch?" --poll-option "Pizza" --poll-option "Sushi"
 ```
 
@@ -53,11 +53,11 @@ Params:
 ## Channel differences
 - WhatsApp: 2-12 options, `maxSelections` must be within option count, ignores `durationHours`.
 - Discord: 2-10 options, `durationHours` clamped to 1-768 hours (default 24). `maxSelections > 1` enables multi-select; Discord does not support a strict selection count.
-- MS Teams: Adaptive Card polls (Clawdbot-managed). No native poll API; `durationHours` is ignored.
+- MS Teams: Adaptive Card polls (Pool Bot-managed). No native poll API; `durationHours` is ignored.
 
 ## Agent tool (Message)
 Use the `message` tool with `poll` action (`to`, `pollQuestion`, `pollOption`, optional `pollMulti`, `pollDurationHours`, `channel`).
 
 Note: Discord has no “pick exactly N” mode; `pollMulti` maps to multi-select.
 Teams polls are rendered as Adaptive Cards and require the gateway to stay online
-to record votes in `~/.clawdbot/msteams-polls.json`.
+to record votes in `~/.poolbot/msteams-polls.json`.

package/docs/automation/webhook.md

@@ -2,7 +2,7 @@
 summary: "Webhook ingress for wake and isolated agent runs"
 read_when:
   - Adding or changing webhook endpoints
-  - Wiring external systems into Clawdbot
+  - Wiring external systems into Pool Bot
 ---
 
 # Webhooks
@@ -27,10 +27,10 @@ Notes:
 
 ## Auth
 
-Every request must include the hook token:
-- `Authorization: Bearer <token>`
-- or `x-clawdbot-token: <token>`
-- or `?token=<token>`
+Every request must include the hook token. Prefer headers:
+- `Authorization: Bearer <token>` (recommended)
+- `x-poolbot-token: <token>`
+- `?token=<token>` (deprecated; logs a warning and will be removed in a future major release)
 
 ## Endpoints
 
@@ -96,7 +96,9 @@ Mapping options (summary):
 - TS transforms require a TS loader (e.g. `bun` or `tsx`) or precompiled `.js` at runtime.
 - Set `deliver: true` + `channel`/`to` on mappings to route replies to a chat surface
   (`channel` defaults to `last` and falls back to WhatsApp).
-- `clawdbot webhooks gmail setup` writes `hooks.gmail` config for `clawdbot webhooks gmail run`.
+- `allowUnsafeExternalContent: true` disables the external content safety wrapper for that hook
+  (dangerous; only for trusted internal sources).
+- `poolbot webhooks gmail setup` writes `hooks.gmail` config for `poolbot webhooks gmail run`.
 See [Gmail Pub/Sub](/automation/gmail-pubsub) for the full Gmail watch flow.
 
 ## Responses
@@ -118,7 +120,7 @@ curl -X POST http://127.0.0.1:18789/hooks/wake \
 
 ```bash
 curl -X POST http://127.0.0.1:18789/hooks/agent \
-  -H 'x-clawdbot-token: SECRET' \
+  -H 'x-poolbot-token: SECRET' \
   -H 'Content-Type: application/json' \
   -d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'
 ```
@@ -129,7 +131,7 @@ Add `model` to the agent payload (or mapping) to override the model for that run
 
 ```bash
 curl -X POST http://127.0.0.1:18789/hooks/agent \
-  -H 'x-clawdbot-token: SECRET' \
+  -H 'x-poolbot-token: SECRET' \
   -H 'Content-Type: application/json' \
   -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.2-mini"}'
 ```
@@ -148,3 +150,6 @@ curl -X POST http://127.0.0.1:18789/hooks/gmail \
 - Keep hook endpoints behind loopback, tailnet, or trusted reverse proxy.
 - Use a dedicated hook token; do not reuse gateway auth tokens.
 - Avoid including sensitive raw payloads in webhook logs.
+- Hook payloads are treated as untrusted and wrapped with safety boundaries by default.
+  If you must disable this for a specific hook, set `allowUnsafeExternalContent: true`
+  in that hook's mapping (dangerous).

package/docs/bedrock.md

@@ -1,12 +1,12 @@
 ---
-summary: "Use Amazon Bedrock (Converse API) models with Clawdbot"
+summary: "Use Amazon Bedrock (Converse API) models with Pool Bot"
 read_when:
-  - You want to use Amazon Bedrock models with Clawdbot
+  - You want to use Amazon Bedrock models with Pool Bot
   - You need AWS credential/region setup for model calls
 ---
 # Amazon Bedrock
 
-Clawdbot can use **Amazon Bedrock** models via pi‑ai’s **Bedrock Converse**
+Pool Bot can use **Amazon Bedrock** models via pi‑ai’s **Bedrock Converse**
 streaming provider. Bedrock auth uses the **AWS SDK default credential chain**,
 not an API key.
 
@@ -19,7 +19,7 @@ not an API key.
 
 ## Automatic model discovery
 
-If AWS credentials are detected, Clawdbot can automatically discover Bedrock
+If AWS credentials are detected, Pool Bot can automatically discover Bedrock
 models that support **streaming** and **text output**. Discovery uses
 `bedrock:ListFoundationModels` and is cached (default: 1 hour).
 
@@ -97,9 +97,9 @@ export AWS_BEARER_TOKEN_BEDROCK="..."
 
 ## EC2 Instance Roles
 
-When running Clawdbot on an EC2 instance with an IAM role attached, the AWS SDK
+When running Pool Bot on an EC2 instance with an IAM role attached, the AWS SDK
 will automatically use the instance metadata service (IMDS) for authentication.
-However, Clawdbot's credential detection currently only checks for environment
+However, Pool Bot's credential detection currently only checks for environment
 variables, not IMDS credentials.
 
 **Workaround:** Set `AWS_PROFILE=default` to signal that AWS credentials are
@@ -146,8 +146,8 @@ aws ec2 associate-iam-instance-profile \
   --iam-instance-profile Name=EC2-Bedrock-Access
 
 # 3. On the EC2 instance, enable discovery
-clawdbot config set models.bedrockDiscovery.enabled true
-clawdbot config set models.bedrockDiscovery.region us-east-1
+poolbot config set models.bedrockDiscovery.enabled true
+poolbot config set models.bedrockDiscovery.region us-east-1
 
 # 4. Set the workaround env vars
 echo 'export AWS_PROFILE=default' >> ~/.bashrc
@@ -155,7 +155,7 @@ echo 'export AWS_REGION=us-east-1' >> ~/.bashrc
 source ~/.bashrc
 
 # 5. Verify models are discovered
-clawdbot models list
+poolbot models list
 ```
 
 ## Notes
@@ -163,7 +163,7 @@ clawdbot models list
 - Bedrock requires **model access** enabled in your AWS account/region.
 - Automatic discovery needs the `bedrock:ListFoundationModels` permission.
 - If you use profiles, set `AWS_PROFILE` on the gateway host.
-- Clawdbot surfaces the credential source in this order: `AWS_BEARER_TOKEN_BEDROCK`,
+- Pool Bot surfaces the credential source in this order: `AWS_BEARER_TOKEN_BEDROCK`,
   then `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`, then `AWS_PROFILE`, then the
   default AWS SDK chain.
 - Reasoning support depends on the model; check the Bedrock model card for

package/docs/brave-search.md

@@ -7,7 +7,7 @@ read_when:
 
 # Brave Search API
 
-Clawdbot uses Brave Search as the default provider for `web_search`.
+Pool Bot uses Brave Search as the default provider for `web_search`.
 
 ## Get an API key
 

package/docs/broadcast-groups.md

@@ -17,7 +17,7 @@ Broadcast Groups enable multiple agents to process and respond to the same messa
 
 Current scope: **WhatsApp only** (web channel).
 
-Broadcast groups are evaluated after channel allowlists and group activation rules. In WhatsApp groups, this means broadcasts happen when Clawdbot would normally reply (for example: on mention, depending on your group settings).
+Broadcast groups are evaluated after channel allowlists and group activation rules. In WhatsApp groups, this means broadcasts happen when Pool Bot would normally reply (for example: on mention, depending on your group settings).
 
 ## Use Cases
 
@@ -76,7 +76,7 @@ Add a top-level `broadcast` section (next to `bindings`). Keys are WhatsApp peer
 }
 ```
 
-**Result:** When Clawdbot would reply in this chat, it will run all three agents.
+**Result:** When Pool Bot would reply in this chat, it will run all three agents.
 
 ### Processing Strategy
 
@@ -296,7 +296,7 @@ Broadcast groups work alongside existing routing:
 
 **Debug:**
 ```bash
-tail -f ~/.clawdbot/logs/gateway.log | grep broadcast
+tail -f ~/.poolbot/logs/gateway.log | grep broadcast
 ```
 
 ### Only One Agent Responding
@@ -368,7 +368,7 @@ tail -f ~/.clawdbot/logs/gateway.log | grep broadcast
 ### Config Schema
 
 ```typescript
-interface ClawdbotConfig {
+interface Pool BotConfig {
   broadcast?: {
     strategy?: "parallel" | "sequential";
     [peerId: string]: string[];

package/docs/channels/bluebubbles.md

@@ -12,7 +12,7 @@ Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. **R
 ## Overview
 - Runs on macOS via the BlueBubbles helper app ([bluebubbles.app](https://bluebubbles.app)).
 - Recommended/tested: macOS Sequoia (15). macOS Tahoe (26) works; edit is currently broken on Tahoe, and group icon updates may report success but not sync.
-- Clawdbot talks to it through its REST API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`).
+- Pool Bot talks to it through its REST API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`).
 - Incoming messages arrive via webhooks; outgoing replies, typing indicators, read receipts, and tapbacks are REST calls.
 - Attachments and stickers are ingested as inbound media (and surfaced to the agent when possible).
 - Pairing/allowlist works the same way as other channels (`/start/pairing` etc) with `channels.bluebubbles.allowFrom` + pairing codes.
@@ -22,7 +22,7 @@ Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. **R
 ## Quick start
 1. Install the BlueBubbles server on your Mac (follow the instructions at [bluebubbles.app/install](https://bluebubbles.app/install)).
 2. In the BlueBubbles config, enable the web API and set a password.
-3. Run `clawdbot onboard` and select BlueBubbles, or configure manually:
+3. Run `poolbot onboard` and select BlueBubbles, or configure manually:
    ```json5
    {
      channels: {
@@ -41,7 +41,7 @@ Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. **R
 ## Onboarding
 BlueBubbles is available in the interactive setup wizard:
 ```
-clawdbot onboard
+poolbot onboard
 ```
 
 The wizard prompts for:
@@ -53,7 +53,7 @@ The wizard prompts for:
 
 You can also add BlueBubbles via CLI:
 ```
-clawdbot channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>
+poolbot channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>
 ```
 
 ## Access control (DMs + groups)
@@ -61,8 +61,8 @@ DMs:
 - Default: `channels.bluebubbles.dmPolicy = "pairing"`.
 - Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
 - Approve via:
-  - `clawdbot pairing list bluebubbles`
-  - `clawdbot pairing approve bluebubbles <CODE>`
+  - `poolbot pairing list bluebubbles`
+  - `poolbot pairing approve bluebubbles <CODE>`
 - Pairing is the default token exchange. Details: [Pairing](/start/pairing)
 
 Groups:
@@ -99,7 +99,7 @@ Per-group configuration:
 ## Typing + read receipts
 - **Typing indicators**: Sent automatically before and during response generation.
 - **Read receipts**: Controlled by `channels.bluebubbles.sendReadReceipts` (default: `true`).
-- **Typing indicators**: Clawdbot sends typing start events; BlueBubbles clears typing automatically on send or timeout (manual stop via DELETE is unreliable).
+- **Typing indicators**: Pool Bot sends typing start events; BlueBubbles clears typing automatically on send or timeout (manual stop via DELETE is unreliable).
 
 ```json5
 {
@@ -151,7 +151,7 @@ Available actions:
   - Voice memos: set `asVoice: true` with **MP3** or **CAF** audio to send as an iMessage voice message. BlueBubbles converts MP3 → CAF when sending voice memos.
 
 ### Message IDs (short vs full)
-Clawdbot may surface *short* message IDs (e.g., `1`, `2`) to save tokens.
+Pool Bot may surface *short* message IDs (e.g., `1`, `2`) to save tokens.
 - `MessageSid` / `ReplyToId` can be short IDs.
 - `MessageSidFull` / `ReplyToIdFull` contain the provider full IDs.
 - Short IDs are in-memory; they can expire on restart or cache eviction.
@@ -213,20 +213,21 @@ Prefer `chat_guid` for stable routing:
 - `chat_id:123`
 - `chat_identifier:...`
 - Direct handles: `+15555550123`, `user@example.com`
-  - If a direct handle does not have an existing DM chat, Clawdbot will create one via `POST /api/v1/chat/new`. This requires the BlueBubbles Private API to be enabled.
+  - If a direct handle does not have an existing DM chat, Pool Bot will create one via `POST /api/v1/chat/new`. This requires the BlueBubbles Private API to be enabled.
 
 ## Security
 - Webhook requests are authenticated by comparing `guid`/`password` query params or headers against `channels.bluebubbles.password`. Requests from `localhost` are also accepted.
 - Keep the API password and webhook endpoint secret (treat them like credentials).
+- Localhost trust means a same-host reverse proxy can unintentionally bypass the password. If you proxy the gateway, require auth at the proxy and configure `gateway.trustedProxies`. See [Gateway security](/gateway/security#reverse-proxy-configuration).
 - Enable HTTPS + firewall rules on the BlueBubbles server if exposing it outside your LAN.
 
 ## Troubleshooting
 - If typing/read events stop working, check the BlueBubbles webhook logs and verify the gateway path matches `channels.bluebubbles.webhookPath`.
-- Pairing codes expire after one hour; use `clawdbot pairing list bluebubbles` and `clawdbot pairing approve bluebubbles <code>`.
+- Pairing codes expire after one hour; use `poolbot pairing list bluebubbles` and `poolbot pairing approve bluebubbles <code>`.
 - Reactions require the BlueBubbles private API (`POST /api/v1/message/react`); ensure the server version exposes it.
 - Edit/unsend require macOS 13+ and a compatible BlueBubbles server version. On macOS 26 (Tahoe), edit is currently broken due to private API changes.
 - Group icon updates can be flaky on macOS 26 (Tahoe): the API may return success but the new icon does not sync.
-- Clawdbot auto-hides known-broken actions based on the BlueBubbles server's macOS version. If edit still appears on macOS 26 (Tahoe), disable it manually with `channels.bluebubbles.actions.edit=false`.
-- For status/health info: `clawdbot status --all` or `clawdbot status --deep`.
+- Pool Bot auto-hides known-broken actions based on the BlueBubbles server's macOS version. If edit still appears on macOS 26 (Tahoe), disable it manually with `channels.bluebubbles.actions.edit=false`.
+- For status/health info: `poolbot status --all` or `poolbot status --deep`.
 
 For general channel workflow reference, see [Channels](/channels) and the [Plugins](/plugins) guide.