@intent-systems/nexus 2026.1.5-3

package/docs/mac/skills.md

@@ -0,0 +1,27 @@
+---
+summary: "macOS Skills settings UI and gateway-backed status"
+read_when:
+  - Updating the macOS Skills settings UI
+  - Changing skills gating or install behavior
+---
+# Skills (macOS)
+
+The macOS app surfaces Nexus skills via the gateway; it does not parse skills locally.
+
+## Data source
+- `skills.status` (gateway) returns all skills plus eligibility and missing requirements
+  (including allowlist blocks for bundled skills).
+- Requirements are derived from `metadata.nexus.requires` in each `SKILL.md`.
+
+## Install actions
+- `metadata.nexus.install` defines install options (brew/node/go/uv).
+- The app calls `skills.install` to run installers on the gateway host.
+- The gateway surfaces only one preferred installer when multiple are provided
+  (brew when available, otherwise node manager from `skills.install`, default npm).
+
+## Env/API keys
+- The app stores keys in `~/nexus/state/nexus.json` under `skills.entries.<skillKey>`.
+- `skills.update` patches `enabled`, `apiKey`, and `env`.
+
+## Remote mode
+- Install + config updates happen on the gateway host (not the local Mac).

package/docs/mac/voice-overlay.md

@@ -0,0 +1,52 @@
+---
+summary: "Voice overlay lifecycle when wake-word and push-to-talk overlap"
+read_when:
+  - Adjusting voice overlay behavior
+---
+## Voice Overlay Lifecycle (macOS)
+
+Audience: macOS app contributors. Goal: keep the voice overlay predictable when wake-word and push-to-talk overlap.
+
+### Current intent
+- If the overlay is already visible from wake-word and the user presses the hotkey, the hotkey session *adopts* the existing text instead of resetting it. The overlay stays up while the hotkey is held. When the user releases: send if there is trimmed text, otherwise dismiss.
+- Wake-word alone still auto-sends on silence; push-to-talk sends immediately on release.
+
+### Implemented (Dec 9, 2025)
+- Overlay sessions now carry a token per capture (wake-word or push-to-talk). Partial/final/send/dismiss/level updates are dropped when the token doesn’t match, avoiding stale callbacks.
+- Push-to-talk adopts any visible overlay text as a prefix (so pressing the hotkey while the wake overlay is up keeps the text and appends new speech). It waits up to 1.5s for a final transcript before falling back to the current text.
+- Chime/overlay logging is emitted at `info` in categories `voicewake.overlay`, `voicewake.ptt`, and `voicewake.chime` (session start, partial, final, send, dismiss, chime reason).
+
+### Next steps
+1. **VoiceSessionCoordinator (actor)**
+   - Owns exactly one `VoiceSession` at a time.
+   - API (token-based): `beginWakeCapture`, `beginPushToTalk`, `updatePartial`, `endCapture`, `cancel`, `applyCooldown`.
+   - Drops callbacks that carry stale tokens (prevents old recognizers from reopening the overlay).
+2. **VoiceSession (model)**
+   - Fields: `token`, `source` (wakeWord|pushToTalk), committed/volatile text, chime flags, timers (auto-send, idle), `overlayMode` (display|editing|sending), cooldown deadline.
+3. **Overlay binding**
+   - `VoiceSessionPublisher` (`ObservableObject`) mirrors the active session into SwiftUI.
+   - `VoiceWakeOverlayView` renders only via the publisher; it never mutates global singletons directly.
+   - Overlay user actions (`sendNow`, `dismiss`, `edit`) call back into the coordinator with the session token.
+4. **Unified send path**
+   - On `endCapture`: if trimmed text is empty → dismiss; else `performSend(session:)` (plays send chime once, forwards, dismisses).
+   - Push-to-talk: no delay; wake-word: optional delay for auto-send.
+   - Apply a short cooldown to the wake runtime after push-to-talk finishes so wake-word doesn’t immediately retrigger.
+5. **Logging**
+   - Coordinator emits `.info` logs in subsystem `com.nexus`, categories `voicewake.overlay` and `voicewake.chime`.
+   - Key events: `session_started`, `adopted_by_push_to_talk`, `partial`, `finalized`, `send`, `dismiss`, `cancel`, `cooldown`.
+
+### Debugging checklist
+- Stream logs while reproducing a sticky overlay:
+
+  ```bash
+  sudo log stream --predicate 'subsystem == "com.nexus" AND category CONTAINS "voicewake"' --level info --style compact
+  ```
+- Verify only one active session token; stale callbacks should be dropped by the coordinator.
+- Ensure push-to-talk release always calls `endCapture` with the active token; if text is empty, expect `dismiss` without chime or send.
+
+### Migration steps (suggested)
+1. Add `VoiceSessionCoordinator`, `VoiceSession`, and `VoiceSessionPublisher`.
+2. Refactor `VoiceWakeRuntime` to create/update/end sessions instead of touching `VoiceWakeOverlayController` directly.
+3. Refactor `VoicePushToTalk` to adopt existing sessions and call `endCapture` on release; apply runtime cooldown.
+4. Wire `VoiceWakeOverlayController` to the publisher; remove direct calls from runtime/PTT.
+5. Add integration tests for session adoption, cooldown, and empty-text dismissal.

