@plebeiantech/lat.md 0.12.3-fork.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yury Selivanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+<p align="center">
+  <img src="templates/logo-dark.svg" alt="lat.md" width="500">
+</p>
+
+<p align="center">
+  <a href="https://github.com/1st1/lat.md/actions/workflows/ci.yml"><img src="https://github.com/1st1/lat.md/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/lat.md"><img src="https://img.shields.io/npm/v/lat.md" alt="npm"></a>
+</p>
+
+<p align="center">A knowledge graph for your codebase, written in markdown.</p>
+
+## The problem
+
+`AGENTS.md` doesn't scale. A single flat file can describe a small project, but as a codebase grows, maintaining one monolithic document becomes impractical. Key design decisions get buried, business logic goes undocumented, and agents hallucinate context they should be able to look up.
+
+## The idea
+
+Compress the knowledge about your program domain into a **graph** — a set of interconnected markdown files that live in a `lat.md/` directory at the root of your project. Sections link to each other with `[[wiki links]]`, markdown files link into the codebase (`[[src/auth.ts#validateToken]]`), source files link back with `// @lat: [[section-id]]` comments, and `lat check` ensures nothing drifts out of sync.
+
+- **Faster coding for agents** — instead of grepping through your codebase, agents search the knowledge graph to discover key design decisions, constraints, and domain context fast and consistently.
+
+- **Faster workflow for humans** — your agents maintain lat files for you. When you review a diff, start with the semantic changes in `lat.md/` to understand *what* changed and *why*. Reviewing code becomes the secondary task.
+
+- **Knowledge retention** — the context and reasoning behind your prompts is usually lost after a session ends. With lat, agents capture that knowledge into the graph as they work, so future sessions start with full context instead of rediscovering it from scratch.
+
+- **Test specs with enforcement** — test cases can be described as sections in `lat.md/` and marked with `require-code-mention: true`. Each spec then must be referenced by a `// @lat:` comment in test code. `lat check` flags any spec without a backlink, so you can review and maintain test coverage from the knowledge graph.
+
+The `lat` CLI gives agents and humans a system to navigate and maintain the graph:
+
+- **`lat init`** — sets up popular coding agents with hooks and instructions to keep lat updated and correct
+- **`lat check`** — enforces referential consistency; agents call it automatically before finishing work
+- **`lat search`** and **`lat section`** — agents use these to understand your prompts and navigate the graph instead of endless `grep` calls
+
+`lat` is a workflow that comes with tools — build pre-commit hooks and GitHub bots, run CI tasks that improve the knowledge graph in the background.
+
+## Install
+
+```bash
+npm install -g lat.md
+```
+
+Then run `lat init` in the repo you want to use lat in.
+
+## How it works
+
+Run `lat init` to scaffold a `lat.md/` directory, then write markdown files describing your architecture, business logic, test specs — whatever matters. Link between sections using `[[file#Section#Subsection]]` syntax. Link to source code symbols with `[[src/auth.ts#validateToken]]`. Annotate source code with `// @lat: [[section-id]]` (or `# @lat: [[section-id]]` in Python) comments to tie implementation back to concepts.
+
+```
+my-project/
+├── lat.md/
+│   ├── architecture.md    # system design, key decisions
+│   ├── auth.md            # authentication & authorization logic
+│   └── tests.md           # test specs (require-code-mention: true)
+├── src/
+│   ├── auth.ts            # // @lat: [[auth#OAuth Flow]]
+│   └── server.ts          # // @lat: [[architecture#Request Pipeline]]
+└── ...
+```
+
+## CLI
+
+```bash
+lat init                        # scaffold a lat.md/ directory
+lat check                       # run full graph and documentation validation
+lat locate "OAuth Flow"         # find sections by name (exact, fuzzy)
+lat section "auth#OAuth Flow"   # show a section with its links and refs
+lat refs "auth#OAuth Flow"      # find what references a section
+lat search "how do we auth?"    # semantic search via embeddings
+lat expand "fix [[OAuth Flow]]" # expand [[refs]] in a prompt for agents
+lat mcp                         # start MCP server for editor integration
+```
+
+## Configuration
+
+Semantic search (`lat search`) works **offline by default** — no API key required. It uses a bundled local embedding model (all-MiniLM-L6-v2, compiled to WebAssembly; no native binaries, no network).
+
+To use higher-quality hosted embeddings instead, provide an OpenAI (`sk-...`) or Vercel AI Gateway (`vck_...`) API key, 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 — power users can set `llm_key` manually. Run `lat config` to print its location.
+
+Switch backends any time with `lat reindex` (`--local` to force the offline model, `--remote` to use your key).
+
+## Development
+
+Development requires Node.js 22, pnpm, and Rust installed through rustup. The
+pnpm setup installs the matching WASM target and build tools project-locally.
+See the [development process](lat.md/dev-process.md) for complete setup and
+contribution guidance.
+
+```bash
+pnpm install
+pnpm buildall
+pnpm test
+```

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

