@poolzin/pool-bot 2026.1.26 → 2026.1.29

package/docs/gateway/discovery.md

@@ -7,12 +7,12 @@ read_when:
 ---
 # Discovery & transports
 
-Clawdbot has two distinct problems that look similar on the surface:
+Pool Bot has two distinct problems that look similar on the surface:
 
 1) **Operator remote control**: the macOS menu bar app controlling a gateway running elsewhere.
 2) **Node pairing**: iOS/Android (and future nodes) finding a gateway and pairing securely.
 
-The design goal is to keep all network discovery/advertising in the **Node Gateway** (`clawd` / `clawdbot gateway`) and keep clients (mac app, iOS) as consumers.
+The design goal is to keep all network discovery/advertising in the **Node Gateway** (`clawd` / `poolbot gateway`) and keep clients (mac app, iOS) as consumers.
 
 ## Terms
 
@@ -52,7 +52,7 @@ Troubleshooting and beacon details: [Bonjour](/gateway/bonjour).
 #### Service beacon details
 
 - Service types:
-  - `_clawdbot-gw._tcp` (gateway transport beacon)
+  - `_poolbot-gw._tcp` (gateway transport beacon)
 - TXT keys (non-secret):
   - `role=gateway`
   - `lanHost=<hostname>.local`
@@ -60,13 +60,13 @@ Troubleshooting and beacon details: [Bonjour](/gateway/bonjour).
   - `gatewayPort=18789` (Gateway WS + HTTP)
   - `gatewayTls=1` (only when TLS is enabled)
   - `gatewayTlsSha256=<sha256>` (only when TLS is enabled and fingerprint is available)
-  - `canvasPort=18793` (default canvas host port; serves `/__clawdbot__/canvas/`)
-  - `cliPath=<path>` (optional; absolute path to a runnable `clawdbot` entrypoint or binary)
+  - `canvasPort=18793` (default canvas host port; serves `/__poolbot__/canvas/`)
+  - `cliPath=<path>` (optional; absolute path to a runnable `poolbot` entrypoint or binary)
   - `tailnetDns=<magicdns>` (optional hint; auto-detected when Tailscale is available)
 
 Disable/override:
 - `CLAWDBOT_DISABLE_BONJOUR=1` disables advertising.
-- `gateway.bind` in `~/.clawdbot/clawdbot.json` controls the Gateway bind mode.
+- `gateway.bind` in `~/.poolbot/poolbot.json` controls the Gateway bind mode.
 - `CLAWDBOT_SSH_PORT` overrides the SSH port advertised in TXT (defaults to 22).
 - `CLAWDBOT_TAILNET_DNS` publishes a `tailnetDns` hint (MagicDNS).
 - `CLAWDBOT_CLI_PATH` overrides the advertised CLI path.

package/docs/gateway/doctor.md

@@ -6,44 +6,44 @@ read_when:
 ---
 # Doctor
 
-`clawdbot doctor` is the repair + migration tool for Clawdbot. It fixes stale
+`poolbot doctor` is the repair + migration tool for Pool Bot. It fixes stale
 config/state, checks health, and provides actionable repair steps.
 
 ## Quick start
 
 ```bash
-clawdbot doctor
+poolbot doctor
 ```
 
 ### Headless / automation
 
 ```bash
-clawdbot doctor --yes
+poolbot doctor --yes
 ```
 
 Accept defaults without prompting (including restart/service/sandbox repair steps when applicable).
 
 ```bash
-clawdbot doctor --repair
+poolbot doctor --repair
 ```
 
 Apply recommended repairs without prompting (repairs + restarts where safe).
 
 ```bash
-clawdbot doctor --repair --force
+poolbot doctor --repair --force
 ```
 
 Apply aggressive repairs too (overwrites custom supervisor configs).
 
 ```bash
-clawdbot doctor --non-interactive
+poolbot doctor --non-interactive
 ```
 
 Run without prompts and only apply safe migrations (config normalization + on-disk state moves). Skips restart/service/sandbox actions that require human confirmation.
 Legacy state migrations run automatically when detected.
 
 ```bash
-clawdbot doctor --deep
+poolbot doctor --deep
 ```
 
 Scan system services for extra gateway installs (launchd/systemd/schtasks).
@@ -51,7 +51,7 @@ Scan system services for extra gateway installs (launchd/systemd/schtasks).
 If you want to review changes before writing, open the config file first:
 
 ```bash
-cat ~/.clawdbot/clawdbot.json
+cat ~/.poolbot/poolbot.json
 ```
 
 ## What it does (summary)
