compound-agent 1.3.0 → 1.3.2

package/dist/cli.js

@@ -2,14 +2,14 @@
 import { Command } from 'commander';
 import { getLlama, resolveModelFile } from 'node-llama-cpp';
 import { mkdirSync, writeFileSync, statSync, unlinkSync, existsSync, readFileSync, copyFileSync, chmodSync, readdirSync } from 'fs';
-import { homedir } from 'os';
+import { homedir, tmpdir } from 'os';
 import path, { join, dirname, resolve, relative } from 'path';
 import * as fs from 'fs/promises';
 import { readFile, mkdir, appendFile, writeFile, chmod, rm, rename, readdir } from 'fs/promises';
 import { createHash } from 'crypto';
 import { z } from 'zod';
 import { createRequire } from 'module';
-import { execSync, execFileSync } from 'child_process';
+import { execSync, execFileSync, spawn } from 'child_process';
 import chalk from 'chalk';
 
 // src/cli-utils.ts
@@ -1135,6 +1135,171 @@ function registerCompoundCommands(program2) {
 var _require = createRequire(import.meta.url);
 var _pkg = _require("../package.json");
 var VERSION = _pkg.version;
+var SAMPLE_RATE = 22050;
+var BITS = 16;
+var MAX_AMP = 24576;
+var NOTE = {
+  C3: 131,
+  E3: 165,
+  G3: 196,
+  C4: 262,
+  E4: 330,
+  G4: 392,
+  C5: 523,
+  E5: 659,
+  G5: 784,
+  C6: 1047
+};
+function envelope(i, total, attack, release) {
+  if (i < attack) return i / attack;
+  if (i > total - release) return (total - i) / release;
+  return 1;
+}
+function tone(freq, durationMs, amp = 1) {
+  const samples = Math.floor(SAMPLE_RATE * durationMs / 1e3);
+  const attack = Math.min(Math.floor(samples * 0.05), 200);
+  const release = Math.min(Math.floor(samples * 0.15), 400);
+  const out2 = [];
+  for (let i = 0; i < samples; i++) {
+    const env = envelope(i, samples, attack, release);
+    out2.push(Math.sin(2 * Math.PI * freq * i / SAMPLE_RATE) * env * amp);
+  }
+  return out2;
+}
+function chord(freqs, durationMs, amp = 1) {
+  const tones = freqs.map((f) => tone(f, durationMs, 1));
+  const len = tones[0].length;
+  const out2 = [];
+  const scale = amp / freqs.length;
+  for (let i = 0; i < len; i++) {
+    let sum = 0;
+    for (const t of tones) sum += t[i];
+    out2.push(sum * scale);
+  }
+  return out2;
+}
+function silence(durationMs) {
+  return new Array(Math.floor(SAMPLE_RATE * durationMs / 1e3)).fill(0);
+}
+function composeMelody() {
+  const samples = [];
+  samples.push(...tone(NOTE.C3, 250, 0.3));
+  samples.push(...silence(150));
+  samples.push(...tone(NOTE.C3, 250, 0.35));
+  samples.push(...silence(100));
+  samples.push(...tone(NOTE.E3, 200, 0.3));
+  samples.push(...silence(80));
+  samples.push(...tone(NOTE.C4, 140, 0.45));
+  samples.push(...silence(30));
+  samples.push(...tone(NOTE.E4, 140, 0.5));
+  samples.push(...silence(30));
+  samples.push(...tone(NOTE.G4, 140, 0.5));
+  samples.push(...silence(30));
+  samples.push(...tone(NOTE.C5, 160, 0.55));
+  samples.push(...silence(30));
+  samples.push(...tone(NOTE.E5, 160, 0.55));
+  samples.push(...silence(30));
+  samples.push(...tone(NOTE.G5, 180, 0.6));
+  samples.push(...silence(60));
+  samples.push(...tone(NOTE.C4, 100, 0.4));
+  samples.push(...tone(NOTE.E4, 100, 0.45));
+  samples.push(...tone(NOTE.G4, 100, 0.45));
+  samples.push(...tone(NOTE.C5, 120, 0.5));
+  samples.push(...tone(NOTE.E5, 120, 0.55));
+  samples.push(...tone(NOTE.G5, 140, 0.6));
+  samples.push(...silence(60));
+  samples.push(...tone(NOTE.C6, 80, 0.3));
+  samples.push(...silence(40));
+  samples.push(...tone(NOTE.G5, 80, 0.35));
+  samples.push(...silence(40));
+  samples.push(...tone(NOTE.C6, 80, 0.3));
+  samples.push(...silence(40));
+  samples.push(...tone(NOTE.E5, 100, 0.35));
+  samples.push(...silence(60));
+  samples.push(...chord([NOTE.C4, NOTE.E4, NOTE.G4], 600, 0.7));
+  samples.push(...chord([NOTE.C4, NOTE.E4, NOTE.G4, NOTE.C5], 500, 0.6));
+  samples.push(...chord([NOTE.C3, NOTE.G3, NOTE.C4], 1200, 0.35));
+  return samples;
+}
+function encodeWav(samples) {
+  const dataSize = samples.length * (BITS / 8);
+  const fileSize = 44 + dataSize;
+  const buf = Buffer.alloc(fileSize);
+  buf.write("RIFF", 0);
+  buf.writeUInt32LE(fileSize - 8, 4);
+  buf.write("WAVE", 8);
+  buf.write("fmt ", 12);
+  buf.writeUInt32LE(16, 16);
+  buf.writeUInt16LE(1, 20);
+  buf.writeUInt16LE(1, 22);
+  buf.writeUInt32LE(SAMPLE_RATE, 24);
+  buf.writeUInt32LE(SAMPLE_RATE * BITS / 8, 28);
+  buf.writeUInt16LE(BITS / 8, 32);
+  buf.writeUInt16LE(BITS, 34);
+  buf.write("data", 36);
+  buf.writeUInt32LE(dataSize, 40);
+  let offset = 44;
+  for (const s of samples) {
+    const clamped = Math.max(-1, Math.min(1, s));
+    buf.writeInt16LE(Math.round(clamped * MAX_AMP), offset);
+    offset += 2;
+  }
+  return buf;
+}
+function spawnPlayer(filePath) {
+  try {
+    switch (process.platform) {
+      case "darwin":
+        return spawn("afplay", [filePath], { stdio: "ignore", detached: true });
+      case "linux":
+        return spawn("aplay", ["-q", filePath], { stdio: "ignore", detached: true });
+      case "win32":
+        return spawn("powershell", [
+          "-c",
+          `(New-Object Media.SoundPlayer '${filePath}').PlaySync()`
+        ], { stdio: "ignore", detached: true });
+      default:
+        return null;
+    }
+  } catch {
+    return null;
+  }
+}
+function playBannerAudio() {
+  try {
+    const wav = encodeWav(composeMelody());
+    const tmpPath = join(tmpdir(), `ca-banner-${process.pid}.wav`);
+    writeFileSync(tmpPath, wav);
+    const proc = spawnPlayer(tmpPath);
+    if (!proc) {
+      try {
+        unlinkSync(tmpPath);
+      } catch {
+      }
+      return null;
+    }
+    proc.unref();
+    const cleanup2 = () => {
+      try {
+        proc.kill();
+      } catch {
+      }
+      try {
+        unlinkSync(tmpPath);
+      } catch {
+      }
+    };
+    proc.on("exit", () => {
+      try {
+        unlinkSync(tmpPath);
+      } catch {
+      }
+    });
+    return { stop: cleanup2 };
+  } catch {
+    return null;
+  }
+}
 
 // src/setup/banner.ts
 var W = 62;
@@ -1316,6 +1481,7 @@ async function playInstallBanner() {
   const ps = [];
   const write = (s) => process.stdout.write(s);
   write("\x1B[?25l\x1B[2J\x1B[H");
+  const audio = playBannerAudio();
   const restoreCursor = () => process.stdout.write("\x1B[?25h\x1B[0m");
   process.on("exit", restoreCursor);
   try {
@@ -1327,7 +1493,7 @@ async function playInstallBanner() {
       put(cvs, nx(CENTER), ny(CENTER), seedCh[f % 4], seedCo[f % 4]);
       write(flush(cvs));
       write(`
-  ${CO.DIM}Seed detected...${CO.VOID}
+  ${CO.DIM}Seed detected...\x1B[K${CO.VOID}
 `);
       await sleep(60);
     }
@@ -1374,7 +1540,7 @@ async function playInstallBanner() {
       let active = 0;
       for (let i = 0; i < nc; i++) if (isGrown[i]) active++;
       write(`
-  \x1B[0;35mNodes \x1B[1;36m${active}\x1B[0;35m/${nc}\x1B[0m  \x1B[0;90mGrowing neural tendrils...\x1B[0m
+  \x1B[0;35mNodes \x1B[1;36m${active}\x1B[0;35m/${nc}\x1B[0m  \x1B[0;90mGrowing neural tendrils...\x1B[K\x1B[0m
 `);
       await sleep(40);
     }
@@ -1397,7 +1563,7 @@ async function playInstallBanner() {
       renderParticles(cvs, ps, f);
       write(flush(cvs));
       write(`
-  ${CO.SETTLED}Crystallizing pathways...${CO.VOID}
+  ${CO.SETTLED}Crystallizing pathways...\x1B[K${CO.VOID}
 `);
       await sleep(60);
     }
@@ -1473,6 +1639,7 @@ async function playInstallBanner() {
       await sleep(120);
     }
   } finally {
+    audio?.stop();
     process.removeListener("exit", restoreCursor);
     restoreCursor();
     write("\n");
@@ -1489,6 +1656,30 @@ function checkBeadsAvailable() {
     };
   }
 }
+function checkBeadsInitialized(repoRoot) {
+  return existsSync(join(repoRoot, ".beads"));
+}
+function checkBeadsHealthy(repoRoot) {
+  try {
+    execSync("bd doctor", { cwd: repoRoot, shell: "/bin/sh", stdio: "pipe", encoding: "utf-8" });
+    return { healthy: true };
+  } catch (e) {
+    const msg = e instanceof Error && "stderr" in e ? String(e.stderr).trim() : "bd doctor failed";
+    return { healthy: false, message: msg };
+  }
+}
+function runFullBeadsCheck(repoRoot) {
+  const cli = checkBeadsAvailable();
+  if (!cli.available) {
+    return { cliAvailable: false, initialized: false, healthy: false, healthMessage: cli.message };
+  }
+  const initialized = checkBeadsInitialized(repoRoot);
+  if (!initialized) {
+    return { cliAvailable: true, initialized: false, healthy: false };
+  }
+  const health = checkBeadsHealthy(repoRoot);
+  return { cliAvailable: true, initialized: true, healthy: health.healthy, healthMessage: health.message };
+}
 
 // src/memory/capture/quality.ts
 var DEFAULT_SIMILARITY_THRESHOLD = 0.8;
@@ -2562,6 +2753,22 @@ function printPnpmConfigStatus(result) {
     console.log(`  pnpm config: Added onlyBuiltDependencies [${result.added.join(", ")}]`);
   }
 }
