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/common.php

@@ -1,9 +1,69 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   The system-metrics library. Everything the monitor page shows about this machine —
+//   CPU per core, memory breakdown, GPUs, disks and pools, network, UPS, parity, VMs,
+//   containers, transcodes — plus a roll-up of the same for remote nodes.
+//
+// DESIGN PRINCIPLES
+//   Prefer the Unraid API, fall back to reading the system directly.
+//       vv_api_data() is tried first; when it is unavailable each metric has a local path
+//       (/proc, /sys, emhttp ini files, shell tools). The API going away degrades detail,
+//       never the page.
+//
+//   Remote stats read every host*.conf, not just this host's.
+//       A partner's API key lives in the partner's own conf. vv_remote_hosts_stats() globs
+//       CONF_DIR for all host*.conf and merges what it finds, because sparse checkout means
+//       the partner's file arrives through the conf cache rather than from git.
+//
+//   Background cache first, live call second.
+//       Remote payloads written by remote_arr_cache_writer.sh (every 2h) are used when
+//       present; otherwise a live call runs behind a 30s inline cache. The expensive path is
+//       the exception, not the default.
+//
+//   Reports raw numbers, applies no policy.
+//       Thresholds, alerting and remediation belong to the watchdogs. This file answers
+//       "what is the value" and nothing else.
+//
+// OPERATIONAL SAFEGUARDS
+//   Every read degrades to empty, never fatal.
+//       Filesystem reads use @ with a ?: fallback and every shell_exec redirects stderr.
+//       A missing GPU, absent UPS, or unreadable sysfs node yields [] and the corresponding
+//       card simply does not render. One missing subsystem cannot blank the whole page.
+//
+//   Absent tooling is a normal outcome.
+//       No nvidia-smi means no GPU section — not an error. The page is built to be correct
+//       on hardware that lacks any given subsystem.
+//
+//   Missing state files return an explicit unavailable flag.
+//       vv_transcode_sessions() returns ['available' => false] when transcode_state.db does
+//       not exist, so the caller can distinguish "not running" from "zero sessions".
+//
+//   External IP lookups are cached and time-boxed.
+//       curl runs with --max-time and the result is cached 300s, so a slow or unreachable
+//       endpoint cannot stall a page render.
+//
+//   Read-only throughout. Nothing here starts, stops, or reconfigures anything.
+//
+// EXPORTS
+//   System      vv_system_info(), vv_system_resources(), vv_cpu_per_core(), vv_memory_breakdown()
+//   Storage     vv_df(), vv_storage_pools(), vv_array_disks(), vv_disk_io_rates(),
+//               vv_disk_thresholds(), vv_disk_entry(), vv_parity_status()
+//   Hardware    vv_gpu_stats(), vv_gpu_stats_all(), vv_gpu_processes(), vv_ups_stats()
+//   Containers  vv_docker_containers(), vv_docker_stopped()
+//   Network     vv_network_stats()
+//   Remote      vv_remote_hosts_stats()
+//   Misc        vv_transcode_sessions(), vv_log_tail(), vv_parse_bash_array()
+//
+// CONFIGURATION
+//   STATE_DIR              transcode_state.db lives here
+//   HOST*_UNRAID_API_KEY   per-host, read from every host*.conf for remote metrics
+//   VV_CACHE_DIR           ext_ip (300s) and monitor_remote_<host> (written externally)
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+
 require_once __DIR__ . '/config.php';
 require_once __DIR__ . '/unraid_api.php';
 
-// Common helpers shared across all Varaverk pages.
-
 function vv_system_info(): array {
     // ── Shared local reads (always needed regardless of API) ──────────────────
     $ident = @parse_ini_file('/boot/config/ident.cfg') ?: [];