lat.md 0.6.0 → 0.7.1

package/README.md

@@ -33,7 +33,7 @@ After installing, run `lat init` in the repo you want to use lat in.
 
 ## How it works
 
-Run `lat init` to scaffold a `lat.md/` directory, then write markdown files describing your architecture, business logic, test specs — whatever matters. Link between sections using `[[file#Section#Subsection]]` syntax. Annotate source code with `// @lat: [[section-id]]` (or `# @lat: [[section-id]]` in Python) comments to tie implementation back to concepts.
+Run `lat init` to scaffold a `lat.md/` directory, then write markdown files describing your architecture, business logic, test specs — whatever matters. Link between sections using `[[file#Section#Subsection]]` syntax. Link to source code symbols with `[[src/auth.ts#validateToken]]`. Annotate source code with `// @lat: [[section-id]]` (or `# @lat: [[section-id]]` in Python) comments to tie implementation back to concepts.
 
 ```
 my-project/
@@ -53,9 +53,10 @@ my-project/
 npx lat.md init                        # scaffold a lat.md/ directory
 npx lat.md check                       # validate all wiki links and code refs
 npx lat.md locate "OAuth Flow"         # find sections by name (exact, fuzzy)
+npx lat.md section "auth#OAuth Flow"   # show a section with its links and refs
 npx lat.md refs "auth#OAuth Flow"      # find what references a section
 npx lat.md search "how do we auth?"    # semantic search via embeddings
-npx lat.md prompt "fix [[OAuth Flow]]" # expand [[refs]] in a prompt for agents
+npx lat.md expand "fix [[OAuth Flow]]" # expand [[refs]] in a prompt for agents
 ```
 
 ## Configuration

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

