@intent-systems/nexus 2026.1.5-4 → 2026.1.5-8

package/skills/guides/onboarding/docs/canonical/00_CONFLICT_ANALYSIS.md

@@ -0,0 +1,463 @@
+# Nexus Documentation Conflict Analysis
+
+> This document identifies all conflicts and inconsistencies across the existing onboarding documentation.
+> Use this to make decisions, then build the canonical docs in this folder.
+
+---
+
+## Overview
+
+After analyzing all 19 documentation files, I found **9 major conflict categories**. These need resolution before we can build a cohesive story.
+
+---
+
+## Conflict 1: CLI Philosophy — Gateway vs Discovery
+
+**This is the biggest conceptual conflict.** The docs fundamentally disagree on what the `nexus` CLI does.
+
+### Option A: Execution Gateway
+
+The CLI wraps ALL skill/tool execution. Every invocation is logged automatically.
+
+**Documents supporting this:**
+- `SKILL_GATEWAY_DESIGN.md`: "The skill gateway... wraps all skill execution. Every invocation is logged automatically"
+- `SKILL_GATEWAY_PRD.md`: "Build a CLI gateway that wraps all skill execution"
+- `GOAL_STATE_ARCHITECTURE.md`: "All skill access flows through `nexus skill use`"
+
+**Implications:**
+- Agent uses `nexus skill use gog` to get the guide, then runs `gog gmail search ...` directly
+- Automatic usage logging without agent cooperation
+- Gateway becomes single source of truth for skill state
+- More overhead, but complete observability
+
+### Option B: Discovery & Guidance System
+
+The CLI helps agents discover and learn about skills. Agents then use tools directly.
+
+**Documents supporting this:**
+- `CLI_GRAMMAR.md`: "Nexus is a discovery and guidance system, not an execution gateway. Agents read guides via `nexus skill use`, then use tools directly"
+- `DOCUMENTATION_OVERVIEW.md`: "Discovery + Guidance, Not Execution Gateway"
+
+**Implications:**
+- Agent runs `nexus skill use gog` to get the guide, then runs `gog gmail search ...` directly
+- Tracking measures "how often agents needed guidance" not "tool executions"
+- Honest model — agents can always use tools outside nexus anyway
+- Less overhead, but relies on agent cooperation for some tracking
+
+### Decision Needed
+
+Which philosophy do you want?
+
+| Aspect | Gateway | Discovery |
+|--------|---------|-----------|
+| **Tracking** | Automatic, complete | Voluntary, partial |
+| **Agent overhead** | Higher (every call through CLI) | Lower (direct tool usage) |
+| **Honesty** | Somewhat artificial (agent can bypass) | Honest about what we control |
+| **Complexity** | More complex CLI | Simpler CLI |
+
+---
+
+## Conflict 2: CLI Command Naming
+
+Different docs use different commands for the same operations.
+
+### Get a Skill Guide
+
+| Document | Command |
+|----------|---------|
+| `CLI_GRAMMAR.md` | `nexus skill use <name>` |
+| `CLI_GRAMMAR_SKILLS.md` | `nexus skill show <name> --prompt` |
+| `CLI_GRAMMAR_ONBOARDING.md` | `nexus guide use <name>` |
+| `SKILL_GATEWAY_*.md` | `nexus skill use <name>` (returns SKILL.md guide) |
+
+### View Full Capability Map
+
+| Document | Command |
+|----------|---------|
+| `CLI_GRAMMAR.md` | `nexus capabilities` |
+| `CLI_GRAMMAR_ONBOARDING.md` | `nexus map` |
+
+### Primary Status Command
+
+| Document | Command |
+|----------|---------|
+| `CLI_GRAMMAR.md` | `nexus status` |
+| `GOAL_STATE_ARCHITECTURE.md` | `nexus skills status` |
+| `NEXUS_SYSTEM_OVERVIEW.md` | `nexus skills status` |
+
+### View Skill Details
+
+| Document | Command |
+|----------|---------|
+| `CLI_GRAMMAR.md` | `nexus skill info <name>` |
+| `CLI_GRAMMAR_SKILLS.md` | `nexus skill show <name>` |
+| `SKILL_GATEWAY_*.md` | `nexus skill show <name>` |
+
+### Decision Needed
+
+Pick one command for each operation:
+
+| Operation | Options | Recommendation |
+|-----------|---------|----------------|
+| Get guide | `use` / `show --prompt` / `run` | `use` (clearest intent) |
+| Capability map | `capabilities` / `map` | `map` (shorter, more intuitive) |
+| Status | `status` / `skills status` | `status` (main entry point) |
+| Skill details | `info` / `show` | `info` (distinct from `use`) |
+
+---
+
+## Conflict 3: Entity Type Terminology
+
+The classification system for skills uses inconsistent names across documents.
+
+### Comparison
+
+| Document | Type 1 | Type 2 | Type 3 | Type 4 |
+|----------|--------|--------|--------|--------|
+| `ENTITY_MODEL.md` | **Tool** | **Connector** | **Guide** | — |
+| `CAPABILITY_TAXONOMY.md` | Pure Skills | Tool Skills | Connector Skills | — |
+| `SKILLS_SPECIFICATION.md` | Pure prompt | Tool-backed | Connector-backed | Script-backed |
+| `DOCUMENTATION_OVERVIEW.md` | Pure/Guide | Tool | Connector | — |
+
+### Key Questions
+
+1. **Do we need a "Script-backed" type?** 
+   - `SKILLS_SPECIFICATION.md` adds it as a 4th type
+   - Other docs don't mention it
+   - Examples: `brave-search` (node script), `openai-image-gen` (python script)
+
+2. **What do we call them?**
+   - Noun form: Tool / Connector / Guide
+   - Adjective form: Tool-backed / Connector-backed / Pure
+
+### Decision Needed
+
+| Question | Options | Recommendation |
+|----------|---------|----------------|
+| Number of types | 3 or 4 | 3 (scripts are a subset of tools) |
+| Naming convention | Noun / Adjective | Noun (Tool, Connector, Guide) |
+
+---
+
+## Conflict 4: Skill Folder Structure
+
+Are skill definitions split by type or kept in one folder?
+
+### Option A: Unified (Current?)
+
+```
+~/nexus/skills/
+├── gog/SKILL.md
+├── eve/SKILL.md
+├── google-oauth/SKILL.md
+├── discord/SKILL.md
+├── computer-use/SKILL.md
+├── filesystem/SKILL.md
+└── ...
+```
+
+**Documents using this:**
+- `NEXUS_SYSTEM_OVERVIEW.md`
+- `SKILLS_SPECIFICATION.md`
+- Root `AGENTS.md`
+
+### Option B: Split by Type (Chosen)
+
+```
+~/nexus/
+└── skills/
+    ├── tools/
+    │   ├── gog/SKILL.md
+    │   ├── eve/SKILL.md
+    │   └── ...
+    ├── connectors/
+    │   ├── google-oauth/SKILL.md
+    │   ├── discord/SKILL.md
+    │   └── ...
+    └── guides/
+        ├── computer-use/SKILL.md
+        ├── filesystem/SKILL.md
+        └── ...
+```
+
+**Documents using this:**
+- `ENTITY_MODEL.md`
+- `SKILL_INVENTORY.md` (migration plan)
+
+### Decision Needed
+
+| Option | Pros | Cons |
+|--------|------|------|
+| **Unified** | Simpler, already working | Harder to see what type something is |
+| **Split** | Clear separation, easier discovery | Requires migration, more complex paths |
+
+---
+
+## Conflict 5: Identity File Paths
+
+Minor but real inconsistency in how identity files are organized.
+
+### User Identity
+
+| Document | Path |
+|----------|------|
+| `STATE_ARCHITECTURE.md` | `state/user/IDENTITY.md` |
+| `CAPABILITY_TAXONOMY.md` | `state/user/IDENTITY.md` |
+| Root `AGENTS.md` | `~/nexus/state/user/IDENTITY.md` |
+
+**Conflicts:**
+- With or without `identity/` subdirectory?
+- File named `IDENTITY.md` (PROFILE.md is legacy)?
+
+### Agent Identity
+
+| Document | Path |
+|----------|------|
+| `STATE_ARCHITECTURE.md` | `state/agents/{name}/IDENTITY.md` |
+| `CAPABILITY_TAXONOMY.md` | `state/agents/{agent}/IDENTITY.md` |
+| Root `AGENTS.md` | `~/nexus/state/agents/echo/IDENTITY.md` |
+
+**Conflict:** With or without `identity/` subdirectory?
+
+### Decision
+
+| Component | Decision | Rationale |
+|-----------|----------|-----------|
+| User identity file | `state/user/IDENTITY.md` | Matches CLI and bootstrap behavior |
+| User file name | `IDENTITY.md` | Consistent with agent identity naming |
+| Agent identity | `state/agents/{name}/IDENTITY.md` | Simple, current implementation |
+
+---
+
+## Conflict 6: Credential Storage Path
+
+One document has a typo that could cause confusion.
+
+### Canonical (Correct)
+
+```
+state/credentials/{service}/accounts/{account}/auth/{type}.json
+```
+
+Example: `state/credentials/google/accounts/tyler@gmail.com/auth/oauth.json`
+
+**Documents using this:**
+- `CLI_GRAMMAR_CREDENTIALS.md`
+- `STATE_ARCHITECTURE.md`
+
+### Incorrect Reference
+
+`ENTITY_MODEL.md` has one diagram showing:
+```
+state/connectors/google/accounts/user@gmail.com/auth/oauth.json
+```
+
+Note: Uses `connectors` instead of `credentials`.
+
+### Decision
+
+This is just a typo to fix. The canonical path uses `credentials/`.
+
+---
+
+## Conflict 7: Per-Skill State — Single File vs Folders
+
+The skill state storage has two different approaches documented.
+
+### Option A: Single File (Possibly Legacy)
+
+```
+~/nexus/state/skill-state.json      # All skills in one file
+~/nexus/state/skill-usage.log       # All usage in one log
+```
+
+**Document mentioning this:**
+- `SKILLS_SPECIFICATION.md`: Shows this as "Current implementation"
+
+### Option B: Per-Skill Folders (Planned/Canonical)
+
+```
+~/nexus/state/nexus/skills/
+├── manifest.json
+├── gog/
+│   ├── state.json
+│   └── usage.log
+├── eve/
+│   ├── state.json
+│   └── usage.log
+└── ...
+```
+
+**Documents using this:**
+- `STATE_ARCHITECTURE.md` (canonical)
+- `SKILL_GATEWAY_DESIGN.md`
+- `SKILL_GATEWAY_PRD.md`
+
+### Decision Needed
+
+What's the actual current state? If single-file is legacy, we should only document the per-skill folder approach.
+
+---
+
+## Conflict 8: Capability Definition Approach
+
+How are capabilities defined and discovered?
+
+### Option A: Predefined Taxonomy
+
+All capabilities are predefined in a master list.
+
+**Document:**
+- `CAPABILITIES.md`: Exhaustive list of 58+ capabilities organized by category
+
+### Option B: Emergent Discovery
+
+Capabilities emerge organically from what tools/connectors declare.
+
+**Document:**
+- `ENTITY_MODEL.md`: "Capabilities are abstract interfaces — tags that describe what something enables. They emerge organically rather than being predefined."
+
+### Decision Needed
+
+These aren't necessarily contradictory — the taxonomy can be the current state while allowing organic emergence. But we should clarify:
+
+1. Is `CAPABILITIES.md` the exhaustive list, or just documentation of what exists?
+2. Can new capabilities be added without updating a master list?
+
+---
+
+## Conflict 9: What Documents Say About Each Other
+
+Some documents explicitly reference others, creating dependencies:
+
+| Document | References |
+|----------|------------|
+| `STATE_ARCHITECTURE.md` | Declared as canonical for paths and schemas |
+| `SKILL_GATEWAY_DESIGN.md` | Points to `STATE_ARCHITECTURE.md` |
+| `SKILL_GATEWAY_PRD.md` | Points to `STATE_ARCHITECTURE.md` |
+| `NEXUS_SYSTEM_OVERVIEW.md` | Says "defer to `STATE_ARCHITECTURE.md`" |
+| `DOCUMENTATION_OVERVIEW.md` | Maps all documents and their purposes |
+
+This is good — `STATE_ARCHITECTURE.md` is already treated as canonical for file paths.
+
+---
+
+## Conflict 10: Agent Bootstrap Enforcement
+
+Docs currently rely on the agent to remember to run `nexus status` and read
+identity files. That is not deterministic.
+
+### Option A: Rules + AGENTS.md Only
+
+- **Pros:** Simple, no scripting
+- **Cons:** Probabilistic, easy to miss
+
+### Option B: Cursor SessionStart Hook (Recommended)
+
+- **Pros:** Deterministic, runs before first response, can inject context
+- **Cons:** Requires hook files + script
+
+### Option C: Skills
+
+- **Pros:** Reuses existing packaging
+- **Cons:** Skills are doc-only; they do not execute
+
+### Decision Needed
+
+Use Cursor sessionStart hook as the authoritative bootstrap. Keep `AGENTS.md`
+and `.cursor/rules` as the fallback contract.
+
+---
+
+## Summary: Decisions Checklist
+
+| # | Decision | Options | Your Choice |
+|---|----------|---------|-------------|
+| 1 | CLI Philosophy | Gateway / Discovery | **Discovery** - CLI mediates skill docs, NOT tool execution |
+| 2 | Get guide command | `use` / `show` / `run` | **`nexus skill use <name>`** |
+| 3 | Capability map command | `map` / `capabilities` | **`nexus capabilities`** |
+| 4 | Status command | `status` / `skills status` | **`nexus status`** |
+| 5 | Skill details command | `info` / `show` | **`nexus skill info <name>`** |
+| 6 | Entity type names | Tool/Connector/Guide / other | **Tool / Connector / Guide** |
+| 7 | Number of entity types | 3 / 4 (include Script) | **3** (scripts can live in any skill) |
+| 8 | Skill folder structure | Unified / Split by type | **Split** under `skills/`: `skills/tools`, `skills/connectors`, `skills/guides` |
+| 9 | Identity subdirectory | With `identity/` / Without | **Without** subdirectory |
+| 10 | User identity filename | `PROFILE.md` / `IDENTITY.md` | **`IDENTITY.md`** for user + agent |
+| 11 | Per-skill state | Single file / Per-skill folders | **Per-skill folders** at `state/skills/{name}/` |
+| 12 | Capability definition | Predefined only / Allow emergence | **Predefined taxonomy** initially, emergence later |
+| 13 | Agent bootstrap enforcement | Rules / Hooks / Skills | **Hooks** (sessionStart), rules as fallback |
+
+### Key Conceptual Clarification
+
+**Skills ≠ Tools**
+
+The CLI wraps all **skill** access (returning SKILL.md guides), but does NOT wrap **tool** execution.
+
+```
+nexus skill use gogcli
+  → Returns the SKILL.md guide for gogcli
+  → Agent reads guide, learns how to use the gog binary
+  → Agent invokes `gog gmail search ...` DIRECTLY (not through nexus)
+```
+
+This distinction was the source of most confusion in the old docs.
+
+---
+
+## Canonical Documents Created
+
+Based on the resolved decisions, these canonical documents have been created:
+
+| Document | Purpose |
+|----------|---------|
+| `01_NEXUS_OVERVIEW.md` | Essential concepts, workspace structure |
+| `02_CLI_REFERENCE.md` | Complete command documentation |
+| `03_STATE_ARCHITECTURE.md` | File paths, schemas, storage |
+| `04_SKILL_SPECIFICATION.md` | How to create skills |
+| `05_CAPABILITY_TAXONOMY.md` | Onboarding journey |
+| `06_CAPABILITIES_REFERENCE.md` | Exhaustive capability list |
+| `07_AGENT_BINDINGS.md` | Agent bootstrap and binding flow |
+
+---
+
+## Old Documents to Delete
+
+Once you're happy with the canonical docs, these can be deleted:
+
+### Merge Complete - Delete
+
+| Old Document | Merged Into |
+|--------------|-------------|
+| `CLI_GRAMMAR.md` | `02_CLI_REFERENCE.md` |
+| `CLI_GRAMMAR_CREDENTIALS.md` | `02_CLI_REFERENCE.md` + `03_STATE_ARCHITECTURE.md` |
+| `CLI_GRAMMAR_ONBOARDING.md` | `02_CLI_REFERENCE.md` |
+| `CLI_GRAMMAR_SKILLS.md` | `02_CLI_REFERENCE.md` |
+| `STATE_ARCHITECTURE.md` | `03_STATE_ARCHITECTURE.md` |
+| `ENTITY_MODEL.md` | `04_SKILL_SPECIFICATION.md` |
+| `SKILLS_SPECIFICATION.md` | `04_SKILL_SPECIFICATION.md` |
+| `CAPABILITY_TAXONOMY.md` | `05_CAPABILITY_TAXONOMY.md` |
+| `CAPABILITIES.md` | `06_CAPABILITIES_REFERENCE.md` |
+| `DOCUMENTATION_OVERVIEW.md` | Obsolete |
+| `NEXUS_SYSTEM_OVERVIEW.md` | `01_NEXUS_OVERVIEW.md` |
+| `GOAL_STATE_ARCHITECTURE.md` | `01_NEXUS_OVERVIEW.md` |
+
+### Keep Separately
+
+| Document | Reason |
+|----------|--------|
+| `SKILLS_HUB_SPEC.md` | Future feature, not core docs |
+| `SKILL_INVENTORY.md` | Reference list of actual skills |
+| `USER_JOURNEY.md` | UX design reference |
+| `WOW_MOMENTS.md` | UX design reference |
+| `TROUBLESHOOTING.md` | Operational reference |
+| `SKILL_GATEWAY_DESIGN.md` | Implementation reference (archive) |
+| `SKILL_GATEWAY_PRD.md` | Implementation reference (archive) |
+
+---
+
+## Next Steps
+
+1. **Review** the 6 canonical docs in this folder
+2. **Iterate** if anything needs adjustment
+3. **Delete** old docs from parent folder
+4. **Move** canonical docs up (or keep in canonical/)

