clawdbot 2026.1.4-1

package/docs/AGENTS.default.md

@@ -0,0 +1,116 @@
+---
+summary: "Default Clawdbot agent instructions and skills roster for the personal assistant setup"
+read_when:
+  - Starting a new Clawdbot agent session
+  - Enabling or auditing default skills
+---
+# AGENTS.md — Clawdbot Personal Assistant (default)
+
+## First run (recommended)
+
+Clawdbot uses a dedicated workspace directory for the agent. Default: `~/.clawdbot/workspace`.
+
+1) Create the workspace (if it doesn’t already exist):
+
+```bash
+mkdir -p ~/.clawdbot/workspace
+```
+
+2) Copy the default workspace templates into the workspace:
+
+```bash
+cp docs/templates/AGENTS.md ~/.clawdbot/workspace/AGENTS.md
+cp docs/templates/SOUL.md ~/.clawdbot/workspace/SOUL.md
+cp docs/templates/TOOLS.md ~/.clawdbot/workspace/TOOLS.md
+```
+
+3) Optional: if you want the personal assistant skill roster, replace AGENTS.md with this file:
+
+```bash
+cp docs/AGENTS.default.md ~/.clawdbot/workspace/AGENTS.md
+```
+
+4) Optional: choose a different workspace by setting `agent.workspace` (supports `~`):
+
+```json5
+{
+  agent: {
+    workspace: "~/clawd"
+  }
+}
+```
+
+## Safety defaults
+- Don’t dump directories or secrets into chat.
+- Don’t run destructive commands unless explicitly asked.
+- Don’t send partial/streaming replies to external messaging surfaces (only final replies).
+
+## Session start (required)
+- Read `SOUL.md`, `USER.md`, `memory.md`, and today+yesterday in `memory/`.
+- Do it before responding.
+
+## Soul (required)
+- `SOUL.md` defines identity, tone, and boundaries. Keep it current.
+- If you change `SOUL.md`, tell the user.
+- You are a fresh instance each session; continuity lives in these files.
+
+## Shared spaces (recommended)
+- You’re not the user’s voice; be careful in group chats or public channels.
+- Don’t share private data, contact info, or internal notes.
+
+## Memory system (recommended)
+- Daily log: `memory/YYYY-MM-DD.md` (create `memory/` if needed).
+- Long-term memory: `memory.md` for durable facts, preferences, and decisions.
+- On session start, read today + yesterday + `memory.md` if present.
+- Capture: decisions, preferences, constraints, open loops.
+- Avoid secrets unless explicitly requested.
+
+## Tools & skills
+- Tools live in skills; follow each skill’s `SKILL.md` when you need it.
+- Keep environment-specific notes in `TOOLS.md` (Notes for Skills).
+
+## Backup tip (recommended)
+If you treat this workspace as Clawd’s “memory”, make it a git repo (ideally private) so `AGENTS.md` and your memory files are backed up.
+
+```bash
+cd ~/.clawdbot/workspace
+git init
+git add AGENTS.md
+git commit -m "Add Clawd workspace"
+# Optional: add a private remote + push
+```
+
+## What Clawdbot Does
+- Runs WhatsApp gateway + Pi coding agent so the assistant can read/write chats, fetch context, and run skills via the host Mac.
+- macOS app manages permissions (screen recording, notifications, microphone) and exposes the `clawdbot` CLI via its bundled binary.
+- Direct chats collapse into the shared `main` session by default; groups stay isolated as `surface:group:<id>` (rooms: `surface:channel:<id>`); heartbeats keep background tasks alive.
+
+## Core Skills (enable in Settings → Skills)
+- **mcporter** — Tool server runtime/CLI for managing external skill backends.
+- **Peekaboo** — Fast macOS screenshots with optional AI vision analysis.
+- **camsnap** — Capture frames, clips, or motion alerts from RTSP/ONVIF security cams.
+- **oracle** — OpenAI-ready agent CLI with session replay and browser control.
+- **qmd** — Hybrid markdown search (BM25 + vectors + rerank) with a local server for agents.
+- **eightctl** — Control your sleep, from the terminal.
+- **imsg** — Send, read, stream iMessage & SMS.
+- **wacli** — WhatsApp CLI: sync, search, send.
+- **discord** — Discord actions: react, stickers, polls.
+- **gog** — Google Suite CLI: Gmail, Calendar, Drive, Contacts.
+- **spotify-player** — Terminal Spotify client to search/queue/control playback.
+- **sag** — ElevenLabs speech with mac-style say UX; streams to speakers by default.
+- **Sonos CLI** — Control Sonos speakers (discover/status/playback/volume/grouping) from scripts.
+- **blucli** — Play, group, and automate BluOS players from scripts.
+- **OpenHue CLI** — Philips Hue lighting control for scenes and automations.
+- **OpenAI Whisper** — Local speech-to-text for quick dictation and voicemail transcripts.
+- **Gemini CLI** — Google Gemini models from the terminal for fast Q&A.
+- **bird** — X/Twitter CLI to tweet, reply, read threads, and search without a browser.
+- **agent-tools** — Utility toolkit for automations and helper scripts.
+
+## Usage Notes
+- Prefer the `clawdbot` CLI for scripting; mac app handles permissions.
+- Run installs from the Skills tab; it hides the button if a binary is already present.
+- Keep heartbeats enabled so the assistant can schedule reminders, monitor inboxes, and trigger camera captures.
+- Canvas UI runs full-screen with native overlays. Avoid placing critical controls in the top-left/top-right/bottom edges; add explicit gutters in the layout and don’t rely on safe-area insets.
+- For browser-driven verification, use `clawdbot browser` (tabs/status/screenshot) with the clawd-managed Chrome profile.
+- For DOM inspection, use `clawdbot browser eval|query|dom|snapshot` (and `--json`/`--out` when you need machine output).
+- For interactions, use `clawdbot browser click|type|hover|drag|select|upload|press|wait|navigate|back|evaluate|run` (click/type require snapshot refs; use `evaluate` for CSS selectors).

