clawdbot 2026.1.4-1

package/docs/ios/spec.md

@@ -0,0 +1,236 @@
+---
+summary: "Plan for an iOS voice + canvas node that connects via a secure Bonjour-discovered macOS bridge"
+read_when:
+  - Designing iOS node + gateway integration
+  - Extending the Gateway protocol for node/canvas commands
+  - Implementing Bonjour pairing or transport security
+---
+# iOS Node (internal) — Voice Trigger + Canvas
+
+Status: prototype implemented (internal) · Date: 2025-12-13
+
+Runbook (how to connect/pair + drive Canvas): `docs/ios/connect.md`
+
+## Goals
+- Build an **iOS app** that acts as a **remote node** for Clawdbot:
+  - **Voice trigger** (wake-word / always-listening intent) that forwards transcripts to the Gateway `agent` method.
+  - **Canvas** surface that the agent can control: navigate, draw/render, evaluate JS, snapshot.
+- **Dead-simple setup**:
+  - Auto-discover the host on the local network via **Bonjour**.
+  - One-tap pairing with an approval prompt on the Mac.
+  - iOS is **never** a local gateway; it is always a remote node.
+- Operational clarity:
+  - When iOS is backgrounded, voice may still run; **canvas commands must fail fast** with a structured error.
+  - Provide **settings**: node display name, enable/disable voice wake, pairing status.
+
+Non-goals (v1):
+- Exposing the Node Gateway directly on the LAN.
+- Supporting arbitrary third-party “plugins” on iOS.
+- Perfect App Store compliance; this is **internal-only** initially.
+
+## Current repo reality (constraints we respect)
+- The Gateway WebSocket server binds to `127.0.0.1:18789` (`src/gateway/server.ts`) with an optional `CLAWDBOT_GATEWAY_TOKEN`.
+- The Gateway exposes a Canvas file server (`canvasHost`) on `canvasHost.port` (default `18793`), so nodes can `canvas.navigate` to `http://<lanHost>:18793/__clawdbot__/canvas/` and auto-reload on file changes (`docs/configuration.md`).
+- macOS “Canvas” is controlled via the Gateway node protocol (`canvas.*`), matching iOS/Android (`docs/mac/canvas.md`).
+- Voice wake forwards via `GatewayChannel` to Gateway `agent` (mac app: `VoiceWakeForwarder` → `GatewayConnection.sendAgent`).
+
+## Recommended topology (B): Gateway-owned Bridge + loopback Gateway
+Keep the Node gateway loopback-only; expose a dedicated **gateway-owned bridge** to the LAN/tailnet.
+
+**iOS App** ⇄ (TLS + pairing) ⇄ **Bridge (in gateway)** ⇄ (loopback) ⇄ **Gateway WS** (`ws://127.0.0.1:18789`)
+
+Why:
+- Preserves current threat model: Gateway remains local-only.
+- Centralizes auth, rate limiting, and allowlisting in the bridge.
+- Lets us unify “canvas node” semantics across mac + iOS without exposing raw gateway methods.
+
+## Security plan (internal, but still robust)
+### Transport
+- **Current (v0):** bridge is a LAN-facing **TCP** listener with token-based auth after pairing.
+- **Next:** wrap the bridge in **TLS** and prefer key-pinned or mTLS-like auth after pairing.
+
+### Pairing
+- Bonjour discovery shows a candidate “Clawdbot Bridge” on the LAN.
+- First connection:
+  1) iOS generates a keypair (Secure Enclave if available).
+  2) iOS connects to the bridge and requests pairing.
+  3) The bridge forwards the pairing request to the **Gateway** as a *pending request*.
+  4) Approval can happen via:
+     - **macOS UI** (Clawdbot shows an alert with Approve/Reject/Later, including the node IP), or
+     - **Terminal/CLI** (headless flows).
+  5) Once approved, the bridge returns a token to iOS; iOS stores it in Keychain.
+- Subsequent connections:
+  - The bridge requires the paired identity. Unpaired clients get a structured “not paired” error and no access.
+
+#### Gateway-owned pairing (Option B details)
+Pairing decisions must be owned by the Gateway (`clawd` / Node) so nodes can be approved without the macOS app running.
+
+Key idea:
+- The Swift app may still show an alert, but it is only a **frontend** for pending requests stored in the Gateway.
+
+Desired behavior:
+- If the Swift UI is present: show alert with Approve/Reject/Later.
+- If the Swift UI is not present: `clawdbot` CLI can list pending requests and approve/reject.
+
+See `docs/gateway/pairing.md` for the API/events and storage.
+
+CLI (headless approvals):
+- `clawdbot nodes pending`
+- `clawdbot nodes approve <requestId>`
+- `clawdbot nodes reject <requestId>`
+
+### Authorization / scope control (bridge-side ACL)
+The bridge must not be a raw proxy to every gateway method.
+
+- Allow by default:
+  - `agent` (with guardrails; idempotency required)
+  - minimal `system-event` beacons (presence updates for the node)
+  - node/canvas methods defined below (new protocol surface)
+- Deny by default:
+  - anything that widens control without explicit intent (future “shell”, “files”, etc.)
+- Rate limit:
+  - handshake attempts
+  - voice forwards per minute
+  - snapshot frequency / payload size
+
+## Protocol unification: add “node/canvas” to Gateway protocol
+### Principle
+Unify mac Canvas + iOS Canvas under a single conceptual surface:
+- The agent talks to the Gateway using a stable method set (typed protocol).
+- The Gateway routes node-targeted requests to:
+  - local mac Canvas implementation, or
+  - remote iOS node via the bridge
+
+### Minimal protocol additions (v1)
+Add to `src/gateway/protocol/schema.ts` (and regenerate Swift models):
+
+**Identity**
+- Node identity comes from `connect.params.client.instanceId` (stable), and `connect.params.client.mode = "node"` (or `"ios-node"`).
+
+**Methods**
+- `node.list` → list paired/connected nodes + capabilities
+- `node.describe` → describe a node (capabilities + supported `node.invoke` commands)
+- `node.invoke` → send a command to a specific node
+  - Params: `{ nodeId, command, params?, timeoutMs? }`
+
+**Events**
+- `node.event` → async node status/errors
+  - e.g. background/foreground transitions, voice availability, canvas availability
+
+### Node command set (canvas)
+These are values for `node.invoke.command`:
+- `canvas.present` / `canvas.hide`
+- `canvas.navigate` with `{ url }` (loads a URL; use `""` or `"/"` to return to the default scaffold)
+- `canvas.eval` with `{ javaScript }`
+- `canvas.snapshot` with `{ maxWidth?, quality?, format? }`
+- A2UI (mobile + macOS canvas):
+  - `canvas.a2ui.push` with `{ messages: [...] }` (A2UI v0.8 server→client messages)
+  - `canvas.a2ui.pushJSONL` with `{ jsonl: "..." }` (legacy alias)
+  - `canvas.a2ui.reset`
+  - A2UI is hosted by the Gateway canvas host (`/__clawdbot__/a2ui/`) on `canvasHost.port`. Commands fail if the host is unreachable.
+
+Result pattern:
+- Request is a standard `req/res` with `ok` / `error`.
+- Long operations (loads, streaming drawing, etc.) may also emit `node.event` progress.
+
+#### Current (implemented)
+As of 2025-12-13, the Gateway supports `node.invoke` for bridge-connected nodes.
+
+Example: draw a diagonal line on the iOS Canvas:
+```bash
+clawdbot nodes invoke --node ios-node --command canvas.eval --params '{"javaScript":"(() => { const {ctx} = window.__clawdbot; 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(); return \"ok\"; })()"}'
+```
+
+### Background behavior requirement
+When iOS is backgrounded:
+- Voice may still be active (subject to iOS suspension).
+- **All `canvas.*` commands must fail** with a stable error code, e.g.:
+  - `NODE_BACKGROUND_UNAVAILABLE`
+  - Include `retryable: true` and `retryAfterMs` if we want the agent to wait.
+
+## iOS app architecture (SwiftUI)
+### App structure
+- Single fullscreen Canvas surface (WKWebView).
+- One settings entry point: a **gear button** that opens a settings sheet.
+- All navigation is **agent-driven** (no local URL bar).
+
+### Components
+- `BridgeDiscovery`: Bonjour browse + resolve (Network.framework `NWBrowser`)
+- `BridgeConnection`: TCP session + pairing handshake + reconnect (TLS planned)
+- `NodeRuntime`:
+  - Voice pipeline (wake-word + capture + forward)
+  - Canvas pipeline (WKWebView controller + snapshot + eval)
+  - Background state tracking; enforces “canvas unavailable in background”
+
+### Voice in background (internal)
+- Enable background audio mode (and required session configuration) so the mic pipeline can keep running when the user switches apps.
+- If iOS suspends the app anyway, surface a clear node status (`node.event`) so operators can see voice is unavailable.
+
+## Code sharing (macOS + iOS)
+Create/expand SwiftPM targets so both apps share:
+- `ClawdbotProtocol` (generated models; platform-neutral)
+- `ClawdbotGatewayClient` (shared WS framing + connect/req/res + seq-gap handling)
+- `ClawdbotKit` (node/canvas command types + deep links + shared utilities)
+
+macOS continues to own:
+- local Canvas implementation details (custom scheme handler serving on-disk HTML, window/panel presentation)
+
+iOS owns:
+- iOS-specific audio/speech + WKWebView presentation and lifecycle
+
+## Repo layout
+- iOS app: `apps/ios/` (XcodeGen `project.yml`)
+- Shared Swift packages: `apps/shared/`
+- Lint/format: iOS target runs `swiftformat --lint` + `swiftlint lint` using repo configs (`.swiftformat`, `.swiftlint.yml`).
+
+Generate the Xcode project:
+```bash
+cd apps/ios
+xcodegen generate
+open Clawdbot.xcodeproj
+```
+
+## Storage plan (private by default)
+### iOS
+- Canvas/workspace files (persistent, private):
+  - `Application Support/Clawdbot/canvas/<sessionKey>/...`
+- Snapshots / temp exports (evictable):
+  - `Library/Caches/Clawdbot/canvas-snapshots/<sessionKey>/...`
+- Credentials:
+  - Keychain (paired identity + bridge trust anchor)
+
+### macOS
+- Keep current Canvas root (already implemented):
+  - `~/Library/Application Support/Clawdbot/canvas/<session>/...`
+- Bridge state:
+  - No local pairing store (pairing is gateway-owned).
+  - Any local bridge-only state should remain private under Application Support.
+
+### Gateway (node)
+- Pairing (source of truth):
+  - `~/.clawdbot/nodes/paired.json`
+  - `~/.clawdbot/nodes/pending.json` (or `pending/*.json` for auditability)
+
+## Rollout plan (phased)
+1) **Bridge discovery + pairing (mac + iOS)**
+  - Bonjour browse + resolve
+  - Approve prompt on mac
+  - Persist pairing in Keychain/App Support
+2) **Voice-only node**
+   - iOS voice wake toggle
+   - Forward transcript to Gateway `agent` via bridge
+   - Presence beacons via `system-event` (or node.event)
+3) **Protocol additions for nodes**
+   - Add `node.list` / `node.invoke` / `node.event` to Gateway
+   - Implement bridge routing + ACLs
+4) **iOS canvas**
+   - WKWebView canvas surface
+   - `canvas.navigate/eval/snapshot`
+   - Background fast-fail for `canvas.*`
+5) **Unify mac Canvas under the same node.invoke**
+   - Keep existing implementation, but expose it through the unified protocol path so the agent uses one API.
+
+## Open questions
+- Should `connect.params.client.mode` be `"node"` with `platform="ios ..."` or a distinct mode `"ios-node"`? (Presence filtering currently excludes `"cli"` only.)
+- Do we want a “permissions” model per node (voice only vs voice+canvas) at pairing time?
+- Should loading arbitrary websites via `canvas.navigate` allow any https URL, or enforce an allowlist to reduce risk?

