lat.md 0.8.1 → 0.9.0

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/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

@@ -1,11 +1,13 @@
 import { existsSync, cpSync, mkdirSync, writeFileSync, readFileSync, } from 'node:fs';
 import { join, resolve } from 'node:path';
+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 { getConfigPath, readConfig, writeConfig, } from '../config.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';
 import { selectMenu } from './select-menu.js';
 async function confirm(rl, message) {
     while (true) {
@@ -86,10 +88,26 @@ function resolveLatBin() {
     // .ts file but no special loader flags — best-effort, just return the path
     return script;
 }
+/** Return the lat binary string for the given command style. */
+function latBinString(style) {
+    if (style === 'global')
+        return 'lat';
+    if (style === 'npx')
+        return 'npx lat.md@latest';
+    return resolveLatBin();
+}
+/** Return the MCP server command descriptor for the given command style. */
+function styledMcpCommand(style) {
+    if (style === 'global')
+        return { command: 'lat', args: ['mcp'] };
+    if (style === 'npx')
+        return { command: 'npx', args: ['lat.md@latest', 'mcp'] };
+    return mcpCommand();
+}
 // ── Claude Code helpers ──────────────────────────────────────────────
-/** Derive the hook command prefix from the currently running binary. */
-function latHookCommand(event) {
-    return `${resolveLatBin()} hook claude ${event}`;
+/** Derive the hook command prefix for the given command style. */
+function latHookCommand(style, event) {
+    return `${latBinString(style)} hook claude ${event}`;
 }
 /** True if any command in this entry looks like it was installed by lat. */
 function isLatHookEntry(entry) {
@@ -103,7 +121,7 @@ function isLatHookEntry(entry) {
  * Remove all lat-owned hook entries from settings, then add fresh ones.
  * Preserves any non-lat hooks the user may have configured.
  */
-function syncLatHooks(settingsPath) {
+function syncLatHooks(settingsPath, style) {
     let settings = {};
     if (existsSync(settingsPath)) {
         const raw = readFileSync(settingsPath, 'utf-8');
@@ -136,7 +154,7 @@ function syncLatHooks(settingsPath) {
             hooks[event] = [];
         }
         hooks[event].push({
-            hooks: [{ type: 'command', command: latHookCommand(event) }],
+            hooks: [{ type: 'command', command: latHookCommand(style, event) }],
         });
     }
     writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
@@ -154,6 +172,25 @@ function ensureGitignored(root, entry) {
             return;
         }
     }
+    // Skip if the entry is already tracked in git — adding it to .gitignore
+    // would have no effect and confuse the user.
+    if (existsSync(gitDir)) {
+        try {
+            const result = execSync(`git ls-files "${entry}"`, {
+                cwd: root,
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            if (result.trim().length > 0) {
+                console.log(chalk.yellow(`  ${entry}`) +
+                    ' is already checked in to git — skipping .gitignore');
+                return;
+            }
+        }
+        catch {
+            console.log(chalk.yellow(`  Warning:`) + ' git ls-files failed — skipping check');
+        }
+    }
     if (existsSync(gitignorePath)) {
         // Append to existing .gitignore
         let content = readFileSync(gitignorePath, 'utf-8');
@@ -215,7 +252,7 @@ function hasMcpServer(configPath, key) {
         return false;
     }
 }
-function addMcpServer(configPath, key) {
+function addMcpServer(configPath, key, style) {
     let cfg = { [key]: {} };
     if (existsSync(configPath)) {
         const raw = readFileSync(configPath, 'utf-8');
@@ -228,7 +265,7 @@ function addMcpServer(configPath, key) {
             throw new Error(`Cannot parse ${configPath}: ${e.message}`);
         }
     }
-    cfg[key].lat = mcpCommand();
+    cfg[key].lat = styledMcpCommand(style);
     mkdirSync(join(configPath, '..'), { recursive: true });
     writeFileSync(configPath, JSON.stringify(cfg, null, 2) + '\n');
 }
@@ -277,13 +314,22 @@ 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);
     if (hash)
         hashes['AGENTS.md'] = hash;
 }
-async function setupClaudeCode(root, latDir, template, hashes, ask) {
+async function setupClaudeCode(root, latDir, template, hashes, ask, style) {
     // CLAUDE.md — written directly (not a symlink)
     const hash = await writeTemplateFile(root, latDir, 'CLAUDE.md', template, 'claude.md', 'CLAUDE.md', '  ', ask);
     if (hash)
@@ -295,8 +341,15 @@ async function setupClaudeCode(root, latDir, template, hashes, ask) {
     const claudeDir = join(root, '.claude');
     const settingsPath = join(claudeDir, 'settings.json');
     mkdirSync(claudeDir, { recursive: true });
-    syncLatHooks(settingsPath);
+    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
@@ -308,13 +361,13 @@ async function setupClaudeCode(root, latDir, template, hashes, ask) {
         console.log(chalk.green('  MCP server') + ' already configured');
     }
     else {
-        addMcpServer(mcpPath, 'mcpServers');
+        addMcpServer(mcpPath, 'mcpServers', style);
         console.log(chalk.green('  MCP server') + ' registered in .mcp.json');
     }
     // Ensure .mcp.json is gitignored (it contains local absolute paths)
     ensureGitignored(root, '.mcp.json');
 }
-async function setupCursor(root, latDir, hashes, ask) {
+async function setupCursor(root, latDir, hashes, ask, style) {
     // .cursor/rules/lat.md
     const hash = await writeTemplateFile(root, latDir, '.cursor/rules/lat.md', readCursorRulesTemplate(), 'cursor-rules.md', 'Rules (.cursor/rules/lat.md)', '  ', ask);
     if (hash)
@@ -328,16 +381,18 @@ async function setupCursor(root, latDir, hashes, ask) {
         console.log(chalk.green('  MCP server') + ' already configured');
     }
     else {
-        addMcpServer(mcpPath, 'mcpServers');
+        addMcpServer(mcpPath, 'mcpServers', style);
         console.log(chalk.green('  MCP server') + ' registered in .cursor/mcp.json');
     }
     // 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"');
 }
-async function setupCopilot(root, latDir, hashes, ask) {
+async function setupCopilot(root, latDir, hashes, ask, style) {
     // .github/copilot-instructions.md
     const hash = await writeTemplateFile(root, latDir, '.github/copilot-instructions.md', readAgentsTemplate(), 'agents.md', 'Instructions (.github/copilot-instructions.md)', '  ', ask);
     if (hash)
@@ -351,41 +406,40 @@ async function setupCopilot(root, latDir, hashes, ask) {
         console.log(chalk.green('  MCP server') + ' already configured');
     }
     else {
-        addMcpServer(mcpPath, 'servers');
+        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) {
+async function setupPi(root, latDir, hashes, ask, style) {
     // AGENTS.md — Pi reads this natively
     // (already created in the shared step if any non-Claude agent is selected)
     // .pi/extensions/lat.ts — extension that registers tools + lifecycle hooks
     console.log('');
     console.log(chalk.dim('  The Pi extension registers lat tools and hooks into the agent lifecycle'));
     console.log(chalk.dim('  to inject search context and validate lat.md/ before finishing.'));
-    const template = readPiExtensionTemplate().replace('__LAT_BIN__', resolveLatBin());
+    const template = readPiExtensionTemplate().replace('__LAT_BIN__', latBinString(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');
 }
 // ── LLM key setup ───────────────────────────────────────────────────
 async function setupLlmKey(rl) {
-    // Check env var first
-    const envKey = process.env.LAT_LLM_KEY;
-    if (envKey) {
+    // Use the centralized key resolution (env var → file → helper → config)
+    const existingKey = getLlmKey();
+    if (existingKey) {
         console.log('');
-        console.log(chalk.green('Semantic search') + ' — LAT_LLM_KEY is set. Ready.');
-        return;
-    }
-    // Check existing config
-    const config = readConfig();
-    const configPath = getConfigPath();
-    if (config.llm_key) {
-        console.log('');
-        console.log(chalk.green('Semantic search') +
-            ' — LLM key configured in ' +
-            chalk.dim(configPath));
+        console.log(chalk.green('Semantic search') + ' — LLM key found. Ready.');
         return;
     }
     // No key found — explain what semantic search is and prompt
@@ -445,12 +499,35 @@ async function setupLlmKey(rl) {
         console.log('  Saving anyway — you can update it later.');
     }
     // Save to config
-    const updatedConfig = { ...config, llm_key: key };
+    const updatedConfig = { ...readConfig(), llm_key: key };
     writeConfig(updatedConfig);
-    console.log(chalk.green('  Key saved') + ' to ' + chalk.dim(configPath));
+    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();
+    const local = getLocalVersion();
+    if (latest && latest !== local) {
+        console.log(' ' +
+            chalk.yellow('update available:') +
+            ' ' +
+            local +
+            ' → ' +
+            chalk.green(latest) +
+            ' — run ' +
+            chalk.cyan('npm install -g lat.md') +
+            ' to update.');
+        console.log('');
+    }
+    else {
+        console.log(' ' + chalk.green(`latest version is used (${local})`));
+    }
     const root = resolve(targetDir ?? process.cwd());
     const latDir = join(root, 'lat.md');
     const interactive = process.stdin.isTTY ?? false;
@@ -508,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,
                 },
@@ -528,6 +605,24 @@ export async function initCmd(targetDir) {
         const useCopilot = selectedAgents.includes('copilot');
         const useCodex = selectedAgents.includes('codex');
         const anySelected = selectedAgents.length > 0;
+        const needsLatCommand = useClaudeCode || usePi || useCursor || useCopilot;
+        // Step 2b: How should agents run lat?
+        let commandStyle = 'local';
+        if (anySelected && needsLatCommand && interactive) {
+            console.log('');
+            const localBin = resolveLatBin();
+            const styleOptions = [
+                { label: 'lat', value: 'global' },
+                { label: localBin, value: 'local' },
+                { label: 'npx lat.md@latest', value: 'npx' },
+            ];
+            const styleChoice = await selectMenu(styleOptions, 'How should agents run lat?', 0);
+            if (!styleChoice) {
+                console.log('Aborted.');
+                return;
+            }
+            commandStyle = styleChoice;
+        }
         // Now that selectMenu is done, it's safe to create the readline interface.
         // selectMenu has restored stdin to its original state (paused, non-raw).
         if (interactive) {
@@ -555,27 +650,28 @@ export async function initCmd(targetDir) {
         if (useClaudeCode) {
             console.log('');
             console.log(chalk.bold('Setting up Claude Code...'));
-            await setupClaudeCode(root, latDir, template, fileHashes, ask);
+            await setupClaudeCode(root, latDir, template, fileHashes, ask, commandStyle);
         }
         if (usePi) {
             console.log('');
             console.log(chalk.bold('Setting up Pi...'));
-            await setupPi(root, latDir, fileHashes, ask);
+            await setupPi(root, latDir, fileHashes, ask, commandStyle);
         }
         if (useCursor) {
             console.log('');
             console.log(chalk.bold('Setting up Cursor...'));
-            await setupCursor(root, latDir, fileHashes, ask);
+            await setupCursor(root, latDir, fileHashes, ask, commandStyle);
         }
         if (useCopilot) {
             console.log('');
             console.log(chalk.bold('Setting up VS Code Copilot...'));
-            await setupCopilot(root, latDir, fileHashes, ask);
+            await setupCopilot(root, latDir, fileHashes, ask, commandStyle);
         }
         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);

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

@@ -0,0 +1,7 @@
+/** Walk up from this file to find the nearest package.json version. */
+export declare function getLocalVersion(): string;
+/**
+ * Fetch the latest published version of `lat.md` from the npm registry.
+ * Returns null if the fetch fails or times out (3s).
+ */
+export declare function fetchLatestVersion(): Promise<string | null>;

package/dist/src/version.js

@@ -0,0 +1,39 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Walk up from this file to find the nearest package.json version. */
+export function getLocalVersion() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        const candidate = join(dir, 'package.json');
+        try {
+            return JSON.parse(readFileSync(candidate, 'utf-8')).version;
+        }
+        catch { }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return '0.0.0';
+        dir = parent;
+    }
+}
+/**
+ * Fetch the latest published version of `lat.md` from the npm registry.
+ * Returns null if the fetch fails or times out (3s).
+ */
+export async function fetchLatestVersion() {
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 3000);
+        const res = await fetch('https://registry.npmjs.org/lat.md/latest', {
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return data.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lat.md",
-  "version": "0.8.1",
+  "version": "0.9.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/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