release: add Linux x86-64 bundle + dual-platform release notes

- tools_pc/bundle-linux.sh: package a Linux build (exe + README + licenses +
  prepare-assets) as a .tar.gz. Mirrors bundle-win.sh's ROM / size guards and
  prepare-assets assembly. No shared libs bundled — the generated README tells
  the user to install SDL2 / zlib / libGL from their distro.
- tools_pc/dist/README.md.in: made OS-neutral via @PLATFORM@ / @EXE@ / @DEPS@ /
  @LICENSE_EXTRA@ tokens; refreshed the known-issues list (dropped the stale
  "ladders don't work" line — D177 fixed M-36; added black sky + missing HUD
  weapon icon).
- .github/workflows/ci.yml: linux-build now packages + uploads the Linux
  bundle; the release job attaches both platforms to the draft pre-release.
- .github/release-notes.md: rewritten for the two-platform NTSC-U alpha with
  the prepare-assets step and current known issues.

Alpha scope: NTSC-U only, one-time prepare-assets step (Part A launcher and
Part B native converter from release-dropin-rom-plan.md remain follow-ups).

Claude-Session: https://claude.ai/code/session_01V4pK3pT83YnPsBp3Ey4RP2

.github/release-notes.md

@@ -3,31 +3,53 @@
 > ⚠️ **Very early research alpha. Not a playable game.**
 > The intro and menus render and all 21 solo missions load, but:
 > - **no audio** (Phase 3, not started);
-> - some front-end 3D models and some text are broken;
-> - **ladders don't work** and can block progression on some levels;
+> - some front-end 3D models and some text are broken (the spinning Nintendo
+>   logo, MISSION COMPLETE / mode-select models, some briefing objective text);
+> - outdoor levels render with a **black sky**;
+> - the in-HUD **weapon icon is missing** (the ammo count still shows);
 > - expect crashes and glitches once past the level intro.
 >
 > This is a technical demo of the porting work. If you want to *play* GoldenEye
 > on PC, use one of the Xbox 360 recompilation projects instead — see the
 > [project README](https://github.com/jkdansereau/goldeneye-pc-port#how-this-differs-from-the-other-goldeneye-pc-projects).
 
-### Download
+### Downloads
 
-`goldeneye-pc-port-<version>-win64.zip` — the engine executable, its runtime
-DLLs, a README, and license texts. **Windows x86-64 only.** No ROM, no game
-assets.
+| File | Platform |
+|---|---|
+| `goldeneye-pc-port-<version>-win64.zip` | Windows x86-64 |
+| `goldeneye-pc-port-<version>-linux-x86_64.tar.gz` | Linux x86-64 |
+
+Each contains the engine executable, a README, license texts, and the
+`prepare-assets` tool. **No ROM, no game assets.** The Windows bundle also
+carries its runtime DLLs; the Linux bundle links against your distro's SDL2 /
+zlib / libGL (`sudo apt install libsdl2-2.0-0 zlib1g libgl1`, or the equivalent).
+
+Windows development and playtesting is the primary path; the Linux build boots
+and renders (tested on WSLg) but has had far less exercise.
 
 ### Running it
 
 You supply your own **NTSC-U GoldenEye 007 N64 ROM** (`.z64`, big-endian,
-`SHA-1 abe01e4aeb033b6c0836819f549c791b26cfde83`). Unzip, put the ROM in a
-`data/` folder next to the exe as `ge007.ntsc-final.z64`, run the exe from that
-folder. Full steps in the bundled `README.md`.
+`SHA-1 abe01e4aeb033b6c0836819f549c791b26cfde83`). Only the US ROM is supported
+in this alpha.
+
+1. Unpack the archive.
+2. Make a `data/` folder next to the executable and put the ROM in it as
+   `ge007.ntsc-final.z64`.
+3. Run the one-time asset step (needs Python 3.8+):
+   `python3 prepare-assets/prepare-assets.py`
+   — it reads your ROM and writes the two `data/pc*-ntsc-final/` folders the
+   engine needs. Standard library only; a few seconds.
+4. Run the executable **from that folder**.
+
+Full steps are in the bundled `README.md`.
 
 ### Verify the download
 
 ```
 sha256sum -c goldeneye-pc-port-<version>-win64.zip.sha256
+sha256sum -c goldeneye-pc-port-<version>-linux-x86_64.tar.gz.sha256
 ```
 
 ### Source & docs

