lat.md 0.6.0 → 0.7.1

package/dist/src/cli/refs.js

@@ -2,37 +2,37 @@ import { readFile } from 'node:fs/promises';
 import { listLatticeFiles, loadAllSections, findSections, extractRefs, flattenSections, buildFileIndex, resolveRef, } from '../lattice.js';
 import { formatResultList } from '../format.js';
 import { scanCodeRefs } from '../code-refs.js';
-export async function refsCmd(ctx, query, scope) {
+/**
+ * Find all sections and code locations that reference a given section.
+ * Accepts any valid section id (full-path, short-form, with or without brackets).
+ */
+export async function findRefs(ctx, query, scope) {
+    query = query.replace(/^\[\[|\]\]$/g, '');
     const allSections = await loadAllSections(ctx.latDir);
-    const matches = findSections(allSections, query);
-    if (matches.length === 0) {
-        console.error(ctx.chalk.red(`No section matching "${query}" (no exact, substring, or fuzzy matches)`));
-        process.exit(1);
-    }
-    // Resolve short refs and require exact match
     const flat = flattenSections(allSections);
     const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
     const fileIndex = buildFileIndex(allSections);
     const { resolved } = resolveRef(query, sectionIds, fileIndex);
     const q = resolved.toLowerCase();
-    const exactMatch = flat.find((s) => s.id.toLowerCase() === q);
-    if (!exactMatch) {
-        console.error(ctx.chalk.red(`No section "${query}" found.`));
-        if (matches.length > 0) {
-            console.error(ctx.chalk.dim('\nDid you mean:\n'));
-            for (const m of matches) {
-                console.error(ctx.chalk.dim('*') +
-                    ' ' +
-                    ctx.chalk.white(m.section.id) +
-                    ' ' +
-                    ctx.chalk.dim(`(${m.reason})`));
-            }
+    let exactMatch = flat.find((s) => s.id.toLowerCase() === q);
+    // If resolveRef didn't land on an exact id, use findSections as fallback
+    const matches = !exactMatch ? findSections(allSections, query) : [];
+    if (!exactMatch && matches.length >= 1) {
+        const top = matches[0];
+        const isConfident = top.reason === 'exact match' ||
+            top.reason.startsWith('file stem expanded') ||
+            top.reason === 'section name match';
+        if (isConfident) {
+            exactMatch = top.section;
         }
-        process.exit(1);
+    }
+    if (!exactMatch) {
+        const suggestions = matches.length > 0 ? matches : findSections(allSections, query);
+        return { kind: 'no-match', suggestions };
     }
     const targetId = exactMatch.id.toLowerCase();
-    const mdMatches = [];
-    const codeLines = [];
+    const mdRefs = [];
+    const codeRefs = [];
     if (scope === 'md' || scope === 'md+code') {
         const files = await listLatticeFiles(ctx.latDir);
         const matchingFromSections = new Set();
@@ -49,33 +49,57 @@ export async function refsCmd(ctx, query, scope) {
         if (matchingFromSections.size > 0) {
             const referrers = flat.filter((s) => matchingFromSections.has(s.id.toLowerCase()));
             for (const s of referrers) {
-                mdMatches.push({ section: s, reason: 'wiki link' });
+                mdRefs.push({ section: s, reason: 'wiki link' });
             }
         }
     }
     if (scope === 'code' || scope === 'md+code') {
-        const { refs: codeRefs } = await scanCodeRefs(ctx.projectRoot);
-        for (const ref of codeRefs) {
+        const { refs: scannedRefs } = await scanCodeRefs(ctx.projectRoot);
+        for (const ref of scannedRefs) {
             const { resolved: codeResolved } = resolveRef(ref.target, sectionIds, fileIndex);
             if (codeResolved.toLowerCase() === targetId) {
-                codeLines.push(`${ref.file}:${ref.line}`);
+                codeRefs.push(`${ref.file}:${ref.line}`);
             }
         }
     }
-    if (mdMatches.length === 0 && codeLines.length === 0) {
-        console.error(ctx.chalk.red(`No references to "${exactMatch.id}" found`));
-        process.exit(1);
+    return { kind: 'found', target: exactMatch, mdRefs, codeRefs };
+}
+export async function refsCommand(ctx, query, scope) {
+    const result = await findRefs(ctx, query, scope);
+    if (result.kind === 'no-match') {
+        const s = ctx.styler;
+        if (result.suggestions.length > 0) {
+            const suggestions = result.suggestions
+                .map((m) => `  ${s.dim('*')} ${s.white(m.section.id)} ${s.dim(`(${m.reason})`)}`)
+                .join('\n');
+            return {
+                output: s.red(`No section "${query}" found.`) +
+                    ' Did you mean:\n' +
+                    suggestions,
+                isError: true,
+            };
+        }
+        return {
+            output: s.red(`No section matching "${query}"`),
+            isError: true,
+        };
     }
-    if (mdMatches.length > 0) {
-        console.log(formatResultList(`References to "${exactMatch.id}":`, mdMatches, ctx.projectRoot));
+    const { target, mdRefs, codeRefs } = result;
+    if (mdRefs.length === 0 && codeRefs.length === 0) {
+        return {
+            output: ctx.styler.yellow(`No references to "${target.id}" found`),
+            isError: true,
+        };
     }
-    if (codeLines.length > 0) {
-        if (mdMatches.length > 0)
-            console.log('');
-        console.log(ctx.chalk.bold('Code references:'));
-        console.log('');
-        for (const line of codeLines) {
-            console.log(`${ctx.chalk.dim('*')} ${line}`);
-        }
+    const s = ctx.styler;
+    const parts = [];
+    if (mdRefs.length > 0) {
+        parts.push(formatResultList(ctx, `References to "${target.id}":`, mdRefs));
+    }
+    if (codeRefs.length > 0) {
+        parts.push('## Code references:' +
+            '\n\n' +
+            codeRefs.map((l) => `${s.dim('*')} ${l}`).join('\n'));
     }
+    return { output: parts.join('\n') };
 }

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

@@ -1,5 +1,27 @@
-import type { CliContext } from './context.js';
-export declare function searchCmd(ctx: CliContext, query: string | undefined, opts: {
+import type { CmdContext, CmdResult, Styler } from '../context.js';
+import { type IndexStats } from '../search/index.js';
+import { type SectionMatch } from '../lattice.js';
+export type SearchResult = {
+    query: string;
+    matches: SectionMatch[];
+};
+export type IndexProgress = {
+    /** Called before indexing starts. `isEmpty` is true on first run. */
+    beforeIndex?: (isEmpty: boolean) => void;
+    /** Called after indexing completes with stats. */
+    afterIndex?: (stats: IndexStats, isEmpty: boolean) => void;
+};
+/**
+ * Run a semantic search across lat.md sections.
+ * Handles indexing (with optional progress callback). Returns matched sections.
+ */
+export declare function runSearch(latDir: string, query: string, key: string, limit: number, progress?: IndexProgress): Promise<SearchResult>;
+/**
+ * Index-only mode (no query). Used by `lat search --reindex`.
+ */
+export declare function runIndex(latDir: string, key: string, progress?: IndexProgress): Promise<void>;
+export declare function cliProgress(reindex: boolean, s: Styler): IndexProgress;
+export declare function searchCommand(ctx: CmdContext, query: string | undefined, opts: {
     limit: number;
     reindex?: boolean;
-}): Promise<void>;
+}, progress?: IndexProgress): Promise<CmdResult>;

package/dist/src/cli/search.js

@@ -1,67 +1,101 @@
-import chalk from 'chalk';
 import { openDb, ensureSchema, closeDb } from '../search/db.js';
 import { detectProvider } from '../search/provider.js';
 import { indexSections } from '../search/index.js';
 import { searchSections } from '../search/search.js';
-import { loadAllSections, flattenSections } from '../lattice.js';
-import { formatResultList } from '../format.js';
-import { getLlmKey, getConfigPath } from '../config.js';
-export async function searchCmd(ctx, query, opts) {
-    let key;
-    try {
-        key = getLlmKey();
-    }
-    catch (err) {
-        console.error(chalk.red(err.message));
-        process.exit(1);
-    }
-    if (!key) {
-        console.error(chalk.red('No API key configured.') +
-            ' Provide a key via LAT_LLM_KEY, LAT_LLM_KEY_FILE, LAT_LLM_KEY_HELPER, or run ' +
-            chalk.cyan('lat init') +
-            ' to save one in ' +
-            chalk.dim(getConfigPath()) +
-            '.');
-        process.exit(1);
-    }
+import { loadAllSections, flattenSections, } from '../lattice.js';
+import { formatResultList, formatNavHints } from '../format.js';
+async function withDb(latDir, key, progress, fn) {
     const provider = detectProvider(key);
-    const db = openDb(ctx.latDir);
+    const db = openDb(latDir);
     try {
         await ensureSchema(db, provider.dimensions);
-        // Check if index needs updating
         const countResult = await db.execute('SELECT COUNT(*) as n FROM sections');
         const isEmpty = countResult.rows[0].n === 0;
-        if (isEmpty || opts.reindex) {
-            const label = opts.reindex ? 'Re-indexing' : 'Building index';
-            process.stderr.write(chalk.dim(`${label}...`));
-            const stats = await indexSections(ctx.latDir, db, provider, key);
-            process.stderr.write(chalk.dim(` done (${stats.added} added, ${stats.updated} updated, ${stats.removed} removed)\n`));
-        }
-        else {
-            // Incremental update
-            const stats = await indexSections(ctx.latDir, db, provider, key);
-            if (stats.added + stats.updated + stats.removed > 0) {
-                process.stderr.write(chalk.dim(`Index updated: ${stats.added} added, ${stats.updated} updated, ${stats.removed} removed\n`));
-            }
-        }
-        if (!query)
-            return;
-        const results = await searchSections(db, query, provider, key, opts.limit);
+        progress?.beforeIndex?.(isEmpty);
+        const stats = await indexSections(latDir, db, provider, key);
+        progress?.afterIndex?.(stats, isEmpty);
+        return await fn(db, provider);
+    }
+    finally {
+        await closeDb(db);
+    }
+}
+/**
+ * Run a semantic search across lat.md sections.
+ * Handles indexing (with optional progress callback). Returns matched sections.
+ */
+export async function runSearch(latDir, query, key, limit, progress) {
+    return withDb(latDir, key, progress, async (db, provider) => {
+        const results = await searchSections(db, query, provider, key, limit);
         if (results.length === 0) {
-            console.log(chalk.dim('No results found.'));
-            return;
+            return { query, matches: [] };
         }
-        // Load sections for formatting with location info
-        const allSections = await loadAllSections(ctx.latDir);
+        const allSections = await loadAllSections(latDir);
         const flat = flattenSections(allSections);
         const byId = new Map(flat.map((s) => [s.id, s]));
-        const matched = results
+        const matches = results
             .map((r) => byId.get(r.id))
             .filter((s) => !!s)
             .map((s) => ({ section: s, reason: 'semantic match' }));
-        console.log(formatResultList(`Search results for "${query}":`, matched, ctx.projectRoot));
+        return { query, matches };
+    });
+}
+/**
+ * Index-only mode (no query). Used by `lat search --reindex`.
+ */
+export async function runIndex(latDir, key, progress) {
+    await withDb(latDir, key, progress, async () => { });
+}
+export function cliProgress(reindex, s) {
+    return {
+        beforeIndex(isEmpty) {
+            if (isEmpty || reindex) {
+                const label = reindex ? 'Re-indexing' : 'Building index';
+                process.stderr.write(s.dim(`${label}...`));
+            }
+        },
+        afterIndex(stats, isEmpty) {
+            if (isEmpty || reindex) {
+                process.stderr.write(s.dim(` done (${stats.added} added, ${stats.updated} updated, ${stats.removed} removed)\n`));
+            }
+            else if (stats.added + stats.updated + stats.removed > 0) {
+                process.stderr.write(s.dim(`Index updated: ${stats.added} added, ${stats.updated} updated, ${stats.removed} removed\n`));
+            }
+        },
+    };
+}
+export async function searchCommand(ctx, query, opts, progress) {
+    const { getLlmKey, getConfigPath } = await import('../config.js');
+    let key;
+    try {
+        key = getLlmKey();
     }
-    finally {
-        await closeDb(db);
+    catch (err) {
+        return { output: err.message, isError: true };
+    }
+    if (!key) {
+        const s = ctx.styler;
+        return {
+            output: s.red('No API key configured.') +
+                ' Provide a key via LAT_LLM_KEY, LAT_LLM_KEY_FILE, LAT_LLM_KEY_HELPER, or run ' +
+                s.cyan('lat init') +
+                (ctx.mode === 'cli'
+                    ? ' to save one in ' + s.dim(getConfigPath())
+                    : '') +
+                '.',
+            isError: true,
+        };
+    }
+    if (!query) {
+        await runIndex(ctx.latDir, key, progress);
+        return { output: '' };
+    }
+    const result = await runSearch(ctx.latDir, query, key, opts.limit, progress);
+    if (result.matches.length === 0) {
+        return { output: 'No results found.' };
     }
+    return {
+        output: formatResultList(ctx, `Search results for "${query}":`, result.matches) +
+            formatNavHints(ctx),
+    };
 }

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

@@ -0,0 +1,26 @@
+import { type Section, type SectionMatch } from '../lattice.js';
+import type { CmdContext, CmdResult } from '../context.js';
+export type SectionFound = {
+    kind: 'found';
+    section: Section;
+    content: string;
+    outgoingRefs: {
+        target: string;
+        resolved: Section;
+    }[];
+    incomingRefs: SectionMatch[];
+};
+export type SectionResult = SectionFound | {
+    kind: 'no-match';
+    suggestions: SectionMatch[];
+};
+/**
+ * Look up a section by id, return its content, outgoing wiki link targets,
+ * and incoming references from other sections.
+ */
+export declare function getSection(ctx: CmdContext, query: string): Promise<SectionResult>;
+/**
+ * Format a successful section result with styling.
+ */
+export declare function formatSectionOutput(ctx: CmdContext, result: SectionFound): string;
+export declare function sectionCommand(ctx: CmdContext, query: string): Promise<CmdResult>;

package/dist/src/cli/section.js

@@ -0,0 +1,138 @@
+import { readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { loadAllSections, findSections, flattenSections, extractRefs, buildFileIndex, resolveRef, listLatticeFiles, } from '../lattice.js';
+import { formatSectionId, formatNavHints } from '../format.js';
+/**
+ * Look up a section by id, return its content, outgoing wiki link targets,
+ * and incoming references from other sections.
+ */
+export async function getSection(ctx, query) {
+    query = query.replace(/^\[\[|\]\]$/g, '');
+    const allSections = await loadAllSections(ctx.latDir);
+    const matches = findSections(allSections, query);
+    if (matches.length === 0) {
+        return { kind: 'no-match', suggestions: [] };
+    }
+    // Accept the top match if confident
+    const top = matches[0];
+    const isConfident = top.reason === 'exact match' ||
+        top.reason.startsWith('file stem expanded') ||
+        top.reason === 'section name match';
+    if (!isConfident) {
+        return { kind: 'no-match', suggestions: matches };
+    }
+    const section = top.section;
+    // Read raw content between startLine and endLine
+    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');
+    // Find outgoing wiki link targets within this section's content
+    const flat = flattenSections(allSections);
+    const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
+    const fileIndex = buildFileIndex(allSections);
+    const sectionRefs = extractRefs(absPath, fileContent, ctx.projectRoot);
+    const sectionId = section.id.toLowerCase();
+    const outgoingRefs = [];
+    const seen = new Set();
+    for (const ref of sectionRefs) {
+        if (ref.fromSection.toLowerCase() !== sectionId)
+            continue;
+        const { resolved } = resolveRef(ref.target, sectionIds, fileIndex);
+        const resolvedLower = resolved.toLowerCase();
+        if (seen.has(resolvedLower))
+            continue;
+        seen.add(resolvedLower);
+        const targetSection = flat.find((s) => s.id.toLowerCase() === resolvedLower);
+        if (targetSection) {
+            outgoingRefs.push({ target: ref.target, resolved: targetSection });
+        }
+    }
+    // Find incoming references: other sections that link to this one
+    const incomingRefs = [];
+    const files = await listLatticeFiles(ctx.latDir);
+    const incomingSections = new Set();
+    for (const file of files) {
+        const fc = await readFile(file, 'utf-8');
+        const fileRefs = extractRefs(file, fc, ctx.projectRoot);
+        for (const ref of fileRefs) {
+            const { resolved } = resolveRef(ref.target, sectionIds, fileIndex);
+            if (resolved.toLowerCase() === sectionId &&
+                ref.fromSection.toLowerCase() !== sectionId) {
+                if (!incomingSections.has(ref.fromSection.toLowerCase())) {
+                    incomingSections.add(ref.fromSection.toLowerCase());
+                    const fromSection = flat.find((s) => s.id.toLowerCase() === ref.fromSection.toLowerCase());
+                    if (fromSection) {
+                        incomingRefs.push({ section: fromSection, reason: 'wiki link' });
+                    }
+                }
+            }
+        }
+    }
+    return { kind: 'found', section, content, outgoingRefs, incomingRefs };
+}
+function truncate(s, max) {
+    return s.length > max ? s.slice(0, max) + '...' : s;
+}
+/**
+ * Format a successful section result with styling.
+ */
+export function formatSectionOutput(ctx, result) {
+    const s = ctx.styler;
+    const { section, content, outgoingRefs, incomingRefs } = 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
+        .split('\n')
+        .map((line) => (line ? `> ${line}` : '>'))
+        .join('\n');
+    const parts = [
+        `${s.bold('[[' + formatSectionId(section.id, s) + ']]')} (${loc})`,
+        '',
+        quoted,
+    ];
+    if (outgoingRefs.length > 0) {
+        parts.push('', '## This section references:', '');
+        for (const ref of outgoingRefs) {
+            const body = ref.resolved.firstParagraph
+                ? ` ${s.dim('—')} ${truncate(ref.resolved.firstParagraph, 120)}`
+                : '';
+            parts.push(`${s.dim('*')} [[${formatSectionId(ref.resolved.id, s)}]]${body}`);
+        }
+    }
+    if (incomingRefs.length > 0) {
+        parts.push('', '## Referenced by:', '');
+        for (const ref of incomingRefs) {
+            const body = ref.section.firstParagraph
+                ? ` ${s.dim('—')} ${truncate(ref.section.firstParagraph, 120)}`
+                : '';
+            parts.push(`${s.dim('*')} [[${formatSectionId(ref.section.id, s)}]]${body}`);
+        }
+    }
+    parts.push(formatNavHints(ctx));
+    return parts.join('\n');
+}
+export async function sectionCommand(ctx, query) {
+    const result = await getSection(ctx, query);
+    if (result.kind === 'no-match') {
+        const s = ctx.styler;
+        if (result.suggestions.length > 0) {
+            const suggestions = result.suggestions
+                .map((m) => `  ${s.dim('*')} ${s.white(m.section.id)} ${s.dim(`(${m.reason})`)}`)
+                .join('\n');
+            return {
+                output: s.red(`No section "${query}" found.`) +
+                    ' Did you mean:\n' +
+                    suggestions,
+                isError: true,
+            };
+        }
+        return {
+            output: s.red(`No sections matching "${query}"`),
+            isError: true,
+        };
+    }
+    return { output: formatSectionOutput(ctx, result) };
+}

package/dist/src/code-refs.js

@@ -39,7 +39,8 @@ export async function scanCodeRefs(projectRoot) {
         try {
             content = await readFile(file, 'utf-8');
         }
-        catch {
+        catch (err) {
+            process.stderr.write(`Error: failed to read ${file}: ${err.message}\n`);
             continue;
         }
         const lines = content.split('\n');

package/dist/src/config.js

@@ -16,8 +16,9 @@ export function readConfig() {
     try {
         return JSON.parse(readFileSync(configPath, 'utf-8'));
     }
-    catch {
-        return {};
+    catch (err) {
+        process.stderr.write(`Error: failed to parse config ${configPath}: ${err.message}\n`);
+        process.exit(1);
     }
 }
 export function writeConfig(config) {

package/dist/src/context.d.ts

@@ -0,0 +1,21 @@
+export type Styler = {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    red: (s: string) => string;
+    cyan: (s: string) => string;
+    white: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    boldWhite: (s: string) => string;
+};
+export declare const plainStyler: Styler;
+export type CmdContext = {
+    latDir: string;
+    projectRoot: string;
+    styler: Styler;
+    mode: 'cli' | 'mcp';
+};
+export type CmdResult = {
+    output: string;
+    isError?: boolean;
+};

package/dist/src/context.js

@@ -0,0 +1,11 @@
+const identity = (s) => s;
+export const plainStyler = {
+    bold: identity,
+    dim: identity,
+    red: identity,
+    cyan: identity,
+    white: identity,
+    green: identity,
+    yellow: identity,
+    boldWhite: identity,
+};

package/dist/src/format.d.ts

@@ -1,6 +1,8 @@
 import type { Section, SectionMatch } from './lattice.js';
-export declare function formatSectionId(id: string): string;
-export declare function formatSectionPreview(section: Section, projectRoot: string, opts?: {
+import type { CmdContext, Styler } from './context.js';
+export declare function formatSectionId(id: string, s: Styler): string;
+export declare function formatSectionPreview(ctx: CmdContext, section: Section, opts?: {
     reason?: string;
 }): string;
-export declare function formatResultList(header: string, matches: SectionMatch[], projectRoot: string): string;
+export declare function formatResultList(ctx: CmdContext, header: string, matches: SectionMatch[]): string;
+export declare function formatNavHints(ctx: CmdContext): string;

package/dist/src/format.js

@@ -1,38 +1,43 @@
 import { join, relative } from 'node:path';
-import chalk from 'chalk';
-export function formatSectionId(id) {
+export function formatSectionId(id, s) {
     const parts = id.split('#');
     return parts.length === 1
-        ? chalk.bold.white(parts[0])
-        : chalk.dim(parts.slice(0, -1).join('#') + '#') +
-            chalk.bold.white(parts[parts.length - 1]);
+        ? s.boldWhite(parts[0])
+        : s.dim(parts.slice(0, -1).join('#') + '#') +
+            s.boldWhite(parts[parts.length - 1]);
 }
-export function formatSectionPreview(section, projectRoot, opts) {
-    const relPath = relative(process.cwd(), join(projectRoot, section.filePath));
+export function formatSectionPreview(ctx, section, opts) {
+    const s = ctx.styler;
+    const relPath = relative(process.cwd(), join(ctx.projectRoot, section.filePath));
     const kind = section.id.includes('#') ? 'Section' : 'File';
-    const reasonSuffix = opts?.reason ? ' ' + chalk.dim(`(${opts.reason})`) : '';
+    const reasonSuffix = opts?.reason ? ' ' + s.dim(`(${opts.reason})`) : '';
     const lines = [
-        `${chalk.dim('*')} ${chalk.dim(kind + ':')} [[${formatSectionId(section.id)}]]${reasonSuffix}`,
-        `  ${chalk.dim('Defined in')} ${chalk.cyan(relPath)}${chalk.dim(`:${section.startLine}-${section.endLine}`)}`,
+        `${s.dim('*')} ${s.dim(kind + ':')} [[${formatSectionId(section.id, s)}]]${reasonSuffix}`,
+        `  ${s.dim('Defined in')} ${s.cyan(relPath)}${s.dim(`:${section.startLine}-${section.endLine}`)}`,
     ];
-    if (section.body) {
-        const truncated = section.body.length > 200
-            ? section.body.slice(0, 200) + '...'
-            : section.body;
-        lines.push('');
-        lines.push(`  ${chalk.dim('>')} ${truncated}`);
+    if (section.firstParagraph) {
+        lines.push('', `  ${s.dim('>')} ${section.firstParagraph}`);
     }
     return lines.join('\n');
 }
-export function formatResultList(header, matches, projectRoot) {
-    const lines = ['', chalk.bold(header), ''];
+export function formatResultList(ctx, header, matches) {
+    const lines = ['', `## ${header}`, ''];
     for (let i = 0; i < matches.length; i++) {
         if (i > 0)
             lines.push('');
-        lines.push(formatSectionPreview(matches[i].section, projectRoot, {
+        lines.push(formatSectionPreview(ctx, matches[i].section, {
             reason: matches[i].reason,
         }));
     }
     lines.push('');
     return lines.join('\n');
 }
+export function formatNavHints(ctx) {
+    const s = ctx.styler;
+    const hints = ctx.mode === 'cli'
+        ? `${s.dim('*')} \`lat section "section#id"\` \u2014 show full content with outgoing/incoming refs\n` +
+            `${s.dim('*')} \`lat search "new query"\` \u2014 search for something else`
+        : `${s.dim('*')} \`lat_section\` \u2014 show full content with outgoing/incoming refs\n` +
+            `${s.dim('*')} \`lat_search\` \u2014 search for something else`;
+    return `\n## To navigate further:\n\n${hints}`;
+}

package/dist/src/init-version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Bump this number whenever `lat init` setup changes in a way that
+ * requires users to re-run it (e.g. new hooks, AGENTS.md changes,
+ * MCP config changes).
+ */
+export declare const INIT_VERSION = 1;
+export declare function readInitVersion(latDir: string): number | null;
+export declare function readFileHash(latDir: string, relPath: string): string | null;
+export declare function contentHash(content: string): string;
+export declare function writeInitMeta(latDir: string, fileHashes: Record<string, string>): void;