@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/CAPABILITIES.md

@@ -0,0 +1,444 @@
+# Nexus Capabilities
+
+> Complete taxonomy of ALL capabilities provided by nexus core tools, connectors, and guides.
+
+---
+
+## Overview
+
+Capabilities are **what your agent can do**, not **which tools are installed**. A single capability can be satisfied by multiple providers, and a single provider can enable multiple capabilities.
+
+```
+Capability (abstract)  →  Provider (concrete)
+     email             →  gog + google-oauth
+     messaging         →  imsg, eve, wacli
+     chat              →  discord, slack
+```
+
+**Key principles**: 
+- Things can have multiple capabilities (`nexus-cloud` → `cloud-sync` + `collaboration`)
+- Some tools provide read vs write separately (e.g., can read emails but not send)
+- Capabilities should be granular enough to capture what's actually possible
+
+---
+
+## Capability Categories
+
+### 🗣️ Communication
+
+How you talk to people — personal and group messaging across all channels.
+
+| Capability | Description | Providers | Setup |
+|------------|-------------|-----------|-------|
+| `email-read` | Read emails | gog + google-oauth | OAuth |
+| `email-send` | Send emails | gog + google-oauth | OAuth |
+| `messaging-read` | Read messages (SMS, iMessage, WhatsApp, Telegram) | imsg (darwin), eve (darwin), wacli | FDA / QR |
+| `messaging-send` | Send messages | imsg (darwin), wacli | FDA / QR |
+| `voice` | Phone calls and meetings | (TBD) | - |
+| `chat-read` | Read chat (Discord, Slack servers/channels) | discord, slack | Bot token / OAuth |
+| `chat-send` | Send to chat | discord, slack | Bot token / OAuth |
+| `contacts` | Address book, contact info | gog + google-oauth | OAuth |
+
+**Note**: Read vs send are separate capabilities — some tools can read but not send, or vice versa.
+
+### 📱 Social & News
+
+Social media feeds, posts, and news aggregation — consumption & publishing.
+
+| Capability | Description | Providers | Setup |
+|------------|-------------|-----------|-------|
+| `social-x` | X/Twitter feed & posting | bird + twitter | Cookie auth |
+| `social-instagram` | Instagram feed & posting | (needs provider) | - |
+| `social-linkedin` | LinkedIn feed & posting | (needs provider) | - |
+| `rss` | RSS feed monitoring | blogwatcher | None |
+| `news` | News from multiple sources | brave-search | API key |
+
+**Note**: Social DMs belong in Communication, feeds belong here.
+
+### 🔮 Insights
+
+Analytics and analysis from your personal data — understanding yourself and relationships.
+
+| Capability | Description | Providers | Setup |
+|------------|-------------|-----------|-------|
+| `personal-insights` | Insights about you from your data | eve (darwin), comms | FDA |
+| `relationship-insights` | Who you talk to, communication patterns | eve, comms | FDA |
+| `session-insights` | AI conversation analysis | aix | None |
+| `communication-insights` | Response times, frequency, trends | comms | Multiple sources |
+
+**Why its own category?** These tools don't just *access* data, they *analyze* it for insight. Eve reading your messages is `messaging-read`. Eve telling you "you haven't texted Mom in 5 days" is `relationship-insights`.
+
+### 📋 Productivity
+
+Task management, notes, calendar, documents — getting things done.
+
+| Capability | Description | Providers | Setup |
+|------------|-------------|-----------|-------|
+| `tasks` | Todo lists, task management | things-mac (darwin), apple-reminders (darwin), trello | App/API |
+| `notes` | Note-taking, knowledge base | apple-notes (darwin), bear-notes (darwin), obsidian, notion | App/API |
+| `calendar` | Events, scheduling | gog + google-oauth | OAuth |
+| `reminders` | Time-based notifications | apple-reminders (darwin), gog | App/OAuth |
+| `pdf-processing` | Read/edit PDFs | nano-pdf | API key |
+| `collaboration` | Multi-user coordination | nexus-cloud | Account |
+
+### 💾 Data Access
+
+Access to files and storage — your digital life.
+
+| Capability | Description | Providers | Setup |
+|------------|-------------|-----------|-------|
+| `cloud-storage` | Google Drive, Dropbox, etc. | gog + google-oauth | OAuth |
+| `local-files` | Filesystem access | filesystem guide | FDA |
+
+### 🤖 Automation
+
+Scheduled tasks, reactive triggers, and autonomous screen control.
+
+| Capability | Description | Providers | Setup |
+|------------|-------------|-----------|-------|
+| `scheduling` | Time-based task execution (cron) | nexus cron | LLM API |
+| `reactive-triggers` | Event-driven automation | (needs implementation) | LLM API |
+| `gui-automation` | Screen/mouse/keyboard control | peekaboo (darwin) | FDA |
+| `browser-automation` | Web browsing automation | computer-use guide + peekaboo | FDA |
+
+**Key distinction**: 
+- `scheduling` = "Run this every morning at 7am"
+- `reactive-triggers` = "When I get an email about flight check-in, run this"
+
+Both require LLM API keys to actually execute.
+
+### 🧠 AI & LLM
+
+Language models, voice, image generation — the agent's brain.
+
+| Capability | Description | Providers | Setup |
+|------------|-------------|-----------|-------|
+| `anthropic` | Claude models | anthropic connector | API key |
+| `openai` | GPT models | openai connector | API key |
+| `gemini` | Gemini models | gemini connector | API key |
+| `local-llm` | Local models (Ollama) | ollama | Install |
+| `text-to-speech` | Voice synthesis | elevenlabs | API key |
+| `speech-to-text` | Transcription | openai-whisper, openai-whisper-api | Install/API |
+| `image-generation` | Generate images | openai (DALL-E), nano-banana-pro | API key |
+| `summarization` | Summarize content | summarize + LLM | API key |
+
+### 🏠 Smart Home & IoT
+
+Control your physical environment.
+
+| Capability | Description | Providers | Setup |
+|------------|-------------|-----------|-------|
+| `smart-lights` | Philips Hue, etc. | openhue + hue | Bridge auth |
+| `smart-audio` | Sonos, BluOS | sonoscli, blucli | Network |
+| `smart-sleep` | Eight Sleep | eightctl + eightsleep | Account auth |
+| `bluetooth` | Bluetooth device control | blucli (darwin) | None |
+| `camera-control` | Take photos, webcam | camsnap (darwin) | Camera config |
+
+### 🎵 Music
+
+Music playback and control.
+
+| Capability | Description | Providers | Setup |
+|------------|-------------|-----------|-------|
+| `spotify` | Spotify playback | spotify-player + spotify | OAuth |
+| `apple-music` | Apple Music | (needs provider) | - |
+| `youtube-music` | YouTube Music | (needs provider) | - |
+| `music-detection` | Identify songs playing | songsee (darwin) | None |
+
+### 🌐 Web
+
+Web search, scraping, and content retrieval.
+
+| Capability | Description | Providers | Setup |
+|------------|-------------|-----------|-------|
+| `web-search` | Search the web | brave-search | API key |
+| `web-scraping` | Extract web content | firecrawl, apify | API key |
+| `url-fetch` | Fetch/render URLs | summarize | LLM API |
+| `weather` | Weather forecasts | weather guide | None (free API) |
+| `place-search` | Find businesses/locations | goplaces, local-places | API key |
+
+### 🎨 Media & Creative
+
+Photos, video, audio, documents.
+
+| Capability | Description | Providers | Setup |
+|------------|-------------|-----------|-------|
+| `video-processing` | Extract frames, edit | video-frames (ffmpeg) | Install |
+| `screenshot-annotation` | Annotate screenshots | sag | None |
+| `gif-search` | Find GIFs | gifgrep | API key (full) |
+| `transcription` | Audio to text | openai-whisper, openai-whisper-api | Install/API |
+| `document-rendering` | Render markdown/docs to PDF | qmd | Install |
+
+### 💻 Development
+
+Coding, version control, and cloud deployment.
+
+| Capability | Description | Providers | Setup |
+|------------|-------------|-----------|-------|
+| `version-control` | Git repos (GitHub, GitLab) | github | OAuth/token |
+| `vercel` | Vercel deployments | (needs skill) | API token |
+| `cloudflare` | Cloudflare Workers/Pages | cloudflare | API token |
+| `aws` | AWS services | (needs skill) | Credentials |
+| `gcloud` | Google Cloud services | (needs skill) | Credentials |
+| `coding-agents` | External coding tools | coding-agent guide | Codex + API |
+| `mcp-tools` | MCP server management | mcporter | Install |
+| `git-sync` | Sync git repos | upstream-sync | None |
+| `terminal-sessions` | Tmux management | tmux | Install |
+
+### ☁️ Cloud & Sync
+
+Backup, sync, and collaboration.
+
+| Capability | Description | Providers | Setup |
+|------------|-------------|-----------|-------|
+| `cloud-sync` | Backup workspace | nexus-cloud | Account |
+| `cloud-storage` | Google Drive access | gog + google-oauth | OAuth |
+| `rollback` | Version history | nexus-cloud, github | Account |
+
+### 🔐 Security
+
+Credential and secret management.
+
+| Capability | Description | Providers | Setup |
+|------------|-------------|-----------|-------|
+| `credential-management` | Secure secret storage | 1password, keychain | App/None |
+| `oauth-management` | OAuth token handling | google-oauth, etc. | OAuth flow |
+
+### 🍔 Food & Commerce
+
+Ordering and transactions.
+
+| Capability | Description | Providers | Setup |
+|------------|-------------|-----------|-------|
+| `food-ordering` | Order food delivery | ordercli, food-order | Account auth |
+
+---
+
+## Capability Status Levels
+
+Each capability can be in one of these states:
+
+| Emoji | Status | Meaning |
+|-------|--------|---------|
+| ⛔ | `unavailable` | Not available on this OS/platform |
+| 📥 | `needs-install` | Tool/binary needs to be installed |
+| 🔧 | `needs-setup` | Installed but needs credential/config |
+| ⭐ | `ready` | Fully configured, ready to use |
+| ✅ | `active` | Configured AND has been used |
+| ❌ | `broken` | Was working but now failing |
+
+Example status output:
+```
+📧 email-read, email-send
+   ✅ active (via gog) - last used 2h ago
+   
+💬 chat-discord  
+   🔧 needs-setup - discord connector needs bot token
+   
+📱 messaging-read
+   ⭐ ready (via imsg) - configured, never used
+   
+🎵 apple-music
+   ⛔ unavailable - no provider exists yet
+   
+🎬 video-processing
+   📥 not-installed - ffmpeg binary not found
+```
+
+---
+
+## Capability → Provider Mapping
+
+### Communication
+| Capability | Providers |
+|------------|-----------|
+| email-read | `gog` + `google-oauth` |
+| email-send | `gog` + `google-oauth` |
+| messaging-read | `imsg` (darwin), `eve` (darwin), `wacli` |
+| messaging-send | `imsg` (darwin), `wacli` |
+| voice | (TBD) |
+| chat-read | `discord`, `slack` |
+| chat-send | `discord`, `slack` |
+| contacts | `gog` + `google-oauth` |
+
+### Social & News
+| Capability | Providers |
+|------------|-----------|
+| social-x | `bird` + `twitter` |
+| social-instagram | (needs provider) |
+| social-linkedin | (needs provider) |
+| rss | `blogwatcher` |
+| news | `brave-search` |
+
+### Insights
+| Capability | Providers |
+|------------|-----------|
+| personal-insights | `eve` (darwin), `comms` |
+| relationship-insights | `eve`, `comms` |
+| session-insights | `aix` |
+| communication-insights | `comms` |
+
+### Productivity
+| Capability | Providers |
+|------------|-----------|
+| tasks | `things-mac` (darwin), `apple-reminders` (darwin), `trello` |
+| notes | `apple-notes` (darwin), `bear-notes` (darwin), `obsidian`, `notion` |
+| calendar | `gog` + `google-oauth` |
+| reminders | `apple-reminders` (darwin), `gog` |
+| pdf-processing | `nano-pdf` |
+| collaboration | `nexus-cloud` |
+
+### Data Access
+| Capability | Providers |
+|------------|-----------|
+| cloud-storage | `gog` + `google-oauth` |
+| local-files | `filesystem` |
+
+### Automation
+| Capability | Providers |
+|------------|-----------|
+| scheduling | `nexus cron` (+ LLM) |
+| reactive-triggers | (needs implementation) |
+| gui-automation | `peekaboo` (darwin) |
+| browser-automation | `computer-use` + `peekaboo` |
+
+### AI & LLM
+| Capability | Providers |
+|------------|-----------|
+| anthropic | `anthropic` connector |
+| openai | `openai` connector |
+| gemini | `gemini` connector |
+| local-llm | `ollama` |
+| text-to-speech | `elevenlabs` |
+| speech-to-text | `openai-whisper`, `openai-whisper-api` |
+| image-generation | `openai`, `nano-banana-pro` |
+| summarization | `summarize` + LLM |
+
+### Smart Home
+| Capability | Providers |
+|------------|-----------|
+| smart-lights | `openhue` + `hue` |
+| smart-audio | `sonoscli`, `blucli` |
+| smart-sleep | `eightctl` + `eightsleep` |
+| bluetooth | `blucli` (darwin) |
+| camera-control | `camsnap` (darwin) |
+
+### Music
+| Capability | Providers |
+|------------|-----------|
+| spotify | `spotify-player` + `spotify` |
+| apple-music | (needs provider) |
+| youtube-music | (needs provider) |
+| music-detection | `songsee` (darwin) |
+
+### Web
+| Capability | Providers |
+|------------|-----------|
+| web-search | `brave-search` |
+| web-scraping | `firecrawl`, `apify` |
+| url-fetch | `summarize` |
+| weather | `weather` guide |
+| place-search | `goplaces`, `local-places` |
+
+### Media
+| Capability | Providers |
+|------------|-----------|
+| video-processing | `video-frames` |
+| screenshot-annotation | `sag` |
+| gif-search | `gifgrep` |
+| transcription | `openai-whisper`, `openai-whisper-api` |
+| document-rendering | `qmd` |
+
+### Development
+| Capability | Providers |
+|------------|-----------|
+| version-control | `github` |
+| vercel | (needs skill) |
+| cloudflare | `cloudflare` connector |
+| aws | (needs skill) |
+| gcloud | (needs skill) |
+| coding-agents | `coding-agent` |
+| mcp-tools | `mcporter` |
+| git-sync | `upstream-sync` |
+| terminal-sessions | `tmux` |
+
+### Cloud & Sync
+| Capability | Providers |
+|------------|-----------|
+| cloud-sync | `nexus-cloud` |
+| cloud-storage | `gog` + `google-oauth` |
+| rollback | `nexus-cloud`, `github` |
+
+### Security
+| Capability | Providers |
+|------------|-----------|
+| credential-management | `1password`, keychain |
+| oauth-management | various connectors |
+
+### Commerce
+| Capability | Providers |
+|------------|-----------|
+| food-ordering | `ordercli`, `food-order` |
+
+---
+
+## Abstract Dependencies
+
+Tools and guides can declare abstract capability requirements:
+
+```yaml
+# Instead of:
+requires:
+  tools: [gog]
+
+# Use:
+requires:
+  capabilities: [email-read]  # Any email provider works
+```
+
+This enables portability — if someone uses Outlook instead of Gmail, the skill still works as long as `email-read` capability is satisfied.
+
+### Example: Morning Briefing Automation
+
+```yaml
+name: morning-briefing
+type: guide
+
+requires:
+  capabilities:
+    - email-read      # Any email provider
+    - calendar        # Any calendar provider
+    - weather         # Free, always available
+  anyCapabilities:
+    - chat-send       # Or messaging-send
+    - messaging-send  # One way to reach user
+```
+
+---
+
+## What This Enables
+
+### For `nexus status`
+Show which capabilities are active:
+```
+Capabilities: 15/58 active
+
+🗣️ Communication:
+  ✅ email-read, email-send (gog)
+  ✅ messaging-read (eve, imsg)
+  ⭐ chat-read, chat-send (discord) - ready, never used
+  
+🔮 Insights:
+  ✅ relationship-insights (eve)
+  ⭐ session-insights (aix) - ready
+```
+
+### For `nexus map`
+Show ALL capabilities organized by category with status.
+
+### For `nexus quest`
+Recommend capabilities that unlock the most power based on the CAPABILITY_TAXONOMY optimal path.
+
+---
+
+*This taxonomy is the source of truth for ALL nexus capabilities.*