lat.md 0.6.0 → 0.7.1

package/dist/src/cli/index.js

@@ -8,8 +8,6 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
 import { resolveContext } from './context.js';
-import { locateCmd } from './locate.js';
-import { refsCmd } from './refs.js';
 function findPackageJson() {
     let dir = dirname(fileURLToPath(import.meta.url));
     while (true) {
@@ -24,6 +22,14 @@ function findPackageJson() {
         dir = parent;
     }
 }
+function handleResult(result) {
+    if (result.isError) {
+        console.error(result.output);
+        process.exit(1);
+    }
+    if (result.output)
+        console.log(result.output);
+}
 const version = findPackageJson();
 const program = new Command();
 program
@@ -39,7 +45,17 @@ program
     .argument('<query>', 'section id to search for')
     .action(async (query) => {
     const ctx = resolveContext(program.opts());
-    await locateCmd(ctx, query);
+    const { locateCommand } = await import('./locate.js');
+    handleResult(await locateCommand(ctx, query));
+});
+program
+    .command('section')
+    .description('Show a section with its content, outgoing refs, and incoming refs')
+    .argument('<query>', 'section id to look up')
+    .action(async (query) => {
+    const ctx = resolveContext(program.opts());
+    const { sectionCommand } = await import('./section.js');
+    handleResult(await sectionCommand(ctx, query));
 });
 program
     .command('refs')
@@ -53,46 +69,50 @@ program
         process.exit(1);
     }
     const ctx = resolveContext(program.opts());
-    await refsCmd(ctx, query, scope);
+    const { refsCommand } = await import('./refs.js');
+    handleResult(await refsCommand(ctx, query, scope));
 });
 const check = program
     .command('check')
     .description('Validate links and code references')
     .action(async () => {
     const ctx = resolveContext(program.opts());
-    const { checkAllCmd } = await import('./check.js');
-    await checkAllCmd(ctx);
+    const { checkAllCommand } = await import('./check.js');
+    handleResult(await checkAllCommand(ctx));
 });
 check
     .command('md')
     .description('Validate wiki links in lat.md markdown files')
     .action(async () => {
     const ctx = resolveContext(program.opts());
-    const { checkMdCmd } = await import('./check.js');
-    await checkMdCmd(ctx);
+    const { checkMdCommand } = await import('./check.js');
+    handleResult(await checkMdCommand(ctx));
 });
 check
     .command('code-refs')
     .description('Validate @lat code references and coverage')
     .action(async () => {
     const ctx = resolveContext(program.opts());
-    const { checkCodeRefsCmd } = await import('./check.js');
-    await checkCodeRefsCmd(ctx);
+    const { checkCodeRefsCommand } = await import('./check.js');
+    handleResult(await checkCodeRefsCommand(ctx));
 });
 check
     .command('index')
     .description('Validate directory index files in lat.md')
     .action(async () => {
     const ctx = resolveContext(program.opts());
-    const { checkIndexCmd } = await import('./check.js');
-    await checkIndexCmd(ctx);
+    const { checkIndexCommand } = await import('./check.js');
+    handleResult(await checkIndexCommand(ctx));
 });
-program
-    .command('prompt')
-    .description('Expand [[refs]] in a prompt to lat.md section locations')
-    .argument('[text]', 'prompt text')
-    .option('--stdin', 'read prompt from stdin')
-    .action(async (text, opts) => {
+check
+    .command('sections')
+    .description('Validate section leading paragraphs in lat.md')
+    .action(async () => {
+    const ctx = resolveContext(program.opts());
+    const { checkSectionsCommand } = await import('./check.js');
+    handleResult(await checkSectionsCommand(ctx));
+});
+async function runExpand(text, opts) {
     if (opts.stdin) {
         const chunks = [];
         for await (const chunk of process.stdin) {
@@ -101,12 +121,33 @@ program
         text = Buffer.concat(chunks).toString('utf-8');
     }
     if (!text) {
-        console.error('Provide prompt text as an argument or use --stdin');
+        console.error('Provide text as an argument or use --stdin');
         process.exit(1);
     }
     const ctx = resolveContext(program.opts());
-    const { promptCmd } = await import('./prompt.js');
-    await promptCmd(ctx, text);
+    const { expandCommand } = await import('./expand.js');
+    const result = await expandCommand(ctx, text);
+    if (result.isError) {
+        console.error(result.output);
+        process.exit(1);
+    }
+    // Use stdout.write (no trailing newline) for piping
+    process.stdout.write(result.output);
+}
+program
+    .command('expand')
+    .description('Expand [[refs]] in text to lat.md section locations')
+    .argument('[text]', 'text containing [[refs]]')
+    .option('--stdin', 'read text from stdin')
+    .action(runExpand);
+// Deprecated alias — hidden from --help
+program
+    .command('prompt', { hidden: true })
+    .argument('[text]')
+    .option('--stdin')
+    .action(async (text, opts) => {
+    console.error('Warning: `lat prompt` is deprecated, use `lat expand` instead.');
+    await runExpand(text, opts);
 });
 program
     .command('search')
@@ -116,16 +157,15 @@ program
     .option('--reindex', 'force full re-indexing')
     .action(async (query, opts) => {
     const ctx = resolveContext(program.opts());
-    const { searchCmd } = await import('./search.js');
-    await searchCmd(ctx, query, {
-        limit: parseInt(opts.limit),
-        reindex: opts.reindex,
-    });
+    const { searchCommand, cliProgress } = await import('./search.js');
+    const progress = cliProgress(!!opts.reindex, ctx.styler);
+    const result = await searchCommand(ctx, query, { limit: parseInt(opts.limit), reindex: opts.reindex }, progress);
+    handleResult(result);
 });
 program
     .command('gen')
-    .description('Generate a file to stdout (agents.md, claude.md)')
-    .argument('<target>', 'file to generate: agents.md or claude.md')
+    .description('Generate a file to stdout (agents.md, claude.md, cursor-rules.md)')
+    .argument('<target>', 'file to generate: agents.md, claude.md, cursor-rules.md')
     .action(async (target) => {
     const { genCmd } = await import('./gen.js');
     await genCmd(target);
@@ -138,6 +178,15 @@ program
     const { initCmd } = await import('./init.js');
     await initCmd(dir);
 });
+program
+    .command('hook')
+    .description('Handle agent hook events (called by agent hooks, not directly)')
+    .argument('<agent>', 'agent name (claude)')
+    .argument('<event>', 'hook event (UserPromptSubmit, Stop)')
+    .action(async (agent, event) => {
+    const { hookCmd } = await import('./hook.js');
+    await hookCmd(agent, event);
+});
 program
     .command('mcp')
     .description('Start the MCP server (stdio transport)')

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.projectRoot));
+    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>;