lat.md 0.3.0 → 0.4.1

package/README.md

@@ -29,7 +29,7 @@ npm install -g lat.md
 
 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.
+After installing, run `lat init` in the repo you want to use lat in.
 
 ## How it works
 
@@ -58,6 +58,15 @@ npx lat.md search "how do we auth?"    # semantic search via embeddings
 npx lat.md prompt "fix [[OAuth Flow]]" # expand [[refs]] in a prompt for agents
 ```
 
+## Configuration
+
+Semantic search (`lat search`) requires an OpenAI (`sk-...`) or Vercel AI Gateway (`vck_...`) API key. The key is resolved in order:
+
+1. `LAT_LLM_KEY` env var — direct value
+2. `LAT_LLM_KEY_FILE` env var — path to a file containing the key
+3. `LAT_LLM_KEY_HELPER` env var — shell command that prints the key (10s timeout)
+4. Config file — saved by `lat init`. Run `lat config` to see its location.
+
 ## Development
 
 Requires Node.js 22+ and pnpm.

package/dist/src/cli/check.js

@@ -288,4 +288,19 @@ export async function checkAllCmd(ctx) {
     if (totalErrors > 0)
         process.exit(1);
     console.log(ctx.chalk.green('All checks passed'));
+    const { getLlmKey } = await import('../config.js');
+    let hasKey = false;
+    try {
+        hasKey = !!getLlmKey();
+    }
+    catch {
+        // key resolution failed (e.g. empty file) — treat as missing
+    }
+    if (!hasKey) {
+        console.log(ctx.chalk.yellow('Warning:') +
+            ' No LLM key found — semantic search (lat search) will not work.' +
+            ' Provide a key via LAT_LLM_KEY, LAT_LLM_KEY_FILE, LAT_LLM_KEY_HELPER, or run ' +
+            ctx.chalk.cyan('lat init') +
+            ' to configure.');
+    }
 }

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

@@ -1,2 +1,3 @@
 export declare function readAgentsTemplate(): string;
+export declare function readCursorRulesTemplate(): string;
 export declare function genCmd(target: string): Promise<void>;

package/dist/src/cli/gen.js

@@ -4,6 +4,9 @@ import { findTemplatesDir } from './templates.js';
 export function readAgentsTemplate() {
     return readFileSync(join(findTemplatesDir(), 'AGENTS.md'), 'utf-8');
 }
+export function readCursorRulesTemplate() {
+    return readFileSync(join(findTemplatesDir(), 'cursor-rules.md'), 'utf-8');
+}
 export async function genCmd(target) {
     const normalized = target.toLowerCase();
     if (normalized !== 'agents.md' && normalized !== 'claude.md') {

package/dist/src/cli/index.js

@@ -3,7 +3,7 @@
 if (!process.argv.includes('--verbose')) {
     process.noDeprecation = true;
 }
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
@@ -138,4 +138,20 @@ program
     const { initCmd } = await import('./init.js');
     await initCmd(dir);
 });
+program
+    .command('mcp')
+    .description('Start the MCP server (stdio transport)')
+    .action(async () => {
+    const { startMcpServer } = await import('../mcp/server.js');
+    await startMcpServer();
+});
+program
+    .command('config')
+    .description('Show configuration file path')
+    .action(async () => {
+    const { getConfigPath } = await import('../config.js');
+    const configPath = getConfigPath();
+    const exists = existsSync(configPath);
+    console.log(`Config file: ${configPath}${exists ? '' : ' (not found)'}`);
+});
 await program.parseAsync();

package/dist/src/cli/init.js

@@ -1,22 +1,33 @@
-import { existsSync, cpSync, mkdirSync, writeFileSync, readFileSync, copyFileSync, chmodSync, symlinkSync, } from 'node:fs';
+import { existsSync, cpSync, mkdirSync, writeFileSync, readFileSync, copyFileSync, chmodSync, } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import chalk from 'chalk';
 import { findTemplatesDir } from './templates.js';
-import { readAgentsTemplate } from './gen.js';
+import { readAgentsTemplate, readCursorRulesTemplate } from './gen.js';
+import { getConfigPath, readConfig, writeConfig, } from '../config.js';
 async function confirm(rl, message) {
     try {
         const answer = await rl.question(`${message} ${chalk.dim('[Y/n]')} `);
         return answer.trim().toLowerCase() !== 'n';
     }
     catch {
-        return true;
+        // Ctrl+C or closed stdin — abort
+        console.log('');
+        process.exit(130);
     }
 }
+async function prompt(rl, message) {
+    try {
+        const answer = await rl.question(message);
+        return answer.trim();
+    }
+    catch {
+        console.log('');
+        process.exit(130);
+    }
+}
+// ── Claude Code helpers ──────────────────────────────────────────────
 const HOOK_COMMAND = '.claude/hooks/lat-prompt-hook.sh';
-/**
- * Check if .claude/settings.json already has the lat-prompt hook configured.
- */
 function hasLatHook(settingsPath) {
     if (!existsSync(settingsPath))
         return false;
@@ -31,17 +42,15 @@ function hasLatHook(settingsPath) {
         return false;
     }
 }
-/**
- * Add the lat-prompt hook to .claude/settings.json, preserving existing config.
- */
 function addLatHook(settingsPath) {
     let settings = {};
     if (existsSync(settingsPath)) {
+        const raw = readFileSync(settingsPath, 'utf-8');
         try {
-            settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+            settings = JSON.parse(raw);
         }
-        catch {
-            // Corrupted file — start fresh
+        catch (e) {
+            throw new Error(`Cannot parse ${settingsPath}: ${e.message}`);
         }
     }
     if (!settings.hooks || typeof settings.hooks !== 'object') {
@@ -56,6 +65,278 @@ function addLatHook(settingsPath) {
     });
     writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
 }
+// ── Gitignore helper ─────────────────────────────────────────────────
+function ensureGitignored(root, entry) {
+    const gitignorePath = join(root, '.gitignore');
+    const gitDir = join(root, '.git');
+    // Check if already ignored
+    if (existsSync(gitignorePath)) {
+        const content = readFileSync(gitignorePath, 'utf-8');
+        const lines = content.split('\n').map((l) => l.trim());
+        if (lines.includes(entry)) {
+            console.log(chalk.green(`  ${entry}`) + ' already in .gitignore');
+            return;
+        }
+    }
+    if (existsSync(gitignorePath)) {
+        // Append to existing .gitignore
+        let content = readFileSync(gitignorePath, 'utf-8');
+        if (!content.endsWith('\n'))
+            content += '\n';
+        writeFileSync(gitignorePath, content + entry + '\n');
+        console.log(chalk.green(`  Added ${entry}`) + ' to .gitignore');
+    }
+    else if (existsSync(gitDir)) {
+        // Create .gitignore with the entry
+        writeFileSync(gitignorePath, entry + '\n');
+        console.log(chalk.green(`  Created .gitignore`) + ` with ${entry}`);
+    }
+    else {
+        console.log(chalk.yellow(`  Warning:`) +
+            ` could not add ${entry} to .gitignore (not a git repository)`);
+    }
+}
+// ── MCP command detection ────────────────────────────────────────────
+/**
+ * Derive the MCP server command from the currently running binary.
+ * If `lat init` was invoked as `/path/to/lat`, we emit
+ * `{ command: "/path/to/lat", args: ["mcp"] }` so the MCP client
+ * starts the same binary.
+ */
+function mcpCommand() {
+    return { command: resolve(process.argv[1]), args: ['mcp'] };
+}
+function hasMcpServer(configPath) {
+    if (!existsSync(configPath))
+        return false;
+    try {
+        const cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
+        return !!cfg?.mcpServers?.lat;
+    }
+    catch {
+        return false;
+    }
+}
+function addMcpServer(configPath) {
+    let cfg = { mcpServers: {} };
+    if (existsSync(configPath)) {
+        const raw = readFileSync(configPath, 'utf-8');
+        try {
+            cfg = JSON.parse(raw);
+            if (!cfg.mcpServers)
+                cfg.mcpServers = {};
+        }
+        catch (e) {
+            throw new Error(`Cannot parse ${configPath}: ${e.message}`);
+        }
+    }
+    cfg.mcpServers.lat = mcpCommand();
+    mkdirSync(join(configPath, '..'), { recursive: true });
+    writeFileSync(configPath, JSON.stringify(cfg, null, 2) + '\n');
+}
+// ── Per-agent setup ──────────────────────────────────────────────────
+function setupAgentsMd(root, template) {
+    const agentsPath = join(root, 'AGENTS.md');
+    if (!existsSync(agentsPath)) {
+        writeFileSync(agentsPath, template);
+        console.log(chalk.green('Created AGENTS.md'));
+    }
+    else {
+        console.log(chalk.green('AGENTS.md') + ' already exists');
+    }
+}
+async function setupClaudeCode(root, template) {
+    const created = [];
+    // CLAUDE.md — written directly (not a symlink)
+    const claudePath = join(root, 'CLAUDE.md');
+    if (!existsSync(claudePath)) {
+        writeFileSync(claudePath, template);
+        console.log(chalk.green('  Created CLAUDE.md'));
+        created.push('CLAUDE.md');
+    }
+    else {
+        console.log(chalk.green('  CLAUDE.md') + ' already exists');
+    }
+    // Prompt hook
+    console.log('');
+    console.log(chalk.dim("  Claude Code doesn't reliably follow CLAUDE.md for per-prompt actions,"));
+    console.log(chalk.dim('  so we install a hook that injects lat.md workflow reminders into every prompt.'));
+    const claudeDir = join(root, '.claude');
+    const hooksDir = join(claudeDir, 'hooks');
+    const hookPath = join(hooksDir, 'lat-prompt-hook.sh');
+    const settingsPath = join(claudeDir, 'settings.json');
+    if (hasLatHook(settingsPath)) {
+        console.log(chalk.green('  Prompt hook') + ' already configured');
+    }
+    else {
+        mkdirSync(hooksDir, { recursive: true });
+        const templateHook = join(findTemplatesDir(), 'lat-prompt-hook.sh');
+        copyFileSync(templateHook, hookPath);
+        chmodSync(hookPath, 0o755);
+        addLatHook(settingsPath);
+        console.log(chalk.green('  Prompt hook') + ' installed');
+        created.push('.claude/hooks/lat-prompt-hook.sh');
+    }
+    // MCP server → .mcp.json at project root
+    console.log('');
+    console.log(chalk.dim('  Agents can call `lat` from the command line, but an MCP server gives lat'));
+    console.log(chalk.dim('  more visibility and makes agents more likely to use it proactively.'));
+    const mcpPath = join(root, '.mcp.json');
+    if (hasMcpServer(mcpPath)) {
+        console.log(chalk.green('  MCP server') + ' already configured');
+    }
+    else {
+        addMcpServer(mcpPath);
+        console.log(chalk.green('  MCP server') + ' registered in .mcp.json');
+        created.push('.mcp.json');
+    }
+    // Ensure .mcp.json is gitignored (it contains local absolute paths)
+    ensureGitignored(root, '.mcp.json');
+    return created;
+}
+async function setupCursor(root) {
+    const created = [];
+    // .cursor/rules/lat.md
+    const rulesDir = join(root, '.cursor', 'rules');
+    const rulesPath = join(rulesDir, 'lat.md');
+    if (!existsSync(rulesPath)) {
+        mkdirSync(rulesDir, { recursive: true });
+        writeFileSync(rulesPath, readCursorRulesTemplate());
+        console.log(chalk.green('  Rules') + ' created at .cursor/rules/lat.md');
+        created.push('.cursor/rules/lat.md');
+    }
+    else {
+        console.log(chalk.green('  Rules') + ' already exist');
+    }
+    // .cursor/mcp.json
+    console.log('');
+    console.log(chalk.dim('  Agents can call `lat` from the command line, but an MCP server gives lat'));
+    console.log(chalk.dim('  more visibility and makes agents more likely to use it proactively.'));
+    const mcpPath = join(root, '.cursor', 'mcp.json');
+    if (hasMcpServer(mcpPath)) {
+        console.log(chalk.green('  MCP server') + ' already configured');
+    }
+    else {
+        addMcpServer(mcpPath);
+        console.log(chalk.green('  MCP server') + ' registered in .cursor/mcp.json');
+        created.push('.cursor/mcp.json');
+    }
+    // Ensure .cursor/mcp.json is gitignored (it contains local absolute paths)
+    ensureGitignored(root, '.cursor/mcp.json');
+    console.log('');
+    console.log(chalk.yellow('  Note:') +
+        ' Enable MCP in Cursor: Settings → Features → MCP → check "Enable MCP"');
+    return created;
+}
+async function setupCopilot(root) {
+    const created = [];
+    // .github/copilot-instructions.md
+    const githubDir = join(root, '.github');
+    const instructionsPath = join(githubDir, 'copilot-instructions.md');
+    if (!existsSync(instructionsPath)) {
+        mkdirSync(githubDir, { recursive: true });
+        writeFileSync(instructionsPath, readAgentsTemplate());
+        console.log(chalk.green('  Instructions') +
+            ' created at .github/copilot-instructions.md');
+        created.push('.github/copilot-instructions.md');
+    }
+    else {
+        console.log(chalk.green('  Instructions') + ' already exist');
+    }
+    // .vscode/mcp.json
+    console.log('');
+    console.log(chalk.dim('  Agents can call `lat` from the command line, but an MCP server gives lat'));
+    console.log(chalk.dim('  more visibility and makes agents more likely to use it proactively.'));
+    const mcpPath = join(root, '.vscode', 'mcp.json');
+    if (hasMcpServer(mcpPath)) {
+        console.log(chalk.green('  MCP server') + ' already configured');
+    }
+    else {
+        addMcpServer(mcpPath);
+        console.log(chalk.green('  MCP server') + ' registered in .vscode/mcp.json');
+        created.push('.vscode/mcp.json');
+    }
+    return created;
+}
+// ── LLM key setup ───────────────────────────────────────────────────
+async function setupLlmKey(rl) {
+    console.log('');
+    console.log(chalk.bold('Semantic search'));
+    console.log('');
+    console.log('  lat.md includes semantic search (' +
+        chalk.cyan('lat search') +
+        ') that lets agents find');
+    console.log('  relevant documentation by meaning, not just keywords. This requires an');
+    console.log('  embedding API key (OpenAI or Vercel AI Gateway). Without it, agents can still');
+    console.log('  use ' +
+        chalk.cyan('lat locate') +
+        ' for exact lookups, but will miss semantic matches.');
+    console.log('');
+    // Check env var first
+    const envKey = process.env.LAT_LLM_KEY;
+    if (envKey) {
+        console.log(chalk.green('  LAT_LLM_KEY') +
+            ' is set in your environment. Semantic search is ready.');
+        return;
+    }
+    // Check existing config
+    const config = readConfig();
+    const configPath = getConfigPath();
+    if (config.llm_key) {
+        console.log(chalk.green('  LLM key') +
+            ' already configured in ' +
+            chalk.dim(configPath));
+        return;
+    }
+    // Interactive prompt
+    if (!rl) {
+        console.log(chalk.yellow('  No LLM key found.') +
+            ' Set LAT_LLM_KEY env var or run ' +
+            chalk.cyan('lat init') +
+            ' interactively.');
+        return;
+    }
+    console.log('  You can provide a key now, or skip and set ' +
+        chalk.cyan('LAT_LLM_KEY') +
+        ' env var later.');
+    console.log('  Supported: OpenAI (' +
+        chalk.dim('sk-...') +
+        ') or Vercel AI Gateway (' +
+        chalk.dim('vck_...') +
+        ')');
+    console.log('');
+    const key = await prompt(rl, `  Paste your key (or press Enter to skip): `);
+    if (!key) {
+        console.log(chalk.dim('  Skipped.') +
+            ' You can set ' +
+            chalk.cyan('LAT_LLM_KEY') +
+            ' later or re-run ' +
+            chalk.cyan('lat init') +
+            '.');
+        return;
+    }
+    // Validate prefix
+    if (key.startsWith('sk-ant-')) {
+        console.log(chalk.red('  That looks like an Anthropic key.') +
+            " Anthropic doesn't offer embeddings.");
+        console.log('  lat.md needs an OpenAI (' +
+            chalk.dim('sk-...') +
+            ') or Vercel AI Gateway (' +
+            chalk.dim('vck_...') +
+            ') key.');
+        return;
+    }
+    if (!key.startsWith('sk-') && !key.startsWith('vck_')) {
+        console.log(chalk.yellow('  Unrecognized key prefix.') +
+            ' Expected sk-... (OpenAI) or vck_... (Vercel AI Gateway).');
+        console.log('  Saving anyway — you can update it later.');
+    }
+    // Save to config
+    const updatedConfig = { ...config, llm_key: key };
+    writeConfig(updatedConfig);
+    console.log(chalk.green('  Key saved') + ' to ' + chalk.dim(configPath));
+}
+// ── Main init flow ───────────────────────────────────────────────────
 export async function initCmd(targetDir) {
     const root = resolve(targetDir ?? process.cwd());
     const latDir = join(root, 'lat.md');
@@ -83,51 +364,57 @@ export async function initCmd(targetDir) {
             cpSync(templateDir, latDir, { recursive: true });
             console.log(chalk.green('Created lat.md/'));
         }
-        // Step 2: AGENTS.md / CLAUDE.md
-        const agentsPath = join(root, 'AGENTS.md');
-        const claudePath = join(root, 'CLAUDE.md');
-        const hasAgents = existsSync(agentsPath);
-        const hasClaude = existsSync(claudePath);
-        if (!hasAgents && !hasClaude) {
-            if (await ask('Generate AGENTS.md and CLAUDE.md with lat.md instructions for coding agents?')) {
-                const template = readAgentsTemplate();
-                writeFileSync(agentsPath, template);
-                symlinkSync('AGENTS.md', claudePath);
-                console.log(chalk.green('Created AGENTS.md and CLAUDE.md → AGENTS.md'));
-            }
+        // Step 2: Which coding agents do you use?
+        console.log('');
+        console.log(chalk.bold('Which coding agents do you use?'));
+        console.log('');
+        const useClaudeCode = await ask('  Claude Code?');
+        const useCursor = await ask('  Cursor?');
+        const useCopilot = await ask('  VS Code Copilot?');
+        const useCodex = await ask('  Codex / OpenCode?');
+        const anySelected = useClaudeCode || useCursor || useCopilot || useCodex;
+        if (!anySelected) {
+            console.log('');
+            console.log(chalk.dim('No agents selected. You can re-run') +
+                ' lat init ' +
+                chalk.dim('later.'));
+            return;
         }
-        else {
-            const existing = [hasAgents && 'AGENTS.md', hasClaude && 'CLAUDE.md']
-                .filter(Boolean)
-                .join(' and ');
-            console.log(`\n${existing} already exists. Run ${chalk.cyan('lat gen agents.md')} to preview the template,` +
-                ` then incorporate its content or overwrite as needed.`);
+        console.log('');
+        const template = readAgentsTemplate();
+        // Step 3: AGENTS.md (shared by non-Claude agents)
+        const needsAgentsMd = useCursor || useCopilot || useCodex;
+        if (needsAgentsMd) {
+            setupAgentsMd(root, template);
         }
-        // Step 3: Claude Code prompt hook
-        const claudeDir = join(root, '.claude');
-        const hooksDir = join(claudeDir, 'hooks');
-        const hookPath = join(hooksDir, 'lat-prompt-hook.sh');
-        const settingsPath = join(claudeDir, 'settings.json');
-        if (hasLatHook(settingsPath)) {
-            console.log(chalk.green('Claude Code hook') + ' already configured');
+        // Step 4: Per-agent setup
+        if (useClaudeCode) {
+            console.log('');
+            console.log(chalk.bold('Setting up Claude Code...'));
+            await setupClaudeCode(root, template);
         }
-        else {
+        if (useCursor) {
             console.log('');
-            console.log(chalk.bold('Claude Code hook') +
-                ' — adds a per-prompt reminder for the agent to consult lat.md');
-            console.log(chalk.dim('  Creates .claude/hooks/lat-prompt-hook.sh and registers it in .claude/settings.json'));
-            console.log(chalk.dim('  On every prompt, the agent is instructed to run `lat search` and `lat prompt` before working.'));
-            if (await ask('Set up Claude Code prompt hook?')) {
-                mkdirSync(hooksDir, { recursive: true });
-                const templateHook = join(findTemplatesDir(), 'lat-prompt-hook.sh');
-                copyFileSync(templateHook, hookPath);
-                chmodSync(hookPath, 0o755);
-                addLatHook(settingsPath);
-                console.log(chalk.green('Created .claude/hooks/lat-prompt-hook.sh'));
-                console.log(chalk.green('Updated .claude/settings.json') +
-                    ' with UserPromptSubmit hook');
-            }
+            console.log(chalk.bold('Setting up Cursor...'));
+            await setupCursor(root);
+        }
+        if (useCopilot) {
+            console.log('');
+            console.log(chalk.bold('Setting up VS Code Copilot...'));
+            await setupCopilot(root);
+        }
+        if (useCodex) {
+            console.log('');
+            console.log(chalk.bold('Codex / OpenCode') +
+                ' — uses AGENTS.md (already created). No additional setup needed.');
         }
+        // Step 5: LLM key setup
+        await setupLlmKey(rl);
+        console.log('');
+        console.log(chalk.green('Done!') +
+            ' Run ' +
+            chalk.cyan('lat check') +
+            ' to validate your setup.');
     }
     finally {
         rl?.close();

package/dist/src/cli/search.js

@@ -5,10 +5,23 @@ 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) {
-    const key = process.env.LAT_LLM_KEY;
+    let key;
+    try {
+        key = getLlmKey();
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
     if (!key) {
-        console.error(chalk.red('LAT_LLM_KEY is not set. Set it to an OpenAI (sk-...) or Vercel AI (vck_...) 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);
     }
     const provider = detectProvider(key);

package/dist/src/config.d.ts

@@ -0,0 +1,17 @@
+export declare function getConfigDir(): string;
+export declare function getConfigPath(): string;
+export type LatConfig = {
+    llm_key?: string;
+};
+export declare function readConfig(): LatConfig;
+export declare function writeConfig(config: LatConfig): void;
+/**
+ * Returns the LLM key from (in priority order):
+ * 1. LAT_LLM_KEY environment variable
+ * 2. LAT_LLM_KEY_FILE — path to a file containing the key
+ * 3. LAT_LLM_KEY_HELPER — shell command that prints the key
+ * 4. llm_key field in ~/.config/lat/config.json
+ *
+ * Returns undefined if none is set.
+ */
+export declare function getLlmKey(): string | undefined;

package/dist/src/config.js

@@ -0,0 +1,65 @@
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import xdg from '@folder/xdg';
+// ── XDG config directory ────────────────────────────────────────────
+export function getConfigDir() {
+    return join(xdg().config, 'lat');
+}
+export function getConfigPath() {
+    return join(getConfigDir(), 'config.json');
+}
+export function readConfig() {
+    const configPath = getConfigPath();
+    if (!existsSync(configPath))
+        return {};
+    try {
+        return JSON.parse(readFileSync(configPath, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeConfig(config) {
+    const dir = getConfigDir();
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(getConfigPath(), JSON.stringify(config, null, 2) + '\n');
+}
+// ── Centralized LLM key resolution ─────────────────────────────────
+/**
+ * Returns the LLM key from (in priority order):
+ * 1. LAT_LLM_KEY environment variable
+ * 2. LAT_LLM_KEY_FILE — path to a file containing the key
+ * 3. LAT_LLM_KEY_HELPER — shell command that prints the key
+ * 4. llm_key field in ~/.config/lat/config.json
+ *
+ * Returns undefined if none is set.
+ */
+export function getLlmKey() {
+    const envKey = process.env.LAT_LLM_KEY;
+    if (envKey)
+        return envKey;
+    const file = process.env.LAT_LLM_KEY_FILE;
+    if (file) {
+        const content = readFileSync(file, 'utf-8').trim();
+        if (!content) {
+            throw new Error(`LAT_LLM_KEY_FILE (${file}) is empty.`);
+        }
+        return content;
+    }
+    const helper = process.env.LAT_LLM_KEY_HELPER;
+    if (helper) {
+        const result = execSync(helper, {
+            encoding: 'utf-8',
+            timeout: 10_000,
+        }).trim();
+        if (!result) {
+            throw new Error('LAT_LLM_KEY_HELPER command returned an empty string.');
+        }
+        return result;
+    }
+    const config = readConfig();
+    if (config.llm_key)
+        return config.llm_key;
+    return undefined;
+}

package/dist/src/mcp/server.d.ts

@@ -0,0 +1 @@
+export declare function startMcpServer(): Promise<void>;

package/dist/src/mcp/server.js

@@ -0,0 +1,310 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { relative } from 'node:path';
+import { findLatticeDir, loadAllSections, findSections, flattenSections, buildFileIndex, resolveRef, extractRefs, listLatticeFiles, } from '../lattice.js';
+import { scanCodeRefs } from '../code-refs.js';
+import { checkMd, checkCodeRefs, checkIndex } from '../cli/check.js';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+function formatSection(s, latDir) {
+    const relPath = relative(process.cwd(), latDir + '/' + s.file + '.md');
+    const kind = s.id.includes('#') ? 'Section' : 'File';
+    const lines = [
+        `* ${kind}: [[${s.id}]]`,
+        `  Defined in ${relPath}:${s.startLine}-${s.endLine}`,
+    ];
+    if (s.body) {
+        const truncated = s.body.length > 200 ? s.body.slice(0, 200) + '...' : s.body;
+        lines.push('', `  > ${truncated}`);
+    }
+    return lines.join('\n');
+}
+function formatMatches(header, matches, latDir) {
+    const lines = [header, ''];
+    for (let i = 0; i < matches.length; i++) {
+        if (i > 0)
+            lines.push('');
+        lines.push(formatSection(matches[i].section, latDir) + ` (${matches[i].reason})`);
+    }
+    return lines.join('\n');
+}
+export async function startMcpServer() {
+    const latDir = findLatticeDir();
+    if (!latDir) {
+        process.stderr.write('No lat.md directory found\n');
+        process.exit(1);
+    }
+    const server = new McpServer({
+        name: 'lat',
+        version: '1.0.0',
+    });
+    server.tool('lat_locate', 'Find sections by name (exact, fuzzy, subsequence matching)', { query: z.string().describe('Section name or id to search for') }, async ({ query }) => {
+        const sections = await loadAllSections(latDir);
+        const matches = findSections(sections, query.replace(/^\[\[|\]\]$/g, ''));
+        if (matches.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No sections matching "${query}"`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: formatMatches(`Sections matching "${query}":`, matches, latDir),
+                },
+            ],
+        };
+    });
+    server.tool('lat_search', 'Semantic search across lat.md sections using embeddings', {
+        query: z.string().describe('Search query in natural language'),
+        limit: z
+            .number()
+            .optional()
+            .default(5)
+            .describe('Max results (default 5)'),
+    }, async ({ query, limit }) => {
+        const { getLlmKey } = await import('../config.js');
+        let key;
+        try {
+            key = getLlmKey();
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: err.message }],
+                isError: true,
+            };
+        }
+        if (!key) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No LLM key found. Provide a key via LAT_LLM_KEY, LAT_LLM_KEY_FILE, LAT_LLM_KEY_HELPER, or run `lat init`.',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { detectProvider } = await import('../search/provider.js');
+        const { openDb, ensureSchema, closeDb } = await import('../search/db.js');
+        const { indexSections } = await import('../search/index.js');
+        const { searchSections } = await import('../search/search.js');
+        const provider = detectProvider(key);
+        const db = openDb(latDir);
+        try {
+            await ensureSchema(db, provider.dimensions);
+            await indexSections(latDir, db, provider, key);
+            const results = await searchSections(db, query, provider, key, limit);
+            if (results.length === 0) {
+                return {
+                    content: [{ type: 'text', text: 'No results found.' }],
+                };
+            }
+            const allSections = await loadAllSections(latDir);
+            const flat = flattenSections(allSections);
+            const byId = new Map(flat.map((s) => [s.id, s]));
+            const matched = results
+                .map((r) => byId.get(r.id))
+                .filter((s) => !!s)
+                .map((s) => ({ section: s, reason: 'semantic match' }));
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: formatMatches(`Search results for "${query}":`, matched, latDir),
+                    },
+                ],
+            };
+        }
+        finally {
+            await closeDb(db);
+        }
+    });
+    server.tool('lat_prompt', 'Expand [[refs]] in text to resolved lat.md section paths with context', { text: z.string().describe('Text containing [[refs]] to expand') }, async ({ text }) => {
+        const WIKI_LINK_RE = /\[\[([^\]]+)\]\]/g;
+        const allSections = await loadAllSections(latDir);
+        const refs = [...text.matchAll(WIKI_LINK_RE)];
+        if (refs.length === 0) {
+            return {
+                content: [{ type: 'text', text }],
+            };
+        }
+        const resolved = new Map();
+        const errors = [];
+        for (const match of refs) {
+            const target = match[1];
+            if (resolved.has(target))
+                continue;
+            const matches = findSections(allSections, target);
+            if (matches.length >= 1) {
+                resolved.set(target, {
+                    target,
+                    best: matches[0],
+                    alternatives: matches.slice(1),
+                });
+            }
+            else {
+                errors.push(`No section found for [[${target}]]`);
+            }
+        }
+        if (errors.length > 0) {
+            return {
+                content: [{ type: 'text', text: errors.join('\n') }],
+                isError: true,
+            };
+        }
+        let output = text.replace(WIKI_LINK_RE, (_match, target) => {
+            const ref = resolved.get(target);
+            return `[[${ref.best.section.id}]]`;
+        });
+        output += '\n\n<lat-context>\n';
+        for (const ref of resolved.values()) {
+            const isExact = ref.best.reason === 'exact match';
+            const all = isExact ? [ref.best] : [ref.best, ...ref.alternatives];
+            if (isExact) {
+                output += `* [[${ref.target}]] is referring to:\n`;
+            }
+            else {
+                output += `* [[${ref.target}]] might be referring to either of the following:\n`;
+            }
+            for (const m of all) {
+                const reason = isExact ? '' : ` (${m.reason})`;
+                const relPath = relative(process.cwd(), latDir + '/' + m.section.file + '.md');
+                output += `  * [[${m.section.id}]]${reason}\n`;
+                output += `    * ${relPath}:${m.section.startLine}-${m.section.endLine}\n`;
+                if (m.section.body) {
+                    output += `    * ${m.section.body}\n`;
+                }
+            }
+        }
+        output += '</lat-context>\n';
+        return {
+            content: [{ type: 'text', text: output }],
+        };
+    });
+    server.tool('lat_check', 'Validate all wiki links, code references, and directory indexes in lat.md', {}, async () => {
+        const md = await checkMd(latDir);
+        const code = await checkCodeRefs(latDir);
+        const indexErrors = await checkIndex(latDir);
+        const allErrors = [...md.errors, ...code.errors];
+        const lines = [];
+        for (const err of allErrors) {
+            lines.push(`${err.file}:${err.line}: ${err.message}`);
+        }
+        for (const err of indexErrors) {
+            lines.push(`${err.dir}: ${err.message}`);
+        }
+        const totalErrors = allErrors.length + indexErrors.length;
+        if (totalErrors === 0) {
+            return {
+                content: [{ type: 'text', text: 'All checks passed' }],
+            };
+        }
+        lines.push(`\n${totalErrors} error${totalErrors === 1 ? '' : 's'} found`);
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            isError: true,
+        };
+    });
+    server.tool('lat_refs', 'Find sections that reference a given section via wiki links or @lat code comments', {
+        query: z.string().describe('Section id to find references for'),
+        scope: z
+            .enum(['md', 'code', 'md+code'])
+            .optional()
+            .default('md')
+            .describe('Where to search: md, code, or md+code'),
+    }, async ({ query, scope }) => {
+        const allSections = await loadAllSections(latDir);
+        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) {
+            const matches = findSections(allSections, query);
+            if (matches.length > 0) {
+                const suggestions = matches
+                    .map((m) => `  * ${m.section.id} (${m.reason})`)
+                    .join('\n');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `No exact section "${query}" found. Did you mean:\n${suggestions}`,
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No section matching "${query}"`,
+                    },
+                ],
+            };
+        }
+        const targetId = exactMatch.id.toLowerCase();
+        const mdMatches = [];
+        const codeLines = [];
+        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, latDir);
+                for (const ref of fileRefs) {
+                    const { resolved: refResolved } = resolveRef(ref.target, sectionIds, fileIndex);
+                    if (refResolved.toLowerCase() === targetId) {
+                        matchingFromSections.add(ref.fromSection.toLowerCase());
+                    }
+                }
+            }
+            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' });
+                }
+            }
+        }
+        if (scope === 'code' || scope === 'md+code') {
+            const projectRoot = join(latDir, '..');
+            const { refs: codeRefs } = await scanCodeRefs(projectRoot);
+            for (const ref of codeRefs) {
+                const { resolved: codeResolved } = resolveRef(ref.target, sectionIds, fileIndex);
+                if (codeResolved.toLowerCase() === targetId) {
+                    codeLines.push(`${ref.file}:${ref.line}`);
+                }
+            }
+        }
+        if (mdMatches.length === 0 && codeLines.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No references to "${exactMatch.id}" found`,
+                    },
+                ],
+            };
+        }
+        const parts = [];
+        if (mdMatches.length > 0) {
+            parts.push(formatMatches(`References to "${exactMatch.id}":`, mdMatches, latDir));
+        }
+        if (codeLines.length > 0) {
+            parts.push('Code references:\n' + codeLines.map((l) => `* ${l}`).join('\n'));
+        }
+        return {
+            content: [{ type: 'text', text: parts.join('\n\n') }],
+        };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/src/search/provider.js