package/docs/mac/voicewake.md

@@ -0,0 +1,56 @@
+---
+summary: "Voice wake and push-to-talk modes plus routing details in the mac app"
+read_when:
+  - Working on voice wake or PTT pathways
+---
+# Voice Wake & Push-to-Talk
+
+Updated: 2025-12-23 · Owners: mac app
+
+## Modes
+- **Wake-word mode** (default): always-on Speech recognizer waits for trigger tokens (`swabbleTriggerWords`). On match it starts capture, shows the overlay with partial text, and auto-sends after silence.
+- **Push-to-talk (Right Option hold)**: hold the right Option key to capture immediately—no trigger needed. The overlay appears while held; releasing finalizes and forwards after a short delay so you can tweak text.
+
+## Runtime behavior (wake-word)
+- Speech recognizer lives in `VoiceWakeRuntime`.
+- Trigger only fires when there’s a **meaningful pause** between the wake word and the next word (~0.45s gap).
+- Silence windows: 2.0s when speech is flowing, 5.0s if only the trigger was heard.
+- Hard stop: 120s to prevent runaway sessions.
+- Debounce between sessions: 350ms.
+- Overlay is driven via `VoiceWakeOverlayController` with committed/volatile coloring.
+- After send, recognizer restarts cleanly to listen for the next trigger.
+
+## Lifecycle invariants
+- If Voice Wake is enabled and permissions are granted, the wake-word recognizer should be listening (except during an explicit push-to-talk capture).
+- Overlay visibility (including manual dismiss via the X button) must never prevent the recognizer from resuming.
+
+## Sticky overlay failure mode (previous)
+Previously, if the overlay got stuck visible and you manually closed it, Voice Wake could appear “dead” because the runtime’s restart attempt could be blocked by overlay visibility and no subsequent restart was scheduled.
+
+Hardening:
+- Wake runtime restart is no longer blocked by overlay visibility.
+- Overlay dismiss completion triggers a `VoiceWakeRuntime.refresh(...)` via `VoiceSessionCoordinator`, so manual X-dismiss always resumes listening.
+
+## Push-to-talk specifics
+- Hotkey detection uses a global `.flagsChanged` monitor for **right Option** (`keyCode 61` + `.option`). We only observe events (no swallowing).
+- Capture pipeline lives in `VoicePushToTalk`: starts Speech immediately, streams partials to the overlay, and calls `VoiceWakeForwarder` on release.
+- When push-to-talk starts we pause the wake-word runtime to avoid dueling audio taps; it restarts automatically after release.
+- Permissions: requires Microphone + Speech; seeing events needs Accessibility/Input Monitoring approval.
+- External keyboards: some may not expose right Option as expected—offer a fallback shortcut if users report misses.
+
+## User-facing settings
+- **Voice Wake** toggle: enables wake-word runtime.
+- **Hold Cmd+Fn to talk**: enables the push-to-talk monitor. Disabled on macOS < 26.
+- Language & mic pickers, live level meter, trigger-word table, tester.
+- **Sounds**: chimes on trigger detect and on send; defaults to the macOS “Glass” system sound. You can pick any `NSSound`-loadable file (e.g. MP3/WAV/AIFF) for each event or choose **No Sound**.
+
+## Forwarding behavior
+- When Voice Wake is enabled, transcripts are forwarded to the active gateway/agent (the same local vs remote mode used by the rest of the mac app).
+- Replies are delivered to the **last-used main provider** (WhatsApp/Telegram/Discord/WebChat). If delivery fails, the error is logged and the run is still visible via WebChat/session logs.
+
+## Forwarding payload
+- `VoiceWakeForwarder.prefixedTranscript(_:)` prepends the machine hint before sending. Shared between wake-word and push-to-talk paths.
+
+## Quick verification
+- Toggle push-to-talk on, hold Cmd+Fn, speak, release: overlay should show partials then send.
+- While holding, menu-bar ears should stay enlarged (uses `triggerVoiceEars(ttl:nil)`); they drop after release.

