nodmix 2026.5.25

package/docs/platforms/mac/dev-setup.md

@@ -0,0 +1,112 @@
+---
+summary: "Setup guide for developers working on the Nodmix macOS app"
+read_when:
+  - Setting up the macOS development environment
+title: "macOS dev setup"
+---
+
+# macOS developer setup
+
+Build and run the Nodmix 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 24 & pnpm**: Recommended for the gateway, CLI, and packaging scripts. Node 22 LTS, currently `22.19+`, remains supported for compatibility.
+
+## 1. Install Dependencies
+
+Install the project-wide dependencies:
+
+```bash
+pnpm install
+```
+
+## 2. Build and Package the App
+
+To build the macOS app and package it into `dist/Nodmix.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** (`-`).
+
+For dev run modes, signing flags, and Team ID troubleshooting, see the macOS app README:
+[https://github.com/nodmix/nodmix/blob/main/apps/macos/README.md](https://github.com/nodmix/nodmix/blob/main/apps/macos/README.md)
+
+> **Note**: Ad-hoc signed apps may trigger security prompts. If the app crashes immediately with "Abort trap 6", see the [Troubleshooting](#troubleshooting) section.
+
+## 3. Install the CLI
+
+The macOS app expects a global `nodmix` CLI install to manage background tasks.
+
+**To install it (recommended):**
+
+1. Open the Nodmix app.
+2. Go to the **General** settings tab.
+3. Click **"Install CLI"**.
+
+Alternatively, install it manually:
+
+```bash
+npm install -g nodmix@<version>
+```
+
+`pnpm add -g nodmix@<version>` and `bun add -g nodmix@<version>` also work.
+For the Gateway runtime, Node remains the recommended path.
+
+## Troubleshooting
+
+### Build fails: toolchain or SDK mismatch
+
+The macOS app build expects the latest macOS SDK and Swift 6.2 toolchain.
+
+**System dependencies (required):**
+
+- **Latest macOS version available in Software Update** (required by Xcode 26.2 SDKs)
+- **Xcode 26.2** (Swift 6.2 toolchain)
+
+**Checks:**
+
+```bash
+xcodebuild -version
+xcrun swift --version
+```
+
+If versions don't match, update macOS/Xcode and re-run the build.
+
+### 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 ai.nodmix.mac.debug
+   ```
+
+2. If that fails, change the `BUNDLE_ID` temporarily in [`scripts/package-mac-app.sh`](https://github.com/nodmix/nodmix/blob/main/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
+nodmix gateway status
+nodmix gateway stop
+
+# If you're not using a LaunchAgent (dev mode / manual runs), find the listener:
+lsof -nP -iTCP:18789 -sTCP:LISTEN
+```
+
+If a manual run is holding the port, stop that process (Ctrl+C). As a last resort, kill the PID you found above.
+
+## Related
+
+- [macOS app](/platforms/macos)
+- [Install overview](/install)

package/docs/platforms/mac/health.md

@@ -0,0 +1,39 @@
+---
+summary: "How the macOS app reports gateway/Baileys health states"
+read_when:
+  - Debugging mac app health indicators
+title: "Health checks (macOS)"
+---
+
+# Health Checks on macOS
+
+How to see whether the linked channel 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 "linked · auth 12m" 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.
+- **Channels tab** surfaces channel status + controls for WhatsApp/Telegram (login QR, logout, probe, last disconnect/error).
+
+## How the probe works
+
+- App runs `nodmix health --json` via `ShellExecutor` every ~60s and on demand. The probe loads creds 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 [Gateway health](/gateway/health) (`nodmix status`, `nodmix status --deep`, `nodmix health --json`) and tail `/tmp/nodmix/nodmix-*.log` for `web-heartbeat` / `web-reconnect`.
+
+## Related
+
+- [Gateway health](/gateway/health)
+- [macOS app](/platforms/macos)

package/docs/platforms/mac/icon.md

@@ -0,0 +1,36 @@
+---
+summary: "Menu bar icon states and animations for Nodmix on macOS"
+read_when:
+  - Changing menu bar icon behavior
+title: "Menu bar icon"
+---
+
+# 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.
+
+## Related
+
+- [Menu bar](/platforms/mac/menu-bar)
+- [macOS app](/platforms/macos)

package/docs/platforms/mac/logging.md

@@ -0,0 +1,62 @@
+---
+summary: "Nodmix 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
+title: "macOS logging"
+---
+
+# Logging (macOS)
+
+## Rolling diagnostics file log (Debug pane)
+
+Nodmix 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/Nodmix/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 Nodmix (`ai.nodmix`)
+
+- Write the plist to a temp file first, then install it atomically as root:
+
+```bash
+cat <<'EOF' >/tmp/ai.nodmix.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/ai.nodmix.plist /Library/Preferences/Logging/Subsystems/ai.nodmix.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/ai.nodmix.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.
+
+## Related
+
+- [macOS app](/platforms/macos)
+- [Gateway logging](/gateway/logging)

package/docs/platforms/mac/menu-bar.md

@@ -0,0 +1,93 @@
+---
+summary: "Menu bar status logic and what is surfaced to users"
+read_when:
+  - Tweaking mac menu UI or status logic
+title: "Menu bar"
+---
+
+## 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.
+- A root "Context" submenu contains recent sessions instead of expanding them directly in the root menu.
+- The "Nodes" block in the root menu lists **devices** only (paired nodes via `node.list`), not client/presence entries.
+- A root "Usage" section appears below Context when provider usage snapshots are available, followed by usage-cost details when available.
+
+## 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
+
+- `exec` → 💻
+- `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.
+
+## Context submenu
+
+- The root menu shows one "Context" row with a session count/status and opens a submenu.
+- The Context submenu header shows the active session count for the last 24 hours.
+- Each session row keeps its token bar, age, preview, thinking/verbose, reset, compact, and delete actions.
+- Loading, disconnected, and session-load error messages appear inside the Context submenu.
+- Provider usage and usage-cost details stay root-level below Context so they remain glanceable without opening the submenu.
+
+## Status row text (menu)
+
+- While work is active: `<Session role> · <activity label>`
+  - Examples: `Main · exec: pnpm test`, `Other · read: apps/macos/Sources/Nodmix/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:
+  - `exec`: 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.
+
+## Related
+
+- [macOS app](/platforms/macos)
+- [Menu bar icon](/platforms/mac/icon)

package/docs/platforms/mac/peekaboo.md

@@ -0,0 +1,92 @@
+---
+summary: "PeekabooBridge integration for macOS UI automation"
+read_when:
+  - Hosting PeekabooBridge in Nodmix.app
+  - Integrating Peekaboo via Swift Package Manager
+  - Changing PeekabooBridge protocol/paths
+  - Deciding between PeekabooBridge, Codex Computer Use, and cua-driver MCP
+title: "Peekaboo bridge"
+---
+
+Nodmix can host **PeekabooBridge** as a local, permission-aware UI automation
+broker. This lets the `peekaboo` CLI drive UI automation while reusing the
+macOS app's TCC permissions.
+
+## What this is (and is not)
+
+- **Host**: Nodmix.app can act as a PeekabooBridge host.
+- **Client**: use the `peekaboo` CLI (no separate `nodmix ui ...` surface).
+- **UI**: visual overlays stay in Peekaboo.app; Nodmix is a thin broker host.
+
+## Relationship to Computer Use
+
+Nodmix has three desktop-control paths, and they intentionally stay separate:
+
+- **PeekabooBridge host**: Nodmix.app can host the local PeekabooBridge socket.
+  The `peekaboo` CLI remains the client and uses Nodmix.app's macOS
+  permissions for Peekaboo automation primitives such as screenshots, clicks,
+  menus, dialogs, Dock actions, and window management.
+- **Codex Computer Use**: the bundled `codex` plugin prepares Codex app-server,
+  verifies that Codex's `computer-use` MCP server is available, and then lets
+  Codex own native desktop-control tool calls during Codex-mode turns. Nodmix
+  does not proxy those actions through PeekabooBridge.
+- **Direct `cua-driver` MCP**: Nodmix can register TryCua's upstream
+  `cua-driver mcp` server as a normal MCP server. That gives agents the CUA
+  driver's own schemas and pid/window/element-index workflow without routing
+  through the Codex marketplace or the PeekabooBridge socket.
+
+Use Peekaboo when you want the broad macOS automation surface and Nodmix.app's
+permission-aware bridge host. Use Codex Computer Use when a Codex-mode agent
+should rely on Codex's native computer-use plugin. Use direct `cua-driver mcp`
+when you want the CUA driver exposed to any Nodmix-managed runtime as a normal
+MCP server.
+
+## Enable the bridge
+
+In the macOS app:
+
+- Settings → **Enable Peekaboo Bridge**
+
+When enabled, Nodmix starts a local UNIX socket server. If disabled, the host
+is stopped and `peekaboo` will fall back to other available hosts.
+
+## Client discovery order
+
+Peekaboo clients typically try hosts in this order:
+
+1. Peekaboo.app (full UX)
+2. Claude.app (if installed)
+3. Nodmix.app (thin broker)
+
+Use `peekaboo bridge status --verbose` to see which host is active and which
+socket path is in use. You can override with:
+
+```bash
+export PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock
+```
+
+## Security and permissions
+
+- The bridge validates **caller code signatures**; an allowlist of TeamIDs is
+  enforced (Peekaboo host TeamID + Nodmix app TeamID).
+- Requests time out after ~10 seconds.
+- If required permissions are missing, the bridge returns a clear error message
+  rather than launching System Settings.
+
+## Snapshot behavior (automation)
+
+Snapshots are stored in memory and expire automatically after a short window.
+If you need longer retention, re-capture from the client.
+
+## Troubleshooting
+
+- If `peekaboo` reports "bridge client is not authorized", ensure the client is
+  properly signed or run the host with `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1`
+  in **debug** mode only.
+- If no hosts are found, open one of the host apps (Peekaboo.app or Nodmix.app)
+  and confirm permissions are granted.
+
+## Related
+
+- [macOS app](/platforms/macos)
+- [macOS permissions](/platforms/mac/permissions)

package/docs/platforms/mac/permissions.md

@@ -0,0 +1,53 @@
+---
+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
+title: "macOS permissions"
+---
+
+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 Nodmix, `dist/Nodmix.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 ai.nodmix.mac
+sudo tccutil reset ScreenCapture ai.nodmix.mac
+sudo tccutil reset AppleEvents
+```
+
+## Files and folders permissions (Desktop/Documents/Downloads)
+
+macOS may also gate Desktop, Documents, and Downloads for terminal/background processes. If file reads or directory listings hang, grant access to the same process context that performs file operations (for example Terminal/iTerm, LaunchAgent-launched app, or SSH process).
+
+Workaround: move files into the Nodmix workspace (`~/.nodmix/workspace`) if you want to avoid per-folder grants.
+
+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.
+
+## Related
+
+- [macOS app](/platforms/macos)
+- [macOS signing](/platforms/mac/signing)

package/docs/platforms/mac/remote.md

@@ -0,0 +1,123 @@
+---
+summary: "macOS app flow for controlling a remote Nodmix gateway"
+read_when:
+  - Setting up or debugging remote mac control
+title: "Remote control"
+---
+
+This flow lets the macOS app act as a full remote control for an Nodmix gateway running on another host (desktop/server). The app can connect directly to trusted LAN/Tailnet gateway URLs or manage an SSH tunnel when the remote gateway is loopback-only. Health checks, Voice Wake forwarding, and Web Chat reuse the same remote configuration from _Settings → General_.
+
+## Modes
+
+- **Local (this Mac)**: Everything runs on the laptop. No SSH involved.
+- **Remote over SSH (default)**: Nodmix commands are executed on the remote host. The mac app opens an SSH connection with `-o BatchMode` plus your chosen identity/key and a local port-forward.
+- **Remote direct (ws/wss)**: No SSH tunnel. The mac app connects to the gateway URL directly (for example, via LAN, Tailscale, Tailscale Serve, or a public HTTPS reverse proxy).
+
+## Remote transports
+
+Remote mode supports two transports:
+
+- **SSH tunnel** (default): Uses `ssh -N -L ...` to forward the gateway port to localhost. The gateway will see the node's IP as `127.0.0.1` because the tunnel is loopback.
+- **Direct (ws/wss)**: Connects straight to the gateway URL. The gateway sees the real client IP.
+
+In SSH tunnel mode, discovered LAN/tailnet hostnames are saved as
+`gateway.remote.sshTarget`. The app keeps `gateway.remote.url` on the local
+tunnel endpoint, for example `ws://127.0.0.1:18789`, so CLI, Web Chat, and
+the local node-host service all use the same safe loopback transport.
+If the local tunnel port differs from the remote gateway port, set
+`gateway.remote.remotePort` to the port on the remote host.
+
+Browser automation in remote mode is owned by the CLI node host, not by the
+native macOS app node. The app starts the installed node host service when
+possible; if you need browser control from that Mac, install/start it with
+`nodmix node install ...` and `nodmix node start` (or run
+`nodmix node run ...` in the foreground), then target that browser-capable
+node.
+
+## Prereqs on the remote host
+
+1. Install Node + pnpm and build/install the Nodmix CLI (`pnpm install && pnpm build && pnpm link --global`).
+2. Ensure `nodmix` is on PATH for non-interactive shells (symlink into `/usr/local/bin` or `/opt/homebrew/bin` if needed).
+3. For SSH transport only: open SSH with key auth. We recommend **Tailscale** IPs for stable reachability off-LAN.
+
+## macOS app setup
+
+To preconfigure the app without the welcome flow:
+
+```bash
+nodmix-mac configure-remote \
+  --ssh-target user@gateway.local \
+  --local-port 18789 \
+  --remote-port 18789 \
+  --token "$NODMIX_GATEWAY_TOKEN"
+```
+
+For a gateway already reachable on a trusted LAN or Tailnet, skip SSH entirely:
+
+```bash
+nodmix-mac configure-remote \
+  --direct-url ws://192.168.0.202:18789 \
+  --token "$NODMIX_GATEWAY_TOKEN"
+```
+
+This writes the remote config, marks onboarding complete, and lets the app own
+the selected transport when it starts.
+
+1. Open _Settings → General_.
+2. Under **Nodmix runs**, pick **Remote** and set:
+   - **Transport**: **SSH tunnel** or **Direct (ws/wss)**.
+   - **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.
+   - **Gateway URL** (Direct only): `wss://gateway.example.ts.net` (or `ws://...` for local/LAN).
+   - **Identity file** (advanced): path to your key.
+   - **Project root** (advanced): remote checkout path used for commands.
+   - **CLI path** (advanced): optional path to a runnable `nodmix` entrypoint/binary (auto-filled when advertised).
+3. Hit **Test remote**. Success indicates the remote `nodmix 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 the selected transport automatically.
+
+## Web Chat
+
+- **SSH tunnel**: Web Chat connects to the gateway over the forwarded WebSocket control port (default 18789).
+- **Direct (ws/wss)**: Web Chat connects straight to the configured gateway URL.
+- 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.
+
+## Security notes
+
+- Prefer loopback binds on the remote host and connect via SSH, Tailscale Serve, or a trusted Tailnet/LAN direct URL.
+- SSH tunneling uses strict host-key checking; trust the host key first so it exists in `~/.ssh/known_hosts`.
+- If you bind the Gateway to a non-loopback interface, require valid Gateway auth: token, password, or an identity-aware reverse proxy with `gateway.auth.mode: "trusted-proxy"`.
+- See [Security](/gateway/security) and [Tailscale](/gateway/tailscale).
+
+## WhatsApp login flow (remote)
+
+- Run `nodmix channels 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**: `nodmix` 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 (`nodmix 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.
+- **Node IP shows 127.0.0.1**: expected with the SSH tunnel. Switch **Transport** to **Direct (ws/wss)** if you want the gateway to see the real client IP.
+- **Dashboard works but Mac capabilities are offline**: this means the app's operator/control connection is healthy, but the companion node connection is not connected or is missing its command surface. Open the menu bar device section and check whether the Mac is `paired · disconnected`. For `wss://*.ts.net` Tailscale Serve endpoints, the app detects stale legacy TLS leaf pins after certificate rotation, clears the stale pin when macOS trusts the new certificate, and retries automatically. If the certificate is not system-trusted or the host is not a Tailscale Serve name, set `gateway.remote.tlsFingerprint` to the expected certificate fingerprint, review the certificate, or switch to **Remote over SSH**.
+- **Voice Wake**: trigger phrases are forwarded automatically in remote mode; no separate forwarder is needed.
+
+## Notification sounds
+
+Pick sounds per notification from scripts with `nodmix` and `node.invoke`, e.g.:
+
+```bash
+nodmix 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.
+
+## Related
+
+- [macOS app](/platforms/macos)
+- [Remote access](/gateway/remote)

package/docs/platforms/mac/signing.md

@@ -0,0 +1,52 @@
+---
+summary: "Signing steps for macOS debug builds generated by packaging scripts"
+read_when:
+  - Building or signing mac debug builds
+title: "macOS signing"
+---
+
+# mac signing (debug builds)
+
+This app is usually built from [`scripts/package-mac-app.sh`](https://github.com/nodmix/nodmix/blob/main/scripts/package-mac-app.sh), which now:
+
+- sets a stable debug bundle identifier: `ai.nodmix.mac.debug`
+- writes the Info.plist with that bundle id (override via `BUNDLE_ID=...`)
+- calls [`scripts/codesign-mac-app.sh`](https://github.com/nodmix/nodmix/blob/main/scripts/codesign-mac-app.sh) to sign the main binary 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 [macOS permissions](/platforms/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: `NodmixBuildTimestamp` (UTC) and `NodmixGitCommit` (short hash) so the About pane can show build, git, and debug/release channel.
+- **Packaging defaults to Node 24**: the script runs TS builds and the Control UI build. Node 22 LTS, currently `22.19+`, remains supported for compatibility.
+- 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).
+- runs a Team ID audit after signing and fails if any Mach-O inside the app bundle is signed by a different Team ID. Set `SKIP_TEAM_ID_CHECK=1` to bypass.
+
+## 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)
+DISABLE_LIBRARY_VALIDATION=1 scripts/package-mac-app.sh   # dev-only Sparkle Team ID mismatch workaround
+```
+
+### 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 [macOS permissions](/platforms/mac/permissions) for recovery steps.
+
+## Build metadata for About
+
+`package-mac-app.sh` stamps the bundle with:
+
+- `NodmixBuildTimestamp`: ISO8601 UTC at package time
+- `NodmixGitCommit`: 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/Nodmix.app`) preserves the grants between builds, matching the VibeTunnel approach.
+
+## Related
+
+- [macOS app](/platforms/macos)
+- [macOS permissions](/platforms/mac/permissions)