+function printBeadsFullStatus(check) {
+  console.log(`  Beads CLI:          ${check.cliAvailable ? "OK" : "not found"}`);
+  if (check.cliAvailable) {
+    console.log(`  Beads repo:         ${check.initialized ? "OK" : "not initialized (run: bd init)"}`);
+    if (check.initialized) {
+      console.log(`  Beads health:       ${check.healthy ? "OK" : `issues found${check.healthMessage ? ` \u2014 ${check.healthMessage}` : ""}`}`);
+    }
+  }
+}
+function printScopeStatus(scope) {
+  if (scope.isUserScope) {
+    console.log("  Scope:              user-scope (reduced compounding value)");
+  } else {
+    console.log("  Scope:              OK (repository scope)");
+  }
+}
 async function runStatus(repoRoot) {
   const agentsDir = join(repoRoot, ".claude", "agents", "compound");
   const commandsDir = join(repoRoot, ".claude", "commands", "compound");
@@ -2580,12 +2787,10 @@ async function runStatus(repoRoot) {
   } catch {
   }
   console.log(`  Hooks:              ${hooksInstalled ? "installed" : "not installed"}`);
-  const beads = checkBeadsAvailable();
-  console.log(`  Beads CLI:          ${beads.available ? "available" : "not found"}`);
+  const fullBeads = runFullBeadsCheck(repoRoot);
+  printBeadsFullStatus(fullBeads);
   const scope = checkUserScope(repoRoot);
-  if (scope.isUserScope) {
-    console.log("  Scope:              user-scope (reduced compounding value)");
-  }
+  printScopeStatus(scope);
 }
 var REQUIRED_PATTERNS = ["node_modules/", ".claude/.cache/"];
 var SECTION_COMMENT = "# compound-agent";
