@intent-systems/nexus 2026.1.5-3

package/docs/skills-config.md

@@ -0,0 +1,58 @@
+---
+summary: "Skills config schema and examples"
+read_when:
+  - Adding or modifying skills config
+  - Adjusting bundled allowlist or install behavior
+---
+# Skills Config
+
+All skills-related configuration lives under `skills` in `~/nexus/state/nexus.json`.
+
+```json5
+{
+  skills: {
+    allowBundled: ["brave-search", "gemini"],
+    load: {
+      extraDirs: [
+        "~/Projects/agent-scripts/skills",
+        "~/Projects/oss/some-skill-pack/skills"
+      ]
+    },
+    install: {
+      preferBrew: true,
+      nodeManager: "npm" // npm | pnpm | yarn | bun
+    },
+    entries: {
+      "nano-banana-pro": {
+        enabled: true,
+        apiKey: "GEMINI_KEY_HERE",
+        env: {
+          GEMINI_API_KEY: "GEMINI_KEY_HERE"
+        }
+      },
+      peekaboo: { enabled: true },
+      sag: { enabled: false }
+    }
+  }
+}
+```
+
+## Fields
+
+- `allowBundled`: optional allowlist for **bundled** skills only. When set, only
+  bundled skills in the list are eligible (home/project/extraDirs skills unaffected).
+- `load.extraDirs`: additional skill directories to scan (lowest precedence).
+- `install.preferBrew`: prefer brew installers when available (default: true).
+- `install.nodeManager`: node installer preference (`npm` | `pnpm` | `yarn` | `bun`, default: npm).
+- `entries.<skillKey>`: per-skill overrides.
+
+Per-skill fields:
+- `enabled`: set `false` to disable a skill even if it’s bundled/installed.
+- `env`: environment variables injected for the agent run (only if not already set).
+- `apiKey`: optional convenience for skills that declare a primary env var.
+
+## Notes
+
+- Keys under `entries` map to the skill name by default. If a skill defines
+  `metadata.nexus.skillKey`, use that key instead.
+- Changes to skills are picked up on the next new session.

package/docs/skills.md

