@intent-systems/nexus 2026.1.5-5 → 2026.1.5-8

package/skills/guides/onboarding/docs/canonical/06_CAPABILITIES_REFERENCE.md

@@ -0,0 +1,207 @@
+# Capabilities Reference
+
+> Exhaustive list of all capabilities and their providers.
+
+---
+
+## Overview
+
+This is the complete mapping of capabilities to providers. Use `nexus capabilities` to see what's active in your workspace.
+
+Agent bootstrap/binding is handled by Cursor hooks (not a capability). See
+`07_AGENT_BINDINGS.md`.
+
+---
+
+## Communication
+
+| Capability | Providers | Setup |
+|------------|-----------|-------|
+| `email-read` | gog + google-oauth | OAuth |
+| `email-send` | gog + google-oauth | OAuth |
+| `messaging-read` | imsg (darwin), eve (darwin), wacli | FDA / QR |
+| `messaging-send` | imsg (darwin), wacli | FDA / QR |
+| `chat-read` | discord, slack | Bot token / OAuth |
+| `chat-send` | discord, slack | Bot token / OAuth |
+| `contacts` | gog + google-oauth | OAuth |
+| `voice` | (TBD) | — |
+
+---
+
+## Social & News
+
+| Capability | Providers | Setup |
+|------------|-----------|-------|
+| `social-x` | bird + twitter | Cookie auth |
+| `social-instagram` | (needs provider) | — |
+| `social-linkedin` | (needs provider) | — |
+| `rss` | blogwatcher | None |
+| `news` | brave-search | API key |
+
+---
+
+## Insights
+
+| Capability | Providers | Setup |
+|------------|-----------|-------|
+| `personal-insights` | eve, comms | FDA |
+| `relationship-insights` | eve, comms | FDA |
+| `session-insights` | aix | None |
+| `communication-insights` | comms | Multiple sources |
+
+---
+
+## Productivity
+
+| Capability | Providers | Setup |
+|------------|-----------|-------|
+| `tasks` | things-mac (darwin), apple-reminders (darwin), trello | App/API |
+| `notes` | apple-notes (darwin), bear-notes (darwin), obsidian, notion | App/API |
+| `calendar` | gog + google-oauth | OAuth |
+| `reminders` | apple-reminders (darwin), gog | App/OAuth |
+| `pdf-processing` | nano-pdf | API key |
+| `collaboration` | nexus-cloud | Account |
+
+---
+
+## Data Access
+
+| Capability | Providers | Setup |
+|------------|-----------|-------|
+| `cloud-storage` | gog + google-oauth | OAuth |
+| `local-files` | filesystem guide | FDA |
+
+---
+
+## Automation
+
+| Capability | Providers | Setup |
+|------------|-----------|-------|
+| `scheduling` | nexus cron | LLM API |
+| `reactive-triggers` | (needs implementation) | LLM API |
+| `gui-automation` | peekaboo (darwin) | FDA |
+| `browser-automation` | computer-use + peekaboo | FDA |
+
+---
+
+## AI & LLM
+
+| Capability | Providers | Setup |
+|------------|-----------|-------|
+| `llm-anthropic` | anthropic connector | API key |
+| `llm-openai` | openai connector | API key |
+| `llm-gemini` | gemini connector | API key |
+| `llm-local` | ollama | Install |
+| `text-to-speech` | elevenlabs | API key |
+| `speech-to-text` | openai-whisper, openai-whisper-api | Install/API |
+| `image-generation` | openai (DALL-E), nano-banana-pro | API key |
+| `summarization` | summarize + LLM | API key |
+
+---
+
+## Smart Home & IoT
+
+| Capability | Providers | Setup |
+|------------|-----------|-------|
+| `smart-lights` | openhue + hue | Bridge auth |
+| `smart-audio` | sonoscli, blucli | Network |
+| `smart-sleep` | eightctl + eightsleep | Account auth |
+| `bluetooth` | blucli (darwin) | None |
+| `camera-control` | camsnap (darwin) | Camera config |
+
+---
+
+## Music
+
+| Capability | Providers | Setup |
+|------------|-----------|-------|
+| `spotify` | spotify-player + spotify | OAuth |
+| `apple-music` | (needs provider) | — |
+| `youtube-music` | (needs provider) | — |
+| `music-detection` | songsee (darwin) | None |
+
+---
+
+## Web
+
+| Capability | Providers | Setup |
+|------------|-----------|-------|
+| `web-search` | brave-search | API key |
+| `web-scraping` | firecrawl, apify | API key |
+| `url-fetch` | summarize | LLM API |
+| `weather` | weather guide | None |
+| `place-search` | goplaces, local-places | API key |
+
+---
+
+## Media & Creative
+
+| Capability | Providers | Setup |
+|------------|-----------|-------|
+| `video-processing` | video-frames (ffmpeg) | Install |
+| `screenshot-annotation` | sag | None |
+| `gif-search` | gifgrep | API key (full) |
+| `transcription` | openai-whisper | Install/API |
+| `document-rendering` | qmd | Install |
+
+---
+
+## Development
+
+| Capability | Providers | Setup |
+|------------|-----------|-------|
+| `version-control` | github | OAuth/token |
+| `vercel` | (needs skill) | API token |
+| `cloudflare` | cloudflare | API token |
+| `aws` | (needs skill) | Credentials |
+| `gcloud` | (needs skill) | Credentials |
+| `coding-agents` | coding-agent guide | Codex + API |
+| `mcp-tools` | mcporter | Install |
+| `git-sync` | upstream-sync | None |
+| `terminal-sessions` | tmux | Install |
+
+---
+
+## Cloud & Sync
+
+| Capability | Providers | Setup |
+|------------|-----------|-------|
+| `cloud-sync` | nexus-cloud | Account |
+| `rollback` | nexus-cloud, github | Account |
+
+---
+
+## Security
+
+| Capability | Providers | Setup |
+|------------|-----------|-------|
+| `credential-management` | 1password, keychain | App/None |
+| `oauth-management` | google-oauth, etc. | OAuth flow |
+
+---
+
+## Commerce
+
+| Capability | Providers | Setup |
+|------------|-----------|-------|
+| `food-ordering` | ordercli, food-order | Account auth |
+
+---
+
+## Platform Notes
+
+- **(darwin)** = macOS only
+- **FDA** = Full Disk Access required
+- **LLM API** = Requires an LLM API key configured
+
+---
+
+## Adding Capabilities
+
+Capabilities emerge from skills. To add a new capability:
+
+1. Create a skill that provides it
+2. Add `provides: [capability-name]` to the skill frontmatter
+3. The capability appears in `nexus capabilities`
+
+The predefined list above is the starting taxonomy. New capabilities can emerge as skills are added.