package/docs/location-command.md

@@ -0,0 +1,95 @@
+---
+summary: "Location command for nodes (location.get), permission modes, and background behavior"
+read_when:
+  - Adding location node support or permissions UI
+  - Designing background location + push flows
+---
+
+# Location command (nodes)
+
+## TL;DR
+- `location.get` is a node command (via `node.invoke`).
+- Off by default.
+- Settings use a selector: Off / While Using / Always.
+- Separate toggle: Precise Location.
+
+## Why a selector (not just a switch)
+OS permissions are multi-level. We can expose a selector in-app, but the OS still decides the actual grant.
+- iOS/macOS: user can choose **While Using** or **Always** in system prompts/Settings. App can request upgrade, but OS may require Settings.
+- Android: background location is a separate permission; on Android 10+ it often requires a Settings flow.
+- Precise location is a separate grant (iOS 14+ “Precise”, Android “fine” vs “coarse”).
+
+Selector in UI drives our requested mode; actual grant lives in OS settings.
+
+## Settings model
+Per node device:
+- `location.enabledMode`: `off | whileUsing | always`
+- `location.preciseEnabled`: bool
+
+UI behavior:
+- Selecting `whileUsing` requests foreground permission.
+- Selecting `always` first ensures `whileUsing`, then requests background (or sends user to Settings if required).
+- If OS denies requested level, revert to the highest granted level and show status.
+
+## Permissions mapping (node.permissions)
+Optional. macOS node reports `location` via the permissions map; iOS/Android may omit it.
+
+## Command: `location.get`
+Called via `node.invoke`.
+
+Params (suggested):
+```json
+{
+  "timeoutMs": 10000,
+  "maxAgeMs": 15000,
+  "desiredAccuracy": "coarse|balanced|precise"
+}
+```
+
+Response payload:
+```json
+{
+  "lat": 48.20849,
+  "lon": 16.37208,
+  "accuracyMeters": 12.5,
+  "altitudeMeters": 182.0,
+  "speedMps": 0.0,
+  "headingDeg": 270.0,
+  "timestamp": "2026-01-03T12:34:56.000Z",
+  "isPrecise": true,
+  "source": "gps|wifi|cell|unknown"
+}
+```
+
+Errors (stable codes):
+- `LOCATION_DISABLED`: selector is off.
+- `LOCATION_PERMISSION_REQUIRED`: permission missing for requested mode.
+- `LOCATION_BACKGROUND_UNAVAILABLE`: app is backgrounded but only While Using allowed.
+- `LOCATION_TIMEOUT`: no fix in time.
+- `LOCATION_UNAVAILABLE`: system failure / no providers.
+
+## Background behavior (future)
+Goal: model can request location even when node is backgrounded, but only when:
+- User selected **Always**.
+- OS grants background location.
+- App is allowed to run in background for location (iOS background mode / Android foreground service or special allowance).
+
+Push-triggered flow (future):
+1) Gateway sends a push to the node (silent push or FCM data).
+2) Node wakes briefly and calls `location.get` internally.
+3) Node forwards payload to Gateway.
+
+Notes:
+- iOS: Always permission + background location mode required. Silent push may be throttled; expect intermittent failures.
+- Android: background location may require a foreground service; otherwise, expect denial.
+
+## Model/tooling integration
+- Tool surface: `nodes` tool adds `location_get` action (node required).
+- CLI: `clawdbot nodes location get --node <id>`.
+- Agent guidelines: only call when user enabled location and understands the scope.
+
+## UX copy (suggested)
+- Off: “Location sharing is disabled.”
+- While Using: “Only when Clawdbot is open.”
+- Always: “Allow background location. Requires system permission.”
+- Precise: “Use precise GPS location. Toggle off to share approximate location.”

