lat.md 0.1.3 → 0.2.3

package/README.md

@@ -1,6 +1,7 @@
 # lat.md
 
 [![CI](https://github.com/1st1/lat.md/actions/workflows/ci.yml/badge.svg)](https://github.com/1st1/lat.md/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/lat.md)](https://www.npmjs.com/package/lat.md)
 
 A knowledge graph for your codebase, written in markdown.
 
@@ -26,7 +27,9 @@ The result is a structured knowledge base that:
 npm install -g lat.md
 ```
 
-Or use directly with `npx lat.md <command>`.
+Or use directly with `npx lat.md@latest <command>`.
+
+For semantic search (`lat search`), set the `LAT_LLM_KEY` environment variable with an OpenAI (`sk-...`) or Vercel AI Gateway (`vck_...`) API key.
 
 ## How it works
 

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

@@ -13,6 +13,13 @@ export type CheckResult = {
 };
 export declare function checkMd(latticeDir: string): Promise<CheckResult>;
 export declare function checkCodeRefs(latticeDir: string): Promise<CheckResult>;
+export type IndexError = {
+    dir: string;
+    message: string;
+    snippet?: string;
+};
+export declare function checkIndex(latticeDir: string): Promise<IndexError[]>;
 export declare function checkMdCmd(ctx: CliContext): Promise<void>;
 export declare function checkCodeRefsCmd(ctx: CliContext): Promise<void>;
+export declare function checkIndexCmd(ctx: CliContext): Promise<void>;
 export declare function checkAllCmd(ctx: CliContext): Promise<void>;

package/dist/src/cli/check.js

@@ -1,7 +1,27 @@
 import { readFile } from 'node:fs/promises';
-import { extname, join, relative } from 'node:path';
-import { listLatticeFiles, loadAllSections, extractRefs, flattenSections, parseFrontmatter, parseSections, } from '../lattice.js';
+import { basename, extname, join, relative } from 'node:path';
+import { listLatticeFiles, loadAllSections, extractRefs, flattenSections, parseFrontmatter, parseSections, buildFileIndex, resolveRef, } from '../lattice.js';
 import { scanCodeRefs } from '../code-refs.js';
+import { walkEntries } from '../walk.js';
+function filePart(id) {
+    const h = id.indexOf('#');
+    return h === -1 ? id : id.slice(0, h);
+}
+/** Format an ambiguous-ref error as structured markdown-like text. */
+function ambiguousMessage(target, candidates, suggested) {
+    const shortName = filePart(target);
+    const fileList = candidates.map((c) => `  - "${filePart(c)}.md"`).join('\n');
+    const lines = [];
+    if (suggested) {
+        lines.push(`ambiguous link '[[${target}]]' — did you mean '[[${suggested}]]'?`);
+    }
+    else {
+        const options = candidates.map((a) => `'[[${a}]]'`).join(', ');
+        lines.push(`ambiguous link '[[${target}]]' — multiple paths match, use either of: ${options}`);
+    }
+    lines.push(`  The short path "${shortName}" is ambiguous — ${candidates.length} files match:`, fileList, `  Please fix the link to use a fully qualified path.`);
+    return lines.join('\n');
+}
 function countByExt(paths) {
     const stats = {};
     for (const p of paths) {
@@ -15,14 +35,23 @@ export async function checkMd(latticeDir) {
     const allSections = await loadAllSections(latticeDir);
     const flat = flattenSections(allSections);
     const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
+    const fileIndex = buildFileIndex(allSections);
     const errors = [];
     for (const file of files) {
         const content = await readFile(file, 'utf-8');
-        const refs = extractRefs(file, content);
+        const refs = extractRefs(file, content, latticeDir);
         const relPath = relative(process.cwd(), file);
         for (const ref of refs) {
-            const target = ref.target.toLowerCase();
-            if (!sectionIds.has(target)) {
+            const { resolved, ambiguous, suggested } = resolveRef(ref.target, sectionIds, fileIndex);
+            if (ambiguous) {
+                errors.push({
+                    file: relPath,
+                    line: ref.line,
+                    target: ref.target,
+                    message: ambiguousMessage(ref.target, ambiguous, suggested),
+                });
+            }
+            else if (!sectionIds.has(resolved.toLowerCase())) {
                 errors.push({
                     file: relPath,
                     line: ref.line,
@@ -39,13 +68,22 @@ export async function checkCodeRefs(latticeDir) {
     const allSections = await loadAllSections(latticeDir);
     const flat = flattenSections(allSections);
     const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
+    const fileIndex = buildFileIndex(allSections);
     const scan = await scanCodeRefs(projectRoot);
     const errors = [];
     const mentionedSections = new Set();
     for (const ref of scan.refs) {
-        const target = ref.target.toLowerCase();
-        mentionedSections.add(target);
-        if (!sectionIds.has(target)) {
+        const { resolved, ambiguous, suggested } = resolveRef(ref.target, sectionIds, fileIndex);
+        mentionedSections.add(resolved.toLowerCase());
+        if (ambiguous) {
+            errors.push({
+                file: ref.file,
+                line: ref.line,
+                target: ref.target,
+                message: ambiguousMessage(ref.target, ambiguous, suggested),
+            });
+        }
+        else if (!sectionIds.has(resolved.toLowerCase())) {
             errors.push({
                 file: ref.file,
                 line: ref.line,
@@ -60,7 +98,7 @@ export async function checkCodeRefs(latticeDir) {
         const fm = parseFrontmatter(content);
         if (!fm.requireCodeMention)
             continue;
-        const sections = parseSections(file, content);
+        const sections = parseSections(file, content, latticeDir);
         const fileSections = flattenSections(sections);
         const leafSections = fileSections.filter((s) => s.children.length === 0);
         const relPath = relative(process.cwd(), file);
@@ -77,12 +115,129 @@ export async function checkCodeRefs(latticeDir) {
     }
     return { errors, files: countByExt(scan.files) };
 }
-function formatErrors(ctx, errors) {
-    for (const err of errors) {
-        console.error(`${ctx.chalk.cyan(err.file + ':' + err.line)}: ${ctx.chalk.red(err.message)}`);
+/**
+ * Extract the immediate (first-level) entries from walkEntries results.
+ * Returns unique file and directory names visible in a given directory.
+ */
+function immediateEntries(walkedPaths) {
+    const entries = new Set();
+    for (const p of walkedPaths) {
+        const slash = p.indexOf('/');
+        entries.add(slash === -1 ? p : p.slice(0, slash));
     }
-    if (errors.length > 0) {
-        console.error(ctx.chalk.red(`\n${errors.length} error${errors.length === 1 ? '' : 's'} found`));
+    return [...entries].sort();
+}
+/** Parse bullet items from an index file. Matches `- **name** — description` */
+function parseIndexEntries(content) {
+    const names = new Set();
+    const re = /^- \*\*(.+?)\*\*/gm;
+    let match;
+    while ((match = re.exec(content)) !== null) {
+        names.add(match[1]);
+    }
+    return names;
+}
+/** Generate a bullet-list snippet for the given entry names. */
+function indexSnippet(entries) {
+    return entries.map((e) => `- **${e}** — <describe>`).join('\n');
+}
+export async function checkIndex(latticeDir) {
+    const errors = [];
+    const allPaths = await walkEntries(latticeDir);
+    // Collect all directories to check (including root, represented as '')
+    const dirs = new Set(['']);
+    for (const p of allPaths) {
+        const parts = p.split('/');
+        // Add every directory prefix
+        for (let i = 1; i < parts.length; i++) {
+            dirs.add(parts.slice(0, i).join('/'));
+        }
+    }
+    for (const dir of dirs) {
+        // Determine the index file name and its expected path.
+        // The index file shares the directory's name — for `lat.md/` it's `lat.md`,
+        // for a subdir `api/` it's `api.md`.
+        const dirName = dir === '' ? basename(latticeDir) : dir.split('/').pop();
+        const indexFileName = dirName.endsWith('.md') ? dirName : dirName + '.md';
+        const indexRelPath = dir === '' ? indexFileName : dir + '/' + indexFileName;
+        // Get the immediate children of this directory
+        const prefix = dir === '' ? '' : dir + '/';
+        const childPaths = allPaths
+            .filter((p) => p.startsWith(prefix) && p !== indexRelPath)
+            .map((p) => p.slice(prefix.length));
+        const children = immediateEntries(childPaths);
+        if (children.length === 0)
+            continue;
+        // Check if the index file exists
+        const indexFullPath = join(latticeDir, indexRelPath);
+        let content;
+        try {
+            content = await readFile(indexFullPath, 'utf-8');
+        }
+        catch {
+            const relDir = dir === '' ? basename(latticeDir) + '/' : dir + '/';
+            errors.push({
+                dir: relDir,
+                message: `missing index file "${indexRelPath}" — create it with a directory listing:\n\n${indexSnippet(children)}`,
+                snippet: indexSnippet(children),
+            });
+            continue;
+        }
+        // Parse existing entries and validate
+        const listed = parseIndexEntries(content);
+        const relDir = dir === '' ? basename(latticeDir) + '/' : dir + '/';
+        const missing = [];
+        for (const child of children) {
+            if (!listed.has(child)) {
+                missing.push(child);
+            }
+        }
+        if (missing.length > 0) {
+            errors.push({
+                dir: relDir,
+                message: `"${indexRelPath}" is missing entries — add:\n\n${indexSnippet(missing)}`,
+                snippet: indexSnippet(missing),
+            });
+        }
+        for (const name of listed) {
+            if (!children.includes(name) && name !== indexFileName) {
+                errors.push({
+                    dir: relDir,
+                    message: `"${indexRelPath}" lists "${name}" but it does not exist`,
+                });
+            }
+        }
+    }
+    return errors;
+}
+function formatErrors(ctx, errors, startIdx = 0) {
+    for (let i = 0; i < errors.length; i++) {
+        const err = errors[i];
+        if (i > 0 || startIdx > 0)
+            console.error('');
+        const loc = ctx.chalk.cyan(err.file + ':' + err.line);
+        const [first, ...rest] = err.message.split('\n');
+        console.error(`- ${loc}: ${ctx.chalk.red(first)}`);
+        for (const line of rest) {
+            console.error(`  ${ctx.chalk.red(line)}`);
+        }
+    }
+}
+function formatIndexErrors(ctx, errors, startIdx = 0) {
+    for (let i = 0; i < errors.length; i++) {
+        if (i > 0 || startIdx > 0)
+            console.error('');
+        const loc = ctx.chalk.cyan(errors[i].dir);
+        const [first, ...rest] = errors[i].message.split('\n');
+        console.error(`- ${loc}: ${ctx.chalk.red(first)}`);
+        for (const line of rest) {
+            console.error(`  ${ctx.chalk.red(line)}`);
+        }
+    }
+}
+function formatErrorCount(ctx, count) {
+    if (count > 0) {
+        console.error(ctx.chalk.red(`\n${count} error${count === 1 ? '' : 's'} found`));
     }
 }
 function formatStats(ctx, stats) {
@@ -94,6 +249,7 @@ export async function checkMdCmd(ctx) {
     const { errors, files } = await checkMd(ctx.latDir);
     formatStats(ctx, files);
     formatErrors(ctx, errors);
+    formatErrorCount(ctx, errors.length);
     if (errors.length > 0)
         process.exit(1);
     console.log(ctx.chalk.green('md: All links OK'));
@@ -102,13 +258,23 @@ export async function checkCodeRefsCmd(ctx) {
     const { errors, files } = await checkCodeRefs(ctx.latDir);
     formatStats(ctx, files);
     formatErrors(ctx, errors);
+    formatErrorCount(ctx, errors.length);
     if (errors.length > 0)
         process.exit(1);
     console.log(ctx.chalk.green('code-refs: All references OK'));
 }
+export async function checkIndexCmd(ctx) {
+    const errors = await checkIndex(ctx.latDir);
+    formatIndexErrors(ctx, errors);
+    formatErrorCount(ctx, errors.length);
+    if (errors.length > 0)
+        process.exit(1);
+    console.log(ctx.chalk.green('index: All directory index files OK'));
+}
 export async function checkAllCmd(ctx) {
     const md = await checkMd(ctx.latDir);
     const code = await checkCodeRefs(ctx.latDir);
+    const indexErrors = await checkIndex(ctx.latDir);
     const allErrors = [...md.errors, ...code.errors];
     const allFiles = { ...md.files };
     for (const [ext, n] of Object.entries(code.files)) {
@@ -116,7 +282,10 @@ export async function checkAllCmd(ctx) {
     }
     formatStats(ctx, allFiles);
     formatErrors(ctx, allErrors);
-    if (allErrors.length > 0)
+    formatIndexErrors(ctx, indexErrors, allErrors.length);
+    const totalErrors = allErrors.length + indexErrors.length;
+    formatErrorCount(ctx, totalErrors);
+    if (totalErrors > 0)
         process.exit(1);
     console.log(ctx.chalk.green('All checks passed'));
 }

package/dist/src/cli/index.js

@@ -79,6 +79,14 @@ check
     const { checkCodeRefsCmd } = await import('./check.js');
     await checkCodeRefsCmd(ctx);
 });
+check
+    .command('index')
+    .description('Validate directory index files in lat.md')
+    .action(async () => {
+    const ctx = resolveContext(program.opts());
+    const { checkIndexCmd } = await import('./check.js');
+    await checkIndexCmd(ctx);
+});
 program
     .command('prompt')
     .description('Expand [[refs]] in a prompt to lat.md section locations')

package/dist/src/cli/prompt.js

@@ -1,5 +1,5 @@
 import { relative } from 'node:path';
-import { loadAllSections, findSections, flattenSections, } from '../lattice.js';
+import { loadAllSections, findSections, flattenSections, buildFileIndex, resolveRef, } from '../lattice.js';
 const WIKI_LINK_RE = /\[\[([^\]]+)\]\]/g;
 function formatContext(section, latDir) {
     const relPath = relative(process.cwd(), latDir + '/' + section.file + '.md');
@@ -13,6 +13,8 @@ function formatContext(section, latDir) {
 export async function promptCmd(ctx, text) {
     const allSections = await loadAllSections(ctx.latDir);
     const flat = flattenSections(allSections);
+    const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
+    const fileIndex = buildFileIndex(allSections);
     const refs = [...text.matchAll(WIKI_LINK_RE)];
     if (refs.length === 0) {
         process.stdout.write(text);
@@ -23,7 +25,9 @@ export async function promptCmd(ctx, text) {
         const target = match[1];
         if (resolved.has(target))
             continue;
-        const q = target.toLowerCase();
+        // Resolve short refs (e.g. search#X → tests/search#X)
+        const { resolved: resolvedTarget } = resolveRef(target, sectionIds, fileIndex);
+        const q = resolvedTarget.toLowerCase();
         const exact = flat.find((s) => s.id.toLowerCase() === q);
         if (exact) {
             resolved.set(target, exact);

package/dist/src/cli/refs.js

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { listLatticeFiles, loadAllSections, findSections, extractRefs, flattenSections, } from '../lattice.js';
+import { listLatticeFiles, loadAllSections, findSections, extractRefs, flattenSections, buildFileIndex, resolveRef, } from '../lattice.js';
 import { formatSectionPreview } from '../format.js';
 import { scanCodeRefs } from '../code-refs.js';
 export async function refsCmd(ctx, query, scope) {
@@ -10,9 +10,12 @@ export async function refsCmd(ctx, query, scope) {
         console.error(ctx.chalk.red(`No section matching "${query}" (no exact, substring, or fuzzy matches)`));
         process.exit(1);
     }
-    // Require exact full-path match
-    const q = query.toLowerCase();
+    // 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.`));
@@ -31,9 +34,10 @@ export async function refsCmd(ctx, query, scope) {
         const matchingFromSections = new Set();
         for (const file of files) {
             const content = await readFile(file, 'utf-8');
-            const fileRefs = extractRefs(file, content);
+            const fileRefs = extractRefs(file, content, ctx.latDir);
             for (const ref of fileRefs) {
-                if (ref.target.toLowerCase() === targetId) {
+                const { resolved: refResolved } = resolveRef(ref.target, sectionIds, fileIndex);
+                if (refResolved.toLowerCase() === targetId) {
                     matchingFromSections.add(ref.fromSection.toLowerCase());
                 }
             }
@@ -52,7 +56,8 @@ export async function refsCmd(ctx, query, scope) {
         const projectRoot = join(ctx.latDir, '..');
         const { refs: codeRefs } = await scanCodeRefs(projectRoot);
         for (const ref of codeRefs) {
-            if (ref.target.toLowerCase() === targetId) {
+            const { resolved: codeResolved } = resolveRef(ref.target, sectionIds, fileIndex);
+            if (codeResolved.toLowerCase() === targetId) {
                 if (hasOutput)
                     console.log('');
                 console.log(`  ${ref.file}:${ref.line}`);

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

@@ -1,4 +1,5 @@
-/** Walk project files respecting .gitignore. Skips lat.md/, .claude/, and sub-projects. */
+/** Walk project files for code-ref scanning. Uses walkEntries for .gitignore
+ *  support, then additionally skips .md files, lat.md/, .claude/, and sub-projects. */
 export declare function walkFiles(dir: string): Promise<string[]>;
 export declare const LAT_REF_RE: RegExp;
 export type CodeRef = {

package/dist/src/code-refs.js

@@ -1,13 +1,10 @@
 import { readFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
-// @ts-expect-error -- no type declarations
-import walk from 'ignore-walk';
-/** Walk project files respecting .gitignore. Skips lat.md/, .claude/, and sub-projects. */
+import { walkEntries } from './walk.js';
+/** 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) {
-    const entries = await walk({
-        path: dir,
-        ignoreFiles: ['.gitignore'],
-    });
+    const entries = await walkEntries(dir);
     // Collect directories that contain their own lat.md/ (sub-projects)
     const subProjects = new Set();
     for (const e of entries) {
@@ -17,7 +14,6 @@ export async function walkFiles(dir) {
     }
     return entries
         .filter((e) => !e.endsWith('.md') &&
-        !e.startsWith('.git/') &&
         !e.startsWith('lat.md/') &&
         !e.startsWith('.claude/') &&
         ![...subProjects].some((prefix) => e.startsWith(prefix)))

package/dist/src/lattice.d.ts

@@ -21,8 +21,29 @@ export declare function parseFrontmatter(content: string): LatFrontmatter;
 export declare function stripFrontmatter(content: string): string;
 export declare function findLatticeDir(from?: string): string | null;
 export declare function listLatticeFiles(latticeDir: string): Promise<string[]>;
-export declare function parseSections(filePath: string, content: string): Section[];
+export declare function parseSections(filePath: string, content: string, latticeDir?: string): Section[];
 export declare function loadAllSections(latticeDir: string): Promise<Section[]>;
 export declare function flattenSections(sections: Section[]): Section[];
+/**
+ * Build an index mapping bare file stems to their full vault-relative paths.
+ * Used by resolveRef to allow short references when a stem is unambiguous.
+ */
+export declare function buildFileIndex(sections: Section[]): Map<string, string[]>;
+export type ResolveResult = {
+    resolved: string;
+    ambiguous: string[] | null;
+    /** When ambiguous but exactly one candidate has the section, suggest it. */
+    suggested: string | null;
+};
+/**
+ * Resolve a potentially short reference to its canonical full-path form.
+ * If the file segment of the ref is a bare stem that uniquely maps to one
+ * full path, expands it. Otherwise returns the ref unchanged.
+ *
+ * When ambiguous (multiple files share the stem), returns all candidates.
+ * If exactly one candidate actually contains the referenced section,
+ * `suggested` is set to that candidate so the caller can propose a fix.
+ */
+export declare function resolveRef(target: string, sectionIds: Set<string>, fileIndex: Map<string, string[]>): ResolveResult;
 export declare function findSections(sections: Section[], query: string): Section[];
-export declare function extractRefs(filePath: string, content: string): Ref[];
+export declare function extractRefs(filePath: string, content: string, latticeDir?: string): Ref[];

package/dist/src/lattice.js

@@ -1,7 +1,8 @@
-import { readdir, readFile } from 'node:fs/promises';
-import { dirname, join, basename, resolve } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { dirname, join, basename, relative, resolve } from 'node:path';
 import { existsSync, statSync } from 'node:fs';
 import { parse } from './parser.js';
+import { walkEntries } from './walk.js';
 import { visit } from 'unist-util-visit';
 export function parseFrontmatter(content) {
     const match = content.match(/^---\n([\s\S]*?)\n---/);
@@ -31,7 +32,7 @@ export function findLatticeDir(from) {
     }
 }
 export async function listLatticeFiles(latticeDir) {
-    const entries = await readdir(latticeDir);
+    const entries = await walkEntries(latticeDir);
     return entries
         .filter((e) => e.endsWith('.md'))
         .sort()
@@ -63,9 +64,11 @@ function lastLine(content) {
     // If trailing newline, count doesn't include empty last line
     return lines[lines.length - 1] === '' ? lines.length - 1 : lines.length;
 }
-export function parseSections(filePath, content) {
+export function parseSections(filePath, content, latticeDir) {
     const tree = parse(stripFrontmatter(content));
-    const file = basename(filePath, '.md');
+    const file = latticeDir
+        ? relative(latticeDir, filePath).replace(/\.md$/, '')
+        : basename(filePath, '.md');
     const roots = [];
     const stack = [];
     const flat = [];
@@ -128,14 +131,28 @@ export function parseSections(filePath, content) {
     }
     return roots;
 }
-export async function loadAllSections(latticeDir) {
-    const files = await listLatticeFiles(latticeDir);
-    const all = [];
-    for (const file of files) {
-        const content = await readFile(file, 'utf-8');
-        all.push(...parseSections(file, content));
+const sectionsCache = new Map();
+export function loadAllSections(latticeDir) {
+    const noCache = !!process.env._LAT_TEST_DISABLE_FS_CACHE;
+    const key = resolve(latticeDir);
+    if (!noCache) {
+        const cached = sectionsCache.get(key);
+        if (cached)
+            return cached;
     }
-    return all;
+    const result = (async () => {
+        const files = await listLatticeFiles(latticeDir);
+        const all = [];
+        for (const file of files) {
+            const content = await readFile(file, 'utf-8');
+            all.push(...parseSections(file, content, latticeDir));
+        }
+        return all;
+    })();
+    if (!noCache) {
+        sectionsCache.set(key, result);
+    }
+    return result;
 }
 export function flattenSections(sections) {
     const result = [];
@@ -176,11 +193,73 @@ function tailSegments(id) {
     }
     return tails;
 }
+/**
+ * Build an index mapping bare file stems to their full vault-relative paths.
+ * Used by resolveRef to allow short references when a stem is unambiguous.
+ */
+export function buildFileIndex(sections) {
+    const flat = flattenSections(sections);
+    const index = new Map();
+    for (const s of flat) {
+        const stem = s.file.includes('/') ? s.file.split('/').pop() : null;
+        if (stem) {
+            if (!index.has(stem))
+                index.set(stem, new Set());
+            index.get(stem).add(s.file);
+        }
+    }
+    const result = new Map();
+    for (const [stem, paths] of index) {
+        result.set(stem, [...paths]);
+    }
+    return result;
+}
+/**
+ * Resolve a potentially short reference to its canonical full-path form.
+ * If the file segment of the ref is a bare stem that uniquely maps to one
+ * full path, expands it. Otherwise returns the ref unchanged.
+ *
+ * When ambiguous (multiple files share the stem), returns all candidates.
+ * If exactly one candidate actually contains the referenced section,
+ * `suggested` is set to that candidate so the caller can propose a fix.
+ */
+export function resolveRef(target, sectionIds, fileIndex) {
+    // Already matches a known section — no resolution needed
+    if (sectionIds.has(target.toLowerCase())) {
+        return { resolved: target, ambiguous: null, suggested: null };
+    }
+    // Extract the file segment (before first #) and try resolving it
+    const hashIdx = target.indexOf('#');
+    const filePart = hashIdx === -1 ? target : target.slice(0, hashIdx);
+    const rest = hashIdx === -1 ? '' : target.slice(hashIdx);
+    const candidates = fileIndex.get(filePart) ?? [];
+    if (candidates.length === 1) {
+        const expanded = candidates[0] + rest;
+        if (sectionIds.has(expanded.toLowerCase())) {
+            return { resolved: expanded, ambiguous: null, suggested: null };
+        }
+    }
+    else if (candidates.length > 1) {
+        // Multiple files share this stem — ambiguous at the filename level
+        const all = candidates.map((c) => c + rest);
+        const valid = candidates.filter((c) => sectionIds.has((c + rest).toLowerCase()));
+        return {
+            resolved: target,
+            ambiguous: all,
+            suggested: valid.length === 1 ? valid[0] + rest : null,
+        };
+    }
+    return { resolved: target, ambiguous: null, suggested: null };
+}
 const MAX_DISTANCE_RATIO = 0.4;
 export function findSections(sections, query) {
     const flat = flattenSections(sections);
-    const q = query.toLowerCase();
     const isFullPath = query.includes('#');
+    // Tier 0: resolve short refs (e.g. search#X → tests/search#X)
+    const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
+    const fileIndex = buildFileIndex(sections);
+    const { resolved } = resolveRef(query, sectionIds, fileIndex);
+    const q = resolved.toLowerCase();
     // Tier 1: exact full-id match
     const exact = flat.filter((s) => s.id.toLowerCase() === q);
     if (exact.length > 0 && isFullPath)
@@ -214,9 +293,11 @@ export function findSections(sections, query) {
     fuzzy.sort((a, b) => a.distance - b.distance);
     return [...exact, ...subsection, ...fuzzy.map((f) => f.section)];
 }
-export function extractRefs(filePath, content) {
+export function extractRefs(filePath, content, latticeDir) {
     const tree = parse(stripFrontmatter(content));
-    const file = basename(filePath, '.md');
+    const file = latticeDir
+        ? relative(latticeDir, filePath).replace(/\.md$/, '')
+        : basename(filePath, '.md');
     const refs = [];
     // Build a flat list of sections to determine enclosing section for each wiki link
     const flat = [];

package/dist/src/walk.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Walk a directory tree respecting .gitignore rules. Returns relative paths
+ * of all non-ignored files, excluding .git/ and dotfiles (e.g. .gitignore).
+ *
+ * Results are memoized by resolved directory path — safe because CLI commands
+ * don't modify the filesystem during a run. Set _LAT_TEST_DISABLE_FS_CACHE=1
+ * to bypass caching in tests that mutate the filesystem mid-run.
+ *
+ * This is the single entry point for all directory walking in lat.md — both
+ * code-ref scanning and lat.md/ index validation use it so .gitignore rules
+ * are consistently honored.
+ */
+export declare function walkEntries(dir: string): Promise<string[]>;

package/dist/src/walk.js

@@ -0,0 +1,32 @@
+import { resolve } from 'node:path';
+// @ts-expect-error -- no type declarations
+import walk from 'ignore-walk';
+const cache = new Map();
+/**
+ * Walk a directory tree respecting .gitignore rules. Returns relative paths
+ * of all non-ignored files, excluding .git/ and dotfiles (e.g. .gitignore).
+ *
+ * Results are memoized by resolved directory path — safe because CLI commands
+ * don't modify the filesystem during a run. Set _LAT_TEST_DISABLE_FS_CACHE=1
+ * to bypass caching in tests that mutate the filesystem mid-run.
+ *
+ * This is the single entry point for all directory walking in lat.md — both
+ * code-ref scanning and lat.md/ index validation use it so .gitignore rules
+ * are consistently honored.
+ */
+export function walkEntries(dir) {
+    const noCache = !!process.env._LAT_TEST_DISABLE_FS_CACHE;
+    if (!noCache) {
+        const cached = cache.get(resolve(dir));
+        if (cached)
+            return cached;
+    }
+    const result = walk({
+        path: dir,
+        ignoreFiles: ['.gitignore'],
+    }).then((entries) => entries.filter((e) => !e.startsWith('.git/') && !e.startsWith('.')));
+    if (!noCache) {
+        cache.set(resolve(dir), result);
+    }
+    return result;
+}

package/package.json

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

package/templates/AGENTS.md

@@ -33,7 +33,7 @@ If `lat search` fails because `LAT_LLM_KEY` is not set, explain to the user that
 
 # Syntax primer
 
-- **Section ids**: `file-stem#Heading#SubHeading` (e.g. `cli#search#Indexing`)
+- **Section ids**: `path/to/file#Heading#SubHeading` — full form uses vault-relative path (e.g. `tests/search#RAG Replay Tests`). Short form uses bare file name when unique (e.g. `search#RAG Replay Tests`, `cli#search#Indexing`).
 - **Wiki links**: `[[target]]` or `[[target|alias]]` — cross-references between sections
 - **Code refs**: `// @lat: [[section-id]]` (JS/TS) or `# @lat: [[section-id]]` (Python) — ties source code to concepts
 
@@ -50,9 +50,14 @@ lat:
 
 ## User login
 ### 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.
 ```
 
+Every section MUST have a description — at least one sentence explaining what the test verifies and why. Empty sections with just a heading are not acceptable.
+
 Each test in code should reference its spec with exactly one comment placed next to the relevant test — not at the top of the file:
 
 ```python

package/templates/init/lat.md

@@ -0,0 +1 @@
+This directory defines the high-level concepts, business logic, and architecture of this project using markdown. It is managed by [lat.md](https://www.npmjs.com/package/lat.md) — a tool that anchors source code to these definitions. Install the `lat` command with `npm i -g lat.md` and run `lat --help`.

package/dist/src/cli.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-export {};

package/dist/src/cli.js

@@ -1,23 +0,0 @@
-#!/usr/bin/env node
-import { findLatticeDir, loadAllSections, findSections } from './lattice.js';
-const args = process.argv.slice(2);
-const command = args[0];
-if (command !== 'locate' || args.length < 2) {
-    console.error('Usage: lat locate <query>');
-    process.exit(1);
-}
-const query = args[1];
-const latticeDir = findLatticeDir();
-if (!latticeDir) {
-    console.error('No .lattice directory found');
-    process.exit(1);
-}
-const sections = await loadAllSections(latticeDir);
-const matches = findSections(sections, query);
-if (matches.length === 0) {
-    console.error(`No sections matching "${query}"`);
-    process.exit(1);
-}
-for (const m of matches) {
-    console.log(m.id);
-}

package/templates/init/README.md

@@ -1,5 +0,0 @@
-This directory defines the high-level concepts, business logic, and architecture of this project using markdown.
-
-It is managed by [lat.md](https://www.npmjs.com/package/lat.md) — a tool that anchors source code to these definitions.
-
-Install the `lat` command with `npm i -g lat.md` and run `lat --help`.