@poolzin/pool-bot 2026.1.26 → 2026.1.29

package/docs/gateway/multiple-gateways.md

@@ -1,5 +1,5 @@
 ---
-summary: "Run multiple Clawdbot Gateways on one host (isolation, ports, and profiles)"
+summary: "Run multiple Pool Bot Gateways on one host (isolation, ports, and profiles)"
 read_when:
   - Running more than one Gateway on the same machine
   - You need isolated config/state/ports per Gateway
@@ -23,18 +23,18 @@ Profiles auto-scope `CLAWDBOT_STATE_DIR` + `CLAWDBOT_CONFIG_PATH` and suffix ser
 
 ```bash
 # main
-clawdbot --profile main setup
-clawdbot --profile main gateway --port 18789
+poolbot --profile main setup
+poolbot --profile main gateway --port 18789
 
 # rescue
-clawdbot --profile rescue setup
-clawdbot --profile rescue gateway --port 19001
+poolbot --profile rescue setup
+poolbot --profile rescue gateway --port 19001
 ```
 
 Per-profile services:
 ```bash
-clawdbot --profile main gateway install
-clawdbot --profile rescue gateway install
+poolbot --profile main gateway install
+poolbot --profile rescue gateway install
 ```
 
 ## Rescue-bot guide
@@ -54,11 +54,11 @@ Port spacing: leave at least 20 ports between base ports so the derived browser/
 ```bash
 # Main bot (existing or fresh, without --profile param)
 # Runs on port 18789 + Chrome CDC/Canvas/... Ports 
-clawdbot onboard
-clawdbot gateway install
+poolbot onboard
+poolbot gateway install
 
 # Rescue bot (isolated profile + ports)
-clawdbot --profile rescue onboard
+poolbot --profile rescue onboard
 # Notes: 
 # - workspace name will be postfixed with -rescue per default
 # - Port should be at least 18789 + 20 Ports, 
@@ -66,14 +66,14 @@ clawdbot --profile rescue onboard
 # - rest of the onboarding is the same as normal
 
 # To install the service (if not happened automatically during onboarding)
-clawdbot --profile rescue gateway install
+poolbot --profile rescue gateway install
 ```
 
 ## Port mapping (derived)
 
 Base port = `gateway.port` (or `CLAWDBOT_GATEWAY_PORT` / `--port`).
 
-- `browser.controlUrl port = base + 2`
+- browser control service port = base + 2 (loopback only)
 - `canvasHost.port = base + 4`
 - Browser profile CDP ports auto-allocate from `browser.controlPort + 9 .. + 108`
 
@@ -81,27 +81,27 @@ If you override any of these in config or env, you must keep them unique per ins
 
 ## Browser/CDP notes (common footgun)
 
-- Do **not** pin `browser.controlUrl` or `browser.cdpUrl` to the same values on multiple instances.
-- Each instance needs its own browser control port and CDP range.
+- Do **not** pin `browser.cdpUrl` to the same values on multiple instances.
+- Each instance needs its own browser control port and CDP range (derived from its gateway port).
 - If you need explicit CDP ports, set `browser.profiles.<name>.cdpPort` per instance.
 - Remote Chrome: use `browser.profiles.<name>.cdpUrl` (per profile, per instance).
 
 ## Manual env example
 
 ```bash
-CLAWDBOT_CONFIG_PATH=~/.clawdbot/main.json \
-CLAWDBOT_STATE_DIR=~/.clawdbot-main \
-clawdbot gateway --port 18789
+CLAWDBOT_CONFIG_PATH=~/.poolbot/main.json \
+CLAWDBOT_STATE_DIR=~/.poolbot-main \
+poolbot gateway --port 18789
 
-CLAWDBOT_CONFIG_PATH=~/.clawdbot/rescue.json \
-CLAWDBOT_STATE_DIR=~/.clawdbot-rescue \
-clawdbot gateway --port 19001
+CLAWDBOT_CONFIG_PATH=~/.poolbot/rescue.json \
+CLAWDBOT_STATE_DIR=~/.poolbot-rescue \
+poolbot gateway --port 19001
 ```
 
 ## Quick checks
 
 ```bash
-clawdbot --profile main status
-clawdbot --profile rescue status
-clawdbot --profile rescue browser status
+poolbot --profile main status
+poolbot --profile rescue status
+poolbot --profile rescue browser status
 ```

