@intent-systems/nexus 2026.1.5-3

package/docs/gateway/cron.md

@@ -0,0 +1,61 @@
+---
+summary: "Gateway cron jobs: scheduling tasks and automation"
+read_when:
+  - Scheduling periodic tasks
+  - Automating syncs, backups, or reports
+---
+
+# Cron (Gateway)
+
+Cron jobs schedule tasks through the Gateway. Use them for recurring syncs, backups, and reports.
+
+## Basic commands
+
+```bash
+nexus cron list
+nexus cron add --schedule "0 2 * * *" --command "eve sync" --name "Daily iMessage sync"
+nexus cron remove <job-id>
+nexus cron disable <job-id>
+nexus cron enable <job-id>
+nexus cron logs <job-id>
+```
+
+## Schedule format
+
+Standard cron syntax: `minute hour day month weekday`
+
+Examples:
+
+- `0 9 * * *` daily at 9:00
+- `*/30 * * * *` every 30 minutes
+- `0 * * * *` hourly
+- `0 0 * * 0` Sundays at midnight
+
+## Common use cases
+
+```bash
+# Hourly WhatsApp sync
+nexus cron add --schedule "0 * * * *" --command "wacli sync" --name "Hourly WhatsApp sync"
+
+# Nightly backup
+nexus cron add --schedule "0 3 * * *" --command "nexus-cloud push -m 'Daily backup'" --name "Daily backup"
+
+# Update qmd index
+nexus cron add --schedule "0 * * * *" --command "qmd update" --name "Index update"
+```
+
+## Best practices
+
+- Test commands manually before scheduling.
+- Use absolute paths for binaries if PATH is unknown.
+- Redirect output to logs for debugging.
+
+## Troubleshooting
+
+If jobs do not run:
+
+```bash
+nexus status
+nexus cron list
+nexus cron logs <job-id>
+```

package/docs/gateway/heartbeat.md