@@ -65,7 +65,7 @@ cat ~/.clawdbot/clawdbot.json
 - State integrity and permissions checks (sessions, transcripts, state dir).
 - Config file permission checks (chmod 600) when running locally.
 - Model auth health: checks OAuth expiry, can refresh expiring tokens, and reports auth-profile cooldown/disabled states.
-- Extra workspace dir detection (`~/clawdbot`).
+- Extra workspace dir detection (`~/poolbot`).
 - Sandbox image repair when sandboxing is enabled.
 - Legacy service migration and extra gateway detection.
 - Gateway runtime checks (service installed but not running; cached launchd label).
@@ -92,12 +92,12 @@ schema.
 
 ### 2) Legacy config key migrations
 When the config contains deprecated keys, other commands refuse to run and ask
-you to run `clawdbot doctor`.
+you to run `poolbot doctor`.
 
 Doctor will:
 - Explain which legacy keys were found.
 - Show the migration it applied.
-- Rewrite `~/.clawdbot/clawdbot.json` with the updated schema.
+- Rewrite `~/.poolbot/poolbot.json` with the updated schema.
 
 The Gateway also auto-runs doctor migrations on startup when it detects a
 legacy config format, so stale configs are repaired without manual intervention.
@@ -127,18 +127,18 @@ remove the override and restore per-model API routing + costs.
 ### 3) Legacy state migrations (disk layout)
 Doctor can migrate older on-disk layouts into the current structure:
 - Sessions store + transcripts:
-  - from `~/.clawdbot/sessions/` to `~/.clawdbot/agents/<agentId>/sessions/`
+  - from `~/.poolbot/sessions/` to `~/.poolbot/agents/<agentId>/sessions/`
 - Agent dir:
-  - from `~/.clawdbot/agent/` to `~/.clawdbot/agents/<agentId>/agent/`
+  - from `~/.poolbot/agent/` to `~/.poolbot/agents/<agentId>/agent/`
 - WhatsApp auth state (Baileys):
-  - from legacy `~/.clawdbot/credentials/*.json` (except `oauth.json`)
-  - to `~/.clawdbot/credentials/whatsapp/<accountId>/...` (default account id: `default`)
+  - from legacy `~/.poolbot/credentials/*.json` (except `oauth.json`)
+  - to `~/.poolbot/credentials/whatsapp/<accountId>/...` (default account id: `default`)
 
 These migrations are best-effort and idempotent; doctor will emit warnings when
 it leaves any legacy folders behind as backups. The Gateway/CLI also auto-migrates
 the legacy sessions + agent dir on startup so history/auth/models land in the
 per-agent path without a manual doctor run. WhatsApp auth is intentionally only
-migrated via `clawdbot doctor`.
+migrated via `poolbot doctor`.
 
 ### 4) State integrity checks (session persistence, routing, and safety)
 The state directory is the operational brainstem. If it vanishes, you lose
@@ -155,12 +155,12 @@ Doctor checks:
   transcript files.
 - **Main session “1-line JSONL”**: flags when the main transcript has only one
   line (history is not accumulating).
-- **Multiple state dirs**: warns when multiple `~/.clawdbot` folders exist across
+- **Multiple state dirs**: warns when multiple `~/.poolbot` folders exist across
   home directories or when `CLAWDBOT_STATE_DIR` points elsewhere (history can
   split between installs).
 - **Remote mode reminder**: if `gateway.mode=remote`, doctor reminds you to run
   it on the remote host (the state lives there).
-- **Config file permissions**: warns if `~/.clawdbot/clawdbot.json` is
+- **Config file permissions**: warns if `~/.poolbot/poolbot.json` is
   group/world readable and offers to tighten to `600`.
 
 ### 5) Model auth health (OAuth expiry)
@@ -184,9 +184,9 @@ switch to legacy names if the current image is missing.
 
 ### 8) Gateway service migrations and cleanup hints
 Doctor detects legacy gateway services (launchd/systemd/schtasks) and
-offers to remove them and install the Clawdbot service using the current gateway
+offers to remove them and install the Pool Bot service using the current gateway
 port. It can also scan for extra gateway-like services and print cleanup hints.
-Profile-named Clawdbot gateway services are considered first-class and are not
+Profile-named Pool Bot gateway services are considered first-class and are not
 flagged as "extra."
 
 ### 9) Security warnings
@@ -203,7 +203,7 @@ workspace.
 
 ### 12) Gateway auth checks (local token)
 Doctor warns when `gateway.auth` is missing on a local gateway and offers to
-generate a token. Use `clawdbot doctor --generate-gateway-token` to force token
+generate a token. Use `poolbot doctor --generate-gateway-token` to force token
 creation in automation.
 
 ### 13) Gateway health check + restart
@@ -221,11 +221,11 @@ restart delay). When it finds a mismatch, it recommends an update and can
 rewrite the service file/task to the current defaults.
 
 Notes:
