@intent-systems/nexus 2026.1.5-3

package/docs/feature-inventory/overview.md

@@ -0,0 +1,141 @@
+# Feature Inventory Overview
+
+> Scope: Nexus CLI repo (`/home/projects/nexus`) + Nexus Website repo (`/home/projects/nexus-website`)  
+> Includes Rust cloud engine under `native/nexus-cloud`.  
+> Last updated: 2026-01-17
+
+This is the canonical inventory of **all functionality and flows** built across Nexus.
+Use it to guide stabilization, documentation, and test planning.
+
+## CLI Feature Map (Nexus repo)
+
+### Core commands (base CLI)
+- `nexus init [workspace]` — create workspace
+- `nexus status` — onboarding/status overview, filters
+- `nexus capabilities` / `nexus map` — capabilities registry
+- `nexus quest` — onboarding quests
+- `nexus suggestions` — next‑action suggestions
+- `nexus identity [user|agent]` — identity files
+- `nexus config` — config path/status
+- `nexus update` — updater
+- `nexus log` — CLI log/diagnostic surface
+
+### Cloud Sync (TypeScript wrapper + Rust engine)
+- `nexus cloud init/login/push/pull/status/log/reset/guide`
+- Rust engine: `native/nexus-cloud/cli/src/main.rs`
+- TS wrapper: `src/cli/cloud-cli.ts`
+- State path:
+  - `$NEXUS_HOME/state/cloud` (preferred)  
+  - `~/.nexus-rs/state/cloud` (fallback)
+
+### Collaboration / Shared Spaces (Cloud)
+- `nexus cloud collab keys/auth/spaces/invite-links`
+- `nexus cloud spaces list/mount/unmount/push/pull`
+
+### Skills (Local)
+- `nexus skill list/info/use/run/verify/stats`
+
+### Skills Hub (Remote)
+- `nexus skills search/publish/install`
+
+### Credentials & Connectors
+- `nexus credential list/get/add/remove/import/scan/verify`
+- `nexus connector verify/accounts`
+
+### Usage & Telemetry
+- `nexus usage upload/tracking`
+
+### Gateway / Daemon / RPC
+- `nexus gateway *` (start/stop/status/call/agent/health/wake)
+
+### DNS / Discovery
+- `nexus dns setup`
+
+### Devices / Nodes / Browser / Canvas
+- Browser CLI: `src/cli/browser-cli.ts` (+ inspect/manage/observe/actions)
+- Nodes CLI: `src/cli/nodes-cli.ts` (+ camera/screen/canvas)
+- Canvas CLI: `src/cli/canvas-cli.ts`
+
+### Other CLI Modules
+- Cron: `src/cli/cron-cli.ts`
+- Hooks: `src/cli/hooks-cli.ts`
+- Models: `src/cli/models-cli.ts`
+- Pairing: `src/cli/pairing-cli.ts`
+- Profile: `src/cli/profile.ts`
+- Prompt: `src/cli/prompt.ts`
+- TUI: `src/cli/tui-cli.ts`
+- Telegram: `src/cli/telegram-cli.ts`
+- Upstream sync: `src/cli/upstream-sync-cli.ts`
+- Wait: `src/cli/wait.ts`
+
+## Cloud Engine (Rust /native/nexus-cloud)
+
+Crates:
+- `api`, `core`, `crypto`, `storage`, `sync`, `chunker`, `cli`, `daemon`
+
+State files (encrypted unless noted):
+- `keys.enc`, `auth-keypair.enc`, `collab-keys.enc`, `space-secrets.enc`
+- `website-auth.enc`
+- `config.json`, `index.db`, `spaces/*.json`
+
+Key behaviors:
+- All encryption keys remain local; server never receives plaintext.
+- Space keys are per‑member and must be resealed on key rotation.
+
+## Website Feature Map (nexus-website repo)
+
+### Auth & Sessions
+- `/api/auth/*` Auth.js handlers  
+- `/login` (magic links, OAuth)
+- CLI auth flow: `/auth/cli`, `/api/cli/token`
+- Token validation: `/api/validate-token`
+
+### Dashboard & Account
+- `/dashboard` main UI
+- `/dashboard/settings` (profile, recovery phrase, usage tracking)
+- `/dashboard/tokens` (API tokens)
+- `/dashboard/skills` + admin panels
+
+### Cloud Sync
+- `/api/cloud/token` (cloud token exchange)
+- `/api/usage/upload`
+- `/api/usage/settings`
+
+### Collaboration
+- `/api/spaces` (list/create)
+- `/api/spaces/$id/key`
+- `/api/spaces/$id/members/*`
+- `/api/spaces/$id/invite-links/*`
+- `/api/connections/*`
+- `/api/invite-links/$token/accept`
+- `/invite/$token` UI flow
+
+### Skills Hub
+- `/skills` browse/search
+- `/skills/$slug` detail
+- `/skills/$slug/audits` audit report
+- `/api/skills/*` search/detail/download/version/review/star/flag/moderate
+- `/api/skills/audits/run`
+- `/api/skills/$slug/audits/rescan`
+- `/api/skills/capabilities*` registry & proposals
+- `/api/skills/registry/refresh`
+- `/api/skills/blobs/$sha`
+
+### Audit, Policy, Moderation
+Key files:
+- `app/lib/skills-audit-runner.ts`
+- `app/lib/skills-policy.ts`
+- `app/lib/skills-events.ts`
+
+### Admin / Ops
+- `/dashboard/admin` (usage ingestion metrics, events, opt‑outs)
+- gated by `isNexusAdminEmail()` (`app/lib/skills-admin.ts`)
+
+## Manual End‑to‑End Flows (Summary)
+
+- Auth: magic link, OAuth, logout, CLI device auth
+- Personal workspace: init/login/push/log/pull/reset
+- Collaboration: create space, invite, accept, mount, push/pull, key rotation
+- Skills Hub: publish, search, install, audits, review/flag
+- Usage: upload, settings, admin monitoring
+- Gateway/DNS/Tools: service health, discovery, verification

