The controls map becomes the handbook

It stopped being a controls map somewhere around the display arrangement
and the joystick wizard, and a page called CONTROLS.html is the wrong
place to look for what a file in the game folder does. So:
docs/rp412-controls.html is now docs/rp412-handbook.html and ships as
HANDBOOK.html, titled to match.

The new section answers the question the page could not: what is in the
game folder and which of it is yours. Four files are - environ.ini,
bindings.txt, pilot.cfg, mfd_layout.cfg - and only the first ships, so a
fresh unzip has none of the others and deleting one simply starts that
part over. A second table covers the shipped engine data, which nobody
should edit but everybody eventually wonders about: which INI the gauge
canvas comes from, why there are audio mixer tables for hardware that has
not existed since 1995, and that JOYSTICK.INI is the legacy path rather
than anything the new joystick support reads.

The callout carries the two that actually catch people, both of which
have caught us during this work: environ.ini is applied OVER the
environment, so a variable set in a shell loses to an uncommented line in
the file; and bindings.txt is never overwritten once it exists, which is
what protects a player's edits and also why an update's new defaults do
not appear until it is deleted.

CONTROLS.txt keeps its name. It is the controls half in plain text for
Notepad, which is still exactly what it is, and the README now says so
rather than describing the two as the same thing.

Verified by rendering the packed HANDBOOK.html headless: both tables and
the callout sit in the page's own components, the footer names the new
file, and the version stamp still flows through - the shipped copy reads
4.12.96 from the build it was packed with.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/rp412-handbook.html

