@intent-systems/nexus 2026.1.5-3

package/docs/mac/dev-setup.md

@@ -0,0 +1,81 @@
+---
+summary: "Setup guide for developers working on the Nexus macOS app"
+read_when:
+  - Setting up the macOS development environment
+---
+# macOS Developer Setup
+
+This guide covers the necessary steps to build and run the Nexus macOS application from source.
+
+## Prerequisites
+
+Before building the app, ensure you have the following installed:
+
+1.  **Xcode 26.2+**: Required for Swift development.
+2.  **Node.js & pnpm**: Required for the gateway and CLI components.
+3.  **Bun**: Required to package the embedded gateway relay.
+    ```bash
+    curl -fsSL https://bun.sh/install | bash
+    ```
+
+## 1. Initialize Submodules
+
+Nexus depends on several submodules (like `Peekaboo`). You must initialize these recursively:
+
+```bash
+git submodule update --init --recursive
+```
+
+## 2. Install Dependencies
+
+Install the project-wide dependencies:
+
+```bash
+pnpm install
+```
+
+## 3. Build and Package the App
+
+To build the macOS app and package it into `dist/Nexus.app`, run:
+
+```bash
+./scripts/package-mac-app.sh
+```
+
+If you don't have an Apple Developer ID certificate, the script will automatically use **ad-hoc signing** (`-`). 
+
+> **Note**: Ad-hoc signed apps may trigger security prompts. If the app crashes immediately with "Abort trap 6", see the [Troubleshooting](#troubleshooting) section.
+
+## 4. Install the CLI Helper
+
+The macOS app requires a symlink named `nexus` in `/usr/local/bin` or `/opt/homebrew/bin` to manage background tasks.
+
+**To install it:**
+1.  Open the Nexus app.
+2.  Go to the **General** settings tab.
+3.  Click **"Install CLI helper"** (requires administrator privileges).
+
+Alternatively, you can manually link it from your Admin account:
+```bash
+sudo ln -sf "/Users/$(whoami)/nexus/dist/Nexus.app/Contents/Resources/Relay/nexus" /usr/local/bin/nexus
+```
+
+## Troubleshooting
+
+### App Crashes on Permission Grant
+If the app crashes when you try to allow **Speech Recognition** or **Microphone** access, it may be due to a corrupted TCC cache or signature mismatch.
+
+**Fix:**
+1. Reset the TCC permissions:
+   ```bash
+   tccutil reset All com.nexus.mac.debug
+   ```
+2. If that fails, change the `BUNDLE_ID` temporarily in `scripts/package-mac-app.sh` to force a "clean slate" from macOS.
+
+### Gateway "Starting..." indefinitely
+If the gateway status stays on "Starting...", check if a zombie process is holding the port:
+
+```bash
+lsof -nP -i :18789
+```
+Kill any existing `node` or `nexus` processes listening on that port and restart the app.

package/docs/mac/health.md

@@ -0,0 +1,28 @@
+---
+summary: "How the macOS app reports gateway/Baileys health states"
+read_when:
+  - Debugging mac app health indicators
+---
+# Health Checks on macOS
+
+How to see whether the WhatsApp Web/Baileys bridge is healthy from the menu bar app.
+
+## Menu bar
+- Status dot now reflects Baileys health:
+  - Green: linked + socket opened recently.
+  - Orange: connecting/retrying.
+  - Red: logged out or probe failed.
+- Secondary line reads "Web: linked · auth 12m · socket ok" or shows the failure reason.
+- "Run Health Check" menu item triggers an on-demand probe.
+
+## Settings
+- General tab gains a Health card showing: linked auth age, session-store path/count, last check time, last error/status code, and buttons for Run Health Check / Reveal Logs.
+- Uses a cached snapshot so the UI loads instantly and falls back gracefully when offline.
+- **Connections tab** surfaces provider status + controls for WhatsApp/Telegram (login QR, logout, probe, last disconnect/error).
+
+## How the probe works
+- App runs `nexus health --json` via `ShellExecutor` every ~60s and on demand. The probe loads creds, attempts a short Baileys connect, and reports status without sending messages.
+- Cache the last good snapshot and the last error separately to avoid flicker; show the timestamp of each.
+
+## When in doubt
+- You can still use the CLI flow in [`docs/health.md`](https://docs.nexus.bot/health) (`nexus status`, `nexus status --deep`, `nexus health --json`) and tail `~/nexus/state/logs/nexus-*.log` for `web-heartbeat` / `web-reconnect`.

package/docs/mac/icon.md

@@ -0,0 +1,26 @@
+---
+summary: "Menu bar icon states and animations for Nexus on macOS"
+read_when:
+  - Changing menu bar icon behavior
+---
+# Menu Bar Icon States
+
+Author: steipete · Updated: 2025-12-06 · Scope: macOS app (`apps/macos`)
+
+- **Idle:** Normal icon animation (blink, occasional wiggle).
+- **Paused:** Status item uses `appearsDisabled`; no motion.
+- **Voice trigger (big ears):** Voice wake detector calls `AppState.triggerVoiceEars(ttl: nil)` when the wake word is heard, keeping `earBoostActive=true` while the utterance is captured. Ears scale up (1.9x), get circular ear holes for readability, then drop via `stopVoiceEars()` after 1s of silence. Only fired from the in-app voice pipeline.
+- **Working (agent running):** `AppState.isWorking=true` drives a “tail/leg scurry” micro-motion: faster leg wiggle and slight offset while work is in-flight. Currently toggled around WebChat agent runs; add the same toggle around other long tasks when you wire them.
+
+Wiring points
+- Voice wake: runtime/tester call `AppState.triggerVoiceEars(ttl: nil)` on trigger and `stopVoiceEars()` after 1s of silence to match the capture window.
+- Agent activity: set `AppStateStore.shared.setWorking(true/false)` around work spans (already done in WebChat agent call). Keep spans short and reset in `defer` blocks to avoid stuck animations.
+
+Shapes & sizes
+- Base icon drawn in `CritterIconRenderer.makeIcon(blink:legWiggle:earWiggle:earScale:earHoles:)`.
+- Ear scale defaults to `1.0`; voice boost sets `earScale=1.9` and toggles `earHoles=true` without changing overall frame (18×18 pt template image rendered into a 36×36 px Retina backing store).
+- Scurry uses leg wiggle up to ~1.0 with a small horizontal jiggle; it’s additive to any existing idle wiggle.
+
+Behavioral notes
+- No external CLI/broker toggle for ears/working; keep it internal to the app’s own signals to avoid accidental flapping.
+- Keep TTLs short (<10s) so the icon returns to baseline quickly if a job hangs.

package/docs/mac/logging.md

@@ -0,0 +1,51 @@
+---
+summary: "Nexus logging: rolling diagnostics file log + unified log privacy flags"
+read_when:
+  - Capturing macOS logs or investigating private data logging
+  - Debugging voice wake/session lifecycle issues
+---
+# Logging (macOS)
+
+## Rolling diagnostics file log (Debug pane)
+Nexus routes macOS app logs through swift-log (unified logging by default) and can write a local, rotating file log to disk when you need a durable capture.
+
+- Verbosity: **Debug pane → Logs → App logging → Verbosity**
+- Enable: **Debug pane → Logs → App logging → “Write rolling diagnostics log (JSONL)”**
+- Location: `~/Library/Logs/Nexus/diagnostics.jsonl` (rotates automatically; old files are suffixed with `.1`, `.2`, …)
+- Clear: **Debug pane → Logs → App logging → “Clear”**
+
+Notes:
+- This is **off by default**. Enable only while actively debugging.
+- Treat the file as sensitive; don’t share it without review.
+
+## Unified logging private data on macOS
+
+Unified logging redacts most payloads unless a subsystem opts into `privacy -off`. Per Peter's write-up on macOS [logging privacy shenanigans](https://steipete.me/posts/2025/logging-privacy-shenanigans) (2025) this is controlled by a plist in `/Library/Preferences/Logging/Subsystems/` keyed by the subsystem name. Only new log entries pick up the flag, so enable it before reproducing an issue.
+
+## Enable for Nexus (`com.nexus`)
+- Write the plist to a temp file first, then install it atomically as root:
+
+```bash
+cat <<'EOF' >/tmp/com.nexus.plist
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>DEFAULT-OPTIONS</key>
+    <dict>
+        <key>Enable-Private-Data</key>
+        <true/>
+    </dict>
+</dict>
+</plist>
+EOF
+sudo install -m 644 -o root -g wheel /tmp/com.nexus.plist /Library/Preferences/Logging/Subsystems/com.nexus.plist
+```
+
+- No reboot is required; logd notices the file quickly, but only new log lines will include private payloads.
+- View the richer output with the existing helper, e.g. `./scripts/clawlog.sh --category WebChat --last 5m`.
+
+## Disable after debugging
+- Remove the override: `sudo rm /Library/Preferences/Logging/Subsystems/com.nexus.plist`.
+- Optionally run `sudo log config --reload` to force logd to drop the override immediately.
+- Remember this surface can include phone numbers and message bodies; keep the plist in place only while you actively need the extra detail.

package/docs/mac/menu-bar.md

@@ -0,0 +1,69 @@
+---
+summary: "Menu bar status logic and what is surfaced to users"
+read_when:
+  - Tweaking mac menu UI or status logic
+---
+# Menu Bar Status Logic
+
+## What is shown
+- We surface the current agent work state in the menu bar icon and in the first status row of the menu.
+- Health status is hidden while work is active; it returns when all sessions are idle.
+- The “Nodes” block in the menu lists **devices** only (gateway bridge nodes via `node.list`), not client/presence entries.
+
+## State model
+- Sessions: events arrive with `runId` (per-run) plus `sessionKey` in the payload. The “main” session is the key `main`; if absent, we fall back to the most recently updated session.
+- Priority: main always wins. If main is active, its state is shown immediately. If main is idle, the most recently active non‑main session is shown. We do not flip‑flop mid‑activity; we only switch when the current session goes idle or main becomes active.
+- Activity kinds:
+  - `job`: high‑level command execution (`state: started|streaming|done|error`).
+  - `tool`: `phase: start|result` with `toolName` and `meta/args`.
+
+## IconState enum (Swift)
+- `idle`
+- `workingMain(ActivityKind)`
+- `workingOther(ActivityKind)`
+- `overridden(ActivityKind)` (debug override)
+
+### ActivityKind → glyph
+- `bash` → 💻
+- `read` → 📄
+- `write` → ✍️
+- `edit` → 📝
+- `attach` → 📎
+- default → 🛠️
+
+### Visual mapping
+- `idle`: normal critter.
+- `workingMain`: badge with glyph, full tint, leg “working” animation.
+- `workingOther`: badge with glyph, muted tint, no scurry.
+- `overridden`: uses the chosen glyph/tint regardless of activity.
+
+## Status row text (menu)
+- While work is active: `<Session role> · <activity label>`
+  - Examples: `Main · bash: pnpm test`, `Other · read: apps/macos/Sources/Nexus/AppState.swift`.
+- When idle: falls back to the health summary.
+
+## Event ingestion
+- Source: control‑channel `agent` events (`ControlChannel.handleAgentEvent`).
+- Parsed fields:
+  - `stream: "job"` with `data.state` for start/stop.
+  - `stream: "tool"` with `data.phase`, `name`, optional `meta`/`args`.
+- Labels:
+  - `bash`: first line of `args.command`.
+  - `read`/`write`: shortened path.
+  - `edit`: path plus inferred change kind from `meta`/diff counts.
+  - fallback: tool name.
+
+## Debug override
+- Settings ▸ Debug ▸ “Icon override” picker:
+  - `System (auto)` (default)
+  - `Working: main` (per tool kind)
+  - `Working: other` (per tool kind)
+  - `Idle`
+- Stored via `@AppStorage("iconOverride")`; mapped to `IconState.overridden`.
+
+## Testing checklist
+- Trigger main session job: verify icon switches immediately and status row shows main label.
+- Trigger non‑main session job while main idle: icon/status shows non‑main; stays stable until it finishes.
+- Start main while other active: icon flips to main instantly.
+- Rapid tool bursts: ensure badge does not flicker (TTL grace on tool results).
+- Health row reappears once all sessions idle.

package/docs/mac/peekaboo.md

@@ -0,0 +1,170 @@
+---
+summary: "Plan for integrating Peekaboo automation into Nexus via PeekabooBridge (socket-based TCC broker)"
+read_when:
+  - Hosting PeekabooBridge in Nexus.app
+  - Integrating Peekaboo as a submodule
+  - Changing PeekabooBridge protocol/paths
+---
+# Peekaboo Bridge in Nexus (macOS UI automation broker)
+
+## TL;DR
+- **Peekaboo removed its XPC helper** and now exposes privileged automation via a **UNIX domain socket bridge** (`PeekabooBridge` / `PeekabooBridgeHost`, socket name `bridge.sock`).
+- Nexus integrates by **optionally hosting the same bridge** inside **Nexus.app** (user-toggleable). The primary client is the **`peekaboo` CLI** (installed via npm); Nexus does not need its own `ui …` CLI surface.
+- For **visualizations**, we keep them in **Peekaboo.app** (best UX); Nexus stays a thin broker host. No visualizer toggle in Nexus.
+
+Non-goals:
+- No auto-launching Peekaboo.app.
+- No onboarding deep links from the automation endpoint (Nexus onboarding already handles permissions).
+- No AI provider/agent runtime dependencies in Nexus (avoid pulling Tachikoma/MCP into the Nexus app/CLI).
+
+## Big refactor (Dec 2025): XPC → Bridge
+Peekaboo’s privileged execution moved from “CLI → XPC helper” to “CLI → socket bridge host”. For Nexus this is a win:
+- It matches the existing “local socket + codesign checks” approach.
+- It lets us piggyback on **either** Peekaboo.app’s permissions **or** Nexus.app’s permissions (whichever is running).
+- It avoids “two apps with two TCC bubbles” unless needed.
+
+Reference (Peekaboo submodule): `Peekaboo/docs/bridge-host.md`.
+
+## Architecture
+### Processes
+- **Bridge hosts** (provide TCC-backed automation):
+  - **Peekaboo.app** (preferred; also provides visualizations + controls)
+  - **Claude.app** (secondary; lets `peekaboo` reuse Claude Desktop’s granted permissions)
+  - **Nexus.app** (secondary; “thin host” only)
+- **Bridge clients** (trigger single actions):
+  - `peekaboo …` (preferred; humans + agents)
+  - Optional: Nexus/Node shells out to `peekaboo` when it needs UI automation/capture
+
+### Host discovery (client-side)
+Order is deliberate:
+1. Peekaboo.app host (full UX)
+2. Claude.app host (piggyback on Claude Desktop permissions)
+3. Nexus.app host (piggyback on Nexus permissions)
+
+Socket paths (convention; exact paths must match Peekaboo):
+- Peekaboo: `~/Library/Application Support/Peekaboo/bridge.sock`
+- Claude: `~/Library/Application Support/Claude/bridge.sock`
+- Nexus: `~/Library/Application Support/nexus/bridge.sock`
+
+No auto-launch: if a host isn’t reachable, the command fails with a clear error (start Peekaboo.app, Claude.app, or Nexus.app).
+
+Override (debugging): set `PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock`.
+
+### Protocol shape
+- **Single request per connection**: connect → write one JSON request → half-close → read one JSON response → close.
+- **Timeout**: 10 seconds end-to-end per action (client enforced; host should also enforce per-operation).
+- **Errors**: human-readable string by default; structured envelope in `--json`.
+
+## Dependency strategy (submodule)
+Integrate Peekaboo via git submodule (nested submodules are OK).
+
+Path in Nexus repo:
+- `./Peekaboo` (Swabble-style; keep stable so SwiftPM path deps don’t churn).
+
+What Nexus should use:
+- **Client side**: `PeekabooBridge` (socket client + protocol models).
+- **Host side (Nexus.app)**: `PeekabooBridgeHost` + the minimal Peekaboo services needed to implement operations.
+
+What Nexus should *not* embed:
+- **Visualizer UI**: keep it in Peekaboo.app for now (toggle + controls live there).
+- **XPC**: don’t reintroduce helper targets; use the bridge.
+
+## IPC / CLI surface
+### No `nexus ui …`
+We avoid a parallel “Nexus UI automation CLI”. Instead:
+- `peekaboo` is the user/agent-facing CLI surface for automation and capture.
+- Nexus.app can host PeekabooBridge as a **thin TCC broker** so Peekaboo can piggyback on Nexus permissions when Peekaboo.app isn’t running.
+
+### Diagnostics
+Use Peekaboo’s built-in diagnostics to see which host would be used:
+- `peekaboo bridge status`
+- `peekaboo bridge status --verbose`
+- `peekaboo bridge status --json`
+
+### Output format
+Peekaboo commands default to human text output. Add `--json` for a structured envelope.
+
+### Timeouts
+Default timeout for UI actions: **10 seconds** end-to-end (client enforced; host should also enforce per-operation).
+
+## Coordinate model (multi-display)
+Requirement: coordinates are **per screen**, not global.
+
+Standardize for the CLI (agent-friendly): **top-left origin per screen**.
+
+Proposed request shape:
+- Requests accept `screenIndex` + `{x, y}` in that screen’s local coordinate space.
+- Nexus.app converts to global CG coordinates using `NSScreen.screens[screenIndex].frame.origin`.
+- Responses should echo both:
+  - The resolved `screenIndex`
+  - The local `{x, y}` and bounds
+  - Optionally the global `{x, y}` for debugging
+
+Ordering: use `NSScreen.screens` ordering consistently (documented in the CLI help + JSON schema).
+
+## Targeting (per app/window)
+Expose window/app targeting in the UI surface (align with Peekaboo targeting):
+- frontmost
+- by app name / bundle id
+- by window title substring
+- by (app, index)
+
+Peekaboo CLI targeting (agent-friendly):
+- `--bundle-id <id>` for app targeting
+- `--window-index <n>` (0-based) for disambiguating within an app when capturing
+
+All “see/click/type/scroll/wait” requests should accept a target (default: frontmost).
+
+## “See” + click packs (Playwright-style)
+Behavior stays aligned with Peekaboo:
+- `peekaboo see` returns element IDs (e.g. `B1`, `T3`) with bounds/labels.
+- Follow-up actions reference those IDs without re-scanning.
+
+`peekaboo see` should:
+- capture (optionally targeted) window/screen
+- return a screenshot **file path** (default: temp directory)
+- return a list of elements (text or JSON)
+
+Snapshot lifecycle requirement:
+- Host apps are long-lived, so snapshot state should be **in-memory by default**.
+- Snapshot scoping: “implicit snapshot” is **per target bundle id** (reuse last snapshot for that app when snapshot id is omitted).
+
+Practical flow (agent-friendly):
+- `peekaboo list apps` / `peekaboo list windows` provide bundle-id context for targeting.
+- `peekaboo see --bundle-id X` updates the implicit snapshot for `X`.
+- `peekaboo click --bundle-id X --on B1` reuses the most recent snapshot for `X` when `--snapshot-id` is omitted.
+
+## Visualizer integration
+Keep visualizations in **Peekaboo.app** for now.
+- Nexus hosts the bridge, but does not render overlays.
+- Any “visualizer enabled/disabled” setting is controlled in Peekaboo.app.
+
+## Screenshots (legacy → Peekaboo takeover)
+Nexus should not grow a separate screenshot CLI surface.
+
+Migration plan:
+- Use `peekaboo capture …` / `peekaboo see …` (returns a file path, default temp directory).
+- Once Nexus’ legacy screenshot plumbing is replaced, remove it cleanly (no aliases).
+
+## Permissions behavior
+If required permissions are missing:
+- return `ok=false` with a short human error message (e.g., “Accessibility permission missing”)
+- do not try to open System Settings from the automation endpoint
+
+## Security (socket auth)
+Both hosts must enforce:
+- filesystem perms on the socket path (owner read/write only)
+- server-side caller validation:
+  - require the caller’s code signature TeamID to be `Y5PE65HELJ`
+  - optional bundle-id allowlist for tighter scoping
+
+Debug-only escape hatch (development convenience):
+- “allow same-UID callers” means: *skip codesign checks for clients running under the same Unix user*.
+- This must be **opt-in**, **DEBUG-only**, and guarded by an env var (Peekaboo uses `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1`).
+
+## Next integration steps (after this doc)
+1. Add Peekaboo as a git submodule (nested submodules OK).
+2. Host `PeekabooBridgeHost` inside Nexus.app behind a single setting (“Enable Peekaboo Bridge”, default on).
+3. Ensure Nexus hosts the bridge at `~/Library/Application Support/nexus/bridge.sock` and speaks the PeekabooBridge JSON protocol.
+4. Validate with `peekaboo bridge status --verbose` that Peekaboo can select Nexus as the fallback host (no auto-launch).
+5. Keep all protocol decisions aligned with Peekaboo (coordinate system, element IDs, snapshot scoping, error envelopes).

package/docs/mac/permissions.md

@@ -0,0 +1,40 @@
+---
+summary: "macOS permission persistence (TCC) and signing requirements"
+read_when:
+  - Debugging missing or stuck macOS permission prompts
+  - Packaging or signing the macOS app
+  - Changing bundle IDs or app install paths
+---
+# macOS permissions (TCC)
+
+macOS permission grants are fragile. TCC associates a permission grant with the
+app's code signature, bundle identifier, and on-disk path. If any of those change,
+macOS treats the app as new and may drop or hide prompts.
+
+## Requirements for stable permissions
+- Same path: run the app from a fixed location (for Nexus, `dist/Nexus.app`).
+- Same bundle identifier: changing the bundle ID creates a new permission identity.
+- Signed app: unsigned or ad-hoc signed builds do not persist permissions.
+- Consistent signature: use a real Apple Development or Developer ID certificate
+  so the signature stays stable across rebuilds.
+
+Ad-hoc signatures generate a new identity every build. macOS will forget previous
+grants, and prompts can disappear entirely until the stale entries are cleared.
+
+## Recovery checklist when prompts disappear
+1. Quit the app.
+2. Remove the app entry in System Settings -> Privacy & Security.
+3. Relaunch the app from the same path and re-grant permissions.
+4. If the prompt still does not appear, reset TCC entries with `tccutil` and try again.
+5. Some permissions only reappear after a full macOS restart.
+
+Example resets (replace bundle ID as needed):
+
+```bash
+sudo tccutil reset Accessibility com.nexus.mac
+sudo tccutil reset ScreenCapture com.nexus.mac
+sudo tccutil reset AppleEvents
+```
+
+If you are testing permissions, always sign with a real certificate. Ad-hoc
+builds are only acceptable for quick local runs where permissions do not matter.

package/docs/mac/release.md

@@ -0,0 +1,76 @@
+---
+summary: "Nexus macOS release checklist (Sparkle feed, packaging, signing)"
+read_when:
+  - Cutting or validating a Nexus macOS release
+  - Updating the Sparkle appcast or feed assets
+---
+
+# Nexus macOS release (Sparkle)
+
+This app now ships Sparkle auto-updates. Release builds must be Developer ID–signed, zipped, and published with a signed appcast entry.
+
+## Prereqs
+- Developer ID Application cert installed (`Developer ID Application: Peter Steinberger (Y5PE65HELJ)` is expected).
+- Sparkle private key path set in the environment as `SPARKLE_PRIVATE_KEY_FILE`; key lives in `/Users/steipete/Library/CloudStorage/Dropbox/Backup/Sparkle` (same key as Trimmy; public key baked into Info.plist).
+- Notary credentials (keychain profile or API key) for `xcrun notarytool` if you want Gatekeeper-safe DMG/zip distribution.
+  - We use a Keychain profile named `nexus-notary`, created from App Store Connect API key env vars in your shell profile:
+    - `APP_STORE_CONNECT_API_KEY_P8`, `APP_STORE_CONNECT_KEY_ID`, `APP_STORE_CONNECT_ISSUER_ID`
+    - `echo "$APP_STORE_CONNECT_API_KEY_P8" | sed 's/\\n/\n/g' > /tmp/nexus-notary.p8`
+    - `xcrun notarytool store-credentials "nexus-notary" --key /tmp/nexus-notary.p8 --key-id "$APP_STORE_CONNECT_KEY_ID" --issuer "$APP_STORE_CONNECT_ISSUER_ID"`
+- `pnpm` deps installed (`pnpm install --config.node-linker=hoisted`).
+- Sparkle tools are fetched automatically via SwiftPM at `apps/macos/.build/artifacts/sparkle/Sparkle/bin/` (`sign_update`, `generate_appcast`, etc.).
+
+## Build & package
+Notes:
+- `APP_BUILD` maps to `CFBundleVersion`/`sparkle:version`; keep it numeric + monotonic (no `-beta`), or Sparkle compares it as equal.
+- Defaults to the current architecture (`$(uname -m)`). For release/universal builds, set `BUILD_ARCHS="arm64 x86_64"` (or `BUILD_ARCHS=all`).
+
+```bash
+# From repo root; set release IDs so Sparkle feed is enabled.
+# APP_BUILD must be numeric + monotonic for Sparkle compare.
+BUNDLE_ID=com.nexus.mac \
+APP_VERSION=0.1.0 \
+APP_BUILD="$(git rev-list --count HEAD)" \
+BUILD_CONFIG=release \
+SIGN_IDENTITY="Developer ID Application: Peter Steinberger (Y5PE65HELJ)" \
+scripts/package-mac-app.sh
+
+# Zip for distribution (includes resource forks for Sparkle delta support)
+ditto -c -k --sequesterRsrc --keepParent dist/Nexus.app dist/Nexus-0.1.0.zip
+
+# Optional: also build a styled DMG for humans (drag to /Applications)
+scripts/create-dmg.sh dist/Nexus.app dist/Nexus-0.1.0.dmg
+
+# Recommended: build + notarize/staple zip + DMG
+# First, create a keychain profile once:
+#   xcrun notarytool store-credentials "nexus-notary" \
+#     --apple-id "<apple-id>" --team-id "<team-id>" --password "<app-specific-password>"
+NOTARIZE=1 NOTARYTOOL_PROFILE=nexus-notary \
+BUNDLE_ID=com.nexus.mac \
+APP_VERSION=0.1.0 \
+APP_BUILD="$(git rev-list --count HEAD)" \
+BUILD_CONFIG=release \
+SIGN_IDENTITY="Developer ID Application: Peter Steinberger (Y5PE65HELJ)" \
+scripts/package-mac-dist.sh
+
+# Optional: ship dSYM alongside the release
+ditto -c -k --keepParent apps/macos/.build/release/Nexus.app.dSYM dist/Nexus-0.1.0.dSYM.zip
+```
+
+## Appcast entry
+Use the release note generator so Sparkle renders formatted HTML notes:
+```bash
+SPARKLE_PRIVATE_KEY_FILE=/Users/steipete/Library/CloudStorage/Dropbox/Backup/Sparkle/ed25519-private-key scripts/make_appcast.sh dist/Nexus-0.1.0.zip   https://raw.githubusercontent.com/nexus/nexus/main/appcast.xml
+```
+Generates HTML release notes from `CHANGELOG.md` (via `scripts/changelog-to-html.sh`) and embeds them in the appcast entry.
+Commit the updated `appcast.xml` alongside the release assets (zip + dSYM) when publishing.
+
+## Publish & verify
+- Upload `Nexus-0.1.0.zip` (and `Nexus-0.1.0.dSYM.zip`) to the GitHub release for tag `v0.1.0`.
+- Ensure the raw appcast URL matches the baked feed: `https://raw.githubusercontent.com/nexus/nexus/main/appcast.xml`.
+- Sanity checks:
+  - `curl -I https://raw.githubusercontent.com/nexus/nexus/main/appcast.xml` returns 200.
+  - `curl -I <enclosure url>` returns 200 after assets upload.
+  - On a previous public build, run “Check for Updates…” from the About tab and verify Sparkle installs the new build cleanly.
+
+Definition of done: signed app + appcast are published, update flow works from an older installed version, and release assets are attached to the GitHub release.

package/docs/mac/remote.md

@@ -0,0 +1,57 @@
+---
+summary: "macOS app flow for controlling a remote Nexus gateway over SSH"
+read_when:
+  - Setting up or debugging remote mac control
+---
+# Remote Nexus (macOS ⇄ remote host)
+
+Updated: 2025-12-08
+
+This flow lets the macOS app act as a full remote control for a Nexus gateway running on another host (e.g. a Mac Studio). All features—health checks, Voice Wake forwarding, and Web Chat—reuse the same remote SSH configuration from *Settings → General*.
+
+## Modes
+- **Local (this Mac)**: Everything runs on the laptop. No SSH involved.
+- **Remote over SSH**: Nexus commands are executed on the remote host. The mac app opens an SSH connection with `-o BatchMode` plus your chosen identity/key.
+
+## Prereqs on the remote host
+1) Install Node + pnpm and build/install the Nexus CLI (`pnpm install && pnpm build && pnpm link --global`).
+2) Ensure `nexus` is on PATH for non-interactive shells (symlink into `/usr/local/bin` or `/opt/homebrew/bin` if needed).
+3) Open SSH with key auth. We recommend **Tailscale** IPs for stable reachability off-LAN.
+
+## macOS app setup
+1) Open *Settings → General*.
+2) Under **Nexus runs**, pick **Remote over SSH** and set:
+   - **SSH target**: `user@host` (optional `:port`).
+     - If the gateway is on the same LAN and advertises Bonjour, pick it from the discovered list to auto-fill this field.
+   - **Identity file** (advanced): path to your key.
+   - **Project root** (advanced): remote checkout path used for commands.
+   - **CLI path** (advanced): optional path to a runnable `nexus` entrypoint/binary (auto-filled when advertised).
+3) Hit **Test remote**. Success indicates the remote `nexus status --json` runs correctly. Failures usually mean PATH/CLI issues; exit 127 means the CLI isn’t found remotely.
+4) Health checks and Web Chat will now run through this SSH tunnel automatically.
+
+## Web Chat over SSH
+- Web Chat connects to the gateway over the forwarded WebSocket control port (default 18789).
+- There is no separate WebChat HTTP server anymore.
+
+## Permissions
+- The remote host needs the same TCC approvals as local (Automation, Accessibility, Screen Recording, Microphone, Speech Recognition, Notifications). Run onboarding on that machine to grant them once.
+- Nodes advertise their permission state via `node.list` / `node.describe` so agents know what’s available.
+
+## WhatsApp login flow (remote)
+- Run `nexus login --verbose` **on the remote host**. Scan the QR with WhatsApp on your phone.
+- Re-run login on that host if auth expires. Health check will surface link problems.
+
+## Troubleshooting
+- **exit 127 / not found**: `nexus` isn’t on PATH for non-login shells. Add it to `/etc/paths`, your shell rc, or symlink into `/usr/local/bin`/`/opt/homebrew/bin`.
+- **Health probe failed**: check SSH reachability, PATH, and that Baileys is logged in (`nexus status --json`).
+- **Web Chat stuck**: confirm the gateway is running on the remote host and the forwarded port matches the gateway WS port; the UI requires a healthy WS connection.
+- **Voice Wake**: trigger phrases are forwarded automatically in remote mode; no separate forwarder is needed.
+
+## Notification sounds
+Pick sounds per notification from scripts with `nexus` and `node.invoke`, e.g.:
+
+```bash
+nexus nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass
+```
+
+There is no global “default sound” toggle in the app anymore; callers choose a sound (or none) per request.