-- `clawdbot doctor` prompts before rewriting supervisor config.
-- `clawdbot doctor --yes` accepts the default repair prompts.
-- `clawdbot doctor --repair` applies recommended fixes without prompts.
-- `clawdbot doctor --repair --force` overwrites custom supervisor configs.
-- You can always force a full rewrite via `clawdbot gateway install --force`.
+- `poolbot doctor` prompts before rewriting supervisor config.
+- `poolbot doctor --yes` accepts the default repair prompts.
+- `poolbot doctor --repair` applies recommended fixes without prompts.
+- `poolbot doctor --repair --force` overwrites custom supervisor configs.
+- You can always force a full rewrite via `poolbot gateway install --force`.
 
 ### 16) Gateway runtime + port diagnostics
 Doctor inspects the service runtime (PID, last exit status) and warns when the

package/docs/gateway/gateway-lock.md

@@ -24,5 +24,5 @@ Last updated: 2025-12-11
 - Other bind failures surface as `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")`.
 
 ## Operational notes
-- If the port is occupied by *another* process, the error is the same; free the port or choose another with `clawdbot gateway --port <port>`.
+- If the port is occupied by *another* process, the error is the same; free the port or choose another with `poolbot gateway --port <port>`.
 - The macOS app still maintains its own lightweight PID guard before spawning the gateway; the runtime lock is enforced by the WebSocket bind.

package/docs/gateway/health.md

@@ -8,22 +8,22 @@ read_when:
 Short guide to verify channel connectivity without guessing.
 
 ## Quick checks
-- `clawdbot status` — local summary: gateway reachability/mode, update hint, linked channel auth age, sessions + recent activity.
-- `clawdbot status --all` — full local diagnosis (read-only, color, safe to paste for debugging).
-- `clawdbot status --deep` — also probes the running Gateway (per-channel probes when supported).
-- `clawdbot health --json` — asks the running Gateway for a full health snapshot (WS-only; no direct Baileys socket).
+- `poolbot status` — local summary: gateway reachability/mode, update hint, linked channel auth age, sessions + recent activity.
+- `poolbot status --all` — full local diagnosis (read-only, color, safe to paste for debugging).
+- `poolbot status --deep` — also probes the running Gateway (per-channel probes when supported).
+- `poolbot health --json` — asks the running Gateway for a full health snapshot (WS-only; no direct Baileys socket).
 - Send `/status` as a standalone message in WhatsApp/WebChat to get a status reply without invoking the agent.
-- Logs: tail `/tmp/clawdbot/clawdbot-*.log` and filter for `web-heartbeat`, `web-reconnect`, `web-auto-reply`, `web-inbound`.
+- Logs: tail `/tmp/poolbot/poolbot-*.log` and filter for `web-heartbeat`, `web-reconnect`, `web-auto-reply`, `web-inbound`.
 
 ## Deep diagnostics
-- Creds on disk: `ls -l ~/.clawdbot/credentials/whatsapp/<accountId>/creds.json` (mtime should be recent).
-- Session store: `ls -l ~/.clawdbot/agents/<agentId>/sessions/sessions.json` (path can be overridden in config). Count and recent recipients are surfaced via `status`.
-- Relink flow: `clawdbot channels logout && clawdbot channels login --verbose` when status codes 409–515 or `loggedOut` appear in logs. (Note: the QR login flow auto-restarts once for status 515 after pairing.)
+- Creds on disk: `ls -l ~/.poolbot/credentials/whatsapp/<accountId>/creds.json` (mtime should be recent).
+- Session store: `ls -l ~/.poolbot/agents/<agentId>/sessions/sessions.json` (path can be overridden in config). Count and recent recipients are surfaced via `status`.
+- Relink flow: `poolbot channels logout && poolbot channels login --verbose` when status codes 409–515 or `loggedOut` appear in logs. (Note: the QR login flow auto-restarts once for status 515 after pairing.)
 
 ## When something fails
-- `logged out` or status 409–515 → relink with `clawdbot channels logout` then `clawdbot channels login`.
-- Gateway unreachable → start it: `clawdbot gateway --port 18789` (use `--force` if the port is busy).
+- `logged out` or status 409–515 → relink with `poolbot channels logout` then `poolbot channels login`.
+- Gateway unreachable → start it: `poolbot gateway --port 18789` (use `--force` if the port is busy).
 - No inbound messages → confirm linked phone is online and the sender is allowed (`channels.whatsapp.allowFrom`); for group chats, ensure allowlist + mention rules match (`channels.whatsapp.groups`, `agents.list[].groupChat.mentionPatterns`).
 
 ## Dedicated "health" command