@@ -0,0 +1,207 @@
+---
+summary: "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 you.
+
+## Quick start (beginner)
+
+1. Leave heartbeats enabled (default is `30m`) or set your own cadence.
+2. Create a tiny `HEARTBEAT.md` checklist in the agent workspace (optional but recommended).
+3. Decide where heartbeat messages should go (`target: "last"` is the default).
+4. Optional: enable heartbeat reasoning delivery for transparency.
+
+Example config:
+
+```json5
+{
+  agents: {
+    defaults: {
+      heartbeat: {
+        every: "30m",
+        target: "last",
+        // includeReasoning: true, // optional: send separate `Reasoning:` message too
+      }
+    }
+  }
+}
+```
+
+## Defaults
+
+- Interval: `30m` (set `agents.defaults.heartbeat.every`; use `0m` to disable).
+- Prompt body (configurable via `agents.defaults.heartbeat.prompt`):
+  `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`
+- The heartbeat prompt is sent **verbatim** as the user message. The system
+  prompt includes a “Heartbeat” section and the run is flagged internally.
+
+## What the heartbeat prompt is for
+
+The default prompt is intentionally broad:
+- **Background tasks**: “Consider outstanding tasks” nudges the agent to review
+  follow-ups (inbox, calendar, reminders, queued work) and surface anything urgent.
+- **Human check-in**: “Checkup sometimes on your human during day time” nudges an
+  occasional lightweight “anything you need?” message, but avoids night-time spam
+  by using your configured local timezone (see [/concepts/timezone](/concepts/timezone)).
+
+If you want a heartbeat to do something very specific (e.g. “check Gmail PubSub
+stats” or “verify gateway health”), set `agents.defaults.heartbeat.prompt` to a
+custom body (sent verbatim).
+
+## Response contract
+
+- If nothing needs attention, reply with **`HEARTBEAT_OK`**.
+- During heartbeat runs, Nexus treats `HEARTBEAT_OK` as an ack when it appears
+  at the **start or end** of the reply. The token is stripped and the reply is
+  dropped if the remaining content is **≤ `ackMaxChars`** (default: 300).
+- If `HEARTBEAT_OK` appears in the **middle** of a reply, it is not treated
+  specially.
+- For alerts, **do not** include `HEARTBEAT_OK`; return only the alert text.
+
+Outside heartbeats, stray `HEARTBEAT_OK` at the start/end of a message is stripped
+and logged; a message that is only `HEARTBEAT_OK` is dropped.
+
+## Config
+
+```json5
+{
+  agents: {
+    defaults: {
+      heartbeat: {
+        every: "30m",           // default: 30m (0m disables)
+        model: "anthropic/claude-opus-4-5",
+        includeReasoning: false, // default: false (deliver separate Reasoning: message when available)
+        target: "last",         // last | whatsapp | telegram | discord | slack | signal | imessage | none
+        to: "+15551234567",     // optional provider-specific override
+        prompt: "Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.",
+        ackMaxChars: 300         // max chars allowed after HEARTBEAT_OK
+      }
+    }
+  }
+}
+```
+
+### Field notes
+
+- `every`: heartbeat interval (duration string; default unit = minutes).
+- `model`: optional model override for heartbeat runs (`provider/model`).
+- `includeReasoning`: when enabled, also deliver the separate `Reasoning:` message when available (same shape as `/reasoning on`).
+- `target`:
+  - `last` (default): deliver to the last used external provider.
+  - explicit provider: `whatsapp` / `telegram` / `discord` / `slack` / `signal` / `imessage`.
+  - `none`: run the heartbeat but **do not deliver** externally.
+- `to`: optional recipient override (E.164 for WhatsApp, chat id for Telegram, etc.).
+- `prompt`: overrides the default prompt body (not merged).
+- `ackMaxChars`: max chars allowed after `HEARTBEAT_OK` before delivery.
+
+## Delivery behavior
+
+- Heartbeats run in the **main session** (`main`, or `global` when scope is global).
+- If the main queue is busy, the heartbeat is skipped and retried later.
+- If `target` resolves to no external destination, the run still happens but no
+  outbound message is sent.
+- Heartbeat-only replies do **not** keep the session alive; the last `updatedAt`
+  is restored so idle expiry behaves normally.
+
+## HEARTBEAT.md (optional)
+
+If a `HEARTBEAT.md` file exists in the workspace, the default prompt tells the
+agent to read it. Think of it as your “heartbeat checklist”: small, stable, and
+safe to include every 30 minutes.
+
+Keep it tiny (short checklist or reminders) to avoid prompt bloat.
+
+Example `HEARTBEAT.md`:
+
+```md
+# Heartbeat checklist
+
+- Quick scan: anything urgent in inboxes?
+- If it’s daytime, do a lightweight check-in if nothing else is pending.
+- If a task is blocked, write down *what is missing* and ask Peter next time.
+```
+
+### Can the agent update HEARTBEAT.md?
+
+Yes — if you ask it to.
+
+`HEARTBEAT.md` is just a normal file in the agent workspace, so you can tell the
+agent (in a normal chat) something like:
+- “Update `HEARTBEAT.md` to add a daily calendar check.”
+- “Rewrite `HEARTBEAT.md` so it’s shorter and focused on inbox follow-ups.”
+
+If you want this to happen proactively, you can also include an explicit line in
+your heartbeat prompt like: “If the checklist becomes stale, update HEARTBEAT.md
+with a better one.”
+
+Safety note: don’t put secrets (API keys, phone numbers, private tokens) into
+`HEARTBEAT.md` — it becomes part of the prompt context.
+
+## Manual wake (on-demand)
+
+You can enqueue a system event and trigger an immediate heartbeat with:
+
+```bash
+nexus wake --text "Check for urgent follow-ups" --mode now
+```
+
+Use `--mode next-heartbeat` to wait for the next scheduled tick.
+
+## Reasoning delivery (optional)
+
+By default, heartbeats deliver only the final “answer” payload.
+
+If you want transparency, enable:
+- `agents.defaults.heartbeat.includeReasoning: true`
+
+When enabled, heartbeats will also deliver a separate message prefixed
+`Reasoning:` (same shape as `/reasoning on`). This can be useful when the agent
+is managing multiple sessions/codexes and you want to see why it decided to ping
+you — but it can also leak more internal detail than you want. Prefer keeping it
+off in group chats.
+
+## Cost awareness
+
+Heartbeats run full agent turns. Shorter intervals burn more tokens. Keep
+`HEARTBEAT.md` small and consider a cheaper `model` or `target: "none"` if you
+only want internal state updates.
+
+## Heartbeat commands
+
+```bash
+nexus heartbeat list
+nexus heartbeat status <heartbeat-name>
+nexus heartbeat logs <heartbeat-name>
+nexus heartbeat run <heartbeat-name>
+nexus heartbeat disable <heartbeat-name>
+nexus heartbeat enable <heartbeat-name>
+```
+
+## Example heartbeats
+
+```yaml
+heartbeats:
+  - name: "Ollama health"
+    interval: 60
+    command: "curl -sf http://localhost:11434/api/tags > /dev/null"
+    alert_on_failure: true
+    alert_after: 2
+
+  - name: "Disk space"
+    interval: 300
+    command: "df -h / | awk 'NR==2 {print $5}' | sed 's/%//' | awk '{if ($1 > 90) exit 1}'"
+    alert_on_failure: true
+```
+
+## Troubleshooting
+
+If heartbeats do not run:
+
+```bash
+nexus status
+nexus heartbeat list
+```

