@intent-systems/nexus 2026.1.5-3

package/docs/session-ingestion.md

@@ -0,0 +1,119 @@
+---
+summary: "How Nexus ingests session transcripts from NexusBot and Cursor (storage locations + adapter strategy)"
+read_when:
+  - You want Nexus to index/review sessions across harnesses
+  - You are building a Cursor/NexusBot session adapter
+---
+
+# Session ingestion (NexusBot + Cursor → Nexus)
+
+Nexus wants a **harness-agnostic session/thread registry** that can index “work that happened” regardless of where it was initiated.
+
+This doc records where sessions live today for:
+- NexusBot / Nexus gateway runs (**JSONL transcripts on disk**)
+- Cursor agent chats (**JSON stored inside VSCode-style SQLite DBs**)
+
+## Nexus/NexusBot gateway sessions (gateway-owned)
+
+### Session directory structure (NEW FORMAT)
+
+As of 2026-01, Nexus uses an **agent-grouped, per-session directory** format:
+
+Canonical default:
+
+```
+~/nexus/state/agents/<agentId>/sessions/<sessionKey>/
+├── session.json      # Metadata (created, updated, surface, model, etc.)
+├── history.jsonl     # Current active turns
+├── archives/         # Compacted history files (preserved forever)
+│   ├── 001.jsonl     # Full history before 1st compaction
+│   ├── 002.jsonl     # Full history before 2nd compaction
+│   └── ...
+└── summary.md        # Current context summary (post-compaction)
+```
+
+This format enables:
+- Agent-grouped: All sessions for an agent live together
+- Per-session isolation: Each session is self-contained
+- Archive preservation: Searchable history even after compaction
+- Cursor-style dynamic context discovery
+
+### Legacy session formats (migration sources)
+
+Old flat format (sessions.json + JSONL transcripts):
+
+```
+~/.nexus/agents/<agentId>/sessions/sessions.json
+~/.nexus/agents/<agentId>/sessions/<sessionId>.jsonl
+~/.nexus/sessions/<sessionId>.jsonl
+```
+
+Migration from old format happens automatically on first access.
+
+Notes:
+- Transcript format can vary by runtime; some lines are `{ role, content, ... }`, some may be wrapped.
+- When ingesting, prefer “be liberal”: parse each JSON line; if it has a `.message` field, unwrap it, otherwise treat the object as the message.
+
+## Cursor sessions (IDE-owned)
+
+Cursor (VSCode-based) persists AI chat state in SQLite DBs.
+
+### Per-workspace DBs
+
+Cursor stores one SQLite DB per workspace folder:
+
+```
+~/Library/Application Support/Cursor/User/workspaceStorage/<hash>/state.vscdb
+```
+
+`workspace.json` maps the `<hash>` folder back to the workspace path:
+
+```
+~/Library/Application Support/Cursor/User/workspaceStorage/<hash>/workspace.json
+```
+
+Example:
+- `workspace.json` contains `{"folder":"file:///Users/tyler/Desktop/projects"}`
+
+### Where the actual AI Chat transcript lives
+
+In the per-workspace `state.vscdb`, the full “AI Chat” data is stored as JSON text under:
+
+- `ItemTable.key = "workbench.panel.aichat.view.aichat.chatdata"`
+
+That JSON includes:
+- `tabs[]` with:
+  - `tabId`
+  - `chatTitle`
+  - `bubbles[]` (messages + context selections)
+
+Bubble notes (observed):
+- User bubbles: `type: "user"`, `messageType: 2`
+  - content often lives in `initText` / `richText` (Lexical JSON), not `rawText`
+- Assistant bubbles: `type: "assistant"`, `messageType: 3`
+  - content lives in `text` / `rawText`
+
+Related (useful but not required for ingestion):
+- `ItemTable.key = "aiService.prompts"`
+- `ItemTable.key = "aiService.generations"`
+
+## Adapter strategy (90% equivalent quickly)
+
+### Goal
+
+Build an adapter that:
+- Scans NexusBot transcripts from state dir
+- Extracts Cursor transcripts from `state.vscdb`
+- Writes a Nexus-owned index so sessions are searchable/reviewable
+
+### Minimal output
+
+- `index.json` (a lightweight catalog)
+- Cursor tabs exported as JSONL for easy reading/search
+- NexusBot sessions referenced by path (optionally copied)
+
+## Implementation
+
+See `nexus sessions-ingest --help` (Nexus fork) once implemented.
+
+