-`clawdbot health --json` asks the running Gateway for its health snapshot (no direct channel sockets from the CLI). It reports linked creds/auth age when available, per-channel probe summaries, session-store summary, and a probe duration. It exits non-zero if the Gateway is unreachable or the probe fails/timeouts. Use `--timeout <ms>` to override the 10s default.
+`poolbot health --json` asks the running Gateway for its health snapshot (no direct channel sockets from the CLI). It reports linked creds/auth age when available, per-channel probe summaries, session-store summary, and a probe duration. It exits non-zero if the Gateway is unreachable or the probe fails/timeouts. Use `--timeout <ms>` to override the 10s default.

package/docs/gateway/heartbeat.md

@@ -62,7 +62,7 @@ stats” or “verify gateway health”), set `agents.defaults.heartbeat.prompt`
 ## Response contract
 
 - If nothing needs attention, reply with **`HEARTBEAT_OK`**.
-- During heartbeat runs, Clawdbot treats `HEARTBEAT_OK` as an ack when it appears
+- During heartbeat runs, Pool Bot treats `HEARTBEAT_OK` as an ack when it appears
   at the **start or end** of the reply. The token is stripped and the reply is
   dropped if the remaining content is **≤ `ackMaxChars`** (default: 300).
 - If `HEARTBEAT_OK` appears in the **middle** of a reply, it is not treated
@@ -140,7 +140,7 @@ Example: two agents, only the second agent runs heartbeats.
 - `includeReasoning`: when enabled, also deliver the separate `Reasoning:` message when available (same shape as `/reasoning on`).
 - `session`: optional session key for heartbeat runs.
   - `main` (default): agent main session.
-  - Explicit session key (copy from `clawdbot sessions --json` or the [sessions CLI](/cli/sessions)).
+  - Explicit session key (copy from `poolbot sessions --json` or the [sessions CLI](/cli/sessions)).
   - Session key formats: see [Sessions](/concepts/session) and [Groups](/concepts/groups).
 - `target`:
   - `last` (default): deliver to the last used external channel.
@@ -194,7 +194,7 @@ Precedence: per-account → per-channel → channel defaults → built-in defaul
 - `showAlerts`: sends the alert content when the model returns a non-OK reply.
 - `useIndicator`: emits indicator events for UI status surfaces.
 
-If **all three** are false, Clawdbot skips the heartbeat run entirely (no model call).
+If **all three** are false, Pool Bot skips the heartbeat run entirely (no model call).
 
 ### Per-channel vs per-account examples
 
@@ -233,7 +233,7 @@ agent to read it. Think of it as your “heartbeat checklist”: small, stable,
 safe to include every 30 minutes.
 
 If `HEARTBEAT.md` exists but is effectively empty (only blank lines and markdown
-headers like `# Heading`), Clawdbot skips the heartbeat run to save API calls.
+headers like `# Heading`), Pool Bot skips the heartbeat run to save API calls.
 If the file is missing, the heartbeat still runs and the model decides what to do.
 
 Keep it tiny (short checklist or reminders) to avoid prompt bloat.
@@ -269,7 +269,7 @@ Safety note: don’t put secrets (API keys, phone numbers, private tokens) into
 You can enqueue a system event and trigger an immediate heartbeat with:
 
 ```bash
-clawdbot system event --text "Check for urgent follow-ups" --mode now
+poolbot system event --text "Check for urgent follow-ups" --mode now
 ```
 
 If multiple agents have `heartbeat` configured, a manual wake runs each of those

package/docs/gateway/index.md

@@ -9,20 +9,20 @@ Last updated: 2025-12-09
 
 ## What it is
 - The always-on process that owns the single Baileys/Telegram connection and the control/event plane.
-- Replaces the legacy `gateway` command. CLI entry point: `clawdbot gateway`.
+- Replaces the legacy `gateway` command. CLI entry point: `poolbot gateway`.
 - Runs until stopped; exits non-zero on fatal errors so the supervisor restarts it.
 
 ## How to run (local)
 ```bash
-clawdbot gateway --port 18789
+poolbot gateway --port 18789
 # for full debug/trace logs in stdio:
-clawdbot gateway --port 18789 --verbose
+poolbot gateway --port 18789 --verbose
 # if the port is busy, terminate listeners then start:
-clawdbot gateway --force
+poolbot gateway --force
 # dev loop (auto-reload on TS changes):
 pnpm gateway:watch
 ```
-- Config hot reload watches `~/.clawdbot/clawdbot.json` (or `CLAWDBOT_CONFIG_PATH`).
+- Config hot reload watches `~/.poolbot/poolbot.json` (or `CLAWDBOT_CONFIG_PATH`).
   - Default mode: `gateway.reload.mode="hybrid"` (hot-apply safe changes, restart on critical).
   - Hot reload uses in-process restart via **SIGUSR1** when needed.
   - Disable with `gateway.reload.mode="off"`.