package/docs/mac/signing.md

@@ -0,0 +1,41 @@
+---
+summary: "Signing steps for macOS debug builds generated by packaging scripts"
+read_when:
+  - Building or signing mac debug builds
+---
+# mac signing (debug builds)
+
+This app is usually built from `scripts/package-mac-app.sh`, which now:
+
+- sets a stable debug bundle identifier: `com.nexus.mac.debug`
+- writes the Info.plist with that bundle id (override via `BUNDLE_ID=...`)
+- calls `scripts/codesign-mac-app.sh` to sign the main binary, bundled CLI, and app bundle so macOS treats each rebuild as the same signed bundle and keeps TCC permissions (notifications, accessibility, screen recording, mic, speech). For stable permissions, use a real signing identity; ad-hoc is opt-in and fragile (see [`docs/mac/permissions.md`](https://docs.nexus.bot/mac/permissions)).
+- uses `CODESIGN_TIMESTAMP=auto` by default; it enables trusted timestamps for Developer ID signatures. Set `CODESIGN_TIMESTAMP=off` to skip timestamping (offline debug builds).
+- inject build metadata into Info.plist: `NexusBuildTimestamp` (UTC) and `NexusGitCommit` (short hash) so the About pane can show build, git, and debug/release channel.
+- **Packaging requires Bun**: The embedded gateway relay is compiled using `bun`. Ensure it is installed (`curl -fsSL https://bun.sh/install | bash`).
+- reads `SIGN_IDENTITY` from the environment. Add `export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)"` (or your Developer ID Application cert) to your shell rc to always sign with your cert. Ad-hoc signing requires explicit opt-in via `ALLOW_ADHOC_SIGNING=1` or `SIGN_IDENTITY="-"` (not recommended for permission testing).
+
+## Usage
+
+```bash
+# from repo root
+scripts/package-mac-app.sh               # auto-selects identity; errors if none found
+SIGN_IDENTITY="Developer ID Application: Your Name" scripts/package-mac-app.sh   # real cert
+ALLOW_ADHOC_SIGNING=1 scripts/package-mac-app.sh    # ad-hoc (permissions will not stick)
+SIGN_IDENTITY="-" scripts/package-mac-app.sh        # explicit ad-hoc (same caveat)
+```
+
+### Ad-hoc Signing Note
+When signing with `SIGN_IDENTITY="-"` (ad-hoc), the script automatically disables the **Hardened Runtime** (`--options runtime`). This is necessary to prevent crashes when the app attempts to load embedded frameworks (like Sparkle) that do not share the same Team ID. Ad-hoc signatures also break TCC permission persistence; see [`docs/mac/permissions.md`](https://docs.nexus.bot/mac/permissions) for recovery steps.
+
+## Build metadata for About
+
+`package-mac-app.sh` stamps the bundle with:
+- `NexusBuildTimestamp`: ISO8601 UTC at package time
+- `NexusGitCommit`: short git hash (or `unknown` if unavailable)
+
+The About tab reads these keys to show version, build date, git commit, and whether it’s a debug build (via `#if DEBUG`). Run the packager to refresh these values after code changes.
+
+## Why
+
+TCC permissions are tied to the bundle identifier *and* code signature. Unsigned debug builds with changing UUIDs were causing macOS to forget grants after each rebuild. Signing the binaries (ad‑hoc by default) and keeping a fixed bundle id/path (`dist/Nexus.app`) preserves the grants between builds, matching the VibeTunnel approach.