lat.md 0.8.2 → 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/gen.d.ts

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

package/dist/src/cli/gen.js

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

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.d.ts

@@ -1 +1,2 @@
+export declare function readLogo(): string;
 export declare function initCmd(targetDir?: string): Promise<void>;

package/dist/src/cli/init.js

@@ -4,7 +4,7 @@ import { execSync } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 import chalk from 'chalk';
 import { findTemplatesDir } from './templates.js';
-import { readAgentsTemplate, readCursorRulesTemplate, readPiExtensionTemplate, } from './gen.js';
+import { readAgentsTemplate, readCursorRulesTemplate, readPiExtensionTemplate, readSkillTemplate, } from './gen.js';
 import { getLlmKey, getConfigPath, readConfig, writeConfig, } from '../config.js';
 import { writeInitMeta, readFileHash, contentHash } from '../init-version.js';
 import { getLocalVersion, fetchLatestVersion } from '../version.js';
@@ -314,6 +314,15 @@ async function writeTemplateFile(root, latDir, relPath, template, genTarget, lab
         ' to see the latest template.');
     return null;
 }
+// ── Shared skill setup ───────────────────────────────────────────────
+async function writeAgentsSkill(root, latDir, hashes, ask) {
+    console.log('');
+    console.log(chalk.dim('  The lat-md skill teaches the agent how to write and maintain lat.md/ files.'));
+    const skillTemplate = readSkillTemplate();
+    const skillHash = await writeTemplateFile(root, latDir, '.agents/skills/lat-md/SKILL.md', skillTemplate, 'skill.md', 'Skill (.agents/skills/lat-md/SKILL.md)', '  ', ask);
+    if (skillHash)
+        hashes['.agents/skills/lat-md/SKILL.md'] = skillHash;
+}
 // ── Per-agent setup ──────────────────────────────────────────────────
 async function setupAgentsMd(root, latDir, template, hashes, ask) {
     const hash = await writeTemplateFile(root, latDir, 'AGENTS.md', template, 'agents.md', 'AGENTS.md', '', ask);
@@ -334,6 +343,13 @@ async function setupClaudeCode(root, latDir, template, hashes, ask, style) {
     mkdirSync(claudeDir, { recursive: true });
     syncLatHooks(settingsPath, style);
     console.log(chalk.green('  Hooks') + ' synced (UserPromptSubmit + Stop)');
+    // .claude/skills/lat-md/SKILL.md — skill for authoring lat.md files
+    console.log('');
+    console.log(chalk.dim('  The lat-md skill teaches the agent how to write and maintain lat.md/ files.'));
+    const skillTemplate = readSkillTemplate();
+    const skillHash = await writeTemplateFile(root, latDir, '.claude/skills/lat-md/SKILL.md', skillTemplate, 'skill.md', 'Skill (.claude/skills/lat-md/SKILL.md)', '  ', ask);
+    if (skillHash)
+        hashes['.claude/skills/lat-md/SKILL.md'] = skillHash;
     // Ensure .claude is gitignored (settings contain local absolute paths)
     ensureGitignored(root, '.claude');
     // MCP server → .mcp.json at project root
@@ -370,6 +386,8 @@ async function setupCursor(root, latDir, hashes, ask, style) {
     }
     // Ensure .cursor/mcp.json is gitignored (it contains local absolute paths)
     ensureGitignored(root, '.cursor/mcp.json');
+    // .agents/skills/lat-md/SKILL.md — skill for authoring lat.md files
+    await writeAgentsSkill(root, latDir, hashes, ask);
     console.log('');
     console.log(chalk.yellow('  Note:') +
         ' Enable MCP in Cursor: Settings → Features → MCP → check "Enable MCP"');
@@ -391,6 +409,8 @@ async function setupCopilot(root, latDir, hashes, ask, style) {
         addMcpServer(mcpPath, 'servers', style);
         console.log(chalk.green('  MCP server') + ' registered in .vscode/mcp.json');
     }
+    // .agents/skills/lat-md/SKILL.md — skill for authoring lat.md files
+    await writeAgentsSkill(root, latDir, hashes, ask);
 }
 async function setupPi(root, latDir, hashes, ask, style) {
     // AGENTS.md — Pi reads this natively
@@ -403,6 +423,13 @@ async function setupPi(root, latDir, hashes, ask, style) {
     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;
+    // .pi/skills/lat-md/SKILL.md — skill for authoring lat.md files
+    console.log('');
+    console.log(chalk.dim('  The lat-md skill teaches the agent how to write and maintain lat.md/ files.'));
+    const skillTemplate = readSkillTemplate();
+    const skillHash = await writeTemplateFile(root, latDir, '.pi/skills/lat-md/SKILL.md', skillTemplate, 'skill.md', 'Skill (.pi/skills/lat-md/SKILL.md)', '  ', ask);
+    if (skillHash)
+        hashes['.pi/skills/lat-md/SKILL.md'] = skillHash;
     // Ensure .pi is gitignored (extension contains local absolute paths)
     ensureGitignored(root, '.pi');
 }
@@ -477,7 +504,11 @@ async function setupLlmKey(rl) {
     console.log(chalk.green('  Key saved') + ' to ' + chalk.dim(getConfigPath()));
 }
 // ── Main init flow ───────────────────────────────────────────────────
+export function readLogo() {
+    return readFileSync(join(findTemplatesDir(), 'logo.txt'), 'utf-8');
+}
 export async function initCmd(targetDir) {
+    console.log(chalk.cyan(readLogo()));
     // Upfront version check — let the user upgrade before proceeding
     process.stdout.write(chalk.dim('Checking latest version...'));
     const latest = await fetchLatestVersion();
@@ -554,7 +585,7 @@ export async function initCmd(targetDir) {
                 {
                     label: selectedAgents.length === 0
                         ? "I don't use any of these"
-                        : 'This is it: exit',
+                        : 'This is it: continue',
                     value: '__done__',
                     accent: true,
                 },
@@ -638,8 +669,9 @@ export async function initCmd(targetDir) {
         }
         if (useCodex) {
             console.log('');
-            console.log(chalk.bold('Codex / OpenCode') +
-                ' — uses AGENTS.md (already created). No additional setup needed.');
+            console.log(chalk.bold('Setting up Codex / OpenCode...'));
+            console.log(chalk.dim('  Uses AGENTS.md (already created).'));
+            await writeAgentsSkill(root, latDir, fileHashes, ask);
         }
         // Step 5: LLM key setup
         await setupLlmKey(rl);
@@ -650,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/cli/select-menu.js

@@ -32,7 +32,7 @@ export async function selectMenu(options, prompt, defaultIndex) {
                 const pointer = selected ? '❯' : ' ';
                 if (selected) {
                     if (opt.accent) {
-                        lines.push(`  ${pointer} ${chalk.bgRed.white.bold(` ${opt.label} `)}`);
+                        lines.push(`  ${pointer} ${chalk.bgGreen.black.bold(` ${opt.label} `)}`);
                     }
                     else {
                         lines.push(`  ${pointer} ${chalk.bgCyan.black.bold(` ${opt.label} `)}`);

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.8.2",
+  "version": "0.10.0",
   "description": "A knowledge graph for your codebase, written in markdown",
   "type": "module",
   "packageManager": "pnpm@10.30.2",

package/templates/logo.txt

@@ -0,0 +1,7 @@
+░██             ░██                                ░██
+░██             ░██                                ░██
+░██  ░██████  ░██████       ░█████████████   ░████████
+░██       ░██   ░██         ░██   ░██   ░██ ░██    ░██
+░██  ░███████   ░██         ░██   ░██   ░██ ░██    ░██
+░██ ░██   ░██   ░██         ░██   ░██   ░██ ░██   ░███
+░██  ░█████░██   ░███  ░██  ░██   ░██   ░██  ░█████░██

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];

package/templates/skill/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: lat-md
+description: >-
+  Writing and maintaining lat.md documentation files — structured markdown that
+  describes a project's architecture, design decisions, and test specs. Use when
+  creating, editing, or reviewing files in the lat.md/ directory.
+---
+
+# lat.md Authoring Guide
+
+This skill covers the syntax, structure rules, and conventions for writing `lat.md/` files. Load it whenever you need to create or edit sections in the `lat.md/` directory.
+
+## What belongs in lat.md
+
+`lat.md/` files describe **what** the project does and **why** — domain concepts, key design decisions, business logic, and test specifications. They do NOT duplicate source code. Think of each section as an anchor that source code references back to.
+
+Good candidates for sections:
+- Architecture decisions and their rationale
+- Domain concepts and business rules
+- API contracts and protocols
+- Test specifications (what is tested and why)
+- Non-obvious constraints or invariants
+
+Bad candidates:
+- Step-by-step code walkthroughs (the code itself is the walkthrough)
+- Auto-generated API docs (use tools for that)
+- Temporary notes or TODOs
+
+## Section structure
+
+Every section **must** have a leading paragraph — at least one sentence immediately after the heading, before any child headings or other block content.
+
+The first paragraph must be ≤250 characters (excluding `[[wiki link]]` content). This paragraph is the section's identity — it appears in search results, command output, and RAG context.
+
+```markdown
+# Good Section
+
+Brief overview of what this section documents and why it matters.
+
+More detail can go in subsequent paragraphs, code blocks, or lists.
+
+## Child heading
+
+Details about this child topic.
+```
+
+```markdown
+# Bad Section
+
+## Child heading
+
+This is invalid — "Bad Section" has no leading paragraph.
+```
+
+`lat check` enforces this rule.
+
+## Section IDs
+
+Sections are addressed by file path and heading chain:
+
+- **Full form**: `lat.md/path/to/file#Heading#SubHeading`
+- **Short form**: `file#Heading#SubHeading` (when the file stem is unique)
+
+Examples: `lat.md/tests/search#RAG Replay Tests`, `cli#init`, `parser#Wiki Links`.
+
+## Wiki links
+
+Cross-reference other sections or source code with `[[target]]` or `[[target|alias]]`.
+
+### Section links
+
+```markdown
+See [[cli#init]] for setup details.
+The parser validates [[parser#Wiki Links|wiki link syntax]].
+```
+
+### Source code links
+
+Reference functions, classes, constants, and methods in source files:
+
+```markdown
+[[src/config.ts#getConfigDir]]          — function
+[[src/server.ts#App#listen]]            — class method
+[[lib/utils.py#parse_args]]             — Python function
+[[src/lib.rs#Greeter#greet]]            — Rust impl method
+[[src/app.go#Greeter#Greet]]            — Go method
+[[src/app.h#Greeter]]                   — C struct
+```
+
+`lat check` validates that all targets exist.
+
+## Code refs
+
+Tie source code back to `lat.md/` sections with `@lat:` comments:
+
+```typescript
+// @lat: [[cli#init]]
+export function init() { ... }
+```
+
+```python
+# @lat: [[cli#init]]
+def init():
+    ...
+```
+
+Supported comment styles: `//` (JS/TS/Rust/Go/C) and `#` (Python).
+
+Place one `@lat:` comment per section, at the relevant code — not at the top of the file.
+
+## Test specs
+
+Describe tests as sections in `lat.md/` files. Add frontmatter to require that every leaf section has a matching `@lat:` comment in test code:
+
+```markdown
+---
+lat:
+  require-code-mention: true
+---
+# Tests
+
+Authentication test specifications.
+
+## User login
+
+Verify credential validation and error handling.
+
+### Rejects expired tokens
+
+Tokens past their expiry timestamp are rejected with 401, even if otherwise valid.
+
+### Handles missing password
+
+Login request without a password field returns 400 with a descriptive error.
+```
+
+Each test references its spec:
+
+```python
+# @lat: [[tests#User login#Rejects expired tokens]]
+def test_rejects_expired_tokens():
+    ...
+```
+
+Rules:
+- Every leaf section under `require-code-mention: true` must be referenced by exactly one `@lat:` comment
+- Every section MUST have a description — at least one sentence explaining what the test verifies and why
+- `lat check` flags unreferenced specs and dangling code refs
+
+## Frontmatter
+
+Optional YAML frontmatter at the top of `lat.md/` files:
+
+```yaml
+---
+lat:
+  require-code-mention: true
+---
+```
+
+Currently the only supported field is `require-code-mention` for test spec enforcement.
+
+## Validation
+
+Always run `lat check` after editing `lat.md/` files. It validates:
+- All wiki links point to existing sections or source code symbols
+- All `@lat:` code refs point to existing sections
+- Every section has a leading paragraph (≤250 chars)
+- All `require-code-mention` leaf sections are referenced in code