lat.md 0.2.3 → 0.4.0

package/dist/src/cli/check.js

@@ -288,4 +288,12 @@ export async function checkAllCmd(ctx) {
     if (totalErrors > 0)
         process.exit(1);
     console.log(ctx.chalk.green('All checks passed'));
+    const { getLlmKey } = await import('../config.js');
+    if (!getLlmKey()) {
+        console.log(ctx.chalk.yellow('Warning:') +
+            ' No LLM key found — semantic search (lat search) will not work.' +
+            ' Set LAT_LLM_KEY env var or run ' +
+            ctx.chalk.cyan('lat init') +
+            ' to configure.');
+    }
 }

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

@@ -1,2 +1,3 @@
 export declare function readAgentsTemplate(): string;
+export declare function readCursorRulesTemplate(): string;
 export declare function genCmd(target: string): Promise<void>;

package/dist/src/cli/gen.js

@@ -4,6 +4,9 @@ import { findTemplatesDir } from './templates.js';
 export function readAgentsTemplate() {
     return readFileSync(join(findTemplatesDir(), 'AGENTS.md'), 'utf-8');
 }
+export function readCursorRulesTemplate() {
+    return readFileSync(join(findTemplatesDir(), 'cursor-rules.md'), 'utf-8');
+}
 export async function genCmd(target) {
     const normalized = target.toLowerCase();
     if (normalized !== 'agents.md' && normalized !== 'claude.md') {

package/dist/src/cli/index.js

@@ -138,4 +138,11 @@ program
     const { initCmd } = await import('./init.js');
     await initCmd(dir);
 });
+program
+    .command('mcp')
+    .description('Start the MCP server (stdio transport)')
+    .action(async () => {
+    const { startMcpServer } = await import('../mcp/server.js');
+    await startMcpServer();
+});
 await program.parseAsync();

package/dist/src/cli/init.js

@@ -1,18 +1,342 @@
-import { existsSync, cpSync, mkdirSync, writeFileSync, symlinkSync, } from 'node:fs';
+import { existsSync, cpSync, mkdirSync, writeFileSync, readFileSync, copyFileSync, chmodSync, } 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 } from './gen.js';
+import { readAgentsTemplate, readCursorRulesTemplate } from './gen.js';
+import { getConfigPath, readConfig, writeConfig, } from '../config.js';
 async function confirm(rl, message) {
     try {
         const answer = await rl.question(`${message} ${chalk.dim('[Y/n]')} `);
         return answer.trim().toLowerCase() !== 'n';
     }
     catch {
-        return true;
+        // Ctrl+C or closed stdin — abort
+        console.log('');
+        process.exit(130);
     }
 }