package/docs/gateway/openai-http-api.md

@@ -5,14 +5,14 @@ read_when:
 ---
 # OpenAI Chat Completions (HTTP)
 
-Clawdbot’s Gateway can serve a small OpenAI-compatible Chat Completions endpoint.
+Pool Bot’s Gateway can serve a small OpenAI-compatible Chat Completions endpoint.
 
 This endpoint is **disabled by default**. Enable it in config first.
 
 - `POST /v1/chat/completions`
 - Same port as the Gateway (WS + HTTP multiplex): `http://<gateway-host>:<port>/v1/chat/completions`
 
-Under the hood, requests are executed as a normal Gateway agent run (same codepath as `clawdbot agent`), so routing/permissions/config match your Gateway.
+Under the hood, requests are executed as a normal Gateway agent run (same codepath as `poolbot agent`), so routing/permissions/config match your Gateway.
 
 ## Authentication
 
@@ -28,15 +28,15 @@ Notes:
 
 No custom headers required: encode the agent id in the OpenAI `model` field:
 
-- `model: "clawdbot:<agentId>"` (example: `"clawdbot:main"`, `"clawdbot:beta"`)
+- `model: "poolbot:<agentId>"` (example: `"poolbot:main"`, `"poolbot:beta"`)
 - `model: "agent:<agentId>"` (alias)
 
-Or target a specific Clawdbot agent by header:
+Or target a specific Pool Bot agent by header:
 
-- `x-clawdbot-agent-id: <agentId>` (default: `main`)
+- `x-poolbot-agent-id: <agentId>` (default: `main`)
 
 Advanced:
-- `x-clawdbot-session-key: <sessionKey>` to fully control session routing.
+- `x-poolbot-session-key: <sessionKey>` to fully control session routing.
 
 ## Enabling the endpoint
 
@@ -91,9 +91,9 @@ Non-streaming:
 curl -sS http://127.0.0.1:18789/v1/chat/completions \
   -H 'Authorization: Bearer YOUR_TOKEN' \
   -H 'Content-Type: application/json' \
-  -H 'x-clawdbot-agent-id: main' \
+  -H 'x-poolbot-agent-id: main' \
   -d '{
-    "model": "clawdbot",
+    "model": "poolbot",
     "messages": [{"role":"user","content":"hi"}]
   }'
 ```
@@ -103,9 +103,9 @@ Streaming:
 curl -N http://127.0.0.1:18789/v1/chat/completions \
   -H 'Authorization: Bearer YOUR_TOKEN' \
   -H 'Content-Type: application/json' \
-  -H 'x-clawdbot-agent-id: main' \
+  -H 'x-poolbot-agent-id: main' \
   -d '{
-    "model": "clawdbot",
+    "model": "poolbot",
     "stream": true,
     "messages": [{"role":"user","content":"hi"}]
   }'

package/docs/gateway/openresponses-http-api.md

@@ -6,7 +6,7 @@ read_when:
 ---
 # OpenResponses API (HTTP)
 
-Clawdbot’s Gateway can serve an OpenResponses-compatible `POST /v1/responses` endpoint.
+Pool Bot’s Gateway can serve an OpenResponses-compatible `POST /v1/responses` endpoint.
 
 This endpoint is **disabled by default**. Enable it in config first.
 
@@ -14,7 +14,7 @@ This endpoint is **disabled by default**. Enable it in config first.
 - Same port as the Gateway (WS + HTTP multiplex): `http://<gateway-host>:<port>/v1/responses`
 
 Under the hood, requests are executed as a normal Gateway agent run (same codepath as
-`clawdbot agent`), so routing/permissions/config match your Gateway.
+`poolbot agent`), so routing/permissions/config match your Gateway.
 
 ## Authentication
 
@@ -30,15 +30,15 @@ Notes:
 
 No custom headers required: encode the agent id in the OpenResponses `model` field:
 
