@plebeiantech/lat.md 0.12.3-fork.13 → 0.12.3-fork.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plebeiantech/lat.md",
-  "version": "0.12.3-fork.13",
+  "version": "0.12.3-fork.14",
   "description": "A knowledge graph for your codebase, written in markdown",
   "type": "module",
   "license": "MIT",
@@ -24,49 +24,87 @@
   },
   "files": [
     "dist/src",
-    "templates"
+    "templates",
+    "plugins"
   ],
   "devDependencies": {
+    "@codemirror/commands": "^6.11.0",
+    "@codemirror/lang-markdown": "^6.5.2",
+    "@codemirror/language": "^6.12.4",
+    "@codemirror/merge": "^6.12.2",
+    "@codemirror/state": "^6.7.1",
+    "@codemirror/view": "^6.43.9",
+    "@lezer/highlight": "^1.2.3",
+    "@types/geojson": "^7946.0.16",
+    "@types/express": "^5.0.6",
+    "@types/hast": "^3.0.5",
     "@types/mdast": "^4.0.4",
     "@types/node": "^25.3.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "@types/three": "^0.185.4",
+    "@types/topojson-client": "^3.1.5",
     "@vitejs/plugin-react": "^5.0.0",
     "graphology": "^0.26.0",
     "highlight.js": "^11.12.0",
+    "jsdom": "^30.0.1",
+    "katex": "^0.18.4",
+    "lowlight": "^3.3.0",
+    "maplibre-gl": "^5.24.0",
     "mdast-util-from-markdown": "^2.0.3",
+    "mermaid": "^11.17.2",
     "micromark-util-types": "^2.0.2",
     "prettier": "^3.8.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
+    "rehype-stringify": "^10.0.1",
     "sigma": "^3.0.3",
+    "three": "^0.185.1",
+    "topojson-client": "^3.1.0",
     "tsx": "^4.21.0",
     "typescript": "^5.7.0",
     "vite": "^7.0.0",
     "vitest": "^3.0.0"
   },
   "dependencies": {
+    "@asciidoctor/core": "4.0.6",
     "@folder/xdg": "^4.0.1",
     "@libsql/client": "^0.17.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "@repomix/tree-sitter-wasms": "^0.1.16",
+    "@repomix/tree-sitter-wasms": "^0.1.17",
     "commander": "^14.0.3",
+    "diff": "^8.0.4",
     "github-slugger": "^2.0.0",
     "ignore-walk": "^8.0.0",
+    "mdast-util-gfm-autolink-literal": "^2.0.1",
+    "mdast-util-gfm-footnote": "^2.1.0",
+    "mdast-util-gfm-strikethrough": "^2.0.0",
+    "mdast-util-gfm-table": "^2.0.0",
+    "mdast-util-gfm-task-list-item": "^2.0.0",
     "mdast-util-to-markdown": "^2.1.0",
+    "micromark-extension-gfm-autolink-literal": "^2.1.0",
+    "micromark-extension-gfm-footnote": "^2.1.0",
+    "micromark-extension-gfm-strikethrough": "^2.1.0",
+    "micromark-extension-gfm-table": "^2.1.1",
+    "micromark-extension-gfm-task-list-item": "^2.1.0",
+    "rehype-katex": "^7.0.1",
+    "rehype-raw": "^7.0.0",
     "rehype-sanitize": "^6.0.0",
     "rehype-slug": "^6.0.0",
-    "rehype-stringify": "^10.0.1",
+    "remark-emoji": "^5.0.2",
     "remark-frontmatter": "^5.0.0",
+    "remark-math": "^6.0.0",
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",
     "remark-stringify": "^11.0.0",
+    "rst-compiler": "0.5.9",
     "unified": "^11.0.0",
     "unist-util-visit": "^5.0.0",
     "web-tree-sitter": "^0.26.6",
     "yaml": "^2.8.2",
     "zod": "^4.3.6",
     "@lat.md/embed": "0.2.0",
+    "@lat.md/server": "0.1.0",
     "@lat.md/embed-minilm-fp16": "0.1.0"
   },
   "scripts": {
@@ -76,12 +114,12 @@
     "setup:rust": "pnpm --filter @lat.md/embed setup:rust",
     "build:wasm": "pnpm --filter @lat.md/embed build:wasm",
     "build:weights": "pnpm --filter @lat.md/embed-minilm-fp16 build:weights",
-    "build:packages": "pnpm --filter @lat.md/embed build && pnpm --filter @lat.md/embed-minilm-fp16 build",
+    "build:packages": "pnpm --filter @lat.md/server build && pnpm --filter @lat.md/embed build && pnpm --filter @lat.md/embed-minilm-fp16 build",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit && tsc --noEmit -p view/tsconfig.json",
-    "format": "prettier --write \"src/**/*.ts\" \"view/**/*.{ts,tsx,css,html}\"",
-    "format:check": "prettier --check \"src/**/*.ts\" \"view/**/*.{ts,tsx,css,html}\"",
+    "typecheck": "pnpm --filter @lat.md/server build && tsc --noEmit && tsc --noEmit -p view/tsconfig.json",
+    "format": "prettier --write \"src/**/*.ts\" \"packages/server/src/**/*.ts\" \"view/**/*.{ts,tsx,css,html}\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"packages/server/src/**/*.ts\" \"view/**/*.{ts,tsx,css,html}\"",
     "cook-test-rag": "tsx scripts/cook-test-rag.ts"
   }
 }