package/skills/guides/onboarding/docs/canonical/07_AGENT_BINDINGS.md

@@ -0,0 +1,85 @@
+# Agent Bindings
+> How Nexus binds an agent into a workspace session.
+
+---
+
+## Goals
+
+- Deterministic bootstrap (no "remember to run" steps)
+- Consistent identity and memory injection at session start
+- Clear separation between hooks, rules, AGENTS.md, and skills
+
+---
+
+## Binding Layers (Order of Enforcement)
+
+| Layer | Mechanism | Purpose | Notes |
+|------|-----------|---------|-------|
+| 1 | Cursor hooks | Hard gate + context injection | Deterministic |
+| 2 | `AGENTS.md` | Canonical protocol | Human readable, model-facing |
+| 3 | `.cursor/rules` | Persistent guidance | Advisory, not executable |
+| 4 | Skills | How-to docs | Not for bootstrap |
+
+---
+
+## Cursor SessionStart Hook (Required)
+
+The sessionStart hook is the authoritative bootstrap. It runs before the first response and injects identity context.
+
+**Files:**
+- `.cursor/hooks.json`
+- `.cursor/hooks/nexus-session-start.js`
+
+**Responsibilities:**
+1. Run `nexus status --json` when available.
+2. Resolve identity file paths from status output.
+3. Fallback to default identity paths if the CLI is unavailable.
+4. Inject identity + memory + recent logs as additional context.
+5. If identity is missing, include the bootstrap prompt.
+
+### Expected Context Payload
+
+- Agent identity (`IDENTITY.md`)
+- Agent values (`SOUL.md`)
+- Agent memory (`MEMORY.md`)
+- User identity (`IDENTITY.md`, `PROFILE.md` legacy)
+- Recent daily logs (today + yesterday, if present)
+- Bootstrap prompt (when identity is missing)
+
+### Example `hooks.json`
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      { "command": "node .cursor/hooks/nexus-session-start.js" }
+    ]
+  }
+}
+```
+
+---
+
+## AGENTS.md (Fallback Contract)
+
+When hooks are missing or disabled, the agent must:
+1. Run `nexus status`
+2. Read identity + memory files
+3. Read recent daily logs
+
+---
+
+## Rules vs Skills
+
+- `.cursor/rules` = persistent guidance, not executable
+- Skills = documentation for tools, not session bootstrap
+- Hooks = the only deterministic enforcement layer
+
+---
+
+## Related Docs
+
+- `01_NEXUS_OVERVIEW.md` - System overview
+- `02_CLI_REFERENCE.md` - `nexus init` and `nexus status`
+- `03_STATE_ARCHITECTURE.md` - File paths and layout

package/skills/{onboarding → guides/onboarding}/docs/skill-deep-dives/nexus-cloud.md

@@ -114,7 +114,7 @@ wrangler r2 bucket list | grep nexus-blobs
 
 ```bash
 # Deploy the worker and Durable Object