-- `model: "clawdbot:<agentId>"` (example: `"clawdbot:main"`, `"clawdbot:beta"`)
+- `model: "poolbot:<agentId>"` (example: `"poolbot:main"`, `"poolbot:beta"`)
 - `model: "agent:<agentId>"` (alias)
 
-Or target a specific Clawdbot agent by header:
+Or target a specific Pool Bot agent by header:
 
-- `x-clawdbot-agent-id: <agentId>` (default: `main`)
+- `x-poolbot-agent-id: <agentId>` (default: `main`)
 
 Advanced:
-- `x-clawdbot-session-key: <sessionKey>` to fully control session routing.
+- `x-poolbot-session-key: <sessionKey>` to fully control session routing.
 
 ## Enabling the endpoint
 
@@ -277,9 +277,9 @@ Non-streaming:
 curl -sS http://127.0.0.1:18789/v1/responses \
   -H 'Authorization: Bearer YOUR_TOKEN' \
   -H 'Content-Type: application/json' \
-  -H 'x-clawdbot-agent-id: main' \
+  -H 'x-poolbot-agent-id: main' \
   -d '{
-    "model": "clawdbot",
+    "model": "poolbot",
     "input": "hi"
   }'
 ```
@@ -289,9 +289,9 @@ Streaming:
 curl -N http://127.0.0.1:18789/v1/responses \
   -H 'Authorization: Bearer YOUR_TOKEN' \
   -H 'Content-Type: application/json' \
-  -H 'x-clawdbot-agent-id: main' \
+  -H 'x-poolbot-agent-id: main' \
   -d '{
-    "model": "clawdbot",
+    "model": "poolbot",
     "stream": true,
     "input": "hi"
   }'

package/docs/gateway/pairing.md

@@ -35,11 +35,11 @@ Pending requests expire automatically after **5 minutes**.
 ## CLI workflow (headless friendly)
 
 ```bash