@@ -30,11 +30,11 @@ export function detectProvider(key) {
         };
     }
     if (key.startsWith('sk-ant-')) {
-        throw new Error("Anthropic doesn't offer an embedding model. Set LAT_LLM_KEY to an OpenAI (sk-...) or Vercel AI (vck_...) key.");
+        throw new Error("Anthropic doesn't offer an embedding model. Set LAT_LLM_KEY to an OpenAI (sk-...) or Vercel AI Gateway (vck_...) key.");
     }
     if (key.startsWith('vck_'))
         return vercel;
     if (key.startsWith('sk-'))
         return openai;
-    throw new Error(`Unrecognized LAT_LLM_KEY prefix. Supported: OpenAI (sk-...), Vercel AI (vck_...).`);
+    throw new Error(`Unrecognized LAT_LLM_KEY prefix. Supported: OpenAI (sk-...), Vercel AI Gateway (vck_...).`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lat.md",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "A knowledge graph for your codebase, written in markdown",
   "type": "module",
   "packageManager": "pnpm@10.30.2",
@@ -47,7 +47,9 @@
     "vitest": "^3.0.0"
   },
   "dependencies": {
+    "@folder/xdg": "^4.0.1",
     "@libsql/client": "^0.17.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "ignore-walk": "^8.0.0",
@@ -55,6 +57,7 @@
     "remark-parse": "^11.0.0",
     "remark-stringify": "^11.0.0",
     "unified": "^11.0.0",
-    "unist-util-visit": "^5.0.0"
+    "unist-util-visit": "^5.0.0",
+    "zod": "^4.3.6"
   }
 }

