lat.md 0.1.4 → 0.3.0

package/README.md

@@ -1,6 +1,7 @@
 # lat.md
 
 [![CI](https://github.com/1st1/lat.md/actions/workflows/ci.yml/badge.svg)](https://github.com/1st1/lat.md/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/lat.md)](https://www.npmjs.com/package/lat.md)
 
 A knowledge graph for your codebase, written in markdown.
 
@@ -26,7 +27,9 @@ The result is a structured knowledge base that:
 npm install -g lat.md
 ```
 
-Or use directly with `npx lat.md <command>`.
+Or use directly with `npx lat.md@latest <command>`.
+
+For semantic search (`lat search`), set the `LAT_LLM_KEY` environment variable with an OpenAI (`sk-...`) or Vercel AI Gateway (`vck_...`) API key.
 
 ## How it works
 

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

@@ -13,6 +13,13 @@ export type CheckResult = {
 };
 export declare function checkMd(latticeDir: string): Promise<CheckResult>;
 export declare function checkCodeRefs(latticeDir: string): Promise<CheckResult>;
+export type IndexError = {
+    dir: string;
+    message: string;
+    snippet?: string;
+};
+export declare function checkIndex(latticeDir: string): Promise<IndexError[]>;
 export declare function checkMdCmd(ctx: CliContext): Promise<void>;
 export declare function checkCodeRefsCmd(ctx: CliContext): Promise<void>;
+export declare function checkIndexCmd(ctx: CliContext): Promise<void>;
 export declare function checkAllCmd(ctx: CliContext): Promise<void>;

package/dist/src/cli/check.js

@@ -1,7 +1,27 @@
 import { readFile } from 'node:fs/promises';
-import { extname, join, relative } from 'node:path';
-import { listLatticeFiles, loadAllSections, extractRefs, flattenSections, parseFrontmatter, parseSections, } from '../lattice.js';
+import { basename, extname, join, relative } from 'node:path';
+import { listLatticeFiles, loadAllSections, extractRefs, flattenSections, parseFrontmatter, parseSections, buildFileIndex, resolveRef, } from '../lattice.js';
 import { scanCodeRefs } from '../code-refs.js';
+import { walkEntries } from '../walk.js';
+function filePart(id) {
+    const h = id.indexOf('#');
+    return h === -1 ? id : id.slice(0, h);
+}
+/** Format an ambiguous-ref error as structured markdown-like text. */
+function ambiguousMessage(target, candidates, suggested) {
+    const shortName = filePart(target);
+    const fileList = candidates.map((c) => `  - "${filePart(c)}.md"`).join('\n');
+    const lines = [];
+    if (suggested) {
+        lines.push(`ambiguous link '[[${target}]]' — did you mean '[[${suggested}]]'?`);
+    }
+    else {
+        const options = candidates.map((a) => `'[[${a}]]'`).join(', ');
+        lines.push(`ambiguous link '[[${target}]]' — multiple paths match, use either of: ${options}`);
+    }
+    lines.push(`  The short path "${shortName}" is ambiguous — ${candidates.length} files match:`, fileList, `  Please fix the link to use a fully qualified path.`);
+    return lines.join('\n');
+}
 function countByExt(paths) {
     const stats = {};
     for (const p of paths) {
@@ -15,14 +35,23 @@ export async function checkMd(latticeDir) {
     const allSections = await loadAllSections(latticeDir);
     const flat = flattenSections(allSections);
     const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
+    const fileIndex = buildFileIndex(allSections);
     const errors = [];
     for (const file of files) {
         const content = await readFile(file, 'utf-8');
-        const refs = extractRefs(file, content);
+        const refs = extractRefs(file, content, latticeDir);
         const relPath = relative(process.cwd(), file);
         for (const ref of refs) {
-            const target = ref.target.toLowerCase();
-            if (!sectionIds.has(target)) {
+            const { resolved, ambiguous, suggested } = resolveRef(ref.target, sectionIds, fileIndex);
+            if (ambiguous) {
+                errors.push({
+                    file: relPath,
+                    line: ref.line,
+                    target: ref.target,
+                    message: ambiguousMessage(ref.target, ambiguous, suggested),
+                });
+            }
+            else if (!sectionIds.has(resolved.toLowerCase())) {
                 errors.push({
                     file: relPath,
                     line: ref.line,
@@ -39,13 +68,22 @@ export async function checkCodeRefs(latticeDir) {
     const allSections = await loadAllSections(latticeDir);
     const flat = flattenSections(allSections);
     const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
+    const fileIndex = buildFileIndex(allSections);
     const scan = await scanCodeRefs(projectRoot);
     const errors = [];
     const mentionedSections = new Set();
     for (const ref of scan.refs) {
-        const target = ref.target.toLowerCase();
-        mentionedSections.add(target);
-        if (!sectionIds.has(target)) {
+        const { resolved, ambiguous, suggested } = resolveRef(ref.target, sectionIds, fileIndex);
+        mentionedSections.add(resolved.toLowerCase());
+        if (ambiguous) {
+            errors.push({
+                file: ref.file,
+                line: ref.line,
+                target: ref.target,
+                message: ambiguousMessage(ref.target, ambiguous, suggested),
+            });
+        }
+        else if (!sectionIds.has(resolved.toLowerCase())) {
             errors.push({
                 file: ref.file,
                 line: ref.line,
@@ -60,7 +98,7 @@ export async function checkCodeRefs(latticeDir) {
         const fm = parseFrontmatter(content);
         if (!fm.requireCodeMention)
             continue;
-        const sections = parseSections(file, content);
+        const sections = parseSections(file, content, latticeDir);
         const fileSections = flattenSections(sections);
         const leafSections = fileSections.filter((s) => s.children.length === 0);
         const relPath = relative(process.cwd(), file);
@@ -77,12 +115,129 @@ export async function checkCodeRefs(latticeDir) {
     }
     return { errors, files: countByExt(scan.files) };
 }
-function formatErrors(ctx, errors) {
-    for (const err of errors) {
-        console.error(`${ctx.chalk.cyan(err.file + ':' + err.line)}: ${ctx.chalk.red(err.message)}`);
+/**
+ * Extract the immediate (first-level) entries from walkEntries results.
+ * Returns unique file and directory names visible in a given directory.
+ */
+function immediateEntries(walkedPaths) {
+    const entries = new Set();
+    for (const p of walkedPaths) {
+        const slash = p.indexOf('/');
+        entries.add(slash === -1 ? p : p.slice(0, slash));
     }
-    if (errors.length > 0) {
-        console.error(ctx.chalk.red(`\n${errors.length} error${errors.length === 1 ? '' : 's'} found`));
+    return [...entries].sort();
+}
+/** Parse bullet items from an index file. Matches `- **name** — description` */
+function parseIndexEntries(content) {
+    const names = new Set();
+    const re = /^- \*\*(.+?)\*\*/gm;
+    let match;
+    while ((match = re.exec(content)) !== null) {
+        names.add(match[1]);
+    }
+    return names;
+}
+/** Generate a bullet-list snippet for the given entry names. */
+function indexSnippet(entries) {
+    return entries.map((e) => `- **${e}** — <describe>`).join('\n');
+}
+export async function checkIndex(latticeDir) {
+    const errors = [];
+    const allPaths = await walkEntries(latticeDir);
+    // Collect all directories to check (including root, represented as '')
+    const dirs = new Set(['']);
+    for (const p of allPaths) {
+        const parts = p.split('/');
+        // Add every directory prefix
+        for (let i = 1; i < parts.length; i++) {
+            dirs.add(parts.slice(0, i).join('/'));
+        }
+    }
+    for (const dir of dirs) {
+        // Determine the index file name and its expected path.
+        // The index file shares the directory's name — for `lat.md/` it's `lat.md`,
+        // for a subdir `api/` it's `api.md`.
+        const dirName = dir === '' ? basename(latticeDir) : dir.split('/').pop();
+        const indexFileName = dirName.endsWith('.md') ? dirName : dirName + '.md';
+        const indexRelPath = dir === '' ? indexFileName : dir + '/' + indexFileName;
+        // Get the immediate children of this directory
+        const prefix = dir === '' ? '' : dir + '/';
+        const childPaths = allPaths
+            .filter((p) => p.startsWith(prefix) && p !== indexRelPath)
+            .map((p) => p.slice(prefix.length));
+        const children = immediateEntries(childPaths);
+        if (children.length === 0)
+            continue;
+        // Check if the index file exists
+        const indexFullPath = join(latticeDir, indexRelPath);
+        let content;
+        try {
+            content = await readFile(indexFullPath, 'utf-8');
+        }
+        catch {
+            const relDir = dir === '' ? basename(latticeDir) + '/' : dir + '/';
+            errors.push({
+                dir: relDir,
+                message: `missing index file "${indexRelPath}" — create it with a directory listing:\n\n${indexSnippet(children)}`,
+                snippet: indexSnippet(children),
+            });
+            continue;
+        }
+        // Parse existing entries and validate
+        const listed = parseIndexEntries(content);
+        const relDir = dir === '' ? basename(latticeDir) + '/' : dir + '/';
+        const missing = [];
+        for (const child of children) {
+            if (!listed.has(child)) {
+                missing.push(child);
+            }
+        }
+        if (missing.length > 0) {
+            errors.push({
+                dir: relDir,
+                message: `"${indexRelPath}" is missing entries — add:\n\n${indexSnippet(missing)}`,
+                snippet: indexSnippet(missing),
+            });
+        }
+        for (const name of listed) {
+            if (!children.includes(name) && name !== indexFileName) {
+                errors.push({
+                    dir: relDir,
+                    message: `"${indexRelPath}" lists "${name}" but it does not exist`,
+                });
+            }
+        }
+    }
+    return errors;
+}
+function formatErrors(ctx, errors, startIdx = 0) {
+    for (let i = 0; i < errors.length; i++) {
+        const err = errors[i];
+        if (i > 0 || startIdx > 0)
+            console.error('');
+        const loc = ctx.chalk.cyan(err.file + ':' + err.line);
+        const [first, ...rest] = err.message.split('\n');
+        console.error(`- ${loc}: ${ctx.chalk.red(first)}`);
+        for (const line of rest) {
+            console.error(`  ${ctx.chalk.red(line)}`);
+        }
+    }
+}
+function formatIndexErrors(ctx, errors, startIdx = 0) {
+    for (let i = 0; i < errors.length; i++) {
+        if (i > 0 || startIdx > 0)
+            console.error('');
+        const loc = ctx.chalk.cyan(errors[i].dir);
+        const [first, ...rest] = errors[i].message.split('\n');
+        console.error(`- ${loc}: ${ctx.chalk.red(first)}`);
+        for (const line of rest) {
+            console.error(`  ${ctx.chalk.red(line)}`);
+        }
+    }
+}
+function formatErrorCount(ctx, count) {
+    if (count > 0) {
+        console.error(ctx.chalk.red(`\n${count} error${count === 1 ? '' : 's'} found`));
     }
 }
 function formatStats(ctx, stats) {
@@ -94,6 +249,7 @@ export async function checkMdCmd(ctx) {
     const { errors, files } = await checkMd(ctx.latDir);
     formatStats(ctx, files);
     formatErrors(ctx, errors);
+    formatErrorCount(ctx, errors.length);
     if (errors.length > 0)
         process.exit(1);
     console.log(ctx.chalk.green('md: All links OK'));
@@ -102,13 +258,23 @@ export async function checkCodeRefsCmd(ctx) {
     const { errors, files } = await checkCodeRefs(ctx.latDir);
     formatStats(ctx, files);
     formatErrors(ctx, errors);
+    formatErrorCount(ctx, errors.length);
     if (errors.length > 0)
         process.exit(1);
     console.log(ctx.chalk.green('code-refs: All references OK'));
 }
+export async function checkIndexCmd(ctx) {
+    const errors = await checkIndex(ctx.latDir);
+    formatIndexErrors(ctx, errors);
+    formatErrorCount(ctx, errors.length);
+    if (errors.length > 0)
+        process.exit(1);
+    console.log(ctx.chalk.green('index: All directory index files OK'));
+}
 export async function checkAllCmd(ctx) {
     const md = await checkMd(ctx.latDir);
     const code = await checkCodeRefs(ctx.latDir);
+    const indexErrors = await checkIndex(ctx.latDir);
     const allErrors = [...md.errors, ...code.errors];
     const allFiles = { ...md.files };
     for (const [ext, n] of Object.entries(code.files)) {
@@ -116,7 +282,10 @@ export async function checkAllCmd(ctx) {
     }
     formatStats(ctx, allFiles);
     formatErrors(ctx, allErrors);
-    if (allErrors.length > 0)
+    formatIndexErrors(ctx, indexErrors, allErrors.length);
+    const totalErrors = allErrors.length + indexErrors.length;
+    formatErrorCount(ctx, totalErrors);
+    if (totalErrors > 0)
         process.exit(1);
     console.log(ctx.chalk.green('All checks passed'));
 }

package/dist/src/cli/index.js

@@ -79,6 +79,14 @@ check
     const { checkCodeRefsCmd } = await import('./check.js');
     await checkCodeRefsCmd(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);
+});
 program
     .command('prompt')
     .description('Expand [[refs]] in a prompt to lat.md section locations')

package/dist/src/cli/init.js

@@ -1,4 +1,4 @@
-import { existsSync, cpSync, mkdirSync, writeFileSync, symlinkSync, } from 'node:fs';
+import { existsSync, cpSync, mkdirSync, writeFileSync, readFileSync, copyFileSync, chmodSync, symlinkSync, } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import chalk from 'chalk';
@@ -13,6 +13,49 @@ async function confirm(rl, message) {
         return true;
     }
 }
+const HOOK_COMMAND = '.claude/hooks/lat-prompt-hook.sh';
+/**
+ * Check if .claude/settings.json already has the lat-prompt hook configured.
+ */
+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;
+    }
+}
+/**
+ * Add the lat-prompt hook to .claude/settings.json, preserving existing config.
+ */
+function addLatHook(settingsPath) {
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+        }
+        catch {
+            // Corrupted file — start fresh
+        }
+    }
+    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');
+}
 export async function initCmd(targetDir) {
     const root = resolve(targetDir ?? process.cwd());
     const latDir = join(root, 'lat.md');
@@ -60,6 +103,31 @@ export async function initCmd(targetDir) {
             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.`);
         }
