loudmouth-ai 0.1.0

package/docs/network.md

@@ -0,0 +1,51 @@
+---
+summary: "Network hub: gateway surfaces, pairing, discovery, and security"
+read_when:
+  - You need the network architecture + security overview
+  - You are debugging local vs tailnet access or pairing
+  - You want the canonical list of networking docs
+---
+# Network hub
+
+This hub links the core docs for how Clawdbot connects, pairs, and secures
+devices across localhost, LAN, and tailnet.
+
+## Core model
+
+- [Gateway architecture](/concepts/architecture)
+- [Gateway protocol](/gateway/protocol)
+- [Gateway runbook](/gateway)
+- [Web surfaces + bind modes](/web)
+
+## Pairing + identity
+
+- [Pairing overview (DM + nodes)](/start/pairing)
+- [Gateway-owned node pairing](/gateway/pairing)
+- [Devices CLI (pairing + token rotation)](/cli/devices)
+- [Pairing CLI (DM approvals)](/cli/pairing)
+
+Local trust:
+- Local connections (loopback or the gateway host’s own tailnet address) can be
+  auto‑approved for pairing to keep same‑host UX smooth.
+- Non‑local tailnet/LAN clients still require explicit pairing approval.
+
+## Discovery + transports
+
+- [Discovery & transports](/gateway/discovery)
+- [Bonjour / mDNS](/gateway/bonjour)
+- [Remote access (SSH)](/gateway/remote)
+- [Tailscale](/gateway/tailscale)
+
+## Nodes + transports
+
+- [Nodes overview](/nodes)
+- [Bridge protocol (legacy nodes)](/gateway/bridge-protocol)
+- [Node runbook: iOS](/platforms/ios)
+- [Node runbook: Android](/platforms/android)
+
+## Security
+
+- [Security overview](/gateway/security)
+- [Gateway config reference](/gateway/configuration)
+- [Troubleshooting](/gateway/troubleshooting)
+- [Doctor](/gateway/doctor)

package/docs/nodes/audio.md