@@ -4160,21 +4365,21 @@ npx ca prime
 
 // src/setup/templates/docs.ts
 var DOC_TEMPLATES = {
-  "HOW_TO_COMPOUND.md": `---
+  "README.md": `---
 version: "{{VERSION}}"
 last-updated: "{{DATE}}"
-summary: "Usage guide for compound-agent CLI, skills, and workflows"
+summary: "Overview and getting started guide for compound-agent"
 ---
 
-# How to Compound
+# Compound Agent
 
-A usage guide for humans and AI agents working with compound-agent -- the learning system that helps Claude Code avoid repeating mistakes across sessions.
+A learning system for Claude Code that captures, indexes, and retrieves lessons learned during development sessions -- so the same mistakes are not repeated.
 
 ---
 
-## 1. What is compound-agent
+## What is compound-agent?
 
-Compound-agent is a TypeScript CLI plugin for Claude Code that captures, indexes, and retrieves lessons learned during development sessions. When Claude makes a mistake and gets corrected, or discovers a useful pattern, that knowledge is stored as a **memory item** in \`.claude/lessons/index.jsonl\`. Future sessions search this memory before planning and implementing, so the same mistakes are not repeated.
+Compound-agent is a TypeScript CLI plugin for Claude Code. When Claude makes a mistake and gets corrected, or discovers a useful pattern, that knowledge is stored as a **memory item** in \`.claude/lessons/index.jsonl\`. Future sessions search this memory before planning and implementing.
 
 The system uses:
 
@@ -4183,17 +4388,21 @@ The system uses:
 - **Semantic embeddings** (EmbeddingGemma-300M via node-llama-cpp) for vector similarity search
 - **Claude Code hooks** to inject memory at session start, before compaction, and on tool failures
 
-Memory items have four types: \`lesson\`, \`solution\`, \`pattern\`, and \`preference\`. Each has a trigger (what happened), an insight (what to do differently), tags, severity, and optional citations linking back to source code.
+Memory items have four types: \`lesson\`, \`solution\`, \`pattern\`, and \`preference\`. Each has a trigger, an insight, tags, severity, and optional citations.
 
 ---
 
-## 2. Installation
-
-### Quick start
+## Quick start
 
 \`\`\`bash
-# In your project root:
+# Initialize in your project:
 npx ca init
+
+# Full setup (includes embedding model download):
+npx ca setup
+
+# Verify installation:
+npx ca doctor
 \`\`\`
 
 ### What \`init\` does
@@ -4202,31 +4411,16 @@ npx ca init
 2. Updates \`AGENTS.md\` with a compound-agent section
 3. Adds a reference to \`.claude/CLAUDE.md\`
 4. Creates \`.claude/plugin.json\` manifest
-5. Installs agent templates to \`.claude/agents/compound/\`
-6. Installs workflow slash commands to \`.claude/commands/compound/\`
-7. Installs phase skills to \`.claude/skills/compound/\`
-8. Installs agent role skills to \`.claude/skills/compound/agents/\`
-9. Installs a git pre-commit hook (lesson capture reminder)
-10. Installs Claude Code hooks (SessionStart, PreCompact, UserPromptSubmit, PostToolUseFailure, PostToolUse)
-11. For pnpm projects: auto-configures \`onlyBuiltDependencies\` for native addons
-
-### Full setup (with embedding model)
+5. Installs agent templates, workflow commands, phase skills, and agent role skills
+6. Installs a git pre-commit hook (lesson capture reminder)
+7. Installs Claude Code hooks (SessionStart, PreCompact, UserPromptSubmit, PostToolUseFailure, PostToolUse)
+8. For pnpm projects: auto-configures \`onlyBuiltDependencies\` for native addons
 
-\`\`\`bash
-npx ca setup
-\`\`\`
+\`setup\` does everything \`init\` does, plus downloads the EmbeddingGemma-300M model (~278MB). Use \`--skip-model\` to skip the download.
 
-\`setup\` does everything \`init\` does, plus downloads the EmbeddingGemma-300M model (~278MB) for semantic search. Use \`--skip-model\` to skip the download.
-
-### Verify installation
-
-\`\`\`bash
-npx ca doctor
-\`\`\`
-
-This checks for \`.claude/\` directory, lessons index, embedding model, Claude hooks, and beads (\`bd\`) availability.
+---
 
-### Directory structure after install
+## Directory structure
 
 \`\`\`
 .claude/
@@ -4245,29 +4439,57 @@ This checks for \`.claude/\` directory, lessons index, embedding model, Claude h
 
 ---
 
-## 3. The 5-phase workflow
+## Quick reference
+
+| Task | Command |
+|------|---------|
+| Capture a lesson | \`npx ca learn "insight" --trigger "what happened"\` |
+| Search memory | \`npx ca search "keywords"\` |
+| Check plan against memory | \`npx ca check-plan --plan "description"\` |
+| View stats | \`npx ca stats\` |
+| Run full workflow | \`/compound:lfg <epic-id>\` |
+| Health check | \`npx ca doctor\` |
+
+---
+
+## Further reading
 
-Every feature or epic follows five phases:
+- [WORKFLOW.md](WORKFLOW.md) -- The 5-phase development workflow and LFG orchestrator
+- [CLI_REFERENCE.md](CLI_REFERENCE.md) -- Complete CLI command reference
+- [SKILLS.md](SKILLS.md) -- Phase skills and agent role skills
+- [INTEGRATION.md](INTEGRATION.md) -- Memory system, hooks, beads, and agent guidance
+`,
+  "WORKFLOW.md": `---
+version: "{{VERSION}}"
+last-updated: "{{DATE}}"
+summary: "The 5-phase compound-agent workflow and LFG orchestrator"
+---
+
+# Workflow
+
+Every feature or epic follows five phases. The \`/compound:lfg\` skill chains them with enforcement gates.
 
-### Phase 1: Brainstorm
+---
+
+## Phase 1: Brainstorm
 
-Explore the problem space before committing to a solution. Produce a structured brainstorm document with decisions, open questions, and a beads epic.
+Explore the problem space before committing to a solution.
 
 - Ask "why" before "how"
 - Search memory for similar past features
 - Generate multiple approaches, then converge
 - Create a beads epic: \`bd create --title="..." --type=epic\`
 
-### Phase 2: Plan
+## Phase 2: Plan
 
-Decompose work into small, testable tasks with dependencies and acceptance criteria.
+Decompose work into small, testable tasks with dependencies.
 
 - Review brainstorm output
 - Create beads tasks: \`bd create --title="..." --type=task\`
 - Create Review and Compound blocking tasks (these survive compaction)
 - Run \`npx ca worktree wire-deps <epic-id>\` if using worktrees
 
-### Phase 3: Work
+## Phase 3: Work
 
 Execute implementation through agent teams using TDD.
 
@@ -4276,7 +4498,7 @@ Execute implementation through agent teams using TDD.
 - Commit incrementally as tests pass
 - Run \`/implementation-reviewer\` before closing tasks
 
-### Phase 4: Review
+## Phase 4: Review
 
 Multi-agent code review with severity classification.
 
@@ -4285,7 +4507,7 @@ Multi-agent code review with severity classification.
 - Classify findings as P1/P2/P3
 - Fix all P1 findings before proceeding
 
-### Phase 5: Compound
+## Phase 5: Compound
 
 Extract and store lessons learned. This is what makes the system compound.
 
@@ -4296,14 +4518,85 @@ Extract and store lessons learned. This is what makes the system compound.
 
 ---
 
-## 4. CLI reference
+## LFG orchestrator
+
+\`/compound:lfg\` chains all 5 phases with enforcement gates.
+
+### Invocation
+
+\`\`\`
+/compound:lfg <epic-id>
+/compound:lfg <epic-id> from plan
+\`\`\`
+
+### Phase execution protocol
+
+For each phase, LFG:
+
+1. Announces progress: \`[Phase N/5] PHASE_NAME\`
+2. Initializes state: \`npx ca phase-check start <phase>\`
+3. Reads the phase skill file (non-negotiable -- never from memory)
+4. Runs \`npx ca search\` with the current goal
+5. Executes the phase following skill instructions
+6. Updates epic notes: \`bd update <epic-id> --notes="Phase: NAME COMPLETE | Next: NEXT"\`
+7. Verifies the phase gate before proceeding
+
+### Phase gates
+
+| Gate | When | Verification |
+|------|------|-------------|
+| Post-plan | After Plan | \`bd list --status=open\` shows Review + Compound tasks |
+| Gate 3 | After Work | \`bd list --status=in_progress\` returns empty |
+| Gate 4 | After Review | \`/implementation-reviewer\` returned APPROVED |
+| Final | After Compound | \`npx ca verify-gates <epic-id>\` passes, \`pnpm test\` and \`pnpm lint\` pass |
+
+If any gate fails, LFG stops. You must fix the issue before proceeding.
+
+### Resumption
+
+If interrupted, LFG can resume:
+
+1. Run \`bd show <epic-id>\` and read the notes for phase state
+2. Re-invoke with \`from <phase>\` to skip completed phases
+
+### Phase state tracking
+
+LFG persists state in \`.claude/.ca-phase-state.json\`. Useful commands:
+
+\`\`\`bash
+npx ca phase-check status      # See current phase state
+npx ca phase-check clean       # Reset phase state (escape hatch)
+\`\`\`
+
+### Session close
+
+Before saying "done", LFG runs this inviolable checklist:
+
+\`\`\`bash
+git status
+git add <files>
+bd sync
+git commit -m "..."
+bd sync
+git push
+\`\`\`
+`,
+  "CLI_REFERENCE.md": `---
+version: "{{VERSION}}"
+last-updated: "{{DATE}}"
+summary: "Complete CLI command reference for compound-agent"
+---
+
+# CLI Reference
 
 All commands use \`npx ca\` (or \`npx compound-agent\`). Global flags: \`-v, --verbose\` and \`-q, --quiet\`.
 
-### Capture commands
+---
+
+## Capture commands
 
 \`\`\`bash
-# Capture a lesson (primary command for storing knowledge)
+# Capture a lesson (primary command)
 npx ca learn "Always validate epic IDs before shell execution" \\
   --trigger "Shell injection via bd show" \\
   --tags "security,validation" \\
@@ -4311,7 +4604,7 @@ npx ca learn "Always validate epic IDs before shell execution" \\
   --type lesson
 
 # Capture a pattern (requires --pattern-bad and --pattern-good)
-npx ca learn "Use execFileSync instead of execSync for external commands" \\
+npx ca learn "Use execFileSync instead of execSync" \\
   --type pattern \\
   --pattern-bad "execSync(\\\`bd show \\\${id}\\\`)" \\
   --pattern-good "execFileSync('bd', ['show', id])"
@@ -4327,68 +4620,44 @@ npx ca detect --input corrections.json --save --yes
 **Types**: \`lesson\` (default), \`solution\`, \`pattern\`, \`preference\`
 **Severity**: \`high\`, \`medium\`, \`low\`
 
-### Retrieval commands
+## Retrieval commands
 
 \`\`\`bash
-# Keyword search
-npx ca search "sqlite validation"
+npx ca search "sqlite validation"           # Keyword search
 npx ca search "security" --limit 5
-
-# List all memory items
-npx ca list
+npx ca list                                  # List all memory items
 npx ca list --limit 20
-npx ca list --invalidated      # Show only invalidated items
-
-# Semantic search against a plan
+npx ca list --invalidated                    # Show only invalidated items
 npx ca check-plan --plan "Implement git worktree integration"
-echo "Add caching layer" | npx ca check-plan
-
-# Load high-severity lessons for session context
-npx ca load-session
+echo "Add caching layer" | npx ca check-plan # Semantic search against a plan
+npx ca load-session                          # Load high-severity lessons
 npx ca load-session --json
 \`\`\`
 
-### Management commands
+## Management commands
 
 \`\`\`bash
-# View a specific item
-npx ca show <id>
+npx ca show <id>                             # View a specific item
 npx ca show <id> --json
-
-# Update item fields
-npx ca update <id> --insight "Updated insight text"
+npx ca update <id> --insight "Updated text"  # Update item fields
 npx ca update <id> --severity high --tags "security,input-validation"
-
-# Soft delete (creates tombstone)
-npx ca delete <id>
+npx ca delete <id>                           # Soft delete (creates tombstone)
 npx ca delete <id1> <id2> <id3>
-
-# Mark as invalid (excluded from retrieval but preserved)
-npx ca wrong <id> --reason "This advice was incorrect"
-
-# Re-enable an invalidated item
-npx ca validate <id>
-
-# Export as JSON
-npx ca export
+npx ca wrong <id> --reason "Incorrect"       # Mark as invalid
+npx ca validate <id>                         # Re-enable an invalidated item
+npx ca export                                # Export as JSON
 npx ca export --since 2026-01-01 --tags "security"
-
-# Import from JSONL file
-npx ca import lessons-backup.jsonl
-
-# Database maintenance
-npx ca compact                 # Remove tombstones and archive old items
-npx ca compact --dry-run       # Preview without changes
-npx ca compact --force         # Compact even if below threshold
-npx ca rebuild                 # Rebuild SQLite index from JSONL
-npx ca rebuild --force         # Force rebuild even if unchanged
-npx ca stats                   # Show database health and statistics
-
-# Context recovery
-npx ca prime                   # Reload workflow context after compaction
+npx ca import lessons-backup.jsonl           # Import from JSONL file
+npx ca compact                               # Remove tombstones and archive old items
+npx ca compact --dry-run
+npx ca compact --force
+npx ca rebuild                               # Rebuild SQLite index from JSONL
+npx ca rebuild --force
+npx ca stats                                 # Show database health and statistics
+npx ca prime                                 # Reload workflow context after compaction
 \`\`\`
 
-### Setup commands
+## Setup commands
 
 \`\`\`bash
 npx ca init                    # Initialize in current repo
@@ -4396,21 +4665,18 @@ npx ca init --skip-agents      # Skip AGENTS.md and template installation
 npx ca init --skip-hooks       # Skip git hook installation
 npx ca init --skip-claude      # Skip Claude Code hooks
 npx ca init --json             # Output result as JSON
-
 npx ca setup                   # Full setup (init + model download)
 npx ca setup --update          # Regenerate templates (preserves user files)
 npx ca setup --uninstall       # Remove compound-agent integration
 npx ca setup --status          # Show installation status
 npx ca setup --skip-model      # Skip embedding model download
-
 npx ca setup claude            # Install Claude Code hooks only
 npx ca setup claude --status   # Check hook status
-
 npx ca hooks                   # Install git hooks
 npx ca download-model          # Download embedding model (~278MB)
 \`\`\`
 
-### Reviewer commands
+## Reviewer commands
 
 \`\`\`bash
 npx ca reviewer enable gemini  # Enable Gemini as external reviewer
@@ -4419,11 +4685,10 @@ npx ca reviewer disable gemini # Disable a reviewer
 npx ca reviewer list           # List enabled reviewers
 \`\`\`
 
-### Loop command
+## Loop command
 
 \`\`\`bash
-# Generate an infinity loop script for autonomous epic processing
-npx ca loop
+npx ca loop                    # Generate infinity loop script for autonomous processing
 npx ca loop --epics epic-1 epic-2
 npx ca loop --output my-loop.sh
 npx ca loop --max-retries 5
@@ -4431,22 +4696,15 @@ npx ca loop --model claude-opus-4-6
 npx ca loop --force            # Overwrite existing script
 \`\`\`
 
-### Health and audit commands
+## Health, audit, and verification commands
 
 \`\`\`bash
+npx ca about                    # Show version, animation, and recent changelog
 npx ca doctor                  # Check external dependencies and project health
 npx ca audit                   # Run pattern, rule, and lesson quality checks
 npx ca rules check             # Check codebase against .claude/rules.json
 npx ca test-summary            # Run tests and output compact pass/fail summary
-\`\`\`
-
-### Verification commands
-
-\`\`\`bash
-# Verify workflow gates before epic closure
-npx ca verify-gates <epic-id>
-
-# Phase state management (used by LFG workflow)
+npx ca verify-gates <epic-id>  # Verify workflow gates before epic closure
 npx ca phase-check init <epic-id>
 npx ca phase-check status
 npx ca phase-check start <phase>
@@ -4454,39 +4712,37 @@ npx ca phase-check gate <gate-name>   # post-plan, gate-3, gate-4, final
 npx ca phase-check clean
 \`\`\`
 
-### Worktree commands
+## Worktree commands
 
 \`\`\`bash
-# Create an isolated worktree for an epic
-npx ca worktree create <epic-id>
-
-# Connect merge dependencies
-npx ca worktree wire-deps <epic-id>
-
-# Merge worktree back to main (two-phase: resolve in worktree, land on main)
-npx ca worktree merge <epic-id>
-
-# List active worktrees
-npx ca worktree list
-
-# Remove worktree and clean up
-npx ca worktree cleanup <epic-id>
-npx ca worktree cleanup <epic-id> --force   # Force cleanup of dirty worktrees
+npx ca worktree create <epic-id>              # Create isolated worktree
+npx ca worktree wire-deps <epic-id>           # Connect merge dependencies
+npx ca worktree merge <epic-id>               # Merge worktree back to main
+npx ca worktree list                          # List active worktrees
+npx ca worktree cleanup <epic-id>             # Remove worktree and clean up
+npx ca worktree cleanup <epic-id> --force     # Force cleanup of dirty worktrees
 \`\`\`
 
-### Compound command
+## Compound command
 
 \`\`\`bash
-# Synthesize cross-cutting patterns from accumulated lessons
-npx ca compound
+npx ca compound                # Synthesize cross-cutting patterns from accumulated lessons
 \`\`\`
-
+`,
+  "SKILLS.md": `---
+version: "{{VERSION}}"
+last-updated: "{{DATE}}"
+summary: "Phase skills and agent role skills reference"
 ---
 
-## 5. Skills reference
+# Skills Reference
 
 Skills are instructions that Claude reads before executing each phase. They live in \`.claude/skills/compound/\` and are auto-installed by \`npx ca setup\`.
 
+---
+
+## Phase skills
+
 ### \`/compound:brainstorm\`
 
 **Purpose**: Divergent-then-convergent thinking to explore the solution space.
@@ -4533,7 +4789,7 @@ Skills are instructions that Claude reads before executing each phase. They live
 
 **When invoked**: When you want to run an entire epic end-to-end.
 
-**What it does**: Sequences all 5 phases with mandatory gates between them, tracks progress in beads notes, handles resumption after interruption.
+**What it does**: Sequences all 5 phases with mandatory gates between them, tracks progress in beads notes, handles resumption after interruption. See [WORKFLOW.md](WORKFLOW.md) for full details.
 
 ### \`/compound:set-worktree\`
 
@@ -4545,150 +4801,42 @@ Skills are instructions that Claude reads before executing each phase. They live
 
 ---
 
-## 6. The LFG workflow
-
-\`/compound:lfg\` chains all 5 phases with enforcement gates. Here is how it works:
-
-### Invocation
-
-\`\`\`
-/compound:lfg <epic-id>
-\`\`\`
-
-Or with a phase skip:
-
-\`\`\`
-/compound:lfg <epic-id> from plan
-\`\`\`
-
-### Phase execution protocol
-
-For each phase, LFG:
-
-1. Announces progress: \`[Phase N/5] PHASE_NAME\`
-2. Initializes state: \`npx ca phase-check start <phase>\`
-3. Reads the phase skill file (non-negotiable -- never from memory)
-4. Runs \`npx ca search\` with the current goal
-5. Executes the phase following skill instructions
-6. Updates epic notes: \`bd update <epic-id> --notes="Phase: NAME COMPLETE | Next: NEXT"\`
-7. Verifies the phase gate before proceeding
-
-### Phase gates
-
-| Gate | When | Verification |
-|------|------|-------------|
-| Post-plan | After Plan | \`bd list --status=open\` shows Review + Compound tasks |
-| Gate 3 | After Work | \`bd list --status=in_progress\` returns empty |
-| Gate 4 | After Review | \`/implementation-reviewer\` returned APPROVED |
-| Final | After Compound | \`npx ca verify-gates <epic-id>\` passes, \`pnpm test\` and \`pnpm lint\` pass |
-
-If any gate fails, LFG stops. You must fix the issue before proceeding.
-
-### Resumption
-
-If interrupted, LFG can resume:
+## Skill invocation
 
-1. Run \`bd show <epic-id>\` and read the notes for phase state
-2. Re-invoke with \`from <phase>\` to skip completed phases
+Skills are invoked as Claude Code slash commands:
 
-### Phase state tracking
-
-LFG persists state in \`.claude/.ca-phase-state.json\`. Useful commands:
-
-\`\`\`bash
-npx ca phase-check status      # See current phase state
-npx ca phase-check clean       # Reset phase state (escape hatch)
 \`\`\`
-
-### Session close
-
-Before saying "done", LFG runs this inviolable checklist:
-
-\`\`\`bash
-git status
-git add <files>
-bd sync
-git commit -m "..."
-bd sync
-git push
+/compound:brainstorm       # Start brainstorm phase
+/compound:plan             # Start plan phase
+/compound:work             # Start work phase
+/compound:review           # Start review phase
+/compound:compound         # Start compound phase
+/compound:lfg <epic-id>    # Run all phases end-to-end
+/compound:set-worktree <epic-id>  # Set up worktree before LFG
 \`\`\`
 
+Each skill reads its SKILL.md file from \`.claude/skills/compound/<phase>/SKILL.md\` at invocation time. Skills are never executed from memory.
+`,
+  "INTEGRATION.md": `---
+version: "{{VERSION}}"
+last-updated: "{{DATE}}"
+summary: "Memory system, hooks, beads integration, and agent guidance"
 ---
 
-## 7. Worktree integration
-
-Worktrees let you run epics in isolation, enabling parallel execution across multiple Claude Code sessions.
-
-### Creating a worktree
-
-\`\`\`bash
-npx ca worktree create <epic-id>
-\`\`\`
-
-This:
-
-1. Creates a git worktree at \`../<repo>-wt-<epic-id>\` on branch \`epic/<epic-id>\`
-2. Installs dependencies via \`pnpm install --frozen-lockfile\`
-3. Copies \`.claude/lessons/index.jsonl\` to the worktree
-4. Runs \`npx ca setup --skip-model\` in the worktree
-5. Creates a Merge beads task linked to the epic
-
-### Using with LFG
-
-\`\`\`bash
-# From main repo:
-npx ca worktree create my-epic-id
-
-# Then in the worktree directory:
-# Run /compound:lfg or /compound:set-worktree followed by /compound:lfg
-\`\`\`
-
-Or use the skill:
-
-\`\`\`
-/compound:set-worktree <epic-id>
-\`\`\`
-
-### Merging back
-
-When all work tasks complete, the Merge task surfaces via \`bd ready\`:
-
-\`\`\`bash
-npx ca worktree merge <epic-id>
-\`\`\`
-
-This runs a two-phase merge:
-
-1. Merges \`main\` into the worktree branch (resolve conflicts there)
-2. Fast-forwards \`main\` to the worktree branch (clean landing)
+# Integration
 
-### Cleanup
-
-\`\`\`bash
-npx ca worktree cleanup <epic-id>
-npx ca worktree cleanup <epic-id> --force   # For dirty worktrees
-\`\`\`
-
-This removes the worktree directory, deletes the branch, and closes the Merge task.
-
-### Listing worktrees
-
-\`\`\`bash
-npx ca worktree list
-\`\`\`
-
-Shows active worktrees with their epic and merge task status.
+Deep integration topics for compound-agent: memory system internals, Claude Code hooks, beads workflow, worktree integration, and agent guidance.
 
 ---
 
-## 8. Memory system
+## Memory system
 
 ### Storage format
 
 Memory items are stored as newline-delimited JSON in \`.claude/lessons/index.jsonl\`. Each line is a complete JSON object:
 
 \`\`\`json
-{"id":"L-abc123","type":"lesson","trigger":"Shell injection via execSync","insight":"Use execFileSync with array args to prevent shell interpretation","tags":["security"],"source":"manual","context":{"tool":"cli","intent":"manual learning"},"created":"2026-02-15T10:00:00Z","confirmed":true,"severity":"high","supersedes":[],"related":[]}
+{"id":"L-abc123","type":"lesson","trigger":"Shell injection via execSync","insight":"Use execFileSync with array args","tags":["security"],"source":"manual","context":{"tool":"cli","intent":"manual learning"},"created":"2026-02-15T10:00:00Z","confirmed":true,"severity":"high","supersedes":[],"related":[]}
 \`\`\`
 
 ### Indexing
@@ -4709,14 +4857,6 @@ The index is rebuilt automatically when the JSONL changes. Force rebuild with \`
 
 **Session loading** (\`npx ca load-session\`): Returns high-severity confirmed lessons for injection at session start.
 
-### Compounding (pattern synthesis)
-
-\`\`\`bash
-npx ca compound
-\`\`\`
-
-This reads all memory items, computes embeddings, clusters them by similarity, and synthesizes cross-cutting patterns into \`.claude/lessons/cct-patterns.jsonl\`. Clusters with 2+ items become patterns; single-item clusters are filtered as noise.
-
 ### Data lifecycle
 
 | Operation | Effect |
@@ -4729,21 +4869,7 @@ This reads all memory items, computes embeddings, clusters them by similarity, a
 
 ---
 
-## 9. For AI agents
-
-### Integrating into CLAUDE.md
-
-Add a reference to compound-agent in your project's \`.claude/CLAUDE.md\`:
-
-\`\`\`markdown
-## References
-
-- docs/compound/HOW_TO_COMPOUND.md -- Usage guide for humans and AI agents
-\`\`\`
-
-The \`npx ca init\` command does this automatically.
-
-### Claude Code hooks
+## Claude Code hooks
 
 Compound-agent installs five hooks into \`.claude/settings.json\`:
 
@@ -4751,7 +4877,7 @@ Compound-agent installs five hooks into \`.claude/settings.json\`:
 |------|---------|--------|
 | **SessionStart** | New session or resume | Runs \`npx ca prime\` to load workflow context and high-severity lessons |
 | **PreCompact** | Before context compaction | Runs \`npx ca prime\` to preserve context across compaction |
-| **UserPromptSubmit** | Every user message | Detects correction language ("actually", "wrong") and planning language ("implement", "build"), injects memory reminders |
+| **UserPromptSubmit** | Every user message | Detects correction/planning language, injects memory reminders |
 | **PostToolUseFailure** | Bash/Edit/Write failures | After 2 failures on same file or 3 total, suggests \`npx ca search\` |
 | **PostToolUse** | After successful tool use | Resets failure tracking; tracks skill file reads for phase guard |
 
@@ -4778,7 +4904,9 @@ npx ca learn "The insight" --trigger "What happened" --severity medium
 npx ca compound
 \`\`\`
 
-### Beads workflow integration
+---
+
+## Beads integration
 
 Compound-agent works with beads (\`bd\`) for issue tracking:
 
@@ -4801,11 +4929,38 @@ Before closing an epic, verify all gates pass:
 npx ca verify-gates <epic-id>
 \`\`\`
 
-This checks that:
+This checks that a Review task, Compound task, and (if applicable) Merge task all exist and are closed.
+
+---
+
+## Worktree integration
+
+Worktrees let you run epics in isolation, enabling parallel execution across multiple Claude Code sessions.
+
+\`\`\`bash
+npx ca worktree create <epic-id>   # Creates worktree + installs deps + copies lessons
+npx ca worktree merge <epic-id>    # Two-phase merge back to main
+npx ca worktree cleanup <epic-id>  # Remove worktree, delete branch, close Merge task
+npx ca worktree list               # Show active worktrees
+\`\`\`
+
+See [CLI_REFERENCE.md](CLI_REFERENCE.md) for full worktree command details.
+
+---
+
+## For AI agents
+
+### Integrating into CLAUDE.md
 
-1. A Review task exists and is closed
-2. A Compound task exists and is closed
-3. If a Merge task exists (worktree epic), it is also closed
+Add a reference to compound-agent in your project's \`.claude/CLAUDE.md\`:
+
+\`\`\`markdown
+## References
+
+- docs/compound/README.md -- Compound-agent overview and getting started
+\`\`\`
+
+The \`npx ca init\` command does this automatically.
 
 ### Session completion checklist
 
@@ -5386,12 +5541,18 @@ Synthesize analysis results into a refined optimization plan:
 - Estimate impact on test suite speed and coverage
 - Iterate with subagents until the plan is comprehensive
 
-### Phase 3: Adversarial Review
+### Phase 3: Adversarial Review (CRITICAL QUALITY GATE)
+**This is THE KEY PHASE -- the most important phase in the entire workflow. NEVER skip, NEVER rush, NEVER settle for "good enough."**
+
 Expose the plan to two neutral reviewer subagents:
 - **Reviewer A** (Opus): Independent critique of the optimization plan
 - **Reviewer B** (Sonnet): Independent critique from a different perspective
+
 Both reviewers challenge assumptions, identify risks, and suggest improvements.
-Iterate: adapt the plan based on feedback until confident.
+
+**Mandatory iteration loop**: After each reviewer pass, if ANY issues, concerns, or suggestions remain from EITHER reviewer, revise the plan and re-submit to BOTH reviewers. Repeat until BOTH reviewers explicitly approve with ZERO reservations. Do not proceed to Phase 4 until unanimous, unconditional approval is reached.
+
+This is the critical quality gate. Loop as many times as needed. The test suite must be bulletproof before execution begins.
 
 ### Phase 4: Execution
 Apply the agreed changes:
@@ -5417,13 +5578,13 @@ Apply the agreed changes:
 ## Common Pitfalls
 - Deleting tests without verifying coverage is maintained elsewhere
 - Optimizing for speed at the cost of correctness
-- Not running the adversarial review (skipping Phase 3)
+- Settling for partial approval or cutting the Phase 3 review loop short before BOTH reviewers approve with zero reservations
 - Making changes without machine-readable output
 - Not feeding results back into compound-agent memory
 
 ## Quality Criteria
 - All 5 phases completed (analysis, planning, review, execution, verification)
-- Adversarial review with 2 independent reviewers was conducted
+- Both adversarial reviewers approved with zero reservations after iterative refinement
 - Machine-readable output format used throughout
 - Full test suite passes after changes
 - Coverage not degraded
@@ -5726,7 +5887,7 @@ async function stripHeadersRecursive(dir, dryRun = false) {
   return count;
 }
 async function upgradeDocVersion(repoRoot, newVersion, dryRun = false) {
-  const docPath = join(repoRoot, "docs", "compound", "HOW_TO_COMPOUND.md");
+  const docPath = join(repoRoot, "docs", "compound", "README.md");
   if (!existsSync(docPath)) return false;
   const content = await readFile(docPath, "utf-8");
   const updated = content.replace(/^(version: ")([^"]+)(")/m, `$1${newVersion}$3`);
@@ -5872,6 +6033,10 @@ async function runUpdate(repoRoot, dryRun) {
   for (const [name, content] of Object.entries(AGENT_ROLE_SKILLS)) {
     await processFile(join(repoRoot, ".claude", "skills", "compound", "agents", name, "SKILL.md"), content);
   }
+  for (const [filename, template] of Object.entries(DOC_TEMPLATES)) {
+    const content = template.replace("{{VERSION}}", VERSION).replace("{{DATE}}", (/* @__PURE__ */ new Date()).toISOString().slice(0, 10));
+    await processFile(join(repoRoot, "docs", "compound", filename), content);
+  }
   for (const filename of LEGACY_ROOT_SLASH_COMMANDS) {
     const filePath = join(repoRoot, ".claude", "commands", filename);
     if (existsSync(filePath)) {
@@ -5881,6 +6046,14 @@ async function runUpdate(repoRoot, dryRun) {
       }
     }
   }
+  const oldDocPath = join(repoRoot, "docs", "compound", "HOW_TO_COMPOUND.md");
+  if (existsSync(oldDocPath)) {
+    const oldContent = await readFile(oldDocPath, "utf-8");
+    if (oldContent.startsWith("---\nversion:")) {
+      if (!dryRun) await rm(oldDocPath);
+      updated++;
+    }
+  }
   let configUpdated = false;
   if (!dryRun) {
     const { hooks } = await configureClaudeSettings();
@@ -5895,11 +6068,12 @@ var MODEL_STATUS_MSG = {
   already_exists: "Already exists",
   failed: "Download failed (run `ca download-model` manually)"
 };
-async function printSetupResult(result, quiet) {
+async function printSetupResult(result, quiet, repoRoot) {
   if (!quiet) {
-    if (result.scope.isUserScope) console.log(`  ${result.scope.message}`);
-    if (!result.beads.available) console.log(`  ${result.beads.message}`);
-    if (result.upgrade?.isUpgrade) console.log(`  ${result.upgrade.message}`);
+    if (result.upgrade?.isUpgrade) {
+      console.log(`  ${result.upgrade.message}`);
+      console.log("  Tip: Run with --update to regenerate managed files with latest templates.");
+    }
     if (process.stdout.isTTY) await playInstallBanner();
   }
   out.success("Compound agent setup complete");
@@ -5910,6 +6084,9 @@ async function printSetupResult(result, quiet) {
   printPnpmConfigStatus(result.pnpmConfig);
   printGitignoreStatus(result.gitignore);
   console.log(`  Model: ${MODEL_STATUS_MSG[result.model]}`);
+  const fullBeads = runFullBeadsCheck(repoRoot);
+  printBeadsFullStatus(fullBeads);
+  printScopeStatus(result.scope);
   console.log("\nNext steps:\n  1. Restart Claude Code to load hooks\n  2. Use `npx ca search` and `npx ca learn` commands");
 }
 function registerSetupAllCommand(setupCommand) {
@@ -5931,6 +6108,7 @@ function registerSetupAllCommand(setupCommand) {
       return;
     }
     if (options.update) {
+      if (!dryRun && process.stdout.isTTY) await playInstallBanner();
       const result2 = await runUpdate(repoRoot, dryRun);
       const prefix = dryRun ? "[dry-run] " : "";
       if (result2.upgrade.isUpgrade) {
@@ -5946,6 +6124,10 @@ function registerSetupAllCommand(setupCommand) {
         console.log(`  ${prefix}.gitignore: Added [${result2.gitignore.added.join(", ")}]`);
       }
       if (result2.configUpdated) console.log(`  ${prefix}Config: hooks updated`);
+      const fullBeads = runFullBeadsCheck(repoRoot);
+      printBeadsFullStatus(fullBeads);
+      const scope = checkUserScope(repoRoot);
+      printScopeStatus(scope);
       return;
     }
     if (options.status) {
@@ -5954,7 +6136,7 @@ function registerSetupAllCommand(setupCommand) {
     }
     const result = await runSetup({ skipModel: options.skipModel, skipHooks: options.skipHooks });
     const { quiet } = getGlobalOpts(this);
-    await printSetupResult(result, quiet);
+    await printSetupResult(result, quiet, repoRoot);
   });
 }
 async function handleStatus(alreadyInstalled, displayPath, settingsPath, options) {
@@ -6175,18 +6357,14 @@ async function initAction(cmd, options) {
   const repoRoot = getRepoRoot();
   const { quiet } = getGlobalOpts(cmd);
   const scopeResult = checkUserScope(repoRoot);
-  if (scopeResult.isUserScope && !quiet && !options.json) {
-    console.log(`  ${scopeResult.message}`);
-  }
-  const beadsResult = checkBeadsAvailable();
-  if (!beadsResult.available && !quiet && !options.json) {
-    console.log(`  ${beadsResult.message}`);
-  }
   let upgradeResult = null;
   if (options.update || detectExistingInstall(repoRoot)) {
     upgradeResult = await runUpgrade(repoRoot);
     if (!quiet && !options.json && upgradeResult.isUpgrade) {
       console.log(`  ${upgradeResult.message}`);
+      if (!options.update) {
+        console.log("  Tip: Run with --update to regenerate managed files with latest templates.");
+      }
     }
   }
   if (!quiet && !options.json && process.stdout.isTTY) {
@@ -6220,8 +6398,9 @@ async function initAction(cmd, options) {
     claudeHooksResult = await installClaudeHooksForInit(repoRoot);
   }
   const gitignoreResult = await ensureGitignore(repoRoot);
+  const fullBeads = runFullBeadsCheck(repoRoot);
   if (options.json) {
-    printInitJson({ lessonsDir, agentsMdUpdated, hookResult, claudeHooksResult, pnpmConfig, beadsResult, scopeResult, upgradeResult, gitignoreResult });
+    printInitJson({ lessonsDir, agentsMdUpdated, hookResult, claudeHooksResult, pnpmConfig, fullBeads, scopeResult, upgradeResult, gitignoreResult });
     return;
   }
   if (quiet) return;
@@ -6232,6 +6411,8 @@ async function initAction(cmd, options) {
   printClaudeHooksStatus(claudeHooksResult, options.skipClaude);
   printPnpmConfigStatus2(pnpmConfig);
   printGitignoreStatus(gitignoreResult);
+  printBeadsFullStatus(fullBeads);
+  printScopeStatus(scopeResult);
 }
 function printInitJson(ctx) {
   const claudeHooksInstalled = ctx.claudeHooksResult.action === "installed";
@@ -6244,7 +6425,9 @@ function printInitJson(ctx) {
     hookStatus: ctx.hookResult?.status ?? "skipped",
     claudeHooks: claudeHooksInstalled,
     pnpmConfig: ctx.pnpmConfig.isPnpm ? { added: ctx.pnpmConfig.added, alreadyConfigured: ctx.pnpmConfig.alreadyConfigured } : null,
-    beadsAvailable: ctx.beadsResult.available,
+    beadsAvailable: ctx.fullBeads.cliAvailable,
+    beadsInitialized: ctx.fullBeads.initialized,
+    beadsHealthy: ctx.fullBeads.healthy,
     userScope: ctx.scopeResult.isUserScope,
     upgrade: ctx.upgradeResult ? { isUpgrade: ctx.upgradeResult.isUpgrade, removedCommands: ctx.upgradeResult.removedCommands, strippedHeaders: ctx.upgradeResult.strippedHeaders } : null,
     gitignore: ctx.gitignoreResult.added
@@ -6514,6 +6697,17 @@ function registerCrudCommands(program2) {
     await deleteAction(ids, options);
   });
 }
+function checkGitignoreHealth(repoRoot) {
+  const gitignorePath = join(repoRoot, ".gitignore");
+  if (!existsSync(gitignorePath)) return false;
+  try {
+    const content = readFileSync(gitignorePath, "utf-8");
+    const lines = new Set(content.split("\n").map((l) => l.trim()));
+    return ["node_modules/", ".claude/.cache/"].every((p) => lines.has(p));
+  } catch {
+    return false;
+  }
+}
 async function runDoctor(repoRoot) {
   const checks = [];
   const claudeDir = join(repoRoot, ".claude");
@@ -6540,20 +6734,21 @@ async function runDoctor(repoRoot) {
   checks.push(modelOk ? { name: "Embedding model", status: "pass" } : { name: "Embedding model", status: "warn", fix: "Run: npx ca download-model" });
   const beadsResult = checkBeadsAvailable();
   checks.push(beadsResult.available ? { name: "Beads CLI", status: "pass" } : { name: "Beads CLI", status: "warn", fix: "Install beads: https://github.com/Nathandela/beads" });
-  const gitignorePath = join(repoRoot, ".gitignore");
-  const requiredPatterns = ["node_modules/", ".claude/.cache/"];
-  let gitignoreOk = false;
-  if (existsSync(gitignorePath)) {
+  checks.push(checkGitignoreHealth(repoRoot) ? { name: ".gitignore health", status: "pass" } : { name: ".gitignore health", status: "warn", fix: "Run: npx ca setup --update" });
+  const docPath = join(repoRoot, "docs", "compound", "README.md");
+  checks.push(existsSync(docPath) ? { name: "Usage documentation", status: "pass" } : { name: "Usage documentation", status: "warn", fix: "Run: npx ca setup" });
+  const beadsDir = join(repoRoot, ".beads");
+  checks.push(existsSync(beadsDir) ? { name: "Beads initialized", status: "pass" } : { name: "Beads initialized", status: "warn", fix: "Run: bd init" });
+  if (beadsResult.available && existsSync(beadsDir)) {
     try {
-      const content = readFileSync(gitignorePath, "utf-8");
-      const lines = new Set(content.split("\n").map((l) => l.trim()));
-      gitignoreOk = requiredPatterns.every((p) => lines.has(p));
+      execSync("bd doctor", { cwd: repoRoot, shell: "/bin/sh", stdio: "pipe" });
+      checks.push({ name: "Beads healthy", status: "pass" });
     } catch {
+      checks.push({ name: "Beads healthy", status: "warn", fix: "Run: bd doctor" });
     }
   }
-  checks.push(gitignoreOk ? { name: ".gitignore health", status: "pass" } : { name: ".gitignore health", status: "warn", fix: "Run: npx ca setup --update" });
-  const docPath = join(repoRoot, "docs", "compound", "HOW_TO_COMPOUND.md");
-  checks.push(existsSync(docPath) ? { name: "Usage documentation", status: "pass" } : { name: "Usage documentation", status: "warn", fix: "Run: npx ca setup" });
+  const scope = checkUserScope(repoRoot);
+  checks.push(!scope.isUserScope ? { name: "Codebase scope", status: "pass" } : { name: "Codebase scope", status: "warn", fix: "Install in a specific repository, not home directory" });
   return checks;
 }
 var STATUS_ICONS = {
@@ -7335,6 +7530,96 @@ function registerVerifyGatesCommand(program2) {
     }
   });
 }
+
+// src/changelog-data.ts
+var CHANGELOG_RECENT = `## [1.3.2] - 2026-02-21
+
+### Added
+
+- **Banner audio**: Pure TypeScript WAV synthesis plays a rising pentatonic melody during the tendril animation. Cross-platform: \`afplay\` (macOS), \`aplay\` (Linux), PowerShell (Windows). Silently skips if player unavailable. Zero dependencies.
+- **Test coverage**: 19 new tests for \`ca about\` command, changelog extraction/escaping, and \`--update\` doc migration path
+
+### Fixed
+
+- **\`setup --update\` doc migration**: \`--update\` now installs the 5 split docs before removing legacy \`HOW_TO_COMPOUND.md\`, preventing empty \`docs/compound/\`
+- **Fresh checkout type-check**: \`src/changelog-data.ts\` tracked in git so \`tsc --noEmit\` passes without a prior build
+- **Trailing status text**: Banner animation no longer leaves "al tendrils..." remnant from previous phase
+
+### Changed
+
+- **\`ca about\` command**: Renamed from \`ca version-show\` for brevity
+- **Changelog extraction**: Core parsing/escaping logic extracted to \`scripts/changelog-utils.ts\` (shared between prebuild script and tests)
+- **Narrowed \`.gitignore\`**: Setup-generated patterns scoped to \`compound/\` subdirectories to avoid hiding tracked TDD agent definitions
+
+## [1.3.1] - 2026-02-21
+
+### Added
+
+- **\`ca about\` command**: Displays version with terminal animation (tendril growth) and recent changelog entries. Non-TTY environments get plain text output. Changelog is embedded at build time from CHANGELOG.md.
+- **3 new doctor checks**: Beads initialized (\`.beads/\` dir), beads healthy (\`bd doctor\`), codebase scope (user-scope detection)
+- **Beads + scope status in init/setup output**: Full beads health display (CLI available, initialized, healthy) and scope status shown after \`ca init\`, \`ca setup\`, and \`ca setup --update\`
+- **Banner on \`--update\`**: Terminal art animation now plays during \`ca setup --update\` and \`ca init --update\` (same TTY/quiet guards as fresh install)
+
+### Changed
+
+- **Split documentation**: \`HOW_TO_COMPOUND.md\` replaced by 5 focused documents in \`docs/compound/\`: \`README.md\`, \`WORKFLOW.md\`, \`CLI_REFERENCE.md\`, \`SKILLS.md\`, \`INTEGRATION.md\`
+- **Test-cleaner Phase 3 strengthened**: Adversarial review phase now mandates iteration loop until both reviewers give unconditional approval. Heading, emphasis, and quality criteria updated.
+- **Update hint on upgrade**: When \`ca init\` or \`ca setup\` detects an existing install, displays tip to run with \`--update\` to regenerate managed files
+- **HOW_TO_COMPOUND.md migration**: \`ca setup --update\` automatically removes old monolithic \`HOW_TO_COMPOUND.md\` if it has version frontmatter (generated by compound-agent)
+- **Doctor doc check**: Now checks for \`docs/compound/README.md\` instead of \`HOW_TO_COMPOUND.md\`
+
+## [1.3.0] - 2026-02-21
+
+### Added
+
+- **Setup hardening**: Four new pre-flight checks during \`ca init\` and \`ca setup\`:
+  - **Beads CLI check** (\`beads-check.ts\`): Detects if \`bd\` is available, shows install URL if missing (informational, non-blocking)
+  - **User-scope detection** (\`scope-check.ts\`): Warns when installing at home directory level where lessons are shared across projects
+  - **.gitignore injection** (\`gitignore.ts\`): Ensures \`node_modules/\` and \`.claude/.cache/\` patterns exist in \`.gitignore\`
+  - **Upgrade detection** (\`upgrade.ts\`): Detects existing installs and runs migration pipeline (deprecated command removal, header stripping, doc version update)
+- **Upgrade engine**: Automated migration from v1.2.x to v1.3.0:
+  - Removes 5 deprecated CLI wrapper commands (\`search.md\`, \`list.md\`, \`show.md\`, \`stats.md\`, \`wrong.md\`)
+  - Strips legacy \`<!-- generated by compound-agent -->\` headers from installed files
+  - Updates \`HOW_TO_COMPOUND.md\` version during upgrade
+- **\`/compound:research\` skill**: PhD-depth research producing structured survey documents following \`TEMPLATE_FOR_RESEARCH.md\` format
+- **\`/compound:test-clean\` skill**: 5-phase test suite optimization with adversarial review (audit, design, implement, verify, report)
+- **Documentation template**: \`HOW_TO_COMPOUND.md\` deployed to \`docs/compound/\` during setup with version and date placeholders
+- **Test scripts**: \`test:segment\` (run tests for specific module), \`test:random\` (seeded random subset), \`test:critical\` (*.critical.test.ts convention)
+- **3 new doctor checks**: Beads CLI availability, \`.gitignore\` health, usage documentation presence
+
+### Fixed
+
+- **\`setup --update --dry-run\` no longer mutates files**: \`runUpgrade()\` now accepts a \`dryRun\` parameter propagated to all sub-functions (removeDeprecatedCommands, stripGeneratedHeaders, upgradeDocVersion)
+- **\`setup --uninstall\` respects plugin.json ownership**: Checks \`name === "compound-agent"\` before deleting; user-owned plugin manifests are preserved
+- **Upgrade ownership guard**: \`removeDeprecatedCommands\` checks file content for compound-agent markers before deleting, preventing silent removal of user-authored files with the same name
+- **Malformed settings.json no longer silently clobbered**: On parse error, \`configureClaudeSettings\` warns and skips instead of overwriting with empty config
+
+### Changed
+
+- **\`setup --update\` overhaul**: Now uses path-based file detection (compound/ = managed) instead of marker-based. Runs upgrade pipeline and \`.gitignore\` remediation during update
+- **JSON-first \`bd\` parsing in loop**: \`jq\` primary with \`python3\` fallback via \`parse_json()\` helper
+- **CLI test helpers hardened**: Replaced shell string interpolation with \`execFileSync\` for safety and reliability
+- **Beads check portable**: Uses POSIX \`command -v\` instead of non-portable \`which\`
+- **Template expansion**: Brainstorm and plan skills now cross-reference researcher skill; 9 total skills, 11 total commands
+- **Code organization**: Extracted display utilities to \`display-utils.ts\`, uninstall logic to \`uninstall.ts\`
+
+### Removed
+
+- **5 deprecated CLI wrapper commands**: \`search.md\`, \`list.md\`, \`show.md\`, \`stats.md\`, \`wrong.md\` (redundant wrappers around \`npx ca <cmd>\`)
+- **\`GENERATED_MARKER\` on new installs**: New installs use path-based detection; marker retained only for backward-compatible \`--update\` detection`;
+
+// src/commands/about.ts
+function registerAboutCommand(program2) {
+  program2.command("about").description("Show version, animation, and recent changelog").action(async () => {
+    if (process.stdout.isTTY) {
+      await playInstallBanner();
+    } else {
+      console.log(`compound-agent v${VERSION}`);
+    }
+    console.log("");
+    console.log(CHANGELOG_RECENT);
+  });
+}
 function parseWorktreeList(raw) {
   const entries = [];
   let currentPath = "";
@@ -8443,6 +8728,7 @@ function registerManagementCommands(program2) {
   registerRulesCommands(program2);
   registerTestSummaryCommand(program2);
   registerVerifyGatesCommand(program2);
+  registerAboutCommand(program2);
   registerWorktreeCommands(program2);
 }