From b79f083cc157206d6b71c37e59a3c50e026dd50c Mon Sep 17 00:00:00 2001
From: Torben Nehmer <torben@nehmer.net>
Date: Sat, 26 Sep 2026 07:54:12 +0200
Subject: [PATCH] docs: README/INSTALL/DEVELOPMENT/docs point at -h and command
 records, not the old tables (#121)

Files changed:
- DEVELOPMENT.md
- INSTALL.md
- README.md
- docs/knowledge-and-commitment.md
---
 DEVELOPMENT.md                   |  2 +-
 INSTALL.md                       |  3 ++-
 README.md                        | 20 +++++++++++---------
 docs/knowledge-and-commitment.md |  2 +-
 4 files changed, 15 insertions(+), 12 deletions(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 0f841d1..7bd6a2c 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -82,7 +82,7 @@ Die drei Verify-Befehle stehen oben in Schritt 3; was jeder von ihnen prüft, st
 [tools/CONTRACT.md](tools/CONTRACT.md) und wird dort von `docs verify` gegen die tatsächliche
 CLI gehalten. Hier steht es bewusst **nicht** noch einmal: eine zweite Beschreibung derselben
 Befehle ist genau die Kopie, die driftet (AGENTS.md Invariante 8), und dieses Dokument liegt
-außerhalb der Dateien, die der Kommandotabellen-Check von `docs verify` abdeckt - hier fällt eine
+außerhalb der Dateien, die der Kommando-Datensatz-Check von `docs verify` abdeckt - hier fällt eine
 Drift also niemandem auf. Was `pytest` an dieser Stelle vom Entwickler erwartet, steht in
 [instructions/dev/testing-conventions.md](instructions/dev/testing-conventions.md).
 
diff --git a/INSTALL.md b/INSTALL.md
index e809805..9f3c2a5 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -242,7 +242,8 @@ eingeschlossen, sha256-Vergleich von Hand). `dist upgrade` ersetzt genau diesen
 dennoch von Hand nachvollziehen will oder muss (ein Werkzeug, das `wikitool` selbst nicht
 ausführen kann), findet die Dateiliste im `files`-Block der `.wikitool-release.json` und die
 Ausnahmen (`kb/CONVENTIONS.md`, `kb/*/COLLECTION.md`, `.wikitool-kb.json`) in
-[tools/CONTRACT.md](tools/CONTRACT.md)s `dist upgrade`-Zeile.
+[tools/CONTRACT.md](tools/CONTRACT.md)s `dist upgrade`-Datensatz (oder direkt:
+`tools/wikitool dist upgrade -h`).
 
 ## Konfiguration
 
diff --git a/README.md b/README.md
index d2b0e83..e49ca74 100644
--- a/README.md
+++ b/README.md
@@ -134,7 +134,7 @@ chemenu/
 ├── reports/            # DERIVED: lint reports, traces, eval scores. Gitignored
 │   └── CONTRACT.md
 └── tools/              # COMPILER: the wikitool CLI
-    ├── CONTRACT.md     # Command reference, error contracts, maintenance schedule
+    ├── CONTRACT.md     # Command records (generated) and index, maintenance schedule
     └── README.md       # How wikitool is built and how to change it
 ```
 
@@ -411,16 +411,18 @@ Mechanical wiki operations - never hand-edited by the LLM - are handled by
 `tools/wikitool`: scaffolding pages, renaming and deleting them, cross-references,
 index/log/provenance regeneration, structural linting, and publishing.
 
-The full command reference - every option, the per-command error contracts, and
-the maintenance schedule - is in [`tools/CONTRACT.md`](tools/CONTRACT.md). It is
-the single place that list lives, and `tools/wikitool docs verify` checks it
-against the CLI in both directions. [`tools/README.md`](tools/README.md) is the
-other half: how the CLI is built and how to add a command. `AGENTS.md` holds the
-invariants that say when each command is mandatory.
+Every command carries one data record - synopsis, properties, exit status,
+retry policy - kept next to its code. `tools/wikitool <command> -h` prints it,
+`tools/wikitool -h` prints a one-line index of all of them, and
+[`tools/CONTRACT.md`](tools/CONTRACT.md) holds a generated copy together with the
+maintenance schedule; `tools/wikitool docs verify` checks that copy and every
+command's flags against the CLI in both directions. [`tools/README.md`](tools/README.md)
+is the other half: how the CLI is built and how to add a command. `AGENTS.md`
+holds the invariants that say when each command is mandatory.
 
 ```bash
-tools/wikitool --help
-tools/wikitool <command> --help
+tools/wikitool -h
+tools/wikitool <command> -h
 ```
 
 <!-- dist:strip-start -->
diff --git a/docs/knowledge-and-commitment.md b/docs/knowledge-and-commitment.md
index e999b65..e8da208 100644
--- a/docs/knowledge-and-commitment.md
+++ b/docs/knowledge-and-commitment.md
@@ -5,7 +5,7 @@ Those look like one subject - both are "things about my projects" - and the stac
 keeps them apart: `kb/gtd/` holds one page per initiative, an external task tracker holds the
 open items, and the only thing that crosses between them is a name. This page is about why that
 line was drawn there. The rules that follow from it live in [kb/CONTRACT.md](../kb/CONTRACT.md)
-and the `review`, `new project` and `task new` rows of [tools/CONTRACT.md](../tools/CONTRACT.md).
+and the `review`, `new` and `task new` records in [tools/CONTRACT.md](../tools/CONTRACT.md).
 
 <!-- wikitool:toc -->
 ## Contents