@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/SKILL_GATEWAY_PRD.md

@@ -0,0 +1,278 @@
+# Skill Gateway PRD
+
+> **Note**: State layout and credential storage are defined in
+> `STATE_ARCHITECTURE.md`. References to per-skill state and usage logs in this
+> PRD are canonical under `~/nexus/state/nexus/skills/{skill}/`.
+
+> **Status**: Ready for Implementation  
+> **Created**: 2026-01-12  
+> **Last Updated**: 2026-01-12  
+> **Owner**: Tyler + Agent
+
+---
+
+## TL;DR
+
+Build a CLI gateway (`nexus skill *`) that wraps all skill execution, providing automatic usage tracking, state management, and gated discovery. This solves the "two hard problems" of onboarding: tracking state and injecting state into the agent.
+
+**Key Insight**: Instead of asking agents to report usage (unreliable), we make them execute through the gateway (automatic). The gateway becomes the single source of truth for what skills exist, which are ready, and how they're being used.
+
+---
+
+## Goals
+
+1. **Automatic Usage Tracking** — Every skill invocation logged without agent cooperation
+2. **Gated Discovery** — Only show skills that are ready to use
+3. **Verification on First Run** — Trust but verify, then cache the result
+4. **Observable Skill Health** — Know which skills work, which fail, usage patterns
+5. **Simple Agent Instructions** — Agent just needs to know `nexus skill run <name>`
+
+---
+
+## Non-Goals (For Now)
+
+- MCP integration (CLI only)
+- Full sandboxing/isolation
+- Skill crystallization (performance optimization)
+- Complex adapters for different skill types
+- Cross-agent skill sharing
+
+---
+
+## Architecture
+
+See: [SKILL_GATEWAY_DESIGN.md](./SKILL_GATEWAY_DESIGN.md) for complete technical specification.
+
+### Core Files
+
+| File | Purpose |
+|------|---------|
+| `~/nexus/state/nexus/skills/{skill}/state.json` | Per-skill runtime state |
+| `~/nexus/state/nexus/skills/{skill}/usage.log` | Append-only JSONL log |
+| `~/nexus/state/nexus/skills/manifest.json` | Skill manifest (discovery) |
+
+### New Commands
+
+```bash
+nexus skills list [--ready] [--locked]  # List skills with status
+nexus skill show <name>                  # Show skill details + prompt
+nexus skill verify <name>                # Check if skill is configured
+nexus skill run <name> [args...]         # Execute skill (logged)
+nexus skill stats [name]                 # Usage statistics
+nexus status                             # Quick status overview
+```
+
+---
+
+## Implementation Phases
+
+### Phase 1: State Infrastructure ✅
+**Completed**: 2026-01-12
+
+- [x] **1.1** Create `src/agents/skill-state.ts`
+  - `loadSkillState()` / `saveSkillState()` 
+  - `getSkillState(name)` / `setSkillState(name, updates)`
+  - Schema: `SkillState` type with version, skills map
+
+- [x] **1.2** Create `src/agents/skill-usage.ts`
+  - `logSkillUsage(entry)` with append + prune
+  - `getSkillStats(name?)` for analytics
+  - Schema: `UsageLogEntry` type
+
+- [x] **1.3** Define skill tool mappings
+  - `KNOWN_SKILL_TOOLS`: Record<string, { tool, verify }>
+  - `SCRIPT_SKILLS`: Record<string, { runner, script }>
+  - `PROMPT_ONLY_SKILLS`: Set<string>
+
+- [x] **1.4** Unit tests for state management
+  - 29 tests passing
+
+### Phase 2: Core Commands ✅
+**Completed**: 2026-01-12
+
+- [x] **2.1** `nexus skill show <name>` command
+  - Load skill from manifest
+  - Read SKILL.md content
+  - Display state from per-skill state.json
+  - Output: name, description, status, prompt
+
+- [x] **2.2** `nexus skill verify <name>` command
+  - Determine verification method (binary check, command, etc.)
+  - Execute verification
+  - Update per-skill state.json with result
+  - Output: success/failure with details
+
+- [x] **2.3** `nexus skill run <name> [args...]` command
+  - Check if skill is prompt-only vs tool-based
+  - For tools: execute with arg passthrough
+  - Capture timing, exit code, stderr
+  - Log to per-skill usage.log
+  - Update per-skill state.json (lastUsed, etc.)
+
+- [x] **2.4** Create `src/agents/skill-runner.ts`
+  - Core gateway logic
+  - `execCapture()` utility
+  - Output streaming
+
+### Phase 3: Stats & Polish ✅
+**Completed**: 2026-01-12
+
+- [x] **3.1** `nexus skill stats [name]` command
+  - Parse per-skill usage.log
+  - Calculate: total runs, success rate, avg duration
+  - Per-skill or aggregate
+
+- [x] **3.2** `nexus skills status` command
+  - Add `--ready` flag (only configured skills)
+  - Add `--locked` flag (only unconfigured skills)
+  - Show status indicator per skill
+
+- [ ] **3.3** `nexus status` convenience alias (deferred)
+  - Quick overview: # skills ready, # locked, recent activity
+
+- [ ] **3.4** Update Cursor rules generation (deferred)
+  - Include gateway instructions in generated rules
+
+### Phase 4: Testing & Documentation ⬜
+**Estimated**: 2-3 hours
+
+- [ ] **4.1** Manual testing with real skills
+  - Test: gog, tmux, peekaboo, filesystem (prompt-only)
+  - Verify logging, state updates, error handling
+
+- [ ] **4.2** Edge case fixes
+  - Handle missing skills gracefully
+  - Handle verification failures
+  - Handle tool execution errors
+
+- [ ] **4.3** Update AGENTS.md template
+  - New gateway instructions
+  - Remove old skill loading patterns
+
+- [ ] **4.4** Update nexus README
+  - Document new commands
+  - Usage examples
+
+---
+
+## Skills Inventory Reconciliation ⬜
+**Estimated**: 1-2 hours  
+**Priority**: After Phase 2 (needs working gateway to test)
+
+### Context
+
+There are skills in two locations that need reconciliation:
+- `~/nexus/skills/` (user's active skills)  
+- `~/nexus/home/projects/nexus/skills/` (core nexus repo)
+
+### Tasks
+
+- [ ] **5.1** Generate diff report
+  - Skills only in user dir
+  - Skills only in core dir
+  - Skills in both (check for differences)
+
+- [ ] **5.2** Decide unification strategy
+  - Which is canonical?
+  - Symlink vs copy vs git submodule?
+
+- [ ] **5.3** Execute unification
+  - Preserve user customizations
+  - Update any hardcoded paths
+
+- [ ] **5.4** Verify all skills load correctly
+  - Run `nexus skills list` after merge
+  - Test representative skills from each category
+
+---
+
+## Skill Tool Mappings
+
+Reference for Phase 1.3 (from IMPLEMENTATION_RESEARCH.md):
+
+### Tool-Based Skills (Binary Required)
+
+| Skill | Tool Binary | Verify Command |
+|-------|-------------|----------------|
+| gog | gog | `gog gmail labels list --account default` |
+| eve | eve | `eve messages --limit 1` |
+| 1password | op | `op whoami` |
+| tmux | tmux | `tmux -V` |
+| peekaboo | peekaboo | `peekaboo --version` |
+| qmd | qmd | `qmd status` |
+| aix | aix | `aix --version` |
+| summarize | summarize | `summarize --version` |
+| video-frames | ffmpeg | `ffmpeg -version` |
+| camsnap | camsnap | `camsnap --help` |
+| gifgrep | gifgrep | `gifgrep --version` |
+| nano-pdf | nano-pdf | `nano-pdf --help` |
+| songsee | songsee | `songsee --version` |
+| bear-notes | bear | `bear --version` |
+| openhue | openhue | `openhue --version` |
+| obsidian-semantic-search | obsidian-semantic-search | `obsidian-semantic-search --version` |
+| nexus-cloud | wrangler | `wrangler --version` |
+
+### Script-Based Skills
+
+| Skill | Runner | Notes |
+|-------|--------|-------|
+| brave-search | node | Requires BRAVE_API_KEY |
+| openai-image-gen | python | Requires OPENAI_API_KEY |
+
+### Prompt-Only Skills (No External Tool)
+
+filesystem, computer-use, weather, github, discord, coding-agent, gemini, model-usage, x-twitter, apple-calendar, apple-notes, apple-reminders, things, blogwatcher, web-scraping, newsletter-generation, etc.
+
+---
+
+## Risk Mitigation
+
+| Risk | Mitigation |
+|------|------------|
+| Tool binary names change | `KNOWN_SKILL_TOOLS` is single source of truth, easy to update |
+| Verification commands change | Same - centralized mapping |
+| State file corruption | Atomic writes (write to tmp, rename) |
+| Log file grows unbounded | Prune to last 2000 entries / 2MB |
+| Gateway adds latency | Minimal overhead (just logging) |
+| Agent bypasses gateway | Agent instructions emphasize using `nexus skill run` |
+
+---
+
+## Success Criteria
+
+1. ✅ `nexus skills list --ready` shows only configured skills
+2. ✅ `nexus skill run gog gmail labels list` works and logs
+3. ✅ `nexus skill stats` shows usage patterns
+4. ✅ Agent can discover and use skills via gateway
+5. ✅ No manual reporting required from agent
+6. ✅ Skills reconciliation complete, single source of truth
+
+---
+
+## Dependencies
+
+- Existing `nexus` CLI (TypeScript, Commander)
+- Existing `resolveStateDir()` helper
+- Existing `loadJsonFile()` / `saveJsonFile()` patterns
+- Existing cron log patterns (for append-only log)
+
+---
+
+## Open Questions
+
+1. **Should failed verifications block `skill run`?**
+   - Current plan: Warn but allow (user might know something we don't)
+
+2. **How to handle skills with multiple tools?**
+   - Current plan: Primary tool only, note others in SKILL.md
+
+3. **What about skills that need env vars but no binary?**
+   - Current plan: Consider them "prompt-only" with optional env check
+
+---
+
+## Change Log
+
+| Date | Change |
+|------|--------|
+| 2026-01-12 | Initial PRD created |

package/skills/onboarding/docs/SKILL_INVENTORY.md

@@ -0,0 +1,266 @@
+# Skill Inventory & Migration Plan
+
+> Categorization of existing skills into the new entity model: Tools, Connectors, and Guides.
+
+## Summary
+
+| Category | Count | Description |
+|----------|-------|-------------|
+| **Tools** | 32 | Binary/CLI that performs work |
+| **Connectors** | 15 | Service auth + credentials |
+| **Guides** | 10 | Standalone prompts/instructions |
+| **Composite** | Many | Tools that also need connectors (listed in both) |
+
+---
+
+## Tools
+
+Tools are binaries/CLIs that perform actual work. They may require connectors for auth.
+
+| Name | Binary | OS | Connector Required | Capabilities Provided |
+|------|--------|-----|-------------------|----------------------|
+| `gog` | `gog` | all | `google-oauth` | email, calendar, drive, contacts, tasks |
+| `eve` | `eve` | **darwin** | `gemini` (optional) | messaging-analytics, imessage |
+| `imsg` | `imsg` | **darwin** | — | messaging (iMessage) |
+| `aix` | `aix` | darwin, linux | `gemini` (optional) | ai-session-analytics |
+| `summarize` | `summarize` | all | LLM provider | summarization |
+| `peekaboo` | `peekaboo` | **darwin** | — | gui-automation |
+| `qmd` | `qmd` | all | — | document-rendering |
+| `camsnap` | `camsnap` | **darwin** | — | camera-capture |
+| `tmux` | `tmux` | darwin, linux | — | terminal-sessions |
+| `video-frames` | `ffmpeg` | all | — | video-processing |
+| `nano-pdf` | `nano-pdf` | all | API key? | pdf-processing |
+| `songsee` | `songsee` | **darwin** | — | music-detection |
+| `blucli` | `blucli` | **darwin** | — | bluetooth-control |
+| `openhue` | `openhue` | all | `hue` | smart-home |
+| `sonoscli` | `sonoscli` | all | — | audio-control |
+| `spotify-player` | `spotify_player` | all | `spotify` | music-playback |
+| `bird` | `bird` | all | `twitter` | social-media (X) |
+| `wacli` | `wacli` | all | `whatsapp` | messaging (WhatsApp) |
+| `eightctl` | `eightctl` | all | `eightsleep` | smart-home |
+| `sag` | `sag` | all | — | screenshot-annotation |
+| `gifgrep` | `gifgrep` | all | API key (partial) | gif-search |
+| `ordercli` | `ordercli` | all | `doordash`? | food-ordering |
+| `model-usage` | script | all | LLM providers | api-analytics |
+| `openai-whisper` | `whisper` | all | — | transcription (local) |
+| `nexus-cloud` | `wrangler` | all | `cloudflare` | cloud-sync |
+| `upstream-sync` | scripts | all | — | git-sync |
+| `mcporter` | `mcporter` | all | — | mcp-tools |
+| `1password` | `op` | all | `1password` | credential-management |
+| `apple-notes` | AppleScript | **darwin** | — | notes |
+| `apple-reminders` | AppleScript | **darwin** | — | reminders |
+| `bear-notes` | AppleScript | **darwin** | — | notes |
+| `things-mac` | AppleScript | **darwin** | — | tasks |
+| `obsidian` | Obsidian URI | all | — | notes |
+| `goplaces` | `goplaces` | all | `google-places` | location-search |
+| `local-places` | MCP server | all | `google-places` | location-search |
+| `blogwatcher` | `blogwatcher` | all | — | rss-monitoring |
+| `comms` | tool | all | various | messaging (unified) |
+
+**Bold darwin** = macOS only (no Linux/Windows support)
+
+---
+
+## Connectors
+
+Connectors provide auth to external services. Each needs setup and credentials.
+
+| Name | Service | Auth Type | Capabilities Enabled |
+|------|---------|-----------|---------------------|
+| `google-oauth` | Google | OAuth 2.0 | google-auth (email, calendar, drive, etc.) |
+| `anthropic` | Anthropic | API key | llm |
+| `openai` | OpenAI | API key | llm, image-gen, transcription |
+| `gemini` | Google AI | API key | llm |
+| `brave-search` | Brave | API key | web-search |
+| `discord` | Discord | Bot token | messaging (Discord) |
+| `slack` | Slack | Bot token | messaging (Slack) |
+| `trello` | Trello | API key + token | task-management |
+| `notion` | Notion | API key | notes, databases |
+| `github` | GitHub | OAuth/token | version-control |
+| `twitter` | X/Twitter | OAuth | social-media |
+| `spotify` | Spotify | OAuth | music |
+| `whatsapp` | WhatsApp | Phone auth | messaging |
+| `cloudflare` | Cloudflare | API token | cloud-infra |
+| `1password` | 1Password | App integration | credential-management |
+| `elevenlabs` | ElevenLabs | API key | voice-synthesis |
+| `firecrawl` | Firecrawl | API key | web-scraping |
+| `apify` | Apify | API token | web-scraping |
+| `hue` | Philips Hue | Bridge auth | smart-home |
+| `eightsleep` | Eight Sleep | Account auth | smart-home |
+
+---
+
+## Guides
+
+Pure prompts/instructions that may reference tools and connectors.
+
+| Name | Dependencies | Purpose |
+|------|--------------|---------|
+| `computer-use` | anyTools: [peekaboo, interpreter, browser-use] | Meta-guide for UI automation |
+| `filesystem` | — | Home directory organization |
+| `coding-agent` | anyTools: [codex, claude, opencode, pi] | Meta-guide for coding agents |
+| `oracle` | LLM providers | LLM routing and selection |
+| `weather` | curl | Weather queries (no API key) |
+| `food-order` | ordercli? | Food ordering workflow |
+| `onboarding` | nexus CLI | Nexus onboarding (to be integrated into CLI) |
+| `clawdhub` | — | ClawdHub skill discovery |
+| `skill-cli-template` | — | Template for creating CLIs |
+
+---
+
+## Migration Plan
+
+### Phase 1: Create folder structure
+
+```bash
+mkdir -p ~/nexus/tools ~/nexus/connectors ~/nexus/guides
+```
+
+### Phase 2: Handle composite skills
+
+Only **one** skill is truly composite (tool + connector bundle):
+
+| Current Skill | Split Into |
+|---------------|------------|
+| `gog/SKILL.md` | `tools/gog/` + `connectors/google-oauth/` |
+
+The gog SKILL.md contains both tool usage AND OAuth setup. The OAuth setup should move to a separate `google-oauth` connector.
+
+**Note:** These are NOT composites—they're pure connectors with scripts:
+- `brave-search` → `connectors/brave-search/` (has search.mjs, content.mjs scripts)
+- `discord` → `connectors/discord/` (uses Nexus internal tool)
+- `slack` → `connectors/slack/` (uses Nexus internal tool)
+- `trello` → `connectors/trello/` (has curl script examples)
+- `notion` → `connectors/notion/` (has curl script examples)
+- `github` → `connectors/github/` (gh CLI is external, this is just auth setup)
+
+Connectors can ship with utility scripts—that doesn't make them tools.
+
+### Phase 3: Move pure tools
+
+Tools with no connector requirements (or with optional connectors):
+
+```
+skills/imsg/          → tools/imsg/
+skills/peekaboo/      → tools/peekaboo/
+skills/qmd/           → tools/qmd/
+skills/tmux/          → tools/tmux/
+skills/aix/           → tools/aix/
+skills/eve/           → tools/eve/
+skills/summarize/     → tools/summarize/
+...
+```
+
+### Phase 4: Move pure guides
+
+```
+skills/computer-use/  → guides/computer-use/
+skills/filesystem/    → guides/filesystem/
+skills/coding-agent/  → guides/coding-agent/
+skills/weather/       → guides/weather/
+...
+```
+
+### Phase 5: Update frontmatter
+
+Add `type` field to all SKILL.md files:
+
+```yaml
+---
+name: gog
+type: tool
+provides: [email, calendar, drive]
+requires:
+  connectors: [google-oauth]
+...
+---
+```
+
+---
+
+## Capability Mapping
+
+### Core Capabilities (from CAPABILITY_TAXONOMY.md)
+
+| Capability | Providers (Tools + Connectors) |
+|------------|-------------------------------|
+| **email** | gog + google-oauth |
+| **calendar** | gog + google-oauth |
+| **messaging** | imsg, eve, discord, slack, wacli + respective connectors |
+| **llm** | gemini, anthropic, openai connectors |
+| **web-search** | brave-search connector, summarize tool |
+| **version-control** | gh CLI + github connector |
+| **notes** | apple-notes, bear-notes, obsidian, notion |
+| **tasks** | things-mac, apple-reminders, trello |
+| **gui-automation** | peekaboo, interpreter (from computer-use) |
+| **credential-management** | 1password |
+| **cloud-sync** | nexus-cloud + cloudflare connector |
+
+### Capability → Onboarding Level Mapping
+
+| Onboarding Level | Required Capabilities |
+|------------------|----------------------|
+| **Core** | (none - just workspace setup) |
+| **Credential Management** | credential-management |
+| **User Comms** | messaging (any provider) |
+| **User Data** | email, calendar, notes, version-control |
+| **Enable Agents** | llm (any provider) |
+| **Agent Comms** | messaging (agent-owned account) |
+| **Automation** | llm + cron |
+| **Cloud Sync** | cloud-sync |
+
+---
+
+## State Architecture Integration
+
+### Connectors → state/credentials/
+
+Each connector maps to a service folder in `state/credentials/` (runtime credentials):
+
+```
+state/credentials/
+├── google/                 # For google-oauth connector
+│   ├── config.json         # Shared OAuth client config
+│   └── accounts/
+│       └── user@gmail.com/
+├── anthropic/              # For anthropic connector
+│   └── accounts/
+│       └── personal/
+├── discord/                # For discord connector
+│   └── accounts/
+│       └── echo-bot/
+...
+```
+
+**Note:** `connectors/` (root level) contains definitions + setup guides. `state/credentials/` contains actual credentials (never distributed).
+
+### Tools → state/nexus/skills/{tool}/
+
+Each tool has usage tracking:
+
+```
+state/nexus/skills/gog/
+├── state.json              # configured, verified, lastUsed
+└── usage.log               # Invocation history
+```
+
+### Guides → state/nexus/skills/{guide}/
+
+Guides also get usage tracking (when invoked via `nexus skill`):
+
+```
+state/nexus/skills/computer-use/
+├── state.json
+└── usage.log
+```
+
+---
+
+## Next Steps
+
+1. [x] Finalize ENTITY_MODEL.md schema
+2. [ ] Create migration script to reorganize folders
+3. [ ] Update each SKILL.md frontmatter with `type` and `provides`/`requires`
+4. [ ] Extract google-oauth connector from gog (only true composite)
+5. [ ] Update nexus CLI to handle new folder structure (tools/, connectors/, guides/)
+6. [ ] Ensure STATE_ARCHITECTURE.md uses `state/credentials/` (not `state/connectors/`)