@intent-systems/nexus 2026.1.5-3

package/docs/wizard.md

@@ -0,0 +1,167 @@
+---
+summary: "CLI onboarding wizard: guided setup for gateway, workspace, providers, and skills"
+read_when:
+  - Running or configuring the onboarding wizard
+  - Setting up a new machine
+---
+
+# Onboarding Wizard (CLI)
+
+The onboarding wizard is the **recommended** way to set up Nexus on any OS.
+It configures a local Gateway or a remote Gateway connection, plus providers, skills,
+and workspace defaults in one guided flow.
+
+Primary entrypoint:
+
+```bash
+nexus onboard
+```
+
+Follow‑up reconfiguration:
+
+```bash
+nexus configure
+```
+
+## What the wizard does
+
+**Local mode (default)** walks you through:
+- Model/auth (Anthropic or OpenAI Codex OAuth recommended, API key optional, Minimax M2.1 via LM Studio)
+- Workspace location + bootstrap files
+- Gateway settings (port/bind/auth/tailscale)
+- Providers (WhatsApp, Telegram, Discord, Signal)
+- Daemon install (LaunchAgent / systemd user unit / Scheduled Task)
+- Health check
+- Skills (recommended)
+
+**Remote mode** only configures the local client to connect to a Gateway elsewhere.
+It does **not** install or change anything on the remote host.
+
+## Flow details (local)
+
+1) **Existing config detection**
+   - If `~/nexus/state/nexus.json` exists, choose **Keep / Modify / Reset**.
+   - Reset uses `trash` (never `rm`) and offers scopes:
+     - Config only
+     - Config + credentials + sessions
+     - Full reset (also removes workspace)
+
+2) **Model/Auth**
+   - **Anthropic OAuth (recommended)**: browser flow; paste the `code#state`.
+   - **OpenAI Codex OAuth**: browser flow; paste the `code#state`.
+     - Sets `agent.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`.
+   - **API key**: stores the key for you.
+   - **Minimax M2.1 (LM Studio)**: config is auto‑written for the LM Studio endpoint.
+   - **Skip**: no auth configured yet.
+   - Wizard runs a model check and warns if the configured model is unknown or missing auth.
+   - OAuth credentials live in `~/nexus/state/credentials/oauth.json`; auth profiles live in `~/nexus/state/agent/auth-profiles.json` (API keys + OAuth).
+
+3) **Workspace**
+   - Default `~/nexus` (configurable).
+   - Seeds the workspace files needed for the agent bootstrap ritual.
+
+4) **Gateway**
+   - Port, bind, auth mode, tailscale exposure.
+   - Auth recommendation: keep **Off** for single-machine loopback setups. Use **Token** for multi-machine access or non-loopback binds.
+   - Non‑loopback binds require auth.
+
+5) **Providers**
+   - WhatsApp: optional QR login.
+   - Telegram: bot token.
+   - Discord: bot token.
+   - Signal: optional `signal-cli` install + account config.
+   - iMessage: local `imsg` CLI path + DB access.
+   - DM security: default is pairing (unknown DMs get a pairing code). Approve via `nexus pairing approve --provider <provider> <code>`.
+
+6) **Daemon install**
+   - macOS: LaunchAgent
+     - Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
+   - Linux: systemd user unit
+     - Wizard attempts to enable lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.
+     - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
+   - Windows: Scheduled Task
+     - Runs on user logon; headless/system services are not configured by default.
+
+7) **Health check**
+   - Starts the Gateway (if needed) and runs `nexus health`.
+
+8) **Skills (recommended)**
+   - Reads the available skills and checks requirements.
+   - Lets you choose a node manager: **npm / pnpm / bun**.
+   - Installs optional dependencies (some use Homebrew on macOS).
+
+9) **Finish**
+   - Summary + next steps, including iOS/Android/macOS apps for extra features.
+   - If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.
+
+## Remote mode
+
+Remote mode configures a local client to connect to a Gateway elsewhere.
+
+What you’ll set:
+- Remote Gateway URL (`ws://...`)
+- Optional token
+
+Notes:
+- No remote installs or daemon changes are performed.
+- If the Gateway is loopback‑only, use SSH tunneling or a tailnet.
+- Discovery hints:
+  - macOS: Bonjour (`dns-sd`)
+  - Linux: Avahi (`avahi-browse`)
+
+## Non‑interactive mode
+
+Use `--non-interactive` to automate or script onboarding:
+
+```bash
+nexus onboard --non-interactive \
+  --mode local \
+  --auth-choice apiKey \
+  --anthropic-api-key "$ANTHROPIC_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback \
+  --skip-skills
+```
+
+Add `--json` for a machine‑readable summary.
+
+## Gateway wizard RPC
+
+The Gateway exposes the wizard flow over RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`).
+Clients (macOS app, Control UI) can render steps without re‑implementing onboarding logic.
+
+## Signal setup (signal-cli)
+
+The wizard can install `signal-cli` from GitHub releases:
+- Downloads the appropriate release asset.
+- Stores it under `~/nexus/state/tools/signal-cli/<version>/`.
+- Writes `signal.cliPath` to your config.
+
+Notes:
+- JVM builds require **Java 21**.
+- Native builds are used when available.
+- Windows auto‑install is not supported yet (manual install required).
+
+## What the wizard writes
+
+Typical fields in `~/nexus/state/nexus.json`:
+- `agent.workspace`
+- `agent.model` / `models.providers` (if Minimax chosen)
+- `gateway.*` (mode, bind, auth, tailscale)
+- `telegram.botToken`, `discord.token`, `signal.*`, `imessage.*`
+- `skills.install.nodeManager`
+- `wizard.lastRunAt`
+- `wizard.lastRunVersion`
+- `wizard.lastRunCommit`
+- `wizard.lastRunCommand`
+- `wizard.lastRunMode`
+
+WhatsApp credentials go to `~/nexus/state/credentials/`.
+Sessions are stored under `~/nexus/state/sessions/`.
+
+## Related docs
+
+- macOS app onboarding: [`docs/onboarding.md`](https://docs.nexus.bot/onboarding)
+- Config reference: [`docs/configuration.md`](https://docs.nexus.bot/configuration)
+- Providers: [`docs/whatsapp.md`](https://docs.nexus.bot/whatsapp), [`docs/telegram.md`](https://docs.nexus.bot/telegram), [`docs/discord.md`](https://docs.nexus.bot/discord), [`docs/signal.md`](https://docs.nexus.bot/signal), [`docs/imessage.md`](https://docs.nexus.bot/imessage)
+- Skills: [`docs/skills.md`](https://docs.nexus.bot/skills), [`docs/skills-config.md`](https://docs.nexus.bot/skills-config)

package/package.json

@@ -0,0 +1,209 @@
+{
+  "name": "@intent-systems/nexus",
+  "version": "2026.1.5-3",
+  "description": "WhatsApp gateway CLI (Baileys web) with Pi RPC agent",
+  "homepage": "https://github.com/Napageneral/nexus",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Napageneral/nexus.git"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "nexus": "dist/entry.js"
+  },
+  "files": [
+    "dist/agents/**",
+    "dist/auto-reply/**",
+    "dist/browser/**",
+    "dist/canvas-host/**",
+    "dist/cli/**",
+    "dist/commands/**",
+    "dist/config/**",
+    "dist/control-ui/**",
+    "dist/cron/**",
+    "dist/daemon/**",
+    "dist/discord/**",
+    "dist/gateway/**",
+    "dist/hooks/**",
+    "dist/imessage/**",
+    "dist/infra/**",
+    "dist/macos/**",
+    "dist/media/**",
+    "dist/process/**",
+    "dist/sessions/**",
+    "dist/providers/**",
+    "dist/signal/**",
+    "dist/slack/**",
+    "dist/telegram/**",
+    "dist/tui/**",
+    "dist/web/**",
+    "dist/wizard/**",
+    "dist/*.js",
+    "dist/*.json",
+    "docs/**",
+    "skills/**",
+    "README.md",
+    "README-header.png",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "bun src/entry.ts",
+    "postinstall": "node scripts/postinstall.js",
+    "docs:list": "bun scripts/docs-list.ts",
+    "docs:dev": "cd docs && mint dev",
+    "docs:build": "cd docs && pnpm dlx mint broken-links",
+    "build": "tsc -p tsconfig.json && bun scripts/canvas-a2ui-copy.ts",
+    "release:check": "bun scripts/release-check.ts",
+    "release:npm": "bun scripts/release-npm.ts",
+    "release:brew": "bun scripts/release-brew.ts",
+    "release:all": "bun scripts/release-npm.ts && bun scripts/release-brew.ts",
+    "ui:install": "node scripts/ui.js install",
+    "ui:dev": "node scripts/ui.js dev",
+    "ui:build": "node scripts/ui.js build",
+    "start": "bun src/entry.ts",
+    "nexus": "bun src/entry.ts",
+    "gateway:watch": "bun --watch src/entry.ts gateway --force",
+    "nexus:rpc": "bun src/entry.ts agent --mode rpc --json",
+    "lint": "biome check src test && oxlint --type-aware src test --ignore-pattern src/canvas-host/a2ui/a2ui.bundle.js",
+    "lint:swift": "swiftlint lint --config .swiftlint.yml && (cd apps/ios && swiftlint lint --config .swiftlint.yml)",
+    "lint:fix": "biome check --write --unsafe src && biome format --write src",
+    "format": "biome format src",
+    "format:swift": "swiftformat --lint --config .swiftformat apps/macos/Sources apps/ios/Sources apps/shared/NexusKit/Sources",
+    "format:fix": "biome format src --write",
+    "test": "vitest",
+    "test:force": "bun scripts/test-force.ts",
+    "test:integration": "vitest run -t 'Real API'",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:install:smoke": "bash scripts/test-install-sh-docker.sh",
+    "test:docker:qr": "bash scripts/e2e/qr-import-docker.sh",
+    "protocol:gen": "bun scripts/protocol-gen.ts",
+    "protocol:gen:swift": "bun scripts/protocol-gen-swift.ts",
+    "protocol:check": "pnpm protocol:gen && pnpm protocol:gen:swift && git diff --exit-code -- dist/protocol.schema.json apps/macos/Sources/NexusProtocol/GatewayModels.swift",
+    "canvas:a2ui:bundle": "bash scripts/bundle-a2ui.sh"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "packageManager": "pnpm@10.23.0",
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "@grammyjs/transformer-throttler": "^1.2.1",
+    "@homebridge/ciao": "^1.3.4",
+    "@mariozechner/pi-agent-core": "^0.37.2",
+    "@mariozechner/pi-ai": "^0.37.2",
+    "@mariozechner/pi-coding-agent": "^0.37.2",
+    "@mariozechner/pi-tui": "^0.37.2",
+    "@sinclair/typebox": "0.34.46",
+    "@slack/bolt": "^4.6.0",
+    "@slack/web-api": "^7.13.0",
+    "@whiskeysockets/baileys": "7.0.0-rc.9",
+    "ajv": "^8.17.1",
+    "body-parser": "^2.2.1",
+    "chalk": "^5.6.2",
+    "chokidar": "^5.0.0",
+    "chromium-bidi": "12.0.1",
+    "commander": "^14.0.2",
+    "croner": "^9.1.0",
+    "detect-libc": "^2.1.2",
+    "discord-api-types": "^0.38.37",
+    "discord.js": "^14.25.1",
+    "dotenv": "^17.2.3",
+    "express": "^5.2.1",
+    "file-type": "^21.3.0",
+    "grammy": "^1.39.2",
+    "json5": "^2.2.3",
+    "long": "5.3.2",
+    "playwright-core": "1.57.0",
+    "proper-lockfile": "^4.1.2",
+    "qrcode-terminal": "^0.12.0",
+    "sharp": "^0.34.5",
+    "tslog": "^4.10.2",
+    "undici": "^7.18.0",
+    "ws": "^8.19.0",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.11",
+    "@lit-labs/signals": "^0.2.0",
+    "@lit/context": "^1.1.6",
+    "@mariozechner/mini-lit": "0.2.1",
+    "@types/body-parser": "^1.19.6",
+    "@types/express": "^5.0.6",
+    "@types/markdown-it": "^14.1.2",
+    "@types/node": "^25.0.3",
+    "@types/proper-lockfile": "^4.1.4",
+    "@types/qrcode-terminal": "^0.12.2",
+    "@types/ws": "^8.18.1",
+    "@vitest/coverage-v8": "^4.0.16",
+    "docx-preview": "^0.3.7",
+    "jszip": "^3.10.1",
+    "lit": "^3.3.2",
+    "lucide": "^0.562.0",
+    "markdown-it": "^14.1.0",
+    "ollama": "^0.6.3",
+    "oxlint": "^1.37.0",
+    "oxlint-tsgolint": "^0.10.1",
+    "quicktype-core": "^23.2.6",
+    "rolldown": "1.0.0-beta.58",
+    "signal-utils": "^0.21.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16",
+    "wireit": "^0.14.12"
+  },
+  "pnpm": {
+    "overrides": {
+      "@sinclair/typebox": "0.34.46"
+    },
+    "patchedDependencies": {
+      "@mariozechner/pi-ai": "patches/@mariozechner__pi-ai.patch",
+      "qrcode-terminal": "patches/qrcode-terminal.patch",
+      "playwright-core@1.57.0": "patches/playwright-core@1.57.0.patch"
+    }
+  },
+  "vitest": {
+    "coverage": {
+      "provider": "v8",
+      "reporter": [
+        "text",
+        "lcov"
+      ],
+      "thresholds": {
+        "lines": 70,
+        "functions": 70,
+        "branches": 70,
+        "statements": 70
+      },
+      "include": [
+        "src/**/*.ts"
+      ],
+      "exclude": [
+        "src/**/*.test.ts"
+      ]
+    },
+    "include": [
+      "src/**/*.test.ts"
+    ],
+    "exclude": [
+      "dist/**",
+      "apps/macos/**",
+      "apps/macos/.build/**",
+      "**/vendor/**",
+      "apps/macos/.build/**",
+      "dist/Nexus.app/**"
+    ]
+  },
+  "patchedDependencies": {
+    "@mariozechner/pi-ai": "patches/@mariozechner__pi-ai.patch",
+    "qrcode-terminal": "patches/qrcode-terminal.patch",
+    "playwright-core@1.57.0": "patches/playwright-core@1.57.0.patch"
+  }
+}

package/skills/1password/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: 1password
+description: Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
+homepage: https://developer.1password.com/docs/cli/get-started/
+metadata: {"nexus":{"emoji":"🔐","requires":{"bins":["op"]},"install":[{"id":"brew","kind":"brew","formula":"1password-cli","bins":["op"],"label":"Install 1Password CLI (brew)"}]}}
+---
+
+# 1Password CLI
+
+Follow the official CLI get-started steps. Don't guess install commands.
+
+## Docs
+
+- `docs/setup.md` (install + app integration + sign-in flow)
+- `docs/troubleshooting.md` (common failure modes + fixes)
+
+## References
+
+- `references/get-started.md` (install + app integration + sign-in flow)
+- `references/cli-examples.md` (real `op` examples)
+
+## Workflow
+
+1. Check OS + shell.
+2. Verify CLI present: `op --version`.
+3. Confirm desktop app integration is enabled (per get-started) and the app is unlocked.
+4. Sign in / authorize this terminal: `op signin` (expect an app prompt).
+5. If multiple accounts: use `--account` or `OP_ACCOUNT`.
+6. Verify access: `op whoami` or `op account list`.
+
+## Avoid repeated auth prompts (tmux)
+
+The bash tool uses a fresh TTY per command, so app integration may prompt every time. To reuse authorization, run multiple `op` commands inside a single tmux session.
+
+Example (see `tmux` skill for socket conventions):
+
+```bash
+SOCKET_DIR="${NEXUS_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/nexus-tmux-sockets}"
+mkdir -p "$SOCKET_DIR"
+SOCKET="$SOCKET_DIR/nexus.sock"
+SESSION=op-auth
+
+tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
+tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op signin --account my.1password.com" Enter
+tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op vault list" Enter
+tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200
+```
+
+## Guardrails
+
+- Never paste secrets into logs, chat, or code.
+- Prefer `op run` / `op inject` over writing secrets to disk.
+- If sign-in without app integration is needed, use `op account add`.
+- If a command returns "account is not signed in", re-run `op signin` and authorize in the app.

package/skills/1password/docs/setup.md

@@ -0,0 +1,85 @@
+# 1Password CLI Setup
+
+Use this guide to install and configure the 1Password CLI (`op`) with desktop
+app integration.
+
+## What it enables
+
+- Secure secret storage without writing secrets to disk.
+- Secret injection into config files and environment variables.
+- Secure command execution with temporary secrets in env.
+- Multi-account switching for personal/work vaults.
+
+## Prerequisites
+
+- Active 1Password account and desktop app installed.
+- A package manager (Homebrew on macOS, or equivalent).
+
+## Install the CLI
+
+### macOS (Homebrew)
+
+```bash
+brew install 1password-cli
+op --version
+```
+
+### Other platforms
+
+Follow the official install steps in `references/get-started.md`.
+
+## Enable desktop app integration (manual)
+
+1. Open the 1Password desktop app and unlock it.
+2. Go to Settings:
+   - macOS: 1Password -> Settings -> Developer
+   - Windows: Settings -> Developer (requires Windows Hello)
+   - Linux: Settings -> Security, then Developer
+3. Enable "Integrate with 1Password CLI".
+4. Keep the desktop app unlocked while you run `op` commands.
+
+## Sign in and verify
+
+```bash
+op signin
+op whoami
+op vault list
+```
+
+If you have multiple accounts, set a default:
+
+```bash
+export OP_ACCOUNT="work.1password.com"
+op whoami --account work.1password.com
+```
+
+## Automation helper
+
+This script checks whether `op` is installed and signed in.
+
+```bash
+#!/bin/bash
+
+if ! command -v op >/dev/null 2>&1; then
+  echo "1Password CLI not installed"
+  echo "Run: brew install 1password-cli"
+  exit 1
+fi
+
+if ! op whoami >/dev/null 2>&1; then
+  echo "Not signed in to 1Password"
+  echo "Run: op signin (authorize in the desktop app)"
+  exit 1
+fi
+
+echo "1Password CLI ready"
+op whoami
+```
+
+## Testing checklist
+
+- Install works: `op --version`
+- App integration enabled (manual check)
+- Sign-in works: `op signin`
+- Account info: `op whoami`
+- Vault access: `op vault list`

package/skills/1password/docs/troubleshooting.md

@@ -0,0 +1,63 @@
+# 1Password CLI Troubleshooting
+
+## CLI not signed in
+
+**Symptom:** `op` commands return "not signed in".
+
+**Cause:** Desktop app integration not enabled, app locked, or terminal not authorized.
+
+**Fix:**
+
+```bash
+# Ensure the 1Password desktop app is open and unlocked
+op signin
+op whoami
+```
+
+## Desktop app integration not enabled
+
+**Symptom:** `op signin` prompts for account details instead of using the app.
+
+**Cause:** "Integrate with 1Password CLI" is disabled in the desktop app.
+
+**Fix:**
+
+1. Open 1Password desktop app.
+2. Settings -> Developer.
+3. Enable "Integrate with 1Password CLI".
+4. Run `op signin` again.
+
+## Repeated auth prompts in automation
+
+**Symptom:** Every `op` command asks for authorization.
+
+**Cause:** Each command runs in a fresh TTY and loses the auth session.
+
+**Fix:** Run multiple `op` commands in the same session (tmux is recommended).
+
+```bash
+SOCKET_DIR="${NEXUS_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/nexus-tmux-sockets}"
+mkdir -p "$SOCKET_DIR"
+SOCKET="$SOCKET_DIR/nexus.sock"
+SESSION=op-auth
+
+tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
+tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op signin" Enter
+tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op vault list" Enter
+tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200
+```
+
+## Multi-account confusion
+
+**Symptom:** Vaults from the wrong account appear.
+
+**Cause:** Multiple accounts are signed in; default account is not set.
+
+**Fix:**
+
+```bash
+op account list
+op signin --account work.1password.com
+export OP_ACCOUNT="work.1password.com"
+op whoami
+```

package/skills/1password/references/cli-examples.md

@@ -0,0 +1,29 @@
+# op CLI examples (from op help)
+
+## Sign in
+
+- `op signin`
+- `op signin --account <shorthand|signin-address|account-id|user-id>`
+
+## Read
+
+- `op read op://app-prod/db/password`
+- `op read "op://app-prod/db/one-time password?attribute=otp"`
+- `op read "op://app-prod/ssh key/private key?ssh-format=openssh"`
+- `op read --out-file ./key.pem op://app-prod/server/ssh/key.pem`
+
+## Run
+
+- `export DB_PASSWORD="op://app-prod/db/password"`
+- `op run --no-masking -- printenv DB_PASSWORD`
+- `op run --env-file="./.env" -- printenv DB_PASSWORD`
+
+## Inject
+
+- `echo "db_password: {{ op://app-prod/db/password }}" | op inject`
+- `op inject -i config.yml.tpl -o config.yml`
+
+## Whoami / accounts
+
+- `op whoami`
+- `op account list`

package/skills/1password/references/get-started.md

@@ -0,0 +1,17 @@
+# 1Password CLI get-started (summary)
+
+- Works on macOS, Windows, and Linux.
+  - macOS/Linux shells: bash, zsh, sh, fish.
+  - Windows shell: PowerShell.
+- Requires a 1Password subscription and the desktop app to use app integration.
+- macOS requirement: Big Sur 11.0.0 or later.
+- Linux app integration requires PolKit + an auth agent.
+- Install the CLI per the official doc for your OS.
+- Enable desktop app integration in the 1Password app:
+  - Open and unlock the app, then select your account/collection.
+  - macOS: Settings > Developer > Integrate with 1Password CLI (Touch ID optional).
+  - Windows: turn on Windows Hello, then Settings > Developer > Integrate.
+  - Linux: Settings > Security > Unlock using system authentication, then Settings > Developer > Integrate.
+- After integration, run any command to sign in (example in docs: `op vault list`).
+- If multiple accounts: use `op signin` to pick one, or `--account` / `OP_ACCOUNT`.
+- For non-integration auth, use `op account add`.