.github/workflows/ci.yml

@@ -26,8 +26,11 @@ concurrency:
 # Jobs:
 #
 #   linux-build   — ubuntu, system GCC. Actually compiles + links (unlike
-#                   validate). Surfaces GCC-on-Linux strictness gaps MinGW
-#                   misses. Not a runtime claim; not a required check yet.
+#                   validate), then packages the Linux bundle (exe + README +
+#                   licenses + prepare-assets, NO ROM / assets / bundled libs)
+#                   via tools_pc/bundle-linux.sh and uploads it. Surfaces
+#                   GCC-on-Linux strictness gaps MinGW misses. Not a runtime
+#                   claim; not a required check yet.
 #
 #   validate      — ubuntu, configure-only. Byte-compiles the tooling,
 #                   regenerates the US ROM-asset symbol file, and CMake-
@@ -43,10 +46,10 @@ concurrency:
 #                   the ROM nor extracted assets are needed to BUILD (they are
 #                   runtime-only), so CI builds but never runs the port.
 #
-#   release       — tags only (v*). Downloads the bundle from windows-build and
-#                   attaches it to a DRAFT pre-release for that tag. Draft, so a
-#                   human does the ROM smoke-test and hits Publish. This is the
-#                   only job granted contents: write.
+#   release       — tags only (v*). Downloads the Windows + Linux bundles and
+#                   attaches both to a DRAFT pre-release for that tag. Draft, so
+#                   a human does the ROM smoke-test on each platform and hits
+#                   Publish. This is the only job granted contents: write.
 
 jobs:
   # Did this push touch anything outside docs / licenses? Branch pushes to main
@@ -153,6 +156,29 @@ jobs:
           ls -la build-linux/ge007* || true
           file build-linux/ge007* || true
 
