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

@@ -1,4 +1,77 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   The auth-stack control layer. Drives the three services behind every protected hostname:
+//   Nginx Proxy Manager (proxy hosts and certificates), LLDAP (users and groups), and
+//   Authelia (access-control rules). Read and write.
+//
+// OPERATIONAL MODEL
+//   The only include/ file that routinely mutates external state. Everything else here
+//   reports; this one creates users, rewrites proxy hosts, edits Authelia's YAML, and
+//   restarts the Authelia container. Treat every function below as load-bearing.
+//
+// DESIGN PRINCIPLES
+//   Credentials come from conf, never from the page.
+//       NPM and LLDAP credentials are read from host*.conf. The browser never sees them and
+//       never supplies them.
+//
+//   Tokens are cached per session, not per request.
+//       NPM and LLDAP tokens are held in $_SESSION with a 23-hour expiry, so a page that
+//       makes twelve calls authenticates once. Expiry is checked before reuse.
+//
+//   Authelia is edited as text, not parsed and re-emitted.
+//       Only the access_control block is rewritten, in place. Round-tripping the whole YAML
+//       through a parser would silently reformat and drop comments from a file that is
+//       hand-maintained and synced between hosts.
+//
+//   The owner host is the source of truth for auth config.
+//       Changes are made here and reach the partner through Critical-Data sync, not by
+//       writing to two hosts from the browser.
+//
+// OPERATIONAL SAFEGUARDS
+//   The Authelia config write is atomic and reversible up to the last step.
+//       Existence check → read → regex replace → write .vv.tmp → rename() into place. A
+//       failure at any stage returns an error and leaves the original untouched; a failed
+//       rename unlinks the temp file rather than leaving it beside the real config.
+//
+//   A missing config file is refused, never created.
+//       Both the read and write paths return 'Config not found' rather than writing a fresh
+//       file. Creating one would hand Authelia a config with no rules and a default policy —
+//       an accidental open door. See HOST*_AUTHELIA_CONFIG below.
+//
+//   The container restart is shell-escaped.
+//       The container name comes from conf and is passed through escapeshellarg(), so a
+//       malformed conf value cannot become a command.
+//
+//   Auth failure is reported, not retried into a lockout.
+//       A failed token fetch returns an _err string immediately. Nothing loops on bad
+//       credentials against a service that may rate-limit or lock the account.
+//
+//   Every remote call has a timeout, and every function returns a structured result —
+//   ['ok' => bool] or an _err key — so no caller has to distinguish an exception from a
+//   legitimately empty list.
+//
+// EXPORTS
+//   Config    vv_auth_conf()
+//   NPM       vv_npm_list_proxies(), vv_npm_list_certs(), vv_npm_create_proxy(),
+//             vv_npm_update_proxy(), vv_npm_delete_proxy(), vv_npm_toggle_proxy()
+//   LLDAP     vv_lldap_list_users(), vv_lldap_list_groups(), vv_lldap_create_user(),
+//             vv_lldap_update_user(), vv_lldap_delete_user(), vv_lldap_set_password(),
+//             vv_lldap_create_group(), vv_lldap_delete_group(),
+//             vv_lldap_add_to_group(), vv_lldap_remove_from_group()
+//   Authelia  vv_authelia_read_rules(), vv_authelia_write_rules()
+//
+// CONFIGURATION
+//   HOST*_NPM_URL         admin API — port 7818. Port 81 is the partnership WebUI port
+//                         (HOST*_PARTNERSHIP_AUTH_WEBUIS), not the API. Easy to confuse.
+//   HOST*_NPM_USER / _NPM_PASS
+//   HOST*_LLDAP_URL / _LLDAP_USER / _LLDAP_PASS
+//   HOST*_AUTHELIA_CONFIG     path to configuration.yml. Lives in the Critical-Data share so
+//                             it is covered by the 30-minute auth sync — not under
+//                             /mnt/user/appdata, which is not synced.
+//   HOST*_AUTHELIA_CONTAINER  restarted after a successful rules write
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+
 require_once __DIR__ . '/config.php';
 
 // ── Config ────────────────────────────────────────────────────────────────────