-cd ~/nexus/home/projects/nexus-cloud
+cd ~/nexus/home/projects/nexus/nexus-cloud
 wrangler deploy
 
 # Note the deployed URL (e.g., nexus-cloud.your-account.workers.dev)
@@ -401,7 +401,7 @@ echo "Creating R2 bucket..."
 wrangler r2 bucket create nexus-blobs
 
 echo "Deploying worker..."
-cd ~/nexus/home/projects/nexus-cloud
+cd ~/nexus/home/projects/nexus/nexus-cloud
 wrangler deploy
 
 echo "✅ Cloudflare setup complete!"

package/skills/{onboarding → guides/onboarding}/scripts/ralph/progress.txt

@@ -8,7 +8,7 @@ Started: 2025-01-08
 - Some skills have additional docs in `~/nexus/skills/<name>/docs/`
 - Deep-dive output goes to `~/nexus/skills/onboarding/docs/skill-deep-dives/<name>.md`
 - Use TEMPLATE.md as the format guide
-- Gateway docs (cron, heartbeat) are at `~/nexus/home/projects/nexus/docs/`
+- Gateway docs (cron, heartbeat) are at `~/nexus/home/projects/nexus/nexus-cli/docs/`
 
 ## Key Files
 

package/skills/{nexus-cloud → tools/nexus-cloud}/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: nexus-cloud
 description: "Install and operate the Nexus Cloud CLI for encrypted workspace sync: build the Rust CLI, init/login, enable the background daemon, sync the personal workspace, mount shared workspaces, and explain how shared workspaces are created and shared."
+metadata: {"nexus":{"type":"tool"}}
 ---
 
 # Nexus Cloud CLI
@@ -15,7 +16,7 @@ Keep the security model straight: keys stay local, the server never sees plainte
 
 ## Install and setup (personal workspace)
 
-1. Go to the repo: `~/nexus/home/projects/nexus-cloud`
+1. Go to the repo: `~/nexus/home/projects/nexus/nexus-cloud`
 2. Build the CLI: `./scripts/build-rust-cli.sh`
 3. Point to the binary:
    - `CLI=./rust/target/release/cli`

package/skills/{nexus-cloud → tools/nexus-cloud}/docs/setup.md

@@ -25,7 +25,7 @@ wrangler r2 bucket create nexus-blobs
 ## Deploy the worker
 
 ```bash
-cd ~/nexus/home/projects/nexus-cloud
+cd ~/nexus/home/projects/nexus/nexus-cloud
 wrangler deploy
 ```
 

package/docs/templates/PROFILE.md

@@ -1,14 +0,0 @@
----
-summary: "User profile record"
-read_when:
-  - Bootstrapping a workspace manually
----
-# PROFILE.md - About Your Human
-
-*Fill this in during your first conversation. Keep it concise and factual.*
-
-- **Name:**
-- **Preferred address:**
-- **Pronouns (optional):**
-- **Timezone (optional):**
-- **Notes:**