Two AI includes documented themselves under names nothing else uses

Plugin/unraid/include/ai_profiles.php

@@ -5,47 +5,51 @@
 //   shared chat include and every page that renders it — reads it from here instead of
 //   restating it.
 //
-// WHY THIS EXISTS
-//   A profile used to be defined in five places: history depth in api/ai.php, capabilities in
-//   include/ai.php, label/hint/depth again in the chat's JavaScript, a prompt branch in the
-//   worker, and a label map in pages/scheduler.php. They had already drifted — the JavaScript
-//   knew three profiles where PHP knew four, so the shared chat could not offer troubleshoot at
-//   all and the Scheduler dock hand-rolled its own labels to compensate. The include carried a
-//   comment telling the next person not to let the two tables diverge, which is a comment doing
-//   a data structure's job.
+// DESIGN PRINCIPLES
+//   One definition, not five.
+//       A profile used to be defined in five places: history depth in api/ai.php, capabilities
+//       in include/ai.php, label/hint/depth again in the chat's JavaScript, a prompt branch in
+//       the worker, and a label map in pages/scheduler.php. They had already drifted — the
+//       JavaScript knew three profiles where PHP knew four, so the shared chat could not offer
+//       troubleshoot at all and the Scheduler dock hand-rolled its own labels to compensate. The
+//       include carried a comment telling the next person not to let the two tables diverge,
+//       which is a comment doing a data structure's job.
 //
-// WHAT LIVES HERE, AND WHAT DELIBERATELY DOES NOT
-//   Here: anything more than one file needs to agree on — the set of profiles, their labels and
-//   hints, history depth, capabilities, and whether a profile is offered as a button.
+//   What lives here is whatever more than one file must agree on.
+//       The set of profiles, their labels and hints, history depth, capabilities, and whether a
+//       profile is offered as a button.
 //
-//   Not here: the system prompts. They are long, delicate, and have exactly one consumer, so
-//   moving them would be churn against the most sensitive text in the subsystem for no reduction
-//   in duplication. Tools/ai_chat_worker.php still owns them; it just keys off ids validated
-//   here rather than an if-chain that invents its own vocabulary.
+//       Not the system prompts. They are long, delicate, and have exactly one consumer, so
+//       moving them would be churn against the most sensitive text in the subsystem for no
+//       reduction in duplication. Tools/ai_chat_worker.php still owns them; it just keys off ids
+//       validated here rather than an if-chain that invents its own vocabulary.
 //
-// CAPABILITIES ARE PER PROFILE, NOT PER CAPABILITY
-//   The old table was inverted — capability => [profiles] — which reads well when adding a
-//   capability and badly when answering the question actually asked at runtime, which is always
-//   "what can this profile do". Same content, turned the right way round.
+//   Capabilities are stored per profile, not per capability.
+//       The old table was inverted — capability => [profiles] — which reads well when adding a
+//       capability and badly when answering the question actually asked at runtime, which is
+//       always "what can this profile do". Same content, turned the right way round.
 //
-//   A profile is a contract plus a set of inputs, and the inputs are the half that has to be
-//   enforced rather than requested. The caps list is that half.
+//       A profile is a contract plus a set of inputs, and the inputs are the half that has to be
+//       enforced rather than requested. The caps list is that half.
 //
-//   It exists because the alternative already failed. The same permissions used to live as a
-//   dozen `$profile === 'varaverk' || $profile === 'troubleshoot'` conditions spread across the
-//   worker, and answering "may chat ever be shown a log?" meant reading all of them. It could —
-//   a gate added for run-outcome questions granted it by omission, and the chat profile, whose
-//   entire value is that it has NOT been shown this installation, was one phrasing away from
-//   being handed a health sweep and 120 lines of log. Nothing about that was visible at the
-//   point of the mistake. Here it would have been one missing word on one line.
+// OPERATIONAL SAFEGUARDS
+//   The capability list is the grant, and it is enforced in one place.
+//       The same permissions used to live as a dozen `$profile === 'varaverk' || $profile ===
+//       'troubleshoot'` conditions spread across the worker, and answering "may chat ever be
+//       shown a log?" meant reading all of them. It could — a gate added for run-outcome
+//       questions granted it by omission, and the chat profile, whose entire value is that it
+//       has NOT been shown this installation, was one phrasing away from being handed a health
+//       sweep and 120 lines of log. Nothing about that was visible at the point of the mistake.
+//       Here it would have been one missing word on one line.
 //
-//   A capability is permission, not need. varaverk holds 'health' but only attaches it when the
-//   question looks diagnostic; troubleshoot attaches it always. The gates decide whether an
-//   input is warranted, this decides whether it is allowed, and a gate can never widen the grant.
+//   A capability is permission, not need.
+//       varaverk holds 'health' but only attaches it when the question looks diagnostic;
+//       troubleshoot attaches it always. The gates decide whether an input is warranted, this
+//       decides whether it is allowed, and a gate can never widen the grant.
 //
-//   chat holding an empty capability list is a guarantee, not an oversight. Anything added to it
-//   stops being general chat and becomes an assistant that sometimes lies about this
-//   installation.
+//   chat holding an empty capability list is a guarantee, not an oversight.
+//       Anything added to it stops being general chat and becomes an assistant that sometimes
+//       lies about this installation.
 //
 // EXPORTS
 //   vv_ai_profiles()            the whole table