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/chemenu/commands/provenance_cmd.py

@@ -60,9 +60,21 @@ def _normalize_raw_path(raw: str) -> str:
         atomic="Read-only",
         budget=cli_contract.Budget.COUNTED,
     ),
-    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.",
+    notes=(
+        "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.",
+    ),
     failures=(),
+    examples=(
+        "tools/wikitool sources coverage",
+        "tools/wikitool sources coverage --json",
+    ),
+    see_also=(
+        "`wikitool sources trace` - follows one file or page",
+        "`wiki-ingest` skill - turns an uncovered raw file into a source page",
+    ),
 ))
 def coverage(json_out: bool = typer.Option(False, "--json", help="Print raw findings as JSON")):
     """Report raw files with no source page, broken raw_files: references, and
@@ -99,15 +111,30 @@ def coverage(json_out: bool = typer.Option(False, "--json", help="Print raw find
         atomic="Read-only",
         budget=cli_contract.Budget.COUNTED,
     ),
-    notes="Trace provenance in either direction: raw file -> source page(s) -> citing pages, or "
-    "page -> its sources -> their raw files",
-    failures=(cli_contract.Failure(
-        label="",
-        cause="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",
-        reaction="Fix the argument and retry",
-    ),),
+    notes=(
+        "`--raw <path>`: raw file -> the source page(s) covering it -> the pages citing those.",
+        "`--page \"<Title>\"`: page -> its sources -> their raw files.",
+        "Read-only.",
+    ),
+    failures=(
+        cli_contract.Failure(
+            cause="Neither or both of `--raw`/`--page` given, or `--page` names an unknown page",
+            reaction="Fix the argument and retry",
+        ),
+        cli_contract.Failure(
+            cause="`--raw` names a file no source page covers - reported as a plain finding "
+            "plus exit 1, not the usual `ERROR`-prefixed rejection",
+            reaction="Nothing to retry: the file is uncovered. Ingest it, or check the path",
+        ),
+    ),
+    examples=(
+        'tools/wikitool sources trace --page "Docker"',
+        'tools/wikitool sources trace --raw "raw/articles/llm-wiki.md"',
+    ),
+    see_also=(
+        "`wikitool sources coverage` - every uncovered raw file at once",
+        "`wikitool xref link-source` - links a source page to what it mentions",
+    ),
 ))
 def trace(
     raw: Optional[str] = typer.Option(None, "--raw", help="Raw file path to trace forward from"),
@@ -215,13 +242,26 @@ def build_provenance_index(kb_dir: Path, raw_dir: Path) -> str:
         atomic="Yes - the single provenance file is regenerated from scratch",
         budget=cli_contract.Budget.COUNTED,
     ),
-    notes="Regenerate the `kb/provenance.md` reverse index (raw file -> source page -> citing "
-    "pages)",
+    notes=(
+        "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`.",
+    ),
     failures=(cli_contract.Failure(
-        label="",
-        cause="Rare I/O error only",
+        cause="An I/O error while writing `kb/provenance.md` (rare)",
         reaction="Safe to retry freely",
     ),),
+    examples=(
+        "tools/wikitool sources rebuild-index",
+        "tools/wikitool sources rebuild-index --dry-run",
+    ),
+    never=(
+        "Never hand-edit `kb/provenance.md` - re-run this command instead.",
+    ),
+    see_also=(
+        "`wikitool index rebuild` - the page catalog, rebuilt alongside",
+        "`instructions/publish-cycle.md` - where a write session runs this",
+    ),
 ))
 def rebuild_index(
     dry_run: bool = typer.Option(False, "--dry-run", help="Print the result instead of writing kb/provenance.md"),