@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/CLI_GRAMMAR.md

@@ -0,0 +1,797 @@
+# Nexus CLI Grammar
+
+> Complete command reference for the nexus CLI — the primary interface for agents and users to interact with the Nexus workspace.
+
+---
+
+## Philosophy
+
+**Nexus is a discovery and guidance system, not an execution gateway.**
+
+- Agents read guides via `nexus skill use`, then use tools directly
+- Tracking measures "how often agents needed guidance" not "tool executions"
+- This is honest — agents can always use tools outside nexus
+- Less forcing, more enabling
+
+**Agent-first design:**
+- Commands return structured, parseable output (`--json` everywhere)
+- Help output is verbose and detailed (agents handle it well)
+- Consistent patterns across all commands
+- `nexus status` is THE entry point for orientation
+
+---
+
+## Command Tree
+
+```bash
+nexus
+├── help [command]              # Discovery and documentation
+├── version                     # Version info
+├── update [check|apply]        # Update management
+├── config [list|get|set]       # Workspace configuration
+│
+├── init                        # Create workspace
+├── status                      # Main agent entry point
+├── capabilities                # Full capability map
+├── quest [--list|--progress]   # Growth recommendations
+│
+├── identity [user|agent]       # Paths to identity documents
+│
+├── skill                       # Universal entity interface
+│   ├── use <name>              # Return SKILL.md guide
+│   ├── info <name>             # Metadata + status + usage
+│   └── list [filters]          # Filtered skill listing
+│
+├── tool                        # Tool-specific operations
+│   ├── verify <name>           # Check binary exists
+│   └── path <name>             # Return binary location
+│
+├── connector                   # Connector-specific operations
+│   ├── verify <name>           # Test credentials work
+│   └── accounts <name>         # List configured accounts
+│
+├── credential                  # Credential management
+│   ├── list                    # List all credentials
+│   ├── add                     # Add new credential
+│   ├── get <service>           # Retrieve credential
+│   ├── remove <service>        # Remove credential
+│   ├── scan [--deep]           # Detect from environment
+│   ├── import <source>         # Import external CLI credentials
+│   └── flag <service>          # Mark as broken
+│
+└── log [--skill|--errors|--since]  # Activity logs
+```
+
+---
+
+## System Commands
+
+### `nexus help`
+
+Display help for nexus or a specific command.
+
+```bash
+nexus help                    # Overview of all commands
+nexus help status             # Detailed help for status
+nexus help skill              # Help for skill subcommands
+nexus help credential add     # Help for specific subcommand
+```
+
+### `nexus version`
+
+Display version information.
+
+```bash
+$ nexus version
+nexus 0.1.0 (darwin/arm64)
+```
+
+```bash
+$ nexus version --json
+{"version": "0.1.0", "os": "darwin", "arch": "arm64"}
+```
+
+### `nexus update`
+
+Check for and apply updates.
+
+```bash
+nexus update check            # Check if update available
+nexus update apply            # Apply available update
+```
+
+**Behavior:**
+- On any `nexus` command, background check for updates (if `autoCheck: true`)
+- If update available, writes to `state/nexus/update-available.json`
+- Next command shows notice: "Update available: 0.2.0. Run `nexus update apply`"
+- Never auto-applies without consent (unless `autoApply: true` in config)
+
+**Distribution support:**
+- npm: Uses `npm outdated/update -g nexus`
+- Homebrew: Uses `brew outdated/upgrade nexus`
+
+### `nexus config`
+
+Manage workspace configuration.
+
+```bash
+nexus config list                     # Show all config
+nexus config get update.autoCheck     # Get specific value
+nexus config set update.autoCheck false
+```
+
+**Config structure** (`state/nexus/config.json`):
+
+```json
+{
+  "version": "0.1.0",
+  "os": "darwin",
+  "arch": "arm64",
+  
+  "update": {
+    "autoCheck": true,
+    "autoApply": false,
+    "lastCheck": "2026-01-15T10:00:00Z"
+  },
+  
+  "gateway": {
+    "port": 18789,
+    "host": "127.0.0.1",
+    "auth": {
+      "tokenStorage": {
+        "provider": "1password",
+        "vault": "Personal",
+        "item": "Nexus Gateway",
+        "field": "token"
+      }
+    }
+  },
+  
+  "stateDir": "~/nexus/state"
+}
+```
+
+---
+
+## Orientation Commands
+
+### `nexus init`
+
+Create a new nexus workspace.
+
+```bash
+nexus init                    # Create at ~/nexus
+nexus init /path/to/workspace # Create at specific path
+```
+
+**Creates:**
+- Folder structure
+- `AGENTS.md` at root
+- `.cursor/rules` pointing to nexus
+- `state/nexus/config.json` with OS/platform info
+- Does NOT create identity files (that's the bootstrap conversation)
+
+### `nexus status`
+
+**Main entry point for agents.** Shows current state, capabilities, and suggestions.
+
+This is THE command agents run at startup (via AGENTS.md) to orient themselves.
+
+```bash
+$ nexus status
+
+╔════════════════════════════════════════════════════════════════╗
+║                        Nexus Status                            ║
+║                        darwin/arm64                            ║
+╚════════════════════════════════════════════════════════════════╝
+
+👤 Identity
+   User: Tyler (@tyler)
+         → state/user/identity/PROFILE.md
+   
+   Agent: Echo
+         → state/agents/echo/identity/IDENTITY.md
+         → state/agents/echo/identity/SOUL.md
+         → state/agents/echo/identity/MEMORY.md
+
+🔑 Credentials (12 configured)
+   LLM Providers:
+     ✅ anthropic (tyler@anthropic.com)
+     ✅ openai (tyler@openai.com)
+     ✅ gemini (tyler@google.com)
+   
+   Services:
+     ✅ google-oauth (tyler@gmail.com)
+     ✅ github (steipete)
+     ⭐ discord (echo-bot)
+     ❌ twitter (steipete) - flagged broken
+   
+   Run `nexus credential list` for details
+
+🎯 Capabilities (18/58 active)
+   
+   🗣️ Communication:
+     ✅ email-read, email-send (gog)
+     ✅ messaging-read (eve, imsg)
+     ⭐ chat-read, chat-send (discord)
+   
+   🔮 Insights:
+     ✅ relationship-insights (eve)
+     ⭐ session-insights (aix)
+   
+   Run `nexus capabilities` for full breakdown
+
+📊 Usage (last 7 days)
+   Most used: gog (47), eve (23), summarize (18)
+   Ready but unused: discord, aix, spotify
+   
+🎯 Suggestions
+   1. 💬 Try Discord! Configured but never used.
+   2. 📈 Set up reactive-triggers
+   3. 🔄 Fix twitter credentials
+
+╔════════════════════════════════════════════════════════════════╗
+║  Power Level: ████████░░ 78%                                   ║
+║  Next unlock: Agent Communications (+15%)                      ║
+╚════════════════════════════════════════════════════════════════╝
+```
+
+**Flags:**
+```bash
+nexus status --json           # JSON output
+nexus status --brief          # Compact (identity + suggestions only)
+nexus status --capabilities   # Focus on capabilities
+nexus status --credentials    # Focus on credentials
+```
+
+**Bootstrap detection:** If identity files don't exist, outputs bootstrap prompt with separate instructions for humans and agents.
+
+### `nexus capabilities`
+
+Full capability map showing everything possible.
+
+```bash
+$ nexus capabilities
+
+╔════════════════════════════════════════════════════════════════╗
+║                     Nexus Capabilities                         ║
+║                     Platform: darwin/arm64                     ║
+╚════════════════════════════════════════════════════════════════╝
+
+Legend: ✅ active  ⭐ ready  🔧 needs-setup  📥 needs-install  ⛔ unavailable  ❌ broken
+
+🗣️ Communication (7/8)
+   ✅ email-read ─────── gog + google-oauth
+   ✅ email-send ─────── gog + google-oauth
+   ✅ messaging-read ─── eve, imsg
+   📥 voice ──────────── (no provider yet)
+   ⭐ chat-read ──────── discord
+   ⭐ chat-send ──────── discord
+
+📱 Social & News (2/5)
+   ✅ social-x ───────── bird + twitter
+   🔧 news ───────────── brave-search (needs API key)
+
+🔮 Insights (2/4)
+   ✅ relationship-insights ── eve
+   ⭐ session-insights ─────── aix
+
+...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Summary: 18 active │ 8 ready │ 5 needs-setup │ 4 needs-install │ 1 broken
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Flags:**
+```bash
+nexus capabilities --json
+nexus capabilities --category communication
+nexus capabilities --status needs-setup
+```
+
+### `nexus quest`
+
+Personalized recommendations for growing capabilities.
+
+```bash
+$ nexus quest
+
+╔════════════════════════════════════════════════════════════════╗
+║                      🎯 Your Next Quest                        ║
+╚════════════════════════════════════════════════════════════════╝
+
+Based on your current setup, here's the highest-impact next step:
+
+┌────────────────────────────────────────────────────────────────┐
+│  🏆 QUEST: Enable Agent Communications                         │
+│                                                                │
+│  You have messaging and email connected, plus LLM API keys.   │
+│  But your agent can't reach YOU outside of Cursor yet.        │
+│                                                                │
+│  Setting up Discord lets your agent:                          │
+│    • Message you from anywhere                                │
+│    • Send proactive notifications                              │
+│    • Work with you asynchronously                             │
+│                                                                │
+│  Time: ~10 minutes │ Power boost: +15%                        │
+│                                                                │
+│  → Ready? Run: nexus skill use discord                        │
+└────────────────────────────────────────────────────────────────┘
+```
+
+**Flags:**
+```bash
+nexus quest --list            # Show all available quests
+nexus quest --progress        # Show completion progress
+nexus quest --power-path      # Show optimal path to 100%
+nexus quest --json
+```
+
+### `nexus identity`
+
+Show paths to identity documents.
+
+```bash
+$ nexus identity
+
+👤 User Identity
+   → state/user/identity/PROFILE.md
+
+🤖 Agent Identity (Echo)
+   → state/agents/echo/identity/IDENTITY.md
+   → state/agents/echo/identity/SOUL.md
+   → state/agents/echo/identity/MEMORY.md
+```
+
+```bash
+nexus identity user           # User profile path only
+nexus identity agent          # Agent identity paths only
+nexus identity --json
+```
+
+---
+
+## Skill Commands
+
+### `nexus skill use`
+
+**Primary command.** Returns the SKILL.md guide for any entity (tool, connector, or guide).
+
+```bash
+nexus skill use gog           # Returns gog tool guide
+nexus skill use discord       # Returns discord connector setup guide
+nexus skill use computer-use  # Returns computer-use guide
+```
+
+**Output:** The full SKILL.md content, ready for the agent to read and act on.
+
+**Tracks:** Each `use` is logged for usage statistics.
+
+### `nexus skill info`
+
+Show metadata, status, and usage statistics for a skill.
+
+```bash
+$ nexus skill info gog
+
+╔════════════════════════════════════════════════════════════════╗
+║                         gog                                    ║
+╚════════════════════════════════════════════════════════════════╝
+
+Type: tool
+Status: ✅ active
+Description: Google Workspace CLI for Gmail, Calendar, Drive, Contacts
+
+Provides: email-read, email-send, calendar, cloud-storage, contacts
+Requires:
+  - Connector: google-oauth
+  - Binary: gog
+
+Install:
+  - brew: steipete/tap/gogcli
+  - go: github.com/steipete/gogcli
+
+Usage:
+  Times accessed: 47
+  Last accessed: 2 hours ago
+  First accessed: 2025-12-01
+
+Binary: /opt/homebrew/bin/gog (verified)
+```
+
+```bash
+nexus skill info gog --json
+```
+
+### `nexus skill list`
+
+List skills with smart filtering.
+
+```bash
+$ nexus skill list
+
+╔════════════════════════════════════════════════════════════════╗
+║                        Nexus Skills                            ║
+╚════════════════════════════════════════════════════════════════╝
+
+🔧 Tools (14)
+   ✅ gog          email, calendar, drive, contacts
+   ✅ eve          messaging-read, relationship-insights
+   ✅ imsg         messaging-read, messaging-send
+   ⭐ aix          session-insights
+   ⭐ peekaboo     gui-automation
+   📥 ffmpeg       video-processing
+   📥 camsnap      camera-control
+
+🔌 Connectors (11)
+   ✅ google-oauth    google services auth
+   ✅ anthropic       claude models
+   ⭐ discord         chat-read, chat-send
+   🔧 brave-search    web-search (needs API key)
+   🔧 spotify         music playback (needs OAuth)
+
+📖 Guides (8)
+   ✅ computer-use    browser-automation patterns
+   ✅ filesystem      local file organization
+   ⭐ weather         weather queries
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Legend: ✅ active  ⭐ ready  🔧 needs-setup  📥 needs-install  ⛔ unavailable
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+33 skills │ 12 active │ 8 ready │ 5 need setup │ 4 need install
+
+Use 'nexus skill use <name>' to see the guide.
+```
+
+**Filters:**
+```bash
+nexus skill list --type tool          # Only tools
+nexus skill list --type connector     # Only connectors
+nexus skill list --type guide         # Only guides
+nexus skill list --active             # Only active
+nexus skill list --ready              # Only ready
+nexus skill list --needs-setup        # Only needs-setup
+nexus skill list --needs-install      # Only needs-install
+nexus skill list --all                # Include unavailable
+nexus skill list --json
+```
+
+**Default:** Shows all except unavailable (⛔).
+
+---
+
+## Tool Commands
+
+### `nexus tool verify`
+
+Check if a tool's binary exists and is executable.
+
+```bash
+$ nexus tool verify gog
+✅ gog binary found at /opt/homebrew/bin/gog
+   Version: 1.2.3
+```
+
+```bash
+$ nexus tool verify ffmpeg
+📥 ffmpeg not found
+   Install with: brew install ffmpeg
+```
+
+### `nexus tool path`
+
+Return the path to a tool's binary.
+
+```bash
+$ nexus tool path gog
+/opt/homebrew/bin/gog
+```
+
+---
+
+## Connector Commands
+
+### `nexus connector verify`
+
+Test if a connector's credentials are valid and working.
+
+```bash
+$ nexus connector verify google-oauth
+✅ google-oauth credentials valid
+   Account: tyler@gmail.com
+   Scopes: gmail, calendar, drive
+   Expires: 2026-02-15
+```
+
+```bash
+$ nexus connector verify twitter
+❌ twitter credentials invalid
+   Error: Cookie expired
+   Run 'nexus skill use twitter' for refresh instructions
+```
+
+### `nexus connector accounts`
+
+List all accounts configured for a connector.
+
+```bash
+$ nexus connector accounts google-oauth
+
+google-oauth accounts:
+
+  ✅ tyler@gmail.com (user)
+     Scopes: gmail, calendar, drive
+     Last verified: 2 hours ago
+  
+  ✅ work@company.com (user)
+     Scopes: gmail, calendar
+     Last verified: 1 day ago
+```
+
+```bash
+nexus connector accounts google-oauth --json
+```
+
+---
+
+## Credential Commands
+
+### `nexus credential list`
+
+List all configured credentials.
+
+```bash
+$ nexus credential list
+
+╔════════════════════════════════════════════════════════════════╗
+║                       Credentials                              ║
+╚════════════════════════════════════════════════════════════════╝
+
+LLM Providers:
+  ✅ anthropic │ tyler@anthropic.com │ keychain
+  ✅ openai    │ tyler@openai.com    │ keychain
+  ✅ gemini    │ tyler@google.com    │ keychain
+
+Services:
+  ✅ google    │ tyler@gmail.com     │ keychain
+  ✅ google    │ work@company.com    │ 1password
+  ✅ github    │ steipete            │ keychain
+  ⭐ discord   │ echo-bot            │ keychain
+  ❌ twitter   │ steipete            │ keychain (broken)
+
+12 credentials │ 10 active │ 1 ready │ 1 broken
+```
+
+```bash
+nexus credential list --json
+nexus credential list --broken       # Only broken
+nexus credential list --service google
+```
+
+### `nexus credential add`
+
+Add a new credential interactively or via flags.
+
+**Interactive:**
+```bash
+$ nexus credential add
+
+? Service: anthropic
+? Account (email/username): tyler@anthropic.com
+? Credential type: api-key
+? Owner (user/agent:name): user
+? Storage: keychain (recommended)
+? Paste your API key: ****
+
+✅ Credential stored
+   Service: anthropic
+   Account: tyler@anthropic.com
+   Storage: keychain (nexus.anthropic.tyler@anthropic.com)
+```
+
+**Non-interactive:**
+```bash
+nexus credential add \
+  --service anthropic \
+  --account tyler@anthropic.com \
+  --type api-key \
+  --owner user \
+  --storage keychain \
+  --value sk-ant-xxxxx
+```
+
+### `nexus credential get`
+
+Retrieve a credential value (for agent use).
+
+```bash
+$ nexus credential get anthropic --account tyler@anthropic.com
+sk-ant-api03-xxxxx...
+```
+
+Returns just the value, suitable for piping or capture.
+
+### `nexus credential remove`
+
+Remove a credential.
+
+```bash
+$ nexus credential remove anthropic --account tyler@anthropic.com
+
+⚠️  This will remove:
+   Service: anthropic
+   Account: tyler@anthropic.com
+   Storage: keychain
+
+? Confirm removal? (y/N) y
+
+✅ Credential removed
+```
+
+### `nexus credential scan`
+
+Detect credentials from environment variables.
+
+```bash
+$ nexus credential scan
+
+Scanning environment variables...
+
+Found:
+  ✅ ANTHROPIC_API_KEY → anthropic (sk-ant-...xxxx)
+  ✅ OPENAI_API_KEY → openai (sk-...xxxx)
+  ⚠️  GITHUB_TOKEN → github (ghp_...xxxx) - not yet imported
+
+Import these? Run: nexus credential scan --import
+```
+
+### `nexus credential flag`
+
+Mark a credential as broken (when usage fails).
+
+```bash
+$ nexus credential flag twitter --account steipete --reason "Cookie expired"
+
+❌ Flagged twitter (steipete) as broken
+   Reason: Cookie expired
+   
+Run 'nexus skill use twitter' for refresh instructions.
+```
+
+---
+
+## Log Commands
+
+### `nexus log`
+
+View recent activity.
+
+```bash
+$ nexus log
+
+Recent activity:
+
+2026-01-15 14:30:00  skill use    gog
+2026-01-15 14:25:00  skill use    eve
+2026-01-15 14:20:00  skill use    discord
+2026-01-15 14:15:00  credential   add anthropic
+2026-01-15 14:10:00  status       (bootstrap detected)
+```
+
+**Filters:**
+```bash
+nexus log --skill gog         # Filter by skill
+nexus log --errors            # Only errors
+nexus log --since 7d          # Time filter (7d, 24h, 1w)
+nexus log --limit 50          # Limit entries
+nexus log --json
+```
+
+---
+
+## Status Levels Reference
+
+| Emoji | Status | Meaning |
+|-------|--------|---------|
+| ✅ | `active` | Configured AND has been used |
+| ⭐ | `ready` | Configured, never used |
+| 🔧 | `needs-setup` | Installed but needs credential/config |
+| 📥 | `needs-install` | Tool binary needs to be installed |
+| ⛔ | `unavailable` | Not available on this OS/platform |
+| ❌ | `broken` | Was working but now failing |
+
+---
+
+## JSON Output
+
+All commands support `--json` for programmatic use:
+
+```bash
+nexus status --json
+nexus capabilities --json
+nexus skill list --json
+nexus skill info gog --json
+nexus credential list --json
+```
+
+JSON output is designed for agent parsing — structured, complete, and consistent.
+
+---
+
+## Agent Usage Pattern
+
+Typical agent workflow:
+
+```bash
+# 1. Orient at session start
+nexus status
+
+# 2. Check what's available
+nexus skill list
+
+# 3. Get guide for specific skill
+nexus skill use gog
+
+# 4. (Agent uses tool directly based on guide)
+
+# 5. If something fails, check/flag
+nexus connector verify google-oauth
+nexus credential flag google --reason "Token expired"
+
+# 6. Grow capabilities
+nexus quest
+```
+
+---
+
+## Integration with AGENTS.md
+
+Root `AGENTS.md` should instruct agents:
+
+```markdown
+## Initialization
+
+Before doing anything else:
+1. Run `nexus status` to understand current state
+2. Read your identity files (paths shown in status)
+3. Check available capabilities
+
+## Using Skills
+
+1. Run `nexus skill use <name>` to get the guide
+2. Follow the guide to use the tool directly
+3. If credentials fail, run `nexus credential flag <service>`
+
+## Growing Capabilities
+
+- Run `nexus quest` for recommendations
+- Run `nexus skill list --needs-setup` to see what you could configure
+```
+
+---
+
+## Summary
+
+| Command | Purpose |
+|---------|---------|
+| `nexus status` | Main entry point, orientation |
+| `nexus capabilities` | Full capability map |
+| `nexus quest` | Growth recommendations |
+| `nexus skill use <name>` | Get the guide for any skill |
+| `nexus skill list` | See all available skills |
+| `nexus tool verify` | Check tool binary |
+| `nexus connector verify` | Test credentials |
+| `nexus credential *` | Manage credentials |
+| `nexus log` | View activity |
+
+**The core loop:**
+1. `nexus status` → orient
+2. `nexus skill use <name>` → learn
+3. (use tool directly) → execute
+4. `nexus quest` → grow
+
+---
+
+*This is the complete CLI grammar for nexus.*