package/docs/feature-inventory/rollout-checklist.md

@@ -0,0 +1,53 @@
+# Rollout Checklist
+
+> Use after all rows in `test-matrix.md` are marked **pass** or **accepted risk**.
+
+## Pre‑Launch (Day ‑1)
+
+### Data & Schema
+- [ ] All migrations applied to prod (verify `drizzle/meta/_journal.json`)
+- [ ] `users.usage_tracking_opt_out` exists in prod
+- [ ] Invite link tables updated and reachable
+
+### Secrets & Env
+- [ ] `AUTH_SECRET` set
+- [ ] `AUTH_URL` / `NEXTAUTH_URL` set
+- [ ] `EMAIL_SERVER` + `EMAIL_FROM` verified
+- [ ] Cloud URLs set (`NEXUS_HUB_URL`, `NEXUS_WEBSITE_URL`, `NEXUS_CLOUD_URL`)
+- [ ] Stripe keys set (if billing enabled)
+
+### Infra
+- [ ] Vercel deployment healthy
+- [ ] Worker endpoints reachable (`/api/cloud/token`, `/api/skills/*`)
+- [ ] Object storage (R2/S3) reachable for skills + sync
+- [ ] Logs + metrics visible
+
+## Launch Day (Day 0)
+
+### Smoke Tests (must pass)
+- [ ] Magic link login (web)
+- [ ] CLI login (`nexus cloud login`)
+- [ ] Personal workspace push/pull
+- [ ] Collab space create + invite + mount + push/pull
+- [ ] Skills hub search + install + download
+- [ ] Audit runner executes
+- [ ] Usage upload succeeds
+
+### User‑Facing UI
+- [ ] `/skills` loads and search works
+- [ ] `/skills/$slug` detail loads and audit view link works
+- [ ] `/dashboard` loads for logged‑in users
+- [ ] Logout clears session
+
+## Post‑Launch (Day +1)
+
+### Monitoring
+- [ ] Audit job health
+- [ ] Usage ingestion counts steady
+- [ ] Error rate within bounds
+- [ ] Sync error rate acceptable
+
+### Backlog Review
+- [ ] Record known issues
+- [ ] Prioritize test automation
+- [ ] Capture user feedback

package/docs/feature-inventory/test-matrix.md

