Document the PHP api layer and fix what documenting it exposed

Writing down what each endpoint actually guarantees made the places it
didn't obvious — shell arguments reaching a crontab or a bash -c
unescaped, master.conf written without tmp+rename, and conf edits that
could be saved without ever being parsed.

Plugin/unraid/api/partnership.php

@@ -1,4 +1,40 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Partnership data endpoint. The whole partnership picture in one document — known hosts,
+//   reachability, SSH trust, conf-sync state and the shared-service inventory — for the
+//   partnership tab's poll.
+//
+// DESIGN PRINCIPLES
+//   Thin transport. Host enumeration, SSH probing and trust evaluation live in
+//   include/partnership.php; this file only sets the content type and encodes.
+//
+//   No parameters. The partnership is defined by conf, not by the request, so there is
+//   nothing for a caller to select and nothing to validate.
+//
+// OPERATIONAL SAFEGUARDS
+//   Read-only. Nothing here installs a key, edits a conf, or changes a partner's state.
+//   Every mutating partnership operation is a separate endpoint (partnership_settings.php,
+//   setup.php) so that a page poll can never alter trust.
+//
+//   An unreachable partner is a reported condition, not a failure.
+//       vv_partnership_all() returns each host with its own reachability result, so a dark
+//       node renders as unreachable while the rest of the page stays accurate. The tab has to
+//       stay useful precisely when a partner is down.
+//
+//   Probes are time-boxed inside the library, so this endpoint cannot outlast them.
+//       vv_pt_ssh() runs with ConnectTimeout (4s default) and BatchMode=yes, so a partner
+//       that is powered off costs that timeout and can never sit waiting for a password.
+//
+// REQUEST
+//   GET, no parameters
+//
+// RESPONSE
+//   vv_partnership_all() verbatim — {"config":…,"nodes":…,"sync":…,"ts":epoch}
+//
+// DEPENDS ON
+//   include/partnership.php   vv_partnership_all()
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/partnership.php';
 echo json_encode(vv_partnership_all());