docs: fix reconciliation date in GE-ENV-PROBES.md (2026-09-28, not 10-07)

release/v0.4.0: v0.4.0 feature + fidelity release (widescreen, aim system, rebinding, crosshair, rumble, options rebuild, 60 fps fix)

.github/pull_request_template.md

@@ -13,9 +13,14 @@ rules there are non-negotiable.
 
 ## Scope check
 
-- [ ] No changes under `src/` or `include/` — **or** the only changes are the
-      narrow `#ifdef PORT` ABI exception (CONTRIBUTING.md rule 2), and each is
-      documented in `docs/porting-notes.md` / `docs/dev/findings.md`.
+- [ ] No changes under `src/` or `include/` — **or** the only changes are
+      the narrow `#ifdef PORT` ABI exception (CONTRIBUTING.md rule 2),
+      checked against `docs/porting-notes.md` §A1, and documented in
+      `docs/dev/findings.md` (§F/D3x).
+- [ ] If this PR contains a genuine `src/game` behavior change (not an
+      ABI/layout fix): an explicit rule-2 sign-off was granted
+      (`docs/dev-process.md` §7) and is recorded in a
+      `RULE-2-SIGNOFF`-tagged `docs/dev/findings.md` entry linked here.
 - [ ] `Makefile`, `tools/`, `rsp/`, `ld/` untouched (N64 build).
 - [ ] If `CMakeLists.txt` `REGION_DEFS` changed, it still matches the N64
       `Makefile` per-region macro set exactly.

.github/release-notes.md

@@ -1,139 +1,333 @@
-## GoldenEye 007 PC Port <version>
+# GoldenEye 007 PC Port — v0.4.0
 
 <p align="center">
-  <img src="https://github.com/jkdansereau/goldeneye-pc-port/raw/v0.2.0/docs/media/goldeneye-gh-preview.gif" width="480"
-       alt="~32 s gameplay montage from live play sessions (no audio track)">
+  <img src="https://github.com/jkdansereau/goldeneye-pc-port/raw/v0.4.0/docs/media/goldeneye-gh-preview.gif" width="480"
+       alt="~24 s gameplay montage from live v0.4.0 play sessions, opening on the Runway tank (no audio track)">
 </p>
 
-> The full single-player campaign runs at a steady 60 fps with audio (music +
-> SFX) playing throughout, on Windows and Linux including Steam Deck, and it
-> is completable end to end: the whole campaign has been playtested through
-> all 21 missions (Agent difficulty). It's an early public cut: all 21 solo
-> missions load and run crash-free, but the known issues below are real;
-> feedback is very welcome.
+Platforms: **Windows x86-64** and **Linux x86-64 (including Steam Deck)**.
+Region: **NTSC-U (US) only** — see [Things to know](#things-to-know).
 
-### What's new since v0.1.0
+v0.4.0 is a large feature and fidelity release. The full campaign runs at a
+steady 60 fps with music and SFX throughout, and has been playtested end to
+end (all 20 missions, Agent difficulty) on Windows and on Steam Deck with a
+physical controller. This is a pre-1.0 release: the known issues below are
+real, and some areas (multiplayer, PAL/JP, HD assets) are still ahead of us.
 
-- **Drop-in ROM, no tooling**: unpack the bundle, drop your NTSC-U (US) ROM
-  in `data/`, launch; the first run generates the derived assets
-  automatically. No Python, no installer, nothing to set up.
-- **Steady 60 fps** in normal play (the software RSP runs off the presentation
-  critical path); `Video.DisplayFPS` in the F10 overlay shows it.
-- **Audio**: in-level music and sound effects throughout (the alpha was
-  silent). A handful of tracks have wrong-sounding instruments (below).
-- **Mouse**: click-to-lock capture (click to grab, ESC to release) with a
-  proportional GEPD-style aim mode; sensitivity / Y-inversion / aim-turn split
-  tunable in `ge007.ini` or the F10 overlay. The legacy always-grab mode is
-  gone.
-- **Rendering**: outdoor skies render correctly; water no longer renders
-  green/pulsing; reflective surfaces (glass, chrome weapon skins) work.
-- **Crash fixes**: the two v0.1.0-era crashing levels (Bunker ii, Statue) and
-  the AI-pacing bug that broke Cradle are fixed and playtest-verified: all 21
-  solo missions load and run crash-free. Also fixed: the Steam Deck / Linux
-  Facility crash triggered by walking into the crouch-forcing spot at the
-  level's opening (D253); this also revives the auto-crouch and ladder
-  signals, which were dead on PC before.
-- **QoL**: F10 in-game options overlay (fullscreen, resolution, frame cap,
-  MSAA, texture filtering, FOV/draw distance, sensitivity), F12 screenshot.
-- **Sharper defaults out of the box**: draw distance and LOD swap distance now
-  default to 150% of the authored N64 values, so props no longer fade in just
-  before they become visible (Dam's alarms and wall switches being the tell);
-  F10 → *Draw distance* / *LOD distance* set back to 100 restores the
-  console-authentic look. MSAA now defaults to 4× instead of off.
-- **All-unlocked toggle**: F10 → *All unlocked* makes all 21 solo levels
-  selectable at every difficulty from the first launch, adds 007 mode, and
-  fully populates the cheat menu. It is off by default (faithful N64
-  progression). No *active* cheats are enabled either way (weapons remain
-  per-mission pickups, as on N64).
-- **Steam Deck first-run preset**: on SteamOS the first launch seeds
-  Deck-friendly defaults (native 1280×800 fullscreen, VSync, MSAA 4, 150%
-  draw/LOD distance); an existing `ge007.ini` always wins. Two more F10 rows:
-  *No hit flash* (suppresses the damage-flash overlay) and *Skip intro*.
-- **Modern dual-stick controller layout** (the scheme used by the console
-  re-releases): left stick move/strafe, right stick look, right trigger fire,
-  left trigger aim, A/X use, B/Y crouch/cancel, **RB/LB cycle weapons**.
-- **Linux / Steam Deck**: the Linux bundle now ships its own SDL2, so it runs
-  as-is on any distro, and sideloads onto a Steam Deck with nothing
-  installed. Saves and F10 settings now persist no matter which directory you
-  launch from (previously Linux wrote them relative to the launch directory
-  only, so they silently failed elsewhere; D256); the options overlay is
-  fully gamepad-driven on the Deck.
+---
 
-### Known issues
+## New features
 
-- **Cutscenes still glitch, mostly with James Bond**: in scripted sequences
-  Bond is the one who gets misplaced, hovers, or spins; the other actors are
-  fine for the most part now. The Dam level-end cutscene is racy (D243).
-  Still the most visible gap in this release.
-- **Particle colours cycle through a rainbow palette**: bullet-impact sparks
-  and lingering smoke/explosion residue drift through the hues over time
-  instead of holding their intended grey/orange palette (D252).
-- Water on `IsWater` levels shows a moving seam between two patterns (D245);
-  thin pixel strips at the left/right screen edges at non-integer window
-  scales (D246).
-- The front-end **Nintendo logo renders as two white blobs**, and the
-  Rareware logo is close but its texture filtering looks off (D75).
-- The F10 overlay's **bottom row duplicates whatever item is currently
-  selected** (e.g. the MSAA value appears both on its own row and again at
-  the panel bottom); earlier builds showed it as an intermittent 4K-
-  fullscreen ghost of the top row.
-- **Steam Deck: one intermittent crash remains**: the v0.1.0-era Facility
-  crash is confirmed fixed on Deck hardware, but a SIGSEGV can occasionally
-  occur during heavy firefights (D255; seen on Bunker and Frigate). The
-  faulting-register capture in `ge007.crash.log` has pinned it: an object
-  record whose model reference is NULL while the record is still active;
-  i.e. something in a mid-firefight destruction leaves the record live one
-  tick too long. We're tracking down the exact destruction path; more Deck
-  playtime across levels is welcome; please report any Deck-specific faults.
+### Native widescreen *(on by default)*
 
-### Downloads
+The world now renders natively at your display's aspect ratio instead of
+stretched 4:3: geometry is undistorted (wider view, same vertical FOV), the
+in-level HUD keeps its shape and anchors to the screen edges, and the 4:3
+front-end menus and ending-credits sequence are pillarboxed. Turn it off
+with the **`Native widescreen`** toggle (F10 → Display) to restore the old
+stretched frame. (D334/D335)
+
+### A true, stable 60 fps
+
+v0.3.0 could settle at 30 fps game-wide on some setups. The cause was a
+pointer-width bug in the game's frame scheduler: a "present every frame"
+flag was read back at a hardcoded byte offset that the 32→64-bit transition
+silently moved, so the render path ran on the audio client's every-other-
+frame cadence. Fixed at the root; the game now holds a rock-stable 60 fps
+(measured with the in-game FPS readout) on both platforms. (D248)
+
+### A complete aim system for mouse *and* controller
+
+- **`Aim style`** — **N64** (default): the crosshair deflects and the
+  camera follows once it reaches the screen edge. **Centred (PC)**: the
+  crosshair is fixed at screen center and your mouse — or your right stick —
+  moves the camera directly. In v0.3.0 the centred mode only worked with a
+  mouse; it now works with a controller too, using the N64 original's own
+  stick-response curve so full stick matches the original's top turn rate.
+  (D332/D333/D337/D404)
+- **`Aim range`** (shown while Centred is selected) — **PC** (default,
+  full-screen feel) or **N64** (the original 65% stick limits). (D338)
+- **Reticule jitter in aim mode is gone** — mouse aim now runs on the
+  Perfect Dark PC port's aim model. (D332)
+- Per-device sensitivity: `Mouse horizontal/vertical sensitivity`, and for
+  controllers `X axis / Y axis look sensitivity (controller)` plus
+  `Look smoothing (controller)`.
+
+### Rebuilt options (F10 overlay + front-end PC Options)
+
+- Both options screens are reorganized into functional sections — **Input,
+  Gameplay, HUD, Graphics, Audio, Display** — each with its own *Reset to
+  defaults*; per-profile settings scoping; and the old "save file" wording
+  is now **profile**. (D353–D356)
+- The **F10 in-game overlay** was refreshed GE-style: category headers,
+  full controller support (value-adjust with hold-to-repeat), fixed pointer/
+  keyboard navigation, and new rows: **Show FPS**, **Skip intro
+  (experimental)**, pad
+  **Invert look / Southpaw / Deadzone / Trigger threshold**. (D237/D345–
+  D347/D360–D370)
+- The front end gained a **PC Options screen** beside the file-select bar,
+  and save-file **Copy/Erase** moved into the bottom bar. Long sections
+  (Input) page within the screen -- a "Page 1/2" marker plus a bottom hint
+  on every page -- so every row stays on screen and stays reachable; the
+  mouse wheel and W/S also page the list, and the selection clamps at page
+  edges. (D343/D406/D407)
+- Watch-only settings — **Auto-aim**, **Look ahead** and the rest — are now
+  editable from the PC options and **persist correctly** (this closes the
+  "auto-aim won't stay on" report, issue #103). (D330/D350/D352/D354)
+- **`HUD scale`** (75–150%, default 100%): scales the ammo counter, pickup
+  text and subtitle bars for smaller or larger displays. (D226)
+
+### Crosshair customization *(defaults leave the N64 crosshair untouched)*
+
+**Show crosshair** (on/off), **Crosshair colour** (the original red,
+or green / blue / yellow / cyan / magenta / white, or custom RGB), **Crosshair size**
+(default 100% of the original drawing), and **Crosshair style** (Original /
+Thin cross). (D373/D379/D381/D382)
+
+### In-game key rebinding + new default layout
+
+A two-group key editor (**Movement**, **Actions**, each with its own *Reset
+to defaults*) lives in both options screens. The new default **Actions**
+layout is the GEPD-style preset (e.g. Action/next-weapon on the keys you'd
+expect from a modern layout); existing INI bindings are honored and older
+ones migrate automatically. (D371/D374/D383/D385)
+
+### Controller improvements
+
+- **Sane pad defaults**: **A = use/interact, X = reload, Y = weapon cycle**
+  (v0.3.0 mapped two buttons to crouch and had no in-game use button). (D393)
+- Crouch uses the engine's real crouch input, with a **`Crouch mode`**
+  toggle (hold / latched). (D375)
+- Xbox-variant controller parity, **Southpaw**, and per-stick
+  **deadzone** + **trigger threshold** rows. (D237/D394)
+- **The N64 Rumble Pak now drives real gamepad haptics** (Steam Deck
+  included), scaled by a global **`Vibration`** slider (default 50%). (D401)
+- The F10 overlay is fully gamepad-driven. (D347/D395/D396)
+
+### `All unlocked` ships as a documented EXPERIMENTAL feature
+
+F10 → Gameplay → **`All unlocked (EXPERIMENTAL)`** opens every mission, 007
+mode and the full cheat menu. On a fresh install it now yields the game's
+own fresh-slot layout instead of corrupting state (D281) — but enabling it
+can still bake synthetic cheat/completion data into your save that switching
+it off does not undo: **complete a level normally first, and back up
+`data/ge007.eep` before enabling it.** (D387)
+
+### Steam Deck / Linux
+
+The first clean SteamOS/glibc build, plus a first-launch preset for decks
+without a config (native 1280×800, 2× MSAA, vsync, 250% draw/LOD
+distances). (D402/D283)
+
+---
+
+## Bug fixes
+
+### Fidelity (verified against the N64 original / era-correct references)
+
+- **Water** on the `IsWater` levels (Dam, Frigate, Surface 2, …) matches
+  the original: the moving seam between two patterns and the pattern
+  "resetting" as you moved are gone. (D245)
+- The **particle "rainbow" effect** (intermittently recoloured sparks and
+  explosion residue) no longer occurs. (D252)
+- **Frigate: "every polygon breaks except the gun"** after turning — and
+  the rare "Bond briefly out of place" quirk — were the same never-written
+  fields read by the head-bob animation; both are fixed. (D336/D311)
+- Surface 1/2: the tree backdrop that rendered as a solid wall of texture
+  now renders as proper camera-facing tree cards. (D236)
+- Ejected **shell casings** render again. (D331)
+- The intro **gun-barrel blood drip** draws correctly. (D341)
+- The extra erroneous **long muzzle flash** on some guns is gone. (D303)
+- Occasional **z-fighting** fixed; **security-camera props** no longer face
+  backwards; the front-end **Nintendo logo and copyright page** render
+  correctly. (D308/D307/D403)
+- The **train-intro soldier pose** is correct. (D392)
+- **Tanks** (Runway, Streets) can be boarded and exited again — the new
+  use/reload button split had removed the B-button tap the engine's tank
+  handlers use; B is presented again in tank states, and use keeps its
+  no-reload-fallback semantics everywhere else. A short input lockout during
+  the sit-down animation means a double-tap can't cancel boarding, and in-tank
+  mouse aim has its own **`Tank aim speed`** setting (`Input.TankAimScale`,
+  default 100) so the turret matches your on-foot feel. (D407)
+- File-select background / gun-barrel comb rendering fixed. (D397)
+- Stale-texture artifacts after level transitions fixed. (D235)
+- Distant-geometry dropout on the biggest open levels (Streets, Egyptian)
+  substantially improved at default settings. (D249)
+- The **Facility execution-scene watchdog** from v0.3.0 stays enabled as a
+  safeguard; the animation-pinning that motivated it is root-caused (a tick
+  granularity divergence) and fixed, so the scene plays out as authored.
+  (D329/D318)
+
+### Front end & UI
+
+- Randomly **flickering F10 menu items** are gone. (D314)
+- The watch's **controller-page graphic** renders again. (D290)
+- File-select **folders and Bond photos** no longer vanish after backing
+  out of a file. (D342)
+- File-select bottom row (SELECT FILE / Copy / Erase / PC Options) aligned.
+  (D398–D400)
+
+### Audio
+
+- **Gunshot SFX** cadence matches the N64 original's rate, and the
+  intermittent silence of the PP7/AK47 under sustained fire near a looping
+  sound is gone. (D240/D241)
+- The silenced **PPK "slap"** and the broader real-time mixer corruption
+  behind it are fixed. (D202)
+- Windows audio now prefers the **DirectSound** backend over WASAPI (lower,
+  more robust latency). (D322)
+- In-stage music **re-synchronizes** correctly at stage transitions and
+  level entry. (D355)
+- Long-session audio degradation (issue #87): pool hardening shipped, plus
+  an optional `GE_D322=1` telemetry probe if it ever recurs.
+
+### Stability & renderer
+
+- **Orderly game exit**: quitting no longer lands inside the graphics
+  driver (a class of Windows driver bugchecks seen during testing). (D344)
+- A **non-self-recovering Windows freeze** after the window sat idle and
+  lost focus is fixed (mouse-mode changes now applied on the window
+  thread). (D287)
+- **MSAA above your driver's maximum no longer black-screens** (the request
+  is clamped to `GL_MAX_SAMPLES`), and two framebuffer-state bugs in the
+  render/resolve paths were fixed — community contribution, PR #106,
+  security-reviewed. (D405)
+- Port-wide code audit: missing returns in front-end menus, missing
+  prototypes, undefined-behaviour shifts.
+
+---
+
+## Options reference
+
+All settings available in v0.4.0, in both options screens (front-end
+**PC Options** and the in-game **F10 overlay**). Defaults in parentheses.
+
+| Setting | Section | Default |
+|---|---|---|
+| `Native widescreen` | Display | On |
+| `Frame rate cap` | Display | 60 (30 / 60) |
+| `Show FPS` | Display | Off |
+| `MSAA` | Display | 2× (1/2/4/8, clamped to driver max) |
+| `Aim style` | Input | N64 (N64 / Centred (PC)) |
+| `Aim range` | Input | PC (shown while Centred) |
+| `Mouse horizontal/vertical sensitivity` | Input | calibrated midpoint |
+| `Invert look (mouse)` / `Invert look (controller)` / `Southpaw` | Input | Off |
+| `X / Y axis look sensitivity (controller)` | Input | 100% (native) |
+| `Look smoothing (controller)` | Input | 0 |
+| `Tank aim speed` | Input | 100% (`Input.TankAimScale`) |
+| `Deadzone (left/right stick)` | Input | 70% |
+| `Trigger threshold` | Input | 23% |
+| `Vibration` | Input | 50% |
+| `Crouch mode` | Input | Hold |
+| `Bindings…` (Movement / Actions editors) | Input | GEPD-style preset |
+| `Auto-aim` / `Look ahead` | Gameplay | Off (watch-backed) |
+| `Skip intro` / `No hit flash` | Gameplay | Off |
+| `All unlocked (EXPERIMENTAL)` | Gameplay | Off |
+| `HUD scale` | HUD | 100% (75–150%) |
+| `Show crosshair` / `Crosshair colour` / `Crosshair size` / `Crosshair style` | HUD | N64-intact (size 100%) |
+
+---
+
+## Things to know
+
+- **NTSC-U (US) ROMs only.** PAL and JP ROMs are not supported in this
+  version; asset repair for those regions is on the post-release roadmap.
+  (D258)
+- **The default Actions key layout is new** (GEPD-style). If you preferred
+  the v0.3.0 defaults, rebind them in *Input → Bindings…* or reset the
+  group. Existing INI bindings are auto-migrated and still honored.
+- **Back up `data/ge007.eep` before using `All unlocked`** (see above).
+- Steam Deck: the first launch in Game Mode applies the Deck preset only if
+  no `ge007.ini` exists yet; F10 changes always win afterwards.
+
+## Known issues
+
+- On Facility, if gas leaks during Ourumov's monologue he can pause for up
+  to ~10 s before resuming the scripted shootout — a latent race that exists
+  in the N64 original too (where it softlocks permanently); the port detects
+  and auto-recovers it. (D318)
+- With *Native widescreen* on, the F10 options overlay stretches with the
+  window instead of pillarboxing like the front-end menus (legible;
+  cosmetic). (D335b)
+- The front-end Rareware logo shows a subtle texture-filtering artifact
+  (the Nintendo logo and legal page are clean). Cosmetic only. (D75)
+- **`All unlocked` is experimental** (see above); the fresh-install
+  corruption case is fixed, but saves made while it is on are not
+  guaranteed recoverable by switching it off. (D387)
+- **`Skip intro` is experimental — not recommended for regular use yet.**
+  With it on, a failed or aborted mission skips the post-mission failure
+  report screen and returns straight to the menus (the mission still records
+  correctly). An older audio quirk on some saves is also still being chased.
+  (D408/D216)
+
+## Roadmap since v0.3.0 (research, not yet features)
+
+- ROM-level **mod support** investigated and found viable (the game's file
+  table lives in the ROM); HD texture packs and the drop-in-ROM flow are
+  tracked post-1.0. (D325–D328)
+- A measured CPU budget on low-end hardware (issue #92) reshaped the
+  performance investigation toward the GPU. (D339)
+- Controller options wave 2 (presets, pad reassignment UI) and PAL/JP
+  support are planned post-v0.4.0.
+
+---
+
+## Downloads
 
 | File | Platform |
 |---|---|
-| `goldeneye-pc-port-<version>-win64.zip` | Windows x86-64 |
-| `goldeneye-pc-port-<version>-linux-x86_64.tar.gz` | Linux x86-64 (incl. Steam Deck) |
+| `goldeneye-pc-port-0.4.0-win64.zip` | Windows x86-64 |
+| `goldeneye-pc-port-0.4.0-linux-x86_64.tar.gz` | Linux x86-64 (incl. Steam Deck) |
 
 Each contains the engine executable, a README, license texts, and the
-`prepare-assets` tool. **No ROM, no game assets.** The Windows bundle carries
-its runtime DLLs; the Linux bundle carries SDL2, so on both platforms nothing
-needs to be installed first.
+`prepare-assets` tool. **No ROM, no game assets.** The Windows bundle
+carries its runtime DLLs; the Linux bundle carries SDL2, so on both
+platforms nothing needs to be installed first.
 
-### Running it
+## Running it
 
 You supply your own **GoldenEye 007 N64 ROM** (`.z64`, big-endian) that you
-legally own: the **NTSC-U (US)** release is what this build supports (PAL / JP
-are on the roadmap). No Python, no toolchain, nothing to install.
+legally own (NTSC-U only, as noted above). No Python, no toolchain, nothing
+to install.
 
 1. Unpack the archive.
 2. Make a `data/` folder next to the executable and put the ROM in it, named
    `ge007.ntsc-final.z64`.
 3. Run the executable **from that folder**. The first run takes a few extra
    seconds: it detects your ROM, generates the two derived asset folders
-   (`data/pcmodels-ntsc-final/`, `data/pccg-ntsc-final/`) once, and saves them
-   for every future run. (The generator is `prepare-assets/ge007-convert`
-   inside the bundle; you can also run it manually; it prints what it's doing.)
+   (`data/pcmodels-ntsc-final/`, `data/pccg-ntsc-final/`) once, and saves
+   them for every future run. (The generator is
+   `prepare-assets/ge007-convert` inside the bundle; you can also run it
+   manually; it prints what it's doing.)
 
-**Steam Deck:** sideload the unpacked folder (USB or a file manager), do steps
-2–3, then add the executable to Games → *Add Game* as a non-Steam game.
+**Steam Deck:** sideload the unpacked folder (SFTP, USB or a file manager), do
+steps 2–3, then add the executable to Games → *Add Game* as a non-Steam
+game. The first launch in Game Mode picks up the Deck preset (native
+1280×800, 2× MSAA, vsync) automatically if no config exists yet.
 
-**In-game settings on the Deck:** the options overlay is fully gamepad-driven:
-it opens with **Select**, the D-pad or left stick (up/down) moves between
-options, **A** steps the selected option forward, **B** steps it back, and
-**Start** (or Select again) closes. No keyboard needed.
+**In-game settings on the Deck:** the options overlay is fully
+gamepad-driven: it opens with **Select**, the D-pad or left stick (up/down)
+moves between options, **A** steps the selected option forward, **B** steps
+it back, and **Start** (or Select again) closes. No keyboard needed.
 
 Full steps are in the bundled `README.md`.
 
-### Verify the download
+## Verify the download
 
 ```
-sha256sum -c goldeneye-pc-port-<version>-win64.zip.sha256
-sha256sum -c goldeneye-pc-port-<version>-linux-x86_64.tar.gz.sha256
+sha256sum -c goldeneye-pc-port-0.4.0-win64.zip.sha256
+sha256sum -c goldeneye-pc-port-0.4.0-linux-x86_64.tar.gz.sha256
 ```
 
-### Source & docs
+## Source & docs
 
 <https://github.com/jkdansereau/goldeneye-pc-port>, built on the
-[GoldenEye 007 decompilation](https://github.com/n64decomp/007), architecture
-after the [Perfect Dark PC port](https://github.com/fgsfdsfgs/perfect_dark).
+[GoldenEye 007 decompilation](https://github.com/n64decomp/007),
+architecture after the [Perfect Dark PC port](https://github.com/fgsfdsfgs/perfect_dark).
 Non-commercial fan preservation/research project; not affiliated with any
-rights holder.
+rights holder. **AI disclosure:** built through agentic AI coding (Claude
+Code + a local open-weight model), directed by one person in their spare
+time — as much a study of what agentic development gets wrong on a
+game-sized codebase as it is a port. See the README's
+[Background section](https://github.com/jkdansereau/goldeneye-pc-port#background)
+for the full account.

.github/social-preview.html

@@ -124,12 +124,12 @@
     <div class="rep">REPORT:</div>
 
     <div class="rows">
-      <div class="statusline">Status: <span class="status">RELEASED v0.2.0 &mdash; WINDOWS &middot; LINUX &middot; STEAM DECK</span></div>
+      <div class="statusline">Status: <span class="status">RELEASED v0.3.0 &mdash; WINDOWS &middot; LINUX &middot; STEAM DECK</span></div>
       <div class="stats">
-        <span class="k">Statistics:</span><span>All 21 solo missions &mdash; full campaign completed in playtesting</span>
+        <span class="k">Statistics:</span><span>All 20 solo missions &mdash; full campaign completed in playtesting</span>
         <span></span><span>~230 game-code units, compiled unmodified</span>
-        <span></span><span>~22k lines C/C++ &nbsp;&middot;&nbsp; ~10k Python  (port layer + tools)</span>
-        <span></span><span>~250 bugs root-caused &nbsp;&middot;&nbsp; two coding agents, one human, part-time</span>
+        <span></span><span>~24k lines C/C++ &nbsp;&middot;&nbsp; ~7k Python  (port layer + tools)</span>
+        <span></span><span>199 findings root-caused &nbsp;&middot;&nbsp; two coding agents, one human, part-time</span>
       </div>
     </div>
 

.github/workflows/ci.yml

@@ -138,6 +138,20 @@ jobs:
           python3 tools_pc/gen_findings_index.py --check
           python3 tools_pc/gen_env_probes.py --check
 
+      # Docs budget guardrail (ctx-opt P2): warn, don't fail. The §F index
+      # table should stay one-liners; fat cell content belongs in `## Dxx`
+      # sections at the file tail (lookup path: docs/dev/findings-index.csv).
+      - name: Check dev-docs size budgets (warn only)
+        run: |
+          # Budget = ~55 KB of table rows + ~110 KB of legacy D24–D33 / M-xxx
+          # narrative that predates the ctx-opt migration. The signal is fat
+          # ROWS re-accumulating, so the threshold sits ~15 KB above today's
+          # 166 KB total.
+          f=$(awk '/^### F\./{f=1;next} /^### G\./{f=0} f' docs/dev/findings.md | wc -c)
+          [ "$f" -le 184320 ] || echo "WARNING: findings.md §F region is $f bytes (> 180 KB) — fat rows accumulating; migrate cell content to ## Dxx sections at the file tail"
+          p=$(wc -c < docs/porting-notes.md)
+          [ "$p" -le 122880 ] || echo "WARNING: porting-notes.md is $p bytes (> 120 KB) — consider splitting or adding a TOC block"
+
       # US only. gen_romassets.py resolves every symbol for the US region from
       # the committed CSVs with no ROM present; PAL/JP each need a handful of
       # region-specific prop/font offsets that only come from that region's ROM

.gitignore

@@ -156,12 +156,23 @@ ge007.crash.log
 
 # agent scratch space + audio probe artifacts (regenerable dumps/traces)
 scratchpad/
+# session logs / investigation scratch — local only, never in the public repo
+# (untracked 2026-09-19 during the v0.3.0 release review)
+/scratch/
+# re-vendored GPL reference source (see reference/mouse-injector/README.md)
+/reference/mouse-injector/*
+!reference/mouse-injector/README.md
+# local research/backlog working docs (TCRF cut-content cross-reference etc.)
+backlog/
 # montage work artifact: the tiled contact sheet behind docs/img/shots/ and
 # the preview video (regenerable from the same session recordings)
 docs/img/shots/CONTACT-SHEET.jpg
 /audiodump.raw
 /audiotrace.log
 /mixertrace.log
+# texture-dump probe artifacts (regenerable via GE_TEXDUMP)
+/texdump/
+/texdump_p23_old/
 
 # Claude Code local state / agent worktrees
 .claude/
@@ -176,3 +187,16 @@ gdb-hang.txt
 # frozen asset converter (built by CI via PyInstaller; local freezes land here)
 tools_pc/dist/prepare-assets/ge007-convert*
 build-pyinst/
+
+# Local working junk (frame captures, timerun state, PPM dumps) - moved here
+# from repo root / scratch on 2026-09-18; never commit.
+/local/
+build-pc-cmd.bat
+
+# v0.4.0 modern-options wave: per-landing sweep capture dirs (capture.sh output)
+tools_pc/sweep-captures/capture-*/
+
+# Stray full CPython install that landed in repo root (2026-09-28);
+# referenced by no project tooling. Never commit.
+/Python/
+docs/media/*.mp4

AGENTS.md

@@ -4,14 +4,14 @@
 
 - `n64decomp/007`: WIP decompilation of GoldenEye 007 (N64), byte-matches US/EU/JP ROMs.
 - Active work: **PC port** modelled on the Perfect Dark PC port (same Rare "Indy" engine family).
-- **Reference docs:** `docs/internals.md` — architecture, GE-specific RSP deltas, phased plan (§1–§10). `docs/dev/findings.md` — the `Dxx` finding log (§F + §H, indexed at the top of §F); read the entry you need, don't linear-read. `docs/porting-notes.md` — the recurring N64→PC bug classes (dense; skim the headers, read what's relevant).
+- **Reference docs:** `docs/internals.md` — architecture, GE-specific RSP deltas, phased plan (§1–§10). `docs/dev/findings.md` — the `Dxx` finding log (§F + §H). **Look up findings via `docs/dev/findings-index.csv` (label, one-liner, status; regenerate with `tools_pc/gen_findings_index.py`), then read only the specific `## Dxx` entry (multi-pass labels like D202/D176(a) have large sections — grep within the section or read with offset/limit, don't slurp it whole). Never linear-read.** `docs/porting-notes.md` — the recurring N64→PC bug classes (dense; skim the headers, read what's relevant).
 - **Current status:** the README "Status" section, and `docs/dev/LEVEL-STATUS.md` for the per-level sweep. Current task + environment: `docs/HANDOFF.md` (a rolling local working file — may be absent in a fresh clone; fall back to the README "Status" section).
 - **Dispatching subagents?** `docs/dev-process.md` — task budgets/deadlines, file partitioning, pre-flight, the standard brief template. Every investigation subagent reads `docs/porting-notes.md` first and appends to it.
 
 ## Non-negotiables
 
 1. **N64 build untouched.** `Makefile`, `tools/`, `rsp/`, `ld/` belong to the N64 build. Never modify them for the PC port.
-2. **Game logic is unmodified.** The decomp's control flow and behavior are ground truth for 1:1 fidelity — never change them. All N64 *hardware* dependencies are satisfied by the `port/` layer; if a game file seems to need a behavioral change, stop — the fix belongs in `port/`. **Narrow exception (ABI/layout only):** the 32→64-bit transition forces a small class of mechanical, semantics-preserving edits that cannot be isolated in `port/` — chiefly pointer-width reconciliation in ROM-serialized structs (a struct with a 32-bit-pointer field misaligns when read as 64-bit). These follow the PD ground-truth pattern (store the embedded address as `u32`, cast to a real pointer at the use site), change no logic or behavior, and are each documented in `docs/dev/findings.md` §F/D3x. No other game-code edits are permitted.
+2. **Game logic is unmodified.** The decomp's control flow and behavior are ground truth for 1:1 fidelity — never change them. All N64 *hardware* dependencies are satisfied by the `port/` layer; if a game file seems to need a behavioral change, stop and check the exception below before assuming the fix belongs in `port/`. **Diagnosis is never restricted — only the fix.** Trace a bug as deep into `src/game` state as the evidence leads, and name the exact struct/field/logic responsible, before deciding which of three buckets it falls in (full framing: `docs/dev-process.md`). **Narrow exception (ABI/layout only):** the 32→64-bit pointer-width transition forces a small class of mechanical, semantics-preserving edits that cannot be isolated in `port/` — **any struct-layout or pointer-width-driven misread caused by 32→64-bit widening**, whether in a ROM-serialized record (a struct with a 32-bit-pointer field misaligns when read as 64-bit) or a **live runtime struct/union** (a raw-byte offset alias into a union arm whose true field shifted because an earlier member in the same union widened — the D209/D210/D255 pattern; see `docs/porting-notes.md` §A1 for the full catalogue and its diagnostic tells). These follow the PD ground-truth pattern (store the embedded address as `u32` and cast to a real pointer at the use site; or read the correctly-named/typed field instead of a raw-offset/mistyped alias), change no logic or behavior, and are each documented in `docs/dev/findings.md` §F/D3x, cross-tagged to §A1 where that pattern applies. **A genuine behavioral difference** — the decomp's byte-identical code, given verified-correct inputs, still diverging from real N64 behavior — is not covered by this exception and requires the rule-2 sign-off procedure (`docs/dev-process.md`) before any `src/game` edit. No other game-code edits are permitted.
 3. **Region macros mirror the Makefile.** `CMakeLists.txt` `REGION_DEFS` must match the N64 Makefile's per-region macro set exactly (finding A1). Divergence = silent branch divergence + link failures.
 4. **`src/libultrare/Makefile.libultrare` is ground truth** for original-vs-Rare libultra files (finding B3). The PC build compiles: `libultra/audio`, `libultrare/audio` (drvrNew/env/reverb), `libultra/gu`, and `libultrare/io/vitbl.c` only. All other `io/` + `os/` files are excluded and shimmed in `port/src/libultra.c`.
 5. **`rsp/graphics/gmain.s` is the RSP ground truth** — the authoritative reference for which GBI commands GE emits (modified fast3d, 1545 lines). We do not run it on PC; `port/fast3d/` replaces it. Use it to validate the software RSP's command decoding and the custom CC/RM modes.
@@ -21,11 +21,12 @@
 | File | Role |
 |---|---|
 | `docs/internals.md` | Architecture + RSP deltas + phased plan (§1–§10). Reference, not a linear read. |
-| `docs/dev/findings.md` | The `Dxx` finding log (§F/§H, indexed at top of §F). |
+| `docs/dev/findings.md` | The `Dxx` finding log (§F/§H); lookups via `docs/dev/findings-index.csv`. |
 | `CMakeLists.txt` | PC build (parallel to the N64 Makefile). Source list + `REGION_DEFS` live here. |
 | `port/src/` | Shims: `libultra.c` (OS API), `gesched.c` (scheduler), `n64stubs.c` (boot/TLB/FPU/rmon), `random.c` (PRNG ported verbatim from `random.s`), `ucode.c` (microcode segment markers), `main.c`, `video.c`, … |
 | `port/fast3d/` | Software RSP (adapted from the PD port). The main Phase 2 work. |
 | `rsp/graphics/gmain.s` | GE's RSP ucode — ground truth for GBI/CC/RM. |
+| `reference/mouse-injector/README.md` | **Stub only** — the vendored GEPD-Edition Mouse Injector source (GPLv2) was removed from the public repo 2026-09-19 (license hygiene: GPL code + prebuilt binary in an MIT project; it was never compiled here). The stub records provenance + how to re-vendor locally (gitignored). The ported mouse-aim model lives in `port/src/input.c` (D194 lineage); design record: `docs/dev/GEPD-INPUT-PLAN.md`. |
 | A local **Perfect Dark PC port** checkout ([fgsfdsfgs/perfect_dark](https://github.com/fgsfdsfgs/perfect_dark)) | **Standing reference** — consult it whenever a work item has a PD analogue (same Rare engine family): port-layer ground truth (`port/fast3d/`, crash/system/video), plus copy candidates `port/src/preprocess/` (N64→PC asset conversion; `filemodel.c` is the D43 near-analogue) and `mixer.c`/`input.c`/`fs.c`. Port-layer files only; same family ≠ identical format — validate per field. Full audit: `docs/internals.md` §2.4. |
 
 ## Build
@@ -38,6 +39,59 @@ Needs CMake + SDL2 + zlib + OpenGL, and must run from the MSYS2 MINGW64 shell
 (see `build-pc.sh` header and `docs/building.md`). ROM goes in `./data/`
 (not distributed); assets must be extracted from it first (`docs/building.md`).
 
+**Windows build environment (three recurring failure modes — diagnose in this order):**
+
+1. **`Cannot create temporary file in C:\Windows\: Permission denied`** at the
+   link step. The PE toolchain (ninja → cmd → gcc/ld) needs a writable
+   TMP/TEMP; the msys→native env conversion drops it in non-login shells
+   (agent harnesses; the `C:/msys64` tree here was built for `D:/M/msys64`,
+   so its conversion is unreliable). `build-pc.sh` now **self-heals**: it
+   probes a native child's TMP (via a file — piped `cmd.exe` stdout is
+   unreliable under msys console emulation) and, if broken, re-runs
+   cmake+build under PowerShell with `TMP`/`TEMP` set natively (the
+   native→native boundary passes env through intact; only msys→native is
+   broken). If you run cmake/ninja *by hand* from a broken shell: run them
+   from cmd/PowerShell with `C:\msys64\mingw64\bin` on PATH.
+   **Guard revision (2026-09-28):** the re-exec writes a self-contained
+   `.ps1` to a temp file and runs `powershell -File` with plain path/word
+   args only (the msys→native argv conversion mangles `$`-bearing
+   `-Command` strings; a file write is conversion-free). Inside: PATH is
+   built explicitly (never trust the inherited value); TMP is chosen from
+   writable candidates (`%LocalAppData%\Temp` first —
+   `[System.IO.Path]::GetTempPath()` honours the inherited *broken* TMP,
+   observed as `C:\Windows\`); every native step self-logs to
+   `build-pc/ge007-native-reexec-{diag,cmake,build}.log`; a null
+   `$LASTEXITCODE` ("did not execute") is a distinct failure (exit 2/3) —
+   in PS 5.1 a piped native command errors out non-terminating and never
+   sets it, so an unguarded `if ($LASTEXITCODE -ne 0)` passes vacuously.
+   In `.ps1`, `-DROMID=$Var` is a literal (bare tokens don't expand) — it
+   must be `"-DROMID=$Var"`. Launch powershell plainly — `env -i` before it
+   breaks the nested cmake launch (verified 2026-09-28).
+   **OPEN (next session):** the guard still fails *inside* `build-pc.sh`
+   (cmake "did not execute": the `.ps1` runs, but `$LASTEXITCODE` stays
+   empty) while the *identical* standalone invocation succeeds (cmake runs
+   and the build completes — that is how the D401 builds were made). First
+   test: diff the heredoc-generated `.ps1` against a hand-extracted copy
+   (suspect: heredoc line-ending/whitespace corruption).
+   **Working workaround:** extract the heredoc `.ps1` and run
+   `powershell -NoProfile -ExecutionPolicy Bypass -File <ps1> "C:\msys64\usr\bin" "C:\msys64\mingw64\bin" C:/msys64 <repo-win-path> build-pc <romid>`.
+   Re-confirmed 2026-09-28: in-script re-exec fails again (cmake configure
+   dies inside the ps1; re-exec logs left stale) while the identical
+   standalone invocation reconfigured and built cleanly (extract with
+   `awk "/<<'PS1'\$/{f=1;next} /^PS1\$/{f=0} f" build-pc.sh > /tmp/ps1`
+   — mind the leading whitespace, and `export PATH` to include mingw/bin
+   first, failure mode 3).
+2. **`cannot open output file ge007.x86_64.exe: Permission denied`.** A
+   **running** `ge007.x86_64.exe` locks the output file (Windows rule; you
+   can't relink over a live PE). Check with `Get-Process | Where-Object {
+   $_.ProcessName -like '*ge007*' }` and close the game before rebuilding.
+   An agent must not kill the user's game process to make a link succeed.
+3. **`cc1.exe: ... libmpfr-6.dll: cannot open shared object file`.** The
+   calling PATH lacks `C:\msys64\mingw64\bin` (the gcc driver finds cc1 via
+   its own directory, but the child needs the mingw DLL dir on PATH). In an
+   msys shell: `export PATH="/c/msys64/mingw64/bin:/c/msys64/usr/bin:$PATH"`
+   before building.
+
 ## Verification ritual (after any build-affecting change)
 
 1. **Undefined symbols.** Every symbol referenced by the compiled set (see `CMakeLists.txt`: `SRC_GAME`, `SRC_ENGINE`, `SRC_LIBAUDIO`, `SRC_LIBULTRARE_AUDIO`, `SRC_LIBULTRARE_DATA`, `SRC_GU`, `SRC_PORT*`) must be defined exactly once in the compiled set or in `port/`. Symbols that live in EXCLUDED files (`libultra/io/*`, `libultrare/io/*` except `vitbl.c`, `libultra/os/*`, `libultrare/os/*`, `sched.c`, `rmon.c`, `vi.c`, `src/*.s`) must be provided by `port/src/libultra.c`, `gesched.c`, `n64stubs.c`, `random.c`, or `ucode.c`.
@@ -50,8 +104,9 @@ Run `/linkcheck` for this sweep. Record new findings in `docs/dev/findings.md`
 
 - **Phase 0–1.5:** done. Build system, boot chain, OS-shim layer, fast3d
   integration, first frames, full intro rendering.
-- **Phase 2 (rendering):** in progress. All 21 solo levels load + render +
-  survive an unattended window; front end (menu → mission select → briefing →
+- **Phase 2 (rendering):** in progress. All 20 solo missions (plus the
+  ending-credits sequence, `-level_54`) load + render + survive an
+  unattended window; front end (menu → mission select → briefing →
   start) is functional; file-backed EEPROM saves work. Cosmetic defects are
   parked in `docs/dev/GRAPHICS-BACKLOG.md`.
 - **Phase 3 (audio + input):** input layer done (`port/src/input.c`); polish

CLAUDE.md

@@ -21,9 +21,10 @@ Context is scarce. Load by tier; do not blind-read whole files.
 - **Tier 2 — on demand only, do NOT read start-to-finish:**
   - `docs/internals.md` — architecture / RSP deltas / phased plan (§1–§10).
     Read the section you need.
-  - `docs/dev/findings.md` — the `Dxx` finding log (§F + §H).
-    **Jump to a specific `Dxx` via the index at the top of §F.** Never
-    linear-read.
+  - Findings: look up via `docs/dev/findings-index.csv` (label, one-liner,
+    status), then read only the specific `## Dxx` entry in
+    `docs/dev/findings.md` (multi-pass labels like D202/D176(a) have large
+    sections — grep within or offset/limit). Never linear-read.
   - `docs/dev/HANDOFF-ARCHIVE.md` — prior-session narrative (M-2…). Only
     when tracing the history of one fix.
   - `docs/dev-process.md` — before dispatching a subagent (also Tier 1

CONTRIBUTING.md

@@ -11,12 +11,19 @@ keep the port faithful to the original game.
    belong to the N64 build and are never touched for PC work. If PC code seems
    to need a behavioural change in the game, the fix belongs in `port/`.
 
-2. **Narrow ABI exception.** The 32→64-bit transition forces a small class of
-   mechanical, semantics-preserving edits to ROM-serialized structs (storing an
-   embedded 32-bit pointer as `u32` and casting at the use site). These are
-   allowed, must be guarded with `#ifdef PORT`, must change no behaviour, and
-   must be documented. See `docs/porting-notes.md` for the catalogue of
-   patterns.
+2. **Narrow ABI exception; diagnosis is always allowed.** Trace a bug as
+   deep into the decomp's state as the evidence leads — that's never
+   restricted. Only the *fix* is constrained: the 32→64-bit transition
+   forces a small class of mechanical, semantics-preserving edits — any
+   struct-layout or pointer-width-driven misread caused by 32→64-bit
+   widening, in a ROM-serialized record or a live runtime struct/union alike
+   (see `docs/porting-notes.md` §A1 for the pattern and its tells). These
+   are allowed, must be guarded with `#ifdef PORT`, must change no
+   behaviour, and must be documented. A genuine behavioral difference from
+   real N64 behavior is a separate, much rarer case that needs explicit
+   maintainer sign-off first — see `docs/dev-process.md`'s rule-2 sign-off
+   procedure; it is not something a contributor can self-approve or infer
+   from this exception.
 
 3. **Region macros mirror the Makefile.** `CMakeLists.txt` `REGION_DEFS` must
    match the N64 `Makefile`'s per-region macro set exactly.

README.md

@@ -1,7 +1,12 @@
 # GoldenEye 007 PC Port
 
 [![CI](https://github.com/jkdansereau/goldeneye-pc-port/actions/workflows/ci.yml/badge.svg)](https://github.com/jkdansereau/goldeneye-pc-port/actions/workflows/ci.yml)
-![license](https://img.shields.io/badge/license-MIT-green)
+![license](https://img.shields.io/badge/license-MIT-ffb454)
+
+<p align="center"><em>GoldenEye 007 (Nintendo 64, 1997) on the PC —
+decompiled, ported, and playable at 60 fps.</em></p>
+
+[Download](#download) · [News](#news) · [Status](#status) · [Roadmap](#roadmap) · [Building](#building) · [Docs](#documentation) · [Legal](#legal)
 
 A native PC port of _GoldenEye 007_ (Rare, 1997, Nintendo 64), compiled from
 the [GoldenEye 007 decompilation](https://github.com/n64decomp/007): the
@@ -12,15 +17,24 @@ in a dedicated `port/` layer, following the architecture of the
 [Perfect Dark PC port](https://github.com/fgsfdsfgs/perfect_dark), the same
 Rare "Indy" engine family, one hardware generation apart.
 
-**v0.2.0** is out for Windows and Linux (including Steam Deck, where the
-Linux bundle sideloads as-is) and runs the full campaign at a steady 60 fps
-with known rough edges ([Status](#status)). Free to download, build on and
-modify (you bring the ROM).
+**v0.4.0** (released 2026-09-28) is out for Windows and Linux (including
+Steam Deck, where the Linux bundle sideloads as-is). It is the most complete
+release to date: the full campaign runs at a steady 60 fps with the known
+issues now few and mostly cosmetic ([Status](#status)). Free to download,
+build on and modify (you bring the ROM).
 
-It's also a case study in AI-agent collaboration on a large, low-level
-codebase: two coding agents, driven by one person part-time, porting ~230
-translation units of unmodified big-endian MIPS game code to a 64-bit desktop.
-See [Background](#background).
+**This is a pre-1.0 release, not a finished product.** v1.0 is the target
+for a polished, feature-complete build; until then, expect missing features
+and the occasional breaking change between versions. See [Status](#status)
+for what works today and [Roadmap](#roadmap) for where this is headed.
+
+**AI disclosure:** development here was agentic - Claude Pro plus a local
+open-weight model on a single RTX 5090, as of August–September 2026. This
+project is as much a study of *that process* as it is a port: whether
+current LLMs can carry a codebase like this, and what actually goes wrong
+along the way. Judge the result for yourself. I'm one person doing this in my
+spare time, not a team. See [Background](#background) for the full setup,
+timeline, and an honest account of what worked and what didn't.
 
 > [!IMPORTANT]
 > **You must supply your own GoldenEye 007 ROM.** This repository contains no
@@ -29,92 +43,142 @@ See [Background](#background).
 
 <p align="center">
   <img src="docs/media/goldeneye-gh-preview.gif" width="64%"
-       alt="~32 s gameplay montage from live play sessions">
-  <br><em>All in-engine, running in the port, a ~32&nbsp;s gameplay montage loop
-  from the v0.2.0 playtest.</em>
+       alt="~24 s gameplay montage from live play sessions">
+  <br><em>All in-engine, running in the port — a ~24&nbsp;s gameplay montage
+  from live v0.4.0 play sessions, opening on the Runway tank ·
+  <a href="docs/index.md">12 level stills in the project index</a></em>
 </p>
 
+---
+
+## News
+
+- **2026-09-28** — **v0.4.0**: native widescreen, a complete aim system for
+  mouse and controller, in-game key rebinding, crosshair customization,
+  rumble-pak haptics, a rebuilt options overlay, and a broad fidelity-fix
+  pass (water, particles, billboard trees, front-end logo, gunshot SFX, a
+  true stable 60 fps). [Release notes](https://github.com/jkdansereau/goldeneye-pc-port/releases/tag/v0.4.0) ·
+  [downloads](#download).
+- **2026-09-20** — **v0.3.0**: the first release with the complete campaign
+  playable end to end at 60 fps on Windows, Linux, and Steam Deck.
+  [Release notes](https://github.com/jkdansereau/goldeneye-pc-port/releases/tag/v0.3.0).
+- **2026-09-04 → 2026-09-16** — **v0.1.0 – v0.2.2**: the alpha and beta
+  cycle — build chain, software RSP, first rendered frames, front end, and
+  per-level stabilization across the campaign.
+
+---
+
 ## Download
 
 | Platform | Bundle | Notes |
 |---|---|---|
-| **Windows** (x86_64) | [win64.zip](/jkdansereau/goldeneye-pc-port/releases) | Engine + runtime DLLs + the one-time asset tool. |
-| **Linux** (x86_64) / **Steam Deck** | [linux tarball](/jkdansereau/goldeneye-pc-port/releases) | SDL2 is bundled, so it runs as-is on any distro, and sideloads onto a Deck with nothing installed. |
+| **Windows** (x86_64) | [win64.zip](https://github.com/jkdansereau/goldeneye-pc-port/releases) | Engine + runtime DLLs + the one-time asset tool. |
+| **Linux** (x86_64) / **Steam Deck** | [linux tarball](https://github.com/jkdansereau/goldeneye-pc-port/releases) | SDL2 is bundled, so it runs as-is on any distro, and sideloads onto a Deck with nothing installed. |
 
 Both bundles contain **no ROM and no game assets**: you supply your own
 (see [Requirements](#requirements)), which keeps the release legal to
-distribute. Earlier builds: v0.1.0 alpha, same page. You can also build it
-yourself; see [Building](#building).
+distribute. Earlier builds: v0.3.0, v0.2.2, v0.2.1, v0.2.0, and v0.1.0
+alpha, same page. You can also build it yourself; see [Building](#building).
 
 ### Quick start
 
 You need a GoldenEye 007 N64 ROM (`.z64`, big-endian). This release supports
 the **NTSC-U (US)** version; PAL and JP are on the roadmap ([issue
-#85](/jkdansereau/goldeneye-pc-port/issues/85)). No ROM or game asset is
+#85](https://github.com/jkdansereau/goldeneye-pc-port/issues/85)). No ROM or game asset is
 included or distributed. Then:
 
-1. Download the Windows or Linux bundle from [Releases](/jkdansereau/goldeneye-pc-port/releases) and unpack it.
+1. Download the Windows or Linux bundle from [Releases](https://github.com/jkdansereau/goldeneye-pc-port/releases) and unpack it.
 2. Make a `data/` folder next to the executable and drop the ROM in as `ge007.ntsc-final.z64`.
 3. Launch the executable from that folder. The first run takes a few extra seconds: it detects the ROM and generates the derived asset folders once (no Python or other tooling needed).
 
-Read the [Status](#status) caveats first: v0.2.0 has known rough edges,
-listed plainly there.
+Read the [Status](#status) section first: the small number of known issues
+in this release are listed plainly there.
+
+---
 
 ## Status
 
-**v0.2.0 - playable, with known rough edges.** The full single-player
-campaign is completable end to end (all 21 missions, Agent difficulty,
-playtested), at a steady 60 fps; all 21 solo missions load, render and run
-crash-free, verified on Windows, Linux and real Steam Deck hardware. Feedback
-is very welcome.
+**v0.4.0 - fully playable, with a small set of known caveats.** The full
+single-player campaign is completable end to end (all 20 missions, Agent
+difficulty, playtested), at a steady 60 fps; all 20 solo missions — plus
+the end-of-campaign credits sequence — load, render and run crash-free,
+verified on Windows, Linux and real Steam Deck hardware. The most common
+defect classes from earlier releases — particle colour drift, water seams,
+z-fighting, billboard trees, muzzle flashes, the front-end Nintendo logo,
+gunshot SFX — are fixed in this version; what remains is a short list,
+below. Feedback is very welcome.
+
+What a release actually installs (no networking, no telemetry, no ROM or
+game assets shipped) and how faithfully the port tracks the original N64
+game's logic: [Security & fidelity status](docs/security-and-fidelity-status.md).
 
 **Working:** boot sequence and front end (menu → mission select → briefing →
-start); all 21 solo missions load, render and are crash-free (full campaign
-playtested end to end at Agent difficulty); steady 60 fps
-(software RSP off the presentation critical path); full audio: in-level music and SFX; keyboard + mouse (click-to-lock, proportional aim mode) and a modern
-dual-stick controller layout; file-backed saves; faithful N64 progression by default
-(F10 → *All unlocked* opens every level, 007 mode and the full cheat menu); F10 in-game
-options overlay (resolution, frame cap, MSAA, filtering, FOV, sensitivity);
-Windows and Linux.
+start), front-end menu navigation on the left stick to match the F10 overlay
+(D282); all 20 solo missions load, render and are crash-free (full campaign
+playtested end to end at Agent difficulty, including the ending sequence); steady 60 fps
+(software RSP off the presentation critical path); full audio: in-level music and SFX; keyboard + mouse (click-to-lock, an aim style of your
+choice — N64 or centred FPS-style — with per-device sensitivity) and a modern
+dual-stick controller layout (use/reload/weapon-cycle on A/X/Y, rumble-pak
+vibration on supported pads); native widescreen at any aspect ratio
+(undistorted world, HUD anchored to the screen edges, 4:3 menus pillarboxed);
+in-game key rebinding (keyboard/mouse) with a GEPD-style default layout;
+crosshair customization (opt-in); Bond is fixed in cutscenes (no more
+floating or spin-glitching) and his third-person model positioning generally
+is right the large majority of the time now, at most a small drift when off; file-backed saves; faithful N64 progression
+by default (F10 → *All unlocked* opens every level, 007 mode and the full
+cheat menu); F10 in-game options overlay (video, input, gameplay, HUD,
+graphics, audio; frame cap, MSAA, filtering, FOV, sensitivity, key rebinding,
+crosshair, vibration); Windows and
+Linux, including Steam Deck.
 
 **Known issues:**
 
-- **Cutscenes still glitch, mostly with James Bond**: in scripted sequences
-  Bond is the one who gets misplaced, hovers, or spins; the other actors are
-  fine for the most part now. The Dam level-end cutscene is racy (D243).
-  Still the most visible gap in this release.
-- Particle colours drift through a rainbow palette instead of holding their
-  grey/orange intent (bullet sparks, lingering smoke/explosion residue) (D252).
-- Water levels show a moving seam between two water patterns (D245); thin
-  pixel strips at the left/right screen edges at non-integer window scales
-  (D246).
-- Some front-end 3D models are off: the spinning Nintendo logo renders as two
-  white blobs and the Rareware logo's texture filtering looks wrong (D75).
-- The F10 overlay's bottom row duplicates whatever item is currently selected
-  (D251).
-- **Steam Deck:** one intermittent SIGSEGV remains in heavy firefights (D255);
-  current builds capture full faulting registers in `ge007.crash.log`.
+- On Facility, if gas leaks during Ourumov's monologue he can pause for up to
+  ~10 s before resuming the scripted shootout — a latent race that exists in
+  the N64 original too (where it softlocks permanently); the port detects and
+  auto-recovers it (D318).
+- With native widescreen on, the F10 options overlay stretches with the
+  window instead of pillarboxing like the front-end menus (legible; cosmetic;
+  the F10 *Native widescreen* toggle restores the old stretched frame
+  throughout). The world/HUD widescreen rendering itself is correct (D335b).
+- The Rareware front-end logo shows a subtle texture-filtering artifact
+  (Nintendo logo and legal page are clean). Cosmetic only (D75).
+- This release ships NTSC (US) assets; PAL/JP ROMs are not supported in this
+  version (D258).
+- **`All unlocked` is experimental: back up `data/ge007.eep` before enabling
+  it.** Any save while ON, even a profile-settings change, can permanently
+  write artificial cheat unlocks and completion times into the EEPROM;
+  switching OFF does not undo them (D387). Do not use it on a save whose
+  original progression you need to preserve.
 - Assorted further cosmetic defects are tracked in
   [`docs/dev/GRAPHICS-BACKLOG.md`](docs/dev/GRAPHICS-BACKLOG.md).
-- No macOS or ARM support; no controller rebinding UI.
+- No macOS or ARM support. Keyboard/mouse rebinding shipped in v0.4.0;
+  controller-button rebinding is not supported yet.
 
-Root causes and fix status for every item: the [release notes](/jkdansereau/goldeneye-pc-port/releases)
+Root causes and fix status for every item: the [release notes](https://github.com/jkdansereau/goldeneye-pc-port/releases)
 and the finding log in [`docs/dev/findings.md`](docs/dev/findings.md).
 
 ### Steam Deck
 
 The Linux bundle is the Deck build. SFTP it over from your PC, or download
-it straight from the [releases page](/jkdansereau/goldeneye-pc-port/releases) on the Deck itself:
-unzip, drop your ROM in `data/`, launch it once (the first run generates the
+it straight from the [releases page](https://github.com/jkdansereau/goldeneye-pc-port/releases) on the Deck itself:
+extract, drop your ROM in `data/`, launch it once (the first run generates the
 derived assets), and add the executable as a non-Steam game. SDL2 is bundled, so no dependencies need
 installing. On SteamOS the first launch seeds `ge007.ini` with Deck-friendly
-defaults: native 1280×800 fullscreen, VSync, MSAA 4, and 150% draw/LOD
-distance (the authored N64 fade distances read short on the close-up panel);
-everything is changeable in the options overlay and persists afterwards. The renderer is CPU-bound (software RSP); expect original N64-era
-performance at 60 fps rather than more. This release was playtested on real
-Deck hardware; the v0.1.0-era Facility crash (D203) did not recur: its root
-cause was identified and fixed (D253), verified on the Deck; one intermittent
-SIGSEGV in heavy firefights remains open (D255).
+defaults: native 1280×800 fullscreen, VSync, 2× MSAA, and 250% draw/LOD
+distance (the N64-authored fade distances read short on the close-up 7"
+panel); everything is changeable in the options overlay and persists
+afterwards. **Do that first launch in Game Mode, not Desktop Mode** — an ini
+created by an earlier Desktop Mode launch (e.g. while testing before adding
+it as a Steam shortcut) permanently skips the Deck preset, since any
+existing ini always wins over it (D283). If your resolution isn't 1280×800
+on first Game Mode boot, just set it manually: F10 → *Resolution*. The
+renderer is CPU-bound (software RSP); expect original N64-era performance at
+60 fps rather than more. This release was playtested on real Deck hardware;
+the v0.1.0-era Facility crash (D203) did not recur: its root cause was
+identified and fixed (D253), and a separate intermittent SIGSEGV in heavy
+firefights/terminal destruction (D255) and an audio-thread crash (D305) are
+both fixed and live-verified on real hardware as of this release.
 
 **In-game settings on the Deck.** The options overlay is fully gamepad-driven:
 it opens with **Select**, the D-pad or left stick (up/down) moves between
@@ -123,11 +187,36 @@ options, **A** steps the selected option forward, **B** steps it back, and
 filtering cycle, sliders step in increments. With a keyboard attached the same
 overlay is `F10` + arrows/Enter.
 
+---
+
+## Roadmap
+
+No fixed timeline or committed feature list — this is spare-time work — but
+directionally, on the way to v1.0:
+
+- Working through the [known issues](#status) above and the fuller list in
+  [`docs/dev/findings.md`](docs/dev/findings.md).
+- **PAL and JP ROM support** ([issue #85](https://github.com/jkdansereau/goldeneye-pc-port/issues/85)); NTSC-U is the only supported region today.
+- **Controller (pad) button rebinding UI** (keyboard/mouse rebinding shipped
+  in v0.4.0), and macOS/ARM builds.
+- **LAN multiplayer**: reviving GoldenEye's original split-screen/deathmatch
+  netplay across multiple PCs on a local network. Genuinely under
+  consideration, but early and not started; no ETA.
+- General polish: performance, remaining rendering/audio defects, save/config
+  robustness.
+
+Not currently planned: new game modes GE never shipped (e.g. co-op), online (non-LAN)
+multiplayer, ray tracing. If any of these matter to you, open an issue —
+it helps prioritize.
+
+---
+
 ## Beyond playing
 
 - **Tweak it**: `ge007.ini` and the F10 in-game overlay expose resolution,
-  frame cap, MSAA, texture filtering, FOV/draw distance and mouse feel;
-  launch with `-fresh` for a clean-slate run.
+  frame cap, MSAA, texture filtering, FOV/draw distance, mouse feel, key
+  rebinding, crosshair and vibration; launch with `-fresh` for a clean-slate
+  run.
 - **Read it**: [`docs/internals.md`](docs/internals.md) maps the
   architecture and the software RSP; [`docs/porting-notes.md`](docs/porting-notes.md)
   is the catalogue of N64→PC bug classes hit along the way. Game logic in
@@ -138,6 +227,8 @@ overlay is `F10` + arrows/Enter.
   the ground rules for getting changes in, and [`docs/dev/`](docs/dev/) is
   the raw engineering record behind every fix.
 
+---
+
 ## Background
 
 The port was built by two coding agents, a local open-weight model
@@ -147,7 +238,8 @@ asset pipeline, first frames), and **Claude Code** (Sonnet 5, Opus 5 for the
 hardest bugs) joining for the collaborative phase (the 21-level sweep, the
 ABI finding catalog, SDL input, front end), handing work back and forth
 through shared written notes, directed by one person part-time. In short:
-~3.5 weeks, ~430 commits, 200+ bugs logged and tracked to resolution.
+43 days (16 Aug – 28 Sep), 1005 commits, 286 findings root-caused and logged
+(`D1`–`D408`).
 
 The full write-up (timeline, handoff mechanism, effort breakdown, an honest
 "what worked / what didn't"): [`docs/dev/agentic-development.md`](docs/dev/agentic-development.md).
@@ -155,6 +247,8 @@ The workflow itself: [`docs/dev-process.md`](docs/dev-process.md). To cite the
 project or its findings: [`CITATION.cff`](CITATION.cff) (GitHub's "Cite this
 repository" menu).
 
+---
+
 ## How this differs from the other GoldenEye PC projects
 
 This is a native port of the original 1997 Nintendo 64 game, built from its
@@ -170,13 +264,15 @@ code with this one.
 | **How** | Decompilation-based source port: human-reconstructed C, compiled for the host; game logic runs as written | Static binary recompilation: the shipped machine code is auto-translated to C; no source-level understanding |
 | **Lineage** | [GoldenEye 007 decompilation](https://github.com/n64decomp/007) + [Perfect Dark PC port](https://github.com/fgsfdsfgs/perfect_dark) engine family | Xbox 360 "…Recompiled" static-recompilation family |
 | **Renderer** | Software RSP → OpenGL | Hardware (Vulkan) |
-| **Status** | v0.2.0 public release; full campaign playable at 60 fps (see [Status](#status)) | Playable full game with online multiplayer |
+| **Status** | v0.4.0 public release; full campaign playable at 60 fps (see [Status](#status)) | Playable full game |
 | **Why it exists** | To run the *original* N64 game from source, and as a [case study in AI-agent collaboration](#background) on a hard low-level codebase | To get a playable PC release of the remaster |
 
 They answer a different question: how to get the *remaster* onto PC by
 machine translation. This project answers how to get the *original 1997
 game* onto PC, running from its reconstructed source.
 
+---
+
 ## Requirements
 
 You need a GoldenEye 007 (Nintendo 64) ROM that you legally own, in
@@ -190,12 +286,14 @@ big-endian (`.z64`) format, matching one of:
 
 This release supports the US (NTSC-U) version; PAL and JP ROMs are
 recognised by region but not yet supported (on the roadmap, [issue
-#85](/jkdansereau/goldeneye-pc-port/issues/85)).
+#85](https://github.com/jkdansereau/goldeneye-pc-port/issues/85)).
 
 The port also relies on the decompilation's asset-extraction step, which pulls
 the level, model, texture and music data out of your ROM at build time. That
 step, too, requires your ROM and is part of [Building](#building).
 
+---
+
 ## Building
 
 Prerequisites: CMake >= 3.16, a C/C++ toolchain, SDL2, zlib, OpenGL, Python 3,
@@ -235,6 +333,8 @@ cd goldeneye-pc-port
 The executable is written to `build-pc/ge007.x86_64` (on Windows,
 `build-pc/ge007.x86_64.exe`).
 
+---
+
 ## Running
 
 1. Create a `data/` directory in the repo root.
@@ -253,21 +353,33 @@ lives in `ge007.eep`. Launch with `-fresh` to wipe both before starting
 |---------------------|--------------------------|---------------|
 | Move / strafe       | `W` `A` `S` `D` / arrows  | Left stick (or D-pad) |
 | Aim / look          | Mouse                    | Right stick   |
-| Fire (Z)            | Left mouse / `LCtrl`     | Right trigger |
-| Aim mode (R)        | Right mouse / `LShift`   | Left trigger  |
-| Use / accept (A)    | `Space` / `E` / `X`      | A / X         |
-| Reload / cancel (B) | `R` / `F`                | B / Y         |
-| Next weapon         | Mouse wheel up           | RB            |
-| Previous weapon     | Mouse wheel down         | LB            |
+| Fire                | Left mouse               | Right trigger |
+| Aim mode            | Right mouse / `LShift`   | Left trigger / LB |
+| Use / interact      | `E`                       | A             |
+| Reload              | `R`                       | X             |
+| Crouch              | `LCtrl`                   | Left or right stick click |
+| Cycle owned gadgets | Watch inventory          | B             |
+| Next weapon         | Mouse wheel down / `Q`   | Y             |
+| Previous weapon     | Mouse wheel up           | —             |
 | Start               | `Enter` / `Tab`          | Start         |
-| Options overlay     | `F10`                    | Select (D-pad/stick + A/B navigate, Start closes) |
+| Options overlay     | `F10`                    | Select (A toggles/steps; B backs; D-pad/stick adjusts sliders; Start closes) |
 
-The controller layout follows the modern dual-stick scheme used by the
-console re-releases (left stick move, right stick look, triggers fire/aim,
-shoulders cycle weapons).
+The default layout is the GEPD-style preset on the keyboard and the standard
+dual-stick scheme on controllers (left stick move, right stick look,
+triggers fire/aim, A use, X reload, B gadget cycle, Y weapon cycle, stick
+click crouch). The watch gadget cycle selects the next owned gadget in the
+N64 inventory. The controller layout matches Rare's Xbox 1.1 (Jinx) button
+roles (user-tested on a physical pad; D394), and the remaining Xbox schemes
+(1.2 Christmas, 1.3 Frost, 1.4 Elektra) are planned as selectable presets
+and not yet available. Keyboard → Bindings edits **keyboard/mouse only**; a
+controller can navigate those pages and use B to go back, but
+controller-button rebinding is not supported yet.
 
 Mouse sensitivity, Y-inversion and the aim/turn split are tunable in the
-`[Input]` section of `ge007.ini`.
+F10 overlay (*Keyboard → Sensitivity*) or the `[Input]` section of
+`ge007.ini`.
+
+---
 
 ## How it works
 
@@ -300,6 +412,8 @@ tools_pc/           PC-port helper + analysis scripts
 docs/               see below
 ```
 
+---
+
 ## Documentation
 
 Key docs are also published as a site:
@@ -315,6 +429,8 @@ Key docs are also published as a site:
 | [`docs/dev/`](docs/dev/) | The raw engineering record: the full finding log, per-level status, graphics backlog, playtest matrices, and [`docs/dev/game-behavior-reference.md`](docs/dev/game-behavior-reference.md) (a secondary-sourced playtest reference for how the retail game is meant to behave; repo-only, code is ground truth). |
 | [`docs/SetupGuide.md`](docs/SetupGuide.md), [`docs/StyleGuide.md`](docs/StyleGuide.md) | Inherited from the decompilation this repo forks. |
 
+---
+
 ## Credits
 
 This port is a thin layer on a large amount of other people's work.
@@ -357,16 +473,23 @@ This port is a thin layer on a large amount of other people's work.
   Kids decompilation write-up), the agent-workflow practices in
   [`docs/dev-process.md`](docs/dev-process.md) are adapted from it.
 
+**Consultation**
+
+- **f1zz1ec0ke** ([GitHub](https://github.com/f1zz1ec0ke)): LLM consultation on model
+  tuning, agent harnesses, and agentic strategy throughout the port's development.
+
 **Tools and models used to develop the port**
 
-- Qwen 3.8 (Alibaba Qwen team), run locally as the
+- Qwen 3.8 (Alibaba Qwen team), run locally from the
   [`unsloth/Qwen3.8-27B-GGUF`](https://huggingface.co/unsloth/Qwen3.8-27B-GGUF)
-  `UD-Q4_K_XL` quant;
-  [Unsloth](https://unsloth.ai) (the GGUF quantisation and Unsloth Desktop,
-  used as the local model server).
+  repo — `UD-Q4_K_XL` as the primary quant, with other quants used along the
+  way; [Unsloth](https://unsloth.ai) (the GGUF quantisation and Unsloth
+  Desktop) as the local model server.
 - [pi](https://pi.dev/): the local coding-agent harness.
 - [Claude / Claude Code](https://claude.com/claude-code) (Anthropic).
 
+---
+
 ## Legal
 
 This is a non-commercial fan preservation/research project, in the same
@@ -382,7 +505,7 @@ GitHub. It follows the same conventions they do:
 - No official logos, box art, or marketing assets are used. "GoldenEye 007",
   "007", "James Bond" and related marks belong to their respective owners
   (Nintendo, Microsoft/Rare, MGM, Danjaq, EON Productions).
-- Pre-built binaries published under [Releases](/jkdansereau/goldeneye-pc-port/releases) contain
+- Pre-built binaries published under [Releases](https://github.com/jkdansereau/goldeneye-pc-port/releases) contain
   only the engine (the `port/` layer plus the compiled decompilation, with no
   game data of any kind), bundled with permissively-licensed runtime libraries
   (SDL2, zlib, the MinGW runtime; their licenses travel in the download). Any
@@ -399,3 +522,7 @@ The original work in this repository, the port layer (`port/`), the PC build
 system, `tools_pc/`, and the documentation, is released under the MIT License;
 see [`LICENSE`](LICENSE). Everything inherited from the upstream decompilation
 is covered by [`NOTICE`](NOTICE), not by that license.
+
+---
+
+*Last updated 2026-09-28 — v0.4.0 · <a href="https://github.com/jkdansereau/goldeneye-pc-port">GitHub</a> · <a href="https://github.com/jkdansereau/goldeneye-pc-port/releases">Releases</a>*

build-pc.sh

@@ -14,7 +14,7 @@
 # Example (Linux):
 #   sudo apt install cmake libsdl2-dev zlib1g-dev libgl1-mesa-dev
 # Example (macOS):
-#   brew install cmake sdl2 zlib
+#   brew install cmake libsdl2-dev
 # Example (Windows/MSYS2):
 #   pacman -S mingw-w64-x86_64-toolchain mingw-w64-x86_64-SDL2 \
 #             mingw-w64-x86_64-zlib mingw-w64-x86_64-cmake
@@ -24,6 +24,132 @@ set -euo pipefail
 ROMID="${1:-ntsc-final}"
 BUILD_DIR="${BUILD_DIR:-build-pc}"
 
+# ---------------------------------------------------------------------------
+# Windows toolchain env guard (see AGENTS.md "Build" — the recurring
+# "Cannot create temporary file in C:\Windows\: Permission denied" link
+# failure).
+#
+# The PE toolchain (ninja -> cmd -> gcc/ld) creates temp files under the
+# child's TMP/TEMP. A full MSYS2 MINGW64 login shell arranges that for
+# native children; other shells (agent harnesses, non-login shells) do not
+# -- the msys->native env conversion silently drops/breaks TMP and the
+# linker falls back to C:\Windows\. Probe what a native child actually
+# sees (via a file: msys console emulation makes piped cmd.exe stdout
+# unreliable), and if broken, re-run the cmake+build steps under
+# PowerShell. Crucially the temp vars are set INSIDE PowerShell: the broken
+# boundary is msys->native, while native->native (powershell -> cmake ->
+# ninja) passes env vars through intact.
+# GE_PC_BUILD_VIA_NATIVE=1 prevents a re-exec loop.
+# ---------------------------------------------------------------------------
+if [ -n "${MSYSTEM:-}" ] && [ -z "${GE_PC_BUILD_VIA_NATIVE:-}" ]; then
+    _probe="$(mktemp -d "${TMPDIR:-/tmp}/gebuildprobe.XXXXXX")"
+    _probe_win="$(cygpath -w "${_probe}" 2>/dev/null || echo 'C:\\msys64\\tmp')"
+    /c/Windows/system32/cmd.exe //c "if exist \"%TMP%\" (echo ok > \"${_probe_win}/ok.txt\") else (echo bad > \"${_probe_win}/bad.txt\")" >/dev/null 2>&1 || true
+    if [ ! -s "${_probe}/ok.txt" ]; then
+        command -v powershell >/dev/null 2>&1 || {
+            echo "ERROR: native TMP is unusable from this shell and powershell.exe was not found for the fallback." >&2
+            echo "Manual fix: run cmake+ninja from cmd/PowerShell with C:\\msys64\\mingw64\\bin on PATH, or" >&2
+            echo "set the user env vars (setx TMP \"C:\\msys64\\tmp\"; setx TEMP \"C:\\msys64\\tmp\") and re-open the shell." >&2
+            rm -rf "${_probe}"; exit 1
+        }
+        echo "==> native TMP unusable from this shell; re-running cmake+build via PowerShell"
+        export GE_PC_BUILD_VIA_NATIVE=1
+        _here="$(pwd -W 2>/dev/null || cygpath -w "$(pwd)")"
+        # Resolve the Windows-side toolchain paths from what msys found (no
+        # hardcoded install dir: C:\msys64 on this box, D:\M\msys64
+        # elsewhere). usr/bin first: mingw gcc.exe needs msys-2.0.dll from
+        # there.
+        _cmake_root="$(dirname "$(command -v cmake)")"          # .../mingw64/bin
+        _msys_root="$(cd "${_cmake_root}/../.." && pwd -W 2>/dev/null || cygpath -w "$(cd "${_cmake_root}/../.." && pwd)")"  # msys install root (.. twice: bin -> mingw64 -> root)
+        _bin_w="$(cygpath -w "${_cmake_root}")"
+        _usrbin_w="$(cygpath -w "${_msys_root}/usr/bin")"
+        # The PowerShell script is written to a .ps1 FILE, not passed via
+        # -Command: the msys->native argv conversion mangles $-bearing
+        # strings (a '\$LASTEXITCODE' check arrived as an empty token and a
+        # failed cmake would have exited 0 silently). A file write is
+        # conversion-free; only plain path/word arguments cross the boundary.
+        _ps1="$(mktemp "${TMPDIR:-/tmp}/ge007-rerun.XXXXXX.ps1")"
+        cat > "${_ps1}" <<'PS1'
+param([string]$UsrBin, [string]$Bin, [string]$MsysRoot, [string]$Here, [string]$BuildDir, [string]$RomId)
+# Self-logging: a headless shell loses this process's console output, so
+# every fact that matters goes to diag/log files in the build dir.
+$diag = Join-Path $BuildDir "ge007-native-reexec-diag.log"
+$cmakeLog = Join-Path $BuildDir "ge007-native-reexec-cmake.log"
+$buildLog = Join-Path $BuildDir "ge007-native-reexec-build.log"
+# The inherited native PATH may be mangled/dropped by the broken msys->native
+# env conversion, so build it explicitly: the toolchain only needs the two
+# msys bin dirs plus the usual system dirs. (usr/bin first: mingw gcc/cmake
+# need msys-2.0.dll from there.)
+$env:PATH = "$UsrBin;$Bin;C:\Windows\System32;C:\Windows;C:\Windows\System32\Wbem"
+# Writable temp for the native toolchain. [System.IO.Path]::GetTempPath()
+# CANNOT be used here: it honours the inherited (broken) TMP/TEMP env vars
+# and returned C:\Windows\. Pick the first writable candidate instead.
+$tmpdir = $null
+foreach ($cand in @((Join-Path ([Environment]::GetFolderPath('LocalApplicationData')) 'Temp'), (Join-Path $MsysRoot 'tmp'))) {
+    try {
+        if (-not (Test-Path $cand)) { New-Item -ItemType Directory -Force -Path $cand -ErrorAction Stop | Out-Null }
+        $probe = Join-Path $cand 'ge007-tmp-write-test.tmp'
+        'x' | Out-File -FilePath $probe -ErrorAction Stop
+        Remove-Item $probe -ErrorAction SilentlyContinue
+        $tmpdir = $cand
+        break
+    } catch { }
+}
+if ($null -eq $tmpdir) { "no writable temp dir found" | Out-File $diag -Encoding ascii; Write-Host 'no writable temp dir for the native toolchain'; exit 4 }
+$env:TMP = $tmpdir
+$env:TEMP = $tmpdir
+"start UsrBin=[$UsrBin] Bin=[$Bin] MsysRoot=[$MsysRoot] Here=[$Here] BuildDir=[$BuildDir] RomId=[$RomId] tmp=[$tmpdir]" | Out-File $diag -Encoding ascii
+$exe = "$Bin\cmake.exe"
+"exe=[$exe] exists=[$(Test-Path -LiteralPath $exe)]" | Out-File $diag -Append -Encoding ascii
+Set-Location $Here
+"cwd=[$([System.IO.Directory]::GetCurrentDirectory())]" | Out-File $diag -Append -Encoding ascii
+try {
+    # -DROMID must be a DOUBLE-QUOTED string: a bare `-DROMID=$RomId` token
+    # does NOT expand the variable in PowerShell (cmake got the literal
+    # "$RomId" and failed with "Unknown ROMID").
+    $out = & $exe -S . -B $BuildDir "-DROMID=$RomId" 2>&1
+    "cmake ran LASTEXITCODE=[$LASTEXITCODE]" | Out-File $diag -Append -Encoding ascii
+    $out | Out-File -FilePath $cmakeLog -Encoding ascii
+} catch {
+    "cmake TERMINAL ERROR: $($_.Exception.Message)" | Out-File $diag -Append -Encoding ascii
+}
+if ($null -eq $LASTEXITCODE) { Write-Host "cmake.exe did not execute (diag: $diag)"; exit 2 }
+if ($LASTEXITCODE -ne 0) { Write-Host "cmake re-configure failed (rc=$LASTEXITCODE; log: $cmakeLog)"; exit $LASTEXITCODE }
+Write-Host "cmake reconfigured (TMP=$($env:TMP))"
+try {
+    $out = & $exe --build $BuildDir -j 2>&1
+    "build ran LASTEXITCODE=[$LASTEXITCODE]" | Out-File $diag -Append -Encoding ascii
+    $out | Out-File -FilePath $buildLog -Encoding ascii
+} catch {
+    "build TERMINAL ERROR: $($_.Exception.Message)" | Out-File $diag -Append -Encoding ascii
+}
+if ($null -eq $LASTEXITCODE) { Write-Host "cmake --build did not execute (diag: $diag)"; exit 3 }
+if ($LASTEXITCODE -ne 0) { Write-Host "build failed (rc=$LASTEXITCODE; log: $buildLog)"; exit $LASTEXITCODE }
+"done" | Out-File $diag -Append -Encoding ascii
+Write-Host "cmake + build ok (native re-exec, TMP=$($env:TMP))"
+PS1
+        _ps1_win="$(cygpath -w "${_ps1}")"
+        rc=0
+        # NOTE: do NOT launch powershell via `env -i` (tried 2026-09-28): a
+        # native child started with a scrubbed msys env cannot launch
+        # cmake.exe (CreateProcess fails silently; LASTEXITCODE stays null).
+        powershell -NoProfile -ExecutionPolicy Bypass -File "${_ps1_win}" "${_usrbin_w}" "${_bin_w}" "${_msys_root}" "${_here}" "${BUILD_DIR}" "${ROMID}" || rc=$?
+        rm -f "${_ps1}"
+        if [ "${rc}" -ne 0 ]; then
+            # Surface the .ps1's own diagnostics (console output is lost in a
+            # headless shell) plus whatever the failing step wrote.
+            for _lg in "${BUILD_DIR}/ge007-native-reexec-diag.log" "${BUILD_DIR}/ge007-native-reexec-cmake.log" "${BUILD_DIR}/ge007-native-reexec-build.log"; do
+                if [ -s "${_lg}" ]; then
+                    echo "---- ${_lg} (last 40 lines) ----" >&2
+                    tail -40 "${_lg}" >&2
+                fi
+            done
+        fi
+        exit "${rc}"
+    fi
+    rm -rf "${_probe}"
+fi
+
 echo "==> Configuring PC port (ROMID=${ROMID})"
 cmake -S . -B "${BUILD_DIR}" -DROMID="${ROMID}"
 

docs/_config.yml

@@ -1,11 +1,15 @@
 # GitHub Pages config. Site is served from the /docs folder on the default
 # branch (Settings -> Pages -> Deploy from a branch -> main / docs).
 title: GoldenEye 007 PC Port
-description: >-
-  A native PC port of the original Nintendo 64 GoldenEye 007, built from its
-  decompiled source with a software RSP — plus the engineering record:
-  internals, porting notes, and the two-agent development workflow.
-theme: jekyll-theme-cayman
+# v0.2.1 (Bing SEO): keep this SHORT -- jekyll-seo-tag splices it into the
+# home page <title> whenever the page title equals the site title, and the
+# long version made a ~230-char title. It also renders as the masthead
+# tagline on every page. Per-page meta/og descriptions come from each page's
+# front matter `description:` (see index.md), not from here.
+description: GoldenEye 007 (Nintendo 64, 1997) on the PC - decompiled, ported, and playable.
+# No GitHub theme: the site uses a hand-rolled _layouts/default.html plus the
+# design in _includes/head-custom.html (charcoal/off-white/amber, square and
+# flat.)
 show_downloads: false
 
 # Canonical site location - used by jekyll-seo-tag (canonical URLs, og: tags)

docs/_includes/head-custom.html

@@ -3,267 +3,242 @@
 
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500&display=swap" rel="stylesheet">
+<link href="https://fonts.googleapis.com/css2?family=Libre+Baskerville:ital,wght@0,400;0,700;1,400&display=swap" rel="stylesheet">
 
 <style>
   /* ----------------------------------------------------------------------
-     Design pass over the stock Cayman theme.
-     Restrained "spy-tech" palette: near-black, slate, a single amber accent.
-     Loaded after the theme stylesheet, so these rules win without !important.
+     Hand-rolled site theme (replaces jekyll-theme-cayman, 2026-09-28).
+     Look: committed charcoal/off-white/amber "night desk" — flat and square,
+     serif display type (Libre Baskerville) over a system sans body, thin
+     amber rules between sections, text navigation separated by middots.
+     No gradients, no shadows, no rounded corners, no theme switcher.
      --------------------------------------------------------------------- */
   :root {
-    color-scheme: light dark;
-    --ink:        #14171c;
-    --ink-soft:   #3d444d;
-    --ink-mute:   #626b76;
-    --line:       #e4e6e9;
-    --bg:         #ffffff;
-    --bg-soft:    #f7f8fa;
-    --accent:     #b7791f;
-    --accent-ink: #8a5a12;
-    --header-1:   #0d1117;
-    --header-2:   #1c2530;
-    --radius:     8px;
-    --measure:    44rem;
+    --bg:        #1b1b1d;   /* charcoal page            */
+    --bg-soft:   #232326;   /* code / alt rows          */
+    --bg-deep:   #141416;   /* code blocks, masthead    */
+    --ink:       #e8e6e3;   /* off-white body text      */
+    --ink-soft:  #b5b1a9;   /* secondary text           */
+    --ink-mute:  #8d897f;   /* captions, footer         */
+    --line:      #3a3a3e;   /* 1px borders              */
+    --accent:    #ffb454;   /* amber/gold               */
+    --accent-hi: #ffd08a;   /* link hover               */
+    --measure:   44rem;
   }
 
-  @media (prefers-color-scheme: dark) {
-    :root {
-      --ink:      #e7eaee;
-      --ink-soft: #b9c0c9;
-      --ink-mute: #8b939e;
-      --line:     #2a2f37;
-      --bg:       #0f1216;
-      --bg-soft:  #171b21;
-      --accent:   #e0a94a;
-      --accent-ink: #f0c274;
-      --header-1: #0a0d11;
-      --header-2: #161d27;
-    }
-  }
+  html { background: var(--bg); }
 
   body {
-    font-family: "IBM Plex Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+    margin: 0;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+                 "Helvetica Neue", Arial, sans-serif;
+    font-size: 16.5px;
+    line-height: 1.7;
     color: var(--ink);
     background: var(--bg);
-    font-size: 17px;
-    line-height: 1.7;
     -webkit-font-smoothing: antialiased;
     text-rendering: optimizeLegibility;
   }
 
-  /* ---- Header --------------------------------------------------------- */
-  .page-header {
-    position: relative;
-    isolation: isolate;
-    text-align: center;
-    padding: 4rem 1rem 3.75rem;
-    background: linear-gradient(135deg, var(--header-1), var(--header-2));
-    border-bottom: 1px solid rgba(224, 169, 74, 0.28);
+  /* ---- Masthead -------------------------------------------------------- */
+  .site-masthead {
+    background: var(--bg-deep);
+    border-bottom: 1px solid var(--accent);
   }
-  .page-header::before {
-    content: "";
-    position: absolute;
-    inset: 0;
-    z-index: -1;
-    background-image: url("{{ '/img/attract-bunker1.png' | relative_url }}");
-    background-size: cover;
-    background-position: center 38%;
-    opacity: 0.16;
-    filter: grayscale(0.35) contrast(1.05);
-  }
-  .page-header::after {
-    content: "";
-    position: absolute;
-    inset: 0;
-    z-index: -1;
-    background: linear-gradient(180deg, rgba(13,17,23,0.35), rgba(13,17,23,0.82));
-  }
-  .project-name {
-    font-weight: 700;
-    letter-spacing: -0.02em;
-    font-size: 2.4rem;
-    margin: 0 0 0.4rem;
-    color: #fff;
-    text-shadow: 0 1px 24px rgba(0,0,0,0.5);
-  }
-  .project-tagline {
-    font-weight: 400;
-    font-size: 1.12rem;
-    line-height: 1.55;
-    color: #d3d9e0;
-    opacity: 1;
-    max-width: 42rem;
-    margin: 0 auto 1.6rem;
-  }
-  .page-header .btn {
-    display: inline-block;
-    padding: 0.5rem 1.1rem;
-    margin: 0.3rem 0.25rem 0;
-    font-size: 0.9rem;
-    font-weight: 500;
-    letter-spacing: 0.01em;
-    color: #f3f5f7;
-    background: rgba(255,255,255,0.06);
-    border: 1px solid rgba(255,255,255,0.22);
-    border-radius: var(--radius);
-    transition: background 0.15s ease, border-color 0.15s ease, transform 0.15s ease;
-  }
-  .page-header .btn:hover {
-    background: rgba(224,169,74,0.16);
-    border-color: var(--accent);
-    text-decoration: none;
-    transform: translateY(-1px);
-  }
-
-  /* ---- Body ---------------------------------------------------------- */
-  .main-content {
+  .masthead-inner {
     max-width: 52rem;
     margin: 0 auto;
-    padding: 3rem 1.5rem 1rem;
-    color: var(--ink);
-    font-size: 17px;
+    padding: 2.6rem 1.5rem 1.6rem;
+    text-align: center;
   }
-  .main-content p,
-  .main-content ul,
-  .main-content ol,
-  .main-content blockquote { max-width: var(--measure); }
+  .masthead-title {
+    display: inline-block;
+    font-family: "Libre Baskerville", Georgia, "Times New Roman", serif;
+    font-weight: 700;
+    font-size: 2.1rem;
+    line-height: 1.25;
+    color: var(--ink);
+    text-decoration: none;
+    letter-spacing: 0.01em;
+  }
+  .masthead-title:hover { color: var(--accent); }
+  .masthead-tagline {
+    margin-top: 0.5rem;
+    color: var(--ink-mute);
+    font-size: 0.95rem;
+  }
+  .masthead-nav {
+    margin-top: 1.3rem;
+    font-size: 0.9rem;
+  }
+  .masthead-nav a {
+    color: var(--accent);
+    text-decoration: none;
+    padding: 0.1rem 0.15rem;
+  }
+  .masthead-nav a:hover { color: var(--accent-hi); text-decoration: underline; }
+  .nav-sep { color: var(--ink-mute); padding: 0 0.35rem; }
 
-  .main-content h1,
-  .main-content h2,
-  .main-content h3,
-  .main-content h4 {
+  /* ---- Content ---------------------------------------------------------- */
+  .doc-content {
+    max-width: 52rem;
+    margin: 0 auto;
+    padding: 2.5rem 1.5rem 1rem;
+  }
+  .doc-content p,
+  .doc-content ul,
+  .doc-content ol,
+  .doc-content blockquote { max-width: var(--measure); }
+
+  .doc-content h1,
+  .doc-content h2,
+  .doc-content h3,
+  .doc-content h4 {
+    font-family: "Libre Baskerville", Georgia, "Times New Roman", serif;
+    font-weight: 700;
+    line-height: 1.35;
     color: var(--ink);
-    font-weight: 600;
-    letter-spacing: -0.015em;
-    line-height: 1.3;
     margin-top: 2.4rem;
+    margin-bottom: 0.9rem;
   }
-  .main-content h1 { font-size: 1.9rem; }
-  .main-content h2 {
-    font-size: 1.4rem;
-    padding-bottom: 0.35rem;
-    border-bottom: 1px solid var(--line);
-  }
-  .main-content h3 { font-size: 1.15rem; }
-  .main-content > h1:first-child { margin-top: 0.5rem; }
+  .doc-content h1 { font-size: 1.75rem; }
+  .doc-content h2 { font-size: 1.35rem; }
+  .doc-content h3 { font-size: 1.1rem; }
+  .doc-content > h1:first-child { margin-top: 0.5rem; }
 
-  .main-content a {
-    color: var(--accent-ink);
+  .doc-content a {
+    color: var(--accent);
     text-decoration: underline;
-    text-decoration-color: rgba(183,121,31,0.4);
+    text-decoration-color: rgba(255, 180, 84, 0.45);
     text-underline-offset: 2px;
   }
-  .main-content a:hover {
-    color: var(--accent);
+  .doc-content a:hover {
+    color: var(--accent-hi);
     text-decoration-color: currentColor;
   }
-  @media (prefers-color-scheme: dark) {
-    .main-content a { color: var(--accent); }
+
+  .doc-content hr {
+    border: 0;
+    height: 1px;
+    background: var(--accent);
+    opacity: 0.5;
+    margin: 2.5rem 0;
   }
 
-  .main-content blockquote {
-    color: var(--ink-mute);
+  .doc-content blockquote {
+    color: var(--ink-soft);
     border-left: 3px solid var(--accent);
     padding: 0.2rem 0 0.2rem 1.1rem;
     margin-left: 0;
     font-style: normal;
   }
 
-  .main-content hr {
-    height: 1px;
-    background: var(--line);
-    border: 0;
-    margin: 2.5rem 0;
-  }
-
   /* Lead paragraph on doc pages (the italic summary under the H1) */
-  .main-content > p > em:only-child {
+  .doc-content > p > em:only-child {
     font-style: normal;
     color: var(--ink-soft);
     font-size: 1.05rem;
   }
 
-  /* ---- Code --------------------------------------------------------- */
-  .main-content code {
-    font-family: "IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
+  /* ---- Code ------------------------------------------------------------ */
+  .doc-content code {
+    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
     font-size: 0.86em;
     background: var(--bg-soft);
     border: 1px solid var(--line);
-    border-radius: 4px;
     padding: 0.12em 0.4em;
     color: var(--ink);
   }
-  .main-content pre {
-    background: var(--header-1);
+  .doc-content pre {
+    background: var(--bg-deep);
     border: 1px solid var(--line);
-    border-radius: var(--radius);
     padding: 1rem 1.15rem;
     max-width: var(--measure);
     overflow-x: auto;
+    line-height: 1.55;
   }
-  .main-content pre code {
+  .doc-content pre code {
     background: transparent;
     border: 0;
     padding: 0;
-    color: #e6edf3;
+    color: var(--ink);
     font-size: 0.84rem;
   }
 
-  /* ---- Tables ------------------------------------------------------- */
-  .main-content table {
+  /* ---- Tables ----------------------------------------------------------- */
+  .doc-content table {
     border-collapse: collapse;
-    display: table;
     width: 100%;
     max-width: var(--measure);
     margin: 1.5rem 0;
     font-size: 0.92rem;
   }
-  .main-content table th,
-  .main-content table td {
+  .doc-content table th,
+  .doc-content table td {
     border: 1px solid var(--line);
     padding: 0.5rem 0.75rem;
+    text-align: left;
   }
-  .main-content table th { background: var(--bg-soft); font-weight: 600; }
-  .main-content table tr { background: transparent; }
-  .main-content table tr:nth-child(2n) { background: var(--bg-soft); }
+  .doc-content table th { background: var(--bg-soft); font-weight: 600; }
+  .doc-content table tr:nth-child(2n) { background: #1f1f22; }
 
-  .main-content img {
-    border-radius: var(--radius);
+  /* ---- Images & gallery -------------------------------------------------- */
+  .doc-content img {
     border: 1px solid var(--line);
+    border-radius: 0;
+    max-width: 100%;
   }
 
-  /* ---- Footer ------------------------------------------------------- */
+  .doc-content details {
+    max-width: var(--measure);
+    border: 1px solid var(--line);
+    background: var(--bg-soft);
+    padding: 0.6rem 0.9rem;
+    margin: 1.5rem 0;
+  }
+  .doc-content summary { cursor: pointer; color: var(--accent); }
+
+  /* ---- Footer ------------------------------------------------------------- */
   .site-footer {
     max-width: 52rem;
     margin: 3rem auto 0;
     padding: 1.5rem 1.5rem 2.5rem;
     border-top: 1px solid var(--line);
-    color: var(--ink-mute);
-    font-size: 0.86rem;
   }
-  .site-footer a { color: var(--accent-ink); }
-  @media (prefers-color-scheme: dark) { .site-footer a { color: var(--accent); } }
+  .footer-inner { max-width: var(--measure); }
+  .footer-stamp {
+    color: var(--ink-soft);
+    font-size: 0.88rem;
+    margin: 0 0 0.8rem;
+  }
+  .footer-stamp a { color: var(--accent); text-decoration: none; }
+  .footer-stamp a:hover { color: var(--accent-hi); text-decoration: underline; }
+  .footer-legal {
+    color: var(--ink-mute);
+    font-size: 0.8rem;
+    line-height: 1.6;
+    margin: 0;
+  }
 
   @media (max-width: 42rem) {
-    .project-name { font-size: 1.9rem; }
-    .page-header { padding: 3rem 1rem 2.75rem; }
-    .main-content { padding-top: 2rem; }
+    .masthead-title { font-size: 1.7rem; }
+    .masthead-inner { padding: 2rem 1rem 1.2rem; }
+    .doc-content { padding-top: 1.8rem; }
   }
 
-  /* ---- Mermaid diagrams ------------------------------------------------ */
+  /* ---- Mermaid diagrams ---------------------------------------------------- */
   /* Kramdown renders ```mermaid fences as <pre><code class="language-mermaid">.
      The script below hands their text to mermaid and swaps in the SVG. Keep
-     the pre unstyled (no dark code background) while it waits to render. */
-  .main-content pre.mermaid,
-  .main-content pre > code.language-mermaid {
+     the pre unstyled (no code-block background) while it waits to render. */
+  .doc-content pre.mermaid,
+  .doc-content pre > code.language-mermaid {
     background: transparent;
     border: 0;
     color: var(--ink);
     padding: 0;
   }
-  .main-content pre.mermaid { text-align: center; overflow-x: auto; }
-  .main-content pre.mermaid:not([data-processed]) { visibility: hidden; }
+  .doc-content pre.mermaid { text-align: center; overflow-x: auto; }
+  .doc-content pre.mermaid:not([data-processed]) { visibility: hidden; }
 </style>
 
 <script type="module">
@@ -271,7 +246,6 @@
 
   // Move each ```mermaid code block's text into a <pre class="mermaid"> that
   // mermaid.run() recognises.
-  const dark = window.matchMedia("(prefers-color-scheme: dark)").matches;
   document.querySelectorAll("pre > code.language-mermaid").forEach((code) => {
     const pre = document.createElement("pre");
     pre.className = "mermaid";
@@ -282,7 +256,7 @@
   mermaid.initialize({
     startOnLoad: false,
     securityLevel: "loose", // our own docs; needed for <br/> in node labels
-    theme: dark ? "dark" : "neutral",
+    theme: "dark",
   });
   mermaid.run({ querySelector: "pre.mermaid" });
 </script>

docs/_layouts/default.html

@@ -0,0 +1,48 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <link rel="icon" type="image/png" href="{{ '/img/attract-bunker1.png' | relative_url }}">
+  {%- seo -%}
+  {%- include head-custom.html -%}
+</head>
+<body>
+  <header class="site-masthead">
+    <div class="masthead-inner">
+      <a class="masthead-title" href="{{ '/' | relative_url }}">{{ site.title }}</a>
+      <div class="masthead-tagline">{{ site.description }}</div>
+      <nav class="masthead-nav">
+        <a href="{{ '/' | relative_url }}">Home</a><span class="nav-sep">·</span>
+        <a href="{{ '/internals' | relative_url }}">Internals</a><span class="nav-sep">·</span>
+        <a href="{{ '/porting-notes' | relative_url }}">Porting notes</a><span class="nav-sep">·</span>
+        <a href="{{ '/building' | relative_url }}">Building</a><span class="nav-sep">·</span>
+        <a href="{{ '/dev-process' | relative_url }}">Dev process</a><span class="nav-sep">·</span>
+        <a href="{{ '/dev/agentic-development' | relative_url }}">Two-agent study</a>
+      </nav>
+    </div>
+  </header>
+
+  <main class="doc-content">
+    {{ content }}
+  </main>
+
+  <footer class="site-footer">
+    <div class="footer-inner">
+      <p class="footer-stamp">
+        Last updated 2026-09-28 — v0.4.0
+        <span class="nav-sep">·</span>
+        <a href="https://github.com/jkdansereau/goldeneye-pc-port">GitHub</a>
+        <span class="nav-sep">·</span>
+        <a href="https://github.com/jkdansereau/goldeneye-pc-port/releases">Releases</a>
+      </p>
+      <p class="footer-legal">
+        Non-commercial fan preservation/research project. No ROM or game assets
+        are distributed; you supply a ROM you already own. Not affiliated with
+        or endorsed by Nintendo, Rare, Microsoft, MGM, Danjaq, or EON
+        Productions.
+      </p>
+    </div>
+  </footer>
+</body>
+</html>

docs/building.md

@@ -3,7 +3,7 @@ title: Building
 description: Full build and asset-extraction guide for the GoldenEye 007 PC port, covering Windows (MSYS2) and Linux.
 ---
 
-# Building the PC port
+## Building the PC port
 
 Stages:
 

docs/dev-process.md

@@ -3,7 +3,7 @@ title: Development Process
 description: The investigation workflow behind the port; task budgets, file partitioning, and the finding-log discipline used across sessions and agents.
 ---
 
-# How this port is developed
+## How this port is developed
 
 Most of this port's work is not writing code; it is **diagnosis**: figuring
 out which N64 hardware or ABI behavior a piece of unmodified game code is
@@ -22,6 +22,45 @@ faster than its predecessor. That project bit-matches compiler output;
 this one matches runtime behavior, so the mechanics differ; but the
 project-structure lessons carry over directly.
 
+### Diagnosis is unrestricted; only the fix is constrained
+
+AGENTS.md non-negotiable #2 restricts *changing* `src/game` behavior. It
+has never restricted *investigating* it. An agent that stops short of
+naming the exact `src/game` struct, field, or logic responsible for a bug
+— because touching that file "feels" off-limits — is doing worse
+diagnosis than the rules require, not better compliance with them.
+Several of this port's hardest, highest-impact bugs (D209, D210, D255)
+were exactly this shape: a `src/game` state variable reading wrong,
+root-caused only by tracing fully into the game file that owned it.
+
+Every investigation should end able to say which of three buckets
+applies:
+
+- **(a) ABI/layout-class.** The true cause is a struct-layout or
+  pointer-width misread introduced by the 32→64-bit transition — in a
+  ROM-serialized record or a live runtime struct/union alike. Fixable
+  under the narrow exception, entirely inside the game file under
+  `#ifdef PORT`, no sign-off needed. Check `docs/porting-notes.md` §A1
+  first (the pattern's tells + worked examples) — this is the most
+  common shape a "`src/game` behavior looks wrong" report turns out to
+  have.
+- **(b) Port-layer bug that merely manifests through game state.** The
+  game code is reading state that's correct for what N64 would have
+  produced; something in `port/` (a shim, fast3d, frame timing, an
+  uninitialized or mis-ordered port-owned value) is what actually
+  differs. Fixable entirely in `port/`, no `src/game` touch, no sign-off
+  needed.
+- **(c) Genuine game-logic behavior difference.** The decomp's
+  byte-identical control flow, given verified-correct inputs, provably
+  diverges from real N64 behavior. Rare, and requires the rule-2
+  sign-off procedure (§7 below) before any `src/game` edit.
+
+Bucket (c) is rare by design — most bugs that look like (c) turn out to
+be (a) or (b) in disguise — but ruling it in or out requires actually
+tracing the state to its source, not stopping at the file boundary.
+"This state lives in `src/game`" is a reason to keep tracing, not a
+reason to stop.
+
 ## 1. Every investigation task gets a visible budget
 
 An open-ended tool; for them the permuter, for us "rebuild and run the game
@@ -63,6 +102,18 @@ The classes it currently tracks:
 - whole serialized formats are converted by an **offline sidecar** rather than
   patched at runtime.
 
+**Two process lessons from the sibling GEVR VR port** (same decomp lineage,
+reference-only survey in `scratchpad/GEVR-TRIAGE.md` item D — their corpus
+hit both repeatedly enough to name them): (1) **a grep standing in for a
+read** — a site list built by grepping one helper name or spelling misses
+siblings spelled differently or living in an adjacent file (their own
+missed-smoke-scissor-site example); treat a grep-built site list as a draft,
+not a census, until it's been read against. (2) **write the falsifier before
+the run** — state up front what result would kill the hypothesis ("if X
+survives, hypothesis Y is dead"), not just what would confirm it; this fits
+the existing budget/findings discipline directly and costs one sentence per
+brief.
+
 ## 3. Parallelise by file, consolidate often
 
 Lewis ran multiple git worktrees and found the real cost was
@@ -135,6 +186,68 @@ justifies. Rules:
   is still true as a fresh, small PR against current `main`. Merging stale
   content back over newer information is a regression, not a save.
 
+## 7. The rule-2 sign-off procedure (genuine `src/game` behavior changes)
+
+Use this only for bucket (c) from the diagnosis framing above — never for
+the ABI/layout exception (§A1-class fixes need no sign-off, only
+documentation) and never for anything expressible in `port/`.
+
+**To request sign-off, the write-up must state:**
+
+1. The exact `src/game` file:line and the specific behavior being
+   proposed for change.
+2. **Proof of divergence.** Given verified-correct inputs — i.e. every
+   upstream ABI/layout suspect (§A1) and every port-layer suspect has
+   been checked and ruled out, with the ruling-out cited — the
+   byte-identical decomp code still produces behavior that differs from
+   real N64 reference behavior. Name the reference (a capture, documented
+   prior N64 behavior, a cited external source). "It looks wrong" is not
+   proof; "it disagrees with `<reference>`, verified by `<method>`" is.
+3. Why the fix cannot be expressed in `port/`, and why it does not
+   qualify under the ABI/layout exception — the two questions that must
+   be answered "no" before this procedure applies at all.
+4. The proposed fix, scoped as tightly as possible to the one named
+   behavior, plus a same-engine precedent if one exists — the Perfect
+   Dark port is the standing reference; cite the analogous PD change the
+   way `docs/dev/WIDESCREEN-FOV-PLAN.md`'s "Rule #2 exception framing"
+   section did.
+
+**Granting.** The user reviews the above and replies with an explicit
+go-ahead in-thread. There is no implicit or inferred sign-off: silence,
+"seems reasonable," a prior similar grant, or approval of a *different*
+behavior in the same file do not carry over to a new request.
+
+**Recording.** Every sign-off gets its own `docs/dev/findings.md` entry
+(next `Dxx` label), tagged **`RULE-2-SIGNOFF`** in its status line
+alongside the normal finding classification, and recording: the request
+as stated above, the grant (quoted or summarized, with date), and the
+resulting diff. Add the label to `findings-index.csv` like any other row,
+so `tools_pc/gen_findings_index.py` keeps it discoverable — chat history
+is not the record of approval; the finding entry is.
+
+**Constraints that still apply after approval:**
+
+- Still `#ifdef PORT` — the N64 build is untouched, and the `#else` arm
+  (or the file's un-PORT-guarded default) still matches the original
+  decomp exactly.
+- Still scoped to the one named behavior — a grant is not a standing
+  license; a different behavior difference in the same file needs its own
+  request, even if related.
+- Still fully documented in the `RULE-2-SIGNOFF` finding entry — that
+  entry is the permanent record of *why* this specific exception to
+  non-negotiable #2 exists.
+- If the fix would visibly change behavior at *default*
+  settings/difficulty/region beyond the one bug being fixed, treat that
+  as a signal the scope drifted mid-implementation — stop and go back for
+  a fresh sign-off on the wider scope rather than shipping it under the
+  narrower original grant.
+
+This generalizes the ad hoc precedent in
+`docs/dev/WIDESCREEN-FOV-PLAN.md`'s "Rule #2 exception framing" section (a
+real, already-granted case, kept as historical record) into a reusable
+process; new requests cite this section rather than re-deriving the case
+for a process each time.
+
 ## Investigation-brief template
 
 ```
@@ -144,7 +257,16 @@ FILES YOU MAY TOUCH: <disjoint from any other in-flight work>.
 KNOWN-GOOD / RULED OUT: <list; do not re-investigate>.
 PRE-FLIGHT ATTACHED: <probe output, baseline capture, PD-port pointer>.
 BUDGET: <N build->run cycles / ~M min>. On expiry: revert probes, write up with confidence.
-CONSTRAINTS: no game-logic changes; ABI/layout/format only; #ifdef PORT; documented in the finding log.
+CONSTRAINTS: diagnosis may trace as deep into src/game state as the evidence
+  needs — name the exact struct/field/logic responsible before concluding
+  which bucket applies (see "Diagnosis is unrestricted" above). The FIX is
+  still constrained: no src/game behavior changes unless (a) it's an
+  ABI/layout-class struct-layout or pointer-width misread — check
+  docs/porting-notes.md §A1 first; #ifdef PORT; documented in the finding
+  log under §F/D3x — or (b) it's fixable entirely in port/ (no src/game
+  touch). A genuine game-logic behavior difference (bucket c) is NOT
+  authorized by this brief — stop and write up a rule-2 sign-off request
+  per docs/dev-process.md §7 instead of applying it.
 VERIFY: <the exact tools_pc/verify.sh (or probe) invocation that proves this done; or, if runtime verification is impossible in this environment, say so and name what a human must run>.
 REPORT: (a) root cause + file:line evidence  (b) fix diff, or why not
         (c) probes left in tree  (d) confidence.

docs/dev/ACCURACY-AUDIT-2026-09-20.md

@@ -0,0 +1,77 @@
+# Accuracy / code review — N64 fidelity sweep (2026-09-20)
+
+A thorough pass over the PC port with one question: *where does the port diverge from the
+N64 original, and what latent failure classes of the D318 kind are still unpriced?*
+Method: static review against the decomp ground truth + targeted verification builds.
+Findings below; new finding **D320** logged in `findings.md`.
+
+## 1. PRNG — verified bit-exact
+
+`port/src/random.c` re-checked line-by-line against both `src/random.s` and
+`src/game/chrObjRandom.s`. The MIPS64 `dsll32`/`dsrl32` semantics (post-D284) are
+emulated correctly: the 32-bit LFSR state advances identically, and
+`randomGetNext()` returns the same 31-bit values in the same order. No divergence.
+
+## 2. Known bug-class sweeps — all clean or already fixed
+
+| Class | Result |
+|---|---|
+| **A1** raw-byte/padding aliases (32→64-bit layout shift) | Remaining `padding[]` uses are in pointer-free structs (layout-stable) or already fixed (D115, D209, D312). No live misreads. |
+| Shifts by 32 / pointer-width arithmetic in game logic | Only port-layer code (`d318watchdog` print, `DRAM_SIZE`). Game logic clean. |
+| Signed-overflow UB | `-fwrapv` enabled in `CMakeLists.txt` — the whole class is neutralized to N64-wrap semantics. |
+| `#ifdef PORT` hygiene (N64 path preserved) | 307 hunks audited; 178 are pure additions (diagnostics / struct extensions). No hunk alters the non-PORT control flow. |
+| **§B** Gfx/Vtx 16-byte records (raw byte indexing) | `bg.c` uses typed `.words`/`.dma` fields throughout; no remaining raw byte offsets. D312's fix pattern is the last of this class. |
+| `osVirtualToPhysical` call sites (88) | All flow through fast3d's `seg_addr()` (D131 fix intact). No site assumes N64 segment RAM layout. |
+| Dead code | `objecthandler_2.c` compiles but is not linked on PC (symbols absent from the binary). Harmless; noted for a future source-list prune. |
+
+## 3. Timing layer — intentional, documented
+
+Frame-locked virtual clock (vsync tick), `GE_DETERM` fixed-tick mode, and
+`g_GlobalTimerDelta` zero-guarded at every division site. All deliberate port-layer
+design, each documented in its finding. No hidden drift source found beyond the
+already-fixed D204 tempo work.
+
+## 4. D318-class latent softlock sweep → **D320** (the main new result)
+
+D318's mechanism is generic, not Facility-specific: `actor_fire_or_aim_at_target_update`
+(`chraction.c:4882`) retargets any ACT_ATTACK chr with an AIM_ONLY/DONTTURN attacktype and
+only moves the model's **endframe** — it never re-inits the animation. If the chr is pinned
+on a pre-shoot aim-hold pose (hold endframe H < variant shoot window) and the new endframe
+lands above H, the model pins forever and the timer-gated fire events never open; if the
+surrounding AI script's only escape is an `if_guard_has_stopped_moving` gate, it can never
+pass (`chrHasStoppedOrPatroling` is FALSE for ACT_ATTACK). **Permanent softlock — on N64 too.**
+
+Swept every level's AI scripts (`assets/obseg/setup/*.c`): 17 lists in 8 levels contain an
+aim-hold + `_update` pair. Risk-ranked table in the D320 entry. Headlines:
+
+- **Facility ai_19** — HIGH. Same non-self-healing shape as ai_22 (second softlock point in
+  the same level).
+- **Control ai_9** — HIGH. Near-exact ai_22 mirror (pre-aim hold → timer → update → fire
+  loop gated on the target dying from this guard's shot).
+- **Depot ai_12** — MED-HIGH. The kill is scripted, but the objective bit is gated behind a
+  stop-check; pinned guard → level-complete softlock.
+- **Bond-combat loops** (Aztec/Control/Egyptian/Depot/Streets/Bunker/Surface) — likely safe:
+  sustained fire keeps the model inside the shoot window by design, and every playtest
+  exercises them without freezes. Inferred, not probe-verified per list.
+
+Classification: **as-authored latent race(s), faithfully reproduced** — same bucket as D318,
+not a port bug. Verification path (generalized timeline probe) and the
+generalize-the-watchdog recommendation are in D320.
+
+## 5. Fixed this session
+
+- `port/fast3d/gfx_pc.cpp:2417` — the GE_D116 diagnostic printf used `%f` for `uint32_t`
+  args (`v->u`, `tex_width`) and `%d` for unsigned tile fields; wrong debug output only, no
+  runtime impact. Casts added; build now warning-free on that file.
+
+## 6. Verification ritual
+
+Full `./build-pc.sh ntsc-final` configure + compile + link: **PASS**, no warnings on
+touched files. All new/changed symbols resolve exactly once (link is the sweep). D318
+watchdog/timeline symbols confirmed present in the binary.
+
+## 7. Deliberately not committed (release-prep WIP, separate workstream)
+
+`.github/release-notes.md`, `README.md`, `docs/index.md`, `docs/media/goldeneye-gh-preview.gif`,
+`docs/dev/agentic-development.md`, `.gitignore` (`/local/` exclude), and non-D318 scratch
+artifacts — left in the working tree for their owner.

docs/dev/CONTROLLER-INPUT-PLAN.md

@@ -0,0 +1,246 @@
+# Controller & input options wave (port plan)
+
+Status: **Wave A IMPLEMENTED** (code complete, clean Windows/MSYS2 build; pending
+user by-ear/by-eye feel-check + Deck tuning of item 5) — the "low-hanging
+fruit" from the Nightdive *Turok* PC-port options menu that is cheap, well-
+scoped, and
+**port-layer only** (zero `src/` / `src/game` edits → rule 2 and the ABI
+exception do not apply). Sequenced after v0.4.0 ships. This is the *input*
+wave; the sibling *video/audio/graphics* Tier-A items (borderless window,
+primary display, brightness, master volume, button glyphs, uncapped-FPS) are a
+separate follow-on wave — see §Out of scope.
+
+Reference: `docs/dev/RUMBLE-PLAN.md` (D401) is the closest precedent — a
+controller option that lives entirely in `port/src/input.c` +
+`port/src/optionsoverlay.c` + a `configRegister*` key + a `kResetDefaults`
+entry, with the game side (`src/joy.c`, `src/` stick consumers) untouched.
+`docs/dev/GEPD-INPUT-PLAN.md` documents the pad poll path this wave extends.
+
+---
+
+## Ground truth (current state, verified 2026-09-27)
+
+**Pad poll = `inputComputePad()`** (`port/src/input.c:1375`), runs on the game
+thread (`osContStartReadData`). It reads the SDL axes/buttons for pad `idx`,
+writes out a 16-bit button mask plus `*stick_x` / `*stick_y` (the N64
+`signed char` stick, clamped to `STICK_MAX`). All the knobs in this wave are
+applied **inside** `inputComputePad`, before the two `*stick_x`/`*stick_y`
+writes at `:2063-2064` — i.e. the port re-shapes the *input the game already
+consumes*, never the game's stick→turn math.
+
+**Two pitch modes drive the look stick** (selected by `Input.NaturalPitch`,
+the default-on "SOLITARE" mode, D194/D238):
+- **Continuous (natural-pitch, the default):** the **right stick** is the
+  continuous look axis — `input.c:1927-1933`:
+  `rxs = scaleAxis(rx);` … `rys = -scaleAxis(ry); if (padLookInvertY)
+  rys = -rys; sx = rxs; sy = rys;`. The left stick becomes digital-step
+  movement. **This is the path the X/Y look-sensitivity + look-smoothing +
+  right-stick deadzone knobs target.**
+- **Digital (native, natural-pitch off):** the left stick is analog
+  movement/turn and the right stick is digitized into the C-button look
+  (`:1935-1947`, thresholds at `RSTICK_THRESHOLD`). Look here is the faithful
+  N64 *digital* C-button turn — **not sens-scalable** (there is no analog look
+  to scale), so the new look-sens/smoothing knobs are inert in this mode,
+  exactly as `Input.AimMode`/`Input.AimRange` already are per mode.
+
+**Existing pad knobs** (all `configRegister*` in `input.c`, rows in
+`optionsoverlay.c` INPUT section): `Input.PadDeadzone` (single,
+`padDeadzone = STICK_DEADZONE`, `:524`), `Input.PadTriggerPct` (`:525`),
+`Input.PadLookInvertY` (`:526`), `Input.RumbleScale` (D401). `scaleAxis()`
+applies the shared deadzone + `STICK_MAX` scale to a raw `int16` axis.
+
+**Already covered elsewhere** (do not re-plan): mouse sens/invert/smoothing
+(`Input.MouseSensitivity`/`MouseInvertY`/`MouseSmoothing`), **uncapped FPS**
+(`docs/dev/UNLOCKED-FPS-PLAN.md` — parked; has a real perf prerequisite, D250),
+**controller rebinding** (PR #109 / D383 — the hard, open gap, out of scope).
+
+---
+
+## Items (all port-layer)
+
+### 1. `Input.PadLookSensX` — right-stick look **horizontal** sensitivity  *(S)*
+New int key, default **100** (= 1×, current behaviour), range ~**25–200 %**.
+Applied in the continuous-look branch only: after `rxs = scaleAxis(rx)`,
+`rxs = clamp(rxs * padLookSensX / 100, ±STICK_MAX)` before `sx = rxs`
+(`input.c:1928/1932`). Pure gain on the emitted look X. In digital mode: inert.
+- Row: INPUT, "Look sensitivity (left/right)", slider, after "Rumble strength".
+- Risk: none (monotonic gain; 100% = byte-identical to today). Deck-testable.
+
+### 2. `Input.PadLookSensY` — right-stick look **vertical (pitch)** sensitivity  *(S)*
+Same shape, applied to `rys` (`input.c:1930/1933`): `rys = clamp(rys *
+padLookSensY / 100, ±STICK_MAX)`. Default **100**, range ~**25–200 %**.
+Kept separate from X (Turok splits them; pitch and yaw feel different on a
+stick). Independent of the existing `Input.HipfirePitchSpeed` (that one is the
+hipfire/mouse pitch rate, a different path). In digital mode: inert.
+- Row: INPUT, "Look sensitivity (up/down)", slider.
+- Risk: none (same as item 1).
+
+### 3. `Input.PadSouthpaw` — swap L/R triggers  *(S)*
+New toggle, default **off**. Today (`input.c:1954-1958`): `TRIGGERRIGHT >
+trigPt → GE_CONT_G`; `TRIGGERLEFT > trigPt → GE_CONT_R`. Under southpaw, swap
+the two `GE_CONT_G`/`GE_CONT_R` assignments (left trigger becomes the
+right-shoulder action and vice-versa). Two lines. Lets left-handed /
+southpaw players put their index finger on the primary fire trigger.
+- Row: INPUT, "Southpaw", toggle.
+- Risk: none at default off; trivial to verify by re-aiming.
+
+### 4. `Input.PadDeadzoneL` / `Input.PadDeadzoneR` — per-stick deadzone  *(S–M)*
+Split the single `Input.PadDeadzone` into a **left (movement)** and a
+**right (look)** deadzone. Thread the deadzone through `scaleAxis()` (it is
+currently the global `padDeadzone`) as a per-call argument: left-stick calls
+use `padDeadzoneL`, right-stick calls use `padDeadzoneR`.
+- **Back-compat/migration:** on load, if `Input.PadDeadzoneL`/`R` are absent
+  but legacy `Input.PadDeadzone` is set, seed both from it (one-time, like the
+  `AimStyle`→`AimMode` migration at `input.c:449-454`). Keep `Input.PadDeadzone`
+  registered so old inis keep loading; it becomes hidden/superseded (D337/`D333`
+  precedent for a superseded key).
+- Rows: INPUT, "Deadzone (left stick)" + "Deadzone (right stick)", sliders.
+- Risk: low — a deadzone is a per-axis floor; splitting it cannot change
+  behaviour when both equal the current single value. Watch the menu-navigation
+  path (`:1918-1922`, left stick in menus) to use the **left** deadzone there.
+
+### 5. `Input.PadLookSmoothing` — right-stick look low-pass  *(M)*
+New key, default **0 (off)**, range 0–10 (0 = off = today). When >0, low-pass
+filter the *emitted* right-stick look deflection so the look axis eases rather
+than tracking the stick 1:1 — the pad analogue of `Input.MouseSmoothing`
+(which smooths the *relative* mouse delta). Because the continuous stick is
+**absolute** (not a delta), implement as a per-pad exponential moving average
+on the emitted `rxs`/`rys` (state kept per `idx`, reset on pad hot-unplug and
+on aim-mode exit so releasing the stick recentres cleanly). The higher the
+value, the heavier the easing.
+- Row: INPUT, "Look smoothing", slider (0 = off).
+- Risk: **medium** — an EMA on an absolute stick can feel laggy or fail to
+  recentre if the filter isn't driven back to 0 when the stick is centred;
+  needs hands-on tuning on the Deck (the natural test device). Keep default off
+  so it ships inert until tuned.
+
+### 6. Mouse **vertical** sensitivity row  *(trivial — folds in)*
+`Input.MouseYScale` already exists as a registered key; it just has no F10
+row. Add one slider row (INPUT) so the asymmetric X/Y mouse sensitivity is
+user-adjustable without editing the ini. No `input.c` change — row only.
+
+---
+
+## Shared plumbing (do once, not per item)
+- **`configRegisterInt`/`Float`** for each new key in `input.c` next to the
+  existing pad-key registrations (~`:2536-2538`).
+- **Static state** next to `padDeadzone`/`padLookInvertY` (`:524-526`):
+  `padLookSensX/Y`, `padSouthpaw`, `padDeadzoneL/R`, `padLookSmoothing` + the
+  per-pad EMA state for item 5.
+- **F10 rows** in `optionsoverlay.c` `rows[]` INPUT section (after
+  "Rumble strength", with the other controller rows) + matching **front options**
+  rows via the shared `optionsRow*` accessors (both UIs read `rows[]` — D401
+  precedent, so one definition covers F10 *and* the front options screen).
+- **`kResetDefaults`** entries for each new key (neutral: sens 100, smoothing
+  0, southpaw 0, deadzones = `STICK_DEADZONE`) so INPUT "Reset to defaults"
+  covers them (D401 item-3 precedent).
+
+## Ground rules
+1. **Port-layer only** — every edit is in `port/src/input.c`,
+   `port/src/optionsoverlay.c`, `port/src/frontoptions.c`, and `CMakeLists.txt`
+   (nothing new to compile — no new files). Zero `src/` / `src/game` edits →
+   rule 2 and the pointer-width ABI exception are not engaged.
+2. **Off-by-default = today's behaviour.** Every new key defaults to a neutral
+   value that leaves the emitted stick/buttons byte-identical to the current
+   build, so the golden gate (D117/`golden_gate.sh`) is unaffected at defaults
+   and the v0.4.0 playtest baseline is preserved.
+3. **Per-mode honesty.** The continuous-look knobs (1, 2, 5) apply only in
+   natural-pitch mode; in digital mode they are inert — document this on the
+   rows (mirrors how `Input.AimRange` is hidden in Centred mode, D338), rather
+   than pretending they affect the digital C-button look.
+4. **Deck is the reference device** for the pad wave (native Steam Controller,
+   the real-world target); Windows + a plugged gamepad as the second check.
+
+## Verification
+1. `./build-pc.sh ntsc-final` clean (no new symbols/dupes — the `configRegister*`
+   + `kResetDefaults` additions are the only new references).
+2. `/linkcheck` + the golden gate (`tools_pc/golden_gate.sh`) — must pass
+   **unchanged at defaults** (proves the neutral-default invariant).
+3. Hands-on, on a pad / the Steam Deck: each knob at a non-neutral value
+   changes feel as expected and at default leaves it identical; southpaw
+   re-maps the triggers; per-stick deadzones floor the correct stick; look
+   smoothing eases and **recentres on stick release** (item 5's known risk).
+4. New finding (D4xx, next free label) recording the wave + per-item
+   Deck-test result, cross-ref'd to D401 (precedent), D337/D338 (per-mode
+   gating pattern), D333 (`AimStyle` migration pattern), PR #109 (out-of-scope
+   rebind).
+
+## Out of scope for this wave (see the assessment above)
+- **Sibling Tier-A, other sections (separate follow-on wave):** borderless
+  windowed, primary-display selection, brightness slider, master audio volume,
+  button-prompt glyphs.
+- **Tier B (medium, contained):** radial fog toggle, HUD opacity, flash-
+  intensity slider (promote `Game.NoHitFlash`), show-HUD master toggle, audio
+  output device, low-pass filter, SMAA/FXAA.
+- **Uncapped FPS** — `docs/dev/UNLOCKED-FPS-PLAN.md` (parked; D250 perf
+  prerequisite means it is not quick).
+- **Tier C (rule-2 / big-feature / out-of-scope):** head-bobbing sliders,
+  death-cinematic / switch-on-pickup / walk toggles (all `src/game` flow),
+  bloom / light-scattering / water refraction-reflection / simple shadows,
+  violence / blood colour, multiple graphics APIs, and **full controller
+  rebinding** (PR #109 — the genuinely hard input item).
+
+## Suggested sequencing (v0.5.0)
+1. **Wave A (this doc):** items 1–4 + 6 (sens X/Y, southpaw, per-stick
+   deadzone, mouse-Y row) — all low-risk, shippable behind neutral defaults.
+2. **Item 5 (look smoothing)** lands in the same wave but may ship default-off
+   pending Deck feel-tuning.
+3. **Wave B:** the sibling video/audio/graphics Tier-A items.
+4. Revisit Tier C only with explicit sign-off (rule-2 items need the
+   `docs/dev-process.md` procedure).
+
+---
+
+## Implementation status (2026-09-28)
+
+Wave A code is complete and compiles clean (Windows/MSYS2 `ninja` incremental,
+exit 0, no new warnings — only the pre-existing `ramrom.c` / `gfx_pc.cpp` ones).
+Every edit is in `port/src/input.c` + `port/src/optionsoverlay.c`;
+`frontoptions.c` needed **no** change (both UIs read the shared `rows[]` via the
+`optionsRow*` API). Zero `src/` edits, no new files/symbols — only file-local
+statics + `configRegisterInt` calls — so the link is unchanged.
+
+Implemented (all off/neutral-by-default → byte-identical at defaults):
+- **1/2. `Input.PadLookSensX` / `Input.PadLookSensY`** (25–200 %, dflt 100):
+  right-stick look, applied in the natural-pitch branch of `inputComputePad()`
+  after `scaleAxis()`, re-clamped to `STICK_MAX`. Inert in digital mode (the
+  right stick is digitized there, no analog look to scale).
+- **3. `Input.PadSouthpaw`** (toggle, dflt 0): swaps the fire (`GE_CONT_G`)
+  and grenade (`GE_CONT_R`) trigger actions *after* the raw edges are captured,
+  so edge-detection stays consistent.
+- **4. `Input.PadDeadzoneL` / `Input.PadDeadzoneR`** (0–30000, dflt 7000):
+  `scaleAxis()` now takes a per-stick deadzone param; left-stick (movement)
+  calls pass `L`, right-stick (look) calls pass `R`. The legacy
+  `Input.PadDeadzone` key stays registered (no row) so old inis load; a
+  one-time migration in `inputInit()` seeds any unset L/R (C-init sentinel
+  `PAD_DZ_UNSET = -1`) from the legacy value, before any `configSave`. The
+  single "Stick deadzone" row is replaced by "Deadzone (left stick)" /
+  "(right stick)".
+- **5. `Input.PadLookSmooth`** (0–10, dflt 0 = off, shown "N/10"): per-pad EMA
+  low-pass on the natural-pitch look output (`padSmSX/padSmSY[MAX_PADS]`), reset
+  on hot-unplug (`inputRescanPads`) so a snapped-back stick can't lag from a
+  stale value; otherwise the EMA decays to 0 as the stick recentres. Turok has
+  this as on/off; GE ships a graduated 0-10 knob instead. Ships **default-off**
+  pending Deck feel-tuning.
+- **6. `Input.MouseYScale`** row (dflt 100): the pre-existing registered key
+  finally gets an INPUT slider row ("Mouse vertical sensitivity") — row only,
+  no `input.c` change.
+
+**Verbiage + display baseline (Turok PC, 2026-09-28):** row labels now match the
+Turok options menu verbatim where GE has an analogue — *Mouse horizontal /
+vertical sensitivity*, *X axis / Y axis look sensitivity*, *Look smoothing*,
+*Southpaw*, *Vibration* (was "Rumble strength"), *Deadzone (left/right stick)*.
+The display is baselined to Turok's scales: sensitivity + deadzone knobs read
+**0-100 with 50 = the default** (the existing `calibratedDefault` "N/100" path),
+and look smoothing reads **0-10** ("N/10"). (Turok's Mouse/Controller subsection
+split is not mirrored — GE keeps one flat INPUT section per D356, so the two
+invert rows retain their "(mouse)"/"(controller)" suffixes to stay unambiguous.)
+
+`kResetDefaults` covers all six so INPUT "Reset to defaults" is complete;
+`calibratedDefault()` gives the sensitivity + deadzone rows their 50/100 default
+midpoint, and `dispMax` renders the smoothing knob as "N/10".
+
+**Still owed (verification, not code):** user by-ear/by-eye feel-check of the
+new knobs on a real pad (esp. item 5 smoothing strength + item 1/2 sens range),
+the Deck cross-check, and confirming the per-stick deadzone migration on an
+old-ini user (L/R seed from `Input.PadDeadzone`).

docs/dev/CUT-CONTENT-BACKLOG.md

@@ -0,0 +1,360 @@
+# CUT-CONTENT-BACKLOG — TCRF "cutting room floor" findings vs decomp/port
+
+Research branch: `research/cut-content-backlog`. Source of truth: the local TCRF
+export at `scratchpad/backlog-scrape/restore-cut-content-mod/` (gitignored).
+
+> **Superseded by the verified cross-reference.** All six article *bodies* were
+> recovered and every major claim was checked against the decomp source and asset
+> tables. The full verified findings (with file:line references, corrections to
+> TCRF, and updated mod tiers) live in `backlog/cut-content/RESEARCH.md`
+> (gitignored; article markdowns in `backlog/cut-content/articles/`). This doc is
+> the first pass (image-filename based) — read it for the per-item imagery index,
+> but trust RESEARCH.md where they disagree. Key corrections: (1) "dest" is the
+> *shipped* Frigate geometry, not an early version (`bg.c` levelinfotable);
+> `cryp`/`dish` are shipped Egypt/Temple; (2) Library/Stack share Basement's bg
+> file — they have geometry; (3) all 29 "unused items" exist in the ROM object
+> table as pickup+prop pairs except heroine; (4) TCRF's 11 unused cheats, music
+> track index, MP character table and build dates all verify 1:1 against
+> `bondconstants.h`/`cheat.c`/`front.c`/`compiletime.c`.
+>
+> **Round 2 (decomp-only discoveries — not in TCRF's documentation):**
+>
+> 1. **The shipped game still calls the M16 an "AR33"** — pickup text
+>    `"an AR33 assault rifle."` (`LpropobjE.c` PROPOBJ_STR_2A, used at
+>    `propobj.c:10471`), plus unused strings `"US AR33 Assault Rifle"`/
+>    `"US AR33"` (`LgunE.c` GUN_STR_74/75) and `PROP_CHRM16 /* AR33 Assault
+>    Rifle */` comments. TCRF's prerelease page mentions the AR33 name in early
+>    footage but not that it survived into retail text.
+> 2. **Klobb rename trace verified**: weapon-name strings in `LgunE.c` are
+>    alphabetical except GUN_STR_6B `"Klobb"` (between "Spy File" and "Staff
+>    List") — exactly the last-minute Skorpion→Klobb scar TCRF describes.
+> 3. **Two cut weapons TCRF's unused-items page doesn't list**: `cartrifle` and
+>    `wristdart` — full pickup+prop resources (`GcartrifleZ`, `GwristdartZ`,
+>    `PchrwristdartZ /* (BETA) */`) but no `ITEM_*` entry and no WeaponStats,
+>    i.e. unusable as weapons. The wrist dart is the hardware behind TCRF's
+>    `AMMO_DARTS` ($0E).
+> 4. **All four Bonds, fully mapped**: `CUFF_CONNERY/DALTON/MOORE` +
+>    `BOND_BROSNAN/CONNERY/DALTON/MOORE` enums; the actor-switch code
+>    (`bondview2.c:391-460`) survives with every branch flattened to Brosnan;
+>    the save struct keeps the per-dossier actor field. **No Connery/Moore/
+>    Dalton models exist in the retail ROM** (80 `C*Z` chr models enumerated —
+>    none for the former actors); only enum slots + the `SW_CONNERY`/`SW_DINNER`
+>    switches on the watch-arm model remain. TCRF's "four dossiers, four
+>    actors" was pre-release state.
+> 5. **Cuba is the one orphan level with recoverable content**: `LlenE.c` holds a
+>    cut Natalya dialogue exchange, the "C U B A N J U N G L E" title card, and a
+>    full alternate credits cast. The other 12 unused level text files are empty
+>    stubs.
+> 6. **Orphan-level geometry IS in the ROM**: `assets/obseg/obseg.h` declares all
+>    nine text-only orphans' bg segments (`bg_sho_all_p_seg[]` …) — a
+>    byte-matching decomp can't fabricate them. What's missing is mission setup
+>    (briefings exist only for the 21 solo levels), not geometry.
+> 7. **Moneypenny's two risqué Frigate-briefing lines are gone from the ROM**
+>    (final `LdestE.c` keeps only the toned-down "thighs of steel" paragraph);
+>    recoverable only from TCRF's transcription. "Destroyer"→"Frigate" rename is
+>    complete; the Manticore yacht mission has zero ROM trace.
+> 8. **Music enum ↔ Notes-page GS index fully aligned**: indices 0–48 match
+>    slot-for-slot; four local mismatches past 0x2C (49 `M_CUBA` vs "Ending
+>    theme", 52 `M_MPTHEME3` vs "Surface 2 X", 54 `M_GUITARGLISS` vs "MP Death
+>    (Alt)", 59 `M_SURFACE2X` vs "Surface 1 X") — in-game `DEB_MUSIC` audition
+>    needed to resolve.
+
+## 1. Findings
+
+### A. Debug menu & dev tools — fully in the ROM, fully compiled into the PC build
+
+TCRF main page images: `GEDebugMenu`, `GECheatOptions`, `GoldenEye-displayspeed`,
+`GoldenEye-moveview`, `GoldenEye-LineMode`, `GoldenEye-testingmanpos`,
+`GoldenEye-gunwatchpos`.
+
+All of these exist in decompiled code:
+
+- **Debug menu** — `src/game/debugmenu_handler.c` (1202 lines). Opened by holding
+  **U + D C-buttons** (`debug_menu_processor`, ~line 451; wired into `boss.c:551`
+  and the main game loop). Full option list at lines 116–185: `move view`,
+  `stan view`, `bond view`, `level` / `region` / `scale` (level switching),
+  `play title`, `bond die`, `select anim`, `gun pos`, `flash colour`,
+  `hit colour`, `music`, `sfx`, `invincible`, `visible`, `collisions`,
+  `all guns`, `max ammo`, `display speed`, `background`, `props`,
+  `stan hit` / `stan region` / `stan problems`, `print man pos`,
+  `port close` / `port inf` / `port approx`, `pr room loads`,
+  `show mem use` / `show mem bars`, `grab rgb` / `grab jpeg` / `grab task`
+  (screenshots), `rnd walk`, **`record ramrom` / `replay ramrom` /
+  `save ramrom` / `load ramrom`** (input recording/replay!), `auto y aim`,
+  `auto x aim`, `agent` / `all` / `fast` (unlock flags), `objectives`,
+  `marg top/bot/left/right/reset`, `screen size`, `screen pos`,
+  `show patrols`, `intro` / `intro edit` / `intro pos`, `world pos`,
+  `gun key pos`, `vis cvg`.
+- **Free camera** — `src/game/debug_camera.c` (the "move view" option).
+- **Load-all-models tool** — `src/game/deb_loadallmodels.c` (used by
+  `initguards.c`; dumps every model — how the TCRF screenshots of unused
+  models were likely made).
+- **Line mode** — `CHEAT_LINEMODE` in `src/game/cheat.c:685` (wireframe toggle,
+  cheat-menu unlockable; `front.c:1017`).
+- Screenshot options (`grab rgb`/`grab jpeg`) call `indyGrabRgb32bit()` /
+  `indyGrabJpg32bit()` — N64 VI grabs; on PC these are the natural hook for the
+  port's existing screenshot QoL (see `feat/qol-mute-screenshot` lineage).
+
+**Status: Tier 0.** Everything compiles into the PC build (`CMakeLists.txt`
+`GLOB_RECURSE src/game/*.c`). The debug menu should already work in the PC port
+if U+D C-buttons can be produced by `port/src/input.c`. *Verify in-game* (open
+menu, toggle `display speed`, use free cam). Mod value: document it; consider a
+config/keybind that synthesizes the U+D c-button hold, and mapping `grab rgb`
+to the port's screenshot path.
+
+### B. Cut weapons — fully functional in the ROM, grantable via existing cheat codes
+
+TCRF images (main + prerelease pages): `GoldenEye-Taser[PR]`, `GoldenEye-KF7[PR]`
+(+`KF7Watch`), `GoldenEye-GrenadeLauncher[PR]`, `GoldenEye-RocketLauncher[PR]`
+(+`RocketLauncherWatch`), `GoldenEye-RifleLauncher` (+`RifleLauncherCheat`),
+`GE64_Shotgun1`, watch variants `MagnumWatchPR`, `PP7WatchPR`, `KlobbWatchPR`,
+`TaserWatch`.
+
+Evidence in code/assets:
+
+- Model + stat files exist for every cut gun under `assets/obseg/gun/`:
+  `taser/`, `rocketlaunch/`, `grenadelaunch/`, `fnp90/`, `spectre/`,
+  `autoshot/`, `ak47/`, `m16/`, `skorpion/` … each with
+  `gunWeaponStat.inc.c` + `ModelFileHeader.inc.c`.
+- `assets/obseg/gun/gunWeaponStats.inc.c`: complete `WeaponStats` for
+  `taser_stats` (line ~365), `rocketlaunch_stats` (~305),
+  `grenadelaunch_stats` (~295), plus `watchlaser_stats`, `tank_stats`,
+  `bombcase_stats`, etc. These are data-driven — the weapon engine
+  (`src/game/gun.c`, `gunfire.c`) will run them.
+- First-person view cases exist: `src/game/bondview_r.c:38` handles
+  `ITEM_GRENADELAUNCH`, `:41` `ITEM_ROCKETLAUNCH`.
+- **Cheat codes grant them**: `src/game/cheat.c` — `CHEAT_2X_ROCKET_LAUNCHER`
+  (line 711), `CHEAT_2X_GRENADE_LAUNCHER` (712), `CHEAT_2X_RCP90` (713),
+  plus unlock sequences (`CHEAT_UNLOCK_2XGL/2XRL/2XFNP0`, lines ~695–734) and
+  the grant logic at lines 1277–1310: `bondinvAddInvItem(ITEM_ROCKETLAUNCH)` /
+  `give_cur_player_ammo(AMMO_ROCKETS, …)` etc. Note the `#if defined(BUGFIX_R1)`
+  guards — check which region macros the PC build defines (non-negotiable #3).
+- Taser SFX exist: `GUN_TASER_SFX` / `GUN_TASER_LOOP_SFX` (`src/bondconstants.h:2271`).
+- `ITEM_TASER` is in the item enum and used as an inventory bound in
+  `bondinv.c:854` (JP-text-trigger branch) — the taser was closest to shipping.
+
+**Status: Tier 0/1.** Rocket launcher, grenade launcher and FN P90 are
+playable today via the game's own cheat codes (single-player). Taser/Spectre/
+AutoShot have no cheat path but everything needed is in the binary; a
+port-layer toggle calling the same `bondinvAddInvItem` +
+`give_cur_player_ammo` pair the cheats use would be a clean mod (no game-logic
+change — it replicates an existing code path). Watch-mounted variants
+(KF7/Magnum/PP7/Taser watch) are *not* in the item enum — likely cut before
+data landed; **unverified** whether any model exists beyond what TCRF shows.
+
+### C. "Unused items" page (intact imagery) — objects with full logic, never placed
+
+The 20 intact images correspond exactly to ROM object entries
+(`assets/obseg/file_resource_table.inc.c`, 781 entries):
+
+| Image | Resource ID | Notes |
+|---|---|---|
+| `GE007-AudioTape` | `AUDIOTAPE` / `CHRAUDIOTAPE` (lines 125, 265) | pickup + prop variants |
+| `GE007-BombCase` | `BOMBCASE` (129) | has full `bombcase_stats` (throwable explosive) |
+| `GE007-Controller` | N64 controller model (`joypad/` dir in gun table) | desk prop |
+| `GE007-WatchMagnetRepel` | `ITEM_WATCHMAGNETREPEL` (`bondconstants.h:4190`) | watch function, use-logic present |
+| `GEMicroCamera` | `MICROCAMERA` (176) + `AMMO_MICRO_CAMERA` | |
+| `GoldenEye-Weapon_Case` | `ITEM_WEAPONCASE` (`gunfire.c:3066` use-case) | |
+| `GE007-PolarizedGlasses` | `POLARIZEDGLASSES` (185) + `ITEM_POLARIZEDGLASSES` | `darkglasses/` also present |
+| `GoldenEye-Plans` | `PLANS` (183) | `blueprints/` variant too |
+| `GoldenEye-Watch_Identifier` | `WATCHIDENTIFIER` (208) + `ITEM_WATCHIDENTIFIER` (`gunfire.c:3076`) | 4th watch function with use-anim, never spawned |
+| `GoldenEye-Safecracker` | `SAFECRACKERCASE` (190) | |
+| `GoldenEye-Watch_Communicator` / `Watch_Geiger_Counter` | `ITEM_WATCHCOMMUNICATOR` / `ITEM_WATCHGEIGERCOUNTER` (`bondconstants.h:4188-89`) | shown for contrast — these *are* used (Aztec) |
+| `GEGasKeyring` | `GASKEYRING` (157) + `ITEM_GASKEYRING` | |
+
+All have `GUN_ANIM_STATE_USE_ITEM` handling in `gunfire.c:3060-3084` — i.e. the
+game can *use* them; level data just never places them.
+
+**Status: Tier 1/2.** Granting any of these to Bond is a port-layer item-spawn
+(same mechanism as §B). Actually *placing* them in levels requires ROM/level-data
+editing (a level editor or hand-patched object tables) — Tier 2, out of scope
+for this repo but viable as a data mod.
+
+### D. Cut multiplayer maps — 8 commented-out menu entries with dev notes
+
+`src/game/front.c:556-573` `multi_stage_setups[]`: the shipped MP list is
+Random/Temple/Complex/Caves/Library/Basement/Stack (default) + Facility/Bunker2/
+Archives/Caverns/Egypt (progression-unlocked). Immediately below, **commented
+out with in-source dev annotations**:
+
+```c
+  //{... LEVELID_CITADEL ...}, //Citadel (old format setup)
+  //{... LEVELID_FRIGATE ...}, //dest (has xbla setup)
+  //{... LEVELID_STATUE ...},  //stat (works)
+  //{... LEVELID_CRADLE ...},  //crad (works)
+  //{... LEVELID_AZTEC ...},   //azt (needs setup)
+  //{... LEVELID_RUNWAY ...},  //runway (xbla setup)
+  //{... LEVELID_DAM ...},     //dam (xbla setup)
+  //{... LEVELID_DEPOT ...},   //depot (xbla setup)
+```
+
+TCRF imagery matches: `GECitadel*` (5 screenshots, main page),
+`GEStatueMulti`, `GECradleMulti`, the whole Depot image set (`DepotCrateStack`,
+`DepotRockets`, `DepotSafeTable`, `DepotSiloPipe[Ed]`, `DepotTrailers`,
+`DepotPhoto`), and `GoldenEye-FrigateMap`.
+
+The port already boots every one of these standalone (`-level_XX`; see
+`docs/dev/LEVEL-STATUS.md` — Statue `-level_22`, Train `-level_25`, etc. all
+PASS). So the geometry, AI setup and briefings
+(`assets/obseg/brief/UbriefdepoZ.c`, `UbrieftraZ.c`, …) are intact; only the MP
+menu entry was removed.
+
+**Status: Tier 3 (mod fork).** Re-enabling = editing a game data table in
+`src/game/front.c` — that's a game-logic change, disallowed in this repo
+(non-negotiable #2). Viable as a separate mod branch/fork ("8 more MP maps"),
+or as a documented cheat-menu route (the debug menu's `level`/`region` options
+may already jump to any level ID — verify).
+
+### E. Per-level unused props & geometry ("Unused stuff by level" page)
+
+~150 intact screenshots, grouped by level. Cross-referenced against the object
+table and level IDs:
+
+- **Streets** (campaign stage 12; `LEVELID_STREETS`): an entire prop kit was
+  never placed — `StreetsCars`, `StreetsLamp[Base/Big]`, `StreetsSign[2/3]`,
+  `StreetsTrafficLight`, `StreetsShovel`, `StreetsCrossing`, plus two cut set
+  pieces `GE64-StreetsArea1/2` and Ourumov's car driving/crashing
+  (`StreetsOuruGo`, `StreetsOuruCrash`, `GEOurumovsCar`). Suggests a cut
+  street-chase scene.
+- **Silo**: `SiloVentShaft`, `SiloLadder`, `SiloLaunchDoors`,
+  `SiloWalkway2Door/Guard`, `SiloMissingHandrail` (a bug/oddity screenshot),
+  `GoldenEye_UnusedStartingPoint`, and prerelease-only `PRSiloElevator`,
+  `PRSiloLamps`, `SiloCutWalkway`, **`ThirdSiloEditor`** (editor view of a
+  third silo that didn't ship).
+- **Facility**: PR-vs-final wall sets (`FacilityWalls[Final]`,
+  `PRFacilityWalls`, `ArchivesWalls`), plus cut rooms: `FacilityBathroom`,
+  `FacilityConveyor`, `FacilityGasTanks`, `FacilityLabTanks`,
+  `FacilityWalkway`, `FacilityArmedScientistPR`, `FacilitySatBoxTex`,
+  `GoldenEye007-FacilityPhoto`.
+- **Archives**: `ArchivesOverview`, `ArchivesLamp[Scan]`, `ArchivesPhoto`,
+  `PRArchivesNoWalls` (wall-less build view).
+- **Bunker**: `BunkerExtraMons[Side]` (extra monster/guard spawns),
+  `BunkerPIP`, PR `BunkerLamp`.
+- **Caverns**: `CavernsPursueObj` (a cut "pursue" objective marker), PR
+  `CavernsWalkway`.
+- **Dam**: `DamIsland`, `DamPlatform`, `DamDockDoors`, `DamEndDuct`,
+  `DamTruckDoor`; region-diff shots `DamCompUS/EU`.
+- **Frigate**: `FrigateHarpoonScan` (scan of a harpoon model),
+  `PRTrainTargetGlass`, `Pdest_harpoonZ[2]`, `Ptorpedo_rack`,
+  `FrigateMoneypennyPR` (a Moneypenny model in the Frigate PR build!),
+  region-diff `FrigateIntroUS/JP`.
+- **Aztec/Temple**: `AztecConsolePads1-4`, `GE-AztScreen2781/2789`,
+  `AztExtraMainframe`, `AztDronePadsLabel`, `unused-Aztec-Path` (a whole
+  unplaced path), `EgyptianRed/WhiteClouds` (two skybox variants),
+  `TempleSkySolo/Multi`, PR: `AztBlueSuitPR` (cut enemy suit),
+  `AztHeavyFogPR`, `AztTableScreensPR`.
+- **Surface**: `SurfaceBookCrate`, `SurfaceObsPad`, `SurfaceTower`,
+  `SurfaceJerryCan`, `SurfaceHutTable`, `SurfacePropHut`, PR
+  `SurfaceOverviewPR`, `SurfaceVent[PR]`, `SurfaceDish[PR]`.
+- **Train** (campaign stage 14): `GE007-TrainSecretRoom` (a hidden room),
+  `TrainTargetGlass`.
+- **Misc props/vehicles**: `GEMotorbike`, `GERedTruck`, `GESovietBoat`,
+  `GEHelicopterPilot`, `GEBiker`, `GoldenEye-moonfemale` (`moonfemale/` chr
+  model exists), `OurumovKey/Briefcase`, `GEDeskMat`, `GoldenEye-Crypt`
+  (confirmed orphaned map — see note below),
+  `GE64-BridgeRooms`, `GEJunglePicture`, `Runwaypicture`,
+  `Controlicon`, `Cactus`.
+- **Orphaned level geometry** — `assets/obseg/bg/` holds per-level dirs for
+  `ame arch arec ark azt cat cave crad cryp dam depo dest dish len oat ref run
+  sev sevb sevx silo stat tra`. Notable: `cryp` (Crypt) has full geometry +
+  briefing (`UbriefcrypZ.c`) but **no `LEVELID_CRYPT` entry** in
+  `bondconstants.h` — fully orphaned. `len` (Lenin statue area, cf.
+  `StatueLeninPR`) and `dish`/`cat`/`oat`/`arec`/`ame`/`ark`/`ref` are further
+  level dirs beyond the shipped set. No `citadel` dir — its geometry was
+  either removed or shared (TCRF's 5 Citadel screenshots show a finished map,
+  so it existed in some build).
+
+**Status: Tier 2.** All models are in the ROM's object table (spot-checked:
+`PchrtesttubeZ`, `Pdest_harpoonZ`, `Pdoor_roller1-4Z`, `PhatfurryZ`,
+`Pletter_tray1Z`, `Pmissile_rackZ`, `PsilencerZ`, `Psteel_door2[ b]Z`,
+`Ptorpedo_rack`). Placing them needs level-data editing (object spawn tables) —
+a data-mod / level-editor project, not a port change. The PR-vs-final texture
+pairs (`*PR__1vt.jpg`) are interesting for a "pre-release textures" cosmetic mod
+via the `tools_pc` asset pipeline — but the PR ROM itself isn't available here,
+so source assets would have to come from TCRF's screenshots (low-res) or a
+donated PR dump.
+
+### F. Unused characters & faces
+
+TCRF main-page imagery: `UnusedFace1/2/3` (each with F/S1/S2 views),
+`GE64-FemHead1-4`, `KenFaceUnused/Used`, `Rosika[Compare]`, `SciCompare`,
+`FemaleSci`, `GEBonds`, `Terrorists`, `TerroristBiker`, `StPetersburgGuard`,
+Bond-suit sets named after actors: `Connery*`, `Dalton*`, `Moore*` (each with
+HeadFront/Back/Left/Right + Jacket pieces), `GEArmor[our]`.
+
+Cross-reference:
+
+- The MP character table (`front.c:601+` `mp_chr_setup[]`) is huge — ~40 named
+  entries beyond the 8 selectable, including `ROSIKA`, `KARL`, `MARTIN`,
+  `MARK`, `DAVE`, `DUNCAN`, … `TERRORIST`, `BIKER`, `STPETERSBURGGUARD`,
+  `HELICOPTERPILOT` — Brosnan-body + swapped-head combos. The "unused faces"
+  are almost certainly extra head models in this pool that no body/entry uses.
+- Head model dirs exist under `assets/obseg/chr/`: `headken` (the Ken face),
+  `headbrosnan*` (4 costume variants), `moonfemale`, plus ~30 named heads.
+  The actor-named suits (Connery/Dalton/Moore) do **not** appear as chr dirs —
+  **resolved in round 2**: the ROM holds exactly 80 `C*Z` character models and
+  none is a former-Bond actor; only the enum slots + the flattened actor-switch
+  code (`bondview2.c:391-460`) survive (see banner, item 4).
+
+**Status: Tier 2/3.** Cosmetic mod (extra MP faces) = asset-level work if the
+models are in the ROM; verify by dumping `assets/obseg/chr/*/Model.c` headers.
+
+### G. Prerelease / dev-build evidence
+
+Prerelease page (body blocked; filenames + embeds only):
+
+- PR-vs-final comparison pairs: Taser, KF7, GrenadeLauncher, RocketLauncher
+  (+watch versions), SurfaceVent/Dish, `StatueLeninPR`, Facility walls/rooms
+  (§E), ArchivesWalls, CavernsWalkway, SiloCutWalkway, ThirdSiloEditor,
+  PRSiloElevator, BunkerLamp, OutletConsoles. Pattern: the PR build had more
+  weapons (watch-mounted guns!) and different Facility/Silo/Aztec geometry.
+- **Dev-build videos** (YouTube embeds captured in the export):
+  - "Goldeneye 007 - Shoshinkai/Space World 1996"
+  - "Nintendo of America E3 1996 Take Away Video (VHS Rip)"
+  - "Goldeneye Beta WalMart Video"
+  - "Goldeneye 007 Promotional Trailer 1996"
+  - "N64 vous n'en reviendrez pas (VHS RIP 1997)"
+  - "64History - N64 B-Roll (1995)"
+  - "Escape (Banjo-Kazooie, GoldenEye 007)" — engine sibling footage.
+  Useful for dating PR features; not actionable in-repo.
+
+### H. Misc oddities (main page, unverified)
+
+- `GoldenEye007MickeyMouse` (by-level page, 2 KB image) — no "mickey" object in
+  the resource table; likely a texture/model easter egg spotted in a level.
+- `Unused_bond_walk.gif` — an unused Bond walk animation (check
+  `assets/animationtable_entries.c` for orphaned anim IDs).
+- `GoldenEye007-MovieLogoUnused` / `-MovieNoLogoUnused` — alternate intro logo
+  frames (title sequence data; `src/game/brief*`? verify).
+- `GE_UnusedAlarm`, `GoldenEye-BloodImpact` / `BoxBlood` / PR `OpaqueBlood` —
+  blood-effect variants (cf. `src/game/blood_animation.c`).
+- `GoldenEye007-BarrelUnused` / `-SmallBarrelUnused` — barrel props never placed.
+- `GoldenEye-OddDay`, `Sight[Alt]`, `MountainTex`, `background`, `Pbin1Z`,
+  `PchrtesttubeZ[Explode]`, `PitonGunBungee`, `Psev_door[3_wind]Z` — props in
+  the table, placement unverified.
+- Bugs & Notes articles: **nothing recoverable from this export** — re-scrape.
+
+## 2. Feasibility summary
+
+| Tier | Item | Effort | Where it lands |
+|---|---|---|---|
+| **0 — already works** | Debug menu (U+D C-hold), free cam, line mode, ramrom record/replay, cheat-grantable rocket/grenade/P90 | verify in-game; document keybinds | docs + maybe `input.c` keybind for U+D c-buttons |
+| **1 — port-layer hook** | Grant taser/spectre/autoshot + unused items (watch identifier, bomb case, …) via config toggle replicating the cheat grant path (`bondinvAddInvItem` + `give_cur_player_ammo`) | small; follow F10-toggles pattern (`feat/f10-game-toggles`) | `port/src/` only |
+| **2 — data/asset mod** | Place unused props per level; extra MP faces; PR texture swap | needs level-editor or object-table patching; separate project | data mod, not this repo's code |
+| **3 — game-logic change (mod fork)** | Re-enable 8 cut MP maps (`front.c` table), campaign reordering | one-line-per-map table edits + setup fixes ("xbla setup" = unknown editor flag) | separate mod branch/fork only |
+
+## 3. Next steps
+
+1. **In-game verification pass** (PC build): open debug menu; confirm free cam,
+   `display speed`, level switch; enter the 2X rocket/grenade/P90 cheat codes;
+   screenshot via `grab rgb`. Record results here + findings.md if anything new
+   breaks (Dxx).
+2. Confirm which region macros the PC build defines vs the `BUGFIX_R1` guards in
+   the weapon-grant cheats (non-negotiable #3) — the grants may be dead code in
+   our build.
+3. Dump `assets/obseg/chr/` model headers to identify the UnusedFace1-3 /
+   FemHead1-4 models concretely.
+4. ~~Re-scrape TCRF article bodies~~ — **done**; all six bodies recovered into
+   `backlog/cut-content/articles/` and cross-referenced (see RESEARCH.md §0).
+5. If Tier-1 item granting is wanted: spec it as an F10 toggle set, port-layer
+   only, each entry citing the cheat-code precedent in `cheat.c`.

docs/dev/D356-SETTINGS-REGROUP-PLAN.md

@@ -0,0 +1,369 @@
+# D356 — Settings regroup: functional sections, save-file scoping, per-section reset
+
+Status: **LANDED (D356, 2026-09-27, port-only)** — signed off and implemented
+this session; verification in `docs/dev/findings.md` D356 (GE_WSPROBE_RESET
+front + in-stage probes, regressions, build). Supersedes the "BOND FILE"
+section introduced in D353. Baselines: Turok PC port options (Nightdive, list
+provided by the maintainer), the PD port's `port/src/optionsmenu.c`
+(`C:\Users\james\Source\Repos\pd_port`), and plan §6 of
+`docs/dev/OPTIONS-MENU-PLAN.md` (the original "align with Turok" note).
+
+## 1. Goal
+
+The D353 "BOND FILE" section is the one section named after *where a value is
+saved* — an implementation detail — while every other section is functional
+(DISPLAY, GRAPHICS, MOUSE/AIM, CONTROLLER, GAME). Its contents are also a
+mishmash (aim/look toggles + HUD toggles + audio), and it exposes N64-watch
+rows that **collide with or duplicate** the PC-native rows the port added
+(watch look-invert vs `Input.MouseInvertY`/`Input.PadLookInvertY`; watch aim
+control vs `Input.AimMode`). The baseline ports (Turok, PD) never name a
+section after the save and never re-expose legacy overrides.
+
+D356 rewrites the row table so that:
+
+1. Every section is functional, using the baseline names:
+   **INPUT, GAMEPLAY, GRAPHICS, AUDIO, VIDEO**.
+2. Save-file scope is communicated the PD way — *in the section title*
+   ("GAMEPLAY (File 1)"), generalized from the D353 BOND-FILE annotation —
+   plus a single **Save file: File N [change]** row at the top of the
+   options screen (PD "Player N" pattern; D354's default resolution applies).
+   "Bond file" appears nowhere in the UI.
+3. Redundant/colliding watch rows are removed from the **menu surface only**
+   (the established D181/D216/D304 pattern): keys, in-game watch behavior,
+   and ini hand-editing all remain untouched. No game-code change (rule 2).
+4. A **Reset to defaults** action row per section (Turok's per-category
+   reset; plan §6 Gate E, made concrete) with a **confirmation contract**:
+   edge-triggered activation (no auto-repeat), two-step arm→confirm, never
+   repeatable (WATCH-SETTINGS-PLAN §6 gate: "separate confirmation and
+   persistence policy before wiring a button" — §5.4 below is that policy).
+5. A **context-aware file accessor** (front-end target vs active stage
+   target) with the "none" chooser position retired, so "Save file: File N"
+   is always a true statement (§5.5).
+6. Section resets iterate the section's **declared** rows (including
+   conditionally hidden ones, §5.6) and reset verification exercises the UI
+   action itself, headlessly (§5.8).
+
+## 2. Non-goals
+
+- No `src/game` changes; the N64 watch menu keeps all its options and its
+  N64 wording (ground truth).
+- No key rebinding (Phase 4) — but the section layout leaves room for a
+  "KEY BINDINGS" page exactly where Turok/PD have one.
+- Master volume stays M3-backlog; the AUDIO section is shaped for it
+  (Turok's Master/Sound/Music trio).
+- N64 build untouched.
+
+## 3. Exposure filter (menu surface only)
+
+| Row (key) | Verdict | Reason |
+|---|---|---|
+| `Bond.Look` ("Look up/down (watch; stacks)") | **Hide** | Duplicates `Input.MouseInvertY` + `Input.PadLookInvertY`; stacking both produces the double-negation trap. |
+| `Bond.AimControl` ("Aim control") | **Hide** | Collides with `Input.AimMode` (N64 vs PC aim model) — two rows fighting over the same domain. |
+| `Bond.AutoAim` | Keep | Unique gameplay assist; orthogonal to aim style/range. |
+| `Bond.LookAhead` | Keep | Unique; no PC counterpart, no conflict. |
+| `Bond.Sight`, `Bond.Ammo` | Keep | Unique HUD-visibility options; compose with `Game.HudScale`. |
+| `Bond.Music`, `Bond.FX` | Keep | Core of D350–D355. |
+
+Hidden rows are commented out in `rows[]` with a D356 note (D181/D216 style:
+config keys + watch path stay live; ini power users can still set them).
+
+## 4. New layout (5 pages + save-file row)
+
+`MAX_PAGES=8`, `MAX_PROWS=15` — all pages below the caps (D353 overflow log
+still guards).
+
+Top row (drawn by `frontoptions.c` above the paged content, not paged):
+**`Save file: File 1 [change]`** — cycles files via `watchSettingsChooseFile`
+(D354 default resolution: explicit pick > viewed folder > first valid;
+auto-init fallback). Hidden in F10 (existing `optionsRowIsBondChooser`
+mechanism, generalized). F10 targets the active file, as today.
+
+| Page | Rows (key · kind) | Title annotation |
+|---|---|---|
+| **INPUT** | `Input.MouseSensitivity` · `Input.MouseInvertY` · `Input.AimMode` · `Input.AimRange` · `Input.PadLookInvertY` · `Input.PadDeadzone` · `Input.PadTriggerPct` · *Reset to defaults* | |
+| **GAMEPLAY** (File N) | `Bond.AutoAim` · `Bond.LookAhead` · `Bond.Sight` · `Bond.Ammo` *(save, dim "(save)" tag)* · `Game.SkipIntro` · `Game.NoHitFlash` · `Game.AllUnlocked` · `Game.HudScale` · *Reset to defaults* · `__QuitToDesktop` | (File 1) |
+| **GRAPHICS** | 11 rows unchanged from D353 · *Reset to defaults* | |
+| **AUDIO** (File N) | `Bond.Music` · `Bond.FX` *(save; title annotation only — homogeneous section, PD-style)* · (master volume, M3) · *Reset to defaults* | (File 1) |
+| **VIDEO** | `Video.Fullscreen` · `__Resolution` · `Video.VSync` · `Video.FpsCap` · `Video.DisplayFPS` · *Reset to defaults* | |
+
+Moves from D353 layout: mouse/aim + controller rows merge into **INPUT**
+(the two old headers `__HdrMouse`/`__HdrPad` are dropped); DISPLAY → **VIDEO**
+(rename, `Video.DisplayFPS` moves from GAME); GAME section is renamed
+**GAMEPLAY** and absorbs the surviving watch toggles; the `__HdrBond` header
+and `__BondFile` chooser row are retired (replaced by the top save-file row);
+`Bond.Look`/`Bond.AimControl` rows are commented out (§3).
+
+Scope annotation: the D353 "(File N)"/"(no file)" title annotation — today
+special-cased to the BOND FILE page via `optionsRowIsBondChooser()` — is
+generalized: **any page containing per-file rows annotates**. Sections with
+per-file rows: GAMEPLAY, AUDIO.
+
+F10: same table (F10 already shows all rows, chooser hidden). The
+(Gameplay/Audio) annotation in-stage shows the active file number (the
+context-aware accessor, §5.8 — *not* the raw chooser value). "Reset to
+defaults" rows stay visible in F10 (O2) under the same confirmation
+contract (§5.4).
+
+**(save) tag (O1):** the four mixed-scope GAMEPLAY save rows carry a subtle
+dim "(save)" suffix — the only place a section mixes scopes. AUDIO is
+homogeneously per-file, so its title annotation is sufficient (no tags).
+Implementation: one `int saveScoped` field on `struct Row` + dim-ink suffix in
+the row-draw path (frontoptions.c already draws the dim annotation).
+
+## 5. Code changes
+
+All in `port/` (D350-family); files: `port/src/optionsoverlay.c`,
+`port/src/frontoptions.c`, `port/include/optionsoverlay.h`,
+`port/src/watchsettings.c` (only if reset needs a new enqueue helper —
+expected not to, see below).
+
+### 5.1 Row table (`optionsoverlay.c`)
+
+- Rename headers: `__HdrDisplay`→VIDEO (last page), add `__HdrInput`
+  (INPUT), `__HdrGameplay` (GAMEPLAY); delete `__HdrBond`, `__HdrMouse`,
+  `__HdrPad`, and rename `__HdrGame`→GAMEPLAY. New section order in the
+  table: INPUT, GAMEPLAY, GRAPHICS, AUDIO, VIDEO (Turok's order: Input,
+  Gameplay, Graphics, Audio, Video).
+- Move the 7 mouse/aim + 3 controller rows under INPUT; move the 4 surviving
+  `Bond.*` toggles + music/FX into GAMEPLAY/AUDIO; comment out
+  `Bond.Look`/`Bond.AimControl` (§3).
+- New `ROW_ACTION` rows, one per section: `.key="__Reset<Section>"`,
+  `.label="Reset to defaults"`. All five use one shared handler
+  (`rowResetSection(section)`).
+
+### 5.2 Save-file top row (`frontoptions.c`)
+
+- New non-paged line above the page content: "Save file: File N" + a
+  "change" control (left/right or Enter cycles, reusing
+  `watchSettingsChooseFile(dir)`; D354 lazy default fills N). Dim ink, same
+  visual language as the D353 annotation. `selected_folder_num` unchanged —
+  the row never touches the game's active file (plan Gate B invariant).
+  **Display value reads through the context-aware accessor (§5.5), never
+  the raw chooser value.**
+- **Unavailable state (maintainer consistency fix):** the D354 auto-init
+  fallback creates the blank file on a *later game tick*, so at an
+  empty/corrupt-save startup the accessor can return -1 for a few ticks.
+  The row then shows the unavailable state ("(no file)"), never a file
+  number the write path cannot use. Once creation succeeds the same tick
+  the row shows "File 1".
+- F10 context: row suppressed (extend the D353 accessor to cover it).
+
+### 5.3 Reset to defaults (Gate E)
+
+- **Per-file rows** (GAMEPLAY/AUDIO save rows): defaults = **BLANKSAVEDATA**
+  (`src/game/file2.c` — the game's own factory save; per WATCH-SETTINGS-PLAN
+  §6, watch rows reset to BLANKSAVEDATA/`DEFAULT_OPTIONS` for the selected
+  file, *not* from a global ini snapshot; new saves start Music/FX 0xFF,
+  auto-aim/sight/look-ahead/ammo enabled — read the fields from
+  `BLANKSAVEDATA` at reset time, no hardcoded table). Reset re-applies live
+  via the existing `watchsettings` apply path **and** persists field-scoped
+  to the selected file (`watchSettingsPersistField`), exactly like a normal
+  commit. In-stage: enqueued through the D352 command queue (N field commits
+  with `commit=1`) — no new threading; game thread applies + persists.
+- **Ini rows** (INPUT/GRAPHICS/VIDEO/GAMEPLAY-ini): `config.c` has no
+  central default table (first-write "defaults" = current values,
+  config.c:280), so the section handler uses an explicit
+  `static const struct { const char *key; double def; }` reset table in
+  `optionsoverlay.c`, mirroring the port's C initializers (each entry
+  commented with its source variable; **verified against the initializer at
+  implementation time** — e.g. `Game.AllUnlocked` = **0**,
+  `port/src/video.c:116,348`; the D257 comment in optionsoverlay.c that
+  says "default ON" is stale and is corrected as part of D356). Front-end:
+  write live + `configSave()` (existing). In-stage ini resets: applied
+  **immediately** (O3 — consistent with how every other ini row already
+  behaves when changed in F10; video.c applies most display changes on the
+  fly).
+- **Resolution is excluded from the VIDEO reset (maintainer item 2).**
+  `__Resolution` is an action backed by `s_resSel` +
+  `videoRequestWindowSize()` — not a registered config row, so the numeric
+  default table cannot reset it, and a "default window size" is a
+  display-capability choice, not a tunable. The D356 findings entry
+  documents the exception explicitly: VIDEO reset covers Fullscreen, VSync,
+  FpsCap, DisplayFPS — Resolution keeps the player's current choice.
+- **Scope-aware by construction:** a section's reset touches each row
+  **by its own scope** (file rows → that file's BLANKSAVEDATA values;
+  ini rows → ini defaults). No cross-scope surprise (Gate E: "do not make
+  a global reset wipe per-file watch settings" — a reset of the selected
+  file never touches other files; §5.8 verifies this).
+- **Activation contract (§5.4) applies to every section's reset row.**
+
+### 5.4 Reset activation contract (maintainer item 1)
+
+A reset is a *destructive bulk write* — GAMEPLAY's in particular changes
+both ini values **and** the selected save in one action. WATCH-SETTINGS-PLAN
+§6 gates confirmation + persistence policy; this is that policy:
+
+- **Edge-triggered:** reset actions fire only on a *fresh* event. The
+  frontoptions left/right key repeat (held keys re-issue the action) is
+  suppressed for `ROW_ACTION` reset rows — the arming/confirm events must
+  carry a no-repeat flag (SDL keydown with `repeat==0` / a fresh click),
+  so a held key or held mouse button can never arm *and* confirm, nor
+  re-trigger.
+- **Two-step confirm:** first activation **arms** the row (label swaps to
+  "Confirm reset…", armed highlight); a second activation within **3 s**
+  commits. Timeout, or navigating to another row, disarms (label
+  restores). Arm state is per-row, per-open; opening/closing F10 or the
+  options screen clears all armed resets.
+- **One commit per confirmed activation.** No auto-repeat, no re-arming on
+  the same event. F10 and the options screen share the identical contract
+  (O2: rows stay visible in F10; confirmation makes accidental in-game
+  resets unlikely).
+- The confirmed action then dispatches the section handler (§5.3) exactly
+  once.
+
+### 5.5 Context-aware file accessor; retire "none" (maintainer item 3)
+
+`watchSettingsFolder()` returns the raw `chosen`, which may be -1 before
+`frontFolder()` lazily resolves, and in-stage `chosen` can differ from the
+active file (`snapFolder`). The generalized title/top-row accessor must be
+**context-aware**, not a repurposed chooser-value read:
+
+- New `watchSettingsActiveFolder(void)` (name tentative):
+  - **Front-end contexts** (options screen, F10-on-file-select, title):
+    the *resolved front target* — explicit `chosen` if set, else
+    `selected_folder_num` if valid, else first valid folder (i.e. the
+    `frontFolder()` resolution; the accessor is pure-read and does not
+    mutate `chosen` — lazy mutation stays in `frontFolder()`/the
+    auto-init fallback).
+  - **In-stage (F10):** the *active stage target* — `selected_folder_num`
+    (the file the stage loaded, `snapFolder` at apply time).
+  - The D353 title annotation and the §5.2 top row both read through this
+    accessor, in both surfaces.
+- **The chooser's "none" position is retired.** `watchSettingsChooseFile`
+  cycles FOLDER1..MAX only (dropping the -1 stop). Rationale: D354's
+  default resolution + boot-time BLANKSAVEDATA slots + the auto-init
+  fallback guarantee a valid target, so "none" was only reachable by
+  deliberate cycling and serves no remaining purpose — and "Save file:
+  File N" (the §5.2 invariant) is not true when `chosen == -1`.
+  `watchSettingsFolder()`'s "-1 = none" contract is updated/superseded by
+  the new accessor.
+
+### 5.6 Reset iterates declared rows (maintainer item 4)
+
+The section handler iterates the section's **declared row range in
+`rows[]`** (from its header to the next header), *not* `s_visIdx`/the
+currently visible list — conditionally hidden rows (GRAPHICS draw/LOD
+sliders while their auto-FOV toggles are on) must be reset too, or they
+silently survive a purported section reset. Hidden-row defaults come from
+the same default table; their *live* values are written directly (the
+`ptr`/`rowSet` path), visibility is irrelevant. The `(save)` tag, hidden-row
+resets, and the reset table are all keyed off `rows[]` indices, never the
+visible list.
+
+### 5.7 F10
+
+Unchanged machinery: shared table, save-file row suppressed (the D353
+accessor pattern extended to the §5.2 top row). Annotation shows the active
+file via §5.5. "Reset to defaults" rows stay **visible** in F10 (O2) under
+the §5.4 confirmation contract.
+
+### 5.8 Reset verification probe (maintainer item 5)
+
+New env-gated probe **`GE_WSPROBE_RESET=<tick>`** (GE_D314/GE_WSPROBE
+pattern): at tick N of a *front-end* boot it drives the **UI action path**
+through the same handler the confirm step calls (arm → confirm → dispatch,
+no bypass). **Every section being verified is itself dispatched:** the
+probe dispatches all five section resets (INPUT, GAMEPLAY, GRAPHICS, AUDIO,
+VIDEO) via arm → confirm, and after *each* dispatch verifies that
+section's rows:
+
+- **INPUT / GRAPHICS / VIDEO (ini rows):** values == the default table.
+  GRAPHICS specifically covers the **hidden** draw/LOD sliders (hidden
+  while their auto-FOV toggles are on) — a section reset must land them
+  even while they are not visible; VIDEO's `__Resolution` is the documented
+  exclusion (unchanged, logged).
+- **GAMEPLAY (mixed scope):** the four save rows == BLANKSAVEDATA
+  (auto-aim/sight/look-ahead/ammo) *and* the ini rows (SkipIntro/
+  NoHitFlash/AllUnlocked/HudScale) == the ini default table — the two
+  scopes land independently in one action.
+- **AUDIO (save rows):** Music/FX == BLANKSAVEDATA (0xFF raw = 32767,
+  the `VOLUME_MAX` endpoint), not the probe's pre-dirtied 4096.
+- **Scope isolation (after all dispatches):** a *second* folder's
+  `save_data` is byte-identical to its pre-reset snapshot (a reset of the
+  selected file never touches other files).
+
+Front-end prep (tick N) first dirties live values (Music/FX → 4096,
+VSync/HudScale → non-defaults) and snapshots the second folder, so the
+verifications at tick N+1 prove the resets actually moved values back.
+
+In-stage dispatch is covered by the same env var on a `-level_XX` run:
+arm → confirm at tick N (file rows enqueue through the D352 queue — the
+probe logs the enqueued command count), drain at N+1, then the same
+per-section value verification against the post-apply state.
+
+### 5.9 No changes
+
+- `buildPages` in `frontoptions.c` (generic; 5 pages < MAX_PAGES),
+  `watchSettingsGameTick`/queue (D352/D354/D355 logic untouched), the D355
+  track-1 resync, `BLANKSAVEDATA` itself.
+
+## 6. Threading / persistence gates (unchanged, restated)
+
+- D350: no GE writes from the F10 input/render thread except the sanctioned
+  front-end commit path; in-stage edits queue to the game thread.
+- D352: queue holds across transitions; per-field coalescing.
+- D354: front contexts (including F10-on-file-select) route through the
+  chooser path; `frontFolder()` default resolution; auto-init fallback.
+- D355: Music commit + level-entry resync of the BGM (track 1) player.
+- D356 adds no new write path: reset = N existing commits (file rows) +
+  existing ini writes (ini rows).
+
+## 7. Docs
+
+- `docs/dev/findings.md` D356 entry + §F index row; regenerate
+  `findings-index.csv`.
+- `docs/dev/WATCH-SETTINGS-PLAN.md`: status + D353/D354 "Bond File" section
+  references updated; Gate E marked landed (subset: per-section rows).
+- `docs/dev/OPTIONS-MENU-PLAN.md` (tracked) + local notes: §6 "align with
+  Turok" annotated as landed via D356 (M3 master volume + key bindings
+  remain).
+
+## 8. Verification
+
+1. Clean NTSC build (`./build-pc.sh` / `cmake --build build-pc`).
+2. Headless smoke: boots to front end; log page count (5, under MAX_PAGES),
+   no `buildPages` overflow warning, save-file row resolves to File 1 by
+   default (D354), annotation on GAMEPLAY/AUDIO pages, no "none" reachable
+   (chooser cycles files only, §5.5).
+3. `GE_WSPROBE` / `GE_WSPROBE_FRONT` regression: identical pass as D355
+   (queue/commit paths untouched).
+4. **`GE_WSPROBE_RESET` (§5.8) exercises the UI action, not just direct
+   commits:** per-section arm → confirm → dispatch of all five sections,
+   with each section's rows verified right after its own dispatch
+   (ini == table, save == BLANKSAVEDATA, hidden GRAPHICS rows included,
+   VIDEO resolution untouched), then the second-folder byte-identity
+   check. In-stage dispatch: `GE_WSPROBE`-style queue check on a
+   `-level_XX` run (enqueued command count + post-apply state).
+5. **Confirmation contract check (§5.4):** a held key/click arms but never
+   confirms (edge-triggered); second activation within 3 s commits exactly
+   once; timeout/navigate disarms. Headlessly assertable via the probe
+   (arm-then-timeout leaves values untouched).
+6. Manual visual pass (owed, same list as D353): arrows through 5 pages,
+   save-file cycling updates the annotation live, `(save)` tag on the four
+   GAMEPLAY save rows, F10 in-stage, reset in stage vs front (including the
+   armed/confirm visual state), rapid slider drag.
+
+## 9. Open questions — RESOLVED (maintainer sign-off, 2026-09-27)
+
+- **O1:** **yes** — subtle dim "(save)" tag on the four mixed-scope
+  GAMEPLAY rows; AUDIO's title annotation alone is sufficient (homogeneous
+  section).
+- **O2:** **visible in F10**, provided resets require the §5.4 confirmation
+  step (which they do).
+- **O3:** **immediate** in-stage ini resets, consistent with existing ini
+  edits in F10.
+- **O4:** `__QuitToDesktop` stays in GAMEPLAY, **literally last — after the
+  Reset row** (section order: rows…, *Reset to defaults*, *Quit to desktop*;
+  the §4 page table is corrected accordingly).
+
+Layout itself is signed off by the maintainer (2026-09-27): five-page
+regroup + menu-only exposure filter, with the §5.4–§5.8 contracts as
+specified above.
+
+## 10. Estimate
+
+One commit. ~5 files (`optionsoverlay.c`, `frontoptions.c`,
+`watchsettings.c`, `port/include/optionsoverlay.h`,
+`port/include/watchsettings.h`), net +400/−140 (table reshuffle + reset
+contract + context-aware accessor + `GE_WSPROBE_RESET` are the new code).
+Findings/csv/plan updates ride along.

docs/dev/D357-SETTINGS-VALUES-PLAN.md

@@ -0,0 +1,160 @@
+# D357 — Settings thresholds & values: align display units/defaults with the PD port + Turok PC
+
+Status: **PROPOSAL — awaiting sign-off** (2026-09-27). Baselines: the PD port
+checkout (`C:\Users\james\Source\Repos\pd_port`, `port/src/optionsmenu.c` +
+`input.c`/`video.c` config registrations), the Turok PC (Nightdive) list from
+the maintainer's notes (`docs/dev/notes/OPTIONS-MENU-PLAN.md` §6 — *taken from
+user notes, not checked independently*), and the N64 watch (ground truth for
+the `Bond.*` rows only). Triggered by maintainer report: the current values
+are "a bit confusing".
+
+Companion change landed with this doc's review: the terminology settled on
+**"Profile"** as the end-user term for a per-player game file -- the
+front top row reads **Profile**, the per-file row tag reads
+**"(per profile)"** and the F10 unavailable value reads **"Select a
+profile"** (§4).
+
+## 1. Problem
+
+The D356 regroup fixed the *layout*; the *values* still mix three unit
+families with no consistent rule:
+
+- **raw internal units shown as-is**: `Input.MouseSensitivity` (1–500, 100 =
+  1× — the "100" is a % of a 1.0 multiplier, not a count),
+  `Input.PadDeadzone` (raw 0–30000, `dispDiv=300` → "23%" but the step of 500
+  raw is 1.67 display-%, so the slider lands on 23, 25, 26…),
+  `Bond.Music`/`Bond.FX` (0–32767, `dispDiv=328`, step 128 = 0.39 display-%);
+- **N64-era vocabulary on PC rows**: texture filter "Nearest / Bilinear /
+  **3-Point**" (the N64 watch term for trilinear), "FOV scale %" instead of
+  degrees;
+- **defaults that don't read as defaults**: MSAA shows "4x" fine, but
+  `FpsCap` 0–1000 with step 1 invites 117 FPS; `Video.LodDistance` default
+  150% vs `DrawDistance` 150% with a 25-step grid (100/125/150/175…).
+
+The PD port is the house style to copy: per-stick sensitivity as a **±10
+multiplier (default 1.0, negatives invert)** (`input.c:1537`), mouse speed
+**-30..30 (default 2.5)**, deadzone **raw 0–32767 per stick+axis**, rumble
+**0–1**, MSAA as a **2x/4x/8x/16x dropdown**, frame cap as **"N FPS"**,
+volumes as 0–100 %. Turok's (user's list) conventions: single mouse
+sensitivity knob, per-section resets (landed, D356), master/sound/music
+volume trio (master still M3-backlog).
+
+## 2. Principles
+
+1. **Display, don't rescale the world.** Every change is port-only (row
+   table, `dispDiv`/step/`unit` fields, value-text, `kResetDefaults`): no
+   `src/game` change, and config *storage units* are kept wherever a change
+   would migrate existing ini files (principle 3).
+2. **Human units in the value column**: `%` on a 0–100 grid, `×` multipliers
+   with 1.0 as the default, `N FPS`, `Off/2x/4x/8x`, `Unlimited`. A slider
+   step must map to a **whole display unit** (the deadzone 1.67%-step bug is
+   the canonical example to fix).
+3. **Ini stability**: renaming a config key's storage unit is a migration.
+   Where the plan needs it, register a *new* key (e.g.
+   `Input.PadDeadzonePct`) and keep the old key as a read-once legacy alias —
+   the D333 `Input.AimMode`→`Input.AimStyle` alias pattern (`input.c:1962`).
+   Each migration gets a findings note.
+4. **`kResetDefaults` stays in lockstep** with the config C initializers
+   (D356 Gate E): every default change in this plan updates the table in
+   `optionsoverlay.c` in the same commit; the `GE_WSPROBE_RESET` probe
+   re-verifies.
+5. **Defaults = the config C initializers**, never a new menu-only default.
+
+## 3. Row-by-row audit & proposal
+
+Current state from `optionsoverlay.c` `rows[]` + the `configRegister*`
+ranges (2026-09-27). "Display" = what the value column shows today.
+
+### INPUT
+
+| Row | Now (default · range · step · display) | PD port | Turok (notes) | Proposal |
+|---|---|---|---|---|
+| Mouse sensitivity | 100 · 1–500 · 5 · raw `100` | `MouseSpeedX/Y` float −30..30, def 2.5 (sign = invert) | single knob | **Display as a × multiplier**: keep storage (100 = 1.0×), value text `%.1f×` (v/100); range 10–300 (0.1–3.0×), step 10 (0.1×). Label stays "Mouse sensitivity". |
+| Invert look (mouse) | Off/On | folded into the −/× sign of MouseSpeed | — | **Keep On/Off** (PD's negative-multiplier style is an alternative; a separate invert is simpler next to the × slider). Decision: confirm. |
+| Aim style / Aim range | N64/Centred (PC) · PC/N64 | — (GE-only, D337/D338) | — | Keep as-is (GE-specific; hiddenIfOn already sane). |
+| Invert look (controller) | Off/On | sign of stick scale | — | Keep. |
+| Stick deadzone | 7000 raw · 0–30000 · 500 · ÷300 → `23%` (1.67%-steps) | raw 0–32767 per stick+axis, `DEFAULT_DEADZONE` | MISSING | **New key `Input.PadDeadzonePct` 0–100, step 1, default 23** (7000/30000×100); `input.c` scales back to raw at apply; old key becomes a legacy alias (principle 3). Display `N%` on a whole-% grid. |
+| Trigger threshold | 23 · 1–99 · 1 · `%` | — (GE extra) | — | Keep. |
+
+### GAMEPLAY
+
+| Row | Now | Baseline | Proposal |
+|---|---|---|---|
+| Auto-aim / Sight / Look ahead / Ammo (profile) | Off/On (N64 watch 0/1) | N64 watch = ground truth | Keep; tag now reads **(profile)** (this doc's companion change). |
+| Skip intro / No hit flash / All unlocked | Off/On | Turok: screen-shake/hit-flash family | Keep. |
+| HUD scale | 100 · 75–150 · 5 · `%` | — | Keep (whole-% grid already; range cap D226). |
+
+### GRAPHICS
+
+| Row | Now | Baseline | Proposal |
+|---|---|---|---|
+| Anti-aliasing | 1/2/4/8, def 4, shows `None/2x/4x/8x`, restart | PD dropdown 2x/4x/8x/**16x**, def 4x | **Add 16x to the sequence** (`kMsaaSeq`, range clamp 1–16) — SDL/GL supports it; PD has it. Decision: perf cost on mid GPUs (restart already flagged). |
+| Texture filter | Nearest / Bilinear / **3-Point** | PC convention: Nearest/Linear/Bilinear | **Rename the enum names to `Nearest / Linear / Bilinear`** (3-point *is* trilinear; the N64 term is the last one left on a PC row). Storage 0/1/2 unchanged. |
+| Anisotropic filtering | 4 · 1–16 · 1 · `x` | Turok 1–16 | Keep; **dim/disable when filter = Nearest** (anisotropy only applies to filtered sampling) — `hiddenIfOff`-style guard, UI-only. |
+| FOV scale | 100 · 50–150 · 5 · `%` | Turok 3: 60–120° slider | **Display in degrees**: the 100% baseline is the N64 vertical FOV scaled to the port's widescreen math — value text `N°` (v/100 × baseline, 1 decimal); storage unchanged. Decision: degrees vs % (Turok uses degrees; % is the existing mental model — pick one, recommend degrees). |
+| Native widescreen / Widescreen auto FOV / Crop overscan | Off/On | — | Keep. |
+| Draw distance | 150 · 100–400 · 25 · `%` (hidden under auto-FOV) | Turok: draw-distance row | Keep the % grid (25% steps read fine); **step 25 → display already whole-%**. No change. |
+| LOD distance | 150 · 25–400 · 25 · `%` | — | Keep; note default 150 vs DrawDistance 150 is intentional parity. |
+
+### AUDIO
+
+| Row | Now | Baseline | Proposal |
+|---|---|---|---|
+| Music volume (profile) | 32767 · 0–32767 · 128 · ÷328 → 0.39%-steps | Turok: 0–100% | **step 128 → 328** (exactly 1 display-%; 32767/328 = 99.9 ≈ "100%"). Storage unchanged (N64 `VOLUME_MAX` semantics). |
+| FX volume (profile) | same | same | same. |
+| *(master volume)* | — | Turok trio | M3-backlog, out of scope (shape the section for it, D356 note). |
+
+### VIDEO
+
+| Row | Now | Baseline | Proposal |
+|---|---|---|---|
+| Fullscreen | Off/On | Turok: window mode (borderless missing) | Keep; borderless = separate backlog item. |
+| Resolution | action row (presets) | both | Keep. |
+| VSync | On/Off | both | Keep. |
+| Frame rate cap | 60 · 0–1000 · 1 · `Uncapped/N FPS` | Turok: "up to 120 FPS" / uncapped | **Preset grid**: 0/30/60/120/144 (step = next preset, wraps to Uncapped); value text already `N FPS`/`Uncapped`. Decision: preset grid vs free 1-step (recommend presets; 117 FPS has no purpose). |
+| Show FPS | Off/On | both | Keep. |
+
+## 4. Terminology (end-user term = "Profile")
+
+Decision (2026-09-27, UX review): the end-user term for a per-player
+game file is **"Profile"** — the per-player bundle of progress +
+per-file settings. Rejected: **"game file"** (the instruction manual's
+current term) reads, in modern PC usage, as the *program's* own files
+("Verify integrity of game files"), not the user's save; **"Save"** was
+the fallback (universally understood) but reads as a verb in the row tag
+and as progress-only, which these files are not. "Profile" covers both
+and fits the dossier styling of the screen.
+
+Final string set (both UIs: front options + F10 overlay):
+
+| String | Where |
+|---|---|
+| **"Profile"** + value `N` | front options top row (was "Save file: File N") |
+| **"(Profile N)"** / **"(none)"** | section-title annotation on save-scoped sections (was "(File N)"/"(no file)") |
+| **"(per profile)"** | per-file row tag (was "(save)", then "(profile)", then "(game file)") |
+| **"Select a profile"** | F10 unavailable value (was "Select file") |
+
+**Manual sync TODO:** the instruction manual's "game file" should be
+updated to "profile" (the manual is a port document we own).
+
+"Bond file" remains in code identifiers/config keys (`Bond.*` rows,
+`watchSettingsChooseFile`, ini keys) only -- never user-visible.
+
+## 5. Gates
+
+1. Port-only per principle 1; the deadzone key migration (principle 3) is
+   the only config-surface change and follows the D333 alias pattern.
+2. `kResetDefaults` updated in the same commit as every default/range
+   change; `GE_WSPROBE_RESET` (front + `-level_33`) re-run, all sections
+   `failures=0`.
+3. Build via `build-pc-cmd.bat` (the pi-shell MSYS env gap, D356 note).
+4. Visual check owed (maintainer): front options screen + F10 in all five
+   sections; the overlap fix from the same session (the level-1 save-file
+   row no longer paints under the first content row).
+
+## 6. Out of scope
+
+- Key rebinding (Phase 4), master volume (M3), output-device selection,
+  borderless window, per-axis controller sensitivity (PD-style four-knob —
+  GE's one-knob design is D238/D304).
+- Any `src/game` change; the N64 watch keeps its own values and wording.

docs/dev/F10-GE-STYLE-PLAN.md

@@ -0,0 +1,129 @@
+# F10 visual refresh — GoldenEye dossier styling (proposal)
+
+Status: **superseded by D363 after user playtest** — the dossier/paper
+concept below was implemented as D362, then replaced with a dark
+watch-green/Bank Gothic version. This is the historical proposal for a
+port-layer F10 overlay proposal, not a replacement for GE's pause watch or the
+front-end PC Options screen. Reference surfaces: `src/game/front.c`
+`constructor_menu15_cheat`/`frontSetupMenuBackground`, the existing
+`port/src/frontoptions.c` cheat-list-inspired options screen, and GE's in-stage
+watch. Current overlay: `port/src/optionsoverlay.c` `optionsOverlayEmit`,
+`overlayRowAtY`, `sliderBarSpan`, `maxVisibleRows`.
+
+## 1. Direction and boundaries
+
+Make F10 read as an **MI6 dossier laid over the game scene**, not a generic
+SDL debug panel: dark translucent scrim, warm paper/ivory content card,
+black Zurich-style menu text, red for active options/slider fills and an
+occasional muted gold title/accent. The front-end PC Options already uses
+GE's actual 3D folder and Zurich text; use it as the visual reference, not
+as a display-list dependency. In-stage F10 must remain an inexpensive flat
+2D overlay: no loading a 3D wallet model, new ROM assets, front-end init
+functions or `src/game` modifications. Preserve the current two-level
+category -> settings navigation and the shared settings/commit API.
+
+The initial port-only implementation lives in `optionsOverlayEmit()` and
+uses one shared `OvLayout` for both 320x240 stage and 440x330 front canvases.
+Headless captures live under `scratch/d362-test/` (not distributed). Manual
+visual review on a bright stage and controller/mouse feel-check remain owed.
+
+## 2. Concrete visual hierarchy
+
+- **Backdrop/card:** keep an adjustable translucent dim over the scene;
+  replace the opaque blue-black rectangle with a near-opaque ivory panel
+  (subtle border and one offset shadow). Do not mimic the actual folder
+  texture unless a later, measured prototype proves the simple card
+  insufficient. Preserve legible contrast against both dark and bright
+  levels, including safe-area crop and widescreen pillarboxes.
+- **Masthead:** small gold/black `MI6 / OPTIONS` or `PC OPTIONS` heading,
+  fine black rule (a restrained `CLASSIFIED` stamp can be added later if
+  measured text fits) rather than a blue title/instruction block. Keep the
+  category name on the **same
+  page above its first setting**, especially INPUT over Mouse sensitivity.
+- **Root:** numbered `1. Input` ... `5. Video`, GE's dossier/menu numbering
+  and title case as on `frontoptions.c`; a narrow translucent dark selection
+  box behind the focused item. Category order and labels stay unchanged in
+  the shared row table; casing is presentation-only.
+- **Section:** a compact `PREVIOUS`/Back tab, title and optional
+  `(Profile N)` annotation, then two columns: label at left, value at right.
+  Unselected values in black, active/toggled values in GE's dark red
+  (`0xA00000FF` is the cheat-screen reference). Slider tracks are thin
+  charcoal with a red fill and an obvious knob; show the numerical value
+  outside the bar. A mixed-scope `(per profile)` marker must remain legible
+  without colliding with the value column; measure it and, if necessary,
+  use a small second line rather than silently removing the distinction.
+- **Actions:** Reset retains its two-press/three-second confirmation and
+  displays `CONFIRM` in red only while armed. Quit remains visually distinct
+  from resets (and retains its existing activation semantics). Back/Close
+  affordances should match the actual click targets, not become decoration.
+- **Footer:** one quiet, short line for mouse/arrows/controller, with an
+  explicit `ESC: Back / F10: Close` cue. No newly invented glyphs or fonts
+  that may be missing from the game's text bank. FPS readout is independent.
+
+Suggested layout sketch (not pixel positions):
+
+```
+  MI6  /  PC OPTIONS                         CLOSE
+  -----------------------------------------------
+  PREVIOUS     GRAPHICS
+  Anti-aliasing                            2x
+  Texture filter                     Bilinear
+  Draw distance         [------|----]     50/100
+  ...
+  Reset to defaults                     [ENTER]
+  ESC Back  /  F10 Close
+```
+
+## 3. Implementation boundaries
+
+1. Extract a port-only layout helper for fonts, palette,
+   panel rectangles and spacing; preserve `rows[]`, `rowAdjust`, persistence,
+   file scoping, reset logic and input bindings. Use GE's loaded Zurich Bold
+   font for body *only after* validating it exists on both stage and front
+   contexts; Bank Gothic can remain a fallback/header font. Text clipping
+   must use the whole viewport as `textRender` expects.
+2. Replace only the fill/text passes in `optionsOverlayEmit()` first. Emit
+   fills before text as currently, reset GBI state explicitly and keep
+   `OV_BUF_CMDS`/DL size bounds. Avoid mutable texture uploads or new assets.
+3. One shared geometry calculation must drive panel/card positions,
+   `maxVisibleRows`, row Y, slider-bar span, close/back hitboxes, and
+   `overlayRowAtY`. In particular, don't change visual row spacing without
+   updating hit-testing (D304/D316), and don't use naive OS-window pixel
+   mapping instead of `gfx_get_ui_screen_rect` (D316/D335). When a page
+   scrolls, keep its section title visible; a clipped row cannot be clicked.
+4. Use measured text widths to reserve space for values, `Confirm`,
+   `(Profile N)` and restart markers. At 320x240, allow scrolling/short
+   contextual hints, not overlapping text or tiny glyphs. At 440x330 and
+   ultrawide, centre or constrain the card rather than stretching the
+   columns across the entire viewport.
+5. Make any GE-like UI sound effects opt-in to a *separate* follow-up: F10
+   runs in controller polling, and D361 prohibits game save/audio calls
+   from that thread. A cosmetic refresh must not reintroduce that lockup.
+
+## 4. Acceptance gates
+
+- Compare screenshots with the existing front Options/cheat dossier and the
+  in-stage watch; user reviews the live palette/layout before closing the task.
+- Native 320x240, front-end 440x330, windowed 4:3, 16:9 and 21:9,
+  fullscreen, safe-area crop on/off: INPUT title visible; no text clipping,
+  unreadable values, wrong hitboxes, phantom/duplicated bottom rows or
+  overflow in the display list. Check graphics's longest labels and AUDIO's
+  per-profile markers with and without a valid file.
+- Mouse click/drag/wheel, arrows and D-pad/stick, ESC back, F10/Start/X
+  close, focused/armed reset, and quit action all behave **exactly** as
+  before. F10 Audio on file select still commits via D361's game-thread
+  queue; test both fresh and existing EEPROM without altering the user's
+  save (backup/restore for probes).
+- With overlay closed, append no panel DL and retain existing golden frame
+  hashes (unless FPS display is explicitly enabled). Run `./build-pc.sh
+  ntsc-final`, link/duplicate-symbol checks, front-end + stage smoke,
+  `GE_WSPROBE_F10FRONT` and targeted live playtest. Log the result in
+  `docs/dev/findings.md` after implementation, not in advance.
+
+## 5. Explicit non-goals
+
+No fullscreen 3D folder in gameplay, changes to the N64 watch, new config
+keys, row wording/value changes, save-format changes, controller remapping,
+new persistent assets, or `src/game` behavioral edits. The front-end PC
+Options screen is a **visual reference**, not part of the first styling
+patch; harmonizing its tiny decorative details is a later optional pass.

docs/dev/GE-ENV-PROBES.md

@@ -3,7 +3,7 @@
 Every `getenv("GE_…")` in the tree. The table prose is hand-curated;
 **`tools_pc/gen_env_probes.py`** re-greps the live sites and reports drift
 (NEW / GONE vars + a fresh file:line map) — run it before trusting the
-File:line cells. Last reconciled 2026-09-04 (M-51). All are **env-gated**: unset = zero behavior
+File:line cells. Last reconciled 2026-09-28 (v0.4.0 release sweep: rows added for probes introduced since 09-21 — D383 bind-capture smoke, D388 option-tree walk, D406 front-options diagnostics, D354/D344 watch-settings & quit-frame harnesses, D318B boundary suite, z-fight grid; the drift checker now also sees the cached env-flag wrapper reads from `port/include/envflag.h`). All are **env-gated**: unset = zero behavior
 change, so they are safe to leave in a release build (they only cost a
 `getenv` on the guarded path). "Dead" below means *the finding it was built
 for is closed* — the probe is strip-candidate scaffolding, not that it does
@@ -20,10 +20,12 @@ Two classes:
 | Env var | File:line | What it does | Status |
 |---|---|---|---|
 | `GE_PCDUMP` | `port/fast3d/gfx_opengl.cpp:1079` (`is_pcdump`), `gfx_opengl.cpp:700`, `port/src/video.c:188`, `port/src/config.c:46` (`configGetFrameDump`) | Per-frame framebuffer PPM dump to `$PCDUMP` dir (verification-ritual golden captures, `tools_pc/framediff.py`/`pixcount.py`). Also settable via `[Debug] FrameDump` ini (env wins). **M-33/D168: the writer now emits rows top-to-bottom — captures before that fix are vertically flipped.** | **live** |
-| `GE_INPUTSCRIPT` | `port/src/input.c:306` | Headless scripted controller-0 input: `"<frame>:<tok>,…;…"` (`SUP/SDOWN/SLEFT/SRIGHT/SNONE` sustain, buttons pulse). Sole input source when set. | **live** |
+| `GE_INPUTSCRIPT` | `port/src/input.c:306` | Headless scripted controller-0 input: `"<frame>:<tok>,…;…"` (`SUP/SDOWN/SLEFT/SRIGHT/SNONE` sustain, buttons pulse; `ZHOLD`/`ZREL` sustain fire, D207 M-201). Sole input source when set. | **live** |
 | `GE_INPUTLOG` | `port/src/input.c:329`, `port/src/config.c:53` (`configGetInputLog`) | Logs computed pad state (buttons + stick) each poll when non-zero. Also `[Debug] InputLog` ini. Also traces D165 `menuptr est/tgt/eff/stick`. | **live** |
 | `GE_STARTMENU` (+ `GE_STARTMENU_PAGE`, `GE_STARTMENU_DIFF`) | `src/game/lv.c:398-402` (`#ifdef PORT`) | Boot straight into a front-end menu id (13=MISSION_COMPLETE, 10=BRIEFING, 7=MISSION_SELECT, 12=MISSION_FAILED, 6=MODE_SELECT); `_PAGE`=folder row (def 1=Dam), `_DIFF`=0..3. Crash-test a screen fast. | **live** |
 | `GE_UNLOCK_ALL` | `src/game/debugmenu_handler.c:1098` (`get_debug_enable_all_levels_flag`, `#ifdef PORT`) | Mission-select shows every solo level (playtest jump-to-any-level aid). Cached in a `static int c`. | **live** |
+| `GE_DEBUG_UNLOCKALL` | `src/game/file2.c:404` (`#ifdef PORT`) | Forces the "all levels unlocked" flag TRUE regardless of the shipped save — same effect as `GE_UNLOCK_ALL` but at the file2 unlock-query site. Cached in a `static int`. | **live** (playtest aid) |
+| `GE_DEBUGMENU` | `src/boss.c:566` (`#ifdef PORT`) | Makes the L+R debug menu respond to live controller input (C-up+C-down open/close, stick + buttons read from pad 0) instead of the `#ifndef DEBUGMENU` path; unset reproduces that path exactly. Cached in a `static int`. | **live** (playtest aid) |
 | `GE_OPTIONSOVERLAY` | `port/src/optionsoverlay.c:231` | Force-enable the F10 port-layer options overlay (D184 / PR #10) regardless of ini. `atoi != 0`. | **live** |
 | `GE_D204` | `port/src/audio.c` (`audioSetNextBuffer`) | **Audio-health monitor (D204).** One line per 5 s of wall clock: `rt=` produced-audio/wall ratio (1.000 healthy; below 1 = the 30 Hz audio retrace is starving and the device is padding with silence), `q=` SDL queue depth / `queueLimit` (pinning at the limit with `drop=` climbing = overproduction, the "eventually no audio" state), `drop=` blocks discarded, `max=` largest block vs its `g_MaxFrameSize*4` allocation. **Deliberately cheap (~30 clock reads/s) — safe to leave on for a full playtest, unlike `GE_MIXERTRACE`.** The instrument of record for D202. | **live** |
 | `GE_D204_OLD` | `port/src/audio.c` (`d204OldMode`) | Restores pre-D204 behaviour (`osAiGetLength()` reports the whole SDL queue depth; `queueLimit` back to 8192) so before/after can be A/B'd in **one binary**, without build-to-build variance. Temporary — remove when D204 closes. | **live** (D204 A/B) |
@@ -39,19 +41,65 @@ Two classes:
 | `GE_MIXERTRACE` | `port/src/mixer.c`, `src/audi.c` (`amDmaCallback`), `src/libultra/audio/load.c` (`_decodeChunk`, `alLoadParam`) | Per-opcode mixer trace to `mixertrace.log` (DMEM addresses, ADPCM books, decoded frames, `[DMAREQ]`/`[DMAHIT]`/`[DMAMISS]`/`[BINDTABLE]`). **WARNING: unbuffered per-opcode `fprintf`, ~25 MB/min. It slows the process enough to starve the audio thread — M-63 measured "audio at 13 % of real time" that was entirely this probe's own artifact. NEVER use it for timing-sensitive measurement; use `GE_D204`.** Grep it, never read it whole. | **live** (D202) — timing-unsafe |
 | `GE_TEXPITCH` | `port/fast3d/gfx_pc.cpp:924` (`gfx_tex_pitch_fix`, cached) | `=0` disables the D183 defensive de-stride in `import_texture` (default on). RC2/RC3 texture-shear A/B knob. | **live** (RC3 not finished) |
 | `GE_TEXRAW` | `port/fast3d/gfx_pc.cpp:1079` | With `GE_TEXDUMP`, also dumps the raw pre-import source bytes (`texdump/rNNN_f…_s…_WxH.bin`) so a decode bug can be told from a source-data bug offline (D183). | **live** (RC3 not finished) |
+| `GE_TEXDUMP_ADDR` | `port/fast3d/gfx_pc.cpp` (`import_texture`, cached env check) | D75/M-197: with value `<hex>`, dumps the raw source bytes of **every** import from that exact address (bypassing the 400-dump cap) to `texdump/aNNNNN_WxH.bin` + a `GE_TEXA[…]` log line with fmt/siz/size/min/max/nonzero byte stats. Distinguished "never loaded" from "loaded zeros" for the Nintendo-logo texture buffer (root-caused to the D50 sidecar converter dropping embedded blobs). | **live** (D75) |
 | `GE_D219RAW` | `src/game/image.c` (`texReadUncompressed`/`texChannelsToPixels`, `#ifdef PORT`) | Diagnostic-only, print-only (no behavior change): logs the runtime texture decompressor's bitstream header (texnum/format/width/height/compmethod) for every non-zlib wide-pixel image, plus a dump of the first row of decoded texels exactly as stored in the pool (post-`PORT_PIXEL16`, i.e. byte-swapped for the 16-bit family) for RGBA16/RGB15/IA16. No texnum filter — lets any suspect texture be cross-referenced against the offline ROM census (`scratch/d219_census.txt`) without narrowing by hand. | **live** (D219, closed — kept for future runtime-decoder triage) |
 | `GE_WRAPFIX` | `port/fast3d/gfx_pc.cpp:3166` (`gfx_set_wrap_fix`) | RC3 test override for the `Video.WrapFix` D74/D167 wrap-block path (`atoi != 0` wins over the ini). | **live** (RC3 not finished) |
 | `GE_SAVELOG` | `src/game/file.c:46`, `src/game/file2.c:16` (`SAVELOG` macro), `src/boss.c:749`, `src/game/objective_status.c:297,343` | Traces the campaign save/unlock chain (objective completion → `end_of_mission_briefing` → `fileWriteSave` → EEPROM). Used to confirm D157. `g_savelogObjOnce` gates the per-criterion dump to the `bossReturnTitleStage` call. | **live** (strip once a few more level boundaries are playtested) |
 | `GE_D160` | `src/boss.c:744`, `src/game/bondview2.c:791`, `src/aicommands.def:10055,10181,10236,10242,10247` (all `#ifdef PORT`) | Dam exit-cutscene (D148/D160) diagnostic: trace points in `bossReturnTitleStage`, `bondviewSetCameraMode`, and AI cmds `EndLevel`/`exit_level`/`CameraLookAtBondFromPad`/`CameraSwitch`. **Investigation in progress** — user owes a `GE_D160=1` Dam run. | **live** |
+| `GE_D243` | `src/game/front.c` (`menu_init`, cached `s_d243`) | Per-menu-transition trace with a local per-tick frame counter (D243 stale-DL-burst screen identification). Counter is NOT numerically identical to the port's internal frame count — cross-reference by elapsed offset. | **live** (D243) |
+| `GE_D243CAM` | `src/game/bondview2.c` (`bondviewFrozenCameraTick`, three `CAMERAMODE_POSEND` branches) | Dumps eye/look-at positions (+theta/verta on the `gBondViewCutscene` branch, +dt/angle/pad on the orbit branch) per call. **Found M-143**: the `gBondViewCutscene` branch fires and its look-at (`field_3C4/8/C`) sweeps through a filter catch-up after the cutscene warp — the shake mechanism. | **live** (D243) |
+| `GE_D243M` | `src/game/bondview2.c` (`solo_char_load`, `bondviewRemovePlayerBody`, `playerTick`; cached `d243mEnabled`) + `src/game/objecthandler.c` (`drawjointlist`, both region variants) + `src/game/chr.c` (`chrTick`, `after_position_update:`) | M-151/M-154/M-159 probe for the Dam-abseil "frozen Bonds + shake": `D243M: CREATE/REMOVE` at both `bodyModel` sites; `D243M: tick` (idx/model/**propptr/chrptr**/cam modes/`prop->pos`/`field_488.pos`/`field_3B8`/`field_3C4-8-C`/**rp** = render_pos pointer, **never dereferenced** — M-154 fix 2: tick-time `render_pos` holds arbitrary stale slot contents until the first draw pass, so the pre-view root translation is logged by `chrdraw` only) while the model exists or POSEND/INTRO is active; `D243M: draw` per on-screen player render submission; `D243M: chrdraw` — M-154 per-frame model-draw census, one line per CHR render submission (Model* + raw root translation) while a scripted camera mode (POSEND/INTRO/SWIRL/FADESWIRL) is active; a second Bond instance = extra lines with *distinct* model pointers at the same frame (same model is drawn twice/frame — two passes — dedupe by (frame, model)); `D243M: onscreen` (M-159/M-162/M-163/M-166, `chr.c`) — one line per `chrTick` call while the probe is active: `vis=` `posIsOnScreen`'s result (M-159's frustum hypothesis, REFUTED by M-160) + the live `prop->pos` + `actiontype=`/`anim=` (M-160/M-164: which of `chrTick`'s branches fired, the attached-animation pointer) + `aidx=`/`animframe=` (M-166: the animation reverse-resolved to its `animation_table_ptrs1` index, GE_D193A's technique, + its current playback phase — tests whether the visible chr's animation *phase* at cutscene-entry, not just its identity, is what differs from N64) + `x2active=`/`x2raw=` (M-162/M-163, gated on `GE_D243X2`: whether the decisive save/restore experiment ran this tick, and the raw pre-restore position it overrode — the whole `prop->pos` vector as of M-163, not just Z). Silent during FPS play, silent on the `GE_D243X2` fields unless that env var is also set. Note: `field_3B8` x/z read at 10× world units in the smoke capture — not plain world position. | **live** (D243) |
+| `GE_D243X2` | `src/game/chr.c` (`chrTick`, gated additionally on `d243mProbeActive()`) | **Not a probe — a decisive behavioral experiment, off by default, NOT a fix.** M-162/M-163: saves `prop->pos` right before `chrTick`'s position-update dispatch (`chr.c:2541-2617`) runs, restores it at `after_position_update:` — before the render-matrix computation later in the same tick can see the cycled value (unlike M-161, which restored too late to have any effect). Tests whether `chrTick`'s own animation-position write (M-160/M-164) is what produces the Dam-abseil shake. M-162 was Z-only (confirmed the mechanism on that axis, but the visible glitch persisted because that capture's chr cycled on Y instead); M-163 widened it to the whole vector. **M-163's live result: NEGATIVE for the visible shake** — `prop->pos` genuinely went smooth (log-verified) but the shake was unchanged, because the camera's look-at filter reads a *different* variable (`field_488.pos`, see `GE_D243X3`) that this experiment never touches. Kept in the tree as a real, useful (if ultimately not the visible-symptom fix) data point — always pair with `GE_D243M=1` so the `x2active=`/`x2raw=` fields on `D243M: onscreen` show whether/what it overrode. Do not ship. | **live, test-only** (D243) |
+| `GE_D243X3` | `src/game/bondview2.c` (`playerTick`, the `field_488.pos` write site, gated on `g_CameraMode == CAMERAMODE_POSEND`) | **Not a probe — the experiment that actually confirmed the mechanism, off by default, NOT a fix.** M-167: skips the `field_488.pos.x/y/z` assignment (`bondview2.c:10495-10497`) entirely while POSEND is active, freezing it at whatever value it held the instant suppression engaged. `field_488.pos` — not `prop->pos` — is what the cutscene's leaky-integrator look-at filter (M-143, `field_3B8`/`field_3C4-8-C`) actually reads; it comes from `render_pos` (the model's animated-skeleton readback), an independent data path from `prop->pos`. **Live-confirmed positive: user — "yep camera shake is gone now."** Logs a companion `D243M: f488write frame=... idx=... x3active=... x3skip=... epoch=... f488pos=x,y,z` line (always-on when `GE_D243M=1`, independent of whether `GE_D243X3` itself is set) so the freeze is log-verifiable. **M-169: no longer freezes forever** — re-baselines (`x3skip=0`, write allowed through) exactly on the tick a legitimate shot-change teleport fires (`d243GetTeleportEpoch()`, bumped by `chrai.c`'s `AI_TRYTeleportingChrToPad` right after its real `setsuboffset()` call), addressing the M-168 postmortem's "camera looks the wrong way for later shots" incompleteness — untested live yet, next session's first move. **Superseded: D243 shipped its permanent fix (`4ccab22c`, M-170), which removed the X3 suppression block from `playerTick` — no live site remains.** Kept here as a tombstone; the generator flags it GONE. | **dead** (D243 closed — probe removed) |
+| `GE_D243X4` | `src/game/chr.c` (`chrTick`, the `render_pos` snapshot/restore, gated on `d243mProbeActive()`) | **Not a probe — the M-168 experiment applying X3's technique to the actual draw-path consumer, off by default, NOT a fix.** Snapshots `model->render_pos[]` after a 2-tick warm-up once POSEND engages, then holds it steady by copying the cached contents back over each subsequent tick's freshly-computed buffer — `subcalcmatrices()` always still runs first (never skipped; the first two attempts skipped it and crashed on a reused-pointer stale `-1` tombstone, see findings.md D243 M-168). Addresses Bond's own rendered-body duplication (the consumer X3 never touched). Crash-free, stable, but same forever-freeze incompleteness as X3 pre-M-169. **M-169: same teleport-epoch re-baseline as X3** — the warm-up counter now also resets (re-snapshots) whenever `d243GetTeleportEpoch()` changes, not only on the active/inactive edge. Untested live yet. Revert once a real root-cause fix replaces it; do not ship as-is. | **live, test-only** (D243) |
+| `GE_D243SWIRL` | `src/game/bondview2.c:10480` (`playerTick`, cached `d243SwirlTarget`) | D243 follow-up probe: `GE_D243SWIRL=<chrnum>` logs a per-tick line for that chr while the swirl/fade camera path is active (tick counter + state), to verify post-fix behavior of the swirl transition. Inert unless set to a non-negative chr number. | **live** (D243 verification) |
 | `GE_D193` | `src/game/frametiming.c` (`waitForNextFrame`, `#ifdef PORT`) | Per-wall-second line: `render=` rendered frames, `sim=` sim ticks delivered (Σ of the `deltaFrames`/`g_ClockTimer` fed downstream), `clamped=` frames whose catch-up hit `FRAMETIMING_PORT_MAX_CATCHUP`, `maxraw=` largest pre-clamp delta. Healthy steady state = `render=30 sim=60 clamped=0 maxraw=2` (measured M-80, all levels idle). Use to check whether the wall-clock timer under-advances under real AI load (D193). Cheap; safe for a full playtest. | **live** (D193) |
 | `GE_D193A` | `src/game/chr.c` (`chrTick` → `d193aSample`, plus `d193aMoved` in `chrUpdateAnim`; `#ifdef PORT`) | Per-wall-second per-ticked-chr locomotion telemetry (D193/D209): `chr=` chrnum, `act=` ACT_TYPE, `speed=` world-units travelled/s, `gtd=` g_GlobalTimerDelta, `tier=` `act_gopos.unk59` SPEED tier (0 walk / 1 run / 2 sprint; `-1` when not ACT_GOPOS), `gspd=` `act_gopos.speed` (**a turn rate, not a travel rate** — 0 means running straight), `typ=` PROP_TYPE (3=CHR, 6=VIEWER), `tick=`/`move=`/`frz=` chrTick entries vs `chrUpdateAnim` calls vs freeze-gated (move « tick = the chr is being visibility-culled out of its own locomotion; `move=0` at high `speed` = WAYMODE_MAGIC), `hid=` CHRFLAG_HIDDEN, then the root-motion scalars `scale` / `xlscale` / `animrate` / `playspeed` / `mspeed` (model->speed) / `endframe` / `anim` ptr / `aidx=` that pointer reverse-resolved to its `animation_table_ptrs1` index (40 walking, 41 sprinting, 42 running, 107 walking_unarmed — map via `src/game/initanitable.c`). `GE_D193A_CHR=<n>` restricts to one chrnum. **This probe found D209**: Cradle showed `tier=1` (RUN) with `aidx=40/107` (walk anims) on every sample. | **live** (D193/D209) |
 | `GE_D193B` | `src/game/model.c` (`sub_GAME_7F06D3F4`, `#ifdef PORT`) | Rate-limited (1/97) raw anim root-motion decode trace (D193): `joint=` / `flip=` / `base=` mtx channel index / `frame=` / `tmp=` decoded s16 translation triple from the anim bitstream / `angle=` / `anim` ptr / `bd=`+`bs=` the D32 u32 bitDescriptors/bitStream addresses / `njoints`. M-80 Facility: `base=0`, `angle=0` **always** (root-motion facing delta never non-zero — top lead), `tmp` ≈ (±small, ~1086 hip-height, ±small). Compare `tmp`/`angle` magnitudes against a clean N64 decomp build of the same anim+frame. | **live** (D193) |
 | `GE_D250` | `src/boss.c` (`bossMainloop`, wraps `lvlRender()`, `#ifdef PORT`) | Per-wall-second line: `[D250] lvlRender avg=Nus n=M` — average + count of `lvlRender()` (DL-building: culling/animation/scene traversal) calls that wall-second, isolated from `gfx_run()`'s software-RSP interpretation cost (already covered by the existing "frame rendered in Nus" line). Added M-120 to chase D250 (fps stuck ~45-50 on Dam, ruled resolution/MSAA/vsync/build-flags out already) — found `lvlRender` itself is cheap (~0.5-1.5ms avg), so it is NOT the missing ~10-15ms/frame either; the still-unexplained cost must be elsewhere in the per-retrace-message loop (scheduler/thread round-trip, audio, or something not yet isolated by a targeted timer). Cheap; safe for a full playtest. | **live** (D250) |
 | `GE_D172` | `port/fast3d/gfx_pc.cpp` (`gfx_sp_tri1` — SETCOMBINE dedup log + non-LOD multitex tri dump; `#ifdef PORT`) | Particle magenta/cyan colour (D172). Logs each distinct SETCOMBINE + active cycletype, and — for a 2-cycle tri that consumes TEXEL1 with `tex_lod=0` and a distinct 2nd tile — the tile fast3d *samples* for each texunit vs what the DL *configured*. **Found D172**: 40/40 particle tris configured tile 1 @ tmem 392 (fire) but sampled tile 0 (smoke) → `smoke*smoke`. FIXED (`gfx_lod_tile_offset` `return rdp.tex_lod ? 0 : i`). Probe kept inert. | **live** (D172 FIXED, probe kept) |
+| `GE_D157` | `port/fast3d/gfx_pc.cpp` (`gfx_sp_vertex` + `import_texture`; `#ifdef PORT`) | D219/D252's "rainbow particle" family — bullet-impact spark on Bunker1 door confirmed by screenshot to cycle magenta/green/cyan (M-157). Three sub-probes: original exact-color-match log (`g_BulletSparkColors[]` byte match → geometry_mode/LIGHTING + shaded RGB); **`D157T`** texture-identity-keyed vertex full-path log (tile 0 holds a loaded texture ≤16 KiB in frame window [90,240] → raw `cn[]`, post-shade RGBA, LIGHTING, geometry_mode, combine_mode, tile-0 tmem/fmt/siz/addr/size/line, uv; cap 400 + summary/200); **`D157I`** import census (small textures imported in the window, deduped per source address → addr/fmt/siz/size/tile/tmem). M-158: bug did NOT reproduce in 6 identical dev-box runs — probes left live to capture the full RGBA path on the next occurrence (user Steam Deck run with `GE_D157=1`). **M-201:** F12 opens a ~90-frame full-detail `D157TB` burst; continuous logging cut to a 2000-line baseline + 500 colour-match hits (the uncapped white match ran live play at 4–6 fps). | **TEMP** (D252 fixed M-201; remove after release) |
 | `GE_DVM` | `src/game/gunfire.c` (`gunUpdateAndFire` gate dump + `gunRenderFirstPersonGunModels` render dump; `#ifdef PORT`) | 1P weapon viewmodel (D215). `[DVM]` line: the `field_87F` show/hide gate terms + `Gun_hand_without_item` sub-terms + `copy_of_body_obj_header` RootNode/Switches/numRecords. `[DVMr]` line: `87F` + `cmds_emitted` = gfx commands the weapon `subdraw()` produced (healthy ≈ 150; the D215 bug showed **1**). Rate-limited ~1/s per hand. **Found + verified D215** (`renderdata.flags` read 0 → all weapon DL nodes gated off). Probe kept inert. | **live** (D215 FIXED, probe kept) |
 | `GE_DTEX` | `port/fast3d/gfx_pc.cpp:1001` | Per-`import_texture` param log (dims / line / size / lod / gen_mipmaps). Used to root-cause RC2 and D159. Kept as an inert diagnostic. | **live** (RC2/RC3 not finished) |
 | `GE_TEXDUMP` | `port/fast3d/gfx_pc.cpp:1020`, `port/fast3d/gfx_opengl.cpp:700` | PPM dump of every uploaded texture + a `fmt/siz/palfmt/palidx/pal[0..3]` line. Root-caused D161 (Depot ceiling). Kept as an inert diagnostic. | **live** (RC3 not finished) |
 | `GE_D116` | `port/fast3d/gfx_pc.cpp:1710,2362`, `src/game/textrelated.c:265,541` (cached `ge_d116`) | HUD/text "X-mirror" (D114/D116) vbo/uv trace. **D114/D116 CLOSED — NOT A BUG (M-33/D168): the captures were upside-down, not mirrored.** Probe is now dead scaffolding — strip on the next cleanup pass. | dead (D114/D116 closed) |
+| `GE_D288` | `port/fast3d/gfx_pc.cpp` (`gfx_sp_tri1`, right after the D233 trivial-reject guard; cached `ge_d288`) | M-152 diag for the Silo intro stray triangle: frame-gated to `num_dls` 550–755 (M-155), now **skips `any_behind_camera==1` triangles** (M-155 follow-up — the x/w divide is meaningless for w≤0; that subset was pure false-lead noise) and logs the render-mode word (`oml`) so a live capture can ID the culprit asset against level tables. Logs any triangle whose clip-space NDC bbox covers >50% of the screen or goes non-finite, with each vertex's `w`. Bare `-level_20` re-run: 1965 sane hits in the window, still zero for the target color RGB(83,62,44) — consistent with M-155's working theory that the bare boot's scripted camera never reaches the bug state; **headless probing is at its limit, live capture is next**. | **live** (D288) |
+| `GE_D245V` | `src/game/sky.c:962` (`skyPortRenderPoly`-adjacent, `#ifdef PORT`) | D245 water-seam diag: per-call min/max of the recomputed S/T texture-coordinate ranges for the water fan vertices (rate-limited), to check whether the seam tracks a tc-shift boundary. Inert unset. | **live** (D245 OPEN) |
+| `GE_D245_FIXEDSHIFT` | `src/game/sky.c:946` (`#ifdef PORT`) | D245 test override: pins the water tc shift `k` to the given integer (0..SKY_TC_MAX_SHIFT) instead of the computed per-vertex value, to A/B the allowShift=TRUE behavior. Off by default (unset = current behavior). | **live, test-only** (D245 OPEN) |
+| `GE_D252` | `port/fast3d/gfx_pc.cpp:733` (`import_texture`, cached `s_d252`) | D252 rainbow-particle diag: one-shot per (address,size) import log of the tile state (tmem/fmt/siz/addr/size/line) for small textures so a suspect particle tile can be checked against its source bytes by hand. Remove once D252 is resolved. | **live** (D252 OPEN — non-reproducible) |
+| `GE_D252POOL` | `src/game/image.c` (`texLoad`), `src/game/initmttex.c`, `port/src/gimgfixup.c` | **TEMP** (M-201): one line per new texture load (pool main/other, free bytes) + `POOL-FULL` events + stage pool range; `D252SYNC: N slots re-synced, M changed` per stage load (the D252 fix at work: M>0 from the 2nd stage on). Load-time only, no fps cost. | **TEMP** (D252 fixed; remove after release) |
+| `GE_D245_OLDVTX=1` / `GE_D245_OLDTEX=1` | `src/game/sky.c` (`skyPortRenderPoly`) / `port/fast3d/gfx_pc.cpp` (CI8 import + tri-path dims) | **A/B** (M-201): restore the pre-fix s16 sky/water vertex path / the pre-fix 32x43, 16-wide water texture geometry. | **TEMP** (D245 fixed; remove post-release) |
+| `GE_DYNTEXHASH_OFF=1` | `port/fast3d/gfx_pc.cpp` (`import_texture` cache key) | **A/B** (M-201, D341): disable the content-hashed cache key for dyn-pool textures (reverts to the stale address-only key). | **TEMP** (A/B switch) |
+| `GE_D207S` | `src/game/gunfire.c` (player shot-sound block, `#ifdef PORT`) | **TEMP** (M-201): one line per player shot-sound decision: `D207S t=<g_GlobalTimer> hand item rate -> H1|H2|SKIP` (SKIP = both per-hand sound handles still held). Read-only, uncapped, cheap; use instead of `GE_AUDIOTRACE` for live captures (that probe does file I/O on the audio path). | **TEMP** (D207/D241) |
+| `GE_D306C="f0 f1 [wmax]"` | `port/fast3d/gfx_pc.cpp` (after `zf_note_emit`) | **TEMP** (M-201): depth-state census of every emitted triangle in frames f0..f1 (GL depth mode, geometry_mode, other_mode_l, tile-0 texture, NDC centroid, z/w range, min w); optional `wmax` keeps near geometry only. Cap 60000 lines. | **TEMP** (D306 closed; remove post-release) |
+| `GE_INTROCAM=<n>` | `src/game/bondview_r.c` (`#ifdef PORT`, intro camera pick) | **TEMP/test-only**: force the level intro's first camera index (Dam truck shot = 5). The PRNG draw is still consumed. Logs `D306: intro camera index` when set (or with `GE_D306C`). | **TEMP** (useful repro tool) |
+| `GE_STARTWEAPON=<ITEM_IDS>` | `src/game/bondview_r.c` (`#ifdef PORT`, after the start-inventory setup) | **TEMP/test-only** (M-201, D303): adds the item + 400 rounds of its ammo and makes it the starting right-hand weapon (M16 = 13). Pair with `GE_INPUTSCRIPT` `ZHOLD`. | **TEMP** (useful repro tool) |
+| `GE_D235` | `src/boss.c` (per-stage `while (!done)` block, after `memaReset`; `#ifdef PORT`) | D235 evidence probe: logs how many GL-texture-cache entries the per-stage `videoResetTextureCache()` call purges at each level load. A cold boot into a level should log 0; a death/restart (or any transition from a level that uploaded textures) logs >0 — direct evidence of the stale-entry mechanism. The clear itself is **not** gated on this var (it's the fix, see below); the var only controls the log line. | **live** (D235) |
+| `GE_D235_OFF` | `src/boss.c` (same block) | **TEMP** A/B switch: skips the per-stage `videoResetTextureCache()`, i.e. reverts the D235 fix for one run. For comparing a restart with and without the fix. | **TEMP** (D235; remove when D235 closes) |
+| `GE_D235_RELOAD=<frames>` | `src/boss.c` (same block + `bossMainloop` retrace branch) | **TEMP** reload harness: once the title stage loads after the first level (e.g. after a scripted watch Abort), wait `<frames>` retraces, then re-enter that level via `bossSetLoadedStage()`, the front end's own mission-start call. A headless death/restart without the pointer-menu walk. Pair with `GE_INPUTSCRIPT="800:START;1200:A;1300:RIGHT;1400:A"` (abort) on `-level_XX`. | **TEMP** (D235; remove when D235 closes) |
+| `GE_D235_NEXT=<stage id>` | `src/boss.c` (with `GE_D235_RELOAD`) | **TEMP**: re-enter a *different* stage after the abort (level A → title → level B), used for D336 (Runway → Frigate). `GE_D85TEX=1` now also logs each stage's texture-pool size and address range (`src/game/initmttex.c`). | **TEMP** |
+| `GE_D320R="tick:action;..."` | `port/src/d320repro.c` (hooked in `src/game/lv.c` per-tick PORT block) | **TEMP** forced-repro harness keyed on `g_GlobalTimer`. Actions: `roster`, `jump=<chr>,list=<hexid>,off=<n>`, `bit=<hex>`, `trace=<chr>`, `rename=<chr>,<num>`, `seed=<hi>,<lo>` (D320); `explode=<type>,<dist>` (explosionCreate ahead of Bond) and `cheat=gl|rl|inv|<id>` (game cheat activation) for D252 headless explosion/debris captures. | **TEMP** (D320/D252) |
+| `GE_AIMLOG=1` (+ `GE_INPUTSCRIPT` tokens `MDX<n>` `MDY<n>` `RHOLD` `LHOLD` `RREL`) | `port/src/input.c` | D337 aim-model harness: scripted sustained mouse deltas (treated as a grabbed mouse) and aim holds, plus a per-poll line with aim state, active device, the game's drawn crosshair x, `crosshair_x/y_pos` and camera angles. Measures range, edge-scroll and jitter headlessly. | **live** |
+| `GE_PERFSTAT=1` | `port/fast3d/gfx_pc.cpp` (`gfx_run`/`gfx_end_frame`), `port/fast3d/gfx_opengl.cpp` (start/end_frame), `src/boss.c` (main loop) | #92/D339 perf probe: per-300-frame averages of render phases (pre / display-list / post / swap+pace), tris and draw batches per frame, game-thread busy time per scheduler message, and a GL_TIME_ELAPSED GPU timer (meaningful only when GPU-bound). | **live** |
+| `GE_D75V` | `port/fast3d/gfx_pc.cpp` (`gfx_sp_vertex`, end of the copy/transform loop; cached env check) | D75 (Nintendo logo) per-batch vertex probe: for each `G_VTX` batch in frames `lo..hi`, logs frame#, source pointer, n_vertices, original dest_index, raw ob[0..2] of the first vertex, min/max of the transformed x/y/z/w across the batch, and the MP translation row. Used to prove the transform is correct (M-195) and that every batch encodes v0=0 (slot-overwrite hypothesis). Value form `"lo-hi"` (e.g. `300-900` = the logo screen); unset = off. | **live** (D75) |
+| `GE_D75D` | `port/fast3d/gfx_pc.cpp` (`gfx_sp_vertex` G_VTX case + `gfx_sp_tri1` rejection/emit gates; cached env check) | D75 (Nintendo logo) per-frame draw-path probe (M-196): for frames `lo..hi`, logs one line/frame with the V/T token stream (`seq`), max triangle vertex index, cumulative vertices loaded, and per-triangle accounting — trivial-reject / backface-cull counts, how many tris reach GL, how many of those are on-screen (NDC bbox ⊂ [−1,1]²), invisible-flag count, vertex-color min/max, first oml word, depth z/w range + NaN count, texture-sampler presence (`utex` = GL shader, `cutex` = combiner), combine mode, prim/env color. Used to REFUTE the slot-overwrite hypothesis (DL is streamed, max index 15) and narrow the bug to a texture-modulate material rendering black. M-197 added logo-mode `lg_*` fields (sampled only on tris with the logo combine word — the frame-level `utex`/`cutex` are first-tri-wins and were the source of the "combiner claims 0" false anomaly): `lg_utex`/`lg_tex` + tile-0 descriptor + texture buffer address/id/size for the logo material. Value form `"lo-hi"` (logo window ≈ `244-320` on a bare front-end boot); unset = off. Companion one-shot `D75DCC:` log in `gfx_generate_cc` fires when `combine_mode==0x009ffe4f19ffe4f1` to decode the logo's combine slots. | **live** (D75) |
+
+| `GE_PDMOUSEAIM` | `port/src/input.c:487` (`pdMouseAimEnabled`) | Force on/off the PD-style mouse-aim model (D194 lineage); unset = default (on in N64 aim mode unless legacy GEPD aim is selected). | **live** |
+| `GE_QUITFRAME` | `port/src/video.c:966` | D344 harness clean self-quit: exits after frame `<n>` completes and swaps (replaces `timeout` kills; the host never exits under an in-flight frame). Cached. | **live** (harness) |
+| `GE_ROOMPOOL` | `port/src/video.c:371` (`portRoomPoolScale`) | Scales the port's room pool by a float factor — before/after captures, and a user opt-out if the larger pool ever causes trouble on a level. | **live** |
+| `GE_BINDPROBE` | `port/src/input.c:885` | One-shot dump of the resolved PC bindings after setup (D383 bind-capture verification). | **live** (diagnostic) |
+| `GE_BINDCAPTUREPROBE` (+ `GE_BINDCAPTUREACTION`) | `port/src/optionsoverlay.c:1000,1005` | D383 isolated host→menu smoke probe: when the overlay force-opens, injects a scripted bind-capture keypress (ESC/DEL/F2). Test data dir must be private — capture persists the key. | **live** (diagnostic) |
+| `GE_OPTIONSOVERLAY_SECTION` | `port/src/optionsoverlay.c:989` | Isolated screenshot/probe of a nested F10 page by row key (opens that header; never a menu mode). | **live** (diagnostic) |
+| `GE_OPTIONSOVERLAY_SELECTBACK` | `port/src/optionsoverlay.c:995` | Screenshot-only: pins the selection to the Back row when the overlay auto-opens, to check it against a normally selected setting on the same page. | **live** (diagnostic) |
+| `GE_OPTIONTREEPROBE` | `port/src/optionsoverlay.c:888` | D388: opt-in in-memory walk of the real F10 page tree; writes no settings, binds or profile bytes; restores UI state afterward. | **live** (diagnostic) |
+| `GE_OVPOINTERMAP` | `port/src/optionsoverlay.c:1726` | D391 pointer-map diagnostic: on LMB-down (and every 120 samples) logs SDL mouse coords vs GL drawable pixel coords + the hover row, to separate hit-band/scroll errors from coordinate-space mismatch. | **live** (diagnostic) |
+| `GE_FOOTERPROBE` | `port/src/optionsoverlay.c:2232` | One-shot log of the overlay footer/help-line metrics (x extents). | **live** (diagnostic) |
+| `GE_FRONTOPTIONS_SECTION` | `port/src/frontoptions.c:295` | Isolated headless screenshot of a nested front-end options page by key (changes navigation only; never edits profile or config values). | **live** (diagnostic) |
+| `GE_FRONTNAVLOG` | `port/src/frontoptions.c:430,573` | Logs each front-options navigation select (section/row/item number). | **live** (diagnostic) |
+| `GE_FRONTOPTS_WIDTHS` | `port/src/frontoptions.c:673` | D406b: one-shot label-metrics log for the options rows (layout diagnostics). | **live** (diagnostic) |
+| `GE_FRONTOPTIONS_AUTO` | `port/src/frontoptions.c:818` | D406 test hook: enters the options screen without a mouse click so headless runs (`GE_INPUTSCRIPT` D-pad stepping + `GE_FRONTNAVLOG`) can exercise it. Never active without the env. | **live** (diagnostic) |
+| `GE_WSPROBE` (+ `GE_WSPROBE_FRONT`, `GE_WSPROBE_RESET`, `GE_WSPROBE_F10FRONT`) | `port/src/watchsettings.c:616,568,512`, `port/src/optionsoverlay.c:1566` | D354 watch-settings probe family: `WSPROBE[=tick]` logs before/after the queued settings commit one tick apart; `_FRONT[=tick]` drives a headless front-end change scenario; `_RESET` prepares an options-reset after 120 front ticks and verifies persistence once the stage drains; `_F10FRONT` fires a one-shot F10→front poll after the file-select save becomes available (avoids the joyDisablePoll deadlock). | **live** (diagnostic) |
+| `GE_ZF` (+ `GE_ZFTOL`, `GE_ZFBOX`) | `port/fast3d/gfx_pc.cpp:1653-1657` | Z-fight grid probe: per tri emit, buckets the centroid cell and flags cells that fight ≥5 times (cap 600 hits); `ZFTOL`=tolerance, `ZFBOX="x0 y0 x1 y1"`=world-box filter. | **live** (diagnostic) |
 
 ## Dxx diagnostic probes — finding closed unless noted
 
@@ -83,6 +131,21 @@ Two classes:
 | `GE_D104` | `src/game/bg.c:654` (rate-limited, `d104c`) | D104 depth-clear trace | dead (D104 closed) |
 | `GE_D71LOG` | `port/fast3d/gfx_pc.cpp:645` | D71 fast3d trace | dead (D71 closed) |
 | `GE_D75` | `src/game/title.c` `sub_GAME_7F007F30` (capped 8) | D75 Bug 2 gun-barrel model probe: logs `chrModelInstance`/`gunModelInstance` ptr+obj+numMatrices, `render_pos`, `renderData.mtxlist`, `g_GfxMemPos`, `osVirtualToPhysical(render_pos)` | **LIVE** (D75 Bug 2 OPEN — see §F "D75 Bug 2 — RUNTIME PROBE") |
+| `GE_D305` | `src/snd.c:420` (`sndHandleEvent` desync branch, `#ifdef PORT`) | D305: logs the sound-preemption desync state when it is detected (after the NULL-guard fix made the crash itself impossible) — confirms whether `Game.AllUnlocked` correlates or was coincidental, and whether it recurs. Inert unset. | **live** (D305 monitoring) |
+| `GE_D309` | `src/game/chrai.c:810,3424`, `src/game/chraction.c:10139` (all `#ifdef PORT`) | D309 freeze probe: logs AI label-not-found restarts (`chrai.c`) and the run-to-bond persistent-list step-on path (`chraction.c`, capped 400 lines) — the diagnostics used to root-cause the elusive complete freeze (D309/D310). Inert unset. | **live** (D309/D310 fixed — kept for recurrence) |
+| `GE_D314` | `port/src/optionsoverlay.c:681` (cached `s_d314Enabled`) | D314 F10-flicker probe: logs the overlay's viGetY / visible-row count / scroll / selection each poll. Inert unset; strip candidate once D314 is triaged. | **live** (D314 pending triage) |
+| `GE_D318R` | `port/src/random.c:69,147` (`#ifdef PORT`) | PRNG golden probe (D284/D318): logs the first 4000 gameplay-PRNG draws with tick + caller return address, and every `randomSeed` set — verifies the bit-exact port of `random.s` and which call sites consume the stream. Inert unset. | **live** (D284 verification) |
+| `GE_RSEED` | `port/src/random.c:134` (`#ifdef PORT`) | Test-only boot-seed override: `GE_RSEED=<hex64>` pins `g_randomSeed` at first seed instead of the wall-clock-derived value — for determinism and N64-parity tests. Inert unset. | **live, test-only** |
+| `GE_RSEED_LV` | `port/src/d318watchdog.c:232` (`#ifdef PORT`) | One-shot level-start seed log: logs `g_randomSeed` at the first tick after level start (optionally armed for a specific tick via `<hex>@<tick>`) — ties a saved/loaded game's PRNG state to a level for D318-class repro. Inert unset. | **live** (D318 verification) |
+| `GE_D318T` | `port/src/d318watchdog.c:270` (`#ifdef PORT`) | D318 watchdog timeline probe: per-tick log of the Facility ai_22 softlock signature window (c78 list/offset/attack state, c67 health) while the watchdog watches. Inert unset. | **live** (D318 verification) |
+| `GE_D322` | `port/src/audio.c` (`audioSetNextBuffer`), `src/snd.c` (`sndD322PoolSummary`) | D322 pool-telemetry probe: one line per 5 s of wall clock with the three pool layers a long session can exhaust — `sfx=count/max` (8-voice SFX soft cap), `evtq=n/64` (event queue occupancy; full = silent post drops, M-71), `pv free/lame/alloc` (24 physical synth voices shared by SFX + music; `-1`s before sndInit), plus the D204 pipeline fields. Cheap (~30 reads/s), campaign-safe; read together with `GE_D204=1`. | **live** (D322 capture) |
+| `GE_D318W` | `port/src/d318watchdog.c:136` (`#ifdef PORT`) | **Not a probe — the D318 port-side watchdog itself, ON by default.** Detects the Facility ai_22 hold-pose softlock signature (a latent N64 race, see findings.md D318) for 600 consecutive ticks and re-seeds c78's attack via the game's own fresh-attack entry point. `GE_D318W=0` opts out; logs `D318W:` lines when it acts. **Permanent fix, not strip-candidate.** | **live** (D318 fix — permanent) |
+| `GE_D294` | `src/boss.c:498` (`#ifdef PORT`) | One line per stage reset: stage number + current MA malloc value (D294 pool investigation). | **live** (D294) |
+| `GE_D294BANK` | `src/game/bg.c:605` | D294: restarts the bank-window counter on stage change (pairs with the `GE_D104` windowing). | **live** (D294) |
+| `GE_D303` | `port/fast3d/gfx_pc.cpp:1717` | D303: logs up to 200 tri emits with per-vertex bbox + w-sum (degenerate-triangle hunt). | **live** (D303) |
+| `GE_D307` | `src/game/prop.c:709` | D307: load-time dump of every CCTV record's inputs + derived orientation, for word-for-word PC-vs-ROM comparison. | **live** (D307) |
+| `GE_D318B` (+ `GE_D318B_ALL`, `GE_D318B_CLK`) | `port/src/d318bprobe.c:91,97,210` | D318/D320 boundary probe suite (M-199): per-tick ground truth of the aim-hold/derail/anim-pin state machine for env-selected chrs (`"5,9"`, max 4); `_ALL` logs every ACT_ATTACK tick; `_CLK=N` locksteps N sim ticks per rendered frame. Read-only. **TEMP — remove when D318/D320 conclude.** | **TEMP** (D318/D320) |
+| `GE_D329` (+ `GE_D329LOG`) | `src/game/model.c:3516,3519` (`#ifdef PORT`) | **The D329 anim-pin fix gate — ON by default** (unlike the other probes here): re-derives a stale pinned frameb when the endframe no longer blocks it. `GE_D329=0` A/B-disables; `GE_D329LOG` logs each trigger (cap 2000). Cached. | **live** (D329 fix) |
 
 ## Notes
 

docs/dev/GEPD-INPUT-PLAN.md

@@ -0,0 +1,217 @@
+# GEPD-inspired input overhaul — FINAL PLAN (issues #89, #90)
+
+Status: **plan only** — no code changes yet. Companion to `port/src/input.c`
+(current state: D118/D165/D166/D194/D214/D223/D238 lineage).
+
+## 1. The reference (no longer vendored in the public repo)
+
+The GEPD Edition Mouse Injector source was vendored at `reference/mouse-injector/`
+and **removed from the public repo on 2026-09-19** (GPLv2 code + a prebuilt
+binary inside an MIT project; never compiled here). See
+`reference/mouse-injector/README.md` for provenance and how to re-vendor it
+locally if you need the original. The file that mattered was
+**`games/goldeneye.c`** (~380 lines, the whole GE aim model), plus `device.c`
+(raw mouse polling) and `maindll.h` (tickrate — the units every per-tick
+constant assumes). The model is quoted inline below and in the D194 findings;
+the ported result lives in `port/src/input.c`.
+
+### What the Mouse Injector does (GE)
+
+### What the Mouse Injector actually does (GE)
+
+| Aspect | GEPD implementation (`games/goldeneye.c`) |
+|---|---|
+| Mouse source | Raw driver deltas via ManyMouse (`device.c`), cursor locked by periodic `SetCursorPos`. No OS pointer accel, no deadzone. |
+| **Hipfire look** | **Direct camera write**: `camx += XPOS/10 * (SENS/40) * (fov/basefov)` degrees per tick; `camy` likewise, clamped ±90 (−20 in tank). Linear in px — this is why GEPD "just feels right". |
+| **Aim mode (R)** | Crosshair *position* accumulator `crosshairpos += XPOS/10 * SENS/292`, clamped to ±`CROSSHAIRLIMIT` (5.159° = screen edge). Gun/arm pose derived per-weapon from a 33-entry offset table. **View scrolls only past 72% of the way to the edge**: `aimx = (ratio−0.72) * 475 * timestep`, scaled by `fov/basefov`. |
+| FOV coupling | Every term carries `(fov/basefov)` — scopes automatically get finer control. `basefov` = min(60, override). |
+| Tank | Separate direct write to the tank x-rotation global (`0x80036484`), different scale (`360/TANKXROT * 2.5`); crosshair X locked to 0 when driving with tank equipped. |
+| Menus | Mouse moves the menu cursor directly (`menux/y += px/10*SENS*6`, clamped to screen rect); aim button acts as B (back) in menus; wheel = weapon cycle macro. |
+| Safety gates | Injection only when `camera==4||0 && menupage==11 && !dead && !watch && !pause && !mproundend`. |
+| Extras | Crouch *toggle* mode, dedicated reload key (ROM hack — not portable to us), FOV override + viewmodel repositioning (ROM hacks — we have the clean equivalents in `port/`), intro skip on FIRE+AIM. |
+
+### Already inherited (do not redo)
+
+- **D194 GEPD-mirror aim** (`aimGepdCompute()`): crosshair-position model,
+  ±5.159° clamp, 72% edge scroll at 475/s, fov scaling, per-tick overwrite of
+  `crosshair_x/y_pos` + `gun_azimuth_angle/turning`. This *is* GEPD's aim mode.
+- D223 mouse-wheel weapon cycling (A / A+Z synthesis) — mirrors
+  `GE_Controller()`'s weapon macro; D214 ini key binds; click-to-lock capture;
+  F10 options overlay with aim/turn sensitivity sliders; D194(b) dt-decoupled
+  look; menu pointer via direct `cursor_h/v_pos` writes (mirrors GEPD's
+  `menux/y` writes).
+
+### Remaining inheritances (this plan)
+
+GEPD's *hipfire* is a direct linear camera write — we still route hipfire
+through the N64 stick curve (#89). Also un-inherited: raw-input-by-default,
+crouch toggle, GEPD-style safety gates on our always-live look paths, and its
+sensitivity/FOV coupling discipline. That's WIs 1–3 + 6 below.
+
+### Reference split (GEPD vs PD port)
+
+Two references, two jobs (decided during #89/#90 triage):
+
+- **GEPD Mouse Injector** (was `reference/mouse-injector/`, removed from the
+  public repo 2026-09-19 — see its README stub) = *what the mouse does to the
+  camera*. The only reference with GE-specific knowledge (camera fields,
+  crosshair limits, tank case, safety gates). Primary for WI-1.
+- **PD PC port checkout** (standing reference, see AGENTS.md) = *how a PC game
+  presents and captures input*: cursor-lock behavior, raw input handling,
+  sensitivity units/scaling, and the shipped in-game options/keybind UI.
+  Primary for WI-2 conventions and WI-5's menu design. PD knows nothing about
+  GE — never use it for camera math.
+
+## 2. Issue #89 — "mouse movement is not uniform; slow motion barely registers"
+
+### Diagnosis (high confidence)
+
+The complaint is the **hipfire** path. Today hipfire converts mouse px into an
+*analog stick value* (`sx += (int)(hipEdx * hipSens * MOUSE_TURN_GAIN)`), and
+the game then runs that stick through its own N64-era natural-turn response —
+a **quadratic-ish curve with a soft floor** (D238: "saturates the game's
+quadratic natural-turn curve at ~13 px/poll"). Consequences, exactly as the
+reporter describes:
+
+1. Slow mouse motion → small stick values → squared-off tiny turn rates →
+   "almost unrecognised".
+2. Fast motion saturates the curve at full 315°/s — so the usable band is
+   narrow and the feel is non-uniform (bang-bang-ish).
+3. `(int)` truncation of the stick adds a quantized dead zone on top.
+
+GEPD/PD-PC never hit this because **they write the camera angles directly** —
+the stick curve is bypassed entirely, and sensitivity is linear in px with
+FOV scaling. We already do exactly that in aim mode (D194); hipfire is the one
+leftover N64-stick-shaped path.
+
+Secondary contributors worth folding in:
+
+- `Input.MouseRawInput` defaults to **0** — on X11/Wayland (the #90 reporter
+  is on Linux) OS pointer acceleration still shapes relative deltas; GEPD
+  reads the raw driver. Windows is largely unaffected.
+- Sensitivity is spread over 4 knobs (`MouseSensitivity`, `MouseTurnSpeed`,
+  `AimModeSens`, legacy `MouseAimSpeed`) — the reporter "tried adjusting
+  ge007.ini" and couldn't find the one that mattered for hipfire.
+
+### Work items
+
+**WI-1 (core fix): direct camera writes for hipfire look.**
+Mirror GEPD's hipfire branch in `input.c`.
+
+*Pre-flight:* skim the PD port's `port/src/input.c` mouse path first and match
+its conventions (sensitivity units, dt handling, focus-loss behavior) so the
+result feels like PD PC rather than a reinvention. GEPD supplies the GE camera
+math; PD supplies the UX shape.
+
+Implementation:
+
+- New path `hipDirectCompute()` next to `aimGepdCompute()`: convert this
+  poll's dt-scaled px to degrees using the *current* viewport
+  (deg/px = fovy/viewH, or hfov/viewW — reuse whatever D194 absolute aim used),
+  scale by `MouseTurnSpeed * MouseSensitivity`, and add straight to
+  `g_CurrentPlayer->vv_theta` / `vv_verta` (clamp ±90). Same confinement as
+  today: only when `idx==0`, cursor captured, in a running stage.
+- **GEPD's safety gates** must be ported over (aim mode got away without them
+  because it requires RMB held; hipfire is always live): check the decomp
+  equivalents of GEPD's `camera==4||0 && menupage==11 && !dead && !watch &&
+  !pause` before writing. `menupage` → `current_menu` (already have); the rest
+  are `player`/game globals — read-only, no logic change.
+- **Tank**: GEPD writes a separate tank-rotation global with its own scale and
+  locks crosshair X to 0 when driving with the tank equipped. Find the decomp
+  symbol for `0x80036484` (tank.c) and mirror it; if too fiddly, phase 2 —
+  tanks are rare in single-player.
+- Keyboard turn (arrows → stick) keeps the existing stick path; only mouse px
+  goes direct. Escape hatch: `Input.MouseDirectLook=1` default, `0` reverts to
+  the current stick path (kept as-is).
+- This makes hipfire and aim mode share one linear mental model: px → screen
+  angle, FOV-scaled, dt-normalized. Expect to then simplify or delete the
+  D166/D238 curve-tuning knobs that become inert (`MouseAimCurve`, `AimBand`,
+  legacy `MouseAimSpeed`) — *after* playtest, and keep the config keys as
+  no-op aliases so existing inis don't break.
+
+**WI-2: raw input by default.** Flip `Input.MouseRawInput` default to 1 (SDL
+hints already handled in `inputInit`). Verify Windows relative-mode deltas are
+unaffected; this mainly fixes Linux feel. Keep the escape hatch.
+
+**WI-3: one honest sensitivity number.** With WI-1, hipfire and aim both scale
+off px→degrees, so `MouseSensitivity` becomes genuinely master. Add it to the
+F10 overlay (see WI-5), document the knob hierarchy in the generated ini
+header comment, and re-calibrate defaults against GEPD's SENS≈40 ≈ 1:1
+screen-angle mapping (our current 38/50/100 trio should land close; measure,
+don't guess).
+
+**Verification:** `GE_INPUTLOG` linearity check — log px-in vs deg-out at slow
+and fast speeds (ratio must be constant); headless script harness for the
+stick-fallback path; manual playtest checklist (hipfire slow/fast, aim mode,
+scope zoom, tank, menu, death/cutscene safety gates). New finding `Dxxx` in
+`docs/dev/findings.md`, index row added.
+
+## 3. Issue #90 — in-game key bindings + "ini binds don't work" + sensitivity menu
+
+### Diagnosis candidates for "binds don't work properly" (repro before fixing)
+
+1. **Not a bug, GE design:** in-game, a fresh A edge *without* Z held is the
+   weapon-cycle-forward signal (D223 documents `weaponForwardOffset`). The
+   default Action bind includes E — so "pressing E changes weapon" is the
+   game's own behavior, and "Escape reloads/activates switches" is the default
+   Cancel=Escape → B button. The user's mental model (PC: E = interact)
+   collides with GE's A/B semantics. Address via documentation + possibly a
+   PC-idiomatic default set (product decision; GEPD itself uses Q=A, E=B).
+2. **Ini syntax footgun:** keys must be written as `Input.Bind.Action=E` (or
+   `Bind.Action=E` under `[Input]`). A bare `Action=E` under `[Input]` resolves
+   to `Input.Action`, which is unregistered and silently ignored. `configLoad`
+   also ignores unknown keys with no warning — add a log line for unrecognized
+   keys so users get feedback.
+3. **Key-name format:** binds use SDL scancode names (`"Left Ctrl"`, `"Up"`,
+   `"Space"`); nothing documents this in the ini. Add per-key comments in
+   `configSave` output and/or a `# valid names: ...` header.
+4. There may still be a real parse bug lurking (`strtok` on the seeded buffer,
+   constructor ordering vs `configLoad`) — **repro first**: write an ini with
+   `Input.Bind.Action=E`, launch, confirm via `GE_INPUTLOG` that E alone
+   produces A. Fix whatever actually breaks; don't fix hypotheticals.
+
+### Work items
+
+**WI-4: keybind audit + ini ergonomics.** Repro (above), fix real bugs, add
+unknown-key warnings, document scancode names in the saved ini. Cheap, do first
+— it unblocks #90's half regardless of the UI work.
+
+**WI-5: F10 overlay — bindings section + master sensitivity.**
+Model the UX on the PD port's shipped in-game options menu (standing reference
+checkout) where anything is player-facing. `optionsoverlay.c` already has
+row/hit-test/scroll infrastructure and owns all input while open; what's missing:
+
+- A new row kind `ROW_BIND`: label = action, value = first bound key name;
+  click → "press a key…" state that captures the *next* scancode (keyboard or
+  mouse button), writes it into `g_bindStr[a]` (replacing or appending —
+  decide: GEPD/PD use one primary + optional secondary; simplest v1 = replace
+  single key, keep multi-key only for ini power users), then `inputRebuildBinds()`
+  + persist via the existing config save path.
+- Expose `Input.MouseSensitivity` (master), and after WI-1 trim the panel to
+  master + per-mode fine-trim + invert Y (drop inert legacy rows).
+- Bind capture must swallow all input while armed (overlay already does this)
+  and handle ESC = cancel, Backspace/Delete = clear.
+
+**WI-6 (nice-to-have, from GEPD): crouch toggle.** GEPD's `CROUCHTOGGLE` state
+machine (`GE_Crouch`) is ~20 lines and pure port-side (stance flag write).
+Low priority; include only if WI-1..5 land cleanly.
+
+## 4. Suggested order
+
+1. **WI-4** (keybind repro/fix + ini docs) — small, unblocks #90 partially.
+2. **WI-1** (direct hipfire) + **WI-2** (raw input default) — the #89 fix;
+   playtest-heavy, needs the safety gates done right.
+3. **WI-5** (overlay binds + master sens) — completes #90.
+4. **WI-3** (sensitivity consolidation/cleanup) — after WI-1 defaults settle.
+5. **WI-6** (crouch toggle) — optional garnish.
+
+## 5. Constraints reminders
+
+- All work is `port/`-only: direct struct writes are the established D194
+  pattern (read/write live game state from the input poll, no logic change).
+  Any temptation to "fix" the natural-turn curve in `src/game` = rule-2 sign-off
+  territory — don't.
+- Keep every removed/renamed ini key registered as an alias so shipped inis
+  keep loading; log deprecations at startup.
+- Findings: new `Dxxx` entries for WI-1 (hipfire direct look), the #90 bind
+  repro outcome, and the overlay bind UI; update `findings-index.csv`.

docs/dev/GRAPHICS-BACKLOG.md

@@ -10,14 +10,15 @@ once the game is playable start-to-finish without crashes.
 |----|---------|----------------|
 | ~~**D114/D116**~~ | ~~HUD text + ammo digits render each glyph individually X-mirrored~~ | **CLOSED — NOT A BUG (M-33, §F D168).** The `GE_PCDUMP` PPM writer never reversed `glReadPixels` rows, so every capture was upside-down; "mirrored" was a misread of inverted asymmetric content. The game renders correctly on hardware (developer-confirmed). Writer fixed (`gfx_opengl.cpp`). "Every stage verified non-mirrored" was correct — there was no mirror. |
 | ~~**D74 wrap-block**~~ | ~~`gfx_pc.cpp:1546/1551` PORT block is dead code (guard `cms & G_TX_WRAP` always false; indexes per-texunit arrays with the vertex index → OOB if reached).~~ | **RESOLVED (M-30, RC3/D167).** The in-vertex-loop wrap block was reworked and hoisted to a per-texunit pre-wrap window (`gfx_pc.cpp` ~1574, now `cms`-correct and indexed by texunit not vertex), behind the `Video.WrapFix` knob (default OFF). No longer dead code or OOB. See §F "RC3 · D167". |
-| **D75** | ~~Nintendo logo mispositioned; gun-barrel Bond model absent~~; cast-roll character models — status unknown. (Rareware logo OK.) | **Shrunk (M-33, upright captures after D168).** The "overlaps D114 shared mirror" note is withdrawn. **Gun-barrel Bond RENDERS correctly** (walk + fire, upright) — the "absent" reports were the flipped capture. **Nintendo logo IS still broken** — renders as two overlapping white ellipsoids shifted left, no wordmark/geometry (a real `logoinst` model transform/geometry bug, not a flip). Cast roll not re-captured — recheck with `GE_PCDUMP="1400-2200:25"`. `findings.md` §F "D75 Bug 2 — M-33 UPDATE". |
+| **D392** | In the opening attract-mode Train demo, a soldier consistently looks more hunched on PC than in 1964/GEPD; his hand intersects his body at the wrong position. User comparison: `docs/img/animation-glitch-pc-port.png` and `docs/img/animation-glitch-1964gepd.png`. | **FIXED — user visually verified (D392).** Train's normal opening (`-level_25`) has a central firing guard (`chr=5`) whose torso/shoulder aim offsets reached `aimupback=-0.855`, `shoulder=-0.606,+0.868` radians by tick 100. `chrlvUpdateAimendbackShoulders` used N64 `((f32*)arg1)[12/13/16/17]` offsets into a firing table whose first member widens from a 4-byte to an 8-byte pointer union on PC; it read *other* floats and bent the torso/arms to wrong angles. `#ifdef PORT` now reads `max_up/max_down/free_arm_frac_up/free_arm_frac_down` by name; with the same short Train intro probe the torso offset stays 0, shoulders ~0.028/+0.014 at tick 100. User's original comparison: `docs/img/animation-glitch-pc-port.png` vs `docs/img/animation-glitch-1964gepd.png`. The user subsequently confirmed the soldier's pose looked fixed in-game; this session's image tool itself cannot display PNGs. No ramrom demo override needed; ordinary `-level_25` reproduces. |
+| **D75** | ~~Nintendo logo mispositioned; gun-barrel Bond model absent~~; cast-roll character models — status unknown. (Rareware logo OK.) | **Nintendo logo + GoldenEye logo + legal page FIXED (M-197, user-confirmed live 2026-09-21).** Root cause: the D50 sidecar converter (`tools_pc/d43_emit.py`) reserved + remapped the model's embedded texture-blob span but never copied the pixel bytes into the emitted RZ image → TEXEL0 sampled a zeroed buffer → the texture-modulate logo rendered black (M-195/M-196 had proven emission/transform/combiner all correct). Same latent bug hit `PgoldeneyelogoZ` + `PlegalpageZ`. Fix = tooling-only (blob raw-copy + round-trip check); ntsc sidecars regenerated; logo window now renders 23k px (7.59%) vs 0–33 pre-fix. Gun-barrel Bond renders correctly (M-33). Cast roll still unverified — recheck with `GE_PCDUMP="1400-2200:25"`. `findings.md` §F D75 (M-195/M-196/M-197 updates) + M-197 at file tail. |
 | **D76** | 2D disclaimer screen only partially drawn. | §F D76. |
 | ~~**D77**~~ | ~~No audible music on PC.~~ | **RESOLVED (M-104, PR #42) — in-level music now plays.** Root cause was a D6-class missing `return` in `sub_GAME_7F0C0BF0` (`mp_music.c`) that zeroed the seqp volume on the only in-level trigger path; menu/intro music bypassed it and was always fine. The remaining audio-*quality* gap (wrong-sounding instruments on some tracks — elevator named specifically — plus occasional garbling) is tracked as **D230**. §F D77/D230. |
 | ~~**D116 (HUD)**~~ | ~~proportional-font strings + ammo counter mirrored~~ | **CLOSED — NOT A BUG (M-33, §F D168).** Same capture-orientation artifact as D114. |
-| **D148** | Level-end cinematics don't play. Dam: hitting the exit trigger should show Bond rappelling down the dam (the bungee jump); instead it cuts straight to the mission-complete report. **Broader (M-49 full playthrough): cutscenes are buggy in many places across the game**, not just the Dam ending — the user reports frequent cutscene glitches (skipped, wrong camera, misplaced/hovering actors, timing). Treat D148/D160 as the tracking entry for the whole cutscene-reliability problem, not just Dam. | Scripted cutscene / cinematic-camera + Bond rappel anim. Found M-27 during the first full Dam→Facility playthrough. Progression is unaffected — the report and next briefing load fine. The widespread nature (M-49) points at a systemic cause: the propDef/`sizepropdef` stride desync (D122/D132 family) that misreads `CutsceneRecord` lookups, and/or D75 anim-model + D173 actor-position bugs showing up wherever a cutscene puts a character on screen, and/or the D155/D156/D193 timing family driving cutscene camera/anim pacing. **M-31 (§F D160):** static-traced the Dam end ailists (`ai_24`→`ai_17`, `camera_switch`→`CutsceneRecord` type-46 lookup). Diagnostic `GE_D160=1` shipped (`c95713f5`) — user runs Dam to the exit with it set; the trace pins whether the cutscene AI runs, and whether the propDef-index walk (D122/D132 family) hands `camera_switch` a bogus cutscene record. Leading hypothesis: propDef `sizepropdef` stride desync (medium confidence), not D75 anim-model. **M-87 user playtest:** Bond floating/hover cutscene glitch (D173) still present; new specific instance — **Bond spins in circles in some cutscenes**, named example the end-of-Cradle Trevelyan-falls cutscene. Likely the same actor-position/anim-root cause manifesting as bad rotation instead of bad height. |
+| **D148** | Level-end cinematics glitch. Dam: the Bond rappelling/bungee cutscene plays but the camera violently shakes and Bond's own model appears to duplicate/glitch. **Cutscenes are buggy in many places across the game** (D173 level-start floating, D292 death-sinking, Cradle spin) — treat D148/D243 as the tracking entry for the whole cutscene-reliability problem, not just Dam. | **2026-09-17 (D243 M-107 through M-168, ~18 session-passes): the mechanism is now understood in real depth, and the camera-shake half is fixed (diagnostically, live-confirmed).** Full history + code citations: `docs/dev/findings.md` `## D243` (long, multi-pass — look up via `findings-index.csv`, read the M-159 through M-168 paragraphs for the current understanding, don't linear-read). Short version for planning purposes: **(1) Root mechanism** — the cutscene teleports the *visible* Bond chr between shot positions correctly (`AI_TRYTeleportingChrToPad`, `chrai.c:4064`), but the actual rappel *animation* commands run on a separate, invisible driver chr (M-145) — the visible chr never gets told to play it, so it just keeps ticking whatever animation it already had equipped before the cutscene grabbed it. Every tick, that stale animation's own root motion gets read back into the chr's render position (`chrUpdateAnim`→`getsuboffset`, `model.c:684`), producing a small repeating cycle that reads as "shaking"/"glitching" on screen. Whether this exact mechanism is itself decomp-faithful (with the real PC/N64 divergence being *which* animation phase Bond happens to inherit at the cutscene boundary, not a code-path bug) is still an open question (M-165/M-166) — not yet answered. **(2) Two independent render paths, not one bug** — the camera's look-at filter reads `field_488.pos` (derived from `render_pos`, the model's animated-skeleton transform); the model's own on-screen draw reads `render_pos` directly (`objecthandler.c`'s `drawjointlist`). Fixing one does not fix the other; two live-test cycles were spent learning this the hard way (M-162/M-163 → M-167). **(3) Camera shake: FIXED at the mechanism level, live-confirmed by the user** ("camera shake is gone now") by freezing `field_488.pos` during the cutscene (`GE_D243X3`, `bondview2.c:10495`) — diagnostic-only, not shippable as-is (see next). **(4) Bond's own model duplication: mechanism-level fix attempted (`GE_D243X4`, `chr.c`, freezing `render_pos`'s contents) — stable after fixing two crashes (model-pointer-reuse hazard, see `porting-notes.md`'s two D11 updates), but freezing unconditionally also breaks the cutscene's *legitimate* per-shot camera/model repositioning** (the camera now looks the wrong direction for later shots; Bond still looks stuck) — not a fix yet. **Next steps for whoever picks this up** (none attempted yet): (a) re-baseline the `GE_D243X3`/`GE_D243X4` freeze on a position-delta threshold (a jump much larger than the observed intra-shot cycling amplitude, already characterized in the M-153/M-160 captures, is very likely a real shot-change teleport, not cycling) instead of freezing forever; or (b) hook the freeze/re-baseline directly to `AI_TRYTeleportingChrToPad` firing, the precise, unambiguous signal for "a legitimate reposition just happened"; (c) separately, find the actual N64-vs-PC divergence point per M-165/M-166 (log `aidx=`/`animframe=`, already wired into `D243M: onscreen`) to determine whether a real, permanent fix is even a `port/`-layer timing correction or needs a rule-2 sign-off for a genuine behavioral difference — this determines which of (a)/(b) is worth turning into a real fix vs. a stopgap. |
 | ~~**D149**~~ | ~~Front-end MISSION COMPLETE / mode-select 3D models (dossier, wallets) render as garbled full-screen geometry or not at all.~~ | **CLOSED — user-verified fixed (M-87 playtest).** No longer reproduces; presumably fixed as a side effect of other front-end/D75-family work since M-49. D75 family. §F D146. |
 | **D170** | Named-NPC "flee" scripted behavior looks wrong on PC: on Silo, Ourumov breaks into a full run the instant he alerts ("Ourumov: Kill him!") rather than the N64 walk/retreat; developer reports Trevelyan behaves the same way on Cradle. **M-49 full playthrough: escalated — Cradle (`-level_51`) is "bugged out completely" from Trevelyan's behavior; the final level's scripted progression breaks. Now folded into / superseded by §F D193 (NPC AI locomotion too slow).** | **Observed, not investigated** (M-34, from a Silo playtest capture; user bug report — no fix wanted yet). Could be a genuine ailist / `chrTick` divergence, OR the D155/D156 wall-clock `deltaFrames` locomotion-anim speed-up (a catch-up spike playing the walk cycle at 2–3×). **Verify first:** capture the same beat against N64 reference footage before assuming it diverges — Ourumov may be scripted to flee. If it's real, suspect the frametiming clamp (§F D155/D156) or the Cradle-family AI path (§F D123). |
-| **D171** | Silo missile-shaft: a large translucent grey triangle sweeps across the lower frame while panning down the shaft (~3 s of the capture). Looks like a stray poly / near-plane clip fan, same family as D106 (portal near-plane min>max). | **Observed, not investigated** (M-34, Silo capture). Cosmetic, intermittent, tied to camera angle in the open vertical shaft. |
+| **D171** | Silo missile-shaft: a large triangle sweeps across the frame while panning down the shaft. **Promoted to `docs/dev/findings.md` §F D288 (M-141)** with a user-reproduced, precisely-bounded, visually-documented repro (frames ~562-741 of a bare `-level_20` boot) — read that entry for the current state, not this row. | See D288. |
 | **D172** | Bullet-impact / blood particle spray renders magenta or cyan instead of dark red (visible on guards hit at close range on Silo). | **M-82: ROOT CAUSE FOUND + FIXED (PR #34).** `GE_D172` probe on a user Silo firefight: 40/40 particle tris configure tile 1 = RGBA16 fire @ tmem 392 but fast3d **samples tile 0 (smoke) for both texunits** — `gfx_lod_tile_offset()` returns 0 unconditionally (D107 blurry-ceiling fix; `video.c:225` disables `gfx_detail_textures_enabled`). `G_CC_INTERFERENCE` = `smoke*smoke` → magenta/cyan. Fix: `return rdp.tex_lod ? 0 : i` — only fold to base tile for real LOD/mip draws. (0xB9 + cycle-type were both false trails, ruled out earlier in M-82.) **Owed: in-game eyeball — blood should be dark red.** Detail: `D172-PARTICLE-COLOR-RESEARCH.md`. |
 | ~~**D178**~~ | ~~Objectives not listed correctly on the pre-mission briefing screen (the mission overview shown before starting a level).~~ | **CLOSED — user-verified fixed (M-87 playtest): "main menu text is good now."** No longer reproduces. M-36 triage below kept for reference. **M-36 triage: the objective lines are BLANK, not wrong.** `GE_STARTMENU=10` Dam briefing renders the header fine ("OHMSS / Agent: James Bond / Mission 1: Arkangelsk / Part i: Dam / PRIMARY OBJECTIVES:") then just the bullet "a." with no text and no b/c/d. → **D143/D151 blank-text family** (`langGet()` → NULL → silent blank), *not* a propDef walk / difficulty decode. **Family B** in `docs/dev/M-36-TRIAGE.md` — find which lang bank the front-end briefing flow fails to load. Re-confirm the exact shape in a *real* briefing (the `GE_STARTMENU` boot skips real save state). Close relatives: D151 (watch objective text blank — type-35/23 `text` slot u16→u32 fix, M-28; interactive re-verify was still pending), D143 (briefing/objective text blank via `langGet` NULL), D157 (objective difficulty byte offset — could make difficulty-gated objectives appear/disappear wrongly). The pre-start briefing is a *different surface* from the in-level watch, so D151's fix may not cover it. **Next:** ask user which level + what exactly shows vs expected; compare against `docs/dev/LEVEL-OBJECTIVES.md` (regenerated post-D157); if lines are blank → D143/D151 family (`langGet` NULL guard = silent blank), if wrong objectives listed → propDef type-23 record walk / difficulty decode. |
 | **D175** | In-game stutter / brief hang during normal play — observed opening a door on Runway (mission 3, `-level_35`) and also on Surface. No backtrace captured (gdb attach missed the window; it self-recovered). | **Observed, not investigated** (user QA report). Matches known transient-hang classes rather than looking new: D155 (post-slow-load catch-up spiral — clamped), D156 (anim NaN loop — guarded, prints one-shot stderr diag if it fires), D134 (SP/DP task-done event swallowed — fixed M-22, Runway was an original victim), D147/D152 (audio `s_imLock` steal = ~2 s hiccup). Door-open specifically = new room first visible → one-off texture-import/frame spike (likely benign). **Next:** reproduce under `tools_pc/debug.ps1` with the box idle; check console for the D156 stderr diag; if it recurs, attach gdb mid-hang and pattern-match `bt` (import_texture = benign slow frame; model.c:3131 spin = D156; pthread_mutex_lock on s_imLock = D147/D152). |
@@ -25,15 +26,19 @@ once the game is playable start-to-finish without crashes.
 | ~~**D233**~~ | ~~All levels (intermittent): near doors — especially doors you can't see through to the inside — the indoor level geometry vanishes and you can see straight through it into the room, while world objects (computer terminals, furniture) in that space still draw.~~ | **FIXED + VISUALLY VERIFIED (M-107 fix, M-108 verify).** `port/fast3d/gfx_pc.cpp` `gfx_sp_tri1` was trivial-rejecting visible triangles that had a behind-camera (`w<0`) vertex. Status cell here was stale at "not investigated" — corrected M-119. §F D233. |
 | ~~**D234**~~ | ~~Dam: the guard towers along the actual dam structure are invisible except for the first one.~~ | **FIXED + VISUALLY VERIFIED (M-108).** Same underlying mechanism as D233. Status cell here was stale at "not investigated" — corrected M-119. §F D234. |
 | **D235** | Wrong textures load after dying/restarting a level — clarified: not Facility-specific, seen on multiple levels; trigger is death/restart (level reload), not a general build regression. | **Observed, not investigated** (M-106, user QA report, clarified same session). This is a state-leak on level re-entry, not a one-level texture-decode bug — prime suspect is the texture pool / CI-cache (D217/D228 neighbourhood) not fully resetting between a level teardown and reload (stale arena base, a palette-cache entry keyed by a reused address, or a texpool index not rewound). Needs: confirm it does NOT repro on a fresh level boot (only after death/restart); which surfaces; a screenshot. Next: instrument `texInitPool`/the CI-cache clear path for what does/doesn't reset on reload vs cold boot. | 
-| **D236** | Surface 1: the 2D billboard trees that appear at the start of the level and around the map don't draw as discrete tree sprites — they render as a wall/sheet of tree texture instead of the proper 2D tree objects. | **Observed, not investigated** (M-106, user QA report). Billboards = camera-facing quads; "wall of tree texture" reads as either (a) the billboard orientation/quaternion missing so all quads emit coplanar in world space, or (b) a UV/texture-rect setup error mapping the whole sheet onto each quad. Distinct from D176(b)'s tree-*line* backdrop static (that's the painted perimeter wall; this is discrete 2D tree objects). First checks: `GE_PCDUMP` at the Surface 1 opening; inspect one tree billboard's emitted vertices + texture coords in fast3d; check whether the quads are camera-facing on N64 reference footage. |
+| **D236** | Surface 1: the 2D billboard trees that appear at the start of the level and around the map don't draw as discrete tree sprites — they render as a wall/sheet of tree texture instead of the proper 2D tree objects. | **FIXED (M-198, pass 26) — awaiting user play-test sign-off.** Root cause was a texture-BINDING bug, not decode/alpha/mip/geometry: GE binds the four Surface 1 treeline cards (`tex1198`-`tex1201`, RGBA5551 64x17 cut-outs) as `TEXTURETYPE_DETAIL`, where `texHandleType1` (`tex.c`) loads the *detail* texture at TMEM 0 and the real base image at TMEM `texGetSizeInBytes(detail,0)` on tiles 1+. fast3d's `gfx_lod_tile_offset` folded every `G_TL_LOD` draw to tile 0 (D107, correct for TEXTURETYPE_LOD/MIPMAP), so the port drew the shared detail texture -- `tex2465`, an opaque 32x32 IA8 noise tile, which is exactly the 'noise painter' D267/D276 measured at 1023/1024 texels opaque -- and never imported the cards at all. Fix: when a tile pair differs in both TMEM address and `fmt`/`siz` under `G_TL_LOD`, sample the base image (tile 1). `Video.DetailBaseTile`, default on. Live-verified on Surface 1 (discrete snow-covered pines) and Surface 2; Depot clean; bunker1 golden bit-identical with the fix on/off; `type=1` bindings exist only in sevx/depo/sevb/sev, so every other level is provably untouched. Full trail: `findings.md` D236 pass 26; generalised as `porting-notes.md` §D12.
 | **D249** | Streets and Egyptian (the two biggest/most-open levels) show culling problems on far-away geometry at *default* FOV — distant geometry drops/pops incorrectly. Also a QoL ask: improve LOD in general, but gate it behind a toggle so N64-accurate ("old school") LOD stays selectable. | **Observed, not investigated** (M-119, user QA report). Distinct from D222 (high-FOV near-edge culling) and D218 (fog/far-clip tint). Two candidate mechanisms: (a) portal/room-visibility cutting off too aggressively at range on large multi-room layouts (D233/D234 neighbourhood — check for a far-plane/depth-range sibling to D233's w<0 trivial-reject fix), or (b) GE's own LOD/detail-swap system not ported faithfully (mip-tile / simple-model substitution at distance, `gfx_lod_tile_offset` family). First checks: `GE_PCDUMP` a long sightline on Streets/Egyptian where geometry visibly pops; determine which of (a)/(b) is firing before designing the fix or the requested toggle. §F D249. | 
 | **D217** | 1P weapon viewmodel + character-model CI textures render with a wrong palette on many levels / multiple weapons — PP7 grip + hand render flat green on Facility & Depot, "weird or missing" gun textures elsewhere; Bond's watch face too. Surfaced by D215 (viewmodel now draws). Clean on Bunker1. | **Defect ① FIXED (M-90), pending human playtest eyeball — full detail in `findings.md` §H "D217 — M-90" and §F D217.** Root cause: weapon texpool arena bases land %8==4 on PC (memp bump drift from pointer bloat); `texAlignIndices` absolute 8-byte row padding then shifts every palette 4 bytes early while model-DL `G_LOADTLUT` reads the N64 offset (grip count=1 load lands on next tenant's header slot → `0x1A00` green; larger loads read a 2-entry zero pad — the M-86 tell). Fix: `texInitPool` rounds the base up to 8 under `#ifdef PORT` (no-op on N64); 21/21 sweep PASS. Two defects: ① **visible green = misaligned texpool arena** (fixed as above). ② **CI texture-cache collision** (no palette-content key) — proven, **fix landed on branch `fix/d217-model-texture-palette` `f6fc0399`** (palette FNV-1a hash in the CI cache key), owes a 21-level `verify.sh sweep`; does not fix ①. |
 | **D174** | "No blood effect" — user reports no visible blood when shooting guards / into surfaces. | **User QA report; likely D120, unverified.** Decals: the D120 `PointUsage[]` converter fix (M-30) was never interactively verified and only takes effect after a full sidecar regen (`d43 && d69 && d88 --regen`) — check whether the playtest build had regenerated sidecars before concluding the fix failed. Spray: D172 observed the particle spray *drawing* (wrong color, magenta/cyan) on Silo — if the user sees no spray either, that's new info (different weapon/range, or the D172 decode is worse than "wrong color"). First step: BUNKER1 firefight with regenerated sidecars; if decals still absent, instrument the `chr.c:3328` decal walk. |
 | **D173** | Third-person Bond model (the player-representing figure shown at level start) spawns too high — floats well above the ground "a lot of the time" while the actual player spawn is correct. Same symptom on the Cuba end credits: JB stands ~6 ft in the air above Natalya. | **Confirmed still present across the full 21-level playthrough (M-49).** **Observed, not investigated** (user QA report). D75 animated-model family but a *position* defect, not absence — M-33 confirmed the gun-barrel Bond renders fine upright. Suspects: (a) intro/credits puppet chr spawn position vs the model's base transform; (b) anim root-motion accumulation (`modelSetAnimFrame2WithChrStuff`, D156 area) offsetting the rendered joints above the body origin; (c) a `coord3d`/packed-float decode in the intro camera/model setup. "Player spawning is OK" localises it to the render-side model, not `g_CurrentPlayer` state. |
-| **D182** | SELECT FILE screen degrades after navigating away and back (main menu → file select, or backing out of file select and re-entering). On the fresh screen the 007 gun-barrel spiral / Bond silhouette renders behind the file boxes; after a round-trip **the Bond image stops drawing entirely** and the whole background gains the **comb / interlacing** artifact (horizontal line scramble). File boxes, text and the Copy/Erase icons still draw. | **Observed, screenshot committed** (M-35, user QA; `docs/img/bugs/d182-file-select-backout-20260902.png`). Two symptoms, likely linked: **(1)** background 3D image stops rendering after re-entry → a front-end model/DL whose `render_pos` / segment binding is only valid on first construction (D149 / D75 `constructor_menuXX` family — the dossier/wallet models have the same "renders once" behavior). **(2)** interlacing = **M-36 triage: Family A**, the `import_texture_*` `line` vs `full_image_line` shear (see D176(b) / `docs/dev/M-36-TRIAGE.md`) — **not** the D159 `texSwapAltRowBytes` path (that is a full PORT no-op). Open question: why only *after* a round-trip — first import may land `line == width`, re-import may not, or the tile descriptor is stale on re-entry. Repro: `GE_STARTMENU` to file-select, back out with ESC/B, re-enter; `GE_DTEX` on the spiral texture across both visits. Shares defect (2) with D176(b). |
+| **D182** | SELECT FILE screen degrades after navigating away and back (main menu → file select, or backing out of file select and re-entering). On the fresh screen the 007 gun-barrel spiral / Bond silhouette renders behind the file boxes; after a round-trip **the Bond image stops drawing entirely** and the whole background gains the **comb / interlacing** artifact (horizontal line scramble). File boxes, text and the Copy/Erase icons still draw. | **Observed, screenshot committed** (M-35, user QA; `docs/img/bugs/d182-file-select-backout-20260902.png`). Two symptoms, likely linked: **(1)** background 3D image stops rendering after re-entry → a front-end model/DL whose `render_pos` / segment binding is only valid on first construction (D149 / D75 `constructor_menuXX` family — the dossier/wallet models have the same "renders once" behavior). **(2)** interlacing = **M-36 triage: Family A**, the `import_texture_*` `line` vs `full_image_line` shear (see D176(b) / `docs/dev/M-36-TRIAGE.md`) — **not** the D159 `texSwapAltRowBytes` path (that is a full PORT no-op). Open question: why only *after* a round-trip — first import may land `line == width`, re-import may not, or the tile descriptor is stale on re-entry. Repro: `GE_STARTMENU` to file-select, back out with ESC/B, re-enter; `GE_DTEX` on the spiral texture across both visits. Shares defect (2) with D176(b). **2026-09-27 (D397):** user re-reported the comb/interlace on the file-select background AND on the **intro gun-barrel** — the latter is a *first-time* render, so the defect is persistent (not only after a round-trip), refuting the "stale descriptor on re-entry" hypothesis. D159 (odd-row swap) is no-op'd and D183 pitch shear is disproven for level_36 + a no-op for the 299×440×1 row-strip. Next step is a live `GE_PCDUMP` capture + ROM ground-truth decode of the gun-barrel RLE image to separate ground-truth dithered content from a GL sampling/texture-cache artifact. See findings.md D397. |
 | **D197** | Character face/head textures wrap wrong — the face texture repeats around the side of the head "and continues weird" instead of clamping to the front. Seen on **Silo** (M-49 playtest), intermittent ("sometimes"). Reads as **`G_TX_CLAMP` not honoured** for the character-skin tile in fast3d (→ `GL_REPEAT`, so the face UV region tiles around the skull), or wrong `shifts`/`shiftt` / LOD-tile selection on the head texture, or the D167 non-PoT wrap-period issue (head textures are often non-PoT) hitting skinned models. | **Observed, not investigated** (M-49, user bug report — needs a capture + which chr/level). Distinct from D176(b)/D182(2) (those are *bg wall* pitch shear). Related: RC3/D167 (`Video.WrapFix`, non-PoT wrap period) + the `texWriteTileLods` `shifts=shiftt=lod` note in findings §F "D176(b) → 4. candidate 2". First checks: does `gfx_pc.cpp` map N64 `cms/cmt` `G_TX_CLAMP` → `GL_CLAMP_TO_EDGE` for character DLs; is the head tile getting the base tile vs an LOD tile (D107); try `Video.WrapFix=1` on a repro. |
 | **D195** | Transparency / alpha-blended surfaces render wrong — reported on **Control** (Severnaya bunker basement — Natalya's console room; heavy on glass partitions and the translucent projected/holographic wall displays). Exact failure mode not yet pinned by the reporter (M-49 playtest): candidates are alpha-blended geometry drawing fully opaque, translucent panels drawing invisible, or draw-order/sort so translucent surfaces occlude what's behind. | **Observed, not investigated** (M-49, user bug report — needs a `GE_PCDUMP` capture + which surfaces). fast3d render-mode / combiner path. Same neighborhood as D161 (CI8 tile + `G_TT_NONE` → garbage), D172 (particle-sprite channel order), D176(b) (texture pitch shear) — but this is a *blend/alpha* defect, not a texture-decode one. Note D128 already touched Control's `specialportalarray` (portal struct stride) — check whether the affected surfaces are portal-adjacent. First checks: does `gfx_pc.cpp` honour `G_RM_*` XLU render modes + `G_AC_THRESHOLD`/`G_CC` alpha for these DLs; is `gDPSetRenderMode` `w1` being parsed (cf. findings §F "zbuf-clear w1 scribble"); is Z-write-vs-blend ordering right for XLU surfaces. Get the reporter to say: opaque-where-should-be-clear, invisible, or wrong edges? |
 | **D252** | Particle effects cycle through a rainbow palette — bullet-impact sparks and lingering smoke/explosion residue drift through the full hue wheel over time (~10 shots to sweep it) instead of holding their intended grey/orange palette (M-124, user playtest). Full mechanism + suspect in findings §F **D252**: colour comes from 15 distinct `IMAGE_SMOKE_N`×`IMAGE_FIRE_N` (RGBA16) pairs the particles age through; prime suspect is `import_texture_rgba16` deriving width/height from the tile line size (32×7 instead of 16×14 for the fire tiles), scrambling each stage's sprite into a different wrong hue. | **Documented only — not fixed for v0.2.0-pre** (user instruction). Confirm with one dumped fire tile vs raw `IMAGE_FIRE_N` bytes, then derive width/height from the LOADBLOCK dtx/dlh. D172/M-82 lineage. |
+| **D323** | Distant geometry on 15 levels samples driver-generated mips from the finest texture level; N64 samples Rare's hand-authored mip chain for explicit-LOD textures bound under `G_TL_LOD` (heaviest: Statue 378 binds, Aztec 806). Overwhelmingly CI8/IA8 — subtle fidelity gap, no reported artifact; the only RGBA5551 cut-outs are the D236 set (already handled). | **OPEN / parked** — mechanism confirmed, census in `tools_pc/bg_lod_audit.py`, fix path documented in findings §F **D323** (upload GL mip chains for TEXTLOD-on bindings). Not worth doing speculatively; revisit only if a playtest flags mushy distant detail. |
+| **D335a** | **RESOLVED 2026-09-23.** Gun-barrel backdrop (Bond's spotlight) leaked into the pillarbox bars while sliding in from off-canvas. Fix: `menu_jump_constructor_handler` emits a full-canvas `gDPSetScissor` right after the CENTER wrap (only when wider than 4:3), which fast3d squeezes to the pillarbox, so off-canvas draws clip at the 4:3 edge as the N64 RDP clips at the screen edge. Verified with a 16:9 barrel capture. |
+| **D335b** | Native widescreen: the F10 options overlay still stretches with the window (legible, pre-existing look). Pillarboxing it needs `optionsoverlay.c`'s click mapping (`gfx_get_ui_screen_rect`) remapped into the centred region in step. Polish, post-playtest. |
+| **#105** | Dam: uncovered water-reflection pixels show the procedural cyan fill instead of the stage sky (residual after the water/wall-reflection work; visible boundary between reflected geometry and sky in the settled Enhanced/Remaster capture). | Backlogged 2026-09-28 from [issue #105](https://github.com/jkdansereau/goldeneye-pc-port/issues/105); post-v0.4.0 graphics queue. Note: the issue's "D329" cross-ref is the issue author's own numbering — our D329 is the anim-pinning fix. |
 | **1P weapon viewmodel** | **RESOLVED (M-83, D215).** In-level first-person weapon models drew nothing. Root cause: `gunRenderFirstPersonGunModels` built its `ModelRenderData` via `*(ModelRenderData*)&D_80035CC0` — a reinterpret across two separately-declared adjacent globals that only lands right on the N64 linker + 4-byte pointers; on x86-64 `renderdata.flags` read 0, gating every weapon DL node off in `modelRenderNodeGundl`. All 3 ranked suspects in VIEWMODEL-RESEARCH.md were ruled out first by the `GE_DVM=1` probe. Fixed `#ifdef PORT` (explicit field init). `subdraw` 1→153 gfx cmds; owed one BUNKER1 eyeball. |
 
 ## Resolved (for reference)

docs/dev/LEVEL-PLAYTEST.md

@@ -47,7 +47,7 @@ Objective status: `src/game/objective_status.c`
 - Notes / defects:
 ```
 
-## 21 solo levels (mission order — numbers = `-level_XX`)
+## The 20 solo missions (+ ending sequence; mission order — numbers = `-level_XX`)
 
 | # | Level | -level | Briefing asset |
 |---|---|---|---|
@@ -71,7 +71,14 @@ Objective status: `src/game/objective_status.c`
 | 18 | Cradle | 41 | UbriefcradZ |
 | 19 | Aztec | 28 | UbriefaztZ |
 | 20 | Egypt | 32 | UbriefcrypZ |
-| 21 | Cuba | 54 | (post-Egypt unlock) |
+| — | *Ending sequence* ("Cuba") | 54 | not a playable mission — cast/credits stage (D129) |
 
-(Mission table: `front.c:433`. Cuba = `LEVELID_CUBA`, not in the standard
-folder list — unlocked after Egypt.)
+(Mission table: `front.c`, `mission_folder_setup_entries` — exactly 20
+playable missions; the game's own enum says it, `SP_LEVEL_MAX // 20` in
+`bondconstants.h`). "Cuba" (`-level_54`, `LEVELID_CUBA`) is **not** a
+selectable mission: after the final mission the front end jumps straight to
+it for the extended cast display + credits scroll
+(`front.c` `selected_stage = LEVELID_CUBA` → `do_extended_cast_display(TRUE)`;
+`bondviewRenderCredits`, D129). Older docs and sweep logs count it as a 21st
+"level" — the campaign is 20 missions; "21/21" sweep results mean 21 stage
+boots, of which 20 are missions.)

docs/dev/LEVEL-STATUS.md

@@ -1,4 +1,10 @@
-# LEVEL-STATUS — 21 solo-level load+render sweep (WS4)
+# LEVEL-STATUS — level load+render sweep (WS4) — 20 solo missions + ending sequence
+
+**Counting note:** the campaign is **20 playable missions** (`SP_LEVEL_MAX //
+20` in `bondconstants.h`; `mission_folder_setup_entries` in `front.c` has
+exactly 20 entries). The sweep's 21st boot target, "Cuba" (`-level_54`,
+`LEVELID_CUBA`), is the end-of-campaign cast/credits stage (D129), not a solo
+mission — so "21/21 PASS" below means *21 stage boots*, 20 of them missions.
 
 Method: bare `./build-pc/ge007.x86_64.exe -level_XX` (per-level `-m*` pools
 auto-injected, D121), `GE_PCDUMP="80-260:40"`, ~24 s watchdog then

docs/dev/M7-ALLUNLOCKED-PLAN.md

@@ -0,0 +1,45 @@
+# M7 — Reversible AllUnlocked: investigation and fix plan
+
+**v0.4.0 release decision (2026-09-28, user):** ship AllUnlocked as a
+**loudly-documented, EXPERIMENTAL, irreversible** option for this release rather
+than hiding/disabling it or landing a safe architecture. The toggle stays (default
+OFF); the in-game row is now labelled **"All unlocked (EXPERIMENTAL)"** with the ON
+value displayed as **"ON - UNSAFE"** in both the F10 overlay and the front PC
+Options screen, and the README Known-issues bullet already tells users to back up
+`data/ge007.eep` before enabling it. A proper fix (Candidate A port-only shadow or
+Candidate B non-mutating virtual query) remains the v0.5.0 work item.
+
+Status: **investigation, NO FIX APPROVED OR LANDED**. Root cause/repro: `docs/dev/findings.md` D387; original feature: D257, fresh-save repair: D281, old-CRC migration: D297. This plan supersedes the M7 "no-code proof" in `docs/dev/notes/MODERN-OPTIONS-PLAN.md`. Follow `AGENTS.md` rule 2 and `docs/dev-process.md` §7 before any `src/game` edit.
+
+## User-visible contract to settle
+
+Recommended: OFF (after restart, as presently documented) must display only genuinely earned mission progress/cheats; ON may *temporarily* expose every level, difficulty, 007 mode and cheat, without modifying durable progress. Achievements **earned while ON without an active cheat** should survive OFF, including difficulty inheritance, timed cheats and profile operations. Enabling/disabling must never silently delete existing genuine save records. Do not auto-repair an EEPROM already containing baked fake unlocks: the bytes lack provenance. The user has not explicitly signed off on a game-code alternative.
+
+## Confirmed facts (source + isolated data)
+
+- `port/src/libultra.c:geEepromRW` first migrates legacy CRCs on the five-slot block-4 read, then `geEepromPatchAllCheats` fills unlocked-cheat bits and every zero completion time with 0x3FF and re-CRCs a **temporary copy**. `fileValidateSaves` (`src/game/file2.c:527`) accepts that copy into `saves[]`. `fileWriteSave` (`file2.c:86`) writes the entire 96-byte live slot, not only the setting/progress that changed.
+- Private data under `AppData/Local/Temp/ge-m7-20260927/`: the older `data/ge007 copy.eep` has two genuine times and only cheat `04 00 00` in active folder 0 (slot 4). ON or OFF boot without a save yields identical EEPROM bytes after the same legacy CRC migration. ON plus existing `GE_WSPROBE_FRONT=600` performs an ordinary Music-volume save to slot 4: cheats become `ff ff 0f`, 58 empty times become 0x3FF, two real times remain. OFF + restart validates the written CRC and retains all fakes. Full repro/logs: D387. Current `data/ge007.ini` and `data/ge007.eep` were never opened for write; copies and SHA-256s in that private test directory.
+- `main.c` seeds debug unlock flags only at boot; an in-session OFF toggle leaves those RAM flags set until restart. `Game.AllUnlocked` defaults OFF; the relevant UI currently gives no explicit restart warning.
+- More than a write-mask problem: a successful mission runs `end_of_mission_briefing` (`src/game/file.c:41–68`) → `fileUnlockStageInFolderAtDifficulty` (`file2.c:828`) → `fileOverwriteSaveSlotWithNewSave` (`file2.c:794`), **rotating the profile to a free EEPROM slot** and freeing the old slot. `fileCheckSaveStageDifficultyTime` only updates if the real time beats the synthetic 0x3FF. Genuine lower-difficulty completions and long (>1023-second) runs can also have legitimate 0x3FF times; value alone is not provenance. Fake cheat bits cause `fileGetIsCheatUnlocked` to return true, so `end_of_mission_briefing` skips a genuinely earned timed-cheat award. A port-only sanitizer keyed by physical slot or by `time==0x3FF` is incorrect.
+- The current user EEPROM already has two nonfree slots with 60/60 max times and all cheat bits, consistent with an earlier write-back. Two separate older EEPROM backups exist in `data/`, but replacing or auto-merging them would risk later real progress; do not touch or auto-repair originals.
+
+## Architecture decision before code
+
+**Candidate A — port-only EEPROM shadow/merge:** keep authoritative *raw* progress per logical profile outside patched `saves[]` and translate every write to durable real-only state. Must cover direct settings writes, profile rotation, copy/delete/reset, earned times (including 0x3FF), timed cheat grants currently suppressed by fake reads, five-slot CRCs, and old-CRC migration. Physical-slot-only interception demonstrably fails. A read/write-only adapter may have insufficient information to recognize some genuine completions or cheat awards; prove a full event/provenance model in an isolated prototype before promising this path. No new sidecar that can be lost/desynced without a recovery design.
+
+**Candidate B — non-mutating virtual query:** retire `geEepromPatchAllCheats`, keep raw `saves[]` and EEPROM intact, and make the *opt-in* UI/gameplay availability queries report AllUnlocked without changing saved bits/times. Likely small PORT-gated touch points: `fileGetIsCheatUnlocked` (`src/game/file2.c:391`, existing D225 developer-only query override), `fileIsStageUnlockedAtDifficulty` (`file2.c:681`; cheat-enabled mission selection requires `STAGESTATUS_COMPLETED`, not merely the debug-flag `UNLOCKED`), and the raw earned-cheat check in `end_of_mission_briefing` (`src/game/file.c:41–68`), which must still record real cheat awards while virtual availability is ON. Audit every caller and the Rare/PD analogue first. A live-only toggle may require restoring debug flags safely; simplest contract is **takes effect on restart** and an explicit UI label. This alters opt-in `src/game` behavior and is **not** the ABI/layout exception: no implementation or implicit sign-off. If port-only is ruled out, prepare the exact file/line, reference, reason, scope and precedent required by `docs/dev-process.md` §7; obtain explicit user approval and document the grant in a new RULE-2-SIGNOFF finding before edits.
+
+**Release fallback:** if neither safe architecture is ready, do not present the current toggle as a reversible enhancement. Get an explicit release decision on hiding/disabling it vs shipping a loudly irreversible option; default-off alone does not protect users who toggle it on. Keep existing saves intact.
+
+## Test matrix (private files ONLY)
+
+1. Capture baseline hashes of copied current ini/EEPROM; separate valid older-progress, fully fresh zero EEPROM, already-contaminated, legacy-CRC, and mixed/multiple-folder fixtures. Do not copy old saves back into `data/`.
+2. No-write ON boot then OFF restart: raw five slots unchanged except *explicit* D297 migration; correct UI availability in both states.
+3. ON settings writes via `GE_WSPROBE_FRONT` (normal slot), in-stage F10 watch writes, and save-file chooser/reset: only real settings/intentional reset persist; CRC valid; no synthetic completions/cheats in raw file.
+4. Real mission completion at agent and higher difficulty (including inherited lower difficulty), fast timed-cheat award, slow/capped 0x3FF completion, and cheat-enabled mission selection. Verify actual new earned records after OFF restart, no artificial ones. Build an isolated gameplay harness if manual replay is impractical; do not use a settings-write test as a substitute for mission completion.
+5. Save-slot rotation (`fileOverwriteSaveSlotWithNewSave`), profile copy/delete, all four folders plus free slot, and reopen across process restart. Confirm all five CRCs via `GE_SAVELOG=1` and raw bit-level diff; compare copied baseline profile identity rather than just physical slot index.
+6. Default-OFF NTSC/PAL/JP builds and post-landing 21-level default-render comparison; config/EEPROM originals hash-verified **after** all tests. Human test of ON/OFF UI text and behavior. Existing contaminated saves need an explicit *separate*, opt-in recovery plan; never silently rewrite them.
+
+## Other wave item
+
+M5 remains under user review: FPS cap and MSAA are independently exposed already; dropping the two-setting Low-end preset is a separate decision, not a dependency of this M7 investigation.

docs/dev/OPTIONS-MENU-PLAN.md

@@ -1,6 +1,11 @@
 # In-game PC options menu — design + resume point
 
 Status: **config-system foundation landed (M-35); menu surface not built.**
+(Updated 2026-09-27: the menu surface *has* since been built and iterated
+as D346 -> D356; the current layout and per-section reset live in
+`docs/dev/D356-SETTINGS-REGROUP-PLAN.md` + `docs/dev/WATCH-SETTINGS-PLAN.md`
+and `docs/dev/findings.md` D346–D356. This doc remains the historical
+M3-scope record.)
 Pattern follows `docs/dev/AUDIO-PLAN.md` — a plan doc that a later session
 executes.
 
@@ -85,6 +90,12 @@ or are flagged "restart".
 
 ## 4. Alternative if an in-fiction surface is required later
 
+> **2026-09-27: route B chosen (v0.4.0 intake).** The entry point is on the
+> file select screen, not a main options menu (GE's front end has none). M1
+> landed as D343: an "Options" label that opens the F10 overlay, via one
+> Rule-2 `#ifdef PORT` draw hook. M2 (a GE-styled screen that reuses the
+> overlay's rows) follows.
+
 Route (B): a new front-end screen `constructor_menuXX_pcoptions` +
 `menuXX_pcoptions_navigation` in `front.c` under `#ifdef PORT`, reached from
 a new "PC OPTIONS" row on the main options menu. Each row calls a

docs/dev/QOL-INVENTORY.md

@@ -33,7 +33,7 @@ ScreenShakeIntensity. Debug: FrameDump, InputLog.
 | **DisplayFPS** _(DONE M-83, D213)_ | config `Video.DisplayFPS` | P | S | Top-right readout, config-only; ~0.5 s sample window. |
 | **Anisotropic filtering** _(DONE M-83, D212)_ | `Video.Anisotropy` (1–16, dflt 4) | P | S | fast3d already had the GL hook + a hardcoded 4×; M-83 exposed it as config. MipmapFilter / TextureFilter2D still not surfaced. |
 | Per-pad tuning: per-stick deadzones, stick scale, rumble scale, device index, swap sticks, C-button mapping | `input.c` padsCfg block | P | M | Medium. Matters for real-controller users; PD pattern is a config section per pad. **M-87 survey addendum:** PD does *incremental* hot-plug (`SDL_CONTROLLERDEVICEADDED/REMOVED` opens/closes individual pads into the first free slot, remembers `deviceIndex=-1` on removal so a replugged pad returns to its configured seat, `input.c:473-491`); GE's port instead does a full rescan-close-and-reopen-everything (`inputRescanPads()`, `input.c:983-1000`) and the game itself latches the controller mask at boot, so a pad added later merges into controller 0 for play. PD's incremental-with-remembered-seat approach is the natural implementation shape for this row and sidesteps the boot-latch merge — fold into the design when this row gets built, not a separate item. |
-| **Rumble → D224 (M-87). DEPRIORITIZED (M-87, user call) — gamepad-only, this release targets mouse/keyboard as primary.** GE's port fully no-ops the N64 Rumble Pak (`port/src/libultra.c:1220-1223` `osMotorInit/Start/Stop` all stubbed "no accessories on the PC") — GE genuinely has a rumble subsystem (`src/motor.c`, `src/joy.c`) that never reaches any output. **PD's PC port wires this straight through to real gamepad rumble**: `inputRumbleSupported()`/`inputRumble()` call `SDL_GameControllerRumble()` when the connected pad reports haptics, `Input.PadN.RumbleScale` config + an options-menu slider, `osMemSize`-style "pretend the accessory is there" pattern applied to a real one instead of faked. | P | M | Concrete PD-port precedent, straightforward port-layer wiring, ready whenever gamepad support is prioritized (no `src/` game-logic touch — GE's `motor.c` calls already exist, just need `osMotorStart/Stop` in `libultra.c` to route to a real `SDL_GameControllerRumble` call the way PD's do). |
+| **Rumble** _(DONE D401 — D224 / M-87, re-promoted 2026-09-27)_ | `port/src/input.c` + `port/src/libultra.c` + `port/src/optionsoverlay.c` | P | M | D401 implements the PD precedent per `docs/dev/RUMBLE-PLAN.md`: `inputRumbleSupported()`/`inputRumble()` → `SDL_GameControllerRumble()` when the pad reports haptics (SDL ≥ 2.0.18 `HasRumble`, else `SDL_JoystickIsHaptic` + known-type Windows fallback), per-pad haptics detection (`SDL_GameControllerHasRumble` / `SDL_JoystickIsHaptic` + known-type Windows fallback), a single global `Input.RumbleScale` (0..1, dflt 0.5) config + one `Rumble strength` slider row; `libultra.c` sets `CONT_CARD_ON` in `g_contStatus` for rumble-capable pads and routes `osPfsInit` → `PFS_ERR_DEVICE`, `osMotorInit/Start/Stop` → the haptics API — the two M-87 addendum blockers that kept `joyRumblePakInit` from arming. Zero `src/` edits. **Real-pad haptics confirmed working by the user (2026-09-28).** Plan item 3 landed the same day: the original four per-player rows were replaced (user decision) with one global `Rumble strength` slider in the F10 overlay + front options screen (`optionsoverlay.c`, shared `rows[]`), 0.05 detents, `kResetDefaults` 0.5; the four `Input.PlayerN.RumbleScale` ini keys were dropped (stale keys self-clean on the next save). A disabled-when-unsupported row state is deferred with the per-pad tuning row (needs a generic row-disabled mechanism). Unverified: `RumbleScale=0` silence check (trivial early-out). |
 | FakeGamepads / FirstGamepadNum / UseHIDAPI | `input.c` | P | S–M | Niche (local MP on PC); defer until MP is actually played. |
 | Window polish: DefaultFullscreen/Maximize, CenterWindow, AllowHiDpi, ExclusiveFullscreen | `video.c` vid* block | P | S | HiDpi + center are the useful ones on modern Windows. |
 | VSync adaptive (−1..10) | `Video.VSync` range | P | S | Note for FPS plan — GE's 0/1 toggle is fine until then. |

docs/dev/RUMBLE-PLAN.md

@@ -0,0 +1,264 @@
+# Rumble Pak → real gamepad haptics (port plan)
+
+Status: **IMPLEMENTED — finding D401 (2026-09-27/28).** Items 1+2+3 all
+landed (port layer only; zero `src/` edits), re-promoting the
+DEPRIORITIZED finding **D224** (M-87) to DONE. **Real-pad haptics confirmed
+working by the user (2026-09-28).** Menu shape: **one global `Rumble
+strength` slider** (`Input.RumbleScale`, user decision 2026-09-28 — the
+four per-player rows were dropped). Only the `RumbleScale=0` silence check
+remains unverified (trivial early-out path).
+
+Scope: wire the N64 Rumble Pak path (already present in `src/`) through to
+`SDL_GameControllerRumble()` on the PC. **Port-layer only — zero `src/game` or
+`src/` logic edits**, so rule 2 / ABI-exception do not apply.
+
+Reference: the PD PC port (local checkout `../pd_port`, `port/src/input.c`
++ `port/src/libultra.c`) implements the identical feature for the same Rare
+engine family. Copy its shape; the only friction is that **GE's `src/joy.c`
+calls the classic libultra names** (`osMotorInit/Start/Stop`, `osPfsInit/
+osPfsIsPlug`) while PD's engine renamed them (`osMotorProbe`,
+`__osMotorAccess`, `osPfsInitPak`). We translate names, not logic.
+
+---
+
+## Ground truth (current state)
+
+Game side — **already correct, untouched:**
+- `src/joy.c` full Rumble-Pak state machine: `joyRumblePakInit` (:178),
+  `joyRumblePakTick` (:298), `joyRumblePakStart`/`Stop`. Call sites (verified
+  2026-09-27 for D401) live in `gunfire.c:3284` (start) / `:3288` (stop),
+  `bondview2.c:9722` (start) / `:9726` (stop, incl. 2P second pad),
+  `lv.c:1688` (stop at level start), plus `sched.c:272` (stop on level
+  teardown).
+- `src/motor.c` is **EXCLUDED** from the PC build (N64 SI-DMA driver), replaced
+  by no-op stubs. CMakeLists.txt:525 documents this.
+
+Port side — **all no-oped today, in `port/src/libultra.c`:**
+- `osPfsInit`        (:1413) → `return PFS_ERR_NOPACK;`
+- `osPfsIsPlug`      (:1415) → `*pattern = 0; return 0;`
+- `osMotorInit`      (:1417) → `return -1;`
+- `osMotorStart`     (:1419) → `return -1;`
+- `osMotorStop`      (:1420) → `return -1;`
+- `g_contStatus[i].status = 0;` (:1102) — `CONT_CARD_ON` **never set**.
+
+Gamepad side — **exists, no change needed:**
+- `port/src/input.c` owns `static SDL_GameController *pads[MAX_PADS]`
+  (MAX_PADS = 4, aligned with `MAXCONTROLLERS`), open/close, hotplug,
+  `inputComputePad()`. This is the exact object `SDL_GameControllerRumble()`
+  needs.
+
+## The two upstream blockers (D224 M-87 addendum — MUST land together)
+
+`joyRumblePakInit` (src/joy.c:178) only drives the motor if BOTH pass:
+1. `g_ContStatus[index].status & CONT_CARD_ON`  → today always 0, so init
+   never even runs.
+2. `osPfsInit(...)` returns `PFS_ERR_ID_FATAL` **or** `PFS_ERR_DEVICE`  →
+   today returns `PFS_ERR_NOPACK`, so `osMotorInit` is never attempted.
+
+If the SDL wiring is done without (1)+(2), the state machine parks at
+`RUMBLEPAKINITSTATE_NOT_READY` forever and nothing rumbles despite "looking
+wired." Both fixes are in the same file we already touch, so no extra cost.
+
+---
+
+## Work items
+
+### 1. `port/src/input.c` — detection + API
+
+Add per-pad fields (GE uses flat statics, not PD's `padsCfg[]` array):
+```c
+static int   padRumbleOn[MAX_PADS];    // set where pads[i] is opened (line ~582)
+static float padRumbleScale[MAX_PADS] = { 0.5f, 0.5f, 0.5f, 0.5f };
+```
+On pad open (in the `SDL_GameControllerOpen` path, line ~575-589), mirror PD:
+```c
+#if SDL_VERSION_ATLEAST(2, 0, 18)
+    padRumbleOn[i] = SDL_GameControllerHasRumble(pads[i]);
+#else
+    padRumbleOn[i] = SDL_JoystickIsHaptic(SDL_GameControllerGetJoystick(pads[i]));
+    if (!padRumbleOn[i]) {
+        const SDL_GameControllerType t = SDL_GameControllerGetType(pads[i]);
+        padRumbleOn[i] = t && (t != SDL_CONTROLLER_TYPE_VIRTUAL);  // Win no-haptic fallback
+    }
+#endif
+```
+On pad close, `padRumbleOn[i] = 0;`. GE has no `inputCloseController`
+(PD-only) — the close sites are `inputDestroy()` and the close loop in
+`inputRescanPads()`, both of which zero it (`inputOpenPads` re-detects on
+open anyway).
+
+New public fns (declare in `port/include/input.h`, define in input.c):
+```c
+int  inputRumbleSupported(int idx);            // 0<=idx<MAX_PADS ? padRumbleOn[idx] : 0
+void inputRumble(int idx, float strength, float time);   // scaled SDL_GameControllerRumble
+float inputRumbleGetScale(int idx);
+void  inputRumbleSetScale(int idx, float v);
+```
+`inputRumble` body (from PD, verbatim logic):
+```c
+if (idx < 0 || idx >= MAX_PADS || !pads[idx]) return;
+if (padRumbleScale[idx] <= 0.f) return;
+if (padRumbleOn[idx]) {
+    strength *= padRumbleScale[idx];
+    if (strength <= 0.f) { strength = 0; time = 0; }
+    else { strength *= 65535.f; time *= 1000.f; }
+    SDL_GameControllerRumble(pads[idx], (Uint16)strength, (Uint16)strength, (Uint32)time);
+}
+```
+In init, add the two PS4/5 hints (PD input.c:696-697) so BT pads report
+haptics:
+```c
+SDL_SetHint(SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE, "1");
+SDL_SetHint(SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE, "1");
+```
+Register per-pad config (in the existing `configRegister*` block, ~line 2457+):
+```c
+char key[48];
+for (int c = 0; c < MAX_PADS; ++c) {
+    sprintf(key, "Input.Player%d.RumbleScale", c + 1);
+    configRegisterFloat(key, &padRumbleScale[c], 0.f, 1.f);
+}
+```
+Note: **`strFmt` is NOT available in `input.c`** (0 uses, no decl in
+`port/include`) — use a local `sprintf` buffer as above. `configRegisterFloat`
+is declared in `port/include/config.h` (already included by input.c:80); it's
+used elsewhere (video.c) so the symbol is already in the link set.
+
+### 2. `port/src/libultra.c` — rewire the shims
+
+`contSnapshotFromKeyboard` (:1096): set the status bit for connected,
+rumble-capable pads (need a per-channel capability check → call
+`inputRumbleSupported(i)`; it's declared in input.h so include it):
+```c
+g_contStatus[i].type   = connected ? CONT_TYPE_NORMAL : 0;
+g_contStatus[i].status = (connected && inputRumbleSupported(i)) ? CONT_CARD_ON : 0;
+```
+Replace the 5 accessory stubs (:1413-1420) with real routing (PD libultra.c:235-351):
+```c
+s32 osPfsInit(OSMesgQueue *q, OSPfs *pfs, int channel) {
+    (void)q;
+    // "pretend the Rumble Pak is present" when the real pad can rumble:
+    // returning PFS_ERR_DEVICE is what joyRumblePakInit (src/joy.c:186-190)
+    // needs to proceed to osMotorInit.
+    return inputRumbleSupported(channel) ? PFS_ERR_DEVICE : PFS_ERR_NOPACK;
+}
+s32 osPfsIsPlug(OSMesgQueue *q, u8 *pattern) {
+    (void)q;
+    if (pattern) {
+        *pattern = 0;
+        for (int i = 0; i < MAXCONTROLLERS; ++i)
+            if (inputRumbleSupported(i)) *pattern |= (u8)(1 << i);
+    }
+    return 0;
+}
+s32 osMotorInit(OSMesgQueue *mq, OSPfs *pfs, int channel) {
+    if (pfs && inputRumbleSupported(channel)) {
+        pfs->queue = mq;
+        pfs->channel = channel;
+        pfs->activebank = 0xff;   // PD's osMotorProbe stores this too
+        // NOTE: PFS_MOTOR_INITIALIZED is NOT defined in GE's headers, and
+        // joy.c never reads pfs->status — it only checks (osMotorInit()==0)
+        // to set RUMBLEPAKINITSTATE_READY (src/joy.c:190). Skip the status store.
+        return 0;
+    }
+    (void)mq; (void)channel;
+    return PFS_ERR_NOPACK;
+}
+s32 osMotorStart(OSPfs *pfs) {
+    if (!pfs) return PFS_ERR_NOPACK;
+    // N64 motor has no duration; the game's joyRumblePakTimer60 (joy.c) turns it
+    // off. Issue one generous window, PD-style ("hope the timer stops it"):
+    inputRumble(pfs->channel, 1.0f, 5.0f);
+    return 0;
+}
+s32 osMotorStop(OSPfs *pfs) {
+    if (!pfs) return PFS_ERR_NOPACK;
+    inputRumble(pfs->channel, 0.0f, 0.0f);   // zero-duration / zero-strength = stop
+    return 0;
+}
+```
+**JPN note (2026-09-27):** `_HW_VERSION_1` defines `MAXCONTROLLERS` as 6
+while `MAX_PADS` is 4 — the `MAXCONTROLLERS`-bounded loops above are safe
+because `inputRumbleSupported()` bounds-checks against `MAX_PADS` and reports
+unsupported (silent) for `i >= 4`. `osPfsIsPlug` has **no GE game-side call
+sites** — its rewiring is completeness/hygiene only; the load-bearing stubs
+are `osPfsInit`/`osMotor*`.
+
+Headers confirmed: `OSPfs` (`include/PR/os.h:282`) has `queue` + `channel`; the
+error macros `PFS_ERR_DEVICE` (:642) and `PFS_ERR_ID_FATAL` (:641) and
+`PFS_ERR_NOPACK` (:631) are all defined there. **`PFS_MOTOR_INITIALIZED` is NOT
+defined** anywhere in GE's headers and `joy.c` never reads `pfs->status`, so it
+is not needed. `input.h` is already included by libultra.c (line 50), so
+`inputRumbleSupported` is directly callable there.
+
+### 3. (DONE 2026-09-28) options-menu slider — single global
+
+Landed in `port/src/optionsoverlay.c` (not PD's `optionsmenu.c` — GE's F10
+overlay + front options screen share `rows[]`, walked by `frontoptions.c`
+via the `optionsRow*` accessors): ONE `ROW_SLIDER` row `Rumble strength`
+on `Input.RumbleScale` (0.05 detents, generic `CONFIG_OPT_FLOAT` display
+`%.2f`), in the INPUT section after the controller rows, plus a
+`kResetDefaults` entry (0.5, the `gRumbleScale` C initializer) so INPUT's
+"Reset to defaults" covers it.
+
+**Decision (user, 2026-09-28):** the original four-per-player-row design
+(`Rumble (Player 1..4)` on `Input.Player%d.RumbleScale`) was coded and
+reviewed, then replaced with the single global row **before its first
+compile**: the scale applies to every rumble-capable pad, and the four
+`Input.PlayerN.RumbleScale` ini keys are dropped — stale keys in an
+existing ini log four harmless `unknown key` `LOG_NOTE` lines at config
+load and self-clean on the next `configSave` (which rewrites the whole
+file with the registered keys). Per-player rumble tuning stays a G-class
+stretch goal (QOL-INVENTORY) — and a per-pad override-on-top-of-global
+design would be a no-op for everyone anyway, because `configSave`
+rewrites all registered keys and the "user explicitly set this?" signal
+is burned as soon as any key exists at the 0.5 default. The
+row-disabled-when-unsupported state is deferred with the per-pad tuning
+row (the overlay has no generic row-disabled mechanism); the row is inert
+(no-op) on non-rumble setups.
+
+**Original plan (for reference):** PD wires the per-pad scale into the
+options menu (`optionsmenu.c:533-540`): `inputRumbleGetScale(player)`,
+`inputRumbleSetScale(player, v/10)`, disabled when
+`!inputRumbleSupported(player)`. In GE this maps onto
+`port/src/optionsoverlay.c` / the per-pad tuning row (QOL-INVENTORY.md).
+Config file value alone is enough for the feature; the UI is the polish.
+
+---
+
+## Verification ritual (AGENTS.md)
+
+- [x] `./build-pc.sh ntsc-final` compiles clean (2026-09-27). New
+      `inputRumble*` defined once in input.c, declared in input.h; no new
+      undefined/duplicate symbols (full `/linkcheck` sweep pending at D401
+      close).
+- [x] `CONT_CARD_ON` + `PFS_ERR_DEVICE` land (the two-blocker addendum);
+      the state machine's READY path is provable by code read — the runtime
+      proof is folded into the real-pad test below.
+- [x] **By-hand, real pad:** user confirmed the rumble works on a real
+      controller (2026-09-28) — fire a weapon (`gunfire.c:3284` recoil),
+      explosion rumble, 2P second pad (`bondview2.c:9722/9726`). Non-rumble
+      pad and mouse/keyboard-only stay silent by construction (`pads[idx]`
+      NULL / `padRumbleOn` 0 ⇒ `inputRumble` no-op).
+- [ ] `Input.RumbleScale=0` fully silences (unverified — the trivial
+      `gRumbleScale <= 0` early-out in `inputRumble`); max value loud
+      (confirmed implicitly by the working playtest at scale 0.5).
+
+## Finding log
+
+Done (2026-09-27): **D401** added to `docs/dev/findings.md` (§F index +
+full entry) documenting the D224 implementation + the two-blocker
+resolution; the `QOL-INVENTORY.md` M-87/D224 row re-promoted
+DEPRIORITIZED → DONE (D401); `docs/dev/findings-index.csv` regenerated.
+
+---
+
+## Effort
+
+- Items 1+2: **~1–2 h** coding (mostly a rename + copy from PD) + build/linkcheck.
+- Hands-on pad testing: **~30 min–1 h** (the only genuinely open-ended part —
+  feels-right tuning).
+- Item 3 (UI slider): **~1 h**, landed 2026-09-28 as the single global
+  `Rumble strength` row.
+
+**Total for working core: half a day max, <2 h of pure code.**

docs/dev/V0.4.0-PLAN.md

@@ -0,0 +1,515 @@
+# v0.4.0 Plan — local working document (NOT pushed; update as items move)
+
+**2026-09-27 user release decision:** defer M7 / AllUnlocked save-safety work
+for v0.4.0 (D387); do not ask for a live-save test or treat the feature as
+safe. Before shipping, hide/disable the unsafe toggle or explicitly agree
+on a release limitation — default OFF alone does not prevent a user from
+turning it ON. The user will do a full campaign playtest *instead of* the
+21-level automated sweep; record the campaign result as the release gate,
+not as a sweep PASS. **Playtest interruption D393/D394:** physical-pad
+A use / X reload / Y weapon cycle was user-tested. After the user supplied
+the StrategyWiki Xbox 1.1 Jinx mapping, D394 moved crouch to either stick
+click, LB to aim, B to a port-side owned-gadget cycle, and retired LB/RB
+weapon cycling. Build linked; user physically confirmed the new button roles work, including
+stick-click crouch, LB aim, RB no weapon cycling and B gadget cycling (the
+N64 port has no separate gadget HUD icon). **D395:** both controller-accessible
+binding menus now refuse pad-initiated keyboard/mouse capture and allow B to
+cancel an active modal, pending pad-only retest; this is not gamepad rebinding.
+**D396:** F10 B now backs/closes, A selects/toggles without changing sliders;
+left/right adjusts sliders. NTSC linked; physical pad retest owed. Inspect B's item category/order during campaign play if multiple mission
+items are owned: the current ID-range filter includes some mission objects.
+RB's remastered-graphics toggle cannot be replicated with N64 assets, and
+Back remains the PC options shortcut.
+
+Created 2026-09-21 from a fresh triage of `findings-index.csv`,
+`GRAPHICS-BACKLOG.md`, `docs/BACKLOG.md`, `ROADMAP-1.0.md` (M-139 phase order),
+`QOL-INVENTORY.md`, and the 2026-09-20 HANDOFF.
+
+**Release goal (user-set):** fix everything that still makes the port not 1:1
+with the N64 original; *then* improvements outside the OG game, plus stability.
+Sequencing follows M-139's R → Q → F order, split into four phases below.
+
+## Baseline
+
+- **v0.3.0 is shipped** (tag on origin at `4827bc86`); `main` is 7 docs-only
+  commits ahead. Branch `release/v0.4.0` off `main` when Phase 1 starts.
+- All 20 solo missions (plus the ending-credits sequence) load/render/crash-free; campaign completable end-to-end
+  (Agent, playtested). Steady 60 fps. Audio done. Saves done.
+- Known-issue list = README "Known issues" section (D303, D245, D308/
+  D306, D307, D311, D318 disclosure, widescreen-stretch, D249,
+  D240/D241, D257/D259/D281 AllUnlocked caveat). ~~D252~~ retired (M-188),
+  ~~D75~~ fixed (M-197, user-confirmed), ~~D236~~ fixed (M-198, pass 26 —
+  awaiting play-test sign-off).
+
+## Triage of every open item (as of this triage)
+
+### Bucket A — Fidelity (port diverges from N64 behavior/appearance/sound)
+
+| ID | Item | State / notes |
+|----|------|---------------|
+| D320 | 17 aim-hold AI lists in 8 levels carry the as-authored D318 softlock race; Facility `ai_19`, Control `ai_9`, Depot `ai_12` high/med-high | Static sweep done; **live probe-verification owed** (GE_D318T-style timeline on the 3 lists). If one freezes: generalize `d318watchdog.c` (parameterize list/offset/chr/entityid), not per-list copies. N64 softlocks permanently — watchdog stays a port-side recovery, disclosed like D318. |
+| D252 | Rainbow particles still intermittent on both platforms after the vertex-buffer fix | Second cause unrooted; prime suspect `import_texture_rgba16` fire-tile width/height from tile line size (32×7 vs 16×14). README known issue. |
+| D245 | Water seam between two patterns, moves with view (REOPENED) | M-142 probe: tc-shift k flips during ordinary rotation; opt-in `GE_D245_FIXEDSHIFT` candidate build-verified, needs A/B vs N64 reference before making it default. |
+| D303 | Wrong extra long muzzle flash (M16 + others) | **Investigated — pipeline + data ruled out.** Flash path (`gunUpdateAndFire` → `rwmtx[1]/[2]`, `dorottex` DLPRIMARY arms) is byte-identical game code; M16's `MuzzleFlashExtension`=6.0 is the legitimate max stat; Gm16Z flash-node data byte-faithful through d43. Headless runs can't fire weapons (guards don't shoot an idle player), so a TEMP `GE_D303=1` probe in `gfx_pc.cpp` logs every very-tall-thin emitted triangle with full RDP state — **blocked on a live firing capture** (playtest brief item 17). |
+| D306/D308 | Z-fighting: Dam intro/truck wheels + general/broader instances | **Investigated — real fighting confirmed, port-vs-faithful open.** Depth precision is equivalent to N64 (24-bit both sides; GE's RSP writes full 16.16 post-transform coords, not s16), so level-authored coincident geometry is the prime suspect and likely fights on N64 too. TEMP `GE_ZF=1` flicker probe in `gfx_pc.cpp` (recurrence-filtered; `GE_ZFBOX` region filter) shows sustained oscillation (counts ~1000) in the Dam-intro truck region. Closing it as faithful needs an N64 reference of the same spot; a PC-only mitigation (float depth) would diverge from N64 and needs a rule-2-style decision. |
+| D307 | In-level security camera props face backwards on some levels (Bunker) | **Investigated 2026-09-21 — no port-side bug found.** Full orientation path traced (`setupCctv` → per-frame `RotY(unkC8)×unk84`); every input verified N64-faithful against the ROM (PcctvZ switch data, boundpads incl. the legitimate load-time room-scale ×1.8542, record config words); all math helpers are byte-identical `src/game` code. Remaining suspect if it genuinely differs from N64: fast3d handling of the non-orthonormal lens matrix. **Blocked on user repro detail** (which camera/level + screenshot + ideally N64 compare). `GE_D307=1` diagnostic kept in-tree. |
+| D236 | Surface 1 billboard trees render as a solid wall of texture | **FIXED (M-198, pass 26, `425237f9`):** root cause was a texture-BINDING bug — `TEXTURETYPE_DETAIL` cards drawn from the detail tile (opaque IA8 noise) instead of the base image; `gfx_lod_tile_offset` now samples tile 1 when the pair differs (`Video.DetailBaseTile`, default on). Live-verified Surface 1/2 + Depot; other levels provably untouched. Awaiting user play-test sign-off; probes stripped (`0503d335`). |
+| D235 | Wrong textures after death/restart (level reload), multiple levels | **Headless verification 2026-09-23 (`2a6bc2bb`)**: fix clean on reload; bug NOT reproduced even with the fix off. Needs the real die → mission select → restart A/B (`GE_D235_OFF=1`). |
+| D288 | Silo intro: huge flat untextured triangle sweeps the frame (frames ~562–741 of bare `-level_20`) | **Does NOT reproduce on the current build (2026-09-23, `30cf76b8`)**; D271 A/B ruled out as the fixer. Close if the Silo playtest does not see it. |
+| D294 | Statue: CCCP monument ground renders solid black, self-recovers in 10–30 s | **FIXED pending user playtest** (2026-09-22). Note: its "3× pool corrupts anim" symptom was D336, so the 2× cap can be revisited. |
+| D291 | Dam: texture glitches when the truck drives past | Not investigated. |
+| D249 | Distant geometry drops out on Streets/Egyptian at default FOV | M-142 ruled out far-clip + LOD-multiplier; narrowed to portal/room-visibility BFS. **First check overlap with D271's portal-culling fix** (branch state, see Phase 0). Needs live screenshot+location. |
+| D195 | Control: transparency/alpha-blended surfaces render wrong (glass partitions, holographic displays) | **FIXED** (index: gfx_sp_vertex fix) — plan row was stale (2026-09-23 reconcile). |
+| D197 | Character face textures wrap around the head instead of clamping (Silo, intermittent) | **CLOSED** (user playtest v0.2.0-pre) — plan row was stale (2026-09-23 reconcile). |
+| D182(2)/D176(b) | File-select background degrades after round-trip (comb/interlacing); Surface tree-line static — shared "texture pitch/shear" defect | M-36 Family A; `import_texture_*` line-size assumption. Distinct from the disproven D183 hypothesis. |
+| D176(a) | Sky: RDPHALF tri-raster decode; horizon-band coverage (Defect 2) still open | Path B draft in `scratchpad/sky.patch`, phase-fold fix applied, **never visually verified** — one `-level_22` screenshot owed. Branch `land/d176a-sky-perspective-scroll` exists (forgejo remote) — audit + port to main. |
+| D75 | Front-end logos: Nintendo logo degenerate (tiny orbiting fragment); Rareware filtering wrong | **FIXED (M-197, user-confirmed live 2026-09-21)**: D50 sidecar converter dropped embedded texture blobs. Remaining: pal/jpn sidecar regen on ROM-holding machines. |
+| D290 | Watch in-game "controller" section shows no control-pad graphic | **FIXED 2026-09-23 (`a5804d10`)**: D264-pattern template read in `watchRenderController` + 3 pointer-width/raw-Gfx sites. Sibling sweep also found + fixed **D331** (shell casings never rendered, `94dff811`). |
+| D174/D172 | Blood: decals never interactively verified (D120 needs sidecar regen); spray color fixed but owed an eyeball | BUNKER1 firefight with regenerated sidecars (`d43 && d69 && d88 --regen`). |
+| D240/D241 | Gunshot SFX cadence drifts; PP7/AK47 goes silent under heavy fire near looping sounds | D241 high-confidence = D207 reproduced (check D207 entry status first — index row is stale/ambiguous). Fold into the D207 voice-cap family. |
+| D322 | Long-session audio degradation (issue #87, v0.3.0 full campaign): from Silo onward audio worsens; by Caverns/Cradle OST inaudible + SFX "come and go"; restart cures → session-accumulating state | OPEN — static triage done (teardown audit clean, mixer stateless, D202 leak class covered only for ownerless `count==-1` loops and only validated single-level; D305 already records a pool/list desync). Ranked: voice-pool exhaustion/counter drift > queue starvation > evtq saturation. `GE_D322` pool-telemetry probe shipped 2026-09-21; needs a campaign capture with `GE_D322=1 GE_D204=1`. |
+| D311 (residual) | Upstream anim-poison source still open (freeze class guarded) | **Likely root-caused by D336** (head-bob alias read); headless Caverns clean at 2× pool. Close after one live Caverns combat session. |
+| D258 | PAL/JP asset conversion broken at the source-data level | Repair path verified, not applied. Region fidelity — NTSC-only users unaffected, but it blocks "faithful in every region" and any JP/PAL ROM use. |
+| D160 (residual) | Cutscene reliability PARTIAL (D243 family mostly fixed via M-189/M-190) | Residual = whatever the live GE_D160/GE_D243 campaign pass shows. |
+
+### Bucket B — Stability (crashes/freezes/hangs; not N64-parity per se)
+
+| ID | Item | State / notes |
+|----|------|---------------|
+| D289 | Dam computer-room crash (Deck, one occurrence, never repro'd) | Needs a human re-test on a current build (D255+). If it never recurs → close as untracked. |
+| D287 | Windows: real, non-self-recovering freeze after ~15–20 min idle + click-back | One confirmed occurrence; `gfxFrameMsgQ` full is a lead. Consider crash-dump wiring on Windows for the next hit. |
+| D286 | Deck: ~8 s self-recovering frame freeze on Caverns | One confirmed occurrence, no repro trigger. |
+| D175 | Brief stutter/hang (door-open on Runway/Surface) | Matches known transient-hang classes; reproduce under `tools_pc/debug.ps1` idle-box before believing it's new. |
+| D285 (residual) | Audio-thread race fix was PARTIAL | Re-check the thread-lock state vs D305's NULL guard coverage. |
+| D281 | AllUnlocked breaks audio + RMB aim when enabled with zero saves written | User-facing mitigation shipped; proper fix = make the feature robust or gate it harder (see Phase 3 decision). |
+| — | getenv caching in hot paths (**DONE 2026-09-23, `d9d7cd35`**) (post-release cleanup, HANDOFF M-192) | D302 fixed one instance; sweep for stragglers. Cheap perf/stability hygiene. |
+| D117 | Frame nondeterminism (GE_DETERM attempted, not achieved) | Parked as a research item; do not block the release on it. |
+
+### Bucket C — Improvements / QoL (outside OG game; after fidelity)
+
+| ID | Item | Notes |
+|----|------|-------|
+| Widescreen | Currently **stretched 4:3**, not native — README discloses this | **DONE 2026-09-23 (D334 world `d5d9a36a`, D335 HUD/front end `f62bceaf`)**: native at any aspect, default on, F10 toggle; Rule-2 approved. Owed: user HUD playtest at 16:9/21:9; D335a cosmetic. |
+| D237 | F10 overlay: mouse-wheel scroll, more settings, category grouping | **DONE 2026-09-23 (`91bd0f84`)**: F10 category headers + 5 more rows (wheel scroll already existed). |
+| D314/D315 | F10 flicker (user-deprioritized) + main-vs-in-game menu scaling | D315 deferred from v0.3.0; bigger design question — lands naturally with the overlay work. |
+| D238 | Mouse sensitivity rework (master sens, RMB aim sens, Y-gain parity) | Partly superseded: aim modes folded (D337, N64 default via PD integration; Centred (PC) opt-in), Aim range PC/N64 (D338). Remaining: sensitivity feel tuning. |
+| D239 | Click-to-lock parity: delete always-grab mode 0 + config key | Small; closes D192 by deletion. |
+| GEPD controls (M3) | **IMPLEMENTED, targeted playtest owed (D378/D380/D383–D386).** One effective keyboard/mouse layout, no `Input.Layout` selector: Ctrl crouches without aim; E interacts without reloading; R reloads without interacting. Input → Bindings → Movement/Actions edits two Primary/Secondary keyboard-or-Mouse 1–5 slots in both UIs (D388). Mouse 3 (right) is Aim default; wheel still cycles weapons. Menu arrows/Enter/Escape and mouse clicks remain fixed. See `MODERN-OPTIONS-PLAN.md` M3; earlier preset/B-button text there is historical. |
+| Modern controller presets (D394) | **1.1 Jinx button roles physically confirmed; precise gadget category still open**: A action, X reload, B cycle owned gadgets, Y cycle weapons, L3/R3 crouch, RT fire, LT/LB aim, D-pad movement, Start pause. RB updated-graphics and Back scores are XBLA remaster-specific: no HD assets/score view in the N64 port; reserve RB, keep Back→PC options. **Planned** named selector: 1.1 Jinx (L move+strafe, R look+turn), 1.2 Christmas (L move+turn, R look+strafe), 1.3 Frost (L look+strafe, R move+turn), 1.4 Elektra (L look+turn, R move+strafe). Face/trigger roles remain fixed across schemes. Add an `Input.ControllerPreset` enum with default 1.1, F10/front-options selector, preserve per-pad inversion/deadzone, separate keyboard `NaturalPitch` from the pad selector, adapt both stick axes and D-pad per scheme, and verify in watch/menu/tank and physical controller before labeling each selectable. Do not treat these four presets as already implemented. |
+| Modern options wave (parity set, 2026-09-27) | **In progress, not a single opt-in Modern page (D388).** M1: Input → Bindings and Gameplay → HUD, shared by F10/front; M2: Original red crosshair plus White/custom RGB, style, size and visibility implemented (D379/D381/D382); M3: single effective layout and rebinding (above). **M5: redundant Low-end toggle removed (D388); Frame rate cap and Anti-aliasing remain independently adjustable, stored values preserved on migration.** M4 GE+ knockback/hitstun/damage-sound/death-cam toggles parked for v0.5.0, not v0.4.0 blockers. **M7 BLOCKED (D387):** AllUnlocked ON can persist synthetic cheats/times after any profile-settings save; OFF does not remove them. Do not run on live saves; a safe design and multi-profile fixture tests are owed. PNG screenshot upgrade dropped from this wave; dev PPM dump remains. The M1–M7 detailed notes retain their historical design record in `MODERN-OPTIONS-PLAN.md`. |
+| D226 | Player-adjustable HUD scale (ammo counter, pickup text, dialogue) | **DONE 2026-09-24 (`30720354`)**: Game.HudScale 75–150% (user-verified), fast3d rect scaling about anchors, dialogue/bottom width-capped. |
+| Controller rebinding UI (D395) | **Not implemented.** The two Input → Bindings → Movement/Actions pages edit keyboard/mouse slots only. Pad-only users could previously enter a capture modal and get stuck; pad-triggered capture is now disabled in both UIs and B cancels a capture started by keyboard/mouse (NTSC build linked; physical pad-only retest owed). Controller presets (D394) are separate from arbitrary pad rebinding; design an explicit controller-actions page, persistence/migration and capture/cancel semantics before enabling pad capture. | Post-v0.4 scope decision; no promise that keyboard binding slots can hold pad buttons. |
+| Rumble (D224) | Wire `osMotor*` → `SDL_GameControllerRumble` (PD precedent exists) | Deprioritized M-87; pick up if gamepad support is in scope for v0.4.0 — user call. |
+| Per-pad tuning / hot-plug | PD incremental hot-plug + remembered seats; deadzone/scale/rumble per pad | Medium; real-controller users. |
+| Window polish | HiDpi, center window, maximize/default-fullscreen | Small P-class wins. |
+| Unlocked FPS | Plan parked; premise changed (D248/D250 fixed — default is now a true 60) | Phase 0 re-measurement before any work; motion interpolation stays out. |
+
+### Bucket D — Infra / housekeeping
+
+- **D244** self-hosted CI runner link failure — fix before the release tag so
+  CI can build win+linux bundles (or confirm GitHub runners suffice).
+- Post-release v0.3.0 cleanup (HANDOFF): remove GE_OBJT probes
+  (`chraction.c` chrSet/UnsetStageFlags, `propobj.c` GAS line); M-183/M-185
+  clamp removal pending full-cutscene re-verification; D309 probe decision
+  (keep for v0.4.0 debugging or remove).
+- Working-tree archaeology: ~~uncommitted D236 second-pass state~~ **RESOLVED
+  before this plan was written — `532092c7`/`6807555c` (Sep 15) already landed
+  the D266 IA4/texedge decode + D271 portal-culling fixes on main and dropped
+  the D267–D280 probes.** Consequence: Phase 1 item 9 (D249) can proceed with
+  the D271 fix in-tree; the D236 tree-wall work continues from D276's oml/fmt=3
+  lead on top of the landed decode fixes.
+
+## Session additions (2026-09-23/24, local)
+
+- **D336** Frigate "everything breaks but the gun" (uninitialised head-bob alias fields, D100 follow-up): FIXED, user-confirmed.
+- **D337/D338** aim modes folded + Aim range option: user-approved ("Seems good").
+- **D339** #92 low-end perf: `GE_PERFSTAT` probe; CPU budget measured (~2 ms/frame), GPU the likely bottleneck; needs target hardware.
+- **#105** (Enhanced/Remaster water reflection) refers to a `feature/graphics-final-stack` branch that isn't on origin or local; not v0.4.0 scope. Its "D329" label collides with ours, so watch for that if that work merges.
+
+## Phases
+
+### Phase 0 — Hygiene (½–1 session; do before any fidelity work)
+1. Branch `release/v0.4.0` off `main`.
+2. ~~Resolve the uncommitted D236/D271 tree state~~ already landed (`532092c7`).
+3. Remove GE_OBJT probes + playtest-folder `.bat`; decide D309 probe fate;
+   getenv-cache sweep.
+4. Fix/confirm CI runner (D244) so release tooling works end-to-end.
+5. Carry-over verifications from the v0.3.0 handoff that were owed:
+   Runway AllUnlocked toggle re-test, menu-click spot check (D316/D317 both
+   closed — just confirm no regression on the new tree).
+
+### Release gate (independent of the phases below)
+
+**D322 (long-session audio degradation, issue #87)** is a campaign-breaking
+defect in shipped v0.3.0 and does not wait for the phase ladder: the
+`GE_D322` probe is already built and smoke-tested — request the campaign
+capture (`GE_D322=1 GE_D204=1`) from the reporter now, and run its decision
+rules as soon as the log lands. If the capture implicates a port-side leak,
+the fix slots into Phase 2; if it's a rule-2 behavioral difference, it gets
+its own sign-off item.
+
+### Phase 1 — Fidelity wave (the release's core)
+Ordered by (crash risk → visibility → effort); each item ends with its own
+verification (headless where possible, human eyeball/ear as merge gate):
+
+1. **D320 live verification + watchdog generalization** — the only open
+   item that can hard-lock progression on 8 levels; probes already exist.
+2. **D289 re-test** (crash class; one human pass, then close or chase).
+3. **Batch "one-off geometry/texture anomalies": D288 + D294 + D291** —
+   all are single-location, bounded, visually documented; likely share a
+   fast3d import/culling root cause. One investigation thread.
+4. ~~**D252 rainbow particles second cause**~~ — **retired (M-188):** the
+   user's symptom closed as a duplicate of the D219 fix (live retest clean);
+   decode + dimensions proven correct (M-141/M-156). Re-open only on a
+   fireball-rainbow re-report.
+5. **D245 water seam** — candidate fix exists; A/B against N64 reference,
+   then flip default (A1-class fidelity call).
+6. **D303 + D306/D308 z-fighting family** — small visual parity items; batch
+   per commit cadence. (~~D307 camera flip~~ investigated 2026-09-21: no
+   port-side bug found, all inputs verified N64-faithful — blocked on user
+   repro detail; see Bucket A row.) D303 + D306/D308 both investigated
+   2026-07-19: no port-side bug found in either (pipeline/data/precision all
+   verified N64-faithful); capture probes `GE_D303` and `GE_ZF` are in-tree —
+   both now blocked on user-side captures (firing repro / N64 reference).
+   Nothing further to do agent-side until those land.
+7. ~~**D236 tree wall**~~ — **done (M-198, pass 26):** `TEXTURETYPE_DETAIL`
+   tile-binding fix in fast3d (`Video.DetailBaseTile`); live-verified,
+   probes stripped. Only the user play-test sign-off remains.
+8. ~~**D235 texture reload leak**~~ — **done (M-193):** port-side
+   `TextureCacheMap` now cleared on every stage transition via
+   `videoResetTextureCache()` in boss.c; 21/21 sweep pixel-identical; live
+   death/restart confirm is a playtest item.
+9. **D249 culling** — *after* the D271 overlap check; live screenshot+location
+   first, BFS instrumentation second.
+10. **Audio parity: D322 long-session degradation first** (issue #87 — the
+    only audio report that breaks a full campaign; `GE_D322` probe already
+    shipped, get the campaign capture, then apply the decision rules in the
+    finding), **then D240/D241** (fold into D207 family) + verify D230's bass
+    fix by ear on the elevator track.
+11. **Front-end fidelity batch: D290 watch pad graphic, D182(2)/
+    D176(b) pitch-shear defect, D176(a) sky Defect 2** (verify the patch
+    visually first — it's been unverified for weeks). (~~D75 logos~~ fixed
+    M-197; ~~D195 Control alpha~~ FIXED per findings; ~~D197 face wrap~~
+    CLOSED at v0.2.0-pre playtest — both were stale in this list.)
+12. **D174/D172 blood verification** (regen sidecars, BUNKER1 firefight).
+13. **D258 PAL/JP asset conversion repair** — apply the verified repair path;
+    re-run the region sweep. Decide scope: ship JP/PAL-accurate or document
+    NTSC-only for v0.4.0 (user call).
+14. **D311 upstream anim-poison source** — close out the last open thread of
+    the freeze class so the known-issue bullet can be dropped.
+
+Exit criteria: every README "Known issues" bullet either fixed or explicitly
+re-disclosed with a v0.5.0 pointer; no new fidelity regressions (21-level
+sweep after each landing).
+
+### Phase 2 — Stability wave
+1. **D287/D286 freeze investigation** — wire Windows crash dumps (or an
+   in-process fault log) so the next occurrence is diagnosable; pattern-match
+   against `gfxFrameMsgQ` lead and the D309 teardown-race class.
+2. **D175 stutter** — idle-box repro under `tools_pc/debug.ps1`; likely a
+   known transient-hang class, confirm and close or chase.
+3. **D285 residual** — re-audit audio thread-locking vs D305's guard.
+4. **D281 AllUnlocked no-save path** — make it robust (root-cause the
+   sndHandleEvent/aim interaction) or gate the toggle until a save exists.
+   User call on which.
+5. Long-idle soak test (both platforms) as the stability acceptance bar.
+
+### Phase 3 — Improvements / QoL (only after Phases 1–2 are green)
+Order by user-visible value (2026-09-27 refresh — several rows since DONE, marked):
+1. ~~**Native widescreen**~~ — **DONE 2026-09-23** (D334/D335; playtest sign-off owed).
+2. ~~**F10 overlay wave: D237 + D314/D315**~~ — D237 **DONE 2026-09-23**; D314/D315 still open (user-deprioritized; lands with further overlay work).
+3. **Input feel: D238 sensitivity rework, D239 delete always-grab, window
+   HiDpi/center; rumble + per-pad tuning if gamepad is in scope (user call).**
+4. ~~**D226 HUD scale**~~ — **DONE 2026-09-24**.
+5. Unlocked FPS: re-measure Phase 0 against the post-D248/D250 baseline and
+   decide whether v0.4.0 or v0.5.0.
+6. **Modern options wave — substantially implemented, NOT release-complete**
+   (D377–D389). Five functional roots; Input → Bindings → Movement/Actions
+   and Gameplay → HUD work in both menus. One effective PC layout with
+   dedicated E/R/Ctrl; two bind slots including Mouse 1–5; crosshair
+   visibility, Original/White/colour, style and size. Redundant Low-end
+   preset retired, but FPS cap/MSAA remain. M4 GE+ toggles deferred to
+   v0.5.0, M6 PNG screenshot removed from this release. **M7 blocked by
+   persisted fake save progress (D387); do not test with a live save**.
+   Physical acceptance, M7 release decision, 21-level visual gate and
+   documentation/commit reconciliation are still open. Earlier "one
+   opt-in section/default-off/preservation proof" estimates were superseded;
+   the original research remains in `MODERN-OPTIONS-PLAN.md`.
+
+### Phase 4 — Release ritual
+1. `./build-pc.sh ntsc-final` clean; `/linkcheck`; full 21-level
+   `tools_pc/verify.sh sweep --json`.
+2. Full campaign playtest sign-off (user), incl. the D320-probe levels and a
+   water level + Surface + Silo (the Phase 1 visual fixes).
+3. Refresh README Known Issues, `.github/release-notes.md`, findings index;
+   regenerate `agentic-development.md` stats from git (still owed since
+   v0.3.0 prep).
+4. Push `release/v0.4.0` → tag `v0.4.0` → CI draft bundles → validate both
+   artifacts → fast-forward main.
+
+## Explicitly out of scope for v0.4.0
+- macOS/ARM, LAN multiplayer.
+- Motion interpolation / sim-rate changes (UNLOCKED-FPS non-goals).
+- D117 frame determinism (research-parked).
+- **Mod support and HD texture packs — both post-1.0, both researched; see below.**
+
+### Post-1.0, researched and tracked (do not start in v0.4.0)
+
+Both were investigated 2026-09-22 against the Perfect Dark PC port fork
+`perfect-dark-dabs-mod-dabs-mod` (**MIT**, Ryan Dwyer — same license as this
+tree; `AGENTS.md` already names the PD port a standing reference, so code may be
+adapted with attribution). Fuller sequencing notes live in the local
+`docs/dev/notes/MODERN-PORT-FEATURES-BACKLOG.md` §5/§6, which is
+gitignored — the
+durable record is `docs/dev/findings.md` and the summary here. The
+drop-in mod support design itself is expanded in the local
+`docs/dev/notes/MOD-LOADER-PLAN.md` (2026-09-27: C1–C4 components, v1
+scope, acceptance bar).
+
+**Mod support (ROM patches) — viable, medium–large.** Findings **D325–D328**.
+- Community mods *repack* the ROM, so vanilla offsets are useless: Goldfinger 64
+  (12→24 MB, 797/803 slices differ) and even the content-neutral Random Eye
+  randomizer (identical ROM size, yet 803/803 slices differ — content shifted
+  +7392). Both die in `tools_pc/d43_emit.py:273` on a vanilla-offset zlib slice.
+- **The fix is not a loader rewrite.** PD's `port/src/modimport.c` states our own
+  constraint verbatim and instead diffs the patched ROM against stock, extracting
+  what differs into a **mod directory** its loader already reads. The game keeps
+  running its stock ROM at fixed compiled offsets.
+- GE's file table is in the ROM after all (D327 said otherwise; corrected by
+  D328): 1172-compressed data segment at ROM `0x21990` — one raw inflate, which
+  `port/src/rzdecomp.c` already wraps — table at `0x252c4`, 727 records of 12
+  bytes, pointers `0x80020d90`-based, size by differencing adjacent addresses,
+  exactly `obInit` (`src/game/ob.c:126`). Verified: **681 exact offset+size
+  matches vs `filelist.u.csv`, 0 mismatches**; discovery needs **no hardcoded
+  offsets** and reads Random Eye's own table to **704/726 files byte-identical**.
+- Remaining work: extraction in C (proven), patch decoding (PD's `rompatch.c` is
+  an MIT VCDIFF/BPS/IPS decoder — **removes the GPLv2 xdelta3 constraint**),
+  converters taking the extracted table, and the real effort: a
+  **mod-directory override layer** — `port/src/romdata.c` reads the ROM only and
+  has no analogue of PD's `romfile.moddir` file slots.
+- **Hard limit:** mods that *add levels* need new stage-table entries in
+  `src/game` — rule 2, not the ABI/layout exception. Either a sign-off or scope
+  down to the existing 20 slots. ASM/code mods stay impossible (ROM code is never
+  executed here).
+
+**HD texture packs — medium, well-scaffolded. Answers issue #100** ("High
+Resolution Textures", open, `enhancement` — a user asking whether HD textures can
+be used with the port). Architecture studied from PD's
+`port/include/texpack.h` + `port/fast3d/gfx_pc.cpp`; no finding written yet, so
+this entry and backlog §6 are the record.
+- **Identity is the whole problem, not decoding.** The renderer only ever sees
+  the pointer `gDPSetTextureImage` was handed, so PD keeps an address →
+  texture-number registry populated where `texLoad()` runs and invalidates it
+  when the pool drops (a stale entry names the *wrong* texture). Then three-tier
+  matching: texture number → texel checksum (for textures embedded in model
+  files) → per-record. Packs are `textures/<texnum>.png`; decode happens on a
+  worker so loading does not hitch; the hook is inside `import_texture`, gated so
+  it costs one lookup when off.
+- Most scaffolding exists here: our `gfx_pc.cpp` is the same lineage
+  (`gfx_texture_cache`, `:92,579`), `g_Textures[].texturenum` exists
+  (`src/game/chr.c:3894`), and **`GE_TEXDUMP` already dumps textures**
+  (`port/fast3d/gfx_pc.cpp:1205`) — it just names them by sequence
+  (`r000_f3_s1_64x64.bin`) rather than texture number, so dumps cannot round-trip.
+  Renaming that is the single change turning the probe into a pack dumper. A PNG
+  decoder is the one new dependency, and zlib is already required.
+- Step 1 (the identity registry) is the only novel design decision, and it
+  records identity where textures load — a `src/game` touch needing `#ifdef PORT`
+  plus a §F note. Settle that at design time, not mid-implementation.
+
+## Session log (agent-driven, 2026-09-20 evening)
+
+**Phase 0 — done except user-side items:**
+- `release/v0.4.0` cut off `main` (which already carried the D266/D271 fixes,
+  `532092c7` — the "uncommitted tree state" item was stale; plan updated).
+- D322 probe work committed (`7bb43260`); GE_OBJT probes removed (D321 closed,
+  M-192 item 7, `56ac2ab8`); D309 probe **kept** (inert, cheap, recurrence
+  value for the D309/D310 freeze class).
+- getenv hot-path sweep (D302 follow-up): function-level scan of all GE_*
+  sites found no frame/triangle-rate stragglers in fast3d; cached four
+  per-frame/per-hit guards in `src/game/bg.c` (GE_D104 room pass, GE_D63
+  primary+secondary render logs, GE_D154 inner GDL walk) — all `#ifdef PORT`,
+  mechanical.
+- D244 (self-hosted CI runner): needs `pacman -Syu` on the box itself —
+  **user-side action**, not locally fixable; fallback (`#ifdef PORT` thin
+  wrapper for the `#pragma weak` alias) only if the toolchain update fails.
+- 21-level sweep gate: running on the new tree (see `scratchpad/sweeps/`).
+- Carry-over D316/D317 + Runway AllUnlocked re-tests are interactive → folded
+  into the big playtest brief below.
+
+**Phase 1 — in flight:**
+- Item 1 (D320): generic pin-signature detector added to `d318TimelineTick`
+  (`GE_D318T=1` now covers any chr: ACT_ATTACK + live-fire attacktype +
+  byte-stable animframe for 10 s → one `D320T: PIN?` line per chr, repeating
+  every 10 s while pinned). Detection only — the recovery watchdog stays
+  hardcoded to ai_22 per D320's own instruction until a second list freezes.
+  Live verification of Facility ai_19 / Control ai_9 / Depot ai_12 beats =
+  playtest work (see brief).
+- Item 3 (D288/D294/D291 batch): D288 probe refined per M-155 follow-up
+  (any_behind_camera==0 only — the w<0 bbox math was a false lead; oml word
+  now logged for asset ID). D294: `GE_D104` room-visibility trace confirmed
+  sufficient (curRoom/roomsDrawn/budget + per-room load state every 10 s);
+  needs live Statue repro at FovScale≈130 + max draw distance. D291: still
+  needs live Dam truck details — lowest value of the three.
+- Item 13 (D258 PAL/JP): **deferred pending user scope call** (ship
+  multi-region or document NTSC-only for v0.4.0) — no PAL/JP ROMs available
+  here to verify a blind CSV rename against.
+- Item 4 (D235 wrong textures after death/restart): **mechanism found + fix
+  applied (M-193).** M-108's refutation of the game-side CI-cache theory
+  stands, but the *port* has its own `TextureCacheMap` (source-address keyed,
+  no content check) that was never invalidated on stage transitions —
+  `videoResetTextureCache()` existed with zero callers. Now wired into the
+  per-stage reset block in boss.c (`#ifdef PORT`, after `memaReset`).
+  Pixel-identical re-uploads; golden sweep running to confirm. Live
+  death/restart confirmation + a `GE_D235` >0 capture are playtest items.
+- D311 upstream poison source (M-194): static pass done — all
+  `sub_GAME_7F06FE90` callers pass arg2=16.0f (denominator safe); the
+  old→new lerp only circulates values; `bheadAdjustAnimation` is the one
+  path where a live player-velocity corruption reaches `model->speed`. Both
+  speed-write choke points (`modelSetAnimSpeed`, `modelSetAnimation2`) now
+  log `D311: … ANOMALY` on |v|>1e4/NaN — next Caverns occurrence is a
+  one-line diagnosis. No env var (D156-guard pattern).
+- Item 4 (D252 rainbow particles): **effectively closed — no agent work
+  left.** Re-read the finding this session: M-141 refuted the width/height
+  suspect (line=4 → correct 16×14, cross-confirmed by the GE_TEXDUMP
+  is_fire_shape filter), M-156 proved the ROM bytes decode to a clean
+  white-hot→ember progression, and **M-188 closed the user's actual symptom
+  (lingering residue sprites) as a duplicate of the D219 fix** — user
+  retested live: "seems fine now." Only a *fireball* rainbow re-report would
+  re-open it. Plan item 4 retired.
+- Item 10 (D207 alarm klaxon): **blocked on user repro info, not agent-
+  workable.** M-77b implemented the designed last-resort LOOPED-preemption
+  pass + `[D207-DROP]`/`[D207-YIELD]` counters, BUNKER1 forced-alarm soak
+  showed zero drops / zero yields (pass 1 always finds a victim), and the
+  change was reverted. The finding now asks for: which level, which
+  weapon/situation, and a `GE_AUDIOTRACE=1` capture (or clip) of the failing
+  alarm — then decide between heavy-level 8/8 starvation (re-apply the
+  reverted pass), an alarm-stop-path leak, or pure perception (klaxon mix
+  volume vs N64). Added to the playtest brief as a low-effort ask.
+- Full 21-level golden sweep: **21/21 PASS** on the final tree (`bb508e5c`),
+  confirming D235 fix + D311 probe + all Phase 0 changes are pixel-identical.
+- **D75 (Nintendo logo) investigation — M-195, no root cause yet but two
+  suspects eliminated.** (a) Fresh `GE_D63` run: all 23 logo Primary GDLs
+  emitted every frame, zero unknown-opcode warnings → emission + DL
+  consumption fine; PC GDLs byte-faithful to N64 source. (b) New `GE_D75V`
+  per-batch vertex probe: transformed coords match the wordmark geometry
+  exactly (MP translation matches the lookat) → basematrix / f32→s32 /
+  matrix-list suspects eliminated. **Leading hypothesis:** every `G_VTX`
+  batch encodes v0=0, so multi-batch nodes overwrite shared vertex slots
+  0..n−1 (only the last batch survives; higher-indexed triangles read stale
+  slots) — consistent with the single tiny orbiting fragment observed. Next:
+  ROM-dump one node's GDL stream and cross-reference `G_TRI4` index ranges
+  against per-batch counts; fix would be port-layer fast3d slot management.
+  Probe code (`gfx_pc.cpp`, `videoGetFrameCount()` in video.c/h) uncommitted
+  at end of session — commit with the doc updates.
+- **D307 (CCTV facing backwards) investigated — no port-side bug found.**
+  Env-gated `GE_D307=1` probe in `setupCctv` dumps every input + derived
+  orientation per record. Bunker1 (`UsetupsevbunkerZ`) decode vs live: model
+  switch offset = `PcctvZ` (NOT `GcameraZ`, that's the gun) sw[0]
+  bit-for-bit; boundpads match the pccg sidecar once the legitimate load-time
+  room-scale (`pad->pos *= get_room_data_float2()`, ≈1.8542 here) is applied;
+  record config words (incl. `unkCC`) match; all matrix/atan2 helpers are
+  byte-identical `src/game` code. Conclusion: PC orientation values == what
+  the N64 computes; if the symptom is real vs N64, the remaining suspect is
+  fast3d's handling of the non-orthonormal lens matrix (`unk84` row 0 scaled
+  0.1×). Blocked on user repro detail (which camera/level + screenshot).
+  Findings entry updated; probe kept in-tree (D60/D88 pattern).
+- **D303 (extra long muzzle flash) investigated — no port-side bug found yet,**
+  blocked on live capture. Mapped the full flash pipeline (`gunUpdateAndFire`
+  builds `rwmtx[1]` = yaw×scale×flashext and `rwmtx[2]` from `Switches[2]`; the
+  flare arms are `dorottex` DLPRIMARY nodes) — all byte-identical game code,
+  matrix helpers verified index-for-index. Ruled out: weapon stats (M16's
+  flashext=6.0 is the legitimate max, sniperrifle matches; the ext≥3 ⊆
+  CAN_DUAL_WIELD overlap is design coincidence) and model conversion (Gm16Z
+  DLPRIMARY records + vertex blocks byte-faithful per d43 round-trip). Added a
+  TEMP `GE_D303=1` probe in `gfx_pc.cpp` (cached-getenv; logs very-tall-thin
+  emitted triangles with blend/oml/comb/prim/env/w) — 75 s unattended runs on
+  Bunker1/Dam/Depot show only static scene geometry, so the artifact needs a
+  live firing repro. Next: user fires the M16 under `GE_D303=1` and shares the
+  log lines; the spurious quad's RDP state will identify its source.
+- **D306/D308 (z-fighting family) investigated — real fighting confirmed, cause
+  framed.** Verified GE's RSP writes post-transform x/y/z/w as full 32-bit 16.16
+  (not s16 8.8), so the port's float pipeline + `GL_DEPTH24_STENCIL8` matches N64
+  depth precision — no port-side precision deficit exists. Built a TEMP
+  `GE_ZF=1` flicker probe in `gfx_pc.cpp` (96×54 screen-cell grid, per-cell depth
+  history, requires non-monotonic a-b-a oscillation within GE_ZFTOL recurring ≥5×
+  at the same cell; `GE_ZFBOX` region filter) — earlier center-pair and simple
+  flicker variants saturated on tessellation noise. Dam (`-level_33`) unattended:
+  sustained hits in the lower-left truck region with per-cell oscillation counts to
+  ~970 → D306's "transparent areas" are real depth-test alternation. Prime suspect
+  is level-authored coincident geometry (fights on N64 too); confirming port-only
+  needs an N64 reference of the same spot, and a mitigation (e.g. float depth)
+  would diverge from N64 — parked pending that.
+- **Plan/doc refresh:** D75 (M-197) and D236 (M-198) marked fixed throughout
+  (Bucket A rows, Phase 1 items 6/7/11, playtest brief); findings index
+  regenerated; README Known Issues to match.
+
+### Big playtest brief (for the user, when the tree is final)
+
+Build: `./build-pc.sh ntsc-final`. Set **`GE_D322=1 GE_D204=1`** for the whole
+campaign (D322 pool telemetry — the release gate). For the three D320 beats,
+add **`GE_D318T=1`** on: Facility (the captive-scientists monologue/execution
+beat), Control (the ai_9 guard beat), Depot (the execution beat) — watch for
+`D320T: PIN?` lines; a frozen run keeps printing every 10 s.
+
+Checklist beyond the normal play:
+1. **D322**: full campaign, share `ge007.log` after (decision rules in the
+   finding).
+2. **D316/D317 regression confirm**: click menu rows at a few window sizes,
+   esp. low rows (crop overscan bars) with SafeAreaCrop on/off; toggle
+   Game.AllUnlocked back and forth in-game.
+3. **D289**: Dam computer room — interact with the terminals (was a one-off
+   crash, likely D255-class, already fixed — confirm it stays gone).
+4. **D294**: Statue, set FovScale ≈130 + max DrawDistance/LodDistance, walk
+   past the CCCP monument at ground level; if the black-ground window hits,
+   note the time (a `GE_D104=1` run there is the follow-up capture).
+5. **D291**: Dam — watch for texture glitches as the truck drives past;
+   screenshot + which surface.
+6. **D175**: door-open on Runway/Surface — note any stutter/hang.
+7. **D287**: leave a level idle+unfocused 15–20 min, click back (the
+   non-self-recovering freeze; one prior occurrence).
+8. **D320 beats** as above with `GE_D318T=1`.
+9. Audio by-ear: elevator track bass (D230 verify), PP7/AK47 under heavy fire
+   near looping sounds (D240/D241).
+10. **D235**: on any level, die and restart (or reload a save) in the same
+    session, then look around — textures should be correct (no swapped/wrong
+    stage textures). Run once with `GE_D235=1` and share the log if anything
+    looks off (a `>0` count means a stale-cache hit slipped through).
+11. **D288 (Silo)**: play Silo normally; if you see the wrong-color target /
+    geometry anomaly, set `GE_D288=1 GE_PCDUMP=1` for a 30–60 s run around it
+    and share log + captures (the probe logs the offending oml word for asset
+    ID).
+12. **D311 (Caverns)**: play Caverns ~2 min of normal combat; if the anim-
+    speed freeze/poison recurs, the log will now carry a one-line
+    `D311: … ANOMALY` naming the corrupting call site — share it.
+13. **D207 (alarm klaxon)**: if gunfire goes quiet during an alarm, note the
+    level + weapon + situation; ideally re-run that spot with
+    `GE_AUDIOTRACE=1` and share the log (or a short clip).
+14. **D75 (front-end logos)**: confirm the Nintendo/Rareware logos + legal
+    page still render correctly (fixed M-197; user-confirmed once already).
+15. **D236 (Surface trees)**: Surface 1/2 — confirm the treeline renders as
+    discrete tree sprites, not a wall (fixed M-198; probes stripped).
+16. **D307 (security cameras)**: if any in-level CCTV camera looks like it's
+    facing backwards, note which level + which camera (screenshot) — the
+    orientation math is verified N64-faithful, so a concrete repro is what's
+    needed to keep chasing it.
+17. **D303 (extra long muzzle flash)**: run with `GE_D303=1` in your terminal,
+    fire the M16 (and any other gun that shows the extra upward flash) until
+    you see it, then share the `D303:` log lines from around that moment —
+    each line carries the RDP state of a candidate quad and will identify the
+    spurious draw call's source.
+18. **AllUnlocked preservation (M7) BLOCKED — D387.** Do not run this
+    against a real save: even changing a profile setting while ON persists
+    synthetic cheats and 0x3FF completion times; OFF requires a restart and
+    does not undo already-written fakes. First define safe earned-progress
+    semantics, fix in `port/`, and verify on private copies with settings
+    writes, mission completion, OFF restart and multi-slot CRC checks.
+    M4 modern toggles are parked to v0.5.0.
+
+## Conventions reminder
+- One findings entry per investigation; the index tail moves constantly —
+  it ended at **D370** as of 2026-09-27 (the F10 drag entry), so new
+  labels start **D371+** (the old "after D322" note is long stale; always
+  confirm the tail of `findings-index.csv` before filing).
+- Fidelity fixes: port-layer or documented A1/ABI exception only; genuine
+  behavioral differences need the rule-2 sign-off (`docs/dev-process.md`).
+- Every subagent reads `docs/porting-notes.md` first and appends to it.

docs/dev/WATCH-SETTINGS-PLAN.md

@@ -0,0 +1,63 @@
+# Watch-backed settings in PC Options and F10 — proposal for review
+
+Status: **watch-backed subset implemented (D350), robustness fixes landed (D352), Turok-style regrouping done (D353), front-end F10 routing + transparent default Bond-file selection landed (D354: non-stage contexts use the chooser path, default = explicit pick > `selected_folder_num` > first valid file, with a one-shot `fileBuildWriteNewSave(FOLDER1)` fallback; GE_WSPROBE/GE_WSPROBE_FRONT headless probes), the in-stage BGM resync landed (D355: the Music commit also drives the track-1 BGM player, matching the game's own MP-path resync; by-ear confirmed), and the settings regroup landed (D356: functional sections INPUT/GAMEPLAY/GRAPHICS/AUDIO/VIDEO, PD-style "(File N)" scoping annotations, N64-watch rows off the menu surface, per-section reset-to-defaults = Gate E; GE_WSPROBE_RESET headless probes front + in-stage).** Wider M3 remains outstanding: master volume, key rebinding. PC-only per-file persistence and explicit Bond-file chooser approved; details below. See `docs/dev/findings.md` D350–D356 for verification. This is the watch-integration part of M3, not a replacement for the native watch menu. The older tracked `docs/dev/OPTIONS-MENU-PLAN.md` and local `docs/dev/notes/OPTIONS-MENU-PLAN.md` describe the wider M3 scope (master volume, window mode/display, resets).
+
+## Goal and ownership
+
+Show GE's existing watch settings in both PC settings surfaces (`MENU_PC_OPTIONS` and F10) without maintaining a second copy of each value. Both surfaces already consume one row table in `port/src/optionsoverlay.c`; the watch remains an independent UI editing the **same underlying GE value**. Changes made in either direction must be visible on the next read. Preserve the N64 watch, its behavior, and the N64 build.
+
+**Approved ownership:** per-file GE settings belong in the Bond save; machine-wide PC settings belong in `ge007.ini`. GE's original watch edits are *not* persisted on normal play (D349 below): **watch-made changes remain session-only**, while **PC-UI-made changes persist to the selected Bond file**. This is a deliberate port-side QoL divergence, not existing GE behavior. Do not register watch-backed settings as ini variables, copy watch values into config globals, or overwrite a newly loaded Bond file with stale ini values. A proposed PC master volume is separate: it multiplies the final output and does not replace the watch's Music/FX volumes.
+
+## Inventory and proposed rows
+
+Source of truth: `src/game/options.c` (`game_options_entries`, `cur_player_get/set_*`, `get_mTrack2Vol`/`set_mTrack2Vol`, `sub_GAME_7F0A91A0`), `src/game/file2.c:1246-1350` (per-folder serialization), and `port/src/input.c:~939` (forced control style). Audit exact getter/setter availability and initialization before implementing each row.
+
+| Watch control | PC presentation | Notes |
+|---|---|---|
+| Music / FX volume | Audio section, separate Music and FX sliders | GE range 0..32767, stored in the Bond save at 8-bit precision; use actual GE APIs, not an SDL channel gain in place of either. Master volume stays a distinct global row. |
+| Look up/down (reverse/upright), auto-aim, aim control (hold/toggle), sight on screen, look ahead, ammo on screen | Bond file / gameplay subsection, with GE-specific labels | These are the watch's `game_options_entries` and save bits. Watch look-up/down is distinct from PC MouseInvertY and PadLookInvertY: the independent inversions compose (XOR). Label/help text must explain the stacking; do not combine their stored values. |
+| Screen (Full/Wide/Cinema), Ratio (Normal/16:9) | Separate clearly marked GE presentation controls, if useful | Not PC window resolution/mode or `Video.NativeWidescreen`. Verify interactions with native widescreen/crop before exposing. |
+| Controller style / controller diagram | Defer pending input design | The diagram is not a setting. `inputComputePad(0)` currently reasserts Honey or Solitaire from `Input.NaturalPitch` every poll, including after save load or watch changes; `bondview.c` and multiplayer load also force Honey in some contexts. A naive style row would be immediately undone. Decide whether the watch selector should be informational, limited to supported PC mappings, or integrated with the port mapping; no row until this is reconciled. Dual-controller styles need their own decision. |
+
+This inventory is not permission to expose every field automatically. Especially do not silently merge identically named PC and GE toggles that have different input paths or persistence.
+
+### Persistence ground truth (D349)
+
+`fileSaveSettingsForFolder` (`src/game/file2.c:1246`) has one caller, `fileClearSavefileForFolder` (`:1379`), reached from the erase path. Normal watch edits change live values but do **not** write the file's `options`/`music_vol`/`sfx_vol` fields or EEPROM. `init_watch_at_start_of_stage` (`src/game/options.c:415`) calls `fileLoadSaveSettingsForSelectedFolder`, so the next stage reloads those fields and discards unsaved watch edits. This is a GE/N64 quirk, not a PC regression; Gate A should re-audit indirect writes before implementation and record any correction to D349.
+
+Thus a front-end row that edits only live watch state will be silently undone before gameplay. The maintainer approved **port-side per-file persistence of PC-UI changes**, without changing the N64 save format or the N64 watch's session-only behavior. Do not auto-persist edits made directly in the watch.
+
+## UI / data design
+
+1. Add a **watch-backed row type** to the existing shared row model, not another settings menu or fake config registration. Its read/write/availability callbacks operate on GE's real option API; existing config-backed rows continue to work unchanged. Keep enum labels, range/step and value formatting in the shared row table so F10 and the GE-styled screen cannot diverge.
+2. Use GE's existing getters/setters for **all eight proposed entries** (`src/game/options.c:526-598`) and both volume controls (`get_mTrack2Vol`/`set_mTrack2Vol`, `call_sndGetSfxSlotFirstNaturalVolume`/`sub_GAME_7F0A91A0`). For FX use the same game volume API as the watch, not an SDL channel gain. No `src/game` bridge or Rule-2 game-code edit is expected for these rows. Preserve the watch's side effects; persistence, if approved, is a separate port-side operation.
+3. **Threading is a design gate:** F10 input runs on the scheduler thread (`inputComputePad(0)`); the GE-styled screen and watch run on the game thread. Do not directly mutate game/watch state from the F10 thread merely because a getter or pointer is accessible. Route F10 writes as bounded requests to a safe game-thread point, and publish a safe, current snapshot for F10 rendering/reads, or establish an equivalently reviewed synchronization scheme. Cancel or retarget queued writes when the active folder/stage changes; never apply a write to the next folder by accident. Check audio/music initialization before **writing** Music/FX in the front end: the music getter reads a global, but the setters may touch not-yet-ready playback state.
+4. Make scope visible to the player: use a dedicated **Bond file** section/page in `MENU_PC_OPTIONS` for GE watch options, with an **explicit Bond-file chooser**; never trust `selected_folder_num` on that screen (frontoptions init even assigns it a fallback). F10 in-stage targets the active file with no chooser. **D354 supersedes the "do not silently choose folder 1" stance:** all non-stage contexts (options screen *and* F10 on file select) lazily default to *explicit pick > `selected_folder_num` > first valid folder* so the section works transparently; an explicit "Edit file" cycle (still including "none") always overrides, and a game-thread `fileBuildWriteNewSave(FOLDER1)` one-shot builds a blank file 1 when no valid save exists. Switching chooser folders must not change the game's active file. D350 reads saved fields directly without calling `fileLoadSettingsForFolder` (which would audibly change front-end music). Unvalidated/absent slots are skipped. Test new/blank files in a normal boot as well as the D299 `GE_STARTMENU` shortcut.
+5. **Approved port-side persistence:** resolve the actual save-slot pointer with `fileGetSaveForFoldernum(folder)`; `saves[folder]` is **not** generally the folder's physical slot (`fileWriteSave` requires a pointer into `saves[SAVESLOT1..SAVESLOTRAMROM)`). For F10, use a validated in-place path: serialize the live settings into a **temporary copy** with `fileSaveSettingsForFolder(&copy)`, then copy only the PC-UI-edited field/bit(s) into the real save-slot pointer and call `fileWriteSave(save)` with existing CRC/EEPROM handling. In the front end, where no GE player is active, merge only the selected field directly into the chosen saved record instead of loading it into live watch state. Retain `OPTION_CONTROLTYPE` from the real save: the port reasserts Honey/Solitaire every poll and must not overwrite stored controller style. This field-scoped merge also prevents a watch-only edit to a *different* field from piggybacking onto the next PC-UI save, preserving the approved session-only asymmetry. Validate the path against absent/free slots and ensure the live state belongs to **only** the chosen folder (do not load or copy values from a different folder). Never call `fileClearSavefileForFolder` as a generic settings save. Toggle/enum changes persist on value change; slider drags persist on release, not each detent. F10 requests must reach the correct game-thread/file target before write. The GE watch's own edits remain session-only. Test stage load, file switch, copy/erase, and restart for cross-file contamination; no N64 game-code changes. **Known erase edge:** GE's `fileClearSavefileForFolder` serializes *current* live settings into the reset file; after editing B, erasing A could copy B's live options into wiped A (also possible on N64 after watch edits). Document/test, do not change game code.
+6. For future per-section reset-to-defaults: ini rows reset from registered PC defaults; watch rows reset to **`BLANKSAVEDATA`/`DEFAULT_OPTIONS`** (`bondconstants.h:2151`, `file2.h:23`) for the selected file, not from a global ini snapshot. New saves start with Music/FX 0xFF (full volume) and auto-aim/sight/look-ahead/ammo enabled. Separate confirmation and persistence policy before wiring a button.
+
+## Sequence / review gates
+
+- **Gate A — behavior audit + D349:** re-verify the erase-only write and stage-start reload (including indirect save paths); record the ground-truth quirk, defaults, stored control-type preservation, erase cross-file edge and exact API for each row. Trace folder-to-physical-slot mapping, FX/music setter readiness, watch-to-gameplay consumers, composed inversion and the F10/game-thread boundary. Approved policy: explicit chooser + PC-UI edits persist; watch edits remain session-only.
+- **Gate B — foundation: IMPLEMENTED in D350**, including explicit file chooser, CRC guard, stage/file identity and thread-safe F10 command/snapshot path. D352 (review of `1303c0eb`) fixed the remaining robustness gaps: pending commands now survive stage transitions (hold-not-drop), the UI-thread chooser state is spinlocked with a front-screen guard, the queue coalesces to one pending command per field, and every silent no-op path logs a warning. Manual gamepad/mouse playtest still owed.
+- **Gate C — audio: ROWS IMPLEMENTED in D350**, Music/FX save path headless-verified. Watch↔F10 live and audible checks still owed. Global master gain is a separate, not-yet-implemented M3 item.
+- **Gate D — watch gameplay: ROWS IMPLEMENTED in D350** for six GE watch booleans; auto-aim and watch look-bit per-file saves headless-verified. Each watch/in-game effect and two-file isolation still need hands-on checks. Screen/Ratio remain a separate product decision.
+- **Gate E — control style and resets:** design decisions first, then separate work. Avoid exposing a control-style row that the port immediately overwrites. Do not make a global reset wipe per-file watch settings.
+
+## Acceptance checks
+
+- Watch changes show in both PC surfaces without reopening/restarting, and PC changes show in the watch; no extra watch-key values in `ge007.ini`.
+- With two Bond files, change Music/FX and a gameplay toggle in A via PC UI; switch to B, verify B retains its own values; return to A, start a stage, quit/restart and reload, verify A's values. Repeat an edit via F10 while in-stage. Drag sliders: only one save on release, not per detent. PC-UI persistence is a *port QoL test*, not a claim about N64; watch-only edits should still revert on stage reload. Check that stored controller-style bits survive PC saves and that file copy and erase retain GE behavior (including the erase cross-file edge above).
+- F10 changes are not lost or applied to another file across a stage/menu transition. Check full-range sliders, watch's save quantization, no unexpected audio spikes, and no race/crash on quit.
+- Menu layouts: use a dedicated Bond file section/page plus Audio; `MAX_PROWS=15` is a **per-page** cap in `frontoptions.c`, with `MAX_PAGES=8`; F10 scrolls. Check the 440x330 front-end page, F10 visible rows, mouse, keyboard, and real pad navigation; ASCII-only new text for region safety. Check NTSC headless captures, widescreen, golden gate, and PAL/JP build where possible (only NTSC ROM locally).
+- Build/link checks and the normal verification ritual after implementation. Document any game-side change as its own Rule-2 request before editing it.
+
+## Decisions and remaining scope
+
+- **Approved:** PC-UI edits persist per selected Bond file; watch-only edits stay session-only. The front screen gets an explicit file chooser; F10 uses the active file. Preserve stored controller type; toggles/enums save on change, slider drags on release. No `src/game` behavior change or N64 save-format change.
+- **Still separate product decisions:** whether/how to expose GE Screen/Ratio alongside PC video settings; whether to expose control style at all given the port's forced mapping (deferred); whether Bond-file reset needs its own confirmation rather than being bundled with global PC defaults.
+- **Landed 2026-09-27 (D352/D353, port-only):** bridge robustness fixes (D352) and the Turok-style row-table regrouping (D353: six sections — DISPLAY, GRAPHICS, BOND FILE, MOUSE / AIM, CONTROLLER, GAME; the music/FX sliders sit in BOND FILE; the page title annotates the selected file; `buildPages` overflow logs).
+- **Landed 2026-09-27 (D354, port-only):** front-end F10 routing + transparent default Bond-file selection (see item 4 above); in-stage F10 verified working by the `GE_WSPROBE` probe.
+- **Landed 2026-09-27 (D355, port-only):** the Music commit now also resyncs the in-stage BGM (track 1) via `musicTrack1ApplySeqpVol`, plus a once-per-activation resync on level entry; by-ear confirmed. N64 watch path unchanged.
+- **Landed 2026-09-27 (D356, port-only):** the settings regroup (plan `docs/dev/D356-SETTINGS-REGROUP-PLAN.md`): Turok-style pages renamed to functional sections (INPUT/GAMEPLAY/GRAPHICS/AUDIO/VIDEO, all below MAX_PROWS), the redundant N64-watch rows (`Bond.Look`, `Bond.AimControl`) commented out of the menu surface (keys + watch paths stay live, D181/D216 style), the `__HdrBond`/`__BondFile` rows retired for the front-only top save-file row, per-file sections annotated `"(File N)"` via the `saveScoped` flag, and the Turok reset rows replaced by a real per-section Reset-to-defaults (edge-triggered two-step arm->confirm within 3 s; watch rows -> BLANKSAVEDATA through the D352 commit path, ini rows -> the port's C initializers; `__Resolution` a documented exclusion). GE_WSPROBE_RESET front + in-stage probes headless-verified.
+- A standalone AUDIO section (master volume + the config-side volume keys) and per-section reset-to-defaults (Gate E) are the next settings-scope items; key rebinding stays Phase 4.

docs/dev/WIDESCREEN-FOV-PLAN.md

@@ -1,287 +0,0 @@
-# Widescreen & FOV Plan
-
-Status: **proposal, parked** — like `UNLOCKED-FPS-PLAN.md`, resume after audio
-work (project Phase 3). Research current as of this writing.
-
-Scope decision (agreed): **target exactly two display aspects — 4:3 and 16:9.**
-Arbitrary aspect ratios are TBD and out of scope; the window manager should
-snap/letterbox to one of the two rather than trying to serve anything else.
-
-Standard (agreed): **Option B (native 16:9 render, PD-parity) is the goal.**
-The PD PC port's widescreen architecture is the reference standard for this
-engine family. Option A (4:3-internal + stretch) remains an acceptable
-**case-by-case workaround** only where B proves impractical for a specific
-surface — each such fallback documented individually.
-
-## Problem
-
-At high resolutions (e.g. 4K) in a 16:9 window the game is disorienting. Root
-cause, confirmed in code: the port renders in *window-resolution space*. All
-320×240 logical screen coordinates are scaled per-axis by
-`RATIO_X = win_w/320`, `RATIO_Y = win_h/240` (`port/fast3d/gfx_pc.cpp:53-54`).
-In a 16:9 window everything — world geometry **and** HUD — is stretched 4/3
-horizontally: circles become ellipses, and the horizontal FOV balloons from
-~78° to ~91° while vertical stays 60°. That stretch is the disorientation.
-
-## Research findings
-
-### 1. The FOV model (where FOV lives)
-
-- Vertical FOV is a fixed 60° base: `FOV_Y_F` (`src/fr.h:137`); per-player
-  `fovy`/`aspect` fields default to 60 / `DEFAULT_ASPECT`
-  (`src/game/player.c:454-455`).
-- Setters: `viSetFovY` / `viSetAspect` / `viSetFov(fovx, fovy)`
-  (`src/fr.c:911-934`) → `guPerspectiveF(g_viProjectionMatrixF, …, fovy,
-  aspect, znear, zfar, 1.0f)` (`src/fr.c:718`).
-- **FOV is dynamic**: aim zoom rewrites fovy every frame via
-  `viSetFovY(g_CurrentPlayer->zoominfovy)` (`src/game/bondview2.c:3123`), and
-  the camera path resets fovy/aspect per frame
-  (`bondviewMovePlayerUpdateViewport`, `src/game/bondview2.c:7967-8034`).
-  ⇒ Any FOV option must be a *multiplicative correction composable with zoom*,
-  not an override of a constant.
-
-### 2. The game ships with a (stretch-based) 16:9 path
-
-This decomp contains a player-facing widescreen path from the original:
-options-menu **"Ratio": Normal / 16:9** (`GAME_OPTIONS_INDEX_RATIO`, string
-`OPTION_STR_23_169_LF`, `src/game/options.c:129`), save bit
-`OPTION_SCREENRATIO` (`src/game/file2.c:1266-1270, 1323`),
-`get/set_screen_ratio()` (`src/game/options.c:553-558`). When active, the
-camera sets `aspect = (vp_w/vp_h) × 0.75 × 16/9` (= viewport ratio × 4/3,
-`src/game/bondview2.c:8007-8034`) — the pre-distortion for a **4:3 render
-stretched to 16:9** (N64-out-4:3, TV stretches). HUD compensation exists for
-crosshair (`gunfire.c:6316-6318`, half-width ×0.75) and rocket aim
-(`gunfire.c:501`); EU-only extras need an NTSC audit.
-
-⇒ This path is exactly **Option A's** game-side machinery. It is *not* the
-PD standard (which renders native 16:9), so under Option B it stays dormant
-except as fallback.
-
-### 3. Current port rendering pipeline (what to build on)
-
-- Render happens at window size; an FBO path already exists and activates when
-  internal dims ≠ window dims or MSAA > 1 (`gfx_pc.cpp:3041-3115+`).
-- Native-res bookkeeping: `GE_NATIVE_W/H` = 640×480 (NTSC) / 640×400 (PAL)
-  (`port/src/video.c:40-44`); VI size requests clamp to ≤640
-  (`port/src/libultra.c:816`). Auto window defaults to 4:3
-  (`port/fast3d/gfx_sdl2.cpp:107`).
-
-### 4. fast3d EXT aspect commands — already present in GE's RSP
-
-GE's software RSP (adapted from PD's) implements Rare's PC-port extension
-geometry-mode commands `G_ASPECT_{LEFT,RIGHT,WIDE,CENTER}_EXT`
-(`gfx_pc.cpp:1954-1979`, decoder at `gfx_sp_extra_geometry_mode`), and
-`port/fast3d/gbiex.h` carries the `gSP…EXT` command macros. **The RSP side of
-the PD standard already works in this codebase**; only the game-code emission
-sites are missing.
-
-### 5. The PD standard (reference architecture — what Option B replicates)
-
-From the `pd_port` checkout (N64 PD had no widescreen; the port added it):
-
-1. **Projection aspect comes from the port**: `videoGetAspect()` returns the
-   real window aspect (`gfx_current_dimensions.aspect_ratio`,
-   `port/src/video.c:232-235`). Game code calls `viSetAspect(videoGetAspect())`
-   (e.g. `title.c:2495`; even `#define TITLE_ASPECT (videoGetAspect())`).
-   Native 16:9 projection ⇒ correct perspective, vertical FOV preserved.
-2. **Per-element screen-space corrections** where an element is positioned in
-   screen coords: `sightGetAdjustedX(x)`, `×(SCREEN_ASPECT / videoGetAspect())`
-   scalings (`sight.c:77,921`, `sky.c:2728+`, `menu.c:2332,4771`,
-   `player.c:3108`).
-3. **HUD alignment via the EXT commands**: screen-space draw segments wrapped
-   in `gSPSetExtraGeometryModeEXT(gdl, G_ASPECT_CENTER_EXT)` …
-   `gSPClearExtraGeometryModeEXT(…)`, all under `#ifndef PLATFORM_N64`. With
-   the mode active, fast3d scales 4:3-logical screen coords by the *native*
-   aspect and centers (or left/right-aligns) them in the wider window — no
-   distortion. PD scale: **52 emission sites across 10 game files** (sight,
-   hudmsg, bondgun, menu, radar, title, propobj, credits, activemenu,
-   game_1531a0).
-4. User-facing: vsync/framerate options + HUD-centering option
-   (`g_HudCenter` → `g_HudAlignModeL/R`, `port/src/main.c:77-83`).
-
-**M-87 PD-legacy-survey notes (`docs/dev/notes/PD-LEGACY-SURVEY.md`):**
-- **Overscan/safe-frame (candidate 2, deliberate divergence, recorded here):**
-  PD hardcodes its native viewport to 320×220 (`port/src/video.c:77-79`) — the
-  N64-on-a-TV visible area after ~20 lines top/bottom of overscan. **GE's port
-  renders the full 640×480/640×400 frame, no overscan crop** (`port/src/video.c:38-47`)
-  — a deliberate PC-default choice (nothing hidden, no HUD-clipping risk from a
-  TV-only limitation), not an oversight, and not something to "fix" toward PD's
-  behavior. Net effect: GE shows ~9% more vertical content than PD at the
-  equivalent native resolution. Revisit only if a `Video.SafeAreaOverlay` debug
-  knob is ever wanted to visualize the original TV-safe region.
-- **"Ratio" 4:3/16:9 option (candidate 3) — correction, M-87 review:** PD
-  deleted its N64-era per-player Ratio dropdown on PC (`options.c` forces
-  `SCREENRATIO_NORMAL` outside `PLATFORM_N64`). GE's equivalent (`SCREEN_RATIO_16_9`,
-  `get/set_screen_ratio`, `options.c:553-558`, persisted per-save, consumed by
-  the camera) is a live, functioning code path — but it's an old **anamorphic
-  stretch toggle**, not true wider-FOV rendering, and this doc's own **Open
-  Questions** (below) already flag the tension and lean the *other* way: leave
-  this legacy flag **dormant** and have a **separate, new, port-owned
-  `Video.Aspect` config** be Option B's actual trigger — the same
-  separation-of-concerns choice PD itself made (PD didn't repurpose its legacy
-  flag either). Repurposing the shipped save-flag to drive a brand-new render
-  path risks desync (existing saves silently gaining/missing the modern
-  feature, or the flag and `Video.Aspect` disagreeing). **Not yet decided**
-  ("Decide Phase 1" below) — correcting an earlier note here that overstated
-  this as settled.
-
-## Option B — the standard (native 16:9, PD-parity)
-
-### Architecture
-
-Render directly at the 16:9 window resolution. World: projection aspect =
-window aspect (vertical FOV preserved, no post-stretch). HUD/screen-space:
-4:3-logical coordinates mapped undistorted via the EXT aspect modes
-(centered by default; left/right alignment available à la PD). 4:3 windows:
-byte-identical to today.
-
-### Change inventory
-
-**Port layer (no rules issues):**
-- [ ] `videoGetAspect()` equivalent in `port/src/video.c` (return window
-      aspect; GE already tracks `gfx_current_dimensions.aspect_ratio`).
-- [ ] Window/aspect policy: `Video.Aspect` {4:3, 16:9}, snap on create/resize;
-      out-of-scope aspects → nearest + note (TBD).
-- [ ] Make `port/fast3d/gbiex.h` reachable from game TUs (include path or a
-      shim header) — build-system only.
-- [ ] HUD alignment mode plumbing if we adopt PD's center/wide option
-      (`g_HudAlignModeL/R` pattern) — decide in Phase 1; default = centered.
-
-**Game code (exception class — see below):**
-- **(a) Projection aspect path.** `bondviewMovePlayerUpdateViewport`
-      (`bondview2.c:8007-8034`): under PORT + 16:9, use window aspect instead
-      of the ×4/3 stretch formula. Plus the menu/title/briefing call sites
-      `viSetFovY(FOV_Y_F); viSetAspect(ASPECT_RATIO_SD)` (`front.c` — ~7+
-      sites; enumerate in Phase 1) → PD pattern `viSetAspect(videoGetAspect())`.
-- **(b) HUD / screen-space draw sites.** Audit + wrap with EXT aspect modes
-      and/or per-element corrections, per surface: gameplay HUD (crosshair —
-      replaces the existing ×0.75 compensation; ammo/timer/text via
-      `textrelated.c`), menus (`front.c`), title/briefing/credits, letterbox
-      bars (`fr.c` gDPFillRectangle calls). GE's known screen-space emitters:
-      `front.c`, `textrelated.c`, `gunfire.c`, `bondwalk2.c` (initial grep;
-      Phase 1 completes the audit). Expect PD-comparable scale (~10 files),
-      possibly less.
-- **(c) Anything the audit surfaces** (e.g. mouse→screen mapping for menus,
-      cutscene camera framing) — each item logged individually.
-
-### Rule #2 exception framing (needs explicit sign-off to start Phase 2)
-
-This is a behavior-affecting game-code edit class, outside the ABI-only D3x
-exception. The case for granting it:
-
-1. **Direct sister-engine precedent**: PD's port made exactly these edits on
-   the same Rare engine/fast3d; the project designates PD as standing
-   reference for port patterns. We replicate a proven, bounded change class,
-   not inventing one.
-2. **Bounded and gated**: every edit is `#ifdef PORT` (and where sensible
-   runtime aspect-gated) so the N64 build and the 4:3 default path stay
-   byte-identical; golden/determinism tests unaffected at 4:3.
-3. **The decomp already contains** both a shipped 16:9 branch and `#ifdef
-   PORT` precedents in game files — the pattern is not foreign to this tree.
-
-Conditions: explicit user sign-off before Phase 2; each change (or tight
-cluster) gets a findings.md entry with §F index label citing the PD analogue;
-4:3 byte-identity verified per phase; any edit that would alter *sim* behavior
-(not just presentation) stops the work and comes back for review.
-
-### Fallback (case-by-case, documented)
-
-If the Phase 1 audit shows a specific surface is disproportionately costly or
-can't be made clean under B (candidate: complex cutscene framing), that
-surface may fall back to **Option A** — 4:3-internal render + edge-to-edge
-stretch using the game's shipped `SCREEN_RATIO_16_9` path (`set_screen_ratio`
-is an existing API; FBO+blit infra exists) — recorded as a finding with the
-reason. Whole-feature fallback to A only if B fails verification overall.
-
-## FOV adjustment design (port-only, applies to both options)
-
-- **Hook: software RSP projection post-scale.** Wherever the RSP applies the
-  uploaded projection matrix, scale its vertical row by
-  `tan(fov_orig/2) / tan(fov_adj/2)`. Zoom rewrites the matrix every frame, so
-  post-scaling whatever arrives composes with aim zoom for free. No game code.
-- Rejected: editing `viSetFovY` call sites (game code); writing
-  `g_ViBackData` from the port (racy).
-- UI: `Video.FovScale` (percent of original vertical FOV, e.g. 50–150),
-  default 100 = byte-identical to today.
-
-## Phases
-
-### Phase 0 — Verification research (port-only, read-mostly)
-
-- [ ] Playtest the in-game Ratio option as-is on PC; document + screenshot
-      what the shipped stretch path does under the current pipeline.
-- [ ] Measure baseline FOVs (4:3 and current 16:9-stretch) from the projection
-      matrix or a calibration render; record numbers.
-- [ ] Confirm `gbiex.h` EXT commands round-trip through GE's RSP with a test
-      DL (they should — decoder exists).
-- [ ] Audit EU-only aspect constants (`g_GunSightAspectRatio`,
-      `EU_CAMERA_8003642C_ASPECT`) for NTSC/PAL effect.
-- [ ] Record a Dxxx finding consolidating baselines.
-
-### Phase 1 — Port foundation + full change audit (port-only)
-
-- [ ] `videoGetAspect()`, window/aspect policy, gbiex.h include path.
-- [ ] Complete the screen-space draw-site audit for inventory item (b): every
-      emitter, its coordinate assumptions, proposed wrap/correction, PD
-      analogue cited. Output = the signed change list for Phase 2/3.
-- [ ] Decide HUD alignment default (centered vs PD's center/wide option).
-
-### Phase 2 — Projection aspect (game-code exception class, small wave)
-
-- [ ] Item (a): camera path + front.c call sites, `#ifdef PORT`-gated.
-- [ ] Verify: world perspective correct at 16:9 (FOV measurement vs Phase 0),
-      aim zoom composes, 4:3 byte-identical.
-
-### Phase 3 — HUD alignment wave (game-code exception class)
-
-- [ ] Item (b), per surface in order: gameplay HUD → menus →
-      title/briefing/credits → letterbox/misc. Each surface: change, visual
-      verification at 4:3 + 16:9, finding entry. Fallback-to-A decisions
-      happen here, per surface, with documented reason.
-
-### Phase 4 — FOV slider (port-only) — **LANDED (M-83, D211)**
-
-- [x] RSP projection post-scale (`gfx_apply_fov_scale()` in
-      `port/fast3d/gfx_pc.cpp`, load-path only); `Video.FovScale` config
-      (percent of vertical FOV, 50–150, default 100 = byte-identical) + F10
-      overlay row. Perspective-only (ortho/HUD untouched); columns 0+1 scaled
-      together so aspect is preserved. Build clean, `bunker1` no-op confirmed.
-- [ ] Owed: interactive eyeball of composition with aim-zoom at scale ≠ 100.
-
-This phase does **not** depend on the Phase 2/3 game-code exception — it
-shipped standalone ahead of the rest of the plan.
-
-### Phase 5 — Verification & sign-off
-
-- [ ] FOV measurements per mode/scale vs Phase 0 baselines.
-- [ ] Full HUD pass at 4:3 + 16:9; cosmetics → `GRAPHICS-BACKLOG.md`.
-- [ ] 4K performance check; MSAA interaction; config persistence; screenshots.
-- [ ] `./build-pc.sh` + `/linkcheck`; findings complete with §F index labels.
-
-## Open questions
-
-- HUD alignment UX: always-centered (simple) vs PD's center/wide option
-  (more faithful, more surface area). Decide Phase 1.
-- In-game Ratio menu entry under Option B: the shipped option means "stretch
-  mode" — keep it as the *fallback* trigger, hide it, or repurpose? Decide
-  Phase 1 (leaning: leave dormant; port config owns display mode).
-- Mouse/menu coordinate mapping at 16:9 (PD had `videoGetAspect()`-scaled
-  mouse math in menu.c) — confirm GE's menu input path needs the same.
-- Ordering vs `UNLOCKED-FPS-PLAN.md`: both parked behind audio; B renders
-  native so the FPS plan's present-stage duplication slots in unchanged.
-  Decide order when audio lands.
-- PAL: `GE_NATIVE` 640×400 bookkeeping — confirm aspect math per region.
-- Split-screen viewports under 16:9 — likely out of scope for PC; note and close.
-- **M-87 QoL ask (user, not critical, backlogged):** expose `Video.FovScale` as
-  a real horizontal-or-vertical **degree** value instead of the current
-  percent-of-original-vertical-FOV scale (D211) — the "50–150%" knob doesn't
-  tell the user what degree FOV they're actually getting. Needs: pick a
-  convention (report vertical, since that's what `frFovY` actually is post-D211
-  refix — `fr.c:737`) and either (a) relabel the F10 row + INI value as degrees
-  directly (`frFovY = clamp(requestedDeg, ~24°, 160°)`, drop the percent
-  multiply), or (b) keep percent internally but show the *computed* degree
-  value live in the F10 overlay/INI comment for transparency. (a) is cleaner
-  and removes a level of indirection; check whether anything else reads
-  `Video.FovScale` as a percent before renaming the key (search besides
-  `fr.c`/`video.c`). Cosmetic/UX only, no render-path change beyond the
-  input unit.

docs/dev/agentic-development.md

@@ -3,7 +3,7 @@ title: Agentic Development
 description: A case study in two AI coding agents porting a Nintendo 64 game to PC; the setup, timeline, handoff workflow, and an honest assessment of what worked.
 ---
 
-# Agentic development: two AI coding agents porting GoldenEye 007
+## Agentic development: two AI coding agents porting GoldenEye 007
 
 *How this port was actually built: a local open-weight model (Qwen 3.8 on a
 single RTX 5090) and a hosted frontier model (Claude / Claude Code) handing
@@ -11,6 +11,10 @@ work back and forth through shared written notes, under one person's
 part-time direction. The goal, the setup, the timeline, and an honest read on
 what did and didn't work.*
 
+> *Snapshot as of the v0.3.0 milestone (20 Sep 2026; findings through D321).
+> v0.4.0 (28 Sep) extended the timeline with the options/input work -- the
+> README's Background section carries the final project numbers.*
+
 ## Contents
 
 - [Why this project exists](#why-this-project-exists)
@@ -62,13 +66,13 @@ reserved for the bugs that needed the most reasoning held at once; the same
 
 ## Timeline
 
-All dates from this repository's own commit history (August 2026).
+All dates from this repository's own commit history (August–September 2026).
 
 ```mermaid
 gantt
     dateFormat YYYY-MM-DD
     axisFormat %b %d
-    title GoldenEye 007 PC port; from fork to playable front end
+    title GoldenEye 007 PC port; from fork to v0.3.0
     section Local model - Qwen 3.8 via pi
     Fork + PC-port scaffolding            :m1, 2026-08-16, 1d
     Full compile + link (~230 TUs)        :m2, 2026-08-20, 1d
@@ -84,6 +88,11 @@ gantt
     SDL input layer (kbd/mouse/gamepad)   :2026-08-29, 1d
     Front-end flow (menu to briefing to start) :m7, 2026-08-30, 1d
     File-backed EEPROM saves              :2026-08-31, 1d
+    section Month one - front end to v0.3.0
+    Audio mixer (music + SFX)              :2026-09-02, 7d
+    Steam Deck hardening + F10 overlay QoL :2026-09-14, 3d
+    Final fix sweep (D309-D321) + release review :2026-09-18, 3d
+    v0.3.0 released (full campaign playtested) :milestone, 2026-09-20, 0d
 ```
 
 - **Day 0** (16 Aug): repository forked, PC-port scaffolding added.
@@ -97,50 +106,60 @@ gantt
   unattended play window without crashing.**
 - **Day 14** (30–31 Aug): front end playable end to end (menu → mission
   select → difficulty → briefing → start); file-backed saves.
+- **Day 35** (20 Sep): **v0.3.0 released** — the full campaign playtested
+  end to end at Agent difficulty, audio complete, bundles for Windows,
+  Linux and Steam Deck.
 
 So roughly **two weeks**, one person part-time, to take a decompilation from
 "builds an N64 ROM" to "boots on desktop, renders every solo level, playable
-through the front end into the early game"; with audio and a set of cosmetic
-issues still outstanding.
+through the front end into the early game". The rest of month one (29 Aug –
+20 Sep) took it from there to a public release: the 21-level sweep to
+full-campaign completion, the audio mixer, input and Steam Deck polish,
+widescreen FOV scaling, and the v0.3.0 bundles — with a set of cosmetic
+issues documented rather than outstanding.
 
 ## By the numbers
 
 | | |
 |---|---|
-| Calendar time | 26 days (17 Aug – 11 Sep 2026), one person part-time |
-| Commits on the port | ~430 |
-| Root-caused bugs logged | `D1`–`D226` in [`findings.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/findings.md), 116 still-listed entries (some labels later merged or withdrawn) |
-| Handoff sessions | 89+ (`M-2` … `M-89`, and counting) |
-| Game-source files given `#ifdef PORT` ABI edits | 67 files, ~305 blocks |
-| New port-layer / tooling files | ~114 |
-| Port layer | ~21,900 lines C/C++ (`port/`) |
-| PC asset-conversion tooling | ~7,050 lines Python (`tools_pc/`) |
-| Outcome | intro + all 21 solo missions render and are crash-free, front end playable, in-level SFX + menu/intro music play; in-level music and full-campaign completion re-confirmation still owed |
+| Calendar time | 36 days (16 Aug – 20 Sep 2026), one person part-time |
+| Commits on the port | ~835 |
+| Root-caused bugs logged | `D1`–`D321` in [`findings.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/findings.md), 199 tracked entries in the index (some labels later merged or withdrawn) |
+| Handoff sessions | 190+ (`M-2` … `M-192`, and counting) |
+| Game-source files given `#ifdef PORT` ABI edits | 71 files, ~385 blocks |
+| New port-layer / tooling files | ~119 |
+| Port layer | ~24,450 lines C/C++ (`port/`) |
+| PC asset-conversion tooling | ~7,180 lines Python (`tools_pc/`) |
+| Outcome | **v0.3.0 released**: full campaign playable end to end (all 21 missions playtested at Agent difficulty) at a steady 60 fps, full audio (music + SFX), file-backed saves; Windows, Linux and Steam Deck; known cosmetic defects documented in the finding log |
 
 ### Commit velocity
 
 ```mermaid
 xychart-beta
-    title "Commits per day"
-    x-axis ["8/16", "8/17", "8/20", "8/21", "8/22", "8/23", "8/24", "8/27", "8/28", "8/29", "8/30", "8/31", "9/1"]
-    y-axis "commits" 0 --> 60
-    bar [1, 2, 2, 6, 9, 2, 4, 7, 57, 39, 39, 46, 9]
+    title "Commits per week (week start)"
+    x-axis ["8/16", "8/23", "8/30", "9/6", "9/13", "9/20"]
+    y-axis "commits" 0 --> 250
+    bar [20, 109, 203, 141, 220, 6]
 ```
 
-Days with no commits are omitted. The 8/25–8/26 gap is between phases; the
-step up from 8/28 onward is the collaborative phase in full swing, including
-the parallel multi-agent "bursts" used near the end.
+Weekly totals (the final week is release day only). The step up from the
+8/23 week onward is the collaborative phase in full swing, including the
+parallel multi-agent "bursts"; the 9/13–9/19 week peaks on a single-day
+84-commit burst (9/15) when the Steam Deck playtest-feedback batch landed
+at once.
 
 ### Who did what
 
 ```mermaid
-pie showData title "Commits by agent (raw count)"
+pie showData title "Commits by agent (raw count, snapshot through early September)"
     "Claude" : 161
     "Local model (Qwen 3.8 / pi)" : 62
 ```
 
 (Phase A, the first 26 commits, to 24 Aug, was entirely the local model,
-solo; from 27 Aug on the two agents worked in parallel.)
+solo; from 27 Aug on the two agents worked in parallel. The raw tally was
+not re-run for the final third of the project; treat the milestone-weighted
+estimate below as the better number.)
 
 | Milestone / workstream | Primary agent | Weight |
 |---|---|---|
@@ -183,7 +202,7 @@ result worth taking away.
 This is the part worth paying attention to.
 
 ```mermaid
-flowchart LR
+flowchart TD
     H["Human: direction, integration,<br/>build + playtest verification"]
     C["Claude / Claude Code<br/>frontier, hosted"]
     Q["Qwen 3.8 via pi<br/>open-weight, local RTX 5090"]
@@ -208,9 +227,11 @@ let them substitute for each other:
    usage limit mid-problem, the local model picked the task up from the
    HANDOFF state and continued; when the local model hit a bug that needed
    deeper structural reasoning, it wrote up where it was and Claude took over.
-2. **`findings.md`**; the chronological finding log. 162 numbered entries,
-   each a root cause with `file:line` evidence and the fix. New agents (either
-   model) are pointed at the relevant entries before they start.
+2. **`findings.md`**; the chronological finding log. 321 numbered `D`
+   entries by v0.3.0 (199 tracked in the index; some labels merged or
+   withdrawn), each a root cause with `file:line` evidence and the fix. New
+   agents (either model) are pointed at the relevant entries before they
+   start.
 3. **`porting-notes.md`**; the append-only "recurring bug classes" file. The
    single highest-leverage artifact: it stopped both models from
    re-deriving the same class of N64→PC bug over and over.
@@ -262,7 +283,8 @@ Honest notes, for anyone weighing whether this transfers.
   to Opus 5. Each tier earned its place on the problems the tier below it
   couldn't close.
 
-**Still outstanding** (parked below crash/level work): audio is not
-implemented; several front-end 3D transforms and some text rendering are
-wrong. See
+**Still outstanding** (the v0.3.0 known-issues list): cosmetic rendering
+defects (particle colours, Surface 1 billboard trees, front-end logos, water
+seam), stretched-not-native widescreen, PAL/JP support, a controller
+rebinding UI, and macOS/ARM builds. See the README's Status section and
 [`GRAPHICS-BACKLOG.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/GRAPHICS-BACKLOG.md).

docs/dev/findings-index.csv

@@ -7,137 +7,281 @@ D43-D50,RESOLVED,"model-file loading → offline sidecar ""Plan B"" (d43_emit.py
 D51-D58,RESOLVED,"font pixeldata, osGetCount tick rate, model RW pools, cseq BE header, synth slots, RLE menu bg, watch raw offsets, gun-barrel DL",resolved
 D59-D68,RESOLVED,"intro render: blood-RLE clobber, DMA validate, OSMesgQueue, HEADS/BODIES sentinels, romCopy width, image_entry, Globalimagetable BE→LE",resolved
 D70-D74,RESOLVED,"intro-logo pixels: C-array bswap, UV path, sinf/cosf DVAL(), texture-import truncation",resolved
-D75,OPEN,front-end 3D model transforms (D77 audio split out below —,"OPEN (parked). M-32 triage (see §F ""D75 ADDENDUM""):"
-D76 · D164,PROPOSED,disclaimer/legal screen only draws line 1 —,fix proposed (not applied —
+D75,PARTIAL,front-end 3D model transforms (D77 audio split out below —,PARTIAL (M-197 fixed the logo texture blobs; v0.4.0 campaign 2026-09-28:
+D76 · D164,FIXED,Legal screen only draws line 1 —,"FIXED — this row and the ## D164 entry below were stale; the proposed one-line #ifdef PORT fix was actually committed 8dfc578f4 (2026-08-31), well before this correction (2026-09-18)."
 D159,FIXED,"front-end wallet-Bond photo ""interlaced""/combed (RC1 / D149) —",FIXED (#ifdef PORT no-op the swap in image.c)
 D161,FIXED,Depot (-level_30) ceiling = bright-blue speckle + radial rays (B2).,FIXED (port/fast3d/gfx_pc.cpp)
-D165 · D166,FIXED,"input-layer polish (M-31, port-only, port/src/input.c):",FIXED
-D180 · D181,PARTIAL,"native-PC input pass (QoL run, qol/native-pc-input-menu):","LANDED, config-gated, feel-checks owed"
-D186,PARTIAL,"Video.FpsCap throttles the sim, not just presentation (M-39 diag, M-42 clamp).","CLAMP LANDED (port/fast3d/gfx_sdl2.cpp, port/src/video.c); real fix owed"
+D165 · D166,FIXED,"Input-layer polish (M-31, port-only):",FIXED
+D180 · D181,FIXED,Native-PC input pass (QoL run):,FIXED (2026-09-26 bookkeeping:
+D186,OPEN,"Video.FpsCap throttles the sim, not just presentation (M-39 diag, M-42 clamp).","OPEN (2026-09-26, user direction:"
 D187,FIXED,"HUD ammo-type/weapon icon vanished at -O2 (M-46 root-cause, M-47 fix + verify).","FIXED (src/game/gunfire.c, #ifdef AVOID_UB); PR #19"
 D188,FIXED,Linux -O2 boot crash:,"FIXED (src/libultrare/libc/xprintf.c, src/sprintf.c, #ifdef PORT); PR #22"
 D189,FIXED,Linux -fstack-protector aborts on the decomp's latent stack-buffer overruns (M-48) —,"FIXED (CMakeLists.txt, src/game/stan.c #ifdef PORT); PR #23"
-D190,?,"Linux -level_45 SIGSEGV at load in add_ptr_to_objective (objective.c:64) (M-48, open).","CLOSED — not a port bug; level 45 is MP-only and has no solo setup file in the ROM (root-caused M-105, reproduced on Windows)."
-D191,FIXED,Windows -O2 release-bundle crash:,FIXED + PLAYTEST-VERIFIED (M-79).
-D193,FIXED,NPC AI locomotion is too slow —,FIXED + user-playtest-verified (M-81) —
-D194,PARTIAL,Mouse input needs another tuning pass —,PARTIAL — M-120 human playtest:
-D195,FIXED,"Transparency / alpha surfaces broken on Control (M-49, user playtest) —","FIXED (port/fast3d/gfx_pc.cpp, gfx_sp_vertex) —"
-D197,?,"Character face/head textures wrap around the head, seen on Silo (M-49, user playtest).",CLOSED — user playtest v0.2.0-pre
+D190,CLOSED,"Linux -level_45 SIGSEGV at load in add_ptr_to_objective (objective.c:64) (M-48, open).","CLOSED — not a port bug; level 45 is MP-only and has no solo setup file in the ROM (root-caused M-105, reproduced on Windows)."
+D191,FIXED,Windows -O2 release-bundle crash:,FIXED + PLAYTEST-VERIFIED (M-79).…
+D193,FIXED,NPC AI locomotion is too slow —,FIXED + user-playtest-verified (M-81) —…
+D194,FIXED,Mouse input needs another tuning pass —,FIXED (2026-09-26: user reports the v0.3.0→v0.4.0 mouse changes feel solid and glitch-free; code-side validation owed).
+D195,FIXED,"Transparency / alpha surfaces broken on Control (M-49, user playtest) —","FIXED (port/fast3d/gfx_pc.cpp, gfx_sp_vertex) —…"
+D197,CLOSED,"Character face/head textures wrap around the head, seen on Silo (M-49, user playtest).",CLOSED — user playtest v0.2.0-pre
 D198,FIXED,alAdpcmPull/_decodeChunk used K0_TO_PHYS (an unconditional & 0x1FFFFFFF mask) on 64-bit heap pointers (src/libultra/audio/load.c).,FIXED (src/libultra/audio/load.c) —
-D199,PARTIAL,Phase-3 software audio mixer:,"LANDED (port/src/mixer.c, port/include/mixer.h, include/PR/abi.h) —"
+D199,FIXED,Phase-3 software audio mixer:,FIXED (2026-09-26 bookkeeping:
 D200,FIXED,-level_09 segfault: reverb's ALDelay.input/output are u32 —,FIXED — 5-line cast in reverb.c (this session)
-D196,FIXED,"OS mouse cursor stays visible after closing the F10 options overlay in click-to-lock mode (M-49, user playtest).","FIXED (6e758f1d, merged to main) —"
-D192,?,Front-end mission/level-select grid pointer still can't reach the outer cells —,"CLOSED — the buggy mode 0 was removed entirely in the v0.2.0 prep pass (see D239); click-to-lock is now the only capture mode, so the unreachable-cells path no longer exists"
-D221,FIXED,SELECT FILE screen: the mouse hit-box for a file slot is vertically offset from its visible box —,FIXED (M-91) — root cause was NOT a coordinate/origin mismatch:
+D196,FIXED,"OS mouse cursor stays visible after closing the F10 options overlay in click-to-lock mode (M-49, user playtest).","FIXED (6e758f1d, merged to main) —…"
+D192,CLOSED,Front-end mission/level-select grid pointer still can't reach the outer cells —,"CLOSED — the buggy mode 0 was removed entirely in the v0.2.0 prep pass (see D239); click-to-lock is now the only capture mode, so the unreachable-cells path no longer exists"
+D221,FIXED,SELECT FILE mouse hit-box offset —,"FIXED (M-91) — explicit {min,max} coord2d pairs under #ifdef PORT; human mouse-playtest confirmed."
 D222,FIXED,High Video.FovScale breaks culling —,"FIXED, awaiting visual verification (M-121)."
-D223,FIXED,QoL ask: mouse-wheel weapon cycling should be directional like a normal PC shooter —,"FIXED (M-105, port/src/input.c) —"
-D224,FIXED,"QoL gap (M-87, from a PD-PC-port survey):","DEPRIORITIZED (M-87, user call)."
-D225,OPEN,"Dev-tooling QoL (M-87, user ask):","OPEN — root-caused, not implemented."
-D226,OPEN,"QoL ask: player-adjustable HUD scale for the ammo counter, bottom-left pickup/item status text, and top-of-screen dialogue/subtitle text.","OPEN — root cause / call sites identified, not designed or implemented."
+D223,FIXED,QoL ask: mouse-wheel weapon cycling should be directional like a normal PC shooter —,"FIXED (M-105, port/src/input.c) —…"
+D224,PARTIAL,"QoL gap (M-87, from a PD-PC-port survey):","LANDED via D401 (2026-09-27, re-promoted from DEPRIORITIZED)."
+D225,FIXED,"Dev-tooling QoL (M-87, user ask):","FIXED (2026-09-18) — GE_DEBUG_UNLOCKALL=1 short-circuits fileGetIsCheatUnlocked() (src/game/file2.c, #ifdef PORT, cached getenv) to always return TRUE; default off, no save mutation."
+D226,FIXED,"QoL ask: player-adjustable HUD scale for the ammo counter, bottom-left pickup/item status text, and top-of-screen dialogue/subtitle text.","FIXED (2026-09-24): Game.HudScale 75–150% (user-verified, capped at 150) via fast3d G_HUDSCALE_EXT rect scaling about per-element anchors; dialogue/bottom messages width-capped."
 D227,FIXED,Sky renders as two independently-moving halves —,"FIXED (M-100b, PR #43) —"
-D229,FIXED,"Water on IsWater levels renders green and pulses blue<->green on an interval (M-101, user playtest, Frigate -level_26; Surface 2 also an IsWater level).",FIXED (port-layer) — root cause:
-D230,OPEN,In-level music quality:,"OPEN — static-analysis pass done (M-108), not runtime-confirmed."
-D233,FIXED,All levels (intermittent):,"FIXED (port/fast3d/gfx_pc.cpp, gfx_sp_tri1) —"
-D234,FIXED,"Dam: guard towers along the dam structure invisible except the first one (M-106, user QA report).",VISUALLY VERIFIED FIXED (M-108) —
-D244,OPEN,Self-hosted CI runner (corpyvt6agent01) link failure:,"OPEN, not yet fixed. Next:"
-D228,FIXED,AK47 (and other) weapon models still show WHITE missing-texture patches after D217's texpool-alignment fix —,"FIXED (port/fast3d/gfx_pc.cpp, palette_to_rgba32) —"
-D204,FIXED,PC audio ran ~2 % below real time permanently:,"FIXED (port/src/audio.c, port/src/libultra.c, port/include/audio.h) —"
-D203,?,"Steam Deck (SteamOS, x86_64 Linux) v0.1.0 release bundle:",CLOSED — root cause + fix in D253.
+D229,FIXED,"IsWater-level water renders green, pulses blue<->green (M-101; Frigate -level_26).","FIXED (port-layer) — ZLIB+CI8 water image now imports via the CI8 palette path (gfx_pc.cpp); Frigate verified live (""looks better""); sweep + Surface 2 by-eye still owed."
+D230,FIXED,In-level music quality:,"FIXED (M-121, v0.2.0) —"
+D231,CLOSED,"QoL batch: mute-on-focus-loss + screenshot-hotkey productization (M-105, roadmap Tier 3, port-only).","CLOSED — PARKED/DEPRIORITIZED (user, 2026-09-25)."
+D233,FIXED,All levels (intermittent):,"FIXED (port/fast3d/gfx_pc.cpp, gfx_sp_tri1) —…"
+D234,FIXED,"Dam: guard towers along the dam structure invisible except the first one (M-106, user QA report).",VISUALLY VERIFIED FIXED (M-108) —…
+D244,OPEN,Self-hosted CI runner (corpyvt6agent01) link failure:,"OPEN, not yet fixed. Next…"
+D228,FIXED,AK47 white missing-texture patches after D217's texpool fix —,"FIXED (port/fast3d/gfx_pc.cpp, palette_to_rgba32) —"
+D204,FIXED,PC audio ran ~2 % below real time permanently (AI feedback loop's 3 ms setpoint vs PC jitter).,"FIXED (port/src/audio.c, port/src/libultra.c, port/include/audio.h) —"
+D203,CLOSED,"Steam Deck (SteamOS, x86_64 Linux) v0.1.0 release bundle:",CLOSED — root cause + fix in D253.
 D201,FIXED,"src/libultra/audio/bnkf.c bank/instrument/sound/wavetable relocation offsets were s32, truncating the real 64-bit base pointer.",FIXED (src/libultra/audio/bnkf.c) —
-D202,RESOLVED,"Silenced PPK plays a ""slap"" instead of a gunshot, PLUS user reports broader real-time audio corruption (M-52 → M-59 → REOPENED M-60 → M-61/M-62 closed the data…",ROOT CAUSE ESTABLISHED (M-66); DISPOSITION C IMPLEMENTED + MEASURED (M-66b) —
-D206,FIXED,PC played every SFX one bank slot too high —,"FIXED (M-76, src/snd.c:1001, #ifdef PORT → soundArray[soundIndex - 1], N64 line verbatim under #else)."
-D207,PROPOSED,Alarm klaxon starves combat SFX and (per user) doesn't recover after it stops —,MONITORING (M-77c: user reports the alarm is acceptable in play after D206; no fix shipped) —
+D202,FIXED,"Silenced PPK ""slap"" + broader real-time mixer corruption (M-52→M-67).","FIXED (2026-09-26, user by-ear:"
+D206,FIXED,PC played every SFX one bank slot too high —,"FIXED (M-76, src/snd.c:1001, #ifdef PORT) —"
+D207,FIXED,"Alarm klaxon starves combat SFX and doesn't recover after it stops (surfaced by D206, M-77).",MONITORING — user 2026-09-26:
 D208,FIXED,Player weapon-fire sound goes permanently silent mid-firefight (all other SFX unaffected) —,FIXED + user playtest-verified (M-78d) —
 D209,FIXED,Every AI character in the game is locked to a *walk* animation regardless of the speed the ailist commands —,FIXED + user-playtest-verified (M-81).
-D210,FIXED,chrToPatrol() leaves act_patrol.lastvisible60 uninitialised on PC —,"FIXED (chraction.c:3872, #ifdef PORT → self->act_patrol.lastvisible60 = -1;, N64 line under #else)."
-D205,RESOLVED,PC plays wrong/extra SFX for gameplay events the user can A/B against N64:,CLOSED (M-78) — root cause was D206; all four symptoms resolved + user-confirmed by ear vs N64.
+D210,FIXED,chrToPatrol() leaves act_patrol.lastvisible60 uninitialised on PC —,"FIXED (chraction.c:3872, #ifdef PORT → self->act_patrol.lastvisible60 = -1;, N64 line under #else).…"
+D205,CLOSED,"PC plays wrong/extra SFX for gameplay events (gunfire slap layer, explosion→scream, armour pickup, melee→Klobb idx 106) —",CLOSED (M-78) — root cause was D206; all four symptoms resolved + user-confirmed by ear.
 D152+,FIXED,D152 addendum (M-31):,"FIXED (src/snd.c, port/src/libultra.c, #ifdef PORT) —"
 D168,FIXED,GE_PCDUMP / F12 PPM captures were vertically flipped —,FIXED (port/fast3d/gfx_opengl.cpp); D114 / D116 reclassified as capture-orientation artifacts (below).
 D169,FIXED,Front-end mouse pointer can't reach the outer cells of the mission/level-select grid —,"FIXED (M-33, port/src/input.c, port-only, no #ifdef PORT)."
 D178,FIXED,Pre-mission briefing screen:,FIXED (M-36) — high confidence
-D175,OPEN,In-game stutter / brief hang during normal play (user QA report):,"OPEN — observed, not investigated"
-D176,FIXED,"Surface exterior renders wrong (-level_36), two independent defects.","(a) ""scrolls too fast/tiles too visibly"" ROOT-CAUSED + FIXED (see ""D176(a) —"
+D175,CLOSED,In-game stutter / brief hang during normal play —,"CLOSED (v0.4.0 campaign sign-off 2026-09-28, user:"
+D176,FIXED,"Surface exterior renders wrong (-level_36), two independent defects.","(a) scroll-speed FIXED (fidelity pass; HIGH confidence on root cause, MODERATE on N64 parity); M-93 playtest + M-98 Defect-2 starburst screenshot in the sections."
 D177,FIXED,Ladders non-functional —,FIXED (M-36) — high confidence; interactive climb test owed
-D172,FIXED,"Bullet-impact / blood / spark particles render magenta or cyan instead of dark red (M-82, ROOT CAUSE FOUND + FIXED).",FIXED (port/fast3d/gfx_pc.cpp gfx_lod_tile_offset):
-D174,OPEN,"""No blood effect"" (user QA report).",OPEN — observed; first step = BUNKER1 firefight with regenerated sidecars
-D183,OPEN,"M-36 Family A (""texture line/pitch shear"") is DISPROVEN for the Surface repro (-level_36).",Hypothesis DISPROVEN + diagnostics shipped; D176(b)/D182(2) still OPEN
-D173,OPEN,Third-person Bond model spawns too high (user QA report):,"OPEN — observed, not investigated."
+D172,FIXED,"Bullet-impact / blood / spark particles render magenta or cyan instead of dark red (M-82, ROOT CAUSE FOUND + FIXED).",FIXED (port/fast3d/gfx_pc.cpp gfx_lod_tile_offset)…
+D174,CLOSED,"""No blood effect"" (user QA report).","CLOSED — faithful (2026-09-26, user side-by-side on 1964:"
+D183,CLOSED,"M-36 Family A (""texture line/pitch shear"") is DISPROVEN for the Surface repro (-level_36).","CLOSED (2026-09-26, user-approved:"
+D173,FIXED,Third-person Bond model spawns too high —,"MOSTLY FIXED as a side effect of D243 (2026-09-18, user-confirmed)."
 D179,FIXED,Packaged build crashes after the logos —,"Diagnosed, not fixed —"
-D180,PARTIAL,"Native-PC input pass (M-XX QoL run, qol/native-pc-input-menu, port-only).","LANDED, port-only, no #ifdef PORT."
-D181,PARTIAL,Game.ScreenShakeIntensity —,"LANDED behind config, default = original."
-D184,PARTIAL,F10 port-layer options overlay —,"LANDED, port-only, no #ifdef PORT in src/."
-D211,PARTIAL,"PC FOV slider — Video.FovScale (M-83 QoL wave, port-only, WIDESCREEN-FOV-PLAN.md Phase 4).",PARTIAL — M-84 refix:
-D212,PARTIAL,Anisotropic-filtering config wiring —,"LANDED, port-only. Build clean."
-D213,PARTIAL,On-screen FPS readout —,"LANDED, port-only. Build clean; bunker1 no-op confirmed."
-D214,PARTIAL,"Keyboard rebinding — [Input.Bind] config section (M-83, port-only, PD parity, Phase 4 debt).",PARTIAL — M-84: code PASS (alt/ctrl); one doc-only fix.
+D180,FIXED,"Native-PC input pass (M-XX QoL run, qol/native-pc-input-menu, port-only).",FIXED (2026-09-26 bookkeeping:
+D181,FIXED,Game.ScreenShakeIntensity —,FIXED (2026-09-26 bookkeeping:
+D184,FIXED,F10 port-layer options overlay —,FIXED (2026-09-26 bookkeeping:
+D211,FIXED,"PC FOV slider — Video.FovScale (M-83 QoL wave, port-only, WIDESCREEN-FOV-PLAN.md Phase 4).",FIXED (2026-09-26 bookkeeping:
+D212,FIXED,Anisotropic-filtering config wiring —,FIXED (2026-09-26 bookkeeping:
+D213,FIXED,On-screen FPS readout —,FIXED (2026-09-26 bookkeeping:
+D214,FIXED,"Keyboard rebinding — [Input.Bind] config section (M-83, port-only, PD parity, Phase 4 debt).",FIXED (2026-09-26 bookkeeping:
 D215,FIXED,1P weapon viewmodel never drew in-level —,"FIXED (src/game/gunfire.c, #ifdef PORT)."
-D216,PARTIAL,"Game.SkipIntro — boot straight to the file-select menu (M-83, port + one #ifdef PORT game-code line, PD parity, Phase 4 quick win).",LANDED + VERIFIED this session.
-D217,FIXED,1P weapon viewmodel + third-person Bond model textures render garbled —,FIXED (M-90/M-92/M-97; PR #47 texpool alignment + PR #49 CI-cache palette key) —
-D218,FIXED,Wide FOV exposes the per-level draw-distance / fog boundary —,"Logged (M-84), fix proposed + parked."
-D219,RESOLVED,"PPK explosions render purple on Dam (M-87, user QA, ""not 3D but noting"").","RESOLVED (M-115, 2026-09-12) —"
-D220,PARTIAL,"1P muzzle flash position shifts upward at higher Video.FovScale (M-87, user QA, Jungle/M16).","ANALYZED (M-91) — the suspected unscaled-viewmodel root does NOT hold; this is correct perspective behavior, likely cosmetic/QoL."
-D85,OPEN,room primary/secondary DL → texLoadFromGdl garbage,"OPEN (safety-netted; widen/pool fixes landed, geometry now renders)"
-D86 · D87,RESOLVED,modelInitRwData truncated ptr · attract-demo BE ramromfilestructure,resolved
-D88.4,RESOLVED,propDefs polymorphic record stream not byteswapped → setupDoor crash,resolved (d88_propdefs.py); layout audit M-20 → D132
+D216,FIXED,"Game.SkipIntro — boot straight to the file-select menu (M-83, port + one #ifdef PORT game-code line, PD parity, Phase 4 quick win).",FIXED (2026-09-26 bookkeeping:
+D217,FIXED,1P weapon viewmodel + 3P Bond model textures garbled —,FIXED + merged (PR #47 + PR #49); white residual split out as D228.
+D218,FIXED,Wide FOV exposes the per-level draw-distance / fog boundary —,FIXED (2026-09-26 reclassified:
+D219,RESOLVED,"PPK explosions render purple on Dam (M-87, user QA, ""not 3D but noting"").","RESOLVED (M-115, 2026-09-12) for the original PPK-purple symptom."
+D220,CLOSED,"1P muzzle flash position shifts upward at higher Video.FovScale (M-87, user QA, Jungle/M16).","CLOSED — merged into D303 (2026-09-26, user:"
+D85,CLOSED,Room primary/secondary DL → texLoadFromGdl garbage.,"CLOSED (2026-09-26, user-approved:"
+D86 · D87,RESOLVED,modelInitRwData truncated ptr · attract-demo BE ramromfilestructure.,resolved
+D88.4,RESOLVED,propDefs polymorphic record stream not byteswapped → setupDoor crash.,resolved (d88_propdefs.py); layout audit M-20 → D132
 D132,PROPOSED,D88 propDefs layout audit (M-20):,proposed fix (not applied) —
-D157,FIXED,"Campaign never unlocks the next level (M-30, user bug —","FIXED (src/bondtypes.h, #ifdef PORT —"
-D160,PARTIAL,Dam level-end cutscene (Bond off the dam / bungee) never plays —,"DIAGNOSTIC SHIPPED, not root-caused (c95713f5, #ifdef PORT + GE_D160=1):"
+D157,FIXED,"Campaign never unlocks the next level (M-30, user bug —","FIXED (src/bondtypes.h, #ifdef PORT —…"
+D160,FIXED,Dam level-end cutscene (Bond off the dam / bungee) never plays —,"FIXED (user, 2026-09-26:"
 D89-D92,RESOLVED,"stage-load→frame: stan zero-fill overrun, portal address trunc, chr/AI spawn ptrs",resolved
 D93-D102,RESOLVED,struct-pun / hardcoded-size pass:,resolved (D95 pool bump partial)
 D103-D107,RESOLVED,"BUNKER1 viewport height, depth-buffer clear (G_CLEAR_DEPTH_EXT), portal near-plane, LOD mip tile",resolved
 D108-D112,RESOLVED,skeletal models: d43_emit.py put_f32 byte-reversal bug,resolved
 D113-D116,FIXED,portal BFS ok · matrix chain ok · player raw-offset audit + gunfire.c THROW* · HUD text X-mirror,"D114/D116 CLOSED — NOT A BUG (M-33, see D168):"
-D117,OPEN,frame nondeterminism root-caused; GE_DETERM deferred; framediff.py structural.,"OPEN (mode attempted, not achieved)"
-D118,RESOLVED,SDL input layer (port/src/input.c); M-24 mouse-look rework:,resolved (D118a residual)
+D117,OPEN,"Frame nondeterminism root-caused; GE_DETERM attempted, not achieved.","OPEN (mode attempted, not achieved)"
+D118,RESOLVED,"SDL input layer; M-24 mouse-look rework (mode-aware map, real INI); D118b/c FIXED.",resolved (D118a residual)
 D150,FIXED,watch OBJECTIVES / BRIEF page crash:,FIXED (src/str.c #ifdef PORT); interactive re-verify pending
+D260-D265,CLOSED,"v0.2.1 hotfix batch: D260 wheel direction swap (fixed) · D261 watch-menu nav auto-repeat (fixed, feel-check owed) · D262 watch item-preview model missing → roo…",CLOSED (2026-09-26 bookkeeping:
+D266-D269,CLOSED,"D236/D265 wall, second pass:",CLOSED (2026-09-26 bookkeeping:
+D270,CLOSED,Backfilled (M-132) — this label was never given its own row; only code comments and the HANDOFF archive documented it.,CLOSED (2026-09-26 bookkeeping:
+D271,FIXED,"D236 wall, third pass —",FIXED-but-insufficient (src/game/bg.c #ifdef PORT) —
+D276,CLOSED,"D236 wall, eighth pass —",CLOSED (2026-09-26 bookkeeping:
+D279,CLOSED,Backfilled — this label was consumed by an undocumented partial session (2026-09-14 ~23:00) that left artifacts in scratch/ (d279_run.log… —,CLOSED (2026-09-26 bookkeeping:
+D281,FIXED,"Game.AllUnlocked (D257) still breaks audio, and can also break right-mouse aim, when enabled before any save has ever been written (v0.2.1 user testing… —","FIXED (2026-09-23, port/src/libultra.c):"
+D282,FIXED,"QoL ask (v0.2.1 user testing, 2026-09-15):","FIXED (port/src/input.c, #ifdef not needed —"
+D283,OPEN,"Steam Deck first-run preset (D-unnumbered in port/src/video.c/main.c, videoApplySteamOSDefaults()) did not apply for a user who added the game via Steam… —","OPEN — mechanism understood, root cause (Desktop-vs-Game-Mode STEAMOS env var difference) unverified on real hardware; user-facing workaround documented in README/release notes."
+D280,CLOSED,"D236 wall, ninth pass —",CLOSED (2026-09-26 bookkeeping:
+D275,CLOSED,"D236 wall, eighth pass —",CLOSED (2026-09-26 bookkeeping:
+D274,CLOSED,"D236 wall, seventh pass —",CLOSED (2026-09-26 bookkeeping:
+D273,CLOSED,"D236 wall, fifth pass —",CLOSED (2026-09-26 bookkeeping:
+D272,CLOSED,"D236 wall, fourth pass —",CLOSED (2026-09-26 bookkeeping:
 D137,FIXED,right-mouse (aim-sight) crash:,FIXED (src/game/gunfire.c #ifdef PORT —
 D119 · D120,FIXED,guard-attack weapons_held[]->chr pun crash · blood-stain PointUsage[] chain hang,D119 fixed · D120 FIXED (M-30)
 D120,FIXED,Blood-decal PointUsage[] chain —,FIXED (tools_pc/d43_emit.py).
-D121,RESOLVED,WS1 frictionless per-level boot:,resolved
+D121,RESOLVED,WS1 frictionless per-level boot (bare -level_XX injects its -m* row).,resolved
 D122,FIXED,per-level prop/item model-load crash (Dam/Facility/Runway modelLoad/modelInitRwData):,converter fixed; residual chr/fast3d crashes on those levels are separate
 D123,FIXED,crash class C1: chrIsNotDeadOrShot NULL deref on 6 levels (Dam/Runway/Frigate/Statue/Streets/Cradle).,"converter fixed (OBJ_ID_WORDS); C1 cleared on all 6, residual crashes are fast3d (C2)"
 D125,RESOLVED,crash classes C3+C6 (Aztec/Bunker2/Surface2):,resolved (M-16b) — line 374 → 8 NULs; all 21 sidecars regen'd; Aztec -level_28 now PASSES (was C3 CRASH).
 D126,RESOLVED,"crash classes C3r/C4/C6 (Bunker2 -level_27 door7F054FB4 propobj.c:13523, Depot -level_30 prop.c:902, Surface2 -level_43 loadobjectmodel.c:393):",resolved — d88_propdefs.py PROPDEF_PC_BYTES[30/32/33/35]=24 + typed handler; loadobjectmodel.c sizepropdef PORT returns 6.
 D124,FIXED,crash class C2: fast3d bad texture pointer.,Jungle fixed (port/src/gimgfixup.c); Facility → D130
-D131,RESOLVED,crash class C2m (Jungle -level_37):,"resolved — seg_addr() restores the module high word for any fallthrough w1 in [0x40000000, 0x70000000) (module fixed-based at 0x140000000, no ASLR; DRAM/KSEG0/segmented/phys all handled earlier)."
+D131,RESOLVED,crash class C2m (Jungle -level_37):,"resolved — seg_addr() restores the module high word for any fallthrough w1 in [0x40000000, 0x70000000) (module fixed-based at 0x140000000, no ASLR; DRAM/KSEG0/segmented/phys all handled earlier).…"
 D133,RESOLVED,intro render triage (M-20):,"RESOLVED — not a regression, parked (D75/D76, GRAPHICS-BACKLOG.md)"
 D134,FIXED,"Frame-2 boot hang / sweep ""NO-FRAMES"" flakiness —",FIXED (port/src/libultra.c)
-D135,FIXED,"Firefight crash — bgTestHitOnObj (propobj.c:8446) is an unported N64 GBI parser (M-22, WS6 playtest).","FIXED (src/game/propobj.c, #ifdef PORT —"
+D135,FIXED,"Firefight crash — bgTestHitOnObj (propobj.c:8446) is an unported N64 GBI parser (M-22, WS6 playtest).","FIXED (src/game/propobj.c, #ifdef PORT —…"
 D136,RESOLVED,"Stage-unload crash — objFree obj->prop reads float garbage (M-22, WS6 Facility playthrough).",ROOT-CAUSED → D139 (it was NOT a layout bug —
-D139,FIXED,Stage-unload crash root cause + fix (M-23).,"FIXED (src/game/cleanup_objects.c, #ifdef PORT —"
+D139,FIXED,Stage-unload crash root cause + fix (M-23).,"FIXED (src/game/cleanup_objects.c, #ifdef PORT —…"
 D140,FIXED,Pause-menu crash (M-23 open → M-27 fixed).,"FIXED (src/game/bondview.h, src/game/bondview2.c; #ifdef PORT)."
 D141,FIXED,"Watch-menu item-model crash (M-27), exposed by D140.","FIXED (src/game/gunfire.c, #ifdef PORT)."
-D152,OPEN,"Mission-failed / objective-failed → permanent black screen (M-28, user bug report —","MITIGATED (port/src/libultra.c, M-28, #ifdef PORT/port-only)."
-D154,FIXED,"bg.c room-geometry ray/hit-test GBI parser port (M-28, WRITTEN / UNVERIFIED / UNCOMMITTED).",M-30 re-audit + fixes (still playtest-gated for final verify).
-D156,PARTIAL,"Facility outro-cutscene ""hang"" —","GUARDED (src/game/model.c, #ifdef PORT):"
-D155,FIXED,"Facility outro-cutscene end → ""hang"" = unclamped deltaFrames spiral (M-29, user bug report).","FIXED (src/game/frametiming.c, #ifdef PORT —"
+D152,FIXED,"Mission-failed / objective-failed → permanent black screen (M-28, user bug report —","FIXED (user, 2026-09-26:"
+D154,?,"bg.c room-geometry ray/hit-test GBI parser port (M-28, WRITTEN / UNVERIFIED / UNCOMMITTED).",M-30 re-audit + fixes (still playtest-gated for final verify).
+D156,FIXED,"Facility outro-cutscene ""hang"" —","FIXED (user, 2026-09-26:"
+D155,FIXED,"Facility outro-cutscene end → ""hang"" = unclamped deltaFrames spiral (M-29, user bug report).","FIXED (src/game/frametiming.c, #ifdef PORT —…"
 D153,RESOLVED,"-level_09 frame ~900–1400 0xc0000005 = D117/D134 load flakiness, NOT a bug (M-28).",NOT A BUG — closed. Run anchors on a quiet machine.
-D151,FIXED,Watch data all blank —,"FIXED (src/bondtypes.h, #ifdef PORT —"
+D151,FIXED,Watch data all blank —,"FIXED (src/bondtypes.h, #ifdef PORT —…"
 D130,RESOLVED,"crash class C2 (Facility -level_34, Runway -level_35):",resolved — stage all 6 N64 fields in a local f[6] before writing any.
-D164,PROPOSED,"Disclaimer / legal screen only draws the first line (D76 root cause, M-31).","FIX PROPOSED, NOT APPLIED (front.c is owned by another agent this session)."
+D164,FIXED,"Disclaimer / legal screen only draws the first line (D76 root cause, M-31).",FIXED — corrected 2026-09-18:
 D165,FIXED,"Front-end menu cursor doesn't feel like a mouse pointer (M-31, user bug B5 follow-up).","FIXED (port/src/input.c; Input.MenuPointerMode, Input.HipfirePitchSpeed added)."
-D166,FIXED,Hipfire mouse pitch is digital while yaw is analog —,FIXED (port/src/input.c).
-D235,OPEN,Wrong textures load after dying/restarting a level —,OPEN — needs: does it repro on a *fresh* level boot (rules out reload-state) vs only after death/restart (confirms it); which surfaces; a screenshot.
-D236,OPEN,"Surface 1: 2D billboard trees render as a wall/sheet of tree texture instead of discrete camera-facing tree sprites (M-106, user QA report).",OPEN — not investigated
-D237,OPEN,"QoL ask (M-106, user QA):",OPEN — not designed; port-only
-D238,OPEN,"QoL ask (M-106, user QA):",OPEN — not designed; port-only (port/src/input.c + config.c)
-D239,?,"QoL ask (M-106, user QA):",CLOSED — executed in the v0.2.0 prep pass (port-only):
-D240,OPEN,"Player gunshot SFX timing/cadence reportedly does not match the N64 original's rate (M-106, user QA report).","OPEN — not root-caused; static call-site tracing only, no runtime verification possible in this environment."
-D241,OPEN,Player gunshot SFX goes silent under some conditions —,"OPEN — not newly root-caused; high confidence this is D207 reproduced, not an independent bug."
-D242,?,Player-death sequence UX regression vs N64 original:,NOT A PORT-LOGIC BUG as far as static analysis can tell.
-D243,OPEN,"Dam end-of-level cutscene (the abseil/bungee sequence, D148/D160's subject):",OPEN — M-109 re-analysis of the same session's raw logs corrects the timing/pattern claims above; the D134/pendingGfx race hypothesis is likely wrong.
-D245,OPEN,IsWater water: two competing patterns with a visible seam that moves as the player looks around (mouse/aim) —,"OPEN — REOPENED (M-116 live playtest, same session):"
-D246,OPEN,"Tiny pixel strips at the left and right edges of the screen, ""like overscan"" —","OPEN — one candidate ruled out (M-116 follow-up), root cause not found."
-D247,RESOLVED,Black bars top and bottom of screen —,"NOT A BUG — confirmed faithful, unmodified N64 decomp behaviour, no code change made."
+D166,FIXED,Hipfire mouse pitch is digital while yaw is analog —,FIXED (port/src/input.c).…
+D235,CLOSED,Wrong textures load after dying/restarting a level —,"CLOSED (user, 2026-09-26:"
+D236,CLOSED,"Surface 1: 2D billboard trees render as a wall/sheet of tree texture instead of discrete camera-facing tree sprites (M-106, user QA report).","CLOSED (M-198, pass 26, 425237f9; probes stripped 0503d335):"
+D237,FIXED,"QoL ask (M-106, user QA):","FIXED (2026-09-23): category headers + 5 more settings (SkipIntro, Show FPS, pad invert/deadzone/trigger); wheel scroll already existed."
+D238,FIXED,"QoL ask (M-106, user QA):",FIXED (2026-09-26: covered by D337/D338 aim work; user reports mouse feel good; code-side validation owed).
+D239,CLOSED,"QoL ask (M-106, user QA):",CLOSED — executed in the v0.2.0 prep pass (port-only)…
+D240,CLOSED,"Player gunshot SFX timing/cadence reportedly does not match the N64 original's rate (M-106, user QA report).","CLOSED (v0.4.0 campaign sign-off 2026-09-28, user:"
+D241,CLOSED,Player gunshot SFX goes silent under some conditions —,"CLOSED as the D207 family (v0.4.0 campaign sign-off 2026-09-28, user:"
+D242,FIXED,Player-death sequence UX regression vs N64 original:,"FIXED/CLOSED (2026-09-26, user:"
+D243,FIXED,"Dam end-of-level cutscene (the abseil/bungee sequence, D148/D160's subject):","FIXED, live-confirmed by the user (M-189/M-190, 2026-09-18)."
+D245,FIXED,IsWater water: two competing patterns with a visible seam that moves as the player looks around (mouse/aim) —,"FIXED (M-201, 2026-09-26, user-verified vs 1964):"
+D246,FIXED,"Tiny pixel strips at the left and right edges of the screen, ""like overscan"" —","FIXED (2026-09-18 session, port-only, Video.SafeAreaCrop)."
+D247,FIXED,Black bars top and bottom of screen —,"FIXED (2026-09-18 session, port-only, Video.SafeAreaCrop)."
 D248,FIXED,"Port runs a stable 30 FPS instead of 60 FPS game-wide (M-117, user asked to verify FPS after the D209 timing-keystone fixes).","FIXED, root-caused to a genuine pointer-width ABI bug in src/sched.c (compiled for the PC build, not excluded)."
-D249,OPEN,"LOD/culling breaks down on large open levels (Streets, Egyptian named specifically) at *default* FOV —",OPEN — not investigated.
-D250,?,FPS is inconsistent/low on many levels since the port started actually running at 60fps —,
+D249,OPEN,"LOD/culling breaks down on large open levels (Streets, Egyptian named specifically) at *default* FOV —","OPEN — M-142 static review ruled out the unscaled-far-clip and LOD-multiplier suspects (both already correct); CLOSED (v0.4.0 campaign sign-off 2026-09-28, user:"
+D250,FIXED,"FPS is inconsistent/low on many levels after 60 Hz shipped (M-119, user QA; D248 follow-on).","FIXED — per-call getenv() cost was the bottleneck; rock-steady 60-61 fps after, user re-tested 1440p/4K clean."
 D251,FIXED,F10 options overlay QoL pass:,"FIXED (port-only, port/src/optionsoverlay.c)."
-D252,?,"Particle effects cycle through a rainbow palette (M-124, user playtest of the v0.2.0-pre candidate).",
+D252,FIXED,"Particle effects cycle through a rainbow palette (M-124, user playtest of the v0.2.0-pre candidate).","FIXED (M-201, 2026-09-26, user-verified):"
 D253,FIXED,Facility (and any level with a FORCECROUCH/LADDER linked special tile) SIGSEGV on Linux/Steam Deck —,FIXED — Deck-verified:
 D254,FIXED,Linux crash handler destroyed its own logs:,FIXED — field-verified.
-D255,OPEN,"Facility firefight SIGSEGV on Steam Deck (v0.2.0-pre CI bundle, D253 fix confirmed working —","OPEN — case identified (NULL model on an active OBJ record; destroy-path ordering), reproducible on Deck in combat (Bunker + Frigate); fix pending rule-#2 sign-off."
+D255,FIXED,Facility firefight SIGSEGV on Steam Deck (v0.2.0-pre CI bundle; D253 fix confirmed working).,"FIXED (M-140) — D3x-class 32-bit pointer truncation (vtxstore_fix_refs read Model* through the mistyped ChrRecord.chrflags 4-byte-enum alias instead of ObjectRecord.model), not the destroy-path race…"
 D256,FIXED,Saves (and config) silently failed to persist on Linux whenever the game was not launched from the directory containing data/ —,FIXED (path half) — save-flow detail still owed from the user.
 D257,FIXED,New Game.AllUnlocked option (F10; default flipped OFF for v0.2.0 —,FIXED — verified by user playtest (PR #79 merged); default flipped OFF for v0.2.0 (D259).
-D259,OPEN,Game.AllUnlocked (D257) breaks audio on a fresh save:,OPEN — quirk documented; default flipped OFF for v0.2.0 (port/src/video.c); fix deferred.
-D258,OPEN,PAL/JP asset conversion is broken at the source-data level —,"OPEN — repair path verified, not applied (out of v0.2.0 scope)."
+D259,FIXED,Game.AllUnlocked (D257) breaks audio on a fresh save:,FIXED in v0.2.1 —…
+D260,FIXED,v0.2.1 (user request):,"FIXED — build green; one-line branch swap, trivially reviewable."
+D261,FIXED,v0.2.1 (user request:,FIXED — feel-check received; W/S sensitivity follow-up logged above.
+D262,FIXED,v0.2.1 (user report):,"FIXED (primary cause, D264) —"
+D264,FIXED,"D262's root cause (ABI/layout class, cf.","FIXED — build green, probes removed; visual confirmation pending."
+D263,RESOLVED,v0.2.1 (user report):,"RESOLVED (not a bug), refined (v0.2.1 further user testing, 2026-09-15)."
+D265,CLOSED,"D236 investigation (port-layer, port/fast3d/gfx_pc.cpp):",CLOSED (2026-09-26 bookkeeping:
+D258,PROPOSED,PAL/JP asset conversion is broken at the source-data level —,DEFERRED (user call 2026-09-28:
+D284,FIXED,port/src/random.c's MIPS64 dsll32/dsrl32 shift helpers were backwards —,"FIXED, 21-level sweep clean, no crashes —"
+D285,FIXED,Steam Deck SIGSEGV during D255 live-testing = SEPARATE bug:,"FIXED (user, 2026-09-26:"
+D286,CLOSED,"User-confirmed real ~8s frame freeze on Caverns, Steam Deck —","CLOSED (2026-09-26, user-approved:"
+D287,FIXED,"User-confirmed real, non-self-recovering freeze on Windows (M-141, 2026-09-15/16) after ~15-20 minutes with no input, triggered by clicking back into the… —",FIXED (user playtest 2026-09-26:
+D288,CLOSED,"Silo intro: a huge, flat-shaded, untextured brown/tan triangle sweeps across the frame during the camera pan down the missile shaft (M-141, user report —… —","CLOSED — not reproduced on the current build (2026-09-23 capture) and the 2026-09-25 user Silo playtest confirms it gone (""silo fixed"")."
+D289,FIXED,"Dam: a crash in the computer room, not reproducible on a second attempt (M-141, Steam Deck user playtest).","FIXED (user, 2026-09-26:"
+D290,FIXED,"Watch's in-game ""controller"" section shows no control-pad graphic (M-141, Steam Deck user playtest).","FIXED (2026-09-23): D264-pattern template read in watchRenderController (flags read 0), plus 3 pointer-width/raw-Gfx sites on the same path; controller model verified rendering on Windows."
+D291,CLOSED,"Dam: texture glitches when the truck drives past (M-141, Steam Deck user playtest).","CLOSED — duplicate of D306, faithful (M-201, 2026-09-26:"
+D292,FIXED,Death animations are glitched —,"MOSTLY FIXED as a side effect of D243 (2026-09-18, user-confirmed alongside D173) —"
+D293,FIXED,"QoL ask: no discoverable way to quit the game from the UI (M-141, Steam Deck user playtest —","FIXED (M-141) — ""Quit to desktop"" row added to the F10 overlay; build-verified Win+Linux, not yet live-confirmed.…"
+D294,FIXED,"Statue: ground geometry near the large CCCP/hammer-and-sickle monument briefly renders solid black over a wide area, then self-recovers 10-30 seconds later… —","FIXED, user playtest confirmed (2026-09-25:"
+D295,FIXED,"Campaign-halting crash at the end of Control Center on 00 Agent difficulty, then a crash on every subsequent relaunch/resume (GitHub #87, user campaign playtes…",FIXED (M-149) — M-148 root-caused + reproduced on HEAD; fix landed:
+D296,CLOSED,"Control Center, 00 Agent:","CLOSED (2026-09-26, user-approved:"
+D297,FIXED,v0.3.0 silently wipes ALL pre-fix player saves on first launch (D284 side effect; found during D295/M-148).,FIXED (M-150) — migration shim landed:
+D298,CLOSED,Full HUD (not just the aim-mode crosshair) missing in a v0.3.0 dev build —,"CLOSED (2026-09-26, user:"
+D299,FIXED,Game.SkipIntro crashed selecting any save slot except one —,"FIXED — fileValidateSaves() (only called from the skipped legal screen) never ran under SkipIntro, leaving saves[] all-zero; added the missing call to the SkipIntro shortcut (src/game/lv.c, #ifdef PO…"
+D300,FIXED,Hipfire look feels non-uniform (issue #89):,"FIXED, user-confirmed live —"
+D301,FIXED,"fileGetIsCheatUnlocked() NULL-deref, unguarded on every call site, not just the D299/SkipIntro one (GitHub #87, two reports with an identical crash PC/fault ad…",FIXED locally on release/v0.3.0 (not pushed) —
+D302,FIXED,"Render FPS regression to ~40-45fps on release/v0.3.0 (user QA on the local v0.3.0 pre-release build, 2026-09-18) —","FIXED — 4 uncached getenv() calls added by D236 passes 10/12/14/16 directly inside gfx_sp_tri1 (port/fast3d/gfx_pc.cpp, per-triangle) cached with the same static int x = -1 pattern D250 established e…"
+D303,FIXED,"Some muzzle flashes (M16 named specifically, ""and some others"") draw wrong —","FIXED (M-201, 2026-09-26):"
+D304,FIXED,"Mouse sensitivity menu overhaul (user request, 2026-09-18):","FIXED — see full entry for both the range/parity pass and the same-day follow-up (collapsed to a single Input.MouseSensitivity menu row + fixed overlayUpdateScroll()'s unconditional bottom-anchor, th…"
+D305,FIXED,"Steam Deck SIGSEGV on the v0.3.0 pre-release build (Cavern, early in the level, Game.AllUnlocked previously enabled on the session/save) —",FIXED (defensive guard) —
+D306,CLOSED,"Dam intro/truck wheels render with odd transparent-looking areas, possibly z-fighting (user QA, 2026-09-18).","CLOSED — faithful, confirmed on 1964 (M-201):"
+D307,FIXED,"In-level security camera entities can be flipped facing the wrong direction (backwards) on some levels, e.g.","FIXED (M-201, 2026-09-26, user-verified):"
+D308,CLOSED,"Occasional z-fighting confirmed on some levels' geometry, general/broader than the D306 truck-wheel instance (user QA, 2026-09-18).","CLOSED — faithful (2026-09-26, user:"
+D309,FIXED,Complete non-self-recovering freeze (Windows) returning from Caverns to the intro screen —,FIXED via D310 — user-playtest-confirmed 2026-09-18 (Caverns→intro clean; the spin record itself observed resuming correctly in the post-fix probe log).
+D310,FIXED,"RULE-2-SIGNOFF: chraiitemsize() mis-sizes 1-byte AI_PRINT records (NUL-scans forward), corrupting AI execution for any list containing an active PRINT —",FIXED — user-playtest-confirmed 2026-09-18 (v2:
+D311,FIXED,Complete freeze in modelSetAnimFrame2WithChrStuff root-motion loop —,FIXED — root cause D336 (bheadAdjustAnimation read never-written placeholder fields); the #ifdef PORT guard is retained as a safety net.
+D312,FIXED,"Throwable items (mines, grenades, etc.) can clip through walls in certain spots (user report, v0.3.0 pre-release playtest, 2026-09-18).",FIXED — bgBuildRoomVtxBounds mis-reads the G_VTX vertex count on PC (Gfx_le.dma.par bit-layout shift):
+D313,FIXED,Bullet impacts do not appear on some walls/surfaces —,"FIXED — same root cause as D312, merged diagnosis; same one-line fix."
+D314,FIXED,"F10 menu items flicker randomly/intermittently (reported on the main-menu context, user report, v0.3.0 playtest build, 2026-09-18).",FIXED (user playtest 2026-09-26) —
+D315,CLOSED,Menu scaling differs between main menu and in-game —,"CLOSED (2026-09-26, user:"
+D316,FIXED,"Mouse-clicking some menu items glitches and lands on the item below instead (user report, v0.3.0 playtest build, 2026-09-18).",FIXED — root-caused to two compounding bugs (naive mouse->logical mapping ignoring the safe-area crop; asymmetric row hit-test band) in port/src/optionsoverlay.c + port/fast3d/gfx_pc.cpp.
+D317,CLOSED,"Crash when toggling Game.AllUnlocked back and forth in-game (user report, v0.3.0 playtest build, 2026-09-18) —","CLOSED — symptom of D316 (confirmed instant window close, no WER report; the D316 hit-band bias let a click on ""All unlocked"" fall through to the adjacent ""Quit to desktop"" row)."
+D318,FIXED,Facility (regular play path):,FIXED via D329 (2026-09-26 bookkeeping:
+D319,FIXED,"Frame cap slider was mostly a dead zone; replaced with a plain 30/60 toggle (user ask, 2026-09-18).",FIXED — new ROW_FPSCAP cycle (30/60 only) in port/src/optionsoverlay.c; default changed to 60 in port/src/video.c.
+D320,FIXED,"D318-class sweep: aim-hold → _update AI lists in 8 levels carry the same as-authored softlock race (static analysis, 2026-09-20).",FIXED via D329 (2026-09-26 bookkeeping:
+D321,FIXED,D318 trigger chain fully mapped:,FIXED via D329 (2026-09-26 bookkeeping:
+D322,FIXED,Long-session audio degradation:,"FIXED (Windows) for the periodic ""garbled"" bursts —"
+D323,CLOSED,G_TL_LOD bindings of explicit-LOD textures:,"CLOSED — parked as a fidelity enhancement, not a bug (2026-09-26, user-approved:"
+D324,FIXED,"GE's <stdlib.h> stub declares nothing, so TUs that include it get NO CRT prototypes —",FIXED (2026-09-22) — proven impact:
+D325,CLOSED,ROM-mod (xdelta) compatibility:,CLOSED as a question —
+D326,CLOSED,Random Eye randomizer repacks the ROM too —,CLOSED as a question —
+D327,RESOLVED,"Mod support, resolved plan:",RESOLVED — superseded by D328; approach (a) is NOT ruled out (these scans missed the 1172-compressed data segment).
+D328,CLOSED,"Mod support is viable and D327's ""ruled out"" was wrong:",CLOSED as a question —
+D329,FIXED,The D318/D320 guard anim pin is a tick-granularity divergence:,"FIXED — Rule-2 high-FPS fix in model.c; clk=1 no longer pins (WSL + native Windows), 0 triggers at clk=2; bunker1 golden failure predates it (on/off A/B); user playtest confirms N64-matching Ourumov…"
+D330,FIXED,"#103 (v0.3.0, Win 11):",FIXED (port/src/input.c) —
+D331,FIXED,Ejected shell casings never rendered on PC:,"FIXED (gunfire.c #ifdef PORT, explicit template); PP7 casing verified on native Windows (before:"
+D332,FIXED,Reticule jitter in aim mode (RMB) —,FIXED (fix/mouse-pd-model) —
+D333,FIXED,"#104 (v0.3.0, Linux):",FIXED (2026-09-26 bookkeeping:
+D334,FIXED,"Native widescreen, world side (WIDESCREEN-FOV-PLAN Option B Phase 2):",FIXED (2026-09-26 bookkeeping:
+D335,FIXED,"Native widescreen, HUD + front end (WIDESCREEN-FOV-PLAN Phase 3):",FIXED (2026-09-26 bookkeeping:
+D336,FIXED,"Frigate (and any level) ""all polygons break except the gun"" after turning:","FIXED (src/game/bondhead.c #ifdef PORT, ABI/layout); headless repro (Runway → exit → Frigate → turn, D294 2× room pool) clean, D156 0 fires; golden 3/3; Win + Linux builds."
+D337,FIXED,Aim modes folded (user decision):,FIXED (2026-09-26 bookkeeping:
+D338,FIXED,"Input.AimRange (F10 ""Aim range""):",FIXED (2026-09-26 bookkeeping:
+D339,OPEN,"#92 (low-end ~30 fps, Celeron N3060 / HD 400) —","OPEN (2026-09-26, user:"
+D341,FIXED,"Intro gun-barrel blood drip draws as static blocks/lines instead of dripping (user, v0.4.0, 2026-09-26; death blood fine).","FIXED (M-201, user-verified 2026-09-27):"
+D342,FIXED,"File select: folder bodies and Bond photos vanish after selecting a file and backing out (user, v0.4.0, 2026-09-26).","FIXED (M-201, user-verified):"
+D343,FIXED,"File select: PC ""Options"" label opens the settings overlay (v0.4.0 feature, M1 of the route-B options screen, 2026-09-27); also fixes F10 on file select jumpin…","FIXED (M1, closed): one Rule-2 #ifdef PORT draw hook (user sign-off 2026-09-27); headless + user-verified (mouse, F10, >30 s, widescreen, physical controller on the bottom-bar label and options scree…"
+D344,FIXED,Host PC bugchecks (BSOD 0x119 VIDEO_SCHEDULER_INTERNAL_ERROR) during game test runs; probable cause:,"FIXED (probable cause; orderly quit + GE_QUITFRAME), headless + user-verified; no dump, watch for recurrence."
+D345,FIXED,"Front-end crosshair snaps away from the pointer on screen/page changes (file select → mode select setCursorPOSforMode(0), front.c:2516; every MENU_PC_OPTIONS p…","Port-only, user-verified (parts a–g):"
+D346,CLOSED,PC-settings wording pass:,CLOSED (2026-09-28). Shipped in v0.4.0; accepted in the user's final review / campaign playtest.
+D347,FIXED,F10 overlay controller:,"FIXED (port-only, optionsoverlay.c):"
+D348,?,"File-select ""PC Options"" label:",SUPERSEDED by D398 (glyph replaced with the IMG_DOT texture; no new art).
+D349,CLOSED,GE watch settings are not normally saved to the Bond file:,CLOSED (2026-09-28). Shipped in v0.4.0; accepted in the user's final review / campaign playtest.
+D350,CLOSED,Watch-backed PC options:,CLOSED (2026-09-28). Shipped in v0.4.0; accepted in the user's final review / campaign playtest.
+D351,FIXED,Existing D346 value/unit rows had positional initializers shifted into hidePtr:,"FIXED (port-only): designated row initializers restore unit, deadzone divisor and hide-if-auto fields; build clean, headless smoke clean."
+D352,FIXED,D350 review of 1303c0eb:,"FIXED (port-only, port/src/watchsettings.c):"
+D353,FIXED,Turok-style settings regrouping:,"FIXED (port-only, optionsoverlay.c/frontoptions.c):"
+D354,FIXED,Front-end F10 Bond rows silently disabled:,"FIXED (port-only, port/src/watchsettings.c):"
+D355,FIXED,F10/options Music slider inaudible in-stage:,"FIXED (port-only, port/src/watchsettings.c):"
+D356,FIXED,"Settings regroup: Turok-style pages renamed to functional sections (INPUT/GAMEPLAY/GRAPHICS/AUDIO/VIDEO) with PD-style ""(File N)"" scoping annotations, the redu…","FIXED (port-only, port/src/optionsoverlay.{h,c} + port/src/watchsettings.{h,c} + port/src/frontoptions.c; plan docs/dev/D356-SETTINGS-REGROUP-PLAN.md):"
+D358,FIXED,D356 level-1 overlap:,"FIXED (port-only, port/src/frontoptions.c):"
+D359,CLOSED,"Settings UI file terminology settled on the end-user term ""Profile"":",CLOSED (2026-09-28). Shipped in v0.4.0; accepted in the user's final review / campaign playtest.
+D360,CLOSED,F10 INPUT heading scrolled away; F10 navigation and distance defaults (2026-09-27).,CLOSED (2026-09-28). Shipped in v0.4.0; accepted in the user's final review / campaign playtest.
+D361,FIXED,Main-menu F10 Audio freezes the game:,"FIXED (port-only, port/src/watchsettings.c + F10 probe in optionsoverlay.c):"
+D362,CLOSED,F10 GoldenEye dossier-style visual refresh (2026-09-27).,CLOSED (superseded by D363 after user playtest):
+D363,FIXED,F10 return to a dark overlay with the N64 watch's green/Bank Gothic visual language (2026-09-27).,"FIXED (palette/font user-approved, 2026-09-27); D364 follows up on profile tags, click alignment and slider calibration."
+D364,FIXED,Settings UI feedback:,FIXED (user mostly accepted; D365 follows up on annotation size and click targets).
+D365,CLOSED,F10 annotation hierarchy and visible mouse change targets (2026-09-27).,CLOSED (2026-09-28). Shipped in v0.4.0; accepted in the user's final review / campaign playtest.
+D366,CLOSED,Input calibration label:,CLOSED (2026-09-28). Shipped in v0.4.0; accepted in the user's final review / campaign playtest.
+D367,?,F10 full-width control boxes misaligned with their contents (2026-09-27).,SUPERSEDED by D368 after user playtest:
+D368,?,Simplify F10 click targets:,"INPUT RULE KEPT; tinted strips user-rejected, removed in D369."
+D369,FIXED,Remove F10 row boxes/strips entirely (2026-09-27).,FIXED (awaiting live acceptance):
+D370,CLOSED,F10 distance/volume drags hurt frame rate (2026-09-27).,CLOSED (2026-09-28). Shipped in v0.4.0; accepted in the user's final review / campaign playtest.
+D371,FIXED,"GEPD key-layout preset + reload/crouch bindings, v0.4.0 modern options wave M3 (2026-09-27).",FIXED (headless-verified; awaiting user live accept):
+D372,FIXED,"Low-end perf preset (v0.4.0 modern options wave M5, 2026-09-27).",FIXED (headless-verified; awaiting user live accept):
+D373,FIXED,"In-game crosshair on/off + colour (v0.4.0 modern options wave M2, 2026-09-27).",FIXED (user live-tested; rule-2 sign-off recorded 2026-09-27):
+D374,FIXED,"GEPD becomes the default key layout; preset layering fix (v0.4.0 M3 playtest feedback, 2026-09-27).",FIXED (headless + user live-tested):
+D375,CLOSED,Crouch wired to the wrong pad bit:,CLOSED (2026-09-28). Shipped in v0.4.0; accepted in the user's final review / campaign playtest.
+D376,CLOSED,Crouch follow-up + modern-options spot check (2026-09-27).,CLOSED (2026-09-28). Shipped in v0.4.0; accepted in the user's final review / campaign playtest.
+D377,FIXED,GEPD independent crouch (2026-09-27).,FIXED (scripted stance verified; user says live crouch was good; pad/hold-vs-toggle specifics owed):
+D378,FIXED,GEPD use/reload separation (2026-09-27).,FIXED (headless edges tested; user says E/R seemed good; targeted door/partial-mag cases owed):
+D379,FIXED,Crosshair colour: authored texture is red (2026-09-27).,FIXED (cyan frame capture; live yellow/blue recheck owed):
+D380,FIXED,One PC keyboard layout; PD-style rebind design (2026-09-27).,FIXED (follow-up D383):
+D381,CLOSED,"RULE-2-SIGNOFF: opt-in RGB, size and Beta crosshair (2026-09-27).",CLOSED (2026-09-28). Shipped in v0.4.0; accepted in the user's final review / campaign playtest.
+D382,CLOSED,Crosshair menu placement and slider hitches (2026-09-27).,CLOSED (2026-09-28). Shipped in v0.4.0; accepted in the user's final review / campaign playtest.
+D383,PARTIAL,PD-style keyboard rebinding in both options UIs (2026-09-27).,PARTIAL (2026-09-28).
+D384,CLOSED,Front PC Options key-bind navigation feedback + two-slot UI (2026-09-27).,CLOSED (2026-09-28). Shipped in v0.4.0; accepted in the user's final review / campaign playtest.
+D385,CLOSED,Real mouse 1–5 action rebinding in the two-slot editor (2026-09-27).,CLOSED (2026-09-28). Shipped in v0.4.0; accepted in the user's final review / campaign playtest.
+D386,CLOSED,Correct Aim default from SDL middle (Mouse 2) to right (Mouse 3) (2026-09-27).,CLOSED (2026-09-28). Shipped in v0.4.0; accepted in the user's final review / campaign playtest.
+D387,OPEN,M7 AllUnlocked's read-time fake unlocks leak into saved EEPROM (2026-09-27).,OPEN (isolated user-data-copy save/untoggle repro; no fix):
+D388,CLOSED,Nest functional binding/HUD menus and remove redundant M5 toggle (2026-09-27).,CLOSED (2026-09-28). Shipped in v0.4.0; accepted in the user's final review / campaign playtest.
+D389,CLOSED,F10 footer clipping and ambiguous submenu links (2026-09-27).,CLOSED (2026-09-28). Shipped in v0.4.0; accepted in the user's final review / campaign playtest.
+D390,CLOSED,F10 pinned Back selection did not visibly change (2026-09-27).,CLOSED (2026-09-28). Shipped in v0.4.0; accepted in the user's final review / campaign playtest.
+D391,CLOSED,F10 click at glyph bottom could select next row (2026-09-27).,CLOSED (2026-09-28). Shipped in v0.4.0; accepted in the user's final review / campaign playtest.
+D392,FIXED,Train intro soldier hunched; hand intersects torso vs 1964 —,FIXED (#ifdef PORT ABI/layout in chraction.c); Train aim-angle probe confirms correction; user visually verified the soldier looks fixed against 1964.
+D393,FIXED,Controller B/Y both crouch; no in-game use button —,FIXED + user live-tested A use / X reload / Y weapon cycle.
+D394,PARTIAL,Xbox 1.1 Jinx controller parity —,PARTIAL (2026-09-28).
+D395,RESOLVED,Controller trapped in keyboard/mouse-only binding capture —,"RESOLVED (v0.4.0 campaign sign-off 2026-09-28, user:"
+D396,RESOLVED,"F10 pad B/A used as slider decrement/increment, not back/select —","RESOLVED (v0.4.0 campaign sign-off 2026-09-28, user:"
+D397,RESOLVED,SELECT FILE background + intro gun-barrel show an interlaced/comb look —,RESOLVED (2026-09-28):
+D398,FIXED,PC Options label: D348's procedural slider glyph replaced with an existing mainfolderimages texture (2026-09-27).,"SUPERSEDED by D400 (icon removed, text-only label; purple-hover bug moot; the D400 textMeasure arg-swap bug was found and fixed there)."
+D399,PARTIAL,File-select bottom row (SELECT FILE text + Copy/Erase + PC Options dot/label) shifted 15px left as a block (user sign-off 2026-09-27).,"LANDED (port-only, D343 class):"
+D400,PARTIAL,"File-select ""PC Options"" label:","LANDED (port-only, frontoptions.c):"
+D401,CLOSED,Rumble Pak → real gamepad haptics (re-promotes D224/M-87):,CLOSED (2026-09-28). Rumble shipped in v0.4.0 (D401); Steam Deck real-pad validation:
+D402,RESOLVED,First clean Linux (glibc / SteamOS) build of release/v0.4.0 broke in two port-layer include-resolution spots MinGW tolerated (bondconstants.h first-include cyc…,RESOLVED (Linux/Ubuntu-24.04 build → glibc-2.41-compatible binary for the Steam Deck):
+D403,RESOLVED,Deck v0.4.0-pre test:,"RESOLVED (2026-09-27, user-confirmed on the Deck:"
+D404,RESOLVED,"""Aim style: Centred (PC)"" (Input.AimMode=1, D333/D337) has no effect when aiming with a gamepad; the row's own doc comment over-promises (""applies to every aim…","RESOLVED (2026-09-28, port-layer only):"
+D405,CLOSED,"fast3d/OpenGL: MSAA above the driver max black-screens; two glBindFramebuffer calls pass an index where a GL name is required (PR #106, italoarruda, 2026-09-25…","CLOSED (2026-09-28). Merged from PR #106 (code file only; security-reviewed clean - port-layer GL state fixes, no external input, no allocations)."
+D406,RESOLVED,front-end PC Options screen:,"RESOLVED (2026-09-28, port-layer only, Steam Deck-validated):"
+D407,PARTIAL,Tanks cannot be boarded/exited on PC —,"PARTIAL (fix landed in v0.4.0, port-only):"
+D408,OPEN,Game.SkipIntro skips the post-mission failure dossier:,"OPEN (cosmetic, not root-caused past the handoff site)."

docs/dev/release-dropin-rom-plan.md

@@ -303,3 +303,32 @@ offer to create it).
 2. Interim frozen `ge007-convert.exe` wired to first-run — days, optional.
 3. Part B C port of `d43`/`d69` + embedded metadata + output diffing — weeks.
 4. Drop the interim binary; single-binary drop-in experience complete.
+
+## Part B follow-up backlog (was GitHub issue #85, folded here 2026-09-25)
+
+Follow-up to #6, which shipped in v0.2.0 as an NTSC-U-only drop-in (PR #84). The issue was closed on GitHub and its scope is tracked here now. It has three independent workstreams.
+
+### 1. PAL/JP asset pipeline repair (data + build)
+
+`scripts/filelist.e.csv` and `filelist.j.csv` contain naming defects that make PAL/JP conversion impossible from this tree (D258: no PAL/JP PC build has ever been producible). The repair path has been verified but not applied:
+
+- **PAL:** rename 31 model rows to the exact `file_resource_table.inc.c` symbols. Examples: `Pbridge_console` ×6 → `Pbridge_console1aZ…3bZ`, and `Pchrgrenadelauncher` → `PchrgrenadelaunchZ`. Greedy sequence alignment proves the mapping: 512×512 exact 1:1, offsets non-decreasing, and zero size anomalies against US.
+- **JP:** rename the mislabeled font row @3044276 from `fontZurichBold_fontchartable.bin` to `fontBankGothic_fontchartable.bin`. The contiguity invariant confirms it: the Gothic kerning table @3043600+676 ends exactly at this row, and the size matches the US Gothic chartable.
+- **Then:**
+  - `gen_romassets.py e/j` must run clean without a ROM.
+  - Commit `romassets_e.s` and `romassets_j.s`.
+  - Replace the hardcoded `filelist.u.csv` in the d43/d69/d88 emitters with a region→suffix map.
+  - Remove the NTSC-U-only gate in `prepare-assets.py`.
+- **Needs a PAL and/or JP ROM** for final byte-level verification of at least one region. Only NTSC is available locally.
+
+### 2. Multi-region release layout
+
+- Give each region its own OUTPUT_NAME (`ge007-ntsc-final` / `-pal-final` / `-jpn-final`) plus a default alias.
+- Add a region re-exec guard in `romdata.c` (~50 lines): if the country byte at 0x3E doesn't match the build, re-exec the sibling exe.
+- CI builds all 3 regions sequentially, and the bundle scripts package all 3 exes.
+
+### 3. C port of the emitters (optional, removes PyInstaller)
+
+Port the d43/d69/d88 emit logic to C. That removes the frozen-converter dependency entirely, because the converter becomes part of the engine binary. It's a 2–4 week task, and PD's `filemodel.c` is the closest analogue. It isn't required for PAL/JP: the frozen Python path works for all three regions once #1 lands.
+
+**Acceptance:** a user with a PAL or JP ROM gets the same one-step drop-in experience as NTSC does today.

docs/img/shots/manifest.csv

@@ -1,27 +1,13 @@
 new_name,original,video_session,snapshot_time
-shot-01.jpg,Build-pc 2026.09.13 - 16.05.44.10.mp4_snapshot_02.11.149.jpg,2026.09.13 - 16.05.44.10,02:11:149
-shot-02.jpg,Build-pc 2026.09.13 - 16.05.44.10.mp4_snapshot_06.00.446.jpg,2026.09.13 - 16.05.44.10,06:00:446
-shot-03.jpg,Build-pc 2026.09.13 - 16.05.44.10.mp4_snapshot_07.56.664.jpg,2026.09.13 - 16.05.44.10,07:56:664
-shot-04.jpg,Build-pc 2026.09.13 - 16.05.44.10.mp4_snapshot_08.33.264.jpg,2026.09.13 - 16.05.44.10,08:33:264
-shot-05.jpg,Build-pc 2026.09.13 - 16.05.44.10.mp4_snapshot_10.16.041.jpg,2026.09.13 - 16.05.44.10,10:16:041
-shot-06.jpg,Build-pc 2026.09.13 - 16.05.44.10.mp4_snapshot_11.03.430.jpg,2026.09.13 - 16.05.44.10,11:03:430
-shot-07.jpg,Build-pc 2026.09.13 - 16.54.07.12.mp4_snapshot_02.25.190.jpg,2026.09.13 - 16.54.07.12,02:25:190
-shot-08.jpg,Build-pc 2026.09.13 - 16.54.07.12.mp4_snapshot_03.05.000.jpg,2026.09.13 - 16.54.07.12,03:05:000
-shot-09.jpg,Build-pc 2026.09.13 - 16.54.07.12.mp4_snapshot_05.39.999.jpg,2026.09.13 - 16.54.07.12,05:39:999
-shot-10.jpg,Build-pc 2026.09.13 - 16.54.07.12.mp4_snapshot_05.55.651.jpg,2026.09.13 - 16.54.07.12,05:55:651
-shot-11.jpg,Build-pc 2026.09.13 - 16.54.07.12.mp4_snapshot_06.25.650.jpg,2026.09.13 - 16.54.07.12,06:25:650
-shot-12.jpg,Build-pc 2026.09.13 - 16.54.07.12.mp4_snapshot_09.33.997.jpg,2026.09.13 - 16.54.07.12,09:33:997
-shot-13.jpg,Build-pc 2026.09.13 - 16.54.07.12.mp4_snapshot_12.09.456.jpg,2026.09.13 - 16.54.07.12,12:09:456
-shot-14.jpg,Build-pc 2026.09.13 - 16.54.07.12.mp4_snapshot_12.59.497.jpg,2026.09.13 - 16.54.07.12,12:59:497
-shot-15.jpg,Build-pc 2026.09.13 - 16.54.07.12.mp4_snapshot_13.09.496.jpg,2026.09.13 - 16.54.07.12,13:09:496
-shot-16.jpg,Build-pc 2026.09.13 - 16.54.07.12.mp4_snapshot_15.22.656.jpg,2026.09.13 - 16.54.07.12,15:22:656
-shot-17.jpg,Build-pc 2026.09.13 - 16.54.07.12.mp4_snapshot_15.39.495.jpg,2026.09.13 - 16.54.07.12,15:39:495
-shot-18.jpg,Build-pc 2026.09.13 - 16.54.07.12.mp4_snapshot_16.54.496.jpg,2026.09.13 - 16.54.07.12,16:54:496
-shot-19.jpg,Build-pc 2026.09.13 - 16.54.07.12.mp4_snapshot_17.29.495.jpg,2026.09.13 - 16.54.07.12,17:29:495
-shot-20.jpg,Build-pc 2026.09.13 - 16.54.07.12.mp4_snapshot_17.39.495.jpg,2026.09.13 - 16.54.07.12,17:39:495
-shot-21.jpg,Build-pc 2026.09.13 - 17.49.35.18.mp4_snapshot_00.21.484.jpg,2026.09.13 - 17.49.35.18,00:21:484
-shot-22.jpg,Build-pc 2026.09.13 - 17.49.35.18.mp4_snapshot_00.31.328.jpg,2026.09.13 - 17.49.35.18,00:31:328
-shot-23.jpg,Build-pc 2026.09.13 - 17.49.35.18.mp4_snapshot_02.03.469.jpg,2026.09.13 - 17.49.35.18,02:03:469
-shot-24.jpg,Build-pc 2026.09.13 - 17.54.08.19.mp4_snapshot_00.11.972.jpg,2026.09.13 - 17.54.08.19,00:11:972
-shot-25.jpg,Build-pc 2026.09.13 - 17.54.08.19.mp4_snapshot_02.36.532.jpg,2026.09.13 - 17.54.08.19,02:36:532
-shot-26.jpg,settings menu.jpg,settings-menu,
+shot-01.jpg,v040/dam0.png,v0.4.0 attract pass 2026.09.28,
+shot-03.jpg,v040/runway.png,v0.4.0 attract pass 2026.09.28,
+shot-04.jpg,v040/surface 1.png,v0.4.0 attract pass 2026.09.28,
+shot-09.jpg,v040/frigate 0.png,v0.4.0 attract pass 2026.09.28,
+shot-11.jpg,v040/surface 2.png,v0.4.0 attract pass 2026.09.28,
+shot-16.jpg,v040/statue 0.png,v0.4.0 attract pass 2026.09.28,
+shot-20.jpg,v040/archives 0.png,v0.4.0 attract pass 2026.09.28,
+shot-21.jpg,v040/cradle 0.png,v0.4.0 attract pass 2026.09.28,
+shot-24.jpg,v040/aztec 0.png,v0.4.0 attract pass 2026.09.28,
+shot-27.jpg,v040/control 0.png,v0.4.0 attract pass 2026.09.28,
+shot-28.jpg,v040/streets 0.png,v0.4.0 attract pass 2026.09.28,
+shot-29.jpg,v040/jungle.png,v0.4.0 attract pass 2026.09.28,

docs/index.md

@@ -1,34 +1,70 @@
 ---
 title: GoldenEye 007 PC Port
+# v0.4.0: status bumped from v0.3.0; Honest status replaced by the v0.4.0
+# release-notes known issues (rainbow/water/z-fight/cameras/trees/muzzle/
+# stretched-widescreen/gunshot items all fixed; D335b F10-overlay stretch is
+# the new widescreen residual). Description kept short (Bing's 160 limit).
 description: >-
-  A native PC port of the original Nintendo 64 GoldenEye 007, built from its
-  decompiled source with a software RSP. v0.2.0 is out for Windows
-  and Linux (including Steam Deck): download it, drop in your own ROM, and
-  play; or dig into the code and the engineering record behind it.
+  A native PC port of GoldenEye 007 (Nintendo 64, 1997), built from
+  decompiled source with a software RSP. v0.4.0 for Windows, Linux and
+  Steam Deck.
 ---
 
-# GoldenEye 007 PC Port
+A native PC port of _GoldenEye 007_ (Rare, 1997, Nintendo 64), compiled from
+the [GoldenEye 007 decompilation](https://github.com/n64decomp/007): the
+original N64 game running from reconstructed source, not the Xbox 360
+remaster. The N64's graphics coprocessor (RSP) is emulated in software; every
+other hardware surface (video, audio, input, timers, save storage) is shimmed
+in a dedicated `port/` layer, following the architecture of the
+[Perfect Dark PC port](https://github.com/fgsfdsfgs/perfect_dark), the same
+Rare "Indy" engine family, one hardware generation apart.
 
-A native PC port of the original 1997 Nintendo 64 _GoldenEye 007_, compiled
-from the game's [decompiled source](https://github.com/n64decomp/007) with the
-N64's graphics coprocessor (RSP) running in software, the same architecture
-as the [Perfect Dark PC port](https://github.com/fgsfdsfgs/perfect_dark), the
-same Rare "Indy" engine family, one hardware generation apart.
+[Download](#download) · [News](#news) · [See it running](#see-it-running) · [Honest status](#honest-status) · [Documentation](#documentation)
 
-**Status: v0.2.0.** The full single-player campaign runs at a steady 60 fps
-and is completable end to end; all 21 missions load and run clean on Windows
-and Linux (one intermittent Steam Deck crash remains, listed below), and
-audio (music + SFX) plays throughout. The known
-rough edges (cutscenes that still glitch, a few music tracks that sound
-wrong, a handful of cosmetic rendering defects) are listed plainly under
-[Honest status](#honest-status).
+**Status: v0.4.0 (2026-09-28) — fully playable, with a small set of known
+caveats.** The full single-player campaign runs at a steady 60 fps and is
+completable end to end (all 20 missions, plus the ending-credits sequence,
+playtested on Windows, Linux and Steam Deck). It is the most complete release
+to date: **native widescreen** (on by default — undistorted world at your
+display's aspect, 4:3 menus pillarboxed), a **complete aim system** (N64 or
+centred PC style, for mouse *and* controller), **in-game key rebinding** with
+a GEPD-style default layout, **crosshair customization**, **rumble-pak
+haptics** on supported gamepads, and a **rebuilt options overlay** with
+fine-tuning rows (frame cap, MSAA, draw/LOD distance, HUD scale). The most
+common defect classes from earlier releases — particle colour drift, water
+seams, z-fighting, billboard trees, muzzle flashes, the front-end Nintendo
+logo, gunshot SFX — are fixed in this version; what remains is a short list,
+under [Honest status](#honest-status).
+
+**This is a pre-1.0 release, not a finished product** — v1.0 is the target
+for a polished, feature-complete build; expect missing features and the
+occasional breaking change until then. See the
+[README's Roadmap section](https://github.com/jkdansereau/goldeneye-pc-port#roadmap)
+for direction (PAL/JP support, controller-button rebinding, LAN multiplayer
+under consideration, and more).
 
 <p align="center">
   <img src="media/goldeneye-gh-preview.gif" width="70%"
-       alt="~32 s gameplay montage from live play sessions">
-  <br><em>~32 s gameplay montage loop from live play sessions, running in the port.</em>
+       alt="~24 s gameplay montage from live play sessions">
+  <br><em>~24 s gameplay montage from live v0.4.0 play sessions (Runway tank,
+  Dam, Caverns, Aztec, Bunker&nbsp;2, Surface&nbsp;2), running in the port.</em>
 </p>
 
+## News
+
+- **2026-09-28** — **v0.4.0**: native widescreen, a complete aim system for
+  mouse and controller, in-game key rebinding, crosshair customization,
+  rumble-pak haptics, a rebuilt options overlay, and a broad fidelity-fix
+  pass (water, particles, billboard trees, front-end logo, gunshot SFX, a
+  true stable 60 fps). [Release notes](https://github.com/jkdansereau/goldeneye-pc-port/releases/tag/v0.4.0) ·
+  [downloads](#download).
+- **2026-09-20** — **v0.3.0**: the first release with the complete campaign
+  playable end to end at 60 fps on Windows, Linux, and Steam Deck.
+  [Release notes](https://github.com/jkdansereau/goldeneye-pc-port/releases/tag/v0.3.0).
+- **2026-09-04 → 2026-09-16** — **v0.1.0 – v0.2.2**: the alpha and beta
+  cycle — build chain, software RSP, first rendered frames, front end, and
+  per-level stabilization across the campaign.
+
 ## Download
 
 | Platform | Bundle | Notes |
@@ -50,89 +86,61 @@ without a ROM you already own.
 ## See it running
 
 <p align="center">
-  <img src="img/shots/shot-06.jpg" width="45%" alt="Bunker 1, rendered by the port (v0.2.0 playtest)">
-  <img src="img/shots/shot-01.jpg" width="45%" alt="Dam, rendered by the port (v0.2.0 playtest)">
+  <img src="img/shots/shot-28.jpg" width="45%" alt="Streets, rendered by the port (v0.4.0 intro attract)">
+  <img src="img/shots/shot-01.jpg" width="45%" alt="Dam, rendered by the port (v0.4.0 intro attract)">
 </p>
 
 <details>
-<summary><strong>Full playtest gallery</strong>: 19 in-engine captures from the v0.2.0 Windows playtest, across the campaign</summary>
+<summary><strong>Full gallery</strong>: 12 in-engine captures from a v0.4.0 intro-attract pass (3072×1728 widescreen, Sep 2026)</summary>
 
 <p align="center">
   <div style="width:32%;text-align:center;margin:4px">
-    <img src="img/shots/shot-01.jpg" width="100%" alt="In-engine: Dam (v0.2.0)">
+    <img src="img/shots/shot-01.jpg" width="100%" alt="In-engine: Dam (v0.4.0 intro attract)">
     <div><small>Dam</small></div>
   </div>
   <div style="width:32%;text-align:center;margin:4px">
-    <img src="img/shots/shot-02.jpg" width="100%" alt="In-engine: Facility (v0.2.0)">
-    <div><small>Facility</small></div>
-  </div>
-  <div style="width:32%;text-align:center;margin:4px">
-    <img src="img/shots/shot-03.jpg" width="100%" alt="In-engine: Runway (v0.2.0)">
+    <img src="img/shots/shot-03.jpg" width="100%" alt="In-engine: Runway (v0.4.0 intro attract)">
     <div><small>Runway</small></div>
   </div>
   <div style="width:32%;text-align:center;margin:4px">
-    <img src="img/shots/shot-04.jpg" width="100%" alt="In-engine: Surface (v0.2.0)">
+    <img src="img/shots/shot-04.jpg" width="100%" alt="In-engine: Surface (v0.4.0 intro attract)">
     <div><small>Surface</small></div>
   </div>
   <div style="width:32%;text-align:center;margin:4px">
-    <img src="img/shots/shot-05.jpg" width="100%" alt="In-engine: Surface (v0.2.0)">
-    <div><small>Surface</small></div>
-  </div>
-  <div style="width:32%;text-align:center;margin:4px">
-    <img src="img/shots/shot-06.jpg" width="100%" alt="In-engine: Bunker 1 (v0.2.0)">
-    <div><small>Bunker 1</small></div>
-  </div>
-  <div style="width:32%;text-align:center;margin:4px">
-    <img src="img/shots/shot-07.jpg" width="100%" alt="In-engine: Silo (v0.2.0)">
-    <div><small>Silo</small></div>
-  </div>
-  <div style="width:32%;text-align:center;margin:4px">
-    <img src="img/shots/shot-09.jpg" width="100%" alt="In-engine: Frigate (v0.2.0)">
+    <img src="img/shots/shot-09.jpg" width="100%" alt="In-engine: Frigate (v0.4.0 intro attract)">
     <div><small>Frigate</small></div>
   </div>
   <div style="width:32%;text-align:center;margin:4px">
-    <img src="img/shots/shot-10.jpg" width="100%" alt="In-engine: Frigate (v0.2.0)">
-    <div><small>Frigate</small></div>
-  </div>
-  <div style="width:32%;text-align:center;margin:4px">
-    <img src="img/shots/shot-11.jpg" width="100%" alt="In-engine: Surface 2 (v0.2.0)">
+    <img src="img/shots/shot-11.jpg" width="100%" alt="In-engine: Surface 2 (v0.4.0 intro attract)">
     <div><small>Surface 2</small></div>
   </div>
   <div style="width:32%;text-align:center;margin:4px">
-    <img src="img/shots/shot-13.jpg" width="100%" alt="In-engine: Bunker 2 (v0.2.0)">
-    <div><small>Bunker 2</small></div>
-  </div>
-  <div style="width:32%;text-align:center;margin:4px">
-    <img src="img/shots/shot-16.jpg" width="100%" alt="In-engine: Statue (v0.2.0)">
+    <img src="img/shots/shot-16.jpg" width="100%" alt="In-engine: Statue (v0.4.0 intro attract)">
     <div><small>Statue</small></div>
   </div>
   <div style="width:32%;text-align:center;margin:4px">
-    <img src="img/shots/shot-19.jpg" width="100%" alt="In-engine: Statue (v0.2.0)">
-    <div><small>Statue</small></div>
-  </div>
-  <div style="width:32%;text-align:center;margin:4px">
-    <img src="img/shots/shot-20.jpg" width="100%" alt="In-engine: Archives (v0.2.0)">
+    <img src="img/shots/shot-20.jpg" width="100%" alt="In-engine: Archives (v0.4.0 intro attract)">
     <div><small>Archives</small></div>
   </div>
   <div style="width:32%;text-align:center;margin:4px">
-    <img src="img/shots/shot-21.jpg" width="100%" alt="In-engine: Cradle (v0.2.0)">
+    <img src="img/shots/shot-21.jpg" width="100%" alt="In-engine: Cradle (v0.4.0 intro attract)">
     <div><small>Cradle</small></div>
   </div>
   <div style="width:32%;text-align:center;margin:4px">
-    <img src="img/shots/shot-23.jpg" width="100%" alt="In-engine: Cradle (v0.2.0)">
-    <div><small>Cradle</small></div>
-  </div>
-  <div style="width:32%;text-align:center;margin:4px">
-    <img src="img/shots/shot-24.jpg" width="100%" alt="In-engine: Aztec (v0.2.0)">
+    <img src="img/shots/shot-24.jpg" width="100%" alt="In-engine: Aztec (v0.4.0 intro attract)">
     <div><small>Aztec</small></div>
   </div>
   <div style="width:32%;text-align:center;margin:4px">
-    <img src="img/shots/shot-25.jpg" width="100%" alt="In-engine: Aztec (v0.2.0)">
-    <div><small>Aztec</small></div>
+    <img src="img/shots/shot-27.jpg" width="100%" alt="In-engine: Control (v0.4.0 intro attract)">
+    <div><small>Control</small></div>
   </div>
   <div style="width:32%;text-align:center;margin:4px">
-    <img src="img/shots/shot-26.jpg" width="100%" alt="In-engine: Frigate (v0.2.0)">
-    <div><small>Frigate</small></div>
+    <img src="img/shots/shot-28.jpg" width="100%" alt="In-engine: Streets (v0.4.0 intro attract)">
+    <div><small>Streets</small></div>
+  </div>
+  <div style="width:32%;text-align:center;margin:4px">
+    <img src="img/shots/shot-29.jpg" width="100%" alt="In-engine: Jungle (v0.4.0 intro attract)">
+    <div><small>Jungle</small></div>
   </div>
 </p>
 </details>
@@ -155,11 +163,16 @@ More captures may land here as playtesting continues.
   licensed and yours to extend: new video options, input tweaks, your own
   asset sidecar. [CONTRIBUTING](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/CONTRIBUTING.md)
   has the ground rules that keep it faithful to the original game.
-- **The research angle**: this is also a case study in AI-agent collaboration
-  on a large, low-level codebase: two coding agents (a local open-weight model
-  on a single RTX 5090, and Claude / Claude Code), driven by one person
-  part-time through ~230 translation units of unmodified big-endian MIPS game
-  code. [The full write-up](dev/agentic-development.md): setup, timeline, the
+- **AI disclosure**: development here was agentic — Claude Pro plus a local
+  open-weight model on a single RTX 5090, as of August–September 2026. This
+  project is as much a study of *that process* as it is a port: whether
+  current LLMs can carry a codebase like this, and what actually goes wrong
+  along the way. Game codebases have historically been a rough fit for
+  LLMs — large, stateful, hardware-adjacent, unforgiving of a subtly wrong
+  memory layout — more so for older local models, so this is a useful data
+  point on where that stands now, for better or worse. Judge the result for
+  yourself. I'm one person doing this in my spare time, not a team. See
+  [the full write-up](dev/agentic-development.md) for the setup, timeline,
   handoff workflow, and an honest assessment of what did and didn't work.
 
 ## How it works
@@ -176,19 +189,25 @@ catalogue: [Porting notes](porting-notes.md).
 
 ## Honest status
 
-- **Cutscenes still glitch, mostly with James Bond**: in scripted sequences
-  Bond is the one who gets misplaced, hovers, or spins; the other actors are
-  fine for the most part now. Still the most visible gap in this release.
-- A few in-level music tracks sound wrong (wrong instruments, occasional garbling).
-- Particle colours drift through a rainbow palette instead of holding grey/orange.
-- Water levels show a moving seam; pixel strips at screen edges at non-integer
-  scales; some front-end 3D models mispositioned or absent.
-- The F10 overlay's bottom row duplicates the selected item; one intermittent
-  Steam Deck SIGSEGV in heavy firefights remains open (D255).
-- No macOS/ARM support; no controller rebinding UI yet.
+- On Facility, if gas leaks during Ourumov's monologue he can pause for up to
+  ~10 s before resuming the scripted shootout — a latent race that exists in
+  the N64 original too (where it softlocks permanently); the port detects and
+  auto-recovers it. (D318)
+- With native widescreen on, the F10 options overlay stretches with the
+  window instead of pillarboxing like the front-end menus (legible; cosmetic;
+  the F10 *Native widescreen* toggle restores the old stretched frame
+  throughout). The world/HUD widescreen rendering itself is correct. (D335b)
+- The front-end Rareware logo shows a subtle texture-filtering artifact
+  (the Nintendo logo and legal page are clean). Cosmetic only. (D75)
+- **`All unlocked` is experimental**: the fresh-install corruption case is
+  fixed, but saves made while it is on are not guaranteed recoverable by
+  switching it off — complete a level normally first, and back up
+  `data/ge007.eep` before enabling it. (D387)
+- No macOS or ARM support. Keyboard/mouse rebinding shipped in v0.4.0;
+  controller-button rebinding is not supported yet.
 
 The full list, with root causes and fix status: the
-[README's Status section](https://github.com/jkdansereau/goldeneye-pc-port#status)
+[release notes](https://github.com/jkdansereau/goldeneye-pc-port/releases)
 and the [finding log](https://github.com/jkdansereau/goldeneye-pc-port/tree/main/docs/dev).
 
 ## Documentation
@@ -198,9 +217,3 @@ and the [finding log](https://github.com/jkdansereau/goldeneye-pc-port/tree/main
 - [Internals](internals.md): architecture, the software RSP-emulation approach, GoldenEye-vs-Perfect-Dark engine differences, the phased plan.
 - [Porting notes](porting-notes.md): the recurring Nintendo 64 → PC bug classes hit during the port, with fixes.
 - [Building](building.md): full build and asset-extraction guide.
-
----
-
-<small>Non-commercial fan preservation/research project. No ROM or game assets
-are distributed; you supply a ROM you already own. Not affiliated with or
-endorsed by Nintendo, Rare, Microsoft, MGM, Danjaq, or EON Productions.</small>

docs/internals.md

@@ -3,7 +3,7 @@ title: Internals
 description: Architecture behind the PC port; the software RSP-emulation approach, GoldenEye-vs-Perfect-Dark engine differences, and the phased development plan.
 ---
 
-# GoldenEye 007 PC Port: architecture & plan
+## GoldenEye 007 PC Port: architecture & plan
 
 > This began as the pre-implementation research note and is kept as the
 > architecture reference. Sections 1–9 describe the design; section 10 lists

docs/porting-notes.md

@@ -3,7 +3,7 @@ title: Porting Notes
 description: A field guide to the recurring N64-to-PC bug classes hit while running unmodified big-endian game code on a 64-bit host, each with its symptom and fix.
 ---
 
-# Porting notes: recurring N64→PC bug classes
+## Porting notes: recurring N64→PC bug classes
 
 A field guide to the bug classes that keep recurring when running big-endian
 32-bit N64 game code, unmodified, on a little-endian 64-bit host. Terse by
@@ -28,6 +28,8 @@ good that you are looking at one of these.
 - [D3. GCC/mingw makes an all-non-negative `enum` UNSIGNED](#d3-gccmingw-makes-an-all-non-negative-enum-unsigned)
 - [D4. N64 "interrupts off" must be a real lock on PC](#d4-n64-interrupts-off-is-not-free-on-pc--it-must-be-a-real-lock)
 - [D5. Loop bounds that assume linker adjacency of two globals](#d5-loop-bounds-that-assume-linker-adjacency-of-two-file-scope-globals)
+- [D12. Collapsing an LOD binding to tile 0 breaks a DETAIL binding](#d12-collapse-an-lod-binding-to-tile-0-is-wrong-for-a-two-texture-detail-binding-d236)
+- [D13. Per-render accumulation is not associative (1 vs 2–3 ticks/frame)](#d13-per-render-accumulation-is-not-associative-the-ports-1-tickframe-can-reach-states-the-n64s-23-ticksframe-never-did-d329)
 - [E. Process / method notes](#e-process--method-notes)
 
 ## A. Pointer-width struct growth (32→64): the dominant class
@@ -55,8 +57,9 @@ state.
   `.act_*.attack_item`; aliased `WeaponObjRecord.weaponnum` at 0x80 on
   N64 via act-union@0x2C+84; act union moves to ~0x38 on PC).
 
-**A1. Raw-byte aliases into a union (`act_ubytes.padding[N]`); the silent
-variant.** The nastiest members of this class do not crash: a literal byte
+**A1. Raw-byte or mistyped aliases into a union/struct whose true field
+shifted because a sibling member widened; the silent variant.** The nastiest
+members of this class do not crash: a literal byte
 index into a union that overlays pointer-bearing structs still *reads*, it
 just reads the wrong byte, so the game runs and merely behaves wrong. Grep
 for hardcoded indices into any `padding[]`/`u8[]` union arm.
@@ -86,13 +89,69 @@ for hardcoded indices into any `padding[]`/`u8[]` union arm.
   named writes of the *same* arm. The rest of the `padding[N]` sweep
   (`chrlvTickAnim`/`chrlvTickDead` → `act_anim`/`act_dead`, both pointer-free)
   is layout-stable.
+- **D255** (a mistyped-field variant, not a raw-offset variant — same
+  mechanism, different syntax): `vtxstore_fix_refs` read a record's
+  `Model*` through `((Model*)((ChrRecord*)prop->chr)->chrflags)` —
+  `ChrRecord.chrflags` is typed `CHRFLAG`, a **4-byte enum**. On 32-bit
+  N64 the cast is bit-exact; on 64-bit PC it reads only the pointer's
+  low 32 bits and zero-extends, discarding the real high bits. The
+  truncated result is `(nil)` whenever the real pointer's low 32 bits
+  happen to be zero — which read exactly like a legitimate NULL-model
+  case, and cost two prior investigation sessions chasing a
+  "destroy-path race" theory before the field itself was the suspect.
+  **Tell that generalizes past D209/D210's `padding[N]` shape:** it
+  doesn't have to be a raw numeric offset — a field that is *correctly
+  named* but *undersized/mistyped relative to a pointer it's secretly
+  meant to hold* (an enum, a `u32`, a `s32` doing double duty as a
+  pointer slot) is the same bug through a different syntax. Fix: read
+  through the correctly-typed sibling field (`ObjectRecord.model`)
+  instead, `#ifdef PORT`, N64 line/cast kept verbatim under `#else`.
+  §F **D255** (M-140).
+- **D392** (the firing-guard pose variant): `chrlvUpdateAimendbackShoulders`
+  reads `((f32*)arg1)[12/13/16/17]` into a
+  `weapon_firing_animation_table` whose *first* member is a union of a
+  `s32` and a `ModelAnimation *`. N64's 4-byte union places those slots at
+  `max_up/max_down/free_arm_frac_up/free_arm_frac_down`; on PC the 8-byte
+  union shifts the floats, so the raw indices read `aim_end_frame/max_up/
+  max_right/free_arm_frac_up`. The wrong aim clamp bends the torso ~49° and
+  pushes the hands through it. Under `#ifdef PORT`, use the four named
+  fields; retain the raw indices for N64. §F D392.
 
-**Lesson.** When a value reads as a clean constant (0, 1) rather than
-garbage, a pointer byte is a prime suspect; the high bytes of a low-4GB
-heap pointer are all zero, so a misaligned read looks like a legitimate
-"feature off" value. Prefer the named field under `#ifdef PORT`; the alias
-is only correct at 32-bit pointer width. Also: verify that every caller
-reaches the site with the union arm you are naming actually active.
+**Lesson.** When a value reads as a clean constant (0, 1, NULL) rather
+than garbage, a pointer byte is a prime suspect; the high bytes of a
+low-4GB heap pointer are all zero, so a misaligned or truncated read
+looks like a legitimate "feature off" / "not set" value. **Tell-tale
+signs of this pattern, any one of which should trigger an A1-first
+check before assuming a bug is genuine game-logic behavior:**
+- The observed value is **byte-exact-looking but wrong from the very
+  first call/frame** — not intermittent corruption, not "usually right
+  but occasionally wrong."
+- A **raw/literal offset or byte-width read** into a union or struct
+  that has **any pointer member**, anywhere in that union/struct's
+  layout (not just the field being read) — the read doesn't need to
+  touch the pointer itself; any member *after* one that widened is at
+  risk.
+- A field that is **correctly named but too narrow to hold what it's
+  actually storing** (an enum/`u32`/`s32` reused as a truncated pointer
+  slot — the D255 shape, distinct from D209/D210's literal-offset shape
+  but the same underlying cause).
+- The resulting behavior is **deterministic and internally
+  self-consistent, but demonstrably not what the N64 original would
+  produce** — the code isn't crashing or producing garbage, it's
+  confidently doing the wrong (but stable) thing.
+- Prefer the named field (or a correctly-typed sibling field) under
+  `#ifdef PORT`; the alias/pun is only correct at 32-bit pointer width.
+  Verify every caller reaches the site with the union/struct arm you're
+  naming actually active.
+
+**Distinguish from D284** (`port/src/random.c`'s MIPS64
+shift-emulation bug): same *epistemic* shape — deterministic,
+self-consistent, silently not-N64 — but a different *mechanism*
+(instruction semantics, not struct layout/pointer width) and,
+critically, **entirely inside `port/`, no `src/game` touch at all**.
+D284 was never a rule-2 question in the first place; don't fold it
+into this catalogue's "looks like game logic, is really ABI"
+framing — it never looked like game logic to begin with.
 - **Open landmine:** raw hardcoded-offset accessors into `struct player`
   / `struct hand`; see `docs/dev/AUDIT-M6-player-offsets.md`.
 - **D126 corollary; a trailing runtime list pointer in a ROM-serialized
@@ -201,6 +260,36 @@ reaches the site with the union arm you are naming actually active.
   decompilation of what the write side already does, `#ifdef PORT` with the
   N64 hand-rolled offset kept verbatim under `#else`. §F **D248**.
 
+- **One layout bug often has sibling call sites.** D264 fixed a
+  cross-global `ModelRenderData` template read in the watch item preview;
+  the identical read in `watchRenderController` (`D_80035D04 + 0x3c`) stayed
+  broken until D290. When fixing a raw-offset global read, grep for every
+  other read of the same globals (`D_80035D00`/`D_80035D04` here) before closing.
+
+- **When a split N64 struct is made inline on PC, its placeholder fields
+  become dead, and any code still reading them reads uninitialised memory.**
+  D100 turned `player.model` into a real inline `struct Model`, but the
+  decomp's `field_59C..field_650` placeholders (raw N64 offsets into that
+  model) stayed as separate fields. `bheadAdjustAnimation` kept reading
+  `field_5C0` (= N64 `model.animframe1`) and `animFlipFlag` (= `model.gunhand`),
+  which nothing ever wrote (D336: garbage anim frames, Frigate scene wrecked,
+  sensitive to memory layout). After inlining a split struct, grep every
+  placeholder in the old range and remap each read to the real field.
+  Diagnostic tell: a hardware watchpoint on the "poisoned" field sees *no
+  writes at all*.
+
+### A-dup. Renaming an IDO duplicate member re-points every read of it (D307)
+
+IDO accepts a struct that redeclares an inherited member name (`inherits ObjectRecord;` then its own `pad`); GCC rejects it, so the port renames one. **The rename changes which field existing code reads**: on N64 the later declaration shadows the inherited one, so `rec->pad` meant the derived record's own field. After renaming it (`lookpad`), unchanged game code silently binds to the inherited field instead. D307: `setupCctv` read the mount pad as the look-at pad and every security camera faced its wall. When a port rename resolves a duplicate, grep every `->name` on that struct type and decide per site which field N64 meant (PD's named-field sources are the tie-breaker).
+
+### A-cnt. A record's "count" field may not count what the converter copies (D303)
+
+The offline model converter sizes each record's trailing arrays from its count field. Check what the *runtime consumer* does with that count before trusting its name: GE's op-22 `DisplayListPrimaryRecord.numVertices` is really the number of star-flash ARMS, and `dorottex()` reads `count*4` vertices (PD names it `stargunfire.unk00` and reads `unk00*4`). Sizing by the field name dropped 3/4 of every muzzle star; the missing vertices came from neighbouring sidecar bytes and drew as spikes. For every record type, derive the copied extent from the reading loop, and cross-check PD's typed struct.
+
+### A-buf. Growing one region of a shared buffer must move every hard-coded offset after it (D342)
+
+When a PC-larger asset gets a bigger reservation inside a shared scratch buffer (D45: the wallet model 0xA000 -> 0x17000 in `ptr_logo_and_walletbond_DL`), grep for every other user of that buffer that computes a fixed offset (`base + 4096*10`). Those still point into the old boundary and silently overwrite the enlarged asset; the corruption only shows when the asset is not reloaded.
+
 ## B. 16-byte PC `Gfx` / `Vtx` vs 8-byte N64
 
 Any buffer reservation, `memcpy` size, slot stride, or pool budget
@@ -235,8 +324,14 @@ expressed in N64 `Gfx`/`Vtx` units is **half-size** on PC.
   N64-semantics `.dma.par` becomes `((u32)gdl->words.w0 >> 16) & 0xff` on PC;
   **`gdl->dma.par` gives bits 0-23 (length), and `& 0xf` on it is always 0**
   because `len == 16*n`. The original D154 port had exactly this bug (vtxoff
-  forced to 0). Same trap latent in `bgBuildRoomVtxBounds` (`gdl.dma.par>>4&0xf`
-  reads PC bits 4-7, not N64 bits 20-23; currently tolerated). Rule: for
+  forced to 0). Same trap in `bgBuildRoomVtxBounds` (`gdl.dma.par>>4&0xf`
+  reads PC bits 4-7 = `n&0xf`, not N64 bits 20-23 = `n-1`): for n ≤ 15 it
+  happened to read the whole block (+1 vertex), but for n = 16 (the common
+  authored size) it collapsed to `numvertices=1` → single-point batch bounds
+  → the per-batch AABB pre-test in `bgTestBulletHitBackground` rejected the
+  batch → its wall triangles were never ray-tested: D312 projectile
+  pass-through + D313 missing bullet impacts (FIXED 2026-09-18, recover the
+  params byte via `((u32)gdl->words.w0 >> 20) & 0xf`). Rule: for
   anything but the opcode, extract the bit-field explicitly from
   `(u32)gdl->words.w0` / `.w1`, don't trust the named `.dma.*` sub-fields.
   Also: a `words.w0 << k >> m` bit-extract idiom that relied on 32-bit
@@ -502,12 +597,42 @@ through a converter or a runtime bswap fixup reads scrambled.
   (exact for hold-to-aim; a toggle scheme needs `g_CurrentPlayer->
   insightaimmode`). GE's native pitch is **inverted** (C-up → look down);
   hide it so mouse-down looks down; `MouseInvertY` flips (D118, M-24).
+- **N64 A/B bit names are not modern pad A/B semantics (D393).** GE's
+  gameplay `GE_CONT_A` cycles weapons and `GE_CONT_B` contextually uses or
+  reloads. Assigning Xbox A/X both to native A and B/Y both to independent
+  crouch leaves *no* use button. For modern controls, map A to a dedicated
+  use edge, X to a dedicated reload edge, B to crouch, Y to a weapon-cycle
+  edge; preserve native accept/cancel bits in front menus/watch/tank. Track
+  held buttons across UI transitions so closing F10 does not trigger an
+  unexpected use/reload/cycle.
 - `osContGetReadData(pad)` must fill **one OSContPad per channel**
   (`MAXCONTROLLERS`-long array), not just controller 0; joy.c passes the
   whole `samples[i].pads` array (D118).
 - Controller state has one source: `port/src/input.c`. `libultra.c`'s SI
   section marshals `inputComputePad()` into `g_contPad[]`; it is driven by
   `osContStartReadData` (per logic tick), no separate `video.c` frame hook.
+- **The in-level watch/pause is not a "menu" to `input.c`** (`current_menu`
+  stays `RUN_STAGE`), but it reads the stick as **discrete** input: ±0x2E
+  on X picks an option value or flips a page, and Y scrolls rows. Any path
+  that turns a continuous device (the mouse) into stick deflection must be
+  gated off there (`!outside_watch_menu || pause_state`), or small hand
+  motion becomes phantom menu choices. D330/#103: mouse → legacy stick
+  fallback silently reset Auto-Aim/Look-Ahead to OFF. The direct-write
+  look paths already gate on this; the fallbacks must too.
+
+- **A port-side shadow of game data must be re-synced every time the game
+  re-derives the original, not just the first time.** D252: `texReset()`
+  re-resolves the global image DLs' texture pointers on *every* stage load;
+  the compiled shadow copies (`gimgSyncCompiledGlobalDLs`, D68) only accepted
+  a write while a slot still held its unresolved marker, so every stage after
+  the title kept pointers into freed memory. It looked fine until the new
+  stage overwrote that region (rainbow explosions mid-level). Key a sync on
+  *which slots* are synced (learned once), never on "still unresolved".
+  Headless `-level_XX` boots hide this class (the first stage is the level
+  itself): repro through a real boot → title → level sequence.
+
+- **A texture re-declared in another format must be normalised with the geometry it was IMPORTED with (D245).** GE's sky water loads a CI8 image and draws it through an RGBA16 tile; fast3d imports it as CI8 (D229) but its triangle path computed the UV divisor from the RGBA16 tile (half the width) and the whole mip-chain height (43 rows, not the 32-row mask period). Anything that changes the importer's format/extent must change the tri-path `tex_width/tex_height` with it, and wrap must equal the N64 mask period.
+- **CPU-built RDP triangles need float vertices, not `Vtx` (D245).** Where GE builds RDP edge/texture coefficients on the CPU (sky/water), 32-bit S/T and positions are normal; squeezing them through s16 `tc`/`ob` costs visible precision on horizon-scale geometry. Use `G_FLOATVTX_EXT` (`port/include/floatvtx.h`).
 
 ## D. N64 hardware idioms fast3d does not emulate
 
@@ -680,6 +805,41 @@ through a converter or a runtime bswap fixup reads scrambled.
   backface culling already has, or it'll silently eat near-camera geometry
   exactly where a port is most likely to get scrutinized (doorways,
   tight corridors).
+- `gfx_sp_tri1`'s `G_CULL_BOTH` backface-cull cross-product (`gfx_pc.cpp`,
+  right below the D233 trivial-reject guard) divides raw vertex `w` with
+  no epsilon guard. A vertex at/near `w≈0` during a near-plane crossing
+  can NaN/Inf the cross product, which silently fails both the
+  `cross<=0` and `cross>=0` cull branches and lets a triangle draw that
+  should have been backface-culled — a candidate for D288 (Silo intro
+  stray triangle), not yet confirmed against a live repro (M-152). Unlike
+  D233's fix, this one hasn't been shown to actually fire yet; it's a
+  code-review lead, not a confirmed mechanism.
+- **When chasing a missing UI element, split "game logic decides to draw
+  it" from "fast3d actually rasterizes it."** This codebase's decomp side
+  for menu/watch item rendering is consistently byte-matched and rarely
+  at fault; the recurring bug class is a combiner/blend-mode or
+  texture-format edge case in `port/fast3d/gfx_pc.cpp` for a one-off
+  translucent/`PROP_TYPE_PLAYER` draw that doesn't share a code path with
+  the common in-level rendering (D172 particle color, D217/D228 CI/IA16
+  palette, D229 water blend, D233 invisible-through-doors, and D290's
+  leading hypothesis — the watch controller graphic's fade-in uses a
+  low-alpha `PROP_TYPE_PLAYER` combiner state nothing else exercises).
+  Confirm the `src/game/` side is clean first (item ID, resource-table
+  entry, model header, generic equip/gate pipeline) before spending time
+  in fast3d — but once it is, look there, not back at the decomp logic.
+- **`portHeartbeatCheck` (`port/src/libultra.c:218`) hard-caps at 3
+  reports total per process lifetime, by design** ("stop after a few
+  reports"). When chasing a long-idle hang (D287), "the heartbeat stopped
+  logging" is that cap firing, not evidence the hang resolved, worsened,
+  or changed mechanism — don't read silence from this diagnostic as a
+  signal. Gate a raised/unlimited report count behind its own env var for
+  these investigations instead of trusting the default cap's silence.
+- **Before citing a `scratch/*.log`/`.txt` capture as "evidence" in a
+  finding, grep it for the specific numbers/strings the write-up claims**
+  (D287): a file with the right name on disk is not proof it holds the
+  claimed capture — this one turned out to be an unrelated normal-exit
+  run, not the freeze it was cited for, and the mistake propagated
+  through the entry unnoticed until a later static pass checked.
 - **D74 wrap-block is DEAD CODE** (`gfx_pc.cpp:1546/1551`): guard is
   `cms & G_TX_WRAP` but `G_TX_WRAP == 0`, so always false (line 1887 does
   it right with `cms == G_TX_WRAP`). And if it did run it indexes
@@ -776,6 +936,52 @@ through a converter or a runtime bswap fixup reads scrambled.
   (ginit.s is missing from this repo; the expansion lives there), not UV,
   shade, or the combiner.
 
+## D14. LOD tile selection is a 2-cycle-only RDP feature; stale `G_TL_LOD` must not affect 1-cycle texture rectangles (D341)
+
+`G_TL_LOD` is sticky other-mode state. Game code that draws a 1-cycle texture rectangle after an LOD-textured draw never clears it, because on the RDP it is irrelevant outside 2-cycle mode. fast3d's LOD/detail tile folding (D107/D236) must therefore not run for 1-cycle texrects, or they sample a neighbouring tile's stale declaration. Related: textures the CPU rewrites in place at recurring addresses (dyn pool) need a content-hashed cache key, and remember game code reaches them through the 0x80000000 KSEG0 mirror.
+
+## D12. "Collapse an LOD binding to tile 0" is wrong for a two-texture DETAIL binding (D236)
+
+**M-198 (finding D236 pass 26).** GE's `texLoadFromGdl` resolves a room DL's
+`G_NOOP` texture reference through one of three handlers, chosen by
+`in->words.w0 & 7` (`src/game/tex.c`):
+
+| type | handler | TMEM layout |
+|---|---|---|
+| 0 `TEXTURETYPE_LOD` | `texHandleType0` | ONE load block at TMEM 0; tiles 0..n are LOD levels **of that one image** |
+| 1 `TEXTURETYPE_DETAIL` | `texHandleType1` | TWO load blocks: the **detail** texture at TMEM 0, the **base** image at TMEM `texGetSizeInBytes(detail,0)` on tiles 1.. |
+| 2 `TEXTURETYPE_MIPMAP` | `texHandleType2` | as type 0 |
+
+fast3d's `gfx_lod_tile_offset` (`port/fast3d/gfx_pc.cpp`) folded **every**
+`G_TL_LOD` draw to tile 0, on the reasoning (D107) that "GE loads the whole mip
+chain at TMEM 0". That is true for types 0 and 2 and **false for type 1**,
+where TMEM 0 holds the detail texture and the image you actually want is on
+tile 1. The port therefore drew the detail texture in place of the base image —
+and never even *imported* the base image, so every probe looking for it came
+back empty.
+
+On Surface 1 this was the whole of D236: all four treeline cards
+(`tex1198`–`tex1201`, RGBA5551 64×17 cut-outs) are type-1 bindings sharing one
+detail texture, `tex2465` — an opaque 32×32 IA8 noise tile. Result: an opaque
+tiled noise wall where the treeline belongs, for 20+ investigation passes.
+
+**Tells.** (a) A texture the game demonstrably decodes into the pool is never
+imported by the renderer — that is a *binding* bug, not a decode, alpha, mip or
+geometry bug, and no amount of work on the texture's contents will move it.
+(b) The wrong thing drawn is itself a real, correctly-decoded texture from the
+same draw — look for a second texture bound by the same command.
+
+**Discriminating the two layouts at draw time.** Prefer an invariant that a mip
+chain can never satisfy. Tiles 1.. of a type-0/2 binding are LOD levels of tile
+0's image, so they necessarily carry the **same `fmt`/`siz`**; a type-1 pair is
+two unrelated textures and generally does not. Deliberately choose the
+asymmetric test — a mip chain can never trip it, and a detail pair that happens
+to share a format merely keeps the old behaviour. Two weaker discriminators
+were tried live and both misfire: "tile 1 sits at a different TMEM address"
+matches ordinary mip chains (their levels are at different TMEM offsets too),
+and "tile 1's TMEM slot has a registered load" matches them as well, because
+`rdp.loaded_texture[]` is persistent state that is never cleared between binds.
+
 ## D2. The HUD/model "X-mirror" (D114/D116): RESOLVED, it was an upside-down capture
 
 **M-33 (finding D168).** There was no mirror. `gfx_opengl_dump_bound_fbo`
@@ -930,6 +1136,12 @@ silently disappears.
   upstream. This class isn't limited to display-list cursors; audit any
   `-O2`-only "quietly broken but not crashing" symptom for the same shape.
   Fix: `return` under `#ifdef AVOID_UB` (`#else` keeps the N64 body).
+- Instances (latent, 2026-09-25 Q7 warning audit): `constructor_menu07_missionsel()` and
+  `constructor_menu0D_missioncomplete()` (`src/game/front.c`), both `DL = f(DL)` at the
+  caller. Currently harmless: old/new objects disassemble identically at `-O2` (GCC
+  keeps `frontDrawCursor()`'s result in `rax`), but a clang/arm64 build is not bound
+  by that. `return DL;` under `#ifdef AVOID_UB`. A `-Wreturn-type` sweep lists the
+  remaining candidates; the other 7 current hits have callers that ignore the value.
 - The one flagged in-source with an explicit comment is
   `grep -rn "missing a \"return\"" src/` (`gunfire.c`). Others (like D77's)
   exist without the banner; suspect this class whenever an `-O2` build
@@ -980,6 +1192,15 @@ and turns every such overrun into a fatal `*** stack smashing detected ***`
   (bail is `if (cat >= 41)`, checked once per outer loop → writes `[40..]`);
   `bondview2.c` `bondviewCalcIntroSwirlCamera` `f32 pointbuf[10]` written
   `[-3 .. 11]`.
+- Instance (D295/M-148): `front.c:2616` `char difficultytext[4]` receives
+  `strcpy("00 Agent")`/`strcat("\n")` — the NUL lands exactly on the adjacent
+  `textpos.p[0]` (y-coord), which is then re-stored; when y ≥ 0x80 the string
+  carries a high-bit byte into `textRender` → JPN-glyph path → NULL deref of
+  `g_JpnCacheCacheItems` (`language.c:320`). Same class, different fatality:
+  no canary involved — the clobbered *neighbour* changes control flow. On N64
+  the identical overflow is cosmetic (the JPN-cache pointer is valid memory in
+  any language); the crash severity is a PC artifact of that global being NULL
+  outside Japanese mode.
 - Fix policy: **`-fno-stack-protector` globally** (`CMakeLists.txt`) so Linux
   matches the N64 and MinGW builds; the code is byte-matched to the ROM and
   cannot be "fixed" per site without diverging. Where a case is cleanly
@@ -992,8 +1213,166 @@ and turns every such overrun into a fatal `*** stack smashing detected ***`
 - Distinct from D7 (`va_list` UB) and D6 (missing `return`) but the same
   "works on N64 + MinGW, fatal on hardened Linux" shape.
 
+## D9. Changing a PRNG/CRC implementation invalidates persisted derived state — save checksums are de facto file format
+
+D284 (M-139b) fixed `port/src/random.c`'s `dsll32`/`dsrl32` semantics and the
+entry claimed "savegames unaffected (seed isn't save state)". It was wrong:
+`fileGenerateCRC` (`src/game/crc.c`) — the per-slot validation checksum checked
+by `fileValidateSaves` (`file2.c:544`) — runs `randomGetNextFrom` off its own
+**local constant seed**, so every stored slot CRC is a fingerprint of the PRNG
+implementation that wrote it. Verified against a real v0.2.x save (GitHub #87):
+pre-fix PRNG reproduces all five stored CRCs bit-exact, post-fix matches zero →
+first launch of any post-fix build **silently wipes every existing player's
+entire campaign** (D295 M-148). Generalizable rule for this port: before
+changing anything that feeds persisted derived state (PRNG, CRC/hash routines,
+endian/byte-order helpers used by serializers), audit *all* consumers whose
+output is stored on disk — not just the in-memory streams. A "port-only" fix to
+a checksum primitive is a save-file-format break unless old and new outputs are
+made mutually acceptable (dual validation / one-time migration).
+
+## D10. A "skip to state X" port shortcut must replicate every side effect of the screens it skips, not just the terminal flags
+
+D216's `Game.SkipIntro` jumps straight from boot to `MENU_FILE_SELECT`,
+skipping the legal screen + Nintendo/Rare/GoldenEye logo attract loop, by
+directly setting the handful of state-machine flags (`is_first_time_on_main_menu`,
+`prev_keypresses`, `maybe_is_in_menu`, `menu_update`) that the normal intro
+path would have arrived at. Its original comment claimed this "reuses the
+game's own post-intro route" — true for the menu *flags*, but the skipped
+`init_menu00_legalscreen()` also has a one-time side effect with no flag of
+its own: it calls `fileValidateSaves()`, the only place `saves[]` is ever
+populated from EEPROM. Skipping it left `saves[]` all-zero, and file-select's
+unguarded `fileGetIsCheatUnlocked()` crashed selecting any folder except the
+one a zeroed `save_data` happened to decode to (D299). Generalizable rule:
+when adding a port shortcut that jumps over N64 screens/states, enumerate
+every side effect those screens' `init_menuXX_*()`/`update_menuXX_*()`
+functions perform — not just the menu-transition flags — and replicate the
+non-flag ones (data loads, one-time validation, subsystem init) explicitly.
+Grepping the skipped `init_*`/`update_*` functions for calls with no
+matching state flag is the concrete check.
+
+## D11. A chr's own per-tick animation-position logic can silently overwrite an AI script's scripted position in the same frame (D243)
+
+`chrTick` (`src/game/chr.c:2442`) always runs one of three `chr->actiontype`-
+gated branches (`ACT_ANIM`/`ACT_STAND`/else, `chr.c:2578-2616`) that call
+`chrUpdateAnim`/`modelTickAnim` — ordinary per-chr animation/locomotion
+logic with no check for whether the chr is currently being driven by a
+scripted cutscene camera/AI-script position write instead. If something
+else (an AI script's `GOTO`/teleport, a cinema-pad move, D243's
+`CHR_BOND_CINEMA` teleport) writes `prop->pos` earlier in the same frame,
+`chrTick`'s own animation-position write can silently overwrite it before
+the model transform is computed — two writers racing for the same field
+within one tick, no error, no crash, just whichever runs last wins. This
+produced D243's "frozen render position that doesn't track the smooth
+scripted sweep" symptom: a first pass (M-159) wrongly attributed it to
+the on-screen/frustum-visibility gate (`posIsOnScreen`) skipping the
+render-transform refresh on off-camera ticks — REFUTED by a live capture
+that logged BOTH the pre-`chrTick` position (from the AI script, smoothly
+sweeping) and the post-`chrTick` position (frozen) for the same frame
+numbers, with the visibility gate returning true throughout. **The
+generalizable check:** when a rendered position looks "frozen" or
+lagging behind a scripted/AI-driven `prop->pos`, don't assume a
+visibility/culling gate is skipping an update — log the same field both
+immediately before and immediately after the suspect tick function to
+see whether something *inside* that function is overwriting it. A
+visibility gate stopping updates and a competing writer stomping them
+produce the same visual symptom but need opposite fixes.
+
+**Update (same D243 investigation, later in the same project's life): fixing the field you found the bug in doesn't mean you've fixed what's rendered — check which field the CONSUMER actually reads.** Having found `chrTick` overwrites `prop->pos`, two live-playtest cycles were spent neutralizing exactly that overwrite (save/restore `prop->pos` around `chrTick`) — it worked completely (confirmed in logs: the field went smooth) and yet the visible symptom (camera shake) was completely unchanged. The reason: the camera's look-at filter doesn't read `prop->pos` at all — it reads `field_488.pos`, a *different* field written from a *different* data path (`render_pos`, the model's animated-skeleton transform, computed independently of `prop->pos` inside the same function). Both fields happened to show the same "period-4 cycling" symptom, which made them look like one bug through a probe that only logged `prop->pos` — they were two independent outputs of the same underlying animation-tick call, and only one of them was what actually got rendered. **The generalizable check, sharpened:** once you've confirmed a field is being overwritten, don't assume that field is what the visible symptom's consumer (a camera filter, a draw call, a collision check) actually reads — trace the consumer's own read site explicitly and confirm it's the same field before spending a live-test cycle suppressing the wrong one. A quick static check (grep the consumer's exact read expression) is far cheaper than a live playtest.
+
+**Update 2 (same investigation, immediately after): freezing a *value* and freezing a *pointer target* are different operations — treating them the same crashed twice.** Extending the same freeze technique to `render_pos` (a `Model*` field, unlike `field_488.pos` a plain value) by skipping the call that reassigns it (`subcalcmatrices`) seemed equivalent to M-167's "skip the write" but wasn't: `render_pos` is a pointer into a per-tick dynamically-reallocated arena, and skipping its reassignment only works if the pointer it's left holding is still valid — which depends on model lifecycle, not just on this tick's logic. Two fixes in a row tried to detect "is it safe to skip" by inspecting either the pointer's *value* (a sentinel check, `!= NULL && != -1`) or a *cached identity* (comparing the pointer against a remembered "already validated" pointer) — both crashed, because **the allocator reuses model-pointer addresses across genuinely different logical model instances**: a freshly-`CREATE`d model can land at the exact address a previously-removed model occupied, so both the sentinel check and the identity check wrongly conclude "this is already valid" for an instance whose `render_pos` is still an uninitialized tombstone. This is the same "don't guess validity from a value that can coincidentally look right" trap as the paragraph above, encountered a second time from a different angle (a *pointer's* target identity, not a *field's* content). **The robust fix:** never skip the call that establishes the pointer's validity — let it always run — and apply the freeze as a *contents* copy afterward, on top of a buffer that's now unconditionally guaranteed valid. If you must "hold something steady" and that something is reached through a pointer that some other code reassigns, freeze the *pointee's bytes*, not the *act of assignment* — the assignment is usually also the thing keeping the pointer sane.
+
+## D12. Depth precision: the port matches N64 exactly — z-fighting seen on PC is probably faithful (D306/D308)
+
+When a user reports z-fighting, do NOT assume the software renderer has less depth precision than the RDP. Verified for GE: the RSP's vertex transform (`rsp/graphics/gmain.s`) writes post-transform x/y/z/w back to the vertex buffer as **full 32-bit 16.16 fixed-point** (`sdv` stores), not s16 8.8 — the RDP interpolates from full-precision NDC and quantizes once, into its 24-bit z-image. The port keeps floats through `gfx_sp_vertex` and writes a `GL_DEPTH24_STENCIL8` buffer: same or better precision at every stage, same near/far. So coincident geometry authored into the level fights on both platforms; a PC-only explanation needs positive evidence (an N64 reference of the same spot), not just the existence of the symptom. A mitigation like switching to 32-bit float depth would *reduce* fighting but diverge from N64 behavior — that's a rule-2-style decision, not a silent fix.
+
+**Probe technique that worked (vs. three variants that didn't):** detecting z-fighting from emitted triangles requires filtering out (a) tessellation gradients — adjacent tris of one surface have near-equal depths by construction — and (b) camera-motion coincidences — as the camera moves, unrelated world points pass through the same screen cell and their depths happen to sit close. What survives both: a coarse screen-cell grid keeping a short per-cell depth history, flagging only **non-monotonic** (a-b-a) oscillation within a small tolerance that **recurs many times at the same cell**. Monotonic drift = gradient; one-off close pairs = motion artifact; sustained recurrence = a real fight. `GE_ZF` in `port/fast3d/gfx_pc.cpp` implements this (`GE_ZFTOL` tolerance, `GE_ZFBOX` region filter). **Caveat (M-201):** `GE_ZF` actually quantises NDC z to ±255, not 24 bits, so at its default tolerance it flags unrelated nearby surfaces; treat a hit as a lead, not proof. Before calling anything "z-fighting", check the separation against the near plane: at close range 24-bit depth resolves far finer than any non-coplanar model parts, so "whole surfaces in the wrong order" there is depth *state* or geometry, not precision. Use `GE_D306C` (per-triangle depth-state census) for that; D306 turned out to be authored geometry seen from an unusual camera.
+
+## D13. Per-render accumulation is not associative: the port's 1 tick/frame can reach states the N64's 2–3 ticks/frame never did (D329)
+
+GE on N64 renders gameplay at ~20–30 fps, so `g_ClockTimer` (= `speedgraphframes`, 60 Hz ticks per rendered frame) is normally 2–3. The port at 60 fps gives 1. Code that folds `numticks` ticks into **one** downstream call is not equivalent at different granularities. `modelTickAnim` sums `playspeed*speed` over the ticks, then makes one `modelSetAnimFrame2WithChrStuff` call, which only moves `framea`/`frameb` when `floor(frame)` crosses an integer. At speed < 1 and 1 tick/frame a clamped (`framea == frameb`) non-looping anim never crosses, so it stays pinned even after its endframe is raised. At 2+ ticks it crosses on the next frame. Result: permanent guard freezes on PC (D318/D320) that the console could not sustain.
+
+- **Tell:** a state that holds forever at 60 fps, is frame-exact (integer frame, `fa == fb`), and has a per-tick step < 1.0 unit.
+- **Repro correctly:** force the granularity with `GE_D318B_CLK=N` (TEMP probe, lockstep N ticks/frame) and A/B N=1 vs N=2. Wall-clock runs on a slow host (WSLg renders ~5 fps → mixed clk 1–6) and `GE_DETERM=1` (advances per VI-retrace request, also mixed clk) both give uncalibrated results.
+- **Where else to look:** any `for/while (numticks)` accumulator followed by a single threshold/floor consumer; D193 (AI locomotion rate) and D243 (cutscene `numticks` bursts) touched the same axis from the other side.
+
+## D15. A texture-rectangle idiom that is sub-1-native-pixel tall relies on the RDP's floor-based fixed-point scanline stepping — now replicated in `gfx_draw_rectangle` (D397, RESOLVED 2026-09-28)
+
+GE's front-end vertical-gradient trick (`titleRenderFolderMenuBackgroundLines`,
+`src/game/title2.c`) draws a tall image as 299 separate 1-scanline-tall
+`gSPTextureRectangle`s, one per source row, each tinted by a per-row
+interpolated `gDPSetPrimColor`. The lower-right Y coordinate uses the
+universal N64 idiom `((y+1)<<2)-1`, which in U10.2 units is **3, not 4** — a
+0.75-native-pixel-tall rect, not 1.0. This is correct *on real hardware*
+specifically because the RDP's scan converter steps by truncating
+(flooring) the fixed-point Y to an integer scanline before testing coverage,
+so `y*4+3` still falls in scanline `y` and nothing else — the "-1" is a
+hardware-truncation idiom, not a literal float height.
+
+`gfx_pc.cpp`'s `gfx_draw_rectangle` does not replicate that truncation: it
+converts the U10.2 corners straight to continuous NDC floats
+(`ulyf/lryf = ±(y / (4·HALF_SCREEN_HEIGHT)) + 1`) and hands them to the GPU's
+own continuous rasterizer, which uses pixel-center/coverage rules, not
+floor-stepped scanlines. A rect that is 0.75 (native) pixels tall, stacked
+299 times with each row offset by exactly 1.0 native pixel from the last,
+does not reliably rasterize as "exactly the one scanline the N64 idiom
+intended" under a continuous rasterizer — whether a given row rounds to 0 or
+1 device pixel depends on where its fractional edges land relative to the
+device pixel grid, and that phase drifts row-to-row (worse under any
+non-integer native→window viewport scale, `gfx_adjust_viewport_or_scissor`'s
+`ratioX`/`ratioY`). Stacked over ~300 rows filling the screen, sporadic
+per-row rounding reads as a periodic horizontal comb/interlace — this is the
+leading mechanism for D397's "interlaced" file-select background and intro
+gun-barrel, and is a **first-render, not re-entry-triggered** artifact
+(unlike D182), because it is a rasterization property of the geometry itself,
+not stale state.
+
+**Tell:** any GE front-end/menu draw that fakes a large image or gradient by
+stacking many independent 1-scanline (or otherwise sub-1-native-pixel-tall)
+`gSPTextureRectangle`s rather than one multi-row texture — the `(<<2)-1`
+lower-right idiom is the signature to grep for. A single such rect is
+invisible (sub-pixel rounding on one edge); many stacked ones make the
+rounding pattern visible as banding.
+
+**Fix (landed 2026-09-28, RESOLVED):** `gfx_draw_rectangle` (`gfx_pc.cpp`) now replicates the RDP truncation. After the sub-pixel offset is applied, it floors the U10.2 top edge to its scanline and the bottom edge to the *last covered* scanline — the RDP scanline range `[top_scan, bot_scan+1]` — before converting to NDC: `top_scan = uly>>2`, `bot_scan = (lry-1)>>2`, then `uly = top_scan<<2`, `lry = (bot_scan+1)<<2`. This is a **no-op for whole-pixel rects** (their edges are already `4k`/`4k−1`, and the `(<<2)−1` bottom idiom already yields `bot_scan` = the intended last row), so only sub-pixel-tall strips change. **Confirmed by a falsifiable 3-scale PCDUMP test:** the comb period is fixed at ≈3 *native* rows across 640/1024/1280 (window-period = 3×scale) — the beat of 0.75-px strips at a 1.0-px pitch — exactly the fixed-point-flooring signature, ruling out the scale-invariant LERP/CC factor. Verified by playtest: gun-barrel + file-select gradient render clean, comb gone.
+
+**Not the cause (checked and ruled out for D397):** the CC/LERP scaling of
+`ENV_ALPHA` as `value/255.0f` (`gfx_pc.cpp` around the `G_CCMUX_ENV_ALPHA`
+case) is byte-identical to the Perfect Dark PC port's (`gfx_pc.cpp` in the
+local `pd_port` checkout) — same formula, no special-cased "5-bit RDP
+coefficient" scaling in either port. The real RDP color combiner's A/B/C/D
+inputs are 8-bit values (PRIM/ENV alpha come from an 8-bit `gDPSetEnvColor`
+field); there is no coarser-precision quirk to correct here. A uniform
+darkening from a nonzero `ENV_ALPHA` LERP factor is very likely faithful
+(possibly authored/original-dev-intentional tinting), not a bug — do not
+"fix" it without an N64/1964-GEPD reference screenshot proving otherwise.
+
 ## E. Process / method notes
 
+- **Never `exit()` while another thread may be inside the GL driver (D344).**
+  The GL context lives on the render (scheduler) thread; quit events arrive on
+  other threads. Request the quit (`videoRequestQuit`), let the render thread
+  `glFinish` + unbind at a frame boundary and park, then exit from the host.
+  An unclean GL teardown bugchecked the maintainer's PC (0x119, HAGS on).
+  Harness runs should end with `GE_QUITFRAME=<n>`, not a `timeout` kill.
+- **Headless front-end scripts: turn the mouse off (D343).** In menus the
+  pointer follows the real OS mouse (WI-2 absolute tracking), so the desktop
+  mouse moves the in-game cursor mid-`GE_INPUTSCRIPT`. Put
+  `[Input] MouseEnabled = 0` in the pinned test ini. Script "frames" were
+  about one per rendered frame on the file select screen; calibrate with a
+  log, not by assumption.
+- **`textMeasure` height is 0 without a trailing newline (D343).** It only
+  counts completed lines. Measure `"text\n"` when you need a height (front.c's
+  folder text does this); the width is unaffected.
+- **Periodic audio glitches: measure the host audio device before touching
+  the pipeline (D322).** A clock-regular overflow/garble pattern (~5 min period,
+  ~45 s bursts, independent of level and load) looked like a port timing beat
+  and cost several game runs to chase. `tools_pc/sdl_drain_monitor.c` opens SDL
+  exactly like `port/src/audio.c` with no game and no window; on the
+  maintainer's Focusrite USB interface it showed the same ~312 s drain dips
+  (to 88 %) outright, and running it on several SDL backends at once showed the
+  culprit was SDL2's WASAPI path, not the device (DirectSound was clean; the
+  port now prefers it on Windows). Run it first on any "audio gets garbled"
+  report, and compare backends with `SDL_AUDIODRIVER` before blaming the hardware.
 - Investigation loop is: reproduce → env-gated capped probe → root-cause
   → narrow `#ifdef PORT` fix → visual verify (`GE_PCDUMP` +
   `tools_pc/pixcount.py` vs `docs/reference/n64-footage-*`).
@@ -1003,6 +1382,51 @@ and turns every such overrun into a fatal `*** stack smashing detected ***`
   writing anything new; same Rare engine family.
 - Don't re-investigate a closed §F finding or re-derive a format spec
   that already has a converter.
+- **When re-implementing a ROM bitstream/codec offline, PORT the derivation
+  from the decomp; never reconstruct it from the comment.** A half-right
+  bitstream parser in this codebase does not fail loudly — it returns
+  confident, plausible, wrong output. Three hits in four D236 passes:
+  (1) a texture-header parse that omitted the leading control byte
+  (`image.c:2568`) still produced sensible-looking formats and dimensions,
+  and was only caught by counting implausible entries (1020/2699 vs 1/2699
+  when correct) and noticing the format nibble only ever took values
+  0/4/8/12 — the tell that a field was straddling a boundary;
+  (2) omitting the per-image byte-align at the end of each LOD
+  (`image.c:1096`: discard the partial byte, and skip a whole byte when
+  already aligned) silently desynchronised every LOD after the first;
+  (3) `texInflateRle`'s run-length `fudge` was *guessed* from the doc comment
+  instead of ported from the loop at `image.c:1605`, and still decoded
+  images — just with the wrong alpha coverage (66.7% vs the correct 43.1%).
+  Practical rules: copy the arithmetic statement-for-statement even when it
+  looks like it could be closed-formed; build a cheap global plausibility
+  counter into the tool and print it every run; and cross-check one decoded
+  artifact against an independent expectation (here, that a LOD chain's
+  dimensions halve exactly and its alpha coverage stays roughly constant)
+  before trusting any number the tool emits.
+
+- **A negative result from a diagnostic is worthless until the diagnostic has
+  been shown capable of producing the positive.** Two independent hits: D219's
+  "verify diagnostic caps exempt the real target signature before trusting
+  'clean'", and D236 pass 21, where a static setup scanner located GE's `PROP`
+  enum with `startswith("typedef enum PROP")` — which matches
+  `typedef enum PROPFLAG` hundreds of lines earlier, yielding an enum with **no
+  `PROP_*` members at all**. Every prop id then resolved to `?` and every
+  "foliage props placed" count came back 0, which is exactly what a clean,
+  meaningful negative looks like. Build the positive control **into** the probe:
+  have it print what it is capable of matching (`foliage props recognised (9):
+  …`) and fail loudly when that set is empty, so the failure mode cannot be
+  read as a finding. Applies equally to grep-based audits over generated C,
+  where near-miss identifier prefixes (`PROP` / `PROPFLAG` / `PROPDEF_TYPE`) are
+  the norm.
+
+- **`docs/dev/findings-index.csv` is generator-derived** (`tools_pc/gen_findings_index.py`): the status cell is normalised from the `## Dxx` entry's §F summary-table row in `findings.md`, so hand-editing the CSV is silently reverted on the next regen (hit live in the D219/D252 M-158 session). Update the table row, then run the generator.
+- **Every game launch rewrites `data/ge007.eep`** (the eeprom shim stores on
+  every write; validation resets, cheat patches and normal saves all write).
+  When restoring a specific save artifact for a controlled test (e.g. an issue
+  reproduction), restore it *after* any sweep/verify run — or re-hash after
+  each run — not before: `tools_pc/level_sweep.sh` alone boots the game 21
+  times against `data/` and will clobber a pre-run restore (caught live in the
+  D295 M-149 session; "verified" must mean checked at report time).
 - **The port is NOT frame-deterministic** (D117): `osGetCount()` is
   wall-clock on PC, and GE is a variable-timestep sim
   (`frametiming.c waitForNextFrame` → `deltaFrames` = 60 Hz ticks of real
@@ -1013,6 +1437,38 @@ and turns every such overrun into a fatal `*** stack smashing detected ***`
   fixed-tick mode was assessed not-narrow (redesigns retrace/tick
   semantics); design is in §F D117 if someone picks it up, after which
   `framediff.py --exact` becomes usable.
+- **A "deterministic boot" flag (`-level_XX`) pins the level and starting
+  state, but NOT the camera's later path through it — don't assume two
+  captures from the same boot flag are comparing the same view.** D236
+  pass 10 (M-155) found a render-mode-class triangle count that looked
+  "run-to-run dependent" across separate captures using the same
+  `-level_36` boot; three independent re-launches (including one with a
+  full `GE_INPUTSCRIPT` sustained-rotation sweep) actually produced
+  byte-identical, fully deterministic per-frame counts — the real
+  variance was the boot's own scripted intro camera walking from an
+  outdoor room into an indoor one at a fixed frame, and the two captures
+  being compared had sampled before vs. after that walk (or against an
+  unrelated live/free-play session entirely). **Before concluding a
+  count/state is nondeterministic across runs of the same boot flag,
+  correlate against a room/position probe (`GE_D104`-style) in the SAME
+  run** to rule out "the camera simply isn't where you assumed it was
+  yet" before chasing an instantiation or streaming bug.
+- **A level's opening cutscene is not necessarily input-inert, and
+  `GE_INPUTSCRIPT` stick holds during it are not necessarily useful.**
+  D236 pass 11 (M-155): holding `SUP`/`SDOWN` from frame 0 of the
+  `-level_36` deterministic boot changed which room the player occupied
+  at the very first probe sample (`curRoom` 12/7/13 depending on the held
+  direction) — the pre-transition window is NOT purely camera-scripted
+  with input discarded, as pass 10 might suggest. But none of forward,
+  backward, or a `START`-skip attempt could keep the camera in the
+  outdoor room past the scripted indoor transition, which fired at
+  roughly the same real time regardless of held direction and *earlier*
+  when `START` was pressed to skip faster — i.e. the transition looks
+  timer/event-driven, not distance-to-a-trigger-driven. **Don't assume a
+  scripted sequence's transition point is walkable-around just because
+  input has *some* visible effect during it** — test whether the specific
+  transition you care about is time-gated vs. position-gated before
+  investing in a nav script to avoid it.
 - **Anything blocking on the scheduler thread throttles the whole sim**
   (D186, cf. D134). The gfx task runs synchronously on `src/sched.c`'s
   thread, and that same thread delivers VI-retrace events; any `sysSleep` /
@@ -1203,3 +1659,87 @@ and turns every such overrun into a fatal `*** stack smashing detected ***`
   one silently drifts from the other; when investigating a decode bug, diff
   the suspect path against its sibling path for the same format before
   re-deriving the bit layout from scratch. §F **D228**.
+- **A Claude Code session's default `Bash` tool is NOT the MSYS2 MINGW64
+  shell the build needs, even when `uname -a`/`$MSYSTEM` claim it is (M-140).**
+  On this box the tool's shell is Git-for-Windows Bash (root mounted from
+  `C:/Program Files/Git`), which sets `MSYSTEM=MINGW64` and reports
+  `MINGW64_NT-...` from `uname` for compatibility — both of AGENTS.md's own
+  “are you in the right shell” checks pass while `cmake`/`ninja`/`gcc` are
+  still missing from `PATH` (they resolve at `/c/msys64/mingw64/bin` and
+  `/c/msys64/usr/bin`, not `/mingw64/bin` — that path exists but is a
+  Git-Bash stub, not the project's real MSYS2 install). Symptom if you build
+  anyway with only Git-Bash's own `gcc`/toolchain state: `cmake: command not
+  found`, or (if some `gcc.exe` further down PATH resolves) every compile
+  fails with `Cannot create temporary file in C:\Windows\: Permission
+  denied` — a native Windows exe's `GetTempPath` falling back to `C:\Windows`
+  because the child process doesn't actually see a usable `TMP`/`TEMP` the
+  way it does when launched from a real MSYS2 shell window. Fix: explicitly
+  `export PATH="/c/msys64/mingw64/bin:/c/msys64/usr/bin:$PATH"` (adjust if
+  MSYS2 is installed elsewhere) before `./build-pc.sh`/`ninja`/`cmake` in any
+  Claude Code Bash-tool session; do this once per session, first thing, not
+  reactively after a mystery failure. Also: `cd` with a *backslash* Windows
+  path (`cd C:\Users\...`) is unreliable in this same shell and can silently
+  mis-parse to a mangled path on a later command in the same tool call —
+  prefer `cd /c/Users/...` (forward slashes) for the build working directory.
+  **The PATH fix alone can still leave the *link* step broken (M-141):**
+  compiling succeeds but `ld.exe` fails with `cannot find @C:\Windows\Temp\
+  ccXXXX: Invalid argument` if `TMP`/`TEMP` are unset or point at a
+  non-writable/non-real path like a literal `C:\Windows\Temp` string — the
+  response-file `ld` uses for the link command has to land somewhere this
+  shell's child process can actually write and re-read. Fix: `export
+  TMP=... TEMP=...` to a real writable per-session directory (the Claude
+  Code scratchpad path works well) before `ninja`/`build-pc.sh`, not just any
+  Windows-looking path string.
+- **A backgrounded `ge007.x86_64.exe` launch from this Bash tool does not
+  reliably die to `pkill -f ge007.x86_64.exe`** (M-155, D288 session): the
+  process appears in `ps aux` as bare `ge007.x86_64`, no `.exe` suffix, so
+  the `-f` pattern match on the full name silently fails and the game
+  window (and its log-writing) keeps running well past the intended
+  `sleep N` capture window — one session let a stray instance run ~90s
+  longer than intended before it was caught. Use `taskkill //F //IM
+  ge007.x86_64.exe` instead to reliably terminate it from this shell, and
+  `ps aux | grep -i ge007` to confirm before moving on — don't trust a
+  `kill`/`pkill` exit code alone.
+- **Headless visual verification of a rendering bug is possible without a
+  live human** (M-156/M-157, D252/D219 sessions) — combine `GE_INPUTSCRIPT`
+  (scripted controller input, e.g. `Z` pulses to fire a weapon) with
+  `GE_PCDUMP="lo-hi:step"` (writes `./ppm/frame_NNNNNN.ppm` — NOT a separate
+  configurable output dir, just `./ppm` relative to cwd; `GE_MKDIR` creates
+  it) in the *same* run, then actually open the resulting PPMs (Python
+  `PIL.Image.open(...).convert('RGB')` reads them fine, no format quirks)
+  instead of only grepping a probe's text log. A text-only probe proves a
+  code path fired; it does not prove what ended up on screen — several
+  long-OPEN findings (D290/D291/D294, and D252/D219's whole "rainbow
+  particle" family before this session) were stalled for lack of eyes on
+  the actual pixels, not for lack of a working probe. Build a low-res
+  contact-sheet montage first (tile many frames small, e.g. 160×120, to
+  scan for the moment of interest cheaply) before zooming into individual
+  full-res frames — full Dam/Bunker1 frames are 3072×1728, too large to
+  eyeball one at a time across a whole capture window.
+- **A crash fault address of `0xffffffffffffffff` on x86-64 usually means a
+  non-canonical #GP from a garbage-high-bits pointer (bits 63:48 not a sign
+  extension of bit 47), not a computed `-1` sentinel** (cross-validated
+  against the sibling GEVR VR port, same decomp lineage — see
+  `scratchpad/GEVR-TRIAGE.md` item C; we independently hit the same register
+  shape in D191). Two companion habits worth keeping: re-read map anchors
+  from the freshly rebuilt map after every rebuild (a stale map silently
+  resolves the wrong symbol), and confirm the fault PC actually disassembles
+  on an instruction boundary before trusting a resolved symbol.
+- **Frame-rate assumptions — read before proposing any non-60 Hz mode**
+  (cross-validated against GEVR, `scratchpad/GEVR-TRIAGE.md` item B). GE's
+  logic is delta-scaled through `g_GlobalTimerDelta` (~216 call sites); the
+  PAL build (×1.2) is a shipping proof that delta-scaled code tolerates
+  other rates. But: **Bond's walk is frame-rate dependent by construction**
+  — `MoveBond` (`bondview2.c`) is an exponential approach toward a target,
+  advanced once per frame with no timestep, so convergence is measured in
+  frames, not seconds (GEVR measured ~1.487× walk speed at 90 Hz vs 60 Hz,
+  ≈90/60 exactly). Turn/aim *is* delta-scaled; walk is not. High-refresh or
+  uncapped presentation modes are therefore out of scope without a
+  game-logic change, which is forbidden — we tick at fixed 60 Hz (D52
+  pacing) by design, not as a limitation to fix. Also: `g_ClockTimer` must
+  stay integer (24 iteration sites depend on it); of 44
+  `/g_GlobalTimerDelta` divide sites, 40 are guarded (three different
+  spellings) and 4 are not (front-end cast camera `front.c:8271-8273`,
+  `propobj.c:~2393`) — those 4 rely on div-by-zero yielding NaN/inf without
+  trapping on both MIPS and x86-64 SSE, matching retail behavior; do not
+  "fix" them.

docs/security-and-fidelity-status.md

@@ -0,0 +1,109 @@
+---
+title: Security & fidelity status
+description: What a release actually installs (no networking, no telemetry, no ROM or assets)
+and how faithfully the port tracks the original N64 game's logic.
+---
+
+# Security & fidelity status
+
+This page answers two questions plainly: *what does installing this put on
+your machine*, and *how faithfully does the port actually reproduce the
+original N64 game's logic*. Both were reviewed end-to-end on 2026-09-15 and
+re-verified for the v0.3.0 release bundles on 2026-09-18 (bundle contents,
+no-networking source check, and the asset converter). The full engineering
+record behind each item is in the project's finding log
+([`docs/dev/findings.md`](dev/findings.md)).
+
+## What a release actually installs
+
+Each release (`goldeneye-pc-port-*-win64.zip` / `-linux-x86_64.tar.gz`)
+contains, and only contains: the game engine executable, a fixed set of
+standard runtime libraries (SDL2, zlib, and the MinGW/Linux runtime — no
+third-party downloads), the one-time ROM-to-PC asset converter, a README,
+and license texts. The build scripts hard-fail if a ROM image or an
+oversized blob ends up in the bundle. **No ROM, no game assets (textures,
+audio, models, levels, text) are ever shipped** — you supply your own
+legally-owned copy.
+
+At runtime, the engine:
+
+- has **no networking of any kind** (no sockets, no HTTP, checked directly
+  against the source),
+- has **no telemetry, crash reporting, or analytics** of any kind,
+- **never touches the Windows registry** and **never requests elevated
+  permissions**,
+- writes save data, config, and derived ROM assets only inside its own
+  folder — never to `%APPDATA%`, `Program Files`, or any system location.
+
+The one-time asset converter (`ge007-convert` / `prepare-assets.py`) — the
+part of the bundle most likely to draw suspicion, since it's the thing that
+reads your ROM and writes new files — has no network access at all,
+verifies your ROM against a fixed table of known retail GoldenEye 007
+hashes before touching it (an unrecognized file is rejected outright), and
+writes only inside the bundle folder. Its full source ships right next to
+the compiled version in every release if you'd like to read it yourself.
+
+See [`SECURITY.md`](../.github/SECURITY.md) for why the binaries are
+unsigned and what that means in practice (a SmartScreen prompt on first
+run, and why some antivirus engines flag the converter specifically).
+
+## Building from source
+
+Cloning and building pulls in only standard, well-known packages: MSYS2
+`pacman` packages on Windows, `apt` packages on Linux — no `npm`, no
+`cargo`, nothing downloaded at CMake configure time, no git submodules, and
+no prebuilt binaries checked into the repository. **One real gap**: the CI
+build installs `pyinstaller` from PyPI without pinning a version, which is
+used to freeze the release's asset-converter tool. It's a widely-used
+packaging tool, and what it packages is entirely in-repo, stdlib-only
+Python — but an unpinned dependency means a future PyInstaller release
+could change what ships without a corresponding diff in this repository.
+Pinning it is a tracked follow-up.
+
+One development-only backdoor exists in source builds: the `GE_DEBUG_UNLOCKALL`
+environment variable (`src/game/file2.c`) pre-unlocks all cheat options at boot.
+It is off unless explicitly set, changes no shipped behavior, and is documented
+here so the env-var surface stays fully accounted for.
+
+## Fidelity to the original N64 game
+
+The port's non-negotiable rule is that decompiled game logic is never
+changed — only genuine N64-hardware dependencies get a PC-side
+replacement, in the `port/` layer. This was audited directly:
+
+- **Region build macros** exactly mirror the original N64 Makefile's macro
+  sets for all three regions — verified line-by-line.
+- **The audio/library file classification** (which original files compile
+  vs. get PC-shimmed) exactly matches the project's own ground-truth
+  manifest — no silent gaps, no silent duplicates.
+- **The one shipped game-logic-adjacent change** (a portal-culling
+  float-precision fix, D271) is `#ifdef PORT`-gated, documented in the
+  finding log, and moves *toward* matching N64 behavior, not away from it.
+  Every other deviation from the decompiled source is one of the documented
+  32→64-bit pointer-width ABI corrections described above.
+
+**One issue, found and fixed before v0.3.0 shipped**: the port's
+random-number generator (`port/src/random.c`) was documented as a bit-exact
+port of the N64's PRNG, but wasn't — a shift-operation helper didn't match
+the real MIPS64 instruction semantics it was meant to mirror. This was
+independently confirmed by hand-tracing the assembly against the C port,
+tracked as finding D284, and fixed before the release (verified clean
+across a full level sweep — all 20 missions plus the ending sequence —
+no crashes). It affected loot placement, AI
+behavior variance, and replay-state determinism from the very first random
+draw, in every release before v0.3.0. Because of the fix, RNG-derived
+output — including the save-file CRC — changed, which meant existing save
+files and any previously recorded replays no longer validate; v0.3.0's
+release notes describe the automatic save migration that handles this. We'd
+rather say this plainly than let a "verified bit-exact" claim stand
+uncorrected, both when it was wrong and now that it's fixed.
+
+Everything else checked (the documented ABI/pointer-width exceptions used
+for the 32-to-64-bit transition, a sample of the finding log's own claimed
+fixes against the actual current code) matched what's documented.
+
+---
+
+*This page is kept current alongside future releases. Its source review is a
+manual, human-reviewed process today — see the project roadmap for plans to
+partially automate the mechanical parts of it.*

port/fast3d/gfx_api.h

@@ -47,9 +47,17 @@ void gfx_set_target_fps(int);
 void gfx_set_texture_filter(enum FilteringMode mode);
 void gfx_set_mipmap_filter(enum MipmapFilteringMode mode);
 void gfx_set_fix_mip_textures(int on);
+void gfx_set_detail_base_tile(int on);  /* D236: sample the base image of a DETAIL binding */
 void gfx_set_wrap_fix(int on);
 void gfx_set_anisotropy_level(int level);  /* 1 = off; clamped to GL max */
+void gfx_set_safe_area_crop(int on);       /* crop the N64 TV-overscan safe-area margin instead of showing it as black bars */
+/* On-window pixel rect (top-left origin) the full VI logical canvas (0,0)-
+ * (SCREEN_WIDTH, SCREEN_HEIGHT) currently maps to, honoring the safe-area
+ * crop above -- for inverting a window mouse click into logical 2D UI space
+ * (see port/src/optionsoverlay.c, D316). */
+void gfx_get_ui_screen_rect(int32_t *outX, int32_t *outY, int32_t *outW, int32_t *outH);
 void gfx_texture_cache_clear(void);
+int gfx_texture_cache_count(void); /* D235 */
 void gfx_texture_cache_delete(const uint8_t *orig_addr);
 void gfx_texture_cache_delete_range(const uint8_t *start, const uint8_t *end);
 int gfx_create_framebuffer(uint32_t width, uint32_t height, int upscale, int autoresize);

port/fast3d/gfx_opengl.cpp

@@ -510,11 +510,27 @@ static struct ShaderProgram* gfx_opengl_create_and_load_new_shader(uint64_t shad
         }
     }
 
+    /* D266: CVG_X_ALPHA ("texedge") modelled on the RDP's actual semantics,
+     * keyed on the alphacompare field. The inherited line quantized to
+     * opaque/discard at a hardcoded 0.19: it kept texels the N64 discards and
+     * forced survivors fully opaque, defeating the ALPHA_CVG_SEL blend.
+     * GE's Surface 1 IA4 tree strip (D236/D265) rendered as a wall because of
+     * it. Now: AC_DITHER -> dithered discard; AC_THRESHOLD -> discard only
+     * fully-transparent; AC_NONE -> discard below 0x80 and let survivors keep
+     * their alpha for blending. (AC_DECAL never sets SHADER_OPT_TEXTURE_EDGE,
+     * see gfx_pc.cpp.) */
     if (cc_features.opt_texture_edge && cc_features.opt_alpha) {
-        append_line(fs_buf, &fs_len, "    if (texel.a > 0.19) texel.a = 1.0; else discard;");
+        if (cc_features.opt_noise) {
+            append_line(fs_buf, &fs_len,
+                        "    if (texel.a < ((random(vec3(floor(gl_FragCoord.xy * noise_scale), float(frame_count))) + 1.0) / 2.0)) discard;");
+        } else if (cc_features.opt_alpha_threshold) {
+            append_line(fs_buf, &fs_len, "    if (texel.a < 1.0 / 256.0) discard;");
+        } else {
+            append_line(fs_buf, &fs_len, "    if (texel.a < 0.5) discard;");
+        }
     }
 
-    if (cc_features.opt_alpha && cc_features.opt_noise) {
+    if (cc_features.opt_alpha && cc_features.opt_noise && !cc_features.opt_texture_edge) {
         append_line(fs_buf, &fs_len,
                     "    texel.a *= floor(clamp(random(vec3(floor(gl_FragCoord.xy * noise_scale), float(frame_count))) + "
                     "texel.a, 0.0, 1.0));");
@@ -1079,12 +1095,54 @@ static void gfx_opengl_init(void) {
 static void gfx_opengl_on_resize(void) {
 }
 
+/* #92 perf probe (GE_PERFSTAT=1): GPU time per frame via GL_TIME_ELAPSED,
+ * double-buffered so reading never stalls the pipeline. Skipped when the
+ * driver lacks timer queries. Tells a low-end reporter's log whether frames
+ * are GPU-bound (render/MSAA/filtering cost) or CPU-bound. */
+static int s_gpuq_on = -1;
+static GLuint s_gpuq[2];
+static int s_gpuq_idx = 0, s_gpuq_valid[2] = { 0, 0 };
+static double s_gpuq_ms = 0.0;
+static int s_gpuq_n = 0, s_gpuq_frames = 0;
+
 static void gfx_opengl_start_frame(void) {
     frame_count++;
+    if (s_gpuq_on < 0) {
+        s_gpuq_on = getenv("GE_PERFSTAT") != NULL && glGenQueries != NULL &&
+                    glGetQueryObjectui64v != NULL && glBeginQuery != NULL;
+        if (s_gpuq_on) {
+            glGenQueries(2, s_gpuq);
+            fprintf(stderr, "PERFSTAT gpu timer on: %s | %s\n",
+                    (const char *)glGetString(GL_RENDERER), (const char *)glGetString(GL_VERSION));
+        }
+    }
+    if (s_gpuq_on == 1) {
+        if (s_gpuq_valid[s_gpuq_idx]) {
+            GLuint avail = 0;
+            glGetQueryObjectuiv(s_gpuq[s_gpuq_idx], GL_QUERY_RESULT_AVAILABLE, &avail);
+            if (avail) {
+                GLuint64 ns = 0;
+                glGetQueryObjectui64v(s_gpuq[s_gpuq_idx], GL_QUERY_RESULT, &ns);
+                s_gpuq_ms += (double)ns / 1.0e6;
+                s_gpuq_n++;
+            }
+        }
+        glBeginQuery(GL_TIME_ELAPSED, s_gpuq[s_gpuq_idx]);
+    }
 }
 
 static void gfx_opengl_end_frame(void) {
     glFlush();
+    if (s_gpuq_on == 1) {
+        glEndQuery(GL_TIME_ELAPSED);
+        s_gpuq_valid[s_gpuq_idx] = 1;
+        s_gpuq_idx ^= 1;
+        if (++s_gpuq_frames % 300 == 0 && s_gpuq_n > 0) {
+            fprintf(stderr, "PERFSTAT gpu=%.2fms/frame (avg over %d frames)\n", s_gpuq_ms / s_gpuq_n, s_gpuq_n);
+            s_gpuq_ms = 0.0;
+            s_gpuq_n = 0;
+        }
+    }
 }
 
 /* Frame capture (dev tool, env GE_PCDUMP) — see gfx_opengl.h. TEMP D70: read
@@ -1172,6 +1230,20 @@ static void gfx_opengl_update_framebuffer_parameters(int fb_id, uint32_t width,
     width = max(width, 1U);
     height = max(height, 1U);
 
+    /* macOS GL 4.1 core: asking for more samples than GL_MAX_SAMPLES (e.g. 8x)
+     * makes the multisample renderbuffers incomplete and the screen goes dark
+     * (glReadPixels 0x506). Clamp to what the driver reports. */
+    if (msaa_level > 1) {
+        static GLint maxSamples = -1;
+        if (maxSamples < 0) {
+            glGetIntegerv(GL_MAX_SAMPLES, &maxSamples);
+            if (maxSamples < 1) maxSamples = 1;
+        }
+        if ((GLint)msaa_level > maxSamples) {
+            msaa_level = (uint32_t)maxSamples;
+        }
+    }
+
     if (gfx_framebuffers_enabled) {
         glBindFramebuffer(GL_FRAMEBUFFER, fb.fbo);
 
@@ -1268,7 +1340,8 @@ void gfx_opengl_resolve_msaa_color_buffer(int fb_id_target, int fb_id_source) {
     glBindFramebuffer(GL_READ_FRAMEBUFFER, fb_src.fbo);
     glBlitFramebuffer(0, 0, fb_src.width, fb_src.height, 0, 0, fb_dst.width, fb_dst.height, GL_COLOR_BUFFER_BIT,
                       GL_NEAREST);
-    glBindFramebuffer(GL_FRAMEBUFFER, current_framebuffer);
+    /* current_framebuffer is an INDEX into framebuffers[], not a GL name; fb 0 is the window's default framebuffer (name 0). */
+    glBindFramebuffer(GL_FRAMEBUFFER, current_framebuffer == 0 ? 0 : framebuffers[current_framebuffer].fbo);
     glEnable(GL_SCISSOR_TEST);
 }
 
@@ -1332,7 +1405,7 @@ void gfx_opengl_copy_framebuffer(int fb_dst, int fb_src, int left, int top, bool
 
     glBlitFramebuffer(srcX0, srcY0, srcX1, srcY1, dstX0, dstY0, dstX1, dstY1, GL_COLOR_BUFFER_BIT, GL_NEAREST);
 
-    glBindFramebuffer(GL_FRAMEBUFFER, framebuffers[current_framebuffer].fbo);
+    glBindFramebuffer(GL_FRAMEBUFFER, current_framebuffer == 0 ? 0 : framebuffers[current_framebuffer].fbo);
 
     glReadBuffer(GL_BACK);
 

port/fast3d/gfx_sdl.h

@@ -16,6 +16,8 @@ void gfx_sdl_make_context_current(void);
 /* Release the GL context from the calling (host main) thread after init, so
  * the game's scheduler thread can bind it per frame (see gfx_sdl2.cpp). */
 void gfx_sdl_release_context(void);
+/* D344: finish queued GL work and unbind the context (render thread, quit). */
+void gfx_sdl_park_for_exit(void);
 
 /* Refresh the cached drawable size after a window resize (called by the
  * host thread's event pump). */

port/fast3d/gfx_sdl2.cpp

@@ -9,6 +9,8 @@
 #include "gfx_screen_config.h"
 #include "input.h"
 
+extern "C" void videoRequestQuit(const char *why);   // port/src/video.c (D344)
+
 static SDL_Window* wnd;
 static SDL_GLContext ctx;
 static SDL_Renderer* renderer;
@@ -319,7 +321,9 @@ static void gfx_sdl_handle_events(void) {
                 } else if (event.key.keysym.sym == SDLK_F4 && (event.key.keysym.mod & KMOD_ALT)) {
                     // D145: Alt+F4 quits; bare ESC no longer does (it is the
                     // menu "back" key -- see port/src/video.c / input.c).
-                    exit(0);
+                    // D344: request, don't exit(): this is the render thread,
+                    // mid-frame. It parks at the frame's end; the host exits.
+                    videoRequestQuit("Alt+F4 (render pump)");
                 } else if (event.key.keysym.sym == SDLK_ESCAPE && !event.key.repeat) {
                     // WI-1: this render-thread pump and port/src/video.c's
                     // host-thread pump both drain the same SDL queue, so either
@@ -345,7 +349,7 @@ static void gfx_sdl_handle_events(void) {
                            event.window.windowID == SDL_GetWindowID(wnd)) {
                     // We listen specifically for main window close because closing main window
                     // on macOS does not trigger SDL_Quit.
-                    exit(0);
+                    videoRequestQuit("window closed (render pump)");   // D344
                 } else if (event.window.event == SDL_WINDOWEVENT_FOCUS_LOST) {
                     inputSetMouseGrab(0);   // free + show cursor on alt-tab (also handled by video.c's pump; whichever dequeues it)
                 } else if (event.window.event == SDL_WINDOWEVENT_FOCUS_GAINED) {
@@ -353,7 +357,7 @@ static void gfx_sdl_handle_events(void) {
                 }
                 break;
             case SDL_QUIT:
-                exit(0);
+                videoRequestQuit("quit event (render pump)");   // D344
                 break;
         }
     }
@@ -372,6 +376,20 @@ extern "C" void gfx_sdl_make_context_current(void) {
     }
 }
 
+/* D344: called on the render thread when a quit was requested, at a frame
+ * boundary: wait for the GPU to drain everything this process queued, then
+ * unbind the context, so process teardown never lands inside the driver. */
+extern "C" void gfx_sdl_park_for_exit(void) {
+    if (ctx && SDL_GL_GetCurrentContext() == ctx) {
+        typedef void (SDLCALL *FinishFn)(void);   // = APIENTRY on Windows
+        FinishFn finish = (FinishFn)SDL_GL_GetProcAddress("glFinish");
+        if (finish) {
+            finish();
+        }
+        SDL_GL_MakeCurrent(NULL, NULL);
+    }
+}
+
 /* Release the GL context from the calling (host main) thread. WGL only allows
  * a context to be current on one thread at a time, and while another thread
  * still holds it, wglMakeContextCurrent fails with "The requested resource is

port/include/d318bprobe.h

@@ -0,0 +1,13 @@
+/* d318bprobe.h -- D318/D320 boundary probe (M-199 step 2).
+ *
+ * Env-gated per-tick ground-truth logger for the aim-hold / derail /
+ * anim-pin state machine of chrlvTickAttack + chrlvTickAttackCommon.
+ * Read-only; inert without GE_D318B. TEMP: remove when D318/D320
+ * conclude (same class as d320repro.c).
+ */
+#ifndef D318BPROBE_H
+#define D318BPROBE_H
+
+void d318bProbeTick(void);
+
+#endif /* D318BPROBE_H */

port/include/envflag.h

@@ -0,0 +1,20 @@
+#ifndef _ENVFLAG_H_
+#define _ENVFLAG_H_
+
+/* Cached env-var probes for hot paths (D250/D302: an uncached getenv() per
+ * node/poly/audio event is a measurable per-frame cost on Windows). Each
+ * expansion site gets its own static, read once on first use; the env is
+ * fixed for the process lifetime, so this is exact. The TU must already have
+ * a real getenv() prototype (see D324). GCC/Clang statement expressions. */
+#define GE_ENVFLAG(name) __extension__({ \
+    static int _ge_envflag = -1; \
+    if (_ge_envflag < 0) _ge_envflag = getenv(name) != NULL; \
+    _ge_envflag; })
+
+#define GE_ENVSTR(name) __extension__({ \
+    static int _ge_envstr_init = 0; \
+    static const char *_ge_envstr; \
+    if (!_ge_envstr_init) { _ge_envstr = getenv(name); _ge_envstr_init = 1; } \
+    _ge_envstr; })
+
+#endif

port/include/floatvtx.h

@@ -0,0 +1,33 @@
+#ifndef PORT_FLOATVTX_H
+#define PORT_FLOATVTX_H
+
+/* D245 (M-201): port-only full-precision vertex load for the sky/water fans.
+ *
+ * On N64, sky.c builds these triangles directly as RDP edge/texture
+ * coefficients with 32-bit S/T, so a horizon-scale quad (the IsWater ocean
+ * spans ~300,000 S10.5 units, ~9,400 texels) is exact. Routed through an
+ * ordinary gSPVertex, both its texture coords (s16 tc: +-1,024 texels) and its
+ * positions (s16 ob, divided by a fan-wide wScale to fit camera-space w up to
+ * ~2e5) had to be quantised -- visible as water/sky jitter that slides with
+ * the view. G_FLOATVTX_EXT hands fast3d the clip-space position and S/T as
+ * floats instead; fast3d already stores every loaded vertex as floats.
+ *
+ * w0 = G_FLOATVTX_EXT << 24 | dest_index << 16 | count, w1 = PortFloatVtx *.
+ * s/t are in Vtx.tc units (S10.5, before gSPTexture scaling). */
+#define G_FLOATVTX_EXT 0x47
+
+typedef struct PortFloatVtx {
+    float x, y, z, w;   /* clip space */
+    float s, t;         /* tc units */
+    unsigned char r, g, b, a;
+} PortFloatVtx;
+
+#define gSPFloatVertexExt(pkt, ptr, n, v0)                                        \
+    do {                                                                          \
+        Gfx *_g = (Gfx *)(pkt);                                                   \
+        _g->words.w0 = ((uintptr_t)G_FLOATVTX_EXT << 24) |                        \
+                       (((uintptr_t)(v0) & 0xff) << 16) | ((uintptr_t)(n) & 0xffff); \
+        _g->words.w1 = (uintptr_t)(ptr);                                          \
+    } while (0)
+
+#endif

port/include/frontoptions.h

@@ -0,0 +1,35 @@
+#ifndef PORT_FRONTOPTIONS_H
+#define PORT_FRONTOPTIONS_H
+
+/*
+ * D343: PC options as a GE front-end screen, MENU_PC_OPTIONS
+ * (port/src/frontoptions.c).
+ *
+ * Hooks:
+ *   front.c  the five MENU_* dispatch sites : frontOptionsMenu{Init,Update,
+ *            Interface,Draw} and the debug name (all #ifdef PORT)
+ *   front.c  constructor_menu05_fileselect : optionsFileSelectLabel() draws the
+ *            file-select entry label and enters MENU_PC_OPTIONS on a click
+ *   video.c / input.c : F10 / Select don't open the overlay on this screen
+ */
+
+#include <PR/ultratypes.h>
+#include <PR/gbi.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+void frontOptionsMenuInit(void);
+void frontOptionsMenuUpdate(void);
+void frontOptionsMenuInterface(void);
+Gfx *frontOptionsMenuDraw(Gfx *DL);
+
+Gfx *optionsFileSelectLabel(Gfx *gdl);   /* file-select hook */
+int  frontOptionsBlocksOverlay(void);    /* 1 while MENU_PC_OPTIONS is up */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* PORT_FRONTOPTIONS_H */

port/include/hudaspect.h

@@ -0,0 +1,49 @@
+#ifndef _HUDASPECT_H_
+#define _HUDASPECT_H_
+
+/* D335 (WIDESCREEN-FOV-PLAN Option B, Phase 3): HUD alignment under native
+ * widescreen (D334). The world is projected at the window aspect, but 2D/HUD
+ * elements are laid out in the game's 4:3 logical canvas, which fast3d
+ * stretches to the window. Wrapping a HUD draw in an aspect mode makes fast3d
+ * map its x undistorted (x scaled by (4/3)/window_aspect) and anchor it to
+ * the left edge, the right edge, or the centre -- the PD port's
+ * G_ASPECT_{LEFT,RIGHT,CENTER}_EXT extra-geometry-mode, which GE's fast3d
+ * already decodes (gfx_pc.cpp gfx_sp_extra_geometry_mode /
+ * gfx_update_aspect_mode). Game-includable: no SDL, no fast3d headers.
+ *
+ * PORT_HUD_ASPECT emits only while native widescreen is on and the window is
+ * wider than 4:3; otherwise the display list is byte-identical to before. */
+
+#define GE_HUD_ASPECT_NONE     0x00u
+#define GE_HUD_ASPECT_LEFT     0x10u   /* G_ASPECT_LEFT_EXT   (port/fast3d/gbiex.h) */
+#define GE_HUD_ASPECT_RIGHT    0x20u   /* G_ASPECT_RIGHT_EXT  */
+#define GE_HUD_ASPECT_CENTER   0x30u   /* G_ASPECT_CENTER_EXT */
+#define GE_HUD_ASPECT_MASK     0x70u   /* G_ASPECT_MODE_EXT   */
+#define GE_EXTRAGEOMETRYMODE_EXT 0x3a  /* G_EXTRAGEOMETRYMODE_EXT */
+
+/* The decoder does extra_mode = (extra_mode & ~clear) | set with
+ * clear = ~(w0 & 0xFFFFFF): passing ~MASK as the low 24 bits clears exactly
+ * the aspect bits and leaves the other extra-geometry flags alone. */
+#define gSPHudAspectEXT(pkt, mode) \
+    gDma0p((pkt), GE_EXTRAGEOMETRYMODE_EXT, (mode), ((~GE_HUD_ASPECT_MASK) & 0xFFFFFFu))
+
+extern float portNativeAspect(void);   /* port/src/video.c */
+
+/* Only for windows wider than 4:3: in a narrower window a centred 4:3 HUD
+ * would be wider than the window and crop, so there the HUD keeps the canvas
+ * mapping (squeezed, never cropped). 1.3334 so exact 4:3 emits nothing. */
+#define PORT_HUD_ASPECT(gdl, mode) \
+    do { if (portNativeAspect() > 1.3334f) { gSPHudAspectEXT((gdl)++, (mode)); } } while (0)
+
+/* D226: HUD span scale. PORT_HUD_SCALE(gdl, ax, ay) scales every rectangle
+ * drawn after it (glyphs, message boxes, ammo icons) about the anchor
+ * (logical screen px) by Game.HudScale %, until PORT_HUD_SCALE_END. At 100%
+ * nothing is emitted (byte-identical). Decoded as G_HUDSCALE_EXT in fast3d. */
+#define GE_HUDSCALE_EXT 0x46
+extern s32 portHudScalePercent(void);   /* port/src/video.c */
+#define gSPHudScaleEXT(pkt, scale256, ax4, ay4)     gDma0p((pkt), GE_HUDSCALE_EXT, ((u32)(ax4) << 16) | ((u32)(ay4) & 0xFFFFu), ((u32)(scale256) & 0xFFFFu))
+#define PORT_HUD_SCALE(gdl, ax, ay)     do { s32 _hp = portHudScalePercent();          if (_hp != 100) { gSPHudScaleEXT((gdl)++, _hp * 256 / 100, (ax) * 4, (ay) * 4); } } while (0)
+#define PORT_HUD_SCALE_PCT(gdl, pct, ax, ay)     do { s32 _hp = (pct); if (_hp != 100) { gSPHudScaleEXT((gdl)++, _hp * 256 / 100, (ax) * 4, (ay) * 4); } } while (0)
+#define PORT_HUD_SCALE_END(gdl)     do { if (portHudScalePercent() != 100) { gSPHudScaleEXT((gdl)++, 256, 0, 0); } } while (0)
+
+#endif

port/include/input.h

@@ -12,6 +12,7 @@
  */
 
 #include <PR/ultratypes.h>
+#include <SDL.h>   /* API types (SDL_GameControllerButton/Axis); cf. video.h */
 
 #ifdef __cplusplus
 extern "C" {
@@ -43,6 +44,8 @@ unsigned inputComputePad(int idx, signed char *stick_x, signed char *stick_y);
  * also suspends mouse-aim reads until re-grabbed. No-op if the mouse is
  * disabled in config. */
 void inputSetMouseGrab(int on);
+/* D287: apply queued mouse-mode/cursor changes; host (window) thread only. */
+void inputApplyMouseRequests(void);
 
 /* WI-1 click-to-lock cursor capture. The host event pump calls
  * inputNotifyClick() when a mouse button goes down inside the game window
@@ -65,9 +68,37 @@ short inputPadAxis(int idx, SDL_GameControllerAxis a);
  * ignored -- GE only cycles forward on a bare A edge. */
 void inputPostWheel(int notches);
 
+/* v0.4.0 M3: re-derive the keyboard binds after an F10 change to
+ * Input.CrouchMode or a future binding capture (optionsoverlay hook).
+ * Also drops the latched-crouch state. Scheduler thread only. */
+void inputBindingsApply(void);
+/* D384/D385: Primary/Secondary each accept a key or Mouse 1..5.
+ * Legacy extra ini tokens remain on disk but are ignored until action edit. */
+#define INPUT_BIND_SLOTS 2
+#define INPUT_BIND_MOUSE(button) (SDL_NUM_SCANCODES + (button))
+const char *inputBindingSlot(const char *key, int slot);
+int inputBindingSetSlot(const char *key, int slot, int code);
+int inputBindingResetKey(const char *key);
+
+/* D345(b): 1 while the 1:1 menu pointer owns cursor_h/v_pos (in a menu,
+ * abs pointer available, mouse used within the re-assert window). Port
+ * screens that teleport the crosshair should skip their snap when set. */
+int  inputMenuPointerLive(void);
+
 /* Re-enumerate gamepads after a hotplug (SDL_CONTROLLERDEVICEADDED/REMOVED). */
 void inputRescanPads(void);
 
+/* D401: Rumble Pak -> real gamepad haptics. The osMotor* shims in
+ * libultra.c (game's src/joy.c rumble state machine) route here.
+ * idx is the N64 controller channel (0..3; out-of-range is a no-op).
+ * strength is 0..1, time seconds; 0/0 stops an active rumble. The scale
+ * is the single global Input.RumbleScale config value (0 = silent),
+ * applied to every pad. */
+int  inputRumbleSupported(int idx);
+void inputRumble(int idx, f32 strength, f32 time);
+f32  inputRumbleGetScale(void);
+void inputRumbleSetScale(f32 v);
+
 #ifdef __cplusplus
 }
 #endif

port/include/optionsoverlay.h

@@ -17,10 +17,17 @@
  *   input.c   inputComputePad  : controller 0 swallowed while open;
  *                                nav routed to optionsOverlayHandleInput()
  *   gfx_pc.cpp gfx_run          : optionsOverlayEmit() appended after the game DL
+ *
+ * D346 (M2): the row API below is the shared row table the front MENU_PC_
+ * OPTIONS screen (frontoptions.c) renders from, so one option set in one
+ * place.
  */
 
 #include <PR/ultratypes.h>
 #include <PR/gbi.h>
+#include <config.h>
+#include <video.h>
+#include <watchsettings.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -28,6 +35,8 @@ extern "C" {
 
 /* Toggle open/closed. On the closing edge the config is saved. */
 void optionsOverlayToggle(void);
+/* ESC: back to categories, or close from the category list (host-thread request). */
+void optionsOverlayBack(void);
 
 /* 1 while the overlay is on screen. */
 int optionsOverlayIsOpen(void);
@@ -39,10 +48,70 @@ void optionsOverlayHandleInput(void);
 /* Mouse-wheel notch -> move the selection (host event pump). */
 void optionsOverlayScroll(int dir);
 
+/* D383/D385 keyboard + mouse rebinding modal, shared by both options UIs.
+ * Host event pump hands off one key/button; menu thread commits it. */
+int optionsBindingCaptureActive(void);
+int optionsBindingInputBlocked(void); /* active or captured key still held */
+int optionsBindingKeyDown(const SDL_KeyboardEvent *ev); /* 1 = consumed */
+int optionsBindingMouseDown(const SDL_MouseButtonEvent *ev); /* 1 = consumed */
+int optionsBindingCaptureTick(void); /* 1 = swallow menu nav this tick */
+
 /* Build the overlay's 2D display list for this frame, or return NULL when the
  * overlay is closed. Called by fast3d after running the game DL. */
 Gfx *optionsOverlayEmit(void);
 
+/* D343 (M2): row API for the file-select options screen (frontoptions.c).
+ * Index i runs over the same row table as the F10 overlay; headers split it
+ * into the screen's sections. */
+int         optionsRowCount(void);
+int         optionsRowIsHeader(int i);
+int         optionsRowHeaderParent(int i); /* -1 for root sections */
+int         optionsRowChildHeader(int i);  /* -1 unless this row opens a nested section */
+int         optionsRowIsShown(int i);
+const char *optionsRowLabel(int i);
+int         optionsRowIsSlider(int i);
+int         optionsRowIsBind(int i);
+void        optionsRowBeginBind(int i);
+int         optionsRowIsBondChooser(int i); /* D353: the Bond-file chooser row
+                                              (front options screen only) */
+/* D356: 1 when this row's value lives in the selected save file (content
+ * rows); on a header, when its section contains such rows -- the front page
+ * uses the header form for its "(File N)" title annotation. */
+int         optionsRowIsSaveScoped(int i);
+int         optionsRowNeedsRestart(int i);
+double      optionsRowFraction(int i);
+double      optionsRowGetValue(int i); /* D356: raw value (fraction is bar geometry) */
+void        optionsRowSetFraction(int i, double f);
+void        optionsRowCommit(int i); /* slider release; watch rows persist once */
+void        optionsRowValueText(int i, char *out, int n);
+void        optionsRowAdjust(int i, int dir);
+
+/* D356: per-section "Reset to defaults" rows (ROW_ACTION, keys
+ * "__Reset*"). Activation is edge-triggered and two-step (arm -> confirm
+ * within 3 s, one commit per confirmed activation; timeout or navigating
+ * away disarms) -- optionsRowIsReset lets the front screen suppress its
+ * held-key repeat for them. optionsResetMaintain runs each frame from the
+ * open UI (selRow = its selected rows[] index, -1 = none); optionsResetClear
+ * when a UI closes. Identical contract in F10 and on the front options
+ * screen (they are never open at the same time). Front: the confirmed reset
+ * writes the section's file rows through watchSettingsSet (direct commit)
+ * and the ini rows live (persisted on screen close, like any ini edit).
+ * In stage: the file rows enter the D352 queue (the game thread applies +
+ * persists them) and the ini rows are applied live immediately. */
+int  optionsRowIsReset(int i);
+void optionsRowActivateReset(int i);
+void optionsResetMaintain(int selRow);
+void optionsResetClear(void);
+
+/* D356 GE_WSPROBE_RESET dev hook (env-gated, driven from
+ * watchSettingsGameTick): runs the real arm -> confirm -> dispatch for
+ * EVERY section's reset row and verifies each section's values after its
+ * own dispatch (plan §5.8). Front is one-shot; the stage pair runs on the
+ * tick after the stage drain. */
+void optionsResetProbePrepare(void);
+void optionsResetProbeDispatchStage(void);
+void optionsResetProbeVerifyStage(void);
+
 #ifdef __cplusplus
 }
 #endif

port/include/pc_protos.h

@@ -71,6 +71,11 @@ void alloc_false_GUARDdata_to_exec_global_action();
 void alloc_init_GUARDdata_entries();
 void alloc_load_expand_ani_table();
 void assert();
+/* D324: GE's <stdlib.h> stub (#if 0'd body) declares neither; an implicit
+ * `int f()` declaration reads the xmm0 double return from eax -> garbage.
+ * port/src TUs that include <stdlib.h> get these from port/shim/stdlib.h. */
+double atof();
+double strtod();
 char * bgDebPrintROOMID();
 void bgFindRoomsAlongSegment();
 s32 bgGetConnectedRooms();

port/include/video.h

@@ -37,9 +37,17 @@ void videoEndFrame(void);
  * loop from main(). Exits the process on QUIT/ESC/close. */
 void videoPumpEvents(void);
 
+/* D344: orderly quit. Any thread may request it; the render thread parks at
+ * the next frame boundary (glFinish + context released) and the host thread
+ * then exits. Never call exit() directly for a normal quit: the render thread
+ * could be inside the GL driver (the 0x119 bugchecks). */
+void videoRequestQuit(const char *why);
+int  videoQuitRequested(void);
+
 /* The game's native video mode (NTSC 640x480, PAL 640x400). fast3d scales
  * N64 screen coordinates into window pixels using this. */
 void videoUpdateNativeResolution(s32 w, s32 h);
+u32  videoGetFrameCount(void);
 s32  videoGetNativeWidth(void);
 s32  videoGetNativeHeight(void);
 
@@ -51,9 +59,9 @@ void videoResetTextureCache(void);
 /* Current FPS (measured). */
 float videoGetFPS(void);
 
-/* Re-apply the live-tunable [Video] knobs (VSync / FpsCap / TextureFilter) on
- * the next frame start. Called by the F10 options overlay after an edit. */
-void videoRequestLiveConfig(void);
+/* Apply only the GL/SDL setting named by a changed options row at the next
+ * frame start. Sprite/HUD and direct-read settings need no reconfiguration. */
+void videoRequestLiveConfigForKey(const char *key);
 
 /* F10 options overlay -> window/fullscreen changes. The overlay input handler
  * runs on the scheduler thread; SDL window ops must run on the thread that

port/include/watchsettings.h

@@ -0,0 +1,48 @@
+#ifndef PORT_WATCHSETTINGS_H
+#define PORT_WATCHSETTINGS_H
+
+/* D349: one source of truth for Bond-file-backed GE settings. All GE state and
+ * EEPROM access runs on the game thread. F10 sends requests to that thread. */
+enum WatchSettingField {
+    WATCH_SETTING_MUSIC,
+    WATCH_SETTING_FX,
+    WATCH_SETTING_LOOK,
+    WATCH_SETTING_AUTOAIM,
+    WATCH_SETTING_AIMCONTROL,
+    WATCH_SETTING_SIGHT,
+    WATCH_SETTING_LOOKAHEAD,
+    WATCH_SETTING_AMMO,
+    WATCH_SETTING_COUNT
+};
+
+int watchSettingsFieldForKey(const char *key); /* -1 for non-watch row */
+int watchSettingsFolder(void);                /* explicit front chooser; -1 = none */
+/* D356: the chooser cycles folders only -- "none" is retired from the UI
+ * surface (plan §5.5): the front target is always a folder (frontFolder()
+ * resolves -1 to a valid folder lazily, D354; the auto-init fallback builds
+ * file 1 if none exists). The UI shows an unavailable state until the
+ * target's file actually exists instead of a number the write path cannot
+ * use. */
+void watchSettingsChooseFile(int dir);        /* game thread only */
+int watchSettingsAvailable(void);
+int watchSettingsRead(enum WatchSettingField field); /* front: saved file, F10: snapshot */
+void watchSettingsSet(enum WatchSettingField field, int value, int commit);
+void watchSettingsCommit(enum WatchSettingField field); /* slider release */
+void watchSettingsGameTick(void);             /* game thread; after gfxFrameMsgQ receive */
+
+/* D356: context-aware, READ-ONLY active-file accessor (never mutates the
+ * stored front target): in stage -> the stage's active file; front
+ * contexts -> the resolved front target (frontFolder()'s lazy default).
+ * -1 when nothing usable (e.g. the auto-init fallback not yet applied).
+ * Drives the "(File N)" title annotations in the F10 overlay and the front
+ * options screen (plan §5.5). */
+int watchSettingsActiveFolder(void);
+/* D356: the BLANKSAVEDATA value of a field -- the per-file "default" the
+ * reset-to-defaults rows restore (plan §5.3/§5.6). */
+int watchSettingsBlankValue(enum WatchSettingField field);
+/* D352: queued field commands awaiting the game thread (0 in front
+ * contexts -- nothing is queued there). Drives the in-stage reset probe's
+ * dispatch check. */
+int watchSettingsQueueCount(void);
+
+#endif

port/shim/PR/gbi.h

@@ -136,5 +136,21 @@ typedef union {
 
 #define Gfx Gfx_le
 
+/*
+ * The gDP* display-list macros in the real gbi.h use _SHIFTL/_SHIFTR, which
+ * the N64 headers define in PR/mbi.h. A port TU that includes <PR/gbi.h>
+ * without <ultra64.h> (e.g. port/src/video.c) never reaches mbi.h; on Linux
+ * no other header in its include chain pulls it in, so the gDP* calls expand
+ * to implicit _SHIFTL()/_SHIFTR() function calls and fail to link (D402).
+ * Define them if absent. Guarded so a TU that also reaches mbi.h keeps
+ * mbi.h's own definitions.
+ */
+#ifndef _SHIFTL
+#    define _SHIFTL(v, s, w) ((u32)(((u32)(v) & ((0x01 << (w)) - 1)) << (s)))
+#endif
+#ifndef _SHIFTR
+#    define _SHIFTR(v, s, w) ((u32)(((u32)(v) >> (s)) & ((0x01 << (w)) - 1)))
+#endif
+
 #endif /* defined(PORT) */
 #endif /* _PORT_SHIM_GBI_H_ */

port/shim/PR/ucode.h

@@ -13,7 +13,18 @@
 
 #if defined(PORT)
 #    include "include/PR/ucode.h"
-#    include "pc_protos.h"
+#    /* D402 (Linux build): a TU that includes <bondconstants.h> before
+#     * <ultra64.h> (e.g. port/src/optionsoverlay.c) sets src/bondconstants.h's
+#     * include-guard, then that header's own top `#include <ultra64.h>` reaches
+#     * this pc_protos.h -> bondtypes.h -> bondconstants.h chain while
+#     * src/bondconstants.h is still mid-parse (its ITEM_IDS/ACT_TYPE/... are
+#     * defined only later in the file). glibc GCC rejects the half-defined
+#     * types hard (MinGW tolerated it, so this only surfaced on Linux). The
+#     * bondconstants.h shim sets _PORT_DEFER_PC_PROTOS around that pass so the
+#     * D38 prototypes are pulled in only once, after the constants are whole. */
+#    if !defined(_PORT_DEFER_PC_PROTOS)
+#        include "pc_protos.h"
+#    endif
 #else
 #    include <PR/ucode.h>
 #endif

port/shim/bondconstants.h

@@ -21,7 +21,21 @@
  * Inert in the N64 build (no -DPORT): pure pass-through.
  */
 #if defined(PORT)
+/* D402 (Linux build): parse the PR base headers first, but tell the PR/ucode.h
+ * shim to defer pc_protos.h for this pass. pc_protos.h reaches bondtypes.h,
+ * which needs the bondconstants.h types (ITEM_IDS, ACT_TYPE, ...) that are only
+ * defined later in src/bondconstants.h. Without this, a TU that includes
+ * <bondconstants.h> before <ultra64.h> re-enters the still-parsing
+ * src/bondconstants.h (guard already set) from bondtypes.h and glibc GCC
+ * rejects the half-defined types (MinGW tolerated it). We finish
+ * src/bondconstants.h below and then pull pc_protos.h so the D38 prototypes
+ * are still seen exactly once. */
+#    define _PORT_DEFER_PC_PROTOS
+#    include <ultra64.h>
+#    undef _PORT_DEFER_PC_PROTOS
+
 #include "src/bondconstants.h"
+#include "pc_protos.h"
 
 /*
  * D38: src/bondconstants.h defines ntohl()/ntohs() as function-like macros

port/shim/stdlib.h

@@ -17,15 +17,30 @@
 #include "hoststdlib.h"
 #else
 #include "include/stdlib.h"
-#if !defined(_WIN32)
-/* The N64 stub declares only lldiv_t/ldiv_t + lldiv/ldiv. MinGW's other CRT
- * headers leak getenv() etc.; a strict host GCC (Linux/macOS) does not, so
- * getenv()'s 64-bit pointer return is assumed int and truncated (crashed
- * configGetFrameDump). Declare the pointer-returning stragglers the port +
- * game code use that nothing else declares. K&R form = compatible with any
- * real prototype. (malloc/calloc/free are in port/include/pc_protos.h and
- * a few port TUs' own local decls — not repeated here to avoid conflicts.) */
+/* D324: the N64 stub declares nothing else, and -- unlike getenv/realloc
+ * below -- MinGW's leaked CRT headers do NOT declare these in the port TUs
+ * that use them. An implicit `int f()` declaration makes the caller read a
+ * double return from eax instead of xmm0 (silent garbage) and truncates
+ * pointer/64-bit-long returns to 32 bits (latent on LP64 for strtol).
+ * Declared unconditionally; K&R form is compatible with any real prototype.
+ * Game TUs that never include <stdlib.h> get these from pc_protos.h. */
+extern double atof();
+extern double strtod();
+extern long int strtol();
+extern int atoi();
+extern int atexit();
+/* D324: getenv was previously declared only on non-Windows, on the (wrong)
+ * assumption that MinGW's other CRT headers leak a prototype -- config.c gets
+ * none, so its implicit `int f()` declaration truncated the pointer return to
+ * 32 bits. Declare unconditionally; K&R form is compatible with any leaked or
+ * real prototype. */
 extern char *getenv();
+#if !defined(_WIN32)
+/* The N64 stub declares only lldiv_t/ldiv_t + lldiv/ldiv, and a strict host
+ * GCC (Linux/macOS) leaks no CRT prototypes at all, so realloc's pointer
+ * return would be assumed int and truncated (crashed configGetFrameDump).
+ * (malloc/calloc/free are in port/include/pc_protos.h and a few port TUs'
+ * own local decls — not repeated here to avoid conflicts.) */
 extern void *realloc();
 #endif
 #endif

port/src/audio.c

@@ -17,6 +17,9 @@
 #include "config.h"
 #include "audio.h"
 #include "audiotrace.h"
+#ifdef PORT
+#include "envflag.h"   /* cached getenv for hot-path probes */
+#endif
 
 static SDL_AudioDeviceID dev = 0;
 
@@ -85,6 +88,18 @@ static int d204OldMode(void)
 
 int audioInit(void)
 {
+#if defined(_WIN32) && defined(SDL_HINT_AUDIODRIVER)
+    /* D322: prefer DirectSound over SDL2's WASAPI backend on Windows. Measured
+     * side by side on the same USB interface (tools_pc/sdl_drain_monitor.c,
+     * four simultaneous streams, 700 s): WASAPI fell to 81-88 % drain for
+     * ~30-50 s every ~317 s and lost 1.4 % of playback overall, whichever
+     * buffer size was used, while DirectSound drained at exactly real time
+     * throughout. Each WASAPI shortfall overflowed our queue and dropped whole
+     * blocks (the periodic "garbled audio" bursts). WASAPI stays as the
+     * fallback, and the SDL_AUDIODRIVER environment variable still overrides
+     * this (SDL_HINT_NORMAL yields to the environment). */
+    SDL_SetHint(SDL_HINT_AUDIODRIVER, "directsound,wasapi");
+#endif
     if (SDL_InitSubSystem(SDL_INIT_AUDIO) < 0) {
         sysLogPrintf(LOG_ERROR, "audioInit: SDL_InitSubSystem: %s", SDL_GetError());
         return -1;
@@ -101,7 +116,8 @@ int audioInit(void)
         return -1;
     }
     SDL_PauseAudioDevice(dev, 0);
-    sysLogPrintf(LOG_INFO, "audioInit: opened SDL audio device at %d Hz", have.freq);
+    sysLogPrintf(LOG_INFO, "audioInit: opened SDL audio device at %d Hz (driver %s)", have.freq,
+                 SDL_GetCurrentAudioDriver() ? SDL_GetCurrentAudioDriver() : "?");
     return 0;
 }
 
@@ -280,6 +296,34 @@ void audioSetNextBuffer(const s16 *buf, u32 len)
             lastReportUs = now;
         }
     }
+    /* D322 (issue #87): long-session audio degradation -- voice-pool health
+     * monitor, sibling of the GE_D204 pipeline monitor above. One line per 5 s
+     * of wall clock with the three pool layers a multi-hour campaign can
+     * exhaust: the 8-voice SFX soft cap (sfx), the 64-slot event queue (evtq),
+     * and the 24 physical synth voices shared by SFX + music (pv). A sfx count
+     * that ratchets up level over level, or pv alloc that never returns to
+     * baseline after quiet sections, is the voice-leak signature; q pinning at
+     * queueLimit with drop climbing is the overproduction/queue signature.
+     * Cheap (one locked list walk per 5 s) -- safe for a full playtest. */
+    if (GE_ENVFLAG("GE_D322")) {
+        static u64 d322StartUs = 0, d322NextUs = 0;
+        extern void sndD322PoolSummary(s32 *, s32 *, s32 *, s32 *, s32 *, s32 *);
+        u64 now = sysGetMicroseconds();
+        if (!d322StartUs) { d322StartUs = now; d322NextUs = now + 5000000ull; }
+        if (now >= d322NextUs) {
+            s32 sfx, sfxMax, ev, pf, pl, pa;
+            sndD322PoolSummary(&sfx, &sfxMax, &ev, &pf, &pl, &pa);
+            sysLogPrintf(LOG_NOTE,
+                "D322 pool t=%llus sfx=%d/%d evtq=%d/64 pv free/lame/alloc=%d/%d/%d q=%d/%d drop=%u",
+                (unsigned long long)((now - d322StartUs) / 1000000ull),
+                (int)sfx, (int)sfxMax, (int)ev,
+                (int)pf, (int)pl, (int)pa,
+                (int)audioGetSamplesBuffered(), queueLimit,
+                (unsigned)dropCount);
+            d322NextUs = now + 5000000ull;
+        }
+    }
+
     if (dev && buf && len) {
         if (audioGetSamplesBuffered() < queueLimit) {
             SDL_QueueAudio(dev, buf, len);

port/src/config.c

@@ -25,6 +25,7 @@
 #include "platform.h"
 #include "system.h"
 #include "config.h"
+#include "envflag.h"
 
 /*
  * [Debug] knobs mirroring the dev env vars. The env var always wins so
@@ -43,14 +44,14 @@ PD_CONSTRUCTOR static void configDebugInit(void)
 
 const char *configGetFrameDump(void)
 {
-    const char *e = getenv("GE_PCDUMP");
+    const char *e = GE_ENVSTR("GE_PCDUMP");   /* per frame (videoPreSwapCapture) */
     if (e && *e) return e;
     return dbgFrameDump[0] ? dbgFrameDump : NULL;
 }
 
 int configGetInputLog(void)
 {
-    return getenv("GE_INPUTLOG") ? 1 : dbgInputLog;
+    return GE_ENVFLAG("GE_INPUTLOG") ? 1 : dbgInputLog;   /* several calls per poll */
 }
 
 #define MAX_OPTIONS 256

port/src/d318bprobe.c

@@ -0,0 +1,377 @@
+/* d318bprobe.c -- D318/D320 boundary probe (M-199 step 2).
+ *
+ * Purpose: capture per-tick ground truth of the aim-hold / derail /
+ * anim-pin state machine so the D318/D320/D321 writeups can be rewritten
+ * on verified evidence and each watchdog entry judged for excision on its
+ * own data. Static analysis (this session) established:
+ *
+ *   - The hold-pose pin is topologically stable, not a float knife-edge:
+ *     once modelConstrainOrWrapAnimFrame clamps both framea and frameb to
+ *     ceil(endframe), the tail of modelSetAnimFrame2WithChrStuff re-emits
+ *     the stale va==vb pair every tick (the per-frame loop only runs when
+ *     floor(frame) crosses an integer boundary, which a pinned animframe1
+ *     never does). All comparisons in the frozen state are exact integers.
+ *   - Post-derail, escape requires a modelSetAnimation re-init from one of
+ *     exactly three paths: chrlvTickAttack's unk36==0 branch (auto
+ *     weapons, endframe<=frame), chrlvTickAttackCommon re-init block
+ *     branch 1 (unk37!=0, i.e. auto weapon -> kneel-stop) or branch 3
+ *     (unk31 armed by the fire gate while frame sits in the recoil/shoot
+ *     window). None is reachable in the observed pins (auto weapons,
+ *     endframe unbounded) -- BUT the pin itself only persists at 1 sim
+ *     tick per rendered frame: a >=2-tick frame advances >=1.0 and
+ *     crosses the integer boundary, so no escape path is needed (D329,
+ *     lockstep A/B via GE_D318B_CLK below). Not a platform-invariant lock.
+ *
+ * This probe logs, for env-selected chrs, every operand those decisions
+ * read: the drawn variant (identified by pointer against all six firing-
+ * group sets), its frame fields, the unk30..unk44 gate bytes, the weapon
+ * auto-firing rates, full-precision model frame/endframe/speed state, and
+ * each branch condition recomputed from the same fields. Read-only;
+ * inert without GE_D318B.
+ *
+ * Usage: GE_D318B="5,9"   (comma-separated chrnums, max 4)
+ *        GE_D318B_ALL=1   (log every ACT_ATTACK tick, not just changes)
+ *        GE_D318B_CLK=N   (lockstep: exactly N sim ticks per rendered frame)
+ * Combined with the D320R forced repro, e.g.:
+ *   GE_D320R="900:jump=5,list=0x0414,off=341" GE_D318B="5"
+ *
+ * TEMP: investigation probe, remove when D318/D320 conclude.
+ */
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "PR/os.h"
+#include "bondtypes.h"
+#include "bondaicommands.h"
+#include "chr.h"
+#include "chraction.h"
+#include "gun.h"
+#include "lv.h"
+#include "model.h"
+
+#ifdef PORT
+
+#define D318B_MAX_CHRS 4
+#define D318B_LINE_CAP 6000
+
+typedef struct
+{
+    s16  chr;
+    /* last-logged state (change detection) */
+    int  act;
+    u32  atk;
+    u32  ent;
+    char animid[8];
+    u32  framebits;
+    s32  stable;   /* consecutive ticks with unchanged frame bits */
+    s32  hb;       /* ticks since last heartbeat log */
+} D318BState;
+
+static int      s_on = -1;
+static int      s_all = 0; /* GE_D318B_ALL=1: log every attack tick */
+static int      s_n  = 0;
+static D318BState s_s[D318B_MAX_CHRS];
+static long     s_lines = 0;
+static int      s_capped = 0;
+
+#define d318bLog osSyncPrintf
+
+static void d318bInit(void)
+{
+    const char *e;
+    char buf[128];
+    char *p, *save;
+
+    if (s_on != -1)
+    {
+        return;
+    }
+    s_on = 0;
+    e = getenv("GE_D318B");
+    if (!e || !e[0])
+    {
+        return;
+    }
+    s_on = 1;
+    s_all = (getenv("GE_D318B_ALL") != NULL);
+    strncpy(buf, e, sizeof(buf) - 1);
+    buf[sizeof(buf) - 1] = 0;
+    p = buf;
+    while (p && *p && s_n < D318B_MAX_CHRS)
+    {
+        save = strchr(p, ',');
+        if (save)
+        {
+            *save = 0;
+        }
+        memset(&s_s[s_n], 0, sizeof(D318BState));
+        s_s[s_n].chr = (s16)strtol(p, NULL, 0);
+        s_s[s_n].act = -1;
+        s_n++;
+        p = save ? save + 1 : NULL;
+    }
+    d318bLog("D318B: probe active for %d chr(s): %s\n", s_n, buf);
+}
+
+static ChrRecord *d318bFindChr(s16 chrnum)
+{
+    s32 i;
+
+    for (i = 0; i < g_NumChrSlots; i++)
+    {
+        if (g_ChrSlots[i].chrnum == chrnum)
+        {
+            return &g_ChrSlots[i];
+        }
+    }
+    for (i = 0; i < g_ActiveChrsCount; i++)
+    {
+        if (g_ActiveChrs[i].chrnum == chrnum)
+        {
+            return &g_ActiveChrs[i];
+        }
+    }
+    return NULL;
+}
+
+/* Identify act_attack.animfloats by pointer against all six firing-group
+ * sets. Returns 1 and fills id (e.g. "P3.2" = pistol set, bearing group
+ * index 3, variant row 2) on success. */
+static int d318bIdentifyAnim(struct weapon_firing_animation_table *row, char *id, int idsz)
+{
+    static const struct
+    {
+        const char                          tag;
+        struct anim_group_info              *const *set;
+    } sets[] = {
+        { 'P', ptr_pistol_firing_animation_groups },
+        { 'R', ptr_rifle_firing_animation_groups },
+        { 'D', ptr_doubles_firing_animation_groups },
+        { 'C', ptr_crouched_rifle_firing_animation_groups },
+        { 'K', ptr_crouched_pistol_firing_animation_groups },
+        { 'L', ptr_crouched_doubles_firing_animation_groups },
+    };
+    s32 si, gi, ri;
+
+    for (si = 0; si < 6; si++)
+    {
+        for (gi = 0; gi < 32; gi++)
+        {
+            struct anim_group_info *g = sets[si].set[gi];
+
+            if (g == NULL)
+            {
+                continue;
+            }
+            for (ri = 0; ri < g->len; ri++)
+            {
+                if (&(*g->table)[ri] == row)
+                {
+                    snprintf(id, idsz, "%c%d.%d", sets[si].tag, gi, ri);
+                    return 1;
+                }
+            }
+        }
+    }
+    snprintf(id, idsz, "-");
+    return 0;
+}
+
+static s32 d318bAutoRate(ChrRecord *self, GUNHAND hand)
+{
+    PropRecord *prop;
+    s32 item;
+
+    prop = chrGetEquippedWeaponPropWithCheck(self, hand);
+    if (prop == NULL || prop->chr == NULL)
+    {
+        return -99;
+    }
+    item = (s32)prop->chr->act_attack.attack_item;
+    if (item < 0)
+    {
+        return -98;
+    }
+    return (s32)bondwalkItemGetAutomaticFiringRate((ITEM_IDS)item);
+}
+
+/* GE_D318B_CLK=N (test-only): force exactly N sim ticks per rendered frame,
+ * independent of host render speed -- a lockstep model of a console frame
+ * rate of 60/N fps. Rewrites the three values lvlManageMpGame just derived
+ * from speedgraphframes (the hook runs after them, before any chr tick).
+ * Pause/lock frames (g_ClockTimer == 0) are left alone. */
+static void d318bClockLock(void)
+{
+    static s32 s_clk = -1;
+
+    if (s_clk < 0)
+    {
+        const char *e = getenv("GE_D318B_CLK");
+
+        s_clk = (e && strtol(e, NULL, 10) > 0) ? (s32)strtol(e, NULL, 10) : 0;
+        if (s_clk)
+        {
+            d318bLog("D318B: clock lock active, %d tick(s)/frame\n", s_clk);
+        }
+    }
+    if (s_clk && g_ClockTimer > 0 && g_ClockTimer != s_clk)
+    {
+        g_GlobalTimer += s_clk - g_ClockTimer;
+        g_ClockTimer = s_clk;
+        g_GlobalTimerDelta = (f32)s_clk;
+    }
+}
+
+void d318bProbeTick(void)
+{
+    s32 i;
+
+    d318bClockLock();
+    d318bInit();
+    if (!s_on || s_capped)
+    {
+        return;
+    }
+
+    for (i = 0; i < s_n; i++)
+    {
+        D318BState *st = &s_s[i];
+        ChrRecord  *c;
+        Model      *m;
+        struct act_attack *a;
+        struct weapon_firing_animation_table *f;
+        f32 fr, ef;
+        u32 framebits;
+        int chg, atpin, dolog, gate = 0, k;
+        char animid[8];
+
+        c = d318bFindChr(st->chr);
+        if (c == NULL || c->model == NULL)
+        {
+            continue;
+        }
+        m = c->model;
+        a = &c->act_attack;
+        f = a->animfloats;
+
+        if (c->actiontype != ACT_ATTACK && c->actiontype != ACT_ATTACKROLL)
+        {
+            /* reset change-detection so the next attack logs its entry */
+            st->act = -1;
+            continue;
+        }
+
+        fr = m->animframe1;
+        ef = m->endframe;
+        memcpy(&framebits, &fr, sizeof(framebits));
+
+        d318bIdentifyAnim(f, animid, sizeof(animid));
+
+        chg = (st->act != (int)c->actiontype) || (st->atk != a->attacktype)
+             || (st->ent != a->entityid) || (strcmp(st->animid, animid) != 0);
+
+        if (framebits == st->framebits)
+        {
+            st->stable++;
+        }
+        else
+        {
+            st->stable = 0;
+        }
+        st->hb++;
+
+        atpin = ((ef >= 0.0f) && (ef <= fr + 1e-6f));
+        dolog = s_all || chg || atpin || (st->stable >= 20) || (st->hb >= 60);
+        if (!dolog)
+        {
+            goto update;
+        }
+        if (++s_lines >= D318B_LINE_CAP)
+        {
+            s_capped = 1;
+            d318bLog("D318B: line cap (%ld) reached, probe silent\n",
+                     (long) D318B_LINE_CAP);
+            return;
+        }
+
+        /* per-hand fire-loop outcome in chrlvTickAttackCommon (source
+         * order): bit0/1 = unk3a[k]==0 arm, frame in shoot window
+         * [ss,se) -> ToggleHidden(1) (gun fires) + unk44=now;
+         * bit4/5 = unk3a[k]!=0 arm, unk31 re-arm conditions met
+         * (unk31==0, unk32 turn, frame in recoil window or >=ss). */
+        for (k = 0; k < 2; k++)
+        {
+            if (a->unk38[k] == 0)
+            {
+                continue;
+            }
+            if (a->unk3a[k] == 0)
+            {
+                if (f->shoot_start_frame <= fr && fr < f->shoot_end_frame)
+                {
+                    gate |= (1 << k);
+                }
+            }
+            else if (a->unk31 == 0
+                     && (k == a->unk32 || a->unk3a[(s32)a->unk32] == 0)
+                     && ((f->recoil_start_frame >= 0.0f && f->recoil_start_frame <= fr
+                          && fr <= f->recoil_end_frame)
+                         || (f->recoil_start_frame < 0.0f && f->shoot_start_frame <= fr)))
+            {
+                gate |= (0x10 << k);
+            }
+        }
+
+        d318bLog(
+            "D318B: t=%d clk=%d c%d off=%d act=%d atk=0x%x ent=%u toM=%d | v=%s "
+            "st=%.9g end=%.9g ss=%.9g se=%.9g rs=%.9g re=%.9g as=%.9g ae=%.9g | "
+            "31=%d 32=%d 33=%d 34=%d 36=%d 37=%d 38=%d/%d 3a=%d/%d 40=%u 44=%d atkT=%d | "
+            "fr=%.9g ef=%.9g fa=%d fb=%d spd=%.9g ps=%.9g nn=%.9g oo=%.9g ts=%.9g es=%.9g "
+            "b0=%.9g b4=%.9g ac=%.9g loop=%d a2=%d a2len=%u wr=%d wl=%d | "
+            "aim=%d dnt=%d efle=%d trm=%d b1=%d b2=%d b3=%d gate=%d cf1=%d\n",
+            (int)g_GlobalTimer, (int)g_ClockTimer, st->chr, (int)c->aioffset, (int)c->actiontype,
+            (unsigned)a->attacktype, (unsigned)a->entityid, (int)a->type_of_motion,
+            animid,
+            (double)f->start_frame, (double)f->end_frame,
+            (double)f->shoot_start_frame, (double)f->shoot_end_frame,
+            (double)f->recoil_start_frame, (double)f->recoil_end_frame,
+            (double)f->aim_start_frame, (double)f->aim_end_frame,
+            (int)a->unk31, (int)a->unk32, (int)a->unk33, (int)a->unk34,
+            (int)a->unk36, (int)a->unk37, (int)a->unk38[0], (int)a->unk38[1],
+            (int)a->unk3a[0], (int)a->unk3a[1], (unsigned)a->unk40,
+            (int)a->unk44, (int)a->attack_time,
+            (double)fr, (double)ef, (int)m->framea, (int)m->frameb,
+            (double)m->speed, (double)m->playspeed, (double)m->newspeed,
+            (double)m->oldspeed, (double)m->timespeed, (double)m->elapsespeed,
+            (double)m->unkb0, (double)m->unkb4, (double)m->unkac,
+            (int)m->animlooping, (int)(m->anim2 != NULL),
+            m->anim2 ? (unsigned)m->anim2->unk04 : 0u,
+            d318bAutoRate(c, GUNRIGHT), d318bAutoRate(c, GUNLEFT),
+            (int)((a->attacktype & TARGET_AIM_ONLY) != 0),
+            (int)((a->attacktype & TARGET_DONTTURN) != 0),
+            (int)((ef >= 0.0f) && (ef <= fr)),
+            (int)(a->unk36 == 0 && f->recoil_end_frame > 0.0f && fr <= f->recoil_end_frame
+                  && (ef >= 0.0f) && (ef <= fr)),
+            (int)(a->unk37 != 0 || a->unk34 < a->unk33),
+            (int)(a->unk33 == a->unk34),
+            (int)(a->unk31 != 0),
+            gate,
+            (int)(a->attack_time < a->unk44 - 30 && m->anim2 == NULL
+                  && f->shoot_start_frame + 10.0f < fr && fr < f->shoot_end_frame));
+
+    update:
+        st->act = (int)c->actiontype;
+        st->atk = a->attacktype;
+        st->ent = a->entityid;
+        strncpy(st->animid, animid, sizeof(st->animid) - 1);
+        st->animid[sizeof(st->animid) - 1] = 0;
+        st->framebits = framebits;
+        if (dolog)
+        {
+            st->hb = 0;
+        }
+    }
+}
+
+#endif /* PORT */

port/src/d318watchdog.c

@@ -0,0 +1,714 @@
+/* d318watchdog.c -- D318: port-side deadlock recovery for the Facility
+ * (level_34) Ourumov/Trevelyan execution softlock.
+ *
+ * What this is (full writeup: docs/dev/findings.md, D318):
+ *
+ * As-authored latent race, faithfully reproduced by the port (NOT a port
+ * bug -- every link in the chain is byte-matched ROM logic):
+ *
+ *   1. Ourumov (chr 78, ai_22) pre-aims at kneeling Trevelyan (chr 67)
+ *      during his monologue: actor_aim_at_actor with TARGET_AIM_ONLY|
+ *      TARGET_DONTTURN (attacktype 0x64). chrlvInitActAttack picks a RANDOM
+ *      variant from the aim-animation group (randomGetNext() % len) and
+ *      modelSetAnimation's it with animlooping=0.
+ *   2. The aim anim plays to its endframe H (the "hold" pose). With
+ *      animlooping==0, modelTickAnim has no wrap logic; when the frame
+ *      reaches endframe, modelConstrainOrWrapAnimFrame clamps BOTH framea
+ *      and frameb to ceil(H), so framea==frameb, and the tail of
+ *      modelSetAnimFrame2WithChrStuff (if (vb==va) animframe1 = va) then
+ *      discards all sub-frame progress: the model is PINNED at H. That is
+ *      how a hold pose works by design -- normally something else changes
+ *      the attack state next.
+ *   3. If the gas cascade sets objective bit 0x04 (combat) mid-monologue,
+ *      ai_22 derails to section 0x2a and off=307 runs
+ *      actor_fire_or_aim_at_target_update, which SUCCEEDS while the pre-aim
+ *      is active: attacktype becomes 0x04, entityid becomes Trevelyan, and
+ *      chrlvAttackActionRelated sets a NEW endframe from the variant's
+ *      recoil/shoot start frame -- but it never calls modelSetAnimation.
+ *   4. Branch (determined by the random variant chosen in step 1):
+ *        - new endframe <= H: chrlvTickAttackCommon's "endframe <= frame"
+ *          block fires next tick and its unk31 path calls modelSetAnimation
+ *          again -> pin broken -> anim advances into the shoot window ->
+ *          c78 live-fires Trevelyan -> he dies -> attack ends -> ACT_STAND
+ *          -> the stop check at ai_22 off=324 passes -> scene continues.
+ *        - new endframe > H: nothing ever calls modelSetAnimation again
+ *          (verified by probe: zero calls in frozen runs). The frame stays
+ *          pinned at H < shoot_start, c78 never fires, Trevelyan never
+ *          dies, and ai_22's off=324 stop check (chrHasStoppedOrPatroling,
+ *          TRUE only for ACT_STAND/ACT_ANIM/ACT_PATROL) can never pass
+ *          while c78 is in ACT_ATTACK -> PERMANENT SOFTLOCK.
+ *
+ * N64 manifestation unverified (findings D318, 2026-09-22 correction): the
+ * user's empirical prior is that no such freeze occurs on real hardware;
+ * whether the derail window ever opens organically on N64 is open (an
+ * unthrottled-emulator deliberate-timing A/B is the discriminating test).
+ * This watchdog is a deliberate port-layer accommodation either way (same
+ * pattern as the D202 M-66b port-side expiration). It detects the exact unrecoverable signature and,
+ * after a long margin, re-initializes c78's attack via sub_GAME_7F025560 --
+ * the same entry point the game itself uses for a fresh attack (chrlvTickAttack
+ * type_of_motion==2 calls it with (attacktype, entityid)). That runs
+ * chrlvInitActAttack: random variant pick + modelSetAnimation(start_frame),
+ * which breaks the framea==frameb pin. c78 then live-fires Trevelyan exactly
+ * like the natural escape path (verified: escape runs kill c67 within ~230
+ * ticks of a fresh init), his attack sequence completes, he reaches
+ * ACT_STAND, the stop check at off=324 passes, and ai_22 proceeds as
+ * authored (the off=333 headshot lands on the corpse -- the same no-op the
+ * game already handles when Trevelyan dies of gas before the execution shot).
+ *
+ * NOTE: merely killing Trevelyan (e.g. via handles_shot_actors) is NOT
+ * enough -- a pinned attack has no internal completion event tied to target
+ * death, so c78 would stay in ACT_ATTACK and the stop check would still
+ * never pass (verified by probe). The attack state itself must be re-seeded.
+ *
+ * Signature (all must hold for D318_DEADLOCK_TICKS consecutive ticks):
+ *   - chr 78 exists, is on AI list 0x0417 (ai_22), offset in [321, 333)
+ *     (the sleep/stop-check loop; 333 is the headshot command itself),
+ *   - chr 78 actiontype == ACT_ATTACK with act_attack.entityid == 67
+ *     (targeting Trevelyan -- the derailed state; legitimate combat at this
+ *     offset targets Bond, ent=1),
+ *   - chr 67 exists, has a prop, and is not dead.
+ *
+ * In every non-deadlocked state the watchdog is inert: the escape path
+ * kills Trevelyan within ~25-100 ticks (60x under the threshold) and
+ * legitimate combat never targets chr 67 from this loop. One-shot per
+ * OCCURRENCE: after firing, it re-arms once the signature has been absent
+ * for D318_REARM_TICKS consecutive ticks (the deadlock is gone -- recovered
+ * or the player moved on), so a later replay of Facility in the same
+ * session (AllUnlocked) is still covered. Logs its detection and
+ * intervention for playtest audit.
+ *
+ * D320 generalization (2026-09-22, findings D320): the identical pin was
+ * force-reproduced headless on two more lists, and the watchdog is now
+ * table-driven over all confirmed signatures:
+ *
+ *   - 0x0417 ai_22 [321,333) ent=67 c67-alive : D318 Facility execution
+ *   - 0x0414 ai_19 [480,548) any-ent          : D320 Facility scientist/
+ *                                               pad kneel-aim hold (label
+ *                                               0x34 stop-check loop; pin
+ *                                               observed at off=483)
+ *   - 0x040a ai_9  [60,86)   any-ent          : D320 Control chr-0xFC aim
+ *                                               hold (label 0x0b stop-check
+ *                                               loop; pin observed at
+ *                                               off=69, ~2/3 of variants)
+ *
+ * Any chr (not just c78) sitting in a listed loop range in ACT_ATTACK with
+ * a LIVE-FIRE attacktype (no TARGET_AIM_ONLY bit) for D318_DEADLOCK_TICKS
+ * consecutive ticks gets the same sub_GAME_7F025560 re-seed. Depot ai_12
+ * (0x040d) tested clean 3/3 under forced repro and is deliberately NOT
+ * covered. In every non-deadlocked state each entry is inert: the escape
+ * path leaves the loop range in < 2 s (60x under the threshold), and a
+ * re-holding guard's anim frame moves between cycles.
+ *
+ * Repeat rescues: for the D320 entries a successful re-seed plays out the
+ * attack, the stop check passes, and the beat RE-ROLLS (re-aim -> wait ->
+ * update) -- which can pin AGAIN immediately (verified: in the forced-repro
+ * contexts every re-roll re-pinned ~240 ticks after each rescue; whether a
+ * given roll pins depends on the random aim-variant and is context/RNG-
+ * stream dependent, sometimes ~100%). So there is NO fire cap: while the
+ * signature persists, the watchdog re-fires every D318W_REFIRE_TICKS (6 s,
+ * > the ~240-tick re-roll cycle; a non-pinned guard leaves the loop range
+ * well inside that). This keeps the beat alive -- the guard fires in
+ * periodic bursts instead of freezing -- until an escape roll lands, the
+ * target dies (the beats progress on their dying/dead checks), or player
+ * action breaks the state. Full re-arm only when the signature has been
+ * absent for D318_REARM_TICKS.
+ *
+ * Opt out (research only): GE_D318W=0
+ */
+#include <stdlib.h>
+#include <string.h>
+
+#include "PR/os.h"
+#include "bondtypes.h"
+#include "chr.h"
+#include "chrai.h"
+#include "chraction.h"
+#include "lv.h"
+#include "model.h"
+#include "random.h"
+
+#ifdef PORT
+
+/* chrai.c defines these but chrai.h does not declare them. */
+extern s32 chraiGetAIListID(AIRecord *AIList, bool *isGlobalAIList);
+
+/* src/bondaicommands.h:467 -- kept local so this port file doesn't pull in
+ * the AI-command header just for one bit constant. */
+#define D320_TARGET_AIM_ONLY 0x0020 /* "Aim at target instead of firing"   */
+
+/* chraction.c internal (not in chraction.h): the fresh-attack entry point.
+ * Signature from the definition; call form mirrors chrlvTickAttack's own
+ * re-init at chraction.c:7401. */
+extern void sub_GAME_7F025560(ChrRecord *self, s32 attack_type, s32 arg2);
+
+#define D318_LIST_AI22       0x0417 /* Ourumov's execution list (ai_22)      */
+#define D318_OURUMOV_CHR     78
+#define D318_TREVELYAN_CHR   67
+#define D318_DEADLOCK_TICKS  600    /* 10 s at 60 Hz; escape takes < 2 s     */
+#define D318_REARM_TICKS     600    /* signature-absent ticks before re-arm  */
+#define D318W_REFIRE_TICKS   360    /* > the ~240-tick re-roll cycle         */
+
+static ChrRecord *d318wFindChr(s16 chrnum)
+{
+    s32 i;
+
+    for (i = 0; i < g_NumChrSlots; i++)
+    {
+        if (g_ChrSlots[i].chrnum == chrnum)
+        {
+            return &g_ChrSlots[i];
+        }
+    }
+    for (i = 0; i < g_ActiveChrsCount; i++)
+    {
+        if (g_ActiveChrs[i].chrnum == chrnum)
+        {
+            return &g_ActiveChrs[i];
+        }
+    }
+    return NULL;
+}
+
+/* Table-driven pin signatures (D318 + D320). off_max is exclusive. */
+typedef struct
+{
+    u32         listid;
+    s32         off_min, off_max;
+    s32         ent;              /* required act_attack.entityid, -1 = any  */
+    s32         target_alive_chr; /* must exist w/ prop and be alive, -1 n/a */
+    const char *tag;              /* log tag                                 */
+} D318WEntry;
+
+#define D318W_NENTRIES 3
+static const D318WEntry s_wEntries[D318W_NENTRIES] = {
+    { 0x0417, 321, 333, D318_TREVELYAN_CHR, D318_TREVELYAN_CHR, "D318 Facility ai_22" },
+    { 0x0414, 480, 548, -1,               -1,                 "D320 Facility ai_19" },
+    { 0x040a, 60,  86,  -1,               -1,                 "D320 Control ai_9"   },
+};
+
+static bool d318wChrAlive(s32 chrnum)
+{
+    ChrRecord *c = d318wFindChr((s16)chrnum);
+
+    return c && c->prop && !chrIsDead(c);
+}
+
+/* Does this chr match the entry's pin signature? */
+static bool d318wMatches(const D318WEntry *en, ChrRecord *c)
+{
+    bool g = FALSE;
+
+    if (!c->ailist)
+    {
+        return FALSE;
+    }
+    if (chraiGetAIListID(c->ailist, &g) != (s32)en->listid)
+    {
+        return FALSE;
+    }
+    if (c->aioffset < en->off_min || c->aioffset >= en->off_max)
+    {
+        return FALSE;
+    }
+    if (c->actiontype != ACT_ATTACK)
+    {
+        return FALSE;
+    }
+    /* live-fire only: an AIM_ONLY pre-aim holding its pose is not a pin */
+    if ((s32)c->act_attack.attacktype & D320_TARGET_AIM_ONLY)
+    {
+        return FALSE;
+    }
+    if (en->ent >= 0 && (s32)c->act_attack.entityid != en->ent)
+    {
+        return FALSE;
+    }
+    return TRUE;
+}
+
+void d318WatchdogTick(void)
+{
+    static int   s_enabled = -1; /* -1 uncached, 0 off (GE_D318W=0), 1 on    */
+    static s32   s_run[D318W_NENTRIES];   /* sig-held ticks per entry         */
+    static s32   s_absent[D318W_NENTRIES];/* sig-absent ticks per entry       */
+    static s32   s_cool[D318W_NENTRIES];  /* ticks since last fire (sig up)   */
+    static s32   s_fires[D318W_NENTRIES]; /* rescues this occurrence          */
+    static bool  s_fired[D318W_NENTRIES];
+    s32 e, i;
+
+    if (s_enabled < 0)
+    {
+        const char *ev = getenv("GE_D318W");
+
+        s_enabled = (ev && ev[0] == '0') ? 0 : 1;
+    }
+    if (!s_enabled)
+    {
+        return;
+    }
+
+    for (e = 0; e < D318W_NENTRIES; e++)
+    {
+        const D318WEntry *en  = &s_wEntries[e];
+        ChrRecord        *hit = NULL;
+        bool              sig = FALSE;
+
+        for (i = 0; i < g_NumChrSlots && !hit; i++)
+        {
+            if (d318wMatches(en, &g_ChrSlots[i]))
+            {
+                hit = &g_ChrSlots[i];
+            }
+        }
+        for (i = 0; i < g_ActiveChrsCount && !hit; i++)
+        {
+            if (d318wMatches(en, &g_ActiveChrs[i]))
+            {
+                hit = &g_ActiveChrs[i];
+            }
+        }
+
+        sig = hit && (en->target_alive_chr < 0 || d318wChrAlive(en->target_alive_chr));
+
+        if (sig)
+        {
+            s_absent[e] = 0;
+            if (!s_fired[e])
+            {
+                if (s_run[e] == 1)
+                {
+                    osSyncPrintf("D318W: t=%d [%s] pin signature detected (c%d off=%d "
+                                 "ACT_ATTACK atk=0x%x ent=%d) -- starting %d-tick confirmation window\n",
+                                 (int)g_GlobalTimer, en->tag, (int)hit->chrnum,
+                                 (int)hit->aioffset, (unsigned)hit->act_attack.attacktype,
+                                 (int)hit->act_attack.entityid, D318_DEADLOCK_TICKS);
+                }
+                s_run[e]++;
+                if (s_run[e] >= D318_DEADLOCK_TICKS)
+                {
+                    osSyncPrintf("D318W: t=%d [%s] anim pin confirmed -- re-initializing "
+                                 "c%d's attack (sub_GAME_7F025560 atk=0x%x ent=%d) to break it\n",
+                                 (int)g_GlobalTimer, en->tag, (int)hit->chrnum,
+                                 (unsigned)hit->act_attack.attacktype,
+                                 (int)hit->act_attack.entityid);
+                    sub_GAME_7F025560(hit, (s32)hit->act_attack.attacktype,
+                                      (s32)hit->act_attack.entityid);
+                    s_fired[e] = TRUE;
+                    s_fires[e] = 1;
+                    s_cool[e]  = 0;
+                }
+            }
+            else if (++s_cool[e] >= D318W_REFIRE_TICKS)
+            {
+                /* The beat re-rolled and re-pinned (see header). No cap: */
+                s_cool[e] = 0;
+                osSyncPrintf("D318W: t=%d [%s] re-pin rescued (%d) -- c%d off=%d "
+                             "atk=0x%x ent=%d\n",
+                             (int)g_GlobalTimer, en->tag, s_fires[e] + 1,
+                             (int)hit->chrnum, (int)hit->aioffset,
+                             (unsigned)hit->act_attack.attacktype,
+                             (int)hit->act_attack.entityid);
+                sub_GAME_7F025560(hit, (s32)hit->act_attack.attacktype,
+                                  (s32)hit->act_attack.entityid);
+                s_fires[e]++;
+            }
+        }
+        else
+        {
+            s_run[e]  = 0;
+            s_cool[e] = 0;
+            /* Once the signature has been clear for a while after a fire,
+             * re-arm so a later replay of the level in the same process
+             * (AllUnlocked) is still covered. */
+            if (s_fired[e] && ++s_absent[e] >= D318_REARM_TICKS)
+            {
+                s_fired[e] = FALSE;
+                s_absent[e] = 0;
+                s_fires[e]  = 0;
+                osSyncPrintf("D318W: t=%d [%s] signature clear for %d ticks -- watchdog re-armed\n",
+                             (int)g_GlobalTimer, en->tag, D318_REARM_TICKS);
+            }
+        }
+    }
+}
+
+/* ------------------------------------------------------------------ */
+/* D318T: diagnostic timeline for the "Ourumov shoots Trevelyan the   */
+/* moment his lines begin" report (2026-09-20). Env-gated, OFF by     */
+/* default; enable with GE_D318T=1. Port-side read-only: logs state   */
+/* transitions so a single playtest captures which combat trigger     */
+/* (gas bit 0x04 vs Bond near-miss flag) derailed ai_22, and how many */
+/* ticks after the monologue started it landed. No game state is      */
+/* touched.                                                            */
+/*                                                                     */
+/* Background: the ONLY path by which c78 live-fires Trevelyan        */
+/* (entityid 67) in this scene is section 0x2a -> off=307             */
+/* actor_fire_or_aim_at_target_update succeeding while the pre-aim    */
+/* (ACT_ATTACK + AIM_ONLY|DONTTURN) is active. That requires a combat */
+/* trigger inside the monologue loop: gas bit 0x04 (off=75) or        */
+/* chrIfNearMiss (off=87, CHRFLAG_NEAR_MISS -- set by Bond bullets    */
+/* passing c78's bounds, cleared on c78's next tick). The freeze      */
+/* (D318) and the immediate-fire are the two branches of the same     */
+/* derailed state (random aim-variant endframe vs the hold frame H).  */
+/* ------------------------------------------------------------------ */
+
+/* Manual hex parse: MinGW's strtoull returns the sign-extended low 32 bits
+ * for values above LLONG_MAX (verified: "deadbeefcafe0123" ->
+ * ffffffffcafe0123). Parse by hand; stops at '@' or non-hex. */
+static u64 d318wParseHex(const char *s)
+{
+    u64 v = 0;
+
+    while (*s && *s != '@')
+    {
+        char c = *s++;
+
+        v <<= 4;
+        if (c >= '0' && c <= '9')      { v |= (u64)(c - '0'); }
+        else if (c >= 'a' && c <= 'f') { v |= (u64)(c - 'a' + 10); }
+        else if (c >= 'A' && c <= 'F') { v |= (u64)(c - 'A' + 10); }
+        else                           { break; }
+    }
+    return v;
+}
+
+void d318TimelineTick(void)
+{
+    /* E-B seed injection: GE_RSEED_LV=<hex64>[@tick] -- set g_randomSeed to
+     * the value read from N64 RAM (0x80024460) at a canonical moment, so the
+     * port's stream can be A/B-compared against the original from that point
+     * on. Test-only; inert without the env var. The DET line logs the running
+     * seed every 60 ticks for verifying stream parity afterwards. */
+    {
+        static int  s_seedArmed = 1;
+        static u64  s_seedVal   = 0;
+        static s32  s_seedTick  = 0;
+
+        if (s_seedArmed)
+        {
+            const char *e = getenv("GE_RSEED_LV");
+
+            s_seedArmed = 0;
+            if (e && e[0])
+            {
+                const char *at = strchr(e, '@');
+
+                s_seedVal  = d318wParseHex(e); /* MinGW strtoull mangles >LLONG_MAX */
+                s_seedTick = at ? (s32)strtol(at + 1, NULL, 10) : 0;
+            }
+        }
+        if (s_seedVal && (s32)g_GlobalTimer >= s_seedTick)
+        {
+            u64 v = s_seedVal;
+
+            g_randomSeed = v;
+            s_seedVal    = 0;
+            osSyncPrintf("D318T: t=%d RSEED_LV -> %016llx\n",
+                         (int)g_GlobalTimer, (unsigned long long)v);
+        }
+    }
+
+    static int  s_on      = -1; /* -1 uncached, 0 off, 1 on (GE_D318T=1)   */
+    static s32  s_obj     = -1;  /* last logged objectiveregisters1        */
+    static s32  s_off     = -1;  /* last logged c78 aioffset               */
+    static s32  s_act     = -1;  /* last logged c78 actiontype             */
+    static s32  s_atk     = -1;  /* last logged c78 act_attack.attacktype  */
+    static s32  s_ent     = -1;  /* last logged c78 act_attack.entityid    */
+    static s32  s_nm      = -1;  /* last logged c78 NEAR_MISS flag state   */
+    static f32  s_dmg     = -1.0f;
+    static bool s_dead    = FALSE;
+    static s32  s_hb      = 0;
+    static s32  s_det     = 0;  /* E1 determinism fingerprint counter       */
+    ChrRecord  *c78;
+    ChrRecord  *c67;
+
+    if (s_on < 0)
+    {
+        const char *e = getenv("GE_D318T");
+
+        s_on = (e && e[0] == '1') ? 1 : 0;
+    }
+    if (!s_on)
+    {
+        return;
+    }
+
+    /* Unified chr view: real guards live in g_ChrSlots[0..g_NumChrSlots) with
+     * model != NULL; the background script entities (chrnum 0xFE, list IDs
+     * >= 0x1000) live in g_ActiveChrs. Both are ticked by chrlvAllChrTick,
+     * so both must be scanned for pins / fingerprints. (D320, 2026-09-22:
+     * the detector originally walked g_ActiveChrs only and was blind to
+     * every real guard.) */
+    static ChrRecord *s_all[96];
+    static int        s_nall = 0;
+    s32               i;
+
+    s_nall = 0;
+    for (i = 0; i < g_NumChrSlots && s_nall < 96; i++)
+    {
+        if (g_ChrSlots[i].model != NULL)
+        {
+            s_all[s_nall++] = &g_ChrSlots[i];
+        }
+    }
+    for (i = 0; i < g_ActiveChrsCount && s_nall < 96; i++)
+    {
+        s_all[s_nall++] = &g_ActiveChrs[i];
+    }
+
+    c78 = d318wFindChr(D318_OURUMOV_CHR);
+    c67 = d318wFindChr(D318_TREVELYAN_CHR);
+
+    /* Objective bitfield transitions (the derail triggers live here:     */
+    /* 0x04 gas/combat, 0x20 surrender/monologue, 0x40 flee).             */
+    if (s_obj != objectiveregisters1)
+    {
+        osSyncPrintf("D318T: t=%d obj bits 0x%08x -> 0x%08x\n",
+                 (int)g_GlobalTimer, (unsigned)s_obj, (unsigned)objectiveregisters1);
+        s_obj = objectiveregisters1;
+    }
+
+    if (c78)
+    {
+        s32 nm = (c78->chrflags & CHRFLAG_NEAR_MISS) != 0;
+
+        /* D318 anim-internals line: catches the kneel-attack route          */
+        /* (unk54==0 => sub_GAME_7F0256F0 "chrAttackKneel" re-inits) and the */
+        /* hold/pin frame values, for the "bending down too far" report.     */
+        {
+            static s32 s_tom  = -1;
+            static u32 s_u54  = 0xFFFFFFFFu;
+            static f32 s_endf = -1.0f;
+
+            s32 tom  = (s32)c78->act_attack.type_of_motion;
+            u32 u54  = c78->act_attack.unk54;
+            f32 endf = c78->model ? modelGetAnimEndFrame(c78->model) : -1.0f;
+
+            if (s_tom != tom || s_u54 != u54 || s_endf != endf)
+            {
+                osSyncPrintf("D318T: t=%d c78 anim mot=%d unk54=%u endframe=%.2f frame1=%.2f (off=%d)\n",
+                             (int)g_GlobalTimer, tom, (unsigned)u54,
+                             (double)endf,
+                             (double)(c78->model ? modelGetAnimFrame(c78->model) : 0.0f),
+                             (int)c78->aioffset);
+                s_tom  = tom;
+                s_u54  = u54;
+                s_endf = endf;
+            }
+        }
+
+        if (s_off != (s32)c78->aioffset || s_act != (s32)c78->actiontype)
+        {
+            const char *phase = "?";
+
+            if (c78->aioffset >= 38 && c78->aioffset < 44)      { phase = "pre-aim(off38)"; }
+            else if (c78->aioffset >= 44 && c78->aioffset < 69) { phase = "wait-loop(off44)"; }
+            else if (c78->aioffset >= 69 && c78->aioffset < 272){ phase = "MONOLOGUE(off69+)"; }
+            else if (c78->aioffset >= 272 && c78->aioffset < 295){ phase = "execution(0x13)"; }
+            else if (c78->aioffset >= 302 && c78->aioffset < 333){ phase = "COMBAT-0x2a"; }
+
+            osSyncPrintf("D318T: t=%d c78 off=%d [%s] act=%d atk=0x%x ent=%d\n",
+                     (int)g_GlobalTimer, (int)c78->aioffset, phase,
+                     (int)c78->actiontype, (unsigned)c78->act_attack.attacktype,
+                     (int)c78->act_attack.entityid);
+            s_off = (s32)c78->aioffset;
+            s_act = (s32)c78->actiontype;
+        }
+        if (s_atk != (s32)c78->act_attack.attacktype || s_ent != (s32)c78->act_attack.entityid)
+        {
+            osSyncPrintf("D318T: t=%d c78 ATTACK CHANGE atk=0x%x ent=%d (off=%d)\n",
+                     (int)g_GlobalTimer, (unsigned)c78->act_attack.attacktype,
+                     (int)c78->act_attack.entityid, (int)c78->aioffset);
+            s_atk = (s32)c78->act_attack.attacktype;
+            s_ent = (s32)c78->act_attack.entityid;
+        }
+        if (s_nm != nm)
+        {
+            osSyncPrintf("D318T: t=%d c78 NEAR_MISS flag %s (Bond bullet passed his bounds)\n",
+                     (int)g_GlobalTimer, nm ? "SET" : "cleared");
+            s_nm = nm;
+        }
+    }
+
+    if (c67)
+    {
+        bool dead = chrIsDead(c67);
+
+        if (s_dmg != c67->damage || s_dead != dead)
+        {
+            osSyncPrintf("D318T: t=%d c67(Trevelyan) dmg=%.2f/%.2f %s\n",
+                     (int)g_GlobalTimer, (double)c67->damage, (double)c67->maxdamage,
+                     dead ? "DEAD" : "");
+            s_dmg = c67->damage;
+            s_dead = dead;
+        }
+    }
+
+    /* Heartbeat while c78 is on his execution list, so gaps are visible. */
+    if (c78 && c78->ailist)
+    {
+        bool g = FALSE;
+
+        if (chraiGetAIListID(c78->ailist, &g) == D318_LIST_AI22 && (++s_hb >= 60))
+        {
+            s_hb = 0;
+            osSyncPrintf("D318T: t=%d c78 hb off=%d act=%d atk=0x%x ent=%d obj=0x%08x\n",
+                     (int)g_GlobalTimer, (int)c78->aioffset, (int)c78->actiontype,
+                     (unsigned)c78->act_attack.attacktype, (int)c78->act_attack.entityid,
+                     (unsigned)objectiveregisters1);
+        }
+    }
+
+    /* E1 determinism fingerprint: one line per second over ALL active chrs  */
+    /* + the PRNG seed + objective bits. Two no-input runs that differ here */
+    /* are non-deterministic in the port (foundational); identical logs     */
+    /* mean run-to-run variation is input-timing-driven.                    */
+    if (++s_det >= 60)
+    {
+        s32 h = 0x811C9DC5;
+
+        s_det = 0;
+        for (i = 0; i < s_nall; i++)
+        {
+            ChrRecord *c = s_all[i];
+            union { f32 f; u32 u; } xf, yf, zf, df;
+
+            xf.f = c->prop ? c->prop->pos.x : 0.0f;
+            yf.f = c->prop ? c->prop->pos.y : 0.0f;
+            zf.f = c->prop ? c->prop->pos.z : 0.0f;
+            df.f = c->damage;
+            h ^= c->chrnum;          h = (h * 0x01000193) ^ 0x9E3779B9;
+            h ^= (s32)c->actiontype; h = (h * 0x01000193) ^ 0x9E3779B9;
+            h ^= (s32)c->aioffset;   h = (h * 0x01000193) ^ 0x9E3779B9;
+            h ^= xf.u;               h = (h * 0x01000193) ^ 0x9E3779B9;
+            h ^= yf.u;               h = (h * 0x01000193) ^ 0x9E3779B9;
+            h ^= zf.u;               h = (h * 0x01000193) ^ 0x9E3779B9;
+            h ^= df.u;               h = (h * 0x01000193) ^ 0x9E3779B9;
+        }
+        osSyncPrintf("D318T: DET t=%d seed=%08x%08x obj=0x%08x h=%08x nchrs=%d\n",
+                     (int)g_GlobalTimer,
+                     (unsigned)(u32)(g_randomSeed >> 32), (unsigned)(u32)g_randomSeed,
+                     (unsigned)objectiveregisters1, (unsigned)h, s_nall);
+    }
+
+    /* D320: generic D318-class pin DETECTION for the sweep's flagged lists
+     * (Facility ai_19, Control ai_9, Depot ai_12 -- see findings D320).
+     * Detection only: it logs, it never intervenes; the recovery watchdog
+     * above stays hardcoded to ai_22 by design until a second list actually
+     * freezes in play (D320's explicit instruction).
+     *
+     * Signature: a chr in ACT_ATTACK whose attacktype is LIVE FIRE (no
+     * TARGET_AIM_ONLY bit -- it is supposed to be shooting) and whose
+     * modelGetAnimFrame is byte-stable for 600 consecutive ticks (10 s). A
+     * guard that should be firing but whose animation never advances is the
+     * exact D318 frozen shape on any list. The two legitimate long-stable
+     * states are excluded or self-clearing: monologue pre-aims keep the
+     * AIM_ONLY bit (excluded), and a working fire cycle re-inits through
+     * chrlvTickAttackCommon's "endframe <= frame" block, so its frame does
+     * not stay byte-stable for 10 s. One line at first detection, then one
+     * per further 600 stable ticks while it persists; a frozen run keeps
+     * printing, an escaped run stops after the single line (or none). */
+    {
+        typedef struct { s16 chrnum; u32 framebits; s32 stable; s32 nextlog; }
+                D320Pin;
+        static D320Pin s_pins[8];
+        static int     s_npins = 0;
+        s32 i, j;
+
+        for (i = 0; i < s_nall; i++)
+        {
+            ChrRecord *c = s_all[i];
+            union { f32 f; u32 u; } fr;
+            D320Pin   *p = NULL;
+
+            if (c->actiontype != ACT_ATTACK || c->model == NULL)
+            {
+                continue;
+            }
+            if ((s32)c->act_attack.attacktype & D320_TARGET_AIM_ONLY)
+            {
+                continue; /* legitimate hold pose (monologue pre-aim) */
+            }
+
+            fr.f = modelGetAnimFrame(c->model);
+            for (j = 0; j < s_npins; j++)
+            {
+                if (s_pins[j].chrnum == c->chrnum)
+                {
+                    p = &s_pins[j];
+                    break;
+                }
+            }
+            if (!p)
+            {
+                if (s_npins < 8)
+                {
+                    p = &s_pins[s_npins++];
+                }
+                else
+                {
+                    continue; /* table full: drop the newest, keep tracking */
+                }
+                p->chrnum    = c->chrnum;
+                p->framebits = fr.u;
+                p->stable    = 0;
+                p->nextlog   = 600;
+            }
+
+            if (p->framebits == fr.u)
+            {
+                p->stable++;
+            }
+            else
+            {
+                p->framebits = fr.u;
+                p->stable    = 0;
+                p->nextlog   = 600;
+            }
+
+            if (p->stable >= p->nextlog)
+            {
+                bool g = FALSE;
+                s32 aid = c->ailist ? chraiGetAIListID(c->ailist, &g) : -1;
+
+                osSyncPrintf("D320T: t=%d PIN? c%d aiid=0x%04x%s off=%d atk=0x%x ent=%d "
+                             "mot=%d unk54=%u frame=%.2f stable=%d ticks (D318-class pin candidate)\n",
+                             (int)g_GlobalTimer, (int)c->chrnum,
+                             (unsigned)aid, g ? "G" : "", (int)c->aioffset,
+                             (unsigned)c->act_attack.attacktype,
+                             (int)c->act_attack.entityid,
+                             (s32)c->act_attack.type_of_motion,
+                             (unsigned)c->act_attack.unk54,
+                             (double)fr.f, p->stable);
+                p->nextlog = p->stable + 600;
+            }
+        }
+
+        /* Drop entries for chrs that left the tracked state so a later
+         * re-entry starts a fresh confirmation window. */
+        for (i = 0; i < s_npins; i++)
+        {
+            bool alive = FALSE;
+
+            for (j = 0; j < s_nall; j++)
+            {
+                ChrRecord *c = s_all[j];
+
+                if (c->chrnum == s_pins[i].chrnum && c->actiontype == ACT_ATTACK
+                    && c->model != NULL
+                    && !((s32)c->act_attack.attacktype & D320_TARGET_AIM_ONLY))
+                {
+                    alive = TRUE;
+                    break;
+                }
+            }
+            if (!alive)
+            {
+                s_pins[i] = s_pins[--s_npins];
+                i--;
+            }
+        }
+    }
+}
+
+#endif /* PORT */

port/src/d320repro.c

@@ -0,0 +1,480 @@
+/* d320repro.c -- D320: forced-repro harness for the three high-risk
+ * D318-class aim-hold softlock lists (Facility ai_19, Control ai_9,
+ * Depot ai_12; findings D320).
+ *
+ * These beats are scripted cutscene moments that do not play in a bare
+ * headless boot (the scene is static with no input), so -- exactly like
+ * D318's mode-5 repro -- the probe forces them: at chosen ticks it can
+ * dump the chr roster, hijack a guard's AI pointer to a loaded list at a
+ * given byte offset, and/or set objective-register bits. The in-tree
+ * D320T pin detector (d318watchdog.c, GE_D318T=1) then reports any
+ * live-fire attack whose anim frame stays byte-stable for 600 ticks --
+ * the exact frozen shape.
+ *
+ * TEMP: investigation probe, remove when D320 concludes. Inert without
+ * the env var (zero cost).
+ *
+ * Usage: GE_D320R="tick:action;tick:action;..." where action is one of
+ *   roster                          -- dump every active chr (num, act,
+ *                                      list id, offset, alive)
+ *   jump=<chr>,list=<hexid>,off=<n> -- set the chr's ailist to
+ *                                      ailistFindById(hexid) at byte
+ *                                      offset n, sleep=0
+ *   bit=<hex>                       -- objectiveregisters1 |= hex
+ *   rename=<chr>,<newnum>           -- reassign a chr's chrnum (used to
+ *                                      materialize an absent target, e.g.
+ *                                      Control ai_9 aims at 0xFC which is
+ *                                      not spawned in a bare boot)
+ *   seed=<hi32>,<lo32>              -- overwrite g_randomSeed (the boot
+ *                                      seed is deterministic, so vary this
+ *                                      between runs to sample different
+ *                                      aim-variant branches)
+ *   explode=<type>,<dist>           -- D252: explosionCreate(<type>) <dist>
+ *                                      units in front of Bond (headless
+ *                                      explosion-particle capture)
+ *   cheat=gl|rl|inv|<id>            -- D252: cheatButtonHandleCheatsTurnedOn
+ *   trace=<chr>                     -- from this tick on, log the chr's
+ *                                      off/act/atk/ent/frame/endframe on
+ *                                      any change + a 120-tick heartbeat
+ *                                      while it is in ACT_ATTACK
+ *
+ * Example (Facility ai_19 hold block):
+ *   GE_D320R="60:roster;900:jump=5,list=0x0414,off=341;900:trace=5"
+ */
+#include <stdlib.h>
+#include <string.h>
+
+#include "PR/os.h"
+#include "bondtypes.h"
+#include "chr.h"
+#include "chrai.h"
+#include "chraction.h"
+#include "lv.h"
+#include "model.h"
+#include "explosion.h"
+#include "player.h"
+#include "cheat.h"
+extern void cheatButtonHandleCheatsTurnedOn(CHEAT_ID cheat_id);
+
+#ifdef PORT
+
+/* chrai.c defines these but chrai.h does not declare them. */
+extern s32 chraiGetAIListID(AIRecord *AIList, bool *isGlobalAIList);
+
+/* port/src/random.c; not declared in a shared header. */
+extern u64 g_randomSeed;
+
+#define D320R_MAX_ACTIONS 16
+#define D320R_MAX_TRACES  4
+
+typedef struct
+{
+    s32  tick;
+    int  kind; /* 0 roster, 1 jump, 2 bit, 3 trace */
+    s16  chr;
+    s32  listid;
+    u16  off;
+    u32  bit;   /* also: new chrnum for rename */
+    int  fired;
+} D320RAction;
+
+typedef struct
+{
+    s16  chr;
+    s32  off;
+    s32  act;
+    s32  atk;
+    s32  ent;
+    u32  framebits;
+    s32  hb;
+} D320RTrace;
+
+static ChrRecord *d320rFindChr(s16 chrnum)
+{
+    s32 i;
+
+    for (i = 0; i <g_NumChrSlots; i++)
+    {
+        if (g_ChrSlots[i].chrnum == chrnum)
+        {
+            return &g_ChrSlots[i];
+        }
+    }
+    for (i = 0; i < g_ActiveChrsCount; i++)
+    {
+        if (g_ActiveChrs[i].chrnum == chrnum)
+        {
+            return &g_ActiveChrs[i];
+        }
+    }
+    return NULL;
+}
+
+static void d320rDumpRoster(void)
+{
+    s32 i;
+
+    osSyncPrintf("D320R: t=%d roster slots=%d bgchrs=%d\n", (int)g_GlobalTimer,
+                 (int)g_NumChrSlots, (int)g_ActiveChrsCount);
+    for (i = 0; i < g_NumChrSlots; i++)
+    {
+        ChrRecord *c = &g_ChrSlots[i];
+        bool       g = FALSE;
+        s32        aid;
+
+        if (c->model == NULL)
+        {
+            continue;
+        }
+        aid = c->ailist ? chraiGetAIListID(c->ailist, &g) : -1;
+        osSyncPrintf("D320R:   S c%d act=%d aiid=0x%04x%s off=%d atk=0x%x ent=%d %s\n",
+                     (int)c->chrnum, (int)c->actiontype, (unsigned)aid,
+                     g ? "G" : "", (int)c->aioffset,
+                     (unsigned)c->act_attack.attacktype,
+                     (int)c->act_attack.entityid,
+                     chrIsDead(c) ? "DEAD" : "");
+    }
+    for (i = 0; i < g_ActiveChrsCount; i++)
+    {
+        ChrRecord *c = &g_ActiveChrs[i];
+        bool       g = FALSE;
+        s32        aid = c->ailist ? chraiGetAIListID(c->ailist, &g) : -1;
+
+        osSyncPrintf("D320R:   B c%d act=%d aiid=0x%04x%s off=%d\n",
+                     (int)c->chrnum, (int)c->actiontype, (unsigned)aid,
+                     g ? "G" : "", (int)c->aioffset);
+    }
+}
+
+void d320ReproTick(void)
+{
+    static int        s_on = -1; /* -1 uncached, 0 off, 1 on              */
+    static D320RAction s_a[D320R_MAX_ACTIONS];
+    static int         s_na = 0;
+    static D320RTrace  s_tr[D320R_MAX_TRACES];
+    static int         s_nt = 0;
+    s32 i;
+
+    if (s_on < 0)
+    {
+        const char *e = getenv("GE_D320R");
+
+        s_on = (e && e[0]) ? 1 : 0;
+        if (s_on)
+        {
+            /* Parse "tick:action;..." -- one pass, fixed budget. */
+            char buf[512];
+            char *p, *save;
+
+            strncpy(buf, e, sizeof(buf) - 1);
+            buf[sizeof(buf) - 1] = 0;
+            p = buf;
+            while (p && *p && s_na < D320R_MAX_ACTIONS)
+            {
+                char        *semi = strchr(p, ';');
+                char        *colon;
+                D320RAction *a    = &s_a[s_na];
+
+                if (semi)
+                {
+                    *semi = 0;
+                }
+                colon = strchr(p, ':');
+                if (!colon)
+                {
+                    break;
+                }
+                *colon = 0;
+                a->tick = (s32)strtol(p, NULL, 10);
+                a->kind = -1;
+                a->chr  = -1;
+                a->listid = 0;
+                a->off    = 0;
+                a->bit    = 0;
+                a->fired  = 0;
+
+                if (strcmp(colon + 1, "roster") == 0)
+                {
+                    a->kind = 0;
+                }
+                else if (strncmp(colon + 1, "jump=", 5) == 0)
+                {
+                    const char *q = colon + 6;
+
+                    /* documented form "jump=<chr>,list=..": a leading bare
+                     * number (no '=' before the first ',') is the chr */
+                    {
+                        char *eq0 = strchr(q, '=');
+                        char *cm0 = strchr(q, ',');
+
+                        if (cm0 && (!eq0 || cm0 < eq0))
+                        {
+                            *cm0   = 0;
+                            a->chr = (s16)strtol(q, NULL, 0);
+                            q      = cm0 + 1;
+                        }
+                    }
+
+                    while (q && *q)
+                    {
+                        char       *eq = strchr(q, '=');
+                        char       *cm  = strchr(q, ',');
+                        const char *key;
+
+                        if (!eq)
+                        {
+                            break;
+                        }
+                        if (cm && cm < eq)
+                        {
+                            break; /* malformed */
+                        }
+                        *eq = 0;
+                        key = q; /* const-cast: parsed in place below */
+                        if (strcmp(key, "chr") == 0)      { a->chr    = (s16)strtol(eq + 1, NULL, 0); }
+                        else if (strcmp(key, "list") == 0){ a->listid = (s32)strtol(eq + 1, NULL, 0); }
+                        else if (strcmp(key, "off") == 0) { a->off    = (u16)strtol(eq + 1, NULL, 0); }
+                        q = cm ? cm + 1 : NULL;
+                    }
+                    if (a->chr >= 0 && a->listid)
+                    {
+                        a->kind = 1;
+                    }
+                }
+                else if (strncmp(colon + 1, "bit=", 4) == 0)
+                {
+                    a->bit  = (u32)strtol(colon + 5, NULL, 0);
+                    a->kind = 2;
+                }
+                else if (strncmp(colon + 1, "trace=", 6) == 0)
+                {
+                    a->chr  = (s16)strtol(colon + 7, NULL, 0);
+                    a->kind = 3;
+                }
+                else if (strncmp(colon + 1, "rename=", 7) == 0)
+                {
+                    const char *q  = colon + 8;
+                    char       *cm = strchr(q, ',');
+
+                    if (cm)
+                    {
+                        *cm         = 0;
+                        a->chr      = (s16)strtol(q, NULL, 0);
+                        a->bit      = (u32)strtol(cm + 1, NULL, 0);
+                        a->kind     = 4;
+                    }
+                }
+                else if (strncmp(colon + 1, "cheat=", 6) == 0)
+                {
+                    const char *q = colon + 7;
+
+                    a->listid = (strcmp(q, "gl") == 0)    ? CHEAT_2X_GRENADE_LAUNCHER
+                              : (strcmp(q, "rl") == 0)    ? CHEAT_2X_ROCKET_LAUNCHER
+                              : (strcmp(q, "inv") == 0)   ? CHEAT_INVINCIBILITY
+                              : (s32)strtol(q, NULL, 0);
+                    a->kind   = 7;
+                }
+                else if (strncmp(colon + 1, "explode=", 8) == 0)
+                {
+                    const char *q  = colon + 9;
+                    char       *cm = strchr(q, ',');
+
+                    a->listid = (s32)strtol(q, NULL, 0);                 /* type */
+                    a->bit    = cm ? (u32)strtol(cm + 1, NULL, 0) : 400; /* dist */
+                    a->kind   = 6;
+                }
+                else if (strncmp(colon + 1, "seed=", 5) == 0)
+                {
+                    const char *q  = colon + 6;
+                    char       *cm = strchr(q, ',');
+
+                    if (cm)
+                    {
+                        *cm         = 0;
+                        a->listid   = (s32)(u32)strtol(q, NULL, 0);      /* hi */
+                        a->bit      = (u32)strtol(cm + 1, NULL, 0);      /* lo */
+                        a->kind     = 5;
+                    }
+                }
+                if (a->kind >= 0)
+                {
+                    s_na++;
+                }
+                p = semi ? semi + 1 : NULL;
+            }
+            osSyncPrintf("D320R: armed %d actions\n", s_na);
+        }
+    }
+    if (!s_on)
+    {
+        return;
+    }
+
+    for (i = 0; i < s_na; i++)
+    {
+        D320RAction *a = &s_a[i];
+
+        if (a->fired || (s32)g_GlobalTimer < a->tick)
+        {
+            continue;
+        }
+        a->fired = 1;
+
+        switch (a->kind)
+        {
+            case 0: /* roster */
+                d320rDumpRoster();
+                break;
+            case 1: /* jump */
+            {
+                ChrRecord *c = d320rFindChr(a->chr);
+
+                if (c)
+                {
+                    AIRecord *list = ailistFindById(a->listid);
+
+                    if (list)
+                    {
+                        c->ailist   = list;
+                        c->aioffset = a->off;
+                        c->sleep    = 0;
+                        osSyncPrintf("D320R: t=%d JUMP c%d -> aiid=0x%04x off=%d\n",
+                                     (int)g_GlobalTimer, (int)c->chrnum,
+                                     (unsigned)a->listid, (int)a->off);
+                    }
+                    else
+                    {
+                        osSyncPrintf("D320R: t=%d JUMP FAILED c%d aiid=0x%04x not found\n",
+                                     (int)g_GlobalTimer, (int)c->chrnum,
+                                     (unsigned)a->listid);
+                    }
+                }
+                else
+                {
+                    osSyncPrintf("D320R: t=%d JUMP FAILED c%d not active\n",
+                                 (int)g_GlobalTimer, (int)a->chr);
+                }
+                break;
+            }
+            case 7: /* cheat (D252) */
+                cheatButtonHandleCheatsTurnedOn((CHEAT_ID)a->listid);
+                osSyncPrintf("D320R: t=%d CHEAT %d\n",(int)g_GlobalTimer, (int)a->listid);
+                break;
+            case 6: /* explode (D252) */
+                if (g_CurrentPlayer && g_CurrentPlayer->prop)
+                {
+                    struct coord3d pos = g_CurrentPlayer->prop->pos;
+
+                    pos.f[0] += -g_CurrentPlayer->vv_sintheta * (f32)a->bit;
+                    pos.f[2] += g_CurrentPlayer->vv_costheta * (f32)a->bit;
+                    explosionCreate(0, &pos, g_CurrentPlayer->prop->stan, (s16)a->listid,
+                                    0, 0, g_CurrentPlayer->prop->rooms, 0);
+                    osSyncPrintf("D320R: t=%d EXPLODE type=%d dist=%u\n",
+                                 (int)g_GlobalTimer, (int)a->listid, (unsigned)a->bit);
+                }
+                break;
+            case 2: /* bit */
+                objectiveregisters1 |= a->bit;
+                osSyncPrintf("D320R: t=%d BIT |= 0x%08x (now 0x%08x)\n",
+                             (int)g_GlobalTimer, (unsigned)a->bit,
+                             (unsigned)objectiveregisters1);
+                break;
+            case 3: /* trace */
+                if (s_nt < D320R_MAX_TRACES)
+                {
+                    s_tr[s_nt].chr       = a->chr;
+                    s_tr[s_nt].off       = -1;
+                    s_tr[s_nt].act       = -1;
+                    s_tr[s_nt].atk       = -1;
+                    s_tr[s_nt].ent       = -1;
+                    s_tr[s_nt].framebits = 0;
+                    s_tr[s_nt].hb        = 0;
+                    s_nt++;
+                    osSyncPrintf("D320R: t=%d TRACE c%d armed\n",
+                                 (int)g_GlobalTimer, (int)a->chr);
+                }
+                break;
+            case 4: /* rename */
+            {
+                ChrRecord *c = d320rFindChr(a->chr);
+
+                if (c)
+                {
+                    osSyncPrintf("D320R: t=%d RENAME c%d -> c%d\n",
+                                 (int)g_GlobalTimer, (int)c->chrnum,
+                                 (int)a->bit);
+                    c->chrnum = (s16)a->bit;
+                }
+                else
+                {
+                    osSyncPrintf("D320R: t=%d RENAME FAILED c%d not found\n",
+                                 (int)g_GlobalTimer, (int)a->chr);
+                }
+                break;
+            }
+            case 5: /* seed */
+                g_randomSeed = ((u64)(u32)a->listid << 32) | (u32)a->bit;
+                osSyncPrintf("D320R: t=%d SEED := %08x%08x\n",
+                             (int)g_GlobalTimer, (unsigned)(u32)(g_randomSeed >> 32),
+                             (unsigned)(u32)g_randomSeed);
+                break;
+            default:
+                break;
+        }
+    }
+
+    for (i = 0; i < s_nt; i++)
+    {
+        D320RTrace *t = &s_tr[i];
+        ChrRecord  *c = d320rFindChr(t->chr);
+        u32         fb = 0;
+        f32         fr = 0.0f, ef = -1.0f;
+
+        if (!c)
+        {
+            continue;
+        }
+        if (c->model)
+        {
+            union { f32 f; u32 u; } x;
+
+            x.f    = modelGetAnimFrame(c->model);
+            fb     = x.u;
+            fr     = x.f;
+            ef     = modelGetAnimEndFrame(c->model);
+        }
+
+        if (t->off != (s32)c->aioffset || t->act != (s32)c->actiontype
+            || t->atk != (s32)c->act_attack.attacktype
+            || t->ent != (s32)c->act_attack.entityid)
+        {
+            osSyncPrintf("D320R: t=%d c%d off=%d act=%d atk=0x%x ent=%d frame=%.2f endf=%.2f\n",
+                         (int)g_GlobalTimer, (int)c->chrnum, (int)c->aioffset,
+                         (int)c->actiontype, (unsigned)c->act_attack.attacktype,
+                         (int)c->act_attack.entityid, (double)fr, (double)ef);
+            t->off = (s32)c->aioffset;
+            t->act = (s32)c->actiontype;
+            t->atk = (s32)c->act_attack.attacktype;
+            t->ent = (s32)c->act_attack.entityid;
+        }
+        else if (c->actiontype == ACT_ATTACK && fb != t->framebits)
+        {
+            /* frame is moving: note the range so a later stall is visible */
+            osSyncPrintf("D320R: t=%d c%d frame MOVED to %.2f (endf=%.2f off=%d)\n",
+                         (int)g_GlobalTimer, (int)c->chrnum, (double)fr,
+                         (double)ef, (int)c->aioffset);
+        }
+        t->framebits = fb;
+
+        if (c->actiontype == ACT_ATTACK && ++t->hb >= 120)
+        {
+            t->hb = 0;
+            osSyncPrintf("D320R: t=%d c%d hb off=%d act=%d atk=0x%x ent=%d frame=%.2f endf=%.2f\n",
+                         (int)g_GlobalTimer, (int)c->chrnum, (int)c->aioffset,
+                         (int)c->actiontype, (unsigned)c->act_attack.attacktype,
+                         (int)c->act_attack.entityid, (double)fr, (double)ef);
+        }
+    }
+}
+
+#endif /* PORT */

port/src/dram.c

@@ -71,7 +71,7 @@ void *dramReserve(void)
     sa.bInheritHandle = FALSE;
 
     HANDLE hSec = CreateFileMappingW(INVALID_HANDLE_VALUE, &sa, PAGE_READWRITE,
-                                     (DWORD)(DRAM_SIZE >> 32),
+                                     (DWORD)((unsigned long long)DRAM_SIZE >> 32),
                                      (DWORD)(DRAM_SIZE & 0xFFFFFFFF), NULL);
     if (!hSec) {
         sysFatalError("dram: CreateFileMapping failed (%lu)", GetLastError());

port/src/frontoptions.c

@@ -0,0 +1,844 @@
+/*
+ * frontoptions.c -- D343: PC options as a GE front-end screen.
+ *
+ * GE's front end has no generic menu system, so PC settings get their own
+ * screen, MENU_PC_OPTIONS (route B, docs/dev/OPTIONS-MENU-PLAN.md), built the
+ * way GE builds its Cheat Options screen (front.c init/interface/constructor_
+ * menu15_cheat): the open dossier with tabs and a blank CLASSIFIED page, black
+ * Zurich text on the paper via frontPrintText, GE's translucent highlight
+ * boxes, the PREVIOUS tab as "back", and the game's crosshair.
+ *
+ *   page 0: five functional categories; page 1: a category's settings;
+ *   deeper pages: Input -> Bindings -> Movement/Actions and Gameplay -> HUD
+ *
+ * The sections and rows are the F10 overlay's row table, reached through the
+ * row API in optionsoverlay.c, so both UIs edit the same settings.
+ *
+ * Game-code surface (Rule 2, user sign-off 2026-09-27): the MENU_PC_OPTIONS
+ * enum value (bondconstants.h) and five one-line dispatch cases (front.c),
+ * all #ifdef PORT. Entry is the "PC Options" label on file select, drawn by
+ * the existing D343 hook in constructor_menu05_fileselect.
+ *
+ * Everything here runs on the game's main thread (the front-end tick and
+ * constructor), like GE's own screens.
+ */
+
+#include <string.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+#include <ultra64.h>
+#include <bondgame.h>
+#include <bondconstants.h>
+#include <fr.h>
+#include <joy.h>
+#include <music.h>
+#include <snd.h>
+#include "front.h"
+#include "textrelated.h"
+#include "language.h"
+
+#include "platform.h"
+#include "system.h"
+#include "config.h"
+#include "envflag.h"
+#include "optionsoverlay.h"
+#include "watchsettings.h"
+#include "frontoptions.h"
+#include "input.h"
+
+/* front.c functions this screen shares with the cheat screen (not all are in
+ * front.h). */
+extern Gfx *frontSetupMenuBackground(Gfx *DL);
+extern Gfx *frontAddPreviousTabText(Gfx *DL);
+extern s32  frontCheckCursorOnPreviousTab(void);
+extern Gfx *frontDrawCursor(Gfx *DL);
+extern Gfx *frontPrintText(Gfx *gdl, s32 *x, s32 *y, s8 *text, s32 second_font_table,
+                           s32 first_font_table, s32 arg6, s32 view_x, s32 view_y,
+                           s32 arg9, s32 arga);
+extern void load_walletbond(void);
+extern void disable_all_switches(Model *arg0);                                   /* front.c:967 */
+extern void set_item_visibility_in_objinstance(Model *objinstance, s32 item, s32 mode); /* front.c:968 */
+extern s32  folder_selection_screen_option_icon;
+extern struct rectbbox folder_option_ERASE_bound;   /* front.c:439 */
+
+/* ---- colours on the paper (RRGGBBAA; 0xFF = opaque black, GE's ink) ---- */
+#define INK        0x000000FFu
+#define INK_ON     0xA00000FFu   /* the cheat screen's ON red */
+#define INK_DIM    0x00000080u
+#define HILITE     0x32          /* GE's menu highlight box (black, alpha 0x32) */
+
+/* ---- layout, in the front end's 440x330 canvas (paper; tabs start at 390) ---- */
+#define TITLE_Y    0x2B
+#define ROW_X      0x37          /* the cheat list's x */
+#define ROW_Y0     0x41          /* cheat list starts 0x35; +12 for the title line */
+/* D346b: 20 -> 18 px so a full section fits the paper on one page. Hit bands
+ * stay contiguous at any pitch >= 6; the 22px highlight box still clears the
+ * next row (y+14 < y+17). D353: the largest section is now GRAPHICS at 11
+ * rows (both auto-FOV toggles off); MAX_PROWS=15 keeps headroom, and
+ * buildPages() logs any future overflow instead of silently truncating. */
+#define ROW_DY     18
+#define NUM_X      0x37          /* "1." on the section list */
+#define SEC_X      0x4B
+#define VAL_R      372           /* values right-aligned here */
+#define BAR_X0     232
+#define BAR_X1     316
+#define ROW_HIT_X0 40.0f
+#define ROW_HIT_X1 385.0f
+
+/* ---- file-select label: right end of the Select / Copy / Erase bar ---- */
+#define LABEL_X     351   /* D400: floor = NTSC Erase right (~323) + LABEL_GAP; JP's wider Erase pushes past it */
+#define LABEL_CY    285   /* the bar's centre line, as Copy/Erase */
+#define LABEL_GAP   28    /* D400: text-only now (icon removed), a plain word gap after Erase */
+#define HIT_PAD     4
+
+#define MAX_PAGES  8
+#define MAX_PROWS  15            /* D346b: 12 -> 15 for the merged Video section (see ROW_DY) */
+/* D406: content rows per page. The 440x330 paper ends at y=330; content row k
+ * sits at y = ROW_Y0 + (k+2)*ROW_DY (the D356 profile row takes slot 1), so a
+ * page fits while ROW_Y0 + (CAP+2)*ROW_DY + ~10px of text stays <= 330 (the
+ * bottom line is reserved for the page hint): CAP = 11 at ROW_DY 18. D346b's 18px pitch was sized for 15 rows with no
+ * profile row; D356's profile row plus the v0.4.0 Wave-A INPUT rows (17)
+ * pushed the 14th row to y=335 -- off the bottom of the paper -- and rows
+ * 15-17 (Crouch mode, Reset to defaults, Bindings...) were dropped by the
+ * old silent page cap, unreachable from the front screen. Sections that
+ * outgrow one page now page: the vertical stepper crosses page boundaries
+ * and the title carries a (p/N) marker. The F10 overlay is unaffected
+ * (it scrolls its own window, D345-D347). */
+#define ROWS_PER_PAGE 11
+
+static const char kLabel[]   = "PC Options";  /* ASCII only: issue #87 / D295 */
+static const char kLabelNL[] = "PC Options\n"; /* height measure only, D400 */
+
+/* ---- screen state (game thread) ---- */
+static int s_level = 0;          /* 0 = categories, 1 = category, 2/3 = nested pages */
+static int s_page = 0;           /* current root category */
+static int s_pageno = 0;         /* D406: page within the active section */
+static int s_rowTotal = 0;       /* D406: visible rows in the active section */
+static int s_subHeader = -1;     /* rows[] header index for the nested page */
+static int s_hl = -1;            /* highlighted row / section, -1 = none */
+static int s_dragRow = -1;       /* global row index being dragged */
+static int s_repeatDir = 0, s_repeatTimer = 0;
+/* D345(e): hold-to-repeat state for vertical row stepping (separate from
+ * the left/right value-adjust repeat; both can be held at once). */
+static int s_vrepeatDir = 0, s_vrepeatTimer = 0;
+
+static int s_pageHdr[MAX_PAGES];
+static int s_pageN = 0;
+static int s_rowIdx[MAX_PROWS];
+static int s_rowN = 0;
+#define MAX_SECT_ROWS 48   /* D406: per-section gather buffer (INPUT = 17) */
+
+/* ------------------------------------------------------------------------ */
+
+static void playSfx(s16 id)
+{
+    sndPlaySfx((struct ALBankAlt_s *)g_musicSfxBufferPtr, id, NULL);
+}
+
+static s32 measureW(const char *str)
+{
+    s32 h = 0, w = 0;
+    textMeasure(&h, &w, (char *)str, ptrFontZurichBoldChars, ptrFontZurichBold, 0);
+    return w;
+}
+
+static Gfx *ink(Gfx *DL, s32 x, s32 y, const char *str, u32 colour)
+{
+    return frontPrintText(DL, &x, &y, (s8 *)str, (s32)(uintptr_t)ptrFontZurichBoldChars,
+                          (s32)(uintptr_t)ptrFontZurichBold, (s32)colour,
+                          viGetX(), viGetY(), 0, 0);
+}
+
+static Gfx *inkR(Gfx *DL, s32 xr, s32 y, const char *str, u32 colour)
+{
+    return ink(DL, xr - measureW(str), y, str, colour);
+}
+
+/* D406b: per-row slider-bar origin. Long labels ("X axis look sensitivity
+ * (controller)") used to run into the fixed 232px bar and overlap the track;
+ * the bar now starts 10px past the label. Rows whose labels leave less than
+ * 12px of track show the value only. */
+static int rowBarX0(const char *label)
+{
+    int x0 = ROW_X + measureW(label) + 10;
+    return x0 < BAR_X0 ? BAR_X0 : x0;
+}
+
+/* "MOUSE / AIM" -> "Mouse / Aim" (GE's menus use title case). */
+static void titleCase(const char *in, char *out, int n)
+{
+    int j = 0, start = 1;
+    for (int i = 0; in[i] && j < n - 1; i++) {
+        char c = in[i];
+        if (c >= 'A' && c <= 'Z' && !start) c = (char)(c - 'A' + 'a');
+        if (c >= 'a' && c <= 'z' && start)  c = (char)(c - 'a' + 'A');
+        start = (c == ' ' || c == '/');
+        out[j++] = c;
+    }
+    out[j] = '\0';
+}
+
+static int rowY(int k)
+{
+    /* Every open section, including a nested section, has the profile row. */
+    if (s_level >= 1) k++;
+    return ROW_Y0 + k * ROW_DY;
+}
+
+static int activeHeader(void)
+{
+    return s_level >= 2 ? s_subHeader : s_pageHdr[s_page];
+}
+
+static void buildPages(void)
+{
+    int n = optionsRowCount();
+    s_pageN = 0;
+    for (int i = 0; i < n && s_pageN < MAX_PAGES; i++) {
+        if (optionsRowIsHeader(i) && optionsRowHeaderParent(i) < 0)
+            s_pageHdr[s_pageN++] = i;
+    }
+    if (s_page >= s_pageN) {
+        s_page = 0;
+    }
+    s_rowN = 0;
+    s_rowTotal = 0;
+    if (s_pageN > 0) {
+        /* D406: gather every visible row of the active section, then page it
+         * (ROWS_PER_PAGE fits the paper, see above). The old code capped at
+         * MAX_PROWS-1 and silently dropped the rest -- a warning, no access.
+         * s_pageno is re-clamped on every build so rows that auto-hide
+         * (aim range, auto-FOV) cannot strand the cursor past the end. */
+        int tmp[MAX_SECT_ROWS];
+        int tn = 0;
+        for (int i = activeHeader() + 1; i < n && !optionsRowIsHeader(i); i++) {
+            if (!optionsRowIsShown(i)) continue;
+            if (tn < MAX_SECT_ROWS) tmp[tn++] = i;
+        }
+        s_rowTotal = tn;
+        int pages = (tn + ROWS_PER_PAGE - 1) / ROWS_PER_PAGE;
+        if (pages < 1) pages = 1;
+        if (s_pageno > pages - 1) s_pageno = pages - 1;
+        int off = s_pageno * ROWS_PER_PAGE;
+        for (int k = 0; k < ROWS_PER_PAGE && off + k < tn; k++)
+            s_rowIdx[s_rowN++] = tmp[off + k];
+    }
+}
+
+static int itemCount(void)
+{
+    /* D356: level 1 carries the top save-file row (item 0, not in rows[]) on
+     * top of the page's content rows. */
+    return s_level == 0 ? s_pageN : s_rowN + 1;
+}
+
+/* Put the crosshair on item k, unconditionally. */
+static void cursorToItemRaw(int k)
+{
+    /* D345(g): snap into the left gutter (x=44), not onto the row text
+     * (the old ROW_X+20 centred the sprite over the label/highlight box).
+     * 44 stays inside [ROW_HIT_X0..1] so the highlight hit-test still
+     * resolves row k, and clears the number column (NUM_X=55) / highlight
+     * boxes (from x=53/73). The PREVIOUS-tab hitbox (x>390 && y>223) is
+     * far away. Mouse users are unaffected: the pointer sits under the
+     * real mouse, never at this snap position. */
+    cursor_h_pos = 44.0f;
+    cursor_v_pos = (f32)(rowY(k) + 6);
+}
+
+/* Put the crosshair on item k (entering a page / going back). */
+static void cursorToItem(int k)
+{
+    /* D345(b): while the 1:1 pointer owns the crosshair (mouse recently
+     * used), it is already under the OS pointer -- snapping would yank it
+     * to the top-left item and it would stay there until the next mouse
+     * movement. Keyboard/D-pad users (stale mouse) keep the snap. */
+    if (inputMenuPointerLive()) return;
+    cursorToItemRaw(k);
+}
+
+/* ------------------------------------------------------------------------ */
+/* MENU_PC_OPTIONS: init / update / interface / constructor (front.c cases) */
+
+void frontOptionsMenuInit(void)
+{
+    /* As init_menu15_cheat: reset the tab state and make sure the dossier
+     * model is loaded (the background draws walletinst[0]). */
+    tab_start_selected = FALSE;
+    tab_next_selected = FALSE;
+    tab_prev_selected = FALSE;
+    tab_prev_highlight = FALSE;
+    tab_next_highlight = FALSE;
+    tab_start_highlight = FALSE;
+    load_walletbond();
+
+    /* frontSetupMenuBackground frames the folder at folderpositions[
+     * selected_folder_num]; file select leaves it at -1. Use folder 1, as a
+     * return from mode select would (file select's init does the same). */
+    if (selected_folder_num < FOLDER1 || selected_folder_num >= MAX_FOLDER_COUNT) {
+        selected_folder_num = FOLDER1;
+    }
+    folder_selection_screen_option_icon = 0;   /* crosshair, not Copy/Erase */
+
+    s_level = 0;
+    s_page = 0;
+    s_pageno = 0;   /* D406 */
+    s_subHeader = -1;
+    s_hl = -1;
+    s_dragRow = -1;
+    s_repeatDir = 0;
+    s_vrepeatDir = 0;
+    buildPages();
+    /* Isolated headless screenshot of a nested page. This diagnostic only
+     * changes menu navigation; it never edits profile or config values. */
+    const char *testPage = getenv("GE_FRONTOPTIONS_SECTION");
+    if (testPage) {
+        for (int i = 0; i < optionsRowCount(); i++) {
+            if (!optionsRowIsHeader(i) || strcmp(optionsRowLabel(i), testPage)) continue;
+            int root = i, depth = 1;
+            while (optionsRowHeaderParent(root) >= 0) {
+                root = optionsRowHeaderParent(root);
+                depth++;
+            }
+            for (int p = 0; p < s_pageN; p++) {
+                if (s_pageHdr[p] == root) {
+                    s_page = p;
+                    s_pageno = 0;
+                    s_level = depth;
+                    s_subHeader = depth > 1 ? i : -1;
+                    buildPages();
+                    sysLogPrintf(LOG_INFO, "frontoptions: diagnostic page %s (depth %d, %d rows)",
+                                 testPage, depth, s_rowN);
+                    break;
+                }
+            }
+            break;
+        }
+    }
+    cursorToItem(0);
+    sysLogPrintf(LOG_INFO, "frontoptions: opened");
+}
+
+void frontOptionsMenuUpdate(void)
+{
+}
+
+static void goBack(void)
+{
+    playSfx(DOOR_METAL_CLOSE2_SFX);
+    if (s_dragRow >= 0) optionsRowCommit(s_dragRow);
+    s_dragRow = -1;
+    optionsResetClear();   /* D356: navigating away (or closing) disarms a pending reset */
+    if (s_level >= 2) {
+        int child = s_subHeader;
+        int parent = optionsRowHeaderParent(child);
+        s_pageno = 0;   /* D406: every fresh page view starts at page 1 */
+        if (parent == s_pageHdr[s_page]) {
+            s_level = 1;
+            s_subHeader = -1;
+        } else {
+            s_level--;
+            s_subHeader = parent;
+        }
+        buildPages();
+        int selected = 0;
+        for (int k = 0; k < s_rowN; k++)
+            if (optionsRowChildHeader(s_rowIdx[k]) == child) selected = k + 1;
+        cursorToItem(selected);
+        s_hl = -1;
+        sysLogPrintf(LOG_INFO, "frontoptions: back to %s", optionsRowLabel(activeHeader()));
+        return;
+    }
+    if (s_level == 1) {
+        s_level = 0;
+        s_pageno = 0;   /* D406 */
+        cursorToItem(s_page);
+        sysLogPrintf(LOG_INFO, "frontoptions: back to section list");
+        return;
+    }
+    configSave();
+    sysLogPrintf(LOG_INFO, "frontoptions: closed");
+    frontChangeMenu(MENU_FILE_SELECT, FALSE);
+}
+
+void frontOptionsMenuInterface(void)
+{
+    viSetFovY(FOV_Y_F);
+    viSetAspect(ASPECT_RATIO_SD);
+    viSetZRange(100.0f, 10000.0f);
+    viSetUseZBuf(0);
+
+    buildPages();   /* an auto toggle may have hidden or shown % rows */
+    /* D383: modal key capture owns events on the host thread. Suppress
+     * navigation until its one-shot key has been consumed and released. */
+    if (optionsBindingCaptureTick()) return;
+
+    /* D345(f): NO raw stick integration on this screen (the D345(c) call to
+     * frontUpdateControlStickPosition() was removed): vertical input is the
+     * discrete row stepper below, horizontal is the left/right block -- F10
+     * model. Raw drift fought the pointer over cursor_h/v_pos. */
+
+    /* Highlight: as the cheat screen, recomputed while A is not held. */
+    if (joyGetButtons(PLAYER_1, A_BUTTON | Z_TRIG) == 0) {
+        tab_prev_highlight = FALSE;
+        s_hl = -1;
+        if (frontCheckCursorOnPreviousTab()) {
+            tab_prev_highlight = TRUE;
+        } else if (cursor_h_pos >= ROW_HIT_X0 && cursor_h_pos <= ROW_HIT_X1) {
+            for (int k = itemCount() - 1; k >= 0; k--) {
+                if (cursor_v_pos >= (f32)(rowY(k) - 3) &&
+                    cursor_v_pos <  (f32)(rowY(k) + ROW_DY - 3)) {
+                    s_hl = k;
+                    break;
+                }
+            }
+            /* D407(b): past the top/bottom edge of the visible rows, clamp
+             * the highlight to the edge row instead of dropping it (a
+             * mouse-only user keeps a row selected at the page edge; wheel
+             * / S then turns the page). */
+            if (s_hl < 0 && itemCount() > 0) {
+                if (cursor_v_pos < (f32)rowY(0))
+                    s_hl = 0;
+                else if (cursor_v_pos <= (f32)(rowY(itemCount() - 1) + ROW_DY))
+                    s_hl = itemCount() - 1;
+            }
+        }
+    }
+
+    if (joyGetButtonsPressedThisFrame(PLAYER_1, A_BUTTON | Z_TRIG | START_BUTTON)) {
+        if (tab_prev_highlight) {
+            goBack();
+        } else if (s_hl >= 0 && s_level == 0) {
+            playSfx(DOOR_METAL_CLOSE2_SFX);
+            s_page = s_hl;
+            s_level = 1;
+            s_pageno = 0;   /* D406 */
+            sysLogPrintf(LOG_INFO, "frontoptions: section %d", s_page + 1);
+            buildPages();
+            cursorToItem(0);
+            s_hl = -1;
+        } else if (s_hl == 0 && s_level >= 1) {
+            /* D356: the top save-file row -- A steps to the next file (the
+             * D352 chooser; folders only, "none" retired, plan §5.5). */
+            playSfx(DOOR_LOCK_SFX);
+            watchSettingsChooseFile(1);
+        } else if (s_hl >= 1 && s_hl <= s_rowN) {
+            /* s_hl is item-numbered (0 = the save-file row); content row k
+             * is item k+1, so the row index is s_hl - 1. */
+            int i = s_rowIdx[s_hl - 1];
+            if (getenv("GE_FRONTNAVLOG"))
+                sysLogPrintf(LOG_INFO, "frontnav: select %s/%s (item %d)",
+                             optionsRowLabel(activeHeader()), optionsRowLabel(i), s_hl);
+            playSfx(DOOR_LOCK_SFX);
+            int child = optionsRowChildHeader(i);
+            int bx0 = optionsRowIsSlider(i) ? rowBarX0(optionsRowLabel(i)) : BAR_X0;
+            if (child >= 0) {
+                optionsResetClear();
+                s_subHeader = child;
+                s_level++;
+                s_pageno = 0;   /* D406 */
+                buildPages();
+                sysLogPrintf(LOG_INFO, "frontoptions: opened %s (depth %d)",
+                             optionsRowLabel(child), s_level);
+                cursorToItem(0);
+                s_hl = -1;
+            } else if (optionsRowIsSlider(i) && bx0 <= BAR_X1 - 12 &&
+                       cursor_h_pos >= bx0 - 4 && cursor_h_pos <= BAR_X1 + 4) {
+                optionsRowSetFraction(i, ((double)cursor_h_pos - bx0) / (BAR_X1 - bx0));
+                s_dragRow = i;
+            } else if (optionsRowIsBind(i)) {
+                /* D395: pad A/X may navigate the keyboard/mouse binding
+                 * pages but cannot enter a modal that only a key can finish.
+                 * Enter or a mouse click still starts ordinary key capture. */
+                const Uint8 *ks = SDL_GetKeyboardState(NULL);
+                if (ks[SDL_SCANCODE_RETURN] || ks[SDL_SCANCODE_KP_ENTER] ||
+                    (SDL_GetMouseState(NULL, NULL) & SDL_BUTTON(SDL_BUTTON_LEFT)))
+                    optionsRowBeginBind(i);
+            } else if (optionsRowIsReset(i)) {
+                /* D356: reset rows are two-step arm -> confirm (edge
+                 * activation: joyGetButtonsPressedThisFrame fires once per
+                 * press). The value column shows "Confirm" while armed. */
+                optionsRowActivateReset(i);
+            } else {
+                optionsRowAdjust(i, +1);   /* toggle / cycle / step (wraps) */
+            }
+        }
+    } else if (joyGetButtonsPressedThisFrame(PLAYER_1, B_BUTTON)) {
+        goBack();
+    }
+
+    /* Drag a slider while A is held. */
+    if (s_dragRow >= 0) {
+        if (joyGetButtons(PLAYER_1, A_BUTTON | Z_TRIG)) {
+            int bx0 = rowBarX0(optionsRowLabel(s_dragRow));
+            optionsRowSetFraction(s_dragRow, ((double)cursor_h_pos - bx0) / (BAR_X1 - bx0));
+        } else {
+            optionsRowCommit(s_dragRow);
+            s_dragRow = -1;
+        }
+    }
+
+    /* Left/right (D-pad, C buttons; keyboard A/D) adjust the highlighted row,
+     * with hold-to-repeat. D356: on the save-file row it cycles the file;
+     * on a reset row a fresh press activates (arm/confirm) and the held
+     * repeat is suppressed (the activation contract, plan §5.4). */
+    if (s_level >= 1 && s_hl >= 0) {
+        int dir = 0;
+        /* D345(f): stick X joins the D-pad/C-buttons, so Left/Right arrows
+         * (and the pad's left stick) adjust values like F10's left/right. */
+        s8 vsx = joyGetStickX(PLAYER_1);
+        if (joyGetButtons(PLAYER_1, L_JPAD | L_CBUTTONS) || vsx < -5) dir = -1;
+        if (joyGetButtons(PLAYER_1, R_JPAD | R_CBUTTONS) || vsx > 5) dir = +1;
+        if (dir != 0) {
+            int fire = 0;
+            if (dir != s_repeatDir) {
+                fire = 1;
+                s_repeatTimer = 18;
+            } else if (--s_repeatTimer <= 0) {
+                fire = 1;
+                s_repeatTimer = 4;
+            }
+            if (fire) {
+                if (s_hl == 0) {
+                    watchSettingsChooseFile(dir);   /* save-file row */
+                } else {
+                    int i = s_rowIdx[s_hl - 1];
+                    if (optionsRowIsReset(i))
+                        optionsRowActivateReset(i);
+                    else if (optionsRowChildHeader(i) < 0)
+                        optionsRowAdjust(i, dir);
+                }
+            }
+        }
+        s_repeatDir = dir;
+    } else {
+        s_repeatDir = 0;
+    }
+
+    /* D356: reset arm state -- the screen's selected rows[] index (s_hl 0 is
+     * the save row, not a rows[] entry); moving on disarms, goBack clears. */
+    optionsResetMaintain(s_level >= 1 && s_hl > 0 ? s_rowIdx[s_hl - 1] : -1);
+
+    /* The dossier: tabs + a blank CLASSIFIED page, as the cheat screen. */
+    disable_all_switches(walletinst[0]);
+    set_item_visibility_in_objinstance(walletinst[0], SW_TABS, 1);
+    set_item_visibility_in_objinstance(walletinst[0], SW_BLANK, 1);
+    set_item_visibility_in_objinstance(walletinst[0], SW_CLASSIFIED, 1);
+
+    /* D345(e): F10-style discrete vertical navigation. W/S / Up-Down arrows
+     * (stick via D345(d)) or the pad's stick/D-pad step the highlight one
+     * row at a time -- clamped at the ends, hold-to-repeat with the same
+     * 18/4-frame cadence as left/right -- and snap the crosshair onto the
+     * new row (ungated: explicit keyboard navigation owns the cursor even
+     * right after mouse use). Replaces the raw stick drift of D345(c),
+     * which fought the pointer over cursor_v_pos. The mouse is untouched:
+     * any movement re-owns the cursor and the highlight hit-test above
+     * follows it next frame. Skipped while a slider drag holds A. */
+    if (s_dragRow < 0) {
+        int vdir = 0;
+        s8 vsy = joyGetStickY(PLAYER_1);
+        if (joyGetButtons(PLAYER_1, U_JPAD) || vsy > 5)      vdir = -1;  /* up   */
+        else if (joyGetButtons(PLAYER_1, D_JPAD) || vsy < -5) vdir = +1;  /* down */
+        if (vdir != 0) {
+            int fire = 0;
+            if (vdir != s_vrepeatDir) {
+                fire = 1;
+                s_vrepeatTimer = 18;
+            } else if (--s_vrepeatTimer <= 0) {
+                fire = 1;
+                s_vrepeatTimer = 4;
+            }
+            if (fire) {
+                int n = itemCount();
+                if (n > 0) {
+                    int q = (s_hl < 0 ? 0 : s_hl) + vdir;
+                    /* D406: stepping past the end of the visible page turns
+                     * the page (cursor lands on the first row of the next
+                     * page, or the last row of the previous one); with one
+                     * page the ends simply clamp, as before. */
+                    if (q >= n && s_pageno * ROWS_PER_PAGE + s_rowN < s_rowTotal) {
+                        s_pageno++;
+                        buildPages();
+                        q = 1;
+                    } else if (q < 0 && s_pageno > 0) {
+                        s_pageno--;
+                        buildPages();
+                        q = itemCount() - 1;
+                    } else {
+                        if (q < 0) q = 0;
+                        if (q >= n) q = n - 1;
+                    }
+                    if (q != s_hl) {
+                        if (getenv("GE_FRONTNAVLOG"))
+                            sysLogPrintf(LOG_INFO, "frontnav: %s -> item %d%s%s (page %d)",
+                                         s_level ? optionsRowLabel(activeHeader()) : "categories",
+                                         q, s_level && q > 0 ? " " : "",
+                                         s_level && q > 0 ? optionsRowLabel(s_rowIdx[q - 1]) : "",
+                                         s_level ? s_pageno + 1 : 0);
+                        s_hl = q;
+                        cursorToItemRaw(q);
+                    }
+                }
+            }
+        }
+        s_vrepeatDir = vdir;
+    } else {
+        s_vrepeatDir = 0;
+    }
+}
+
+Gfx *frontOptionsMenuDraw(Gfx *DL)
+{
+    char buf[48];
+
+    DL = viSetFillColor(DL, 0, 0, 0);
+    DL = viFillScreen(DL);
+#ifdef VERSION_EU
+    DL = viFillScreen(DL);
+    DL = viFillScreen(DL);
+    DL = viFillScreen(DL);
+#endif
+    DL = frontSetupMenuBackground(DL);
+    DL = microcode_constructor(DL);
+
+    if (s_level == 0) {
+        DL = ink(DL, ROW_X, TITLE_Y, "PC Options\n", INK);
+        for (int k = 0; k < s_pageN; k++) {
+            char name[32], num[8];
+            titleCase(optionsRowLabel(s_pageHdr[k]), name, sizeof(name));
+            strcat(name, "\n");
+            snprintf(num, sizeof(num), "%d.\n", k + 1);
+            if (k == s_hl) {
+                DL = microcode_constructor_related_to_menus(DL, SEC_X - 2, rowY(k) - 1,
+                        SEC_X + measureW(name) + 5, rowY(k) + 0xE, HILITE);
+            }
+            DL = ink(DL, NUM_X, rowY(k), num, INK);
+            DL = ink(DL, SEC_X, rowY(k), name, INK);
+        }
+    } else {
+        char title[32];
+        titleCase(optionsRowLabel(activeHeader()), title, sizeof(title));
+        int titleW = measureW(title);
+        strcat(title, "\n");
+        DL = ink(DL, ROW_X, TITLE_Y, title, INK);
+
+        /* D356: scope annotation -- a section that carries per-file rows has
+         * its title carry the active file ("GAMEPLAY (File 2)"), PD-style.
+         * watchSettingsActiveFolder() is the context-aware accessor (front:
+         * the resolved front target; -1 while no file is usable, which the
+         * annotation renders as an unavailable state, never a number the
+         * write path cannot use). */
+        if (optionsRowIsSaveScoped(activeHeader())) {
+            int f = watchSettingsActiveFolder();
+            char note[16];
+            if (f < 0) snprintf(note, sizeof(note), "(none)");
+            else       snprintf(note, sizeof(note), "(Profile %d)", f + 1);
+            DL = ink(DL, ROW_X + titleW + 8, TITLE_Y, note, INK_DIM);
+        }
+
+        /* D406b: page marker for sections that span pages -- "Page p/N"
+         * right of the title row, dim, so page 2 is unmistakable. */
+        if (s_rowTotal > ROWS_PER_PAGE) {
+            int pages = (s_rowTotal + ROWS_PER_PAGE - 1) / ROWS_PER_PAGE;
+            char pg[24];
+            snprintf(pg, sizeof(pg), "Page %d/%d", s_pageno + 1, pages);
+            DL = inkR(DL, VAL_R, TITLE_Y, pg, INK_DIM);
+        }
+
+        /* D356: the top profile row (item 0, not in the row table; the label
+         * reads "Profile" -- the end-user term for a per-player game file,
+         * see D357 plan section 4): the single file control of the front
+         * screen (F10 always targets the active file, so it has no file
+         * row). L/R (and A) cycle folders; (none) is the unavailable state
+         * until one is created. */
+        {
+            int y = rowY(0);
+            char sv[32];
+            if (s_hl == 0) {
+                DL = microcode_constructor_related_to_menus(DL, ROW_X - 2, y - 1,
+                        ROW_X + 140, y + 0xE, HILITE);
+            }
+            DL = ink(DL, ROW_X, y, "Profile\n", INK);
+            int f = watchSettingsActiveFolder();
+            if (f < 0) snprintf(sv, sizeof(sv), "(none)");
+            else       snprintf(sv, sizeof(sv), "%d\n", f + 1);
+            DL = inkR(DL, VAL_R, y, sv, INK);
+        }
+
+        for (int k = 0; k < s_rowN; k++) {
+            int i = s_rowIdx[k];
+            /* D406b: one-shot label-metrics log (layout diagnostics). */
+            static int widthsLogged = 0;
+            if (!widthsLogged && getenv("GE_FRONTOPTS_WIDTHS")) {
+                widthsLogged = 1;
+                for (int w2 = 0; w2 < s_rowN; w2++) {
+                    int j = s_rowIdx[w2];
+                    sysLogPrintf(LOG_INFO, "frontoptions: '%s' w=%d barx0=%d",
+                                 optionsRowLabel(j), measureW(optionsRowLabel(j)),
+                                 rowBarX0(optionsRowLabel(j)));
+                }
+            }
+            /* Content row k is item k+1 (item 0 is the save-file row), so
+             * it sits one line below the save row -- rowY() already shifts
+             * level-1 items down by one. */
+            int y = rowY(k + 1);
+            char label[48];
+            snprintf(label, sizeof(label), "%s\n", optionsRowLabel(i));
+            if (k + 1 == s_hl) {
+                DL = microcode_constructor_related_to_menus(DL, ROW_X - 2, y - 1,
+                        ROW_X + measureW(label) + 5, y + 0xE, HILITE);
+            }
+            DL = ink(DL, ROW_X, y, label, INK);
+
+            /* GAMEPLAY/HUD mix ini and profile options. AUDIO is wholly
+             * profile-scoped and already has (Profile N) in its title. */
+            if (optionsRowIsSaveScoped(i) &&
+                (strcmp(optionsRowLabel(activeHeader()), "GAMEPLAY") == 0 ||
+                 strcmp(optionsRowLabel(activeHeader()), "HUD") == 0)) {
+                DL = ink(DL, ROW_X + measureW(label) + 4, y, "(per profile)\n", INK_DIM);
+            }
+
+            if (optionsRowIsSlider(i)) {
+                int x0 = rowBarX0(optionsRowLabel(i));
+                if (BAR_X1 - x0 >= 12) {
+                    s32 fx = x0 + (s32)((BAR_X1 - x0) * optionsRowFraction(i) + 0.5);
+                    DL = microcode_constructor_related_to_menus(DL, x0, y + 5, BAR_X1, y + 8, 0x00000040);
+                    DL = microcode_constructor_related_to_menus(DL, x0, y + 5, fx, y + 8, 0xA00000C0);
+                }
+            } else if (optionsRowNeedsRestart(i)) {
+                DL = ink(DL, BAR_X0, y, "(restart)\n", INK_DIM);
+            }
+
+            optionsRowValueText(i, buf, sizeof(buf) - 1);
+            if (strcmp(optionsRowLabel(i), "Crosshair colour") == 0 && buf[0]) {
+                extern void portCrosshairPreview(s32 *, s32 *, s32 *);
+                s32 red, green, blue;
+                portCrosshairPreview(&red, &green, &blue);
+                s32 x = VAL_R - measureW(buf) - 17;
+                DL = microcode_constructor_related_to_menus(DL, x, y + 2,
+                         x + 10, y + 12,
+                         ((u32)red << 24) | ((u32)green << 16) |
+                         ((u32)blue << 8) | 0xff);
+            }
+            if (buf[0]) {
+                u32 col = (buf[0] == 'O' && buf[1] == 'N') ? INK_ON : INK;
+                /* D346: kOnOff is title-case; M7 (D387) tags the
+                 * experimental AllUnlocked ON value "ON - UNSAFE". */
+                strcat(buf, "\n");
+                DL = inkR(DL, VAL_R, y, buf, col);
+            }
+        }
+        if (strcmp(optionsRowLabel(activeHeader()), "MOVEMENT") == 0 ||
+            strcmp(optionsRowLabel(activeHeader()), "ACTIONS") == 0) {
+            DL = ink(DL, ROW_X, rowY(s_rowN + 2),
+                     optionsBindingCaptureActive()
+                         ? "Press key/mouse  B/ESC cancel  DEL clear\n"
+                         : "Keys/mouse only  Enter: bind  B: back\n", INK_DIM);
+        } else if (s_rowTotal > ROWS_PER_PAGE) {
+            /* D406b: bottom hint on every page of a multi-page section (11
+             * rows per page leaves the last line of the paper for it). */
+            int last = s_pageno * ROWS_PER_PAGE + s_rowN >= s_rowTotal;
+            int first = s_pageno == 0;
+            /* D406d: one row below the last content row (rowY(s_rowN + 1))
+             * -- pitch-aligned with the list; +2 sat ~26px clear of it and
+             * looked orphaned at the paper's bottom edge. */
+            DL = ink(DL, ROW_X, rowY(s_rowN + 1),
+                     first ? "Down: next page\n"
+                     : last ? "Up: previous page\n"
+                            : "Up: previous page   Down: next page\n",
+                     INK_DIM);
+        }
+    }
+
+    DL = frontAddPreviousTabText(DL);
+    DL = frontDrawCursor(DL);
+    return DL;
+}
+
+/* F10 / Select must not stack the overlay on this screen. */
+int frontOptionsBlocksOverlay(void)
+{
+    return current_menu == MENU_PC_OPTIONS;
+}
+
+/* ------------------------------------------------------------------------ */
+/* File select: the "Options" entry, drawn from the D343 hook in           */
+/* constructor_menu05_fileselect (game thread, after the interface tick).  */
+/* ------------------------------------------------------------------------ */
+
+Gfx *optionsFileSelectLabel(Gfx *gdl)
+{
+    s32 h = 0, w = 0;
+    s32 x, y;
+    int hot;
+
+    /* The F10 overlay pads the controller away from front.c, so file select's
+     * idle timer never resets and it dropped to the legal screen after 30 s.
+     * This hook only runs on MENU_FILE_SELECT, the one screen where
+     * g_MenuTimer is an idle timer (elsewhere it is the intro / cast-roll
+     * clock). Same write front.c makes when a button is pressed. */
+    if (optionsOverlayIsOpen()) {
+        g_MenuTimer = 0;
+    }
+
+    /* D400 (user sign-off, "most straightforward design"): text-only label,
+     * the D398 dot icon is gone. Exact Copy/Erase pattern from front.c:
+     * measure the single-line label (no trailing newline -- the kLabelNL
+     * trick measured a taller box and sat the text ~7px higher than the
+     * bar's other words, the "different size/look" complaint), centre it
+     * on the bar line, draw with the same font. Hot colour is the game's
+     * own packed gold 0xEBD879FF, the very constant front.c passes to
+     * textRender for its gold folder text -- no per-channel unpacking, so
+     * no purple (the D398 dot bug came from unpacking that word for
+     * gDPSetEnvColor in the wrong byte order). */
+    /* NB: textMeasure's signature is (textheight, textwidth) -- height FIRST
+     * (an earlier cut passed these swapped and drew the label 35px above the
+     * bar, hit band transposed). Height is measured WITH a trailing newline:
+     * Copy/Erase's localised strings end in a newline, so textMeasure gives
+     * them a full 14px line height and y = 285 - 7 = 278 (PCDUMP tops
+     * 279); measuring the bare label gives h=0 -> y=285, sitting 7px LOWER
+     * than the bar's other words. Measuring kLabelNL matches their tops
+     * exactly. (This was the D398 "kLabelNL trick"; the D400 rewrite
+     * dropped it and that is what broke the vertical alignment.) */
+    textMeasure(&h, &w, (char *)kLabelNL, ptrFontZurichBoldChars, ptrFontZurichBold, 0);
+    /* Follow the Erase label's measured right edge (set by the constructor
+     * just before this hook), so a wider localised "Erase" (JP glyphs)
+     * pushes the label right instead of overlapping it. */
+    x = (s32)folder_option_ERASE_bound.right + LABEL_GAP;
+    if (x < LABEL_X) {
+        x = LABEL_X;
+    }
+    /* Same centring front.c uses for Copy/Erase (front.c:2779/2791). */
+    y = LABEL_CY - (h / 2);
+
+    /* D406: test hook -- enter the screen without a mouse click so headless
+     * runs (GE_INPUTSCRIPT D-pad stepping + GE_FRONTNAVLOG / diagnostics)
+     * can exercise it. Diagnostic-only: never active without the env. */
+    if (getenv("GE_FRONTOPTIONS_AUTO") && menu_update == MENU_INVALID &&
+        folder_selected_for_deletion < 0) {
+        static int autoEntered = 0;
+        if (!autoEntered) {
+            autoEntered = 1;
+            playSfx(DOOR_LOCK_SFX);
+            frontChangeMenu(MENU_PC_OPTIONS, FALSE);
+        }
+    }
+
+    hot = !optionsOverlayIsOpen()
+       && menu_update == MENU_INVALID
+       && folder_selected_for_deletion < 0
+       && cursor_h_pos >= (f32)(x - HIT_PAD) && cursor_h_pos <= (f32)(x + w + HIT_PAD)
+       && cursor_v_pos >= (f32)(y - HIT_PAD) && cursor_v_pos <= (f32)(y + h + HIT_PAD);
+
+    if (hot && joyGetButtonsPressedThisFrame(PLAYER_1, A_BUTTON | Z_TRIG | START_BUTTON)) {
+        playSfx(DOOR_LOCK_SFX);   /* Copy/Erase's click */
+        frontChangeMenu(MENU_PC_OPTIONS, FALSE);
+    }
+
+    /* Same font, size and centre line as Copy/Erase; white idle, the
+     * game's gold while the cursor is over it. */
+    return textRender(gdl, &x, &y, (char *)kLabel, ptrFontZurichBoldChars,
+                      ptrFontZurichBold, hot ? 0xEBD879FF : 0xFFFFFFFF,
+                      viGetX(), viGetY(), 0, 0);
+}

port/src/gimgfixup.c

@@ -11,6 +11,9 @@
 #include <PR/ultratypes.h>
 #include <PR/gbi.h>
 #include "gimgfixup.h"
+extern char *getenv(const char *name); /* D324: no CRT proto via GE stdlib.h */
+#include "envflag.h"
+extern void osSyncPrintf(const char *fmt, ...);
 
 #define GIMG_REGION_SIZE 0x13F8u
 
@@ -99,9 +102,17 @@ void gimgFixupGlobalimagetable(u8 *base)
     }
 }
 
+/* D252 (2026-09-26): which compiled G_SETTIMG slots are IMAGESEG texture
+ * references. Learned on the first sync, while they still hold the 0xABCD
+ * marker; every later sync re-copies exactly these slots. */
+#define GIMG_MAX_CMDS 256
+static u8 s_imgslot[N_DLS][GIMG_MAX_CMDS];
+static int s_imgslot_learned = 0;
+
 void gimgSyncCompiledGlobalDLs(u8 *base)
 {
     int i;
+    int nslots = 0, nchanged = 0; /* D252 TEMP verify counters */
     u8 *end = base + GIMG_REGION_SIZE;
 
     for (i = 0; i < N_DLS; i++)
@@ -110,21 +121,44 @@ void gimgSyncCompiledGlobalDLs(u8 *base)
         Gfx *dst = s_dl_syms[i];
         int j = 0;
 
-        while (p + 8 <= end && p[0] != (u8)G_ENDDL)
+        while (p + 8 <= end && p[0] != (u8)G_ENDDL && j < GIMG_MAX_CMDS)
         {
             /* D68/C2: texLoadFromDisplayList() has already replaced every
              * IMAGESEG w1 word in the ROM copy with a real texture pointer,
-             * so the 0xABCDxxxx marker is gone from `p`. Identify the slots
-             * that need syncing from the COMPILED array instead: a G_SETTIMG
-             * command whose w1 is still an unresolved IMAGESEG marker
-             * (0xABCDxxxx). Copy the ROM copy's resolved word into it. */
-            if ((u8)(dst[j].words.w0 >> 24) == (u8)G_SETTIMG &&
+             * so the 0xABCDxxxx marker is gone from `p`. On the first call,
+             * identify the slots from the COMPILED array instead (a
+             * G_SETTIMG whose w1 is still an unresolved 0xABCDxxxx marker)
+             * and remember them.
+             *
+             * D252: texReset() runs on EVERY stage load and re-resolves the
+             * ROM copy into the new stage's texture pool. The original sync
+             * only ever copied into slots still holding the marker, i.e.
+             * only on the first stage (the title screen). Every later stage
+             * kept the title's pointers into its freed texture pool; once
+             * the new stage's allocations overwrote that memory, explosion
+             * smoke/fire/debris sampled garbage (rainbow particles). Re-copy
+             * the remembered slots on every call, as the N64 does by running
+             * the freshly patched ROM copy directly. */
+            if (!s_imgslot_learned &&
+                (u8)(dst[j].words.w0 >> 24) == (u8)G_SETTIMG &&
                 (dst[j].words.w1 >> 16) == 0xABCDu)
             {
+                s_imgslot[i][j] = 1;
+            }
+            if (s_imgslot[i][j])
+            {
+                nslots++;
+                if ((u32)dst[j].words.w1 != *(u32 *)(p + 4))
+                    nchanged++;
                 dst[j].words.w1 = *(u32 *)(p + 4);
             }
             p += 8;
             j++;
         }
     }
+    s_imgslot_learned = 1;
+    /* D252 TEMP: before the fix, every stage after the first left
+     * `nchanged` explosion texture pointers stale. */
+    if (GE_ENVFLAG("GE_D252POOL"))
+        osSyncPrintf("D252SYNC: %d texture slots re-synced, %d changed\n", nslots, nchanged);
 }

port/src/legacycrc.c

@@ -0,0 +1,106 @@
+/*
+ * port/src/legacycrc.c — D297: one-time migration of pre-D284 save-slot CRCs.
+ *
+ * WHY A DELIBERATELY-WRONG PRNG LIVES IN THIS TREE (read before "fixing" it):
+ *
+ *   v0.2.x shipped with a port-side bug in randomGetNextFrom's dsll32/dsrl32
+ *   semantics (modelled as 32-bit shifts; real MIPS64 shifts by n+32 over the
+ *   full register). D284 (commit 0de99b4d) fixed it. But fileGenerateCRC
+ *   (src/game/crc.c) runs that PRNG off a LOCAL constant seed, so every slot
+ *   checksum stored on disk is a fingerprint of the PRNG implementation that
+ *   wrote it: saves written by v0.2.x validate under the OLD stream and fail
+ *   the NEW one, and fileValidateSaves wipes failing slots (D295/M-148, D297).
+ *
+ *   This file carries the pre-D284 transform so the eeprom shim can recognize
+ *   a legacy save (old-CRC match) and re-stamp its two checksum words with the
+ *   current-PRNG values before the game validates. No game files are touched;
+ *   the new CRCs come from the game's own fileGenerateCRC — only the OLD PRNG
+ *   is duplicated here, and it must stay bit-exact-WRONG. Do not "fix" the
+ *   shifts below; do not share helpers with port/src/random.c.
+ *
+ *   When this can be deleted: once no pre-D284 saves are expected in the wild
+ *   (the v0.3.0 release is the last build that meets them un-migrated). Keep
+ *   it at least until then; the cost is ~60 lines of dead-but-harmless code.
+ *
+ * Verification: the legacy stream below was re-derived from
+ * `git show 0de99b4d^:port/src/random.c` and matches tools_pc/d295_crc.py,
+ * which is bit-exact against compiled C for both PRNGs (see D295 M-148).
+ */
+
+#include <ultra64.h>
+#include "file.h" /* save_data */
+
+extern void fileGenerateCRC(u8 *addressA, u8 *addressB, save_data *retval);
+
+/* Pre-D284 randomGetNextFrom: verbatim body from 0de99b4d^:port/src/random.c
+ * with the OLD helper semantics inlined ((x << n) & 0xFFFFFFFF etc.). */
+static u32 geLegacyRandomGetNextFrom(u64 *seed)
+{
+    u64 a3 = *seed;
+    u64 a1, a2;
+
+    a2 = (a3 << 0x1f) & 0xFFFFFFFFULL; /* dsll32, pre-D284 semantics */
+    a1 = a3 << 0x1f;                   /* dsll */
+    a2 = a2 >> 0x1f;                   /* dsrl */
+    a1 = (a1 >> 0) & 0xFFFFFFFFULL;    /* dsrl32, pre-D284 semantics */
+    a3 = (a3 << 0xc) & 0xFFFFFFFFULL;  /* dsll32, pre-D284 semantics */
+    a2 = a2 | a1;
+    a3 = (a3 >> 0) & 0xFFFFFFFFULL;    /* dsrl32, pre-D284 semantics */
+    a2 = a2 ^ a3;
+    a3 = a2 >> 0x14;                   /* dsrl */
+    a3 = a3 & 0xfff;
+    a3 = a3 ^ a2;
+
+    *seed = a3;
+    return (u32)a3;
+}
+
+/* Same loop as fileGenerateCRC (src/game/crc.c) stepping the legacy PRNG.
+ * Keep in lockstep with crc.c if that loop ever changes. */
+static void geLegacyGenerateCRC(u8 *addressA, u8 *addressB, save_data *retval)
+{
+    u8 *byte;
+    s32 shift      = 0;
+    s64 polynormal = 0x8F809F473108B3C1; /* same local constant seed as crc.c */
+    s32 checksum1  = 0;
+    s32 checksum2  = 0;
+
+    for (byte = addressA; byte < addressB; byte++, shift += 7) {
+        polynormal += *byte << (shift & 0xF);
+        checksum1 ^= geLegacyRandomGetNextFrom(&polynormal);
+    }
+    for (byte = addressB - 1; byte >= addressA; byte--, shift += 3) {
+        polynormal += *byte << (shift & 0xF);
+        checksum2 ^= geLegacyRandomGetNextFrom(&polynormal);
+    }
+    retval->chksum1 = checksum1;
+    retval->chksum2 = checksum2;
+}
+
+/* Migrate up to five consecutive 96-byte save slots in place. A slot is
+ * migrated iff it FAILS the current-PRNG check but PASSES the legacy one;
+ * re-stamped via the game's own fileGenerateCRC. Corrupt slots (fail both)
+ * are left alone for the game's own wipe path. Returns the count migrated. */
+int geLegacyCrcMaybeMigrateSlots(u8 *slots5)
+{
+    save_data *slots = (save_data *)slots5;
+    int migrated = 0;
+
+    for (int i = 0; i < 5; i++) {
+        save_data calc = {0}; /* only chksum1/chksum2 are read back */
+        u8 *a = &slots[i].completion_bitflags; /* slot bytes [8..96) */
+        u8 *b = (u8 *)&slots[i + 1];           /* end boundary, never dereferenced */
+
+        fileGenerateCRC(a, b, &calc);
+        if (calc.chksum1 == slots[i].chksum1 && calc.chksum2 == slots[i].chksum2)
+            continue; /* current-PRNG save (or already migrated) — idempotent no-op */
+
+        geLegacyGenerateCRC(a, b, &calc);
+        if (calc.chksum1 != slots[i].chksum1 || calc.chksum2 != slots[i].chksum2)
+            continue; /* corrupt: game's fileValidateSaves handles it */
+
+        fileGenerateCRC(a, b, &slots[i]); /* re-stamp chksum1/chksum2 in place */
+        migrated++;
+    }
+    return migrated;
+}