@@ -31,13 +31,13 @@ pnpm gateway:watch
   - OpenAI Chat Completions (HTTP): [`/v1/chat/completions`](/gateway/openai-http-api).
   - OpenResponses (HTTP): [`/v1/responses`](/gateway/openresponses-http-api).
   - Tools Invoke (HTTP): [`/tools/invoke`](/gateway/tools-invoke-http-api).
-- Starts a Canvas file server by default on `canvasHost.port` (default `18793`), serving `http://<gateway-host>:18793/__clawdbot__/canvas/` from `~/clawd/canvas`. Disable with `canvasHost.enabled=false` or `CLAWDBOT_SKIP_CANVAS_HOST=1`.
+- Starts a Canvas file server by default on `canvasHost.port` (default `18793`), serving `http://<gateway-host>:18793/__poolbot__/canvas/` from `~/clawd/canvas`. Disable with `canvasHost.enabled=false` or `CLAWDBOT_SKIP_CANVAS_HOST=1`.
 - Logs to stdout; use launchd/systemd to keep it alive and rotate logs.
 - Pass `--verbose` to mirror debug logging (handshakes, req/res, events) from the log file into stdio when troubleshooting.
 - `--force` uses `lsof` to find listeners on the chosen port, sends SIGTERM, logs what it killed, then starts the gateway (fails fast if `lsof` is missing).
 - If you run under a supervisor (launchd/systemd/mac app child-process mode), a stop/restart typically sends **SIGTERM**; older builds may surface this as `pnpm` `ELIFECYCLE` exit code **143** (SIGTERM), which is a normal shutdown, not a crash.
 - **SIGUSR1** triggers an in-process restart when authorized (gateway tool/config apply/update, or enable `commands.restart` for manual restarts).
-- Gateway auth: set `gateway.auth.mode=token` + `gateway.auth.token` (or pass `--token <value>` / `CLAWDBOT_GATEWAY_TOKEN`) to require clients to send `connect.params.auth.token`.
+- Gateway auth is required by default: set `gateway.auth.token` (or `CLAWDBOT_GATEWAY_TOKEN`) or `gateway.auth.password`. Clients must send `connect.params.auth.token/password` unless using Tailscale Serve identity.
 - The wizard now generates a token by default, even on loopback.
 - Port precedence: `--port` > `CLAWDBOT_GATEWAY_PORT` > `gateway.port` > default `18789`.
 
@@ -56,12 +56,12 @@ Usually unnecessary: one Gateway can serve multiple messaging channels and agent
 Supported if you isolate state + config and use unique ports. Full guide: [Multiple gateways](/gateway/multiple-gateways).
 
 Service names are profile-aware:
-- macOS: `com.clawdbot.<profile>`
-- Linux: `clawdbot-gateway-<profile>.service`
-- Windows: `Clawdbot Gateway (<profile>)`
+- macOS: `com.poolbot.<profile>`
+- Linux: `poolbot-gateway-<profile>.service`
+- Windows: `Pool Bot Gateway (<profile>)`
 
 Install metadata is embedded in the service config:
-- `CLAWDBOT_SERVICE_MARKER=clawdbot`
+- `CLAWDBOT_SERVICE_MARKER=poolbot`
 - `CLAWDBOT_SERVICE_KIND=gateway`
 - `CLAWDBOT_SERVICE_VERSION=<version>`
 
@@ -72,24 +72,24 @@ Rescue-Bot Pattern: keep a second Gateway isolated with its own profile, state d
 Fast path: run a fully-isolated dev instance (config/state/workspace) without touching your primary setup.
 
 ```bash
-clawdbot --dev setup
-clawdbot --dev gateway --allow-unconfigured
+poolbot --dev setup
+poolbot --dev gateway --allow-unconfigured
 # then target the dev instance:
-clawdbot --dev status
-clawdbot --dev health
+poolbot --dev status
+poolbot --dev health
 ```
 
 Defaults (can be overridden via env/flags/config):
-- `CLAWDBOT_STATE_DIR=~/.clawdbot-dev`
-- `CLAWDBOT_CONFIG_PATH=~/.clawdbot-dev/clawdbot.json`
+- `CLAWDBOT_STATE_DIR=~/.poolbot-dev`
+- `CLAWDBOT_CONFIG_PATH=~/.poolbot-dev/poolbot.json`
 - `CLAWDBOT_GATEWAY_PORT=19001` (Gateway WS + HTTP)
