clawdbot 2026.1.4-1

package/docs/control-api.md

@@ -0,0 +1,49 @@
+---
+summary: "Deprecated newline-delimited control channel API (pre-gateway)"
+read_when:
+  - Maintaining legacy control channel support
+---
+# Control channel API (newline-delimited JSON)
+
+**Deprecated (historical):** superseded by the WebSocket Gateway protocol (`clawdbot gateway`, see `docs/architecture.md` and `docs/gateway.md`).
+Current builds use a WebSocket server on `ws://127.0.0.1:18789` and do **not** expose this TCP control channel.
+
+Legacy endpoint (if present in an older build): `127.0.0.1:18789` (TCP, localhost only), typically reached via SSH port forward in remote mode.
+
+## Frame format
+Each line is a JSON object. Two shapes exist:
+- **Request**: `{ "type": "request", "id": "<uuid>", "method": "health" | "status" | "last-heartbeat" | "set-heartbeats" | "ping", "params"?: { ... } }`
+- **Response**: `{ "type": "response", "id": "<same id>", "ok": true, "payload"?: { ... } }` or `{ "type": "response", "id": "<same id>", "ok": false, "error": "message" }`
+- **Event**: `{ "type": "event", "event": "heartbeat" | "gateway-status" | "log", "payload": { ... } }`
+
+## Methods
+- `ping`: sanity check. Payload: `{ pong: true, ts }`.
+- `health`: returns the gateway health snapshot (same shape as `clawdbot health --json`).
+- `status`: shorter summary (linked/authAge/heartbeatSeconds, session counts).
+- `last-heartbeat`: returns the most recent heartbeat event the gateway has seen.
+- `set-heartbeats { enabled: boolean }`: toggle heartbeat scheduling.
+
+## Events
+- `heartbeat` payload:
+  ```json
+  {
+    "ts": 1765224052664,
+    "status": "sent" | "ok-empty" | "ok-token" | "skipped" | "failed",
+    "to": "+15551234567",
+    "preview": "Heartbeat OK",
+    "hasMedia": false,
+    "durationMs": 1025,
+    "reason": "<error text>" // only on failed/skipped
+  }
+  ```
+- `gateway-status` payload: `{ "state": "starting" | "running" | "restarting" | "failed" | "stopped", "pid"?: number, "reason"?: string }`
+- `log` payload: arbitrary log line; optional, can be disabled.
+
+## Suggested client flow
+1) Connect (or reconnect) → send `ping`.
+2) Send `health` and `last-heartbeat` to populate UI.
+3) Listen for `event` frames; update UI in real time.
+4) For user toggles, send `set-heartbeats` and await response.
+
+## Backward compatibility
+- If the control channel is unavailable: that’s expected on modern builds. Use the Gateway WS protocol instead.

package/docs/control-ui.md

