clawdbot 2026.1.4-1

package/docs/bonjour.md

@@ -0,0 +1,159 @@
+---
+summary: "Bonjour/mDNS discovery + debugging (Gateway beacons, clients, and common failure modes)"
+read_when:
+  - Debugging Bonjour discovery issues on macOS/iOS
+  - Changing mDNS service types, TXT records, or discovery UX
+---
+# Bonjour / mDNS discovery
+
+Clawdbot uses Bonjour (mDNS / DNS-SD) as a **LAN-only convenience** to discover a running Gateway bridge transport. It is best-effort and does **not** replace SSH or Tailnet-based connectivity.
+
+## Wide-Area Bonjour (Unicast DNS-SD) over Tailscale
+
+If you want iOS node auto-discovery while the Gateway is on another network (e.g. Vienna ⇄ London), you can keep the `NWBrowser` UX but switch discovery from multicast mDNS (`local.`) to **unicast DNS-SD** (“Wide-Area Bonjour”) over Tailscale.
+
+High level:
+
+1) Run a DNS server on the gateway host (reachable via tailnet IP).
+2) Publish DNS-SD records for `_clawdbot-bridge._tcp` in a dedicated zone (example: `clawdbot.internal.`).
+3) Configure Tailscale **split DNS** so `clawdbot.internal` resolves via that DNS server for clients (including iOS).
+
+Clawdbot standardizes on the discovery domain `clawdbot.internal.` for this mode. iOS/Android nodes browse both `local.` and `clawdbot.internal.` automatically (no per-device knob).
+
+### Gateway config (recommended)
+
+On the gateway host (the machine running the Gateway bridge), add to `~/.clawdbot/clawdbot.json` (JSON5):
+
+```json5
+{
+  bridge: { bind: "tailnet" }, // tailnet-only (recommended)
+  discovery: { wideArea: { enabled: true } } // enables clawdbot.internal DNS-SD publishing
+}
+```
+
+### One-time DNS server setup (gateway host)
+
+On the gateway host (macOS), run:
+
+```bash
+clawdbot dns setup --apply
+```
+
+This installs CoreDNS and configures it to:
+- listen on port 53 **only** on the gateway’s Tailscale interface IPs
+- serve the zone `clawdbot.internal.` from the gateway-owned zone file `~/.clawdbot/dns/clawdbot.internal.db`
+
+The Gateway writes/updates that zone file when `discovery.wideArea.enabled` is true.
+
+Validate from any tailnet-connected machine:
+
+```bash
+dns-sd -B _clawdbot-bridge._tcp clawdbot.internal.
+dig @<TAILNET_IPV4> -p 53 _clawdbot-bridge._tcp.clawdbot.internal PTR +short
+```
+
+### Tailscale DNS settings
+
+In the Tailscale admin console:
+
+- Add a nameserver pointing at the gateway’s tailnet IP (UDP/TCP 53).
+- Add split DNS so the domain `clawdbot.internal` uses that nameserver.
+
+Once clients accept tailnet DNS, iOS nodes can browse `_clawdbot-bridge._tcp` in `clawdbot.internal.` without multicast.
+Wide-area beacons also include `tailnetDns` (when available) so the macOS app can auto-fill SSH targets off-LAN.
+
+### Bridge listener security (recommended)
+
+The bridge port (default `18790`) is a plain TCP service. By default it binds to `0.0.0.0`, which makes it reachable from *any* interface on the gateway machine (LAN/Wi‑Fi/Tailscale).
+
+For a tailnet-only setup, bind it to the Tailscale IP instead:
+
+- Set `bridge.bind: "tailnet"` in `~/.clawdbot/clawdbot.json`.
+- Restart the Gateway (or restart the macOS menubar app via `./scripts/restart-mac.sh` on that machine).
+
+This keeps the bridge reachable only from devices on your tailnet (while still listening on loopback for local/SSH port-forwards).
+
+## What advertises
+
+Only the **Node Gateway** (`clawd` / `clawdbot gateway`) advertises Bonjour beacons.
+
+- Implementation: `src/infra/bonjour.ts`
+- Gateway wiring: `src/gateway/server.ts`
+
+## Service types
+
+- `_clawdbot-bridge._tcp` — bridge transport beacon (used by macOS/iOS/Android nodes).
+
+## TXT keys (non-secret hints)
+
+The Gateway advertises small non-secret hints to make UI flows convenient:
+
+- `role=gateway`
+- `lanHost=<hostname>.local`
+- `sshPort=<port>` (defaults to 22 when not overridden)
+- `gatewayPort=<port>` (informational; the Gateway WS is typically loopback-only)
+- `bridgePort=<port>` (only when bridge is enabled)
+- `canvasPort=<port>` (only when the canvas host is enabled + reachable; default `18793`; serves `/__clawdbot__/canvas/`)
+- `cliPath=<path>` (optional; absolute path to a runnable `clawdbot` entrypoint or binary)
+- `tailnetDns=<magicdns>` (optional hint; auto-detected from Tailscale when available; may be absent)
+
+## Debugging on macOS
+
+Useful built-in tools:
+
+- Browse instances:
+  - `dns-sd -B _clawdbot-bridge._tcp local.`
+- Resolve one instance (replace `<instance>`):
+  - `dns-sd -L "<instance>" _clawdbot-bridge._tcp local.`
+
+If browsing shows instances but resolving fails, you’re usually hitting a LAN policy / multicast issue.
+
+## Debugging in Gateway logs
+
+The Gateway writes a rolling log file (printed on startup as `gateway log file: ...`).
+
+Look for `bonjour:` lines, especially:
+
+- `bonjour: advertise failed ...` (probing/announce failure)
+- `bonjour: ... name conflict resolved` / `hostname conflict resolved`
+- `bonjour: watchdog detected non-announced service; attempting re-advertise ...` (self-heal attempt after sleep/interface churn)
+
+## Debugging on iOS node
+
+The iOS node app discovers bridges via `NWBrowser` browsing `_clawdbot-bridge._tcp`.
+
+To capture what the browser is doing:
+
+- Settings → Bridge → Advanced → enable **Discovery Debug Logs**
+- Settings → Bridge → Advanced → open **Discovery Logs** → reproduce the “Searching…” / “No bridges found” case → **Copy**
+
+The log includes browser state transitions (`ready`, `waiting`, `failed`, `cancelled`) and result-set changes (added/removed counts).
+
+## Common failure modes
+
+- **Bonjour doesn’t cross networks**: London/Vienna style setups require Tailnet (MagicDNS/IP) or SSH.
+- **Multicast blocked**: some Wi‑Fi networks (enterprise/hotels) disable mDNS; expect “no results”.
+- **Sleep / interface churn**: macOS may temporarily drop mDNS results when switching networks; retry.
+- **Browse works but resolve fails (iOS “NoSuchRecord”)**: make sure the advertiser publishes a valid SRV target hostname.
+  - Implementation detail: `@homebridge/ciao` defaults `hostname` to the *service instance name* when `hostname` is omitted. If your instance name contains spaces/parentheses, some resolvers can fail to resolve the implied A/AAAA record.
+  - Fix: set an explicit DNS-safe `hostname` (single label; no `.local`) in `src/infra/bonjour.ts`.
+
+## Escaped instance names (`\\032`)
+Bonjour/DNS-SD often escapes bytes in service instance names as decimal `\\DDD` sequences (e.g. spaces become `\\032`).
+
+- This is normal at the protocol level.
+- UIs should decode for display (iOS uses `BonjourEscapes.decode` in `apps/shared/ClawdbotKit`).
+
+## Disabling / configuration
+
+- `CLAWDBOT_DISABLE_BONJOUR=1` disables advertising.
+- `CLAWDBOT_BRIDGE_ENABLED=0` disables the bridge listener (and therefore the bridge beacon).
+- `bridge.bind` / `bridge.port` in `~/.clawdbot/clawdbot.json` control bridge bind/port (preferred).
+- `CLAWDBOT_BRIDGE_HOST` / `CLAWDBOT_BRIDGE_PORT` still work as a back-compat override when `bridge.bind` / `bridge.port` are not set.
+- `CLAWDBOT_SSH_PORT` overrides the SSH port advertised in `_clawdbot-bridge._tcp`.
+- `CLAWDBOT_TAILNET_DNS` publishes a `tailnetDns` hint (MagicDNS) in `_clawdbot-bridge._tcp`. If unset, the gateway auto-detects Tailscale and publishes the MagicDNS name when possible.
+
+## Related docs
+
+- Discovery policy and transport selection: `docs/discovery.md`
+- Node pairing + approvals: `docs/gateway/pairing.md`