@@ -0,0 +1,109 @@
+---
+summary: "How inbound audio/voice notes are downloaded, transcribed, and injected into replies"
+read_when:
+  - Changing audio transcription or media handling
+---
+# Audio / Voice Notes — 2026-01-17
+
+## What works
+- **Media understanding (audio)**: If audio understanding is enabled (or auto‑detected), Clawdbot:
+  1) Locates the first audio attachment (local path or URL) and downloads it if needed.
+  2) Enforces `maxBytes` before sending to each model entry.
+  3) Runs the first eligible model entry in order (provider or CLI).
+  4) If it fails or skips (size/timeout), it tries the next entry.
+  5) On success, it replaces `Body` with an `[Audio]` block and sets `{{Transcript}}`.
+- **Command parsing**: When transcription succeeds, `CommandBody`/`RawBody` are set to the transcript so slash commands still work.
+- **Verbose logging**: In `--verbose`, we log when transcription runs and when it replaces the body.
+
+## Auto-detection (default)
+If you **don’t configure models** and `tools.media.audio.enabled` is **not** set to `false`,
+Clawdbot auto-detects in this order and stops at the first working option:
+
+1) **Local CLIs** (if installed)
+   - `sherpa-onnx-offline` (requires `SHERPA_ONNX_MODEL_DIR` with encoder/decoder/joiner/tokens)
+   - `whisper-cli` (from `whisper-cpp`; uses `WHISPER_CPP_MODEL` or the bundled tiny model)
+   - `whisper` (Python CLI; downloads models automatically)
+2) **Gemini CLI** (`gemini`) using `read_many_files`
+3) **Provider keys** (OpenAI → Groq → Deepgram → Google)
+
+To disable auto-detection, set `tools.media.audio.enabled: false`.
+To customize, set `tools.media.audio.models`.
+Note: Binary detection is best-effort across macOS/Linux/Windows; ensure the CLI is on `PATH` (we expand `~`), or set an explicit CLI model with a full command path.
+
+## Config examples
+
+### Provider + CLI fallback (OpenAI + Whisper CLI)
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        enabled: true,
+        maxBytes: 20971520,
+        models: [
+          { provider: "openai", model: "gpt-4o-mini-transcribe" },
+          {
+            type: "cli",
+            command: "whisper",
+            args: ["--model", "base", "{{MediaPath}}"],
+            timeoutSeconds: 45
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+### Provider-only with scope gating
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        enabled: true,
+        scope: {
+          default: "allow",
+          rules: [
+            { action: "deny", match: { chatType: "group" } }
+          ]
+        },
+        models: [
+          { provider: "openai", model: "gpt-4o-mini-transcribe" }
+        ]
+      }
+    }
+  }
+}
+```
+
+### Provider-only (Deepgram)
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        enabled: true,
+        models: [{ provider: "deepgram", model: "nova-3" }]
+      }
+    }
+  }
+}
+```
+
+## Notes & limits
+- Provider auth follows the standard model auth order (auth profiles, env vars, `models.providers.*.apiKey`).
+- Deepgram picks up `DEEPGRAM_API_KEY` when `provider: "deepgram"` is used.
+- Deepgram setup details: [Deepgram (audio transcription)](/providers/deepgram).
+- Audio providers can override `baseUrl`, `headers`, and `providerOptions` via `tools.media.audio`.
+- Default size cap is 20MB (`tools.media.audio.maxBytes`). Oversize audio is skipped for that model and the next entry is tried.
+- Default `maxChars` for audio is **unset** (full transcript). Set `tools.media.audio.maxChars` or per-entry `maxChars` to trim output.
+- OpenAI auto default is `gpt-4o-mini-transcribe`; set `model: "gpt-4o-transcribe"` for higher accuracy.
+- Use `tools.media.audio.attachments` to process multiple voice notes (`mode: "all"` + `maxAttachments`).
+- Transcript is available to templates as `{{Transcript}}`.
+- CLI stdout is capped (5MB); keep CLI output concise.
+
+## Gotchas
+- Scope rules use first-match wins. `chatType` is normalized to `direct`, `group`, or `room`.
+- Ensure your CLI exits 0 and prints plain text; JSON needs to be massaged via `jq -r .text`.
+- Keep timeouts reasonable (`timeoutSeconds`, default 60s) to avoid blocking the reply queue.

package/docs/nodes/camera.md