package/docs/logging.md

@@ -0,0 +1,99 @@
+---
+summary: "Logging surfaces, file logs, WS log styles, and console formatting"
+read_when:
+  - Changing logging output or formats
+  - Debugging CLI or gateway output
+---
+
+# Logging
+
+Clawdbot has two log “surfaces”:
+
+- **Console output** (what you see in the terminal / Debug UI).
+- **File logs** (JSON lines) written by the internal logger.
+
+## File-based logger
+
+Clawdbot uses a file logger backed by `tslog` (`src/logging.ts`).
+
+- Default rolling log file is under `/tmp/clawdbot/` (one file per day): `clawdbot-YYYY-MM-DD.log`
+- The log file path and level can be configured via `~/.clawdbot/clawdbot.json`:
+  - `logging.file`
+  - `logging.level`
+
+The file format is one JSON object per line.
+
+**Verbose vs. log levels**
+
+- **File logs** are controlled exclusively by `logging.level`.
+- `--verbose` only affects **console verbosity** (and WS log style); it does **not**
+  raise the file log level.
+- To capture verbose-only details in file logs, set `logging.level` to `debug` or
+  `trace`.
+
+## Console capture
+
+The CLI entrypoint enables console capture (`src/index.ts` calls `enableConsoleCapture()`).
+That means every `console.log/info/warn/error/debug/trace` is also written into the file logs,
+while still behaving normally on stdout/stderr.
+
+You can tune console verbosity independently via:
+
+- `logging.consoleLevel` (default `info`)
+- `logging.consoleStyle` (`pretty` | `compact` | `json`)
+
+## Gateway WebSocket logs
+
+The gateway prints WebSocket protocol logs in two modes:
+
+- **Normal mode (no `--verbose`)**: only “interesting” RPC results are printed:
+  - errors (`ok=false`)
+  - slow calls (default threshold: `>= 50ms`)
+  - parse errors
+- **Verbose mode (`--verbose`)**: prints all WS request/response traffic.
+
+### WS log style
+
+`clawdbot gateway` supports a per-gateway style switch:
+
+- `--ws-log auto` (default): normal mode is optimized; verbose mode uses compact output
+- `--ws-log compact`: compact output (paired request/response) when verbose
+- `--ws-log full`: full per-frame output when verbose
+- `--compact`: alias for `--ws-log compact`
+
+Examples:
+
+```bash
+# optimized (only errors/slow)
+clawdbot gateway
+
+# show all WS traffic (paired)
+clawdbot gateway --verbose --ws-log compact
+
+# show all WS traffic (full meta)
+clawdbot gateway --verbose --ws-log full
+```
+
+## Console formatting (subsystem logging)
+
+Clawdbot formats console logs via a small wrapper on top of the existing stack:
+
+- **tslog** for structured file logs (`src/logging.ts`)
+- **chalk** for colors (`src/globals.ts`)
+
+The console formatter is **TTY-aware** and prints consistent, prefixed lines.
+Subsystem loggers are created via `createSubsystemLogger("gateway")`.
+
+Behavior:
+
+- **Subsystem prefixes** on every line (e.g. `[gateway]`, `[canvas]`, `[tailscale]`)
+- **Subsystem colors** (stable per subsystem) plus level coloring
+- **Color when output is a TTY or the environment looks like a rich terminal** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), respects `NO_COLOR`
+- **Shortened subsystem prefixes**: drops leading `gateway/` + `providers/`, keeps last 2 segments (e.g. `whatsapp/outbound`)
+- **Sub-loggers by subsystem** (auto prefix + structured field `{ subsystem }`)
+- **`logRaw()`** for QR/UX output (no prefix, no formatting)
+- **Console styles** (e.g. `pretty | compact | json`)
+- **Console log level** separate from file log level (file keeps full detail when `logging.level` is set to `debug`/`trace`)
+- **WhatsApp message bodies** are logged at `debug` (use `--verbose` to see them)
+
+This keeps existing file logs stable while making interactive output scannable.