package/docs/mac/webchat.md

@@ -0,0 +1,27 @@
+---
+summary: "How the mac app embeds the gateway WebChat and how to debug it"
+read_when:
+  - Debugging mac WebChat view or loopback port
+---
+# Web Chat (macOS app)
+
+The macOS menu bar app shows the WebChat UI as a native SwiftUI view and reuses the **primary Nexus session** (`main`, or `global` when scope is global).
+
+- **Local mode**: connects directly to the local Gateway WebSocket.
+- **Remote mode**: forwards the Gateway WebSocket control port over SSH and uses that as the data plane.
+
+## Launch & debugging
+- Manual: Lobster menu → “Open Chat”.
+- Auto-open for testing: run `dist/Nexus.app/Contents/MacOS/Nexus --webchat` (or pass `--webchat` to the binary launched by launchd). The window opens on startup.
+- Logs: see `./scripts/clawlog.sh` (subsystem `com.nexus`, category `WebChatSwiftUI`).
+
+## How it’s wired
+- Implementation: `apps/macos/Sources/Nexus/WebChatSwiftUI.swift` hosts `NexusChatUI` and speaks to the Gateway over `GatewayConnection`.
+- Data plane: Gateway WebSocket methods `chat.history`, `chat.send`, `chat.abort`; events `chat`, `agent`, `presence`, `tick`, `health`.
+- Session: usually primary (`main`); multiple transports (WhatsApp/Telegram/Discord/Desktop) share the same key. The onboarding flow uses a dedicated `onboarding` session to keep first-run setup separate.
+
+## Security / surface area
+- Remote mode forwards only the Gateway WebSocket control port over SSH.
+
+## Known limitations
+- The UI is optimized for the primary session and typical “chat” usage (not a full browser-based sandbox surface).

package/docs/mac/xpc.md