@@ -0,0 +1,12 @@
+import type { CheckError } from './check.js';
+/**
+ * Report frontmatter that parses to nothing useful, or that puts a lat field
+ * somewhere the parser will not look.
+ *
+ * Both failures are quiet by nature, and both fail OPEN. A misplaced or
+ * unparseable `require-code-mention` turns a validation off, and `lat check`
+ * then reports success on a file whose leaf sections are no longer required to
+ * carry `@lat:` coverage. Nothing else in the output says the rule stopped
+ * applying, which is precisely why it has to be said here.
+ */
+export declare function checkFrontmatter(latticeDir: string, projectRoot?: string): Promise<CheckError[]>;

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

@@ -0,0 +1,44 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, relative } from 'node:path';
+import { listLatticeFiles, parseFrontmatter } from '../lattice.js';
+import { toPosix } from '../walk.js';
+/**
+ * Report frontmatter that parses to nothing useful, or that puts a lat field
+ * somewhere the parser will not look.
+ *
+ * Both failures are quiet by nature, and both fail OPEN. A misplaced or
+ * unparseable `require-code-mention` turns a validation off, and `lat check`
+ * then reports success on a file whose leaf sections are no longer required to
+ * carry `@lat:` coverage. Nothing else in the output says the rule stopped
+ * applying, which is precisely why it has to be said here.
+ */
+export async function checkFrontmatter(latticeDir, projectRoot = dirname(latticeDir)) {
+    const files = await listLatticeFiles(latticeDir);
+    const errors = [];
+    for (const file of files) {
+        const content = await readFile(file, 'utf-8');
+        const problems = parseFrontmatter(content).problems;
+        if (!problems)
+            continue;
+        const relPath = relative(process.cwd(), file);
+        const target = toPosix(relative(projectRoot, file)).replace(/\.md$/, '');
+        for (const problem of problems) {
+            if (problem.kind === 'root-level-field') {
+                errors.push({
+                    file: relPath,
+                    line: 1,
+                    target,
+                    message: `frontmatter sets "${problem.field}" at the document root, where it is ignored — nest it under "lat:" instead:\n    ---\n    lat:\n      ${problem.field}: ...\n    ---`,
+                });
+                continue;
+            }
+            errors.push({
+                file: relPath,
+                line: 1,
+                target,
+                message: `frontmatter is not valid YAML (${problem.message}) — every lat field in this document is being ignored, including any that turn a check on`,
+            });
+        }
+    }
+    return errors;
+}

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

@@ -0,0 +1,6 @@
+import type { CheckError } from './check.js';
+export declare const DIATAXIS_MODES: readonly ["tutorial", "how-to", "reference", "explanation"];
+export type DiataxisMode = (typeof DIATAXIS_MODES)[number];
+/** Directory below lat.md/ that holds each mode. */
+export declare const MODE_DIRS: Record<DiataxisMode, string>;
+export declare function checkMode(latticeDir: string, projectRoot?: string): Promise<CheckError[]>;

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