@@ -0,0 +1,83 @@
+---
+summary: "Browser-based control UI for the Gateway (chat, nodes, config)"
+read_when:
+  - You want to operate the Gateway from a browser
+  - You want Tailnet access without SSH tunnels
+---
+# Control UI (browser)
+
+The Control UI is a small **Vite + Lit** single-page app served by the Gateway:
+
+- default: `http://<host>:18789/`
+- optional prefix: set `gateway.controlUi.basePath` (e.g. `/clawdbot`)
+
+It speaks **directly to the Gateway WebSocket** on the same port.
+
+Auth is supplied during the WebSocket handshake via:
+- `connect.params.auth.token`
+- `connect.params.auth.password`
+The dashboard settings panel lets you store a token; passwords are not persisted.
+
+## What it can do (today)
+- Chat with the model via Gateway WS (`chat.history`, `chat.send`, `chat.abort`)
+- Stream tool calls + live tool output cards in Chat (agent events)
+- Connections: WhatsApp/Telegram status + QR login + Telegram config (`providers.status`, `web.login.*`, `config.set`)
+- Instances: presence list + refresh (`system-presence`)
+- Sessions: list + per-session thinking/verbose overrides (`sessions.list`, `sessions.patch`)
+- Cron jobs: list/add/run/enable/disable + run history (`cron.*`)
+- Skills: status, enable/disable, install, API key updates (`skills.*`)
+- Nodes: list + caps (`node.list`)
+- Config: view/edit `~/.clawdbot/clawdbot.json` (`config.get`, `config.set`)
+- Config schema + form rendering (`config.schema`); Raw JSON editor remains available
+- Debug: status/health/models snapshots + event log + manual RPC calls (`status`, `health`, `models.list`)
+
+## Tailnet access (recommended)
+
+### Integrated Tailscale Serve (preferred)
+
+Keep the Gateway on loopback and let Tailscale Serve proxy it with HTTPS:
+
+```bash
+clawdbot gateway --tailscale serve
+```
+
+Open:
+- `https://<magicdns>/` (or your configured `gateway.controlUi.basePath`)
+
+By default, the gateway trusts Tailscale identity headers in serve mode. You can still set
+`CLAWDBOT_GATEWAY_TOKEN` or `gateway.auth` if you want a shared secret instead.
+
+### Bind to tailnet + token (legacy)
+
+```bash
+clawdbot gateway --bind tailnet --token "$(openssl rand -hex 32)"
+```
+
+Then open:
+- `http://<tailscale-ip>:18789/` (or your configured `gateway.controlUi.basePath`)
+
+Paste the token into the UI settings (sent as `connect.params.auth.token`).
+
+## Building the UI
+
+The Gateway serves static files from `dist/control-ui`. Build them with:
+
+```bash
+pnpm ui:install
+pnpm ui:build
+```
+
+Optional absolute base (when you want fixed asset URLs):
+
+```bash
+CLAWDBOT_CONTROL_UI_BASE_PATH=/clawdbot/ pnpm ui:build
+```
+
+For local development (separate dev server):
+
+```bash
+pnpm ui:install
+pnpm ui:dev
+```
+
+Then point the UI at your Gateway WS URL (e.g. `ws://127.0.0.1:18789`).

package/docs/cron.md