package/docs/session-tool.md

@@ -0,0 +1,154 @@
+---
+summary: "Agent session tools for listing sessions, fetching history, and sending cross-session messages"
+read_when:
+  - Adding or modifying session tools
+---
+
+# Session Tools
+
+Goal: small, hard-to-misuse tool set so agents can list sessions, fetch history, and send to another session.
+
+## Tool Names
+- `sessions_list`
+- `sessions_history`
+- `sessions_send`
+- `sessions_spawn`
+
+## Key Model
+- Main direct chat bucket is always the literal key `"main"`.
+- Group chats use `<provider>:group:<id>` or `<provider>:channel:<id>`.
+- Cron jobs use `cron:<job.id>`.
+- Hooks use `hook:<uuid>` unless explicitly set.
+- Node bridge uses `node-<nodeId>` unless explicitly set.
+
+`global` and `unknown` are internal-only and never listed. If `session.scope = "global"`, we alias it to `main` for all tools so callers never see `global`.
+
+## sessions_list
+List sessions as an array of rows.
+
+Parameters:
+- `kinds?: string[]` filter: any of `"main" | "group" | "cron" | "hook" | "node" | "other"`
+- `limit?: number` max rows (default: server default, clamp e.g. 200)
+- `activeMinutes?: number` only sessions updated within N minutes
+- `messageLimit?: number` 0 = no messages (default 0); >0 = include last N messages
+
+Behavior:
+- `messageLimit > 0` fetches `chat.history` per session and includes the last N messages.
+- Tool results are filtered out in list output; use `sessions_history` for tool messages.
+- When running in a **sandboxed** agent session, session tools default to **spawned-only visibility** (see below).
+
+Row shape (JSON):
+- `key`: session key (string)
+- `kind`: `main | group | cron | hook | node | other`
+- `provider`: `whatsapp | telegram | discord | signal | imessage | webchat | internal | unknown`
+- `displayName` (group display label if available)
+- `updatedAt` (ms)
+- `sessionId`
+- `model`, `contextTokens`, `totalTokens`
+- `thinkingLevel`, `verboseLevel`, `systemSent`, `abortedLastRun`
+- `sendPolicy` (session override if set)
+- `lastProvider`, `lastTo`
+- `transcriptPath` (best-effort path derived from store dir + sessionId)
+- `messages?` (only when `messageLimit > 0`)
+
+## sessions_history
+Fetch transcript for one session.
+
+Parameters:
+- `sessionKey` (required)
+- `limit?: number` max messages (server clamps)
+- `includeTools?: boolean` (default false)
+
+Behavior:
+- `includeTools=false` filters `role: "toolResult"` messages.
+- Returns messages array in the raw transcript format.
+
+## sessions_send
+Send a message into another session.
+
+Parameters:
+- `sessionKey` (required)
+- `message` (required)
+- `timeoutSeconds?: number` (default >0; 0 = fire-and-forget)
+
+Behavior:
+- `timeoutSeconds = 0`: enqueue and return `{ runId, status: "accepted" }`.
+- `timeoutSeconds > 0`: wait up to N seconds for completion, then return `{ runId, status: "ok", reply }`.
+- If wait times out: `{ runId, status: "timeout", error }`. Run continues; call `sessions_history` later.
+- If the run fails: `{ runId, status: "error", error }`.
+- Waits via gateway `agent.wait` (server-side) so reconnects don't drop the wait.
+- Agent-to-agent message context is injected for the primary run.
+- After the primary run completes, Nexus runs a **reply-back loop**:
+  - Round 2+ alternates between requester and target agents.
+  - Reply exactly `REPLY_SKIP` to stop the ping‑pong.
+  - Max turns is `session.agentToAgent.maxPingPongTurns` (0–5, default 5).
+- Once the loop ends, Nexus runs the **agent‑to‑agent announce step** (target agent only):
+  - Reply exactly `ANNOUNCE_SKIP` to stay silent.
+  - Any other reply is sent to the target provider.
+  - Announce step includes the original request + round‑1 reply + latest ping‑pong reply.
+
+## Provider Field
+- For groups, `provider` is the provider recorded on the session entry.
+- For direct chats, `provider` maps from `lastProvider`.
+- For cron/hook/node, `provider` is `internal`.
+- If missing, `provider` is `unknown`.
+
+## Security / Send Policy
+Policy-based blocking by provider/chat type (not per session id).
+
+```json
+{
+  "session": {
+    "sendPolicy": {
+      "rules": [
+        {
+          "match": { "provider": "discord", "chatType": "group" },
+          "action": "deny"
+        }
+      ],
+      "default": "allow"
+    }
+  }
+}
+```
+
+Runtime override (per session entry):
+- `sendPolicy: "allow" | "deny"` (unset = inherit config)
+- Settable via `sessions.patch` or owner-only `/send on|off|inherit`.
+
+Enforcement points:
+- `chat.send` / `agent` (gateway)
+- auto-reply delivery logic
+
+## sessions_spawn
+Spawn a sub-agent run in an isolated session and announce the result back to the requester chat provider.
+
+Parameters:
+- `task` (required)
+- `label?` (optional; used for logs/UI)
+- `timeoutSeconds?` (default 0; 0 = fire-and-forget)
+- `cleanup?` (`delete|keep`, default `delete`)
+
+Behavior:
+- Starts a new `subagent:<uuid>` session with `deliver: false`.
+- Sub-agents default to the full tool set **minus session tools** (configurable via `agent.subagents.tools`).
+- Sub-agents are not allowed to call `sessions_spawn` (no sub-agent → sub-agent spawning).
+- After completion (or best-effort wait), Nexus runs a sub-agent **announce step** and posts the result to the requester chat provider.
+- Reply exactly `ANNOUNCE_SKIP` during the announce step to stay silent.
+
+## Sandbox Session Visibility
+
+Sandboxed sessions can use session tools, but by default they only see sessions they spawned via `sessions_spawn`.
+
+Config:
+
+```json5
+{
+  agent: {
+    sandbox: {
+      // default: "spawned"
+      sessionToolsVisibility: "spawned" // or "all"
+    }
+  }
+}
+```

