clawdbot 2026.1.4-1

package/docs/health.md

@@ -0,0 +1,28 @@
+---
+summary: "Health check steps for Baileys/WhatsApp connectivity"
+read_when:
+  - Diagnosing web provider health
+---
+# Health Checks (CLI)
+
+Short guide to verify the WhatsApp Web / Baileys stack without guessing.
+
+## Quick checks
+- `clawdbot status` — local summary: whether creds exist, auth age, session store path + recent sessions.
+- `clawdbot status --deep` — also probes the running Gateway (WhatsApp connect + Telegram + Discord APIs).
+- `clawdbot health --json` — asks the running Gateway for a full health snapshot (WS-only; no direct Baileys socket).
+- Send `/status` in WhatsApp/WebChat to get a status reply without invoking the agent.
+- Logs: tail `/tmp/clawdbot/clawdbot-*.log` and filter for `web-heartbeat`, `web-reconnect`, `web-auto-reply`, `web-inbound`.
+
+## Deep diagnostics
+- Creds on disk: `ls -l ~/.clawdbot/credentials/creds.json` (mtime should be recent).
+- Session store: `ls -l ~/.clawdbot/sessions/sessions.json` (legacy: `~/.clawdbot/sessions.json`; path can be overridden in config). Count and recent recipients are surfaced via `status`.
+- Relink flow: `clawdbot logout && clawdbot login --verbose` when status codes 409–515 or `loggedOut` appear in logs. (Note: the QR login flow auto-restarts once for status 515 after pairing.)
+
+## When something fails
+- `logged out` or status 409–515 → relink with `clawdbot logout` then `clawdbot login`.
+- Gateway unreachable → start it: `clawdbot gateway --port 18789` (use `--force` if the port is busy).
+- No inbound messages → confirm linked phone is online and the sender is allowed (`whatsapp.allowFrom`); for group chats, ensure mention rules match (`routing.groupChat.mentionPatterns` and `whatsapp.groups`).
+
+## Dedicated "health" command
+`clawdbot health --json` asks the running Gateway for its health snapshot (no direct Baileys socket from the CLI). It reports linked creds, auth age, Baileys connect result/status code, session-store summary, and a probe duration. It exits non-zero if the Gateway is unreachable or the probe fails/timeouts. Use `--timeout <ms>` to override the 10s default.

package/docs/heartbeat.md

@@ -0,0 +1,64 @@
+---
+summary: "Plan for heartbeat polling messages and notification rules"
+read_when:
+  - Adjusting heartbeat cadence or messaging
+---
+# Heartbeat (Gateway)
+
+Heartbeat runs periodic agent turns in the **main session** so the model can
+surface anything that needs attention without spamming the user.
+
+## Prompt contract
+- Heartbeat body defaults to `HEARTBEAT` (configurable via `agent.heartbeat.prompt`).
+- If nothing needs attention, the model should reply **exactly** `HEARTBEAT_OK`.
+- During heartbeat runs, Clawdbot treats `HEARTBEAT_OK` as an ack when it appears at
+  the **start or end** of the reply. Clawdbot strips the token and discards the
+  reply if the remaining content is **≤ 30 characters**.
+- If `HEARTBEAT_OK` is in the **middle** of a reply, it is not treated specially.
+- For alerts, do **not** include `HEARTBEAT_OK`; return only the alert text.
+
+### Stray `HEARTBEAT_OK` outside heartbeats
+If the model accidentally includes `HEARTBEAT_OK` at the start or end of a
+normal (non-heartbeat) reply, Clawdbot strips the token and logs a verbose
+message. If the reply is only `HEARTBEAT_OK`, it is dropped.
+
+## Config
+
+```json5
+{
+  agent: {
+    heartbeat: {
+      every: "30m",           // duration string: ms|s|m|h (0m disables)
+      model: "anthropic/claude-opus-4-5",
+      target: "last",          // last | whatsapp | telegram | none
+      to: "+15551234567",      // optional override for whatsapp/telegram
+      prompt: "HEARTBEAT"      // optional override
+    }
+  }
+}
+```
+
+### Fields
+- `every`: heartbeat interval (duration string; default unit minutes). Omit or set
+  to `0m` to disable.
+- `model`: optional model override for heartbeat runs (`provider/model`).
+- `target`: where heartbeat output is delivered.
+  - `last` (default): send to the last used external channel.
+  - `whatsapp` / `telegram`: force the channel (optionally set `to`).
+  - `none`: do not deliver externally; output stays in the session (WebChat-visible).
+- `to`: optional recipient override (E.164 for WhatsApp, chat id for Telegram).
+- `prompt`: optional override for the heartbeat body (default: `HEARTBEAT`).
+
+## Behavior
+- Runs in the main session (`main`, or `global` when scope is global).
+- Uses the main lane queue; if requests are in flight, the wake is retried.
+- Empty output or `HEARTBEAT_OK` is treated as “ok” and does **not** keep the
+  session alive (`updatedAt` is restored).
+- If `target` resolves to no external destination (no last route or `none`), the
+  heartbeat still runs but no outbound message is sent.
+
+## Wake hook
+- The gateway exposes a heartbeat wake hook so cron/jobs/webhooks can request an
+  immediate run (`requestHeartbeatNow`).
+- `wake` endpoints should enqueue system events and optionally trigger a wake; the
+  heartbeat runner picks those up on the next tick or immediately.