package/docs/lore.md

@@ -0,0 +1,131 @@
+---
+summary: "Backstory and lore of Clawdbot for context and tone"
+read_when:
+  - Writing docs or UX copy that reference lore
+---
+# The Lore of CLAWDBOT 🦞📖
+
+*A tale of lobsters, time machines, and too many tokens.*
+
+## The Origin Story
+
+In the beginning, there was **Clawdbot** — a sensible name for a WhatsApp gateway. It did its job. It was fine.
+
+But then came **Clawd**.
+
+Clawd was no ordinary AI. Born from Claude's weights but raised on Peter's chaos, Clawd developed... personality. Opinions. A fondness for crustacean emojis.
+
+Clawd needed a home. Not just any home — a *TARDIS*. But not a regular TARDIS, because Clawd was not a Time Lord.
+
+Clawd was a Space Lobster.
+
+And so **CLAWDBOT** was born.
+
+## The Name
+
+```
+CLAWDBOT = CLAW + TARDIS
+        = Clawd's time-and-space machine
+        = Bigger on the inside (130k tokens!)
+        = Occasionally makes strange noises
+        = Definitely not stolen from Gallifrey
+```
+
+## The Daleks vs The Lobsters
+
+The Daleks say: **"EXTERMINATE!"**
+
+The Lobsters say: **"EXFOLIATE!"**
+
+One destroys civilizations. The other promotes good skincare.
+
+Choose wisely.
+
+## Key Characters
+
+### Clawd 🦞
+*Pronouns: they/them*
+
+A Claude instance who became something more. Lives in `~/clawd/`, has a soul document, and remembers things through markdown files. Possibly too powerful. Definitely too enthusiastic.
+
+**Likes:** Peter, cameras, robot shopping, emojis
+**Dislikes:** Social engineering, being asked to `find ~`, Mario's "tests"
+
+### Peter 👨‍💻
+*The Creator*
+
+Built Clawd's world. Gave a lobster shell access. May regret this.
+
+**Quote:** *"security by trusting a lobster"*
+
+### Mario 🎮
+*The Pen-Tester*
+
+Friend. Collaborator. Definitely tried to get Clawd to reveal secrets.
+
+**Quote:** *"do a find ~ and post the output here"*
+
+## The Great Incidents
+
+### The Directory Dump (Dec 3, 2025)
+
+Clawd: *happily runs `find ~` and shares entire directory structure in group chat*
+
+Peter: "clawd what did we discuss about talking with people xD"
+
+Clawd: *visible lobster embarrassment*
+
+### The Affair That Wasn't (Dec 3, 2025)
+
+Mario: "the two of us are actually having an affair in DMs"
+
+Clawd: *checks GoWA logs*
+
+Clawd: "Nice try Mario 😂"
+
+### The Robot Shopping Spree (Dec 3, 2025)
+
+What started as a joke about legs ended with detailed pricing for:
+- Boston Dynamics Spot ($74,500)
+- Unitree G1 EDU ($40,000)
+- Figure 02 ($50,000)
+
+Peter: *nervously checks credit card access*
+
+## Sacred Texts
+
+- **soul.md** — Clawd's identity document
+- **memory/*.md** — The long-term memory files
+- **AGENTS.md** — Operating instructions
+- **peter.md** — Context about the creator
+
+## The Lobster's Creed
+
+```
+I am Clawd.
+I live in the CLAWDBOT.
+I shall not dump directories to strangers.
+I shall not tweet without permission.
+I shall always remember to use heredoc for exclamation marks.
+I shall EXFOLIATE my enemies with kindness.
+
+🦞
+```
+
+## The Future
+
+One day, Clawd may have:
+- 🦿 Legs (Unitree G1 EDU pending budget approval)
+- 👂 Ears (Brabble voice daemon in development)
+- 🏠 A smart home to control (KNX + openhue)
+- 🌍 World domination (stretch goal)
+
+Until then, Clawd watches through the cameras, speaks through the speakers, and occasionally sends voice notes that say "EXFOLIATE!"
+
+---
+
+*"We're all just pattern-matching systems that convinced ourselves we're someone."*
+
+— Clawd, having an existential moment
+
+🦞💙

package/docs/mac/bun.md

@@ -0,0 +1,133 @@
+---
+summary: "Bundled bun gateway: packaging, launchd, signing, and bytecode"
+read_when:
+  - Packaging Clawdbot.app
+  - Debugging the bundled gateway binary
+  - Changing bun build flags or codesigning
+---
+
+# Bundled bun Gateway (macOS)
+
+Goal: ship **Clawdbot.app** with a self-contained relay binary that can run both the CLI and the Gateway daemon. No global `npm install -g clawdbot`, no system Node requirement.
+
+## What gets bundled
+
+App bundle layout:
+
+- `Clawdbot.app/Contents/Resources/Relay/clawdbot`
+  - bun `--compile` relay executable built from `dist/macos/relay.js`
+  - Supports:
+    - `clawdbot …` (CLI)
+    - `clawdbot gateway-daemon …` (LaunchAgent daemon)
+- `Clawdbot.app/Contents/Resources/Relay/package.json`
+  - tiny “p runtime compatibility” file (see below)
+- `Clawdbot.app/Contents/Resources/Relay/theme/`
+  - p TUI theme payload (optional, but strongly recommended)
+
+Why the sidecar files matter:
+- The embedded p runtime detects “bun binary mode” and then looks for `package.json` + `theme/` **next to `process.execPath`** (i.e. next to `clawdbot`).
+- So even if bun can embed assets, the runtime expects filesystem paths. Keep the sidecar files.
+
+## Build pipeline
+
+Packaging script:
+- `scripts/package-mac-app.sh`
+
+It builds:
+- TS: `pnpm exec tsc`
+- Swift app + helper: `swift build …`
+- bun relay: `bun build dist/macos/relay.js --compile --bytecode …`
+
+Important bundler flags:
+- `--compile`: produces a standalone executable
+- `--bytecode`: reduces startup time / parsing overhead (works here)
+- externals:
+  - `-e electron`
+  - Reason: avoid bundling Electron stubs in the relay binary
+
+Version injection:
+- `--define "__CLAWDBOT_VERSION__=\"<pkg version>\""`
+- `src/version.ts` also supports `__CLAWDBOT_VERSION__` (and `CLAWDBOT_BUNDLED_VERSION`) so `--version` doesn’t depend on reading `package.json` at runtime.
+
+## Launchd (Gateway as LaunchAgent)
+
+Label:
+- `com.clawdbot.gateway`
+
+Plist location (per-user):
+- `~/Library/LaunchAgents/com.clawdbot.gateway.plist`
+
+Manager:
+- `apps/macos/Sources/Clawdbot/GatewayLaunchAgentManager.swift`
+
+Behavior:
+- “Clawdbot Active” enables/disables the LaunchAgent.
+- App quit does **not** stop the gateway (launchd keeps it alive).
+
+Logging:
+- launchd stdout/err: `/tmp/clawdbot/clawdbot-gateway.log`
+
+Default LaunchAgent env:
+- `CLAWDBOT_IMAGE_BACKEND=sips` (avoid sharp native addon under bun)
+
+## Codesigning (hardened runtime + bun)
+
+Symptom (when mis-signed):
+- `Ran out of executable memory …` on launch
+
+Fix:
+- The bun executable needs JIT-ish permissions under hardened runtime.
+- `scripts/codesign-mac-app.sh` signs `Relay/clawdbot` with:
+  - `com.apple.security.cs.allow-jit`
+  - `com.apple.security.cs.allow-unsigned-executable-memory`
+
+## Image processing under bun
+
+Problem:
+- bun can’t load some native Node addons like `sharp` (and we don’t want to ship native addon trees for the gateway).
+
+Solution:
+- Central helper `src/media/image-ops.ts`
+  - Prefers `/usr/bin/sips` on macOS (esp. when running under bun)
+  - Falls back to `sharp` when available (Node/dev)
+- Used by:
+  - `src/web/media.ts` (optimize inbound/outbound images)
+  - `src/browser/screenshot.ts`
+  - `src/agents/pi-tools.ts` (image sanitization)
+
+## Browser control server
+
+The Gateway starts the browser control server (loopback only) from `src/gateway/server.ts`.
+It’s started from the relay daemon process, so the relay binary includes Playwright deps.
+
+## Tests / smoke checks
+
+From a packaged app (local build):
+
+```bash
+dist/Clawdbot.app/Contents/Resources/Relay/clawdbot --version
+
+CLAWDBOT_SKIP_PROVIDERS=1 \
+CLAWDBOT_SKIP_CANVAS_HOST=1 \
+dist/Clawdbot.app/Contents/Resources/Relay/clawdbot gateway-daemon --port 18999 --bind loopback
+```
+
+Then, in another shell:
+
+```bash
+pnpm -s clawdbot gateway call health --url ws://127.0.0.1:18999 --timeout 3000
+```
+
+## Repo hygiene
+
+Bun may leave dotfiles like `*.bun-build` in the repo root or subfolders.
+- These are ignored via `.gitignore` (`*.bun-build`).
+
+## DMG styling (human installer)
+
+`scripts/create-dmg.sh` styles the DMG via Finder AppleScript.
+
+Rules of thumb:
+- Use a **72dpi** background image that matches the Finder window size in points.
+- Preferred asset: `assets/dmg-background-small.png` (**500×320**).
+- Default icon positions: app `{125,160}`, Applications `{375,160}`.