package/docs/session.md

@@ -0,0 +1,85 @@
+---
+summary: "Session management rules, keys, and persistence for chats"
+read_when:
+  - Modifying session handling or storage
+---
+# Session Management
+
+Nexus treats **one direct-chat session per agent** as primary. Direct chats collapse to `agent:<agentId>:<mainKey>` (default `main`), while group/channel chats get their own keys. `session.mainKey` is honored.
+
+## Gateway is the source of truth
+All session state is **owned by the gateway** (the “master” Nexus). UI clients (macOS app, WebChat, etc.) must query the gateway for session lists and token counts instead of reading local files.
+
+- In **remote mode**, the session store you care about lives on the remote gateway host, not your Mac.
+- Token counts shown in UIs come from the gateway’s store fields (`inputTokens`, `outputTokens`, `totalTokens`, `contextTokens`). Clients do not parse JSONL transcripts to “fix up” totals.
+
+## Where state lives
+- On the **gateway host**:
+  - Store file: `~/nexus/state/agents/<agentId>/sessions/sessions.json` (per agent).
+  - Transcripts: `~/nexus/state/agents/<agentId>/sessions/<SessionId>.jsonl` (one file per session id).
+- The store is a map `sessionKey -> { sessionId, updatedAt, ... }`. Deleting entries is safe; they are recreated on demand.
+- Group entries may include `displayName`, `provider`, `subject`, `room`, and `space` to label sessions in UIs.
+- Nexus does **not** read legacy Pi/Tau session folders.
+
+## Mapping transports → session keys
+- Direct chats collapse to the per-agent primary key: `agent:<agentId>:<mainKey>`.
+  - Multiple phone numbers and providers can map to the same agent main key; they act as transports into one conversation.
+- Group chats isolate state: `agent:<agentId>:<provider>:group:<id>` (rooms/channels use `agent:<agentId>:<provider>:channel:<id>`).
+  - Legacy `group:<id>` keys are still recognized for migration.
+- Other sources:
+  - Cron jobs: `cron:<job.id>`
+  - Webhooks: `hook:<uuid>` (unless explicitly set by the hook)
+  - Node bridge runs: `node-<nodeId>`
+
+## Lifecyle
+- Idle expiry: `session.idleMinutes` (default 60). After the timeout a new `sessionId` is minted on the next message.
+- Reset triggers: exact `/new` or `/reset` (plus any extras in `resetTriggers`) start a fresh session id and pass the remainder of the message through. If `/new` or `/reset` is sent alone, Nexus runs a short “hello” greeting turn to confirm the reset.
+- Manual reset: delete specific keys from the store or remove the JSONL transcript; the next message recreates them.
+
+## Send policy (optional)
+Block delivery for specific session types without listing individual ids.
+
+```json5
+{
+  session: {
+    sendPolicy: {
+      rules: [
+        { action: "deny", match: { provider: "discord", chatType: "group" } },
+        { action: "deny", match: { keyPrefix: "cron:" } }
+      ],
+      default: "allow"
+    }
+  }
+}
+```
+
+Runtime override (owner only):
+- `/send on` → allow for this session
+- `/send off` → deny for this session
+- `/send inherit` → clear override and use config rules
+
+## Configuration (optional rename example)
+```json5
+// ~/nexus/state/nexus.json
+{
+  session: {
+    scope: "per-sender",      // keep group keys separate
+    idleMinutes: 120,
+    resetTriggers: ["/new", "/reset"],
+    store: "~/nexus/state/agents/{agentId}/sessions/sessions.json",
+    mainKey: "main",
+  }
+}
+```
+
+## Inspecting
+- `pnpm nexus status` — shows store path and recent sessions.
+- `pnpm nexus sessions --json` — dumps every entry (filter with `--active <minutes>`).
+- `pnpm nexus gateway call sessions.list --params '{}'` — fetch sessions from the running gateway (use `--url`/`--token` for remote gateway access).
+- Send `/status` in chat to see whether the agent is reachable, how much of the session context is used, current thinking/verbose toggles, and when your WhatsApp web creds were last refreshed (helps spot relink needs).
+- Send `/compact` (optional instructions) to summarize older context and free up window space.
+- JSONL transcripts can be opened directly to review full turns.
+
+## Tips
+- Keep the primary key dedicated to 1:1 traffic; let groups keep their own keys.
+- When automating cleanup, delete individual keys instead of the whole store to preserve context elsewhere.

