Add structured headers to the PHP pages layer

Documents each tab's purpose, what it renders, and which endpoints it polls.
Pages that start with markup get the header in a <?php ?> block so it never
reaches the browser.

Also corrects the layer diagram in README-unraid.md: eight of eleven pages hold
no PHP logic and poll api/ for everything — only auth, monitor and scheduler
require an include/ file directly.
This commit is contained in:
Gmer4Lfe
2026-08-02 00:51:41 -04:00
parent 0b4ff27be4
commit ccc6c742ee
12 changed files with 414 additions and 5 deletions
+33
View File
@@ -1,4 +1,37 @@
<?php
// ═══════════════════════════════════════════════════════════════════════════════════════════════
// PURPOSE
// Setup tab. First-run wizard — walks a fresh install through host identity, credentials,
// API key creation, storage mode, and the readiness checklist.
//
// DESIGN PRINCIPLES
// The checklist is derived, never stored. api/checklist.php re-evaluates real state on each
// load, so a step cannot be marked complete while the thing it checks is actually missing.
//
// Setup state is pushed to partners. Once a node knows who it is, that identity is shared
// through vv_push_setup_state() rather than typed twice.
//
// Detection over interrogation. Where a value can be read from a running service, setup
// reads it instead of asking — the same principle conf_populate.sh follows.
//
// OPERATIONAL SAFEGUARDS
// Existing values are not overwritten by detection. A field already filled in stays as it
// is; the wizard fills gaps rather than resetting a working install.
//
// Ambiguous detection is refused rather than guessed — a container prefix matching two
// containers is reported for manual resolution, never picked arbitrarily.
//
// Credentials entered here are written to host*.conf, which is gitignored. They are never
// committed and never leave the node except through the explicit partner push.
//
// RENDERS
// Step-by-step wizard, readiness checklist, credential entry, API key creation
//
// DEPENDS ON
// api/setup.php wizard state and writes
// api/checklist.php live readiness evaluation
// api/create_api_key.php unraid-api key provisioning
// api/storage.php storage-mode selection
// First-run setup wizard — uniform flow for all hosts.
// Step 1: auto-detect environment + server identity form.
// Step 2: auto-populate + guide + checklist.