-- `browser.controlUrl=http://127.0.0.1:19003` (derived: `gateway.port+2`)
+- browser control service port = `19003` (derived: `gateway.port+2`, loopback only)
 - `canvasHost.port=19005` (derived: `gateway.port+4`)
 - `agents.defaults.workspace` default becomes `~/clawd-dev` when you run `setup`/`onboard` under `--dev`.
 
 Derived ports (rules of thumb):
 - Base port = `gateway.port` (or `CLAWDBOT_GATEWAY_PORT` / `--port`)
-- `browser.controlUrl port = base + 2` (or `CLAWDBOT_BROWSER_CONTROL_URL` / config override)
+- browser control service port = base + 2 (loopback only)
 - `canvasHost.port = base + 4` (or `CLAWDBOT_CANVAS_HOST_PORT` / config override)
 - Browser profile CDP ports auto-allocate from `browser.controlPort + 9 .. + 108` (persisted per profile).
 
@@ -102,14 +102,14 @@ Checklist per instance:
 
 Service install per profile:
 ```bash
-clawdbot --profile main gateway install
-clawdbot --profile rescue gateway install
+poolbot --profile main gateway install
+poolbot --profile rescue gateway install
 ```
 
 Example:
 ```bash
-CLAWDBOT_CONFIG_PATH=~/.clawdbot/a.json CLAWDBOT_STATE_DIR=~/.clawdbot-a clawdbot gateway --port 19001
-CLAWDBOT_CONFIG_PATH=~/.clawdbot/b.json CLAWDBOT_STATE_DIR=~/.clawdbot-b clawdbot gateway --port 19002
+CLAWDBOT_CONFIG_PATH=~/.poolbot/a.json CLAWDBOT_STATE_DIR=~/.poolbot-a poolbot gateway --port 19001
+CLAWDBOT_CONFIG_PATH=~/.poolbot/b.json CLAWDBOT_STATE_DIR=~/.poolbot-b poolbot gateway --port 19002
 ```
 
 ## Protocol (operator view)
@@ -123,7 +123,7 @@ CLAWDBOT_CONFIG_PATH=~/.clawdbot/b.json CLAWDBOT_STATE_DIR=~/.clawdbot-b clawdbo
 - `agent` responses are two-stage: first `res` ack `{runId,status:"accepted"}`, then a final `res` `{runId,status:"ok"|"error",summary}` after the run finishes; streamed output arrives as `event:"agent"`.
 
 ## Methods (initial set)
-- `health` — full health snapshot (same shape as `clawdbot health --json`).
+- `health` — full health snapshot (same shape as `poolbot health --json`).
 - `status` — short summary.
 - `system-presence` — current presence list.
 - `system-event` — post a presence/system note (structured).
@@ -175,26 +175,26 @@ See also: [Presence](/concepts/presence) for how presence is produced/deduped an
 
 ## Supervision (macOS example)
 - Use launchd to keep the service alive:
-  - Program: path to `clawdbot`
+  - Program: path to `poolbot`
   - Arguments: `gateway`
   - KeepAlive: true
   - StandardOut/Err: file paths or `syslog`
 - On failure, launchd restarts; fatal misconfig should keep exiting so the operator notices.
 - LaunchAgents are per-user and require a logged-in session; for headless setups use a custom LaunchDaemon (not shipped).
-  - `clawdbot gateway install` writes `~/Library/LaunchAgents/com.clawdbot.gateway.plist`
-    (or `com.clawdbot.<profile>.plist`).
-  - `clawdbot doctor` audits the LaunchAgent config and can update it to current defaults.
+  - `poolbot gateway install` writes `~/Library/LaunchAgents/com.poolbot.gateway.plist`
+    (or `com.poolbot.<profile>.plist`).
+  - `poolbot doctor` audits the LaunchAgent config and can update it to current defaults.
 
 ## Gateway service management (CLI)
 
 Use the Gateway CLI for install/start/stop/restart/status:
 
 ```bash
-clawdbot gateway status
-clawdbot gateway install
-clawdbot gateway stop
-clawdbot gateway restart
-clawdbot logs --follow
+poolbot gateway status
+poolbot gateway install
+poolbot gateway stop
+poolbot gateway restart
+poolbot logs --follow
 ```
 
 Notes:
@@ -206,37 +206,37 @@ Notes:
 - `gateway status` prints config path + probe target to avoid “localhost vs LAN bind” confusion and profile mismatches.
 - `gateway status` includes the last gateway error line when the service looks running but the port is closed.
 - `logs` tails the Gateway file log via RPC (no manual `tail`/`grep` needed).
-- If other gateway-like services are detected, the CLI warns unless they are Clawdbot profile services.
+- If other gateway-like services are detected, the CLI warns unless they are Pool Bot profile services.
   We still recommend **one gateway per machine** for most setups; use isolated profiles/ports for redundancy or a rescue bot. See [Multiple gateways](/gateway/multiple-gateways).
