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

@@ -1,4 +1,83 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Setup checklist. Evaluates what this host still needs before it is fully configured —
+//   identity, conf, API and SSH keys, service discovery, media keys, and partnership state —
+//   and names the action that fixes each gap.
+//
+// OPERATIONAL MODEL
+//   Derived, never stored. Every item is computed from the conf files and the setup state on
+//   each request, so the checklist cannot go stale or disagree with reality. There is no
+//   "completed" flag anyone could tick.
+//
+//   The item list is not fixed. Emby and Jellyfin checks appear only once their container is
+//   configured; the master.conf pull appears only on a partner host; partnership appears only
+//   once a HOST2 is named. A checklist that listed everything would tell a single-host
+//   install it was permanently incomplete.
+//
+//   Items carry an action name, not a URL. The page maps create_key, ssh_setup, run_populate,
+//   pull_master and onboard onto the right endpoint or instruction — so this file describes
+//   what is wrong, and the UI owns how to fix it.
+//
+// DESIGN PRINCIPLES
+//   Each check answers the narrowest useful question.
+//       The SSH item tests that the configured path exists on disk, not merely that a path is
+//       set — a path set to a file that was never generated is the actual failure mode, and
+//       the detail text distinguishes the two cases.
+//
+//   Auto-populate is satisfied by any one service.
+//       The check passes on the first arr key or media container found. Requiring all of them
+//       would leave the item permanently red on a host that legitimately runs only some.
+//
+//   Partnership reports its phases separately.
+//       Phase 1 done with phase 2 outstanding is its own message, because the fix is to go
+//       finish onboarding on the other host — not to re-run anything here.
+//
+//   State keys are read case-insensitively.
+//       Both HOST2_PHASE1_DONE and host2_phase1_done are accepted, because the state file has
+//       been written by both the shell layer and the PHP layer over its life.
+//
+//   complete is derived from the items, not tracked.
+//       A single strict in_array(false, …) over the item results, so the summary can never
+//       disagree with the list it summarises.
+//
+// OPERATIONAL SAFEGUARDS
+//   Read-only. This endpoint diagnoses and never fixes — every remedy is a separate,
+//   explicitly invoked action. That separation is what makes it safe to poll.
+//
+//   No input at all. There are no parameters, so there is nothing to validate and no way to
+//   ask about a host other than this one.
+//
+//   An unidentified host degrades to a report rather than an error.
+//       vv_detect_host() returning 'unknown' is handled at every use — the host conf is not
+//       read, and the identity and host_conf items say so explicitly. That is the exact state
+//       a fresh install is in, and it is the checklist's job to describe it.
+//
+//   Every conf read is defaulted.
+//       vv_read_conf_raw() returns empty for a missing file and every scalar lookup is
+//       trimmed with a ?? fallback, so a partial or absent conf yields items marked not-ok
+//       rather than a fatal that would blank the whole panel.
+//
+//   Key presence is reported, key values never are.
+//       The API, SSH, Emby and Jellyfin items report only whether a value is set — and for
+//       SSH, the basename of the path. No credential is returned.
+//
+//   Missing is reported as missing, never as fine.
+//       Every item defaults to ok:false and is only set true by a positive test. A check that
+//       cannot run reports the gap it could not rule out.
+//
+// REQUEST
+//   GET, no parameters
+//
+// RESPONSE
+//   {"ok":true,"complete":bool,"host_id":"host<n>|unknown",
+//    "items":[{"id","label","ok","detail","action"?}, …]}
+//   action is present and non-null only when there is a remedy the UI can invoke.
+//
+// DEPENDS ON
+//   include/config.php   vv_detect_host(), vv_read_conf_raw(), vv_parse_conf_scalar(),
+//                        vv_setup_state_read(), CONF_DIR
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';