@plebeiantech/lat.md 0.12.3-fork.2 → 0.12.3-fork.21

package/dist/src/cli/hook.js

@@ -1,17 +1,22 @@
 import { execSync } from 'node:child_process';
-import { dirname, extname } from 'node:path';
-import { findLatticeDir, loadAllSections, findSections, } from '../lattice.js';
-import { plainStyler } from '../context.js';
-import { expandPrompt } from './expand.js';
+import { lstatSync, readFileSync } from 'node:fs';
+import { dirname, extname, join } from 'node:path';
+import { findLatticeDir } from '@plebeiantech/lat.md-core/project-discovery';
+import { findSections } from '@plebeiantech/lat.md-core/lattice-model';
+import { plainStyler, } from '@plebeiantech/lat.md-core/context';
 import { runSearch } from './search.js';
-import { getSection, formatSectionOutput } from './section.js';
-import { checkMd, checkCodeRefs, checkIndex, checkSections } from './check.js';
-import { checkMode } from './check-mode.js';
-import { SOURCE_EXTENSIONS } from '../source-parser.js';
+import { DEFAULT_SEARCH_LIMIT } from '../search/search.js';
+import { getSection, formatSectionOutput, } from '@plebeiantech/lat.md-core/cli/section';
+import { checkMd, checkCodeRefs, checkIndex, checkSections, } from '@plebeiantech/lat.md-core/cli/check';
+import { CheckRunContext } from '@plebeiantech/lat.md-core/cli/check-context';
+import { isSourceFileExtension } from '@plebeiantech/lat.md-core/source-formats';
+import { commandProjectAnalysis } from '@plebeiantech/lat.md-core/project-analysis';
+import { checkMode } from '@plebeiantech/lat.md-core/cli/check-mode';
 import { federateTags, taggedDocsForFiles } from '../knowledge/index.js';
 import { loadSessionMarkers, saveSessionMarkers, } from '../knowledge/session.js';
 import { computeCommentReminder, } from './comment-reminder.js';
 import { handlePreToolUse } from './comment-guard.js';