@@ -0,0 +1,153 @@
+---
+summary: "Skills: bundled vs home/project, gating rules, and config/env wiring"
+read_when:
+  - Adding or modifying skills
+  - Changing skill gating or load rules
+---
+# Skills (Nexus)
+
+Nexus uses **AgentSkills-compatible** skill folders to teach the agent how to use tools. Each skill is a directory containing a `SKILL.md` with YAML frontmatter and instructions. Nexus loads **bundled skills** plus optional local overrides, and filters them at load time based on environment, config, and binary presence.
+
+## Locations and precedence
+
+Skills are loaded from **(at most) three** places:
+
+1) **Bundled baseline**: shipped with the install (npm package or Nexus.app)
+2) **Home skills** (portable): `~/nexus/home/skills`
+3) **Project skills** (portable): `<projectRoot>/skills`
+
+If a skill name conflicts, precedence is:
+
+`<projectRoot>/skills` (highest) → `~/nexus/home/skills` → bundled baseline (lowest)
+
+Additionally, you can configure extra skill folders (lowest precedence) via
+`skills.load.extraDirs` in `~/nexus/state/nexus.json`.
+
+## Format (AgentSkills + Pi-compatible)
+
+`SKILL.md` must include at least:
+
+```markdown
+---
+name: nano-banana-pro
+description: Generate or edit images via Gemini 3 Pro Image
+---
+```
+
+Notes:
+- We follow the AgentSkills spec for layout/intent.
+- The parser used by the embedded agent supports **single-line** frontmatter keys only.
+- `metadata` should be a **single-line JSON object**.
+- Use `{baseDir}` in instructions to reference the skill folder path.
+- Optional frontmatter keys:
+  - `homepage` — URL surfaced as “Website” in the macOS Skills UI (also supported via `metadata.nexus.homepage`).
+
+## Gating (load-time filters)
+
+Nexus **filters skills at load time** using `metadata` (single-line JSON):
+
+```markdown
+---
+name: nano-banana-pro
+description: Generate or edit images via Gemini 3 Pro Image
+metadata: {"nexus":{"requires":{"bins":["uv"],"env":["GEMINI_API_KEY"],"config":["browser.enabled"]},"primaryEnv":"GEMINI_API_KEY"}}
+---
+```
+
+Fields under `metadata.nexus`:
+- `always: true` — always include the skill (skip other gates).
+- `emoji` — optional emoji used by the macOS Skills UI.
+- `homepage` — optional URL shown as “Website” in the macOS Skills UI.
+- `os` — optional list of platforms (`darwin`, `linux`, `win32`). If set, the skill is only eligible on those OSes.
+- `requires.bins` — list; each must exist on `PATH`.
+- `requires.anyBins` — list; at least one must exist on `PATH`.
+- `requires.env` — list; env var must exist **or** be provided in config.
+- `requires.config` — list of `nexus.json` paths that must be truthy.
+- `primaryEnv` — env var name associated with `skills.entries.<name>.apiKey`.
+- `install` — optional array of installer specs used by the macOS Skills UI (brew/node/go/uv).
+
+Installer example:
+
+```markdown
+---
+name: gemini
+description: Use Gemini CLI for coding assistance and Google search lookups.
+metadata: {"nexus":{"emoji":"♊️","requires":{"bins":["gemini"]},"install":[{"id":"brew","kind":"brew","formula":"gemini-cli","bins":["gemini"],"label":"Install Gemini CLI (brew)"}]}}
+---
+```
+
+Notes:
+- If multiple installers are listed, the gateway picks a **single** preferred option (brew when available, otherwise node).
+- Node installs honor `skills.install.nodeManager` in `nexus.json` (default: npm; options: npm/pnpm/yarn/bun).
+- Go installs: if `go` is missing and `brew` is available, the gateway installs Go via Homebrew first and sets `GOBIN` to Homebrew’s `bin` when possible.
+
+If no `metadata.nexus` is present, the skill is always eligible (unless
+disabled in config or blocked by `skills.allowBundled` for bundled skills).
+
+## Config overrides (`~/nexus/state/nexus.json`)
+
+Skills can be toggled and supplied with env values:
+
+```json5
+{
+  skills: {
+    entries: {
+      "nano-banana-pro": {
+        enabled: true,
+        apiKey: "GEMINI_KEY_HERE",
+        env: {
+          GEMINI_API_KEY: "GEMINI_KEY_HERE"
+        }
+      },
+      peekaboo: { enabled: true },
+      sag: { enabled: false }
+    }
+  }
+}
+```
+
+Note: if the skill name contains hyphens, quote the key (JSON5 allows quoted keys).
+
+Config keys match the **skill name** by default. If a skill defines
+`metadata.nexus.skillKey`, use that key under `skills.entries`.
+
+Rules:
+- `enabled: false` disables the skill even if it’s bundled/installed.
+- `env`: injected **only if** the variable isn’t already set in the process.
+- `apiKey`: convenience for skills that declare `metadata.nexus.primaryEnv`.
+- `allowBundled`: optional allowlist for **bundled** skills only. If set, only
+  bundled skills in the list are eligible (home/project/extraDirs skills unaffected).
+
+## Environment injection (per agent run)
+
+When an agent run starts, Nexus:
+1) Reads skill metadata.
+2) Applies any `skills.entries.<key>.env` or `skills.entries.<key>.apiKey` to
+   `process.env`.
+3) Builds the system prompt with **eligible** skills.
+4) Restores the original environment after the run ends.
+
+This is **scoped to the agent run**, not a global shell environment.
+
+## Session snapshot (performance)
+
+Nexus snapshots the eligible skills **when a session starts** and reuses that list for subsequent turns in the same session. Changes to skills or config take effect on the next new session.
+
+## Bundled baseline + overrides
+
+Nexus ships a baseline set of skills as **bundled skills** as part of the
+install (npm package or Nexus.app).
+
+Overrides live in files (portable):
+- home: `~/nexus/home/skills/<skill>/SKILL.md`
+- project: `<projectRoot>/skills/<skill>/SKILL.md`
+
+If you need a machine-local (non-portable) skill dir, prefer adding it explicitly
+via `skills.load.extraDirs` in `~/nexus/state/nexus.json` (rather than relying on
+an implicit hidden folder).
+
+## Config reference
+
+See [`docs/skills-config.md`](https://docs.nexus.bot/skills-config) for the full configuration schema.
+
+---

package/docs/slack.md

@@ -0,0 +1,221 @@
+---
+summary: "Slack socket mode setup and Nexus config"
+read_when: "Setting up Slack or debugging Slack socket mode"
+---
+
+# Slack (socket mode)
+
+## Setup
+1) Create a Slack app (From scratch) in https://api.slack.com/apps.
+2) **Socket Mode** → toggle on. Then go to **Basic Information** → **App-Level Tokens** → **Generate Token and Scopes** with scope `connections:write`. Copy the **App Token** (`xapp-...`).
+3) **OAuth & Permissions** → add bot token scopes (use the manifest below). Click **Install to Workspace**. Copy the **Bot User OAuth Token** (`xoxb-...`).
+4) **Event Subscriptions** → enable events and subscribe to:
+   - `message.*` (includes edits/deletes/thread broadcasts)
+   - `app_mention`
+   - `reaction_added`, `reaction_removed`
+   - `member_joined_channel`, `member_left_channel`
+   - `channel_rename`
+   - `pin_added`, `pin_removed`
+5) Invite the bot to channels you want it to read.
+6) Slash Commands → create the `/nexus` command (or your preferred name).
+7) App Home → enable the **Messages Tab** so users can DM the bot.
+
+Use the manifest below so scopes and events stay in sync.
+
+## Manifest (optional)
+Use this Slack app manifest to create the app quickly (adjust the name/command if you want).
+
+```json
+{
+  "display_information": {
+    "name": "Nexus",
+    "description": "Slack connector for Nexus"
+  },
+  "features": {
+    "bot_user": {
+      "display_name": "Nexus",
+      "always_online": false
+    },
+    "app_home": {
+      "messages_tab_enabled": true,
+      "messages_tab_read_only_enabled": false
+    },
+    "slash_commands": [
+      {
+        "command": "/nexus",
+        "description": "Send a message to Nexus",
+        "should_escape": false
+      }
+    ]
+  },
+  "oauth_config": {
+    "scopes": {
+      "bot": [
+        "chat:write",
+        "channels:history",
+        "channels:read",
+        "groups:history",
+        "groups:read",
+        "groups:write",
+        "im:history",
+        "im:read",
+        "im:write",
+        "mpim:history",
+        "mpim:read",
+        "mpim:write",
+        "users:read",
+        "app_mentions:read",
+        "reactions:read",
+        "reactions:write",
+        "pins:read",
+        "pins:write",
+        "emoji:read",
+        "commands",
+        "files:read",
+        "files:write"
+      ]
+    }
+  },
+  "settings": {
+    "socket_mode_enabled": true,
+    "event_subscriptions": {
+      "bot_events": [
+        "app_mention",
+        "message.channels",
+        "message.groups",
+        "message.im",
+        "message.mpim",
+        "reaction_added",
+        "reaction_removed",
+        "member_joined_channel",
+        "member_left_channel",
+        "channel_rename",
+        "pin_added",
+        "pin_removed"
+      ]
+    }
+  }
+}
+```
+
+## Scopes (current vs optional)
+Slack's Conversations API is type-scoped: you only need the scopes for the
+conversation types you actually touch (channels, groups, im, mpim). See
+https://api.slack.com/docs/conversations-api for the overview.
+
+### Required by current code
+- `chat:write` (send/update/delete messages via `chat.postMessage`)
+  https://api.slack.com/methods/chat.postMessage
+- `im:write` (open DMs via `conversations.open` for user DMs)
+  https://api.slack.com/methods/conversations.open
+- `channels:history`, `groups:history`, `im:history`, `mpim:history`
+  (`conversations.history` in `src/slack/actions.ts`)
+  https://api.slack.com/methods/conversations.history
+- `channels:read`, `groups:read`, `im:read`, `mpim:read`
+  (`conversations.info` in `src/slack/monitor.ts`)
+  https://api.slack.com/methods/conversations.info
+- `users:read` (`users.info` in `src/slack/monitor.ts` + `src/slack/actions.ts`)
+  https://api.slack.com/methods/users.info
+- `reactions:read`, `reactions:write` (`reactions.get` / `reactions.add`)
+  https://api.slack.com/methods/reactions.get
+  https://api.slack.com/methods/reactions.add
+- `pins:read`, `pins:write` (`pins.list` / `pins.add` / `pins.remove`)
+  https://api.slack.com/scopes/pins:read
+  https://api.slack.com/scopes/pins:write
+- `emoji:read` (`emoji.list`)
+  https://api.slack.com/scopes/emoji:read
+- `files:write` (uploads via `files.uploadV2`)
+  https://api.slack.com/messaging/files/uploading
+
+### Not needed today (but likely future)
+- `mpim:write` (only if we add group-DM open/DM start via `conversations.open`)
+- `groups:write` (only if we add private-channel management: create/rename/invite/archive)
+- `chat:write.public` (only if we want to post to channels the bot isn't in)
+  https://api.slack.com/scopes/chat:write.public
+- `users:read.email` (only if we need email fields from `users.info`)
+  https://api.slack.com/changelog/2017-04-narrowing-email-access
+- `files:read` (only if we start listing/reading file metadata)
+
+## Config
+Slack uses Socket Mode only (no HTTP webhook server). Provide both tokens:
+
+```json
+{
+  "slack": {
+    "enabled": true,
+    "botToken": "xoxb-...",
+    "appToken": "xapp-...",
+    "groupPolicy": "open",
+    "dm": {
+      "enabled": true,
+      "policy": "pairing",
+      "allowFrom": ["U123", "U456", "*"],
+      "groupEnabled": false,
+      "groupChannels": ["G123"]
+    },
+    "channels": {
+      "C123": { "allow": true, "requireMention": true },
+      "#general": { "allow": true, "requireMention": false }
+    },
+    "reactionNotifications": "own",
+    "reactionAllowlist": ["U123"],
+    "actions": {
+      "reactions": true,
+      "messages": true,
+      "pins": true,
+      "memberInfo": true,
+      "emojiList": true
+    },
+    "slashCommand": {
+      "enabled": true,
+      "name": "nexus",
+      "sessionPrefix": "slack:slash",
+      "ephemeral": true
+    },
+    "textChunkLimit": 4000,
+    "mediaMaxMb": 20
+  }
+}
+```
+
+Tokens can also be supplied via env vars:
+- `SLACK_BOT_TOKEN`
+- `SLACK_APP_TOKEN`
+
+Ack reactions are controlled globally via `messages.ackReaction` +
+`messages.ackReactionScope`.
+
+## Sessions + routing
+- DMs share the `main` session (like WhatsApp/Telegram).
+- Channels map to `slack:channel:<channelId>` sessions.
+- Slash commands use `slack:slash:<userId>` sessions.
+
+## DM security (pairing)
+- Default: `slack.dm.policy="pairing"` — unknown DM senders get a pairing code.
+- Approve via: `nexus pairing approve --provider slack <code>`.
+- To allow anyone: set `slack.dm.policy="open"` and `slack.dm.allowFrom=["*"]`.
+
+## Group policy
+- `slack.groupPolicy` controls channel handling (`open|disabled|allowlist`).
+- `allowlist` requires channels to be listed in `slack.channels`.
+
+## Delivery targets
+Use these with cron/CLI sends:
+- `user:<id>` for DMs
+- `channel:<id>` for channels
+
+## Tool actions
+Slack tool actions can be gated with `slack.actions.*`:
+
+| Action group | Default | Notes |
+| --- | --- | --- |
+| reactions | enabled | React + list reactions |
+| messages | enabled | Read/send/edit/delete |
+| pins | enabled | Pin/unpin/list |
+| memberInfo | enabled | Member info |
+| emojiList | enabled | Custom emoji list |
+
+## Notes
+- Mention gating is controlled via `slack.channels` (set `requireMention` to `true`); `routing.groupChat.mentionPatterns` also count as mentions.
+- Reaction notifications follow `slack.reactionNotifications` (use `reactionAllowlist` with mode `allowlist`).
+- Attachments are downloaded to the media store when permitted and under the size limit.

package/docs/subagents.md

@@ -0,0 +1,72 @@
+---
+summary: "Sub-agents: spawning isolated agent runs that announce results back to the requester chat"
+read_when:
+  - You want background/parallel work via the agent
+  - You are changing sessions_spawn or sub-agent tool policy
+---
+
+# Sub-agents
+
+Sub-agents are background agent runs spawned from an existing agent run. They run in their own session (`subagent:<uuid>`) and, when finished, **announce** their result back to the requester chat provider.
+
+Primary goals:
+- Parallelize “research / long task / slow tool” work without blocking the main run.
+- Keep sub-agents isolated by default (session separation + optional sandboxing).
+- Keep the tool surface hard to misuse: sub-agents do **not** get session tools by default.
+- Avoid nested fan-out: sub-agents cannot spawn sub-agents.
+
+## Tool
+
+Use `sessions_spawn`:
+- Starts a sub-agent run (`deliver: false`, global lane: `subagent`)
+- Then runs an announce step and posts the announce reply to the requester chat provider
+
+Tool params:
+- `task` (required)
+- `label?` (optional)
+- `timeoutSeconds?` (default `0`; `0` = fire-and-forget)
+- `cleanup?` (`delete|keep`, default `delete`)
+
+## Announce
+
+Sub-agents report back via an announce step:
+- The announce step runs inside the sub-agent session (not the requester session).
+- If the sub-agent replies exactly `ANNOUNCE_SKIP`, nothing is posted.
+- Otherwise the announce reply is posted to the requester chat provider via the gateway `send` method.
+
+## Tool Policy (sub-agent tools)
+
+By default, sub-agents get **all tools except session tools**:
+- `sessions_list`
+- `sessions_history`
+- `sessions_send`
+- `sessions_spawn`
+
+Override via config:
+
+```json5
+{
+  agent: {
+    subagents: {
+      maxConcurrent: 1,
+      tools: {
+        // deny wins
+        deny: ["gateway", "cron"],
+        // if allow is set, it becomes allow-only (deny still wins)
+        // allow: ["read", "bash", "process"]
+      }
+    }
+  }
+}
+```
+
+## Concurrency
+
+Sub-agents use a dedicated in-process queue lane:
+- Lane name: `subagent`
+- Concurrency: `agent.subagents.maxConcurrent` (default `1`)
+
+## Limitations
+
+- Sub-agent announce is **best-effort**. If the gateway restarts, pending “announce back” work is lost.
+- Sub-agents still share the same gateway process resources; treat `maxConcurrent` as a safety valve.

package/docs/tailscale.md

@@ -0,0 +1,71 @@
+---
+summary: "Integrated Tailscale Serve/Funnel for the Gateway dashboard"
+read_when:
+  - Exposing the Gateway Control UI outside localhost
+  - Automating tailnet or public dashboard access
+---
+# Tailscale (Gateway dashboard)
+
+Nexus can auto-configure Tailscale **Serve** (tailnet) or **Funnel** (public) for the
+Gateway dashboard and WebSocket port. This keeps the Gateway bound to loopback while
+Tailscale provides HTTPS, routing, and (for Serve) identity headers.
+
+## Modes
+
+- `serve`: Tailnet-only HTTPS via `tailscale serve`. The gateway stays on `127.0.0.1`.
+- `funnel`: Public HTTPS via `tailscale funnel`. Requires a shared password.
+- `off`: Default (no Tailscale automation).
+
+## Auth
+
+Set `gateway.auth.mode` to control the handshake:
+
+- `token` (default when `NEXUS_GATEWAY_TOKEN` is set)
+- `password` (shared secret via `NEXUS_GATEWAY_PASSWORD` or config)
+
+When `tailscale.mode = "serve"`, the gateway trusts Tailscale identity headers by
+default unless you force `gateway.auth.mode` to `password` or set
+`gateway.auth.allowTailscale: false`.
+
+## Config examples
+
+### Tailnet-only (Serve)
+
+```json5
+{
+  gateway: {
+    bind: "loopback",
+    tailscale: { mode: "serve" }
+  }
+}
+```
+
+Open: `https://<magicdns>/` (or your configured `gateway.controlUi.basePath`)
+
+### Public internet (Funnel + shared password)
+
+```json5
+{
+  gateway: {
+    bind: "loopback",
+    tailscale: { mode: "funnel" },
+    auth: { mode: "password", password: "replace-me" }
+  }
+}
+```
+
+Prefer `NEXUS_GATEWAY_PASSWORD` over committing a password to disk.
+
+## CLI examples
+
+```bash
+nexus gateway --tailscale serve
+nexus gateway --tailscale funnel --auth password
+```
+
+## Notes
+
+- Tailscale Serve/Funnel requires the `tailscale` CLI to be installed and logged in.
+- `tailscale.mode: "funnel"` refuses to start unless auth mode is `password` to avoid public exposure.
+- Set `gateway.tailscale.resetOnExit` if you want Nexus to undo `tailscale serve`
+  or `tailscale funnel` configuration on shutdown.

package/docs/talk.md

@@ -0,0 +1,79 @@
+---
+summary: "Talk mode: continuous speech conversations with ElevenLabs TTS"
+read_when:
+  - Implementing Talk mode on macOS/iOS/Android
+  - Changing voice/TTS/interrupt behavior
+---
+# Talk Mode
+
+Talk mode is a continuous voice conversation loop:
+1) Listen for speech
+2) Send transcript to the model (main session, chat.send)
+3) Wait for the response
+4) Speak it via ElevenLabs (streaming playback)
+
+## Behavior (macOS)
+- **Always-on overlay** while Talk mode is enabled.
+- **Listening → Thinking → Speaking** phase transitions.
+- On a **short pause** (silence window), the current transcript is sent.
+- Replies are **written to WebChat** (same as typing).
+- **Interrupt on speech** (default on): if the user starts talking while the assistant is speaking, we stop playback and note the interruption timestamp for the next prompt.
+
+## Voice directives in replies
+The assistant may prefix its reply with a **single JSON line** to control voice:
+
+```json
+{"voice":"<voice-id>","once":true}
+```
+
+Rules:
+- First non-empty line only.
+- Unknown keys are ignored.
+- `once: true` applies to the current reply only.
+- Without `once`, the voice becomes the new default for Talk mode.
+- The JSON line is stripped before TTS playback.
+
+Supported keys:
+- `voice` / `voice_id` / `voiceId`
+- `model` / `model_id` / `modelId`
+- `speed`, `rate` (WPM), `stability`, `similarity`, `style`, `speakerBoost`
+- `seed`, `normalize`, `lang`, `output_format`, `latency_tier`
+- `once`
+
+## Config (nexus.json)
+```json5
+{
+  "talk": {
+    "voiceId": "elevenlabs_voice_id",
+    "modelId": "eleven_v3",
+    "outputFormat": "mp3_44100_128",
+    "apiKey": "elevenlabs_api_key",
+    "interruptOnSpeech": true
+  }
+}
+```
+
+Defaults:
+- `interruptOnSpeech`: true
+- `voiceId`: falls back to `ELEVENLABS_VOICE_ID` / `SAG_VOICE_ID` (or first ElevenLabs voice when API key is available)
+- `modelId`: defaults to `eleven_v3` when unset
+- `apiKey`: falls back to `ELEVENLABS_API_KEY` (or gateway shell profile if available)
+- `outputFormat`: defaults to `pcm_44100` on macOS/iOS and `pcm_24000` on Android (set `mp3_*` to force MP3 streaming)
+
+## macOS UI
+- Menu bar toggle: **Talk**
+- Config tab: **Talk Mode** group (voice id + interrupt toggle)
+- Overlay:
+  - **Listening**: cloud pulses with mic level
+  - **Thinking**: sinking animation
+  - **Speaking**: radiating rings
+  - Click cloud: stop speaking
+  - Click X: exit Talk mode
+
+## Notes
+- Requires Speech + Microphone permissions.
+- Uses `chat.send` against session key `main`.
+- TTS uses ElevenLabs streaming API with `ELEVENLABS_API_KEY` and incremental playback on macOS/iOS/Android for lower latency.
+- `stability` for `eleven_v3` is validated to `0.0`, `0.5`, or `1.0`; other models accept `0..1`.
+- `latency_tier` is validated to `0..4` when set.
+- Android supports `pcm_16000`, `pcm_22050`, `pcm_24000`, and `pcm_44100` output formats for low-latency AudioTrack streaming.