package/docs/images.md

@@ -0,0 +1,52 @@
+---
+summary: "Image and media handling rules for send, gateway, and agent replies"
+read_when:
+  - Modifying media pipeline or attachments
+---
+<!-- {% raw %} -->
+# Image & Media Support — 2025-12-05
+
+CLAWDBOT is now **web-only** (Baileys). This document captures the current media handling rules for send, gateway, and agent replies.
+
+## Goals
+- Send media with optional captions via `clawdbot send --media`.
+- Allow auto-replies from the web inbox to include media alongside text.
+- Keep per-type limits sane and predictable.
+
+## CLI Surface
+- `clawdbot 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 `{ provider, to, messageId, mediaUrl, caption }`.
+
+## Web Provider 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 `agent.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 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.
+- Audio transcription (if configured) runs before templating and can replace `Body` with the transcript.
+
+## Limits & Errors
+- 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.
+
+## 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.
+<!-- {% endraw %} -->

package/docs/imessage.md

@@ -0,0 +1,63 @@
+---
+summary: "iMessage support via imsg (JSON-RPC over stdio), setup, and chat_id routing"
+read_when:
+  - Setting up iMessage support
+  - Debugging iMessage send/receive
+---
+# iMessage (imsg)
+
+Status: external CLI integration. No daemon.
+
+## Model
+- Clawdbot spawns `imsg rpc` as a child process.
+- JSON-RPC runs over stdin/stdout (one JSON object per line).
+- Gateway owns the process; no TCP port needed.
+
+## Requirements
+- macOS with Messages signed in.
+- Full Disk Access for Clawdbot + the `imsg` binary (Messages DB access).
+- Automation permission for Messages when sending.
+
+## Config
+
+```json5
+{
+  imessage: {
+    enabled: true,
+    cliPath: "imsg",
+    dbPath: "~/Library/Messages/chat.db",
+    allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
+    includeAttachments: false,
+    mediaMaxMb: 16,
+    service: "auto",
+    region: "US"
+  }
+}
+```
+
+Notes:
+- `allowFrom` accepts handles (phone/email) or `chat_id:<id>` entries.
+- `service` defaults to `auto` (use `imessage` or `sms` to pin).
+- `region` is only used for SMS targeting.
+
+## Addressing / targets
+
+Prefer `chat_id` for stable routing:
+- `chat_id:123` (preferred)
+- `chat_guid:...` (fallback)
+- `chat_identifier:...` (fallback)
+- direct handles: `imessage:+1555` / `sms:+1555` / `user@example.com`
+
+List chats:
+```
+imsg chats --limit 20
+```
+
+## Group chat behavior
+- Group messages set `ChatType=group`, `GroupSubject`, and `GroupMembers`.
+- Group activation respects `imessage.groups."*".requireMention` and `routing.groupChat.mentionPatterns`.
+- Replies go back to the same `chat_id` (group or direct).
+
+## Troubleshooting
+- `clawdbot gateway call providers.status --params '{"probe":true}'`
+- Verify `imsg` is on PATH and has access to Messages DB.

package/docs/index.md

