@intent-systems/nexus 2026.1.5-3

package/docs/index.md

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

package/docs/ios.md

@@ -0,0 +1,372 @@
+---
+summary: "iOS app (node): architecture + connection runbook"
+read_when:
+  - Pairing or reconnecting the iOS node
+  - Debugging iOS bridge discovery or auth
+  - Sending screen/canvas commands to iOS
+  - Designing iOS node + gateway integration
+  - Extending the Gateway protocol for node/canvas commands
+  - Implementing Bonjour pairing or transport security
+---
+# iOS App (Node)
+
+Status: prototype implemented (internal) · Date: 2025-12-13
+
+## Connection Runbook
+
+This is the practical “how do I connect the iOS node” guide:
+
+**iOS app** ⇄ (Bonjour + TCP bridge) ⇄ **Gateway bridge** ⇄ (loopback WS) ⇄ **Gateway**
+
+The Gateway WebSocket stays loopback-only (`ws://127.0.0.1:18789`). The iOS node talks to the LAN-facing **bridge** (default `tcp://0.0.0.0:18790`) and uses Gateway-owned pairing.
+
+### Prerequisites
+
+- You can run the Gateway on the “master” machine.
+- iOS node app can reach the gateway bridge:
+  - Same LAN with Bonjour/mDNS, **or**
+  - Same Tailscale tailnet using Wide-Area Bonjour / unicast DNS-SD (see below), **or**
+  - Manual bridge host/port (fallback)
+- You can run the CLI (`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 Bonjour discovery (optional but recommended)
+
+From the gateway machine:
+
+```bash
+dns-sd -B _nexus-bridge._tcp local.
+```
+
+You should see your gateway advertising `_nexus-bridge._tcp`.
+
+If browse works, but the iOS node can’t connect, try resolving one instance:
+
+```bash
+dns-sd -L "<instance name>" _nexus-bridge._tcp local.
+```
+
+More debugging notes: [`docs/bonjour.md`](https://docs.nexus.bot/bonjour).
+
+#### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD
+
+If the iOS node and the gateway are on different networks but connected via Tailscale, multicast mDNS won’t cross the boundary. Use Wide-Area Bonjour / unicast DNS-SD instead:
+
+1) Set up a DNS-SD zone (example `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 the iOS node app
+
+In the iOS node app:
+- Pick the discovered bridge (or hit refresh).
+- If not paired yet, it will initiate pairing automatically.
+- After the first successful pairing, it will auto-reconnect **strictly to the last discovered gateway** on launch (including after reinstall), as long as the iOS Keychain entry is still present.
+
+#### Connection indicator (always visible)
+
+The Settings tab icon shows a small status dot:
+- **Green**: connected to the bridge
+- **Yellow**: connecting (subtle pulse)
+- **Red**: not connected / error
+
+### 4) Approve pairing (CLI)
+
+On the gateway machine:
+
+```bash
+nexus nodes pending
+```
+
+Approve the request:
+
+```bash
+nexus nodes approve <requestId>
+```
+
+After approval, the iOS node receives/stores the token and reconnects authenticated.
+
+Pairing details: [`docs/gateway/pairing.md`](https://docs.nexus.bot/gateway/pairing).
+
+### 5) Verify the node is connected
+
+- In the macOS app: **Instances** tab should show something like `iOS Node (...)` with a green “Active” presence dot shortly after connect.
+- Via nodes status (paired + connected):
+  ```bash
+  nexus nodes status
+  ```
+- Via Gateway (paired + connected):
+  ```bash
+  nexus gateway call node.list --params "{}"
+  ```
+- Via Gateway presence (legacy-ish, still useful):
+  ```bash
+  nexus gateway call system-presence --params "{}"
+  ```
+  Look for the node `instanceId` (often a UUID).
+
+### 6) Drive the iOS Canvas (draw / snapshot)
+
+The iOS node runs a WKWebView “Canvas” scaffold which exposes:
+- `window.__nexus.canvas`
+- `window.__nexus.ctx` (2D context)
+- `window.__nexus.setStatus(title, subtitle)`
+
+#### Gateway Canvas Host (recommended for web content)
+
+If you want the node to show real HTML/CSS/JS that the agent can edit on disk, point it at the Gateway canvas host.
+
+Note: nodes always use the standalone canvas host on `canvasHost.port` (default `18793`), bound to the bridge interface.
+
+1) Create `~/nexus/canvas/index.html` on the gateway host.
+
+2) Navigate the node to it (LAN):
+
+```bash
+nexus nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18793/__nexus__/canvas/"}'
+```
+
+Notes:
+- The server injects a live-reload client into HTML and reloads on file changes.
+- A2UI is hosted on the same canvas host at `http://<gateway-host>:18793/__nexus__/a2ui/`.
+- Tailnet (optional): if both devices are on Tailscale, use a MagicDNS name or tailnet IP instead of `.local`, e.g. `http://<gateway-magicdns>:18793/__nexus__/canvas/`.
+- iOS may require App Transport Security allowances to load plain `http://` URLs; if it fails to load, prefer HTTPS or adjust the iOS app’s ATS config.
+
+#### Draw with `canvas.eval`
+
+```bash
+nexus nodes invoke --node "iOS Node" --command canvas.eval --params "$(cat <<'JSON'
+{"javaScript":"(() => { const {ctx,setStatus} = window.__nexus; setStatus('Drawing','…'); ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle='#ff2d55'; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); setStatus(null,null); return 'ok'; })()"}
+JSON
+)"
+```
+
+#### Snapshot with `canvas.snapshot`
+
+```bash
+nexus nodes invoke --node 192.168.0.88 --command canvas.snapshot --params '{"maxWidth":900}'
+```
+
+The response includes `{ format, base64 }` image data (default `format="jpeg"`; pass `{"format":"png"}` when you specifically need lossless PNG).
+
+### Common gotchas
+
+- **iOS in background:** all `canvas.*` commands fail fast with `NODE_BACKGROUND_UNAVAILABLE` (bring the iOS node app to foreground).
+- **Return to default scaffold:** `canvas.navigate` with `{"url":""}` or `{"url":"/"}` returns to the built-in scaffold page.
+- **mDNS blocked:** some networks block multicast; use a different LAN or plan a tailnet-capable bridge (see [`docs/discovery.md`](https://docs.nexus.bot/discovery)).
+- **Wrong node selector:** `--node` can be the node id (UUID), display name (e.g. `iOS Node`), IP, or an unambiguous prefix. If it’s ambiguous, the CLI will tell you.
+- **Stale pairing / Keychain cleared:** if the pairing token is missing (or iOS Keychain was wiped), the node must pair again; approve a new pending request.
+- **App reinstall but no reconnect:** the node restores `instanceId` + last bridge preference from Keychain; if it still comes up “unpaired”, verify Keychain persistence on your device/simulator and re-pair once.
+
+## Design + Architecture
+
+### Goals
+- Build an **iOS app** that acts as a **remote node** for Nexus:
+  - **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 `NEXUS_GATEWAY_TOKEN`.
+- The Gateway exposes a Canvas file server (`canvasHost`) on `canvasHost.port` (default `18793`), so nodes can `canvas.navigate` to `http://<lanHost>:18793/__nexus__/canvas/` and auto-reload on file changes ([`docs/configuration.md`](https://docs.nexus.bot/configuration)).
+- macOS “Canvas” is controlled via the Gateway node protocol (`canvas.*`), matching iOS/Android ([`docs/mac/canvas.md`](https://docs.nexus.bot/mac/canvas)).
+- 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 “Nexus 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** (Nexus 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 (`nexus` / 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: `nexus` CLI can list pending requests and approve/reject.
+
+See [`docs/gateway/pairing.md`](https://docs.nexus.bot/gateway/pairing) for the API/events and storage.
+
+CLI (headless approvals):
+- `nexus nodes pending`
+- `nexus nodes approve <requestId>`
+- `nexus 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 (`/__nexus__/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
+nexus nodes invoke --node ios-node --command canvas.eval --params '{"javaScript":"(() => { const {ctx} = window.__nexus; 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:
+- `NexusProtocol` (generated models; platform-neutral)
+- `NexusGatewayClient` (shared WS framing + connect/req/res + seq-gap handling)
+- `NexusKit` (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 Nexus.xcodeproj
+```
+
+## Storage plan (private by default)
+### iOS
+- Canvas/workspace files (persistent, private):
+  - `Application Support/Nexus/canvas/<sessionKey>/...`
+- Snapshots / temp exports (evictable):
+  - `Library/Caches/Nexus/canvas-snapshots/<sessionKey>/...`
+- Credentials:
+  - Keychain (paired identity + bridge trust anchor)
+
+## Related docs
+
+- [`docs/gateway.md`](https://docs.nexus.bot/gateway) (gateway runbook)
+- [`docs/gateway/pairing.md`](https://docs.nexus.bot/gateway/pairing) (approval + storage)
+- [`docs/bonjour.md`](https://docs.nexus.bot/bonjour) (discovery debugging)
+- [`docs/discovery.md`](https://docs.nexus.bot/discovery) (LAN vs tailnet vs SSH)

package/docs/linux.md

@@ -0,0 +1,11 @@
+---
+summary: "Linux app status + contribution call"
+read_when:
+  - Looking for Linux companion app status
+  - Planning platform coverage or contributions
+---
+# Linux App
+
+Nexus core is fully supported on Linux. The core is written in TypeScript, so it runs anywhere Node runs.
+
+We do not have a Linux companion app yet. It is planned, and we would love contributions to make it happen.

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: `nexus 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 Nexus is open.”
+- Always: “Allow background location. Requires system permission.”
+- Precise: “Use precise GPS location. Toggle off to share approximate location.”