Smoke test: pr-triage-b2 combined branch (8/9 PASS)

.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

.gitignore

@@ -31,3 +31,7 @@ Thumbs.db
 # multiclaude runtime (but allow config files)
 .multiclaude/*
 !.multiclaude/*.md
+.claude/
+.go-cache/
+.claude/
+.go-cache/

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:

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?