lat.md 0.7.1 → 0.8.0

package/dist/src/cli/check.js

@@ -3,6 +3,7 @@ import { existsSync } from 'node:fs';
 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 { SOURCE_EXTENSIONS } from '../source-parser.js';
 import { walkEntries } from '../walk.js';
 import { INIT_VERSION, readInitVersion } from '../init-version.js';
 function filePart(id) {
@@ -32,23 +33,11 @@ function countByExt(paths) {
     }
     return stats;
 }
-/** Source file extensions recognized for code wiki links. */
-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);
     const ext = extname(filePart);
-    return SOURCE_EXTS.has(ext);
+    return SOURCE_EXTENSIONS.has(ext);
 }
 /**
  * Try resolving a wiki link target as a source code reference.
@@ -61,7 +50,7 @@ async function tryResolveSourceRef(target, projectRoot) {
         const filePart = hashIdx === -1 ? target : target.slice(0, hashIdx);
         const ext = extname(filePart);
         if (ext && hashIdx !== -1) {
-            const supported = [...SOURCE_EXTS].sort().join(', ');
+            const supported = [...SOURCE_EXTENSIONS].sort().join(', ');
             return `broken link [[${target}]] — unsupported file extension "${ext}". Supported: ${supported}`;
         }
         return `broken link [[${target}]] — no matching section found`;

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

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

package/dist/src/cli/gen.js

@@ -7,6 +7,9 @@ export function readAgentsTemplate() {
 export function readCursorRulesTemplate() {
     return readFileSync(join(findTemplatesDir(), 'cursor-rules.md'), 'utf-8');
 }
+export function readPiExtensionTemplate() {
+    return readFileSync(join(findTemplatesDir(), 'pi-extension.ts'), 'utf-8');
+}
 export async function genCmd(target) {
     const normalized = target.toLowerCase();
     switch (normalized) {
@@ -17,8 +20,11 @@ export async function genCmd(target) {
         case 'cursor-rules.md':
             process.stdout.write(readCursorRulesTemplate());
             break;
+        case 'pi-extension.ts':
+            process.stdout.write(readPiExtensionTemplate());
+            break;
         default:
-            console.error(`Unknown target: ${target}. Supported: agents.md, claude.md, cursor-rules.md`);
+            console.error(`Unknown target: ${target}. Supported: agents.md, claude.md, cursor-rules.md, pi-extension.ts`);
             process.exit(1);
     }
 }

package/dist/src/cli/hook.js

@@ -1,10 +1,13 @@
-import { dirname } from 'node:path';
+import { execSync } from 'node:child_process';
+import { dirname, extname } 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';
+import { checkMd, checkCodeRefs, checkIndex, checkSections } from './check.js';
+import { SOURCE_EXTENSIONS } from '../source-parser.js';
 function outputPromptSubmit(context) {
     process.stdout.write(JSON.stringify({
         hookSpecificOutput: {
@@ -74,7 +77,7 @@ async function handleUserPromptSubmit() {
         // 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.');
+    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.', '', 'Remember: `lat.md/` must stay in sync with the codebase. If you change code, update the relevant sections in `lat.md/` and run `lat check` before finishing.');
     const latDir = findLatticeDir();
     if (latDir && userPrompt) {
         const ctx = makeHookCtx(latDir);
@@ -106,8 +109,46 @@ async function handleUserPromptSubmit() {
     }
     outputPromptSubmit(parts.join('\n'));
 }
+/** Minimum diff size (in lines) to consider "significant" code change. */
+/** Minimum code change size (lines) before we consider flagging lat.md/ sync. */
+const DIFF_THRESHOLD = 5;
+/** lat.md/ changes below this ratio of code changes trigger a sync reminder. */
+const LATMD_RATIO = 0.05;
+/** If lat.md/ changes exceed this many lines, skip the ratio check entirely. */
+const LATMD_UPPER_THRESHOLD = 50;
+/** Run `git diff --numstat` and return { codeLines, latMdLines }. */
+function analyzeDiff(projectRoot) {
+    let output;
+    try {
+        output = execSync('git diff HEAD --numstat', {
+            cwd: projectRoot,
+            encoding: 'utf-8',
+        });
+    }
+    catch {
+        return { codeLines: 0, latMdLines: 0 };
+    }
+    let codeLines = 0;
+    let latMdLines = 0;
+    // Each line: "added\tremoved\tfile" (e.g. "42\t11\tsrc/cli/hook.ts")
+    for (const line of output.split('\n')) {
+        const parts = line.split('\t');
+        if (parts.length < 3)
+            continue;
+        const added = parseInt(parts[0], 10) || 0;
+        const removed = parseInt(parts[1], 10) || 0;
+        const file = parts[2];
+        const changed = added + removed;
+        if (file.startsWith('lat.md/')) {
+            latMdLines += changed;
+        }
+        else if (SOURCE_EXTENSIONS.has(extname(file))) {
+            codeLines += changed;
+        }
+    }
+    return { codeLines, latMdLines };
+}
 async function handleStop() {
-    // Only emit the reminder if we're in a project with lat.md
     const latDir = findLatticeDir();
     if (!latDir)
         return;
@@ -121,11 +162,57 @@ async function handleStop() {
     catch {
         // If we can't parse stdin, treat as first attempt
     }
-    // Don't block twice — avoids infinite loop
-    if (stopHookActive)
+    // Always run lat check — even on second pass
+    const md = await checkMd(latDir);
+    const code = await checkCodeRefs(latDir);
+    const indexErrors = await checkIndex(latDir);
+    const sectionErrors = await checkSections(latDir);
+    const totalErrors = md.errors.length +
+        code.errors.length +
+        indexErrors.length +
+        sectionErrors.length;
+    const checkFailed = totalErrors > 0;
+    // Second pass — warn the user but don't block again
+    if (stopHookActive) {
+        if (checkFailed) {
+            console.error(`lat check is still failing (${totalErrors} error(s)). Run \`lat check\` to see details.`);
+        }
+        return;
+    }
+    const projectRoot = dirname(latDir);
+    // Analyze git diff — flag when lat.md/ changes are < 5% of code changes
+    const { codeLines, latMdLines } = analyzeDiff(projectRoot);
+    let needsSync = false;
+    if (codeLines >= DIFF_THRESHOLD && latMdLines < LATMD_UPPER_THRESHOLD) {
+        // Round up lat.md lines to 1 if nonzero (a tiny touch still counts)
+        const effectiveLatMd = latMdLines === 0 ? 0 : Math.max(latMdLines, 1);
+        needsSync = effectiveLatMd < codeLines * LATMD_RATIO;
+    }
+    // Nothing to do — let the agent stop cleanly
+    if (!checkFailed && !needsSync)
         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.');
+    const syncMsg = latMdLines === 0
+        ? 'The codebase has changes (' +
+            codeLines +
+            ' lines) but `lat.md/` was not updated.'
+        : 'The codebase has changes (' +
+            codeLines +
+            ' lines) but `lat.md/` may not be fully in sync (' +
+            latMdLines +
+            ' lines changed).';
+    if (checkFailed && needsSync) {
+        parts.push('`lat check` found errors. ' + syncMsg + ' Before finishing:', '', '1. Update `lat.md/` to reflect your code changes — run `lat search` to find relevant sections.', '2. Run `lat check` until it passes.');
+    }
+    else if (checkFailed) {
+        parts.push('`lat check` found ' +
+            totalErrors +
+            ' error(s). Run `lat check`, fix the errors, and repeat until it passes.');
+    }
+    else {
+        parts.push(syncMsg +
+            ' Verify `lat.md/` is in sync — run `lat search` to find relevant sections. Run `lat check` at the end.');
+    }
     outputStop(parts.join('\n'));
 }
 export async function hookCmd(agent, event) {

package/dist/src/cli/init.js

@@ -3,9 +3,10 @@ import { join, resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import chalk from 'chalk';
 import { findTemplatesDir } from './templates.js';
-import { readAgentsTemplate, readCursorRulesTemplate } from './gen.js';
+import { readAgentsTemplate, readCursorRulesTemplate, readPiExtensionTemplate, } from './gen.js';
 import { getConfigPath, readConfig, writeConfig, } from '../config.js';
 import { writeInitMeta, readFileHash, contentHash } from '../init-version.js';
+import { selectMenu } from './select-menu.js';
 async function confirm(rl, message) {
     while (true) {
         let answer;
@@ -35,16 +36,68 @@ async function prompt(rl, message) {
         process.exit(130);
     }
 }
+// ── Binary resolution ────────────────────────────────────────────────
+/**
+ * Return the loader-related flags from `process.execArgv`, stripping
+ * `--eval`/`-e`/`--print`/`-p` and their value arguments (those only
+ * appear when the process was started with `node -e`/`-p`).
+ */
+function loaderExecArgs() {
+    const raw = process.execArgv;
+    const args = [];
+    for (let i = 0; i < raw.length; i++) {
+        if (raw[i] === '--eval' ||
+            raw[i] === '-e' ||
+            raw[i] === '--print' ||
+            raw[i] === '-p') {
+            i++; // skip the value argument
+        }
+        else {
+            args.push(raw[i]);
+        }
+    }
+    return args;
+}
+/**
+ * Reconstruct the command prefix used to invoke this process.
+ *
+ * When running via a compiled JS entry point (e.g. the global `lat` binary),
+ * `process.argv[1]` is enough (e.g. `/usr/local/bin/lat`).
+ *
+ * When running via a TypeScript loader like tsx, the script itself can't be
+ * executed directly — we need to replay the same node flags that loaded tsx.
+ * We detect this by checking `process.execArgv` for tsx's `--import` loader
+ * and reconstruct: `node <execArgv...> <script>`.
+ */
+function resolveLatBin() {
+    const script = resolve(process.argv[1]);
+    // Not a .ts file — compiled JS or a wrapper script, use as-is.
+    if (!script.endsWith('.ts'))
+        return script;
+    // Running a .ts file: reconstruct `node <execArgv> <script>` so the
+    // same loader (tsx, ts-node, etc.) is used when the command is replayed.
+    const node = process.argv[0];
+    const execArgs = loaderExecArgs();
+    if (execArgs.length > 0) {
+        return [node, ...execArgs, script]
+            .map((a) => (a.includes(' ') ? `"${a}"` : a))
+            .join(' ');
+    }
+    // .ts file but no special loader flags — best-effort, just return the path
+    return script;
+}
 // ── Claude Code helpers ──────────────────────────────────────────────
 /** Derive the hook command prefix from the currently running binary. */
 function latHookCommand(event) {
-    return `${resolve(process.argv[1])} hook claude ${event}`;
+    return `${resolveLatBin()} hook claude ${event}`;
 }
 /** True if any command in this entry looks like it was installed by lat. */
 function isLatHookEntry(entry) {
     const bin = resolve(process.argv[1]);
     return (entry.hooks?.some((h) => typeof h.command === 'string' &&
-        (/\blat\b/.test(h.command) || h.command.startsWith(bin + ' '))) ?? false);
+        (/\blat\b/.test(h.command) ||
+            h.command.includes('hook claude ') ||
+            h.command.startsWith(bin + ' '))) ?? false);
 }
 /**
  * Remove all lat-owned hook entries from settings, then add fresh ones.
@@ -124,10 +177,31 @@ function ensureGitignored(root, entry) {
  * 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.
+ * starts the same binary. When running via tsx, emits
+ * `{ command: "node", args: ["--import", "tsx/loader", ..., "script.ts", "mcp"] }`.
  */
 function mcpCommand() {
-    return { command: resolve(process.argv[1]), args: ['mcp'] };
+    const script = resolve(process.argv[1]);
+    if (!script.endsWith('.ts')) {
+        return { command: script, args: ['mcp'] };
+    }
+    const raw = process.execArgv;
+    const execArgs = [];
+    for (let i = 0; i < raw.length; i++) {
+        if (raw[i] === '--eval' ||
+            raw[i] === '-e' ||
+            raw[i] === '--print' ||
+            raw[i] === '-p') {
+            i++;
+        }
+        else {
+            execArgs.push(raw[i]);
+        }
+    }
+    if (execArgs.length > 0) {
+        return { command: process.argv[0], args: [...execArgs, script, 'mcp'] };
+    }
+    return { command: script, args: ['mcp'] };
 }
 function hasMcpServer(configPath, key) {
     if (!existsSync(configPath))
@@ -281,6 +355,20 @@ async function setupCopilot(root, latDir, hashes, ask) {
         console.log(chalk.green('  MCP server') + ' registered in .vscode/mcp.json');
     }
 }
+async function setupPi(root, latDir, hashes, ask) {
+    // AGENTS.md — Pi reads this natively
+    // (already created in the shared step if any non-Claude agent is selected)
+    // .pi/extensions/lat.ts — extension that registers tools + lifecycle hooks
+    console.log('');
+    console.log(chalk.dim('  The Pi extension registers lat tools and hooks into the agent lifecycle'));
+    console.log(chalk.dim('  to inject search context and validate lat.md/ before finishing.'));
+    const template = readPiExtensionTemplate().replace('__LAT_BIN__', resolveLatBin());
+    const hash = await writeTemplateFile(root, latDir, '.pi/extensions/lat.ts', template, 'pi-extension.ts', 'Extension (.pi/extensions/lat.ts)', '  ', ask);
+    if (hash)
+        hashes['.pi/extensions/lat.ts'] = hash;
+    // Ensure .pi is gitignored (extension contains local absolute paths)
+    ensureGitignored(root, '.pi');
+}
 // ── LLM key setup ───────────────────────────────────────────────────
 async function setupLlmKey(rl) {
     // Check env var first
@@ -389,15 +477,43 @@ export async function initCmd(targetDir) {
             cpSync(templateDir, latDir, { recursive: true });
             console.log(chalk.green('Created lat.md/'));
         }
-        // Step 2: Which coding agents do you use?
-        console.log('');
-        console.log(chalk.bold('Which coding agents do you use?'));
+        // Step 2: Which coding agents do you use? (interactive select menu)
         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;
+        const allAgents = [
+            { label: 'Claude Code', value: 'claude' },
+            { label: 'Pi', value: 'pi' },
+            { label: 'Cursor', value: 'cursor' },
+            { label: 'VS Code Copilot', value: 'copilot' },
+            { label: 'Codex / OpenCode', value: 'codex' },
+        ];
+        const selectedAgents = [];
+        // Iterative selection: pick agents one at a time until "done"
+        while (true) {
+            const remaining = allAgents.filter((a) => !selectedAgents.includes(a.value));
+            const options = [
+                {
+                    label: selectedAgents.length === 0
+                        ? "I don't use any of these"
+                        : 'This is it: exit',
+                    value: '__done__',
+                    accent: true,
+                },
+                ...remaining,
+            ];
+            const isFirst = selectedAgents.length === 0;
+            const choice = await selectMenu(options, isFirst ? 'Which coding agent do you use?' : 'Add another agent?', isFirst ? 1 : 0);
+            if (!choice || choice === '__done__')
+                break;
+            selectedAgents.push(choice);
+            if (remaining.length === 1)
+                break; // all agents selected
+        }
+        const useClaudeCode = selectedAgents.includes('claude');
+        const usePi = selectedAgents.includes('pi');
+        const useCursor = selectedAgents.includes('cursor');
+        const useCopilot = selectedAgents.includes('copilot');
+        const useCodex = selectedAgents.includes('codex');
+        const anySelected = selectedAgents.length > 0;
         if (!anySelected) {
             console.log('');
             console.log(chalk.dim('No agents selected. You can re-run') +
@@ -409,7 +525,7 @@ export async function initCmd(targetDir) {
         const template = readAgentsTemplate();
         const fileHashes = {};
         // Step 3: AGENTS.md (shared by non-Claude agents)
-        const needsAgentsMd = useCursor || useCopilot || useCodex;
+        const needsAgentsMd = usePi || useCursor || useCopilot || useCodex;
         if (needsAgentsMd) {
             await setupAgentsMd(root, latDir, template, fileHashes, ask);
         }
@@ -419,6 +535,11 @@ export async function initCmd(targetDir) {
             console.log(chalk.bold('Setting up Claude Code...'));
             await setupClaudeCode(root, latDir, template, fileHashes, ask);
         }
+        if (usePi) {
+            console.log('');
+            console.log(chalk.bold('Setting up Pi...'));
+            await setupPi(root, latDir, fileHashes, ask);
+        }
         if (useCursor) {
             console.log('');
             console.log(chalk.bold('Setting up Cursor...'));

package/dist/src/cli/section.js

@@ -22,13 +22,12 @@ export async function getSection(ctx, query) {
         return { kind: 'no-match', suggestions: matches };
     }
     const section = top.section;
-    // Read raw content between startLine and endLine
+    // Read raw content between startLine and the end of the last descendant
     const absPath = join(ctx.projectRoot, section.filePath);
     const fileContent = await readFile(absPath, 'utf-8');
     const lines = fileContent.split('\n');
-    const content = lines
-        .slice(section.startLine - 1, section.endLine)
-        .join('\n');
+    const end = fullEndLine(section);
+    const content = lines.slice(section.startLine - 1, end).join('\n');
     // Find outgoing wiki link targets within this section's content
     const flat = flattenSections(allSections);
     const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
@@ -73,6 +72,11 @@ export async function getSection(ctx, query) {
     }
     return { kind: 'found', section, content, outgoingRefs, incomingRefs };
 }
+function fullEndLine(section) {
+    if (section.children.length === 0)
+        return section.endLine;
+    return fullEndLine(section.children[section.children.length - 1]);
+}
 function truncate(s, max) {
     return s.length > max ? s.slice(0, max) + '...' : s;
 }

package/dist/src/cli/select-menu.d.ts

@@ -0,0 +1,13 @@
+export interface SelectOption {
+    label: string;
+    value: string;
+    /** If true, this option uses a distinct highlight style (e.g. for "done" actions). */
+    accent?: boolean;
+}
+/**
+ * Display an interactive select menu with arrow-key navigation.
+ * Returns the selected option's value, or null if the user pressed Ctrl+C.
+ *
+ * @param defaultIndex - initial cursor position (defaults to 0)
+ */
+export declare function selectMenu(options: SelectOption[], prompt?: string, defaultIndex?: number): Promise<string | null>;

package/dist/src/cli/select-menu.js

@@ -0,0 +1,98 @@
+import chalk from 'chalk';
+/**
+ * Display an interactive select menu with arrow-key navigation.
+ * Returns the selected option's value, or null if the user pressed Ctrl+C.
+ *
+ * @param defaultIndex - initial cursor position (defaults to 0)
+ */
+export async function selectMenu(options, prompt, defaultIndex) {
+    if (options.length === 0)
+        return null;
+    if (!process.stdin.isTTY) {
+        // Non-interactive fallback: return first option
+        return options[0].value;
+    }
+    return new Promise((resolve) => {
+        let cursor = defaultIndex ?? 0;
+        const stdin = process.stdin;
+        // Save original stdin state
+        const wasRaw = stdin.isRaw;
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding('utf-8');
+        function render() {
+            process.stdout.write('\x1B[?25l'); // hide cursor
+            const lines = [];
+            if (prompt) {
+                lines.push(chalk.bold(prompt));
+            }
+            for (let i = 0; i < options.length; i++) {
+                const opt = options[i];
+                const selected = i === cursor;
+                const pointer = selected ? '❯' : ' ';
+                if (selected) {
+                    if (opt.accent) {
+                        lines.push(`  ${pointer} ${chalk.bgRed.white.bold(` ${opt.label} `)}`);
+                    }
+                    else {
+                        lines.push(`  ${pointer} ${chalk.bgCyan.black.bold(` ${opt.label} `)}`);
+                    }
+                }
+                else {
+                    lines.push(`  ${pointer} ${chalk.dim(opt.label)}`);
+                }
+            }
+            process.stdout.write(lines.join('\n') + '\n');
+        }
+        function clearRender() {
+            const totalLines = options.length + (prompt ? 1 : 0);
+            // Move up and clear each line
+            for (let i = 0; i < totalLines; i++) {
+                process.stdout.write('\x1B[A\x1B[2K');
+            }
+        }
+        function cleanup() {
+            stdin.setRawMode(wasRaw ?? false);
+            stdin.pause();
+            process.stdout.write('\x1B[?25h'); // show cursor
+            stdin.removeListener('data', onData);
+        }
+        function onData(data) {
+            const key = data.toString();
+            // Ctrl+C
+            if (key === '\x03') {
+                clearRender();
+                cleanup();
+                console.log('');
+                process.exit(130);
+            }
+            // Enter
+            if (key === '\r' || key === '\n') {
+                clearRender();
+                cleanup();
+                const selected = options[cursor];
+                // Print the selection
+                if (prompt) {
+                    console.log(chalk.bold(prompt) + ' ' + chalk.green(selected.label));
+                }
+                resolve(selected.value);
+                return;
+            }
+            // Arrow keys (escape sequences)
+            if (key === '\x1B[A' || key === 'k') {
+                // Up
+                clearRender();
+                cursor = (cursor - 1 + options.length) % options.length;
+                render();
+            }
+            else if (key === '\x1B[B' || key === 'j') {
+                // Down
+                clearRender();
+                cursor = (cursor + 1) % options.length;
+                render();
+            }
+        }
+        stdin.on('data', onData);
+        render();
+    });
+}

package/dist/src/source-parser.d.ts

@@ -7,6 +7,8 @@ export type SourceSymbol = {
     endLine: number;
     signature: string;
 };
+/** All source file extensions that lat can parse (derived from grammarMap). */
+export declare const SOURCE_EXTENSIONS: ReadonlySet<string>;
 export declare function parseSourceSymbols(filePath: string, content: string): Promise<SourceSymbol[]>;
 /**
  * Check whether a source file path (relative to projectRoot) has a given symbol.

package/dist/src/source-parser.js

@@ -21,18 +21,22 @@ async function ensureParser() {
     }
     return parserInstance;
 }
+/** Extension → tree-sitter WASM grammar mapping. This is the single source of
+ *  truth for which source file extensions lat supports. */
+const grammarMap = {
+    '.ts': 'tree-sitter-typescript.wasm',
+    '.tsx': 'tree-sitter-tsx.wasm',
+    '.js': 'tree-sitter-javascript.wasm',
+    '.jsx': 'tree-sitter-javascript.wasm',
+    '.py': 'tree-sitter-python.wasm',
+    '.rs': 'tree-sitter-rust.wasm',
+    '.go': 'tree-sitter-go.wasm',
+    '.c': 'tree-sitter-c.wasm',
+    '.h': 'tree-sitter-c.wasm',
+};
+/** All source file extensions that lat can parse (derived from grammarMap). */
+export const SOURCE_EXTENSIONS = new Set(Object.keys(grammarMap));
 async function getLanguage(ext) {
-    const grammarMap = {
-        '.ts': 'tree-sitter-typescript.wasm',
-        '.tsx': 'tree-sitter-tsx.wasm',
-        '.js': 'tree-sitter-javascript.wasm',
-        '.jsx': 'tree-sitter-javascript.wasm',
-        '.py': 'tree-sitter-python.wasm',
-        '.rs': 'tree-sitter-rust.wasm',
-        '.go': 'tree-sitter-go.wasm',
-        '.c': 'tree-sitter-c.wasm',
-        '.h': 'tree-sitter-c.wasm',
-    };
     const wasmFile = grammarMap[ext];
     if (!wasmFile)
         return null;

package/package.json

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

package/templates/pi-extension.ts

@@ -0,0 +1,353 @@
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { keyHint } from "@mariozechner/pi-coding-agent";
+import type { Theme } from "@mariozechner/pi-tui";
+import { Box, Text } from "@mariozechner/pi-tui";
+
+const PREVIEW_LINES = 4;
+
+function collapsibleResult(
+  result: { content: Array<{ type: string; text?: string }> },
+  options: { expanded: boolean; isPartial: boolean },
+  theme: Theme,
+) {
+  const text = result.content?.[0]?.type === "text" ? (result.content[0] as { type: "text"; text: string }).text : "";
+  if (!text) return new Text(theme.fg("dim", "(empty)"), 0, 0);
+  if (options.isPartial) return new Text(theme.fg("dim", "…"), 0, 0);
+  if (options.expanded) return new Text(text, 0, 0);
+
+  const lines = text.split("\n");
+  if (lines.length <= PREVIEW_LINES) return new Text(text, 0, 0);
+
+  const preview = lines.slice(0, PREVIEW_LINES).join("\n");
+  const remaining = lines.length - PREVIEW_LINES;
+  const hint = keyHint("expandTools", "to expand");
+  return new Text(
+    preview + "\n" +
+    theme.fg("dim", `… ${remaining} more lines (${hint})`),
+    0, 0,
+  );
+}
+
+/** Absolute path to the lat binary, injected by `lat init`. */
+const LAT = "__LAT_BIN__";
+
+function run(args: string[], cwd?: string): string {
+  const { execSync } = require("child_process") as typeof import("child_process");
+  return execSync(`${LAT} ${args.join(" ")}`, {
+    cwd: cwd ?? process.cwd(),
+    encoding: "utf-8",
+    timeout: 30_000,
+  });
+}
+
+function tryRun(args: string[]): string {
+  try {
+    return run(args);
+  } catch {
+    return "";
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  // ── Tools ──────────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: "lat_search",
+    label: "lat search",
+    description: "Semantic search across lat.md sections using embeddings",
+    promptSnippet: "Search lat.md documentation by meaning",
+    promptGuidelines: [
+      "Use before starting any task to find relevant design context",
+      "Search results include section IDs you can pass to lat_section",
+    ],
+    parameters: Type.Object({
+      query: Type.String({ description: "Search query in natural language" }),
+      limit: Type.Optional(
+        Type.Number({ description: "Max results (default 5)", default: 5 }),
+      ),
+    }),
+    async execute(_id, params) {
+      const args = ["search", JSON.stringify(params.query)];
+      if (params.limit) args.push("--limit", String(params.limit));
+      const output = tryRun(args);
+      return {
+        content: [{ type: "text", text: output || "No results found." }],
+      };
+    },
+    renderCall(args, theme) {
+      return new Text(
+        theme.fg("toolTitle", theme.bold("lat search ")) +
+        theme.fg("dim", `"${args.query}"`),
+        0, 0,
+      );
+    },
+    renderResult: collapsibleResult,
+  });
+
+  pi.registerTool({
+    name: "lat_section",
+    label: "lat section",
+    description:
+      "Show full content of a lat.md section with outgoing/incoming refs",
+    promptSnippet: "Read a specific lat.md section",
+    parameters: Type.Object({
+      query: Type.String({
+        description:
+          'Section ID or name (e.g. "cli#init", "Tests#User login")',
+      }),
+    }),
+    async execute(_id, params) {
+      const output = tryRun(["section", JSON.stringify(params.query)]);
+      return {
+        content: [
+          { type: "text", text: output || "Section not found." },
+        ],
+      };
+    },
+    renderCall(args, theme) {
+      return new Text(
+        theme.fg("toolTitle", theme.bold("lat section ")) +
+        theme.fg("dim", `"${args.query}"`),
+        0, 0,
+      );
+    },
+    renderResult: collapsibleResult,
+  });
+
+  pi.registerTool({
+    name: "lat_locate",
+    label: "lat locate",
+    description:
+      "Find a section by name (exact, subsection tail, or fuzzy match)",
+    promptSnippet: "Find a lat.md section by name",
+    parameters: Type.Object({
+      query: Type.String({ description: "Section name to locate" }),
+    }),
+    async execute(_id, params) {
+      const output = tryRun(["locate", JSON.stringify(params.query)]);
+      return {
+        content: [
+          { type: "text", text: output || "No sections matching query." },
+        ],
+      };
+    },
+    renderCall(args, theme) {
+      return new Text(
+        theme.fg("toolTitle", theme.bold("lat locate ")) +
+        theme.fg("dim", `"${args.query}"`),
+        0, 0,
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "lat_check",
+    label: "lat check",
+    description:
+      "Validate all wiki links and code refs in lat.md. Returns errors or 'All checks passed'",
+    promptSnippet: "Validate lat.md links and code refs",
+    parameters: Type.Object({}),
+    async execute() {
+      try {
+        const output = run(["check"]);
+        return { content: [{ type: "text", text: output }] };
+      } catch (err: unknown) {
+        const e = err as { stdout?: string; stderr?: string };
+        return {
+          content: [{ type: "text", text: e.stdout || e.stderr || "Check failed" }],
+          isError: true,
+        };
+      }
+    },
+    renderCall(_args, theme) {
+      return new Text(
+        theme.fg("toolTitle", theme.bold("lat check")),
+        0, 0,
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "lat_expand",
+    label: "lat expand",
+    description:
+      "Expand [[refs]] in text to resolved file locations and context",
+    promptSnippet: "Resolve [[wiki links]] in text",
+    parameters: Type.Object({
+      text: Type.String({ description: "Text containing [[refs]] to expand" }),
+    }),
+    async execute(_id, params) {
+      const output = tryRun(["expand", JSON.stringify(params.text)]);
+      return {
+        content: [{ type: "text", text: output || params.text }],
+      };
+    },
+    renderCall(args, theme) {
+      const preview = args.text.length > 60 ? args.text.slice(0, 60) + "…" : args.text;
+      return new Text(
+        theme.fg("toolTitle", theme.bold("lat expand ")) +
+        theme.fg("dim", `"${preview}"`),
+        0, 0,
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "lat_refs",
+    label: "lat refs",
+    description: "Find what references a given section",
+    promptSnippet: "Find incoming references to a lat.md section",
+    parameters: Type.Object({
+      query: Type.String({
+        description: 'Section ID (e.g. "cli#init", "file#Section")',
+      }),
+    }),
+    async execute(_id, params) {
+      const output = tryRun(["refs", JSON.stringify(params.query)]);
+      return {
+        content: [{ type: "text", text: output || "No references found." }],
+      };
+    },
+    renderCall(args, theme) {
+      return new Text(
+        theme.fg("toolTitle", theme.bold("lat refs ")) +
+        theme.fg("dim", `"${args.query}"`),
+        0, 0,
+      );
+    },
+  });
+
+  // ── Message renderers ────────────────────────────────────────────
+
+  pi.registerMessageRenderer("lat-reminder", (message, { expanded }, theme) => {
+    const box = new Box(1, 1, (t) => theme.bg("customMessageBg", t));
+    if (expanded) {
+      box.addChild(new Text(theme.fg("accent", "lat.md") + " " + message.content, 0, 0));
+    } else {
+      const hint = keyHint("expandTools", "to expand");
+      box.addChild(new Text(
+        theme.fg("accent", "lat.md") + " " +
+        theme.fg("dim", `Search lat.md before starting work. Keep lat.md/ in sync. (${hint})`),
+        0, 0,
+      ));
+    }
+    return box;
+  });
+
+  pi.registerMessageRenderer("lat-check", (message, { expanded }, theme) => {
+    const box = new Box(1, 1, (t) => theme.bg("customMessageBg", t));
+    if (expanded) {
+      box.addChild(new Text(theme.fg("warning", "lat check") + " " + message.content, 0, 0));
+    } else {
+      const hint = keyHint("expandTools", "to expand");
+      const firstLine = message.content.split("\n")[0];
+      box.addChild(new Text(
+        theme.fg("warning", "lat check") + " " +
+        theme.fg("dim", `${firstLine} (${hint})`),
+        0, 0,
+      ));
+    }
+    return box;
+  });
+
+  // ── Lifecycle hooks ────────────────────────────────────────────────
+
+  // Guard to prevent agent_end from firing twice per prompt (infinite loop)
+  let agentEndFired = false;
+
+  pi.on("before_agent_start", async () => {
+    agentEndFired = false;
+
+    const reminder = [
+      "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.",
+      "",
+      "Remember: `lat.md/` must stay in sync with the codebase. If you change code, update the relevant sections in `lat.md/` and run `lat_check` before finishing.",
+    ].join("\n");
+
+    return {
+      message: {
+        customType: "lat-reminder",
+        content: reminder,
+        display: true,
+      },
+    };
+  });
+
+  pi.on("agent_end", async () => {
+    // Don't fire twice per prompt — prevents infinite loop
+    if (agentEndFired) return;
+    agentEndFired = true;
+
+    // Run lat check
+    let checkOutput: string;
+    let checkFailed = false;
+    try {
+      checkOutput = run(["check"]);
+    } catch (err: unknown) {
+      checkFailed = true;
+      checkOutput = (err as { stdout?: string }).stdout || "";
+    }
+
+    // Run git diff --numstat to check if lat.md/ is in sync
+    let needsSync = false;
+    let codeLines = 0;
+    try {
+      const { execSync } = require("child_process") as typeof import("child_process");
+      const numstat = execSync("git diff HEAD --numstat", {
+        encoding: "utf-8",
+        cwd: process.cwd(),
+      });
+
+      let latMdLines = 0;
+      for (const line of numstat.split("\n")) {
+        const parts = line.split("\t");
+        if (parts.length < 3) continue;
+        const added = parseInt(parts[0], 10) || 0;
+        const removed = parseInt(parts[1], 10) || 0;
+        const file = parts[2];
+        const changed = added + removed;
+        if (file.startsWith("lat.md/")) {
+          latMdLines += changed;
+        } else if (/\.(ts|tsx|js|jsx|py|rs|go|c|h)$/.test(file)) {
+          codeLines += changed;
+        }
+      }
+
+      if (codeLines >= 5) {
+        const effectiveLatMd = latMdLines === 0 ? 0 : Math.max(latMdLines, 1);
+        needsSync = effectiveLatMd < codeLines * 0.05;
+      }
+    } catch {
+      // git not available or no HEAD — skip diff check
+    }
+
+    if (!checkFailed && !needsSync) return;
+
+    const parts: string[] = [];
+    if (checkFailed && needsSync) {
+      parts.push(
+        `\`lat check\` found errors AND the codebase has changes (${codeLines} lines) with no updates to \`lat.md/\`. Before finishing:`,
+        "",
+        "1. Update `lat.md/` to reflect your code changes — run `lat_search` to find relevant sections.",
+        "2. Run `lat_check` until it passes.",
+      );
+    } else if (checkFailed) {
+      parts.push(
+        "`lat check` failed. Run `lat_check`, fix the errors, and repeat until it passes.",
+      );
+    } else {
+      parts.push(
+        `The codebase has changes (${codeLines} lines) but \`lat.md/\` was not updated. Update \`lat.md/\` to be in sync with the changes — run \`lat_search\` to find relevant sections. Run \`lat_check\` at the end.`,
+      );
+    }
+
+    pi.sendMessage(
+      { customType: "lat-check", content: parts.join("\n"), display: true },
+      { deliverAs: "followUp", triggerTurn: true },
+    );
+  });
+}