package/skills/guides/onboarding/docs/canonical/01_NEXUS_OVERVIEW.md

@@ -0,0 +1,167 @@
+# Nexus Overview
+
+> The essential concepts. Read this first.
+
+---
+
+## What is Nexus?
+
+Nexus is a personal AI workspace that gives agents capabilities through skills. It's a folder structure, a CLI, and a set of conventions that let agents:
+
+1. **Know who they are** (identity)
+2. **Know who you are** (user profile)
+3. **Discover what they can do** (skills → capabilities)
+4. **Remember across sessions** (memory)
+
+---
+
+## Core Concepts
+
+### Skills
+
+A **skill** is a folder containing a `SKILL.md` file that teaches an agent how to do something. Skills follow the [Agent Skills Specification](https://agentskills.io/specification).
+
+```
+skill-name/
+├── SKILL.md          # Required: instructions + frontmatter
+├── scripts/          # Optional: executable code
+├── references/       # Optional: additional docs
+└── assets/           # Optional: templates, images
+```
+
+**Key insight**: Skills are documentation, not execution wrappers. When an agent uses a skill, they get the guide. Then they act on it directly.
+
+### Skill Types
+
+Every skill has a `type` in its frontmatter:
+
+| Type | What it is | Example |
+|------|------------|---------|
+| **Guide** | Pure instructions using built-in capabilities | `filesystem`, `computer-use`, `weather` |
+| **Tool** | Instructions for installing and using a binary | `gog`, `eve`, `tmux`, `ffmpeg` |
+| **Connector** | Instructions for setting up auth/credentials | `google-oauth`, `anthropic`, `discord` |
+
+All three are skills. The type just indicates what kind of setup is needed.
+
+### Capabilities
+
+**Capabilities** are abstract goals: "Can the agent read email?" not "Is gog installed?"
+
+```
+Capability (abstract)  →  Provider (concrete)
+     email-read        →  gog + google-oauth
+     messaging-read    →  eve, imsg, wacli
+     web-search        →  brave-search
+```
+
+Multiple providers can satisfy the same capability. The capability taxonomy defines what's possible and tracks what's configured.
+
+### The CLI
+
+The `nexus` CLI is how agents interact with the system:
+
+```bash
+nexus status              # Orient: who am I, what can I do?
+nexus skill use <name>    # Get a skill's guide (SKILL.md)
+nexus skill info <name>   # Get metadata about a skill
+nexus capabilities        # See full capability map
+```
+
+**Important**: The CLI provides skill guides. It does NOT wrap tool execution. After reading a skill guide, agents use tools directly.
+
+```
+# This is what happens:
+nexus skill use gog       # → Returns SKILL.md guide
+gog gmail search "..."    # → Agent runs tool directly
+
+# The CLI does not execute tools.
+```
+
+---
+
+## Workspace Structure
+
+```
+~/nexus/
+├── AGENTS.md                    # Root instructions for agents
+├── .cursor/rules                # Cursor-specific config
+├── .cursor/hooks.json           # Cursor hooks config
+│   └── hooks/                   # Hook scripts
+│       └── nexus-session-start.js
+│
+├── skills/                      # Skill definitions (curated + managed)
+│   ├── tools/{name}/SKILL.md    # Tool skills
+│   ├── connectors/{name}/SKILL.md # Connector skills
+│   ├── guides/{name}/SKILL.md   # Guide skills
+│   └── managed/{slug}/          # Hub-installed skills
+│
+├── state/                       # All runtime state
+│   ├── user/
+│   │   └── IDENTITY.md          # User identity
+│   │
+│   ├── agents/
+│   │   └── {name}/
+│   │       ├── IDENTITY.md     # Agent name, emoji, nature
+│   │       ├── SOUL.md         # Personality, values
+│   │       └── MEMORY.md       # Long-term memories
+│   │
+│   ├── credentials/            # All secrets (linked to manager)
+│   │   └── {service}/accounts/{account}/auth/{type}.json
+│   │
+│   └── skills/                 # Per-skill runtime state
+│       └── {name}/
+│           ├── state.json      # Configured, last used, etc.
+│           └── usage.log       # Invocation history
+│
+└── home/                        # User's personal space
+    ├── memory/                  # Daily logs (YYYY-MM-DD.md)
+    └── projects/                # User's repos/projects
+```
+
+---
+
+## How It Works
+
+### Agent Session Start
+
+1. Cursor sessionStart hook runs (if configured)
+2. Hook runs `nexus status --json` and injects identity + memory context
+3. Agent reviews injected context and is ready to help
+4. If hooks are missing, follow `AGENTS.md` and run `nexus status` manually
+
+### Using a Skill
+
+1. Agent needs to do something (e.g., read email)
+2. Agent runs `nexus skill use gog`
+3. CLI returns the `gog/SKILL.md` content
+4. Agent follows the guide to use the `gog` binary
+5. Usage is logged to `state/skills/gog/usage.log`
+
+### Capability Discovery
+
+1. Agent runs `nexus capabilities`
+2. CLI shows all capabilities grouped by category
+3. Each capability shows status: active, ready, needs-setup, etc.
+4. Agent knows what's possible and what needs configuration
+
+---
+
+## Key Design Decisions
+
+| Decision | Choice | Why |
+|----------|--------|-----|
+| Skills are docs, not wrappers | Discovery, not execution | Honest model - agents can always use tools directly |
+| Split by type | `skills/tools`, `skills/connectors`, `skills/guides` | Clearer organization, easier to understand |
+| Capabilities are abstract | `email-read`, not `gog` | Portability - swap providers without changing skills |
+| Per-skill state folders | `state/skills/{name}/` | Isolation, git-friendly, extensible |
+| Credentials link to managers | 1Password, Keychain, etc. | Security - no plaintext secrets |
+
+---
+
+## What's Next
+
+- **[CLI Reference](./02_CLI_REFERENCE.md)** - Complete command documentation
+- **[State Architecture](./03_STATE_ARCHITECTURE.md)** - File paths and schemas
+- **[Skill Specification](./04_SKILL_SPECIFICATION.md)** - How to create skills
+- **[Capability Taxonomy](./05_CAPABILITY_TAXONOMY.md)** - Onboarding journey
+- **[Agent Bindings](./07_AGENT_BINDINGS.md)** - Hooks, rules, and bootstrap flow