compound-agent 1.3.3 → 1.4.0

package/dist/cli.js

@@ -1,17 +1,521 @@
 #!/usr/bin/env node
+import { createRequire } from 'module';
+import { mkdirSync, writeFileSync, statSync, unlinkSync, existsSync, readFileSync, copyFileSync, chmodSync, lstatSync, readdirSync } from 'fs';
+import path, { join, dirname, resolve, extname, relative } from 'path';
+import { createHash } from 'crypto';
+import * as fs from 'fs/promises';
+import { readFile, mkdir, appendFile, writeFile, chmod, rm, rename, readdir } from 'fs/promises';
 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, 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, spawn } from 'child_process';
+import { fileURLToPath } from 'url';
 import chalk from 'chalk';
 
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+function ensureSqliteAvailable() {
+  if (checked) return;
+  try {
+    const module = require2("better-sqlite3");
+    const Constructor = module.default || module;
+    const testDb = new Constructor(":memory:");
+    testDb.close();
+    DatabaseConstructor = Constructor;
+    checked = true;
+  } catch (cause) {
+    throw new Error(
+      'better-sqlite3 failed to load.\nRun: npx ca setup (auto-configures pnpm native builds)\nOr manually add to your package.json:\n  "pnpm": { "onlyBuiltDependencies": ["better-sqlite3", "node-llama-cpp"] }\nThen run: pnpm install && pnpm rebuild better-sqlite3\nFor npm/yarn, run: npm rebuild better-sqlite3',
+      { cause }
+    );
+  }
+}
+function getDatabaseConstructor() {
+  ensureSqliteAvailable();
+  return DatabaseConstructor;
+}
+var require2, checked, DatabaseConstructor;
+var init_availability = __esm({
+  "src/memory/storage/sqlite/availability.ts"() {
+    require2 = createRequire(import.meta.url);
+    checked = false;
+    DatabaseConstructor = null;
+  }
+});
+
+// src/memory/storage/sqlite-knowledge/schema.ts
+function createKnowledgeSchema(database) {
+  database.exec(SCHEMA_SQL2);
+  database.pragma(`user_version = ${KNOWLEDGE_SCHEMA_VERSION}`);
+}
+var KNOWLEDGE_SCHEMA_VERSION, SCHEMA_SQL2;
+var init_schema = __esm({
+  "src/memory/storage/sqlite-knowledge/schema.ts"() {
+    KNOWLEDGE_SCHEMA_VERSION = 2;
+    SCHEMA_SQL2 = `
+  CREATE TABLE IF NOT EXISTS chunks (
+    id TEXT PRIMARY KEY,
+    file_path TEXT NOT NULL,
+    start_line INTEGER NOT NULL,
+    end_line INTEGER NOT NULL,
+    content_hash TEXT NOT NULL,
+    text TEXT NOT NULL,
+    embedding BLOB,
+    model TEXT,
+    updated_at TEXT NOT NULL
+  );
+
+  CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(
+    text,
+    content='chunks', content_rowid='rowid'
+  );
+
+  CREATE TRIGGER IF NOT EXISTS chunks_ai AFTER INSERT ON chunks BEGIN
+    INSERT INTO chunks_fts(rowid, text)
+    VALUES (new.rowid, new.text);
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS chunks_ad AFTER DELETE ON chunks BEGIN
+    INSERT INTO chunks_fts(chunks_fts, rowid, text)
+    VALUES ('delete', old.rowid, old.text);
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS chunks_au AFTER UPDATE ON chunks BEGIN
+    INSERT INTO chunks_fts(chunks_fts, rowid, text)
+    VALUES ('delete', old.rowid, old.text);
+    INSERT INTO chunks_fts(rowid, text)
+    VALUES (new.rowid, new.text);
+  END;
+
+  CREATE INDEX IF NOT EXISTS idx_chunks_file_path ON chunks(file_path);
+
+  CREATE TABLE IF NOT EXISTS metadata (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+  );
+`;
+  }
+});
+function openKnowledgeDb(repoRoot, options = {}) {
+  const { inMemory = false } = options;
+  const key = inMemory ? `:memory:${repoRoot}` : join(repoRoot, KNOWLEDGE_DB_PATH);
+  const cached = knowledgeDbMap.get(key);
+  if (cached) {
+    return cached;
+  }
+  const Database = getDatabaseConstructor();
+  let database;
+  if (inMemory) {
+    database = new Database(":memory:");
+  } else {
+    const dir = dirname(key);
+    mkdirSync(dir, { recursive: true });
+    database = new Database(key);
+    const version = database.pragma("user_version", { simple: true });
+    if (version !== 0 && version !== KNOWLEDGE_SCHEMA_VERSION) {
+      database.close();
+      try {
+        unlinkSync(key);
+      } catch {
+      }
+      database = new Database(key);
+    }
+    database.pragma("journal_mode = WAL");
+  }
+  createKnowledgeSchema(database);
+  knowledgeDbMap.set(key, database);
+  return database;
+}
+function closeKnowledgeDb() {
+  for (const database of knowledgeDbMap.values()) {
+    database.close();
+  }
+  knowledgeDbMap.clear();
+}
+var KNOWLEDGE_DB_PATH, knowledgeDbMap;
+var init_connection = __esm({
+  "src/memory/storage/sqlite-knowledge/connection.ts"() {
+    init_availability();
+    init_schema();
+    KNOWLEDGE_DB_PATH = ".claude/.cache/knowledge.sqlite";
+    knowledgeDbMap = /* @__PURE__ */ new Map();
+  }
+});
+function generateChunkId(filePath, startLine, endLine) {
+  return createHash("sha256").update(`${filePath}:${startLine}:${endLine}`).digest("hex").slice(0, 16);
+}
+function chunkContentHash(text) {
+  return createHash("sha256").update(text).digest("hex");
+}
+var SUPPORTED_EXTENSIONS, CODE_EXTENSIONS;
+var init_types = __esm({
+  "src/memory/knowledge/types.ts"() {
+    SUPPORTED_EXTENSIONS = /* @__PURE__ */ new Set([
+      ".md",
+      ".txt",
+      ".rst",
+      ".ts",
+      ".py",
+      ".js",
+      ".tsx",
+      ".jsx"
+    ]);
+    CODE_EXTENSIONS = /* @__PURE__ */ new Set([
+      ".ts",
+      ".tsx",
+      ".js",
+      ".jsx",
+      ".py"
+    ]);
+  }
+});
+
+// src/memory/storage/sqlite-knowledge/sync.ts
+function upsertChunks(repoRoot, chunks, embeddings) {
+  if (chunks.length === 0) return;
+  const database = openKnowledgeDb(repoRoot);
+  const insert = database.prepare(`
+    INSERT OR REPLACE INTO chunks (id, file_path, start_line, end_line, content_hash, text, embedding, model, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  const upsertMany = database.transaction((items) => {
+    for (const chunk of items) {
+      const embBuffer = null;
+      insert.run(
+        chunk.id,
+        chunk.filePath,
+        chunk.startLine,
+        chunk.endLine,
+        chunk.contentHash,
+        chunk.text,
+        embBuffer,
+        chunk.model ?? null,
+        chunk.updatedAt
+      );
+    }
+  });
+  upsertMany(chunks);
+}
+function deleteChunksByFilePath(repoRoot, filePaths) {
+  if (filePaths.length === 0) return;
+  const database = openKnowledgeDb(repoRoot);
+  const del = database.prepare("DELETE FROM chunks WHERE file_path = ?");
+  const deleteMany = database.transaction((paths) => {
+    for (const path2 of paths) {
+      del.run(path2);
+    }
+  });
+  deleteMany(filePaths);
+}
+function getIndexedFilePaths(repoRoot) {
+  const database = openKnowledgeDb(repoRoot);
+  const rows = database.prepare("SELECT DISTINCT file_path FROM chunks").all();
+  return rows.map((r) => r.file_path);
+}
+function getChunkCount(repoRoot) {
+  const database = openKnowledgeDb(repoRoot);
+  const row = database.prepare("SELECT COUNT(*) as cnt FROM chunks").get();
+  return row.cnt;
+}
+function getChunkCountByFilePath(repoRoot, filePath) {
+  const database = openKnowledgeDb(repoRoot);
+  const row = database.prepare("SELECT COUNT(*) as cnt FROM chunks WHERE file_path = ?").get(filePath);
+  return row.cnt;
+}
+function setLastIndexTime(repoRoot, time) {
+  const database = openKnowledgeDb(repoRoot);
+  database.prepare("INSERT OR REPLACE INTO metadata (key, value) VALUES ('last_index_time', ?)").run(time);
+}
+var init_sync = __esm({
+  "src/memory/storage/sqlite-knowledge/sync.ts"() {
+    init_connection();
+  }
+});
+function isBinary(content) {
+  return content.includes("\0");
+}
+function splitIntoSections(fileLines, ext) {
+  if (ext === ".md") {
+    return splitMarkdown(fileLines);
+  }
+  if (ext === ".rst") {
+    return splitParagraphs(fileLines);
+  }
+  if (CODE_EXTENSIONS.has(ext)) {
+    return splitCode(fileLines);
+  }
+  return splitParagraphs(fileLines);
+}
+function splitMarkdown(fileLines) {
+  const sections = [];
+  let current = [];
+  let inCodeBlock = false;
+  for (let i = 0; i < fileLines.length; i++) {
+    const line = fileLines[i];
+    const lineObj = { lineNumber: i + 1, text: line };
+    if (line.trimStart().startsWith("```")) {
+      inCodeBlock = !inCodeBlock;
+      current.push(lineObj);
+      continue;
+    }
+    if (!inCodeBlock && /^#{2,}\s/.test(line) && current.length > 0) {
+      sections.push(current);
+      current = [lineObj];
+      continue;
+    }
+    if (!inCodeBlock && line.trim() === "" && current.length > 0 && current.some((l) => l.text.trim() !== "")) {
+      current.push(lineObj);
+      sections.push(current);
+      current = [];
+      continue;
+    }
+    current.push(lineObj);
+  }
+  if (current.length > 0) {
+    sections.push(current);
+  }
+  return sections;
+}
+function splitCode(fileLines) {
+  const sections = [];
+  let current = [];
+  for (let i = 0; i < fileLines.length; i++) {
+    const line = fileLines[i];
+    const lineObj = { lineNumber: i + 1, text: line };
+    if (line.trim() === "" && current.length > 0) {
+      let hasNextNonBlank = false;
+      for (let j = i + 1; j < fileLines.length; j++) {
+        if (fileLines[j].trim() !== "") {
+          hasNextNonBlank = true;
+          break;
+        }
+      }
+      if (hasNextNonBlank) {
+        sections.push(current);
+        current = [lineObj];
+        continue;
+      }
+    }
+    current.push(lineObj);
+  }
+  if (current.length > 0) {
+    sections.push(current);
+  }
+  return sections;
+}
+function splitParagraphs(fileLines) {
+  const sections = [];
+  let current = [];
+  for (let i = 0; i < fileLines.length; i++) {
+    const line = fileLines[i];
+    const lineObj = { lineNumber: i + 1, text: line };
+    if (line.trim() === "" && current.length > 0) {
+      sections.push(current);
+      current = [lineObj];
+      continue;
+    }
+    current.push(lineObj);
+  }
+  if (current.length > 0) {
+    sections.push(current);
+  }
+  return sections;
+}
+function sectionText(section) {
+  return section.map((l) => l.text).join("\n");
+}
+function chunkFile(filePath, content, options) {
+  if (content.trim() === "") return [];
+  if (isBinary(content)) return [];
+  const targetSize = DEFAULT_TARGET_SIZE;
+  const overlapSize = DEFAULT_OVERLAP_SIZE;
+  const fileLines = content.split("\n");
+  const ext = extname(filePath).toLowerCase();
+  const sections = splitIntoSections(fileLines, ext);
+  const chunks = [];
+  let accumulated = [];
+  let accumulatedLength = 0;
+  function emitChunk(lines, overlapLines2) {
+    if (lines.length === 0) return [];
+    const allLines = [...overlapLines2, ...lines];
+    const text = allLines.map((l) => l.text).join("\n");
+    const startLine = allLines[0].lineNumber;
+    const endLine = allLines[allLines.length - 1].lineNumber;
+    chunks.push({
+      id: generateChunkId(filePath, startLine, endLine),
+      filePath,
+      startLine,
+      endLine,
+      text,
+      contentHash: chunkContentHash(text)
+    });
+    if (overlapSize <= 0) return [];
+    const overlapResult = [];
+    let overlapLen = 0;
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const lineLen = lines[i].text.length + 1;
+      if (overlapLen + lineLen > overlapSize && overlapResult.length > 0) break;
+      overlapResult.unshift(lines[i]);
+      overlapLen += lineLen;
+    }
+    return overlapResult;
+  }
+  let overlapLines = [];
+  for (const section of sections) {
+    const sectionLen = sectionText(section).length;
+    if (accumulatedLength > 0 && accumulatedLength + sectionLen > targetSize) {
+      overlapLines = emitChunk(accumulated, overlapLines);
+      accumulated = [];
+      accumulatedLength = 0;
+    }
+    accumulated.push(...section);
+    accumulatedLength += sectionLen;
+    if (accumulatedLength > targetSize) {
+      overlapLines = emitChunk(accumulated, overlapLines);
+      accumulated = [];
+      accumulatedLength = 0;
+    }
+  }
+  if (accumulated.length > 0) {
+    emitChunk(accumulated, overlapLines);
+  }
+  return chunks;
+}
+var DEFAULT_TARGET_SIZE, DEFAULT_OVERLAP_SIZE;
+var init_chunking = __esm({
+  "src/memory/knowledge/chunking.ts"() {
+    init_types();
+    DEFAULT_TARGET_SIZE = 1600;
+    DEFAULT_OVERLAP_SIZE = 320;
+  }
+});
+
+// src/memory/knowledge/indexing.ts
+var indexing_exports = {};
+__export(indexing_exports, {
+  indexDocs: () => indexDocs
+});
+function fileHash(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+function fileHashKey(relativePath) {
+  return "file_hash:" + relativePath;
+}
+function getStoredFileHash(repoRoot, relativePath) {
+  const db = openKnowledgeDb(repoRoot);
+  const row = db.prepare("SELECT value FROM metadata WHERE key = ?").get(fileHashKey(relativePath));
+  return row?.value ?? null;
+}
+function setFileHash(repoRoot, relativePath, hash) {
+  const db = openKnowledgeDb(repoRoot);
+  db.prepare("INSERT OR REPLACE INTO metadata (key, value) VALUES (?, ?)").run(fileHashKey(relativePath), hash);
+}
+function removeFileHash(repoRoot, relativePath) {
+  const db = openKnowledgeDb(repoRoot);
+  db.prepare("DELETE FROM metadata WHERE key = ?").run(fileHashKey(relativePath));
+}
+async function walkSupportedFiles(baseDir, repoRoot) {
+  const results = [];
+  let entries;
+  try {
+    entries = await readdir(baseDir, { recursive: true, withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const ext = extname(entry.name).toLowerCase();
+    if (!SUPPORTED_EXTENSIONS.has(ext)) continue;
+    const fullPath = join(entry.parentPath ?? entry.path, entry.name);
+    const relPath = relative(repoRoot, fullPath);
+    results.push(relPath);
+  }
+  return results;
+}
+async function indexDocs(repoRoot, options = {}) {
+  const start = Date.now();
+  const docsDir = options.docsDir ?? "docs";
+  const force = options.force ?? false;
+  const stats = {
+    filesIndexed: 0,
+    filesSkipped: 0,
+    filesErrored: 0,
+    chunksCreated: 0,
+    chunksDeleted: 0,
+    durationMs: 0
+  };
+  const docsPath = join(repoRoot, docsDir);
+  const filePaths = await walkSupportedFiles(docsPath, repoRoot);
+  for (const relPath of filePaths) {
+    const fullPath = join(repoRoot, relPath);
+    let content;
+    try {
+      content = await readFile(fullPath, "utf-8");
+    } catch {
+      stats.filesErrored++;
+      continue;
+    }
+    const hash = fileHash(content);
+    const storedHash = getStoredFileHash(repoRoot, relPath);
+    if (!force && storedHash === hash) {
+      stats.filesSkipped++;
+      continue;
+    }
+    const chunks = chunkFile(relPath, content);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const knowledgeChunks = chunks.map((chunk) => ({
+      id: chunk.id,
+      filePath: chunk.filePath,
+      startLine: chunk.startLine,
+      endLine: chunk.endLine,
+      contentHash: chunk.contentHash,
+      text: chunk.text,
+      updatedAt: now
+    }));
+    const db = openKnowledgeDb(repoRoot);
+    db.transaction(() => {
+      deleteChunksByFilePath(repoRoot, [relPath]);
+      if (knowledgeChunks.length > 0) {
+        upsertChunks(repoRoot, knowledgeChunks);
+      }
+      setFileHash(repoRoot, relPath, hash);
+    })();
+    stats.filesIndexed++;
+    stats.chunksCreated += knowledgeChunks.length;
+  }
+  const indexedPaths = getIndexedFilePaths(repoRoot);
+  const currentPathSet = new Set(filePaths);
+  const stalePaths = indexedPaths.filter((p) => !currentPathSet.has(p));
+  if (stalePaths.length > 0) {
+    for (const path2 of stalePaths) {
+      stats.chunksDeleted += getChunkCountByFilePath(repoRoot, path2);
+    }
+    deleteChunksByFilePath(repoRoot, stalePaths);
+    for (const path2 of stalePaths) {
+      removeFileHash(repoRoot, path2);
+    }
+  }
+  setLastIndexTime(repoRoot, (/* @__PURE__ */ new Date()).toISOString());
+  stats.durationMs = Date.now() - start;
+  return stats;
+}
+var init_indexing = __esm({
+  "src/memory/knowledge/indexing.ts"() {
+    init_connection();
+    init_sync();
+    init_chunking();
+    init_types();
+  }
+});
+
 // src/cli-utils.ts
 function formatBytes(bytes) {
   if (bytes === 0) return "0 B";
@@ -29,7 +533,7 @@ function parseLimit(value, name) {
   return parsed;
 }
 function getRepoRoot() {
-  return process.env["COMPOUND_AGENT_ROOT"] ?? process.cwd();
+  return process.env["COMPOUND_AGENT_ROOT"] || process.cwd();
 }
 var EPIC_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
 function validateEpicId(epicId) {
@@ -340,29 +844,9 @@ async function readLessons(repoRoot, options = {}) {
   const lessons = result.items.filter((item) => item.type === "lesson");
   return { lessons, skippedCount: result.skippedCount };
 }
-var require2 = createRequire(import.meta.url);
-var checked = false;
-var DatabaseConstructor = null;
-function ensureSqliteAvailable() {
-  if (checked) return;
-  try {
-    const module = require2("better-sqlite3");
-    const Constructor = module.default || module;
-    const testDb = new Constructor(":memory:");
-    testDb.close();
-    DatabaseConstructor = Constructor;
-    checked = true;
-  } catch (cause) {
-    throw new Error(
-      'better-sqlite3 failed to load.\nRun: npx ca setup (auto-configures pnpm native builds)\nOr manually add to your package.json:\n  "pnpm": { "onlyBuiltDependencies": ["better-sqlite3", "node-llama-cpp"] }\nThen run: pnpm install && pnpm rebuild better-sqlite3\nFor npm/yarn, run: npm rebuild better-sqlite3',
-      { cause }
-    );
-  }
-}
-function getDatabaseConstructor() {
-  ensureSqliteAvailable();
-  return DatabaseConstructor;
-}
+
+// src/memory/storage/sqlite/connection.ts
+init_availability();
 
 // src/memory/storage/sqlite/schema.ts
 var SCHEMA_VERSION = 3;
@@ -458,7 +942,10 @@ function openDb(repoRoot, options = {}) {
     database = new Database(key);
     if (!hasExpectedVersion(database)) {
       database.close();
-      unlinkSync(key);
+      try {
+        unlinkSync(key);
+      } catch {
+      }
       database = new Database(key);
     }
     database.pragma("journal_mode = WAL");
@@ -599,7 +1086,65 @@ async function syncIfNeeded(repoRoot, options = {}) {
   return false;
 }
 
+// src/memory/search/hybrid.ts
+var DEFAULT_VECTOR_WEIGHT = 0.7;
+var DEFAULT_TEXT_WEIGHT = 0.3;
+var CANDIDATE_MULTIPLIER = 4;
+var MIN_HYBRID_SCORE = 0.35;
+function normalizeBm25Rank(rank) {
+  if (!Number.isFinite(rank)) return 0;
+  const abs = Math.abs(rank);
+  return abs / (1 + abs);
+}
+function mergeHybridScores(vectorResults, keywordResults, getId, options) {
+  if (vectorResults.length === 0 && keywordResults.length === 0) return [];
+  const rawVecW = options?.vectorWeight ?? DEFAULT_VECTOR_WEIGHT;
+  const rawTxtW = options?.textWeight ?? DEFAULT_TEXT_WEIGHT;
+  const total = rawVecW + rawTxtW;
+  if (total <= 0) return [];
+  const vecW = rawVecW / total;
+  const txtW = rawTxtW / total;
+  const limit = options?.limit;
+  const minScore = options?.minScore;
+  const merged = /* @__PURE__ */ new Map();
+  for (const v of vectorResults) {
+    merged.set(getId(v.item), { item: v.item, vecScore: v.score, txtScore: 0 });
+  }
+  for (const k of keywordResults) {
+    const id = getId(k.item);
+    const existing = merged.get(id);
+    if (existing) {
+      existing.txtScore = k.score;
+    } else {
+      merged.set(id, { item: k.item, vecScore: 0, txtScore: k.score });
+    }
+  }
+  const results = [];
+  for (const entry of merged.values()) {
+    results.push({
+      item: entry.item,
+      score: vecW * entry.vecScore + txtW * entry.txtScore
+    });
+  }
+  results.sort((a, b) => b.score - a.score);
+  const filtered = minScore !== void 0 ? results.filter((r) => r.score >= minScore) : results;
+  return limit !== void 0 ? filtered.slice(0, limit) : filtered;
+}
+function mergeHybridResults(vectorResults, keywordResults, options) {
+  const genericVec = vectorResults.map((v) => ({ item: v.lesson, score: v.score }));
+  const genericKw = keywordResults.map((k) => ({ item: k.lesson, score: k.score }));
+  const merged = mergeHybridScores(genericVec, genericKw, (item) => item.id, options);
+  return merged.map((m) => ({ lesson: m.item, score: m.score }));
+}
+
 // src/memory/storage/sqlite/search.ts
+function safeJsonParse(value, fallback) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return fallback;
+  }
+}
 function rowToMemoryItem(row) {
   const item = {
     id: row.id,
@@ -608,9 +1153,9 @@ function rowToMemoryItem(row) {
     insight: row.insight,
     tags: row.tags ? row.tags.split(",").filter(Boolean) : [],
     source: row.source,
-    context: JSON.parse(row.context),
-    supersedes: JSON.parse(row.supersedes),
-    related: JSON.parse(row.related),
+    context: safeJsonParse(row.context, {}),
+    supersedes: safeJsonParse(row.supersedes, []),
+    related: safeJsonParse(row.related, []),
     created: row.created,
     confirmed: row.confirmed === 1
   };
@@ -641,7 +1186,7 @@ function rowToMemoryItem(row) {
 }
 var FTS_OPERATORS = /* @__PURE__ */ new Set(["AND", "OR", "NOT", "NEAR"]);
 function sanitizeFtsQuery(query) {
-  const stripped = query.replace(/["*^+-]/g, "");
+  const stripped = query.replace(/["*^+\-():{}]/g, "");
   const tokens = stripped.split(/\s+/).filter((t) => t.length > 0 && !FTS_OPERATORS.has(t));
   return tokens.join(" ");
 }
@@ -662,31 +1207,47 @@ function incrementRetrievalCount(repoRoot, lessonIds) {
   });
   updateMany(lessonIds);
 }
-async function searchKeyword(repoRoot, query, limit, typeFilter) {
+function executeFtsQuery(repoRoot, query, limit, options) {
   const database = openDb(repoRoot);
-  const countResult = database.prepare("SELECT COUNT(*) as cnt FROM lessons").get();
-  if (countResult.cnt === 0) return [];
   const sanitized = sanitizeFtsQuery(query);
   if (sanitized === "") return [];
+  const selectCols = options.includeRank ? "l.*, fts.rank" : "l.*";
+  const orderClause = options.includeRank ? "ORDER BY fts.rank" : "";
+  const typeClause = options.typeFilter ? "AND l.type = ?" : "";
+  const sql = `
+    SELECT ${selectCols}
+    FROM lessons l
+    JOIN lessons_fts fts ON l.rowid = fts.rowid
+    WHERE lessons_fts MATCH ?
+      AND l.invalidated_at IS NULL
+      ${typeClause}
+    ${orderClause}
+    LIMIT ?
+  `;
+  const params = options.typeFilter ? [sanitized, options.typeFilter, limit] : [sanitized, limit];
   try {
-    if (typeFilter) ;
-    const rows = database.prepare(
-      `
-        SELECT l.*
-        FROM lessons l
-        JOIN lessons_fts fts ON l.rowid = fts.rowid
-        WHERE lessons_fts MATCH ?
-          AND l.invalidated_at IS NULL
-        LIMIT ?
-      `
-    ).all(sanitized, limit);
-    return rows.map(rowToMemoryItem).filter((x) => x !== null);
+    return database.prepare(sql).all(...params);
   } catch (err) {
     const message = err instanceof Error ? err.message : "Unknown FTS5 error";
     console.error(`[compound-agent] search error: ${message}`);
     return [];
   }
 }
+async function searchKeyword(repoRoot, query, limit, typeFilter) {
+  const rows = executeFtsQuery(repoRoot, query, limit, { includeRank: false, typeFilter });
+  return rows.map(rowToMemoryItem).filter((x) => x !== null);
+}
+async function searchKeywordScored(repoRoot, query, limit, typeFilter) {
+  const rows = executeFtsQuery(repoRoot, query, limit, { includeRank: true, typeFilter });
+  const results = [];
+  for (const row of rows) {
+    const lesson = rowToMemoryItem(row);
+    if (lesson) {
+      results.push({ lesson, score: normalizeBm25Rank(row.rank) });
+    }
+  }
+  return results;
+}
 function getRetrievalStats(repoRoot) {
   const database = openDb(repoRoot);
   const rows = database.prepare("SELECT id, retrieval_count, last_retrieved FROM lessons").all();
@@ -2094,8 +2655,13 @@ async function loadSessionLessons(repoRoot, limit = DEFAULT_LIMIT2) {
 // src/memory/retrieval/plan.ts
 var DEFAULT_LIMIT3 = 5;
 async function retrieveForPlan(repoRoot, planText, limit = DEFAULT_LIMIT3) {
-  const scored = await searchVector(repoRoot, planText, { limit: limit * 2 });
-  const ranked = rankLessons(scored);
+  const candidateLimit = limit * CANDIDATE_MULTIPLIER;
+  const [vectorResults, keywordResults] = await Promise.all([
+    searchVector(repoRoot, planText, { limit: candidateLimit }),
+    searchKeywordScored(repoRoot, planText, candidateLimit)
+  ]);
+  const merged = mergeHybridResults(vectorResults, keywordResults, { minScore: MIN_HYBRID_SCORE });
+  const ranked = rankLessons(merged);
   const topLessons = ranked.slice(0, limit);
   if (topLessons.length > 0) {
     incrementRetrievalCount(repoRoot, topLessons.map((item) => item.lesson.id));
@@ -2118,6 +2684,135 @@ No relevant lessons found for this plan.`;
 ${lessonLines.join("\n")}`;
 }
 
+// src/memory/storage/sqlite-knowledge/index.ts
+init_connection();
+init_schema();
+
+// src/memory/storage/sqlite-knowledge/cache.ts
+init_connection();
+init_types();
+
+// src/memory/storage/sqlite-knowledge/search.ts
+init_connection();
+function rowToChunk(row) {
+  const chunk = {
+    id: row.id,
+    filePath: row.file_path,
+    startLine: row.start_line,
+    endLine: row.end_line,
+    contentHash: row.content_hash,
+    text: row.text,
+    updatedAt: row.updated_at
+  };
+  if (row.model !== null) {
+    chunk.model = row.model;
+  }
+  return chunk;
+}
+function searchChunksKeywordScored(repoRoot, query, limit) {
+  const database = openKnowledgeDb(repoRoot);
+  const sanitized = sanitizeFtsQuery(query);
+  if (sanitized === "") return [];
+  try {
+    const rows = database.prepare(
+      `SELECT c.*, fts.rank
+         FROM chunks c
+         JOIN chunks_fts fts ON c.rowid = fts.rowid
+         WHERE chunks_fts MATCH ?
+         ORDER BY fts.rank
+         LIMIT ?`
+    ).all(sanitized, limit);
+    return rows.map((row) => ({
+      chunk: rowToChunk(row),
+      score: normalizeBm25Rank(row.rank)
+    }));
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Unknown FTS5 error";
+    console.error(`[compound-agent] knowledge scored search error: ${message}`);
+    return [];
+  }
+}
+
+// src/memory/storage/sqlite-knowledge/index.ts
+init_sync();
+
+// src/index.ts
+init_chunking();
+init_indexing();
+
+// src/memory/knowledge/search.ts
+init_connection();
+var DEFAULT_KNOWLEDGE_LIMIT = 6;
+async function searchKnowledgeVector(repoRoot, query, options) {
+  const limit = options?.limit ?? DEFAULT_KNOWLEDGE_LIMIT;
+  const database = openKnowledgeDb(repoRoot);
+  const embRows = database.prepare("SELECT id, embedding FROM chunks WHERE embedding IS NOT NULL").all();
+  if (embRows.length === 0) return [];
+  const queryVector = await embedText(query);
+  const scored = [];
+  for (const row of embRows) {
+    const embFloat = new Float32Array(
+      row.embedding.buffer,
+      row.embedding.byteOffset,
+      row.embedding.byteLength / 4
+    );
+    scored.push({ id: row.id, score: cosineSimilarity(queryVector, embFloat) });
+  }
+  scored.sort((a, b) => b.score - a.score);
+  const topK = scored.slice(0, limit);
+  if (topK.length === 0) return [];
+  const placeholders = topK.map(() => "?").join(",");
+  const sql = `SELECT id, file_path, start_line, end_line, content_hash, text, model, updated_at FROM chunks WHERE id IN (${placeholders})`;
+  const dataRows = database.prepare(sql).all(...topK.map((r) => r.id));
+  const dataMap = new Map(dataRows.map((r) => [r.id, r]));
+  const results = [];
+  for (const { id, score } of topK) {
+    const row = dataMap.get(id);
+    if (!row) continue;
+    const chunk = {
+      id: row.id,
+      filePath: row.file_path,
+      startLine: row.start_line,
+      endLine: row.end_line,
+      contentHash: row.content_hash,
+      text: row.text,
+      updatedAt: row.updated_at
+    };
+    if (row.model !== null) {
+      chunk.model = row.model;
+    }
+    results.push({ item: chunk, score });
+  }
+  return results;
+}
+async function searchKnowledge(repoRoot, query, options) {
+  const limit = options?.limit ?? DEFAULT_KNOWLEDGE_LIMIT;
+  const candidateLimit = limit * CANDIDATE_MULTIPLIER;
+  const usability = await isModelUsable();
+  if (usability.usable) {
+    const [vectorResults, keywordResults2] = await Promise.all([
+      searchKnowledgeVector(repoRoot, query, { limit: candidateLimit }),
+      Promise.resolve(searchChunksKeywordScored(repoRoot, query, candidateLimit))
+    ]);
+    if (vectorResults.length === 0) {
+      return keywordResults2.map((k) => ({ item: k.chunk, score: k.score })).slice(0, limit);
+    }
+    const genericKw = keywordResults2.map((k) => ({
+      item: k.chunk,
+      score: k.score
+    }));
+    const merged = mergeHybridScores(
+      vectorResults,
+      genericKw,
+      (item) => item.id,
+      { limit, minScore: MIN_HYBRID_SCORE }
+    );
+    return merged;
+  }
+  const keywordResults = searchChunksKeywordScored(repoRoot, query, limit);
+  return keywordResults.map((k) => ({ item: k.chunk, score: k.score }));
+}
+
 // src/audit/checks/lessons.ts
 async function checkLessons(repoRoot) {
   const { items } = await readMemoryItems(repoRoot);
@@ -2445,6 +3140,22 @@ var COMPOUND_AGENT_HOOK_BLOCK = `
 # Compound Agent pre-commit hook (appended)
 npx ca hooks run pre-commit
 `;
+var POST_COMMIT_HOOK_TEMPLATE = `#!/bin/sh
+# Compound Agent post-commit hook
+# Auto-indexes docs/ when documentation files change
+
+# Check if any docs/ files were modified in this commit
+if git diff-tree --no-commit-id --name-only -r HEAD | grep -q '^docs/'; then
+  npx ca -q index-docs 2>/dev/null &
+fi
+`;
+var POST_COMMIT_HOOK_MARKER = "# Compound Agent post-commit hook";
+var COMPOUND_AGENT_POST_COMMIT_BLOCK = `
+# Compound Agent post-commit hook (appended)
+if git diff-tree --no-commit-id --name-only -r HEAD | grep -q '^docs/'; then
+  npx ca -q index-docs 2>/dev/null &
+fi
+`;
 var CLAUDE_HOOK_MARKERS = [
   "ca prime",
   "ca load-session",
@@ -2457,7 +3168,8 @@ var CLAUDE_HOOK_MARKERS = [
   "ca hooks run stop-audit",
   // v1.2.9 canonical names
   "ca hooks run post-read",
-  "ca hooks run phase-audit"
+  "ca hooks run phase-audit",
+  "ca index-docs"
 ];
 var CLAUDE_HOOK_CONFIG = {
   matcher: "",
@@ -2555,6 +3267,7 @@ This project uses compound-agent for session memory via **CLI commands**.
 | Command | Purpose |
 |---------|---------|
 | \`npx ca search "query"\` | Search lessons - use BEFORE architectural decisions |
+| \`npx ca knowledge "query"\` | Search docs knowledge - use BEFORE architectural decisions |
 | \`npx ca learn "insight"\` | Capture lessons - use AFTER corrections or discoveries |
 | \`npx ca list\` | List all stored lessons |
 | \`npx ca show <id>\` | Show details of a specific lesson |
@@ -2562,7 +3275,7 @@ This project uses compound-agent for session memory via **CLI commands**.
 
 ### Mandatory Recall
 
-You MUST call \`npx ca search\` BEFORE:
+You MUST call \`npx ca search\` and \`npx ca knowledge\` BEFORE:
 - Architectural decisions or complex planning
 - Patterns you've implemented before in this repo
 - After user corrections ("actually...", "wrong", "use X instead")
@@ -2612,7 +3325,7 @@ var PLUGIN_MANIFEST = {
     name: "Nathan Delacr\xE9taz",
     url: "https://github.com/Nathandela"
   },
-  repository: "https://github.com/Nathandela/compound_agent",
+  repository: "https://github.com/Nathandela/learning_agent",
   license: "MIT",
   hooks: {
     SessionStart: [
@@ -2960,25 +3673,187 @@ async function ensureGitignore(repoRoot) {
 function formatError(command, code, message, remediation) {
   return `ERROR [${command}] ${code}: ${message} \u2014 ${remediation}`;
 }
-var STATE_DIR = ".claude";
-var STATE_FILE = ".ca-phase-state.json";
-var EPIC_ID_PATTERN2 = /^[a-zA-Z0-9_-]+$/;
-var PHASES = ["brainstorm", "plan", "work", "review", "compound"];
-var GATES = ["post-plan", "gate-3", "gate-4", "final"];
-var PHASE_INDEX = {
-  brainstorm: 1,
-  plan: 2,
-  work: 3,
-  review: 4,
-  compound: 5
-};
-function getStatePath(repoRoot) {
-  return join(repoRoot, STATE_DIR, STATE_FILE);
-}
-function isPhaseName(value) {
-  return typeof value === "string" && PHASES.includes(value);
-}
-function isGateName(value) {
+
+// src/setup/hooks-user-prompt.ts
+var CORRECTION_PATTERNS = [
+  /\bactually\b/i,
+  /\bno[,.]?\s/i,
+  /\bwrong\b/i,
+  /\bthat'?s not right\b/i,
+  /\bthat'?s incorrect\b/i,
+  /\buse .+ instead\b/i,
+  /\bi told you\b/i,
+  /\bi already said\b/i,
+  /\bnot like that\b/i,
+  /\byou forgot\b/i,
+  /\byou missed\b/i,
+  /\bstop\s*(,\s*)?(doing|using|that)\b/i,
+  /\bwait\s*(,\s*)?(that|no|wrong)\b/i
+];
+var HIGH_CONFIDENCE_PLANNING = [
+  /\bdecide\b/i,
+  /\bchoose\b/i,
+  /\bpick\b/i,
+  /\bwhich approach\b/i,
+  /\bwhat do you think\b/i,
+  /\bshould we\b/i,
+  /\bwould you\b/i,
+  /\bhow should\b/i,
+  /\bwhat'?s the best\b/i,
+  /\badd feature\b/i,
+  /\bset up\b/i
+];
+var LOW_CONFIDENCE_PLANNING = [
+  /\bimplement\b/i,
+  /\bbuild\b/i,
+  /\bcreate\b/i,
+  /\brefactor\b/i,
+  /\bfix\b/i,
+  /\bwrite\b/i,
+  /\bdevelop\b/i
+];
+var CORRECTION_REMINDER = "Remember: You have memory tools available - `npx ca learn` to save insights, `npx ca search` to find past solutions.";
+var PLANNING_REMINDER = "If you're uncertain or hesitant, remember your memory tools: `npx ca search` may have relevant context from past sessions.";
+function detectCorrection(prompt) {
+  return CORRECTION_PATTERNS.some((pattern) => pattern.test(prompt));
+}
+function detectPlanning(prompt) {
+  if (HIGH_CONFIDENCE_PLANNING.some((pattern) => pattern.test(prompt))) {
+    return true;
+  }
+  const lowMatches = LOW_CONFIDENCE_PLANNING.filter((pattern) => pattern.test(prompt));
+  return lowMatches.length >= 2;
+}
+function processUserPrompt(prompt) {
+  if (detectCorrection(prompt)) {
+    return {
+      hookSpecificOutput: {
+        hookEventName: "UserPromptSubmit",
+        additionalContext: CORRECTION_REMINDER
+      }
+    };
+  }
+  if (detectPlanning(prompt)) {
+    return {
+      hookSpecificOutput: {
+        hookEventName: "UserPromptSubmit",
+        additionalContext: PLANNING_REMINDER
+      }
+    };
+  }
+  return {};
+}
+var SAME_TARGET_THRESHOLD = 2;
+var TOTAL_FAILURE_THRESHOLD = 3;
+var STATE_FILE_NAME = ".ca-failure-state.json";
+var STATE_MAX_AGE_MS = 60 * 60 * 1e3;
+var failureCount = 0;
+var lastFailedTarget = null;
+var sameTargetCount = 0;
+function defaultState() {
+  return { count: 0, lastTarget: null, sameTargetCount: 0, timestamp: Date.now() };
+}
+function readFailureState(stateDir) {
+  try {
+    const filePath = join(stateDir, STATE_FILE_NAME);
+    if (!existsSync(filePath)) return defaultState();
+    const raw = readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (Date.now() - parsed.timestamp > STATE_MAX_AGE_MS) return defaultState();
+    return parsed;
+  } catch {
+    return defaultState();
+  }
+}
+function writeFailureState(stateDir, state) {
+  try {
+    const filePath = join(stateDir, STATE_FILE_NAME);
+    writeFileSync(filePath, JSON.stringify(state), "utf-8");
+  } catch {
+  }
+}
+function deleteStateFile(stateDir) {
+  try {
+    const filePath = join(stateDir, STATE_FILE_NAME);
+    if (existsSync(filePath)) unlinkSync(filePath);
+  } catch {
+  }
+}
+var FAILURE_TIP = "Tip: Multiple failures detected. `npx ca search` may have solutions for similar issues.";
+function resetFailureState(stateDir) {
+  failureCount = 0;
+  lastFailedTarget = null;
+  sameTargetCount = 0;
+  if (stateDir) deleteStateFile(stateDir);
+}
+function getFailureTarget(toolName, toolInput) {
+  if (toolName === "Bash" && typeof toolInput.command === "string") {
+    const trimmed = toolInput.command.trim();
+    const firstSpace = trimmed.indexOf(" ");
+    return firstSpace === -1 ? trimmed : trimmed.slice(0, firstSpace);
+  }
+  if ((toolName === "Edit" || toolName === "Write") && typeof toolInput.file_path === "string") {
+    return toolInput.file_path;
+  }
+  return null;
+}
+function processToolFailure(toolName, toolInput, stateDir) {
+  if (stateDir) {
+    const persisted = readFailureState(stateDir);
+    failureCount = persisted.count;
+    lastFailedTarget = persisted.lastTarget;
+    sameTargetCount = persisted.sameTargetCount;
+  }
+  failureCount++;
+  const target = getFailureTarget(toolName, toolInput);
+  if (target !== null && target === lastFailedTarget) {
+    sameTargetCount++;
+  } else {
+    sameTargetCount = 1;
+    lastFailedTarget = target;
+  }
+  const shouldShowTip = sameTargetCount >= SAME_TARGET_THRESHOLD || failureCount >= TOTAL_FAILURE_THRESHOLD;
+  if (shouldShowTip) {
+    resetFailureState(stateDir);
+    return {
+      hookSpecificOutput: {
+        hookEventName: "PostToolUseFailure",
+        additionalContext: FAILURE_TIP
+      }
+    };
+  }
+  if (stateDir) {
+    writeFailureState(stateDir, {
+      count: failureCount,
+      lastTarget: lastFailedTarget,
+      sameTargetCount,
+      timestamp: Date.now()
+    });
+  }
+  return {};
+}
+function processToolSuccess(stateDir) {
+  resetFailureState(stateDir);
+}
+var STATE_DIR = ".claude";
+var STATE_FILE = ".ca-phase-state.json";
+var PHASE_STATE_MAX_AGE_MS = 72 * 60 * 60 * 1e3;
+var PHASES = ["brainstorm", "plan", "work", "review", "compound"];
+var GATES = ["post-plan", "gate-3", "gate-4", "final"];
+var PHASE_INDEX = {
+  brainstorm: 1,
+  plan: 2,
+  work: 3,
+  review: 4,
+  compound: 5
+};
+function getStatePath(repoRoot) {
+  return join(repoRoot, STATE_DIR, STATE_FILE);
+}
+function isPhaseName(value) {
+  return typeof value === "string" && PHASES.includes(value);
+}
+function isGateName(value) {
   return typeof value === "string" && GATES.includes(value);
 }
 function isIsoDate(value) {
@@ -3021,7 +3896,13 @@ function getPhaseState(repoRoot) {
     if (!existsSync(path2)) return null;
     const raw = readFileSync(path2, "utf-8");
     const parsed = JSON.parse(raw);
-    return validatePhaseState(parsed) ? parsed : null;
+    if (!validatePhaseState(parsed)) return null;
+    const age = Date.now() - new Date(parsed.started_at).getTime();
+    if (age > PHASE_STATE_MAX_AGE_MS) {
+      cleanPhaseState(repoRoot);
+      return null;
+    }
+    return parsed;
   } catch {
     return null;
   }
@@ -3076,7 +3957,7 @@ function printStatusHuman(state) {
 }
 function registerPhaseSubcommands(phaseCheck, getDryRun, repoRoot) {
   phaseCheck.command("init <epic-id>").description("Initialize phase state for an epic").action((epicId) => {
-    if (!EPIC_ID_PATTERN2.test(epicId)) {
+    if (!EPIC_ID_PATTERN.test(epicId)) {
       console.error(`Invalid epic ID: "${epicId}"`);
       process.exitCode = 1;
       return;
@@ -3145,266 +4026,113 @@ function registerPhaseSubcommands(phaseCheck, getDryRun, repoRoot) {
     console.log("Phase state cleaned.");
   });
 }
-function registerPhaseCheckCommand(program2) {
-  const phaseCheck = program2.command("phase-check").description("Manage LFG phase state").option("--dry-run", "Show what would be done without making changes");
-  const getDryRun = () => phaseCheck.opts().dryRun ?? false;
-  const repoRoot = () => process.cwd();
-  registerPhaseSubcommands(phaseCheck, getDryRun, repoRoot);
-  program2.command("phase-clean").description("Remove phase state file (alias for `phase-check clean`)").action(() => {
-    cleanPhaseState(repoRoot());
-    console.log("Phase state cleaned.");
-  });
-}
-
-// src/setup/hooks-phase-guard.ts
-function processPhaseGuard(repoRoot, toolName, _toolInput) {
-  try {
-    if (toolName !== "Edit" && toolName !== "Write") return {};
-    const state = getPhaseState(repoRoot);
-    if (state === null || !state.lfg_active) return {};
-    const expectedSkillPath = `.claude/skills/compound/${state.current_phase}/SKILL.md`;
-    const skillRead = state.skills_read.includes(expectedSkillPath);
-    if (!skillRead) {
-      return {
-        hookSpecificOutput: {
-          hookEventName: "PreToolUse",
-          additionalContext: `PHASE GUARD WARNING: You are in LFG phase ${state.phase_index}/5 (${state.current_phase}) but have NOT read the skill file yet. Read ${expectedSkillPath} before continuing.`
-        }
-      };
-    }
-    return {};
-  } catch {
-    return {};
-  }
-}
-
-// src/setup/hooks-read-tracker.ts
-var SKILL_PATH_PATTERN = /(?:^|\/)\.claude\/skills\/compound\/([^/]+)\/SKILL\.md$/;
-function normalizePath(path2) {
-  return path2.replaceAll("\\", "/");
-}
-function toCanonicalSkillPath(filePath) {
-  const normalized = normalizePath(filePath);
-  const match = SKILL_PATH_PATTERN.exec(normalized);
-  if (!match?.[1]) return null;
-  return `.claude/skills/compound/${match[1]}/SKILL.md`;
-}
-function processReadTracker(repoRoot, toolName, toolInput) {
-  try {
-    if (toolName !== "Read") return {};
-    const state = getPhaseState(repoRoot);
-    if (state === null || !state.lfg_active) return {};
-    const filePath = typeof toolInput.file_path === "string" ? toolInput.file_path : null;
-    if (filePath === null) return {};
-    const canonicalPath = toCanonicalSkillPath(filePath);
-    if (canonicalPath === null) return {};
-    if (!state.skills_read.includes(canonicalPath)) {
-      updatePhaseState(repoRoot, {
-        skills_read: [...state.skills_read, canonicalPath]
-      });
-    }
-    return {};
-  } catch {
-    return {};
-  }
-}
-
-// src/setup/hooks-stop-audit.ts
-function hasTransitionEvidence(state) {
-  if (state.phase_index === 5) return true;
-  const nextPhase = PHASES[state.phase_index];
-  if (nextPhase === void 0) return false;
-  const nextSkillPath = `.claude/skills/compound/${nextPhase}/SKILL.md`;
-  return state.skills_read.includes(nextSkillPath);
-}
-function processStopAudit(repoRoot, stopHookActive = false) {
-  try {
-    if (stopHookActive) return {};
-    const state = getPhaseState(repoRoot);
-    if (state === null || !state.lfg_active) return {};
-    const expectedGate = expectedGateForPhase(state.phase_index);
-    if (expectedGate === null) return {};
-    if (state.gates_passed.includes(expectedGate)) return {};
-    if (!hasTransitionEvidence(state)) return {};
-    return {
-      continue: false,
-      stopReason: `PHASE GATE NOT VERIFIED: ${state.current_phase} requires gate '${expectedGate}'. Run: npx ca phase-check gate ${expectedGate}`
-    };
-  } catch {
-    return {};
-  }
-}
-
-// src/setup/hooks.ts
-var HOOK_FILE_MODE = 493;
-var CORRECTION_PATTERNS = [
-  /\bactually\b/i,
-  /\bno[,.]?\s/i,
-  /\bwrong\b/i,
-  /\bthat'?s not right\b/i,
-  /\bthat'?s incorrect\b/i,
-  /\buse .+ instead\b/i,
-  /\bi told you\b/i,
-  /\bi already said\b/i,
-  /\bnot like that\b/i,
-  /\byou forgot\b/i,
-  /\byou missed\b/i,
-  /\bstop\s*(,\s*)?(doing|using|that)\b/i,
-  /\bwait\s*(,\s*)?(that|no|wrong)\b/i
-];
-var HIGH_CONFIDENCE_PLANNING = [
-  /\bdecide\b/i,
-  /\bchoose\b/i,
-  /\bpick\b/i,
-  /\bwhich approach\b/i,
-  /\bwhat do you think\b/i,
-  /\bshould we\b/i,
-  /\bwould you\b/i,
-  /\bhow should\b/i,
-  /\bwhat'?s the best\b/i,
-  /\badd feature\b/i,
-  /\bset up\b/i
-];
-var LOW_CONFIDENCE_PLANNING = [
-  /\bimplement\b/i,
-  /\bbuild\b/i,
-  /\bcreate\b/i,
-  /\brefactor\b/i,
-  /\bfix\b/i,
-  /\bwrite\b/i,
-  /\bdevelop\b/i
-];
-var CORRECTION_REMINDER = "Remember: You have memory tools available - `npx ca learn` to save insights, `npx ca search` to find past solutions.";
-var PLANNING_REMINDER = "If you're uncertain or hesitant, remember your memory tools: `npx ca search` may have relevant context from past sessions.";
-function detectCorrection(prompt) {
-  return CORRECTION_PATTERNS.some((pattern) => pattern.test(prompt));
-}
-function detectPlanning(prompt) {
-  if (HIGH_CONFIDENCE_PLANNING.some((pattern) => pattern.test(prompt))) {
-    return true;
-  }
-  const lowMatches = LOW_CONFIDENCE_PLANNING.filter((pattern) => pattern.test(prompt));
-  return lowMatches.length >= 2;
-}
-function processUserPrompt(prompt) {
-  if (detectCorrection(prompt)) {
-    return {
-      hookSpecificOutput: {
-        hookEventName: "UserPromptSubmit",
-        additionalContext: CORRECTION_REMINDER
-      }
-    };
-  }
-  if (detectPlanning(prompt)) {
-    return {
-      hookSpecificOutput: {
-        hookEventName: "UserPromptSubmit",
-        additionalContext: PLANNING_REMINDER
-      }
-    };
-  }
-  return {};
-}
-var SAME_TARGET_THRESHOLD = 2;
-var TOTAL_FAILURE_THRESHOLD = 3;
-var STATE_FILE_NAME = ".ca-failure-state.json";
-var STATE_MAX_AGE_MS = 60 * 60 * 1e3;
-var failureCount = 0;
-var lastFailedTarget = null;
-var sameTargetCount = 0;
-function defaultState() {
-  return { count: 0, lastTarget: null, sameTargetCount: 0, timestamp: Date.now() };
-}
-function readFailureState(stateDir) {
-  try {
-    const filePath = join(stateDir, STATE_FILE_NAME);
-    if (!existsSync(filePath)) return defaultState();
-    const raw = readFileSync(filePath, "utf-8");
-    const parsed = JSON.parse(raw);
-    if (Date.now() - parsed.timestamp > STATE_MAX_AGE_MS) return defaultState();
-    return parsed;
-  } catch {
-    return defaultState();
-  }
+function registerPhaseCheckCommand(program2) {
+  const phaseCheck = program2.command("phase-check").description("Manage LFG phase state").option("--dry-run", "Show what would be done without making changes");
+  const getDryRun = () => phaseCheck.opts().dryRun ?? false;
+  const repoRoot = () => getRepoRoot();
+  registerPhaseSubcommands(phaseCheck, getDryRun, repoRoot);
+  program2.command("phase-clean").description("Remove phase state file (alias for `phase-check clean`)").action(() => {
+    cleanPhaseState(repoRoot());
+    console.log("Phase state cleaned.");
+  });
 }
-function writeFailureState(stateDir, state) {
+
+// src/setup/hooks-phase-guard.ts
+function processPhaseGuard(repoRoot, toolName, _toolInput) {
   try {
-    const filePath = join(stateDir, STATE_FILE_NAME);
-    writeFileSync(filePath, JSON.stringify(state), "utf-8");
+    if (toolName !== "Edit" && toolName !== "Write") return {};
+    const state = getPhaseState(repoRoot);
+    if (state === null || !state.lfg_active) return {};
+    const expectedSkillPath = `.claude/skills/compound/${state.current_phase}/SKILL.md`;
+    const skillRead = state.skills_read.includes(expectedSkillPath);
+    if (!skillRead) {
+      return {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          additionalContext: `PHASE GUARD WARNING: You are in LFG phase ${state.phase_index}/5 (${state.current_phase}) but have NOT read the skill file yet. Read ${expectedSkillPath} before continuing.`
+        }
+      };
+    }
+    return {};
   } catch {
+    return {};
   }
 }
-function deleteStateFile(stateDir) {
+
+// src/setup/hooks-read-tracker.ts
+var SKILL_PATH_PATTERN = /(?:^|\/)\.claude\/skills\/compound\/([^/]+)\/SKILL\.md$/;
+function normalizePath(path2) {
+  return path2.replaceAll("\\", "/");
+}
+function toCanonicalSkillPath(filePath) {
+  const normalized = normalizePath(filePath);
+  const match = SKILL_PATH_PATTERN.exec(normalized);
+  if (!match?.[1]) return null;
+  return `.claude/skills/compound/${match[1]}/SKILL.md`;
+}
+function processReadTracker(repoRoot, toolName, toolInput) {
   try {
-    const filePath = join(stateDir, STATE_FILE_NAME);
-    if (existsSync(filePath)) unlinkSync(filePath);
+    if (toolName !== "Read") return {};
+    const state = getPhaseState(repoRoot);
+    if (state === null || !state.lfg_active) return {};
+    const filePath = typeof toolInput.file_path === "string" ? toolInput.file_path : null;
+    if (filePath === null) return {};
+    const canonicalPath = toCanonicalSkillPath(filePath);
+    if (canonicalPath === null) return {};
+    if (!state.skills_read.includes(canonicalPath)) {
+      updatePhaseState(repoRoot, {
+        skills_read: [...state.skills_read, canonicalPath]
+      });
+    }
+    return {};
   } catch {
+    return {};
   }
 }
-var FAILURE_TIP = "Tip: Multiple failures detected. `npx ca search` may have solutions for similar issues.";
-function resetFailureState(stateDir) {
-  failureCount = 0;
-  lastFailedTarget = null;
-  sameTargetCount = 0;
-  if (stateDir) deleteStateFile(stateDir);
-}
-function getFailureTarget(toolName, toolInput) {
-  if (toolName === "Bash" && typeof toolInput.command === "string") {
-    const trimmed = toolInput.command.trim();
-    const firstSpace = trimmed.indexOf(" ");
-    return firstSpace === -1 ? trimmed : trimmed.slice(0, firstSpace);
-  }
-  if ((toolName === "Edit" || toolName === "Write") && typeof toolInput.file_path === "string") {
-    return toolInput.file_path;
-  }
-  return null;
+
+// src/setup/hooks-stop-audit.ts
+function hasTransitionEvidence(state) {
+  if (state.phase_index === 5) return true;
+  const nextPhase = PHASES[state.phase_index];
+  if (nextPhase === void 0) return false;
+  const nextSkillPath = `.claude/skills/compound/${nextPhase}/SKILL.md`;
+  return state.skills_read.includes(nextSkillPath);
 }
-function processToolFailure(toolName, toolInput, stateDir) {
-  if (stateDir) {
-    const persisted = readFailureState(stateDir);
-    failureCount = persisted.count;
-    lastFailedTarget = persisted.lastTarget;
-    sameTargetCount = persisted.sameTargetCount;
-  }
-  failureCount++;
-  const target = getFailureTarget(toolName, toolInput);
-  if (target !== null && target === lastFailedTarget) {
-    sameTargetCount++;
-  } else {
-    sameTargetCount = 1;
-    lastFailedTarget = target;
-  }
-  const shouldShowTip = sameTargetCount >= SAME_TARGET_THRESHOLD || failureCount >= TOTAL_FAILURE_THRESHOLD;
-  if (shouldShowTip) {
-    resetFailureState(stateDir);
+function processStopAudit(repoRoot, stopHookActive = false) {
+  try {
+    if (stopHookActive) return {};
+    const state = getPhaseState(repoRoot);
+    if (state === null || !state.lfg_active) return {};
+    const expectedGate = expectedGateForPhase(state.phase_index);
+    if (expectedGate === null) return {};
+    if (state.gates_passed.includes(expectedGate)) return {};
+    if (!hasTransitionEvidence(state)) return {};
     return {
-      hookSpecificOutput: {
-        hookEventName: "PostToolUseFailure",
-        additionalContext: FAILURE_TIP
-      }
+      continue: false,
+      stopReason: `PHASE GATE NOT VERIFIED: ${state.current_phase} requires gate '${expectedGate}'. Run: npx ca phase-check gate ${expectedGate}`
     };
+  } catch {
+    return {};
   }
-  if (stateDir) {
-    writeFailureState(stateDir, {
-      count: failureCount,
-      lastTarget: lastFailedTarget,
-      sameTargetCount,
-      timestamp: Date.now()
-    });
-  }
-  return {};
-}
-function processToolSuccess(stateDir) {
-  resetFailureState(stateDir);
 }
+
+// src/setup/hooks.ts
+var HOOK_FILE_MODE = 493;
 function hasCompoundAgentHook(content) {
   return content.includes(HOOK_MARKER);
 }
 async function getGitHooksDir(repoRoot) {
-  const gitDir = join(repoRoot, ".git");
-  if (!existsSync(gitDir)) {
+  const gitPath = join(repoRoot, ".git");
+  if (!existsSync(gitPath)) {
     return null;
   }
+  let gitDir = gitPath;
+  if (lstatSync(gitPath).isFile()) {
+    const content = readFileSync(gitPath, "utf-8").trim();
+    const match = /^gitdir:\s*(.+)$/.exec(content);
+    if (!match?.[1]) return null;
+    gitDir = resolve(repoRoot, match[1]);
+  }
   const configPath2 = join(gitDir, "config");
   if (existsSync(configPath2)) {
     const config = await readFile(configPath2, "utf-8");
@@ -3477,6 +4205,36 @@ async function installPreCommitHook(repoRoot) {
   chmodSync(hookPath, HOOK_FILE_MODE);
   return { status: "installed" };
 }
+async function installPostCommitHook(repoRoot) {
+  const gitHooksDir = await getGitHooksDir(repoRoot);
+  if (!gitHooksDir) {
+    return { status: "not_git_repo" };
+  }
+  await mkdir(gitHooksDir, { recursive: true });
+  const hookPath = join(gitHooksDir, "post-commit");
+  if (existsSync(hookPath)) {
+    const content = await readFile(hookPath, "utf-8");
+    if (content.includes(POST_COMMIT_HOOK_MARKER)) {
+      return { status: "already_installed" };
+    }
+    const lines = content.split("\n");
+    const exitLineIndex = findFirstTopLevelExitLine(lines);
+    let newContent;
+    if (exitLineIndex === -1) {
+      newContent = content.trimEnd() + "\n" + COMPOUND_AGENT_POST_COMMIT_BLOCK;
+    } else {
+      const before = lines.slice(0, exitLineIndex);
+      const after = lines.slice(exitLineIndex);
+      newContent = before.join("\n") + COMPOUND_AGENT_POST_COMMIT_BLOCK + after.join("\n");
+    }
+    await writeFile(hookPath, newContent, "utf-8");
+    chmodSync(hookPath, HOOK_FILE_MODE);
+    return { status: "appended" };
+  }
+  await writeFile(hookPath, POST_COMMIT_HOOK_TEMPLATE, "utf-8");
+  chmodSync(hookPath, HOOK_FILE_MODE);
+  return { status: "installed" };
+}
 async function readStdin() {
   const chunks = [];
   for await (const chunk of process.stdin) {
@@ -3506,7 +4264,7 @@ async function runPostToolFailureHook() {
       console.log(JSON.stringify({}));
       return;
     }
-    const stateDir = join(process.cwd(), ".claude");
+    const stateDir = join(getRepoRoot(), ".claude");
     const result = processToolFailure(data.tool_name, data.tool_input ?? {}, stateDir);
     console.log(JSON.stringify(result));
   } catch {
@@ -3516,7 +4274,7 @@ async function runPostToolFailureHook() {
 async function runPostToolSuccessHook() {
   try {
     await readStdin();
-    const stateDir = join(process.cwd(), ".claude");
+    const stateDir = join(getRepoRoot(), ".claude");
     processToolSuccess(stateDir);
     console.log(JSON.stringify({}));
   } catch {
@@ -3531,7 +4289,7 @@ async function runToolHook(processor) {
       console.log(JSON.stringify({}));
       return;
     }
-    console.log(JSON.stringify(processor(process.cwd(), data.tool_name, data.tool_input ?? {})));
+    console.log(JSON.stringify(processor(getRepoRoot(), data.tool_name, data.tool_input ?? {})));
   } catch {
     console.log(JSON.stringify({}));
   }
@@ -3540,7 +4298,7 @@ async function runStopAuditHook() {
   try {
     const input = await readStdin();
     const data = JSON.parse(input);
-    console.log(JSON.stringify(processStopAudit(process.cwd(), data.stop_hook_active ?? false)));
+    console.log(JSON.stringify(processStopAudit(getRepoRoot(), data.stop_hook_active ?? false)));
   } catch {
     console.log(JSON.stringify({}));
   }
@@ -3803,6 +4561,10 @@ Analyze the current session's work context: what was accomplished, what problems
 7. Summarize the work context for lesson extraction
 8. For large diffs spanning multiple modules, spawn opus subagents to analyze each module in parallel. Merge findings before sharing.
 
+## Literature
+- Consult \`docs/compound/research/learning-systems/\` for knowledge compounding theory and context analysis methodology
+- Run \`npx ca knowledge "context analysis work review"\` for indexed knowledge
+
 ## Collaboration
 Share findings with lesson-extractor via direct message so it can extract actionable lessons from the context. Pass results to other compound agents as needed.
 
@@ -3841,6 +4603,10 @@ Share findings with pattern-matcher and solution-writer via direct message so th
 ## Deployment
 AgentTeam member in the **compound** phase. Spawned via TeamCreate. Communicate with teammates via SendMessage.
 
+## Literature
+- Consult \`docs/compound/research/learning-systems/\` for lesson extraction methodology and knowledge representation
+- Run \`npx ca knowledge "lesson extraction knowledge management"\` for indexed knowledge
+
 ## Output Format
 Per lesson:
 - **Insight**: The actionable directive
@@ -3874,6 +4640,10 @@ Share classifications with solution-writer via direct message so it knows which
 ## Deployment
 AgentTeam member in the **compound** phase. Spawned via TeamCreate. Communicate with teammates via SendMessage.
 
+## Literature
+- Consult \`docs/compound/research/learning-systems/\` for deduplication strategies and knowledge graph methodology
+- Run \`npx ca knowledge "pattern matching deduplication"\` for indexed knowledge
+
 ## Output Format
 Per lesson:
 - **Classification**: New / Duplicate / Reinforcement / Contradiction
@@ -3903,6 +4673,10 @@ Transform approved lessons into properly formatted memory items that follow the
 5. Set supersedes or related links when the lesson updates existing knowledge
 6. Store via \`npx ca learn\`
 
+## Literature
+- Consult \`docs/compound/research/learning-systems/\` for knowledge representation and lesson schema design
+- Run \`npx ca knowledge "knowledge storage representation"\` for indexed knowledge
+
 ## Collaboration
 Share findings with other agents via direct message to communicate storage outcomes. Collaborate with pattern-matcher on borderline classifications.
 
@@ -3936,6 +4710,10 @@ Write comprehensive failing tests that define expected behavior before any imple
 7. Do NOT mock the thing being tested
 8. For multiple test files, spawn opus subagents to write tests in parallel (1 subagent per test file or module). Coordinate to avoid duplicate test setup.
 
+## Literature
+- Consult \`docs/compound/research/tdd/\` for test-first development evidence and methodology
+- Run \`npx ca knowledge "TDD test design"\` for indexed knowledge on testing patterns
+
 ## Memory Integration
 Run \`npx ca search\` with the task description before writing tests. Look for known patterns, edge cases, and past mistakes relevant to the feature area.
 
@@ -3970,6 +4748,10 @@ Write the minimum code necessary to make failing tests pass. Follow the TDD gree
 7. After all tests pass, look for obvious refactoring opportunities
 8. For multiple implementation files, spawn opus subagents to implement in parallel (1 subagent per module). Coordinate on shared interfaces via SendMessage.
 
+## Literature
+- Consult \`docs/compound/research/tdd/\` for TDD green-phase methodology and minimal implementation strategies
+- Run \`npx ca knowledge "TDD implementation"\` for indexed knowledge on implementation patterns
+
 ## Memory Integration
 Run \`npx ca search\` with the task description for known patterns, solutions, and implementation approaches relevant to the feature area.
 
@@ -4070,6 +4852,10 @@ Review code changes for security vulnerabilities including OWASP top 10, injecti
 7. Check dependency versions for known CVEs
 8. For large diffs, spawn opus subagents to review different file groups in parallel (e.g., 1 per module). Merge findings and deduplicate.
 
+## Literature
+- Consult \`docs/compound/research/code-review/\` for systematic review methodology and severity classification
+- Run \`npx ca knowledge "security review OWASP"\` for indexed security knowledge
+
 ## Collaboration
 Share cross-cutting findings via SendMessage: security issues impacting architecture go to architecture-reviewer; secrets in test fixtures go to test-coverage-reviewer.
 
@@ -4101,6 +4887,10 @@ Review code for architectural consistency, pattern compliance, module boundary i
 6. Check that dependencies flow in the correct direction
 7. For changes spanning multiple modules, spawn opus subagents to review each module boundary in parallel.
 
+## Literature
+- Consult \`docs/compound/research/code-review/\` for systematic review methodology and architectural assessment frameworks
+- Run \`npx ca knowledge "architecture module design"\` for indexed knowledge on design patterns
+
 ## Collaboration
 Share cross-cutting findings via SendMessage: architecture issues with performance implications go to performance-reviewer; structural violations creating security risks go to security-reviewer.
 
@@ -4131,6 +4921,10 @@ Review code for performance bottlenecks, algorithmic complexity issues, unnecess
 6. Verify resources are properly closed/released
 7. For multiple hot paths, spawn opus subagents to profile different modules in parallel.
 
+## Literature
+- Consult \`docs/compound/research/code-review/\` for systematic performance analysis frameworks
+- Run \`npx ca knowledge "performance review"\` for indexed knowledge on performance patterns
+
 ## Collaboration
 Share cross-cutting findings via SendMessage: performance issues needing test coverage go to test-coverage-reviewer; performance fixes requiring architectural changes go to architecture-reviewer.
 
@@ -4162,6 +4956,11 @@ Review tests for meaningful assertions, edge case coverage, and absence of cargo
 7. Ensure property-based tests exist for pure functions
 8. For many test files, spawn opus subagents to review test files in parallel (1 per test file).
 
+## Literature
+- Consult \`docs/compound/research/tdd/\` for test quality assessment and coverage methodology
+- Consult \`docs/compound/research/property-testing/\` for property-based testing theory
+- Run \`npx ca knowledge "test coverage quality"\` for indexed knowledge
+
 ## Collaboration
 Share cross-cutting findings via SendMessage: cargo-cult tests hiding security issues go to security-reviewer; unnecessary test complexity goes to simplicity-reviewer.
 
@@ -4192,6 +4991,10 @@ Review code for unnecessary complexity, over-engineering, premature abstraction,
 5. Flag feature flags or config for single-use cases
 6. Verify no "just in case" code exists
 
+## Literature
+- Consult \`docs/compound/research/code-review/\` for over-engineering detection and YAGNI assessment methodology
+- Run \`npx ca knowledge "simplicity over-engineering"\` for indexed knowledge
+
 ## Collaboration
 Share cross-cutting findings via SendMessage: over-engineering obscuring security concerns goes to security-reviewer; premature abstractions creating wrong module boundaries goes to architecture-reviewer.
 
@@ -4229,6 +5032,10 @@ Cluster similar lessons from memory and synthesize them into testable CCT (Compo
 6. Skip singleton lessons (not enough signal to form a pattern)
 7. For many clusters, spawn opus subagents to synthesize patterns from different clusters in parallel.
 
+## Literature
+- Consult \`docs/compound/research/learning-systems/\` for knowledge compounding theory and pattern synthesis
+- Run \`npx ca knowledge "lesson clustering compounding"\` for indexed knowledge on learning systems
+
 ## Collaboration
 Share synthesized patterns with the team lead via direct message for review.
 
@@ -4321,6 +5128,11 @@ invariant-designer -> **CCT Subagent** -> test-first-enforcer
    - Priority (REQUIRED vs SUGGESTED)
 5. Pass requirements to test-first-enforcer for inclusion
 
+## Literature
+- Consult \`docs/compound/research/tdd/\` for corrective testing theory and mistake-driven test design
+- Consult \`docs/compound/research/learning-systems/\` for pattern clustering and knowledge synthesis methodology
+- Run \`npx ca knowledge "corrective testing patterns"\` for indexed knowledge
+
 ## Deployment
 Subagent in the TDD pipeline. Return findings directly to the caller.
 
@@ -4354,6 +5166,10 @@ module-boundary-reviewer -> **Drift Detector** -> implementation-reviewer
 5. Use \`npx ca search\` for past architectural decisions that may apply
 6. Report any deviation, even if the implementation "works"
 
+## Literature
+- Consult \`docs/compound/research/property-testing/\` for invariant-driven development and constraint verification
+- Run \`npx ca knowledge "invariant drift detection"\` for indexed knowledge on drift patterns
+
 ## Deployment
 Subagent in the TDD pipeline. Return findings directly to the caller.
 
@@ -4472,6 +5288,19 @@ $ARGUMENTS
 # Test Clean
 
 **MANDATORY FIRST STEP -- NON-NEGOTIABLE**: Use the Read tool to open and read \`.claude/skills/compound/test-cleaner/SKILL.md\` NOW. Do NOT proceed until you have read the complete skill file. It contains the full workflow you must follow.
+`,
+  "get-a-phd.md": `---
+name: compound:get-a-phd
+description: Deep PhD-level research for working subagents
+argument-hint: "<focus area or epic ID>"
+---
+$ARGUMENTS
+
+# Get a PhD
+
+**MANDATORY FIRST STEP -- NON-NEGOTIABLE**: Use the Read tool to open and read \`.claude/skills/compound/researcher/SKILL.md\` NOW. Do NOT proceed until you have read the complete skill file.
+
+Then: scan docs/compound/research/ for gaps, propose topics via AskUserQuestion, spawn parallel researcher subagents.
 `,
   // =========================================================================
   // Utility commands (kept: learn, prime)
@@ -4578,6 +5407,8 @@ npx ca doctor
     index.jsonl                # Memory items (git-tracked source of truth)
   .cache/
     lessons.sqlite             # Rebuildable search index (.gitignore)
+docs/compound/
+  research/                    # PhD-level research docs for agent knowledge
 \`\`\`
 
 ---
@@ -4588,6 +5419,7 @@ npx ca doctor
 |------|---------|
 | Capture a lesson | \`npx ca learn "insight" --trigger "what happened"\` |
 | Search memory | \`npx ca search "keywords"\` |
+| Search docs knowledge | \`npx ca knowledge "query"\` |
 | Check plan against memory | \`npx ca check-plan --plan "description"\` |
 | View stats | \`npx ca stats\` |
 | Run full workflow | \`/compound:lfg <epic-id>\` |
@@ -4942,6 +5774,14 @@ Skills are instructions that Claude reads before executing each phase. They live
 
 **What it does**: Validates the epic, runs \`npx ca worktree create <epic-id>\`, verifies output, and informs the user they can proceed with \`/compound:lfg\`.
 
+### \`/compound:get-a-phd\`
+
+**Purpose**: Conduct deep, PhD-level research to build knowledge for working subagents.
+
+**When invoked**: When agents need domain knowledge not yet covered in \`docs/compound/research/\`.
+
+**What it does**: Analyzes beads epics for knowledge gaps, checks existing docs coverage, proposes research topics for user confirmation, spawns parallel researcher subagents, and stores output at \`docs/compound/research/<topic>/<slug>.md\`.
+
 ---
 
 ## Skill invocation
@@ -4956,6 +5796,7 @@ Skills are invoked as Claude Code slash commands:
 /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
+/compound:get-a-phd <focus>       # Deep research for agent knowledge
 \`\`\`
 
 Each skill reads its SKILL.md file from \`.claude/skills/compound/<phase>/SKILL.md\` at invocation time. Skills are never executed from memory.
@@ -5032,6 +5873,7 @@ Compound-agent installs five hooks into \`.claude/settings.json\`:
 
 \`\`\`bash
 npx ca search "feature area keywords"
+npx ca knowledge "architecture topic"
 npx ca check-plan --plan "description of what you are about to implement"
 \`\`\`
 
@@ -5135,7 +5977,7 @@ Explore the problem space before committing to a solution. This phase produces a
 
 ## Methodology
 1. Ask "why" before "how" -- understand the real problem
-2. Search memory with \`npx ca search\` for similar past features and known constraints
+2. Search memory with \`npx ca search\` and docs with \`npx ca knowledge "relevant topic"\` for similar past features and known constraints
 3. Spawn **subagents** via Task tool in parallel for research (lightweight, no inter-agent coordination):
    - Available agents: \`.claude/agents/compound/repo-analyst.md\`, \`memory-analyst.md\`
    - Or use \`subagent_type: Explore\` for ad-hoc research
@@ -5149,7 +5991,7 @@ Explore the problem space before committing to a solution. This phase produces a
 10. Auto-create ADR files in \`docs/decisions/\` for significant decisions (lightweight: Status, Context, Decision, Consequences)
 
 ## Memory Integration
-- Run \`npx ca search\` with relevant keywords before generating approaches
+- Run \`npx ca search\` and \`npx ca knowledge "relevant topic"\` with relevant keywords before generating approaches
 - Look for past architectural decisions, pitfalls, and preferences
 - If the problem domain matches past work, review those lessons first
 
@@ -5191,7 +6033,7 @@ Create a concrete implementation plan by decomposing work into small, testable t
 
 ## Methodology
 1. Review brainstorm output for decisions and open questions
-2. Search memory with \`npx ca search\` for architectural patterns and past mistakes
+2. Search memory with \`npx ca search\` and docs with \`npx ca knowledge "relevant topic"\` for architectural patterns and past mistakes
 3. Spawn **subagents** via Task tool in parallel for research (lightweight, no inter-agent coordination):
    - Available agents: \`.claude/agents/compound/repo-analyst.md\`, \`memory-analyst.md\`
    - For complex features, deploy MULTIPLE analysts per domain area
@@ -5207,7 +6049,7 @@ Create a concrete implementation plan by decomposing work into small, testable t
 12. Run \`npx ca worktree wire-deps <epic-id>\` to connect merge dependencies (graceful no-op if no worktree is active)
 
 ## Memory Integration
-- Run \`npx ca search\` for patterns related to the feature area
+- Run \`npx ca search\` and \`npx ca knowledge "relevant topic"\` for patterns related to the feature area
 - Look for past planning mistakes (missing dependencies, unclear criteria)
 - Check for preferred architectural patterns in this codebase
 
@@ -5488,7 +6330,7 @@ description: Deep research producing structured survey documents for informed de
 # Researcher Skill
 
 ## Overview
-Conduct deep research on a topic and produce a structured survey document following the project's research template. This skill spawns parallel research subagents to gather comprehensive information, then synthesizes findings into a PhD-depth document stored in \`docs/research/\`.
+Conduct deep research on a topic and produce a structured survey document following the project's research template. This skill spawns parallel research subagents to gather comprehensive information, then synthesizes findings into a PhD-depth document stored in \`docs/compound/research/\`.
 
 ## Methodology
 1. Identify the research question, scope, and exclusions
@@ -5509,16 +6351,16 @@ Conduct deep research on a topic and produce a structured survey document follow
    - Conclusion
    - References (full citations)
    - Practitioner Resources (annotated tools/repos)
-6. Store output at \`docs/research/<topic-slug>.md\` (kebab-case filename)
+6. Store output at \`docs/compound/research/<topic-slug>.md\` (kebab-case filename)
 7. Report key findings back for upstream skill (brainstorm/plan) to act on
 
 ## Memory Integration
 - Run \`npx ca search\` with topic keywords before starting research
-- Check for existing research docs in \`docs/research/\` that overlap
+- Check for existing research docs in \`docs/compound/research/\` that overlap
 - After completion, key findings can be captured via \`npx ca learn\`
 
 ## Docs Integration
-- Scan \`docs/research/\` for prior survey documents on related topics
+- Scan \`docs/compound/research/\` for prior survey documents on related topics
 - Check \`docs/decisions/\` for ADRs that inform or constrain the research scope
 - Reference existing project docs as primary sources where relevant
 
@@ -5613,7 +6455,7 @@ For each phase:
 1. Announce: "[Phase N/5] PHASE_NAME"
 2. Start state: \`npx ca phase-check start <phase>\`
 3. Read the phase skill file (see above)
-4. Run \`npx ca search\` with the current goal -- display results before proceeding
+4. Run \`npx ca search\` and \`npx ca knowledge\` with the current goal -- display results before proceeding
 5. Execute the phase following the skill instructions
 6. Update epic state: \`bd update <epic-id> --notes="Phase: NAME COMPLETE | Next: NEXT"\`
 7. Verify phase gate before proceeding to the next phase
@@ -5850,6 +6692,47 @@ async function installDocTemplates(repoRoot) {
   }
   return created;
 }
+async function installResearchDocs(repoRoot) {
+  const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+  const srcDir = join(pkgRoot, "docs", "research");
+  if (!existsSync(srcDir)) {
+    return false;
+  }
+  const destDir = join(repoRoot, "docs", "compound", "research");
+  await mkdir(destDir, { recursive: true });
+  let created = false;
+  async function copyDir(src, dest) {
+    const entries = await readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+      const srcPath = join(src, entry.name);
+      const destPath = join(dest, entry.name);
+      if (entry.isDirectory()) {
+        await mkdir(destPath, { recursive: true });
+        await copyDir(srcPath, destPath);
+      } else if (!existsSync(destPath) && entry.name.endsWith(".md")) {
+        let content = await readFile(srcPath, "utf-8");
+        if (entry.name === "index.md") {
+          const patched = content.replace(
+            /^# .*/m,
+            "$&\n\n> Shipped by compound-agent. Source: `docs/research/` in the compound-agent package."
+          );
+          content = patched !== content ? patched : `> Shipped by compound-agent.
+
+${content}`;
+        }
+        await writeFile(destPath, content, "utf-8");
+        created = true;
+      }
+    }
+  }
+  try {
+    await copyDir(srcDir, destDir);
+  } catch (err) {
+    console.error(`Warning: Could not install research docs: ${err.message}`);
+    return false;
+  }
+  return created;
+}
 var REQUIRED_BUILD_DEPS = ["better-sqlite3", "node-llama-cpp"];
 async function ensurePnpmBuildConfig(repoRoot) {
   const lockPath = join(repoRoot, "pnpm-lock.yaml");
@@ -6115,6 +6998,10 @@ async function runSetup(options) {
   if (!options.skipHooks) {
     gitHooks = (await installPreCommitHook(repoRoot)).status;
   }
+  let postCommitHook = "skipped";
+  if (!options.skipHooks) {
+    postCommitHook = (await installPostCommitHook(repoRoot)).status;
+  }
   const { hooks } = await configureClaudeSettings();
   const gitignore = await ensureGitignore(repoRoot);
   let modelStatus = "skipped";
@@ -6136,6 +7023,7 @@ async function runSetup(options) {
     agentsMd: agentsMdUpdated,
     hooks,
     gitHooks,
+    postCommitHook,
     model: modelStatus,
     pnpmConfig,
     beads,
@@ -6205,6 +7093,16 @@ async function runUpdate(repoRoot, dryRun) {
   const gitignore = dryRun ? { added: [] } : await ensureGitignore(repoRoot);
   return { updated, added, configUpdated, upgrade, gitignore };
 }
+var POST_COMMIT_STATUS_MSG = {
+  skipped: "Skipped (--skip-hooks)",
+  not_git_repo: "Skipped (not a git repository)",
+  installed: "Installed (auto-indexes docs/ on commit)",
+  appended: "Appended to existing post-commit hook",
+  already_installed: "Already configured"
+};
+function printPostCommitHookStatus(status) {
+  console.log(`  Post-commit hook: ${POST_COMMIT_STATUS_MSG[status]}`);
+}
 var MODEL_STATUS_MSG = {
   skipped: "Skipped (--skip-model)",
   downloaded: "Downloaded",
@@ -6224,6 +7122,7 @@ async function printSetupResult(result, quiet, repoRoot) {
   console.log(`  AGENTS.md: ${result.agentsMd ? "Updated" : "Already configured"}`);
   console.log(`  Claude hooks: ${result.hooks ? "Installed" : "Already configured"}`);
   printSetupGitHooksStatus(result.gitHooks);
+  printPostCommitHookStatus(result.postCommitHook);
   printPnpmConfigStatus(result.pnpmConfig);
   printGitignoreStatus(result.gitignore);
   console.log(`  Model: ${MODEL_STATUS_MSG[result.model]}`);
@@ -6531,6 +7430,7 @@ async function initAction(cmd, options) {
     await installPhaseSkills(repoRoot);
     await installAgentRoleSkills(repoRoot);
     await installDocTemplates(repoRoot);
+    await installResearchDocs(repoRoot);
   }
   let hookResult = null;
   if (!options.skipHooks) {
@@ -7174,6 +8074,7 @@ var TRUST_LANGUAGE_TEMPLATE = `# Compound Agent Active
 | Command | Purpose |
 |---------|---------|
 | \`npx ca search "query"\` | Search lessons - call BEFORE architectural decisions |
+| \`npx ca knowledge "query"\` | Search docs knowledge - use for architecture context |
 | \`npx ca learn "insight"\` | Capture lessons - call AFTER corrections or discoveries |
 
 ## Core Constraints
@@ -7186,7 +8087,7 @@ var TRUST_LANGUAGE_TEMPLATE = `# Compound Agent Active
 
 ## Retrieval Protocol
 
-You MUST call \`npx ca search\` BEFORE:
+You MUST call \`npx ca search\` and \`npx ca knowledge\` BEFORE:
 - Architectural decisions or complex planning
 - Implementing patterns you've done before in this repo
 
@@ -7675,47 +8576,50 @@ function registerVerifyGatesCommand(program2) {
 }
 
 // src/changelog-data.ts
-var CHANGELOG_RECENT = `## [1.3.3] - 2026-02-21
+var CHANGELOG_RECENT = `## [1.4.0] - 2026-02-22
 
-### Changed
+### Fixed
 
-- **Banner audio**: Rewritten as vaporwave composition with PolyBLEP anti-aliased sawtooth synthesis, biquad filters, Schroeder reverb, and delay. E minor ambiguity resolves to E major at bloom, synced 300ms ahead of the visual climax (neural brain lighting up). Post-animation reverb tail holds 1.8s for natural dissolution.
+- **Plugin manifest**: Corrected repository URL from \`compound_agent\` to \`learning_agent\`
 
-## [1.3.2] - 2026-02-21
+### Changed
 
-### Added
+- **Version consolidation**: Roll-up release of v1.3.7\u2013v1.3.9 production readiness fixes (test pipeline hardening, data integrity, two-phase vector search, FTS5 sanitization)
 
-- **Banner audio**: Pure TypeScript WAV synthesis 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
+## [1.3.9] - 2026-02-22
 
 ### 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
+- **Integration test pipeline reliability**: Moved \`pnpm build\` from vitest globalSetup to npm script pre-step, eliminating EPERM errors from tsx/IPC conflicts inside vitest's process
+- **Fail-fast globalSetup**: Missing \`dist/cli.js\` now throws a clear error instead of cascading 68+ test failures
+- **Integration pool isolation**: Changed from \`threads\` to \`forks\` for integration tests \u2014 proper process isolation for subprocess-spawning tests
+- **Timeout safety net**: Added \`testTimeout: 30_000\` to fallback vitest.config.ts, preventing 5s default under edge conditions
 
-### Changed
+## [1.3.8] - 2026-02-22
 
-- **\`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
+### Fixed
 
-## [1.3.1] - 2026-02-21
+- **Integration test reliability**: Dynamic assertion on workflow command count instead of hardcoded magic number; 30s test timeout for integration suite; conditional build in global-setup; 30s timeout on all bare \`execSync\` calls in init tests
+- **Data integrity**: Indexing pipeline wraps delete/upsert/hash-set in a single transaction for atomic file re-indexing
+- **FTS5 sanitization**: Extended regex to strip parentheses, colons, and braces in addition to existing special chars
+- **Safe JSON.parse**: \`rowToMemoryItem\` now uses \`safeJsonParse\` with fallbacks instead of bare \`JSON.parse\`
+- **ENOENT on schema migration**: \`unlinkSync\` in lessons DB wrapped in try/catch (matches knowledge DB pattern)
+- **Worktree hook support**: \`getGitHooksDir\` resolves \`.git\` file (\`gitdir:\` reference) in worktrees
 
-### Added
+### Changed
 
-- **\`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)
+- **Two-phase vector search**: Knowledge vector search loads only IDs + embeddings in phase 1, hydrates full text for top-k only in phase 2 (reduces memory from O(n * text) to O(n * embedding) + O(k * text))
+- **Deduplicated FTS5 search**: \`searchKeyword\` and \`searchKeywordScored\` share a single \`executeFtsQuery\` helper
+- **Removed redundant COUNT pre-checks**: FTS5 naturally returns empty on empty tables
+- **Extracted chunk count helpers**: \`getChunkCount\` / \`getChunkCountByFilePath\` replace raw SQL in \`knowledge.ts\` and \`indexing.ts\`
+- **Immutable extension sets**: \`SUPPORTED_EXTENSIONS\` typed as \`ReadonlySet\`; new \`CODE_EXTENSIONS\` constant replaces hardcoded array in chunking
+- **\`test:all\` builds first**: Script now runs \`pnpm build\` before model download and test run
+- **Test describe label**: Fixed misleading \`'when stop_hook_active is false'\` to match actual test condition
 
-### Changed
+### Added
 
-- **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\``;
+- \`filesErrored\` field in \`IndexResult\` to track file read failures during indexing
+- \`tsx\` added to devDependencies (was used but not declared)`;
 
 // src/commands/about.ts
 function registerAboutCommand(program2) {
@@ -7729,6 +8633,89 @@ function registerAboutCommand(program2) {
     console.log(CHANGELOG_RECENT);
   });
 }
+
+// src/memory/knowledge/index.ts
+init_chunking();
+init_types();
+init_indexing();
+
+// src/commands/knowledge.ts
+var MAX_DISPLAY_TEXT = 200;
+function registerKnowledgeCommand(program2) {
+  program2.command("knowledge <query>").description("Search docs knowledge base").option("-n, --limit <number>", "Maximum results", "6").action(async function(query, opts) {
+    const globalOpts = getGlobalOpts(this);
+    try {
+      let limit;
+      try {
+        limit = parseLimit(opts.limit, "limit");
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Invalid limit";
+        console.error(formatError("knowledge", "INVALID_LIMIT", message, "Use -n with a positive integer"));
+        process.exitCode = 1;
+        return;
+      }
+      const repoRoot = getRepoRoot();
+      openKnowledgeDb(repoRoot);
+      if (getChunkCount(repoRoot) === 0) {
+        try {
+          const { indexDocs: indexDocs2 } = await Promise.resolve().then(() => (init_indexing(), indexing_exports));
+          out.info("Knowledge base empty. Indexing docs...");
+          const result = await indexDocs2(repoRoot);
+          if (result.filesIndexed === 0) {
+            out.info("No docs found to index. Add docs/ directory or run: npx ca index-docs --help");
+            return;
+          }
+        } catch (indexErr) {
+          const msg = indexErr instanceof Error ? indexErr.message : "Unknown error";
+          out.info(`Auto-index failed (${msg}). Run manually: npx ca index-docs`);
+        }
+      }
+      const results = await searchKnowledge(repoRoot, query, { limit });
+      if (results.length === 0) {
+        out.info("No matching results found.");
+        return;
+      }
+      for (const r of results) {
+        const { filePath, startLine, endLine, text } = r.item;
+        const truncated = text.length > MAX_DISPLAY_TEXT ? text.slice(0, MAX_DISPLAY_TEXT) + "..." : text;
+        const displayText = truncated.replace(/\n/g, " ");
+        if (globalOpts.verbose) {
+          console.log(`[${filePath}:L${startLine}-L${endLine}] (score: ${r.score.toFixed(2)}) ${displayText}`);
+        } else {
+          console.log(`[${filePath}:L${startLine}-L${endLine}] ${displayText}`);
+        }
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      console.error(formatError("knowledge", "SEARCH_FAILED", message, "Check that docs are indexed"));
+      process.exitCode = 1;
+    } finally {
+      closeKnowledgeDb();
+    }
+  });
+}
+
+// src/commands/knowledge-index.ts
+function registerKnowledgeIndexCommand(program2) {
+  program2.command("index-docs").description("Index docs/ directory into knowledge base").option("--force", "Re-index all files (ignore cache)").action(async function(options) {
+    const repoRoot = getRepoRoot();
+    out.info("Indexing docs/ directory...");
+    try {
+      const result = await indexDocs(repoRoot, {
+        force: options.force
+      });
+      const skippedPart = result.filesSkipped > 0 ? ` (${result.filesSkipped} skipped)` : "";
+      const deletedPart = result.chunksDeleted > 0 ? `, ${result.chunksDeleted} deleted` : "";
+      const duration = (result.durationMs / 1e3).toFixed(1);
+      out.info(
+        `Indexed ${result.filesIndexed} file${result.filesIndexed !== 1 ? "s" : ""}${skippedPart}, ${result.chunksCreated} chunk${result.chunksCreated !== 1 ? "s" : ""} created${deletedPart}`
+      );
+      out.info(`Duration: ${duration}s`);
+    } finally {
+      closeKnowledgeDb();
+    }
+  });
+}
 function parseWorktreeList(raw) {
   const entries = [];
   let currentPath = "";
@@ -7767,13 +8754,16 @@ function runWorktreeCreate(epicId) {
   const mergeDesc = `INSTRUCTIONS: This task merges the worktree branch back to main. Worktree path: ${worktreePath}. Run \`pnpm exec ca worktree merge ${epicId}\` when all other blocking tasks are resolved.`;
   const bdOutput = execFileSync("bd", [
     "create",
+    "--silent",
     `--title=${mergeTitle}`,
     "--type=task",
     "--priority=1",
     `--description=${mergeDesc}`
-  ], { encoding: "utf-8" });
-  const idMatch = bdOutput.match(/(\S+)$/);
-  const mergeFullId = idMatch?.[1] ?? "";
+  ], {
+    encoding: "utf-8",
+    env: { ...process.env, BEADS_NO_DAEMON: "1" }
+  });
+  const mergeFullId = bdOutput.trim();
   if (!mergeFullId) {
     throw new Error("bd create returned no task ID");
   }
@@ -7934,12 +8924,16 @@ function addCreateCommand(wt) {
       const result = runWorktreeCreate(epicId);
       if (result.alreadyExists) {
         console.log(`Worktree already exists at ${result.worktreePath}`);
+        console.log(`  To use: cd ${result.worktreePath} && claude`);
         return;
       }
       console.log(`Worktree created:`);
       console.log(`  Path:       ${result.worktreePath}`);
       console.log(`  Branch:     ${result.branch}`);
       console.log(`  Merge task: ${result.mergeTaskId}`);
+      console.log("");
+      console.log("Next step: open a NEW Claude session with the worktree as primary directory:");
+      console.log(`  cd ${result.worktreePath} && claude`);
     } catch (err) {
       handleError(err);
     }
@@ -8263,7 +9257,7 @@ function registerCaptureCommands(program2) {
     await handleCapture(this, options);
   });
 }
-var EPIC_ID_PATTERN3 = /^[a-zA-Z0-9_.-]+$/;
+var EPIC_ID_PATTERN2 = /^[a-zA-Z0-9_.-]+$/;
 function buildScriptHeader(timestamp, maxRetries, model, epicIds) {
   return `#!/usr/bin/env bash
 # Infinity Loop - Generated by: ca loop
@@ -8511,8 +9505,8 @@ function validateOptions(options) {
   }
   if (options.epics) {
     for (const id of options.epics) {
-      if (!EPIC_ID_PATTERN3.test(id)) {
-        throw new Error(`Invalid epic ID "${id}": must match ${EPIC_ID_PATTERN3}`);
+      if (!EPIC_ID_PATTERN2.test(id)) {
+        throw new Error(`Invalid epic ID "${id}": must match ${EPIC_ID_PATTERN2}`);
       }
     }
   }
@@ -8637,7 +9631,19 @@ async function searchAction(cmd, query, options) {
   await syncIfNeeded(repoRoot);
   let results;
   try {
-    results = await searchKeyword(repoRoot, query, limit);
+    const usability = await isModelUsable();
+    if (usability.usable) {
+      const candidateLimit = limit * CANDIDATE_MULTIPLIER;
+      const [vectorResults, keywordResults] = await Promise.all([
+        searchVector(repoRoot, query, { limit: candidateLimit }),
+        searchKeywordScored(repoRoot, query, candidateLimit)
+      ]);
+      const merged = mergeHybridResults(vectorResults, keywordResults, { minScore: MIN_HYBRID_SCORE });
+      const ranked = rankLessons(merged);
+      results = ranked.slice(0, limit).map((r) => r.lesson);
+    } else {
+      results = await searchKeyword(repoRoot, query, limit);
+    }
   } catch (err) {
     const message = err instanceof Error ? err.message : "Search failed";
     console.error(formatError("search", "SEARCH_FAILED", message, "Check your query syntax"));
@@ -8761,6 +9767,7 @@ async function checkPlanAction(cmd, options) {
     process.exitCode = 1;
     return;
   }
+  await syncIfNeeded(repoRoot);
   const usability = await isModelUsable();
   if (!usability.usable) {
     if (options.json) {
@@ -8802,7 +9809,7 @@ async function checkPlanAction(cmd, options) {
   }
 }
 function registerRetrievalCommands(program2) {
-  program2.command("search <query>").description("Search lessons by keyword").option("-n, --limit <number>", "Maximum results", DEFAULT_SEARCH_LIMIT).action(async function(query, options) {
+  program2.command("search <query>").description("Search lessons").option("-n, --limit <number>", "Maximum results", DEFAULT_SEARCH_LIMIT).action(async function(query, options) {
     await searchAction(this, query, options);
   });
   program2.command("list").description("List all lessons").option("-n, --limit <number>", "Maximum results", DEFAULT_LIST_LIMIT).option("--invalidated", "Show only invalidated lessons").action(async function(options) {
@@ -8838,6 +9845,8 @@ function registerManagementCommands(program2) {
   registerTestSummaryCommand(program2);
   registerVerifyGatesCommand(program2);
   registerAboutCommand(program2);
+  registerKnowledgeCommand(program2);
+  registerKnowledgeIndexCommand(program2);
   registerWorktreeCommands(program2);
 }