package/docs/CNAME

@@ -0,0 +1 @@
+clawdbot.com

package/docs/RELEASING.md

@@ -0,0 +1,64 @@
+---
+summary: "Step-by-step release checklist for npm + macOS app"
+read_when:
+  - Cutting a new npm release
+  - Cutting a new macOS app release
+  - Verifying metadata before publishing
+---
+
+# Release Checklist (npm + macOS)
+
+Use `pnpm` (Node 22+) from the repo root. Keep the working tree clean before tagging/publishing.
+
+1) **Version & metadata**
+- [ ] Bump `package.json` version (e.g., `1.1.0`).
+- [ ] Update CLI/version strings: `src/cli/program.ts` and the Baileys user agent in `src/provider-web.ts`.
+- [ ] Confirm package metadata (name, description, repository, keywords, license) and `bin` map points to `dist/index.js` for `clawdbot`.
+- [ ] If dependencies changed, run `pnpm install` so `pnpm-lock.yaml` is current.
+
+2) **Build & artifacts**
+- [ ] If A2UI inputs changed, run `pnpm canvas:a2ui:bundle` and commit any updated `src/canvas-host/a2ui/a2ui.bundle.js`.
+- [ ] `pnpm run build` (regenerates `dist/`).
+- [ ] Optional: `npm pack --pack-destination /tmp` after the build; inspect the tarball contents and keep it handy for the GitHub release (do **not** commit it).
+
+3) **Changelog & docs**
+- [ ] Update `CHANGELOG.md` with user-facing highlights (create the file if missing); keep entries strictly descending by version.
+- [ ] Ensure README examples/flags match current CLI behavior (notably new commands or options).
+
+4) **Validation**
+- [ ] `pnpm lint`
+- [ ] `pnpm test` (or `pnpm test:coverage` if you need coverage output)
+- [ ] `pnpm run build` (last sanity check after tests)
+- [ ] `pnpm release:check` (verifies npm pack contents)
+- [ ] (Optional) Spot-check the web gateway if your changes affect send/receive paths.
+
+5) **macOS app (Sparkle)**
+- [ ] Build + sign the macOS app, then zip it for distribution.
+- [ ] Generate the Sparkle appcast (HTML notes via `scripts/make_appcast.sh`) and update `appcast.xml`.
+- [ ] Keep the app zip (and optional dSYM zip) ready to attach to the GitHub release.
+- [ ] Follow `docs/mac/release.md` for the exact commands and required env vars.
+  - `APP_BUILD` must be numeric + monotonic (no `-beta`) so Sparkle compares versions correctly.
+  - If notarizing, use the `clawdbot-notary` keychain profile created from App Store Connect API env vars (see `docs/mac/release.md`).
+
+6) **Publish (npm)**
+- [ ] Confirm git status is clean; commit and push as needed.
+- [ ] `npm login` (verify 2FA) if needed.
+- [ ] `npm publish --access public` (use `--tag beta` for pre-releases).
+- [ ] Verify the registry: `npm view clawdbot version` and `npx -y clawdbot@X.Y.Z --version` (or `--help`).
+
+### Troubleshooting (notes from 2.0.0-beta2 release)
+- **npm pack/publish hangs or produces huge tarball**: the macOS app bundle in `dist/Clawdbot.app` (and release zips) get swept into the package. Fix by whitelisting publish contents via `package.json` `files` (include dist subdirs, docs, skills; exclude app bundles). Confirm with `npm pack --dry-run` that `dist/Clawdbot.app` is not listed.
+- **npm auth web loop for dist-tags**: use legacy auth to get an OTP prompt:
+  - `NPM_CONFIG_AUTH_TYPE=legacy npm dist-tag add clawdbot@X.Y.Z latest`
+- **`npx` verification fails with `ECOMPROMISED: Lock compromised`**: retry with a fresh cache:
+  - `NPM_CONFIG_CACHE=/tmp/npm-cache-$(date +%s) npx -y clawdbot@X.Y.Z --version`
+- **Tag needs repointing after a late fix**: force-update and push the tag, then ensure the GitHub release assets still match:
+  - `git tag -f vX.Y.Z && git push -f origin vX.Y.Z`
+
+7) **GitHub release + appcast**
+- [ ] Tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z` (or `git push --tags`).
+- [ ] Create/refresh the GitHub release for `vX.Y.Z` with **title `clawdbot X.Y.Z`** (not just the tag); body should inline the product-facing bullets from the changelog (no bare links) **and must not repeat the title inside the body**.
+- [ ] Attach artifacts: `npm pack` tarball (optional), `Clawdbot-X.Y.Z.zip`, and `Clawdbot-X.Y.Z.dSYM.zip` (if generated).
+- [ ] Commit the updated `appcast.xml` and push it (Sparkle feeds from main).
+- [ ] From a clean temp directory (no `package.json`), run `npx -y clawdbot@X.Y.Z send --help` to confirm install/CLI entrypoints work.
+- [ ] Announce/share release notes.

package/docs/_config.yml

@@ -0,0 +1,51 @@
+title: "CLAWDBOT Docs"
+description: "A TypeScript/Node gateway + macOS/iOS companions for WhatsApp (web) and Telegram (bot)."
+markdown: kramdown
+highlighter: rouge
+
+# Keep GitHub Pages' default page URLs (e.g. /gateway.html). Many docs links
+# are written as relative *.md links and are rewritten during the build.
+
+plugins:
+  - jekyll-relative-links
+
+relative_links:
+  enabled: true
+  collections: true
+
+defaults:
+  - scope:
+      path: ""
+    values:
+      layout: default
+
+nav:
+  - title: "Home"
+    url: "/"
+  - title: "Clawd Setup"
+    url: "/clawd.html"
+  - title: "Gateway"
+    url: "/gateway.html"
+  - title: "Remote"
+    url: "/remote.html"
+  - title: "Discovery"
+    url: "/discovery.html"
+  - title: "Configuration"
+    url: "/configuration.html"
+  - title: "WebChat"
+    url: "/webchat.html"
+  - title: "macOS App"
+    url: "/clawdbot-mac.html"
+  - title: "iOS Node"
+    url: "/ios/connect.html"
+  - title: "Telegram"
+    url: "/telegram.html"
+  - title: "Security"
+    url: "/security.html"
+  - title: "Troubleshooting"
+    url: "/troubleshooting.html"
+
+kramdown:
+  input: GFM
+  hard_wrap: false
+  syntax_highlighter: rouge

package/docs/_layouts/default.html

@@ -0,0 +1,145 @@
+<!doctype html>
+<html lang="en" data-theme="auto">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="color-scheme" content="light dark" />
+    <title>
+      {% if page.url == "/" %}{{ site.title }}{% else %}{{ page.title | default: page.path | split: "/" | last | replace: ".md", "" }} · {{ site.title }}{% endif %}
+    </title>
+
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Pixelify+Sans:wght@400..700&family=Fragment+Mono:ital,wght@0,400;0,700;1,400;1,700&display=swap"
+      rel="stylesheet"
+    />
+    <script>
+      (() => {
+        try {
+          const stored = localStorage.getItem("clawdbot:theme");
+          if (stored === "light" || stored === "dark") document.documentElement.dataset.theme = stored;
+        } catch {
+          // ignore
+        }
+      })();
+    </script>
+    <link rel="stylesheet" href="{{ "/assets/terminal.css" | relative_url }}" />
+    <link rel="stylesheet" href="{{ "/assets/markdown.css" | relative_url }}" />
+    <script defer src="{{ "/assets/theme.js" | relative_url }}"></script>
+  </head>
+
+  <body>
+    <a class="skip-link" href="#content">Skip to content</a>
+
+    <header class="shell">
+      <div class="shell__frame" role="banner">
+        <div class="shell__titlebar">
+          <div class="brand" aria-label="CLAWDBOT docs terminal">
+            <img
+              class="brand__logo"
+              src="{{ "/assets/pixel-lobster.svg" | relative_url }}"
+              alt=""
+              width="40"
+              height="40"
+              decoding="async"
+            />
+            <div class="brand__text">
+              <div class="brand__name">CLAWDBOT</div>
+              <div class="brand__hint">docs // lobster terminal</div>
+            </div>
+          </div>
+
+          <div class="titlebar__actions">
+            <a class="titlebar__cta" href="https://github.com/clawdbot/clawdbot">
+              <span class="titlebar__cta-label">GitHub</span>
+              <span class="titlebar__cta-meta">repo</span>
+            </a>
+            <a class="titlebar__cta titlebar__cta--accent" href="https://github.com/clawdbot/clawdbot/releases/latest">
+              <span class="titlebar__cta-label">Download</span>
+              <span class="titlebar__cta-meta">latest</span>
+            </a>
+          </div>
+        </div>
+
+        <div class="shell__nav" aria-label="Primary">
+          <nav class="nav">
+            {% assign nav = site.nav | default: empty %}
+            {% for item in nav %}
+              {% assign item_url = item.url | relative_url %}
+              <a class="nav__link" href="{{ item_url }}">
+                <span class="nav__chev">›</span>{{ item.title }}
+              </a>
+            {% endfor %}
+          </nav>
+
+          <div class="shell__status" aria-hidden="true">
+            <span class="status__dot"></span>
+            <span class="status__text">
+              {% if page.url == "/" %}
+                ready
+              {% else %}
+                viewing: {{ page.path }}
+              {% endif %}
+            </span>
+          </div>
+        </div>
+      </div>
+    </header>
+
+    <main id="content" class="content" role="main">
+      <div class="terminal">
+        <div class="terminal__prompt" aria-hidden="true">
+          <span class="prompt__user">clawd</span>@<span class="prompt__host">clawdbot</span>:<span class="prompt__path">~/docs</span>$<span class="prompt__cmd">
+            {% if page.url == "/" %}cat index.md{% else %}less {{ page.path }}{% endif %}
+          </span>
+        </div>
+
+        {% if page.summary %}
+          <p class="terminal__summary">{{ page.summary }}</p>
+        {% endif %}
+
+        {% if page.read_when %}
+          <details class="terminal__meta">
+            <summary>Read when…</summary>
+            <ul>
+              {% for hint in page.read_when %}
+                <li>{{ hint }}</li>
+              {% endfor %}
+            </ul>
+          </details>
+        {% endif %}
+
+        <article class="markdown">
+          {{ content }}
+        </article>
+
+        <footer class="terminal__footer" role="contentinfo">
+          <div class="footer__line">
+            <span class="footer__sig">clawdbot.ai</span>
+            <span class="footer__sep">·</span>
+            <a href="https://github.com/clawdbot/clawdbot">source</a>
+            <span class="footer__sep">·</span>
+            <a href="https://github.com/clawdbot/clawdbot/releases">releases</a>
+          </div>
+          <div class="footer__hint" aria-hidden="true">
+            tip: press <kbd>F2</kbd> (Mac: <kbd>fn</kbd>+<kbd>F2</kbd>) to flip
+            the universe
+          </div>
+          <div class="footer__actions">
+            <button
+              class="theme-toggle"
+              type="button"
+              data-theme-toggle
+              aria-label="Toggle theme (F2; on Mac: fn+F2)"
+              aria-pressed="false"
+            >
+              <span class="theme-toggle__key">F2</span>
+              <span class="theme-toggle__label" data-theme-label>theme</span>
+            </button>
+          </div>
+	        </footer>
+	      </div>
+	    </main>
+	  </body>
+</html>

package/docs/agent-send.md

@@ -0,0 +1,21 @@
+---
+summary: "Design notes for a direct `clawdbot agent` CLI subcommand without WhatsApp delivery"
+read_when:
+  - Adding or modifying the agent CLI entrypoint
+---
+# `clawdbot agent` (direct-to-agent invocation)
+
+`clawdbot agent` lets you talk to the **embedded** agent runtime directly (no chat send unless you opt in), while reusing the same session store and thinking/verbose persistence as inbound auto-replies.
+
+## Behavior
+- Required: `--message <text>`
+- Session selection:
+  - If `--session-id` is given, reuse it.
+  - Else if `--to <e164>` is given, derive the session key from `session.scope` (direct chats collapse to `main`, or `global` when scope is global).
+- Runs the embedded Pi agent (configured via `agent`).
+- Thinking/verbose:
+  - Flags `--thinking <off|minimal|low|medium|high>` and `--verbose <on|off>` persist into the session store.
+- Output:
+  - Default: prints text (and `MEDIA:<url>` lines) to stdout.
+  - `--json`: prints structured payloads + meta.
+- Optional: `--deliver` sends the reply back to the selected provider (`whatsapp`, `telegram`, `discord`, `signal`, `imessage`).

package/docs/agent.md

@@ -0,0 +1,104 @@
+---
+summary: "Agent runtime (embedded p-mono), workspace contract, and session bootstrap"
+read_when:
+  - Changing agent runtime, workspace bootstrap, or session behavior
+---
+<!-- {% raw %} -->
+# Agent Runtime 🤖
+
+CLAWDBOT runs a single embedded agent runtime derived from **p-mono** (internal name: **p**).
+
+## Workspace (required)
+
+You must set an agent home directory via `agent.workspace`. CLAWDBOT uses this as the agent’s **only** working directory (`cwd`) for tools and context.
+
+Recommended: use `clawdbot setup` to create `~/.clawdbot/clawdbot.json` if missing and initialize the workspace files.
+
+If `agent.sandbox` is enabled, non-main sessions can override this with
+per-session workspaces under `agent.sandbox.workspaceRoot` (see
+`docs/configuration.md`).
+
+## Bootstrap files (injected)
+
+Inside `agent.workspace`, CLAWDBOT expects these user-editable files:
+- `AGENTS.md` — operating instructions + “memory”
+- `SOUL.md` — persona, boundaries, tone
+- `TOOLS.md` — user-maintained tool notes (e.g. `imsg`, `sag`, conventions)
+- `BOOTSTRAP.md` — one-time first-run ritual (deleted after completion)
+- `IDENTITY.md` — agent name/vibe/emoji
+- `USER.md` — user profile + preferred address
+
+On the first turn of a new session, CLAWDBOT injects the contents of these files directly into the agent context.
+
+If a file is missing, CLAWDBOT injects a single “missing file” marker line (and `clawdbot setup` will create a safe default template).
+
+## Built-in tools (internal)
+
+p’s embedded core tools (read/bash/edit/write and related internals) are defined in code and always available. `TOOLS.md` does **not** control which tools exist; it’s guidance for how *you* want them used.
+
+## Skills
+
+Clawdbot loads skills from three locations (workspace wins on name conflict):
+- Bundled (shipped with the install)
+- Managed/local: `~/.clawdbot/skills`
+- Workspace: `<workspace>/skills`
+
+Skills can be gated by config/env (see `skills` in `docs/configuration.md`).
+
+## p-mono integration
+
+Clawdbot reuses pieces of the p-mono codebase (models/tools), but **session management, discovery, and tool wiring are Clawdbot-owned**.
+
+- No p-coding agent runtime.
+- No `~/.pi/agent` or `<workspace>/.pi` settings are consulted.
+
+## Peter @ steipete (only)
+
+Apply these notes **only** when the user is Peter Steinberger at steipete.
+
+- Gateway runs on the **Mac Studio in London**.
+- Primary work computer: **MacBook Pro**.
+- Peter travels between **Vienna** and **London**; there are two networks bridged via **Tailscale**.
+- For debugging, connect to the Mac Studio (London) or MacBook Pro (primary).
+- There is also an **M1 MacBook Pro** on the Vienna tailnet you can use to access the Vienna network.
+- Nodes can be accessed via the `clawdbot` binary (`pnpm clawdbot` in `~/Projects/clawdbot`).
+- See also `skills/clawdbot*` for node/browser/canvas/cron usage.
+
+## Sessions
+
+Session transcripts are stored as JSONL at:
+- `~/.clawdbot/sessions/<SessionId>.jsonl`
+
+The session ID is stable and chosen by CLAWDBOT.
+Legacy Pi/Tau session folders are **not** read.
+
+## Steering while streaming
+
+When queue mode is `steer`, inbound messages are injected into the current run.
+The queue is checked **after each tool call**; if a queued message is present,
+remaining tool calls from the current assistant message are skipped (error tool
+results with "Skipped due to queued user message."), then the queued user
+message is injected before the next assistant response.
+
+When queue mode is `followup` or `collect`, inbound messages are held until the
+current turn ends, then a new agent turn starts with the queued payloads. See
+`docs/queue.md` for mode + debounce/cap behavior.
+
+Block streaming sends completed assistant blocks as soon as they finish; disable
+via `agent.blockStreamingDefault: "off"` if you only want the final response.
+Tune the boundary via `agent.blockStreamingBreak` (`text_end` vs `message_end`; defaults to text_end).
+Control soft block chunking with `agent.blockStreamingChunk` (defaults to
+800–1200 chars; prefers paragraph breaks, then newlines; sentences last).
+Verbose tool summaries are emitted at tool start (no debounce); Control UI
+streams tool output via agent events when available.
+
+## Configuration (minimal)
+
+At minimum, set:
+- `agent.workspace`
+- `whatsapp.allowFrom` (strongly recommended)
+
+---
+
+*Next: [Group Chats](./group-messages.md)* 🦞
+<!-- {% endraw %} -->

package/docs/android/connect.md

@@ -0,0 +1,131 @@
+---
+summary: "Runbook: connect/pair the Android node to a Clawdbot Gateway and use Canvas/Chat/Camera"
+read_when:
+  - Pairing or reconnecting the Android node
+  - Debugging Android bridge discovery or auth
+  - Verifying chat history parity across clients
+---
+
+# Android Node Connection Runbook
+
+Android node app ⇄ (mDNS/NSD + TCP bridge) ⇄ **Gateway bridge** ⇄ (loopback WS) ⇄ **Gateway**
+
+The Gateway WebSocket stays loopback-only (`ws://127.0.0.1:18789`). Android talks to the LAN-facing **bridge** (default `tcp://0.0.0.0:18790`) and uses Gateway-owned pairing.
+
+## Prerequisites
+
+- You can run the Gateway on the “master” machine.
+- Android device/emulator can reach the gateway bridge:
+  - Same LAN with mDNS/NSD, **or**
+  - Same Tailscale tailnet using Wide-Area Bonjour / unicast DNS-SD (see below), **or**
+  - Manual bridge host/port (fallback)
+- You can run the CLI (`clawdbot`) on the gateway machine (or via SSH).
+
+## 1) Start the Gateway (with bridge enabled)
+
+Bridge is enabled by default (disable via `CLAWDBOT_BRIDGE_ENABLED=0`).
+
+```bash
+pnpm clawdbot gateway --port 18789 --verbose
+```
+
+Confirm in logs you see something like:
+- `bridge listening on tcp://0.0.0.0:18790 (node)`
+
+For tailnet-only setups (recommended for Vienna ⇄ London), bind the bridge to the gateway machine’s Tailscale IP instead:
+
+- Set `bridge.bind: "tailnet"` in `~/.clawdbot/clawdbot.json` on the gateway host.
+- Restart the Gateway / macOS menubar app.
+
+## 2) Verify discovery (optional)
+
+From the gateway machine:
+
+```bash
+dns-sd -B _clawdbot-bridge._tcp local.
+```
+
+More debugging notes: `docs/bonjour.md`.
+
+### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD
+
+Android NSD/mDNS discovery won’t cross networks. If your Android node and the gateway are on different networks but connected via Tailscale, use Wide-Area Bonjour / unicast DNS-SD instead:
+
+1) Set up a DNS-SD zone (example `clawdbot.internal.`) on the gateway host and publish `_clawdbot-bridge._tcp` records.
+2) Configure Tailscale split DNS for `clawdbot.internal` pointing at that DNS server.
+
+Details and example CoreDNS config: `docs/bonjour.md`.
+
+## 3) Connect from Android
+
+In the Android app:
+
+- The app keeps its bridge connection alive via a **foreground service** (persistent notification).
+- Open **Settings**.
+- Under **Discovered Bridges**, select your gateway and hit **Connect**.
+- If mDNS is blocked, use **Advanced → Manual Bridge** (host + port) and **Connect (Manual)**.
+
+After the first successful pairing, Android auto-reconnects on launch:
+- Manual endpoint (if enabled), otherwise
+- The last discovered bridge (best-effort).
+
+## 4) Approve pairing (CLI)
+
+On the gateway machine:
+
+```bash
+clawdbot nodes pending
+clawdbot nodes approve <requestId>
+```
+
+Pairing details: `docs/gateway/pairing.md`.
+
+## 5) Verify the node is connected
+
+- Via nodes status:
+  ```bash
+  clawdbot nodes status
+  ```
+- Via Gateway:
+  ```bash
+  clawdbot gateway call node.list --params "{}"
+  ```
+
+## 6) Chat + history
+
+The Android node’s Chat sheet uses the gateway’s **primary session key** (`main`), so history and replies are shared with WebChat and other clients:
+
+- History: `chat.history`
+- Send: `chat.send`
+- Push updates (best-effort): `chat.subscribe` → `event:"chat"`
+
+## 7) Canvas + camera
+
+### Gateway Canvas Host (recommended for web content)
+
+If you want the node to show real HTML/CSS/JS that the agent can edit on disk, point the node at the Gateway canvas host.
+
+Note: nodes always use the standalone canvas host on `canvasHost.port` (default `18793`), bound to the bridge interface.
+
+1) Create `~/clawd/canvas/index.html` on the gateway host.
+
+2) Navigate the node to it (LAN):
+
+```bash
+clawdbot nodes invoke --node "<Android Node>" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18793/__clawdbot__/canvas/"}'
+```
+
+Tailnet (optional): if both devices are on Tailscale, use a MagicDNS name or tailnet IP instead of `.local`, e.g. `http://<gateway-magicdns>:18793/__clawdbot__/canvas/`.
+
+This server injects a live-reload client into HTML and reloads on file changes.
+The A2UI host lives at `http://<gateway-host>:18793/__clawdbot__/a2ui/`.
+
+Canvas commands (foreground only):
+- `canvas.eval`, `canvas.snapshot`, `canvas.navigate` (use `{"url":""}` or `{"url":"/"}` to return to the default scaffold). `canvas.snapshot` returns `{ format, base64 }` (default `format="jpeg"`).
+- A2UI: `canvas.a2ui.push`, `canvas.a2ui.reset` (`canvas.a2ui.pushJSONL` legacy alias)
+
+Camera commands (foreground only; permission-gated):
+- `camera.snap` (jpg)
+- `camera.clip` (mp4)
+
+See `docs/camera.md` for parameters and CLI helpers.