@@ -1,4 +1,4 @@
-<title>Red Planet 4.12.7 — Controls</title>
+<title>Red Planet 4.12.7 — Handbook</title>
 
 <style>
   :root {
@@ -755,12 +755,13 @@
 
   <header class="masthead">
     <p class="eyebrow">Virtual World Entertainment · Tesla pod · RP 4.12.7</p>
-    <h1>Red Planet<br>Controls Map</h1>
+    <h1>Red Planet<br>Handbook</h1>
     <p class="lede">
-      Every input the pod answers to, on the gamepad and the keyboard. The
-      keyboard is the pod's button board: the letter and number rows are the
-      MFD banks laid out as they are printed on the panel, and flight moved to
-      the number pad so the board stays free.
+      Every input the pod answers to, on the gamepad and the keyboard, and
+      every file it keeps beside the exe. The keyboard is the pod's button
+      board: the letter and number rows are the MFD banks laid out as they are
+      printed on the panel, and flight moved to the number pad so the board
+      stays free.
     </p>
     <p class="provenance">Generated from the default <code>bindings.txt</code> · all of it rebindable</p>
   </header>
@@ -1312,10 +1313,90 @@
     </div>
   </section>
 
+  <section>
+    <h2>Files beside the exe</h2>
+    <p class="sub">
+      Four files in the game folder are yours. Only one of them ships — the
+      game writes the other three when it first needs them, so a fresh unzip
+      has none of them and nothing is lost by deleting one.
+    </p>
+
+    <div class="tbl-scroll">
+      <table>
+        <caption>Yours to edit</caption>
+        <tbody>
+          <tr>
+            <th class="mono">environ.ini</th>
+            <td>
+              Every engine option, commented in place — displays, renderer,
+              Steam, the podium, the lot. The only one that ships, and the one
+              to read first.
+            </td>
+          </tr>
+          <tr>
+            <th class="mono">bindings.txt</th>
+            <td>
+              Every key, pad button, axis and joystick row. Written with the
+              full documented default layout the first time the game runs.
+            </td>
+          </tr>
+          <tr>
+            <th class="mono">pilot.cfg</th>
+            <td>
+              Your callsign and loadout, saved on the way out of the setup
+              screen so they are there next time.
+            </td>
+          </tr>
+          <tr>
+            <th class="mono">mfd_layout.cfg</th>
+            <td>
+              Where you dragged the windows, and the <code>,noframe</code>
+              flag. Only written when <code>RP412MFDLAYOUT=save</code>.
+            </td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+
+    <div class="callout">
+      <p>
+        <strong>Two that catch people out.</strong>
+        <code>environ.ini</code> is applied <i>over</i> the environment, so a
+        variable you set in a shell loses to an uncommented line in the file —
+        comment the line out rather than fighting it. And
+        <code>bindings.txt</code> is never overwritten once it exists, which
+        is what protects your edits: after an update, <b>delete it</b> to pick
+        up new default bindings.
+      </p>
+    </div>
+
+    <h3>The rest of the folder</h3>
+    <p class="sub">
+      Shipped data the engine reads. Nothing here is meant to be edited, but
+      it is worth knowing what is what.
+    </p>
+
+    <div class="tbl-scroll">
+      <table>
+        <caption>Engine data</caption>
+        <tbody>
+          <tr><th class="mono">RPDPL.INI</th><td>Renderer and scene configuration. Named by <code>L4DPLCFG=</code>, so it can be swapped.</td></tr>
+          <tr><th class="mono">GAUGE\L4GAUGE.INI</th><td>Gauge canvas pages. <code>L4GAUGE=</code> picks one by name — a name that is not in here switches the MFDs off entirely.</td></tr>
+          <tr><th class="mono">GAUGE\L4GAUGE.CFG</th><td>The gauge layout data that page points at.</td></tr>
+          <tr><th class="mono">AUDIO\AUDIO.INI</th><td>Sound banks. <span class="mono">AUDIOMR.INI</span> is the mission-review twin.</td></tr>
+          <tr><th class="mono">JOYSTICK.INI</th><td>The 1995 single-stick calibration, for the legacy <code>L4CONTROLS=DIJOYSTICK</code> path only. Modern sticks are configured in <code>bindings.txt</code> — see above.</td></tr>
+          <tr><th class="mono">*.CFG <span style="color:var(--ink-quiet);font-family:var(--sans)">in AUDIO\</span></th><td>Pod audio-hardware mixer tables. Dead weight on a desktop; kept because the arcade path still reads them.</td></tr>
+          <tr><th class="mono">RPL4.RES</th><td>Resource blob, not text.</td></tr>
+          <tr><th class="mono">steam_appid.txt</th><td>Steam runs under Spacewar (480) until Red Planet has its own AppID.</td></tr>
+        </tbody>
+      </table>
+    </div>
+  </section>
+
   <footer>
     <span>Red Planet 4.12.7</span>
     <span>gitea.mysticmachines.com/VWE/RP412</span>
-    <span>docs/CONTROLS.md · CONTROLS.txt ships with the game</span>
+    <span>docs/rp412-handbook.html · HANDBOOK.html ships with the game</span>
     <span>RGB keyboards mirror the pod lamps · RP412KEYLIGHT=0 to disable</span>
   </footer>
 </div>

pack-dist.ps1

@@ -9,7 +9,7 @@
 #    - libsndfile-1.dll beside the exe; OpenAL32.dll copied from the system
 #      when installed, with oalinst.exe included as the fallback installer
 #    - a desktop environ.ini (PAD;KEYBOARD controls, on-screen plasma)
-#    - start-windowed.bat and a README
+#    - start/joyconfig scripts, HANDBOOK.html, CONTROLS.txt and a README
 #
 #  Usage:  powershell -ExecutionPolicy Bypass -File pack-dist.ps1 [-Zip]
 #
@@ -81,9 +81,8 @@ foreach ($file in 'RPDPL.INI', 'JOYSTICK.INI', 'RPL4.RES', 'TEST.EGG',
     Copy-Item (Join-Path $assets $file) $dist
 }
 
-# The controls map travels with the game (players get the diagrams
-# without needing the repo). Flattened to ASCII so it reads correctly
-# in Notepad - the markdown source keeps its typography.
+# The controls half as plain text, for Notepad. Flattened to ASCII so it
+# reads correctly there - the markdown source keeps its typography.
 $controls = Get-Content (Join-Path $root 'docs\CONTROLS.md') -Raw -Encoding UTF8
 foreach ($pair in @(
         @([char]0x2014, '-'), @([char]0x2013, '-'), @([char]0x2018, "'"),
@@ -93,17 +92,18 @@ foreach ($pair in @(
 }
 Set-Content -Path "$dist\CONTROLS.txt" -Encoding ascii -Value $controls
 
-# The same map as a page, for anyone who would rather look at the
-# diagrams than read them. Its source is the published artifact, which is
-# a fragment - the publisher supplies the document shell - so wrap it to
+# The handbook as a page: the controls map with the diagrams, plus the
+# joystick setup and what every file in the folder is for. Its source is
+# the published artifact, which is a fragment - the publisher supplies
+# the document shell - so wrap it to
 # stand alone: without a doctype the browser drops into quirks mode, and
 # without a charset the typography arrives as mojibake. Written without a
 # BOM so the charset declaration is the only thing speaking.
-$controlsPage = Get-Content (Join-Path $root 'docs\rp412-controls.html') -Raw -Encoding UTF8
+$handbookPage = Get-Content (Join-Path $root 'docs\rp412-handbook.html') -Raw -Encoding UTF8
 # Stamp the shipped copy with the build's own version. The source keeps a
 # readable one for publishing; only "4.12.<n>" is touched, which on this
 # page is always the version and never anything else.
-$controlsPage = [regex]::Replace($controlsPage, '4\.12\.\d+', $version)
+$handbookPage = [regex]::Replace($handbookPage, '4\.12\.\d+', $version)
 $page = @"
 <!doctype html>
 <html lang="en">
@@ -112,12 +112,12 @@ $page = @"
 <meta name="viewport" content="width=device-width, initial-scale=1">
 </head>
 <body>
-$controlsPage
+$handbookPage
 </body>
 </html>
 "@
 [System.IO.File]::WriteAllText(
-    "$dist\CONTROLS.html", $page, (New-Object System.Text.UTF8Encoding $false))
+    "$dist\HANDBOOK.html", $page, (New-Object System.Text.UTF8Encoding $false))
 
 # --- OpenAL runtime --------------------------------------------------------
 # The exe links OpenAL32.dll (32-bit). Prefer shipping the already-installed
@@ -476,9 +476,24 @@ environ.ini is self-documenting: every option ships in the file with
 a comment (Steam networking, keyboard lighting, stick inversion, LAN
 hosting, developer keys, display scaling and radar placement, and more).
 
-CONTROLS.html is the full controls map - open it in a browser for the
-pad, keyboard and pod-panel diagrams. CONTROLS.txt is the same thing as
-plain text.
+HANDBOOK.html is the full manual - open it in a browser for the pad,
+keyboard and pod-panel diagrams, the joystick setup, and what every file
+in this folder is for. CONTROLS.txt is the controls half as plain text.
+
+Four files here are yours. environ.ini is the only one that ships; the
+game writes the rest when it first needs them, so deleting any of them
+simply starts that part over:
+
+  environ.ini      every engine option, commented in place
+  bindings.txt     every key, pad button, axis and joystick row
+  pilot.cfg        your callsign and loadout
+  mfd_layout.cfg   where you dragged the windows (RP412MFDLAYOUT)
+
+Two that catch people out: environ.ini is applied OVER the environment,
+so a variable set in a shell loses to an uncommented line in the file;
+and bindings.txt is never overwritten once it exists, which is what
+protects your edits - so after an update, delete it to pick up any new
+default bindings.
 
 Known prototype notes: pods race untextured (the player1-8 skins come
 from the presets system, not shipped data), and text drawn on the plasma