@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/CAPABILITY_TAXONOMY.md

@@ -0,0 +1,608 @@
+# Nexus Capability Taxonomy
+
+*A comprehensive mapping of capabilities, skills, and the onboarding journey.*
+
+---
+
+## Design Principles
+
+1. **Capabilities are goals, not tools** — "Can agent manage credentials?" not "Is 1Password installed?"
+2. **Multiple providers per capability** — Any qualifying tool satisfies the requirement
+3. **Background detection** — If the tool works, mark capability complete
+4. **Depth before breadth** — Critical unlocks multiply the value of everything else
+5. **Skills have types** — Pure, Tool, or Connector determines when they're usable
+
+---
+
+## Skill Classification
+
+Every skill falls into one of three types based on configuration requirements:
+
+### Pure Skills (Zero Config)
+Just prompts. Agent can use immediately after core onboarding.
+
+### Tool Skills (Agent-Installable)  
+Prompt + open source binary. Agent can install and use without user action.
+
+### Connector Skills (User Config Required)
+Require API keys, credentials, OAuth, or manual setup. User must do something.
+
+---
+
+## What's Actually Usable After Core Onboarding
+
+| Skill | Type | Status | Notes |
+|-------|------|--------|-------|
+| **filesystem** | Pure | ✅ Ready | Just prompts, first wow moment |
+| **computer-use** | Pure | ✅ Ready | Uses Peekaboo on macOS |
+| **peekaboo** | Pure | ✅ Ready | macOS FDA only |
+| **tmux** | Pure | ✅ Ready | If tmux installed |
+| **weather** | Pure | ✅ Ready | Uses free API |
+| **songsee** | Pure | ✅ Ready | Audio visualization |
+| **qmd** | Tool | ✅ Ready | Agent installs binary |
+| **aix** | Tool | ✅ Ready | Agent installs, Cursor users |
+| **video-frames** | Tool | ✅ Ready | Agent installs ffmpeg |
+| **brave-search** | Connector | ❌ Needs API Key | BRAVE_API_KEY required |
+| **nano-pdf** | Connector | ❌ Needs API Key | Uses LLM under the hood |
+| **summarize** | Connector | ❌ Needs API Key | Requires LLM API |
+| **gifgrep** | Connector | ⚠️ Partial | Full access needs GIPHY_API_KEY |
+| **camsnap** | Connector | ❌ Needs Config | Requires camera configuration |
+| **coding-agent** | Connector | ❌ Needs Setup | Requires codex + API key |
+
+**Summary**: After core onboarding, you get ~8-10 immediately usable skills. Everything else is a connector requiring configuration.
+
+---
+
+## The Capability Map
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         CORE ONBOARDING (Linear, Required)                  │
+│                                                                             │
+│  1. ACCESS PLANE ──► 2. NEXUS INSTALL ──► 3. AGENT IDENTITY ──► 4. WORKSPACE│
+│                                                                             │
+│  Immediately Usable: filesystem, computer-use, peekaboo, tmux, weather,    │
+│  songsee, qmd, aix, video-frames                                           │
+│                                                                             │
+│  AI Power: ~10 Capability, 2-3 Alignment, 1 Duration, 1 Throughput         │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                        ════ DEPTH TRACK ════
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    5. CREDENTIAL MANAGEMENT (Recommended)                   │
+│                    (1Password, Bitwarden, etc.)                             │
+│                                                                             │
+│  Can skip but: 2x Capability, 2x Duration — enables agent self-config      │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    6. CLOUD SYNC (Insurance Layer)                          │
+│                    (nexus-cloud, git backup)                                │
+│                                                                             │
+│  Can skip but: Recommended before importing lots of user data              │
+│  Enables: Rollback, fearless agent operations, collaboration               │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                        ════ BREADTH TRACK ════
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                       CAPABILITY EXPANSION (Parallel)                       │
+│                                                                             │
+│  These are all on the SAME LEVEL — user chooses their path:                │
+│                                                                             │
+│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐         │
+│  │ 7. USER COMMS   │    │ 8. USER DATA    │    │ 9. ENABLE       │         │
+│  │ (email, msg,    │    │ (storage, notes │    │    AGENTS       │         │
+│  │  social DMs)    │    │  calendar, code)│    │ (API keys)      │         │
+│  └─────────────────┘    └─────────────────┘    └─────────────────┘         │
+│                                                                             │
+│  User Comms: 2x Capability, +1-2 Alignment (read/send messages for you)    │
+│  User Data: 2x Capability, +Context (files, notes, calendar, GitHub, etc)  │
+│  Enable Agents: Throughput multiplier (agent brain outside IDE)            │
+│                                                                             │
+│  Note: Coding Tools merged into User Data (GitHub, Vercel = your data)     │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                   (Enable Agents unlocks next level)
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    AGENT INDEPENDENCE (Requires: Enable Agents)             │
+│                                                                             │
+│  ┌─────────────────────────┐    ┌─────────────────────────┐                │
+│  │ 10. AGENT COMMUNICATIONS│    │ 11. AUTOMATION          │                │
+│  │     (Discord, Telegram) │    │     (cron, reminders)   │                │
+│  └─────────────────────────┘    └─────────────────────────┘                │
+│                                                                             │
+│  Agent Comms: Realizes throughput gains, remote access, phone control      │
+│  Automation: Largest Duration increase (agent works while you sleep)       │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                            12. FULL POWER                                   │
+│                                                                             │
+│  All capabilities active. Example scenario:                                 │
+│                                                                             │
+│  You get an email about a flight check-in →                                │
+│    Agent reads it (User Data) →                                            │
+│    Uses computer-use to check you in (Pure Skill) →                        │
+│    Sends you a Discord message: "All checked in!" (Agent Comms) →          │
+│    Sets a reminder for departure (Automation)                              │
+│                                                                             │
+│  This requires: User Data + Enable Agents + Agent Comms + Automation       │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Depth vs Breadth
+
+**Depth** = How far down the critical path you've gone (credentials → cloud → agents)
+**Breadth** = How many connectors you've configured at each level
+
+The deeper you go, the more powerful ALL your breadth becomes:
+- Credential Manager at depth means agent can self-configure new connectors
+- Enable Agents at depth means all your connectors can be used autonomously
+- Cloud Sync at depth means you don't fear agent mistakes
+
+You can start going wide early (configure Gmail, GitHub, Discord) but without depth, you're manually entering credentials and babysitting everything.
+
+---
+
+## AI Power Multipliers
+
+Each capability adds to your AI Power (`Capability × Alignment × Duration × Throughput`):
+
+| Capability | Power Impact | Why |
+|------------|--------------|-----|
+| **Core Onboarding** | Baseline: ~10C, 2-3A, 1D, 1T | Agent exists, knows you, has pure skills |
+| **Credential Manager** | 2× Capability, 2× Duration | Trust enables self-config, human out of loop |
+| **Cloud Sync** | Risk insurance | Enables bold agent actions |
+| **User Comms** | 2× Capability, +1-2 Alignment | Read/send messages, relationship context |
+| **User Data** | 2× Capability, +Context | Full picture of your digital life |
+| **Enable Agents** | Throughput multiplier | Brain outside IDE (theoretical until realized) |
+| **Agent Comms** | Realizes Throughput | Agent accessible by phone, can notify you |
+| **Automation** | Largest Duration increase | Was at 1, now potentially 10× |
+
+**Note**: Some connectors offer bigger power jumps than others. Email is huge. Spotify maybe less so. The optimal path prioritizes the biggest multipliers first.
+
+---
+
+## Core Onboarding (Required, Linear)
+
+### 1. Access Plane
+**Goal**: User has a way to interact with agents
+
+| Provider | Skill | Setup | Notes |
+|----------|-------|-------|-------|
+| **Cursor** (recommended) | - | Download + FDA | Best for beginners |
+| Claude Code | coding-agent | Install CLI | Good alternative |
+| Codex CLI | coding-agent | Install CLI | Power users |
+
+**Detection**: `which cursor` or presence of `.cursor/`
+
+### 2. Nexus Installation
+**Goal**: Workspace exists at `~/nexus/`
+
+| Provider | Method | Notes |
+|----------|--------|-------|
+| **nexus init** | CLI | Primary method |
+| Manual | mkdir + files | Fallback |
+
+**Detection**: `~/nexus/AGENTS.md` exists
+
+### 3. Agent Identity
+**Goal**: Agent has name, personality, folder
+
+| Component | File | Created By |
+|-----------|------|------------|
+| Name & Nature | `state/agents/{agent}/identity/IDENTITY.md` | Bootstrap conversation |
+| Personality | `state/agents/{agent}/identity/SOUL.md` | Bootstrap conversation |
+
+**Detection**: `state/agents/{agent}/identity/IDENTITY.md` exists
+
+### 4. Workspace Setup
+**Goal**: IDE configured, user profiled, files organized
+
+| Component | Provider | Notes |
+|-----------|----------|-------|
+| IDE config | `.cursor/rules` update | Dynamic after bootstrap |
+| User profile | `state/user/identity/PROFILE.md` | From conversation + filesystem |
+| File organization | `filesystem` skill | First wow moment |
+
+**Detection**: `state/user/identity/PROFILE.md` exists, `.cursor/rules` has paths
+
+---
+
+## Depth Track
+
+### 5. Credential Management
+**Goal**: Agent can securely store/retrieve secrets
+**Type**: Connector (requires user setup)
+**Can Skip**: Yes, but makes everything 2× harder
+
+| Provider | Skill | Cost | Setup | Notes |
+|----------|-------|------|-------|-------|
+| **1Password** (recommended) | 1password | $3-5/mo | Easy | Touch ID |
+| Bitwarden | (needs skill) | Free | Medium | Open source |
+| pass/gopass | (needs skill) | Free | Hard | CLI purists |
+
+**Detection**: `op whoami` succeeds
+
+**What It Unlocks**:
+- Agent fetches API keys without asking
+- OAuth tokens stored securely
+- Self-configuration of new connectors
+
+### 6. Cloud Sync (Insurance)
+**Goal**: Workspace backed up, collaboration enabled
+**Type**: Connector (requires setup)
+**Can Skip**: Yes, but recommended before importing lots of user data
+
+| Provider | Skill | Cost | Notes |
+|----------|-------|------|-------|
+| Nexus Cloud | nexus-cloud | TBD | Encrypted sync |
+| GitHub (DIY) | github | Free | Manual sync |
+
+**What It Unlocks**:
+- Rollback if agent breaks things
+- Fearless agent operations
+- Collaboration with friends' agents
+
+---
+
+## Breadth Track (All Same Level)
+
+### 7. User Communications
+**Goal**: Agent can read/search your conversations
+**Type**: Connector (OAuth, credentials)
+**Power**: 2× Capability, +1-2 Alignment
+
+#### Email
+
+| Provider | Skill | Setup | Notes |
+|----------|-------|-------|-------|
+| **Gmail** (recommended) | gog | Medium | OAuth |
+| Outlook | (needs skill) | Medium | Microsoft OAuth |
+
+#### Messaging
+
+| Provider | Skill | Setup | Notes |
+|----------|-------|-------|-------|
+| **iMessage** (macOS) | eve, imsg | Easy | FDA only |
+| WhatsApp | wacli | Medium | QR scan |
+| Telegram history | telegram | Easy | Export |
+
+#### Social DMs
+
+| Provider | Skill | Setup | Notes |
+|----------|-------|-------|-------|
+| Discord | discord | Easy | Bot token |
+| Slack | slack | Medium | OAuth |
+
+#### AI History
+
+| Provider | Skill | Setup | Notes |
+|----------|-------|-------|-------|
+| Cursor sessions | aix | Easy | Just works |
+
+**What It Unlocks**:
+- "You haven't texted Mom back in 3 days"
+- Search all your conversations
+- Agent-assisted message drafting
+
+---
+
+### 8. User Data (includes Coding Tools)
+**Goal**: Agent can access your files, notes, code repos
+**Type**: Connector (OAuth, tokens)
+**Power**: 2× Capability, +Context
+
+#### Cloud Storage
+
+| Provider | Skill | Setup | Notes |
+|----------|-------|-------|-------|
+| Google Drive | gog | Medium | OAuth |
+| iCloud | (needs skill) | Hard | Limited APIs |
+
+#### Notes
+
+| Provider | Skill | Setup | Notes |
+|----------|-------|-------|-------|
+| Apple Notes | apple-notes | Easy | Local |
+| Obsidian | obsidian | Easy | Local markdown |
+| Notion | notion | Medium | API key |
+
+#### Calendar
+
+| Provider | Skill | Setup | Notes |
+|----------|-------|-------|-------|
+| Google Calendar | gog | Medium | OAuth |
+| Apple Calendar | (needs skill) | Medium | AppleScript |
+
+#### Code & Dev (merged from Coding Tools)
+
+| Provider | Skill | Setup | Notes |
+|----------|-------|-------|-------|
+| **GitHub** | github | Easy | `gh auth login` |
+| GitLab | (needs skill) | Easy | Token |
+| Vercel | (needs skill) | Easy | Token |
+| Cloudflare | (needs skill) | Easy | Token |
+
+#### Social Data
+
+| Provider | Skill | Setup | Notes |
+|----------|-------|-------|-------|
+| X/Twitter | bird | Easy | Cookie auth |
+
+**What It Unlocks**:
+- Search your notes
+- Access files and documents
+- Calendar context
+- PR management, deployments, CI/CD
+
+---
+
+### 9. Enable Agents (Brain)
+**Goal**: Agent can think outside IDE
+**Type**: Connector (API keys)
+**Power**: Throughput multiplier (theoretical until realized with Agent Comms/Automation)
+
+| Provider | Skill | Cost | Notes |
+|----------|-------|------|-------|
+| **Anthropic** | - | Pay-as-go | Claude |
+| OpenAI | - | Pay-as-go | GPT |
+| Google | gemini | Free tier | Gemini |
+| Ollama | - | Free | Local, needs GPU |
+
+**Detection**: LLM provider credentials present in `credentials/` (or env var fallback)
+
+**⚠️ GATE**: Agent Comms and Automation require this!
+
+---
+
+## Agent Independence (Requires Enable Agents)
+
+### 10. Agent Communications
+**Goal**: User can contact agent outside IDE
+**Type**: Connector (bot tokens, phone numbers)
+**Power**: Realizes throughput gains, remote access
+
+| Provider | Skill | Cost | Setup | Notes |
+|----------|-------|------|-------|-------|
+| **Discord** (recommended!) | discord | Free | Easy | No phone needed |
+| Telegram | telegram | Free | Easy | BotFather |
+| WhatsApp | wacli | Free | Medium | Needs phone |
+| Email | gog | Free | Medium | Agent monitors inbox |
+
+**Why Discord First**:
+1. Free
+2. No phone number required
+3. Cross-platform
+4. Rich features (embeds, reactions)
+5. Easy bot setup
+6. Already have a skill for it
+
+**What It Unlocks**:
+- Text your agent from phone
+- Agent notifications
+- Remote workspace access
+
+### 11. Automation/Productivity
+**Goal**: Agent can schedule tasks
+**Type**: Connector (requires Enable Agents, some need User Data)
+**Power**: Largest Duration increase
+
+| Provider | Skill | Prereqs | Notes |
+|----------|-------|---------|-------|
+| Cron jobs | nexus cron | Enable Agents | Scheduled tasks |
+| Apple Reminders | apple-reminders | User Data | Native macOS |
+| Calendar | gog | User Data | Via Google |
+
+**What It Unlocks**:
+- Morning briefings
+- Scheduled checks
+- Proactive reminders
+- Agent works while you sleep
+
+---
+
+## Full Power Scenarios
+
+When you have everything configured, here's what becomes possible:
+
+### The Flight Check-In
+1. Email arrives about check-in window (User Data: Email)
+2. Agent reads it automatically (Enable Agents: running)
+3. Agent uses computer-use to check you in (Pure Skill)
+4. Agent texts you: "Checked in! Seat 14A" (Agent Comms)
+5. Agent sets reminder for departure time (Automation)
+
+### The Meeting Prep
+1. Calendar shows meeting in 2 hours (User Data: Calendar)
+2. Agent searches your notes about this person (User Data: Notes)
+3. Agent searches email history (User Comms: Email)
+4. Agent summarizes: "Here's context for your call with Sarah..." (Pure Skill)
+5. Sends to your phone (Agent Comms)
+
+### The Forgetful Friend
+1. iMessage shows you haven't texted Mom in a week (User Comms)
+2. Agent drafts a message based on past conversations (Enable Agents)
+3. Sends you a reminder via Discord (Agent Comms)
+4. You approve, agent sends the text (Automation)
+
+---
+
+## Recommended Paths
+
+### The "Mom/Girlfriend" Path (Quickest to Value)
+
+```
+Core Onboarding (15 min)
+  └─ Filesystem wow moment
+      │
+      ▼
+User Comms: iMessage via eve (5 min) ◄── Immediate insight value!
+  └─ "You should text Mom back"
+      │
+      ▼
+Enable Agents: Anthropic API (5 min)
+      │
+      ▼
+Agent Comms: Discord (10 min)
+  └─ Can text agent from phone!
+
+═══════════════════════════════════════
+TOTAL: ~35 min to text-your-agent
+═══════════════════════════════════════
+```
+
+### The "Developer" Path
+
+```
+Core Onboarding (15 min)
+      │
+      ▼
+Credential Mgmt: 1Password (10 min) ◄── Makes everything easier
+      │
+      ▼
+User Data: GitHub (5 min) + Gmail (10 min)
+      │
+      ▼
+Enable Agents: Multiple API keys (5 min)
+      │
+      ▼
+Cloud Sync: nexus-cloud (10 min) ◄── Safety net before going deeper
+      │
+      ▼
+Agent Comms: Discord (10 min)
+      │
+      ▼
+Automation: cron jobs (10 min)
+
+═══════════════════════════════════════
+TOTAL: ~75 min to full automation
+═══════════════════════════════════════
+```
+
+---
+
+## Skill Reference by Type
+
+### Pure Skills (Use Immediately)
+
+| Skill | What It Does |
+|-------|--------------|
+| filesystem | Scan, organize, cleanup files |
+| computer-use | Browser/desktop automation |
+| peekaboo | macOS UI automation |
+| tmux | Terminal session management |
+| weather | Forecasts |
+| songsee | Audio visualization |
+
+### Tool Skills (Agent Installs)
+
+| Skill | What It Does | Installs |
+|-------|--------------|----------|
+| qmd | Local semantic search | qmd binary |
+| aix | Cursor session history | aix binary |
+| video-frames | Extract video frames | ffmpeg |
+
+### Connector Skills by Capability
+
+| Capability | Skills | Requires |
+|------------|--------|----------|
+| Credential Mgmt | 1password | 1Password subscription |
+| User Comms: Email | gog | Google OAuth |
+| User Comms: Messaging | eve, imsg, wacli | FDA / QR scan |
+| User Comms: Social | discord, slack | Bot token / OAuth |
+| User Data: Storage | gog (Drive) | Google OAuth |
+| User Data: Notes | apple-notes, obsidian, notion | App access / API |
+| User Data: Code | github | `gh auth login` |
+| User Data: Social | bird | Cookie auth |
+| Enable Agents | (API keys) | Anthropic/OpenAI/etc account |
+| Agent Comms | discord, telegram, wacli | Bot tokens |
+| Automation | nexus cron | Enable Agents first |
+| Cloud Sync | nexus-cloud | nexus-cloud account |
+
+### Connector Skills (Other)
+
+| Skill | What It Does | Requires |
+|-------|--------------|----------|
+| brave-search | Web search | BRAVE_API_KEY |
+| nano-pdf | PDF editing | LLM API key |
+| summarize | URL/file summarization | LLM API key |
+| gifgrep | GIF search (full) | GIPHY_API_KEY |
+| camsnap | Camera capture | Camera configuration |
+| coding-agent | External coding agents | Codex + API key |
+
+### Uncategorized Utility Skills
+
+| Skill | Type | Notes |
+|-------|------|-------|
+| oracle | Pure | Prompt bundling |
+| model-usage | Pure | Cost tracking |
+| mcporter | Pure | MCP server control |
+| skill-cli-template | Pure | Skill creation |
+
+### Creative Skills (All Connectors)
+
+| Skill | Requires |
+|-------|----------|
+| openai-image-gen | OpenAI API |
+| nano-banana-pro | Gemini API |
+| sag | TTS API |
+| openai-whisper | Local install |
+| openai-whisper-api | OpenAI API |
+
+### Smart Home / IoT (All Connectors)
+
+| Skill | Requires |
+|-------|----------|
+| openhue | Hue Bridge setup |
+| blucli | BluOS setup |
+| sonoscli | Sonos setup |
+| eightctl | Eight Sleep setup |
+| spotify-player | Spotify auth |
+
+### Food & Local (All Connectors)
+
+| Skill | Requires |
+|-------|----------|
+| food-order | Foodora auth |
+| ordercli | Order tracking auth |
+| goplaces | Google API key |
+| local-places | API key |
+
+---
+
+## How the Onboarding Agent Uses This
+
+1. **Identify skill type** — Is it Pure, Tool, or Connector?
+2. **Pure/Tool skills** — Agent can use/install immediately
+3. **Connector skills** — Guide user through setup
+4. **Track depth** — Has user done Credentials? Cloud Sync?
+5. **Update progress** — Write to `state/nexus/onboarding/progress.json`
+6. **Suggest optimal next** — Biggest power multiplier for their current state
+7. **Celebrate unlocks** — "With Email + Enable Agents, your agent can now..."
+
+---
+
+## Key Insight
+
+Every connector adds SOME AI Power. But to maximize power fastest:
+
+1. **Go deep first** — Credentials, then Cloud Sync (optional but recommended)
+2. **Then go wide** — User Comms, User Data, Enable Agents (parallel)
+3. **Then unlock independence** — Agent Comms + Automation (requires Enable Agents)
+
+If you skip depth and go straight to breadth, you're manually entering credentials and babysitting. The depth multiplies everything.
+
+---
+
+*This taxonomy guides all onboarding decisions. Update as new skills are added.*