@@ -0,0 +1,303 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, relative } from 'node:path';
+import { listLatticeFiles, parseFrontmatter } from '../lattice.js';
+import { parse } from '../parser.js';
+import { quoteUntrusted } from '../untrusted.js';
+import { toPosix } from '../walk.js';
+export const DIATAXIS_MODES = [
+    'tutorial',
+    'how-to',
+    'reference',
+    'explanation',
+];
+/** Directory below lat.md/ that holds each mode. */
+export const MODE_DIRS = {
+    tutorial: 'tutorials',
+    'how-to': 'how-to',
+    reference: 'reference',
+    explanation: 'explanation',
+};
+/** Reverse lookup: first path segment -> mode. Built once, not per file. */
+const DIR_TO_MODE = Object.fromEntries(DIATAXIS_MODES.map((mode) => [MODE_DIRS[mode], mode]));
+const OUTCOME_RE = /\b(outcome|by the end|you will (build|learn|have|create)|what you (will )?(build|learn|have|create))\b/i;
+/**
+ * Imperative verbs that flag a command inside an explanation document.
+ * Deliberately excludes ambiguous verbs (Use, Go, Make, Type, Enter, Call,
+ * Import, Export) — each reads naturally as a noun or as descriptive prose
+ * at the start of a sentence ("Use cases include...", "Type inference..."),
+ * and including them produced false positives in testing.
+ */
+const IMPERATIVE_VERBS = [
+    'Run',
+    'Install',
+    'Add',
+    'Set',
+    'Open',
+    'Create',
+    'Delete',
+    'Edit',
+    'Copy',
+    'Move',
+    'Click',
+    'Press',
+    'Configure',
+    'Update',
+    'Remove',
+    'Execute',
+    'Choose',
+    'Select',
+    'Replace',
+    'Rename',
+    'Restart',
+    'Deploy',
+];
+const MAX_IMPERATIVE_ERRORS = 10;
+function orderedListPresent(tree) {
+    let found = false;
+    const walk = (nodes) => {
+        for (const node of nodes) {
+            if (node.type === 'list' && node.ordered === true) {
+                found = true;
+                return;
+            }
+            if ('children' in node) {
+                walk(node.children);
+            }
+            if (found)
+                return;
+        }
+    };
+    walk(tree.children);
+    return found;
+}
+function outcomeStated(tree) {
+    for (const node of tree.children) {
+        if (node.type === 'heading' || node.type === 'paragraph') {
+            const text = inlineTextOf(node);
+            if (OUTCOME_RE.test(text))
+                return true;
+        }
+    }
+    return false;
+}
+function inlineTextOf(node) {
+    return node.children
+        .map((c) => {
+        if ('value' in c && typeof c.value === 'string')
+            return c.value;
+        if ('children' in c)
+            return inlineTextOf(c);
+        return '';
+    })
+        .join('');
+}
+/**
+ * Extra top-level paragraphs found under headings, beyond the one
+ * `checkSections` already permits as the leading summary. A paragraph
+ * before the first heading is the document lead, not narrative prose.
+ */
+function extraParagraphs(tree) {
+    const offenders = [];
+    let currentHeading = null;
+    let seenParagraphUnderHeading = false;
+    for (const node of tree.children) {
+        if (node.type === 'heading') {
+            currentHeading = inlineTextOf(node);
+            seenParagraphUnderHeading = false;
+            continue;
+        }
+        if (node.type === 'paragraph') {
+            if (currentHeading === null) {
+                // Document lead paragraph before any heading — allowed.
+                continue;
+            }
+            if (!seenParagraphUnderHeading) {
+                seenParagraphUnderHeading = true;
+            }
+            else {
+                offenders.push({
+                    line: node.position.start.line,
+                    heading: currentHeading,
+                });
+            }
+        }
+    }
+    return offenders;
+}
+/**
+ * Line numbers (1-indexed, inclusive of both ends) that belong to a `code`
+ * or `yaml` (frontmatter) node anywhere in the tree. Walking the parsed tree
+ * — rather than re-scanning raw text with a fence regex — means a fence of
+ * any marker length or an indented code block is recognized correctly, and
+ * frontmatter needs no special case: it simply isn't prose in the tree.
+ */
+function nonProseLines(tree) {
+    const lines = new Set();
+    const markRange = (node) => {
+        if (!node.position)
+            return;
+        for (let line = node.position.start.line; line <= node.position.end.line; line++) {
+            lines.add(line);
+        }
+    };
+    const walk = (nodes) => {
+        for (const node of nodes) {
+            if (node.type === 'code' || node.type === 'yaml') {
+                markRange(node);
+                continue;
+            }
+            if ('children' in node) {
+                walk(node.children);
+            }
+        }
+    };
+    walk(tree.children);
+    return lines;
+}
+function findImperativeHits(tree, content) {
+    const hits = [];
+    const lines = content.split('\n');
+    const skipLines = nonProseLines(tree);
+    for (let i = 0; i < lines.length; i++) {
+        const lineNumber = i + 1;
+        if (skipLines.has(lineNumber))
+            continue;
+        const trimmedStart = lines[i].trimStart();
+        if (trimmedStart.startsWith('#'))
+            continue;
+        let text = trimmedStart;
+        text = text.replace(/^(?:[-*+]\s+|\d+[.)]\s+)/, '');
+        text = text.replace(/^\*\*/, '');
+        for (const verb of IMPERATIVE_VERBS) {
+            if (text.startsWith(verb + ' ')) {
+                hits.push({ line: lineNumber, verb });
+                break;
+            }
+        }
+    }
+    return hits;
+}
+export async function checkMode(latticeDir, projectRoot = dirname(latticeDir)) {
+    const files = await listLatticeFiles(latticeDir);
+    const errors = [];
+    for (const file of files) {
+        const content = await readFile(file, 'utf-8');
+        const relPath = relative(process.cwd(), file);
+        const target = toPosix(relative(projectRoot, file)).replace(/\.md$/, '');
+        const fm = parseFrontmatter(content);
+        const declaredRaw = fm.raw['mode'];
+        // null (bare `mode:` key) is treated as absent; any other non-string is
+        // reported below via declaredNonString.
+        const declared = declaredRaw === null || declaredRaw === undefined
+            ? undefined
+            : typeof declaredRaw === 'string'
+                ? declaredRaw
+                : undefined;
+        const declaredNonString = declaredRaw !== null &&
+            declaredRaw !== undefined &&
+            typeof declaredRaw !== 'string'
+            ? declaredRaw
+            : undefined;
+        const relFromLattice = toPosix(relative(latticeDir, file));
+        const firstSegment = relFromLattice.split('/')[0];
+        const dirMode = firstSegment && firstSegment !== relFromLattice
+            ? DIR_TO_MODE[firstSegment]
+            : undefined;
+        if (declaredNonString !== undefined) {
+            errors.push({
+                file: relPath,
+                line: 1,
+                target,
+                message: `document declares unknown mode ${quoteUntrusted(JSON.stringify(declaredNonString), 40)} — use one of: tutorial, how-to, reference, explanation`,
+            });
+            continue;
+        }
+        if (declared !== undefined &&
+            !DIATAXIS_MODES.includes(declared)) {
+            errors.push({
+                file: relPath,
+                line: 1,
+                target,
+                message: `document declares unknown mode ${quoteUntrusted(declared, 40)} — use one of: tutorial, how-to, reference, explanation`,
+            });
+            continue;
+        }
+        if (declared !== undefined &&
+            dirMode !== undefined &&
+            declared !== dirMode) {
+            errors.push({
+                file: relPath,
+                line: 1,
+                target,
+                message: `document is in lat.md/${firstSegment}/ but declares mode: ${declared} — the mode must match the directory that holds it`,
+            });
+            continue;
+        }
+        const mode = (declared ?? dirMode);
+        if (mode === undefined)
+            continue;
+        const tree = parse(content);
+        if (mode === 'how-to') {
+            if (!orderedListPresent(tree)) {
+                errors.push({
+                    file: relPath,
+                    line: 1,
+                    target,
+                    message: `a how-to must give ordered steps — add a numbered list`,
+                });
+            }
+            continue;
+        }
+        if (mode === 'tutorial') {
+            if (!orderedListPresent(tree)) {
+                errors.push({
+                    file: relPath,
+                    line: 1,
+                    target,
+                    message: `a tutorial must give ordered steps — add a numbered list`,
+                });
+            }
+            if (!outcomeStated(tree)) {
+                errors.push({
+                    file: relPath,
+                    line: 1,
+                    target,
+                    message: `a tutorial must state its outcome — add a heading or sentence saying what the reader will have at the end`,
+                });
+            }
+            continue;
+        }
+        if (mode === 'reference') {
+            for (const offender of extraParagraphs(tree)) {
+                errors.push({
+                    file: relPath,
+                    line: offender.line,
+                    target,
+                    message: `a reference must not contain narrative prose — this is a second paragraph under "${offender.heading}"; use a list, a table, or a code block instead`,
+                });
+            }
+            continue;
+        }
+        if (mode === 'explanation') {
+            const hits = findImperativeHits(tree, content);
+            const capped = hits.slice(0, MAX_IMPERATIVE_ERRORS);
+            for (const hit of capped) {
+                errors.push({
+                    file: relPath,
+                    line: hit.line,
+                    target,
+                    message: `an explanation must not give commands — line starts with the imperative "${hit.verb}"; describe what happens instead, or move this to a how-to`,
+                });
+            }
+            if (hits.length > MAX_IMPERATIVE_ERRORS) {
+                errors.push({
+                    file: relPath,
+                    line: 1,
+                    target,
+                    message: `capped at ${MAX_IMPERATIVE_ERRORS} imperative-command errors for this document — fix these first, then re-run`,
+                });
+            }
+        }
+    }
+    return errors;
+}

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