@@ -0,0 +1,40 @@
+---
+summary: "macOS IPC architecture for Nexus app, gateway node bridge, and PeekabooBridge"
+read_when:
+  - Editing IPC contracts or menu bar app IPC
+---
+# Nexus macOS IPC architecture (Dec 2025)
+
+**Current model:** there is **no local control socket** and no `nexus-mac` CLI. All agent actions go through the Gateway WebSocket and `node.invoke`. UI automation still uses PeekabooBridge.
+
+## Goals
+- Single GUI app instance that owns all TCC-facing work (notifications, screen recording, mic, speech, AppleScript).
+- A small surface for automation: Gateway + node commands, plus PeekabooBridge for UI automation.
+- Predictable permissions: always the same signed bundle ID, launched by launchd, so TCC grants stick.
+
+## How it works
+### Gateway + node bridge (current)
+- The app runs the Gateway (local mode) and connects to it as a node.
+- Agent actions are performed via `node.invoke` (e.g. `system.run`, `system.notify`, `canvas.*`).
+
+### PeekabooBridge (UI automation)
+- UI automation uses a separate UNIX socket named `bridge.sock` and the PeekabooBridge JSON protocol.
+- Host preference order (client-side): Peekaboo.app → Claude.app → Nexus.app → local execution.
+- Security: bridge hosts require TeamID `Y5PE65HELJ`; DEBUG-only same-UID escape hatch is guarded by `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` (Peekaboo convention).
+- See: [`docs/mac/peekaboo.md`](https://docs.nexus.bot/mac/peekaboo) for the Nexus plan and naming.
+
+### Mach/XPC (future direction)
+- Still optional for internal app services, but **not required** for automation now that node.invoke is the surface.
+
+## Operational flows
+- Restart/rebuild: `SIGN_IDENTITY="Apple Development: Peter Steinberger (2ZAC4GM7GD)" scripts/restart-mac.sh`
+  - Kills existing instances
+  - Swift build + package
+  - Writes/bootstraps/kickstarts the LaunchAgent
+- Single instance: app exits early if another instance with the same bundle ID is running.
+
+## Hardening notes
+- Prefer requiring a TeamID match for all privileged surfaces.
+- PeekabooBridge: `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` (DEBUG-only) may allow same-UID callers for local development.
+- All communication remains local-only; no network sockets are exposed.
+- TCC prompts originate only from the GUI app bundle; run `scripts/package-mac-app.sh` so the signed bundle ID stays stable.

package/docs/macos.md

@@ -0,0 +1,104 @@
+---
+summary: "Spec for the Nexus macOS companion menu bar app (gateway + node broker)"
+read_when:
+  - Implementing macOS app features
+  - Changing gateway lifecycle or node bridging on macOS
+---
+# Nexus macOS Companion (menu bar + gateway broker)
+
+Author: steipete · Status: draft spec · Date: 2025-12-20
+
+## Purpose
+- Single macOS menu-bar app named **Nexus** that:
+  - Shows native notifications for Nexus/nexus events.
+  - Owns TCC prompts (Notifications, Accessibility, Screen Recording, Automation/AppleScript, Microphone, Speech Recognition).
+  - Runs (or connects to) the **Gateway** and exposes itself as a **node** so agents can reach macOS‑only features.
+  - Hosts **PeekabooBridge** for UI automation (consumed by `peekaboo`; see [`docs/mac/peekaboo.md`](https://docs.nexus.bot/mac/peekaboo)).
+  - Installs a single CLI (`nexus`) by symlinking the bundled binary.
+
+## High-level design
+- SwiftPM package in `apps/macos/` (macOS 15+, Swift 6).
+- Targets:
+  - `NexusIPC` (shared Codable types + helpers for app‑internal actions).
+  - `Nexus` (LSUIElement MenuBarExtra app; hosts Gateway + node bridge + PeekabooBridgeHost).
+- Bundle ID: `com.nexus.mac`.
+- Bundled runtime binaries live under `Contents/Resources/Relay/`:
+  - `nexus` (bun‑compiled relay: CLI + gateway-daemon)
+- The app symlinks `nexus` into `/usr/local/bin` and `/opt/homebrew/bin`.
+
+## Gateway + node bridge
+- The mac app runs the Gateway in **local** mode (unless configured remote).
+- The gateway port is configurable via `gateway.port` or `NEXUS_GATEWAY_PORT` (default 18789). The mac app reads that value for launchd, probes, and remote SSH tunnels.
+- The mac app connects to the bridge as a **node** and advertises capabilities/commands.
+- Agent‑facing actions are exposed via `node.invoke` (no local control socket).
+- The mac app watches `~/nexus/state/nexus.json` and switches modes live when `gateway.mode` or `gateway.remote.url` changes.
+- If `gateway.mode` is unset but `gateway.remote.url` is set, the mac app treats it as remote mode.
+- Changing connection mode in the mac app writes `gateway.mode` (and `gateway.remote.url` in remote mode) back to the config file.
+
+### Node commands (mac)
+- Canvas: `canvas.present|navigate|eval|snapshot|a2ui.*`
+- Camera: `camera.snap|camera.clip`
+- Screen: `screen.record`
+- System: `system.run` (shell) and `system.notify`
+
+### Permission advertising
+- Nodes include a `permissions` map in hello/pairing.
+- The Gateway surfaces it via `node.list` / `node.describe` so agents can decide what to run.
+
+## CLI (`nexus`)
+- The **only** CLI is `nexus` (TS/bun). There is no `nexus-mac` helper.
+- For mac‑specific actions, the CLI uses `node.invoke`:
+  - `nexus canvas present|navigate|eval|snapshot|a2ui push|a2ui reset`
+  - `nexus nodes run --node <id> -- <command...>`
+  - `nexus nodes notify --node <id> --title ...`
+
+## Onboarding
+- Install CLI (symlink) → Permissions checklist → Test notification → Done.
+- Remote mode skips local gateway/CLI steps.
+- Selecting Local auto-enables the bundled Gateway via launchd (unless “Attach only” debug mode is enabled).
+
+## Deep links (URL scheme)
+
+Nexus (the macOS app) registers a URL scheme for triggering local actions from anywhere (browser, Shortcuts, CLI, etc.).
+
+Scheme:
+- `nexus://…`
+
+### `nexus://agent`
+
+Triggers a Gateway `agent` request (same machinery as WebChat/agent runs).
+
+Example:
+
+```bash
+open 'nexus://agent?message=Hello%20from%20deep%20link'
+```
+
+Query parameters:
+- `message` (required): the agent prompt (URL-encoded).
+- `sessionKey` (optional): explicit session key to use.
+- `thinking` (optional): thinking hint (e.g. `low`; omit for default).
+- `deliver` (optional): `true|false` (default: false).
+- `to` / `provider` (optional): forwarded to the Gateway `agent` method (only meaningful with `deliver=true`).
+- `timeoutSeconds` (optional): timeout hint forwarded to the Gateway.
+- `key` (optional): unattended mode key (see below).
+
+Safety/guardrails:
+- Always enabled.
+- Without a `key` query param, the app will prompt for confirmation before invoking the agent.
+- With `key=<value>`, Nexus runs without prompting (intended for personal automations).
+  - The current key is shown in Debug Settings and stored locally in UserDefaults.
+
+Notes:
+- In local mode, Nexus will start the local Gateway if needed before issuing the request.
+- In remote mode, Nexus will use the configured remote tunnel/endpoint.
+
+## Build & dev workflow (native)
+- `cd apps/macos && swift build` (debug) / `swift build -c release`.
+- Run app for dev: `swift run Nexus` (or Xcode scheme).
+- Package app + CLI: `scripts/package-mac-app.sh` (builds bun CLI + gateway).
+- Tests: add Swift Testing suites under `apps/macos/Tests`.
+
+## Open questions / decisions
+- Should `system.run` support streaming stdout/stderr or keep buffered responses only?
+- Should we allow node‑side permission prompts, or always require explicit app UI action?

package/docs/model-failover.md

@@ -0,0 +1,75 @@
+---
+summary: "How Nexus rotates auth profiles and falls back across models"
+read_when:
+  - Diagnosing auth profile rotation, cooldowns, or model fallback behavior
+  - Updating failover rules for auth profiles or models
+---
+
+# Model failover
+
+Nexus handles failures in two stages:
+1) **Auth profile rotation** within the current provider.
+2) **Model fallback** to the next model in `agent.model.fallbacks`.
+
+This doc explains the runtime rules and the data that backs them.
+
+## Profile IDs
+
+OAuth logins create distinct profiles so multiple accounts can coexist.
+- Default: `provider:default` when no email is available.
+- OAuth with email: `provider:<email>` (for example `google-antigravity:user@gmail.com`).
+
+Profiles live in `~/nexus/state/agent/auth-profiles.json` under `profiles`.
+
+## Rotation order
+
+When a provider has multiple profiles, Nexus chooses an order like this:
+
+1) **Explicit config**: `auth.order[provider]` (if set).
+2) **Configured profiles**: `auth.profiles` filtered by provider.
+3) **Stored profiles**: entries in `auth-profiles.json` for the provider.
+
+If no explicit order is configured, Nexus uses a round‑robin order:
+- **Primary key:** `usageStats.lastUsed` (oldest first).
+- **Secondary key:** profile type (OAuth before API keys).
+- **Cooldown profiles** are moved to the end, ordered by soonest cooldown expiry.
+
+## Cooldowns
+
+When a profile fails due to auth/rate‑limit errors (or a timeout that looks
+like rate limiting), Nexus marks it in cooldown and moves to the next profile.
+
+Cooldowns use exponential backoff:
+- 1 minute
+- 5 minutes
+- 25 minutes
+- 1 hour (cap)
+
+State is stored in `auth-profiles.json` under `usageStats`:
+
+```json
+{
+  "usageStats": {
+    "provider:profile": {
+      "lastUsed": 1736160000000,
+      "cooldownUntil": 1736160600000,
+      "errorCount": 2
+    }
+  }
+}
+```
+
+## Model fallback
+
+If all profiles for a provider fail, Nexus moves to the next model in
+`agent.model.fallbacks`. This applies to auth failures, rate limits, and
+timeouts that exhausted profile rotation.
+
+## Related config
+
+See [`docs/configuration.md`](https://docs.nexus.bot/configuration) for:
+- `auth.profiles` / `auth.order`
+- `agent.model.primary` / `agent.model.fallbacks`
+- `agent.imageModel` routing
+
+See [`docs/models.md`](https://docs.nexus.bot/models) for the broader model selection and fallback overview.

package/docs/models.md

@@ -0,0 +1,91 @@
+---
+summary: "Plan for models CLI: scan, list, aliases, fallbacks, status"
+read_when:
+  - Adding or modifying models CLI (models list/set/scan/aliases/fallbacks)
+  - Changing model fallback behavior or selection UX
+  - Updating model scan probes (tools/images)
+---
+# Models CLI plan
+
+Goal: give clear model visibility + control (configured vs available), plus scan tooling
+that prefers tool-call + image-capable models and maintains ordered fallbacks.
+
+## Command tree (draft)
+
+- `nexus models list`
+  - default: configured models only
+  - flags: `--all` (full catalog), `--local`, `--provider <name>`, `--json`, `--plain`
+- `nexus models status`
+  - show default model + aliases + fallbacks + configured models
+- `nexus models set <modelOrAlias>`
+  - writes `agent.model.primary` and ensures `agent.models` entry
+- `nexus models set-image <modelOrAlias>`
+  - writes `agent.imageModel.primary` and ensures `agent.models` entry
+- `nexus models aliases list|add|remove`
+  - writes `agent.models.*.alias`
+- `nexus models fallbacks list|add|remove|clear`
+  - writes `agent.model.fallbacks`
+- `nexus models image-fallbacks list|add|remove|clear`
+  - writes `agent.imageModel.fallbacks`
+- `nexus models scan`
+  - OpenRouter :free scan; probe tool-call + image; interactive selection
+
+## Config changes
+
+- `agent.models` (configured model catalog + aliases).
+- `agent.model.primary` + `agent.model.fallbacks`.
+- `agent.imageModel.primary` + `agent.imageModel.fallbacks` (optional).
+- `auth.profiles` + `auth.order` for per-provider auth failover.
+
+## Scan behavior (models scan)
+
+Input
+- OpenRouter `/models` list (filter `:free`)
+- Requires OpenRouter API key from auth profiles or `OPENROUTER_API_KEY`
+- Optional filters: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates`
+- Probe controls: `--timeout`, `--concurrency`
+
+Probes (direct pi-ai complete)
+- Tool-call probe (required):
+  - Provide a dummy tool, verify tool call emitted.
+- Image probe (preferred):
+  - Prompt includes 1x1 PNG; success if no "unsupported image" error.
+
+Scoring/selection
+- Prefer models passing tool + image for text/tool fallbacks.
+- Prefer image-only models for image tool fallback (even if tool probe fails).
+- Rank by: image ok, then lower tool latency, then larger context, then params.
+
+Interactive selection (TTY)
+- Multiselect list with per-model stats:
+  - model id, tool ok, image ok, median latency, context, inferred params.
+- Pre-select top N (default 6).
+- Non-TTY: auto-select; require `--yes`/`--no-input` to apply.
+
+Output
+- Writes `agent.model.fallbacks` ordered.
+- Writes `agent.imageModel.fallbacks` ordered (image-capable models).
+- Ensures `agent.models` entries exist for selected models.
+- Optional `--set-default` to set `agent.model.primary`.
+- Optional `--set-image` to set `agent.imageModel.primary`.
+
+## Runtime fallback
+
+- On model failure: try `agent.model.fallbacks` in order.
+- Per-provider auth failover uses `auth.order` (or stored profile order) **before**
+  moving to the next model.
+- Image routing uses `agent.imageModel` **only when configured** and the primary
+  model lacks image input.
+- Persist last successful provider/model to session entry; auth profile success is global.
+- See [`docs/model-failover.md`](https://docs.nexus.bot/model-failover) for auth profile rotation, cooldowns, and timeout handling.
+
+## Tests
+
+- Unit: scan selection ordering + probe classification.
+- CLI: list/aliases/fallbacks add/remove + scan writes config.
+- Status: shows last used model + fallbacks.
+
+## Docs
+
+- Update [`docs/configuration.md`](https://docs.nexus.bot/configuration) with `agent.models` + `agent.model` + `agent.imageModel`.
+- Keep this doc current when CLI surface or scan logic changes.

package/docs/multi-agent.md

@@ -0,0 +1,74 @@
+---
+title: Multi-Agent Routing
+read_when: "You want multiple isolated agents (workspaces + auth) in one gateway process."
+status: active
+---
+
+# Multi-Agent Routing
+
+Goal: multiple *isolated* agents (separate workspace + `agentDir` + sessions), plus multiple provider accounts (e.g. two WhatsApps) in one running Gateway. Inbound is routed to an agent via bindings.
+
+## Concepts
+
+- `agentId`: one “brain” (workspace, per-agent auth, per-agent session store).
+- `accountId`: one provider account instance (e.g. WhatsApp account `"personal"` vs `"biz"`).
+- `binding`: routes inbound messages to an `agentId` by `(provider, accountId, peer)` and optionally guild/team ids.
+- Direct chats collapse to `agent:<agentId>:<mainKey>` (per-agent “main”; `session.mainKey`).
+
+## Example: two WhatsApps → two agents
+
+`~/nexus/state/nexus.json` (JSON5):
+
+```js
+{
+  routing: {
+    defaultAgentId: "home",
+
+    agents: {
+      home: {
+        workspace: "~/nexus-home",
+        agentDir: "~/nexus/state/agents/home/agent",
+      },
+      work: {
+        workspace: "~/nexus-work",
+        agentDir: "~/nexus/state/agents/work/agent",
+      },
+    },
+
+    // Deterministic routing: first match wins (most-specific first).
+    bindings: [
+      { agentId: "home", match: { provider: "whatsapp", accountId: "personal" } },
+      { agentId: "work", match: { provider: "whatsapp", accountId: "biz" } },
+
+      // Optional per-peer override (example: send a specific group to work agent).
+      {
+        agentId: "work",
+        match: {
+          provider: "whatsapp",
+          accountId: "personal",
+          peer: { kind: "group", id: "1203630...@g.us" },
+        },
+      },
+    ],
+
+    // Off by default: agent-to-agent messaging must be explicitly enabled + allowlisted.
+    agentToAgent: {
+      enabled: false,
+      allow: ["home", "work"],
+    },
+  },
+
+  whatsapp: {
+    accounts: {
+      personal: {
+        // Optional override. Default: ~/nexus/state/credentials/whatsapp/personal
+        // authDir: "~/nexus/state/credentials/whatsapp/personal",
+      },
+      biz: {
+        // Optional override. Default: ~/nexus/state/credentials/whatsapp/biz
+        // authDir: "~/nexus/state/credentials/whatsapp/biz",
+      },
+    },
+  },
+}
+```

package/docs/nix.md

@@ -0,0 +1,95 @@
+---
+summary: "Install Nexus declaratively with Nix"
+read_when:
+  - You want reproducible, rollback-able installs
+  - You're already using Nix/NixOS/Home Manager
+  - You want everything pinned and managed declaratively
+---
+
+# Nix Installation
+
+The recommended way to run Nexus with Nix is via **[nix-nexus](https://github.com/nexus/nix-nexus)** — a batteries-included Home Manager module.
+
+## Quick Start
+
+Paste this to your AI agent (Claude, Cursor, etc.):
+
+```text
+I want to set up nix-nexus on my Mac.
+Repository: github:nexus/nix-nexus
+
+What I need you to do:
+1. Check if Determinate Nix is installed (if not, install it)
+2. Create a local flake at ~/code/nexus-local using templates/agent-first/flake.nix
+3. Help me create a Telegram bot (@BotFather) and get my chat ID (@userinfobot)
+4. Set up secrets (bot token, Anthropic key) - plain files at ~/.secrets/ is fine
+5. Fill in the template placeholders and run home-manager switch
+6. Verify: launchd running, bot responds to messages
+
+Reference the nix-nexus README for module options.
+```
+
+> **📦 Full guide: [github.com/nexus/nix-nexus](https://github.com/nexus/nix-nexus)**
+>
+> The nix-nexus repo is the source of truth for Nix installation. This page is just a quick overview.
+
+## What you get
+
+- Gateway + macOS app + tools (whisper, spotify, cameras) — all pinned
+- Launchd service that survives reboots
+- Plugin system with declarative config
+- Instant rollback: `home-manager switch --rollback`
+
+---
+
+## Nix Mode Runtime Behavior
+
+When `NEXUS_NIX_MODE=1` is set (automatic with nix-nexus):
+
+Nexus supports a **Nix mode** that makes configuration deterministic and disables auto-install flows.
+Enable it by exporting:
+
+```bash
+NEXUS_NIX_MODE=1
+```
+
+On macOS, the GUI app does not automatically inherit shell env vars. You can
+also enable Nix mode via defaults:
+
+```bash
+defaults write com.nexus.mac nexus.nixMode -bool true
+```
+
+### Config + state paths
+
+Nexus reads JSON5 config from `NEXUS_CONFIG_PATH` and stores mutable data in `NEXUS_STATE_DIR`.
+
+- `NEXUS_STATE_DIR` (default: `~/nexus/state`)
+- `NEXUS_CONFIG_PATH` (default: `$NEXUS_STATE_DIR/nexus.json`)
+
+When running under Nix, set these explicitly to Nix-managed locations so runtime state and config
+stay out of the immutable store.
+
+### Runtime behavior in Nix mode
+
+- Auto-install and self-mutation flows are disabled
+- Missing dependencies surface Nix-specific remediation messages
+- UI surfaces a read-only Nix mode banner when present
+
+## Packaging note (macOS)
+
+The macOS packaging flow expects a stable Info.plist template at:
+
+```
+apps/macos/Sources/Nexus/Resources/Info.plist
+```
+
+`scripts/package-mac-app.sh` copies this template into the app bundle and patches dynamic fields
+(bundle ID, version/build, Git SHA, Sparkle keys). This keeps the plist deterministic for SwiftPM
+packaging and Nix builds (which do not rely on a full Xcode toolchain).
+
+## Related
+
+- [nix-nexus](https://github.com/nexus/nix-nexus) — full setup guide
+- [Wizard](https://docs.nexus.bot/wizard) — non-Nix CLI setup
+- [Docker](https://docs.nexus.bot/docker) — containerized setup