-clawdbot nodes pending
-clawdbot nodes approve <requestId>
-clawdbot nodes reject <requestId>
-clawdbot nodes status
-clawdbot nodes rename --node <id|name|ip> --name "Living Room iPad"
+poolbot nodes pending
+poolbot nodes approve <requestId>
+poolbot nodes reject <requestId>
+poolbot nodes status
+poolbot nodes rename --node <id|name|ip> --name "Living Room iPad"
 ```
 
 `nodes status` shows paired/connected nodes and their capabilities.
@@ -74,10 +74,10 @@ If silent approval fails, it falls back to the normal “Approve/Reject” promp
 
 ## Storage (local, private)
 
-Pairing state is stored under the Gateway state directory (default `~/.clawdbot`):
+Pairing state is stored under the Gateway state directory (default `~/.poolbot`):
 
-- `~/.clawdbot/nodes/paired.json`
-- `~/.clawdbot/nodes/pending.json`
+- `~/.poolbot/nodes/paired.json`
+- `~/.poolbot/nodes/pending.json`
 
 If you override `CLAWDBOT_STATE_DIR`, the `nodes/` folder moves with it.
 

package/docs/gateway/protocol.md

@@ -9,7 +9,7 @@ read_when:
 # Gateway protocol (WebSocket)
 
 The Gateway WS protocol is the **single control plane + node transport** for
-Clawdbot. All clients (CLI, web UI, macOS app, iOS/Android nodes, headless
+Pool Bot. All clients (CLI, web UI, macOS app, iOS/Android nodes, headless
 nodes) connect over WebSocket and declare their **role** + **scope** at
 handshake time.
 
@@ -53,7 +53,7 @@ Client → Gateway:
     "permissions": {},
     "auth": { "token": "…" },
     "locale": "en-US",
-    "userAgent": "clawdbot-cli/1.2.3",
+    "userAgent": "poolbot-cli/1.2.3",
     "device": {
       "id": "device_fingerprint",
       "publicKey": "…",
@@ -111,7 +111,7 @@ When a device token is issued, `hello-ok` also includes:
     "permissions": { "camera.capture": true, "screen.record": false },
     "auth": { "token": "…" },
     "locale": "en-US",
-    "userAgent": "clawdbot-ios/1.2.3",
+    "userAgent": "poolbot-ios/1.2.3",
     "device": {
       "id": "device_fingerprint",
       "publicKey": "…",
@@ -198,7 +198,8 @@ The Gateway treats these as **claims** and enforces server-side allowlists.
 - **Local** connects include loopback and the gateway host’s own tailnet address
   (so same‑host tailnet binds can still auto‑approve).
 - All WS clients must include `device` identity during `connect` (operator + node).
-  Control UI can omit it **only** when `gateway.controlUi.allowInsecureAuth` is enabled.
+  Control UI can omit it **only** when `gateway.controlUi.allowInsecureAuth` is enabled
+  (or `gateway.controlUi.dangerouslyDisableDeviceAuth` for break-glass use).
 - Non-local connections must sign the server-provided `connect.challenge` nonce.
 
 ## TLS + pinning

package/docs/gateway/remote-gateway-readme.md

@@ -1,11 +1,11 @@
 ---
-summary: "SSH tunnel setup for Clawdbot.app connecting to a remote gateway"
+summary: "SSH tunnel setup for Pool Bot.app connecting to a remote gateway"
 read_when: "Connecting the macOS app to a remote gateway over SSH"
 ---
 
-# Running Clawdbot.app with a Remote Gateway
+# Running Pool Bot.app with a Remote Gateway
 
-Clawdbot.app uses SSH tunneling to connect to a remote gateway. This guide shows you how to set it up.
+Pool Bot.app uses SSH tunneling to connect to a remote gateway. This guide shows you how to set it up.
 
 ## Overview
 
@@ -13,7 +13,7 @@ Clawdbot.app uses SSH tunneling to connect to a remote gateway. This guide shows
 ┌─────────────────────────────────────────────────────────────┐
 │                        Client Machine                          │
 │                                                              │
-│  Clawdbot.app ──► ws://127.0.0.1:18789 (local port)           │
+│  Pool Bot.app ──► ws://127.0.0.1:18789 (local port)           │
 │                     │                                        │
 │                     ▼                                        │
 │  SSH Tunnel ────────────────────────────────────────────────│
@@ -65,11 +65,11 @@ launchctl setenv CLAWDBOT_GATEWAY_TOKEN "<your-token>"
 ssh -N remote-gateway &
 ```
 
-### Step 5: Restart Clawdbot.app
+### Step 5: Restart Pool Bot.app
 
 ```bash
-# Quit Clawdbot.app (⌘Q), then reopen:
-open /path/to/Clawdbot.app
+# Quit Pool Bot.app (⌘Q), then reopen:
+open /path/to/Pool Bot.app
 ```
 
 The app will now connect to the remote gateway through the SSH tunnel.
@@ -82,7 +82,7 @@ To have the SSH tunnel start automatically when you log in, create a Launch Agen
 
 ### Create the PLIST file
 
-Save this as `~/Library/LaunchAgents/com.clawdbot.ssh-tunnel.plist`:
+Save this as `~/Library/LaunchAgents/com.poolbot.ssh-tunnel.plist`:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -90,7 +90,7 @@ Save this as `~/Library/LaunchAgents/com.clawdbot.ssh-tunnel.plist`:
 <plist version="1.0">
 <dict>
     <key>Label</key>
-    <string>com.clawdbot.ssh-tunnel</string>
+    <string>com.poolbot.ssh-tunnel</string>
     <key>ProgramArguments</key>
     <array>
         <string>/usr/bin/ssh</string>
@@ -108,7 +108,7 @@ Save this as `~/Library/LaunchAgents/com.clawdbot.ssh-tunnel.plist`:
 ### Load the Launch Agent
 
 ```bash
-launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.clawdbot.ssh-tunnel.plist
+launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.poolbot.ssh-tunnel.plist
 ```
 
 The tunnel will now:
@@ -130,13 +130,13 @@ lsof -i :18789
 **Restart the tunnel:**
 
 ```bash
-launchctl kickstart -k gui/$UID/com.clawdbot.ssh-tunnel
+launchctl kickstart -k gui/$UID/com.poolbot.ssh-tunnel
 ```
 
 **Stop the tunnel:**
 
 ```bash
-launchctl bootout gui/$UID/com.clawdbot.ssh-tunnel
+launchctl bootout gui/$UID/com.poolbot.ssh-tunnel
 ```
 
 ---
@@ -150,4 +150,4 @@ launchctl bootout gui/$UID/com.clawdbot.ssh-tunnel
 | `KeepAlive` | Automatically restarts tunnel if it crashes |
 | `RunAtLoad` | Starts tunnel when the agent loads |
 
-Clawdbot.app connects to `ws://127.0.0.1:18789` on your client machine. The SSH tunnel forwards that connection to port 18789 on the remote machine where the Gateway is running.
+Pool Bot.app connects to `ws://127.0.0.1:18789` on your client machine. The SSH tunnel forwards that connection to port 18789 on the remote machine where the Gateway is running.

package/docs/gateway/remote.md

@@ -34,7 +34,7 @@ This is ideal when your laptop sleeps often but you want the agent always-on.
 
 The laptop does **not** run the agent. It connects remotely:
 
-- Use the macOS app’s **Remote over SSH** mode (Settings → General → “Clawdbot runs”).
+- Use the macOS app’s **Remote over SSH** mode (Settings → General → “Pool Bot runs”).
 - The app opens and manages the tunnel, so WebChat + health checks “just work.”
 
 Runbook: [macOS remote access](/platforms/mac/remote).
@@ -71,8 +71,8 @@ ssh -N -L 18789:127.0.0.1:18789 user@host
 ```
 
 With the tunnel up:
-- `clawdbot health` and `clawdbot status --deep` now reach the remote gateway via `ws://127.0.0.1:18789`.
-- `clawdbot gateway {status,health,send,agent,call}` can also target the forwarded URL via `--url` when needed.
+- `poolbot health` and `poolbot status --deep` now reach the remote gateway via `ws://127.0.0.1:18789`.
+- `poolbot gateway {status,health,send,agent,call}` can also target the forwarded URL via `--url` when needed.
 
 Note: replace `18789` with your configured `gateway.port` (or `--port`/`CLAWDBOT_GATEWAY_PORT`).
 
@@ -117,6 +117,6 @@ Short version: **keep the Gateway loopback-only** unless you’re sure you need
 - `gateway.remote.tlsFingerprint` pins the remote TLS cert when using `wss://`.
 - **Tailscale Serve** can authenticate via identity headers when `gateway.auth.allowTailscale: true`.
   Set it to `false` if you want tokens/passwords instead.
-- Treat `browser.controlUrl` like an admin API: tailnet-only + token auth.
+- Treat browser control like operator access: tailnet-only + deliberate node pairing.
 
 Deep dive: [Security](/gateway/security).

package/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md

@@ -7,7 +7,7 @@ status: active
 
 # Sandbox vs Tool Policy vs Elevated
 
-Clawdbot has three related (but different) controls:
+Pool Bot has three related (but different) controls:
 
 1. **Sandbox** (`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`) decides **where tools run** (Docker vs host).
 2. **Tool policy** (`tools.*`, `tools.sandbox.tools.*`, `agents.list[].tools.*`) decides **which tools are available/allowed**.
@@ -15,13 +15,13 @@ Clawdbot has three related (but different) controls:
 
 ## Quick debug
 
-Use the inspector to see what Clawdbot is *actually* doing:
+Use the inspector to see what Pool Bot is *actually* doing:
 
 ```bash
-clawdbot sandbox explain
-clawdbot sandbox explain --session agent:main:main
-clawdbot sandbox explain --agent work
-clawdbot sandbox explain --json
+poolbot sandbox explain
+poolbot sandbox explain --session agent:main:main
+poolbot sandbox explain --agent work
+poolbot sandbox explain --json
 ```
 
 It prints:
@@ -59,6 +59,8 @@ Two layers matter:
 Rules of thumb:
 - `deny` always wins.
 - If `allow` is non-empty, everything else is treated as blocked.