@@ -0,0 +1,152 @@
+---
+summary: "Camera capture (iOS node + macOS app) for agent use: photos (jpg) and short video clips (mp4)"
+read_when:
+  - Adding or modifying camera capture on iOS nodes or macOS
+  - Extending agent-accessible MEDIA temp-file workflows
+---
+
+# Camera capture (agent)
+
+Clawdbot supports **camera capture** for agent workflows:
+
+- **iOS node** (paired via Gateway): capture a **photo** (`jpg`) or **short video clip** (`mp4`, with optional audio) via `node.invoke`.
+- **Android node** (paired via Gateway): capture a **photo** (`jpg`) or **short video clip** (`mp4`, with optional audio) via `node.invoke`.
+- **macOS app** (node via Gateway): capture a **photo** (`jpg`) or **short video clip** (`mp4`, with optional audio) via `node.invoke`.
+
+All camera access is gated behind **user-controlled settings**.
+
+## iOS node
+
+### User setting (default on)
+
+- iOS Settings tab → **Camera** → **Allow Camera** (`camera.enabled`)
+  - Default: **on** (missing key is treated as enabled).
+  - When off: `camera.*` commands return `CAMERA_DISABLED`.
+
+### Commands (via Gateway `node.invoke`)
+
+- `camera.list`
+  - Response payload:
+    - `devices`: array of `{ id, name, position, deviceType }`
+
+- `camera.snap`
+  - Params:
+    - `facing`: `front|back` (default: `front`)
+    - `maxWidth`: number (optional; default `1600` on the iOS node)
+    - `quality`: `0..1` (optional; default `0.9`)
+    - `format`: currently `jpg`
+    - `delayMs`: number (optional; default `0`)
+    - `deviceId`: string (optional; from `camera.list`)
+  - Response payload:
+    - `format: "jpg"`
+    - `base64: "<...>"`
+    - `width`, `height`
+  - Payload guard: photos are recompressed to keep the base64 payload under 5 MB.
+
+- `camera.clip`
+  - Params:
+    - `facing`: `front|back` (default: `front`)
+    - `durationMs`: number (default `3000`, clamped to a max of `60000`)
+    - `includeAudio`: boolean (default `true`)
+    - `format`: currently `mp4`
+    - `deviceId`: string (optional; from `camera.list`)
+  - Response payload:
+    - `format: "mp4"`
+    - `base64: "<...>"`
+    - `durationMs`
+    - `hasAudio`
+
+### Foreground requirement
+
+Like `canvas.*`, the iOS node only allows `camera.*` commands in the **foreground**. Background invocations return `NODE_BACKGROUND_UNAVAILABLE`.
+
+### CLI helper (temp files + MEDIA)
+
+The easiest way to get attachments is via the CLI helper, which writes decoded media to a temp file and prints `MEDIA:<path>`.
+
+Examples:
+
+```bash
+clawdbot nodes camera snap --node <id>               # default: both front + back (2 MEDIA lines)
+clawdbot nodes camera snap --node <id> --facing front
+clawdbot nodes camera clip --node <id> --duration 3000
+clawdbot nodes camera clip --node <id> --no-audio
+```
+
+Notes:
+- `nodes camera snap` defaults to **both** facings to give the agent both views.
+- Output files are temporary (in the OS temp directory) unless you build your own wrapper.
+
+## Android node
+
+### User setting (default on)
+
+- Android Settings sheet → **Camera** → **Allow Camera** (`camera.enabled`)
+  - Default: **on** (missing key is treated as enabled).
+  - When off: `camera.*` commands return `CAMERA_DISABLED`.
+
+### Permissions
+
+- Android requires runtime permissions:
+  - `CAMERA` for both `camera.snap` and `camera.clip`.
+  - `RECORD_AUDIO` for `camera.clip` when `includeAudio=true`.
+
+If permissions are missing, the app will prompt when possible; if denied, `camera.*` requests fail with a
+`*_PERMISSION_REQUIRED` error.
+
+### Foreground requirement
+
+Like `canvas.*`, the Android node only allows `camera.*` commands in the **foreground**. Background invocations return `NODE_BACKGROUND_UNAVAILABLE`.
+
+### Payload guard
+
+Photos are recompressed to keep the base64 payload under 5 MB.
+
+## macOS app
+
+### User setting (default off)
+
+The macOS companion app exposes a checkbox:
+
+- **Settings → General → Allow Camera** (`clawdbot.cameraEnabled`)
+  - Default: **off**
+  - When off: camera requests return “Camera disabled by user”.
+
+### CLI helper (node invoke)
+
+Use the main `clawdbot` CLI to invoke camera commands on the macOS node.
+
+Examples:
+
+```bash
+clawdbot nodes camera list --node <id>            # list camera ids
+clawdbot nodes camera snap --node <id>            # prints MEDIA:<path>
+clawdbot nodes camera snap --node <id> --max-width 1280
+clawdbot nodes camera snap --node <id> --delay-ms 2000
+clawdbot nodes camera snap --node <id> --device-id <id>
+clawdbot nodes camera clip --node <id> --duration 10s          # prints MEDIA:<path>
+clawdbot nodes camera clip --node <id> --duration-ms 3000      # prints MEDIA:<path> (legacy flag)
+clawdbot nodes camera clip --node <id> --device-id <id>
+clawdbot nodes camera clip --node <id> --no-audio
+```
+
+Notes:
+- `clawdbot nodes camera snap` defaults to `maxWidth=1600` unless overridden.
+- On macOS, `camera.snap` waits `delayMs` (default 2000ms) after warm-up/exposure settle before capturing.
+- Photo payloads are recompressed to keep base64 under 5 MB.
+
+## Safety + practical limits
+
+- Camera and microphone access trigger the usual OS permission prompts (and require usage strings in Info.plist).
+- Video clips are capped (currently `<= 60s`) to avoid oversized node payloads (base64 overhead + message limits).
+
+## macOS screen video (OS-level)
+
+For *screen* video (not camera), use the macOS companion:
+
+```bash
+clawdbot nodes screen record --node <id> --duration 10s --fps 15   # prints MEDIA:<path>
+```
+
+Notes:
+- Requires macOS **Screen Recording** permission (TCC).

