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

@@ -1,4 +1,64 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   The scheduler's engine. Owns schedule.json, regenerates the Varaverk cron file, builds
+//   the script library shown on the scheduler page, and reads each script's own header to
+//   describe it in the UI.
+//
+// OPERATIONAL MODEL
+//   Writes state that changes what the machine does on a timer. A bad write here does not
+//   break a page — it changes which jobs run, or stops them running at all.
+//
+// DESIGN PRINCIPLES
+//   The bash header is the description; the UI does not keep its own copy.
+//       vv_script_description() parses the PURPOSE (or DESCRIPTION) block out of the script
+//       itself. A script's documentation and its listing cannot drift apart, because they are
+//       the same text. This is the live consumer of the repo-wide header convention.
+//
+//   schedule.json is per-host and never synced.
+//       What a node runs is a property of that node. Syncing it would hand a partner this
+//       host's job list, which is exactly wrong under a mutual-redundancy model.
+//
+//   The cron file is regenerated, never edited in place.
+//       vv_cron_rebuild() emits the whole file from schedule.json. Incremental edits are how
+//       a cron file accumulates entries nobody can account for.
+//
+//   Scripts are discovered from conf arrays and the filesystem.
+//       Orchestrator job lists come from master.conf; user scripts are any *.sh dropped in
+//       CUSTOM_SCRIPTS_DIR. Neither requires registration in a second place.
+//
+// OPERATIONAL SAFEGUARDS
+//   The cron file must stay in /boot.
+//       update_cron merges plugin *.cron files from there into /etc/cron.d/root. Relocating
+//       it silently stops every scheduled job — nothing errors, the jobs simply never fire.
+//
+//   The legacy direct cron file is removed on rebuild.
+//       A file left over from before the update_cron migration would fire every job a second
+//       time. Rebuild deletes it rather than assuming it is gone.
+//
+//   Custom scripts live outside the git repo.
+//       CUSTOM_SCRIPTS_DIR points at the User Scripts plugin's own storage, so a user's
+//       scripts are never touched by a pull and never committed by accident.
+//
+//   Shell arguments are escaped where the schedule feeds a command line.
+//
+// EXPORTS
+//   Schedule   vv_schedule_load(), vv_schedule_save(), vv_schedule_update(),
+//              vv_schedule_update_batch(), vv_cron_rebuild(), vv_script_suggested_cron()
+//   Library    vv_script_library(), vv_tools_scripts(), vv_custom_scripts(),
+//              vv_rsync_standalone(), vv_orch_conf_arrays(), vv_job_tree(), vv_script_children()
+//   Headers    vv_script_header(), vv_script_header_clean(), vv_script_description(),
+//              vv_readme_section(), vv_parse_user_script_template()
+//   Conf       vv_conf_script_map(), vv_conf_flag_value(), vv_conf_flag_set(),
+//              vv_conf_toggle_script(), vv_parse_conf_array(), vv_parse_conf_array_full()
+//   Paths      vv_job_flags(), vv_job_log_path(), vv_job_stat_path(), vv_folders_load()
+//
+// CONFIGURATION
+//   SCHEDULE_FILE        SCRIPTS_DIR/schedule.json — per-host, never synced
+//   CRON_FILE            /boot/config/plugins/varaverk/varaverk.cron — must stay in /boot
+//   CUSTOM_SCRIPTS_DIR   user-authored scripts, outside the repo
+//   master.conf          orchestrator job arrays drive the script tree
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 // Scheduler — manages schedule.json and the Unraid plugin cron file.
 // schedule.json is per-host, never synced.