LLM wiki operations

# 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](../../foundations/AUTHORSHIP.md) prevents named
system authorship from being blurred into ownership of user Domains or generated content.

## The four layers

```text
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:

```bash
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:

| Flag | Use |
|---|---|
| `--read` | append a bounded excerpt of the top page: only the sections that score against the question |
| `--lines N` | the excerpt's line budget (4–400, default 40); the tail states how much was withheld |
| `--width N` | wrap route prose to an explicit column count (40–200) |

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:

```bash
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:

```bash
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:

```bash
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.

Raw Markdown source