-  - Cleanup: `clawdbot gateway uninstall` (current service) and `clawdbot doctor` (legacy migrations).
-- `gateway install` is a no-op when already installed; use `clawdbot gateway install --force` to reinstall (profile/env/path changes).
+  - Cleanup: `poolbot gateway uninstall` (current service) and `poolbot doctor` (legacy migrations).
+- `gateway install` is a no-op when already installed; use `poolbot gateway install --force` to reinstall (profile/env/path changes).
 
 Bundled mac app:
-- Clawdbot.app can bundle a Node-based gateway relay and install a per-user LaunchAgent labeled
-  `com.clawdbot.gateway` (or `com.clawdbot.<profile>`).
-- To stop it cleanly, use `clawdbot gateway stop` (or `launchctl bootout gui/$UID/com.clawdbot.gateway`).
-- To restart, use `clawdbot gateway restart` (or `launchctl kickstart -k gui/$UID/com.clawdbot.gateway`).
-  - `launchctl` only works if the LaunchAgent is installed; otherwise use `clawdbot gateway install` first.
-  - Replace the label with `com.clawdbot.<profile>` when running a named profile.
+- Pool Bot.app can bundle a Node-based gateway relay and install a per-user LaunchAgent labeled
+  `com.poolbot.gateway` (or `com.poolbot.<profile>`).
+- To stop it cleanly, use `poolbot gateway stop` (or `launchctl bootout gui/$UID/com.poolbot.gateway`).
+- To restart, use `poolbot gateway restart` (or `launchctl kickstart -k gui/$UID/com.poolbot.gateway`).
+  - `launchctl` only works if the LaunchAgent is installed; otherwise use `poolbot gateway install` first.
+  - Replace the label with `com.poolbot.<profile>` when running a named profile.
 
 ## Supervision (systemd user unit)
-Clawdbot installs a **systemd user service** by default on Linux/WSL2. We
+Pool Bot installs a **systemd user service** by default on Linux/WSL2. We
 recommend user services for single-user machines (simpler env, per-user config).
 Use a **system service** for multi-user or always-on servers (no lingering
 required, shared supervision).
 
-`clawdbot gateway install` writes the user unit. `clawdbot doctor` audits the
+`poolbot gateway install` writes the user unit. `poolbot doctor` audits the
 unit and can update it to match the current recommended defaults.
 
-Create `~/.config/systemd/user/clawdbot-gateway[-<profile>].service`:
+Create `~/.config/systemd/user/poolbot-gateway[-<profile>].service`:
 ```
 [Unit]
-Description=Clawdbot Gateway (profile: <profile>, v<version>)
+Description=Pool Bot Gateway (profile: <profile>, v<version>)
 After=network-online.target
 Wants=network-online.target
 
 [Service]
-ExecStart=/usr/local/bin/clawdbot gateway --port 18789
+ExecStart=/usr/local/bin/poolbot gateway --port 18789
 Restart=always
 RestartSec=5
 Environment=CLAWDBOT_GATEWAY_TOKEN=
@@ -252,16 +252,16 @@ sudo loginctl enable-linger youruser
 Onboarding runs this on Linux/WSL2 (may prompt for sudo; writes `/var/lib/systemd/linger`).
 Then enable the service:
 ```
-systemctl --user enable --now clawdbot-gateway[-<profile>].service
+systemctl --user enable --now poolbot-gateway[-<profile>].service
 ```
 
 **Alternative (system service)** - for always-on or multi-user servers, you can
 install a systemd **system** unit instead of a user unit (no lingering needed).
-Create `/etc/systemd/system/clawdbot-gateway[-<profile>].service` (copy the unit above,
+Create `/etc/systemd/system/poolbot-gateway[-<profile>].service` (copy the unit above,
 switch `WantedBy=multi-user.target`, set `User=` + `WorkingDirectory=`), then:
 ```
 sudo systemctl daemon-reload
