LLM wiki operations

Meridians treats maintained knowledge as a compiled, compounding artifact rather than a flat collection of documents or a cache of chat answers. The implementation adapts the LLM-wiki pattern to a software repository where authority is plural: code owns runtime behavior; Meridians' creator and architectural author Jason Yu holds its constitutional authorship; humans own their decisions and authored canon; immutable sources own what they originally said; and maintained pages synthesize the understanding between them. The authorship and provenance contract prevents named system authorship from being blurred into ownership of user Domains or generated content.

The four layers

code, tests, canonical record     runtime truth
knowledge-base/sources/           immutable imported evidence and founder material
knowledge-base/knowledge + specs  maintained semantic synthesis
knowledge-base/generated/         disposable catalogs, maps, and measured projections

knowledge-base/knowledge-schema.json is the policy surface: it declares catalog roots, accepted source and operation kinds, stop words, defaults, and ordered page rules. The scripts provide mechanism—compile, retrieve, preserve, validate—and do not contain a competing list of Meridians authorities or content types. Authority and status are returned to the reader but never secretly boost retrieval relevance. The compiled knowledge-catalog.json gives each maintained page a title, bounded summary, use-when route, authority, status, headings, links, code anchors, and search terms. It is a routing artifact, never a replacement for the page or its sources.

Query: retrieve before broad reading

Run:

npm run knowledge:query -- "How does World branch lineage work?"
npm run knowledge:query -- "How does World branch lineage work?" --paths
npm run knowledge:query -- "How does World branch lineage work?" --read --lines 60
npm run knowledge:benchmark

Read the highest relevant hub or owning leaf, normally no more than two or three results. For technical and behavioral claims, inspect the listed code anchors and implementation before answering or editing. Use --paths when a script or agent needs a minimal newline-delimited handoff, --anchors when it needs the implementation files instead of the prose, and --json when it needs scores and routing explanations. Limits must be explicit integers from 1 to 50. Use the cumulative corpus only for portability or a genuinely whole-system question; it is not the normal hydration path.

Reading inside the harness viewport

Agent output is shaped for the surface that reads it, because a transcript pane is a narrower and more expensive medium than a developer terminal:

Without --width, wrapping follows the terminal columns, then MERIDIANS_VIEWPORT_WIDTH, then COLUMNS, then a 96-column default, clamped to 48–120. Set MERIDIANS_VIEWPORT_WIDTH when a harness reports no usable terminal size.

An excerpt is a bounded read, never a substitute for the page. Excerpt body lines are emitted verbatim and prefixed with a path:Lstart-Lend range so a quoted table, fence, or diagram survives as a citation; only route prose is wrapped. When the excerpt withholds sections, open the page.

Route backwards from changed code

Rule 8 asks which owning doc must move with a behavior change. The catalog's code anchors answer it:

npm run knowledge:owners
npm run knowledge:owners -- src/lib/server/record/write.ts --json
npm run knowledge:query -- --for src/lib/core/reducer/actions.ts

With no paths, knowledge:owners uses the files this branch changed. It separates pages that anchor a changed path exactly from those anchoring its directory, and lists changed files no maintained page claims at all. Neither result is an instruction to write: an unclaimed file may need no prose, and a claimed page is only a candidate until its text is read against the change.

knowledge:benchmark runs representative coding and product questions against checked expected routes. Treat its top-k hit rate and reciprocal rank as regression signals, not objectives: add a case when a real agent question exposes a routing miss, then improve the page contract or general ranking rule instead of special-casing the wording.

Routine queries remain read-only and unlogged. When an answer contains a durable synthesis that should survive the conversation, update the existing owning page, cite the source or code basis, and record a synthesis operation. Do not archive ordinary answers or create pages merely because a query occurred.

Ingest: preserve before synthesizing

Run:

npm run knowledge:ingest -- --source /absolute/path/to/note.md --kind founder

The command preserves the original bytes and hash, writes provenance, records the ingest, and suggests maintained pages that may own the material. It deliberately does not edit those pages. The compiling agent must read the source, compare it with the suggested owners and any code authority, surface contradictions, then make the smallest coherent synthesis update.

One source may update several pages when each page owns a distinct consequence. Repeating the same summary across pages is not synthesis. Prefer an ownership link over duplicated prose, and never let a compiled page cite another compiled page as the sole evidence for a factual claim when the raw source or code is available.

Lint: deterministic failures, reviewed semantic findings

Run:

npm run knowledge:lint

The deterministic lint checks that the schema and compiled catalog are structurally valid, the catalog matches maintained pages, summaries are usable, every immutable source has an adjacent manifest, hashes still match, paths remain contained, and every operation follows the configured vocabulary. Existing knowledge quality and staleness reports continue to own navigation shape and code/prose drift.

Contradictions and unsupported claims require judgment. An agent may report suspected conflicts with both passages and their authorities, but must not auto-rewrite a human contract, authored canon, or factual claim merely to make the wiki sound consistent.

Performance contract

The catalog exists to reduce broad reads and repeated reconstruction. It uses deterministic lexical ranking because that is fast, inspectable, local, and sufficient for the measured questions today—not because lexical retrieval is constitutionally preferred. Improvements should be evaluated on real repository questions using answer correctness, completeness, citation validity, pages opened, tool turns, and context tokens. Do not add embeddings, a vector database, or an autonomous background writer until those measurements show the deterministic catalog and lexical retrieval are insufficient.

The retrieval mechanism lives in scripts/knowledge/wiki-core.mjs (compilation and ranking), scripts/knowledge/wiki-view.mjs (viewport sizing, wrapping, line budgets, section excerpts), scripts/knowledge/wiki-query.mjs, and scripts/knowledge/wiki-owners.mjs. Presentation stays pure and separate from the filesystem so both directions of routing are testable.

For a whole-system orientation rather than a specific question, npm run gen:knowledge-atlas compiles the catalog into corpus, concept-co-occurrence, cross-branch-link, authority, and status lenses. The atlas replaces neither the semantic tree nor query retrieval: a word or branch can be frequent because it is infrastructure, verbose, or broadly referenced. Use the atlas to decide where to look; use an owning source and implementation evidence to decide what is true.