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

@@ -1,6 +1,62 @@
 <?php
-// Config file parser and writer.
-// Reads master.conf and the appropriate host*.conf based on running host.
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Root of the PHP layer. Locates the Varaverk installation, parses master.conf plus this
+//   host's own host*.conf into a flat array, and provides host identity, remote resolution,
+//   and the tmpfs payload cache. Every other include/ file requires this one.
+//
+// DESIGN PRINCIPLES
+//   varaverk.cfg is the single source of truth for location.
+//       SCRIPTS_DIR is read from it; CONF_DIR, DATA_DIR, STATE_DIR and DEPLOY_DIR are all
+//       derived. Storage-mode migration rewrites that one value and every path follows.
+//
+//   Host identity mirrors bash detect_hosts() exactly.
+//       Same HOST<n> / HOST<n>_NAME matching, same 15-char NetBIOS truncation fallback. The
+//       two implementations must agree — a page that disagrees with the scripts about which
+//       host it is on is worse than one that cannot tell.
+//
+//   Conf parsing resolves ${VAR} in two passes.
+//       Bash expands at runtime; PHP reads the file literally. Pass 1 substitutes
+//       ${SCRIPTS_DIR} from the PHP-side constant, pass 2 resolves remaining ${VAR} against
+//       the already-parsed set. Without this, every derived path arrives as a literal string.
+//
+//   Read-only with respect to behaviour.
+//       This file parses conf and reports; it does not decide policy. Callers own that.
+//
+// OPERATIONAL SAFEGUARDS
+//   Ambiguous truncated hostnames are refused, never guessed.
+//       The 15-char fallback accepts a match only when exactly one configured host qualifies.
+//       Two plausible candidates return 'unknown' rather than picking one — a wrong host
+//       identity silently routes local work to a remote node.
+//
+//   Cache writes are atomic.
+//       vv_cache_write() writes .tmp then rename()s into place, so a concurrent reader sees
+//       either the old payload or the new one, never a half-written file.
+//
+//   Cache reads are age-gated and fail to null.
+//       Past $maxAge, vv_cache_read() returns null rather than stale data. Callers treat null
+//       as "no cache" and fall back to a live call — a missing cache can never be the reason
+//       a page fails to render.
+//
+//   Unknown host degrades instead of guessing.
+//       vv_detect_host() returns 'unknown' and vv_conf_vars() then loads master.conf alone.
+//       Shared config still resolves; host-specific values are simply absent.
+//
+// EXPORTS
+//   Identity      vv_detect_host(), vv_get_hostname(), vv_is_owner(), vv_known_hosts()
+//   Config        vv_conf_vars(), vv_read_conf_raw(), vv_write_conf_raw(), vv_get_conf_files()
+//   Parsing       vv_parse_conf_scalar(), vv_parse_kv_db(), vv_format_uptime()
+//   Remote        vv_resolve_tailscale_ip(), vv_remote_state_cmd(), vv_local_ip()
+//   Setup state   vv_setup_state_read/_write(), vv_push_setup_state(), vv_push_master_conf()
+//   Cache         vv_cache_read(), vv_cache_write()
+//   Unraid API    vv_unraid_api_query(), vv_auto_create_api_key()
+//
+// CONFIGURATION
+//   varaverk.cfg      SCRIPTS_DIR, CUSTOM_SCRIPTS_DIR
+//   master.conf       HOST<n> / HOST<n>_NAME — host identity
+//   host*.conf        HOST*_SSH_KEY — used for setup-state and conf push
+//   VV_CACHE_DIR      /tmp/vv_cache (tmpfs — RAM speed, cleared on reboot)
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 
 define('PLUGIN_CFG',  '/boot/config/plugins/varaverk/varaverk.cfg');