> ## Documentation Index
> Fetch the complete documentation index at: https://llmwiki.atomicstrata.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Source Citations and Provenance Tracking in llmwiki

> llmwiki traces every paragraph and claim back to the source file and line range. Learn how paragraph and claim-level citations work.

When you compile a wiki, you are trusting an LLM to synthesize knowledge from your sources. That trust is only well-placed if you can trace every claim back to where it came from. llmwiki builds provenance tracing into the page format itself: paragraphs carry lightweight citation markers pointing back to the source file that contributed them, and specific claims can pin to exact line ranges within that file. This means you can open any compiled page, see a citation marker, and know precisely which source - and which lines of that source - the content derives from. `llmwiki lint` validates every citation on every run, and `llmwiki eval` measures how thoroughly and accurately your pages are cited.

## Paragraph-Level Citations

The most common citation form is a paragraph-level source marker. At the end of a prose paragraph, llmwiki appends `^[filename.md]` to indicate which source file contributed that paragraph's content:

```markdown theme={null}
Knowledge compilation refers to a family of techniques for pre-processing
a knowledge base into a target language that supports efficient queries. ^[knowledge-compilation.md]

The two-phase compile pipeline separates concept extraction from page
generation so that cross-source merges happen deterministically. ^[architecture-notes.md]
```

The filename inside `^[...]` is relative to the `sources/` directory. You do not include the `sources/` prefix - just the bare filename as it appears in the `sources` frontmatter field.

## Claim-Level Citations

For claims that require tighter verification - specific numbers, precise technical assertions, direct quotations - you can pin a citation to a line range within the source file. llmwiki supports two equivalent syntaxes:

<CodeGroup>
  ```markdown Colon range syntax theme={null}
  The system uses a two-phase compile pipeline. ^[architecture-notes.md:42-58]
  ```

  ```markdown GitHub anchor syntax theme={null}
  The system uses a two-phase compile pipeline. ^[architecture-notes.md#L42-L58]
  ```
</CodeGroup>

Both forms identify the same span: lines 42 through 58 (inclusive) of `architecture-notes.md` in the `sources/` directory. Use whichever form your team prefers - llmwiki's linter and eval harness treat them identically.

<Tip>
  Claim-level citations are tracked by `llmwiki eval` as the `claim_level_citation_rate` metric: the fraction of all citations in the wiki that pin to a specific line range rather than a whole file. Higher rates mean tighter, more verifiable provenance. You can set a minimum threshold in `.llmwiki/eval/thresholds.yaml`.
</Tip>

## How `llmwiki lint` Validates Citations

`llmwiki lint` validates every citation marker in every compiled page. It checks for four categories of problems:

<CardGroup cols={2}>
  <Card title="Missing source file" icon="file-circle-xmark">
    The filename inside `^[...]` does not exist in `sources/`. This happens when a source is deleted after compilation or when the LLM hallucinated a filename. Treated as an **error**.
  </Card>

  <Card title="Malformed citation" icon="triangle-exclamation">
    The citation syntax is not parseable - for example, `^[file.md:abc]` where the range is not a pair of integers. Treated as an **error**.
  </Card>

  <Card title="Impossible range" icon="ban">
    A line range where the start line is `0` (lines are 1-indexed), or where the end line is less than the start line (e.g. `^[file.md:8-3]`). Treated as an **error**.
  </Card>

  <Card title="Out-of-bounds range" icon="arrows-up-to-line">
    A line range that extends past the end of the source file (e.g. citing lines `900-950` in a 200-line file). Treated as a **warning**, since the source may have been truncated on ingest.
  </Card>
</CardGroup>

Citation errors contribute to the health score computed by `llmwiki eval` and are listed individually in lint output. Broken citations also trigger the `provenance-violating` review policy hold mode, so pages with bad citations can be automatically queued for human review rather than written to `wiki/`.

## What Happens During Source Merge

When multiple sources contribute to the same concept slug, llmwiki merges them into a single page. Epistemic metadata is reconciled across all contributing sources:

| Field | Merge rule |
| - | - |
| `confidence` | Minimum across all contributing sources |
| `provenanceState` | Always set to `merged` |
| `contradictedBy` | Deduplicated union of all contributing sources' contradiction lists |

Citation markers in the merged page body continue to point to the specific source file each paragraph came from. A merged page may therefore carry citations to multiple different files in `sources/`:

```markdown theme={null}
The attention mechanism computes a weighted sum over values. ^[attention-paper.md:12-18]

Multi-head attention applies the mechanism h times in parallel. ^[transformer-architecture.md:44-51]
```

## A Full Example Compiled Page

Here is a complete example showing frontmatter and body with both paragraph and claim-level citation markers:

```markdown theme={null}
---
title: Knowledge Compilation
summary: Techniques for converting knowledge representations into forms that support efficient reasoning.
kind: concept
sources:
  - knowledge-compilation.md
  - architecture-notes.md
confidence: 0.82
provenanceState: merged
createdAt: "2026-04-05T12:00:00Z"
updatedAt: "2026-04-05T12:00:00Z"
---

# Knowledge Compilation

Knowledge compilation refers to a family of techniques for pre-processing
a knowledge base into a target language that supports efficient queries. ^[knowledge-compilation.md]

The process runs in two phases: first, all concepts are extracted from changed
sources; then, pages are generated from those extracted concepts. ^[architecture-notes.md:42-58]

Splitting the phases eliminates order-dependence and allows concepts shared
across multiple sources to be merged into a single page. ^[architecture-notes.md#L59-L74]

Related concepts: [[Compilation Pipeline]], [[Incremental Compilation]], [[Wikilinks]]
```

## Citation Coverage and Eval

`llmwiki eval` measures citation quality across the entire wiki as part of its health score:

* **Citation coverage** - the fraction of prose paragraphs in `wiki/concepts/` that carry at least one `^[...]` marker. Low coverage means paragraphs are floating without provenance.
* **Citation precision** - the fraction of `^[...]` markers that point to a source file that actually exists in `sources/`. A precision below 100% indicates hallucinated or deleted source references.
* **Citation support** (`--suite full`) - samples up to N `(claim, source span)` pairs and asks a judge model to score each 0–2 (unsupported → fully supported). Results are cached in `.llmwiki/eval/citation-cache.jsonl` so re-runs only judge new pairs.
* **Claim-level citation rate** - the fraction of all citations that use a line-range form rather than a bare filename.

You can set minimum thresholds for all of these in `.llmwiki/eval/thresholds.yaml` to gate CI pipelines on citation quality.

For details on running lint and eval, see [llmwiki lint and eval](/cli/lint-eval).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.