@@ -0,0 +1,87 @@
+# Test Matrix (Manual)
+
+> Goal: confirm every surface works end‑to‑end before launch.  
+> Status values: `pending` | `pass` | `fail` | `blocked`
+
+## Auth & Sessions
+
+| Area | Flow | Where | Expected | Status |
+| --- | --- | --- | --- | --- |
+| Magic link login | Email → verify → dashboard | Web | Session cookie set, dashboard loads | pending |
+| OAuth login | OAuth → dashboard | Web | Session cookie set, dashboard loads | pending |
+| Logout | Dashboard → Sign out | Web | Session cleared, protected routes redirect to login | pending |
+| CLI auth | `nexus cloud login` | CLI + Web | Token stored, rust state provisioned | pending |
+| Token creation | `/api/tokens/create` | Web API | Token returned once, usable for CLI | pending |
+
+## Personal Workspace Sync
+
+| Area | Flow | Where | Expected | Status |
+| --- | --- | --- | --- | --- |
+| Init | `nexus cloud init` | CLI | Config + state created | pending |
+| Login | `nexus cloud login` | CLI | Keys provisioned, auth stored | pending |
+| Push | `nexus cloud push` | CLI | Commit hash returned | pending |
+| Log | `nexus cloud log` | CLI | Commit history visible | pending |
+| Pull | `nexus cloud pull` | CLI | Files updated, commit hash | pending |
+| Reset | `nexus cloud reset --force` | CLI | Remote workspace cleared | pending |
+| Large sync | push with large files | CLI | No timeout / retry OK | pending |
+
+## Collaboration / Spaces
+
+| Area | Flow | Where | Expected | Status |
+| --- | --- | --- | --- | --- |
+| Create space | `collab spaces create` | CLI | Space created, keys saved | pending |
+| Invite link | `collab spaces invite-links create` | CLI | Link created | pending |
+| Accept invite | `/invite/$token` | Web | Join succeeds, metadata visible | pending |
+| Fetch space key | `collab spaces key` | CLI | Space key stored locally | pending |
+| Mount | `spaces mount` | CLI | Mount path created, config saved | pending |
+| Sync push | `spaces push` | CLI | Commit hash | pending |
+| Sync pull | `spaces pull` | CLI | Files present | pending |
+| Key rotation | remove + re‑invite | Web/API + CLI | New key version, member can mount | pending |
+
+## Skills Hub (CLI + Web)
+
+| Area | Flow | Where | Expected | Status |
+| --- | --- | --- | --- | --- |
+| Publish | `nexus skills publish` | CLI | Skill version created | pending |
+| Search | `/skills`, `/api/skills/search` | Web | Results ordered, filters apply | pending |
+| Search | `nexus skills search` | CLI | Results displayed | pending |
+| Install | `nexus skills install` | CLI | Skill installed, files present | pending |
+| Download | `/api/skills/$slug/download` | Web | Artifact URL delivered | pending |
+| Audit run | `/api/skills/audits/run` | Web API | Audits created | pending |
+| Audit rescan | `/api/skills/$slug/audits/rescan` | Web API | New audit entries | pending |
+| Review/flag/star | `/api/skills/$slug/review|flag|star` | Web | Counts update | pending |
+
+## Usage Tracking
+
+| Area | Flow | Where | Expected | Status |
+| --- | --- | --- | --- | --- |
+| Upload | `nexus usage upload` → `/api/usage/upload` | CLI + Web | Batches ingested | pending |
+| Opt‑out | `/dashboard/settings` | Web | Paid plan can toggle | pending |
+| Admin view | `/dashboard/admin` | Web | Metrics visible | pending |
+
+## Credentials & Connectors
+
+| Area | Flow | Where | Expected | Status |
+| --- | --- | --- | --- | --- |
+| Credential add | `nexus credential add` | CLI | Stored + listed | pending |
+| Credential verify | `nexus credential verify` | CLI | Validates against provider | pending |
+| Connector verify | `nexus connector verify` | CLI | Dependency checks pass | pending |
+
+## Gateway / DNS / Tools
+
+| Area | Flow | Where | Expected | Status |
+| --- | --- | --- | --- | --- |
+| Gateway start | `nexus gateway start` | CLI | Health OK | pending |
+| RPC call | `nexus gateway call` | CLI | Response returned | pending |
+| DNS setup | `nexus dns setup` | CLI | CoreDNS configured | pending |
+
+## Website Admin / Ops
+
+| Area | Flow | Where | Expected | Status |
+| --- | --- | --- | --- | --- |
+| Admin access | `/dashboard/admin` | Web | Only admins can view | pending |
+| Audit moderation | `/api/skills/$slug/moderate` | Web API | Status updated | pending |
+
+## Notes / Known Blockers
+
+- Record any infra or env issues here before launch.