+        // Step 3: Claude Code prompt hook
+        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('Claude Code hook') + ' already configured');
+        }
+        else {
+            console.log('');
+            console.log(chalk.bold('Claude Code hook') +
+                ' — adds a per-prompt reminder for the agent to consult lat.md');
+            console.log(chalk.dim('  Creates .claude/hooks/lat-prompt-hook.sh and registers it in .claude/settings.json'));
+            console.log(chalk.dim('  On every prompt, the agent is instructed to run `lat search` and `lat prompt` before working.'));
+            if (await ask('Set up Claude Code prompt hook?')) {
+                mkdirSync(hooksDir, { recursive: true });
+                const templateHook = join(findTemplatesDir(), 'lat-prompt-hook.sh');
+                copyFileSync(templateHook, hookPath);
+                chmodSync(hookPath, 0o755);
+                addLatHook(settingsPath);
+                console.log(chalk.green('Created .claude/hooks/lat-prompt-hook.sh'));
+                console.log(chalk.green('Updated .claude/settings.json') +
+                    ' with UserPromptSubmit hook');
+            }
+        }
     }
     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,18 +1,12 @@
 import { relative } from 'node:path';
-import { loadAllSections, findSections, flattenSections, } 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 refs = [...text.matchAll(WIKI_LINK_RE)];
     if (refs.length === 0) {
         process.stdout.write(text);
@@ -23,39 +17,43 @@ export async function promptCmd(ctx, text) {
         const target = match[1];
         if (resolved.has(target))
             continue;
-        const q = target.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, } from '../lattice.js';
-import { formatSectionPreview } from '../format.js';
+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) {
     const allSections = await loadAllSections(ctx.latDir);
@@ -10,41 +10,47 @@ export async function refsCmd(ctx, query, scope) {
         console.error(ctx.chalk.red(`No section matching "${query}" (no exact, substring, or fuzzy matches)`));
         process.exit(1);
     }
-    // Require exact full-path match
-    const q = query.toLowerCase();
+    // 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.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();
         for (const file of files) {
             const content = await readFile(file, 'utf-8');
-            const fileRefs = extractRefs(file, content);
+            const fileRefs = extractRefs(file, content, ctx.latDir);
             for (const ref of fileRefs) {
-                if (ref.target.toLowerCase() === targetId) {
+                const { resolved: refResolved } = resolveRef(ref.target, sectionIds, fileIndex);
+                if (refResolved.toLowerCase() === targetId) {
                     matchingFromSections.add(ref.fromSection.toLowerCase());
                 }
             }
         }
         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' });
             }
         }
     }
