lat.md 0.8.2 → 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

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

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/package.json

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