package/docs/nodes/images.md

@@ -0,0 +1,61 @@
+---
+summary: "Image and media handling rules for send, gateway, and agent replies"
+read_when:
+  - Modifying media pipeline or attachments
+---
+# Image & Media Support — 2025-12-05
+
+The WhatsApp channel runs via **Baileys Web**. This document captures the current media handling rules for send, gateway, and agent replies.
+
+## Goals
+- Send media with optional captions via `clawdbot message send --media`.
+- Allow auto-replies from the web inbox to include media alongside text.
+- Keep per-type limits sane and predictable.
+
+## CLI Surface
+- `clawdbot message send --media <path-or-url> [--message <caption>]`
+  - `--media` optional; caption can be empty for media-only sends.
+  - `--dry-run` prints the resolved payload; `--json` emits `{ channel, to, messageId, mediaUrl, caption }`.
+
+## WhatsApp Web channel behavior
+- Input: local file path **or** HTTP(S) URL.
+- Flow: load into a Buffer, detect media kind, and build the correct payload:
+  - **Images:** resize & recompress to JPEG (max side 2048px) targeting `agents.defaults.mediaMaxMb` (default 5 MB), capped at 6 MB.
+  - **Audio/Voice/Video:** pass-through up to 16 MB; audio is sent as a voice note (`ptt: true`).
+  - **Documents:** anything else, up to 100 MB, with filename preserved when available.
+- WhatsApp GIF-style playback: send an MP4 with `gifPlayback: true` (CLI: `--gif-playback`) so mobile clients loop inline.
+- MIME detection prefers magic bytes, then headers, then file extension.
+- Caption comes from `--message` or `reply.text`; empty caption is allowed.
+- Logging: non-verbose shows `↩️`/`✅`; verbose includes size and source path/URL.
+
+## Auto-Reply Pipeline
+- `getReplyFromConfig` returns `{ text?, mediaUrl?, mediaUrls? }`.
+- When media is present, the web sender resolves local paths or URLs using the same pipeline as `clawdbot message send`.
+- Multiple media entries are sent sequentially if provided.
+
+## Inbound Media to Commands (Pi)
+- When inbound web messages include media, Clawdbot downloads to a temp file and exposes templating variables:
+  - `{{MediaUrl}}` pseudo-URL for the inbound media.
+  - `{{MediaPath}}` local temp path written before running the command.
+- When a per-session Docker sandbox is enabled, inbound media is copied into the sandbox workspace and `MediaPath`/`MediaUrl` are rewritten to a relative path like `media/inbound/<filename>`.
+- Media understanding (if configured via `tools.media.*` or shared `tools.media.models`) runs before templating and can insert `[Image]`, `[Audio]`, and `[Video]` blocks into `Body`.
+  - Audio sets `{{Transcript}}` and uses the transcript for command parsing so slash commands still work.
+  - Video and image descriptions preserve any caption text for command parsing.
+- By default only the first matching image/audio/video attachment is processed; set `tools.media.<cap>.attachments` to process multiple attachments.
+
+## Limits & Errors
+**Outbound send caps (WhatsApp web send)**
+- Images: ~6 MB cap after recompression.
+- Audio/voice/video: 16 MB cap; documents: 100 MB cap.
+- Oversize or unreadable media → clear error in logs and the reply is skipped.
+
+**Media understanding caps (transcription/description)**
+- Image default: 10 MB (`tools.media.image.maxBytes`).
+- Audio default: 20 MB (`tools.media.audio.maxBytes`).
+- Video default: 50 MB (`tools.media.video.maxBytes`).
+- Oversize media skips understanding, but replies still go through with the original body.
+
+## Notes for Tests
+- Cover send + reply flows for image/audio/document cases.
+- Validate recompression for images (size bound) and voice-note flag for audio.
+- Ensure multi-media replies fan out as sequential sends.