@@ -52,16 +58,26 @@ export async function refsCmd(ctx, query, scope) {
         const projectRoot = join(ctx.latDir, '..');
         const { refs: codeRefs } = await scanCodeRefs(projectRoot);
         for (const ref of codeRefs) {
-            if (ref.target.toLowerCase() === targetId) {
-                if (hasOutput)
-                    console.log('');
-                console.log(`  ${ref.file}:${ref.line}`);
-                hasOutput = true;
+            const { resolved: codeResolved } = resolveRef(ref.target, sectionIds, fileIndex);
+            if (codeResolved.toLowerCase() === targetId) {
+                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}`);
+        }
+    }
 }

package/dist/src/cli/search.js

@@ -44,10 +44,9 @@ export async function searchCmd(ctx, query, opts) {
         const byId = new Map(flat.map((s) => [s.id, s]));
         const matched = results
             .map((r) => byId.get(r.id))
-            .filter((s) => !!s);
-        console.log(formatResultList(`Search results for "${query}":`, matched, ctx.latDir, {
-            numbered: true,
-        }));
+            .filter((s) => !!s)
+            .map((s) => ({ section: s, reason: 'semantic match' }));
+        console.log(formatResultList(`Search results for "${query}":`, matched, ctx.latDir));
     }
     finally {
         await closeDb(db);

package/dist/src/code-refs.d.ts

@@ -1,4 +1,5 @@
-/** Walk project files respecting .gitignore. Skips lat.md/, .claude/, and sub-projects. */
+/** Walk project files for code-ref scanning. Uses walkEntries for .gitignore
+ *  support, then additionally skips .md files, lat.md/, .claude/, and sub-projects. */
 export declare function walkFiles(dir: string): Promise<string[]>;
 export declare const LAT_REF_RE: RegExp;
 export type CodeRef = {

package/dist/src/code-refs.js

@@ -1,13 +1,10 @@
 import { readFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
-// @ts-expect-error -- no type declarations
-import walk from 'ignore-walk';
-/** Walk project files respecting .gitignore. Skips lat.md/, .claude/, and sub-projects. */
+import { walkEntries } from './walk.js';
+/** Walk project files for code-ref scanning. Uses walkEntries for .gitignore
+ *  support, then additionally skips .md files, lat.md/, .claude/, and sub-projects. */
 export async function walkFiles(dir) {
-    const entries = await walk({
-        path: dir,
-        ignoreFiles: ['.gitignore'],
-    });
+    const entries = await walkEntries(dir);
     // Collect directories that contain their own lat.md/ (sub-projects)
     const subProjects = new Set();
     for (const e of entries) {
@@ -17,7 +14,6 @@ export async function walkFiles(dir) {
     }
     return entries
         .filter((e) => !e.endsWith('.md') &&
-        !e.startsWith('.git/') &&
         !e.startsWith('lat.md/') &&
         !e.startsWith('.claude/') &&
         ![...subProjects].some((prefix) => e.startsWith(prefix)))

package/dist/src/format.d.ts

@@ -1,8 +1,6 @@
-import type { Section } from './lattice.js';
+import type { Section, SectionMatch } from './lattice.js';
 export declare function formatSectionId(id: string): string;
 export declare function formatSectionPreview(section: Section, latticeDir: string, opts?: {
-    index?: number;
-}): string;
-export declare function formatResultList(header: string, sections: Section[], latticeDir: string, opts?: {
-    numbered?: boolean;
+    reason?: string;
 }): string;
+export declare function formatResultList(header: string, matches: SectionMatch[], latticeDir: string): string;

package/dist/src/format.js

@@ -9,28 +9,28 @@ export function formatSectionId(id) {
 }
 export function formatSectionPreview(section, latticeDir, opts) {
     const relPath = relative(process.cwd(), latticeDir + '/' + section.file + '.md');
-    const prefix = opts?.index != null ? `${chalk.dim(`${opts.index}.`)} ` : '  ';
-    const indent = opts?.index != null ? '   ' : '  ';
+    const kind = section.id.includes('#') ? 'Section' : 'File';
+    const reasonSuffix = opts?.reason ? ' ' + chalk.dim(`(${opts.reason})`) : '';
     const lines = [
-        `${prefix}${formatSectionId(section.id)}`,
-        `${indent}${chalk.dim('Defined in')} ${chalk.cyan(relPath)}${chalk.dim(`:${section.startLine}-${section.endLine}`)}`,
+        `${chalk.dim('*')} ${chalk.dim(kind + ':')} [[${formatSectionId(section.id)}]]${reasonSuffix}`,
+        `  ${chalk.dim('Defined in')} ${chalk.cyan(relPath)}${chalk.dim(`:${section.startLine}-${section.endLine}`)}`,
     ];
     if (section.body) {
         const truncated = section.body.length > 200
             ? section.body.slice(0, 200) + '...'
             : section.body;
         lines.push('');
-        lines.push(`${indent}${chalk.dim('>')} ${truncated}`);
+        lines.push(`  ${chalk.dim('>')} ${truncated}`);
     }
     return lines.join('\n');
 }
-export function formatResultList(header, sections, latticeDir, opts) {
+export function formatResultList(header, matches, latticeDir) {
     const lines = ['', chalk.bold(header), ''];
-    for (let i = 0; i < sections.length; i++) {
+    for (let i = 0; i < matches.length; i++) {
         if (i > 0)
             lines.push('');
-        lines.push(formatSectionPreview(sections[i], latticeDir, {
-            index: opts?.numbered ? i + 1 : undefined,
+        lines.push(formatSectionPreview(matches[i].section, latticeDir, {
+            reason: matches[i].reason,
         }));
     }
     lines.push('');

package/dist/src/lattice.d.ts

@@ -21,8 +21,33 @@ export declare function parseFrontmatter(content: string): LatFrontmatter;
 export declare function stripFrontmatter(content: string): string;
 export declare function findLatticeDir(from?: string): string | null;
 export declare function listLatticeFiles(latticeDir: string): Promise<string[]>;
-export declare function parseSections(filePath: string, content: string): Section[];
+export declare function parseSections(filePath: string, content: string, latticeDir?: string): Section[];
 export declare function loadAllSections(latticeDir: string): Promise<Section[]>;
 export declare function flattenSections(sections: Section[]): Section[];
-export declare function findSections(sections: Section[], query: string): Section[];
-export declare function extractRefs(filePath: string, content: string): Ref[];
+/**
+ * Build an index mapping bare file stems to their full vault-relative paths.
+ * Used by resolveRef to allow short references when a stem is unambiguous.
+ */
+export declare function buildFileIndex(sections: Section[]): Map<string, string[]>;
+export type ResolveResult = {
+    resolved: string;
+    ambiguous: string[] | null;
+    /** When ambiguous but exactly one candidate has the section, suggest it. */
+    suggested: string | null;
+};
+/**
+ * Resolve a potentially short reference to its canonical full-path form.
+ * If the file segment of the ref is a bare stem that uniquely maps to one
+ * full path, expands it. Otherwise returns the ref unchanged.
+ *
+ * When ambiguous (multiple files share the stem), returns all candidates.
+ * If exactly one candidate actually contains the referenced section,
+ * `suggested` is set to that candidate so the caller can propose a fix.
+ */
+export declare function resolveRef(target: string, sectionIds: Set<string>, fileIndex: Map<string, string[]>): ResolveResult;
+export type SectionMatch = {
+    section: Section;
+    reason: string;
+};
+export declare function findSections(sections: Section[], query: string): SectionMatch[];
+export declare function extractRefs(filePath: string, content: string, latticeDir?: string): Ref[];

package/dist/src/lattice.js

@@ -1,7 +1,8 @@
-import { readdir, readFile } from 'node:fs/promises';
-import { dirname, join, basename, resolve } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { dirname, join, basename, relative, resolve } from 'node:path';
 import { existsSync, statSync } from 'node:fs';
 import { parse } from './parser.js';
+import { walkEntries } from './walk.js';
 import { visit } from 'unist-util-visit';
 export function parseFrontmatter(content) {
     const match = content.match(/^---\n([\s\S]*?)\n---/);
@@ -31,7 +32,7 @@ export function findLatticeDir(from) {
     }
 }
 export async function listLatticeFiles(latticeDir) {
-    const entries = await readdir(latticeDir);
+    const entries = await walkEntries(latticeDir);
     return entries
         .filter((e) => e.endsWith('.md'))
         .sort()
@@ -63,9 +64,11 @@ function lastLine(content) {
     // If trailing newline, count doesn't include empty last line
     return lines[lines.length - 1] === '' ? lines.length - 1 : lines.length;
 }
-export function parseSections(filePath, content) {
+export function parseSections(filePath, content, latticeDir) {
     const tree = parse(stripFrontmatter(content));
-    const file = basename(filePath, '.md');
+    const file = latticeDir
+        ? relative(latticeDir, filePath).replace(/\.md$/, '')
+        : basename(filePath, '.md');
     const roots = [];
     const stack = [];
     const flat = [];
@@ -128,14 +131,28 @@ export function parseSections(filePath, content) {
     }
     return roots;
 }
-export async function loadAllSections(latticeDir) {
-    const files = await listLatticeFiles(latticeDir);
-    const all = [];
-    for (const file of files) {
-        const content = await readFile(file, 'utf-8');
-        all.push(...parseSections(file, content));
+const sectionsCache = new Map();
+export function loadAllSections(latticeDir) {
+    const noCache = !!process.env._LAT_TEST_DISABLE_FS_CACHE;
+    const key = resolve(latticeDir);
+    if (!noCache) {
+        const cached = sectionsCache.get(key);
+        if (cached)
+            return cached;
     }
-    return all;
+    const result = (async () => {
+        const files = await listLatticeFiles(latticeDir);
+        const all = [];
+        for (const file of files) {
+            const content = await readFile(file, 'utf-8');
+            all.push(...parseSections(file, content, latticeDir));
+        }
+        return all;
+    })();
+    if (!noCache) {
+        sectionsCache.set(key, result);
+    }
+    return result;
 }
 export function flattenSections(sections) {
     const result = [];
@@ -176,47 +193,231 @@ function tailSegments(id) {
     }
     return tails;
 }
+/**
+ * Build an index mapping bare file stems to their full vault-relative paths.
+ * Used by resolveRef to allow short references when a stem is unambiguous.
+ */
+export function buildFileIndex(sections) {
+    const flat = flattenSections(sections);
+    const index = new Map();
+    for (const s of flat) {
+        const stem = s.file.includes('/') ? s.file.split('/').pop() : null;
+        if (stem) {
+            if (!index.has(stem))
+                index.set(stem, new Set());
+            index.get(stem).add(s.file);
+        }
+    }
+    const result = new Map();
+    for (const [stem, paths] of index) {
+        result.set(stem, [...paths]);
+    }
+    return result;
+}
+/**
+ * Resolve a potentially short reference to its canonical full-path form.
+ * If the file segment of the ref is a bare stem that uniquely maps to one
+ * full path, expands it. Otherwise returns the ref unchanged.
+ *
+ * When ambiguous (multiple files share the stem), returns all candidates.
+ * If exactly one candidate actually contains the referenced section,
+ * `suggested` is set to that candidate so the caller can propose a fix.
+ */
+export function resolveRef(target, sectionIds, fileIndex) {
+    // Already matches a known section — no resolution needed
+    if (sectionIds.has(target.toLowerCase())) {
+        return { resolved: target, ambiguous: null, suggested: null };
+    }
+    // Extract the file segment (before first #) and try resolving it
+    const hashIdx = target.indexOf('#');
+    const filePart = hashIdx === -1 ? target : target.slice(0, hashIdx);
+    const rest = hashIdx === -1 ? '' : target.slice(hashIdx);
+    const candidates = fileIndex.get(filePart) ?? [];
+    if (candidates.length === 1) {
+        const expanded = candidates[0] + rest;
+        if (sectionIds.has(expanded.toLowerCase())) {
+            return { resolved: expanded, ambiguous: null, suggested: null };
+        }
+    }
+    else if (candidates.length > 1) {
+        // Multiple files share this stem — ambiguous at the filename level
+        const all = candidates.map((c) => c + rest);
+        const valid = candidates.filter((c) => sectionIds.has((c + rest).toLowerCase()));
+        return {
+            resolved: target,
+            ambiguous: all,
+            suggested: valid.length === 1 ? valid[0] + rest : null,
+        };
+    }
+    return { resolved: target, ambiguous: null, suggested: null };
+}
 const MAX_DISTANCE_RATIO = 0.4;
 export function findSections(sections, query) {
     const flat = flattenSections(sections);
-    const q = query.toLowerCase();
-    const isFullPath = query.includes('#');
+    // Leading # means "search for a heading", strip it
+    const normalized = query.startsWith('#') ? query.slice(1) : query;
+    const q = normalized.toLowerCase();
+    const isFullPath = normalized.includes('#');
     // Tier 1: exact full-id match
     const exact = flat.filter((s) => s.id.toLowerCase() === q);
-    if (exact.length > 0 && isFullPath)
-        return exact;
+    const exactMatches = exact.map((s) => ({
+        section: s,
+        reason: 'exact match',
+    }));
+    if (exactMatches.length > 0 && isFullPath)
+        return exactMatches;
+    // Tier 1b: file stem expansion
+    // For bare names: "locate" → matches root section of "tests/locate.md"
+    // For paths with #: "setup#Install" → expands to "guides/setup#Install"
+    const fileIndex = buildFileIndex(sections);
+    const stemMatches = [];
+    if (isFullPath) {
+        // Expand file stem in the file part of the query
+        const hashIdx = normalized.indexOf('#');
+        const filePart = normalized.slice(0, hashIdx);
+        const rest = normalized.slice(hashIdx);
+        const paths = fileIndex.get(filePart) ?? [];
+        for (const p of paths) {
+            const expanded = (p + rest).toLowerCase();
+            const s = flat.find((s) => s.id.toLowerCase() === expanded && !exact.includes(s));
+            if (s)
+                stemMatches.push({
+                    section: s,
+                    reason: `file stem expanded: ${filePart} → ${p}`,
+                });
+        }
+        if (stemMatches.length > 0)
+            return [...exactMatches, ...stemMatches];
+    }
+    else {
+        // Bare name: match file root sections via stem index
+        const paths = fileIndex.get(normalized) ?? [];
+        for (const p of paths) {
+            const s = flat.find((s) => s.id.toLowerCase() === p.toLowerCase() && !exact.includes(s));
+            if (s)
+                stemMatches.push({ section: s, reason: 'file stem match' });
+        }
+    }
     // Tier 2: exact match on trailing segments (subsection name match)
+    const seen = new Set([
+        ...exact.map((s) => s.id),
+        ...stemMatches.map((m) => m.section.id),
+    ]);
     const subsection = isFullPath
         ? []
-        : flat.filter((s) => tailSegments(s.id).some((tail) => tail.toLowerCase() === q));
+        : flat
+            .filter((s) => {
+            if (seen.has(s.id))
+                return false;
+            return tailSegments(s.id).some((tail) => tail.toLowerCase() === q);
+        })
+            .map((s) => ({ section: s, reason: 'section name match' }));
+    // Tier 2b: subsequence match — query segments are a subsequence of section id segments
+    // e.g. "Markdown#Resolution Rules" matches "markdown#Wiki Links#Resolution Rules"
+    const seenSub = new Set([...seen, ...subsection.map((m) => m.section.id)]);
+    const qParts = q.split('#');
+    const subsequence = qParts.length >= 2
+        ? flat
+            .filter((s) => {
+            if (seenSub.has(s.id))
+                return false;
+            const sParts = s.id.toLowerCase().split('#');
+            if (sParts.length <= qParts.length)
+                return false;
+            let qi = 0;
+            for (const sp of sParts) {
+                if (sp === qParts[qi])
+                    qi++;
+                if (qi === qParts.length)
+                    return true;
+            }
+            return false;
+        })
+            .map((s) => {
+            const skipped = s.id.split('#').length - qParts.length;
+            return {
+                section: s,
+                reason: `path match, ${skipped} intermediate ${skipped === 1 ? 'section' : 'sections'} skipped`,
+            };
+        })
+        : [];
     // Tier 3: fuzzy match by edit distance on each segment tail and full id
-    const seen = new Set([
-        ...exact.map((s) => s.id),
-        ...subsection.map((s) => s.id),
+    const seenAll = new Set([
+        ...seenSub,
+        ...subsequence.map((m) => m.section.id),
     ]);
     const fuzzy = [];
+    // For full-path queries, extract the file and heading parts so we can
+    // fuzzy-match only the heading portion when the file part matches exactly.
+    // This prevents the shared file prefix from inflating similarity scores
+    // (e.g. "cli#locat" would otherwise fuzzy-match "cli#prompt").
+    const qHashIdx = normalized.indexOf('#');
+    const qFile = qHashIdx === -1 ? null : normalized.slice(0, qHashIdx).toLowerCase();
+    const qHeading = qHashIdx === -1 ? null : normalized.slice(qHashIdx + 1).toLowerCase();
     for (const s of flat) {
-        if (seen.has(s.id))
+        if (seenAll.has(s.id))
             continue;
         const candidates = [s.id, ...tailSegments(s.id)];
         let best = Infinity;
+        let bestCandidate = '';
         for (const c of candidates) {
-            const d = levenshtein(c.toLowerCase(), q);
-            const maxLen = Math.max(c.length, q.length);
-            if (d / maxLen <= MAX_DISTANCE_RATIO && d < best) {
+            let d;
+            let maxLen;
+            const cl = c.toLowerCase();
+            const cHashIdx = cl.indexOf('#');
+            // When both query and candidate have # and their file parts match,
+            // compare only the heading portions to avoid file-prefix inflation
+            if (qFile && qHeading && cHashIdx !== -1) {
+                const cFile = cl.slice(0, cHashIdx);
+                const cHeading = cl.slice(cHashIdx + 1);
+                if (cFile === qFile) {
+                    d = levenshtein(cHeading, qHeading);
+                    maxLen = Math.max(cHeading.length, qHeading.length);
+                }
+                else {
+                    d = levenshtein(cl, q);
+                    maxLen = Math.max(c.length, q.length);
+                }
+            }
+            else {
+                d = levenshtein(cl, q);
+                maxLen = Math.max(c.length, q.length);
+            }
+            if (maxLen > 0 && d / maxLen <= MAX_DISTANCE_RATIO && d < best) {
                 best = d;
+                bestCandidate = c;
             }
         }
         if (best < Infinity) {
-            fuzzy.push({ section: s, distance: best });
+            fuzzy.push({ section: s, distance: best, matched: bestCandidate });
         }
     }
     fuzzy.sort((a, b) => a.distance - b.distance);
-    return [...exact, ...subsection, ...fuzzy.map((f) => f.section)];
+    const fuzzyMatches = fuzzy.map((f) => ({
+        section: f.section,
+        reason: f.matched.toLowerCase() === f.section.id.toLowerCase()
+            ? `fuzzy match, distance ${f.distance}`
+            : `fuzzy match on "${f.matched}", distance ${f.distance}`,
+    }));
+    // Sort results: shallower depth first, then fewer path segments
+    const sortKey = (s) => {
+        const pathDepth = (s.file.match(/\//g) || []).length;
+        return s.depth * 100 + pathDepth;
+    };
+    const sortedStems = [...stemMatches].sort((a, b) => sortKey(a.section) - sortKey(b.section));
+    return [
+        ...exactMatches,
+        ...sortedStems,
+        ...subsection,
+        ...subsequence,
+        ...fuzzyMatches,
+    ];
 }
-export function extractRefs(filePath, content) {
+export function extractRefs(filePath, content, latticeDir) {
     const tree = parse(stripFrontmatter(content));
-    const file = basename(filePath, '.md');
+    const file = latticeDir
+        ? relative(latticeDir, filePath).replace(/\.md$/, '')
+        : basename(filePath, '.md');
     const refs = [];
     // Build a flat list of sections to determine enclosing section for each wiki link
     const flat = [];

package/dist/src/walk.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Walk a directory tree respecting .gitignore rules. Returns relative paths
+ * of all non-ignored files, excluding .git/ and dotfiles (e.g. .gitignore).
+ *
+ * Results are memoized by resolved directory path — safe because CLI commands
+ * don't modify the filesystem during a run. Set _LAT_TEST_DISABLE_FS_CACHE=1
+ * to bypass caching in tests that mutate the filesystem mid-run.
+ *
+ * This is the single entry point for all directory walking in lat.md — both
+ * code-ref scanning and lat.md/ index validation use it so .gitignore rules
+ * are consistently honored.
+ */
+export declare function walkEntries(dir: string): Promise<string[]>;

package/dist/src/walk.js

@@ -0,0 +1,32 @@
+import { resolve } from 'node:path';
+// @ts-expect-error -- no type declarations
+import walk from 'ignore-walk';
+const cache = new Map();
+/**
+ * Walk a directory tree respecting .gitignore rules. Returns relative paths
+ * of all non-ignored files, excluding .git/ and dotfiles (e.g. .gitignore).
+ *
+ * Results are memoized by resolved directory path — safe because CLI commands
+ * don't modify the filesystem during a run. Set _LAT_TEST_DISABLE_FS_CACHE=1
+ * to bypass caching in tests that mutate the filesystem mid-run.
+ *
+ * This is the single entry point for all directory walking in lat.md — both
+ * code-ref scanning and lat.md/ index validation use it so .gitignore rules
+ * are consistently honored.
+ */
+export function walkEntries(dir) {
+    const noCache = !!process.env._LAT_TEST_DISABLE_FS_CACHE;
+    if (!noCache) {
+        const cached = cache.get(resolve(dir));
+        if (cached)
+            return cached;
+    }
+    const result = walk({
+        path: dir,
+        ignoreFiles: ['.gitignore'],
+    }).then((entries) => entries.filter((e) => !e.startsWith('.git/') && !e.startsWith('.')));
+    if (!noCache) {
+        cache.set(resolve(dir), result);
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lat.md",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "description": "A knowledge graph for your codebase, written in markdown",
   "type": "module",
   "packageManager": "pnpm@10.30.2",

package/templates/AGENTS.md

@@ -33,7 +33,7 @@ If `lat search` fails because `LAT_LLM_KEY` is not set, explain to the user that
 
 # Syntax primer
 
-- **Section ids**: `file-stem#Heading#SubHeading` (e.g. `cli#search#Indexing`)
+- **Section ids**: `path/to/file#Heading#SubHeading` — full form uses vault-relative path (e.g. `tests/search#RAG Replay Tests`). Short form uses bare file name when unique (e.g. `search#RAG Replay Tests`, `cli#search#Indexing`).
 - **Wiki links**: `[[target]]` or `[[target|alias]]` — cross-references between sections
 - **Code refs**: `// @lat: [[section-id]]` (JS/TS) or `# @lat: [[section-id]]` (Python) — ties source code to concepts
 

package/templates/init/lat.md

@@ -0,0 +1 @@
+This directory defines the high-level concepts, business logic, and architecture of this project using markdown. It is managed by [lat.md](https://www.npmjs.com/package/lat.md) — a tool that anchors source code to these definitions. Install the `lat` command with `npm i -g lat.md` and run `lat --help`.

package/templates/lat-prompt-hook.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# lat.md prompt hook for Claude Code
+# Injected by `lat init` — reminds the agent to consult lat.md before working.
+#
+# This hook fires on every user prompt submission. It adds a short instruction
+# telling the agent to run `lat search` and `lat prompt` so that lat.md context
+# is consulted before any code changes.
+
+cat <<'HOOK_JSON'
+{
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": "Before starting work on this task:\n1. Run `lat search` with a query relevant to the task and read the results to understand the design intent.\n2. If the prompt contains [[refs]], run `lat prompt` on the full prompt text to resolve them.\n3. After completing work, run `lat check` to validate all links and code refs.\nDo not skip these steps."
+  }
+}
+HOOK_JSON

package/dist/src/cli.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-export {};

package/dist/src/cli.js

@@ -1,23 +0,0 @@
-#!/usr/bin/env node
-import { findLatticeDir, loadAllSections, findSections } from './lattice.js';
-const args = process.argv.slice(2);
-const command = args[0];
-if (command !== 'locate' || args.length < 2) {
-    console.error('Usage: lat locate <query>');
-    process.exit(1);
-}
-const query = args[1];
-const latticeDir = findLatticeDir();
-if (!latticeDir) {
-    console.error('No .lattice directory found');
-    process.exit(1);
-}
-const sections = await loadAllSections(latticeDir);
-const matches = findSections(sections, query);
-if (matches.length === 0) {
-    console.error(`No sections matching "${query}"`);
-    process.exit(1);
-}
-for (const m of matches) {
-    console.log(m.id);
-}

package/templates/init/README.md

@@ -1,5 +0,0 @@
-This directory defines the high-level concepts, business logic, and architecture of this project using markdown.
-
-It is managed by [lat.md](https://www.npmjs.com/package/lat.md) — a tool that anchors source code to these definitions.
-
-Install the `lat` command with `npm i -g lat.md` and run `lat --help`.