The dev checkers documented themselves under headings nothing else uses

Plugin/unraid/Tools/ai_log_check.php

@@ -8,10 +8,34 @@
 //   Reads ai_log_fixtures.txt and this host's /var/log/syslog*. Files nothing, writes nothing,
 //   and calls no part of the sweep beyond vv_ai_syslog_findings() on lines it supplies itself.
 //
-// EXIT
+// DESIGN PRINCIPLES
-//   0 when every fixture is recognised as written. Precision findings are reported but never
+//   Only recall can fail the run.
-//   fail the run: what a real syslog contains is a fact about the machine, not about the
+//       A missed fixture is a fact about the patterns and is always a defect. A precision hit is
-//   patterns, and a genuinely failing disk should not turn this into a red test.
+//       a fact about this machine — a genuinely failing disk should not turn this red, and if it
+//       did, the honest fix would be to stop having a failing disk rather than to edit a pattern.
+//
+//   Precision is replayed against real history, not a sample.
+//       The patterns that cause damage are the ones matching ordinary operation, and ordinary
+//       operation is exactly what a hand-written fixture file never contains. Only the machine's
+//       own syslog can show what a pattern fires on when nothing is wrong.
+//
+//   The sweep is never invoked, only its matcher.
+//       vv_ai_syslog_findings() is called on lines this file supplies. Running the real sweep
+//       would file findings, and a test that has to be cleaned up afterwards stops being run.
+//
+// OPERATIONAL SAFEGUARDS
+//   Read-only. Reads ai_log_fixtures.txt and this host's /var/log/syslog*; files no finding,
+//   writes no store, and touches no conf beyond the enable flag.
+//
+//   Exit 0 when every fixture is recognised as written. Precision findings are reported but
+//   never fail the run — see DESIGN PRINCIPLES.
+//
+// RUNTIME MODES
+//   php ai_log_check.php               both checks
+//   php ai_log_check.php --recall      fixtures only
+//   php ai_log_check.php --precision   replay this host's syslog history only
+//
+//   Not scheduled, and deliberately so. Run it after touching VV_AI_SYSLOG_PATTERNS.
 // ═══════════════════════════════════════════════════════════════════════════════════════════════
 require_once dirname(__DIR__) . '/include/ai_repair.php';
 

Plugin/unraid/Tools/ai_log_check.sh

@@ -15,6 +15,47 @@
 #
 # Run it after touching VV_AI_SYSLOG_PATTERNS. Nothing here writes: no findings are filed, no
 # conf is read for anything but the enable flag, and the sweep is never invoked.
+#
+# ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+# A wrapper. The work is in ai_log_check.php, next to the sweep's own matcher — the patterns and
+# vv_ai_syslog_findings() live in include/ai_repair.php, and a bash reimplementation of the
+# matching would be a second set of regexes to keep in step with the first.
+#
+# Flags are forwarded verbatim; nothing is interpreted here.
+#
+# Not scheduled and in no orchestrator. This is a development check that runs when the patterns
+# change, not on a timer — nothing on the running system depends on it.
+#
+# ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# Two checks, because the failure modes are opposite.
+#   Recall catches a pattern that stopped matching; precision catches one that matches too much.
+#   A single test would catch one and silently permit the other, and the second is the one that
+#   fills the findings store with noise until the operator stops reading it.
+#
+# Precision is measured against this machine's real history.
+#   A hand-written fixture file can show that a pattern matches what it should. Only a real
+#   syslog can show what it also matches when nothing is wrong.
+#
+# Only recall fails the run.
+#   What a real syslog contains is a fact about the machine, not about the patterns. A genuinely
+#   failing disk should not turn this red.
+#
+# ==============================================================================================
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+# Read-only. No finding is filed, no store is written, and the repair sweep itself is never run
+# — only its matcher, on lines this check supplies.
+#
+# Safe to run on a live host at any time, including one that is currently faulting. It observes
+# the syslog it replays and changes nothing about it.
+#
 # ==============================================================================================
 # RUNTIME MODES
 # ==============================================================================================

Plugin/unraid/Tools/conf_widget_check.php

@@ -13,16 +13,39 @@
 //     php Tools/conf_widget_check.php            assertions, then the live summary
 //     php Tools/conf_widget_check.php --list     every live field and its inferred control
 //
-// WHY IT ASSERTS AGAINST SNIPPETS AND NOT THE LIVE CONF
+// DESIGN PRINCIPLES
-//   The live conf is the thing being described, so it cannot also be the thing that proves the
+//   Assertions run against snippets, never against the live conf.
-//   description right — an inference rule that silently stopped matching would keep passing as
+//       The live conf is the thing being described, so it cannot also be the thing that proves
-//   the conf drifted to suit it. The snippets are frozen copies of each convention as written,
+//       the description right — an inference rule that silently stopped matching would keep
-//   so a rule change that breaks one shows up here rather than as a wrong control on a page.
+//       passing as the conf drifted to suit it. The snippets are frozen copies of each
+//       convention as written, so a rule change that breaks one shows up here rather than as a
+//       wrong control on a page.
 //