package/docs/feature-inventory.md

@@ -0,0 +1,9 @@
+# Feature Inventory Docs
+
+The feature inventory has been split into a dedicated folder:
+
+- `docs/feature-inventory/overview.md`
+- `docs/feature-inventory/test-matrix.md`
+- `docs/feature-inventory/rollout-checklist.md`
+
+Start with the overview, then work through the test matrix and rollout checklist.

package/docs/gateway/configuration-examples.md

@@ -0,0 +1,221 @@
+---
+summary: "Schema-accurate configuration examples for common Nexus setups"
+read_when:
+  - Learning how to configure Nexus
+  - Looking for configuration examples
+  - Setting up Nexus for the first time
+---
+# Configuration Examples
+
+Examples below are aligned with the current config schema. For the exhaustive
+reference and per-field notes, see [Configuration](/configuration).
+
+## Quick start
+
+### Absolute minimum
+```json5
+{
+  agent: { workspace: "~/nexus" },
+  whatsapp: { allowFrom: ["+15555550123"] }
+}
+```
+
+Save to `~/nexus/state/nexus.json` and you can DM the bot from that number.
+
+### Recommended starter
+```json5
+{
+  identity: {
+    name: "Nexus",
+    theme: "helpful assistant",
+    emoji: "🦞"
+  },
+  agent: {
+    workspace: "~/nexus",
+    model: { primary: "anthropic/claude-sonnet-4-5" }
+  },
+  whatsapp: {
+    allowFrom: ["+15555550123"],
+    groups: { "*": { requireMention: true } }
+  },
+  routing: {
+    groupChat: {
+      mentionPatterns: ["@nexus", "nexus"]
+    }
+  }
+}
+```
+
+## Expanded example (major options)
+
+> JSON5 lets you use comments and trailing commas. Regular JSON works too.
+
+```json5
+{
+  identity: {
+    name: "Nexus",
+    theme: "helpful assistant",
+    emoji: "🦞"
+  },
+
+  logging: {
+    level: "info",
+    consoleLevel: "info",
+    consoleStyle: "pretty",
+    redactSensitive: "tools"
+  },
+
+  messages: {
+    messagePrefix: "[nexus]",
+    responsePrefix: ">",
+    ackReaction: "👀",
+    ackReactionScope: "group-mentions"
+  },
+
+  routing: {
+    groupChat: {
+      mentionPatterns: ["@nexus", "nexus"],
+      historyLimit: 50
+    },
+    queue: {
+      mode: "collect",
+      debounceMs: 1000,
+      cap: 20,
+      drop: "summarize",
+      byProvider: {
+        whatsapp: "collect",
+        telegram: "collect",
+        discord: "collect",
+        slack: "collect",
+        signal: "collect",
+        imessage: "collect",
+        webchat: "collect"
+      }
+    }
+  },
+
+  session: {
+    scope: "per-sender",
+    idleMinutes: 60,
+    resetTriggers: ["/new", "/reset"],
+    store: "~/nexus/state/agents/main/sessions/sessions.json",
+    typingIntervalSeconds: 5,
+    sendPolicy: {
+      default: "allow",
+      rules: [
+        { action: "deny", match: { channel: "discord", chatType: "group" } }
+      ]
+    }
+  },
+
+  agent: {
+    workspace: "~/nexus",
+    userTimezone: "America/Chicago",
+    model: {
+      primary: "anthropic/claude-sonnet-4-5",
+      fallbacks: ["anthropic/claude-opus-4-5", "openai/gpt-5.2"]
+    },
+    imageModel: {
+      primary: "openrouter/anthropic/claude-sonnet-4-5"
+    },
+    models: {
+      "anthropic/claude-opus-4-5": { alias: "opus" },
+      "anthropic/claude-sonnet-4-5": { alias: "sonnet" },
+      "openai/gpt-5.2": { alias: "gpt" }
+    },
+    thinkingDefault: "low",
+    verboseDefault: "off",
+    elevatedDefault: "on",
+    blockStreamingDefault: "off",
+    blockStreamingBreak: "text_end",
+    blockStreamingChunk: {
+      minChars: 800,
+      maxChars: 1200,
+      breakPreference: "paragraph"
+    },
+    timeoutSeconds: 600,
+    mediaMaxMb: 5,
+    typingIntervalSeconds: 5,
+    maxConcurrent: 3,
+    heartbeat: {
+      every: "30m",
+      target: "last",
+      prompt: "Consider outstanding tasks and HEARTBEAT.md guidance from the workspace context (if present). Checkup sometimes on your human during (user local) day time.",
+      ackMaxChars: 300
+    },
+    memorySearch: {
+      provider: "openai",
+      model: "text-embedding-004",
+      remote: {
+        baseUrl: "https://generativelanguage.googleapis.com/v1beta/openai/",
+        apiKey: "${GEMINI_API_KEY}"
+      }
+    },
+    sandbox: {
+      mode: "non-main",
+      perSession: true,
+      workspaceRoot: "~/nexus/sandboxes",
+      docker: {
+        image: "nexus-sandbox:bookworm-slim",
+        workdir: "/workspace",
+        readOnlyRoot: true,
+        tmpfs: ["/tmp", "/var/tmp", "/run"],
+        network: "none",
+        user: "1000:1000"
+      },
+      browser: {
+        enabled: false
+      }
+    }
+  },
+
+  whatsapp: {
+    dmPolicy: "pairing",
+    allowFrom: ["+15555550123"],
+    groupPolicy: "allowlist",
+    groupAllowFrom: ["+15555550123"],
+    groups: { "*": { requireMention: true } }
+  },
+
+  telegram: {
+    enabled: true,
+    botToken: "YOUR_TELEGRAM_BOT_TOKEN",
+    allowFrom: ["123456789"],
+    groupPolicy: "allowlist",
+    groupAllowFrom: ["123456789"],
+    groups: { "*": { requireMention: true } }
+  },
+
+  discord: {
+    enabled: true,
+    token: "YOUR_DISCORD_BOT_TOKEN",
+    dm: { enabled: true, allowFrom: ["steipete"] },
+    guilds: {
+      "123456789012345678": {
+        slug: "friends-of-nexus",
+        requireMention: false,
+        channels: {
+          general: { allow: true },
+          help: { allow: true, requireMention: true }
+        }
+      }
+    }
+  },
+
+  slack: {
+    enabled: true,
+    botToken: "xoxb-REPLACE_ME",
+    appToken: "xapp-REPLACE_ME",
+    channels: {
+      "#general": { allow: true, requireMention: true }
+    },
+    dm: { enabled: true, allowFrom: ["U123"] },
+    slashCommand: {
+      enabled: true,
+      name: "nexus",
+      sessionPrefix: "slack:slash",
+      ephemeral: true
+    }
+  }
+}
+```

