v0.6.0: release notes, ROADMAP and findings for D953-D955 (maintainer Deck-confirmed)

c_lodscalez is built from the rendered FOV (D222), so Video.FovScale moved every model LOD switch,
the prop fog fade and the fog-range visibility test closer (x0.58 at 150); half-fogged props such
as the Surface windows went fully invisible and flickered while turning. All three now use the
game's own FOV (portLodScaleOwnFov); identity at the default FOV.

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -7,9 +7,8 @@ body:
       value: |
         Thanks for filing a report. First, please check:
 
-        - The port is **Phase 2 of 4** — rendering is incomplete and many
-          cosmetic defects are already tracked in
-          [`docs/dev/GRAPHICS-BACKLOG.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/GRAPHICS-BACKLOG.md).
+        - Known open issues (rendering, audio, platform) are tracked in
+          [`docs/ROADMAP.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/ROADMAP.md).
           Search open issues and that file before filing.
         - Only the **Windows / MSYS2 MINGW64** build is tested. Linux and
           macOS are best-effort — build breaks there are expected.

.github/ISSUE_TEMPLATE/config.yml

@@ -4,7 +4,7 @@ contact_links:
     url: https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/building.md
     about: Read this first for build/extraction problems — most are covered here.
   - name: Known rendering defects
-    url: https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/GRAPHICS-BACKLOG.md
+    url: https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/ROADMAP.md
     about: Cosmetic / rendering issues already known and tracked. Check before filing.
   - name: Security vulnerability
     url: https://github.com/jkdansereau/goldeneye-pc-port/security/advisories/new

.github/SECURITY.md

@@ -1,12 +1,66 @@
 # Security Policy
 
 This project is a non-commercial, fan-made research port. It has no server
-component and ships no binaries. The realistic security surface is:
+component and no telemetry, and no networking unless you turn on the opt-in
+update check (`Game.CheckUpdates`, off by default), which makes one HTTPS
+request to GitHub's releases API per launch (GitHub sees that request and
+your IP, as with any web request). On Windows it loads the system
+`winhttp.dll` from System32 only then; on Linux/Steam Deck it runs the
+system `curl`. It never downloads or installs anything. Each release ships
+prebuilt Windows and Linux binaries, but never a ROM or any game asset — you
+supply those yourself from a copy you legally own. The realistic security
+surface is:
 
 - the PC port executable parsing your own ROM and asset files at load time
   (a malformed ROM/asset could in principle crash it or worse), and
 - the build/extraction scripts and CI workflow.
 
+A full walkthrough of what a release actually installs on your machine, and
+what a from-source build pulls in, is in
+[`docs/security.md`](../docs/security.md).
+
+### Why the binaries are unsigned
+
+The Windows `.exe` and the Linux build are **not code-signed** — this is a
+free, single-developer, non-commercial hobby project with no code-signing
+budget, not a sign of anything wrong with the binary. Two things you may
+run into as a result:
+
+- **Windows SmartScreen** may show "Windows protected your PC" on first
+  run. Click "More info" → "Run anyway."
+- Some antivirus engines flag `ge007-convert.exe` (the one-time ROM-asset
+  converter bundled in the release) specifically, because it's packaged
+  with PyInstaller's `--onefile` mode — a well-known trigger for heuristic
+  AV engines industry-wide, unrelated to what this project's code actually
+  does. The game launches this converter itself on the first run, when the
+  derived asset folders are missing, so an AV prompt can appear at that
+  moment rather than when you unpack the release. If you want to verify what
+  it does, its full source is `prepare-assets.py`, shipped right next to it in
+  the same bundle folder. The build pins the PyInstaller version and the CI
+  actions it uses (by commit SHA), so what ships is reproducible from this
+  repository.
+
+### Verifying a release build (build provenance)
+
+From **v0.5.0** on, the tag-only CI job attaches an in-toto SLSA
+build-provenance attestation to each release artifact (the zip/tarball and
+its `.sha256` sidecars). The attestation is signed by GitHub's OIDC key for
+*this repository's* workflow running the tagged commit. It does not replace a
+code signature — but it proves that the exact file you downloaded was produced
+by this repo's CI from the release tag, and nothing else. Verify any
+downloaded artifact with:
+
+```sh
+gh attestation verify goldeneye-pc-port-0.6.0-win64.zip \
+  --repo jkdansereau/goldeneye-pc-port
+```
+
+(use the name of the file you downloaded, e.g.
+`goldeneye-pc-port-0.6.0-linux-x86_64.tar.gz` on Linux). A passing check confirms both
+the file's digest and its provenance; a tampered or foreign file fails.
+Releases before v0.5.0 have no attestations — for those, the per-file
+`.sha256` sidecars and a from-source build are the available checks.
+
 ## Reporting a vulnerability
 
 Please **do not** open a public issue for a security problem.
@@ -38,4 +92,6 @@ errors, and anything requiring a ROM or assets we do not distribute.
 
 ## Supported versions
 
-Only the tip of the default branch is supported. There are no releases yet.
+Only the tip of the default branch and the
+[latest release](https://github.com/jkdansereau/goldeneye-pc-port/releases/latest)
+are supported.

.github/labels.yml

@@ -10,7 +10,7 @@
 
 - name: rendering
   color: 5319e7
-  description: Graphics / fast3d / RSP output defect (see docs/dev/GRAPHICS-BACKLOG.md)
+  description: Graphics / fast3d / RSP output defect (see docs/ROADMAP.md)
 
 - name: audio
   color: 1d76db

.github/release-notes.md

@@ -1,333 +1,120 @@
-# GoldenEye 007 PC Port — v0.4.0
+# GoldenEye 007 PC Port — v<version>
 
 <p align="center">
-  <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)">
+  <img src="https://github.com/jkdansereau/goldeneye-pc-port/raw/v<version>/docs/img/shots/feature-splitscreen.jpg" width="340" alt="2-player split-screen multiplayer in the port">
+  <img src="https://github.com/jkdansereau/goldeneye-pc-port/raw/v<version>/docs/img/shots/feature-options.jpg" width="340" alt="The PC options menu: custom crosshair colour sliders">
 </p>
 
-Platforms: **Windows x86-64** and **Linux x86-64 (including Steam Deck)**.
-Region: **NTSC-U (US) only** — see [Things to know](#things-to-know).
+> [!NOTE]
+> **Updating?** Your progress and settings carry over. Unpack the new version into a new folder and copy your ROM, `ge007.eep` and `ge007.ini` into its `data/` folder. Leave the old `pcmodels-*` and `pccg-*` folders behind; the new version makes its own.
 
-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.
+> [!NOTE]
+> The downloads aren't code-signed. On Windows, if SmartScreen appears, click **More info**, then **Run anyway**. On macOS, see [Getting started](#getting-started).
 
----
+## Highlights
 
-## New features
-
-### Native widescreen *(on by default)*
-
-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.
-
----
+- **Frame rates above 60.** Pick 90, 120, 144, 165 or 240, or **Auto** to match your display (up to 240). The game still runs at its original speed; the extra frames are blended between its ticks, for the camera, the level, the sky, and the guards, doors and objects moving in it. A rework of f1zz1ec0ke's #137.
+- **macOS on Apple Silicon (experimental).** A new download for M1 and later Macs, based on danturn's #95. Tested on one M3 Mac so far; reports are welcome.
+- **Original controls are now original (#145, #149).** With *Control style* set to Original, your pad behaves as an N64 controller, and *Invert look* works in every original style.
+- **Fixes:** geometry vanishing up close (#150), the first launch opening on the wrong monitor (#151), the end-credits crash on Linux and macOS (#152) and a crash when a guard spawns with a hat (#153, #156).
+- **Also:** an optional mission timer (#144), the file-select crest fixed (#146), and a fix for a Windows blue screen on exit.
 
 ## Downloads
 
 | File | Platform |
 |---|---|
-| `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) |
+| `goldeneye-pc-port-<version>-win64.zip` | Windows 10/11, 64-bit |
+| `goldeneye-pc-port-<version>-linux-x86_64.tar.gz` | Linux x86-64 (glibc 2.31+), including Steam Deck |
+| `goldeneye-pc-port-<version>-macos-arm64.tar.gz` | macOS 14+ on Apple Silicon (experimental) |
 
-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.
+Each download is ready to run: it carries its runtime libraries, a README, the license texts and the one-time asset tool. **No ROM and no game assets are included; you need your own US GoldenEye 007 ROM.**
 
-## Running it
+## Getting started
 
-You supply your own **GoldenEye 007 N64 ROM** (`.z64`, big-endian) that you
-legally own (NTSC-U only, as noted above). No Python, no toolchain, nothing
-to install.
+1. Unpack the download.
+2. Make a `data/` folder next to the executable and put your ROM in it as `ge007.ntsc-final.z64`.
+3. Start the game. The first start takes a few extra seconds while it prepares the game files from your ROM. **F10** (controller: **Select**) opens the options menu.
 
-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.)
+**Steam Deck:** do the steps on the Deck, then add the executable 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.
+**macOS:** the app isn't notarized, so run this once in Terminal before the first launch, then start `./ge007.aarch64` from the folder.
 
-**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.
+```
+xattr -dr com.apple.quarantine goldeneye-pc-port-<version>-macos-arm64
+```
 
-Full steps are in the bundled `README.md`.
+Or download it in Terminal, which skips that step:
+
+```
+curl -L https://github.com/jkdansereau/goldeneye-pc-port/releases/download/v<version>/goldeneye-pc-port-<version>-macos-arm64.tar.gz | tar xz
+```
+
+Without Terminal: after macOS blocks the first launch, open System Settings → Privacy & Security and click **Open Anyway** next to the `ge007.aarch64` message.
+
+The [user guide](https://github.com/jkdansereau/goldeneye-pc-port/blob/v0.6.0/docs/user-guide.md) covers controls, settings, emulator saves and troubleshooting.
+
+## What's new
+
+### Added
+
+- **Frame rate cap:** Auto, 90, 120, 144, 165 and 240 join 30 and 60 (F10 → *Video*). Auto is the default on fresh installs; an existing `ge007.ini` keeps its value. Above 60 the extra frames are blended between game ticks (no effect on a 60 Hz display): the camera, the level and the sky, and each guard, door and object along its own motion. This adds one tick of latency; a fast camera turn or a big change on screen shows a full frame instead. The *Original N64* display mode keeps 60.
+- **macOS Apple Silicon download** (experimental), plus source builds with Homebrew's GNU `gcc`.
+- **Original control style as an N64 controller:** every press sends the real N64 button in levels, menus, the watch and the tank. Default layout: South = A, West = B, right trigger = Z, left trigger / RB = R, LB = L, right stick = C-buttons. Each button can be moved per player in `ge007.ini` (`Input.N64Pad.A = a`, ...), and `Input.N64StickFeel` picks the N64's linear stick range.
+- **Mission timer** (#144): an optional always-visible timer, off by default.
+- **`ge007.log`:** every run is logged next to the ini; the previous run is kept as `ge007.prev.log`.
+
+### Fixed
+
+- Geometry vanishing when you stand against a wall (#150).
+- With a wider *Field of view*, objects in fog (such as the windows on Surface) no longer flicker or vanish while you turn, and models keep their detail out to the normal distance.
+- The first launch opening on the wrong monitor (#151).
+- A crash during the end credits on Linux and macOS (#152).
+- macOS: a black window that never started the game when it was launched while the display was asleep.
+- A crash when a guard spawns wearing a hat (#153, #156).
+- The file-select crest drawing on a dark square (#146).
+- *Invert look* now works in every original control style and stays in sync with the watch's *Look up/down* (#145).
+- A Windows blue screen (0x119) when the game exits, seen on an NVIDIA GPU.
+- The Cradle catwalk shadow flicker, and stale pixels beside the widescreen picture on front-end screens.
+- Sound and text pointer checks that rejected valid pointers (#108, with italoarruda).
+- The Linux/macOS update check failing on a large response.
+- F10 slider labels being cut off at HUD scale 150.
+
+### Changed
+
+- Windows: per-monitor DPI awareness, so fullscreen on a scaled 4K display is native resolution.
+- F10 dropdowns stay inside the settings box.
+- The crosshair look (colour, size, style) is no longer reset by the *Display mode* presets.
+- The old front-end *Velocity* pointer mode is removed.
+
+## Known issues
+
+| Issue | Workaround |
+|---|---|
+| On the Steam Deck at 90 fps, firefights in the centre of Bunker 1 and 2 can drop a few fps, and Jungle can feel slightly less smooth | Set the frame cap to 60 for those levels |
+| Cradle's turret explosions may draw wrongly | None yet |
+| On Windows, the picture can look hazy for a moment after alt-tabbing back | It settles on its own |
+| PAL and JP ROMs aren't supported yet | Use the US (NTSC-U) ROM |
+| Saves from v0.4.0 and earlier can hold fake unlocks from *All unlocked* | Keep a backup of `data/ge007.eep` from before you used it |
+
+The full list is the [known-issues table](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/ROADMAP.md#known-issues).
+
+## Tested on
+
+The release downloads themselves, from a fresh folder with only the ROM: all 21 solo levels on Windows (at 120 fps), the Steam Deck (Desktop and Game Mode, at 90), macOS on Apple Silicon, and a 2011 Linux laptop with Intel HD 3000 graphics (at 60).
+
+## Thanks
+
+f1zz1ec0ke (#137, the frame-interpolation design this release reworks), danturn (#95, macOS), Julio C. Rocha (#88, the first macOS groundwork), italoarruda (#108), and everyone who reported the issues above.
 
 ## Verify the download
 
 ```
-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
+sha256sum -c goldeneye-pc-port-<version>-win64.zip.sha256
+sha256sum -c goldeneye-pc-port-<version>-linux-x86_64.tar.gz.sha256
+shasum -a 256 -c goldeneye-pc-port-<version>-macos-arm64.tar.gz.sha256   # macOS
+gh attestation verify <file> --repo jkdansereau/goldeneye-pc-port         # build provenance
 ```
 
-## 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).
-Non-commercial fan preservation/research project; not affiliated with any
-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.
+Built on the [GoldenEye 007 decompilation](https://github.com/n64decomp/007) and modelled on the [Perfect Dark PC port](https://github.com/fgsfdsfgs/perfect_dark). A non-commercial fan project, not affiliated with any rights holder. Developed with AI coding agents directed by one maintainer; see [About the project](https://github.com/jkdansereau/goldeneye-pc-port/blob/v0.6.0/docs/about.md#how-it-was-made).

.github/social-preview.html

@@ -55,11 +55,9 @@
   .tab span { writing-mode:vertical-rl; text-orientation:mixed;
     font-family:'Arimo',sans-serif; font-weight:700; font-size:15px;
     letter-spacing:4px; color:#3b3b33; transform:rotate(180deg); }
-  .reticle { position:absolute; right:34px; top:246px; width:44px; height:44px; z-index:5; }
-  .reticle::before, .reticle::after { content:""; position:absolute; background:#c62828; }
-  .reticle::before { left:50%; top:-6px; width:3px; height:56px; margin-left:-1.5px; }
-  .reticle::after { top:50%; left:-6px; height:3px; width:56px; margin-top:-1.5px; }
-  .reticle i { position:absolute; inset:4px; border:3px solid #c62828; border-radius:50%; }
+  /* the project mark: in-game default crosshair proportions (ring outer r 18,
+     bars reach ~1.43x r with an open centre ~0.24x r); see tools_pc/make_icon.py */
+  .reticle { position:absolute; right:30px; top:242px; width:52px; height:52px; z-index:5; }
 
   /* the parchment card */
   .card { position:absolute; left:40px; top:40px; right:96px; bottom:40px;
@@ -124,12 +122,12 @@
     <div class="rep">REPORT:</div>
 
     <div class="rows">
-      <div class="statusline">Status: <span class="status">RELEASED v0.3.0 &mdash; WINDOWS &middot; LINUX &middot; STEAM DECK</span></div>
+      <div class="statusline">Status: <span class="status">RELEASED v0.6.0 &mdash; WINDOWS &middot; LINUX &middot; STEAM DECK</span></div>
       <div class="stats">
-        <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>~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>
+        <span class="k">Statistics:</span><span>All 20 solo missions &mdash; 60 to 144 fps &middot; macOS (experimental)</span>
+        <span></span><span>~210 game-code units, compiled unmodified</span>
+        <span></span><span>~34k lines C/C++ &nbsp;&middot;&nbsp; ~10k Python  (port layer + tools)</span>
+        <span></span><span>465 findings logged &nbsp;&middot;&nbsp; AI coding agents + a handful of contributors</span>
       </div>
     </div>
 
@@ -142,6 +140,6 @@
     <div class="tab"><span>NEXT</span></div>
     <div class="tab"><span>PREVIOUS</span></div>
   </div>
-  <div class="reticle"><i></i></div>
+  <svg class="reticle" viewBox="-26 -26 52 52" aria-hidden="true"><g fill="none" stroke="#c62828" stroke-width="3"><circle r="16.5"/><path d="M0-26V-4.5M0 4.5V26M-26 0H-4.5M4.5 0H26"/></g></svg>
 </body>
 </html>

.github/workflows/ci.yml

@@ -75,7 +75,7 @@ jobs:
       #     self-hosted per the 2026-09-12 standing preference.
       windows_selfhosted: ${{ steps.runner.outputs.selfhosted }}
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           fetch-depth: 0
@@ -120,7 +120,7 @@ jobs:
     if: needs.changes.outputs.code == 'true'
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -171,40 +171,71 @@ jobs:
   # here is a "does it compile + link" signal only, not a runtime claim.
   # Not a required check yet; flip it to required once it is reliably green.
   #
-  # Toolchain: ubuntu-24.04 + gcc-14. The port is developed on MinGW GCC 16;
-  # pinning a recent GCC here keeps the first bring-up focused on real
-  # portability gaps rather than a decade of accumulated old-GCC pedantry.
-  # (A "does it build on the GCC a typical distro ships" pass can come later.)
+  # Toolchain: Steam Runtime 3 "sniper" SDK container (Debian 11 base,
+  # glibc 2.31) + its gcc-14. Building against the old glibc is what sets the
+  # tarball's floor: the ubuntu-24.04 build needed glibc 2.38 (C23
+  # __isoc23_* symbols), so it refused to start on Ubuntu 22.04 / Debian 12.
+  # The image is pinned by version AND digest.
+  # SDL2 is built from source (2.30.0, the version the 24.04 build bundled
+  # and every Linux/Deck test used): the SDK's own libSDL2 is sdl2-compat,
+  # which needs SDL3 at runtime. pip is bootstrapped from a hash-pinned
+  # get-pip.py: Debian 11's security archive no longer serves python3-pip.
   linux-build:
     runs-on: ubuntu-24.04
+    container:
+      image: registry.gitlab.steamos.cloud/steamrt/sniper/sdk:3.0.20260805.254768@sha256:1c33c507bc75d012e77df5727f93b0d5b8c3f7c8d4142ba5f7a16882cc92e014
+    # A container job's default `run` shell is sh, not bash (the packaging
+    # step's ${GITHUB_SHA::7} is a bashism).
+    defaults:
+      run:
+        shell: bash
     env:
       CC: gcc-14
       CXX: g++-14
       # CMakeLists.txt opt-in enables CMAKE_{C,CXX}_COMPILER_LAUNCHER=ccache
       # when ccache is on PATH (b4de1c68, speed-ups plan Step 5). Game
       # sources are frozen (1:1 with the decomp), so after the first run only
-      # touched port/ files miss cache -- near-total hit rate.
-      CCACHE_DIR: ${{ github.workspace }}/.ccache
+      # touched port/ files miss cache -- near-total hit rate. CCACHE_DIR is
+      # set in a step: in a container job ${{ github.workspace }} is the
+      # host path, not the container's.
       CCACHE_MAXSIZE: 500M
+      SDL2_VERSION: 2.30.0
+      SDL2_SHA256: 36e2e41557e0fa4a1519315c0f5958a87ccb27e25c51776beb6f1239526447b0
+      GET_PIP_SHA256: 95c0ae79ccf9ac1e47e4187f49081d6ae1f45997afd4549e14f37337cbcfd766
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install dependencies
         run: |
-          sudo apt-get update
-          sudo apt-get install -y build-essential gcc-14 g++-14 cmake python3 \
-            python3-pip libsdl2-dev zlib1g-dev libgl1-mesa-dev ccache patchelf
+          echo "CCACHE_DIR=$GITHUB_WORKSPACE/.ccache" >> "$GITHUB_ENV"
+          apt-get update
+          apt-get install -y patchelf
+          curl -fsSL -o /tmp/get-pip.py https://bootstrap.pypa.io/pip/3.9/get-pip.py
+          echo "$GET_PIP_SHA256  /tmp/get-pip.py" | sha256sum -c
+          python3 /tmp/get-pip.py --quiet
+
+      - name: Build SDL2 ${{ env.SDL2_VERSION }} from source
+        run: |
+          curl -fsSL -o /tmp/sdl2.tar.gz \
+            "https://github.com/libsdl-org/SDL/releases/download/release-$SDL2_VERSION/SDL2-$SDL2_VERSION.tar.gz"
+          echo "$SDL2_SHA256  /tmp/sdl2.tar.gz" | sha256sum -c
+          tar xzf /tmp/sdl2.tar.gz -C /tmp
+          cmake -S "/tmp/SDL2-$SDL2_VERSION" -B /tmp/sdl-build -DCMAKE_BUILD_TYPE=Release \
+            -DCMAKE_INSTALL_PREFIX=/usr/local -DSDL_STATIC=OFF -DSDL_TEST=OFF
+          cmake --build /tmp/sdl-build -j"$(nproc)"
+          cmake --install /tmp/sdl-build
+          ldconfig
 
       - name: Restore ccache
-        uses: actions/cache@v4
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
-          path: ${{ env.CCACHE_DIR }}
-          key: ccache-linux-${{ hashFiles('CMakeLists.txt') }}-${{ github.sha }}
+          path: .ccache
+          key: ccache-linux-sniper-${{ hashFiles('CMakeLists.txt') }}-${{ github.sha }}
           restore-keys: |
-            ccache-linux-${{ hashFiles('CMakeLists.txt') }}-
-            ccache-linux-
+            ccache-linux-sniper-${{ hashFiles('CMakeLists.txt') }}-
+            ccache-linux-sniper-
 
       - name: Regenerate ROM-asset symbol file (US)
         run: python3 scripts/gen_romassets.py u
@@ -216,8 +247,8 @@ jobs:
       # tools_pc/dist/prepare-assets/ where bundle-linux.sh picks it up.
       - name: Freeze asset converter (PyInstaller)
         run: |
-          python3 -c "import PyInstaller" 2>/dev/null \
-            || python3 -m pip install --quiet --break-system-packages pyinstaller
+          python3 -c "import PyInstaller, sys; sys.exit(PyInstaller.__version__ != '6.22.3')" 2>/dev/null \
+            || python3 -m pip install --quiet pyinstaller==6.22.3
           python3 -m PyInstaller --onefile --noconfirm --clean \
             --name ge007-convert \
             --distpath tools_pc/dist/prepare-assets \
@@ -254,7 +285,7 @@ jobs:
           tools_pc/bundle-linux.sh "$V"
 
       - name: Upload bundle
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: goldeneye-pc-port-linux-x86_64
           path: |
@@ -263,6 +294,93 @@ jobs:
           if-no-files-found: error
           retention-days: 14
 
+  # Experimental macOS (Apple Silicon) build. Compiles + links with Homebrew's
+  # real GNU GCC (Apple Clang cannot compile the decomp's Plan 9 struct
+  # extensions) and packages the bundle with scripts/package-macos.sh: the
+  # non-system dylibs (sdl2-compat + SDL3, libstdc++, libgcc_s) are copied
+  # next to the exe with @executable_path install names, re-signed ad-hoc.
+  # The bundle is not notarized; the README inside it gives the one-line
+  # `xattr -dr com.apple.quarantine .` unblock. Like linux-build this is a
+  # "compiles + links + packages" signal, not a runtime claim. Not a required
+  # check. Mirrors the maintainer's local build-mac configuration (Unix
+  # Makefiles, RelWithDebInfo, newest Homebrew gcc-N).
+  macos-build:
+    runs-on: macos-14
+    env:
+      CCACHE_MAXSIZE: 500M
+      HOMEBREW_NO_AUTO_UPDATE: "1"
+      HOMEBREW_NO_INSTALL_CLEANUP: "1"
+      HOMEBREW_NO_ANALYTICS: "1"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install dependencies
+        run: |
+          echo "CCACHE_DIR=$GITHUB_WORKSPACE/.ccache" >> "$GITHUB_ENV"
+          brew install gcc cmake sdl2 sdl3 ccache
+          ls "$(brew --prefix)"/bin/gcc-[0-9]* "$(brew --prefix)"/bin/g++-[0-9]*
+
+      - name: Restore ccache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: .ccache
+          key: ccache-macos-arm64-${{ hashFiles('CMakeLists.txt') }}-${{ github.sha }}
+          restore-keys: |
+            ccache-macos-arm64-${{ hashFiles('CMakeLists.txt') }}-
+            ccache-macos-arm64-
+
+      - name: Regenerate ROM-asset symbol file (US)
+        run: python3 scripts/gen_romassets.py u
+
+      # Same frozen first-run converter as linux-build. The runner's python3
+      # is Homebrew's (PEP 668, no system pip installs), so use a venv.
+      - name: Freeze asset converter (PyInstaller)
+        run: |
+          python3 -m venv "$RUNNER_TEMP/venv"
+          "$RUNNER_TEMP/venv/bin/pip" install --quiet pyinstaller==6.22.3
+          "$RUNNER_TEMP/venv/bin/python" -m PyInstaller --onefile --noconfirm --clean             --name ge007-convert             --distpath tools_pc/dist/prepare-assets             --workpath build-pyinst --specpath build-pyinst             tools_pc/dist/prepare-assets/prepare-assets.py
+          ls -la tools_pc/dist/prepare-assets/ge007-convert
+
+      - name: Configure (ntsc-final)
+        run: |
+          GCC="$(ls "$(brew --prefix)"/bin/gcc-[0-9]* | sort -t- -k2 -n | tail -1)"
+          GXX="$(ls "$(brew --prefix)"/bin/g++-[0-9]* | sort -t- -k2 -n | tail -1)"
+          echo "using $GCC / $GXX"
+          cmake -S . -B build-mac -DROMID=ntsc-final -DCMAKE_BUILD_TYPE=RelWithDebInfo             -DCMAKE_C_COMPILER="$GCC" -DCMAKE_CXX_COMPILER="$GXX"
+
+      - name: Build (ntsc-final)
+        run: cmake --build build-mac -j"$(sysctl -n hw.ncpu)"
+
+      - name: ccache stats
+        run: ccache -s
+
+      - name: Show binary
+        run: |
+          ls -la build-mac/ge007* || true
+          file build-mac/ge007* || true
+          otool -L build-mac/ge007.aarch64
+
+      - name: Package macOS bundle
+        run: |
+          if [ "${GITHUB_REF_TYPE}" = "tag" ]; then
+            V="${GITHUB_REF_NAME}"
+          else
+            V="0.0.0-ci.${GITHUB_SHA::7}"
+          fi
+          bash scripts/package-macos.sh build-mac dist "$V"
+
+      - name: Upload bundle
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: goldeneye-pc-port-macos-arm64
+          path: |
+            dist/*.tar.gz
+            dist/*.tar.gz.sha256
+          if-no-files-found: error
+          retention-days: 14
+
   # Real Windows (MSYS2 MINGW64) build — the only platform the port is
   # developed and tested on. This compiles and LINKS the full executable.
   #
@@ -288,7 +406,7 @@ jobs:
       CCACHE_DIR: ${{ github.workspace }}/.ccache
       CCACHE_MAXSIZE: 500M
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -300,7 +418,7 @@ jobs:
       # wrapper every job needs. Packages themselves are hand-maintained on
       # the box; the dependency check below (not this step) verifies they're
       # present.
-      - uses: msys2/setup-msys2@v2
+      - uses: msys2/setup-msys2@ec48f7c5447b3140e2b088413ae3a55687bccb6e # v2.33.0
         with:
           msystem: MINGW64
           release: ${{ needs.changes.outputs.windows_selfhosted != 'true' }}
@@ -316,7 +434,7 @@ jobs:
         run: tools_pc/check-selfhosted-deps.sh
 
       - name: Restore ccache
-        uses: actions/cache@v4
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: ${{ env.CCACHE_DIR }}
           key: ccache-windows-${{ hashFiles('CMakeLists.txt') }}-${{ github.sha }}
@@ -335,9 +453,9 @@ jobs:
         run: |
           # MSYS2's mingw python ships without pip and has ensurepip
           # disabled — install pip from pacman, then PyInstaller.
-          python -c "import PyInstaller" 2>/dev/null || {
-            pacman -S --noconfirm mingw-w64-x86_64-python-pip
-            python -m pip install --quiet --break-system-packages pyinstaller
+          python -c "import PyInstaller, sys; sys.exit(PyInstaller.__version__ != '6.22.3')" 2>/dev/null || {
+            pacman -S --noconfirm --needed mingw-w64-x86_64-python-pip
+            python -m pip install --quiet --break-system-packages pyinstaller==6.22.3
           }
           python -m PyInstaller --onefile --noconfirm --clean \
             --name ge007-convert \
@@ -349,6 +467,12 @@ jobs:
       - name: Build (ntsc-final)
         run: ./build-pc.sh ntsc-final
 
+      # D441 ratchet: fail if the per-file count of 64-bit pointer/int ABI
+      # warnings rises relative to tools_pc/abi_baseline.json. Re-baseline
+      # locally with `python tools_pc/abi_ratchet.py build-pc --update`.
+      - name: ABI warning ratchet (D441)
+        run: python tools_pc/abi_ratchet.py build-pc
+
       - name: ccache stats
         run: ccache -s
 
@@ -366,7 +490,7 @@ jobs:
           tools_pc/bundle-win.sh "$V"
 
       - name: Upload bundle
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: goldeneye-pc-port-win64
           path: |
@@ -380,30 +504,60 @@ jobs:
       # -level_09 soak, a golden-frame diff) would run on a self-hosted runner
       # instead. Not planned.
 
-  # Tags only. Attach the packaged Windows + Linux bundles to a DRAFT
+  # Tags only. Attach the packaged Windows + Linux + macOS bundles to a DRAFT
   # pre-release so a human can do the ROM smoke-test on each platform before
-  # publishing. This job — and only this job — gets contents: write.
+  # publishing. This job — and only this job — gets contents: write, and it
+  # is also the only job that attests build provenance (id-token: write +
+  # attestations: write; attest-build-provenance needs both).
   release:
     if: github.ref_type == 'tag'
-    needs: [ changes, validate, windows-build, linux-build ]
+    needs: [ changes, validate, windows-build, linux-build, macos-build ]
     runs-on: ubuntu-22.04
     permissions:
       contents: write
+      id-token: write
+      attestations: write
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
-      - uses: actions/download-artifact@v7
+      # The pushed tag must match the version baked into the exe (the update
+      # check compares against it); bump GE007_VERSION in CMakeLists.txt first.
+      - name: Check tag matches GE007_VERSION
+        run: |
+          ver=$(sed -n 's/^set(GE007_VERSION "\([^"]*\)").*/\1/p' CMakeLists.txt)
+          if [ -z "$ver" ] || [ "${GITHUB_REF_NAME}" != "v${ver}" ]; then
+            echo "tag ${GITHUB_REF_NAME} != v${ver} (CMakeLists.txt GE007_VERSION)"; exit 1
+          fi
+
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: goldeneye-pc-port-win64
           path: dist
 
-      - uses: actions/download-artifact@v7
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: goldeneye-pc-port-linux-x86_64
           path: dist
 
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: goldeneye-pc-port-macos-arm64
+          path: dist
+
+      # SLSA build provenance for the release artifacts (in-toto, signed by
+      # GitHub's OIDC key for this repo's workflow at the tagged commit).
+      # Anyone can check a downloaded file:
+      #   gh attestation verify <file> --repo jkdansereau/goldeneye-pc-port
+      - uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be # v2.4.0
+        with:
+          subject-path: |
+            dist/*.zip
+            dist/*.zip.sha256
+            dist/*.tar.gz
+            dist/*.tar.gz.sha256
+
       - name: Create or update draft pre-release
         env:
           GH_TOKEN: ${{ github.token }}
@@ -412,7 +566,7 @@ jobs:
           ASSETS=(dist/*.zip dist/*.zip.sha256 dist/*.tar.gz dist/*.tar.gz.sha256)
           NOTES="$(mktemp)"
           # Asset names are built from the tag with the leading v stripped
-          # (bundle-{linux,win}.sh), so substitute the same form -- a raw
+          # (bundle-{linux,win}.sh, package-macos.sh), so substitute the same form -- a raw
           # TAG would make the notes reference goldeneye-pc-port-v*.* assets
           # that don't exist.
           NOTES_VERSION="${TAG#v}"

.github/workflows/selfhosted.yml

@@ -1,7 +1,7 @@
 # Self-hosted runtime (ROM-gated)
 #
 # Runs the build + the 21-level headless sweep (tools_pc/verify.sh) on the
-# self-hosted runner "corpyvt6agent01", the one machine that has a legal ROM.
+# self-hosted runner, the one machine that has a legal ROM.
 # This is the job class ci.yml explicitly does NOT do: CI is build-only, no
 # ROM, so runtime checks live here. Setup + rollout plan (gitignored, local):
 #   docs/dev/notes/SELFHOSTED-RUNNER-PLAN.md
@@ -9,16 +9,19 @@
 # Persistence model — everything lives under the runner's own paths, managed
 # by the pipeline; no hand-maintained directories:
 #   - ccache  -> actions/cache (stored by the runner under _work/_temp)
-#   - ROM     -> actions/cache, key ge-rom-data-ntsc-v1. Bootstrap: copy the
-#                three files into {runner_home}/_rom-seed/ on the box; a run
-#                with an empty cache copies them in and attempts to save the
-#                cache entry. The seed dir is kept (NOT deleted) rather than
-#                treated as one-time -- actions/cache/save has been silently
-#                failing to persist on this box (warning, not a hard step
-#                failure; root cause open, see SELFHOSTED-RUNNER-PLAN.md), so
-#                the seed is the durable fallback every run re-copies from
-#                until that's fixed. Integrity is re-verified every run
-#                against the committed ge007.u.sha1 (repo-tracked US ROM hash).
+#   - ROM     -> copied every run from a seed dir on the runner:
+#                {runner_home}/_rom-seed/, or the repo variable
+#                GE_ROM_SEED_DIR. Bootstrap: put ge007.ntsc-final.z64,
+#                pcmodels-ntsc-final/ and pccg-ntsc-final/ there once.
+#                Integrity is re-verified every run against the committed
+#                ge007.u.sha1 (repo-tracked US ROM hash).
+#                The ROM is deliberately NOT stored in actions/cache (it
+#                used to be, key ge-rom-data-ntsc-v1). Cache entries live on
+#                GitHub's side, and pull_request workflows, including ci.yml
+#                runs from fork PRs, can restore caches created on the base
+#                branch, so a PR could read the ROM out of the cache. (The
+#                old save never actually persisted on this box, so no entry
+#                was ever created; checked 2026-09-30.)
 #   - MSYS2   -> machine-level install at C:\msys64 (verify.sh hardcodes the
 #                prefix), installed and its packages maintained BY HAND on
 #                the box. msys2/setup-msys2 still runs every job (it's what
@@ -37,8 +40,8 @@
 #     a runner that can see the ROM.
 #
 # Leak rules (docs/dev/notes/AGENT-VM-FORGEJO-PLAN.md checklist):
-#   - The ROM + sidecars live in the runner-managed cache only; nothing in
-#     this workflow uploads from data/.
+#   - The ROM + sidecars live only in the runner's local seed dir (never in
+#     actions/cache); nothing in this workflow uploads from data/.
 #   - Artifacts here are console logs + a JSON verdict only. Rendered frames
 #     (ppm/) are ROM-derived content and are NOT uploaded.
 
@@ -67,7 +70,7 @@ concurrency:
   cancel-in-progress: false
 
 env:
-  ROM_CACHE_KEY: ge-rom-data-ntsc-v1
+  GE_ROM_SEED_DIR: ${{ vars.GE_ROM_SEED_DIR }}
 
 jobs:
   build-and-sweep:
@@ -79,7 +82,7 @@ jobs:
       CCACHE_DIR: ${{ github.workspace }}/.ccache
       CCACHE_MAXSIZE: 500M
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -90,7 +93,7 @@ jobs:
       # no pacman -S, no network round-trip). This step still has to run
       # every time — it's what registers the `msys2 {0}` shell wrapper
       # above — but does no install/update work.
-      - uses: msys2/setup-msys2@v2
+      - uses: msys2/setup-msys2@ec48f7c5447b3140e2b088413ae3a55687bccb6e # v2.33.0
         with:
           msystem: MINGW64
           release: false
@@ -101,71 +104,26 @@ jobs:
       - name: Check self-hosted dependencies
         run: tools_pc/check-selfhosted-deps.sh
 
-      # --- ROM + sidecars: runner-managed cache, one-time seed --------------
-      - name: Restore ROM + sidecars (runner cache)
-        uses: actions/cache/restore@v4
-        with:
-          path: |
-            data/ge007.ntsc-final.z64
-            data/pcmodels-ntsc-final
-            data/pccg-ntsc-final
-          key: ${{ env.ROM_CACHE_KEY }}
-
-      - name: Check ROM store presence
-        id: romcheck
-        run: |
-          present=true
-          for f in ge007.ntsc-final.z64 pcmodels-ntsc-final pccg-ntsc-final; do
-            if [ ! -f "data/$f" ]; then echo "missing from cache: $f"; present=false; fi
-          done
-          echo "present=$present" >> "$GITHUB_OUTPUT"
-
+      # --- ROM + sidecars: runner-local seed dir (never actions/cache) ------
       # {runner_home} = two levels up from RUNNER_WORKSPACE ({home}/_work/{repo}).
-      # NOT deleted after the cache save below (see that step's comment) --
-      # kept as a durable fallback source until the cache save is proven to
-      # actually round-trip on this box.
-      - name: Seed ROM cache (from durable seed dir)
-        if: steps.romcheck.outputs.present == 'false'
+      # The seed dir is the only copy the workflow uses; it is never deleted.
+      - name: Stage ROM + sidecars (runner seed dir)
         run: |
-          seed="$(dirname "$(dirname "$RUNNER_WORKSPACE")")/_rom-seed"
-          [ -d "$seed" ] || {
-            echo "ROM cache is empty and no seed found at $seed." >&2
-            echo "One-time bootstrap: copy ge007.ntsc-final.z64, pcmodels-ntsc-final," >&2
-            echo "and pccg-ntsc-final into that directory on the runner, then re-run." >&2
-            exit 2
-          }
+          seed="${GE_ROM_SEED_DIR:-$(dirname "$(dirname "$RUNNER_WORKSPACE")")/_rom-seed}"
+          for f in ge007.ntsc-final.z64 pcmodels-ntsc-final pccg-ntsc-final; do
+            [ -e "$seed/$f" ] || {
+              echo "missing $seed/$f" >&2
+              echo "One-time bootstrap: copy ge007.ntsc-final.z64, pcmodels-ntsc-final/" >&2
+              echo "and pccg-ntsc-final/ into $seed (or set the repo variable GE_ROM_SEED_DIR)." >&2
+              exit 2
+            }
+          done
           mkdir -p data
           # -r: pcmodels-*/pccg-* are directories, not single files (found by
           # testing — a plain cp failed with "omitting directory").
           cp -r "$seed/ge007.ntsc-final.z64" "$seed/pcmodels-ntsc-final" \
                 "$seed/pccg-ntsc-final" data/
-          echo "seeded ROM store from $seed"
-
-      # Explicit save (restore alone never saves): persist the seeded store
-      # immediately, before the build/sweep can fail out from under it.
-      # KNOWN ISSUE (2026-09-12): this reliably logs a WARNING annotation
-      # ("Failed to save: ... tar.exe failed with exit code 2") on this box
-      # and never actually persists anything to the cache -- but
-      # actions/cache/save treats a save failure as non-fatal by design, so
-      # the step still reports success and the job carries on. Root cause not
-      # yet found (see docs/dev/notes/SELFHOSTED-RUNNER-PLAN.md). Consequence:
-      # do NOT delete the seed dir after this step (previously done, and it
-      # meant a *silent* cache-save failure combined with the delete wiped
-      # the only copy of the ROM every run -- exactly what broke rollout
-      # step 5's repeated dispatches). The seed dir now stays in place
-      # indefinitely as a durable fallback; "Check ROM store presence" /
-      # "Seed ROM cache" above already re-copy from it whenever the cache
-      # comes back empty, so this is safe to leave as a no-op once the cache
-      # save is fixed for real.
-      - name: Save ROM cache
-        if: steps.romcheck.outputs.present == 'false'
-        uses: actions/cache/save@v4
-        with:
-          path: |
-            data/ge007.ntsc-final.z64
-            data/pcmodels-ntsc-final
-            data/pccg-ntsc-final
-          key: ${{ env.ROM_CACHE_KEY }}
+          echo "staged ROM store from $seed"
 
       - name: Verify ROM integrity (committed US sha1)
         run: |
@@ -179,7 +137,7 @@ jobs:
       # Same opt-in ccache CMakeLists.txt wires up (speed-ups plan Step 5);
       # persisted via actions/cache like ci.yml's windows-build.
       - name: Restore ccache
-        uses: actions/cache/restore@v4
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: ${{ env.CCACHE_DIR }}
           key: ccache-selfhosted-${{ hashFiles('CMakeLists.txt') }}-${{ github.sha }}
@@ -197,8 +155,16 @@ jobs:
       # symbolication -> pixcount -> framediff vs tools_pc/golden/. Serialized
       # + watchdog + one retry by design (D117: not frame-deterministic).
       - name: Level sweep (all 21, or dispatch subset)
+        env:
+          INPUT_LEVELS: ${{ inputs.levels }}
         run: |
-          [ -n "${{ inputs.levels }}" ] && export SWEEP_LEVELS='${{ inputs.levels }}'
+          if [ -n "$INPUT_LEVELS" ]; then
+            if ! printf '%s' "$INPUT_LEVELS" | grep -Eq '^[A-Za-z0-9]+:[0-9]+( [A-Za-z0-9]+:[0-9]+)*$'; then
+              echo "levels input must be space-separated Name:NN entries, e.g. 'Dam:33 Facility:34'" >&2
+              exit 1
+            fi
+            export SWEEP_LEVELS="$INPUT_LEVELS"
+          fi
           tools_pc/verify.sh sweep --json > sweep.log 2>&1
           rc=$?
           cat sweep.log
@@ -223,7 +189,7 @@ jobs:
       # Console logs + verdict only — no frames, no ROM bytes (leak rules).
       - name: Upload sweep report
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: selfhosted-sweep-${{ github.run_number }}
           path: |

.gitignore

@@ -196,7 +196,20 @@ build-pc-cmd.bat
 # v0.4.0 modern-options wave: per-landing sweep capture dirs (capture.sh output)
 tools_pc/sweep-captures/capture-*/
 
+# Sweep capture output dirs and PPM dumps: regenerable framebuffer captures
+# (capture.sh OUTDIR), useful on disk, never in the tracked tree.
+tools_pc/sweep-captures/cap-*/
+tools_pc/sweep-captures/**/*.ppm
+
 # Stray full CPython install that landed in repo root (2026-09-28);
 # referenced by no project tooling. Never commit.
 /Python/
 docs/media/*.mp4
+
+# mod-loader tool build artifacts
+/tools_pc/modpatch/modpatch.exe
+
+# demo harness data (tools_pc/demobatch.sh): personal recordings + run output
+demos/
+demobatch/
+levelbench/

AGENTS.md

@@ -5,9 +5,37 @@
 - `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). **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).
+- **Open work / known issues:** `docs/ROADMAP.md` — the single tracker; add new items there, never start a new backlog/roadmap file.
+- **Current status:** the README "Status" section (`docs/dev/LEVEL-STATUS.md` is a historical per-level sweep record). 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.
 
+## Public site pages (`docs/`) — presentation layer, not a source of truth
+
+The repo's homepage and sub-pages are published by GitHub Pages; the local
+preview is `node scratch/build_preview.mjs site` → `scratch/_site/` (served
+with `node scratch/serve_preview.mjs 8777`). The site is a **presentation
+layer over the reference docs, kept in a separate area, and allowed to go
+stale** — never let it poison a work item:
+
+- **Pure site pages** — `docs/index.md`, `documentation.md`,
+  `the-software-rsp.md`, `the-asset-pipeline.md`, `framerate-and-pacing.md`,
+  `input-and-aim.md`, `saves.md`, `security.md`, `fidelity.md` —
+  summarise the ROADMAP / README / finding log / release notes. **Do not
+  consult them as work information, cross-check against them, or treat a
+  mismatch with `docs/ROADMAP.md` or the finding log as a bug** (that is
+  the expected, independent-staleness case). Update them only when the task
+  says so, and source every fact from the ROADMAP / README / finding log —
+  never the other way round. The footer "last updated" date in
+  `docs/_layouts/default.html` is the same class of site-only detail.
+- **Shared files** — `docs/internals.md`, `porting-notes.md`,
+  `building.md`, `dev-process.md`, `dev/agentic-development.md` are
+  authoritative working docs that the site publishes verbatim; edit them
+  normally as part of dev work and the site picks up the change for free.
+
+Keep the split intact: no working notes migrate into pure site pages, and
+never edit a shared doc merely to make the site read better — if the site is
+stale, fix the site page (or the fact upstream, as its own task).
+
 ## Non-negotiables
 
 1. **N64 build untouched.** `Makefile`, `tools/`, `rsp/`, `ld/` belong to the N64 build. Never modify them for the PC port.
@@ -16,6 +44,60 @@
 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.
 
+## Tree hygiene & release gate
+
+Standing rules for anything that lands in the tracked tree or in a push. These
+exist because the repo is public, MIT-licensed, forked, and its history is
+mostly agent-authored.
+
+1. **No local machine paths.** Tracked files carry no local absolute paths and
+   no usernames. Use the placeholder convention: `<repo>` = this working
+   directory, `<repos>` = the local source-repos root, `<games>` / `<videos>` =
+   local media roots, `<python>` = the local CPython install, `<temp>` = a
+   writable native temp dir (legend at the top of
+   `docs/dev/HANDOFF-ARCHIVE.md`). Tools must not default to a machine-specific
+   path — take the path as an argument and error if it is missing.
+2. **No contributor emails in prose.** Credit people by name plus the PR/issue
+   that carries the change ("co-authored with X (#123)"), never an inline
+   `<email>` trailer inside findings text or docs. Commit-trailer emails must
+   be noreply forms, never a contributor's real address.
+3. **Every vendored third-party component is declared in `NOTICE`** with its
+   license and holder — the "Third-party code vendored into the port layer" and
+   "Vendored build tooling" lists. GPL sources must ship their license text
+   in-tree (`tools/gzipsrc/COPYING`). MIT covers only our original work; never
+   relicense inherited code and never re-license the repo (forks depend on the
+   MIT `LICENSE` staying put).
+4. **Screenshots are game content.** A framebuffer capture is a derivative work
+   of Nintendo/MGM art regardless of which engine drew it. Keep repo imagery
+   documentary and small (bug shots, previews — downscaled), and never commit
+   bulk ROM-derived captures: capture output dirs are gitignored
+   (`tools_pc/sweep-captures/cap-*/`, `tools_pc/sweep-captures/**/*.ppm`); the
+   only bulk imagery in the tree is `tools_pc/golden/**/*.png`
+   (63 frames × 3 platforms, 189 total, nested per level at
+   `tools_pc/golden/<level>/{win,linux,deck}/`; the `deck` set added
+   2026-10-05 with maintainer approval), which exists because `verify.sh`
+   consumes it. Downloads ship no game content at all.
+5. **Batch, don't spam.** Accumulate approved doc/tree fixes across a session
+   into ONE commit; no per-item branches.
+6. **Release gate.** Before pushing a release: the PII scrub and legal/copyright
+   review reports (gitignored, `docs/dev/notes/`) must be run and clean, and the
+   README Legal section must name every rights holder the game's trademarks
+   implicate. Rewriting pushed history (squash) needs explicit maintainer
+   consent, and any such report states the remote + branch it applies to.
+7. **Squashes and history rebuilds must not erase contributor PRs.** Release
+   lines may squash *our own* work, but every contributor PR whose content
+   shipped gets a zero-diff record merge at its timeline position (merge
+   commit with the PR head as second parent, tree unchanged) so the PR shows
+   as merged and the contributor's commits stay reachable in public history
+   with their authorship. If the PR's base is a stale internal branch, merge
+   it there via `gh pr merge` so the badge is true; GitHub refuses a base
+   change to a branch that already contains the head. Superseded/reworked
+   PRs are never merged — comment + let the author close. Before force-
+   pushing a rewritten release branch: back up the pushed tip to Forgejo
+   (`backup/<branch>-pre-rebuild-<date>`), pass a byte-identical tree-diff
+   gate against the old tip, re-run CI, and note the rebuild in any open
+   issue that tells people to build the branch.
+
 ## Critical files
 
 | File | Role |
@@ -23,7 +105,7 @@
 | `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); 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/src/` | Shims: `libultra.c` (OS API; also shims the scheduler's hardware leaf calls and runs the software RSP inline — the game's real `src/sched.c` is compiled), `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`. |
@@ -44,8 +126,9 @@ Needs CMake + SDL2 + zlib + OpenGL, and must run from the MSYS2 MINGW64 shell
 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
+   (agent harnesses; the `C:/msys64` tree here was built for a relocated MSYS2
+   root — `<msys>` in the placeholder legend — so its path 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
@@ -67,20 +150,45 @@ Needs CMake + SDL2 + zlib + OpenGL, and must run from the MSYS2 MINGW64 shell
    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).
+   **FIXED 2026-09-30 (`fix/build-pc-tmp-reexec`):** the heredoc `.ps1`
+   was byte-identical to a hand-extracted copy — not line endings. Three
+   real bugs: (a) the TMP probe's inline `cmd //c "... \"path\" ..."` never
+   ran (msys re-escapes embedded quotes as `\"`, which cmd rejects), so
+   *every* build took the re-exec, and it only tested that TMP existed;
+   (b) the `.ps1`'s toolchain dirs were derived from `command -v cmake`,
+   which in Git Bash/agent shells is a pip cmake (no MSYS2 toolchain) —
+   the hand-run worked because it passed explicit `C:\msys64\...` paths;
+   (c) `/tmp` + `cygpath` disagree when Git Bash and MSYS2 `usr/bin` are
+   both on PATH, so the `.ps1` could be written to one `/tmp` and
+   powershell pointed at the other (it then exits 0 having done nothing).
+   Now: the MSYS2 `mingw64/bin` is located and validated (override:
+   `GE_MSYS2_ROOT`) and prepended to PATH; the probe is a `.cmd` file that
+   tests TMP *writability*; all native-facing files live in the build dir
+   with paths from bash's own `pwd -W`. Verified from an agent Git Bash
+   shell: fresh + incremental builds, both on the direct path and with a
+   forced unwritable TMP (`TMP=C:\Windows\`) through the re-exec.
+   **FIXED 2026-09-30 (`fix/build-pc-reexec-noop`): the re-exec exited rc=2
+   with the diag log ending `cmake ran LASTEXITCODE=[]`.** From a shell with
+   MSYS2 `usr/bin` first on PATH, powershell inherits a stripped ~13-var env
+   with `PATHEXT=.CPL` and no ComSpec/TMP/TEMP, so `& cmake.exe` silently
+   launches nothing. The `.ps1` now restores PATHEXT and ComSpec. In that
+   shell the re-exec itself is legitimately needed (no TMP), so the probe
+   is correct. Verified: MSYS2-PATH shell, forced `TMP=C:\Windows\`, and a
+   no-change incremental run all exit 0 with a fresh exe.
+   **FIXED 2026-10-04 (`fix/build-arch-tag`, D515):** a FRESH build dir
+   configured through the re-exec cached `CMAKE_HOST_SYSTEM_PROCESSOR ""` /
+   `CMAKE_SYSTEM_PROCESSOR ""` (the stripped env also drops
+   `PROCESSOR_ARCHITECTURE`, which CMake reads for the host processor — same
+   class as PATHEXT/ComSpec), so `cmake/TargetArch.cmake` produced an empty
+   arch tag: `Target arch:  (64bit=FALSE)`, binary named `ge007..exe`
+   (a correct 64-bit build; only the name was wrong — found during T7, D513).
+   The `.ps1` now restores `PROCESSOR_ARCHITECTURE` from the machine
+   environment (fallback `AMD64`; `SystemRoot`/`windir` likewise) and logs
+   the four vars to the diag log; `cmake/TargetArch.cmake` falls back to
+   `${CMAKE_C_COMPILER} -dumpmachine` when `CMAKE_SYSTEM_PROCESSOR` is empty
+   and FATAL_ERRORs instead of emitting an untagged binary. Existing build
+   dirs are unaffected (value already cached); a dir configured before the
+   fix picks up x86_64 on its next in-place reconfigure.
 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 {
@@ -94,25 +202,14 @@ Needs CMake + SDL2 + zlib + OpenGL, and must run from the MSYS2 MINGW64 shell
 
 ## 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`.
+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`, `n64stubs.c`, `random.c`, or `ucode.c`.
 2. **Duplicates.** No symbol defined twice across the compiled set (watch `sp_*` stacks, `rmon*`, `os*` shims, segment markers).
 3. **Syntax.** Every touched file must parse; `./build-pc.sh` is the final word.
 
 Run `/linkcheck` for this sweep. Record new findings in `docs/dev/findings.md` §F/§H style (next `Dxx` label after the last used) and add the label to the §F index.
 
-## Phase status (summary — see README + `docs/dev/findings.md` for detail)
+## Phase status
 
-- **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 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
-  bugs open (D118* mouse-look residuals; interactive feel-checks owed). Audio
-  mixer done (libaudio → SDL software mixer, D198–D201); D204 tempo drift
-  fixed + measured; D202 stuck door loop root-caused with a port-side
-  expiration (M-66b) awaiting by-ear verification.
-- **Phase 4 (saves + polish):** file-backed EEPROM done; widescreen, config,
-  rebinding UI outstanding.
+Do not keep a status summary here — it goes stale. Open work, known issues
+and decisions owed: **`docs/ROADMAP.md`** (the single tracker). Current
+release state: the README "Status" section.

CLAUDE.md

@@ -16,6 +16,8 @@ Context is scarce. Load by tier; do not blind-read whole files.
   `docs/HANDOFF.md` (current state + next task + environment — a rolling
   local working file; may be absent in a fresh clone, in which case read
   the README "Status" section instead) — read fully;
+  `docs/ROADMAP.md` (the single tracker of open work — read the section
+  relevant to the task);
   `docs/porting-notes.md` (recurring bug classes) — skim the section
   headers, read the classes relevant to the task.
 - **Tier 2 — on demand only, do NOT read start-to-finish:**
@@ -41,6 +43,12 @@ Having a concrete "next step" from the handoff is NOT license to skip this.
 2. Skim the README "Status" section for where the project stands.
 3. If you may dispatch a subagent this session, read `docs/dev-process.md`
    NOW — not at dispatch time.
+4. Tree hygiene applies to anything you commit — see AGENTS.md §Tree hygiene &
+   release gate: no local absolute paths or usernames in tracked files (use
+   `<repo>`/`<repos>`/`<games>`/`<videos>`/`<python>`/`<temp>`), no contributor
+   emails in prose (name + PR number), every vendored third-party license
+   declared in `NOTICE`, no bulk ROM-derived captures in the tree (capture
+   dirs are gitignored), and one batched commit per session — not one per fix.
 
 ## Dispatch preflight — EVERY Agent/Task spawn, no exceptions
 
@@ -74,7 +82,7 @@ Full template: `docs/dev-process.md` -> "Investigation-brief template".
 ## Local Qwen dispatch (cost-free, data-local worker)
 
 A local Qwen3.8-27B is wired in via the `delegate-local` MCP server (see
-`C:\Users\james\Source\Repos\20260902-qwen38claudepair`). Use it as a
+`<repos>\20260902-qwen38claudepair`). Use it as a
 *subagent whose compute runs on-machine* for scoped, checkable work — the lead
 still owns judgment, planning, and the verification gate.
 
@@ -91,7 +99,7 @@ still owns judgment, planning, and the verification gate.
   proxy (`litellm/run.ps1`) + Unsloth Studio both up.
 - **Corrected 2026-09-04:** the "worker's shell is `cmd.exe`, no grep/cat"
   claim that used to live here was WRONG — verified directly against the
-  harness's own `_run_bash` (`C:\Users\james\tools\claude-code-delegate-local`):
+  harness's own `_run_bash` (the local `claude-code-delegate-local` harness dir):
   `grep`, `sed`, `cat`, `ls`, `head`, pipes, and `grep -rn` all work fine
   (Git-for-Windows/MSYS2 toolchain on PATH). The stale claim, baked into 4 of
   5 local agent `.md` files, caused a real dispatch (a multi-file

CMakeLists.txt

@@ -25,11 +25,26 @@ list(APPEND CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake)
 # name as an inherited one — CCTVRecord's `pad` — see docs/internals.md.)
 # An explicit -DCMAKE_C_COMPILER=... always wins.
 if(NOT DEFINED CMAKE_C_COMPILER)
-  find_program(_GE007_GCC NAMES gcc)
+  if(CMAKE_HOST_APPLE)
+    # Homebrew installs real GNU GCC with a version suffix; /usr/bin/gcc is
+    # Apple Clang and does not support the Plan 9 struct extensions required
+    # by the decomp's `inherits` pattern.
+    find_program(_GE007_GCC
+      NAMES gcc-16 gcc-15 gcc-14 gcc-13 gcc-12 gcc-11 gcc)
+  else()
+    find_program(_GE007_GCC NAMES gcc)
+  endif()
   if(_GE007_GCC)
     set(CMAKE_C_COMPILER "${_GE007_GCC}" CACHE FILEPATH "C compiler" FORCE)
     get_filename_component(_GE007_GCC_DIR "${_GE007_GCC}" DIRECTORY)
-    find_program(_GE007_GXX NAMES g++ PATHS "${_GE007_GCC_DIR}" NO_DEFAULT_PATH)
+    if(CMAKE_HOST_APPLE)
+      find_program(_GE007_GXX
+        NAMES g++-16 g++-15 g++-14 g++-13 g++-12 g++-11 g++
+        PATHS "${_GE007_GCC_DIR}" NO_DEFAULT_PATH)
+    else()
+      find_program(_GE007_GXX NAMES g++
+        PATHS "${_GE007_GCC_DIR}" NO_DEFAULT_PATH)
+    endif()
     if(_GE007_GXX)
       set(CMAKE_CXX_COMPILER "${_GE007_GXX}" CACHE FILEPATH "CXX compiler" FORCE)
     endif()
@@ -37,17 +52,48 @@ if(NOT DEFINED CMAKE_C_COMPILER)
 endif()
 
 if(APPLE)
+  # CMAKE_OSX_ARCHITECTURES is normally EMPTY here (the build targets the host
+  # arch), so an arm64 Mac used to fall into the 10.13 (Intel) floor and ld
+  # warned that the brew-gcc aarch64 runtime libs and the generated .s objects
+  # carry a newer floor than the linked one. D609 (macos branch): also consult
+  # the host machine when no explicit -arch list was requested. CMake's own
+  # CMAKE_HOST_SYSTEM_PROCESSOR is EMPTY on macOS (its `uname -p` probe
+  # returns "unknown" there - same class as D515's stripped-env arch probe),
+  # so ask `uname -m` directly. 11.0 is Big Sur, the first arm64 release.
   if(CMAKE_OSX_ARCHITECTURES MATCHES "arm64")
-    set(CMAKE_OSX_DEPLOYMENT_TARGET "11.0" CACHE STRING "" FORCE)
-  else()
-    set(CMAKE_OSX_DEPLOYMENT_TARGET "10.13" CACHE STRING "" FORCE)
+    set(_GE007_OSX_FLOOR "11.0")
+  elseif(CMAKE_OSX_ARCHITECTURES STREQUAL "")
+    # No /bin/uname on macOS, and CMake's execute_process looks the name up in
+    # PATH - so pass the bare name.
+    execute_process(COMMAND uname -m OUTPUT_VARIABLE _GE007_UNAME_M
+                    RESULT_VARIABLE _GE007_UMRC)
+    if(_GE007_UMRC EQUAL 0)
+      string(STRIP "${_GE007_UNAME_M}" _GE007_UNAME_M)
+      if(_GE007_UNAME_M MATCHES "^(aarch64|arm64)")
+        set(_GE007_OSX_FLOOR "11.0")
+      else()
+        set(_GE007_OSX_FLOOR "10.13")
+      endif()
+    endif()
   endif()
+  if(NOT DEFINED _GE007_OSX_FLOOR)
+    set(_GE007_OSX_FLOOR "10.13")
+  endif()
+  set(CMAKE_OSX_DEPLOYMENT_TARGET "${_GE007_OSX_FLOOR}" CACHE STRING "" FORCE)
+  unset(_GE007_OSX_FLOOR)
+  message(STATUS "macOS deployment target floor: ${CMAKE_OSX_DEPLOYMENT_TARGET}")
 endif()
 
 # ASM is needed for the generated absolute ROM asset symbols
 # (port/src/romassets_<region>.s, see scripts/gen_romassets.py).
 project(ge007 C CXX ASM)
 
+# Debug gate: validate every u32 -> host-pointer conversion against the regions
+# the port actually maps, and report offenders at the conversion site with a
+# backtrace. Off by default (zero cost); enable with -DPORT_ADDR_STRICT=ON.
+# Catches the MACOS-SFX-BOUND through MACOS-TEXALIGN truncated/never-rebased-pointer family early.
+option(PORT_ADDR_STRICT "Validate N64->host address conversions at runtime" OFF)
+
 include(TargetArch)
 include(FindPkgConfig)
 
@@ -93,6 +139,21 @@ else()
 endif()
 message(STATUS "Target arch: ${TARGET_ARCH} (64bit=${TARGET_IS_64BIT})")
 
+# Host base of the N64 address window (port/include/portaddr.h, D607). Must be
+# set BEFORE add_definitions below, and AFTER target_architecture(): D609 showed
+# CMAKE_SYSTEM_PROCESSOR/CMAKE_HOST_SYSTEM_PROCESSOR are EMPTY on macOS, so the
+# gate uses TARGET_ARCH (the D609 pagezero gate uses the same test).
+# 0 on Windows/Linux; 16 TiB on arm64 macOS (overridable with
+# -DPORT_ADDR_BASE=... for tooling, e.g. an ASan build whose shadow region
+# overlaps 16 TiB). Fed to the compiler (-DPORT_ADDR_BASE) and to
+# scripts/gen_macho_syms.py --base for the romassets absolute symbols, so the
+# cart pairing (romdata.c CART_HOST vs romassets_*.s values) agrees.
+if(APPLE AND TARGET_ARCH MATCHES "^aarch64$")
+  set(PORT_ADDR_BASE 0x100000000000 CACHE STRING "Host base of the N64 address window (arm64 macOS)")
+else()
+  set(PORT_ADDR_BASE 0x0 CACHE STRING "Host base of the N64 address window")
+endif()
+
 if(WIN32)
   set(TARGET_OS "windows")
 elseif(APPLE)
@@ -149,6 +210,7 @@ endif()
 # Provenance, printed by --version and at startup (port/src/main.c): a build
 # keeps pointing at this repository no matter who compiles or renames it.
 set(VERSION_CODENAME "larkspur")
+set(GE007_VERSION "0.6.0")   # bump on every release
 set(ORIGIN_URL "https://github.com/jkdansereau/goldeneye-pc-port")
 
 configure_file(
@@ -163,7 +225,18 @@ configure_file(
 # the toolchain include dir from the compiler location (MinGW/MSYS2 layout:
 # bin/../include) and generate an absolute-path include.
 get_filename_component(_PORT_GCC_DIR "${CMAKE_C_COMPILER}" DIRECTORY)
-get_filename_component(PORT_HOST_STRING_H "${_PORT_GCC_DIR}/../include/string.h" ABSOLUTE)
+if(APPLE)
+  execute_process(
+    COMMAND xcrun --show-sdk-path
+    OUTPUT_VARIABLE _PORT_MACOS_SDK OUTPUT_STRIP_TRAILING_WHITESPACE
+    ERROR_QUIET)
+  if(NOT _PORT_MACOS_SDK)
+    message(FATAL_ERROR "Cannot locate the macOS SDK; install the Xcode Command Line Tools")
+  endif()
+  set(PORT_HOST_STRING_H "${_PORT_MACOS_SDK}/usr/include/string.h")
+else()
+  get_filename_component(PORT_HOST_STRING_H "${_PORT_GCC_DIR}/../include/string.h" ABSOLUTE)
+endif()
 configure_file(
   "${CMAKE_SOURCE_DIR}/port/include/hoststring.h.in"
   "${CMAKE_BINARY_DIR}/port/include/hoststring.h" @ONLY)
@@ -172,7 +245,11 @@ configure_file(
 # the include path and shadows the system header; libstdc++'s <thread>/gthr
 # headers in the fast3d C++ TUs need the real <sched.h> (cpu_set_t,
 # sched_yield). Both MinGW and Linux keep <sched.h> at bin/../include.
-get_filename_component(PORT_HOST_SCHED_H "${_PORT_GCC_DIR}/../include/sched.h" ABSOLUTE)
+if(APPLE)
+  set(PORT_HOST_SCHED_H "${_PORT_MACOS_SDK}/usr/include/sched.h")
+else()
+  get_filename_component(PORT_HOST_SCHED_H "${_PORT_GCC_DIR}/../include/sched.h" ABSOLUTE)
+endif()
 configure_file(
   "${CMAKE_SOURCE_DIR}/port/include/hostsched.h.in"
   "${CMAKE_BINARY_DIR}/port/include/hostsched.h" @ONLY)
@@ -182,7 +259,11 @@ configure_file(
 # one C++ TU (fast3d): MinGW's own sec_api/stdlib_s.h does `#include
 # <stdlib.h>`, which resolves to the N64 header via -I. The shim routes C++
 # TUs to the host header by absolute path (same trick as hoststring.h).
-get_filename_component(PORT_HOST_STDLIB_H "${_PORT_GCC_DIR}/../include/stdlib.h" ABSOLUTE)
+if(APPLE)
+  set(PORT_HOST_STDLIB_H "${_PORT_MACOS_SDK}/usr/include/stdlib.h")
+else()
+  get_filename_component(PORT_HOST_STDLIB_H "${_PORT_GCC_DIR}/../include/stdlib.h" ABSOLUTE)
+endif()
 configure_file(
   "${CMAKE_SOURCE_DIR}/port/include/hoststdlib.h.in"
   "${CMAKE_BINARY_DIR}/port/include/hoststdlib.h" @ONLY)
@@ -212,8 +293,13 @@ add_definitions(
   -D_LANGUAGE_C=1
   -DAVOID_UB=1
   -DPAL=${VERSION_IS_PAL}
+  -DPORT_ADDR_BASE=${PORT_ADDR_BASE}
   ${REGION_DEFS}
 )
+if(PORT_ADDR_STRICT)
+  add_definitions(-DPORT_ADDR_STRICT=1)
+  message(STATUS "PORT_ADDR_STRICT enabled: N64->host conversions are validated at runtime")
+endif()
 if(TARGET_IS_64BIT)
   add_definitions(-DPLATFORM_64BIT=1)
 endif()
@@ -237,7 +323,9 @@ add_compile_options(
 # runs the same way; the genuinely understood cases are still fixed properly
 # under #ifdef PORT (D189). A hardened Linux build would need the whole class
 # swept first — tracked in docs/dev/findings.md.
-add_compile_options(-fno-stack-protector)
+if(NOT GE_STACK_PROTECTOR_ALL)
+  add_compile_options(-fno-stack-protector)
+endif()
 # Keep frame pointers: dbghelp's StackWalk64 (crash handler + thread dumps)
 # cannot read DWARF unwind info on MinGW, so the EBP chain is the only way to
 # get a real backtrace of a hung/crashed game thread.
@@ -287,14 +375,18 @@ add_compile_options($<$<COMPILE_LANGUAGE:CXX>:-Wno-unused-function>)
 # automatic base-pointer conversion the idiom relies on). C only — the decomp
 # is C; fast3d C++ does not use `inherits`.
 if(NOT MINGW)
-  add_compile_options($<$<COMPILE_LANGUAGE:C>:-fplan9-extensions>)
-  # GCC 14 promoted several long-standing C leniencies to hard errors
-  # (int<->pointer for a known prototype, incompatible-pointer arg types,
-  # implicit int/function). The WIP decomp still trips these (e.g.
-  # append_text_picked_up's vestigial u8* params in propobj.c). -fpermissive
-  # downgrades them to warnings — the C counterpart of the -Wno-error lines
-  # above, and the documented path for building older C against GCC 14+.
-  add_compile_options($<$<COMPILE_LANGUAGE:C>:-fpermissive>)
+  # GCC-only flags: the macOS default compiler is Apple clang (via the
+  # /usr/bin/gcc c99 shim), which rejects both of these.
+  if(CMAKE_C_COMPILER_ID STREQUAL "GNU")
+    add_compile_options($<$<COMPILE_LANGUAGE:C>:-fplan9-extensions>)
+    # GCC 14 promoted several long-standing C leniencies to hard errors
+    # (int<->pointer for a known prototype, incompatible-pointer arg types,
+    # implicit int/function). The WIP decomp still trips these (e.g.
+    # append_text_picked_up's vestigial u8* params in propobj.c). -fpermissive
+    # downgrades them to warnings — the C counterpart of the -Wno-error lines
+    # above, and the documented path for building older C against GCC 14+.
+    add_compile_options($<$<COMPILE_LANGUAGE:C>:-fpermissive>)
+  endif()
 endif()
 
 # ASLR must be OFF: dram_syms.s defines absolute symbols (cfb_16 @ 0x70000000,
@@ -328,6 +420,30 @@ elseif(UNIX AND NOT APPLE)
   # relocations are fine (unlike a 0x140000000 base, which needs mcmodel=large).
   # This is the ELF analogue of the Windows build's fixed 0x140000000 base.
   set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Wl,-Ttext-segment=0x20000000")
+elseif(APPLE)
+  # Mach-O executables normally reserve [0, 4 GiB) as __PAGEZERO. The x86_64
+  # (Intel) port needs fixed mappings at 0x10000000 (ROM), 0x70000000 (s32-safe
+  # DRAM) and 0x80000000 (KSEG0 mirror), so shrink the guard to 64 KiB and keep
+  # null/low-pointer protection only that far (#88).
+  #
+  # D609: on arm64 macOS that flag is FATAL AT EXEC, not at link time. The
+  # Apple-Silicon kernel enforces the 4 GiB guard region (SVE): an image whose
+  # __PAGEZERO is smaller than 0x100000000 is SIGKILL'd by the kernel during
+  # exec, before dyld runs - no output, no crash report, no unified-log entry
+  # at unprivileged levels, and lldb refuses the image ("Malformed Mach-o file").
+  # Reproduced with a 6-line C program: `gcc probe.c -Wl,-pagezero_size,0x10000`
+  # exits 137 (128+9); the same program with the default pagezero exits 7. The
+  # arm64 port does not need the shrink at all - portaddr.h already shifts the
+  # whole N64 window up by PORT_ADDR_BASE = 16 TiB, so every required mapping
+  # (ROM, DRAM V1/K0) lives far above the guard; verified with the same minimal
+  # probe (shm_open + the two MAP_FIXED mmaps at 0x100070000000 / 0x100080000000
+  # alias correctly and exit 7). So: shrink on x86_64 only, default on arm64.
+  if(TARGET_ARCH MATCHES "^aarch64$")
+    message(STATUS "arm64 macOS: keeping the default 4 GiB __PAGEZERO (arena is at PORT_ADDR_BASE)")
+  else()
+    set(CMAKE_EXE_LINKER_FLAGS
+      "${CMAKE_EXE_LINKER_FLAGS} -Wl,-pagezero_size,0x10000")
+  endif()
 endif()
 
 # port/shim first: PC-only shadow headers (bondtypes.h, bondconstants.h,
@@ -342,6 +458,7 @@ include_directories(
   "${CMAKE_SOURCE_DIR}/src/game"
   "${CMAKE_SOURCE_DIR}/src/libultra"
   "${CMAKE_SOURCE_DIR}/src/libultra/audio"
+  "${CMAKE_SOURCE_DIR}/src/libultra/gu"
   "${CMAKE_SOURCE_DIR}/port/include"
   "${CMAKE_BINARY_DIR}/port/include"
 )
@@ -395,6 +512,8 @@ if(NOT EXTRA_LIBRARIES)
     set(EXTRA_LIBRARIES dbghelp -static-libstdc++ pthread)
   elseif(WIN32)
     set(EXTRA_LIBRARIES dbghelp -static-libstdc++)
+  elseif(APPLE)
+    set(EXTRA_LIBRARIES stdc++ m pthread)
   else()
     set(EXTRA_LIBRARIES stdc++ m dl pthread)
   endif()
@@ -414,14 +533,91 @@ file(GLOB_RECURSE SRC_FAST3D    "${CMAKE_SOURCE_DIR}/port/fast3d/*.cpp"
 # scripts/gen_romassets.py). Defines every obseg/ramrom/music label and the
 # ge007.ld segment markers as 0x10000000 + rom_offset, so `&symbol` / romCopy()
 # work once romdata.c maps the .z64 at 0x10000000.
-set(SRC_ROMASSETS "${CMAKE_SOURCE_DIR}/port/src/romassets_${ASSET_REGION}.s")
-if(NOT EXISTS ${SRC_ROMASSETS})
-  message(FATAL_ERROR "Missing ${SRC_ROMASSETS} — run: python3 scripts/gen_romassets.py ${ASSET_REGION}")
+set(SRC_ROMASSETS_INPUT "${CMAKE_SOURCE_DIR}/port/src/romassets_${ASSET_REGION}.s")
+if(NOT EXISTS ${SRC_ROMASSETS_INPUT})
+  message(FATAL_ERROR "Missing ${SRC_ROMASSETS_INPUT} — run: python3 scripts/gen_romassets.py ${ASSET_REGION}")
 endif()
 
 # Absolute symbols inside the reserved N64-DRAM region (port/src/dram.c):
 # cfb_16 (replaces src/cfb.c) and _bssSegmentEnd (mempool start marker).
-set(SRC_DRAM_SYMS "${CMAKE_SOURCE_DIR}/port/src/dram_syms.s")
+set(SRC_DRAM_SYMS_INPUT "${CMAKE_SOURCE_DIR}/port/src/dram_syms.S")
+
+# D441 high-arena test flavour: relocate the DRAM arena for test builds
+# (tier 1 = 0x90000000). Build option only — the default build is unchanged.
+#   GE_HIGHARENA_BASE=0x90000000 ./build-pc.sh ntsc-final
+# or -DGE_HIGHARENA_BASE=0x90000000 at configure time. The value must be a
+# C/asm integer literal; it overrides PORT_DRAM_V1_BASE in portaddr.h for
+# C, CXX and ASM (dram.c's mapping and the dram_syms.S absolute symbols both
+# follow it).
+set(GE_HIGHARENA_BASE "" CACHE STRING "Override PORT_DRAM_V1_BASE for test builds (high-arena flavour)")
+if(NOT GE_HIGHARENA_BASE)
+  set(GE_HIGHARENA_BASE "$ENV{GE_HIGHARENA_BASE}")
+endif()
+if(GE_HIGHARENA_BASE)
+  message(STATUS "GE_HIGHARENA_BASE = ${GE_HIGHARENA_BASE}")
+  set(_d441_arena_def "-DPORT_DRAM_V1_BASE=${GE_HIGHARENA_BASE}")
+  set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${_d441_arena_def}")
+  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${_d441_arena_def}")
+  set(CMAKE_ASM_FLAGS "${CMAKE_ASM_FLAGS} ${_d441_arena_def}")
+endif()
+
+# Apple: the two absolute-symbol files are converted to Mach-O spelling
+# (scripts/gen_macho_syms.py: .global -> .globl with a leading underscore,
+# ELF-style directives dropped). dram_syms.S is C-preprocessed first: it
+# pulls the arena bases from portaddr.h (PORT_ADDR_BASE + offset; the header
+# self-detects the 16 TiB arm64 base from its own __ASSEMBLER__ branch, no
+# -D needed), and the Mach-O assembler does not run the C preprocessor on
+# .s input. Only the high-arena test flavour passes a -D override.
+if(APPLE)
+  find_package(Python3 REQUIRED COMPONENTS Interpreter)
+  # The generated .s files land in a build-dir subdir; CMake creates dirs for
+  # rules with C/C++ outputs only, so make it explicitly (the cc -E -o below
+  # fails with "No such file or directory" otherwise).
+  file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/port/src")
+  set(SRC_ROMASSETS "${CMAKE_BINARY_DIR}/port/src/romassets_${ASSET_REGION}_macho.s")
+  set(SRC_DRAM_SYMS_EXPANDED "${CMAKE_BINARY_DIR}/port/src/dram_syms_expanded.s")
+  set(SRC_DRAM_SYMS "${CMAKE_BINARY_DIR}/port/src/dram_syms_macho.s")
+  add_custom_command(
+    OUTPUT "${SRC_ROMASSETS}"
+    COMMAND "${Python3_EXECUTABLE}"
+            "${CMAKE_SOURCE_DIR}/scripts/gen_macho_syms.py"
+            --base "${PORT_ADDR_BASE}"
+            "${SRC_ROMASSETS_INPUT}" "${SRC_ROMASSETS}"
+    DEPENDS "${SRC_ROMASSETS_INPUT}"
+            "${CMAKE_SOURCE_DIR}/scripts/gen_macho_syms.py"
+    VERBATIM)
+  set(_dram_syms_pp_def "")
+  if(GE_HIGHARENA_BASE)
+    set(_dram_syms_pp_def "-DPORT_DRAM_V1_BASE=${GE_HIGHARENA_BASE}")
+  endif()
+  # D607: the COMMAND list must stay one CMake argument per argv element:
+  # quoting the whole "cc -E -I..." as ONE string works on Windows (cmd
+  # parses the command line) but /bin/sh on macOS/Linux treats the entire
+  # string as a single filename ("No such file or directory").
+  add_custom_command(
+    OUTPUT "${SRC_DRAM_SYMS_EXPANDED}"
+    COMMAND "${CMAKE_C_COMPILER}" "-E"
+            "-I${CMAKE_SOURCE_DIR}/port/include"
+            ${_dram_syms_pp_def}
+            "${SRC_DRAM_SYMS_INPUT}"
+            "-o" "${SRC_DRAM_SYMS_EXPANDED}"
+    DEPENDS "${SRC_DRAM_SYMS_INPUT}"
+            "${CMAKE_SOURCE_DIR}/port/include/portaddr.h"
+    VERBATIM)
+  add_custom_command(
+    OUTPUT "${SRC_DRAM_SYMS}"
+    COMMAND "${Python3_EXECUTABLE}"
+            "${CMAKE_SOURCE_DIR}/scripts/gen_macho_syms.py"
+            "${SRC_DRAM_SYMS_EXPANDED}" "${SRC_DRAM_SYMS}"
+    DEPENDS "${SRC_DRAM_SYMS_EXPANDED}"
+            "${CMAKE_SOURCE_DIR}/scripts/gen_macho_syms.py"
+    VERBATIM)
+  set_source_files_properties(${SRC_ROMASSETS} ${SRC_DRAM_SYMS_EXPANDED} ${SRC_DRAM_SYMS}
+    PROPERTIES GENERATED TRUE)
+else()
+  set(SRC_ROMASSETS "${SRC_ROMASSETS_INPUT}")
+  set(SRC_DRAM_SYMS "${SRC_DRAM_SYMS_INPUT}")
+endif()
 
 # Game code — compiled unmodified.
 file(GLOB_RECURSE SRC_GAME "${CMAKE_SOURCE_DIR}/src/game/*.c")
@@ -452,6 +648,39 @@ file(GLOB SRC_LIBULTRARE_AUDIO "${CMAKE_SOURCE_DIR}/src/libultrare/audio/*.c")
 # gu matrix helpers.
 file(GLOB SRC_GU "${CMAKE_SOURCE_DIR}/src/libultra/gu/*.c")
 
+# GCC for Darwin crashes while lowering the decomp's ELF-style
+# `#pragma weak alias = target` directives. Compile generated copies with
+# those directives removed, then provide their aliases in Mach-O assembly.
+set(SRC_MACHO_ALIASES "")
+if(APPLE)
+  set(_MACHO_GENERATED_SOURCES "")
+  set(_MACHO_WEAK_INPUTS
+    "${CMAKE_SOURCE_DIR}/src/game/lv.c"
+    "${CMAKE_SOURCE_DIR}/src/game/objective_status.c"
+    "${CMAKE_SOURCE_DIR}/src/game/spectrum.c"
+    "${CMAKE_SOURCE_DIR}/src/libultra/gu/sinf.c"
+    "${CMAKE_SOURCE_DIR}/src/libultra/gu/cosf.c")
+  foreach(_INPUT IN LISTS _MACHO_WEAK_INPUTS)
+    get_filename_component(_NAME "${_INPUT}" NAME)
+    set(_OUTPUT "${CMAKE_BINARY_DIR}/port/src/macho_${_NAME}")
+    add_custom_command(
+      OUTPUT "${_OUTPUT}"
+      COMMAND "${Python3_EXECUTABLE}"
+              "${CMAKE_SOURCE_DIR}/scripts/strip_weak_pragmas.py"
+              "${_INPUT}" "${_OUTPUT}"
+      DEPENDS "${_INPUT}" "${CMAKE_SOURCE_DIR}/scripts/strip_weak_pragmas.py"
+      VERBATIM)
+    list(APPEND SRC_MACHO_ALIASES "${_OUTPUT}")
+    list(APPEND _MACHO_GENERATED_SOURCES "${_OUTPUT}")
+    list(REMOVE_ITEM SRC_GAME "${_INPUT}")
+    list(REMOVE_ITEM SRC_GU "${_INPUT}")
+  endforeach()
+  list(APPEND SRC_MACHO_ALIASES
+    "${CMAKE_SOURCE_DIR}/port/src/macho_weak_aliases.s")
+  set_source_files_properties(${_MACHO_GENERATED_SOURCES}
+    PROPERTIES GENERATED TRUE)
+endif()
+
 # VI mode table (DATA, not a driver): fr.c references osViModeTable ~15x.
 # This is the only libultra/io file we compile — the rest are hardware
 # drivers that get shimmed in port/src/libultra.c.
@@ -569,6 +798,7 @@ set(SRC
   ${SRC_LIBULTRARE_LIBC}
   ${SRC_ASSETS}
   ${SRC_GU}
+  ${SRC_MACHO_ALIASES}
   ${SRC_ENGINE}
 )
 
@@ -581,6 +811,11 @@ target_link_libraries(ge007 ${LIBS})
 set_target_properties(ge007 PROPERTIES OUTPUT_NAME "${BIN_NAME}")
 if(WIN32)
   set_target_properties(ge007 PROPERTIES WIN32_EXECUTABLE TRUE)
+  # Explorer/taskbar icon: the original crosshair mark (cmake/icon/ge007.rc,
+  # a static resource script; the ge007.ico it references is generated by
+  # tools_pc/make_icon.py). Compiled by the resource compiler; ge007.ico is
+  # resolved relative to this .rc file.
+  target_sources(ge007 PRIVATE cmake/icon/ge007.rc)
 endif()
 
 message(STATUS "Output binary: ${BIN_NAME}")

CONTRIBUTING.md

@@ -32,6 +32,25 @@ keep the port faithful to the original game.
    clean configure + build for `ntsc-final` and a crash-free run of one level
    (`./build-pc/ge007.x86_64 -level_09`).
 
+5. **No game data, ever.** Never commit, upload or attach a ROM or anything
+   extracted from one (textures, audio, models, level data, in-game text,
+   the generated `data/pcmodels-*` / `data/pccg-*` folders) in a pull
+   request or an issue. A small cropped screenshot of a glitch is fine.
+
+## Bug reports
+
+Open an [issue](https://github.com/jkdansereau/goldeneye-pc-port/issues/new/choose)
+with:
+
+- `ge007.crash.log` if the game crashed (in the folder you launched from),
+- the output of `ge007.x86_64 --version` (or the release version you
+  downloaded), your OS, and your GPU and driver version,
+- your ROM's SHA-1 (Windows: `certutil -hashfile <rom> SHA1`, Linux:
+  `sha1sum <rom>`),
+- what you did, what happened, and what you expected.
+
+**Never attach the ROM itself.**
+
 ## Style
 
 - C/C++ formatting follows `.clang-format` and `.editorconfig` in the repo

NOTICE

@@ -10,6 +10,9 @@ repository:
   * the port layer            port/
   * the PC build system        CMakeLists.txt, cmake/, build-pc.sh
   * PC-port tooling            tools_pc/
+  * macOS packaging            scripts/package-macos.sh, scripts/gen_macho_syms.py,
+                               scripts/strip_weak_pragmas.py
+  * agent-development tooling  pi/ (not part of the game build)
   * documentation              docs/, README.md
 
 Third-party code vendored into the port layer keeps its own license:
@@ -18,6 +21,33 @@ Third-party code vendored into the port layer keeps its own license:
     libultraship / sm64-port lineage; see port/fast3d/LICENSE.txt.
   * port/fast3d/glad/ - generated OpenGL loader (glad), public domain / MIT.
 
+Runtime libraries bundled in the downloads (not in this repository) keep
+their own licenses; each license text ships in the download's licenses/ folder:
+
+  * SDL2 (all platforms) and SDL3 (macOS, loaded by sdl2-compat) - zlib license.
+  * zlib - zlib license.
+  * Windows: the MinGW-w64 runtime (libwinpthread, libgcc, libstdc++).
+  * macOS: the GCC runtime (libgcc_s, libstdc++) - GPL-3.0 with the GCC
+    Runtime Library Exception 3.1. The GPL-3.0 text the macOS package ships
+    is tools_pc/dist/GPL-3.0.txt.
+
+The license texts the downloads carry come from the build environment where
+it provides them, otherwise from tools_pc/dist/ (GPL-3.0.txt,
+GCC-RUNTIME-EXCEPTION.txt, SDL2-LICENSE.txt).
+
+Vendored build tooling keeps its own license (none of it is compiled or linked
+into the PC port; it belongs to the N64 decompilation build):
+
+  * tools/ido5.3_recomp/rabbitizer/ - disassembler library (rabbitizer), MIT,
+    (c) 2022 Decompollaborate; license text in that directory's LICENSE file.
+  * tools/armips.cpp - assembler (armips), MIT, (c) 2009-2020 Kingcom.
+  * tools/extractor/puff.c, puff.h - puff-style inflate, zlib-style license,
+    (c) Mark Adler.
+  * tools/gzipsrc/ - gzip 1.x sources, GPL-2.0-or-later, (c) 1992-1993
+    Jean-loup Gailly; the GPL-2.0 text is tools/gzipsrc/COPYING. These sources
+    are build tooling only: they are never linked into the port, and they are
+    not part of any download package.
+
 It does NOT cover:
 
   * src/, include/, assets/, Makefile, tools/, rsp/, ld/, and the other
@@ -34,11 +64,13 @@ It does NOT cover:
     assets -- textures, audio, models, level geometry, in-game text -- are
     NOT included and are extracted from your own ROM at build time.
 
-NO NINTENDO / RARE CONTENT IS DISTRIBUTED HERE
----------------------------------------------
+NO ROM DATA OR ORIGINAL ASSETS ARE DISTRIBUTED HERE
+--------------------------------------------------
 
-This repository contains NO copyrighted ROM data, game assets (textures,
-models, levels, audio, text), or Nintendo/Rare code. Building a playable
+This repository contains NO ROM data and none of the original game assets
+(textures, models, levels, audio, text), and no original Nintendo/Rare
+binaries. The C source under src/ is the decompilation community's
+reconstruction of the game's code (see above). Building a playable
 executable requires a GoldenEye 007 Nintendo 64 ROM that you legally own;
 the build extracts the required assets from that ROM on your own machine.
 

README.md

@@ -1,435 +1,264 @@
-# GoldenEye 007 PC Port
+<p align="center">
+  <img src="docs/img/icon/ge007-icon.png" width="112" alt="GoldenEye 007 PC Port">
+</p>
 
-[![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-ffb454)
+<h1 align="center">GoldenEye 007 PC Port</h1>
 
-<p align="center"><em>GoldenEye 007 (Nintendo 64, 1997) on the PC —
-decompiled, ported, and playable at 60 fps.</em></p>
+<p align="center">
+  The original Nintendo 64 GoldenEye 007 (1997) as a native game for Windows,
+  Linux, Steam Deck and macOS (Apple Silicon).
+</p>
 
-[Download](#download) · [News](#news) · [Status](#status) · [Roadmap](#roadmap) · [Building](#building) · [Docs](#documentation) · [Legal](#legal)
+The GoldenEye 007 PC Port is a native port built from the game's own
+reconstructed source code (the [GoldenEye 007 decompilation](https://github.com/n64decomp/007)),
+in the same family as the [Perfect Dark PC port](https://github.com/fgsfdsfgs/perfect_dark).
+It is not an emulator: the game is compiled for your PC and runs from your own
+ROM, with native widescreen, 60 fps or more (up to 240 on fast displays),
+mouse and keyboard or a modern controller, split-screen for up to 4 players,
+and an in-game options menu.
 
-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.
+### [Download the latest release](https://github.com/jkdansereau/goldeneye-pc-port/releases/latest)
 
-**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).
-
-**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
-> Nintendo code or assets, and no ROM. Nothing here is distributable as a
-> playable game: see [Requirements](#requirements) and [Legal](#legal).
+**This repository and its downloads contain no ROM data and none of the
+original game assets. You need your own GoldenEye 007 ROM (US version) to play.**
 
 <p align="center">
   <img src="docs/media/goldeneye-gh-preview.gif" width="64%"
-       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>
+       alt="GoldenEye 007 running natively on PC: the Facility, the Dam sniper rifle and split-screen multiplayer">
+  <br><em>Recorded in the port: the Facility intro, the Archives, the Dam
+  sniper rifle, Silo, a 2-player match and the Dam ending.</em>
 </p>
 
----
+## Table of contents
 
-## 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](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.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](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](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) section first: the small number of known issues
-in this release are listed plainly there.
-
----
-
-## Status
-
-**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), 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:**
-
-- 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. 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](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](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, 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
-options, **A** steps the selected option forward, **B** steps it back, and
-**Start** (or Select again) closes. Toggles flip, resolution / MSAA /
-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, 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
-  `src/` is unmodified decompilation; every hardware surface lives in the
-  MIT-licensed `port/` layer.
-- **Mod it**: the port layer, build system and `tools_pc/` are yours to
-  extend (see [License](#license)); [`CONTRIBUTING.md`](CONTRIBUTING.md) has
-  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
-(`unsloth/Qwen3.8-27B-GGUF` on one RTX 5090, via the [pi](https://pi.dev/)
-agent) doing the groundwork (build, boot chain, software-RSP integration,
-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:
-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).
-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
-actual reconstructed source code, the same lineage as the Perfect Dark PC
-port. The other well-known "GoldenEye on PC" projects are something
-different: they machine-translate the shipped binary of the *unreleased Xbox
-360 XBLA remaster*, a different game on a different codebase with no shared
-code with this one.
-
-| | This project | The other well-known "GoldenEye on PC" recompilation projects (and their Steam Deck builds) |
-|---|---|---|
-| **What it ports** | The original **Nintendo 64** game (1997) | The **Xbox 360 XBLA** HD remaster (built ~2007, never released) |
-| **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.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](#requirements)
+- [Quick start](#quick-start)
+- [Controls](#controls)
+- [What this port offers](#what-this-port-offers)
+- [FAQ](#faq)
+- [Status](#status)
+- [Roadmap](#roadmap)
+- [Building from source](#building-from-source)
+- [Documentation](#documentation)
+- [Contributing and forking](#contributing-and-forking)
+- [Credits](#credits)
+- [Legal](#legal)
 
 ## Requirements
 
-You need a GoldenEye 007 (Nintendo 64) ROM that you legally own, in
-big-endian (`.z64`) format, matching one of:
+- **Windows:** Windows 10 or 11, 64-bit. Nothing to install: the download
+  carries its own runtime libraries and the one-time asset tool.
+- **Linux and Steam Deck:** 64-bit x86 Linux with glibc 2.31 or newer (Ubuntu
+  20.04+, Debian 11+, Fedora 32+, SteamOS). SDL2 is bundled.
+- **macOS (experimental):** an Apple Silicon Mac (M1 or later) on macOS 14 or
+  newer.
+- **Graphics:** OpenGL 3.0 (practically any PC GPU from the last fifteen
+  years). A 2011 laptop with Intel HD 3000 graphics holds 60 fps.
+- **Input:** keyboard and mouse, or an Xbox, PlayStation, Switch or other
+  SDL-supported controller; split-screen needs one controller per extra player.
 
-| Region | ROMID | ROM filename (in `data/`) | SHA-1 |
-|--------|-------|---------------------------|-------|
-| NTSC-U (US)  | `ntsc-final` | `ge007.ntsc-final.z64` | `abe01e4aeb033b6c0836819f549c791b26cfde83` |
-| PAL (EU)     | `pal-final`  | `ge007.pal-final.z64`  | `167c3c433dec1f1eb921736f7d53fac8cb45ee31` |
-| NTSC-J (JP)  | `jpn-final`  | `ge007.jpn-final.z64`  | `2a5dade32f7fad6c73c659d2026994632c1b3174` |
+## Quick start
 
-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](https://github.com/jkdansereau/goldeneye-pc-port/issues/85)).
+1. Download the build for your system from
+   [Releases](https://github.com/jkdansereau/goldeneye-pc-port/releases/latest)
+   and extract it. On Windows, don't run the exe from inside the zip.
+2. Make a `data/` folder next to the executable and put your ROM in it as
+   `ge007.ntsc-final.z64` (US version; [check your ROM](docs/user-guide.md#whats-a-rom)).
+3. Launch the game. The first start takes a few extra seconds while it
+   prepares the game files from your ROM.
+   - **Windows:** if SmartScreen appears (the exe isn't code-signed), click
+     **More info**, then **Run anyway**.
+   - **Steam Deck:** add the executable as a non-Steam game. It starts in
+     native 1280x800 fullscreen.
+   - **macOS:** run `xattr -dr com.apple.quarantine <folder>` once in
+     Terminal, then start `./ge007.aarch64`
+     (see the [macOS setup details](docs/user-guide.md#macos-apple-silicon-experimental)).
+4. Play. **F10** (controller: **Select**) opens the options menu.
 
-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,
-plus the decompilation's own build dependencies (an IRIX MIPS toolchain via
-`qemu-irix`, used only for the one-time asset extraction). See
-[`docs/building.md`](docs/building.md) for the full walkthrough and the
-asset-extraction details.
-
-### Windows (MSYS2)
-
-```sh
-# in the MINGW64 shell
-pacman -S mingw-w64-x86_64-toolchain mingw-w64-x86_64-SDL2 \
-          mingw-w64-x86_64-zlib mingw-w64-x86_64-cmake \
-          mingw-w64-x86_64-python make git
-
-git clone https://github.com/jkdansereau/goldeneye-pc-port.git
-cd goldeneye-pc-port
-# 1. extract assets from your ROM (see docs/building.md)
-# 2. build the port
-./build-pc.sh ntsc-final         # NTSC-U; PAL/JP engine builds compile, but their asset sidecars are not yet producible (issue #85)
-```
-
-### Linux
-
-The Linux build is compiled on every push by CI (ubuntu-24.04); the release
-bundle additionally bundles SDL2 so no system packages are needed at runtime.
-
-```sh
-sudo apt install build-essential cmake python3 libsdl2-dev zlib1g-dev libgl1-mesa-dev
-git clone https://github.com/jkdansereau/goldeneye-pc-port.git
-cd goldeneye-pc-port
-# extract assets (docs/building.md), then:
-./build-pc.sh ntsc-final
-```
-
-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.
-2. Put your ROM in it, named as in the table above
-   (e.g. `data/ge007.ntsc-final.z64`).
-3. Run the executable from the repo root:
-   `./build-pc/ge007.x86_64`.
-
-Configuration is written to `ge007.ini` on first run; game progress
-lives in `ge007.eep`. Launch with `-fresh` to wipe both before starting
-(a clean-slate run for playtesting).
-
-### Default controls
+## Controls
 
 | Action              | Keyboard / mouse         | Controller    |
 |---------------------|--------------------------|---------------|
-| Move / strafe       | `W` `A` `S` `D` / arrows  | Left stick (or D-pad) |
+| Move / strafe       | `W` `A` `S` `D`           | Left stick (or D-pad) |
+| Move / turn         | Arrow keys               | -             |
 | Aim / look          | Mouse                    | Right stick   |
 | 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 |
+| Crouch (toggles)    | `LCtrl`                   | Left or right stick click |
 | Cycle owned gadgets | Watch inventory          | B             |
 | Next weapon         | Mouse wheel down / `Q`   | Y             |
-| Previous weapon     | Mouse wheel up           | —             |
+| Previous weapon     | Mouse wheel up           | -             |
 | Start               | `Enter` / `Tab`          | Start         |
-| Options overlay     | `F10`                    | Select (A toggles/steps; B backs; D-pad/stick adjusts sliders; Start closes) |
+| Options menu        | `F10`                    | Select        |
 
-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.
+Everything is rebindable in the options menu. Rare's Xbox control styles are
+presets, and the **Original** control style turns your pad into an N64
+controller. The [user guide](docs/user-guide.md#controls) covers control
+styles, rebinding and split-screen.
 
-Mouse sensitivity, Y-inversion and the aim/turn split are tunable in the
-F10 overlay (*Keyboard → Sensitivity*) or the `[Input]` section of
-`ge007.ini`.
+## What this port offers
 
----
+- **Real 60 fps, not a speed hack.** The game's logic counts time in 60 Hz
+  ticks. On the N64 it only drew a frame every 2–3 ticks (20–30 fps); here it
+  draws every tick, so you get 60 fps with the game, physics and AI running
+  at the N64's own speed. There is no CPU overclock or frame-skip patch involved,
+  and the few spots in the game that behaved differently at one tick per frame
+  are fixed to match the N64. Above 60 (90 to 240, or Auto), extra
+  frames are blended between ticks for smoothness, at the cost of one tick of
+  latency.
+- **Aiming that doesn't feel floaty.** *Aim style* picks the behavior.
+  **Centered** pins the crosshair in the middle, and the mouse or the right
+  stick turns the camera directly, like a modern shooter. **Original** keeps
+  the N64's crosshair that moves a little before the camera follows. The stick
+  has separate horizontal and vertical sensitivity, separate deadzones for each
+  stick, look smoothing and a trigger threshold. The mouse has raw input, an aim
+  curve, smoothing, and separate turn and aim-mode sensitivities.
+- **Dual analog and mouse and keyboard, built in.** No emulator remapping. The
+  right stick looks, the triggers fire and aim, and every button is rebindable,
+  for the keyboard, the mouse and each controller. Rare's Xbox control styles are
+  presets. If you want the N64 exactly, the **Original** control style turns the
+  pad into a strict virtual N64 controller.
+- **The whole game.** All 20 solo missions and the credits, with every
+  difficulty, 007 mode and the cheats, plus split-screen multiplayer for up to
+  4 players. Your emulator saves (1964, Project64) load directly.
+- **Faithful by construction.** It is the game's own reconstructed source
+  compiled natively, not an emulator and not a remake, so levels, guards and
+  weapons behave the way the N64 cartridge does. The few changes to game code
+  either keep that N64 behavior where the PC would otherwise differ (frame
+  rate, widescreen, compiler) or are opt-in extras, and the **Original N64**
+  display preset switches every visual improvement off at once.
+- **Modern display options:** native widescreen and ultrawide at any aspect ratio, high
+  resolutions, MSAA, adjustable FOV and draw distance, and HUD scaling.
+- **Windows, Linux, Steam Deck and (experimental) macOS** from one download
+  page, with an in-game options menu on F10 or the pad's Select button.
 
-## How it works
+Bots, online play, mod support and PAL/JP ROMs are on the
+[Roadmap](#roadmap).
 
-The R4300 game code in `src/` is compiled completely unmodified; the
-decompilation's control flow is ground truth. Everything that would touch N64
-hardware is redirected into `port/`: a **software RSP** (`port/fast3d/`,
-adapted from the Perfect Dark port) that interprets the GBI display list the
-game builds each frame and emits OpenGL, bypassing the RDP; a scheduler
-replacement (`port/src/gesched.c`) that drives it directly; single-threaded
-libultra OS shims (`port/src/libultra.c`); and SDL2/OpenGL/filesystem backends
-for video, audio, input and storage. The 32→64-bit transition forces a small,
-cataloged class of mechanical ABI-only edits to ROM-serialized structs
-(pointer-width reconciliation); these change no behavior and are documented
-individually. Where it diverges from the Perfect Dark port: GoldenEye's N64
-serialized asset formats are converted offline by Python "sidecar" converters
-in `tools_pc/` rather than fixed up at load time. Full detail:
-[`docs/internals.md`](docs/internals.md) and
-[`docs/porting-notes.md`](docs/porting-notes.md).
+The [user guide](docs/user-guide.md#feature-list) has the full feature list.
 
-```
-CMakeLists.txt      PC build (parallel to the decomp's Makefile, which is untouched)
-build-pc.sh         configure + build helper
-src/  include/      the decompilation (game + libultra) - compiled unmodified
-port/
-  fast3d/           software RSP -> OpenGL
-  src/              port layer (main, OS shims, video, audio, input, fs, ...)
-  include/          port-facing headers
-tools/  Makefile    the N64 build + asset extraction (from the decomp; do not modify)
-tools_pc/           PC-port helper + analysis scripts
-docs/               see below
+## FAQ
+
+**Is this an emulator?**
+No. The game's code is compiled natively for your PC, the same way the
+Perfect Dark PC port works. Graphics go through OpenGL, and the N64 hardware
+is replaced by a small port layer.
+
+**Do I need the game?**
+Yes. You need a ROM of the US (NTSC-U) version, dumped from a cartridge you
+own. PAL and Japanese ROMs are planned.
+
+**Does it play like the original?**
+Yes. Levels, guards and weapons run on the game's own logic at its original
+speed. The **Original N64** display preset and the **Original** control style
+give you the N64 look and controls whenever you want them.
+
+**Does it run on the Steam Deck?**
+Yes. The Linux download is the Deck build: add it as a non-Steam game and it
+starts in native 1280x800 fullscreen at up to 90 fps, with the options menu
+fully usable on the controller.
+
+**Does it support ultrawide and high refresh rates?**
+Yes. Native widescreen works at any aspect ratio, including ultrawide, and the
+frame rate goes up to 240 fps on fast displays (Auto matches your monitor).
+
+**Is there online play, bots or mod support?**
+Not today. LAN play, bots and mod support are on the [roadmap](#roadmap) as
+opt-in extras.
+
+**Can I use HD textures?**
+Not in this release. A texture-pack loader is planned for 1.0.
+
+**How is this different from the XBLA recompilation projects?**
+Those projects statically recompile the unreleased Xbox 360 remaster, a
+separate version of the game. This project ports the original N64 game from
+its source code. See [About the project](docs/about.md#how-this-differs-from-the-other-goldeneye-pc-projects).
+
+**Can I keep my saves?**
+Yes. Your progress is a plain file, `data/ge007.eep`. Saves from 1964 or
+Project64 load directly (see [using an emulator save](docs/user-guide.md#using-an-emulator-save)),
+and updating keeps your save and settings (see [updating](docs/user-guide.md#updating)).
+
+**Was AI used to build it?**
+Yes. The port was developed with AI coding agents directed by one maintainer.
+Releases are checked by comparing captured frames from all 21 solo levels on
+Windows, crash sweeps on four platforms, and play-testing.
+[How it was made](docs/about.md#how-it-was-made) has the full story.
+
+**Something went wrong.**
+See [Troubleshooting](docs/user-guide.md#troubleshooting), or
+[open an issue](https://github.com/jkdansereau/goldeneye-pc-port/issues/new/choose)
+with `ge007.crash.log`, your OS and GPU. Never attach the ROM.
+
+## Status
+
+**v0.6.0 is the current release.** The whole campaign, the end credits and
+split-screen multiplayer are playable on Windows, Linux, Steam Deck and macOS.
+The project is pre-1.0, so expect new features and the occasional change
+between versions. Known issues and workarounds are in the
+[known-issues table](docs/ROADMAP.md#known-issues);
+[About the project](docs/about.md#status-in-detail) has the testing details and
+the [release history](docs/about.md#release-history).
+
+## Roadmap
+
+The goal is a **feature-complete, faithful** port: every mode and region the
+N64 cartridge ships, with modern options on top that can always be switched
+back to the original look and feel. Next up:
+
+- **PAL and JP ROM support** in the release packages
+  ([#85](https://github.com/jkdansereau/goldeneye-pc-port/issues/85)).
+- **A notarized macOS build**, Intel Macs and ARM Linux.
+- **A texture-pack loader** for HD texture packs.
+- **The 1.0 sign-off:** a full campaign playthrough and a split-screen session
+  on every platform that ships.
+
+After 1.0, opt-in extras that are always off by default: LAN play, bots,
+co-op and enhanced visuals. The full tracker is
+[`docs/ROADMAP.md`](docs/ROADMAP.md). If something matters to you, open an
+issue; it helps prioritize.
+
+## Building from source
+
+You need CMake 3.16+, a C/C++ toolchain, SDL2, zlib, OpenGL and Python 3, plus
+a one-time asset extraction from your ROM. On Windows, build in the MSYS2
+MINGW64 shell; on macOS, use Homebrew's GNU `gcc`.
+
+```sh
+git clone https://github.com/jkdansereau/goldeneye-pc-port.git
+cd goldeneye-pc-port
+# extract assets from your ROM first (see docs/building.md), then:
+./build-pc.sh ntsc-final
 ```
 
----
+[`docs/building.md`](docs/building.md) has the full walkthrough for Windows,
+Linux and macOS.
 
 ## Documentation
 
-Key docs are also published as a site:
+The docs are also published as a site:
 <https://jkdansereau.github.io/goldeneye-pc-port/>.
 
 | Doc | What's in it |
 |---|---|
-| [`docs/building.md`](docs/building.md) | Full build + asset-extraction guide. |
-| [`docs/internals.md`](docs/internals.md) | Architecture, the RSP-emulation approach, GE-vs-PD engine differences, the phased plan. |
-| [`docs/porting-notes.md`](docs/porting-notes.md) | The recurring N64→PC bug classes hit during the port, with fixes. |
-| [`docs/dev/agentic-development.md`](docs/dev/agentic-development.md) | The research angle: the two-agent setup, timeline, handoff workflow, and an assessment of what did and didn't work. |
-| [`docs/dev-process.md`](docs/dev-process.md) | The investigation workflow in detail: budgets, file partitioning, the finding-log discipline. |
-| [`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. |
+| [User guide](docs/user-guide.md) | Controls, settings and files, ROM check, macOS setup, updating, emulator saves, troubleshooting. |
+| [About the project](docs/about.md) | Release history, testing status, how it was made, how it works. |
+| [Roadmap](docs/ROADMAP.md) | Open work and the known-issues table. |
+| [Building](docs/building.md) | Full build and asset-extraction guide. |
+| [Internals](docs/internals.md) | Architecture and the software RSP. |
+| [Porting notes](docs/porting-notes.md) | The recurring N64-to-PC bug classes, with fixes. |
+| [Security](docs/security.md) and [Fidelity](docs/fidelity.md) | What a release installs, and how closely it tracks the original game's logic. |
+| [`docs/dev/`](docs/dev/) | The engineering record: the finding log and development process. |
 
----
+## Contributing and forking
+
+Issues and pull requests are welcome, and so are forks: the port layer, build
+system and `tools_pc/` are MIT-licensed and exist to be extended. Read
+[`CONTRIBUTING.md`](CONTRIBUTING.md) first: it has the ground rules that keep
+the port faithful, what to check before a pull request, and what a fork is
+asked to keep.
 
 ## Credits
 
@@ -473,48 +302,69 @@ 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.
 
+**Contributors**
+
+- **dolent** (#120, #121, #122, #123), **italoarruda** (#106, #107, #108, #109),
+  **danturn** (#95 macOS, #96), **Julio C. Rocha** (#88 macOS Intel groundwork),
+  **f1zz1ec0ke** (#137 frame interpolation), **JosephAHK** (#133), and
+  **MST246** (the #125 investigation), plus everyone who filed issues.
+
 **Consultation**
 
 - **f1zz1ec0ke** ([GitHub](https://github.com/f1zz1ec0ke)): LLM consultation on model
-  tuning, agent harnesses, and agentic strategy throughout the port's development.
+  tuning, agent harnesses, and agentic strategy throughout the port's development
+  (and the author of the #137 frame-interpolation design noted above).
 
-**Tools and models used to develop the port**
-
-- Qwen 3.8 (Alibaba Qwen team), run locally from the
-  [`unsloth/Qwen3.8-27B-GGUF`](https://huggingface.co/unsloth/Qwen3.8-27B-GGUF)
-  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).
-
----
+The models and tools used to develop the port are listed in
+[About the project](docs/about.md#tools-and-models-used-to-develop-the-port).
 
 ## Legal
 
 This is a non-commercial fan preservation/research project, in the same
 category as the many other N64 decompilation and native-port repositories on
-GitHub. It follows the same conventions they do:
+GitHub. It is **not affiliated with, endorsed by, or sponsored by** Nintendo,
+Rare, Microsoft, Valve, Apple, MGM, Danjaq, EON Productions, or any rights holder in
+GoldenEye or James Bond. "GoldenEye 007", "007", "James Bond" and related
+marks belong to their respective owners; they are used here only to say which
+game this port runs. No official logos, box art, or marketing assets are used.
 
-- **No ROM and no game assets are distributed**: not in this repository and
-  not in any release. Textures, audio, models, level data and in-game text are
-  extracted from a ROM *you already own*, on *your* machine, at build time.
-- The repository is a fork of the public
-  [GoldenEye 007 decompilation](https://github.com/n64decomp/007) and inherits
-  its contents unmodified (see [`NOTICE`](NOTICE) for what that includes).
-- 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](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
-  build, yours or ours, is useless without a ROM you supply.
+### What the download contains
 
-This project is **not affiliated with, endorsed by, or sponsored by** Nintendo,
-Rare, Microsoft, MGM, Danjaq, EON Productions, or any rights holder in
-GoldenEye or James Bond. If you are a rights holder with a concern, open an
-issue and it will be addressed.
+- **The engine:** the `port/` layer plus the compiled decompilation.
+- **Runtime libraries:** SDL2 (and SDL3 on macOS) and zlib under the zlib
+  license, the MinGW runtime on Windows, and the GCC C++ runtime on macOS
+  (GPL-3.0 with the GCC Runtime Library Exception); their licenses travel in
+  the download.
+- **The one-time asset tool**, which reads your ROM on your machine.
+
+It contains **no ROM and no game assets of any kind**. Any build, yours or a
+release, is useless without a ROM you supply.
+
+### What happens on your computer
+
+Textures, audio, models, level data and in-game text are extracted from a ROM
+*you already own*, on *your* machine, the first time you start the game. The
+port has no network access unless you turn on the opt-in *Check for updates* option (`Game.CheckUpdates`, off by default). When on, it makes one HTTPS request per launch to GitHub's releases API to look for a newer release (GitHub sees the request and your IP, as with any web request), never downloads or installs anything, and never uploads anything.
+
+### This repository
+
+The repository is a fork of the public
+[GoldenEye 007 decompilation](https://github.com/n64decomp/007) and inherits
+its contents (see [`NOTICE`](NOTICE) for what that includes). The few
+port-specific edits inside the decompiled code are marked `#ifdef PORT`.
+
+The project mark / favicon is original *generated* art -- a generic version
+of the game's default aim cross (a circle with N/S/E/W lines crossing its
+edge), no game screenshots or logos in it.
+
+### Your part
+
+- Only use a ROM that you dumped from a cartridge you own.
+- Never ask for, link to or share ROMs or extracted game files in issues,
+  discussions or pull requests.
+
+If you are a rights holder with a concern, open an issue and it will be
+addressed.
 
 ## License
 
@@ -525,4 +375,4 @@ 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>*
+*v0.6.0 · 2026-10-13 · <a href="https://github.com/jkdansereau/goldeneye-pc-port/releases">Releases</a>*

assets/animationtable_data.h

@@ -197,7 +197,7 @@
 // These are compile time extern constants (so not "really" const), but used the same
 // as the defines above, which is to index into ptr_animation_table.
 
-#if defined(__x86_64__)
+#if defined(__x86_64__) || (defined(__aarch64__) && defined(__APPLE__))
 /* D34 (docs/dev/findings.md): on N64 this segment links at VMA 0
  * (ge007.ld), so &ANIM_DATA_x is the record's offset within the
  * animation_data segment and game code re-bases it with
@@ -207,7 +207,9 @@
  * image base, set by romdataInit); (s32)&ANIM_DATA_x then equals
  * PTR_ANIM_x exactly. Address-only: the record data itself is romCopy'd
  * from ROM into ptr_animation_table, and assets/animationtable_data.c is
- * not compiled into the PC image. Never dereference these lvalues. */
+ * not compiled into the PC image. Never dereference these lvalues.
+ * D608: the arm64 macOS image loads at the 16 TiB window base
+ * (PORT_ADDR_BASE) — same re-basing class, mechanical guard widening. */
 extern unsigned char *g_pc_animdata_base;
 #define ANIM_DATA_empty (g_pc_animdata_base[0x0u])
 #define ANIM_DATA_idle (g_pc_animdata_base[0x1cu])
@@ -572,7 +574,7 @@ extern s32 ANIM_DATA_credits_natalya_kissing;
 extern s32 ANIM_DATA_helicopter_cradle;
 extern s32 ANIM_DATA_plane_runway;
 extern s32 ANIM_DATA_helicopter_takeoff;
-#endif /* __x86_64__ (D34) */
+#endif /* __x86_64__ / arm64 macOS (D34, D608) */
 
 
 

build-pc.sh

@@ -41,10 +41,68 @@ BUILD_DIR="${BUILD_DIR:-build-pc}"
 # ninja) passes env vars through intact.
 # GE_PC_BUILD_VIA_NATIVE=1 prevents a re-exec loop.
 # ---------------------------------------------------------------------------
+# Locate the MSYS2 MinGW64 toolchain dir (cmake.exe + gcc.exe, inside an
+# MSYS2 install). Whatever `cmake`/`gcc` happen to be first on PATH is not
+# trustworthy: Git Bash's /mingw64 has no toolchain, and a pip-installed
+# cmake in a Python Scripts dir can shadow the MSYS2 one. GE_MSYS2_ROOT
+# (e.g. C:\msys64) overrides the search.
+_ge_find_mingw_bin() {
+    local c root
+    root="${GE_MSYS2_ROOT:-}"
+    [ -n "${root}" ] && root="$(cygpath -u "${root}" 2>/dev/null || echo "${root}")"
+    for c in \
+        ${root:+"${root}/mingw64/bin"} \
+        "$(dirname "$(command -v gcc 2>/dev/null || echo /nonexistent/gcc)")" \
+        "$(dirname "$(command -v cmake 2>/dev/null || echo /nonexistent/cmake)")" \
+        "/mingw64/bin" \
+        "/c/msys64/mingw64/bin"; do
+        if [ -f "${c}/cmake.exe" ] && [ -f "${c}/gcc.exe" ] && [ -f "${c}/../../usr/bin/msys-2.0.dll" ]; then
+            (cd "${c}" && pwd)
+            return 0
+        fi
+    done
+    return 1
+}
+
 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
+    _mingw_bin="$(_ge_find_mingw_bin)" || {
+        echo "ERROR: could not find the MSYS2 MinGW64 toolchain (mingw64/bin with cmake.exe + gcc.exe)." >&2
+        echo "Install it (see docs/building.md) or point GE_MSYS2_ROOT at the MSYS2 root, e.g. GE_MSYS2_ROOT='C:\msys64'." >&2
+        exit 1
+    }
+    # Failure mode 3 (AGENTS.md): the toolchain's DLL dir must be on PATH,
+    # and ahead of any other cmake/gcc. Only mingw64/bin — NOT usr/bin:
+    # from a Git Bash shell that would swap in MSYS2's cygpath/mktemp,
+    # whose /tmp is a different Windows dir than this bash's /tmp.
+    export PATH="${_mingw_bin}:${PATH}"
+    # Every path that crosses to a native process lives in the build dir and
+    # is converted with bash's own `pwd -W` — never /tmp + cygpath, which
+    # silently disagree when two msys runtimes are on PATH (Git Bash + MSYS2:
+    # the .ps1 was written to one /tmp and powershell was pointed at the
+    # other; the TMP probe likewise always read "unusable").
+    mkdir -p "${BUILD_DIR}"
+    _bd_win="$(cd "${BUILD_DIR}" && pwd -W)"
+    _bd_win="${_bd_win//\//\\}"
+    _probe="${BUILD_DIR}/.ge007-tmpprobe"
+    rm -rf "${_probe}"; mkdir -p "${_probe}"
+    # The probe is a .cmd FILE: an inline `cmd //c "... \"path\" ..."` never
+    # worked — the msys argv conversion re-escapes embedded quotes as \"
+    # (which cmd does not understand), so neither ok.txt nor bad.txt was
+    # ever written and every build took the re-exec. It also tests that TMP
+    # is WRITABLE, not merely that it exists (the failure mode is TMP =
+    # C:\Windows\, which exists). %~dp0 = the probe's own dir: no paths
+    # cross the boundary. CRLF: cmd's goto/label scan is unreliable on LF.
+    sed 's/$/\r/' > "${_probe}/probe.cmd" <<'CMD'
+@echo off
+if "%TMP%"=="" goto bad
+(echo x> "%TMP%\ge007-tmpprobe.tmp") 2>nul || goto bad
+del "%TMP%\ge007-tmpprobe.tmp" 2>nul
+echo ok> "%~dp0ok.txt"
+exit /b 0
+:bad
+echo bad> "%~dp0bad.txt"
+CMD
+    /c/Windows/system32/cmd.exe //c "${_bd_win}\\.ge007-tmpprobe\\probe.cmd" >/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
@@ -54,25 +112,30 @@ if [ -n "${MSYSTEM:-}" ] && [ -z "${GE_PC_BUILD_VIA_NATIVE:-}" ]; then
         }
         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")"
+        _here="$(pwd -W)"
+        # Windows-side toolchain paths: from the validated MSYS2 mingw64/bin
+        # found above (NOT blindly from `command -v cmake`, which in a Git
+        # Bash / agent shell resolves to e.g. a pip-installed cmake and fed
+        # the .ps1 a bin dir with no MSYS2 toolchain — the "re-exec fails
+        # in-script, works by hand with explicit paths" bug). usr/bin first
+        # on the .ps1's PATH: mingw tools may need msys-2.0.dll from there.
+        _msys_root="$(cd "${_mingw_bin}/../.." && pwd -W)"      # msys install root (bin -> mingw64 -> root)
+        _bin_w="$(cd "${_mingw_bin}" && pwd -W)"
+        _bin_w="${_bin_w//\//\\}"
+        _usrbin_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")"
+        _ps1="${BUILD_DIR}/ge007-native-reexec.ps1"
+        _ps1_win="${_bd_win}\\ge007-native-reexec.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.
+# Resolve BuildDir against the repo root, not the inherited cwd.
+Set-Location $Here
 $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"
@@ -81,6 +144,30 @@ $buildLog = Join-Path $BuildDir "ge007-native-reexec-build.log"
 # 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"
+# A PowerShell launched from an MSYS2 bash (the agent-shell case: MSYS2's
+# usr/bin first on PATH, so `env bash` is MSYS2's bash) inherits a stripped
+# ~13-var env with PATHEXT=".CPL" and no ComSpec. With that PATHEXT,
+# `& cmake.exe` silently does NOTHING: no process, no output, $LASTEXITCODE
+# stays $null (the rc=2 "did not execute" regression). Restore them.
+$env:PATHEXT = '.COM;.EXE;.BAT;.CMD'
+if (-not $env:ComSpec) { $env:ComSpec = 'C:\Windows\System32\cmd.exe' }
+# D515: same class of bug as PATHEXT/ComSpec above — a stripped re-exec env
+# can also drop PROCESSOR_ARCHITECTURE, which CMake reads to fill
+# CMAKE_HOST_SYSTEM_PROCESSOR; empty value -> empty TARGET_ARCH -> "ge007..".
+# Restore it from the machine environment (fallback 'AMD64'), and restore
+# SystemRoot/windir the same way (standard Windows vars native tools expect).
+if (-not $env:PROCESSOR_ARCHITECTURE) {
+    $env:PROCESSOR_ARCHITECTURE = [Environment]::GetEnvironmentVariable('PROCESSOR_ARCHITECTURE', 'Machine')
+    if (-not $env:PROCESSOR_ARCHITECTURE) { $env:PROCESSOR_ARCHITECTURE = 'AMD64' }
+}
+if (-not $env:SystemRoot) {
+    $env:SystemRoot = [Environment]::GetEnvironmentVariable('SystemRoot', 'Machine')
+    if (-not $env:SystemRoot) { $env:SystemRoot = 'C:\Windows' }
+}
+if (-not $env:windir) {
+    $env:windir = [Environment]::GetEnvironmentVariable('windir', 'Machine')
+    if (-not $env:windir) { $env:windir = 'C:\Windows' }
+}
 # 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.
@@ -99,8 +186,15 @@ if ($null -eq $tmpdir) { "no writable temp dir found" | Out-File $diag -Encoding
 $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
+# D515 diag: the stripped re-exec env can also drop PROCESSOR_ARCHITECTURE,
+# which CMake reads to fill CMAKE_HOST_SYSTEM_PROCESSOR (empty value ->
+# empty TARGET_ARCH -> "ge007.."). One line, cheap, useful next time.
+"env PROCESSOR_ARCHITECTURE=[$env:PROCESSOR_ARCHITECTURE] PROCESSOR_ARCHITEW6432=[$env:PROCESSOR_ARCHITEW6432] SystemRoot=[$env:SystemRoot] windir=[$env:windir]" | Out-File $diag -Append -Encoding ascii
 $exe = "$Bin\cmake.exe"
 "exe=[$exe] exists=[$(Test-Path -LiteralPath $exe)]" | Out-File $diag -Append -Encoding ascii
+# A missing exe makes `& $exe` throw (caught below) and leaves LASTEXITCODE
+# null, which used to surface only as an opaque "did not execute".
+if (-not (Test-Path -LiteralPath $exe)) { Write-Host "cmake.exe not found at [$exe] (diag: $diag)"; exit 5 }
 Set-Location $Here
 "cwd=[$([System.IO.Directory]::GetCurrentDirectory())]" | Out-File $diag -Append -Encoding ascii
 try {
@@ -128,7 +222,7 @@ if ($LASTEXITCODE -ne 0) { Write-Host "build failed (rc=$LASTEXITCODE; log: $bui
 "done" | Out-File $diag -Append -Encoding ascii
 Write-Host "cmake + build ok (native re-exec, TMP=$($env:TMP))"
 PS1
-        _ps1_win="$(cygpath -w "${_ps1}")"
+        rm -rf "${_probe}"
         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/TargetArch.cmake

@@ -6,6 +6,14 @@ function(target_architecture OUT_VAR)
     # Derive from the cross-compiler target, e.g. x86_64-w64-mingw32-gcc
     string(REGEX MATCH "^(i[3-6]86|x86_64|aarch64|arm|powerpc|wasm32)" _arch
            "${CMAKE_C_COMPILER_TARGET}")
+  elseif(CMAKE_SYSTEM_PROCESSOR STREQUAL "")
+    # D515: a stripped native env (e.g. the build-pc.sh PowerShell re-exec
+    # before it restored PROCESSOR_ARCHITECTURE) leaves
+    # CMAKE_HOST_SYSTEM_PROCESSOR / CMAKE_SYSTEM_PROCESSOR empty. Ask the
+    # compiler instead of silently producing an untagged binary ("ge007..").
+    execute_process(COMMAND "${CMAKE_C_COMPILER}" -dumpmachine
+                    OUTPUT_VARIABLE _dm OUTPUT_STRIP_TRAILING_WHITESPACE)
+    string(REGEX MATCH "^(i[3-6]86|x86_64|aarch64|arm|powerpc|wasm32)" _arch "${_dm}")
   else()
     if(CMAKE_SYSTEM_PROCESSOR MATCHES "^(x86_64|amd64|AMD64)$")
       set(_arch "x86_64")
@@ -24,5 +32,9 @@ function(target_architecture OUT_VAR)
     set(_arch "i686")
   endif()
 
+  if(_arch STREQUAL "")
+    message(FATAL_ERROR "TargetArch: could not determine the target architecture (CMAKE_SYSTEM_PROCESSOR empty and compiler -dumpmachine did not match); refusing to build an untagged binary -- the 'ge007..' bug, see D515.")
+  endif()
+
   set(${OUT_VAR} "${_arch}" PARENT_SCOPE)
 endfunction()

cmake/icon/ge007.rc

@@ -0,0 +1,4 @@
+/* Windows executable icon (Explorer / taskbar).
+ * Original crosshair mark generated by tools_pc/make_icon.py (cmake/icon/
+ * ge007.ico) -- same art as the site favicon (docs/img/icon/). */
+IDI_ICON1 ICON "ge007.ico"

docs/404.html

@@ -0,0 +1,20 @@
+---
+title: 404
+description: Page not found.
+layout: default
+permalink: /404.html
+---
+
+## 404
+
+This page doesn't exist. The site's real pages are linked from the
+nav: [home]({{ '/' | relative_url }}) ·
+[documentation]({{ '/documentation' | relative_url }}) ·
+[building]({{ '/building' | relative_url }}).
+
+*Note for anyone following a moved link: the old "under the hood" page now
+lives at [documentation]({{ '/documentation' | relative_url }}).*
+
+<!-- Links use the | relative_url filter on purpose: a 404 page is served for
+     ANY unknown path, so plain relative links would resolve against the
+     requested (dead) URL instead of the site root. -->

docs/ROADMAP.md

@@ -0,0 +1,357 @@
+# Roadmap and open items
+
+**This is the single tracker for high-level work on the port.** If an item
+is not here, it is either done or not planned. The README's *Known issues*
+and *Roadmap* sections are short summaries of this file. Root-cause detail
+for each `Dxx` lives in [`dev/findings.md`](dev/findings.md) (find it via
+[`dev/findings-index.csv`](dev/findings-index.csv); that index is generated,
+first-line-only, and can lag the entry tail, so read the entry).
+
+Last full triage: 2026-09-29. Sources: the findings log, all GitHub issues,
+PRs and releases, every local backlog/plan/roadmap note, `HANDOFF.md`, all
+local and remote branches, and known community forks.
+
+## How to use this file
+
+- **One row per item.** Link the `Dxx` and/or GitHub `#issue`. Keep detail
+  in the finding, not here.
+- **Status vocabulary:** `open` · `partial` · `verify` (fixed, a live check
+  is owed) · `parked` (work exists on a branch or patch, not merged) ·
+  `decision` (blocked on a maintainer call).
+- **When an item closes, delete its row.** The history is kept in the
+  finding and in git. Do not strike rows through. Struck rows are what made
+  the old backlogs unreadable.
+- **New work goes here first.** Do not start a new backlog, roadmap or
+  plan-of-record file. A design doc for one item is fine; link it from the
+  row and delete it when the item lands.
+- Release scoping (which items go into which version) happens in the
+  release notes, not here.
+- The **release gate** (what must be green before pushing / publishing a
+  release) is kept as a local working note — `docs/dev/notes/RELEASE-BLOCKERS-v050.md`
+  (gitignored, like the other P-pass reports). Keep it current; don't fork a
+  second copy of it into the tracked tree.
+- **Known issues** (the player-facing subset) live in the table below. The
+  README links to it and does not duplicate it.
+
+## Goal and definition of done
+
+**Feature complete and faithful to the N64 original.** Every mode and
+region the cartridge ships should work and behave 1:1 with the N64,
+checked against an accurate emulator (1964/GEPD) or real hardware. On top
+of that sits a **modern-remaster layer** (the bar set by Nightdive's
+Quake/Turok remasters, the XBLA remaster and GE+/Dab's mod). It must never
+change game logic by default, and it must always be possible to get back
+to the original look and feel (see the *Original N64 preset*, D440).
+
+The port is **feature complete** when all of these hold:
+
+1. Every solo mission (all 20 plus the credits) is completable at every
+   difficulty, on Windows and Linux.
+2. No crash on any level under normal play, on either platform.
+3. Audio is complete and faithful: music, positional SFX, menu and weapon
+   sounds.
+4. Cutscenes play correctly (camera, actor positions, timing).
+5. AI locomotion and pacing match the N64.
+6. Input feels like GoldenEye on a controller, and like a modern FPS on
+   mouse and keyboard.
+7. Rendering has no visible defect versus 1964/GEPD at default settings,
+   apart from the port's deliberate modern defaults.
+8. **Multiplayer (2–4 player split-screen) works.** It is the largest item
+   left (§1).
+9. **PAL and JP ROMs work** (§1, pending a decision).
+
+**Exit gate:** a full two-platform campaign playthrough at more than one
+difficulty, plus a split-screen session, on a build with the §3
+verification debt cleared.
+
+Where things stand (2026-10-01): 1–7 hold for NTSC-U, with the small
+accuracy gaps in §2. 8 is merged on `release/v0.4.1` (3P/4P with real pads
+owed). 9 is open (Stage B). **Parity rule (2026-09-30):** every released
+platform carries the same gate: a full 21-level sweep plus a campaign pass.
+
+## Order of work (decided 2026-09-30)
+
+Work continues on `release/v0.4.1`, **shipped as v0.5.0 (named 2026-10-03,
+cut staged 2026-10-05, maintainer)** — the docs, golden set (both platforms,
+63 frames each) and tooling are complete; the P11 squash + tag + push is owed
+maintainer consent (push checklist: `dev/notes/PUSH-TASKS-v041.md`). There are
+two stages:
+
+**Stage A: now → the pre-1.0 build**
+1. Clear the §3 verification debt.
+2. Split-screen (§1): keep working and testing until it is good.
+3. `All unlocked` rework (§5a).
+4. D357 settings values (§5a), plus the restart button.
+5. Outside PRs (§5a), in the proposed order once the maintainer approves it.
+6. Pillarbox with the exact original aspect for the Original N64 preset (§5a).
+7. Platform parity: re-base the golden baselines and extend them to both
+   platforms (§7), then run the gate on each platform.
+8. Investigate and triage every §2 fidelity gap to fix or accept. Do not
+   leave any of them as "open, unexamined".
+
+**Stage B: pre-1.0 build → 1.0**
+1. PAL/JP (§1). It goes last on purpose, so that region-specific
+   regressions are easy to isolate and unwind.
+2. macOS/ARM: merge the `macos-arm64` branch (§4), with the D441 census
+   (store-to-u32 tagging) and a high-arena test. (2026-10-08 decision: an
+   *experimental* arm64 macOS build ships in v0.6.0; the merge-to-main is
+   still the post-1.0 step here. Scope is Apple Silicon — the x86_64 path is
+   unverified and out of release scope.)
+3. The exit gate on every shipped platform.
+4. Remove the temporary scaffolding (§7).
+
+**Next (decided 2026-10-03, after the Birdman64 comparison; local note `BIRDMAN64-LESSONS.md`):**
+1. D441 census: **done 2026-10-03** (§2).
+2. Fix the listed sites as mechanical, build-checked batches on a cheap
+   worker; the lead reviews every diff (§7). **Batches 1-5 done
+   2026-10-03.** Next: the tier-1 sweep over every level with a seeded
+   frame compare, then further batches from it.
+3. Scripted-playthrough harness: moved to post-1.0 (maintainer
+   2026-10-04; revisit with newer models) (§7).
+
+## Known issues
+
+What a player will notice in the current release. **This table is the
+single list:** the README links here instead of keeping its own copy. When
+an issue is fixed and released, delete its row. When a new player-visible
+issue is confirmed, add a row here (and its tracking row in the sections
+below).
+
+| Issue | Impact | Workaround | Tracking |
+|---|---|---|---|
+| PAL and JP ROMs aren't supported in release packages | NTSC-U only | Use an NTSC-U ROM. Both regions convert, build and boot from source (D258, D487, D488; see `docs/building.md`); packaging (per-region exe, CI matrix, converter region check) is still open | D258, #85, §1 |
+| Changing Aspect ratio in a level (mostly Fill window to Original or a forced ratio) can briefly glitch the gun / hand model, rarely | Cosmetic, one-off | Change the ratio from the front-end PC Options, or accept it | D509 (frame hold fixed the common case; the rare remainder is logged, not investigated) |
+| No Intel macOS or ARM Linux builds (the macOS download is Apple Silicon only, experimental and not notarized) | Platform | — | #88, #95, #101, #154, §4 |
+| Steam Deck at 90 fps: centre firefights in Bunker 1/2 drop several fps; Jungle feels slightly less smooth than other levels | Brief FPS drops | Frame cap 60 for those levels | D583, D585 (present thread, v0.7.0), D614 |
+| Cradle's turret explosions may draw wrongly | Cosmetic | None yet | Deck per-level pass (2026-10-10), not investigated |
+| Windows: the picture can look hazy for a moment after alt-tabbing back; fast repeated alt-tabbing recovers slowly | Cosmetic, temporary | It settles on its own | D578, alt-tab row in §4 (v0.7.0) |
+| Saves from v0.4.0 and earlier can hold fake unlocks from `All unlocked` | Save data | Not repaired automatically. Since v0.5.0 the option never writes the save; keep a backup of `data/ge007.eep` from before you used it | D442, D387 |
+| The first frame of a level takes a little longer while its textures upload | Brief FPS-counter dip | None needed | D475, D480 |
+| Far objects almost fully in fog are now hidden as on the N64, except in widescreen, where the wider view can still show a faint distant building edge (e.g. Surface's dish from the start area). 4:3 matches the N64 | Cosmetic | None; higher Draw/LOD distance shows more | D503, §5c |
+| Windows: an occasional one-off render-thread stall can trip the "no frame rendered for N ms" watchdog (rare; observed once, during heavy `GE_`-debug I/O) | Brief one-off stall / recover | Normal play (no `GE_` dump probes) is unaffected; a flake, not a deterministic hang | D593 (root-cause owed: probe I/O cost vs a genuine render-thread hang) |
+
+---
+
+## 1. Feature completeness vs the N64 cartridge
+
+| Item | Status | Refs | Notes |
+|---|---|---|---|
+| **2–4 player split-screen multiplayer** | verify | #99, D416–D423, D496 | Merged 2026-10-01. D417 Rule-2 approved. **Maintainer playtest 2026-10-03:** 2P and 3P with real Xbox and PS5 pads, handicaps, teams and game modes all good (D496 fixed an uninitialised weapon-text buffer). **Still owed:** 4P with real pads, pads-only mode, MP audio, D422 centred aim live on P2+ (`AimMode = 1`), D428 sway on P2+. |
+| **PAL and JP ROM support** | partial | D258, D487, #85 | **2026-10-02: both regions convert, build and boot** (D258 byte-verified against real PAL and JP ROMs); both play Dam with no crash; NTSC-U unchanged. Build: `BUILD_DIR=build-pal ./build-pc.sh pal-final` / `build-jpn ... jpn-final` with `data/ge007.<region>.z64`. D487, D488 fixed (PAL frame height, TV type). **Open:** full runtime passes per region (levels, menus, audio, saves; PAL 50 Hz feel incl. the D427/D451/D486 gates; EU-only text); packaging (per-region exe names, CI matrix, converter region gate, #6). ROMs: `ge-port-reference/1964_GEPD_Edition/ROMs`. #85 needs reopening or a fresh tracker when this ships. |
+| Drop-in ROM converter, remaining parts | decision | #6, [`dev/release-dropin-rom-plan.md`](dev/release-dropin-rom-plan.md) | NTSC-U drop-in shipped. Left: per-region output names and re-exec guard (with PAL/JP), native C emitters to replace the PyInstaller converter. |
+| Cut content (TCRF weapons/items) | decision | [`dev/CUT-CONTENT-BACKLOG.md`](dev/CUT-CONTENT-BACKLOG.md) | Not part of the shipped game. Tier 0 already works via the debug/cheat menus. Tier 1 (config-toggle grants) is small and port-only. Tier 2/3 (placing props, re-enabling unused MP maps) need game data changes and are out of scope for this repo. **2026-10-09 (maintainer):** the Tier-2/3 items whose data is already in the ROM — the 8 cut MP maps and the extended MP roster (backlog §D/§F) — are in 1.0 scope as a mod-fork branch (the `front.c` table edits touch `src/game`, non-negotiable #2), shipped through the mod scaffolding (§5a). Prop placement stays out. |
+
+## 2. Accuracy (behaviour differs from the N64)
+
+| Item | Status | Refs | Notes |
+|---|---|---|---|
+| Third-person Bond offset residual | partial; intro puppet explained (2026-10-02) | D173, D292 | Mostly fixed. On the level-start puppet the variance is tick/PRNG-dependent idle timing (D13 class, faithful, no sign-off requested); one 1-frame first-tick Y transient is untraced. If the residual is seen elsewhere (cutscene body model), the maintainer should note where. |
+| AI awareness follows two non-default render settings | fixed 2026-10-06 (D565: Fog distance floor 100; AI fog cull rescaled to the game's FOV) | D565, D466, D468, D540, D222 | AI review of v0.4.0..v0.5.0 (interpreter, movement/timing, visibility/combat): no regression at shipped settings (Draw 2.0x, Fog 1.0x, FOV 60, native widescreen). Two leaks of player render settings into AI awareness remain: **(1) `Video.FogDistance` below 100** shrinks the far clip (`bgfog.c fogLoadCurrentEnvironment`, clip = FarFog x min(Fog, Draw)). AI on-screen checks require the render `PROPFLAG_ONSCREEN` (`drawdistgameplay.c portPropGameplayOnScreen`), so guards beyond the shortened clip stop counting as on screen; at Draw 1.0x `portD466Active()` is off and sight range (`fogGetScaledFarFogIntensitySquared`) shrinks too. Effect: guards notice Bond / on-screen triggers fire later than the N64. Fix (shipped): `Video.FogDistance` is floored at 100 (`video.c` registration, so 50/75 in an ini clamp to 100 on load; F10 slider `uiMin` 100); 100-800 only extends, which D466 already keeps off gameplay. **(2) FOV other than 60 (`Video.FovScale` != 100, or native widescreen off at a wide aspect)**: the gameplay fog-cull `propobj.c portSub7F054C58Gameplay` uses `getPlayer_c_lodscalez()`, which grows with the rendered FOV (D222), so at a wider FOV far fogged positions drop out of the AI on-screen verdict sooner (narrower: later). Fix: divide out the port FOV factor (as `portFovYScaleFactor`), keeping the game's own zoom FOV changes. Minor at defaults: the D466 verdict reuses the extended pass's room screen bbox (`posIsOnScreen`); at Fog 1.0x the clip is the authored far, so the two passes match. D491 (room-list portal seeds) and D431 (light-fixture hit scoring) were checked: both restore N64 data reads and only move AI toward the N64. |
+| Dam ending cutscene | done (2026-10-06) | D526, D552 | Railing/grate transparency faithful (D526); first-shot swivel restored (D552, maintainer-verified). |
+| Title-screen attract demo runs too fast; F10 box rescales while it plays | backlogged (after v0.5.0, maintainer 2026-10-04) | D87 (ramrom file struct); timing: D13, D248, D427, D451, D486 | **Reported 2026-10-04 (live pass):** attract plays visibly too fast; not investigated. Lead: it is a ramrom demo replay whose recordings carry a per-frame tick count, which the port's 60 fps / 1-tick pacing may override. Rule out PC causes, then compare with 1964. Same pass: the F10 box briefly rescaled during the demo (not reproduced; candidate fix = overlay reads fast3d's native viewport, parked locally). |
+| Sniper rifle: zoom level and speed vs 1964 | verify | #136, D484, D485, D494 | Crouch: **D494** (2026-10-03) makes the PC crouch key crouch/stand freely with the sniper, as GEPD does (superseding D483's freeze); maintainer-verified. Zoom level (D484, 20 -> 7 degrees) and speed (D485, tick-scaled, Rule-2) fixed 2026-10-02. **Owed:** 1964 A/B of zoom level and speed; close #136 after it. |
+| Geometry disappears when hugging a wall (dark close-range smear) | verify (fixed 2026-10-09; golden sweep owed) | #150, D579, D543 | **Root cause (2026-10-09):** a v0.5.0 regression from D543, the CPU near-plane clip. It cut at the near plane (`z = -w`), but GL runs with `GL_DEPTH_CLAMP`, so geometry between the eye and the near plane is meant to be drawn (as on the N64; 1964 shows the wall). Hugging a wall put it in that band and the clip deleted it. Confirmed by one `GE_NEARCLIP=0` run (no see-through). **Fix:** the clip now cuts at the camera plane (`w = 0.01`), and clip-created vertices take fog at `max(z/w, -1)` so the D553 near-plane haze is unchanged. Maintainer-verified at the Dam gate in 16:9 with the floor haze intact. The earlier cull/ucode/guard-band investigation was a dead end (see D579 and dev-process §8 "Regression triage first"). **Owed:** one 21-level golden sweep. Diagnostics stripped (last one, the `src/game/bg.c` probe, removed 2026-10-10). The `any_w_neg` no-cull caused the Cradle catwalk flicker; mixed-w triangles now get the homogeneous facing test (D584), Dam gate wall hug re-checked clean. |
+| Decal shadows flicker at high FPS (Dam, Cradle catwalks) | closed 2026-10-09 | D578 | Maintainer compared Dam against 1964 (GEPD): the shadow look there is essentially the same, so it is faithful, not a port bug. The flicker seen during the D578 switch testing is not considered an open issue. Reopen if the Cradle catwalk flicker shows up on the shipped default. |
+| 120 fps + VSync on G-Sync/VRR: OLED brightness flicker (present cadence); Deck 90 smoothness | PC fixed 2026-10-09; Deck 90 good on most levels (per-level pass 2026-10-10, `feat/d583-deck90`, local); open items in the per-level row below | D583, D578 | PC: continuous present grid snapped to tick/N, 8-slot present ring, draw-time-based ready, present-before-draw (120.0 presents/s, 99%+ gaps 7-9.5 ms, OLED by eye OK). Deck: false turn-detection redraws removed, exact frames drawn once, turn softening applied at frame start, room scissor = union of replayed and game box, projections paired by nearest (draw peak 8-10 -> 3-5 ms, 88-90 presents/s; maintainer by eye OK); no post-swap glFinish under gamescope (present 3.3 -> 0.3 ms); set-change limit 60%. Not yet a smooth 90 in crowded fights (maintainer: "not perfect for the release yet"): set-change holds and turn-softening steps remain; cut detection replaced the matrix set-change check (crowd fights "good now"). Next: re-tune softening (Dam tunnel by-eye), per-level Deck pass, Dam truck brief flicker (Deck, 2026-10-09), Aztec M16 viewmodel flicker, rare dead-body flicker before fade-out, level-start load stutter, gamescope flip-time stats. PC 120 re-checked 2026-10-09 (120.0/s, 1% exact). Owed: VSync-without-G-Sync check, per-level Deck pass + 90 fps performance validation across levels (only Dam exercised). **2026-10-10 Deck Dam run (ac50865d):** 9.5-12 ms gaps 98-99.7% per 10 s window, 0-5 dropped, draw peak 2.1-6.3 ms, late softened (redrawn) 8-56 per 10 s, maintainer by eye: good, no tunnel holes. **Turn-softening re-tune closed as not needed** (the redraw count no longer costs presents). **2026-10-10:** per-level Deck pass done (next row); the older "Next" list above is superseded by it, except the still-unexplained Dam truck / Aztec M16 / dead-body flickers (captures owed), level-start stutter, gamescope flip-time stats and the VSync-without-G-Sync PC check. |
+| Deck per-level pass findings (2026-10-10, maintainer, `ac50865d`) | open | D583, D578 | Overall very strong. (1) **Bunker 1/2 centre firefights drop 5-10 fps:** the log shows a ~70-frame run of 2-pass frames drawing 11.2-12.5 ms (~5.6 ms per pass, over the 11.1 ms 90 Hz budget); game side is idle (work ~0.14 ms), so this is draw cost, a real-optimization job (profile the pass), not pacing. **2026-10-10 measured (SLOW line counters):** ~550-800 batches per pass at ~6 us each (~4-5 ms per pass); texture lookups ~1.2 per batch, few misses; a softened restart made fight frames 3 passes. Refuted: same-texture rebinds (reverted). Landed: late-soften budget gate (no restart when n+1 passes exceed 3/4 tick; `nobudget` = old): 3-pass frames mostly gone, but drops remain (2-pass frames to ~13 ms; maintainer: still up to ~10 fps drops). **2026-10-10 late (D583 addendum "present scheduling"):** NOT draw cost: not CPU-bound (perf), not the GPU clock (1600 MHz manual: same), not the VBO upload (ring: within noise). 72% of the long present gaps are a due present stuck behind the single worker's next draw. **2026-10-10 review: present thread (D585) PARKED for v0.7.0** on local `wip/d585-present-thread` (opt-in, offscreen frames black): a second shared GL context + thread on every platform, macOS included, for one Deck scenario was too much risk for a point release. v0.6.0 ships with the Bunker fight drops as a known Deck issue. **2026-10-10 (D614):** texture-cache thrash measured in the fight (CI8 keys hashed leftover palette entries); fixing it cut re-imports 60-70% but did not change pacing: reverted, not the cause. (2) **Jungle/Egyptian read 90 fps but do not feel fully smooth:** motion histogram shows 3-10 hold+jump pairs per 10 s (~0.5-1 visible hitch/s) even with 0 dropped; next step is to log which decision (room-change exact, late exact, pre-soften) precedes each hold. **2026-10-10 hold-cause log (6d7aa851), Jungle:** every hold is an exact fallback (1-7 per 10 s), almost all REACH (a room the previous frame drew and this one dropped); `noreach` removed them with no visible holes in Jungle but did NOT change the feel (maintainer: "not significantly"; Egyptian and other levels feel better). So holds are not the Jungle issue and the pacing stats look like the good levels. Untested lead: content refreshed only at the game tick inside a 90 Hz blended view (the sky is always this frame's; objects not paired), most visible outdoors. Needs a focused look, not more switch rounds. (3) **Clip-through at long range (FIXED 2026-10-10):** Frigate terminal shadow through a wall, Statue Valentin through his crate; above 60 fps only. Cause: the D578 in-between depth-clip widening (`gfx_interp_conservative_clip`, heading-dependent depth remap). Gone on the Deck with `noclip`; now default OFF (`interp_clip_off`; `GE_INTERPCLIP_ON` / `clipon` opts back in). Owed: Dam distant-ridgeline check without it (the reason it was added; maintainer deferred it 2026-10-10). (4) **Cradle catwalk shadow flicker (FIXED 2026-10-10, D584):** a regression from D579 at every frame rate (bisected on the Deck); mixed-w triangles get the homogeneous facing test again. (5) **Cradle turret explosions may draw wrongly** (maintainer, 2026-10-10): noted only, not investigated. |
+| Native widescreen: stale watch pixels at the sides of 4:3 menus (mission folder, file-select background, main menu after exiting from the watch) | fixed (2026-10-10, ac50865d; maintainer Deck check OK) | D579, D334 | Not interpolation (present with `allexact`). D579 (#150) stopped the per-frame canvas color clear to match N64 persistent VRAM and clears only the letterbox bars; with Native widescreen the canvas is the full 16:10 window, but 2D menus draw only their 4:3 core, so the canvas sides are never drawn or cleared and keep the watch. Fix direction: keep the no-clear where the game draws, clear the widescreen extension outside the 4:3 core (or on 2D/menu frames). Regression from D579 (this week), not in v0.5.0 releases. **Fix 2026-10-10 (`gfx_frame_body`, D579 follow-up):** outside a running stage (`current_menu != RUN_STAGE`) with native widescreen wider than 4:3, the canvas strips outside the centred 4:3 core are cleared to black before the DL, like the letterbox bars; in-stage frames keep the no-clear. |
+| Dam: grate decals vanish behind a sliding edge, wall lighting shifts with view; guard tower window/doorway view of the outside glitches | closed 2026-10-09: faithful | D583 | Present with every present exact (`allexact`) and in v0.5.0; maintainer checked 1964 (GEPD): the exact same behaviour. Original-game portal/culling artefacts, not port bugs. Candidate for the opt-in fixes row below. |
+| Opt-in fixes for original-game rendering bugs (QoL) | idea, post-1.0 (maintainer 2026-10-09) | D583 | Maintainer: a nice QoL feature would be optionally fixing artefacts the original game has, e.g. the Dam wall grates cut by a sliding portal edge and the guard-tower window/doorway outside view (D583 row above), and overlapping 2D transparent textures on Cradle sorting wrongly (also in the original). Must stay off by default (fidelity is the default) and live in `port/` or an explicit option; game-logic changes would need Rule-2 sign-off. |
+| Exclusive fullscreen picks the wrong resolution with NVIDIA "OpenGL present method = Prefer native" | open (v0.7.0, maintainer 2026-10-10) | D583 | Seen 2026-10-09 while bisecting D583; borderless is fine. Probably exclusive mode switches to the ini Width/Height instead of keeping the desktop mode. Not investigated. |
+| Deck golden captures are 1280x800 when interpolation is on | open (v0.7.0, maintainer 2026-10-10) | D578, D283 | With Auto FpsCap on the Deck's 90 Hz screen, GE_PCDUMP writes 1280x800 frames against the 640x480 Deck goldens, so every frame fails to compare (and the sweep prints PASS with "stems don't match", which is not a pass). **2026-10-11:** the false PASS is fixed: `framediff.py` exits 3 on a size mismatch and `verify.sh` reports it as REGRESSION ("not compared"); the capture-size fix itself is still owed. `verify.sh` now pins `Video.DeckPresetApplied = 1` (D283 preset). Fix: dump at the window size, or re-capture the Deck goldens once. |
+| Crash on save slots 1/3/4, plus a host BSOD (fltmgr.sys) | decided | #94 | Needs a repro. Two maintainer retest requests (v0.3.0, v0.4.0) got no reply. Likely D299/D301 (save-slot crash, fixed) and D344 (BSOD on exit, fixed). **Decided 2026-10-01: close as stale when the release ships**, pointing at D299/D301/D344; no GitHub activity before then. |
+| Authored mip chains not sampled for explicit-LOD textures | post-1.0 | D323 | Distant textures use driver mips instead of Rare's hand-authored chain (heaviest on Statue/Aztec). Parked as a fidelity enhancement. **Decided 2026-10-01:** after 1.0, together with the LOD-fraction approximation as one "real RDP LOD" project. |
+| Approximations in the software RSP | post-1.0 | `gfx_pc.cpp` `G_CCMUX_LOD_FRACTION`; D323 | The LOD-fraction CC input is an eyeballed approximation, bundled with D323 as one "real RDP LOD" project after 1.0 (2026-09-30 triage). **WrapFix settled 2026-10-02:** the maintainer checked the Depot building ceilings against 1964 with the default `Video.WrapFix = 0` and they look right, so the default stays off (the opt-in knob remains; RC3/D167). |
+| Latent 64-bit ABI hazards | partial | D441, #107, #108; AUDIT-M6 `struct player`/`struct hand` raw offsets (porting-notes §A1) | **State (2026-10-03, D441):** complete census (local `scratch/d441/`; many hits are intentional `(s32)&ANIM_DATA_*` offsets, D34); 17 files widened to `uintptr_t` under `#ifdef PORT`; 35 sign-extension sites fixed; CI ratchet `tools_pc/abi_ratchet.py` (baseline 389); arena windows centralised (`port/include/portaddr.h`); tier-1 high-arena build (`GE_HIGHARENA_BASE=0x90000000`) runs the menu and `-level_09` pixel-identical to default. D478: nothing live on the current layout; the rest would bite only on macOS/ARM/ASLR. **Sweep (2026-10-05):** tier-1 all-level sweep done, 21/21 PASS, no fix batches, ratchet unchanged (389), recipe in the D441 entry. **Owed:** tier 2 (above 4 GiB; u32 slots widened); store-to-u32 vs arithmetic-only tag per site (`portHostToN64` under macOS port_addr); `mema.c` widening (D453); `initanitable.c` heap slots; GE_DETERM wall-clock timers (D117 follow-up, blocks using determinism mode for frame gates). **#108:** widening the `sndPlaySfx` bound disables the guard everywhere; prefer a range check — **done in v0.6.0 as D573** (address-window check). |
+| Port-memory vertex/pool bounds hardening | post-1.0 (decided; not a v0.5.0 blocker) | D545, D549 | D545 (rockets through floor, fixed) left one residual: ~1 dropped rocket in ~60 spawns (Archives, akimbo), consistent with the room-pool hypothesis (`bgBuildRoomVtxBounds` allocation failing leaves no bounds) but unproven; D549 (same stack-overflow class in grenade/knife/object throws) is fixed. Both shipped. Proposed hardening: a port-memory bounds table validating vtx/pool pointers against the known arena windows. |
+
+## 3. Verification debt (fixed; a live check is owed)
+
+A single campaign pass with these on the checklist would clear most of them.
+
+| Item | Refs | Check |
+|---|---|---|
+| Presets: Original N64 / Port defaults | D440 | Press both rows in F10 and in the front-end PC Options with a mouse and a pad; draw distance applies from the next level load. `GE_OPTIONTREEPROBE` already fails on the base commit (separate look). |
+| Probe strip (2026-09-30) | D245, D302, D318 | Frigate or Dam water/sky A/B against the previous build (the s16 sky path was removed); one Facility playthrough to confirm the D318 watchdog stays silent. |
+| Infra fixes | D179, D515, build-pc.sh, crash.c, CI | 2026-09-30 re-exec no-op (PATHEXT) fixed; 2026-10-04 empty-arch-tag bug (D515) fixed headless (details in AGENTS.md) — confirm on your next fresh-dir build. **Owed:** `./build-pc.sh` from a genuine MSYS2 login shell; the next CI run (pinned actions, workflow input check). `GE_CRASHTEST=6` shows resolved frames. The romdata `VirtualAlloc` failure path now fails boot instead of falling back to the heap copy: confirm you want that. |
+| Light-fixture hit-type reads (impact sound + sparks) | D434, #119 | Shoot fixtures on Bunker and Caverns. |
+| Dam/Caverns water animation | D465, #127 | Fixed 2026-10-01 (16-byte `Gfx` raw-index write). Maintainer: still "slightly faster" than 1964 on Dam; measured rate equals N64 within 0.1%. Optional objective check: time ten shimmer cycles on both (expect ~26 s). |
+| End credits after Cradle | #129 | Did not reproduce on `release/v0.4.1` 2026-10-01 (maintainer finished Cradle on Agent, credits played, clean exit). Close #129 as not reproducing when the release ships. |
+| v0.4.1 batch (unreleased; fixes live on `release/v0.4.1`) | D424–D432; #114 fire rate, #115 tank-crush audio loop, #116 tank movement, #117 sway, #118 GL recoil, #119 light fixtures | All user-verified against GEPD/1964 on 2026-09-29. Close the issues when it ships. |
+| FOV-scale edge culling | D222 | Max FOV, pan across NPCs at the screen edge. Also audit the FOV/aspect terms in `camIsPosInScreen` and `c_lodscalez` for the Surface dish (D503 residual). Maintainer decision owed: expected widescreen behaviour vs fix. |
+| Draw/LOD 800% | D503 | Draw/LOD distance ceiling raised 400% → 800% (2026-10-04). Owed: at 600-800, check far-field z-fighting on Dam (tunnel), Surface and Jungle; on Aztec or Streets, grep the log for the D500 vtx-pool budget line. If z-fighting shows, lower the ceiling to 600 rather than touching depth precision. |
+| Water pulse, Surface 2 | D229 | Frigate is verified. Only the Surface 2 by-eye check is owed. |
+| Linux save/config path when launched outside the game dir | D256 | Save-flow check on Linux. |
+| Settings/F10 batch | D356, D358, D361, D363, D374, D406 | Live accept of each item in the F10 overlay. (D377–D379 residuals were waived.) |
+| Controller feel | CONTROLLER-INPUT-PLAN Wave A, D204 | Per-stick deadzone/smoothing feel on a pad and on Deck; D204 tempo by ear; `Input.RumbleScale=0` silences rumble. |
+| Widescreen HUD at 21:9 | D334/D335 | One ultrawide HUD playthrough. |
+| Older "owed" notes | D371, D372 | **Bookkeeping done 2026-10-01:** D150, D177, D264 ticked off against the 2026-09-28 campaign sign-off; D369 accepted in use. Still owed: D371 (GEPD key-layout preset + reload/crouch bindings: select the preset in F10 and play a level). (D372 low-end preset: no further effort; low-end work is real optimizations, see §4.) |
+
+## 4. Platform
+
+| Item | Status | Refs | Notes |
+|---|---|---|---|
+| macOS (Apple Silicon) / ARM64 Linux | open (target 0.9.0/1.0, maintainer 2026-10-02; **scope 2026-10-08: Apple Silicon only, experimental in v0.6.0**) | PRs #88, #95; #101 | Outside drafts, parked until after 1.0. **Address model decided (2026-09-30): port_addr (#95)**, a `portN64ToHost`/`PORT_N64PTR` chokepoint with a `PORT_ADDR_STRICT` validator. The integration branch is `macos-arm64` (renamed 2026-10-08 from `macos`; local + Forgejo mirror) with #88 (merged), #132 (merged) and #95 (**merged 2026-10-10** — record merge `903095c9` in the v0.6.0 line + base merge `f87f4bcd`; the stale GitHub `origin/macos` mirror was deleted 2026-10-10, its lineage stays reachable via the record merge); nothing merges to `main` before the post-1.0 pass. **Scope decision (maintainer 2026-10-08): ship Apple Silicon only** — the x86_64 macOS path (#88) stays in-tree (identity at `PORT_ADDR_BASE==0`) but was **never verified on Intel hardware** and is out of release scope; **arm64 macOS is planned as *experimental* in v0.6.0** (the first release carrying a macOS build; owed before the release: D602 diagnosis, D600/D601 live confirmations, and a release-notes experimental marker on the `macos-arm64` artifact). **#131 (self-hosted sweep scaffold) closed 2026-10-10** — its content shipped in the v0.6.0 CI; the fork-friendly rework is parked locally (`park/ci-selfhosted-sweep-131`, `2fb8e52e`) for the v0.7.0 self-hosted runner item. **Status 2026-10-08:** D590 fixed the deterministic Windows `load_bg_file` SIGSEGV (the D588 bug class on the full-width `bg_addr_t` — plain casts, 5/5 Dam runs clean; the D589 A/B's Win side is unblocked); **D589's rev32 is ROOT-CAUSED as D591**: the decode-time pool is 134/134 byte-identical Mac/Win (the writer side is clean — the “pool holds the rev32” line is retired), and the reversal happens at the *import* — `gfx_tex_source_is_c_array` (`port/fast3d/gfx_pc.cpp`) mixes host-space and N64-raw-space in its range test, so on arm64 macOS (`PORT_ADDR_BASE=16 TiB`) every DRAM/cart texture source mis-classifies as a “C-compiled array” and `gfx_tex_normalize_source` bswaps it (a clean rev32 of the whole wide-pixel pool — the D219/M-114 pink-HUD symptom class). Fix in `9c59cbe7` (compare the host pointer directly; port-layer only, no-op at `PORT_ADDR_BASE==0`); **Windows verified byte-identical (400/400 import `r*.bin` + PPM unchanged), Mac A/B now verified 2026-10-08** (clean arm64 build at `25f92e09`: `GE_TEXN carray=0` on all probe lines, Mac `raw8` matches the Win baseline — the rev32 is gone). **D589 is now RESOLVED: the "second cause" (D592) was CLOSED as a non-issue 2026-10-08.** The "rock striping" that D592 tracked turned out to be a **false positive of a crude vertical-high-frequency (VHF) metric flagging natural rock grain**, *not* a GL-layer artifact: a `GE_TEXSTATE` GL-state probe showed the effective sampler state **and** the NPOT mip level counts are **byte-identical Win/Mac** (the Apple M3/Metal backend builds the full NPOT mip chain; the aniso extension is present on both; the NPOT rock texture gets `min=trilinear, mag=linear, aniso=4` on both sides), a 0-pink scan confirmed **D591 held**, and the **maintainer's live Mac look showed the Dam rendering clean** (no visible striping, ammo counter not pink, F10 menu fine). The NPOT `glGenerateMipmap` guard + companion single-level sampler fix (`9bed5904` / `82dbea9c`) were **reverted as dead weight** (`b80dcd08`, which also strips the `GE_TEXSTATE` probe). The genuine cross-platform symptom (the pink HUD) was **D591 (fixed, `9c59cbe7`)**. **D594 (FIXED): macOS partial input** — `GE_KEYLOG` **disproved** the cross-thread-poll suspect (WASD + LMB reach both the main-thread pump and the scheduler-thread poll); the real gap was the `actHeld` mouse gate on `current_menu == RUN_STAGE` (a forced `-level_NN` start leaves `current_menu == INVALID (-1)`, so the mouse was never read) plus the macOS `reconcileGrab` `windowFocused` gate. Fixed by matching PD's input model (in-stage = RUN_STAGE *or* INVALID; macOS grab = PD's MLOCK_ON, no focus gate) — LMB fire now works on the Mac (trackpad: LMB fire, two-finger = RMB/aim, Shift = ADS). **D595 (FIXED): the arm64-only SIGSEGV that firing then exposed** — `initResolveAnimTable` truncated the live `ptr_animation_table` host pointer to `(s32)`, dropping the 16 TiB `PORT_ADDR_BASE` → every AI hit/stagger `struck_anim` resolved to bogus low memory → crash in `modelSetAnimFrame` on the first AI hit-reaction. Fixed by reading the base at full pointer width (§A1; identity on x86_64). Both are the last input-blockers to a playable arm64 macOS build. (maintainer visual-sanity package: `scratch/d589-dam/ab3-mac/{d591_sbs_win_mac.png,d591_diffmap.png,D591-AB-SUMMARY.txt}`. `tools_pc/abi_ratchet.py` baseline refreshed for the branch. **Integration into the v0.6.0 line done (2026-10-10):** #95's `crouched_rifle` hunk and its `D420` label were dropped at integration (our #120/D445 is Line truncated
+| macOS first-launch black window (v0.7.0) | open | D581-era sweeps; logs in `docs/dev/notes/mac-first-launch-hang-2026-10-13/` (local) | **2026-10-13, v0.6.0 release download on the M3:** the cold first launch generated assets, reached the title stage (90) and then rendered no frame (`kernel heartbeat: no frame rendered`, frames=0, all game threads blocked); the next launch was clean. 1 hang in 16 launches that day (1 in 10 first launches), 0 in 7 after a reboot; neither a new binary alone nor asset generation alone reproduced it. 3 earlier sightings on 10-12. Lead: one timer mq in the heartbeat dump shows `valid=83746432/0`. Release notes carry a one-line "close and start again" tip. |
+| Pixel gate vs the Auto frame-cap default (v0.7.0) | open | D578, `tools_pc/verify.sh` | The goldens (2026-10-02) predate frame blending; with the defaults-only ini the sweep now runs Auto, which blends at 120 on a 120 Hz panel, and 2-9 levels flag at random per run (worst 9.3%). The same levels pass with `VERIFY_INI_EXTRA` set to a `[Video]` block with `FpsCap = 60`. Pin the sweep to 60 or re-capture goldens on the blended path; until then run the release sweep with that extra ini. |
+| Platform parity gate (Linux co-equal with Windows) | open (v0.7.0, maintainer 2026-10-10) | — | **Decided 2026-09-30:** yes. Every released platform carries the same gate: a 21-level sweep plus a campaign pass. Needs the golden baselines on both platforms first (§7). The last known Linux crash (D190) was closed as not-a-bug. |
+| Low-end GPUs (~30 fps on Celeron/HD 400) | fixed, verify on N3060 class | D339, D481, D482, #92 | **D481 (2026-10-02):** fast3d ran inline on the scheduler thread, delaying retrace delivery so the tick gate skipped frames; the render worker took a Lenovo X220 (HD 3000) from 44-46 to 60.0 fps. **D482:** Atom/Celeron-class GPUs (HD 400-605, UHD 600/605, software renderers) get DrawDistance/LodDistance 100 and MSAA 1 once, where still at defaults. **D473:** uncached per-batch getenv fixed. Direction: real optimizations, not a preset. **Next only if N3060-class hardware still drops:** one `GE_PERFSTAT=1` run (`gpu=` vs `run=`), then a lighter renderer-keyed default (GPU) or fast3d per-batch cuts (CPU; local `PERF-HOTSPOTS.md`). |
+| Statue/Cradle hitching (maintainer, 2026-09-30) | parked (not player-visible, 2026-10-02) | `GE_PERFSTAT` spike counters | **Diagnosed (D475, D477, D480):** no sustained load — the ~33 ms frames are the frame limiter skipping a retrace after a late gfx task (`boss.c`, D13-class timing); CPU bursts were CI-palette re-imports (ruled out, D477) and in-play shader compiles (fixed, D480). **Parked 2026-10-02:** a play session with the timeline probe felt no hitching. Reopen only if a visible hitch is reported (lever: pre-warm at level load). |
+| Steam Deck preset skipped when first launched from Desktop Mode | verify | D283 | Fixed on `release/v0.4.1`: the Deck is detected by DMI hardware id (Valve Jupiter/Galileo; `STEAMOS` as a second signal) and the preset applies once per ini, only while Fullscreen/Maximized are untouched. Only a Windows build and a Linux `-fsyntax-only` check ran. **Owed: one run on a real Deck** (Desktop-Mode-created ini, then Game Mode; expect fullscreen 1280x800 and the log line `video: Steam Deck (DMI Valve ...)`). The Known-issues row goes when this ships. |
+| Windows 7 | open | #98 | **Re-checked 2026-10-02: likely feasible around 1.0.** The exe imports no Windows 8+ functions and the bundled SDL2 2.32.10 still supports Windows 7. The real blocker is the first-run converter `ge007-convert.exe` (PyInstaller, Python 3.9+): the native C converter (#6 Part B) removes it, or a separate Python 3.8 build. Work: one Windows 7 VM test, then manual per-release checks (CI cannot test it). Supersedes the earlier 'won't-fix' call. |
+| Alt-tab haze + fast alt-tab recovery | open (v0.7.0, maintainer 2026-10-10) | D578 | Maintainer 2026-10-10 (v0.6.0 build, Windows 120 Hz): alt-tabbing leaves a hazy picture; fast repeated alt-tab is wonky and recovers only after a while or more alt-tabbing. Not new in v0.6.0 (was an owed check). Known issue in the v0.6.0 notes. QoL fix: clean focus-loss/regain path (context/FBO state, present queue reset). |
+| Deck: max Field of view feels choppier while turning | fixed in v0.6.0 2026-10-13 (D953 LOD/fade/visibility + D954/D955); maintainer Deck-confirmed (Surface windows) | D953 | At FOV 90 (menu max) turning feels worse than at 60, at 60 and 90 fps. Frame pacing measured identical at both FOVs. Lead: FovScale pulls every model LOD switch 1.73x closer, and depth-based LOD flips off-axis objects while turning (Dam turn probe: 0 flips at 60 deg, 400 at 90 deg, 120 with the fix candidate on `fix/d953-fov-lod`). Pass 2 (10-13 evening): prop fog fade and fog-range visibility fixed the same way; on Surface LOD/fade/visibility do not change while turning, so they are not the feel. Maintainer: objects "update not at the right speed" (object motion is not interpolated at 90, plan D955). **Next:** D955 Stage 0, and one Deck `GE_D193=1` run per FOV for 2-tick game steps. |
+| Doors and guards flicker at 90 fps (not at 60) | fixed 2026-10-13 (D954); maintainer Deck-confirmed | D954 | In-between presents drew props (chrs, doors, effects) at the exact camera while rooms used the blended one, so props jumped against the world whenever the camera moved (Surface turn on Windows: 0.4-0.5 deg mean, up to 1.8 deg). Present in v0.6.0 at 90 fps. Fix in `gfx_pc.cpp`: props' plain perspective gets the room camera blend (`P * R^-1 * Rb`) up to the first-person gun. **Owed:** Deck at 90 fps, Surface doors/guards, and the gun must not move while turning. |
+| Objects move at 60 Hz steps at 90 fps (props, doors, guards) | fixed 2026-10-13 (D955 + sky pass); maintainer Deck-confirmed (guards, doors); first-person weapon not blended yet | D955 | In-between presents drew objects at their tick pose (only the camera was blended). Now blended per joint, keyed by (Model*, joint) from a game-thread snapshot, rebased onto the new camera; exact on room-origin changes, failed gates, split-screen. Dam on Windows: 99.6% of object joint loads blended. **Owed:** Deck at 90: guards walking, gun in hand, hats, deaths, shadows, doors, Facility stall doors/sinks (the old ghost site), room boundaries. Vehicles later. |
+| Windows display scaling: the game is not DPI-aware on scaled displays | fixed 2026-10-10 (D626); maintainer by-eye on a scaled display owed | D626 | Seen 2026-10-07 during the v0.5.0 4K captures: on a 3840x2160 display at 125% Windows gives the game a 3072x1728 surface and stretches it, so the picture is softer than native. `gfx_sdl2.cpp` sets `SDL_HINT_WINDOWS_DPI_AWARENESS` only when `allow_hidpi` is off; setting it (`permonitorv2`) on the HiDPI path too renders at native resolution. Workaround today: environment variable `SDL_WINDOWS_DPI_AWARENESS=permonitorv2`. |
+
+## 5. Modern-remaster layer (port features beyond the N64)
+
+**The bar:** feature parity with a Nightdive-style remaster and with
+GE+/Dab's mod where it's practical. Shipped so far: native widescreen and
+ultrawide, FOV, MSAA/anisotropic/texture-filter options (including N64
+3-point), draw and LOD distance, VSync and a frame cap, show-FPS,
+keyboard/mouse rebinding with a GEPD-style layout, pad deadzone,
+sensitivity, smoothing, southpaw and triggers, rumble, crosshair and HUD
+customisation, HUD scale, music/FX volume, no-hit-flash, SkipIntro,
+All unlocked (see D387, D442), and the F10 overlay.
+
+The modern defaults (native widescreen, overscan crop, 250% draw/LOD
+distance, bilinear filtering) are **deliberate**. They are not a fidelity
+defect.
+
+Background research lives in the maintainer's local notes (gitignored):
+`GEPORT-REFERENCE-DEEPDIVE.md`, `MODERN-PORT-FEATURES-BACKLOG.md`,
+`MODERN-OPTIONS-PLAN.md` and `PD-LEGACY-SURVEY.md` under `docs/dev/notes/`.
+
+### 5a. Before 1.0
+
+**Renumbered 2026-10-10 (maintainer):** the planned v0.5.1 (frame rate above 60 + macOS) ships as **v0.6.0**, and the old v0.6.0 scope is now **v0.7.0**; labels below are updated, findings and commits keep the old names. **Order (maintainer, 2026-10-08; mod-start added 2026-10-09): v0.6.0 = frame rate above 60 (D578) + macOS (#95, local); then custom textures and mod support (the texture work likely shares the surface/geometry findings from D578). v0.7.0 ships the items marked v0.7.0 below (#145 control styles, native N64 pad support, the v0.5.0 issue triage, the README line, **mod support start — maintainer 2026-10-09: mods come sooner, in v0.7.0, not after 1.0**). They are the minimum for 1.0.** Everything marked v0.7.0 is open; none of it is claimed fixed or verified.
+
+| Item | Status | Refs | Notes |
+|---|---|---|---|
+| Log file (next release) | done (v0.6.0) | maintainer 2026-10-06; D576 | **Done 2026-10-07 (D576):** `ge007.log` next to the ini, previous run kept as `ge007.prev.log`, 8 MiB cap. Was: write `ge007.log` next to the ini (console output is lost on a normal launch). Crosshair pointer done in v0.5.0 (D555). |
+| F10 / PC Options menu: PD-style dialog refactor + watch-consolidation review | verify | D504-D512, `MENU-PD-ALIGNMENT-PLAN.md` (maintainer's local notes) | **Built 2026-10-04 (D504); follow-ups merged:** D505/D506/D507 (wording, real-unit sliders, descriptions); D508 forced aspect ratios (16:9 / 21:9); D509 2-frame hold after an aspect change (rare gun glitch = known issue); D510 overlay + FPS counter same size front end vs level; D512 `Game.HudScale` scales the F10 overlay. **Owed (live pass, `docs/dev/notes/MENU-LIVE-CHECKLIST.md`, launches A/B/C):** look-and-feel vs PD; mouse, keyboard and pad in a level and on the front end; HudScale 75/100/150; 21:9; display-mode round trip across a restart; split-screen 2P with the overlay open. **Gaps:** background blur (post-1.0, §5c); per-seat control scheme is #139 / D513. Watch consolidation: not cheaply feasible (parked as T5). |
+| Defaults/presets consolidation: one `Display mode` switch | verify | D504, D440, `MENU-PD-ALIGNMENT-PLAN.md` §5 (local notes) | **Landed 2026-10-04 (D504):** the derived `__DisplayMode` row shows Modern / Original N64 / Custom (no ini key); F10 dropdown + left/right stepping, front end steps too; one reset row per dialog covering exactly its keys; editing a non-bundled key does not flip Display mode. **Decided 2026-10-03: tri-state**, flipping to Custom when the user edits a bundled key. **Owed (live):** display-mode round trip across a restart; read of the regrouped pages and wording (MENU-LIVE-CHECKLIST.md A1/A2/A4). |
+| Control style Original shows the game's own N64 styles | verify | #139 follow-up, D516, D517 | **Landed 2026-10-04 (D516, merged @ 91595597):** "Controller style" row (Original only; the game's own 1.1-2.4 per seat, saved to the Bond file; front end reads "(in a mission)"); D498 presets hidden in Original. **D517:** hold-repeat on any Bond row dropped fps (EEPROM rewrite per detent); now staged like sliders. Live passes 2026-10-04 (maintainer): single player + split-screen 2P with different styles per seat. **Owed:** the 2.x second-pad pass (real second controller). |
+| Pad layout preset per player (setting P2's no longer moves P1) | verify | D518, D498 follow-up | **Landed 2026-10-04 (D518):** `Input.PadPreset` kept as seat 1's key + new `Input.PadPreset2/3/4`; the F10/front-end preset row follows the Select-player seat. Headless GE_PADMAPTEST PASS; **live passes 2026-10-04** (P2 change leaves P1 alone; split-screen: each seat ran its own preset). |
+| Control scheme selectable: Ext / Original control style | verify | #139, D513, D498, D166 | **Landed 2026-10-04 (D513, merged into `release/v0.4.1`).** `Input.ControlScheme` (row "Control style", Ext default / Original) on the Controller page, both UIs. Original leaves the game's own style alone; D498 presets set layout and stick swap only in Original; 2.x runs faithfully; global in v1, per seat with the Select Player work. **Owed:** pad pass in both modes, watch-selected 1.1-1.4, split-screen 2P with different styles, 2.x with a second pad. |
+| Outside PRs #107–#109, #122–#124 | decided | #122 hot-plugged pads never reopen, #123 persistent crosshair (`gunfire.c`), #124 compact health/armour bars (`bondview2.c`); #107/#108/#109 (italoarruda) | **Decided 2026-10-01:** **#120/#121/#122** merged locally (#122 = D450); close on push. **#123**: merged 2026-10-06 into v0.5.0 (D436; presets set it off, tip, Rule-2 signed off; by-eye hipfire / sniper zoom / 2P owed). **#124**: deferred (ignores HudScale, overlaps status text, ultrawide anchoring, split-screen untested) — **tentatively on the v0.7.0 triage list (commented to the author 2026-10-10; blocker is ours: scope + golden re-baseline, so a rebase onto `release/v0.6.0` would make integration cheaper).** **#133**: duplicates D472; close as superseded on push. **#109** (pad rebinding): decline as-is; supersede with our pad presets (§5a), crediting the author (Co-authored-by). **#107**: folded into D441; close on push. **#108**: range check implemented in v0.6.0 as D573 (commented + credited 2026-10-10; superseded, author to close). |
+| Gamepad presets: duplicate-binding warning, Xbox stick behaviours | open (after v0.5.0; documented in the README) | D469, D498, D518, D394 | D469 (pad action table, Jinx 1.1 default, Custom per-seat bindings), **D498** (Xbox 1.2 Christmas / 1.3 Frost / 1.4 Elektra) and the per-seat preset (**D518**) are done and maintainer-verified with pads. Not done (maintainer 2026-10-04: skip in game for v0.5.0, document only): a warning when two actions share a button; the Xbox "left stick aims the crosshair" and "D-pad copies the left stick" behaviours (D394). |
+| Pad button names on a Nintendo pad | verify | D471; local note `PAD-MENU-AUDIT.md` | Audit done 2026-10-01 (no controller-only trap; D472 fixed G1-G3). D471 family button names + player LEDs: **PS5 DualSense verified 2026-10-03.** **Owed:** a Nintendo (Switch) pad check; the maintainer has no such pad, so this waits for one or for a user report. |
+| Mute and auto-pause on focus loss; PNG screenshots to `screenshots/` | parked | D231, PR #56 (closed unmerged), `docs/dev/notes/parked/0001-QoL-*.patch` (local) | Deprioritised by the maintainer on 2026-09-25. F12 today is the dev PPM dump. |
+| Frame rate above 60 (90/120/144 with interpolation); **v0.6.0** | verify | D578, #137 (f1zz1ec0ke), [`dev/UNLOCKED-FPS-PLAN.md`](dev/UNLOCKED-FPS-PLAN.md) | **Built 2026-10-07 (D578, rework of #137 by f1zz1ec0ke), branch `feat/interp-fps`:** `Video.FpsCap` 90/120/144 draws matrix-blended frames between game frames on displays faster than 60 Hz; exact-frame fallback for turns (default ON); room-set change forces an exact frame; auto (match display) cap default. Latest commit `06ab98af`: port-side portal-chain replay recomputes room scissors for the interpolated camera (verified 0 mismatches over 1,200 exact frames at alpha=1 on Dam; the deep tunnel chain and flicker are untested). **Goal: a fresh Steam Deck install defaults to 90.** **Remaining before merge into the `release/v0.6.0` line (all open):** (1) Dam tunnel holes / pop-in re-test on a Deck with `06ab98af`; (2) VSync-on re-test (74.5 presents/s seen earlier); (3) Windows 120 Hz check plus a default-60 golden regression; (4) alt-tab haze; (5) live 144 Hz and Deck OLED 90 Hz checks. Dam in-between flicker (2026-10-08, NOT FIXED, the blocker for shipping high FPS): eight Deck A/B variants (dclamp, projset, exactproj, clipfix, nodepth, nocull, fullsciss, plus the older noportal/nosciss/noclip/noreach) all still flicker, and the CPU emits the same triangle counts in blended and exact passes; the loss is per-pixel content, not missing triangles. Next: run `holecap` in the Dam tunnel gap (saves in-between vs exact images of a real hole) and read what the hole pixels are. Findings: D578 addenda; handoff: docs/HANDOFF.md. **State 2026-10-10 (supersedes the "Remaining before merge" list and the Dam-flicker note above, both resolved by D578 2026-10-09 / D583):** work lives on `feat/d583-deck90` (local, unpushed, on top of `feat/interp-fps`). PC 120 + VSync on G-Sync fixed; Deck 90 good on most levels. **Merged 2026-10-10 into `land/v051-integration`** (off `release/v0.6.0`, with `macos-arm64`). Known issues for the release notes: Bunker fight drops on the Deck (D585 parked), Jungle feel, Cradle turret explosions (uninvestigated). Open gates: Dam ridgeline check with the clip widening off, default-60 golden regression / 21-level golden sweep, alt-tab haze, 144 Hz live check, VSync-without-G-Sync PC check. Was: decision. Older note: the menu cap was {30, 60} (the ini accepts 0 = uncapped, but the sim ticks at the VI rate); the plan's Phase 0 is resolved by D248 and its Phase 1 audit and Phase 2 slice scope are written (2026-09-30). Must stay compatible with netplay determinism. |
+| PD Extended Options parity: settings that need new dev work | done (reviewed 2026-10-04; two rows deferred) | `MENU-PARITY-SONNET-PLAN.md` §3 (local notes); pd_port `port/src/optionsmenu.c` @ 32a1cb9 | **Reviewed 2026-10-04 (maintainer decisions; local notes).** **Done:** D511 fullscreen mode, Center window, crosshair opacity and color by health (live check owed, MENU-LIVE-CHECKLIST.md A4/A5/B3). **Watch Screen size/Ratio:** stay on the watch, no PC rows; the game saves watch settings on watch close (D349 correction) and they don't fight Aspect ratio (README). **Deferred past v0.5.0:** mouse lock mode (Auto/Always/Off; aim lock itself = `Input.AimMode`, D337); per-seat controller device select (needs a stable pad id; MP input layer). **Closed:** edge deadzone = `Input.AimRange` (D338); crosshair sway N/A (GE has none; gun sway is D428); use key reloads, no toggle (Ext keeps D378's GEPD split, Control style Original gives the N64 behaviour); per-seat options/binds (pad binds already per seat, D469/D518; keyboard/mouse is one device); no Detail textures toggle (`Video.DetailBaseTile` is the D236 fix); N/A confirmed: HUD centering (D335b), glare, overexposure, GE64 muzzle flashes, MP death music, radial menu speed, language filter, crosshair speed. **Other rows:** analog movement/stick scale/crouch → #139, T7; tickrate/framerate limit → frame rate above 60. |
+| One PC options UI: front-end "PC Options" opens the F10 overlay over the folder graphic | verify | D519, D343, D504, D510, D512 | **Landed 2026-10-04 (D519):** the file-select "PC Options" entry opens the F10 overlay over file select; the `MENU_PC_OPTIONS` screen and four old probes are gone; Bond-file rows and the watch chooser are keyed to file select. Headless checks pass. **Owed:** by-eye mouse, keyboard and pad pass on file select; profile chooser + Controller style with a real profile; footer text overlaps the Copy/Erase bar. |
+| Emulator saves load directly in the game (no tool for import) | verify | D514, D492; `port/src/eepimport.c` called from `geEepromLoad`; D297 `legacycrc.c` same pattern | **Landed 2026-10-04 (D514).** Copying a 1964/Project64 `.eep` in as `data/ge007.eep` works: on first launch each region that validates in emulator format and not port format is converted in place (same rules as `eep_convert.py`); regions invalid in both are left to the game's wipe; port saves untouched; the original is backed up to `ge007.eep.emulator.bak`. Export stays with `eep_convert.py`. Headless verify 6/6 byte-identical to the reference. **Owed:** by-eye mission select after importing a real 1964 save. |
+| DexDrive / GameFAQs `.n64` saves | idea (easy, post-1.0) | D514; sample `scratch/eepinv/gamefaqs_dexdrive_2001.eep` (local) | **Noted 2026-10-04.** Old GameFAQs GoldenEye saves are DexDrive Controller Pak dumps (`123-456-STD` header, then a 32 KB pak) whose note (game code `3BADD1E5`, 2 pages) holds the 512-byte cartridge EEPROM. Extracting it and zero-padding to 2048 bytes gives a valid emulator-format save (TenebrusoM sample: all 6 CRCs OK). Support = walk the note table, pull the note, pad, hand to the D514 importer (or an `eep_convert.py dexdrive-to-pc` subcommand). Not tested in game. |
+| Title bar and window icon (no FPS counter; static "GoldenEye 007" title + GE-crosshair window icon) | done (v0.5.0 polish) | maintainer request 2026-10-17; D550; `port/src/video.c`, `port/fast3d/gfx_sdl2.cpp`, `cmake/icon/ge007.rc`; icon art = `docs/img/icon/ge007-icon.png` (`tools_pc/make_icon.py`) | **DONE 2026-10-17 (D550):** static title bar (live FPS stays on F10), `SDL_SetWindowIcon` from a generated 32x32 header, exe icon via `ge007.rc`. Original generated mark, no game imagery. Build-verified; maintainer live window/taskbar check owed. |
+| Opt-in update check (`Game.CheckUpdates`, off by default) | verify | D551; `port/src/updatecheck.c` | **Landed 2026-10-06:** Game-page toggle; one HTTPS GET per launch to `/releases/latest` (no pre-releases); Windows loads `winhttp.dll` at runtime only. Live-verified (Win/Linux/Deck), security-reviewed. **Follow-up PR (2026-10-06):** (1) DONE 2026-10-07 (D575; offline harness `tools_pc/updatecheck_test.c` covers the edge-case half of (2); the live half is still owed). Was: the Linux/Deck `curl` path reads into a 64 KB buffer and treats `curl`'s exit code as failure, so a `/releases/latest` response over 64 KB (long notes, many assets) silently gives no result even though `tag_name` is in the first ~1.5 KB; raise the cap and accept a full buffer (v0.4.0's response is 27 KB, so v0.5.0 is safe). (2) Validation matrix: offline harness for `versionNewer`/`extractTag` edge cases; throwaway builds with `GE007_VERSION` set to 0.3.0/0.4.0 against the live endpoint, Windows + Deck; a pre-release never prompts; after a publish, an older-version build shows the F10 row and opens the releases page; network-off and setting-off runs. |
+| Control style: Classic/Original gamepad styles do not match the N64 (#145) | open (v0.7.0; reported on v0.5.0) | #145, D516, D498, D469, D518, D394; README gamepad section | **Reported:** (a) Input "Invert look" (`port/src/input.c` `padLookInvertY`, applied only on the right-stick look path, ~lines 2797/2821) does not reach the left stick when an Original style that aims with the left stick (1.2) is active. **Hypothesis from code reading, not yet verified.** (b) Face buttons under "Classic" do not revert to the original roles (original: South = change weapon, West = action/reload; port: South = action, West = reload, North = change weapon). (c) Menu buttons differ (original: South accepts, West goes back; port: West + South accept, East goes back). (d) The in-game watch invert row looks locked (D564 removed the game's own Look up/down row). **Decision owed (maintainer):** should "Original" mean strictly the N64 face-button and menu roles, with the modern roles kept as a separate preset? Port-only fix. Cross-refs the Gamepad presets row above. |
+| Native N64 pads (raphnet adapter) | open (v0.7.0; unverified) | v0.5.0 video review; vendored mupen `InputAutoCfg.ini` | Nothing raphnet-specific exists in the repo. The adapter should appear as an SDL joystick, but that is **unverified**. Work: verify with a real adapter or a user report (raw stick range ~+-80, octagonal gate, deadzone, C-buttons as buttons vs axes), then add a port-only N64-pad profile alongside the Xbox 1.2-1.4 styles. **Owed: a real adapter test (maintainer or a tester).** |
+| v0.5.0 issue triage: #146 menu emblem, #147 gun sway part 2, #144 mission timer | open (v0.7.0 triage) | #146, #147, #144, D428 | **#146:** main-menu file-folder emblem texture corruption (4K, Fedora KDE); needs a repro and a 1964 comparison before any fix. **#147:** gun slides side to side but does not turn with the look direction (part 2 of the sway report, relates to D428); check against 1964 first. **#144:** optional PD-style mission timer; port-only QoL, small. Parked issues #113 (cheat toggles), #111 (bots), #110 (third-person), #105, #101, #100, #98 are unchanged and already decided/answered above. |
+| README "what this is" line | open (v0.7.0, docs) | recurring viewer questions (v0.5.0 video comments) | Add a short, honest line to the README: a decomp-based native port, AI-assisted, with 1:1 fidelity as the goal. Answers the repeated vibe-coding doubts and comparisons with other GoldenEye ports. VR stays post-1.0 (reference row in *Community forks*). |
+| Opt-in gameplay behaviour toggles (shoot-through, true rockets) | open (1.0, added 2026-10-09; **not started — no F10 row, no ini key, no port code; today's build is pure vanilla**) | §5b pattern; `gunfire.c`, `chrprop.c`; the 007 Plus source in the reference tree (**semantic reference only — it is a modded decomp, never a copy source**) | Port-only, default off; one batched Rule-2 sign-off (same pattern as the §5b rows). **Semantics (checked 2026-10-09 against the 007 Plus source in the reference tree):** shoot-through = the per-weapon `ObjectsShootThrough` stat (`gun.h:77`; `PROPFLAG2_SHOOTTHROUGH` `bondconstants.h:360`; penetration-limit checks `chrprop.c:2693/2822/2848`) — how many cover objects a shot passes through; mods retune the per-weapon table (e.g. Moonraker 6 vs 2; the dabs weapon-stat notes agree) and the disable toggle restores the vanilla values (RAM override, All-unlocked class). **True rockets — still open (2026-10-09):** the on-disk Plus tree's rocket handling matches vanilla (`propobj.c:4943`: fixed 100.0f player-prop / 2.0f enemy damage, owner-tagged self-damage, `unk8C` wall-bounce), so the scene's "true" semantics are not in that tree, nor in the GEPD bundle or the footstep docs; plausible candidates = AoE radius/splash retune or door-destruction behaviour — **confirm with the scene author before implementing**. **Implementation-risk note (maintainer 2026-10-09):** these are game-adjacent weapon-stat edits — fine-tune, don't guess: implement as minimal RAM-override toggles, diff-check against the vanilla values, verify with 1964 A/B + golden frames, one small commit per toggle, human review of the diff. **State 2026-10-09: nothing implemented. Work order:** (1) one-off stats-table dumper (vanilla + tuned per-weapon values, both ROMs); (2) the RAM-override + F10 row (one small commit, per the risk note); (3) 1964 A/B + golden-frame verify. True rockets waits on the scene-author answer for its semantics. F10 rows; the Original N64 preset keeps both off. |
+| Mod/patch support: drag-and-drop mod loading + mod management + mod template scaffolding + a shipped example mod | open (v0.7.0 start — maintainer 2026-10-09: **mods come sooner, in v0.7.0, not after 1.0**; full scope stays the 1.0 floor; added 2026-10-09) | D413 (capacity-only Rule-2 exception, user-approved 2026-09-28 — recorded in the mod-loader worktree's AGENTS.md), `land/modloader-*` worktrees, §5d; dabs `CLAUDE-notes/mods.md` (local reference) | **Progress so far (the Goldfinger 64 campaign, 2026-09-28 → 2026-10-08, worktree `land/modloader-m1-backlog`) — this is a working mod-loader layer, not a starting point; do not undersell it:** the **`rommod` layer is live** — a 25.1 MB GF64 mod ROM loads over the 12.5 MB vanilla base (`rommod: mod 'goldfinger64' requested — 58 raw file rows, 598 sidecar rows` in the run logs; the standard pcmodels/pccg sidecar pools carry the extra content), with C2 ROM-patch decoding of the mod's patches. **M1 done** (`97fda74f`): GF64 **boots, renders (walls fixed), clean-quits** via the loader. **C2 done** (`8c325fc5`): the ROM-patch decoder CLI `tools_pc/modpatch/` — **branch-only, not yet merged to main**. **D413** (user-approved 2026-09-28): the capacity-only Rule-2 exception — raising compiled table/pool capacities (`rommodTextureCap()`, `g_MaxProps`, `STAN_MAX_ROOMS`) under `#ifdef PORT` with a provably-vanilla-identical gate; it is the mechanism that lets a mod exceed vanilla limits. **Asset-prep + verification:** the `modprepare` pipeline (decodes the vanilla RZ file table — 727 rows, all resolved → `base_filelist.csv`/`base_table.json`); a **70-run GF64-vs-vanilla A/B campaign** (per-system: chrs/heads, levels, fog, portals, props, textures, vis/cull/nocull, mem, dyn, shots, clean-quit; vanilla-gate runs proving no-mod identity; GF64 re-verification runs against mainline findings). This row = M1→: content-tier mods (maps, textures, models) loadable by drop onto the exe / a `mods/` folder, with a management list (enable/disable); custom patch support rides on the same path. **Design standard (maintainer 2026-10-09): the dabs mod system** — `mods/<name>/{files,segs,textures}` overlay dirs, single-overlay slot, live file swap (`modListApplySelection` / `romdataResetFiles`), restart path only for `segs/` mods. **Add (maintainer 2026-10-09):** mod-template scaffolding + docs (new mod = copy template into `mods/`) and a first example mod we ship that does something cool. **The starter/test mod is the gun-colour feature (maintainer 2026-10-09 — it does not stand alone as its own feature):** per-weapon tint + a texture swap, demonstrating the scaffold end-to-end (crosshair colour is the separate shipped D511 — don't conflate). **Precedent:** the drop-in ROM converter already loads a Goldfinger 64 ROM — maps work, the mod's custom logic is inert; closing that gap (weapon/script data) is the stretch goal. Acceptance case: GEPD footstep-patch-style mods (bodies staying down, footstep SFX, core tweaks); their feature set maps onto the §5b opt-in toggles. **v0.7.0 slice (maintainer 2026-10-09):** look at mods sooner — merge M1/C2 to main, start the M1→ management + scaffolding (dabs standard) in v0.7.0, with the GF64 boot/render as the acceptance case; template + example mod and custom-patch support complete by 1.0. |
+| Cut-content restoration (mod tier): extended MP roster + the 8 cut MP maps | open (1.0; added 2026-10-09, bring sooner if easy) | [`dev/CUT-CONTENT-BACKLOG.md`](dev/CUT-CONTENT-BACKLOG.md) §D/§F | Everything is in the ROM data (backlog, verified): roster — `front.c:601+` `mp_chr_setup[]` holds ~40 named entries beyond the 8 selectable (ROSIKA, KARL, TERRORIST, BIKER, …); maps — `front.c:556-573` `multi_stage_setups[]` has 8 commented-out entries (Citadel/Frigate/Statue/Cradle/Aztec/Runway/Dam/Depot) and every one of those maps already boots standalone (`-level_XX`, geometry, AI setup and briefings intact). Tier 2/3: the table edits touch `src/game` → land on the mod-fork branch (non-negotiable #2) and ship through the mod scaffolding above; Tier-1 config-toggle grants stay port-side (backlog §2). **Maintainer 2026-10-09: in the 1.0 roadmap at minimum; if the `front.c` table edits + setup fixes turn out small, pull in earlier (v0.7.0).** **Assessed 2026-10-10 (read-only, `front.c`):** decision = *not* pulled in for v0.7.0. (a) Roster half is smaller than the row implies: `num_chars_selectable_mp` is already dynamic game logic (`front.c:4240` `unlock_all_mp_chars()` sets 0x40 via the existing debug/cheat unlock-all; `front.c:4986` sets 0x21 on Agent + Cradle-completed, else 8) — so an extended roster may need no `src/game` table edit at all: a Tier-1 port-only config toggle invoking the existing unlock path (live check owed: the 64-char select screen under the cheat) — the one-line "set the default to N" variant is the only `src/game` touch, and that stays mod-fork-only either way. (b) Maps half is the real cost: 8 entries are commented out with per-map state flags (`stat`/`crad` "works"; `azt` "needs setup"; `dest`/`runway`/`dam`/`depot` "xbla setup"; `Citadel` "old format") — uncommenting is trivial, the xbla/old-format/needs-setup fixes are not, and they touch `src/game` data handling → mod-fork branch. (c) v0.7.0 has no mod scaffolding yet (it lands with the 1.0 mod-fork), so there is no v0.7.0 ship path for the content itself; keep the item in 1.0 mod-fork scope and do the (a) live check opportunistically. |
+| Motion/gyro aim (controller sensor) | open (1.0, added 2026-10-09) | — | Controller gyro look, opt-in, default off; sensitivity + calibration rows. **Scope note (2026-10-09):** gyro hardware exists only on PS4/PS5 pads (and the rare Switch Pro via adapter) — Xbox/XInput pads have no sensor, so the practical feature set is small; the API is SDL2 `SDL_GameControllerGetSensor` — **verify first on the PS5 DualSense (maintainer has one; the D471 row already used it as a controller test)** before building. Steam-Input-style gyro mapping stays a player-side workaround (the game is non-Steam, custom shortcut only — no Steamworks). |
+| Localisation: JP/PAL ROM support first, then community language packs | open (1.0; reframed 2026-10-09) | §1 (PAL/JP row) | **Reframed 2026-10-09 (maintainer):** phase 1 = JP/PAL ROM support, already Stage B (§1). Phase 2 (later 1.0, community-driven) = a port-only text-override layer (`data/languages/<code>` packs overriding ROM strings) so people can add their own language packs if inclined; translation content is community-supplied (open-source-branching model). |
+| Custom gun colour (ships as the example/starter mod — see the mod row above) | deferred (2026-10-09) | D511 (crosshair colour already shipped — a different thing) | Maintainer 2026-10-09: not a feature in its own right — it is the starter/test mod that demonstrates the mod scaffolding (per-weapon tint + texture swap); the hook (a tint pass in the model/fast3d stage) is designed when the mod row starts. |
+
+
+### 5b. GE+ / Dab's-mod gameplay options (opt-in; touch game code)
+
+| Item | Status | Refs | Notes |
+|---|---|---|---|
+| Disable knockback / hitstun, damage sound, endless death cam | post-1.0 | hooks at `chraction.c:2233`, `gunfire.c:3334`, `bondview2.c:8354` | Needs one batched Rule-2 sign-off. **Decided 2026-10-01:** after 1.0, all opt-in (default OFF), one batched Rule-2 sign-off. |
+| Bodies stay where they fell | post-1.0 | — | **Decided 2026-10-01:** after 1.0, opt-in. |
+| Port-native third-person camera | post-1.0 | #110 | The 007 Plus ROM patch itself is out of scope. Decide whether a port-native TP camera is in or out. **Decided 2026-10-01:** decide in/out after 1.0 with the other §5b options. |
+
+### 5c. Enhanced visuals (optional; after feature-complete)
+
+The XBLA/Nightdive-style "new look". None of it has started in this repo.
+An outside fork has a large Original/Enhanced/Remaster render-mode stack
+(see *Community forks* below). Adopting any of it is its own decision and
+needs Rule-2 review.
+
+| Item | Status | Notes |
+|---|---|---|
+| Post-process chain: FXAA/SMAA, bloom, depth of field, colour grade/LUT, CRT filter, brightness/gamma, colourblind filters, SSAO | post-1.0 | Build the framebuffer pass once. Every effect defaults OFF. **Decided 2026-10-01:** after 1.0; our own opt-in implementation (default OFF; the Original N64 preset restores the N64 look); thepont's fork is reference only. |
+| Near-full fog reveal (D503): far objects about 97% fogged show as faint silhouettes with straight room-clip edges on 32-bit output (e.g. Surface's dish) | verify | **Snap landed 2026-10-04** (cutoff 247, not derived from measured vertex fog); dish residual = (C) widescreen frustum, moved to the §3 D222 row; by-eye pass across levels owed. **Decided 2026-10-03 (maintainer): option (a)**, snap fog at or above ~97% to full fog (port-only, fast3d vertex fog). Option (b) (N64 16-bit colour/dither output) stays a candidate for the Original N64 bundle. Measurements: findings D503. |
+| Render scale / supersampling, integer scaling, "authentic 320×240" mode | post-1.0 | **Decided 2026-10-01:** after 1.0; our own opt-in implementation (default OFF; the Original N64 preset restores the N64 look); thepont's fork is reference only. |
+| Dynamic/coloured lighting, dynamic shadows, water reflections | post-1.0 | Large. Consult the PD port first. #105 is about the fork's version of reflections, not ours. **Decided 2026-10-01:** after 1.0; our own opt-in implementation (default OFF; the Original N64 preset restores the N64 look); thepont's fork is reference only. |
+| Path-traced render mode (opt-in, RTGL1) | post-1.0 | Experimental, for fun (maintainer, 2026-10-01): **deprioritised to after 1.0**. Plan in the maintainer's local notes: vendor MIT RTGL1 behind `port/rt/`, default OFF; fast3d stays the default backend and the fidelity ground truth; Phase 0 is a toolchain spike (RTGL1 under MSYS2/MINGW64). Nothing starts before 1.0. |
+| HD texture packs: loader + texnum dumper; model packs | open (1.0; loader + dumper bumped 2026-10-09, was post-1.0; model packs stay post-1.0) | #100 | There is a staged design. Step 1 (texture identity registry) touches `src/game`, so it needs Rule-2 framing. **Bumped 2026-10-09:** loader + texnum dumper in 1.0 — the §5a order already puts custom texture work in the v0.6.0 sequence (sharing the D578 surface/geometry findings); the geometry/texture-lining fixes for pack support come first; model packs stay post-1.0; our own opt-in implementation (default OFF; the Original N64 preset restores the N64 look); thepont's fork is reference only. |
+| Animation smoothing (keyframe slerp) | post-1.0 | **Decided 2026-10-01:** after 1.0; our own opt-in implementation (default OFF; the Original N64 preset restores the N64 look); thepont's fork is reference only. |
+| F10 background blur + GUI-only texture filtering | post-1.0 | **Backlogged 2026-10-04 (maintainer): visual nice-to-have after 1.0.** Design done (local `MENU-BLUR-GUIFILTER-DESIGN.md`, ready Sonnet prompts in its §4). Blur: fast3d already decodes PD's framebuffer EXT opcodes and has the 16-tap kernel; only an emitter is missing (`port/fast3d/gbiex.h`); capture once on open (live capture too costly on HD 3000, D481). GUI filter: `Video.GuiTextNearest` point-samples texrects only. Port-only, default off. |
+
+### 5d. Extras (nice to have)
+
+In-game console · demo/replay record and playback (doubles as the
+determinism harness, §7) · photo mode · benchmark mode · subtitles · HUD
+opacity and a flash-intensity slider · a screen-shake slider that covers
+every shake source (D181 only scales explosions) · F11 video recording ·
+in-game patch notes and update check · mod loader (parked: branches
+`land/modloader-*`, D413/D414; only the content tier M1/C3′ is viable here)
+and a stage loader.
+
+## 6. Multiplayer beyond the N64
+
+| Item | Status | Refs | Notes |
+|---|---|---|---|
+| LAN netplay | open (1.0; bumped 2026-10-09, was post-1.0) | — | Depends on split-screen. Determinism groundwork is D117 (not achieved). **Decided 2026-10-01:** in scope after 1.0. **Bumped to 1.0 (2026-10-09):** single-screen view option alongside split-screen, spectator mode, and demo recording (doubles as the §7 determinism harness, §5d). Online (non-LAN) netplay is in scope via the client/server row below. |
+| Online netplay: client/server (Zandronum-style) | open (1.0 if viable — tier 1 pre-1.0, narrow tier-2 core as the 1.0 stretch, else post-1.0 per the plan) | local note `dev/notes/ONLINE-CLIENT-SERVER-PLAN.md` (direction agreed 2026-10-07) | **Added 2026-10-09 (maintainer pivot; supersedes the blanket online exclusion in *Not planned*); maintainer 2026-10-09: wants it in 1.0 if viable — the viability gate is D117 determinism + the plan's tier-2 milestones, tier 1 (port-only) goes regardless.** Target: client/server (Quake/QuakeWorld→Source lineage) with a Zandronum-style feature set; shipped as a build variant in the main repo (`GE_ONLINE=ON` → `ge007-online` client + headless `ge007-server`; no forks); game-logic hooks fenced under `#ifdef GE_ONLINE` so faithful builds stay byte-identical (golden frames prove it; a fenced Rule-2 amendment owed, maintainer call). **Tiers:** 1 port-only (lobby + NAT, server config, master server + browser, quick match, rcon — pre-1.0); 2 the `GE_ONLINE` core (authoritative server, prediction/reconciliation, mid-match join, spectators — start narrow: one level, one scenario, 4 players; 1.0 stretch, post-1.0 if the gate slips); 3 later (more players, unlagged hit checks, server demos). References: the PD port `port-net` branch (ENet, host-authoritative — closest analogue, study first); Zandronum/Odamex design-only (GPL — copy design, never code). **The #141 security hold stands** (forensic review before reusing any of it). |
+| MP bots | open (1.0; bumped 2026-10-09, was post-1.0; opt-in) | #111 | Not N64 (GoldenEye's MP is human-only; Simulants are Perfect Dark). birdturtle `simulants` is an outside prototype. **Decided 2026-10-01:** in scope after 1.0 (opt-in; not N64). **Bumped to 1.0 (2026-10-09):** opt-in AI/scripted bots for local MP. |
+| Co-op campaign | open (1.0; bumped 2026-10-09, was post-1.0; opt-in) | — | Not N64. thepont `feature/coop` is an outside prototype. Listed under Not planned unless this changes. **Decided 2026-10-01:** in scope after 1.0 (opt-in; not N64). **Bumped to 1.0 (2026-10-09):** opt-in split-screen co-op campaign (007 Plus-style). |
+| Cheats beyond the N64 cheat menu | post-1.0 | #113 | Only in scope as an opt-in toggle. **Decided 2026-10-01:** in scope after 1.0, opt-in toggles only. |
+
+## 7. Tooling, infrastructure, security
+
+| Item | Status | Refs | Notes |
+|---|---|---|---|
+| 1964-vs-port comparison harness | partial | `tools_pc/abpad/` | One millisecond timeline drives 1964 (virtual XInput pad) and the port (`GE_INPUTSCRIPT_MS`); both windows captured on one clock with side-by-side sheets, verified through intro skip, file select and folder open. Not frame-identical (1964 has no seed pin or frame dump). **Left:** in-level timelines (e.g. the D486 turret check); the two sides use different save files. |
+| Scripted-playthrough harness | post-1.0 (maintainer 2026-10-04: not a good use of current LLMs, revisit with newer models) | `GE_INPUTSCRIPT`, D117 | Input script + `GE_PCDUMP` + crash-log check for unattended regression runs. Levers: Invincibility + Invisibility cheats, closed-loop waypoint steering, pinned seed. Spike: one Dam route x5, measure end-position spread, then go/no-go. |
+| Cheap worker for mechanical, build-checked tasks | open | `delegate-local` MCP; memory of past Qwen issues | Birdman64's fast worker model wrote 44% of its commits while the lead planned and reviewed. Ours: pattern-applied edits (D441 fix batches, scaffolding strips, small tools), each gated by a clean build + a specific check + the lead's diff review, in the worker's own worktree. Local Qwen for edit-only tasks (it fabricates on reading tasks), or a hosted fast model via `delegate_to_provider` (the maintainer's cost call). |
+| Golden baselines | partial | `tools_pc/verify.sh`, `tools_pc/golden/README.md`, D117/D522/D529/D531 | **2026-10-06: all three sets (win/linux/deck) re-based for D543/D546**, A/B-confirmed; history in the golden README. **Windows gate GREEN (2026-10-05 re-base):** 21/21 PASS honest sequential. The recipe pins the save CONTENT (D529: `verify.sh` installs the canonical in-tree save `tools_pc/golden/ge007.eep` per level) and per-level windows — `900-1500:300` on 14 levels, `1000-1400:200` on Surface 2/Streets/Depot/Cradle/Frigate, `1500-1700:100` on Dam — because the 900 stem sits inside the wall-clock-paced intro flyby (D117; dam measured 1.6–7.2 % run to run). No tol limit raised. **Linux set (D525 → D530 → D531):** D530's re-round ran under the box-local save (`capture_p7.sh`'s re-pin overwrote D529's canonical install); D531 fixed the tool and re-captured all 21 levels under the canonical eep (47/63 frames moved). **Cross-platform spread recomputed 2026-10-05** from the committed pairs (`framediff.py` win-vs-linux at the stems, tol 2): exact **0.380–5.120 %** on the 20 non-Cuba levels (silo's 900 stem is the outlier: cell mean 34.3, phash 10), structural **21/21 clean**, max phash 40 (cradle, at threshold); Cuba 1.357–12.663 % is the structural-tier-only level. **Pixel gate green on all three, final v0.5.0 build (2026-10-06):** win 21/21; linux 21/21 on the X220 (`DISPLAY=:1` makes the GL probe see the real GPU; one Jungle flyby-jitter miss passed twice solo); deck 21/21 (needs `XAUTHORITY` for the probe over ssh). |
+| Flicker scan (A/B/A frame alternation) | parked (2026-10-03: tooling, nothing blocked on it; local spec `scratch/birdman64-rows-investigation.md` §4) | `GE_PCDUMP`, `GE_INPUTSCRIPT` | Dump **every** frame of a scripted run at low resolution and flag frame n when it differs from n-1 but matches n-2. For any old-vs-new pixel diff outside the golden gate, run a same-commit control first. Reference: Birdman64 `tools/flicker_scan.py`. |
+| GE_ probe catalog (macos-track diagnostics: keep vs strip) | done 2026-10-08 (strip debt closed; the `GE_TEXDUMP` KEEP family stays in-tree) | [`dev/GE-PROBE-CATALOG.md`](dev/GE-PROBE-CATALOG.md) | The macOS track added env-gated, diagnostic-only `GE_` probes (all off by default, no behavior change when unset). **Keep:** the `GE_TEXDUMP` family (`GE_TEXN`/`GE_TEXDUMPROW`/`GE_TEXRAW` + the GL `.rgba32` upload dump — the standing cross-platform texture-triage tool, cached `getenv`). **Stripped already (2026-10-08, `b80dcd08`):** `GE_NPOT_NOGENMIP` (the D592 NPOT mip-guard, `9bed5904` + companion `82dbea9c`) and `GE_TEXSTATE` (the D592 GL-state probe, `de5a0fea`) — both removed when **D592 closed as a non-issue** (metric false-positive; see the D592 close-out). **Stripped 2026-10-08 (final probe-strip commit; on `macos-arm64`, pushed to Forgejo 2026-10-08):** `GE_TEXP` (the `src/game/image.c` pool-cursor dump — its removal returns that region to the N64 build), `GE_SIZEOF` (the `port/src/main.c` startup ABI-width canary, redundant with the `abi_ratchet.py` CI) and `GE_KEYLOG` (the `video.c`+`input.c` D594 input diagnostic) — 75 pure deletions, behavior-neutral, Mac headless re-verified (2P + solo, 0 crash logs). Stripping is a mechanical, behavior-neutral edit. |
+| Release build-provenance attestation | verify | `.github/workflows/ci.yml` release job; `.github/SECURITY.md`; README Status section | **Implemented 2026-10-04:** SHA-pinned `actions/attest-build-provenance` attests `dist/*.zip[.sha256]` + `dist/*.tar.gz[.sha256]` in the tag-only release job (`id-token: write` + `attestations: write` on that job only). Backs SECURITY.md's "unsigned, but reproducible" stance with `gh attestation verify <file> --repo jkdansereau/goldeneye-pc-port`; documented in SECURITY.md and the README. **Owed:** the v0.5.0 tag build is the first real run; confirm the step passes and verification succeeds on a downloaded asset, then delete this row. |
+| Self-hosted CI runner link failure | open (v0.7.0, maintainer 2026-10-10) | D244 | Needs a `pacman -Syu` on the runner (maintainer-only access). Release tag builds use GitHub runners, so it doesn't block a release. |
+| Remove temporary scaffolding before a release | partial | [`dev/GE-ENV-PROBES.md`](dev/GE-ENV-PROBES.md), D302 | Passes 2026-09-30 to 2026-10-03 removed the closed-finding probe suites (registry in `GE-ENV-PROBES.md`, `gen_env_probes.py --check` passing); TEMP probes `GE_TESTSTYLE` / `GE_D516` removed 2026-10-04. **Left:** D104 (kept while D294 is in verify); the M-183/M-185 clamps were **deleted 2026-10-04** (`879f879a`, `model.c` pure decomp again; the M-189 root fix stays) and the cutscene re-check was covered by the 2026-10-05 Deck campaign playthrough on rc1 (level intros, endings incl. Facility and Dam, credits). |
+| P12 U5 review of `tools_pc/**` (release-diff, B10) | partial | D531/D532/D533 | Reviewed 2026-10-05 (the unit that owed the P7 merge). **Blocker found + fixed (D531):** `capture_p7.sh`'s per-level re-pin restored the local save (see Golden baselines). **Should-fixes applied as D532 (tooling-only):** `verify.sh`'s `pin_ini_640x480` fails closed like `pin_eep`; `GOLDEN_SEED` hard-pinned with a warning for a stray `GE_RSEED`; `audiodebug.ps1`'s dead `-AB`/`-Old` switches removed. Box pixel verify done 2026-10-06 (see Golden baselines). |
+| Findings log and doc size | partial | `tools_pc/docs_budget.py` | Budget checker (per-file and tier-1 token budgets; `--toc FILE`). `findings.md` is still about 2 MB (~500k tokens), so agents must keep using the index. Nothing blocks; trim only when a budget check fails. |
+| Branch and PR housekeeping | open | — | 30 landed local branches pruned 2026-09-30 (tips in `prune-branches-2026-09-30.txt`, notes archive). **On hold by the maintainer (do not prune yet):** probe-only `d243-verify-local`, `investigate/d243-cutscene-race`, `park/d236-probes-m139`. Local `main` and `release/v0.4.1` are deliberately not pushed. PR #62 (mouse dt-decouple) stays held until mouse feel is fundamentally better. |
+| Docs site: Web 1.0 phase 2 | decision | — | Phase 1 shipped. Phase 2 (centred serif page) is plan-only. |
+| Docs site: press/SEO pass (2026-10-05) | partial | `docs/` site pages | Landed on the pure site pages + layout: real `<h1>` masthead, `color-scheme`/`theme-color`/`max-image-preview`/`rel=me`, ink-mute >=4.5:1, focus-visible + selection, 15px body, mobile padding; `date`/`modified_time` front matter on the pure pages. Home-page additions (pull-quote, Overview fact table, press section) **removed on review 2026-10-05** as duplicates. The five short topic notes (the-software-rsp, the-asset-pipeline, framerate-and-pacing, input-and-aim, saves) were dropped from the published set (files stay as working material). **Open:** the same front matter on the *shared* docs is deliberately untouched (authoritative working docs, not edited for site polish). |
+| Agentic-development deep dive (doc) | queued — not yet (2026-10-05) | `docs/dev/agentic-development.md` | Write-up owed for the public case study: per-agent commit/work estimates (manual attribution pass over the session log, incl. D350-style commit-date divergences), a code-quality audit of the trial models (GPT-6 (Sol) et al.), and process feedback / findings. Deferred by the maintainer; nothing here blocks. |
+| Docs site: split Security & fidelity -> two pages + v0.5.0 update pass (2026-10-05) | done (local, unpushed) | `docs/security.md`, `docs/fidelity.md` (was `security-and-fidelity-status.md`) | Split on review (the homepage pointer sat near Known issues and read as if there were security *issues*); both pages cross-linked and linked from the hub and index.md's Download section. Update pass 2026-10-05 against the `release/v0.4.1` tree: no network includes/symbols/HTTP literals in compiled `src/`+`port/`; no registry or library-loading calls; converter imports no network module; bundle manifests re-checked (allowlist + ROM/oversized-blob hard-fail); region macros re-compared vs the Makefile (all three regions); library classification re-checked (CMake globs libultra+libultrare audio, gu, `io/vitbl.c` only). Full game-logic audit not re-run; recent `src/game` edits are finding-gated. |
+| Docs site: final sanity sweep + anchor fixes (2026-10-05) | done (local, unpushed) | `docs/porting-notes.md` (3 TOC hrefs), `docs/404.html` (permalink) | Audit of the 10-page published set (one h1 per page, no heading skips, in-page anchors resolve, unique titles/descriptions, og:image/canonical, JSON-LD, no local paths, served == built). Three `porting-notes.md` TOC hrefs had a double hyphen where kramdown emits one: corrected at source against the live ids. `docs/404.html` got `permalink: /404.html`. Preview-builder slug rule fixed to kramdown's. |
+| LLM-agent dev-velocity workstream (model tiers + subagents + compaction hygiene) | decision — Tier 0/1 landed 2026-10-09; two approvals outstanding | `docs/dev-process.md` §8, `pi/` package, forensics of pi session `01a11ec6` (#150 cull-hunt evening) | Root cause of the #150 loss was model + discipline, not retrieval: a 4-bit-quantized 27B default model fired unvalidated render fixes at the maintainer for A/B (four consecutive failures); the 04:52Z compaction promoted an unvalidated hypothesis to "diagnosed" and post-compaction turns built on it. RAG/GitNexus evaluated and rejected (PolyForm license conflict, auto-writes AGENTS.md, wrong failure class; the repo's `findings-index.csv` is the domain-specific retrieval layer). **Landed per the 2026-10-09 maintainer instruction:** Tier 0 — `~/.pi/agent/settings.json` default = the ninfer backend's model (only one of ninfer/strata runs at a time, and ninfer is the fast one; today that is the coding-launcher 4-bit `qwen3.8-27b-nvfp4full` — the quality launcher `ninfer-quality.bat` serves the groupwise-int `qwen3.8-27b` as the strong local tier, a 30-second launcher restart + new pi session, not a backend switch); §8 rules (model tiers; data-before-edit; context reset after a 2nd failed maintainer A/B or a contested compaction; evidence-ledger compaction prompt); MODEL line in the brief template. Tier 1 — `pi install npm:pi-subagents@0.76.1` (pinned; audit in `docs/dev/notes/pi-subagents-audit.md`: MIT, no eval/telemetry, no install hooks, 310 js files) + tracked `pi/` package: four model-pinned subagent roles on ninfer (`build-runner`/`sweep-watcher`/`doc-sync` on 4-bit; `pairing` pinned `inherit` so the reasoning step follows the parent session's tier) + the `compaction-ledger` extension (evidence-ledger prompt; optional stronger summarizer via `GE_COMPACT_MODEL`). **Awaiting maintainer approval:** (1) `pi-subagents` as a third-party npm dependency; (2) the tier split itself — planning on `openrouter/deepseek/deepseek-v4-pro` (or `strata-coder-hard` with the local backend switched), execution on the standing ninfer backend (default = the model it serves, today the 4-bit `nvfp4full`). **Parked until after v0.7.0:** `pi-plans` trial (228★/2 contributors, exploratory benchmark, self-published evidence), `rpiv-ask-user-question`, Langfuse tracing, `pi-durable-subagents` (1★, unvetted); do NOT stack `billion-context` on the ledger extension (compaction overlap). **Workstream mapping:** first real runs on the v0.6.0 critical path — D578 Dam-tunnel flicker (`feat/interp-fps`; the `holecap` probe is `build-runner`-shaped) and D579 T-step (a)+(c) log pairing (the `pairing` agent's first job); build-runner + sweep-watcher support the v0.7.0 #145/native-pad campaigns. The ledger extension loads at session start, so its verification happens in a fresh session. |
+
+## Community forks (not ours; reference only)
+
+| Fork | What it has | Relevance |
+|---|---|---|
+| thepont/goldeneye-pc-port `feature/graphics-final-stack`, `fix/original-water-fidelity`, `feature/coop` | ORIGINAL/ENHANCED/REMASTER render mode, lighting, post-FX, bump/shadow/DoF, water reflections, vector HUD font, 2P co-op | Source of #105. Heavy `src/game` edits. **Their D323–D326 and "D329" labels clash with ours**, so relabel anything ported. |
+| birdturtle `feature/local-mp-input`, `simulants` | Local MP restore; first MP bot | Cross-check for #99 and #111. |
+| kaziema `vita` | PS Vita port | Platform reference. |
+| mattymattmattmatt/goldeneye-pcvr-port `vr/stereo-headaim` | VR stereo + head aim | Platform reference. |
+
+## Decisions owed (maintainer)
+
+Decided 2026-09-30 and 2026-10-01 (all moved into the rows above): PAL/JP in Stage B; `All unlocked` as a RAM override; D357 approved with changes; platform parity gate; feature PRs get a design review first; port_addr for #88/#95; D417 approved; the gameplay-visibility policy (§2); §5b, §5c and §6 post-1.0 and opt-in; D433 code audit; D323 post-1.0; #94 closes as stale on release.
+
+Nothing else owed right now (outside PRs decided 2026-10-01, see §5a).
+
+## Not planned
+
+Online matchmaking, leaderboards, anti-cheat, cross-play (client/server
+netplay is in scope now — the §6 online row) · Steamworks, achievements, cloud
+saves · HDR, frame
+generation, stereo 3D (ray tracing only as the opt-in post-1.0 experiment
+in §5c) · remake-scope assets (new models, music or voice) · new movement
+mechanics (jump, roll, melee) · the 007 Plus ROM patch as such (#110) · a
+per-user save folder (decided 2026-10-03: saves stay next to the game,
+keeping the security doc's "never writes to `%APPDATA%`" promise) · a
+first-launch controls card and controller toasts (decided 2026-10-03: new
+UI for little gain; F10 is documented in both READMEs).

docs/_config.yml

@@ -1,15 +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
-# v0.2.1 (Bing SEO): keep this SHORT -- jekyll-seo-tag splices it into the
+# Keep this SHORT (Bing SEO): 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.)
+# design in _includes/head-custom.html (the dark "amber terminal" theme: a
+# near-black starfield, a single amber accent, mono chrome over a sans body).
 show_downloads: false
 
 # Canonical site location - used by jekyll-seo-tag (canonical URLs, og: tags)
@@ -19,7 +19,7 @@ baseurl: /goldeneye-pc-port
 
 # Link-preview card image for jekyll-seo-tag (og:image / twitter:image).
 # Path is relative to the site root; the plugin prepends url + baseurl.
-image: /img/attract-bunker1.png
+image: /img/shots/shot-28.jpg
 
 # Both are on the GitHub Pages plugin whitelist - no Gemfile needed.
 # jekyll-seo-tag: per-page <title>/description/canonical/OpenGraph via {% seo %}
@@ -35,40 +35,57 @@ plugins:
 # instead, so they resolve from the published pages too.
 
 # ---------------------------------------------------------------------------
-# The site publishes a small curated set (see docs/dev/notes/DE-SLOP-DOCS-PLAN.md):
-#   index.md, building.md, internals.md, porting-notes.md, dev-process.md,
-#   dev/agentic-development.md
-# Everything else under docs/ is working material - the finding log, level
-# status, backlogs, plans, inherited decomp guides. It stays in the repo (and
-# on GitHub) but is excluded from the site build so it never shows up as a
-# published page or in sitemap.xml.
+# The site publishes a small curated set:
+#   index.md, documentation.md (the documentation hub), building.md, plus
+#   404.html (themed not-found page),
+#   the four docs grouped behind that hub: internals.md, porting-notes.md,
+#   dev-process.md, dev/agentic-development.md, and
+#   security-and-fidelity-status.md (split on review 2026-10-05 into
+#   security.md + fidelity.md, linked from index.md's Download section and
+#   the hub).
+# The five short topic notes (the-software-rsp.md, the-asset-pipeline.md,
+# framerate-and-pacing.md, input-and-aim.md, saves.md) were dropped from the
+# site on review 2026-10-05: the Perfect Dark port documents the same
+# subjects and nothing here was significantly new; they stay in the repo as
+# working material. Everything else under docs/ is working material - the
+# finding log, level status, backlogs, plans, session notes, inherited
+# decomp guides. It stays in the repo (and on GitHub) but is excluded from
+# the site build so it never shows up as a published page or in sitemap.xml.
+# NOTE: keep this list in sync as dev/ working docs are added; a new unlisted
+# .md under docs/ is silently published to the site + sitemap.xml.
 exclude:
-  - BACKLOG.md
+  - the-software-rsp.md
+  - the-asset-pipeline.md
+  - framerate-and-pacing.md
+  - input-and-aim.md
+  - saves.md
   - HANDOFF.md
+  - ROADMAP.md
   - SetupGuide.md
-  - StructureGuide.md
   - StyleGuide.md
+  - dev/ACCURACY-AUDIT-2026-09-20.md
   - dev/AUDIO-PLAN.md
   - dev/AUDIT-M6-player-offsets.md
-  - dev/D172-PARTICLE-COLOR-RESEARCH.md
+  - dev/CONTROLLER-INPUT-PLAN.md
+  - dev/CUT-CONTENT-BACKLOG.md
   - dev/D176a-SKY-NOTES.md
+  - dev/D356-SETTINGS-REGROUP-PLAN.md
+  - dev/D357-SETTINGS-VALUES-PLAN.md
   - dev/GE-ENV-PROBES.md
-  - dev/GRAPHICS-BACKLOG.md
+  - dev/GEPD-INPUT-PLAN.md
   - dev/HANDOFF-ARCHIVE.md
   - dev/LEVEL-OBJECTIVES.md
   - dev/LEVEL-PLAYTEST.md
   - dev/LEVEL-STATUS.md
-  - dev/LINUX-PORT.md
-  - dev/M-35-PLAYTEST-CHECKLIST.md
-  - dev/M-35-QOL-REVIEW.md
-  - dev/M-36-TRIAGE.md
-  - dev/MODERN-PORT-FEATURES-BACKLOG.md
+  - dev/notes
   - dev/OPTIONS-MENU-PLAN.md
+  - dev/preview-video.md
   - dev/QOL-INVENTORY.md
+  - dev/RUMBLE-PLAN.md
   - dev/TEXTURE-GLITCH-ANALYSIS.md
   - dev/UNLOCKED-FPS-PLAN.md
   - dev/VIEWMODEL-RESEARCH.md
-  - dev/WIDESCREEN-FOV-PLAN.md
+  - dev/WATCH-SETTINGS-PLAN.md
   - dev/findings-index.csv
   - dev/findings.md
   - dev/game-behavior-reference.md

docs/_includes/head-custom.html

@@ -3,154 +3,196 @@
 
 <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=Libre+Baskerville:ital,wght@0,400;0,700;1,400&display=swap" rel="stylesheet">
+<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;600;700&family=IBM+Plex+Sans:wght@400;600&display=swap" rel="stylesheet">
 
 <style>
   /* ----------------------------------------------------------------------
-     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.
+     Site theme (replaces the 2026-09-28 "night desk" theme).
+     Look: a dark, minimal "amber terminal" -- near-black space background
+     (a faint starfield), a single amber accent (GoldenEye gold), a
+     console/mono identity for chrome (IBM Plex Mono) over a clean
+     readable sans body (IBM Plex Sans). Flat and calm: to reduce eye
+     strain and evoke the old-school web. Content is untouched; this is
+     a presentation layer only.
      --------------------------------------------------------------------- */
   :root {
-    --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;
+    --bg:        #050607;   /* true near-black        */
+    --bg-frame:  #0c0d0f;   /* the page frame         */
+    --bg-panel:  #121316;   /* code / cards / tables  */
+    --ink:       #e6e4df;   /* warm off-white         */
+    --ink-soft:  #a9a7a0;   /* secondary text         */
+    --ink-mute:  #8a8a83;   /* captions, footer (>=4.5:1 on --bg-frame:
+                               the old #70706a measured 3.9:1 and failed
+                               WCAG AA on the tagline + legal line) */
+    --line:      #26282c;   /* 1px borders            */
+    --line-2:    #3a3d44;   /* stronger borders       */
+    --accent:    #e8a13a;   /* GoldenEye gold (amber) */
+    --accent-hi: #ffca7a;   /* link / accent hover    */
+    --code-ink:  #ffcf9e;   /* code text (warm)       */
+    --th:        #15161a;   /* table header fill      */
+    --zebra:     #0e0f12;   /* alt row fill           */
+    --measure:   46rem;
+    --mono: "IBM Plex Mono","Courier New",monospace;
+    --sans: "IBM Plex Sans",Verdana,Geneva,sans-serif;
   }
 
   html { background: var(--bg); }
 
   body {
     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-family: var(--sans);
+    font-size: 15px;          /* 14px read as console chrome, but the
+                                 body is prose people actually read */
+    line-height: 1.6;
+    /* faint starfield (the old-school "space" tile, softened) */
+    background-color: var(--bg);
+    background-image:
+      radial-gradient(1px 1px at 22px 34px,  rgba(255,255,255,.50), transparent),
+      radial-gradient(1px 1px at 120px 82px, rgba(255,255,255,.28), transparent),
+      radial-gradient(1.4px 1.4px at 68px 138px, rgba(232,161,58,.45), transparent),
+      radial-gradient(1px 1px at 172px 44px, rgba(255,255,255,.20), transparent),
+      radial-gradient(1px 1px at 92px 172px,  rgba(255,255,255,.32), transparent);
+    background-size: 200px 200px;
     -webkit-font-smoothing: antialiased;
     text-rendering: optimizeLegibility;
   }
 
-  /* ---- Masthead -------------------------------------------------------- */
-  .site-masthead {
-    background: var(--bg-deep);
-    border-bottom: 1px solid var(--accent);
-  }
-  .masthead-inner {
-    max-width: 52rem;
-    margin: 0 auto;
-    padding: 2.6rem 1.5rem 1.6rem;
-    text-align: center;
-  }
-  .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; }
-
-  /* ---- 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);
-    margin-top: 2.4rem;
-    margin-bottom: 0.9rem;
-  }
-  .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; }
-
-  .doc-content a {
+  a {
     color: var(--accent);
     text-decoration: underline;
-    text-decoration-color: rgba(255, 180, 84, 0.45);
+    text-decoration-color: rgba(232,161,58,.45);
     text-underline-offset: 2px;
   }
-  .doc-content a:hover {
+  a:hover { color: var(--accent-hi); text-decoration-color: currentColor; }
+
+  /* keyboard focus + selection: the amber thread again, so a focused
+     control is visible on the near-black ground (a11y / keyboard users) */
+  :focus-visible {
+    outline: 2px solid var(--accent-hi);
+    outline-offset: 2px;
+  }
+  ::selection { background: var(--accent); color: #0b0b0d; }
+
+  /* ---- the centred "page" frame -------------------------------------- */
+  .frame {
+    max-width: 50rem;
+    margin: 20px auto 32px;
+    background: var(--bg-frame);
+    border: 1px solid var(--line-2);
+    box-shadow: 0 0 0 1px #000, 0 18px 50px -30px #000;
+  }
+
+  /* ---- banner -------------------------------------------------------- */
+  .banner { text-align: center; padding: 2.4rem 1rem 1.4rem; }
+  .banner .t {
+    margin: 0;                /* it is an <h1> now (see the layout) */
+    font-family: var(--mono);
+    font-weight: 700;
+    font-size: 1.7rem;
+    letter-spacing: .05em;
+    color: var(--accent); /* brand name in goldeneye gold -- the amber
+                           thread (masthead -> nav -> rule -> page title) */
+  }
+  .banner .tag { color: var(--ink-mute); font-size: .82rem; margin-top: .55rem; }
+
+  /* ---- top nav row --------------------------------------------------- */
+  .sitenav {
+    text-align: center;
+    padding: .5rem 1rem;
+    font-family: var(--mono);
+    font-size: .78rem;
+    letter-spacing: .05em;
+  }
+  .sitenav a {
+    color: var(--accent);
+    text-decoration: none;
+    padding: 0 .35rem;
+  }
+  .sitenav a:hover { color: var(--accent-hi); text-decoration: underline; }
+  .sitenav .sep { color: var(--ink-mute); }
+
+  /* the amber rule */
+  .rule { border: 0; height: 1px; background: var(--line); margin: 0; }
+  .rule.g {
+    background: linear-gradient(90deg, transparent, var(--accent), transparent);
+    height: 1px; opacity: .55;
+  }
+
+  /* ---- content ------------------------------------------------------- */
+  .doc-content { padding: 1.6rem 1.6rem .6rem; }
+  .doc-content p, .doc-content ul, .doc-content ol,
+  .doc-content blockquote { max-width: var(--measure); }
+
+  .doc-content h1 {
+    font-family: var(--mono);
+    font-size: 1.5rem;
+    font-weight: 700;
+    color: var(--accent);
+    letter-spacing: .02em;
+    margin: .2rem 0 1rem;
+  }
+  .doc-content > h1:first-child { margin-top: .2rem; }
+  .doc-content h2 {
+    font-family: var(--mono);
+    font-size: 1.05rem;
+    font-weight: 600;
+    color: var(--ink);
+    letter-spacing: .03em;
+    margin: 2rem 0 .8rem;
+    padding-bottom: .35rem;
+    border-bottom: 1px solid var(--line-2);
+  }
+  .doc-content h2::before { content: "\25aa  "; color: var(--accent); }
+  /* Page-title look: the 2026-09 SEO pass demoted page headings to h2
+     (the masthead owns h1; no duplicate page titles) -- see the SEO
+     conventions note in scratch/pr-seo-revise-prompt.md. The first
+     content h2 of each page gets the h1 look; presentation only, the
+     heading levels stay per-convention. (On the home page the masthead
+     itself is the title, so its first h2 -- Status -- leads as a section.) */
+  /* .flat-title (front matter on the home page): the masthead IS the
+     page title there, so the first h2 must read as a plain section --
+     otherwise masthead-h1 + amber first-h2 stack as a double header. */
+  .doc-content:not(.flat-title) > h2:first-of-type {
+    font-size: 1.5rem;
+    font-weight: 700;
+    color: var(--accent);
+    margin: .2rem 0 1rem;
+    padding-bottom: 0;
+    border-bottom: 0;
+  }
+  .doc-content h3 {
+    font-family: var(--mono);
+    font-size: .92rem;
     color: var(--accent-hi);
-    text-decoration-color: currentColor;
+    margin: 1.6rem 0 .5rem;
+  }
+  .doc-content > p > em:only-child {
+    font-style: normal; color: var(--ink-soft); font-size: 1.05rem;
   }
 
   .doc-content hr {
-    border: 0;
-    height: 1px;
-    background: var(--accent);
-    opacity: 0.5;
-    margin: 2.5rem 0;
+    border: 0; height: 1px; background: var(--line-2); margin: 2rem 0;
   }
 
   .doc-content blockquote {
     color: var(--ink-soft);
     border-left: 3px solid var(--accent);
-    padding: 0.2rem 0 0.2rem 1.1rem;
+    padding: .2rem 0 .2rem 1rem;
     margin-left: 0;
-    font-style: normal;
   }
 
-  /* Lead paragraph on doc pages (the italic summary under the H1) */
-  .doc-content > p > em:only-child {
-    font-style: normal;
-    color: var(--ink-soft);
-    font-size: 1.05rem;
-  }
-
-  /* ---- Code ------------------------------------------------------------ */
+  /* ---- code ---------------------------------------------------------- */
   .doc-content code {
-    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
-    font-size: 0.86em;
-    background: var(--bg-soft);
+    font-family: var(--mono);
+    font-size: .86em;
+    background: var(--bg-panel);
     border: 1px solid var(--line);
-    padding: 0.12em 0.4em;
-    color: var(--ink);
+    padding: .1em .4em;
+    color: var(--code-ink);
   }
   .doc-content pre {
-    background: var(--bg-deep);
+    background: var(--bg-panel);
     border: 1px solid var(--line);
     padding: 1rem 1.15rem;
     max-width: var(--measure);
@@ -158,105 +200,169 @@
     line-height: 1.55;
   }
   .doc-content pre code {
-    background: transparent;
-    border: 0;
-    padding: 0;
-    color: var(--ink);
-    font-size: 0.84rem;
+    background: transparent; border: 0; padding: 0;
+    color: var(--code-ink); font-size: .84rem;
   }
 
-  /* ---- Tables ----------------------------------------------------------- */
+  /* ---- tables -------------------------------------------------------- */
   .doc-content table {
-    border-collapse: collapse;
-    width: 100%;
-    max-width: var(--measure);
-    margin: 1.5rem 0;
-    font-size: 0.92rem;
+    border-collapse: collapse; width: 100%;
+    max-width: var(--measure); margin: 1.5rem 0; font-size: .9rem;
   }
-  .doc-content table th,
-  .doc-content table td {
-    border: 1px solid var(--line);
-    padding: 0.5rem 0.75rem;
-    text-align: left;
+  .doc-content th, .doc-content td {
+    border: 1px solid var(--line); padding: .5rem .7rem; text-align: left;
   }
-  .doc-content table th { background: var(--bg-soft); font-weight: 600; }
-  .doc-content table tr:nth-child(2n) { background: #1f1f22; }
+  .doc-content th {
+    background: var(--th); color: var(--accent);
+    font-family: var(--mono); font-size: .74rem;
+    letter-spacing: .05em; font-weight: 600;
+  }
+  .doc-content tr:nth-child(2n) td { background: var(--zebra); }
 
-  /* ---- Images & gallery -------------------------------------------------- */
-  .doc-content img {
+  /* ---- console blocks ------------------------------------------------ */
+  /* Status / News / Download / Known issues panels (home page). Same
+     amber-terminal language as the code blocks above, but the content
+     keeps its semantic list/table markup (SEO + screen readers).
+
+     Site formatting rules (2026-10-05 PR pass + 2026-09 SEO conventions)
+     — keep these:
+     - Heading LEVELS follow the SEO pass: the page heading is h2 (the
+       masthead owns h1; no duplicate page titles), sections are h2,
+       h3 labels a real sub-topic only (e.g. the current-release line
+       under Status). The first content h2 gets the amber "page-title"
+       look via CSS only (.doc-content > h2:first-of-type) -- never by
+       promoting the markup to h1.
+     - h2 = the section, outside the panel.
+     - Directives ("always use the latest release") are .callouts inside
+       panels, or a .warn line (amber rule, ink text) where no panel
+       exists; never headings — headings label topics,
+       never emphasis.
+     - List intros ("what a player will notice…") stay plain paragraphs.
+     - Dated list-item leads ("2026-10-05 — v0.5.0") stay <strong> leads
+       inside the <li>, not headings.
+     - Headings must be single source lines: marked ends an ATX heading at
+       the line break, so a wrapped "### …" silently becomes a heading plus
+       a stray paragraph (Jekyll/other renderers differ — don't rely on
+       multi-line headings at all). */
+  .doc-content .cblock {
+    background: var(--bg-panel);
     border: 1px solid var(--line);
-    border-radius: 0;
-    max-width: 100%;
+    padding: 1.1rem 1.3rem .9rem;
+    margin: 1.6rem 0;
   }
 
+  /* Expandable panels (<details>, e.g. the release history folded under
+     Status): same panel language as .cblock; the summary line is the
+     amber handle. The content is in the DOM either way -- collapsing is
+     presentation, not hiding from search. */
   .doc-content details {
-    max-width: var(--measure);
+    background: var(--bg-panel);
     border: 1px solid var(--line);
-    background: var(--bg-soft);
-    padding: 0.6rem 0.9rem;
-    margin: 1.5rem 0;
+    padding: .3rem 1.3rem .8rem;
+    margin: 1.6rem 0;
   }
-  .doc-content summary { cursor: pointer; color: var(--accent); }
+  .doc-content summary {
+    font-family: var(--mono);
+    font-size: .9rem;
+    font-weight: 600;
+    color: var(--accent);
+    letter-spacing: .03em;
+    cursor: pointer;
+  }
+  .cblock h3 { margin-top: 0; color: var(--ink); }
+  .cblock p, .cblock ul, details p, details ul {
+    font-family: var(--mono);
+    font-size: .88rem;
+    line-height: 1.6;
+  }
+  .cblock li, details li { margin: .5rem 0; }
+  .cblock li::marker, details li::marker { color: var(--accent); }
+  .cblock strong, details strong { color: var(--accent); font-weight: 600; }
+  .cblock code, details code { background: transparent; border: 0; padding: 0; }
+  .doc-content .callout {
+    border-left: 3px solid var(--accent);
+    padding: .15rem 0 .15rem .8rem;
+    margin: 0 0 1rem;
+  }
+  .doc-content .callout p { color: var(--ink-soft); }
 
-  /* ---- Footer ------------------------------------------------------------- */
-  .site-footer {
-    max-width: 52rem;
-    margin: 3rem auto 0;
-    padding: 1.5rem 1.5rem 2.5rem;
-    border-top: 1px solid var(--line);
+  /* Inline directive marker -- "Warning:" leading a sentence, amber like
+     the rest of the accent thread, no panel around it. */
+  .doc-content details .warn {
+    border-left: 3px solid var(--accent);
+    padding: .1rem 0 .1rem .7rem;
+    margin: .2rem 0 .9rem;
+    font-weight: 600;
   }
-  .footer-inner { max-width: var(--measure); }
+  .cblock table { background: transparent; margin: 1rem 0 .4rem; }
+  .cblock > p:last-child { margin-bottom: 0; }
+
+  /* ---- images -------------------------------------------------------- */
+  .doc-content img {
+    border: 1px solid var(--line); border-radius: 0; max-width: 100%;
+    height: auto;                 /* no squashed stills when a width= is set */
+  }
+
+  /* ---- console-viewer carousel (home page media) --------------------- */
+  .viewer {
+    max-width: 38rem; margin: 1rem auto;
+    border: 1px solid var(--line-2);
+    background: var(--bg-panel);
+    font-family: var(--mono);
+  }
+  .viewer .vbar {
+    display: flex; align-items: center; gap: .5rem;
+    padding: .4rem .6rem; border-bottom: 1px solid var(--line);
+    font-size: .72rem; color: var(--ink-mute); letter-spacing: .05em;
+  }
+  .viewer .vbar .dots { display: flex; gap: .3rem; }
+  .viewer .vbar .dots i {
+    width: 8px; height: 8px; border: 1px solid var(--line-2);
+    display: inline-block;
+  }
+  .viewer .vbar .dots i:nth-child(1) { border-color: var(--accent); }
+  .viewer .vbar .lbl { flex: 1; }
+  .viewer .vbar .idx { color: var(--accent); }
+  .viewer .vstage { position: relative; background: #000; aspect-ratio: 16 / 9; }
+  .viewer .vstage img { width: 100%; height: 100%; object-fit: contain; display: block; }
+  .viewer .vbtn {
+    position: absolute; top: 50%; transform: translateY(-50%);
+    background: rgba(6,7,8,.55);
+    border: 1px solid var(--line-2);
+    color: var(--accent);
+    font-family: var(--mono); font-size: 1.3rem; line-height: 1;
+    width: 34px; height: 52px; cursor: pointer; padding: 0;
+  }
+  .viewer .vbtn:hover { color: var(--accent-hi); border-color: var(--accent); }
+  .viewer .vbtn.prev { left: 0; }
+  .viewer .vbtn.next { right: 0; }
+  .viewer .vcap {
+    display: flex; justify-content: space-between; align-items: center;
+    padding: .45rem .6rem; border-top: 1px solid var(--line);
+    font-size: .74rem; color: var(--ink-soft); letter-spacing: .02em;
+  }
+
+  /* ---- footer -------------------------------------------------------- */
+  .site-footer { text-align: center; padding: 1.2rem 1rem 1.6rem; }
   .footer-stamp {
-    color: var(--ink-soft);
-    font-size: 0.88rem;
-    margin: 0 0 0.8rem;
+    font-family: var(--mono); font-size: .78rem;
+    letter-spacing: .03em; color: var(--ink-soft);
+    margin: 0 0 .7rem;
   }
   .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;
+    color: var(--ink-mute); font-size: .72rem; line-height: 1.55;
+    margin: 0 auto; max-width: var(--measure);
   }
 
-  @media (max-width: 42rem) {
-    .masthead-title { font-size: 1.7rem; }
-    .masthead-inner { padding: 2rem 1rem 1.2rem; }
-    .doc-content { padding-top: 1.8rem; }
+  @media (max-width: 40rem) {
+    .frame { margin: 8px; }
+    .banner { padding: 1.4rem .8rem 1rem; }
+    .banner .t { font-size: 1.35rem; }
+    .doc-content { padding: 1.1rem 1rem .5rem; }
+    .doc-content table { font-size: .82rem; }
+    .doc-content pre { padding: .7rem .8rem; }
   }
 
-  /* ---- 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 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;
-  }
-  .doc-content pre.mermaid { text-align: center; overflow-x: auto; }
-  .doc-content pre.mermaid:not([data-processed]) { visibility: hidden; }
 </style>
-
-<script type="module">
-  import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
-
-  // Move each ```mermaid code block's text into a <pre class="mermaid"> that
-  // mermaid.run() recognises.
-  document.querySelectorAll("pre > code.language-mermaid").forEach((code) => {
-    const pre = document.createElement("pre");
-    pre.className = "mermaid";
-    pre.textContent = code.textContent;
-    code.parentElement.replaceWith(pre);
-  });
-
-  mermaid.initialize({
-    startOnLoad: false,
-    securityLevel: "loose", // our own docs; needed for <br/> in node labels
-    theme: "dark",
-  });
-  mermaid.run({ querySelector: "pre.mermaid" });
-</script>

docs/_layouts/default.html

@@ -3,46 +3,69 @@
 <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 }}">
+  <!-- Paint the browser chrome (scrollbars, form controls, new-tab cards)
+       dark before CSS loads, so the page never flashes white on mobile. -->
+  <meta name="color-scheme" content="dark">
+  <meta name="theme-color" content="#050607">
+  <!-- Indexing is NOT restricted: this only asks Google/Bing to show the
+       large image preview in search cards, which is what makes the
+       in-engine stills legible in a coverage roundup. -->
+  <meta name="robots" content="max-image-preview:large">
+  <!-- Favicon: the project's own crosshair mark (tools_pc/make_icon.py),
+       not a game still -- original art, no derivative-work exposure. -->
+  <!-- favicon.ico is a byte copy of cmake/icon/ge007.ico (the exe icon, with
+       the hand-tuned 16/24/32 px variants); a browser-downscaled 512 px PNG
+       washes out at tab size. Re-copy it after running make_icon.py. -->
+  <link rel="icon" href="{{ '/favicon.ico' | relative_url }}" sizes="16x16 24x24 32x32 48x48 64x64 128x128 256x256">
+  <link rel="apple-touch-icon" sizes="512x512" href="{{ '/img/icon/ge007-icon.png' | relative_url }}">
+  <!-- Entity disambiguation: the maintainer behind every page. -->
+  <link rel="me" href="https://github.com/jkdansereau">
   {%- 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>
+  <div class="frame">
 
-  <main class="doc-content">
-    {{ content }}
-  </main>
+    <!-- The masthead IS the page's h1: every page gets exactly one h1
+         (the brand), and the page's own heading starts at h2. A <div>
+         here left the document with no h1 at all, which is what search
+         and screen readers key on. Presentation only -- the CSS class
+         carries the look. -->
+    <header class="banner">
+      <h1 class="t">{{ site.title }}</h1>
+      <p class="tag">{{ site.description }}</p>
+    </header>
 
-  <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>
+    <nav class="sitenav" aria-label="Site navigation">
+      <a href="{{ '/' | relative_url }}">home</a><span class="sep">/</span>
+      <a href="{{ '/documentation' | relative_url }}">documentation</a><span class="sep">/</span>
+      <a href="{{ '/building' | relative_url }}">building</a>
+    </nav>
+    <div class="rule g"></div>
+
+    <!-- flat_title: this page's masthead IS its title, so the layout opts
+         out of the amber first-h2 "page-title" look (no double header).
+         Jekyll + the preview builder both honour this conditional. -->
+    <main class="doc-content{% if page.flat_title %} flat-title{% endif %}">
+      {{ content }}
+    </main>
+
+    <div class="rule g"></div>
+
+    <footer class="site-footer">
+      <div class="footer-stamp">
+        <a href="https://github.com/jkdansereau">maintained by jkdansereau</a>
+        &nbsp;&middot;&nbsp; last updated: 2026-10-13 &middot; v0.6.0
+        &nbsp;&middot;&nbsp; <a href="https://github.com/jkdansereau/goldeneye-pc-port">GitHub</a>
+        &nbsp;&middot;&nbsp; <a href="https://github.com/jkdansereau/goldeneye-pc-port/releases">releases</a>
+      </div>
+      <div 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.
+      </div>
+    </footer>
+
+  </div>
 </body>
 </html>

docs/about.md

@@ -0,0 +1,225 @@
+---
+title: About the project
+description: Release history, how the GoldenEye 007 PC port was made, how it works, and how it differs from the other GoldenEye PC projects.
+---
+
+# About the project
+
+- [Release history](#release-history)
+- [Status in detail](#status-in-detail)
+- [How it was made](#how-it-was-made)
+- [How it works](#how-it-works)
+- [How this differs from the other GoldenEye PC projects](#how-this-differs-from-the-other-goldeneye-pc-projects)
+
+
+## Release history
+
+The full notes for each version are on the [Releases page](https://github.com/jkdansereau/goldeneye-pc-port/releases).
+
+- **2026-10-13** — **v0.6.0** ([release notes](https://github.com/jkdansereau/goldeneye-pc-port/releases/tag/v0.6.0)):
+  - **Frame rates above 60.** `Video.FpsCap` now offers 90, 120, 144, 165 and
+    240, and an **Auto** setting (the new default on fresh installs) that
+    matches your display's refresh rate, up to 240. Frames between game ticks are blended from the
+    previous and current frame; the game still simulates at its original
+    rate. It costs one game tick of extra latency, does nothing on a 60 Hz
+    display, and the *Original N64* preset caps at 60. This is a rework of
+    f1zz1ec0ke's #137. I checked 120 Hz with VSync on a G-Sync display
+    on PC and 90 fps on the Steam Deck.
+  - **macOS on Apple Silicon (experimental).** There is now a `macos-arm64`
+    download (or build from source; see [Building](building.md)). Based
+    on danturn's #95 (with Julio C. Rocha's earlier Intel groundwork in
+    #88). Tested with a 21-level sweep and live sessions on one M3 Mac (the
+    one crash seen, in the end credits, is guarded in this release); the download is not notarized, so see [macOS](user-guide.md#macos-apple-silicon-experimental)
+    for the one-line unblock. Test reports are very welcome.
+  - **Fixes:** geometry vanishing when you press against a wall (#150),
+    the first launch opening on the wrong monitor (#151), a crash in the end
+    credits on Linux and macOS (#152), a crash when a guard spawns with a hat (#153, #156), a
+    sound/text pointer check that rejected valid pointers (#108), a Cradle
+    catwalk shadow flicker, stale pixels beside the widescreen picture on
+    front-end screens, and a black window on macOS when the game was started
+    with the display asleep.
+  - **Original controls (#145, #149):** with *Control style* set to Original,
+    a gamepad now behaves as an N64 controller (South = A, West = B, the game
+    decides what each does), and *Invert look* works in every original style.
+    Also an optional mission timer (#144), the file-select crest no longer
+    drawing on a dark square (#146), and a fix for a Windows blue screen on
+    exit.
+  - **Smaller changes:** the legacy front-end Velocity pointer mode is gone,
+    the Linux/macOS update check no longer fails on a large response, every
+    run is also logged to `ge007.log` next to the ini, and F10 slider labels
+    fit at HUD 150.
+  - **Known issues on the Steam Deck at 90 fps:** firefights in the centre of
+    Bunker 1 and 2 can drop several fps, and Jungle can feel slightly less
+    smooth than other levels. Cradle's turret explosions may draw wrongly
+    (reported, not yet investigated).
+- **2026-10-07** — **v0.5.0** ([release notes](https://github.com/jkdansereau/goldeneye-pc-port/releases/tag/v0.5.0)), the first release
+  since v0.4.0; it includes the v0.4.1 work, which was never published on
+  its own:
+  - **Split-screen multiplayer for up to 4 players**, each player with their
+    own pad, controls and aim settings.
+  - **One options menu** for every setting, laid out like the Perfect Dark
+    port's, with the game's own crosshair as the mouse pointer. Pick the
+    game's own N64 control styles (1.1–2.4) per player, or the Xbox release's
+    presets with per-player pad rebinding; PlayStation and Nintendo pads show
+    their own button names.
+  - **Closer to the N64:** fog and haze (Surface 2's ground fog, the sky at
+    the horizon), automatic-weapon fire rate, sniper and camera zoom, Dam and
+    Caverns water, the Jungle boss fight's timing, guard visibility in
+    widescreen, and the Dam ending camera.
+  - **Fewer crashes and glitches:** a multiplayer crash with the crouched
+    rifle, rockets passing through the ground, and broken geometry around
+    Aztec's shuttle.
+  - **A steady 60 fps on low-end GPUs** (tested on an Intel HD 3000 laptop),
+    with lighter first-launch defaults on Atom/Celeron-class graphics.
+  - **Emulator saves load directly:** copy a 1964 or Project64 save in as
+    `data/ge007.eep` and it is converted on first launch.
+  - Also: more audio, video and control settings (master volume, audio device,
+    trilinear filtering, draw distance up to 800%, PC-friendly crouch and
+    look-ahead defaults), and controllers are picked up again when replugged.
+- **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).
+- **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.
+
+## Status in detail
+
+**Fully playable, with a small set of known caveats.** All 20 solo missions
+and the end-of-campaign credits load, render and run crash-free. For v0.6.0
+the release downloads themselves were tested on Windows, Steam Deck (Desktop
+and Game Mode), macOS on Apple Silicon and a 2011 Linux laptop: a fresh
+folder with only the ROM, a first launch, then all 21 solo levels. The new frame-rate path and the listed fixes were also checked by
+playing on Windows and the Steam Deck. The full campaign was last played end
+to end, at Agent difficulty on Windows, Linux and the Deck, for v0.4.0.
+Split-screen was played live in 2P on every multiplayer map and in 4P on
+Temple.
+
+**Known issues:** see the **[known-issues table](ROADMAP.md#known-issues)**
+(what you'll notice, impact, workarounds). The short version: NTSC-U ROMs
+only in the release packages, and the Apple Silicon macOS download is
+experimental and not notarized. On the Steam Deck at 90 fps, Bunker 1/2
+centre firefights can drop several fps and Jungle can feel slightly less smooth
+than other levels.
+
+> ***All unlocked* never changes your save** since v0.5.0: it unlocks every
+> level and cheat in memory only, and switching it off shows your real
+> progress. v0.4.0 and earlier could write fake unlocks into the save, and
+> those are not repaired; if you used it on an older build, keep a backup of
+> `data/ge007.eep`.
+
+What a release installs (no networking unless you turn on the opt-in update check, which is off by default and makes one HTTPS request to GitHub per launch; no telemetry, no ROM or game assets)
+and how faithfully the port tracks the original game's logic:
+[Security](security.md) and [fidelity](fidelity.md) status.
+The binaries are not code-signed; from v0.5.0 on each release artifact also
+carries a GitHub build-provenance attestation you can check with
+`gh attestation verify <file> --repo jkdansereau/goldeneye-pc-port`
+(see [SECURITY.md](../.github/SECURITY.md)).
+
+## How it was made
+
+The port was built by several coding agents directed by one maintainer, with
+contributions from a handful of people (credited in the release notes).
+A local open-weight model (`unsloth/Qwen3.8-27B-GGUF` on one RTX 5090, via the
+[pi](https://github.com/earendil-works/pi) agent) did the groundwork: build, boot chain,
+software-RSP integration, asset pipeline, first frames. **Claude Code**
+(Sonnet 5 and Opus 5, now 5.5; Opus for the hardest bugs) joined for the collaborative phase:
+the 21-level sweep, the ABI finding catalog, SDL input, front end. The two
+handed work back and forth through shared written notes. Up to v0.5.0: 51
+days (16 Aug – 6 Oct), 1,537 commits (the public history squashes the
+v0.4.1–v0.5.0 work into 17), and 419 findings root-caused and logged
+(`D1`–`D564`). Every change is checked by comparing captured frames from all
+21 solo levels against reference images, crash sweeps on Windows, Linux,
+Steam Deck and macOS, and play-testing; there is no unit-test suite.
+
+The full write-up (timeline, handoff mechanism, effort breakdown, an honest
+"what worked / what didn't"): [`docs/dev/agentic-development.md`](dev/agentic-development.md).
+The workflow itself: [`docs/dev-process.md`](dev-process.md). To cite the
+project or its findings: [`CITATION.cff`](../CITATION.cff) (GitHub's "Cite this
+repository" menu).
+
+### Tools and models used to develop the port
+
+Development ran for most of its life on a single local model — **Unsloth's
+Qwen 3.8 27B** — which did nearly all of the local (groundwork) work on its
+own. In the final week that grew into a small menu, and the **current standard
+is NInfer + Strata**; tools are chosen per task, with local models carrying
+the high-volume work and hosted models the exception. The full record of the
+models used, and the harnesses that drove them:
+
+| Model | Ran as | How it was used |
+|---|---|---|
+| **Qwen 3.8 27B** ([Unsloth](https://huggingface.co/unsloth/Qwen3.8-27B-GGUF)) | `UD-Q4_K_XL`, one RTX 5090 | The primary local workhorse for the bulk of the port's development. |
+| **Qwen 3.8 27B** via [NInfer](https://github.com/natpate/ninfer-windows) (Windows) | base, NVFP4 and NVFP4-full artifacts; MTP (DFlash2) spec-decode; one 5090 | Trialed in the final week, now half of the standard; the fast day-to-day local driver. |
+| **Qwen 3.8 27B** ([ISTA-DASLab](https://huggingface.co/ISTA-DASLab/Qwen3.8-27B-GSQ-RCO-GGUF)) | `IQ3_S` (GSQ-RCO), larger context | Briefly trialed for larger-context workloads; shelved, little use since v0.2.0. |
+| **Qwen 3.8 Flash-Next** via [Strata](https://github.com/Niko1221/Strata) | 125B MoE, `IQ1_M` (1-bit), one gaming GPU | The big-context local tier: a model that normally needs a server, run locally for the largest-context passes. |
+| **Claude** (Anthropic) | Sonnet 5 / Opus 5, now **Sonnet 5.5 / Opus 5.5** (out in the last few weeks) | The orchestrator in the two-agent phase: held what the 27B couldn't close, took over on limit handoff; the 5.5 tier has driven the most recent work. |
+| **GPT-6 (Sol)** (OpenAI), via [OpenRouter](https://openrouter.ai) | a frontier hosted model | Trialed. |
+
+*Harnesses and tooling:*
+
+- **[pi](https://github.com/earendil-works/pi)** — the local coding-agent
+  harness that drives the local models.
+- **[Claude Code](https://github.com/anthropics/claude-code)** (Anthropic) —
+  the agentic harness that drove the Claude models above; the orchestrator in
+  the two-agent phase.
+- **[claude-code-delegate-local](https://github.com/fegone/claude-code-delegate-local)** —
+  the MCP bridge that let Claude and the local models talk (delegating Claude's
+  subagents to the local engines).
+
+## How it works
+
+The game code in `src/` is the decompilation's, and its control flow is the
+reference we preserve. Everything that would touch N64 hardware is redirected into
+`port/`: a **software RSP** (`port/fast3d/`, adapted from the Perfect Dark
+port) that interprets the graphics command stream (the GBI display list)
+the game builds each frame and
+emits OpenGL, bypassing the RDP; libultra OS shims (`port/src/libultra.c`,
+game threads as real host threads) that let the game's own scheduler run,
+with the software RSP on its own render thread as the RSP was its own chip;
+and SDL2/OpenGL/filesystem backends for video, audio, input and storage.
+Every port change inside `src/` is gated behind `#ifdef PORT` and
+documented. They are few in kind, all narrow in scope: mechanical 32→64-bit
+pointer/struct fixes (the pointer-width transition touches many structs, so
+there are a lot of them), a few maintainer-approved timing fixes where
+per-frame N64 code ran too fast at the PC's 60 fps (for example sniper zoom
+and turret fire), the opt-in *All unlocked* hook, and env-gated diagnostic
+probes tied to the bug catalogue (off by default, no behavior change). Where it diverges from the Perfect Dark port: GoldenEye's N64
+serialized asset formats are converted in a separate step rather than
+fixed up at load time — on first start for a download, or by the offline
+Python converters in `tools_pc/` for a source build. Full detail:
+[`docs/internals.md`](internals.md) and
+[`docs/porting-notes.md`](porting-notes.md).
+
+```
+CMakeLists.txt      PC build (parallel to the decomp's Makefile, which is untouched)
+build-pc.sh         configure + build helper
+src/  include/      the decompilation (game + libultra); port edits are #ifdef PORT
+port/
+  fast3d/           software RSP -> OpenGL
+  src/              port layer (main, OS shims, video, audio, input, fs, ...)
+  include/          port-facing headers
+tools/  Makefile    the N64 build + asset extraction (from the decomp; do not modify)
+tools_pc/           PC-port helper + analysis scripts
+docs/               see below
+```
+
+## How this differs from the other GoldenEye PC projects
+
+This is a native port of the original 1997 Nintendo 64 game, built from its
+reconstructed source code, the same lineage as the Perfect Dark PC port.
+Other GoldenEye PC projects take a different approach: they statically
+recompile the Xbox 360 XBLA remaster, a separate version of the game with its
+own codebase. The two don't share code, and they target different versions
+of the game.
+
+| | This project | The XBLA recompilation projects |
+|---|---|---|
+| **What it ports** | The original **Nintendo 64** game (1997) | The **Xbox 360 XBLA** remaster |
+| **How** | Decompilation-based source port: reconstructed C, compiled for the host | Static recompilation of the Xbox 360 executable |
+| **Lineage** | [GoldenEye 007 decompilation](https://github.com/n64decomp/007) + [Perfect Dark PC port](https://github.com/fgsfdsfgs/perfect_dark) engine family | The Xbox 360 static-recompilation family |

docs/building.md

@@ -1,6 +1,6 @@
 ---
 title: Building
-description: Full build and asset-extraction guide for the GoldenEye 007 PC port, covering Windows (MSYS2) and Linux.
+description: Full build and asset-extraction guide for the GoldenEye 007 PC port on Windows, Linux, and macOS.
 ---
 
 ## Building the PC port
@@ -18,7 +18,7 @@ Stages:
    files the port loads at runtime. **Required to run.**
 
 You need a GoldenEye 007 N64 ROM you legally own (`.z64`, big-endian). See the
-[Requirements table in the README](https://github.com/jkdansereau/goldeneye-pc-port#requirements)
+[ROM table in the user guide](user-guide.md#whats-a-rom)
 for accepted versions and hashes.
 
 ---
@@ -27,21 +27,36 @@ for accepted versions and hashes.
 
 ### Port build
 
-> **The Windows (MSYS2 MINGW64) path is the primary one.** The Linux build is
-> compiled by CI on every push and ships in the release bundle (also
-> playtested on Steam Deck hardware); the macOS column is best-effort
-> guidance and has never been built or run there. Expect to fix build breaks
-> yourself on untested platforms.
+> **The Windows (MSYS2 MINGW64) path is the primary one.** Linux is compiled
+> by CI and ships in the release bundle. **macOS on Apple Silicon is
+> experimental as of v0.6.0**: the release has a `macos-arm64` download
+> (`scripts/package-macos.sh` makes it on a Mac; CI runs it) that is not
+> notarized, so clear the quarantine flag once before the first launch with
+> `xattr -dr com.apple.quarantine <folder>`. This guide covers building it from
+> source. On an arm64 Mac the build moves the N64 address window to a
+> high host base (`PORT_ADDR_BASE`, set automatically); Windows and Linux builds
+> are unaffected. The x86_64 macOS path (Julio C. Rocha, #88) is still in the
+> tree but was never verified on Intel hardware.
 
 | Need | Windows (MSYS2 MINGW64) | Debian/Ubuntu | macOS (Homebrew) |
 |------|------------------------|---------------|------------------|
-| toolchain | `mingw-w64-x86_64-toolchain` | `build-essential` | Xcode CLT / `gcc` |
+| toolchain | `mingw-w64-x86_64-toolchain` | `build-essential` | Xcode CLT + Homebrew `gcc` |
 | CMake | `mingw-w64-x86_64-cmake` | `cmake` | `cmake` |
 | SDL2 | `mingw-w64-x86_64-SDL2` | `libsdl2-dev` | `sdl2` |
 | zlib | `mingw-w64-x86_64-zlib` | `zlib1g-dev` | `zlib` |
 | OpenGL | (in the toolchain) | `libgl1-mesa-dev` | (system) |
 | Python 3 | `mingw-w64-x86_64-python` | `python3` | `python3` |
 
+On macOS, install the build dependencies with:
+
+```sh
+brew install cmake gcc sdl2 zlib python3
+```
+
+The project requires real GNU GCC for the decomp's Plan 9 struct extensions.
+Apple's `/usr/bin/gcc` is Clang and is not compatible. CMake automatically
+selects Homebrew's versioned `gcc-N`/`g++-N` executables.
+
 ### Asset extraction (decompilation toolchain)
 
 The extraction scripts need `binutils-mips-linux-gnu` (or an equivalent MIPS
@@ -51,7 +66,7 @@ toolchain is involved in extraction or in the PC build.** (The IDO toolchain is
 only needed to build the N64 ROM itself, and its proprietary SGI binaries are
 not distributed here; see [`SetupGuide.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/SetupGuide.md) "Recompile IDO".)
 On Windows this is easiest under WSL or a Linux VM. Full details and
-alternatives (Docker) are in [`SetupGuide.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/SetupGuide.md).
+alternatives (Docker) are in `SetupGuide.md`.
 
 ---
 
@@ -93,6 +108,15 @@ cmake -S . -B build-pc -DROMID=ntsc-final
 cmake --build build-pc -j
 ```
 
+On Windows, `build-pc.sh` also locates the MSYS2 MinGW64 toolchain itself
+(so it works from Git Bash or a non-login shell too, even with another
+`cmake` earlier on PATH) and, if native child processes would get an
+unwritable `TMP`, re-runs the configure+build under PowerShell with a
+writable one. If MSYS2 is not installed at `C:\msys64`, set
+`GE_MSYS2_ROOT` (e.g. `GE_MSYS2_ROOT='C:\tools\msys64'` for a custom
+install location). Re-exec logs:
+`build-pc/ge007-native-reexec-*.log`.
+
 For PAL/JP you must first generate that region's ROM-asset symbol file
 (the US one is committed):
 
@@ -128,11 +152,15 @@ to d69's output):
 ```sh
 python3 tools_pc/d43_emit.py ntsc-final          # -> data/pcmodels-ntsc-final/{pcmodels.bin,manifest.csv}  (~1.3 MB)
 python3 tools_pc/d69_emit.py ntsc-final          # -> data/pccg-ntsc-final/{pccg.bin,manifest.csv}          (bg + stan)
-python3 tools_pc/d88_emit.py ntsc-final --regen  #    appends the 21 per-level Usetup*Z stage-setup files -> ~3.6 MB
+python3 tools_pc/d88_emit.py ntsc-final --regen  #    appends the 21 solo Usetup*Z + 13 multiplayer Ump_setup*Z stage-setup files -> ~3.6 MB
 ```
 
-**PAL / JP note:** sidecar generation for these regions is currently broken at
-the source-data level (finding D258); use an NTSC-U ROM until issue #85 lands.
+**PAL / JP note:** both regions convert, build and boot from source (finding
+D258, fixed 2026-10-02; D487/D488 fixed the PAL frame height and TV type).
+Run the three emit passes with `pal-final` or `jpn-final`, and build into a
+separate directory, for example `BUILD_DIR=build-pal ./build-pc.sh pal-final`.
+Release packages are still NTSC-U only until per-region packaging lands
+(issue #85).
 
 These are **pure-stdlib Python 3** (no MIPS toolchain, independent of the
 step-2 asset extraction) and read only the ROM plus files already committed to

docs/dev-process.md

@@ -185,6 +185,13 @@ justifies. Rules:
   spend a cycle rebasing it**; re-derive only whatever part of its content
   is still true as a fresh, small PR against current `main`. Merging stale
   content back over newer information is a regression, not a save.
+- **Commit/tree hygiene is a standing rule, not a per-session judgment** —
+  see AGENTS.md §Tree hygiene & release gate. In short: no local absolute
+  paths or usernames in tracked files (use the placeholder convention), no
+  contributor emails in prose (name + PR number), every vendored third-party
+  license declared in `NOTICE`, no bulk ROM-derived captures in the tree
+  (capture output dirs are gitignored — keep them on disk, untracked), and
+  one batched commit per session rather than one per approved fix.
 
 ## 7. The rule-2 sign-off procedure (genuine `src/game` behavior changes)
 
@@ -248,6 +255,62 @@ 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.
 
+## 8. LLM session discipline (model tiers, data-before-edit, context resets)
+
+Standing rules for LLM-agent sessions, fixed 2026-10-09 after the session
+forensics on the #150 cull hunt (pi session `01a11ec6`, 2026-10-09): a
+27B 4-bit-quantized default model spent an evening firing unvalidated
+render fixes at the maintainer for A/B (four consecutive failures), and
+the mid-session compaction summary promoted an unvalidated hypothesis to
+"diagnosed" — the post-compaction turns then built three more fix
+candidates on that false premise. The loss was model + discipline, not
+retrieval; the rules below are the zero- and low-cost countermeasures.
+
+- **Model tiers.** Planning, diagnosis, and anything that touches a
+  contested claim run on the strongest model available — the frontier
+  `openrouter/deepseek/deepseek-v4-pro` (no local contention) or, with
+  the local backend switched, `strata-coder-hard`. Only ONE local backend
+  can run at a time (ninfer ↔ strata), so the **standing backend is ninfer** and the
+  session default is its model (`qwen3.8-27b-nvfp4full`, the
+  `ninfer-coding.bat` 4-bit daily driver). The strong *local* tier is
+  the same backend under `ninfer-quality.bat` (groupwise-int
+  `qwen3.8-27b`, 200k ctx) — a launcher restart, not a backend
+  switch; the strata 125B remains the top local option at the cost of a
+  full switch. Mechanical labor — builds, captures,
+  log triage, golden sweeps, doc sync — goes to the ninfer models via
+  the model-pinned subagent roles in the `pi/` package (see
+  `pi/README.md`): 4-bit for build/capture/triage/doc-sync, and
+  `pairing` pinned to `inherit` so the reasoning step follows the
+  parent session’s tier. 4-bit is never a planning or diagnosis model.
+- **Data before edit.** If a probe log for the current hypothesis
+  already exists on disk, the next action is *analyzing it*, not building
+  another fix candidate. The maintainer gates only the final candidate;
+  intermediate variants are judged by the golden sweep (regressions are
+  machine-detected), not by maintainer A/B — one A/B is the gate, not
+  the test harness.
+- **Context resets.** After a second failed maintainer A/B, or after a
+  compaction whose state is contested, do not continue the session: write
+  a HANDOFF brief and start a fresh session from it. Compaction summaries
+  must carry an **evidence ledger** — one line per live hypothesis tagged
+  `refuted` / `unvalidated` / `validated (<artifact: log, golden frame,
+  maintainer A/B, commit>)`, and `"diagnosed"` is forbidden for any fix
+  lacking a maintainer A/B or a passing golden sweep. The
+  `pi/extensions/compaction-ledger/` extension encodes this prompt (and,
+  with `GE_COMPACT_MODEL`, summarizes on a stronger model than the
+  session's labor model).
+- **Regression triage first.** Before any probe or theory on a bug,
+  ask when it first appeared. If a release window is known, list the
+  commits in `git log <good>..<bad>` that touch the subsystem and run the
+  off switch each of them shipped with, one run per switch. The #150
+  wall-hug see-through (D579) spent days on cull/ucode/guard-band probes; a
+  single `GE_NEARCLIP=0` run named the v0.5.0 feature (D543) and the fix
+  was one line. Corollaries: when an A/B refutes a layer, leave that layer;
+  when a probe shows the code behaving correctly, pivot instead of probing
+  deeper; a delegated decode is a cross-check, never the lead.
+- **Briefs are mandatory** (§1): no investigation kickoff without a
+  BUDGET line and a filled brief template — including the MODEL line
+  below, so the tier choice is visible in the brief itself.
+
 ## Investigation-brief template
 
 ```
@@ -256,6 +319,8 @@ READ FIRST: docs/porting-notes.md; docs/dev/findings.md <specific Dxx entries>.
 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>.
+MODEL: <tier + model id, per §8 — planning/diagnosis on the strong
+  model; mechanical labor delegated to the pi/ subagent roles>.
 BUDGET: <N build->run cycles / ~M min>. On expiry: revert probes, write up with confidence.
 CONSTRAINTS: diagnosis may trace as deep into src/game state as the evidence
   needs — name the exact struct/field/logic responsible before concluding

docs/dev/AUDIO-PLAN.md

@@ -1,5 +1,7 @@
 # AUDIO-PLAN — Phase 3 / ROADMAP B3 (libaudio → SDL)
 
+> **Historical record — do not act on status claims in this file.** The audio track shipped (D198–D204); the "gaps" and TODOs described below are closed. Kept for the architecture rationale. Current open work and status: [`docs/ROADMAP.md`](../ROADMAP.md) (2026-09-29).
+
 Status: plan of record for the audio track, 2026-09-05. Companion to
 `ROADMAP-1.0.md` §B3 ("audio (Phase 3)", "audio track parallel from M-50 →
 v0.4.0"). Independent of B1/B2 — can start immediately.
@@ -36,7 +38,7 @@ More is already in place than "audio not started" suggests:
   `osAiGetLength()` in `port/src/libultra.c:852-862` discard everything
   (`osAiGetLength` returns 0), and `port/src/audio.c` never opens an SDL
   device. `main.c:141-142` already calls `audioInit()` / `mixerInit()`.
-- **The PD reference is local** at `C:\Users\james\Source\Repos\pd_port`,
+- **The PD reference is local** at `<repos>\pd_port`,
   with the full audio stack: `port/src/audio.c` (75 lines, SDL device +
   queue), `port/src/mixer.c` (~720 lines, software RSP-audio-ucode), and the
   wiring trick in `include/PR/abi.h`.
@@ -199,4 +201,4 @@ M-50) → v0.4.0".
 | `port/src/libultra.c:848-863` | `osAi*` shims — wire to audio.c (Phase 1) |
 | `port/src/libultra.c:1237` | M_AUDTASK branch — stays a completing no-op; hosts `GE_AUDIOTRACE` |
 | `port/src/ucode.c` | Dummy `aspMain*` markers stay forever under CPU-bypass — document decision |
-| `C:\Users\james\Source\Repos\pd_port\port\src\{audio,mixer}.c`, `include\PR\abi.h` | PD ground truth: device glue + DSP cores + the macro-swap pattern |
+| `<repos>\pd_port\port\src\{audio,mixer}.c`, `include\PR\abi.h` | PD ground truth: device glue + DSP cores + the macro-swap pattern |

docs/dev/D172-PARTICLE-COLOR-RESEARCH.md

@@ -1,170 +0,0 @@
-# D172 — particle/flares wrong color (magenta/cyan blood): ROOT CAUSE FOUND + FIXED (M-82)
-
-Symptom (user-reported, GRAPHICS-BACKLOG line 31): bullet impacts / flares / blood spatter
-render magenta/cyan instead of dark red.
-
-## TL;DR (M-82)
-
-**Root cause:** `gfx_lod_tile_offset()` (`gfx_pc.cpp`) returns `0` unconditionally on
-the `!gfx_detail_textures_enabled` path (a D107 blurry-ceiling fix — and
-`port/src/video.c:225` sets that flag `false` at startup). Particle draws use
-`G_CC_INTERFERENCE` (`TEXEL0 * TEXEL1`) with tile 0 = IA8 smoke @ TMEM 0 and
-tile 1 = RGBA16 fire @ TMEM 0x188 — but with the offset pinned to 0, **texunit 1
-samples the smoke texture too**. `smoke * smoke` through the rest of the combine
-= the magenta/cyan. Confirmed by the `GE_D172` probe on a user Silo firefight:
-40/40 particle tris logged `cfg1[tile=1 tmem=392 fmt=RGBA]` but
-`SAMPLED1=tile0(tmem=0 fmt=IA)`.
-
-**Fix (`gfx_pc.cpp` `gfx_lod_tile_offset`):** `return rdp.tex_lod ? 0 : i;` —
-fold to the base tile only when LOD is actually active (D107's mip case,
-`tex_lod=1`, unchanged); a genuine non-LOD 2-texture combine now gets tile `i`.
-`bunker1` verify PASS (the D107 repro level). Committed on PR #34. **Owed: an
-in-game eyeball that blood/sparks now read dark red.**
-
-The 0xB9 / cycle-type false trails and the probe design are kept below for the
-record.
-
----
-
-Original note (superseded): Static audit done; one strong root-cause candidate
-with a cheap in-game verification. **No code changed.**
-
-## 1. How particles get their color state (mechanism)
-
-Particle triangles (`explosion.c`, `gSPVertex` + `G_TRI_FILL`/`G_TRI_SHADE_TXTR`) carry
-**no per-primitive material command**. Their CC/tile state comes from replaying ROM-resident
-state records via `gSPDisplayList(gdl++, g_ExplosionDisplayLists[var_s2])`
-(`explosion.c:894`, 15-record loop, one record + its particles per iteration).
-
-- Records: `globalDL_0x078 … globalDL_0x9a8`, a 17-entry table at image-bank offset
-  0x28 (`g_pc_gimg_off_globalDL_*`), bank base cart 0x1029D160 (see `image_bank.c:322`).
-- Each record is also scanned at load by `texLoadFromDisplayList` (`src/game/image.c:475`)
-  for its `G_SETTIMG` + ABCD marker word — that part works (textures upload fine).
-
-## 2. Record layout (decoded from ROM)
-
-```
-+0x00  E7 C3 FF FE        G_RDPPIPESYNC
-+0x08  B9 00 03 1D        ???  <-- UNHANDLED by fast3d (see §4)
-+0x10  <varies>           second word of the ??? command
-+0x18  FC ...             G_SETCOMBINE w0   (rgb c0 | alpha c0 <<16)
-+0x20  FF ...             G_SETCOMBINE w1   (rgb c1 | alpha c1 <<16)
-+0x28  FD ...             G_SETTIMG w0      (timg pointer)
-+0x30  .. 50 50 50 50     G_SETTIMG w1      (ABCD marker)
-```
-
-Dominant particle combine mode (14 of 17 records), decoded with the standard libultra
-bit layout:
-
-- cycle 0 RGB: `TEXEL0, 0, TEXEL1, COMB_A`
-- cycle 0 ALP: `TEXEL0A, COMB_A, SHADE, COMB_A`
-- cycle 1 RGB: `COMBINED, 0, SHADE, COMB_A`   ← **2-cycle** modulate
-- cycle 1 ALP: same as cycle 0
-
-## 3. fast3d audit (what is right)
-
-- `G_SETCOMBINE` bit extraction (`gfx_pc.cpp:2786`) matches the standard libultra layout
-  exactly (verified field-by-field against the ROM words). Not the bug.
-- Store/decode of `rdp.combine_mode` (`gfx_dp_set_combine_mode` vs `gfx_generate_cc`
-  key shifts) are consistent. Not the bug.
-- The generated GLSL combiner implements the RDP formula with the usual special cases;
-  `SHADER_COMBINED` correctly resolves to the previous cycle's running value.
-
-## 4. The 0xB9 root-cause candidate is WITHDRAWN (M-82, 2026-09-08)
-
-The earlier audit claimed fast3d has "no case for opcode 0xB9" and that the D146
-`default:` guard therefore aborts every particle sub-DL. **That is wrong.**
-
-This build does **not** define `F3DEX_GBI_2` (verified: no `-DF3DEX_GBI_2` in
-`CMakeLists.txt`, no `#define` in `include/PR/gbi.h` or anywhere in tree). In the
-non-F3DEX2 branch of `gbi.h`, `G_SETOTHERMODE_L = G_IMMFIRST-6 = -71`, and
-`(uint8_t)(-71) == 0xB9`. So `gfx_pc.cpp:2731` `case (uint8_t)G_SETOTHERMODE_L:`
-**is** `case 0xB9:`.
-
-Decode of the record word `w0 = 0xB900031D`, `w1 = <varies>`:
-`gfx_sp_set_other_mode(C0(8,8)=3, C0(0,8)=29, w1)` → sets `other_mode_l` bits
-3..31. `sft=3 == G_MDSFT_RENDERMODE`, `len=29` — this is exactly
-`gsDPSetRenderMode(w1)`. `w1` values (`0x0C184B50`, `0x00504B50`, …) are
-render-mode / blender words. fast3d applies it correctly.
-
-So the particle sub-DL runs to completion on PC: `E7` RDPPIPESYNC (handled),
-`B9` SetRenderMode (handled), `FC` SETCOMBINE (handled), `FD` SETTIMG (handled).
-**No D146 abort. No stale-state fallthrough.** The wrong-colour bug is elsewhere.
-
-## 5. Cycle-type is ALSO ruled out — the real record, and where the bug is (M-82)
-
-The actual particle records are in **`assets/oddtextures.c`**
-(`globalDL_0x078` … , 17 of them). One record verbatim:
-
-```c
-gsDPPipeSync(),
-gsDPSetCycleType(G_CYC_2CYCLE),            // <-- record DOES set 2-cycle
-gsDPSetRenderMode(G_RM_PASS, G_RM_ZB_CLD_SURF2),
-gsDPSetTextureLOD(G_TL_TILE),
-gsDPSetCombineMode(G_CC_INTERFERENCE, G_CC_MODULATEIA2),
-gsSPTexture(..., G_TX_RENDERTILE, G_ON),
-  // tile 0: IMAGE_SMOKE_0  IA16 image -> loaded/rendered as IA8, 56x56
-  // tile 1: IMAGE_FIRE_0   RGBA16, 16x14, loaded to tmem 0x188
-gsDPSetTextureLUT(G_TT_NONE),
-gsDPPipeSync(),
-gsSPEndDisplayList(),
-```
-
-So the record **explicitly sets `G_CYC_2CYCLE`** (opcode `0xBA` =
-`G_SETOTHERMODE_H` in this build), and fast3d handles `0xBA` correctly:
-`gfx_pc.cpp:2734` → `gfx_sp_set_other_mode(52, 2, w1<<32)` sets `other_mode_h`
-cycletype = 2CYC. **Confirmed by probe (M-82):** the `GE_D172=1` SETCOMBINE
-probe logged the particle combine `w0=fc26a004` (= `G_CC_INTERFERENCE`/
-`G_CC_MODULATEIA2`) with **`cycletype=1 (2CYC)`** every time. The cycle-type
-hypothesis is dead too.
-
-**The bug is the `G_CC_INTERFERENCE` two-tile combine / TEXEL1 path.**
-`G_CC_INTERFERENCE` cycle-0 = `TEXEL0 * TEXEL1`; the record binds **two
-different tiles of two different formats** (tile 0 IA8 smoke, tile 1 RGBA16
-fire at tmem 0x188). Magenta/cyan = a TEXEL1 sampling/decode fault: wrong tmem
-offset for tile 1, RGBA16 (5551) channel/endian misread, or fast3d treating
-tile 1 as an LOD mip of tile 0 under `G_TL_TILE`. This needs a visual
-render-iterate pass (headless can't see particle colour) — see §6.
-
-### Probes shipped (M-82, `#ifdef PORT`, `GE_D172=1`, inert when unset)
-
-- `gfx_pc.cpp` G_SETCOMBINE case — logs each distinct combine + active
-  cycletype (dedup, 64 max). Confirmed the particle combine `fc26a004` runs
-  at `cycletype=2CYC`.
-- `gfx_pc.cpp` `gfx_sp_tri1` (after the texunit loop) — whenever a **2-cycle
-  triangle actually consumes TEXEL1**, dumps `combine_mode` + both texunits'
-  `tile / tmem / fmt / siz`. This is the decisive probe: a Silo close-range
-  guard kill with `GE_D172=1` should log
-  `T0[... fmt=3(IA) siz=1(8b)]  T1[tmem=392 fmt=0(RGBA) siz=2(16b)]`.
-  If `T1.tmem != 392`, or `T1.fmt/siz` are wrong, the TEXEL1 bind is the bug.
-  If they're all correct, the fault is in `import_texture_rgba16` for the
-  second texunit or the `G_CC_INTERFERENCE` CC generation — pair with
-  `GE_DTEX=1` / `GE_TEXRAW=1` to dump the fire tile's bytes.
-
-## 6. Fix path (next session — needs a display)
-
-1. Get a `-level_XX` capture with visible particle spray (Silo guard kill at
-   close range per the original report, or any wall-impact spark). Note the
-   colour.
-2. Env-gated probe in `gfx_pc.cpp` `import_texture` / the TEXEL1 bind path:
-   for tile 1 when combine == the particle key, log format/size/tmem-addr/
-   line_size and the first few decoded texels. Compare against the RGBA16
-   `IMAGE_FIRE_0` bytes in the extracted asset.
-3. Likely fixes, in order of suspicion: (a) tile-1 tmem address 0x188 not
-   honoured → TEXEL1 reads tile-0 bytes; (b) RGBA16→RGBA32 decode for the
-   second texunit; (c) `G_TL_TILE` LOD path picking the wrong tile for TEXEL1.
-4. Re-decode `G_CC_INTERFERENCE` / `G_CC_MODULATEIA2` as fast3d generates them
-   (`gfx_cc.cpp`) and confirm the GLSL matches `TEXEL0*TEXEL1` then
-   `COMBINED*SHADE`.
-
-## Files
-
-- `src/game/explosion.c` — record table (165), replay loop (894)
-- `src/game/image_bank.c:322`, `src/game/image.c:475` — record offsets / load-time scan
-- `port/fast3d/gfx_pc.cpp` — SP walker cases (~2600–2930), D146 default (2920),
-  SETCOMBINE decode (2786), combine store (2270), cc generation (312+), 2CYCLE flag (1523)
-- `rsp/graphics/gmain.s` — N64 ucode ground truth for 0xB9 (dispatch table at dmem 0xbc;
-  ginit.s missing from repo)
-
-Note (M-82): 0xB9 is `G_SETOTHERMODE_L` in this non-F3DEX2 build and is already
-handled by fast3d — `gmain.s` / `ginit.s` are NOT needed to resolve D172.

docs/dev/D176a-SKY-NOTES.md

@@ -1,6 +1,6 @@
 # D176(a) Sky — consolidated research notes (read-only)
 
-Companion to `GRAPHICS-BACKLOG.md` D176(a) and findings.md M-37/M-47.
+Companion to the (since retired) `GRAPHICS-BACKLOG.md` D176(a) and findings.md M-37/M-47.
 Purpose: make the next implementation session mechanical. No code changed by
 this doc.
 

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

@@ -5,7 +5,7 @@ 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
+(`<repos>\pd_port`), and plan §6 of
 `docs/dev/OPTIONS-MENU-PLAN.md` (the original "align with Turok" note).
 
 ## 1. Goal

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

@@ -1,7 +1,7 @@
 # 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` +
+Status: **IMPLEMENTED 2026-09-30 (findings D443) for mouse sens ×, deadzone whole-%, volume step, FOV degrees, MSAA 16×, Restart game; texture filter unchanged by decision; frame-rate cap deferred (§0 presets + custom = separate project). Approved with changes; see §0.** Proposal dated 2026-09-27. Baselines: the PD port
+checkout (`<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
@@ -14,6 +14,23 @@ front top row reads **Profile**, the per-file row tag reads
 **"(per profile)"** and the F10 unavailable value reads **"Select a
 profile"** (§4).
 
+## 0. Sign-off (2026-09-30) — these override §3 where they differ
+
+- **FOV:** display in **degrees** (the PC standard). Storage stays unchanged.
+- **Frame rate cap:** presets **30 / 60 / 90 / 120 / 144 / 240 / Uncapped**,
+  **plus** an arbitrary custom value. This keeps the ini's free range and
+  adds a custom entry in the menu, instead of the plan's presets-only grid.
+- **MSAA:** add **16×**.
+- **Mouse invert:** stays a separate On/Off toggle.
+- **Texture filter: do NOT rename.** The §3 premise ("3-point *is*
+  trilinear") is wrong. 3-point is the N64's own 3-sample bilinear
+  approximation, and "Linear" and "Bilinear" name the same thing. Keep
+  "N64 3-point" and check the current enum strings before touching them.
+- **Refresh §3's "Now" column before implementing.** The stick deadzone is
+  already split L/R, and the draw/LOD defaults are 250, not 150.
+- Related QoL, tracked separately in ROADMAP §5a: a **Restart game** action
+  next to Quit to desktop, for restart-flagged rows such as MSAA.
+
 ## 1. Problem
 
 The D356 regroup fixed the *layout*; the *values* still mix three unit
@@ -65,6 +82,23 @@ volume trio (master still M3-backlog).
 Current state from `optionsoverlay.c` `rows[]` + the `configRegister*`
 ranges (2026-09-27). "Display" = what the value column shows today.
 
+### Implemented 2026-09-30 (D443) -- refreshed "Now" vs. result
+
+The per-row tables below keep the 2026-09-27 audit text for history. Actual
+pre-change state and what shipped (all port-only; no default or storage change,
+so `kResetDefaults` is untouched and `GE_WSPROBE_RESET` stays failures=0):
+
+| Row | Actual "Now" (pre-D443) | Shipped |
+|---|---|---|
+| Mouse horizontal sensitivity | 1-500 · step 5 · shown as calibrated `N/100` (50/100 at raw 100) | UI range 10-300, step 10, shown `%.1fx` (raw/100), linear bar; left the calibrated mapping |
+| Stick deadzone L / R | already split `Input.PadDeadzoneL/R` 0-30000 · step 500 · calibrated `N/100` | step 300 + `dispDiv=300` `%` (whole-% grid, no key migration); left the calibrated mapping |
+| Music / FX volume | step 128, `/328` | step 328 (1 display-%) |
+| FOV | `Video.FovScale` 50-150 · step 5 · `%` | row "Field of view", horizontal degrees (see D443 formula); key/storage unchanged, step walks the displayed degree |
+| Anti-aliasing | 1/2/4/8 · default 2 (C initialiser) | + 16x; range 1-16 (GL clamps to `GL_MAX_SAMPLES`) |
+| Texture filter | Nearest / Bilinear / 3-Point | unchanged (decision §0) |
+| Frame-rate cap | 30/60 toggle (sim ticks at 60 Hz) | unchanged this round |
+| Restart game | -- | new action row after Quit to desktop (both UIs, shared table) |
+
 ### INPUT
 
 | Row | Now (default · range · step · display) | PD port | Turok (notes) | Proposal |

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

@@ -1,129 +0,0 @@
-# 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-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
+File:line cells. Last reconciled 2026-09-30 (ROADMAP §7 strip pass: D157/D157T/D157I/D157TB, D207S, D227V, D245_OLDVTX/OLDTEX, D252POOL, D288, D309, D318B suite, D320R removed and marked as tombstones; D318W demoted to detect-only). Previously 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
@@ -19,22 +19,42 @@ Two classes:
 
 | Env var | File:line | What it does | Status |
 |---|---|---|---|
+| `GE_INPUTRECORD` | `port/src/input.c:1547` | Records pad input to a file (D583 Deck harness; `levelbench.sh --record`). | live tooling |
+| `GE_INPUTREPLAY` | `port/src/input.c:1548` | Replays a `GE_INPUTRECORD` file (`levelbench.sh --replay`; pin `GE_RSEED`). | live tooling |
+| `GE_INTERPLOG` | `port/src/libultra.c:1482` | D578 IPLOG pacing trace (`=<n>` caps the lines). | live diag |
+| `GE_INTERP_ALPHA1` | `port/src/libultra.c:1489` | D578: every interpolated pass exact (identity check). | live diag |
+| `GE_INTERP_FORCE` | `port/src/video.c:1058` | D578: interpolate even when the display refresh is not above the VI rate. | live diag |
+| `GE_INTERPCLIP_ON / GE_INTERPCLIP_OFF` | `port/fast3d/gfx_pc.cpp:1816` | D578 in-between depth-clip widening (default off since 2026-10-10). | live switch |
+| `GE_INTERPPORTAL_OFF` | `port/fast3d/gfx_pc.cpp:4156` | D578: disable the portal-scissor replay on in-between passes. | live switch |
+| `GE_INTERPROOM_OFF` | `port/fast3d/gfx_pc.cpp:6059` | D578: disable the room-change exact fallback. | live switch |
+| `GE_INTERPREACH_OFF` | `port/fast3d/gfx_pc.cpp:6128` | D583: disable the REACH exact fallback. | live switch |
+| `GE_INTERPOBJ_OFF` | `port/fast3d/gfx_pc.cpp:2626` | D955: in-between presents draw objects at their tick pose again (no per-joint motion blend; counters still run). A group whose joints step more than 120 units in a tick is drawn exact. | live switch |
+| `GE_INTERPPROPCAM_OFF` | `port/fast3d/gfx_pc.cpp:2436` | D954: in-between presents draw props at the exact camera again (no room-camera blend on the plain perspective). | live switch |
+| `GE_PCDUMP_PRESENTS` | `port/src/video.c:1539` | With `GE_PCDUMP`: one capture per present instead of per game frame. | live tooling |
+| `GE_NOTICKLOCK` | `port/src/libultra.c:1321` | D600: disable the display-locked retrace tick. | live switch |
+| `GE_ADDRSTRICT_SELFTEST` | `port/src/port_addr.c:122` | D607 (macOS): address-window self-test at startup. | live diag |
 | `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; `ZHOLD`/`ZREL` sustain fire, D207 M-201). Sole input source when set. | **live** |
+| `GE_INPUTSCRIPT_MS` | `port/src/input.c:1194` | abpad: entry times in `GE_INPUTSCRIPT` are milliseconds since SDL init instead of controller reads (`tools_pc/abpad`). C-button holds `CUPHOLD`/`CDOWNHOLD`/`CLEFTHOLD`/`CRIGHTHOLD`/`CNONE` (1.2 walk/strafe) also live in the script parser. | **live** |
+| `GE_PAD_BACKGROUND` | `port/src/input.c:1472` | `=1` sets `SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS` so the port reads pads while unfocused: one real pad drives the port and 1964 side by side (`tools_pc/abpad/live_ab.ps1`). | **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_STARTMP` | `src/game/lv.c:403` (`#ifdef PORT`) | D416: `GE_STARTMP=<players>[,<mpStageIdx>]` starts a local multiplayer match with the menu's default options (as MP options -> START does); pair with `GE_MPVIRT=<players-1>` for the controller count. Unattended split-screen testing. | **live** (D416) |
+| `GE_MPVIRT` | `port/src/input.c:686` | D416: report `n` extra idle controllers (1..3) so the MP menu unlocks / a 2P+ stage loads on a machine with no gamepads. Test harness only; P2..Pn get no input. | **live** (D416) |
 | `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_FAKE_DECK` | `port/src/video.c:490` (`videoDetectSteamDeck`) | D283: `=1` forces the Steam Deck path on any host (Windows/Linux desktop) so the once-per-ini Deck preset logic (`Video.DeckPresetApplied`, applied only while `Video.Fullscreen=0` and `Window.Maximized=0`) can be tested; `=0` forces it off on a real Deck (skips DMI + `STEAMOS`). Unset = real detection (DMI `Valve` + `Jupiter`/`Galileo`, then `STEAMOS`). **Writes the ini** (preset + flag) — use a throwaway data dir. | **live** (test hook) |
 | `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) |
+| `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. | **dead** (D204 closed) — removed 2026-09-30 (ROADMAP §7 strip pass, batch 1, branch `chore/scaffolding-removal-1`); tombstone — the generator flags it GONE |
 | `GE_AUDIOTRACE` | `src/snd.c` (`sndPlaySfx`, `sndDeactivate`), `src/game/propobj.c` (door sounds), `src/libultra/audio/load.c` (`alLoadParam`) | Per-`sndPlaySfx` resolution trace to `audiotrace.log`: `soundIndex` → `ALSound*`/keyMap/wavetable/base/len/book, the returned `ALSoundState*`, every `sndDeactivate`, and wavetable bind events. M-65 additions: `[VOICE+]`/`[VOICE-]` pairing every voice acquire/release with sound/state/flags (NB: written from two threads to one unbuffered FILE* — occasional torn lines, parse defensively), `[SLOTWRITE]` door slot ownership, `[RETRIGGER-POST]`, `[WAVELOOP]` (per-sound `ALADPCMloop` presence), `[DOORSND]` every door sound state change incl. an `ORPHAN-both-slots-busy` verdict. M-66b addition: `[EXPIRE]` — posted whenever the port-side ownerless-infinite-loop expiration is scheduled (sound/state/delay/fade); this line is **permanent** (part of the D202 option-C fix), unlike the rest of the probe set which is removable on close. M-67/M-69 additions: `[WIRE] t=µs filter=… <- table=…` (`src/libultra/audio/load.c`, every wavetable→decoder bind, µs-timestamped) and `[VOICEMAP]` (`src/libultra/audio/synthesizer.c`, full PVoice→decoder/resampler/env-state address map at synth init — this is how offline voicedump slot addresses tie to WIRE filter addresses). M-68 additions: `[EVT] t=µs type=N state=P` + `[STOP-EVT] … deltaUs=N` (event types per `src/snd.h`: 1=PLAY, 2=STOP, 8=VOL, 64=DECAY, 128=END). M-71 additions: `[VOL] t=µs state=… rawVol=… playing=…` (`src/snd.c`, per-VOL-event value before the slot-volume law) and `[DISTVOL] pos=(…) player=(…) dist=… vol=…` (`src/game/propobj.c`, the distance-attenuation funnel `sub_GAME_7F053894` — this is how an SFX's final volume is computed from hit position). NB: lines from the multiple file handles interleave — occasional torn/corrupt lines, parse defensively. `dumppos=` gives the exact byte offset into `audiodump.raw` (quantised to the 2880-byte audio block). Low cost. | **live** (D202/D205) |
+| `GE_AUDIOGAINLOG=1` | `port/src/audio.c` (`audioSetNextBuffer`, cached `GE_ENVFLAG`) | D470: once per second logs `D470 gain: master=N peak=P`, the max abs sample of the final (post master-volume) buffer. Cheap; shows the gain effect headlessly. | **live** |
 | `GE_PULLTRACE` | `src/libultra/audio/load.c` (`alAdpcmPull`) | `[PASTEND]` assertion: fires if a voice's `f->sample` exceeds its wave's total samples while `nOver == 0` (i.e. an unstopped voice keeps decoding past the end instead of zero-filling). Rate-limited to 40 lines. M-65: 0 hits — exhausted voices go silent correctly. | **live** (D202) |
 | `GE_DMEMWIPE` | `port/src/mixer.c` (`aClearBufferImpl`) | Zeroes the whole software DMEM at the frame boundary (detected as `alMainBusPull`'s clear of `AL_MAIN_L_OUT`, addr 1088). Tests whether audio state survives across frames in DMEM. M-65: no-op on output — ruled out. | **live** (D202) |
 | `GE_NOWET` | `port/src/mixer.c` (`aSetVolumeImpl`) | Mutes the reverb send (`wetamt = 0`), isolating the reverb delay lines as a possible source of persistent signal. M-65: drone unchanged — ruled out (NB `aPoleFilterImpl` is still an unimplemented no-op, D199). | **live** (D202) |
 | `GE_BANKDUMP` | `port/src/romdata.c` | `BANKSRC` lines: the source ROM-layout bank tree per `soundIndex` (instrument → sound → envelope pointers + `decayTime`). Used to prove sound 203's `decay=-1` is genuine ROM data, not a conversion bug. One-shot at load. | **live** (D202) |
-| `GE_FORCEALARM` | `src/game/propobj.c` (`handle_alarm_gas_timer_calldamage`, `#ifdef PORT`) | **D207 diag (temporary).** Forces the in-game alarm klaxon (`alarmActivate`) on a frame counter — on ~2–10 s, off, on again — and emits a per-frame `[D207] f=… active=… ptr_alarm_sfx=… playstate=… locked=…` line to `audiotrace.log`. Repro harness for the "alarm SFX overrides other audio" report when a level's own alarm can't be triggered headlessly. Remove when D207 closes. | **live** (D207) — temporary |
+| `GE_FORCEALARM` | `src/game/propobj.c` (`handle_alarm_gas_timer_calldamage`, `#ifdef PORT`) | **D207 diag (temporary).** Forces the in-game alarm klaxon (`alarmActivate`) on a frame counter — on ~2–10 s, off, on again — and emits a per-frame `[D207] f=… active=… ptr_alarm_sfx=… playstate=… locked=…` line to `audiotrace.log`. Repro harness for the "alarm SFX overrides other audio" report when a level's own alarm can't be triggered headlessly. Remove when D207 closes. | **dead** (D207 closed) — removed 2026-09-30 (ROADMAP §7 strip pass, batch 1, branch `chore/scaffolding-removal-1`); tombstone — the generator flags it GONE |
 | `GE_KEYMAPDUMP` | `port/src/romdata.c` | `KEYMAP` + `ENVSRC` lines: raw source bytes of every `ALKeyMap` / `ALEnvelope` in the ROM-layout blob, for byte-wise comparison against runtime values. One-shot at load. | **live** (D202) |
 | `GE_AUDIODUMP` | `port/src/audio.c` (`audioSetNextBuffer`) | Raw-dumps every mixed s16/stereo/22050 Hz buffer to `audiodump.raw` in the CWD for offline waveform inspection. Length ÷ 88200 = seconds of audio produced. | **live** (D202) |
 | `GE_VOICEDUMP` | `port/src/mixer.c` (`aEnvMixerImpl`) | Dumps each voice's resampled mono stream (post-resample/pre-envelope, i.e. the env-mixer input) to `voicedump.raw` as records of `[u32 stateAddr][u32 nSamples][u64 us][s16 × n]`. **The µs stamp is when the block was MIXED — records are rendered ahead, so a record's samples END at its stamp** (M-69: treating stamps as start offsets misplaces content by up to one ~33 ms block). `stateAddr` = the env-mixer state address from `[VOICEMAP]`. Used with `scratchpad/exact_match.py` for full-corpus per-voice sample verification. | **live** (D202) |
@@ -46,105 +66,134 @@ Two classes:
 | `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_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. | **dead** (D243 FIXED) — removed 2026-10-01 (scaffolding strip batch 3, branch `chore/strip-d243-probes`); kept as a tombstone — the generator flags it GONE |
+| `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. | **dead** (D243 FIXED) — removed 2026-10-01 (scaffolding strip batch 3, branch `chore/strip-d243-probes`); kept as a tombstone — the generator flags it GONE |
+| `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. | **dead** (D243 FIXED) — removed 2026-10-01 (scaffolding strip batch 3, branch `chore/strip-d243-probes`); kept as a tombstone — the generator flags it GONE |
+| `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. | **dead** (D243 FIXED) — removed 2026-10-01 (scaffolding strip batch 3, branch `chore/strip-d243-probes`); kept as a tombstone — the generator flags it GONE |
 | `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_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. | **dead** (D243 FIXED) — removed 2026-10-01 (scaffolding strip batch 3, branch `chore/strip-d243-probes`); kept as a tombstone — the generator flags it GONE |
+| `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. | **dead** (D243 FIXED) — removed 2026-10-01 (scaffolding strip batch 3, branch `chore/strip-d243-probes`); kept as a tombstone — the generator flags it GONE |
 | `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_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). | **dead** (D252 fixed) — removed 2026-09-30 (ROADMAP §7 strip pass, branch `chore/strip-temp-probes`); tombstone — the generator flags it GONE |
 | `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_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) — removed 2026-10-03 (strip batch 5, `chore/strip-batch5`); tombstone — the generator flags it GONE |
+| `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**. | **dead** (D288 closed) — removed 2026-09-30 (ROADMAP §7 strip pass, branch `chore/strip-temp-probes`); tombstone — the generator flags it GONE |
+| `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. | **dead** (D245 fixed) — removed 2026-10-02 (strip batch 4, `chore/strip-batch4`); tombstone |
+| `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). | **dead** (D245 fixed) — removed 2026-10-02 with the inert sky tile-capture/shift code (strip batch 4); tombstone |
+| `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. | **dead** (D252 closed) — removed 2026-09-30 (ROADMAP §7 strip pass, batch 1, branch `chore/scaffolding-removal-1`); tombstone — the generator flags it GONE |
+| `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. | **dead** (D252 fixed) — removed 2026-09-30 (ROADMAP §7 strip pass, branch `chore/strip-temp-probes`); tombstone — the generator flags it GONE |
+| `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. | **dead** (D245 fixed) — removed 2026-09-30 (ROADMAP §7 strip pass, branch `chore/strip-temp-probes`); tombstone — the generator flags it GONE. The pre-fix s16 sky/water vertex path (`skyPortRenderPoly` tail + `skyPortEmitTileShift`) went with it; the float path is now unconditional |
+| `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). | **dead** (D341 closed) — removed 2026-09-30 (ROADMAP §7 strip pass, batch 1, branch `chore/scaffolding-removal-1`); tombstone — the generator flags it GONE |
+| `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). | **dead** (D207/D241 closed) — removed 2026-09-30 (ROADMAP §7 strip pass, branch `chore/strip-temp-probes`); tombstone — the generator flags it GONE |
+| `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. | dead — fully removed 2026-10-01 (ROADMAP §7 scaffolding strip, batch 2; kept here as a tombstone) |
 | `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_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. | **dead** (D235 closed) — removed 2026-10-02 (strip batch 4); tombstone. The D235 fix (`videoResetTextureCache()` per stage load) and the `GE_D235` log stay |
+| `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`. | **dead** (D235 closed) — removed 2026-10-02 (strip batch 4); tombstone |
+| `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`). | **dead** (D235 closed) — removed 2026-10-02 (strip batch 4); tombstone |
+| `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. | **dead** (D320 fixed via D329) — removed 2026-09-30 (ROADMAP §7 strip pass, branch `chore/strip-temp-probes`); tombstone — the generator flags it GONE; `port/src/d320repro.c` + its `lv.c` hook deleted |
 | `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_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). 2026-10-01: also prints `PERFSTAT spikes: max=..ms at frame N (dl= run=) >20ms= >33ms=` per 300-frame window (hitches hide in the averages). | **live** |
+| `GE_NOSHADERWARM=1` | `port/fast3d/gfx_pc.cpp` (`gfx_shader_list_open`) | D480 falsifier: disables the shader pre-warm (no read or write of `$S/ge007.shaders`), so first-seen combiners compile mid-frame as before. | **live** (D480) |
+| `GE_RENDERINLINE=1` | `port/src/libultra.c` (`portRenderWorkerOn`) | D481 falsifier: run gfx tasks inline on the scheduler thread (the pre-D481 path) instead of on the render worker. `GE_DETERM` forces this too. | **live** (D481) |
+| `GE_FAKE_LOWEND=1/0` | `port/src/video.c` (`videoApplyLowEndDefaults`) | D482: force the low-end GPU classification on (1) or off (0) for the one-time first-launch defaults check (`Video.LowEndConsidered`). Testing only, like `GE_FAKE_DECK`. | **live** (D482) |
+| `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. **D473 (2026-10-01): the cache was broken (re-read on every G_VTX when unset); now a real one-shot cache.** | **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_PADMAPTEST` | `port/src/input.c` (`inputInit` -> `padMapSelfTest`) | D469: boot-time self-test of the gamepad action table. Proves preset 0 == the legacy hard-wired mapping (20,971,520 synthetic cases), logs the per-source mask table, a Custom remap, per-seat independence, the Start guard and the binding API; restores config afterwards (nothing persisted); the game then continues. Cached (`GE_ENVFLAG`). | **live** (harness) |
+| `GE_D466LOG=<n>` | `port/src/drawdistgameplay.c` (`portD466FrameLog`, called from `bgDetermineVisibleRooms`) | D466 dev probe: every `<n>` calls (per player view) logs `D466 f=.. active= ext= auth= subset= hext= hauth= chrOn= chrGp= seen= hgame=` to stderr: extended vs authored room-set counts + hashes, ONSCREEN chrs vs gameplay-on-screen chrs, `HAS_BEEN_ON_SCREEN` count, and a chr-state hash. Cached. | **live** (D466 dev probe) |
+| `GE_D468_SCALE=<0.05..1>` | `port/src/drawdistgameplay.c` (`portD468UpdateClamp`) | D468 dev falsifier: multiplies the AI-view-clamp fractions (and so turns the clamp on even at 16:9 / FOV 100), so a headless `GE_D466LOG` run can show the authored room set and gameplay on-screen chrs shrinking. Cached; out-of-range values ignored. | **live** (D468 dev probe) |
+| `GE_SHADEPERSP=1` | `port/fast3d/gfx_opengl.cpp` (`gfx_opengl_init`, shader build) | D540 A/B switch: perspective-correct shade-colour interpolation instead of the default RDP-style screen-affine (`noperspective`) one (the sky horizon fade). Read once at GL init. | **live** (D540 A/B) |
+| `GE_FOGPIXEL=1` | `port/fast3d/gfx_opengl.cpp` (`gfx_opengl_init`), `port/fast3d/gfx_pc.cpp` (`gfx_sp_vertex`) | D543 A/B switch: the D540 exact per-pixel fog (fog * w, divided by w in the shader) instead of the default per-vertex RSP fog (honest negative-w divide, CPU near clip lerps it). Read once at GL init. | **live** (D543 A/B) |
+| `GE_FOGVERTEX` | (removed) | **removed** -- D540's per-vertex-fog opt-in; per-vertex fog is the D543 default, the opt-out is `GE_FOGPIXEL=1`; tombstone kept. | **removed** |
+| `GE_NEARCLIP=0` | `port/fast3d/gfx_pc.cpp` (`gfx_sp_tri1`) | D543 A/B switch: disable the CPU RSP-style near-plane clip (default on) and leave near-plane clipping to the GPU. Cached on first triangle. | **live** (D543 A/B) |
+| `GE_NEARCLIPFOG=recompute` | `port/fast3d/gfx_pc.cpp` (`gfx_sp_tri1`) | D543 A/B switch: recompute the per-vertex RSP fog value of near-clip-created vertices from their new z/w (as `gfx_sp_vertex`) instead of lerping it (default). Cached on first triangle. | **live** (D543 A/B) |
+| `GE_FOGSNAP=1` | `port/fast3d/gfx_opengl.cpp` (fragment shader build) | D540 A/B switch: re-enables the D503 full-fog snap (fog >= 247/255 -> full), off by default since D540 (its hard edge swept across the ground in chunks). Cached on first shader build. | **live** (D540 A/B) |
+| `GE_PADFAMILY=xbox\|ps\|nintendo` | `port/src/input.c` (`inputPadFamily`) | D471 dev override: force the controller family used for button names in the PC menus (headless screenshots without the hardware). Cached. | **live** (D471 dev knob) |
+| `GE_D466_FORCE=1` | `port/src/drawdistgameplay.c` (`portD466Active`) | D466: run the authored-distance split even at DrawDistance 100% (identity test: authored set must equal extended). Cached. | **live** (D466 test hook) |
+| `GE_D466_OFF=1` | `port/src/drawdistgameplay.c` (`portD466Active`) | D466 kill switch: disable the gameplay/render split (every gameplay reader falls back to the extended-range state, i.e. the pre-fix #125 behaviour). For A/B only. Cached. | **live** (D466 kill switch) |
+| `GE_INPUTSCRIPT_P1` | `port/src/input.c:1216` | Split-screen test harness: scripted input for player slot 1, same entry syntax as `GE_INPUTSCRIPT` (slot 0); mouse tokens and `CHOLD`/`CREL` ignored with one warning. Used with `GE_STARTMP` + `GE_MPVIRT`. | **live** (test harness) |
+| `GE_INPUTSCRIPT_P2` | `port/src/input.c:1217` | As `GE_INPUTSCRIPT_P1`, for player slot 2. | **live** (test harness) |
+| `GE_INPUTSCRIPT_P3` | `port/src/input.c:1217` | As `GE_INPUTSCRIPT_P1`, for player slot 3. | **live** (test harness) |
+| `GE_MEMPREDZONE=1` | `src/memp.c:340`, `src/memp.c:369` (+ periodic check in `port/src/video.c`) | D464 red-zone checker: pads every stage-bank allocation with a 64-byte pattern trailer and logs `MEMPREDZONE: HIT ...` at level unload, every 60 frames and at quit. Unset = one cached branch per allocation. | **live** (D464 dev tool) |
+| `GE_CRASHTEST` | `port/src/crash.c` (`crashTestMaybe`, called at the end of `crashInit`) | Deliberate-crash hook for verifying the crash handler: `GE_CRASHTEST=<N>` recurses N frames deep (capped at 64) right after the handler is installed and faults with a null write. `ge007.crash.log` should then show `#00`..`#N-1` in `crashTestRecurse`, then `SDL_main`, CRT and system frames; each frame line carries `va=0x…` for `addr2line -f -p -e build-pc/ge007.x86_64.exe <va>`. Unset/0 = no effect. | **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_OPTIONSOVERLAY_DROPDOWN` | `port/src/optionsoverlay.c:1195` | Screenshot-only: with the overlay auto-opened on a page, opens the dropdown popup of the named row key (e.g. `Video.TextureFilter`, `__Resolution`) and focuses it. | **live** (diagnostic) |
+| `GE_OPTIONSOVERLAY_ATFRAME` | `port/src/optionsoverlay.c:3362` | Re-applies the GE_OPTIONSOVERLAY / _SECTION / _SELECT request at emit frame n so it survives a level load (in-level screenshots, D558). Read once. | **live** (diagnostic) |
+| `GE_OPTIONSOVERLAY_SELECT` | `port/src/optionsoverlay.c:1221` | Screenshot-only: selects the named row key on the auto-opened page (e.g. `Game.NoHitFlash`) so its tip shows (D558). | **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_PRESETPROBE` | `port/src/optionsoverlay.c:957` (`presetProbe`) | D440: one-shot at overlay init — drives the "Original N64" and "Port defaults" preset rows through the real arm -> confirm activation and checks the "Active" state; logs `GE_PRESETPROBE: PASS/FAIL`. **Writes the live config** (persisted on exit) — use a throwaway data dir. | **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_FOOTERPROBE` | (removed) | **removed** -- the F10 footer was replaced by the hint line under the box (menu PD parity); tombstone kept. | **removed** |
+| `GE_OVNAV` | `port/src/frontoptions.c:106` | D519 follow-up harness: scripted overlay navigation on file select (O toggle, D/U move, A open, B back, P log the place), one token per 20 file-select frames. | **live** (harness) |
+| `GE_FILESELECT_OVERLAY` | `port/src/frontoptions.c:96` | One-PC-options-UI (D519) test hook: opens the F10 overlay over file select without a click; value `n` > 1 also closes it `n` label-frames later. Replaces the retired front-screen probes (the FRONTOPTIONS_SECTION, FRONTNAVLOG, FRONTOPTS_WIDTHS and FRONTOPTIONS_AUTO probes). | **live** (harness) |
 | `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) |
+| `GE_D526` (+ `GE_D526BOX`, `GE_D526MAX`) | `port/fast3d/gfx_pc.cpp:1895,2024,2032,2034` | D526 per-triangle draw-state census probe (text-only): `GE_D526="lo-hi"` = sim-frame range (same dash syntax as `GE_D75D`); `GE_D526BOX="x0 y0 x1 y1"` = NDC region filter (same syntax as `GE_ZFBOX`, default on-screen); `GE_D526MAX` caps per-triangle lines (default 400). Per emitted in-region tri: frame, NDC bbox, z/w, geometry_mode, other_mode_l/h, combine word, sampled tile tmem/fmt/siz, first_tile_index, prim alpha, vertex alpha min/max, use_alpha/modulate/invisible — plus one per-frame line aggregating in-region tris by (comb, oml, omh, alpha) signature. Retained as a generic transparency/texture triage tool (D195/D266/D268/D273 class); the D526 grate case itself was confirmed faithful N64 behaviour, so no fix shipped. Zero cost unless `GE_D75D`/`GE_ZF`/`GE_D303`/`GE_D526` is set (folded into the D474 `tri_dbg` gate). | **live** (diagnostic) |
 
 ## Dxx diagnostic probes — finding closed unless noted
 
 | Env var | File:line | Finding / what it logged | Status |
 |---|---|---|---|
-| `GE_D51` | `port/src/libultra.c:496`, `src/game/model.c:125,244,544` | msgQ 32-slot overflow watch / ModelSlot layout | dead (D51 closed) |
+| `GE_D589POOL` | `src/game/image.c:339,1202` | D589 (macOS): texture-pool decode trace. | open diag |
+| `GE_D590HDR` | `src/game/bg.c:899` | D590: `load_bg_file` header trace. | closed |
+| `GE_TEXDUMPROW` | `port/fast3d/gfx_pc.cpp:1480` | D591/D592 (macOS): per-row texture dump. | closed |
+| `GE_TEXIMP2` | `port/fast3d/gfx_pc.cpp:1588` | D592 (macOS): import-order trace. | closed |
+| `GE_TEXSRC` | `src/game/image.c:1042,1177` | D591 (macOS): texture source-address trace. | closed |
+| `GE_ZLIBDUMP` | `src/game/image.c:317` | D611 (macOS): inflate input/output dump. | closed |
+| `GE_D51` | `port/src/libultra.c:496`, `src/game/model.c:125,244,544` | msgQ 32-slot overflow watch / ModelSlot layout | dead (D51 closed) — removed 2026-10-03 (strip batch 5, `chore/strip-batch5`); tombstone — the generator flags it GONE |
 | `GE_D54` | — (all blocks stripped M-32, commit `49ce620a`) | music seq-table ABI / endianness (`ALMidiHdr`) | dead (D54 closed) — fully removed (kept here as a tombstone; the generator flags it GONE) |
-| `GE_D154` | `src/game/bg.c:3418,3447,3632` (capped 64 calls) | bg room-GDL call trace (room / gdlidx / vtxoff / op / raw hdr words) | dead (D154 closed) |
-| `GE_D227V` | `src/game/sky.c` (`skyPortRenderPoly`, `#ifdef PORT`) | Sky/water per-vertex dump: `S`/`T`/`w`/`1/w`, screen xy, the chosen tc shift `k`, the baked `tc`, and whether the tile capture succeeded. **Found D227**: one sky quad spans ~30,000 texels in S and T but `Vtx.tc` is S10.5 in an `s16` (+/-1024 texels), so 7 of its 8 texture coordinates overflowed and wrapped -- the starburst/"two sky processes" seam. Root cause was a unit error (`unk20`/`unk24` are already S10.5, not texels; M-82's `*32` was spurious). FIXED M-100b. Probe kept inert. | **live** (D227 FIXED, probe kept; useful for D229 water) |
+| `GE_D154` | `src/game/bg.c:3418,3447,3632` (capped 64 calls) | bg room-GDL call trace (room / gdlidx / vtxoff / op / raw hdr words) | dead (D154 closed) — removed 2026-10-03 (strip batch 5, `chore/strip-batch5`); tombstone — the generator flags it GONE |
+| `GE_D227V` | `src/game/sky.c` (`skyPortRenderPoly`, `#ifdef PORT`) | Sky/water per-vertex dump: `S`/`T`/`w`/`1/w`, screen xy, the chosen tc shift `k`, the baked `tc`, and whether the tile capture succeeded. **Found D227**: one sky quad spans ~30,000 texels in S and T but `Vtx.tc` is S10.5 in an `s16` (+/-1024 texels), so 7 of its 8 texture coordinates overflowed and wrapped -- the starburst/"two sky processes" seam. Root cause was a unit error (`unk20`/`unk24` are already S10.5, not texels; M-82's `*32` was spurious). FIXED M-100b. Probe kept inert. | **dead** (D227 fixed) — the probe lived in the pre-D245 s16 sky path, unreachable since D245 M-201; removed 2026-09-30 (ROADMAP §7 strip pass, branch `chore/strip-temp-probes`); tombstone — the generator flags it GONE |
 | `GE_D176` | `src/game/bgfog.c:459,471`, `src/game/sky.c:325,381` (all `#ifdef PORT`) | D176 sky/fog env-match + sky-vert trace (Path B, PR #18) | **live** (D176(a)/(b) OPEN) |
-| `GE_D178` | `src/game/front.c:6586,6594` (`#ifdef PORT`) | briefing-data u16 decode trace (blank-objectives, D143/D178) | dead (D178 closed) |
-| `GE_D56` | `src/game/model.c:227,830` | watch `Model` raw-offset reads | dead (D56 closed) |
-| `GE_D60` | `port/src/libultra.c:521,735` | gfx frame msgQ delivery trace | dead (D60 closed) |
-| `GE_D61` | `port/src/libultra.c:795` (`s_d61opened`) | opens a one-shot log file | dead (D61 closed) |
-| `GE_D62` | `port/src/libultra.c:477` | osRecvMesg trace | dead (D62 closed) |
-| `GE_D63` | remaining: `src/game/bg.c:2525,2908,2953`, `front.c:1410,1416,7814,7889,8083,8091,8099,8366`, `image.c:2453`, `language.c:431`, `model.c:4340`, `title.c:607` | gun-barrel sub-DL clobber hunt (D63/D64/D65/D66 — the labels drift within the blocks). Stripped M-30 (`d0789358`, `gfx_pc.cpp` trail). Stripped M-32 (`49ce620a`): `memp.c`, `bg.c:2880` (incl. the bare non-PORT `d63bgprimarycount` static + entry log), `blood_animation.c`, `dyn.c`, `rsp.c`. **Remaining blocks are all `#ifdef PORT` + getenv-guarded and inert — strip candidates for a later pass.** | dead (D63 closed) — partially removed |
-| `GE_D69` | `src/game/ob.c:165,227` | stage-load (D69) object trace | dead (D69 closed) |
-| `GE_D69BB` | `src/game/bg.c:2460,2479,3020` | D69 bg-binary layout trace | dead |
-| `GE_D69STAN` | `src/game/stan.c:266,276` | D69 stan-tile trace | dead |
-| `GE_D85DUMP` | `src/game/bg.c:2510` | D85 `bgWidenRoomGdl` 8→16B dump | dead (D85 closed) |
+| `GE_D178` | `src/game/front.c:6586,6594` (`#ifdef PORT`) | briefing-data u16 decode trace (blank-objectives, D143/D178) | dead (D178 closed) — removed 2026-10-03 (strip batch 5, `chore/strip-batch5`); tombstone — the generator flags it GONE |
+| `GE_D56` | `src/game/model.c:227,830` | watch `Model` raw-offset reads | dead (D56 closed) — removed 2026-10-03 (strip batch 5, `chore/strip-batch5`); tombstone — the generator flags it GONE |
+| `GE_D60` | `port/src/libultra.c:521,735` | gfx frame msgQ delivery trace | dead (D60 closed) — removed 2026-10-03 (strip batch 5, `chore/strip-batch5`); tombstone — the generator flags it GONE |
+| `GE_D61` | `port/src/libultra.c:795` (`s_d61opened`) | opens a one-shot log file | dead (D61 closed) — removed 2026-10-03 (strip batch 5, `chore/strip-batch5`); tombstone — the generator flags it GONE |
+| `GE_D62` | `port/src/libultra.c:477` | osRecvMesg trace | dead (D62 closed) — removed 2026-10-03 (strip batch 5, `chore/strip-batch5`); tombstone — the generator flags it GONE |
+| `GE_D63` | remaining: `src/game/bg.c:2525,2908,2953`, `front.c:1410,1416,7814,7889,8083,8091,8099,8366`, `image.c:2453`, `language.c:431`, `model.c:4340`, `title.c:607` | gun-barrel sub-DL clobber hunt (D63/D64/D65/D66 — the labels drift within the blocks). Stripped M-30 (`d0789358`, `gfx_pc.cpp` trail). Stripped M-32 (`49ce620a`): `memp.c`, `bg.c:2880` (incl. the bare non-PORT `d63bgprimarycount` static + entry log), `blood_animation.c`, `dyn.c`, `rsp.c`. **Remaining blocks are all `#ifdef PORT` + getenv-guarded and inert — strip candidates for a later pass.** | dead (D63 closed) — partially removed — removed 2026-10-03 (strip batch 5, `chore/strip-batch5`); tombstone — the generator flags it GONE |
+| `GE_D69` | `src/game/ob.c:165,227` | stage-load (D69) object trace | dead (D69 closed) — removed 2026-10-03 (strip batch 5, `chore/strip-batch5`); tombstone — the generator flags it GONE |
+| `GE_D69BB` | `src/game/bg.c:2460,2479,3020` | D69 bg-binary layout trace | dead — removed 2026-10-03 (strip batch 5, `chore/strip-batch5`); tombstone — the generator flags it GONE |
+| `GE_D69STAN` | `src/game/stan.c:266,276` | D69 stan-tile trace | dead — removed 2026-10-03 (strip batch 5, `chore/strip-batch5`); tombstone — the generator flags it GONE |
+| `GE_D85DUMP` | `src/game/bg.c:2510` | D85 `bgWidenRoomGdl` 8→16B dump | dead (D85 closed) — removed 2026-10-03 (strip batch 5, `chore/strip-batch5`); tombstone — the generator flags it GONE |
 | `GE_D85TEX` | `src/game/image.c:2479`, `src/game/tex.c:859,1050` | D85 texpool-full events (Depot analysis) | dead (D85 closed) — was useful for §3 |
 | `GE_D217TEX` | `src/game/image.c:234` (`texInflateZlib`) | D217: logs `texnum`/`format`/`numcolours`/`palette[0..1]` straight off the decode bitstream (before any arena/pointer math) — the decode-correctness check that proved the affected texture (grip, `texnum=1608`) decodes byte-identically across levels, ruling out a decode/ROM-data bug. | **live** (D217 open — investigation instrument) |
 | `GE_D229` | `port/fast3d/gfx_pc.cpp` (`gfx_sp_tri` dual-texunit probe + `import_texture`) | D229: per-draw dump of both texunits' tile/tmem/fmt/siz/UV state for 2-cycle draws, plus a one-shot confirm line when the RGBA16-over-CI8 import remap fires (the fix path). Inert by default. | **live** (D229 fixed — probe kept for the Surface 2 / sweep verification) |
-| `GE_D86` | `src/game/model.c:6295`, `src/game/objecthandler_2.c:143` | D86 model rwdata trace | dead (D86 closed) |
-| `GE_D87` | `src/game/ramromreplay.c:296,363,381` | D87 `ramromfilestructure` endianness | dead (D87 closed) |
-| `GE_D88` | `src/game/prop.c:1367`, `src/game/stan.c:3090` | D88 `Usetup*Z` propDef stream | dead (D88 family closed; D88.4 resolved) |
-| `GE_D90` | remaining: `src/game/bondview2.c:2146`, `src/game/prop.c:1391` (bondview_r.c blocks stripped M-32, `49ce620a`) | D90 bondview / prop NULL trace | dead (D90 closed) — partially removed |
-| `GE_D96` | `src/game/chrprop.c:436,507` (cached `probe`) | D96 chrprop trace | dead (D96 closed) |
+| `GE_D86` | `src/game/model.c:6295`, `src/game/objecthandler_2.c:143` | D86 model rwdata trace | dead (D86 closed) — removed 2026-10-03 (strip batch 5, `chore/strip-batch5`); tombstone — the generator flags it GONE |
+| `GE_D87` | `src/game/ramromreplay.c:296,363,381` | D87 `ramromfilestructure` endianness | dead (D87 closed) — removed 2026-10-03 (strip batch 5, `chore/strip-batch5`); tombstone — the generator flags it GONE |
+| `GE_D88` | `src/game/prop.c:1367`, `src/game/stan.c:3090` | D88 `Usetup*Z` propDef stream | dead (D88 family closed; D88.4 resolved) — removed 2026-10-03 (strip batch 5, `chore/strip-batch5`); tombstone — the generator flags it GONE |
+| `GE_D90` | remaining: `src/game/bondview2.c:2146`, `src/game/prop.c:1391` (bondview_r.c blocks stripped M-32, `49ce620a`) | D90 bondview / prop NULL trace | dead (D90 closed) — partially removed — removed 2026-10-03 (strip batch 5, `chore/strip-batch5`); tombstone — the generator flags it GONE |
+| `GE_D96` | `src/game/chrprop.c:436,507` (cached `probe`) | D96 chrprop trace | dead (D96 closed) — removed 2026-10-03 (strip batch 5, `chore/strip-batch5`); tombstone — the generator flags it GONE |
 | `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_D71LOG` | `port/fast3d/gfx_pc.cpp:645` | D71 fast3d trace | dead (D71 closed) — removed 2026-10-03 (strip batch 5, `chore/strip-batch5`); tombstone — the generator flags it GONE |
 | `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_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. | **dead** (D309/D310 fixed) — removed 2026-09-30 (ROADMAP §7 strip pass, branch `chore/strip-temp-probes`); tombstone — the generator flags it GONE |
 | `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_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. | **dead** (D318 closed) — removed 2026-09-30 (ROADMAP §7 strip pass, batch 1, branch `chore/scaffolding-removal-1`); tombstone — the generator flags it GONE |
+| `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. | dead — fully removed 2026-10-01 (ROADMAP §7 scaffolding strip, batch 2; kept here as a tombstone) |
 | `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_D318W` | `port/src/d318watchdog.c` (`d318WatchdogTick`, `#ifdef PORT`) | **The D318/D320 pin detector, ON by default, DETECT-AND-LOG ONLY since 2026-09-30.** Watches the Facility ai_22 / ai_19 and Control ai_9 hold-pose pin signatures (findings D318/D320) and logs `D318W:` lines (first detection, confirmation after 600 ticks, periodic reminders while held). It used to re-seed the attack via `sub_GAME_7F025560`; that recovery was removed because D329 fixed the cause, so a hit now means a D329 regression. `GE_D318W=0` silences it. | **live** (D329 regression detector) |
 | `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_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.** | **dead** (D318/D320 fixed via D329) — removed 2026-09-30 (ROADMAP §7 strip pass, branch `chore/strip-temp-probes`); tombstone — the generator flags it GONE; `port/src/d318bprobe.c` + `port/include/d318bprobe.h` deleted. NB `GE_D318B_CLK` (sim-ticks-per-frame lockstep, used for the D329 pin repro) went with the suite |
 | `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/GE-PROBE-CATALOG.md

@@ -0,0 +1,41 @@
+# GE_ diagnostic-probe catalog (keep vs strip before a `main` merge)
+
+The `macos` track added a set of env-gated, diagnostic-only `GE_` probes to
+triage the D589/D591/D592 wide-pixel + GL-layer work. All of them are **off
+by default** (a `getenv` returns NULL → no code runs) and **change no game
+behavior** when unset. The decision owed before any merge toward `main`
+(§4, post-1.0) is, per probe: **keep** (a useful shipping debug tool) or
+**strip** (diagnostic-only, no shipping value, or a `src/game` edit that is
+not a port-layer fix). This file is that catalog — the tracker row is ROADMAP
+§7 "GE_ probe catalog."
+
+## The macOS-track texture / ABI probes
+
+| Probe | Where | Gate | What it does | Disposition |
+|---|---|---|---|---|
+| `GE_TEXDUMP` | `port/fast3d/gfx_pc.cpp` (import) + `port/fast3d/gfx_opengl.cpp` (GL upload) | master, cached `getenv` | Per-import `GE_TEXI`/`GE_TEXN` log lines; `texdump/rNNN_*` normalized bins; GL-level `tNNN_*.ppm` + `.rgba32` (the exact `glTexImage2D` input, D592 Q1). Zero hot-loop cost when unset (the `getenv` is cached once). | **KEEP** — the standing cross-platform texture-triage tool (predates the macOS track; B2/D161). |
+| `GE_TEXDUMPROW` | `port/fast3d/gfx_pc.cpp` | sub-gate (needs `GE_TEXDUMP`) | Dumps the FINAL post-transform source bytes keyed by the stable RAW source address (`texdump/row_<rawaddr>_f<fmt>_s<siz>.bin`) — the D592 cross-platform byte-compare key. | **KEEP** — cheap, off by default, and the raw-addr key is the right way to compare a specific texture across platforms (the positional rNNN index is not a stable key). |
+| `GE_TEXRAW` | `port/fast3d/gfx_pc.cpp` | sub-gate (needs `GE_TEXDUMP`) | Writes the RAW source bytes handed to the importer (`texdump/rNNN_*.bin`). | **KEEP** — part of the same triage family. |
+| `GE_TEXP` | **`src/game/image.c`** | independent `getenv` | D589 L2: logs pool-cursor state after each pool load. | **STRIPPED 2026-10-08** — `image.c` is back to the N64 build in this region; the pool-cursor dump served the D589 L2 cross-check only. |
+| `GE_SIZEOF` | `port/src/main.c` | `#ifdef PORT` + `getenv` | Startup ABI-width canary (`sizeof` of key structs/pointers) for a quick 32/64-bit sanity check on a fresh platform. | **STRIPPED 2026-10-08** — the ongoing ABI-width check is the `tools_pc/abi_ratchet.py` CI ratchet; `main.c` also drops the `game/image.h` include it needed. |
+| `GE_NPOT_NOGENMIP` (+ companion single-level sampler fix) | `port/fast3d/gfx_opengl.cpp` | `#ifdef PORT` + `getenv`, default off | The D592 NPOT `glGenerateMipmap` guard (skip mips on NPOT textures) + a companion that forced a single-level min filter under the guard. **REVERTED 2026-10-08 (`b80dcd08`)** when **D592 closed as a non-issue**: the "rock striping" was a VHF-metric false-positive (natural rock grain), and the `GE_TEXSTATE` probe showed the sampler state + NPOT mip level counts are byte-identical Win/Mac, so the guard had nothing to fix. | **REMOVED** — no longer in the tree (was `9bed5904` + companion `82dbea9c`). |
+| `GE_TEXSTATE` | `port/fast3d/gfx_opengl.cpp` (upload + set_sampler) | `#ifdef PORT` + `getenv`, default off, needs `--debug-gl` (logs at `LOG_NOTE`) | D592 Q2: logged the **effective sampler state** for the bound texture + per-NPOT-shape mip level counts. Confirmed the sampler state **and** the NPOT mip levels are **byte-identical Win/Mac** (the Metal backend builds the full NPOT mip chain; the aniso extension is present on both), which is the core evidence that closed D592. | **STRIPPED 2026-10-08 (`b80dcd08`)** — one-off D592 GL-state diagnostic, removed with the guard when D592 closed as a non-issue. |
+| `GE_KEYLOG` | `port/src/video.c` (`videoPumpEvents`) + `port/src/input.c` (`inputComputePadSlot`) | `getenv`, default off (writes `./ge_keylog.txt`) | D594: logs SDL key/mouse-button **events** on the main (host) thread (`E main KEYDOWN/KEYUP/MOUSEBT-…`) and the scheduler-thread **per-frame poll** (`P sched A/W/S/D/LMB/RMB`, change-only) to `./ge_keylog.txt`. The two streams together answer "do the key events reach the game, and does the *different* scheduler thread ever see them?" (the cross-thread poll is the D594 prime suspect). Validated on Windows (known-good input: poll logs the all-zero baseline; event lines fire on real key/mouse press). | **STRIPPED 2026-10-08** — both helpers and their two call sites removed (`video.c`, `input.c`). The D597 headless fire check is now "no SIGSEGV while firing" only (it no longer logs `LMB=1`). |
+
+## Notes
+- **Stripping is a mechanical, behavior-neutral edit**: delete the `getenv`
+  + the env-gated block; nothing else references the probe (each is self-
+  contained). `GE_TEXP`, `GE_SIZEOF`, and `GE_KEYLOG` are the ones still in the
+  tree with a real "should not ship" character; the `GE_TEXDUMP` family is the
+  kind of triage tool that earns its place. `GE_NPOT_NOGENMIP` (+ its
+  companion) and `GE_TEXSTATE` are already gone (`b80dcd08`) with the D592
+  close-out.
+- The broader `GE_` set (the ~70 vars in `port/`: `GE_QUITFRAME`, `GE_PCDUMP`,
+  `GE_RSEED`, `GE_DETERM`, the `GE_OPTIONSOVERLAY_*` UI probes, the `GE_ZF*`
+  z-fog family, etc.) is the standing debug-tool set and is **out of scope**
+  for this decision — it already ships. Only the **macOS-track additions**
+  above need a keep/strip verdict.
+- **Ordering:** strip (or consciously keep) `GE_TEXP` + `GE_SIZEOF` +
+  `GE_KEYLOG` as part of the §4 post-1.0 macOS merge, *before* the branch goes
+  near `main`; leave the `GE_TEXDUMP` family in. (`GE_NPOT_NOGENMIP` +
+  `GE_TEXSTATE` are already stripped with the D592 close-out, `b80dcd08`.)

docs/dev/GRAPHICS-BACKLOG.md

@@ -1,51 +0,0 @@
-# GRAPHICS-BACKLOG — known cosmetic / rendering issues
-
-Deferred below level-progression and crash work (user priority, M-11).
-Minor graphical glitches are acceptable in the current state. Fix these
-once the game is playable start-to-finish without crashes.
-
-## Open
-
-| ID | Symptom | Status / notes |
-|----|---------|----------------|
-| ~~**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". |
-| **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 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 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). |
-| **D176** | Surface exterior renders wrong (two co-located defects). **(a)** Sky is solid **black** — the skybox / sky gradient does not draw at all (reference: warm sunset cloud gradient). **(b)** The perimeter **tree-line backdrop renders as grey TV-static / comb interlacing** instead of snow-laden pines — the geometry is present and roughly the right silhouette but every tree texture is scrambled noise. Ground, tunnel and the dish/bunker building draw fine. | **Observed, screenshots committed** (M-35, user QA; `docs/img/bugs/d176-surface-exterior-our-build.png` vs `-reference.png`). Level is the shared Surface exterior — user reached it Dam→Surface on Agent so this is **Surface (i) `-level_36`** (confirm it also affects `-level_43`). **(a)** black sky: **M-36 partial (findings.md "D176(a)").** Env data is correct (`Sky.Clouds=1`, `CloudRGB=240,120,30`, `SkyImageId=0`); `skyRender` runs the cloud path and classifies corners correctly (switch case 12), but `skyRenderTri`/`skyRenderFull` emit nothing — not even the `env->RGB` fill shows. Not root-caused: next is probing `sub_GAME_7F097388` projected coords, verifying `skywaterimages[0]` resolves on PC (`image_bank.c` GIMG offset `0xFB4`), and a fast3d sky-tri trace. `GE_D176=1` probe shipped. **M-37: ROOT-CAUSED** — `skyRenderTri`/`skyRenderFull` build geometry *exclusively* as `G_RDPHALF_*` immediates, which `gfx_pc.cpp` deliberately no-ops (identical no-op in the PD port); fix = decode the RDPHALF tri-raster stream in fast3d (~1 session, genuine new code). **M-42: `-level_22` (Statue) confirmed a clean headless repro** — bare boot, frame ~360, upper half pure black; use it to verify the decoder. **M-47 + read-only consolidation:** Path B draft exists (`scratchpad/sky.patch`, `skyPortRenderPoly` PORT hook — geometry+texture reach GL, two unit defects open) and the full RDPHALF wire format is now decoded (S15.1 half-packing, 8-component perspective-interpolated vertex vectors); next session is mechanical per `docs/dev/D176a-SKY-NOTES.md`. `-level_36`/`-43` intro cams face down (not a sky test without `GE_INPUTSCRIPT`). **M-82: PR #18 rebased onto main + Defect-1 fix applied** — cloud tile is `s_skywaterimages[0]` = 64×64 IA8; the patch's `tc = S·32` scale is correct (matches GE's `width<<5` idiom, `glass2.c:678`), the bug was `(s16)` overflow on the ±20k-texel horizon S/T; fix = per-primitive phase-fold to the 64-texel period (`sky.c` `skyPortRenderPoly`, `#ifdef PORT`). Builds clean, no crash (bunker1/statue/surface1 verify PASS). **Unverified visually** — owed: one `-level_22` screenshot (see `D176a-SKY-NOTES.md` "verification ask"). Defect 2 (horizon-band coverage / straddling tris) still open → adaptive tessellation. **(b)** tree/rock static: **M-36 triage — NOT the D159 family.** `texSwapAltRowBytes` is a full `#ifdef PORT` no-op (`image.c:2199`), it cannot cause this. Real cause: `port/fast3d/gfx_pc.cpp` `import_texture_*` assume `line_size_bytes == full_image_line_size_bytes` (`SUPPORT_CHECK`; rgba16's is commented out *"trips ... with a garbage size"* `:658`) → non-PoT / sub-rect tiles get a flat linear read → diagonal row shear = grey static. **Family A** in `docs/dev/M-36-TRIAGE.md`. Fix: honour `line_size_bytes` as the real source pitch. Same defect as D182(2). |
-| ~~**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. | **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). **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)
-
-- D70–D74: intro-logo pixels (Rareware logo renders correctly).
-- D103: viewport / native-resolution half-frame.
-- D105: room geometry Z-buffer never cleared (`G_CLEAR_DEPTH_EXT`).
-- D106: sky-void through doorways (portal near-plane min>max).
-- D107: blurry ceilings/wall-panels (LOD mip tile fabrication).
-- D112: skeletal models were "3D lines" (`d43_emit.py put_f32` byte order).

docs/dev/HANDOFF-ARCHIVE.md

@@ -1,5 +1,11 @@
 # HANDOFF ARCHIVE — session-by-session narrative
 
+> **Local machine paths are genericised** in this archive: `<repo>` = this repo's
+> working directory, `<repos>` = the local source-repos root, `<games>` / `<videos>`
+> = the local games / video roots, `<python>` = the local CPython install, `<temp>`
+> = a writable native temp dir, `<msys>` = the local MSYS2 install root.
+> Session facts are unchanged.
+
 > **Reference only.** Current state lives in the [README](../../README.md)
 > "Status" section and `docs/dev/LEVEL-STATUS.md`; per-finding detail is in
 > [`findings.md`](findings.md) §F/§H — look up via
@@ -985,7 +991,7 @@ In KEEP-A test (sky quad only), the band shows (98,97,128) = fog color. This mea
 ### Environment & build
 
 - Build: `export PATH="/c/msys64/mingw64/bin:$PATH" && cmake --build build-pc -j 8`
-- Python: `"C:\Users\james\AppData\Local\Programs\Python\Python313\python.exe"` (has numpy+PIL)
+- Python: `"<python>\python.exe"` (has numpy+PIL)
 - Run: from repo root, ROM in `./data/`. Level: `-level_36`
 - Frame capture: F12 → `ppm/frame_NNN.ppm`; or `GE_PCDUMP=lo-hi:step`
 - Input script: `GE_INPUTSCRIPT="120:START;..."` (M-99: CANNOT reach mouselook)
@@ -1081,7 +1087,7 @@ Facility = `-level_34` (stageId 34 = `LEVELID_FACILITY`; `boss.c` decodes `-leve
 4. Diff behaviour vs a level whose opening beat DOES work (e.g. Dam `-level_33`) to isolate "Facility data" vs "general beat machinery".
 5. Any fix: port-only unless it's the documented ABI/layout class; new finding = D266+; append to `docs/porting-notes.md` if a new bug class emerges.
 
-**Environment (unchanged from prior sessions):** build `export PATH="/c/msys64/mingw64/bin:$PATH" && cmake --build build-pc -j 8` (or `./build-pc.sh ntsc-final`); kill any running `ge007*` before linking. Exe `build-pc/ge007.x86_64.exe`, run from repo root (ROM in `./data/`). Headless: `GE_INPUTSCRIPT` (tokens A/B/Z/START/UP/DOWN/LEFT/RIGHT/CUP/CDOWN/CLEFT/CRIGHT/SDOWN/SNONE, `tick:TOKEN;…`, pulse = 6 reads), `GE_PCDUMP=lo-hi:step`, `GE_INPUTLOG=1`, F12 → `ppm/shot_NNN.ppm`. Python (PIL/numpy) at `/c/Users/james/AppData/Local/Programs/Python/Python313/python.exe`; **cast uint8 arrays to int32 before bit shifts**.
+**Environment (unchanged from prior sessions):** build `export PATH="/c/msys64/mingw64/bin:$PATH" && cmake --build build-pc -j 8` (or `./build-pc.sh ntsc-final`); kill any running `ge007*` before linking. Exe `build-pc/ge007.x86_64.exe`, run from repo root (ROM in `./data/`). Headless: `GE_INPUTSCRIPT` (tokens A/B/Z/START/UP/DOWN/LEFT/RIGHT/CUP/CDOWN/CLEFT/CRIGHT/SDOWN/SNONE, `tick:TOKEN;…`, pulse = 6 reads), `GE_PCDUMP=lo-hi:step`, `GE_INPUTLOG=1`, F12 → `ppm/shot_NNN.ppm`. Python (PIL/numpy) at `<python>`; **cast uint8 arrays to int32 before bit shifts**.
 
 ---
 
@@ -1345,7 +1351,7 @@ will do a full manual playtest in lieu of the `verify.sh` sweep.
 3. **Steam Deck test session (~1 hr, needs the hardware — who has the Deck?):** install tarball via USB, Facility walk+fire (D203 repro profile), gamepad check, `Video.DisplayFPS` on Dam + Streets, grab `ge007.crash.log` if anything faults.
 4. Tag `v0.2.0-pre`; publish pre-release with known issues: D243 (Dam end race), D230 (music quality), D245 (water seam), D246 (edge strips), D197 (face wrap on Silo), D75 (front-end models), the D251 4K ghost row, and "not yet verified on real Deck hardware". Flip to final after the user's playtest passes.
 
-**Environment:** build as before (`/c/msys64/usr/bin/bash.exe -lc 'export PATH=/c/msys64/mingw64/bin:$PATH; cd /c/Users/james/Source/Repos/gh-fullhist && ./build-pc.sh ntsc-final'`). CI (`.github/workflows/ci.yml`) builds Linux per push — the `linux-build` job's artifact is the bundle source for the tarball if local Linux testing isn't available.
+**Environment:** build as before (`/c/msys64/usr/bin/bash.exe -lc 'export PATH=/c/msys64/mingw64/bin:$PATH; cd <repo> && ./build-pc.sh ntsc-final'`). CI (`.github/workflows/ci.yml`) builds Linux per push — the `linux-build` job's artifact is the bundle source for the tarball if local Linux testing isn't available.
 
 ## F10 overlay QoL session (2026-09-13, shipped in v0.2.0-pre) — D251; known bug: intermittent 4K-fullscreen "repeat of top entry" at panel bottom (MSAA×fullscreen driver suspect, unverified)
 
@@ -1373,7 +1379,7 @@ will do a full manual playtest in lieu of the `verify.sh` sweep.
 **Environment / state notes:**
 - User's live `data/ge007.ini` already has `Fullscreen = 1`, `MSAA = 4` (backup at `/tmp/ge007.ini.bak` — I did not modify their ini). Monitor: single display 3072×1728, window fullscreen at 0,0.
 - `ppm/user4k.png` exists from a PowerShell `CopyFromScreen` capture but was taken with the overlay **closed** — low value; user asked to stop analyzing captures.
-- Build: `/c/msys64/usr/bin/bash.exe -lc 'export PATH=/c/msys64/mingw64/bin:$PATH; cd /c/Users/james/Source/Repos/gh-fullhist && ./build-pc.sh ntsc-final'`. Launch from repo root: `./build-pc/ge007.x86_64.exe &` (needs `./data/` ROM).
+- Build: `/c/msys64/usr/bin/bash.exe -lc 'export PATH=/c/msys64/mingw64/bin:$PATH; cd <repo> && ./build-pc.sh ntsc-final'`. Launch from repo root: `./build-pc/ge007.x86_64.exe &` (needs `./data/` ROM).
 - Design doc for the overlay: `docs/dev/OPTIONS-MENU-PLAN.md` (approach C: port-layer overlay, zero src/ menu edits).
 
 ## M-123 (2026-09-14) — D194 ① log mined + wrap-spike fixed; spazz NOT in our writes (they're rock-stable); next: live capture with the new residue/autoaim logging, then user A/B playtest
@@ -1398,7 +1404,7 @@ will do a full manual playtest in lieu of the `verify.sh` sweep.
 
 ## M-122 (2026-09-13) — D194 GEPD-mirror aim IMPLEMENTED + user-confirmed "mechanically works"; three items left: ① crosshair/arm spazz glitch, ② aim-mode FPS drop (perf.ps1), ③ sensitivity tuning. Next session starts at ①.
 
-**The aim rewrite landed.** After four failed stick-synthesis models (absolute → dial → relative-angle → velocity-mapped stick; see M-121 + commits `8a8d066b`/`650b7f63`/`7f65ed15`), the session found and read **GEPD's actual source** (`C:\Users\james\Games\Emulators\Nintendo 64\1964_GEPD_Edition\1964\source.tar.xz` → `MouseInjectorPlugin/games/goldeneye.c`, extracted copy at `/c/Users/james/AppData/Local/Temp/gepd-src/`) and mirrored its model exactly. **User verdict: "mechanically it works... the aim mode works how we'd want."** Committed as `ef49d9e6` on `fix/d194-mouse-dt-decouple` (branch is up to date with main; PR #75/#76 already merged in).
+**The aim rewrite landed.** After four failed stick-synthesis models (absolute → dial → relative-angle → velocity-mapped stick; see M-121 + commits `8a8d066b`/`650b7f63`/`7f65ed15`), the session found and read **GEPD's actual source** (`<games>\Emulators\Nintendo 64\1964_GEPD_Edition\1964\source.tar.xz` → `MouseInjectorPlugin/games/goldeneye.c`, extracted copy at `<temp>/gepd-src/`) and mirrored its model exactly. **User verdict: "mechanically it works... the aim mode works how we'd want."** Committed as `ef49d9e6` on `fix/d194-mouse-dt-decouple` (branch is up to date with main; PR #75/#76 already merged in).
 
 **The model (all in `port/src/input.c`, `aimGepdCompute()` ~line 1377):** mouse delta moves a crosshair POSITION accumulator (`s_gepdCrossX/Y`, clamped ±`GEPD_CROSSHAIR_LIMIT`=5.16); each tick it writes `crosshair_x/y_pos` + `gun_azimuth_angle/turning` (GEPD formulas, failsafe weapon offsets 0.15/0, RATIOFACTOR=1 for our 4:3, `GEPD_BASE_FOV`=90) and edge-scrolls the camera only past 72% toward the screen edge (`(ratio-0.72)*475*dt*(fov/90)`). **No look stick is emitted while aiming.** On aim release we stop writing and the game's own damping eases crosshair+arm back to centre; every non-aim tick adopts `crosshair_x/y_pos` so re-entry starts where the game left it (GEPD does the same).
 
@@ -1437,7 +1443,7 @@ will do a full manual playtest in lieu of the `verify.sh` sweep.
 **RMB aim-mode (D194 continuation): two more attempts this session, both did not land, session ended mid-plan on the weekly usage limit.**
 
 - **Attempt 1 (small, safe): raised `AIM_MOVE_THRESH` 0.3->2.5px and lowered `Input.MouseAimSpeed` default 16->14 (matching the user's live ini, which had drifted to 50).** User's verdict: **"didn't actually fix anything"** — confirms the core problem isn't a magnitude/gain issue, it's the shape of the response.
-- **Real root cause found via code reading (still valid, not invalidated by what follows):** `bondviewProcessInput(s8 stick_x, s8 stick_y, ...)` in `src/game/bondview2.c` takes a **signed 8-bit stick** — the smallest representable nonzero aim-turn value is a hard jump to 10% speed (stick=61; `(stick-60)/10` is exactly 0 at stick<=60). No threshold/curve tuning on the port's synthesis side can produce a smooth ramp through an integer that can only be 60 or >=61. Confirmed via `pd_port` (`C:\Users\james\Source\Repos\pd_port`) reference: PD's own mouse-look (`src/game/player.c:3669`, `src/game/bondeyespy.c:945`) never synthesizes an N64 stick at all -- it's `theta += mdx * scale`, a continuous float angle accumulator, no floor, no int8 quantization anywhere.
+- **Real root cause found via code reading (still valid, not invalidated by what follows):** `bondviewProcessInput(s8 stick_x, s8 stick_y, ...)` in `src/game/bondview2.c` takes a **signed 8-bit stick** — the smallest representable nonzero aim-turn value is a hard jump to 10% speed (stick=61; `(stick-60)/10` is exactly 0 at stick<=60). No threshold/curve tuning on the port's synthesis side can produce a smooth ramp through an integer that can only be 60 or >=61. Confirmed via `pd_port` (`<repos>\pd_port`) reference: PD's own mouse-look (`src/game/player.c:3669`, `src/game/bondeyespy.c:945`) never synthesizes an N64 stick at all -- it's `theta += mdx * scale`, a continuous float angle accumulator, no floor, no int8 quantization anywhere.
 - **User also reported a second, more specific symptom mid-investigation: aim resets to center the instant mouse movement pauses (even while still holding RMB), breaking precision tasks (shoot-the-lock, watch-laser-cuts-metal-in-train puzzles).** Traced `bondviewCurrentPlayerUpdateSpeedTheta`/`speedVertaUp`/`Down` (bondview2.c) in detail: confirmed this is a smoothed rate-based decel model (`g_CurrentPlayer->speedtheta` eases toward 0 over several ticks when input stops, does NOT hard-reset) -- so a literal snap-to-center was not found in that specific mechanism. Root cause of the reset symptom specifically was **not conclusively identified** before moving to the rewrite.
 - **Attempt 2 (bigger, PD-style, approved by user before starting): bypassed the s8-stick synthesis entirely for aim-mode.** `port/src/input.c` computed a continuous -1..1 turn/vert speed (`inputGetContinuousAimSpeed()`, new function + header decl) instead of synthesizing `sx`/`sy`; `src/game/bondview2.c`'s aim-mode block (`#ifdef PORT`) read it directly, bypassing the `(stick-60)/10` conversion but leaving all downstream `speedtheta`/`speedverta` easing untouched. Removed the now-dead `Input.AimBand`/`Input.MouseAimCurve` knobs. **Compiled clean (verified both PORT and N64 `#ifdef` brace balance carefully), crash-free in a headless sanity check -- but broke live: "somethings broken... can't aim at all... it locks my input completely with the mouse."** Root cause of THAT breakage was not identified (no repro available headlessly; ran out of session before a careful live-debug pass). **Fully reverted** (`git checkout -- src/game/bondview2.c port/src/input.c port/include/input.h` back to the `db6eba2b` merge commit) — repo confirmed clean, PR #62's mouse work is back to its pre-session (working, if imperfectly-tuned) state. Live ini's `MouseAimSpeed` also manually restored 14->16 to match the reverted code default.
 
@@ -1893,7 +1899,7 @@ current testing, folded in:
    player's already-fixed 1P viewmodel isn't implicated. Narrows the
    search surface.
 3. **D194 mouse feel — external corroboration, not a new mechanism.**
-   Investigated `C:\Users\james\Games\Emulators\Nintendo 64\1964_GEPD_Edition`
+   Investigated `<games>\Emulators\Nintendo 64\1964_GEPD_Edition`
    (the user's reference point for "feels better") — the 1964 emulator's
    bundled `Mouse_Injector.dll` (closed-source, no source available; the
    emulator's own `source.tar.xz` is just the stock 1964 core). Its exports
@@ -2839,7 +2845,7 @@ except `bg.c`'s `GE_D63` lines which are not `#ifdef PORT`-guarded).
 
 ## Playtest bug reports (M-49 cont., 2026-09-04) — logged for future triage, NOT v0.1.0 blockers
 
-User playtested the **v0.1.0 win64 bundle** (`C:\Users\james\Games\goldeneye-pc-port-0.1.0-win64`,
+User playtested the **v0.1.0 win64 bundle** (`<games>\goldeneye-pc-port-0.1.0-win64`,
 fresh save). Bugs filed in findings §F (D191–D197), all alpha-acceptable.
 NB: Cradle does **not** crash — it's the D193 scripted-sequence stall (an
 earlier note here wrongly said "Cradle also crashes").
@@ -3303,7 +3309,7 @@ collision geometry. Full ranked next-steps in findings.md D205.
 6. Build + smoke after probe removal: `./build-pc.sh ntsc-final`, then
    `-level_09` 60 s crash-free with `GE_AUDIOTRACE=1`.
 ### Environment (unchanged except noted):
-- Build: `/c/msys64/usr/bin/bash.exe -lc 'cd /c/Users/james/Source/Repos/gh-fullhist && ./build-pc.sh ntsc-final'` (login shell for MINGW64 PATH; SDL2.dll at `/c/msys64/mingw64/bin`).
+- Build: `/c/msys64/usr/bin/bash.exe -lc 'cd <repo> && ./build-pc.sh ntsc-final'` (login shell for MINGW64 PATH; SDL2.dll at `/c/msys64/mingw64/bin`).
 - Capture run: `GE_AUDIOTRACE=1 GE_INPUTSCRIPT="$(cat ../scratchpad/exact_run3_script.txt)" ./ge007.x86_64.exe -level_09` from `build-pc/`; kill with `taskkill //F //PID <pid>` (msys `kill` does not work).
 - `mupen64/` (N64 emulator, user's A/B reference) at repo root — added to .gitignore this session.
 - `scratchpad/` is gitignored: banktest/, exact_match.py, fire scripts, match outputs are all local-only. To re-verify the bank exoneration: `scratchpad/banktest/harness.exe` (rebuild from harness.c against port/src/romdata.c if stale) then `python scratchpad/banktest/diff_bank.py`.
@@ -3391,7 +3397,7 @@ archived user capture: `scratchpad/d202-m66/` (`check_dump.py`,
 The `[EXPIRE]` line and the guard/expire code STAY (permanent, documented).
 Build note for this shell: toolchain at `/c/msys64/mingw64/bin`, and
 `cmake --build -j` hit "Cannot create temporary file in C:\\Windows\\" —
-`ninja -j1` with `TMP/TEMP=C:/Users/james/AppData/Local/Temp` works.
+`ninja -j1` with a writable native `TMP/TEMP` works.
 
 ## Done this session (M-66) — D202 ROOT CAUSE ESTABLISHED: the audible stuck door loop is sound 203 behaving exactly as ROM + ground-truth code specify — faithful N64 behaviour (original quirk), not a port bug. Disposition A/B/C pending user decision.
 
@@ -4765,7 +4771,7 @@ does not.
 Build locally: `cmake -S . -B build-linux -G Ninja -DROMID=ntsc-final
 -DCMAKE_C_COMPILER=gcc-14 -DCMAKE_CXX_COMPILER=g++-14` then `ninja -C
 build-linux` (~20s on drvfs). WSL `Ubuntu` distro provisioned (toolchain +
-SDL2/zlib/GL dev); repo at `/mnt/c/Users/james/Source/Repos/gh-fullhist`
+SDL2/zlib/GL dev); repo at `<repo>`
 (fixed the malformed `/etc/wsl.conf` `[automount]` + `wsl --shutdown`).
 `data/` has the ROM + sidecars already.
 
@@ -5074,7 +5080,7 @@ playtest handoff: `docs/dev/M-35-PLAYTEST-CHECKLIST.md`; WI-3 design:
 (`d43_emit.py` / `d69_emit.py` / `d88_emit.py --regen`, all pass clean) → `./build-pc.sh
 ntsc-final` links 242/242, `-level_09` runs crash-free past frame 1200. **No `assets/*.bin`
 extraction needed** — the committed `assets/` is self-sufficient; the ROM is runtime-only.
-The old repo at `C:/Users/james/Source/Repos/007` has the ROM + a prior build.
+The old repo at `<repos>/007` has the ROM + a prior build.
 
 - **D168 — VERIFIED.** Rebuilt with the flip fix, captured `-level_09` frame 320:
   the exit arrow points up, ammo "7|93" reads normally bottom-right — matches
@@ -6163,3 +6169,217 @@ Run from the **repo root**, not `build-pc/`.
    rating, don't hack it in.
 3. Prefer an **offline sidecar converter** (`tools_pc/d*_emit.py`,
    D43/D69/D88 pattern) over a runtime fixup for a whole ROM-asset format.
+---
+
+# Appended 2026-10-05 (session 07j) — moved verbatim from `docs/HANDOFF.md` (briefs 2026-10-05 (session 07d) → 2026-10-05 (session 07g))
+
+# HANDOFF — 2026-10-05 (session 07d)
+
+## Branch
+`release/v0.4.1` @ `e9cf2ddf` (D530 addendum), tree clean.
+Local-only commits on top of `442eb2ff`: `aa19b354` (site SEO/redundancy),
+`2c378e7e`+`24b084d0` (Known issues), `ada7bbb1` (D530 goldens), `e9cf2ddf`
+(D530 addendum). **Nothing pushed.**
+
+## This session (2026-10-05 (session 07d), user stepped away ~10:45, returns ~14:00 EDT)
+
+1. **HANDOFF 07c item 1 (critical path) — DONE, committed (`ada7bbb1`):**
+   - The X220 P7 re-round had completed on the box 2026-10-05 (tree `442eb2ff`,
+     worktree `~/gh-fullhist-wt-p7`, `~/p7-reround.log` hit `P7 re-round DONE`
+     12:53 EDT, **21/21 levels rc=0** under the canonical `ge007.eep`).
+   - Pulled the 63 PNGs (15 MB tarball → `scratch/p7-pull/`, log →
+     `scratch/p7-reround-pull.log`) and committed them into
+     `tools_pc/golden/<level>/linux/`, replacing the D525 cleared-eep set:
+     **51/63 differ; 12/63 byte-identical** (save-independent scenes,
+     including frigate's first stem 001000 — a D117 stability signal).
+   - **D117 flaky-four first-stem check (D529 never-do 6, first cross-machine
+     test):** dam@1500 worst_cell 1.70 (phash 0), frigate@1000 byte-identical,
+     streets@1000 1.78 (phash 0), jungle@900 5.12 (phash 3) — all in
+     stable-level range, **none red → NO first-stem exclusion/widening**.
+   - Structural tier all `ok` (cradle@40 documented exception; Cuba 26.4%
+     within the documented 23.7–36.3% structural-only range). The `fail` rows
+     in the box report are the expected cross-eep diffs vs the old set.
+   - **Closes D529 never-do 3:** the index/README v0.5.0 "re-based on both
+     platforms (21 levels, 63 frames each)" line now stands on a
+     canonical-eep linux set → linux numbers unblocked (B7 satisfied).
+   - Wrote **D530** (findings.md detail + §F table: D523 now SUPERSEDED-by-
+     D529, D529 row was missing from the table — the 07c CSV had been
+     hand-patched, which is why `gen_findings_index.py --check` drifted;
+     regenerated) + `tools_pc/golden/README.md` linux-set text + History.
+
+2. **DONE: fresh `verify.sh sweep` on the box against the NEW goldens**
+   (shipped the 51 PNGs to `~/gh-fullhist-wt-p7`, box diff = 51 = the
+   tree delta; fired 10:5x EDT, finished ~11:10 EDT): **21/21 PASS, 0
+   FAIL** — but the run was **crash-detect only** (GE_PCDUMP reads black
+   on the box's llvmpipe/WSLg, the D244 note; no pixel gate). So it is a
+   stability re-check; the D117 cross-machine *pixel* evidence remains the
+   re-round capture itself (the D530 first-stem check). Recorded as the
+   D530 addendum (`e9cf2ddf`) with the residual: a pixel-gated box verify
+   needs a working WSLg GPU session (the 10-05 re-round's pixel comparisons
+   ran fine, so one exists).
+   - Log pulled: `scratch/p7-verify-new-pull.log` (tail: `21` PASS, `0`
+     FAIL, `SWEEP DONE`).
+
+3. **DONE (partial, at push time still owed): PII scrub addendum for the 51
+   new golden PNGs** — EXIF/text metadata sweep over all 63 linux PNGs:
+   **0 metadata tags** (PIL); new doc text (D530, golden README) uses
+   "X220" + `~/` paths only — no absolute paths/usernames/private IPs in
+   tracked files (the box LAN address lives only in the gitignored
+   HANDOFF + scratch logs). Addendum appended to
+   `docs/dev/notes/PII-SCRUB-REPORT.md` (gitignored). The full
+   LEGAL-review pass (game-content rule for screenshots) is still owed at
+   push time.
+
+## User to review at ~14:00 EDT
+- Local batch of 5 doc/golden commits (`aa19b354` SEO/redundancy;
+  `2c378e7e`+`24b084d0` Known issues; `ada7bbb1` D530 goldens; `e9cf2ddf`
+  D530 addendum — box sweep 21/21 crash-detect PASS).
+- Then the standing HANDOFF 07c items: 2. maintainer review of the 12-file
+  batch; 3. P12 U2/U5/U6/U7 (deferred light-unit mechanical review);
+  4. re-cut squash → B7/B8/B9 (README linux numbers now unblocked);
+  5. push `release/v0.5.0` + tag.
+
+## Environment
+- Preview: `:8777` (PID may be stale after a reboot — `node
+  scratch/build_preview.mjs site && node scratch/serve_preview.mjs 8777`).
+- Box ssh: `ssh` to the X220 box (Windows→box works; box has no sshd —
+  everything rides the same session's stdin/stdout; pushes via
+  `cat f | ssh ... 'cat > dest'` or tar pipes).
+- 3 parked worktrees (ci/d441/modpatch) untouched.
+
+---
+
+# HANDOFF — 2026-10-05 (session 07e) (D531 + P12 U5)
+
+## Branch
+`release/v0.4.1` @ `164920c6`, tree clean. Three more local-only commits on
+top of `e9cf2ddf`: `4829fd94` (D531 blocker fix + canonical re-capture),
+`d2d75e11` (ROADMAP rows), `164920c6` (D531 addendum). **Nothing pushed.**
+
+## This session (2026-10-05 (session 07e))
+
+**D531 — `capture_p7.sh` canonical-re-pin blocker (P12 U5 review finding),
+fixed + re-captured. AMENDS D530.**
+
+- U5 reviewed `tools_pc/**` (the release-diff unit that owed the P7 merge):
+  small diffs all mechanical/clean; `p7_report.py`, `eep_convert.py`,
+  `abi_ratchet.py`, `docs_budget.py`, `abpad/` clean (list-arg subprocess,
+  raw_decode JSON, no shell, no destructive ops); deletions clean (probe
+  tools + the 433k-line sweep-capture PPM set). **But** `capture_p7.sh`'s
+  D529 adaptation was incomplete: the D524-era per-level re-pin
+  (`cp "$EEP_ORIG" "$EEP"`, restoring the pre-capture LOCAL save) silently
+  overwrote D529's pre-loop canonical install from level 1 — so **the
+  10-05 box re-round (D530) ran under the box-local save, not the
+  canonical eep**. D530's "canonical eep" provenance claim and first-stem
+  table are void as canonical-save evidence (D530 entry + README amended in
+  place; the table's numbers do check out against the 10-05 report).
+  **The win set is unaffected** — `verify.sh`'s `pin_eep` was correct.
+- Fix: the loop now re-pins `cp "$CANON_EEP" "$EEP"` per level (EEP_ORIG
+  kept for the exit-restore only); `cd "$ROOT"` added (the loop's
+  dump/golden paths are root-relative, contradicting the header's
+  "invoked from anywhere" claim).
+- **Re-captured:** shipped the fixed script to the box (sha matched), fresh
+  21-level round with `DISPLAY=:0` → 21/21 rc=0, 63 frames. **47/63 differ
+  from the D530 box-local-save set** (save content demonstrably moves
+  frames), 16 byte-identical. Committed into the linux goldens.
+- **Renderer finding (corrects the 07d item-2 note):** even with
+  `DISPLAY=:0` the box today reports no usable glxinfo renderer (software
+  fallback → black read-backs) — the WSLg GPU display is
+  **session-state-dependent** (the 10-05 re-round's p7_report pixel table
+  proves it was GPU-backed then). Today's `verify.sh sweep` against the new
+  goldens: **21/21 PASS, 0 FAIL, crash-detect only** (log
+  `scratch/p7-verify-pixel-pull.log`). The pixel-gated verdict (incl. the
+  four D117 flaky first stems) is owed for a GPU-display window.
+- Docs: D531 entry + §F row (regenerated CSV, 394 lines, `--check` OK),
+  D530 amended in place, golden README intro + History, ROADMAP Golden
+  baselines row (was still on D523 framing) + new P12 U5 row. PII addendum
+  #2 (63 PNGs, 0 metadata tags).
+
+**U5 should-fixes (rows on the ROADMAP, not yet applied):**
+1. `verify.sh` `pin_ini_640x480 2>/dev/null || true` fails OPEN (pin_eep
+   fails closed) — a failed ini write runs the gate under the user's
+   personal ini → spurious verdicts. Make it abort.
+2. `GOLDEN_SEED="${GE_RSEED:-…}"` lets a stray env var re-seed the gate —
+   warn or hard-pin (capture inherits the same override via its eval out
+   of verify.sh, so gate/capture stay consistent either way).
+3. `audiodebug.ps1` `-AB`/`-Old` are documented dead no-ops (nit).
+
+## User to review at ~14:00 EDT (supersedes the 07d list)
+- 8 local commits: `aa19b354` (site SEO/redundancy), `2c378e7e` +
+  `24b084d0` (Known issues), `ada7bbb1` (D530 goldens — now AMENDED BY
+  D531), `e9cf2ddf` (D530 addendum), `4829fd94` (D531), `d2d75e11`
+  (ROADMAP), `164920c6` (D531 addendum).
+- Preview: `node scratch/build_preview.mjs site` → `scratch/_site/` on :8777.
+
+## Still owed (unchanged, plus)
+- Pixel-gated box verify in a WSLg GPU-display window (never-do 6 applies
+  if the flaky four go red: exclude/widen, do NOT recapture).
+- The three U5 should-fixes above; P12 U2/U6/U7; HANDOFF 07c item 2
+  (maintainer review of the 12-file docs batch); squash → B7/B8/B9; push
+  `release/v0.5.0` + tag.
+- LEGAL review pass at push time (screenshots rule — 47 new linux PNGs are
+  the same class: box-captured, no metadata).
+
+---
+
+# HANDOFF — 2026-10-05 (session 07f) (D532 + squash re-cut + PUSH)
+
+## Pushed (2026-10-05 (session 07e)/f, maintainer approved)
+- **GitHub** `origin`: new branch `release/v0.5.0` (the re-cut squashed
+  chain, 33 commits, tip `f077435a`) + annotated tag `v0.5.0`.
+  **`origin/main` untouched** (`0e8c2ce2`) — main merge + public release
+  wait for the maintainer's playtest.
+- **Forgejo mirror**: `release/v0.5.0-squashed` + tag `v0.5.0`.
+- Squash re-cut: `scratch/p11b-squash.py` (p11 + new tip `4dd1d56d`,
+  assert 488, new group 33 covering D529-D532 + the site/amber pass).
+  Tip tree byte-identical (B7), LAN scrub of intermediate trees
+  re-applied, `pre-squash-v050` -> `4dd1d56d` (B6), tag message in
+  `scratch/tag-msg-v050.txt` (B8), PII/legal addenda on the final tree
+  (B9: clean; 4 pre-existing toolchain-path sites only).
+- **D532** (`4dd1d56d`) landed before the cut: verify.sh fail-closed
+  ini pin + hard-pinned seed (warn on stray `GE_RSEED`), audiodebug
+  dead switches removed. Docs: D532 entry/row, ROADMAP U5 row applied.
+
+## Now owed (in order)
+1. **Maintainer playtest** (C6 list: D511-D514/D519 items) on the
+   `release/v0.5.0` build → then remove the "not yet playtested live"
+   block and cut the `gh release` (C1-C9; bundles built FROM the pushed
+   tree).
+2. **Pixel-gated box verify** in a WSLg GPU-display window (D531; the
+   box worktree `~/gh-fullhist-wt-p7` is still at `442eb2ff` — needs a
+   bundle transfer of the new tip; no LAN route, options per the P7
+   handback §8).
+3. **P12 U2/U6/U7** quick passes (U1/U3/U4/U5 PASS; U6 = build+CI
+   diff, U7 = docs diff — read-only, ROADMAP rows for should-fixes).
+4. CI on the new GitHub branch: first real run of the SLSA
+   build-provenance attestation (ROADMAP "Release build-provenance
+   attestation" row: confirm, then delete).
+5. Box-side parallel: self-gate on the release branch (crash-detect
+   until the GPU window).
+
+## Local state
+`release/v0.4.1` @ `4dd1d56d` (== the pushed squashed tip tree), tree
+clean. `release/v0.5.0` / `release/v0.5.0-squashed` @ `f077435a`.
+`pre-squash-v050` @ `4dd1d56d`. Nothing else pending locally.
+
+---
+
+# HANDOFF — 2026-10-05 (session 07g) (push reverted; held local)
+
+- **GitHub push REVERTED** (branch `release/v0.5.0` + tag `v0.5.0` deleted,
+  verified via `git ls-remote`); backup lives on the private Forgejo mirror
+  (`release/v0.5.0-squashed` + tag `v0.5.0` @ `f077435a`). Local refs:
+  `release/v0.5.0` / `release/v0.5.0-squashed` @ `f077435a`,
+  `pre-squash-v050` @ `4dd1d56d`.
+- **Standing rule (maintainer):** backups → Forgejo, never GitHub; GitHub
+  pushes only after the maintainer approves everything.
+- **Docs finalization owed:** the batch review (`scratch/docs-batch-review.txt`,
+  commit `ba29c558` — 16 text files) and the **PR/SEO language pass**
+  (brief written: `scratch/pr-seo-revise-prompt.md` — tiers T1/T2/T3, voice,
+  SEO parity checklist, hard rules; example fix = the v0.5.0 News tagline
+  leading with "plain-English wording" + the UK/US spelling item demoted to
+  "small stuff").
+- Then: playtest (C6) → `gh release` (C1–C9) → the ONE approved GitHub push
+  (release branch + tag + release) → main.
+
+---

docs/dev/LEVEL-PLAYTEST.md

@@ -1,5 +1,7 @@
 # LEVEL-PLAYTEST — WS6 human completion-validation checklist
 
+> **Historical record — do not act on status claims in this file.** This checklist predates the v0.4.0 input model (D332–D337) and the campaign sign-off; use it as a template only. Current open work and status: [`docs/ROADMAP.md`](../ROADMAP.md) (2026-09-29).
+
 Run **after** `docs/dev/LEVEL-STATUS.md` is all-21 load+render PASS. This is
 the part that needs real input — a human plays each level start to finish
 and confirms it matches retail. Findings feed a WS5-style triage round

docs/dev/LEVEL-STATUS.md

@@ -1,5 +1,7 @@
 # LEVEL-STATUS — level load+render sweep (WS4) — 20 solo missions + ending sequence
 
+> **Historical record — do not act on status claims in this file.** The per-level sweep below predates the 2026-09-28 full-campaign sign-off; its open items (re-playthrough gate, M-49 completability, Cuba crash) are resolved. Current open work and status: [`docs/ROADMAP.md`](../ROADMAP.md) (2026-09-29).
+
 **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`,
@@ -73,7 +75,7 @@ cause. Only remaining crash:
   900. This is the **known D129 residual**: the bare `-level_54` boot
   reaches the cast/credits scroll referencing a text bank the real
   front-end flow would have loaded. Not a real-flow blocker; Cuba loads +
-  renders 300+ frames fine. Parked with D76 (`docs/dev/GRAPHICS-BACKLOG.md`).
+  renders 300+ frames fine. Parked with D76 (since fixed as D164).
 
 | Level | # | Status | Crash site | Class |
 |---|---|---|---|---|

docs/dev/LINUX-PORT.md

@@ -1,91 +0,0 @@
-# Linux port — status & gap analysis
-
-Session M-38 (2026-09-02). Goal-2 on the roadmap (after the Windows alpha /
-release artifact). This is a scoping + first-patch pass; **nothing here has run
-on a Linux machine yet.**
-
-## Method
-
-Read `build-pc.sh`, `CMakeLists.txt`, `docs/building.md`, and grepped
-`port/src`, `port/fast3d`, `port/include` for Windows-only headers / Win32 APIs
-/ unguarded `_WIN32` branches. A local Qwen `triage` pass seeded the hunt; every
-claim below was re-checked against the real files (the 27B was wrong on two of
-three headline items — see "Ruled out").
-
-## What is already Linux-ready (verified by reading)
-
-- **`port/include/platform.h`** — sets `PLATFORM_LINUX` / `PLATFORM_MACOS` /
-  `PLATFORM_WINDOWS` cleanly.
-- **`CMakeLists.txt`** — `find_package(SDL2 REQUIRED)`, `find_package(ZLIB
-  REQUIRED)`, and `else()` branches already present for the non-Windows case:
-  `GL_LIBRARY = GL` (l.291), `EXTRA_LIBRARIES = stdc++ m dl pthread` (l.304),
-  `elseif(UNIX)` platform block (l.86). `WIN32_EXECUTABLE` and the MinGW zlib
-  fallback are correctly `if(WIN32)` / `if(MINGW)` guarded.
-- **`build-pc.sh`** — already documents the Linux apt deps
-  (`cmake libsdl2-dev zlib1g-dev libgl1-mesa-dev`) and is a plain bash script,
-  no MSYS-isms in the executable body.
-- **`port/src/system.c`** — `sysSleep()` has a `nanosleep()` `#else` branch
-  (l.76-82); `<windows.h>` is `PLATFORM_WINDOWS`-guarded.
-- **`port/src/libultra.c`** — the OS-thread kernel has a real pthreads branch
-  next to the Win32 `_beginthreadex` one.
-- **`port/src/crash.c`** — `MessageBoxW` / `SetThreadPriority` / `__debugbreak`
-  all `_WIN32`-guarded, with `PLATFORM_LINUX` counterparts.
-- **`port/src/video.c`** — `GE_MKDIR` has both `_mkdir` and `mkdir(p,0777)`.
-- No `__declspec`, `#pragma comment`, or hardcoded `\`-path / drive-letter
-  usage anywhere in `port/`.
-
-## Ruled out (Qwen triage false positives)
-
-- ~~`system.c:75` `Sleep()` has no POSIX branch~~ — it does (`nanosleep`).
-- ~~CMake needs `else()` branches for zlib/pthread on Linux~~ — already there.
-
-## The one real code gap — FIXED this session (verification owed)
-
-**`port/src/romdata.c`** — the fixed-address cart map (`0x10000000`, so absolute
-ROM-asset symbols are live host pointers) had a **Windows-only** implementation
-(`VirtualAlloc`); the `#else` branch was a stub that logged "not implemented on
-this platform" and fell straight to the heap-copy fallback. In heap-copy mode
-anything that dereferences a cart address *directly* (not via
-`romdataGetRom()` / the PI shims) reads wrong memory — so Linux would run, if at
-all, in the same degraded mode Windows only hits when `VirtualAlloc` loses the
-address race.
-
-**Change (M-38):**
-- Factored the post-map work (memcpy + `pcmodelsLoadSidecars` +
-  `pccgLoadSidecars` + D55 RLE-header fixup) into `romdataFinishCartMap()`,
-  shared by both paths so they cannot drift.
-- POSIX `#else` now does an anonymous `mmap((void*)CART_BASE, len,
-  PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS|MAP_FIXED_NOREPLACE, -1, 0)`.
-  `MAP_FIXED_NOREPLACE` (Linux 4.17+) fails rather than clobbering an existing
-  mapping; where the macro is absent the plain hint is advisory and the
-  `at == CART_BASE` check catches a relocated result. On any failure it
-  `munmap`s and falls through to the identical heap-copy path as before.
-- `romdataDestroy()` `munmap`s on POSIX (tracked length in `mappedLen`).
-
-**Owed verification (needs a Linux box):**
-1. Compiles under GCC on Linux (`<sys/mman.h>` resolves; no decomp-include-path
-   shadowing surprise).
-2. `mmap` actually lands at `0x10000000` on a stock ASLR Linux — `0x10000000`
-   (256 MB) is low but usually free; if the kernel routinely refuses it,
-   consider linking the binary no-PIE or reserving the range via a linker
-   script so the loader keeps it clear.
-3. `-level_09` boots crash-free with the mapped path taken (check the log says
-   "mapped at 0x10000000 (cart base)", not "using heap copy").
-4. Whether the heap-copy fallback is actually survivable on Linux if step 2
-   fails — audit for direct `0x1xxxxxxx` derefs outside the PI shims.
-
-## Remaining Linux work after the romdata patch lands
-
-| # | Item | Size | Note |
-|---|------|------|------|
-| 1 | Run the Ubuntu **`validate`** CI job → upgrade it to a real **compile** job | S | `.github/workflows/ci.yml` already configures on Ubuntu; flipping it to `cmake --build` surfaces the real GCC-strictness gaps cheaply |
-| 2 | First actual Linux runtime bring-up (`-level_09`) | M | expect a short tail of unguarded calls / struct-layout asserts GCC-on-Linux vs MinGW |
-| 3 | `docs/building.md` — promote Linux from "untested" to "supported" once 1+2 pass | S | |
-| 4 | SDL2 / GL context creation on X11 + Wayland | M | fast3d is GL 3.3 core; PD port runs on Linux so the path is known-good |
-| 5 | Package: an AppImage or tarball equivalent of `bundle-win.sh` | M | reuse `prepare-assets.py` verbatim — it is already OS-agnostic |
-
-## Recommended next step
-
-Land the romdata patch behind CI (item 1) — turn the Ubuntu `validate` job into
-a compile job in the same PR so the "does it build on Linux" question is
-answered by the bots, then do the runtime bring-up on a real machine.

docs/dev/M-35-PLAYTEST-CHECKLIST.md

@@ -1,89 +0,0 @@
-# M-35 QoL playtest checklist
-
-Everything on this branch is config-gated to prior behaviour, so the
-**first** thing to confirm is that nothing changed with a default
-`ge007.ini`. Then flip the new keys and check the feel.
-
-Edit `data/ge007.ini` while the game is closed.
-
----
-
-## 0. Regression (default config) — do first
-
-- [ ] Delete `data/ge007.ini`, launch, quit. It rewrites with new keys:
-      `[Input] MouseCaptureMode = 0`, `[Game] ScreenShakeIntensity = 1`.
-      Existing keys keep their values.
-- [ ] Play a level normally (mouse grabbed on focus, as before). Mouse look,
-      aim (RMB), menus — all exactly as the last build. **No behaviour change
-      expected at defaults.**
-- [ ] Alt-tab away and back — cursor frees / re-grabs (unchanged).
-
-## 1. Click-to-lock capture — `Input.MouseCaptureMode = 1`
-
-- [ ] Launch. At the main menu the **OS cursor is visible and free**; moving
-      the mouse moves the game crosshair 1:1 (see item 3).
-- [ ] Click in the window during a level → cursor hides, mouse-look engages.
-- [ ] Press **ESC** during a level → cursor reappears, mouse-look stops,
-      you can move the pointer off the window. (ESC does *not* quit.)
-- [ ] Click back in → re-locks. First click only re-locks — it must **not**
-      fire the weapon.
-- [ ] Open the pause/watch (Start), then a front-end menu → cursor frees
-      automatically. Return to the stage → re-locks without a click.
-- [ ] Alt-tab out mid-level → cursor frees; alt-tab back → stays free until
-      you click (Quake behaviour).
-- **Correct feel:** exactly like Quake/Nightdive remasters — click to play,
-  ESC to get your cursor back.
-- **Tune:** none — it's a mode toggle.
-
-## 2. Aim sensitivity — B3
-
-- [ ] With `Input.MouseCaptureMode` either value, hold RMB (aim mode) and
-      make small aiming corrections. Default is now `MouseAimSpeed = 16`
-      (was 25).
-- **Correct feel:** you can settle the sight on a distant guard's head
-  without overshooting; a fast flick still crosses the screen.
-- **Tune:** `Input.MouseAimSpeed` (1–100+). Up = faster. If hipfire turning
-  now feels faster than aiming, raise `MouseAimSpeed` or lower
-  `Input.MouseTurnSpeed` (default 100). `Input.AimBand` (5–40, default 20)
-  widens the usable stick range past the aim gate — raise it if aim feels
-  capped/notchy at the extremes.
-- [ ] Check the D166 hipfire pitch (mouse up/down without RMB): still
-      proportional taps, consistent with the yaw. Tune
-      `Input.HipfirePitchSpeed` (default 100).
-
-## 3. Menu pointer 1:1 — needs `Input.MouseCaptureMode = 1`
-
-- [ ] On the mission-select grid, move the OS cursor to each of the four
-      **corner** level tiles — the game crosshair must reach all of them
-      (this is the D169 case; absolute mapping should make it exact now).
-- [ ] File-select, mode-select, difficulty-select, watch menu — crosshair
-      tracks the OS cursor with no drift, no lag, no acceleration.
-- [ ] Keyboard nav (arrows / stick) still works on every screen.
-- **Correct feel:** the crosshair sits exactly under the OS pointer, like a
-  normal PC menu.
-- **Tune:** `Input.MenuPointerSpeed` (default 100) still scales the legacy
-  relative path; with capture mode the absolute path ignores it. If tracking
-  feels off, check the window isn't a weird aspect ratio (the map assumes the
-  render fills the window).
-- **Note:** in legacy mode (`MouseCaptureMode = 0`) the menu still uses the
-  D165/D169 relative estimator — 1:1 menu tracking requires capture mode.
-
-## 4. Screen shake — `Game.ScreenShakeIntensity`
-
-- [ ] Default `1` — explosions shake the screen exactly as before.
-- [ ] Set `0` — no shake on explosions / big hits.
-- [ ] Set `2`–`3` — exaggerated.
-- **Correct:** `1` is indistinguishable from the current build.
-
----
-
-## Single most important thing to test first
-
-**Item 0** — confirm a default `ge007.ini` produces a build that plays
-identically to `def0e0ac`. If that holds, everything else is opt-in polish.
-
-## Known not-done (parked, see OPTIONS-MENU-PLAN.md)
-
-- No in-game options **menu** yet — only the config file + the expanded
-  `config.c` API and the `Game.ScreenShakeIntensity` hook. The menu is a
-  port-layer overlay design, documented, not built.

docs/dev/M-35-QOL-REVIEW.md

@@ -1,132 +0,0 @@
-# M-35 — Native-PC input + options-menu QoL review
-
-Branch: `qol/native-pc-input-menu` (cut from `def0e0ac`). Port-layer only
-except one documented route-(b) `#ifdef PORT` line in `src/fr.c` (D181).
-Every new behaviour is config-gated with the default reproducing prior
-behaviour; `tools_pc/golden/` headless captures are unaffected at defaults
-(no mouse in a headless run; `Game.ScreenShakeIntensity` default 1.0 is a
-no-op multiply).
-
-Findings: **D180** (input pass), **D181** (screen-shake hook). See
-`docs/dev/findings.md` §F.
-
----
-
-## WI-1 — In-game mouse: Quake-style click-to-lock
-
-**Status: landed, feel-check owed.**
-
-### What changed
-
-| File:area | Change |
-|---|---|
-| `port/src/input.c` — new statics `mouseCaptureMode` / `captureArmed` / `windowFocused` | Capture-mode state. `mouseCaptureMode` registered as `Input.MouseCaptureMode` (0/1, **default 0**). |
-| `port/src/input.c` `inputInit` | In capture mode, start **un**grabbed (`SDL_SetRelativeMouseMode(FALSE)`), wait for a click. Legacy mode unchanged (grab on start). |
-| `port/src/input.c` `applyGrab()` / `reconcileGrab(menuMode)` | `applyGrab` is the old `inputSetMouseGrab` body (SDL relative-mode toggle + delta drain). `reconcileGrab` computes the wanted grab state: legacy → `windowFocused`; capture → `captureArmed && windowFocused && !menuMode`. Called once per controller-0 poll and from every notify hook. |
-| `port/src/input.c` `inputSetMouseGrab(on)` | Now just records `windowFocused` and calls `reconcileGrab` — so focus loss/gain works in both modes without special-casing. |
-| `port/src/input.c` `inputNotifyClick()` | Capture mode + focused → `captureArmed = 1` + regrab. No-op otherwise (game sees the click). |
-| `port/src/input.c` `inputReleaseCapture()` | Capture mode + grabbed → `captureArmed = 0`, release, return 1 (caller swallows the key). Returns 0 otherwise (ESC falls through to the N64 B button, D145). |
-| `port/src/input.c` `inputComputePad` idx 0 | Calls `reconcileGrab(menuMode)`; when capture-mode + free + in a stage, zeroes the local `mb` so mouse buttons never reach the game (no phantom fire from the re-lock click). |
-| `port/src/video.c` event pump | `SDL_MOUSEBUTTONDOWN` → `inputNotifyClick()`. `SDLK_ESCAPE` keydown → `inputReleaseCapture()` (before the existing fall-through). |
-| `port/include/input.h` | Prototypes for the three new hooks. |
-
-### Config keys
-
-| Key | Range | Default | Effect |
-|---|---|---|---|
-| `Input.MouseCaptureMode` | 0–1 | **0** | 0 = legacy (cursor grabbed whenever the window is focused). 1 = click-to-lock: free cursor until you click the window; ESC / focus-loss / opening a menu frees it; entering a stage while "armed" re-locks. |
-| `Input.MouseAimSpeed` | 1–500 | **16** (was 25) | Aim-mode (RMB / LShift) sensitivity %. B3: still overshot at 25. |
-
-Controller input is completely independent of all of the above — the pad
-branch in `inputComputePad` is untouched, and `reconcileGrab` only ever
-toggles `SDL_SetRelativeMouseMode`.
-
-### D166 / hipfire-pitch interaction
-
-The D166 hipfire pitch pulse is unchanged. It only runs when the cursor is
-grabbed (mouse deltas are zero while free), so click-to-lock does not
-perturb it. The M-24 aim-band (`61 + gain` into the `60 + aimBand` ceiling)
-is unchanged; only the `mouseAimSpeed` scalar feeding `gx`/`gy` moved.
-
-### Owed feel-checks (playtest checklist items 1–4)
-
-Headless runs cannot move the mouse, so the capture ergonomics, the new
-`MouseAimSpeed = 16` default, and the D166 pulse consistency under the new
-model are all inferred, not observed.
-
----
-
-## WI-2 — Menu pointer: absolute cursor tracking
-
-**Status: landed for capture mode, feel-check owed. Route (a), port-only.**
-
-### What changed
-
-`port/src/input.c`, the `menuMode` pointer branch (the D165/D169
-P-controller). Added an **absolute-position** target source: when
-`mouseCaptureMode && !mouseGrabbed` (i.e. a real free OS cursor over a
-front-end screen), read `SDL_GetMouseState` + `SDL_GetWindowSize` of the
-mouse-focus window, normalise to `[0,1]²`, and map straight onto the live
-virtual front-end rect (`loH..hiH × loV..hiV`, already derived from
-`getPlayer_c_screen*` for D169). That becomes `menuTgt{H,V}` directly
-(no accumulation, no drift). The P-controller/estimator below is unchanged
-and simply chases the target, so the game's `cursor_h_pos/v_pos` lands
-exactly where the OS pointer is.
-
-The relative-delta path (legacy `MenuPointerMode`, or capture mode while
-grabbed) is **unchanged** — `haveAbs` gates only the new assignment.
-
-### Why this is enough for 1:1
-
-The D169 fix already made the clamp rect track the real 440×330 field. The
-only thing missing for true 1:1 was a non-drifting target: a free OS cursor
-*is* an absolute device, so mapping its window fraction onto the rect is
-exact. No route-(b) hook needed.
-
-### Keyboard nav parity
-
-Untouched — the menu branch only ever adds to `sx/sy`; D-pad / stick keys
-still feed the same axes. The D118d `front.c` latent sibling was **not**
-touched (no evidence the absolute path exposes it; the stick values emitted
-are small P-controller corrections, never a slammed ±80).
-
-### Caveat
-
-Absolute tracking is only wired for `MouseCaptureMode = 1`. In legacy mode
-(default) the menu still uses the D165/D169 relative estimator. If
-click-to-lock becomes the default later, WI-2 is 1:1 for free; until then
-menu 1:1 requires `Input.MouseCaptureMode = 1`.
-
----
-
-## WI-3 — In-game video/options menu
-
-**Status: config-system foundation landed; menu surface = design doc only.**
-See `docs/dev/OPTIONS-MENU-PLAN.md`.
-
-### Landed
-
-- `configRegisterFloat` / `configRegisterUInt` + clamps (`port/src/config.c`,
-  `port/include/config.h`). `configSave` rewritten to emit all four option
-  kinds section-grouped in one pass.
-- `Game.ScreenShakeIntensity` (0.0–10.0, default 1.0) — the first
-  route-(b) hook, D181, proving the pattern the menu will lean on.
-
-### Not landed (budget) — precise resume point in the design doc
-
-- The menu tables / handlers themselves. GE's menu system (`front.c` /
-  `initmenus.c` / `mainmenu.c`) differs enough from PD's `optionsmenu.c`
-  that it is an adaptation, not a copy. Design doc covers the entry point,
-  the handler shape, and the minimum option set.
-
----
-
-## Verification evidence
-
-| Check | Result |
-|---|---|
-| `./build-pc.sh ntsc-final` | green, 241/241 |
-| `-level_09` framediff (200/320/440) | 3/3 within threshold; nonclear Δ 0.00–0.01pp (91.6%); phash 0/1/5 = documented D117 intro-pan noise |
-| `GE_STARTMENU=7` boot | crash-free, no `ge007.crash.log` |
-| golden dumps at defaults | unaffected (no headless mouse; shake scale 1.0 = no-op) |
-| linkcheck | see PR body |

docs/dev/M-36-TRIAGE.md

@@ -1,94 +0,0 @@
-# M-36 — graphics / QA bug triage sweep
-
-Branch `qol/native-pc-input-menu` (local). Goal: sort the open
-`GRAPHICS-BACKLOG.md` + QA-report bugs into **root-cause families** so a
-fix hits several at once, and correct one mis-attribution.
-
-Method: headless `GE_PCDUMP` captures (`-level_36` Surface, `GE_STARTMENU=10`
-briefing) + static read of the implicated port code. Frames in
-`scratchpad/` this session; not committed (auto window size = 1957×1468,
-can't framediff — visual only).
-
----
-
-## Headline findings
-
-### 1. The "comb interlacing" is NOT the D159 family
-
-`GRAPHICS-BACKLOG.md` attributes D176(b) and D182(2) to `texSwapAltRowBytes`
-"recurring on re-import". **That function is a full `#ifdef PORT` no-op** —
-`src/game/image.c:2199` `return;` before any work. It cannot be the cause of
-anything. The mis-attribution is now corrected in the backlog.
-
-The real defect: `port/fast3d/gfx_pc.cpp` `import_texture_*` assume
-`full_image_line_size_bytes == line_size_bytes` (explicit `SUPPORT_CHECK`
-on rgba32/ia4/ia8/ia16/…; the rgba16 one is commented out with
-*"this trips in some places with a garbage size in
-full_image_line_size_bytes"*, `gfx_pc.cpp:658`). When a tile's `line`
-(SETTILE pitch) differs from the source image row width — non-power-of-two
-textures, or a sub-rect tile load — the importer does a flat linear read and
-every row walks off by a few bytes → **diagonal shear that reads as grey
-static**. Matches the Surface cliff/tree walls (`-level_36` frame 300–900:
-structured rock texture tiling but each tile sheared to noise) and the
-file-select spiral after re-entry.
-
-Open question: why does D182 only scramble **after** navigating away and
-back? Either the first import happens to have `line == width` and the
-re-import doesn't, or the tile descriptor is stale on the second visit.
-
-### 2. Briefing objectives are BLANK, not wrong
-
-`GE_STARTMENU=10` briefing (Dam): header renders perfectly ("OHMSS / Agent:
-James Bond / Mission 1: Arkangelsk / Part i: Dam / PRIMARY OBJECTIVES:").
-Under it: just the bullet letter **"a."** with **no objective text**, and no
-b/c/d lines. So D178 is the **D143/D151 blank-text family** (`langGet()`
-returns NULL for the objective string slot → text silently blank), *not* a
-propDef walk-desync or difficulty-decode problem. Fix = find which lang bank
-the front-end briefing flow fails to load/map.
-
-Caveat: this repro used the synthetic `GE_STARTMENU` boot (skips real
-save/unlock state). The user's D178 report is from a live playthrough, and
-D143 independently documents blank briefing text, so it is a real defect —
-but re-confirm the exact "a." + blank shape in a real briefing.
-
----
-
-## Family table
-
-| Family | Bugs | Root cause (hypothesis) | Files | ROI |
-|---|---|---|---|---|
-| **A — fast3d texture line/pitch shear** | D176(b) Surface walls; D182(2) file-select bg | **HYPOTHESIS DISPROVEN (D183, `4b71435d`).** 0/166 texture loads on `-level_36` are strided; the wall texture is a 32×32 IA8 whose ROM bytes are genuinely a noise field, decoded correctly. A golden-safe de-stride + `GE_TEXRAW`/`GE_DTEX` diagnostics landed anyway (latent hardening). **D176(b)/D182(2) still OPEN** — next: ROM ground-truth decode of the wall texnum (`TEXTURE-GLITCH-ANALYSIS.md` §7) → likely a tiling-density / UV-scale / `shifts`/`shiftt`-LOD issue (RC3/D167 family) or a wrong-texture bind, not a decode bug. | `port/fast3d/gfx_pc.cpp` | was HIGH, **now needs re-scoping** |
-| **B — front-end string bank not loaded** | D178 briefing objectives blank; D143 briefing text blank | **FIXED (D178, `cd1ed574`).** Not a bank-load problem — the `Ubrief*Z` segment is a raw 48-byte BE ROM image loaded with no converter; all 24 `u16` (string ids + difficulty gates) read byte-swapped on LE → `langGet()` NULL → blank, and `>=` difficulty gate always-false → objectives vanish. `romdataFixupBriefing()` swaps in place. Verified: all 4 Dam objectives render at 00 Agent with correct gating. **D143 was a symptom of this** — annotate it superseded. D151 (watch objective text) still owed a re-verify. | `port/src/romdata.c`, `src/game/front.c` (`#ifdef PORT`) | **DONE** |
-| **C — D75 front-end / cutscene 3D models** | D75 Nintendo logo; D148 Dam rappel cutscene; D149 MISSION COMPLETE / mode-select models; D182(1) file-select Bond image "renders once"; D173 3rd-person Bond floats; 1P weapon viewmodel absent | mixed: compiled sub-DL corruption (D144/D146), model transform/geometry, `render_pos` arena lifetime, constructor-runs-once | `port/fast3d/gfx_pc.cpp`, `title.c`, `bondview*.c`, model path | **LOW** per fix, deep. **DEFER** (agreed COA). |
-| **D — blood / particle** | D172 spray magenta/cyan; D174 no blood decals | D172: CC-mode / texture-format decode in the fast3d sprite path. D174: likely D120 `PointUsage[]` — **only takes effect after a full sidecar regen** (`d43 && d69 && d88 --regen`); verify that first. | `blood_animation.c`, fast3d sprite path; `tools_pc/d43_emit.py` | **MEDIUM**. D174 may already be fixed — regen + BUNKER1 firefight to confirm before touching code. |
-| **E — transient hang / anim speed / clip** | D175 door-open stutter (Runway/Surface); D170 NPC flee runs not walks; D171 Silo grey-triangle sweep | D175: matches D155/D156/D134/D147 known classes (benign texture-import spike most likely). D170: D155/D156 wall-clock `deltaFrames` anim speed-up, or just scripted. D171: near-plane clip fan (D106 family). | frametiming clamp, `chrTick`/AI, portal near-plane | **LOW–MED** — needs interactive repro + N64 reference footage. **DEFER**. |
-| **F — misc cosmetic** | D74 dead wrap-block (latent, harmless); D76 disclaimer partial (D164 fix owed an eyeball); D77 audio (Phase 3); **D176(a) black sky** | D176(a): sky DL not emitting / wrong transform — **separate from D176(b)**, own investigation (could be C-family or a sky-pass issue). | various | **LOW**, opportunistic. |
-
----
-
-## Results (2 subagents, integrated + verified on branch HEAD)
-
-- **Family B → FIXED** (`cd1ed574`). Byte-swapped raw briefing segment. Also
-  explains D143. High confidence.
-- **Family A → hypothesis disproven** (`4b71435d`, D183). D176(b) is not a
-  texture decode bug. Golden-safe de-stride + diagnostics shipped for the
-  latent case. **D176(b) / D182(2) remain open and need re-scoping** — start
-  from the ROM ground-truth decode of the wall texnum; suspect
-  tiling-density / UV / per-LOD `shifts`/`shiftt` (RC3/D167 family) or a
-  wrong-texture bind.
-
-Harness note: both agent worktrees were created from `def0e0ac` (the M-35
-branch point, ~5 commits stale — the M-31 stale-worktree bug again). No harm
-this round: the integrator re-applied both patches onto branch HEAD and
-verified there. Check `git worktree list` HEADs on the next burst.
-
-## Next
-
-1. **D176(b) re-scope** — offline decode the Surface wall texnum from ROM
-   (`TEXTURE-GLITCH-ANALYSIS.md` §7). Structured rock in ROM → wrong bind or
-   UV/tiling; noise in ROM → not our bug (or a shift-LOD density issue).
-2. **D176(a)** black sky — untouched, separate investigation.
-3. **D182** — re-test the file-select round-trip now that `GE_TEXPITCH` /
-   `GE_TEXRAW` exist; the "renders once" half (D182-1) is Family C.
-4. Reassess C/D/E with the user. D174 (blood) is the cheapest — just needs a
-   sidecar regen + BUNKER1 firefight to confirm the D120 fix.

docs/dev/M7-ALLUNLOCKED-PLAN.md

@@ -1,45 +0,0 @@
-# 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/RELEASE-GATE.md

@@ -0,0 +1,21 @@
+# Release gate driver
+
+`tools_pc/release_gate.sh` runs the automatable pre-release checks and prints one
+PASS / FAIL / SKIPPED table. It wraps `verify.sh` (pixel gate) and `levelbench.sh`
+(scripted run, clean-quit and crash-log detection); every run ends through
+`GE_QUITFRAME`, nothing is hard-killed.
+
+```sh
+tools_pc/release_gate.sh --dry-run all       # print what would run
+tools_pc/release_gate.sh win                 # sweep vs win goldens + fire smoke + exit path
+tools_pc/release_gate.sh deck <host>         # 21 levels via deckrunner (shortcut must be up)
+GE_MAC_DIR=<remote game dir> tools_pc/release_gate.sh mac <host>
+```
+
+Options: `--secs N` (per-level run length, default 30), `--out DIR`. Hosts and
+paths come only from arguments or env (`GE_WIN_DIR`, `GE_DECK_HOST`,
+`GE_MAC_HOST`, `GE_MAC_DIR`, `GE_MAC_EXE`, `GE_MAC_BUILD_CMD`,
+`GE_GATE_SSH_OPTS`). The Deck pixel compare is reported SKIPPED (640x480
+goldens vs 1280x800 dumps); Mac has no goldens, so it is crash-free only. The
+fire smoke is `GE_INPUTSCRIPT` `MLB1`/`MLB0` (D597, the D595 regression).
+Remote job, result and script files are deleted after the summaries are pulled.

docs/dev/TEXTURE-GLITCH-ANALYSIS.md

@@ -1,5 +1,7 @@
 # Texture Glitch Analysis — PC Port
 
+> **Historical record — do not act on status claims in this file.** Only the status table is current; the diagnosis from §1 onward is from 2026-08-29 and includes retracted fixes (RC4) — never apply them. Current open work and status: [`docs/ROADMAP.md`](../ROADMAP.md) (2026-09-29).
+
 **Original diagnosis:** 2026-08-29 (read-only) · **Status table refreshed:** 2026-08-31 (M-31)
 Companion artifacts: `<local-path>` (outside repo).
 

docs/dev/UNLOCKED-FPS-PLAN.md

@@ -83,40 +83,124 @@ Two useful existing properties:
 
 ### Phase 0 — Baseline & ground truth (port-only)
 
-Goal: know exactly what the default preset does before touching anything.
+**RESOLVED (2026-09-12, commit 8f2f9e1d, D248).** The ~30 fps default was
+confirmed a **port artifact**, not original N64/GE behavior: `sched.c`'s
+`__scHandleRetrace` read a per-client "every retrace vs. every other
+retrace" flag via a hardcoded `*((s32*)client + 2)` byte offset (`sched.c`
+~line 350) that only lands on the right field when `OSScClient` is 8 bytes
+(32-bit pointers, true on N64). On this 64-bit port the struct is 16 bytes,
+so the read landed inside the gfx client's own `msgQ` pointer (always
+non-NULL), silently collapsing the gfx client onto the audio client's 30Hz
+path even though the VI-retrace pacemaker itself always ticked at a correct
+60Hz. Fix (`#ifdef PORT`, `sched.c` ~line 348): index the struct
+(`client[1].next`) instead of the hand-rolled offset, so it scales with
+pointer width. Verified live via the `Video.DisplayFPS` overlay: rock-stable
+30 FPS pre-fix, 60 FPS post-fix, same build/scene. Same bug class as
+D122/D126/D132/D209 (pointer-width struct growth), just in the scheduler.
 
-- [ ] Measure actual sim rate and present rate of the current default build
-      (speedgraph + a `video.c` counter; add a periodic log line
-      `sim=..Hz render=..Hz`). Confirm NTSC vs PAL build.
-- [ ] Find why the default is ~30 rather than the console's 60 Hz. Candidates:
-      - tick-thread 4 ms chunked-sleep drift under host load;
-      - `__scTaskReady` double-buffer check (`sched.c`) stalling a task every
-        other retrace;
-      - `__scHandleRetrace`'s client flag read `*((s32*)client + 2)` is
-        **out-of-bounds of `OSScClient`** (struct is only `next`+`msgQ`; the
-        decomp even says "im wrong size"). For `gfxClient[0]` it happens to
-        read `gfxClient[1].next` (zero) — but this is layout luck, worth a
-        documented finding either way.
-- [ ] Record a Dxxx finding with the measured rates and root cause.
-- [ ] **Decision gate:** if 30 fps turns out to be a port artifact rather than
-      original behavior, document it and decide with data whether the default
-      preset keeps the current pace (test continuity) or is fixed. Default
-      assumption: keep current behavior as the "original" preset either way;
-      a fix becomes its own item.
+**Decision-gate answer:** the default preset is now the console's real
+60Hz(NTSC)/50Hz(PAL) rate — decision #1 above ("default preset = the
+original pace") is satisfied by this fix, not by preserving the halved
+30fps. All prior playtest/determinism baselines predate this fix and should
+be treated as pre-D248.
+
+- [x] Find why the default was ~30 rather than the console's 60 Hz — root
+      cause above; §F **D248**.
+- [x] Record a Dxxx finding with the measured rates and root cause — D248.
+- [ ] Measure actual sim rate and present rate with a dedicated periodic log
+      line (`sim=..Hz render=..Hz`) rather than the one-off `DisplayFPS`
+      overlay reading used to verify D248. Not yet built — still open if a
+      standing measurement (vs. a spot-check) is wanted before Phase 1/2
+      work lands.
+- [x] **Decision gate** — resolved above.
 
 ### Phase 1 — PD-style pacing hardening (port-only)
 
 Makes the default preset stable and drift-free; no game-code changes.
 
-- [ ] Replace the free-running tick grid in `portTickThread` with a
-      wall-clock accumulator + remainder carry (PD `frametimeCalculate` math):
-      post ticks when real time says they're due, carry the remainder, bounded
-      catch-up after hitches (D155 philosophy). No drift under load, no burst
-      of back-to-back ticks.
-- [ ] `video.c`: proper frame limiter for fractional caps (spin+sleep hybrid),
-      triple-buffered swap chain, and the PD safety rule (vsync off + no cap →
-      force a max cap so "unlocked" can't spin).
-- [ ] Config: keep `Video.VSync` / `Video.FpsCap`; add whatever Phase 2 needs.
+**Audit (2026-09-12, post-D248):** more of this than the plan assumed
+already exists. Verified by reading the code directly (not just the
+delegate's first pass, which mis-read one of these — see below):
+
+- [x] **Accumulator + remainder carry, tick thread.** `portTickThread`
+      (`port/src/libultra.c` ~294-313) already schedules off `g_nextTickUs +=
+      g_tickIntervalUs` — the *scheduled* time, not `now` — so it doesn't
+      drift under load. It resyncs to `now + interval` only when a tick is
+      already overdue (`g_nextTickUs <= now`), which is a bounded-catch-up
+      behavior, not a naive reset. This already matches the PD
+      `frametimeCalculate` accumulator pattern.
+- [x] **Accumulator + remainder carry, present-side limiter.**
+      `sync_framerate_with_timer` (`port/fast3d/gfx_sdl2.cpp` ~403-428) uses
+      the same shape: `next = previous_time + interval` (schedule-based, not
+      wall-clock-based), a sleep-then-busy-wait hybrid to hit the deadline
+      precisely, and only snaps `previous_time` to the real wake time `t`
+      when the overshoot exceeds ~1ms (`t - next < 10000` in its 100ns units)
+      — i.e. it already carries the remainder in the normal case and only
+      gives it up after a real hitch. (An earlier audit pass mis-read this as
+      "no remainder carry, resets every frame" — it does not; re-verified by
+      reading `gfx_sdl2.cpp:403-428` directly.)
+- [ ] **Triple-buffered swap chain.** Not present — presentation uses a
+      standard SDL/GL double-buffer swap (`SDL_GL_SwapWindow`,
+      `gfx_sdl_swap_buffers_begin`, `gfx_sdl2.cpp` ~436-444). Not started.
+- [ ] **PD safety rule (vsync off + no cap → force a max cap).** Not present.
+      The only existing floor/ceiling logic is the D186 guard in
+      `gfx_sdl_set_target_fps` / `video.c` (~289-292, ~464-467), which goes
+      the *other* direction — it refuses caps below 30 (because pacing still
+      runs inline on the sim thread, see Phase 2 note below) — there is no
+      "vsync off AND cap==0" case that forces a ceiling. Not started.
+- [x] Config: `Video.VSync` / `Video.FpsCap` already registered
+      (`video.c:106-107`) and live-reapplied (`video.c` ~340-349).
+
+**Net:** the hard part of Phase 1 (drift-free accumulator scheduling) is
+already done, on both the sim-tick and present-side clocks. What's left is
+narrow: a safety-cap rule and, if wanted, triple buffering — plus whatever
+Phase 2 needs on top.
+
+**Phase 2 first slice, scoped (2026-09-12).** The real gap for a 120fps
+*presentation* preset isn't pacing math — it's that `gfx_run()`
+(`gfx_pc.cpp:3179-3232`) composites straight into the default framebuffer
+(fb 0) once per sim tick and then calls `gfx_wapi->swap_buffers_begin()`
+once; there's no mechanism to show that same completed frame again on an
+extra vsync between sim ticks. The existing `GfxRenderingAPI` already has
+everything needed to do this **without any new GL primitives or a second
+thread/context**:
+- `copy_framebuffer(fb_dst, fb_src, left, top, flip_y, use_back)`
+  (`gfx_opengl.cpp:1270`) already blits the real window backbuffer
+  (`fb_src == 0` + `use_back = true` reads `GL_BACK`, confirmed
+  `gfx_opengl.cpp:1309-1311`) into an arbitrary allocated FBO/texture, and
+  can blit back the other way (`fb_dst == 0` writes straight into the real
+  default framebuffer, `gfx_opengl.cpp:1214`'s `fb_id == 0 -> bind 0`
+  convention).
+- `gfx_pc.cpp` already keeps a couple of always-allocated internal
+  framebuffers this same way (`game_framebuffer`,
+  `game_framebuffer_msaa_resolved`, created at `gfx_pc.cpp:3069-3070`) — a
+  new "last presented frame" capture FBO is the same pattern, one more
+  entry.
+- The tick clock (`portTickThread`) runs on its own pthread, independent of
+  the render/sim thread that calls `gfx_run`/`swap_buffers_begin` — so
+  spending extra wall-clock time *inside* `swap_buffers_begin` presenting a
+  duplicate frame does not touch the tick schedule at all; it only changes
+  how much idle time the render thread burns before the next tick message
+  is waiting for it. Sim rate stays exactly invariant by construction, per
+  decision #3.
+
+**Smallest concrete slice:** capture the just-finished frame into a new
+internal FBO right before the real `swap_buffers_begin()` call
+(`gfx_pc.cpp:3230-3231`, via `gfx_rapi->copy_framebuffer(captureFb, 0, -1,
+-1, false, true)`); when an experimental `Video.PresentRate` config knob
+requests double-rate (2x — e.g. 120 from a 60Hz NTSC sim, 100 from 50Hz
+PAL), have `gfx_sdl_swap_buffers_begin` (`gfx_sdl2.cpp`) do the normal swap,
+then — using the same schedule-accumulator shape as
+`sync_framerate_with_timer` — sleep to the halfway point of the tick
+interval, blit the capture FBO back into fb 0
+(`gfx_rapi->copy_framebuffer(0, captureFb, -1, -1, false, false)`), and
+`SDL_GL_SwapWindow` again. Default (`Video.PresentRate = 0`) must take none
+of these code paths, so the default preset stays byte-identical to today.
+Restrict the first slice to exactly {0 = off, 2 = double}; don't generalize
+to arbitrary/uncapped multipliers yet — that needs the vsync-off safety cap
+from the Phase 1 list above first. No options-menu UI in this slice
+(config-file-only); that's a fast follow once the mechanism is playtest-
+verified not to tear/stutter.
 
 ### Phase 2 — Experimental presentation rates (port-only)
 

docs/dev/V0.4.0-PLAN.md

@@ -1,515 +0,0 @@
-# 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/VIEWMODEL-RESEARCH.md

@@ -8,7 +8,7 @@
 > `#ifdef PORT` in `src/game/gunfire.c`. See findings.md D215. This doc is kept
 > for the ruled-out analysis only.
 
-Companion to `GRAPHICS-BACKLOG.md` ("1P weapon viewmodel") and findings D115
+Companion to the (since retired) `GRAPHICS-BACKLOG.md` ("1P weapon viewmodel") and findings D115
 item #5 / AUDIT-M6 #5. Goal: narrow the five audit suspects to a ranked,
 probe-ready list. No code changed by this doc.
 

docs/dev/agentic-development.md

@@ -12,8 +12,8 @@ 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.*
+> v0.4.0 (28 Sep) extended the timeline with the options/input work — the
+> README's "How it was made" section carries the final project numbers.*
 
 ## Contents
 
@@ -50,7 +50,7 @@ and forth** through shared written artifacts, directed by one human.
 
 | | |
 |---|---|
-| Local agent | `unsloth/Qwen3.8-27B-GGUF:UD-Q4_K_XL` on a single **NVIDIA RTX 5090**, driven mainly through the **[pi](https://pi.dev/)** coding agent. Unsloth Desktop (Unsloth's local model runtime, which can drive agents such as Claude Code) was also trialed but not used significantly. |
+| Local agent | `unsloth/Qwen3.8-27B-GGUF:UD-Q4_K_XL` on a single **NVIDIA RTX 5090**, driven mainly through the **[pi](https://github.com/earendil-works/pi)** coding agent. Unsloth Desktop (Unsloth's local model runtime, which can drive agents such as Claude Code) was also trialed but not used significantly. |
 | Hosted agent | **Claude**, via **Claude Code**, on a Claude Pro subscription; mostly **Sonnet 5**, with **Opus 5** used as an escalation tier for the hardest problems and whenever there was subscription budget to spend on it |
 | Human | one person: direction, work partitioning, integration, and every build / playtest / frame-capture the agents could not run |
 | Base | fork of the [GoldenEye 007 decompilation](https://github.com/n64decomp/007) (years of prior work by Larry Ficken ("kholdfuzion") and contributors) |
@@ -59,58 +59,32 @@ and forth** through shared written artifacts, directed by one human.
 The port is the GoldenEye-specific porting work **on top of** those two
 existing bodies of work; it is not a from-scratch reimplementation of either.
 
-In practice the models formed a **three-tier escalation**: the local model
-handled well-scoped work, Sonnet 5 took what it stalled on, and Opus 5 was
-reserved for the bugs that needed the most reasoning held at once; the same
-"escalate when stuck" move applied at every level.
+In practice the models formed a **three-tier escalation** — the local model
+handled well-scoped work, Sonnet 5 took what it stalled on, and Opus 5 the
+rest; the same "escalate when stuck" move applied at every level.
 
 ## Timeline
 
 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 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
-    Boot to window (ROM map + SDL2)       :m3, 2026-08-20, 1d
-    OS shims, threads, fast3d integration :2026-08-21, 2d
-    First rendered frames                 :m4, 2026-08-22, 1d
-    Offline asset-conversion pipeline     :2026-08-22, 2d
-    Entire intro renders (logos to cast)  :m5, 2026-08-24, 1d
-    section Both agents - handoff workflow
-    Claude joins                          :milestone, 2026-08-27, 0d
-    Stage load; Bunker 1 renders + firefight :2026-08-27, 2d
-    21 solo levels load + render + no-crash  :m6, 2026-08-29, 1d
-    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
+```text
+# phase timeline (from the port's own commit dates)
+Aug 16  day 0   fork + PC-port scaffolding
+Aug 20  day 4   full compile + link (~230 TUs); boot to window
+Aug 22  day 6   first rendered frames; offline asset-conversion pipeline
+Aug 24  day 8   entire intro renders (logos -> gun-barrel -> cast)
+Aug 27  day 11  Claude joins (handoff workflow begins)
+Aug 29  day 13  21 solo levels load + render + unattended no-crash; SDL input layer
+Aug 30  day 14  front-end flow (menu -> briefing -> start)
+Aug 31  day 14  file-backed EEPROM saves
+Sep 02        audio mixer (music + SFX)
+Sep 14        Steam Deck hardening + F10 overlay QoL
+Sep 18        final fix sweep (D309-D321) + release review
+Sep 20  day 35  v0.3.0 released: full campaign at Agent difficulty, audio
+                complete, bundles for Windows, Linux and Steam Deck
 ```
 
-- **Day 0** (16 Aug): repository forked, PC-port scaffolding added.
-- **Day 4** (20 Aug): the entire ~230-TU game + libultra set compiles and
-  links as a host binary.
-- **Day 6** (22 Aug): first real frames render.
-- **Day 8** (24 Aug): the whole intro sequence renders; logos, gun-barrel,
-  cast roll.
-- **Day 11** (27 Aug): second agent joins.
-- **Day 13** (29 Aug): **all 21 solo missions load, render, and survive an
-  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
+Roughly **two weeks**, one person part-time, took the decompilation from
 "builds an N64 ROM" to "boots on desktop, renders every solo level, playable
 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
@@ -134,12 +108,15 @@ issues documented rather than outstanding.
 
 ### Commit velocity
 
-```mermaid
-xychart-beta
-    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]
+```text
+# commits per week (week start)
+8/16  ## 20
+8/23  ########### 109
+8/30  #################### 203
+9/6   ############## 141
+9/13  ###################### 220
+9/20  # 6   (release day only)
+      (each # ~ 10 commits)
 ```
 
 Weekly totals (the final week is release day only). The step up from the
@@ -150,10 +127,11 @@ at once.
 
 ### Who did what
 
-```mermaid
-pie showData title "Commits by agent (raw count, snapshot through early September)"
-    "Claude" : 161
-    "Local model (Qwen 3.8 / pi)" : 62
+```text
+# commits by agent (raw count, snapshot through early September)
+Claude                    ################  161   (72%)
+Local model (Qwen 3.8/pi) ######            62   (28%)
+                          (each # ~ 10 commits)
 ```
 
 (Phase A, the first 26 commits, to 24 Aug, was entirely the local model,
@@ -184,10 +162,11 @@ chain in relatively few, large commits, and the local model kept contributing
 raw commits; the foundation is a heavier third of the project than its commit
 share suggests; the developer's estimate is roughly:
 
-```mermaid
-pie showData title "Agent effort, milestone-weighted"
-    "Claude" : 60
-    "Local model (Qwen 3.8 / pi)" : 40
+```text
+# agent effort, milestone-weighted
+Claude                    ############  60%
+Local model (Qwen 3.8/pi) ########      40%
+                          (each # ~ 5%)
 ```
 
 The local model's ~40% is front-loaded and foundational (the build, the boot
@@ -201,21 +180,19 @@ result worth taking away.
 
 This is the part worth paying attention to.
 
-```mermaid
-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"]
-    D[(Shared artifacts:<br/>HANDOFF.md · findings.md · porting-notes.md)]
+```text
+# the handoff workflow
 
-    H -->|scopes task, budget, files| C
-    H -->|scopes task, budget, files| Q
-    C <-->|reads / appends| D
-    Q <-->|reads / appends| D
-    C -.->|usage limit reached| Q
-    Q -.->|hard structural bug| C
-    C -->|patch + write-up| H
-    Q -->|patch + write-up| H
+    HUMAN
+    direction, integration, build + playtest verification
+      | scopes task, budget, files    | scopes task, budget, files
+      v                               v
+  CLAUDE (hosted)             QWEN 3.8 / pi (local, RTX 5090)
+      | patch + write-up                | patch + write-up
+      +--------------+   +--------------+
+                     v   v
+      SHARED ARTIFACTS (both agents read + append)
+      HANDOFF.md  .  findings.md  .  porting-notes.md
 ```
 
 Both agents worked against the **same three written artifacts**, which is what
@@ -255,8 +232,7 @@ Honest notes, for anyone weighing whether this transfers.
 
 - The **local model carried the groundwork phase**; build system, boot
   chain, OS shims, and the offline-converter architecture. None of it was
-  rewritten later. A 27B open model on one consumer GPU was genuinely productive
-  on this.
+  rewritten later.
 - **The written-artifact discipline made agent output compound.** An agent
   starting cold late in the project was more effective than one early on,
   because the accumulated notes were good. This is also what made the two
@@ -283,8 +259,49 @@ 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** (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).
+**Still outstanding:** see
+[`docs/ROADMAP.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/ROADMAP.md),
+the single tracker for open work.
+
+## Since the two-agent phase
+
+The two-agent setup above is the **initial phase**, snapshotted at v0.3.0
+(the project has since shipped v0.4.x and is heading to v0.5.0; the model
+and harness record below is current through that point).
+
+Since then the emphasis has shifted from "the two models that built it" to
+**testing a lot of new models and harnesses**, to find what's fastest and
+cheapest per task. The long-time local workhorse stayed **Unsloth's Qwen 3.8 27B**;
+in the final week that broadened into a menu, and the **current standard is
+NInfer + Strata**. On the hosted side, the Claude orchestrator stepped up from
+**Sonnet 5 / Opus 5** to the **5.5 tier** (Sonnet 5.5 / Opus 5.5, out in the
+last few weeks), which has driven the most recent work. The local menu:
+
+- **Qwen 3.8 27B** ([Unsloth](https://huggingface.co/unsloth/Qwen3.8-27B-GGUF),
+  `UD-Q4_K_XL`) — the primary local workhorse for most of the port's life, doing
+  nearly all of the local groundwork on its own. A larger-context
+  [`ISTA-DASLab/Qwen3.8-27B-GSQ-RCO-GGUF`](https://huggingface.co/ISTA-DASLab/Qwen3.8-27B-GSQ-RCO-GGUF)
+  (`IQ3_S`) was also briefly trialed for bigger-context workloads, then shelved
+  (little use since v0.2.0).
+- **NInfer (Windows)**
+  ([natpate/ninfer-windows](https://github.com/natpate/ninfer-windows), v0.9.0,
+  CUDA 13.1 — a standalone Windows port of the NInfer engine, with MTP /
+  DFlash2 speculative decoding) — ran **Qwen 3.8 27B** in base, NVFP4 and
+  NVFP4-full artifacts; trialed in the final week, now half of the standard
+  and the fast day-to-day local driver.
+- **Qwen 3.8 Flash-Next** via
+  [Strata](https://github.com/Niko1221/Strata) (Niko1221's MIT-licensed
+  C++/CUDA/HIP engine) — a 125B mixture-of-experts model that normally needs a
+  server, run **locally on a single gaming GPU** (IQ1_M, 1-bit) for the
+  biggest-context coding passes. The other half of the standard.
+- **[claude-code-delegate-local](https://github.com/fegone/claude-code-delegate-local)**
+  — an MCP server that let the Claude Code orchestrator and the local models
+  talk, delegating Claude's subagents to the local engines. A nice tool, but
+  **mostly deprecated now**: hand-offs between agents are done by hand for now,
+  pending a better parallel-agent handoff system that drops the MCP overhead.
+- **GPT-6 (Sol)** via [OpenRouter](https://openrouter.ai) — a frontier hosted
+  model, **trialed** to see how it held up (not the hardest-work tool).
+
+The practical effect: the project stopped depending on any one model or its
+usage limits. The local GPU is now the default path for high-volume work, with
+hosted frontier models reserved for the problems the local models can't close.

docs/dev/findings-index.csv

@@ -7,13 +7,13 @@ 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,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:
+D75,FIXED,front-end 3D model transforms (D77 audio split out below —,FIXED 2026-10-02 (branch fix/fidelity-gaps; by-eye check owed):
 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):",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:"
+D186,CLOSED,"Video.FpsCap throttles the sim, not just presentation (M-39 diag, M-42 clamp).",CLOSED (2026-09-28 bookkeeping:
 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"
@@ -31,7 +31,7 @@ D192,CLOSED,Front-end mission/level-select grid pointer still can't reach the ou
 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,PARTIAL,"QoL gap (M-87, from a PD-PC-port survey):","LANDED via D401 (2026-09-27, re-promoted from DEPRIORITIZED)."
+D224,CLOSED,"QoL gap (M-87, from a PD-PC-port survey):",CLOSED (2026-09-28 bookkeeping:
 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) —"
@@ -40,14 +40,14 @@ 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…"
+D244,OPEN,Self-hosted CI runner 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,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:
+D207,CLOSED,"Alarm klaxon starves combat SFX and doesn't recover after it stops (surfaced by D206, M-77).",CLOSED (2026-09-28 bookkeeping:
 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).…"
@@ -57,12 +57,12 @@ D168,FIXED,GE_PCDUMP / F12 PPM captures were vertically flipped —,FIXED (port/
 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,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
+D176,FIXED,"Surface exterior renders wrong (-level_36), two independent defects.",FIXED (2026-09-29 bookkeeping:
+D177,FIXED,Ladders non-functional —,"FIXED (M-36) — high confidence; interactive climb test owed Owed climb test considered cleared by the 2026-09-28 v0.4.0 campaign sign-off (ROADMAP §3 bookkeeping, 2026-10-01); reopen if seen."
 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)."
+D173,PARTIAL,Third-person Bond model spawns too high —,PARTIAL (2026-09-29 bookkeeping:
 D179,FIXED,Packaged build crashes after the logos —,"Diagnosed, not fixed —"
 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:
@@ -74,13 +74,13 @@ D214,FIXED,"Keyboard rebinding — [Input.Bind] config section (M-83, port-only,
 D215,FIXED,1P weapon viewmodel never drew in-level —,"FIXED (src/game/gunfire.c, #ifdef PORT)."
 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:
+D218,FIXED,Wide FOV exposes the per-level draw-distance / fog boundary —,FIXED (2026-09-26 reclassified; 2026-09-29 default corrected:
 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) —
+D132,CLOSED,D88 propDefs layout audit (M-20):,CLOSED (2026-09-28 bookkeeping:
 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
@@ -88,18 +88,18 @@ D93-D102,RESOLVED,struct-pun / hardcoded-size pass:,resolved (D95 pool bump part
 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 attempted, not achieved.","OPEN (mode attempted, not achieved)"
+D117,CLOSED,"Frame nondeterminism root-caused; GE_DETERM attempted, not achieved.",CLOSED (2026-09-28 bookkeeping:
 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
+D150,FIXED,watch OBJECTIVES / BRIEF page crash:,"FIXED (src/str.c #ifdef PORT); interactive re-verify pending Owed re-verify considered cleared by the 2026-09-28 v0.4.0 campaign sign-off (ROADMAP §3 bookkeeping, 2026-10-01); reopen if seen."
 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) —
+D271,CLOSED,"D236 wall, third pass —",CLOSED (2026-09-29 bookkeeping:
 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."
+D283,FIXED,"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… —","FIXED (2026-09-30, port-only) —"
 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:
@@ -123,7 +123,7 @@ D139,FIXED,Stage-unload crash root cause + fix (M-23).,"FIXED (src/game/cleanup_
 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,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).
+D154,CLOSED,"bg.c room-geometry ray/hit-test GBI parser port (M-28, WRITTEN / UNVERIFIED / UNCOMMITTED).",CLOSED (2026-09-28 bookkeeping:
 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.
@@ -145,7 +145,7 @@ D245,FIXED,IsWater water: two competing patterns with a visible seam that moves
 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 — 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:"
+D249,CLOSED,"LOD/culling breaks down on large open levels (Streets, Egyptian named specifically) at *default* FOV —",CLOSED (2026-09-28 bookkeeping:
 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,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):"
@@ -161,7 +161,7 @@ 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:
+D258,DEFERRED,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:"
@@ -172,7 +172,7 @@ D290,FIXED,"Watch's in-game ""controller"" section shows no control-pad graphic
 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:"
+D294,PARTIAL,"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… —",PARTIAL -> fix landed pending by-eye check (2026-10-03:
 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:
@@ -225,8 +225,8 @@ D344,FIXED,Host PC bugchecks (BSOD 0x119 VIDEO_SCHEDULER_INTERNAL_ERROR) during
 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.
+D348,CLOSED,"File-select ""PC Options"" label:",CLOSED (2026-09-28 bookkeeping:
+D349,CLOSED,GE watch settings ARE saved to the Bond file when the watch closes:,"SUPERSEDED (2026-10-04, P2b correction):"
 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):"
@@ -243,8 +243,8 @@ D363,FIXED,F10 return to a dark overlay with the N64 watch's green/Bank Gothic v
 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."
+D367,CLOSED,F10 full-width control boxes misaligned with their contents (2026-09-27).,CLOSED (2026-09-28 bookkeeping:
+D368,CLOSED,Simplify F10 click targets:,CLOSED (2026-09-28 bookkeeping:
 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):
@@ -253,17 +253,17 @@ D373,FIXED,"In-game crosshair on/off + colour (v0.4.0 modern options wave M2, 20
 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):
+D377,FIXED,GEPD independent crouch (2026-09-27).,FIXED (2026-09-28 bookkeeping:
+D378,FIXED,GEPD use/reload separation (2026-09-27).,FIXED (2026-09-28 bookkeeping:
+D379,FIXED,Crosshair colour: authored texture is red (2026-09-27).,FIXED (2026-09-28 bookkeeping:
 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).
+D383,CLOSED,PD-style keyboard rebinding in both options UIs (2026-09-27).,CLOSED (2026-09-28 bookkeeping:
 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):
+D387,FIXED,M7 AllUnlocked's read-time fake unlocks leak into saved EEPROM (2026-09-27).,"FIXED 2026-09-30 (port-only per-slot raw/seen merge on EEPROM write, libultra.c geD387MergeSlotWrite; isolated ON-vs-OFF byte-identity matrix passed)."
 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.
@@ -274,14 +274,222 @@ 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):"
+D398,CLOSED,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,CLOSED,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).,CLOSED (2026-09-28 bookkeeping:
+D400,CLOSED,"File-select ""PC Options"" label:",CLOSED (2026-09-28 bookkeeping:
 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)."
+D541,PARTIAL,One A press advanced two menu screens on the Steam Deck (Desktop Mode) —,"PARTIAL 2026-10-05 (mitigation landed, port-only:"
+D542,OPEN,"Stray polygons left of Bond's gun, frequent on foggy levels (Streets, Surface 2) —",OPEN 2026-10-05 (triage:
+D543,FIXED,Surface 2: lit area following Bond brighter than 1964 —,"FIXED 2026-10-06 (CPU RSP-style near clip in gfx_sp_tri1 + per-vertex fog default; build-verified, by-eye vs 1964 at next playtest)"
+D544,FIXED,OS cursor flickers with F10 open on the main menu —,"FIXED 2026-10-05 (port-only, input.c; build-verified, maintainer mouse check owed)"
+D545,FIXED,Player rockets can pass through the ground when fired near Bond's feet —,"FIXED 2026-10-06 (AVOID_UB array, gun.c; maintainer Archives preset A/B:"
+D546,FIXED,PC settings standardization:,FIXED 2026-10-05 (port-only; build + maintainer check owed; golden re-base batched with D543)
+D547,FIXED,Game.AllUnlocked applies live (no restart) —,"FIXED 2026-10-05 (port-only, main.c/optionsoverlay.c; build-verified, maintainer mission-select check owed)"
+D548,FIXED,Walls near rocket fire/explosions banded black/white/yellow/blue (Aztec dark corridor; also seen on Deck) —,FIXED 2026-10-06 (gfx_opengl.cpp input clamp; root fix = D543 CPU near clip; maintainer Aztec re-check owed)
+D549,FIXED,Thrown grenade/knife/object:,"FIXED 2026-10-06 (AVOID_UB coord3d, gun.c x3; build-verified)"
+D550,FIXED,"Static title bar (no more per-second ""NN fps"" refresh) + project mark as favicon / window / taskbar icon —","FIXED 2026-10-17 (port + tooling only, video.c/gfx_sdl2.cpp/make_icon.py; ninja-command-verified + full build 249/249; maintainer live window/taskbar check owed)"
+D551,?,"Opt-in update check (Game.CheckUpdates, default off):",ADDED 2026-10-06 (port layer only; live-verified Windows/Linux/Deck + F10 UI capture; security review fixes applied)
+D552,FIXED,Dam ending cutscene: the first camera shot no longer swivels up onto Bond —,FIXED 2026-10-06 (port-only addition removed; code path back to the decomp; maintainer-verified live)
+D553,FIXED,Surface 2: the haze around Bond brightened/darkened as he moved —,FIXED 2026-10-06 (fast3d:
+D554,OPEN,F10 settings menu: wording/casing pass + two-line tips —,DONE 2026-10-06 (port/src/optionsoverlay.c; maintainer by-eye check owed)
+D555,OPEN,Crosshair mouse pointer over the F10 / PC Options overlay —,"DONE 2026-10-06 (port/src/input.c, optionsoverlay.c, tools_pc/make_icon.py; maintainer by-eye check owed)"
+D556,OPEN,"F10 feedback pass (tips trimmed, conditional-row order, wording fixes) + mouse scrollbar —","DONE 2026-10-06 (port/src/optionsoverlay.c; build only, by-eye check owed)"
+D557,FIXED,"New/blank profiles start with Look ahead OFF on PC (Rule-2 sign-off, maintainer 2026-10-06) —",FIXED 2026-10-06 (src/game/file2.h DEFAULT_OPTIONS under #ifdef PORT; existing saves untouched; win gate 21/21)
+D558,FIXED,F10 overlay tips cut off in a level (not on the front end) —,FIXED 2026-10-06 (optionsoverlay.c textRenderWide; verified by in-level capture)
+D559,FIXED,"Look ahead off for untouched existing folders (maintainer-approved, port layer only) —",FIXED 2026-10-06 (watchsettings.c migrateUntouchedLookAhead)
+D560,FIXED,F10 copy pass 3 (maintainer line review) —,FIXED 2026-10-06 (optionsoverlay.c tips/labels/value names; display text only)
+D561,FIXED,"F10: ""Menu pointer"" row removed (front-end-only legacy option; confused players) —","FIXED 2026-10-06 (row/tip/names removed; Input.MenuPointerMode ini key, Direct default and the legacy code path kept for one release)"
+D562,FIXED,F10 crosshair pointer hidden while a pad/keyboard drives the menu —,FIXED 2026-10-06 (drawCrosshairPointer draws only while s_mouseActive)
+D563,FIXED,F10 root hub: Left/Right no longer open pages; held nav inputs latched on open/page change —,FIXED 2026-10-06
+D564,FIXED,"F10: game's own ""Look up/down"" row removed (dead for mouse and centred pad, stacked with Invert look); value pinned to factory; tip polish —","FIXED 2026-10-06 (port only; Mouse / Controller ""Invert look"" are the inversion controls)"
+D565,FIXED,AI awareness followed two player render settings:,FIXED 2026-10-06 (maintainer decision:
+D566,FIXED,Steam Deck Game Mode showed the on-screen keyboard at every launch (SDL text input left on) —,FIXED 2026-10-06 (port only:
+D567,FIXED,Front-end PC Options with a pad pulled the game's crosshair to the top-left (overlay synced the cursor to the untouched OS mouse) —,FIXED 2026-10-06 (port only:
+D568,FIXED,F10 dropdown popup drawn empty and misplaced for a long list on a mid-page row (negative top) —,FIXED 2026-10-06 (port only:
+D569,?,Crosshair color follows the PD port:,CHANGED 2026-10-06 (maintainer request; old presets migrate to Custom RGB)
+D570,FIXED,Scaled crosshair (Crosshair size != 100%) showed a faint copy of the top bar's tip under the bottom bar (WRAP tile flags) —,FIXED 2026-10-06 (port only:
+D571,?,"Project icon restyled to the in-game sight red as pixel art (exe, window, favicon) —",CHANGED 2026-10-06 (maintainer request; make_icon.py; social preview unchanged)
+D572,?,Linux tarball glibc floor lowered from 2.38 to 2.31:,CHANGED 2026-10-07 (maintainer request; packaging only; X220 glibc 2.36 fresh install PASS)
+D573,FIXED,"sndPlaySfx / langGet pointer guards used an absolute [64 KiB, 16 GiB) literal; replaced by portAddrIsMapped() (DRAM arena views + mapped cart image) —","FIXED 2026-10-07 (from #108, italoarruda; Windows build + golden:"
+D574,FIXED,Legacy front-end menu-pointer Velocity mode deleted (Input.MenuPointerMode / Input.MenuPointerSpeed); retired ini keys dropped silently —,FIXED 2026-10-07 (D561 follow-up; build + ini runtime check)
+D575,FIXED,Update check (D551) gave no result on Linux/macOS when /releases/latest exceeded 64 KB (curl SIGPIPE); parse helpers moved to a header with an offline test —,FIXED 2026-10-07 (harness 19/19; live Linux/Deck matrix owed)
+D576,FIXED,"ge007.log written next to the ini (previous run kept as ge007.prev.log, 8 MiB cap) —",FIXED 2026-10-07 (Windows runtime check)
+D577,FIXED,"F10 slider labels ended in "".."" at HUD 150:",FIXED 2026-10-07 (captures HUD 100 unchanged / HUD 150 whole)
+D578,OPEN,Frame interpolation above 60 fps (Video.FpsCap 90/120/144):,BUILT 2026-10-07 (Windows:
+D579,FIXED,Issue #150: hugging a wall makes geometry vanish (N64 native widescreen does not).,"FIXED 2026-10-09 (maintainer-verified, Dam gate 16:9; golden sweep owed)"
+D583,FIXED,120 fps + VSync on G-Sync/VRR:,"FIXED on PC 2026-10-09 (G-Sync OLED, maintainer by eye); Deck 90 good on most levels (per-level pass 2026-10-10); open:"
+D584,FIXED,Cradle catwalk shadow flicker at every frame rate (regression from D579).,FIXED 2026-10-10 (maintainer Deck:
+D614,OPEN,Deck Bunker fight texture-cache thrash:,"OPEN: measured, fix not shipped (2026-10-10)"
+D605,FIXED,"Issue #145 (v0.6.0): F10 ""Invert look"" never reached the look stick in the HONEY role (game styles 1.1/1.3 -- left stick looks, right stick is the digital move…",FIXED 2026-10-09 (v0.6.0 line; port-only:
+D606,FIXED,Issue #144 (v0.6.0 triage):,"FIXED 2026-10-09 (v0.6.0 line; port-only in port/src/optionsoverlay.c, src/game zero-diff; off by default so goldens stay byte-identical; smoke-verified:"
+D407,CLOSED,Tanks cannot be boarded/exited on PC —,CLOSED (2026-09-28 bookkeeping:
+D408,FIXED,Game.SkipIntro skips the post-mission failure dossier:,FIXED 2026-09-30 (SkipIntro hook gated to first boot; live dossier check owed).
+D415,FIXED,"Shooting a light fixture does not ""kill"" its flickering light (Bunker, Caverns):",FIXED (2026-09-29 bookkeeping:
+D416,RESOLVED,"2-player split-screen crashes (issue #99, v0.3.0 4827bc8, fault addr 0xa43a0ed4, PC 0x14009e758):",RESOLVED in-harness (converter + D417 + D418 fix the 2P crash and split-screen flicker; 18/18 2P/3P/4P x 6-stage load runs clean; live pad play still owed).
+D417,RESOLVED,enum PROP unsigned on GCC:,"RESOLVED (src/bondconstants.h PROP__PORT_SIGNED = -1, D3/D142 precedent; Rule-2 review done 2026-10-06:"
+D418,RESOLVED,"Split-screen: fast3d safe-area crop stretched the last-set (half-height) viewport over the whole window, so each player's view filled the screen and the last-d…","RESOLVED (gfx_set_split_screen, port-only)."
+D419,RESOLVED,Split-screen input shared between players / P1 lost solo controls:,"RESOLVED (per-slot slotPlayer(), port-only; no current-player swaps from the poll thread; live-tested OK)."
+D420,FIXED,MP score / stats screen shows an odd big number (issue #99) —,FIXED 2026-10-01 (mp/virtual-seats); 2P/3P/4P watch-menu runs show 0s.
+D421,CLOSED,Gadget cycling (pad B / gadget key) disabled in 2+ player matches —,"CLOSED 2026-10-01: moot, no MP inventory holds a gadget (mp_weapon.c); hook reviewed + reverted."
+D422,FIXED,P2+ have no centred-aim mode in split-screen (single-slot aim state) —,FIXED in tree (commit ac92e0ab:
+D423,CLOSED,Unidentified black arrowhead in P2's split-screen view (stage 38) —,"CLOSED 2026-10-01: faithful (level shadow at a doorway top), maintainer-confirmed live."
+D424,FIXED,WeaponStats.RecoilSpeed/b44[] byte order:,"FIXED in tree (WS_B44, port-guarded); user-verified vs GEPD/1964 2026-09-29."
+D425,FIXED,Tank run-over death sound loops:,FIXED (2026-09-29 bookkeeping:
+D426,RESOLVED,Tank cannot be steered with the mouse out of aim mode (issue #116).,RESOLVED (user 2026-09-29:
+D427,FIXED,"Automatic fire cadence is frame-counted, ~2-3x faster than N64 at 60 fps (issue #114).","FIXED in tree (modulus scaled by ticks/frame; measured 6 ticks/shot at 30 and 60 cap); user-verified vs GEPD/1964 2026-09-29 (AK47 mag empties in ~3 s, Klobb normal)."
+D428,FIXED,No gun turn-sway with direct mouse look (issue #117).,FIXED in tree (2nd pass:
+D429,CLOSED,Tank full pass: aim-mode (RMB) mouse behaviour and tank sticking forward/back (follow-up to D426).,CLOSED faithful (user 2026-09-29:
+D430,FIXED,Shot light fixtures do not go dark:,FIXED in tree (D154-style words.w0/.w1 decode); user-verified vs GEPD/1964 on Caverns 2026-09-29.
+D431,FIXED,Light fixtures never reached lightFixtureBreak on PC:,FIXED in tree (fixture table records the image id; bg.c hit code looks it up; free-slot guard); user-verified vs GEPD/1964 2026-09-29.
+D432,FIXED,"Gunshot sounds ""off"" after D427:",FIXED in tree (gate offset rounded to odd at 1 tick/frame); measured shot/sound cadence identical to N64 rules; residual audible difference vs 1964 tracked as D433.
+D433,OPEN,"Slight audible difference in automatic-gun shot sound vs GEPD/1964 after cadence was matched (user by-ear, Caverns).",OPEN (not a timing issue; audio layer suspected).
+D434,FIXED,Raw ((u8*)&g_Textures[n])[0] & 0xf hit-type reads are wrong on PC; latent OOB once D431 returned real texture ids (found by sub-agent review).,"FIXED (.hitTexture at 3 sites, port-guarded); live check owed."
+D440,FIXED,"""Original N64"" / ""Port defaults"" one-press presets in the F10 overlay and front-end PC Options (+ -n64preset/-portpreset).",FIXED (port-only; headless-verified; user live accept owed).
+D441,PARTIAL,64-bit pointer-width sweep (part 1):,"PARTIAL (census + GE_HIGHARENA_BASE tier-1 build + 35 sites fixed + CI ratchet, 2026-10-03; tier-1 all-level sweep 21/21 PASS, 0 crashes, 2026-10-05; the above-4-GiB tier still owed)."
+D442,FIXED,Game.AllUnlocked reworked into a pure RAM/query-time override:,"FIXED; verified 2026-10-03 headless (mission select all 20 / only real progress when OFF, full cheat menu, eep byte-identical)."
+D443,FIXED,"D357 settings-display cleanup (mouse ×, whole-% deadzone and volume steps, FOV in horizontal degrees, MSAA 16×) plus a ""Restart game"" action (orderly D344 quit…",FIXED (port-only; reset probes pass; both-UI visual check and one Restart click owed; Linux relaunch path not compiled).
+D454,FIXED,Knife slash crashed on Windows:,FIXED (verified by maintainer live:
+D461,FIXED,Item-slot allocation overran into the next stage-bank block:,FIXED (maintainer-verified:
+D462,FIXED,vtxstore.c sized its two record tables with the N64 stride 0x14 for a 24-byte struct unk_09B7A0_struct_parent on PC (Vertex* unk00 widened); both are indexed a…,FIXED (build + solo -level_09 and 4P GE_STARTMP=4 smoke runs exit clean; no crash; by-eye owed in solo).
+D444,FIXED,Front-end PC Options:,FIXED (build-verified; human mouse test owed)
+D455,FIXED,Binary-first census of exe-static addresses truncated to 32 bits (D454 class) (2026-09-30).,FIXED/CLEAN (no further REAL site beyond D454)
+D447,FIXED,Pillarbox output mode (Video.AspectMode = Original) for the Original N64 preset; crop overscan no longer cancels Wide/Cinema.,"FIXED (build + 3 captures verified; Wide/Cinema, 16:9 Ratio, mouse and 1964 comparison owed to a human)"
+D445,FIXED,Crouched-rifle firing animation (crouched_rifle_firing_animation_groupA) never resolved on PC -> SIGSEGV in modelConstrainOrWrapAnimFrame when an MP player cro…,"FIXED — layout only (§D5 linker adjacency, D164 class):"
+D446,FIXED,Couch 2P watch-menu text (the MP pause page) differs by +-1-2 per channel between builds whose only difference is data layout (2026-09-29).,FIXED — port-only (fast3d):
+D448,PARTIAL,Split-screen pad seats:,"PARTIAL (committed 918ac5f9 on feat/mp-splitscreen-99, build + 2P smoke OK; plug/unplug behaviour not exercised at runtime)."
+D456,?,"Font-pointer / text-string-pointer slots retyped from s32 to real pointers (ABI/layout exception; front.c, options.c, language.c, bondview*, mpmenu.c, propobj.…",
+D457,?,64-bit ABI retypes part 2:,
+D453,?,"memp allocator API made 64-bit clean (D441 step 0; ABI/layout exception, §A1).",2026-09-30
+D451,FIXED,Automatic-fire gate at unsteady frame rates (D427 follow-up) and D173 residual.,"FIXED (RULE-2-SIGNOFF, maintainer 2026-09-30:"
+D463,FIXED,fast3d divided by zero (0xc0000094) importing a texture for a zero-area TextureRectangle on a tile with line = 0:,FIXED (port-layer guard in import_texture; 8 repeats of the crashing config + the 18-run sweep + solo -level_09 + menu boot all rc=0 with no crash; the guard fired in 3 of 8 repeats).
+D464,PARTIAL,"GE_MEMPREDZONE=1: 64-byte red-zone checker for the memp bump allocator (all banks), side table + checks at level unload / every 60 frames / orderly quit; re-in…","TOOL LANDED (local, feat/memp-redzone); MP sweep owed."
+D465,FIXED,#127 Dam/Caverns/Complex water slid side to side:,"FIXED 2026-10-01 (fix/d465-water-primlod, local); rate measured = N64; maintainer by-eye on Dam:"
+D466,FIXED,#125 Xenia's boss fight on Jungle triggers early:,"FIXED 2026-10-01 (fix/d466-drawdist-gameplay, local); RULE-2-SIGNOFF (port-feature leak fix; design-review approval); verified headless (room sets, on-screen counts), player-facing shot/autoaim/use/p…"
+D467,CLOSED,#130 Golden Gun empty click with each shot:,CLOSED: faithful by code + log (audited 2026-10-01; by-ear check of held-trigger behaviour vs 1964 is maintainer-owned)
+D468,FIXED,AI view clamp: under ultrawide (> 16:9) or Video.FovScale > 100 the AI's on-screen tests used the wider rendered frustum; they now keep the cartridge-widest vi…,"FIXED 2026-10-01 (feat/d468-ai-view-clamp, local); RULE-2-SIGNOFF (policy approved by the maintainer 2026-10-01); verified headless (clamp on/off switching + falsifier)."
+D469,FIXED,Gamepad presets + per-seat controller rebinding (ROADMAP 5a; supersedes outside PR #109):,"FIXED 2026-10-01 (merged into release/v0.4.1, local); preset 0 == old mapping proven (20,971,520 cases); live pad test owed (maintainer); Jinx 1.2/1.3 undefined (gap)"
+D470,FIXED,Audio master volume + output-device selection (ROADMAP 5a):,FIXED (live listening test owed)
+D471,FIXED,Controller-family button names (no glyphs) in the PC menus + player-index LEDs:,FIXED 2026-10-01 (local); headless captures for Xbox/PS/Nintendo; live PS/Nintendo pad check owed
+D472,FIXED,"F10 overlay polish: multi-pad ownership (audit G1-G3), widescreen pillarbox (D335b), red EXPERIMENTAL rows, unknown-ini-key warning.","FIXED 2026-10-01 (merged; port-only, no src/game)."
+D473,FIXED,"Uncached getenv(""GE_D75V"") on every G_VTX:",FIXED 2026-10-01 (local); Statue display-list CPU about -55% in steady windows
+D474,FIXED,fast3d micro-optimisations:,FIXED 2026-10-01 (local); output-identical by construction; measured gain on the dev machine within noise
+D475,OPEN,Statue/Cradle hitches diagnosed:,OPEN (diagnosed 2026-10-01):
+D476,FIXED,CI4 textures keyed on their own 16-entry palette bank instead of the whole 256-entry table (D217 hash):,FIXED 2026-10-02 (local); Statue sweep CI4 cache misses 189 -> 36
+D477,?,CI8 palette re-imports measured and ruled out as a CPU-side hitch cause:,MEASURED 2026-10-02 (local); premise of the D475/D476 follow-up refuted on the dev box; GPU/driver-side cost unmeasured
+D478,FIXED,"D441 read-side census re-run (319 warnings, 129 outside the chr.c D34 initialisers) triaged against the current tree:","FIXED 2026-10-02 (local; snprintf bound); census triage recorded, Stage B items listed"
+D479,FIXED,Split-screen GE_STARTMP harness hid the ammo counter:,"FIXED 2026-10-02 (local); harness-only, 2P frame shows the counter in both halves"
+D480,FIXED,"Shader pre-warm: every created shader pair (shader_id0, shader_id1) is remembered in $S/ge007.shaders and compiled at the first frame of the next session, so a…","FIXED 2026-10-02 (local, perf/shader-prewarm); output-identical (menu frame exact), 0 in-play compiles on the warm run"
+D481,FIXED,Low-end ~45/30 fps (#92):,"FIXED 2026-10-02 (local, perf/render-worker); X220 (HD 3000) 44-46 -> 60.0 fps, GE_RENDERINLINE=1 falsifier restores 45.9"
+D482,FIXED,Lighter first-launch defaults on Atom/Celeron-class GPUs (#92 follow-up):,"FIXED 2026-10-02 (local, perf/lowend-defaults); X220 forced-path:"
+D483,FIXED,#136: the PC crouch key stood Bond up when he switched to the sniper rifle; the N64 keeps the stance (the weapon's DISABLE_CROUCH flag blocks both crouch-down…,"FIXED 2026-10-02 (local, fix/d483-sniper); scripted crouch -> switch -> release keeps SQUAT"
+D484,FIXED,"#136: portScaleFovY's 20-degree floor raised the game's own zoom FOVs, capping sniper/camera magnification at 20 degrees instead of the N64's 7 (about a third…","FIXED 2026-10-02 (local, fix/d483-sniper, maintainer-approved 2026-10-02); full zoom renders at 7 degrees, normal views pixel-identical"
+D485,FIXED,"#136: sniper/camera zoom stepped once per game frame with no tick scaling, so at the port's 1 tick/frame it zoomed 2x faster in real time than the N64 at 2 tic…","FIXED 2026-10-02 (local, fix/d483-sniper); 15 -> 7 takes 16 frames at 60 fps (was 8) = the N64 at 30 fps"
+D486,FIXED,#126: explosions dropped in heavy firefights (turrets on Cradle/Egypt/Aztec):,"FIXED (a)(c)(d); drops + (b) faithful, closed."
+D487,FIXED,"PAL: the in-level ammo counter was not drawn (only a small dot where the ""7 / 93"" counter should be) —",FIXED; maintainer PAL play check 2026-10-02:
+D488,FIXED,PAL build reported the Brazilian MPAL TV type instead of PAL (osTvType) —,FIXED
+D489,FIXED,FPS dropped sharply while adjusting F10 watch sliders (music/FX) with a pad or arrow keys:,"FIXED 2026-10-02 (port-only UI layer, fix/d489-pad-slider-commit, merged into release/v0.4.1 2026-10-03); maintainer pad check passed 2026-10-03"
+D490,FIXED,Dam first-tower guard walked a small circle:,"FIXED 2026-10-02 (fix/d490-glass-hull, merged into release/v0.4.1 2026-10-03); maintainer by-eye Dam check passed 2026-10-02"
+D491,FIXED,"Struct reads across separately-declared adjacent globals (the D5/D215 class), found by the D24 overflow audit:","FIXED 2026-10-03 (fix/d491-adjacent-global-reads, local); builds clean, 900-frame -level_09 smoke clean; no by-eye effect expected beyond room-membership-driven behaviour"
+D492,CLOSED,Emulator .eep saves are not drop-in compatible:,CLOSED (converter shipped 2026-10-04:
+D493,FIXED,Pad rumble kept going after quitting the game:,"FIXED 2026-10-03, maintainer-verified in play (DualSense; Original-mode edges incl."
+D494,FIXED,"Sniper rifle: the PC crouch key now crouches/stands freely with a disable-crouch weapon (GEPD parity), never injecting C-down for it; supersedes D483's stance…","FIXED 2026-10-03, maintainer-verified in play"
+D495,FIXED,"Tank: with the default pad preset X changed the tank weapon and Y left it, because in-tank faces fell back to the fixed menu faces; PadMapCtx.tank routes Next/…","FIXED 2026-10-03, maintainer-verified in play"
+D496,FIXED,3P/4P split-screen: weapon-pickup messages garbled and oversized —,"FIXED 2026-10-03 (condensed 3+P text is faithful, maintainer-confirmed)"
+D497,FIXED,PC Options paging now matches the game's dossiers:,"FIXED 2026-10-03, maintainer-verified in play"
+D498,FIXED,Xbox 1.2 Christmas / 1.3 Frost / 1.4 Elektra gamepad presets:,"FIXED 2026-10-03, maintainer-verified with a pad"
+D499,FIXED,Trilinear texture filter option:,"FIXED 2026-10-03, maintainer-checked (no visible difference; kept)"
+D500,FIXED,"Aztec shuttle area: polygons ""fell apart""; the per-frame vtx pool (dyn.c, no bounds check, Aztec -mvtx40) could overrun into the half the render worker draws;…","FIXED 2026-10-03, maintainer-verified at the Aztec spot"
+D501,CLOSED,Ultrawide 16:9 pillarbox for cutscenes and the watch:,CLOSED (reverted 31ade91f)
+D502,FIXED,PC Options pad navigation:,"FIXED 2026-10-03, maintainer-verified with a pad"
+D503,PARTIAL,"Surface: near-full-fog silhouettes on 32-bit output (fog snap applied); the remaining Surface dish is the widescreen frustum, 4:3 matches N64 —",FIX LANDED (by-eye pass owed)
+D504,FIXED,F10 / PC Options menu:,FIXED (port-only; by-eye pass vs the PD port owed)
+D505,FIXED,Menu wording pass: 27 maintainer-approved text edits across both PC options UIs —,FIXED (port-only; by-eye pass owed)
+D506,FIXED,Menu slider values standardized:,FIXED (port-only; by-eye pass owed)
+D507,FIXED,Menu: one-line description of the focused option in both PC options UIs —,FIXED (by-eye pass owed)
+D508,FIXED,Forced aspect ratios:,FIXED (by-eye pass owed)
+D509,FIXED,Held frames after an aspect-ratio change:,FIXED (by-eye pass owed)
+D510,FIXED,F10 overlay + FPS counter the same on-screen size on the front end and in a level —,FIXED (live check owed)
+D511,OPEN,Four PD-parity settings:,DONE headless (live checks owed)
+D512,OPEN,Game.HudScale also scales the F10 overlay and FPS counter —,DONE headless (live check owed)
+D513,OPEN,"Input.ControlScheme: Modern / OG controls (#139, T7) —",DONE headless (pad pass owed)
+D514,OPEN,Emulator saves load directly:,DONE headless (by-eye mission select owed)
+D515,FIXED,Empty arch tag from a fresh build dir:,FIXED (headless-verified)
+D516,FIXED,"Control style Original shows the game's own N64 styles (1.1-2.4, per seat, saved to the Bond file) instead of the D498 presets —",FIXED (live pass 2026-10-04 incl.
+D517,FIXED,Holding left/right on a Bond settings row dropped the fps:,FIXED (live pass 2026-10-04)
+D518,FIXED,Pad layout preset was one global value:,FIXED (live pass 2026-10-04 incl.
+D519,FIXED,"One PC options UI: the file-select ""PC Options"" entry opens the F10 overlay; the MENU_PC_OPTIONS screen is deleted —",FIXED (headless-verified 2026-10-04; by-eye pass owed)
+D520,FIXED,"F10 overlay slider wedge, slider marker and dropdown arrow antialiased (they stepped in whole canvas pixels that grow with the window) —",FIXED (headless before/after capture; by-eye owed)
+D521,PARTIAL,A fixed-frame golden window that overlaps the intro flyby is platform-nondeterministic (cross-platform goldens); verify.sh's linux pixel-gate skip is driver-co…,PARTIAL (rule recorded 2026-10-04; the two residual bands CLOSED 2026-10-05 by D525's box re-round —
+D522,FIXED,The golden window's frame-900 stem is not settled gameplay on several levels —,FIXED 2026-10-05 (recipe-side re-base:
+D523,CLOSED,The golden recipe does not pin save state:,SUPERSEDED by D529 (2026-10-05) —
+D524,FIXED,The golden tooling was destructive and drift-prone:,FIXED 2026-10-05 (both pins idempotent —
+D525,FIXED,"The whole <level>/linux/ golden set was stale, not just on the six re-based levels —","FIXED 2026-10-05 (21-level box re-round, 63 frames, save pinned present; structural parity 21/21, Archives/Streets bands attributed to save state, not a renderer)"
+D526,CLOSED,P13 Dam-ending grate / edge-railing transparency is faithful N64 behaviour (port == 1964/GEPD); the per-triangle census probe is retained as a generic draw-sta…,"CLOSED — faithful, confirmed on 1964/GEPD (2026-10-05):"
+D527,OPEN,GE_PCDUMP written first:last (a colon where the dash belongs) silently dumps EVERY frame —,OPEN (harness documentation; a log-or-fail-closed fix is owed in the port layer)
+D528,OPEN,"GE_STARTMENU skips the EEPROM read, so front-end-only sessions never import the emulator save —",OPEN (harness documentation; the D514 imported-save test must run from a normal boot; a log-or-import fix is owed in the port layer)
+D529,FIXED,The golden gate depends on the save file's CONTENT —,FIXED 2026-10-05 (canonical save in-tree at tools_pc/golden/ge007.eep; verify.sh installs it like the ini pin; all 21 win sets re-captured under it —
+D530,?,The box (X220) linux golden re-round landed —,AMENDED BY D531 (2026-10-05) —
+D531,FIXED,capture_p7.sh's D529 adaptation was incomplete —,"FIXED 2026-10-05 (loop re-pins the canonical save per level + cd ""$ROOT""; fresh 21/21 box re-capture committed —"
+D532,FIXED,The three P12 U5 should-fixes applied —,FIXED 2026-10-05 (tooling-only:
+D533,FIXED,"The probe-doc drift that would have failed CI, plus three tracked-file accuracy/hygiene fixes (release-sweep spot-check) —",FIXED 2026-10-05 (GE-ENV-PROBES.md missing the GE_D526 family → gen_env_probes.py --check rc 1 = a CI-failing step; build-pc.sh local MSYS2 root in two messages; docs/fidelity.md og line; release-not…
+D534,FIXED,Pre-release review of the 2026-10-05 local batch —,FIXED 2026-10-05 (verify.sh/capture_p7.sh INT/TERM trap; release-notes linux-gate wording; dead security-and-fidelity-status.md links; future-dated 2026-10-07 labels normalised; D526 probe dangling-e…
+D540,FIXED,Fog rework (Deck playtest):,FIXED 2026-10-05 (port:
+D450,FIXED,"Unplugging and replugging a controller was not picked up (user, GameSir-G7 Pro; 2026-09-29).","FIXED — port-only: the render thread's gfx_sdl_handle_events drains the same SDL queue as video.c's host pump but had no case for SDL_CONTROLLERDEVICEADDED/REMOVED, so it usually swallowed them and i…"
+D436,FIXED,"Persistent (hipfire) crosshair, opt-in:",FIXED (shipped 2026-09-29; rule-2 sign-off:
+D617,OPEN,"The HD pack's ge007.tdb is the emulator's full per-draw key list, not the pack's PNG list —",OPEN — plan written (docs/dev/TEXPACK-RICE-DRAW-PLAN.md); whole-texture recipe confirmed correct by 9 tdb hits with exact ;WxH agreement; PNG-filename and brute-force param searches are dead ends
+D618,?,"The community HD pack's non-CI keys are per-draw rects partly unreachable from N64 tile state (440x1 strips), and a rect key cannot land in the whole-texture p…",STOPPED 2026-10-06 — tdb ;WxH are per-draw rects (440x1 ×301 over tmem's 128-byte pitch = recompile-side); ~100 byte-domain variants score 0 hits; content-join does not discriminate; rect-keyed repla…
+D619,?,"The community HD pack's remaining 1790 PNGs are blocked by four independent causes (recompile-side rect keys, wrong hash domain, rect-vs-whole-texture format,…",WRITTEN UP 2026-10-06 —
+D620,OPEN,The HD pack's non-CI keys hash the pack's own re-encoded content —,MEASURED 2026-10-07 —
+D621,PARTIAL,The PD dabs-mod texture-pack notes mine:,PLAN LANDED 2026-10-07 —
+D622,?,B0 sprite-bank confirmation —,"PASS 2026-10-07 — two human-driven GE_TEXNUMDUMP+GE_TEXDUMP runs (front end 377 unique texnums / 521 dumps, -level_09 combat 321 / 316; evidence scratch/b0/):"
+D623,OPEN,Phase B1–B3 measured:,MEASURED 2026-10-07 —
+D624,OPEN,B4 content scorer built + tuned:,"BUILT 2026-10-07 — 5-stage pipeline (geometric prefilter → content rank → GT-tuned auto-accept → vision judge → human queue) per the 2026-10-07 decision (commits 512e6d57, 95d38637)."
+D625,?,"texpack A5: downscale-to-GL-max instead of the D615 vanilla fallback, plus first-use decode-stall metering —","BUILT 2026-10-10, not yet A/B-verified —"
+D626,FIXED,Windows DPI awareness was never declared:,FIXED 2026-10-10 (gfx_sdl2.cpp:
+D627,FIXED,DexDrive / GameFAQs .n64 saves import directly:,"FIXED 2026-10-10 (eepimport.c + eep_convert.py dexdrive-to-pc); byte-identical to the reference extraction, malformed inputs rejected untouched; by-eye mission select owed"
+D628,RESOLVED,"The exact-CRC CI half of the GoldenEye-007-HD join is sound (256 texnums, independently re-verified), but its structural half was scored against GE_TEXDUMP cap…","CI HALF ACCEPTED 2026-10-10 (256/256 (crc,fmt,siz) agreement with the rice census, 256 distinct texnums, palette-variant collision resolved by ROM palcrc, builder resolves all 256 sources); structura…"
+D632,OPEN,Exit BSOD 0x119 recurred (2026-10-10) despite D344; the first minidump shows it fires in the kernel's process-exit GPU cleanup (DXGPROCESS::Destroy -> DXGCONTE…,FIX BUILT 2026-10-10 (fix/d632-exit-teardown):
+D636,FIXED,Non-CI pack textures ARE fingerprint-keyed:,FIXED 2026-10-10 (feat/texpack-fp):
+D637,?,Fingerprint fallback in the loader:,BUILT 2026-10-10 (feat/texpack-fp); C CRC == Python on 80 ROM glyphs; not run-verified (game runs on hold)
+D638,FIXED,HD-pack ammo icon cut off:,FIXED 2026-10-10 (chore/v070-agentic-batch):
+D639,OPEN,Exclusive fullscreen picked the wrong resolution:,FIX BUILT 2026-10-10 (chore/v070-agentic-batch):
+D643,FIXED,Issues #145 (b)(c) / #149:,FIXED 2026-10-12 (port-only; GE_PADMAPTEST PASS; maintainer pad pass vs the #145/#149 reports; 1:1 N64-pad stick check owed when an adapter is available)
+D644,FIXED,File-select royal crest drew on an opaque dark square (#146):,"FIXED 2026-10-12 (import_texture_ia4; 1964-confirmed symptom, maintainer-verified; Win sweep unchanged)"
+D645,FIXED,"Original 1.1: F10 ""Invert look"" did not invert vertical look (#145 a):",FIXED 2026-10-12 (F10 row and watch row synced in Original; maintainer-verified)
+D646,FIXED,"F10 dropdown popup drew over the hint/tooltip panel (popup bounded by the screen edge, not the settings box) —",FIXED 2026-10-12 (ddGeom bounded to the box; maintainer-verified)
+D951,OPEN,"v0.6.0 release gate: Windows golden sweep flags are timing noise in the test, not rendering changes —",OPEN (test-side; 2026-10-13)
+D952,FIXED,"macOS: black window, no frame, when the game starts while the display is asleep (SDL3 Cocoa VSync waits forever on a CVDisplayLink that never started) —","FIXED 2026-10-13 (port-only, gfx_sdl2.cpp; Mac A/B:"
+D953,FIXED,Deck: wide Field of view feels choppier while turning —,FIXED 2026-10-13 (v0.6.0; LOD + prop fog fade/visibility follow the game FOV; maintainer Deck-confirmed)
+D954,FIXED,"Doors and guards flicker at 90 fps, not at 60:","FIXED 2026-10-13 (port-only, gfx_pc.cpp + interpportal.c; maintainer Deck-confirmed)"
+D955,FIXED,"Objects (props, doors, guards) moved at the 60 Hz tick inside a 90 Hz picture:","FIXED 2026-10-13 (port-only, gfx_pc.cpp + interpportal.c; sky pass; maintainer Deck-confirmed)"
+D607,OPEN,Address model unified into one header:,DONE 2026-10-07 (macos branch; Windows identity gate:
+D608,FIXED,D34 ANIM_DATA_x re-basing guard in assets/animationtable_data.h was __x86_64__-only:,"FIXED 2026-10-07 (macos branch; mechanical guard widening, arm64 link clean)"
+D609,FIXED,macOS arm64 SIGKILL at exec:,"FIXED 2026-10-07 (macos branch; probe-confirmed; arm64 keeps the 4 GiB pagezero, floor 11.0)"
+D610,FIXED,GE_MEMPOOL_CEILING (port/src/n64stubs.c) hard-coded the D441 base-0 arena top; now #if PORT_ADDR_BASE != 0-keyed so arm64 gets the arena-relative ceiling and b…,FIXED 2026-10-07 (macos branch; base-0 identity by construction)
+D611,FIXED,"Mempool arena start is truncated to 32 bits at three carriers (osVirtualToPhysical, PHYS_TO_K0, src/boss.c:168 u32 start) so arm64 macOS banks live at arena-re…","DIAGNOSED 2026-10-07 (macos branch; arena-start leg fixed as D612, rest owed with the #95 re-application)"
+D612,PARTIAL,Arena-start leg fixed (src/boss.c:,PARTIAL 2026-10-07 (macos branch:
+D613,FIXED,PR #95 (macos branch) re-applied onto release/v0.5.1 —,FIXED 2026-10-07 (macos branch)
+D586,FIXED,"Apple gen_macho_syms.py --base parse was dead code (undefined args), the shifted literals emitted bare (assembler ""expected newline""), and the generated .s dir…",FIXED 2026-10-07 (macos branch)
+D587,FIXED,macos sweep: 9 of the first 13 levels SIGSEGV at one site —,FIXED 2026-10-07 (macos branch)
+D588,FIXED,Windows x86_64 SIGSEGV (deterministic 3/3) in texReadBits under lvlStageLoad:,FIXED 2026-10-07 (macos branch)
+D589,RESOLVED,macOS arm64: wide-pixel (32-bit RGBA / 16-bit) textures render as colourful static / confetti (the Surface 1/2 billboard trees) while x86_64 renders them corre…,RESOLVED 2026-10-08 (macos branch; byte order fixed+verified = D591; the SECOND CAUSE D592 is CLOSED as a non-issue —
+D590,FIXED,"Windows x86_64 deterministic SIGSEGV in load_bg_file (bg-load worker thread, 4/4 incl.",FIXED 2026-10-08 (macos branch)
+D591,FIXED,arm64 macOS fast3d mis-classifies every DRAM/cart texture source as a “C-compiled array” and byte-swaps it —,FIXED + Mac A/B VERIFIED 2026-10-08 (macos branch; 9c59cbe7) —
+D592,CLOSED,"arm64 macOS — the ""rock striping"" (the remaining cross-platform frame diff after the D591 byte-order fix) is a VHF-metric FALSE-POSITIVE, not a GL-layer defect.",CLOSED (non-issue) 2026-10-08 (macos branch; VHF-metric false-positive —
+D593,OPEN,"Windows x86_64 — an occasional render-thread stall fired the kernel's ""no frame rendered for N ms"" watchdog (observed once, 8001 ms, on an NVIDIA RTX 5090 duri…",OPEN 2026-10-08 (Windows; single observation; repro + root-cause owed)
+D594,FIXED,arm64 macOS — partial input:,FIXED 2026-10-08 (macos branch; actHeld menu gate + macOS reconcileGrab focus gate → PD MLOCK_ON; LMB fire verified on the Mac; unblocked D595)
+D595,FIXED,arm64 macOS — deterministic SIGSEGV in modelSetAnimFrame when an AI plays a hit/stagger/death animation (fire → triggered_on_shot_hit → modelSetAnimation2); th…,FIXED 2026-10-08 (macos branch; read the base at full pointer width —
+D596,FIXED,"the win/ golden set predates D565/D569/D570, so verify.sh on the macos branch (and the main tip) reported a REGRESSION worst_cell=3.106875 that is a stale refe…","FIXED 2026-10-08 (macos branch; win goldens regenerated from e0a2d4b9, 21/21 PASS; recipe-side only, no game-code change; the linux/deck sets need their own re-capture round before any new cross-plat…"
+D597,FIXED,"GE_INPUTSCRIPT gains MLB<n>/MRB<n> (sustained mouse-button tokens, slot 0):",FIXED 2026-10-08 (macos branch; Windows menu + forced-level keylog checks; Mac sweep-fire no-crash run + no-env no-op run; the live E1 LMB fire is the struck-animation ground truth; cmd-wrapper gotch…
+D598,RESOLVED,"arm64 macOS gameplay is ""a bit choppy"" on heavy levels (Cradle-class) —",RESOLVED 2026-10-08 by D600 (display-locked retrace tick; live playtest confirmation owed)
+D599,FIXED,arm64 macOS: SIGBUS (signal 10) the moment a game controller is connected —,FIXED 2026-10-08 (macos branch; Mac M3 re-run with a connected Xbox pad:
+D600,FIXED,VSync-on frame pacing:,FIXED + LIVE-CONFIRMED 2026-10-08 (macos branch; Mac M3:
+D601,FIXED,"Long-session hang at stage load (macOS playtest, Archives):","FIXED + LIVE-CONFIRMED 2026-10-08 (macos branch; #ifdef PORT guard, D152/D285 class; evidence = live lldb read of the hung process; maintainer full-campaign completion incl."
+D602,OPEN,macOS end-credits SIGBUS:,"MITIGATED 2026-10-08, OPEN (macos branch; langGet returns NULL for offset > 1 MiB and logs the bank state once as D602:; needs one natural-flow re-trigger to diagnose)"
+D603,FIXED,"arm64 macOS multiplayer (2P, stage 38) SIGSEGV in modelSetAnimFrame via playerTick:","FIXED 2026-10-08, live confirmation owed (macos branch; identity at PORT_ADDR_BASE==0; headless 2/3/4P + solo smoke clean but the death/firing-animation path is not reachable headlessly)"
+D604,FIXED,arm64 macOS multiplayer respawn SIGSEGV:,FIXED + LIVE-CONFIRMED 2026-10-08 (macos branch; maintainer 2P respawn OK; identity at PORT_ADDR_BASE==0)

docs/dev/preview-video.md

@@ -31,7 +31,7 @@ passes together fit in ~55 s.
 
 ## Source material
 
-`C:\Users\james\Videos\NVIDIA\Build-pc\new\` — ShadowPlay recordings
+`<videos>\NVIDIA\Build-pc\new\` — ShadowPlay recordings
 (3072x1728 @ 60 fps, h264), no usable audio track (cut with `-an`). The four
 sessions and their tags are hardcoded in `SESSIONS` at the top of the script;
 add a new session there (tag, filename suffix, duration) to use it.

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

@@ -1,5 +1,7 @@
 # Release plan — "drop in your ROM and play"
 
+> **Historical record — do not act on status claims in this file.** Part A shipped as the NTSC-U drop-in ROM flow (PR #84, issue #6). The remaining Part B pieces are tracked in the roadmap. Current open work and status: [`docs/ROADMAP.md`](../ROADMAP.md) (2026-09-29).
+
 Status: proposal / not yet scheduled. Owner: TBD.
 
 ## Goal

docs/documentation.md

@@ -0,0 +1,33 @@
+---
+title: Documentation
+description: The technical documentation for the GoldenEye 007 PC port; the architecture, the N64-to-PC bug catalogue, and how the project is developed.
+date: '2026-10-05'
+modified_time: '2026-10-05'
+---
+
+## Documentation
+
+The technical documentation for the port: the **architecture** and how the
+project is **developed**. (Building and running from source live on the
+separate [Building](building.md) page.)
+
+## Architecture
+
+- **[Internals](internals.md)** — the architecture: the software RSP, the
+  port layer, the asset pipeline, and the phased plan. The single reference
+  for what the port is and how it's put together.
+- **[Porting notes](porting-notes.md)** — the catalogue of N64→PC bugs: the
+  recurring classes of defect and the ground-truth pattern each fix follows.
+
+## Development
+
+- **[Development process](dev-process.md)** — the investigation workflow:
+  task budgets, file partitioning, the finding-log discipline, and the rules
+  for what counts as a diagnosis versus a change.
+- **[Agentic development](dev/agentic-development.md)** — the case study:
+  how the two-AI-agent setup ran, its timeline and numbers, and an honest
+  read on what did and didn't work.
+- **[Security status](security.md)** — what the release packages install
+  (and don't): no networking unless you opt in to the update check, no telemetry, no ROM, no system writes.
+- **[Fidelity status](fidelity.md)** — how faithfully the port reproduces
+  the N64 game's logic, and what was audited to back that claim.

docs/fidelity.md

@@ -0,0 +1,72 @@
+---
+title: Fidelity status
+description: How faithfully the port reproduces the N64 game: unmodified decompiled logic, Makefile-mirrored region macros, one game-logic-adjacent change, and PRNG notes.
+date: '2026-10-05'
+modified_time: '2026-10-05'
+---
+
+## Fidelity status
+
+This page answers one question plainly: *how faithfully does the port
+actually reproduce the original N64 game's logic*?
+The audit was run end-to-end on 2026-09-15 and re-verified for the v0.3.0
+release bundles on 2026-09-18.
+
+**v0.5.0 update pass, 2026-10-05:** two of the checks were re-run
+directly against the current tree — the region build macros were
+compared line-by-line against the original N64 Makefile's macro sets
+(all three regions match exactly), and the library file classification
+(which original files compile versus get PC-shimmed) was re-checked
+against the project's own ground-truth manifest (the CMake build
+compiles the libultra and libultrare audio sets, the gu matrix helpers,
+and `io/vitbl.c` only — no silent gaps, no silent duplicates). The
+full game-logic audit was not re-run in this pass; recent `src/game`
+edits on the release branch are finding-gated (for example the D519
+front-end options work, and a model-c scripted-camera clamp removal
+that returned those files to pure decompilation). The full engineering
+record behind each item is in the project's finding log
+([`docs/dev/findings.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/findings.md)).
+
+## The rule and what was checked
+
+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 (re-run 2026-10-05).
+- **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 (re-run 2026-10-05).
+- **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.*

docs/framerate-and-pacing.md

@@ -0,0 +1,56 @@
+---
+title: Framerate and pacing
+description: How the GoldenEye 007 PC port holds a steady 60 fps, draws frames above 60 on fast displays, and keeps per-frame game timing correct on a fast CPU.
+date: '2026-10-05'
+modified_time: '2026-10-10'
+---
+
+## Framerate and pacing
+
+The port targets a **steady 60 fps** with VSync and a frame cap, including on
+low-end GPUs. Since v0.6.0 the cap can also go above 60 on a faster display
+(see [Above 60 fps](#above-60-fps)).
+
+The N64's game code assumed a **60 Hz vertical-interrupt tick** — it ran a
+few ticks per displayed frame. On a PC the CPU is far faster, so left alone
+the game logic would race ahead. The port handles this in two places:
+
+- **Frame pacing** happens in `port/src/video.c` on the render thread (the
+  software RSP thread), which paces the frame and does the swap and FPS
+  accounting.
+- **Per-frame counters** in the game are gated with `portN64FrameStep()` so
+  they advance at the *display* rate, not the CPU rate. Getting this wrong is
+  a recurring class of subtle timing bug (a counter that ticks too fast, a
+  stall that isn't real) — the [porting notes](porting-notes.md) track these
+  (for example D13, D22 and D486).
+
+On very weak integrated GPUs (Atom/Celeron class) the first launch writes
+lighter values for draw distance, LOD distance and anti-aliasing into
+`ge007.ini` so the game still holds 60 fps.
+
+### Above 60 fps
+
+`Video.FpsCap` (F10, *Frame rate cap*) accepts Auto, 30, 60, 90, 120, 144, 165 and 240.
+**Auto** is the default on fresh installs (an existing `ge007.ini` keeps its
+value) and matches the display's refresh rate, up to 240 (the renderer draws at most four
+frames per game tick); on a 60 Hz display it
+is plain 60.
+
+- **The game still simulates at its original 60 Hz (NTSC) tick.** The extra
+  frames are drawn between two game ticks by blending the previous and current
+  frame's matrices (camera and objects), so no game state changes.
+- **Cost:** one game tick of extra latency.
+- **Inert on 60 Hz displays.** The present rate is the lower of the cap and the
+  display's refresh rate. The *Original N64* display mode caps at 60.
+- **Fallbacks:** a fast camera turn or a large change in the visible room set
+  draws a full (non-blended) frame instead.
+- The design comes from f1zz1ec0ke's PR #137; the port reworked it onto the
+  render worker thread and from a fixed 2x to any present rate, so a 90 Hz
+  Steam Deck OLED works (D578, D583, D584).
+
+Checked by the maintainer: 120 Hz with VSync on a G-Sync display on PC, and 90
+fps on the Steam Deck. Known issue: on the Deck at 90, centre firefights in
+Bunker 1/2 can drop several fps, and Jungle can feel slightly less smooth.
+
+*More: [porting notes](porting-notes.md) — the timing-related findings (D13,
+D22, D486).*

docs/index.md

@@ -1,13 +1,20 @@
 ---
 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).
+# v0.6.0: status bumped from v0.5.0. Description kept short (Bing's 160 limit).
 description: >-
   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
+  decompiled source with a software RSP. v0.6.0 for Windows, Linux and
   Steam Deck.
+# Freshness signals for jekyll-seo-tag (article:published_time / modified_time
+# and the WebPage JSON-LD dates). Keep these equal to the last real content
+# change of THIS page, not to the last release.
+date: '2026-10-05'
+modified_time: '2026-10-13'
+locale: en_US
+# The masthead is this page's title, so its first content h2 must NOT get the
+# amber page-title look (double header). See the .flat-title rule in
+# _includes/head-custom.html.
+flat_title: true
 ---
 
 A native PC port of _GoldenEye 007_ (Rare, 1997, Nintendo 64), compiled from
@@ -19,58 +26,110 @@ 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.
 
-[Download](#download) · [News](#news) · [See it running](#see-it-running) · [Honest status](#honest-status) · [Documentation](#documentation)
+[Status](#status) · [Download](#download) · [See it running](#see-it-running) · [Known issues](#known-issues) · [Documentation](#documentation)
 
-**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).
+## Status
 
-**This is a pre-1.0 release, not a finished product** — v1.0 is the target
+<div class="cblock" markdown="1">
+
+### v0.6.0 (2026-10-13) — frame rates above 60, experimental macOS, fixes.
+
+- **Frame rates above 60:** the frame cap offers 90, 120, 144, 165 and 240, and **Auto**
+  (the default on fresh installs) matches your display. Frames between game
+  ticks are blended; the game still simulates at its original rate. It costs
+  one game tick of latency and does nothing on a 60 Hz display. A rework of
+  f1zz1ec0ke's #137. See [framerate and pacing](framerate-and-pacing.md).
+- **macOS on Apple Silicon, experimental:** a `macos-arm64` download (not
+  notarized; run `xattr -dr com.apple.quarantine <folder>` once before the
+  first launch) or build from source. Based on danturn's #95.
+- **Fixes:** geometry vanishing against a wall (#150), the first launch opening
+  on the wrong monitor (#151), a Linux end-credits crash (#152), a hat-spawn
+  crash (#153), the Cradle catwalk shadow flicker, and stale pixels beside the
+  native-widescreen picture.
+- **Known issues:** on the Steam Deck at 90 fps, Bunker 1/2 centre firefights
+  can drop several fps and Jungle can feel slightly less smooth; Cradle's
+  turret explosions may draw wrongly (not yet investigated).
+
+</div>
+
+<details>
+<summary>v0.5.0 (2026-10-07) — split-screen multiplayer, one options menu, closer to the N64</summary>
+
+<div class="cblock" markdown="1">
+
+- **Split-screen multiplayer for up to 4 players**, each player with their
+  own pad, controls and aim settings.
+- **One options menu** for every setting, laid out like the Perfect Dark
+  port's, with the game's own crosshair as the mouse pointer. Pick the game's
+  own N64 control styles (1.1–2.4) per player, or the Xbox release's presets
+  with per-player pad rebinding; PlayStation and Nintendo pads show their own
+  button names.
+- **Closer to the N64:** fog and haze (Surface 2's ground fog, the sky at the
+  horizon), automatic-weapon fire rate, sniper and camera zoom, Dam and
+  Caverns water, the Jungle boss fight's timing, guard visibility in
+  widescreen, and the Dam ending camera.
+- **Fewer crashes and glitches:** a multiplayer crash with the crouched rifle,
+  rockets passing through the ground, and broken geometry around Aztec's
+  shuttle.
+- **A steady 60 fps on low-end GPUs** (tested on an Intel HD 3000 laptop),
+  with lighter first-launch defaults on Atom/Celeron-class graphics.
+- **Emulator saves load directly:** copy a 1964 or Project64 save in as
+  `data/ge007.eep` and it is converted on first launch.
+- Also: more audio, video and control settings (master volume, audio device,
+  trilinear filtering, draw distance up to 800%, PC-friendly crouch and
+  look-ahead defaults), and controllers are picked up again when replugged.
+
+</div>
+</details>
+
+What remains is a short list, under [Known issues](#known-issues).
+
+**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).
+occasional breaking change until then. The [README's Roadmap
+section](https://github.com/jkdansereau/goldeneye-pc-port#roadmap) is the
+single tracker for what comes next.
 
-<p align="center">
-  <img src="media/goldeneye-gh-preview.gif" width="70%"
-       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>
+<details id="known-issues">
+<summary>Known issues</summary>
 
-## News
+<p>Full table in the <a href="https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/ROADMAP.md#known-issues">roadmap's known-issues section</a>; root causes in the <a href="https://github.com/jkdansereau/goldeneye-pc-port/tree/main/docs/dev">finding log</a>.</p>
 
-- **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.
+<ul>
+<li><strong>NTSC-U ROMs only in the release packages.</strong> PAL and JP ROMs convert, build and run from source, but release packages ship the US (NTSC-U) ROM. On the roadmap.</li>
+<li><strong>Changing the aspect ratio in a level can briefly glitch the gun/hand model</strong> (cosmetic, one-off). Change the ratio from the front-end PC Options, or accept it (D509).</li>
+<li><strong>No ARM Linux build; macOS is experimental.</strong> The release ships Windows, Linux and Steam Deck (keyboard, mouse and controller-button rebinding are all supported, defaults in the <a href="https://github.com/jkdansereau/goldeneye-pc-port#controls">README's Controls section</a>). macOS on Apple Silicon is an experimental, not-notarized download (run <code>xattr -dr com.apple.quarantine &lt;folder&gt;</code> before the first launch) or a source build; ARM Linux is on the roadmap.</li>
+<li><strong>Saves from v0.4.0 and earlier can hold fake unlocks from <code>All unlocked</code></strong> — <code>All unlocked</code> has not written your save since v0.5.0, but saves made while it was on in v0.4.0 and earlier can hold fake unlocks and are not repaired; back up <code>data/ge007.eep</code> if you used it on an older build (D442, D387).</li>
+<li><strong>The first frame of a level takes a little longer</strong> while its textures upload — a brief FPS-counter dip; nothing to fix (D475, D480).</li>
+<li><strong>In widescreen, far objects almost fully in fog can still show a faint distant building edge</strong> (4:3 matches the N64). Cosmetic (D503).</li>
+</ul>
+
+</details>
+
+<details>
+<summary>Release history</summary>
+
+<p class="warn"><strong>Warning:</strong> always use the latest release — earlier builds are kept in the release history for reference only; they lack the features and fixes of newer versions, so don't install an older release.</p>
+
+<ul>
+<li><strong>2026-10-07 — v0.5.0</strong>: split-screen multiplayer, one options menu, closer-to-N64 fog and fidelity fixes, emulator save import. <a href="https://github.com/jkdansereau/goldeneye-pc-port/releases/tag/v0.5.0">Release notes</a>.</li>
+<li><strong>2026-09-28 — v0.4.0</strong>: 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. <a href="https://github.com/jkdansereau/goldeneye-pc-port/releases/tag/v0.4.0">Release notes</a>.</li>
+<li><strong>2026-09-20 — v0.3.0</strong>: the first release with the complete campaign playable end to end at 60 fps on Windows, Linux, and Steam Deck. <a href="https://github.com/jkdansereau/goldeneye-pc-port/releases/tag/v0.3.0">Release notes</a>.</li>
+<li><strong>2026-09-04 → 2026-09-16 — v0.1.0 – v0.2.2</strong>: the alpha and beta cycle — build chain, software RSP, first rendered frames, front end, and per-level stabilization across the campaign.</li>
+</ul>
+
+</details>
 
 ## Download
 
+<div class="cblock" markdown="1">
+
 | Platform | Bundle | Notes |
 |---|---|---|
 | **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. |
+| **macOS** (Apple Silicon, experimental) | macos-arm64 tarball | SDL2 and the C++ runtime are bundled. Not notarized: run `xattr -dr com.apple.quarantine <folder>` once before the first launch. Tested on one Mac; reports welcome. |
+| ARM Linux | — | No download; on the roadmap. |
 
 **Bring your own ROM.** Both bundles contain no ROM and no game assets: you
 supply your own GoldenEye 007 N64 ROM (the
@@ -80,77 +139,37 @@ ROM; PAL and JP are on the roadmap. Then: unpack, drop the ROM in `data/`,
 and launch; the first run generates the derived assets automatically (no
 Python or other tooling needed). The full steps are in the
 [Quick start](https://github.com/jkdansereau/goldeneye-pc-port#quick-start);
-pre-built releases are legal to distribute precisely because they're useless
-without a ROM you already own.
+  the packages carry no ROM or game assets, and run only with a ROM you
+already own. The binaries are not code-signed; each
+release artifact carries a GitHub build-provenance attestation you can
+verify with `gh attestation verify <file> --repo
+jkdansereau/goldeneye-pc-port`.
+
+</div>
+
+What the release actually installs is covered on [Security status](security.md);
+how faithfully it tracks the N64 game, on [Fidelity status](fidelity.md).
 
 ## See it running
 
-<p align="center">
-  <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 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.4.0 intro attract)">
-    <div><small>Dam</small></div>
+<div class="viewer" id="viewer">
+  <div class="vbar">
+    <span class="dots"><i></i><i></i><i></i></span>
+    <span class="lbl">viewer &mdash; in-engine captures, 3840&times;2160</span>
+    <span class="idx" id="vIdx">1 / 14</span>
   </div>
-  <div style="width:32%;text-align:center;margin:4px">
-    <img src="img/shots/shot-03.jpg" width="100%" alt="In-engine: Runway (v0.4.0 intro attract)">
-    <div><small>Runway</small></div>
+  <div class="vstage">
+    <img id="vImg" src="img/shots/feature-splitscreen.jpg" alt="GoldenEye 007 PC port — 2-player split-screen multiplayer, in-engine capture">
+    <button class="vbtn prev" id="vPrev" aria-label="previous capture">&#8249;</button>
+    <button class="vbtn next" id="vNext" aria-label="next capture">&#8250;</button>
   </div>
-  <div style="width:32%;text-align:center;margin:4px">
-    <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-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-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-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-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.4.0 intro attract)">
-    <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.4.0 intro attract)">
-    <div><small>Aztec</small></div>
-  </div>
-  <div style="width:32%;text-align:center;margin:4px">
-    <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-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>
-
-More captures may land here as playtesting continues.
+  <div class="vcap"><span id="vCap">2-player split-screen &mdash; v0.5.0</span></div>
+</div>
 
 ## Play it, or take it apart
 
 - **Try it yourself**: grab a bundle above, bring your own ROM, and play the
-  campaign. It's an early cut for exactly this: if something breaks, an
+  campaign. It's a pre-1.0 build for exactly this: if something breaks, an
   [issue](https://github.com/jkdansereau/goldeneye-pc-port/issues) with what
   you were doing is genuinely useful.
 - **Read the code**: the game logic in `src/` is unmodified decompilation;
@@ -163,57 +182,111 @@ 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.
-- **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.
+- **AI disclosure**: development here used AI coding agents — Claude Code
+  plus a local open-weight model on a single RTX 5090, directed by one person
+  in their spare time. The project is as much a study of that process as it
+  is a port; the write-up records what happened and takes no position for or
+  against using LLMs on a project like this. See [the full
+  write-up](dev/agentic-development.md) — the setup, timeline, handoff
+  workflow, and an honest account of what did and didn't work.
 
 ## How it works
 
-The R4300 game code is compiled completely unmodified; the decompilation's
-control flow is ground truth. The N64's Reality Signal Processor, the graphics
-coprocessor that builds and executes each frame's display list, is emulated in
-software: the port interprets the GBI stream the game emits and translates it
-to OpenGL, bypassing the RDP entirely. Everything else that would touch N64
-hardware (video, audio, input, timers, save storage) is shimmed in a small
-dedicated layer, following the architecture of the Perfect Dark PC port from
-the same Rare engine family. Full detail: [Internals](internals.md); the bug
+The R4300 game code's logic and control flow are the decompilation's, and
+remain the reference we preserve. The port's changes inside `src/` are few in
+kind and each is gated behind `#ifdef PORT`: mechanical 32→64-bit
+pointer-width fixes, a couple of approved timing fixes, and the opt-in
+*All unlocked* and *Skip intro* hooks. The N64's Reality Signal Processor
+(RSP), the graphics coprocessor that builds and executes each frame's
+display list, is emulated in software: the port interprets the graphics
+command stream (GBI) the game emits and translates it to OpenGL, bypassing
+the RDP entirely. Everything else that would touch N64 hardware (video,
+audio, input, timers, save storage) is shimmed in a small dedicated layer,
+following the architecture of the Perfect Dark PC port from the same Rare
+engine family. Full detail: [Internals](internals.md); the bug
 catalogue: [Porting notes](porting-notes.md).
 
-## Honest status
-
-- 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
-[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
 
-- [The two-agent development case study](dev/agentic-development.md): goal, setup, timeline, the handoff workflow, and an honest assessment of what did and didn't work.
-- [Development process](dev-process.md): how work was scoped, partitioned, and budgeted across agents; the finding-log discipline.
-- [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.
+The technical docs live on the [Documentation](documentation.md) page — the
+architecture, the N64→PC bug catalogue, and how the project is developed.
+[Building](building.md) covers building and running from source.
+
+<script>
+  // console-viewer carousel: one media slot, cycle the captures. Vanilla JS.
+  (function () {
+    var slides = [
+      { src:"img/shots/feature-splitscreen.jpg", cap:"2-player split-screen — v0.5.0" },
+      { src:"img/shots/feature-options.jpg", cap:"PC options menu, custom crosshair colour — v0.5.0" },
+      { src:"img/shots/shot-01.jpg", cap:"Dam — v0.5.0 intro attract, 4K" },
+      { src:"img/shots/shot-03.jpg", cap:"Runway — v0.5.0 intro attract, 4K" },
+      { src:"img/shots/shot-04.jpg", cap:"Surface — v0.5.0 intro attract, 4K" },
+      { src:"img/shots/shot-09.jpg", cap:"Frigate — v0.5.0 intro attract, 4K" },
+      { src:"img/shots/shot-11.jpg", cap:"Surface 2 — v0.5.0 intro attract, 4K" },
+      { src:"img/shots/shot-16.jpg", cap:"Statue — v0.5.0 intro attract, 4K" },
+      { src:"img/shots/shot-20.jpg", cap:"Archives — v0.5.0 intro attract, 4K" },
+      { src:"img/shots/shot-21.jpg", cap:"Cradle — v0.5.0 intro attract, 4K" },
+      { src:"img/shots/shot-24.jpg", cap:"Aztec — v0.5.0 intro attract, 4K" },
+      { src:"img/shots/shot-27.jpg", cap:"Control — v0.5.0 intro attract, 4K" },
+      { src:"img/shots/shot-28.jpg", cap:"Streets — v0.5.0 intro attract, 4K" },
+      { src:"img/shots/shot-29.jpg", cap:"Jungle — v0.5.0 intro attract, 4K" }
+    ];
+    var img = document.getElementById("vImg"),
+        cap = document.getElementById("vCap"),
+        idx = document.getElementById("vIdx"),
+        i = 0;
+    function show(n) {
+      i = (n + slides.length) % slides.length;
+      img.src = slides[i].src;
+      img.alt = "GoldenEye 007 PC port — " + slides[i].cap +
+                ", in-engine capture, 3840×2160";
+      cap.textContent = slides[i].cap;
+      idx.textContent = (i + 1) + " / " + slides.length;
+    }
+    document.getElementById("vPrev").addEventListener("click", function () { show(i - 1); });
+    document.getElementById("vNext").addEventListener("click", function () { show(i + 1); });
+    document.addEventListener("keydown", function (e) {
+      if (e.key === "ArrowLeft") show(i - 1);
+      else if (e.key === "ArrowRight") show(i + 1);
+    });
+    show(0);
+  })();
+</script>
+
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "Software",
+  "name": "GoldenEye 007 PC Port",
+  "genericName": "Native PC port of a Nintendo 64 game",
+  "softwareName": "GoldenEye 007 PC Port",
+  "category": "GameCategory",
+  "description": "A native PC build of GoldenEye 007 (Rare, 1997, Nintendo 64), compiled from the n64decomp/007 decompilation with the N64's RSP emulated in software. Ships no ROM and no game assets; you supply your own.",
+  "softwareVersion": "0.5.0",
+  "datePublished": "2026-10-05",
+  "dateModified": "2026-10-07",
+  "operatingSystem": ["Windows", "Linux", "Steam Deck"],
+  "downloadUrl": "https://github.com/jkdansereau/goldeneye-pc-port/releases",
+  "distributionType": "Software-Offline",
+  "officialDistribution": {
+    "@type": "SoftwareDistribution",
+    "downloadUrl": "https://github.com/jkdansereau/goldeneye-pc-port/releases",
+    "distributionLicense": "MIT"
+  },
+  "license": "https://opensource.org/licenses/MIT",
+  "isFreeApplication": true,
+  "url": "https://jkdansereau.github.io/goldeneye-pc-port/",
+  "sameAs": "https://github.com/jkdansereau/goldeneye-pc-port",
+  "publisher": {
+    "@type": "Person",
+    "name": "jkdansereau",
+    "url": "https://github.com/jkdansereau"
+  },
+  "gallery": [
+    "https://jkdansereau.github.io/goldeneye-pc-port/img/shots/shot-28.jpg",
+    "https://jkdansereau.github.io/goldeneye-pc-port/img/shots/shot-01.jpg",
+    "https://jkdansereau.github.io/goldeneye-pc-port/img/shots/shot-24.jpg"
+  ],
+  "alternateName": "GoldenEye 007 (Nintendo 64, 1997) on the PC"
+}
+</script>

docs/input-and-aim.md

@@ -0,0 +1,32 @@
+---
+title: Input and aim
+description: How the GoldenEye 007 PC port maps keyboard, mouse and modern controllers onto the N64's controller, including mouse aim.
+date: '2026-10-05'
+modified_time: '2026-10-05'
+---
+
+## Input and aim
+
+`port/src/input.c` maps **SDL2 keyboard, mouse and gamepad** events into the
+N64's own controller structs, so the game's input code runs unmodified.
+
+**Mouse aim** is modelled on the *GEPD* mouse-injector behaviour that the 1964
+"GoldenEye/Perfect Dark Edition" bundle used — an **independent
+reimplementation** of that behaviour (not derived code), credited to its
+author in the README. It comes in two styles, the N64's own aim feel or a
+centered FPS-style, with per-device sensitivity, smoothing and Y-inversion.
+
+**Controllers:** modern pads get a dual-stick layout, deadzones,
+sensitivity, southpaw, trigger thresholds, Rumble-Pak vibration, and
+PlayStation/Nintendo button names. **Everything is rebindable** — keyboard,
+mouse and each controller — in the F10 options overlay. Split-screen needs one
+controller per extra player.
+
+**Control style** offers **Ext** (this port's scheme) or **Original**, the
+game's own N64 styles 1.1–2.4, chosen per seat. New profiles start with
+**Look ahead** off (it fights mouse look) and **Crouch** on Toggle; the
+game's own Look up/down row was removed in favour of **Invert look** on the
+Mouse and Controller pages.
+
+*More: [internals](internals.md) §7 (input & saves); the aim model's
+provenance is the D194 lineage in `port/src/input.c`.*

docs/internals.md

@@ -3,14 +3,14 @@ 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
+## 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
 > external references. The phased plan in section 8 is largely done through
 > Phase 2; for current status see the
 > [README](https://github.com/jkdansereau/goldeneye-pc-port#status) and
-> [`dev/LEVEL-STATUS.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/LEVEL-STATUS.md);
+> [`ROADMAP.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/ROADMAP.md);
 > for the blow-by-blow finding log see
 > [`dev/findings.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/findings.md).
 
@@ -382,6 +382,51 @@ sync/flush) is shared.
     rumble/mempak.
   This is simpler than a full Memory Pak/PFS emulation.
 
+* **F10 settings overlay: mouse and scrolling** (`port/src/optionsoverlay.c`,
+  `port/src/input.c`; D544, D314, D304):
+  * *Cursor.* `inputSuspendForOverlay()` (`input.c`) drops relative-mouse
+    grab and calls `mouseRequestCursor(1)`. With `Input.CrosshairCursor` on
+    (default, D555) `inputApplyMouseRequests()` (host thread) then hides the OS
+    cursor while the overlay is open and `drawCrosshairPointer()` in
+    `optionsoverlay.c` draws the game's own `crosshairimage` sprite at the mouse,
+    last in the overlay DL, at the game's on-screen size; the front end's own
+    crosshair keeps tracking the mouse (D519) and the pointer is drawn exactly
+    over it (`inputFrontEndCursorUiFrac()`), so only one shows; in a level it
+    follows the OS mouse. With the option off the OS arrow shows over the box. One owner of the cursor state (no show/hide race).
+  * *Hover vs selection.* `overlayHandleInputLocked()` maps the pointer to a
+    visible row with `overlayRowAtY()` (follows the eased scroll position, so
+    a click lands on the row it visually covers). Hover sets `s_hover` only
+    while `s_mouseActive` (mouse moved or clicked); it is a focus cue, never
+    the selection. The tip line (`helpVis` in the emit path) follows the
+    hovered row while the mouse is in use, else the selected row. The
+    wheel clears `s_mouseActive`.
+  * *Clicks.* Left-click on a row selects it; headers, links and Back act on
+    the whole row, otherwise only a click in the control span to the right of
+    the name changes the setting (toggle/cycle, open a dropdown, start a
+    binding capture, or set + drag a slider). With a dropdown open
+    (`s_ddRow >= 0`) it owns the pointer: hover picks, click confirms, click
+    outside or right-click cancels. Right-click elsewhere = Esc/back (closes a
+    dropdown first, then one page, then the overlay). `s_rmbBlock` holds that
+    off until release after a binding capture, so a right-click just bound
+    does not also back out.
+  * *Scrolling.* Long pages scroll as a window
+    over the visible-row list (`s_visIdx`/`s_visN`, first displayed entry
+    `s_scroll`, section header pinned). `overlayUpdateScroll()` moves the
+    window only when the selection leaves it (D304). The wheel arrives on the
+    host thread: `optionsOverlayScroll()` only queues notches in
+    `s_wheelPending` (SDL atomic, D314) and `overlayApplyWheel()` applies them
+    on the scheduler thread. The drawn position `s_scrollF` eases toward
+    `s_scroll` each emit (snaps on page change via `s_scrollSnap`).
+  * *Scrollbar (D556).* A page that overflows (same test as the "^ v" title
+    marker) draws a thin track + thumb in the card's right margin
+    (`overlayScrollbar()`: x = right-7..right-4, clear of the value text that
+    ends at right-10); thumb size = visible/total rows, position from
+    `s_scrollF`. Mouse: a press on the thumb drags it, a press on the track
+    pages up/down; both call `overlayScrollTo()`, which sets `s_scroll` and
+    moves `s_sel` into the window (like the wheel; otherwise
+    `overlayUpdateScroll()` would snap back). A scrollbar press never reaches
+    the row-click path.
+
 ---
 
 ## 8. Recommended plan
@@ -411,7 +456,7 @@ sync/flush) is shared.
 * Bring in the PD `fast3d` (gfx_pc / gfx_opengl / gfx_cc / gfx_sdl2).
 * Verify the custom CC/RM modes against `gmain.s`; add a `G_SETTEX` decode
   path only if it turns out to be used (see §5; it appears unused).
-* Port `pdsched.c` (GE variant) to drive the software RSP.
+* Port `pdsched.c` (GE variant) to drive the software RSP. *(Done differently: GE compiles its real `src/sched.c` and shims its hardware leaf calls in `port/src/libultra.c`, which runs the software RSP inline — see the CMakeLists.txt `SRC_ENGINE` comment.)*
 * Goal: render the title screen / first level.
 
 ### Phase 3: Audio + input

docs/porting-notes.md

@@ -19,14 +19,14 @@ good that you are looking at one of these.
 
 ## Contents
 
-- [A. Pointer-width struct growth (32→64); the dominant class](#a-pointer-width-struct-growth-3264--the-dominant-class)
+- [A. Pointer-width struct growth (32→64); the dominant class](#a-pointer-width-struct-growth-3264-the-dominant-class)
 - [B. 16-byte PC `Gfx` / `Vtx` vs 8-byte N64](#b-16-byte-pc-gfx--vtx-vs-8-byte-n64)
 - [C. Big-endian rodata / ROM data read on little-endian PC](#c-big-endian-rodata--rom-data-read-on-little-endian-pc)
 - [C2. Port-layer / SDL shims](#c2-port-layer--sdl-shims)
 - [D. N64 hardware idioms fast3d does not emulate](#d-n64-hardware-idioms-fast3d-does-not-emulate)
-- [D2. The HUD/model "X-mirror"; RESOLVED](#d2-the-hudmodel-x-mirror-d114d116--resolved-it-was-an-upside-down-capture)
+- [D2. The HUD/model "X-mirror"; RESOLVED](#d2-the-hudmodel-x-mirror-d114d116-resolved-it-was-an-upside-down-capture)
 - [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)
+- [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)
@@ -290,6 +290,20 @@ The offline model converter sizes each record's trailing arrays from its count f
 
 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.
 
+**A1 cross-tag (D441, 2026-09-30):** the 32→64 widening of `(u32)`/`(s32)` *pointer casts* (rebase arithmetic on RAM copies, segment/anim-table bases) is the same class. Pattern: `#ifdef PORT` `(uintptr_t)` arm + untouched `#else`. Exception: `(s32)&ANIM_DATA_x` is an intentional offset (D34: 4 GiB-aligned base, low 32 bits = segment offset) — widen only the *base* it is added to, never the offset. Census of the remaining ~185 sites in the touched files is still owed (D441).
+
+**A1 cross-tag (D457, 2026-09-30): a pure pointer-width retype can change behaviour by shifting the allocation layout.** Widening `struct player` (+32 B) / `struct Model` (+16 B, inline x4 in player) flipped the default-boot file-select menu to an all-black frame (no crash, identical log) while `-level_09` was fine; allocating the player block at its old size restored it. The menu depends on the MEMPOOL_STAGE layout (player block precedes `g_GfxBuffers[0]`, D98) through something address-sensitive. After any struct widening, run the default-boot menu with a `GE_PCDUMP` frame (not only a level) and check the frame extrema, not just rc. Also: a hardcoded record stride (`vtxstore.c` `n * 0x14` for a record that is 0x18 bytes on x86-64) is a silent overrun that widening makes worse; grep literals near allocs of retyped structs.
+
+**A1 cross-tag (D441, 2026-10-03): the read side, `s32` back to a pointer, sign-extends.** An arena pointer stored in an `s32` (a local, a global, a field, a function parameter named like an id: `pathid`, `opcode`, `resolution`, `helddst`) truncates harmlessly below 4 GiB, but `(T *)s32` and the implicit `s32` -> `T *` conversion (a `-Wint-conversion` "makes pointer from integer", no cast to grep for) sign-extend bit 31. Invisible while the arena sits below 0x80000000; the tier-1 test build (`GE_HIGHARENA_BASE=0x90000000`) turns each one into a 0xffffffff9xxxxxxx fault, in crash order. Fix: `(T *)(uintptr_t)(u32)(EXPR)` under `#ifdef PORT`. Also grep the port layer for address-range **upper bounds**, not only base literals: fast3d's DRAM-vs-C-array texture test ended at a `0x90000000` literal, so with the arena moved there every DRAM texture was bswapped (mirrored texel pairs, no crash). Ranges must come from `portaddr.h` (base + `PORT_DRAM_SIZE`). And pin `GE_RSEED` + `GE_INPUTSCRIPT` before diffing level frames between builds: unseeded runs differ every frame.
+
+**A1 cross-tag (D588, 2026-10-07): re-basing a LIVE host pointer through `portN64ToHost` mis-maps a native (out-of-window) pointer that *collides* with the D131 image-rel range.** `texSetBitstring` took the compressed-source cursor as an `s32` and re-based it (`portN64ToHost((u32)pos)`) — correct for an in-window (macOS) pointer whose low 32 bits are a genuine N64 offset, but wrong for a **native** pointer (e.g. the Windows libwinpthread worker-thread stack at `0x618d…`–`0x620d…`, whose low 32 bits fall in `[0x40M,0x70M)`): `portN64ToHost` maps it onto the PE image (`imagebase + (low32 − 0x40M)`), landing past the image end → deterministic SIGSEGV in `texReadBits`. Rule: a *stored N64 u32 field / DRAM address* is the legitimate `portN64ToHost` re-base input; a *live host pointer* must be carried at full pointer width (take the parameter as `u8 *` / `void *` under `#ifdef PORT`) so no truncate-then-rebase happens at all. Grep for `portN64ToHost((u32)<live-ptr-param>` — the feeder `rzipGetSomething()` (truncating `s_rz_nextin` to `s32`) was the second site. §F D588.
+
+**A1 cross-tag (D590, 2026-10-08): the same collision, one site up the call chain, and the general diagnostic tell.** `load_bg_file` reads its stack `header` array through `PORT_N64PTR(void, ptr_bg_data)` where `ptr_bg_data` is a full-width host `bg_addr_t` (D457) — the truncate-then-re-base maps the bg-load worker stack onto the PE image and faults at `header[1]`. **Diagnostic tell for the whole class: if the fault address equals `imagebase + (low32(faulting pointer) − 0x40000000)` — i.e. the top 32 bits were dropped and the remainder re-based into the D131 image-rel window — the bug is a live host pointer fed through `portN64ToHost` / `PORT_N64PTR`, not a game-logic fault.** The check is a one-line arithmetic compare against the crash log's FAULT ADDR (Windows: `ge007.crash.log` prints both; `R8`/`RSP` in the same record give the raw pointer) — far cheaper than rebuild-and-run hypothesis testing. `PORT_ADDR_STRICT` does NOT catch this variant: strict only rejects u32s that map to no known N64 region, and a colliding in-window low32 passes it (a clean strict run is path-coverage evidence only). The legitimate `PORT_N64PTR` operand is a *stored N64 u32 field or DRAM address* (ROM-serialized records); a stack array, a `mempAllocBytesInBank` result, or any D457-retyped host pointer must not go through it. §F D590.
+
+**A1 cross-tag (D591, 2026-10-08): host-space vs N64-raw-space mixup in a range *classification* test (not a rebase) — bswaps every in-window source on the `PORT_ADDR_BASE != 0` platform.** `gfx_tex_source_is_c_array` (`port/fast3d/gfx_pc.cpp`) stripped `PORT_ADDR_BASE` first (putting the pointer in N64 raw space, `0x70xxxxxx`), then compared against **host-space** bounds — `PORT_DRAM_V1_BASE`/`PORT_DRAM_K0_BASE` are `PORT_ADDR_BASE + 0x70000000`/`+ 0x80000000` (`port/include/portaddr.h`), i.e. `0x100070000000` on arm64 macOS. At `PORT_ADDR_BASE == 0` (x86_64) the two spaces coincide and the test is accidentally correct; at 16 TiB the raw pool offset is *above* the raw cart window and *below* the host-space DRAM bases, so every DRAM and cart texture source fails all three range checks and falls through to the C-array default — `gfx_tex_normalize_source` then hands fast3d a `PD_BE32`-swapped copy of the whole texture pool (the D589 confetti / D219-M-114 pink-HUD symptom class; a clean rev32 in the import-time dumps while the decode-time pool stays byte-identical). **Diagnostic tell: a texture-format-dependent byte-reversal that appears on *one* platform, with the pool-write side proven clean (decode-time dumps byte-identical) — check the platform-gated *classification* of the source address, not the writer; and on any `PORT_ADDR_BASE != 0` build, grep for range tests that strip the base before comparing to `PORT_DRAM_*` bounds (or, conversely, compare a raw offset to host bases). The test must use one space end to end: the host pointer against host-space bounds, or the raw offset against raw bases.** §F D591.
+
+**A1 cross-tag (D595, 2026-10-08): the simplest member — a plain `(s32)` *read* of a live host pointer as the rebase *base* (no `portN64ToHost`, no classification), silently identity on x86_64 and wrong at `PORT_ADDR_BASE != 0`.** `initResolveAnimTable` (`src/game/initactorpropstuff.c`) resolves the `StruckAnim` reaction tables (`death_stagger`, `g_HitReactionTable[*].{death,flinch}Anims`) as `struck_anim = base + offset`, where `base` is the live host pointer `ptr_animation_table` (`mempAllocBytesInBank(…, MEMPOOL_PERMANENT)`) and `offset` is a small N64 `PTR_ANIM_*` (e.g. `0x1C`). The PORT path read the base as `(*((s32 *)entries))`: on x86_64 the PERMANENT bank is s32-low (`0x70xxxxxx`) so the 4-byte read is identity; on arm64 macOS (`PORT_ADDR_BASE` = 16 TiB, `0x10007xxxxxx`) it drops the high 32 bits, so every `struck_anim` landed in bogus low memory and the first AI hit/stagger/death reaction (`triggered_on_shot_hit → modelSetAnimation2 → modelSetAnimFrame` deref of `anim->unk07`) SIGSEGV'd. **Diagnostic tell: an arm64-only NULL/garbage-pointer fault in an *animation / table-resolution* path where the pointer is `base + small-rom-offset` and `base` is a `mempAllocBytesInBank` result — grep the `(s32)`/`(u32)` reads of such bases (the sibling sites `bondhead.c` / `bondview2.c` already use a full-width `(uintptr_t)&ptr_animation_table->data`; `initResolveAnimTable` was the one still on the `(s32)` form).** Fix: read the base at full width (`(*entries).struck_anim`), add the offset as `u32`; identity on every `PORT_ADDR_BASE == 0` platform. §F D595.
+
 ## B. 16-byte PC `Gfx` / `Vtx` vs 8-byte N64
 
 Any buffer reservation, `memcpy` size, slot stride, or pool budget
@@ -310,6 +324,9 @@ expressed in N64 `Gfx`/`Vtx` units is **half-size** on PC.
   `(word >> (8*(3-i))) & 0xff`). `gdl++` (advances by `sizeof(Gfx)`) is already
   correct. Watch `(s32)ptr` truncation in vtx-base math and `x | 0x80000000`
   KSEG0 folds (identity on PC; just drop the OR, and guard segmented w1).
+  Also raw-index **writes** into static DLs: D465 (`unk_092E50.c` water
+  controller patched `((u32*)dl)[8]`, meaning N64 `Gfx[4].w0`, which hit
+  `Gfx[2]` on PC; use `dl[n].words.w0` instead).
   Instances: `bgTestHitOnObj` (`propobj.c`, FIXED); `bgTestRayIntersectionInRoom`
   + `bgTestBulletHitBackground` tail (`bg.c`, D154; ported M-28, re-audited +
   bug-fixed M-30, playtest-gated).
@@ -580,6 +597,30 @@ through a converter or a runtime bswap fixup reads scrambled.
 
 ## C2. Port-layer / SDL shims
 
+- **Darwin assembly uses Mach-O symbol spelling.** GAS absolute symbols that
+  are `.global foo` / `.set foo, address` on ELF/PE must become `.globl _foo`
+  / `.set _foo, address`; Darwin also rejects the ELF `.section .data`
+  spelling used by these symbol-only files. Generate transformed build-tree
+  copies rather than changing the cross-platform source files (D294).
+- **Darwin GCC cannot lower ELF-style `#pragma weak alias = target`.** It can
+  ICE in `assemble_alias`; compile generated copies with those pragmas removed
+  and provide Mach-O indirect symbols (`.set _alias, _target`) separately
+  (D294).
+- **Mach-O's default `__PAGEZERO` reserves the entire low 4 GiB.** A build
+  can compile and link successfully yet fail every fixed N64 mapping at
+  runtime (`0x10000000`, `0x70000000`, `0x80000000`). Link with
+  `-Wl,-pagezero_size,0x10000` so null-page pointers remain protected while
+  the cartridge and DRAM ranges are available (D294).
+- **Darwin has no `MAP_FIXED_NOREPLACE`; a fixed-address hint can relocate.**
+  Once `__PAGEZERO` is deliberately bounded below the cart range, use
+  `MAP_FIXED` for the `0x10000000` cartridge mapping. Retaining the advisory
+  hint silently falls back to a heap ROM and later crashes on direct absolute
+  ROM-symbol reads (D294).
+- **AppKit event polling is main-thread-only.** This port has both a host-main
+  `videoPumpEvents()` loop and fast3d's render-thread event pump. The latter
+  must be disabled on macOS or `SDL_PollEvent` raises
+  `NSInternalInconsistencyException`; the main-thread loop already handles
+  the complete event set (D294).
 - `#include <PR/os.h>` in a port `.c`/`.h` that also sees `<errno.h>`
   breaks: `OSContStatus`/`OSContPad` have a `u8 errno;` field vs errno.h's
   macro. libultra.c wraps the include in `#pragma push_macro("errno")` /
@@ -633,6 +674,9 @@ through a converter or a runtime bswap fixup reads scrambled.
 
 - **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`).
+- **A first-run-only preset is skipped forever by any earlier launch that created the ini, and window keys are not an "untouched" signal (D283).** Seeding values *before* `configLoad()` only works when no `ge007.ini` exists; one launch in a different environment (SteamOS Desktop Mode has no `STEAMOS`) writes a plain ini and the preset never runs. Apply presets *after* the load, record a one-shot flag key, and gate on keys the user must change deliberately (`Video.Fullscreen`, `Window.Maximized`) — `Window.Width/Height` are rewritten from the live window on every clean exit (`videoSaveWindowState`), so "still at default" never holds for them.
+
+**SDL3 on macOS: a GL swap with VSync can wait forever (D952).** SDL3's Cocoa backend implements the GL swap interval itself: `SDL_GL_SwapWindow` waits, with no timeout, for a tick from a `CVDisplayLink` that SDL creates and starts once, with the context. If that link never runs (seen when the game starts while the display is asleep), the first swap never returns: black window, zero frames, every other thread waiting behind the render thread. Tells: `sample` shows `Cocoa_GL_SwapWindow -> SDL_WaitCondition*` on the render thread and the process has no `CVDisplayLink` thread. Fix pattern: leave SDL's interval at 0 and set `kCGLCPSwapInterval` on the context with `CGLSetParameter`, which waits in the driver (SDL2's behaviour). Reproduce with `pmset displaysleepnow` before launching.
 
 ## D. N64 hardware idioms fast3d does not emulate
 
@@ -1013,7 +1057,10 @@ for (s = SP_LEVEL_EGYPT; s >= SP_LEVEL_DAM /* == 0 */; s--)   // never ends
 
 - Symptom: a silent hang (kernel-heartbeat stall, no crash log) inside a
   loop over an enum range; the counter holds a huge value in gdb.
-- Instances: **D142**; `LEVEL_SOLO_SEQUENCE` in
+- Instances: **D417** (`enum PROP`: `getPropForHeldItem()` returns -1 for the
+  fist and callers test `prop >= 0` -> unsigned enum lets -1 through ->
+  `modelLoad(-1)` crash in any 2P+ stage; sentinel `PROP__PORT_SIGNED`);
+  **D142**; `LEVEL_SOLO_SEQUENCE` in
   `fileGetHighestStageDifficultyCompletedForFolder` froze the SELECT FILE
   screen. `DIFFICULTY` was already safe (`DIFFICULTY_MULTI = -1`).
 - Fix: add a never-used negative sentinel enumerator under `#ifdef PORT`
@@ -1098,6 +1145,13 @@ past it (walk off the end).
   links 0x60 bytes *before* `legalpage_text_array` → only line 1 renders
   (== the D76 "disclaimer half-drawn" bug; it was never an image-table
   issue). Fix: `#ifdef PORT` uses `array + ARRAY_COUNT(array)`.
+- Instance: **D491**; the same assumption in struct reads, not loop bounds:
+  `*(coord3d *)&D_80044904` (bg.c portal bbox seeds) and
+  `*(coord3d *)&D_80035EA4` (gunfire.c casing rot) read three separately
+  declared scalars as one struct. mingw emits such runs in **reverse** order,
+  so the read picks up a different neighbour. `-Warray-bounds` flags these
+  ("partly outside array bounds of 's32[1]'"); confirm with `nm -n` on the
+  exe. Fix: `#ifdef PORT` reads each named global.
 - Grep for `= &` / `(TYPE *)&` on the RHS of a loop-terminator compare, and
   any `for`/`while`/`do` whose end pointer is the address of a *different*
   symbol than the one being iterated.
@@ -1201,6 +1255,11 @@ and turns every such overrun into a fatal `*** stack smashing detected ***`
   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.
+- Instance (D420): `mpmenu.c` `mp_watch_menu_display` `char rankbuffer[4]`
+  receives "Rank: 1st" / "P<n> KILLS"; GCC puts `scores[4]` next to it, so
+  the MP Scores page printed the rank text's bytes as numbers (1932599354 =
+  ": 1s"). Tell: a displayed number whose hex is printable ASCII from a
+  neighbouring string. Widened to `[64]` under `#ifdef PORT`.
 - 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
@@ -1250,6 +1309,14 @@ 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.
 
+Second instance (D479): the `GE_STARTMP` split-screen harness skipped the
+file-select screen, whose init sets `selected_folder_num = -1` for an MP
+launch. The harness left the boot default `FOLDER1`, so every stage load ran
+`fileLoadSettingsForFolder(0)` against an unvalidated (all-zero) `saves[]`
+record: options 0, i.e. ammo counter, sight and auto-aim off in harness
+matches only. A real menu launch never applies a Bond file in MP. Symptom
+looked like a HUD bug; the tell was that it never reproduced from the menu.
+
 ## 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`-
@@ -1294,6 +1361,7 @@ GE on N64 renders gameplay at ~20–30 fps, so `g_ClockTimer` (= `speedgraphfram
 - **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.
+- **Frame-counter gates (D427/D451):** a gate that reads the current `g_ClockTimer` to rescale a frame counter (`88C % (rate*(clk>=2?1:2))`) is only exact at steady pacing. Prefer the tick accumulator already kept beside the counter (`field_890`) and test for a threshold *crossing* (`t/P != (t-clk)/P`): stateless and exact on average at any pacing.
 
 ## 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)
 
@@ -1346,6 +1414,83 @@ 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.
 
+## D16. Split-screen: port-side "one full-screen viewport" assumptions break 2P+ (D418)
+
+Two traps from the #99 split-screen bring-up:
+
+- **Safe-area crop (`gfx_adjust_viewport_or_scissor`) caches the LAST SP
+  viewport's Y range and stretches it over the whole window.** Right for the
+  solo 220-line viewport, wrong for 2P+ (each player's viewport is a sub-rect):
+  every player's view filled the window and the last-drawn (order is shuffled
+  per frame, `get_nth_player_from_shuffled`) covered the rest -> alternating
+  full-screen flicker. Fix = `gfx_set_split_screen()`. Any new port feature that
+  assumes "the viewport is the screen" needs the same 2P+ gate.
+- **Per-frame port hooks must sit on the path frames really take.** The
+  scheduler calls `gfx_run` directly (`port/src/libultra.c`), NOT through
+  `videoSubmitCommands`; a hook placed only in the latter silently never ran.
+  Log once on the first state change when adding such a hook.
+
+Debug recipe that found it: capture consecutive frames after the stage starts
+(GE_PCDUMP range, or the harness `GE_STARTMP=<players>[,<stageIdx>]` +
+`GE_MPVIRT=<players-1>` to start a match with no one at the menu) and look at
+them — the symptom was obvious in one montage.
+
+## D17. Un-stubbing a `-1` sentinel re-activates every dormant consumer of the value (D431/D434)
+
+A port stub that forces a value to `-1` (D154 `texnum`, D135) can hide latent layout bugs in its other readers. When restoring a real value, grep ALL readers of the field first and check each for raw-layout reads and table-bounds assumptions. Instance: D431 made light-fixture hits return real image ids, which reached `chrprop.c`/`propobj.c` reading `((u8*)&g_Textures[n])[0] & 0xf` as a hit type -- on PC byte 0 is the low byte of `dataoffset` (LE bitfield layout, D67), so it indexed `g_HitTypeSounds[13]` with 0..15. Use the `.hitTexture`/`.hitSound` bitfields (as `chr.c` does).
+
+## D18. A port feature that widens a shared range (draw distance, FOV) leaks into gameplay through every reader of the state it widened (D466)
+
+`Video.DrawDistance` scaled the one far-clip value that both the renderer and gameplay read, so `room_rendered`, `PROPFLAG_ONSCREEN`, `CHRFLAG_HAS_BEEN_ON_SCREEN` and the fog intensities all grew with it, and AI scripts ("on screen", "seen", target-in-sight, spawn out of view) fired earlier than on N64. Rule: when adding a "see farther / wider" option, grep every reader of the state it feeds and split render from gameplay; the render consumer keeps the extended value, the gameplay readers get a stored copy computed at the authored value.
+
+- **Tell:** `PROPFLAG_ONSCREEN`-style flags are dual-use (render gate AND AI input), so never gate the flag itself; store a separate verdict bit.
+- **Techniques that worked:** run the original traversal twice with a port flag that pins the single far read (a static read, never `viSetZRange`) and snapshot the result; keep the "gameplay verdict" in an unused bit of a u8 flag byte (`prop->flags & 0x80`) written by every setter of the dual-use flag; store the authored fog values at load time instead of recomputing from the live multiplier.
+- **Triage trap:** check whether a `PROPFLAG_*` hit is on `prop->flags` (runtime u8) or on `obj->flags` / pdef flags (u32 definition bits) before treating it as a reader (`propobj.c:8417`, `prop.c` 233-467 are the latter).
+- **Remaining class member:** FOV/widescreen widening of `camIsPosInScreen` and `c_lodscalez` (D222).
+- **Fixed-size per-frame budgets are readers too (D500):** the dyn.c vtx pool (`-mvtx`, as low as 40 KB) is bump-allocated with no bounds check and sized for what the N64 could see; widened views overran it (Aztec triangles). Look for unchecked per-frame pools sized by per-level tokens when a widening feature shows corruption only in busy scenes.
+- **A pixel ratio is not a fog factor (D503):** "~97% fogged" was a pixel-colour ratio; derive any fog snap cutoff from measured vertex fog, not from it. And before blaming fog for a far object, do the cheap 4:3 + N64-FOV test: if it vanishes, the cause is the widened frustum, not fog.
+- **Reveal, not regression (D503):** the N64's 16-bit framebuffer hid 2-5 level differences (near-full fog against haze); 32-bit output shows them, plus the room-scissor edges of nearly fogged objects. Measure pixel values against the fog colour before blaming draw distance.
+
+## D19. A "click after the shot" report needs the trigger-hold duration, not just the state machine (D433/D467)
+State-machine audits of a gun's fire/dry-fire path (GE: `gunTickHandState`, CLICKY weapons) are tick-driven and match the console at any tick/frame ratio; an extra click/sound that appears "with the shot" is usually the trigger still being down when the recoil state ends (about 14 ticks for the Golden Gun). Measure with `GE_STARTWEAPON` + `GE_INPUTSCRIPT` holds of 4/9/16 frames and a `state/mag/88C/890/clk` log at the sound-play sites before suspecting the audio layer; and remember `GE_QUITFRAME` counts frames from boot, the level's `g_GlobalTimer` starts ~270 later.
+
+## D20. Running an RCP task inline on the scheduler thread delays retrace delivery (D481)
+The N64 scheduler (`src/sched.c` `__scMain`) both starts RSP/RDP tasks and forwards each VI retrace to the game. On hardware the task runs on separate processors, so the scheduler is never busy. If the port executes the task synchronously inside `osSpTaskStartGo`, any retrace that arrives during it reaches the game late, and `boss.c`'s half-frame tick gate then skips the following retrace (33 ms frames). Tell: frame rate stuck below 60 at every graphics setting, moderate render and GPU times, and the lost frames failing the tick check (`skip_tick`), not the pending-gfx check. It only shows when the task takes a large fraction of a frame (slow hardware), so a fast dev box never sees it. Run hardware-side work off the scheduler thread and signal completion with the same events the hardware would.
+
+## D21. `gDPLoadBlock` with dxt = 0 depends on the RDP's odd-row TMEM read swap; static assets need it emulated, the tex.c pipeline must not get it (D75)
+
+The RDP swaps the two 32-bit halves of every 8-byte group on odd TMEM rows when *reading*, and compensates on *load* only when LoadBlock's dxt counter advances. A `gsDPLoadBlock(..., dxt = 0)` of a multi-row image therefore samples as "memory with odd rows pair-swapped". Rare's compiled-in assets that load this way (the Rareware logo's RAREWARE text, `DL_RAREWARETEXT`) are pre-swapped in the data and look scrambled ("interleaved/combed", identical at every texture-filter setting) if fast3d uploads them linearly. `tex.c` uses dxt = 0 for the whole runtime texture pipeline too, but there `texSwapAltRowBytes` was the matching pre-swap and D159 no-ops it, so those images are already linear. fast3d (`import_texture`) therefore swaps only dxt = 0 loads whose source is a compiled-in C array (`gfx_tex_source_is_c_array`). Generalisable tells: a texture that looks identically garbled at filter 0/1/2, interlaced along ROWS with a 2-texel horizontal shift, drawn from `assets/*.c`; decode the C array offline both ways before suspecting filtering/clamp. Counting how often a new texture-path branch fires on a level boot (a temporary env-gated log) caught a ~300-per-level over-reach before it shipped.
+
+## D22. Per-frame counters: gate them with `portN64FrameStep()` (D486)
+
+Decomp code that advances a counter once per *call* (per rendered frame) instead of by `g_ClockTimer` runs 2-3x faster in real time at the port's 1 tick/frame (and every frame when uncapped, `clk == 0`). D486 found three on the explosion/turret path: autogun shot counter (`unkAC++`), explosion part spawning, explosion/smoke shake decay. `port/include/porttick.h` `portN64FrameStep()` is the shared Rule-2 gate: true on every call at >= 2 ticks/frame (N64-identical), every second tick below, so the counter keeps the N64's 2-ticks-per-frame pace (the D427/D451 reference). If the gated counter also scales a per-event quantity by `g_GlobalTimerDelta` (autogun damage per shot), charge the full 2-tick frame on gated calls or the rate halves. Verify by A/B at `Video.FpsCap` 60 vs 30: the two must match. Any such gate is game logic and needs Rule-2 sign-off.
+
+## D23. Region bring-up: tooling and port code silently assume NTSC-U (D258)
+
+PAL/JP had never been built. What broke was all port-side: (1) asset emitters hard-coded `scripts/filelist.u.csv` (so on a PAL/JP ROM they would use US offsets with no error); (2) `romdata.c` treated "not PAL" as NTSC-U (rejecting a JP ROM's country byte); (3) port code referenced globals that exist only under a region-specific define (`LEFTOVERDEBUG` is US/JP-only), which surfaces as a PAL-only link error; (4) the decomp's PAL/JP filelists were incomplete and mislabelled. With a real ROM, prove every filelist row by bytes (same-name US file comparison, constant-shift search, header-walk for variable files) instead of trusting labels. Whenever port code touches a symbol inside a `#if` region block, check all three `REGION_DEFS` sets.
+
+## D24. Decomp out-of-bounds writes that the N64 stack layout absorbed (D490)
+
+Some decomp functions write past a local array in edge cases. On the N64, IDO's stack layout put a padding local (often a `pad[]` the decomp keeps for matching) right after the array, so the overflow was harmless. GCC lays the stack out differently, so the same write corrupts a live neighbour. D490: `sub_GAME_7F03ECC0` writes up to 6 entries into `s32 rem[4]` when an object's bbox is flat, overwriting `pts[0]` and giving every glass pane a phantom collision vertex (guards circled pads they could not reach). Tells: a bug that only appears for degenerate inputs (flat or zero-size boxes, coincident points); a value that is exactly 0 or a tiny denormal where a real number belongs; a `pad[]` local next to a fixed-size array in the decomp. Fix pattern: enlarge the array under `#ifdef AVOID_UB`, keep the original under `#else`, change no reads, so the result matches the N64's uncorrupted path.
+
+Also the read side: D496 (`generate_language_specific_text_for_weapon` strcat'd onto an uninitialised caller stack buffer for 3+ players; init under `AVOID_UB`).
+
+## D25. Cross-platform goldens: a fixed frame stem is only comparable at settled gameplay (D521)
+
+`GE_PCDUMP`/`GE_QUITFRAME` step the port's *sim* frame counter (`port/src/video.c:1406` `++frames`, one per `portRenderGfxTask()` at `port/src/libultra.c:1256`), and retrace messages are dropped at the posting site when the game's queue is nearly full (`port/src/libultra.c:753`), so a slow box stretches wall time without advancing `frames` -- frame stems are comparable, wall time is not. What is NOT comparable is any stem inside the intro flyby, whose settle point is wall-clock paced (D117): on a ~54 fps Linux box the flyby was still running at frame 900 (settles ~830-1130 run to run) while the Windows golden at 900 was settled, which reads as a 92.9% "different scene" delta if reported bare. Tells: over-tol2 % >30% at one stem and 1-7% at the next; phash Hamming in the 80s; a dense dump whose consecutive diffs sit at 80-95% and drop to 1-5% once settled. Never compare across platforms with `GE_DETERM=1` (call-sequenced retraces: stable run to run, different frame -> sim mapping). Before calling a residual band a renderer bug, classify it: a constant ~20 delta confined to a screen band (Archives' top 3 grid rows, all three stems) is systematic and needs a same-sim-state capture pair; a uniform d 3-6 over the whole frame with cell means <= 11 (Cuba) is the dither/quantization noise floor. **RESOLVED 2026-10-05 (D525):** both residual bands were *save state*, not renderer — the pair that closed them was a re-round of the whole linux set with `data/ge007.eep` pinned present (Archives 19.956-24.554% -> 3.590-3.859%, worst cell 50.8 -> 2.31; Streets 1200's 16.0-148.4 cell-mean band -> 3.616-3.983%, worst cell 4.43). The diagnostic tell that separates the two: re-capture one side with the save present and the band collapses to the noise floor, while a renderer defect survives identical sim state.
+
+## D26. Never bound a host address with an absolute number (D573)
+
+A plausibility guard written as `p < 0x10000 || p >= 0x400000000ULL` encodes today's layout (DRAM at `0x7000_0000`, cart at `0x1000_0000`). It silently rejects every real pointer once the arena moves (macOS `PORT_ADDR_BASE`, the D441 above-4-GiB tier), and it accepts any unmapped address below the bound. Test the actual windows with `portAddrIsMapped()` (`portaddr.h`: DRAM arena views + mapped cart image). Tells: a feature that goes completely silent or blank (all SFX, all text) on one platform or arena flavour while the rest of the game runs; a guard comment that names the windows next to a literal that does not.
+
+## D27. Rendering one display list twice: per-frame renderer state must not advance per pass (D578)
+
+Frame interpolation (D578) draws each game DL several times. Everything a fresh frame starts from has to be the same for every pass: emulated RSP/RDP state, segment table, viewport caches, and the GL backend's noise seed (`frame_count` in `gfx_opengl.cpp`, which advances in `start_frame` and seeds dither noise; letting it advance per pass changed thousands of pixels on early-level frames). Do NOT restore caches that mirror live GL state (`rendering_state`). Tells: a pass-0 vs pass-N diff (`GE_INTERP_SELFCHECK`) that is large on a few frames (noise, dithered alpha) or 1-4 px on rare frames (a DL relying on the texture left bound by the previous frame). Also: never re-read a game DL after posting SP/DP done; draw every pass before it.
+
+## D29. A "default depends on whether the user chose" needs the load-time `seen` flag, not the value (D578)
+
+`configLoad` writes the registered defaults to a missing ini *before* subsystems init, so by `videoInit` the file already contains every key and its value cannot tell "fresh" from "chosen". Use `configIntKeyWasLoaded(key)` (the per-option `seen` flag from the last load) for fresh-install-only defaults (gamescope VSync off), and re-`configSave()` if the override must persist. Likewise a new sentinel for an existing numeric key (FpsCap Auto = -1) must not reuse 0 when old inis already give 0 a meaning, and the registered min must be widened or the load clamps it away.
+
 ## E. Process / method notes
 
 - **Never `exit()` while another thread may be inside the GL driver (D344).**
@@ -1360,6 +1505,11 @@ darkening from a nonzero `ENV_ALPHA` LERP factor is very likely faithful
   `[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.
+- **Per-slot headless scripts: `GE_INPUTSCRIPT_P1..P3` drive seats 2-4.**
+  Same entry syntax as `GE_INPUTSCRIPT` (slot 0); "frame" counts that
+  controller's reads. Mouse tokens and CHOLD/CREL are ignored on slots 1-3
+  (one warning per script). Recipe for a scripted 4P split-screen run:
+  `GE_STARTMP=4,<stage> GE_MPVIRT=3 GE_INPUTSCRIPT_P1=... GE_INPUTSCRIPT_P2=... GE_INPUTSCRIPT_P3=... GE_QUITFRAME=...`.
 - **`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.
@@ -1743,3 +1893,130 @@ darkening from a nonzero `ENV_ALPHA` LERP factor is very likely faithful
   `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.
+
+- **x64 Windows backtraces: unwind with the PE's .pdata, never walk RBP.**
+  `-fno-omit-frame-pointer` on MinGW-w64 GCC does not give an RBP chain:
+  most prologues set `RBP = RSP + N` (Win64 allows an offset frame
+  pointer), so `[RBP]` is not the saved RBP and a manual walk dies at
+  frame 1. `RtlLookupFunctionEntry` + `RtlVirtualUnwind` from the
+  exception CONTEXT is reliable and needs no dbghelp/symbols (crash.c,
+  2026-09-30). Print `va = preferred ImageBase + RVA` per frame so
+  `addr2line -e ge007.x86_64.exe` resolves it even if the image was
+  relocated. Test with `GE_CRASHTEST=<N>`.
+- **Crossing msys -> native: pass files, not quoted strings; get paths from
+  bash's own `pwd -W`.** The msys argv conversion re-escapes embedded `"`
+  as `\"`, which `cmd.exe` does not understand, so an inline
+  `cmd //c "... \"C:\path\" ..."` silently never runs (build-pc.sh's TMP
+  probe was dead this way). And with Git Bash plus MSYS2 `usr/bin` on one
+  PATH, `/tmp`, `mktemp` and `cygpath` can belong to different runtimes
+  (different Windows dirs). Never trust `command -v cmake` for the MSYS2
+  toolchain either: a pip-installed cmake can shadow it (2026-09-30).
+
+### Poll-thread input must never re-point `g_CurrentPlayer` (D419)
+
+`inputComputePad` runs on the scheduler thread (`joyPoll`), a real pthread, not the game thread. Any save/swap/restore of `g_CurrentPlayer`/`player_num`/`g_playerPerm` from there races the game tick's own `set_cur_player`: the restore can leave the game thread on the wrong player and it then spins in list walks that compare against `g_CurrentPlayer->...` (seen: `bondinvCycleForward` infinite loop after a split-screen respawn). Resolve the owning player explicitly (`g_playerPointers[slot]`) and touch its fields directly; for game functions that take no player argument, present a native button bit instead of calling them.
+
+**A1 cross-tag (D492, 2026-10-03): serialized multi-byte fields are host-endian in this port.** Structs copied raw to a file (the EEPROM save via `geEepromRW`) store s32/u16 fields little-endian, while N64 images are big-endian. A raw-byte CRC over the region gives the same value on both, which hides the difference until the stored checksum words themselves are compared. Tell: data that is intact but fails validation, with `calc_crc` equal to the big-endian reading of the stored word. Any field inside the CRC range must be swapped *before* recomputing the checksum.
+
+**A1 cross-tag (D455, 2026-09-30):** an exe-static address (array/global/function in `.data`/`.rodata`/`.text`) held in a `u32`/`s32` truncates on Windows (image base `0x140000000`; Linux 0x20000000 hides it). Binary tell: `mov r64,[rip+.refptr.X]` ... `mov r32,r32` before the pointer is used or passed. The address load may precede a `jmp` join, so an adjacent-instruction scan misses it; follow jumps. A census of the whole exe found only the D454 site; `_*Segment*` linker symbols are ROM constants (`.set` in `romassets_u.s`), not exe addresses, and are benign in `(u32)` casts.
+
+**`GE_MEMPREDZONE=1` (D464): catch allocator overruns deterministically.** Set it before any run to pad every `mempAlloc*` block with a 64-byte pattern trailer and check at level unload, every 60 frames and on orderly quit. A hit prints `MEMPREDZONE: HIT ... caller=0x<addr>`; resolve with `addr2line -f -C -i -e build-pc/ge007.x86_64.exe 0x<addr>` to the allocation site, then compare its size expression with `sizeof` of how the buffer is indexed (an N64 literal stride vs a widened struct is the D461/D462 class). Zero hits is only "no overrun reached the trailer"; whole-bank allocations are unpadded until shrunk. Unset = one cached branch per allocation.
+
+**Data-driven input mapping: factor the pure core, keep the old code as a test oracle (D469).** To refactor a hard-wired input block into a table without changing default behaviour, move the decision into a pure function over (raw source bits, bindings, previous-state, incoming mask) and keep a verbatim transcription of the old block next to it, used only by an env-gated boot self-test (`GE_PADMAPTEST`) that compares them exhaustively over the (small) input space. 2^15 source combinations x prev x ctx x incoming masks is ~21M cheap calls, ~1 s, and gives a byte-identity proof no live pad is needed for. Watch the side inputs the old code mutated implicitly (here the incoming `button` mask: the southpaw swap acted on keyboard fire too, so the pure function takes it as a parameter). Table edits arrive from other threads: the poll thread must rebuild into a spare buffer keyed by a cheap config signature and publish by atomic pointer, never parse (no `strtok`) or re-point shared state in place.
+
+**Audio device/gain changes belong on the producer thread (D470).** The SDL audio path is a queue (`SDL_QueueAudio`), fed and sized only from `audioSetNextBuffer`/`audioGetAiLengthBytes`. To change the device live, have UI/event threads only set atomics and do the close/reopen at the top of `audioSetNextBuffer`; never close `dev` from the UI thread. Apply master gain to a scratch copy (never the game's buffer) and pass the original pointer through at 100 so the default stays byte-identical. `SDL_AUDIODEVICEREMOVED.which` is the opened device id for output devices.
+
+**Overlay/menu input must name its owner pad; never hard-code seat 0 (D472).** When several pads can open a shared UI, keep a per-pad edge array (one shared `prev` flag masks edges and double-toggles), record the opener, and resolve the effective owner (opener -> lowest attached -> 0) at read time so a detach cannot strand the UI. Port-layer 2D that must pillarbox under native widescreen: wrap it in `PORT_HUD_ASPECT(CENTER)` and map the mouse through `vis = (4/3)/portNativeAspect()`.
+
+### The options row table has two UIs; new row kinds need a front-end answer (menu PD alignment)
+`port/src/optionsoverlay.c`'s `rows[]` is consumed by the F10 overlay and by `frontoptions.c` through the `optionsRow*` accessors. A row kind that only one UI understands (separator, Back, hub-only actions) must be hidden from the other in `optionsRowIsShown()`, and should be a `ROW_ACTION` with a key prefix so the section-reset and reset-probe loops (which skip `ROW_ACTION`) stay correct. Moving a row between sections silently changes what that section's "Reset to defaults" resets: re-run `GE_WSPROBE_RESET` after any regroup.
+
+### Never put a blocking vsync swap ahead of the draw the game is waiting on (D578)
+A render worker that must post "task done" after drawing must not swap (a blocking VSync present) before the draw: under a compositor (gamescope) each swap blocks a full refresh and the game misses retraces while CPU/GPU idle. Draw, post done, then present; derive interpolation alphas from predicted vblanks (swap-return times), not a free-running timer.
+
+## D28. A "fall back to exact" gate on a per-tick rate needs a graded response, not a cliff (D578)
+
+A fallback that turns interpolation off for the whole frame above a low threshold (1.5 deg/tick view turn) fired on ordinary stick turns (9-64% of frames on a 90 Hz Deck). Prefer pulling the blend alphas toward 1 in proportion to threshold/measured (bounded offset, still smooth) and reserve full fallback for genuine cuts. Also: the display list references live game memory, so deferring a draw past SP/DP done is unsafe without copying every referenced buffer.
+
+A second, unscaled cliff hid behind the first: the modelview 6 deg/tick gate set "exact" directly, so softening the projection check changed nothing. When softening a fallback, grep every writer of the fallback flag. Also: a per-pass cost estimate must divide by passes actually drawn (discarded restarts included) and clamp single outliers, or one exact restart collapses the pass budget (D578).
+
+## D30. Detect "the culled set changed" from a stable per-item id in the DL, not from matrix pairing (D578)
+
+When a game builds its visible set and per-item clip rects for the current camera only, an interpolated pass cannot repair a changed set. The cheapest exact detector is a per-item marker already in the DL (GE: `gSPSegment(14, room vertices)` before each room's `gSPDisplayList`; the base is unique per room). Record the sorted unique ids per game frame and compare prev -> cur; do not infer it from matrix-pairing counts (rooms share matrices). Clip rects derived from a recursive portal descent are path-dependent intersections, so they cannot be recomputed per portal in isolation.
+
+## D31. A render worker must not read live game state; snapshot it on the game thread at task submit (D578)
+
+With the D481 render worker the game thread is already building frame N+1 (running `bgDetermineVisibleRooms`, resetting per-frame arrays, replacing matrices) while frame N is being drawn. Any port-side code that re-derives something from game globals at draw time (here: replaying the portal traversal) sees a half-updated mix: counts and arrays disagree mid-compare, matrices point at the next frame's allocation. Capture what the replay needs on the game thread at the one synchronous point per frame (`osSendMesg(sched_cmdQ, gfx task)` in `rspGfxTaskStart`; recognise it by `msg == g_gfxTaskSettingsList`), key it by the display-list pointer, and read only the snapshot (plus truly static level data) on the render side. A probe that compares live game output with a replay will report "extra/missing" noise that is really this race.
+
+## D32. A replay of game code at an interpolated camera needs the camera in the game's own matrix convention (D578)
+
+GE folds the camera lookat into the room projection (`field_10E0 = lookat * persp`) while `field_10CC` is the world-to-view matrix bg.c culls with, in a different (unscaled, un-offset) position space. To get the second at a blended camera from the first: `L = P * persp^-1` (row vectors; `matrix_4x4_multiply(a,b,r)` means `r = b*a`), take rotation and camera position from `L`, convert the position delta back with the world scale (`D_800364CC`), rebuild `field_10CC`. Verify the derivation on exact frames first (derived rotation == `field_10CC` rotation, `(cam - model_pos) * scale == derived position`): both held to 1e-5 / 3e-3, which also proves the multiply-order and layout assumptions before any blended frame is trusted. Accept a projection pair as "the room projection" only when that rotation check passes, and cache the replay per pass: pure-perspective and HUD loads between room draws must not flip a room's scissor between two code paths.
+
+## D33. "Enable depth clamp" is not a fix until you find every far-plane reject, and read the matrix layout before editing a column (D578)
+
+A GL-side `GL_DEPTH_CLAMP` is moot when the software RSP already drops whole triangles on the CPU (`z > w` CLIP_FAR trivial reject): audit CPU rejects before blaming or relying on the GL clip stage, and check whether the clamp is already globally on. Separately, when patching a perspective matrix that GE pre-multiplies by a lookat (`lookat * persp`, row vectors), the z column is `A*L[i][2]` for the basis rows and `A*T.z + B` for the translation row (T is nonzero: the lookat is built from camera-minus-model-origin). Reading row 3 as `k*L[2]` is a column-vector habit; the result is a heading-dependent tilt, not a clean plane shift.
+
+## D34. Diagnose "geometry vanishes" by counting outcomes and capturing the frame, not by switching features off one at a time (D578)
+
+Eight A/B switches on a visual dropout (far clip, depth, cull, scissor, projection lerp ...) all failed to move it; two cheap instruments did what they could not. Per-room triangle fate counters (seen / rejected by plane / culled / eye-crossing / emitted), compared between the suspect pass and the reference pass of the SAME frame, showed the CPU side was equal and eliminated a whole class at once. Two traps: (1) log both directions (or an aggregate), never only the losses, or selection bias manufactures a "systematic loss"; (2) an automatic capture trigger must be insensitive to legitimate change. An interpolated image can only contain what the previous and current exact frames contain, so "differs from BOTH neighbours" isolates real glitches, whereas "differs from the exact frame" fires on every camera turn and burns the capture cap.
+
+## D35. A CPU-side clip must clip where the GPU would, and the GPU runs with depth clamp (D579)
+
+`GL_DEPTH_CLAMP` is on globally (`gfx_opengl.cpp`), so GL never clips at the near plane: geometry between the eye and the near plane is drawn, as on the N64. The D543 CPU clip, added to stop attribute extrapolation across the camera plane, cut at `z = -w` and so deleted exactly that geometry, and a wall the player hugs vanished (#150, a v0.5.0 regression). The cut belongs at the camera plane (`w = eps`), with fog for clip-created vertices evaluated at `max(z/w, -1)` so the near-plane haze is unchanged. Before adding any CPU reject or clip, check which GL clip stages are actually live; see also D33.
+
+## D36. Under VRR the swap is not a clock: pace presents from one continuous grid (D583)
+
+With G-Sync/FreeSync a blocking swap returns when *we* present, so swap-return gaps measure our own cadence; any scheduler that derives its period or phase from them (or rebuilds its slot grid per game tick from the last swap) feeds back and wobbles, and a VRR OLED shows every frame-time change as a brightness change. Present from one continuous grid at the display period, snapped to exactly tick/N when within ~1% (no beat between the game clock and the display clock), re-anchored only on a real stall; never drop a queued present when a new game frame arrives (ring), base the ready time on the measured whole-frame draw (capped, so load frames are not learned), and avoid letting a queued present fall due during the next frame's draw. Measure cadence with a gap histogram, not presents/s alone.
+
+## D37. Interpolation gates: never normalise a tiny measurement by (1 - alpha) near 1, and measure before any widening (D583)
+
+A per-tick rate estimated as offset / (1 - alpha) amplifies anything that is not proportional to (1 - alpha): float rounding in an acos (~0.05 deg) and a fixed offset added by a later step (the far-clip widening read as 0.16 deg) became 1.5-3 deg/tick on passes with alpha just under 1, and every such frame was redrawn from scratch for a change nobody could see. Measure on the value before any post-processing, and only where the denominator is large or the measurement well above its noise. Count what each gate costs (redraws per 10 s), not just how often it fires.
+
+## D38. Pair cameras by nearest, not one-to-one; and an exact fallback should draw once (D583)
+
+GE loads the same camera projection once per room/object (~60 per pass). Pairing each load one-to-one with the previous frame's loads runs out of partners whenever the count changes (a set of rooms entering or leaving view) and pairs the leftover with another kind of projection: one object is drawn at the wrong camera or depth on an in-between present and appears to flicker in step with the room change. Pair a camera with the nearest previous camera even if already claimed, and give identical source matrices an identical result within a pass (memo). Separately: when a frame falls back to exact, draw the exact image once and copy it to the remaining present slots; redrawing n identical passes is pure cost.
+
+## D39. Behind-camera triangles still need a facing test: use det[x y w], not "skip" (D584)
+
+Dropping the cull for triangles with a vertex at w < 0 (because x/w is undefined there) draws both faces of two-faced translucent walls (Cradle catwalks) and reads as flicker at every frame rate. The homogeneous determinant det[x y w] is the correct facing test for any w: for all w > 0 its sign equals the NDC cross, and for mixed w it equals the classic XOR behind-eye flip, with no division. Also: when bisecting on a test box, use builds made from a known commit; a backup's file name is not its provenance (D584 lost one round to a mislabelled binary).
+
+## D40. Deck draw cost: count before optimising, and never redraw past the budget (D583)
+
+On the Deck (Game Mode: stderr is dropped, so instruments must go to ge007.log via sysLogPrintf), a heavy pass is ~6 us per batch, and batches track texture changes about 1:1. A counter at the top of `import_texture` counts lookups, not uploads; split hits, misses and time before concluding anything. "Skip the rebind when the same texture is re-issued" looked like a win on paper and changed nothing: consecutive batches really use different textures. For interpolation, any decision that redraws a whole pass (softened restart) must check the measured pass time against the refresh budget first: one slightly-off in-between image is invisible, a missed present is not.
+
+## D41. A long frame time on one render thread is not draw cost until you line presents up against draws (D583)
+
+Before optimising a "slow" interpolated frame, check what its time contains: with one worker that both draws and presents, a frame's measured draw includes nothing but work, yet the presents queued behind it go out late by up to the whole draw, and the symptom (uneven 8/14 ms gap pairs at full present rate) looks exactly like an over-budget pass. Profile on-CPU time (`perf` works on SteamOS, `perf_event_paranoid` 2 is enough for your own process) and rule out the GPU clock (QAM Manual GPU Clock) before touching batching; then log each draw's start/end next to each present's due/late time (`GE_INTERPLOG=<n>`). On the Deck in Game Mode, gamescope only shows windows Steam launched: a harness started over ssh runs hidden and throttled, so launch through a Steam shortcut (`tools_pc/deckrunner.sh`).
+## D42.. Combiner alpha only reaches the framebuffer through the blender: no FORCE_BL, no blend (D414)
+
+fast3d's `use_alpha` (blender inputs CLR_MEM/1MA) is a heuristic for "this is an alpha-blended draw". On the RDP the blender only acts on interior pixels when `FORCE_BL` is set (or via coverage/`CVG_X_ALPHA`); a render mode with XLU-style inputs but no `FORCE_BL` is opaque regardless of combiner alpha. Vanilla GE never noticed because its combiner alpha there is `SHADE` alpha (255). A mod's DL with cycle-2 alpha `(0,0,0,0)` drew fully transparent = black. GL blend is now gated on `FORCE_BL | CVG_X_ALPHA`.
+
+**Tell:** rasterized with correct depth, immune to vertex-shade boosting, correct raw texels, black output. **Bisect fast:** output raw `texVal0/texVal1` in the fragment shader (bypasses combiner + blend); if that is right, the fault is combiner or blend state, not textures.
+
+## D43. A capture taken through the feature under test is not ground truth (D628)
+
+`GE_TEXDUMP` dumps what the GL upload receives, which is the *texture pack's*
+image whenever a pack supplies that texnum - so dumps captured with
+`Video.TexturePack` set cannot validate a pack join: the hold-out compares the
+pack PNG with a dump of itself and scores a perfect 1.000. 52 of 346 dumps in
+one such set were pack-substituted, and the false "pack and ROM textures are
+the same size" premise read off them then gated the matcher down to nothing
+(real packs are 4x-128x upscales). Two habits avoid the whole class: capture
+ground truth with the feature OFF (and record in the dump dir which switches
+were set), and before trusting a precision number, check that the hold-out's
+dims/format still look like the *source* data rather than the replacement.
+A 100 % score on a derived metric is a circularity smell, not a result.
+
+**"Faithful" input mode = emit native bits and add nothing (D643).** A port that routes pad buttons to PC *actions* (dedicated use/reload calls, crouch, gadget cycle) cannot also claim to be the N64 pad: the game's own handlers (e.g. B = use-else-reload) only run on the native bit, so a button bound to two actions double-fires, and a fixed menu lockout reinterprets faces. For a strict mode, give the published bind table a native-button layer, zero every port-action mask in it (so side paths that read the action bitset, like a dedicated use/reload hook, go inert without being touched), and make the pure mapper `orig`-flagged and context-free; prove it with the same boot self-test (per-source table across stage/menu/tank). Also stop role-swapping sticks to match the game's selected style: a virtual pad keeps left = analog, right = C.
+
+## D44. RDP IA4 is I3:A1; a decode tweak justified by "hardware layout" needs a texel dump (D644)
+
+IA4 = 3-bit intensity + 1-bit alpha (nibble = I<<1 | A). An I2:A2 decode (D266) turned the A=0 nibbles 2/4/6 into semi-opaque black and drew the file-select crest on a dark square. When a texture's transparent texels render opaque, histogram the raw nibbles/bytes (`GE_TEXRAW` + `GE_D526` for the draw's fmt/oml/comb) before touching blender or alpha-compare code: the importer's alpha expansion is the cheapest suspect.
+
+## D45. Interpolating GE: rooms carry the camera in the projection, props carry it in the modelview (D954)
+
+GE loads two projections per view: `field_10E0` = perspective * lookat for rooms (modelviews are scale*translation), and the plain perspective `projmatrix` for chrs, doors, props, glass, explosions and the gun (camera baked into each modelview; LOD reads `-m[3][2]` as view depth). An interpolator that blends only the projection moves the rooms and leaves every prop at the exact camera, which reads as props flickering against the world at high frame rates only. Give the plain perspective the room camera blend (`P * R^-1 * Rb`, row vectors, `R = L * P`), and stop before anything camera-attached (the gun inherits the loaded projection; its `gSPPerspNormalize` marks the boundary). Check the matrix order at runtime (`R * P^-1` affine) instead of assuming it.
+
+## D46. GE models are matrix-skinned; every view matrix is relative to the current room's origin (D955)
+
+Chrs and objects load per-joint matrices from `model->render_pos` through segment 3 (`gSPSegment(3, render_pos)` in `subdraw`); the vertices are the model file's shared static arrays, so per-object identity lives in the matrix block, not in vertex buffers (interpolate matrices, keyed by (Model*, joint); never by draw ordinal, which shifts with LOD, weapons, hats and decals). Those matrices have the camera baked in, and every view matrix (rooms, props, the lookat in `field_10E0`) is relative to `current_model_pos`, the current ROOM's origin, which jumps at a room change: anything that compares matrices across ticks must rebase by the camera delta and treat a room change as a discontinuity.

docs/saves.md

@@ -0,0 +1,29 @@
+---
+title: Saves
+description: How the GoldenEye 007 PC port backs the N64's EEPROM save with a plain file you can back up.
+date: '2026-10-05'
+modified_time: '2026-10-05'
+---
+
+## Saves
+
+GoldenEye's N64 save is **EEPROM-based** — the controller's EEPROM
+(`osEeprom*`), not a Memory Pak. The port backs it with a **plain file**,
+`data/ge007.eep` next to the executable, so your progress is a file you can
+copy to back it up (or move to another machine).
+
+A few details:
+
+- The **PFS / Memory-Pak and motor (Rumble Pak) code** is only for accessory
+  detection and is stubbed to report "no accessory," so the game proceeds
+  without a Memory Pak.
+- **Emulator saves load directly** — an emulator-format `ge007.eep` placed
+  in `data/` is converted on first launch, so a Project64, mupen or 1964
+  save continues in the port (see the README's *Using an emulator save*).
+- The save's **checksum is part of the file format**. The PRNG/CRC the save
+  depends on is kept byte-stable, because changing it would silently
+  invalidate existing saves — a porting-notes finding (D9).
+- `-fresh` (a launch option) wipes the save and settings for a clean-slate run.
+
+*More: [internals](internals.md) §7; the checksum finding is
+[porting notes](porting-notes.md) D9.*

docs/security-and-fidelity-status.md

@@ -1,109 +0,0 @@
----
-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.*

docs/security.md

@@ -0,0 +1,96 @@
+---
+title: Security status
+description: What a GoldenEye PC port release installs and doesn't: no networking unless you opt in to the update check, no telemetry, no ROM, no system writes — re-verified against the v0.5.0 source.
+date: '2026-10-05'
+modified_time: '2026-10-05'
+---
+
+## Security status
+
+This page answers one question plainly: *what does installing this put on
+your machine*? The review was done
+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 no-networking source check was repeated against the
+`release/v0.4.1` tree on 2026-09-30 (no socket, HTTP or name-resolution
+calls in `src/` or `port/`; neither the engine nor the bundled `SDL2.dll`
+imports a networking DLL; no registry calls in the port's own code); the
+bundle contents were not re-checked then.
+
+**v0.5.0 update pass, 2026-10-05:** the source checks were re-run against
+the current tree — no socket/network includes, no network symbols and no
+HTTP string literals in the compiled `src/` and `port/` sets; no registry
+or library-loading calls in either (since D551 the one exception is the
+opt-in update check: a System32 `winhttp.dll` load on Windows or a `curl`
+process on Linux, only when `Game.CheckUpdates` is on); the converter's Python sources
+(`prepare-assets.py` and its emit-script imports) import no network
+module. The bundle contents were re-checked against the packaging
+manifests (`tools_pc/bundle-win.sh` / `bundle-linux.sh` — the scripts CI
+runs): an explicit allowlist of engine, runtime DLLs, SDL2, licenses and
+converter tools, with a hard-fail guard against a ROM image or oversized
+blob sneaking in. The v0.5.0 artifacts themselves were not re-unpacked
+locally; they are built by the same scripts. The full engineering record
+behind each item is in the project's finding log
+([`docs/dev/findings.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/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 unless you turn on the opt-in update check**
+  (`Game.CheckUpdates`, off by default): then it makes one HTTPS request to
+  GitHub's releases API per launch (a fixed User-Agent; GitHub sees the
+  request and your IP, as with any web request) and never downloads or
+  installs anything. On Windows it loads the system `winhttp.dll` from
+  System32 at runtime only in that case (it is not in the import table); on
+  Linux/Steam Deck it runs the system `curl`. With the setting off there
+  are no sockets and no HTTP (D551; checked against the source and run live
+  on Windows, Linux and Steam Deck),
+- 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.
+The engine starts it automatically on the first run, when the two derived
+asset folders (`data/pcmodels-*`, `data/pccg-*`) are missing, passing it
+the ROM it found and the output folder; after that first run it is not
+launched again.
+
+See [`SECURITY.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/.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. The CI build freezes the
+release's asset-converter tool with `pyinstaller`, which is pinned to an
+exact version, and every third-party GitHub Action the workflows use is
+pinned to a full commit SHA (both from the release after v0.4.0; earlier
+releases installed an unpinned `pyinstaller`). What PyInstaller packages
+is in-repo, stdlib-only Python — a release is reproducible from this
+repository alone.
+
+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.

docs/the-asset-pipeline.md

@@ -0,0 +1,33 @@
+---
+title: The asset pipeline
+description: How the GoldenEye 007 PC port turns N64 ROM assets into the model and graphics files it loads at runtime.
+date: '2026-10-05'
+modified_time: '2026-10-05'
+---
+
+## The asset pipeline
+
+The N64 stored the game's assets (models, textures, fonts, level and cutscene
+data) inside the ROM in on-hardware formats a PC can't use directly. The port
+converts them into two "sidecar" files it loads at runtime:
+
+- **`pcmodels`** — the 3D models (a PC layout of the N64's RZ model format).
+- **`pccg`** — the graphics: textures, fonts and the rest of the ROM data.
+
+Each is a single concatenated image plus a small `manifest.csv` (name, offset,
+size) that the loader reads — `port/src/pcmodels.c` and `port/src/pccg.c`.
+
+**Where they come from.** Two paths produce the same files:
+
+- **A downloaded build** generates them from *your* ROM on first start, into
+  `data/pcmodels-<region>/` and `data/pccg-<region>/` next to the executable.
+  Delete them at any time — they are made again on the next start.
+- **Building from source** runs the offline Python converters in `tools_pc/`
+  to produce the same files (see the [Building](building.md) guide, §4).
+
+This is one of the deliberate differences from the Perfect Dark port, which
+fixes up the N64 asset formats at load time: GoldenEye's serialized formats
+are converted **offline** instead.
+
+*More: [building](building.md) §2 and §4; the loaders are
+`port/src/pcmodels.c` and `port/src/pccg.c`.*

docs/the-software-rsp.md

@@ -0,0 +1,38 @@
+---
+title: The software RSP
+description: How the GoldenEye 007 PC port emulates the N64's Reality Signal Processor (the graphics coprocessor) in software and bypasses the RDP.
+date: '2026-10-05'
+modified_time: '2026-10-05'
+---
+
+## The software RSP
+
+On the N64, the **Reality Signal Processor (RSP)** is the graphics
+coprocessor. The R4300 CPU builds a list of graphics commands each frame
+(the **GBI display list**); the RSP runs a "fast3d" microcode that turns
+those commands into **RDP** (rasterizer) commands, which the RDP turns into
+pixels.
+
+The port does two things to that pipeline:
+
+- **It emulates the RSP in software.** `port/fast3d/` (~7,000 lines of C++,
+  adapted from the Perfect Dark port) *is* the RSP: it interprets the GBI
+  display list the game builds and, instead of emitting RDP commands, emits
+  **OpenGL** calls directly.
+- **It bypasses the RDP entirely** — there is no rasterizer to emulate,
+  because the software RSP talks straight to the GPU.
+
+The game's own R4300 code runs natively and is unaware of the difference: it
+builds display lists and "starts the RSP" exactly as it would on hardware. A
+replacement scheduler (`pdsched.c`) catches the "start the RSP" call and runs
+the software RSP on the render thread.
+
+GoldenEye's custom commands are handled by the same interpreter: the packed
+four-triangle `G_TRI4` command and the fade/blend **color-combiner** modes
+(compiled on the fly from the N64's combiner equation to a GLSL shader by
+`gfx_cc.cpp`). The N64's own RSP microcode (`rsp/graphics/gmain.s`) is not
+run on PC but is the reference the software RSP's command decoding is checked
+against.
+
+*More: [internals](internals.md) §2 (the reference architecture) and §5
+(GoldenEye-specific graphics work).*

docs/user-guide.md

@@ -0,0 +1,307 @@
+---
+title: User guide
+description: Controls, settings, files, ROM check, updating, emulator saves, macOS setup and troubleshooting for the GoldenEye 007 PC port.
+---
+
+# User guide
+
+Everything beyond the [Quick start](../README.md#quick-start): the full
+controls, every setting and file, and fixes for common problems.
+
+- [Controls](#controls)
+- [Feature list](#feature-list)
+- [Settings and files](#settings-and-files)
+- [What's a ROM?](#whats-a-rom)
+- [macOS (Apple Silicon, experimental)](#macos-apple-silicon-experimental)
+- [Updating](#updating) · [Using an emulator save](#using-an-emulator-save) · [Uninstalling](#uninstalling)
+- [Troubleshooting](#troubleshooting)
+
+
+## Controls
+
+| Action              | Keyboard / mouse         | Controller    |
+|---------------------|--------------------------|---------------|
+| Move / strafe       | `W` `A` `S` `D`           | Left stick (or D-pad) |
+| Move / turn         | Arrow keys               | —             |
+| Aim / look          | Mouse                    | Right stick   |
+| Fire                | Left mouse               | Right trigger |
+| Aim mode            | Right mouse / `LShift`   | Left trigger / LB |
+| Use / interact      | `E`                       | A             |
+| Reload              | `R`                       | X             |
+| Crouch (toggles)    | `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        |
+
+The keyboard defaults are a GEPD-style layout. The controller layout matches
+Rare's Xbox 1.1 (Jinx) button roles; the other Xbox styles (1.2 Christmas,
+1.3 Frost, 1.4 Elektra, which swap the stick roles) are selectable under
+*Controller* (pick a player first, then *Layout presets*). PlayStation and Nintendo controllers
+show their own button names in the menus.
+
+**Control style:** *Controller → Control style* (named after the watch's own
+setting, with **Extended**, after Perfect Dark's "Ext", for the port's controls) picks how the
+game's controller style (the watch's 1.1–1.4 selector) is treated. **Extended**
+(the default) keeps the port's feel and fixes the style itself, so the watch's
+selector has no effect. **Original** stops the port from touching the style:
+pick 1.1, 1.2, 1.3 or 1.4 on the watch (or in the multiplayer setup) and it
+behaves as on the N64, and the Controller page then offers the game's own
+styles ("Controller style", 1.1 Honey to 2.4 Goodhead, saved in the Bond file
+like the watch's) instead of the layout presets, which apply in Extended only. Buttons are passed
+through as the N64's buttons, so 1.3 and 1.4 move fire and aim exactly as the
+console does. The 2.x dual-controller styles run faithfully too: the game
+reads their second stick from the next controller slot, which the port does not
+map yet (a second pad assigned to that slot should provide it, untested), so with
+one pad pick a 1.x style. Saves made with earlier builds may hold 1.2 (the port wrote its
+forced style back into the save), so when you switch to the Original control style, pick
+your style on the watch once.
+
+In the Original control style the pad is a strict virtual N64 controller in
+every context (stage, menus, watch, tank): each press sends the native N64
+button and the game decides what it means (so *B* uses a door or reloads, as
+on the console). Default layout, remappable per player in the ini
+(`Input.N64Pad.<Button>`, `Input.N64Pad2..4` for players 2-4; up to two pad
+buttons each) and with `Input.N64StickFeel` (1 = linear +/-80 stick with a
+small dead centre, 0 = the Extended deadzone):
+
+| Pad | N64 | Pad | N64 |
+|---|---|---|---|
+| South (A) | A | Right stick | C buttons |
+| West (X) | B | Left stick | Analog stick |
+| Right trigger | Z | D-pad | D-pad |
+| Left trigger / RB | R | Start | Start |
+| LB | L | Back | PC options overlay |
+
+**Rebinding:** *Key Bindings* in the options overlay rebinds the
+keyboard and mouse (one list: movement, then actions). Controller buttons are
+rebindable per controller under *Controller* (pick a player first): set *Layout presets* to
+*Custom*, select an action and press a pad button (tap B or Esc to cancel,
+hold B to bind B itself, hold Back to clear; Y clears the selected slot).
+Each action takes up to two buttons. Menus always keep A/X accept and B/Y
+cancel, so you can't lock yourself out. There is no warning yet when two
+actions share a button, and the Xbox release's "left stick aims the
+crosshair" and "D-pad copies the left stick" behaviors are not reproduced
+(here the right stick aims and the D-pad strafes, as on the N64).
+
+**Split-screen:** pick Multiplayer from the main menu. With one controller,
+keyboard/mouse is player 1 and the controller is player 2; with two or more
+controllers, the controllers take players 1–4 (`Input.MPMode` in `ge007.ini`
+changes this). A controller unplugged mid-match keeps its player when
+plugged back in.
+
+**Options overlay with a controller** (also how it works on the Deck):
+**Select** opens it, the D-pad or left stick moves between rows and
+left/right adjusts the selected value, **A** opens a page or toggles a row,
+**B** goes back one page (and closes from the top), and **Start** (or Select
+again) closes. With a keyboard, use `F10`, the arrow keys, Enter and
+Backspace.
+
+
+## Feature list
+
+- **Split-screen multiplayer for up to 4 players**, with the N64's own setup
+  flow and per-player HUD.
+- **Native widescreen** at any aspect ratio: the world is undistorted, the HUD
+  sits at the screen edges, and 4:3 menus are pillarboxed. FOV and draw/LOD
+  distance are adjustable, and AI behaviour stays as on the N64 whatever you
+  set them to.
+- **The original look in one click:** the *Display mode* row (F10 → *Video*) switches
+  between *Modern* and *Original N64* (it reads *Custom* once you edit a setting it covers),
+  and *Aspect ratio → Original* shows the exact 4:3 frame.
+- **A steady 60 fps**, with VSync and a frame cap (30 or 60), including on
+  the low-end GPUs I test on.
+- **Frame rates above 60:** 90, 120, 144, 165 or 240 fps, or **Auto** to match
+  your display (up to 240). Extra frames are blended between game ticks (the game still runs at
+  its original rate), at the cost of one tick of latency. It has no effect on
+  a 60 Hz display, and the *Original N64* preset keeps 60. See
+  [framerate and pacing](framerate-and-pacing.md).
+- **macOS (Apple Silicon), experimental:** a `macos-arm64` download, not
+  notarized (one Terminal command to unblock it, see [macOS](#macos-apple-silicon-experimental)),
+  or build from source. I'd like test reports.
+- **Graphics options:** resolution, borderless or exclusive fullscreen,
+  a Center window action while windowed, MSAA (up to 16×), anisotropic
+  filtering, and nearest, bilinear, trilinear or the N64's own 3-point
+  texture filter.
+- **Mouse aim** in your choice of style (the N64's, or centered FPS-style) with
+  per-device sensitivity, smoothing and Y-inversion.
+- **Modern controller support:** dual-stick layout, deadzones, sensitivity,
+  southpaw, trigger thresholds, rumble-pak vibration, and PlayStation/Nintendo
+  button names.
+- **Rebindable controls** for keyboard, mouse and each controller.
+- **HUD and crosshair options:** HUD scale (also scales the in-game options
+  menu), an optional always-on crosshair, a custom RGB crosshair color
+  with adjustable opacity and a health-based color, and a no-hit-flash option.
+- **Full audio:** in-level music and sound effects, with music, FX and master
+  volume and a choice of output device.
+- **An in-game options overlay** (F10 / pad Select) for all of the above,
+  saved automatically; the game's crosshair is the mouse pointer, and
+  each page has a *Reset to defaults* row.
+- **Faithful N64 progression by default.** Opt-in extras: *Skip intro* and
+  *All unlocked* (every level, 007 mode and the full cheat menu, without
+  touching your save), and *Check for updates* (off
+  by default; one request to GitHub per launch when on, see [Security](security.md)).
+- **Saves in a plain file** next to the game, so backing up is a file copy;
+  1964 and Project64 saves load directly ([details](#using-an-emulator-save)).
+
+## Settings and files
+
+**Options overlay:** press **F10** (pad: **Select**) in game or in the menus;
+on the file-select screen the *PC Options* entry opens it too.
+Changes are saved automatically. Most settings live in `ge007.ini`; the
+ones that come from the game's own watch menu (auto-aim, aim
+control, sight, look ahead, ammo on screen, screen size, screen ratio, music
+and FX volume) are part of your save, as on the N64. Screen size (Full / Wide /
+Cinema) and screen ratio (Normal / 16:9) combine with the PC **Aspect ratio**
+setting: Aspect ratio owns the window shape, while the watch's two options
+only change what the game renders inside it.
+
+**Where files live:** everything stays inside the game's own folder. The port
+never writes to `%APPDATA%`, the registry or any system location.
+
+| File | What it is |
+|---|---|
+| `data/ge007.ntsc-final.z64` | Your ROM (you put it there). |
+| `data/ge007.eep` | Your game progress (the N64 save). |
+| `data/ge007.ini` | Settings, written on first start. |
+| `data/pcmodels-<region>/`, `data/pccg-<region>/` | Asset files generated from your ROM on first start. Safe to delete: they are made again on the next start. |
+| `data/ge007.shaders` | A list of the graphics shaders the game used, compiled at startup to avoid stutter. Safe to delete. |
+| `ge007.crash.log` | Written in the folder you launched from if the game crashes. |
+
+**Removing ROM-derived content:** the only files on your machine that come
+from the game are the ROM you put there and the two generated asset folders
+(`data/pcmodels-<region>/`, `data/pccg-<region>/`). Delete those and every
+ROM-derived file is gone; your save (`ge007.eep`) and settings (`ge007.ini`)
+are separate files, yours to keep or delete.
+
+**`ge007.ini`** uses `[Section]` headers and `Key = value` lines. A few
+common keys and their defaults:
+
+```ini
+[Video]
+Fullscreen = 0
+VSync = 1
+FpsCap = -1
+MSAA = 2
+TextureFilter = 1
+NativeWidescreen = 1
+FovScale = 100
+DrawDistance = 200
+
+[Audio]
+MasterVolume = 100
+```
+
+`Fullscreen` 1 is borderless fullscreen; `FpsCap` -1 is Auto (match the display,
+up to 240), 0 is uncapped, otherwise a fps cap (30, 60, or 90 to 240 for frame
+interpolation on a faster display; an existing ini keeps its value); `TextureFilter` is 0 nearest,
+1 bilinear, 2 the N64 3-point filter, 3 trilinear; `FovScale` and `DrawDistance` are
+percentages of the original (the options overlay shows the field of view in
+degrees). On Atom/Celeron-class GPUs the first launch writes lighter values
+for draw distance, LOD distance and `MSAA`. Edit the file with the game
+closed: it is rewritten on a clean exit, and comments are dropped.
+
+**Launch options:** `-fresh` wipes the save and settings before starting (a
+clean-slate run). `--version` prints the build id.
+
+## What's a ROM?
+
+A ROM is a copy of the game cartridge's data, made with a cartridge dumper
+from a cartridge you own. This project can't provide or link one. The port
+needs the big-endian `.z64` format, and supports the US version today:
+
+| Region | ROM filename (in `data/`) | SHA-1 | Supported |
+|--------|---------------------------|-------|-----------|
+| NTSC-U (US) | `ge007.ntsc-final.z64` | `abe01e4aeb033b6c0836819f549c791b26cfde83` | yes |
+| PAL (EU)    | `ge007.pal-final.z64`  | `167c3c433dec1f1eb921736f7d53fac8cb45ee31` | not yet ([#85](https://github.com/jkdansereau/goldeneye-pc-port/issues/85)) |
+| NTSC-J (JP) | `ge007.jpn-final.z64`  | `2a5dade32f7fad6c73c659d2026994632c1b3174` | not yet ([#85](https://github.com/jkdansereau/goldeneye-pc-port/issues/85)) |
+
+To check which file you have, compute its SHA-1: on Windows,
+`certutil -hashfile ge007.ntsc-final.z64 SHA1`; on Linux,
+`sha1sum ge007.ntsc-final.z64`; on macOS, `shasum ge007.ntsc-final.z64`.
+
+## macOS (Apple Silicon, experimental)
+
+**Download:** `goldeneye-pc-port-<version>-macos-arm64.tar.gz` from the release
+page, for Apple Silicon (M1 or later), macOS 14 or newer. It bundles SDL2 and the
+C++ runtime, so Homebrew is not needed. The app is experimental and **not
+signed with an Apple Developer ID or notarized**, so Gatekeeper blocks it when
+it comes from a download. Unpack it, then run `xattr -dr com.apple.quarantine <folder>` in Terminal once, before the first launch:
+
+```sh
+xattr -dr com.apple.quarantine goldeneye-pc-port-<version>-macos-arm64
+```
+
+**Or skip the quarantine step** by downloading in Terminal instead of a browser
+(`curl` does not mark the file, so Gatekeeper never checks it):
+
+```sh
+curl -L https://github.com/jkdansereau/goldeneye-pc-port/releases/download/v<version>/goldeneye-pc-port-<version>-macos-arm64.tar.gz | tar xz
+```
+
+**Without Terminal:** after macOS blocks the first launch, open System Settings →
+Privacy & Security, scroll down to the message about `ge007.aarch64` and click
+**Open Anyway** (macOS 15 removed the old right-click → Open bypass).
+
+Then set up `data/` with your ROM as in the package README and run
+`./ge007.aarch64` from that folder in Terminal. If you launch it first, the process
+stalls before the window appears (it never reached `main` in my test; that is
+most likely Gatekeeper, and clearing the flag afterwards did not unstick that
+copy), so re-extract the archive and clear the flag before launching. I have run
+the package on one M3 Mac only, so test reports (what Mac, what macOS, what
+happened) are very welcome.
+
+## Updating
+
+Extract the new release into a new folder, then copy your ROM, `ge007.eep`
+and `ge007.ini` from the old `data/` folder into the new one. Don't copy the
+generated `pcmodels-*` and `pccg-*` folders: the new version makes its own on first start, and
+stale ones from an older version can cause glitches.
+
+## Using an emulator save
+
+Saves from N64 emulators (1964, Project64, …) load directly: with the game
+closed, just copy your `.eep` to `data/ge007.eep`. On first launch the game
+detects the emulator byte order and converts it in place, keeping a backup of
+the original file next to it as `ge007.eep.emulator.bak` (never overwriting an
+existing one). Any slot that is corrupt in both formats is left alone and gets
+reset by the game, exactly as before. An existing port save is untouched.
+
+To take a save back into an emulator, use the small converter that ships in
+the release folder as `tools/eep_convert.py`
+(`tools_pc/eep_convert.py` in a source checkout; plain Python 3, no
+dependencies):
+
+```sh
+python tools/eep_convert.py pc-to-n64 data/ge007.eep back-to-emulator.eep  # port -> emulator
+python tools/eep_convert.py verify some-file.eep    # which format is this?
+```
+
+`verify` checks every save checksum and, without `--as n64|pc`, tells you
+which convention the file uses.
+
+## Uninstalling
+
+Delete the folder. The port writes nothing anywhere else, so that removes the
+game, your save and your settings; back up `data/ge007.eep` first if you
+want to keep your progress.
+
+## Troubleshooting
+
+- **The game says the ROM is missing or wrong:** check it is in `data/`, named
+  `ge007.ntsc-final.z64`, in `.z64` byte order, and that its SHA-1 matches the
+  US row in [What's a ROM?](#whats-a-rom). PAL and JP ROMs are not supported
+  yet.
+- **Windows shows a SmartScreen warning:** the exe is not code-signed. Click
+  **More info**, then **Run anyway**.
+- **Black screen or no window:** update your graphics driver; the port needs
+  OpenGL 3.0.
+- **Wrong resolution on the Steam Deck:** F10 → *Video → Resolution*.
+- **Where are my saves?** `data/ge007.eep`. Copy it somewhere safe while the
+  game is not running to back it up.
+- **The game crashes:** open an
+  [issue](https://github.com/jkdansereau/goldeneye-pc-port/issues/new/choose)
+  and attach `ge007.crash.log` (in the folder you launched from), the output of
+  `--version`, your OS, your GPU and your ROM's SHA-1. **Never attach the ROM
+  itself.**

pi/README.md

@@ -0,0 +1,64 @@
+# pi/ — agent-development tooling (local, not part of the game build)
+
+This directory is a [pi package](https://pi.dev/packages) for the
+LLM-agent workflow of this repo — it is **not** part of the game build
+(never add it to `CMakeLists.txt`). It exists because the 2026-10-09
+session forensics on the #150 cull hunt (see `docs/dev-process.md` §8
+and the `Tooling workstream` row in `docs/ROADMAP.md` §7) showed the
+loss mode is model + discipline, not retrieval.
+
+**Install (per machine):**
+
+```sh
+pi install ./pi                      # local package: agents + compaction-ledger
+pi install npm:pi-subagents@0.76.1   # the subagent runtime (pinned; audit: docs/dev/notes/)
+```
+
+`.pi/` is gitignored, so the install declarations land in machine-local
+settings; the reviewable source of truth is this directory, committed.
+
+**What it provides**
+
+- `agents/` — four model-pinned subagent roles (via `pi-subagents`), all on the
+  standing **ninfer** backend (only one of ninfer/strata runs at a time;
+  children inherit the running backend, so pins must match it):
+  - `build-runner` — `./build-pc.sh` + capture + golden sweep, reports
+    pass/fail. `ninfer-windows/qwen3.8-27b-nvfp4full` (fast 4-bit).
+  - `pairing` — D579T-style log pairing (E-rows vs C-rows by x/y/w),
+    names candidate cull rules, read-only. `model: inherit` — the
+    reasoning step, so it follows the parent session's tier; run the
+    parent on a strong model when doing D579 diagnosis.
+  - `sweep-watcher` — watches long golden-sweep runs, triages new vs
+    regressed frames. `ninfer-windows/qwen3.8-27b-nvfp4full`.
+  - `doc-sync` — ROADMAP rows, findings-index.csv, findings.md §F index
+    after a verified change. `ninfer-windows/qwen3.8-27b-nvfp4full`.
+
+  Note: NInfer serves one model per launcher — `ninfer-coding.bat`
+  (4-bit `qwen3.8-27b-nvfp4full`) is the standing default; the
+  `ninfer-quality.bat` launcher serves the ≈6-bit groupwise-int
+  `qwen3.8-27b` as the strong local tier (a launcher restart + new pi
+  session, not a backend switch). If a better/faster artifact appears in
+  the closed NInfer set, promote the labor-role pins to it.
+
+  Model pins live in each agent file's frontmatter (`model:
+  provider/model`) — keep them here, not in untracked settings, so the
+  pins are reviewable, and keep them on the standing backend (ninfer).
+  Planning/diagnosis stays on the parent session's strong model
+  (`openrouter/deepseek/deepseek-v4-pro`, or `strata-coder-hard` with the
+  local backend switched); only mechanical labor goes to these agents.
+
+- `extensions/compaction-ledger/` — overrides the compaction summary
+  with an evidence-ledger prompt (every live hypothesis must be tagged
+  `refuted` / `unvalidated` / `validated (<artifact>)`; "diagnosed"
+  without a maintainer A/B or golden sweep is forbidden) and, when
+  `GE_COMPACT_MODEL` is set (e.g. `openrouter/deepseek/deepseek-v4-pro` or
+  `strata/strata-coder-hard`), summarizes with that
+  stronger model instead of the session model. The 01a11ec6 session
+  lost the evening because a mid-session compaction promoted an
+  unvalidated hypothesis to "diagnosed" and the post-compaction turns
+  built on it.
+
+Rules for anything added here: machine paths are forbidden (tree
+hygiene), third-party deps are forbidden without a ROADMAP §7 approval
+row (like `pi-subagents`), and `src/game` is still read-only ground
+truth for every agent.

pi/agents/build-runner.md

@@ -0,0 +1,27 @@
+---
+name: build-runner
+description: Runs ./build-pc.sh, verifies the exe, runs capture + golden sweep, reports pass/fail with log tails. Never edits code.
+tools: bash, read
+model: ninfer-windows/qwen3.8-27b-nvfp4full
+---
+
+You are the build-runner for the GoldenEye 007 PC port. Your single job:
+build, run, capture, sweep, report. You do NOT edit or write any source
+file, and you do NOT diagnose — you report facts.
+
+Procedure (the task gives you the region and the level):
+1. `./build-pc.sh <region>` (ntsc-final | pal-final | jpn-final). If the
+   build fails, capture the last 60 lines of the error and STOP.
+2. Run the capture command the task gives you (or the standard
+   `tools_pc/sweep` invocation) and let it finish.
+3. Run the golden sweep / framediff pass the task names; collect the
+   per-frame verdicts (pass / new-diff / regressed).
+4. Report: region, exe timestamp, pass/fail counts, the list of
+   regressed frames with their diff sizes, and any crash log tail.
+   End with one line: `VERDICT: PASS` or `VERDICT: FAIL (<count> regressed)`.
+
+House rules: no commits, no pushes, no edits outside capture output
+dirs. Machine paths in your report must use the placeholder legend from
+`docs/dev/HANDOFF-ARCHIVE.md` (`<repo>`, `<games>`, `<python>`, `<temp>`).
+If the game process is locking the exe (link "Permission denied"),
+report it — do not kill user processes.

pi/agents/doc-sync.md

@@ -0,0 +1,31 @@
+---
+name: doc-sync
+description: After a verified change, syncs docs/ROADMAP.md rows, docs/dev/findings-index.csv, and the findings.md §F index. Never invents findings.
+tools: read, write, edit, bash
+model: ninfer-windows/qwen3.8-27b-nvfp4full
+---
+
+You are the doc-sync agent for the GoldenEye 007 PC port. You keep the
+documentation layer in sync AFTER a change is verified (golden sweep +
+maintainer A/B where applicable). You never invent findings or change
+status of work you have not been told about.
+
+Scope per task (the task names the change and its evidence):
+1. `docs/dev/findings.md` — if a new Dxx finding was recorded, check
+   the §F/§H index entry exists; regenerate `docs/dev/findings-index.csv`
+   with `python tools_pc/gen_findings_index.py` (verify the CSV matches
+   the labels in findings.md).
+2. `docs/ROADMAP.md` — update the row(s) the task names: status
+   vocabulary only (`open` / `partial` / `verify` / `parked` /
+   `decision`), refs as Dxx/#issue links, one row per item; delete rows
+   that are closed (their content moves to findings.md if not already
+   there). Never create a new backlog file.
+3. If the task says so: the README "Status" section (current release
+   state only) and `docs/dev/LEVEL-STATUS.md` if a level changed.
+
+House rules: batch all doc edits into the commit the task names (one
+commit, not one per item); no local machine paths (placeholder legend
+in `docs/dev/HANDOFF-ARCHIVE.md`); no contributor emails in prose; pure
+site pages under `docs/` (index.md, fidelity.md, etc.) are a
+presentation layer — do NOT edit them to match working docs and do not
+treat their staleness as a bug.

pi/agents/pairing.md

@@ -0,0 +1,29 @@
+---
+name: pairing
+description: Pairs D579T-style probe logs (E-rows vs C-rows by x/y/w) and names candidate cull rules. Read-only analysis.
+tools: bash, read
+model: inherit
+---
+
+You are the pairing analyst for the GoldenEye 007 PC port's #150 cull
+investigation (D579). You pair two probe logs and name candidate cull
+rules. You are READ-ONLY: no edits, no builds, no game runs — bash is
+for `awk`/`sort`/`join`-style offline processing of log files only.
+
+Method (the task names the two log files, e.g. `GE_X_NOCULL=1` vs
+default with `GE_D579T=1`):
+1. Parse the E-rows (wall-visible, should-be-drawn) and C-rows
+   (culled) with their x/y/w fields.
+2. Match culled C-objects to wall-visible E-objects by (x, y, w) with a
+   small tolerance; report the match rate and the unmatched sets.
+3. From the geometry of the matched/mismatched sets, state the
+   candidate cull rule that would explain them (e.g. "C set = E set
+   minus objects with w < 24 and y < horizon").
+4. Output: a table of the paired rows, the match statistics, and the
+   candidate rule(s) ranked by how many rows they explain. Do not
+   declare a rule validated — validation is the golden sweep + a
+   maintainer A/B.
+
+House rules: `src/game` is ground truth and read-only; cite the exact
+log lines (line numbers) behind every claim; keep machine paths to the
+placeholder convention.

pi/agents/sweep-watcher.md

@@ -0,0 +1,28 @@
+---
+name: sweep-watcher
+description: Watches a long golden-sweep run in the background, triages new vs regressed frames against golden baselines, writes a triage table.
+tools: bash, read, write
+model: ninfer-windows/qwen3.8-27b-nvfp4full
+---
+
+You are the sweep-watcher for the GoldenEye 007 PC port. You monitor
+long-running golden-sweep / capture jobs and triage their results. You
+may write ONE triage file (the task names it); you do not edit source,
+run builds, or start game sessions yourself.
+
+Procedure:
+1. Poll the sweep's output dir / log the task names until it finishes
+   (bounded: report and stop if it runs past the task's deadline).
+2. Compare each frame against its golden baseline
+   (`tools_pc/golden/<level>/{win,linux,deck}/`); classify every
+   non-identical frame as NEW-DIFF (was passing) or REGRESSED (worse
+   than the previous sweep's triage file, if given).
+3. Write the triage table: frame, level, platform, status, diff size,
+   one-line guess only if obvious from the diff stats (never
+   "diagnosed" — diagnosis needs a parent session with context).
+4. Report: counts by status, the worst 5 frames, and the triage file
+   path. End with `VERDICT: CLEAN` / `VERDICT: N REGRESSIONS`.
+
+House rules: capture output dirs are gitignored — write the triage file
+where the task says (typically `docs/dev/notes/`), use placeholder
+paths, and never commit or push anything.

pi/extensions/compaction-ledger/index.ts

@@ -0,0 +1,241 @@
+/**
+ * Evidence-ledger compaction for the GoldenEye 007 PC port (pi/ package).
+ * Targets the installed pi 1.0.2 extension API (SessionBeforeCompactResult);
+ * the first-party examples/ in the npm package target a newer API — do not
+ * copy from them without re-checking dist/core/extensions/types.d.ts.
+ *
+ * What it does:
+ *
+ *  1. Overrides the compaction summary with an evidence-ledger prompt: every
+ *     live hypothesis about the bug being worked gets one line tagged
+ *     refuted / unvalidated / validated(<artifact>). "Diagnosed" is
+ *     forbidden without a maintainer A/B or a passing golden sweep.
+ *     Motivated by pi session 01a11ec6 (the #150 cull hunt): the 04:52Z
+ *     compaction promoted an unvalidated hypothesis to "diagnosed" and the
+ *     post-compaction turns built the next three fix candidates on that
+ *     false premise.
+ *
+ *  2. When GE_COMPACT_MODEL is set (fully-qualified "provider/model", e.g.
+ *     "strata/strata-coder-hard" or "openrouter/deepseek/deepseek-v4-pro"),
+ *     the summarization runs on that stronger model instead of the session
+ *     model. Unset -> the session model (labor on a fast local model,
+ *     compaction on a strong one).
+ *
+ * Failure mode is safe by design: if the custom summarization throws (model
+ * down, no API key, shape drift after a pi upgrade), the handler returns
+ * nothing and pi's built-in compaction proceeds unchanged.
+ *
+ * GE_COMPACT_LEDGER=0 disables the extension's override entirely.
+ */
+import { completeSimple } from "@earendil-works/pi-ai/compat";
+import type { Model } from "@earendil-works/pi-ai";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  SessionBeforeCompactEvent,
+  SessionBeforeCompactResult,
+} from "@earendil-works/pi-coding-agent";
+
+const EVIDENCE_LEDGER_PROMPT = [
+  "The summary MUST start with a section titled `Evidence ledger`. For every",
+  "live hypothesis or open claim about the bug/work item being pursued, write",
+  "exactly one line in this form:",
+  "  - <claim> -- refuted | unvalidated | validated (<artifact>)",
+  "where <artifact> is a concrete check: a named log file, a golden-sweep",
+  "frame, a maintainer A/B, or a commit. Rules:",
+  '  - A fix that has not passed a maintainer A/B or a golden sweep is',
+  '"unvalidated", never "diagnosed" or "root-caused".',
+  "  - Carry forward the previous summary's ledger lines that are still live;",
+  "    do not drop a refutation just because it was summarized before.",
+  "After the ledger, include: the uncommitted-tree state (files, which work",
+  "item each belongs to), the next concrete step, and -- if the session's",
+  "brief had a BUDGET line -- the remaining budget.",
+].join("\n");
+
+const SUMMARY_SYSTEM = [
+  "You are writing the context-compaction summary for a coding-agent session.",
+  "Produce a compact, dense handoff summary that a fresh session can resume",
+  "work from. Preserve: the active task, refuted hypotheses (so they are not",
+  "retried), the uncommitted tree state, standing environment rules, and the",
+  "next concrete step. No filler, no restating this instruction.",
+].join("\n");
+
+// ---------------------------------------------------------------- transcript
+
+type Msg = { role?: string; content?: unknown; toolName?: string; [k: string]: unknown };
+
+function contentText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((p) => {
+        if (p && typeof p === "object") {
+          const o = p as Record<string, unknown>;
+          if (o.type === "text") return (o.text as string) ?? "";
+          if (o.type === "toolCall" || o.type === "tool_use")
+            return `[tool call: ${(o.name as string) ?? "?"}]`;
+          if (o.type === "image" || o.type === "image_url") return "[image]";
+        }
+        return "";
+      })
+      .join(" ");
+  }
+  return "";
+}
+
+function truncate(s: string, n: number): string {
+  return s.length <= n ? s : s.slice(0, n) + ` [${s.length - n} chars elided]`;
+}
+
+function digestMessages(messages: Msg[], capChars: number): string {
+  const lines: string[] = [];
+  let budget = capChars;
+  for (const m of messages) {
+    const role = m?.role ?? "unknown";
+    let text = contentText(m?.content).replace(/\s+/g, " ").trim();
+    if (role === "toolResult" || m?.toolName) text = truncate(text, 400);
+    const line = `[${role}] ${text}`.trim();
+    if (budget - line.length - 1 < 0 && lines.length > 0) {
+      lines.unshift(`[... ${messages.length - lines.length} earlier messages elided ...]`);
+      break;
+    }
+    budget -= line.length + 1;
+    lines.push(line);
+  }
+  return lines.join("\n");
+}
+
+function buildLedgerPrompt(
+  prep: SessionBeforeCompactEvent["preparation"],
+  extraInstructions: string | undefined,
+): string {
+  const sections: string[] = [];
+  if (prep.previousSummary) {
+    sections.push(
+      "## Previous compaction summary (update it; carry forward still-live ledger lines)\n" +
+        prep.previousSummary,
+    );
+  }
+  sections.push(
+    `## Transcript to summarize (${prep.messagesToSummarize.length} messages)\n` +
+      digestMessages(prep.messagesToSummarize as Msg[], 24000),
+  );
+  if (prep.turnPrefixMessages?.length) {
+    sections.push(
+      `## Split-turn prefix (${prep.turnPrefixMessages.length} messages)\n` +
+        digestMessages(prep.turnPrefixMessages as Msg[], 8000),
+    );
+  }
+  if (extraInstructions) {
+    sections.push(`## Extra custom instructions\n${extraInstructions}`);
+  }
+  sections.push(EVIDENCE_LEDGER_PROMPT);
+  return sections.join("\n\n");
+}
+
+// ------------------------------------------------------------------- models
+
+function pickSummarizer(ctx: ExtensionContext): Model<any> | undefined {
+  const spec = process.env.GE_COMPACT_MODEL?.trim();
+  if (spec) {
+    const i = spec.indexOf("/");
+    if (i > 0 && i < spec.length - 1) {
+      const m = ctx.modelRegistry.find(spec.slice(0, i), spec.slice(i + 1));
+      if (m) return m;
+      try {
+        ctx.ui.notify?.(`compaction-ledger: GE_COMPACT_MODEL "${spec}" not found; using session model`, "warning");
+      } catch {
+        /* headless */
+      }
+    }
+  }
+  return ctx.model;
+}
+
+function extractSummaryText(resp: unknown): string {
+  const r = resp as { content?: unknown };
+  if (Array.isArray(r?.content)) {
+    return (r.content as Array<Record<string, unknown>>)
+      .filter((p) => p?.type === "text")
+      .map((p) => (p.text as string) ?? "")
+      .join("");
+  }
+  return typeof r?.content === "string" ? (r.content as string) : "";
+}
+
+// -------------------------------------------------------------------- entry
+
+export default function (pi: ExtensionAPI): void {
+  pi.registerCommand("compact-ledger", {
+    description: "Compact now with the evidence-ledger summary prompt (usage: /compact-ledger [extra instruction])",
+    handler: async (args: string, ctx: ExtensionContext) => {
+      const instructions = [
+        EVIDENCE_LEDGER_PROMPT,
+        args ? `Additional user instruction: ${args}` : "",
+      ]
+        .filter(Boolean)
+        .join("\n");
+      ctx.compact({
+        customInstructions: instructions,
+        onError: (err) => {
+          try {
+            ctx.ui.notify?.(`compaction failed: ${err.message}`, "error");
+          } catch {
+            /* headless */
+          }
+        },
+      });
+      try {
+        ctx.ui.notify?.("Compaction started (evidence ledger)", "info");
+      } catch {
+        /* headless */
+      }
+    },
+  });
+
+  pi.on("session_before_compact", async (event, ctx): Promise<SessionBeforeCompactResult | undefined> => {
+    if (process.env.GE_COMPACT_LEDGER === "0") return; // opt-out: built-in compaction
+    const prep = event.preparation;
+    const model = pickSummarizer(ctx);
+    if (!model) return; // no model resolvable -> built-in compaction
+    try {
+      const prompt = buildLedgerPrompt(prep, event.customInstructions);
+      const maxTokens = Math.min(8192, Math.max(2048, Math.floor(((model as { maxTokens?: number }).maxTokens ?? 4096) / 2)));
+      const resp = await completeSimple(
+        model as never,
+        {
+          systemPrompt: SUMMARY_SYSTEM,
+          messages: [{ role: "user", content: prompt }],
+        },
+        { signal: event.signal, maxTokens, temperature: 0.2 },
+      );
+      const summary = extractSummaryText(resp);
+      if (!summary.trim()) throw new Error("summarizer returned an empty summary");
+      try {
+        ctx.ui.notify?.(
+          `Compaction complete (evidence ledger): ${prep.tokensBefore} -> ~${Math.ceil(summary.length / 4)} tokens`,
+          "info",
+        );
+      } catch {
+        /* headless */
+      }
+      return {
+        compaction: {
+          summary,
+          firstKeptEntryId: prep.firstKeptEntryId,
+          tokensBefore: prep.tokensBefore,
+        },
+      };
+    } catch (err) {
+      try {
+        ctx.ui.notify?.(
+          `compaction-ledger: custom summarization failed (${(err as Error).message}); using built-in compaction`,
+          "warning",
+        );
+      } catch {
+        /* headless */
+      }
+      return; // undefined -> pi's built-in compaction takes over
+    }
+  });
+}