dlorenc · whitmo · Jan 24, 2026 · Jan 24, 2026 · Jan 24, 2026 · Jan 24, 2026
diff --git a/.github/workflows/verify-docs.yml b/.github/workflows/verify-docs.yml
@@ -0,0 +1,23 @@
+name: Verify Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  verify-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.25'
+          cache: true
+
+      - name: Verify extension docs are in sync with code
+        run: go run ./cmd/verify-docs
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -50,8 +50,8 @@ MULTICLAUDE_TEST_MODE=1 go test ./test/...  # Skip Claude startup
 │                          Daemon (internal/daemon)                │
 │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
 │  │ Health   │  │ Message  │  │ Wake/    │  │ Socket   │        │
-│  │ Check    │  │ Router   │  │ Nudge    │  │ Server   │        │
-│  │ (2min)   │  │ (2min)   │  │ (2min)   │  │          │        │
+│  │ Check    │  │ (2min)   │  │ (2min)   │  │ Server   │        │
+│  │ (2min)   │  │ Router   │  │ Nudge    │  │          │        │
 │  └──────────┘  └──────────┘  └──────────┘  └──────────┘        │
 └────────────────────────────────┬────────────────────────────────┘
                                  │
@@ -212,6 +212,29 @@ External tools can integrate via:
 
 **Note:** Web UIs, event hooks, and notification systems are explicitly out of scope per ROADMAP.md.
 
