tools: command records, Instance health group - one bullet per check, examples (#142)

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

CHANGES.md

@@ -59,7 +59,7 @@ concern - readable here, never shipped as something to parse.
 
 ---
 
-## 7.1.0-beta.19 - 2026-09-26 - Command records, Private instances group: one line per cause, examples, prohibitions
+## 7.1.0-beta.20 - 2026-09-26 - Command records, Instance health group: one bullet per check, examples
 
 **Author:** Torben Nehmer
 
@@ -88,6 +88,7 @@ concern - readable here, never shipped as something to parse.
 - Command records, Telemetry group: examples, the missing --fail-on-error exit line
 - Command records, Content migrations group: one line per cause, examples, prohibitions
 - Command records, Private instances group: one line per cause, examples, prohibitions
+- Command records, Instance health group: one bullet per check, examples
 <!-- /wikitool:bumps -->
 
 ### CalDAV task-tracker provider (Nextcloud Tasks, iOS Reminders); review reports unknown-value findings instead of skipping them
@@ -324,6 +325,14 @@ single paragraph is now one bullet per step of the merge, and its exit-1 causes
 fetch failure, a failing git step inside the open merge, and the post-commit leak, which its old
 record mentioned only in passing - each carry their own reaction.
 
+### Command records, Instance health group: one bullet per check, examples
+
+`doctor` rewritten the same way; text only. Its one-sentence inventory of every check is now one
+bullet per area, each stating which outcome is `OK`, `WARN` or `FAIL`. One stale reason was
+dropped rather than moved: the record justified the conventions `FAIL` by `xref`/`cite` writing
+out of the section headings, while the check's own docstring calls those headings cosmetic and
+grounds the `FAIL` in the file binding every page.
+
 ---
 
 ## 7.0.0 - 2026-09-22 - Task-Tracker-Anbindung: Vorhaben als Seitenart, Verpflichtungsschicht, Weekly Review als Read-Time-Join

VERSION

@@ -1 +1 @@
-7.1.0-beta.19
+7.1.0-beta.20

tools/CONTRACT.md

@@ -3151,6 +3151,11 @@ Check that this instance is correctly configured.
 - budget: exempt
 - network: yes
 
+**EXAMPLES**
+
+- `tools/wikitool doctor`
+- `tools/wikitool doctor --json`
+
 **EXIT STATUS**
 
 - 0    success
@@ -3162,7 +3167,25 @@ Check that this instance is correctly configured.
 
 **NOTES**
 
-Dependencies (Python, ripgrep), author resolution, stack version, git identity/branch/remote, published skills, kb/raw/reports/work/instructions structure, personalization (`USER.md`/`SOUL.md` present **and** filled - a file still carrying the template's sentinel is a `FAIL`, since a renamed template is not a filled one), the KB conventions (`kb/CONVENTIONS.md` present, unsentinelled, and naming all three tool-owned section headings - a `FAIL` on any of the three, because `xref`/`cite` write out of it), the environment note (`ENVIRONMENT.md` - optional, so absent is `OK`; a still-templated one is a `WARN`), generated files, whether the MCP `submit` tool is armed (`.wikitool-upload.json` present/absent/malformed, its limits, and how many submissions are waiting in `mcp-upload/` - absent is `OK` and means the write path does not exist at all, malformed is the one `FAIL` here, since a broken opt-in must not silently disable the limits it exists to enforce), the task-tracker provider (`.wikitool-tasks.json` present/absent/malformed - absent is `OK` and means no tracker is configured, malformed is `FAIL` for the same reason the upload opt-in is; for a configured `superproductivity` provider, also its configured `access` path's own state - `access: "api"` reports whether its local REST API answers `GET /health` right now, `access: "snapshot"` reports whether a backup file is ready; the *other* access path is never attempted and is not a finding - and neither ever `FAIL`s, an app that is simply not running is not a fault; for a configured `caldav` provider, whether the server is reachable and Basic auth succeeds - also never a `FAIL`, only a broken config block is), the session id source (`OK` for `WIKITOOL_SESSION_ID` or a registered harness variable, `WARN` only for the bare parent-pid fallback - see `chemenu.session`), and telemetry state (on/off, why - installation-form default, `.wikitool-telemetry.json`, or `WIKI_TRACE` - and the current session count/byte total against both caps; never `FAIL`, see `EVALS.md`). Read-only, exit 1 only on a `FAIL` (a missing remote, session id, or `VERSION` is a `WARN`, not a fault). Exempt from the Iteration Budget Gate
+- Checks dependencies (Python, ripgrep), author resolution, stack version, git identity/branch/remote, published skills, the kb/raw/reports/work/instructions structure, and generated files.
+- Personalization: `USER.md`/`SOUL.md` present **and** filled - a file still carrying the template's sentinel is a `FAIL`.
+- KB conventions: `kb/CONVENTIONS.md` present, unsentinelled, and naming all three tool-owned section headings - a `FAIL` on any of the three.
+- Environment note: `ENVIRONMENT.md` is optional, so absent is `OK`; a still-templated one is a `WARN`.
+- MCP `submit` tool: whether `.wikitool-upload.json` is present, absent or malformed, its limits, and how many submissions wait in `mcp-upload/`. Absent is `OK` and means the write path does not exist at all; malformed is a `FAIL`.
+- Task tracker: `.wikitool-tasks.json` present, absent or malformed - absent is `OK` (no tracker configured), malformed is a `FAIL`.
+- For a configured `superproductivity` provider, the configured `access` path's own state: `access: "api"` reports whether its local REST API answers `GET /health` right now, `access: "snapshot"` whether a backup file is ready. The other access path is never attempted, and neither state is ever a `FAIL`.
+- For a configured `caldav` provider, whether the server is reachable and Basic auth succeeds - never a `FAIL`; only a broken config block is.
+- Session id source: `OK` for `WIKITOOL_SESSION_ID` or a registered harness variable, `WARN` only for the bare parent-pid fallback.
+- Telemetry: on or off and why - installation-form default, `.wikitool-telemetry.json`, or `WIKI_TRACE` - and the current session's count and byte total against both caps; never a `FAIL`.
+- Exits 1 only on a `FAIL`; a missing remote, session id or `VERSION` is a `WARN`, not a fault.
+- Read-only and exempt from the Iteration Budget Gate.
+
+**SEE ALSO**
+
+- `instructions/setup-instance.md` - the setup steps most findings point back to
+- `INSTALL.md` § "Konfiguration" - the per-checkout configuration files
+- `EVALS.md` - telemetry state and caps
+- `instructions/session-setup.md` - setting `WIKITOOL_SESSION_ID`
 <!-- /wikitool:commands -->
 ## Design notes
 

tools/chemenu/commands/doctor.py

@@ -628,38 +628,51 @@ def run_doctor() -> list[Check]:
         budget=cli_contract.Budget.EXEMPT,
         network=cli_contract.Network.YES,
     ),