@@ -1,4 +1,4 @@
-import type { CliContext } from './context.js';
+import type { CmdContext, CmdResult } from '../context.js';
 export type CheckError = {
     file: string;
     line: number;
@@ -19,7 +19,9 @@ export type IndexError = {
     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>;
+export declare function checkSections(latticeDir: string): Promise<CheckError[]>;
+export declare function checkAllCommand(ctx: CmdContext): Promise<CmdResult>;
+export declare function checkMdCommand(ctx: CmdContext): Promise<CmdResult>;
+export declare function checkCodeRefsCommand(ctx: CmdContext): Promise<CmdResult>;
+export declare function checkIndexCommand(ctx: CmdContext): Promise<CmdResult>;
+export declare function checkSectionsCommand(ctx: CmdContext): Promise<CmdResult>;

package/dist/src/cli/check.js

@@ -4,6 +4,7 @@ import { basename, dirname, 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';
+import { INIT_VERSION, readInitVersion } from '../init-version.js';
 function filePart(id) {
     const h = id.indexOf('#');
     return h === -1 ? id : id.slice(0, h);
@@ -32,7 +33,17 @@ function countByExt(paths) {
     return stats;
 }
 /** Source file extensions recognized for code wiki links. */
-const SOURCE_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.py']);
+const SOURCE_EXTS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.py',
+    '.rs',
+    '.go',
+    '.c',
+    '.h',
+]);
 function isSourcePath(target) {
     const hashIdx = target.indexOf('#');
     const filePart = hashIdx === -1 ? target : target.slice(0, hashIdx);
@@ -45,6 +56,14 @@ function isSourcePath(target) {
  */
 async function tryResolveSourceRef(target, projectRoot) {
     if (!isSourcePath(target)) {
+        // Check if it looks like a file path with an unsupported extension
+        const hashIdx = target.indexOf('#');
+        const filePart = hashIdx === -1 ? target : target.slice(0, hashIdx);
+        const ext = extname(filePart);
+        if (ext && hashIdx !== -1) {
+            const supported = [...SOURCE_EXTS].sort().join(', ');
+            return `broken link [[${target}]] — unsupported file extension "${ext}". Supported: ${supported}`;
+        }
         return `broken link [[${target}]] — no matching section found`;
     }
     const hashIdx = target.indexOf('#');
@@ -199,9 +218,22 @@ function indexSnippet(entries) {
 export async function checkIndex(latticeDir) {
     const errors = [];
     const allPaths = await walkEntries(latticeDir);
+    // Flag non-.md files — only markdown belongs in lat.md/
+    for (const p of allPaths) {
+        const name = p.includes('/') ? p.slice(p.lastIndexOf('/') + 1) : p;
+        if (!name.endsWith('.md')) {
+            const relDir = basename(latticeDir) + '/';
+            errors.push({
+                dir: relDir,
+                message: `"${p}" is not a .md file — only markdown files belong in lat.md/`,
+            });
+        }
+    }
+    // Only .md files participate in index validation
+    const mdPaths = allPaths.filter((p) => p.endsWith('.md'));
     // Collect all directories to check (including root, represented as '')
     const dirs = new Set(['']);
-    for (const p of allPaths) {
+    for (const p of mdPaths) {
         const parts = p.split('/');
         // Add every directory prefix
         for (let i = 1; i < parts.length; i++) {
@@ -217,7 +249,7 @@ export async function checkIndex(latticeDir) {
         const indexRelPath = dir === '' ? indexFileName : dir + '/' + indexFileName;
         // Get the immediate children of this directory
         const prefix = dir === '' ? '' : dir + '/';
-        const childPaths = allPaths
+        const childPaths = mdPaths
             .filter((p) => p.startsWith(prefix) && p !== indexRelPath)
             .map((p) => p.slice(prefix.length));
         const children = immediateEntries(childPaths);
@@ -270,84 +302,124 @@ export async function checkIndex(latticeDir) {
     }
     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)}`);
+// --- Section structure validation ---
+/** Max characters for the first paragraph of a section (excluding [[wiki links]]). */
+const MAX_BODY_LENGTH = 250;
+/** Count body text length excluding `[[...]]` wiki link markers and content. */
+function bodyTextLength(body) {
+    return body.replace(/\[\[[^\]]*\]\]/g, '').length;
+}
+export async function checkSections(latticeDir) {
+    const projectRoot = dirname(latticeDir);
+    const files = await listLatticeFiles(latticeDir);
+    const errors = [];
+    for (const file of files) {
+        const content = await readFile(file, 'utf-8');
+        const sections = parseSections(file, content, projectRoot);
+        const flat = flattenSections(sections);
+        const relPath = relative(process.cwd(), file);
+        for (const section of flat) {
+            if (!section.firstParagraph) {
+                errors.push({
+                    file: relPath,
+                    line: section.startLine,
+                    target: section.id,
+                    message: `section "${section.id}" has no leading paragraph. ` +
+                        `Every section must start with a brief overview (≤${MAX_BODY_LENGTH} chars) ` +
+                        `summarizing what it documents — this powers search snippets and command output.`,
+                });
+                continue;
+            }
+            const len = bodyTextLength(section.firstParagraph);
+            if (len > MAX_BODY_LENGTH) {
+                errors.push({
+                    file: relPath,
+                    line: section.startLine,
+                    target: section.id,
+                    message: `section "${section.id}" leading paragraph is ${len} characters ` +
+                        `(max ${MAX_BODY_LENGTH}, excluding [[wiki links]]). ` +
+                        `Keep the first paragraph brief — it serves as the section's summary ` +
+                        `in search results and command output. Use subsequent paragraphs for details.`,
+                });
+            }
         }
     }
+    return errors;
+}
+// --- Formatting helpers (shared by all check commands) ---
+function formatFileStats(files, s) {
+    const entries = Object.entries(files).sort(([a], [b]) => a.localeCompare(b));
+    return s.dim(`Scanned ${entries.map(([ext, n]) => `${n} ${ext}`).join(', ')}`);
 }
-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)}`);
+function formatCheckErrors(errors, s) {
+    const lines = [];
+    for (const err of errors) {
+        lines.push('');
+        const loc = s.cyan(err.file + ':' + err.line);
+        const [first, ...rest] = err.message.split('\n');
+        lines.push(`- ${loc}: ${s.red(first)}`);
         for (const line of rest) {
-            console.error(`  ${ctx.chalk.red(line)}`);
+            lines.push(`  ${s.red(line)}`);
         }
     }
+    return lines;
 }
-function formatErrorCount(ctx, count) {
-    if (count > 0) {
-        console.error(ctx.chalk.red(`\n${count} error${count === 1 ? '' : 's'} found`));
+function formatCheckIndexErrors(errors, s) {
+    const lines = [];
+    for (const err of errors) {
+        lines.push('');
+        const loc = s.cyan(err.dir);
+        const [first, ...rest] = err.message.split('\n');
+        lines.push(`- ${loc}: ${s.red(first)}`);
+        for (const line of rest) {
+            lines.push(`  ${s.red(line)}`);
+        }
     }
+    return lines;
 }
-function formatStats(ctx, stats) {
-    const entries = Object.entries(stats).sort(([a], [b]) => a.localeCompare(b));
-    const parts = entries.map(([ext, n]) => `${n} ${ext}`);
-    console.log(ctx.chalk.dim(`Scanned ${parts.join(', ')}`));
-}
-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'));
-}
-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'));
+function formatErrorCount(count, s) {
+    return s.red(`\n${count} error${count === 1 ? '' : 's'} found`);
 }
-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) {
+// --- Unified command functions ---
+export async function checkAllCommand(ctx) {
     const md = await checkMd(ctx.latDir);
     const code = await checkCodeRefs(ctx.latDir);
     const indexErrors = await checkIndex(ctx.latDir);
+    const sectionErrors = await checkSections(ctx.latDir);
     const allErrors = [...md.errors, ...code.errors];
     const allFiles = { ...md.files };
     for (const [ext, n] of Object.entries(code.files)) {
         allFiles[ext] = (allFiles[ext] || 0) + n;
     }
-    formatStats(ctx, allFiles);
-    formatErrors(ctx, allErrors);
-    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'));
+    const s = ctx.styler;
+    const lines = [formatFileStats(allFiles, s)];
+    // Init version warning first — user should fix setup before addressing errors
+    const storedVersion = readInitVersion(ctx.latDir);
+    if (storedVersion === null) {
+        lines.push('', s.yellow('Warning:') +
+            ' No init version recorded — run ' +
+            s.cyan('lat init') +
+            ' to set up agent hooks and configuration.');
+    }
+    else if (storedVersion < INIT_VERSION) {
+        lines.push('', s.yellow('Warning:') +
+            ' Your setup is outdated (v' +
+            storedVersion +
+            ' → v' +
+            INIT_VERSION +
+            '). Re-run ' +
+            s.cyan('lat init') +
+            ' to update agent hooks and configuration.');
+    }
+    lines.push(...formatCheckErrors(allErrors, s));
+    lines.push(...formatCheckIndexErrors(indexErrors, s));
+    lines.push(...formatCheckErrors(sectionErrors, s));
+    const totalErrors = allErrors.length + indexErrors.length + sectionErrors.length;
+    if (totalErrors > 0) {
+        lines.push(formatErrorCount(totalErrors, s));
+        return { output: lines.join('\n'), isError: true };
+    }
+    lines.push(s.green('All checks passed'));
     const { getLlmKey } = await import('../config.js');
     let hasKey = false;
     try {
@@ -357,10 +429,59 @@ export async function checkAllCmd(ctx) {
         // key resolution failed (e.g. empty file) — treat as missing
     }
     if (!hasKey) {
-        console.log(ctx.chalk.yellow('Warning:') +
+        lines.push(s.yellow('Warning:') +
             ' No LLM key found — semantic search (lat search) will not work.' +
             ' Provide a key via LAT_LLM_KEY, LAT_LLM_KEY_FILE, LAT_LLM_KEY_HELPER, or run ' +
-            ctx.chalk.cyan('lat init') +
+            s.cyan('lat init') +
             ' to configure.');
     }
+    return { output: lines.join('\n') };
+}
+export async function checkMdCommand(ctx) {
+    const { errors, files } = await checkMd(ctx.latDir);
+    const s = ctx.styler;
+    const lines = [formatFileStats(files, s)];
+    lines.push(...formatCheckErrors(errors, s));
+    if (errors.length > 0) {
+        lines.push(formatErrorCount(errors.length, s));
+        return { output: lines.join('\n'), isError: true };
+    }
+    lines.push(s.green('md: All links OK'));
+    return { output: lines.join('\n') };
+}
+export async function checkCodeRefsCommand(ctx) {
+    const { errors, files } = await checkCodeRefs(ctx.latDir);
+    const s = ctx.styler;
+    const lines = [formatFileStats(files, s)];
+    lines.push(...formatCheckErrors(errors, s));
+    if (errors.length > 0) {
+        lines.push(formatErrorCount(errors.length, s));
+        return { output: lines.join('\n'), isError: true };
+    }
+    lines.push(s.green('code-refs: All references OK'));
+    return { output: lines.join('\n') };
+}
+export async function checkIndexCommand(ctx) {
+    const errors = await checkIndex(ctx.latDir);
+    const s = ctx.styler;
+    const lines = [];
+    lines.push(...formatCheckIndexErrors(errors, s));
+    if (errors.length > 0) {
+        lines.push(formatErrorCount(errors.length, s));
+        return { output: lines.join('\n'), isError: true };
+    }
+    lines.push(s.green('index: All directory index files OK'));
+    return { output: lines.join('\n') };
+}
+export async function checkSectionsCommand(ctx) {
+    const errors = await checkSections(ctx.latDir);
+    const s = ctx.styler;
+    const lines = [];
+    lines.push(...formatCheckErrors(errors, s));
+    if (errors.length > 0) {
+        lines.push(formatErrorCount(errors.length, s));
+        return { output: lines.join('\n'), isError: true };
+    }
+    lines.push(s.green('sections: All sections have valid leading paragraphs'));
+    return { output: lines.join('\n') };
 }

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

@@ -1,11 +1,6 @@
-import { type ChalkInstance } from 'chalk';
-export type CliContext = {
-    latDir: string;
-    projectRoot: string;
-    color: boolean;
-    chalk: ChalkInstance;
-};
+import type { CmdContext } from '../context.js';
+export type { CmdContext };
 export declare function resolveContext(opts: {
     dir?: string;
     color?: boolean;
-}): CliContext;
+}): CmdContext;

package/dist/src/cli/context.js

@@ -1,6 +1,18 @@
 import { dirname } from 'node:path';
 import chalk from 'chalk';
 import { findLatticeDir } from '../lattice.js';
+function makeChalkStyler() {
+    return {
+        bold: (s) => chalk.bold(s),
+        dim: (s) => chalk.dim(s),
+        red: (s) => chalk.red(s),
+        cyan: (s) => chalk.cyan(s),
+        white: (s) => chalk.white(s),
+        green: (s) => chalk.green(s),
+        yellow: (s) => chalk.yellow(s),
+        boldWhite: (s) => chalk.bold.white(s),
+    };
+}
 export function resolveContext(opts) {
     const color = opts.color !== false;
     if (!color) {
@@ -13,5 +25,5 @@ export function resolveContext(opts) {
         process.exit(1);
     }
     const projectRoot = dirname(latDir);
-    return { latDir, projectRoot, color, chalk };
+    return { latDir, projectRoot, styler: makeChalkStyler(), mode: 'cli' };
 }

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

@@ -0,0 +1,7 @@
+import type { CmdContext, CmdResult } from '../context.js';
+/**
+ * Resolve [[refs]] in text and return the expanded output.
+ * Returns null if there are no wiki links, or if resolution fails.
+ */
+export declare function expandPrompt(ctx: CmdContext, text: string): Promise<string | null>;
+export declare function expandCommand(ctx: CmdContext, text: string): Promise<CmdResult>;

package/dist/src/cli/{prompt.js → expand.js}

@@ -5,14 +5,17 @@ function formatLocation(section, projectRoot) {
     const relPath = relative(process.cwd(), join(projectRoot, section.filePath));
     return `${relPath}:${section.startLine}-${section.endLine}`;
 }
-export async function promptCmd(ctx, text) {
-    const allSections = await loadAllSections(ctx.latDir);
+/**
+ * Resolve [[refs]] in text and return the expanded output.
+ * Returns null if there are no wiki links, or if resolution fails.
+ */
+export async function expandPrompt(ctx, text) {
     const refs = [...text.matchAll(WIKI_LINK_RE)];
-    if (refs.length === 0) {
-        process.stdout.write(text);
-        return;
-    }
+    if (refs.length === 0)
+        return null;
+    const allSections = await loadAllSections(ctx.latDir);
     const resolved = new Map();
+    const errors = [];
     for (const match of refs) {
         const target = match[1];
         if (resolved.has(target))
@@ -24,12 +27,13 @@ export async function promptCmd(ctx, text) {
                 best: matches[0],
                 alternatives: matches.slice(1),
             });
-            continue;
         }
-        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);
+        else {
+            errors.push(`No section found for [[${target}]]`);
+        }
     }
+    if (errors.length > 0)
+        return null;
     // Replace [[refs]] inline
     let output = text.replace(WIKI_LINK_RE, (_match, target) => {
         const ref = resolved.get(target);
@@ -51,11 +55,38 @@ export async function promptCmd(ctx, text) {
             const reason = isExact ? '' : ` (${m.reason})`;
             output += `  * [[${m.section.id}]]${reason}\n`;
             output += `    * ${formatLocation(m.section, ctx.projectRoot)}\n`;
-            if (m.section.body) {
-                output += `    * ${m.section.body}\n`;
+            if (m.section.firstParagraph) {
+                output += `    * ${m.section.firstParagraph}\n`;
             }
         }
     }
     output += '</lat-context>\n';
-    process.stdout.write(output);
+    return output;
+}
+export async function expandCommand(ctx, text) {
+    const result = await expandPrompt(ctx, text);
+    if (result === null) {
+        const refs = [...text.matchAll(WIKI_LINK_RE)];
+        if (refs.length === 0) {
+            return { output: text };
+        }
+        // Resolution failed — find which ref is broken
+        const allSections = await loadAllSections(ctx.latDir);
+        for (const match of refs) {
+            const target = match[1];
+            const matches = findSections(allSections, target);
+            if (matches.length === 0) {
+                const s = ctx.styler;
+                return {
+                    output: s.red(`No section found for [[${target}]]`) +
+                        ' (no exact, substring, or fuzzy matches).\n' +
+                        s.dim('Ask the user to correct the reference.'),
+                    isError: true,
+                };
+            }
+        }
+        // All refs matched individually but expansion still failed — shouldn't happen
+        return { output: text };
+    }
+    return { output: result };
 }

package/dist/src/cli/gen.js

@@ -9,9 +9,16 @@ export function readCursorRulesTemplate() {
 }
 export async function genCmd(target) {
     const normalized = target.toLowerCase();
-    if (normalized !== 'agents.md' && normalized !== 'claude.md') {
-        console.error(`Unknown target: ${target}. Supported: agents.md, claude.md`);
-        process.exit(1);
+    switch (normalized) {
+        case 'agents.md':
+        case 'claude.md':
+            process.stdout.write(readAgentsTemplate());
+            break;
+        case 'cursor-rules.md':
+            process.stdout.write(readCursorRulesTemplate());
+            break;
+        default:
+            console.error(`Unknown target: ${target}. Supported: agents.md, claude.md, cursor-rules.md`);
+            process.exit(1);
     }
-    process.stdout.write(readAgentsTemplate());
 }

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

@@ -0,0 +1 @@
+export declare function hookCmd(agent: string, event: string): Promise<void>;

package/dist/src/cli/hook.js

@@ -0,0 +1,147 @@
+import { dirname } from 'node:path';
+import { findLatticeDir } from '../lattice.js';
+import { plainStyler } from '../context.js';
+import { expandPrompt } from './expand.js';
+import { runSearch } from './search.js';
+import { getSection, formatSectionOutput } from './section.js';
+import { getLlmKey } from '../config.js';
+function outputPromptSubmit(context) {
+    process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: 'UserPromptSubmit',
+            additionalContext: context,
+        },
+    }));
+}
+function outputStop(reason) {
+    process.stdout.write(JSON.stringify({
+        decision: 'block',
+        reason,
+    }));
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+}
+function hasWikiLinks(text) {
+    return /\[\[[^\]]+\]\]/.test(text);
+}
+function makeHookCtx(latDir) {
+    return {
+        latDir,
+        projectRoot: dirname(latDir),
+        styler: plainStyler,
+        mode: 'cli',
+    };
+}
+async function searchAndExpand(ctx, userPrompt) {
+    let key;
+    try {
+        key = getLlmKey();
+    }
+    catch {
+        return null;
+    }
+    if (!key)
+        return null;
+    const result = await runSearch(ctx.latDir, userPrompt, key, 5);
+    if (result.matches.length === 0)
+        return null;
+    const parts = [
+        `Search results for the user prompt (${result.matches.length} matches):`,
+        '',
+    ];
+    for (const match of result.matches) {
+        const sectionResult = await getSection(ctx, match.section.id);
+        if (sectionResult.kind === 'found') {
+            parts.push(formatSectionOutput(ctx, sectionResult));
+            parts.push('');
+        }
+    }
+    return parts.join('\n');
+}
+async function handleUserPromptSubmit() {
+    let userPrompt = '';
+    try {
+        const raw = await readStdin();
+        const input = JSON.parse(raw);
+        userPrompt = input.user_prompt ?? '';
+    }
+    catch {
+        // If we can't parse stdin, still emit the reminder
+    }
+    const parts = [];
+    parts.push("Before starting work, run `lat search` with one or more queries describing the user's intent.", 'ALWAYS do this, even when the task seems straightforward — search results may reveal critical design details, protocols, or constraints.', 'Use `lat section` to read the full content of relevant matches.', 'Do not read files, write code, or run commands until you have searched.');
+    const latDir = findLatticeDir();
+    if (latDir && userPrompt) {
+        const ctx = makeHookCtx(latDir);
+        // If the user prompt contains [[refs]], resolve them inline
+        if (hasWikiLinks(userPrompt)) {
+            try {
+                const expanded = await expandPrompt(ctx, userPrompt);
+                if (expanded) {
+                    parts.push('', 'Expanded user prompt with resolved [[refs]]:', expanded);
+                }
+                else {
+                    parts.push('', 'NOTE: The user prompt contains [[refs]] but they could not be resolved. Ask the user to correct them.');
+                }
+            }
+            catch {
+                parts.push('', 'NOTE: The user prompt contains [[refs]] but resolution failed. Run `lat expand` on the prompt text manually.');
+            }
+        }
+        // Search for relevant sections and include their full content
+        try {
+            const searchContext = await searchAndExpand(ctx, userPrompt);
+            if (searchContext) {
+                parts.push('', searchContext);
+            }
+        }
+        catch {
+            // Search failed (no key, index error, etc.) — agent can search manually
+        }
+    }
+    outputPromptSubmit(parts.join('\n'));
+}
+async function handleStop() {
+    // Only emit the reminder if we're in a project with lat.md
+    const latDir = findLatticeDir();
+    if (!latDir)
+        return;
+    // Read stdin to check if we already blocked once
+    let stopHookActive = false;
+    try {
+        const raw = await readStdin();
+        const input = JSON.parse(raw);
+        stopHookActive = input.stop_hook_active ?? false;
+    }
+    catch {
+        // If we can't parse stdin, treat as first attempt
+    }
+    // Don't block twice — avoids infinite loop
+    if (stopHookActive)
+        return;
+    const parts = [];
+    parts.push('Before finishing, verify:', '- Did you update `lat.md/`? Run `lat search` with a query describing what you changed to find relevant sections that may need updating.', '- Did you run `lat check` and confirm all links and code refs pass?', 'If you made code changes but did not update lat.md/, do that now.');
+    outputStop(parts.join('\n'));
+}
+export async function hookCmd(agent, event) {
+    if (agent !== 'claude') {
+        console.error(`Unknown agent: ${agent}. Supported: claude`);
+        process.exit(1);
+    }
+    switch (event) {
+        case 'UserPromptSubmit':
+            await handleUserPromptSubmit();
+            break;
+        case 'Stop':
+            await handleStop();
+            break;
+        default:
+            console.error(`Unknown hook event: ${event}. Supported: UserPromptSubmit, Stop`);
+            process.exit(1);
+    }
+}