+### For LLMs: Keeping Extension Docs Updated
+
+**CRITICAL:** When modifying multiclaude core, keep extension documentation **code-first and drift-free**. Never document an API/command/event that does not exist on `main`. If something is planned, mark it `[PLANNED]` until it ships. Always run `go run ./cmd/verify-docs` on doc or API changes.
+
+1. **State Schema Changes** (`internal/state/state.go`)
+   - Update: [`docs/extending/STATE_FILE_INTEGRATION.md`](docs/extending/STATE_FILE_INTEGRATION.md)
+   - Update schema reference section
+   - Update all code examples showing state structure
+   - Run: `go run ./cmd/verify-docs`
+
+2. **Socket Command Changes** (`internal/daemon/daemon.go`)
+   - Update: [`docs/extending/SOCKET_API.md`](docs/extending/SOCKET_API.md)
+   - Add/update command reference entries
+   - Add code examples for new commands
+   - Update client library examples if needed
+
+**Pattern:** After any internal/* or pkg/* changes, search extension docs for outdated references:
+```bash
+# Find docs that might need updating
+grep -r "internal/state" docs/extending/
+grep -r "socket.Request" docs/extending/
+```
+
 ## Contributing Checklist
 
 When modifying agent behavior:

diff --git a/docs/CLI_RESTRUCTURE_PROPOSAL.md b/docs/CLI_RESTRUCTURE_PROPOSAL.md
@@ -0,0 +1,147 @@
+# CLI Restructure Proposal
+
+> **Status**: Partially implemented (updated 2026-03-01)
+> **Author**: cool-wolf worker
+> **Aligns with**: ROADMAP P2 - Better onboarding
+
+## Implementation Status
+
+| Item | Status | PR |
+|------|--------|-----|
+| Add `Hidden` field to Command struct | DONE | #337 |
+| Mark aliases as hidden from `--help` | DONE | #337 |
+| Restructure help output with categories | DONE | #337 |
+| Add `Category` field to Command struct | DONE | #337 |
+| Add `guide` command | NOT STARTED | |
+| Rename `agents` → `templates` | NOT STARTED | |
+| Add deprecation warnings to aliases | NOT STARTED | |
+| v2.0 alias removal plan | NOT STARTED | |
+| Merge `worker`/`workspace` under `agent` | NOT STARTED | |
+| Update COMMANDS.md | NOT STARTED | |
+| Update embedded prompts | NOT STARTED | |
+
+---
+
+## Problem Statement
+
+The multiclaude CLI has grown organically and now suffers from:
+
+1. **Too many top-level commands** (28 entries)
+2. **Redundant aliases** that pollute `--help` output
+3. **Inconsistent naming** (`agent`/`agents`, `work`/`worker`)
+4. **Unclear mental model** - is the tool repo-centric or agent-centric?
+
+### Evidence: Current `--help` Output
+
+```
+Subcommands:
+  repair          ← maintenance
+  claude          ← agent context
+  logs            ← agent ops
+  status          ← system overview
+  daemon          ← daemon management
+  worker          ← agent creation
+  work            ← ALIAS for worker
+  agent           ← agent ops
+  attach          ← ALIAS for agent attach
+  review          ← agent creation
+  config          ← repo config
+  start           ← ALIAS for daemon start
+  list            ← ALIAS for repo list
+  workspace       ← agent creation
+  refresh         ← agent ops
+  docs            ← meta
+  diagnostics     ← meta
+  version         ← meta
+  agents          ← agent definitions (confusing: singular vs plural)
+  init            ← ALIAS for repo init
+  cleanup         ← maintenance
+  bug             ← meta
+  stop-all        ← daemon control
+  repo            ← repo management
+  history         ← ALIAS for repo history
+  message         ← agent comms
+```
+
+A new user sees 28 commands and has no idea where to start.
+
+## Proposed Solutions
+
+### Option D: Hybrid (Recommended)
+
+**Phase 1 (Partially Done)**:
+1. ~~Hide aliases from `--help` (still work)~~ DONE
+2. ~~Group help output by category~~ DONE
+3. Add `multiclaude guide` command with interactive walkthrough
+4. Rename `agents` → `templates` (avoids `agent`/`agents` confusion)
+
+**Phase 2 (v2.0)**:
+1. Remove deprecated aliases
+2. Optionally merge `worker`/`workspace` under `agent`
+
+## Remaining Actions
+
+### 1. Add `guide` Command
+
+```bash
+$ multiclaude guide
+
+Welcome to multiclaude! Here's how to get started:
+
+1. INITIALIZE A REPO
+   multiclaude repo init https://github.com/you/repo
+
+2. START THE DAEMON
+   multiclaude start
+
+3. CREATE A WORKER
+   multiclaude worker "Fix the login bug"
+
+4. WATCH IT WORK
+   multiclaude agent attach <worker-name>
+
+Need more? See: multiclaude docs
+```
+
+### 2. Rename `agents` → `templates`
+
+The current naming creates confusion:
+- `agent attach` - operate on running agent
+- `agents list` - list agent definitions (templates)
+
+Rename to:
+- `templates list` - list agent templates
+- `templates spawn` - spawn from template
+- `templates reset` - reset to defaults
+
+### 3. Add Deprecation Warnings
+
+Aliases should print notices pointing to canonical commands:
+
+| Current | Replacement |
+|---------|-------------|
+| `multiclaude init` | `multiclaude repo init` |
+| `multiclaude list` | `multiclaude repo list` |
+| `multiclaude start` | `multiclaude daemon start` |
+| `multiclaude attach` | `multiclaude agent attach` |
+| `multiclaude work` | `multiclaude worker` |
+| `multiclaude history` | `multiclaude repo history` |
+
+### 4. Consider Merging `worker`/`workspace` under `agent`
+
+```
+multiclaude agent create "task"         ← replaces worker create
+multiclaude agent create --workspace    ← replaces workspace add
+multiclaude agent list                  ← unified listing
+```
+
+## Questions for Review
+
+1. **Keep `start` alias?** It's the most commonly used shortcut.
+2. **Merge worker/workspace?** They're conceptually similar (agent instances).
+3. **Add `quickstart` or `guide`?** Which name is clearer?
+4. **Timeline for v2.0?** When do we remove deprecated aliases?
+
+---
+
+*Originally generated by cool-wolf worker. Updated with implementation status.*
diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md
@@ -1,13 +1,22 @@
 # Commands Reference
 
-Everything you can tell multiclaude to do.
+Everything you can tell multiclaude to do. Run `multiclaude` with no arguments for a quick reference.
+
+## Quick Start
+
+```bash
+multiclaude repo init <github-url>    # Track a repository
+multiclaude start                     # Start the daemon (alias for daemon start)
+multiclaude worker "task"             # Create a worker for a task
+multiclaude status                    # See what's running
+```
 
 ## Daemon
 
 The daemon is the brain. Start it, and agents come alive.
 
 ```bash
-multiclaude start              # Wake up
+multiclaude daemon start       # Wake up
 multiclaude daemon stop        # Go to sleep
 multiclaude daemon status      # You alive?
 multiclaude daemon logs -f     # What are you thinking?

diff --git a/docs/extending/SOCKET_API.md b/docs/extending/SOCKET_API.md
@@ -13,6 +13,7 @@ list_agents
 complete_agent
 restart_agent
 trigger_cleanup
+trigger_refresh
 repair_state
 get_repo_config
 update_repo_config
@@ -49,6 +50,7 @@ Each command below matches a `case` in `handleRequest`.
 | `complete_agent` | Mark agent ready for cleanup | `repo`, `name`, `summary`, `failure_reason` |
 | `restart_agent` | Restart a persistent agent | `repo`, `name` |
 | `trigger_cleanup` | Force cleanup cycle | none |
+| `trigger_refresh` | Force worktree refresh cycle | none |
 | `repair_state` | Run state repair routine | none |
 | `get_repo_config` | Get merge-queue / pr-shepherd config | `repo` |
 | `update_repo_config` | Update repo config | `repo`, `config` (JSON object) |
@@ -644,6 +646,27 @@ class MulticlaudeClient {
 }
 ```
 
+#### trigger_refresh
+
+**Description:** Trigger immediate worktree refresh for all agents (syncs with main branch)
+
+**Request:**
+```json
+{
+  "command": "trigger_refresh"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": "Worktree refresh triggered"
+}
+```
+
+**Note:** Refresh runs asynchronously in the background.
+
 #### repair_state
 
 **Description:** Repair inconsistent state (equivalent to `multiclaude repair`)