@intent-systems/nexus 2026.1.5-3

package/docs/troubleshooting.md

@@ -0,0 +1,257 @@
+---
+summary: "Quick troubleshooting guide for common Nexus failures"
+read_when:
+  - Investigating runtime issues or failures
+---
+# Troubleshooting 🔧
+
+When your NEXUS misbehaves, here's how to fix it.
+
+## Common Issues
+
+### "Agent was aborted"
+
+The agent was interrupted mid-response.
+
+**Causes:**
+- User sent `stop`, `abort`, `esc`, or `exit`
+- Timeout exceeded
+- Process crashed
+
+**Fix:** Just send another message. The session continues.
+
+### Messages Not Triggering
+
+**Check 1:** Is the sender in `whatsapp.allowFrom`?
+```bash
+cat ~/nexus/state/nexus.json | jq '.whatsapp.allowFrom'
+```
+
+**Check 2:** For group chats, is mention required?
+```bash
+# The message must match mentionPatterns or explicit mentions; defaults live in provider groups/guilds.
+cat ~/nexus/state/nexus.json | jq '.routing.groupChat, .whatsapp.groups, .telegram.groups, .imessage.groups, .discord.guilds'
+```
+
+**Check 3:** Check the logs
+```bash
+tail -f "$(ls -t ~/nexus/state/logs/nexus-*.log | head -1)" | grep "blocked\\|skip\\|unauthorized"
+```
+
+### Image + Mention Not Working
+
+Known issue: When you send an image with ONLY a mention (no other text), WhatsApp sometimes doesn't include the mention metadata.
+
+**Workaround:** Add some text with the mention:
+- ❌ `@nexus` + image
+- ✅ `@nexus check this` + image
+
+### Session Not Resuming
+
+**Check 1:** Is the session file there?
+```bash
+ls -la ~/nexus/state/sessions/
+```
+
+**Check 2:** Is `idleMinutes` too short?
+```json
+{
+  "session": {
+    "idleMinutes": 10080  // 7 days
+  }
+}
+```
+
+**Check 3:** Did someone send `/new`, `/reset`, or a reset trigger?
+
+### Agent Timing Out
+
+Default timeout is 30 minutes. For long tasks:
+
+```json
+{
+  "reply": {
+    "timeoutSeconds": 3600  // 1 hour
+  }
+}
+```
+
+Or use the `process` tool to background long commands.
+
+### WhatsApp Disconnected
+
+```bash
+# Check local status (creds, sessions, queued events)
+nexus status
+# Probe the running gateway + providers (WA connect + Telegram + Discord APIs)
+nexus status --deep
+
+# View recent connection events
+tail -100 ~/nexus/state/logs/nexus-*.log | grep "connection\\|disconnect\\|logout"
+```
+
+**Fix:** Usually reconnects automatically once the Gateway is running. If you’re stuck, restart the Gateway process (however you supervise it), or run it manually with verbose output:
+
+```bash
+nexus gateway --verbose
+```
+
+If you’re logged out / unlinked:
+
+```bash
+nexus logout
+trash ~/nexus/state/credentials # if logout can't cleanly remove everything
+nexus login --verbose       # re-scan QR
+```
+
+### Media Send Failing
+
+**Check 1:** Is the file path valid?
+```bash
+ls -la /path/to/your/image.jpg
+```
+
+**Check 2:** Is it too large?
+- Images: max 6MB
+- Audio/Video: max 16MB  
+- Documents: max 100MB
+
+**Check 3:** Check media logs
+```bash
+grep "media\\|fetch\\|download" "$(ls -t ~/nexus/state/logs/nexus-*.log | head -1)" | tail -20
+```
+
+### High Memory Usage
+
+NEXUS keeps conversation history in memory.
+
+**Fix:** Restart periodically or set session limits:
+```json
+{
+  "session": {
+    "historyLimit": 100  // Max messages to keep
+  }
+}
+```
+
+## macOS Specific Issues
+
+### App Crashes when Granting Permissions (Speech/Mic)
+
+If the app disappears or shows "Abort trap 6" when you click "Allow" on a privacy prompt:
+
+**Fix 1: Reset TCC Cache**
+```bash
+tccutil reset All com.nexus.mac.debug
+```
+
+**Fix 2: Force New Bundle ID**
+If resetting doesn't work, change the `BUNDLE_ID` in `scripts/package-mac-app.sh` (e.g., add a `.test` suffix) and rebuild. This forces macOS to treat it as a new app.
+
+### Gateway stuck on "Starting..."
+
+The app connects to a local gateway on port `18789`. If it stays stuck:
+
+**Fix 1: Kill Zombie Processes**
+Another process might be holding the port.
+```bash
+lsof -nP -i :18789
+# Kill any matching PIDs
+kill -9 <PID>
+```
+
+If the gateway is supervised by launchd, killing the PID will just respawn it.
+Stop the supervisor instead:
+```bash
+nexus gateway stop
+# Or: launchctl bootout gui/$UID/com.nexus.gateway
+```
+
+**Fix 2: Check embedded gateway**
+Ensure the gateway relay was properly bundled. Run `./scripts/package-mac-app.sh` and ensure `bun` is installed.
+
+## Debug Mode
+
+Get verbose logging:
+
+```bash
+# Turn on trace logging in config:
+#   ~/nexus/state/nexus.json -> { logging: { level: "trace" } }
+#
+# Then run verbose commands to mirror debug output to stdout:
+nexus gateway --verbose
+nexus login --verbose
+```
+
+## Log Locations
+
+| Log | Location |
+|-----|----------|
+| Main logs (default) | `~/nexus/state/logs/nexus-YYYY-MM-DD.log` |
+| Session files | `~/nexus/state/sessions/` |
+| Media cache | `~/nexus/state/media/` |
+| Credentials | `~/nexus/state/credentials/` |
+
+## Health Check
+
+```bash
+# Is the gateway reachable?
+nexus health --json
+
+# Is something listening on the default port?
+lsof -nP -iTCP:18789 -sTCP:LISTEN
+
+# Recent activity
+tail -20 ~/nexus/state/logs/nexus-*.log
+```
+
+## Reset Everything
+
+Nuclear option:
+
+```bash
+trash ~/nexus/state
+nexus login         # re-pair WhatsApp
+nexus gateway        # start the Gateway again
+```
+
+⚠️ This loses all sessions and requires re-pairing WhatsApp.
+
+## Getting Help
+
+1. Check logs first: `~/nexus/state/logs/` (default: `nexus-YYYY-MM-DD.log`, or your configured `logging.file`)
+2. Search existing issues on GitHub
+3. Open a new issue with:
+   - NEXUS version
+   - Relevant log snippets
+   - Steps to reproduce
+   - Your config (redact secrets!)
+
+---
+
+*"Have you tried turning it off and on again?"* — Every IT person ever
+
+🦞🔧
+
+### Browser Not Starting (Linux)
+
+If you see `"Failed to start Chrome CDP on port 18800"`:
+
+**Most likely cause:** Snap-packaged Chromium on Ubuntu.
+
+**Quick fix:** Install Google Chrome instead:
+```bash
+wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
+sudo dpkg -i google-chrome-stable_current_amd64.deb
+```
+
+Then set in config:
+```json
+{
+  "browser": {
+    "executablePath": "/usr/bin/google-chrome-stable"
+  }
+}
+```
+
+**Full guide:** See [browser-linux-troubleshooting](https://docs.nexus.bot/browser-linux-troubleshooting)

package/docs/tui.md

@@ -0,0 +1,71 @@
+---
+summary: "Terminal UI (TUI) for Nexus via the Gateway"
+read_when:
+  - You want a terminal UI that connects to the Gateway from any machine
+  - You are debugging the TUI client or Gateway chat stream
+---
+# TUI (Gateway chat client)
+
+Updated: 2026-01-03
+
+## What it is
+- A terminal UI that connects to the Gateway WebSocket and speaks the same chat APIs as WebChat.
+- Uses Gateway agent events for tool cards while streaming responses.
+- Works locally (loopback) or remotely (Tailscale/SSH tunnel) without running a separate agent process.
+
+## Run
+```bash
+nexus tui
+```
+
+### Remote
+```bash
+nexus tui --url ws://127.0.0.1:18789 --token <gateway-token>
+```
+Use SSH tunneling or Tailscale to reach the Gateway WS.
+
+## Options
+- `--url <url>`: Gateway WebSocket URL (defaults to config `gateway.remote.url` or `ws://127.0.0.1:18789`).
+- `--token <token>`: Gateway token (if required).
+- `--password <password>`: Gateway password (if required).
+- `--session <key>`: Session key (default: `main`, or `global` when scope is global).
+- `--deliver`: Deliver assistant replies to the provider (default off).
+- `--thinking <level>`: Override thinking level for sends.
+- `--timeout-ms <ms>`: Agent timeout in ms (default 30000).
+- `--history-limit <n>`: History entries to load (default 200).
+
+## Controls
+- Enter: send message
+- Esc: abort active run
+- Ctrl+C: clear input (press twice to exit)
+- Ctrl+D: exit
+- Ctrl+L: model picker
+- Ctrl+P: session picker
+- Ctrl+O: toggle tool output expansion
+- Ctrl+T: toggle thinking visibility
+
+## Slash commands
+- `/help`
+- `/status`
+- `/session <key>` (or `/sessions`)
+- `/model <provider/model>` (or `/model list`, `/models`)
+- `/think <off|minimal|low|medium|high>`
+- `/verbose <on|off>`
+- `/elevated <on|off>`
+- `/elev <on|off>`
+- `/activation <mention|always>`
+- `/deliver <on|off>`
+- `/new` or `/reset`
+- `/compact [instructions]`
+- `/abort`
+- `/settings`
+- `/exit`
+
+## Notes
+- The TUI shows Gateway chat deltas (`event: chat`) and agent tool events.
+- It registers as a Gateway client with `mode: "tui"` for presence and debugging.
+
+## Files
+- CLI: `src/cli/tui-cli.ts`
+- Runner: `src/tui/tui.ts`
+- Gateway client: `src/tui/gateway-chat.ts`

package/docs/typebox.md

@@ -0,0 +1,42 @@
+---
+summary: "TypeBox schemas as the single source of truth for the gateway protocol"
+read_when:
+  - Updating protocol schemas or codegen
+---
+# TypeBox as Protocol Source of Truth
+
+Last updated: 2025-12-09
+
+We use TypeBox schemas in `src/gateway/protocol/schema.ts` as the single source of truth for the Gateway control plane (connect/req/res/event frames and payloads). All derived artifacts should be generated from these schemas, not edited by hand.
+
+## Current pipeline
+
+- **TypeBox → JSON Schema**: `pnpm protocol:gen` writes `dist/protocol.schema.json` (draft-07) and runs AJV in the server tests.
+- **TypeBox → Swift**: `pnpm protocol:gen:swift` generates `apps/macos/Sources/NexusProtocol/GatewayModels.swift`.
+
+## Problem
+
+- We want strong typing in Swift, including a sealed `GatewayFrame` enum with a discriminator and a forward-compatible `unknown` case.
+
+## Preferred plan (next step)
+
+- Add a small, custom Swift generator driven directly by the TypeBox schemas:
+  - Emit a sealed `enum GatewayFrame: Codable { case req(RequestFrame), res(ResponseFrame), event(EventFrame) }`.
+  - Emit strongly typed payload structs/enums (`ConnectParams`, `HelloOk`, `RequestFrame`, `ResponseFrame`, `EventFrame`, `PresenceEntry`, `Snapshot`, `StateVersion`, `ErrorShape`, `AgentEvent`, `TickEvent`, `ShutdownEvent`, `SendParams`, `AgentParams`, `ErrorCode`, `PROTOCOL_VERSION`).
+  - Custom `init(from:)` / `encode(to:)` enforces the `type` discriminator and can include an `unknown` case for forward compatibility.
+  - Wire a new script (e.g., `pnpm protocol:gen:swift`) into `protocol:check` so CI fails if the generated Swift is stale.
+
+Why this path:
+- Single source of truth stays TypeBox; no new IDL to maintain.
+- Predictable, strongly typed Swift (no optional soup).
+- Small deterministic codegen (~150–200 LOC script) we control.
+
+## Alternative (if we want off-the-shelf codegen)
+
+- Wrap the existing JSON Schema into an OpenAPI 3.1 doc (auto-generated) and use **swift-openapi-generator** or **openapi-generator swift5**. More moving parts, but also yields enums with discriminator support. Keep this as a fallback if we don’t want a custom emitter.
+
+## Action items
+
+- Implement `protocol:gen:swift` that reads the TypeBox schemas and emits the sealed Swift enum + payload structs.
+- Update `protocol:check` to include the Swift generator output in the diff check.
+- Remove quicktype output once the custom generator is in place (or keep it for docs only).

package/docs/updating.md

@@ -0,0 +1,138 @@
+---
+summary: "Updating Nexus safely (npm or source), plus rollback strategy"
+read_when:
+  - Updating Nexus
+  - Something breaks after an update
+---
+
+# Updating
+
+Nexus is moving fast (pre “1.0”). Treat updates like shipping infra: update → run checks → restart → verify.
+
+## Before you update
+
+- Know how you installed: **npm** (global) vs **from source** (git clone).
+- Know how your Gateway is running: **foreground terminal** vs **supervised service** (launchd/systemd/Scheduled Task).
+- Snapshot your tailoring:
+  - Config: `~/nexus/state/nexus.json`
+  - Credentials: `~/nexus/state/credentials/`
+  - Workspace: `~/nexus`
+
+## Update (npm install)
+
+Global install (pick one):
+
+```bash
+npm i -g nexus@latest
+```
+
+```bash
+pnpm add -g nexus@latest
+```
+
+Then:
+
+```bash
+nexus doctor
+nexus gateway restart
+nexus health
+```
+
+Notes:
+- If your Gateway runs as a service, `nexus gateway restart` is preferred over killing PIDs.
+- If you’re pinned to a specific version, see “Rollback / pinning” below.
+
+## Update (from source)
+
+From the repo checkout:
+
+```bash
+git pull
+pnpm install
+pnpm build
+pnpm ui:install
+pnpm ui:build
+pnpm nexus doctor
+pnpm nexus health
+```
+
+Notes:
+- `pnpm build` matters when you run the packaged `nexus` binary (`dist/entry.js`) or use Node to run `dist/`.
+- If you run directly from TypeScript (`pnpm nexus ...` / `bun run nexus ...`), a rebuild is usually unnecessary, but **config migrations still apply** → run doctor.
+
+## Always run: `nexus doctor`
+
+Doctor is the “safe update” command. It’s intentionally boring: repair + migrate + warn.
+
+Typical things it does:
+- Migrate deprecated config keys / legacy config file locations.
+- Audit DM policies and warn on risky “open” settings.
+- Check Gateway health and can offer to restart.
+- Detect and migrate older gateway services (launchd/systemd/schtasks) to current Nexus services.
+- On Linux, ensure systemd user lingering (so the Gateway survives logout).
+
+Details: https://docs.nexus.bot/doctor
+
+## Start / stop / restart the Gateway
+
+CLI (works regardless of OS):
+
+```bash
+nexus gateway stop
+nexus gateway restart
+nexus gateway --port 18789
+```
+
+If you’re supervised:
+- macOS launchd (app-bundled LaunchAgent): `launchctl kickstart -k gui/$UID/com.nexus.gateway`
+- Linux systemd user service: `systemctl --user restart nexus-gateway.service`
+- Windows: restart the `Nexus Gateway` Scheduled Task (Task Scheduler)
+
+Runbook + exact service labels: https://docs.nexus.bot/gateway
+
+## Rollback / pinning (when something breaks)
+
+### Pin (npm)
+
+Install a known-good version:
+
+```bash
+npm i -g nexus@2026.1.5-3
+```
+
+Then restart + re-run doctor:
+
+```bash
+nexus doctor
+nexus gateway restart
+```
+
+### Pin (source) by date
+
+Pick a commit from a date (example: “state of main as of 2026-01-01”):
+
+```bash
+git fetch origin
+git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
+```
+
+Then reinstall deps + restart:
+
+```bash
+pnpm install
+pnpm build
+pnpm nexus gateway restart
+```
+
+If you want to go back to latest later:
+
+```bash
+git checkout main
+git pull
+```
+
+## If you’re stuck
+
+- Run `nexus doctor` again and read the output carefully (it often tells you the fix).
+- Check: https://docs.nexus.bot/troubleshooting
+- Ask in Discord: https://discord.gg/nexus

package/docs/usage-cloud-aggregation-spec.md

@@ -0,0 +1,133 @@
+# Nexus Usage Cloud Aggregation Spec (Draft)
+
+This spec defines the anonymized usage event schema and the local upload
+batching mechanism. It is designed to preserve ordering while minimizing
+privacy risk.
+
+## Goals
+
+- Aggregate usage patterns across users without storing PII.
+- Preserve event order within a session.
+- Allow local-only operation by default (opt-in for upload).
+- Support backfill from local event logs.
+
+## Non-Goals
+
+- Rich content capture (no args, no file paths).
+- Per-user personalization in the cloud.
+- Any biometric, location, or personal identifiers.
+
+## Anonymization Model
+
+### Identifiers
+
+- `anon_user_id`: stable random UUID stored locally.
+- `anon_session_id`: SHA-256 of `(anon_salt + session_id)`.
+- `anon_salt`: local-only random secret. Never uploaded.
+
+### Data Removed
+
+- Command arguments
+- File paths
+- Freeform text
+- Secrets or tokens
+
+### Allowed Fields
+
+- `command_path` (e.g., `status`, `skills search`)
+- `tool_name` (e.g., `run_terminal_cmd`)
+- `event_type`, `source`, `seq`, `ts`
+- `invocation_kind` (optional)
+
+## Upload Event Schema (JSON)
+
+```json
+{
+  "schema_version": 1,
+  "anon_user_id": "uuid",
+  "anon_session_id": "sha256",
+  "ts": 1712345678901,
+  "seq": 12,
+  "source": "nexus_cli",
+  "event_type": "command_finished",
+  "command_path": "status",
+  "tool_name": "run_terminal_cmd",
+  "tool_phase": "start",
+  "invocation_kind": "node_dist",
+  "status": "ok"
+}
+```
+
+## Batch Schema (JSON)
+
+```json
+{
+  "batch_id": "uuid",
+  "generated_at": 1712345680000,
+  "schema_version": 1,
+  "anon_user_id": "uuid",
+  "events": [ ... ]
+}
+```
+
+## Upload Pipeline (Local)
+
+1. Read `~/nexus/state/events/*.jsonl`
+2. Filter to allowed event types:
+   - `command_started|finished|failed`
+   - `agent_event` with `stream=tool` and `phase=start`
+3. Transform into upload events:
+   - anonymize `session_id`
+   - drop args and freeform content
+4. Write to outbox:
+   - `~/nexus/state/events-outbox/usage-batch-<ts>-<id>.json`
+5. Upload outbox file to cloud endpoint
+
+### Cursor State
+
+An upload state file tracks the last processed event:
+
+```
+~/nexus/state/usage/upload-state.json
+```
+
+Fields:
+- `cursor_ts`
+- `cursor_id`
+- `anon_id`
+- `anon_salt`
+
+## Configuration
+
+Environment variables:
+
+- `NEXUS_USAGE_UPLOAD_URL` (required to upload)
+- `NEXUS_USAGE_UPLOAD_TOKEN` (optional bearer token)
+- `NEXUS_USAGE_OUTBOX_DIR` (optional override)
+
+Disable upload:
+- Do not set `NEXUS_USAGE_UPLOAD_URL`
+
+Disable event log entirely:
+- `NEXUS_EVENT_LOG=0`
+
+## CLI Surface
+
+```
+nexus usage upload --dry-run --json
+nexus usage upload --limit 500
+nexus usage upload --only-flush
+```
+
+## Server Requirements
+
+The upload endpoint should:
+- accept JSON batches
+- validate schema_version
+- respond 2xx on success
+
+## Privacy Notes
+
+- `anon_user_id` is local-only and never reversible.
+- `anon_session_id` is salted; a single session cannot be linked across devices.
+- If the user opts out, the outbox remains empty.