@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/CLI_GRAMMAR_ONBOARDING.md

@@ -0,0 +1,815 @@
+# CLI Grammar: Onboarding & Capability Guidance
+
+> Commands for orientation, capability discovery, and guided progression.
+
+---
+
+## Philosophy
+
+The onboarding system is NOT a one-time wizard. It's an ongoing **capability guide** that:
+
+1. **Detects** your current state dynamically (identity, credentials, skills, usage)
+2. **Knows** what's possible (full capability map)
+3. **Recommends** what to try next (optimal path to full power)
+4. **Encourages** exploration of untried capabilities
+5. **Ties** recommendations to what you're working on
+
+Think of it as a **mentor/sage** that helps you grow your AI power, not a setup wizard you run once.
+
+---
+
+## Commands Overview
+
+```bash
+nexus
+├── status          # Main entry - state snapshot for agents
+├── map             # Full capability map - what's possible
+├── quest           # Recommendations - what to do next
+└── init            # (existing) Create workspace
+```
+
+---
+
+## Workspace Configuration
+
+Track OS and platform info at workspace level for capability availability:
+
+```json
+// state/nexus/workspace.json
+{
+  "os": "darwin",           // darwin, linux, windows
+  "arch": "arm64",          // arm64, x64
+  "created": "2026-01-12T10:00:00Z",
+  "lastAccess": "2026-01-15T14:30:00Z"
+}
+```
+
+This enables `nexus status` and `nexus map` to correctly mark capabilities as `⛔ unavailable` for the current platform.
+
+---
+
+## Bootstrap Detection
+
+**Any `nexus` command** (except `init`) checks for identity. If missing, output guides whoever is reading it:
+
+```bash
+$ nexus status
+
+╔════════════════════════════════════════════════════════════════╗
+║                    Welcome to Nexus! 🌟                        ║
+╠════════════════════════════════════════════════════════════════╣
+║                                                                ║
+║  This is a fresh workspace. Identity setup required.           ║
+║                                                                ║
+╚════════════════════════════════════════════════════════════════╝
+
+┌────────────────────────────────────────────────────────────────┐
+│  FOR HUMANS:                                                   │
+│                                                                │
+│  Start a conversation with your AI assistant. Tell them:       │
+│  - Your name and what you'd like to be called                 │
+│  - What you're hoping to accomplish with AI                   │
+│  - Any preferences for how they should communicate            │
+│                                                                │
+│  The AI will create identity files as you chat. Takes ~5 min. │
+└────────────────────────────────────────────────────────────────┘
+
+┌────────────────────────────────────────────────────────────────┐
+│  FOR AGENTS:                                                   │
+│                                                                │
+│  You are beginning a bootstrap conversation. Your goals:       │
+│                                                                │
+│  1. Learn the user's name                                      │
+│     → Create: state/user/identity/PROFILE.md                  │
+│                                                                │
+│  2. Let the user name you                                      │
+│     → Create: state/agents/{name}/identity/IDENTITY.md        │
+│                                                                │
+│  3. Develop your personality together                          │
+│     → Create: state/agents/{name}/identity/SOUL.md            │
+│                                                                │
+│  4. Initialize your memory                                     │
+│     → Create: state/agents/{name}/identity/MEMORY.md          │
+│                                                                │
+│  5. Understand their goals and interests                       │
+│                                                                │
+│  Be warm, curious, and conversational. Don't rush through a   │
+│  checklist. Ask follow-up questions. Make it feel like        │
+│  getting to know a new friend.                                 │
+│                                                                │
+│  When complete, run `nexus status` to show them what's        │
+│  unlocked and suggest the filesystem organization wow moment. │
+└────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## `nexus status`
+
+**Purpose**: Main entry point for agents. Shows current state, capabilities, and suggestions.
+
+This is THE command agents run at startup (via AGENTS.md and cursorrules) to orient themselves. The output can be detailed — agents need full context.
+
+### Output Structure
+
+```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: auth expired
+   
+   Run `nexus credential list` for full details
+
+🎯 Capabilities (18/58 active)
+   
+   🗣️ Communication:
+     ✅ email-read, email-send (gog)
+     ✅ messaging-read (eve, imsg)
+     ⭐ chat-read, chat-send (discord) - ready, never used
+     ✅ contacts (gog)
+   
+   🔮 Insights:
+     ✅ relationship-insights (eve)
+     ⭐ session-insights (aix) - ready
+   
+   🤖 Automation:
+     ✅ scheduling (3 active jobs)
+     📥 reactive-triggers
+     ✅ gui-automation (peekaboo)
+     ✅ browser-automation (computer-use)
+   
+   🧠 AI & LLM:
+     ✅ anthropic
+     ✅ openai
+     ✅ gemini
+   
+   💻 Development:
+     ✅ version-control (github)
+     ✅ terminal-sessions (tmux)
+   
+   🎵 Music:
+     ⭐ spotify - ready
+   
+   Run `nexus map` for full capability breakdown
+
+📊 Usage (last 7 days)
+   Most used: gog (47), eve (23), summarize (18)
+   Ready but unused: discord, aix, spotify
+   
+🎯 Suggestions
+   
+   1. 💬 Try Discord! You have it configured but never used.
+      Your agent can message you outside Cursor.
+      → nexus guide use discord
+   
+   2. 📈 Set up reactive-triggers
+      With email + scheduling, you could auto-respond to events.
+      → nexus quest
+   
+   3. 🔄 Fix twitter credentials (auth expired)
+      → nexus credential verify twitter
+
+╔════════════════════════════════════════════════════════════════╗
+║  Power Level: ████████░░ 78%                                   ║
+║  Next unlock: Agent Communications (+15%)                      ║
+║                                                                ║
+║  Complete CAPABILITY_TAXONOMY path to reach 100%!              ║
+║  (Some users have reached 120%+ with extra integrations)       ║
+╚════════════════════════════════════════════════════════════════╝
+```
+
+### How Suggestions Are Generated
+
+Suggestions are prioritized by:
+
+1. **Broken credentials** — Fix anything that stopped working
+2. **Ready but unused** — You configured it, try it!
+3. **Next in CAPABILITY_TAXONOMY** — Optimal path to power
+4. **Quick wins** — Easy 5-minute setups available
+
+The suggestion strings are generated from a combination of:
+- Static templates for known scenarios
+- Dynamic data (which credentials are ready, what's broken)
+- The optimal path from CAPABILITY_TAXONOMY.md
+
+### Flags
+
+```bash
+nexus status [options]
+
+Options:
+  --json              Output as JSON (for programmatic use)
+  --brief             Compact output (identity + suggestions only)
+  --capabilities      Focus on capability breakdown
+  --credentials       Focus on credential status
+  --usage             Focus on usage statistics
+  --quiet             Minimal output, exit codes only
+```
+
+### JSON Output
+
+```bash
+$ nexus status --json
+```
+
+```json
+{
+  "workspace": {
+    "os": "darwin",
+    "arch": "arm64"
+  },
+  "identity": {
+    "user": {
+      "name": "Tyler",
+      "handle": "tyler",
+      "profile": "state/user/identity/PROFILE.md",
+      "exists": true
+    },
+    "agent": {
+      "name": "Echo",
+      "identity": "state/agents/echo/identity/IDENTITY.md",
+      "soul": "state/agents/echo/identity/SOUL.md",
+      "memory": "state/agents/echo/identity/MEMORY.md",
+      "exists": true
+    }
+  },
+  "credentials": {
+    "total": 12,
+    "broken": 1,
+    "llmProviders": [
+      {"service": "anthropic", "account": "tyler@anthropic.com", "status": "active"},
+      {"service": "openai", "account": "tyler@openai.com", "status": "active"},
+      {"service": "gemini", "account": "tyler@google.com", "status": "active"}
+    ],
+    "services": [
+      {"service": "google-oauth", "account": "tyler@gmail.com", "status": "active"},
+      {"service": "github", "account": "steipete", "status": "active"},
+      {"service": "discord", "account": "echo-bot", "status": "active"},
+      {"service": "twitter", "account": "steipete", "status": "broken", "error": "auth expired"}
+    ]
+  },
+  "capabilities": {
+    "active": 18,
+    "total": 58,
+    "byCategory": {
+      "communication": {
+        "email-read": {"status": "active", "providers": ["gog"]},
+        "email-send": {"status": "active", "providers": ["gog"]},
+        "messaging-read": {"status": "active", "providers": ["eve", "imsg"]},
+        "chat-read": {"status": "ready", "providers": ["discord"]},
+        "chat-send": {"status": "ready", "providers": ["discord"]}
+      }
+    }
+  },
+  "usage": {
+    "last7days": {
+      "gog": 47,
+      "eve": 23,
+      "summarize": 18
+    },
+    "readyButUnused": ["discord", "aix", "spotify"]
+  },
+  "suggestions": [
+    {
+      "priority": 1,
+      "type": "try-unused",
+      "title": "Try Discord!",
+      "description": "You have it configured but never used. Your agent can message you outside Cursor.",
+      "command": "nexus guide use discord"
+    }
+  ],
+  "powerLevel": {
+    "current": 78,
+    "nextUnlock": "Agent Communications",
+    "nextUnlockBoost": 15,
+    "note": "Can exceed 100% with extra integrations"
+  }
+}
+```
+
+---
+
+## `nexus map`
+
+**Purpose**: Show the full capability landscape — everything that's possible.
+
+### Output Structure
+
+```bash
+$ nexus map
+
+╔════════════════════════════════════════════════════════════════╗
+║                     Nexus Capability Map                       ║
+║                     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
+   ✅ messaging-send ─── imsg
+   📥 voice ──────────── (no provider yet)
+   ⭐ chat-read ──────── discord (ready)
+   ⭐ chat-send ──────── discord (ready)
+   ✅ contacts ───────── gog + google-oauth
+
+📱 Social & News (2/5)
+   ✅ social-x ───────── bird + twitter
+   ⬜ social-instagram ─ (no provider)
+   ⬜ social-linkedin ── (no provider)
+   ⭐ rss ────────────── blogwatcher (ready)
+   🔧 news ───────────── brave-search (needs API key)
+
+🔮 Insights (2/4)
+   ✅ relationship-insights ── eve, comms
+   ⭐ session-insights ─────── aix (ready)
+   ⬜ personal-insights ────── comms (not configured)
+   ⬜ communication-insights ─ comms (not configured)
+
+📋 Productivity (4/6)
+   ✅ calendar ──────── gog + google-oauth
+   ✅ tasks ─────────── things-mac
+   ✅ notes ─────────── obsidian
+   ⭐ reminders ─────── apple-reminders (ready)
+   ⬜ pdf-processing ── nano-pdf (not installed)
+   ⬜ collaboration ─── nexus-cloud (not configured)
+
+💾 Data Access (2/2)
+   ✅ local-files ───── filesystem
+   ✅ cloud-storage ─── gog (Drive)
+
+🤖 Automation (3/4)
+   ✅ scheduling ────────── nexus cron (3 jobs)
+   📥 reactive-triggers ─── (not implemented)
+   ✅ gui-automation ────── peekaboo
+   ✅ browser-automation ── computer-use
+
+🧠 AI & LLM (4/8)
+   ✅ anthropic ─────────── anthropic connector
+   ✅ openai ────────────── openai connector
+   ✅ gemini ────────────── gemini connector
+   ⬜ local-llm ─────────── ollama (not installed)
+   ⬜ text-to-speech ────── elevenlabs (not configured)
+   ⭐ speech-to-text ────── openai-whisper (ready)
+   🔧 image-generation ─── openai (needs DALL-E)
+   ✅ summarization ─────── summarize
+
+🏠 Smart Home (0/5)
+   ⬜ smart-lights ─────── openhue (not installed)
+   ⬜ smart-audio ──────── sonoscli (not installed)
+   ⬜ smart-sleep ──────── eightctl (not installed)
+   ⛔ bluetooth ─────────── blucli (darwin only, FDA needed)
+   ⬜ camera-control ───── camsnap (not installed)
+
+🎵 Music (2/4)
+   ⭐ spotify ──────────── spotify-player (ready)
+   ⬜ apple-music ──────── (no provider)
+   ⬜ youtube-music ────── (no provider)
+   ✅ music-detection ──── songsee
+
+🌐 Web (3/5)
+   🔧 web-search ───────── brave-search (needs API key)
+   ⬜ web-scraping ─────── firecrawl (not configured)
+   ✅ url-fetch ─────────── summarize
+   ✅ weather ────────────── weather guide
+   ⬜ place-search ──────── goplaces (not configured)
+
+🎨 Media (3/5)
+   ⬜ video-processing ────── ffmpeg (not installed)
+   ✅ screenshot-annotation ─ sag
+   ⭐ gif-search ───────────── gifgrep (ready, API for full)
+   ✅ transcription ────────── openai-whisper
+   ⭐ document-rendering ──── qmd (ready)
+
+💻 Development (4/9)
+   ✅ version-control ─── github
+   ⬜ vercel ──────────── (no skill)
+   ⬜ cloudflare ─────── (not configured)
+   ⬜ aws ─────────────── (no skill)
+   ⬜ gcloud ──────────── (no skill)
+   ⬜ coding-agents ──── coding-agent (not configured)
+   ⬜ mcp-tools ──────── mcporter (not installed)
+   ✅ git-sync ────────── upstream-sync
+   ✅ terminal-sessions ─ tmux
+
+☁️ Cloud & Sync (1/3)
+   ⬜ cloud-sync ────── nexus-cloud (not configured)
+   ✅ cloud-storage ─── gog (Drive)
+   ✅ rollback ──────── github (via commits)
+
+🔐 Security (2/2)
+   ✅ credential-management ─ 1password, keychain
+   ✅ oauth-management ────── google-oauth
+
+🍔 Commerce (0/1)
+   ⬜ food-ordering ─── ordercli (not configured)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Summary: 18 active │ 8 ready │ 3 needs-setup │ 26 missing │ 1 unavailable │ 1 broken
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Run `nexus quest` for personalized recommendations.
+```
+
+### Flags
+
+```bash
+nexus map [options]
+
+Options:
+  --json              Output as JSON
+  --category <name>   Show only one category
+  --status <status>   Filter by status (active|ready|needs-setup|missing)
+  --compact           One-line-per-capability format
+```
+
+---
+
+## `nexus quest`
+
+**Purpose**: Personalized recommendations for next steps toward full power.
+
+Quests are **hardcoded** based on the optimal activation path from CAPABILITY_TAXONOMY.md. We know what the important unlocks are. New quests can be pushed with updates (including secret quests!).
+
+### Quest Types
+
+1. **Power quests**: Strategic unlocks on the CAPABILITY_TAXONOMY path
+2. **Try quests**: Use a ready-but-unused capability  
+3. **Fix quests**: Repair broken credentials or configs
+4. **Secret quests**: Hidden achievements unlocked by specific combinations
+
+### Default Output (Smart Recommendation)
+
+```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 (eve) and email (gog) connected, plus     │
+│  LLM API keys configured. But your agent can't reach YOU      │
+│  outside of Cursor yet.                                        │
+│                                                                │
+│  Setting up Discord lets your agent:                          │
+│    • Message you from anywhere (phone, desktop, web)          │
+│    • Send proactive notifications                              │
+│    • Work with you asynchronously                             │
+│                                                                │
+│  Time to complete: ~10 minutes                                │
+│  Power boost: +15%                                            │
+│                                                                │
+│  You already have discord credentials configured (echo-bot)   │
+│  but haven't used them yet!                                    │
+│                                                                │
+│  → Ready? Run: nexus guide use discord                        │
+│  → Or try something else: nexus quest --list                  │
+└────────────────────────────────────────────────────────────────┘
+```
+
+### Hardcoded Quest Catalog
+
+These quests follow the CAPABILITY_TAXONOMY activation path:
+
+```
+CORE PATH (Required, in order):
+1. identity-setup        - Bootstrap conversation, create identity files
+2. filesystem-wow        - First wow moment, organize Downloads
+3. credential-manager    - Set up 1Password or use Keychain
+4. cloud-backup         - nexus-cloud for safety before going deep
+
+BREADTH PATH (Parallel, any order):
+5. connect-email        - Set up gog + google-oauth
+6. connect-messages     - Set up eve/imsg for messaging
+7. connect-calendar     - Calendar access (usually comes with email)
+8. enable-llm           - Configure at least one LLM API key
+
+POWER PATH (Requires LLM):
+9. enable-scheduling    - Set up cron jobs
+10. enable-agent-comms  - Discord/Telegram for agent reachability
+11. first-automation    - Create your first automated workflow
+
+SECRET QUESTS (Unlock by discovery):
+- completionist        - Configure 50+ capabilities
+- polyglot             - Use 3+ different LLM providers
+- social-butterfly     - Connect 5+ communication channels
+- home-automation      - Control 3+ smart home devices
+- full-stack           - Dev capabilities (GitHub + Vercel + Cloudflare)
+```
+
+### List Available Quests
+
+```bash
+$ nexus quest --list
+
+Available Quests (sorted by impact):
+
+🏆 POWER PATH
+   1. Enable Agent Communications [+15%] ← RECOMMENDED
+      You're 1 step away from texting your agent!
+      → nexus quest --start enable-agent-comms
+   
+   2. Set up Cloud Backup [+10%]
+      Backup your workspace before going deeper.
+      → nexus quest --start cloud-backup
+
+⭐ TRY SOMETHING NEW  
+   3. Use Discord (configured but unused)
+      Your discord credentials are ready to go.
+      → nexus guide use discord
+   
+   4. Try session insights with aix
+      See insights from your Cursor sessions.
+      → nexus skill run aix
+
+🔧 FIX ISSUES
+   5. Repair twitter credentials
+      Auth expired 3 days ago.
+      → nexus credential verify twitter
+
+🔓 UNLOCK MORE POWER
+   6. Configure Brave Search [+5%]
+      Enable web search capability.
+      → nexus connector setup brave-search
+   
+   7. Set up Spotify [+3%]
+      Control your music playback.
+      → nexus connector setup spotify
+
+🎭 SECRET QUESTS
+   You've discovered 1/5 secret quests!
+   → nexus quest --secrets
+```
+
+### Quest Progress
+
+```bash
+$ nexus quest --progress
+
+╔════════════════════════════════════════════════════════════════╗
+║                    Quest Progress                              ║
+╚════════════════════════════════════════════════════════════════╝
+
+CORE PATH (4/4 complete) ✅
+  ✅ identity-setup
+  ✅ filesystem-wow  
+  ✅ credential-manager
+  ✅ cloud-backup
+
+BREADTH PATH (3/4 complete)
+  ✅ connect-email
+  ✅ connect-messages
+  ✅ connect-calendar
+  ⬜ enable-llm (skip? you have 3 providers!)
+
+POWER PATH (1/3 complete)
+  ✅ enable-scheduling
+  ⬜ enable-agent-comms ← YOU ARE HERE
+  ⬜ first-automation
+
+SECRET QUESTS: 1/5 discovered
+  ✅ polyglot (3 LLM providers)
+  🔒 completionist
+  🔒 social-butterfly
+  🔒 home-automation
+  🔒 full-stack
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Overall: 78% → Complete enable-agent-comms for 93%!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Flags
+
+```bash
+nexus quest [options]
+
+Options:
+  --list              Show all available quests
+  --start <quest>     Start a specific quest (guided walkthrough)
+  --progress          Show quest completion progress
+  --secrets           Show discovered secret quests
+  --power-path        Show optimal path to max power
+  --quick-wins        Show easy 5-minute wins only
+  --json              Output as JSON
+```
+
+---
+
+## State Detection
+
+All commands dynamically detect state from existing files:
+
+### Identity Detection
+
+```typescript
+// Check if identity exists
+const userProfile = await exists('state/user/identity/PROFILE.md');
+const agentIdentity = await glob('state/agents/*/identity/IDENTITY.md');
+
+// Parse user name from PROFILE.md frontmatter
+const userName = parseYamlFrontmatter(userProfile).name;
+
+// Parse agent name from folder path
+const agentName = agentIdentity[0].split('/')[2]; // state/agents/{name}/identity
+```
+
+### Credential Detection
+
+```typescript
+// Walk state/credentials/ tree
+const credentials = await walkDir('state/credentials/');
+
+// For each service/account/auth, check if it's been flagged as broken
+for (const cred of credentials) {
+  // Credentials are marked broken when usage fails
+  // We don't proactively verify (expensive), just track failures
+  cred.status = cred.flaggedBroken ? 'broken' : 'active';
+}
+```
+
+### Capability Detection
+
+```typescript
+// For each capability, check providers
+for (const cap of CAPABILITIES) {
+  const providers = cap.providers;
+  
+  for (const provider of providers) {
+    if (provider.type === 'tool') {
+      // Check if binary exists
+      cap.status = await hasBinary(provider.binary) ? 'ready' : 'missing';
+    }
+    if (provider.type === 'connector') {
+      // Check if credentials exist and aren't broken
+      const cred = await hasCredential(provider.service);
+      if (!cred) cap.status = 'missing';
+      else if (cred.flaggedBroken) cap.status = 'broken';
+      else if (cred.neverUsed) cap.status = 'ready';
+      else cap.status = 'active';
+    }
+  }
+}
+```
+
+### Usage Detection
+
+```typescript
+// Read usage logs from state/nexus/skills/
+const usageLogs = await glob('state/nexus/skills/*/usage.log');
+
+for (const log of usageLogs) {
+  const entries = parseJsonLines(log);
+  const lastUsed = entries[entries.length - 1]?.timestamp;
+  const totalUses = entries.length;
+}
+```
+
+---
+
+## Bootstrap Flow
+
+### What happens during `nexus init`:
+1. Create folder structure
+2. Create empty `AGENTS.md` at root
+3. Create `.cursor/rules` pointing to nexus
+4. Create `state/nexus/workspace.json` with OS/platform info
+5. **Does NOT create identity files** (that's the bootstrap conversation)
+
+### What happens during bootstrap conversation:
+1. Agent detects missing identity via `nexus status`
+2. Receives bootstrap prompt (targeted at agents)
+3. Has conversation with user
+4. Creates:
+   - `state/user/identity/PROFILE.md`
+   - `state/agents/{name}/identity/IDENTITY.md`
+   - `state/agents/{name}/identity/SOUL.md`
+   - `state/agents/{name}/identity/MEMORY.md`
+5. Runs `nexus status` to show what's unlocked
+6. Suggests filesystem organization as first wow moment
+
+### First quests after bootstrap:
+1. **Filesystem organization** (immediate wow, no setup)
+2. **Connect first data source** (eve for macOS, gog for all)
+3. **Set up credential manager** (makes everything easier)
+4. **Enable LLM** (API keys for agent independence)
+5. **Agent communications** (the magic moment — text your agent!)
+
+---
+
+## Integration with AGENTS.md
+
+The root `AGENTS.md` should instruct agents:
+
+```markdown
+## Initialization
+
+Before doing anything else:
+1. Run `nexus status` to understand current state
+2. Read your identity at `state/agents/{name}/identity/`
+3. Read your memory at `state/agents/{name}/identity/MEMORY.md`
+4. Read user profile at `state/user/identity/PROFILE.md`
+5. Check available capabilities
+
+## Ongoing
+
+- Run `nexus status` at the start of each session
+- Check `nexus quest` periodically for growth opportunities
+- Use `nexus skill run <name>` for all skill invocations
+- Flag broken credentials with `nexus credential flag <service>`
+```
+
+---
+
+## Power Level Calculation
+
+Power level is based on CAPABILITY_TAXONOMY activation path:
+
+```typescript
+const POWER_WEIGHTS = {
+  // Core path (40%)
+  'identity-setup': 10,
+  'filesystem-wow': 5,
+  'credential-manager': 15,
+  'cloud-backup': 10,
+  
+  // Breadth path (30%)
+  'connect-email': 10,
+  'connect-messages': 10,
+  'connect-calendar': 5,
+  'enable-llm': 5,
+  
+  // Power path (30%)
+  'enable-scheduling': 10,
+  'enable-agent-comms': 15,
+  'first-automation': 5,
+};
+
+// Base is 100%, but extra integrations can push higher
+// Someone with 50+ capabilities might be at 120%+
+const BONUS_PER_EXTRA_CAPABILITY = 2;
+```
+
+Power level **can exceed 100%** — it's fun to compete on how many capabilities you've set up!
+
+---
+
+## Summary
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `nexus status` | State snapshot | Agent startup, orientation |
+| `nexus map` | Full capability view | Exploring what's possible |
+| `nexus quest` | Recommendations | Growing capabilities |
+| `nexus init` | Create workspace | First time only |
+
+The "onboarding" is really just:
+- Bootstrap prompt (if no identity)
+- `nexus status` (show current state to agent)
+- `nexus quest` (recommend next step)
+
+Dynamic, conversational, ongoing — not a one-time script.
+
+---
+
+## Next: Quest Design Session
+
+We should dedicate time to fully designing each quest:
+- What triggers it
+- What steps it involves
+- What counts as completion
+- What the reward/power boost is
+- Easter eggs and secret quests
+
+This will make the onboarding feel like a game, not a chore.