package/docs/nodes/index.md

@@ -0,0 +1,305 @@
+---
+summary: "Nodes: pairing, capabilities, permissions, and CLI helpers for canvas/camera/screen/system"
+read_when:
+  - Pairing iOS/Android nodes to a gateway
+  - Using node canvas/camera for agent context
+  - Adding new node commands or CLI helpers
+---
+
+# Nodes
+
+A **node** is a companion device (macOS/iOS/Android/headless) that connects to the Gateway **WebSocket** (same port as operators) with `role: "node"` and exposes a command surface (e.g. `canvas.*`, `camera.*`, `system.*`) via `node.invoke`. Protocol details: [Gateway protocol](/gateway/protocol).
+
+Legacy transport: [Bridge protocol](/gateway/bridge-protocol) (TCP JSONL; deprecated/removed for current nodes).
+
+macOS can also run in **node mode**: the menubar app connects to the Gateway’s WS server and exposes its local canvas/camera commands as a node (so `clawdbot nodes …` works against this Mac).
+
+Notes:
+- Nodes are **peripherals**, not gateways. They don’t run the gateway service.
+- Telegram/WhatsApp/etc. messages land on the **gateway**, not on nodes.
+
+## Pairing + status
+
+**WS nodes use device pairing.** Nodes present a device identity during `connect`; the Gateway
+creates a device pairing request for `role: node`. Approve via the devices CLI (or UI).
+
+Quick CLI:
+
+```bash
+clawdbot devices list
+clawdbot devices approve <requestId>
+clawdbot devices reject <requestId>
+clawdbot nodes status
+clawdbot nodes describe --node <idOrNameOrIp>
+```
+
+Notes:
+- `nodes status` marks a node as **paired** when its device pairing role includes `node`.
+- `node.pair.*` (CLI: `clawdbot nodes pending/approve/reject`) is a separate gateway-owned
+  node pairing store; it does **not** gate the WS `connect` handshake.
+
+## Remote node host (system.run)
+
+Use a **node host** when your Gateway runs on one machine and you want commands
+to execute on another. The model still talks to the **gateway**; the gateway
+forwards `exec` calls to the **node host** when `host=node` is selected.
+
+### What runs where
+- **Gateway host**: receives messages, runs the model, routes tool calls.
+- **Node host**: executes `system.run`/`system.which` on the node machine.
+- **Approvals**: enforced on the node host via `~/.clawdbot/exec-approvals.json`.
+
+### Start a node host (foreground)
+
+On the node machine:
+
+```bash
+clawdbot node run --host <gateway-host> --port 18789 --display-name "Build Node"
+```
+
+### Start a node host (service)
+
+```bash
+clawdbot node install --host <gateway-host> --port 18789 --display-name "Build Node"
+clawdbot node restart
+```
+
+### Pair + name
+
+On the gateway host:
+
+```bash
+clawdbot nodes pending
+clawdbot nodes approve <requestId>
+clawdbot nodes list
+```
+
+Naming options:
+- `--display-name` on `clawdbot node run` / `clawdbot node install` (persists in `~/.clawdbot/node.json` on the node).
+- `clawdbot nodes rename --node <id|name|ip> --name "Build Node"` (gateway override).
+
+### Allowlist the commands
+
+Exec approvals are **per node host**. Add allowlist entries from the gateway:
+
+```bash
+clawdbot approvals allowlist add --node <id|name|ip> "/usr/bin/uname"
+clawdbot approvals allowlist add --node <id|name|ip> "/usr/bin/sw_vers"
+```
+
+Approvals live on the node host at `~/.clawdbot/exec-approvals.json`.
+
+### Point exec at the node
+
+Configure defaults (gateway config):
+
+```bash
+clawdbot config set tools.exec.host node
+clawdbot config set tools.exec.security allowlist
+clawdbot config set tools.exec.node "<id-or-name>"
+```
+
+Or per session:
+
+```
+/exec host=node security=allowlist node=<id-or-name>
+```
+
+Once set, any `exec` call with `host=node` runs on the node host (subject to the
+node allowlist/approvals).
+
+Related:
+- [Node host CLI](/cli/node)
+- [Exec tool](/tools/exec)
+- [Exec approvals](/tools/exec-approvals)
+
+## Invoking commands
+
+Low-level (raw RPC):
+
+```bash
+clawdbot nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'
+```
+
+Higher-level helpers exist for the common “give the agent a MEDIA attachment” workflows.
+
+## Screenshots (canvas snapshots)
+
+If the node is showing the Canvas (WebView), `canvas.snapshot` returns `{ format, base64 }`.
+
+CLI helper (writes to a temp file and prints `MEDIA:<path>`):
+
+```bash
+clawdbot nodes canvas snapshot --node <idOrNameOrIp> --format png
+clawdbot nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9
+```
+
+### Canvas controls
+
+```bash
+clawdbot nodes canvas present --node <idOrNameOrIp> --target https://example.com
+clawdbot nodes canvas hide --node <idOrNameOrIp>
+clawdbot nodes canvas navigate https://example.com --node <idOrNameOrIp>
+clawdbot nodes canvas eval --node <idOrNameOrIp> --js "document.title"
+```
+
+Notes:
+- `canvas present` accepts URLs or local file paths (`--target`), plus optional `--x/--y/--width/--height` for positioning.
+- `canvas eval` accepts inline JS (`--js`) or a positional arg.
+
+### A2UI (Canvas)
+
+```bash
+clawdbot nodes canvas a2ui push --node <idOrNameOrIp> --text "Hello"
+clawdbot nodes canvas a2ui push --node <idOrNameOrIp> --jsonl ./payload.jsonl
+clawdbot nodes canvas a2ui reset --node <idOrNameOrIp>
+```
+
+Notes:
+- Only A2UI v0.8 JSONL is supported (v0.9/createSurface is rejected).
+
+## Photos + videos (node camera)
+
+Photos (`jpg`):
+
+```bash
+clawdbot nodes camera list --node <idOrNameOrIp>
+clawdbot nodes camera snap --node <idOrNameOrIp>            # default: both facings (2 MEDIA lines)
+clawdbot nodes camera snap --node <idOrNameOrIp> --facing front
+```
+
+Video clips (`mp4`):
+
+```bash
+clawdbot nodes camera clip --node <idOrNameOrIp> --duration 10s
+clawdbot nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio
+```
+
+Notes:
+- The node must be **foregrounded** for `canvas.*` and `camera.*` (background calls return `NODE_BACKGROUND_UNAVAILABLE`).
+- Clip duration is clamped (currently `<= 60s`) to avoid oversized base64 payloads.
+- Android will prompt for `CAMERA`/`RECORD_AUDIO` permissions when possible; denied permissions fail with `*_PERMISSION_REQUIRED`.
+
+## Screen recordings (nodes)
+
+Nodes expose `screen.record` (mp4). Example:
+
+```bash
+clawdbot nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
+clawdbot nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio
+```
+
+Notes:
+- `screen.record` requires the node app to be foregrounded.
+- Android will show the system screen-capture prompt before recording.
+- Screen recordings are clamped to `<= 60s`.
+- `--no-audio` disables microphone capture (supported on iOS/Android; macOS uses system capture audio).
+- Use `--screen <index>` to select a display when multiple screens are available.
+
+## Location (nodes)
+
+Nodes expose `location.get` when Location is enabled in settings.
+
+CLI helper:
+
+```bash
+clawdbot nodes location get --node <idOrNameOrIp>
+clawdbot nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000
+```
+
+Notes:
+- Location is **off by default**.
+- “Always” requires system permission; background fetch is best-effort.
+- The response includes lat/lon, accuracy (meters), and timestamp.
+
+## SMS (Android nodes)
+
+Android nodes can expose `sms.send` when the user grants **SMS** permission and the device supports telephony.
+
+Low-level invoke:
+
+```bash
+clawdbot nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from Clawdbot"}'
+```
+
+Notes:
+- The permission prompt must be accepted on the Android device before the capability is advertised.
+- Wi-Fi-only devices without telephony will not advertise `sms.send`.
+
+## System commands (node host / mac node)
+
+The macOS node exposes `system.run`, `system.notify`, and `system.execApprovals.get/set`.
+The headless node host exposes `system.run`, `system.which`, and `system.execApprovals.get/set`.
+
+Examples:
+
+```bash
+clawdbot nodes run --node <idOrNameOrIp> -- echo "Hello from mac node"
+clawdbot nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"
+```
+
+Notes:
+- `system.run` returns stdout/stderr/exit code in the payload.
+- `system.notify` respects notification permission state on the macOS app.
+- `system.run` supports `--cwd`, `--env KEY=VAL`, `--command-timeout`, and `--needs-screen-recording`.
+- `system.notify` supports `--priority <passive|active|timeSensitive>` and `--delivery <system|overlay|auto>`.
+- macOS nodes drop `PATH` overrides; headless node hosts only accept `PATH` when it prepends the node host PATH.
+- On macOS node mode, `system.run` is gated by exec approvals in the macOS app (Settings → Exec approvals).
+  Ask/allowlist/full behave the same as the headless node host; denied prompts return `SYSTEM_RUN_DENIED`.
+- On headless node host, `system.run` is gated by exec approvals (`~/.clawdbot/exec-approvals.json`).
+
+## Exec node binding
+
+When multiple nodes are available, you can bind exec to a specific node.
+This sets the default node for `exec host=node` (and can be overridden per agent).
+
+Global default:
+
+```bash
+clawdbot config set tools.exec.node "node-id-or-name"
+```
+
+Per-agent override:
+
+```bash
+clawdbot config get agents.list
+clawdbot config set agents.list[0].tools.exec.node "node-id-or-name"
+```
+
+Unset to allow any node:
+
+```bash
+clawdbot config unset tools.exec.node
+clawdbot config unset agents.list[0].tools.exec.node
+```
+
+## Permissions map
+
+Nodes may include a `permissions` map in `node.list` / `node.describe`, keyed by permission name (e.g. `screenRecording`, `accessibility`) with boolean values (`true` = granted).
+
+## Headless node host (cross-platform)
+
+Clawdbot can run a **headless node host** (no UI) that connects to the Gateway
+WebSocket and exposes `system.run` / `system.which`. This is useful on Linux/Windows
+or for running a minimal node alongside a server.
+
+Start it:
+
+```bash
+clawdbot node run --host <gateway-host> --port 18789
+```
+
+Notes:
+- Pairing is still required (the Gateway will show a node approval prompt).
+- The node host stores its node id, token, display name, and gateway connection info in `~/.clawdbot/node.json`.
+- Exec approvals are enforced locally via `~/.clawdbot/exec-approvals.json`
+  (see [Exec approvals](/tools/exec-approvals)).
+- On macOS, the headless node host prefers the companion app exec host when reachable and falls
+  back to local execution if the app is unavailable. Set `CLAWDBOT_NODE_EXEC_HOST=app` to require
+  the app, or `CLAWDBOT_NODE_EXEC_FALLBACK=0` to disable fallback.
+- Add `--tls` / `--tls-fingerprint` when the Gateway WS uses TLS.
+
+## Mac node mode
+
+- The macOS menubar app connects to the Gateway WS server as a node (so `clawdbot nodes …` works against this Mac).
+- In remote mode, the app opens an SSH tunnel for the Gateway port and connects to `localhost`.