package/docs/gateway/configuration.md

@@ -0,0 +1,172 @@
+---
+summary: "Gateway configuration reference for ~/nexus/state/nexus.json"
+read_when:
+  - Adding or modifying config fields
+---
+# Gateway Configuration 🔧
+
+Nexus reads an optional **JSON5** config from `~/nexus/state/nexus.json`
+(comments + trailing commas allowed). You can override the path with
+`NEXUS_CONFIG_PATH` (legacy: `NEXUS_CONFIG_PATH`).
+
+If the file is missing, Nexus uses safe defaults (embedded Pi agent + per-sender
+sessions + workspace `~/nexus`). You usually only need a config to:
+- restrict who can trigger the bot (`whatsapp.allowFrom`, `telegram.allowFrom`, etc.)
+- control group allowlists + mention behavior (`whatsapp.groups`, `telegram.groups`, `discord.guilds`, `routing.groupChat`)
+- customize message prefixes (`messages`)
+- set the agent's workspace (`agent.workspace`)
+- tune the embedded agent defaults (`agent`) and session behavior (`session`)
+- set identity used in UI/status (`identity`)
+
+For the full schema and per-field notes, see [Configuration](/configuration).
+For examples, see [Configuration Examples](/gateway/configuration-examples).
+
+## Minimal config (recommended starting point)
+
+```json5
+{
+  agent: { workspace: "~/nexus" },
+  whatsapp: { allowFrom: ["+15555550123"] }
+}
+```
+
+Build the default sandbox image once with:
+```bash
+scripts/sandbox-setup.sh
+```
+
+## Apply + restart (RPC)
+
+Use `config.apply` to validate + write the full config and restart the Gateway
+in one step. It writes a restart sentinel and pings the last active session
+after the Gateway comes back.
+
+Params:
+- `raw` (string) — JSON5 payload for the entire config
+- `sessionKey` (optional) — last active session key for the wake-up ping
+- `restartDelayMs` (optional) — delay before restart (default 2000)
+
+Example (via `nexus gateway call`):
+
+```bash
+nexus gateway call config.apply --params '{
+  "raw": "{\\n  agent: { workspace: \\"~/nexus\\" }\\n}\\n",
+  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
+  "restartDelayMs": 1000
+}'
+```
+
+## Config Includes (`$include`)
+
+Split your config into multiple files using the `$include` directive. This is
+useful for:
+- organizing large configs (for example per-client routing rules)
+- sharing common settings across environments
+- keeping sensitive configs separate
+
+### Basic usage
+
+```json5
+// ~/nexus/state/nexus.json
+{
+  gateway: { port: 18789 },
+
+  // Include a single file (replaces the key's value)
+  agent: { "$include": "./agent.json5" },
+
+  // Include multiple files (deep-merged in order)
+  routing: {
+    "$include": [
+      "./routing/base.json5",
+      "./routing/clients.json5"
+    ]
+  }
+}
+```
+
+```json5
+// ~/nexus/state/agent.json5
+{
+  workspace: "~/nexus"
+}
+```
+
+### Merge behavior
+
+- **Single file**: Replaces the object containing `$include`
+- **Array of files**: Deep-merges files in order (later files override earlier ones)
+- **With sibling keys**: Sibling keys are merged after includes (override included values)
+- **Arrays**: Concatenated when both sides are arrays
+
+```json5
+// Sibling keys override included values
+{
+  "$include": "./base.json5", // { a: 1, b: 2 }
+  b: 99                        // Result: { a: 1, b: 99 }
+}
+```
+
+### Nested includes
+
+Included files can themselves contain `$include` directives (up to 10 levels deep):
+
+```json5
+// clients/mueller.json5
+{
+  routing: { "$include": "./mueller/routing.json5" },
+  agent: { "$include": "./mueller/agent.json5" }
+}
+```
+
+### Path resolution
+
+- **Relative paths**: Resolved relative to the including file
+- **Absolute paths**: Used as-is
+- **Parent directories**: `../` references work as expected
+
+```json5
+{ "$include": "./sub/config.json5" }       // relative
+{ "$include": "/etc/nexus/base.json5" }    // absolute
+{ "$include": "../shared/common.json5" }   // parent dir
+```
+
+### Error handling
+
+- **Missing file**: Clear error with resolved path
+- **Parse error**: Shows which included file failed
+- **Circular includes**: Detected and reported with include chain
+
+### Example: Modular routing setup
+
+```json5
+// ~/nexus/state/nexus.json
+{
+  gateway: { port: 18789, auth: { token: "secret" } },
+  routing: {
+    agents: { "$include": [
+      "./clients/mueller/agents.json5",
+      "./clients/schmidt/agents.json5"
+    ]},
+    groups: { "$include": [
+      "./clients/mueller/groups.json5",
+      "./clients/schmidt/groups.json5"
+    ]}
+  },
+  whatsapp: { dmPolicy: "pairing" }
+}
+```
+
+```json5
+// ~/nexus/state/clients/mueller/agents.json5
+{
+  "mueller-transcribe": { workspace: "~/clients/mueller/transcribe" },
+  "mueller-docs": { workspace: "~/clients/mueller/docs" }
+}
+```
+
+```json5
+// ~/nexus/state/clients/mueller/groups.json5
+{
+  "120363403215116621@g.us": ["mueller-transcribe", "mueller-docs"]
+}
+```