tools: command records, Provenance group - examples, exit lines per cause (#142)

Files changed:
- CHANGES.md
- VERSION
- tools/CONTRACT.md
- tools/chemenu/commands/provenance_cmd.py

tools/CONTRACT.md

@@ -1242,13 +1242,25 @@ List raw files with no source page, broken `raw_files:` references, and legacy d
 - budget: counted
 - network: no
 
+**EXAMPLES**
+
+- `tools/wikitool sources coverage`
+- `tools/wikitool sources coverage --json`
+
 **EXIT STATUS**
 
 - 0    success
 
 **NOTES**
 
-List raw files with no source page, broken `raw_files:` references, and legacy directory/URL-only source pages. Never fails. Safe to retry freely.
+- 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.
+
+**SEE ALSO**
+
+- `wikitool sources trace` - follows one file or page
+- `wiki-ingest` skill - turns an uncovered raw file into a source page
 
 #### `sources trace`
 
@@ -1266,18 +1278,32 @@ Trace provenance in either direction: raw file, or page.
 - budget: counted
 - network: no
 
+**EXAMPLES**
+
+- `tools/wikitool sources trace --page "Docker"`
+- `tools/wikitool sources trace --raw "raw/articles/llm-wiki.md"`
+
 **EXIT STATUS**
 
 - 0    success
-- 1    Neither or both of `--raw`/`--page` given, `--raw` names a file no source page covers (reported as a plain finding plus exit 1, not the usual `ERROR`-prefixed rejection), or `--page` names an unknown page
+- 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
 
 **ON FAILURE**
 
-- Neither or both of `--raw`/`--page` given, `--raw` names a file no source page covers (reported as a plain finding plus exit 1, not the usual `ERROR`-prefixed rejection), or `--page` names an unknown page -> Fix the argument and retry
+- Neither or both of `--raw`/`--page` given, or `--page` names an unknown page -> Fix the argument and retry
+- `--raw` names a file no source page covers - reported as a plain finding plus exit 1, not the usual `ERROR`-prefixed rejection -> Nothing to retry: the file is uncovered. Ingest it, or check the path
 
 **NOTES**
 
-Trace provenance in either direction: raw file -> source page(s) -> citing pages, or page -> its sources -> their raw files
+- `--raw <path>`: raw file -> the source page(s) covering it -> the pages citing those.
+- `--page "<Title>"`: page -> its sources -> their raw files.
+- Read-only.
+
+**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`
 
@@ -1295,18 +1321,33 @@ Regenerate the `kb/provenance.md` reverse index.
 - budget: counted
 - network: no
 
+**EXAMPLES**
+
+- `tools/wikitool sources rebuild-index`
+- `tools/wikitool sources rebuild-index --dry-run`
+
 **EXIT STATUS**
 
 - 0    success
-- 1    Rare I/O error only
+- 1    An I/O error while writing `kb/provenance.md` (rare)
 
 **ON FAILURE**
 
-- Rare I/O error only -> Safe to retry freely
+- An I/O error while writing `kb/provenance.md` (rare) -> Safe to retry freely
+
+**NEVER**
+
+- Never hand-edit `kb/provenance.md` - re-run this command instead.
 
 **NOTES**
 
-Regenerate the `kb/provenance.md` reverse index (raw file -> source page -> citing pages)
+- 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`.
+
+**SEE ALSO**
+
+- `wikitool index rebuild` - the page catalog, rebuilt alongside
+- `instructions/publish-cycle.md` - where a write session runs this
 
 ### Raw material and uploads