-// WHAT AN INFERENCE IS NOT
+//   An inference is a drawing decision, not a validation.
-//   Consistent with confform.php, none of this validates. A number field carrying min and max is
+//       Consistent with confform.php, none of this validates. A number field carrying min and
-//   a courtesy to whoever is typing, not a promise the value is sensible — the consuming script
+//       max is a courtesy to whoever is typing, not a promise the value is sensible — the
-//   still owns that question.
+//       consuming script still owns that question.
+//
+//   The live pass reports, it does not assert.
+//       What this host's master.conf infers to is a description of that file, not a verdict on
+//       it. Turning the live summary into pass/fail would make an unusual but legitimate
+//       setting look like a defect.
+//
+// OPERATIONAL SAFEGUARDS
+//   Read-only. Parses conf and reports; writes no conf, no store and no page.
+//
+//   Exits non-zero only when a snippet assertion fails, so it can gate a commit without a real
+//   conf's contents ever being able to break the build.
+//
+//   Never renders. It reports which control would be drawn; the drawing stays in confform.php,
+//   so this cannot disagree with the page by construction.
+//
+// RUNTIME MODES
+//   php Tools/conf_widget_check.php            assertions, then the live summary
+//   php Tools/conf_widget_check.php --list     every live field and its inferred control
+//
+//   Hand-run. Not scheduled and in no orchestrator — run it after touching _vv_conf_widget(),
+//   after adding a conf convention, or when a setting draws as the wrong control.
 //
 // DEPENDS ON
 //   include/confform.php   _vv_conf_parse_field_range(), vv_conf_key_is_secret()

Plugin/unraid/Tools/ui_map_build.php

@@ -5,31 +5,49 @@
 //   to reach it. Generated so the assistant can answer "how do I change X" with a path through
 //   the pages instead of an instruction to open master.conf.
 //
-// WHY THE ASSISTANT NEEDS THIS AT ALL
+// DESIGN PRINCIPLES
+//   The assistant cannot see the UI any other way.
 //       The retrieval index reads git-tracked files. PHP body markup is not indexed and would be
-//   useless if it were — a page is a pile of divs, not a description of itself — so the assistant
+//       useless if it were — a page is a pile of divs, not a description of itself — so the
-//   has never had any way to know the UI exists. It could name a conf key and nothing more.
+//       assistant has never had any way to know the UI exists. It could name a conf key and
-//   pages/readme/*.md is the one directory the chunker classifies as kind='ui', which is why the
+//       nothing more. pages/readme/*.md is the one directory the chunker classifies as
-//   output lands there and not in docs/.
+//       kind='ui', which is why the output lands there and not in docs/.
 //
-// WHY IT IS GENERATED
+//   Generated, because a hand-written map lies with confidence.
-//   A hand-written map is a second description of the pages, and the moment a card moves it
+//       A second description of the pages starts being wrong the moment a card moves, and that
-//   starts lying with total confidence — which is worse than saying nothing, because the
+//       is worse than saying nothing, because the assistant will repeat it. Everything here is
-//   assistant will repeat it. Everything here is derived from the same registries the pages
+//       derived from the same registries the pages themselves are built from:
-//   themselves are built from: VV_SCRIPT_CONF_SECTIONS for what the Scheduler shows per script,
+//       VV_SCRIPT_CONF_SECTIONS for what the Scheduler shows per script, VV_UI_SECTION_SURFACES
-//   VV_UI_SECTION_SURFACES for the pages that show sections by subject, and the conf files for
+//       for the pages that show sections by subject, and the conf files for the settings and
-//   the settings and their controls.
+//       their controls.
+//
+//   An unreachable section is reported, never dropped.
+//       A section no page renders is listed at the end rather than silently omitted. A setting
+//       with no route through the UI is a real finding, and this map is the only thing that
+//       would ever notice.
 //
 // OPERATIONAL MODEL
-//   Hand-run, and re-run after adding a conf section, a script mapping or a settings surface.
+//   Reads the section registries and the conf files, resolves each setting to the page and card
-//   Writes exactly one file and nothing else.
+//   that renders it, and writes the whole map in one pass. Nothing is merged with what is
+//   already there — the output is derived entirely from the registries, so a stale entry cannot
+//   survive a rebuild.
 //
+// OPERATIONAL SAFEGUARDS
+//   Writes exactly one file, pages/readme/ui-map.md, and nothing else. No conf is modified, no
+//   page is touched, and the registries it reads are only read.
+//
+//   --check reports what would change and writes nothing, so the map can be verified current in
+//   a commit without regenerating it.
+//
+//   Generated output only. Nothing hand-edited belongs in ui-map.md — an edit there is lost on
+//   the next run, which is the correct behaviour for a derived file and the reason the header
+//   says so.
+//
+// RUNTIME MODES
 //   php Tools/ui_map_build.php            write the map
 //   php Tools/ui_map_build.php --check    report what it would change, write nothing
 //
-//   Only sections that are genuinely reachable are listed. A section no page renders is reported
+//   Hand-run. Re-run after adding a conf section, a script mapping or a settings surface.
-//   at the end as unreachable rather than silently omitted — a setting with no route is a real
-//   finding, and the map is the only place that would notice.
 //
 // DEPENDS ON
 //   include/confform.php   the section registries, the parser, and the inferred controls