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

CHANGES.md

@@ -59,11 +59,14 @@ concern - readable here, never shipped as something to parse.
 
 ---
 
-## 7.1.0-beta.3 - 2026-09-25 - stack-close: wait for CI through the authenticated Gitea connection, with timings and a give-up point
+## 7.1.0-beta.4 - 2026-09-25 - wikitool: one data record per command - `-h`, index and CONTRACT.md render from cli_contract (Gitea #121 Phase 1)
 
 **Author:** Torben Nehmer
 
 <!-- wikitool:bumps -->
+**High impact**
+- wikitool: one data record per command - `-h`, index and CONTRACT.md render from cli_contract (Gitea #121 Phase 1)
+
 **Medium impact**
 - CalDAV task-tracker provider (Nextcloud Tasks, iOS Reminders); review reports unknown-value findings instead of skipping them
 
@@ -111,6 +114,43 @@ check after about 4 minutes (5 with a release job), then once a minute, and hand
 after 15. Any shell loop that polls instead must end on the first unexpected response. Dev-only;
 nothing here ships to an instance.
 
+### wikitool: one data record per command - `-h`, index and CONTRACT.md render from cli_contract (Gitea #121 Phase 1)
+
+`--help`/`-h`, the `tools/CONTRACT.md` command reference, and the run-time budget exemption list
+used to be four hand-maintained copies of the same facts about a command - a docstring, two
+tables in `tools/CONTRACT.md` (§ Commands, § Error contracts), and `run_budget.py`'s own
+`SKIP_COMMANDS`/`SKIP_COMMAND_PATHS` sets - and they had already drifted (`xref add`/
+`xref link-source` were missing `--dry-run` from their documented synopsis; the tool error
+contract's non-idempotent list disagreed with the per-command retry-policy cells it stood next
+to). All 61 commands (60 existing, plus the new `docs contract`) now carry one
+`cli_contract.CommandRecord` - name, synopsis, properties (effect, idempotency, atomicity,
+budget, network, gates), exit status and retry policy - attached to the command function by a
+`@cli_contract.record(...)` decorator in its own module. Three views render from that one
+source: `wikitool <cmd> -h` (the full record, plain text), `wikitool -h` (an index line per
+command, fixed-width and `grep`-stable), and `tools/CONTRACT.md`'s generated
+`<!-- wikitool:commands -->` region (`wikitool docs contract [--apply]`), which replaces the two
+old tables. `run_budget.is_exempt` now reads a command's `budget:` property directly instead of
+carrying its own list, which is what `wikitool -h | grep non-idempotent`/`budget:exempt` now
+answers for `AGENTS.md`'s tool error contract instead of a hand-written enumeration.
+
+Help itself changed shape: Rich's boxed panels are off (`typer.core.HAS_RICH = False`) for both
+`--help` and a usage error, so the output is the same plain, GNU-style text with or without a
+TTY - byte-identical, which a new test pins by comparing a real run against one with `isatty`
+patched. `-h` is now a recognised alias for `--help` on every command (no command used the flag
+for anything else). `wikitool docs verify` grew three checks to hold the new machinery to the
+same "checked or absent" rule as everything else it enforces: every registered command has
+exactly one `cli_contract` record and appears exactly once in `cli_contract.GROUPS`, every
+command's non-hidden flags match its record's SYNOPSIS in both directions, and no command's
+rendered help - a docstring above its `\f` marker, or an option's own `help=` text - cites an
+issue number (a distributed instance has no tracker to resolve one against, the same reasoning
+`check_no_issue_references` already applied to shipped `.md` files).
+
+Redactional work - examples, an explicit "never do this" section per command, and pulling the
+"why" out of a record's NOTES into its own section - is Phase 2 (Gitea #142), deliberately not
+part of this change: this pass moved the existing table cells' text into records mechanically,
+without editing it beyond the one documented fix (the `--dry-run` synopsis gap above) and the
+docstring/option-text rewording needed to stop citing issue numbers in rendered help.
+
 ---
 
 ## 7.0.0 - 2026-09-22 - Task-Tracker-Anbindung: Vorhaben als Seitenart, Verpflichtungsschicht, Weekly Review als Read-Time-Join