@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/CLI_GRAMMAR_SKILLS.md

@@ -0,0 +1,449 @@
+# CLI Grammar: Skills, Tools, Connectors, Guides
+
+> Defines the nexus CLI interface for entity discovery, verification, and execution.
+> 
+> **Scope:** This document covers skill-related commands only. Credentials and onboarding are defined separately.
+
+## Design Principles
+
+1. **Unified discovery, type-specific actions** - Use `nexus skill` for common operations (list, show, verify, run). Use type-specific commands for actions unique to that type.
+
+2. **Progressive disclosure** - `nexus skill list` shows everything. Filters and type-specific commands reveal more detail.
+
+3. **Agent-friendly output** - All commands support `--json` for structured output.
+
+4. **Gateway pattern** - All skill invocations go through the gateway for logging and state tracking.
+
+---
+
+## Command Reference
+
+### `nexus skill` - Unified Entity Operations
+
+Works for all entity types (tools, connectors, guides).
+
+#### `nexus skill list`
+
+List all available entities.
+
+```bash
+nexus skill list                      # All entities
+nexus skill list --type tool          # Only tools
+nexus skill list --type connector     # Only connectors  
+nexus skill list --type guide         # Only guides
+nexus skill list --ready              # Only configured/ready
+nexus skill list --locked             # Only need configuration
+nexus skill list --provides email     # Filter by capability
+nexus skill list --json               # JSON output
+```
+
+**Output (human):**
+```
+📚 Nexus Skills (47 total)
+
+Tools (32):
+  ● gog - Google Workspace CLI (email, calendar, drive)
+  ● eve - iMessage intelligence engine
+  ○ spotify-player - Spotify TUI (needs: spotify connector)
+  ...
+
+Connectors (10):
+  ● google-oauth - Google OAuth setup
+  ○ brave-search - Brave Search API (needs: API key)
+  ...
+
+Guides (5):
+  ● computer-use - GUI automation patterns
+  ● filesystem - Home directory organization
+  ...
+
+● = ready   ○ = needs config
+```
+
+**Output (JSON):**
+```json
+{
+  "tools": [
+    {"name": "gog", "type": "tool", "configured": true, "provides": ["email", "calendar", "drive"]},
+    ...
+  ],
+  "connectors": [...],
+  "guides": [...]
+}
+```
+
+#### `nexus skill show <name>`
+
+Show detailed information about an entity.
+
+```bash
+nexus skill show gog                  # Basic info
+nexus skill show gog --prompt         # Include full SKILL.md content
+nexus skill show gog --json           # JSON output
+```
+
+**Output:**
+```
+Skill: gog
+Type: tool
+Description: Google Workspace CLI for Gmail, Calendar, Drive...
+Homepage: https://gogcli.sh
+
+Provides: email, calendar, drive, contacts, tasks
+Requires:
+  Connectors: google-oauth
+  Binaries: gog
+
+Status: ● Configured
+Last used: 2026-01-12T10:30:00Z
+Total runs: 47
+
+Run 'nexus skill show gog --prompt' to see full guide.
+```
+
+#### `nexus skill verify <name>`
+
+Check if an entity is properly configured.
+
+```bash
+nexus skill verify gog                # Verify tool is installed + connector configured
+nexus skill verify gog --force        # Re-verify even if already marked configured
+nexus skill verify gog --json         # JSON output
+```
+
+**Output:**
+```
+✓ gog
+
+Checks performed:
+  ✓ Binary 'gog' found in PATH
+  ✓ Connector 'google-oauth' configured
+  ✓ Account 'tnapathy@gmail.com' has valid OAuth token
+
+Ready to use.
+```
+
+**On failure:**
+```
+✗ gog
+
+Checks performed:
+  ✓ Binary 'gog' found in PATH
+  ✗ Connector 'google-oauth' not configured
+
+To fix:
+  Run 'nexus connector setup google-oauth'
+```
+
+#### `nexus skill run <name> [args...]`
+
+Execute a skill through the gateway. All invocations are logged.
+
+```bash
+nexus skill run gog gmail search "is:unread"    # Run tool with args
+nexus skill run filesystem                       # Output guide prompt
+nexus skill run computer-use                     # Output guide prompt
+nexus skill run gog --timeout 30000              # Custom timeout
+nexus skill run gog --json                       # JSON output wrapper
+nexus skill run gog --no-verify                  # Skip auto-verification
+```
+
+**Behavior by type:**
+- **Tool**: Executes binary with args, streams stdout/stderr
+- **Connector**: Outputs setup guide (or runs setup script if available)
+- **Guide**: Outputs the prompt/instructions
+
+#### `nexus skill stats [name]`
+
+Show usage statistics.
+
+```bash
+nexus skill stats                     # Aggregate stats
+nexus skill stats gog                 # Single skill stats
+nexus skill stats --json              # JSON output
+```
+
+**Output (aggregate):**
+```
+Skill Usage Statistics
+
+Skills used: 23
+Total invocations: 847
+Overall success rate: 94.2%
+
+Most used:
+  gog: 203 runs
+  eve: 156 runs
+  filesystem: 89 runs
+
+Recent errors:
+  brave-search: API rate limit exceeded (2026-01-12)
+```
+
+---
+
+### `nexus tool` - Tool-Specific Operations
+
+Actions that only apply to tools.
+
+#### `nexus tool install <name>`
+
+Run the installation process for a tool.
+
+```bash
+nexus tool install gog                # Install using default method
+nexus tool install gog --method brew  # Use specific install method
+nexus tool install gog --dry-run      # Show what would be installed
+```
+
+**Output:**
+```
+Installing gog...
+
+Available methods:
+  1. brew - Install gog via Homebrew (recommended)
+  2. go - Install gog via Go
+
+Using: brew
+
+$ brew install steipete/tap/gogcli
+==> Installing gogcli from steipete/tap
+...
+
+✓ gog installed successfully
+  Binary: /opt/homebrew/bin/gog
+  Version: 1.2.3
+
+Next: Run 'nexus connector setup google-oauth' to configure authentication.
+```
+
+#### `nexus tool update <name>`
+
+Update an installed tool.
+
+```bash
+nexus tool update gog                 # Update to latest
+nexus tool update --all               # Update all tools
+```
+
+#### `nexus tool path <name>`
+
+Show where a tool's files live.
+
+```bash
+nexus tool path gog
+```
+
+**Output:**
+```
+Tool: gog
+
+Definition: ~/nexus/tools/gog/SKILL.md
+Binary: /opt/homebrew/bin/gog
+Config: ~/.config/gog/
+State: ~/nexus/state/nexus/skills/gog/
+```
+
+---
+
+### `nexus connector` - Connector-Specific Operations
+
+Actions that only apply to connectors.
+
+#### `nexus connector setup <name>`
+
+Interactive setup wizard for a connector's credentials.
+
+```bash
+nexus connector setup google-oauth    # Interactive OAuth flow
+nexus connector setup brave-search    # Prompt for API key
+nexus connector setup --account work  # Setup for specific account
+```
+
+**Output:**
+```
+Setting up: google-oauth
+
+This connector requires OAuth authentication with Google.
+
+Steps:
+1. Open Google Cloud Console
+2. Create OAuth credentials (Desktop app)
+3. Download credentials.json
+
+? Do you have credentials.json ready? (y/n) y
+? Path to credentials.json: ~/.config/gog/credentials.json
+
+Starting OAuth flow...
+Opening browser for authentication...
+
+✓ OAuth token obtained for: tnapathy@gmail.com
+
+Credential stored:
+  Service: google
+  Account: tnapathy@gmail.com
+  Storage: 1password (Nexus vault)
+
+This connector is now ready. Tools using it:
+  • gog (email, calendar, drive)
+```
+
+#### `nexus connector list`
+
+List all connectors with their status.
+
+```bash
+nexus connector list                  # All connectors
+nexus connector list --ready          # Only configured
+nexus connector list --json           # JSON output
+```
+
+#### `nexus connector info <name>`
+
+Show connector details including which tools use it.
+
+```bash
+nexus connector info google-oauth
+```
+
+**Output:**
+```
+Connector: google-oauth
+Description: Google OAuth for workspace services
+
+Credentials required:
+  Type: oauth
+  Provider: google
+  Scopes: gmail, calendar, drive
+
+Configured accounts:
+  ● tnapathy@gmail.com (owner: user)
+  ○ echo@nexus.bot (owner: agent:echo) - needs setup
+
+Used by tools:
+  • gog (email, calendar, drive)
+  • goplaces (location-search)
+```
+
+---
+
+### `nexus guide` - Guide-Specific Operations
+
+Guides are mostly accessed via `nexus skill show/run`, but have one specific command.
+
+#### `nexus guide use <name>`
+
+Shortcut to output a guide's prompt (same as `nexus skill run <name>` for guides).
+
+```bash
+nexus guide use computer-use          # Output the guide
+nexus guide use filesystem            # Output the guide
+```
+
+---
+
+## Entity Resolution
+
+When a name is provided, nexus searches in order:
+1. `tools/<name>/SKILL.md`
+2. `connectors/<name>/SKILL.md`
+3. `guides/<name>/SKILL.md`
+4. Legacy `skills/<name>/SKILL.md` (during migration)
+
+If ambiguous (same name in multiple locations), prefer the explicit type command:
+```bash
+nexus tool show myname
+nexus connector show myname
+```
+
+---
+
+## State Tracking
+
+All `nexus skill run` invocations are logged to:
+```
+~/nexus/state/nexus/skills/<name>/
+├── state.json     # configured, lastUsed, lastVerified, errors
+└── usage.log      # JSON Lines of each invocation
+```
+
+See [STATE_ARCHITECTURE.md](./STATE_ARCHITECTURE.md) for schema details.
+
+---
+
+## Integration with Capabilities
+
+The `--provides` filter on `nexus skill list` queries the capability tags from entity frontmatter:
+
+```bash
+nexus skill list --provides email
+```
+
+Returns all entities where `provides: [email, ...]` in their schema.
+
+This enables the capability taxonomy to query what's available:
+- "Do I have email capability?" → `nexus skill list --provides email --ready`
+- "What would give me email?" → `nexus skill list --provides email --locked`
+
+---
+
+## Examples
+
+### Agent discovering capabilities
+
+```bash
+# What can I do right now?
+nexus skill list --ready --json
+
+# What's missing for email?
+nexus skill list --provides email --locked
+
+# Check if gog works
+nexus skill verify gog
+
+# Use gog
+nexus skill run gog gmail search "is:unread" --max 5
+```
+
+### User setting up a new tool
+
+```bash
+# Find email tools
+nexus skill list --provides email
+
+# Install gog
+nexus tool install gog
+
+# Setup authentication
+nexus connector setup google-oauth
+
+# Verify everything works
+nexus skill verify gog
+
+# Use it
+nexus skill run gog gmail search "is:unread"
+```
+
+### Checking what needs configuration
+
+```bash
+# What's locked?
+nexus skill list --locked
+
+# Why is spotify-player locked?
+nexus skill show spotify-player
+# Output shows: Requires connector: spotify
+
+# Setup the connector
+nexus connector setup spotify
+```
+
+---
+
+## Related Documents
+
+- [ENTITY_MODEL.md](./ENTITY_MODEL.md) - Entity type definitions and schemas
+- [SKILL_INVENTORY.md](./SKILL_INVENTORY.md) - Current skill categorization
+- [STATE_ARCHITECTURE.md](./STATE_ARCHITECTURE.md) - State file schemas
+- CLI_GRAMMAR_CREDENTIALS.md - Credential commands (TBD)
+- CLI_GRAMMAR_ONBOARDING.md - Onboarding commands (TBD)