lat.md 0.5.0 → 0.7.0

package/dist/src/cli/init.js

@@ -1,19 +1,28 @@
-import { existsSync, cpSync, mkdirSync, writeFileSync, readFileSync, copyFileSync, chmodSync, } from 'node:fs';
+import { existsSync, cpSync, mkdirSync, writeFileSync, readFileSync, } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import chalk from 'chalk';
 import { findTemplatesDir } from './templates.js';
 import { readAgentsTemplate, readCursorRulesTemplate } from './gen.js';
 import { getConfigPath, readConfig, writeConfig, } from '../config.js';
+import { writeInitMeta, readFileHash, contentHash } from '../init-version.js';
 async function confirm(rl, message) {
-    try {
-        const answer = await rl.question(`${message} ${chalk.dim('[Y/n]')} `);
-        return answer.trim().toLowerCase() !== 'n';
-    }
-    catch {
-        // Ctrl+C or closed stdin — abort
-        console.log('');
-        process.exit(130);
+    while (true) {
+        let answer;
+        try {
+            answer = await rl.question(`${message} ${chalk.dim('[Y/n]')} `);
+        }
+        catch {
+            // Ctrl+C or closed stdin — abort
+            console.log('');
+            process.exit(130);
+        }
+        const val = answer.trim().toLowerCase();
+        if (val === '' || val === 'y' || val === 'yes')
+            return true;
+        if (val === 'n' || val === 'no')
+            return false;
+        console.log(chalk.yellow('  Please answer Y or n.'));
     }
 }
 async function prompt(rl, message) {
@@ -27,22 +36,21 @@ async function prompt(rl, message) {
     }
 }
 // ── Claude Code helpers ──────────────────────────────────────────────
-const HOOK_COMMAND = '.claude/hooks/lat-prompt-hook.sh';
-function hasLatHook(settingsPath) {
-    if (!existsSync(settingsPath))
-        return false;
-    try {
-        const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-        const entries = settings?.hooks?.UserPromptSubmit;
-        if (!Array.isArray(entries))
-            return false;
-        return entries.some((entry) => entry.hooks?.some((h) => h.command === HOOK_COMMAND));
-    }
-    catch {
-        return false;
-    }
+/** Derive the hook command prefix from the currently running binary. */
+function latHookCommand(event) {
+    return `${resolve(process.argv[1])} hook claude ${event}`;
 }
-function addLatHook(settingsPath) {
+/** True if any command in this entry looks like it was installed by lat. */
+function isLatHookEntry(entry) {
+    const bin = resolve(process.argv[1]);
+    return (entry.hooks?.some((h) => typeof h.command === 'string' &&
+        (/\blat\b/.test(h.command) || h.command.startsWith(bin + ' '))) ?? false);
+}
+/**
+ * Remove all lat-owned hook entries from settings, then add fresh ones.
+ * Preserves any non-lat hooks the user may have configured.
+ */
+function syncLatHooks(settingsPath) {
     let settings = {};
     if (existsSync(settingsPath)) {
         const raw = readFileSync(settingsPath, 'utf-8');
@@ -57,12 +65,27 @@ function addLatHook(settingsPath) {
         settings.hooks = {};
     }
     const hooks = settings.hooks;
-    if (!Array.isArray(hooks.UserPromptSubmit)) {
-        hooks.UserPromptSubmit = [];
+    // Strip lat-owned entries from ALL event types (cleans up stale events too)
+    for (const [event, entries] of Object.entries(hooks)) {
+        if (!Array.isArray(entries))
+            continue;
+        const filtered = entries.filter((entry) => !isLatHookEntry(entry));
+        if (filtered.length > 0) {
+            hooks[event] = filtered;
+        }
+        else {
+            delete hooks[event];
+        }
+    }
+    // Add fresh hooks for current events
+    for (const event of ['UserPromptSubmit', 'Stop']) {
+        if (!Array.isArray(hooks[event])) {
+            hooks[event] = [];
+        }
+        hooks[event].push({
+            hooks: [{ type: 'command', command: latHookCommand(event) }],
+        });
     }
-    hooks.UserPromptSubmit.push({
-        hooks: [{ type: 'command', command: HOOK_COMMAND }],
-    });
     writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
 }
 // ── Gitignore helper ─────────────────────────────────────────────────
@@ -113,7 +136,8 @@ function hasMcpServer(configPath, key) {
         const cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
         return !!cfg?.[key]?.lat;
     }
-    catch {
+    catch (err) {
+        process.stderr.write(`Warning: failed to parse ${configPath}: ${err.message}\n`);
         return false;
     }
 }
@@ -134,49 +158,73 @@ function addMcpServer(configPath, key) {
     mkdirSync(join(configPath, '..'), { recursive: true });
     writeFileSync(configPath, JSON.stringify(cfg, null, 2) + '\n');
 }
+// ── Template file helpers ─────────────────────────────────────────────
+/**
+ * Write a template-generated file, using stored hashes to decide whether
+ * to overwrite or prompt the user about local modifications.
+ *
+ * Returns the hash of the written content, or null if the file was skipped.
+ */
+async function writeTemplateFile(root, latDir, relPath, template, genTarget, label, indent, ask) {
+    const absPath = join(root, relPath);
+    const templateHash = contentHash(template);
+    if (!existsSync(absPath)) {
+        mkdirSync(join(absPath, '..'), { recursive: true });
+        writeFileSync(absPath, template);
+        console.log(chalk.green(`${indent}Created ${label}`));
+        return templateHash;
+    }
+    // File exists — check if user has modified it
+    const currentContent = readFileSync(absPath, 'utf-8');
+    const currentHash = contentHash(currentContent);
+    const storedHash = readFileHash(latDir, relPath);
+    if (currentHash === templateHash) {
+        // Already matches the latest template
+        console.log(chalk.green(`${indent}${label}`) + ' already up to date');
+        return templateHash;
+    }
+    if (storedHash && currentHash === storedHash) {
+        // Unmodified by user — safe to overwrite with new template
+        writeFileSync(absPath, template);
+        console.log(chalk.green(`${indent}Updated ${label}`));
+        return templateHash;
+    }
+    // User has modified the file — ask whether to overwrite
+    console.log(chalk.yellow(`${indent}${label}`) +
+        ' exists and may contain your own content.');
+    if (await ask(`${indent}Overwrite with latest lat template?`)) {
+        writeFileSync(absPath, template);
+        console.log(chalk.green(`${indent}Updated ${label}`));
+        return templateHash;
+    }
+    console.log(chalk.dim(`${indent}Kept existing file.`) +
+        ' Run ' +
+        chalk.cyan(`lat gen ${genTarget}`) +
+        ' to see the latest template.');
+    return null;
+}
 // ── Per-agent setup ──────────────────────────────────────────────────
-function setupAgentsMd(root, template) {
-    const agentsPath = join(root, 'AGENTS.md');
-    if (!existsSync(agentsPath)) {
-        writeFileSync(agentsPath, template);
-        console.log(chalk.green('Created AGENTS.md'));
-    }
-    else {
-        console.log(chalk.green('AGENTS.md') + ' already exists');
-    }
+async function setupAgentsMd(root, latDir, template, hashes, ask) {
+    const hash = await writeTemplateFile(root, latDir, 'AGENTS.md', template, 'agents.md', 'AGENTS.md', '', ask);
+    if (hash)
+        hashes['AGENTS.md'] = hash;
 }
-async function setupClaudeCode(root, template) {
-    const created = [];
+async function setupClaudeCode(root, latDir, template, hashes, ask) {
     // CLAUDE.md — written directly (not a symlink)
-    const claudePath = join(root, 'CLAUDE.md');
-    if (!existsSync(claudePath)) {
-        writeFileSync(claudePath, template);
-        console.log(chalk.green('  Created CLAUDE.md'));
-        created.push('CLAUDE.md');
-    }
-    else {
-        console.log(chalk.green('  CLAUDE.md') + ' already exists');
-    }
-    // Prompt hook
+    const hash = await writeTemplateFile(root, latDir, 'CLAUDE.md', template, 'claude.md', 'CLAUDE.md', '  ', ask);
+    if (hash)
+        hashes['CLAUDE.md'] = hash;
+    // Hooks — UserPromptSubmit (lat.md reminders + [[ref]] expansion) and Stop (update reminder)
     console.log('');
-    console.log(chalk.dim("  Claude Code doesn't reliably follow CLAUDE.md for per-prompt actions,"));
-    console.log(chalk.dim('  so we install a hook that injects lat.md workflow reminders into every prompt.'));
+    console.log(chalk.dim('  Hooks inject lat.md workflow reminders into every prompt and remind'));
+    console.log(chalk.dim('  the agent to update lat.md/ before finishing.'));
     const claudeDir = join(root, '.claude');
-    const hooksDir = join(claudeDir, 'hooks');
-    const hookPath = join(hooksDir, 'lat-prompt-hook.sh');
     const settingsPath = join(claudeDir, 'settings.json');
-    if (hasLatHook(settingsPath)) {
-        console.log(chalk.green('  Prompt hook') + ' already configured');
-    }
-    else {
-        mkdirSync(hooksDir, { recursive: true });
-        const templateHook = join(findTemplatesDir(), 'lat-prompt-hook.sh');
-        copyFileSync(templateHook, hookPath);
-        chmodSync(hookPath, 0o755);
-        addLatHook(settingsPath);
-        console.log(chalk.green('  Prompt hook') + ' installed');
-        created.push('.claude/hooks/lat-prompt-hook.sh');
-    }
+    mkdirSync(claudeDir, { recursive: true });
+    syncLatHooks(settingsPath);
+    console.log(chalk.green('  Hooks') + ' synced (UserPromptSubmit + Stop)');
+    // Ensure .claude is gitignored (settings contain local absolute paths)
+    ensureGitignored(root, '.claude');
     // MCP server → .mcp.json at project root
     console.log('');
     console.log(chalk.dim('  Agents can call `lat` from the command line, but an MCP server gives lat'));
@@ -188,26 +236,15 @@ async function setupClaudeCode(root, template) {
     else {
         addMcpServer(mcpPath, 'mcpServers');
         console.log(chalk.green('  MCP server') + ' registered in .mcp.json');
-        created.push('.mcp.json');
     }
     // Ensure .mcp.json is gitignored (it contains local absolute paths)
     ensureGitignored(root, '.mcp.json');
-    return created;
 }
-async function setupCursor(root) {
-    const created = [];
+async function setupCursor(root, latDir, hashes, ask) {
     // .cursor/rules/lat.md
-    const rulesDir = join(root, '.cursor', 'rules');
-    const rulesPath = join(rulesDir, 'lat.md');
-    if (!existsSync(rulesPath)) {
-        mkdirSync(rulesDir, { recursive: true });
-        writeFileSync(rulesPath, readCursorRulesTemplate());
-        console.log(chalk.green('  Rules') + ' created at .cursor/rules/lat.md');
-        created.push('.cursor/rules/lat.md');
-    }
-    else {
-        console.log(chalk.green('  Rules') + ' already exist');
-    }
+    const hash = await writeTemplateFile(root, latDir, '.cursor/rules/lat.md', readCursorRulesTemplate(), 'cursor-rules.md', 'Rules (.cursor/rules/lat.md)', '  ', ask);
+    if (hash)
+        hashes['.cursor/rules/lat.md'] = hash;
     // .cursor/mcp.json
     console.log('');
     console.log(chalk.dim('  Agents can call `lat` from the command line, but an MCP server gives lat'));
@@ -219,30 +256,18 @@ async function setupCursor(root) {
     else {
         addMcpServer(mcpPath, 'mcpServers');
         console.log(chalk.green('  MCP server') + ' registered in .cursor/mcp.json');
-        created.push('.cursor/mcp.json');
     }
     // Ensure .cursor/mcp.json is gitignored (it contains local absolute paths)
     ensureGitignored(root, '.cursor/mcp.json');
     console.log('');
     console.log(chalk.yellow('  Note:') +
         ' Enable MCP in Cursor: Settings → Features → MCP → check "Enable MCP"');
-    return created;
 }
-async function setupCopilot(root) {
-    const created = [];
+async function setupCopilot(root, latDir, hashes, ask) {
     // .github/copilot-instructions.md
-    const githubDir = join(root, '.github');
-    const instructionsPath = join(githubDir, 'copilot-instructions.md');
-    if (!existsSync(instructionsPath)) {
-        mkdirSync(githubDir, { recursive: true });
-        writeFileSync(instructionsPath, readAgentsTemplate());
-        console.log(chalk.green('  Instructions') +
-            ' created at .github/copilot-instructions.md');
-        created.push('.github/copilot-instructions.md');
-    }
-    else {
-        console.log(chalk.green('  Instructions') + ' already exist');
-    }
+    const hash = await writeTemplateFile(root, latDir, '.github/copilot-instructions.md', readAgentsTemplate(), 'agents.md', 'Instructions (.github/copilot-instructions.md)', '  ', ask);
+    if (hash)
+        hashes['.github/copilot-instructions.md'] = hash;
     // .vscode/mcp.json
     console.log('');
     console.log(chalk.dim('  Agents can call `lat` from the command line, but an MCP server gives lat'));
@@ -254,40 +279,40 @@ async function setupCopilot(root) {
     else {
         addMcpServer(mcpPath, 'servers');
         console.log(chalk.green('  MCP server') + ' registered in .vscode/mcp.json');
-        created.push('.vscode/mcp.json');
     }
-    return created;
 }
 // ── LLM key setup ───────────────────────────────────────────────────
 async function setupLlmKey(rl) {
-    console.log('');
-    console.log(chalk.bold('Semantic search'));
-    console.log('');
-    console.log('  lat.md includes semantic search (' +
-        chalk.cyan('lat search') +
-        ') that lets agents find');
-    console.log('  relevant documentation by meaning, not just keywords. This requires an');
-    console.log('  embedding API key (OpenAI or Vercel AI Gateway). Without it, agents can still');
-    console.log('  use ' +
-        chalk.cyan('lat locate') +
-        ' for exact lookups, but will miss semantic matches.');
-    console.log('');
     // Check env var first
     const envKey = process.env.LAT_LLM_KEY;
     if (envKey) {
-        console.log(chalk.green('  LAT_LLM_KEY') +
-            ' is set in your environment. Semantic search is ready.');
+        console.log('');
+        console.log(chalk.green('Semantic search') + ' — LAT_LLM_KEY is set. Ready.');
         return;
     }
     // Check existing config
     const config = readConfig();
     const configPath = getConfigPath();
     if (config.llm_key) {
-        console.log(chalk.green('  LLM key') +
-            ' already configured in ' +
+        console.log('');
+        console.log(chalk.green('Semantic search') +
+            ' — LLM key configured in ' +
             chalk.dim(configPath));
         return;
     }
+    // No key found — explain what semantic search is and prompt
+    console.log('');
+    console.log(chalk.bold('Semantic search'));
+    console.log('');
+    console.log('  lat.md includes semantic search (' +
+        chalk.cyan('lat search') +
+        ') that lets agents find');
+    console.log('  relevant documentation by meaning, not just keywords. This requires an');
+    console.log('  embedding API key (OpenAI or Vercel AI Gateway). Without it, agents can still');
+    console.log('  use ' +
+        chalk.cyan('lat locate') +
+        ' for exact lookups, but will miss semantic matches.');
+    console.log('');
     // Interactive prompt
     if (!rl) {
         console.log(chalk.yellow('  No LLM key found.') +
@@ -382,26 +407,27 @@ export async function initCmd(targetDir) {
         }
         console.log('');
         const template = readAgentsTemplate();
+        const fileHashes = {};
         // Step 3: AGENTS.md (shared by non-Claude agents)
         const needsAgentsMd = useCursor || useCopilot || useCodex;
         if (needsAgentsMd) {
-            setupAgentsMd(root, template);
+            await setupAgentsMd(root, latDir, template, fileHashes, ask);
         }
         // Step 4: Per-agent setup
         if (useClaudeCode) {
             console.log('');
             console.log(chalk.bold('Setting up Claude Code...'));
-            await setupClaudeCode(root, template);
+            await setupClaudeCode(root, latDir, template, fileHashes, ask);
         }
         if (useCursor) {
             console.log('');
             console.log(chalk.bold('Setting up Cursor...'));
-            await setupCursor(root);
+            await setupCursor(root, latDir, fileHashes, ask);
         }
         if (useCopilot) {
             console.log('');
             console.log(chalk.bold('Setting up VS Code Copilot...'));
-            await setupCopilot(root);
+            await setupCopilot(root, latDir, fileHashes, ask);
         }
         if (useCodex) {
             console.log('');
@@ -410,6 +436,8 @@ export async function initCmd(targetDir) {
         }
         // Step 5: LLM key setup
         await setupLlmKey(rl);
+        // Record init version and file hashes so `lat check` can detect stale setups
+        writeInitMeta(latDir, fileHashes);
         console.log('');
         console.log(chalk.green('Done!') +
             ' Run ' +

package/dist/src/cli/locate.d.ts

@@ -1,2 +1,2 @@
-import type { CliContext } from './context.js';
-export declare function locateCmd(ctx: CliContext, query: string): Promise<void>;
+import type { CmdContext, CmdResult } from '../context.js';
+export declare function locateCommand(ctx: CmdContext, query: string): Promise<CmdResult>;

package/dist/src/cli/locate.js

@@ -1,12 +1,17 @@
 import { loadAllSections, findSections } from '../lattice.js';
 import { formatResultList } from '../format.js';
-export async function locateCmd(ctx, query) {
+export async function locateCommand(ctx, query) {
     const stripped = query.replace(/^\[\[|\]\]$/g, '');
     const sections = await loadAllSections(ctx.latDir);
     const matches = findSections(sections, stripped);
     if (matches.length === 0) {
-        console.error(ctx.chalk.red(`No sections matching "${stripped}" (no exact, substring, or fuzzy matches)`));
-        process.exit(1);
+        const s = ctx.styler;
+        return {
+            output: s.red(`No sections matching "${stripped}" (no exact, substring, or fuzzy matches)`),
+            isError: true,
+        };
     }
-    console.log(formatResultList(`Sections matching "${stripped}":`, matches, ctx.latDir));
+    return {
+        output: formatResultList(ctx, `Sections matching "${stripped}":`, matches),
+    };
 }

package/dist/src/cli/refs.d.ts

@@ -1,4 +1,20 @@
-import type { CliContext } from './context.js';
-type Scope = 'md' | 'code' | 'md+code';
-export declare function refsCmd(ctx: CliContext, query: string, scope: Scope): Promise<void>;
-export {};
+import { type Section, type SectionMatch } from '../lattice.js';
+import type { CmdContext, CmdResult } from '../context.js';
+export type Scope = 'md' | 'code' | 'md+code';
+export type RefsFound = {
+    kind: 'found';
+    target: Section;
+    mdRefs: SectionMatch[];
+    codeRefs: string[];
+};
+export type RefsError = {
+    kind: 'no-match';
+    suggestions: SectionMatch[];
+};
+export type RefsResult = RefsFound | RefsError;
+/**
+ * Find all sections and code locations that reference a given section.
+ * Accepts any valid section id (full-path, short-form, with or without brackets).
+ */
+export declare function findRefs(ctx: CmdContext, query: string, scope: Scope): Promise<RefsResult>;
+export declare function refsCommand(ctx: CmdContext, query: string, scope: Scope): Promise<CmdResult>;

package/dist/src/cli/refs.js

@@ -1,45 +1,44 @@
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
 import { listLatticeFiles, loadAllSections, findSections, extractRefs, flattenSections, buildFileIndex, resolveRef, } from '../lattice.js';
 import { formatResultList } from '../format.js';
 import { scanCodeRefs } from '../code-refs.js';
-export async function refsCmd(ctx, query, scope) {
+/**
+ * Find all sections and code locations that reference a given section.
+ * Accepts any valid section id (full-path, short-form, with or without brackets).
+ */
+export async function findRefs(ctx, query, scope) {
+    query = query.replace(/^\[\[|\]\]$/g, '');
     const allSections = await loadAllSections(ctx.latDir);
-    const matches = findSections(allSections, query);
-    if (matches.length === 0) {
-        console.error(ctx.chalk.red(`No section matching "${query}" (no exact, substring, or fuzzy matches)`));
-        process.exit(1);
-    }
-    // Resolve short refs and require exact match
     const flat = flattenSections(allSections);
     const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
     const fileIndex = buildFileIndex(allSections);
     const { resolved } = resolveRef(query, sectionIds, fileIndex);
     const q = resolved.toLowerCase();
-    const exactMatch = flat.find((s) => s.id.toLowerCase() === q);
-    if (!exactMatch) {
-        console.error(ctx.chalk.red(`No section "${query}" found.`));
-        if (matches.length > 0) {
-            console.error(ctx.chalk.dim('\nDid you mean:\n'));
-            for (const m of matches) {
-                console.error(ctx.chalk.dim('*') +
-                    ' ' +
-                    ctx.chalk.white(m.section.id) +
-                    ' ' +
-                    ctx.chalk.dim(`(${m.reason})`));
-            }
+    let exactMatch = flat.find((s) => s.id.toLowerCase() === q);
+    // If resolveRef didn't land on an exact id, use findSections as fallback
+    const matches = !exactMatch ? findSections(allSections, query) : [];
+    if (!exactMatch && matches.length >= 1) {
+        const top = matches[0];
+        const isConfident = top.reason === 'exact match' ||
+            top.reason.startsWith('file stem expanded') ||
+            top.reason === 'section name match';
+        if (isConfident) {
+            exactMatch = top.section;
         }
-        process.exit(1);
+    }
+    if (!exactMatch) {
+        const suggestions = matches.length > 0 ? matches : findSections(allSections, query);
+        return { kind: 'no-match', suggestions };
     }
     const targetId = exactMatch.id.toLowerCase();
-    const mdMatches = [];
-    const codeLines = [];
+    const mdRefs = [];
+    const codeRefs = [];
     if (scope === 'md' || scope === 'md+code') {
         const files = await listLatticeFiles(ctx.latDir);
         const matchingFromSections = new Set();
         for (const file of files) {
             const content = await readFile(file, 'utf-8');
-            const fileRefs = extractRefs(file, content, ctx.latDir);
+            const fileRefs = extractRefs(file, content, ctx.projectRoot);
             for (const ref of fileRefs) {
                 const { resolved: refResolved } = resolveRef(ref.target, sectionIds, fileIndex);
                 if (refResolved.toLowerCase() === targetId) {
@@ -50,34 +49,57 @@ export async function refsCmd(ctx, query, scope) {
         if (matchingFromSections.size > 0) {
             const referrers = flat.filter((s) => matchingFromSections.has(s.id.toLowerCase()));
             for (const s of referrers) {
-                mdMatches.push({ section: s, reason: 'wiki link' });
+                mdRefs.push({ section: s, reason: 'wiki link' });
             }
         }
     }
     if (scope === 'code' || scope === 'md+code') {
-        const projectRoot = join(ctx.latDir, '..');
-        const { refs: codeRefs } = await scanCodeRefs(projectRoot);
-        for (const ref of codeRefs) {
+        const { refs: scannedRefs } = await scanCodeRefs(ctx.projectRoot);
+        for (const ref of scannedRefs) {
             const { resolved: codeResolved } = resolveRef(ref.target, sectionIds, fileIndex);
             if (codeResolved.toLowerCase() === targetId) {
-                codeLines.push(`${ref.file}:${ref.line}`);
+                codeRefs.push(`${ref.file}:${ref.line}`);
             }
         }
     }
-    if (mdMatches.length === 0 && codeLines.length === 0) {
-        console.error(ctx.chalk.red(`No references to "${exactMatch.id}" found`));
-        process.exit(1);
+    return { kind: 'found', target: exactMatch, mdRefs, codeRefs };
+}
+export async function refsCommand(ctx, query, scope) {
+    const result = await findRefs(ctx, query, scope);
+    if (result.kind === 'no-match') {
+        const s = ctx.styler;
+        if (result.suggestions.length > 0) {
+            const suggestions = result.suggestions
+                .map((m) => `  ${s.dim('*')} ${s.white(m.section.id)} ${s.dim(`(${m.reason})`)}`)
+                .join('\n');
+            return {
+                output: s.red(`No section "${query}" found.`) +
+                    ' Did you mean:\n' +
+                    suggestions,
+                isError: true,
+            };
+        }
+        return {
+            output: s.red(`No section matching "${query}"`),
+            isError: true,
+        };
     }
-    if (mdMatches.length > 0) {
-        console.log(formatResultList(`References to "${exactMatch.id}":`, mdMatches, ctx.latDir));
+    const { target, mdRefs, codeRefs } = result;
+    if (mdRefs.length === 0 && codeRefs.length === 0) {
+        return {
+            output: ctx.styler.yellow(`No references to "${target.id}" found`),
+            isError: true,
+        };
     }
-    if (codeLines.length > 0) {
-        if (mdMatches.length > 0)
-            console.log('');
-        console.log(ctx.chalk.bold('Code references:'));
-        console.log('');
-        for (const line of codeLines) {
-            console.log(`${ctx.chalk.dim('*')} ${line}`);
-        }
+    const s = ctx.styler;
+    const parts = [];
+    if (mdRefs.length > 0) {
+        parts.push(formatResultList(ctx, `References to "${target.id}":`, mdRefs));
+    }
+    if (codeRefs.length > 0) {
+        parts.push(s.bold('Code references:') +
+            '\n\n' +
+            codeRefs.map((l) => `${s.dim('*')} ${l}`).join('\n'));
     }
+    return { output: parts.join('\n') };
 }

package/dist/src/cli/search.d.ts

@@ -1,5 +1,27 @@
-import type { CliContext } from './context.js';
-export declare function searchCmd(ctx: CliContext, query: string | undefined, opts: {
+import type { CmdContext, CmdResult, Styler } from '../context.js';
+import { type IndexStats } from '../search/index.js';
+import { type SectionMatch } from '../lattice.js';
+export type SearchResult = {
+    query: string;
+    matches: SectionMatch[];
+};
+export type IndexProgress = {
+    /** Called before indexing starts. `isEmpty` is true on first run. */
+    beforeIndex?: (isEmpty: boolean) => void;
+    /** Called after indexing completes with stats. */
+    afterIndex?: (stats: IndexStats, isEmpty: boolean) => void;
+};
+/**
+ * Run a semantic search across lat.md sections.
+ * Handles indexing (with optional progress callback). Returns matched sections.
+ */
+export declare function runSearch(latDir: string, query: string, key: string, limit: number, progress?: IndexProgress): Promise<SearchResult>;
+/**
+ * Index-only mode (no query). Used by `lat search --reindex`.
+ */
+export declare function runIndex(latDir: string, key: string, progress?: IndexProgress): Promise<void>;
+export declare function cliProgress(reindex: boolean, s: Styler): IndexProgress;
+export declare function searchCommand(ctx: CmdContext, query: string | undefined, opts: {
     limit: number;
     reindex?: boolean;
-}): Promise<void>;
+}, progress?: IndexProgress): Promise<CmdResult>;