package/docs/gateway/pairing.md

@@ -0,0 +1,109 @@
+---
+summary: "Gateway-owned node pairing (Option B) for iOS and other remote nodes"
+read_when:
+  - Implementing node pairing approvals without macOS UI
+  - Adding CLI flows for approving remote nodes
+  - Extending gateway protocol with node management
+---
+# Gateway-owned pairing (Option B)
+
+Goal: The Gateway (`nexus`) is the **source of truth** for which nodes are allowed to join the network.
+
+This enables:
+- Headless approval via terminal/CLI (no Swift UI required).
+- Optional macOS UI approval (Swift app is just a frontend).
+- One consistent membership store for iOS, mac nodes, future hardware nodes.
+
+## Concepts
+- **Pending request**: a node asked to join; requires explicit approve/reject.
+- **Paired node**: node is allowed; gateway returns an auth token for subsequent connects.
+- **Bridge**: direct transport endpoint owned by the gateway. The bridge does not decide membership.
+
+## API surface (gateway protocol)
+These are conceptual method names; wire them into [`src/gateway/protocol/schema.ts`](https://github.com/nexus/nexus/blob/main/src/gateway/protocol/schema.ts) and regenerate Swift types.
+
+### Events
+- `node.pair.requested`
+  - Emitted whenever a new pending pairing request is created.
+  - Payload:
+    - `requestId` (string)
+    - `nodeId` (string)
+    - `displayName?` (string)
+    - `platform?` (string)
+    - `version?` (string)
+    - `remoteIp?` (string)
+    - `silent?` (boolean) — hint that the UI may attempt auto-approval
+    - `ts` (ms since epoch)
+- `node.pair.resolved`
+  - Emitted when a pending request is approved/rejected.
+  - Payload:
+    - `requestId` (string)
+    - `nodeId` (string)
+    - `decision` ("approved" | "rejected" | "expired")
+    - `ts` (ms since epoch)
+
+### Methods
+- `node.pair.request`
+  - Creates (or returns) a pending request.
+  - Params: node metadata (same shape as `node.pair.requested` payload, minus `requestId`/`ts`).
+  - Optional `silent` flag hints that the UI can attempt an SSH auto-approve before showing an alert.
+  - Result:
+    - `status` ("pending")
+    - `created` (boolean) — whether this call created the pending request
+    - `request` (pending request object), including `isRepair` when the node was already paired
+  - Security: **never returns an existing token**. If a paired node “lost” its token, it must be approved again (token rotation).
+- `node.pair.list`
+  - Returns:
+    - `pending[]` (pending requests)
+    - `paired[]` (paired node records)
+- `node.pair.approve`
+  - Params: `{ requestId }`
+  - Result: `{ requestId, node: { nodeId, token, ... } }`
+  - Must be idempotent (first decision wins).
+- `node.pair.reject`
+  - Params: `{ requestId }`
+  - Result: `{ requestId, nodeId }`
+- `node.pair.verify`
+  - Params: `{ nodeId, token }`
+  - Result: `{ ok: boolean, node?: { nodeId, ... } }`
+
+## CLI flows
+CLI must be able to fully operate without any GUI:
+- `nexus nodes pending`
+- `nexus nodes approve <requestId>`
+- `nexus nodes reject <requestId>`
+- `nexus nodes status` (paired nodes + connection status/capabilities)
+
+Optional interactive helper:
+- `nexus nodes watch` (subscribe to `node.pair.requested` and prompt in-place)
+
+Implementation pointers:
+- CLI commands: [`src/cli/nodes-cli.ts`](https://github.com/nexus/nexus/blob/main/src/cli/nodes-cli.ts)
+- Gateway handlers + events: [`src/gateway/server.ts`](https://github.com/nexus/nexus/blob/main/src/gateway/server.ts) + [`src/gateway/server-methods/nodes.ts`](https://github.com/nexus/nexus/blob/main/src/gateway/server-methods/nodes.ts)
+- Pairing store: [`src/infra/node-pairing.ts`](https://github.com/nexus/nexus/blob/main/src/infra/node-pairing.ts) (under `~/nexus/state/nodes/`)
+- Optional macOS UI prompt (frontend only): [`apps/macos/Sources/Nexus/NodePairingApprovalPrompter.swift`](https://github.com/nexus/nexus/blob/main/apps/macos/Sources/Nexus/NodePairingApprovalPrompter.swift)
+  - Push-first: listens to `node.pair.requested`/`node.pair.resolved`, does a `node.pair.list` on startup/reconnect,
+    and only runs a slow safety poll while a request is pending/visible.
+
+## Storage (private, local)
+Gateway stores the authoritative state under `~/nexus/state/`:
+- `~/nexus/state/nodes/paired.json`
+- `~/nexus/state/nodes/pending.json` (or `~/nexus/state/nodes/pending/*.json`)
+
+Notes:
+- Tokens are secrets. Treat `paired.json` as sensitive.
+- Pending entries should have a TTL (e.g. 5 minutes) and expire automatically.
+
+## Bridge integration
+Target direction:
+- The gateway runs the bridge listener (LAN/tailnet-facing) and advertises discovery beacons (Bonjour).
+- The bridge is transport only; it forwards/scopes requests and enforces ACLs, but pairing decisions are made by the gateway.
+
+The macOS UI (Swift) can:
+- Subscribe to `node.pair.requested`, show an alert (including `remoteIp`), and call `node.pair.approve` or `node.pair.reject`.
+- Or ignore/dismiss (“Later”) and let CLI handle it.
+- When `silent` is set, it can try a short SSH probe (same user) and auto-approve if reachable; otherwise fall back to the normal alert.
+
+## Implementation note
+If the bridge is only provided by the macOS app, then “no Swift app running” cannot work end-to-end.
+The long-term goal is to move bridge hosting + Bonjour advertising into the Node gateway so headless pairing works by default.

package/docs/gateway-lock.md

@@ -0,0 +1,28 @@
+---
+summary: "Gateway singleton guard using the WebSocket listener bind"
+read_when:
+  - Running or debugging the gateway process
+  - Investigating single-instance enforcement
+---
+# Gateway lock
+
+Last updated: 2025-12-11
+
+## Why
+- Ensure only one gateway instance runs per host.
+- Survive crashes/SIGKILL without leaving stale lock files.
+- Fail fast with a clear error when the control port is already occupied.
+
+## Mechanism
+- The gateway binds the WebSocket listener (default `ws://127.0.0.1:18789`) immediately on startup using an exclusive TCP listener.
+- If the bind fails with `EADDRINUSE`, startup throws `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
+- The OS releases the listener automatically on any process exit, including crashes and SIGKILL—no separate lock file or cleanup step is needed.
+- On shutdown the gateway closes the WebSocket server and underlying HTTP server to free the port promptly.
+
+## Error surface
+- If another process holds the port, startup throws `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
+- Other bind failures surface as `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")`.
+
+## Operational notes
+- If the port is occupied by *another* process, the error is the same; free the port or choose another with `nexus gateway --port <port>`.
+- The macOS app still maintains its own lightweight PID guard before spawning the gateway; the runtime lock is enforced by the WebSocket bind.

package/docs/gateway.md

@@ -0,0 +1,227 @@
+---
+summary: "Runbook for the Gateway daemon, lifecycle, and operations"
+read_when:
+  - Running or debugging the gateway process
+---
+# Gateway (daemon) runbook
+
+Last updated: 2025-12-09
+
+## What it is
+- The always-on process that owns the single Baileys/Telegram connection and the control/event plane.
+- Replaces the legacy `gateway` command. CLI entry point: `nexus gateway`.
+- Runs until stopped; exits non-zero on fatal errors so the supervisor restarts it.
+
+## How to run (local)
+```bash
+pnpm nexus gateway --port 18789
+# for full debug/trace logs in stdio:
+pnpm nexus gateway --port 18789 --verbose
+# if the port is busy, terminate listeners then start:
+pnpm nexus gateway --force
+# dev loop (auto-reload on TS changes):
+pnpm gateway:watch
+```
+- Config hot reload watches `~/nexus/state/nexus.json` (or `NEXUS_CONFIG_PATH`).
+  - Default mode: `gateway.reload.mode="hybrid"` (hot-apply safe changes, restart on critical).
+  - Hot reload uses in-process restart via **SIGUSR1** when needed.
+  - Disable with `gateway.reload.mode="off"`.
+- Binds WebSocket control plane to `127.0.0.1:<port>` (default 18789).
+- The same port also serves HTTP (control UI, hooks, A2UI). Single-port multiplex.
+- Starts a Canvas file server by default on `canvasHost.port` (default `18793`), serving `http://<gateway-host>:18793/__nexus__/canvas/` from `~/nexus/canvas`. Disable with `canvasHost.enabled=false` or `NEXUS_SKIP_CANVAS_HOST=1`.
+- Logs to stdout; use launchd/systemd to keep it alive and rotate logs.
+- Pass `--verbose` to mirror debug logging (handshakes, req/res, events) from the log file into stdio when troubleshooting.
+- `--force` uses `lsof` to find listeners on the chosen port, sends SIGTERM, logs what it killed, then starts the gateway (fails fast if `lsof` is missing).
+- If you run under a supervisor (launchd/systemd/mac app child-process mode), a stop/restart typically sends **SIGTERM**; older builds may surface this as `pnpm` `ELIFECYCLE` exit code **143** (SIGTERM), which is a normal shutdown, not a crash.
+- **SIGUSR1** triggers an in-process restart (no external supervisor required). This is what the `gateway` agent tool uses.
+- Optional shared secret: pass `--token <value>` or set `NEXUS_GATEWAY_TOKEN` to require clients to send `connect.params.auth.token`.
+- Port precedence: `--port` > `NEXUS_GATEWAY_PORT` > `gateway.port` > default `18789`.
+
+## Remote access
+- Tailscale/VPN preferred; otherwise SSH tunnel:
+  ```bash
+  ssh -N -L 18789:127.0.0.1:18789 user@host
+  ```
+- Clients then connect to `ws://127.0.0.1:18789` through the tunnel.
+- If a token is configured, clients must include it in `connect.params.auth.token` even over the tunnel.
+
+## Multiple gateways (same host)
+
+Supported if you isolate state + config and use unique ports.
+
+### Dev profile (`--dev`)
+
+Fast path: run a fully-isolated dev instance (config/state/workspace) without touching your primary setup.
+
+```bash
+nexus --dev setup
+nexus --dev gateway --allow-unconfigured
+# then target the dev instance:
+nexus --dev status
+nexus --dev health
+```
+
+Defaults (can be overridden via env/flags/config):
+- `NEXUS_STATE_DIR=~/nexus/state-dev`
+- `NEXUS_CONFIG_PATH=~/nexus/state-dev/nexus.json`
+- `NEXUS_GATEWAY_PORT=19001` (Gateway WS + HTTP)
+- `bridge.port=19002` (derived: `gateway.port+1`)
+- `browser.controlUrl=http://127.0.0.1:19003` (derived: `gateway.port+2`)
+- `canvasHost.port=19005` (derived: `gateway.port+4`)
+- `agent.workspace` default becomes `~/nexus-dev` when you run `setup`/`onboard` under `--dev`.
+
+Derived ports (rules of thumb):
+- Base port = `gateway.port` (or `NEXUS_GATEWAY_PORT` / `--port`)
+- `bridge.port = base + 1` (or `NEXUS_BRIDGE_PORT` / config override)
+- `browser.controlUrl port = base + 2` (or `NEXUS_BROWSER_CONTROL_URL` / config override)
+- `canvasHost.port = base + 4` (or `NEXUS_CANVAS_HOST_PORT` / config override)
+- Browser profile CDP ports auto-allocate from `browser.controlPort + 9 .. + 108` (persisted per profile).
+
+Checklist per instance:
+- unique `gateway.port`
+- unique `NEXUS_CONFIG_PATH`
+- unique `NEXUS_STATE_DIR`
+- unique `agent.workspace`
+- separate WhatsApp numbers (if using WA)
+
+Example:
+```bash
+NEXUS_CONFIG_PATH=~/nexus/state/a.json NEXUS_STATE_DIR=~/nexus/state-a nexus gateway --port 19001
+NEXUS_CONFIG_PATH=~/nexus/state/b.json NEXUS_STATE_DIR=~/nexus/state-b nexus gateway --port 19002
+```
+
+## Protocol (operator view)
+- Mandatory first frame from client: `req {type:"req", id, method:"connect", params:{minProtocol,maxProtocol,client:{name,version,platform,deviceFamily?,modelIdentifier?,mode,instanceId}, caps, auth?, locale?, userAgent? } }`.
+- Gateway replies `res {type:"res", id, ok:true, payload:hello-ok }` (or `ok:false` with an error, then closes).
+- After handshake:
+  - Requests: `{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
+  - Events: `{type:"event", event, payload, seq?, stateVersion?}`
+- Structured presence entries: `{host, ip, version, platform?, deviceFamily?, modelIdentifier?, mode, lastInputSeconds?, ts, reason?, tags?[], instanceId? }`.
+- `agent` responses are two-stage: first `res` ack `{runId,status:"accepted"}`, then a final `res` `{runId,status:"ok"|"error",summary}` after the run finishes; streamed output arrives as `event:"agent"`.
+
+## Methods (initial set)
+- `health` — full health snapshot (same shape as `nexus health --json`).
+- `status` — short summary.
+- `system-presence` — current presence list.
+- `system-event` — post a presence/system note (structured).
+- `send` — send a message via the active provider(s).
+- `agent` — run an agent turn (streams events back on same connection).
+- `node.list` — list paired + currently-connected bridge nodes (includes `caps`, `deviceFamily`, `modelIdentifier`, `paired`, `connected`, and advertised `commands`).
+- `node.describe` — describe a node (capabilities + supported `node.invoke` commands; works for paired nodes and for currently-connected unpaired nodes).
+- `node.invoke` — invoke a command on a node (e.g. `canvas.*`, `camera.*`).
+- `node.pair.*` — pairing lifecycle (`request`, `list`, `approve`, `reject`, `verify`).
+
+See also: [`docs/presence.md`](https://docs.nexus.bot/presence) for how presence is produced/deduped and why `instanceId` matters.
+
+## Events
+- `agent` — streamed tool/output events from the agent run (seq-tagged).
+- `presence` — presence updates (deltas with stateVersion) pushed to all connected clients.
+- `tick` — periodic keepalive/no-op to confirm liveness.
+- `shutdown` — Gateway is exiting; payload includes `reason` and optional `restartExpectedMs`. Clients should reconnect.
+
+## WebChat integration
+- WebChat is a native SwiftUI UI that talks directly to the Gateway WebSocket for history, sends, abort, and events.
+- Remote use goes through the same SSH/Tailscale tunnel; if a gateway token is configured, the client includes it during `connect`.
+- macOS app connects via a single WS (shared connection); it hydrates presence from the initial snapshot and listens for `presence` events to update the UI.
+
+## Typing and validation
+- Server validates every inbound frame with AJV against JSON Schema emitted from the protocol definitions.
+- Clients (TS/Swift) consume generated types (TS directly; Swift via the repo’s generator).
+- Types live in `src/gateway/protocol/*.ts`; regenerate schemas/models with `pnpm protocol:gen` (writes `dist/protocol.schema.json`) and `pnpm protocol:gen:swift` (writes `apps/macos/Sources/NexusProtocol/GatewayModels.swift`).
+
+## Connection snapshot
+- `hello-ok` includes a `snapshot` with `presence`, `health`, `stateVersion`, and `uptimeMs` plus `policy {maxPayload,maxBufferedBytes,tickIntervalMs}` so clients can render immediately without extra requests.
+- `health`/`system-presence` remain available for manual refresh, but are not required at connect time.
+
+## Error codes (res.error shape)
+- Errors use `{ code, message, details?, retryable?, retryAfterMs? }`.
+- Standard codes:
+  - `NOT_LINKED` — WhatsApp not authenticated.
+  - `AGENT_TIMEOUT` — agent did not respond within the configured deadline.
+  - `INVALID_REQUEST` — schema/param validation failed.
+  - `UNAVAILABLE` — Gateway is shutting down or a dependency is unavailable.
+
+## Keepalive behavior
+- `tick` events (or WS ping/pong) are emitted periodically so clients know the Gateway is alive even when no traffic occurs.
+- Send/agent acknowledgements remain separate responses; do not overload ticks for sends.
+
+## Replay / gaps
+- Events are not replayed. Clients detect seq gaps and should refresh (`health` + `system-presence`) before continuing. WebChat and macOS clients now auto-refresh on gap.
+
+## Supervision (macOS example)
+- Use launchd to keep the daemon alive:
+  - Program: path to `nexus`
+  - Arguments: `gateway`
+  - KeepAlive: true
+  - StandardOut/Err: file paths or `syslog`
+- On failure, launchd restarts; fatal misconfig should keep exiting so the operator notices.
+- LaunchAgents are per-user and require a logged-in session; for headless setups use a custom LaunchDaemon (not shipped).
+
+Bundled mac app:
+- Nexus.app can bundle a bun-compiled gateway binary and install a per-user LaunchAgent labeled `com.nexus.gateway`.
+- To stop it cleanly, use `nexus gateway stop` (or `launchctl bootout gui/$UID/com.nexus.gateway`).
+- To restart, use `nexus gateway restart` (or `launchctl kickstart -k gui/$UID/com.nexus.gateway`).
+
+## Supervision (systemd user unit)
+Create `~/.config/systemd/user/nexus-gateway.service`:
+```
+[Unit]
+Description=Nexus Gateway
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=/usr/local/bin/nexus gateway --port 18789
+Restart=always
+RestartSec=5
+Environment=NEXUS_GATEWAY_TOKEN=
+WorkingDirectory=/home/youruser
+
+[Install]
+WantedBy=default.target
+```
+Enable lingering (required so the user service survives logout/idle):
+```
+sudo loginctl enable-linger youruser
+```
+Onboarding runs this on Linux (may prompt for sudo; writes `/var/lib/systemd/linger`).
+Then enable the service:
+```
+systemctl --user enable --now nexus-gateway.service
+```
+
+**Alternative (system service)** - for always-on or multi-user servers, you can
+install a systemd **system** unit instead of a user unit (no lingering needed).
+Create `/etc/systemd/system/nexus-gateway.service` (copy the unit above,
+switch `WantedBy=multi-user.target`, set `User=` + `WorkingDirectory=`), then:
+```
+sudo systemctl daemon-reload
+sudo systemctl enable --now nexus-gateway.service
+```
+
+## Supervision (Windows scheduled task)
+- Onboarding installs a Scheduled Task named `Nexus Gateway` (runs on user logon).
+- Requires a logged-in user session; for headless setups use a system service or a task configured to run without a logged-in user (not shipped).
+
+## Operational checks
+- Liveness: open WS and send `req:connect` → expect `res` with `payload.type="hello-ok"` (with snapshot).
+- Readiness: call `health` → expect `ok: true` and `web.linked=true`.
+- Debug: subscribe to `tick` and `presence` events; ensure `status` shows linked/auth age; presence entries show Gateway host and connected clients.
+
+## Safety guarantees
+- Only one Gateway per host; all sends/agent calls must go through it.
+- No fallback to direct Baileys connections; if the Gateway is down, sends fail fast.
+- Non-connect first frames or malformed JSON are rejected and the socket is closed.
+- Graceful shutdown: emit `shutdown` event before closing; clients must handle close + reconnect.
+
+## CLI helpers
+- `nexus gateway health|status` — request health/status over the Gateway WS.
+- `nexus gateway send --to <num> --message "hi" [--media-url ...]` — send via Gateway (idempotent).
+- `nexus gateway agent --message "hi" [--to ...]` — run an agent turn (waits for final by default).
+- `nexus gateway call <method> --params '{"k":"v"}'` — raw method invoker for debugging.
+- `nexus gateway stop|restart` — stop/restart the supervised gateway service (launchd/systemd/schtasks).
+- Gateway helper subcommands assume a running gateway on `--url`; they no longer auto-spawn one.
+
+## Migration guidance
+- Retire uses of `nexus gateway` and the legacy TCP control port.
+- Update clients to speak the WS protocol with mandatory connect and structured presence.