lat.md 0.9.0 → 0.10.0

package/README.md

@@ -27,9 +27,7 @@ The result is a structured knowledge base that:
 npm install -g lat.md
 ```
 
-Or use directly with `npx lat.md@latest <command>`.
-
-After installing, run `lat init` in the repo you want to use lat in.
+Then run `lat init` in the repo you want to use lat in.
 
 ## How it works
 
@@ -50,13 +48,14 @@ my-project/
 ## CLI
 
 ```bash
-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 expand "fix [[OAuth Flow]]" # expand [[refs]] in a prompt for agents
+lat init                        # scaffold a lat.md/ directory
+lat check                       # validate all wiki links and code refs
+lat locate "OAuth Flow"         # find sections by name (exact, fuzzy)
+lat section "auth#OAuth Flow"   # show a section with its links and refs
+lat refs "auth#OAuth Flow"      # find what references a section
+lat search "how do we auth?"    # semantic search via embeddings
+lat expand "fix [[OAuth Flow]]" # expand [[refs]] in a prompt for agents
+lat mcp                         # start MCP server for editor integration
 ```
 
 ## Configuration

package/dist/src/cli/check.js

@@ -131,9 +131,10 @@ export async function checkCodeRefs(latticeDir) {
     for (const ref of scan.refs) {
         const { resolved, ambiguous, suggested } = resolveRef(ref.target, sectionIds, fileIndex);
         mentionedSections.add(resolved.toLowerCase());
+        const displayPath = relative(process.cwd(), join(projectRoot, ref.file));
         if (ambiguous) {
             errors.push({
-                file: ref.file,
+                file: displayPath,
                 line: ref.line,
                 target: ref.target,
                 message: ambiguousMessage(ref.target, ambiguous, suggested),
@@ -141,7 +142,7 @@ export async function checkCodeRefs(latticeDir) {
         }
         else if (!sectionIds.has(resolved.toLowerCase())) {
             errors.push({
-                file: ref.file,
+                file: displayPath,
                 line: ref.line,
                 target: ref.target,
                 message: `@lat: [[${ref.target}]] — no matching section found`,
@@ -371,17 +372,22 @@ function formatErrorCount(count, s) {
 }
 // --- Unified command functions ---
 export async function checkAllCommand(ctx) {
+    const startTime = Date.now();
     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 elapsed = Date.now() - startTime;
     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;
     }
     const s = ctx.styler;
-    const lines = [formatFileStats(allFiles, s)];
+    const elapsedStr = elapsed < 1000 ? `${elapsed}ms` : `${(elapsed / 1000).toFixed(1)}s`;
+    const lines = [
+        formatFileStats(allFiles, s) + s.dim(` in ${elapsedStr}`),
+    ];
     // Init version warning first — user should fix setup before addressing errors
     const storedVersion = readInitVersion(ctx.latDir);
     if (storedVersion === null) {
@@ -424,6 +430,17 @@ export async function checkAllCommand(ctx) {
             s.cyan('lat init') +
             ' to configure.');
     }
+    // Suggest ripgrep if check was slow (>1s) and rg is not available
+    if (elapsed > 1000) {
+        const { hasRipgrep } = await import('../code-refs.js');
+        if (!(await hasRipgrep())) {
+            lines.push(s.yellow('Tip:') +
+                ' Install ' +
+                s.cyan('ripgrep') +
+                ' (rg) for faster code scanning.' +
+                ' See https://github.com/BurntSushi/ripgrep#installation');
+        }
+    }
     return { output: lines.join('\n') };
 }
 export async function checkMdCommand(ctx) {

package/dist/src/cli/index.js

@@ -61,7 +61,7 @@ program
     .command('refs')
     .description('Find references to a section')
     .argument('<query>', 'section id to find references for')
-    .option('--scope <scope>', 'where to search: md, code, or md+code', 'md')
+    .option('--scope <scope>', 'where to search: md, code, or md+code', 'md+code')
     .action(async (query, opts) => {
     const scope = opts.scope;
     if (scope !== 'md' && scope !== 'code' && scope !== 'md+code') {

package/dist/src/cli/init.js

@@ -682,6 +682,17 @@ export async function initCmd(targetDir) {
             ' Run ' +
             chalk.cyan('lat check') +
             ' to validate your setup.');
+        // Suggest ripgrep if not available
+        const { hasRipgrep } = await import('../code-refs.js');
+        if (!(await hasRipgrep())) {
+            console.log('');
+            console.log(chalk.yellow('Tip:') +
+                ' Install ' +
+                chalk.cyan('ripgrep') +
+                ' (rg) for faster code scanning.' +
+                ' See ' +
+                chalk.underline('https://github.com/BurntSushi/ripgrep#installation'));
+        }
     }
     finally {
         rl?.close();

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

@@ -13,8 +13,10 @@ export type RefsError = {
 };
 export type RefsResult = RefsFound | RefsError;
 /**
- * Find all sections and code locations that reference a given section.
- * Accepts any valid section id (full-path, short-form, with or without brackets).
+ * Find all sections and code locations that reference a given section or
+ * source file. Accepts section ids (full-path, short-form) and source file
+ * paths (e.g. src/app.rs#foo). Source file queries match wiki links directly
+ * without section resolution.
  */
 export declare function findRefs(ctx: CmdContext, query: string, scope: Scope): Promise<RefsResult>;
 export declare function refsCommand(ctx: CmdContext, query: string, scope: Scope): Promise<CmdResult>;

package/dist/src/cli/refs.js

@@ -1,13 +1,135 @@
 import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { extname, join, relative } from 'node:path';
 import { listLatticeFiles, loadAllSections, findSections, extractRefs, flattenSections, buildFileIndex, resolveRef, } from '../lattice.js';
 import { formatResultList } from '../format.js';
 import { scanCodeRefs } from '../code-refs.js';
+/** Extensions recognized as source code for ref queries. */
+const SOURCE_EXTS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.py',
+    '.rs',
+    '.go',
+    '.c',
+    '.h',
+]);
 /**
- * Find all sections and code locations that reference a given section.
- * Accepts any valid section id (full-path, short-form, with or without brackets).
+ * Check if a query looks like a source file path (has a recognized extension
+ * and the file exists on disk).
+ */
+function isSourceQuery(query, projectRoot) {
+    const hashIdx = query.indexOf('#');
+    const filePart = hashIdx === -1 ? query : query.slice(0, hashIdx);
+    const symbolPart = hashIdx === -1 ? '' : query.slice(hashIdx + 1);
+    const ext = extname(filePart);
+    if (!SOURCE_EXTS.has(ext))
+        return null;
+    if (!existsSync(join(projectRoot, filePart)))
+        return null;
+    return { filePart, symbolPart };
+}
+/**
+ * Find references to a source file or symbol across lat.md and code files.
+ * For file-level queries (no #symbol), matches all wiki links targeting
+ * that file or any symbol in it.
+ */
+async function findSourceRefs(latDir, projectRoot, query, scope) {
+    const hashIdx = query.indexOf('#');
+    const filePart = hashIdx === -1 ? query : query.slice(0, hashIdx);
+    const isFileLevel = hashIdx === -1;
+    const queryLower = query.toLowerCase();
+    const fileLower = filePart.toLowerCase();
+    // Build a synthetic Section for the target
+    const target = {
+        id: query,
+        heading: hashIdx === -1 ? filePart : query.slice(hashIdx + 1),
+        depth: 0,
+        file: filePart,
+        filePath: filePart,
+        children: [],
+        startLine: 0,
+        endLine: 0,
+        firstParagraph: '',
+    };
+    // Try to get real line info from the source parser
+    try {
+        const { resolveSourceSymbol } = await import('../source-parser.js');
+        if (hashIdx !== -1) {
+            const symbolPart = query.slice(hashIdx + 1);
+            const { found, symbols } = await resolveSourceSymbol(filePart, symbolPart, projectRoot);
+            if (found) {
+                const parts = symbolPart.split('#');
+                const sym = symbols.find((s) => parts.length === 1
+                    ? s.name === parts[0] && !s.parent
+                    : s.name === parts[1] && s.parent === parts[0]);
+                if (sym) {
+                    target.startLine = sym.startLine;
+                    target.endLine = sym.endLine;
+                    target.firstParagraph = sym.signature;
+                }
+            }
+        }
+    }
+    catch {
+        // source parser unavailable — proceed without line info
+    }
+    const allSections = await loadAllSections(latDir);
+    const flat = flattenSections(allSections);
+    const mdRefs = [];
+    const codeRefs = [];
+    if (scope === 'md' || scope === 'md+code') {
+        const files = await listLatticeFiles(latDir);
+        const matchingFromSections = new Set();
+        for (const file of files) {
+            const content = await readFile(file, 'utf-8');
+            const fileRefs = extractRefs(file, content, projectRoot);
+            for (const ref of fileRefs) {
+                const targetLower = ref.target.toLowerCase();
+                const matches = isFileLevel
+                    ? targetLower === fileLower || targetLower.startsWith(fileLower + '#')
+                    : targetLower === queryLower;
+                if (matches) {
+                    matchingFromSections.add(ref.fromSection.toLowerCase());
+                }
+            }
+        }
+        if (matchingFromSections.size > 0) {
+            const referrers = flat.filter((s) => matchingFromSections.has(s.id.toLowerCase()));
+            for (const s of referrers) {
+                mdRefs.push({ section: s, reason: 'wiki link' });
+            }
+        }
+    }
+    if (scope === 'code' || scope === 'md+code') {
+        const { refs: scannedRefs } = await scanCodeRefs(projectRoot);
+        for (const ref of scannedRefs) {
+            const targetLower = ref.target.toLowerCase();
+            const matches = isFileLevel
+                ? targetLower === fileLower || targetLower.startsWith(fileLower + '#')
+                : targetLower === queryLower;
+            if (matches) {
+                const displayPath = relative(process.cwd(), join(projectRoot, ref.file));
+                codeRefs.push(`${displayPath}:${ref.line}`);
+            }
+        }
+    }
+    return { kind: 'found', target, mdRefs, codeRefs };
+}
+/**
+ * Find all sections and code locations that reference a given section or
+ * source file. Accepts section ids (full-path, short-form) and source file
+ * paths (e.g. src/app.rs#foo). Source file queries match wiki links directly
+ * without section resolution.
  */
 export async function findRefs(ctx, query, scope) {
     query = query.replace(/^\[\[|\]\]$/g, '');
+    // Source file queries bypass section resolution
+    if (isSourceQuery(query, ctx.projectRoot)) {
+        return findSourceRefs(ctx.latDir, ctx.projectRoot, query, scope);
+    }
     const allSections = await loadAllSections(ctx.latDir);
     const flat = flattenSections(allSections);
     const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
@@ -58,7 +180,8 @@ export async function findRefs(ctx, query, scope) {
         for (const ref of scannedRefs) {
             const { resolved: codeResolved } = resolveRef(ref.target, sectionIds, fileIndex);
             if (codeResolved.toLowerCase() === targetId) {
-                codeRefs.push(`${ref.file}:${ref.line}`);
+                const displayPath = relative(process.cwd(), join(ctx.projectRoot, ref.file));
+                codeRefs.push(`${displayPath}:${ref.line}`);
             }
         }
     }

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

@@ -1,5 +1,16 @@
 import { type Section, type SectionMatch } from '../lattice.js';
 import type { CmdContext, CmdResult } from '../context.js';
+export type CodeBackRef = {
+    file: string;
+    line: number;
+    snippet: string;
+};
+export type SourceRef = {
+    target: string;
+    file: string;
+    line: number;
+    snippet: string;
+};
 export type SectionFound = {
     kind: 'found';
     section: Section;
@@ -8,7 +19,9 @@ export type SectionFound = {
         target: string;
         resolved: Section;
     }[];
+    outgoingSourceRefs: SourceRef[];
     incomingRefs: SectionMatch[];
+    codeRefs: CodeBackRef[];
 };
 export type SectionResult = SectionFound | {
     kind: 'no-match';

package/dist/src/cli/section.js

@@ -1,6 +1,8 @@
 import { readFile } from 'node:fs/promises';
-import { join, relative } from 'node:path';
+import { extname, join, relative } from 'node:path';
 import { loadAllSections, findSections, flattenSections, extractRefs, buildFileIndex, resolveRef, listLatticeFiles, } from '../lattice.js';
+import { scanCodeRefs } from '../code-refs.js';
+import { SOURCE_EXTENSIONS, resolveSourceSymbol } from '../source-parser.js';
 import { formatSectionId, formatNavHints } from '../format.js';
 /**
  * Look up a section by id, return its content, outgoing wiki link targets,
@@ -35,10 +37,53 @@ export async function getSection(ctx, query) {
     const sectionRefs = extractRefs(absPath, fileContent, ctx.projectRoot);
     const sectionId = section.id.toLowerCase();
     const outgoingRefs = [];
+    const outgoingSourceRefs = [];
     const seen = new Set();
     for (const ref of sectionRefs) {
         if (ref.fromSection.toLowerCase() !== sectionId)
             continue;
+        // Detect source code references by file extension
+        const hashIdx = ref.target.indexOf('#');
+        const filePart = hashIdx === -1 ? ref.target : ref.target.slice(0, hashIdx);
+        const ext = extname(filePart);
+        if (SOURCE_EXTENSIONS.has(ext)) {
+            const targetLower = ref.target.toLowerCase();
+            if (!seen.has(targetLower)) {
+                seen.add(targetLower);
+                const symbolPart = hashIdx === -1 ? '' : ref.target.slice(hashIdx + 1);
+                let line = 0;
+                let snippet = '';
+                if (symbolPart) {
+                    const { found, symbols } = await resolveSourceSymbol(filePart, symbolPart, ctx.projectRoot);
+                    if (found) {
+                        const parts = symbolPart.split('#');
+                        const sym = symbols.find((s) => parts.length === 1
+                            ? s.name === parts[0] && !s.parent
+                            : s.name === parts[1] && s.parent === parts[0]);
+                        if (sym) {
+                            line = sym.startLine;
+                            try {
+                                const src = await readFile(join(ctx.projectRoot, filePart), 'utf-8');
+                                const srcLines = src.split('\n');
+                                const start = sym.startLine - 1;
+                                const end = Math.min(srcLines.length, start + 5);
+                                snippet = srcLines.slice(start, end).join('\n');
+                            }
+                            catch {
+                                // file unreadable
+                            }
+                        }
+                    }
+                }
+                outgoingSourceRefs.push({
+                    target: ref.target,
+                    file: filePart,
+                    line,
+                    snippet,
+                });
+            }
+            continue;
+        }
         const { resolved } = resolveRef(ref.target, sectionIds, fileIndex);
         const resolvedLower = resolved.toLowerCase();
         if (seen.has(resolvedLower))
@@ -70,7 +115,36 @@ export async function getSection(ctx, query) {
             }
         }
     }
-    return { kind: 'found', section, content, outgoingRefs, incomingRefs };
+    // Find code back-references: @lat: comments pointing to this section
+    const codeRefs = [];
+    const { refs: scannedRefs } = await scanCodeRefs(ctx.projectRoot);
+    for (const ref of scannedRefs) {
+        const { resolved: codeResolved } = resolveRef(ref.target, sectionIds, fileIndex);
+        if (codeResolved.toLowerCase() === sectionId) {
+            const absFile = join(ctx.projectRoot, ref.file);
+            let snippet = '';
+            try {
+                const src = await readFile(absFile, 'utf-8');
+                const srcLines = src.split('\n');
+                const start = Math.max(0, ref.line - 1 - 2);
+                const end = Math.min(srcLines.length, ref.line - 1 + 3);
+                snippet = srcLines.slice(start, end).join('\n');
+            }
+            catch {
+                // file unreadable — skip snippet
+            }
+            codeRefs.push({ file: ref.file, line: ref.line, snippet });
+        }
+    }
+    return {
+        kind: 'found',
+        section,
+        content,
+        outgoingRefs,
+        outgoingSourceRefs,
+        incomingRefs,
+        codeRefs,
+    };
 }
 function fullEndLine(section) {
     if (section.children.length === 0)
@@ -85,7 +159,7 @@ function truncate(s, max) {
  */
 export function formatSectionOutput(ctx, result) {
     const s = ctx.styler;
-    const { section, content, outgoingRefs, incomingRefs } = result;
+    const { section, content, outgoingRefs, outgoingSourceRefs, incomingRefs, codeRefs, } = result;
     const relPath = relative(process.cwd(), join(ctx.projectRoot, section.filePath));
     const loc = `${s.cyan(relPath)}${s.dim(`:${section.startLine}-${section.endLine}`)}`;
     const quoted = content
@@ -97,7 +171,7 @@ export function formatSectionOutput(ctx, result) {
         '',
         quoted,
     ];
-    if (outgoingRefs.length > 0) {
+    if (outgoingRefs.length > 0 || outgoingSourceRefs.length > 0) {
         parts.push('', '## This section references:', '');
         for (const ref of outgoingRefs) {
             const body = ref.resolved.firstParagraph
@@ -105,6 +179,18 @@ export function formatSectionOutput(ctx, result) {
                 : '';
             parts.push(`${s.dim('*')} [[${formatSectionId(ref.resolved.id, s)}]]${body}`);
         }
+        for (const ref of outgoingSourceRefs) {
+            const loc = ref.line
+                ? `${s.dim(` (${ref.file}:${ref.line})`)}`
+                : `${s.dim(` (${ref.file})`)}`;
+            parts.push(`${s.dim('*')} [[${s.cyan(ref.target)}]]${loc}`);
+            if (ref.snippet) {
+                const snippetLines = ref.snippet.split('\n');
+                for (const line of snippetLines) {
+                    parts.push(`  ${s.dim('|')} ${line}`);
+                }
+            }
+        }
     }
     if (incomingRefs.length > 0) {
         parts.push('', '## Referenced by:', '');
@@ -115,6 +201,19 @@ export function formatSectionOutput(ctx, result) {
             parts.push(`${s.dim('*')} [[${formatSectionId(ref.section.id, s)}]]${body}`);
         }
     }
+    if (codeRefs.length > 0) {
+        parts.push('', '## Referenced by code:', '');
+        for (const ref of codeRefs) {
+            const codeRelPath = relative(process.cwd(), join(ctx.projectRoot, ref.file));
+            parts.push(`${s.dim('*')} ${s.cyan(codeRelPath)}${s.dim(`:${ref.line}`)}`);
+            if (ref.snippet) {
+                const snippetLines = ref.snippet.split('\n');
+                for (const line of snippetLines) {
+                    parts.push(`  ${s.dim('|')} ${line}`);
+                }
+            }
+        }
+    }
     parts.push(formatNavHints(ctx));
     return parts.join('\n');
 }

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

@@ -10,5 +10,8 @@ export type CodeRef = {
 export type ScanResult = {
     refs: CodeRef[];
     files: string[];
+    usedRg: boolean;
 };
+/** Check whether ripgrep (`rg`) is available on PATH. */
+export declare function hasRipgrep(): Promise<boolean>;
 export declare function scanCodeRefs(projectRoot: string): Promise<ScanResult>;

package/dist/src/code-refs.js

@@ -1,6 +1,11 @@
 import { readFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
 import { join, relative } from 'node:path';
 import { walkEntries } from './walk.js';
+/** Glob patterns used to exclude directories/files from code-ref scanning.
+ *  Shared between rg args and the TS fallback's walkFiles filter. */
+const EXCLUDE_DIRS = ['lat.md', '.claude'];
+const EXCLUDE_GLOBS = ['*.md'];
 /** 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) {
@@ -31,8 +36,141 @@ export const LAT_REF_RE = re('gv') `
     ( [^\]]+ )
   \]\]
 `;
-export async function scanCodeRefs(projectRoot) {
-    const files = await walkFiles(projectRoot);
+/**
+ * Run an external command and return stdout, or null if the command is not found
+ * or fails.
+ */
+function tryExec(cmd, args, cwd) {
+    return new Promise((resolve) => {
+        execFile(cmd, args, { cwd, maxBuffer: 50 * 1024 * 1024 }, (err, out) => {
+            if (err) {
+                // Exit code 1 with no stderr typically means "no matches" for grep/rg
+                const exitCode = err.code;
+                if (exitCode === 'ENOENT') {
+                    resolve(null); // command not found
+                    return;
+                }
+                // rg/grep exit 1 = no matches (not an error)
+                if ('status' in err &&
+                    err.status === 1 &&
+                    out === '') {
+                    resolve('');
+                    return;
+                }
+                resolve(null);
+                return;
+            }
+            resolve(out);
+        });
+    });
+}
+/**
+ * Detect sub-projects (directories containing their own lat.md/) using
+ * rg --files. Finds files inside nested lat.md/ dirs and extracts the parent
+ * directory paths. Returns paths relative to projectRoot.
+ */
+async function findSubProjects(projectRoot) {
+    // List files inside any lat.md/ dir, then extract unique parent paths.
+    // The root lat.md/ is excluded by EXCLUDE_DIRS in the caller, so we only
+    // need to find nested ones here — search for files under */lat.md/.
+    const out = await tryExec('rg', ['--files', '--glob', '**/lat.md/**', '.'], projectRoot);
+    if (!out)
+        return [];
+    const subProjects = new Set();
+    for (const line of out.split('\n')) {
+        if (!line)
+            continue;
+        const clean = line.startsWith('./') ? line.slice(2) : line;
+        // "tests/cases/foo/lat.md/specs.md" → "tests/cases/foo"
+        // Skip root lat.md/ (no parent prefix — starts with "lat.md/")
+        const idx = clean.indexOf('/lat.md/');
+        if (idx !== -1)
+            subProjects.add(clean.slice(0, idx));
+    }
+    return [...subProjects];
+}
+/** Build rg glob exclusion args. */
+function rgExcludeArgs(subProjects) {
+    const args = [];
+    for (const dir of EXCLUDE_DIRS)
+        args.push('--glob', `!${dir}/`);
+    for (const glob of EXCLUDE_GLOBS)
+        args.push('--glob', `!${glob}`);
+    for (const sp of subProjects)
+        args.push('--glob', `!${sp}/`);
+    return args;
+}
+/**
+ * Try scanning with ripgrep. Returns parsed refs and scanned file list, or null
+ * if rg is not available. rg respects .gitignore by default; we add glob
+ * exclusions for lat.md/, .claude/, *.md files, and sub-projects.
+ */
+async function tryRipgrep(projectRoot) {
+    // Detect sub-projects first so we can exclude them from all rg calls
+    const subProjects = await findSubProjects(projectRoot);
+    const excludes = rgExcludeArgs(subProjects);
+    // Search for @lat refs
+    const searchArgs = [
+        '--no-heading',
+        '--line-number',
+        '--with-filename',
+        ...excludes,
+        '@lat:.*\\[\\[',
+        '.',
+    ];
+    const out = await tryExec('rg', searchArgs, projectRoot);
+    if (out === null)
+        return null;
+    const { refs } = parseGrepOutput(out, projectRoot);
+    // List all scanned files (for stats) — rg --files is fast
+    const filesOut = await tryExec('rg', ['--files', ...excludes, '.'], projectRoot);
+    const files = (filesOut || '')
+        .split('\n')
+        .filter(Boolean)
+        .map((f) => {
+        const clean = f.startsWith('./') ? f.slice(2) : f;
+        return join(projectRoot, clean);
+    });
+    return { refs, files };
+}
+/**
+ * Parse rg output lines (file:line:content) into CodeRef entries.
+ */
+function parseGrepOutput(output, projectRoot) {
+    const refs = [];
+    if (!output.trim())
+        return { refs };
+    for (const line of output.split('\n')) {
+        if (!line)
+            continue;
+        // Format: ./path/to/file:linenum:content
+        const firstColon = line.indexOf(':');
+        if (firstColon === -1)
+            continue;
+        const secondColon = line.indexOf(':', firstColon + 1);
+        if (secondColon === -1)
+            continue;
+        let filePath = line.slice(0, firstColon);
+        const lineNum = parseInt(line.slice(firstColon + 1, secondColon), 10);
+        const content = line.slice(secondColon + 1);
+        if (isNaN(lineNum))
+            continue;
+        // Strip leading ./ from path
+        if (filePath.startsWith('./'))
+            filePath = filePath.slice(2);
+        // Extract targets using the same regex as the TS fallback
+        LAT_REF_RE.lastIndex = 0;
+        let match;
+        while ((match = LAT_REF_RE.exec(content)) !== null) {
+            refs.push({ target: match[1], file: filePath, line: lineNum });
+        }
+    }
+    return { refs };
+}
+/**
+ * TypeScript fallback: read every file and scan for @lat refs.
+ */
+async function scanWithTs(files, projectRoot) {
     const refs = [];
     for (const file of files) {
         let content;
@@ -50,11 +188,30 @@ export async function scanCodeRefs(projectRoot) {
             while ((match = LAT_REF_RE.exec(lines[i])) !== null) {
                 refs.push({
                     target: match[1],
-                    file: relative(process.cwd(), file),
+                    file: relative(projectRoot, file),
                     line: i + 1,
                 });
             }
         }
     }
-    return { refs, files };
+    return refs;
+}
+/** Check whether ripgrep (`rg`) is available on PATH. */
+export async function hasRipgrep() {
+    const result = await tryExec('rg', ['--version'], '.');
+    return result !== null;
+}
+export async function scanCodeRefs(projectRoot) {
+    // Fast path: use rg for both searching and file listing
+    // _LAT_DISABLE_RG is a test-only escape hatch to force the TS fallback
+    if (process.env._LAT_DISABLE_RG !== '1') {
+        const rgResult = await tryRipgrep(projectRoot);
+        if (rgResult !== null) {
+            return { refs: rgResult.refs, files: rgResult.files, usedRg: true };
+        }
+    }
+    // Fallback: walk files ourselves and scan with TS
+    const files = await walkFiles(projectRoot);
+    const refs = await scanWithTs(files, projectRoot);
+    return { refs, files, usedRg: false };
 }

package/dist/src/mcp/server.js

@@ -50,7 +50,7 @@ export async function startMcpServer() {
         scope: z
             .enum(['md', 'code', 'md+code'])
             .optional()
-            .default('md')
+            .default('md+code')
             .describe('Where to search: md, code, or md+code'),
     }, async ({ query, scope }) => toMcp(await refsCommand(ctx, query, scope)));
     const transport = new StdioServerTransport();

package/package.json

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

package/templates/pi-extension.ts

@@ -1,8 +1,8 @@
 import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { keyHint } from "@mariozechner/pi-coding-agent";
+import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
 import type { Theme } from "@mariozechner/pi-tui";
-import { Box, Text } from "@mariozechner/pi-tui";
+import { Box, Markdown, Text } from "@mariozechner/pi-tui";
 
 const PREVIEW_LINES = 4;
 
@@ -14,10 +14,11 @@ function collapsibleResult(
   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 mdTheme = getMarkdownTheme();
+  if (options.expanded) return new Markdown(text, 0, 0, mdTheme);
 
   const lines = text.split("\n");
-  if (lines.length <= PREVIEW_LINES) return new Text(text, 0, 0);
+  if (lines.length <= PREVIEW_LINES) return new Markdown(text, 0, 0, mdTheme);
 
   const preview = lines.slice(0, PREVIEW_LINES).join("\n");
   const remaining = lines.length - PREVIEW_LINES;
@@ -223,7 +224,8 @@ export default function (pi: ExtensionAPI) {
   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));
+      box.addChild(new Text(theme.fg("accent", "lat.md"), 0, 0));
+      box.addChild(new Markdown(message.content, 0, 0, getMarkdownTheme()));
     } else {
       const hint = keyHint("expandTools", "to expand");
       box.addChild(new Text(
@@ -238,7 +240,8 @@ export default function (pi: ExtensionAPI) {
   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));
+      box.addChild(new Text(theme.fg("warning", "lat check"), 0, 0));
+      box.addChild(new Markdown(message.content, 0, 0, getMarkdownTheme()));
     } else {
       const hint = keyHint("expandTools", "to expand");
       const firstLine = message.content.split("\n")[0];