Add structured headers to the PHP include layer, fix monitor state paths

All 16 include/ files now carry PURPOSE / DESIGN PRINCIPLES / OPERATIONAL
SAFEGUARDS / EXPORTS / CONFIGURATION, keeping the first three section names
identical to the bash headers so retrieval can route across both languages.

monitor.php read six watchdog state files from /tmp while the watchdogs write
to STATE_DIR, so every strike set came back empty and the summary reported
healthy unconditionally. docs.php gained path containment before it is wired
to a page.

Plugin/unraid/include/vms.php

@@ -1,4 +1,33 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   VM inventory for the monitor page — name, state, and assigned resources for each libvirt
+//   domain on this host.
+//
+// DESIGN PRINCIPLES
+//   Prefer the Unraid API, fall back to virsh.
+//       The API path returns the full set in one call; virsh is queried per domain only when
+//       the API is unavailable.
+//
+//   Reports VM state; never changes it. Nothing here starts, stops, or reconfigures a domain.
+//
+// OPERATIONAL SAFEGUARDS
+//   Domain names are shell-escaped.
+//       Every virsh invocation passes the name through escapeshellarg(), so a domain named
+//       with shell metacharacters cannot become a command.
+//
+//   A host with no VMs, or no libvirt at all, returns an empty list.
+//       The VM card simply does not render. This is the expected state on a host that does
+//       not run VMs, not a failure.
+//
+//   Unknown state is reported as 'unknown' rather than assumed stopped.
+//
+// EXPORTS
+//   vv_get_vms()   every libvirt domain with state and assigned resources
+//
+// CONFIGURATION
+//   None. Reads libvirt through the API or virsh; no Varaverk conf variables involved.
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 require_once __DIR__ . '/unraid_api.php';
 
 function vv_get_vms(): array {