-sudo systemctl enable --now clawdbot-gateway[-<profile>].service
+sudo systemctl enable --now poolbot-gateway[-<profile>].service
 ```
 
 ## Windows (WSL2)
@@ -280,13 +280,13 @@ Windows installs should use **WSL2** and follow the Linux systemd section above.
 - Graceful shutdown: emit `shutdown` event before closing; clients must handle close + reconnect.
 
 ## CLI helpers
-- `clawdbot gateway health|status` — request health/status over the Gateway WS.
-- `clawdbot message send --target <num> --message "hi" [--media ...]` — send via Gateway (idempotent for WhatsApp).
-- `clawdbot agent --message "hi" --to <num>` — run an agent turn (waits for final by default).
-- `clawdbot gateway call <method> --params '{"k":"v"}'` — raw method invoker for debugging.
-- `clawdbot gateway stop|restart` — stop/restart the supervised gateway service (launchd/systemd).
+- `poolbot gateway health|status` — request health/status over the Gateway WS.
+- `poolbot message send --target <num> --message "hi" [--media ...]` — send via Gateway (idempotent for WhatsApp).
+- `poolbot agent --message "hi" --to <num>` — run an agent turn (waits for final by default).
+- `poolbot gateway call <method> --params '{"k":"v"}'` — raw method invoker for debugging.
+- `poolbot gateway stop|restart` — stop/restart the supervised gateway service (launchd/systemd).
 - Gateway helper subcommands assume a running gateway on `--url`; they no longer auto-spawn one.
 
 ## Migration guidance
-- Retire uses of `clawdbot gateway` and the legacy TCP control port.
+- Retire uses of `poolbot gateway` and the legacy TCP control port.
 - Update clients to speak the WS protocol with mandatory connect and structured presence.

package/docs/gateway/local-models.md

@@ -1,5 +1,5 @@
 ---
-summary: "Run Clawdbot on local LLMs (LM Studio, vLLM, LiteLLM, custom OpenAI endpoints)"
+summary: "Run Pool Bot on local LLMs (LM Studio, vLLM, LiteLLM, custom OpenAI endpoints)"
 read_when:
   - You want to serve models from your own GPU box
   - You are wiring LM Studio or an OpenAI-compatible proxy
@@ -7,7 +7,7 @@ read_when:
 ---
 # Local models
 
-Local is doable, but Clawdbot expects large context + strong defenses against prompt injection. Small cards truncate context and leak safety. Aim high: **≥2 maxed-out Mac Studios or equivalent GPU rig (~$30k+)**. A single **24 GB** GPU works only for lighter prompts with higher latency. Use the **largest / full-size model variant you can run**; aggressively quantized or “small” checkpoints raise prompt-injection risk (see [Security](/gateway/security)).
+Local is doable, but Pool Bot expects large context + strong defenses against prompt injection. Small cards truncate context and leak safety. Aim high: **≥2 maxed-out Mac Studios or equivalent GPU rig (~$30k+)**. A single **24 GB** GPU works only for lighter prompts with higher latency. Use the **largest / full-size model variant you can run**; aggressively quantized or “small” checkpoints raise prompt-injection risk (see [Security](/gateway/security)).
 
 ## Recommended: LM Studio + MiniMax M2.1 (Responses API, full-size)
 

package/docs/gateway/logging.md

@@ -9,16 +9,16 @@ read_when:
 
 For a user-facing overview (CLI + Control UI + config), see [/logging](/logging).
 
-Clawdbot has two log “surfaces”:
+Pool Bot has two log “surfaces”:
 
 - **Console output** (what you see in the terminal / Debug UI).
 - **File logs** (JSON lines) written by the gateway logger.
 
 ## File-based logger
 
-- Default rolling log file is under `/tmp/clawdbot/` (one file per day): `clawdbot-YYYY-MM-DD.log`
+- Default rolling log file is under `/tmp/poolbot/` (one file per day): `poolbot-YYYY-MM-DD.log`
   - Date uses the gateway host's local timezone.
-- The log file path and level can be configured via `~/.clawdbot/clawdbot.json`:
+- The log file path and level can be configured via `~/.poolbot/poolbot.json`:
   - `logging.file`
   - `logging.level`
 
@@ -28,7 +28,7 @@ The Control UI Logs tab tails this file via the gateway (`logs.tail`).
 CLI can do the same:
 
 ```bash
-clawdbot logs --follow
+poolbot logs --follow
 ```
 
 **Verbose vs. log levels**
@@ -72,7 +72,7 @@ The gateway prints WebSocket protocol logs in two modes:
 
 ### WS log style
 
-`clawdbot gateway` supports a per-gateway style switch:
+`poolbot gateway` supports a per-gateway style switch:
 
 - `--ws-log auto` (default): normal mode is optimized; verbose mode uses compact output
 - `--ws-log compact`: compact output (paired request/response) when verbose
@@ -83,13 +83,13 @@ Examples:
 
 ```bash
 # optimized (only errors/slow)
-clawdbot gateway
+poolbot gateway
 
 # show all WS traffic (paired)
-clawdbot gateway --verbose --ws-log compact
+poolbot gateway --verbose --ws-log compact
 
 # show all WS traffic (full meta)
-clawdbot gateway --verbose --ws-log full
+poolbot gateway --verbose --ws-log full
 ```
 
 ## Console formatting (subsystem logging)