+      # Package the Linux bundle on every run so the release path stays
+      # exercised. No shared libs are bundled — the README tells the user to
+      # install SDL2 / zlib / libGL from their distro. Same ROM / size guards
+      # as the Windows bundle.
+      - name: Package Linux bundle
+        run: |
+          if [ "${GITHUB_REF_TYPE}" = "tag" ]; then
+            V="${GITHUB_REF_NAME}"
+          else
+            V="0.0.0-ci.${GITHUB_SHA::7}"
+          fi
+          tools_pc/bundle-linux.sh "$V"
+
+      - name: Upload bundle
+        uses: actions/upload-artifact@v7
+        with:
+          name: goldeneye-pc-port-linux-x86_64
+          path: |
+            dist/*.tar.gz
+            dist/*.tar.gz.sha256
+          if-no-files-found: error
+          retention-days: 14
+
   # Real Windows (MSYS2 MINGW64) build — the only platform the port is
   # developed and tested on. This compiles and LINKS the full executable.
   #
@@ -219,12 +245,12 @@ jobs:
       # -level_09 soak, a golden-frame diff) would run on a self-hosted runner
       # instead. Not planned.
 
-  # Tags only. Attach the packaged bundle to a DRAFT pre-release so a human can
-  # do the ROM smoke-test before publishing. This job — and only this job —
-  # gets contents: write.
+  # Tags only. Attach the packaged Windows + Linux bundles to a DRAFT
+  # pre-release so a human can do the ROM smoke-test on each platform before
+  # publishing. This job — and only this job — gets contents: write.
   release:
     if: github.ref_type == 'tag'
-    needs: [ changes, validate, windows-build ]
+    needs: [ changes, validate, windows-build, linux-build ]
     runs-on: ubuntu-22.04
     permissions:
       contents: write
@@ -238,15 +264,21 @@ jobs:
           name: goldeneye-pc-port-win64
           path: dist
 
+      - uses: actions/download-artifact@v7
+        with:
+          name: goldeneye-pc-port-linux-x86_64
+          path: dist
+
       - name: Create or update draft pre-release
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
           TAG="${GITHUB_REF_NAME}"
+          ASSETS=(dist/*.zip dist/*.zip.sha256 dist/*.tar.gz dist/*.tar.gz.sha256)
           if gh release view "$TAG" >/dev/null 2>&1; then
-            gh release upload "$TAG" dist/*.zip dist/*.zip.sha256 --clobber
+            gh release upload "$TAG" "${ASSETS[@]}" --clobber
           else
-            gh release create "$TAG" dist/*.zip dist/*.zip.sha256 \
+            gh release create "$TAG" "${ASSETS[@]}" \
               --draft --prerelease \
               --title "GoldenEye 007 PC Port $TAG" \
               --notes-file .github/release-notes.md

tools_pc/bundle-linux.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+#
+# Package a Linux GoldenEye 007 PC port build for distribution.
+#
+# Run from anywhere, AFTER building (./build-pc.sh or a cmake --build):
+#
+#     tools_pc/bundle-linux.sh [VERSION]
+#
+# Produces, under dist/ :
+#     goldeneye-pc-port-<VERSION>-linux-x86_64/        the unpacked bundle
+#     goldeneye-pc-port-<VERSION>-linux-x86_64.tar.gz  + .tar.gz.sha256
+#
+# The bundle contains ONLY: the engine executable, a README, license texts, and
+# the prepare-assets/ tool. It contains NO ROM and NO game assets, and — unlike
+# the Windows bundle — NO bundled shared libraries: the user installs SDL2 / zlib
+# / libGL from their distro (see the README this generates). The script hard-
+# fails if a ROM image or an oversized blob ends up inside the bundle.
+#
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT"
+
+VERSION="${1:-$(git describe --tags --always --dirty 2>/dev/null || echo 0.0.0-dev)}"
+VERSION="${VERSION#v}"                                  # strip a leading "v"
+NAME="goldeneye-pc-port-${VERSION}-linux-x86_64"
+OUT="dist/${NAME}"
+
+# Accept a build from either the CI Linux tree or a local build-pc/ tree.
+EXE=""
+for cand in build-linux/ge007.x86_64 build-pc/ge007.x86_64 build-linux/ge007* build-pc/ge007*; do
+  if [ -f "$cand" ] && [ -x "$cand" ] && [[ "$cand" != *.exe ]]; then EXE="$cand"; break; fi
+done
+[ -n "$EXE" ] || { echo "error: no Linux ge007 binary found in build-linux/ or build-pc/ — build first" >&2; exit 1; }
+
+echo "==> Bundling $EXE  ->  $NAME"
+rm -rf "$OUT"
+mkdir -p "$OUT/licenses"
+cp "$EXE" "$OUT/"
+chmod +x "$OUT/$(basename "$EXE")"
+
+# --- report the dynamic-library needs (informational; not bundled) -----
+if command -v ldd >/dev/null 2>&1; then
+  echo "    dynamic dependencies (must be present on the target system):"
+  ldd "$EXE" | sed 's/^/      /' || true
+fi
+
+# --- docs + licenses --------------------------------------------------
+EXE_NAME="$(basename "$EXE")"
+DEPS_BLOCK=$'## 1a. Install the runtime libraries\n\nThis Linux build links against your distro\'s SDL2, zlib and OpenGL. Install\nthem first:\n\n```\n# Debian / Ubuntu\nsudo apt install libsdl2-2.0-0 zlib1g libgl1\n\n# Fedora\nsudo dnf install SDL2 zlib libglvnd-glx\n\n# Arch\nsudo pacman -S sdl2 zlib libglvnd\n```\n'
+sed -e "s|@VERSION@|${VERSION}|g" \
+    -e "s|@PLATFORM@|Linux x86-64|g" \
+    -e "s|@EXE@|${EXE_NAME}|g" \
+    -e "s|@LICENSE_EXTRA@||g" \
+    tools_pc/dist/README.md.in > "$OUT/README.md.tmp"
+# @DEPS@ is a multi-line block — substitute it via awk, not sed.
+awk -v repl="$DEPS_BLOCK" '{ if ($0 == "@DEPS@") print repl; else print }' \
+    "$OUT/README.md.tmp" > "$OUT/README.md"
+rm -f "$OUT/README.md.tmp"
+
+cp NOTICE  "$OUT/licenses/NOTICE"
+cp LICENSE "$OUT/licenses/LICENSE-port-MIT.txt"
+[ -f port/fast3d/LICENSE.txt ] && cp port/fast3d/LICENSE.txt "$OUT/licenses/LICENSE-fast3d.txt"
+
+# --- asset-prep tool (identical assembly to bundle-win.sh) -----------
+PREP="$OUT/prepare-assets"
+mkdir -p "$PREP/vendor/scripts" "$PREP/vendor/assets/obseg"
+cp tools_pc/dist/prepare-assets/prepare-assets.py "$PREP/"
+cp tools_pc/d43_emit.py tools_pc/d69_emit.py       "$PREP/"
+cp tools_pc/d88_emit.py tools_pc/d88_propdefs.py   "$PREP/"
+cp scripts/filelist.u.csv                          "$PREP/vendor/scripts/"
+cp assets/obseg/file_resource_table.inc.c          "$PREP/vendor/assets/obseg/"
+find assets -iname 'modelfileheader.inc.c' -print0 \
+  | xargs -0 -I{} cp --parents {} "$PREP/vendor/"
+nmh="$(find "$PREP/vendor/assets" -iname 'modelfileheader.inc.c' | wc -l)"
+echo "    + prepare-assets/ (emit scripts + $nmh model headers)"
+[ "$nmh" -gt 400 ] || { echo "error: prepare-assets vendored only $nmh model headers — expected ~512" >&2; exit 1; }
+
+# --- guard: no ROM / game data snuck in ------------------------------
+if find "$OUT" -type f \( -iname '*.z64' -o -iname '*.n64' -o -iname '*.v64' \) | grep -q .; then
+  echo "error: bundle contains a ROM image — aborting" >&2
+  exit 1
+fi
+BYTES="$(du -sb "$OUT" | cut -f1)"
+LIMIT=$((60 * 1024 * 1024))
+if [ "$BYTES" -gt "$LIMIT" ]; then
+  echo "error: bundle is $BYTES bytes (> 60 MB) — likely contains game data, aborting" >&2
+  exit 1
+fi
+
+# --- tarball + checksum ---------------------------------------------
+( cd dist && rm -f "${NAME}.tar.gz" "${NAME}.tar.gz.sha256" \
+          && tar -czf "${NAME}.tar.gz" "$NAME" \
+          && sha256sum "${NAME}.tar.gz" > "${NAME}.tar.gz.sha256" )
+
+echo "==> dist/${NAME}.tar.gz  ($(du -h "dist/${NAME}.tar.gz" | cut -f1))"
+cat "dist/${NAME}.tar.gz.sha256"
+find "$OUT" -type f | sed "s#^dist/##" | sort

tools_pc/bundle-win.sh

@@ -70,7 +70,13 @@ fi
 [ "$missing" -eq 0 ] || { echo "error: exe needs MinGW DLLs that were not bundled (see above)" >&2; exit 1; }
 
 # --- docs + licenses ---------------------------------------------------
-sed "s/@VERSION@/${VERSION}/g" tools_pc/dist/README.md.in > "$OUT/README.md"
+EXE_NAME="$(basename "$EXE")"
+sed -e "s|@VERSION@|${VERSION}|g" \
+    -e "s|@PLATFORM@|Windows x86-64|g" \
+    -e "s|@EXE@|${EXE_NAME}|g" \
+    -e "s|@DEPS@||g" \
+    -e "s|@LICENSE_EXTRA@|, the MinGW runtime|g" \
+    tools_pc/dist/README.md.in > "$OUT/README.md"
 cp NOTICE  "$OUT/licenses/NOTICE"
 cp LICENSE "$OUT/licenses/LICENSE-port-MIT.txt"
 [ -f port/fast3d/LICENSE.txt ] && cp port/fast3d/LICENSE.txt "$OUT/licenses/LICENSE-fast3d.txt"

tools_pc/dist/README.md.in

@@ -5,15 +5,18 @@ A native PC port of the original Nintendo 64 *GoldenEye 007*, compiled from the
 
 > **Very early research alpha — not a playable game.**
 > The intro and menus render and all 21 solo missions load, but there is
-> **no audio**, some 3D models and text are broken, ladders don't work yet
-> (and can block progression on some levels), and you should expect crashes and
-> glitches past the level intro. This is a technical demo of the porting work.
+> **no audio**, some 3D models and text are broken, outdoor levels render with
+> a black sky, the in-HUD weapon icon is missing, and you should expect crashes
+> and glitches past the level intro. This is a technical demo of the porting
+> work.
 >
 > If you just want to *play* GoldenEye on PC, use one of the Xbox 360
 > recompilation projects instead — see the project page.
 
 Project & source: <https://github.com/jkdansereau/goldeneye-pc-port>
 
+This is the **@PLATFORM@** build. The executable is `@EXE@`.
+
 ---
 
 ## 1. You must supply your own ROM
@@ -28,26 +31,29 @@ NTSC-U (US):
 
 Only the US ROM is supported in this alpha.
 
+@DEPS@
 ## 2. Set up (one time)
 
 1. Unzip this folder anywhere.
-2. Make a `data` folder next to `ge007.x86_64.exe`.
-3. Copy your ROM into it, named exactly: `data\ge007.ntsc-final.z64`
+2. Make a `data` folder next to `@EXE@`.
+3. Copy your ROM into it, named exactly: `data/ge007.ntsc-final.z64`
 4. Prepare the ROM-derived data (needs Python 3.8+ on your PATH):
 
    ```
-   python prepare-assets\prepare-assets.py
+   python3 prepare-assets/prepare-assets.py
    ```
 
-   This reads your ROM and writes `data\pcmodels-ntsc-final\` and
-   `data\pccg-ntsc-final\` next to the exe. It uses only the Python standard
-   library — no compiler or N64 toolchain — and takes a few seconds. Run it
-   again only if you replace the ROM.
+   (On Windows, `python prepare-assets\prepare-assets.py`.)
+
+   This reads your ROM and writes `data/pcmodels-ntsc-final/` and
+   `data/pccg-ntsc-final/` next to the executable. It uses only the Python
+   standard library — no compiler or N64 toolchain — and takes a few seconds.
+   Run it again only if you replace the ROM.
 
 ## 3. Run
 
-Run `ge007.x86_64.exe` **from this folder**. Configuration is written to
-`ge007.ini` on first run.
+Run `@EXE@` **from this folder**. Configuration is written to `ge007.ini` on
+first run.
 
 > If the game exits immediately reporting missing data, re-run step 2.4 above
 > and check it printed `ALL CHECKS PASSED` for both passes.
@@ -73,4 +79,4 @@ endorsed by, or sponsored by Nintendo, Rare, Microsoft, MGM, Danjaq, or EON
 Productions. No ROM, game assets, or official logos are distributed.
 
 See `licenses/` for the port's MIT license, the upstream project `NOTICE`, and
-the third-party library licenses (SDL2, zlib, the MinGW runtime).
+the third-party library licenses (SDL2, zlib@LICENSE_EXTRA@).