tools: one data record per command - -h, index and CONTRACT.md render from cli_contract (#121)

Files changed:
- AGENTS.md
- CHANGES.md
- VERSION
- instructions/dev/doc-pull-through.md
- instructions/dev/stack-close/SKILL.md
- tools/CONTRACT.md
- tools/README.md
- tools/chemenu/cli.py
- tools/chemenu/cli_contract.py
- tools/chemenu/commands/cite_cmd.py
- tools/chemenu/commands/dist_cmd.py
- tools/chemenu/commands/docs_verify.py
- tools/chemenu/commands/doctor.py
- tools/chemenu/commands/eval_cmd.py
- tools/chemenu/commands/git_publish.py
- tools/chemenu/commands/index_build.py
- tools/chemenu/commands/instructions_cmd.py
- tools/chemenu/commands/links_cmd.py
- tools/chemenu/commands/lint.py
- tools/chemenu/commands/log_append.py
- tools/chemenu/commands/migrate_cmd.py
- tools/chemenu/commands/new_page.py
- tools/chemenu/commands/page_ops.py
- tools/chemenu/commands/provenance_cmd.py
- tools/chemenu/commands/raw_cmd.py
- tools/chemenu/commands/review_cmd.py
- tools/chemenu/commands/run_budget.py
- tools/chemenu/commands/search.py
- tools/chemenu/commands/task_cmd.py
- tools/chemenu/commands/touch.py
- tools/chemenu/commands/types_cmd.py
- tools/chemenu/commands/upload_cmd.py
- tools/chemenu/commands/upstream_cmd.py
- tools/chemenu/commands/version_cmd.py
- tools/chemenu/commands/work_cmd.py
- tools/chemenu/commands/xref.py
- tools/chemenu/tests/test_cli_contract.py
- tools/chemenu/tests/test_docs_verify.py
- tools/chemenu/tests/test_run_budget.py

AGENTS.md

@@ -219,7 +219,7 @@ stack is built the way it is - see [File naming](#file-naming)), and this file.
 | `kb/` | [kb/CONTRACT.md](kb/CONTRACT.md) + `kb/CONVENTIONS.md` | What the stack enforces about a page (collections, linking, provenance), and beside it what this instance decided (language, naming, tone, labels, hedging) |
 | `reports/` | [reports/CONTRACT.md](reports/CONTRACT.md) | Why reports and traces are generated, gitignored, and carried into `kb/log.md` |
 | `work/` | [work/CONTRACT.md](work/CONTRACT.md) | Workshop runs: run keys, required files, why they are tracked, how a run closes |
-| `tools/` | [tools/CONTRACT.md](tools/CONTRACT.md) | Command reference and per-command error contracts, one row per command in each of two tables - a file to look a row up in rather than read through, as its own opening paragraph says - plus the maintenance schedule |
+| `tools/` | [tools/CONTRACT.md](tools/CONTRACT.md) | Command reference: one generated data record per command (name, synopsis, properties, exit status, retry policy), plus an index and the maintenance schedule - a command to look up (`wikitool <cmd> -h`, or a `grep` here) rather than a file to read through, as its own opening paragraph says |
 | `instructions/` | [instructions/CONTRACT.md](instructions/CONTRACT.md) | Instruction vs. skill, publishing, writing standard |
 
 **By collection** - then read the contract for the collection you are writing in.
@@ -295,12 +295,18 @@ Every `tools/wikitool` call has exactly four outcomes:
 3. **User clearance required (exit 42).** Not an error and not yours to resolve: show the
    command's output to the user verbatim and stop. See [Gates](#gates).
 4. **Unexpected error (timeout, crash, interrupted process).** Do not guess whether it
-   worked, do not retry more than once, and never hand-write what the tool would have
-   produced.
+   worked, do not retry more than once - or, when the command is non-idempotent, not at
+   all: an unclear outcome plus a blind retry is how a non-idempotent call takes effect
+   twice. This is narrower than case 2's own "fix the cause, retry once": a validation error
+   is a known cause with a known fix, so it always gets that one retry regardless of
+   idempotency, and a command's own retry-policy text (`wikitool <cmd> -h`) is the one to
+   follow for it.
 
-After the single allowed retry - or immediately, for the non-idempotent commands `new`,
-`log append`, `publish`, and `upstream merge` - stop and report the exact command and error
-text to the user.
+After the single allowed retry - or immediately, for case 4 on a non-idempotent command -
+stop and report the exact command and error text to the user. Which commands those are is
+not a list here to drift behind the code: `wikitool -h | grep non-idempotent` reads it from
+each command's own
+`cli_contract` record, the same property `tools/CONTRACT.md`'s generated index prints.
 
 Per-command detail (what exit 1 means, whether the command is atomic, whether a retry is
 safe) is in [tools/CONTRACT.md](tools/CONTRACT.md). A gate refusal is not a validation error -
@@ -338,9 +344,9 @@ READMEs go in [CHANGES.md](CHANGES.md) - never in an inline version-history tabl
 change that introduced a stage, a command or a workflow, not follow-up work: nobody comes back
 for them, and a document that describes a repo which no longer exists is worse than none. What
 `tools/wikitool docs verify` mechanically checks is exactly what its own `docs verify` row in
-[tools/CONTRACT.md](tools/CONTRACT.md) lists - no more. **Every cell's text is outside that
-check** - a command table entry's description, an error contract's wording, a stage contract's
-prose - and is therefore session work, the same as the three README-shaped files.
+[tools/CONTRACT.md](tools/CONTRACT.md) lists - no more. **Every prose field is outside that
+check** - a command's own summary, notes or retry-policy text, a stage contract's prose - and is
+therefore session work, the same as the three README-shaped files.
 
 `docs/` pages are held to a different clock than those three. A README goes stale on every new
 flag; a `docs/` page goes stale only when the reasoning it wrote down stops holding - a gate