+import { handleAntigravityHook } from '../fork/antigravity-hook.js';
 function outputPromptSubmit(context) {
     process.stdout.write(JSON.stringify({
         hookSpecificOutput: {
@@ -53,9 +58,6 @@ async function readStdin() {
     }
     return Buffer.concat(chunks).toString('utf-8');
 }
-function hasWikiLinks(text) {
-    return /\[\[[^\]]+\]\]/.test(text);
-}
 function makeHookCtx(latDir) {
     return {
         latDir,
@@ -64,15 +66,15 @@ function makeHookCtx(latDir) {
         mode: 'cli',
     };
 }
-async function searchAndExpand(ctx, userPrompt, preloadedSections) {
+async function searchContextForPrompt(ctx, userPrompt) {
     let result;
     try {
         // Read-only: search an existing index but never build/update it here. A fresh
         // repo's first prompt must not trigger a full local embed pass — that's what
         // `lat search` / `lat reindex` are for. Returns no matches until then.
-        result = await runSearch(ctx.latDir, userPrompt, 5, undefined, {
+        result = await runSearch(ctx.latDir, userPrompt, DEFAULT_SEARCH_LIMIT, undefined, {
             buildIndex: false,
-            preloadedSections,
+            project: await commandProjectAnalysis(ctx),
         });
     }
     catch {
@@ -109,32 +111,16 @@ async function handleUserPromptSubmit() {
         // If we can't parse stdin, still emit the reminder
     }
     const parts = [];
-    parts.push("Before starting work, run `lat search` with one or more queries describing the user's intent.", 'ALWAYS do this, even when the task seems straightforward — search results may reveal critical design details, protocols, or constraints.', 'Use `lat section` to read the full content of relevant matches.', 'Do not read files, write code, or run commands until you have searched.', '', 'Remember: `lat.md/` must stay in sync with meaningful codebase state. If you change behavior, architecture, tests, or planned work, update the relevant current-state sections and run `lat check` before finishing. Do not use `lat.md/` as a journal/changelog or add notes for insignificant details.');
+    parts.push("Before starting work, run `lat search` with one or more queries describing the user's intent.", 'ALWAYS do this, even when the task seems straightforward — search results may reveal critical design details, protocols, or constraints.', 'Use `lat section` to read the full content of relevant matches.', 'Do not read files, write code, or run commands until you have searched.', '', 'Remember: `lat.md/` must stay in sync with meaningful codebase state. If you change implemented behavior, architecture, or tests, update the relevant current-state sections and run `lat check` before finishing. Plans may be drafted in `lat.md/` alongside implementation, with the intent that by commit time they describe what was implemented. Otherwise, keep proposals, hypothetical designs, and future work outside `lat.md/` unless the user explicitly requests them there. Do not use `lat.md/` as a journal/changelog or add notes for insignificant details.');
     const latDir = findLatticeDir();
     if (latDir && userPrompt) {
         const ctx = makeHookCtx(latDir);
-        // Loaded once and threaded through expansion, search, and federation
-        // below — each of those otherwise walks and parses the whole tree itself.
-        const allSections = await loadAllSections(latDir);
-        // If the user prompt contains [[refs]], resolve them inline
-        if (hasWikiLinks(userPrompt)) {
-            try {
-                const expanded = await expandPrompt(ctx, userPrompt, allSections);
-                if (expanded) {
-                    parts.push('', 'Expanded user prompt with resolved [[refs]]:', expanded);
-                }
-                else {
-                    parts.push('', 'NOTE: The user prompt contains [[refs]] but they could not be resolved. Ask the user to correct them.');
-                }
-            }
-            catch {
-                parts.push('', 'NOTE: The user prompt contains [[refs]] but resolution failed. Run `lat expand` on the prompt text manually.');
-            }
-        }
+        // Search and federation share the analysis memoised on `ctx`.
+        const { allSections } = await commandProjectAnalysis(ctx);
         // Search for relevant sections and include their full content
         let searchFilePaths = [];
         try {
-            const searchContext = await searchAndExpand(ctx, userPrompt, allSections);
+            const searchContext = await searchContextForPrompt(ctx, userPrompt);
             searchFilePaths = searchContext.filePaths;
             if (searchContext.text) {
                 parts.push('', searchContext.text);
@@ -161,7 +147,7 @@ async function handleUserPromptSubmit() {
                     }
                 }
             }
-            // Reuses what searchAndExpand already matched. Searching again here
+            // Reuses what searchContextForPrompt already matched. Searching again here
             // would double the cost of every prompt, and an unusable index makes
             // runSearch throw — which abandoned the [[ref]] paths collected above,
             // even though resolving those never touches the index at all.
@@ -252,55 +238,116 @@ const DIFF_THRESHOLD = 5;
 const LATMD_RATIO = 0.05;
 /** If lat.md/ changes exceed this many lines, skip the ratio check entirely. */
 const LATMD_UPPER_THRESHOLD = 50;
-/** Run `git diff --numstat` and return { codeLines, latMdLines }. */
-function analyzeDiff(projectRoot) {
-    let output;
+function diffFileKind(file) {
+    if (file.startsWith('lat.md/'))
+        return 'latMd';
+    if (isSourceFileExtension(extname(file)))
+        return 'code';
+    return null;
+}
+/** Count a regular text file's lines as additions, matching Git numstat. */
+function countUntrackedFileLines(projectRoot, file) {
     try {
-        output = execSync('git diff HEAD --numstat', {
-            cwd: projectRoot,
-            encoding: 'utf-8',
-            timeout: 2000,
-        });
+        const path = join(projectRoot, file);
+        if (!lstatSync(path).isFile())
+            return 0;
+        const text = readFileSync(path, 'utf-8');
+        if (text.length === 0)
+            return 0;
+        return text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
     }
     catch {
-        return { codeLines: 0, latMdLines: 0 };
+        return 0;
     }
+}
+/**
+ * Measure code vs `lat.md/` churn since HEAD, in lines. Combines tracked
+ * changes (`git diff HEAD --numstat`) with untracked files
+ * (`git ls-files --others --exclude-standard -z`). Counting untracked files is
+ * what makes a freshly scaffolded, never-committed `lat.md/` register as
+ * updated — otherwise its edits are invisible to `git diff HEAD` and the sync
+ * reminder fires on every turn until `lat.md/` is committed (issue #61).
+ * Both scans are scoped and made relative to `projectRoot`, so a Lat project
+ * nested in a larger worktree neither misses its own `lat.md/` paths nor counts
+ * changes from sibling projects.
+ * Outside a Git worktree both scans contribute zero churn by design: Git is
+ * optional, so the hook still validates the project but skips the sync ratio.
+ */
+export function analyzeDiff(projectRoot) {
     let codeLines = 0;
     let latMdLines = 0;
-    // Each line: "added\tremoved\tfile" (e.g. "42\t11\tsrc/cli/hook.ts")
-    for (const line of output.split('\n')) {
-        const parts = line.split('\t');
-        if (parts.length < 3)
-            continue;
-        const added = parseInt(parts[0], 10) || 0;
-        const removed = parseInt(parts[1], 10) || 0;
-        const file = parts[2];
-        const changed = added + removed;
-        if (file.startsWith('lat.md/')) {
+    const tally = (kind, changed) => {
+        if (kind === 'latMd') {
             latMdLines += changed;
         }
-        else if (SOURCE_EXTENSIONS.has(extname(file))) {
+        else {
             codeLines += changed;
         }
+    };
+    // Tracked changes vs HEAD. Throws when there is no HEAD yet (a repo with no
+    // commits) or no repo at all; the untracked scan below still runs.
+    try {
+        const output = execSync('git diff HEAD --numstat --relative -- .', {
+            cwd: projectRoot,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        // Each line: "added\tremoved\tfile" (e.g. "42\t11\tsrc/cli/hook.ts")
+        for (const line of output.split('\n')) {
+            const parts = line.split('\t');
+            if (parts.length < 3)
+                continue;
+            const added = parseInt(parts[0], 10) || 0;
+            const removed = parseInt(parts[1], 10) || 0;
+            const kind = diffFileKind(parts[2]);
+            if (kind)
+                tally(kind, added + removed);
+        }
+    }
+    catch {
+        // Not a git repo, or no HEAD — fall through to the untracked scan.
+    }
+    // NUL-delimited output preserves spaces, non-ASCII names, and newlines.
+    // Classify paths before reading so unrelated untracked files are never read.
+    try {
+        const output = execSync('git ls-files --others --exclude-standard -z -- .', {
+            cwd: projectRoot,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        for (const file of output.split('\0')) {
+            if (!file)
+                continue;
+            const kind = diffFileKind(file);
+            if (!kind)
+                continue;
+            tally(kind, countUntrackedFileLines(projectRoot, file));
+        }
+    }
+    catch {
+        // Not a Git repo — diff-based sync analysis is intentionally disabled.
     }
     return { codeLines, latMdLines };
 }
-async function getStopStatus(latDir) {
-    const md = await checkMd(latDir);
-    const code = await checkCodeRefs(latDir);
-    const indexErrors = await checkIndex(latDir);
-    const sectionErrors = await checkSections(latDir);
+export async function getStopStatus(latDir) {
+    const projectRoot = dirname(latDir);
+    const run = new CheckRunContext(latDir, projectRoot);
     // Must stay in step with `checkAllCommand` in check.ts. A check counted
     // there but not here lets the Stop hook call a failing tree clean, which
     // silently disables the very enforcement the check was added for.
-    const modeErrors = await checkMode(latDir);
+    const [md, code, indexErrors, sectionErrors, modeErrors] = await Promise.all([
+        checkMd(latDir, projectRoot, run),
+        checkCodeRefs(latDir, projectRoot, run),
+        checkIndex(latDir, run),
+        checkSections(latDir, projectRoot, run),
+        checkMode(latDir, projectRoot),
+    ]);
     const totalErrors = md.errors.length +
         code.errors.length +
         indexErrors.length +
         sectionErrors.length +
         modeErrors.length;
     const checkFailed = totalErrors > 0;
-    const projectRoot = dirname(latDir);
     const { codeLines, latMdLines } = analyzeDiff(projectRoot);
     let needsSync = false;
     if (codeLines >= DIFF_THRESHOLD && latMdLines < LATMD_UPPER_THRESHOLD) {
@@ -315,7 +362,7 @@ async function getStopStatus(latDir) {
         latMdLines,
     };
 }
-function formatStopReason({ checkFailed, totalErrors, needsSync, codeLines, latMdLines, }) {
+export function formatStopReason({ checkFailed, totalErrors, needsSync, codeLines, latMdLines, }) {
     if (!checkFailed && !needsSync)
         return null;
     const parts = [];
@@ -425,8 +472,12 @@ export async function hookCmd(agent, event) {
                     console.error(`Unknown hook event for cursor: ${event}. Supported: stop, postToolUse`);
                     process.exit(1);
             }
+        case 'antigravity':
+        case 'gemini':
+            await handleAntigravityHook(event);
+            return;
         default:
-            console.error(`Unknown agent: ${agent}. Supported: claude, codex, cursor`);
+            console.error(`Unknown agent: ${agent}. Supported: claude, codex, cursor, antigravity, gemini`);
             process.exit(1);
     }
 }

package/dist/src/cli/index.js

@@ -1,15 +1,39 @@
 #!/usr/bin/env node
-// Suppress deprecation warnings from transitive dependencies unless --verbose
-if (!process.argv.includes('--verbose')) {
-    process.noDeprecation = true;
+import { Command, InvalidArgumentError } from 'commander';
+import { handleResult, packageVersion, } from '@plebeiantech/lat.md-core/cli';
+import { resolveContext } from '@plebeiantech/lat.md-core/cli/context';
+import { DEFAULT_SEARCH_LIMIT, DEFAULT_MIN_SIMILARITY, } from '../search/search.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;
+}
+function parseUiServerBuildTarget(value) {
+    if (value !== 'node' && value !== 'vercel') {
+        throw new InvalidArgumentError('target must be node or vercel');
+    }
+    return value;
+}
+function configureUiRun(command) {
+    return command
+        .option('--logo-text <text>', 'top-left logo text')
+        .option('--no-git', 'disable Git working-tree integration')
+        .option('--port <number>', 'server port (default: 4242; explicit ports are strict)', parsePort);
+}
+function parseSimilarityThreshold(value) {
+    const threshold = Number(value);
+    if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1) {
+        throw new InvalidArgumentError('min-similarity must be a number from 0 to 1');
+    }
+    return threshold;
 }
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { Command } from 'commander';
-import { resolveCheckContext, resolveContext } from './context.js';
-/** Reserve `-- <directory>` for an explicit check target. */
-function splitCheckTarget(args) {
+import { resolveCheckContext } from '@plebeiantech/lat.md-core/cli/context';
+function splitCheckTarget(args, name) {
     let commandIndex = -1;
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
@@ -32,7 +56,7 @@ function splitCheckTarget(args) {
         return { args };
     const targets = args.slice(separatorIndex + 1);
     if (targets.length !== 1 || targets[0] === '') {
-        console.error('error: `lat check --` expects exactly one directory after `--`');
+        console.error(`error: \`${name} check --\` expects exactly one directory after \`--\``);
         process.exit(1);
     }
     return {
@@ -40,45 +64,27 @@ function splitCheckTarget(args) {
         target: targets[0],
     };
 }
-const checkTargetArgs = splitCheckTarget(process.argv.slice(2));
-function findPackageJson() {
-    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;
-    }
-}
-function handleResult(result) {
-    if (result.isError) {
-        console.error(result.output);
-        process.exit(1);
-    }
-    if (result.output)
-        console.log(result.output);
-}
-const version = findPackageJson();
+const checkTargetArgs = splitCheckTarget(process.argv.slice(2), 'lat');
 const program = new Command();
 program
     .name('lat')
+    .version(packageVersion(import.meta.url))
     .description('Anchor source code to high-level concepts defined in markdown')
-    .version(version)
     .option('--dir <path>', 'project root to look for lat.md in (default: cwd)')
     .option('--no-color', 'disable color output')
     .option('--verbose', 'show deprecation warnings and extra diagnostics');
+if (checkTargetArgs.args.includes('--verbose'))
+    process.noDeprecation = false;
+else
+    process.noDeprecation = true;
+const args = checkTargetArgs.args;
 program
     .command('locate')
-    .description('Find sections by id')
-    .argument('<query>', 'section id to search for')
+    .description('Find section(s) by name or text')
+    .argument('<query>', 'name or text to search for')
     .action(async (query) => {
     const ctx = resolveContext(program.opts());
-    const { locateCommand } = await import('./locate.js');
+    const { locateCommand } = await import('@plebeiantech/lat.md-core/cli/locate');
     handleResult(await locateCommand(ctx, query));
 });
 program
@@ -87,16 +93,64 @@ program
     .argument('<query>', 'section id to look up')
     .action(async (query) => {
     const ctx = resolveContext(program.opts());
-    const { sectionCommand } = await import('./section.js');
+    const { sectionCommand } = await import('@plebeiantech/lat.md-core/cli/section');
     handleResult(await sectionCommand(ctx, query));
 });
 program
-    .command('ui')
-    .description('Open lat.md in a local browser')
-    .action(async () => {
+    .command('paths')
+    .description('Show configuration, cache, and temporary file locations')
+    .option('--config', 'show only the user configuration file path')
+    .action(async (options) => {
+    const { pathsCommand } = await import('@plebeiantech/lat.md-core/cli/paths');
+    console.log(pathsCommand({ ...program.opts(), ...options, search: true }));
+});
+async function runUi(opts) {
     const ctx = resolveContext(program.opts());
     const { uiCommand } = await import('./ui.js');
-    handleResult(await uiCommand(ctx));
+    handleResult(await uiCommand(ctx, {
+        git: opts.git,
+        logoText: opts.logoText,
+        port: opts.port,
+    }));
+}
+const ui = configureUiRun(program.command('ui').description('Run or build the Lat UI')).action(runUi);
+configureUiRun(ui.command('run').description('Run the local Lat UI server')).action(async (opts) => {
+    await runUi(opts);
+});
+const uiBuild = ui.command('build').description('Build a deployable Lat UI');
+uiBuild
+    .command('static')
+    .description('Build a fully static, read-only Lat UI')
+    .argument('[output]', 'output directory relative to the project (default: .lat-build/static)', '.lat-build/static')
+    .option('--base <path>', 'deployment base path', '/')
+    .option('--force', 'replace an existing output 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,
+        force: opts.force,
+        logoText: opts.logoText ?? ui.opts().logoText,
+    }));
+});
+uiBuild
+    .command('server')
+    .description('Build a static Lat UI with a portable search server')
+    .argument('[output]', 'output directory (default: .lat-build/server for node, .vercel/output for vercel)')
+    .option('--base <path>', 'deployment base path', '/')
+    .option('--force', 'replace an existing output path')
+    .option('--logo-text <text>', 'top-left logo text')
+    .option('--target <target>', 'deployment target: node or vercel', parseUiServerBuildTarget, 'node')
+    .action(async (output, opts) => {
+    const ctx = resolveContext(program.opts());
+    const { uiBuildServerCommand } = await import('./ui-build-server.js');
+    handleResult(await uiBuildServerCommand(ctx, output, {
+        basePath: opts.base,
+        force: opts.force,
+        logoText: opts.logoText ?? ui.opts().logoText,
+        target: opts.target,
+    }));
 });
 program
     .command('refs')
@@ -110,18 +164,56 @@ program
         process.exit(1);
     }
     const ctx = resolveContext(program.opts());
-    const { refsCommand } = await import('./refs.js');
+    const { refsCommand } = await import('@plebeiantech/lat.md-core/cli/refs');
     handleResult(await refsCommand(ctx, query, scope));
 });
+const external = program
+    .command('external')
+    .description('Manage pinned external source repositories');
+external
+    .command('add')
+    .argument('[handle]', 'stable external source handle')
+    .argument('[repo]', 'canonical HTTPS Git repository')
+    .option('--commit <commit-or-ref>', 'commit, branch, or tag to pin')
+    .option('--prefix <path>', 'repository path prefix')
+    .option('--default-file-extension <extension>', 'extension for external paths that omit one')
+    .option('--strategy <strategy>', 'retrieval strategy: fetch or checkout')
+    .option('--fetch-url <template>', 'raw-file URL template')
+    .action(async (handle, repo, opts) => {
+    const ctx = resolveContext(program.opts());
+    const { externalAddCommand } = await import('@plebeiantech/lat.md-core/cli/external');
+    handleResult(await externalAddCommand(ctx, handle, repo, opts));
+});
+external
+    .command('show')
+    .argument('<source>', 'handle or exact external target')
+    .option('--json', 'emit structured JSON')
+    .action(async (source, opts) => {
+    const ctx = resolveContext(program.opts());
+    const { externalShowCommand } = await import('@plebeiantech/lat.md-core/cli/external');
+    handleResult(await externalShowCommand(ctx, source, !!opts.json));
+});
+external
+    .command('list')
+    .option('--json', 'emit structured JSON')
+    .action(async (opts) => {
+    const ctx = resolveContext(program.opts());
+    const { externalListCommand } = await import('@plebeiantech/lat.md-core/cli/external');
+    handleResult(await externalListCommand(ctx, !!opts.json));
+});
 const check = program
     .command('check')
     .usage('[subcommand] [-- <directory>]')
     .description('Validate markdown, links, code references, and structure')
     .option('--fix', 'generate/update directory index files from frontmatter')
+    .option('--profile', 'show detailed validation timing')
     .action(async (opts) => {
     const ctx = resolveCheckContext(program.opts(), checkTargetArgs.target);
-    const { checkAllCommand } = await import('./check.js');
-    handleResult(await checkAllCommand(ctx, { fix: opts.fix }));
+    const { checkAllCommand } = await import('@plebeiantech/lat.md-core/cli/check');
+    handleResult(await checkAllCommand(ctx, {
+        fix: opts.fix,
+        profile: !!opts.profile,
+    }));
 });
 check
     .command('md')
@@ -129,7 +221,7 @@ check
     .description('Validate wiki links in markdown files')
     .action(async () => {
     const ctx = resolveCheckContext(program.opts(), checkTargetArgs.target);
-    const { checkMdCommand } = await import('./check.js');
+    const { checkMdCommand } = await import('@plebeiantech/lat.md-core/cli/check');
     handleResult(await checkMdCommand(ctx));
 });
 check
@@ -138,7 +230,7 @@ check
     .description('Validate relative markdown links')
     .action(async () => {
     const ctx = resolveCheckContext(program.opts(), checkTargetArgs.target);
-    const { checkLinksCommand } = await import('./check.js');
+    const { checkLinksCommand } = await import('@plebeiantech/lat.md-core/cli/check');
     handleResult(await checkLinksCommand(ctx));
 });
 check
@@ -147,7 +239,7 @@ check
     .description('Validate @lat code references and coverage')
     .action(async () => {
     const ctx = resolveCheckContext(program.opts(), checkTargetArgs.target);
-    const { checkCodeRefsCommand } = await import('./check.js');
+    const { checkCodeRefsCommand } = await import('@plebeiantech/lat.md-core/cli/check');
     handleResult(await checkCodeRefsCommand(ctx));
 });
 check
@@ -162,7 +254,7 @@ check
     // read it off `check.opts()` instead.
     .action(async () => {
     const ctx = resolveCheckContext(program.opts(), checkTargetArgs.target);
-    const { checkIndexCommand } = await import('./check.js');
+    const { checkIndexCommand } = await import('@plebeiantech/lat.md-core/cli/check');
     handleResult(await checkIndexCommand(ctx, { fix: check.opts().fix }));
 });
 check
@@ -171,7 +263,7 @@ check
     .description('Validate section leading paragraphs')
     .action(async () => {
     const ctx = resolveCheckContext(program.opts(), checkTargetArgs.target);
-    const { checkSectionsCommand } = await import('./check.js');
+    const { checkSectionsCommand } = await import('@plebeiantech/lat.md-core/cli/check');
     handleResult(await checkSectionsCommand(ctx));
 });
 check
@@ -180,7 +272,7 @@ check
     .description('Validate Diátaxis modes and document shape')
     .action(async () => {
     const ctx = resolveCheckContext(program.opts(), checkTargetArgs.target);
-    const { checkModeCommand } = await import('./check.js');
+    const { checkModeCommand } = await import('@plebeiantech/lat.md-core/cli/check');
     handleResult(await checkModeCommand(ctx));
 });
 check
@@ -189,7 +281,7 @@ check
     .description('Validate provenance status and detect stale reviews')
     .action(async () => {
     const ctx = resolveCheckContext(program.opts(), checkTargetArgs.target);
-    const { checkStatusCommand } = await import('./check.js');
+    const { checkStatusCommand } = await import('@plebeiantech/lat.md-core/cli/check');
     handleResult(await checkStatusCommand(ctx));
 });
 async function runExpand(text, opts) {
@@ -205,7 +297,7 @@ async function runExpand(text, opts) {
         process.exit(1);
     }
     const ctx = resolveContext(program.opts());
-    const { expandCommand } = await import('./expand.js');
+    const { expandCommand } = await import('@plebeiantech/lat.md-core/cli/expand');
     const result = await expandCommand(ctx, text);
     if (result.isError) {
         console.error(result.output);
@@ -231,14 +323,26 @@ program
 });
 program
     .command('search')
-    .description('Semantic search across lat.md sections')
+    .description('Hybrid search across lat.md sections')
     .argument('[query]', 'search query in plain English')
-    .option('--limit <n>', 'max results', '5')
+    .option('--limit <n>', `max results (default: ${DEFAULT_SEARCH_LIMIT})`, String(DEFAULT_SEARCH_LIMIT))
+    .option('--preview <variant>', 'preview passage, intro, or both', (value) => {
+    if (!['passage', 'intro', 'both'].includes(value))
+        throw new InvalidArgumentError('preview must be passage, intro, or both');
+    return value;
+}, 'passage')
+    .option('--debug', 'show retrieval scores and candidate diagnostics')
+    .option('--min-similarity <score>', `minimum cosine similarity score (default: ${DEFAULT_MIN_SIMILARITY})`, parseSimilarityThreshold)
     .action(async (query, opts) => {
     const ctx = resolveContext(program.opts());
     const { searchCommand, cliProgress } = await import('./search.js');
     const progress = cliProgress(ctx.styler);
-    const result = await searchCommand(ctx, query, { limit: parseInt(opts.limit) }, progress);
+    const result = await searchCommand(ctx, query, {
+        limit: parseInt(opts.limit),
+        debug: opts.debug,
+        minSimilarity: opts.minSimilarity,
+        preview: opts.preview,
+    }, progress);
     handleResult(result);
 });
 program
@@ -285,13 +389,11 @@ program
     await startMcpServer();
 });
 program
-    .command('config')
-    .description('Show configuration file path')
+    .command('config', { hidden: true })
+    .description('Alias for paths --config')
     .action(async () => {
-    const { getConfigPath } = await import('../config.js');
-    const configPath = getConfigPath();
-    const exists = existsSync(configPath);
-    console.log(`Config file: ${configPath}${exists ? '' : ' (not found)'}`);
+    const { pathsCommand } = await import('@plebeiantech/lat.md-core/cli/paths');
+    console.log(pathsCommand({ config: true }));
 });
 program
     .command('graph')

package/dist/src/cli/init-preferences.d.ts

@@ -0,0 +1,4 @@
+/** Read machine-local checklist defaults without inferring installed agents. */
+export declare function readInitAgents(latDir: string): string[];
+/** Update just the confirmed selection, preserving other YAML and comments. */
+export declare function writeInitAgents(latDir: string, agents: string[]): void;