# Provenance

Which raw source backs which page, and the generated provenance index that records it.

<!-- wikitool:toc -->
## Contents

- [`sources coverage`](#sources-coverage)
- [`sources trace`](#sources-trace)
- [`sources rebuild-index`](#sources-rebuild-index)
<!-- /wikitool:toc -->

<!-- wikitool:reference-commands -->
## `sources coverage`

List raw files with no source page, broken `raw_files:` references, and legacy directory/URL-only source pages.

**Synopsis**

- `wikitool sources coverage [--json]`

**Options**

```text
  --json      Print raw findings as JSON
  -h, --help  Show this message and exit.
```

**Examples**

```bash
tools/wikitool sources coverage
tools/wikitool sources coverage --json
```

**Behaviour**

- Lists raw files with no source page, broken `raw_files:` references, and legacy directory/URL-only source pages.
- `--json` prints the same lists as JSON.
- Never fails; read-only and safe to retry freely.

**Properties**

- Changes files: no
- Idempotent: yes
- Atomic: Read-only
- Counts toward the session call budget: yes
- Can reach the network: no

**Exit codes**

- `0` - success

**See also**

- `wikitool sources trace` - follows one file or page
- `wiki-ingest` skill - turns an uncovered raw file into a source page

## `sources trace`

Trace provenance in either direction: raw file, or page.

**Synopsis**

- `wikitool sources trace --raw <path> | --page "<Title>"`

**Options**

```text
  --raw <str>   Raw file path to trace forward from
  --page <str>  Wiki page title to trace backward from
  -h, --help    Show this message and exit.
```

**Examples**

```bash
tools/wikitool sources trace --page "Docker"
tools/wikitool sources trace --raw "raw/articles/llm-wiki.md"
```

**Behaviour**

- `--raw <path>`: raw file -> the source page(s) covering it -> the pages citing those.
- `--page "<Title>"`: page -> its sources -> their raw files.
- Read-only.

**Properties**

- Changes files: no
- Idempotent: yes
- Atomic: Read-only
- Counts toward the session call budget: yes
- Can reach the network: no

**Exit codes**

- `0` - success
- `1` - Neither or both of `--raw`/`--page` given, or `--page` names an unknown page
- `1` - `--raw` names a file no source page covers - reported as a plain finding plus exit 1, not the usual `ERROR`-prefixed rejection

**See also**

- `wikitool sources coverage` - every uncovered raw file at once
- `wikitool xref link-source` - links a source page to what it mentions

## `sources rebuild-index`

Regenerate the `kb/provenance.md` reverse index.

**Synopsis**

- `wikitool sources rebuild-index [--dry-run]`

**Options**

```text
  --dry-run   Print the result instead of writing kb/provenance.md
  -h, --help  Show this message and exit.
```

**Examples**

```bash
tools/wikitool sources rebuild-index
tools/wikitool sources rebuild-index --dry-run
```

**Behaviour**

- Regenerates the `kb/provenance.md` reverse index (raw file -> source page -> citing pages) from scratch.
- `--dry-run` prints the result instead of writing `kb/provenance.md`.

**Properties**

- Changes files: yes
- Idempotent: yes
- Atomic: Yes - the single provenance file is regenerated from scratch
- Counts toward the session call budget: yes
- Can reach the network: no

**Exit codes**

- `0` - success
- `1` - An I/O error while writing `kb/provenance.md` (rare)

**See also**

- `wikitool index rebuild` - the page catalog, rebuilt alongside
- `instructions/publish-cycle.md` - where a write session runs this
<!-- /wikitool:reference-commands -->