docs: README hook, discoverability, Pages site, game-behaviour reference

- README: lead with what it is + the AI-agent-collaboration research framing + current status in the first paragraph; rename H1 to "GoldenEye 007 PC Port"; add a live CI badge. - New "How this differs from the other GoldenEye PC projects" section: this is a source port of the N64 original; the Recomp projects binary-translate the Xbox 360 XBLA remaster (different game, no shared code). - CITATION.cff for GitHub's "Cite this repository" widget / Zenodo. - GitHub Pages site off /docs (_config.yml + index.md landing page). - agentic-development.md: searchable title + abstract. - .github/social-preview.{png,html,md}: repo social-preview card styled after the GE mission-briefing screen, kept editable (CSS source + a regen/how-to doc beside the PNG). - docs/dev/game-behavior-reference.md: distilled the raw GameFAQs walkthrough dump down to the behaviour-defining parts (combat/AI model, difficulty scaling, per-level objective sets, timers, weapon data, original-game quirks). Credits: Brett "Nemesis" Franklin, marshmallow. Claude-Session: https://claude.ai/code/session_01GULf6knbsqfsnW39tMr9WT
2026-09-02 00:27:05 -04:00
1 parent 0c2673f636
commit 4e2b721ac8
@@ -0,0 +1,147 @@
+<!doctype html>
+<!--
+  Source for .github/social-preview.png — the repo's GitHub "Social preview"
+  card (Settings → General → Social preview). 1280×640.
+
+  Regenerate the PNG with headless Chrome/Edge (any Chromium):
+
+    chrome --headless --disable-gpu --hide-scrollbars \
+           --force-device-scale-factor=1 --virtual-time-budget=6000 \
+           --window-size=1280,640 \
+           --screenshot=social-preview.png \
+           "$(pwd)/social-preview.html"
+
+  --virtual-time-budget waits for the Google Fonts (Tinos, Arimo) to load.
+  If your Chromium blocks file:// font loads, serve the folder first
+  (`python -m http.server` and point --screenshot at the localhost URL).
+
+  Design + rationale: .github/social-preview.md
+-->
+<html>
+<head>
+<meta charset="utf-8">
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Tinos:ital,wght@0,400;0,700;1,400&family=Arimo:wght@400;700&display=swap" rel="stylesheet">
+<style>
+  * { margin:0; padding:0; box-sizing:border-box; }
+  html,body { width:1280px; height:640px; overflow:hidden; }
+  body {
+    position:relative;
+    background:#4c4f3c;
+    font-family:'Arimo','Helvetica Neue',Arial,sans-serif;
+  }
+  /* rough concrete/stone surround, like the GE briefing screen.
+     Layered SVG fractal-noise: broad blotches (dark), mid mottle (light),
+     fine tooth. */
+  .concrete { position:absolute; inset:0; z-index:0;
+    background-color:#5c5f48;
+    background-image:
+      url("data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20width='520'%20height='520'%3E%3Cfilter%20id='a'%3E%3CfeTurbulence%20type='fractalNoise'%20baseFrequency='0.007'%20numOctaves='4'%20seed='19'%20stitchTiles='stitch'/%3E%3CfeColorMatrix%20type='matrix'%20values='0%200%200%200%200%200%200%200%200%200%200%200%200%200%200%200.55%200.5%200.4%200%20-0.5'/%3E%3C/filter%3E%3Crect%20width='100%25'%20height='100%25'%20filter='url(%23a)'/%3E%3C/svg%3E"),
+      url("data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20width='520'%20height='520'%3E%3Cfilter%20id='b'%3E%3CfeTurbulence%20type='fractalNoise'%20baseFrequency='0.02'%20numOctaves='4'%20seed='4'%20stitchTiles='stitch'/%3E%3CfeColorMatrix%20type='matrix'%20values='0%200%200%200%200.82%200%200%200%200%200.83%200%200%200%200%200.72%200.4%200.38%200.32%200%20-0.42'/%3E%3C/filter%3E%3Crect%20width='100%25'%20height='100%25'%20filter='url(%23b)'/%3E%3C/svg%3E"),
+      url("data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20width='200'%20height='200'%3E%3Cfilter%20id='c'%3E%3CfeTurbulence%20type='fractalNoise'%20baseFrequency='0.12'%20numOctaves='2'%20seed='8'%20stitchTiles='stitch'/%3E%3CfeColorMatrix%20type='matrix'%20values='0%200%200%200%200%200%200%200%200%200%200%200%200%200%200%200.4%200.4%200.4%200%20-0.55'/%3E%3C/filter%3E%3Crect%20width='100%25'%20height='100%25'%20filter='url(%23c)'/%3E%3C/svg%3E");
+    background-size:520px 520px,520px 520px,200px 200px;
+  }
+  .concrete::after { content:""; position:absolute; inset:0;
+    background:radial-gradient(ellipse at 50% 45%, transparent 45%, rgba(12,14,8,.30) 100%); }
+
+  /* file tabs on the right edge */
+  .tabs { position:absolute; right:26px; top:70px; bottom:70px; width:58px;
+    display:flex; flex-direction:column; align-items:stretch; z-index:4; }
+  .tab { flex:1; margin:5px 0; background:linear-gradient(90deg,#8f8f86,#c4c4bb);
+    border:2px solid #5b5b52; border-left:none;
+    box-shadow:2px 3px 6px rgba(0,0,0,.4);
+    display:flex; align-items:center; justify-content:center; }
+  .tab span { writing-mode:vertical-rl; text-orientation:mixed;
+    font-family:'Arimo',sans-serif; font-weight:700; font-size:15px;
+    letter-spacing:4px; color:#3b3b33; transform:rotate(180deg); }
+  .reticle { position:absolute; right:34px; top:246px; width:44px; height:44px; z-index:5; }
+  .reticle::before, .reticle::after { content:""; position:absolute; background:#c62828; }
+  .reticle::before { left:50%; top:-6px; width:3px; height:56px; margin-left:-1.5px; }
+  .reticle::after { top:50%; left:-6px; height:3px; width:56px; margin-top:-1.5px; }
+  .reticle i { position:absolute; inset:4px; border:3px solid #c62828; border-radius:50%; }
+
+  /* the parchment card */
+  .card { position:absolute; left:40px; top:40px; right:96px; bottom:40px;
+    background:#d9d4b0;
+    background-image:
+      repeating-radial-gradient(circle at 30% 20%, rgba(150,140,95,.10) 0 6px, rgba(120,112,72,.05) 6px 13px),
+      repeating-linear-gradient(4deg, rgba(140,130,90,.08) 0 3px, transparent 3px 9px);
+    box-shadow:0 6px 24px rgba(0,0,0,.5), inset 0 0 60px rgba(150,138,95,.35);
+    padding:44px 58px 40px; overflow:hidden; z-index:2; }
+
+  /* faint watermark, upper right */
+  .crest { position:absolute; right:44px; top:30px; width:190px; height:190px;
+    opacity:.10; }
+  .crest .ring { position:absolute; inset:0; border:9px solid #3a3320; border-radius:50%; }
+  .crest .ring2 { position:absolute; inset:34px; border:4px solid #3a3320; border-radius:50%; }
+  .crest .bar { position:absolute; left:50%; top:6%; width:6px; height:88%;
+    margin-left:-3px; background:#3a3320; transform:rotate(30deg); transform-origin:center; }
+  .crest .bar2 { transform:rotate(-30deg); }
+  .crest .bar3 { transform:rotate(90deg); }
+
+  .h1 { font-family:'Tinos','Times New Roman',serif; font-weight:700;
+    font-size:62px; line-height:1.02; color:#1c1a12; letter-spacing:1px; }
+  .h1 .r { color:#a01818; }
+  .h1 small { display:inline-block; font-size:44px; font-weight:700; letter-spacing:3px;
+    color:#a01818; margin-top:4px; border-bottom:5px solid #a01818; padding-bottom:1px; }
+
+  .meta { font-size:25px; line-height:1.45; color:#1c1a12; margin-top:14px; }
+  .rep { font-size:26px; font-weight:700; color:#1c1a12; margin-top:14px; letter-spacing:1px; }
+
+  .rows { margin-top:8px; font-size:25px; line-height:1.5; color:#1c1a12; }
+  .rows .status { color:#a01818; font-weight:700; }
+  .statusline { font-size:26px; margin-bottom:10px; }
+  .stats { display:grid; grid-template-columns:auto 1fr; column-gap:22px; row-gap:4px;
+    max-width:1000px; }
+  .stats .k { white-space:nowrap; font-weight:700; }
+
+  .foot { position:absolute; left:58px; bottom:26px; font-size:17px;
+    color:#4a4432; letter-spacing:.5px; }
+
+  /* diagonal CLASSIFIED stamp */
+  .classified { position:absolute; left:-30px; bottom:40px; right:0;
+    text-align:center; transform:rotate(-16deg); transform-origin:left bottom;
+    font-family:'Arimo',sans-serif; font-weight:700; font-size:104px;
+    letter-spacing:12px; color:rgba(172,40,40,.16); z-index:6; }
+</style>
+</head>
+<body>
+  <div class="concrete"></div>
+
+  <div class="card">
+    <div class="crest">
+      <div class="ring"></div><div class="ring2"></div>
+      <div class="bar"></div><div class="bar bar2"></div><div class="bar bar3"></div>
+    </div>
+
+    <div class="h1">GOLDENEYE <span class="r">007</span><br><small>PC&nbsp;PORT</small></div>
+
+    <div class="meta">
+      Mission: Native PC port of GoldenEye, compiled from the N64 decomp project
+    </div>
+
+    <div class="rep">REPORT:</div>
+
+    <div class="rows">
+      <div class="statusline">Status: <span class="status">PHASE 2 OF 4 &mdash; RENDERING</span></div>
+      <div class="stats">
+        <span class="k">Statistics:</span><span>21 / 21 solo missions load &amp; render</span>
+        <span></span><span>~230 game-code units, compiled unmodified</span>
+        <span></span><span>~17k lines C/C++ &nbsp;&middot;&nbsp; ~6k Python  (port layer + tools)</span>
+        <span></span><span>162 bugs root-caused &nbsp;&middot;&nbsp; built in ~2 weeks, part-time</span>
+      </div>
+    </div>
+
+    <div class="foot">github.com/jkdansereau/goldeneye-pc-port</div>
+
+    <div class="classified">CLASSIFIED</div>
+  </div>
+
+  <div class="tabs">
+    <div class="tab"><span>NEXT</span></div>
+    <div class="tab"><span>PREVIOUS</span></div>
+  </div>
+  <div class="reticle"><i></i></div>
+</body>
+</html>
@@ -0,0 +1,62 @@
+# Social preview card
+
+`social-preview.png` is the image GitHub shows when the repo is linked on
+Slack, Discord, Reddit, X, etc. (Repo **Settings → General → Social preview**.)
+It is generated from `social-preview.html` — the two live side by side so the
+card stays editable.
+
+- **Size:** 1280×640 (GitHub's recommended ratio).
+- **Fonts:** Tinos (a Times metric-compatible serif) for the title, Arimo
+  (Arial metric-compatible) for the body — both from Google Fonts.
+- **Everything else is pure CSS** — no raster assets, no external images.
+
+## Design brief
+
+Recreate GoldenEye 007's in-game **mission-briefing / objectives screen** and
+repurpose it as a project status card:
+
+- a mottled grey-green **concrete/stone** surround (three layered SVG
+  `feTurbulence` fractal-noise fills — broad staining, mid mottle, fine tooth —
+  plus a soft edge vignette);
+- a cream **parchment card** with a faint wavy watermark and a drop shadow;
+- the game's right-edge **filing tabs** (`NEXT` / `PREVIOUS`) and the small red
+  **crosshair/reticle**;
+- a faint circular **emblem** watermark, upper right;
+- a translucent diagonal **`CLASSIFIED`** stamp, kept low-opacity so the status
+  text stays readable;
+- serif title, `007` and `PC PORT` in the GoldenEye menu **red** (`#a01818`);
+- body laid out as the briefing's `Mission:` / `REPORT:` / `Status:` /
+  `Statistics:` fields.
+
+Keep the copy short. Update the stat lines from the README's "By the numbers"
+table when the numbers move; update `Status:` when the phase changes.
+
+## Regenerate the PNG
+
+Any Chromium (Chrome, Edge, Brave, `chromium`) can render it headless:
+
+```sh
+cd .github
+chrome --headless --disable-gpu --hide-scrollbars \
+       --force-device-scale-factor=1 --virtual-time-budget=6000 \
+       --window-size=1280,640 \
+       --screenshot="$(pwd)/social-preview.png" \
+       "$(pwd)/social-preview.html"
+```
+
+`--virtual-time-budget=6000` gives the web fonts time to load.
+`--force-device-scale-factor=1` keeps the output exactly 1280×640.
+
+If your browser blocks web-font loads over `file://`, serve the folder first:
+
+```sh
+cd .github && python -m http.server 8000 &
+chrome --headless --disable-gpu --hide-scrollbars \
+       --force-device-scale-factor=1 --virtual-time-budget=6000 \
+       --window-size=1280,640 \
+       --screenshot="$(pwd)/social-preview.png" \
+       "http://127.0.0.1:8000/social-preview.html"
+```
+
+Then re-upload `social-preview.png` under Settings → General → Social preview
+(GitHub does not pick it up from the repo automatically).
@@ -0,0 +1,35 @@
+cff-version: 1.2.0
+title: "GoldenEye 007 PC Port — a two-agent AI development case study"
+message: >-
+  If you reference this project or its write-up on AI-agent collaboration,
+  please cite it using the metadata below.
+type: software
+authors:
+  - family-names: Dansereau
+    given-names: James
+repository-code: "https://github.com/jkdansereau/goldeneye-pc-port"
+abstract: >-
+  A work-in-progress native PC port of GoldenEye 007 (Rare, 1997, Nintendo 64),
+  built on the GoldenEye 007 decompilation, and a research project on AI-agent
+  collaboration in a large, unfamiliar, low-level codebase: how two coding
+  agents (a local open-weight model and a hosted frontier model), directed by
+  one person part-time, were driven through ~230 translation units of unmodified
+  big-endian MIPS game code and made to run on a 64-bit desktop. Covers software
+  RSP emulation, N64-to-x86-64 ABI reconciliation, and a shared-artifact handoff
+  workflow between agents.
+keywords:
+  - goldeneye-007
+  - nintendo-64
+  - n64
+  - decompilation
+  - pc-port
+  - game-porting
+  - reverse-engineering
+  - agentic-development
+  - ai-agents
+  - llm
+  - coding-agents
+  - software-renderer
+  - mips
+  - opengl
+license: MIT
@@ -1,18 +1,26 @@
-# GoldenEye 007 — PC port
+# GoldenEye 007 PC Port

+[![CI](https://github.com/jkdansereau/goldeneye-pc-port/actions/workflows/ci.yml/badge.svg)](https://github.com/jkdansereau/goldeneye-pc-port/actions/workflows/ci.yml)
 ![status](https://img.shields.io/badge/status-Phase_2_of_4_(rendering)-orange)
 ![tested on](https://img.shields.io/badge/tested_on-Windows_x86--64-blue)
 ![license](https://img.shields.io/badge/license-MIT-green)
 ![built with](https://img.shields.io/badge/built_with-coding_agents-8A2BE2)

-A work-in-progress native port of **GoldenEye 007** (Rare, 1997) to modern
-desktop platforms, built on top of the
-[GoldenEye decompilation](https://github.com/n64decomp/007).
+**A work-in-progress native PC port of _GoldenEye 007_ (Rare, 1997, Nintendo 64),
+built on the [GoldenEye 007 decompilation](https://github.com/n64decomp/007).**
+It is first and foremost a **research project on AI-agent collaboration in a
+large, unfamiliar, low-level codebase** — how far two coding agents (a local
+open-weight model and Claude), driven by one person part-time, can be pushed
+through ~230 translation units of unmodified big-endian MIPS game code and made
+to run on a 64-bit desktop. **Current status: Phase 2 of 4 (rendering).** The
+port boots, renders the full intro and front end, and loads all 21 solo
+missions; there is no audio yet and it is not a playable game. See
+[Status](#status) and [Background](#background).

-It follows the architecture of the
+Technically, it follows the architecture of the
 [Perfect Dark PC port](https://github.com/fgsfdsfgs/perfect_dark) — the same
 Rare "Indy" engine family, one hardware generation apart. The unmodified game C
-sources are compiled for the host; the N64's Reality Signal Processor is
+sources are compiled for the host; the N64's Reality Signal Processor (RSP) is
 emulated in software; every other hardware surface (video, audio, input,
 timers, save storage) is shimmed in a dedicated `port/` layer.

@@ -33,6 +41,7 @@ timers, save storage) is shimmed in a dedicated `port/` layer.
 ## Contents

 - [Background](#background)
+- [How this differs from the other GoldenEye PC projects](#how-this-differs-from-the-other-goldeneye-pc-projects)
 - [Status](#status)
 - [Requirements](#requirements)
 - [Building](#building) · [Windows (MSYS2)](#windows-msys2) · [Linux](#linux)
@@ -46,10 +55,11 @@ timers, save storage) is shimmed in a dedicated `port/` layer.

 ## Background

-This port is primarily a **research project on agentic software development** —
-how far coding agents can be driven, by one person, through a large and
-unfamiliar low-level codebase (~230 translation units of unmodified
-big-endian MIPS game code, made to run on a 64-bit desktop).
+Beyond the port itself, this is primarily a **research project on agentic
+software development** — specifically, on AI-agent collaboration in a large,
+unfamiliar, low-level codebase: how far coding agents can be driven, by one
+person working part-time, through ~230 translation units of unmodified
+big-endian MIPS game code, made to run on a 64-bit desktop.

 It used two agents:

@@ -106,7 +116,31 @@ asset converters — then both agents ran the debugging phase together:

 Full write-up, timeline chart, and 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).
+workflow itself: [`docs/dev-process.md`](docs/dev-process.md). To cite this
+project or its findings, use [`CITATION.cff`](CITATION.cff) (GitHub's "Cite
+this repository" menu).
+
+## How this differs from the other GoldenEye PC projects
+
+This is a **native port of the original 1997 Nintendo 64 game, built from its
+actual reconstructed source code** — the same lineage as the Perfect Dark PC
+port. The other well-known "GoldenEye on PC" projects are something different:
+they machine-translate the shipped binary of the *unreleased Xbox 360 XBLA
+remaster* — a different game, a different codebase, no shared code with this.
+
+| | This project | [GoldenEye-Recomp](https://github.com/SunJaycy/GoldenEye-Recomp) / [Steam Deck build](https://github.com/couchk1ng/GoldenEye-Recomp-SteamDeck) |
+|---|---|---|
+| **What it ports** | The original **Nintendo 64** game (1997) | The **Xbox 360 XBLA** HD remaster (built ~2007, never released) |
+| **How** | **Decompilation-based source port** — human-reconstructed C, compiled for the host; game logic runs as written | **Static binary recompilation** — the shipped machine code is auto-translated to C; no source-level understanding |
+| **Lineage** | [GoldenEye 007 decompilation](https://github.com/n64decomp/007) + [Perfect Dark PC port](https://github.com/fgsfdsfgs/perfect_dark) engine family | Xbox 360 "…Recompiled" static-recompilation family |
+| **Renderer** | Software RSP → OpenGL | Hardware (Vulkan) |
+| **Status** | WIP, Phase 2 — renders and loads all 21 levels; no audio; not playable end to end | Playable full game, higher frame rates, online multiplayer |
+| **Why it exists** | A [case study in AI-agent collaboration](#background) on a hard low-level codebase; the port is the target, not a product | A polished, playable PC release of the remaster |
+
+**If you just want to play GoldenEye on PC today, use one of the recompilation
+projects — they are finished and this is not.** What is interesting here is the
+other half: getting the *original* game running from source, and how much of
+that work was driven by AI agents.

 ## Status

@@ -275,11 +309,15 @@ docs/               see below

 ## Documentation

+Key docs are also published as a site:
+**<https://jkdansereau.github.io/goldeneye-pc-port/>**.
+
 | Doc | What's in it |
 |---|---|
 | [`docs/building.md`](docs/building.md) | Full build + asset-extraction guide. |
 | [`docs/internals.md`](docs/internals.md) | Architecture, the RSP-emulation approach, GE-vs-PD engine differences, the phased plan. |
 | [`docs/porting-notes.md`](docs/porting-notes.md) | The recurring N64→PC bug classes hit during the port, with fixes. |
+| [`docs/dev/game-behavior-reference.md`](docs/dev/game-behavior-reference.md) | How the retail N64 game is meant to behave — combat/AI model, difficulty scaling, per-level objectives, timers, weapon data, original-game quirks. Playtest reference. |
 | [`docs/dev/agentic-development.md`](docs/dev/agentic-development.md) | The research angle: the two-agent setup, timeline, handoff workflow, and an assessment of what did and didn't work. |
 | [`docs/dev-process.md`](docs/dev-process.md) | The investigation workflow in detail — budgets, file partitioning, the finding-log discipline. |
 | [`docs/dev/`](docs/dev/) | The raw engineering record: the full finding log, per-level status, graphics backlog, playtest matrices. |
@@ -0,0 +1,16 @@
+# GitHub Pages config. Site is served from the /docs folder on the default
+# branch (Settings -> Pages -> Deploy from a branch -> main / docs).
+title: GoldenEye 007 PC Port
+description: >-
+  A native PC port of the original Nintendo 64 GoldenEye 007, built from its
+  decompiled source, and a case study in AI-agent collaboration on a large
+  low-level codebase.
+theme: jekyll-theme-cayman
+show_downloads: false
+
+# jekyll-relative-links (on by default for Pages) rewrites the .md links in
+# these docs to .html so cross-links work on the published site.
+
+# Rolling local working files - not useful as published pages.
+exclude:
+  - HANDOFF.md
@@ -1,10 +1,12 @@
-# Agentic development: a two-agent experiment
+# Agentic development: two AI coding agents porting GoldenEye 007

-*A GoldenEye 007 N64→desktop port, taken from "builds a ROM" to "playable front
-end" in about two weeks — driven mostly by two coding agents, a local
-open-weight model and a hosted frontier model, handing work back and forth
-through shared written notes under one person's direction. This is the goal,
-the method, the timeline, and an honest read on what did and didn't work.*
+*A case study in AI-agent collaboration on a large, low-level codebase. A
+GoldenEye 007 Nintendo 64 → desktop port, taken from "builds a ROM" to
+"playable front end" in about two weeks — driven mostly by two coding agents (a
+local open-weight model, Qwen 3, on a single RTX 5090, and a hosted frontier
+model, Claude / Claude Code), handing work back and forth through shared
+written notes under one person's part-time direction. This is the goal, the
+method, the timeline, and an honest read on what did and didn't work.*

 ## Contents

@@ -0,0 +1,358 @@
+# GoldenEye 007 — game-behaviour reference
+
+Community-documented account of how the retail N64 game is *supposed* to
+behave: the combat/AI/stealth model, difficulty scaling, per-level objective
+sets, timers, weapon data, and the original game's known quirks and glitches.
+
+**Status of this document.** This is secondary source material, not ground
+truth. The decompiled game code in `src/` is authoritative for behaviour (see
+`AGENTS.md`). Use this doc to know *what correct looks like* when playtesting
+the port — which objectives a level must expose, what a timer value should be,
+whether a weird behaviour you just saw is an original-game quirk or a port
+regression.
+
+**Sources** (subjective commentary stripped; mechanical/factual data only):
+
+- GameFAQs walkthrough by **Brett "Nemesis" Franklin**, v1.01, July 2001 —
+  overview, mechanics, objective lists, weapon/gadget data, glitches.
+- **marshmallow**, *Extensive 00 Agent Walkthrough* v3.0 (GameFAQs) — the
+  00 Agent difficulty-delta list and the AI-exploit notes in §3.
+
+Distilled from `goldeneye_007_reference.md` (the full raw walkthrough dump);
+the walkthrough's per-stage tactical routes were dropped as not
+behaviour-defining.
+
+---
+
+## 1. Difficulty modes
+
+Three tiers. **00 Agent is a strict superset** of Agent and Secret Agent —
+every objective required at a lower tier is also required at 00 Agent, so one
+00 Agent run satisfies all three.
+
+| Mode | Rank | Layout | Objectives |
+|---|---|---|---|
+| Agent | starting rank | small/simple | fewest |
+| Secret Agent | +1 | average | more |
+| 00 Agent | highest | big/complex | maximum (superset) |
+
+### What 00 Agent changes mechanically
+
+Relative to the lower tiers:
+
+1. Guards are tougher — body-armoured guards can **survive a headshot** (a DD44
+   headshot may not kill).
+2. Better AI — enemies fire sooner, roll/dodge more often, and "hear" the
+   player from further.
+3. Picked-up guns start with only **10 rounds**.
+4. Body armour is nearly absent (a few fixed locations only).
+5. More objectives per level.
+6. Low player health — roughly **8× KF7 Soviet hits** or **~5× AR33 hits** is
+   lethal.
+7. Higher enemy accuracy.
+8. Explosions (crates, grenades, chairs) are near-instant-kill unless the
+   player clears the radius fast.
+9. Security cameras acquire the player in **~3 s** (vs ~10 s on Agent).
+
+---
+
+## 2. Combat, stealth & AI model
+
+### Damage
+
+- **Body-part damage system** — different hit locations do different damage;
+  head shots are the fastest kill and are the intended way to conserve ammo.
+- **Auto-Aim** (option) — snaps to the nearest enemy under the crosshair when
+  firing; ~90% reliable at target selection.
+- **Manual aim** (R / L-R) — zooms for precise body-part targeting.
+- **Full-auto accuracy falls off** with sustained fire and with distance:
+  "pecking" 1–2 rounds is more accurate than spraying; spray only wins against
+  groups.
+
+### Alerting
+
+- A **loud** weapon fired within earshot of **2+ guards** triggers an area
+  alert (they converge on the player's position and can call reinforcements).
+  A lone guard may not call for help.
+- **Silenced** weapons (PP7 Silenced, D5K Silenced, silenced pistols, knives)
+  never alert.
+- **Security cameras**: if a camera acquires the player it raises an alert
+  that **spawns black-clad guards** armed with DD44s and KF7s. Shoot the
+  camera centre for a one-shot kill.
+- **Retreating** breaks pursuit — most guards stop following after a set
+  distance, letting the player reload / heal / reposition.
+
+### AI line-of-sight & animation quirks (exploitable, i.e. defining behaviour)
+
+- A guard behind a **wall, low barrier or railing cannot shoot** the player,
+  even point-blank — it must path around the obstacle. **Exception:** a guard
+  behind a **crate** *can* shoot through/over it.
+- Turrets / sentry guns **drop target beyond a set range**.
+- Most guards play a **kneel animation before firing** (takes ~1–2 s). Circling
+  a kneeling guard makes it fire at the player's previous position.
+- **Point-blank**: a guard the player is pressed against **cannot fire** until
+  it steps back.
+
+---
+
+## 3. Player state
+
+| System | Behaviour |
+|---|---|
+| Health | restored by health packs; no regen. 00 Agent pool ≈ 8 KF7 hits (§1). |
+| Body armour | separate absorbing layer; fixed pickup locations (e.g. by the Jungle drone guns, start of Antenna Cradle). Nearly absent on 00 Agent. |
+| Explosive barrels/crates | shootable for area damage; can kill the player. In Water Caverns, detonating the barrels **before** using the radio destroys the radio and fails that objective. |
+
+---
+
+## 4. Timers (exact values — verify against decomp)
+
+| Level | Trigger | Value | On expiry |
+|---|---|---|---|
+| Silo (M3) | level start | **8:30** | facility self-destructs; must reach the escape elevator |
+| Bunker 2 (M5) | Natalya activates the main control panel | **~60 s** | alarm; must escort Natalya to the exit |
+| Train (M6) | hostage scene, if Xenia is **not** killed | **4 s** | escape window before failure |
+
+---
+
+## 5. Companion AI — Natalya
+
+- Present in Bunker 2, Jungle, Control Center, Water Caverns, Train
+  (Missions 5–7).
+- Carries a **Cougar Magnum**; engages enemies autonomously.
+- Must survive — her death fails objectives.
+- Scripted roles: hacks the mainframe in Control Center (player defends both
+  staircases); freed from a cell and escorted out under the timer in Bunker 2;
+  hacks a terminal in Train while the player laser-cuts the grate bearings.
+
+---
+
+## 6. Objective system
+
+Each sub-level exposes a fixed set of **primary objectives** shown at level
+start; completing the final one ends the sub-level. Objective *count* scales
+with difficulty (§1). Some are **conditional / fail-state** objectives —
+"Minimize scientist casualties", "Minimize civilian casualties" — tracked by a
+running kill count against that class.
+
+21 sub-levels across 9 missions:
+
+| M | Location | Sub-levels |
+|---|---|---|
+| 1 | Aarkangelsk | Dam → Facility → Runaway |
+| 2 | Severnaya | Surface → Bunker |
+| 3 | Kirghizstan | Silo |
+| 4 | Monte Carlo | Frigate |
+| 5 | Severnaya (return) | Surface 2 → Bunker 2 |
+| 6 | St. Petersburg | Statue Park → Military Archives → Streets → Depot → Train |
+| 7 | Cuba | Jungle → Control Center → Water Caverns → Antenna Cradle |
+| 8 | Teotihuacán | Aztec Complex |
+| 9 | el-Saghira | Egyptian Temple |
+
+### Per-level objective sets (00 Agent — the superset)
+
+**Dam** — neutralize all alarms · install covert modem · intercept data backup ·
+bungee jump from platform.
+**Facility** — gain entry to lab · contact double agent (Dr. Doak) · rendezvous
+with 006 · destroy all tanks in bottling room · minimize scientist casualties.
+**Runaway** — find plane ignition key · destroy heavy gun emplacements ·
+destroy missile battery · escape in plane.
+**Surface** — power down comms dish · obtain safe key · steal building plans ·
+enter base via ventilation tower.
+**Bunker** — disrupt all surveillance equipment · copy Goldeneye Key and leave
+original · get personnel to activate computer · download data · photograph main
+video screen.
+**Silo** — plant bombs in fuel rooms · photograph satellite · obtain telemetric
+data · retrieve satellite circuitry · minimize scientist casualties.
+**Frigate** — rescue hostages · disarm bridge bomb · disarm engine-room bomb ·
+plant tracking bug on helicopter.
+**Surface 2** — disrupt all surveillance equipment · break comms link to bunker ·
+disable Spetznaz support aircraft · gain entry to bunker.
+**Bunker 2** — compare staff/casualties lists · recover CCTV tape · disable all
+security cameras · recover Goldeneye operations manual · escape with Natalya.
+**Statue Park** — contact Valentin · confront and unmask Janus · locate
+helicopter · rescue Natalya · find flight recorder.
+**Military Archives** — escape interrogation room · find Natalya · recover
+helicopter black box · escape with Natalya.
+**Streets** — contact Valentin · pursue Ourumov and Natalya · minimize civilian
+casualties.
+**Depot** — destroy illegal arms cache · destroy computer network · obtain safe
+key · recover helicopter blueprints · locate Trevelyan's train.
+**Train** — destroy brake units · rescue Natalya · locate Janus secret base ·
+crack Boris' password · escape to safety.
+**Jungle** — destroy drone guns · eliminate Xenia · blow up ammo dump · escort
+Natalya to Janus base.
+**Control Center** — protect Natalya · disable Goldeneye satellite · destroy
+armored mainframes.
+**Water Caverns** — destroy inlet pump controls · destroy outlet pump controls ·
+destroy master control console · use radio to contact Jack Wade · minimize
+scientist casualties.
+**Antenna Cradle** — destroy control console · settle score with Trevelyan.
+**Aztec Complex** — reprogram shuttle guidance · launch shuttle.
+**Egyptian Temple** — recover the Golden Gun · defeat Baron Samedi.
+
+### Key scripted mechanics per level
+
+- **Bunker / Surface 2** — cameras must be killed to avoid the black-clad
+  alert spawn.
+- **Silo** — Ourumov is killable here (he normally flees; Invisibility stops
+  him); drops DD44 + briefcase. He still reappears later regardless.
+- **Frigate** — hostages held at gunpoint; shoot the guard not the hostage.
+  Bomb Diffuser used on two terminal-mounted bombs.
+- **Streets** — tank vehicle; running over a **civilian** fails the mission;
+  street land-mines apply damage-over-time to the tank.
+- **Train** — kill Xenia + Ourumov simultaneously in the hostage scene; if
+  Xenia survives, the 4 s timer starts and extra guards spawn.
+- **Jungle** — Xenia boss on the bridge: uses RCP-90 + Grenade Launcher, rolls
+  when hit, drops both weapons.
+- **Control Center** — Boris pulls a gun ("I am Invincible!") and fades out
+  rather than being killed.
+- **Water Caverns** — contact Jack Wade by radio **before** detonating the
+  barrel room; Code Cards A/B/C drop from guards in sequence.
+- **Antenna Cradle** — Trevelyan final boss reappears alternately at the two
+  sheds/catwalks; player kills him at each appearance, final fight point-blank
+  in the shed under the cradle.
+- **Aztec Complex** — first terminal starts the launch sequence + opens a
+  door; a second terminal must be destroyed to reveal a hidden hallway before
+  the launch finishes.
+- **Egyptian Temple** — Golden Gun glass case lowers only after a fixed
+  tile-path is walked; Baron Samedi appears twice, uses Lasers, dies only to
+  the Golden Gun.
+
+---
+
+## 7. Weapons — data table
+
+Clip / max-capacity / behaviour. (Balance and capacity numbers to cross-check
+against the decomp's weapon tables.)
+
+| Weapon | Type | Clip | Max | Behaviour notes |
+|---|---|---|---|---|
+| PP7 | pistol | 7 | 800 | default sidearm |
+| PP7 (Silenced) | pistol | 7 | 800 | no alert on fire |
+| DD44 Dostovei | pistol | 8 | 812 | high power, Magnum-like recoil |
+| Cougar Magnum | pistol | 6 | 200 | high per-shot damage; Natalya's sidearm |
+| Gold PP7 / Golden Gun | pistol | 7 / 1 | 800 / 100 | one-shot kill anywhere; Golden Gun = 1 round/clip |
+| Silver PP7 | pistol | 7 | 800 | cosmetic |
+| Klobb | SMG | 20 | 812 | weakest automatic |
+| KF7 Soviet | auto rifle | 30 | 400 | ubiquitous early-game weapon |
+| AR-33 | auto rifle | 30 | 400 | stronger than KF7; zoom |
+| D5K Deutsche | auto rifle | 32 | 800 | zoom |
+| D5K (Silenced) | auto rifle | 32 | 800 | no alert; one level |
+| Phantom | auto rifle | 50 | 800 | very loud; one level |
+| RCP-90 | auto rifle | 80 | 800 | fastest fire rate in the game |
+| ZMG (9mm) | heavy auto | 32 | 800 | dual-wieldable |
+| Automatic Shotgun | auto shotgun | 5 | 200 | Statue Park only (SP) |
+| Shotgun | pump shotgun | 5 | 200 | slower reload; via All Guns cheat |
+| Sniper Rifle | bolt rifle | 8 | 400 | longest zoom; best stealth weapon |
+| Grenade Launcher | launcher | 6 | 12 | arcing grenades |
+| Rocket Launcher | launcher | 1 | 3 | large blast, can kill player |
+| Grenades | thrown | 12 | 12 | — |
+| Throwing Knives | ranged melee | 12 | 12 | low damage |
+| Hunting Knives | melee | — | — | fast silent takedowns |
+| Proximity Mines | placed | 10 | 10 | triggers on proximity |
+| Remote Mines | placed | 10 | 10 | detonated by Remote Watch; no timeout |
+| Timed Mines | placed | 10 | 10 | detonate ~8 s after placement |
+| Taser | gadget | — | — | non-lethal stun |
+| Moonraker (Military) Laser | energy | — | — | fires through walls/doors; kills Jaws |
+| Tank Shells | vehicle | — | — | Runaway, Streets |
+
+Availability: weapons are level-scoped and do not carry between missions unless
+noted. **All Guns** cheat unlocks everything.
+
+---
+
+## 8. Gadgets
+
+| Gadget | Level(s) | Activation / effect |
+|---|---|---|
+| Covert Modem | Dam | toss onto a computer screen to install |
+| Bomb Diffuser | Frigate | use on a terminal-mounted bomb |
+| Camera | Bunker, Silo | photograph a target (video screen / satellite) |
+| Key Analyzer | Bunker | copies a key and **destroys the original** |
+| Data Thief | Bunker | download data from a terminal |
+| Tracking Bug | Frigate | place on the Pirate helicopter |
+| Watch Magnet | Bunker 2, Train | pull a key / metal object at range |
+| Watch Laser | Train | cut metal (grate bearings) |
+| Remote Mines + Remote Watch | Facility, Control Center, Water Caverns | place, then detonate at range |
+| Door Decoder | Facility | from Dr. Doak; opens the locked bottling-room door |
+
+---
+
+## 9. World-interaction objects
+
+| Object | Rule |
+|---|---|
+| Red alarm boxes | shoot to complete "neutralize all alarms"; a guard reaching one spawns reinforcements |
+| Security cameras | destroy (centre = one-shot); acquisition raises the black-clad alert |
+| Sentry guns | fixed turrets (Bunker 2 striped corridor, Depot); destroy to pass |
+| Drone guns | remote turrets (Jungle, Control Center, Water Caverns, Aztec); some pairs must be destroyed together |
+| Locks / grates | shootable (e.g. the 4-lock vent grate at the end of Surface) |
+| Doors | B to open; some need keycard / key / code |
+| Gate switches | red/green buttons control gates (Dam) |
+
+---
+
+## 10. Vehicles
+
+| Vehicle | Level | Rules |
+|---|---|---|
+| Tank | Runaway, Streets | cannons + missiles (Runaway); may crush enemies, **must not crush civilians** (Streets); street mines = DoT |
+| Plane | Runaway | final escape after the missile battery is destroyed |
+| Train | Train | car-to-car traversal; a brake unit (red/yellow wires) in every car must be destroyed |
+
+---
+
+## 11. Controls / input options (relevant to `port/src/input.c`)
+
+Default mapping (control style 1.1): **A** switch weapon/device · **B**
+action / reload · **Z** fire / use gadget · **L/R** aim · **C-Up/Down** look ·
+**C-Left/Right** strafe · **Stick** move · **D-Pad** mirrors C.
+
+Four SP control styles (1.1–1.4) permute which of {aim, fire} is on Z vs A/L-R
+and whether the stick moves or looks. Derived actions: **crouch** = Aim +
+C-Down, **stand** = Aim + C-Up.
+
+Options that change feel: **Reverse Pitch** (invert vertical aim),
+**Look Ahead** (camera leads movement), **Head Roll** (full 360° look),
+**Auto-Aim** (snap to nearest on fire), **Aim Control** = Hold or Toggle.
+
+---
+
+## 12. Original-game quirks & glitches
+
+These are **retail N64 behaviours**. If the port reproduces them it is
+faithful; if you see one while testing, it is probably *not* a port bug.
+
+- **Guard AI freeze under Invisibility** — kill one guard in a group and the
+  rest aim at the player's last known position but can never re-acquire (player
+  is invisible); they hold the aim pose until the player moves or dies.
+- **Ourumov / Jaws killable via Invisibility** — both normally can't be
+  engaged (Ourumov flees, Jaws is near-indestructible); with Invisibility the
+  AI can't see the player, so both become killable with any weapon.
+- **Trevelyan respawn loop (Antenna Cradle, 00 Agent + Invisibility)** —
+  killing Trevelyan on the catwalk can respawn him alive at the far shed,
+  repeatable indefinitely. A pathing/AI bug, not intended.
+- **Invulnerable 006 in Water Caverns** — with Invisibility, one of the
+  "guards" leaving the elevator is actually a static, invulnerable Trevelyan
+  model (his AI never detects the invisible player). An easter egg, not a
+  spawn error.
+- **Post-dialogue allies become killable** — after an ally's scripted
+  conversation ends (e.g. Valentin in Statue Park) the player can kill them;
+  no mechanical penalty.
+- **Ourumov's key opens the Silo launch doors** — the briefcase/key dropped by
+  Ourumov has no objective use, but "firing" the key (action button) near the
+  rocket opens the giant launch doors. Otherwise both items are inert.
+- **Cut content left in levels**: the Dam has the unused geometry of a
+  cancelled boat mission out on the water; the Train's rear region past
+  Alec/Trevelyan leads nowhere; the Facility's starting vent has a second path
+  blocked purely cosmetically and shootable ceiling glass.
+
+---
+
+## 13. Multiplayer (brief)
+
+Up to 4 local players. Deathmatch + variant modes. Level list = all SP levels
+plus dedicated MP maps. Character/costume/face are swappable (the raw dump has
+the full GameShark costume/character ID tables if ever needed for the MP
+character system).
@@ -0,0 +1,32 @@
+---
+title: GoldenEye 007 PC Port
+description: A native PC port of the original Nintendo 64 GoldenEye 007, built from decompiled source — and a case study in AI-agent collaboration on a large low-level codebase.
+---
+
+# GoldenEye 007 PC Port
+
+A work-in-progress **native PC port of the original 1997 Nintendo 64
+_GoldenEye 007_**, compiled from the game's
+[decompiled source](https://github.com/n64decomp/007) and running the N64's
+graphics coprocessor in software. It follows the architecture of the
+[Perfect Dark PC port](https://github.com/fgsfdsfgs/perfect_dark).
+
+It is also a **research project on AI-agent collaboration in a large,
+unfamiliar, low-level codebase**: two coding agents — a local open-weight model
+(Qwen 3) on a single RTX 5090, and Claude / Claude Code — driven by one person
+part-time through ~230 translation units of unmodified big-endian MIPS game
+code, handing work back and forth through shared written notes.
+
+**Status:** Phase 2 of 4 (rendering). Boots, renders the full intro and front
+end, loads all 21 solo missions. No audio yet; not playable end to end.
+
+- **[Project repository and README](https://github.com/jkdansereau/goldeneye-pc-port)** — build instructions, requirements, status, how it compares to the Xbox 360 recompilation projects.
+
+## Documentation
+
+- **[The two-agent development case study](dev/agentic-development.md)** — goal, setup, timeline, the handoff workflow, and an honest assessment of what did and didn't work.
+- **[Development process](dev-process.md)** — how work was scoped, partitioned, and budgeted across agents; the finding-log discipline.
+- **[Internals](internals.md)** — architecture, the software RSP-emulation approach, GoldenEye-vs-Perfect-Dark engine differences, the phased plan.
+- **[Porting notes](porting-notes.md)** — the recurring Nintendo 64 → PC bug classes hit during the port, with fixes.
+- **[Game-behaviour reference](dev/game-behavior-reference.md)** — how the retail N64 game is meant to behave: combat/AI model, difficulty scaling, per-level objectives, timers, weapon data, and the original game's known quirks.
+- **[Building](building.md)** — full build and asset-extraction guide.