@intent-systems/nexus 2026.1.5-3

package/docs/android.md

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

package/docs/architecture.md

@@ -0,0 +1,114 @@
+---
+summary: "WebSocket gateway architecture, components, and client flows"
+read_when:
+  - Working on gateway protocol, clients, or transports
+---
+# Gateway Architecture
+
+Last updated: 2026-01-05
+
+## Overview
+- A single long-lived **Gateway** process owns all messaging surfaces (WhatsApp via Baileys, Telegram via grammY, Slack via Bolt, Discord via discord.js, Signal via signal-cli, iMessage via imsg, WebChat) and the control/event plane.
+- All clients (macOS app, CLI, web UI, automations) connect to the Gateway over one transport: **WebSocket on the configured bind host** (default `127.0.0.1:18789`; tunnel or VPN for remote).
+- One Gateway per host; it is the only place that is allowed to open a WhatsApp session. All sends/agent runs go through it.
+- By default: the Gateway exposes a Canvas host on `canvasHost.port` (default `18793`), serving `~/nexus/canvas` at `/__nexus__/canvas/` with live-reload; disable via `canvasHost.enabled=false` or `NEXUS_SKIP_CANVAS_HOST=1`.
+
+## Implementation snapshot (current code)
+
+### TypeScript Gateway (`src/gateway/server.ts`)
+- Single HTTP + WebSocket server (default `18789`); bind policy `loopback|lan|tailnet|auto`. Refuses non-loopback binds without auth; Tailscale serve/funnel requires loopback.
+- Handshake: first frame must be a `connect` request; AJV validates request + params against TypeBox schemas; protocol negotiated via `minProtocol`/`maxProtocol`.
+- `hello-ok` includes snapshot (presence/health/stateVersion/uptime/configPath/stateDir), features (methods/events), policy (max payload/buffer/tick), and `canvasHostUrl` when available.
+- Events emitted: `agent`, `chat`, `presence`, `tick`, `health`, `heartbeat`, `cron`, `talk.mode`, `node.pair.requested`, `node.pair.resolved`, `voicewake.changed`, `shutdown`.
+- Idempotency keys are required for `send`, `agent`, `chat.send`, and node invokes; the dedupe cache avoids double-sends on reconnects. Payload sizes are capped per connection.
+- Optional node bridge (`src/infra/bridge/server.ts`): TCP JSONL frames (`hello`, `pair-request`, `req/res`, `event`, `invoke`, `ping`). Node connect/disconnect updates presence and flows into the session bus.
+- Control UI + Canvas host: HTTP serves Control UI (base path configurable) and can host the A2UI canvas via `src/canvas-host/server.ts` (live reload). Canvas host URL is advertised to nodes + clients.
+
+### iOS node (`apps/ios`)
+- Discovery + pairing: `BridgeDiscoveryModel` uses `NWBrowser` Bonjour discovery and reads TXT fields for LAN/tailnet host hints plus gateway/bridge/canvas ports.
+- Auto-connect: `BridgeConnectionController` uses stored `node.instanceId` + Keychain token; supports manual host/port; performs `pair-and-hello`.
+- Bridge runtime: `BridgeSession` actor owns an `NWConnection`, JSONL frames, `hello`/`hello-ok`, ping/pong, `req/res`, server `event`s, and `invoke` callbacks; stores `canvasHostUrl`.
+- Commands: `NodeAppModel` executes `canvas.*`, `canvas.a2ui.*`, `camera.*`, `screen.record`, `location.get`. Canvas/camera/screen are blocked when backgrounded.
+- Canvas + actions: `WKWebView` with A2UI action bridge; accepts actions from local-network or trusted file URLs; intercepts `nexus://` deep links and forwards `agent.request` to the bridge.
+- Voice/talk: voice wake sends `voice.transcript` events and syncs triggers via `voicewake.get` + `voicewake.changed`; Talk Mode attaches to the bridge.
+
+### Android node (`apps/android`)
+- Discovery + pairing: `BridgeDiscovery` uses mDNS/NSD to find `_nexus-bridge._tcp`, with manual host/port fallback.
+- Auto-connect: `NodeRuntime` restores a stored token, performs `pair-and-hello`, and reconnects to the last discovered or manual bridge.
+- Bridge runtime: `BridgeSession` owns the TCP JSONL session (`hello`/`hello-ok`, ping/pong, `req/res`, `event`, `invoke`); stores `canvasHostUrl`.
+- Commands: `NodeRuntime` executes `canvas.*`, `canvas.a2ui.*`, `camera.*`, and chat/session events; foreground-only for canvas/camera.
+
+## Components and flows
+- **Gateway (daemon)**  
+  - Maintains WhatsApp (Baileys), Telegram (grammY), Slack (Bolt), Discord (discord.js), Signal (signal-cli), and iMessage (imsg) connections.  
+  - Exposes a typed WS API (req/resp + server push events).  
+  - Validates every inbound frame against JSON Schema; rejects anything before a mandatory `connect`.
+- **Clients (mac app / CLI / web admin)**  
+  - One WS connection per client.  
+  - Send requests (`health`, `status`, `send`, `agent`, `system-presence`, toggles) and subscribe to events (`tick`, `agent`, `presence`, `shutdown`).
+  - On macOS, the app can also be invoked via deep links (`nexus://agent?...`) which translate into the same Gateway `agent` request path (see [`docs/macos.md`](https://docs.nexus.bot/macos)).
+- **Agent process (Pi)**  
+  - Spawned by the Gateway on demand for `agent` calls; streams events back over the same WS connection.
+- **WebChat**  
+  - Serves static assets locally.  
+  - Holds a single WS connection to the Gateway for control/data; all sends/agent runs go through the Gateway WS.  
+  - Remote use goes through the same SSH/Tailscale tunnel as other clients.
+
+## Connection lifecycle (single client)
+```
+Client                    Gateway
+  |                          |
+  |---- req:connect -------->|
+  |<------ res (ok) ---------|   (or res error + close)
+  |   (payload=hello-ok carries snapshot: presence + health) 
+  |                          |
+  |<------ event:presence ---|   (deltas)
+  |<------ event:tick -------|   (keepalive/no-op)
+  |                          |
+  |------- req:agent ------->|
+  |<------ res:agent --------|   (ack: {runId,status:"accepted"})
+  |<------ event:agent ------|   (streaming)
+  |<------ res:agent --------|   (final: {runId,status,summary})
+  |                          |
+```
+## Wire protocol (summary)
+- Transport: WebSocket, text frames with JSON payloads.
+- First frame must be `req {type:"req", id, method:"connect", params:{minProtocol, maxProtocol, client:{name,version,platform,mode,instanceId}, caps, auth?, locale?, userAgent? } }`.
+- Server replies `res {type:"res", id, ok:true, payload: hello-ok }` or `ok:false` then closes.
+- After handshake:  
+  - Requests: `{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`  
+  - Events: `{type:"event", event:"agent"|"presence"|"tick"|"shutdown", payload, seq?, stateVersion?}`
+- If `NEXUS_GATEWAY_TOKEN` (or `--token`) is set, `connect.params.auth.token` must match; otherwise the socket closes with policy violation.
+- Presence payload is structured, not free text: `{host, ip, version, mode, lastInputSeconds?, ts, reason?, tags?[], instanceId? }`.
+- Agent runs are acked `{runId,status:"accepted"}` then complete with a final res `{runId,status,summary}`; streamed output arrives as `event:"agent"`.
+- Protocol versions are bumped on breaking changes; clients must match `minClient`; Gateway chooses within client’s min/max.
+- Idempotency keys are required for side-effecting methods (`send`, `agent`) to safely retry; server keeps a short-lived dedupe cache.
+- Policy in `hello-ok` communicates payload/queue limits and tick interval.
+
+## Type system and codegen
+- Source of truth: TypeBox (or ArkType) definitions in `protocol/` on the server.
+- Build step emits JSON Schema.  
+- Clients:
+  - TypeScript: uses the same TypeBox types directly.
+  - Swift: generated `Codable` models via quicktype from the JSON Schema.
+- Validation: AJV on the server for every inbound frame; optional client-side validation for defensive programming.
+
+## Invariants
+- Exactly one Gateway controls a single Baileys session per host. No fallbacks to ad-hoc direct Baileys sends.
+- Handshake is mandatory; any non-JSON or non-connect first frame is a hard close.
+- All methods and events are versioned; new fields are additive; breaking changes increment `protocol`.
+- No event replay: on seq gaps, clients must refresh (`health` + `system-presence`) and continue; presence is bounded via TTL/max entries.
+
+## Remote access
+- Preferred: Tailscale or VPN; alternate: SSH tunnel `ssh -N -L 18789:127.0.0.1:18789 user@host`.
+- Same protocol over the tunnel; same handshake. If a shared token is configured, clients must send it in `connect.params.auth.token` even over the tunnel.
+- Same protocol over the tunnel; same handshake. If a shared token is configured, clients must send it in `connect.params.auth.token` even over the tunnel.
+
+## Operations snapshot
+- Start: `nexus gateway` (foreground, logs to stdout).  
+  Supervise with launchd/systemd for restarts.  
+- Health: request `health` over WS; also surfaced in `hello-ok.health`.  
+- Metrics/logging: keep outside this spec; gateway should expose Prometheus text or structured logs separately.
+
+## Migration notes
+- This architecture supersedes the legacy stdin RPC and the ad-hoc TCP control port. New clients should speak only the WS protocol. Legacy compatibility is intentionally dropped.

package/docs/assets/markdown.css

@@ -0,0 +1,133 @@
+.markdown {
+  margin-top: 18px;
+  line-height: 1.7;
+}
+
+.mdx-content > h1:first-of-type {
+  display: none;
+}
+
+.markdown h1,
+.markdown h2,
+.markdown h3,
+.markdown h4 {
+  font-family: var(--font-pixel);
+  letter-spacing: 0.04em;
+  line-height: 1.15;
+}
+
+.markdown h1 {
+  font-size: clamp(28px, 4vw, 44px);
+  margin: 26px 0 10px;
+}
+
+.markdown h2 {
+  font-size: 22px;
+  margin: 26px 0 10px;
+}
+
+.markdown h3 {
+  font-size: 18px;
+  margin: 22px 0 8px;
+}
+
+.markdown p {
+  margin: 0 0 14px;
+}
+
+.markdown a {
+  color: var(--link);
+  text-decoration: none;
+  border-bottom: 1px dotted color-mix(in oklab, var(--link) 65%, transparent);
+}
+
+.markdown a:hover {
+  color: var(--link2);
+  border-bottom-color: color-mix(in oklab, var(--link2) 75%, transparent);
+}
+
+.markdown hr {
+  border: 0;
+  height: 1px;
+  background: linear-gradient(
+    90deg,
+    transparent,
+    color-mix(in oklab, var(--frame-border) 30%, transparent),
+    transparent
+  );
+  margin: 26px 0;
+}
+
+.markdown blockquote {
+  margin: 18px 0;
+  padding: 14px 14px;
+  border-radius: var(--radius-sm);
+  background: color-mix(in oklab, var(--panel) 70%, transparent);
+  border-left: 6px solid color-mix(in oklab, var(--accent) 60%, transparent);
+  color: var(--muted);
+}
+
+.markdown ul,
+.markdown ol {
+  margin: 0 0 14px 22px;
+}
+
+.markdown li {
+  margin: 4px 0;
+}
+
+.markdown img {
+  max-width: 100%;
+  height: auto;
+  border-radius: 12px;
+  border: 1px solid color-mix(in oklab, var(--frame-border) 20%, transparent);
+  box-shadow: 0 12px 0 -8px rgba(0, 0, 0, 0.18);
+}
+
+.markdown code {
+  font-family: var(--font-body);
+  font-size: 0.95em;
+  padding: 0.15em 0.35em;
+  border-radius: 8px;
+  background: color-mix(in oklab, var(--panel) 70%, var(--code-bg));
+  border: 1px solid color-mix(in oklab, var(--frame-border) 18%, transparent);
+}
+
+.markdown pre {
+  background: var(--code-bg);
+  color: var(--code-fg);
+  padding: 14px 14px;
+  border-radius: var(--radius-sm);
+  border: 1px solid color-mix(in oklab, var(--frame-border) 18%, transparent);
+  overflow-x: auto;
+  box-shadow: inset 0 0 0 1px color-mix(in oklab, var(--code-accent) 12%, transparent);
+}
+
+.markdown pre code {
+  background: transparent;
+  border: 0;
+  padding: 0;
+  color: inherit;
+}
+
+.markdown table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 16px 0 22px;
+  border: 1px solid color-mix(in oklab, var(--frame-border) 20%, transparent);
+  border-radius: var(--radius-sm);
+  overflow: hidden;
+}
+
+.markdown th,
+.markdown td {
+  padding: 10px 10px;
+  border-bottom: 1px solid color-mix(in oklab, var(--frame-border) 15%, transparent);
+  vertical-align: top;
+}
+
+.markdown th {
+  background: color-mix(in oklab, var(--panel2) 85%, transparent);
+  font-family: var(--font-pixel);
+  letter-spacing: 0.06em;
+}

package/docs/assets/pixel-lobster.svg

@@ -0,0 +1,60 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 16 16" role="img" aria-label="Pixel lobster">
+  <rect width="16" height="16" fill="none"/>
+  <!-- outline -->
+  <g fill="#3a0a0d">
+    <rect x="1" y="5" width="1" height="3"/>
+    <rect x="2" y="4" width="1" height="1"/>
+    <rect x="2" y="8" width="1" height="1"/>
+    <rect x="3" y="3" width="1" height="1"/>
+    <rect x="3" y="9" width="1" height="1"/>
+    <rect x="4" y="2" width="1" height="1"/>
+    <rect x="4" y="10" width="1" height="1"/>
+    <rect x="5" y="2" width="6" height="1"/>
+    <rect x="11" y="2" width="1" height="1"/>
+    <rect x="12" y="3" width="1" height="1"/>
+    <rect x="12" y="9" width="1" height="1"/>
+    <rect x="13" y="4" width="1" height="1"/>
+    <rect x="13" y="8" width="1" height="1"/>
+    <rect x="14" y="5" width="1" height="3"/>
+    <rect x="5" y="11" width="6" height="1"/>
+    <rect x="4" y="12" width="1" height="1"/>
+    <rect x="11" y="12" width="1" height="1"/>
+    <rect x="3" y="13" width="1" height="1"/>
+    <rect x="12" y="13" width="1" height="1"/>
+    <rect x="5" y="14" width="6" height="1"/>
+  </g>
+
+  <!-- body -->
+  <g fill="#ff4f40">
+    <rect x="5" y="3" width="6" height="1"/>
+    <rect x="4" y="4" width="8" height="1"/>
+    <rect x="3" y="5" width="10" height="1"/>
+    <rect x="3" y="6" width="10" height="1"/>
+    <rect x="3" y="7" width="10" height="1"/>
+    <rect x="4" y="8" width="8" height="1"/>
+    <rect x="5" y="9" width="6" height="1"/>
+    <rect x="5" y="12" width="6" height="1"/>
+    <rect x="6" y="13" width="4" height="1"/>
+  </g>
+
+  <!-- claws -->
+  <g fill="#ff775f">
+    <rect x="1" y="6" width="2" height="1"/>
+    <rect x="2" y="5" width="1" height="1"/>
+    <rect x="2" y="7" width="1" height="1"/>
+    <rect x="13" y="6" width="2" height="1"/>
+    <rect x="13" y="5" width="1" height="1"/>
+    <rect x="13" y="7" width="1" height="1"/>
+  </g>
+
+  <!-- eyes -->
+  <g fill="#081016">
+    <rect x="6" y="5" width="1" height="1"/>
+    <rect x="9" y="5" width="1" height="1"/>
+  </g>
+  <g fill="#f5fbff">
+    <rect x="6" y="4" width="1" height="1"/>
+    <rect x="9" y="4" width="1" height="1"/>
+  </g>
+</svg>
+