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/CONTRACT.md

@@ -603,18 +603,37 @@ Regenerate the catalog from every page's frontmatter.
 - budget: counted
 - network: no
 
+**EXAMPLES**
+
+- `tools/wikitool index rebuild`
+- `tools/wikitool index rebuild --dry-run`
+
 **EXIT STATUS**
 
 - 0    success
-- 1    Rare I/O error only
+- 1    An I/O error while writing or removing a catalog file (rare)
 
 **ON FAILURE**
 
-- Rare I/O error only -> Safe to retry freely - the plan is always recomputed from the pages currently on disk, so a re-run converges
+- An I/O error while writing or removing a catalog file (rare) -> Safe to retry freely - the plan is always recomputed from the pages currently on disk, so a re-run converges
+
+**NEVER**
+
+- Never hand-edit `kb/index.md` or an `INDEX.md` - re-run this command instead.
 
 **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
+- 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.
+
+**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
 
 #### `log append`
 
@@ -632,18 +651,35 @@ Append a formatted entry to `kb/log.md`.
 - budget: counted
 - network: no
 
+**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`
+
 **EXIT STATUS**
 
 - 0    success
-- 1    Invalid `--op` or unreadable `--body-file`
+- 1    `--op` is not one of ingest, query, lint, create, update, delete, rename, move
+- 1    `--body-file` cannot be read
 
 **ON FAILURE**
 
-- Invalid `--op` or unreadable `--body-file` -> **Not idempotent.** If the previous run's outcome is uncertain, check the tail of `kb/log.md` before retrying
+- `--op` is not one of ingest, query, lint, create, update, delete, rename, move -> Nothing was written - fix the argument and retry once
+- `--body-file` cannot be read -> Nothing was written - fix the path and retry once
+
+**NEVER**
+
+- Never re-run after an uncertain outcome without first checking the tail of `kb/log.md` - a second run appends a second entry.
 
 **NOTES**
 
-Append a formatted entry to `kb/log.md`.
+- 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.
+
+**SEE ALSO**
+
+- `wikitool log status` - counts the ingests logged since the last lint
+- `instructions/publish-cycle.md` - where a write session runs this
 
 #### `log status`
 
@@ -661,13 +697,26 @@ Read-only: count `ingest` entries logged since the last `lint` entry.
 - budget: counted
 - network: no
 
+**EXAMPLES**
+
+- `tools/wikitool log status`
+
 **EXIT STATUS**
 
 - 0    success
+- 0    `kb/log.md` is missing or empty - reported as nothing logged, not a failure
 
 **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.
+- 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.
+
+**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
 
 ### Finding and checking