package/templates/AGENTS.md

@@ -29,7 +29,7 @@ lat check                      # validate all links and code refs
 
 Run `lat --help` when in doubt about available commands or options.
 
-If `lat search` fails because `LAT_LLM_KEY` is not set, explain to the user that semantic search requires an API key (`export LAT_LLM_KEY=sk-...` for OpenAI or `export LAT_LLM_KEY=vck_...` for Vercel). If the user doesn't want to set it up, use `lat locate` for direct lookups instead.
+If `lat search` fails because no API key is configured, explain to the user that semantic search requires a key provided via `LAT_LLM_KEY` (direct value), `LAT_LLM_KEY_FILE` (path to key file), or `LAT_LLM_KEY_HELPER` (command that prints the key). Supported key prefixes: `sk-...` (OpenAI) or `vck_...` (Vercel). If the user doesn't want to set it up, use `lat locate` for direct lookups instead.
 
 # Syntax primer
 

package/templates/cursor-rules.md

@@ -0,0 +1,71 @@
+# Before starting work
+
+- Use the `lat_search` tool to find sections relevant to your task. Read them to understand the design intent before writing code.
+- Use the `lat_prompt` tool on user prompts to expand any `[[refs]]` — this resolves section names to file locations and provides context.
+
+# Post-task checklist (REQUIRED — do not skip)
+
+After EVERY task, before responding to the user:
+
+- [ ] Update `lat.md/` if you added or changed any functionality, architecture, tests, or behavior
+- [ ] Use the `lat_check` tool — all wiki links and code refs must pass
+- [ ] Do not skip these steps. Do not consider your task done until both are complete.
+
+---
+
+# What is lat.md?
+
+This project uses [lat.md](https://www.npmjs.com/package/lat.md) to maintain a structured knowledge graph of its architecture, design decisions, and test specs in the `lat.md/` directory. It is a set of cross-linked markdown files that describe **what** this project does and **why** — the domain concepts, key design decisions, business logic, and test specifications. Use it to ground your work in the actual architecture rather than guessing.
+
+# Tools
+
+You have access to the following MCP tools from the `lat` server:
+
+- **lat_locate** — find a section by name (exact, fuzzy)
+- **lat_search** — semantic search across all sections
+- **lat_prompt** — expand `[[refs]]` in text to resolved locations
+- **lat_check** — validate all wiki links and code refs
+- **lat_refs** — find what references a section
+
+If `lat_search` fails because `LAT_LLM_KEY` is not set, explain to the user that semantic search requires an API key (`export LAT_LLM_KEY=sk-...` for OpenAI or `export LAT_LLM_KEY=vck_...` for Vercel). If the user doesn't want to set it up, use `lat_locate` for direct lookups instead.
+
+# Syntax primer
+
+- **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
+
+# Test specs
+
+Key tests can be described as sections in `lat.md/` files (e.g. `tests.md`). Add frontmatter to require that every leaf section is referenced by a `// @lat:` or `# @lat:` comment in test code:
+
+```markdown
+---
+lat:
+  require-code-mention: true
+---
+# Tests
+
+## 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
+# @lat: [[tests#User login#Rejects expired tokens]]
+def test_rejects_expired_tokens():
+    ...
+
+# @lat: [[tests#User login#Handles missing password]]
+def test_handles_missing_password():
+    ...
+```
+
+Do not duplicate refs. One `@lat:` comment per spec section, placed at the test that covers it. `lat check` will flag any spec section not covered by a code reference, and any code reference pointing to a nonexistent section.