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

@@ -1,5 +1,52 @@
 <?php
-// Media server session helpers — reads HOST*_EMBY_* / JELLYFIN_* / PLEX_* from host conf.
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Media server session helpers. Discovers the Emby / Jellyfin / Plex instances declared in
+//   the host confs and returns who is currently watching what, for the monitor page's
+//   now-playing panel.
+//
+// DESIGN PRINCIPLES
+//   Conf declares the servers; nothing is probed or auto-detected.
+//       A server appears only because a URL and key were configured for it. Three server
+//       types are supported side by side — this is not an either/or.
+//
+//   Placeholder credentials count as absent.
+//       A key still containing "your-" is a template default that was never filled in, so the
+//       server is skipped rather than queried. Half-configured is treated as unconfigured.
+//
+//   Unknown host reads both host slots.
+//       When vv_detect_host() cannot identify the machine (development, or a hostname that
+//       does not match any HOST<n>), both host confs are tried so the page still shows
+//       something useful instead of nothing.
+//
+//   Session shape is normalised across server types.
+//       Emby, Jellyfin and Plex return quite different payloads; callers get one consistent
+//       structure and do not branch on server type.
+//
+// OPERATIONAL SAFEGUARDS
+//   Every request is time-boxed at 3 seconds.
+//       Session lookups run inside a page render, so a hung media server must not hold the
+//       request open. The stream context timeout is the only thing standing between a
+//       wedged Emby and a page that never returns.
+//
+//   Any failure yields an empty list, never an exception.
+//       Unreachable server, non-JSON body, or an unexpected shape all return [] — the panel
+//       renders empty and the rest of the page is unaffected.
+//
+//   Read-only. Sessions are observed; nothing is stopped, transcoded, or messaged.
+//
+// EXPORTS
+//   vv_discover_media_servers()   configured Emby / Jellyfin / Plex instances for this host
+//   vv_media_sessions()           normalised active sessions across all discovered servers
+//   vv_fetch_jf_sessions()        Jellyfin-specific fetch
+//   vv_fetch_plex_sessions()      Plex-specific fetch
+//   vv_media_conf_scalar()        conf scalar reader used by the above
+//
+// CONFIGURATION
+//   HOST*_EMBY_URL / _EMBY_API_KEY / _EMBY_CONTAINER
+//   HOST*_JELLYFIN_URL / _JELLYFIN_API_KEY / _JELLYFIN_CONTAINER
+//   HOST*_PLEX_URL / _PLEX_TOKEN
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 
 require_once __DIR__ . '/config.php';