@aprimediet/codewalker 1.1.0 → 1.3.0

package/src/format.test.ts

@@ -2,6 +2,24 @@ import { describe, it, expect } from 'vitest';
 import { formatCompact, formatCardBody } from './format.ts';
 import type { QueryResultRow, StalenessInfo } from './types.ts';
 
+function makeLibRow(overrides: Partial<QueryResultRow> = {}): QueryResultRow {
+  return {
+    id: 100,
+    name: 'createMiddleware',
+    kind: 'function',
+    file_path: 'hono/dist/helper.d.ts',
+    line_start: 0,
+    line_end: 0,
+    signature: 'export declare function createMiddleware<E>(...): MiddlewareHandler',
+    summary: 'Define a typed middleware handler.',
+    score: 0.3,
+    source: 'lib',
+    lib: 'hono',
+    version: '4.6.3',
+    ...overrides,
+  };
+}
+
 function makeRow(overrides: Partial<QueryResultRow> = {}): QueryResultRow {
   return {
     id: 1,
@@ -63,6 +81,91 @@ describe('formatCompact', () => {
   });
 });
 
+describe('formatCompact with lib rows', () => {
+  it('renders a lib row with [lib@version] origin tag', () => {
+    const rows = [makeLibRow()];
+    const result = formatCompact(rows, null);
+    expect(result).toContain('createMiddleware');
+    expect(result).toContain('function');
+    expect(result).toContain('[hono@4.6.3]');
+    expect(result).toContain('Define a typed middleware handler.');
+  });
+
+  it('renders mixed code and lib rows', () => {
+    const libRow = makeLibRow();
+    const codeRow: QueryResultRow = {
+      id: 1, name: 'myFunc', kind: 'function',
+      file_path: 'src/util/helper.ts', line_start: 10, line_end: 20,
+      signature: '(x: number) => string', summary: 'Does something', score: 0.5,
+    };
+    const result = formatCompact([codeRow, libRow], null);
+    expect(result).toContain('helper.ts:10-20');
+    expect(result).toContain('[hono@4.6.3]');
+    // Two lines
+    expect(result.split('\n')).toHaveLength(2);
+  });
+
+  it('bounded output for lib rows (one line per hit)', () => {
+    const rows = Array.from({ length: 5 }, (_, i) =>
+      makeLibRow({ name: `fn${i}`, lib: 'test-pkg', version: '1.0.0' })
+    );
+    const result = formatCompact(rows, null);
+    expect(result.split('\n')).toHaveLength(5);
+    expect(result).toContain('[test-pkg@1.0.0]');
+  });
+});
+
+describe('formatCompact with note rows', () => {
+  it('renders a glossary note row with [glossary] prefix', () => {
+    const rows: QueryResultRow[] = [{
+      id: 1, name: 'Idempotency Key', kind: 'glossary',
+      file_path: '', line_start: 0, line_end: 0,
+      signature: '', summary: 'A client-supplied key that makes retries safe.',
+      score: 0.5, source: 'note', note_kind: 'glossary', tags: 'api',
+    }];
+    const result = formatCompact(rows, null);
+    expect(result).toContain('Idempotency Key');
+    expect(result).toContain('glossary');
+    expect(result).toContain('[glossary]');
+    expect(result).toContain('A client-supplied key that makes retries safe.');
+  });
+
+  it('renders a decision note row with [decision] prefix', () => {
+    const rows: QueryResultRow[] = [{
+      id: 1, name: 'Use SQLite', kind: 'decision',
+      file_path: '', line_start: 0, line_end: 0,
+      signature: '', summary: 'Chosen for zero infra.',
+      score: 0.5, source: 'note', note_kind: 'decision', tags: '',
+    }];
+    const result = formatCompact(rows, null);
+    expect(result).toContain('Use SQLite');
+    expect(result).toContain('decision');
+    expect(result).toContain('[decision]');
+  });
+
+  it('renders mixed code + lib + note rows all on separate lines', () => {
+    const codeRow: QueryResultRow = {
+      id: 1, name: 'myFunc', kind: 'function',
+      file_path: 'src/util/helper.ts', line_start: 10, line_end: 20,
+      signature: '', summary: 'Does something', score: 0.5,
+    };
+    const libRow = makeLibRow();
+    const noteRow: QueryResultRow = {
+      id: 1, name: 'Retry Key', kind: 'glossary',
+      file_path: '', line_start: 0, line_end: 0,
+      signature: '', summary: 'Key for idempotent retries.',
+      score: 0.5, source: 'note', note_kind: 'glossary', tags: '',
+    };
+
+    const result = formatCompact([codeRow, libRow, noteRow], null);
+    expect(result).toContain('helper.ts:10-20');
+    expect(result).toContain('[hono@4.6.3]');
+    expect(result).toContain('[glossary]');
+    expect(result).toContain('Retry Key');
+    expect(result.split('\n')).toHaveLength(3);
+  });
+});
+
 describe('formatCardBody', () => {
   it('returns the card body text', () => {
     const body = '# myFunc\n\nDoes something.\n';

package/src/format.ts

@@ -27,6 +27,17 @@ export function formatCompact(
   }
 
   const lines = rows.map((row) => {
+    if (row.source === "note" && row.note_kind) {
+      const prefix = `[${row.note_kind}]`;
+      const summary = truncate(row.summary || "", SUMMARY_MAX);
+      return `${row.name} · ${row.note_kind} · ${prefix} · ${summary}`;
+    }
+    if (row.source === "lib" && row.lib && row.version) {
+      const origin = `[${row.lib}@${row.version}]`;
+      const summary = truncate(row.summary || "", SUMMARY_MAX);
+      const loc = row.file_path ? `${basename(row.file_path)}:${row.line_start}-${row.line_end}` : `lib`;
+      return `${row.name} · ${row.kind} · ${origin} · ${loc} · ${summary}`;
+    }
     const loc = `${basename(row.file_path)}:${row.line_start}-${row.line_end}`;
     const summary = truncate(row.summary || "", SUMMARY_MAX);
     return `${row.name} · ${row.kind} · ${loc} · ${summary}`;

package/src/index.contract.test.ts

@@ -58,10 +58,35 @@ describe('index.ts contract', () => {
     expect(queryTool).toBeDefined();
     expect(queryTool!.description).toContain('code index');
 
+    // Check new v1.3 tools
+    const enrichTool = stub.tools.find(t => t.name === 'codewalker_enrich');
+    expect(enrichTool).toBeDefined();
+    expect(enrichTool!.description).toContain('summary');
+
+    const noteTool = stub.tools.find(t => t.name === 'codewalker_note');
+    expect(noteTool).toBeDefined();
+    expect(noteTool!.description).toContain('glossary');
+
+    // Check enrich tool parameters
+    const enrichParams = (enrichTool!.parameters as any);
+    expect(enrichParams.properties).toHaveProperty('card');
+    expect(enrichParams.properties).toHaveProperty('summary');
+
+    // Check note tool parameters
+    const noteParams = (noteTool!.parameters as any);
+    expect(noteParams.properties).toHaveProperty('type');
+    expect(noteParams.properties).toHaveProperty('title');
+    expect(noteParams.properties).toHaveProperty('body');
+
+    // Check tool has a source parameter
+    const toolParams = (queryTool!.parameters as any);
+    expect(toolParams.properties).toHaveProperty('source');
+
     // Check command registered
     const cmd = stub.commands.find(c => c.name === 'codewalker');
     expect(cmd).toBeDefined();
-    expect(cmd!.description).toBeDefined();
+    expect(cmd!.description).toContain('libs');
+    expect(cmd!.description).toContain('lib');
   });
 
   it('tool.execute returns { content, details } with compact text content', async () => {
@@ -97,4 +122,55 @@ describe('index.ts contract', () => {
 
     fs.rmSync(tmpDir, { recursive: true, force: true });
   });
+
+  it('tool.execute with source="libs" returns valid result even with no lib data', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cw-contract-libs-'));
+    const piDir = path.join(tmpDir, '.pi');
+    fs.mkdirSync(piDir, { recursive: true });
+    const markerId = 'test-project-libs-' + Math.random().toString(36).slice(2, 8);
+    fs.writeFileSync(path.join(piDir, markerId + '.md'), `---\npi-project: true\nid: ${markerId}\n---\n`);
+
+    const homePi = path.join(os.homedir(), '.pi', 'projects', markerId, 'codewalker');
+    fs.mkdirSync(homePi, { recursive: true });
+
+    const mod = await import('./index.ts');
+    const stub = createPiStub();
+    mod.default(stub.api as any);
+
+    const tool = stub.tools.find(t => t.name === 'codewalker_query')!;
+    const result = await tool.execute(
+      'test-id',
+      { query: 'test', source: 'libs' },
+      new AbortController().signal,
+      () => {},
+      { cwd: tmpDir },
+    );
+
+    expect(result).toHaveProperty('content');
+    expect(result.content[0]!.text).toContain('No matches');
+    expect(result.details.rows).toEqual([]);
+
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('command description mentions libs and lib subcommands', async () => {
+    const mod = await import('./index.ts');
+    const stub = createPiStub();
+    mod.default(stub.api as any);
+
+    const cmd = stub.commands.find(c => c.name === 'codewalker')!;
+    expect(cmd.description).toContain('libs [--dev]');
+    expect(cmd.description).toContain('lib <pkg>');
+  });
+
+  it('command description includes enrich, glossary, decisions subcommands', async () => {
+    const mod = await import('./index.ts');
+    const stub = createPiStub();
+    mod.default(stub.api as any);
+
+    const cmd = stub.commands.find(c => c.name === 'codewalker')!;
+    expect(cmd.description).toContain('enrich');
+    expect(cmd.description).toContain('glossary');
+    expect(cmd.description).toContain('decisions');
+  });
 });

package/src/index.ts

@@ -4,38 +4,52 @@
  * Queryable, token-economical project & code index for the pi coding agent.
  *
  * Registers:
- * - `codewalker_query` tool (agent-facing, compact results)
- * - `/codewalker` command (human-facing) with subcommands scan, sync, query
+ * - `codewalker_query` tool (agent-facing, compact results) — now with `source` param
+ * - `/codewalker` command (human-facing) with subcommands scan, sync, query, libs, lib
  */
 
+import * as fs from "node:fs";
+import * as path from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { resolveProject, ensureProject } from "./project.ts";
 import { runQuery } from "./query.ts";
 import { scan, sync } from "./indexer.ts";
-import { formatCompact, formatCardBody } from "./format.ts";
+import { indexLibraries } from "./libs/indexer.ts";
+import { formatCompact } from "./format.ts";
+import { openDb, selectUnenrichedSymbols, updateSymbolSummary, searchNotes, upsertNote } from "./db.ts";
+import { updateCardSummary } from "./cards.ts";
+import { addNote } from "./notes.ts";
+import { formatEnrichWorklist, validateEnrichPath, checkEnrichCap } from "./enrich.ts";
+import type { NoteKind } from "./types.ts";
 
 export default function codewalkerExtension(pi: ExtensionAPI): void {
-  // ----------------------------------------------------------------- tool
+  // ----------------------------------------------------------------- tools
+
+  // -- codewalker_query (v1.1 — extended with source='notes'|'all')
   pi.registerTool({
     name: "codewalker_query",
     label: "Codewalker Query",
     description:
       "Search the project's code index for symbols (functions, consts, classes, types). " +
-      "Returns compact facts (name, kind, file:line, one-line summary) — use this BEFORE grepping/reading files.",
+      "Returns compact facts (name, kind, file:line, one-line summary) — use this BEFORE grepping/reading files. " +
+      "Optionally search libraries (source='libs') or notes/glossary/decisions (source='notes') or both (source='all').",
     parameters: Type.Object({
       query: Type.String({ description: "Search text — symbol name or concept keywords." }),
-      kind: Type.Optional(Type.String({ description: "Filter: function|const|class|type|method|enum" })),
+      kind: Type.Optional(Type.String({ description: "Filter: function|const|class|type|method|enum|glossary|decision" })),
       limit: Type.Optional(Type.Number({ description: "Max hits (default 10)." })),
+      source: Type.Optional(Type.String({ description: "Where to search: code | libs | notes | all (default code)." })),
     }),
     async execute(_id, params, _signal, _onUpdate, ctx) {
+      const p = params as any;
       const project = resolveProject(ctx.cwd);
       const { rows, staleness } = runQuery(
         project.dbPath,
         {
-          query: (params as any).query as string,
-          kind: (params as any).kind as string | undefined,
-          limit: (params as any).limit as number | undefined,
+          query: p.query as string,
+          kind: p.kind as string | undefined,
+          limit: p.limit as number | undefined,
+          source: (p.source as "code" | "libs" | "notes" | "all") ?? "code",
         },
         project.root,
       );
@@ -48,14 +62,128 @@ export default function codewalkerExtension(pi: ExtensionAPI): void {
     },
   });
 
+  // -- codewalker_enrich (v1.3 — write a semantic summary back to a symbol)
+  pi.registerTool({
+    name: "codewalker_enrich",
+    label: "Codewalker Enrich",
+    description:
+      "Write a one-line semantic summary back to a symbol's card and DB index. " +
+      "Call this AFTER reading the symbol's source span. The summary (≤120 chars) " +
+      "is cached so future queries surface meaning, not just names.",
+    parameters: Type.Object({
+      card: Type.String({ description: "card_path of the symbol (from the enrich worklist)." }),
+      summary: Type.String({ description: "One-line (≤120 char) plain-English summary of what it does." }),
+    }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const p = params as any;
+      const card = p.card as string;
+      const summary = p.summary as string;
+      const project = resolveProject(ctx.cwd);
+
+      // Resolve the card path (may be absolute or relative to codewalker dir)
+      let cardPath = card;
+      if (!path.isAbsolute(cardPath)) {
+        cardPath = path.resolve(project.codewalkerDir, card);
+      }
+
+      // Check the card file exists
+      if (!fs.existsSync(cardPath)) {
+        return {
+          content: [{ type: "text" as const, text: `No card file found at ${cardPath}.` }],
+          details: { error: "card_not_found" },
+        };
+      }
+
+      // Read and update the card
+      const cardContent = fs.readFileSync(cardPath, "utf-8");
+      const updated = updateCardSummary(cardContent, summary);
+
+      // Atomic write back to the card file
+      const tmpPath = cardPath + ".tmp";
+      fs.writeFileSync(tmpPath, updated, { encoding: "utf-8", mode: 0o600 });
+      fs.renameSync(tmpPath, cardPath);
+
+      // Update DB
+      const db = openDb(project.dbPath);
+      let updatedRow = false;
+      try {
+        updatedRow = updateSymbolSummary(db, cardPath, summary);
+      } finally {
+        db.close();
+      }
+
+      if (!updatedRow) {
+        return {
+          content: [{ type: "text" as const, text: `Card ${path.basename(cardPath)} updated but no matching symbol row found in DB. Run /codewalker scan first.` }],
+          details: { card_updated: true, db_updated: false },
+        };
+      }
+
+      return {
+        content: [{ type: "text" as const, text: `Summary written to ${path.basename(cardPath)} and indexed.` }],
+        details: { card_updated: true, db_updated: true, card_path: cardPath, summary },
+      };
+    },
+  });
+
+  // -- codewalker_note (v1.3 — write a glossary term or decision)
+  pi.registerTool({
+    name: "codewalker_note",
+    label: "Codewalker Note",
+    description:
+      "Write a glossary term or decision note. Persists to a markdown card " +
+      "under entries/{glossary,decisions}/ and the FTS index. Future queries " +
+      "will surface this conceptual knowledge alongside code symbols.",
+    parameters: Type.Object({
+      type: Type.String({ description: "glossary | decision" }),
+      title: Type.String({ description: "Glossary term, or decision title." }),
+      body: Type.String({ description: "The definition, or the decision + rationale." }),
+      tags: Type.Optional(Type.String({ description: "Comma-separated tags." })),
+      related: Type.Optional(Type.String({ description: "Comma-separated symbol names or file:line refs." })),
+    }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const p = params as any;
+      const type = (p.type as string).toLowerCase();
+
+      if (type !== "glossary" && type !== "decision") {
+        return {
+          content: [{ type: "text" as const, text: `Invalid note type "${type}". Must be "glossary" or "decision".` }],
+          details: { error: "invalid_type" },
+        };
+      }
+
+      const project = await ensureProject(ctx.cwd);
+      const notesDir = type === "glossary" ? project.glossaryDir : project.decisionsDir;
+
+      addNote(project.dbPath, {
+        note_kind: type as NoteKind,
+        title: (p.title as string).trim(),
+        body: (p.body as string).trim(),
+        tags: (p.tags as string ?? "").trim(),
+        related: (p.related as string ?? "").trim(),
+        card_path: "",
+      }, notesDir);
+
+      return {
+        content: [{ type: "text" as const, text: `${type === "glossary" ? "Glossary term" : "Decision"} "${p.title}" saved and indexed.` }],
+        details: { type, title: p.title },
+      };
+    },
+  });
+
   // ----------------------------------------------------------------- command
   pi.registerCommand("codewalker", {
     description:
-      "codewalker: scan | sync | query <text> | help\n" +
-      "  scan           Full (re)build of the code index\n" +
-      "  sync           Git-anchored incremental update\n" +
-      "  query <text>   Search the index for symbols\n" +
-      "  help           Show this help",
+      "codewalker: scan | sync | query <text> | enrich <path> [--max=N] | glossary [query] | decisions [query] | libs [--dev] | lib <pkg> [query] | help\n" +
+      "  scan              Full (re)build of the code index\n" +
+      "  sync              Git-anchored incremental update\n" +
+      "  query <text>      Search the code index (pass source=notes to include glossary/decisions)\n" +
+      "  enrich <path>     Select unenriched symbols under <path> and write summaries\n" +
+      "  glossary [query]  Search glossary terms\n" +
+      "  decisions [query] Search decision notes\n" +
+      "  libs [--dev]      Index all direct dependencies (--dev includes devDependencies)\n" +
+      "  lib <pkg> [query] Search a specific library's API symbols\n" +
+      "  help              Show this help",
     handler: async (args, ctx) => {
       const tokens = (args ?? "").trim().split(/\s+/).filter(Boolean);
       const sub = tokens[0] ?? "help";
@@ -106,13 +234,139 @@ export default function codewalkerExtension(pi: ExtensionAPI): void {
             break;
           }
 
+          // ── v1.3: enrich ───────────────────────────────────
+          case "enrich": {
+            const enrichPath = tokens[1];
+            const pathCheck = validateEnrichPath(enrichPath);
+            if (!pathCheck.valid) {
+              notify(pathCheck.error!, "error");
+              return;
+            }
+
+            // Parse optional --max=N
+            const maxToken = tokens.find(t => t.startsWith("--max="));
+            const cap = maxToken ? parseInt(maxToken.slice(6), 10) : 40;
+
+            // Select unenriched symbols
+            const db = openDb(project.dbPath);
+            let symbols;
+            try {
+              symbols = selectUnenrichedSymbols(db, enrichPath!, cap + 1); // get one extra to detect overflow
+            } finally {
+              db.close();
+            }
+
+            // Cap check
+            const capCheck = checkEnrichCap(symbols.length, cap);
+            if (!capCheck.ok) {
+              notify(capCheck.error!, "error");
+              return;
+            }
+
+            if (symbols.length === 0) {
+              notify(`No unenriched symbols found under "${enrichPath}".`);
+              return;
+            }
+
+            // Format the worklist
+            const worklist = formatEnrichWorklist(symbols, enrichPath!);
+
+            // With UI, drive the agent; without UI, print the worklist
+            if ((ctx as any).hasUI) {
+              notify(worklist);
+              try {
+                (ctx as any).sendUserMessage?.(worklist);
+              } catch {
+                // sendUserMessage may not be available in all contexts
+              }
+            } else {
+              console.log(worklist);
+            }
+            break;
+          }
+
+          // ── v1.3: glossary ─────────────────────────────────
+          case "glossary": {
+            const q = tokens.slice(1).join(" ");
+            const db = openDb(project.dbPath);
+            let rows;
+            try {
+              rows = searchNotes(db, q || "", "glossary", 20);
+            } finally {
+              db.close();
+            }
+            const text = formatCompact(rows as any, null);
+            notify(text || "No glossary terms found.");
+            break;
+          }
+
+          // ── v1.3: decisions ────────────────────────────────
+          case "decisions": {
+            const q = tokens.slice(1).join(" ");
+            const db = openDb(project.dbPath);
+            let rows;
+            try {
+              rows = searchNotes(db, q || "", "decision", 20);
+            } finally {
+              db.close();
+            }
+            const text = formatCompact(rows as any, null);
+            notify(text || "No decision notes found.");
+            break;
+          }
+
+          case "libs": {
+            const includeDev = tokens.includes("--dev");
+            notify(`Indexing libraries${includeDev ? " (including devDependencies)" : ""}…`);
+            const result = await indexLibraries({
+              projectRoot: project.root,
+              libsDir: project.libsDir,
+              dbPath: project.dbPath,
+              includeDev,
+            });
+            if (result.indexed === 0 && result.symbols === 0) {
+              notify("No libraries indexed. Ensure node_modules exists and has dependencies installed.");
+            } else {
+              notify(`Indexed ${result.indexed} libraries, ${result.symbols} symbols${result.errors > 0 ? ` (${result.errors} errors)` : ""}.`);
+            }
+            break;
+          }
+
+          case "lib": {
+            const pkg = tokens[1];
+            if (!pkg) {
+              notify("Usage: /codewalker lib <pkg> [query]", "error");
+              return;
+            }
+            const q = tokens.slice(2).join(" ");
+            const { rows, staleness } = runQuery(
+              project.dbPath,
+              { query: q || "", source: "libs", limit: 20 },
+              project.root,
+            );
+            // Filter to the requested package
+            const pkgRows = rows.filter(r => r.lib === pkg || r.name === pkg);
+            if (pkgRows.length === 0) {
+              notify(`No API symbols found for "${pkg}". Run /codewalker libs first to index libraries.`);
+            } else {
+              const text = formatCompact(pkgRows, staleness);
+              notify(text);
+            }
+            break;
+          }
+
           default: {
             notify(
-              "codewalker: scan | sync | query <text> | help\n" +
-              "  scan           Full (re)build of the code index\n" +
-              "  sync           Git-anchored incremental update\n" +
-              "  query <text>   Search the index for symbols\n" +
-              "  help           Show this help",
+              "codewalker: scan | sync | query <text> | enrich <path> [--max=N] | glossary [query] | decisions [query] | libs [--dev] | lib <pkg> [query] | help\n" +
+              "  scan              Full (re)build of the code index\n" +
+              "  sync              Git-anchored incremental update\n" +
+              "  query <text>      Search the code index (pass source=notes to include glossary/decisions)\n" +
+              "  enrich <path>     Select unenriched symbols under <path> and write summaries\n" +
+              "  glossary [query]  Search glossary terms\n" +
+              "  decisions [query] Search decision notes\n" +
+              "  libs [--dev]      Index all direct dependencies (--dev includes devDependencies)\n" +
+              "  lib <pkg> [query] Search a specific library's API symbols\n" +
+              "  help              Show this help",
             );
           }
         }

package/src/indexer.heal.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Regression test for the "database disk image is malformed" crash on `/codewalker scan`.
+ *
+ * A DB written by an older (pre-trigger, manual-FTS-sync) build can have a `symbols_fts`
+ * external-content index that is silently out of sync with the `symbols` table. v1.3's bootstrap
+ * adds the FTS-sync triggers, but those don't reconcile the already-stale index — so the per-row
+ * DELETEs in scan() fire `symbols_ad` 'delete' commands against mismatched `old.*` values and
+ * corrupt the index. scan()/sync() guard against this by calling rebuildFtsIndexes() first, which
+ * re-derives every `*_fts` from its content table (the FTS5 'rebuild' command).
+ *
+ * The exact on-disk corruption is b-tree-state dependent and not portably synthesizable, so this
+ * test pins the *fix mechanism*: rebuildFtsIndexes() reconciles a deliberately mismatched FTS.
+ */
+
+import { describe, it, expect } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { openDb, rebuildFtsIndexes } from "./db.ts";
+import { scan } from "./indexer.ts";
+
+function tmpDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "cw-heal-"));
+}
+
+function matchCount(db: ReturnType<typeof openDb>, table: string, term: string): number {
+  return (db.prepare(`SELECT count(*) c FROM ${table} WHERE ${table} MATCH ?`).get(term) as { c: number }).c;
+}
+
+describe("rebuildFtsIndexes heals a stale/mismatched FTS index", () => {
+  it("makes content searchable and drops stale tokens for all three FTS tables", () => {
+    const dir = tmpDir();
+    const db = openDb(path.join(dir, "index.db"));
+
+    // Seed base-table rows directly via FTS-bypassing inserts would still fire triggers, so to
+    // simulate a *stale* index we insert the base row, then overwrite the FTS shadow with wrong
+    // tokens (as a pre-trigger build would have left it).
+    db.prepare(
+      "INSERT INTO symbols (name,kind,file_path,line_start,line_end,signature,doc,summary,card_path) VALUES (?,?,?,?,?,?,?,?,?)",
+    ).run("realSymbol", "function", "/a.ts", 1, 2, "sig", "doc", "", "/c.md");
+    db.prepare(
+      "INSERT INTO lib_symbols (lib,version,name,kind,signature,doc,summary,card_path) VALUES (?,?,?,?,?,?,?,?)",
+    ).run("hono", "1.0.0", "realLibSymbol", "function", "sig", "doc", "", "/c.md");
+    db.prepare(
+      "INSERT INTO notes (note_kind,title,body,tags,related,card_path,created_at) VALUES (?,?,?,?,?,?,?)",
+    ).run("glossary", "realTerm", "body", "", "", "/c.md", "now");
+
+    // Corrupt the shadow indexes: replace the synced tokens with bogus ones.
+    db.exec("INSERT INTO symbols_fts(symbols_fts) VALUES('delete-all')");
+    db.exec("INSERT INTO lib_symbols_fts(lib_symbols_fts) VALUES('delete-all')");
+    db.exec("INSERT INTO notes_fts(notes_fts) VALUES('delete-all')");
+    db.prepare("INSERT INTO symbols_fts(rowid,name,signature,doc,summary) VALUES (1,?,?,?,?)").run("WRONG", "x", "y", "z");
+    db.prepare("INSERT INTO lib_symbols_fts(rowid,name,signature,doc,summary) VALUES (1,?,?,?,?)").run("WRONG", "x", "y", "z");
+    db.prepare("INSERT INTO notes_fts(rowid,title,body,tags) VALUES (1,?,?,?)").run("WRONG", "y", "z");
+
+    // Stale precondition: real content not findable, bogus token is.
+    expect(matchCount(db, "symbols_fts", "realSymbol")).toBe(0);
+    expect(matchCount(db, "symbols_fts", "WRONG")).toBe(1);
+
+    rebuildFtsIndexes(db);
+
+    // After heal: real content searchable, bogus tokens gone — across all three tables.
+    expect(matchCount(db, "symbols_fts", "realSymbol")).toBe(1);
+    expect(matchCount(db, "symbols_fts", "WRONG")).toBe(0);
+    expect(matchCount(db, "lib_symbols_fts", "realLibSymbol")).toBe(1);
+    expect(matchCount(db, "lib_symbols_fts", "WRONG")).toBe(0);
+    expect(matchCount(db, "notes_fts", "realTerm")).toBe(1);
+    expect(matchCount(db, "notes_fts", "WRONG")).toBe(0);
+
+    db.close();
+  });
+
+  it("scan() runs the heal and leaves symbols_fts consistent with symbols", async () => {
+    const dir = tmpDir();
+    const dbPath = path.join(dir, "index.db");
+    const entriesDir = path.join(dir, "entries");
+    const symbolsDir = path.join(entriesDir, "symbols");
+    fs.mkdirSync(symbolsDir, { recursive: true });
+
+    await scan({ projectRoot: process.cwd(), globalCodewalkerDir: dir, dbPath, entriesDir, symbolsDir });
+
+    const db = openDb(dbPath);
+    const symbols = (db.prepare("SELECT count(*) c FROM symbols").get() as { c: number }).c;
+    const fts = (db.prepare("SELECT count(*) c FROM symbols_fts").get() as { c: number }).c;
+    db.close();
+
+    expect(symbols).toBeGreaterThan(0);
+    expect(fts).toBe(symbols);
+  });
+});