@plebeiantech/lat.md 0.12.3-fork.4 → 0.12.3-fork.6

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

@@ -0,0 +1,2 @@
+import type { CheckError } from './check.js';
+export declare function checkCoverage(latticeDir: string, projectRoot?: string): Promise<CheckError[]>;

package/dist/src/cli/check-coverage.js

@@ -0,0 +1,71 @@
+import { readFile } from 'node:fs/promises';
+import { relative } from 'node:path';
+import { scanCodeRefs } from '../code-refs.js';
+import { listLatticeFiles } from '../lattice.js';
+import { indexNameFor } from './check-mode.js';
+import { toPosix } from '../walk.js';
+import { basename, dirname } from 'node:path';
+/**
+ * Fail a `lat.md/` tree that has documents and no `@lat:` ref pointing into it
+ * from anywhere in the codebase.
+ *
+ * `require-code-mention` was the only thing asking for refs, and it is opt-in
+ * frontmatter: an agent setting up a tree can simply not write it, and every
+ * check still passes. One did. Its reasons were both ordinary — it read a list
+ * of example comment markers as an exclusive language list and concluded its
+ * language was unsupported, and it was optimising for a green check rather
+ * than a correct one, so the option that could not fail was the one it took.
+ *
+ * A graph nothing points at cannot be reached from the code, which is the only
+ * reason it exists. So the floor is one ref, and the message says where to put
+ * the first one.
+ *
+ * Deliberately a floor and not a coverage ratio. Half this repository's own
+ * documents have no incoming ref and should not have one — a per-document rule
+ * would have to be either wrong here or watered down everywhere.
+ */
+/** Nothing to anchor: a tree of pure navigation, or a project with no code. */
+function isIndex(latticeDir, file) {
+    const holder = basename(dirname(file));
+    return (basename(file) ===
+        indexNameFor(holder === '' ? basename(latticeDir) : holder));
+}
+export async function checkCoverage(latticeDir, projectRoot = dirname(latticeDir)) {
+    const files = await listLatticeFiles(latticeDir);
+    const documents = files.filter((f) => !isIndex(latticeDir, f));
+    if (documents.length === 0)
+        return [];
+    const scan = await scanCodeRefs(projectRoot);
+    if (scan.files.length === 0)
+        return [];
+    if (scan.refs.length > 0)
+        return [];
+    const rootIndexPath = `${latticeDir}/${indexNameFor(basename(latticeDir))}`;
+    const rootIndexRel = toPosix(relative(process.cwd(), rootIndexPath));
+    // Quote the ref the reader should actually paste. A generic placeholder gets
+    // pasted verbatim and then fails `lat check code-refs`, which turns one
+    // error into two.
+    const stem = basename(latticeDir).replace(/\.md$/, '');
+    let anchor = `${stem}#Your Project`;
+    try {
+        const heading = (await readFile(rootIndexPath, 'utf-8')).match(/^#\s+(.+)$/m);
+        if (heading)
+            anchor = `${stem}#${heading[1].trim()}`;
+    }
+    catch {
+        // No root index, or unreadable — the placeholder still names the shape.
+    }
+    return [
+        {
+            file: rootIndexRel,
+            line: 1,
+            target: toPosix(relative(projectRoot, latticeDir)),
+            message: `${documents.length} document(s) here and no \`@lat:\` code ref anywhere in the project — nothing in the codebase can reach this graph.\n` +
+                '    Start at the application entrypoint (config/application.rb, src/index.ts, main.go, manage.py) and point it at the root index:\n' +
+                `        # @lat: [[${anchor}]]\n` +
+                '    Then add one ref per section that source code implements, at that code.\n' +
+                '    The marker is a comment syntax, not a language allowlist: `//` for C-family, `#` for Ruby, Python, shell, Elixir and the rest. The scan is textual and reads every non-markdown file.\n' +
+                '    An `@lat:` line is a machine directive, like a magic comment or a linter pragma. A project convention that minimises comments does not reach it.',
+        },
+    ];
+}

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

@@ -3,4 +3,10 @@ export declare const DIATAXIS_MODES: readonly ["tutorial", "how-to", "reference"
 export type DiataxisMode = (typeof DIATAXIS_MODES)[number];
 /** Directory below lat.md/ that holds each mode. */
 export declare const MODE_DIRS: Record<DiataxisMode, string>;
+/**
+ * The index file a directory is required to carry, e.g. `lat.md` for the root
+ * and `reference.md` for `reference/`. An index is navigation rather than
+ * content, so the `require-mode` gate below never asks one to declare a mode.
+ */
+export declare function indexNameFor(dirName: string): string;
 export declare function checkMode(latticeDir: string, projectRoot?: string): Promise<CheckError[]>;

package/dist/src/cli/check-mode.js

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { dirname, relative } from 'node:path';
+import { basename, dirname, join, relative } from 'node:path';
 import { listLatticeFiles, parseFrontmatter } from '../lattice.js';
 import { parse } from '../parser.js';
 import { quoteUntrusted } from '../untrusted.js';
@@ -181,9 +181,38 @@ function findImperativeHits(tree, content) {
     }
     return hits;
 }
+/**
+ * The index file a directory is required to carry, e.g. `lat.md` for the root
+ * and `reference.md` for `reference/`. An index is navigation rather than
+ * content, so the `require-mode` gate below never asks one to declare a mode.
+ */
+export function indexNameFor(dirName) {
+    return dirName.endsWith('.md') ? dirName : dirName + '.md';
+}
+/**
+ * Whether the root index turns the mode requirement on.
+ *
+ * Opt-in, and deliberately read from the tree rather than from a flag or an
+ * environment variable: the rule belongs to a documentation set, not to a
+ * machine or a CI job, and a tree that predates the rule has to keep passing.
+ * `lat init` stamps the flag into the root index it scaffolds, so a project
+ * set up after this exists is gated from its first commit while an older one
+ * is untouched until someone adds the line.
+ */
+async function requireModeEnabled(latticeDir) {
+    const indexPath = join(latticeDir, indexNameFor(basename(latticeDir)));
+    try {
+        const content = await readFile(indexPath, 'utf-8');
+        return parseFrontmatter(content).raw['require-mode'] === true;
+    }
+    catch {
+        return false;
+    }
+}
 export async function checkMode(latticeDir, projectRoot = dirname(latticeDir)) {
     const files = await listLatticeFiles(latticeDir);
     const errors = [];
+    const requireMode = await requireModeEnabled(latticeDir);
     for (const file of files) {
         const content = await readFile(file, 'utf-8');
         const relPath = relative(process.cwd(), file);
@@ -238,8 +267,21 @@ export async function checkMode(latticeDir, projectRoot = dirname(latticeDir)) {
             continue;
         }
         const mode = (declared ?? dirMode);
-        if (mode === undefined)
+        if (mode === undefined) {
+            const segments = relFromLattice.split('/');
+            const fileName = segments.pop();
+            const holder = segments.length === 0 ? basename(latticeDir) : segments.at(-1);
+            const isIndex = fileName === indexNameFor(holder);
+            if (requireMode && !isIndex) {
+                errors.push({
+                    file: relPath,
+                    line: 1,
+                    target,
+                    message: 'document declares no Diátaxis mode and is not in a mode directory — move it under lat.md/tutorials/, lat.md/how-to/, lat.md/reference/ or lat.md/explanation/, or declare one under its `lat:` frontmatter.\n    A document that would fail its mode is usually two documents: the lookup half belongs in reference/, the reasoning half in explanation/.\n    (The root index sets require-mode: true. Remove that line to turn this off.)',
+                });
+            }
             continue;
+        }
         const tree = parse(content);
         if (mode === 'how-to') {
             if (!orderedListPresent(tree)) {

package/dist/src/cli/check.js

@@ -6,6 +6,7 @@ import { scanCodeRefs } from '../code-refs.js';
 import { checkMode } from './check-mode.js';
 import { checkStatus } from './check-status.js';
 import { checkFrontmatter } from './check-frontmatter.js';
+import { checkCoverage } from './check-coverage.js';
 import { indexEntryNameFromDest } from './link-scheme.js';
 import { fencedLineMask } from './gen-index.js';
 import { SOURCE_EXTENSIONS, clearSymbolCache } from '../source-parser.js';
@@ -621,6 +622,7 @@ export async function checkAllCommand(ctx, opts = {}) {
     const modeErrors = await checkMode(ctx.latDir, ctx.projectRoot);
     const statusErrors = await checkStatus(ctx.latDir, ctx.projectRoot);
     const fmErrors = await checkFrontmatter(ctx.latDir, ctx.projectRoot);
+    const coverageErrors = await checkCoverage(ctx.latDir, ctx.projectRoot);
     const elapsed = Date.now() - startTime;
     const allErrors = [...md.errors, ...linkErrors, ...code.errors];
     const allFiles = { ...md.files };
@@ -658,12 +660,14 @@ export async function checkAllCommand(ctx, opts = {}) {
     lines.push(...formatCheckErrors(modeErrors, s));
     lines.push(...formatCheckErrors(statusErrors, s));
     lines.push(...formatCheckErrors(fmErrors, s));
+    lines.push(...formatCheckErrors(coverageErrors, s));
     const totalErrors = allErrors.length +
         indexErrors.length +
         sectionErrors.length +
         modeErrors.length +
         statusErrors.length +
-        fmErrors.length;
+        fmErrors.length +
+        coverageErrors.length;
     if (totalErrors > 0) {
         lines.push(formatErrorCount(totalErrors, s));
         return { output: lines.join('\n'), isError: true };

package/dist/src/cli/fork-instructions.d.ts

@@ -0,0 +1,19 @@
+export declare function readForkConventions(): string;
+/**
+ * Replace the fork block in `content`, or append one when absent.
+ *
+ * Returns null when the block is already byte-identical, so the caller can
+ * stay quiet rather than announce a write that did not happen.
+ */
+export declare function spliceForkBlock(content: string, body: string): string | null;
+/** Read the body currently fenced by the fork markers, or null if absent. */
+export declare function extractForkBlock(content: string): string | null;
+/**
+ * Write the fork's conventions into every instruction file and skill directory
+ * the selected agents produced.
+ *
+ * `fileHashes` is upstream's record, threaded through so `writeInitMeta`
+ * persists these entries alongside its own; a stored hash is what lets a later
+ * run tell "the user edited our block" from "the template moved on".
+ */
+export declare function writeForkInstructions(root: string, latDir: string, fileHashes: Record<string, string>, ask: (message: string) => Promise<boolean>): Promise<void>;

package/dist/src/cli/fork-instructions.js

@@ -0,0 +1,183 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { styleText } from 'node:util';
+import { contentHash, readFileHash } from '../init-version.js';
+import { findTemplatesDir } from './templates.js';
+/**
+ * The fork's own instruction channel into a consumer project.
+ *
+ * Upstream teaches a consumer's agent through `templates/AGENTS.md` and
+ * `templates/skill/SKILL.md`. Both are upstream files, and both are the ones
+ * upstream is most likely to rewrite, so every sentence this fork adds to them
+ * is a merge conflict bought on credit. The fork's Diátaxis block cost 13
+ * lines in one and 14 in the other before this module existed.
+ *
+ * Everything here writes into fork-owned paths instead. The entire upstream
+ * footprint is one import and one call in `initCmd`.
+ *
+ * Two shapes, because the destinations behave differently:
+ *
+ * - Always-loaded instruction files (`CLAUDE.md`, `AGENTS.md`,
+ *   `.github/copilot-instructions.md`) already carry upstream's
+ *   `%% lat:begin %%` block, so this appends a *second* block under its own
+ *   `%% lat-fork:begin %%` markers. Upstream's `appendTemplateSection` slices
+ *   between its own markers and leaves anything after them intact, so the two
+ *   blocks do not fight on re-run.
+ * - Skill directories get a separate `lat-md-conventions/SKILL.md`. Upstream
+ *   writes its `lat-md` skill with a whole-file hash comparison, so appending
+ *   to that file would make every later `lat init` report it as
+ *   user-modified and prompt.
+ */
+const FORK_BEGIN = '%% lat-fork:begin %%';
+const FORK_END = '%% lat-fork:end %%';
+/**
+ * Hash-map key for a fork block inside a file upstream also owns. Suffixed so
+ * it can never collide with upstream's entry for the same path — both live in
+ * one flat `file_hashes` record.
+ */
+function forkHashKey(relPath) {
+    return `${relPath}#lat-fork`;
+}
+/** Instruction files that use upstream's marker-append shape. */
+const BLOCK_TARGETS = [
+    'CLAUDE.md',
+    'AGENTS.md',
+    '.github/copilot-instructions.md',
+];
+/**
+ * Skill roots every agent integration installs into. Written to only when the
+ * directory already exists, which is what keeps this list from creating skill
+ * directories for agents the user did not select.
+ */
+const SKILL_ROOTS = [
+    '.claude/skills',
+    '.pi/skills',
+    '.agents/skills',
+    '.codex/skills',
+];
+const SKILL_NAME = 'lat-md-conventions';
+const SKILL_FRONTMATTER = `---
+name: ${SKILL_NAME}
+description: >-
+  Rules lat check enforces in this project: Diátaxis mode placement for every
+  lat.md/ document, mandatory @lat: code refs starting at the application
+  entrypoint, and test specs wired to their tests. Load alongside lat-md
+  whenever creating or editing files under lat.md/.
+---
+
+`;
+export function readForkConventions() {
+    return readFileSync(join(findTemplatesDir(), 'fork', 'conventions.md'), 'utf-8');
+}
+function wrapBlock(body) {
+    return `${FORK_BEGIN}\n${body}${body.endsWith('\n') ? '' : '\n'}${FORK_END}\n`;
+}
+/**
+ * Replace the fork block in `content`, or append one when absent.
+ *
+ * Returns null when the block is already byte-identical, so the caller can
+ * stay quiet rather than announce a write that did not happen.
+ */
+export function spliceForkBlock(content, body) {
+    const wrapped = wrapBlock(body);
+    const begin = content.indexOf(FORK_BEGIN);
+    const end = content.indexOf(FORK_END);
+    if (begin === -1 || end === -1 || end <= begin) {
+        let base = content;
+        if (base.length > 0 && !base.endsWith('\n'))
+            base += '\n';
+        return base + (base.length > 0 ? '\n' : '') + wrapped;
+    }
+    const endWithMarker = end + FORK_END.length;
+    const endWithNl = content[endWithMarker] === '\n' ? endWithMarker + 1 : endWithMarker;
+    const existing = content.slice(begin, endWithNl);
+    if (existing === wrapped)
+        return null;
+    return content.slice(0, begin) + wrapped + content.slice(endWithNl);
+}
+/** Read the body currently fenced by the fork markers, or null if absent. */
+export function extractForkBlock(content) {
+    const begin = content.indexOf(FORK_BEGIN);
+    const end = content.indexOf(FORK_END);
+    if (begin === -1 || end === -1 || end <= begin)
+        return null;
+    return content.slice(begin + FORK_BEGIN.length + 1, end);
+}
+/**
+ * Write the fork's conventions into every instruction file and skill directory
+ * the selected agents produced.
+ *
+ * `fileHashes` is upstream's record, threaded through so `writeInitMeta`
+ * persists these entries alongside its own; a stored hash is what lets a later
+ * run tell "the user edited our block" from "the template moved on".
+ */
+export async function writeForkInstructions(root, latDir, fileHashes, ask) {
+    const body = readForkConventions();
+    const bodyHash = contentHash(body);
+    const written = [];
+    for (const relPath of BLOCK_TARGETS) {
+        const absPath = join(root, relPath);
+        if (!existsSync(absPath))
+            continue;
+        const current = readFileSync(absPath, 'utf-8');
+        const existingBlock = extractForkBlock(current);
+        if (existingBlock !== null) {
+            const existingHash = contentHash(existingBlock);
+            if (existingHash === bodyHash) {
+                fileHashes[forkHashKey(relPath)] = bodyHash;
+                continue;
+            }
+            const storedHash = readFileHash(latDir, forkHashKey(relPath));
+            if (storedHash && existingHash !== storedHash) {
+                console.log(styleText('yellow', `  ${relPath}`) +
+                    ' lat-fork section has been modified.');
+                if (!(await ask('  Replace lat-fork section with latest template?'))) {
+                    console.log(styleText('dim', '  Kept existing section.'));
+                    continue;
+                }
+            }
+        }
+        const updated = spliceForkBlock(current, body);
+        if (updated === null) {
+            fileHashes[forkHashKey(relPath)] = bodyHash;
+            continue;
+        }
+        writeFileSync(absPath, updated);
+        fileHashes[forkHashKey(relPath)] = bodyHash;
+        written.push(relPath);
+    }
+    const skillBody = SKILL_FRONTMATTER + body;
+    const skillHash = contentHash(skillBody);
+    for (const skillRoot of SKILL_ROOTS) {
+        const rootAbs = join(root, skillRoot);
+        if (!existsSync(rootAbs))
+            continue;
+        const relPath = `${skillRoot}/${SKILL_NAME}/SKILL.md`;
+        const absPath = join(root, relPath);
+        if (existsSync(absPath)) {
+            const current = readFileSync(absPath, 'utf-8');
+            if (contentHash(current) === skillHash) {
+                fileHashes[relPath] = skillHash;
+                continue;
+            }
+            const storedHash = readFileHash(latDir, relPath);
+            if (storedHash && contentHash(current) !== storedHash) {
+                console.log(styleText('yellow', `  ${relPath}`) + ' has been modified.');
+                if (!(await ask('  Overwrite with latest lat template?'))) {
+                    console.log(styleText('dim', '  Kept existing file.'));
+                    continue;
+                }
+            }
+        }
+        mkdirSync(join(absPath, '..'), { recursive: true });
+        writeFileSync(absPath, skillBody);
+        fileHashes[relPath] = skillHash;
+        written.push(relPath);
+    }
+    if (written.length > 0) {
+        console.log('');
+        console.log(styleText('green', '  lat.md conventions') +
+            ' written to ' +
+            written.join(', '));
+    }
+}

package/dist/src/cli/fork-scaffold.d.ts

@@ -0,0 +1,16 @@
+/** Prepend the `require-mode` flag to a root index that has no frontmatter. */
+export declare function stampRequireMode(content: string): string;
+/**
+ * Append the four mode directories to the root index.
+ *
+ * Without this a fresh `lat init` leaves `lat check index` reporting four
+ * missing entries, which is a poor first impression of a tool whose whole
+ * pitch is that the check passes.
+ */
+export declare function listModeDirs(content: string): string;
+/**
+ * Scaffold the four mode directories and turn the gate on. Called only on the
+ * run that creates `lat.md/`, so an existing tree is never restructured
+ * underneath its owner.
+ */
+export declare function writeForkScaffold(latDir: string): void;

package/dist/src/cli/fork-scaffold.js

@@ -0,0 +1,129 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { styleText } from 'node:util';
+import { DIATAXIS_MODES, MODE_DIRS, indexNameFor } from './check-mode.js';
+/**
+ * Give a freshly created `lat.md/` the Diátaxis shape, and turn the gate on.
+ *
+ * Upstream's `templates/init/` holds two files and is copied wholesale, so a
+ * new tree is one flat root index. An agent asked to document a codebase then
+ * writes flat files beside it — which is not merely untidy: `checkMode` binds
+ * only inside the four mode directories, so flat placement puts every document
+ * out of reach of every shape rule. A bella-derms session did exactly that and
+ * confirmed afterwards that its largest document produced 64 errors the moment
+ * it was moved into `reference/`.
+ *
+ * Structure is the cheaper half of the fix. Four directories that already
+ * exist, each with a passing index, make placement the path of least
+ * resistance; `require-mode: true` in the root index makes flat placement an
+ * error rather than an option.
+ *
+ * Written from here rather than added to `templates/init/` because the flag
+ * has to land inside `lat.md/lat.md`, which upstream's template owns.
+ */
+/** One-line summary and body for each mode's index, keyed by directory. */
+const MODE_INDEX = {
+    tutorials: {
+        title: 'Tutorials',
+        lead: 'Guided first passes through this system, each ending somewhere the reader can see.',
+    },
+    'how-to': {
+        title: 'How-to',
+        lead: 'Recipes for tasks that recur, written for someone who already knows what they want.',
+    },
+    reference: {
+        title: 'Reference',
+        lead: 'Lookup facts about this system: fields, states, limits, names and defaults.',
+    },
+    explanation: {
+        title: 'Explanation',
+        lead: 'Why this system is shaped the way it is, and what the alternatives cost.',
+    },
+};
+/**
+ * A mode index has to satisfy its own mode. A tutorial index needs ordered
+ * steps and a stated outcome, a how-to index needs ordered steps, and a
+ * reference index must not carry a second paragraph — so each stub is written
+ * to the rule it will be checked against rather than to one house style.
+ */
+function indexBody(dir) {
+    const { title, lead } = MODE_INDEX[dir];
+    const header = `# ${title}\n\n${lead}\n`;
+    if (dir === 'tutorials') {
+        return (header +
+            '\nBy the end of any document here the reader will have run something and seen it work.\n' +
+            '\n1. Pick the tutorial closest to what you are trying to learn.\n' +
+            '2. Follow it top to bottom without skipping.\n' +
+            '3. Come back to `reference/` for the details it left out.\n');
+    }
+    if (dir === 'how-to') {
+        return (header +
+            '\n1. Find the recipe for the task in front of you.\n' +
+            '2. Follow its steps.\n' +
+            '3. If no recipe fits, write one here once the task is done.\n');
+    }
+    if (dir === 'reference') {
+        return header;
+    }
+    return (header +
+        '\nEach document here answers a "why", not a "how". The steps that follow ' +
+        'from a decision belong in `how-to/`, and the facts it fixes belong in ' +
+        '`reference/`.\n');
+}
+/** Prepend the `require-mode` flag to a root index that has no frontmatter. */
+export function stampRequireMode(content) {
+    if (/^---\n/.test(content))
+        return content;
+    return `---\nlat:\n  require-mode: true\n---\n\n${content.replace(/^\n+/, '')}`;
+}
+/**
+ * Append the four mode directories to the root index.
+ *
+ * Without this a fresh `lat init` leaves `lat check index` reporting four
+ * missing entries, which is a poor first impression of a tool whose whole
+ * pitch is that the check passes.
+ */
+export function listModeDirs(content) {
+    const entries = DIATAXIS_MODES.map((mode) => {
+        const dir = MODE_DIRS[mode];
+        const { title, lead } = MODE_INDEX[dir];
+        return `- [${title}](${dir}/${dir}.md) — ${lead}`;
+    }).join('\n');
+    if (content.includes(`(${MODE_DIRS.reference}/`))
+        return content;
+    let base = content;
+    if (!base.endsWith('\n'))
+        base += '\n';
+    return `${base}\nEvery document belongs in exactly one of these.\n\n${entries}\n`;
+}
+/**
+ * Scaffold the four mode directories and turn the gate on. Called only on the
+ * run that creates `lat.md/`, so an existing tree is never restructured
+ * underneath its owner.
+ */
+export function writeForkScaffold(latDir) {
+    const created = [];
+    for (const mode of DIATAXIS_MODES) {
+        const dir = MODE_DIRS[mode];
+        const dirPath = join(latDir, dir);
+        const indexPath = join(dirPath, `${dir}.md`);
+        if (existsSync(indexPath))
+            continue;
+        mkdirSync(dirPath, { recursive: true });
+        writeFileSync(indexPath, indexBody(dir));
+        created.push(`${dir}/`);
+    }
+    const rootIndex = join(latDir, indexNameFor(basename(latDir)));
+    if (existsSync(rootIndex)) {
+        const current = readFileSync(rootIndex, 'utf-8');
+        const stamped = listModeDirs(stampRequireMode(current));
+        if (stamped !== current)
+            writeFileSync(rootIndex, stamped);
+    }
+    if (created.length > 0) {
+        console.log(styleText('green', 'Scaffolded Diátaxis modes') +
+            ' — ' +
+            created.join(' ') +
+            styleText('dim', ' (every document belongs in one of these)'));
+    }
+}

package/dist/src/cli/index.js

@@ -6,8 +6,18 @@ if (!process.argv.includes('--verbose')) {
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { Command } from 'commander';
+import { Command, InvalidArgumentError } from 'commander';
 import { resolveCheckContext, resolveContext } from './context.js';
+function parsePort(value) {
+    if (!/^\d+$/.test(value)) {
+        throw new InvalidArgumentError('port must be an integer from 1 to 65535');
+    }
+    const port = Number(value);
+    if (port < 1 || port > 65_535) {
+        throw new InvalidArgumentError('port must be an integer from 1 to 65535');
+    }
+    return port;
+}
 /** Reserve `-- <directory>` for an explicit check target. */
 function splitCheckTarget(args) {
     let commandIndex = -1;
@@ -90,13 +100,28 @@ program
     const { sectionCommand } = await import('./section.js');
     handleResult(await sectionCommand(ctx, query));
 });
-program
+const ui = program
     .command('ui')
     .description('Open lat.md in a local browser')
-    .action(async () => {
+    .option('--logo-text <text>', 'top-left logo text')
+    .option('--port <number>', 'server port (default: 4242; explicit ports are strict)', parsePort)
+    .action(async (opts) => {
     const ctx = resolveContext(program.opts());
     const { uiCommand } = await import('./ui.js');
-    handleResult(await uiCommand(ctx));
+    handleResult(await uiCommand(ctx, { logoText: opts.logoText, port: opts.port }));
+});
+ui.command('build')
+    .description('Export lat.md as a static website')
+    .argument('[output]', 'output directory relative to the project', 'lat-ui')
+    .option('--base <path>', 'deployment base path', '/')
+    .option('--logo-text <text>', 'top-left logo text')
+    .action(async (output, opts) => {
+    const ctx = resolveContext(program.opts());
+    const { uiBuildCommand } = await import('./ui-build.js');
+    handleResult(await uiBuildCommand(ctx, output, {
+        basePath: opts.base,
+        logoText: opts.logoText ?? ui.opts().logoText,
+    }));
 });
 program
     .command('refs')

package/dist/src/cli/init.js

@@ -15,6 +15,8 @@ import { INIT_VERSION, writeInitMeta, readInitVersion, readFileHash, contentHash
 import { getLocalVersion, fetchLatestVersion } from '../version.js';
 import { selectMenu } from './select-menu.js';
 import { checklistMenu } from './checklist-menu.js';
+import { writeForkInstructions } from './fork-instructions.js';
+import { writeForkScaffold } from './fork-scaffold.js';
 async function confirm(rl, message) {
     while (true) {
         let answer;
@@ -900,6 +902,7 @@ export async function initCmd(targetDir) {
             mkdirSync(latDir, { recursive: true });
             cpSync(templateDir, latDir, { recursive: true });
             console.log(styleText('green', 'Created lat.md/'));
+            writeForkScaffold(latDir);
         }
         // Step 2: Configure fresh/outdated setups, ask interactive users about an
         // available key, and offer to rebuild an index whose backend differs. This
@@ -1004,6 +1007,7 @@ export async function initCmd(targetDir) {
             console.log(styleText('bold', 'Setting up Codex...'));
             await setupCodex(root, latDir, fileHashes, ask, commandStyle);
         }
+        await writeForkInstructions(root, latDir, fileHashes, ask);
         // Record init version and file hashes so `lat check` can detect stale setups
         writeInitMeta(latDir, fileHashes);
         console.log('');

package/dist/src/cli/search.js

@@ -73,10 +73,12 @@ async function resolveMatches(latDir, results, preloadedSections) {
     const allSections = preloadedSections ?? (await loadAllSections(latDir));
     const flat = flattenSections(allSections);
     const byId = new Map(flat.map((s) => [s.id, s]));
-    return results
-        .map((r) => byId.get(r.id))
-        .filter((s) => !!s)
-        .map((s) => ({ section: s, reason: 'semantic match' }));
+    return results.flatMap((result) => {
+        const section = byId.get(result.id);
+        return section
+            ? [{ section, reason: 'semantic match', score: result.score }]
+            : [];
+    });
 }
 /**
  * Run a semantic search across lat.md sections.

package/dist/src/cli/ui-build.d.ts

@@ -0,0 +1,4 @@
+import type { CmdContext, CmdResult } from '../context.js';
+import { type StaticViewBuildOptions } from '../view/static-build.js';
+/** Export the current vault as a serverless, read-only Lat UI. */
+export declare function uiBuildCommand(ctx: CmdContext, output?: string, options?: StaticViewBuildOptions): Promise<CmdResult>;

package/dist/src/cli/ui-build.js

@@ -0,0 +1,13 @@
+import { buildStaticView, } from '../view/static-build.js';
+/** Export the current vault as a serverless, read-only Lat UI. */
+export async function uiBuildCommand(ctx, output = 'lat-ui', options = {}) {
+    try {
+        const result = await buildStaticView(ctx, output, options);
+        return {
+            output: `Built ${result.documents} documents and ${result.sources} source views at ${result.outputDir}`,
+        };
+    }
+    catch (error) {
+        return { output: error.message, isError: true };
+    }
+}