@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/ENTITY_MODEL.md

@@ -0,0 +1,582 @@
+# Nexus Entity Model
+
+> The definitive specification for how Nexus organizes tools, connectors, and guides.
+
+## Overview
+
+Nexus breaks from the monolithic "skill" abstraction used by other agent frameworks. Instead, we recognize three distinct entity types that compose together:
+
+| Entity | What It Is | Has Guide? | Provides Capabilities? |
+|--------|-----------|------------|------------------------|
+| **Tool** | Binary/CLI that does work | Yes (usage) | Yes |
+| **Connector** | Service auth + credentials | Yes (setup) | Yes |
+| **Guide** | Standalone instructions | IS the guide | Sometimes |
+
+**Key insight:** Everything has an associated prompt/guide (SKILL.md), but the *type* determines what that guide is for and what dependencies exist.
+
+---
+
+## Entity Types
+
+All entity types follow the [Agent Skills Specification](https://agentskills.io/specification) folder structure:
+
+```
+{entity}/
+├── SKILL.md              # Required: frontmatter + guide
+├── scripts/              # Optional: executable scripts
+├── references/           # Optional: documentation, examples
+└── assets/               # Optional: images, templates
+```
+
+The `scripts/` folder is particularly important—it's where explorations and learnings accumulate. A connector might ship with utility scripts, or users/agents can add their own as they work with the entity.
+
+---
+
+### Tool
+
+A **tool** is a binary, CLI, or script that performs actual work. Tools are stateful—they may own caches, databases, or local files.
+
+**Examples:** `gog`, `eve`, `qmd`, `imsg`, `peekaboo`, `aix`
+
+**Characteristics:**
+- Installable via package manager, binary download, or script
+- May require one or more connectors for auth
+- Provides capabilities (e.g., `email`, `calendar`)
+- Has state (caches, local DBs, config files)
+- Platform/OS dependent
+
+**Schema:**
+
+```yaml
+---
+name: gog
+type: tool
+description: Google Workspace CLI for Gmail, Calendar, Drive, Contacts, Sheets, People, and Tasks.
+homepage: https://gogcli.sh
+emoji: 📧
+
+# What this tool enables
+provides: [email, calendar, drive, contacts, sheets, tasks]
+
+# Dependencies
+requires:
+  connectors: [google-oauth]    # Auth required
+  bins: [gog]                   # Binary name (for verification)
+
+# Platform constraints
+os: [darwin, linux]             # Optional, defaults to all
+
+# Installation options
+install:
+  - id: brew
+    kind: brew
+    formula: steipete/tap/gogcli
+    bins: [gog]
+    label: "Install gog via Homebrew"
+  - id: go
+    kind: go
+    package: github.com/steipete/gogcli
+    bins: [gog]
+    label: "Install gog via Go"
+
+# Where this tool keeps its own state (informational)
+toolState:
+  config: ~/.config/gog/
+  cache: ~/.cache/gog/
+---
+
+# Tool Guide
+
+Instructions for installing and using gog...
+```
+
+**Folder structure example:**
+```
+tools/gog/
+├── SKILL.md              # Tool guide + schema
+├── scripts/
+│   └── cdp/              # Browser automation helpers
+│       ├── create_oauth_client.py
+│       └── README.md
+└── docs/
+    ├── setup.md          # Detailed setup (points to google-oauth connector)
+    └── portability.md    # Moving between machines
+```
+
+### Connector
+
+A **connector** provides authentication and access to an external service. Connectors are stateless in themselves—the actual credentials live in `state/credentials/`.
+
+**Examples:** `google-oauth`, `anthropic`, `discord`, `brave-search`, `github`, `notion`, `trello`
+
+**Characteristics:**
+- Handles auth (OAuth, API keys, tokens)
+- Credentials stored in `state/credentials/{service}/accounts/{account}/auth/`
+- May be shared by multiple tools
+- Provides capabilities or enables tools that do
+- Setup guide explains how to configure credentials
+- **Can include scripts** for API interaction (e.g., curl wrappers, utility scripts)
+
+**Schema:**
+
+```yaml
+---
+name: brave-search
+type: connector
+description: Web search via Brave Search API.
+homepage: https://brave.com/search/api
+emoji: 🦁
+
+# What this connector enables
+provides: [web-search]
+
+# Credential requirements
+credentials:
+  type: api-key
+  provider: brave
+  env: BRAVE_API_KEY              # Environment variable name
+
+# Storage options (where to look for credentials)
+storage:
+  - type: 1password
+    vault: Nexus
+    item: "Brave Search API Key"
+  - type: env
+    var: BRAVE_API_KEY
+  - type: file
+    path: state/credentials/brave-search/accounts/{account}/auth/api-key.json
+---
+
+# Connector Setup Guide
+
+How to get and configure your Brave Search API key...
+
+## Get API Key
+1. Go to https://brave.com/search/api
+2. Sign up / sign in
+3. Create an API key
+
+## Configure
+Store via 1Password (recommended):
+```bash
+op item create --category="API Credential" --title="Brave Search API Key" --vault="Nexus" api_key="your-key"
+```
+
+Or set environment variable:
+```bash
+export BRAVE_API_KEY="your-key"
+```
+```
+
+**Folder structure example (connector with scripts):**
+```
+connectors/brave-search/
+├── SKILL.md              # Setup guide + schema
+└── scripts/
+    ├── search.mjs        # Search utility script
+    └── content.mjs       # Content extraction script
+```
+
+**Note:** Connectors can ship with utility scripts. Users/agents can also add their own scripts as they explore the API—the `scripts/` folder becomes a place to accumulate learnings and patterns.
+
+### Guide
+
+A **guide** is a standalone set of instructions—a prompt that helps accomplish something. Guides may depend on tools and/or connectors, or may be entirely self-contained.
+
+**Examples:** `computer-use`, `filesystem`, `coding-agent`, `weather`, `oracle`
+
+**Characteristics:**
+- Pure instructions (the .md file IS the value)
+- May reference tools/connectors as dependencies
+- Stateless
+- Platform-independent (usually)
+- Can provide capabilities through instruction templates
+- **Can accumulate scripts** as users/agents explore and learn
+
+**Schema:**
+
+```yaml
+---
+name: computer-use
+type: guide
+description: GUI automation patterns using available screen control tools.
+emoji: 🖥️
+
+# What this guide enables (optional)
+provides: [gui-automation]
+
+# Platform constraints (if any)
+os: [darwin, linux]
+
+# Dependencies - flexible options
+requires:
+  anyTools: [peekaboo, interpreter, browser-use]  # One of these
+  # OR specific:
+  # tools: [specific-tool]
+  # connectors: [specific-connector]
+  # capabilities: [email]  # Abstract - any provider works
+---
+
+# Computer Use Guide
+
+Instructions for automating GUI interactions...
+```
+
+**Folder structure example:**
+```
+guides/computer-use/
+├── SKILL.md              # The guide itself
+├── scripts/              # Accumulated automation scripts
+│   ├── oauth-flow.py     # Reusable OAuth automation
+│   └── form-fill.sh      # Form filling helper
+└── references/
+    └── tool-comparison.md
+```
+
+**Note:** Guides can start empty and accumulate scripts over time. As the user/agent explores a workflow, successful patterns get crystallized into reusable scripts in the `scripts/` folder.
+
+---
+
+## Capabilities
+
+**Capabilities are abstract interfaces**—tags that describe what something enables. They emerge organically rather than being predefined.
+
+```yaml
+# A tool declares what it provides
+provides: [email, calendar, drive]
+
+# A guide declares what it requires (abstractly)
+requires:
+  capabilities: [email]  # Any tool/connector providing "email" works
+```
+
+**How capabilities emerge:**
+1. First tool ships: `gog` with `provides: [email, calendar]`
+2. Second tool ships: `outlook-cli` with `provides: [email, calendar]`
+3. Pattern recognized → `email` and `calendar` are now established capabilities
+4. Guides can require `capabilities: [email]` without specifying a tool
+
+**Capability examples:**
+- `email` - Send/receive email
+- `calendar` - Calendar access
+- `messaging` - SMS/iMessage/etc
+- `search` - Web search
+- `llm` - LLM API access
+- `storage` - Cloud file storage
+- `version-control` - Git/GitHub/GitLab
+
+---
+
+## Folder Structure
+
+```
+~/nexus/
+├── tools/                          # Tool definitions + guides
+│   ├── gog/
+│   │   ├── SKILL.md               # type: tool
+│   │   ├── scripts/               # Utility scripts
+│   │   └── docs/
+│   ├── eve/
+│   ├── imsg/
+│   ├── aix/
+│   ├── peekaboo/
+│   └── qmd/
+│
+├── connectors/                     # Connector definitions + setup guides
+│   ├── google-oauth/
+│   │   ├── SKILL.md               # type: connector (setup guide)
+│   │   └── scripts/               # OAuth helper scripts
+│   ├── brave-search/
+│   │   ├── SKILL.md               # type: connector
+│   │   └── scripts/
+│   │       ├── search.mjs
+│   │       └── content.mjs
+│   ├── discord/
+│   ├── slack/
+│   ├── notion/
+│   ├── trello/
+│   ├── github/
+│   ├── anthropic/
+│   └── openai/
+│
+├── guides/                         # Standalone guides
+│   ├── computer-use/
+│   │   ├── SKILL.md               # type: guide
+│   │   └── scripts/               # Accumulated automations
+│   ├── filesystem/
+│   ├── coding-agent/
+│   ├── weather/
+│   └── oracle/
+│
+└── state/
+    └── credentials/                # Runtime credentials (user data)
+        ├── index.json
+        ├── google/
+        │   ├── config.json        # Shared OAuth client config
+        │   └── accounts/
+        │       └── user@gmail.com/
+        │           └── auth/
+        │               └── oauth.json
+        ├── anthropic/
+        │   └── accounts/
+        │       └── personal/
+        │           └── auth/
+        │               └── api-key.json
+        ├── brave-search/
+        │   └── accounts/
+        │       └── tyler@brave.com/
+        │           └── auth/
+        │               └── api-key.json
+        └── ...
+```
+
+**Key distinction:**
+- `connectors/` (root level) = Definitions + setup guides + scripts (distributable via hub)
+- `state/credentials/` = Runtime credentials (user-specific, never distributed)
+
+This keeps naming clear: "connectors" are the packages you install, "credentials" are the secrets you configure.
+
+---
+
+## Dependency Chain
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ GUIDE: "email-insights"                                         │
+│   type: guide                                                   │
+│   requires:                                                     │
+│     tools: [eve]                                                │
+│     connectors: [google-oauth]                                  │
+└─────────────────────────────────────────────────────────────────┘
+                         ↓ depends on
+┌─────────────────────────────────────────────────────────────────┐
+│ TOOL: "eve"                                                     │
+│   type: tool                                                    │
+│   provides: [communication-analytics]                           │
+│   requires:                                                     │
+│     tools: [imsg, gog]  # data sources                          │
+└─────────────────────────────────────────────────────────────────┘
+                         ↓ depends on
+┌─────────────────────────────────────────────────────────────────┐
+│ TOOL: "gog"                                                     │
+│   type: tool                                                    │
+│   provides: [email, calendar, drive]                            │
+│   requires:                                                     │
+│     connectors: [google-oauth]                                  │
+└─────────────────────────────────────────────────────────────────┘
+                         ↓ depends on
+┌─────────────────────────────────────────────────────────────────┐
+│ CONNECTOR: "google-oauth"                                       │
+│   type: connector                                               │
+│   provides: [google-auth]                                       │
+│   credentials: oauth @ google                                   │
+└─────────────────────────────────────────────────────────────────┘
+                         ↓ stored in
+┌─────────────────────────────────────────────────────────────────┐
+│ STATE: connectors/google/accounts/user@gmail.com/auth/oauth.json│
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Invocation
+
+All entities are invoked through `nexus`:
+
+```bash
+# Generic invocation (type inferred from registry)
+nexus skill gog
+nexus skill google-oauth
+nexus skill computer-use
+
+# Type-specific invocation
+nexus tool gog
+nexus connector google-oauth
+nexus guide computer-use
+
+# Actions
+nexus tool gog install       # Run installation
+nexus tool gog verify        # Check if working
+nexus connector google-oauth setup   # Interactive setup
+nexus guide computer-use     # Output the guide
+```
+
+**What invocation does:**
+1. Loads the SKILL.md for the entity
+2. Checks dependencies (are required tools installed? connectors configured?)
+3. Outputs the guide/prompt content
+4. Logs usage to `state/nexus/skills/{name}/usage.log`
+
+---
+
+## State Tracking
+
+Each entity has runtime state tracked in `state/nexus/skills/{name}/`:
+
+```
+state/nexus/skills/gog/
+├── state.json     # Configuration status, last used, etc.
+└── usage.log      # Invocation history (JSON Lines)
+```
+
+**state.json:**
+```json
+{
+  "configured": true,
+  "verified": true,
+  "lastUsed": "2025-01-12T10:30:00Z",
+  "lastVerified": "2025-01-10T08:00:00Z",
+  "totalInvocations": 47,
+  "errors": []
+}
+```
+
+**usage.log (JSON Lines):**
+```jsonl
+{"ts":"2025-01-12T10:30:00Z","action":"invoke","success":true,"durationMs":1200}
+{"ts":"2025-01-12T09:15:00Z","action":"verify","success":true}
+```
+
+---
+
+## Hub Distribution
+
+The Nexus Hub will distribute:
+
+| Entity Type | What's Distributed | User Action |
+|------------|-------------------|-------------|
+| Tool | SKILL.md + docs | Install binary, configure connector |
+| Connector | SKILL.md (setup guide) | Add credentials |
+| Guide | SKILL.md | Just use it |
+
+**Installation flow:**
+```bash
+nexus hub install gog           # Downloads tool definition
+nexus tool gog install          # Installs the binary
+nexus connector google-oauth setup  # Walks through auth setup
+nexus tool gog verify           # Confirms everything works
+```
+
+---
+
+## Migration from Legacy Skills
+
+Many existing "skills" are actually composite entities. Migration approach:
+
+| Legacy Skill | Becomes |
+|-------------|---------|
+| `gog/SKILL.md` | `tools/gog/` + `connectors/google-oauth/` |
+| `brave-search/SKILL.md` | `connectors/brave-search/` (API key only) |
+| `computer-use/SKILL.md` | `guides/computer-use/` |
+| `filesystem/SKILL.md` | `guides/filesystem/` |
+| `eve/SKILL.md` | `tools/eve/` |
+
+---
+
+## Schema Summary
+
+### Common Fields (all types)
+
+```yaml
+name: string                    # Unique identifier
+type: tool | connector | guide  # Entity type
+description: string             # What it does
+homepage: string                # Optional URL
+emoji: string                   # Optional display emoji
+provides: [string]              # Capabilities provided (optional)
+os: [darwin | linux | windows]  # Platform constraints (optional, defaults to all)
+```
+
+### Tool-specific
+
+```yaml
+requires:
+  connectors: [string]  # Required connectors for auth
+  tools: [string]       # Required tools (dependencies)
+  bins: [string]        # Binary names (for verification)
+
+install: [InstallOption]  # How to install
+
+toolState:              # Where tool keeps its own state (informational)
+  config: string
+  cache: string
+```
+
+### Connector-specific
+
+```yaml
+credentials:
+  type: oauth | api-key | token | custom
+  provider: string      # Service provider name
+  env: string           # Environment variable name
+  scopes: [string]      # For OAuth
+
+storage: [StorageOption]  # Where/how to store credentials
+```
+
+### Guide-specific
+
+```yaml
+requires:
+  tools: [string]        # Specific tools needed
+  connectors: [string]   # Specific connectors needed
+  anyTools: [string]     # One of these tools works
+  capabilities: [string] # Abstract requirement (any provider)
+```
+
+---
+
+## Agent Skills Compatibility
+
+Our schema extends the [Agent Skills Specification](https://agentskills.io/specification). To export for compatibility:
+
+**Nexus format (detailed):**
+```yaml
+---
+name: gog
+type: tool
+description: Google Workspace CLI...
+emoji: 📧
+provides: [email, calendar, drive]
+requires:
+  connectors: [google-oauth]
+  bins: [gog]
+os: [darwin, linux]
+install:
+  - id: brew
+    kind: brew
+    formula: steipete/tap/gogcli
+---
+```
+
+**Agent Skills format (compatible export):**
+```yaml
+---
+name: gog
+description: Google Workspace CLI...
+homepage: https://gogcli.sh
+metadata:
+  nexus:
+    type: tool
+    emoji: 📧
+    provides: [email, calendar, drive]
+    requires:
+      connectors: [google-oauth]
+      bins: [gog]
+    os: [darwin, linux]
+    install:
+      - id: brew
+        kind: brew
+        formula: steipete/tap/gogcli
+---
+```
+
+The `metadata.nexus` wrapper maintains compatibility while preserving our richer schema.
+
+---
+
+## Related Documents
+
+- [STATE_ARCHITECTURE.md](./STATE_ARCHITECTURE.md) - Credential storage details
+- [CAPABILITY_TAXONOMY.md](./CAPABILITY_TAXONOMY.md) - Onboarding capability levels
+- [NEXUS_SYSTEM_OVERVIEW.md](./NEXUS_SYSTEM_OVERVIEW.md) - Full system architecture