@@ -0,0 +1,74 @@
+import type { Styler } from '../context.js';
+import type { CheckError } from './check.js';
+/**
+ * Who wrote a document, and whether a person has checked it.
+ *
+ * lat.md states that agents write the graph. Without this field an unmarked
+ * claim written by an agent reaches the model carrying exactly the authority
+ * of one a person read and approved.
+ */
+export declare const DOC_STATUSES: readonly ["human-reviewed", "agent-extracted"];
+export type DocStatus = (typeof DOC_STATUSES)[number];
+export type DocProvenance = {
+    /** Raw `status` value, which may not be one this build understands. */
+    status?: string;
+    /** Raw `reviewed-hash` value, which may not be hex. */
+    reviewedHash?: string;
+};
+/**
+ * Read the provenance fields out of a document's frontmatter.
+ *
+ * Fields live under the top-level `lat:` mapping, so they are read off
+ * `LatFrontmatter.raw` rather than being promoted to named fields. Adding a
+ * named field would mean editing `parseFrontmatter`, and keeping that function
+ * closed to per-feature edits is the whole reason `raw` exists.
+ */
+export declare function readProvenance(content: string): DocProvenance;
+/**
+ * Hash the prose a review actually covered.
+ *
+ * A plain `status` field becomes a lie the moment an agent edits the document:
+ * the field still says a person checked the text, but the text is no longer
+ * the text that person read. Capturing the content at review time turns that
+ * silent failure into a check.
+ *
+ * Frontmatter is excluded deliberately: adding an unrelated frontmatter key
+ * does not change a single claim in the prose, and invalidating a review for
+ * it would train authors to re-stamp the hash without re-reading — which
+ * costs the field its meaning.
+ *
+ * Heading TEXT is excluded for the same reason — re-titling a section changes
+ * no claim in the prose. But a heading LINE is not: adding or removing a
+ * heading changes the document's structure (a new section exists that no one
+ * has reviewed), and that must flip the hash even though no non-heading line
+ * changed. So each heading line is reduced to its `#` marker (which carries
+ * its level and position) rather than dropped outright — retitling a section
+ * leaves the marker alone, but appending or removing a heading changes the
+ * sequence of markers and therefore the hash. (Swapping two headings of the
+ * same level produces the same marker sequence and is not detected — a
+ * narrower version of the blind spot this fix closes.)
+ */
+export declare function hashReviewedBody(content: string): string;
+export type ProvenanceNote = {
+    kind: 'unreviewed' | 'stale' | 'reviewed';
+    text: string;
+};
+/**
+ * The one-line provenance annotation for `lat section` and `lat search`, or
+ * null when the document says nothing about its provenance.
+ *
+ * A document with no `status` produces nothing at all. Most documents in most
+ * repositories have no status, and a line on every one of them would be noise
+ * that readers learn to skip — which would cost the warning its force on the
+ * documents that do carry one.
+ */
+export declare function provenanceNote(content: string): ProvenanceNote | null;
+/** Colourize a note for terminal output. */
+export declare function formatProvenanceNote(note: ProvenanceNote, s: Styler): string;
+/**
+ * Report documents whose recorded review no longer describes their text.
+ *
+ * This is a static validation. It needs no history and no database, and it
+ * catches most of what a temporal graph would answer.
+ */
+export declare function checkStatus(latticeDir: string, projectRoot?: string): Promise<CheckError[]>;