@@ -0,0 +1,374 @@
+---
+summary: "RFC: Cron jobs + wakeups for Clawd/Clawdbot (main vs isolated sessions)"
+read_when:
+  - Designing scheduled jobs, alarms, or wakeups
+  - Adding Gateway methods or CLI commands for automation
+  - Adjusting heartbeat behavior or session routing
+---
+
+# RFC: Cron jobs + wakeups for Clawd
+
+Status: Draft  
+Last updated: 2025-12-13
+
+## Context
+
+Clawdbot already has:
+- A **gateway heartbeat runner** that runs the agent with `HEARTBEAT` and suppresses `HEARTBEAT_OK` (`src/infra/heartbeat-runner.ts`).
+- A lightweight, in-memory **system event queue** (`enqueueSystemEvent`) that is injected into the next **main session** turn (`drainSystemEvents` in `src/auto-reply/reply.ts`).
+- A WebSocket **Gateway** daemon that is intended to be always-on (`docs/gateway.md`).
+
+This RFC adds a small “cron job system” so Clawd can schedule future work and reliably wake itself up:
+- **Delayed**: run on the *next* normal heartbeat tick
+- **Immediate**: run *now* (trigger a heartbeat immediately)
+- **Isolated jobs**: optionally run in their own session that does not pollute the main session and can run concurrently (within configured limits).
+
+## Goals
+
+- Provide a **persistent job store** and an **in-process scheduler** owned by the Gateway.
+- Allow each job to target either:
+  - `sessionTarget: "main"`: inject as `System:` lines and rely on the main heartbeat (or trigger it immediately).
+  - `sessionTarget: "isolated"`: run an agent turn in a dedicated session key (job session), optionally delivering a message and/or posting a summary back to main.
+- Expose a stable control surface:
+  - **Gateway methods** (`cron.*`, `wake`) for programmatic usage (mac app, CLI, agents).
+  - **CLI commands** (`clawdbot cron ...`) to add/remove/edit/list and to debug `run`.
+- Produce clear, structured **logs** for job lifecycle and execution outcomes.
+
+## Non-goals (v1)
+
+- Multi-host distributed scheduling.
+- Exactly-once semantics across crashes (we aim for “at-least-once with idempotency hooks”).
+- A full Unix-cron parser as the only schedule format (we can support it, but v1 should not require complex cron features to be useful).
+
+## Terminology
+
+- **Wake**: a request to ensure the agent gets a turn soon (either right now or next heartbeat).
+- **Main session**: the canonical session bucket (default key `"main"`) that receives `System:` events.
+- **Isolated session**: a per-job session key (e.g. `cron:<jobId>`) with its own session id / session file.
+
+## User stories
+
+- “Remind me in 20 minutes” → add a one-shot job that triggers an immediate heartbeat at T+20m.
+- “Every weekday at 7:30, wake me up and start music” → recurring job, isolated session, deliver to WhatsApp.
+- “Every hour, check battery; only interrupt me if < 20%” → isolated job that decides whether to deliver; may also post a brief status to main.
+- “Next heartbeat, please check calendar” → delayed wake targeting main session.
+
+## Job model
+
+### Storage schema (v1)
+
+Each job is a JSON object with stable keys (unknown keys ignored for forward compatibility):
+
+- `id: string` (UUID)
+- `name: string` (required)
+- `description?: string` (optional)
+- `enabled: boolean`
+- `createdAtMs: number`
+- `updatedAtMs: number`
+- `schedule` (one of)
+  - `{"kind":"at","atMs":number}` (one-shot)
+  - `{"kind":"every","everyMs":number,"anchorMs"?:number}` (simple interval)
+  - `{"kind":"cron","expr":string,"tz"?:string}` (optional; see “Schedule parsing”)
+- `sessionTarget: "main" | "isolated"`
+- `wakeMode: "next-heartbeat" | "now"`
+  - For `sessionTarget:"isolated"`, `wakeMode:"now"` means “run immediately when due”.
+  - For `sessionTarget:"main"`, `wakeMode` controls whether we trigger the heartbeat immediately or just enqueue and wait.
+- `payload` (one of)
+  - `{"kind":"systemEvent","text":string}` (enqueue as `System:`)
+  - `{"kind":"agentTurn","message":string,"deliver"?:boolean,"channel"?: "last"|"whatsapp"|"telegram"|"discord"|"signal"|"imessage","to"?:string,"timeoutSeconds"?:number}`
+- `isolation` (optional; only meaningful for isolated jobs)
+  - `{"postToMainPrefix"?: string}`
+- `runtime` (optional)
+  - `{"maxAttempts"?:number,"retryBackoffMs"?:number}` (best-effort retries; defaults off)
+- `state` (runtime-maintained)
+  - `{"nextRunAtMs":number,"lastRunAtMs"?:number,"lastStatus"?: "ok"|"error"|"skipped","lastError"?:string,"lastDurationMs"?:number}`
+
+### Key behavior
+
+- `sessionTarget:"main"` jobs always enqueue `payload.kind:"systemEvent"` (directly or derived from `agentTurn` results; see below).
+- `sessionTarget:"isolated"` jobs create/use a stable session key: `cron:<jobId>`.
+
+## Storage location
+
+Cron persists everything under `~/.clawdbot/cron/`:
+- Job store: `~/.clawdbot/cron/jobs.json`
+- Run history: `~/.clawdbot/cron/runs/<jobId>.jsonl`
+
+You can override the job store path via `cron.store` in config.
+
+The scheduler should never require additional configuration for the base directory (Clawdbot already treats `~/.clawdbot` as fixed).
+
+## Enabling
+
+Cron execution is enabled by default inside the Gateway.
+
+To disable it, set:
+
+```json5
+{
+  cron: {
+    enabled: false,
+    // optional:
+    store: "~/.clawdbot/cron/jobs.json",
+    maxConcurrentRuns: 1
+  }
+}
+```
+
+You can also disable scheduling via the environment variable `CLAWDBOT_SKIP_CRON=1`.
+
+## Scheduler design
+
+### Ownership
+
+The Gateway owns:
+- the scheduler timer,
+- job store reads/writes,
+- job execution (enqueue system events and/or agent turns).
+
+This keeps scheduling unified with the always-on process and prevents “two schedulers” when multiple CLIs run.
+
+### Timer strategy
+
+- Maintain an in-memory heap/array of enabled jobs keyed by `state.nextRunAtMs`.
+- Use a **single `setTimeout`** to wake at the earliest next run.
+- On wake:
+  - compute all due jobs (now >= nextRunAtMs),
+  - mark them “in flight” (in memory),
+  - persist updated `state` (at least bump `nextRunAtMs` / `lastRunAtMs`) before starting execution to minimize duplicate runs on crash,
+  - execute jobs (with concurrency limits),
+  - persist final `lastStatus/lastError/lastDurationMs`,
+  - re-arm timer for the next earliest run.
+
+### Schedule parsing
+
+V1 can ship with `at` + `every` without extra deps.
+
+If we add `"kind":"cron"`:
+- Use a well-maintained parser (we use `croner`) and support:
+  - 5-field cron (`min hour dom mon dow`) at minimum
+  - optional `tz`
+- Store `nextRunAtMs` computed by the parser; re-compute after each run.
+
+## Execution semantics
+
+### Main session jobs
+
+Main session jobs do not run the agent directly by default.
+
+When due:
+1) `enqueueSystemEvent(job.payload.text)` (or a derived message)
+2) If `wakeMode:"now"`, trigger an immediate heartbeat run (see “Heartbeat wake hook”).
+3) Otherwise do nothing else (the next scheduled heartbeat will pick up the system event).
+
+Why: This keeps the main session’s “proactive” behavior centralized in the heartbeat rules and avoids ad-hoc agent turns that might fight with inbound message processing.
+
+### Isolated session jobs
+
+Isolated jobs run an agent turn in a dedicated session key, intended to be separate from main.
+
+When due:
+- Build a message body that includes schedule metadata, e.g.:
+  - `"[cron:<jobId>] <job.name>: <payload.message>"`
+- Execute via the same agent runner path as other command-mode runs, but pinned to:
+  - `sessionKey = cron:<jobId>`
+  - `sessionId = store[sessionKey].sessionId` (create if missing)
+- Optionally deliver output (`payload.deliver === true`) to the configured channel/to.
+- Isolated jobs always enqueue a summary system event to the main session when they finish (derived from the last agent text output).
+  - Prefix defaults to `Cron`, and can be customized via `isolation.postToMainPrefix`.
+- If `deliver` is omitted/false, nothing is sent to external providers; you still get the main-session summary and can inspect the full isolated transcript in `cron:<jobId>`.
+
+### “Run in parallel to main”
+
+Clawdbot currently serializes command execution through a global in-process queue (`src/process/command-queue.ts`) to avoid collisions.
+
+To support isolated cron jobs running “in parallel”, we should introduce **lanes** (keyed queues) plus a global concurrency cap:
+- Lane `"main"`: inbound auto-replies + main heartbeat.
+- Lane `"cron"` (or `cron:<jobId>`): isolated jobs.
+- Configurable `cron.maxConcurrentRuns` (default 1 or 2).
+
+This yields:
+- isolated jobs can overlap with the main lane (up to cap),
+- each lane still preserves ordering for its own work (optional),
+- we retain safety knobs to prevent runaway resource contention.
+
+## Heartbeat wake hook (immediate vs next heartbeat)
+
+We need a way for the Gateway (or the scheduler) to request an immediate heartbeat without duplicating heartbeat logic.
+
+Design:
+- `startHeartbeatRunner` owns the real heartbeat execution and installs a wake handler.
+- Wake hook lives in `src/infra/heartbeat-wake.ts`:
+  - `setHeartbeatWakeHandler(fn | null)` installed by the heartbeat runner
+  - `requestHeartbeatNow({ reason, coalesceMs? })`
+- If the handler is absent, the request is stored as “pending”; the next time the handler is installed, it runs once.
+- Coalesce rapid calls and respect the “skip when queue busy” behavior (retry soon vs dropping).
+
+## Run history log (JSONL)
+
+In addition to normal structured logs, the Gateway writes an append-only run history “ledger” (JSONL) whenever a job finishes. This is intended for quick debugging (“did the job run, when, and what happened?”).
+
+Path rules:
+- Run logs are stored per job next to the store: `.../runs/<jobId>.jsonl`.
+
+Retention:
+- Best-effort pruning when the file grows beyond ~2MB; keep the newest ~2000 lines.
+
+Each log line includes (at minimum) job id, status/error, timing, and a `summary` string (systemEvent text for main jobs, and the last agent text output for isolated jobs).
+
+## Gateway API
+
+New methods (names can be bikeshed; `cron.*` is suggested):
+
+- `wake`
+  - params: `{ mode: "now" | "next-heartbeat", text: string }`
+  - effect: `enqueueSystemEvent(text)`, plus optional immediate heartbeat trigger
+
+- `cron.list`
+  - params: optional `{ includeDisabled?: boolean }`
+  - returns: `{ jobs: CronJob[] }`
+
+- `cron.add`
+  - params: job payload without `id/state` (server generates and returns created job)
+
+- `cron.update`
+  - params: `{ id: string, patch: Partial<CronJobWritableFields> }`
+
+- `cron.remove`
+  - params: `{ id: string }`
+
+- `cron.run`
+  - params: `{ id: string, mode?: "due" | "force" }` (debugging; does not change schedule unless `force` requires it)
+
+- `cron.runs`
+  - params: `{ id: string, limit?: number }`
+  - returns: `{ entries: CronRunLogEntry[] }`
+  - note: `id` is required (runs are stored per-job).
+
+The Gateway should broadcast a `cron` event for UI/debug:
+- event: `cron`
+  - payload: `{ jobId, action: "added"|"updated"|"removed"|"started"|"finished", status?, error?, nextRunAtMs? }`
+
+## CLI surface
+
+Add a `cron` command group (all commands should also support `--json` where sensible):
+
+- `clawdbot cron list [--json] [--all]`
+- `clawdbot cron add ...`
+  - schedule flags:
+    - `--at <iso8601|ms|relative>` (one-shot)
+    - `--every <duration>` (e.g. `10m`, `1h`)
+    - `--cron "<expr>" [--tz "<tz>"]`
+  - target flags:
+    - `--session main|isolated`
+    - `--wake now|next-heartbeat`
+  - payload flags (choose one):
+    - `--system-event "<text>"`
+    - `--message "<agent message>" [--deliver] [--channel last|whatsapp|telegram|discord|signal|imessage] [--to <dest>]`
+
+- `clawdbot cron edit <id> ...` (patch-by-flags, non-interactive)
+- `clawdbot cron rm <id>`
+- `clawdbot cron enable <id>` / `clawdbot cron disable <id>`
+- `clawdbot cron run <id> [--force]` (debug)
+- `clawdbot cron runs --id <id> [--limit <n>]` (run history)
+- `clawdbot cron status` (scheduler enabled + next wake)
+
+Additionally:
+- `clawdbot wake --mode now|next-heartbeat --text "<text>"` as a thin wrapper around `wake` for agents to call.
+
+## Examples
+
+### Run once at a specific time
+
+One-shot reminder that targets the main session and triggers a heartbeat immediately at the scheduled time:
+
+```bash
+clawdbot cron add \
+  --at "2025-12-14T07:00:00-08:00" \
+  --session main \
+  --wake now \
+  --system-event "Alarm: wake up (meeting in 30 minutes)."
+```
+
+### Run daily (calendar-accurate)
+
+Daily at 07:00 in a specific timezone (preferred over “every 24h” to avoid DST drift):
+
+```bash
+clawdbot cron add \
+  --cron "0 7 * * *" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --wake now \
+  --message "Daily check: scan calendar + inbox; deliver only if urgent." \
+  --deliver \
+  --channel last
+```
+
+### Run weekly (every Wednesday)
+
+Every Wednesday at 09:00:
+
+```bash
+clawdbot cron add \
+  --cron "0 9 * * 3" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --wake now \
+  --message "Weekly: summarize status and remind me of goals." \
+  --deliver \
+  --channel last
+```
+
+### “Next heartbeat”
+
+Enqueue a note for the main session but let the existing heartbeat cadence pick it up:
+
+```bash
+clawdbot wake --mode next-heartbeat --text "Next heartbeat: check battery + upcoming meetings."
+```
+
+## Logging & observability
+
+Logging requirements:
+- Use `getChildLogger({ module: "cron", jobId, runId, name })` for every run.
+- Log lifecycle:
+  - store load/save (debug; include job count)
+  - schedule recompute (debug; include nextRunAt)
+  - job start/end (info)
+  - job skipped (info; include reason)
+  - job error (warn; include error + stack where available)
+- Emit a concise user-facing line to stdout when running in CLI mode (similar to heartbeat logs).
+
+Suggested log events:
+- `cron: scheduler started` (jobCount, nextWakeAt)
+- `cron: job started` (jobId, scheduleKind, sessionTarget, wakeMode)
+- `cron: job finished` (status, durationMs, nextRunAtMs)
+- When `cron.enabled` is false, the Gateway logs `cron: disabled` and jobs will not run automatically (the CLI warns on `cron add`/`cron edit`).
+- Use `clawdbot cron status` to confirm the scheduler is enabled and see the next wake time.
+
+## Safety & security
+
+- Respect existing allowlists/routing rules: delivery defaults should not send to arbitrary destinations unless explicitly configured.
+- Provide a global “kill switch”:
+  - `cron.enabled: boolean` (default `true`).
+  - `gateway method set-heartbeats` already exists; cron should have similar.
+- Avoid persistence of sensitive payloads unless requested; job text may contain private content.
+
+## Testing plan (v1)
+
+- Unit tests:
+  - schedule computation for `at` and `every`
+  - job store read/write + migration behavior
+  - lane concurrency: main vs cron overlap is bounded
+  - “wake now” coalescing and pending behavior when provider not ready
+- Integration tests:
+  - start Gateway with `CLAWDBOT_SKIP_PROVIDERS=1`, add jobs, list/edit/remove
+  - simulate due jobs and assert `enqueueSystemEvent` called + cron events broadcast
+
+## Rollout plan
+
+1) Add the `wake` primitive + heartbeat wake hook (no persistent jobs yet).
+2) Add `cron.*` API and CLI wrappers with `at` + `every`.
+3) Add optional cron expression parsing (`kind:"cron"`) if needed.
+4) Add UI surfacing in WebChat/macOS app (optional).