+- Tool policy is the hard stop: `/exec` cannot override a denied `exec` tool.
+- `/exec` only changes session defaults for authorized senders; it does not grant tool access.
 Provider tool keys accept either `provider` (e.g. `google-antigravity`) or `provider/model` (e.g. `openai/gpt-5.2`).
 
 ### Tool groups (shorthands)
@@ -86,7 +88,7 @@ Available groups:
 - `group:automation`: `cron`, `gateway`
 - `group:messaging`: `message`
 - `group:nodes`: `nodes`
-- `group:clawdbot`: all built-in Clawdbot tools (excludes provider plugins)
+- `group:poolbot`: all built-in Pool Bot tools (excludes provider plugins)
 
 ## Elevated: exec-only “run on host”
 
@@ -95,6 +97,7 @@ Elevated does **not** grant extra tools; it only affects `exec`.
 - Use `/elevated full` to skip exec approvals for the session.
 - If you’re already running direct, elevated is effectively a no-op (still gated).
 - Elevated is **not** skill-scoped and does **not** override tool allow/deny.
+- `/exec` is separate from elevated. It only adjusts per-session exec defaults for authorized senders.
 
 Gates:
 - Enablement: `tools.elevated.enabled` (and optionally `agents.list[].tools.elevated.enabled`)

package/docs/gateway/sandboxing.md

@@ -1,5 +1,5 @@
 ---
-summary: "How Clawdbot sandboxing works: modes, scopes, workspace access, and images"
+summary: "How Pool Bot sandboxing works: modes, scopes, workspace access, and images"
 title: Sandboxing
 read_when: "You want a dedicated explanation of sandboxing or need to tune agents.defaults.sandbox."
 status: active
@@ -7,7 +7,7 @@ status: active
 
 # Sandboxing
 
-Clawdbot can run **tools inside Docker containers** to reduce blast radius.
+Pool Bot can run **tools inside Docker containers** to reduce blast radius.
 This is **optional** and controlled by configuration (`agents.defaults.sandbox` or
 `agents.list[].sandbox`). If sandboxing is off, tools run on the host.
 The Gateway stays on the host; tool execution runs in an isolated sandbox
@@ -46,13 +46,13 @@ Group/channel sessions use their own keys, so they count as non-main and will be
 
 ## Workspace access
 `agents.defaults.sandbox.workspaceAccess` controls **what the sandbox can see**:
-- `"none"` (default): tools see a sandbox workspace under `~/.clawdbot/sandboxes`.
+- `"none"` (default): tools see a sandbox workspace under `~/.poolbot/sandboxes`.
 - `"ro"`: mounts the agent workspace read-only at `/agent` (disables `write`/`edit`/`apply_patch`).
 - `"rw"`: mounts the agent workspace read/write at `/workspace`.
 
 Inbound media is copied into the active sandbox workspace (`media/inbound/*`).
 Skills note: the `read` tool is sandbox-rooted. With `workspaceAccess: "none"`,
-Clawdbot mirrors eligible skills into the sandbox workspace (`.../skills`) so
+Pool Bot mirrors eligible skills into the sandbox workspace (`.../skills`) so
 they can be read. With `"rw"`, workspace skills are readable from
 `/workspace/skills`.
 
@@ -98,7 +98,7 @@ Security notes:
 - See [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) for how binds interact with tool policy and elevated exec.
 
 ## Images + setup
