@intent-systems/nexus 2026.1.5-3

package/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.*

package/docs/CNAME

@@ -0,0 +1 @@
+nexus.com

package/docs/NEXUS_CORE_REWRITE_SPEC.md

@@ -0,0 +1,226 @@
+# Nexus Core Rewrite Spec
+
+This spec defines the big-bang rewrite required to align nexus core with the vision
+articulated in `GOAL_STATE_ARCHITECTURE.md` and `CLI_GRAMMAR.md`.
+
+Sources of truth (in order):
+- `skills/onboarding/docs/GOAL_STATE_ARCHITECTURE.md`
+- `skills/onboarding/docs/CLI_GRAMMAR.md`
+- `skills/onboarding/docs/CLI_GRAMMAR_ONBOARDING.md`
+- `skills/onboarding/docs/STATE_ARCHITECTURE.md`
+- `skills/onboarding/docs/CAPABILITIES.md`
+
+---
+
+## Goals
+
+- Make `nexus status` the single orientation entry point for agents and users.
+- Implement the canonical state layout (agents/user identity, credentials tree, skill state).
+- Implement a first-class credential system with storage providers (1Password, Keychain, plaintext fallback).
+- Build a capability registry and detection engine with dynamic status.
+- Replace wizard-centric onboarding with dynamic detection (no progress.json).
+- Keep `BOOTSTRAP.md` as the canonical identity conversation prompt, but surface it via `nexus status`.
+- Deliver the CLI grammar as specified in `CLI_GRAMMAR.md`.
+
+## Non-Goals
+
+- Backward compatibility with the current CLI or state layout.
+- Migration of existing state (no current users).
+- Integration of messaging/gateway features into the new capability model (deferred).
+
+---
+
+## Current vs Target (Short)
+
+Current:
+- Workspace identity is flat files in `~/nexus/home/`.
+- Credentials live in a single `auth-profiles.json`.
+- Skills have binary/env filtering, but no capability mapping or type system.
+- Onboarding is wizard-driven; `nexus status` reports web health.
+
+Target:
+- Identity, credentials, skills, and state live under `~/nexus/state/`.
+- Credentials are stored in a service/account/auth tree with a fast index.
+- Capabilities are dynamic, provider-driven, and categorized.
+- `nexus status` is the main orientation + guidance surface.
+
+---
+
+## State Layout (Canonical)
+
+```
+~/nexus/
+├── AGENTS.md                 # Nexus-owned, canonical instructions
+├── .cursor/
+│   └── rules                 # Pointer to AGENTS.md (+ Cursor specifics)
+├── home/                     # User-owned workspace
+│   ├── memory/               # Daily logs
+│   ├── projects/             # User repos
+│   └── AGENTS.md             # Optional user content (not auto-read)
+├── state/
+│   ├── nexus/
+│   │   ├── config.json
+│   │   ├── gateway.json
+│   │   ├── skills/
+│   │   │   ├── manifest.json
+│   │   │   └── {skill}/
+│   │   │       ├── state.json
+│   │   │       └── usage.log
+│   │   └── onboarding/       # No progress.json; reserved for ephemeral signals
+│   ├── credentials/
+│   │   ├── index.json         # Fast lookup
+│   │   └── {service}/
+│   │       ├── config.json    # OAuth config (optional)
+│   │       └── accounts/
+│   │           └── {account}/
+│   │               └── auth/
+│   │                   └── {auth-id}.json
+│   ├── user/
+│   │   └── identity/
+│   │       └── PROFILE.md
+│   └── agents/
+│       └── {agent}/
+│           ├── identity/
+│           │   ├── IDENTITY.md
+│           │   ├── SOUL.md
+│           │   └── MEMORY.md
+│           └── config.json
+└── skills/                    # Bundled skills (managed)
+```
+
+Notes:
+- `BOOTSTRAP.md` remains a template under `docs/templates/`, surfaced via `nexus status`.
+- There is no `progress.json`. State is detected dynamically.
+
+---
+
+## Credential System
+
+### File Structure
+- `state/credentials/{service}/accounts/{account}/auth/{auth-id}.json`
+- `state/credentials/index.json` mirrors the tree for fast lookup.
+
+### Credential Storage Providers
+
+Each credential file references a storage provider, not a raw secret:
+
+```json
+{
+  "owner": "user",
+  "type": "oauth",
+  "configuredAt": "2026-01-10T15:00:00Z",
+  "storage": {
+    "provider": "1password",
+    "vault": "Personal",
+    "item": "Gmail - user@gmail.com",
+    "fields": {
+      "accessToken": "access_token",
+      "refreshToken": "refresh_token",
+      "expiresAt": "expires_at"
+    }
+  }
+}
+```
+
+Supported providers:
+- `1password`
+- `keychain`
+- `plaintext` (fallback)
+- `external` (CLI sync sources like Claude CLI/Codex CLI)
+
+### CLI Surface
+`nexus credential list|add|get|remove|scan|flag` is required.
+
+---
+
+## Capabilities and Providers
+
+### Capability Registry
+Source of truth: `skills/onboarding/docs/CAPABILITIES.md`
+
+Each capability maps to one or more providers (skills/connectors). Capabilities are grouped by category.
+
+### Dynamic Status Rules
+- **unavailable**: no provider exists for platform
+- **needs-install**: tool provider missing binary
+- **needs-setup**: connector provider missing credentials/config
+- **ready**: configured but unused
+- **active**: configured + used
+- **broken**: flagged failing
+
+### Skill Types
+Each SKILL.md declares one of:
+- `guide` (pure prompt)
+- `tool` (requires binary)
+- `connector` (requires credential/config)
+
+---
+
+## CLI Grammar (Required)
+
+Top-level commands:
+```
+nexus status
+nexus map (alias: capabilities)
+nexus quest
+nexus identity [user|agent]
+nexus skill use|info|list
+nexus tool verify|path
+nexus connector verify|accounts
+nexus credential list|add|get|remove|scan|flag
+```
+
+### JSON Output
+All commands must support `--json` and produce parseable output aligned with `CLI_GRAMMAR.md`.
+
+---
+
+## Bootstrap Flow
+
+1. `nexus status` runs on startup.
+2. If identity is missing:
+   - Status output includes `BOOTSTRAP.md` content (agent-facing prompt).
+   - Agent runs the identity conversation.
+3. Agent writes:
+   - `state/agents/{agent}/identity/IDENTITY.md`
+   - `state/agents/{agent}/identity/SOUL.md`
+   - `state/agents/{agent}/identity/MEMORY.md`
+   - `state/user/identity/PROFILE.md`
+4. Agent re-runs `nexus status` for guidance + first wow moment.
+
+---
+
+## Skill Gateway State + Usage
+
+Per-skill state:
+```
+state/nexus/skills/{skill}/state.json
+```
+
+Usage log:
+```
+state/nexus/skills/{skill}/usage.log  # JSONL
+```
+
+These files are required for:
+- status output (ready vs active)
+- usage stats
+- recommendation engine
+
+---
+
+## Acceptance Criteria
+
+- `nexus init` creates the canonical state layout at `~/nexus/`.
+- `nexus status` shows identity, credentials, capabilities, and suggestions.
+- Capabilities are computed dynamically, not via progress files.
+- Credentials are stored via providers, not in flat JSON.
+- CLI matches grammar in `CLI_GRAMMAR.md`.
+- No references to legacy `auth-profiles.json` or wizard-first onboarding.
+
+---
+
+## Deferred Scope
+
+- Messaging/gateway command integration into the capability model.
+- Backwards compatibility/migration.