package/docs/dashboard.md

@@ -0,0 +1,17 @@
+---
+summary: "Gateway dashboard (Control UI) access and auth"
+read_when:
+  - Changing dashboard authentication or exposure modes
+---
+# Dashboard (Control UI)
+
+The Gateway dashboard is the browser Control UI served at `/` by default
+(override with `gateway.controlUi.basePath`).
+
+Key references:
+- `docs/control-ui.md` for usage and UI capabilities.
+- `docs/tailscale.md` for Serve/Funnel automation.
+- `docs/web.md` for bind modes and security notes.
+
+Authentication is enforced at the WebSocket handshake via `connect.params.auth`
+(token or password). See `gateway.auth` in `docs/configuration.md`.

package/docs/device-models.md

@@ -0,0 +1,46 @@
+---
+summary: "How Clawdbot vendors Apple device model identifiers for friendly names in the macOS app."
+read_when:
+  - Updating device model identifier mappings or NOTICE/license files
+  - Changing how Instances UI displays device names
+---
+
+# Device model database (friendly names)
+
+The macOS companion app shows friendly Apple device model names in the **Instances** UI by mapping Apple model identifiers (e.g. `iPad16,6`, `Mac16,6`) to human-readable names.
+
+The mapping is vendored as JSON under:
+
+- `apps/macos/Sources/Clawdbot/Resources/DeviceModels/`
+
+## Data source
+
+We currently vendor the mapping from the MIT-licensed repository:
+
+- `kyle-seongwoo-jun/apple-device-identifiers`
+
+To keep builds deterministic, the JSON files are pinned to specific upstream commits (recorded in `apps/macos/Sources/Clawdbot/Resources/DeviceModels/NOTICE.md`).
+
+## Updating the database
+
+1. Pick the upstream commits you want to pin to (one for iOS, one for macOS).
+2. Update the commit hashes in `apps/macos/Sources/Clawdbot/Resources/DeviceModels/NOTICE.md`.
+3. Re-download the JSON files, pinned to those commits:
+
+```bash
+IOS_COMMIT="<commit sha for ios-device-identifiers.json>"
+MAC_COMMIT="<commit sha for mac-device-identifiers.json>"
+
+curl -fsSL "https://raw.githubusercontent.com/kyle-seongwoo-jun/apple-device-identifiers/${IOS_COMMIT}/ios-device-identifiers.json" \
+  -o apps/macos/Sources/Clawdbot/Resources/DeviceModels/ios-device-identifiers.json
+
+curl -fsSL "https://raw.githubusercontent.com/kyle-seongwoo-jun/apple-device-identifiers/${MAC_COMMIT}/mac-device-identifiers.json" \
+  -o apps/macos/Sources/Clawdbot/Resources/DeviceModels/mac-device-identifiers.json
+```
+
+4. Ensure `apps/macos/Sources/Clawdbot/Resources/DeviceModels/LICENSE.apple-device-identifiers.txt` still matches upstream (replace it if the upstream license changes).
+5. Verify the macOS app builds cleanly (no warnings):
+
+```bash
+swift build --package-path apps/macos
+```