-    notes="Dependencies (Python, ripgrep), author resolution, stack version, git "
+    notes=(
-    "identity/branch/remote, published skills, kb/raw/reports/work/instructions structure, "
+        "Checks dependencies (Python, ripgrep), author resolution, stack version, git "
-    "personalization (`USER.md`/`SOUL.md` present **and** filled - a file still carrying the "
+        "identity/branch/remote, published skills, the kb/raw/reports/work/instructions "
-    "template's sentinel is a `FAIL`, since a renamed template is not a filled one), the KB "
+        "structure, and generated files.",
-    "conventions (`kb/CONVENTIONS.md` present, unsentinelled, and naming all three tool-owned "
+        "Personalization: `USER.md`/`SOUL.md` present **and** filled - a file still carrying "
-    "section headings - a `FAIL` on any of the three, because `xref`/`cite` write out of it), "
+        "the template's sentinel is a `FAIL`.",
-    "the environment note (`ENVIRONMENT.md` - optional, so absent is `OK`; a still-templated "
+        "KB conventions: `kb/CONVENTIONS.md` present, unsentinelled, and naming all three "
-    "one is a `WARN`), generated files, whether the MCP `submit` tool is armed "
+        "tool-owned section headings - a `FAIL` on any of the three.",
-    "(`.wikitool-upload.json` present/absent/malformed, its limits, and how many submissions "
+        "Environment note: `ENVIRONMENT.md` is optional, so absent is `OK`; a still-templated "
-    "are waiting in `mcp-upload/` - absent is `OK` and means the write path does not exist at "
+        "one is a `WARN`.",
-    "all, malformed is the one `FAIL` here, since a broken opt-in must not silently disable the "
+        "MCP `submit` tool: whether `.wikitool-upload.json` is present, absent or malformed, "
-    "limits it exists to enforce), the task-tracker provider (`.wikitool-tasks.json` "
+        "its limits, and how many submissions wait in `mcp-upload/`. Absent is `OK` and means "
-    "present/absent/malformed - absent is `OK` and means no tracker is configured, malformed is "
+        "the write path does not exist at all; malformed is a `FAIL`.",
-    "`FAIL` for the same reason the upload opt-in is; for a configured `superproductivity` "
+        "Task tracker: `.wikitool-tasks.json` present, absent or malformed - absent is `OK` "
-    "provider, also its configured `access` path's own state - `access: \"api\"` reports "
+        "(no tracker configured), malformed is a `FAIL`.",
-    "whether its local REST API answers `GET /health` right now, `access: \"snapshot\"` reports "
+        "For a configured `superproductivity` provider, the configured `access` path's own "
-    "whether a backup file is ready; the *other* access path is never attempted and is not a "
+        "state: `access: \"api\"` reports whether its local REST API answers `GET /health` "
-    "finding - and neither ever `FAIL`s, an app that is simply not running is not a fault; for "
+        "right now, `access: \"snapshot\"` whether a backup file is ready. The other access "
-    "a configured `caldav` provider, whether the server is reachable and Basic auth succeeds - "
+        "path is never attempted, and neither state is ever a `FAIL`.",
-    "also never a `FAIL`, only a broken config block is), the session id source (`OK` for "
+        "For a configured `caldav` provider, whether the server is reachable and Basic auth "
-    "`WIKITOOL_SESSION_ID` or a registered harness variable, `WARN` only for the bare "
+        "succeeds - never a `FAIL`; only a broken config block is.",
-    "parent-pid fallback - see `chemenu.session`), and telemetry state (on/off, why - "
+        "Session id source: `OK` for `WIKITOOL_SESSION_ID` or a registered harness variable, "
-    "installation-form default, `.wikitool-telemetry.json`, or `WIKI_TRACE` - and the current "
+        "`WARN` only for the bare parent-pid fallback.",
-    "session count/byte total against both caps; never `FAIL`, see `EVALS.md`). Read-only, exit "
+        "Telemetry: on or off and why - installation-form default, `.wikitool-telemetry.json`, "
-    "1 only on a `FAIL` (a missing remote, session id, or `VERSION` is a `WARN`, not a fault). "
+        "or `WIKI_TRACE` - and the current session's count and byte total against both caps; "
-    "Exempt from the Iteration Budget Gate",
+        "never a `FAIL`.",
+        "Exits 1 only on a `FAIL`; a missing remote, session id or `VERSION` is a `WARN`, not a "
+        "fault.",
+        "Read-only and exempt from the Iteration Budget Gate.",
+    ),
     failures=(cli_contract.Failure(
-        label="",
         cause="At least one check reported `FAIL` (a `WARN`, e.g. no remote or no "
         "`WIKITOOL_SESSION_ID`, does not exit 1)",
         reaction="Each finding names its own fix command; re-run after applying it",
     ),),
+    examples=(
+        "tools/wikitool doctor",
+        "tools/wikitool doctor --json",
+    ),
+    see_also=(
+        "`instructions/setup-instance.md` - the setup steps most findings point back to",
+        "`INSTALL.md` § \"Konfiguration\" - the per-checkout configuration files",
+        "`EVALS.md` - telemetry state and caps",
+        "`instructions/session-setup.md` - setting `WIKITOOL_SESSION_ID`",
+    ),
 ))
 def doctor_command(
     json_out: bool = typer.Option(False, "--json", help="Print the checks as JSON"),