Docs: README, release notes and user docs restructured for v0.6.0

- README in the shape of the top decomp/recomp ports: title, one-paragraph pitch, latest-release link, a single no-assets line; then Requirements, Quick start, Controls, What this port offers, FAQ (new), Status, Roadmap, Building, Documentation, Contributing, Credits, Legal. 852 -> ~370 lines. - Moved, not removed: docs/user-guide.md (full controls, feature list, settings and files, ROM check, macOS setup, updating, emulator saves, uninstalling, troubleshooting) and docs/about.md (release history, status in detail, how it was made with the models/tools table, how it works, the comparison with the XBLA projects). - Release notes: upgrade and code-signing callouts, Highlights, Downloads, Getting started, Added/Fixed/Changed without internal finding labels, a shorter known-issues list, Tested on, Thanks, Verify (incl. attestation). - ROADMAP: v0.7.0 rows for the macOS first-launch black window and the pixel gate vs the Auto frame-cap default. building.md: ROM table link.
2026-10-13 10:47:31 -04:00
1 parent cdf43d0140
commit 1ca5eb197e
@@ -5,238 +5,152 @@
  <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)**, plus
-an **experimental macOS Apple Silicon** download (not notarized; see
-[Running it](#running-it)). Region: **NTSC-U (US) only**. See [Known issues](#known-issues).
+> [!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.
+
+> [!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

-This release is v0.5.0 plus frame rates above 60, an experimental macOS port
-and a batch of fixes.
-
- **Frame rates above 60.** The *Frame rate cap* (`Video.FpsCap`) now offers
-  **90, 120, 144, 165 and 240**, and an **Auto** setting that matches your
-  display's refresh rate (up to 240). Auto is the default on fresh installs; an existing
-  `ge007.ini` keeps its value. Extra frames are blended between game ticks, so
-  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*
-  display mode caps at 60. This is my rework of f1zz1ec0ke's #137.
- **macOS on Apple Silicon (experimental).** There is now a
-  `macos-arm64` download (or build from source; see `docs/building.md`). Based
-  on danturn's #95. A 21-level campaign sweep and live sessions ran without
-  crashes on one M3 Mac, but it has not had the wider testing the Windows and
-  Linux builds have, and the download is not notarized. Test reports are very
+- **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. 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.
- **Fixes you can see:** geometry vanishing when you stand against a wall
-  (#150), the Cradle catwalk shadow flicker, stale pixels beside the
-  native-widescreen picture on front-end screens, and the first launch opening
-  on the wrong monitor (#151).
- **Crash fixes:** the Linux end-credits crash (#152) and a crash when a guard
-  spawned wearing a hat (#153, #156).
 - **Original controls are now original (#145, #149).** With *Control style*
-  set to Original, a gamepad behaves as an N64 controller: South is A, West is
-  B, and the game decides what each button does, so B opens a door or reloads
-  (not both), A changes weapon, and B goes back in menus. *Invert look* works in
-  every original style and stays in sync with the watch's *Look up/down*.
- **Mission timer (#144)**, the file-select crest drawing on a dark square
+  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 Linux end-credits crash (#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 exit crash.

-Checked on PC at 120 Hz with VSync on a G-Sync display, and on the Steam Deck
-at 90 fps.
-
---
-
-## What's new
-
-### Frame rate
-
- **Auto, 90, 120, 144, 165 and 240** join 30 and 60 in the F10 *Frame rate cap* row.
-  Above 60 the port draws extra frames between game ticks by blending the
-  previous and current frame. It only applies when the display is faster than
-  60 Hz; on a 60 Hz display nothing changes.
- A fresh install uses **Auto**, so a 90 Hz screen runs at 90, a 144 Hz
-  monitor at 144 and a 240 Hz monitor at 240 (faster displays hold at 240).
-  The *Original N64* display mode sets the cap to 60.
- A fast camera turn, or a large change in what is on screen, falls back to a
-  full frame instead of a blend.
- The Steam Deck at 90 is good on most levels (see the known issues).
-
-### macOS (Apple Silicon, experimental)
-
- On arm64 macOS the N64 address window sits at a high host base (set
-  automatically by CMake). The 64-bit address fixes this needed (textures,
-  input, animation and multiplayer crashes) are in the shared code and have no
-  effect at base 0 on Windows and Linux.
- There is a `macos-arm64` download, or build from source with Homebrew's
-  GNU `gcc`. The x86_64 macOS code (Julio C. Rocha's #88) is in the tree but was never
-  verified on Intel hardware.
-
-### Controls
-
- **Original control style = an N64 controller** (D643). Every press sends the
-  real N64 button in levels, menus, the watch and the tank; no port-only
-  actions are added. Default layout: South = A, West = B, right trigger = Z,
-  left trigger / RB = R, LB = L, right stick = C-buttons, D-pad and Start as
-  is. Each N64 button can be moved per player in `ge007.ini`
-  (`Input.N64Pad.A = a`, `Input.N64Pad2.B = x`, ...). `Input.N64StickFeel = 1`
-  (default in Original) gives the N64's linear stick range; 0 keeps the
-  previous feel. The Modern style and keyboard/mouse are unchanged.
- **Invert look** reaches every original style (D605) and, in Original, is the
-  same setting as the watch's *Look up/down* (D645).
-
-### Settings and diagnostics
-
- **Mission timer** (D606, #144): an optional always-visible timer, off by
-  default (F10).
- F10 dropdowns stay inside the settings box instead of covering the help
-  text (D646).
- Windows: per-monitor DPI awareness, so fullscreen on a scaled 4K display is
-  native resolution (D626); exclusive fullscreen uses the desktop mode (D639).
-
- The old front-end **Velocity** pointer mode is removed; the retired ini keys
-  are ignored quietly (D574).
- The Linux/macOS **update check** no longer fails on a response over 64 KB
-  (D575).
- Every log line is also written to **`ge007.log`** next to the ini; the
-  previous run is kept as `ge007.prev.log` (D576).
- F10 slider labels no longer end in ".." at HUD scale 150 (D577).
- The crosshair look (colour, size, style, alpha, health colour) is your
-  preference and is no longer reset by the *Display mode* presets (D440).
- The sound-effect and text-bank pointer guards check the real address range,
-  so they work at any address base (D573, #108 with italoarruda).
-
---
-
-## Install and upgrade
-
-### Downloads
+## Downloads

 | File | Platform |
 |---|---|
-| `goldeneye-pc-port-<version>-win64.zip` | Windows x86-64 |
-| `goldeneye-pc-port-<version>-linux-x86_64.tar.gz` | Linux x86-64 (incl. Steam Deck) |
-| `goldeneye-pc-port-<version>-macos-arm64.tar.gz` | macOS Apple Silicon, experimental |
+| `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
-one-time asset tool. **No ROM, no game assets.** The Windows bundle carries
-its runtime DLLs and the Linux bundle carries SDL2, so nothing needs to be
-installed first. The Linux bundle runs on glibc 2.31 or newer (Ubuntu 20.04+,
-Debian 11+, SteamOS). The macOS bundle carries SDL2 and the C++ runtime and
-needs an M1 or later Mac on macOS 14 or newer.
+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 need your own **GoldenEye 007 N64 ROM** (US version, `.z64`).
-
-1. Unpack the archive.
-2. Make a `data/` folder next to the executable and put the ROM in it, named
+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. Run the executable from that folder. The first start takes a few extra
-   seconds while it generates its asset files from your ROM.
+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.

-**Updating from an earlier version:** unpack into a new folder and copy your
-ROM, `ge007.eep` (your progress) and `ge007.ini` (your settings) into its
-`data/` folder. Don't copy the old `pcmodels-*` / `pccg-*` folders: the new
-version makes its own.
+**Steam Deck:** do the steps on the Deck, then add the executable as a
+non-Steam game.

-**macOS (experimental):** the app is not signed with a Developer ID or
-notarized, so Gatekeeper blocks a downloaded copy. After unpacking and before the
-first launch, run this once in Terminal, then start `./ge007.aarch64` from
-the folder:
+**macOS:** the app isn't notarized, so run this once in Terminal before the
+first launch, then start `./ge007.aarch64` from the folder. If the window ever
+stays black on the first start, close it and start it again.

 ```
 xattr -dr com.apple.quarantine goldeneye-pc-port-<version>-macos-arm64
 ```

-Or download it in Terminal, which skips the block entirely (`curl` does not
-mark the file for Gatekeeper):
+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 the first launch is blocked, open System Settings →
+Without Terminal: after macOS blocks the first launch, open System Settings →
 Privacy & Security and click **Open Anyway** next to the `ge007.aarch64`
 message.

-I have only run it on one M3 Mac, so please report what Mac and macOS you
-tried and what happened.
+The [user guide](https://github.com/jkdansereau/goldeneye-pc-port/blob/release/v0.6.0/docs/user-guide.md)
+covers controls, settings, emulator saves and troubleshooting.

-**Steam Deck:** do the steps above on the Deck, then add the executable as a
-non-Steam game. The options overlay opens with **Select** and is fully
-controller-driven.
+## What's new

-Full steps, controls and troubleshooting are in the bundled `README.md`.
+### 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), which 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).
+- The first launch opening on the wrong monitor (#151).
+- A Linux crash during the end credits (#152).
+- 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 crash on exit on some Windows GPUs.
+- 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; exclusive fullscreen uses the desktop mode.
+- 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 | Impact | Workaround |
-|---|---|---|
-| On the Steam Deck at 90 fps, firefights in the centre of Bunker 1 and 2 can drop several fps | Performance, Deck only | Set the frame cap to 60 for those levels |
-| Jungle can feel slightly less smooth at 90 fps than other levels | Feel | Frame cap 60 |
-| Cradle's turret explosions may draw wrongly | Cosmetic; reported, not yet investigated | None |
-| After alt-tabbing away, the picture can look hazy until it settles; fast repeated alt-tab is wonkier and takes longer | Cosmetic, Windows | It recovers on its own; alt-tab again or give it a couple of seconds |
-| macOS: the end credits may crash | Ending only, macOS only | Your progress is already saved by then |
-| macOS (Apple Silicon) is experimental, tested on one Mac, and not notarized | Platform | Run `xattr -dr com.apple.quarantine <folder>` before the first launch; reports welcome |
-| 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; packaging is still open |
-| Changing aspect ratio inside a level can briefly glitch the gun/hand model, rarely | Cosmetic, one-off | Change the ratio from the front-end PC Options, or accept it |
-| 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 |
-| The first frame of a level takes a little longer while its textures upload | Brief FPS-counter dip | None needed |
-| Far objects almost fully in fog are now hidden as on the N64, except in widescreen where a faint distant building edge can still show (e.g. Surface's dish from the start area); 4:3 matches the N64 | Cosmetic | Higher Draw/LOD distance shows more |
+| 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 |
+| macOS: the end credits may crash | Your progress is already saved by then |
+| 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 |

-Faithful original-game quirks are not port bugs. The full list, with
-workarounds, is the
+The full list is the
 [known-issues table](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/ROADMAP.md#known-issues).

---
+## Tested on

-## Fixes and changes, with finding labels
-
- **Frame interpolation above 60 fps** (D578, rework of #137). 120 fps with
-  VSync on G-Sync/VRR: black frames and OLED flicker fixed (D583). Steam Deck
-  90 Hz pacing (D583).
- **#150 geometry disappearing when too close to a wall:** the near-plane clip
-  now cuts at the camera plane (D579).
- **Cradle catwalk shadow flicker:** a D579 regression, fixed (D584).
- **Native-widescreen stale pixels** on front-end screens: the canvas sides are
-  cleared (D579 follow-up).
- **#151** the first launch opens on the primary monitor (D581).
- **#152** Linux end-credits crash: a garbage text pointer is rejected (D582).
- **#153, #156** hat-spawn crash: the object record type and the end-of-list
-  marker were read from the wrong byte on a little-endian machine, so the search
-  could run past the end of the list (D580).
- **#108** SFX / text-bank pointer guards (D573).
- **#145 / #149** Original control style as an N64 controller (D643); Invert
-  look in the original styles (D605, D645).
- **#144** mission timer (D606).
- **#146** file-select crest on a dark square: 4-bit IA textures now decode as
-  the N64 does (D644).
- **Exit crash (BSOD 0x119) on some Windows GPUs:** the GL context and window
-  are released before the process exits (D632).
- Windows DPI awareness (D626), exclusive fullscreen mode (D639), F10 dropdown
-  placement (D646).
- Velocity removal, update-check fix, `ge007.log`, HUD-150 sliders, preset
-  scope (D574-D577, D440).
- **macOS arm64:** one address-model header, the 64-bit pointer fixes and a
-  display-locked tick (D586, D591, D594, D595, D599-D604, D607-D613).
-
-## Verification
-
-Windows: the 21-level reference-frame sweep passes (Streets sits at the edge of
-its tolerance and flips run to run with or without this release's changes).
-Steam Deck and macOS: all 21 levels load, play and quit without a crash (their
-reference frames are not yet comparable, so no pixel check). The fixes above
-were also checked by playing on Windows, with the original controls compared
-against the issue reports rather than an N64 pad.
+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), dolent (#120-#123, already in v0.5.0), plus reporter
-credits on the issue numbers named above.
+italoarruda (#108), and everyone who reported the issues above.

 ## Verify the download

@@ -244,16 +158,13 @@ credits on the issue numbers named above.
 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), with its
-architecture modelled on 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. See the README's
-[How it was made](https://github.com/jkdansereau/goldeneye-pc-port#how-it-was-made)
-section 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/release/v0.6.0/docs/about.md#how-it-was-made).
@@ -1,177 +1,86 @@
-# 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)
-[![Latest release](https://img.shields.io/github/v/release/jkdansereau/goldeneye-pc-port?include_prereleases&label=download)](https://github.com/jkdansereau/goldeneye-pc-port/releases)
-![Platforms](https://img.shields.io/badge/platforms-Windows%20%7C%20Linux%20%7C%20Steam%20Deck-blue)
-![license](https://img.shields.io/badge/license-MIT-ffb454)
+<h1 align="center">GoldenEye 007 PC Port</h1>

-**GoldenEye 007 (Nintendo 64, 1997) as a native PC game for Windows, Linux
-and Steam Deck.** Native widescreen, 60 fps or higher (up to 240 on fast
-displays), split-screen for up to 4 players, mouse and keyboard or a modern controller, rebindable controls
-and an in-game options menu. No
-emulator, and not a binary recompilation: the game's own
-reconstructed C, rebuilt from the
-[GoldenEye 007 decompilation](https://github.com/n64decomp/007), compiled
-for your PC and running from your own ROM.
+<p align="center">
+  The original Nintendo 64 GoldenEye 007 (1997) as a native game for Windows,
+  Linux, Steam Deck and macOS.
+</p>

-**[Download the latest release](https://github.com/jkdansereau/goldeneye-pc-port/releases)**,
-then follow the [Quick start](#quick-start).
+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.

-[Quick start](#quick-start) · [What it offers](#what-this-port-offers) · [Controls](#controls) · [Features](#features) · [Settings and files](#settings-and-files) · [Troubleshooting](#troubleshooting) · [Roadmap](#roadmap) · [Building](#building-from-source) · [Legal](#legal)
+### [Download the latest release](https://github.com/jkdansereau/goldeneye-pc-port/releases/latest)

-> [!IMPORTANT]
-> **You must supply your own GoldenEye 007 ROM.** This repository and its
-> downloads contain no ROM data and none of the original assets; the C source
-> is the community's reconstruction of the game's code (see `NOTICE`). See
-> [What's a ROM?](#whats-a-rom) and [Legal](#legal).
-
-**v0.6.0** is the current release. It is a **pre-1.0 release, not a
-finished product**: the campaign and split-screen multiplayer play end to
-end, but expect missing pieces (PAL/JP ROMs, a notarized macOS build) and the occasional
-breaking change between versions. v1.0 is the target for a feature-complete
-build.
-
-**AI disclosure:** this port was developed using AI coding agents (Claude
-Code and a local open-weight model), directed by one person in their spare time. The
-project is as much a study of that process as it is a port. See
-[How it was made](#how-it-was-made).
+**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="~29 s gameplay montage from live v0.5.0 play sessions">
-  <br><em>All in-engine, running in the port: a ~29&nbsp;s montage from live
-  v0.5.0 play sessions (the Facility intro, auto-aim in the Archives,
-  the crosshair options and the Dam sniper rifle, Silo, a 2-player rocket kill,
-  the Facility bathroom, the Dam ending) ·
-  <a href="docs/index.md">14 stills in the project index</a></em>
+       alt="A short gameplay montage recorded in the port">
+  <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
+- [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)

- **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](docs/building.md)). Based
-    on danturn's #95 (with Julio C. Rocha's earlier Intel groundwork in
-    #88). A campaign sweep and live sessions ran without crashes on one M3
-    Mac; the download is not notarized, so see [macOS](#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 Linux crash in the
-    end credits (#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, and stale watch pixels in native widescreen.
-  - **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 Windows exit-crash fix.
-  - **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.
+## Requirements

---
-
-## System requirements
-
-**Windows:** Windows 10 or 11, 64-bit. Nothing else to install: the
-download carries its own runtime libraries and the one-time asset tool (no
-Python, no emulator).
-
-**Linux / Steam Deck:** 64-bit x86 Linux with glibc 2.31 or newer (Ubuntu
-20.04+, Debian 11+, Fedora 32+, SteamOS). SDL2 is bundled, so
-the tarball runs as-is; it sideloads onto a Steam Deck with nothing installed.
-
-**Both:** a GPU with OpenGL 3.0 drivers (practically any PC GPU from the last
-fifteen years; keep the driver up to date). A 2011 laptop with Intel HD
-3000 graphics holds 60 fps; on very weak integrated GPUs (Atom/Celeron class)
-the first launch lowers draw distance and anti-aliasing to keep up. A
-keyboard and mouse, or a controller (Xbox, PlayStation, Switch and most
-SDL-supported pads); split-screen needs one controller per extra player.
-
-**macOS (Apple Silicon, experimental):** an M1 or later Mac on macOS 14 or newer, using the `macos-arm64` download (nothing to install; it is not notarized, so see [macOS](#macos-apple-silicon-experimental) for the one-line unblock) or a [source build](#building-from-source). **Not yet:** ARM Linux and Windows 7 are on the [roadmap](#roadmap).
+- **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.

 ## Quick start

-1. From [Releases](https://github.com/jkdansereau/goldeneye-pc-port/releases),
-   download the **win64.zip** (Windows) or the **linux tarball** (Linux and
-   Steam Deck), and extract it. On Windows, never run the exe from inside the
-   zip.
+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`. Only the **US (NTSC-U)** ROM works today; see
-   [What's a ROM?](#whats-a-rom) to check yours.
-3. Launch the executable from that folder. Windows may show "Windows
-   protected your PC" (SmartScreen, because the exe is not code-signed):
-   click **More info**, then **Run anyway**.
-4. The first start takes a few extra seconds: the port reads your ROM and
-   generates its asset files once. After that it starts normally.
-5. Play. **F10** (pad: **Select**) opens the options overlay; on the file-select
-   screen the *PC Options* entry opens the same overlay. The
-   [Controls](#controls) table lists the default keys.
-
-**Steam Deck:** the Linux tarball is the Deck build. Download it on the Deck
-(or copy it over from your PC), extract it, add your ROM to `data/`, launch
-it once, and add the executable as a non-Steam game. On first start it
-applies Deck-friendly display defaults (native 1280×800 fullscreen); if the
-resolution is wrong, set it under F10 → *Video → Resolution*.
-
---
+   `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`
+     ([details](docs/user-guide.md#macos-apple-silicon-experimental)).
+4. Play. **F10** (controller: **Select**) opens the options menu.

 ## Controls

 | Action              | Keyboard / mouse         | Controller    |
 |---------------------|--------------------------|---------------|
 | Move / strafe       | `W` `A` `S` `D`           | Left stick (or D-pad) |
-| Move / turn         | Arrow keys               | —             |
+| Move / turn         | Arrow keys               | -             |
 | Aim / look          | Mouse                    | Right stick   |
 | Fire                | Left mouse               | Right trigger |
 | Aim mode            | Right mouse / `LShift`   | Left trigger / LB |
@@ -180,72 +89,14 @@ resolution is wrong, set it under F10 → *Video → Resolution*.
 | 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        |
+| Options menu        | `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 preset*). 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 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. **Ext**
-(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 Ext 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 Ext 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 preset* 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.
+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.

 ## What this port offers

@@ -286,427 +137,119 @@ Backspace.
 Bots, online play, mod support and PAL/JP ROMs are on the
 [Roadmap](#roadmap).

-## Features
+The [user guide](docs/user-guide.md#feature-list) has the full 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](docs/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).
- **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)).
+## 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.
+
+**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 ([how](docs/user-guide.md#using-an-emulator-save)), and
+updating keeps your save and settings ([how](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

-**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. v0.6.0 adds
-frame rates above 60 and experimental macOS support; I checked the new
-frame-rate path and the listed fixes by playing on Windows and Steam Deck (120 Hz
-with VSync on a G-Sync display on PC, 90 fps on the Deck), and a macOS
-Apple Silicon build ran the 21-level campaign sweep and live sessions without crashes. The 21-level pixel comparison of reference
-frames against goldens (Windows, Linux, Steam Deck) was last done for v0.5.0. The
-full campaign was last played end to end, at Agent difficulty on all three
-platforms, 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](docs/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](docs/security.md) and [fidelity](docs/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)).
-
---
-
-## Settings and files
-
-**Options overlay:** press **F10** (pad: **Select**) in game or in the menus.
-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`.
-
-## 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.**
-
---
+**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, behaving 1:1 with the original, with modern options on
-top that can always be switched back to the original look and feel. The full
-list of open items, and which ones are waiting on a decision, lives in one
-place: [`docs/ROADMAP.md`](docs/ROADMAP.md). In brief:
+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)). Both
-  regions already convert, build and boot from source.
- **A notarized macOS build, Intel Macs and ARM Linux.** Apple Silicon macOS is
-  an experimental, unsigned download in v0.6.0.
- The remaining small accuracy differences, each checked against the N64
-  game in an emulator.
- **1.0 sign-off**: a full campaign playthrough at more than one difficulty
-  plus a split-screen session, on every platform that ships.
+  ([#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.

-This is spare-time work, so there's no timeline. Opt-in extras beyond the N64
-game (LAN play, bots, co-op, HD textures, enhanced visuals) come after 1.0, and always off by default. Not planned: online
-multiplayer over the internet, achievements or cloud saves, remake-scope
-assets (new models, music or voice), and new movement mechanics. If any of
-these matter to you, open an issue — it helps prioritize.
-
-## 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`](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
-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 |
-
---
+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

-Prerequisites: CMake >= 3.16, a C/C++ toolchain, SDL2, zlib, OpenGL and
-Python 3, plus MIPS binutils, `make` and `git` for the one-time asset
-extraction (no IDO/IRIX toolchain is involved; on Windows the extraction is
-easiest under WSL). See [`docs/building.md`](docs/building.md) for the full
-walkthrough and the asset-extraction details.
-
-### Windows (MSYS2)
+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
-# 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: see docs/building.md
-```
-
-### 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:
+# extract assets from your ROM first (see 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`). To run a source build, create `data/` in the
-repo root, put your ROM in it as in [What's a ROM?](#whats-a-rom), and run
-`./build-pc/ge007.x86_64` from the repo root.
-
-### 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.
-
-**Build from source:** use Homebrew's
-GNU `gcc` (Apple's Clang can't compile the decomp), then the same
-asset-extraction and `./build-pc.sh ntsc-final` steps as above. Details are in
-[`docs/building.md`](docs/building.md).
-
-```sh
-brew install cmake gcc sdl2 zlib python3
-```
-
-On Apple Silicon the executable is tagged `aarch64` instead of `x86_64`.
-
-## 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`](docs/internals.md) and
-[`docs/porting-notes.md`](docs/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
-```
+[`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/ROADMAP.md`](docs/ROADMAP.md) | The single tracker of open work and known issues. |
-| [`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, 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 (game logic stays unmodified), what to verify before a
-pull request, and what a fork is asked to keep.
-
---
+the port faithful, what to check before a pull request, and what a fork is
+asked to keep.

 ## Credits

@@ -763,34 +306,8 @@ This port is a thin layer on a large amount of other people's work.
  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**
-
-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).
+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

@@ -849,4 +366,4 @@ is covered by [`NOTICE`](NOTICE), not by that license.

 ---

-*Last updated 2026-10-13 — v0.6.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>*
@@ -189,6 +189,8 @@ A single campaign pass with these on the checklist would clear most of them.
 | 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). |
@@ -0,0 +1,224 @@
+---
+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). A campaign sweep and live sessions ran without crashes on one M3
+    Mac; 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 Linux crash in the
+    end credits (#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, and stale watch pixels in native widescreen.
+  - **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 Windows exit-crash fix.
+  - **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
+21-level comparison of captured frames against reference images passes on
+Windows. 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 |
@@ -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.

 ---
@@ -0,0 +1,309 @@
+---
+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 preset*). 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 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. **Ext**
+(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 Ext 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 Ext 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 preset* 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`.
+
+## 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. If the
+window ever stays black on the very first start, close it and start it again;
+later launches start normally. 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.**