-Default image: `clawdbot-sandbox:bookworm-slim`
+Default image: `poolbot-sandbox:bookworm-slim`
 
 Build it once:
 ```bash
@@ -142,9 +142,11 @@ Tool allow/deny policies still apply before sandbox rules. If a tool is denied
 globally or per-agent, sandboxing doesn’t bring it back.
 
 `tools.elevated` is an explicit escape hatch that runs `exec` on the host.
+`/exec` directives only apply for authorized senders and persist per session; to hard-disable
+`exec`, use tool policy deny (see [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated)).
 
 Debugging:
-- Use `clawdbot sandbox explain` to inspect effective sandbox mode, tool policy, and fix-it config keys.
+- Use `poolbot sandbox explain` to inspect effective sandbox mode, tool policy, and fix-it config keys.
 - See [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) for the “why is this blocked?” mental model.
 Keep it locked down.
 

package/docs/gateway/security/formal-verification.md

@@ -0,0 +1,107 @@
+---
+title: Formal Verification (Security Models)
+summary: Machine-checked security models for Pool Bot’s highest-risk paths.
+permalink: /gateway/security/formal-verification/
+---
+
+# Formal Verification (Security Models)
+
+This page tracks Pool Bot’s **formal security models** (TLA+/TLC today; more as needed).
+
+**Goal (north star):** provide a machine-checked argument that Pool Bot enforces its
+intended security policy (authorization, session isolation, tool gating, and
+misconfiguration safety), under explicit assumptions.
+
+**What this is (today):** an executable, attacker-driven **security regression suite**:
+- Each claim has a runnable model-check over a finite state space.
+- Many claims have a paired **negative model** that produces a counterexample trace for a realistic bug class.
+
+**What this is not (yet):** a proof that “Pool Bot is secure in all respects” or that the full TypeScript implementation is correct.
+
+## Where the models live
+
+Models are maintained in a separate repo: [vignesh07/poolbot-formal-models](https://github.com/vignesh07/poolbot-formal-models).
+
+## Important caveats
+
+- These are **models**, not the full TypeScript implementation. Drift between model and code is possible.
+- Results are bounded by the state space explored by TLC; “green” does not imply security beyond the modeled assumptions and bounds.
+- Some claims rely on explicit environmental assumptions (e.g., correct deployment, correct configuration inputs).
+
+## Reproducing results
+
+Today, results are reproduced by cloning the models repo locally and running TLC (see below). A future iteration could offer:
+- CI-run models with public artifacts (counterexample traces, run logs)
+- a hosted “run this model” workflow for small, bounded checks
+
+Getting started:
+
+```bash
+git clone https://github.com/vignesh07/poolbot-formal-models
+cd poolbot-formal-models
+
+# Java 11+ required (TLC runs on the JVM).
+# The repo vendors a pinned `tla2tools.jar` (TLA+ tools) and provides `bin/tlc` + Make targets.
+
+make <target>
+```
+
+### Gateway exposure and open gateway misconfiguration
+
+**Claim:** binding beyond loopback without auth can make remote compromise possible / increases exposure; token/password blocks unauth attackers (per the model assumptions).
+
+- Green runs:
+  - `make gateway-exposure-v2`
+  - `make gateway-exposure-v2-protected`
+- Red (expected):
+  - `make gateway-exposure-v2-negative`
+
+See also: `docs/gateway-exposure-matrix.md` in the models repo.
+
+### Nodes.run pipeline (highest-risk capability)
+
+**Claim:** `nodes.run` requires (a) node command allowlist plus declared commands and (b) live approval when configured; approvals are tokenized to prevent replay (in the model).
+
+- Green runs:
+  - `make nodes-pipeline`
+  - `make approvals-token`
+- Red (expected):
+  - `make nodes-pipeline-negative`
+  - `make approvals-token-negative`
+
+### Pairing store (DM gating)
+
+**Claim:** pairing requests respect TTL and pending-request caps.
+
+- Green runs:
+  - `make pairing`
+  - `make pairing-cap`
+- Red (expected):
+  - `make pairing-negative`
+  - `make pairing-cap-negative`
+
+### Ingress gating (mentions + control-command bypass)
+
+**Claim:** in group contexts requiring mention, an unauthorized “control command” cannot bypass mention gating.
+
+- Green:
+  - `make ingress-gating`
+- Red (expected):
+  - `make ingress-gating-negative`
+
+### Routing/session-key isolation
+
+**Claim:** DMs from distinct peers do not collapse into the same session unless explicitly linked/configured.
+
+- Green:
+  - `make routing-isolation`
+- Red (expected):
+  - `make routing-isolation-negative`
+
+## Roadmap
+
+Next models to deepen fidelity:
+- Pairing store concurrency/locking/idempotency
+- Provider-specific ingress preflight modeling
+- Routing identity-links + dmScope variants + binding precedence
+- Gateway auth conformance (proxy/tailscale specifics)