package/docs/sessions.md

@@ -0,0 +1,8 @@
+---
+summary: "Alias for session management docs"
+read_when:
+  - You looked for docs/sessions.md; canonical doc lives in docs/session.md
+---
+# Sessions
+
+Canonical session management docs live in [`docs/session.md`](https://docs.nexus.bot/session).

package/docs/setup.md

@@ -0,0 +1,131 @@
+---
+summary: "Setup guide: keep your Nexus setup tailored while staying up-to-date"
+read_when:
+  - Setting up a new machine
+  - You want “latest + greatest” without breaking your personal setup
+---
+
+# Setup
+
+Last updated: 2026-01-01
+
+## TL;DR
+- **Tailoring lives outside the repo:** `~/nexus` (workspace) + `~/nexus/state/nexus.json` (config).
+- **Stable workflow:** install the macOS app; let it run the bundled Gateway.
+- **Bleeding edge workflow:** run the Gateway yourself via `pnpm gateway:watch`, then point the macOS app at it using **Debug Settings → Gateway → Attach only**.
+
+## Prereqs (from source)
+- Node `>=22`
+- `pnpm`
+- Docker (optional; only for containerized setup/e2e — see [`docs/docker.md`](https://docs.nexus.bot/docker))
+
+## Tailoring strategy (so updates don’t hurt)
+
+If you want “100% tailored to me” *and* easy updates, keep your customization in:
+
+- **Config:** `~/nexus/state/nexus.json` (JSON/JSON5-ish)
+- **Workspace:** `~/nexus` (skills, prompts, memories; make it a private git repo)
+
+Bootstrap once:
+
+```bash
+nexus setup
+```
+
+From inside this repo, use the local CLI entry:
+
+```bash
+pnpm nexus setup
+```
+
+## Stable workflow (macOS app first)
+
+1) Install + launch **Nexus.app** (menu bar).
+2) Complete the onboarding/permissions checklist (TCC prompts).
+3) Ensure Gateway is **Local** and running (the app manages it).
+4) Link surfaces (example: WhatsApp):
+
+```bash
+nexus login
+```
+
+5) Sanity check:
+
+```bash
+nexus health
+```
+
+If onboarding is still WIP/broken on your build:
+- Run `nexus setup`, then `nexus login`, then start the Gateway manually (`nexus gateway`).
+
+## Bleeding edge workflow (Gateway in a terminal)
+
+Goal: work on the TypeScript Gateway, get hot reload, keep the macOS app UI attached.
+
+### 0) (Optional) Run the macOS app from source too
+
+If you also want the macOS app on the bleeding edge:
+
+```bash
+./scripts/restart-mac.sh
+```
+
+### 1) Start the dev Gateway
+
+```bash
+pnpm install
+pnpm gateway:watch
+```
+
+`gateway:watch` runs `src/index.ts gateway --force` and reloads on `src/**/*.ts` changes.
+
+### 2) Point the macOS app at your running Gateway
+
+In **Nexus.app**:
+
+- Connection Mode: **Local**
+- Settings → **Debug Settings** → **Gateway** → enable **Attach only**
+
+This makes the app **only connect to an already-running gateway** and **never spawn** its own.
+
+### 3) Verify
+
+- In-app Gateway status should read **“Using existing gateway …”**
+- Or via CLI:
+
+```bash
+pnpm nexus health
+```
+
+### Common footguns
+- **Attach only enabled, but nothing is running:** app shows “Attach-only enabled; no gateway to attach”.
+- **Wrong port:** Gateway WS defaults to `ws://127.0.0.1:18789`; keep app + CLI on the same port.
+- **Where state lives:**
+  - Credentials: `~/nexus/state/credentials/`
+  - Sessions/logs: `~/nexus/state/sessions/`
+
+## Updating (without wrecking your setup)
+
+- Keep `~/nexus` and `~/nexus/state/` as “your stuff”; don’t put personal prompts/config into the `nexus` repo.
+- Updating source: `git pull` + `pnpm install` (when lockfile changed) + keep using `pnpm gateway:watch`.
+
+## Linux (systemd user service)
+
+Linux installs use a systemd **user** service. By default, systemd stops user
+services on logout/idle, which kills the Gateway. Onboarding attempts to enable
+lingering for you (may prompt for sudo). If it’s still off, run:
+
+```bash
+sudo loginctl enable-linger $USER
+```
+
+For always-on or multi-user servers, consider a **system** service instead of a
+user service (no lingering needed). See [`docs/gateway.md`](https://docs.nexus.bot/gateway) for the systemd notes.
+
+## Related docs
+
+- [`docs/gateway.md`](https://docs.nexus.bot/gateway) (Gateway runbook; flags, supervision, ports)
+- [`docs/configuration.md`](https://docs.nexus.bot/configuration) (config schema + examples)
+- [`docs/discord.md`](https://docs.nexus.bot/discord) and [`docs/telegram.md`](https://docs.nexus.bot/telegram) (reply tags + replyToMode settings)
+- [`docs/nexus.md`](https://docs.nexus.bot/nexus) (personal assistant setup)
+- [`docs/macos.md`](https://docs.nexus.bot/macos) (macOS app behavior; gateway lifecycle + “Attach only”)

package/docs/showcase.md

@@ -0,0 +1,37 @@
+---
+summary: "Real-world showcases of what Nexus can do"
+read_when:
+  - You want inspiration or proof of capability
+---
+# Showcase
+
+Real projects from the community. Highlights from #showcase (Jan 2–5, 2026).
+
+## Automation & real-world outcomes
+- **Visual morning briefing scene** — Scheduled prompt generates a single "scene" image each morning (weather, tasks, date, favorite post/quote) via a Nexus persona, delivered in Telegram. https://x.com/buddyhadry/status/2010005331925954739
+- **Grocery autopilot (Picnic)** — Skill built around an unofficial Picnic API client. Pulls order history, infers preferred brands, maps recipes to cart, completes order in minutes. https://github.com/timkrase/nexus-picnic-skill
+- **Grocery autopilot (Picnic, alt)** — Another Picnic-based skill built via the `picnic-api` package. https://github.com/MRVDH/picnic-api
+- **German rail planning** — Go CLI for Deutsche Bahn; skill picks best connections given time windows and preferences. https://github.com/timkrase/dbrest-cli + https://github.com/timkrase/nexus-skills/tree/main/db-bahn
+- **Accounting intake** — Collect PDFs from email, prep for tax consultant (monthly accounting batch). (No link shared.)
+
+## Knowledge & memory systems
+- **WhatsApp memory vault** — Ingests full exports, transcribes 1k+ voice notes, cross‑checks with git logs, outputs linked MD reports + ongoing indexing. (No link shared.)
+- **Karakeep semantic search** — Sidecar adds vector search to Karakeep bookmarks (Qdrant + OpenAI/Ollama), includes Nexus skill. https://github.com/jamesbrooksco/karakeep-semantic-search
+- **Inside‑Out‑2 style memory** — Separate memory manager app turns session files into memories → beliefs → self model. (No link shared.)
+
+## Voice, docs, and assistants on the phone
+- **Nexusia phone bridge** — Vapi voice assistant ↔ Nexus HTTP bridge; near‑real‑time phone calls. https://github.com/alejandroOPI/nexusia-bridge
+- **Google Docs edit skill** — Rich‑text editing skill built fast with Claude Code. (No link shared.)
+- **OpenRouter transcription skill** — Multi‑lingual audio transcription via OpenRouter (Gemini etc). NexusHub: https://nexushub.com/obviyus/openrouter-transcribe (user/slug link)
+
+## Infrastructure & deployment
+- **Home Assistant OS gateway add‑on** — Nexus gateway running on HA OS (Raspberry Pi), with SSH tunnel support + persistent state in /config. https://github.com/ngutman/nexus-ha-addon
+- **Home Assistant skill** — Control/automate HA via NexusHub. https://nexushub.com/skills/homeassistant
+- **Nix packaging** — Batteries‑included nixified nexus config. https://github.com/joshp123/nix-nexus
+- **CalDAV skill** — khal/vdirsyncer based calendar skill. NexusHub: caldav-calendar → https://nexushub.com/skills/caldav-calendar
+
+## Home + hardware
+- **Roborock integration** — Plugin for robot vacuum control. https://github.com/joshp123/gohome/tree/main/plugins/roborock
+
+## Community builds (non‑Nexus but made with/around it)
+- **StarSwap marketplace** — Full astronomy gear marketplace. https://star-swap.com/

package/docs/signal.md

@@ -0,0 +1,122 @@
+---
+summary: "Signal support via signal-cli (JSON-RPC + SSE), setup, and number model"
+read_when:
+  - Setting up Signal support
+  - Debugging Signal send/receive
+---
+# Signal (signal-cli)
+
+Status: external CLI integration only. No libsignal embedding.
+
+## Why
+- Signal OSS stack is GPL/AGPL; not compatible with Nexus MIT if bundled.
+- signal-cli is unofficial; must stay up to date (Signal server churn).
+
+## The “number model” (important)
+- Nexus is a **device** connected via `signal-cli`.
+- If you run `signal-cli` on **your personal Signal account**, Nexus will **not** respond to messages sent from that same account (loop protection: ignore sender==account).
+  - Result: you **cannot** “text yourself” to chat with the AI.
+- For “I text her, she texts me back” you want a **separate Signal account/number for the bot**:
+  - Bot number runs `signal-cli` (linked device)
+  - Your personal number is in `signal.allowFrom`
+  - You DM the bot number; Nexus replies back to you
+
+You can still run Nexus on your own Signal account if your goal is “respond to other people as me”, but not for self-chat.
+
+## Model
+- Run `signal-cli` as separate process (user-installed).
+- Prefer `daemon --http=127.0.0.1:PORT` for JSON-RPC + SSE.
+- Alternative: `jsonRpc` mode over stdin/stdout.
+
+## Quickstart (bot number)
+1) Install `signal-cli` (keep Java installed).
+   - If you use the CLI wizard, it can auto-install to `~/nexus/state/tools/signal-cli/...`.
+   - If you want a pinned version (example: `v0.13.22`), install manually:
+     - Download the release asset for your platform from GitHub (tag `v0.13.22`).
+     - Extract it somewhere stable (example: `~/nexus/state/tools/signal-cli/0.13.22/`).
+     - Set `signal.cliPath` to the extracted `signal-cli` binary path.
+2) Link the bot account as a device:
+   - Run: `signal-cli link -n "Nexus"`
+   - Scan QR in Signal: Settings → Linked Devices → Link New Device
+   - Verify: `signal-cli listAccounts` includes the bot E.164
+3) Configure `~/nexus/state/nexus.json`:
+```json5
+{
+  signal: {
+    enabled: true,
+    account: "+15551234567", // bot number (recommended)
+    cliPath: "signal-cli",
+    autoStart: true,
+    httpHost: "127.0.0.1",
+    httpPort: 8080,
+
+    // Who is allowed to talk to the bot (DMs)
+    dmPolicy: "pairing", // pairing | allowlist | open | disabled
+    allowFrom: ["+15557654321"], // your personal number ("open" requires ["*"])
+
+    // Group policy + allowlist
+    groupPolicy: "open",
+    groupAllowFrom: ["+15557654321"]
+  }
+}
+```
+4) Run gateway; sanity probe:
+   - `nexus gateway call providers.status --params '{"probe":true}'`
+   - Expect `signal.probe.ok=true` and `signal.probe.version`.
+5) DM the bot number from your phone; Nexus replies.
+
+## DM pairing
+- Default: `signal.dmPolicy="pairing"` — unknown DM senders get a pairing code.
+- Approve via: `nexus pairing approve --provider signal <code>`.
+
+## “Do I need a separate number?”
+- If you want “I text her and she texts me back”, yes: **use a separate Signal account/number for the bot**.
+- Your personal account can run `signal-cli`, but you can’t self-chat (Signal loop protection; Nexus ignores sender==account).
+
+If you have a second phone:
+- Create/activate the bot number on that phone.
+- Run `signal-cli link -n "Nexus"` on your Mac, scan the QR on the bot phone.
+- Put your personal number in `signal.allowFrom`, then DM the bot number from your personal phone.
+
+## Endpoints (daemon --http)
+- `POST /api/v1/rpc` JSON-RPC request (single or batch).
+- `GET /api/v1/events` SSE stream of `receive` notifications.
+- `GET /api/v1/check` health probe (200 = up).
+
+## Multi-account
+- Start daemon without `-a`.
+- Include `params.account` (E164) on JSON-RPC calls.
+- SSE `?account=+E164` filters events; no param = all accounts.
+
+## Troubleshooting
+- Gateway log coloring: `signal-cli: ...` lines are classified by severity; red means “treat this as an error”.
+- `Failed to initialize HTTP Server` typically means the daemon can’t bind the HTTP port (already in use). Stop the other daemon or change `signal.httpPort`.
+
+## Minimal RPC surface
+- `send` (recipient/groupId/username, message, attachments).
+- `listGroups` (map group IDs).
+- `subscribeReceive` / `unsubscribeReceive` (if manual receive).
+- `startLink` / `finishLink` (optional device link flow).
+
+## Addressing (send targets)
+- Direct: `signal:+15551234567` (or plain `+15551234567`)
+- Groups: `signal:group:<groupId>`
+- Usernames: `username:<name>` / `u:<name>`
+
+## Process plan (Nexus adapter)
+1) Detect `signal-cli` binary; refuse if missing.
+2) Launch daemon (HTTP preferred), store PID.
+3) Poll `/api/v1/check` until ready.
+4) Open SSE stream; parse `event: receive`.
+5) Translate receive payload into Nexus provider model.
+6) On SSE disconnect, backoff + reconnect.
+
+## Storage
+- signal-cli data lives in `$XDG_DATA_HOME/signal-cli/data` or
+  `$HOME/.local/share/signal-cli/data`.
+
+## References (local)
+- `~/Projects/oss/signal-cli/README.md`
+- `~/Projects/oss/signal-cli/man/signal-cli-jsonrpc.5.adoc`
+- `~/Projects/oss/signal-cli/src/main/java/org/asamk/signal/http/HttpServerHandler.java`
+- `~/Projects/oss/signal-cli/src/main/java/org/asamk/signal/jsonrpc/SignalJsonRpcDispatcherHandler.java`