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

@@ -1,4 +1,54 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Partnership page data layer. Enumerates the nodes in the mesh, reaches each over
+//   Tailscale, and reports identity, system summary, sync history and reachability — the
+//   view of "who is in this partnership and are they alive".
+//
+// DESIGN PRINCIPLES
+//   Tailscale is the transport; hostnames resolve through it.
+//       Peers come from `tailscale status`, never from hardcoded IPs. A node that moves
+//       networks stays reachable because nothing here records where it used to be.
+//
+//   The API is tried first, SSH is the fallback.
+//       vv_pt_remote_system() prefers the partner's unraid-api and drops to a single
+//       combined SSH call for version/uptime/load/containers when the API is unavailable.
+//       One round trip either way.
+//
+//   Every remote read is one command.
+//       Partner data is gathered in a single SSH invocation rather than several, because
+//       each one pays full connection setup over a WAN link.
+//
+// OPERATIONAL SAFEGUARDS
+//   SSH is time-boxed, non-interactive, and escaped.
+//       ConnectTimeout, BatchMode=yes so it can never sit waiting for a password, and every
+//       interpolated value passed through escapeshellarg(). A partner that is powered off
+//       costs the configured timeout, not a hung page.
+//
+//   A missing or unreadable key is treated as unreachable.
+//       vv_pt_ssh() returns empty immediately when the key path does not exist, rather than
+//       invoking ssh and letting it fail slowly.
+//
+//   Unreachable partners degrade per node.
+//       Each node is collected independently; one dark host leaves its own card empty and
+//       affects nothing else.
+//
+//   Read-only over SSH. Commands issued are state reads and inventory — this file never
+//   deploys, starts, or stops anything on a partner.
+//
+// EXPORTS
+//   Config    vv_pt_config(), vv_pt_nodes(), vv_pt_ts_peers()
+//   Transport vv_pt_ssh(), vv_pt_ping()
+//   System    vv_pt_local_system(), vv_pt_remote_system()
+//   Sync      vv_pt_sync(), vv_pt_sync_summary(), vv_pt_read_db()
+//   Assembly  vv_partnership_all()
+//
+// CONFIGURATION
+//   HOST*_SSH_KEY              per-host key used for every partner call
+//   HOST*_UNRAID_API_KEY       preferred path before SSH fallback
+//   PARTNERSHIP_ENABLED        whether the partnership layer is active
+//   STATE_DIR / DATA_DIR       sync history and offline counters
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 // Partnership page data helpers
 
 require_once __DIR__ . '/config.php';