package/plugins/lat-md/README.md

@@ -0,0 +1,61 @@
+# Antigravity & Gemini CLI Plugin for lat.md
+
+This plugin integrates [lat.md](https://github.com/PlebeianTech/lat.md) with Google Antigravity and Gemini CLI. It grounds the agent in your codebase knowledge graph, prevents multi-line rationale comments in source code, maintains directory indexes, and blocks finishing work on check failures.
+
+## Features
+
+- **PreInvocation Hook**: Automatically expands wiki links (`[[section]]`) in user prompts, retrieves relevant sections using semantic search, and reminds the agent to maintain the knowledge graph.
+- **PreToolUse Hook**: Intercepts file edits (`replace_file_content` and `write_to_file`) and blocks multi-line rationale comments, prompting the agent to document the reasoning in `lat.md/` with a `@lat:` pointer instead.
+- **PostToolUse Hook**: Runs index synchronization after file modifications.
+- **Stop Hook**: Enforces `lat check` (including Diátaxis mode validation) before the agent completes its work, refusing stop if errors remain.
+- **Bundled Skills**: Provides `lat-md` (syntax & structure authoring guide) and `lat-md-conventions` (fork conventions & rules).
+- **Rules**: Injects core `lat.md` workflow directives via `rules/AGENTS.md`.
+
+## Installation
+
+### Option 1: Via `lat init` (Zero Clone, Recommended)
+
+You do not need to clone the repository to use lat.md with Antigravity. Install the CLI and initialize your repository directly:
+
+```bash
+npm install -g @plebeiantech/lat.md
+# or: mise use -g npm:@plebeiantech/lat.md@latest
+
+lat init
+```
+
+Select **Antigravity / Gemini** from the agent checklist menu. This automatically writes `.agents/hooks.json`, `GEMINI.md`, and `.agents/skills/`.
+
+### Option 2: Global User Plugin (Without Cloning)
+
+To install the plugin bundle globally across all repositories without cloning:
+
+```bash
+mkdir -p ~/.gemini/config/plugins/lat-md && \
+curl -sL https://github.com/PlebeianTech/lat.md/archive/refs/heads/main.tar.gz | \
+  tar -xz -C ~/.gemini/config/plugins/lat-md --strip-components=2 lat.md-main/plugins/lat-md
+```
+
+### Option 3: Workspace Plugin (Without Cloning)
+
+To install the plugin bundle into a specific repository without cloning:
+
+```bash
+mkdir -p .agents/plugins/lat-md && \
+curl -sL https://github.com/PlebeianTech/lat.md/archive/refs/heads/main.tar.gz | \
+  tar -xz -C .agents/plugins/lat-md --strip-components=2 lat.md-main/plugins/lat-md
+```
+
+## Requirements
+
+The plugin requires the `@plebeiantech/lat.md` CLI on your `PATH`:
+
+```bash
+npm install -g @plebeiantech/lat.md
+```
+
+Or using [mise](https://mise.jdx.dev/):
+
+```bash
+mise use -g npm:@plebeiantech/lat.md@latest
+```

package/plugins/lat-md/hooks.json

@@ -0,0 +1,38 @@
+{
+  "lat-md": {
+    "PreInvocation": [
+      {
+        "type": "command",
+        "command": "lat hook antigravity PreInvocation"
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "replace_file_content|write_to_file",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "lat hook antigravity PreToolUse"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "replace_file_content|write_to_file",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "lat hook antigravity PostToolUse"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "type": "command",
+        "command": "lat hook antigravity Stop"
+      }
+    ]
+  }
+}

package/plugins/lat-md/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "lat-md",
+  "version": "0.12.3",
+  "description": "Grounds an agent in a project's lat.md/ knowledge graph deterministically: resolves [[refs]] and federates knowledge into prompts, blocks multi-line rationale comments before they reach source, regenerates directory indexes after edits, and blocks Stop on a failing lat check — including Diataxis mode validation.",
+  "author": {
+    "name": "PlebeianTech"
+  },
+  "keywords": ["documentation", "diataxis", "lat.md", "knowledge-graph"]
+}

package/plugins/lat-md/rules/AGENTS.md

@@ -0,0 +1,118 @@
+# Before starting work
+
+- Run `lat search` to find sections relevant to your task. Read them to understand the design intent before writing code.
+- Run `lat expand` on user prompts to expand any `[[refs]]` — this resolves section names to file locations and provides context.
+
+# Post-task checklist (REQUIRED — do not skip)
+
+After EVERY task, before responding to the user:
+
+- [ ] Update `lat.md/` if you added or changed meaningful functionality, architecture, tests, behavior, or planned work. Keep it a focused snapshot of current/planned state, not a journal/changelog.
+- [ ] Run `lat check` — all validations must pass
+- [ ] Do not skip these steps. Do not consider your task done until both are complete.
+
+---
+
+# What is lat.md?
+
+This project uses [lat.md](https://www.npmjs.com/package/lat.md) to maintain a structured knowledge graph of its architecture, design decisions, and test specs in the `lat.md/` directory. It is a set of cross-linked markdown files that describe **what** this project does and **why** — the domain concepts, key design decisions, business logic, and test specifications. Use it to ground your work in the actual architecture rather than guessing. Do not treat `lat.md/` as a journal or changelog; it should be a focused snapshot of current or planned state, and should not grow just to note insignificant details.
+
+# Commands
+
+```bash
+lat locate "Section Name"      # find a section by name (exact, fuzzy)
+lat refs "file#Section"        # find what references a section
+lat search "natural language"  # semantic search across all sections
+lat expand "user prompt text"  # expand [[refs]] to resolved locations
+lat check                      # run full graph and documentation validation
+```
+
+Run `lat --help` when in doubt about available commands or options.
+
+If `lat search` fails because no API key is configured, explain to the user that semantic search requires a key provided via `LAT_LLM_KEY` (direct value), `LAT_LLM_KEY_FILE` (path to key file), or `LAT_LLM_KEY_HELPER` (command that prints the key). Supported key prefixes: `sk-...` (OpenAI) or `vck_...` (Vercel). If the user doesn't want to set it up, use `lat locate` for direct lookups instead.
+
+# Syntax primer
+
+- **Section ids**: `lat.md/path/to/file#Heading#SubHeading` — full form uses project-root-relative path (e.g. `lat.md/tests/search#RAG Replay Tests`). Short form uses bare file name when unique (e.g. `search#RAG Replay Tests`, `cli#search#Indexing`).
+- **Wiki links**: `[[target]]` or `[[target|alias]]` — cross-references between sections. Can also reference source code: `[[src/foo.ts#myFunction]]`.
+- **Source code links**: Wiki links in `lat.md/` files can reference functions, classes, constants, and methods in TypeScript/JavaScript/Python/Rust/Go/C files. Use the full path: `[[src/config.ts#getConfigDir]]`, `[[src/server.ts#App#listen]]` (class method), `[[lib/utils.py#parse_args]]`, `[[src/lib.rs#Greeter#greet]]` (Rust impl method), `[[src/app.go#Greeter#Greet]]` (Go method), `[[src/app.h#Greeter]]` (C struct). `lat check` validates these exist.
+- **Code refs**: `// @lat: [[section-id]]` (JS/TS/Rust/Go/C) or `# @lat: [[section-id]]` (Python) — ties source code to concepts
+
+# Test specs
+
+Key tests can be described as sections in `lat.md/` files (e.g. `tests.md`). Add frontmatter to require that every leaf section is referenced by a `// @lat:` or `# @lat:` comment in test code:
+
+```markdown
+---
+lat:
+  require-code-mention: true
+---
+# Tests
+
+Authentication and authorization test specifications.
+
+## User login
+
+Verify credential validation and error handling for the login endpoint.
+
+### Rejects expired tokens
+Tokens past their expiry timestamp are rejected with 401, even if otherwise valid.
+
+### Handles missing password
+Login request without a password field returns 400 with a descriptive error.
+```
+
+Every section MUST have a description — at least one sentence explaining what the test verifies and why. Empty sections with just a heading are not acceptable. (This is a specific case of the general leading paragraph rule below.)
+
+Each test in code should reference its spec with exactly one comment placed next to the relevant test — not at the top of the file:
+
+```python
+# @lat: [[tests#User login#Rejects expired tokens]]
+def test_rejects_expired_tokens():
+    ...
+
+# @lat: [[tests#User login#Handles missing password]]
+def test_handles_missing_password():
+    ...
+```
+
+Do not duplicate refs. One `@lat:` comment per spec section, placed at the test that covers it. `lat check` will flag any spec section not covered by a code reference, and any code reference pointing to a nonexistent section.
+
+# Section structure
+
+Every section in `lat.md/` **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 serves as the section's overview and is used in search results, command output, and RAG context — keeping it concise guarantees the section's essence is always captured.
+
+```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
+
+Details about this child topic.
+```
+
+The second example is invalid because `Bad Section` has no leading paragraph. `lat check` validates this rule and reports errors for missing or overly long leading paragraphs.
+
+# Diátaxis modes
+
+Documents under `lat.md/tutorials/`, `lat.md/how-to/`, `lat.md/reference/`, and `lat.md/explanation/` are checked against their Diátaxis mode. Declare it explicitly with nested frontmatter, or rely on the directory:
+
+```markdown
+---
+lat:
+  mode: reference
+---
+```
+
+If a document is in one of the four mode directories, the declared mode must match that directory. Each mode enforces one shape rule: tutorials need an ordered list of steps and a stated outcome; how-to guides need an ordered list of steps; reference docs must not contain narrative prose (no second paragraph under a heading); explanations must not give imperative commands. Run `lat check mode` to validate.

package/plugins/lat-md/skills/lat-md/SKILL.md

@@ -0,0 +1,178 @@
+---
+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.
+
+Project-specific lat documentation belongs in `lat.md/`. Do not modify this generated skill or a generated `AGENTS.md` to record project guidance: both are owned by lat tooling and may be replaced by a later `lat init`.
+
+## 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.
+
+Treat `lat.md/` as a focused snapshot of the current state of affairs or planned features. Do not use it as a journal or changelog, and do not grow it just to record insignificant implementation details.
+
+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)
+- Journal/changelog entries for each change
+- Temporary notes or TODOs
+- Insignificant implementation details that do not change the current-state model
+
+## 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 relative markdown links point to existing files
+- Full and collapsed reference-style links have definitions
+- 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
+- Every `lat.md/` directory has an accurate index