package/docs/browser.md

@@ -0,0 +1,289 @@
+---
+summary: "Spec: integrated browser control server + action commands"
+read_when:
+  - Adding agent-controlled browser automation
+  - Debugging why clawd is interfering with your own Chrome
+  - Implementing browser settings + lifecycle in the macOS app
+---
+
+# Browser (integrated) — clawd-managed Chrome
+
+Status: draft spec · Date: 2025-12-20
+
+Goal: give the **clawd** persona its own browser that is:
+- Visually distinct (lobster-orange, profile labeled "clawd").
+- Fully agent-manageable (start/stop, list tabs, focus/close tabs, open URLs, screenshot).
+- Non-interfering with the user's own browser (separate profile + dedicated ports).
+
+This doc covers the macOS app/gateway side. It intentionally does not mandate
+Playwright vs Puppeteer; the key is the **contract** and the **separation guarantees**.
+
+## User-facing settings
+
+Add a dedicated settings section (preferably under **Skills** or its own "Browser" tab):
+
+- **Enable clawd browser** (`default: on`)
+  - When off: no browser is launched, and browser tools return "disabled".
+- **Browser control URL** (`default: http://127.0.0.1:18791`)
+  - Interpreted as the base URL of the local/remote browser-control server.
+  - If the URL host is not loopback, Clawdbot must **not** attempt to launch a local
+    browser; it only connects.
+- **CDP URL** (`default: controlUrl + 1`)
+  - Base URL for Chrome DevTools Protocol (e.g. `http://127.0.0.1:18792`).
+  - Set this to a non-loopback host to attach the local control server to a remote
+    Chrome/Chromium CDP endpoint (SSH/Tailscale tunnel recommended).
+  - If the CDP URL host is non-loopback, clawd does **not** auto-launch a local browser.
+  - If you tunnel a remote CDP to `localhost`, set **Attach to existing only** to
+    avoid accidentally launching a local browser.
+- **Accent color** (`default: #FF4500`, "lobster-orange")
+  - Used to theme the clawd browser profile (best-effort) and to tint UI indicators
+    in Clawdbot.
+
+Optional (advanced, can be hidden behind Debug initially):
+- **Use headless browser** (`default: off`)
+- **Attach to existing only** (`default: off`) — if on, never launch; only connect if
+  already running.
+- **Browser executable path** (override, optional)
+- **No sandbox** (`default: off`) — adds `--no-sandbox` + `--disable-setuid-sandbox`
+
+### Port convention
+
+Clawdbot already uses:
+- Gateway WebSocket: `18789`
+- Bridge (voice/node): `18790`
+
+For the clawd browser-control server, use "family" ports:
+- Browser control HTTP API: `18791` (bridge + 1)
+- Browser CDP/debugging port: `18792` (control + 1)
+- Canvas host HTTP: `18793` by default, mounted at `/__clawdbot__/canvas/`
+
+The user usually only configures the **control URL** (port `18791`). CDP is an
+internal detail.
+
+## Browser isolation guarantees (non-negotiable)
+
+1) **Dedicated user data dir**
+   - Never attach to or reuse the user's default Chrome profile.
+   - Store clawd browser state under an app-owned directory, e.g.:
+     - `~/Library/Application Support/Clawdbot/browser/clawd/` (mac app)
+     - or `~/.clawdbot/browser/clawd/` (gateway/CLI)
+
+2) **Dedicated ports**
+   - Never use `9222` (reserved for ad-hoc dev workflows; avoids colliding with
+     `agent-tools/browser-tools`).
+   - Default ports are `18791/18792` unless overridden.
+
+3) **Named tab/page management**
+   - The agent must be able to enumerate and target tabs deterministically (by
+     stable `targetId` or equivalent), not "last tab".
+
+## Browser selection (macOS + Linux)
+
+On startup (when enabled + local URL), Clawdbot chooses the browser executable
+in this order:
+1) **Google Chrome Canary** (if installed)
+2) **Chromium** (if installed)
+3) **Google Chrome** (fallback)
+
+Linux:
+- Looks for `google-chrome` / `chromium` in common system paths.
+- Use **Browser executable path** to force a specific binary.
+
+Implementation detail:
+- macOS: detection is by existence of the `.app` bundle under `/Applications`
+  (and optionally `~/Applications`), then using the resolved executable path.
+- Linux: common `/usr/bin`/`/snap/bin` paths.
+
+Rationale:
+- Canary/Chromium are easy to visually distinguish from the user's daily driver.
+- Chrome fallback ensures the feature works on a stock machine.
+
+## Visual differentiation ("lobster-orange")
+
+The clawd browser should be obviously different at a glance:
+- Profile name: **clawd**
+- Profile color: **#FF4500**
+
+Preferred behavior:
+- Seed/patch the profile's preferences on first launch so the color + name persist.
+
+Fallback behavior:
+- If preferences patching is not reliable, open with the dedicated profile and let
+  the user set the profile color/name once via Chrome UI; it must persist because
+  the `userDataDir` is persistent.
+
+## Control server contract (vNext)
+
+Expose a small local HTTP API (and/or gateway RPC surface) so the agent can manage
+state without touching the user's Chrome.
+
+Basics:
+- `GET /` status payload (enabled/running/pid/cdpPort/etc)
+- `POST /start` start browser
+- `POST /stop` stop browser
+- `GET /tabs` list tabs
+- `POST /tabs/open` open a new tab
+- `POST /tabs/focus` focus a tab by id/prefix
+- `DELETE /tabs/:targetId` close a tab by id/prefix
+
+Inspection:
+- `POST /screenshot` `{ targetId?, fullPage?, ref?, element?, type? }`
+- `GET /snapshot` `?format=aria|ai&targetId?&limit?`
+- `GET /console` `?level?&targetId?`
+- `POST /pdf` `{ targetId? }`
+
+Actions:
+- `POST /navigate`
+- `POST /act` `{ kind, targetId?, ... }` where `kind` is one of:
+  - `click`, `type`, `press`, `hover`, `drag`, `select`, `fill`, `wait`, `resize`, `close`, `evaluate`
+
+Hooks (arming):
+- `POST /hooks/file-chooser` `{ targetId?, paths, timeoutMs? }`
+- `POST /hooks/dialog` `{ targetId?, accept, promptText?, timeoutMs? }`
+
+### "Is it open or closed?"
+
+"Open" means:
+- the control server is reachable at the configured URL **and**
+- it reports a live browser connection.
+
+"Closed" means:
+- control server not reachable, or server reports no browser.
+
+Clawdbot should treat "open/closed" as a health check (fast path), not by scanning
+global Chrome processes (avoid false positives).
+
+## Multi-profile support
+
+Clawdbot supports multiple named browser profiles, each with:
+- Dedicated CDP port (auto-allocated from 18800-18899) **or** a per-profile CDP URL
+- Persistent user data directory (`~/.clawdbot/browser/<name>/user-data/`)
+- Unique color for visual distinction
+
+### Configuration
+
+```json
+{
+  "browser": {
+    "enabled": true,
+    "defaultProfile": "clawd",
+    "profiles": {
+      "clawd": { "cdpPort": 18800, "color": "#FF4500" },
+      "work": { "cdpPort": 18801, "color": "#0066CC" },
+      "remote": { "cdpUrl": "http://10.0.0.42:9222", "color": "#00AA00" }
+    }
+  }
+}
+```
+
+### Profile actions
+
+- `GET /profiles` — list all profiles with status
+- `POST /profiles/create` `{ name, color?, cdpUrl? }` — create new profile (auto-allocates port if no `cdpUrl`)
+- `DELETE /profiles/:name` — delete profile (stops browser + removes user data for local profiles)
+- `POST /reset-profile?profile=<name>` — kill orphan process on profile's port (local profiles only)
+
+### Profile parameter
+
+All existing endpoints accept optional `?profile=<name>` query parameter:
+- `GET /?profile=work` — status for work profile
+- `POST /start?profile=work` — start work profile browser
+- `GET /tabs?profile=work` — list tabs for work profile
+- etc.
+
+When `profile` is omitted, uses `browser.defaultProfile` (defaults to "clawd").
+
+### Profile naming rules
+
+- Lowercase alphanumeric characters and hyphens only
+- Must start with a letter or number (not a hyphen)
+- Maximum 64 characters
+- Examples: `clawd`, `work`, `my-project-1`
+
+### Port allocation
+
+Ports are allocated from range 18800-18899 (~100 profiles max). This is far more
+than practical use — memory and CPU exhaustion occur well before port exhaustion.
+Ports are allocated once at profile creation and persisted permanently.
+Remote profiles are attach-only and do **not** use the local port range.
+## Interaction with the agent (clawd)
+
+The agent should use browser tools only when:
+- enabled in settings
+- control URL is configured
+
+If disabled, tools must fail fast with a friendly error ("Browser disabled in settings").
+
+The agent should not assume tabs are ephemeral. It should:
+- call `browser.tabs.list` to discover existing tabs first
+- reuse an existing tab when appropriate (e.g. a persistent "main" tab)
+- avoid opening duplicate tabs unless asked
+
+## CLI quick reference (one example each)
+
+All commands accept `--profile <name>` to target a specific profile (default: `clawd`).
+
+Profile management:
+- `clawdbot browser profiles`
+- `clawdbot browser create-profile --name work`
+- `clawdbot browser create-profile --name remote --cdp-url http://10.0.0.42:9222`
+- `clawdbot browser delete-profile --name work`
+Basics:
+- `clawdbot browser status`
+- `clawdbot browser start`
+- `clawdbot browser stop`
+- `clawdbot browser reset-profile`
+- `clawdbot browser tabs`
+- `clawdbot browser open https://example.com`
+- `clawdbot browser focus abcd1234`
+- `clawdbot browser close abcd1234`
+
+Inspection:
+- `clawdbot browser screenshot`
+- `clawdbot browser screenshot --full-page`
+- `clawdbot browser screenshot --ref 12`
+- `clawdbot browser snapshot`
+- `clawdbot browser snapshot --format aria --limit 200`
+
+Actions:
+- `clawdbot browser navigate https://example.com`
+- `clawdbot browser resize 1280 720`
+- `clawdbot browser click 12 --double`
+- `clawdbot browser type 23 "hello" --submit`
+- `clawdbot browser press Enter`
+- `clawdbot browser hover 44`
+- `clawdbot browser drag 10 11`
+- `clawdbot browser select 9 OptionA OptionB`
+- `clawdbot browser upload /tmp/file.pdf`
+- `clawdbot browser fill --fields '[{\"ref\":\"1\",\"value\":\"Ada\"}]'`
+- `clawdbot browser dialog --accept`
+- `clawdbot browser wait --text "Done"`
+- `clawdbot browser evaluate --fn '(el) => el.textContent' --ref 7`
+- `clawdbot browser evaluate --fn "document.querySelector('.my-class').click()"`
+- `clawdbot browser console --level error`
+- `clawdbot browser pdf`
+
+Notes:
+- `upload` and `dialog` are **arming** calls; run them before the click/press that triggers the chooser/dialog.
+- `upload` can take a `ref` to auto-click after arming (useful for single-step file uploads).
+- `upload` can also take `inputRef` (aria ref) or `element` (CSS selector) to set `<input type="file">` directly without waiting for a file chooser.
+- The arm default timeout is **2 minutes** (clamped to max 2 minutes); pass `timeoutMs` if you need shorter.
+- `snapshot` defaults to `ai`; `aria` returns an accessibility tree for debugging.
+- `click`/`type` require `ref` from `snapshot --format ai`; use `evaluate` for rare CSS selector one-offs.
+- Avoid `wait` by default; use it only in exceptional cases when there is no reliable UI state to wait on.
+
+## Security & privacy notes
+
+- The clawd browser profile is app-owned; it may contain logged-in sessions.
+  Treat it as sensitive data.
+- The control server must bind to loopback only by default (`127.0.0.1`) unless the
+  user explicitly configures a non-loopback URL.
+- Never reuse or copy the user's default Chrome profile.
+- Remote CDP endpoints should be tunneled or protected; CDP is highly privileged.
+
+## Non-goals (for the first cut)
+
+- Cross-device "sync" of tabs between Mac and Pi.
+- Sharing the user's logged-in Chrome sessions automatically.
+- General-purpose web scraping; this is primarily for "close-the-loop" verification
+  and interaction.

package/docs/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 bridge 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).