+async function prompt(rl, message) {
+    try {
+        const answer = await rl.question(message);
+        return answer.trim();
+    }
+    catch {
+        console.log('');
+        process.exit(130);
+    }
+}
+// ── 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;
+    }
+}
+function addLatHook(settingsPath) {
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        const raw = readFileSync(settingsPath, 'utf-8');
+        try {
+            settings = JSON.parse(raw);
+        }
+        catch (e) {
+            throw new Error(`Cannot parse ${settingsPath}: ${e.message}`);
+        }
+    }
+    if (!settings.hooks || typeof settings.hooks !== 'object') {
+        settings.hooks = {};
+    }
+    const hooks = settings.hooks;
+    if (!Array.isArray(hooks.UserPromptSubmit)) {
+        hooks.UserPromptSubmit = [];
+    }
+    hooks.UserPromptSubmit.push({
+        hooks: [{ type: 'command', command: HOOK_COMMAND }],
+    });
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+}
+// ── Gitignore helper ─────────────────────────────────────────────────
+function ensureGitignored(root, entry) {
+    const gitignorePath = join(root, '.gitignore');
+    const gitDir = join(root, '.git');
+    // Check if already ignored
+    if (existsSync(gitignorePath)) {
+        const content = readFileSync(gitignorePath, 'utf-8');
+        const lines = content.split('\n').map((l) => l.trim());
+        if (lines.includes(entry)) {
+            console.log(chalk.green(`  ${entry}`) + ' already in .gitignore');
+            return;
+        }
+    }
+    if (existsSync(gitignorePath)) {
+        // Append to existing .gitignore
+        let content = readFileSync(gitignorePath, 'utf-8');
+        if (!content.endsWith('\n'))
+            content += '\n';
+        writeFileSync(gitignorePath, content + entry + '\n');
+        console.log(chalk.green(`  Added ${entry}`) + ' to .gitignore');
+    }
+    else if (existsSync(gitDir)) {
+        // Create .gitignore with the entry
+        writeFileSync(gitignorePath, entry + '\n');
+        console.log(chalk.green(`  Created .gitignore`) + ` with ${entry}`);
+    }
+    else {
+        console.log(chalk.yellow(`  Warning:`) +
+            ` could not add ${entry} to .gitignore (not a git repository)`);
+    }
+}
+// ── MCP command detection ────────────────────────────────────────────
+/**
+ * Derive the MCP server command from the currently running binary.
+ * If `lat init` was invoked as `/path/to/lat`, we emit
+ * `{ command: "/path/to/lat", args: ["mcp"] }` so the MCP client
+ * starts the same binary.
+ */
+function mcpCommand() {
+    return { command: resolve(process.argv[1]), args: ['mcp'] };
+}
+function hasMcpServer(configPath) {
+    if (!existsSync(configPath))
+        return false;
+    try {
+        const cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
+        return !!cfg?.mcpServers?.lat;
+    }
+    catch {
+        return false;
+    }
+}
+function addMcpServer(configPath) {
+    let cfg = { mcpServers: {} };
+    if (existsSync(configPath)) {
+        const raw = readFileSync(configPath, 'utf-8');
+        try {
+            cfg = JSON.parse(raw);
+            if (!cfg.mcpServers)
+                cfg.mcpServers = {};
+        }
+        catch (e) {
+            throw new Error(`Cannot parse ${configPath}: ${e.message}`);
+        }
+    }
+    cfg.mcpServers.lat = mcpCommand();
+    mkdirSync(join(configPath, '..'), { recursive: true });
+    writeFileSync(configPath, JSON.stringify(cfg, null, 2) + '\n');
+}
+// ── 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 setupClaudeCode(root, template) {
+    const created = [];
+    // 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
+    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.'));
+    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');
+    }
+    // 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'));
+    console.log(chalk.dim('  more visibility and makes agents more likely to use it proactively.'));
+    const mcpPath = join(root, '.mcp.json');
+    if (hasMcpServer(mcpPath)) {
+        console.log(chalk.green('  MCP server') + ' already configured');
+    }
+    else {
+        addMcpServer(mcpPath);
+        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 = [];
+    // .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');
+    }
+    // .cursor/mcp.json
+    console.log('');
+    console.log(chalk.dim('  Agents can call `lat` from the command line, but an MCP server gives lat'));
+    console.log(chalk.dim('  more visibility and makes agents more likely to use it proactively.'));
+    const mcpPath = join(root, '.cursor', 'mcp.json');
+    if (hasMcpServer(mcpPath)) {
+        console.log(chalk.green('  MCP server') + ' already configured');
+    }
+    else {
+        addMcpServer(mcpPath);
+        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 = [];
+    // .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');
+    }
+    // .vscode/mcp.json
+    console.log('');
+    console.log(chalk.dim('  Agents can call `lat` from the command line, but an MCP server gives lat'));
+    console.log(chalk.dim('  more visibility and makes agents more likely to use it proactively.'));
+    const mcpPath = join(root, '.vscode', 'mcp.json');
+    if (hasMcpServer(mcpPath)) {
+        console.log(chalk.green('  MCP server') + ' already configured');
+    }
+    else {
+        addMcpServer(mcpPath);
+        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.');
+        return;
+    }
+    // Check existing config
+    const config = readConfig();
+    const configPath = getConfigPath();
+    if (config.llm_key) {
+        console.log(chalk.green('  LLM key') +
+            ' already configured in ' +
+            chalk.dim(configPath));
+        return;
+    }
+    // Interactive prompt
+    if (!rl) {
+        console.log(chalk.yellow('  No LLM key found.') +
+            ' Set LAT_LLM_KEY env var or run ' +
+            chalk.cyan('lat init') +
+            ' interactively.');
+        return;
+    }
+    console.log('  You can provide a key now, or skip and set ' +
+        chalk.cyan('LAT_LLM_KEY') +
+        ' env var later.');
+    console.log('  Supported: OpenAI (' +
+        chalk.dim('sk-...') +
+        ') or Vercel AI Gateway (' +
+        chalk.dim('vck_...') +
+        ')');
+    console.log('');
+    const key = await prompt(rl, `  Paste your key (or press Enter to skip): `);
+    if (!key) {
+        console.log(chalk.dim('  Skipped.') +
+            ' You can set ' +
+            chalk.cyan('LAT_LLM_KEY') +
+            ' later or re-run ' +
+            chalk.cyan('lat init') +
+            '.');
+        return;
+    }
+    // Validate prefix
+    if (key.startsWith('sk-ant-')) {
+        console.log(chalk.red('  That looks like an Anthropic key.') +
+            " Anthropic doesn't offer embeddings.");
+        console.log('  lat.md needs an OpenAI (' +
+            chalk.dim('sk-...') +
+            ') or Vercel AI Gateway (' +
+            chalk.dim('vck_...') +
+            ') key.');
+        return;
+    }
+    if (!key.startsWith('sk-') && !key.startsWith('vck_')) {
+        console.log(chalk.yellow('  Unrecognized key prefix.') +
+            ' Expected sk-... (OpenAI) or vck_... (Vercel AI Gateway).');
+        console.log('  Saving anyway — you can update it later.');
+    }
+    // Save to config
+    const updatedConfig = { ...config, llm_key: key };
+    writeConfig(updatedConfig);
+    console.log(chalk.green('  Key saved') + ' to ' + chalk.dim(configPath));
+}
+// ── Main init flow ───────────────────────────────────────────────────
 export async function initCmd(targetDir) {
     const root = resolve(targetDir ?? process.cwd());
     const latDir = join(root, 'lat.md');
@@ -40,26 +364,57 @@ export async function initCmd(targetDir) {
             cpSync(templateDir, latDir, { recursive: true });
             console.log(chalk.green('Created lat.md/'));
         }
-        // Step 2: AGENTS.md / CLAUDE.md
-        const agentsPath = join(root, 'AGENTS.md');
-        const claudePath = join(root, 'CLAUDE.md');
-        const hasAgents = existsSync(agentsPath);
-        const hasClaude = existsSync(claudePath);
-        if (!hasAgents && !hasClaude) {
-            if (await ask('Generate AGENTS.md and CLAUDE.md with lat.md instructions for coding agents?')) {
-                const template = readAgentsTemplate();
-                writeFileSync(agentsPath, template);
-                symlinkSync('AGENTS.md', claudePath);
-                console.log(chalk.green('Created AGENTS.md and CLAUDE.md → AGENTS.md'));
-            }
+        // Step 2: Which coding agents do you use?
+        console.log('');
+        console.log(chalk.bold('Which coding agents do you use?'));
+        console.log('');
+        const useClaudeCode = await ask('  Claude Code?');
+        const useCursor = await ask('  Cursor?');
+        const useCopilot = await ask('  VS Code Copilot?');
+        const useCodex = await ask('  Codex / OpenCode?');
+        const anySelected = useClaudeCode || useCursor || useCopilot || useCodex;
+        if (!anySelected) {
+            console.log('');
+            console.log(chalk.dim('No agents selected. You can re-run') +
+                ' lat init ' +
+                chalk.dim('later.'));
+            return;
         }
-        else {
-            const existing = [hasAgents && 'AGENTS.md', hasClaude && 'CLAUDE.md']
-                .filter(Boolean)
-                .join(' and ');
-            console.log(`\n${existing} already exists. Run ${chalk.cyan('lat gen agents.md')} to preview the template,` +
-                ` then incorporate its content or overwrite as needed.`);
+        console.log('');
+        const template = readAgentsTemplate();
+        // Step 3: AGENTS.md (shared by non-Claude agents)
+        const needsAgentsMd = useCursor || useCopilot || useCodex;
+        if (needsAgentsMd) {
+            setupAgentsMd(root, template);
+        }
+        // Step 4: Per-agent setup
+        if (useClaudeCode) {
+            console.log('');
+            console.log(chalk.bold('Setting up Claude Code...'));
+            await setupClaudeCode(root, template);
+        }
+        if (useCursor) {
+            console.log('');
+            console.log(chalk.bold('Setting up Cursor...'));
+            await setupCursor(root);
+        }
+        if (useCopilot) {
+            console.log('');
+            console.log(chalk.bold('Setting up VS Code Copilot...'));
+            await setupCopilot(root);
+        }
+        if (useCodex) {
+            console.log('');
+            console.log(chalk.bold('Codex / OpenCode') +
+                ' — uses AGENTS.md (already created). No additional setup needed.');
         }
+        // Step 5: LLM key setup
+        await setupLlmKey(rl);
+        console.log('');
+        console.log(chalk.green('Done!') +
+            ' Run ' +
+            chalk.cyan('lat check') +
+            ' to validate your setup.');
     }
     finally {
         rl?.close();

package/dist/src/cli/locate.js

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

package/dist/src/cli/prompt.js

@@ -1,20 +1,12 @@
 import { relative } from 'node:path';
-import { loadAllSections, findSections, flattenSections, buildFileIndex, resolveRef, } from '../lattice.js';
+import { loadAllSections, findSections, } from '../lattice.js';
 const WIKI_LINK_RE = /\[\[([^\]]+)\]\]/g;
-function formatContext(section, latDir) {
+function formatLocation(section, latDir) {
     const relPath = relative(process.cwd(), latDir + '/' + section.file + '.md');
-    const loc = `${relPath}:${section.startLine}-${section.endLine}`;
-    let text = `[${section.id}](${loc})`;
-    if (section.body) {
-        text += `: ${section.body}`;
-    }
-    return text;
+    return `${relPath}:${section.startLine}-${section.endLine}`;
 }
 export async function promptCmd(ctx, text) {
     const allSections = await loadAllSections(ctx.latDir);
-    const flat = flattenSections(allSections);
-    const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
-    const fileIndex = buildFileIndex(allSections);
     const refs = [...text.matchAll(WIKI_LINK_RE)];
     if (refs.length === 0) {
         process.stdout.write(text);
@@ -25,41 +17,43 @@ export async function promptCmd(ctx, text) {
         const target = match[1];
         if (resolved.has(target))
             continue;
-        // Resolve short refs (e.g. search#X → tests/search#X)
-        const { resolved: resolvedTarget } = resolveRef(target, sectionIds, fileIndex);
-        const q = resolvedTarget.toLowerCase();
-        const exact = flat.find((s) => s.id.toLowerCase() === q);
-        if (exact) {
-            resolved.set(target, exact);
-            continue;
-        }
-        const fuzzy = findSections(allSections, target);
-        if (fuzzy.length === 1) {
-            resolved.set(target, fuzzy[0]);
+        const matches = findSections(allSections, target);
+        if (matches.length >= 1) {
+            resolved.set(target, {
+                target,
+                best: matches[0],
+                alternatives: matches.slice(1),
+            });
             continue;
         }
-        if (fuzzy.length > 1) {
-            console.error(ctx.chalk.red(`Ambiguous reference [[${target}]].`));
-            console.error(ctx.chalk.dim('\nCould match:\n'));
-            for (const m of fuzzy) {
-                console.error('  ' + m.id);
-            }
-            console.error(ctx.chalk.dim('\nAsk the user which section they meant.'));
-            process.exit(1);
-        }
         console.error(ctx.chalk.red(`No section found for [[${target}]] (no exact, substring, or fuzzy matches).`));
         console.error(ctx.chalk.dim('Ask the user to correct the reference.'));
         process.exit(1);
     }
     // Replace [[refs]] inline
     let output = text.replace(WIKI_LINK_RE, (_match, target) => {
-        const section = resolved.get(target);
-        return `[[${section.id}]]`;
+        const ref = resolved.get(target);
+        return `[[${ref.best.section.id}]]`;
     });
-    // Append context block
+    // Append context block as nested outliner
     output += '\n\n<lat-context>\n';
-    for (const section of resolved.values()) {
-        output += formatContext(section, ctx.latDir) + '\n';
+    for (const ref of resolved.values()) {
+        const isExact = ref.best.reason === 'exact match';
+        const all = isExact ? [ref.best] : [ref.best, ...ref.alternatives];
+        if (isExact) {
+            output += `* \`[[${ref.target}]]\` is referring to:\n`;
+        }
+        else {
+            output += `* \`[[${ref.target}]]\` might be referring to either of the following:\n`;
+        }
+        for (const m of all) {
+            const reason = isExact ? '' : ` (${m.reason})`;
+            output += `  * [[${m.section.id}]]${reason}\n`;
+            output += `    * ${formatLocation(m.section, ctx.latDir)}\n`;
+            if (m.section.body) {
+                output += `    * ${m.section.body}\n`;
+            }
+        }
     }
     output += '</lat-context>\n';
     process.stdout.write(output);

package/dist/src/cli/refs.js

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { listLatticeFiles, loadAllSections, findSections, extractRefs, flattenSections, buildFileIndex, resolveRef, } from '../lattice.js';
-import { formatSectionPreview } from '../format.js';
+import { formatResultList } from '../format.js';
 import { scanCodeRefs } from '../code-refs.js';
 export async function refsCmd(ctx, query, scope) {
     const allSections = await loadAllSections(ctx.latDir);
@@ -22,13 +22,18 @@ export async function refsCmd(ctx, query, scope) {
         if (matches.length > 0) {
             console.error(ctx.chalk.dim('\nDid you mean:\n'));
             for (const m of matches) {
-                console.error('  ' + ctx.chalk.white(m.id));
+                console.error(ctx.chalk.dim('*') +
+                    ' ' +
+                    ctx.chalk.white(m.section.id) +
+                    ' ' +
+                    ctx.chalk.dim(`(${m.reason})`));
             }
         }
         process.exit(1);
     }
     const targetId = exactMatch.id.toLowerCase();
-    let hasOutput = false;
+    const mdMatches = [];
+    const codeLines = [];
     if (scope === 'md' || scope === 'md+code') {
         const files = await listLatticeFiles(ctx.latDir);
         const matchingFromSections = new Set();
@@ -44,11 +49,8 @@ export async function refsCmd(ctx, query, scope) {
         }
         if (matchingFromSections.size > 0) {
             const referrers = flat.filter((s) => matchingFromSections.has(s.id.toLowerCase()));
-            for (let i = 0; i < referrers.length; i++) {
-                if (hasOutput)
-                    console.log('');
-                console.log(formatSectionPreview(referrers[i], ctx.latDir));
-                hasOutput = true;
+            for (const s of referrers) {
+                mdMatches.push({ section: s, reason: 'wiki link' });
             }
         }
     }
@@ -58,15 +60,24 @@ export async function refsCmd(ctx, query, scope) {
         for (const ref of codeRefs) {
             const { resolved: codeResolved } = resolveRef(ref.target, sectionIds, fileIndex);
             if (codeResolved.toLowerCase() === targetId) {
-                if (hasOutput)
-                    console.log('');
-                console.log(`  ${ref.file}:${ref.line}`);
-                hasOutput = true;
+                codeLines.push(`${ref.file}:${ref.line}`);
             }
         }
     }
-    if (!hasOutput) {
+    if (mdMatches.length === 0 && codeLines.length === 0) {
         console.error(ctx.chalk.red(`No references to "${exactMatch.id}" found`));
         process.exit(1);
     }
+    if (mdMatches.length > 0) {
+        console.log(formatResultList(`References to "${exactMatch.id}":`, mdMatches, ctx.latDir));
+    }
+    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}`);
+        }
+    }
 }