tools: command records, Catalog and log group - bullets, examples, prohibitions (#142)

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

tools/chemenu/commands/index_build.py

@@ -229,16 +229,35 @@ def build_index(kb_dir: Path) -> str:
         "some regenerated and others not",
         budget=cli_contract.Budget.COUNTED,
     ),
-    notes="`kb/index.md` becomes a map (statistics, one row per collection and per area, links "
-    "to the shards) and the page tables are written to a generated `INDEX.md` in each "
-    "collection. An area past 50 rows gets its own shard. Stale shards from removed "
-    "collections/areas are deleted in the same pass",
+    notes=(
+        "Rewrites `kb/index.md` as a map: statistics, one row per collection and per area, and "
+        "links to the shards - no page rows.",
+        "Writes the page tables to a generated `INDEX.md` in each collection. An area with more "
+        "than 50 rows gets its own `INDEX.md` in its directory.",
+        "Deletes stale shards - an `INDEX.md` of a collection or area that no longer exists - "
+        "in the same pass.",
+        "Warns about every page nested more than one directory below its collection; it is "
+        "still catalogued, folded into its area.",
+        "`--dry-run` prints every file it would write and every stale shard it would remove, "
+        "and writes nothing.",
+    ),
     failures=(cli_contract.Failure(
-        label="",
-        cause="Rare I/O error only",
+        cause="An I/O error while writing or removing a catalog file (rare)",
         reaction="Safe to retry freely - the plan is always recomputed from the pages currently "
         "on disk, so a re-run converges",
     ),),
+    examples=(
+        "tools/wikitool index rebuild",
+        "tools/wikitool index rebuild --dry-run",
+    ),
+    never=(
+        "Never hand-edit `kb/index.md` or an `INDEX.md` - re-run this command instead.",
+    ),
+    see_also=(
+        "`wikitool search` - finds a page without reading the catalog",
+        "`wikitool lint` - its Nested Pages finding is what the warning previews",
+        "`instructions/publish-cycle.md` - where a write session runs this",
+    ),
 ))
 def index_rebuild(
     dry_run: bool = typer.Option(

tools/chemenu/commands/log_append.py

@@ -64,13 +64,34 @@ def ingests_since_last_lint(entries: list[tuple[str, str, str]]) -> int:
         atomic="Yes - single append",
         budget=cli_contract.Budget.COUNTED,
     ),
-    notes="Append a formatted entry to `kb/log.md`.",
-    failures=(cli_contract.Failure(
-        label="",
-        cause="Invalid `--op` or unreadable `--body-file`",
-        reaction="**Not idempotent.** If the previous run's outcome is uncertain, check the tail "
-        "of `kb/log.md` before retrying",
-    ),),
+    notes=(
+        "Appends one entry to `kb/log.md`: a `## [YYYY-MM-DD] <op> | <title>` heading, the body "
+        "if one is given, and a `---` separator.",
+        "Not idempotent: every successful run appends a new entry, including a repeated one.",
+    ),
+    failures=(
+        cli_contract.Failure(
+            cause="`--op` is not one of ingest, query, lint, create, update, delete, rename, move",
+            reaction="Nothing was written - fix the argument and retry once",
+        ),
+        cli_contract.Failure(
+            cause="`--body-file` cannot be read",
+            reaction="Nothing was written - fix the path and retry once",
+        ),
+    ),
+    examples=(
+        'tools/wikitool log append --op ingest --title "raw/articles/docker-cheatsheet.md" '
+        '--body "Created [[Docker]]; updated [[Container]]."',
+        'tools/wikitool log append --op lint --title "2026-09-26" --body-file lint-summary.md',
+    ),
+    never=(
+        "Never re-run after an uncertain outcome without first checking the tail of "
+        "`kb/log.md` - a second run appends a second entry.",
+    ),
+    see_also=(
+        "`wikitool log status` - counts the ingests logged since the last lint",
+        "`instructions/publish-cycle.md` - where a write session runs this",
+    ),
 ))
 def log_append(
     op: str = typer.Option(..., "--op", help="|".join(VALID_OPS)),
@@ -101,10 +122,24 @@ def log_append(
         atomic="Read-only",
         budget=cli_contract.Budget.COUNTED,
     ),
-    notes="The deterministic trigger behind the Maintenance Schedule's \"every 10 sources\" "
-    "full-lint cadence. Never fails (reports 0 if `kb/log.md` is missing or empty). Safe to "
-    "retry freely.",
-    failures=(),
+    notes=(
+        "Counts the `ingest` entries in `kb/log.md` after the most recent `lint` entry, or "
+        "since the start of the log if it was never linted, and the total number of entries.",
+        "At 10 or more it prints that the `wiki-lint` skill is due next - the every-10-sources "
+        "full lint of the Maintenance Schedule.",
+        "Read-only; safe to retry freely.",
+    ),
+    failures=(cli_contract.Failure(
+        cause="`kb/log.md` is missing or empty - reported as nothing logged, not a failure",
+        reaction="",
+        code=0,
+    ),),
+    examples=("tools/wikitool log status",),
+    see_also=(
+        "`wikitool log append` - writes the entries this counts",
+        "`wiki-lint` skill - what the threshold asks for",
+        "`tools/CONTRACT.md` § Maintenance schedule - the cadence this reports on",
+    ),
 ))
 def log_status():
     """Report how many `ingest` operations have been logged since the last