Clarify 16-pod design: hardware max, fixed 16-line positional output contract

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/ARCHITECTURE.md

@@ -117,9 +117,13 @@ Gated by the `GroupAvalible` config flag.
 Notes:
 - `pqs.sql` is the canonical schema; `dbbuild.sql` is an older SQLyog dump with
   sample data.
-- "Number of pods" is duplicated in three places (`pqs_gameconfig.numpods`,
+- The **16 pod booleans** (`pod01`..`pod16`) are a fixed structure, not a
-  the 16 booleans in `pqs_pods`, and each `pqs_mission.MissionSize`) and kept
+  limitation to normalize away: 16 is the max cockpits one game console can
-  in sync manually by `console.php` on every config save.
+  control, and each pod is toggled individually because the console addresses
+  every position regardless of whether it is online/operational (see
+  `getFSplayers.php`). `MissionSize` is the *count* of active pods; the booleans
+  say *which* ones. `pqs_gameconfig.numpods` caches that count. `console.php`
+  keeps these in sync on every config save.
 
 ## 6. File-by-file reference
 
@@ -159,8 +163,12 @@ Consumed by the operator's **AutoHotkey scripts** (not the pods directly — see
 §4 "How the mission reaches the pods"). The AHK scripts are **not yet recovered**.
 - **`getFSgame.php`** — emits the next mission's settings as newline-delimited
   values (gametype, map, visibility, weather, … cameraship) for AHK to read.
-- **`getFSplayers.php`** — emits 16 CSV lines (one per pod slot):
+- **`getFSplayers.php`** — **always emits exactly 16 CSV lines** (one per pod
-  `active,callsign,rosterNum,team,unit` — the pod loadout for the next mission.
+  slot): `active,callsign,rosterNum,team,unit` — the pod loadout for the next
+  mission. The line count is fixed at 16 by design: the game console addresses
+  all 16 cockpit positions **positionally** whether or not each is online, so an
+  inactive pod is sent as a zeroed line (`0,0,0,0,0`) rather than omitted. 16 is
+  the maximum number of cockpits one game console can currently control.
 - **`playFSTrainer.php`** — *referenced by `docs/get.py` but missing from the
   repo*; was polled by a Raspberry Pi to trigger the trainer video.
 
@@ -194,7 +202,11 @@ These matter most for the "improve vs. rewrite" decision.
   overfill a pod bay** ("Containment Bay OVERLOADED" is literally a handled UI
   state). `numplayers` is a manually-maintained counter that can drift from the
   actual `COUNT(*)` in `pqs_queue`.
-- Pod-count is denormalized across three tables and reconciled by hand.
+- Pod state is spread across `pqs_pods` (which 16 are active), `MissionSize`
+  (the count), and `pqs_gameconfig.numpods` (a cached count), reconciled by
+  `console.php`. Note the fixed count of **16 is intentional** — the hardware
+  max per console — so this is a sync concern, not a "make pod count dynamic"
+  concern.
 
 **Security (mitigated only by the air gap)**
 - **SQL injection is pervasive** — nearly every query interpolates `$_GET`/
@@ -211,7 +223,11 @@ These matter most for the "improve vs. rewrite" decision.
 - Deprecated `mysql_error()` calls remain alongside `mysqli_*` (would fatal on
   PHP 7+). The code targets an EOL PHP 5.x runtime.
 - 16 pods are hard-coded as `pod01..pod16` everywhere (schema, console, FS
-  output) — changing pod count is a code edit, not config.
+  output). This is **intentional** — 16 is the hardware max per game console and
+  the console requires all 16 positions in a fixed order — but it does make the
+  code verbose (16 near-identical branches in `console.php` and
+  `getFSplayers.php`). A loop over a pod count of 16 would be cleaner without
+  changing the contract.
 - Display refresh is fixed-interval full-fragment polling (no change detection
   except the one infopanel flag).
 - Inline `<font>` tags, table layouts, and absolute pixel sizes throughout.
@@ -239,7 +255,8 @@ If **improving in place**, the highest-value, lowest-risk fixes first:
 2. Parameterize all queries (mysqli prepared statements) and remove `DEBUG:`
    output.
 3. Centralize DB access into one include; replace remaining `mysql_*` calls.
-4. Make pod count and timezone configuration-driven, not hard-coded.
+4. Make timezone configuration-driven; collapse the 16 repeated pod branches
+   into a loop (keep the fixed 16-slot output contract — see below).
 
 If **rewriting from scratch**, preserve section 4's lifecycle and section 5's
 tables as the spec. Treat `getFSgame.php` / `getFSplayers.php` output formats as
@@ -247,5 +264,8 @@ a **hard contract**, but note the real contract is defined by the **unrecovered
 AutoHotkey scripts** that scrape them and keyboard-inject into the game console.
 **Recovering those AHK scripts is a prerequisite** to safely changing anything
 about how missions reach the pods — without them the exact expected output
-layout (field order, line count, delimiters) can only be inferred from the PHP.
+layout (field order, delimiters) can only be inferred from the PHP. One part of
+the contract is already known and must be kept: `getFSplayers.php` **always
+returns exactly 16 lines** in fixed pod order, inactive pods zeroed rather than
+omitted, because the game console addresses all 16 positions positionally.
 ```