@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/DOCUMENTATION_OVERVIEW.md

@@ -0,0 +1,290 @@
+# Nexus Documentation Overview
+
+*How all the onboarding documentation fits together.*
+
+---
+
+## The Big Picture
+
+Nexus is a personal AI workspace that gives agents increasing capabilities through a structured onboarding journey. The documentation describes three interconnected models:
+
+1. **The Capability Model** — What agents can DO (abstract goals)
+2. **The Skill Model** — HOW agents get capabilities (tools, connectors, guides)
+3. **The Journey Model** — The optimal PATH through onboarding
+
+---
+
+## Core Concepts
+
+### Capabilities vs Skills
+
+**Capabilities are goals, not tools.** "Can the agent read email?" not "Is gog installed?"
+
+```
+Capability (abstract)  →  Skill/Provider (concrete)
+     email-read        →  gog + google-oauth connector
+     messaging-read    →  imsg, eve, wacli
+     chat-send         →  discord, slack
+```
+
+A single capability can have multiple providers. A single provider can enable multiple capabilities.
+
+### The Three Skill Types
+
+Every skill falls into one of three types based on configuration requirements:
+
+| Type | Requires | Example | When Usable |
+|------|----------|---------|-------------|
+| **Pure/Guide** | Nothing | filesystem, computer-use, weather | Immediately after core onboarding |
+| **Tool** | Binary install | qmd, aix, video-frames | Agent installs, then usable |
+| **Connector** | User credentials/config | gog, discord, 1password | After user configures |
+
+This is THE key distinction. After core onboarding, you get ~8-10 immediately usable skills. Everything else requires user action to configure.
+
+### The Onboarding Journey
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         CORE ONBOARDING (Linear, Required)                  │
+│  1. Access Plane → 2. Nexus Install → 3. Agent Identity → 4. Workspace      │
+│                                                                             │
+│  Immediately usable: filesystem, computer-use, peekaboo, tmux, weather,    │
+│  songsee, qmd, aix, video-frames                                           │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                        ════ DEPTH TRACK ════
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    5. CREDENTIAL MANAGEMENT (Recommended)                   │
+│                    6. CLOUD SYNC (Insurance Layer)                          │
+│                                                                             │
+│  These are MULTIPLIERS — they make everything else easier/safer             │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                        ════ BREADTH TRACK ════
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                       CAPABILITY EXPANSION (Parallel)                       │
+│                                                                             │
+│  7. USER COMMS      │  8. USER DATA       │  9. ENABLE AGENTS              │
+│  (email, messaging) │  (storage, notes,   │  (API keys for LLMs)           │
+│                     │   calendar, code)   │                                 │
+│                                                                             │
+│  User chooses their own path here — all same level                         │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                   (Enable Agents unlocks next level)
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    AGENT INDEPENDENCE (Requires: Enable Agents)             │
+│                                                                             │
+│  10. AGENT COMMUNICATIONS  │  11. AUTOMATION                               │
+│  (Discord, Telegram)       │  (cron, reminders)                            │
+│                                                                             │
+│  Agent can reach user outside IDE, work while user sleeps                  │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                            12. FULL POWER                                   │
+│                                                                             │
+│  Email arrives → Agent reads it → Uses computer-use to act →               │
+│  Texts you via Discord → Sets reminder for follow-up                       │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+**Key insight:** Depth before breadth. Credential management and cloud sync are MULTIPLIERS — they make all breadth capabilities easier to configure and safer to use.
+
+### AI Power Formula
+
+```
+AI Power = Capability × Alignment × Duration × Throughput
+```
+
+| Factor | What It Measures | Key Unlocks |
+|--------|------------------|-------------|
+| **Capability** | What agent CAN do | Each connector adds capability |
+| **Alignment** | How well agent knows YOU | User comms, user data, identity |
+| **Duration** | How LONG agent can work | Automation, scheduling |
+| **Throughput** | PARALLEL agent work | Enable Agents + Agent Comms |
+
+---
+
+## Document Map
+
+### Architecture Documents
+
+| Document | Purpose | Read When... |
+|----------|---------|--------------|
+| **GOAL_STATE_ARCHITECTURE.md** | Defines ideal end-state for how agents interact with nexus | Understanding the vision, designing new features |
+| **STATE_ARCHITECTURE.md** | How credentials and state are stored (folder structure, JSON schemas) | Implementing credential handling, understanding file layout |
+| **CAPABILITY_TAXONOMY.md** | Complete mapping of capabilities → skills → onboarding journey | Understanding what capabilities exist and the optimal onboarding path |
+
+### Capability & Skill Documents
+
+| Document | Purpose | Read When... |
+|----------|---------|--------------|
+| **CAPABILITIES.md** | Exhaustive list of ALL capabilities with providers and setup requirements | Looking up what provides a specific capability |
+| **ENTITY_MODEL.md** | Defines the three entity types (tools, connectors, guides) | Understanding skill classification |
+| **SKILLS_SPECIFICATION.md** | SKILL.md file format and metadata schema | Creating new skills |
+| **SKILL_INVENTORY.md** | Catalog of all existing skills | Finding what skills exist |
+
+### CLI Documents
+
+| Document | Purpose | Read When... |
+|----------|---------|--------------|
+| **CLI_GRAMMAR.md** | Complete nexus CLI command reference | Implementing CLI commands |
+| **CLI_GRAMMAR_ONBOARDING.md** | Onboarding-specific CLI flows | Implementing bootstrap and onboarding UX |
+| **CLI_GRAMMAR_SKILLS.md** | Skill-specific CLI commands | Implementing skill discovery/usage commands |
+| **CLI_GRAMMAR_CREDENTIALS.md** | Credential management CLI | Implementing credential add/list/verify |
+
+### User Experience Documents
+
+| Document | Purpose | Read When... |
+|----------|---------|--------------|
+| **USER_JOURNEY.md** | End-to-end user onboarding experience | Understanding user flow |
+| **WOW_MOMENTS.md** | Key moments that demonstrate value | Designing features that impress users |
+| **TROUBLESHOOTING.md** | Common problems and solutions | Debugging issues |
+
+### Skill Deep Dives
+
+The `skill-deep-dives/` folder contains detailed documentation for individual skills:
+
+| Document | Covers |
+|----------|--------|
+| `1password.md` | Credential manager setup |
+| `gog.md` | Google OAuth and Gmail/Calendar/Drive |
+| `eve.md` | iMessage relationship insights |
+| `aix.md` | AI session history |
+| `discord.md` | Discord bot setup |
+| `telegram.md` | Telegram bot setup |
+| `brave-search.md` | Web search API |
+| `computer-use.md` | GUI automation |
+| `cron-and-heartbeat.md` | Scheduled tasks |
+| `nexus-cloud.md` | Cloud sync |
+| `github.md` | Version control |
+| `weather.md` | Weather API |
+| `qmd.md` | Local semantic search |
+| `wacli.md` | WhatsApp |
+| `comms.md` | Communication insights |
+| `bird.md` | Twitter/X |
+| `homebrew-prereqs.md` | Tool installation |
+| `TEMPLATE.md` | Template for new deep dives |
+
+---
+
+## How Documents Relate
+
+```
+                    ┌─────────────────────────────────┐
+                    │   GOAL_STATE_ARCHITECTURE.md    │
+                    │   (Vision & design principles)  │
+                    └─────────────┬───────────────────┘
+                                  │ informs
+          ┌───────────────────────┼───────────────────────┐
+          │                       │                       │
+          ▼                       ▼                       ▼
+┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
+│ STATE_ARCHITECTURE  │ │ CAPABILITY_TAXONOMY │ │    CLI_GRAMMAR      │
+│ (How state stored)  │ │ (What's possible)   │ │ (How to interact)   │
+└─────────┬───────────┘ └─────────┬───────────┘ └─────────┬───────────┘
+          │                       │                       │
+          │ specifies             │ lists                 │ implements
+          │                       │                       │
+          ▼                       ▼                       ▼
+┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
+│  credentials/       │ │   CAPABILITIES.md   │ │  CLI_GRAMMAR_*.md   │
+│  state/nexus/       │ │   (All caps)        │ │  (Subcommands)      │
+│  state/agents/      │ │                     │ │                     │
+└─────────────────────┘ └─────────┬───────────┘ └─────────────────────┘
+                                  │
+                                  │ provided by
+                                  ▼
+                    ┌─────────────────────────────────┐
+                    │        SKILL_INVENTORY.md       │
+                    │        ENTITY_MODEL.md          │
+                    │        SKILLS_SPECIFICATION.md  │
+                    └─────────────┬───────────────────┘
+                                  │
+                                  │ documented in
+                                  ▼
+                    ┌─────────────────────────────────┐
+                    │       skill-deep-dives/*.md     │
+                    └─────────────────────────────────┘
+```
+
+---
+
+## Key Design Decisions
+
+These decisions are documented across the architecture docs:
+
+### 1. Nexus is Source of Truth
+- Agents query `nexus` CLI, don't parse state files directly
+- State format can change without breaking agents
+- `nexus status` is THE entry point for agent orientation
+
+### 2. Discovery + Guidance, Not Execution Gateway
+- Agents read guides via `nexus skill use`, then use tools directly
+- Tracking measures "how often agents needed guidance" not "tool executions"
+- Honest model — agents can always use tools outside nexus
+
+### 3. Clear Ownership Boundaries
+| Owner | Owns | Can Modify |
+|-------|------|------------|
+| **User** | `home/` directory | Everything in home/, identity via conversation |
+| **Nexus CLI** | Root AGENTS.md, .cursorrules, state/nexus/, skills/ | All nexus-owned files |
+| **Agent** | Nothing directly | Writes to state/agents/{agent}/ with permission |
+
+### 4. Credentials Link to Managers
+- Never store plaintext secrets by default
+- Link to 1Password, Keychain, or external CLI tokens
+- `credentials/index.json` for fast lookup, tree walk for flexibility
+
+### 5. Graceful Degradation
+- System works without full configuration
+- Pure/guide skills work immediately
+- More capabilities unlock as credentials are added
+
+---
+
+## Reading Order for Contributors
+
+**New to nexus?**
+1. This document (DOCUMENTATION_OVERVIEW.md)
+2. GOAL_STATE_ARCHITECTURE.md — understand the vision
+3. CAPABILITY_TAXONOMY.md — understand the journey
+4. CLI_GRAMMAR.md — understand the interface
+
+**Implementing CLI features?**
+1. CLI_GRAMMAR.md — main reference
+2. CLI_GRAMMAR_*.md — specific command groups
+3. STATE_ARCHITECTURE.md — where data lives
+
+**Creating new skills?**
+1. ENTITY_MODEL.md — understand skill types
+2. SKILLS_SPECIFICATION.md — SKILL.md format
+3. skill-deep-dives/TEMPLATE.md — documentation template
+
+**Debugging issues?**
+1. TROUBLESHOOTING.md — common problems
+2. Relevant skill-deep-dives/*.md
+
+---
+
+## What's Not Documented Yet
+
+Areas that need documentation:
+
+- [ ] Multi-agent support (deferred, assuming single agent)
+- [ ] Advanced memory extraction (v2 vision)
+- [ ] Reactive triggers implementation
+- [ ] nexus-cloud sync protocol
+- [ ] MCP server integration patterns
+
+---
+
+*This overview is the starting point for understanding nexus onboarding documentation. When in doubt, start here.*