llmdoc / docs / concepts

Core concepts

The useful question is not “How much context can the model hold?” but “What context is sufficient for this task?”

Context Floor

The Context Floor is the richness of context an agent needs to solve the current problem. Tool calls, token footprint, and the density of key information all shape the time it takes to reach that floor.

llmdoc raises information density before broad source exploration. It does not replace source code: once it narrows the working set, native tools verify live details such as implementation text, line numbers, tests, and Git state.

Design model: a semantic routing graph

llmdoc is not a compressed copy of the repository. It is the smallest connected graph of durable engineering meaning that lets an agent find the right owner, understand the decisions that constrain a task, and then continue into authoritative source.

• Decisions over observations: documents preserve rationale, boundaries, invariants, contracts, failure semantics, and risky workflows; source, tests, schemas, and manifests retain live facts.
• Ownership over layout: knowledge follows stable responsibility and review boundaries, not package or directory shape.
• Progressive disclosure: the map, routing metadata, selected bodies, and source form successively deeper layers.
• Review coupling: code.paths maps a change to the documents whose claims may need review, rather than manufacturing a file-coverage score.

Progressive reading

The retrieval surface reveals knowledge in layers: map or metadata first, then search or source ownership, then selected bodies. A caller may stop at any layer.

tree / index  →  search / context  →  show

Three gates

Retrieval Gate

Before broad discovery—and again when crossing into a new subsystem—choose the one CLI entry point that matches the intent.

Reflection Gate

User corrections, verification failures, and major rework can become privacy-safe temporary candidates. Transcripts and incidental mistakes do not.

Stable Knowledge Gate

A candidate enters tracked knowledge only when it is durable, changes future choices, has a clear owner, and is expensive to recover from a canonical source.

Document model

V3 uses pure Markdown in .mdx documents with YAML front matter. A path is the document ID. The tree has root singleton documents and one level of topic folders; topics do not need index.mdx.

llmdoc/
├── architecture.mdx
├── api-client/
│   └── retry-policy.mdx
└── meta.json

From domain to topic to document

A domain is an analysis boundary: one stable responsibility, authority, invariant set, failure model, and change vocabulary. A topic is its persistent retrieval neighborhood under llmdoc/. A document is the canonical owner of one coherent question, contract, invariant cluster, or workflow.

Package boundaries are only evidence. Split a topic when ownership, failure semantics, or common queries are independently stable; join code from different packages when it implements one contract. Reserve root documents for genuinely cross-topic knowledge.

Use architecture for boundaries, flows, rationale, and invariants; guide for repeatable workflows with verification and recovery; and reference for stable lookup contracts and decision tables.

Two gates, not one

The Stable Knowledge Gate controls what prose deserves to persist. A separate Routing Gate checks whether natural concept queries and representative decision-bearing files reach the correct owner. Concise prose does not excuse a missing route, and mapping a file does not require narrating it.

validate checks structure. Context Floor acceptance additionally probes natural-language search, individual entry and leaf files with context --files, unrelated siblings against broad globs, and mandatory prerequisite relations. Every first-class subsystem must be documented, intentionally reconstructable, or reported as a blocking gap.

Validity is Git-based

llmdoc/meta.json tracks validated Git revisions. Dirty worktree state is an additional signal, never a fabricated revision. A delta hit creates a review obligation; it does not automatically require a prose change.