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

@@ -1,5 +1,57 @@
 <?php
-// Arr (Sonarr / Radarr / Lidarr) data helpers
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Arr data layer for the arrs page. Discovers every Sonarr / Radarr / Lidarr instance
+//   declared in the host confs, fetches live library counts and queue state from each, and
+//   attaches the cleanup / discovery / sync / recovery statistics the scripts have recorded.
+//
+// DESIGN PRINCIPLES
+//   Each host builds its own payload; nobody queries a partner's arrs.
+//       vv_arrs_local_node() is what remote_arr_cache_writer.sh invokes over SSH on the
+//       partner, so the partner assembles its own node using its own local URLs and keys.
+//       This host therefore never holds credentials for a remote's arrs, and no path mapping
+//       between hosts is involved.
+//
+//   Live for local, cache for remote.
+//       vv_arrs_all() calls the local node live and reads remote nodes from the JSON the
+//       cache writer left behind. Cross-host work happens on a 2h timer, never in a page load.
+//
+//   Instances come from conf, not from probing.
+//       vv_discover_arrs() enumerates what the host confs declare. An arr that exists but is
+//       not configured is intentionally invisible — conf is the source of truth.
+//
+// OPERATIONAL SAFEGUARDS
+//   Every arr HTTP call is time-boxed.
+//       vv_arr_http() defaults to a 4s timeout and returns null on any failure. One
+//       unreachable instance costs four seconds, not the page.
+//
+//   A missing remote cache is reported, not faked.
+//       No cache file yields an explicit cache_miss => true with an empty arrs list, so the
+//       page can say "not yet collected" rather than implying the partner has no libraries.
+//
+//   Cached remote nodes carry their own age.
+//       cache_age is attached to every cached node so the UI can show staleness instead of
+//       presenting 2-hour-old counts as current.
+//
+//   Read-only. Statistics are parsed from the databases the scripts write; nothing here
+//   triggers a scan, cleanup, or import.
+//
+// EXPORTS
+//   Discovery   vv_discover_arrs(), vv_arr_known_hosts(), vv_arr_node_names()
+//   Fetch       vv_arr_http(), vv_fetch_arr_live()
+//   Statistics  vv_arr_cleanup_stats(), vv_arr_discovery_stats(), vv_arr_sync_stats(),
+//               vv_arr_recovery_stats()
+//   Assembly    vv_arrs_local_node()  ← called over SSH by remote_arr_cache_writer.sh
+//               vv_arrs_all()         ← local live + remote cached
+//
+// CONFIGURATION
+//   HOST*_SONARR_URL / _RADARR_URL / _LIDARR_URL              per-instance endpoints
+//   HOST*_SONARR_API_KEY / _RADARR_API_KEY / _LIDARR_API_KEY  per-instance keys
+//   HOST*_SONARR_TV_ROOT / _RADARR_MOVIES_ROOT / _LIDARR_MUSIC_ROOT
+//   ARR_SYNC_SONARR_PORT / _RADARR_PORT / _LIDARR_PORT        used to reach partner instances
+//   DATA_DIR      arr_cleanup_stats.db, arr_recovery_stats.db, <type>_discovery_history.db
+//   VV_CACHE_DIR  arrs_remote_<host>.json — written by remote_arr_cache_writer.sh
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 
 require_once __DIR__ . '/config.php';