@intent-systems/nexus 2026.1.5-3

package/docs/RELEASING.md

@@ -0,0 +1,69 @@
+---
+summary: "Step-by-step release checklist for npm + macOS app"
+read_when:
+  - Cutting a new npm release
+  - Cutting a new macOS app release
+  - Verifying metadata before publishing
+---
+
+# Release Checklist (npm + macOS)
+
+Use `pnpm` (Node 22+) from the repo root. Keep the working tree clean before tagging/publishing.
+
+1) **Version & metadata**
+- [ ] Bump `package.json` version (e.g., `1.1.0`).
+- [ ] Update CLI/version strings: `src/cli/program.ts` and the Baileys user agent in `src/provider-web.ts`.
+- [ ] Confirm package metadata (name, description, repository, keywords, license) and `bin` map points to `dist/index.js` for `nexus`.
+- [ ] If dependencies changed, run `pnpm install` so `pnpm-lock.yaml` is current.
+
+2) **Build & artifacts**
+- [ ] If A2UI inputs changed, run `pnpm canvas:a2ui:bundle` and commit any updated `src/canvas-host/a2ui/a2ui.bundle.js`.
+- [ ] `pnpm run build` (regenerates `dist/`).
+- [ ] Optional: `npm pack --pack-destination /tmp` after the build; inspect the tarball contents and keep it handy for the GitHub release (do **not** commit it).
+
+3) **Changelog & docs**
+- [ ] Update `CHANGELOG.md` with user-facing highlights (create the file if missing); keep entries strictly descending by version.
+- [ ] Ensure README examples/flags match current CLI behavior (notably new commands or options).
+
+4) **Validation**
+- [ ] `pnpm lint`
+- [ ] `pnpm test` (or `pnpm test:coverage` if you need coverage output)
+- [ ] `pnpm run build` (last sanity check after tests)
+- [ ] `pnpm release:check` (verifies npm pack contents)
+- [ ] `pnpm test:install:smoke` (Docker install smoke test; required before release)
+  - If the immediate previous npm release is known broken, set `NEXUS_INSTALL_SMOKE_PREVIOUS=<last-good-version>` or `NEXUS_INSTALL_SMOKE_SKIP_PREVIOUS=1` for the preinstall step.
+- [ ] (Optional) Installer E2E (Docker, runs `curl -fsSL https://nexus.bot/install.sh | bash`, onboards, then runs real tool calls):
+  - `pnpm test:install:e2e:openai` (requires `OPENAI_API_KEY`)
+  - `pnpm test:install:e2e:anthropic` (requires `ANTHROPIC_API_KEY`)
+- [ ] (Optional) Spot-check the web gateway if your changes affect send/receive paths.
+
+5) **macOS app (Sparkle)**
+- [ ] Build + sign the macOS app, then zip it for distribution.
+- [ ] Generate the Sparkle appcast (HTML notes via `scripts/make_appcast.sh`) and update `appcast.xml`.
+- [ ] Keep the app zip (and optional dSYM zip) ready to attach to the GitHub release.
+- [ ] Follow [`docs/mac/release.md`](https://docs.nexus.bot/mac/release) for the exact commands and required env vars.
+  - `APP_BUILD` must be numeric + monotonic (no `-beta`) so Sparkle compares versions correctly.
+  - If notarizing, use the `nexus-notary` keychain profile created from App Store Connect API env vars (see [`docs/mac/release.md`](https://docs.nexus.bot/mac/release)).
+
+6) **Publish (npm)**
+- [ ] Confirm git status is clean; commit and push as needed.
+- [ ] `npm login` (verify 2FA) if needed.
+- [ ] `npm publish --access public` (use `--tag beta` for pre-releases).
+- [ ] Verify the registry: `npm view nexus version` and `npx -y nexus@X.Y.Z --version` (or `--help`).
+
+### Troubleshooting (notes from 2.0.0-beta2 release)
+- **npm pack/publish hangs or produces huge tarball**: the macOS app bundle in `dist/Nexus.app` (and release zips) get swept into the package. Fix by whitelisting publish contents via `package.json` `files` (include dist subdirs, docs, skills; exclude app bundles). Confirm with `npm pack --dry-run` that `dist/Nexus.app` is not listed.
+- **npm auth web loop for dist-tags**: use legacy auth to get an OTP prompt:
+  - `NPM_CONFIG_AUTH_TYPE=legacy npm dist-tag add nexus@X.Y.Z latest`
+- **`npx` verification fails with `ECOMPROMISED: Lock compromised`**: retry with a fresh cache:
+  - `NPM_CONFIG_CACHE=/tmp/npm-cache-$(date +%s) npx -y nexus@X.Y.Z --version`
+- **Tag needs repointing after a late fix**: force-update and push the tag, then ensure the GitHub release assets still match:
+  - `git tag -f vX.Y.Z && git push -f origin vX.Y.Z`
+
+7) **GitHub release + appcast**
+- [ ] Tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z` (or `git push --tags`).
+- [ ] Create/refresh the GitHub release for `vX.Y.Z` with **title `nexus X.Y.Z`** (not just the tag); body should inline the product-facing bullets from the changelog (no bare links) **and must not repeat the title inside the body**.
+- [ ] Attach artifacts: `npm pack` tarball (optional), `Nexus-X.Y.Z.zip`, and `Nexus-X.Y.Z.dSYM.zip` (if generated).
+- [ ] Commit the updated `appcast.xml` and push it (Sparkle feeds from main).
+- [ ] From a clean temp directory (no `package.json`), run `npx -y nexus@X.Y.Z send --help` to confirm install/CLI entrypoints work.
+- [ ] Announce/share release notes.

package/docs/_config.yml

@@ -0,0 +1,53 @@
+title: "NEXUS Docs"
+description: "A TypeScript/Node gateway + macOS/iOS/Android companions for WhatsApp (web) and Telegram (bot)."
+markdown: kramdown
+highlighter: rouge
+
+# Keep GitHub Pages' default page URLs (e.g. /gateway.html). Many docs links
+# are written as relative *.md links and are rewritten during the build.
+
+plugins:
+  - jekyll-relative-links
+
+relative_links:
+  enabled: true
+  collections: true
+
+defaults:
+  - scope:
+      path: ""
+    values:
+      layout: default
+
+nav:
+  - title: "Home"
+    url: "/"
+  - title: "Nexus Setup"
+    url: "/nexus.html"
+  - title: "Gateway"
+    url: "/gateway.html"
+  - title: "Remote"
+    url: "/remote.html"
+  - title: "Discovery"
+    url: "/discovery.html"
+  - title: "Configuration"
+    url: "/configuration.html"
+  - title: "WebChat"
+    url: "/webchat.html"
+  - title: "macOS App"
+    url: "/macos.html"
+  - title: "iOS App"
+    url: "/ios.html"
+  - title: "Android App"
+    url: "/android.html"
+  - title: "Telegram"
+    url: "/telegram.html"
+  - title: "Security"
+    url: "/security.html"
+  - title: "Troubleshooting"
+    url: "/troubleshooting.html"
+
+kramdown:
+  input: GFM
+  hard_wrap: false
+  syntax_highlighter: rouge

package/docs/_layouts/default.html

@@ -0,0 +1,145 @@
+<!doctype html>
+<html lang="en" data-theme="auto">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="color-scheme" content="light dark" />
+    <title>
+      {% if page.url == "/" %}{{ site.title }}{% else %}{{ page.title | default: page.path | split: "/" | last | replace: ".md", "" }} · {{ site.title }}{% endif %}
+    </title>
+
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Pixelify+Sans:wght@400..700&family=Fragment+Mono:ital,wght@0,400;0,700;1,400;1,700&display=swap"
+      rel="stylesheet"
+    />
+    <script>
+      (() => {
+        try {
+          const stored = localStorage.getItem("nexus:theme");
+          if (stored === "light" || stored === "dark") document.documentElement.dataset.theme = stored;
+        } catch {
+          // ignore
+        }
+      })();
+    </script>
+    <link rel="stylesheet" href="{{ "/assets/terminal.css" | relative_url }}" />
+    <link rel="stylesheet" href="{{ "/assets/markdown.css" | relative_url }}" />
+    <script defer src="{{ "/assets/theme.js" | relative_url }}"></script>
+  </head>
+
+  <body>
+    <a class="skip-link" href="#content">Skip to content</a>
+
+    <header class="shell">
+      <div class="shell__frame" role="banner">
+        <div class="shell__titlebar">
+          <div class="brand" aria-label="NEXUS docs terminal">
+            <img
+              class="brand__logo"
+              src="{{ "/assets/pixel-lobster.svg" | relative_url }}"
+              alt=""
+              width="40"
+              height="40"
+              decoding="async"
+            />
+            <div class="brand__text">
+              <div class="brand__name">NEXUS</div>
+              <div class="brand__hint">docs // lobster terminal</div>
+            </div>
+          </div>
+
+          <div class="titlebar__actions">
+            <a class="titlebar__cta" href="https://github.com/nexus/nexus">
+              <span class="titlebar__cta-label">GitHub</span>
+              <span class="titlebar__cta-meta">repo</span>
+            </a>
+            <a class="titlebar__cta titlebar__cta--accent" href="https://github.com/nexus/nexus/releases/latest">
+              <span class="titlebar__cta-label">Download</span>
+              <span class="titlebar__cta-meta">latest</span>
+            </a>
+          </div>
+        </div>
+
+        <div class="shell__nav" aria-label="Primary">
+          <nav class="nav">
+            {% assign nav = site.nav | default: empty %}
+            {% for item in nav %}
+              {% assign item_url = item.url | relative_url %}
+              <a class="nav__link" href="{{ item_url }}">
+                <span class="nav__chev">›</span>{{ item.title }}
+              </a>
+            {% endfor %}
+          </nav>
+
+          <div class="shell__status" aria-hidden="true">
+            <span class="status__dot"></span>
+            <span class="status__text">
+              {% if page.url == "/" %}
+                ready
+              {% else %}
+                viewing: {{ page.path }}
+              {% endif %}
+            </span>
+          </div>
+        </div>
+      </div>
+    </header>
+
+    <main id="content" class="content" role="main">
+      <div class="terminal">
+        <div class="terminal__prompt" aria-hidden="true">
+          <span class="prompt__user">nexus</span>@<span class="prompt__host">nexus</span>:<span class="prompt__path">~/docs</span>$<span class="prompt__cmd">
+            {% if page.url == "/" %}cat index.md{% else %}less {{ page.path }}{% endif %}
+          </span>
+        </div>
+
+        {% if page.summary %}
+          <p class="terminal__summary">{{ page.summary }}</p>
+        {% endif %}
+
+        {% if page.read_when %}
+          <details class="terminal__meta">
+            <summary>Read when…</summary>
+            <ul>
+              {% for hint in page.read_when %}
+                <li>{{ hint }}</li>
+              {% endfor %}
+            </ul>
+          </details>
+        {% endif %}
+
+        <article class="markdown">
+          {{ content }}
+        </article>
+
+        <footer class="terminal__footer" role="contentinfo">
+          <div class="footer__line">
+            <span class="footer__sig">nexus.ai</span>
+            <span class="footer__sep">·</span>
+            <a href="https://github.com/nexus/nexus">source</a>
+            <span class="footer__sep">·</span>
+            <a href="https://github.com/nexus/nexus/releases">releases</a>
+          </div>
+          <div class="footer__hint" aria-hidden="true">
+            tip: press <kbd>F2</kbd> (Mac: <kbd>fn</kbd>+<kbd>F2</kbd>) to flip
+            the universe
+          </div>
+          <div class="footer__actions">
+            <button
+              class="theme-toggle"
+              type="button"
+              data-theme-toggle
+              aria-label="Toggle theme (F2; on Mac: fn+F2)"
+              aria-pressed="false"
+            >
+              <span class="theme-toggle__key">F2</span>
+              <span class="theme-toggle__label" data-theme-label>theme</span>
+            </button>
+          </div>
+	        </footer>
+	      </div>
+	    </main>
+	  </body>
+</html>

package/docs/agent-assisted-install.md

@@ -0,0 +1,95 @@
+---
+title: Agent-assisted install (macOS)
+---
+
+# Agent-assisted install (macOS)
+
+This is a copy/paste guide you can send to a friend/family member to get Nexus running quickly on macOS.
+
+## What you’ll need
+
+- A Mac
+- Admin access (you may be prompted for your password)
+- An AI billing method:
+  - **OpenAI Codex / ChatGPT** (recommended if you have it), or
+  - **Anthropic API key** (pay-as-you-go)
+
+> Note: Having the Claude desktop/Code app installed does **not** necessarily mean you have API billing enabled.
+
+## Step 1 — Install Node.js (if you don’t have it)
+
+In Terminal:
+
+```bash
+node -v
+```
+
+If that fails, install Node with Homebrew:
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+brew install node
+```
+
+## Step 2 — Install Nexus CLI
+
+```bash
+npm install -g nexus
+```
+
+## Step 3 — Initialize your Nexus workspace
+
+```bash
+nexus init
+```
+
+This creates:
+- `~/nexus/home` (your workspace)
+- `~/nexus/state` (local state, sessions, credentials)
+
+## Step 4 — QuickStart onboarding (local gateway)
+
+```bash
+nexus onboard --quickstart
+```
+
+This will:
+- pick safe defaults (local loopback gateway)
+- try to auto-detect existing credentials (ex: OpenAI Codex)
+- start the gateway and show the Control UI URL
+
+If Nexus tells you billing/auth is missing, run:
+
+```bash
+nexus onboard
+```
+
+and pick an auth option (OpenAI Codex OAuth, or paste an Anthropic API key).
+
+## Step 5 — Name your Nexus (first run ritual)
+
+Open your workspace folder:
+
+```bash
+open ~/nexus/home
+```
+
+Identity files live under `~/nexus/state/`:
+- `state/agents/{agent}/identity/IDENTITY.md` (what the agent is called)
+- `state/user/identity/PROFILE.md` (who you are)
+- `state/agents/{agent}/identity/SOUL.md` (tone/boundaries)
+- `state/nexus/onboarding/BOOTSTRAP.md` (one-time ritual prompt)
+
+If `BOOTSTRAP.md` exists, you can either:
+- **Chat with Nexus** and let it fill these in, or
+- edit `IDENTITY.md` and `PROFILE.md` manually.
+
+## Optional — iMessage “Nexus bot” (later)
+
+To message Nexus from your phone via iMessage, you’ll eventually:
+- create a dedicated Apple ID (ex: `nexus.bot@icloud.com`)
+- sign into Messages.app with that Apple ID on the Mac running Nexus
+- enable the iMessage provider in Nexus and grant macOS permissions
+
+We intentionally recommend doing this **after** the first “wow moment”.
+

package/docs/agent-loop.md

@@ -0,0 +1,61 @@
+---
+summary: "Agent loop lifecycle, streams, and wait semantics"
+read_when:
+  - You need an exact walkthrough of the agent loop or lifecycle events
+---
+# Agent Loop (Nexus)
+
+Short, exact flow of one agent run. Source of truth: current code in `src/`.
+
+## Entry points
+- Gateway RPC: `agent` and `agent.wait` in `src/gateway/server-methods/agent.ts`.
+- CLI: `agentCommand` in `src/commands/agent.ts`.
+
+## High-level flow
+1) `agent` RPC validates params, resolves session (sessionKey/sessionId), persists session metadata, returns `{ runId, acceptedAt }` immediately.
+2) `agentCommand` runs the agent:
+   - resolves model + thinking/verbose defaults
+   - loads skills snapshot
+   - calls `runEmbeddedPiAgent` (pi-agent-core runtime)
+   - emits **lifecycle end/error** if the embedded loop does not emit one
+3) `runEmbeddedPiAgent`:
+   - builds `AgentSession` and subscribes to pi events
+   - streams assistant deltas + tool events
+   - enforces timeout -> aborts run if exceeded
+   - returns payloads + usage metadata
+4) `subscribeEmbeddedPiSession` bridges pi-agent-core events to Nexus `agent` stream:
+   - tool events => `stream: "tool"`
+   - assistant deltas => `stream: "assistant"`
+   - lifecycle events => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`)
+5) `agent.wait` uses `waitForAgentJob`:
+   - waits for **lifecycle end/error** for `runId`
+   - returns `{ status: ok|error|timeout, startedAt, endedAt, error? }`
+
+## Event streams (today)
+- `lifecycle`: emitted by `subscribeEmbeddedPiSession` (and as a fallback by `agentCommand`)
+- `assistant`: streamed deltas from pi-agent-core
+- `tool`: streamed tool events from pi-agent-core
+
+## Chat provider handling
+- `createAgentEventHandler` in `src/gateway/server-chat.ts`:
+  - buffers assistant deltas
+  - emits chat `delta` messages
+  - emits chat `final` when **lifecycle end/error** arrives
+
+## Timeouts
+- `agent.wait` default: 30s (just the wait). `timeoutMs` param overrides.
+- Agent runtime: `agent.timeoutSeconds` default 600s; enforced in `runEmbeddedPiAgent` abort timer.
+
+## Where things can end early
+- Agent timeout (abort)
+- AbortSignal (cancel)
+- Gateway disconnect or RPC timeout
+- `agent.wait` timeout (wait-only, does not stop agent)
+
+## Files
+- `src/gateway/server-methods/agent.ts`
+- `src/gateway/server-methods/agent-job.ts`
+- `src/commands/agent.ts`
+- `src/agents/pi-embedded-runner.ts`
+- `src/agents/pi-embedded-subscribe.ts`
+- `src/gateway/server-chat.ts`

package/docs/agent-send.md

@@ -0,0 +1,21 @@
+---
+summary: "Design notes for a direct `nexus agent` CLI subcommand without WhatsApp delivery"
+read_when:
+  - Adding or modifying the agent CLI entrypoint
+---
+# `nexus agent` (direct-to-agent invocation)
+
+`nexus agent` lets you talk to the **embedded** agent runtime directly (no chat send unless you opt in), while reusing the same session store and thinking/verbose persistence as inbound auto-replies.
+
+## Behavior
+- Required: `--message <text>`
+- Session selection:
+  - If `--session-id` is given, reuse it.
+  - Else if `--to <e164>` is given, derive the session key from `session.scope` (direct chats collapse to `main`, or `global` when scope is global).
+- Runs the embedded Pi agent (configured via `agent`).
+- Thinking/verbose:
+  - Flags `--thinking <off|minimal|low|medium|high>` and `--verbose <on|off>` persist into the session store.
+- Output:
+  - Default: prints text (and `MEDIA:<url>` lines) to stdout.
+  - `--json`: prints structured payloads + meta.
+- Optional: `--deliver` sends the reply back to the selected provider (`whatsapp`, `telegram`, `discord`, `signal`, `imessage`).

package/docs/agent.md

@@ -0,0 +1,108 @@
+---
+summary: "Agent runtime (embedded p-mono), workspace contract, and session bootstrap"
+read_when:
+  - Changing agent runtime, workspace bootstrap, or session behavior
+---
+# Agent Runtime 🤖
+
+NEXUS runs a single embedded agent runtime derived from **p-mono** (internal name: **p**).
+
+## Workspace (required)
+
+NEXUS uses a single agent workspace directory (`agent.workspace`) as the agent’s **only** working directory (`cwd`) for tools and context.
+
+Recommended: use `nexus init` to create `~/nexus/state/nexus/config.json` if missing and initialize the workspace files.
+
+If `agent.sandbox` is enabled, non-main sessions can override this with
+per-session workspaces under `agent.sandbox.workspaceRoot` (see
+[`docs/configuration.md`](https://docs.nexus.bot/configuration)).
+
+## Bootstrap files (injected)
+
+Nexus stores identity and bootstrap files under `~/nexus/state/`:
+- `~/nexus/AGENTS.md` — operating instructions
+- `~/nexus/state/agents/{agent}/identity/SOUL.md` — persona, boundaries, tone
+- `~/nexus/state/agents/{agent}/identity/IDENTITY.md` — agent name/vibe/emoji
+- `~/nexus/state/agents/{agent}/identity/MEMORY.md` — curated memory
+- `~/nexus/state/user/identity/PROFILE.md` — user profile + preferred address
+- `~/nexus/state/nexus/onboarding/BOOTSTRAP.md` — first-run ritual prompt
+
+`nexus status` is the entry point and will surface bootstrap guidance when identity is missing.
+
+Large bootstrap files are truncated when injected. Control the per-file limit with `agent.bootstrapMaxChars` (default: 20000).
+
+To disable bootstrap file creation entirely (for pre-seeded workspaces), set:
+
+```json5
+{ agent: { skipBootstrap: true } }
+```
+
+## Built-in tools (internal)
+
+p’s embedded core tools (read/bash/edit/write and related internals) are defined in code and always available. `TOOLS.md` does **not** control which tools exist; it’s guidance for how *you* want them used.
+
+## Skills
+
+Nexus loads skills from three locations (higher wins on name conflict):
+- Project: `<projectRoot>/skills`
+- Home: `~/nexus/home/skills`
+- Bundled baseline (shipped with the install)
+
+Skills can be gated by config/env (see `skills` in [`docs/configuration.md`](https://docs.nexus.bot/configuration)).
+
+## p-mono integration
+
+Nexus reuses pieces of the p-mono codebase (models/tools), but **session management, discovery, and tool wiring are Nexus-owned**.
+
+- No p-coding agent runtime.
+- No `~/.pi/agent` or `<workspace>/.pi` settings are consulted.
+
+## Peter @ steipete (only)
+
+Apply these notes **only** when the user is Peter Steinberger at steipete.
+
+- Gateway runs on the **Mac Studio in London**.
+- Primary work computer: **MacBook Pro**.
+- Peter travels between **Vienna** and **London**; there are two networks bridged via **Tailscale**.
+- For debugging, connect to the Mac Studio (London) or MacBook Pro (primary).
+- There is also an **M1 MacBook Pro** on the Vienna tailnet you can use to access the Vienna network.
+- Nodes can be accessed via the `nexus` binary (`pnpm nexus` in `~/Projects/nexus`).
+- See also `skills/nexus*` for node/browser/canvas/cron usage.
+
+## Sessions
+
+Session transcripts are stored as JSONL at:
+- `~/nexus/state/agents/<agentId>/sessions/<SessionId>.jsonl`
+
+The session ID is stable and chosen by NEXUS.
+Legacy Pi/Tau session folders are **not** read.
+
+## Steering while streaming
+
+When queue mode is `steer`, inbound messages are injected into the current run.
+The queue is checked **after each tool call**; if a queued message is present,
+remaining tool calls from the current assistant message are skipped (error tool
+results with "Skipped due to queued user message."), then the queued user
+message is injected before the next assistant response.
+
+When queue mode is `followup` or `collect`, inbound messages are held until the
+current turn ends, then a new agent turn starts with the queued payloads. See
+[`docs/queue.md`](https://docs.nexus.bot/queue) for mode + debounce/cap behavior.
+
+Block streaming sends completed assistant blocks as soon as they finish; disable
+via `agent.blockStreamingDefault: "off"` if you only want the final response.
+Tune the boundary via `agent.blockStreamingBreak` (`text_end` vs `message_end`; defaults to text_end).
+Control soft block chunking with `agent.blockStreamingChunk` (defaults to
+800–1200 chars; prefers paragraph breaks, then newlines; sentences last).
+Verbose tool summaries are emitted at tool start (no debounce); Control UI
+streams tool output via agent events when available.
+
+## Configuration (minimal)
+
+At minimum, set:
+- `agent.workspace`
+- `whatsapp.allowFrom` (strongly recommended)
+
+---
+
+*Next: [Group Chats](https://docs.nexus.bot/group-messages)* 🦞