@intent-systems/nexus 2026.1.5-3

package/docs/home-userspace.md

@@ -0,0 +1,277 @@
+# Nexus Home Userspace
+
+## Overview
+
+Your Nexus home userspace is a portable, user-owned workspace at `~/nexus/home` that contains your customizations, memory, and projects. This directory is designed to be version-controlled with git and backed up to a private remote repository.
+
+## Directory Structure
+
+```
+~/nexus/home/
+├── .git/                    # Git repository (created by nexus init)
+├── .gitignore               # Sensible defaults (created by nexus init)
+├── memory/                  # Daily notes and memory (user-created)
+├── .intent/                 # Intent layer for life/work/projects (user-created)
+├── skills/                  # Workspace skill overrides and custom skills
+└── projects/                # Independent git repos for your projects
+    └── project-name/        # Each project is its own git repo
+```
+
+Identity, credentials, and agent state live under `~/nexus/state/`.
+
+## Git Setup
+
+### Initial Setup
+
+When you run `nexus init`, Nexus automatically:
+1. Creates the `~/nexus/home` directory structure
+2. Initializes a git repository with `git init`
+3. Creates a `.gitignore` file with sensible defaults
+
+### Adding a Git Remote
+
+To back up your home userspace to a private repository:
+
+```bash
+cd ~/nexus/home
+
+# Add your private repository as the remote
+git remote add origin git@github.com:yourusername/nexus-home.git
+
+# Or use HTTPS
+git remote add origin https://github.com/yourusername/nexus-home.git
+
+# Make your first commit
+git add .
+git commit -m "Initial Nexus home setup"
+
+# Push to remote
+git push -u origin main
+```
+
+### Recommended Remote Options
+
+- **GitHub**: Create a private repository at https://github.com/new
+- **GitLab**: Create a private project at https://gitlab.com/projects/new
+- **Gitea/Forgejo**: Self-hosted git server for complete privacy
+- **Company Git**: Use your organization's internal git server
+
+**Important**: Keep this repository **private** as it may contain personal information and preferences.
+
+## What to Commit vs Gitignore
+
+### ✅ Safe to Commit
+
+These files are designed to be version-controlled:
+
+- `memory/` directory (daily notes, agent memory)
+- `.intent/` directory (intent layer artifacts)
+- `skills/` directory (custom skills and overrides)
+- Build/config files specific to your workflow
+
+### ❌ Should Be Gitignored
+
+The default `.gitignore` already excludes:
+
+- `node_modules/`, `venv/`, `__pycache__/` (dependencies)
+- `*.log`, `*.pyc`, `*.pyo` (build artifacts)
+- `.DS_Store`, `Thumbs.db` (OS files)
+- `*.key`, `*.pem`, `*.cert` (secrets)
+- `.env`, `.env.*` (environment files with secrets)
+- Editor files (`.vscode/`, `.idea/`, `*.swp`)
+
+### ⚠️ Projects Directory
+
+The `projects/` directory contains independent git repositories. You have two options:
+
+**Option 1: Gitignore (default)**
+```gitignore
+# Add to .gitignore
+projects/*
+```
+
+Each project maintains its own git history and remotes. You manage them independently.
+
+**Option 2: Git Submodules**
+```bash
+# Explicitly track specific projects as submodules
+git submodule add git@github.com:you/project-a.git projects/project-a
+```
+
+This embeds project commits in your home repo, making it easier to restore exact versions.
+
+**Recommendation**: Start with Option 1 (gitignore). Only use submodules if you need strict version pinning.
+
+## Backup Strategy
+
+### Regular Backups
+
+```bash
+# Daily/weekly routine
+cd ~/nexus/home
+git add .
+git commit -m "Update memory and customizations $(date +%Y-%m-%d)"
+git push
+```
+
+### Automated Backups
+
+Add to your crontab for automatic daily backups:
+
+```bash
+# Edit crontab
+crontab -e
+
+# Add this line (backup at 2 AM daily)
+0 2 * * * cd ~/nexus/home && git add . && git commit -m "Auto backup $(date +\%Y-\%m-\%d)" && git push origin main
+```
+
+Or use a git-based backup tool like [git-sync](https://github.com/simonthum/git-sync) for continuous syncing.
+
+### State Directory Backups
+
+The state directory `~/nexus/state` contains:
+- Credentials and tokens
+- Session transcripts
+- Runtime caches
+- Provider configurations
+
+**This is NOT automatically git-tracked** for security reasons. To back it up:
+
+```bash
+# Manual backup (encrypted recommended)
+tar -czf nexus-state-backup-$(date +%Y%m%d).tar.gz -C ~/nexus state
+
+# Or use rsync for incremental backups
+rsync -av ~/nexus/state/ /path/to/backup/nexus-state/
+
+# Encrypted backup with gpg
+tar -czf - -C ~/nexus state | gpg --symmetric --cipher-algo AES256 > nexus-state-backup.tar.gz.gpg
+```
+
+**Important**: Keep state backups secure as they may contain authentication tokens.
+
+## Restoring on a New Machine
+
+### 1. Install Nexus Core
+
+Install the Nexus CLI on your new machine (via package manager or build from source).
+
+### 2. Clone Your Home Repo
+
+```bash
+# Clone your home userspace
+git clone git@github.com:yourusername/nexus-home.git ~/nexus/home
+cd ~/nexus/home
+```
+
+### 3. Initialize State Directory
+
+```bash
+# Create state directory
+mkdir -p ~/nexus/state
+
+# Restore state from backup (optional)
+tar -xzf nexus-state-backup.tar.gz -C ~/nexus
+
+# Or restore from encrypted backup
+gpg --decrypt nexus-state-backup.tar.gz.gpg | tar -xzf - -C ~/nexus
+```
+
+### 4. Re-authenticate Providers
+
+If you didn't restore state, re-authenticate with providers:
+
+```bash
+nexus login discord
+nexus login telegram
+# etc.
+```
+
+### 5. Verify Setup
+
+```bash
+# Check that everything is working
+nexus doctor
+```
+
+## Multi-Machine Sync
+
+If you work on multiple machines, keep your home userspace in sync:
+
+```bash
+# On Machine A
+cd ~/nexus/home
+git pull --rebase  # Get latest changes
+# ... make changes ...
+git add .
+git commit -m "Update from Machine A"
+git push
+
+# On Machine B
+cd ~/nexus/home
+git pull --rebase  # Get changes from Machine A
+```
+
+**Best Practice**: Always `git pull --rebase` before starting work to avoid merge conflicts.
+
+## Security Considerations
+
+1. **Private Repository**: Keep your home repo private. It contains personal information and preferences.
+
+2. **No Secrets in Home**: Never commit secrets (API keys, tokens, passwords) to `~/nexus/home`. Use the state directory (`~/nexus/state`) for secrets, or use environment variables.
+
+3. **Review Before Commit**: Check what you're committing:
+   ```bash
+   git status
+   git diff
+   ```
+
+4. **Sensitive Files**: If you accidentally commit sensitive data, use tools like [BFG Repo-Cleaner](https://rtyley.github.io/bfg-repo-cleaner/) or `git filter-repo` to remove it from history.
+
+5. **State Backups**: Encrypt state directory backups since they contain credentials.
+
+## Troubleshooting
+
+### Git Not Initialized
+
+If `git init` failed during `nexus init`:
+
+```bash
+cd ~/nexus/home
+git init
+git add .
+git commit -m "Initial commit"
+```
+
+### Lost Remote Connection
+
+If you need to change or re-add the remote:
+
+```bash
+cd ~/nexus/home
+git remote remove origin
+git remote add origin git@github.com:yourusername/new-repo.git
+git push -u origin main
+```
+
+### Merge Conflicts
+
+If you have conflicts after `git pull`:
+
+```bash
+# View conflicts
+git status
+
+# Edit conflicting files, then:
+git add .
+git commit -m "Resolve merge conflicts"
+git push
+```
+
+## See Also
+
+- [ADR 003: Nexus Home Workspace and State Layout](../.intent/decisions/003-nexus-home-workspace-and-state-layout.md)
+- [Three-Layer Architecture](../.intent/decisions/004-three-layer-architecture.md)
+- `nexus init --help` - Initialize home workspace
+- `nexus reset --help` - Reset workspace for testing

package/docs/hubs.md

@@ -0,0 +1,148 @@
+---
+summary: "Hubs that link to every Nexus doc"
+read_when:
+  - You want a complete map of the documentation
+---
+# Docs hubs
+
+Use these hubs to discover every page, including deep dives and reference docs that don’t appear in the left nav.
+
+## Start here
+
+- [Index](https://docs.nexus.bot)
+- [Onboarding](https://docs.nexus.bot/onboarding)
+- [Wizard](https://docs.nexus.bot/wizard)
+- [Setup](https://docs.nexus.bot/setup)
+- [FAQ](https://docs.nexus.bot/faq)
+- [Configuration](https://docs.nexus.bot/configuration)
+- [Nexus (personal assistant)](https://docs.nexus.bot/nexus)
+- [Lore](https://docs.nexus.bot/lore)
+
+## Installation + distribution
+
+- [Docker](https://docs.nexus.bot/docker)
+- [Nix](https://docs.nexus.bot/nix)
+
+## Core concepts
+
+- [Architecture](https://docs.nexus.bot/architecture)
+- [Agent runtime](https://docs.nexus.bot/agent)
+- [Agent loop](https://docs.nexus.bot/agent-loop)
+- [Multi-agent routing](https://docs.nexus.bot/multi-agent)
+- [Sessions](https://docs.nexus.bot/session)
+- [Sessions (alias)](https://docs.nexus.bot/sessions)
+- [Session tools](https://docs.nexus.bot/session-tool)
+- [Queue](https://docs.nexus.bot/queue)
+- [RPC adapters](https://docs.nexus.bot/rpc)
+- [TypeBox schemas](https://docs.nexus.bot/typebox)
+- [Presence](https://docs.nexus.bot/presence)
+- [Discovery + transports](https://docs.nexus.bot/discovery)
+- [Bonjour](https://docs.nexus.bot/bonjour)
+- [Channel routing](https://docs.nexus.bot/channel-routing)
+- [Groups](https://docs.nexus.bot/groups)
+- [Group messages](https://docs.nexus.bot/group-messages)
+
+## Providers + ingress
+
+- [WhatsApp](https://docs.nexus.bot/whatsapp)
+- [Telegram](https://docs.nexus.bot/telegram)
+- [Telegram (grammY notes)](https://docs.nexus.bot/grammy)
+- [Slack](https://docs.nexus.bot/slack)
+- [Discord](https://docs.nexus.bot/discord)
+- [Signal](https://docs.nexus.bot/signal)
+- [iMessage](https://docs.nexus.bot/imessage)
+- [WebChat](https://docs.nexus.bot/webchat)
+- [Webhooks](https://docs.nexus.bot/webhook)
+- [Gmail Pub/Sub](https://docs.nexus.bot/gmail-pubsub)
+
+## Gateway + operations
+
+- [Gateway runbook](https://docs.nexus.bot/gateway)
+- [Gateway pairing](https://docs.nexus.bot/gateway/pairing)
+- [Gateway lock](https://docs.nexus.bot/gateway-lock)
+- [Background process](https://docs.nexus.bot/background-process)
+- [Health](https://docs.nexus.bot/health)
+- [Heartbeat](https://docs.nexus.bot/heartbeat)
+- [Doctor](https://docs.nexus.bot/doctor)
+- [Logging](https://docs.nexus.bot/logging)
+- [Dashboard](https://docs.nexus.bot/dashboard)
+- [Control UI](https://docs.nexus.bot/control-ui)
+- [Remote access](https://docs.nexus.bot/remote)
+- [Remote gateway README](https://docs.nexus.bot/remote-gateway-readme)
+- [Tailscale](https://docs.nexus.bot/tailscale)
+- [Security](https://docs.nexus.bot/security)
+- [Troubleshooting](https://docs.nexus.bot/troubleshooting)
+
+## Tools + automation
+
+- [Tools surface](https://docs.nexus.bot/tools)
+- [Exec tool](https://docs.nexus.bot/exec)
+- [Elevated mode](https://docs.nexus.bot/elevated)
+- [Cron + wakeups](https://docs.nexus.bot/cron)
+- [Thinking + verbose](https://docs.nexus.bot/thinking)
+- [Models](https://docs.nexus.bot/models)
+- [Agent send CLI](https://docs.nexus.bot/agent-send)
+- [Terminal UI](https://docs.nexus.bot/tui)
+- [Browser control](https://docs.nexus.bot/browser)
+- [Browser (Linux troubleshooting)](https://docs.nexus.bot/browser-linux-troubleshooting)
+
+## Nodes, media, voice
+
+- [Nodes overview](https://docs.nexus.bot/nodes)
+- [Camera](https://docs.nexus.bot/camera)
+- [Images](https://docs.nexus.bot/images)
+- [Audio](https://docs.nexus.bot/audio)
+- [Location command](https://docs.nexus.bot/location-command)
+- [Voice wake](https://docs.nexus.bot/voicewake)
+- [Talk mode](https://docs.nexus.bot/talk)
+
+## Platforms
+
+- [macOS app overview](https://docs.nexus.bot/macos)
+- [macOS dev setup](https://docs.nexus.bot/mac/dev-setup)
+- [macOS menu bar](https://docs.nexus.bot/mac/menu-bar)
+- [macOS voice wake](https://docs.nexus.bot/mac/voicewake)
+- [macOS voice overlay](https://docs.nexus.bot/mac/voice-overlay)
+- [macOS WebChat](https://docs.nexus.bot/mac/webchat)
+- [macOS Canvas](https://docs.nexus.bot/mac/canvas)
+- [macOS child process](https://docs.nexus.bot/mac/child-process)
+- [macOS health](https://docs.nexus.bot/mac/health)
+- [macOS icon](https://docs.nexus.bot/mac/icon)
+- [macOS logging](https://docs.nexus.bot/mac/logging)
+- [macOS permissions](https://docs.nexus.bot/mac/permissions)
+- [macOS remote](https://docs.nexus.bot/mac/remote)
+- [macOS signing](https://docs.nexus.bot/mac/signing)
+- [macOS release](https://docs.nexus.bot/mac/release)
+- [macOS bun gateway](https://docs.nexus.bot/mac/bun)
+- [macOS XPC](https://docs.nexus.bot/mac/xpc)
+- [macOS skills](https://docs.nexus.bot/mac/skills)
+- [macOS Peekaboo plan](https://docs.nexus.bot/mac/peekaboo)
+- [iOS node](https://docs.nexus.bot/ios)
+- [Android node](https://docs.nexus.bot/android)
+- [Windows app](https://docs.nexus.bot/windows)
+- [Linux app](https://docs.nexus.bot/linux)
+- [Web surfaces](https://docs.nexus.bot/web)
+
+## Workspace + templates
+
+- [Skills](https://docs.nexus.bot/skills)
+- [Skills config](https://docs.nexus.bot/skills-config)
+- [Default AGENTS](https://docs.nexus.bot/AGENTS.default)
+- [Templates: AGENTS](https://docs.nexus.bot/templates/AGENTS)
+- [Templates: BOOTSTRAP](https://docs.nexus.bot/templates/BOOTSTRAP)
+- [Templates: IDENTITY](https://docs.nexus.bot/templates/IDENTITY)
+- [Templates: SOUL](https://docs.nexus.bot/templates/SOUL)
+- [Templates: TOOLS](https://docs.nexus.bot/templates/TOOLS)
+- [Templates: USER](https://docs.nexus.bot/templates/USER)
+
+## Experiments + proposals
+
+- [Onboarding config protocol](https://docs.nexus.bot/onboarding-config-protocol)
+- [Research: memory](https://docs.nexus.bot/research/memory)
+- [Proposal: model config](https://docs.nexus.bot/proposals/model-config)
+
+## Testing + release
+
+- [Testing](https://docs.nexus.bot/test)
+- [Release checklist](https://docs.nexus.bot/RELEASING)
+- [Device models](https://docs.nexus.bot/device-models)

package/docs/images.md

@@ -0,0 +1,51 @@
+---
+summary: "Image and media handling rules for send, gateway, and agent replies"
+read_when:
+  - Modifying media pipeline or attachments
+---
+# Image & Media Support — 2025-12-05
+
+NEXUS is now **web-only** (Baileys). This document captures the current media handling rules for send, gateway, and agent replies.
+
+## Goals
+- Send media with optional captions via `nexus send --media`.
+- Allow auto-replies from the web inbox to include media alongside text.
+- Keep per-type limits sane and predictable.
+
+## CLI Surface
+- `nexus send --media <path-or-url> [--message <caption>]`
+  - `--media` optional; caption can be empty for media-only sends.
+  - `--dry-run` prints the resolved payload; `--json` emits `{ provider, to, messageId, mediaUrl, caption }`.
+
+## Web Provider Behavior
+- Input: local file path **or** HTTP(S) URL.
+- Flow: load into a Buffer, detect media kind, and build the correct payload:
+  - **Images:** resize & recompress to JPEG (max side 2048px) targeting `agent.mediaMaxMb` (default 5 MB), capped at 6 MB.
+  - **Audio/Voice/Video:** pass-through up to 16 MB; audio is sent as a voice note (`ptt: true`).
+  - **Documents:** anything else, up to 100 MB, with filename preserved when available.
+- WhatsApp GIF-style playback: send an MP4 with `gifPlayback: true` (CLI: `--gif-playback`) so mobile clients loop inline.
+- MIME detection prefers magic bytes, then headers, then file extension.
+- Caption comes from `--message` or `reply.text`; empty caption is allowed.
+- Logging: non-verbose shows `↩️`/`✅`; verbose includes size and source path/URL.
+
+## Auto-Reply Pipeline
+- `getReplyFromConfig` returns `{ text?, mediaUrl?, mediaUrls? }`.
+- When media is present, the web sender resolves local paths or URLs using the same pipeline as `nexus send`.
+- Multiple media entries are sent sequentially if provided.
+
+## Inbound Media to Commands (Pi)
+- When inbound web messages include media, NEXUS downloads to a temp file and exposes templating variables:
+  - `{{MediaUrl}}` pseudo-URL for the inbound media.
+  - `{{MediaPath}}` local temp path written before running the command.
+- When a per-session Docker sandbox is enabled, inbound media is copied into the sandbox workspace and `MediaPath`/`MediaUrl` are rewritten to a relative path like `media/inbound/<filename>`.
+- Audio transcription (if configured) runs before templating and can replace `Body` with the transcript.
+
+## Limits & Errors
+- Images: ~6 MB cap after recompression.
+- Audio/voice/video: 16 MB cap; documents: 100 MB cap.
+- Oversize or unreadable media → clear error in logs and the reply is skipped.
+
+## Notes for Tests
+- Cover send + reply flows for image/audio/document cases.
+- Validate recompression for images (size bound) and voice-note flag for audio.
+- Ensure multi-media replies fan out as sequential sends.

package/docs/imessage.md

@@ -0,0 +1,94 @@
+---
+summary: "iMessage support via imsg (JSON-RPC over stdio), setup, and chat_id routing"
+read_when:
+  - Setting up iMessage support
+  - Debugging iMessage send/receive
+---
+# iMessage (imsg)
+
+Status: external CLI integration. No daemon.
+
+## Model
+- Nexus spawns `imsg rpc` as a child process.
+- JSON-RPC runs over stdin/stdout (one JSON object per line).
+- Gateway owns the process; no TCP port needed.
+
+## Multi-account (Apple IDs)
+
+iMessage “multi-account” in one Gateway process is not currently supported in a meaningful way:
+- Messages accounts are owned by the signed-in macOS user session.
+- `imsg` reads the local Messages DB and sends via that user’s configured services.
+- There isn’t a robust “pick AppleID X as the sender” switch we can depend on.
+
+### Practical approach: multiple gateways on multiple Macs/users
+
+If you need two iMessage identities:
+- Run one Gateway on each macOS user/machine that’s signed into the desired Apple ID.
+- Connect to the desired Gateway remotely (Tailscale preferred; SSH tunnel is the universal fallback).
+
+See:
+- `docs/remote.md` (SSH tunnel to `127.0.0.1:18789`)
+- `docs/discovery.md` (bridge vs SSH transport model)
+
+### Could we do “iMessage over SSH” from a single Gateway?
+
+Maybe, but it’s a new design:
+- Outbound could theoretically pipe `imsg rpc` over SSH (stdio bridge).
+- Inbound still needs a remote watcher (DB polling / event stream) and a transport back to the main Gateway.
+
+That’s closer to “remote provider instances” (or “multi-gateway aggregation”) than a small config tweak.
+
+## Requirements
+- macOS with Messages signed in.
+- Full Disk Access for Nexus + the `imsg` binary (Messages DB access).
+- Automation permission for Messages when sending.
+
+## Config
+
+```json5
+{
+  imessage: {
+    enabled: true,
+    cliPath: "imsg",
+    dbPath: "~/Library/Messages/chat.db",
+    dmPolicy: "pairing", // pairing | allowlist | open | disabled
+    allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
+    groupPolicy: "open",
+    groupAllowFrom: ["chat_id:123"],
+    includeAttachments: false,
+    mediaMaxMb: 16,
+    service: "auto",
+    region: "US"
+  }
+}
+```
+
+Notes:
+- `allowFrom` accepts handles (phone/email) or `chat_id:<id>` entries.
+- Default: `imessage.dmPolicy="pairing"` — unknown DM senders get a pairing code (approve via `nexus pairing approve --provider imessage <code>`). `"open"` requires `allowFrom=["*"]`.
+- `groupPolicy` controls group handling (`open|disabled|allowlist`).
+- `groupAllowFrom` accepts the same entries as `allowFrom`.
+- `service` defaults to `auto` (use `imessage` or `sms` to pin).
+- `region` is only used for SMS targeting.
+
+## Addressing / targets
+
+Prefer `chat_id` for stable routing:
+- `chat_id:123` (preferred)
+- `chat_guid:...` (fallback)
+- `chat_identifier:...` (fallback)
+- direct handles: `imessage:+1555` / `sms:+1555` / `user@example.com`
+
+List chats:
+```
+imsg chats --limit 20
+```
+
+## Group chat behavior
+- Group messages set `ChatType=group`, `GroupSubject`, and `GroupMembers`.
+- Group activation respects `imessage.groups."*".requireMention` and `routing.groupChat.mentionPatterns` (patterns are required to detect mentions on iMessage). When `imessage.groups` is set, it also acts as a group allowlist; include `"*"` to allow all groups.
+- Replies go back to the same `chat_id` (group or direct).
+
+## Troubleshooting
+- `nexus gateway call providers.status --params '{"probe":true}'`
+- Verify `imsg` is on PATH and has access to Messages DB.