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

@@ -1,4 +1,47 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Watchdog data endpoint. Every watchdog's current state for every node in one document —
+//   resource, docker, system, storage, network and stability — together with the thresholds
+//   each one is judging against, for the watchdog tab's poll.
+//
+// DESIGN PRINCIPLES
+//   Thin transport. State-file parsing and threshold resolution live in
+//   include/watchdog.php; this file only sets the content type and encodes.
+//
+//   Thresholds ship with the state, not separately.
+//       vv_wd_all() resolves every threshold from master.conf into the same payload as the
+//       counters they apply to. A strike count means nothing without the limit it is counted
+//       against, so the page never has to fetch the two independently and risk mismatching
+//       them across a conf edit.
+//
+//   No parameters. Which watchdogs exist is fixed by the codebase, not by the request.
+//
+// OPERATIONAL SAFEGUARDS
+//   Read-only. Nothing here clears a strike, lifts a skip-list entry, restarts a container,
+//   or cancels a pending reboot. The watchdogs own their own state; this endpoint reports it.
+//
+//   Absent counters are reported quiet, not alarming.
+//       A watchdog that has not yet written state reads as zero rather than unknown, so a
+//       fresh boot does not light the page up with false strikes.
+//
+//   Thresholds fall back to the shipped defaults.
+//       Every vv_wd_scalar() lookup has a ?: default, so a master.conf that is mid-edit or
+//       missing a key still yields a coherent payload instead of comparing counters against
+//       zero and declaring everything critical.
+//
+//   Remote collection degrades per node — one unreachable partner drops that node's card and
+//   leaves the local host and every other partner intact.
+//
+// REQUEST
+//   GET, no parameters
+//
+// RESPONSE
+//   vv_wd_all() verbatim — per-node watchdog state plus the resolved threshold set
+//
+// DEPENDS ON
+//   include/watchdog.php   vv_wd_all()
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/watchdog.php';
 echo json_encode(vv_wd_all());