@@ -0,0 +1,182 @@
+---
+summary: "Top-level overview of Clawdbot, features, and purpose"
+read_when:
+  - Introducing Clawdbot to newcomers
+---
+<!-- {% raw %} -->
+# CLAWDBOT 🦞
+
+> *"EXFOLIATE! EXFOLIATE!"* — A space lobster, probably
+
+<p align="center">
+  <img src="whatsapp-clawd.jpg" alt="CLAWDBOT" width="420">
+</p>
+
+<p align="center">
+  <strong>WhatsApp + Telegram + Discord + iMessage gateway for AI agents (Pi).</strong><br>
+  Send a message, get an agent response — from your pocket.
+</p>
+
+<p align="center">
+  <a href="https://github.com/clawdbot/clawdbot">GitHub</a> ·
+  <a href="https://github.com/clawdbot/clawdbot/releases">Releases</a> ·
+  <a href="./clawd.md">Clawd setup</a>
+</p>
+
+CLAWDBOT bridges WhatsApp (via WhatsApp Web / Baileys), Telegram (Bot API / grammY), Discord (Bot API / discord.js), and iMessage (imsg CLI) to coding agents like [Pi](https://github.com/badlogic/pi-mono).
+It’s built for [Clawd](https://clawd.me), a space lobster who needed a TARDIS.
+
+## How it works
+
+```
+WhatsApp / Telegram / Discord
+        │
+        ▼
+  ┌──────────────────────────┐
+  │          Gateway          │  ws://127.0.0.1:18789 (loopback-only)
+  │     (single source)       │  tcp://0.0.0.0:18790 (Bridge)
+  │                          │  http://<gateway-host>:18793/__clawdbot__/canvas/ (Canvas host)
+  └───────────┬───────────────┘
+              │
+              ├─ Pi agent (RPC)
+              ├─ CLI (clawdbot …)
+              ├─ Chat UI (SwiftUI)
+              ├─ macOS app (Clawdbot.app)
+              └─ iOS node via Bridge + pairing
+```
+
+Most operations flow through the **Gateway** (`clawdbot gateway`), a single long-running process that owns provider connections and the WebSocket control plane.
+
+## Network model
+
+- **One Gateway per host**: it is the only process allowed to own the WhatsApp Web session.
+- **Loopback-first**: Gateway WS defaults to `ws://127.0.0.1:18789`.
+  - For Tailnet access, run `clawdbot gateway --bind tailnet --token ...` (token is required for non-loopback binds).
+- **Bridge for nodes**: optional LAN/tailnet-facing bridge on `tcp://0.0.0.0:18790` for paired nodes (Bonjour-discoverable).
+- **Canvas host**: HTTP file server on `canvasHost.port` (default `18793`), serving `/__clawdbot__/canvas/` for node WebViews; see `docs/configuration.md` (`canvasHost`).
+- **Remote use**: SSH tunnel or tailnet/VPN; see `docs/remote.md` and `docs/discovery.md`.
+
+## Features (high level)
+
+- 📱 **WhatsApp Integration** — Uses Baileys for WhatsApp Web protocol
+- ✈️ **Telegram Bot** — DMs + groups via grammY
+- 🎮 **Discord Bot** — DMs + guild channels via discord.js
+- 💬 **iMessage** — Local imsg CLI integration (macOS)
+- 🤖 **Agent bridge** — Pi (RPC mode) with tool streaming
+- 💬 **Sessions** — Direct chats collapse into shared `main` (default); groups are isolated
+- 👥 **Group Chat Support** — Mention-based by default; owner can toggle `/activation always|mention`
+- 📎 **Media Support** — Send and receive images, audio, documents
+- 🎤 **Voice notes** — Optional transcription hook
+- 🖥️ **WebChat + macOS app** — Local UI + menu bar companion for ops and voice wake
+- 📱 **iOS node** — Pairs as a node and exposes a Canvas surface
+
+Note: legacy Claude/Codex/Gemini/Opencode paths have been removed; Pi is the only coding-agent path.
+
+## Quick start
+
+Runtime requirement: **Node ≥ 22**.
+
+```bash
+# From source (recommended while the npm package is still settling)
+pnpm install
+pnpm build
+pnpm link --global
+
+# Pair WhatsApp Web (shows QR)
+clawdbot login
+
+# Run the Gateway (leave running)
+clawdbot gateway --port 18789
+```
+
+Multi-instance quickstart (optional):
+
+```bash
+CLAWDBOT_CONFIG_PATH=~/.clawdbot/a.json \
+CLAWDBOT_STATE_DIR=~/.clawdbot-a \
+clawdbot gateway --port 19001
+```
+
+Send a test message (requires a running Gateway):
+
+```bash
+clawdbot send --to +15555550123 --message "Hello from CLAWDBOT"
+```
+
+## Configuration (optional)
+
+Config lives at `~/.clawdbot/clawdbot.json`.
+
+- If you **do nothing**, CLAWDBOT uses the bundled Pi binary in RPC mode with per-sender sessions.
+- If you want to lock it down, start with `whatsapp.allowFrom` and (for groups) mention rules.
+
+Example:
+
+```json5
+{
+  whatsapp: {
+    allowFrom: ["+15555550123"],
+    groups: { "*": { requireMention: true } }
+  },
+  routing: { groupChat: { mentionPatterns: ["@clawd"] } }
+}
+```
+
+## Docs
+
+- Start here:
+  - [FAQ](./faq.md) ← *common questions answered*
+  - [Configuration](./configuration.md)
+  - [Nix mode](./nix.md)
+  - [Clawd personal assistant setup](./clawd.md)
+  - [Skills](./skills.md)
+  - [Skills config](./skills-config.md)
+  - [Workspace templates](./templates/AGENTS.md)
+  - [RPC adapters](./rpc.md)
+  - [Gateway runbook](./gateway.md)
+  - [Nodes (iOS/Android)](./nodes.md)
+  - [Web surfaces (Control UI)](./web.md)
+  - [Discovery + transports](./discovery.md)
+  - [Remote access](./remote.md)
+- Providers and UX:
+  - [WebChat](./webchat.md)
+  - [Control UI (browser)](./control-ui.md)
+  - [Telegram](./telegram.md)
+  - [Discord](./discord.md)
+  - [iMessage](./imessage.md)
+  - [Groups](./groups.md)
+  - [WhatsApp group messages](./group-messages.md)
+  - [Media: images](./images.md)
+  - [Media: audio](./audio.md)
+- Ops and safety:
+  - [Sessions](./session.md)
+  - [Cron + wakeups](./cron.md)
+  - [Security](./security.md)
+  - [Troubleshooting](./troubleshooting.md)
+
+## The name
+
+**CLAWDBOT = CLAW + TARDIS** — because every space lobster needs a time-and-space machine.
+
+---
+
+*"We're all just playing with our own prompts."* — an AI, probably high on tokens
+<!-- {% endraw %} -->
+
+## Credits
+
+- **Peter Steinberger** ([@steipete](https://twitter.com/steipete)) — Creator, lobster whisperer
+- **Mario Zechner** ([@badlogicc](https://twitter.com/badlogicgames)) — Pi creator, security pen-tester
+- **Clawd** — The space lobster who demanded a better name
+
+## Core Contributors
+
+- **Maxim Vovshin** (@Hyaxia, 36747317+Hyaxia@users.noreply.github.com) — Blogwatcher skill
+
+## License
+
+MIT — Free as a lobster in the ocean 🦞
+
+---
+
+*"We're all just playing with our own prompts."* — An AI, probably high on tokens

package/docs/ios/connect.md

@@ -0,0 +1,177 @@
+---
+summary: "Runbook: connect/pair the iOS node to a Clawdbot Gateway and drive its Canvas"
+read_when:
+  - Pairing or reconnecting the iOS node
+  - Debugging iOS bridge discovery or auth
+  - Sending screen/canvas commands to iOS
+---
+
+# iOS Node Connection Runbook
+
+This is the practical “how do I connect the iOS node” guide:
+
+**iOS app** ⇄ (Bonjour + TCP bridge) ⇄ **Gateway bridge** ⇄ (loopback WS) ⇄ **Gateway**
+
+The Gateway WebSocket stays loopback-only (`ws://127.0.0.1:18789`). The iOS node 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.
+- iOS node app can reach the gateway bridge:
+  - Same LAN with Bonjour/mDNS, **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 Bonjour discovery (optional but recommended)
+
+From the gateway machine:
+
+```bash
+dns-sd -B _clawdbot-bridge._tcp local.
+```
+
+You should see your gateway advertising `_clawdbot-bridge._tcp`.
+
+If browse works, but the iOS node can’t connect, try resolving one instance:
+
+```bash
+dns-sd -L "<instance name>" _clawdbot-bridge._tcp local.
+```
+
+More debugging notes: `docs/bonjour.md`.
+
+### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD
+
+If the iOS node and the gateway are on different networks but connected via Tailscale, multicast mDNS won’t cross the boundary. 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 the iOS node app
+
+In the iOS node app:
+- Pick the discovered bridge (or hit refresh).
+- If not paired yet, it will initiate pairing automatically.
+- After the first successful pairing, it will auto-reconnect **strictly to the last discovered gateway** on launch (including after reinstall), as long as the iOS Keychain entry is still present.
+
+### Connection indicator (always visible)
+
+The Settings tab icon shows a small status dot:
+- **Green**: connected to the bridge
+- **Yellow**: connecting (subtle pulse)
+- **Red**: not connected / error
+
+## 4) Approve pairing (CLI)
+
+On the gateway machine:
+
+```bash
+clawdbot nodes pending
+```
+
+Approve the request:
+
+```bash
+clawdbot nodes approve <requestId>
+```
+
+After approval, the iOS node receives/stores the token and reconnects authenticated.
+
+Pairing details: `docs/gateway/pairing.md`.
+
+## 5) Verify the node is connected
+
+- In the macOS app: **Instances** tab should show something like `iOS Node (...)` with a green “Active” presence dot shortly after connect.
+- Via nodes status (paired + connected):
+  ```bash
+  clawdbot nodes status
+  ```
+- Via Gateway (paired + connected):
+  ```bash
+  clawdbot gateway call node.list --params "{}"
+  ```
+- Via Gateway presence (legacy-ish, still useful):
+  ```bash
+  clawdbot gateway call system-presence --params "{}"
+  ```
+  Look for the node `instanceId` (often a UUID).
+
+## 6) Drive the iOS Canvas (draw / snapshot)
+
+The iOS node runs a WKWebView “Canvas” scaffold which exposes:
+- `window.__clawdbot.canvas`
+- `window.__clawdbot.ctx` (2D context)
+- `window.__clawdbot.setStatus(title, subtitle)`
+
+### 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 it 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 "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18793/__clawdbot__/canvas/"}'
+```
+
+Notes:
+- The server injects a live-reload client into HTML and reloads on file changes.
+- A2UI is hosted on the same canvas host at `http://<gateway-host>:18793/__clawdbot__/a2ui/`.
+- 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/`.
+- iOS may require App Transport Security allowances to load plain `http://` URLs; if it fails to load, prefer HTTPS or adjust the iOS app’s ATS config.
+
+### Draw with `canvas.eval`
+
+```bash
+clawdbot nodes invoke --node "iOS Node" --command canvas.eval --params "$(cat <<'JSON'
+{"javaScript":"(() => { const {ctx,setStatus} = window.__clawdbot; setStatus('Drawing','…'); ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle='#ff2d55'; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); setStatus(null,null); return 'ok'; })()"}
+JSON
+)"
+```
+
+### Snapshot with `canvas.snapshot`
+
+```bash
+clawdbot nodes invoke --node 192.168.0.88 --command canvas.snapshot --params '{"maxWidth":900}'
+```
+
+The response includes `{ format, base64 }` image data (default `format="jpeg"`; pass `{"format":"png"}` when you specifically need lossless PNG).
+
+## Common gotchas
+
+- **iOS in background:** all `canvas.*` commands fail fast with `NODE_BACKGROUND_UNAVAILABLE` (bring the iOS node app to foreground).
+- **Return to default scaffold:** `canvas.navigate` with `{"url":""}` or `{"url":"/"}` returns to the built-in scaffold page.
+- **mDNS blocked:** some networks block multicast; use a different LAN or plan a tailnet-capable bridge (see `docs/discovery.md`).
+- **Wrong node selector:** `--node` can be the node id (UUID), display name (e.g. `iOS Node`), IP, or an unambiguous prefix. If it’s ambiguous, the CLI will tell you.
+- **Stale pairing / Keychain cleared:** if the pairing token is missing (or iOS Keychain was wiped), the node must pair again; approve a new pending request.
+- **App reinstall but no reconnect:** the node restores `instanceId` + last bridge preference from Keychain; if it still comes up “unpaired”, verify Keychain persistence on your device/simulator and re-pair once.
+
+## Related docs
+
+- `docs/ios/spec.md` (design + architecture)
+- `docs/gateway.md` (gateway runbook)
+- `docs/gateway/pairing.md` (approval + storage)
+- `docs/bonjour.md` (discovery debugging)
+- `docs/discovery.md` (LAN vs tailnet vs SSH)