chore(ios): update app-repo.json [skip ci]

Merge pull request #1198 from bryanthaboi/dev
bugs and slugs
2026-08-13 00:40:59 +02:00 · 2026-08-12 17:16:13 -04:00 · 2026-08-12 17:07:13 -04:00 · 2026-08-12 16:57:46 -04:00 · 2026-08-12 16:56:46 -04:00 · 2026-08-12 16:56:04 -04:00
1563 changed files with 547626 additions and 9252 deletions
@@ -18,6 +18,21 @@ body:
    validations:
      required: true

+  - type: dropdown
+    id: game
+    attributes:
+      label: Which game were you playing
+      description: Pick every version you saw the bug in. Use N/A if it isn't game-specific.
+      multiple: true
+      options:
+        - Red
+        - Blue
+        - Yellow
+        - Gold
+        - N/A
+    validations:
+      required: true
+
  - type: dropdown
    id: os
    attributes:
@@ -25,10 +40,33 @@ body:
      options:
        - macOS
        - Windows
-        - Both
+        - Linux
+        - Android
+        - iOS
+        - Multiple platforms
    validations:
      required: true

+  - type: dropdown
+    id: mods_enabled
+    attributes:
+      label: Were any mods on
+      description: Check the MODS tab in the launcher if you're not sure.
+      options:
+        - "No"
+        - "Yes"
+    validations:
+      required: true
+
+  - type: input
+    id: mods_which
+    attributes:
+      label: Which mods (if any were on)
+      description: List the enabled mods. Leave blank if none were on.
+      placeholder: nuzlocke 1.0.0, running-shoes 0.3
+    validations:
+      required: false
+
  - type: input
    id: version
    attributes:
@@ -38,6 +76,17 @@ body:
    validations:
      required: true

+  - type: input
+    id: discord
+    attributes:
+      label: Discord username (optional)
+      description: >
+        So maintainers can ping you on Discord if they need a quick follow-up.
+        Leave blank if you'd rather keep everything on GitHub.
+      placeholder: yourname
+    validations:
+      required: false
+
  - type: input
    id: location
    attributes:
@@ -1,35 +1,68 @@
 name: Feature request
-description: Ask for something new, or a change to how something already works.
+description: Ask for something new in the engine, launcher, or platform — not a content/gameplay mod.
 labels: ["enhancement"]
 body:
  - type: markdown
    attributes:
      value: |
+        Use this for **engine / launcher / platform** work (ports, video options, save
+        tooling, networking, mod API seams, docs).
+
+        If what you want is a gameplay, cosmetic, audio, or QoL change that a Lua mod
+        could ship — running shoes, alternate sprites, day/night, shiny indicators,
+        Gen 2-like battle toggles, soundtrack packs — open a
+        **[Mod request](https://github.com/bryanthaboi/gen1recomp/issues/new?template=mod_request.yml)**
+        instead.
+
        "Can we add X" on its own is hard to act on. Say what you want, why you want it,
-        and how you picture it working. A request with real detail is one someone can
-        actually build without guessing at what you meant.
+        and how you picture it working.

  - type: input
    id: summary
    attributes:
      label: One line summary
      description: What you want, in a sentence.
-      placeholder: Add a run toggle so you can move at bike speed without the bike
+      placeholder: Add Linux AppImage releases next to the macOS and Windows builds
    validations:
      required: true

+  - type: dropdown
+    id: game
+    attributes:
+      label: Which game is this about
+      description: Pick every version it applies to. Use N/A if it isn't game-specific.
+      multiple: true
+      options:
+        - Red
+        - Blue
+        - Yellow
+        - Gold
+        - N/A
+    validations:
+      required: true
+
+  - type: input
+    id: discord
+    attributes:
+      label: Discord username (optional)
+      description: >
+        So maintainers can ping you on Discord if they need a quick follow-up.
+        Leave blank if you'd rather keep everything on GitHub.
+      placeholder: yourname
+    validations:
+      required: false
+
  - type: textarea
    id: what
    attributes:
      label: What do you want
      description: >
-        Describe it properly. What is it, where does it live in the game, what does the
-        player see or do. If it changes something that already exists, say what it does today
-        and what it should do instead.
+        Describe it properly. What is it, where does it live (launcher, options,
+        engine), what does the player see or do. If it changes something that already
+        exists, say what it does today and what it should do instead.
      placeholder: |
-        A hold-to-run button, the way later Pokemon games do it. Hold B while moving on
-        foot and the player moves at bike speed. Release and you go back to walking.
-        Doesn't work indoors where the bike doesn't work, doesn't work in battles or menus.
+        Ship a Linux AppImage on each release, same version as the macOS/Windows builds,
+        with the same save folder layout and mod discovery path.
    validations:
      required: true

@@ -41,9 +74,8 @@ body:
        What's annoying or missing right now. What does this fix. If it's just because you
        think it would be fun, say that, it's a real answer.
      placeholder: |
-        Backtracking across routes you've already cleared is slow, and the bike is a menu
-        dive away and doesn't work in a lot of places. Running would cut a lot of dead time
-        without making the game easier.
+        LÖVE already runs on Linux; without a packaged build, players have to assemble
+        it themselves and miss release notes / update checks.
    validations:
      required: true

@@ -52,14 +84,12 @@ body:
    attributes:
      label: How should it work
      description: >
-        The specifics. Which button, which menu, what happens in the edge cases. If you don't
+        The specifics. Which menu, what happens in the edge cases. If you don't
        know, say what you'd expect as a player and leave the rest open.
      placeholder: |
-        - Hold B on the overworld to run
-        - Same speed as the bike
-        - Disabled anywhere the bike is disabled
-        - Sprite should probably need a running animation, not sure what that takes
-        - No effect on encounter rates
+        - GitHub Releases asset next to the .dmg / .exe
+        - Same options.lua / mods/ layout as desktop
+        - Documented in the README install section
    validations:
      required: true

@@ -0,0 +1,130 @@
+name: Mod request
+description: Ask for a gameplay, cosmetic, audio, or QoL change that belongs as a Lua mod.
+labels: ["mod request"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This tracker is for ideas that should ship as **mods**, not as core engine
+        features — alternate sprites, running shoes, day/night, shiny indicators,
+        soundtrack packs, Gen 2-like battle toggles, map cosmetics, bag QoL, etc.
+
+        The engine already exposes a lot of this through registries and hooks
+        ([modding wiki](https://github.com/bryanthaboi/gen1recomp/wiki)).
+        Use a **Feature request** instead for launcher / ports / video options /
+        networking / save tooling / new API seams.
+
+  - type: input
+    id: summary
+    attributes:
+      label: One line summary
+      description: What the mod should do, in a sentence.
+      placeholder: Hold B to run at bike speed on the overworld
+    validations:
+      required: true
+
+  - type: dropdown
+    id: game
+    attributes:
+      label: Which game is this for
+      description: Pick every version the mod should cover. Use N/A if it isn't game-specific.
+      multiple: true
+      options:
+        - Red
+        - Blue
+        - Yellow
+        - Gold
+        - N/A
+    validations:
+      required: true
+
+  - type: input
+    id: discord
+    attributes:
+      label: Discord username (optional)
+      description: >
+        So maintainers or mod authors can ping you on Discord if they pick this up.
+        Leave blank if you'd rather keep everything on GitHub.
+      placeholder: yourname
+    validations:
+      required: false
+
+  - type: textarea
+    id: what
+    attributes:
+      label: What should the mod do
+      description: >
+        Describe the player-facing behavior. What changes, where, what does the
+        player see or press. If it toggles from Options or a START-menu entry, say so.
+      placeholder: |
+        Hold B while walking outdoors to move at bike speed. Release to walk again.
+        Same places the bike is allowed; no effect in battles or menus.
+    validations:
+      required: true
+
+  - type: textarea
+    id: why
+    attributes:
+      label: Why is this worth doing as a mod
+      description: >
+        Why optional/modded rather than a core option. Who wants it on, who wants
+        vanilla left alone.
+      placeholder: |
+        Great for replaying and backtracking, but some people want a strict Gen 1
+        pace. A mod (or an opt-in mod option) keeps both camps happy.
+    validations:
+      required: true
+
+  - type: textarea
+    id: how
+    attributes:
+      label: How should it work
+      description: >
+        Buttons, menus, edge cases, whether it needs new art/audio. If you know a
+        hook or registry that fits (movement.speed, pokemon.sprite, rulesets, …),
+        mention it — otherwise leave it open.
+      placeholder: |
+        - Hold B on the overworld
+        - Same step timing as the bike
+        - Disabled where the bike is disabled
+        - Prefer hooks:wrap("movement.speed") if that still fits
+    validations:
+      required: true
+
+  - type: dropdown
+    id: vanilla
+    attributes:
+      label: With the mod off, is vanilla unchanged
+      options:
+        - Yes — parity when disabled
+        - No — it would replace something always-on
+        - Not sure
+    validations:
+      required: true
+
+  - type: dropdown
+    id: category
+    attributes:
+      label: Best-fit mod category
+      description: Same taxonomy as example mods (BALANCE, GRAPHICS, AUDIO, …).
+      options:
+        - GAMEPLAY / QoL
+        - GRAPHICS
+        - AUDIO
+        - BALANCE / ruleset
+        - CONTENT (maps, encounters, trainers)
+        - UI / TOOL
+        - TOTAL_CONVERSION-ish
+        - Not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else
+      description: >
+        Reference screenshots, other games/hacks that do it, related issues, or
+        "I'd like to try writing this myself." Leave blank if nothing comes to mind.
+    validations:
+      required: false
@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
@@ -10,11 +10,11 @@ name: ci
 # The T3 content tier asserts Pokemon Red facts; scripts/test.sh detects
 # data/generated/ is absent and skips it rather than failing.
 #
-# Runs alongside release.yml, which is untouched by this file.
-
 on:
  push:
-    branches: [main]
+    # Integration branch + release branch. PRs already run via pull_request
+    # (any base); this list is only for post-merge push runs.
+    branches: [dev, main]
  pull_request:

 # a force-push while CI is mid-run should cancel the stale run, not queue
@@ -22,12 +22,360 @@ concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

+permissions:
+  contents: read
+
 jobs:
+  ios-changes:
+    name: detect iOS changes
+    runs-on: ubuntu-latest
+    outputs:
+      changed: ${{ steps.paths.outputs.changed }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - id: paths
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
+          HEAD_SHA: ${{ github.sha }}
+        run: |
+          if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if git diff --name-only "$BASE_SHA" "$HEAD_SHA" | grep -Eq '^(mobile/ios/|scripts/build_ios\.sh$)'; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  ios-build:
+    name: iOS build
+    needs: ios-changes
+    if: needs.ios-changes.outputs.changed == 'true'
+    runs-on: ${{ fromJSON(github.repository == 'bryanthaboi/gen1recomp' && '["self-hosted", "macOS"]' || '"macos-latest"') }}
+    outputs:
+      ipa_url: ${{ steps.upload-ipa.outputs.artifact-url }}
+    steps:
+      - uses: actions/checkout@v7
+      - name: import signing certificate
+        if: github.repository == 'bryanthaboi/gen1recomp'
+        run: |
+          keychain_path="$RUNNER_TEMP/gen1recomp-ci-signing.keychain-db"
+          ci_dir="${POKEMON_CI_DIR:-$HOME/.config/pokemon-ci}"
+          p12="$ci_dir/signing.p12"
+          passfile="$ci_dir/signing.pass"
+          [ -f "$p12" ] && [ -f "$passfile" ] || exit 1
+          p12pw="$(cat "$passfile")"
+          kcpw="$(openssl rand -base64 24)"
+          echo "::add-mask::$kcpw"
+          security delete-keychain "$keychain_path" 2>/dev/null || true
+          security create-keychain -p "$kcpw" "$keychain_path"
+          security set-keychain-settings "$keychain_path"
+          security unlock-keychain -p "$kcpw" "$keychain_path"
+          security import "$p12" -P "$p12pw" -k "$keychain_path" -T /usr/bin/codesign -T /usr/bin/security
+          security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "$kcpw" "$keychain_path" >/dev/null
+          existing="$(security list-keychains -d user | sed -e 's/^[[:space:]]*//' -e 's/"//g')"
+          security list-keychains -d user -s "$keychain_path" $existing
+      - name: install xcbeautify
+        run: brew list xcbeautify >/dev/null 2>&1 || brew install xcbeautify
+      - name: build iOS release
+        env:
+          CANONICAL_REPOSITORY: ${{ github.repository == 'bryanthaboi/gen1recomp' }}
+        run: |
+          if [ "$CANONICAL_REPOSITORY" = true ]; then
+            scripts/build_ios.sh --fetch --device --release
+          else
+            scripts/build_ios.sh --fetch --release
+          fi
+      - name: upload iOS release artifact
+        id: upload-ipa
+        if: github.repository == 'bryanthaboi/gen1recomp'
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-ios-ipa
+          path: dist/ios/gen1recomp.ipa
+          if-no-files-found: error
+          retention-days: 7
+      - name: clean up signing keychain
+        if: ${{ always() && github.repository == 'bryanthaboi/gen1recomp' }}
+        run: security delete-keychain "$RUNNER_TEMP/gen1recomp-ci-signing.keychain-db" 2>/dev/null || true
+
+  switch-changes:
+    name: detect Switch changes
+    runs-on: ubuntu-latest
+    outputs:
+      changed: ${{ steps.paths.outputs.changed }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - id: paths
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
+          HEAD_SHA: ${{ github.sha }}
+        run: |
+          if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if git diff --name-only "$BASE_SHA" "$HEAD_SHA" | grep -Eq '^(scripts/build_switch\.sh$|scripts/switch/|docs/switch-.*\.md$|tests/switch_ci_workflows_test\.lua$|tests/switch_transfer_docs_test\.lua$|\.github/workflows/(ci|release|switch-artifact-comment)\.yml$|src/core/(NxAssetOverlay|Platform|GameVersion)\.lua$|src/import/CacheFs\.lua$|tests/engine/(assets_version_fallback|nx_generated_guard|nx_yellow_boot|switch_diagnostics)_test\.lua$|tests/engine/platform_nx)'; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  switch-selftest:
+    name: Switch offline selftest
+    needs: switch-changes
+    if: needs.switch-changes.outputs.changed == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: install luajit
+        run: sudo apt-get update && sudo apt-get install -y luajit
+      - name: Switch offline selftest
+        run: bash scripts/switch/selftest_build_switch.sh
+      - name: verify_payload self-test
+        run: bash scripts/switch/verify_payload.sh --self-test
+      - name: Switch CI workflow content gate
+        run: luajit tests/switch_ci_workflows_test.lua
+      - name: Switch transfer docs content gate
+        run: luajit tests/switch_transfer_docs_test.lua
+      # NX runtime regressions gate this job via switch-changes; run the NX
+      # engine suites here too so a PR touching them gets feedback on the
+      # fork-safe ubuntu runner before the self-hosted Mac build.
+      - name: NX engine suites (headless)
+        run: |
+          luajit tests/engine/assets_version_fallback_test.lua
+          luajit tests/engine/nx_generated_guard_test.lua
+          luajit tests/engine/nx_yellow_boot_test.lua
+
+  switch-build:
+    name: Switch fused build
+    needs: [switch-changes, switch-selftest]
+    if: |
+      always()
+      && needs.switch-changes.outputs.changed == 'true'
+      && needs.switch-selftest.result == 'success'
+      && github.repository == 'bryanthaboi/gen1recomp'
+      && (github.event_name != 'pull_request'
+          || github.event.pull_request.head.repo.full_name == github.repository)
+    runs-on: ["self-hosted", "macOS"]
+    steps:
+      - uses: actions/checkout@v7
+      - name: Build Switch fused NRO
+        run: |
+          set -euo pipefail
+          VER="$(printf '%s' "$GITHUB_SHA" | cut -c1-7)"
+          scripts/build_switch.sh --fetch --fused --version "$VER"
+          echo "SWITCH_VER=$VER" >> "$GITHUB_ENV"
+      - name: upload Switch NRO artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-switch-nro
+          path: |
+            dist/switch/gen1recomp-${{ env.SWITCH_VER }}-switch.nro
+            dist/switch/gen1recomp-${{ env.SWITCH_VER }}-switch.nro.sha256
+          if-no-files-found: error
+          retention-days: 7
+
+  xbox-uwp-changes:
+    name: detect Xbox UWP changes
+    runs-on: ubuntu-latest
+    outputs:
+      changed: ${{ steps.paths.outputs.changed }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - id: paths
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
+          HEAD_SHA: ${{ github.sha }}
+        run: |
+          if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if git diff --name-only "$BASE_SHA" "$HEAD_SHA" | grep -Eq '^(ports/uwp/|scripts/build_xbox_uwp\.sh$|scripts/xbox-uwp/|scripts/pack_love\.sh$|\.github/workflows/(ci|release)\.yml$|src/core/Platform\.lua$|src/import/(CacheFs|LauncherView|RomImporter)\.lua$|src/update/Check\.lua$|tests/engine/(platform_nx|uwp_baseroms|uwp_native_picker)_test\.lua$|tests/rom_importer_double_pick_test\.lua$)'; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  xbox-uwp-selftest:
+    name: Xbox UWP offline selftest
+    needs: xbox-uwp-changes
+    if: needs.xbox-uwp-changes.outputs.changed == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Xbox UWP offline selftest
+        run: bash scripts/xbox-uwp/selftest_build_xbox_uwp.sh
+      - name: Build shared payload
+        run: |
+          scripts/pack_love.sh \
+            --output .bazinga/work/ci-game.love \
+            --listing .bazinga/work/ci-love-listing.txt \
+            --version 0.0.0
+      - name: Upload shared payload
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-xbox-uwp-payload
+          path: .bazinga/work/ci-game.love
+          if-no-files-found: error
+          retention-days: 1
+
+  xbox-uwp-build:
+    name: Xbox UWP build
+    needs: [xbox-uwp-changes, xbox-uwp-selftest]
+    if: |
+      always()
+      && needs.xbox-uwp-changes.outputs.changed == 'true'
+      && needs.xbox-uwp-selftest.result == 'success'
+    runs-on: windows-2022
+    steps:
+      - uses: actions/checkout@v7
+      - name: Download shared payload
+        uses: actions/download-artifact@v8
+        with:
+          name: gen1recomp-xbox-uwp-payload
+          path: .bazinga/work
+      - name: Build Xbox UWP package
+        shell: bash
+        run: |
+          bash scripts/build_xbox_uwp.sh \
+            --release \
+            --version 0.0.0 \
+            --game-love .bazinga/work/ci-game.love
+      - name: Upload Xbox UWP package
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-xbox-uwp
+          path: |
+            dist/xbox-uwp/gen1recomp-0.0.0-xbox-uwp.zip
+            dist/xbox-uwp/gen1recomp-0.0.0-xbox-uwp.zip.sha256
+          if-no-files-found: error
+          retention-days: 7
+
+  linux-arm64-changes:
+    name: detect Linux arm64 changes
+    runs-on: ubuntu-latest
+    outputs:
+      changed: ${{ steps.paths.outputs.changed }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - id: paths
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
+          HEAD_SHA: ${{ github.sha }}
+        run: |
+          if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if git diff --name-only "$BASE_SHA" "$HEAD_SHA" | grep -Eq '^(scripts/build_linux_arm64\.sh$|scripts/linux-arm64/|scripts/pack_love\.sh$|docs/linux-arm64-build\.md$|\.github/workflows/(ci|release)\.yml$)'; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  linux-arm64-selftest:
+    name: Linux arm64 offline selftest
+    needs: linux-arm64-changes
+    if: needs.linux-arm64-changes.outputs.changed == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # Deliberately on x86_64: everything this gate checks (pins, the
+      # host-arch guard, the dependency exclude list, the AppRun fusion
+      # contract) is answerable without a container or an aarch64 machine,
+      # so the slow native job below only ever starts on a sane tree.
+      - name: Linux arm64 offline selftest
+        run: bash scripts/linux-arm64/selftest_build_linux_arm64.sh
+
+  linux-arm64-build:
+    name: Linux arm64 AppImage build
+    needs: [linux-arm64-changes, linux-arm64-selftest]
+    if: |
+      always()
+      && needs.linux-arm64-changes.outputs.changed == 'true'
+      && needs.linux-arm64-selftest.result == 'success'
+    # No fork restriction, unlike switch-build: this needs no secrets and no
+    # self-hosted hardware, just GitHub's free arm64 runner for public repos,
+    # so contributors get the same coverage on their own PRs.
+    runs-on: ubuntu-24.04-arm
+    steps:
+      - uses: actions/checkout@v7
+      - name: Build the aarch64 AppImage
+        run: |
+          set -euo pipefail
+          scripts/build_linux_arm64.sh --version 0.0.0
+      - name: Verify the AppImage is self-contained and bullseye-compatible
+        run: |
+          set -euo pipefail
+          image="dist/linux-arm64/gen1recomp-0.0.0-linux-arm64.AppImage"
+
+          # --appimage-extract needs no FUSE, so this works on a runner
+          # without /dev/fuse and still exercises the real payload.
+          "$image" --appimage-extract >/dev/null
+          for required in AppRun bin/love game.love lib/liblove-11.5.so; do
+            [ -e "squashfs-root/$required" ] \
+              || { echo "::error::AppImage is missing $required"; exit 1; }
+          done
+
+          # Every bundled object must resolve once AppRun's LD_LIBRARY_PATH is
+          # applied; an unresolved soname here is a user-visible launch crash.
+          #
+          # This runs on a HEADLESS runner on purpose, and that is the point.
+          # The first version of this build bundled Debian's SDL2, which
+          # hard-links libpulse/libasound/libX11/libwayland, so it only ever
+          # started on a full desktop -- a bare runner is what exposed it.
+          missing="$(LD_LIBRARY_PATH="$PWD/squashfs-root/lib" \
+            ldd squashfs-root/bin/love squashfs-root/lib/*.so* 2>/dev/null \
+            | grep 'not found' || true)"
+          [ -z "$missing" ] || { echo "::error::unresolved deps:"; echo "$missing"; exit 1; }
+
+          # Nothing may hard-link a driver, session or audio-stack library:
+          # those must be reached through dlopen so the AppImage runs on a box
+          # with only ALSA, only Wayland, or only KMSDRM.
+          linked="$(for f in squashfs-root/bin/love squashfs-root/lib/*.so*; do
+            objdump -p "$f" 2>/dev/null | awk '/NEEDED/{print $2}'
+          done | sort -u | grep -E '^lib(pulse|asound|X11|wayland|GL|EGL|drm|gbm|xcb|cairo|sndio|dbus)' || true)"
+          [ -z "$linked" ] \
+            || { echo "::error::these must be dlopened, not linked:"; echo "$linked"; exit 1; }
+
+          # The whole point of compiling on bullseye. If a future change moves
+          # the builder to a newer base, the glibc floor silently rises and
+          # every user on an older distro gets "GLIBC_2.xx not found" -- catch
+          # it here instead of in a release.
+          floor="$(objdump -T squashfs-root/bin/love squashfs-root/lib/*.so* 2>/dev/null \
+            | grep -o 'GLIBC_[0-9.]*' | sort -V | tail -1)"
+          echo "highest required glibc symbol version: $floor"
+          [ -n "$floor" ] \
+            || { echo "::error::found no versioned glibc symbols -- objdump read nothing"; exit 1; }
+          highest="$(printf '%s\n' "$floor" "GLIBC_2.31" | sort -V | tail -1)"
+          [ "$highest" = "GLIBC_2.31" ] \
+            || { echo "::error::AppImage requires $floor, above the bullseye 2.31 floor"; exit 1; }
+      - name: Upload the AppImage
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-linux-arm64
+          path: |
+            dist/linux-arm64/gen1recomp-0.0.0-linux-arm64.AppImage
+            dist/linux-arm64/gen1recomp-0.0.0-linux-arm64.AppImage.sha256
+          if-no-files-found: error
+          retention-days: 7
+
  headless:
    name: headless suites (no ROM)
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7

      # LuaJIT, not lua5.4: LOVE 11.x embeds LuaJIT 2.1 and the engine is
      # written to Lua 5.1 semantics, so CI must run the interpreter the
@@ -35,6 +383,9 @@ jobs:
      - name: install luajit
        run: sudo apt-get update && sudo apt-get install -y luajit

+      - name: install Pillow
+        run: python3 -m pip install --upgrade pillow
+
      - name: interpreter version
        run: luajit -v

@@ -45,7 +396,7 @@ jobs:
    name: fixture dataset integrity
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
      - run: sudo apt-get update && sudo apt-get install -y luajit
      - run: python3 -m pip install --upgrade pillow

@@ -87,7 +438,7 @@ jobs:
    name: screenshot differ (capture not yet wired)
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
      - run: python3 -m pip install --upgrade pillow

      # 21-testing-and-ci §"Testing & acceptance criteria": compare_shots
@@ -135,7 +486,7 @@ jobs:
    name: mod lint (no ROM-derived content)
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7

      # the MK305 dump check key-diffs shipped tables through luajit, and
      # modkit treats a missing interpreter as a fatal MK100 -- without
@@ -0,0 +1,55 @@
+name: iOS artifact comment
+
+on:
+  workflow_run:
+    workflows: [ci]
+    types: [completed]
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  comment:
+    if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - id: artifact
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RUN_ID: ${{ github.event.workflow_run.id }}
+          HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
+          HEAD_REPOSITORY: ${{ github.event.workflow_run.head_repository.full_name }}
+        run: |
+          artifact_id="$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$RUN_ID/artifacts" --jq '.artifacts[] | select(.name == "gen1recomp-ios-ipa") | .id')"
+          [ -n "$artifact_id" ] || exit 0
+          head_owner="${HEAD_REPOSITORY%%/*}"
+          pr_number="$(gh api "repos/$GITHUB_REPOSITORY/pulls?state=open&head=$head_owner:$HEAD_BRANCH" --jq '.[0].number // empty')"
+          [ -n "$pr_number" ] || exit 0
+          echo "artifact_url=https://github.com/$GITHUB_REPOSITORY/actions/runs/$RUN_ID/artifacts/$artifact_id" >> "$GITHUB_OUTPUT"
+          echo "pr_number=$pr_number" >> "$GITHUB_OUTPUT"
+      # Upsert via comment-tag only — do not delete-all bot comments (clobbers Switch).
+      - name: Get build info
+        id: build-info
+        env:
+          HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          commit_hash="$(printf '%s' "$HEAD_SHA" | cut -c1-7)"
+          build_time="$(date "+%Y-%m-%d %H:%M:%S")"
+          echo "hash=$commit_hash" >> "$GITHUB_OUTPUT"
+          echo "time=$build_time" >> "$GITHUB_OUTPUT"
+      - name: comment iOS artifact
+        if: steps.artifact.outputs.pr_number != ''
+        uses: thollander/actions-comment-pull-request@v3
+        with:
+          message: |
+            [gen1recomp.ipa](${{ steps.artifact.outputs.artifact_url }})
+
+            **Commit**: [#${{ steps.build-info.outputs.hash }}](https://github.com/${{ github.event.workflow_run.head_repository.full_name }}/commit/${{ github.event.workflow_run.head_sha }})
+            **Build Time**: `${{ steps.build-info.outputs.time }}`
+
+            <sub>This comment was automatically generated. [View workflow run](https://github.com/${{ github.repository }}/actions/runs/${{ github.event.workflow_run.id }})</sub>
+          pr-number: ${{ steps.artifact.outputs.pr_number }}
+          comment-tag: ios-build-result
+          github-token: ${{ github.token }}
@@ -1,7 +1,10 @@
 name: Release

-# Builds the macOS, Windows, and Linux desktop apps plus an Android APK
-# on the self-hosted Mac runner, and publishes them as a GitHub Release.
+# Builds the macOS, Windows, and Linux desktop apps, an Android APK, an iOS
+# IPA, a Nintendo Switch SD-ready zip (experimental), Xbox UWP, the Anbernic
+# RG34XXSP (Stock OS 64-bit MOD / PortMaster) and Linux ARM SBC PortMaster
+# handheld ports on the self-hosted Mac runner, and publishes them as a
+# GitHub Release.
 #
 # Versioning:
 #   - First ever release is 0.1.0.
@@ -10,6 +13,9 @@ name: Release
 #   - To force a specific version, either:
 #       * run this workflow manually (Actions tab) and type it into "version", or
 #       * put "[release X.Y.Z]" anywhere in the commit message.
+#
+# Branch model: day-to-day work merges to `dev`. Releases stay on `main` only
+# so promoting `dev` -> `main` is the ship gate that cuts a build.

 on:
  push:
@@ -20,6 +26,7 @@ on:
    paths-ignore:
      - '.github/**'
      - '**.md'
+      - 'mobile/ios/app-repo.json'
  workflow_dispatch:
    inputs:
      version:
@@ -37,16 +44,17 @@ concurrency:
  cancel-in-progress: false

 jobs:
-  release:
-    runs-on: [self-hosted, macOS]
-
+  version:
+    name: determine release version
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.ver.outputs.version }}
+      tag: ${{ steps.ver.outputs.tag }}
    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
          fetch-tags: true
-
      - name: Determine version
        id: ver
        env:
@@ -54,7 +62,6 @@ jobs:
          GH_TOKEN: ${{ github.token }}
        run: |
          set -euo pipefail
-
          semver_re='^[0-9]+\.[0-9]+\.[0-9]+$'

          # 1) Explicit override from a manual run.
@@ -84,7 +91,6 @@ jobs:
              | grep -E "$semver_re" \
              | sort -t. -k1,1n -k2,2n -k3,3n \
              | tail -1 || true)"
-
            if [ -z "$latest" ]; then
              version="0.1.0"
              echo "No existing release tag; starting at $version"
@@ -112,11 +118,159 @@ jobs:
            echo "::error::Release $tag already exists. Pick a different version."
            exit 1
          fi
-
          echo "version=$version" >> "$GITHUB_OUTPUT"
          echo "tag=$tag" >> "$GITHUB_OUTPUT"

+  love-payload:
+    name: build release game.love
+    needs: version
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Build shared payload
+        run: |
+          scripts/pack_love.sh \
+            --output dist/payload/game.love \
+            --listing dist/payload/love-listing.txt \
+            --version "${{ needs.version.outputs.version }}"
+      - name: Upload shared payload
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-release-love
+          path: dist/payload/game.love
+          if-no-files-found: error
+          retention-days: 1
+
+  linux-arm64:
+    name: build Linux arm64 AppImage
+    needs: [version, love-payload]
+    # GitHub's free arm64 runner for public repos. It has to be arm64: the
+    # AppImage compiles LÖVE natively inside a Debian bullseye arm64
+    # container, and the qemu-emulated alternative takes hours.
+    runs-on: ubuntu-24.04-arm
+    steps:
+      - uses: actions/checkout@v7
+      - name: Download shared payload
+        uses: actions/download-artifact@v8
+        with:
+          name: gen1recomp-release-love
+          path: .bazinga/work
+      - name: Build Linux arm64 AppImage
+        run: |
+          set -euo pipefail
+          scripts/build_linux_arm64.sh \
+            --version "${{ needs.version.outputs.version }}" \
+            --game-love .bazinga/work/game.love
+      - name: Upload Linux arm64 release
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-linux-arm64-release
+          path: |
+            dist/linux-arm64/gen1recomp-${{ needs.version.outputs.version }}-linux-arm64.AppImage
+            dist/linux-arm64/gen1recomp-${{ needs.version.outputs.version }}-linux-arm64.AppImage.sha256
+          if-no-files-found: error
+          retention-days: 1
+
+  xbox-uwp:
+    name: build Xbox UWP release
+    needs: [version, love-payload]
+    runs-on: windows-2022
+    steps:
+      - uses: actions/checkout@v7
+      - name: Download shared payload
+        uses: actions/download-artifact@v8
+        with:
+          name: gen1recomp-release-love
+          path: .bazinga/work
+      - name: Prepare signing certificate
+        shell: pwsh
+        env:
+          CERTIFICATE_BASE64: ${{ secrets.XBOX_UWP_SIGNING_CERTIFICATE }}
+          CERTIFICATE_PASSWORD: ${{ secrets.XBOX_UWP_SIGNING_PASSWORD }}
+          CANONICAL_REPOSITORY: ${{ github.repository == 'bryanthaboi/gen1recomp' }}
+        run: |
+          if ($env:CANONICAL_REPOSITORY -eq 'true' -and
+              [string]::IsNullOrWhiteSpace($env:CERTIFICATE_BASE64)) {
+              throw 'XBOX_UWP_SIGNING_CERTIFICATE is not configured.'
+          }
+          if ([string]::IsNullOrWhiteSpace($env:CERTIFICATE_BASE64)) {
+              "UWP_PUBLISHER=CN=Gen1Recomp" | Out-File $env:GITHUB_ENV -Append
+              exit 0
+          }
+          $pfx = Join-Path $env:RUNNER_TEMP 'gen1recomp-uwp.pfx'
+          [IO.File]::WriteAllBytes($pfx, [Convert]::FromBase64String($env:CERTIFICATE_BASE64))
+          $flags = [Security.Cryptography.X509Certificates.X509KeyStorageFlags]::EphemeralKeySet
+          $cert = [Security.Cryptography.X509Certificates.X509Certificate2]::new(
+              $pfx, $env:CERTIFICATE_PASSWORD, $flags)
+          $cer = Join-Path $env:RUNNER_TEMP 'gen1recomp-uwp.cer'
+          [IO.File]::WriteAllBytes(
+              $cer,
+              $cert.Export([Security.Cryptography.X509Certificates.X509ContentType]::Cert))
+          Import-Certificate -FilePath $cer -CertStoreLocation Cert:\LocalMachine\TrustedPeople | Out-Null
+          "UWP_PFX=$pfx" | Out-File $env:GITHUB_ENV -Append
+          "UWP_CERT_THUMBPRINT=$($cert.Thumbprint)" | Out-File $env:GITHUB_ENV -Append
+          "UWP_PUBLISHER=$($cert.Subject)" | Out-File $env:GITHUB_ENV -Append
+      - name: Build Xbox UWP package
+        shell: bash
+        run: |
+          bash scripts/build_xbox_uwp.sh \
+            --release \
+            --version "${{ needs.version.outputs.version }}" \
+            --publisher "$UWP_PUBLISHER" \
+            --game-love .bazinga/work/game.love
+      - name: Sign and stage Xbox UWP release
+        shell: pwsh
+        env:
+          CERTIFICATE_PASSWORD: ${{ secrets.XBOX_UWP_SIGNING_PASSWORD }}
+        run: |
+          if (-not $env:UWP_PFX) {
+              exit 0
+          }
+          scripts/xbox-uwp/stage_release.ps1 `
+            -Version '${{ needs.version.outputs.version }}' `
+            -Configuration Release `
+            -BuildInfo .bazinga/work/xbox-uwp-build-info.json `
+            -CertificatePath $env:UWP_PFX `
+            -CertificatePassword $env:CERTIFICATE_PASSWORD
+      - name: Upload Xbox UWP release
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-xbox-uwp-release
+          path: |
+            dist/xbox-uwp/gen1recomp-${{ needs.version.outputs.version }}-xbox-uwp.zip
+            dist/xbox-uwp/gen1recomp-${{ needs.version.outputs.version }}-xbox-uwp.zip.sha256
+          if-no-files-found: error
+          retention-days: 1
+      - name: Remove signing certificate
+        if: always()
+        shell: pwsh
+        run: |
+          if ($env:UWP_CERT_THUMBPRINT) {
+              Remove-Item "Cert:\LocalMachine\TrustedPeople\$env:UWP_CERT_THUMBPRINT" -ErrorAction SilentlyContinue
+          }
+          if ($env:UWP_PFX) {
+              Remove-Item $env:UWP_PFX -Force -ErrorAction SilentlyContinue
+          }
+
+  release:
+    needs: [version, xbox-uwp, linux-arm64]
+    runs-on: ${{ fromJSON(github.repository == 'bryanthaboi/gen1recomp' && '["self-hosted", "macOS"]' || '"macos-latest"') }}
+
+    steps:
+      # The self-hosted runner lives under the machine owner's home
+      # directory; mask it first so absolute paths in every later step's
+      # output show up as *** in the public workflow logs.
+      - name: Mask runner paths
+        run: echo "::add-mask::$HOME"
+
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
      - name: Import signing certificate into a temporary keychain
+        if: github.repository == 'bryanthaboi/gen1recomp'
        run: |
          set -euo pipefail
          KEYCHAIN_PATH="$RUNNER_TEMP/pokemon-signing.keychain-db"
@@ -159,14 +313,65 @@ jobs:
          # notarize separately below so it uses secret credentials, not a
          # login-keychain profile. "all" also builds the Linux AppImage,
          # which needs no signing/notarization.
-          scripts/build.sh all --version "${{ steps.ver.outputs.version }}" --no-notarize
+          scripts/build.sh all --version "${{ needs.version.outputs.version }}" --no-notarize

      - name: Build Android
        run: |
          set -euo pipefail
-          scripts/build_android.sh --version "${{ steps.ver.outputs.version }}"
+          scripts/build_android.sh --version "${{ needs.version.outputs.version }}"
+
+      - name: Install xcbeautify
+        run: |
+          set -euo pipefail
+          brew list xcbeautify >/dev/null 2>&1 || brew install xcbeautify
+
+      - name: Build iOS
+        env:
+          CANONICAL_REPOSITORY: ${{ github.repository == 'bryanthaboi/gen1recomp' }}
+        run: |
+          set -euo pipefail
+          if [ "$CANONICAL_REPOSITORY" = true ]; then
+            scripts/build_ios.sh --fetch --device --release \
+              --version "${{ needs.version.outputs.version }}"
+          else
+            scripts/build_ios.sh --fetch --release \
+              --version "${{ needs.version.outputs.version }}"
+          fi
+
+      - name: Build Switch
+        run: |
+          set -euo pipefail
+          # Hard-fail gate: Switch ships with every release (never soft-fail).
+          # PR CI is path-gated (ubuntu selftest + canonical fused); release
+          # always builds Switch regardless of which files changed.
+          # Needs native switch-tools (nacptool/elf2nro) and/or Docker on the
+          # Mac self-hosted runner; see docs/switch-build.md.
+          scripts/build_switch.sh --fetch --fused \
+            --version "${{ needs.version.outputs.version }}"
+
+      - name: Build Anbernic RG34XXSP port
+        run: |
+          set -euo pipefail
+          # Self-contained aarch64 PortMaster-style pack; pulls the LÖVE 11.5
+          # runtime from PortMaster-GUI, so it needs no signing/notarization.
+          ./build-rg34xxsp.sh --version "${{ needs.version.outputs.version }}"
+
+      - name: Build Linux ARM SBC PortMaster port
+        env:
+          # The release workflow must package the commit being released. The
+          # script defaults to the latest published release for standalone
+          # builds, while this explicit local override keeps CI source-aligned.
+          GEN1RECOMP_SOURCE_DIR: ${{ github.workspace }}
+          GEN1RECOMP_RELEASE_TAG: v${{ needs.version.outputs.version }}
+        run: |
+          set -euo pipefail
+          # Same aarch64 PortMaster-style pack for Linux ARM SBC PortMaster. The build
+          # keeps its own cache because the two scripts use different staging
+          # layouts and runtime package paths.
+          ./build-linux-arm-sbc.sh --version "${{ needs.version.outputs.version }}"

      - name: Notarize & staple macOS app
+        if: github.repository == 'bryanthaboi/gen1recomp'
        run: |
          set -euo pipefail
          ci_dir="${POKEMON_CI_DIR:-$HOME/.config/pokemon-ci}"
@@ -177,8 +382,8 @@ jobs:
          set -a; . "$ci_dir/notary.env"; set +a
          echo "::add-mask::$APPLE_APP_PASSWORD"

-          app=".bazinga/work/PokemonRed.app"
-          zip="dist/mac/PokemonRed-macos.zip"
+          app=".bazinga/work/gen1recomp.app"
+          zip="dist/mac/gen1recomp-macos.zip"
          [ -d "$app" ] || { echo "::error::signed app not found at $app"; exit 1; }
          if [ -z "${APPLE_ID:-}" ] || [ -z "${APPLE_APP_PASSWORD:-}" ] || [ -z "${APPLE_TEAM_ID:-}" ]; then
            echo "::error::notary.env is missing APPLE_ID / APPLE_APP_PASSWORD / APPLE_TEAM_ID."
@@ -200,43 +405,124 @@ jobs:
          ditto -c -k --sequesterRsrc --keepParent "$app" "$zip"
          echo "Notarized + stapled ✓"

+      - name: Download Xbox UWP release
+        if: github.repository == 'bryanthaboi/gen1recomp'
+        uses: actions/download-artifact@v8
+        with:
+          name: gen1recomp-xbox-uwp-release
+          path: dist/xbox-uwp
+
+      - name: Download Linux arm64 release
+        if: github.repository == 'bryanthaboi/gen1recomp'
+        uses: actions/download-artifact@v8
+        with:
+          name: gen1recomp-linux-arm64-release
+          path: dist/linux-arm64
+
      - name: Stage release assets
+        if: github.repository == 'bryanthaboi/gen1recomp'
        id: assets
        run: |
          set -euo pipefail
-          v="${{ steps.ver.outputs.version }}"
+          v="${{ needs.version.outputs.version }}"
          outdir="dist/release"
          rm -rf "$outdir"
          mkdir -p "$outdir"
-          cp "dist/mac/PokemonRed-macos.zip" "$outdir/PokemonRed-${v}-macos.zip"
-          cp "dist/win/PokemonRed-win64.zip" "$outdir/PokemonRed-${v}-windows.zip"
-          cp "dist/linux/PokemonRed-linux.zip" "$outdir/PokemonRed-${v}-linux.zip"
+          cp "dist/mac/gen1recomp-macos.zip" "$outdir/gen1recomp-${v}-macos.zip"
+          cp "dist/win/gen1recomp-win64.zip" "$outdir/gen1recomp-${v}-windows.zip"
+          cp "dist/linux/gen1recomp-linux.zip" "$outdir/gen1recomp-${v}-linux.zip"
+
+          # arm64 desktop Linux (Raspberry Pi, Armbian, arm64 VMs). Built on
+          # its own runner because LÖVE publishes no aarch64 binary and the
+          # AppImage has to be compiled natively; ships as a runnable
+          # AppImage rather than a zip so `chmod +x && ./it` just works.
+          arm64_appimage="dist/linux-arm64/gen1recomp-${v}-linux-arm64.AppImage"
+          [ -f "$arm64_appimage" ] || { echo "::error::$arm64_appimage not found (expected from the linux-arm64 job)"; exit 1; }
+          cp "$arm64_appimage" "$outdir/gen1recomp-${v}-linux-arm64.AppImage"
+          chmod +x "$outdir/gen1recomp-${v}-linux-arm64.AppImage"
          apk="$(find dist/android/debug -name '*.apk' | head -1)"
          [ -n "$apk" ] || { echo "::error::no Android APK found under dist/android/debug"; exit 1; }
-          cp "$apk" "$outdir/PokemonRed-${v}-android.apk"
+          cp "$apk" "$outdir/gen1recomp-${v}-android.apk"
+
+          ipa="dist/ios/gen1recomp.ipa"
+          [ -f "$ipa" ] || { echo "::error::$ipa not found (expected from scripts/build_ios.sh --device)"; exit 1; }
+          cp "$ipa" "$outdir/gen1recomp-${v}-ios.ipa"
+
+          swzip="dist/switch/gen1recomp-${v}-switch.zip"
+          [ -f "$swzip" ] || { echo "::error::$swzip not found (expected from scripts/build_switch.sh --fused → pack_sd_zip.sh)"; exit 1; }
+          cp "$swzip" "$outdir/gen1recomp-${v}-switch.zip"
+          # Local fused .nro stays under dist/switch/ for PR CI / debug; release
+          # publishes the SD-ready zip only.
+
+          uwp="dist/xbox-uwp/gen1recomp-${v}-xbox-uwp.zip"
+          [ -f "$uwp" ] || { echo "::error::$uwp not found (expected from the Xbox UWP job)"; exit 1; }
+          cp "$uwp" "$outdir/gen1recomp-${v}-xbox-uwp.zip"
+
+          # Anbernic handheld port (suffix names the CFW it targets, so a
+          # future RG35XX/other-CFW pack can ship alongside it).
+          rg34="dist/rg34xxsp/gen1recomp-rg34xxsp-stockos64-mod.zip"
+          [ -f "$rg34" ] || { echo "::error::$rg34 not found (expected from ./build-rg34xxsp.sh)"; exit 1; }
+          cp "$rg34" "$outdir/gen1recomp-${v}-rg34xxsp-stockos64-mod.zip"
+
+          # Linux ARM SBC PortMaster handheld port.
+          sbc="dist/linux-arm-sbc/gen1recomp-sbc-portmaster.zip"
+          [ -f "$sbc" ] || { echo "::error::$sbc not found (expected from ./build-linux-arm-sbc.sh)"; exit 1; }
+          cp "$sbc" "$outdir/gen1recomp-${v}-sbc-portmaster.zip"
+
+          # Platform-independent update payload, built alongside the desktop
+          # apps above (same game.love that gets fused into each of them).
+          love_file=".bazinga/work/game.love"
+          [ -f "$love_file" ] || { echo "::error::$love_file not found (expected from scripts/build.sh)"; exit 1; }
+          cp "$love_file" "$outdir/gen1recomp-${v}.love"
+
          ls -lh "$outdir"

+          # Checksums for every staged release asset (sums file itself is
+          # written after this and named outside the gen1recomp-* glob, so it
+          # never lists itself).
+          (cd "$outdir" && shasum -a 256 gen1recomp-* > sha256sums.txt)
+          cat "$outdir/sha256sums.txt"
+
      - name: Publish GitHub Release
+        if: github.repository == 'bryanthaboi/gen1recomp'
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          set -euo pipefail
-          v="${{ steps.ver.outputs.version }}"
-          tag="${{ steps.ver.outputs.tag }}"
+          v="${{ needs.version.outputs.version }}"
+          tag="${{ needs.version.outputs.tag }}"

-          # Issues this release closes, per GitHub's own "closing issues" links
-          # (works for squash, rebase, and merge commits alike). Scans every
-          # commit since the previous tag so a skipped release run doesn't drop
-          # issues on the floor.
+          # Issues this release closes. Three sources, deduped by number:
+          #   1. GitHub's own "closing issues" links on every PR whose
+          #      commits are in the range (works for squash, rebase, and
+          #      merge commits alike) -- including PRs that were merged
+          #      into a branch this release PR is itself merging in.
+          #   2. CLOSES/fixes/resolves text in those PRs' titles + bodies
+          #      that GitHub didn't turn into a closing link (a PR into a
+          #      non-default branch never gets one).
+          #   3. The same text in raw commit messages, so a direct push
+          #      with "CLOSES #N #M" still lands in the notes.
+          # Scans every commit since the previous tag so a skipped release
+          # run doesn't drop issues on the floor.
          prev_tag="$(git tag -l 'v*' --sort=-v:refname | grep -v "^${tag}$" | head -1 || true)"
          range="${prev_tag:+${prev_tag}..}$GITHUB_SHA"

-          closed=""
-          for pr in $(git log --pretty=%H "$range" \
-                        | xargs -I{} gh api "repos/$GITHUB_REPOSITORY/commits/{}/pulls" \
-                              --jq '.[].number' 2>/dev/null \
-                        | sort -un || true); do
-            closed+="$(gh api graphql \
+          # every #N on a line that carries a closing keyword (handles the
+          # multi-issue "CLOSES #1 #2 #3" form the tracker uses)
+          scan_closes() {
+            grep -iE '\b(close[sd]?|fix(es|ed)?|resolve[sd]?)\b' \
+              | grep -oE '#[0-9]+' | tr -d '#' || true
+          }
+
+          nums=""
+          nums+=" $(git log --pretty=%B "$range" | scan_closes | tr '\n' ' ')"
+
+          prs="$(git log --pretty=%H "$range" \
+                   | xargs -I{} gh api "repos/$GITHUB_REPOSITORY/commits/{}/pulls" \
+                         --jq '.[].number' 2>/dev/null \
+                   | sort -un || true)"
+          for pr in $prs; do
+            nums+=" $(gh api graphql \
              -f owner="${GITHUB_REPOSITORY%/*}" \
              -f name="${GITHUB_REPOSITORY#*/}" \
              -F pr="$pr" \
@@ -244,33 +530,139 @@ jobs:
                query($owner:String!, $name:String!, $pr:Int!) {
                  repository(owner:$owner, name:$name) {
                    pullRequest(number:$pr) {
-                      closingIssuesReferences(first:50) { nodes { number title } }
+                      closingIssuesReferences(first:50) { nodes { number } }
                    }
                  }
                }' \
-              --jq '.data.repository.pullRequest.closingIssuesReferences.nodes[]
-                    | "- #\(.number) \(.title)"' 2>/dev/null || true)"$'\n'
+              --jq '.data.repository.pullRequest.closingIssuesReferences.nodes[].number' \
+              2>/dev/null | grep -E '^[0-9]+$' | tr '\n' ' ' || true)"
+            nums+=" $(gh api "repos/$GITHUB_REPOSITORY/pulls/$pr" \
+              --jq '.title + " " + (.body // "")' 2>/dev/null \
+              | scan_closes | tr '\n' ' ' || true)"
+          done
+
+          # dedupe, drop anything that is a PR or does not exist, keep
+          # titles (gh api prints the response body to stdout on an HTTP
+          # error, so only a zero exit counts)
+          closed=""
+          for n in $(printf '%s' "$nums" | tr ' ' '\n' | grep -E '^[0-9]+$' | sort -un); do
+            if title="$(gh api "repos/$GITHUB_REPOSITORY/issues/$n" \
+                --jq 'if .pull_request then empty else .title end' \
+                2>/dev/null)"; then
+              [ -n "$title" ] && closed+="- #$n $title"$'\n'
+            fi
          done
          closed="$(printf '%s' "$closed" | grep . | sort -t'#' -k2 -n || true)"

+          # Everyone whose commits are in the range: GitHub login when the
+          # commit is linked to an account, the raw git author name when not;
+          # CI bots filtered out.
+          base="${prev_tag:-$(git rev-list --max-parents=0 "$GITHUB_SHA" | tail -1)}"
+          contributors="$(gh api --paginate \
+            "repos/$GITHUB_REPOSITORY/compare/${base}...${GITHUB_SHA}" \
+            --jq '.commits[] | if .author and .author.login
+                              then "@" + .author.login
+                              else .commit.author.name end' 2>/dev/null \
+            | grep -viE '\[bot\]$' | sort -uf | sed 's/^/- /' || true)"
+
          notes="Download the correct version for your computer below."
          if [ -n "$closed" ]; then
            notes+=$'\n\n## Issues closed\n\n'"$closed"
          fi
+          if [ -n "$contributors" ]; then
+            notes+=$'\n\n## Contributors\n\n'"$contributors"
+          fi
          printf 'Release notes:\n%s\n' "$notes"

+          release_files=(
+            "dist/release/gen1recomp-${v}-macos.zip"
+            "dist/release/gen1recomp-${v}-windows.zip"
+            "dist/release/gen1recomp-${v}-linux.zip"
+            "dist/release/gen1recomp-${v}-linux-arm64.AppImage"
+            "dist/release/gen1recomp-${v}-android.apk"
+            "dist/release/gen1recomp-${v}-ios.ipa"
+            "dist/release/gen1recomp-${v}-switch.zip"
+            "dist/release/gen1recomp-${v}-xbox-uwp.zip"
+            "dist/release/gen1recomp-${v}-rg34xxsp-stockos64-mod.zip"
+            "dist/release/gen1recomp-${v}-sbc-portmaster.zip"
+            "dist/release/gen1recomp-${v}.love"
+            "dist/release/sha256sums.txt"
+          )
+
          gh release create "$tag" \
            --target "$GITHUB_SHA" \
            --title "$v" \
            --notes "$notes" \
-            "dist/release/PokemonRed-${v}-macos.zip" \
-            "dist/release/PokemonRed-${v}-windows.zip" \
-            "dist/release/PokemonRed-${v}-linux.zip" \
-            "dist/release/PokemonRed-${v}-android.apk"
+            "${release_files[@]}"

          echo "Published release $tag"

+      - name: Update iOS app repository
+        if: github.repository == 'bryanthaboi/gen1recomp'
+        run: |
+          set -euo pipefail
+          v="${{ needs.version.outputs.version }}"
+          ipa="dist/release/gen1recomp-${v}-ios.ipa"
+          app_repo="mobile/ios/app-repo.json"
+          [ -f "$ipa" ] || { echo "::error::$ipa not found"; exit 1; }
+          [ -f "$app_repo" ] || { echo "::error::$app_repo not found"; exit 1; }
+
+          date="$(date -u +"%Y-%m-%d")"
+          size="$(wc -c < "$ipa" | tr -d '[:space:]')"
+          download_url="https://github.com/${GITHUB_REPOSITORY}/releases/download/v${v}/gen1recomp-${v}-ios.ipa"
+          localized_description="Gen1Recomp - A native Lua / LÖVE2D recreation of Gen 1 Poke"
+          release_notes="$(GH_TOKEN="${{ github.token }}" gh release view "v${v}" --json body --jq '.body // ""' 2>/dev/null || true)"
+          if [ -n "$release_notes" ]; then
+            localized_description="$release_notes"
+          fi
+          entry="$(jq -n \
+            --arg version "$v" \
+            --arg date "$date" \
+            --arg download_url "$download_url" \
+            --arg localized_description "$localized_description" \
+            --argjson size "$size" \
+            '{version: $version, date: $date, size: $size, downloadURL: $download_url, localizedDescription: $localized_description}')"
+
+          if jq -e --arg version "$v" \
+            'any(.apps[] | select(.bundleIdentifier == "com.theboisclub.gen1recomp").versions[]?; .version == $version)' \
+            "$app_repo" >/dev/null; then
+            jq --arg version "$v" --argjson entry "$entry" \
+              '(.apps[] | select(.bundleIdentifier == "com.theboisclub.gen1recomp").versions) |= map(if .version == $version then $entry else . end)' \
+              "$app_repo" > "$app_repo.tmp"
+          else
+            jq --argjson entry "$entry" \
+              '(.apps[] | select(.bundleIdentifier == "com.theboisclub.gen1recomp").versions) |= [$entry] + .' \
+              "$app_repo" > "$app_repo.tmp"
+          fi
+          mv "$app_repo.tmp" "$app_repo"
+
+      # main is PR-only for everyone except deploy keys (the "main protection"
+      # ruleset's bypass actor), so this push must authenticate with the
+      # RELEASE_DEPLOY_KEY deploy key over SSH; the workflow's GITHUB_TOKEN
+      # would be rejected by the branch protection.
+      - name: Commit iOS app repository
+        if: github.repository == 'bryanthaboi/gen1recomp'
+        env:
+          DEPLOY_KEY: ${{ secrets.RELEASE_DEPLOY_KEY }}
+        run: |
+          set -euo pipefail
+          git add mobile/ios/app-repo.json
+          if git diff --cached --quiet; then
+            echo "app-repo.json unchanged; nothing to push"
+            exit 0
+          fi
+          key="$RUNNER_TEMP/release-deploy-key"
+          printf '%s\n' "$DEPLOY_KEY" > "$key"
+          chmod 600 "$key"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git commit -m "chore(ios): update app-repo.json [skip ci]"
+          git -c core.sshCommand="ssh -i $key -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new" \
+            push "git@github.com:${GITHUB_REPOSITORY}.git" "HEAD:${GITHUB_REF_NAME}"
+          rm -f "$key"
+
      - name: Clean up signing keychain
-        if: always()
+        if: ${{ always() && github.repository == 'bryanthaboi/gen1recomp' }}
        run: |
          security delete-keychain "$RUNNER_TEMP/pokemon-signing.keychain-db" 2>/dev/null || true
+          rm -f "$RUNNER_TEMP/release-deploy-key"
@@ -0,0 +1,55 @@
+name: Switch artifact comment
+
+on:
+  workflow_run:
+    workflows: [ci]
+    types: [completed]
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  comment:
+    if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - id: artifact
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RUN_ID: ${{ github.event.workflow_run.id }}
+          HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
+          HEAD_REPOSITORY: ${{ github.event.workflow_run.head_repository.full_name }}
+        run: |
+          artifact_id="$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$RUN_ID/artifacts" --jq '.artifacts[] | select(.name == "gen1recomp-switch-nro") | .id')"
+          [ -n "$artifact_id" ] || exit 0
+          head_owner="${HEAD_REPOSITORY%%/*}"
+          pr_number="$(gh api "repos/$GITHUB_REPOSITORY/pulls?state=open&head=$head_owner:$HEAD_BRANCH" --jq '.[0].number // empty')"
+          [ -n "$pr_number" ] || exit 0
+          echo "artifact_url=https://github.com/$GITHUB_REPOSITORY/actions/runs/$RUN_ID/artifacts/$artifact_id" >> "$GITHUB_OUTPUT"
+          echo "pr_number=$pr_number" >> "$GITHUB_OUTPUT"
+      # Upsert via comment-tag only — do not delete-all bot comments (clobbers iOS).
+      - name: Get build info
+        id: build-info
+        env:
+          HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          commit_hash="$(printf '%s' "$HEAD_SHA" | cut -c1-7)"
+          build_time="$(date "+%Y-%m-%d %H:%M:%S")"
+          echo "hash=$commit_hash" >> "$GITHUB_OUTPUT"
+          echo "time=$build_time" >> "$GITHUB_OUTPUT"
+      - name: comment Switch artifact
+        if: steps.artifact.outputs.pr_number != ''
+        uses: thollander/actions-comment-pull-request@v3
+        with:
+          message: |
+            [gen1recomp-switch.nro](${{ steps.artifact.outputs.artifact_url }})
+
+            **Commit**: [#${{ steps.build-info.outputs.hash }}](https://github.com/${{ github.event.workflow_run.head_repository.full_name }}/commit/${{ github.event.workflow_run.head_sha }})
+            **Build Time**: `${{ steps.build-info.outputs.time }}`
+
+            <sub>This comment was automatically generated. [View workflow run](https://github.com/${{ github.repository }}/actions/runs/${{ github.event.workflow_run.id }})</sub>
+          pr-number: ${{ steps.artifact.outputs.pr_number }}
+          comment-tag: switch-build-result
+          github-token: ${{ github.token }}
@@ -16,6 +16,7 @@ __pycache__/
 .*
 !.github/
 !.gitignore
+!.luacheckrc

 # Android build outputs / local SDK path / packaged payload (keep love-android sources)
 mobile/android/app/build/
@@ -30,8 +31,47 @@ mobile/ios/love-src/
 mobile/ios/cache/
 mobile/ios/build/

-# Final packaged build artifacts (mac/win/web/android/ios) — see scripts/build.sh
+# love-nx vendor binaries (fetch per docs/switch-build.md; also covered by .*)
+.bazinga/love-nx/
+
+# Final packaged build artifacts (mac/win/web/android/ios/switch) — see scripts/build.sh
 /dist/

+# Switch OTA launcher build outputs
+ports/switch/ota-launcher/build/
+ports/switch/ota-launcher/build-host/
+ports/switch/ota-launcher/*.nro
+ports/switch/ota-launcher/*.nacp
+ports/switch/ota-launcher/*.elf
+ports/switch/ota-launcher/*.map
+ports/switch/ota-launcher/romfs/logo.rgba
+ports/switch/ota-launcher/romfs/logo.png
+ports/switch/ota-launcher/romfs/cacert.pem
+ports/switch/ota-launcher/romfs/ota-bootstrap.nro
+ports/switch/ota-bootstrap/build/
+ports/switch/ota-bootstrap/*.nro
+ports/switch/ota-bootstrap/*.nacp
+ports/switch/ota-bootstrap/*.elf
+ports/switch/ota-bootstrap/*.map
+
 # Legacy manual convenience-copy location (superseded by /dist/android/)
 mobile/dist/
+
+# Tiled map-editing workspace (tools/tiled_export.py). Derived from the imported
+# ROM cache exactly like data/generated/, so it is never committable.
+/build/tiled/
+
+# per-machine iOS bundle-id pin (see scripts/build_ios.sh)
+mobile/ios/bundle_id.local
+
+# Xbox UWP build output
+/ports/uwp/build/
+/ports/uwp/third_party/*/source/
+/ports/uwp/third_party/angle/depot_tools/
+
+# Native TLS dialer build output (dotnet publish)
+/native/tls_dial/bin/
+/native/tls_dial/obj/
+/dist/native/
+/dist/win/
+/.bazinga/
@@ -0,0 +1,43 @@
+-- Static-analysis config for `luacheck` (https://luacheck.readthedocs.io).
+--
+-- Run it over the engine with:  luacheck src   (or scripts/lint.sh)
+--
+-- The point is a high-signal baseline: the categories left on are the ones
+-- that catch real defects -- undefined globals/locals (the class that hid a
+-- `music.volume` crash: applyVolume read a `state` that was still the nil
+-- global), unused values, unreachable code, redefinitions. The cosmetic
+-- categories the codebase deliberately lives with (a `self`/`dt` an
+-- interface requires but a given method ignores, documented empty
+-- fall-through branches, the odd long line) are muted so they don't drown
+-- the signal.
+
+std = "luajit"
+
+-- LÖVE exposes `love` as a mutable table: games assign their callbacks onto
+-- it (love.wheelmoved, love.run, ...), so it is a regular global, not
+-- read-only -- otherwise every callback registration reads as a violation.
+globals = { "love" }
+
+read_globals = {
+  "jit",
+  -- LuaJIT 2.1 ships table.unpack even though the bare 5.1 `table` std lacks
+  -- it; without this, every `table.unpack` reads as an undefined field.
+  table = { fields = { "unpack" } },
+}
+
+-- Vendored/native trees and the test suites have their own conventions.
+exclude_files = {
+  "mobile/",
+  "tests/",
+  "tools/save-editor/",
+}
+
+ignore = {
+  "212",  -- unused argument -- self/dt kept for a shared method signature
+  "213",  -- unused loop variable -- `for _, v in` where only v is wanted
+  "421",  -- shadowing a local -- deliberate re-use in a few tight scopes
+  "431",  -- shadowing an upvalue
+  "432",  -- shadowing an argument
+  "542",  -- empty if branch -- documented fall-throughs, not gaps
+  "631",  -- line is too long
+}
@@ -118,6 +118,7 @@ not a hard error, so the list can grow without breaking old mods.
 | `QUEST` | New story, NPCs, dialogue, cutscenes | content |
 | `MECHANIC` | New or changed battle/field mechanics via hooks/effects | overhaul |
 | `GRAPHICS` | Sprite / tileset / palette / font changes | content |
+| `LANGUAGE` | A translation: `text`, `strings` and the glyphs it needs | content |
 | `AUDIO` | Music, sfx, cries | content |
 | `UI` | New or modified screens, menus, overlays | content / overhaul |
 | `TOOL` | Dev/QoL utilities, overlays, inter-mod libraries | content |
@@ -128,7 +129,120 @@ not a hard error, so the list can grow without breaking old mods.
 keeps validating with the value it has shipped since before the taxonomy
 existed.

-### 4. `mod.card`
+A translation may also set `"language": true` in the manifest. That is the
+one claim online play acts on: an install running nothing but verified
+translations may take an ONLINE MATCH or a TOURNAMENT instead of being
+asked to restart vanilla. The claim is checked, not taken -- the mod
+qualifies only if every record it writes lands in `text`, `strings` or
+`font`, it wraps no hook, subscribes to no event and requests no
+permission. Anything else and it is an ordinary content mod that happens to
+ship text.
+
+### 4. `games` (and the legacy `gen2compat`)
+
+Pokemon Gold is Gen 2, and it runs its own battle engine, overworld, script
+VM and save format. The mod API is shared across both generations (same hook
+names, same event names, same registry names) but Gold cannot serve all of it
+yet, so Gen 2 is opt-in. Say which games the mod is for:
+
+```json
+"games": ["gen1", "gen2"]
+```
+
+Each entry is a version id (`"red"`, `"blue"`, `"yellow"`, `"gold"`), a
+generation (`"gen1"`, `"gen2"`) or `"all"`;
+`src/mods/ModTargets.lua` resolves them off `GameVersion.ORDER` so nothing
+restates the game list. `python3 tools/modkit.py scaffold my_mod --games
+gen1,gen2` writes the key for you. The mod still installs to one directory,
+`mods/<id>/`, shared by every game -- targeting is declared, never filed.
+
+Absent means Gen 1 only, which is what every mod written before the key existed
+was tested as. `"gen2compat": true` is the legacy spelling, still accepted and
+purely additive (it *adds* the Gen 2 games), so no manifest can lose a game it
+already ran on. On a Gold boot a mod claiming no Gen 2 game is not loaded at
+all: the manager lists it as `ENABLED (NOT THIS GAME)` and says why, because a
+mod that half-applies reads as a broken mod. Claim Gen 2 once you have actually
+run your mod on Gold.
+
+Every token is enforced, per game: the loader gates on the same
+`ModTargets.supports` answer both mod surfaces draw, so `"games": ["blue"]`
+really does not load on Red and the skip line is the launcher's line, `For
+Blue, not Red`, and `"games": ["gold"]` alone does not load on Red either. A
+manifest with neither key still covers every Gen 1 game, so nothing written
+before the key existed changes behavior; list both generations or say `"all"`
+when you mean everywhere.
+
+`docs/mod-api-gen2-compat.md` is the compatibility matrix: what works on Gold
+today (40 of the 46 registries, 40 event and 43 hook names shared with Gen 1,
+and 24 Gen 2-only ones), which registries have no Gen 2 home and drop their
+writes with a report, and which hooks and events are still to come.
+`docs/preparing-your-mod-for-gen2.md` is the step-by-step migration guide for a
+Gen 1 mod, and it is the one to start from.
+
+Two consequences worth knowing before you claim Gen 2.
+
+**Dependencies are contagious.** A mod whose hard dependency does not run here
+is left out too, with the dependency's own wording (`depends on X, which does
+not run here (For Blue, not Red)`). It is reported as a skip, not as a failure,
+and neither mod lands on the boot error list, but the mod does not run, so
+every hard dependency has to cover the same games.
+
+**The player can override you.** The claim is yours, and a mod written before
+the key existed can never carry one, so the manager's detail pane offers
+`TRY HERE ANYWAY` for any mod that does not claim the game being played. It
+persists per game in `options.modsGen2[id][version]` and takes effect on the
+next boot; forcing a mod onto Red does not force it onto Gold. A forced mod
+loads normally and keeps a note saying its author never verified it here.
+
+**Prefer the API on Gold, but the Gen 1 names still work.** Gen 2 is a
+parallel module tree behind `src/core/Game2.lua`. In new code take the live
+game from `mod.game` (or the `game.ready` payload, or any `ui.*` hook's first
+argument) and the world from `mod.world`; both resolve per generation, and
+neither needs `engine_internals`.
+
+For the mods written before Gold existed, a require made from a mod's own file
+is answered on a Gold boot by an adapter presenting the Gen 1 API over Gen 2
+internals. Fifteen names are served -- `src.core.Game`,
+`src.world.OverworldController`, `src.world.Map`, `src.world.NPC`,
+`src.world.Collision`, `src.world.WorldAPI`, `src.world.PikachuFollower`,
+`src.world.FieldDefaults`, `src.pokemon.Boxes`, `src.script.ScriptRunner`,
+`src.ui.PartyMenu`, `src.ui.StartMenu`, `src.ui.OptionsMenu`, `src.ui.BoxMenu`
+and `src.battle.BattleState`. `src/mods/Gen2Compat.lua` is the full table and
+publishes what it covers through `Gen2Compat.coverage(name)`, whose members are
+`backed`, `warned` or `absent`. A name with no adapter (`src.script.Commands`,
+`src.ui.OptionRows`) is reported against the mod that required it, and a member
+an adapter cannot back is absent or logs once rather than answering wrongly.
+
+Things no adapter can fix, all mod-side: a hardcoded version allow-list
+(`GameVersion.get() == "red" or ...`) excludes you from Gold by construction;
+Gold's builtin screen ids carry a `Gen2` prefix, so a string match on
+`"BoxMenu"` matches nothing there; a write to a field on a live Gen 2 menu
+instance is inert; and `map.warpAt` is a table on Gen 1 and a method on Gold,
+so indexing it raises. Each has a route that works on both generations, in
+`docs/preparing-your-mod-for-gen2.md`.
+
+Check it statically, then load it headless:
+
+```sh
+python3 tools/modkit.py gen2check mods/my_mod
+```
+
+```lua
+local run = T.sdk.loadMod("mods/my_mod", { generation = 2 })
+T.eq(run.mod and run.mod.state, "loaded",
+  "runs on gen 2: " .. tostring(run.mod and run.mod.skipReason))
+T.eq(#run.errors, 0, "and loads with no boot errors")
+```
+
+Assert the state, not only the error count: a gate skip is deliberately not an
+error, so `#run.errors == 0` passes for a mod that never ran a line.
+
+`gen2check` answers `will load`, `will load but degrade` or `will not work`,
+with a `MK4xx` finding per site and an `unresolved:` note, with a file and a
+line, for every reach a static scan could not follow. Neither substitutes for a
+real Gold boot.
+
+### 5. `mod.card`

 The manifest is the *engine's* contract: identity, load order, dependencies,
 permissions, profile. The card is the *human-facing* one: who made this,
@@ -149,7 +263,7 @@ Two fields deserve their own note:
  distributed mod never carries ROM-derived bytes, not even in its preview
  images.

-### 5. Tags
+### 6. Tags

 Lowercase kebab strings, open vocabulary. The showcase generator
 lowercases and de-dupes. A recommended starting set: `beginner`,
@@ -207,12 +321,15 @@ registry or a new schema field lands with its catalog entry in the same PR
 and the generator runs clean:

 ```sh
-luajit tools/gen_registry_docs.lua                 # in-repo default
-luajit tools/gen_registry_docs.lua ../project.wiki # the wiki checkout
+luajit tools/gen_registry_docs.lua                 # docs/modding/reference/registries.md
+luajit tools/gen_registry_docs.lua ../project.wiki # Reference-Registries.md in a wiki checkout
 ```

-The prose reference lives in the GitHub wiki; the generated pages are
-written into a checkout of it, so they cannot drift from the engine.
+With no argument it writes inside the repo, which is the copy `python3
+tools/modkit.py docs` regenerates and `--out` copies from. Pass a directory
+(or set `POKEPORT_DOCS_DIR`) to write the wiki's flat page name into a wiki
+checkout instead. The prose reference lives in the GitHub wiki; both copies
+come off `src/mods/Schemas.lua`, so neither can drift from the engine.

 ### 5. Deprecation etiquette

@@ -0,0 +1,275 @@
+# Gold port: what is still open after the 2026-08-09 asm parity runs
+
+Two multi-agent runs diffed the Gold port against the `pokegold` disassembly
+(`../pokegold`) and fixed what diverged. Round 1 confirmed 51 defects across 14
+paired clusters; round 2 confirmed 41 more across 13, including one crash. A
+third round (2026-08-10) closed the mod-API boundary: see "The 2026-08-10
+mod-API round" below for what that opened and closed.
+
+Every tier is green at the end of all three: `run_engine` 131/131, `run_tests`
+ALL TESTS PASSED, `run_modkit` 6/6, `run_save_editor_tests` 650/0,
+`run_link_tests` ALL PASSED.
+
+This file records only what is NOT done, so nobody re-derives it. It is a
+working handoff doc in the shape of `KANTO-CONTINUE.md`, not user documentation.
+
+## Do this first or none of it is visible
+
+**Re-import the Gold cache.** Seven fixes live in the extractor and the manifest
+tool, so they do nothing until the ROM is re-imported. This was verified still
+outstanding on 2026-08-10: the default identity's
+`gold/data/generated/menu_gfx.lua` has no `trainerPics` key at all, so a trainer
+battle still opens on the mon rather than the trainer even though the Lua half
+is fixed and correct.
+
+- trainer frontpics (`TrainerPicPointers` walk in `extractMenuGfx`), which is
+  the missing trainer intro image at the start of a trainer battle. The Lua
+  side is now right and re-import is the ONLY thing left: `Trainers.lookup`
+  returns a numeric `class` (36) beside a `classId` (`BUG_CATCHER`), and both
+  `menu_gfx.trainerPics` and `palettes.trainers` are keyed by the constant, so
+  the lookup had to move to `classId`. On a cache that carries the pics the
+  frontpic renders in the class's own palette.
+- egg assets: `battle/front/egg.png` and `menu/egg_hatch.png`, feeding the
+  hatch cutscene and the summary screen's egg page. A fallback landed in the
+  meantime (`ICON_EGG` frame 0, which resolves to a real 16x16 frame), so the
+  egg page draws SOMETHING on a stale cache; `tools/rom_manifest_gold.json`
+  carries `EggPic` at `[20, 31363]` and that stream decompresses to exactly 400
+  bytes (a 5x5-tile pic), so a fresh import takes the real path.
+- the Pokegear phone icon. `_LoadFontsExtra` (`engine/gfx/load_font.asm:8-15`)
+  puts `FontsExtra_SolidBlackAndUpArrowGFX` at `$60`/`$61` and
+  `PokegearPhoneIconGFX` at `$62`, ON TOP of `FontExtra`'s BOLD_A/B/C.
+  `src/import/RomExtractorGen2.lua:342-356` reads `FontExtra` straight in and
+  then blits only `Frames` over `$79-$7E`, so `$62` is still a bold "C" -- which
+  is what the new caller box draws where the telephone glyph belongs. Fix is two
+  files: add the two GFX symbols to `tools/rom_manifest_gold.json`, then blit
+  them at `$60`/`$61`/`$62` in the loop that already handles `Frames`.
+- `PREDEFPAL_UNOWN_PUZZLE = 76`, which is why the Ruins of Alph puzzle rendered
+  grayscale instead of brown
+- the tilemap pad `0x7f -> 0x4f` in `readTilemapRLE` / `readFlatTilemap`
+- held-item icons (`HeldItemIcons` in the manifest, `out.heldItem` in
+  `extractIcons`), which is the held-item marker in the party menu
+- the NPC-trade rows' `item` field, which is what made the Violet City Onix's
+  Bitter Berry print as "83"
+
+## Open: real unknowns, each needs a cache and a driver run
+
+1. **Magnet train renders a blank field.** Pushing `World:magnetTrain` directly
+   shows nothing for 90+ frames (see shot `03-magnet-train.png`). The screen's
+   surround is correct now; what was never investigated is whether
+   `drawBackground` needs setup that the direct push skips. This cannot be
+   settled by reading source.
+
+2. **The NPC that introduces Unown never appears.** Round 1 could not produce a
+   port ref that diverges from the asm, so it is filed `cannot_locate`, not
+   fixed. The cart chain is: solve a chamber puzzle, then
+   `setmapscene RUINS_OF_ALPH_INNER_CHAMBER, SCENE_RUINSOFALPHINNERCHAMBER_STRANGE_PRESENCE`
+   from `maps/RuinsOfAlphKabutoChamber.asm`. Walk that chain live rather than
+   statically: the static read came back clean twice.
+
+3. **Two pic sites still resolve an Unown off the species.**
+   `src/ui/gen2/PhotoStudio.lua:102` and `src/ui/gen2/EvolutionAnim.lua:460` use
+   `def.spriteFront` without going through `Unown.formSprite`. For EvolutionAnim
+   this is almost certainly dead (Unown does not evolve). For PhotoStudio it is
+   genuinely unclear: the cart's `engine/events/print_photo.asm` does not call
+   `GetUnownLetter` at all, so the port may already match. Check before changing.
+
+4. **Unown dex registration on obtain paths.** `engine/pokemon/evolve.asm:310`
+   runs `GetUnownLetter` then `callfar UpdateUnownDex` after
+   `SetSeenAndCaughtMon`, guarded by `cp UNOWN`. That is dex bookkeeping, not
+   rendering, and it was never audited across every path that gives the player a
+   mon. `GetUnownLetter` has 20 call sites on the cart; the port covers the pic
+   ones.
+
+## The 2026-08-10 mod-API round
+
+Six lanes closed the Gen 1 / Gen 2 mod-API boundary and a batch of reported
+gameplay bugs. What that round **closed**, so nobody re-opens it:
+
+- Fifteen seams that had a Gen 2 site but no entry in the parity gate are now
+  listed and asserted: the four `intro.oak_speech.*` events plus the
+  `intro.oak_speech.build` hook, `battle.overlay`,
+  `battle.low_health_alarm`, `battle.catch_exp`, `pokemon.sprite`,
+  `input.step`, `input.pointer`, `render.zones`, `render.compose`,
+  `render.letterbox`, `render.hud`. Five more (`intro.boot.*`) are listed as
+  Gen 2-only. `tests/engine/gate_gen2_mod_api.lua` is 893/893.
+- Two registries un-gated on Gold after their consumer landed:
+  `battle_sprite_scales` (`src/ui/gen2/BattleState.lua:imageScale`) and
+  `render_pipelines` (`src/core/Game2.lua:load` installs
+  `src/render/Pipelines.lua` on the merged dataset after `mods:load`). Both
+  keep the SHARED Gen 1 target, so one mod record serves both games. 40 of the
+  46 registries are now available on Gold.
+- `hook:render.zones` came off the `gate_meta_coverage.lua` DEBT ledger, which
+  is now four entries, all M7/M12 link and give-mon seams.
+
+What that round **left open**, each verified on 2026-08-10:
+
+1. **`render_pipelines`' `drawWorld` half is inert on Gold.** Gold's overworld
+   draws straight to the window rather than into a canvas the way
+   `src/world/OverworldController.lua` hands one to `Pipelines.drawWorld`, so a
+   drawWorld-only pipeline renders nothing. It is not left switched on
+   pretending: `Game2:load` retires a restored level for one and re-applies
+   Tilt from the option the exclusion just cleared, leaving
+   `options.pipelines` untouched so the mode returns the day Gold grows a world
+   canvas. Related: `Pipelines.rows` is read only from
+   `src/ui/OptionsMenu.lua`, so a pipeline on Gold has a hotkey and no OPTION
+   row.
+
+2. **`transitions` stays gated and should.** `src/ui/gen2/BattleTransition.lua`
+   keys `STYLES` as a boolean SET of the four cart wipes (`spin`, `speckle`,
+   `zoom`, `sine`), not the `{ frames, draw, sound, flash }` record the
+   registry carries, and there is no styleDef lookup a mod id could reach --
+   a registered style would fail the membership test and fall back to vanilla.
+   Un-gating it before that changes would be the silent no-op the routing table
+   exists to prevent. Same for `rulesets`, `field`, `text_pointers`,
+   `link_fields` and `map_scripts`; `docs/mod-api-gen2-compat.md` carries the
+   per-registry reason.
+
+3. **`src/core/Game2.lua:joystickremoved` is half of Gen 1's.**
+   `src/core/Game.lua:867` does `self:recoverInput("joystickremoved", joystick)`
+   AND `TouchControls:joystickremoved()`; Game2 does only the pad half, so a
+   controller unplugged mid-hold leaves Gold's Input state stranded and a held
+   direction walks forever. It was a total noop before, so this is not a
+   regression -- it is a seam finished halfway. One line.
+
+4. **`Game2` noops five joystick callbacks.** `joystickpressed`,
+   `joystickreleased`, `joystickaxis`, `joystickhat` and `joystickadded` are
+   assigned `noop`, so a stick with no SDL game-controller-database entry
+   reaches neither Input nor `GamepadMap.RAW_BUTTON_BINDINGS` on Gold. Gen 1
+   handles all four (`src/core/Game.lua:764-797`). A DualSense is
+   SDL-recognized and takes the gamepad path, so this is not the reported
+   SELECT bug -- it is the raw-stick fallback.
+
+5. **`Game2:gamepadpressed` has no SELECT-held guard.** Gen 1
+   (`src/core/Game.lua:686-694`) suppresses the shoulder GAME SPEED cycle while
+   SELECT is held, because Select+L is a display chord on NX. Harmless today
+   (Gold has no display chord) but the two paths have diverged.
+
+6. **`hideCallerBox`'s fallback path skips the screen seams.**
+   `src/script/gen2/CallAsm.lua:217-231` pops through `stack:pop` when the
+   caller box is top (which it always is on a normal call, since `PhoneRing`
+   runs `closetext` before `InitCallReceiveDelay`) but falls back to a bare
+   `table.remove(states, index)` otherwise, which raises neither `exit` nor
+   `screen.popped`. Only a mod screen pushed over the box can reach it, and
+   then a listener that saw `screen.pushed` never sees the pop.
+
+7. **`src/core/gen2/Roamers.lua:338` says the wrong thing.** Its comment says
+   "the shared `encounter.species` hook still runs downstream and is where a
+   mod changes what appears". It does not: `World:tryWildEncounter` calls
+   `startBattle` on a roamer hit and RETURNS before it reaches
+   `World:rollEncounter`. The doc's partial-coverage list is right and the
+   comment is wrong; correct the comment, not the doc.
+
+8. **`src/world/gen2/World.lua:4318` still calls the pack's SEL row something
+   "this port has not built".** The pack submenu now offers SEL. Stale comment.
+
+Three partial coverages that are documented and still true, repeated here
+because "the hook exists" is not "the hook sees everything":
+`encounter.roll` / `encounter.species` are not wired into `World:tryHeadbutt`,
+`World:rockMonEncounter` or the roamer path; `src/ui/gen2/BattleState.lua`
+builds a flat `opts` for `Catching.attempt` with no `data` in it, so a
+mod-registered ball is readable through `Catching.recordFor` but is not
+resolved at the real throw site; and no Gen 2 UI file reads
+`Battle.statusRecordFor(data, status).hudLabel`, so a mod status shows no label
+in the battle HUD, the party menu or the summary page.
+
+## Open: cleanups declined on purpose
+
+These were skipped with reasons during the wiring pass. They are listed so the
+reasons survive, not because they are pending work.
+
+1. **`Vm:showRaw(body, stay)`** was proposed and declined. `showRawHeld` in
+   `Specials.lua` already answers the text lookahead correctly, so this trades
+   one working shape for another.
+
+2. **`tests/drivers/gold_egg_hatch.lua` summary push** was declined as
+   redundant: `gold_egg_hatch_shots.lua` already photographs both the cutscene
+   and the summary page.
+
+3. **Two `Battle.lua` divergences** were filed as notes by the file's own owner
+   rather than fixed, because no reported symptom drives either: text printed
+   for an already-statused target, and Future Sight taking STAB, type
+   effectiveness and weather. Both are real divergences from the cart. Fix them
+   when something actually depends on them.
+
+## Reported, investigated, and NOT defects: do not re-chase these
+
+Each of these came in as a bug report and came back disproved against the asm.
+Re-opening one costs another full investigation, so the reasoning is kept here.
+
+- **SFX pointer table misalignment.** The table is aligned end to end. 188 `dba`
+  rows with no skips or padding, 188 constants, verified through the manifest
+  scraper, the extractor's `*3` stride, and 8 ids spot-checked against the live
+  cache. Two things that look like misalignment are how the cart is built:
+  `SFX_GET_EGG_UNUSED` and `SFX_GET_EGG` both point at `Sfx_GetEgg`, and
+  `Sfx_ReadText` / `Sfx_ReadText2` share one header address. **Do not repoint,
+  re-stride, or add an offset to the SFX, music, or cry tables.**
+
+- **Bind letting you pick other moves.** This is Gen 1 behavior and does not
+  hold for Gen 2. `BattleCommand_TrapTarget` (`effect_commands.asm:5568-5605`)
+  writes only the TARGET's wrap count and trapping move. It touches nothing on
+  the user, so the user is free to switch moves. The port is correct. The real
+  Gen 2 move locks (Rollout, Thrash, Petal Dance) were genuinely missing and
+  have been added.
+
+- **The Slowpoke Tail salesman not blocking progression.** He is Route 32's
+  `FISHER4` at (7,70), not an Azalea Town object, and the cart's refusal arm
+  only prints. `_OfferToSellSlowpokeTail` runs `setscene SCENE_ROUTE32_NOOP`
+  first, so the coord event never fires again. There is no pushback to port.
+
+- **The rival being named BLUE.** Not reproducible. The whole chain is intact:
+  special 36 resolves to `H.NameRival`, `NamingScreen:accept` hands the typed
+  string through, and BLUE is the Gen 1 default that Gold never reaches. A
+  separate real defect on this seam (the rival being pre-named SILVER before the
+  officer asks, and the blank-entry fallback) was found and fixed.
+
+- **Not Very Effective dealing 0 damage**, **status not shown in the battle
+  UI**, and **the Pokedex missing from the Start Menu** all came back
+  `already_fixed`: the damage floor is `MIN_DAMAGE` added after the cap and
+  before the type multiply, the HUD prints the status tag where the level goes,
+  and the menu row is gated on `save.engineFlags[11]` correctly.
+
+## Standing risks, not breakage
+
+- **Four Gold test files are wired into no runner**, so a regression in them
+  will not turn `run_tests.lua` red: `gold_flag_names_test`,
+  `gold_route_validate_test`, `gen2_pokegear_unlock_test`,
+  `gen2_save_export_test`. All four pass standalone. The first two are the
+  pre-run route validators documented in `KANTO-CONTINUE.md`; the last two need
+  a `GOLD_CACHE` and are excluded by an in-file comment. This is deliberate, but
+  it is a coverage hole and worth knowing.
+
+- **`mods/` must stay clean.** The 2026-08-10 round left temporary probe mods
+  behind mid-run (`mods/tmp_menus`, `mods/zz_verify_seams`); both are gone now
+  and `mods/` holds only `example_mew_starter`, `example_silly_oak`, `examples`
+  and `nuzlocke`. A stray `mods/tmp_*` loads on every Gold boot and changes what
+  a driver measures. `mods/example_silly_oak` carries only a `.modkitignore` and
+  warns "manifest.json does not exist" on every boot; that is pre-existing
+  (27 Jul) and unrelated.
+
+- **`tests/drivers/gold_opaque_surround.lua` is stale.** It reads
+  `game.stack._items`; `src/core/StateStack.lua` has only `.states`. That branch
+  is covered instead by `gold_center_pc` and the letterbox-per-frame count in
+  `gold_frame_seams`.
+
+- **`luac` on this machine is Lua 5.5**, so `luac -p` is a weak proxy for the
+  LuaJIT/5.1 semantics this engine targets. Use `luajit -b <file> /dev/null` for
+  a real syntax gate.
+
+- **`docs/rfcs/0001-surfing-pikachu-sprite.md` and `0002-screen-render-visible.md`
+  are deleted** in the working tree, and both are still referenced by name from
+  live modkit case files that pass. Those deletions predate both parity runs.
+  Worth resolving before a commit.
+
+## The failure mode that actually bit, worth remembering
+
+Round 1 reported the Yes/No dialogue fix as landed. It was not. Two of its three
+lanes wrote their half, and the third left the hook closure at
+`World.lua:828` declared as `function(body, onDone)`, so the third argument
+`Vm:resume` passes was silently discarded and the entire `stay` implementation
+in `World:showText` and `World:askYesNo` was dead code. Lua drops extra
+arguments without complaint, so nothing failed and every suite stayed green.
+
+Round 2 caught it only because an investigator probed the boundary empirically
+instead of reading both sides and assuming they met. When work is split across
+agents by file, **the seams between the files are where the bugs live**, and a
+green suite does not prove a seam is connected.
@@ -0,0 +1,7 @@
+Copyright 2026 BOIS CLUB GAMES, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -1,49 +1,188 @@
-# Pokemon Gen 1 Recompilation Project
+# Gen1Recomp

-A native LÖVE2D recreation of Pokemon Red. The engine and map behavior are
-hand-written Lua; game data and graphics are decoded from a ROM supplied by
-the player.
+A native LÖVE2D recreation of Poke Red, Blue and Yellow. The engine and map
+behavior are hand-written Lua; game data and graphics are decoded from a ROM
+supplied by the player.
+
+> [!CAUTION]
+> **We are NOT affiliated with the website `gen1recomp[.]com`** That website is not run by this project, was not authorized by us, and we have no idea who operates it. It is impersonating this project; do not download anything from it, and treat anything it hosts or claims as untrustworthy. Even if the site currently links back to this repository, the people behind it can change its content at any time, so nothing on it should ever be trusted. This GitHub repository and the Discord linked below are the only official sources for this project.
+
+<p align="center"><img src="https://raw.githubusercontent.com/bryanthaboi/gen1recomp/refs/heads/dev/assets/logo/logo.png"></p>
+
+**SUPPORT / ANNOUNCEMENTS / MODS:** [Discord](https://bois.icu)
+
+<p align="center">
+
+<a href="https://www.youtube.com/@bryanthaboi">
+  <img src="https://img.shields.io/badge/YouTube-FF0000?style=for-the-badge&logo=youtube&logoColor=white" alt="YouTube">
+</a>
+<a href="https://www.tiktok.com/@bryanthaboi">
+  <img src="https://img.shields.io/badge/TikTok-000000?style=for-the-badge&logo=tiktok&logoColor=white" alt="TikTok">
+</a>
+<a href="https://x.com/bryanthaboi">
+  <img src="https://img.shields.io/badge/X-000000?style=for-the-badge&logo=x&logoColor=white" alt="X">
+</a>
+<a href="https://bsky.app/profile/bryanthaboi.live">
+  <img src="https://img.shields.io/badge/Bluesky-0285FF?style=for-the-badge&logo=bluesky&logoColor=white" alt="Bluesky">
+</a>
+<a href="https://www.instagram.com/bryanthaboi">
+  <img src="https://img.shields.io/badge/Instagram-E4405F?style=for-the-badge&logo=instagram&logoColor=white" alt="Instagram">
+</a>
+
+</p>
+
+
+<p align="center"> <a href="https://www.polygon.com/pokemon-red-blue-3d-voxel-mod-battle-pixels-gameplay-footage-remake/"> <img src="https://img.shields.io/badge/AS%20SEEN%20ON-POLYGON-ea2e49?style=for-the-badge" alt="As seen on Polygon"> </a> 
+<a href="https://kotaku.com/pokemon-red-blue-recompilation-project-voxel-3d-mod-2000720281"> <img src="https://img.shields.io/badge/AS%20SEEN%20ON-KOTAKU-ea2e49?style=for-the-badge" alt="As seen on KOTAKU"> </a> 
+
+  <a href="https://www.digitalfoundry.net/news/2026/07/pokemon-yellow-voxel-mod-turns-the-original-gameboy-code-into-a-stunning-world">
+    <img src="https://img.shields.io/badge/AS%20SEEN%20ON-DIGITAL%20FOUNDRY-ea2e49?style=for-the-badge" alt="As seen on Digital Foundry">
+  </a>
+  <a href="https://www.androidauthority.com/unofficial-android-port-pokemon-red-blue-yellow-3692724/">
+  <img src="https://img.shields.io/badge/AS%20SEEN%20ON-ANDROID%20AUTHORITY-ea2e49?style=for-the-badge" alt="As seen on Android Authority">
+</a>
+
+<a href="https://www.xda-developers.com/this-amazing-pokemon-red-and-blue-voxel-mod-adds-a-3d-perspective-without-an-emulator/">
+  <img src="https://img.shields.io/badge/AS%20SEEN%20ON-XDA%20DEVELOPERS-ea2e49?style=for-the-badge" alt="As seen on XDA Developers">
+</a>
+</p>
+
+### Watch the latest update video
+
+[![Watch the latest update video](https://img.youtube.com/vi/8IOgqbe4YvA/maxresdefault.jpg)](https://www.youtube.com/watch?v=8IOgqbe4YvA)

-SUPPORT AND ANNOUNCEMENTS: [Discord](https://bois.icu)

 This project does not include a ROM, emulate the Game Boy, transpile assembly,
-or download a disassembly. A canonical US Pokemon Red ROM is the only game
-content input.
+or download a disassembly. A canonical US Poke Red, Blue, Yellow, or Gold ROM
+is the only game content input.

 The ROM is verified, used during import, and then released from memory. It is
 not copied into the cache. Later launches load the private generated cache and
-do not ask for the ROM again.
+do not ask for the ROM again. Red, Blue, Yellow, and Gold can all be imported
+side by side. Gold is Gen 2 Phase 1 (import + launcher; see
+`docs/gold-phase1.md`): the Gen 2 engine is still under construction.

 ## Quick Start

-Open the desktop app. On first boot, choose your legally obtained `.gb` file
-or drop it onto the window. Import takes a few seconds and the game starts
-automatically.
+Open the desktop app. On first boot, choose your legally obtained `.gb` /
+`.gbc` file or drop it onto the window. Import takes a few seconds and the
+game starts automatically.
+
+Only the canonical US Red, Blue, Yellow (1 MiB), and Gold (2 MiB) ROMs are
+accepted. The importer verifies SHA-1 before creating any game data:
+
+- Red: `ea9bcae617fdf159b045185467ae58b2e4a48b9a`
+- Blue: `d7037c83e1ae5b39bde3c30787637ba1d4c48ce2`
+- Yellow: `cc7d03262ebfaf2f06772c1a480c7d9d5f4a38e1`
+- Gold: `d8b8a3600a465308c9953dfa04f0081c05bdcb94`

-Only the canonical 1 MiB US Red ROM is accepted. The importer verifies SHA-1
-`ea9bcae617fdf159b045185467ae58b2e4a48b9a` before creating any game data.
 The packaged app contains neither a ROM nor pre-extracted game data. Music,
 sound effects, and cries are synthesized while the game runs from compact
 audio channel programs copied out of the verified ROM.

+### A note on Windows Defender warnings
+
+Windows Defender sometimes flags the Windows build with a generic
+machine-learning detection such as `Trojan:Win32/Wacatac!ml` (#621). This is
+a known false positive: the exe is the official LÖVE runtime with the game
+archive appended (the standard way LÖVE games ship), and Defender's
+heuristics distrust unsigned executables with appended data. Every release
+publishes SHA-256 checksums (`sha256sums.txt`) so you can verify your
+download, and you can confirm a flagged file yourself on
+[VirusTotal](https://www.virustotal.com), where these builds come back clean
+on every engine except Defender's heuristic. False positives are reported to
+Microsoft as they come up.
+
 ## Controls

-arrow keys or WASD move; Z, Enter, or Space is A; X or Backspace is
-B; Escape opens START. F1 saves and F2 loads. Controllers are supported.
+
+| Action | Keyboard          | Controller         |
+| ------ | ----------------- | ------------------ |
+| Move   | Arrow keys / WASD | D-pad / left stick |
+| A      | Z / Enter / Space | A                  |
+| B      | X / Backspace     | B                  |
+| Start  | Escape            | Start              |
+| Select | Tab / Shift       | Back / Select      |
+
+
+Rebind any of these in-game under **OPTIONS → CONTROLS**. Controllers are
+supported out of the box.
+
+### Hotkeys
+
+
+| Key       | What it does                                         |
+| --------- | ---------------------------------------------------- |
+| `-` / `=` | Zoom out / in (overworld; also mouse wheel)          |
+| `1`       | Cycle GAME SPEED up (controller: R2 faster, L2 slower) |
+| `2`       | Cycle COLORS                                         |
+| `3`       | Cycle TILT (free-roam overworld)                     |
+| `4`       | Cycle ZOOM through every level (free-roam overworld) |
+| `5`       | Cycle GBC FX                                         |
+| `F1`      | Save                                                 |
+| `F2`      | Load                                                 |
+| `F10`     | Open / close the mod manager                         |
+
+
+COLORS, TILT, ZOOM, GBC FX, GAME SPEED, and VOID FILL are also in the
+Options menu and persist in `options.lua`.
+
+### Low-end devices
+
+**OPTIONS → PERFORMANCE** scales the port's optional extras for weaker
+hardware: **HIGH** (everything on), **BALANCED** (no 3D tilt or GBC FX),
+**LOW** (also no survey zoom, FPS capped), or **AUTO** — the default, which
+picks a tier from your device (ARM handhelds → LOW, phones → BALANCED,
+normal desktops → HIGH, unchanged). It only scales presentation; the
+fixed-step game logic is identical on every tier, and a lower tier hides
+your tilt/zoom/GBC-FX preferences without forgetting them. Details in
+[docs/new-features.md](docs/new-features.md#performance-tier-low-end-devices).
+
+### Rulesets
+
+**OPTIONS → RULESET** picks which set of Gen 1 battle behaviors to run.
+Both rulesets share the same damage formulas; they differ only in whether
+the original's quirks are kept. The setting persists in `options.lua`, and
+mods can register their own.
+
+`gen1_faithful` is the default and reproduces the original cartridge,
+famous bugs included:
+
+| Rule                        | Behavior                                              |
+| --------------------------- | ----------------------------------------------------- |
+| `oneIn256Miss`              | A 100%-accurate move still misses on a roll of 255     |
+| `critUsesBaseSpeed`         | Crit rate reads base speed, not the current stat       |
+| `critIgnoresStages`         | Crit rate ignores stat stages                          |
+| `focusEnergyBug`            | FOCUS ENERGY quarters the crit rate instead of x4      |
+| `enemyUnlimitedPP`          | Enemies never spend PP, so they never Struggle         |
+| `hyperBeamSkipRechargeOnKO` | HYPER BEAM skips its recharge when the target faints   |
+| `randMin` / `randMax`       | Damage random factor 217-255                           |
+
+`modern_clean` keeps the formulas but removes the notorious quirks:
+
+| Rule                        | Behavior                                              |
+| --------------------------- | ----------------------------------------------------- |
+| `oneIn256Miss`              | Off: a 100%-accurate move always hits                  |
+| `critUsesBaseSpeed`         | Unchanged: crit rate still reads base speed            |
+| `critIgnoresStages`         | Off: stat stages count toward the crit rate            |
+| `focusEnergyBug`            | Off: FOCUS ENERGY raises the crit rate as intended     |
+| `enemyUnlimitedPP`          | Off: enemies deplete PP and Struggle when empty        |
+| `hyperBeamSkipRechargeOnKO` | Off: HYPER BEAM always recharges, like Gen 2+          |
+| `randMin` / `randMax`       | Damage random factor 217-255, same as faithful         |

 ## Running From Source

-Requires LÖVE 11.x. Place the ROM in the project folder and double-click
-`Play-Mac.command` or `Play-Windows.bat`, or run:
+Requires LÖVE 11.x. Place a Red, Blue, or Yellow ROM in the project folder and
+double-click `Play-Mac.command` or `Play-Windows.bat`, or run:

 ```sh
-scripts/setup.sh --rom "/path/to/Pokemon Red.gb"
+scripts/setup.sh --rom "/path/to/Poke Red.gb"   # or Blue.gb / Yellow.gbc
 scripts/run.sh
 ```

 then `love .` for later launches. Windows PowerShell scripts, the optional
 developer data build, test suites, and cache management are covered in
-[Developer Setup](https://github.com/bryanthaboi/pokemon-gen1-recomp-project/wiki/Guide-Developer-Setup).
+[Developer Setup](https://github.com/bryanthaboi/gen1recomp/wiki/Guide-Developer-Setup).

 ## Portable Mode

@@ -51,7 +190,7 @@ By default the game keeps your save, options, and the private ROM-derived
 data cache in your OS's normal per-user app data folder. To keep everything
 next to the game instead (handy for a USB stick or portable drive you carry
 between computers), drop an empty file named `portable.txt` next to the app
-(next to `PokemonRed.app`/`.exe`, or next to `main.lua`/`conf.lua` when
+(next to `gen1recomp.app`/`.exe`, or next to `main.lua`/`conf.lua` when
 running from source), then launch the game. Portable mode is desktop-only
 (Windows, Linux, macOS); it has no effect on Android or iOS, where the app
 runs from a read-only package.
@@ -59,14 +198,120 @@ runs from a read-only package.
 With `portable.txt` present:

 - `save.lua`, `save.lua.bak`, and `options.lua` are read from and written to
-  that same folder instead of the OS save directory.
+that same folder instead of the OS save directory.
 - A ROM import writes the generated `data/generated` and `assets/generated`
-  cache straight into that folder too (nothing is left in the OS save
-  directory), so a later launch reuses it without asking for the ROM again
-  even on a different computer, as long as the same folder comes along.
+cache straight into that folder too (nothing is left in the OS save
+directory), so a later launch reuses it without asking for the ROM again
+even on a different computer, as long as the same folder comes along.
 - Deleting `portable.txt` switches back to the normal OS save directory; nothing
-  already written to either location is touched automatically, so copy files
-  over yourself if you want to carry existing progress across the switch.
+already written to either location is touched automatically, so copy files
+over yourself if you want to carry existing progress across the switch.
+
+## Launch Options
+
+By default the app opens the launcher so you can pick a game. Launch options
+skip it and start one game directly, which is what you want for a one-click
+entry: a desktop shortcut per game, a Steam entry, or a handheld frontend.
+
+| Option | Effect |
+| --- | --- |
+| `--game=red` | boot Red, skipping the launcher (`blue` and `yellow` too, or just `r` / `b` / `y`) |
+| `--slot=2` | load that save slot; takes a slot number or a slot id |
+| `--launcher` | open the launcher anyway, so you can edit a shortcut you already made |
+
+
+## Linux on arm64 (Raspberry Pi)
+
+Alongside the x86_64 `gen1recomp-*-linux.zip`, every release ships
+`gen1recomp-*-linux-arm64.AppImage` for 64-bit ARM desktop Linux — Raspberry
+Pi 4/5, Armbian and other SBC distros, and arm64 VMs on Apple Silicon:
+
+```sh
+chmod +x gen1recomp-*-linux-arm64.AppImage
+./gen1recomp-*-linux-arm64.AppImage
+```
+
+LÖVE publishes no aarch64 binary of any kind, so this artifact compiles the
+engine — and SDL2, OpenAL and the codecs — from source inside a Debian
+bullseye arm64 container. It needs only glibc 2.29+, libstdc++, freetype and
+zlib on the host; OpenGL, X11, Wayland, KMSDRM, ALSA and PulseAudio are all
+dlopened, so the same image runs on a full desktop, a Wayland-only session or
+a KMSDRM handheld with no X server. Build instructions and the reasoning are
+in [docs/linux-arm64-build.md](docs/linux-arm64-build.md).
+
+
+## iOS
+
+Every release ships `gen1recomp-*-ios.ipa`. Sideload it with AltStore
+(Windows or Mac) — see [docs/ios-sideload.md](docs/ios-sideload.md). To
+build and install from source on a Mac instead, see
+[docs/ios-install.md](docs/ios-install.md).
+
+<div>
+    <a href="https://intradeus.github.io/http-protocol-redirector?r=sidestore://source?url=https://github.com/bryanthaboi/gen1recomp/raw/refs/heads/main/mobile/ios/app-repo.json"><img src="./.github/resources/sidestore-badge.png" alt="Add to SideStore" height="60"></a>
+    &nbsp;
+    <a href="https://intradeus.github.io/http-protocol-redirector?r=feather://source/https://github.com/bryanthaboi/gen1recomp/raw/refs/heads/main/mobile/ios/app-repo.json"><img src="./.github/resources/feather-badge.png" alt="Add to Feather" height="60"></a>
+    &nbsp;
+    <a href="https://intradeus.github.io/http-protocol-redirector?r=altstore://source?url=https://github.com/bryanthaboi/gen1recomp/raw/refs/heads/main/mobile/ios/app-repo.json"><img src="./.github/resources/altstore-badge.png" alt="Add to AltStore" height="60"></a>
+    &nbsp;
+    <a href="https://github.com/bryanthaboi/gen1recomp/releases/latest"><img src="./.github/resources/github-badge.png" alt="Download from GitHub" height="60"></a>
+</div>
+
+## Xbox Dev Mode
+
+Every release ships `gen1recomp-*-xbox-uwp.zip` for Xbox One and Xbox Series
+consoles in Developer Mode. It cannot be installed in retail mode.
+
+Extract the archive, then use Xbox Device Portal to install the `.msix` and
+the x64 package under `Dependencies`.
+
+### External setup
+
+1. Put your legally obtained Red, Blue, or Yellow ROMs on an external drive.
+   Mod ZIPs can go on the same drive.
+2. Connect the drive to the Xbox and open Gen1Recomp.
+3. Select **Import ROM** or **Import Mod**, then choose the file with the Xbox
+   file picker.
+4. Repeat the ROM import for each version you want to use.
+
+### Internal setup
+
+1. Create a folder named `baseroms` on your PC and place your legally obtained
+   Red, Blue, or Yellow ROMs inside it.
+2. ZIP the folder, keeping `baseroms` at the top level of the archive.
+3. Launch Gen1Recomp once, then close it.
+4. Open Xbox Device Portal and upload the ZIP to
+   `Gen1Recomp/LocalState/pokemon-love2d/`.
+5. Choose **Yes** when Device Portal asks whether to extract the archive.
+6. Open Gen1Recomp. The launcher checks baseroms once at startup. When it finds a compatible ROM, that game’s tab shows ROM FOUND and an Import detected ROM button.
+
+ROMs, generated game data, saves, and mods remain in LocalState and are not
+included in the app.
+
+Source builds and package details are covered in
+[the Xbox UWP build notes](ports/uwp/BUILD.md).
+
+## Handhelds
+
+A PortMaster-style port for the **Anbernic RG34XXSP** on Stock OS 64-bit MOD
+ships with every release as `gen1recomp-*-rg34xxsp-stockos64-mod.zip`.
+Install steps, controls, and troubleshooting live in
+[docs/anbernic-rg34xxsp.md](docs/anbernic-rg34xxsp.md).
+
+## Nintendo Switch
+
+Releases ship an SD-ready `gen1recomp-*-switch.zip`. Runtime target is pinned
+[love-nx](https://github.com/retronx-team/love-nx) `11.5-nx1`. Requires a
+console that can run Switch homebrew.
+
+- Players: [docs/switch-install.md](docs/switch-install.md). Download the
+  zip, extract at the microSD root (install or update), title-override
+  launch, import your own legal ROM, Joy-Con controls and shortcuts.
+- Builders: [docs/switch-build.md](docs/switch-build.md). `--fetch` /
+  `--loose` / `--fused`, toolchain, Docker fallback, and CI vs release
+  (path-gated ubuntu selftest, fused PR artifact on the main repo, release
+  hard-fail).
+- File transfer (MTP / SD / FTP): [docs/switch-transfer.md](docs/switch-transfer.md).

 ## Modding

@@ -74,33 +319,40 @@ The game ships a native mod platform: content registries, events and hooks,
 per-mod saves and options, and an in-game manager. The full modding book —
 getting started, a twelve-rung tutorial ladder, a cookbook, and the generated
 reference — lives on the
-[project wiki](https://github.com/bryanthaboi/pokemon-gen1-recomp-project/wiki).
+[project wiki](https://github.com/bryanthaboi/gen1recomp/wiki).

-Shipped example mods, one per kind of author, live in [`mods/`](mods/).
+Shipped example mods, one per kind of author, live in `[mods/](mods/)`.
+
+Maps can be edited in our own build of [Tiled](https://www.mapeditor.org),
+[bryanthaboi/tiled_gen1recomp](https://github.com/bryanthaboi/tiled_gen1recomp/releases),
+and exported back out as a mod; see
+[docs/tiled-map-editing.md](docs/tiled-map-editing.md).

 ## Bugs and Ideas

 Found a bug? A warp dropping you somewhere it shouldn't, a battle doing math
 that looks wrong, text in the wrong box, anything that does not match the
 original game.
-[Open a bug report](https://github.com/bryanthaboi/pokemon-gen1-recomp-project/issues/new?template=bug_report.yml).
+[Open a bug report](https://github.com/bryanthaboi/gen1recomp/issues/new?template=bug_report.yml).
 Attach a screenshot if you can. It saves a lot of back and forth, and if you
 can't get one, the form asks you to describe what you saw instead.

 Thought of a feature that could be good, or a way to improve one that already
 exists?
-[Open a feature request](https://github.com/bryanthaboi/pokemon-gen1-recomp-project/issues/new?template=feature_request.yml).
+[Open a feature request](https://github.com/bryanthaboi/gen1recomp/issues/new?template=feature_request.yml).
 Say what you want, why it is worth doing, and how you picture it working. A
 request with real detail is one that can actually get built.

 ## More

- [Link play](https://github.com/bryanthaboi/pokemon-gen1-recomp-project/wiki/Guide-Link-Play)
-  — START > LINK connects two copies directly over UDP.
- [Save editor](https://github.com/bryanthaboi/pokemon-gen1-recomp-project/wiki/Guide-Save-Editor)
-  — edit party, boxes, items, events, and Pokédex flags outside the game.
+- [Link play](https://github.com/bryanthaboi/gen1recomp/wiki/Guide-Link-Play)
+— START > LINK connects two copies directly over UDP.
+- [Save editor](https://github.com/bryanthaboi/gen1recomp/wiki/Guide-Save-Editor)
+— edit party, boxes, items, events, and Pokédex flags outside the game.
 - `docs/architecture.md` — runtime details;
-  `docs/behavior-porting-notes.md` — formula provenance.
+`docs/behavior-porting-notes.md` — formula provenance.
+
+

 ## Special Thanks

@@ -108,6 +360,4 @@ This project would not be possible without [pret](https://github.com/pret) >
 the pret band of decompiling maniacs > and their
 [pokered](https://github.com/pret/pokered) disassembly.

-## Wanna Support My Work?
-[![Buy Me a Coffee](https://img.shields.io/badge/Buy_Me_a_Coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/bryanthaboi)
-
+<p align="center"><a href="https://boisclub.games"><img src="https://raw.githubusercontent.com/bryanthaboi/gen1recomp/refs/heads/dev/assets/logo/bcg.png"></a></p>
@@ -0,0 +1,13 @@
+# Plain Pixel font
+
+"Plain Pixel Font" by Douglas Vautour (Burpy Fresh) is licensed under
+CC-BY 4.0: https://burpyfresh.itch.io
+
+Version 0.009 (CJK character additions), unmodified. Characters for most
+languages have a 5x11 base but can extend vertically; double-width
+characters such as Hiragana and Katakana are 11x11.
+
+Bundled so a translation mod can opt into TTF text rendering
+(`mod.content.font:register("ttf", {})`; see the Translation support
+section of docs/new-features.md) instead of drawing hundreds of glyph-page
+tiles. The tile font extracted from the player's ROM stays the default.
@@ -0,0 +1,9 @@
+# On-screen touch control art
+
+From Xelu's "Free Controller & Keyboard Prompts" pack (Nicolae Berbece /
+Those Awesome Guys), public domain under CC0:
+https://thoseawesomeguys.com/prompts/
+
+256px Nintendo Switch set, renamed for src/core/TouchControls.lua:
+d-pad (neutral + per-direction highlight), A, B, plus (START) and
+minus (SELECT).
@@ -0,0 +1,366 @@
+#!/usr/bin/env bash
+# Build a PortMaster aarch64 port of gen1recomp for Linux ARM SBC handhelds.
+# The package uses PortMaster control hooks and a self-contained LÖVE runtime,
+# while keeping paths relative to the launcher for broad CFW compatibility.
+#
+# The launcher uses SHDIR-relative paths and bundles the LÖVE 11.5 aarch64
+# runtime so the device does not need a separate runtime download on first launch.
+#
+# Usage:
+#   ./build-linux-arm-sbc.sh [--version X.Y.Z]
+#   GEN1RECOMP_SOURCE_DIR="$PWD" ./build-linux-arm-sbc.sh --version X.Y.Z
+#   ./build-linux-arm-sbc.sh --source /path/to/gen1recomp --version X.Y.Z
+#
+# Output:
+#   dist/linux-arm-sbc/gen1recomp-sbc-portmaster.zip
+#
+# Install on device:
+#   1. Install PortMaster for the handheld firmware.
+#   2. Unzip into the device's PortMaster ports folder so you have:
+#        Roms/Ports (PORTS)/gen1recomp-sbc.sh
+#        Roms/Ports (PORTS)/gen1recomp-sbc/...
+#   3. Copy a legal US Red or Blue .gb into Roms/Ports (PORTS)/gen1recomp-sbc/lovegame/
+#   4. Launch "gen1recomp-sbc" from the Ports list; press Choose ROM (scans that
+#      folder when zenity is missing).
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")" && pwd)"
+HERE="$ROOT/.bazinga"
+CACHE="$HERE/cache/linux-arm-sbc"
+WORK="$HERE/work/linux-arm-sbc"
+DIST="$ROOT/dist/linux-arm-sbc"
+
+APP_NAME="gen1recomp-sbc"
+# Artifact suffix identifies this as the generic PortMaster SBC package.
+# Release uploads stage it as gen1recomp-<ver>-sbc-portmaster.zip.
+ARTIFACT_SUFFIX="portmaster"
+PORT_DIR_NAME="gen1recomp-sbc"
+LAUNCHER_NAME="gen1recomp-sbc.sh"
+LOVE_VERSION="11.5"
+# By default the pack is reproducible from the latest published GitHub release,
+# not whatever happens to be in the caller's checkout.  Development builds can
+# point this at a local checkout with GEN1RECOMP_SOURCE_DIR=/path/to/repo.
+SOURCE_DIR_OVERRIDE="${GEN1RECOMP_SOURCE_DIR:-}"
+SOURCE_TAG_OVERRIDE="${GEN1RECOMP_RELEASE_TAG:-}"
+VERSION="${GEN1RECOMP_VERSION:-}"
+
+# Official PortMaster LÖVE 11.5 aarch64 runtime (small love stub + liblove).
+PM_RUNTIME_BASE="https://raw.githubusercontent.com/PortsMaster/PortMaster-GUI/main/PortMaster/runtimes/love_${LOVE_VERSION}"
+RELEASES_LATEST_URL="https://github.com/bryanthaboi/gen1recomp/releases/latest"
+RELEASE_TARBALL_BASE="https://github.com/bryanthaboi/gen1recomp/archive/refs/tags"
+
+say()  { printf '\033[1;32m==>\033[0m %s\n' "$*"; }
+warn() { printf '\033[1;33mwarn:\033[0m %s\n' "$*" >&2; }
+fail() { printf '\033[1;31merror:\033[0m %s\n' "$*" >&2; exit 1; }
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --version) [ $# -ge 2 ] || fail "--version needs X.Y.Z"; VERSION="$2"; shift ;;
+    --source) [ $# -ge 2 ] || fail "--source needs a directory"; SOURCE_DIR_OVERRIDE="$2"; shift ;;
+    --release-tag) [ $# -ge 2 ] || fail "--release-tag needs a tag"; SOURCE_TAG_OVERRIDE="$2"; shift ;;
+    -h|--help)
+      sed -n '2,24p' "$0"
+      exit 0
+      ;;
+    *) fail "unknown argument: $1" ;;
+  esac
+  shift
+done
+
+command -v curl >/dev/null || fail "curl is required"
+command -v zip  >/dev/null || fail "zip is required"
+command -v unzip >/dev/null || fail "unzip is required"
+command -v tar  >/dev/null || fail "tar is required"
+
+mkdir -p "$CACHE" "$WORK" "$DIST"
+
+download() {
+  local url="$1" dest="$2"
+  if [ -f "$dest" ] && [ -s "$dest" ]; then
+    return 0
+  fi
+  say "downloading $(basename "$dest")"
+  curl -fL --progress-bar "$url" -o "$dest.tmp" \
+    || fail "download failed: $url"
+  mv "$dest.tmp" "$dest"
+}
+
+# --------------------------------------------------------------- source + game tree
+# Release builds use the latest published source archive. A local checkout is
+# an explicit override for development and for CI's just-built release source.
+if [ -n "$SOURCE_DIR_OVERRIDE" ]; then
+  SOURCE_DIR_OVERRIDE="$(cd "$SOURCE_DIR_OVERRIDE" 2>/dev/null && pwd)" \
+    || fail "source directory does not exist: $SOURCE_DIR_OVERRIDE"
+  SOURCE_DIR="$SOURCE_DIR_OVERRIDE"
+  SOURCE_TAG="${SOURCE_TAG_OVERRIDE:-local}"
+  if [ "$SOURCE_TAG" != "local" ]; then
+    printf '%s' "$SOURCE_TAG" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+$' \
+      || fail "release tag must look like vX.Y.Z: $SOURCE_TAG"
+  fi
+  if [ -z "$VERSION" ]; then
+    VERSION="$(git -C "$SOURCE_DIR" rev-parse --short HEAD 2>/dev/null || echo dev)"
+  fi
+else
+  if [ -z "$SOURCE_TAG_OVERRIDE" ]; then
+    latest_location="$(curl -fsSI "$RELEASES_LATEST_URL" \
+      | awk 'tolower($1) == "location:" { print $2 }' | tail -1 | tr -d '\r')" \
+      || fail "could not resolve latest published release"
+    SOURCE_TAG_OVERRIDE="${latest_location##*/}"
+  fi
+  printf '%s' "$SOURCE_TAG_OVERRIDE" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+$' \
+    || fail "release tag must look like vX.Y.Z: $SOURCE_TAG_OVERRIDE"
+  SOURCE_TAG="$SOURCE_TAG_OVERRIDE"
+  SOURCE_ARCHIVE="$CACHE/gen1recomp-${SOURCE_TAG}.tar.gz"
+  download "$RELEASE_TARBALL_BASE/$SOURCE_TAG.tar.gz" "$SOURCE_ARCHIVE"
+  SOURCE_EXTRACT="$WORK/source-$SOURCE_TAG"
+  rm -rf "$SOURCE_EXTRACT"
+  mkdir -p "$SOURCE_EXTRACT"
+  tar -xzf "$SOURCE_ARCHIVE" -C "$SOURCE_EXTRACT"
+  SOURCE_DIR="$(find "$SOURCE_EXTRACT" -mindepth 1 -maxdepth 1 -type d -print -quit)"
+  [ -n "$SOURCE_DIR" ] || fail "release archive had no source directory"
+  if [ -z "$VERSION" ]; then VERSION="${SOURCE_TAG#v}"; fi
+fi
+
+say "staging lovegame/ from $SOURCE_TAG"
+GAME_SRC="$WORK/lovegame"
+rm -rf "$GAME_SRC"
+mkdir -p "$GAME_SRC"
+
+# Same payload as scripts/build.sh's game.love — never ship ROM-derived cache.
+# tools/save-editor is part of that payload: the launcher's Edit button on a
+# save row opens it in-process (main.lua).
+(cd "$SOURCE_DIR" && zip -q -9 -r "$WORK/game-payload.zip" \
+  main.lua conf.lua src libs data assets tools/save-editor \
+  tools/rom_manifest.json tools/rom_manifest_blue.json \
+  -x '*.DS_Store' 'data/generated/*' 'assets/generated/*')
+if unzip -Z1 "$WORK/game-payload.zip" \
+    | grep -Eq '^(data|assets)/generated/[^/]+|^(data|assets)/generated/.+/'; then
+  fail "payload unexpectedly contains generated ROM data"
+fi
+unzip -q "$WORK/game-payload.zip" -d "$GAME_SRC"
+rm -f "$WORK/game-payload.zip"
+
+# Stamp release version into the staged tree only (never the working tree).
+if printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+  say "stamping engine version $VERSION"
+  sed -E "s/(engine[[:space:]]*=[[:space:]]*\")[^\"]*(\")/\1$VERSION\2/" \
+    "$SOURCE_DIR/src/core/Version.lua" > "$GAME_SRC/src/core/Version.lua"
+  version_re="$(printf '%s' "$VERSION" | sed 's/\./\\./g')"
+  grep -Eq "engine[[:space:]]*=[[:space:]]*\"$version_re\"" \
+    "$GAME_SRC/src/core/Version.lua" \
+    || fail "version stamp failed"
+else
+  say "version '$VERSION' is not X.Y.Z — shipping default engine (no stamp)"
+fi
+
+# Portable marker: saves + ROM cache live next to the game on the SD card.
+: > "$GAME_SRC/portable.txt"
+
+# --------------------------------------------------------------- love runtime
+say "fetching LÖVE $LOVE_VERSION aarch64 runtime"
+LOVE_BIN="$CACHE/love.aarch64"
+LOVE_LIB="$CACHE/liblove-11.5.so"
+LUAJIT_LIB="$CACHE/libluajit-5.1.so.2"
+MODPLUG_LIB="$CACHE/libmodplug.so.1"
+OGG_LIB="$CACHE/libogg.so.0"
+
+download "$PM_RUNTIME_BASE/love.aarch64" "$LOVE_BIN"
+download "$PM_RUNTIME_BASE/libs.aarch64/liblove-11.5.so" "$LOVE_LIB"
+download "$PM_RUNTIME_BASE/libs.aarch64/libluajit-5.1.so.2" "$LUAJIT_LIB"
+download "$PM_RUNTIME_BASE/libs.aarch64/libmodplug.so.1" "$MODPLUG_LIB"
+download "$PM_RUNTIME_BASE/libs.aarch64/libogg.so.0" "$OGG_LIB"
+
+# Sanity: love stub must be an aarch64 ELF.
+file "$LOVE_BIN" | grep -qi 'aarch64\|ARM aarch64' \
+  || fail "love.aarch64 does not look like an aarch64 ELF (got: $(file "$LOVE_BIN"))"
+
+# --------------------------------------------------------------- port tree
+say "assembling port package"
+PORT_ROOT="$WORK/port"
+rm -rf "$PORT_ROOT"
+mkdir -p "$PORT_ROOT/$PORT_DIR_NAME/bin" \
+         "$PORT_ROOT/$PORT_DIR_NAME/libs.aarch64" \
+         "$PORT_ROOT/$PORT_DIR_NAME/licenses" \
+         "$PORT_ROOT/$PORT_DIR_NAME/conf"
+
+cp -R "$GAME_SRC" "$PORT_ROOT/$PORT_DIR_NAME/lovegame"
+cp "$LOVE_BIN" "$PORT_ROOT/$PORT_DIR_NAME/bin/love.aarch64"
+chmod +x "$PORT_ROOT/$PORT_DIR_NAME/bin/love.aarch64"
+cp "$LOVE_LIB" "$LUAJIT_LIB" "$MODPLUG_LIB" "$OGG_LIB" \
+  "$PORT_ROOT/$PORT_DIR_NAME/libs.aarch64/"
+
+# Drop a short license pointer for the bundled LÖVE bits.
+cat > "$PORT_ROOT/$PORT_DIR_NAME/licenses/LICENSE.love2d.txt" <<'EOF'
+This port bundles the LÖVE 11.5 aarch64 runtime from PortMaster
+(https://github.com/PortsMaster/PortMaster-GUI). LÖVE is zlib-licensed;
+see https://love2d.org/ for full terms.
+EOF
+
+# --------------------------------------------------------------- launcher
+# Resolve the game directory from the launcher so this works with both
+# PortMaster-managed ports directories.
+cat > "$PORT_ROOT/$LAUNCHER_NAME" <<'EOF'
+#!/bin/bash
+# gen1recomp-sbc — Linux ARM SBC / PortMaster launcher
+# Uses SHDIR-relative paths so firmware-specific mount points do not matter.
+
+export HOME="${HOME:-/root}"
+XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
+SHDIR="$(cd "$(dirname "$0")" && pwd)"
+
+if [ -d "/mnt/SDCARD/Apps/PortMaster/PortMaster/" ]; then
+  controlfolder="/mnt/SDCARD/Apps/PortMaster/PortMaster"
+elif [ -d "/mnt/SDCARD/Roms/ports/PortMaster" ]; then
+  controlfolder="/mnt/SDCARD/Roms/ports/PortMaster"
+elif [ -d "/mnt/SDCARD/Data/PortMaster/" ]; then
+  controlfolder="/mnt/SDCARD/Data/PortMaster"
+elif [ -d "$SHDIR/PortMaster" ]; then
+  controlfolder="$SHDIR/PortMaster"
+elif [ -d "/opt/system/Tools/PortMaster/" ]; then
+  controlfolder="/opt/system/Tools/PortMaster"
+elif [ -d "/opt/tools/PortMaster/" ]; then
+  controlfolder="/opt/tools/PortMaster"
+elif [ -d "$XDG_DATA_HOME/PortMaster/" ]; then
+  controlfolder="$XDG_DATA_HOME/PortMaster"
+elif [ -d "/roms/ports/PortMaster" ]; then
+  controlfolder="/roms/ports/PortMaster"
+else
+  controlfolder="/mnt/SDCARD/Roms/PORTS/PortMaster"
+fi
+
+if [ ! -f "$controlfolder/control.txt" ]; then
+  echo "PortMaster control.txt not found under $controlfolder" >&2
+  exit 1
+fi
+# shellcheck disable=SC1090
+source "$controlfolder/control.txt"
+get_controls
+if [ -n "${CFW_NAME:-}" ] && [ -f "${controlfolder}/mod_${CFW_NAME}.txt" ]; then
+  # shellcheck disable=SC1090
+  source "${controlfolder}/mod_${CFW_NAME}.txt"
+fi
+
+GAMEDIR="$SHDIR/gen1recomp-sbc"
+CONFDIR="$GAMEDIR/conf"
+mkdir -p "$CONFDIR"
+
+cd "$GAMEDIR" || exit 1
+> "$GAMEDIR/log.txt" && exec > >(tee "$GAMEDIR/log.txt") 2>&1
+
+export XDG_DATA_HOME="$CONFDIR"
+export XDG_CONFIG_HOME="$CONFDIR"
+export LD_LIBRARY_PATH="$GAMEDIR/libs.aarch64:${LD_LIBRARY_PATH:-}"
+export SDL_GAMECONTROLLERCONFIG="${sdl_controllerconfig:-}"
+# GLES is the common path on ARM SBC handhelds; firmware may override it.
+export LOVE_GRAPHICS_USE_OPENGLES="${LOVE_GRAPHICS_USE_OPENGLES:-1}"
+
+$ESUDO chmod a+x ./bin/love.aarch64 2>/dev/null || chmod a+x ./bin/love.aarch64
+$ESUDO chmod 666 /dev/uinput 2>/dev/null || true
+
+if [ -n "${GPTOKEYB:-}" ]; then
+  $GPTOKEYB "love.aarch64" &
+fi
+if type pm_platform_helper >/dev/null 2>&1; then
+  pm_platform_helper "$GAMEDIR/bin/love.aarch64"
+fi
+
+./bin/love.aarch64 "$GAMEDIR/lovegame"
+
+if type pm_finish >/dev/null 2>&1; then
+  pm_finish
+else
+  if [ -n "${ESUDO:-}" ]; then
+    $ESUDO kill -9 $(pidof gptokeyb) 2>/dev/null || true
+  else
+    kill -9 $(pidof gptokeyb) 2>/dev/null || true
+  fi
+fi
+EOF
+chmod +x "$PORT_ROOT/$LAUNCHER_NAME"
+
+# --------------------------------------------------------------- metadata
+cat > "$PORT_ROOT/port.json" <<EOF
+{
+  "version": 2,
+  "name": "gen1recomp-sbc.zip",
+  "items": [
+    "$LAUNCHER_NAME",
+    "$PORT_DIR_NAME"
+  ],
+  "items_opt": null,
+  "attr": {
+    "title": "gen1recomp-sbc",
+    "desc": "Native LÖVE2D recreation of Pokemon Red and Blue. Supply your own legal US Red or Blue ROM.",
+    "source": "https://github.com/bryanthaboi/gen1recomp/releases/tag/$SOURCE_TAG",
+    "inst": "Requires a 64-bit Linux ARM handheld with PortMaster. Copy a canonical US Red or Blue .gb into gen1recomp-sbc/lovegame/, then launch and press Choose ROM.",
+    "genres": ["adventure", "rpg"],
+    "porter": ["gen1recomp-sbc"],
+    "image": {},
+    "rtr": true,
+    "runtime": null,
+    "reqs": [],
+    "arch": ["aarch64"]
+  }
+}
+EOF
+
+cat > "$PORT_ROOT/gameinfo.xml" <<EOF
+<?xml version="1.0" encoding="utf-8"?>
+<gameList>
+  <game>
+    <path>./$LAUNCHER_NAME</path>
+    <name>gen1recomp-sbc</name>
+    <desc>Native LÖVE2D recreation of Pokemon Red and Blue. Requires your own legal US Red or Blue ROM.</desc>
+    <releasedate>20250101T000000</releasedate>
+    <developer>the bois club</developer>
+    <publisher>the bois club</publisher>
+    <genre>RPG</genre>
+  </game>
+</gameList>
+EOF
+
+cat > "$PORT_ROOT/README.md" <<'EOF'
+## gen1recomp-sbc (Linux ARM SBC / PortMaster)
+
+Native LÖVE 11.5 aarch64 PortMaster port of gen1recomp for compatible Linux ARM SBC handhelds, including H700-class devices. This pack was built from source release **__SOURCE_TAG__**.
+
+### Install
+
+1. Install PortMaster for your handheld firmware.
+2. Unzip so `gen1recomp-sbc.sh` and the `gen1recomp-sbc/` folder are siblings in the device's PortMaster ports directory.
+3. Copy a legal US Pokémon Red or Blue `.gb` into `gen1recomp-sbc/lovegame/`.
+4. Refresh the launcher and launch **gen1recomp-sbc** from Ports.
+
+### Controls
+
+| Input | Action |
+|--|--|
+| D-pad | Move cursor |
+| A | Click |
+| L1 / R1 | Switch tabs |
+| Start / Select | Play or choose ROM |
+
+Controls use the normal PortMaster / SDL pad map. Device-specific power/suspend behavior is supplied by the firmware and PortMaster runtime.
+
+### First run
+
+Put the `.gb` in `lovegame/`, then press **Choose ROM**. After import, the ROM-derived cache and saves stay beside the game (`portable.txt`).
+
+### Thanks
+
+LÖVE runtime binaries from [PortMaster](https://portmaster.games/). PortMaster device support and runtime integration are maintained by the PortMaster team.
+EOF
+sed -i.bak "s/__SOURCE_TAG__/$SOURCE_TAG/g" "$PORT_ROOT/README.md"
+rm -f "$PORT_ROOT/README.md.bak"
+
+# --------------------------------------------------------------- zip
+ZIP_OUT="$DIST/$APP_NAME-$ARTIFACT_SUFFIX.zip"
+rm -f "$ZIP_OUT"
+say "packing $ZIP_OUT"
+(cd "$PORT_ROOT" && zip -q -9 -r "$ZIP_OUT" \
+  "$LAUNCHER_NAME" "$PORT_DIR_NAME" port.json gameinfo.xml README.md)
+
+say "done."
+say "artifact: $ZIP_OUT ($(du -h "$ZIP_OUT" | cut -f1))"
+say "copy into the device PortMaster ports folder, then drop your .gb into gen1recomp-sbc/lovegame/"
@@ -0,0 +1,336 @@
+#!/usr/bin/env bash
+# Build a PortMaster-style aarch64 port of gen1recomp for Anbernic RG34XXSP
+# on Stock OS 64-bit MOD (H700; cbepx-me StockOS MOD / official V1.0.6 base
+# + PortMaster).
+#
+# The stock Anbernic firmware resolves ports relative to the launch script
+# (roms/PORTS/...), not PortMaster's /$directory/ports/... path. This pack
+# uses SHDIR-relative paths and bundles the LÖVE 11.5 aarch64 runtime so the
+# device does not need a separate love_11.5 runtime download on first launch.
+#
+# Usage:
+#   ./build-rg34xxsp.sh [--version X.Y.Z]
+#
+# Output:
+#   dist/rg34xxsp/gen1recomp-rg34xxsp-stockos64-mod.zip
+#
+# Install on device:
+#   1. Flash / run Stock OS 64-bit MOD with PortMaster installed.
+#   2. Unzip into the SD card's roms/PORTS/ folder so you have:
+#        roms/PORTS/Gen1recomp.sh
+#        roms/PORTS/gen1recomp/...
+#   3. Copy a legal US Red or Blue .gb into roms/PORTS/gen1recomp/lovegame/
+#   4. Launch "Gen1recomp" from the Ports list; press Choose ROM (scans that
+#      folder when zenity is missing).
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")" && pwd)"
+HERE="$ROOT/.bazinga"
+CACHE="$HERE/cache/rg34xxsp"
+WORK="$HERE/work/rg34xxsp"
+DIST="$ROOT/dist/rg34xxsp"
+
+APP_NAME="gen1recomp"
+# Artifact suffix matches the CFW this port targets (Anbernic H700 Stock OS
+# 64-bit MOD for RG34XXSP). Release uploads stage it as
+# gen1recomp-<ver>-rg34xxsp-stockos64-mod.zip.
+ARTIFACT_SUFFIX="rg34xxsp-stockos64-mod"
+PORT_DIR_NAME="gen1recomp"
+LAUNCHER_NAME="Gen1recomp.sh"
+LOVE_VERSION="11.5"
+VERSION="$(git -C "$ROOT" rev-parse --short HEAD 2>/dev/null || echo dev)"
+
+# Official PortMaster LÖVE 11.5 aarch64 runtime (small love stub + liblove).
+PM_RUNTIME_BASE="https://raw.githubusercontent.com/PortsMaster/PortMaster-GUI/main/PortMaster/runtimes/love_${LOVE_VERSION}"
+
+say()  { printf '\033[1;32m==>\033[0m %s\n' "$*"; }
+warn() { printf '\033[1;33mwarn:\033[0m %s\n' "$*" >&2; }
+fail() { printf '\033[1;31merror:\033[0m %s\n' "$*" >&2; exit 1; }
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --version) VERSION="$2"; shift ;;
+    -h|--help)
+      sed -n '2,24p' "$0"
+      exit 0
+      ;;
+    *) fail "unknown argument: $1" ;;
+  esac
+  shift
+done
+
+command -v curl >/dev/null || fail "curl is required"
+command -v zip  >/dev/null || fail "zip is required"
+command -v unzip >/dev/null || fail "unzip is required"
+
+mkdir -p "$CACHE" "$WORK" "$DIST"
+
+download() {
+  local url="$1" dest="$2"
+  if [ -f "$dest" ] && [ -s "$dest" ]; then
+    return 0
+  fi
+  say "downloading $(basename "$dest")"
+  curl -fL --progress-bar "$url" -o "$dest.tmp" \
+    || fail "download failed: $url"
+  mv "$dest.tmp" "$dest"
+}
+
+# --------------------------------------------------------------- game tree
+# Unpacked directory (not a .love zip) so the player can drop a .gb next to
+# main.lua and RomImporter can scan it without zenity/kdialog.
+say "staging lovegame/"
+GAME_SRC="$WORK/lovegame"
+rm -rf "$GAME_SRC"
+mkdir -p "$GAME_SRC"
+
+# Same payload as scripts/build.sh's game.love — never ship ROM-derived cache.
+# tools/save-editor is part of that payload: the launcher's Edit button on a
+# save row opens it in-process (main.lua).
+(cd "$ROOT" && zip -q -9 -r "$WORK/game-payload.zip" \
+  main.lua conf.lua src libs data assets tools/save-editor \
+  tools/rom_manifest.json tools/rom_manifest_blue.json \
+  tools/rom_manifest_yellow.json tools/rom_manifest_gold.json \
+  -x '*.DS_Store' 'data/generated/*' 'assets/generated/*')
+payload_list="$(unzip -Z1 "$WORK/game-payload.zip")"
+printf '%s\n' "$payload_list" \
+  | grep -Eq '^(data|assets)/generated/[^/]+|^(data|assets)/generated/.+/' \
+  && fail "payload unexpectedly contains generated ROM data"
+printf '%s\n' "$payload_list" | grep -qxF "tools/rom_manifest_gold.json" \
+  || fail "payload is missing tools/rom_manifest_gold.json"
+unzip -q "$WORK/game-payload.zip" -d "$GAME_SRC"
+rm -f "$WORK/game-payload.zip"
+
+# Stamp release version into the staged tree only (never the working tree).
+if printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+  say "stamping engine version $VERSION"
+  sed -E "s/(engine[[:space:]]*=[[:space:]]*\")[^\"]*(\")/\1$VERSION\2/" \
+    "$ROOT/src/core/Version.lua" > "$GAME_SRC/src/core/Version.lua"
+  version_re="$(printf '%s' "$VERSION" | sed 's/\./\\./g')"
+  grep -Eq "engine[[:space:]]*=[[:space:]]*\"$version_re\"" \
+    "$GAME_SRC/src/core/Version.lua" \
+    || fail "version stamp failed"
+else
+  say "version '$VERSION' is not X.Y.Z — shipping default engine (no stamp)"
+fi
+
+# Portable marker: saves + ROM cache live next to the game on the SD card.
+: > "$GAME_SRC/portable.txt"
+
+# --------------------------------------------------------------- love runtime
+say "fetching LÖVE $LOVE_VERSION aarch64 runtime"
+LOVE_BIN="$CACHE/love.aarch64"
+LOVE_LIB="$CACHE/liblove-11.5.so"
+LUAJIT_LIB="$CACHE/libluajit-5.1.so.2"
+MODPLUG_LIB="$CACHE/libmodplug.so.1"
+OGG_LIB="$CACHE/libogg.so.0"
+
+download "$PM_RUNTIME_BASE/love.aarch64" "$LOVE_BIN"
+download "$PM_RUNTIME_BASE/libs.aarch64/liblove-11.5.so" "$LOVE_LIB"
+download "$PM_RUNTIME_BASE/libs.aarch64/libluajit-5.1.so.2" "$LUAJIT_LIB"
+download "$PM_RUNTIME_BASE/libs.aarch64/libmodplug.so.1" "$MODPLUG_LIB"
+download "$PM_RUNTIME_BASE/libs.aarch64/libogg.so.0" "$OGG_LIB"
+
+# Sanity: love stub must be an aarch64 ELF.
+file "$LOVE_BIN" | grep -qi 'aarch64\|ARM aarch64' \
+  || fail "love.aarch64 does not look like an aarch64 ELF (got: $(file "$LOVE_BIN"))"
+
+# --------------------------------------------------------------- port tree
+say "assembling port package"
+PORT_ROOT="$WORK/port"
+rm -rf "$PORT_ROOT"
+mkdir -p "$PORT_ROOT/$PORT_DIR_NAME/bin" \
+         "$PORT_ROOT/$PORT_DIR_NAME/libs.aarch64" \
+         "$PORT_ROOT/$PORT_DIR_NAME/licenses" \
+         "$PORT_ROOT/$PORT_DIR_NAME/conf"
+
+cp -R "$GAME_SRC" "$PORT_ROOT/$PORT_DIR_NAME/lovegame"
+cp "$LOVE_BIN" "$PORT_ROOT/$PORT_DIR_NAME/bin/love.aarch64"
+chmod +x "$PORT_ROOT/$PORT_DIR_NAME/bin/love.aarch64"
+cp "$LOVE_LIB" "$LUAJIT_LIB" "$MODPLUG_LIB" "$OGG_LIB" \
+  "$PORT_ROOT/$PORT_DIR_NAME/libs.aarch64/"
+
+# Drop a short license pointer for the bundled LÖVE bits.
+cat > "$PORT_ROOT/$PORT_DIR_NAME/licenses/LICENSE.love2d.txt" <<'EOF'
+This port bundles the LÖVE 11.5 aarch64 runtime from PortMaster
+(https://github.com/PortsMaster/PortMaster-GUI). LÖVE is zlib-licensed;
+see https://love2d.org/ for full terms.
+EOF
+
+# --------------------------------------------------------------- launcher
+# Stock OS fix: resolve GAMEDIR from this script's directory (SHDIR), not
+# PortMaster's $directory variable — Anbernic uses roms/PORTS with different
+# casing and mount points (mmc / sdcard / TF1 / TF2).
+cat > "$PORT_ROOT/$LAUNCHER_NAME" <<'EOF'
+#!/bin/bash
+# gen1recomp — Anbernic RG34XXSP stock OS / PortMaster launcher
+# Uses SHDIR-relative paths so stock firmware finds the game folder.
+
+export HOME="${HOME:-/root}"
+XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
+
+if [ -d "/opt/system/Tools/PortMaster/" ]; then
+  controlfolder="/opt/system/Tools/PortMaster"
+elif [ -d "/opt/tools/PortMaster/" ]; then
+  controlfolder="/opt/tools/PortMaster"
+elif [ -d "$XDG_DATA_HOME/PortMaster/" ]; then
+  controlfolder="$XDG_DATA_HOME/PortMaster"
+elif [ -d "/mnt/mmc/Roms/PORTS/PortMaster" ]; then
+  controlfolder="/mnt/mmc/Roms/PORTS/PortMaster"
+elif [ -d "/mnt/sdcard/Roms/PORTS/PortMaster" ]; then
+  controlfolder="/mnt/sdcard/Roms/PORTS/PortMaster"
+elif [ -d "/roms/ports/PortMaster" ]; then
+  controlfolder="/roms/ports/PortMaster"
+else
+  controlfolder="/roms/PORTS/PortMaster"
+fi
+
+SHDIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck disable=SC1090
+source "$controlfolder/control.txt"
+get_controls
+[ -f "${controlfolder}/mod_${CFW_NAME}.txt" ] && source "${controlfolder}/mod_${CFW_NAME}.txt"
+
+GAMEDIR="$SHDIR/gen1recomp"
+CONFDIR="$GAMEDIR/conf"
+mkdir -p "$CONFDIR"
+
+cd "$GAMEDIR" || exit 1
+> "$GAMEDIR/log.txt" && exec > >(tee "$GAMEDIR/log.txt") 2>&1
+
+export XDG_DATA_HOME="$CONFDIR"
+export XDG_CONFIG_HOME="$CONFDIR"
+export LD_LIBRARY_PATH="$GAMEDIR/libs.aarch64:${LD_LIBRARY_PATH:-}"
+export SDL_GAMECONTROLLERCONFIG="${sdl_controllerconfig:-}"
+# Mali / H700: prefer GLES where available
+export LOVE_GRAPHICS_USE_OPENGLES="${LOVE_GRAPHICS_USE_OPENGLES:-1}"
+# Same GPU class as a phone, but getOS() here says "Linux", so the Android
+# gate (issue #136) would not fire on its own: refuse GBC FX explicitly.
+# Hides the OPTIONS row, pins the level to OFF, and heals a level already
+# persisted in options.lua.
+export POKEPORT_GBCFX="${POKEPORT_GBCFX:-0}"
+
+$ESUDO chmod a+x ./bin/love.aarch64 2>/dev/null || chmod a+x ./bin/love.aarch64
+$ESUDO chmod 666 /dev/uinput 2>/dev/null || true
+
+if [ -n "${GPTOKEYB:-}" ]; then
+  $GPTOKEYB "love.aarch64" &
+fi
+if type pm_platform_helper >/dev/null 2>&1; then
+  pm_platform_helper "$GAMEDIR/bin/love.aarch64"
+fi
+
+./bin/love.aarch64 "$GAMEDIR/lovegame"
+
+if type pm_finish >/dev/null 2>&1; then
+  pm_finish
+else
+  if [ -n "${ESUDO:-}" ]; then
+    $ESUDO kill -9 $(pidof gptokeyb) 2>/dev/null || true
+  else
+    kill -9 $(pidof gptokeyb) 2>/dev/null || true
+  fi
+fi
+EOF
+chmod +x "$PORT_ROOT/$LAUNCHER_NAME"
+
+# --------------------------------------------------------------- metadata
+cat > "$PORT_ROOT/port.json" <<EOF
+{
+  "version": 2,
+  "name": "gen1recomp.zip",
+  "items": [
+    "$LAUNCHER_NAME",
+    "$PORT_DIR_NAME"
+  ],
+  "items_opt": null,
+  "attr": {
+    "title": "gen1recomp",
+    "desc": "Native LÖVE2D recreation of Pokemon Red and Blue. Supply your own legal US Red or Blue ROM.",
+    "inst": "Requires Anbernic RG34XXSP Stock OS 64-bit MOD with PortMaster. Copy a canonical US Red or Blue .gb into gen1recomp/lovegame/, then launch and press Choose ROM.",
+    "genres": ["adventure", "rpg"],
+    "porter": ["gen1recomp"],
+    "image": {},
+    "rtr": true,
+    "runtime": null,
+    "reqs": [],
+    "arch": ["aarch64"]
+  }
+}
+EOF
+
+cat > "$PORT_ROOT/gameinfo.xml" <<EOF
+<?xml version="1.0" encoding="utf-8"?>
+<gameList>
+  <game>
+    <path>./$LAUNCHER_NAME</path>
+    <name>gen1recomp</name>
+    <desc>Native LÖVE2D recreation of Pokemon Red and Blue. Requires your own legal US Red or Blue ROM.</desc>
+    <releasedate>20250101T000000</releasedate>
+    <developer>the bois club</developer>
+    <publisher>the bois club</publisher>
+    <genre>RPG</genre>
+  </game>
+</gameList>
+EOF
+
+cat > "$PORT_ROOT/README.md" <<'EOF'
+## gen1recomp (RG34XXSP / Stock OS 64-bit MOD)
+
+Native LÖVE 11.5 port of gen1recomp for Anbernic RG34XXSP on
+**Stock OS 64-bit MOD** (H700, PortMaster).
+
+### Install
+
+1. Use **Stock OS 64-bit MOD** with PortMaster installed (TF1).
+2. Unzip so `Gen1recomp.sh` and the `gen1recomp/` folder sit in `roms/PORTS/`.
+3. Copy a legal US Pokemon Red or Blue `.gb` into `gen1recomp/lovegame/`.
+4. Refresh Ports / restart EmulationStation and launch **Gen1recomp**.
+
+### Controls (launcher)
+
+| Input | Action |
+|--|--|
+| D-pad / left stick | Move cursor |
+| A | Click |
+| L1 / R1 | Switch tabs |
+| Right stick | Scroll lists |
+| Start / Select | Play or Choose ROM |
+
+In-game controls use the normal PortMaster / SDL pad map (rebind under OPTIONS → CONTROLS).
+
+### Display options
+
+GBC FX is disabled on this device (the H700's Mali GPU compiles that present
+pass and then shows a black frame), so the OPTIONS row is hidden. COLORS,
+TILT, ZOOM, VOID FILL and MAX FPS all work. To try it anyway, launch with
+`POKEPORT_GBCFX=1`.
+
+### First run
+
+Stock OS has no zenity file picker. Put the `.gb` in `lovegame/`, then press
+**Choose ROM** — the game scans that folder. After import, the ROM-derived
+cache and saves stay beside the game (`portable.txt`).
+
+Canonical SHA-1 (1 MiB US carts only):
+
+- Red: `ea9bcae617fdf159b045185467ae58b2e4a48b9a`
+- Blue: `d7037c83e1ae5b39bde3c30787637ba1d4c48ce2`
+
+### Thanks
+
+LÖVE runtime binaries from [PortMaster](https://portmaster.games/).
+Stock OS 64-bit MOD: [cbepx-me](https://github.com/cbepx-me/Anbernic-H700-RG-xx-StockOS-Modification).
+EOF
+
+# --------------------------------------------------------------- zip
+ZIP_OUT="$DIST/$APP_NAME-$ARTIFACT_SUFFIX.zip"
+rm -f "$ZIP_OUT" "$DIST/$APP_NAME-rg34xxsp.zip"
+say "packing $ZIP_OUT"
+(cd "$PORT_ROOT" && zip -q -9 -r "$ZIP_OUT" \
+  "$LAUNCHER_NAME" "$PORT_DIR_NAME" port.json gameinfo.xml README.md)
+
+say "done."
+say "artifact: $ZIP_OUT ($(du -h "$ZIP_OUT" | cut -f1))"
+say "copy onto the RG34XXSP SD card under roms/PORTS/ (Stock OS 64-bit MOD), then drop your .gb into gen1recomp/lovegame/"
@@ -1,4 +1,9 @@
 function love.conf(t)
+  -- PhysFS ignores symlinks unless told otherwise, so a mod dev-linked into
+  -- mods/ (ln -s, matching the mklink /J workflow on Windows) is invisible
+  -- to love.filesystem.getDirectoryItems without this.
+  love.filesystem.setSymlinksEnabled(true)
+
  local editor = os.getenv("POKEPORT_EDITOR") == "1"
  local developer = os.getenv("POKEPORT_DEV") == "1"
  if arg then
@@ -13,7 +18,12 @@ function love.conf(t)
  _G.POKEPORT_DEV_MODE = developer

  if editor then
-    t.identity = os.getenv("POKEPORT_IDENTITY") or "pokemon-love2d-editor"
+    -- Same identity as the game, deliberately: the editor edits the game's
+    -- saves and reads the game's ROM cache, both of which live under this
+    -- folder.  A private editor identity would point love.filesystem at an
+    -- empty directory in a packaged build, so `--editor` could not find
+    -- data/generated at all (SaveIO.defaultPath already assumed this name).
+    t.identity = os.getenv("POKEPORT_IDENTITY") or "pokemon-love2d"
    t.window.title = "Pokemon Save Editor"
    t.window.width = 1280
    t.window.height = 800
@@ -23,11 +33,23 @@ function love.conf(t)
    -- back to the plain title if the source is not mounted yet
    local ok, Version = pcall(require, "src.core.Version")
    t.window.title = ok and Version.title()
-      or "Pokemon Red (Gen 1 Recompilation Project)"
-    t.window.width = 160 * 4
-    t.window.height = 144 * 4
+      or "gen1recomp"
+    -- Open at the launcher's design size (the split-screen ROM selector is
+    -- laid out for 1024x768). The window is resizable and the 160x144 game
+    -- canvas letterboxes into whatever size it ends up, so this only sets the
+    -- starting size, not the game's resolution.
+    t.window.width = 1024
+    t.window.height = 768
+    -- Floor for the resizable desktop window.  The launcher's single-column
+    -- layout is laid out against ~420 logical px of content, and the game
+    -- canvas letterboxes fine below that, so this only stops a drag that would
+    -- squeeze the cards past the point where their buttons still read.  Kept
+    -- well under the smallest supported desktop display; mobile ignores it
+    -- (fullscreen), so the handheld ports are unaffected.
+    t.window.minwidth = 480
+    t.window.minheight = 360
  end
-  t.version = "11.5"
+  t.version = love._os == "iOS" and "12.0" or "11.5"
  t.window.vsync = 1
  t.modules.joystick = true
  t.modules.physics = false
@@ -36,15 +58,33 @@ function love.conf(t)
  -- engine before conf runs (LÖVE 11.x / 11.5).
  local osName = love._os
  local mobile = osName == "Android" or osName == "iOS"
-  if mobile then
+  local nx = osName == "NX"
+  if nx then
+    -- Switch (love-nx): hint handheld 720p. SDL auto-switches portable↔dock
+    -- (720p↔1080p) only when the window is resizable and not exclusive
+    -- fullscreen; NxDisplay.sync also applies the size on boot and dock change.
+    t.window.width = 1280
+    t.window.height = 720
+    t.window.fullscreen = false
+    t.window.resizable = true
+    t.window.highdpi = false
+  elseif mobile then
    -- resizable is what unlocks orientation.  SDL's Android backend, given no
    -- SDL_HINT_ORIENTATIONS (LÖVE sets none), calls setRequestedOrientation
    -- at window creation -- FULL_SENSOR when the window is resizable (rotates
    -- freely to portrait or landscape), otherwise locked to the window's w/h
    -- aspect.  So a non-resizable tall window forced portrait; resizable lets
    -- the game follow the device.  The renderer letterboxes the 160x144
-    -- viewport into whatever size results, and touch input is gesture-based,
-    -- so both orientations just work.  iOS follows the Info.plist orientations
+    -- viewport into whatever size results, and the on-screen touch controls
+    -- re-lay themselves out from the new window size, so both orientations
+    -- just work.  FULL_SENSOR ignores the device's rotation lock, so
+    -- GameActivity.setOrientationBis remaps it to FULL_USER after SDL has
+    -- run: same orientations allowed, but auto-rotate being off now wins.
+    -- A persisted ORIENTATION lock (#592) overrides all of this after boot:
+    -- src/core/Orientation.lua sets SDL_HINT_ORIENTATIONS over the FFI and
+    -- re-triggers the request, from main.lua for the launcher and from
+    -- Game:applyOptions in game.
+    -- iOS follows the Info.plist orientations
    -- (see mobile/ios/overlays/love-ios.plist, now portrait + landscape).
    t.window.resizable = true
    -- Starting size is a tall portrait hint; the OS resizes to the real
@@ -60,6 +100,14 @@ function love.conf(t)
    -- player to copy their ROM there instead of needing a native file
    -- picker (LOVE 11.5 on Android has none -- see src/import/RomImporter.lua).
    t.externalstorage = osName == "Android"
+    -- LOVE 11.x exposes the phone's accelerometer as a 3-axis joystick by
+    -- default.  Gravity keeps one axis pinned near +/-1.0 whenever the phone
+    -- is held upright, so it streams past-deadzone joystickaxis events that
+    -- both hid the touch overlay every instant (it reads as "a controller is
+    -- in use") and, via the generic-joystick axis mapping (#459), walked the
+    -- player around by tilt.  Nothing in the game reads the accelerometer,
+    -- so drop the device entirely (#468).
+    t.accelerometerjoystick = false
  else
    t.window.resizable = true
  end
@@ -1683,158 +1683,172 @@ return {
      { 0, 0, 0 },
    },
  },
+  -- Species -> palette NAME, taken from pokered-gbc data/pokemon/palettes.asm
+  -- ELSE branch -- the one that is NOT gated on GEN_2_GRAPHICS.
+  --
+  -- That file has two tables.  The IF GEN_2_GRAPHICS branch assigns a
+  -- PER-SPECIES palette (PAL_BULBASAUR, PAL_SQUIRTLE, ...) authored for Gen 2
+  -- sprite art; the ELSE branch keeps Gen 1's own assignments (GREENMON,
+  -- CYANMON, ...).  This port extracts Gen 1 pics from the ROM, so the Gen 1
+  -- branch is the matching one.  The per-species table was imported here by
+  -- mistake, which pointed every mon at colours shaded for different art:
+  -- Bulbasaur wore PAL_BULBASAUR's red-orange over a sprite that has no red
+  -- on it, and Squirtle wore PAL_SQUIRTLE's shell brown on his head.
+  --
+  -- The palette VALUES below are still pokered-gbc's, so ADVANCED keeps its
+  -- richer colours -- only which palette each species points at changed.
  pokemon = {
-    ABRA = "ABRA",
-    AERODACTYL = "AERODACTYL",
-    ALAKAZAM = "ALAKAZAM",
-    ARBOK = "ARBOK",
-    ARCANINE = "ARCANINE",
-    ARTICUNO = "ARTICUNO",
-    BEEDRILL = "BEEDRILL",
-    BELLSPROUT = "BELLSPROUT",
-    BLASTOISE = "BLASTOISE",
-    BULBASAUR = "BULBASAUR",
-    BUTTERFREE = "BUTTERFREE",
-    CATERPIE = "CATERPIE",
-    CHANSEY = "CHANSEY",
-    CHARIZARD = "CHARIZARD",
-    CHARMANDER = "CHARMANDER",
-    CHARMELEON = "CHARMELEON",
-    CLEFABLE = "CLEFABLE",
-    CLEFAIRY = "CLEFAIRY",
-    CLOYSTER = "CLOYSTER",
-    CUBONE = "CUBONE",
-    DEWGONG = "DEWGONG",
-    DIGLETT = "DIGLETT",
-    DITTO = "DITTO",
-    DODRIO = "DODRIO",
-    DODUO = "DODUO",
-    DRAGONAIR = "DRAGONAIR",
-    DRAGONITE = "DRAGONITE",
-    DRATINI = "DRATINI",
-    DROWZEE = "DROWZEE",
-    DUGTRIO = "DUGTRIO",
-    EEVEE = "EEVEE",
-    EKANS = "EKANS",
-    ELECTABUZZ = "ELECTABUZZ",
-    ELECTRODE = "ELECTRODE",
-    EXEGGCUTE = "EXEGGCUTE",
-    EXEGGUTOR = "EXEGGUTOR",
-    FARFETCHD = "FARFETCH_D",
-    FEAROW = "FEAROW",
-    FLAREON = "FLAREON",
-    GASTLY = "GASTLY",
-    GENGAR = "GENGAR",
-    GEODUDE = "GEODUDE",
-    GLOOM = "GLOOM",
-    GOLBAT = "GOLBAT",
-    GOLDEEN = "GOLDEEN",
-    GOLDUCK = "GOLDUCK",
-    GOLEM = "GOLEM",
-    GRAVELER = "GRAVELER",
-    GRIMER = "GRIMER",
-    GROWLITHE = "GROWLITHE",
-    GYARADOS = "GYARADOS",
-    HAUNTER = "HAUNTER",
-    HITMONCHAN = "HITMONCHAN",
-    HITMONLEE = "HITMONLEE",
-    HORSEA = "HORSEA",
-    HYPNO = "HYPNO",
-    IVYSAUR = "IVYSAUR",
-    JIGGLYPUFF = "JIGGLYPUFF",
-    JOLTEON = "JOLTEON",
-    JYNX = "JYNX",
-    KABUTO = "KABUTO",
-    KABUTOPS = "KABUTOPS",
-    KADABRA = "KADABRA",
-    KAKUNA = "KAKUNA",
-    KANGASKHAN = "KANGASKHAN",
-    KINGLER = "KINGLER",
-    KOFFING = "KOFFING",
-    KRABBY = "KRABBY",
-    LAPRAS = "LAPRAS",
-    LICKITUNG = "LICKITUNG",
-    MACHAMP = "MACHAMP",
-    MACHOKE = "MACHOKE",
-    MACHOP = "MACHOP",
-    MAGIKARP = "MAGIKARP",
-    MAGMAR = "MAGMAR",
-    MAGNEMITE = "MAGNEMITE",
-    MAGNETON = "MAGNETON",
-    MANKEY = "MANKEY",
-    MAROWAK = "MAROWAK",
-    MEOWTH = "MEOWTH",
-    METAPOD = "METAPOD",
-    MEW = "MEW",
-    MEWTWO = "MEWTWO",
-    MOLTRES = "MOLTRES",
-    MR_MIME = "MR_MIME",
-    MUK = "MUK",
-    NIDOKING = "NIDOKING",
-    NIDOQUEEN = "NIDOQUEEN",
-    NIDORAN_F = "NIDORAN_F",
-    NIDORAN_M = "NIDORAN_M",
-    NIDORINA = "NIDORINA",
-    NIDORINO = "NIDORINO",
-    NINETALES = "NINETALES",
-    ODDISH = "ODDISH",
-    OMANYTE = "OMANYTE",
-    OMASTAR = "OMASTAR",
-    ONIX = "ONIX",
-    PARAS = "PARAS",
-    PARASECT = "PARASECT",
-    PERSIAN = "PERSIAN",
-    PIDGEOT = "PIDGEOT",
-    PIDGEOTTO = "PIDGEOTTO",
-    PIDGEY = "PIDGEY",
-    PIKACHU = "PIKACHU",
-    PINSIR = "PINSIR",
-    POLIWAG = "POLIWAG",
-    POLIWHIRL = "POLIWHIRL",
-    POLIWRATH = "POLIWRATH",
-    PONYTA = "PONYTA",
-    PORYGON = "PORYGON",
-    PRIMEAPE = "PRIMEAPE",
-    PSYDUCK = "PSYDUCK",
-    RAICHU = "RAICHU",
-    RAPIDASH = "RAPIDASH",
-    RATICATE = "RATICATE",
-    RATTATA = "RATTATA",
-    RHYDON = "RHYDON",
-    RHYHORN = "RHYHORN",
-    SANDSHREW = "SANDSHREW",
-    SANDSLASH = "SANDSLASH",
-    SCYTHER = "SCYTHER",
-    SEADRA = "SEADRA",
-    SEAKING = "SEAKING",
-    SEEL = "SEEL",
-    SHELLDER = "SHELLDER",
-    SLOWBRO = "SLOWBRO",
-    SLOWPOKE = "SLOWPOKE",
-    SNORLAX = "SNORLAX",
-    SPEAROW = "SPEAROW",
-    SQUIRTLE = "SQUIRTLE",
-    STARMIE = "STARMIE",
-    STARYU = "STARYU",
-    TANGELA = "TANGELA",
-    TAUROS = "TAUROS",
-    TENTACOOL = "TENTACOOL",
-    TENTACRUEL = "TENTACRUEL",
-    VAPOREON = "VAPOREON",
-    VENOMOTH = "VENOMOTH",
-    VENONAT = "VENONAT",
-    VENUSAUR = "VENUSAUR",
-    VICTREEBEL = "VICTREEBEL",
-    VILEPLUME = "VILEPLUME",
-    VOLTORB = "VOLTORB",
-    VULPIX = "VULPIX",
-    WARTORTLE = "WARTORTLE",
-    WEEDLE = "WEEDLE",
-    WEEPINBELL = "WEEPINBELL",
-    WEEZING = "WEEZING",
-    WIGGLYTUFF = "WIGGLYTUFF",
-    ZAPDOS = "ZAPDOS",
-    ZUBAT = "ZUBAT",
+    ABRA = "YELLOWMON",
+    AERODACTYL = "GRAYMON",
+    ALAKAZAM = "YELLOWMON",
+    ARBOK = "PURPLEMON",
+    ARCANINE = "REDMON",
+    ARTICUNO = "BLUEMON",
+    BEEDRILL = "YELLOWMON",
+    BELLSPROUT = "GREENMON",
+    BLASTOISE = "CYANMON",
+    BULBASAUR = "GREENMON",
+    BUTTERFREE = "CYANMON",
+    CATERPIE = "GREENMON",
+    CHANSEY = "PINKMON",
+    CHARIZARD = "REDMON",
+    CHARMANDER = "REDMON",
+    CHARMELEON = "REDMON",
+    CLEFABLE = "PINKMON",
+    CLEFAIRY = "PINKMON",
+    CLOYSTER = "GRAYMON",
+    CUBONE = "GRAYMON",
+    DEWGONG = "BLUEMON",
+    DIGLETT = "BROWNMON",
+    DITTO = "GRAYMON",
+    DODRIO = "BROWNMON",
+    DODUO = "BROWNMON",
+    DRAGONAIR = "BLUEMON",
+    DRAGONITE = "BROWNMON",
+    DRATINI = "GRAYMON",
+    DROWZEE = "YELLOWMON",
+    DUGTRIO = "BROWNMON",
+    EEVEE = "GRAYMON",
+    EKANS = "PURPLEMON",
+    ELECTABUZZ = "YELLOWMON",
+    ELECTRODE = "YELLOWMON",
+    EXEGGCUTE = "PINKMON",
+    EXEGGUTOR = "GREENMON",
+    FARFETCHD = "BROWNMON",
+    FEAROW = "BROWNMON",
+    FLAREON = "REDMON",
+    GASTLY = "PURPLEMON",
+    GENGAR = "PURPLEMON",
+    GEODUDE = "GRAYMON",
+    GLOOM = "REDMON",
+    GOLBAT = "BLUEMON",
+    GOLDEEN = "REDMON",
+    GOLDUCK = "CYANMON",
+    GOLEM = "GRAYMON",
+    GRAVELER = "GRAYMON",
+    GRIMER = "PURPLEMON",
+    GROWLITHE = "BROWNMON",
+    GYARADOS = "BLUEMON",
+    HAUNTER = "PURPLEMON",
+    HITMONCHAN = "BROWNMON",
+    HITMONLEE = "BROWNMON",
+    HORSEA = "CYANMON",
+    HYPNO = "YELLOWMON",
+    IVYSAUR = "GREENMON",
+    JIGGLYPUFF = "PINKMON",
+    JOLTEON = "YELLOWMON",
+    JYNX = "MEWMON",
+    KABUTO = "BROWNMON",
+    KABUTOPS = "BROWNMON",
+    KADABRA = "YELLOWMON",
+    KAKUNA = "YELLOWMON",
+    KANGASKHAN = "BROWNMON",
+    KINGLER = "REDMON",
+    KOFFING = "PURPLEMON",
+    KRABBY = "REDMON",
+    LAPRAS = "CYANMON",
+    LICKITUNG = "PINKMON",
+    MACHAMP = "GRAYMON",
+    MACHOKE = "GRAYMON",
+    MACHOP = "GRAYMON",
+    MAGIKARP = "REDMON",
+    MAGMAR = "REDMON",
+    MAGNEMITE = "GRAYMON",
+    MAGNETON = "GRAYMON",
+    MANKEY = "BROWNMON",
+    MAROWAK = "GRAYMON",
+    MEOWTH = "YELLOWMON",
+    METAPOD = "GREENMON",
+    MEW = "MEWMON",
+    MEWTWO = "MEWMON",
+    MOLTRES = "REDMON",
+    MR_MIME = "PINKMON",
+    MUK = "PURPLEMON",
+    NIDOKING = "PURPLEMON",
+    NIDOQUEEN = "BLUEMON",
+    NIDORAN_F = "BLUEMON",
+    NIDORAN_M = "PURPLEMON",
+    NIDORINA = "BLUEMON",
+    NIDORINO = "PURPLEMON",
+    NINETALES = "YELLOWMON",
+    ODDISH = "GREENMON",
+    OMANYTE = "BLUEMON",
+    OMASTAR = "BLUEMON",
+    ONIX = "GRAYMON",
+    PARAS = "REDMON",
+    PARASECT = "REDMON",
+    PERSIAN = "YELLOWMON",
+    PIDGEOT = "BROWNMON",
+    PIDGEOTTO = "BROWNMON",
+    PIDGEY = "BROWNMON",
+    PIKACHU = "YELLOWMON",
+    PINSIR = "BROWNMON",
+    POLIWAG = "BLUEMON",
+    POLIWHIRL = "BLUEMON",
+    POLIWRATH = "BLUEMON",
+    PONYTA = "REDMON",
+    PORYGON = "GRAYMON",
+    PRIMEAPE = "BROWNMON",
+    PSYDUCK = "YELLOWMON",
+    RAICHU = "YELLOWMON",
+    RAPIDASH = "REDMON",
+    RATICATE = "GRAYMON",
+    RATTATA = "GRAYMON",
+    RHYDON = "GRAYMON",
+    RHYHORN = "GRAYMON",
+    SANDSHREW = "BROWNMON",
+    SANDSLASH = "BROWNMON",
+    SCYTHER = "GREENMON",
+    SEADRA = "CYANMON",
+    SEAKING = "REDMON",
+    SEEL = "BLUEMON",
+    SHELLDER = "GRAYMON",
+    SLOWBRO = "PINKMON",
+    SLOWPOKE = "PINKMON",
+    SNORLAX = "PINKMON",
+    SPEAROW = "BROWNMON",
+    SQUIRTLE = "CYANMON",
+    STARMIE = "GRAYMON",
+    STARYU = "REDMON",
+    TANGELA = "BLUEMON",
+    TAUROS = "GRAYMON",
+    TENTACOOL = "CYANMON",
+    TENTACRUEL = "CYANMON",
+    VAPOREON = "CYANMON",
+    VENOMOTH = "PURPLEMON",
+    VENONAT = "PURPLEMON",
+    VENUSAUR = "GREENMON",
+    VICTREEBEL = "GREENMON",
+    VILEPLUME = "REDMON",
+    VOLTORB = "YELLOWMON",
+    VULPIX = "REDMON",
+    WARTORTLE = "CYANMON",
+    WEEDLE = "YELLOWMON",
+    WEEPINBELL = "GREENMON",
+    WEEZING = "PURPLEMON",
+    WIGGLYTUFF = "PINKMON",
+    ZAPDOS = "YELLOWMON",
+    ZUBAT = "BLUEMON",
  },
  source = "pokered-gbc data/super_palettes.asm + data/mon_palettes.asm + color/**",
  world = {
@@ -0,0 +1,686 @@
+-- Generated by tools/build_data.py. DO NOT EDIT.
+-- Pokemon Yellow palettes (COLORS=OG YELLOW): SuperPalettes +
+-- CGBBasePalettes (authentic GBC look) as 4 8-bit RGB colors
+-- per palette (color 0 first), plus MonsterPalettes.
+return {
+  cgbBase = {
+    ["0F"] = {
+      { 255, 255, 255 },
+      { 107, 8, 255 },
+      { 0, 74, 255 },
+      { 8, 8, 8 },
+    },
+    BADGE = {
+      { 255, 255, 255 },
+      { 189, 66, 0 },
+      { 140, 115, 90 },
+      { 25, 25, 25 },
+    },
+    BLACK = {
+      { 255, 255, 255 },
+      { 25, 25, 25 },
+      { 25, 25, 25 },
+      { 25, 25, 25 },
+    },
+    BLUEMON = {
+      { 255, 255, 255 },
+      { 132, 148, 255 },
+      { 0, 8, 206 },
+      { 25, 25, 25 },
+    },
+    BROWNMON = {
+      { 255, 255, 255 },
+      { 239, 148, 82 },
+      { 140, 74, 41 },
+      { 25, 25, 25 },
+    },
+    CAVE = {
+      { 255, 255, 255 },
+      { 189, 66, 0 },
+      { 140, 115, 90 },
+      { 25, 25, 25 },
+    },
+    CELADON = {
+      { 255, 255, 255 },
+      { 41, 255, 41 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    CERULEAN = {
+      { 255, 255, 255 },
+      { 41, 66, 255 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    CINNABAR = {
+      { 255, 255, 255 },
+      { 255, 66, 66 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    CYANMON = {
+      { 255, 255, 255 },
+      { 132, 214, 255 },
+      { 0, 140, 255 },
+      { 25, 25, 25 },
+    },
+    FUCHSIA = {
+      { 255, 255, 255 },
+      { 255, 123, 123 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    GAMEFREAK = {
+      { 255, 255, 255 },
+      { 255, 156, 0 },
+      { 156, 156, 0 },
+      { 25, 25, 25 },
+    },
+    GRAYMON = {
+      { 255, 255, 255 },
+      { 165, 189, 82 },
+      { 90, 90, 41 },
+      { 25, 25, 25 },
+    },
+    GREENBAR = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 0, 255, 0 },
+      { 25, 25, 25 },
+    },
+    GREENMON = {
+      { 255, 255, 255 },
+      { 140, 255, 90 },
+      { 8, 181, 49 },
+      { 25, 25, 25 },
+    },
+    INDIGO = {
+      { 255, 255, 255 },
+      { 90, 66, 255 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    LAVENDER = {
+      { 255, 255, 255 },
+      { 206, 33, 255 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    LOGO1 = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 255, 0, 0 },
+      { 255, 0, 0 },
+    },
+    LOGO2 = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 58, 58, 206 },
+      { 0, 0, 140 },
+    },
+    MEWMON = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 255, 8, 8 },
+      { 25, 25, 25 },
+    },
+    PALLET = {
+      { 255, 255, 255 },
+      { 189, 140, 255 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    PEWTER = {
+      { 255, 255, 255 },
+      { 148, 148, 123 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    PIKACHUS_BEACH = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    PIKACHUS_BEACH_TITLE = {
+      { 255, 255, 255 },
+      { 74, 74, 74 },
+      { 255, 173, 0 },
+      { 25, 25, 25 },
+    },
+    PIKACHU_PORTRAIT = {
+      { 255, 255, 255 },
+      { 255, 148, 0 },
+      { 156, 58, 8 },
+      { 25, 25, 25 },
+    },
+    PINKMON = {
+      { 255, 255, 255 },
+      { 255, 123, 148 },
+      { 255, 0, 49 },
+      { 25, 25, 25 },
+    },
+    PURPLEMON = {
+      { 255, 255, 255 },
+      { 206, 123, 255 },
+      { 156, 0, 181 },
+      { 25, 25, 25 },
+    },
+    REDBAR = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 255, 0, 0 },
+      { 25, 25, 25 },
+    },
+    REDMON = {
+      { 255, 255, 255 },
+      { 255, 140, 0 },
+      { 255, 0, 0 },
+      { 25, 25, 25 },
+    },
+    ROUTE = {
+      { 255, 255, 255 },
+      { 132, 255, 33 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    SAFFRON = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    SLOTS1 = {
+      { 255, 255, 255 },
+      { 206, 8, 255 },
+      { 255, 0, 0 },
+      { 25, 25, 25 },
+    },
+    SLOTS2 = {
+      { 255, 255, 255 },
+      { 255, 33, 156 },
+      { 255, 255, 0 },
+      { 25, 25, 25 },
+    },
+    SLOTS3 = {
+      { 255, 255, 255 },
+      { 66, 255, 0 },
+      { 255, 255, 0 },
+      { 25, 25, 25 },
+    },
+    SLOTS4 = {
+      { 255, 255, 255 },
+      { 0, 255, 255 },
+      { 255, 255, 0 },
+      { 25, 25, 25 },
+    },
+    TOWNMAP = {
+      { 255, 255, 255 },
+      { 0, 173, 255 },
+      { 82, 230, 0 },
+      { 8, 8, 8 },
+    },
+    VERMILION = {
+      { 255, 255, 255 },
+      { 255, 156, 0 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    VIRIDIAN = {
+      { 255, 255, 255 },
+      { 156, 255, 0 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    YELLOWBAR = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 255, 148, 0 },
+      { 25, 25, 25 },
+    },
+    YELLOWMON = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 230, 115, 0 },
+      { 25, 25, 25 },
+    },
+  },
+  order = {
+    "ROUTE",
+    "PALLET",
+    "VIRIDIAN",
+    "PEWTER",
+    "CERULEAN",
+    "LAVENDER",
+    "VERMILION",
+    "CELADON",
+    "FUCHSIA",
+    "CINNABAR",
+    "INDIGO",
+    "SAFFRON",
+    "TOWNMAP",
+    "LOGO1",
+    "LOGO2",
+    "0F",
+    "MEWMON",
+    "BLUEMON",
+    "REDMON",
+    "CYANMON",
+    "PURPLEMON",
+    "BROWNMON",
+    "GREENMON",
+    "PINKMON",
+    "YELLOWMON",
+    "GRAYMON",
+    "SLOTS1",
+    "SLOTS2",
+    "SLOTS3",
+    "SLOTS4",
+    "BLACK",
+    "GREENBAR",
+    "YELLOWBAR",
+    "REDBAR",
+    "BADGE",
+    "CAVE",
+    "GAMEFREAK",
+    "PIKACHUS_BEACH",
+    "PIKACHU_PORTRAIT",
+    "PIKACHUS_BEACH_TITLE",
+  },
+  palettes = {
+    ["0F"] = {
+      { 255, 255, 247 },
+      { 197, 165, 247 },
+      { 90, 165, 247 },
+      { 25, 16, 16 },
+    },
+    BADGE = {
+      { 255, 255, 247 },
+      { 165, 123, 90 },
+      { 181, 173, 165 },
+      { 49, 49, 49 },
+    },
+    BLACK = {
+      { 255, 255, 247 },
+      { 49, 49, 49 },
+      { 49, 49, 49 },
+      { 49, 49, 49 },
+    },
+    BLUEMON = {
+      { 255, 255, 247 },
+      { 173, 181, 255 },
+      { 74, 82, 165 },
+      { 49, 49, 49 },
+    },
+    BROWNMON = {
+      { 255, 255, 247 },
+      { 214, 189, 148 },
+      { 148, 115, 82 },
+      { 49, 49, 49 },
+    },
+    CAVE = {
+      { 255, 255, 247 },
+      { 165, 123, 90 },
+      { 181, 173, 165 },
+      { 49, 49, 49 },
+    },
+    CELADON = {
+      { 255, 255, 247 },
+      { 181, 255, 181 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    CERULEAN = {
+      { 255, 255, 247 },
+      { 181, 189, 255 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    CINNABAR = {
+      { 255, 255, 247 },
+      { 255, 123, 115 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    CYANMON = {
+      { 255, 255, 247 },
+      { 214, 230, 255 },
+      { 58, 197, 230 },
+      { 49, 49, 49 },
+    },
+    FUCHSIA = {
+      { 255, 255, 247 },
+      { 255, 214, 214 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    GAMEFREAK = {
+      { 255, 255, 247 },
+      { 230, 197, 115 },
+      { 165, 165, 90 },
+      { 49, 49, 49 },
+    },
+    GRAYMON = {
+      { 255, 255, 247 },
+      { 206, 206, 148 },
+      { 132, 132, 115 },
+      { 49, 49, 49 },
+    },
+    GREENBAR = {
+      { 255, 255, 247 },
+      { 255, 255, 156 },
+      { 0, 173, 0 },
+      { 49, 49, 49 },
+    },
+    GREENMON = {
+      { 255, 255, 247 },
+      { 197, 230, 148 },
+      { 107, 173, 123 },
+      { 49, 49, 49 },
+    },
+    INDIGO = {
+      { 255, 255, 247 },
+      { 140, 140, 206 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    LAVENDER = {
+      { 255, 255, 247 },
+      { 222, 189, 239 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    LOGO1 = {
+      { 255, 255, 247 },
+      { 247, 247, 140 },
+      { 173, 0, 33 },
+      { 173, 0, 33 },
+    },
+    LOGO2 = {
+      { 255, 255, 247 },
+      { 247, 247, 140 },
+      { 148, 148, 197 },
+      { 58, 58, 132 },
+    },
+    MEWMON = {
+      { 255, 255, 247 },
+      { 255, 247, 181 },
+      { 222, 132, 132 },
+      { 49, 49, 49 },
+    },
+    PALLET = {
+      { 255, 255, 247 },
+      { 230, 222, 255 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    PEWTER = {
+      { 255, 255, 247 },
+      { 189, 189, 181 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    PIKACHUS_BEACH = {
+      { 255, 255, 247 },
+      { 255, 247, 181 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    PIKACHUS_BEACH_TITLE = {
+      { 255, 255, 247 },
+      { 132, 132, 132 },
+      { 255, 206, 74 },
+      { 49, 49, 49 },
+    },
+    PIKACHU_PORTRAIT = {
+      { 255, 255, 247 },
+      { 230, 189, 74 },
+      { 148, 115, 82 },
+      { 49, 49, 49 },
+    },
+    PINKMON = {
+      { 255, 255, 247 },
+      { 255, 197, 214 },
+      { 255, 148, 173 },
+      { 49, 49, 49 },
+    },
+    PURPLEMON = {
+      { 255, 255, 247 },
+      { 222, 181, 247 },
+      { 181, 123, 189 },
+      { 49, 49, 49 },
+    },
+    REDBAR = {
+      { 255, 255, 247 },
+      { 255, 255, 156 },
+      { 214, 74, 49 },
+      { 49, 49, 49 },
+    },
+    REDMON = {
+      { 255, 255, 247 },
+      { 255, 197, 90 },
+      { 214, 74, 49 },
+      { 49, 49, 49 },
+    },
+    ROUTE = {
+      { 255, 255, 247 },
+      { 189, 214, 156 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    SAFFRON = {
+      { 255, 255, 247 },
+      { 255, 255, 156 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    SLOTS1 = {
+      { 255, 255, 247 },
+      { 222, 181, 247 },
+      { 214, 74, 49 },
+      { 49, 49, 49 },
+    },
+    SLOTS2 = {
+      { 255, 255, 247 },
+      { 255, 189, 214 },
+      { 239, 239, 66 },
+      { 49, 49, 49 },
+    },
+    SLOTS3 = {
+      { 255, 255, 247 },
+      { 189, 255, 165 },
+      { 239, 239, 66 },
+      { 49, 49, 49 },
+    },
+    SLOTS4 = {
+      { 255, 255, 247 },
+      { 189, 239, 255 },
+      { 239, 239, 66 },
+      { 49, 49, 49 },
+    },
+    TOWNMAP = {
+      { 255, 255, 247 },
+      { 165, 214, 255 },
+      { 140, 189, 82 },
+      { 25, 16, 16 },
+    },
+    VERMILION = {
+      { 255, 255, 247 },
+      { 255, 206, 132 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    VIRIDIAN = {
+      { 255, 255, 247 },
+      { 214, 255, 173 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    YELLOWBAR = {
+      { 255, 255, 247 },
+      { 255, 255, 156 },
+      { 230, 189, 74 },
+      { 49, 49, 49 },
+    },
+    YELLOWMON = {
+      { 255, 255, 247 },
+      { 255, 255, 156 },
+      { 230, 189, 74 },
+      { 49, 49, 49 },
+    },
+  },
+  pokemon = {
+    ABRA = "YELLOWMON",
+    AERODACTYL = "GRAYMON",
+    ALAKAZAM = "YELLOWMON",
+    ARBOK = "PURPLEMON",
+    ARCANINE = "REDMON",
+    ARTICUNO = "BLUEMON",
+    BEEDRILL = "YELLOWMON",
+    BELLSPROUT = "GREENMON",
+    BLASTOISE = "CYANMON",
+    BULBASAUR = "GREENMON",
+    BUTTERFREE = "CYANMON",
+    CATERPIE = "GREENMON",
+    CHANSEY = "PINKMON",
+    CHARIZARD = "REDMON",
+    CHARMANDER = "REDMON",
+    CHARMELEON = "REDMON",
+    CLEFABLE = "PINKMON",
+    CLEFAIRY = "PINKMON",
+    CLOYSTER = "GRAYMON",
+    CUBONE = "GRAYMON",
+    DEWGONG = "BLUEMON",
+    DIGLETT = "BROWNMON",
+    DITTO = "GRAYMON",
+    DODRIO = "BROWNMON",
+    DODUO = "BROWNMON",
+    DRAGONAIR = "BLUEMON",
+    DRAGONITE = "BROWNMON",
+    DRATINI = "GRAYMON",
+    DROWZEE = "YELLOWMON",
+    DUGTRIO = "BROWNMON",
+    EEVEE = "GRAYMON",
+    EKANS = "PURPLEMON",
+    ELECTABUZZ = "YELLOWMON",
+    ELECTRODE = "YELLOWMON",
+    EXEGGCUTE = "PINKMON",
+    EXEGGUTOR = "GREENMON",
+    FARFETCHD = "BROWNMON",
+    FEAROW = "BROWNMON",
+    FLAREON = "REDMON",
+    GASTLY = "PURPLEMON",
+    GENGAR = "PURPLEMON",
+    GEODUDE = "GRAYMON",
+    GLOOM = "REDMON",
+    GOLBAT = "BLUEMON",
+    GOLDEEN = "REDMON",
+    GOLDUCK = "CYANMON",
+    GOLEM = "GRAYMON",
+    GRAVELER = "GRAYMON",
+    GRIMER = "PURPLEMON",
+    GROWLITHE = "BROWNMON",
+    GYARADOS = "BLUEMON",
+    HAUNTER = "PURPLEMON",
+    HITMONCHAN = "BROWNMON",
+    HITMONLEE = "BROWNMON",
+    HORSEA = "CYANMON",
+    HYPNO = "YELLOWMON",
+    IVYSAUR = "GREENMON",
+    JIGGLYPUFF = "PINKMON",
+    JOLTEON = "YELLOWMON",
+    JYNX = "MEWMON",
+    KABUTO = "BROWNMON",
+    KABUTOPS = "BROWNMON",
+    KADABRA = "YELLOWMON",
+    KAKUNA = "YELLOWMON",
+    KANGASKHAN = "BROWNMON",
+    KINGLER = "REDMON",
+    KOFFING = "PURPLEMON",
+    KRABBY = "REDMON",
+    LAPRAS = "CYANMON",
+    LICKITUNG = "PINKMON",
+    MACHAMP = "GRAYMON",
+    MACHOKE = "GRAYMON",
+    MACHOP = "GRAYMON",
+    MAGIKARP = "REDMON",
+    MAGMAR = "REDMON",
+    MAGNEMITE = "GRAYMON",
+    MAGNETON = "GRAYMON",
+    MANKEY = "BROWNMON",
+    MAROWAK = "GRAYMON",
+    MEOWTH = "YELLOWMON",
+    METAPOD = "GREENMON",
+    MEW = "MEWMON",
+    MEWTWO = "MEWMON",
+    MOLTRES = "REDMON",
+    MR_MIME = "PINKMON",
+    MUK = "PURPLEMON",
+    NIDOKING = "PURPLEMON",
+    NIDOQUEEN = "BLUEMON",
+    NIDORAN_F = "BLUEMON",
+    NIDORAN_M = "PURPLEMON",
+    NIDORINA = "BLUEMON",
+    NIDORINO = "PURPLEMON",
+    NINETALES = "YELLOWMON",
+    ODDISH = "GREENMON",
+    OMANYTE = "BLUEMON",
+    OMASTAR = "BLUEMON",
+    ONIX = "GRAYMON",
+    PARAS = "REDMON",
+    PARASECT = "REDMON",
+    PERSIAN = "YELLOWMON",
+    PIDGEOT = "BROWNMON",
+    PIDGEOTTO = "BROWNMON",
+    PIDGEY = "BROWNMON",
+    PIKACHU = "YELLOWMON",
+    PINSIR = "BROWNMON",
+    POLIWAG = "BLUEMON",
+    POLIWHIRL = "BLUEMON",
+    POLIWRATH = "BLUEMON",
+    PONYTA = "REDMON",
+    PORYGON = "GRAYMON",
+    PRIMEAPE = "BROWNMON",
+    PSYDUCK = "YELLOWMON",
+    RAICHU = "YELLOWMON",
+    RAPIDASH = "REDMON",
+    RATICATE = "GRAYMON",
+    RATTATA = "GRAYMON",
+    RHYDON = "GRAYMON",
+    RHYHORN = "GRAYMON",
+    SANDSHREW = "BROWNMON",
+    SANDSLASH = "BROWNMON",
+    SCYTHER = "GREENMON",
+    SEADRA = "CYANMON",
+    SEAKING = "REDMON",
+    SEEL = "BLUEMON",
+    SHELLDER = "GRAYMON",
+    SLOWBRO = "PINKMON",
+    SLOWPOKE = "PINKMON",
+    SNORLAX = "PINKMON",
+    SPEAROW = "BROWNMON",
+    SQUIRTLE = "CYANMON",
+    STARMIE = "GRAYMON",
+    STARYU = "REDMON",
+    TANGELA = "BLUEMON",
+    TAUROS = "GRAYMON",
+    TENTACOOL = "CYANMON",
+    TENTACRUEL = "CYANMON",
+    VAPOREON = "CYANMON",
+    VENOMOTH = "PURPLEMON",
+    VENONAT = "PURPLEMON",
+    VENUSAUR = "GREENMON",
+    VICTREEBEL = "GREENMON",
+    VILEPLUME = "REDMON",
+    VOLTORB = "YELLOWMON",
+    VULPIX = "REDMON",
+    WARTORTLE = "CYANMON",
+    WEEDLE = "YELLOWMON",
+    WEEPINBELL = "GREENMON",
+    WEEZING = "PURPLEMON",
+    WIGGLYTUFF = "PINKMON",
+    ZAPDOS = "YELLOWMON",
+    ZUBAT = "BLUEMON",
+  },
+  source = "pokeyellow data/sgb/sgb_palettes.asm + data/pokemon/palettes.asm",
+}
@@ -11,8 +11,70 @@
 -- equivalent, kept for save compatibility: rows 1-4 also self-heal
 -- older saves (flag set before the port hid the ball) by hiding the
 -- leftover ball on the next interaction.
+--
+-- The room's two readables (data/events/hidden_events.asm,
+-- hidden_events_for CELADON_MANSION_ROOF_HOUSE):
+--   hidden_text_predef 3, 0 / 4, 0  PrintBlackboardLinkCableText, LinkCableHelp
+--   hidden_text_predef 3, 4         PrintNotebookText, TMNotebook
+-- tools/extract/field.py only parses `hidden_event` rows, so no
+-- hidden_text_predef row reaches data/generated/field.lua and both tiles
+-- were dead A presses (#391).  Same hook shape as the bedroom SNES in
+-- data/scripts/flavor/reds_house_2f.lua (#135).  hidden_text_predef puts
+-- the predef id in the facing byte, so neither tile gates on facing.
+
+local Menu = require("src.ui.Menu")
+local TextBox = require("src.render.TextBox")
+
+-- TMNotebookText (data/text/text_2.asm) has no leading underscore, so the
+-- extractor never collects it and the pamphlet's text is inlined.
+local TM_NOTEBOOK_TEXT = "It's a pamphlet\non TMs.\f...\f"
+  .. "There are 50 TMs\nin all.\f"
+  .. "There are also 5\nHMs that can be\vused repeatedly.\f"
+  .. "SILPH CO."
+
+-- LinkCableHelp (engine/events/hidden_events/school_blackboard.asm):
+-- HowToLinkText's four headings in the 15x10 box at the top left; picking
+-- a heading prints its LinkCableInfoText and returns to the menu, B or
+-- STOP READING closes.
+local LINK_HEADINGS = { "HOW TO LINK", "COLOSSEUM", "TRADE CENTER" }
+
+local function linkCableHelp(game)
+  local text = game.data.text or {}
+  local items, showMenu, askHeading
+  function showMenu()
+    game.stack:push(Menu.new(game, items,
+      { tx = 0, ty = 0, tw = 15, th = 10, rowStep = 1 }))
+  end
+  function askHeading()
+    game.stack:push(TextBox.new(game,
+      text._LinkCableHelpText2 or "Which heading do\nyou want to read?",
+      showMenu))
+  end
+  items = {}
+  for i, label in ipairs(LINK_HEADINGS) do
+    items[i] = { label = label, onSelect = function()
+      game.stack:push(TextBox.new(game,
+        text["_LinkCableInfoText" .. i] or label, askHeading))
+    end }
+  end
+  items[#items + 1] = { label = "STOP READING" }
+  game.stack:push(TextBox.new(game,
+    text._LinkCableHelpText1 or "TRAINER TIPS\fUsing a Game Link\nCable",
+    askHeading))
+end

 return {
+  onInteract = function(game, ow, fx, fy)
+    if fy == 0 and (fx == 3 or fx == 4) then
+      linkCableHelp(game)
+      return true
+    end
+    if fx == 3 and fy == 4 then
+      game.stack:push(TextBox.new(game, TM_NOTEBOOK_TEXT))
+      return true
+    end
+    return false
+  end,
  talk = {
    TEXT_CELADONMANSION_ROOF_HOUSE_EEVEE_POKEBALL = {
      { "check_flag", "EVENT_GOT_EEVEE" },                     -- 1
@@ -22,11 +84,16 @@ return {
      { "jump", 13 },                                          -- 4
      { "give_pokemon", "EEVEE", 25 },                         -- 5
      { "jump_if_false", 12 },                                 -- 6 (party+box full)
-      { "play_sound", "Get_Item1" },                           -- 7 (GotMonText jingle)
-      { "show_text", "_GotMonText", { RAM = "EEVEE" } },       -- 8
-      { "set_flag", "EVENT_GOT_EEVEE" },                       -- 9
+      -- flag + HideObject before the jingle and GotMonText: the nickname
+      -- prompt inside give_pokemon and the text row both yield, and a
+      -- script that dies there would leave the EEVEE taken with the ball
+      -- still on the table and the gift claimable again (#426).  The row
+      -- count is unchanged, so the numeric jump targets still hold.
+      { "set_flag", "EVENT_GOT_EEVEE" },                       -- 7
      { "hide_object", "CELADON_MANSION_ROOF_HOUSE",
-        "CELADONMANSION_ROOF_HOUSE_EEVEE_POKEBALL" },          -- 10
+        "CELADONMANSION_ROOF_HOUSE_EEVEE_POKEBALL" },          -- 8
+      { "play_sound", "Get_Item1" },                           -- 9 (GotMonText jingle)
+      { "show_text", "_GotMonText", { RAM = "EEVEE" } },       -- 10
      { "jump", 13 },                                          -- 11
      { "show_text", "_BoxIsFullText" },                       -- 12
    },
@@ -1,10 +1,9 @@
 -- BikeShop (BIKE_SHOP) flavor dialogue
 -- Source: pokered/scripts/BikeShop.asm, pokered/text/BikeShop.asm
 --
-- TEXT_BIKESHOP_CLERK is skipped: it drives the actual voucher-for-bicycle
-- exchange (YesNoChoice purchase menu, GiveItem, RemoveItemByID, SetEvent
-- EVENT_GOT_BICYCLE). That is a significant standalone feature outside the
-- scope of these two flavor NPCs and is left unported here.
+-- TEXT_BIKESHOP_CLERK lives in data/scripts/story2.lua (M.BIKE_SHOP): the
+-- voucher exchange and the BICYCLE/CANCEL price window need more than
+-- command rows (#568).

 return {
  BIKE_SHOP = {
@@ -20,12 +19,15 @@ return {
      -- CheckEvent EVENT_GOT_BICYCLE ; jr nz, .gotBike
      -- before the player owns a bike -> TheseBikesAreExpensiveText
      -- after the player owns a bike  -> CoolBikeText
+      -- The check reads the bag, not the event: the port hands out the
+      -- BICYCLE itself (a key item, so it cannot be tossed), and that also
+      -- reads right on saves written before the clerk set the event (#567).
      TEXT_BIKESHOP_YOUNGSTER = {
        { "face_player" },                                            -- 1
-        { "check_flag", "EVENT_GOT_BICYCLE" },                        -- 2
-        { "jump_if_true", 5 },                                        -- 3
+        { "check_item", "BICYCLE" },                                  -- 2
+        { "jump_if_true", 6 },                                        -- 3
        { "show_text", "_BikeShopYoungsterTheseBikesAreExpensiveText" }, -- 4
-        { "jump", 6 },                                                -- 5
+        { "jump", "end" },                                            -- 5
        { "show_text", "_BikeShopYoungsterCoolBikeText" },            -- 6
      },
    },
@@ -1,33 +1,88 @@
-- Celadon Mansion 3F Game Designer (pokered/scripts/CeladonMansion3F.asm
-- CeladonMansion3FGameDesignerText): text_asm counts set bits in
-- wPokedexOwned and compares against NUM_POKEMON - 1 (discounts Mew).
-- If the player owns >= 150 species, shows the "completed" text
-- (originally followed by DisplayDiploma, which has no equivalent UI
-- in this port, so we just show the congratulatory text); otherwise
-- shows the normal encouragement text.
+-- Celadon Mansion 3F, the GAME FREAK dev floor
+-- (pokered+pokeyellow/scripts/CeladonMansion3F.asm).  Every dev's
+-- text_asm counts set bits in wPokedexOwned against NUM_POKEMON - 1
+-- (150, discounting Mew).  The game designer shows the diploma
+-- (DisplayDiploma -> src/ui/Diploma.lua) on a completed dex; Yellow's
+-- graphic artist then offers the printed copy (PrintDiploma, stood in
+-- by src/core/Printer.lua's PNG export like the Pokédex PRNT item).
+
+local function ownedCount(game)
+  local dex = game.save.pokedex
+  local owned = 0
+  if dex and dex.owned then
+    for _ in pairs(dex.owned) do owned = owned + 1 end
+  end
+  return owned
+end
+
 return {
  CELADON_MANSION_3F = {
    talk = {
      TEXT_CELADONMANSION3F_GAME_DESIGNER = function(game, ow, npc, done)
        local t = game.data.text
-        local dex = game.save.pokedex
-        local owned = 0
-        if dex and dex.owned then
-          for _ in pairs(dex.owned) do
-            owned = owned + 1
-          end
-        end
-        -- NUM_POKEMON - 1 = 150 (discounts Mew, per pokered)
-        local label, fallback
-        if owned >= 150 then
-          label, fallback = "_CeladonMansion3FGameDesignerCompletedDexText",
-            "Wow! Excellent!\nYou completed\nyour POKeDEX!\nCongratulations!"
-        else
-          label, fallback = "_CeladonMansion3FGameDesignerText",
-            "Is that right?\nI'm the game\ndesigner!\nFilling up your\nPOKeDEX is tough,\nbut don't quit!\nWhen you finish,\ncome tell me!"
-        end
        local TextBox = require("src.render.TextBox")
-        game.stack:push(TextBox.new(game, t[label] or fallback, done))
+        if ownedCount(game) < 150 then
+          game.stack:push(TextBox.new(game,
+            t._CeladonMansion3FGameDesignerText
+            or "Is that right?\nI'm the game\ndesigner!\fFilling up your\nPOKéDEX is tough,\nbut don't quit!",
+            done))
+          return
+        end
+        game.stack:push(TextBox.new(game,
+          t._CeladonMansion3FGameDesignerCompletedDexText
+          or "Wow! Excellent!\nYou completed\nyour POKéDEX!\nCongratulations!",
+          function()
+            local Diploma = require("src.ui.Diploma")
+            game.stack:push(Diploma.new(game, function()
+              -- Yellow tags on the unlocked-printing line (CompletedDexText2)
+              local after = require("src.core.GameVersion").isYellow()
+                and (t._CeladonMansion3FGameDesignerCompletedDexText2
+                     or "You can print out\nyour diploma with\nthe GAME BOY\nPrinter!")
+                or nil
+              if after then
+                game.stack:push(TextBox.new(game, after, done))
+              else
+                done()
+              end
+            end))
+          end))
+      end,
+
+      TEXT_CELADONMANSION3F_GRAPHIC_ARTIST = function(game, ow, npc, done)
+        local t = game.data.text
+        local TextBox = require("src.render.TextBox")
+        local yellow = require("src.core.GameVersion").isYellow()
+        if not (yellow and ownedCount(game) >= 150) then
+          game.stack:push(TextBox.new(game,
+            t._CeladonMansion3FGraphicArtistText
+            or "I'm the graphic\nartist!\nI drew you!", done))
+          return
+        end
+        -- _CeladonMansion3FGraphicArtistText2: offer to print the diploma
+        game.stack:push(TextBox.new(game,
+          t._CeladonMansion3FGraphicArtistText2
+          or "I'm the graphic\nartist!\fShould I print\nyour diploma?",
+          function()
+            local ChoiceBox = require("src.ui.ChoiceBox")
+            game.stack:push(ChoiceBox.new(game, function(yes)
+              if not yes then
+                game.stack:push(TextBox.new(game,
+                  t._CeladonMansion3FGraphicArtistText3
+                  or "Oh. But it's a\nspecial diploma!", done))
+                return
+              end
+              local Printer = require("src.core.Printer")
+              local Diploma = require("src.ui.Diploma")
+              local Strings = require("src.core.Strings")
+              local saved, err = Printer.save("diploma", 160, 144, function()
+                Diploma.render(game)
+              end)
+              -- the PRNT stand-in always reports where the PNG landed
+              game.stack:push(TextBox.new(game, saved
+                and Strings("There you go!\fSaved as\n%s\vin the save\nfolder.", saved)
+                or Strings("Printer error!\n%s", tostring(err)), done))
+            end))
+          end))
      end,
    },
  },
@@ -35,13 +35,25 @@ local function middleAgedMan(game, ow, npc, done)
    -- .loop: print WhichBadgeText, then show the badge list menu again
    push(game, t._CeruleanBadgeHouseMiddleAgedManWhichBadgeText, function()
      local ListMenu = require("src.ui.ListMenu")
+      local Strings = require("src.core.Strings")
      local items = {}
      for _, id in ipairs(BADGE_ORDER) do
        local idef = game.data.items[id]
        items[#items + 1] = { label = idef and idef.name or id, value = id }
      end
+      -- PrintListMenuEntries prints ListMenuCancelText once it hits the
+      -- list's $FF terminator (home/list_menu.asm), so every
+      -- DisplayListMenuID list ends in an on-screen CANCEL row; picking it
+      -- takes DisplayListMenuIDLoop's ExitListMenu path, the same .done
+      -- exit as B (#569)
+      items[#items + 1] = { label = Strings("CANCEL") }
      local menu = ListMenu.new(game, "", items, {
        onChoose = function(item)
+          game.stack:pop()
+          if not item.value then
+            push(game, t._CeruleanBadgeHouseMiddleAgedManVisitAnyTimeText, done)
+            return
+          end
          push(game, t[BADGE_TEXT[item.value]], loop)
        end,
        onCancel = function()
@@ -3,6 +3,10 @@
 -- Both NPCs use text_asm with an hRandomAdd roll to pick one of several
 -- flavor lines (no flags, no branching outcome) -- ported as a weighted
 -- math.random pick each time the NPC is talked to.
+--
+-- Yellow renames Slowbro -> Electrode in the text labels (see
+-- tools/yellow_symbol_aliases.py); look up both so Red/Blue and Yellow
+-- share this script.

 local M = {}

@@ -12,6 +16,29 @@ local function push(game, ow, npc, done, text)
  game.stack:push(TextBox.new(game, text, done))
 end

+-- CeruleanCitySlowbroText / CeruleanCityElectrodeText
+-- cp 180 -> 76/256 chance of 1st; cp 120 -> 60/256 chance of 2nd;
+-- cp 60 -> 60/256 chance of 3rd; else 60/256 chance of 4th.
+local function talkMon(game, ow, npc, done)
+  local t = game.data.text
+  local roll = math.random(0, 255)
+  local text
+  if roll >= 180 then
+    text = t._CeruleanCitySlowbroTookASnoozeText
+        or t._CeruleanCityElectrodeTookASnoozeText
+  elseif roll >= 120 then
+    text = t._CeruleanCitySlowbroIsLoafingAroundText
+        or t._CeruleanCityElectrodeIsLoafingAroundText
+  elseif roll >= 60 then
+    text = t._CeruleanCitySlowbroTurnedAwayText
+        or t._CeruleanCityElectrodeTurnedAwayText
+  else
+    text = t._CeruleanCitySlowbroIgnoredOrdersText
+        or t._CeruleanCityElectrodeIgnoredOrdersText
+  end
+  push(game, ow, npc, done, text)
+end
+
 M.CERULEAN_CITY = {
  talk = {
    -- CeruleanCityCooltrainerF1Text (scripts/CeruleanCity.asm:362-393)
@@ -23,32 +50,20 @@ M.CERULEAN_CITY = {
      local text
      if roll >= 180 then
        text = t._CeruleanCityCooltrainerF1SlowbroUseSonicboomText
+            or t._CeruleanCityCooltrainerF1ElectrodeUseSonicboomText
      elseif roll >= 100 then
        text = t._CeruleanCityCooltrainerF1SlowbroPunchText
+            or t._CeruleanCityCooltrainerF1ElectrodePunchText
      else
        text = t._CeruleanCityCooltrainerF1SlowbroWithdrawText
+            or t._CeruleanCityCooltrainerF1ElectrodeWithdrawText
      end
      push(game, ow, npc, done, text)
    end,

-    -- CeruleanCitySlowbroText (scripts/CeruleanCity.asm:395-436)
-    -- cp 180 -> 76/256 chance of 1st; cp 120 -> 60/256 chance of 2nd;
-    -- cp 60 -> 60/256 chance of 3rd; else 60/256 chance of 4th.
-    TEXT_CERULEANCITY_SLOWBRO = function(game, ow, npc, done)
-      local t = game.data.text
-      local roll = math.random(0, 255)
-      local text
-      if roll >= 180 then
-        text = t._CeruleanCitySlowbroTookASnoozeText
-      elseif roll >= 120 then
-        text = t._CeruleanCitySlowbroIsLoafingAroundText
-      elseif roll >= 60 then
-        text = t._CeruleanCitySlowbroTurnedAwayText
-      else
-        text = t._CeruleanCitySlowbroIgnoredOrdersText
-      end
-      push(game, ow, npc, done, text)
-    end,
+    TEXT_CERULEANCITY_SLOWBRO = talkMon,
+    -- Yellow map object uses TEXT_CERULEANCITY_ELECTRODE
+    TEXT_CERULEANCITY_ELECTRODE = talkMon,
  },
 }

@@ -14,9 +14,9 @@ return {
      --   else               -> .WhatsLostIsLostText (player has TM_DIG)
      TEXT_CERULEANTRASHEDHOUSE_FISHING_GURU = {
        { "check_item", "TM_DIG" },
-        { "jump_if_true", 4 },
+        { "jump_if_true", 5 },
        { "show_text", "_CeruleanTrashedHouseFishingGuruTheyStoleATMText" },
-        { "jump", 5 },
+        { "jump", "end" },
        { "show_text", "_CeruleanTrashedHouseFishingGuruWhatsLostIsLostText" },
      },
    },
@@ -1,9 +1,8 @@
 -- Flavor talk scripts for CopycatsHouse2F (registry id COPYCATS_HOUSE_2F).
 -- Source: pokered/scripts/CopycatsHouse2F.asm, pokered/text/CopycatsHouse2F.asm
 --
-- TEXT_COPYCATSHOUSE2F_COPYCAT is already ported (with the POKE DOLL /
-- TM31 MIMIC trade) in data/scripts/story4.lua, so it is intentionally
-- omitted here.
+-- TEXT_COPYCATSHOUSE2F_COPYCAT (POKE DOLL -> TM31 MIMIC) lives in
+-- data/scripts/story4.lua.

 return {
  COPYCATS_HOUSE_2F = {
@@ -0,0 +1,80 @@
+-- Fuchsia City (pokered/scripts/FuchsiaCity.asm)
+--
+-- The exhibit signs are text_asm bodies: PrintText of a single text_far,
+-- then DisplayPokedex for the exhibited species.  The preview marks the
+-- species seen but not owned, same as the S.S. Anne passenger's Snorlax.
+--
+-- The fossil sign branches on the Mt. Moon fossil events.  The exhibit
+-- holds the fossil the player did NOT take: taking the Dome Fossil puts
+-- Omanyte on display, taking the Helix Fossil puts Kabuto.  With neither
+-- event set the sign only prints its undetermined line and no dex entry
+-- opens.
+--
+-- The other text pointers (city sign, Safari Game signs, mart/center/gym
+-- and warden signs, the four NPCs, the exhibited-mon FuchsiaCityPokemonText
+-- rows) are plain text_far wrappers that resolve through Data:resolveText,
+-- so they are not ported here.
+return {
+  FUCHSIA_CITY = {
+    talk = {
+      -- FuchsiaCityChanseySignText: PrintText(_FuchsiaCityChanseySignText),
+      -- then DisplayPokedex CHANSEY.
+      TEXT_FUCHSIACITY_CHANSEY_SIGN = {
+        { "show_text", "_FuchsiaCityChanseySignText" },
+        { "mark_seen", "CHANSEY" },
+        { "push_screen", "DexEntryMenu", "CHANSEY" },
+      },
+
+      -- FuchsiaCityVoltorbSignText: PrintText(_FuchsiaCityVoltorbSignText),
+      -- then DisplayPokedex VOLTORB.
+      TEXT_FUCHSIACITY_VOLTORB_SIGN = {
+        { "show_text", "_FuchsiaCityVoltorbSignText" },
+        { "mark_seen", "VOLTORB" },
+        { "push_screen", "DexEntryMenu", "VOLTORB" },
+      },
+
+      -- FuchsiaCityKangaskhanSignText: PrintText(_FuchsiaCityKangaskhanSignText),
+      -- then DisplayPokedex KANGASKHAN.
+      TEXT_FUCHSIACITY_KANGASKHAN_SIGN = {
+        { "show_text", "_FuchsiaCityKangaskhanSignText" },
+        { "mark_seen", "KANGASKHAN" },
+        { "push_screen", "DexEntryMenu", "KANGASKHAN" },
+      },
+
+      -- FuchsiaCitySlowpokeSignText: PrintText(_FuchsiaCitySlowpokeSignText),
+      -- then DisplayPokedex SLOWPOKE.
+      TEXT_FUCHSIACITY_SLOWPOKE_SIGN = {
+        { "show_text", "_FuchsiaCitySlowpokeSignText" },
+        { "mark_seen", "SLOWPOKE" },
+        { "push_screen", "DexEntryMenu", "SLOWPOKE" },
+      },
+
+      -- FuchsiaCityLaprasSignText: PrintText(_FuchsiaCityLaprasSignText),
+      -- then DisplayPokedex LAPRAS.
+      TEXT_FUCHSIACITY_LAPRAS_SIGN = {
+        { "show_text", "_FuchsiaCityLaprasSignText" },
+        { "mark_seen", "LAPRAS" },
+        { "push_screen", "DexEntryMenu", "LAPRAS" },
+      },
+
+      -- FuchsiaCityFossilSignText: CheckEvent EVENT_GOT_DOME_FOSSIL /
+      -- CheckEventReuseA EVENT_GOT_HELIX_FOSSIL pick the text and the
+      -- displayed entry; with neither set only the undetermined line prints.
+      TEXT_FUCHSIACITY_FOSSIL_SIGN = {
+        { "check_flag", "EVENT_GOT_DOME_FOSSIL" },                 -- 1
+        { "jump_if_true", 7 },                                     -- 2
+        { "check_flag", "EVENT_GOT_HELIX_FOSSIL" },                -- 3
+        { "jump_if_true", 11 },                                    -- 4
+        { "show_text", "_FuchsiaCityFossilSignUndeterminedText" }, -- 5
+        { "jump", "end" },                                         -- 6
+        { "show_text", "_FuchsiaCityFossilSignOmanyteText" },      -- 7
+        { "mark_seen", "OMANYTE" },                                -- 8
+        { "push_screen", "DexEntryMenu", "OMANYTE" },              -- 9
+        { "jump", "end" },                                         -- 10
+        { "show_text", "_FuchsiaCityFossilSignKabutoText" },       -- 11
+        { "mark_seen", "KABUTO" },                                 -- 12
+        { "push_screen", "DexEntryMenu", "KABUTO" },               -- 13
+      },
+    },
+  },
+}
@@ -85,6 +85,47 @@ return {
        alreadyGotLabel = "_GameCornerGentlemanCloselyWatchTheReelsText",
        alreadyGotFallback = "The trick is to\nwatch the reels\vclosely!",
      }),
+
+      -- Yellow keeps all three giveaways with the same events and amounts
+      -- but renames the objects and their text labels: FISHING_GURU ->
+      -- FISHING_GURU1, CLERK2 -> MIDDLE_AGED_MAN2, GENTLEMAN ->
+      -- FISHING_GURU2 (pokeyellow/scripts/GameCorner.asm).  The Red/Blue
+      -- keys above never match there, so Yellow needs its own three (#552).
+      TEXT_GAMECORNER_FISHING_GURU1 = coinGiver({
+        event = "EVENT_GOT_10_COINS",
+        amount = 10,
+        askLabel = "_GameCornerFishingGuru1WantToPlayText",
+        askFallback = "Kid, do you want\nto play?",
+        receivedLabel = "_GameCornerFishingGuru1Received10CoinsText",
+        coinCaseFullLabel = "_GameCornerFishingGuru1DontNeedMyCoinsText",
+        coinCaseFullFallback = "You don't need my\ncoins!",
+        alreadyGotLabel = "_GameCornerFishingGuru1WinsComeAndGoText",
+        alreadyGotFallback = "Wins seem to come\nand go.",
+      }),
+
+      TEXT_GAMECORNER_MIDDLE_AGED_MAN2 = coinGiver({
+        event = "EVENT_GOT_20_COINS_2",
+        amount = 20,
+        askLabel = "_GameCornerMiddleAgedMan2WantSomeCoinsText",
+        askFallback = "What's up? Want\nsome coins?",
+        receivedLabel = "_GameCornerMiddleAgedMan2Received20CoinsText",
+        coinCaseFullLabel = "_GameCornerMiddleAgedMan2YouHaveLotsOfCoinsText",
+        coinCaseFullFallback = "You have lots of\ncoins!",
+        alreadyGotLabel = "_GameCornerMiddleAgedMan2INeedMoreCoinsText",
+        alreadyGotFallback = "Darn! I need more\ncoins for the\vPOKéMON I want!",
+      }),
+
+      TEXT_GAMECORNER_FISHING_GURU2 = coinGiver({
+        event = "EVENT_GOT_20_COINS",
+        amount = 20,
+        askLabel = "_GameCornerFishingGuru2ThrowingMeOffText",
+        askFallback = "Hey, what? You're\nthrowing me off!\vHere are some\vcoins, shoo!",
+        receivedLabel = "_GameCornerFishingGuru2Received20CoinsText",
+        coinCaseFullLabel = "_GameCornerFishingGuru2YouGotYourOwnCoinsText",
+        coinCaseFullFallback = "You've got your\nown coins!",
+        alreadyGotLabel = "_GameCornerFishingGuru2CloselyWatchTheReelsText",
+        alreadyGotFallback = "The trick is to\nwatch the reels\vclosely!",
+      }),
    },
  },
 }
@@ -8,9 +8,9 @@ return {
      TEXT_LAVENDERMART_COOLTRAINER_M = {
        { "face_player" },
        { "check_flag", "EVENT_RESCUED_MR_FUJI" },
-        { "jump_if_true", 5 },
+        { "jump_if_true", 6 },
        { "show_text", "_LavenderMartCooltrainerMReviveText" },
-        { "jump", 6 },
+        { "jump", "end" },
        { "show_text", "_LavenderMartCooltrainerMNuggetText" },
      },
    },
@@ -13,9 +13,9 @@ M.MR_FUJIS_HOUSE = {
    TEXT_MRFUJISHOUSE_SUPER_NERD = {
      { "face_player" },                                                    -- 1
      { "check_flag", "EVENT_RESCUED_MR_FUJI" },                            -- 2
-      { "jump_if_true", 5 },                                                -- 3
+      { "jump_if_true", 6 },                                                -- 3
      { "show_text", "_MrFujisHouseSuperNerdMrFujiIsntHereText" },          -- 4
-      { "jump", 6 },                                                        -- 5
+      { "jump", "end" },                                                    -- 5
      { "show_text", "_MrFujisHouseSuperNerdMrFujiHadBeenPrayingText" },    -- 6
    },

@@ -25,9 +25,9 @@ M.MR_FUJIS_HOUSE = {
    TEXT_MRFUJISHOUSE_LITTLE_GIRL = {
      { "face_player" },                                                    -- 1
      { "check_flag", "EVENT_RESCUED_MR_FUJI" },                            -- 2
-      { "jump_if_true", 5 },                                                -- 3
+      { "jump_if_true", 6 },                                                -- 3
      { "show_text", "_MrFujisHouseLittleGirlThisIsMrFujisHouseText" },     -- 4
-      { "jump", 6 },                                                        -- 5
+      { "jump", "end" },                                                    -- 5
      { "show_text", "_MrFujisHouseLittleGirlPokemonAreNiceToHugText" },    -- 6
    },

@@ -1,15 +1,11 @@
 -- Pewter City flavor dialogue (pokered/scripts/PewterCity.asm).
 -- PewterCity_TextPointers text_asm bodies for the SUPER_NERD1 museum
-- guide, SUPER_NERD2 garden nerd, and the leaving-east YOUNGSTER.
+-- guide and SUPER_NERD2 garden nerd.
 --
-- The escort choreography (SUPER_NERD1 walking the player to the
-- museum, YOUNGSTER walking the player to the gym) is scripted NPC
-- movement + a wPewterCityCurScript state machine that steers the
-- player off-map; the YOUNGSTER's escort to the gym is handled on this
-- map by story5.lua's onStep gate at the east exit (before
-- EVENT_BEAT_BROCK), while the SUPER_NERD1 museum escort is not ported.
-- Here we only port the real YES/NO-branched flavor text these NPCs
-- speak when talked to.
+-- The YOUNGSTER's gym escort (talk + east-exit onStep) lives in
+-- story5.lua so the lockstep RLE walk is not overwritten by this
+-- flavor merge.  SUPER_NERD1's museum escort is not ported; only the
+-- YES/NO-branched flavor text is here.

 local M = {}

@@ -20,9 +16,13 @@ local function push(game, s, done)
  game.stack:push(TextBox.new(game, s, done))
 end

+-- PrintText on a text_end string returns with the box still drawn and
+-- YesNoChoice then draws the menu above it (InitYesNoTextBoxParameters,
+-- engine/menus/text_box.asm); no A press clears the question first.  Ride
+-- TextBox's opts.choice, the same as Commands.ask (#854).
 local function ask(game, s, cb)
-  local ChoiceBox = require("src.ui.ChoiceBox")
-  push(game, s, function() game.stack:push(ChoiceBox.new(game, cb)) end)
+  local TextBox = require("src.render.TextBox")
+  game.stack:push(TextBox.new(game, s, nil, { choice = cb }))
 end

 M.PEWTER_CITY = {
@@ -61,15 +61,6 @@ M.PEWTER_CITY = {
      end)
    end,

-    -- PewterCityYoungsterText (scripts/PewterCity.asm): the "follow
-    -- me" line the youngster says when the player is stopped from
-    -- leaving Pewter east before beating Brock; the actual gate/step
-    -- block is handled by story5.lua's onStep for this map.
-    TEXT_PEWTERCITY_YOUNGSTER = function(game, ow, npc, done)
-      local t = text(game)
-      push(game, t._PewterCityYoungsterYoureATrainerFollowMeText
-        or "You're a trainer\nright? BROCK's\nlooking for new\nchallengers!\nFollow me!", done)
-    end,
  },
 }

@@ -1,13 +1,21 @@
 -- pokered/scripts/PewterNidoranHouse.asm
 -- PewterNidoranHouseNidoranText: text_far _PewterNidoranHouseNidoranText, then
 -- text_asm plays the NIDORAN_M cry (PlayCry/WaitForSoundToFinish) before ending.
-- No sound-effect command exists in Commands.lua, so we port the dialogue line
-- only; the cry SFX is cosmetic and has no gameplay effect.
+-- play_cry only stashes ctx.pendingCry for the very next show_text row, so it
+-- has to sit immediately before that row (src/script/Commands.lua); the cry
+-- then sounds once the box has typed out, matching the asm's print-then-cry
+-- order.  Its waitForButton form keeps DisplayTextID's trailing
+-- WaitForTextScrollButtonPress -- PewterNidoranHouse_Script is
+-- `jp EnableAutoTextBoxDrawing`, which zeroes
+-- wDoNotWaitForButtonPressAfterDisplayingText -- so the box still holds until
+-- A/B.  The cry row was missing, leaving the NIDORAN silent (#247).
 return {
  PEWTER_NIDORAN_HOUSE = {
    talk = {
      TEXT_PEWTERNIDORANHOUSE_NIDORAN = {
        { "face_player" },
+        -- text_asm: ld a, NIDORAN_M / call PlayCry
+        { "play_cry", "NIDORAN_M", true },
        { "show_text", "_PewterNidoranHouseNidoranText" },
      },
    },
@@ -0,0 +1,22 @@
+-- Red's House 2F (pokered data/events/hidden_events.asm +
+-- engine/events/hidden_objects PrintRedSNESText).
+--
+-- The bedroom SNES is a hidden_event at (3, 5) with ANY_FACING that
+-- prints _RedBedroomSNESText.  field.py extracts OpenRedsPC on this map
+-- but skips PrintRedSNESText, so interaction was a no-op (#135).
+
+local TextBox = require("src.render.TextBox")
+
+return {
+  REDS_HOUSE_2F = {
+    -- hidden_events.asm:
+    --   hidden_event 3, 5, PrintRedSNESText, ANY_FACING
+    onInteract = function(game, ow, fx, fy)
+      if fx ~= 3 or fy ~= 5 then return false end
+      local text = game.data.text._RedBedroomSNESText
+        or "{PLAYER} is\nplaying the SNES!"
+      game.stack:push(TextBox.new(game, text))
+      return true
+    end,
+  },
+}
@@ -12,9 +12,9 @@ return {
      TEXT_ROUTE16GATE1F_GUARD = {
        { "face_player" },
        { "check_item", "BICYCLE" },
-        { "jump_if_true", 5 },
+        { "jump_if_true", 6 },
        { "show_text", "_Route16Gate1FGuardNoPedestriansAllowedText" },
-        { "jump", 6 },
+        { "jump", "end" },
        { "show_text", "_Route16Gate1FGuardCyclingRoadExplanationText" },
      },
    },
@@ -14,9 +14,9 @@ return {
      TEXT_ROUTE18GATE1F_GUARD = {
        { "face_player" },
        { "check_item", "BICYCLE" },
-        { "jump_if_true", 5 },
+        { "jump_if_true", 6 },
        { "show_text", "_Route18Gate1FGuardYouNeedABicycleText" },
-        { "jump", 6 },
+        { "jump", "end" },
        { "show_text", "_Route18Gate1FGuardCyclingRoadUphillText" },
      },
    },
@@ -28,7 +28,29 @@ local function badgeGuard(badge, passFlag)
  }
 end

+-- Route23SetVictoryRoadBoulders (pokered scripts/Route23.asm:8): every entry
+-- to Route 23 resets the Victory Road boulder puzzle behind you.  The 2F/3F
+-- switch events clear (so those barriers are closed again on the next floor
+-- load) and the boulder that fell through 3F's hole goes back upstairs:
+-- ShowObject TOGGLE_VICTORY_ROAD_3F_BOULDER / HideObject
+-- TOGGLE_VICTORY_ROAD_2F_BOULDER, which are VICTORYROAD3F_BOULDER4 and
+-- VICTORYROAD2F_BOULDER3 (data/maps/toggleable_objects.asm).  1F's event is
+-- reset by the Indigo Plateau lobby and by Victory Road 2F, not here.  This
+-- is what makes the puzzle "completely reset" on a return trip (#258).
+-- onEnter is the port's BIT_CUR_MAP_LOADED_2 equivalent: setMap runs it on
+-- every map entry, connection crossings included, like EnterMap.
 M.ROUTE_23 = {
+  onEnter = function(game, ow)
+    local f = game.save.flags
+    f.EVENT_VICTORY_ROAD_2_BOULDER_ON_SWITCH1 = nil
+    f.EVENT_VICTORY_ROAD_2_BOULDER_ON_SWITCH2 = nil
+    f.EVENT_VICTORY_ROAD_3_BOULDER_ON_SWITCH1 = nil
+    f.EVENT_VICTORY_ROAD_3_BOULDER_ON_SWITCH2 = nil
+    local Commands = require("src.script.Commands")
+    local ctx = { save = game.save, overworld = ow, game = game }
+    Commands.show_object(ctx, "VICTORY_ROAD_3F", "VICTORYROAD3F_BOULDER4")
+    Commands.hide_object(ctx, "VICTORY_ROAD_2F", "VICTORYROAD2F_BOULDER3")
+  end,
  talk = {
    -- Route23Guard1Text: EventFlagBit ..., EVENT_PASSED_EARTHBADGE_CHECK
    -- -> wWhichBadge = EARTHBADGE
@@ -12,9 +12,9 @@ return {
      TEXT_SILPHCO10F_SILPH_WORKER_F = {
        { "face_player" },
        { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 5 },
+        { "jump_if_true", 6 },
        { "show_text", "_SilphCo10FSilphWorkerFImScaredText" },
-        { "jump", 6 },
+        { "jump", "end" },
        { "show_text", "_SilphCo10FSilphWorkerFQuietAboutMyCryingText" },
      },
    },
@@ -10,9 +10,9 @@ return {
      --   not set: _SilphCo3FSilphWorkerMWhatShouldIDoText
      TEXT_SILPHCO3F_SILPH_WORKER_M = {
        { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 4 },
+        { "jump_if_true", 5 },
        { "show_text", "_SilphCo3FSilphWorkerMWhatShouldIDoText" },
-        { "jump", 5 },
+        { "jump", "end" },
        { "show_text", "_SilphCo3FSilphWorkerMYouSavedUsText" },
      },
    },
@@ -7,9 +7,9 @@ return {
      TEXT_SILPHCO4F_SILPH_WORKER_M = {
        {"face_player"},
        {"check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI"},
-        {"jump_if_true", 5},
+        {"jump_if_true", 6},
        {"show_text", "_SilphCo4FSilphWorkerMImHidingText"},
-        {"jump", 6},
+        {"jump", "end"},
        {"show_text", "_SilphCo4FSilphWorkerMTeamRocketIsGoneText"},
      },
    },
@@ -7,9 +7,9 @@ return {
      TEXT_SILPHCO5F_SILPH_WORKER_M = {
        {"face_player"},
        {"check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI"},
-        {"jump_if_true", 5},
+        {"jump_if_true", 6},
        {"show_text", "_SilphCo5FSilphWorkerMThatsYouRightText"},
-        {"jump", 6},
+        {"jump", "end"},
        {"show_text", "_SilphCo5FSilphWorkerMYoureOurHeroText"},
      },
    },
@@ -11,9 +11,9 @@ return {
      TEXT_SILPHCO6F_SILPH_WORKER_M1 = {
        { "face_player" },
        { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 5 },
+        { "jump_if_true", 6 },
        { "show_text", "_SilphCo6FSilphWorkerM1TookOverTheBuildingText" },
-        { "jump", 6 },
+        { "jump", "end" },
        { "show_text", "_SilphCo6FSilphWorkerM1BackToWorkText" },
      },

@@ -21,9 +21,9 @@ return {
      TEXT_SILPHCO6F_SILPH_WORKER_M2 = {
        { "face_player" },
        { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 5 },
+        { "jump_if_true", 6 },
        { "show_text", "_SilphCo6FSilphWorkerMHelpMePleaseText" },
-        { "jump", 6 },
+        { "jump", "end" },
        { "show_text", "_SilphCo6FSilphWorkerMWeGotEngagedText" },
      },

@@ -31,9 +31,9 @@ return {
      TEXT_SILPHCO6F_SILPH_WORKER_F1 = {
        { "face_player" },
        { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 5 },
+        { "jump_if_true", 6 },
        { "show_text", "_SilphCo6FSilphWorkerF1SuchACowardText" },
-        { "jump", 6 },
+        { "jump", "end" },
        { "show_text", "_SilphCo6FSilphWorkerF1HaveToMarryHimText" },
      },

@@ -41,9 +41,9 @@ return {
      TEXT_SILPHCO6F_SILPH_WORKER_F2 = {
        { "face_player" },
        { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 5 },
+        { "jump_if_true", 6 },
        { "show_text", "_SilphCo6FSilphWorkerF2TeamRocketConquerWorldText" },
-        { "jump", 6 },
+        { "jump", "end" },
        { "show_text", "_SilphCo6FSilphWorkerF2TeamRocketRanText" },
      },

@@ -51,9 +51,9 @@ return {
      TEXT_SILPHCO6F_SILPH_WORKER_M3 = {
        { "face_player" },
        { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 5 },
+        { "jump_if_true", 6 },
        { "show_text", "_SilphCo6FSilphWorkerM3TargetedSilphText" },
-        { "jump", 6 },
+        { "jump", "end" },
        { "show_text", "_SilphCo6FSilphWorkerM3WorkForSilphText" },
      },
    },
@@ -10,9 +10,9 @@ return {
      --   set: _SilphCo7FSilphWorkerM2CancelledMasterBallText
      TEXT_SILPHCO7F_SILPH_WORKER_M2 = {
        { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 4 },
+        { "jump_if_true", 5 },
        { "show_text", "_SilphCo7FSilphWorkerM2AfterTheMasterBallText" },
-        { "jump", 5 },
+        { "jump", "end" },
        { "show_text", "_SilphCo7FSilphWorkerM2CancelledMasterBallText" },
      },

@@ -22,9 +22,9 @@ return {
      --   set: _SilphCo7FSilphWorkerM3YouChasedOffTeamRocketText
      TEXT_SILPHCO7F_SILPH_WORKER_M3 = {
        { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 4 },
+        { "jump_if_true", 5 },
        { "show_text", "_SilphCo7FSilphWorkerM3ItWouldBeBadText" },
-        { "jump", 5 },
+        { "jump", "end" },
        { "show_text", "_SilphCo7FSilphWorkerM3YouChasedOffTeamRocketText" },
      },

@@ -34,9 +34,9 @@ return {
      --   set: _SilphCo7FSilphWorkerM4SafeAtLastText
      TEXT_SILPHCO7F_SILPH_WORKER_M4 = {
        { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 4 },
+        { "jump_if_true", 5 },
        { "show_text", "_SilphCo7FSilphWorkerM4ItsReallyDangerousHereText" },
-        { "jump", 5 },
+        { "jump", "end" },
        { "show_text", "_SilphCo7FSilphWorkerM4SafeAtLastText" },
      },
    },
@@ -10,9 +10,9 @@ return {
      --   set: _SilphCo8FSilphWorkerMThanksForSavingUsText
      TEXT_SILPHCO8F_SILPH_WORKER_M = {
        { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 4 },
+        { "jump_if_true", 5 },
        { "show_text", "_SilphCo8FSilphWorkerMSilphIsFinishedText" },
-        { "jump", 5 },
+        { "jump", "end" },
        { "show_text", "_SilphCo8FSilphWorkerMThanksForSavingUsText" },
      },
    },
@@ -5,19 +5,23 @@ return {
  SILPH_CO_9F = {
    talk = {
      -- SilphCo9FNurseText (pokered/scripts/SilphCo9F.asm):
-      -- before EVENT_BEAT_SILPH_CO_GIOVANNI: heals the party and shows
-      -- "You look tired..." then "Don't give up!"; after the event, just
-      -- says thanks. Nurse texts are not in data/generated/text.lua, so
-      -- the exact pokered/text/SilphCo9F.asm strings are used as literals.
+      -- before EVENT_BEAT_SILPH_CO_GIOVANNI: heals the party, white fade
+      -- (Delay3 between out/in; no Music_PkmnHealed), then "Don't give
+      -- up!"; after the event, just says thanks. Nurse texts are not in
+      -- data/generated/text.lua, so the exact pokered/text/SilphCo9F.asm
+      -- strings are used as literals.
      TEXT_SILPHCO9F_NURSE = {
-        { "face_player" },
-        { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 8 },
-        { "show_text", "You look tired!\nYou should take a\nquick nap!" },
-        { "heal_party" },
-        { "show_text", "Don't give up!" },
-        { "jump", 9 },
-        { "show_text", "Thank you so\nmuch!" },
+        { "face_player" },                                              -- 1
+        { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },                -- 2
+        { "jump_if_true", 11 },                                         -- 3
+        { "show_text", "You look tired!\nYou should take a\nquick nap!" }, -- 4
+        { "heal_party" },                                               -- 5
+        { "fade", "out", "white" },                                     -- 6
+        { "wait", 3 },                                                  -- 7  Delay3
+        { "fade", "in", "white" },                                      -- 8
+        { "show_text", "Don't give up!" },                              -- 9
+        { "jump", "end" },                                              -- 10
+        { "show_text", "Thank you so\nmuch!" },                         -- 11
      },
    },
  },
@@ -7,19 +7,19 @@
 -- CheckFightingMapTrainers/TalkToTrainer via the existing trainer
 -- system, and the item pickups carry no talk text of their own here.
 --
-- TEXT_SSANNE2FROOMS_GENTLEMAN3 also opens the POKéDEX entry for
-- SNORLAX after the text box (DisplayPokedex in the original), which
-- has no equivalent talk-script hook in this port (DexEntryMenu has
-- no done-callback the way other pushed UI states do) -- only the
-- flavor line is ported here.
+-- TEXT_SSANNE2FROOMS_GENTLEMAN3 opens SNORLAX's POKéDEX entry after its
+-- text box, like DisplayPokedex in the original. The preview marks it seen
+-- but does not mark it owned.
 return {
  SS_ANNE_2F_ROOMS = {
    talk = {
-      -- SSAnne2FRoomsGentleman3Text: PrintText(_SSAnne2FRoomsGentleman3Text)
-      -- (then DisplayPokedex SNORLAX -- not ported, see note above)
+      -- SSAnne2FRoomsGentleman3Text: PrintText(_SSAnne2FRoomsGentleman3Text),
+      -- then DisplayPokedex SNORLAX.
      TEXT_SSANNE2FROOMS_GENTLEMAN3 = {
        { "face_player" },
        { "show_text", "_SSAnne2FRoomsGentleman3Text" },
+        { "mark_seen", "SNORLAX" },
+        { "push_screen", "DexEntryMenu", "SNORLAX" },
      },

      -- SSAnne2FRoomsGentleman4Text: PrintText(_SSAnne2FRoomsGentleman4Text)
@@ -23,9 +23,13 @@ local function push(game, s, done)
  game.stack:push(TextBox.new(game, s, done))
 end

+-- PrintText on a text_end string returns with the box still drawn and
+-- YesNoChoice then draws the menu above it (InitYesNoTextBoxParameters,
+-- engine/menus/text_box.asm); no A press clears the question first.  Ride
+-- TextBox's opts.choice, the same as Commands.ask (#854).
 local function ask(game, s, cb)
-  local ChoiceBox = require("src.ui.ChoiceBox")
-  push(game, s, function() game.stack:push(ChoiceBox.new(game, cb)) end)
+  local TextBox = require("src.render.TextBox")
+  game.stack:push(TextBox.new(game, s, nil, { choice = cb }))
 end

 M.VIRIDIAN_CITY = {
@@ -59,13 +63,17 @@ M.VIRIDIAN_CITY = {
    -- ViridianCityYoungster2CaterpieAndWeedleDescriptionText are
    -- defined without a leading underscore in pokered/text/ViridianCity.asm
    -- and aren't present in data/generated/text.lua, so we fall back to
-    -- the literal strings from pokered.
+    -- the literal strings from pokered.  Those fallbacks have to carry the
+    -- extractor's markers, not plain newlines: line -> \n, cont -> \v,
+    -- para -> \f.  Spelling cont/para as \n and \n\n put all six lines on
+    -- one page with nothing to wait on, so the whole speech scrolled past
+    -- without a button press (#250).
    TEXT_VIRIDIANCITY_YOUNGSTER2 = function(game, ow, npc, done)
      local t = text(game)
      ask(game, t._ViridianCityYoungster2YouWantToKnowAboutText
-        or "You want to know\nabout the 2 kinds\nof caterpillar\nPOKéMON?", function(yes)
+        or "You want to know\nabout the 2 kinds\vof caterpillar\vPOKéMON?", function(yes)
        if yes then
-          push(game, "CATERPIE has no\npoison, but\nWEEDLE does.\n\nWatch out for its\nPOISON STING!", done)
+          push(game, "CATERPIE has no\npoison, but\vWEEDLE does.\fWatch out for its\nPOISON STING!", done)
        else
          push(game, "Oh, OK then!", done)
        end
@@ -3,12 +3,16 @@
 return {
  VIRIDIAN_NICKNAME_HOUSE = {
    talk = {
-      -- ViridianNicknameHouseSpearowText: text_asm that shows the text
-      -- then plays a SPEAROW cry (PlayCry/WaitForSoundToFinish). The
-      -- cry playback isn't in the talk-script command vocabulary, so
-      -- only the flavor line is ported here.
+      -- ViridianNicknameHouseSpearowText: text_asm that PrintTexts the
+      -- line, then plays the SPEAROW cry (PlayCry/WaitForSoundToFinish)
+      -- before TextScriptEnd.  play_cry only arms the show_text row that
+      -- follows it, so the cry sounds once the box has typed out; its
+      -- waitForButton form keeps DisplayTextID's trailing
+      -- WaitForTextScrollButtonPress, so the box then holds until A/B like
+      -- any other NPC line rather than popping itself (#251).
      TEXT_VIRIDIANNICKNAMEHOUSE_SPEAROW = {
-        { "show_text", "_ViridianNicknameHouseSpearowText" },
+        { "play_cry", "SPEAROW", true },                      -- 1 PlayCry
+        { "show_text", "_ViridianNicknameHouseSpearowText" }, -- 2 PrintText
      },
    },
  },
@@ -0,0 +1,175 @@
+-- Viridian School House's two readables (data/events/hidden_events.asm,
+-- hidden_events_for VIRIDIAN_SCHOOL_HOUSE):
+--   hidden_text_predef 3, 0  PrintBlackboardLinkCableText, ViridianSchoolBlackboard
+--   hidden_text_predef 3, 4  PrintNotebookText, ViridianSchoolNotebook
+-- tools/extract/field.py only parses `hidden_event` rows, so neither
+-- hidden_text_predef row reaches data/generated/field.lua and both tiles
+-- were dead A presses (#503).  Same hook shape, and the same sibling asm
+-- file, as the Celadon roof house in data/scripts/celadon_eevee.lua (#391);
+-- hidden_text_predef spends the facing byte on the tx_pre id, so neither
+-- tile gates on facing.
+
+local Font = require("src.render.Font")
+local Theme = require("src.ui.Theme")
+local TextBox = require("src.render.TextBox")
+
+-- ViridianSchoolBlackboard (engine/events/hidden_events/school_blackboard.asm):
+-- StatusAilmentText1/2 are the two columns of the 12x8 box at the top left
+-- (hlcoord 0, 0 + `lb bc, 6, 10`); picking a status prints its
+-- ViridianBlackboardStatusPointers entry and jumps back to .blackboardLoop,
+-- QUIT or B falls through to .exitBlackboard.
+local STATUS_LABELS = {
+  { " SLP", "_ViridianBlackboardSleepText" },
+  { " PSN", "_ViridianBlackboardPoisonText" },
+  { " PAR", "_ViridianBlackboardPrlzText" },
+  { " BRN", "_ViridianBlackboardBurnText" },
+  { " FRZ", "_ViridianBlackboardFrozenText" },
+}
+
+-- The headings list is a two-column menu, which src/ui/Menu.lua does not do
+-- (it stacks one column), so the layout lives here (#591).  .blackboardLoop:
+-- TextBoxBorder at hlcoord 0, 0 with `lb bc, 6, 10` is the 12x8 box,
+-- StatusAilmentText1 (" SLP"/" PSN"/" PAR") is placed at hlcoord 1, 2 and
+-- StatusAilmentText2 (" BRN"/" FRZ"/" QUIT") at hlcoord 6, 2.  LEFT/RIGHT
+-- move wTopMenuItemX between those two columns and swap wMenuItemOffset
+-- between 0 and 3 while leaving wCurrentMenuItem (the row) alone; UP/DOWN
+-- are not in wMenuWatchedKeys, so they only slide the cursor and loop.
+local BOARD_LABELS = {}
+for i, row in ipairs(STATUS_LABELS) do BOARD_LABELS[i] = row[1] end
+BOARD_LABELS[#BOARD_LABELS + 1] = " QUIT"
+local BOARD_COL_X = { 1, 6 }
+local BOARD_ROW_Y = 2
+local BOARD_ROWS = 3
+
+local StatusBoard = {}
+StatusBoard.__index = StatusBoard
+
+function StatusBoard.new(game, onPick, onQuit)
+  return setmetatable({ game = game, col = 1, row = 1, labels = BOARD_LABELS,
+                        onPick = onPick, onQuit = onQuit }, StatusBoard)
+end
+
+-- flat index = pokered's wMenuItemOffset (0 or 3) + wCurrentMenuItem (0..2),
+-- so 1..5 are the statuses in ViridianBlackboardStatusPointers order and 6
+-- is QUIT
+function StatusBoard:selection()
+  return (self.col - 1) * BOARD_ROWS + self.row
+end
+
+function StatusBoard:update()
+  local input = self.game.input
+  if input:wasPressed("up") then
+    -- wMenuWrappingEnabled is never set here, so both ends are hard stops
+    if self.row > 1 then self.row = self.row - 1 end
+  elseif input:wasPressed("down") then
+    if self.row < BOARD_ROWS then self.row = self.row + 1 end
+  elseif input:wasPressed("left") then
+    self.col = 1
+  elseif input:wasPressed("right") then
+    self.col = 2
+  elseif input:wasPressed("a") or input:wasPressed("b") then
+    -- HandleMenuInput_ (home/window.asm) beeps for the PAD_A | PAD_B branch,
+    -- and B and QUIT share .exitBlackboard
+    require("src.core.Sound").play(self.game.data, "Press_AB")
+    local sel = self:selection()
+    if input:wasPressed("b") or sel > #STATUS_LABELS then
+      self.onQuit()
+    else
+      self.onPick(sel)
+    end
+  end
+end
+
+function StatusBoard:draw()
+  Font.drawBox(0, 0, 12, 8)
+  love.graphics.setColor(0, 0, 0, 1)
+  for i, label in ipairs(BOARD_LABELS) do
+    local col = i <= BOARD_ROWS and 1 or 2
+    local row = i - (col - 1) * BOARD_ROWS
+    Font.draw(label, BOARD_COL_X[col] * 8, (BOARD_ROW_Y + row - 1) * 8)
+  end
+  -- wTopMenuItemX equals the column PlaceString started at, so the cursor
+  -- covers the blank each label leads with
+  Font.drawCode(Theme.cursor, BOARD_COL_X[self.col] * 8,
+                (BOARD_ROW_Y + self.row - 1) * 8)
+  love.graphics.setColor(1, 1, 1, 1)
+end
+
+local function blackboard(game)
+  local text = game.data.text or {}
+  local openBoard
+  -- wCurrentMenuItem / wMenuItemOffset are zeroed once, above .blackboardLoop,
+  -- and nothing inside the loop clears them again: after a status blurb
+  -- `jp .blackboardLoop` comes back with the cursor still on the row and
+  -- column the player just picked.  One StatusBoard lives for the whole
+  -- reading and is re-pushed each pass, so only entering the blackboard
+  -- resets to the left column / top row (#591).
+  local board
+  -- .blackboardLoop reprints ViridianSchoolBlackboardText2 and only then
+  -- calls HandleMenuInput, so the prompt is on screen for exactly as long as
+  -- the headings list is.  That text ends in `done`, not `prompt`
+  -- (data/text/text_2.asm:646), so PrintText returns with the box still up
+  -- and never waits for a button: TextBox opts.stay holds it open under the
+  -- list and these callbacks pop the pair together (#591).
+  local function closeBoard()
+    game.stack:pop() -- the headings list
+    game.stack:pop() -- the held "Which heading" box under it
+  end
+  local function pick(i)
+    closeBoard()
+    game.stack:push(TextBox.new(game,
+      text[STATUS_LABELS[i][2]] or STATUS_LABELS[i][1], openBoard))
+  end
+  function openBoard()
+    game.stack:push(TextBox.new(game,
+      text._ViridianSchoolBlackboardText2 or "Which heading do\nyou want to read?",
+      nil, { stay = { onShown = function()
+        board = board or StatusBoard.new(game, pick, closeBoard)
+        game.stack:push(board)
+      end } }))
+  end
+  game.stack:push(TextBox.new(game,
+    text._ViridianSchoolBlackboardText1
+      or "The blackboard\ndescribes POKéMON\vSTATUS changes\vduring battles.",
+    openBoard))
+end
+
+-- ViridianSchoolNotebook (engine/events/hidden_events/school_notebooks.asm):
+-- pages 1-3 each end in TurnPageSchoolNotebook (TurnPageText + YesNoChoice)
+-- and NO stops the read; page 4 turns without asking and runs straight into
+-- page 5, the girl catching you at it.
+local function notebook(game)
+  local text = game.data.text or {}
+  local function page(n, after)
+    return TextBox.new(game, text["_ViridianSchoolNotebookText" .. n] or "", after)
+  end
+  local function turnPage(nextPage)
+    return function()
+      game.stack:push(TextBox.new(game, text._TurnPageText or "Turn the page?",
+        nil, { choice = function(yes)
+          if yes then game.stack:push(nextPage()) end
+        end }))
+    end
+  end
+  local function page5() return page(5) end
+  local function page4() return page(4, function() game.stack:push(page5()) end) end
+  local function page3() return page(3, turnPage(page4)) end
+  local function page2() return page(2, turnPage(page3)) end
+  game.stack:push(page(1, turnPage(page2)))
+end
+
+return {
+  VIRIDIAN_SCHOOL_HOUSE = {
+    onInteract = function(game, ow, fx, fy)
+      if fx == 3 and fy == 0 then
+        blackboard(game)
+        return true
+      end
+      if fx == 3 and fy == 4 then
+        notebook(game)
+        return true
+      end
+      return false
+    end,
+  },
+}
@@ -15,6 +15,7 @@ local files = {
  "data.scripts.flavor.cerulean_trashed_house",
  "data.scripts.flavor.copycats_house_1f",
  "data.scripts.flavor.copycats_house_2f",
+  "data.scripts.flavor.fuchsia_city",
  "data.scripts.flavor.game_corner",
  "data.scripts.flavor.lavender_cubone_house",
  "data.scripts.flavor.lavender_mart",
@@ -28,6 +29,7 @@ local files = {
  "data.scripts.flavor.pokemon_fan_club",
  "data.scripts.flavor.power_plant",
  "data.scripts.flavor.reds_house_1f",
+  "data.scripts.flavor.reds_house_2f",
  "data.scripts.flavor.route11_gate_2f",
  "data.scripts.flavor.route18_gate_2f",
  "data.scripts.flavor.route_12_gate_2f",
@@ -59,6 +61,7 @@ local files = {
  "data.scripts.flavor.victory_road_2f",
  "data.scripts.flavor.viridian_city",
  "data.scripts.flavor.viridian_nickname_house",
+  "data.scripts.flavor.viridian_school_house", -- #503
  "data.scripts.flavor.wardens_house",
 }

@@ -18,6 +18,26 @@ local M = {
  VIRIDIAN_GYM  = { city = "VIRIDIAN CITY",  leader = "GIOVANNI", badge = "EARTHBADGE" },
 }

+-- The originals' middle branch shared by every leader's text_asm: beaten
+-- but EVENT_GOT_TM* unset means the bag was full when the victory script
+-- ran GiveItem, so talking to the leader re-runs the ReceiveTM script.
+-- Returns true when the retry took over the talk.  A save from before
+-- #797 already holds the TM without the flag; treat the owned TM as
+-- received so those saves fall through to the advice text instead of
+-- collecting a second copy.
+local function retryTmGive(game, ow, victoryKey, done)
+  local reward = require("data.scripts.victories")[victoryKey]
+  if not (reward and reward.gotFlag) then return false end
+  if game.save.flags[reward.gotFlag] then return false end
+  local owned = game.save.inventory and game.save.inventory[reward.item] or 0
+  if owned > 0 then
+    game.save.flags[reward.gotFlag] = true
+    return false
+  end
+  ow:offerGymTm(reward, done)
+  return true
+end
+
 -- scripts/PewterGym.asm PewterGymBrockText (text_asm): CheckEvent
 -- EVENT_BEAT_BROCK branches his dialogue.  Before the badge he prints
 -- _PewterGymBrockPreBattleText and engages the leader battle
@@ -25,12 +45,14 @@ local M = {
 -- badge/TM34 rewards and EVENT_BEAT_BROCK come from
 -- data/scripts/victories.lua OPP_BROCK#1).  After the badge his
 -- .afterBeat branch prints _PewterGymBrockPostBattleAdviceText ("Go to
-- the GYM in CERULEAN...").  The original's middle branch (beat but
-- TM34 not yet handed over, CheckEventReuseA EVENT_GOT_TM34) is
-- unreachable in the port: the TM is granted with the victory.
+-- the GYM in CERULEAN...").  The middle branch (beat but TM34 not yet
+-- handed over, CheckEventReuseA EVENT_GOT_TM34 -> call
+-- PewterGymScriptReceiveTM34) retries the TM give when the bag was full
+-- at the victory (#797).
 M.PEWTER_GYM.talk = {
  TEXT_PEWTERGYM_BROCK = function(game, ow, npc, done)
    if game.save.flags.EVENT_BEAT_BROCK then
+      if retryTmGive(game, ow, "OPP_BROCK#1", done) then return end
      local TextBox = require("src.render.TextBox")
      game.stack:push(TextBox.new(game,
        game.data.text._PewterGymBrockPostBattleAdviceText
@@ -48,16 +70,17 @@ M.PEWTER_GYM.talk = {
 -- (engageTrainer shows that same pre-battle text via resolveText; the
 -- badge/TM rewards and the beat flag come from data/scripts/victories.lua)
 -- -- and once beaten print the post-battle advice text.  As with Brock,
-- the originals' middle branch (beaten but the TM not yet handed over,
-- CheckEventReuseA EVENT_GOT_TM*) is unreachable in the port: the TM is
-- granted with the victory.
+-- the middle branch (beaten but the TM not yet handed over,
+-- CheckEventReuseA EVENT_GOT_TM*) retries the TM give when the bag was
+-- full at the victory.
 -- afterAdvice, when given, takes over `done`: it is handed (game, ow, npc,
 -- done) and must call done() itself once whatever it's doing (e.g. a fade
 -- around a HideObject) finishes, rather than having it invoked
 -- automatically. Only Giovanni's farewell uses this.
-local function leaderTalk(beatFlag, adviceLabel, fallback, afterAdvice)
+local function leaderTalk(beatFlag, adviceLabel, fallback, afterAdvice, victoryKey)
  return function(game, ow, npc, done)
    if game.save.flags[beatFlag] then
+      if victoryKey and retryTmGive(game, ow, victoryKey, done) then return end
      local TextBox = require("src.render.TextBox")
      local finish = done
      if afterAdvice then
@@ -79,42 +102,42 @@ end
 M.CERULEAN_GYM.talk = {
  TEXT_CERULEANGYM_MISTY = leaderTalk("EVENT_BEAT_MISTY",
    "_CeruleanGymMistyTM11ExplanationText",
-    "TM11 teaches\nBUBBLEBEAM!"),
+    "TM11 teaches\nBUBBLEBEAM!", nil, "OPP_MISTY#1"),
 }

 -- scripts/VermilionGym.asm VermilionGymLTSurgeText .got_tm24_already
 M.VERMILION_GYM.talk = {
  TEXT_VERMILIONGYM_LT_SURGE = leaderTalk("EVENT_BEAT_LT_SURGE",
    "_VermilionGymLTSurgePostBattleAdviceText",
-    "A little word of\nadvice, kid!"),
+    "A little word of\nadvice, kid!", nil, "OPP_LT_SURGE#1"),
 }

 -- scripts/CeladonGym.asm CeladonGymErikaText .afterBeat
 M.CELADON_GYM.talk = {
  TEXT_CELADONGYM_ERIKA = leaderTalk("EVENT_BEAT_ERIKA",
    "_CeladonGymErikaPostBattleAdviceText",
-    "You are cataloging\nPOKéMON? I must\nsay I'm impressed."),
+    "You are cataloging\nPOKéMON? I must\nsay I'm impressed.", nil, "OPP_ERIKA#1"),
 }

 -- scripts/FuchsiaGym.asm FuchsiaGymKogaText .afterBeat
 M.FUCHSIA_GYM.talk = {
  TEXT_FUCHSIAGYM_KOGA = leaderTalk("EVENT_BEAT_KOGA",
    "_FuchsiaGymKogaPostBattleAdviceText",
-    "When afflicted by\nTOXIC, POKéMON\nsuffer more and\nmore as battle\nprogresses!"),
+    "When afflicted by\nTOXIC, POKéMON\nsuffer more and\nmore as battle\nprogresses!", nil, "OPP_KOGA#1"),
 }

 -- scripts/SaffronGym.asm SaffronGymSabrinaText .afterBeat
 M.SAFFRON_GYM.talk = {
  TEXT_SAFFRONGYM_SABRINA = leaderTalk("EVENT_BEAT_SABRINA",
    "_SaffronGymSabrinaPostBattleAdviceText",
-    "Everyone has\npsychic power!\nPeople just don't\nrealize it!"),
+    "Everyone has\npsychic power!\nPeople just don't\nrealize it!", nil, "OPP_SABRINA#1"),
 }

 -- scripts/CinnabarGym.asm CinnabarGymBlaineText .afterBeat
 M.CINNABAR_GYM.talk = {
  TEXT_CINNABARGYM_BLAINE = leaderTalk("EVENT_BEAT_BLAINE",
    "_CinnabarGymBlainePostBattleAdviceText",
-    "FIRE BLAST is the\nultimate fire\ntechnique!"),
+    "FIRE BLAST is the\nultimate fire\ntechnique!", nil, "OPP_BLAINE#1"),
 }

 -- scripts/ViridianGym.asm ViridianGymGiovanniText .afterBeat: after the
@@ -142,7 +165,7 @@ M.VIRIDIAN_GYM.talk = {
            "VIRIDIAN_GYM", "VIRIDIANGYM_GIOVANNI")
        end
      end, done))
-    end),
+    end, "OPP_GIOVANNI#3"),
 }

 return M
@@ -12,11 +12,18 @@
 -- different files can each add NPCs to the same map), and mod
 -- contributions from the map_scripts registry compose on top of it.

+local GameVersion = require("src.core.GameVersion")
 local MapScripts = require("src.script.MapScripts")

+-- OaksLab is a full Yellow rewrite (one Eevee ball + forced Pikachu);
+-- Red/Blue keep the three-starter choose flow.
+local oaksLab = GameVersion.isYellow()
+  and "data.scripts.oaks_lab_yellow"
+  or "data.scripts.oaks_lab"
+
 for _, mapEntry in ipairs({
  { "PALLET_TOWN", "data.scripts.pallet_town" },
-  { "OAKS_LAB", "data.scripts.oaks_lab" },
+  { "OAKS_LAB", oaksLab },
  { "REDS_HOUSE_1F", "data.scripts.reds_house" },
  { "CELADON_MANSION_ROOF_HOUSE", "data.scripts.celadon_eevee" },
 }) do
@@ -36,6 +43,19 @@ for _, file in ipairs({ "data.scripts.story", "data.scripts.story2",
  end
 end

+-- Yellow-only content on top of the shared tables (talk keys merge per
+-- TEXT constant): the Kanto-starter gift quests and Jessie & James.
+if GameVersion.isYellow() then
+  for _, file in ipairs({ "data.scripts.yellow_gifts",
+                          "data.scripts.yellow_jessie_james",
+                          "data.scripts.yellow_beach_house",
+                          "data.scripts.yellow_viridian_old_man" }) do
+    for mapId, mod in pairs(require(file)) do
+      MapScripts.attachBase(mapId, mod)
+    end
+  end
+end
+
 local M = {}

 function M.get(mapId)
@@ -6,7 +6,10 @@
 --   takes it ("I'll take this one, then!") and both balls disappear.
 --   Source: scripts/OaksLab.asm OaksLabCharmanderPokeBallText /
 --   OaksLabRivalTakePokeBallScript.
-- * Rival (object 1): before starter -> "gramps isn't around"; with
+-- * Leftover ball (after the pick): Oak turns and reads the last-mon
+--   line instead of re-offering the starter (OaksLabLastMonScript, #601).
+-- * Rival (object 1): before starter -> "go ahead and choose" once Oak
+--   has walked you in, else "gramps isn't around" (#218); with
 --   starter -> taunt + battle OPP_RIVAL1 with the counter-pick party
 --   (player Bulbasaur -> rival Charmander etc., parties 1/2/3 =
 --   Squirtle/Bulbasaur/Charmander in data/trainers/parties.asm);
@@ -19,82 +22,172 @@ local function starterBall(askText, species, choseFlag, ownBall,
                           rivalBallX, rivalBall)
  return {
    { "check_flag", "EVENT_GOT_STARTER" },        -- 1
-    { "jump_if_true", 20 },                       -- 2
+    { "jump_if_true", 22 },                       -- 2
    -- no picking until Oak has walked you in (OaksLabScript gating)
    { "check_flag", "EVENT_FOLLOWED_OAK_INTO_LAB" }, -- 3
-    { "jump_if_false", 20 },                      -- 4
+    { "jump_if_false", 25 },                      -- 4
    -- the Pokédex "new species" entry shows before the ask (predef
-    -- StarterDex ahead of OaksLabYouWant...Text)
-    { "push_screen", "DexEntryMenu", species },   -- 5
+    -- StarterDex ahead of OaksLabYouWant...Text).  StarterDex temporarily
+    -- sets the owned bits so ShowPokedexData prints height/weight/text;
+    -- forceOwned is that bypass without mutating save.pokedex.owned.
+    { "push_screen", "DexEntryMenu",
+      { species = species, forceOwned = true } }, -- 5
    { "ask", askText },                           -- 6
-    { "jump_if_false", 21 },                      -- 7
-    { "give_pokemon", species, 5 },               -- 8
-    { "set_flag", "EVENT_GOT_STARTER" },          -- 9
-    { "set_flag", choseFlag },                    -- 10
+    { "jump_if_false", "end" },                   -- 7
+    -- OaksLab.asm prints ReceivedMon then AddPartyMon (AskName lives
+    -- inside give_pokemon).  Show the received text first so the
+    -- nickname prompt follows "you got X", matching Gen1.
+    -- The received text carries sound_get_key_item (OaksLab.asm
+    -- OaksLabReceivedMonText); the jingle plays as the box opens
+    -- (same beat as the Yellow port's starter, #668).
+    { "play_sound", "Get_Key_Item" },                              -- 8
+    { "show_text", "_OaksLabReceivedMonText", { RAM = species } }, -- 9
+    { "give_pokemon", species, 5 },               -- 10
+    { "set_flag", "EVENT_GOT_STARTER" },          -- 11
+    { "set_flag", choseFlag },                    -- 12
    -- POKé BALLs are not handed out here in the original -- Oak gives
    -- them later, at OaksLabOak1Text's .give_poke_balls beat once the
    -- player has beaten the Route 22 rival (see TEXT_OAKSLAB_OAK1 below)
-    { "show_text", "_OaksLabReceivedMonText", { RAM = species } }, -- 11
-    { "hide_object", "OAKS_LAB", ownBall },       -- 12
+    { "hide_object", "OAKS_LAB", ownBall },       -- 13
    -- the rival walks to the countering ball (around the furniture)
-    { "move_npc_to", 1, rivalBallX, 4 },          -- 13
-    { "face_object", 1, "up" },                   -- 14
-    { "show_text", "_OaksLabRivalIllTakeThisOneText" },            -- 15
-    { "hide_object", "OAKS_LAB", rivalBall },     -- 16
+    { "move_npc_to", 1, rivalBallX, 4 },          -- 14
+    { "face_object", 1, "up" },                   -- 15
+    { "show_text", "_OaksLabRivalIllTakeThisOneText" },            -- 16
+    { "hide_object", "OAKS_LAB", rivalBall },     -- 17
+    { "play_sound", "Get_Key_Item" },             -- 18 (sound_get_key_item)
    { "show_text", "_OaksLabRivalReceivedMonText",
      { RAM = rivalBall == "OAKSLAB_CHARMANDER_POKE_BALL" and "CHARMANDER"
              or rivalBall == "OAKSLAB_SQUIRTLE_POKE_BALL" and "SQUIRTLE"
-              or "BULBASAUR" } },                 -- 17
-    { "jump", 21 },                               -- 18
-    { "jump", 21 },                               -- 19 (spacer)
-    { "show_text", "_OaksLabThoseArePokeBallsText" }, -- 20
+              or "BULBASAUR" } },                 -- 19
+    { "jump", "end" },                            -- 20
+    { "jump", "end" },                            -- 21 (spacer)
+    -- a leftover ball after the player's pick: Oak turns to face the
+    -- player and reads the last-mon line instead of re-offering the
+    -- starter (scripts/OaksLab.asm OaksLabSelectedPokeBallScript ->
+    -- OaksLabLastMonScript; #601).  The ROM's "#MON" ligature is spelled
+    -- out as Pokémon here.
+    { "face_object", 5, "down" },                 -- 22
+    { "show_text", "That's PROF.OAK's\nlast Pokémon!" }, -- 23
+    -- OaksLabLastMonScript ends at TextScriptEnd; the port used to fall
+    -- through into the pre-pick line below (#601 remnant, reported on #600)
+    { "jump", "end" },                            -- 24
+    { "show_text", "_OaksLabThoseArePokeBallsText" }, -- 25
  }
 end

 return {
  talk = {
-    -- Oak: accepts the parcel and hands over the Pokédex, then (once the
-    -- player has beaten the Route 22 rival) hands over the real POKé
-    -- BALLs (scripts/OaksLab.asm OaksLabOak1Text, simplified: no rival
-    -- recall / dex-rating / "pokemon can fight" / "around the world"
-    -- branches -- see docs/known-differences.md)
+    -- Oak: OaksLabOak1Text.  Parcel delivery kicks SCRIPT_OAKSLAB_RIVAL_
+    -- ARRIVES_AT_OAKS_REQUEST + OaksLabOakGivesPokedexScript (rival walk-
+    -- in, full Pokédex speech, rival exit, Route 22 arm).
    TEXT_OAKSLAB_OAK1 = {
-      { "face_player" },                                          -- 1
-      { "check_flag", "EVENT_GOT_OAKS_PARCEL" },                  -- 2
-      { "jump_if_false", 14 },                                    -- 3
-      { "check_flag", "EVENT_OAK_GOT_PARCEL" },                   -- 4
-      { "jump_if_true", 14 },                                     -- 5
-      { "show_text", "_OaksLabOak1DeliverParcelText" },           -- 6
-      { "take_item", "OAKS_PARCEL", 1 },                          -- 7
-      { "set_flag", "EVENT_OAK_GOT_PARCEL" },                     -- 8
-      { "show_text", "_OaksLabOak1PokemonAroundTheWorldText" },   -- 9
-      { "set_flag", "EVENT_GOT_POKEDEX" },                        -- 10
-      -- the Pokédex swaps Viridian's two old men (OaksLab.asm:602-606:
-      -- HideObject TOGGLE_LYING_OLD_MAN / ShowObject TOGGLE_OLD_MAN).
-      -- Until this ran, the walking man at (17,5) -- who owns the coffee
-      -- ask and the catch tutorial -- stayed OFF for the whole game
-      -- (toggleable_objects.asm seeds him OFF, the sleeper ON).
-      { "hide_object", "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN_SLEEPY" }, -- 11
-      { "show_object", "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN" },  -- 12
-      { "jump", 32 },                                             -- 13
-      { "check_flag", "EVENT_GOT_STARTER" },                      -- 14
-      { "jump_if_false", 29 },                                    -- 15
-      { "check_item", "POKE_BALL" },                              -- 16
-      { "jump_if_true", 27 },                                     -- 17
-      { "check_flag", "EVENT_BEAT_ROUTE22_RIVAL_1ST_BATTLE" },    -- 18
-      { "jump_if_false", 31 },                                    -- 19
-      { "check_flag", "EVENT_GOT_POKEBALLS_FROM_OAK" },           -- 20
-      { "jump_if_true", 27 },                                     -- 21
-      { "set_flag", "EVENT_GOT_POKEBALLS_FROM_OAK" },             -- 22
-      { "give_item", "POKE_BALL", 5, false },                     -- 23
-      { "show_text", "_OaksLabOak1ReceivedPokeballsText" },       -- 24
-      { "show_text", "_OaksLabGivePokeballsExplanationText" },    -- 25
-      { "jump", 32 },                                             -- 26
-      { "show_text", "_OaksLabOak1ComeSeeMeSometimesText" },      -- 27
-      { "jump", 32 },                                             -- 28
-      { "show_text", "_OaksLabOak1WhichPokemonDoYouWantText" },   -- 29
-      { "jump", 32 },                                             -- 30
-      { "show_text", "_OaksLabOak1RaiseYourYoungPokemonText" },   -- 31 (32 = end)
+      { "face_player" },
+      -- OaksLabOak1Text leads with the dex-rating branch (#600): with
+      -- EVENT_PALLET_AFTER_GETTING_POKEBALLS set (converted saves), or
+      -- 2+ species owned once the Pokédex is in hand, Oak asks how it is
+      -- coming and rates it (predef DisplayDexRating).  Red keeps the
+      -- GOT_POKEDEX gate that Yellow's copy of this text drops
+      -- (data/scripts/oaks_lab_yellow.lua).
+      { "check_flag", "EVENT_PALLET_AFTER_GETTING_POKEBALLS" },
+      { "jump_if_true", "dex_rating" },
+      { "check_dex_owned", 2 },
+      { "jump_if_false", "no_rating" },
+      { "check_flag", "EVENT_GOT_POKEDEX" },
+      { "jump_if_true", "dex_rating" },
+      { "label", "no_rating" },
+      { "check_item", "POKE_BALL" },
+      { "jump_if_true", "come_see" },
+      { "check_flag", "EVENT_BEAT_ROUTE22_RIVAL_1ST_BATTLE" },
+      { "jump_if_true", "give_balls" },
+      { "check_flag", "EVENT_GOT_POKEDEX" },
+      { "jump_if_true", "around_world" },
+      { "check_flag", "EVENT_BATTLED_RIVAL_IN_OAKS_LAB" },
+      { "jump_if_false", "pre_lab_battle" },
+      { "check_item", "OAKS_PARCEL" },
+      { "jump_if_false", "raise_young" },
+      -- OaksLabOak1Text.got_parcel → RivalArrives + OakGivesPokedex
+      { "show_text", "_OaksLabOak1DeliverParcelText" },
+      { "play_sound", "Get_Key_Item" },
+      { "show_text", "_OaksLabOak1ParcelThanksText" },
+      { "take_item", "OAKS_PARCEL", 1 },
+      { "stop_music" },
+      { "play_music", "Music_MeetRival" },
+      { "show_text", "_OaksLabRivalGrampsText" },
+      { "show_object", "OAKS_LAB", "OAKSLAB_RIVAL" },
+      -- OaksLabCalcRivalMovementScript: sprite map (8,11) → cell (4,7)
+      -- when the player stands below Oak (the usual desk talk).
+      { "place_npc", 1, 4, 7, "up" },
+      { "move_npc_to", 1, 4, 3 },
+      { "play_music", "Music_OaksLab" },
+      { "face_object", 1, "up" },
+      { "face_object", 5, "down" },
+      { "show_text", "_OaksLabRivalWhatDidYouCallMeForText" },
+      { "face_object", 1, "up" },
+      { "face_object", 5, "down" },
+      { "show_text", "_OaksLabOakIHaveARequestText" },
+      { "face_object", 1, "up" },
+      { "face_object", 5, "down" },
+      { "show_text", "_OaksLabOakMyInventionPokedexText" },
+      { "show_text", "_OaksLabOakGotPokedexText" },
+      { "play_sound", "Get_Key_Item" },
+      { "hide_object", "OAKS_LAB", "OAKSLAB_POKEDEX1" },
+      { "hide_object", "OAKS_LAB", "OAKSLAB_POKEDEX2" },
+      { "face_object", 1, "up" },
+      { "face_object", 5, "down" },
+      { "show_text", "_OaksLabOakThatWasMyDreamText" },
+      { "face_object", 1, "right" },
+      { "show_text", "_OaksLabRivalLeaveItAllToMeText" },
+      { "set_flag", "EVENT_GOT_POKEDEX" },
+      { "set_flag", "EVENT_OAK_GOT_PARCEL" },
+      { "hide_object", "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN_SLEEPY" },
+      { "show_object", "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN" },
+      { "stop_music" },
+      { "play_music", "Music_MeetRival" },
+      { "move_npc_to", 1, 4, 7 },
+      { "hide_object", "OAKS_LAB", "OAKSLAB_RIVAL" },
+      { "play_music", "Music_OaksLab" },
+      { "set_flag", "EVENT_1ST_ROUTE22_RIVAL_BATTLE" },
+      { "clear_flag", "EVENT_2ND_ROUTE22_RIVAL_BATTLE" },
+      { "set_flag", "EVENT_ROUTE22_RIVAL_WANTS_BATTLE" },
+      { "show_object", "ROUTE_22", "ROUTE22_RIVAL1" },
+      { "jump", "end" },
+
+      { "label", "raise_young" },
+      { "show_text", "_OaksLabOak1RaiseYourYoungPokemonText" },
+      { "jump", "end" },
+
+      { "label", "pre_lab_battle" },
+      { "check_flag", "EVENT_GOT_STARTER" },
+      { "jump_if_true", "can_fight" },
+      { "show_text", "_OaksLabOak1WhichPokemonDoYouWantText" },
+      { "jump", "end" },
+      { "label", "can_fight" },
+      { "show_text", "_OaksLabOak1YourPokemonCanFightText" },
+      { "jump", "end" },
+
+      { "label", "around_world" },
+      { "show_text", "_OaksLabOak1PokemonAroundTheWorldText" },
+      { "jump", "end" },
+
+      { "label", "give_balls" },
+      { "check_flag", "EVENT_GOT_POKEBALLS_FROM_OAK" },
+      { "jump_if_true", "come_see" },
+      { "set_flag", "EVENT_GOT_POKEBALLS_FROM_OAK" },
+      { "give_item", "POKE_BALL", 5, false },
+      { "show_text", "_OaksLabOak1ReceivedPokeballsText" },
+      { "show_text", "_OaksLabGivePokeballsExplanationText" },
+      { "jump", "end" },
+
+      { "label", "come_see" },
+      { "show_text", "_OaksLabOak1ComeSeeMeSometimesText" },
+      { "jump", "end" },
+
+      -- .HowIsYourPokedexComingText ends on `prompt` and OaksLabOak1Text
+      -- sets wDoNotWaitForButtonPressAfterDisplayingText, so the seen/owned
+      -- tally follows with no button wait (engine/events/pokedex_rating.asm)
+      { "label", "dex_rating" },
+      { "show_text", "_OaksLabOak1HowIsYourPokedexComingText" },
+      { "dex_rating" },
    },

    TEXT_OAKSLAB_CHARMANDER_POKE_BALL =
@@ -107,47 +200,76 @@ return {
      starterBall("_OaksLabYouWantBulbasaurText", "BULBASAUR", "EVENT_CHOSE_BULBASAUR",
                  "OAKSLAB_BULBASAUR_POKE_BALL", 6, "OAKSLAB_CHARMANDER_POKE_BALL"),

+    -- Talking to the rival only ever prints a line: the lab battle is a
+    -- coordinate trigger (OaksLabRivalChallengesPlayerScript, wYCoord == 6;
+    -- see onStep below), never a talk action.  The handler used to fall
+    -- through from the "looks stronger" taunt straight into start_battle,
+    -- so talking to Blue at the table launched the rival fight before the
+    -- player ever stepped onto the trigger (#219).  scripts/OaksLab.asm
+    -- OaksLabText8 branches text only:
+    --   * got starter, not yet battled -> _OaksLabRivalMyPokemonLooksStronger
+    --   * already battled -> _OaksLabRivalFedUpWithWaitingText (a Route 22
+    --     line; normally unreachable since the rival is hidden after the
+    --     lab battle in OaksLabRivalEndBattleScript)
+    --   * no starter yet -> the FOLLOWED_OAK pre-starter fork (#218)
    TEXT_OAKSLAB_RIVAL = {
-      { "face_player" },                                          -- 1
-      { "check_flag", "EVENT_GOT_STARTER" },                      -- 2
-      { "jump_if_false", 21 },                                    -- 3
-      { "check_flag", "EVENT_BATTLED_RIVAL_IN_OAKS_LAB" },        -- 4
-      { "jump_if_true", 19 },                                     -- 5
-      { "show_text", "_OaksLabRivalMyPokemonLooksStrongerText" }, -- 6
-      { "check_flag", "EVENT_CHOSE_BULBASAUR" },                  -- 7
-      { "jump_if_false", 11 },                                    -- 8
-      { "start_battle", "trainer", "OPP_RIVAL1", 3 },             -- 9  Charmander
-      { "jump", 16 },                                             -- 10
-      { "check_flag", "EVENT_CHOSE_SQUIRTLE" },                   -- 11
-      { "jump_if_false", 15 },                                    -- 12
-      { "start_battle", "trainer", "OPP_RIVAL1", 2 },             -- 13 Bulbasaur
-      { "jump", 16 },                                             -- 14
-      { "start_battle", "trainer", "OPP_RIVAL1", 1 },             -- 15 Squirtle
-      -- OaksLabRivalEndBattleScript: HealParty + flag, then exit either way
-      { "heal_party" },                                           -- 16
-      { "set_flag", "EVENT_BATTLED_RIVAL_IN_OAKS_LAB" },          -- 17
-      { "jump", 23 },                                             -- 18
-      { "show_text", "_OaksLabRivalFedUpWithWaitingText" },       -- 19
-      { "jump", "end" },                                          -- 20
-      { "show_text", "_OaksLabRivalGrampsIsntAroundText" },       -- 21
-      { "jump", "end" },                                          -- 22
-      -- win: sulk text then exit; loss: Rival1WinText already played in
-      -- battle (HandlePlayerBlackOut), so skip straight to the walk-out
-      { "jump_if_false", 25 },                                    -- 23
-      { "show_text", "_OaksLabRivalIPickedTheWrongPokemonText" }, -- 24
-      { "move_npc_to", 1, 4, 11 },                                -- 25
-      { "hide_object", "OAKS_LAB", "OAKSLAB_RIVAL" },             -- 26
+      { "face_player" },
+      { "check_flag", "EVENT_GOT_STARTER" },
+      { "jump_if_false", "pre_starter" },
+      { "check_flag", "EVENT_BATTLED_RIVAL_IN_OAKS_LAB" },
+      { "jump_if_true", "after_battle" },
+      -- has a starter, has not fought yet: just the taunt.  The battle is
+      -- the coordinate trigger in onStep, not this talk (#219)
+      { "show_text", "_OaksLabRivalMyPokemonLooksStrongerText" },
+      { "jump", "end" },
+
+      { "label", "after_battle" },
+      { "show_text", "_OaksLabRivalFedUpWithWaitingText" },
+      { "jump", "end" },
+
+      -- pre-starter fork (scripts/OaksLab.asm OaksLabText8 rival handler):
+      -- Oak has already escorted you in (three balls on the table) -> he
+      -- waves you on to choose; not yet escorted (very early game) -> the
+      -- "Gramps isn't around" line.  #218
+      { "label", "pre_starter" },
+      { "check_flag", "EVENT_FOLLOWED_OAK_INTO_LAB" },
+      { "jump_if_false", "gramps_gone" },
+      { "show_text", "_OaksLabRivalGoAheadAndChooseText" },
+      { "jump", "end" },
+
+      { "label", "gramps_gone" },
+      { "show_text", "_OaksLabRivalGrampsIsntAroundText" },
    },
  },

+  -- Saves that got the Pokédex before #106 never wrote objectToggles for
+  -- the table sprites; re-entering the lab applies the same HideObject
+  -- the gift script now does (OaksLab.asm OakGivesPokedex).
+  onEnter = function(game, ow)
+    if not (game.save.flags and game.save.flags.EVENT_GOT_POKEDEX) then
+      return
+    end
+    local Commands = require("src.script.Commands")
+    local ctx = { save = game.save, game = game, overworld = ow }
+    Commands.hide_object(ctx, "OAKS_LAB", "OAKSLAB_POKEDEX1")
+    Commands.hide_object(ctx, "OAKS_LAB", "OAKSLAB_POKEDEX2")
+  end,
+
  -- Oak stops you leaving without a starter; the rival stops you on
  -- the way out for the first battle (scripts/OaksLab.asm
  -- OaksLabScript8 / OaksLabRivalChallenge)
  onStep = function(game, ow, x, y)
    local flags = game.save.flags
-    -- Oak blocks the exit mats (4,11)/(5,11) until you take a starter
+    -- Oak stops you leaving without a starter at the bookshelf row (cell
+    -- y == 6): this is the same wYCoord == 6 coordinate script the rival
+    -- challenge just below uses (scripts/OaksLab.asm, both gated on
+    -- EVENT_GOT_STARTER), so Oak halts you level with the shelves, not one
+    -- corridor length later on the exit mat.  At y>=6 only the x=4,5
+    -- corridor is walkable and the up-push keeps the player above y=7, so
+    -- this only ever fires at y=6 in the corridor -- matching the rival
+    -- trigger's shape. (#232)
    if flags.EVENT_FOLLOWED_OAK_INTO_LAB and not flags.EVENT_GOT_STARTER
-       and y == 11 and (x == 4 or x == 5) then
+       and y >= 6 then
      ow.runner:run({
        { "show_text", "_OaksLabOakDontGoAwayYetText" },
        { "move_player", "up", 1 },
@@ -160,7 +282,12 @@ return {
       and y >= 6 then
      local rival = ow:npcByIndex(1)
      if not rival then return false end
+      -- OaksLabRivalChallengesPlayerScript swaps in the rival encounter
+      -- fanfare for the taunt/challenge exchange, same as the Yellow port
+      -- (oaks_lab_yellow.lua); it was silently dropped here (#596).
      local rows = {
+        { "stop_music" },
+        { "play_music", "Music_MeetRival" },
        { "show_text", "_OaksLabRivalIllTakeYouOnText" },         -- 1
      }
      -- the rival routes to a free cell beside the player
@@ -186,12 +313,27 @@ return {
      -- OaksLabRivalEndBattleScript: heal + flag on win or loss; no blackout
      table.insert(rows, { "heal_party" })
      table.insert(rows, { "set_flag", "EVENT_BATTLED_RIVAL_IN_OAKS_LAB" })
-      -- win: sulk text then exit; loss jumps to the walk-out (taunt was
-      -- already shown in-battle via Rival1WinText)
+      -- OaksLabRivalEndBattleScript: on WIN, print the "picked the wrong
+      -- POKéMON!" gloat, then BOTH win and loss print the shared exit line
+      -- _OaksLabRivalSmellYouLaterText ("OK! I'll make my POKéMON fight to
+      -- toughen it up!\012<PLAYER>! Gramps! Smell you later!") before Blue
+      -- marches out.  A loss skips only the gloat (that taunt was already
+      -- shown in-battle via Rival1WinText), never the exit line (#231).  The
+      -- jump_if_false convergence point is the exit line: base+6 indexes the
+      -- SmellYouLater row below, so WIN falls IPicked -> SmellYouLater and
+      -- LOSS jumps straight to SmellYouLater (both then walk-out + hide).
      table.insert(rows, { "jump_if_false", base + 6 })
      table.insert(rows, { "show_text", "_OaksLabRivalIPickedTheWrongPokemonText" })
+      table.insert(rows, { "show_text", "_OaksLabRivalSmellYouLaterText" })
+      -- OaksLabRivalStartsExitScript: parting shot, rival exit fanfare, then
+      -- walk out past the player.  The fanfare was dropped here (#683) -- the
+      -- parcel scene above already plays Music_MeetRival on both arrival and
+      -- departure (lines 144-146), and this exit should match (#596).
+      table.insert(rows, { "stop_music" })
+      table.insert(rows, { "play_music", "Music_MeetRival" })
      table.insert(rows, { "move_npc_to", 1, 4, 11 })
      table.insert(rows, { "hide_object", "OAKS_LAB", "OAKSLAB_RIVAL" })
+      table.insert(rows, { "play_music", "Music_OaksLab" })
      ow.runner:run(rows, { npc = rival })
      return true
    end
@@ -0,0 +1,314 @@
+-- Hand-ported from pret/pokeyellow scripts/OaksLab.asm.
+-- Yellow: one Eevee ball on the table.  Rival snatches it; Oak then
+-- gives the player the wild Pikachu he caught earlier (STARTER_PIKACHU).
+-- Object indices differ from Red (no Charmander/Squirtle/Bulbasaur balls):
+--   1 RIVAL (4,3), 2 EEVEE_POKE_BALL (7,3), 3 OAK1 (5,2),
+--   4-5 POKEDEX (2,1)/(3,1), 6 OAK2 (door), 7 GIRL, 8-9 SCIENTIST.
+--
+-- wRivalStarter rides in save.rivalStarter (RIVAL_STARTER_* 1 JOLTEON /
+-- 2 FLAREON / 3 VAPOREON): JOLTEON baseline at the snatch
+-- (OaksLabRivalTakesPokeballScript), FLAREON on a lab win / VAPOREON on
+-- a lab loss (OaksLabRivalEndBattleScript), and Route 22's first battle
+-- upgrades FLAREON back to JOLTEON (Route22Rival1AfterBattleScript).
+
+local OAK1 = 3
+local RIVAL = 1
+
+return {
+  talk = {
+    TEXT_OAKSLAB_OAK1 = {
+      { "face_player" },
+      -- Yellow's OaksLabOak1Text leads with the dex-rating branch: once
+      -- EVENT_PALLET_AFTER_GETTING_POKEBALLS is set (converted saves) or
+      -- 2+ species are owned, Oak asks how the Pokédex is coming and
+      -- rates it (predef DisplayDexRating)
+      { "check_flag", "EVENT_PALLET_AFTER_GETTING_POKEBALLS" },
+      { "jump_if_true", "dex_rating" },
+      { "check_dex_owned", 2 },
+      { "jump_if_true", "dex_rating" },
+      { "check_item", "POKE_BALL" },
+      { "jump_if_true", "come_see" },
+      { "check_flag", "EVENT_BEAT_ROUTE22_RIVAL_1ST_BATTLE" },
+      { "jump_if_true", "give_balls" },
+      { "check_flag", "EVENT_GOT_POKEDEX" },
+      { "jump_if_true", "around_world" },
+      { "check_flag", "EVENT_BATTLED_RIVAL_IN_OAKS_LAB" },
+      { "jump_if_false", "pre_lab_battle" },
+      { "check_item", "OAKS_PARCEL" },
+      { "jump_if_false", "raise_young" },
+      -- .DeliverParcelText: parcel handover, then the Pokédex scene
+      -- (OaksLabRivalArrivesAtOaksRequestScript -> OakGivesPokedexScript)
+      { "show_text", "_OaksLabOak1DeliverParcelText" },
+      { "play_sound", "Get_Key_Item" },
+      { "show_text", "_OaksLabOak1ParcelThanksText" },
+      { "take_item", "OAKS_PARCEL", 1 },
+      { "stop_music" },
+      { "play_music", "Music_MeetRival" },
+      { "show_text", "_OaksLabRivalGrampsText" },
+      -- callfar OaksLabPikachuMovementScript, before ShowObject (#1021)
+      { "pikachu_make_way" },
+      { "show_object", "OAKS_LAB", "OAKSLAB_RIVAL" },
+      { "place_npc", RIVAL, 4, 7, "up" },
+      { "move_npc_to", RIVAL, 4, 3 },
+      { "play_music", "Music_OaksLab" },
+      { "face_object", RIVAL, "up" },
+      { "face_object", OAK1, "down" },
+      -- Yellow opens with the rival bragging, not Red's "what did you
+      -- call me for" (OaksLabOakGivesPokedexScript text order)
+      { "show_text", "_OaksLabRivalMyPokemonHasGrownStrongerText" },
+      { "face_object", RIVAL, "up" },
+      { "face_object", OAK1, "down" },
+      { "show_text", "_OaksLabOakIHaveARequestText" },
+      { "face_object", RIVAL, "up" },
+      { "face_object", OAK1, "down" },
+      { "show_text", "_OaksLabOakMyInventionPokedexText" },
+      { "show_text", "_OaksLabOakGotPokedexText" },
+      { "play_sound", "Get_Key_Item" },
+      { "hide_object", "OAKS_LAB", "OAKSLAB_POKEDEX1" },
+      { "hide_object", "OAKS_LAB", "OAKSLAB_POKEDEX2" },
+      { "face_object", RIVAL, "up" },
+      { "face_object", OAK1, "down" },
+      { "show_text", "_OaksLabOakThatWasMyDreamText" },
+      { "face_object", RIVAL, "right" },
+      { "show_text", "_OaksLabRivalLeaveItAllToMeText" },
+      { "set_flag", "EVENT_GOT_POKEDEX" },
+      { "set_flag", "EVENT_OAK_GOT_PARCEL" },
+      -- OaksLabOakGivesPokedexScript: HideObject TOGGLE_LYING_OLD_MAN /
+      -- ShowObject TOGGLE_OLD_MAN_2 -- Yellow's tutorial old man stands
+      -- on the sleeper's cell (18,9); the Red/Blue walker OLD_MAN at
+      -- (17,5) never appears in Yellow (#617)
+      { "hide_object", "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN_SLEEPY" },
+      { "show_object", "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN2" },
+      { "stop_music" },
+      { "play_music", "Music_MeetRival" },
+      { "move_npc_to", RIVAL, 4, 7 },
+      { "hide_object", "OAKS_LAB", "OAKSLAB_RIVAL" },
+      { "play_music", "Music_OaksLab" },
+      { "set_flag", "EVENT_1ST_ROUTE22_RIVAL_BATTLE" },
+      { "clear_flag", "EVENT_2ND_ROUTE22_RIVAL_BATTLE" },
+      { "set_flag", "EVENT_ROUTE22_RIVAL_WANTS_BATTLE" },
+      { "show_object", "ROUTE_22", "ROUTE22_RIVAL1" },
+      { "jump", "end" },
+
+      { "label", "raise_young" },
+      -- Yellow: talk-to-it (starter Pikachu) instead of Red raise-young line.
+      { "show_text", "_OaksLabOak1YouShouldTalkToIt" },
+      { "jump", "end" },
+
+      { "label", "pre_lab_battle" },
+      { "check_flag", "EVENT_GOT_STARTER" },
+      { "jump_if_true", "can_fight" },
+      { "show_text", "_OaksLabOak1GoAheadItsYours" },
+      { "jump", "end" },
+      { "label", "can_fight" },
+      { "show_text", "_OaksLabOak1YourPokemonCanFightText" },
+      { "jump", "end" },
+
+      { "label", "around_world" },
+      { "show_text", "_OaksLabOak1PokemonAroundTheWorldText" },
+      { "jump", "end" },
+
+      { "label", "give_balls" },
+      { "check_flag", "EVENT_GOT_POKEBALLS_FROM_OAK" },
+      { "jump_if_true", "come_see" },
+      { "set_flag", "EVENT_GOT_POKEBALLS_FROM_OAK" },
+      { "give_item", "POKE_BALL", 5, false },
+      { "show_text", "_OaksLabOak1ReceivedPokeballsText" },
+      { "play_sound", "Get_Key_Item" },
+      { "show_text", "_OaksLabGivePokeballsExplanationText" },
+      { "jump", "end" },
+
+      { "label", "come_see" },
+      { "show_text", "_OaksLabOak1ComeSeeMeSometimesText" },
+      { "jump", "end" },
+
+      { "label", "dex_rating" },
+      { "show_text", "_OaksLabOak1HowIsYourPokedexComingText" },
+      { "dex_rating" },
+    },
+
+    -- OaksLabEeveePokeBallText / OaksLabRivalExclamationScript ->
+    -- OaksLabChoseStarterScript..OaksLabPlayerReceivesPikachuScript:
+    -- before Oak's choose speech the ball is just flavor; after it, the
+    -- rival "!"s, shoves the player off the table, snatches the ball,
+    -- then the player is walked over to Oak and handed Pikachu.
+    TEXT_OAKSLAB_EEVEE_POKE_BALL = function(game, ow, npc, done)
+      local flags = game.save.flags
+      if flags.EVENT_GOT_STARTER then
+        done()
+        return
+      end
+      if not flags.EVENT_OAK_ASKED_TO_CHOOSE_MON then
+        ow.runner:run({
+          { "show_text", "_OaksLabThatsAPokeball" },
+        }, { onDone = done })
+        return
+      end
+      local px, py = ow.player.cellX, ow.player.cellY
+      local rows = {
+        -- OaksLabRivalExclamationScript: "!" over the rival
+        { "emote", RIVAL, "shock" },
+      }
+      -- .RivalPushesPlayerAwayFromEeveeBall is DOWN then RIGHT x3 (the $07
+      -- bytes are Yellow's own step-right encoding, decoded by
+      -- engine/overworld/movement.asm Func_5288 -> Func_532b), and the
+      -- PAD_RIGHT x2 shove is NOT queued alongside it:
+      -- OaksLabRivalTakesPokeballScript .asm_1c564 polls every frame and
+      -- only simulates the pair once wNPCNumScriptedSteps reads 1 -- i.e.
+      -- as the rival begins the LAST byte, the step onto the tile the
+      -- player is standing on.  Starting both on one row had Red stroll
+      -- off the Eevee while the rival was still at the top of the table
+      -- (#559).
+      if py == 4 then
+        rows[#rows + 1] = { "walk_npc", RIVAL, { "down", "right", "right" } }
+        -- this one runs concurrently with the shove below
+        rows[#rows + 1] = { "walk_npc", RIVAL, { "right" }, { wait = false } }
+        rows[#rows + 1] = { "face_player_dir", "left" }
+        rows[#rows + 1] = { "move_player", "right", 2 }
+        -- move_player blocks for both tiles, so the rival has already
+        -- landed on (7,4); this is just the beat before he turns up
+        rows[#rows + 1] = { "wait", 20 }
+      else
+        rows[#rows + 1] = { "move_npc_to", RIVAL, 7, 4 }
+      end
+      rows[#rows + 1] = { "face_object", RIVAL, "up" }
+      rows[#rows + 1] = { "hide_object", "OAKS_LAB", "OAKSLAB_EEVEE_POKE_BALL" }
+      -- rival starter baseline (RIVAL_STARTER_JOLTEON) at snatch time
+      rows[#rows + 1] = { "set_field", "rivalStarter", 1 }
+      rows[#rows + 1] = { "show_text", "_OaksLabRivalTakesText1" }
+      rows[#rows + 1] = { "play_sound", "Get_Key_Item" }
+      rows[#rows + 1] = { "show_text", "_OaksLabRivalTakesText2" }
+      rows[#rows + 1] = { "show_text", "_OaksLabRivalTakesText3" }
+      rows[#rows + 1] = { "show_text", "_OaksLabRivalTakesText4" }
+      rows[#rows + 1] = { "show_text", "_OaksLabRivalTakesText5" }
+      -- OaksLabRLE_PlayerWalksToOak: the simulated-joypad buffer plays
+      -- its RLE list BACKWARDS (StartSimulatingJoypadStates consumes
+      -- from wSimulatedJoypadStatesEnd), so the real order is LEFT 1,
+      -- DOWN 1, LEFT 3, UP 2 -- from the shove spot (9,4) the player
+      -- rounds the BOTTOM of the table to (5,3), directly below Oak
+      if py == 4 then
+        rows[#rows + 1] = { "walk_npc", "player",
+          { "left", "down", "left", "left", "left", "up", "up" } }
+      else
+        rows[#rows + 1] = { "walk_npc", "player", { "left" } }
+      end
+      rows[#rows + 1] = { "face_player_dir", "up" }
+      rows[#rows + 1] = { "face_object", OAK1, "down" }
+      -- OaksLabPlayerReceivedMonText clears wMonDataLocation, so AskName runs (#1013)
+      rows[#rows + 1] = { "show_text", "_OaksLabOakGivesText" }
+      rows[#rows + 1] = { "play_sound", "Get_Key_Item" }
+      rows[#rows + 1] = { "show_text", "_OaksLabReceivedText", { RAM = "PIKACHU" } }
+      rows[#rows + 1] = { "give_pokemon", "PIKACHU", 5 }
+      -- DisablePikachuOverworldSpriteDrawing keeps it in the ball (#1009)
+      rows[#rows + 1] = { "set_field", "pikachuInBall", true }
+      rows[#rows + 1] = { "set_flag", "EVENT_GOT_STARTER" }
+      rows[#rows + 1] = { "set_flag", "EVENT_CHOSE_PIKACHU" }
+      ow.runner:run(rows, { npc = npc, onDone = done,
+        checkpointOnDone = "release_npc" })
+    end,
+
+    TEXT_OAKSLAB_RIVAL = {
+      { "face_player" },
+      { "check_flag", "EVENT_GOT_STARTER" },
+      { "jump_if_false", "pre_starter" },
+      { "show_text", "_OaksLabRivalMyPokemonLooksStrongerText" },
+      { "jump", "end" },
+
+      { "label", "pre_starter" },
+      { "check_flag", "EVENT_FOLLOWED_OAK_INTO_LAB_2" },
+      { "jump_if_false", "gramps_gone" },
+      { "show_text", "_OaksLabRivalIllGetABetterPokemonThanYou" },
+      { "jump", "end" },
+
+      { "label", "gramps_gone" },
+      { "show_text", "_OaksLabRivalGrampsIsntAroundText" },
+    },
+  },
+
+  onEnter = function(game, ow)
+    if not (game.save.flags and game.save.flags.EVENT_GOT_POKEDEX) then
+      return
+    end
+    local Commands = require("src.script.Commands")
+    local ctx = { save = game.save, game = game, overworld = ow }
+    Commands.hide_object(ctx, "OAKS_LAB", "OAKSLAB_POKEDEX1")
+    Commands.hide_object(ctx, "OAKS_LAB", "OAKSLAB_POKEDEX2")
+  end,
+
+  onStep = function(game, ow, x, y)
+    local flags = game.save.flags
+    -- OaksLabPlayerDontGoAwayScript: y==6 without the starter walks the
+    -- player back up a tile
+    if flags.EVENT_FOLLOWED_OAK_INTO_LAB and not flags.EVENT_GOT_STARTER
+       and y >= 6 then
+      ow.runner:run({
+        { "face_object", OAK1, "down" },
+        { "face_object", RIVAL, "down" },
+        { "show_text", "_OaksLabOakDontGoAwayYetText" },
+        { "move_player", "up", 1 },
+      }, {})
+      return true
+    end
+    -- OaksLabRivalChallengesPlayerScript..OaksLabPikachuDislikesPokeballsScript:
+    -- heading for the door with Pikachu starts the rival battle, his
+    -- exit walk, then Pikachu pops out of its ball.
+    if flags.EVENT_GOT_STARTER and not flags.EVENT_BATTLED_RIVAL_IN_OAKS_LAB
+       and y >= 6 then
+      local rival = ow:npcByIndex(RIVAL)
+      if not rival then return false end
+      local rows = {
+        { "face_player_dir", "up" },
+        { "stop_music" },
+        { "play_music", "Music_MeetRival" },
+        { "show_text", "_OaksLabRivalIllTakeYouOnText" },
+      }
+      -- FindPathToPlayer with the Y distance decremented: the rival
+      -- stops one tile above the player
+      local target
+      for _, c in ipairs({ { x, y - 1 }, { x - 1, y }, { x + 1, y },
+                           { x, y + 1 } }) do
+        if ow.map:inBounds(c[1], c[2]) and ow.map:isWalkableCell(c[1], c[2]) then
+          target = c
+          break
+        end
+      end
+      if target then
+        table.insert(rows, { "move_npc_to", RIVAL, target[1], target[2] })
+      end
+      table.insert(rows, { "face_object", RIVAL,
+                           target and target[2] < y and "down"
+                           or target and target[2] > y and "up"
+                           or target and target[1] < x and "right" or "left" })
+      table.insert(rows, { "start_battle", "trainer", "OPP_RIVAL1", 1 })
+      table.insert(rows, { "heal_party" })
+      table.insert(rows, { "set_flag", "EVENT_BATTLED_RIVAL_IN_OAKS_LAB" })
+      -- OaksLabRivalEndBattleScript: his Eevee's future evolution is
+      -- decided here -- FLAREON if the player won, VAPOREON otherwise
+      table.insert(rows, { "check_battle_result", "win" })
+      table.insert(rows, { "jump_if_false", "lost_lab" })
+      table.insert(rows, { "set_field", "rivalStarter", 2 })
+      table.insert(rows, { "jump", "exit" })
+      table.insert(rows, { "label", "lost_lab" })
+      table.insert(rows, { "set_field", "rivalStarter", 3 })
+      table.insert(rows, { "label", "exit" })
+      -- OaksLabRivalStartsExitScript: parting shot, rival exit fanfare, then
+      -- walk out past the player (#683).
+      table.insert(rows, { "wait", 20 })
+      table.insert(rows, { "show_text", "_OaksLabRivalSmellYouLaterText" })
+      table.insert(rows, { "stop_music" })
+      table.insert(rows, { "play_music", "Music_MeetRival" })
+      table.insert(rows, { "move_npc_to", RIVAL, 4, 11 })
+      table.insert(rows, { "hide_object", "OAKS_LAB", "OAKSLAB_RIVAL" })
+      table.insert(rows, { "play_music", "Music_OaksLab" })
+      -- OaksLabPikachuEscapesPokeballScript: the follower reaches the map (#1009)
+      table.insert(rows, { "face_player_dir", "up" })
+      table.insert(rows, { "set_field", "pikachuInBall", false })
+      table.insert(rows, { "play_cry", "PIKACHU" })
+      table.insert(rows, { "show_text", "_OaksLabPikachuDislikesPokeballsText1" })
+      table.insert(rows, { "show_text", "_OaksLabPikachuDislikesPokeballsText2" })
+      ow.runner:run(rows, { npc = rival })
+      return true
+    end
+    return false
+  end,
+}
@@ -1,15 +1,23 @@
 -- Hand-ported from pret/pokered scripts/RedsHouse1F.asm.
-- Mom (RedsHouse1FMomText, text_asm) heals the party and shows the
-- "you should rest" / "looking great" dialogue.  The intro "wake up"
-- branch is tied to the unported intro cutscene, so the heal path is used.
+-- Mom (RedsHouse1FMomText): pre-starter shows the wake-up / Oak tip;
+-- after EVENT_GOT_STARTER, RedsHouse1FMomHealScript fades to white,
+-- heals, plays MUSIC_PKMN_HEALED, fades back, then "looking great".

 return {
  talk = {
    TEXT_REDSHOUSE1F_MOM = {
-      { "face_player" },
-      { "show_text", "_RedsHouse1FMomYouShouldRestText" },
-      { "heal_party" },
-      { "show_text", "_RedsHouse1FMomLookingGreatText" },
+      { "face_player" },                                          -- 1
+      { "check_flag", "EVENT_GOT_STARTER" },                      -- 2
+      { "jump_if_true", 6 },                                      -- 3
+      { "show_text", "_RedsHouse1FMomWakeUpText" },               -- 4
+      { "jump", "end" },                                          -- 5
+      -- RedsHouse1FMomHealScript
+      { "show_text", "_RedsHouse1FMomYouShouldRestText" },        -- 6
+      { "fade", "out", "white" },                                 -- 7  GBFadeOutToWhite
+      { "heal_party" },                                           -- 8
+      { "play_once", "Music_PkmnHealed" },                        -- 9  wait + restore map
+      { "fade", "in", "white" },                                  -- 10 GBFadeInFromWhite
+      { "show_text", "_RedsHouse1FMomLookingGreatText" },         -- 11
    },
  },
 }
@@ -4,9 +4,11 @@
 -- (.PlayerNextToSafariZoneWorker1CoordsArray).  Paying ¥500 hands over
 -- 30 SAFARI BALLs and starts the 502-step game
 -- (SafariZoneGateWouldYouLikeToJoinScript: wSafariSteps = 502,
-- wNumSafariBalls = SAFARI_BALLS_RECEIVED).  Declining walks you back
-- so you can't slip past.  Returning to the gate ends the game and the
-- worker takes the leftover balls back.
+-- wNumSafariBalls = SAFARI_BALLS_RECEIVED), then auto-walks the player
+-- up through the north warp into the zone.  Declining walks you back
+-- so you can't slip past.  Returning to the gate ends the game, the
+-- worker takes the leftover balls back and the auto-walk drops you 3
+-- cells below the warp you came in by (#540).
 --
 -- Step/ball bookkeeping lives in src/world/OverworldController.lua
 -- (safariStep/safariGameOver, from
@@ -19,17 +21,87 @@ local FEE = 500
 local BALLS = 30
 local STEPS = 502

-local function startGame(game, t, done)
-  game.save.money = game.save.money - FEE
-  game.save.safari = { balls = BALLS, steps = STEPS }
+-- SafariZoneGateSafariZoneWorker1WouldYouLikeToJoinText .success closes with
+-- `ld a, PAD_UP / ld c, 3 / SafariZoneEntranceAutoWalk`: paying walks the
+-- player up out of the gate and through the north warp, it is never left to
+-- the player.  EVENT_IN_SAFARI_ZONE is already set when that walk runs, so
+-- the two gate steps taken before the warp fires are charged against
+-- wSafariSteps (home/overworld.asm:307-310) -- which is why the counter
+-- reads 500/500 on arrival even though the script wrote 502 (#540).  The
+-- port's counter only runs on the nine interior maps (FieldDefaults
+-- safari.stepMaps, OverworldState:inSafariStepZone), so charge those two
+-- steps here instead.
+local function walkIntoZone(game, ow)
+  local p = ow.player
+  -- only from the two trigger cells in front of the worker, which are the
+  -- columns the north warps sit on; a player who paid after TALKING to him
+  -- from somewhere else walks in on their own, as they do today
+  local w = p.cellY == 2 and ow.map:warpAtCell(p.cellX, 0) or nil
+  if not w then return end
+  ow:scriptMove(p, "up", 2, function()
+    local st = game.save.safari
+    if st then st.steps = st.steps - 2 end
+    -- scripted steps skip onStepComplete (and with it CheckWarpsNoCollision),
+    -- so take that warp explicitly once the walk lands on it
+    ow:takeWarp(w.def)
+  end)
+end
+
+local function startGame(game, ow, t, done, balls, introText)
+  game.save.safari = { balls = balls or BALLS, steps = STEPS }
+  game.save.safariNags = nil
  local TextBox = require("src.render.TextBox")
-  local paid = (t._SafariZoneGateSafariZoneWorker1ThatllBe500PleaseText
-                or "That'll be ¥500\nplease!\f{PLAYER} received\n30 SAFARI BALLs!")
-               :gsub("{PLAYER}", game.save.player.name)
+  local paid = introText
+    or (t._SafariZoneGateSafariZoneWorker1ThatllBe500PleaseText
+        or "That'll be ¥500\nplease!\f{PLAYER} received\n30 SAFARI BALLs!")
+       :gsub("{NUM:[^}]*}", "500")
+  paid = paid:gsub("{PLAYER}", game.save.player.name)
  local pa = t._SafariZoneGateSafariZoneWorker1CallYouOnThePAText
             or "\fWe'll call you on\nthe PA when you\nrun out of time\nor SAFARI BALLs!"
  local luck = t._SafariZoneGateSafariZoneWorker1GoodLuckText or "Good Luck!"
-  game.stack:push(TextBox.new(game, paid .. pa .. "\f" .. luck, done))
+  game.stack:push(TextBox.new(game, paid .. pa .. "\f" .. luck, function()
+    if done then done() end
+    walkIntoZone(game, ow)
+  end))
+end
+
+-- Yellow's soft-lock fix (scripts/SafariZoneGate_2.asm): a player short of
+-- the full fee still gets in.
+--   0 < money < 500: SafariZoneEntranceCalculateLowCostAdmission takes
+--   everything and hands over min(money/23 + 1, 29) balls.
+--   money == 0: SafariZoneEntranceGetLowCostAdmissionText nags four times
+--   (LowCostText5/6/7/8), then relents -- free entry, one ball.
+local function yellowLowCost(game, ow, t, done, back)
+  local TextBox = require("src.render.TextBox")
+  if game.save.money > 0 then
+    local balls = math.min(math.floor(game.save.money / 23) + 1, 29)
+    game.save.money = 0
+    local intro =
+      (t._SafariZoneGateSafariZoneWorker1NotEnoughMoneyText
+       or "Oops! Not enough\nmoney!")
+      .. (t._SafariZoneLowCostText1
+          or "\fOh, all right, pay\nme what you have.")
+      .. "\f" .. (t._SafariZoneLowCostText2
+                  or "But, I can't give\nyou all 30 BALLs.")
+    startGame(game, ow, t, done, balls, intro)
+    return
+  end
+  local nag = game.save.safariNags or 0
+  game.save.safariNags = nag + 1
+  if nag >= 3 then
+    local intro =
+      (t._SafariZoneLowCostText8 or "Read my lips, NO!\nGet it?")
+      .. (t._SafariZoneLowCostText3
+          or "\fYou're persistent,\naren't you?\fOK, you can go in\nfor free, but\njust this once!")
+    startGame(game, ow, t, done, 1, intro)
+    return
+  end
+  local nags = {
+    t._SafariZoneLowCostText5 or "I'm sorry, but you\nhave to pay to\nenter.",
+    t._SafariZoneLowCostText6 or "You can't enter\nwithout paying!",
+    t._SafariZoneLowCostText7 or "I said, no money,\nno entry!",
+  }
+  back(nags[nag + 1])
 end

 local function joinPrompt(game, ow, done)
@@ -51,10 +123,15 @@ local function joinPrompt(game, ow, done)
          back(t._SafariZoneGateSafariZoneWorker1PleaseComeAgainText
               or "OK! Please come\nagain!")
        elseif game.save.money < FEE then
-          back(t._SafariZoneGateSafariZoneWorker1NotEnoughMoneyText
-               or "Oops! Not enough\nmoney!")
+          if require("src.core.GameVersion").isYellow() then
+            yellowLowCost(game, ow, t, done, back)
+          else
+            back(t._SafariZoneGateSafariZoneWorker1NotEnoughMoneyText
+                 or "Oops! Not enough\nmoney!")
+          end
        else
-          startGame(game, t, done)
+          game.save.money = game.save.money - FEE
+          startGame(game, ow, t, done)
        end
      end))
    end))
@@ -89,27 +166,38 @@ M.SAFARI_ZONE_GATE = {
  -- no walks you back into the zone
  onEnter = function(game, ow)
    if not game.save.safari or ow.player.cellY > 1 then return end
-    local TextBox = require("src.render.TextBox")
-    local ChoiceBox = require("src.ui.ChoiceBox")
-    local t = game.data.text
-    game.stack:push(TextBox.new(game,
-      t._SafariZoneGateSafariZoneWorker1LeavingEarlyText or "Leaving early?",
-      function()
-        game.stack:push(ChoiceBox.new(game, function(yes)
-          if not yes then
-            -- back into the zone through the entrance warp
-            local w = game.data.maps.SAFARI_ZONE_CENTER.warps[1]
-            ow:startWarpTo("SAFARI_ZONE_CENTER", w.x, w.y, "up")
-            return
-          end
-          game.save.safari = nil
-          game.stack:push(TextBox.new(game,
-            (t._SafariZoneGateSafariZoneWorker1ReturnSafariBallsText
-             or "Please return any\nSAFARI BALLs you\nhave left.")
-            .. "\f" .. (t._SafariZoneGateSafariZoneWorker1GoodHaulComeAgainText
-                        or "Did you get a\ngood haul?\fCome again!")))
-        end))
-      end))
+    -- QUEUED, never pushed: onEnter runs inside the arriving warp's
+    -- Transition midpoint, and Transition:finish pops whatever is on top
+    -- the same frame (Timing.WARP_FADE_IN is 0) -- so a box pushed here is
+    -- swallowed, and on a build where it survived it drew over a screen
+    -- still faded to black (#540).  Same contract as M.HALL_OF_FAME in
+    -- data/scripts/story.lua.
+    --
+    -- SafariZoneGateLeavingSafariScript .leaving_early: YES prints the
+    -- return-balls text, faces the player down and runs
+    -- SafariZoneEntranceAutoWalk with `PAD_DOWN, c = 3`, landing on the
+    -- counter row 3 cells below the warp you came in by; NO prints
+    -- "Good Luck!" and walks one step back up through that same warp.
+    local rightSide = ow.player.cellX ~= 3
+    local dest = game.data.maps.SAFARI_ZONE_CENTER.warps[rightSide and 2 or 1]
+    ow:queueScript({
+      { "ask", "_SafariZoneGateSafariZoneWorker1LeavingEarlyText" },
+      { "jump_if_false", "stay" },
+      -- the port never reaches SafariZoneGateLeavingSafariScript's own
+      -- GOOD_HAUL_COME_AGAIN branch (safariGameOver warps straight to the
+      -- counter), so the sign-off rides on this path
+      { "show_text", "_SafariZoneGateSafariZoneWorker1ReturnSafariBallsText" },
+      { "show_text", "_SafariZoneGateSafariZoneWorker1GoodHaulComeAgainText" },
+      -- no value: set_field assigns nil, which is how save.safari is cleared
+      { "set_field", "safari" },
+      -- move_player runs through scriptMove, which skips onStepComplete, so
+      -- walking back down past (x,2) cannot re-fire the join trigger
+      { "move_player", "down", 3 },
+      { "jump", "end" },
+      { "label", "stay" },
+      { "show_text", "_SafariZoneGateSafariZoneWorker1GoodLuckText" },
+      { "warp", "SAFARI_ZONE_CENTER", dest.x, dest.y, "up" },
+    })
  end,
 }

@@ -11,7 +11,7 @@
 -- field.seafoam (SEAFOAM_ISLANDS_1F/B1F/B3F holes+holeDestination and
 -- B3F's pluggedByHolesOn) plus the generic
 -- OverworldState:boulderIntoHole in src/world/OverworldController.lua;
-- no per-map onEnter hook is needed here.
+-- no per-map onEnter hook is needed for the boulders.

 local M = {}

@@ -23,4 +23,46 @@ M.VERMILION_GYM = {
  end,
 }

+-- The PLAYER falling down those same holes (#599).  field.seafoam's holes
+-- carry only the BOULDER's object cell on the floor below (landsAt), not
+-- the player's landing, so the player's landing is spelled out here: it
+-- comes from data/maps/special_warps.asm DungeonWarpList/DungeonWarpData,
+-- which the importer does not extract.  Same shape as MANSION_HOLES in
+-- data/scripts/story6.lua and VICTORY_ROAD_3F.onStep in
+-- data/scripts/story.lua; CAVERN $22 is a walkable tile, so the fall has
+-- to be an onStep, not a collision block.
+--
+-- Sources: scripts/SeafoamIslands1F.asm Seafoam1HolesCoords (17,6)/(24,6),
+-- B1F.asm Seafoam2HolesCoords (18,6)/(23,6), B2F.asm Seafoam3HolesCoords
+-- (19,6)/(22,6), B3F.asm Seafoam4HolesCoords (3,16)/(6,16).  Each floor
+-- sets wDungeonWarpDestinationMap and calls IsPlayerOnDungeonWarp, and
+-- wCoordIndex picks that floor's DungeonWarpData row.  Unconditional in
+-- the original: a plugged hole still drops the player.  The B3F and B4F
+-- landings are water; setMap's CheckForceBikeOrSurf pass
+-- (OverworldState:checkForcedMovement) mounts SURF on arrival.
+local HOLE_FALLS = {
+  SEAFOAM_ISLANDS_1F  = { { 17, 6, "SEAFOAM_ISLANDS_B1F", 18, 7 },
+                          { 24, 6, "SEAFOAM_ISLANDS_B1F", 23, 7 } },
+  SEAFOAM_ISLANDS_B1F = { { 18, 6, "SEAFOAM_ISLANDS_B2F", 19, 7 },
+                          { 23, 6, "SEAFOAM_ISLANDS_B2F", 22, 7 } },
+  SEAFOAM_ISLANDS_B2F = { { 19, 6, "SEAFOAM_ISLANDS_B3F", 18, 7 },
+                          { 22, 6, "SEAFOAM_ISLANDS_B3F", 19, 7 } },
+  SEAFOAM_ISLANDS_B3F = { {  3, 16, "SEAFOAM_ISLANDS_B4F", 4, 14 },
+                          {  6, 16, "SEAFOAM_ISLANDS_B4F", 5, 14 } },
+}
+
+for mapId, holes in pairs(HOLE_FALLS) do
+  M[mapId] = M[mapId] or {}
+  M[mapId].onStep = function(game, ow, x, y)
+    for _, h in ipairs(holes) do
+      if x == h[1] and y == h[2] then
+        require("src.core.Sound").play(game.data, "Faint_Fall")
+        ow:startWarpTo(h[3], h[4], h[5], ow.player.facing)
+        return true
+      end
+    end
+    return false
+  end
+end
+
 return M
@@ -16,6 +16,14 @@ M.VIRIDIAN_MART = {
  -- StartSimulatingJoypadStates walks the player to the counter
  -- (.PlayerMovement: PAD_LEFT 1, PAD_UP 2, door (3,7) -> counter (2,5))
  -- and ViridianMartOaksParcelScript hands the parcel over.  The player
+  -- never presses A.
+  --
+  -- The RLE list is consumed back to front: DecodeRLEList fills forward
+  -- from wSimulatedJoypadStatesEnd, the script seeds wSimulatedJoypadStates-
+  -- Index with the count, and home/overworld.asm decrements that index
+  -- before each read.  So PAD_LEFT 1, PAD_UP 2 actually plays up, up, left,
+  -- and the walk ends facing the clerk.  Replaying the list front to back
+  -- put the player at the counter facing up instead (#235).  The player
  -- never presses A.  This matters beyond convenience: the parcel gates
  -- Oak's Pokedex and the old man clearing Route 2, so vanilla guarantees
  -- it on entry rather than letting you walk out without it.
@@ -28,8 +36,8 @@ M.VIRIDIAN_MART = {
    if not f.EVENT_GOT_STARTER then return end
    ow:queueScript({
      { "show_text", "_ViridianMartClerkYouCameFromPalletTownText" },
-      { "move_player", "left", 1 },
      { "move_player", "up", 2 },
+      { "move_player", "left", 1 },
      -- the quest text's last page is "{PLAYER} got\nOAK's PARCEL!"
      { "give_item", "OAKS_PARCEL", 1, "_ViridianMartClerkParcelQuestText" },
      { "set_flag", "EVENT_GOT_OAKS_PARCEL" },
@@ -86,6 +94,27 @@ M.VIRIDIAN_CITY = {
      { "show_text", "_ViridianCityOldManTimeIsMoneyText" },             -- 8 (9 = end)
    },
  },
+  -- Re-apply the Pokedex old-man swap for a save that already holds the flag
+  -- but was never standing here when it fired: a vanilla .sav imported
+  -- through src/save_convert, whose codec does not model pokered's
+  -- wToggleableObjectFlags array, so save.objectToggles arrives empty and
+  -- both objects fall back to their compiled-in defaults -- the sleeper ON
+  -- (data/maps/toggleable_objects.asm toggleable_objects_for VIRIDIAN_CITY),
+  -- still lying across the north path (#234).
+  -- OaksLabOakGivesPokedexScript (scripts/OaksLab.asm) sets EVENT_GOT_POKEDEX
+  -- and, with no branch in between, runs HideObject TOGGLE_LYING_OLD_MAN /
+  -- ShowObject TOGGLE_OLD_MAN, so that one flag settles both toggles exactly.
+  -- Same shape as M.OAKS_LAB.onEnter in data/scripts/oaks_lab.lua, which
+  -- re-applies the same script's other two HideObjects on entry (#106).
+  onEnter = function(game, ow)
+    if not (game.save.flags and game.save.flags.EVENT_GOT_POKEDEX) then
+      return
+    end
+    local Commands = require("src.script.Commands")
+    local ctx = { save = game.save, game = game, overworld = ow }
+    Commands.hide_object(ctx, "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN_SLEEPY")
+    Commands.show_object(ctx, "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN")
+  end,
  -- ViridianCityCheckGotPokedexScript: the north corridor is gated on
  -- EVENT_GOT_POKEDEX, NOT on the sleeper being hidden, and it triggers
  -- on exactly one cell -- (19,9), the gap east of the sleeper (18,9)
@@ -154,11 +183,17 @@ M.BILLS_HOUSE = {
                                   overworld = ow },
                                 "BILLS_HOUSE", "BILLSHOUSE_BILL_POKEMON")
            game.save.flags.EVENT_BILL_SAID_USE_CELL_SEPARATOR = true
+            require("src.world.PikachuFollower").onBillEnteredMachine(game, ow)
            done()
          end
          if ow.player.facing == "down" then
            -- the player is standing on his straight path: walk around
-            -- (.PokemonWalkAroundPlayerMovement)
+            -- (.PokemonWalkAroundPlayerMovement).  BillsHouseScript2 runs
+            -- BillsHousePikachuWatchPlayer first on this branch, so a
+            -- Pikachu that is still following steps clear of Bill's detour
+            -- and turns to watch the player (#455).
+            require("src.world.PikachuFollower")
+              .onBillWalksAroundPlayer(game, ow)
            ow:scriptMove(npc, "right", 1, function()
              ow:scriptMove(npc, "up", 2, function()
                ow:scriptMove(npc, "left", 1, function()
@@ -222,17 +257,58 @@ M.BILLS_HOUSE = {
  -- repair saves that already got the ticket under the old collapsed
  -- script (the monster never hidden, human Bill never shown)
  onEnter = function(game, ow)
-    if game.save.flags.EVENT_GOT_SS_TICKET
-       and not game.save.flags.EVENT_USED_CELL_SEPARATOR_ON_BILL then
+    local flags = game.save.flags
+    if flags.EVENT_GOT_SS_TICKET
+       and not flags.EVENT_USED_CELL_SEPARATOR_ON_BILL then
      local Commands = require("src.script.Commands")
      local ctx = { game = game, save = game.save, overworld = ow }
      Commands.hide_object(ctx, "BILLS_HOUSE", "BILLSHOUSE_BILL_POKEMON")
      Commands.show_object(ctx, "BILLS_HOUSE", "BILLSHOUSE_BILL1")
-      game.save.flags.EVENT_BILL_SAID_USE_CELL_SEPARATOR = true
-      game.save.flags.EVENT_USED_CELL_SEPARATOR_ON_BILL = true
-      game.save.flags.EVENT_MET_BILL = true
-      game.save.flags.EVENT_MET_BILL_2 = true
+      flags.EVENT_BILL_SAID_USE_CELL_SEPARATOR = true
+      flags.EVENT_USED_CELL_SEPARATOR_ON_BILL = true
+      flags.EVENT_MET_BILL = true
+      flags.EVENT_MET_BILL_2 = true
    end
+    -- After Route25ToggleBillsScript, BILL2 is the visible human Bill
+    -- ("check out my rare POKéMON").  Re-apply on enter so a mid-house
+    -- load still matches the toggles if the pool was rebuilt.
+    if flags.EVENT_LEFT_BILLS_HOUSE_AFTER_HELPING then
+      local Commands = require("src.script.Commands")
+      local ctx = { game = game, save = game.save, overworld = ow }
+      Commands.hide_object(ctx, "BILLS_HOUSE", "BILLSHOUSE_BILL_POKEMON")
+      Commands.hide_object(ctx, "BILLS_HOUSE", "BILLSHOUSE_BILL1")
+      Commands.show_object(ctx, "BILLS_HOUSE", "BILLSHOUSE_BILL2")
+    end
+    if not flags.EVENT_MET_BILL_2 then
+      require("src.world.PikachuFollower").onBillsHouseEnter(game, ow)
+    end
+  end,
+}
+
+-- -------------------------------------------------------------------
+-- Route 25 outside Bill's house (scripts/Route25.asm
+-- Route25ToggleBillsScript): leaving after the SS Ticket arms the
+-- Eevee PC list and swaps human Bill to his post-help dialogue NPC.
+-- Leaving mid-quest (Bill still in the machine) puts the monster back.
+-- -------------------------------------------------------------------
+
+M.ROUTE_25 = {
+  onEnter = function(game, ow)
+    local flags = game.save.flags
+    if flags.EVENT_LEFT_BILLS_HOUSE_AFTER_HELPING then return end
+    local Commands = require("src.script.Commands")
+    local ctx = { game = game, save = game.save, overworld = ow }
+    if not flags.EVENT_MET_BILL_2 then
+      flags.EVENT_BILL_SAID_USE_CELL_SEPARATOR = nil
+      Commands.show_object(ctx, "BILLS_HOUSE", "BILLSHOUSE_BILL_POKEMON")
+      return
+    end
+    if not flags.EVENT_GOT_SS_TICKET then return end
+    flags.EVENT_LEFT_BILLS_HOUSE_AFTER_HELPING = true
+    -- TOGGLE_NUGGET_BRIDGE_GUY (ROUTE24_COOLTRAINER_M1)
+    Commands.hide_object(ctx, "ROUTE_24", "ROUTE24_COOLTRAINER_M1")
+    Commands.hide_object(ctx, "BILLS_HOUSE", "BILLSHOUSE_BILL1")
+    Commands.show_object(ctx, "BILLS_HOUSE", "BILLSHOUSE_BILL2")
  end,
 }

@@ -256,25 +332,40 @@ M.VERMILION_CITY = {
  end,
  -- VermilionCityDefaultScript's per-frame SSAnneTicketCheckCoords check:
  -- the unguarded cell (18,30) just west of the sailor leads straight
-  -- onto the dock warp, so stepping onto it heading for the dock gets
-  -- ticket-checked (and turned back once the ship has sailed) without
-  -- the player ever pressing A.  The sailor himself never disappears.
+  -- onto the dock warp.  Stepping onto it facing down always runs the
+  -- sailor dialog (DisplayTextID TEXT_VERMILIONCITY_SAILOR1); only a
+  -- ticket while the ship is still docked lets the player continue --
+  -- otherwise they are walked back up.  The sailor himself never hides.
  onStep = function(game, ow, x, y)
    if x ~= 18 or y ~= 30 then return false end
    if ow.player.facing ~= "down" then return false end
-    local f = game.save.flags
+    local Flags = require("src.script.Flags")
    local t = game.data.text
    local TextBox = require("src.render.TextBox")
-    if f.EVENT_SS_ANNE_LEFT then
+    local shipLeft = Flags.get(game.save, "EVENT_SS_ANNE_LEFT")
+    local hasTicket = (game.save.inventory.S_S_TICKET or 0) > 0
+    if shipLeft then
      game.stack:push(TextBox.new(game,
        t._VermilionCitySailor1ShipSetSailText or "The ship set sail.",
        function() ow:scriptMove(ow.player, "up", 1) end))
      return true
    end
-    if (game.save.inventory.S_S_TICKET or 0) > 0 then return false end
+    -- Walk-past is never facing-right / inFrontOfOrBehindGuardCoords, so
+    -- VermilionCitySailor1Text always takes .greet_player_and_check_ticket:
+    -- DoYouHaveATicket, then FlashedTicket (allow through) or YouNeedATicket
+    -- (walk back).  Returning true while the box is up also blocks the
+    -- dock warp on this step.
+    local ask = t._VermilionCitySailor1DoYouHaveATicketText
+      or "Welcome to S.S.\nANNE!\fExcuse me, do you\nhave a ticket?"
+    if hasTicket then
+      game.stack:push(TextBox.new(game,
+        ask .. "\f"
+        .. (t._VermilionCitySailor1FlashedTicketText
+            or "{PLAYER} flashed\nthe S.S.TICKET!")))
+      return true
+    end
    game.stack:push(TextBox.new(game,
-      (t._VermilionCitySailor1WelcomeToSSAnneText or "Welcome to S.S.\nANNE!")
-      .. "\f"
+      ask .. "\f"
      .. (t._VermilionCitySailor1YouNeedATicketText
          or "You need a ticket\nto get aboard."),
      function() ow:scriptMove(ow.player, "up", 1) end))
@@ -288,7 +379,7 @@ M.VERMILION_CITY = {
      { "face_player" },                                             -- 1
      { "check_flag", "EVENT_SS_ANNE_LEFT" },                        -- 2
      { "jump_if_true", 11 },                                        -- 3
-      { "show_text", "_VermilionCitySailor1WelcomeToSSAnneText" },   -- 4
+      { "show_text", "_VermilionCitySailor1DoYouHaveATicketText" },  -- 4
      { "check_item", "S_S_TICKET" },                                -- 5
      { "jump_if_false", 9 },                                        -- 6
      { "show_text", "_VermilionCitySailor1FlashedTicketText" },     -- 7
@@ -318,18 +409,21 @@ M.SS_ANNE_2F = {

 M.SS_ANNE_CAPTAINS_ROOM = {
  talk = {
+    -- SSAnneCaptainsRoomCaptainText: after the rub line's text_asm tail,
+    -- pokered plays MUSIC_PKMN_HEALED (scripts/SSAnneCaptainsRoom.asm).
    TEXT_SSANNECAPTAINSROOM_CAPTAIN = {
      { "check_flag", "EVENT_GOT_HM01" },                                 -- 1
-      { "jump_if_true", 9 },                                              -- 2
+      { "jump_if_true", 10 },                                             -- 2
      { "show_text", "_SSAnneCaptainsRoomRubCaptainsBackText" },          -- 3
-      { "show_text", "_SSAnneCaptainsRoomCaptainIFeelMuchBetterText" },   -- 4
+      { "play_once", "Music_PkmnHealed" },                                -- 4
+      { "show_text", "_SSAnneCaptainsRoomCaptainIFeelMuchBetterText" },   -- 5
      -- give-then-print like scripts/SSAnneCaptainsRoom.asm (GiveItem
      -- fills wStringBuffer; the received text reads it)
-      { "give_item", "HM_CUT", 1, false },                                -- 5
-      { "show_text", "_SSAnneCaptainsRoomCaptainReceivedHM01Text" },      -- 6
-      { "set_flag", "EVENT_GOT_HM01" },                                   -- 7
-      { "jump", 10 },                                                     -- 8
-      { "show_text", "_SSAnneCaptainsRoomCaptainNotSickAnymoreText" },    -- 9
+      { "give_item", "HM_CUT", 1, false },                                -- 6
+      { "show_text", "_SSAnneCaptainsRoomCaptainReceivedHM01Text" },      -- 7
+      { "set_flag", "EVENT_GOT_HM01" },                                   -- 8
+      { "jump", 11 },                                                     -- 9
+      { "show_text", "_SSAnneCaptainsRoomCaptainNotSickAnymoreText" },    -- 10
    },
  },
 }
@@ -339,7 +433,93 @@ M.SS_ANNE_CAPTAINS_ROOM = {
 -- MrFujisHouse.asm; the teleport back to his house is a warp)
 -- -------------------------------------------------------------------

+-- scripts/PokemonTower7F.asm: after each Rocket loses,
+-- PokemonTower7FEndBattleScript shows its EndBattle text (EndTrainerBattle),
+-- prints its AfterBattle text (DisplayTextID), then
+-- PokemonTower7FRocketLeaveMovementScript walks the grunt off toward the
+-- (9,16) stairs (MoveSprite) and PokemonTower7FHideNPCScript despawns it
+-- (HideObject).  Without this the beaten grunts stood in the corridor
+-- forever (#200).
+local POKEMON_TOWER_7F_ROCKETS = {
+  { index = 1, name = "POKEMONTOWER7F_ROCKET1",
+    beat = "EVENT_BEAT_POKEMONTOWER_7_TRAINER_0",
+    after = "_PokemonTower7FRocket1AfterBattleText" },
+  { index = 2, name = "POKEMONTOWER7F_ROCKET2",
+    beat = "EVENT_BEAT_POKEMONTOWER_7_TRAINER_1",
+    after = "_PokemonTower7FRocket2AfterBattleText" },
+  { index = 3, name = "POKEMONTOWER7F_ROCKET3",
+    beat = "EVENT_BEAT_POKEMONTOWER_7_TRAINER_2",
+    after = "_PokemonTower7FRocket3AfterBattleText" },
+}
+
+-- PokemonTower7FNPCCoordMovementTable, keyed by the PLAYER's tile ("x,y")
+-- at the engagement (both the talk and the sight walk-up leave the player on
+-- the tile the vanilla table indexes).  Each list is that entry's
+-- NPC_MOVEMENT_* exit, applied from the grunt's current tile.  The exact
+-- tables are one per grunt (dbmapcoord bytes decoded back to x,y).
+local POKEMON_TOWER_7F_EXITS = {
+  [1] = { -- ROCKET1 @ (9,11), faces RIGHT
+    ["9,12"]  = { "right", "down", "down", "down", "down", "down", "left" },
+    ["10,11"] = { "down", "right", "down", "down", "down", "down" },
+    ["11,11"] = { "down", "down", "down", "down", "down" },
+    ["12,11"] = { "down", "down", "down", "down", "down" },
+  },
+  [2] = { -- ROCKET2 @ (12,9), faces LEFT
+    ["12,10"] = { "left", "down", "down", "down", "down", "down", "down" },
+    ["11,9"]  = { "down", "down", "down", "left", "down", "down" },
+    ["10,9"]  = { "down", "down", "down", "down", "down" },
+    ["9,9"]   = { "down", "down", "down", "down", "down" },
+  },
+  [3] = { -- ROCKET3 @ (9,7), faces RIGHT
+    ["9,8"]  = { "right", "down", "down", "down", "down", "down", "down" },
+    ["10,7"] = { "down", "down", "down", "down", "down" },
+    ["11,7"] = { "down", "down", "down", "down", "down" },
+    ["12,7"] = { "down", "down", "down", "down", "down" },
+  },
+}
+-- The vanilla table only lists the sight/talk tiles the map geometry allows;
+-- a plain down-walk keeps any other engagement tile (e.g. talking from the
+-- side) safe -- it still clears the corridor and despawns the grunt.
+local POKEMON_TOWER_7F_EXIT_FALLBACK =
+  { "down", "down", "down", "down", "down" }
+
 M.POKEMON_TOWER_7F = {
+  -- Repair saves that beat a grunt before the exit walk was ported: in
+  -- vanilla HideObject persists (wMissableObjectFlags), so a beaten grunt is
+  -- still gone on re-entry.  hide_object below writes objectToggles for new
+  -- wins; this hides any grunt whose BEAT flag is already set.
+  onEnter = function(game, ow)
+    local Commands = require("src.script.Commands")
+    local ctx = { game = game, save = game.save, overworld = ow }
+    for _, r in ipairs(POKEMON_TOWER_7F_ROCKETS) do
+      if game.save.flags[r.beat] then
+        Commands.hide_object(ctx, "POKEMON_TOWER_7F", r.name)
+      end
+    end
+  end,
+  -- runVictoryHook fires after every trainer win on the map (both the sight
+  -- and talk paths route through engageTrainer -> checkVictoryRewards), so
+  -- this walks off whichever grunt was just beaten but is still standing.
+  -- The AfterBattle text + walk queue UNDER the EndBattle box engageTrainer
+  -- pushes right after, giving the vanilla order: EndBattle, AfterBattle,
+  -- walk, despawn.
+  onVictory = function(game, ow)
+    if ow.runner:isRunning() then return end
+    for _, r in ipairs(POKEMON_TOWER_7F_ROCKETS) do
+      local npc = ow:npcByIndex(r.index)
+      if npc and game.save.flags[r.beat] then
+        local key = ow.player.cellX .. "," .. ow.player.cellY
+        local dirs = (POKEMON_TOWER_7F_EXITS[r.index] or {})[key]
+                     or POKEMON_TOWER_7F_EXIT_FALLBACK
+        ow.runner:run({
+          { "show_text", r.after },                       -- DisplayTextID
+          { "walk_npc", r.index, dirs },                  -- MoveSprite
+          { "hide_object", "POKEMON_TOWER_7F", r.name },  -- HideObject
+        }, { npc = npc })
+        return
+      end
+    end
+  end,
  talk = {
    TEXT_POKEMONTOWER7F_MR_FUJI = {
      { "face_player" },                                  -- 1
@@ -425,12 +605,34 @@ local function snorlaxWake(mapId, objName, beatFlag, wokeUpText, calmedText)
  }
 end

+-- A beaten Snorlax is gone for good: Route12/Route16DefaultScript run
+-- HideObject in the same breath as the battle that sets
+-- EVENT_BEAT_ROUTEnn_SNORLAX, so "event set, object still on the map" is a
+-- state the asm cannot produce.  Here it can (a mod's world:toggleObject, a
+-- save edited or migrated from a build older than the flag), and it is a
+-- dead end: ItemEffects' adjacentSleepingSnorlax refuses to wake a Snorlax
+-- whose beat flag is set (ItemUsePokeFlute's CheckEvent, engine/items/
+-- item_effects.asm), so the sleeper sits in the road forever and Cycling
+-- Road is unreachable (#585).  Reconcile the toggle from the flag on every
+-- entry -- the mirror of SaveData.lua's toggle -> flag backfill, and the
+-- same repair shape the Silph Co. floors use below.
+local function hideBeatenSnorlax(mapId, objName, beatFlag)
+  return function(game, ow)
+    if not game.save.flags[beatFlag] then return end
+    local Commands = require("src.script.Commands")
+    Commands.hide_object({ game = game, save = game.save, overworld = ow },
+                         mapId, objName)
+  end
+end
+
 -- snorlaxWake is looked up by ItemEffects.lua/BagMenu.lua (via
 -- data/scripts/init.lua's M.get) and run when the flute wakes Snorlax;
 -- objName/beatFlag let ItemEffects find the NPC and check whether it's
 -- already been beaten before allowing the wake.
 M.ROUTE_12 = {
  talk = { TEXT_ROUTE12_SNORLAX = { { "show_text", "_Route12SnorlaxText" } } },
+  onEnter = hideBeatenSnorlax("ROUTE_12", "ROUTE12_SNORLAX",
+                              "EVENT_BEAT_ROUTE12_SNORLAX"),
  snorlaxWake = {
    objName = "ROUTE12_SNORLAX", beatFlag = "EVENT_BEAT_ROUTE12_SNORLAX",
    script = snorlaxWake("ROUTE_12", "ROUTE12_SNORLAX", "EVENT_BEAT_ROUTE12_SNORLAX",
@@ -439,6 +641,8 @@ M.ROUTE_12 = {
 }
 M.ROUTE_16 = {
  talk = { TEXT_ROUTE16_SNORLAX = { { "show_text", "_Route16Text7" } } },
+  onEnter = hideBeatenSnorlax("ROUTE_16", "ROUTE16_SNORLAX",
+                              "EVENT_BEAT_ROUTE16_SNORLAX"),
  snorlaxWake = {
    objName = "ROUTE16_SNORLAX", beatFlag = "EVENT_BEAT_ROUTE16_SNORLAX",
    script = snorlaxWake("ROUTE_16", "ROUTE16_SNORLAX", "EVENT_BEAT_ROUTE16_SNORLAX",
@@ -470,11 +674,18 @@ M.SAFARI_ZONE_SECRET_HOUSE = {
 M.WARDENS_HOUSE = {
  talk = {
    TEXT_WARDENSHOUSE_WARDEN = {
+      -- Labelled rather than hand-numbered: the branches here have been
+      -- re-pointed twice now (#535, #645), and every insert used to mean
+      -- renumbering three jumps that had no way of announcing they were stale.
      { "face_player" },                                             -- 1
      { "check_flag", "EVENT_GOT_HM04" },                            -- 2
-      { "jump_if_true", 13 },                                        -- 3
+      -- #535: previously jumped to the same silent-end target as the
+      -- give-then-thank fallthrough, so the warden said nothing on every
+      -- visit after the trade. pokered's .got_item branch
+      -- (scripts/WardensHouse.asm) instead prints HM04ExplanationText.
+      { "jump_if_true", "got_hm04" },                                -- 3
      { "check_item", "GOLD_TEETH" },                                -- 4
-      { "jump_if_false", 15 },                                       -- 5
+      { "jump_if_false", "no_teeth" },                               -- 5
      { "show_text", "_WardensHouseWardenGaveTheGoldTeethText" },    -- 6
      { "take_item", "GOLD_TEETH", 1 },                              -- 7
      { "set_flag", "EVENT_GAVE_GOLD_TEETH" },                       -- 8
@@ -483,9 +694,27 @@ M.WARDENS_HOUSE = {
      { "give_item", "HM_STRENGTH", 1, false },                      -- 10
      { "show_text", "_WardensHouseWardenReceivedHM04Text" },        -- 11
      { "set_flag", "EVENT_GOT_HM04" },                              -- 12
-      { "jump", 16 },                                                -- 13 (already got it)
-      { "jump", 16 },                                                -- 14 (unused)
-      { "show_text", "_WardensHouseWardenGibberish1Text" },          -- 15
+      { "jump", "end" },                                             -- 13 (jp .done)
+
+      -- #645: WardensHouseWardenText prints Gibberish1, then YesNoChoice,
+      -- and the warden answers the same gibberish either way -- Gibberish2
+      -- on yes, Gibberish3 on no (scripts/WardensHouse.asm).  The port
+      -- printed the question and walked off before the answer.
+      { "label", "no_teeth" },                                       -- 14
+      { "ask", "_WardensHouseWardenGibberish1Text" },                -- 15
+      { "jump_if_true", "gibberish_yes" },                           -- 16
+      { "show_text", "_WardensHouseWardenGibberish3Text" },          -- 17
+      { "jump", "end" },                                             -- 18
+      { "label", "gibberish_yes" },                                  -- 19
+      { "show_text", "_WardensHouseWardenGibberish2Text" },          -- 20
+      { "jump", "end" },                                             -- 21
+
+      -- #535: pokered .got_item branch (scripts/WardensHouse.asm) --
+      -- printed on every subsequent talk once EVENT_GOT_HM04 is set.
+      -- Text is _WardensHouseWardenHM04ExplanationText (text/WardensHouse.asm):
+      -- HM04 teaches Strength, and hints at the Safari Zone secret house.
+      { "label", "got_hm04" },                                       -- 22
+      { "show_text", "_WardensHouseWardenHM04ExplanationText" },     -- 23
    },
  },
 }
@@ -495,6 +724,70 @@ M.WARDENS_HOUSE = {
 -- generic OPP_GIOVANNI#2 battle)
 -- -------------------------------------------------------------------

+-- SilphCo11FTeamRocketLeavesScript (scripts/SilphCo11F.asm) hides every
+-- ROCKET and rocket-aligned SCIENTIST toggle on 2F-11F the moment Giovanni
+-- falls; the item balls, the 2F/10F rescued workers and the 7F rival keep
+-- theirs.  Names and order are data/maps/toggleable_objects.asm's
+-- TOGGLE_SILPH_CO_<floor>_n entries.  Saffron City's half of the same
+-- script lives in M.SAFFRON_CITY (story4.lua) (#392).
+local SILPH_ROCKET_OBJECTS = {
+  { "SILPH_CO_2F",  { "SILPHCO2F_SCIENTIST1", "SILPHCO2F_SCIENTIST2",
+                      "SILPHCO2F_ROCKET1", "SILPHCO2F_ROCKET2" } },
+  { "SILPH_CO_3F",  { "SILPHCO3F_ROCKET", "SILPHCO3F_SCIENTIST" } },
+  { "SILPH_CO_4F",  { "SILPHCO4F_ROCKET1", "SILPHCO4F_SCIENTIST",
+                      "SILPHCO4F_ROCKET2" } },
+  { "SILPH_CO_5F",  { "SILPHCO5F_ROCKET1", "SILPHCO5F_SCIENTIST",
+                      "SILPHCO5F_ROCKER", "SILPHCO5F_ROCKET2" } },
+  { "SILPH_CO_6F",  { "SILPHCO6F_ROCKET1", "SILPHCO6F_SCIENTIST",
+                      "SILPHCO6F_ROCKET2" } },
+  { "SILPH_CO_7F",  { "SILPHCO7F_ROCKET1", "SILPHCO7F_SCIENTIST",
+                      "SILPHCO7F_ROCKET2", "SILPHCO7F_ROCKET3" } },
+  { "SILPH_CO_8F",  { "SILPHCO8F_ROCKET1", "SILPHCO8F_SCIENTIST",
+                      "SILPHCO8F_ROCKET2" } },
+  { "SILPH_CO_9F",  { "SILPHCO9F_ROCKET1", "SILPHCO9F_SCIENTIST",
+                      "SILPHCO9F_ROCKET2" } },
+  { "SILPH_CO_10F", { "SILPHCO10F_ROCKET", "SILPHCO10F_SCIENTIST" } },
+  { "SILPH_CO_11F", { "SILPHCO11F_GIOVANNI", "SILPHCO11F_ROCKET1",
+                      "SILPHCO11F_ROCKET2" } },
+}
+
+-- hide_object writes save.objectToggles, so the single pass at the win
+-- covers floors the player is not standing on; onlyMap is the per-floor
+-- repair path below.
+local function silphRocketsLeave(game, ow, onlyMap)
+  local Commands = require("src.script.Commands")
+  local ctx = { game = game, save = game.save, overworld = ow }
+  for _, floor in ipairs(SILPH_ROCKET_OBJECTS) do
+    if not onlyMap or onlyMap == floor[1] then
+      for _, name in ipairs(floor[2]) do
+        Commands.hide_object(ctx, floor[1], name)
+      end
+    end
+  end
+end
+
+-- SilphCo11FGiovanniAfterBattleScript (scripts/SilphCo11F.asm) is the whole
+-- aftermath: DisplayTextID TEXT_SILPHCO11F_GIOVANNI_YOU_RUINED_OUR_PLANS,
+-- GBFadeOutToBlack, SilphCo11FTeamRocketLeavesScript, Delay3,
+-- GBFadeInFromBlack, then SetEvent.  The port had only the hide pass, so the
+-- speech never played and every rocket blinked out in front of the player
+-- (#722).  Same hide list as silphRocketsLeave, spelled as script rows so the
+-- fade can hold over it.
+local function silphAftermathRows()
+  local rows = {
+    { "show_text", "_SilphCo11FGiovanniYouRuinedOurPlansText" },
+    { "fade", "out" },
+  }
+  for _, floor in ipairs(SILPH_ROCKET_OBJECTS) do
+    for _, name in ipairs(floor[2]) do
+      rows[#rows + 1] = { "hide_object", floor[1], name }
+    end
+  end
+  rows[#rows + 1] = { "wait", 3 }   -- Delay3
+  rows[#rows + 1] = { "fade", "in" }
+  return rows
+end
+
 M.SILPH_CO_11F = {
  -- Giovanni's battle is a COORDINATE TRIGGER, not a talk.
  -- SilphCo11FDefaultScript (scripts/SilphCo11F.asm) checks
@@ -507,9 +800,13 @@ M.SILPH_CO_11F = {
  -- line) would touch, and the whole Silph ending -- the flag, the Master
  -- Ball, the Saffron streets clearing -- silently never happened.
  --
-  -- engageTrainer shows TEXT_SILPHCO11F_GIOVANNI as the battle text and,
-  -- via victories.lua OPP_GIOVANNI#2, sets the event on a win; a loss
-  -- sets nothing, so the trigger re-arms exactly as vanilla does.
+  -- SilphCo11FDefaultScript orders it DisplayTextID TEXT_SILPHCO11F_GIOVANNI
+  -- FIRST, then MoveSprite .GiovanniMovement: he speaks from behind the desk
+  -- and only then walks the three tiles down.  Moving him before the box made
+  -- him cross the room in silence and deliver the speech point-blank (#869),
+  -- so the box comes first here and engageTrainer skips its own battle text.
+  -- victories.lua OPP_GIOVANNI#2 sets the event on a win; a loss sets
+  -- nothing, so the trigger re-arms exactly as vanilla does.
  onStep = function(game, ow, x, y)
    if game.save.flags.EVENT_BEAT_SILPH_CO_GIOVANNI then return false end
    if not ((x == 6 and y == 13) or (x == 7 and y == 12)) then return false end
@@ -518,49 +815,77 @@ M.SILPH_CO_11F = {
      if npc.def and npc.def.name == "SILPHCO11F_GIOVANNI" then gio = npc break end
    end
    if not gio or ow:trainerDefeated(gio) then return false end
-    ow:scriptMove(gio, "down", 3, function()
-      gio:facePlayer(ow.player)
-      ow:engageTrainer(gio, function()
-        -- SilphCo11FTeamRocketLeavesScript: Giovanni leaves the floor
-        -- after the loss (the street rockets are handled by
-        -- M.SAFFRON_CITY.onEnter in story4.lua).
-        if game.save.flags.EVENT_BEAT_SILPH_CO_GIOVANNI then
-          local Commands = require("src.script.Commands")
-          local ctx = { game = game, save = game.save, overworld = ow }
-          Commands.hide_object(ctx, "SILPH_CO_11F", "SILPHCO11F_GIOVANNI")
-        end
-      end)
-    end)
+    local TextBox = require("src.render.TextBox")
+    game.stack:push(TextBox.new(game,
+      game.data.text._SilphCo11FGiovanniText
+      or "Ah {PLAYER}!\nSo we meet again!",
+      function()
+        ow:scriptMove(gio, "down", 3, function()
+          gio:facePlayer(ow.player)
+          ow:engageTrainer(gio, function()
+            -- SilphCo11FGiovanniAfterBattleScript: the "Blast it all!"
+            -- speech, then SilphCo11FTeamRocketLeavesScript behind a fade so
+            -- every Silph rocket leaves off-screen (the street rockets are
+            -- handled by M.SAFFRON_CITY.onEnter in story4.lua).  Queued, not
+            -- run here: the battle's own callbacks are still unwinding, so
+            -- queueScript starts it on the first idle overworld frame --
+            -- after the end-battle "Arrgh!!" box victories.lua OPP_GIOVANNI#2
+            -- pushes (#722).
+            if game.save.flags.EVENT_BEAT_SILPH_CO_GIOVANNI then
+              ow:queueScript(silphAftermathRows())
+            end
+          end, nil, true)
+        end)
+      end))
    return true
  end,
  onEnter = function(game, ow)
    if game.save.flags.EVENT_BEAT_SILPH_CO_GIOVANNI then
-      local Commands = require("src.script.Commands")
-      local ctx = { game = game, save = game.save, overworld = ow }
-      Commands.hide_object(ctx, "SILPH_CO_11F", "SILPHCO11F_GIOVANNI")
+      silphRocketsLeave(game, ow)
    end
  end,
  talk = {
+    -- SilphCo11FSilphPresidentText branches on EVENT_GOT_MASTER_BALL only:
+    -- the teleport pads reach him without passing Giovanni's trigger, and
+    -- afterwards he describes the ball forever.  The old rows fell off the
+    -- end of the script on both branches, so a second talk was silence
+    -- (#392).
    TEXT_SILPHCO11F_SILPH_PRESIDENT = {
      { "face_player" },                                                     -- 1
-      { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },                      -- 2
-      { "jump_if_false", 10 },                                               -- 3
-      { "check_flag", "EVENT_GOT_MASTER_BALL" },                             -- 4
-      { "jump_if_true", 10 },                                                -- 5
-      { "show_text", "_SilphCo11FSilphPresidentText" },                      -- 6
+      { "check_flag", "EVENT_GOT_MASTER_BALL" },                             -- 2
+      { "jump_if_true", 9 },                                                 -- 3
+      { "show_text", "_SilphCo11FSilphPresidentText" },                      -- 4
      -- give-then-print like scripts/SilphCo11F.asm
-      { "give_item", "MASTER_BALL", 1, false },                              -- 7
-      { "show_text", "_SilphCo11FSilphPresidentReceivedMasterBallText" },    -- 8
-      { "set_flag", "EVENT_GOT_MASTER_BALL" },                               -- 9
-      { "jump", 11 },                                                        -- 10
+      { "give_item", "MASTER_BALL", 1, false },                              -- 5
+      { "show_text", "_SilphCo11FSilphPresidentReceivedMasterBallText" },    -- 6
+      { "set_flag", "EVENT_GOT_MASTER_BALL" },                               -- 7
+      { "jump", "end" },                                                     -- 8
+      { "show_text",
+        "_SilphCo11FSilphPresidentMasterBallDescriptionText" },              -- 9
    },
  },
 }

+-- Floors 2F-10F carry no other onEnter, so this repairs saves that beat
+-- Giovanni before the hide list existed (same shape as
+-- M.POKEMON_TOWER_7F.onEnter); 11F hides its own inside the table above.
+for _, floor in ipairs(SILPH_ROCKET_OBJECTS) do
+  local mapId = floor[1]
+  if mapId ~= "SILPH_CO_11F" then
+    M[mapId] = M[mapId] or {}
+    M[mapId].onEnter = function(game, ow)
+      if game.save.flags.EVENT_BEAT_SILPH_CO_GIOVANNI then
+        silphRocketsLeave(game, ow, mapId)
+      end
+    end
+  end
+end
+
 -- -------------------------------------------------------------------
 -- Victory Road boulder switches (scripts/VictoryRoad1F/2F/3F.asm):
 -- a boulder resting on a switch removes a barrier block; the 3F hole
-- drops a boulder down to the 2F switch.
+-- drops a boulder down to the 2F switch, and also dungeon-warps the
+-- player (IsPlayerOnDungeonWarp + DungeonWarpList/Data -> 2F at 22,16).
 -- -------------------------------------------------------------------

 local function boulderAt(ow, x, y)
@@ -568,11 +893,20 @@ local function boulderAt(ow, x, y)
  return npc and npc.def.sprite == "SPRITE_BOULDER" and npc or nil
 end

+-- Each barrier is stamped BOTH ways on entry.  pokered only ever stamps the
+-- OPEN block (ReplaceTileBlock edits the loaded block map, which the next map
+-- load throws away, so a fresh entry always shows the .blk's closed barrier),
+-- but OverworldState:replaceBlock writes through Map:setBlock into the SHARED
+-- map record in Game.data, so the port has to put the closed block back
+-- itself or a solved barrier stays open for the rest of the session (#258).
+-- The closed ids are the shipped .blk bytes: VictoryRoad1F.blk (4,6) = $25,
+-- VictoryRoad2F.blk (3,4) = $37 and (11,7) = $25, VictoryRoad3F.blk
+-- (3,5) = $25.  Same both-ways pattern as the card-key doors in
+-- OverworldState:setMap.
 M.VICTORY_ROAD_1F = {
  onEnter = function(game, ow)
-    if game.save.flags.EVENT_VICTORY_ROAD_1_BOULDER_ON_SWITCH then
-      ow:replaceBlock(4, 6, 0x1D)
-    end
+    ow:replaceBlock(4, 6,
+      game.save.flags.EVENT_VICTORY_ROAD_1_BOULDER_ON_SWITCH and 0x1D or 0x25)
  end,
  onBoulderMoved = function(game, ow, npc)
    if npc.cellX == 17 and npc.cellY == 13
@@ -585,12 +919,14 @@ M.VICTORY_ROAD_1F = {

 M.VICTORY_ROAD_2F = {
  onEnter = function(game, ow)
-    if game.save.flags.EVENT_VICTORY_ROAD_2_BOULDER_ON_SWITCH1 then
-      ow:replaceBlock(3, 4, 0x15)
-    end
-    if game.save.flags.EVENT_VICTORY_ROAD_2_BOULDER_ON_SWITCH2 then
-      ow:replaceBlock(11, 7, 0x1D)
-    end
+    -- VictoryRoad2FResetBoulderEventScript (scripts/VictoryRoad2F.asm:19):
+    -- entering 2F clears the 1F switch event, so 1F's barrier is closed
+    -- again the next time you climb down (#258)
+    game.save.flags.EVENT_VICTORY_ROAD_1_BOULDER_ON_SWITCH = nil
+    ow:replaceBlock(3, 4,
+      game.save.flags.EVENT_VICTORY_ROAD_2_BOULDER_ON_SWITCH1 and 0x15 or 0x37)
+    ow:replaceBlock(11, 7,
+      game.save.flags.EVENT_VICTORY_ROAD_2_BOULDER_ON_SWITCH2 and 0x1D or 0x25)
  end,
  onBoulderMoved = function(game, ow, npc)
    if npc.cellX == 1 and npc.cellY == 16
@@ -608,9 +944,8 @@ M.VICTORY_ROAD_2F = {

 M.VICTORY_ROAD_3F = {
  onEnter = function(game, ow)
-    if game.save.flags.EVENT_VICTORY_ROAD_3_BOULDER_ON_SWITCH1 then
-      ow:replaceBlock(3, 5, 0x1D)
-    end
+    ow:replaceBlock(3, 5,
+      game.save.flags.EVENT_VICTORY_ROAD_3_BOULDER_ON_SWITCH1 and 0x1D or 0x25)
  end,
  onBoulderMoved = function(game, ow, npc)
    if npc.cellX == 3 and npc.cellY == 5
@@ -618,14 +953,38 @@ M.VICTORY_ROAD_3F = {
      game.save.flags.EVENT_VICTORY_ROAD_3_BOULDER_ON_SWITCH1 = true
      ow:replaceBlock(3, 5, 0x1D)
    end
-    -- the hole at (23,15): the boulder drops to 2F next to switch 2
-    if npc.cellX == 23 and npc.cellY == 15 then
+    -- the hole at (23,15): the boulder drops to 2F next to switch 2.
+    -- VictoryRoad3FDefaultScript .handle_hole gates the swap on
+    -- CheckAndSetEvent EVENT_VICTORY_ROAD_3_BOULDER_ON_SWITCH2, then
+    -- HideObject TOGGLE_VICTORY_ROAD_3F_BOULDER / ShowObject
+    -- TOGGLE_VICTORY_ROAD_2F_BOULDER.  Those two toggles are
+    -- VICTORYROAD3F_BOULDER4 and VICTORYROAD2F_BOULDER3
+    -- (data/maps/toggleable_objects.asm); the old "VICTORYROAD2F_BOULDER"
+    -- matched no object_event name, so the toggle landed under a key
+    -- objectVisible never reads: harmless only while nothing hid that
+    -- boulder, and fatal once Route 23's reset does (#258).
+    if npc.cellX == 23 and npc.cellY == 15
+       and not game.save.flags.EVENT_VICTORY_ROAD_3_BOULDER_ON_SWITCH2 then
+      game.save.flags.EVENT_VICTORY_ROAD_3_BOULDER_ON_SWITCH2 = true
      local Commands = require("src.script.Commands")
      local ctx = { save = game.save, overworld = ow, game = game }
      Commands.hide_object(ctx, "VICTORY_ROAD_3F", npc.def.name)
-      Commands.show_object(ctx, "VICTORY_ROAD_2F", "VICTORYROAD2F_BOULDER")
+      Commands.show_object(ctx, "VICTORY_ROAD_2F", "VICTORYROAD2F_BOULDER3")
    end
  end,
+  -- scripts/VictoryRoad3F.asm VictoryRoad3FDefaultScript: the same hole
+  -- is a dungeon warp for the player (wDungeonWarpDestinationMap =
+  -- VICTORY_ROAD_2F, wWhichDungeonWarp = 2 -> DungeonWarpData 22,16).
+  -- Mirrors POKEMON_MANSION_3F.onStep; CAVERN $22 is walkable so the
+  -- fall is onStep, not a collision block.
+  onStep = function(game, ow, x, y)
+    if x == 23 and y == 15 then
+      require("src.core.Sound").play(game.data, "Faint_Fall")
+      ow:startWarpTo("VICTORY_ROAD_2F", 22, 16, ow.player.facing)
+      return true
+    end
+    return false
+  end,
 }

 -- -------------------------------------------------------------------
@@ -638,6 +997,16 @@ M.VICTORY_ROAD_3F = {
 -- IndigoPlateauLobby.asm) so the champion is re-fightable on rematches,
 -- like pokered's re-entry cutscene.  EVENT_BEAT_CHAMPION_RIVAL stays set
 -- forever (postgame gates like the Cerulean cave guard read it).
+--
+-- pokered forces the fight on map entry: Agatha's victory arms
+-- SCRIPT_CHAMPIONSROOM_PLAYER_ENTERS (scripts/AgathasRoom.asm), and
+-- ChampionsRoomPlayerEntersScript then runs RivalEntrance_RLEMovement
+-- (up 1, right 1, up 3) before ChampionsRoomRivalReadyToBattleScript.
+-- The rival object has no trainer header / sight range, so without that
+-- entrance script the player can walk past (issue #99).  We arm on the
+-- run flag instead of Agatha's victory bit: same observable effect for
+-- first clear and Indigo rematches, without a cross-map script pointer.
+--
 -- scripts/ChampionsRoom.asm ChampionsRoomRivalDefeatedScript ->
 -- OakArrivesScript -> OakCongratulatesPlayerScript ->
 -- OakDisappointedWithRivalScript -> OakComeWithMeScript -> OakExitsScript,
@@ -646,43 +1015,96 @@ M.VICTORY_ROAD_3F = {
 -- itself is NOT run here: it belongs to the HALL_OF_FAME room script
 -- (scripts/HallOfFame.asm), so we set a one-shot marker and warp; the room
 -- onEnter (M.HALL_OF_FAME below) drives the HoF Oak speech + record.
+local championsRoomRivalScript = {
+  { "face_player" },                                        -- 1
+  { "check_flag", "EVENT_BEAT_CHAMPION_RIVAL_THIS_RUN" },   -- 2
+  -- "end" rather than a row number past the tail: this script grew by a row
+  -- when the follow-Oak walk landed (#704), which silently turned the old
+  -- numeric 26 into a jump ONTO the closing HALL_OF_FAME warp instead of past
+  -- it, so a returning champion warped straight into the induction.
+  { "jump_if_true", "end" },                                -- 3
+  { "show_text", "_ChampionsRoomRivalIntroText" },          -- 4
+  -- ChampionsRoomRivalReadyToBattleScript plays MUSIC_FINAL_BATTLE after
+  -- the intro text, before the battle itself (#706); pushBattle's wipe-time
+  -- playBattle("final") then no-ops on the same song, so the theme stays
+  -- continuous into the fight
+  { "play_music", "Music_FinalBattle" },                    -- 5
+  { "rival_battle", "OPP_RIVAL3", 1 },                      -- 6
+  -- losing halts here; the numeric target this replaced pointed at the
+  -- closing warp, which inducted a player who had just lost the fight (#704)
+  { "jump_if_false", "end" },                               -- 7
+  { "set_flag", "EVENT_BEAT_CHAMPION_RIVAL_THIS_RUN" },     -- 8
+  { "set_flag", "EVENT_BEAT_CHAMPION_RIVAL" },              -- 9
+  -- ChampionsRoomRivalDefeatedScript re-displays TEXT_CHAMPIONSROOM_RIVAL,
+  -- whose text_asm takes the EVENT_BEAT_CHAMPION_RIVAL branch =
+  -- _ChampionsRoomRivalAfterBattleText (the in-battle _RivalDefeatedText
+  -- is the port's generic "<PLAYER> defeated BLUE!" engine line instead).
+  { "show_text", "_ChampionsRoomRivalAfterBattleText" },    -- 10
+  -- ChampionsRoomOakArrivesScript: Music_Cities1AlternateTempo
+  -- (Cities1, kept into HALL_OF_FAME like BIT_NO_MAP_MUSIC after
+  -- defeating RIVAL3), then Oak's "{PLAYER}!" + reveal + walk in.
+  -- audio/alternate_tempo.asm Music_Cities1AlternateTempo is not a plain
+  -- PlayMusic: it fades the current song out (wAudioFadeOutControl = 10),
+  -- waits 100 frames for the fade, then restarts Cities1 with channel 1
+  -- pointed at Music_Cities1_Ch1_AlternateTempo -- `tempo 232` where the
+  -- normal Music_Cities1_Ch1 opens `tempo 144`, i.e. the slower, heavier
+  -- reading of the town theme this scene is known for (#847).
+  { "fade_music", 10 },                                     -- 11
+  { "wait", 100 },                                          -- 12
+  { "play_music", "Music_Cities1", { keep = true, tempo = 232 } }, -- 13
+  { "show_text", "_ChampionsRoomOakText" },                 -- 14
+  { "show_object", "CHAMPIONS_ROOM", "CHAMPIONSROOM_OAK" },  -- 15
+  { "move_npc", 2, "up", 5 },                               -- 16 OakEntranceAfterVictoryMovement
+  -- OakCongratulatesPlayerScript: rival faces left, Oak faces down
+  { "face_object", 1, "left" },                             -- 17
+  { "face_object", 2, "down" },                             -- 18
+  { "show_text", "_ChampionsRoomOakCongratulatesPlayerText" }, -- 19
+  -- OakDisappointedWithRivalScript: Oak turns to the rival (right)
+  { "face_object", 2, "right" },                            -- 20
+  { "show_text", "_ChampionsRoomOakDisappointedWithRivalText" }, -- 21
+  -- OakComeWithMeScript: Oak faces down again, then exits up
+  { "face_object", 2, "down" },                             -- 22
+  { "show_text", "_ChampionsRoomOakComeWithMeText" },       -- 23
+  { "move_npc", 2, "up", 2 },                               -- 24 OakExitChampionsRoomMovement
+  { "hide_object", "CHAMPIONS_ROOM", "CHAMPIONSROOM_OAK" },  -- 25
+  -- ChampionsRoomPlayerFollowsOakScript / WalkToHallOfFame_RLEMovement.
+  -- The player walks out after Oak instead of the screen just fading on the
+  -- spot (#704).  Route one tile right before walking north so the player
+  -- reaches the north-wall HALL_OF_FAME warp without sharing the rival's
+  -- (4,2) cell.  The original simulated movement bypasses entity collision,
+  -- but this scene should not visibly walk through the defeated rival.
+  { "move_player", "right", 1 },                            -- 26
+  { "move_player", "up", 3 },                               -- 27
+  -- hand the induction off to the HALL_OF_FAME room (consumed by its
+  -- onEnter), then warp up into it (destWarp 1 lands at (4,7) facing up)
+  { "set_field", "pendingHallOfFame", true },               -- 28
+  { "warp", "HALL_OF_FAME", 4, 7, "up" },                   -- 29
+}
+
 M.CHAMPIONS_ROOM = {
+  onEnter = function(game, ow)
+    if game.save.flags.EVENT_BEAT_CHAMPION_RIVAL_THIS_RUN then return end
+    -- Lance entrance warps land at y=7; HoF return warps land at y=0.
+    -- Only the south entry should run ChampionsRoomPlayerEntersScript.
+    if ow.player.cellY < 7 then return end
+    local rival
+    for _, npc in ipairs(ow.npcs) do
+      if npc.def and npc.def.name == "CHAMPIONSROOM_RIVAL" then
+        rival = npc
+        break
+      end
+    end
+    -- RivalEntrance_RLEMovement, then the battle/Oak script (queued
+    -- separately so talk-script jump indices stay 1-based as written).
+    ow:queueScript({
+      { "move_player", "up", 1 },
+      { "move_player", "right", 1 },
+      { "move_player", "up", 3 },
+    })
+    ow:queueScript(championsRoomRivalScript, { npc = rival })
+  end,
  talk = {
-    TEXT_CHAMPIONSROOM_RIVAL = {
-      { "face_player" },                                        -- 1
-      { "check_flag", "EVENT_BEAT_CHAMPION_RIVAL_THIS_RUN" },   -- 2
-      { "jump_if_true", 24 },                                   -- 3
-      { "show_text", "_ChampionsRoomRivalIntroText" },          -- 4
-      { "rival_battle", "OPP_RIVAL3", 1 },                      -- 5
-      { "jump_if_false", 24 },                                  -- 6
-      { "set_flag", "EVENT_BEAT_CHAMPION_RIVAL_THIS_RUN" },     -- 7
-      { "set_flag", "EVENT_BEAT_CHAMPION_RIVAL" },              -- 8
-      -- ChampionsRoomRivalDefeatedScript re-displays TEXT_CHAMPIONSROOM_RIVAL,
-      -- whose text_asm takes the EVENT_BEAT_CHAMPION_RIVAL branch =
-      -- _ChampionsRoomRivalAfterBattleText (the in-battle _RivalDefeatedText
-      -- is the port's generic "<PLAYER> defeated BLUE!" engine line instead).
-      { "show_text", "_ChampionsRoomRivalAfterBattleText" },    -- 9
-      -- ChampionsRoomOakArrivesScript: Oak's "{PLAYER}!" then reveal + walk in
-      { "show_text", "_ChampionsRoomOakText" },                 -- 10
-      { "show_object", "CHAMPIONS_ROOM", "CHAMPIONSROOM_OAK" },  -- 11
-      { "move_npc", 2, "up", 5 },                               -- 12 OakEntranceAfterVictoryMovement (3,7)->(3,2)
-      -- OakCongratulatesPlayerScript: rival faces left, Oak faces down
-      { "face_object", 1, "left" },                             -- 13
-      { "face_object", 2, "down" },                             -- 14
-      { "show_text", "_ChampionsRoomOakCongratulatesPlayerText" }, -- 15
-      -- OakDisappointedWithRivalScript: Oak turns to the rival (right)
-      { "face_object", 2, "right" },                            -- 16
-      { "show_text", "_ChampionsRoomOakDisappointedWithRivalText" }, -- 17
-      -- OakComeWithMeScript: Oak faces down again, then exits up
-      { "face_object", 2, "down" },                             -- 18
-      { "show_text", "_ChampionsRoomOakComeWithMeText" },       -- 19
-      { "move_npc", 2, "up", 2 },                               -- 20 OakExitChampionsRoomMovement (3,2)->(3,0)
-      { "hide_object", "CHAMPIONS_ROOM", "CHAMPIONSROOM_OAK" },  -- 21
-      -- hand the induction off to the HALL_OF_FAME room (consumed by its
-      -- onEnter), then warp up into it (destWarp 1 lands at (4,7) facing up)
-      { "set_field", "pendingHallOfFame", true },               -- 22
-      { "warp", "HALL_OF_FAME", 4, 7, "up" },                   -- 23
-    },
+    TEXT_CHAMPIONSROOM_RIVAL = championsRoomRivalScript,
  },
 }

@@ -712,6 +1134,29 @@ M.HALL_OF_FAME = {
    local toggles = game.save.objectToggles and game.save.objectToggles.HALL_OF_FAME
    if toggles then toggles.HALLOFFAME_OAK = nil end

+    -- Make the Hall of Fame recording machine interactable.  The console
+    -- juts from the north wall as the two solid cells (4,1) and (5,1); a
+    -- sign on each lets the player face the machine (from below, or from
+    -- either side) and press A to run the TEXT_HALLOFFAME_PC talk script.
+    -- maps.lua is generated from the ROM and gitignored, so the sign is
+    -- injected here (a tracked script) rather than baked into map data.
+    local def = ow.map.def
+    def.signs = def.signs or {}
+    local present = false
+    for _, s in ipairs(def.signs) do
+      if s.text == "TEXT_HALLOFFAME_PC" then present = true break end
+    end
+    if not present then
+      table.insert(def.signs, { text = "TEXT_HALLOFFAME_PC", x = 4, y = 1 })
+      table.insert(def.signs, { text = "TEXT_HALLOFFAME_PC", x = 5, y = 1 })
+    end
+    -- the live Map instance built its signAt lookup from def.signs before
+    -- this hook ran, so rebuild it (idempotent) to pick up the injection
+    ow.map.signAt = {}
+    for _, s in ipairs(def.signs) do
+      ow.map.signAt[s.y * ow.map.widthCells + s.x] = s
+    end
+
    if not game.save.pendingHallOfFame then return end
    game.save.pendingHallOfFame = false
    ow:queueScript({
@@ -725,6 +1170,21 @@ M.HALL_OF_FAME = {
      { "record_hall_of_fame" },                       -- predef HallOfFamePC: induction + credits
    })
  end,
+  talk = {
+    -- The recording machine doubles as a "warp home" PC: a YES/NO prompt
+    -- that teleports back to the new-game bedroom spawn (special_warps.asm
+    -- NewGameWarp: REDS_HOUSE_2F, 3, 6, facing down).  Fabricated
+    -- convenience -- there is no such prompt in the original ROM.
+    -- Heal + remember_outdoor so house LAST_MAP mats land in Pallet, not
+    -- Indigo Plateau (issue #103 escape path for already-stuck saves).
+    TEXT_HALLOFFAME_PC = {
+      { "ask", "Return to\nPALLET TOWN?" },             -- 1  YES/NO -> lastCheck
+      { "jump_if_false", "end" },                       -- 2  NO: back away
+      { "heal_party" },                                 -- 3
+      { "remember_outdoor", "PALLET_TOWN", 5, 6 },       -- 4  LAST_MAP -> Pallet door
+      { "warp", "REDS_HOUSE_2F", 3, 6, "down" },        -- 5  YES: home to your room
+    },
+  },
 }

 -- -------------------------------------------------------------------
@@ -735,35 +1195,72 @@ M.HALL_OF_FAME = {

 M.CERULEAN_CITY = {
  talk = {
+    -- CeruleanCityRivalText: Bill line once beaten; pre-battle otherwise.
+    -- Post-fight walk matches CeruleanCityMovement4 (right then into town).
    TEXT_CERULEANCITY_RIVAL = {
-      { "face_player" },                                    -- 1
-      { "check_flag", "EVENT_BEAT_CERULEAN_RIVAL" },        -- 2
-      { "jump_if_true", 9 },                                -- 3
-      { "show_text", "_CeruleanCityRivalPreBattleText" },   -- 4
-      { "rival_battle", "OPP_RIVAL1", 7 },                  -- 5
-      { "jump_if_false", 10 },                              -- 6
-      { "set_flag", "EVENT_BEAT_CERULEAN_RIVAL" },          -- 7
-      { "show_text", "_CeruleanCityRivalDefeatedText" },    -- 8
-      { "jump", 10 },                                       -- 9
+      { "face_player" },                                         -- 1
+      { "check_flag", "EVENT_BEAT_CERULEAN_RIVAL" },             -- 2
+      { "jump_if_true", 13 },                                    -- 3
+      { "show_text", "_CeruleanCityRivalPreBattleText" },        -- 4
+      { "rival_battle", "OPP_RIVAL1", 7 },                       -- 5
+      { "jump_if_false", "end" },                                -- 6
+      { "set_flag", "EVENT_BEAT_CERULEAN_RIVAL" },               -- 7
+      { "show_text", "_CeruleanCityRivalDefeatedText" },         -- 8
+      { "show_text", "_CeruleanCityRivalIWentToBillsText" },     -- 9
+      { "walk_npc", 1, { "right", "down", "down", "down",
+                         "down", "down", "down" } },             -- 10
+      { "hide_object", "CERULEAN_CITY", "CERULEANCITY_RIVAL" },  -- 11
+      { "jump", "end" },                                         -- 12
+      { "show_text", "_CeruleanCityRivalIWentToBillsText" },     -- 13
    },
  },
 }

+-- PokemonTower2F.asm: after the battle, PokemonTower2FDefeatedRivalScript
+-- walks him out (RightThenDown vs DownThenRight from EVENT_POKEMON_TOWER_
+-- RIVAL_ON_LEFT) then HideObject TOGGLE_POKEMON_TOWER_2F_RIVAL.  Player
+-- at (15,5) is the ON_LEFT case.
+local TOWER_RIVAL_EXIT_RIGHT_THEN_DOWN =
+  { "right", "down", "down", "right", "down", "down", "right", "right" }
+local TOWER_RIVAL_EXIT_DOWN_THEN_RIGHT =
+  { "down", "down", "right", "right", "right", "right", "down", "down" }
+
+local function pokemonTower2FRivalScript(playerX)
+  local exitDirs = (playerX == 15)
+    and TOWER_RIVAL_EXIT_DOWN_THEN_RIGHT
+    or TOWER_RIVAL_EXIT_RIGHT_THEN_DOWN
+  return {
+    { "face_player" },                                            -- 1
+    { "check_flag", "EVENT_BEAT_POKEMON_TOWER_RIVAL" },           -- 2
+    { "jump_if_true", 12 },                                       -- 3
+    { "show_text", "_PokemonTower2FRivalWhatBringsYouHereText" }, -- 4
+    { "rival_battle", "OPP_RIVAL2", 4 },                          -- 5
+    { "jump_if_false", "end" },                                   -- 6 loss: stay
+    { "set_flag", "EVENT_BEAT_POKEMON_TOWER_RIVAL" },             -- 7
+    { "show_text", "_PokemonTower2FRivalDefeatedText" },          -- 8
+    { "walk_npc", 1, exitDirs },                                  -- 9
+    { "hide_object", "POKEMON_TOWER_2F", "POKEMONTOWER2F_RIVAL" }, -- 10
+    { "jump", "end" },                                            -- 11
+    { "show_text", "_PokemonTower2FRivalHowsYourDexText" },       -- 12
+  }
+end
+
 M.POKEMON_TOWER_2F = {
+  rivalScript = pokemonTower2FRivalScript,
  talk = {
-    TEXT_POKEMONTOWER2F_RIVAL = {
-      { "face_player" },                                            -- 1
-      { "check_flag", "EVENT_BEAT_POKEMON_TOWER_RIVAL" },           -- 2
-      { "jump_if_true", 10 },                                       -- 3
-      { "show_text", "_PokemonTower2FRivalWhatBringsYouHereText" }, -- 4
-      { "rival_battle", "OPP_RIVAL2", 4 },                          -- 5
-      { "jump_if_false", 11 },                                      -- 6
-      { "set_flag", "EVENT_BEAT_POKEMON_TOWER_RIVAL" },             -- 7
-      { "show_text", "_PokemonTower2FRivalDefeatedText" },          -- 8
-      { "jump", 11 },                                               -- 9
-      { "show_text", "_PokemonTower2FRivalHowsYourDexText" },       -- 10
-    },
+    TEXT_POKEMONTOWER2F_RIVAL = function(game, ow, npc, done)
+      ow.runner:run(pokemonTower2FRivalScript(ow.player.cellX),
+                    { npc = npc, onDone = done })
+    end,
  },
+  -- Saves that beat him before the exit walk was ported still have the
+  -- flag but a visible rival; hide on enter like BillsHouse repairs.
+  onEnter = function(game, ow)
+    if not game.save.flags.EVENT_BEAT_POKEMON_TOWER_RIVAL then return end
+    local Commands = require("src.script.Commands")
+    Commands.hide_object({ game = game, save = game.save, overworld = ow },
+                         "POKEMON_TOWER_2F", "POKEMONTOWER2F_RIVAL")
+  end,
  -- PokemonTower2FDefaultScript: walking past the rival's tile forces
  -- the encounter (ArePlayerCoordsInArray on (15,5)/(14,6)) -- he never
  -- waits to be talked to
@@ -775,8 +1272,7 @@ M.POKEMON_TOWER_2F = {
    if not rival then return false end
    ow.player.facing = (x == 15) and "left" or "up"
    require("src.core.Music").play(game.data, "Music_MeetRival")
-    ow.runner:run(M.POKEMON_TOWER_2F.talk.TEXT_POKEMONTOWER2F_RIVAL,
-                  { npc = rival })
+    ow.runner:run(pokemonTower2FRivalScript(x), { npc = rival })
    return true
  end,
 }
@@ -1,6 +1,10 @@
 -- More hand-ported events: the Pallet Town intro, the thirsty Saffron
 -- gate guards, the Bike Voucher chain, fossils and the day-care.
-- Registered via data/scripts/init.lua; each cites its pokered source.
+-- Registered via data/scripts/init.lua; Red/Blue cite pokered, Yellow
+-- cites pokeyellow (Pallet stop row, Oak spawn, walk RLE, and the
+-- wild-Pikachu beat before the lab escort).
+
+local GameVersion = require("src.core.GameVersion")

 local M = {}

@@ -35,72 +39,79 @@ function escort.findPath(fromX, fromY, toX, toY)
  return path
 end

-- PalletTownOakWalksToPlayerScript: Oak appears at his object spot
-- (8,5) and zigzags to one tile below the player (hNPCPlayerYDistance
-- is pre-decremented before predef FindPathToPlayer).
+-- Red: Oak object (8,5) -> one tile below the player at y=1.
+-- Yellow: Oak object (10,4); stop fires at y=0 (pokeyellow PalletTown).
 function escort.oakApproach(playerX)
+  if GameVersion.isYellow() then
+    return escort.findPath(10, 4, playerX, 1)
+  end
  return escort.findPath(8, 5, playerX, 2)
 end

-- RLEList_ProfOakWalkToLab (engine/overworld/auto_movement.asm):
-- DOWN x5, LEFT, DOWN x5, RIGHT x3, UP -- Oak's last step lands on the
-- lab door (12,11).  (The trailing NPC_CHANGE_FACING is a march-in-
-- place beat on the mat; here Oak just stands his final beat.)
-escort.oakSteps = {
-  "down", "down", "down", "down", "down",
-  "left",
-  "down", "down", "down", "down", "down",
-  "right", "right", "right",
-  "up",
-}
+-- RLEList_ProfOakWalkToLab (engine/overworld/auto_movement.asm).
+-- Yellow differs: first DOWN is x6 (Oak starts one tile farther north).
+local function buildOakSteps()
+  if GameVersion.isYellow() then
+    return {
+      "down", "down", "down", "down", "down", "down",
+      "left",
+      "down", "down", "down", "down", "down",
+      "right", "right", "right",
+      "up",
+    }
+  end
+  return {
+    "down", "down", "down", "down", "down",
+    "left",
+    "down", "down", "down", "down", "down",
+    "right", "right", "right",
+    "up",
+  }
+end

-- RLEList_PlayerWalkToLab decodes to UP x2, RIGHT x3, DOWN x5, LEFT,
-- DOWN x6 and plays in REVERSE buffer order (wSimulatedJoypadStatesEnd
-- grows downward): DOWN x6, LEFT, DOWN x5, RIGHT x3, UP x2 -- Oak's
-- exact path one step behind.  The 17th press (the second UP) is eaten
-- by the door-warp frame (WarpFound clears hJoyHeld via EnterMap), so
-- only 16 real steps happen; the walk ends on the door at (12,11).
+escort.oakSteps = buildOakSteps()
+
+-- Player stays one step behind Oak (simplified reverse-RLE port).
 escort.playerSteps = { "down" }
 for _, d in ipairs(escort.oakSteps) do
  escort.playerSteps[#escort.playerSteps + 1] = d
 end

+local function npcNamed(ow, name)
+  for _, n in ipairs(ow.npcs or {}) do
+    if n.def and n.def.name == name then return n end
+  end
+  return nil
+end
+
 M.PALLET_TOWN = {
  talk = require("data.scripts.pallet_town").talk,
  escort = escort,
-  -- Oak stops you at the north row (PalletTownDefaultScript's
-  -- `wYCoord == 1` check), walks up from (8,5), and leads you to his
-  -- lab with the player one step behind (scripts/PalletTown.asm +
-  -- PalletMovementScriptPointerTable in
-  -- engine/overworld/auto_movement.asm), then the lab walk-in and the
-  -- choose-mon exchange (scripts/OaksLab.asm OaksLabDefaultScript ..
-  -- OaksLabOakChooseMonSpeechScript).
+  -- Red: stop at y==1 from (8,5).  Yellow: stop at y==0 from (10,4),
+  -- then a wild Pikachu battle before the lab escort (pokeyellow
+  -- PalletTownPikachuBattleScript).
  onStep = function(game, ow, x, y)
-    if y ~= 1 or game.save.flags.EVENT_FOLLOWED_OAK_INTO_LAB
+    local yellow = GameVersion.isYellow()
+    local stopY = yellow and 0 or 1
+    if y ~= stopY or game.save.flags.EVENT_FOLLOWED_OAK_INTO_LAB
       or game.save.flags.EVENT_GOT_STARTER then
      return false
    end
    local TextBox = require("src.render.TextBox")
    local Commands = require("src.script.Commands")
    local Music = require("src.core.Music")
+    local BattleState = require("src.battle.BattleState")
    local t = game.data.text
    local ctx = { save = game.save, game = game, overworld = ow }

-    -- PalletTownDefaultScript: stop the player, turn them around
-    -- (wPlayerMovingDirection = PLAYER_DIR_DOWN applies on the very
-    -- next frame, before the text box opens) and strike up the "oak
-    -- appears" theme (MUSIC_MEET_PROF_OAK)
-    ow.player.facing = "down"
+    -- Red turns the player down; Yellow faces up at the north exit.
+    ow.player.facing = yellow and "up" or "down"
    Music.play(game.data, "Music_MeetProfOak")

-    -- DelayFrames-style hold: the world pauses (input stays locked)
-    -- for `frames` frames, then cb runs.  Reuses the emote pause slot;
-    -- with an `npc` the "!" bubble draws above it (EmotionBubble).
    local function hold(frames, npc, cb)
      ow.emote = { frames = frames, npc = npc, onDone = cb }
    end

-    -- chain single-tile scriptMoves through a direction list
    local function walkList(entity, steps, done)
      local i = 0
      local function nextStep()
@@ -114,10 +125,8 @@ M.PALLET_TOWN = {
      nextStep()
    end

-    -- ---- Oak's Lab side (scripts/OaksLab.asm) ----------------------
-
-    -- OaksLabOakChooseMonSpeechScript: the fed-up / choose-mon /
-    -- what-about-me / be-patient exchange, Delay3 between boxes
+    -- OaksLabOakChooseMonSpeechScript.  Yellow's OakChooseMon text is
+    -- the single-ball speech, not Red's "there are 3 POKéMON".
    local function chooseMonSpeech()
      local function say(key, fb, next)
        game.stack:push(TextBox.new(game, t[key] or fb, next))
@@ -126,7 +135,9 @@ M.PALLET_TOWN = {
          "{RIVAL}: Gramps!\nI'm fed up with\nwaiting!", function()
        hold(3, nil, function()
          say("_OaksLabOakChooseMonText",
-              "OAK: Here, {PLAYER}!\fThere are 3\nPOKéMON here!\fYou can have one!\nChoose!", function()
+              yellow
+                and "OAK: Look, {PLAYER}! Do\nyou see that ball\non the table?"
+                or "OAK: Here, {PLAYER}!\fThere are 3\nPOKéMON here!\fYou can have one!\nChoose!", function()
            hold(3, nil, function()
              say("_OaksLabRivalWhatAboutMeText",
                  "{RIVAL}: Hey!\nGramps! What\nabout me?", function()
@@ -143,30 +154,18 @@ M.PALLET_TOWN = {
      end)
    end

-    -- entering the lab: the door Oak (OAKSLAB_OAK2, (5,10)) walks up 3
-    -- ahead of the player (OaksLabOakEntersLabScript OakEntryMovement),
-    -- swaps for the desk Oak (OAKSLAB_OAK1, (5,2)), then the player
-    -- walks up 8 from the mat (PlayerEntryMovementRLE) while the rival
-    -- and Oak turn with them (OaksLabPlayerEntersLabScript /
-    -- OaksLabFollowedOakScript)
+    -- Door Oak is OAKSLAB_OAK2: Red index 8, Yellow index 6 (one ball).
    local function labWalkIn()
-      local oak2 = ow:npcByIndex(8)
+      local oak2 = npcNamed(ow, "OAKSLAB_OAK2") or ow:npcByIndex(yellow and 6 or 8)
      local function swapOaks()
        Commands.hide_object(ctx, "OAKS_LAB", "OAKSLAB_OAK2")
        Commands.show_object(ctx, "OAKS_LAB", "OAKSLAB_OAK1")
-        hold(3, nil, function() -- Delay3
-          Commands.face_object(ctx, 1, "down") -- rival watches you pass
+        hold(3, nil, function()
+          Commands.face_object(ctx, 1, "down")
          ow:scriptMove(ow.player, "up", 8, function()
-            -- OaksLabFollowedOakScript: flags only after the walk-in, so a
-            -- stray step on the door mat can't fire the "don't go away"
-            -- push-up (oaks_lab.lua onStep) mid-cutscene.  Outdoor escort
-            -- still re-arms on F1 mid-escort -- these flags stay clear
-            -- until the lab walk finishes.
            game.save.flags.EVENT_FOLLOWED_OAK_INTO_LAB = true
            game.save.flags.EVENT_FOLLOWED_OAK_INTO_LAB_2 = true
            Commands.face_object(ctx, 1, "up")
-            -- res BIT_NO_MAP_MUSIC + PlayDefaultMusic: the lab theme
-            -- only starts once the walk-in is done
            Music.playMap(game.data, "OAKS_LAB")
            chooseMonSpeech()
          end)
@@ -179,9 +178,6 @@ M.PALLET_TOWN = {
      end
    end

-    -- PalletMovementScript_Done + the door warp: Oak is hidden as the
-    -- player steps into the doorway; PALLET_TOWN warp 3 -> OAKS_LAB
-    -- warp 2 = (5,11), with the door SFX (WarpFound -> SFX_GO_INSIDE)
    local function enterLab()
      Commands.hide_object(ctx, "PALLET_TOWN", "PALLETTOWN_OAK")
      Commands.show_object(ctx, "OAKS_LAB", "OAKSLAB_OAK2")
@@ -190,10 +186,6 @@ M.PALLET_TOWN = {
                     { keepMusic = true })
    end

-    -- PalletMovementScript_WalkToLab: Oak's NPC movement and the
-    -- player's simulated joypad run simultaneously, in lockstep; the
-    -- player retraces Oak's path one step behind and follows him into
-    -- the doorway on the final beat
    local function walkToLab(oak)
      local i = 0
      local function tick()
@@ -206,9 +198,6 @@ M.PALLET_TOWN = {
        if oak and escort.oakSteps[i] then
          ow:scriptMove(oak, escort.oakSteps[i], 1)
        elseif oak then
-          -- RLEList_ProfOakWalkToLab's trailing NPC_CHANGE_FACING beat:
-          -- Oak marches in place on the door mat while the player takes
-          -- the final step up behind him (movement.asm ChangeFacingDirection)
          ow:marchInPlace(oak)
        end
        ow:scriptMove(ow.player, playerStep, 1, tick)
@@ -216,10 +205,14 @@ M.PALLET_TOWN = {
      tick()
    end

-    -- PalletMovementScript_OakMoveLeft/_PlayerMoveLeft: from the right
-    -- tile (x == 11) Oak sidesteps left first, then the player follows
-    -- left (wNumStepsToTake = wXCoord - 10), and only then both walk
    local function escortToLab(oak)
+      -- PalletMovementScript_OakMoveLeft
+      -- (engine/overworld/auto_movement.asm) starts MUSIC_MUSEUM_GUY
+      -- when the escort begins in Yellow. Until then, Pallet Town plays
+      -- after the battle; Red/Blue leave MUSIC_MEET_PROF_OAK playing.
+      if yellow then
+        Music.play(game.data, "Music_MuseumGuy")
+      end
      local numSteps = x - 10
      if oak and numSteps > 0 then
        ow:scriptMove(oak, "left", numSteps, function()
@@ -232,37 +225,75 @@ M.PALLET_TOWN = {
      end
    end

-    -- ---- Pallet Town side (scripts/PalletTown.asm) -----------------
+    -- After Oak reaches the player: Red goes straight to "It's unsafe!".
+    -- Yellow (PalletTownOakGreetsPlayerScript..AfterPikachuBattleScript):
+    -- ThatWasClose -> Oak faces the grass patch -> BATTLE_TYPE_PIKACHU
+    -- (the old-man-style simulated battle where PROF.OAK throws the ball
+    -- and always catches the lv5 Pikachu) -> Whew -> ComeWithMe.
+    local function afterOakArrives(oak)
+      if not yellow then
+        game.stack:push(TextBox.new(game,
+          t._PalletTownOakItsUnsafeText
+          or "OAK: It's unsafe!\nWild POKéMON\nlive in tall grass!",
+          function() escortToLab(oak) end))
+        return
+      end
+      local function comeWithMe()
+        game.stack:push(TextBox.new(game,
+          t._PalletTownOakComeWithMe
+          or "OAK: Here, come with\nme!",
+          function() escortToLab(oak) end))
+      end
+      local function afterPikaBattle()
+        if oak then oak.facing = "up" end
+        game.stack:push(TextBox.new(game,
+          t._PalletTownOakWhewText or "OAK: Whew...",
+          comeWithMe))
+      end
+      game.stack:push(TextBox.new(game,
+        t._PalletTownOakThatWasCloseText
+        or "OAK: That was\nclose!\fWild POKéMON live\nin tall grass!",
+        function()
+          -- Oak turns toward the horizontally adjacent grass (left exit
+          -- looks right, right exit looks left -- the
+          -- EVENT_PLAYER_AT_RIGHT_EXIT_TO_PALLET_TOWN branch).
+          -- In pokeyellow, PalletTownOakGreetsPlayerScript turns Oak and
+          -- PalletTownPikachuBattleScript arms the battle on the next
+          -- overworld iteration. OverworldLoopLessDelay
+          -- (home/overworld.asm) burns two DelayFrame calls at the top
+          -- of each iteration and calls RunMapScript before checking
+          -- wCurOpponent, so those two DelayFrame calls are what keep
+          -- Oak's turn on screen before the battle check fires.
+          if oak then oak.facing = x == 10 and "right" or "left" end
+          hold(2, nil, function()
+            local battle = BattleState.newWild(game, "PIKACHU", 5)
+            battle:makeOldManDemo("PROF.OAK")
+            battle.onFinish = function()
+              afterPikaBattle()
+            end
+            -- Use the standard wild-battle entry transition.
+            Commands.pushBattle(ctx, battle)
+          end)
+        end))
+    end

-    -- PalletTownOakWalksToPlayerScript: Oak appears at (8,5), faces up
-    -- (SetSpriteFacingDirectionAndDelay + Delay3), then zigzags to the
-    -- player; the "It's unsafe!" text follows and the escort begins
    local function oakAppearsAndWalks()
      Commands.show_object(ctx, "PALLET_TOWN", "PALLETTOWN_OAK")
-      local oak = ow:npcByIndex(1)
+      local oak = npcNamed(ow, "PALLETTOWN_OAK") or ow:npcByIndex(1)
      if oak then oak.facing = "up" end
      hold(6, nil, function()
        walkList(oak, escort.oakApproach(x), function()
-          -- PalletTownOakNotSafeComeWithMeScript: the second text waits
-          -- for a button, then the escort starts
-          game.stack:push(TextBox.new(game,
-            t._PalletTownOakItsUnsafeText
-            or "OAK: It's unsafe!\nWild POKéMON\nlive in tall grass!",
-            function() escortToLab(oak) end))
+          afterOakArrives(oak)
        end)
      end)
    end

-    -- The "Hey! Wait!" box ends without a button wait (auto), then the
-    -- "!" bubble shows over the player WHILE the box is still on screen
-    -- (PalletTownOakText: DelayFrames 10 then EmotionBubble, box not yet
-    -- cleared).  onOverlap sets the bubble during the box's last frames;
-    -- the box pops after `overlap`, and the bubble's 60-frame hold then
-    -- runs to Oak's appearance (the bubble is static while the box is up,
-    -- since the overworld pauses under it, so 10 overlap + 50 = 60).
    game.stack:push(TextBox.new(game,
      t._PalletTownOakHeyWaitDontGoOutText or "OAK: Hey! Wait!\nDon't go out!",
      nil, { auto = { delay = 10, overlap = 10, onOverlap = function()
+        -- .HeyWaitDontGoOutText turns the player to face down (toward
+        -- the approaching Oak) before the exclamation bubble
+        ow.player.facing = "down"
        ow.emote = { npc = ow.player, frames = 50, onDone = oakAppearsAndWalks }
      end } }))
    return true
@@ -386,35 +417,163 @@ M.POKEMON_FAN_CLUB = {
    TEXT_POKEMONFANCLUB_CHAIRMAN = {
      { "face_player" },                                          -- 1
      { "check_flag", "EVENT_RECEIVED_BIKE_VOUCHER" },            -- 2
-      { "jump_if_true", 9 },                                      -- 3
-      { "show_text", "_PokemonFanClubChairmanIntroText" },        -- 4
-      { "show_text", "_PokemonFanClubChairmanStoryText" },        -- 5
+      { "jump_if_true", "nothing_left" },                         -- 3
+      -- YesNoChoice (scripts/PokemonFanClub.asm): NO forfeits the voucher (#1050)
+      { "ask", "_PokemonFanClubChairmanIntroText" },              -- 4
+      { "jump_if_false", "no_story" },                            -- 5
+      { "show_text", "_PokemonFanClubChairmanStoryText" },        -- 6
      -- give-then-print like scripts/PokemonFanClub.asm (GiveItem
      -- fills wStringBuffer; the received text reads it)
-      { "give_item", "BIKE_VOUCHER", 1, false },                  -- 6
-      { "show_text", "_PokemonFanClubReceivedBikeVoucherText" },  -- 7
-      { "set_flag", "EVENT_RECEIVED_BIKE_VOUCHER" },              -- 8
-      { "show_text", "_PokemonFanClubExplainBikeVoucherText" },   -- 9
+      { "give_item", "BIKE_VOUCHER", 1, false },                  -- 7
+      { "show_text", "_PokemonFanClubReceivedBikeVoucherText" },  -- 8
+      { "set_flag", "EVENT_RECEIVED_BIKE_VOUCHER" },              -- 9
+      { "show_text", "_PokemonFanClubExplainBikeVoucherText" },   -- 10
+      { "jump", "end" },                                          -- 11
+      { "label", "no_story" },                                    -- 12
+      { "show_text", "_PokemonFanClubNoStoryText" },              -- 13
+      { "jump", "end" },                                          -- 14
+      -- .nothingleft: the gift is done, he only reminisces now
+      { "label", "nothing_left" },                                -- 15
+      { "show_text", "_PokemonFanClubChairFinalText" },           -- 16
    },
  },
 }

+-- BikeShopClerkText (scripts/BikeShop.asm) runs three ways: the BICYCLE is
+-- already yours, you are carrying the BIKE VOUCHER, or you get the sales
+-- pitch.  The pitch draws its own window (TextBoxBorder hlcoord 0,0, b=4
+-- c=15) holding BikeShopMenuText and BikeShopMenuPrice, and leaves it up
+-- while the clerk keeps talking in the bottom box: the original never
+-- erases it before TextScriptEnd (#568).
+local BikeShopWindow = {}
+BikeShopWindow.__index = BikeShopWindow
+
+function BikeShopWindow.new(game, footer, onChoose)
+  local self = setmetatable({}, BikeShopWindow)
+  self.game = game
+  self.onChoose = onChoose
+  self.index = 1
+  self.active = true
+  -- BikeShopClerkDoYouLikeItText stays on screen under the window for as
+  -- long as the menu is up.  The text box pushed on top types it out and
+  -- pops itself; this copy of its last page takes over from there, so the
+  -- bottom box never blanks between the pitch and the answer.  Paginated
+  -- with the themed column budget so the copy breaks where the box did.
+  local TextBox = require("src.render.TextBox")
+  local box = require("src.ui.Theme").textBox or {}
+  local pages = TextBox.paginate(TextBox.substitute(game, footer), box.maxCols)
+  self.footer = pages[#pages]
+  return self
+end
+
+function BikeShopWindow:update()
+  -- one answer only: the boxes pushed by onChoose sit on top of this
+  -- state, but a second A on the same frame must not fire it twice
+  if not self.active then return end
+  local input = self.game.input
+  -- HandleMenuInput with wMenuWrappingEnabled clear: the two rows clamp
+  if input:wasPressed("up") then
+    self.index = 1
+  elseif input:wasPressed("down") then
+    self.index = 2
+  elseif input:wasPressed("a") or input:wasPressed("b") then
+    local cancelled = input:wasPressed("b") -- bit B_PAD_B -> .cancel
+    require("src.core.Sound").play(self.game.data, "Press_AB")
+    self.active = false
+    self.onChoose(not cancelled and self.index == 1)
+  end
+end
+
+function BikeShopWindow:draw()
+  local Font = require("src.render.Font")
+  local Strings = require("src.core.Strings")
+  local Theme = require("src.ui.Theme")
+  Font.drawBox(0, 0, 17, 6)
+  love.graphics.setColor(0, 0, 0, 1)
+  local bike = self.game.data.items.BICYCLE
+  Font.draw(bike and bike.name or "BICYCLE", 16, 16)  -- hlcoord 2, 2
+  Font.draw("¥1000000", 64, 24)                       -- hlcoord 8, 3
+  Font.draw(Strings("CANCEL"), 16, 32)                -- `next` skips a row
+  -- wTopMenuItemX 1, wTopMenuItemY 2, rows two apart
+  Font.drawCode(Theme.cursor, 8, self.index == 1 and 16 or 32)
+  if self.footer then
+    -- same geometry TextBox resolves against, so a themed box matches
+    local box = Theme.textBox or {}
+    local tx, ty = box.tx or 0, box.ty or 12
+    love.graphics.setColor(1, 1, 1, 1)
+    Font.drawBox(tx, ty, box.tw or 20, box.th or 6)
+    love.graphics.setColor(0, 0, 0, 1)
+    for i, line in ipairs(self.footer) do
+      Font.draw(line, (tx + 1) * 8, (ty + 2 * i) * 8)
+    end
+  end
+  love.graphics.setColor(1, 1, 1, 1)
+end
+
 M.BIKE_SHOP = {
  talk = {
    TEXT_BIKESHOP_CLERK = function(game, ow, npc, done)
+      local Bag = require("src.inventory.Bag")
+      local Flags = require("src.script.Flags")
      local TextBox = require("src.render.TextBox")
-      if (game.save.inventory.BICYCLE or 0) > 0 then
-        game.stack:push(TextBox.new(game, "How's the\nBICYCLE treating\nyou?", done))
-      elseif (game.save.inventory.BIKE_VOUCHER or 0) > 0 then
-        game.save.inventory.BIKE_VOUCHER = nil
-        game.save.inventory.BICYCLE = 1
-        game.stack:push(TextBox.new(game,
-          ("Oh, that's a\nBIKE VOUCHER!\f%s exchanged\nit for a BICYCLE!")
-          :format(game.save.player.name), done))
-      else
-        game.stack:push(TextBox.new(game,
-          "A BICYCLE costs\n¥1000000. Sorry,\nno instalments!", done))
+      local t = game.data.text
+      local function say(text, after, opts)
+        game.stack:push(TextBox.new(game, text, after, opts))
      end
+
+      -- CheckEvent EVENT_GOT_BICYCLE.  Saves made before the clerk started
+      -- setting the event still have the bike in the bag, so either counts.
+      if (game.save.inventory.BICYCLE or 0) > 0
+          or Flags.get(game.save, "EVENT_GOT_BICYCLE") then
+        say(t._BikeShopClerkHowDoYouLikeYourBicycleText, done)
+        return
+      end
+
+      -- .dontHaveBike: IsItemInBag BIKE_VOUCHER
+      if (game.save.inventory.BIKE_VOUCHER or 0) > 0 then
+        say(t._BikeShopClerkOhThatsAVoucherText, function()
+          -- GiveItem's `jr nc, .BagFull`: the voucher is only spent once
+          -- the BICYCLE is actually in the bag
+          if not Bag.add(game.save, "BICYCLE", 1) then
+            say(t._BikeShopBagFullText, done)
+            return
+          end
+          Bag.remove(game.save, "BIKE_VOUCHER", 1)
+          Flags.set(game.save, "EVENT_GOT_BICYCLE")
+          -- BikeShopExchangedVoucherText carries sound_get_key_item; the
+          -- map runs EnableAutoTextBoxDrawing, so the box still waits for
+          -- a button once the jingle has played (auto.wait, #247)
+          say(t._BikeShopExchangedVoucherText, done, {
+            auto = { wait = true, sound = function()
+              return require("src.core.Sound").play(game.data, "Get_Key_Item")
+            end },
+          })
+        end)
+        return
+      end
+
+      -- .dontHaveVoucher: welcome, then the BICYCLE/CANCEL window
+      say(t._BikeShopClerkWelcomeText, function()
+        local pitch = t._BikeShopClerkDoYouLikeItText
+        game.stack:push(BikeShopWindow.new(game, pitch, function(bought)
+          local function comeAgain()
+            say(t._BikeShopComeAgainText, function()
+              game.stack:pop() -- the window, still up under the text
+              done()
+            end)
+          end
+          if bought then
+            -- a million is out of anyone's reach: BikeShopCantAffordText
+            say(t._BikeShopCantAffordText, comeAgain)
+          else
+            comeAgain()
+          end
+        end))
+        -- PrintText BikeShopClerkDoYouLikeItText, then straight into
+        -- HandleMenuInput: the box types out and hands over without
+        -- waiting, leaving the window's copy of the line on screen
+        say(pitch, nil, { auto = { delay = 0 } })
+      end)
    end,
  },
 }
@@ -445,33 +604,67 @@ local function engageSuperNerd(game, ow, onDone)
  ow:engageTrainer(nerd, onDone)
 end

-local function mtMoonFossil(itemId, otherName)
+-- MtMoonB2FMoveSuperNerdScript: player-near-dome coords walk RIGHT then
+-- UP (MoveRight falls through into MoveUp); near-helix walks UP only.
+local function mtMoonNerdWalk(px, py, itemId)
+  if (px == 12 and py == 7) or (px == 11 and py == 6) or (px == 12 and py == 5) then
+    return { "right", "up" }
+  end
+  if (px == 13 and py == 7) or (px == 14 and py == 6) or (px == 14 and py == 5) then
+    return { "up" }
+  end
+  return (itemId == "DOME_FOSSIL") and { "right", "up" } or { "up" }
+end
+
+-- scripts/MtMoonB2F.asm Dome/Helix fossil text_asm + MoveSuperNerd +
+-- SuperNerdTakesOtherFossil: pick one, hide it, walk the nerd to the
+-- other, "All right. Then this is mine!", hide the other.
+local function mtMoonFossil(itemId, otherName, gotFlag)
  return function(game, ow, npc, done)
    local TextBox = require("src.render.TextBox")
-    local ChoiceBox = require("src.ui.ChoiceBox")
-    if game.save.flags.EVENT_GOT_A_FOSSIL then
-      game.stack:push(TextBox.new(game, "You already took\na fossil.", done))
+    local t = game.data.text
+    local flags = game.save.flags
+    if flags.EVENT_GOT_DOME_FOSSIL or flags.EVENT_GOT_HELIX_FOSSIL then
+      done()
      return
    end
-    -- can't grab a fossil until the Super Nerd is beaten -- he intercepts
    if not superNerdBeaten(ow) then
      engageSuperNerd(game, ow, done)
      return
    end
-    local name = game.data.items[itemId].name
-    game.stack:push(TextBox.new(game, ("You want the\n%s?"):format(name), function()
-      game.stack:push(ChoiceBox.new(game, function(yes)
-        if not yes then done() return end
-        game.save.inventory[itemId] = 1
-        game.save.flags.EVENT_GOT_A_FOSSIL = true
-        local Commands = require("src.script.Commands")
-        local ctx = { save = game.save, overworld = ow, game = game }
-        Commands.hide_object(ctx, "MT_MOON_B2F", npc.def.name)
-        Commands.hide_object(ctx, "MT_MOON_B2F", otherName)
+    local want = (itemId == "DOME_FOSSIL")
+      and (t._MtMoonB2FDomeFossilYouWantText or "You want the\nDOME FOSSIL?")
+      or (t._MtMoonB2FHelixFossilYouWantText or "You want the\nHELIX FOSSIL?")
+    game.stack:push(TextBox.new(game, want, nil, { choice = function(yes)
+      if not yes then done() return end
+      if not require("src.inventory.Bag").add(game.save, itemId, 1) then
        game.stack:push(TextBox.new(game,
-          ("%s got the\n%s!"):format(game.save.player.name, name), done))
-      end))
-    end))
+          t._MtMoonB2FYouHaveNoRoomText or "Look, you've got\nno room for this.",
+          done))
+        return
+      end
+      local idef = game.data.items[itemId]
+      game.stringBuffer = idef and idef.name or itemId
+      require("src.core.Sound").play(game.data, "Get_Key_Item")
+      local dirs = mtMoonNerdWalk(ow.player.cellX, ow.player.cellY, itemId)
+      game.stack:push(TextBox.new(game,
+        t._MtMoonB2FReceivedFossilText
+          or ("{PLAYER} got the\n" .. game.stringBuffer .. "!"),
+        function()
+          local Commands = require("src.script.Commands")
+          Commands.hide_object(
+            { save = game.save, overworld = ow, game = game },
+            "MT_MOON_B2F", npc.def.name)
+          flags[gotFlag] = true
+          ow.runner:run({
+            { "walk_npc", 1, dirs },
+            { "text_opts", { auto = true } },
+            { "show_text", "_MtMoonB2FSuperNerdThenThisIsMineText" },
+            { "play_sound", "Get_Key_Item" },
+            { "hide_object", "MT_MOON_B2F", otherName },
+          }, { onDone = done })
+        end))
+    end }))
  end
 end

@@ -486,13 +679,17 @@ M.MT_MOON_B2F = {
    return false
  end,
  talk = {
-    TEXT_MTMOONB2F_DOME_FOSSIL = mtMoonFossil("DOME_FOSSIL", "MTMOONB2F_HELIX_FOSSIL"),
-    TEXT_MTMOONB2F_HELIX_FOSSIL = mtMoonFossil("HELIX_FOSSIL", "MTMOONB2F_DOME_FOSSIL"),
+    TEXT_MTMOONB2F_DOME_FOSSIL = mtMoonFossil(
+      "DOME_FOSSIL", "MTMOONB2F_HELIX_FOSSIL", "EVENT_GOT_DOME_FOSSIL"),
+    TEXT_MTMOONB2F_HELIX_FOSSIL = mtMoonFossil(
+      "HELIX_FOSSIL", "MTMOONB2F_DOME_FOSSIL", "EVENT_GOT_HELIX_FOSSIL"),
  },
 }

 -- The ticket clerk (scripts/Museum1F.asm Museum1FScientist1Text):
-- Y50, once; declining at the rope walks you back out.
+-- Y50, once.  Declining at the rope shoves the player one tile SOUTH back off
+-- the exhibit rope they crossed heading north (#151); the museum floor has no
+-- ledges, so a plain scriptMove("down",1) is the correct primitive.
 local function museumClerk(game, ow, done, onDecline)
  local TextBox = require("src.render.TextBox")
  local ChoiceBox = require("src.ui.ChoiceBox")
@@ -527,7 +724,7 @@ M.MUSEUM_1F = {
    if y == 4 and (x == 9 or x == 10)
       and not game.save.flags.EVENT_BOUGHT_MUSEUM_TICKET then
      museumClerk(game, ow, nil, function()
-        ow:scriptMove(ow.player, "right", 1)
+        ow:scriptMove(ow.player, "down", 1)
      end)
      return true
    end
@@ -719,73 +916,174 @@ M.CINNABAR_LAB_FOSSIL_ROOM = {
 -- -------------------------------------------------------------------
 -- Day-care (scripts/Daycare.asm): the boarded Pokémon earns 1 exp per
 -- step; the fee is ¥100 plus ¥100 per level gained.
+--
+-- #118: do not raise mon.level until a paid retrieve (pokered reverts
+-- wDayCareMonBoxLevel on .leaveMonInDayCare). Fold pending steps into
+-- mon.exp once and clear them so a second talk cannot re-apply the same
+-- walk. Fill {RAM:wNameBuffer}/{RAM:wDayCareMonName}/{NUM:...} here --
+-- TextBox.TOKENS.RAM only knows wStringBuffer.
 -- -------------------------------------------------------------------

+local function fillDaycareText(s, subs)
+  s = s:gsub("{PLAYER}", subs.player or "")
+  s = s:gsub("{RAM:([^}]*)}", function(name) return subs[name] or "" end)
+  -- extractor NUM spans may include flags after a comma; keep the name
+  s = s:gsub("{NUM:([%w_]+)[^}]*}", function(name)
+    return tostring(subs[name] or "0")
+  end)
+  return s
+end
+
 M.DAYCARE = {
  talk = {
    TEXT_DAYCARE_GENTLEMAN = function(game, ow, npc, done)
      local TextBox = require("src.render.TextBox")
-      local ChoiceBox = require("src.ui.ChoiceBox")
      local t = game.data.text
      local dc = game.save.daycare
+      local playerName = game.save.player and game.save.player.name or "RED"
+
+      local function monName(mon)
+        local def = game.data.pokemon[mon.species]
+        return mon.nickname or (def and def.name) or mon.species
+      end

      if dc and dc.mon then
        local Growth = require("src.pokemon.Growth")
        local Stats = require("src.pokemon.Stats")
+        local Party = require("src.pokemon.Party")
        local mon = dc.mon
        local def = game.data.pokemon[mon.species]
-        mon.exp = mon.exp + (dc.steps or 0)
-        local newLevel = math.min(100, Growth.levelForExp(def.growthRate, mon.exp))
-        local fee = 100 + (newLevel - mon.level) * 100
-        local grew = newLevel > mon.level
-        mon.level = newLevel
-        mon.stats = Stats.calc(def, mon.level, mon.dvs, mon.statExp)
-        mon.hp = mon.stats.hp
-        local msg = grew and (t._DaycareGentlemanMonHasGrownText or "It's grown a lot!")
-                    or "Back already?"
-        game.stack:push(TextBox.new(game,
-          msg .. ("\fThe fee is ¥%d.\nGet it back?"):format(fee), function()
-          game.stack:push(ChoiceBox.new(game, function(yes)
-            if yes and game.save.money >= fee then
+        -- Apply deferred step-exp once (OverworldController only bumps
+        -- daycare.steps). Clearing prevents double-count on re-talk.
+        mon.exp = (mon.exp or 0) + (dc.steps or 0)
+        dc.steps = 0
+        -- depositLevel mirrors wDayCareMonBoxLevel: fee baseline that
+        -- must survive a declined retrieve. Fall back to mon.level for
+        -- older saves that predate the field.
+        if dc.depositLevel == nil then dc.depositLevel = mon.level end
+        local startLevel = dc.depositLevel
+        local newLevel = Growth.levelForExp(def and def.growthRate, mon.exp)
+        if newLevel >= 100 then
+          newLevel = 100
+          if def then
+            mon.exp = Growth.expForLevel(def.growthRate, 100)
+          end
+        end
+        local levelsGrown = math.max(0, newLevel - startLevel)
+        local fee = 100 + levelsGrown * 100
+        local name = monName(mon)
+        local subs = {
+          player = playerName,
+          wNameBuffer = name,
+          wDayCareMonName = name,
+          wDayCareNumLevelsGrown = levelsGrown,
+          wDayCareTotalCost = fee,
+        }
+        local statusText = levelsGrown > 0
+          and (t._DaycareGentlemanMonHasGrownText
+            or "Your {RAM:wNameBuffer}\nhas grown a lot!\fBy level, it's\ngrown by {NUM:wDayCareNumLevelsGrown, 1, 3}!\fAren't I great?")
+          or (t._DaycareGentlemanMonNeedsMoreTimeText
+            or "Back already?\nYour {RAM:wNameBuffer}\nneeds some more\ntime with me.")
+
+        game.stack:push(TextBox.new(game, fillDaycareText(statusText, subs), function()
+          if #game.save.party >= Party.MAX then
+            game.stack:push(TextBox.new(game,
+              t._DaycareGentlemanNoRoomForMonText
+                or "You have no room\nfor this POKéMON!", done))
+            return
+          end
+          game.stack:push(TextBox.new(game,
+            fillDaycareText(
+              t._DaycareGentlemanOweMoneyText
+                or "You owe me ¥{NUM:wDayCareTotalCost, 2 | LEADING_ZEROES | LEFT_ALIGN}\nfor the return\nof this POKéMON.",
+              subs),
+            nil, { choice = function(yes)
+              if not yes then
+                -- .leaveMonInDayCare: revert any transient level bump
+                mon.level = startLevel
+                game.stack:push(TextBox.new(game,
+                  (t._DaycareGentlemanAllRightThenText or "All right then,\n")
+                    .. (t._DaycareGentlemanComeAgainText or "come again."),
+                  done))
+                return
+              end
+              if (game.save.money or 0) < fee then
+                mon.level = startLevel
+                game.stack:push(TextBox.new(game,
+                  t._DaycareGentlemanNotEnoughMoneyText
+                    or "Hey, you don't\nhave enough ¥!", done))
+                return
+              end
              game.save.money = game.save.money - fee
+              mon.level = newLevel
+              if def then
+                mon.stats = Stats.calc(def, mon.level, mon.dvs, mon.statExp)
+                mon.hp = mon.stats.hp
+                -- Daycare.asm: WriteMonMoves with wLearningMovesFromDayCare
+                local Pokemon = require("src.pokemon.Pokemon")
+                Pokemon.learnMovesFromDayCare(
+                  game.data, mon, def, startLevel, newLevel)
+              end
              table.insert(game.save.party, mon)
              game.save.daycare = nil
              game.stack:push(TextBox.new(game,
-                t._DaycareGentlemanGotMonBackText or "Here you go!", done))
-            else
-              game.stack:push(TextBox.new(game,
-                yes and (t._DaycareGentlemanOweMoneyText or "You owe me money!")
-                    or "Come again!", done))
-            end
-          end))
+                t._DaycareGentlemanHeresYourMonText
+                  or "Thank you! Here's\nyour POKéMON!", function()
+                game.stack:push(TextBox.new(game,
+                  fillDaycareText(
+                    t._DaycareGentlemanGotMonBackText
+                      or "{PLAYER} got\n{RAM:wDayCareMonName} back!",
+                    subs), done))
+              end))
+            end }))
        end))
        return
      end

-      if #game.save.party < 2 then
-        game.stack:push(TextBox.new(game,
-          "You only have one\nPOKéMON with you!", done))
-        return
-      end
      game.stack:push(TextBox.new(game,
-        t._DaycareGentlemanIntroText or "I can raise a\nPOKéMON for you.", function()
-        game.stack:push(ChoiceBox.new(game, function(yes)
-          if not yes then done() return end
-          local PartyMenu = require("src.ui.PartyMenu")
-          game.stack:push(PartyMenu.new(game, {
-            pickOnly = true,
-            onSwitch = function(mon)
-              for i, m in ipairs(game.save.party) do
-                if m == mon then table.remove(game.save.party, i) break end
-              end
-              game.save.daycare = { mon = mon, steps = 0 }
-              game.stack:push(TextBox.new(game,
-                t._DaycareGentlemanWillLookAfterMonText or
-                "Fine, I'll look\nafter it a while!", done))
-            end,
-          }))
-        end))
-      end))
+        t._DaycareGentlemanIntroText
+          or "I run a DAYCARE.\nWould you like me\nto raise one of\nyour POKéMON?",
+        nil, { choice = function(yes)
+          if not yes then
+            game.stack:push(TextBox.new(game,
+              t._DaycareGentlemanComeAgainText or "come again.", done))
+            return
+          end
+          if #game.save.party < 2 then
+            game.stack:push(TextBox.new(game,
+              t._DaycareGentlemanOnlyHaveOneMonText
+                or "You only have one\nPOKéMON with you.", done))
+            return
+          end
+          game.stack:push(TextBox.new(game,
+            t._DaycareGentlemanWhichMonText or "Which POKéMON\nshould I raise?",
+            function()
+              local PartyMenu = require("src.ui.PartyMenu")
+              game.stack:push(PartyMenu.new(game, {
+                pickOnly = true,
+                onSwitch = function(mon)
+                  for i, m in ipairs(game.save.party) do
+                    if m == mon then table.remove(game.save.party, i) break end
+                  end
+                  local name = monName(mon)
+                  -- depositLevel = wDayCareMonBoxLevel at deposit time
+                  game.save.daycare = {
+                    mon = mon, steps = 0, depositLevel = mon.level,
+                  }
+                  game.stack:push(TextBox.new(game,
+                    fillDaycareText(
+                      t._DaycareGentlemanWillLookAfterMonText
+                        or "Fine, I'll look\nafter {RAM:wNameBuffer}\nfor a while.",
+                      { player = playerName, wNameBuffer = name }),
+                    function()
+                      game.stack:push(TextBox.new(game,
+                        t._DaycareGentlemanComeSeeMeInAWhileText
+                          or "Come see me in\na while.", done))
+                    end))
+                end,
+              }))
+            end))
+        end }))
    end,
  },
 }
@@ -13,16 +13,30 @@ local function push(game, s, done)
  game.stack:push(TextBox.new(game, s, done))
 end

+-- The question stays on screen under the YES/NO menu.  The dojo prize
+-- balls are the clearest case: FightingDojoHitmonleePokeBallText
+-- (scripts/FightingDojo.asm) is `call PrintText` on a text_end string --
+-- no prompt, so no WaitForTextScrollButtonPress -- immediately followed
+-- by `call YesNoChoice`, and InitYesNoTextBoxParameters
+-- (engine/menus/text_box.asm) puts the menu above the dialogue box
+-- rather than replacing it.  Ride TextBox's opts.choice, the same as
+-- Commands.ask, instead of popping the box with an A press and leaving a
+-- bare ChoiceBox over the overworld (#854).
 local function ask(game, s, cb)
-  local ChoiceBox = require("src.ui.ChoiceBox")
-  push(game, s, function() game.stack:push(ChoiceBox.new(game, cb)) end)
+  local TextBox = require("src.render.TextBox")
+  game.stack:push(TextBox.new(game, s, nil, { choice = cb }))
 end

-- fill the extracted text placeholders ({NUM:...}, {RAM:...}, {PLAYER})
+-- fill text placeholders; key on the hram/wram symbol first, since one
+-- string can carry two different NUM slots (#1006)
 local function fill(s, subs)
  s = s:gsub("{PLAYER}", subs.player or "")
-  s = s:gsub("{NUM:[^}]*}", function() return tostring(subs.num or "") end)
-  s = s:gsub("{RAM:[^}]*}", function() return subs.ram or "" end)
+  s = s:gsub("{NUM:([%w_]*)[^}]*}", function(name)
+    return tostring(subs[name] or subs.num or "")
+  end)
+  s = s:gsub("{RAM:([%w_]*)[^}]*}", function(name)
+    return subs[name] or subs.ram or ""
+  end)
  return s
 end

@@ -37,16 +51,15 @@ local function countOwned(save)
  return n
 end

-local function oaksAide(threshold, itemId)
+local function oaksAide(threshold, itemId, repeatText)
  return function(game, ow, npc, done)
    local t = text(game)
    local flags = game.save.flags
    local itemName = game.data.items[itemId].name
    local flag = "EVENT_GOT_" .. itemId
    if flags[flag] then
-      push(game, fill(t._OaksAideComeBackText or
-        "I already gave\nyou the {RAM:}!",
-        { num = threshold, ram = itemName }), done)
+      push(game, t[repeatText] or
+        fill("I already gave\nyou the {RAM:}!", { ram = itemName }), done)
      return
    end
    ask(game, fill(t._OaksAideHiText or
@@ -74,22 +87,28 @@ local function oaksAide(threshold, itemId)
                { ram = itemName, player = game.save.player.name }), done)
            end)
        else
+          -- .notEnoughOwnedMons prints owned then requirement, two counts
          push(game, fill(t._OaksAideUhOhText or
            "You have only\ncaught {NUM:}!",
-            { num = owned, ram = itemName }), done)
+            { num = owned, ram = itemName,
+              hOaksAideNumMonsOwned = owned,
+              hOaksAideRequirement = threshold }), done)
        end
      end)
  end
 end

 M.ROUTE_2_GATE = {
-  talk = { TEXT_ROUTE2GATE_OAKS_AIDE = oaksAide(10, "HM_FLASH") },
+  talk = { TEXT_ROUTE2GATE_OAKS_AIDE = oaksAide(10, "HM_FLASH",
+    "_Route2GateOaksAideFlashExplanationText") },
 }
 M.ROUTE_11_GATE_2F = {
-  talk = { TEXT_ROUTE11GATE2F_OAKS_AIDE = oaksAide(30, "ITEMFINDER") },
+  talk = { TEXT_ROUTE11GATE2F_OAKS_AIDE = oaksAide(30, "ITEMFINDER",
+    "_Route11Gate2FOaksAideItemfinderDescriptionText") },
 }
 M.ROUTE_15_GATE_2F = {
-  talk = { TEXT_ROUTE15GATE2F_OAKS_AIDE = oaksAide(50, "EXP_ALL") },
+  talk = { TEXT_ROUTE15GATE2F_OAKS_AIDE = oaksAide(50, "EXP_ALL",
+    "_Route15Gate2FOaksAideExpAllText") },
 }

 -- -------------------------------------------------------------------
@@ -134,32 +153,70 @@ M.MT_MOON_POKECENTER = {
 -- Karate Master, take HITMONLEE or HITMONCHAN (the other disappears)
 -- -------------------------------------------------------------------

+-- ownBall/otherBall keep their spots for signature symmetry; only ownBall
+-- is ever hidden (Gen1 removes just the chosen ball).
 local function dojoBall(species, ownBall, otherBall, askKey)
  return function(game, ow, npc, done)
    local t = text(game)
    local flags = game.save.flags
+    -- Already took one prize: the OTHER ball is still on the mat, so
+    -- talking to it now gives the "Better not get greedy..." refusal
+    -- (FightingDojo.asm .gotThePokemon / _FightingDojoBetterNotGetGreedyText),
+    -- not a silent no-op (#197).
    if flags.EVENT_GOT_HITMONLEE or flags.EVENT_GOT_HITMONCHAN then
-      done()
+      push(game, t._FightingDojoBetterNotGetGreedyText
+        or "Better not get\ngreedy...", done)
      return
    end
    if not flags.EVENT_BEAT_KARATE_MASTER then
      push(game, "You'll have to\nbeat the master\nfirst!", done)
      return
    end
-    ask(game, t[askKey] or ("You want\n" .. species .. "?"), function(yes)
-      if not yes then done() return end
-      flags["EVENT_GOT_" .. species] = true
-      flags.EVENT_DEFEATED_FIGHTING_DOJO = true
-      local Commands = require("src.script.Commands")
-      local ctx = { save = game.save, game = game, overworld = ow }
-      Commands.give_pokemon(ctx, species, 30)
-      Commands.hide_object(ctx, "FIGHTING_DOJO", ownBall)
-      Commands.hide_object(ctx, "FIGHTING_DOJO", otherBall)
-      push(game, ("%s got\n%s!"):format(game.save.player.name, species), done)
-    end)
+    -- Examining a ball shows that species' POKéDEX entry first
+    -- (DisplayPokedex in FightingDojo.asm, which also marks it seen),
+    -- then the yes/no take-it prompt (#853).
+    local Commands = require("src.script.Commands")
+    local ctx = { save = game.save, game = game, overworld = ow }
+    Commands.mark_seen(ctx, species)
+    local DexEntryMenu = require("src.ui.DexEntryMenu")
+    game.stack:push(DexEntryMenu.new(game, species, function()
+      ask(game, t[askKey] or ("You want\n" .. species .. "?"), function(yes)
+        if not yes then done() return end
+        flags["EVENT_GOT_" .. species] = true
+        flags.EVENT_DEFEATED_FIGHTING_DOJO = true
+        Commands.give_pokemon(ctx, species, 30)
+        -- Hide ONLY the chosen ball; the other stays (FightingDojo.asm hides
+        -- just the picked object's index) and routes to the greedy line above
+        -- when talked to (#197).
+        Commands.hide_object(ctx, "FIGHTING_DOJO", ownBall)
+        push(game, ("%s got\n%s!"):format(game.save.player.name, species), done)
+      end)
+    end))
  end
 end

+-- FightingDojoDefaultScript does not use the Master's facing direction for
+-- this battle.  It checks exactly the cell left of him, turns both sprites
+-- toward one another, and then displays his trainer text.  Keeping this out
+-- of trainer sight also lets him keep his original downward-facing pose.
+local function dojoMasterGate(game, ow, x, y)
+  if x ~= 4 or y ~= 3 or game.save.flags.EVENT_BEAT_KARATE_MASTER then
+    return false
+  end
+  local master
+  for _, npc in ipairs(ow.npcs) do
+    if npc.def and npc.def.name == "FIGHTINGDOJO_KARATE_MASTER" then
+      master = npc
+      break
+    end
+  end
+  if not master or ow:trainerDefeated(master) then return false end
+  ow.player.facing = "right"
+  master:facePlayer(ow.player)
+  ow:engageTrainer(master)
+  return true
+end
+
 M.FIGHTING_DOJO = {
  talk = {
    TEXT_FIGHTINGDOJO_HITMONLEE_POKE_BALL =
@@ -171,6 +228,22 @@ M.FIGHTING_DOJO = {
               "FIGHTINGDOJO_HITMONLEE_POKE_BALL",
               "_FightingDojoHitmonchanPokeBallText"),
  },
+  -- The two dojo posters on the north wall (FightingDojo.asm bg_events at
+  -- the top of the room, cells (4,0)/(5,0) directly above the prize balls)
+  -- print _EnemiesOnEverySideText.  The map extractor dropped the dojo
+  -- bg_events (signs = {}), so wire the poster read here, the same
+  -- facing-up + coord shape the mansion switches use.  Reachable only once
+  -- a claimed prize frees the ball cell below the poster (#197).
+  onInteract = function(game, ow, fx, fy)
+    if ow.player.facing ~= "up" then return false end
+    if fy == 0 and (fx == 4 or fx == 5) then
+      push(game, text(game)._EnemiesOnEverySideText
+        or "Enemies on every\nside!")
+      return true
+    end
+    return false
+  end,
+  onStep = dojoMasterGate,
 }

 -- -------------------------------------------------------------------
@@ -180,27 +253,32 @@ M.FIGHTING_DOJO = {

 M.SILPH_CO_7F = {
  talk = {
-    TEXT_SILPHCO7F_SILPH_WORKER_M1 = function(game, ow, npc, done)
-      local t = text(game)
-      if game.save.flags.EVENT_GOT_LAPRAS then
-        push(game, t._SilphCo7FSilphWorkerM1LaprasDescriptionText
-          or "How is LAPRAS\ndoing?", done)
-        return
-      end
-      push(game, t._SilphCo7FSilphWorkerM1ThankYouText
-        or "Thank you for\nsaving us!\fI want you to\nhave this LAPRAS!",
-        function()
-          game.save.flags.EVENT_GOT_LAPRAS = true
-          local Commands = require("src.script.Commands")
-          Commands.give_pokemon({ save = game.save, game = game, overworld = ow },
-                                "LAPRAS", 15)
-          push(game, ("%s got\nLAPRAS!"):format(game.save.player.name),
-            function()
-              push(game, t._SilphCo7FSilphWorkerM1LaprasDescriptionText
-                or "It's a good\nswimmer!", done)
-            end)
-        end)
-    end,
+    -- command rows, not a Lua handler: give_pokemon needs a runner to AskName (#1049)
+    TEXT_SILPHCO7F_SILPH_WORKER_M1 = {
+      { "face_player" },
+      { "check_flag", "EVENT_GOT_LAPRAS" },
+      { "jump_if_true", "has_lapras" },
+      { "show_text", "_SilphCo7FSilphWorkerM1HaveThisPokemonText" },
+      { "give_pokemon", "LAPRAS", 15 },
+      { "jump_if_false", "box_full" },
+      -- flag ahead of the jingle, like the Celadon EEVEE (#426)
+      { "set_flag", "EVENT_GOT_LAPRAS" },
+      { "play_sound", "Get_Item1" },
+      { "show_text", "_GotMonText", { RAM = "LAPRAS" } },
+      { "show_text", "_SilphCo7FSilphWorkerM1LaprasDescriptionText" },
+      { "jump", "end" },
+      { "label", "box_full" },
+      { "show_text", "_BoxIsFullText" },
+      { "jump", "end" },
+      -- SilphCo7F.asm .saved_silph gates the thanks on Giovanni
+      { "label", "has_lapras" },
+      { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
+      { "jump_if_true", "saved" },
+      { "show_text", "_SilphCo7FSilphWorkerM1IsOurPresidentOkText" },
+      { "jump", "end" },
+      { "label", "saved" },
+      { "show_text", "_SilphCo7FSilphWorkerM1SavedText" },
+    },
  },
 }

@@ -212,30 +290,31 @@ M.COPYCATS_HOUSE_2F = {
  talk = {
    TEXT_COPYCATSHOUSE2F_COPYCAT = function(game, ow, npc, done)
      local t = text(game)
+      local Bag = require("src.inventory.Bag")
      if game.save.flags.EVENT_GOT_TM31 then
-        push(game, t._CopycatsHouse2FCopycatWhirlingText
-          or "Huh? Huh? Huh?", done)
+        push(game, t._CopycatsHouse2FCopycatTM31Explanation2Text, done)
        return
      end
-      if (game.save.inventory.POKE_DOLL or 0) > 0 then
-        ask(game, t._CopycatsHouse2FCopycatPokeDollText
-          or "Oh wow!\nA POKé DOLL!\fFor me?\nCan I have it?", function(yes)
-          if not yes then done() return end
-          game.save.inventory.POKE_DOLL = game.save.inventory.POKE_DOLL - 1
-          if game.save.inventory.POKE_DOLL == 0 then
-            game.save.inventory.POKE_DOLL = nil
-          end
-          if not require("src.inventory.Bag").add(game.save, "TM_MIMIC", 1) then
-            push(game, "You don't have\nroom for TM31!", done)
+      -- Mimic line first; auto-trade POKE DOLL for TM31 (no YES/NO).
+      push(game, t._CopycatsHouse2FCopycatDoYouLikePokemonText, function()
+        if (game.save.inventory.POKE_DOLL or 0) <= 0 then
+          done()
+          return
+        end
+        push(game, t._CopycatsHouse2FCopycatTM31PreReceiveText, function()
+          if not Bag.add(game.save, "TM_MIMIC", 1) then
+            push(game, t._CopycatsHouse2FCopycatTM31NoRoomText, done)
            return
          end
+          game.stringBuffer = game.data.items.TM_MIMIC.name
+          require("src.core.Sound").play(game.data, "Get_Item1")
+          Bag.remove(game.save, "POKE_DOLL", 1)
          game.save.flags.EVENT_GOT_TM31 = true
-          push(game, ("%s got\nTM31!"):format(game.save.player.name), done)
+          push(game, t._CopycatsHouse2FCopycatReceivedTM31Text, function()
+            push(game, t._CopycatsHouse2FCopycatTM31Explanation1Text, done)
+          end)
        end)
-        return
-      end
-      push(game, t._CopycatsHouse2FCopycatText
-        or "I like to mimic\npeople!", done)
+      end)
    end,
  },
 }
@@ -645,12 +724,44 @@ local function e4ExitSeal(flag, closedBlock, openBlock, dontRunText, autoFlag)
  }
 end

+-- Lorelei/Bruno/Agatha EndBattleScript (pokered): EndTrainerBattle then
+-- DisplayTextID -> TalkToTrainer, which prints the AfterBattle text on a
+-- win.  engageTrainer only shows the won line, so wrap talk like Lance /
+-- Game Corner Rocket and push header.after immediately after a win.
+local function e4LeaderTalk(afterLabel)
+  return function(game, ow, npc, done)
+    done = done or function() end
+    if ow:trainerDefeated(npc) then
+      local after = text(game)[afterLabel]
+      if after then push(game, after, done) else done() end
+      return
+    end
+    ow:engageTrainer(npc, function()
+      if not ow:trainerDefeated(npc) then
+        done()
+        return
+      end
+      local after = text(game)[afterLabel]
+      if after then push(game, after, done) else done() end
+    end)
+  end
+end
+
 M.LORELEIS_ROOM = e4ExitSeal("EVENT_BEAT_LORELEIS_ROOM_TRAINER_0", 0x24, 0x05,
  "_LoreleisRoomLoreleiDontRunAwayText", "EVENT_AUTOWALKED_INTO_LORELEIS_ROOM")
+M.LORELEIS_ROOM.talk = {
+  TEXT_LORELEISROOM_LORELEI = e4LeaderTalk("_LoreleisRoomLoreleiAfterBattleText"),
+}
 M.BRUNOS_ROOM = e4ExitSeal("EVENT_BEAT_BRUNOS_ROOM_TRAINER_0", 0x24, 0x05,
  "_BrunosRoomBrunoDontRunAwayText", "EVENT_AUTOWALKED_INTO_BRUNOS_ROOM")
+M.BRUNOS_ROOM.talk = {
+  TEXT_BRUNOSROOM_BRUNO = e4LeaderTalk("_BrunoAfterBattleText"),
+}
 M.AGATHAS_ROOM = e4ExitSeal("EVENT_BEAT_AGATHAS_ROOM_TRAINER_0", 0x3b, 0x0e,
  "_AgathasRoomAgathaDontRunAwayText", "EVENT_AUTOWALKED_INTO_AGATHAS_ROOM")
+M.AGATHAS_ROOM.talk = {
+  TEXT_AGATHASROOM_AGATHA = e4LeaderTalk("_AgathaAfterBattleText"),
+}

 -- -------------------------------------------------------------------
 -- Lance's room (scripts/LancesRoom.asm). Unlike the other three E4
@@ -672,13 +783,21 @@ M.AGATHAS_ROOM = e4ExitSeal("EVENT_BEAT_AGATHAS_ROOM_TRAINER_0", 0x3b, 0x0e,
 --                 EVENT_LANCES_ROOM_LOCK_DOOR: first crossing seals
 --                 the door behind the player with SFX_GO_INSIDE
 --   (24,16)       the entrance staircase -> WalkToLance: an auto-walk
--                 (up 12, left 12, down 7, left 6) landing on (6,11).
--                 It marches straight across the room's water decor:
--                 pokered's CollisionCheckOnLand skips collision
--                 entirely while simulated joypad states run, and our
--                 scriptMove is collision-free the same way.
+--                 landing on (6,11). Vanilla WalkToLance_RLEList is
+--                 up 12 / left 12 / down 7 / left 6 and skips collision
+--                 through void tiles; our camera follows that literally
+--                 and briefly shows the empty upper chamber (reads as
+--                 "Gary's room"). We keep the same landing cell but
+--                 route along the open-door floor corridor instead.
 -- -------------------------------------------------------------------

+-- Floor corridor (24,16) -> (6,11) with EVENT_LANCES_ROOM_LOCK_DOOR
+-- unset (entrance blocks $31/$32). Exposed for parity tests.
+local LANCE_WALK_IN = {
+  { "down", 2 }, { "left", 6 }, { "down", 5 }, { "left", 10 },
+  { "up", 9 }, { "left", 2 }, { "up", 3 },
+}
+
 local function lanceEntranceBlocks(game, ow)
  local locked = game.save.flags.EVENT_LANCES_ROOM_LOCK_DOOR
  ow:replaceBlock(2, 6, locked and 0x72 or 0x31)
@@ -693,21 +812,24 @@ local function lanceLockDoor(game, ow)
 end

 local function lanceWalkIn(game, ow)
-  ow:scriptMove(ow.player, "up", 12, function()
-    ow:scriptMove(ow.player, "left", 12, function()
-      ow:scriptMove(ow.player, "down", 7, function()
-        ow:scriptMove(ow.player, "left", 6, function()
-          -- the walk lands on (6,11); vanilla's per-frame coord poll
-          -- then locks the door at once. scriptMove landings do not
-          -- fire onStep, so lock here.
-          lanceLockDoor(game, ow)
-        end)
-      end)
-    end)
-  end)
+  local i = 0
+  local function step()
+    i = i + 1
+    local seg = LANCE_WALK_IN[i]
+    if not seg then
+      -- lands on (6,11); vanilla's per-frame coord poll then locks the
+      -- door at once. scriptMove landings do not fire onStep, so lock
+      -- here.
+      lanceLockDoor(game, ow)
+      return
+    end
+    ow:scriptMove(ow.player, seg[1], seg[2], step)
+  end
+  step()
 end

 M.LANCES_ROOM = {
+  walkInRoute = LANCE_WALK_IN,
  onEnter = function(game, ow)
    lanceEntranceBlocks(game, ow)
    -- the warp arrival lands ON the staircase trigger, and onStep only
@@ -727,7 +849,14 @@ M.LANCES_ROOM = {
      end
      if not lance or ow:trainerDefeated(lance) then return false end
      lance:facePlayer(ow.player)
-      ow:engageTrainer(lance, function() end)
+      -- LancesRoomLanceEndBattleScript DisplayTextID -> TalkToTrainer
+      -- after-battle text (rival became champion first). engageTrainer
+      -- only shows the won line, so push the after text on a win.
+      ow:engageTrainer(lance, function()
+        if not ow:trainerDefeated(lance) then return end
+        local after = text(game)._LancesRoomLanceAfterBattleText
+        if after then push(game, after) end
+      end)
      return true
    end
    if (x == 5 or x == 6) and y == 11 then
@@ -49,7 +49,7 @@ local function gift(opts)
        end
      end)
    end
-    if opts.pre then say(opts.pre, "", give) else give() end
+    if opts.pre then say(opts.pre, opts.preFallback or "", give) else give() end
  end
 end

@@ -118,11 +118,21 @@ M.CINNABAR_LAB_METRONOME_ROOM = {
  },
 }

-- TM42 Dream Eater (scripts/ViridianCity.asm, the fisher; no pre text)
+-- TM42 Dream Eater (scripts/ViridianCity.asm, the fisher).  The fisher's
+-- YouCanHaveThisText prints before GiveItem, so this gift needs a pre
+-- text (#775).  Like the SilphCo2F worker (#393) that label carries no
+-- leading underscore, and on Red it sits outside the extractor's symbol
+-- set, so the literal from text/ViridianCity.asm rides along as the
+-- fallback; Yellow resolves the ROM string instead.
 M.VIRIDIAN_CITY = {
  talk = {
    TEXT_VIRIDIANCITY_FISHER = gift({
      flag = "EVENT_GOT_TM42", item = "TM_DREAM_EATER",
+      pre = "ViridianCityFisherYouCanHaveThisText",
+      preFallback = "Yawn!\nI must have dozed\voff in the sun."
+        .. "\fI had this dream\nabout a DROWZEE\veating my dream."
+        .. "\vWhat's this?\vWhere did this TM\vcome from?"
+        .. "\fThis is spooky!\nHere, you can\vhave this TM.",
      received = "_ViridianCityFisherReceivedTM42Text",
      explain = "_ViridianCityFisherTM42ExplanationText",
      noRoom = "_ViridianCityFisherTM42NoRoomText",
@@ -135,6 +145,9 @@ M.SILPH_CO_2F = {
  talk = {
    TEXT_SILPHCO2F_SILPH_WORKER_F = gift({
      flag = "EVENT_GOT_TM36", item = "TM_SELFDESTRUCT",
+      -- the label carries no leading underscore: pokered keeps this one in
+      -- the script bank, not the far-text bank (#393)
+      pre = "SilphCo2FSilphWorkerFPleaseTakeThisText",
      received = "_SilphCo2FSilphWorkerFReceivedTM36Text",
      explain = "_SilphCo2FSilphWorkerFTM36ExplanationText",
      noRoom = "_SilphCo2FSilphWorkerFTM36NoRoomText",
@@ -173,6 +186,20 @@ M.ROUTE_18_GATE_2F = {
      { "face_player" },
      { "trade", 6, "EVENT_TRADED_SLOWBRO_FOR_LICKITUNG" }, -- MARC
    },
+    -- Yellow replaces the youngster with a cook trading SPIKE
+    -- (TANGELA -> PARASECT): pokeyellow/scripts/Route18Gate2F.asm
+    -- Route18Gate2FCookText runs TRADE_FOR_SPIKE, index 6 in the Yellow
+    -- TradeMons table that Data:applyVersionedFieldData swaps in.  Red
+    -- maps have no COOK object here and Yellow maps have no YOUNGSTER,
+    -- so each version only ever fires its own row (#651).  Both rows
+    -- share the Red-flavoured done flag on purpose: a .sav tracks
+    -- "trade slot 6 completed" in one wCompletedInGameTradeFlags bit
+    -- either version reads, and the save codec maps that bit to this
+    -- flag name (src/save_convert/GenSave.lua EXTRA_FLAG_BITS).
+    TEXT_ROUTE18GATE2F_COOK = {
+      { "face_player" },
+      { "trade", 6, "EVENT_TRADED_SLOWBRO_FOR_LICKITUNG" }, -- SPIKE (Yellow)
+    },
  },
 }

@@ -196,14 +223,24 @@ local function inCoords(coords, x, y)
  return false
 end

-- coordinate block: show a line and push the player back one step
+-- coordinate block: show a line and shove the player back one step.  pokered
+-- shoves with a SIMULATED JOYPAD press (scripts/ViridianCity.asm ViridianCity-
+-- CheckGymOpenScript), which runs the normal overworld step pipeline including
+-- HandleLedges (engine/overworld/ledges.asm), so the shove must HOP a ledge
+-- when one sits in front: the tile below the Viridian Gym door is a down-ledge
+-- (#151).  Gates with no ledge in front (Cinnabar gym lock at (18,4)) get
+-- checkLedgeHop == false and fall back to the plain forced step, unchanged.
 local function stepGate(opts)
  return function(game, ow, x, y)
    if not inCoords(opts.coords, x, y) then return false end
    if not opts.blocked(game) then return false end
    require("src.core.Sound").play(game.data, "Denied")
-    push(game, text(game)[opts.text] or opts.fallback,
-         function() ow:scriptMove(ow.player, opts.push, 1) end)
+    push(game, text(game)[opts.text] or opts.fallback, function()
+      ow.player.facing = opts.push
+      if not ow:checkLedgeHop(opts.push) then
+        ow:scriptMove(ow.player, opts.push, 1)
+      end
+    end)
    return true
  end
 end
@@ -262,38 +299,208 @@ M.CINNABAR_ISLAND = {
 -- Pewter's youngster stops you leaving east before Brock is beaten and
 -- escorts you to the gym (scripts/PewterCity.asm
 -- PewterCityCheckPlayerLeavingEastScript /
-- PewterCityYoungsterShowsPlayerGymScript, engine/events/pewter_guys.asm
-- PewterGymGuyCoords): the "follow me" lines, then the player is walked
-- west along the road to the front of the PEWTER_GYM door at (16,17).
+-- PewterCityYoungsterShowsPlayerGymScript, engine/overworld/auto_movement.asm
+-- PewterGymGuyMovementScriptPointerTable, engine/events/pewter_guys.asm
+-- PewterGymGuyCoords).  Same lockstep style as Oak's lab escort: the
+-- youngster walks RLEList_PewterGymGuy while the player plays the
+-- reverse of RLEList_PewterGymPlayer with a PewterGuys positioning
+-- preamble.  Ends at (11,18) / (12,18) by the gym, not phasing through
+-- the building.
+local pewterEscort = {}
+
+-- RLEList_PewterGymGuy (NPC directions play forward)
+pewterEscort.guySteps = {
+  "down", "down",
+  "left", "left", "left", "left", "left", "left", "left", "left",
+  "left", "left", "left", "left", "left", "left", "left",
+  "up", "up", "up", "up", "up",
+  "left", "left", "left", "left", "left", "left", "left", "left",
+  "left", "left", "left",
+  "down", "down", "down", "down", "down",
+  "right", "right", "right",
+}
+
+-- Reverse of guySteps with opposite facings, i.e. the gym-to-spawn
+-- mirror of RLEList_PewterGymGuy.  Kept as the documented inverse that
+-- tests/parity_pewter_escort.lua checks; the youngster does NOT walk it
+-- home any more, because its first step is LEFT through the player
+-- parked on (11,18) (#241).  See walkHome below.
+do
+  local opp = { up = "down", down = "up", left = "right", right = "left" }
+  local ret = {}
+  for i = #pewterEscort.guySteps, 1, -1 do
+    ret[#ret + 1] = opp[pewterEscort.guySteps[i]]
+  end
+  pewterEscort.guyReturnSteps = ret
+end
+
+-- RLEList_PewterGymPlayer before reverse / PewterGuys (NO_INPUT, RIGHT×2,
+-- DOWN×5, LEFT×11, UP×5, LEFT×15)
+pewterEscort.playerRle = {
+  "NO",
+  "right", "right",
+  "down", "down", "down", "down", "down",
+  "left", "left", "left", "left", "left", "left", "left", "left",
+  "left", "left", "left",
+  "up", "up", "up", "up", "up",
+  "left", "left", "left", "left", "left", "left", "left", "left",
+  "left", "left", "left", "left", "left", "left", "left",
+}
+
+-- PewterGymGuyCoords: (x, y) -> positioning moves written after the RLE
+-- (played in reverse; $00 pauses are one overworld frame ≈ 1/8 tile for
+-- the NPC, so eight of them ≈ one guy head-start step)
+pewterEscort.preambles = {
+  ["34,16"] = { "left", "down", "down", "right" },
+  ["35,17"] = { "left", "down", "right", "left" },
+  ["37,18"] = { "left", "left", "left",
+                "NO", "NO", "NO", "NO", "NO", "NO", "NO", "NO" },
+  ["37,19"] = { "left", "left", "up", "left" },
+  ["36,17"] = { "left", "down", "left",
+                "NO", "NO", "NO", "NO", "NO", "NO", "NO", "NO" },
+}
+
+-- Realized player path for a trigger tile: PewterGuys overwrites the
+-- last RLE byte and appends the preamble, then simulated joypad plays
+-- high→low (reverse).  Leading NO×8 collapses to guyHeadStart=1; the
+-- trailing end-of-list NO is dropped (one-frame pause).
+function pewterEscort.playerPlan(x, y)
+  local pre = pewterEscort.preambles[x .. "," .. y]
+  if not pre then return nil end
+  local buf = {}
+  for i, d in ipairs(pewterEscort.playerRle) do buf[i] = d end
+  buf[#buf] = pre[1]
+  for i = 2, #pre do buf[#buf + 1] = pre[i] end
+  local path = {}
+  for i = #buf, 1, -1 do path[#path + 1] = buf[i] end
+  local head = 0
+  while path[head + 1] == "NO" do head = head + 1 end
+  local tail = #path
+  while tail > head and path[tail] == "NO" do tail = tail - 1 end
+  local steps = {}
+  for i = head + 1, tail do steps[#steps + 1] = path[i] end
+  return { steps = steps, guyHeadStart = math.floor(head / 8) }
+end
+
+local function pewterGymEscort(game, ow)
+  if ow.runner:isRunning() or #ow.scriptMoves > 0 then return end
+  local x, y = ow.player.cellX, ow.player.cellY
+  local plan = pewterEscort.playerPlan(x, y)
+  local Music = require("src.core.Music")
+  local t = text(game)
+  local follow = t._PewterCityYoungsterYoureATrainerFollowMeText
+    or "You're a trainer\nright? BROCK's\nlooking for new\nchallengers!\nFollow me!"
+  -- PewterGuys only has entries for five tiles; an unmatched talk tile
+  -- (e.g. (36,16) east of him) just gets the follow-me line, same as a
+  -- failed coords lookup would refuse to arm the walk.
+  if not plan then
+    push(game, follow)
+    return
+  end
+  local guy = ow:npcByIndex(5) -- PEWTERCITY_YOUNGSTER
+  local guySteps = pewterEscort.guySteps
+  local head = plan.guyHeadStart
+
+  -- After the walk: face the player, restore map music, "Go take on
+  -- BROCK", then MovementData_PewterGymGuyExit -- five steps RIGHT out of
+  -- (12,18), the cell PewterCityYoungsterShowsPlayerGymScript pins him to
+  -- with SetSpritePosition1 (hSpriteMapXCoord 16 / hSpriteMapYCoord 22,
+  -- minus the +4 border offset object_event coords carry per
+  -- macros/scripts/maps.asm) and exactly where the escort leaves him.
+  -- That lands him on (17,18), the last walkable cell before the fence at
+  -- (18,18) and one column past the screen edge with the player parked on
+  -- (11,18).  PewterCityHideYoungsterScript then HideObject's him and
+  -- PewterCityResetYoungsterScript's SetSpritePosition2 + ShowObject put
+  -- him back on his object_event spawn (35,16) facing DOWN, which is the
+  -- snap below (the vanish/reappear is off screen, same as the original).
+  --
+  -- The old code retraced guyReturnSteps instead, whose first step is
+  -- LEFT into (11,18) -- the cell the player is standing on -- and
+  -- scriptMove is a pure tween with no entity test, so he walked straight
+  -- through Red (#241).  There is no honest route home: (17,18) is a
+  -- dead-end pocket ((18,18) fence, (17,17) wall), which is precisely why
+  -- the original teleports.  guyReturnSteps stays as the documented
+  -- mirror of RLEList_PewterGymGuy that parity_pewter_escort asserts.
+  -- Brock victory still HideObject's him.
+  local function walkHome()
+    if not guy then return end
+    local i = 0
+    local function tick()
+      i = i + 1
+      if i > 5 then
+        -- SetSpritePosition2: same field writes as Commands.place_npc,
+        -- including the target clear -- a stale targetX/targetY would
+        -- leave OverworldState:npcAtCell reserving (17,18) forever and
+        -- silently wall the player out of that pocket.
+        guy.cellX, guy.cellY = 35, 16
+        guy.px, guy.py = 35 * 16, 16 * 16
+        guy.moving = false
+        guy.targetX, guy.targetY = nil, nil
+        guy.facing = "down"
+        return
+      end
+      ow:scriptMove(guy, "right", 1, tick)
+    end
+    tick()
+  end
+
+  local function afterWalk()
+    if guy then guy.facing = "left" end
+    Music.playMap(game.data, "PEWTER_CITY")
+    push(game, t._PewterCityYoungsterGoTakeOnBrockText
+      or "Go take on BROCK\nat the GYM first!", walkHome)
+  end
+
+  local function lockstep()
+    local i = 0
+    local function tick()
+      i = i + 1
+      local ps = plan.steps[i]
+      if not ps then
+        afterWalk()
+        return
+      end
+      local gs = guySteps[head + i]
+      if guy and gs then ow:scriptMove(guy, gs, 1) end
+      ow:scriptMove(ow.player, ps, 1, tick)
+    end
+    tick()
+  end
+
+  local function beginWalk()
+    Music.play(game.data, "Music_MuseumGuy")
+    if guy and head > 0 then
+      local h = 0
+      local function headTick()
+        h = h + 1
+        if h > head then lockstep(); return end
+        ow:scriptMove(guy, guySteps[h], 1, headTick)
+      end
+      headTick()
+    else
+      lockstep()
+    end
+  end
+
+  push(game, follow, beginWalk)
+end
+
 M.PEWTER_CITY = {
+  escort = pewterEscort,
+  -- PewterCityYoungsterText: talking also arms the gym escort script
+  talk = {
+    TEXT_PEWTERCITY_YOUNGSTER = function(game, ow, npc, done)
+      pewterGymEscort(game, ow)
+      if done then done() end
+    end,
+  },
  onStep = function(game, ow, x, y)
    if game.save.flags.EVENT_BEAT_BROCK then return false end
    if ow.runner:isRunning() or #ow.scriptMoves > 0 then return false end
    if not inCoords({ { 35, 17 }, { 36, 17 }, { 37, 18 }, { 37, 19 } }, x, y) then
      return false
    end
-    local t = text(game)
-    -- walk up onto the road row (y=17), west to one tile east of the gym
-    -- door, then drop below the door and turn to face it
-    local steps = {}
-    for _ = 1, y - 17 do steps[#steps + 1] = "up" end
-    for _ = 1, x - 17 do steps[#steps + 1] = "left" end
-    steps[#steps + 1] = "down"
-    steps[#steps + 1] = "left"
-    local function walk(i)
-      if not steps[i] then
-        ow.player.facing = "up"
-        return
-      end
-      ow:scriptMove(ow.player, steps[i], 1, function() walk(i + 1) end)
-    end
-    push(game, t._PewterCityYoungsterYoureATrainerFollowMeText
-      or "Hey! You're a\ntrainer, right?", function()
-      push(game, t._PewterCityYoungsterGoTakeOnBrockText
-        or "Go take on BROCK\nat the GYM first!", function()
-        walk(1)
-      end)
-    end)
+    pewterGymEscort(game, ow)
    return true
  end,
 }
@@ -315,36 +522,79 @@ end
 -- EVENT_ROUTE22_RIVAL_WANTS_BATTLE in Oak's lab (expired by Pewter
 -- Gym) and again in Viridian Gym; we derive the same windows from the
 -- surrounding story flags so old saves work too.
+-- Rival1Exit → Viridian (right/down); Rival2Exit → League (left).
+-- Both exit lists are keyed on wSavedCoordIndex -- WHICH entry of
+-- Route22DefaultScript.Route22RivalBattleCoords the player matched -- not
+-- on where the rival ended up.  CheckCoords (home/map_objects.asm:107)
+-- zeroes wCoordIndex and `inc [hl]` BEFORE each compare, so the first
+-- entry reports 1: index 1 is (29,4), index 2 is (29,5).
+-- Route22Rival1AfterBattleScript (Route22.asm:175) takes
+-- ...ExitMovementData1 on index 1 and ...Data2 otherwise.  From the top
+-- tile the rival stands BELOW the player on (29,5) and leaves east along
+-- row 5; from the bottom tile he stands LEFT of him on (28,5) and has to
+-- step UP to row 4 to get around him.  The port had the two branches
+-- swapped, so the top tile started the walk with UP out of (28,4) into
+-- the cliff cell (28,3), which is not walkable (#236).
+local function route22ExitDirs(n, py)
+  if n == 2 then
+    -- Route22Rival2ExitMovementData1 falls through into ...Data2: LEFT x4
+    -- from (29,5), LEFT x3 from (28,5), both back onto the spawn (25,5).
+    if py == 4 then return { "left", "left", "left", "left" } end
+    return { "left", "left", "left" }
+  end
+  -- Route22Rival1ExitMovementData1: (29,5) -> (31,5) -> (31,10)
+  if py == 4 then
+    return { "right", "right", "down", "down", "down", "down", "down" }
+  end
+  -- Route22Rival1ExitMovementData2: (28,5) -> (28,4) -> (31,4) -> (31,10)
+  return { "up", "right", "right", "right",
+           "down", "down", "down", "down", "down", "down" }
+end
+
 local function route22Scene(n, objIndex, objName, oppClass, baseParty, beatFlag, py)
+  -- Route22MoveRivalRightScript (Route22.asm:39) walks him RIGHT along his
+  -- own row from the object_event spawn (25,5): the full four-RIGHT
+  -- Route22RivalMovementData on coord index 1 (player on (29,4)), so he
+  -- stops BELOW the player on (29,5); `inc de` drops one RIGHT on index 2
+  -- (player on (29,5)), so he stops LEFT of him on (28,5).  He never
+  -- leaves row 5.  Route22Rival{1,2}StartBattleScript (Route22.asm:110)
+  -- then faces him UP on index 1 and RIGHT otherwise (#236).
+  local rx = (py == 4) and 29 or 28
+  local rivalFacing = (py == 4) and "up" or "right"
  return {
    { "show_object", "ROUTE_22", objName },                    -- 1
-    { "move_npc_to", objIndex, 28, py },                       -- 2
-    { "face_object", objIndex, "right" },                      -- 3
+    { "move_npc_to", objIndex, rx, 5 },                        -- 2
+    { "face_object", objIndex, rivalFacing },                  -- 3
    { "show_text", "_Route22RivalBeforeBattleText" .. n },     -- 4
    { "rival_battle", oppClass, baseParty },                   -- 5
    { "jump_if_false", 11 },                                   -- 6
    { "set_flag", beatFlag },                                  -- 7
    { "show_text", "_Route22Rival" .. n .. "DefeatedText" },   -- 8
    { "show_text", "_Route22RivalAfterBattleText" .. n },      -- 9
-    { "move_npc_to", objIndex, 25, 5 },                        -- 10
+    { "walk_npc", objIndex, route22ExitDirs(n, py) },          -- 10
    { "hide_object", "ROUTE_22", objName },                    -- 11
  }
 end

+-- Route22Rival{1,2}StartBattleScript turns the player toward him too:
+-- PLAYER_DIR_DOWN on coord index 1 (the (29,4) tile, rival below him),
+-- and the PLAYER_DIR_LEFT Route22DefaultScript already set on index 2
+-- (the (29,5) tile, rival to his left) (#236).
 M.ROUTE_22 = {
  onStep = function(game, ow, x, y)
    if not inCoords({ { 29, 4 }, { 29, 5 } }, x, y) then return false end
    local f = game.save.flags
+    local playerFacing = (y == 4) and "down" or "left"
    if f.EVENT_GOT_POKEDEX and not f.EVENT_BEAT_BROCK
       and not f.EVENT_BEAT_ROUTE22_RIVAL_1ST_BATTLE then
      return runAmbush(game, ow,
        route22Scene(1, 1, "ROUTE22_RIVAL1", "OPP_RIVAL1", 4,
-                     "EVENT_BEAT_ROUTE22_RIVAL_1ST_BATTLE", y), "left")
+                     "EVENT_BEAT_ROUTE22_RIVAL_1ST_BATTLE", y), playerFacing)
    end
    if f.EVENT_BEAT_GIOVANNI and not f.EVENT_BEAT_ROUTE22_RIVAL_2ND_BATTLE then
      return runAmbush(game, ow,
        route22Scene(2, 2, "ROUTE22_RIVAL2", "OPP_RIVAL2", 10,
-                     "EVENT_BEAT_ROUTE22_RIVAL_2ND_BATTLE", y), "left")
+                     "EVENT_BEAT_ROUTE22_RIVAL_2ND_BATTLE", y), playerFacing)
    end
    return false
  end,
@@ -353,6 +603,14 @@ M.ROUTE_22 = {
 -- Cerulean City: the Nugget Bridge rival ambush (CeruleanCityCoords2),
 -- the TM28 rocket thief with his forced-fight cells (Coords1), and the
 -- cave guard who steps aside once you are Champion.
+-- Post-battle: Bill text then CeruleanCityMovement3/4 into town.
+local function ceruleanRivalExitDirs(px)
+  if px == 20 then
+    return { "right", "down", "down", "down", "down", "down", "down" }
+  end
+  return { "left", "down", "down", "down", "down", "down", "down" }
+end
+
 local function ceruleanRivalScene(px, py)
  return {
    { "show_object", "CERULEAN_CITY", "CERULEANCITY_RIVAL" },  -- 1
@@ -360,41 +618,43 @@ local function ceruleanRivalScene(px, py)
    { "face_object", 1, "down" },                              -- 3
    { "show_text", "_CeruleanCityRivalPreBattleText" },        -- 4
    { "rival_battle", "OPP_RIVAL1", 7 },                       -- 5
-    { "jump_if_false", 10 },                                   -- 6
+    { "jump_if_false", 11 },                                   -- 6
    { "set_flag", "EVENT_BEAT_CERULEAN_RIVAL" },               -- 7
    { "show_text", "_CeruleanCityRivalDefeatedText" },         -- 8
-    { "move_npc_to", 1, 20, 2 },                               -- 9
-    { "hide_object", "CERULEAN_CITY", "CERULEANCITY_RIVAL" },  -- 10
+    { "show_text", "_CeruleanCityRivalIWentToBillsText" },     -- 9
+    { "walk_npc", 1, ceruleanRivalExitDirs(px) },              -- 10
+    { "hide_object", "CERULEAN_CITY", "CERULEANCITY_RIVAL" },  -- 11
  }
 end

 -- scripts/CeruleanCity.asm CeruleanCityRocketText: fight the thief,
-- then he returns TM28 (DIG) and hurries off
+-- then he returns TM28 (DIG) and hurries off.  CeruleanHideRocket
+-- (CeruleanCity_2.asm) is GBFadeOutToBlack → Show GUARD1 / Hide GUARD2 /
+-- Hide ROCKET → GBFadeInFromBlack -- not a bare hide_object.
 local rocketRows = {
  { "face_player" },                                           -- 1
  { "check_flag", "EVENT_GOT_TM28" },                          -- 2
-  { "jump_if_true", 15 },                                      -- 3
+  { "jump_if_true", 15 },                                      -- 3 → CeruleanHideRocket
  { "check_flag", "EVENT_BEAT_CERULEAN_ROCKET_THIEF" },        -- 4
  { "jump_if_true", 9 },                                       -- 5
  { "show_text", "_CeruleanCityRocketText" },                  -- 6
  { "start_battle", "trainer", "OPP_ROCKET", 5 },              -- 7
-  { "jump_if_false", 18 },                                     -- 8
+  { "jump_if_false", "end" },                                  -- 8
  { "show_text", "_CeruleanCityRocketIllReturnTheTMText" },    -- 9
  { "set_flag", "EVENT_BEAT_CERULEAN_ROCKET_THIEF" },          -- 10
  { "give_item", "TM_DIG", 1, false },                         -- 11 (row 13 prints)
  { "set_flag", "EVENT_GOT_TM28" },                            -- 12
  { "show_text", "_CeruleanCityRocketReceivedTM28Text" },      -- 13
  { "show_text", "_CeruleanCityRocketIBetterGetMovingText" },  -- 14
-  { "hide_object", "CERULEAN_CITY", "CERULEANCITY_ROCKET" },   -- 15
-  -- CeruleanHideRocket (scripts/CeruleanCity_2.asm) does all three behind
-  -- one fade: the ROCKET goes, GUARD1 (28,12) appears and GUARD2 (27,12)
-  -- disappears.  GUARD2 stands on the only walkable neighbour of the
-  -- trashed house's south door, which is one of the two ways through the
-  -- fence dividing Cerulean, so this swap is what reconnects the city.
-  -- Bill's ticket performs the same swap (data/scripts/story.lua), and
-  -- both are idempotent, so whichever the player reaches first opens it.
+  { "fade", "out" },                                           -- 15 GBFadeOutToBlack
+  -- CeruleanHideRocket while black: GUARD1 (28,12) appears, GUARD2
+  -- (27,12) and the ROCKET go.  GUARD2 blocks the trashed-house south
+  -- door neighbour -- the swap reconnects the city (Bill's ticket does
+  -- the same in story.lua; either route is enough).
  { "show_object", "CERULEAN_CITY", "CERULEANCITY_GUARD1" },   -- 16
  { "hide_object", "CERULEAN_CITY", "CERULEANCITY_GUARD2" },   -- 17
+  { "hide_object", "CERULEAN_CITY", "CERULEANCITY_ROCKET" },   -- 18
+  { "fade", "in" },                                            -- 19 GBFadeInFromBlack
 }

 M.CERULEAN_CITY = {
@@ -453,13 +713,83 @@ M.MUSEUM_1F = {
 }

 -- The Pewter Center's singing JIGGLYPUFF (scripts/PewterPokecenter.asm
-- plays MUSIC_JIGGLYPUFF_SONG, then the map theme resumes)
+-- PewterPokecenterJigglypuffText).  The text_asm sets
+-- wDoNotWaitForButtonPressAfterDisplayingText before PrintText, so the box
+-- prints with no A prompt and the script keeps running underneath it:
+-- SFX_STOP_ALL_MUSIC, DelayFrames 32, PlayMusic MUSIC_JIGGLYPUFF_SONG,
+-- then .spinMovementLoop writes the next of DOWN -> LEFT -> UP -> RIGHT (a
+-- clockwise turn) every 24 frames for as long as the song's CHAN1/CHAN2
+-- still sound, DelayFrames 48, PlayDefaultMusic, TextScriptEnd.  Only that
+-- last step closes the box, so the whole dance plays out unskippably
+-- (#249).  Music.playOnce's pendingRestore stands in for both the channel
+-- poll and PlayDefaultMusic, so the Center's theme comes back the frame
+-- the song ends rather than 48 frames later.
+local JIGGLYPUFF_SPIN = { "down", "left", "up", "right" }
+local JIGGLYPUFF_SILENCE, JIGGLYPUFF_STEP, JIGGLYPUFF_TAIL = 32, 24, 48
+
+-- Built as a TextBox `auto` table: auto.sound fires the frame the last
+-- page has typed out (PrintText returning), and auto.tick then runs once
+-- per frame while the gate it returns still reads as playing.
+local function jigglypuffDance(game, npc)
+  local Music = require("src.core.Music")
+  -- .findMatchingFacingDirectionLoop: the rotation picks up at the entry
+  -- matching the sprite's current facing (showMapText has just turned it
+  -- toward the player), and the first write is that same facing, so the
+  -- first visible quarter turn lands 24 frames in
+  local step = 1
+  for i, dir in ipairs(JIGGLYPUFF_SPIN) do
+    if npc and npc.facing == dir then step = i end
+  end
+  local frames, phase = 0, "silence"
+  return {
+    sound = function()
+      Music.stop() -- SFX_STOP_ALL_MUSIC
+      return { isPlaying = function() return phase ~= "done" end }
+    end,
+    tick = function()
+      frames = frames + 1
+      if phase == "silence" then
+        if frames < JIGGLYPUFF_SILENCE then return end
+        frames = 0
+        if Music.playOnce(game.data, "Music_JigglypuffSong") then
+          phase = "spin"
+        else
+          -- no song def (or headless): Music.stop above already took the
+          -- map theme down and nothing armed pendingRestore, so put it
+          -- back by hand and fall through to the tail rather than hold
+          -- the box on a poll that would never clear
+          Music.restoreMap(game.data)
+          phase = "tail"
+        end
+        return
+      end
+      if phase == "spin" then
+        if frames < JIGGLYPUFF_STEP then return end
+        frames = 0
+        -- the loop tests the channels after the delay and before the next
+        -- write, so a song that just ended costs no extra quarter turn
+        if not Music.oneShotPlaying() then
+          phase = "tail"
+          return
+        end
+        step = step % #JIGGLYPUFF_SPIN + 1
+        if npc then npc.facing = JIGGLYPUFF_SPIN[step] end
+        return
+      end
+      if frames >= JIGGLYPUFF_TAIL then phase = "done" end
+    end,
+  }
+end
+
 M.PEWTER_POKECENTER = {
  talk = {
    TEXT_PEWTERPOKECENTER_JIGGLYPUFF = function(game, ow, npc, done)
-      require("src.core.Music").playOnce(game.data, "Music_JigglypuffSong")
-      push(game, text(game)._PewterPokecenterJigglypuffText
-        or "JIGGLYPUFF: Puu\npupuu!", done)
+      -- not the local push() helper: this box needs opts.auto, which is
+      -- also what suppresses the blinking arrow and the A dismissal
+      local TextBox = require("src.render.TextBox")
+      game.stack:push(TextBox.new(game,
+        text(game)._PewterPokecenterJigglypuffText or "JIGGLYPUFF: Puu\npupuu!",
+        done, { auto = jigglypuffDance(game, npc) }))
    end,
  },
 }
@@ -484,8 +814,19 @@ local function bikeGateGuard(coords, stopText, explainText)
    local t = text(game)
    push(game, t[stopText] or "Hey! Wait up!", function()
      push(game, t[explainText] or "You need a\nBICYCLE for\nCYCLING ROAD!", function()
+        -- pokered's Route16Gate1FGuardScript / Route18Gate1FGuardScript
+        -- (scripts/Route16Gate1F.asm, Route18Gate1F.asm) simulate one
+        -- PAD_RIGHT step after the refusal text, and only clear
+        -- wJoyIgnore / hand control back once that step finishes
+        -- (PlayerMovingRightScript). Without it the player was left
+        -- parked beside the guard's counter with no way past. #518
+        local function shoveRight()
+          ow:scriptMove(ow.player, "right", 1)
+        end
        if dist > 0 then
-          ow:scriptMove(ow.player, "up", dist)
+          ow:scriptMove(ow.player, "up", dist, shoveRight)
+        else
+          shoveRight()
        end
      end)
    end)
@@ -533,6 +874,19 @@ M.SILPH_CO_7F = {
  end,
 }

+-- SSAnne2FRivalAfterBattleScript's exit walk is keyed on the player's X,
+-- not on where the rival stopped: from (37,8) the rival stands below him on
+-- (36,8) and takes .RivalDownFourMovement straight down out of the room;
+-- from (36,8) he stands above him on (36,7) and takes
+-- .RivalWalkAroundPlayerMovement, which steps RIGHT and then falls through
+-- into the same four DOWNs, so five downs in all (#360).
+local function ssAnne2FRivalExitDirs(onLeft)
+  if onLeft then
+    return { "right", "down", "down", "down", "down", "down" }
+  end
+  return { "down", "down", "down", "down" }
+end
+
 -- S.S. Anne 2F rival ambush (scripts/SSAnne2F.asm; coords 36/37,8)
 M.SS_ANNE_2F = {
  onStep = function(game, ow, x, y)
@@ -545,11 +899,12 @@ M.SS_ANNE_2F = {
      { "face_object", 2, onLeft and "down" or "right" },      -- 3
      { "show_text", "_SSAnne2FRivalText" },                   -- 4
      { "rival_battle", "OPP_RIVAL2", 1 },                     -- 5
-      { "jump_if_false", 10 },                                 -- 6
+      { "jump_if_false", 11 },                                 -- 6
      { "set_flag", "EVENT_BEAT_SS_ANNE_RIVAL" },              -- 7
      { "show_text", "_SSAnne2FRivalDefeatedText" },           -- 8
-      { "move_npc_to", 2, 36, 4 },                             -- 9
-      { "hide_object", "SS_ANNE_2F", "SSANNE2F_RIVAL" },       -- 10
+      { "show_text", "_SSAnne2FRivalCutMasterText" },          -- 9
+      { "walk_npc", 2, ssAnne2FRivalExitDirs(onLeft) },        -- 10
+      { "hide_object", "SS_ANNE_2F", "SSANNE2F_RIVAL" },       -- 11
    }, onLeft and "up" or "left")
  end,
 }
@@ -12,9 +12,13 @@ local function push(game, s, done)
  game.stack:push(TextBox.new(game, s, done))
 end

+-- PrintText on a text_end string returns with the box still drawn and
+-- YesNoChoice then draws the menu above it (InitYesNoTextBoxParameters,
+-- engine/menus/text_box.asm); no A press clears the question first.  Ride
+-- TextBox's opts.choice, the same as Commands.ask (#854).
 local function ask(game, s, cb)
-  local ChoiceBox = require("src.ui.ChoiceBox")
-  push(game, s, function() game.stack:push(ChoiceBox.new(game, cb)) end)
+  local TextBox = require("src.render.TextBox")
+  game.stack:push(TextBox.new(game, s, nil, { choice = cb }))
 end

 -- -------------------------------------------------------------------
@@ -118,6 +122,7 @@ local MANSION_HOLES = {
 M.POKEMON_MANSION_3F.onStep = function(game, ow, x, y)
  for _, h in ipairs(MANSION_HOLES) do
    if x == h[1] and y == h[2] then
+      require("src.core.Sound").play(game.data, "Faint_Fall")
      ow:startWarpTo(h[3], h[4], h[5], ow.player.facing)
      return true
    end
@@ -173,7 +178,46 @@ local function syncGymGatesAfterBattle(game, ow)
  applyGymGates(game, ow)
 end

+-- Yellow's quiz-first rule (scripts/CinnabarGym.asm SuperNerd2..7): a
+-- gate guardian refuses to battle until his quiz was attempted -- a
+-- wrong answer sics him on you (the onInteract path below), a right one
+-- opens his gate; walking up and talking first just gets the room's
+-- CinnabarGymText_N lecture (Func_f2150's pointer table).
+local function yellowQuizTalk(machineIndex)
+  return function(game, ow, npc, done)
+    local yellow = require("src.core.GameVersion").isYellow()
+    local defeated = ow:trainerDefeated(npc)
+    local gateOpen = game.save.flags[gymGateFlag(machineIndex)]
+    if yellow and not defeated and not gateOpen then
+      local TextBox = require("src.render.TextBox")
+      local t = game.data.text
+      game.stack:push(TextBox.new(game,
+        t["_CinnabarGymText_" .. machineIndex]
+        or "You have to take\nthe quiz first!", done))
+      return
+    end
+    -- gate open (or Red/Blue): the ordinary trainer engagement /
+    -- after-battle line, mirroring talkTo's generic trainer branch
+    npc:facePlayer(ow.player)
+    if not defeated then
+      ow:engageTrainer(npc, done)
+      return
+    end
+    local header = game.data:trainerHeader(ow.map.def.label, npc.def.index)
+    local after = header and header.after and game.data.text[header.after]
+    local TextBox = require("src.render.TextBox")
+    game.stack:push(TextBox.new(game, after or "...", done))
+  end
+end
+
 M.CINNABAR_GYM = {
+  talk = (function()
+    local talk = {}
+    for i = 1, 6 do
+      talk["TEXT_CINNABARGYM_SUPER_NERD" .. (i + 1)] = yellowQuizTalk(i)
+    end
+    return talk
+  end)(),
  onEnter = applyGymGates,
  onVictory = syncGymGatesAfterBattle,
  onInteract = function(game, ow, fx, fy)
@@ -2,8 +2,9 @@
 -- "OPP_CLASS#partyIndex" (the object_event trainer args).  Hand-ported
 -- from the leaders'/bosses' text_asm victory scripts:
 --   gym badges: scripts/PewterGym.asm ... ViridianGym.asm
--   Rocket Hideout Giovanni: his Silph Scope is an item ball next to him
--   (data/maps/objects/RocketHideoutB4F.asm), so no reward entry needed.
+--   Rocket Hideout Giovanni: Silph Scope is a hidden item ball revealed by
+--   ShowObject in RocketHideoutB4FBeatGiovanniScript (ported as the
+--   TEXT_ROCKETHIDEOUTB4F_GIOVANNI talk handler in story3.lua).
 -- The TM each gym leader hands out afterwards is also ported.
 --
 -- `deactivate` lists the EVENT_BEAT_* flags each gym's victory script
@@ -11,6 +12,22 @@
 -- "; deactivate gym trainers" / SetEventRange in the other gyms, and
 -- FightingDojo.asm SetEventRange EVENT_BEAT_KARATE_MASTER ..
 -- EVENT_BEAT_FIGHTING_DOJO_TRAINER_3).
+--
+-- `dialogue` is the end-battle + post-battle text chain each gym leader
+-- runs (SaveEndBattleTextPointers then the map's *PostBattle / ReceiveTM
+-- script).  Leaders are not def_trainers entries, so engageTrainer has
+-- no header.won -- checkVictoryRewards shows this chain instead of a
+-- synthetic "received badge/TM" stub.
+--
+-- Gym entries split the TM hand-over out of `dialogue`, mirroring the
+-- originals' GiveItem check (`call GiveItem` / `jr nc, .BagFull`):
+-- `tmPre` is the ReceiveTM script's lead-in (badge info / "Wait! Take
+-- this!"), shown at the victory and again when a beaten leader retries
+-- the hand-over; `tmDialogue` shows only when the TM actually goes in
+-- the bag; `noRoom` is the "make room" line shown instead when the bag
+-- is full; `gotFlag` (pokered's EVENT_GOT_TM*) is set only on a
+-- successful give, which is what makes the leader's talk script retry
+-- later (gyms.lua).

 local function range(prefix, first, last)
  local t = {}
@@ -21,40 +38,138 @@ local function range(prefix, first, last)
 end

 return {
+  -- PewterGym.asm .gymVictory also HideObject TOGGLE_GYM_GUY
+  -- (PEWTERCITY_YOUNGSTER) and TOGGLE_ROUTE_22_RIVAL_1 so the east-exit
+  -- escort NPC and the first Route 22 rival stay gone after the badge.
  ["OPP_BROCK#1"] = { badge = "BOULDERBADGE", flag = "EVENT_BEAT_BROCK",
                      item = "TM_BIDE",
-                      deactivate = { "EVENT_BEAT_PEWTER_GYM_TRAINER_0" } },
+                      gotFlag = "EVENT_GOT_TM34",
+                      noRoom = "_PewterGymTM34NoRoomText",
+                      deactivate = { "EVENT_BEAT_PEWTER_GYM_TRAINER_0" },
+                      hide = {
+                        { "PEWTER_CITY", "PEWTERCITY_YOUNGSTER" },
+                        { "ROUTE_22", "ROUTE22_RIVAL1" },
+                      },
+                      dialogue = {
+                        "_PewterGymBrockReceivedBoulderBadgeText",
+                        "_PewterGymBrockBoulderBadgeInfoText",
+                      },
+                      tmPre = { "_PewterGymBrockWaitTakeThisText" },
+                      tmDialogue = {
+                        "_PewterGymReceivedTM34Text",
+                        "_TM34ExplanationText",
+                      } },
  ["OPP_MISTY#1"] = { badge = "CASCADEBADGE", flag = "EVENT_BEAT_MISTY",
                      item = "TM_BUBBLEBEAM",
-                      deactivate = range("EVENT_BEAT_CERULEAN_GYM_TRAINER_", 0, 1) },
+                      gotFlag = "EVENT_GOT_TM11",
+                      noRoom = "_CeruleanGymMistyTM11NoRoomText",
+                      deactivate = range("EVENT_BEAT_CERULEAN_GYM_TRAINER_", 0, 1),
+                      dialogue = {
+                        "_CeruleanGymMistyReceivedCascadeBadgeText",
+                      },
+                      tmPre = { "_CeruleanGymMistyCascadeBadgeInfoText" },
+                      tmDialogue = {
+                        "_CeruleanGymMistyReceivedTM11Text",
+                      } },
  ["OPP_LT_SURGE#1"] = { badge = "THUNDERBADGE", flag = "EVENT_BEAT_LT_SURGE",
                         item = "TM_THUNDERBOLT",
-                         deactivate = range("EVENT_BEAT_VERMILION_GYM_TRAINER_", 0, 2) },
+                         gotFlag = "EVENT_GOT_TM24",
+                         noRoom = "_VermilionGymLTSurgeTM24NoRoomText",
+                         deactivate = range("EVENT_BEAT_VERMILION_GYM_TRAINER_", 0, 2),
+                         dialogue = {
+                           "_VermilionGymLTSurgeReceivedThunderBadgeText",
+                         },
+                         tmPre = { "_VermilionGymLTSurgeThunderBadgeInfoText" },
+                         tmDialogue = {
+                           "_VermilionGymLTSurgeReceivedTM24Text",
+                           "_TM24ExplanationText",
+                         } },
  ["OPP_ERIKA#1"] = { badge = "RAINBOWBADGE", flag = "EVENT_BEAT_ERIKA",
                      item = "TM_MEGA_DRAIN",
-                      deactivate = range("EVENT_BEAT_CELADON_GYM_TRAINER_", 0, 6) },
+                      gotFlag = "EVENT_GOT_TM21",
+                      noRoom = "_CeladonGymTM21NoRoomText",
+                      deactivate = range("EVENT_BEAT_CELADON_GYM_TRAINER_", 0, 6),
+                      dialogue = {
+                        "_CeladonGymErikaReceivedRainbowBadgeText",
+                      },
+                      tmPre = { "_CeladonGymRainbowBadgeInfoText" },
+                      tmDialogue = {
+                        "_CeladonGymReceivedTM21Text",
+                        "_TM21ExplanationText",
+                      } },
  ["OPP_KOGA#1"] = { badge = "SOULBADGE", flag = "EVENT_BEAT_KOGA",
                     item = "TM_TOXIC",
-                     deactivate = range("EVENT_BEAT_FUCHSIA_GYM_TRAINER_", 0, 5) },
+                     gotFlag = "EVENT_GOT_TM06",
+                     noRoom = "_FuchsiaGymKogaTM06NoRoomText",
+                     deactivate = range("EVENT_BEAT_FUCHSIA_GYM_TRAINER_", 0, 5),
+                     dialogue = {
+                       "_FuchsiaGymKogaReceivedSoulBadgeText",
+                     },
+                     tmPre = { "_FuchsiaGymKogaSoulBadgeInfoText" },
+                     tmDialogue = {
+                       "_FuchsiaGymKogaReceivedTM06Text",
+                       "_FuchsiaGymKogaTM06ExplanationText",
+                     } },
  ["OPP_SABRINA#1"] = { badge = "MARSHBADGE", flag = "EVENT_BEAT_SABRINA",
                        item = "TM_PSYWAVE",
-                        deactivate = range("EVENT_BEAT_SAFFRON_GYM_TRAINER_", 0, 6) },
+                        gotFlag = "EVENT_GOT_TM46",
+                        noRoom = "_SaffronGymSabrinaTM46NoRoomText",
+                        deactivate = range("EVENT_BEAT_SAFFRON_GYM_TRAINER_", 0, 6),
+                        dialogue = {
+                          "_SaffronGymSabrinaReceivedMarshBadgeText",
+                        },
+                        tmPre = { "_SaffronGymSabrinaMarshBadgeInfoText" },
+                        tmDialogue = {
+                          "_SaffronGymSabrinaReceivedTM46Text",
+                          "_TM46ExplanationText",
+                        } },
  ["OPP_BLAINE#1"] = { badge = "VOLCANOBADGE", flag = "EVENT_BEAT_BLAINE",
                       item = "TM_FIRE_BLAST",
-                       deactivate = range("EVENT_BEAT_CINNABAR_GYM_TRAINER_", 0, 6) },
+                       gotFlag = "EVENT_GOT_TM38",
+                       noRoom = "_CinnabarGymBlaineTM38NoRoomText",
+                       deactivate = range("EVENT_BEAT_CINNABAR_GYM_TRAINER_", 0, 6),
+                       dialogue = {
+                         "_CinnabarGymBlaineReceivedVolcanoBadgeText",
+                       },
+                       tmPre = { "_CinnabarGymBlaineVolcanoBadgeInfoText" },
+                       tmDialogue = {
+                         "_CinnabarGymBlaineReceivedTM38Text",
+                         "_CinnabarGymBlaineTM38ExplanationText",
+                       } },
  ["OPP_GIOVANNI#3"] = { badge = "EARTHBADGE", flag = "EVENT_BEAT_GIOVANNI",
                         item = "TM_FISSURE",
-                         deactivate = range("EVENT_BEAT_VIRIDIAN_GYM_TRAINER_", 0, 7) },
+                         gotFlag = "EVENT_GOT_TM27",
+                         noRoom = "_ViridianGymGiovanniTM27NoRoomText",
+                         deactivate = range("EVENT_BEAT_VIRIDIAN_GYM_TRAINER_", 0, 7),
+                         dialogue = {
+                           "_ViridianGymGiovanniReceivedEarthBadgeText",
+                         },
+                         tmPre = { "_ViridianGymGiovanniEarthBadgeInfoText" },
+                         tmDialogue = {
+                           "_ViridianGymGiovanniReceivedTM27Text",
+                           "_ViridianGymGiovanniTM27ExplanationText",
+                         } },

-  -- Silph Co. Giovanni: unlocks the president's Master Ball gift
-  ["OPP_GIOVANNI#2"] = { flag = "EVENT_BEAT_SILPH_CO_GIOVANNI" },
+  -- Silph Co. Giovanni: unlocks the president's Master Ball gift.
+  -- SilphCo11FGiovanniStartBattleScript (scripts/SilphCo11F.asm) hands the
+  -- battle SilphCo10FGiovanniILostAgainText through SaveEndBattleTextPointers,
+  -- but he has no def_trainers header on 11F, so engageTrainer finds no
+  -- header.won to give it -- this chain is the port's stand-in for that loss
+  -- line (#722).  The "Blast it all!" speech, the fade and the rockets
+  -- leaving are SilphCo11FGiovanniAfterBattleScript, ported in M.SILPH_CO_11F
+  -- (data/scripts/story.lua).
+  ["OPP_GIOVANNI#2"] = { flag = "EVENT_BEAT_SILPH_CO_GIOVANNI",
+                         dialogue = { "_SilphCo10FGiovanniILostAgainText" } },

  -- Fighting Dojo Karate Master (scripts/FightingDojo.asm
  -- FightingDojoKarateMasterPostBattleScript sets EVENT_BEAT_KARATE_MASTER,
  -- which gates the HITMONLEE/HITMONCHAN gift).  OPP_BLACKBELT party 1 is
-  -- only him (data/maps/objects/FightingDojo.asm).
+  -- only him (data/maps/objects/FightingDojo.asm).  `dialogue` is the
+  -- concede + prize offer he speaks after the win (his header supplies the
+  -- "Hwa! Arrgh! Beaten!" won line first; #197).
  ["OPP_BLACKBELT#1"] = { flag = "EVENT_BEAT_KARATE_MASTER",
-                          deactivate = range("EVENT_BEAT_FIGHTING_DOJO_TRAINER_", 0, 3) },
+                          deactivate = range("EVENT_BEAT_FIGHTING_DOJO_TRAINER_", 0, 3),
+                          dialogue = { "_FightingDojoKarateMasterIWillGiveYouAPokemonText" } },

  -- Elite Four progress flags (their rooms' door logic isn't ported, but
  -- the flags make the Hall of Fame checkable)
@@ -0,0 +1,131 @@
+-- Summer Beach House (scripts/SummerBeachHouse.asm), Yellow's Route 19
+-- surf shack.  The Surfin' Dude only lets a party Pikachu that knows
+-- SURF ride (IsSurfingPikachuInParty, home/map_objects.asm); saying yes
+-- runs the Surfing Pikachu minigame (src/ui/SurfingMinigame.lua).  The
+-- corner printer shows/prints the high score once you have surfed this
+-- visit (BIT_PIKACHU_MAP_SURF_SELECT is a per-map-load flag, so the
+-- session markers live on the overworld state, not the save).
+
+local function surfingPikachu(game)
+  for _, mon in ipairs(game.save.party or {}) do
+    if mon.species == "PIKACHU" then
+      for _, mv in ipairs(mon.moves or {}) do
+        if mv.id == "SURF" then return mon end
+      end
+    end
+  end
+  return nil
+end
+
+local function push(game, text, done)
+  local TextBox = require("src.render.TextBox")
+  game.stack:push(TextBox.new(game, text, done))
+end
+
+-- the two-variant posters: the surf-capable line once a surfing
+-- Pikachu is along, the plain one otherwise
+local function poster(n)
+  return function(game, ow, npc, done)
+    local t = game.data.text
+    local key = ("_SummerBeachHousePoster%dText%d"):format(
+      n, surfingPikachu(game) and 1 or 2)
+    push(game, t[key] or "A surfing poster.", done)
+  end
+end
+
+return {
+  SUMMER_BEACH_HOUSE = {
+    talk = {
+      TEXT_SUMMERBEACHHOUSE_SURFINDUDE = function(game, ow, npc, done)
+        local t = game.data.text
+        if not surfingPikachu(game) then
+          push(game, t._SummerBeachHouseSurfinDudeText4
+            or "Dogs and burgers\non special today!", done)
+          return
+        end
+        -- Text1 on the first ask each visit, the short Text3 after
+        local ask = ow.surfinDudeAsked
+          and (t._SummerBeachHouseSurfinDudeText3 or "Wanna go SURF?")
+          or (t._SummerBeachHouseSurfinDudeText1
+              or "Whoa!\nYour PIKACHU knows\nhow to SURF!\fGive it a go?")
+        ow.surfinDudeAsked = true
+        push(game, ask, function()
+          local ChoiceBox = require("src.ui.ChoiceBox")
+          game.stack:push(ChoiceBox.new(game, function(yes)
+            if not yes then
+              push(game, t._SummerBeachHouseSurfinDudeText2
+                or "Come SURF anytime,\nmy friend!", done)
+              return
+            end
+            local SurfingMinigame = require("src.ui.SurfingMinigame")
+            game.stack:push(SurfingMinigame.new(game, function()
+              ow.surfedThisVisit = true -- BIT_PIKACHU_MAP_SURF_SELECT
+              require("src.core.Music").playMap(game.data, ow.map.id)
+              done()
+            end))
+          end))
+        end)
+      end,
+
+      TEXT_SUMMERBEACHHOUSE_PIKACHU = function(game, ow, npc, done)
+        local t = game.data.text
+        push(game, t._SummerBeachHousePikachuText or "PIKACHU: Pikaa!",
+          function()
+            require("src.core.Sound").playCry(game.data, "PIKACHU")
+            done()
+          end)
+      end,
+
+      TEXT_SUMMERBEACHHOUSE_POSTER1 = poster(1),
+      TEXT_SUMMERBEACHHOUSE_POSTER2 = poster(2),
+      TEXT_SUMMERBEACHHOUSE_POSTER3 = poster(3),
+
+      TEXT_SUMMERBEACHHOUSE_PRINTER = function(game, ow, npc, done)
+        local t = game.data.text
+        if not surfingPikachu(game) then
+          push(game, t._SummerBeachHousePrinterText1
+            or "It's some sort of\na machine...", done)
+          return
+        end
+        push(game, t._SummerBeachHousePrinterText2
+          or "SUMMER BEACH HOUSE\nPRINTER, it says.", function()
+          if not ow.surfedThisVisit then
+            done()
+            return
+          end
+          push(game, t._SummerBeachHousePrinterText3
+            or "The Hi-Score is\nshown.\fPRINT it out?", function()
+            local ChoiceBox = require("src.ui.ChoiceBox")
+            game.stack:push(ChoiceBox.new(game, function(yes)
+              if not yes then
+                done()
+                return
+              end
+              -- PrintSurfingMinigameHighScore -> PNG stand-in
+              local Printer = require("src.core.Printer")
+              local Font = require("src.render.Font")
+              local Strings = require("src.core.Strings")
+              local hi = game.save.surfingHighScore or 0
+              local name = game.save.player.name or "RED"
+              local saved, err = Printer.save("surf_hiscore", 160, 64,
+                function()
+                  love.graphics.setColor(1, 1, 1, 1)
+                  love.graphics.rectangle("fill", 0, 0, 160, 64)
+                  love.graphics.setColor(0, 0, 0, 1)
+                  love.graphics.rectangle("line", 2.5, 2.5, 155, 59)
+                  Font.draw(Strings("SUMMER BEACH HOUSE"), 8, 10)
+                  Font.draw(Strings("SURFING Hi-Score"), 8, 24)
+                  Font.draw(name, 8, 40)
+                  Font.draw(Strings("%d pts", hi), 96, 40)
+                end)
+              push(game, saved
+                and Strings("Printed!\fSaved as\n%s\vin the save\nfolder.",
+                            saved)
+                or Strings("Printer error!\n%s", tostring(err)), done)
+            end))
+          end)
+        end)
+      end,
+    },
+  },
+}
@@ -0,0 +1,115 @@
+-- Yellow's three Kanto-starter side-quests, hand-ported from
+-- scripts/CeruleanMelaniesHouse.asm, scripts/Route24.asm
+-- (Route24CooltrainerM4Text) and scripts/VermilionCity_2.asm
+-- (VermilionCityPrintOfficerJennyText).  Registered on top of the shared
+-- Red map scripts by data/scripts/init.lua on a Yellow boot only, so the
+-- table keys compose with story.lua / story4.lua's existing entries.
+
+local M = {}
+
+-- Melanie hands over her Bulbasaur once the starter Pikachu trusts you
+-- (wPikachuHappiness >= 147).
+M.CERULEAN_MELANIES_HOUSE = {
+  talk = {
+    TEXT_CERULEANMELANIESHOUSE_MELANIE = function(game, ow, npc, done)
+      local rows = { { "face_player" } }
+      if game.save.flags.EVENT_GOT_BULBASAUR_IN_CERULEAN then
+        rows[#rows + 1] = { "show_text", "MelanieText4" }
+      elseif (game.save.pikachuHappiness or 90) < 147 then
+        rows[#rows + 1] = { "show_text", "MelanieText1" }
+      else
+        rows[#rows + 1] = { "show_text", "MelanieText1" }
+        rows[#rows + 1] = { "ask", "MelanieText2" }
+        rows[#rows + 1] = { "jump_if_false", "declined" }
+        rows[#rows + 1] = { "give_pokemon", "BULBASAUR", 10 }
+        rows[#rows + 1] = { "jump_if_false", "end" } -- party + box full
+        -- Event and HideObject before MelanieText3: give_pokemon's nickname
+        -- prompt and the received text both yield, and a script that dies
+        -- in that window used to leave the BULBASAUR given with the event
+        -- clear, so Melanie offered a second one (#426).  The flag is only
+        -- read at script entry, so the order is invisible in play.
+        rows[#rows + 1] = { "set_flag", "EVENT_GOT_BULBASAUR_IN_CERULEAN" }
+        rows[#rows + 1] = { "hide_object", "CERULEAN_MELANIES_HOUSE",
+                            "CERULEANMELANIESHOUSE_BULBASAUR" }
+        rows[#rows + 1] = { "show_text", "MelanieText3" }
+        rows[#rows + 1] = { "jump", "end" }
+        rows[#rows + 1] = { "label", "declined" }
+        rows[#rows + 1] = { "show_text", "MelanieText5" }
+      end
+      ow.runner:run(rows, { npc = npc, onDone = done,
+        checkpointOnDone = "release_npc" })
+    end,
+    -- pet flavor: the text with the species' cry over it
+    TEXT_CERULEANMELANIESHOUSE_BULBASAUR = {
+      { "play_cry", "BULBASAUR" },
+      { "show_text", "MelanieBulbasaurText" },
+    },
+    TEXT_CERULEANMELANIESHOUSE_ODDISH = {
+      { "play_cry", "ODDISH" },
+      { "show_text", "MelanieOddishText" },
+    },
+    TEXT_CERULEANMELANIESHOUSE_SANDSHREW = {
+      { "play_cry", "SANDSHREW" },
+      { "show_text", "MelanieSandshrewText" },
+    },
+  },
+}
+
+-- Damian gives away the Charmander he thinks is too weak (EVENT_54F).
+M.ROUTE_24 = {
+  talk = {
+    TEXT_ROUTE24_COOLTRAINER_M4 = {
+      { "face_player" },
+      { "check_flag", "EVENT_54F" },
+      { "jump_if_true", "after" },
+      { "ask", "_Route24DamianText1" },
+      { "jump_if_false", "declined" },
+      { "give_pokemon", "CHARMANDER", 10 },
+      { "jump_if_false", "end" },
+      -- SetEvent hoisted ahead of the received text (Route24.asm writes it
+      -- after Route24Text_515e3, where nothing in between can fail): the
+      -- nickname prompt and the text both yield, and a script death in that
+      -- window left the CHARMANDER given with EVENT_54F clear, so Damian
+      -- handed out a second one on the next talk (#426).
+      { "set_flag", "EVENT_54F" },
+      { "show_text", "_Route24DamianText2" },
+      { "jump", "end" },
+      { "label", "declined" },
+      { "show_text", "_Route24DamianText3" },
+      { "jump", "end" },
+      { "label", "after" },
+      { "show_text", "_Route24DamianText4" },
+    },
+  },
+}
+
+-- Officer Jenny's Squirtle: kept until you carry the Thunder Badge.
+M.VERMILION_CITY = {
+  talk = {
+    TEXT_VERMILIONCITY_OFFICER_JENNY = function(game, ow, npc, done)
+      local rows = { { "face_player" } }
+      if game.save.flags.EVENT_GOT_SQUIRTLE_FROM_OFFICER_JENNY then
+        rows[#rows + 1] = { "show_text", "_OfficerJennyText5" }
+      elseif not (game.save.inventory
+                  and game.save.inventory.THUNDERBADGE) then
+        rows[#rows + 1] = { "show_text", "_OfficerJennyText1" }
+      else
+        rows[#rows + 1] = { "ask", "_OfficerJennyText2" }
+        rows[#rows + 1] = { "jump_if_false", "declined" }
+        rows[#rows + 1] = { "give_pokemon", "SQUIRTLE", 10 }
+        rows[#rows + 1] = { "jump_if_false", "end" }
+        -- event before the received text, as above (#426)
+        rows[#rows + 1] = { "set_flag",
+                            "EVENT_GOT_SQUIRTLE_FROM_OFFICER_JENNY" }
+        rows[#rows + 1] = { "show_text", "_OfficerJennyText3" }
+        rows[#rows + 1] = { "jump", "end" }
+        rows[#rows + 1] = { "label", "declined" }
+        rows[#rows + 1] = { "show_text", "_OfficerJennyText4" }
+      end
+      ow.runner:run(rows, { npc = npc, onDone = done,
+        checkpointOnDone = "release_npc" })
+    end,
+  },
+}
+
+return M
@@ -0,0 +1,308 @@
+-- Jessie & James, Yellow's Team Rocket duo, at all four ambush sites:
+-- Mt Moon B2F (scripts/MtMoonB2F.asm), Rocket Hideout B4F
+-- (scripts/RocketHideoutB4F.asm), Pokemon Tower 7F
+-- (scripts/PokemonTower7F.asm) and Silph Co 11F (scripts/SilphCo11F.asm).
+-- Every site shares one shape: a coordinate trigger swaps the map theme
+-- for Music_MeetJessieJames, the motto plays, the duo closes in, one
+-- battle against the shared OPP_ROCKET party fights them both, and after
+-- their parting lines they vanish together under a second sting of the
+-- theme before the map theme resumes (PlayDefaultMusic ->
+-- play_default_music).
+--
+-- Registered on top of the shared tables by data/scripts/init.lua on a
+-- Yellow boot; MT_MOON_B2F's onStep chains story2's Super Nerd / fossil
+-- trigger and SILPH_CO_11F's chains story's Giovanni trigger, since
+-- non-talk hooks replace rather than merge.
+
+local M = {}
+
+-- Capture the FUNCTION, not the table: attachBase stores the module
+-- table itself, so once this file's onStep is attached the table's slot
+-- points back here -- delegating through the table would self-recurse.
+local baseMtMoonStep = require("data.scripts.story2").MT_MOON_B2F.onStep
+local baseSilph11Step = require("data.scripts.story").SILPH_CO_11F.onStep
+
+M.MT_MOON_B2F = {
+  talk = {
+    TEXT_MTMOONB2F_JESSIE = {
+      { "face_player" }, { "show_text", "_MtMoonJessieJamesText1" },
+    },
+    TEXT_MTMOONB2F_JAMES = {
+      { "face_player" }, { "show_text", "_MtMoonJessieJamesText1" },
+    },
+  },
+
+  onStep = function(game, ow, x, y)
+    if baseMtMoonStep and baseMtMoonStep(game, ow, x, y) then
+      return true
+    end
+    local f = game.save.flags
+    if x ~= 3 or y ~= 5 then return false end
+    if f.EVENT_BEAT_MT_MOON_3_JESSIE_JAMES then return false end
+    if not (f.EVENT_GOT_DOME_FOSSIL or f.EVENT_GOT_HELIX_FOSSIL) then
+      return false
+    end
+    ow.runner:run({
+      { "stop_music" },
+      { "play_music", "Music_MeetJessieJames" },
+      { "show_object", "MT_MOON_B2F", "MTMOONB2F_JESSIE" },
+      { "show_object", "MT_MOON_B2F", "MTMOONB2F_JAMES" },
+      { "show_text", "_MtMoonJessieJamesText1" },
+      { "face_player_dir", "up" },
+      { "emote", "player", "shock", 30 },
+      -- MtMoonB2FScript_49e15 simulates PAD_UP for one player step, then
+      -- Script6/Script9 walk Jessie (object 2, MovementData_f9e65: six
+      -- $06) and James (object 6, f9e66: five $06); both objects' movement
+      -- byte 2 is LEFT, so .determineDirection makes those LEFT steps --
+      -- Jessie (9,3)->(3,3) above the player at (3,4), James (9,4)->(4,4)
+      -- beside him. #423
+      { "walk_npc", "player", { "up" } },
+      { "walk_npc", 2, { "left", "left", "left", "left", "left", "left" } },
+      { "face_object", 2, "down" },
+      { "walk_npc", 6, { "left", "left", "left", "left", "left" } },
+      { "face_object", 6, "left" },
+      { "show_text", "_MtMoonJessieJamesText2" },
+      -- MtMoonB2FScript12 arms _MtMoonJessieJamesText3 with
+      -- SaveEndBattleTextPointers before it sets wCurOpponent, so
+      -- TrainerBattleVictory prints it on the battle screen as "ROCKET: A
+      -- brat beat us?" between TrainerDefeatedText and MoneyForWinningText.
+      -- Its one-word first line only reads right behind that tag (#866).
+      { "save_end_battle_text", "_MtMoonJessieJamesText3" },
+      { "start_battle", "trainer", "OPP_ROCKET", 42 },
+      { "check_battle_result", "win" },
+      { "jump_if_false", "end" },
+      { "show_text", "_MtMoonJessieJamesText4" },
+      { "stop_music" },
+      { "play_music", "Music_MeetJessieJames" },
+      { "fade", "out" },
+      { "hide_object", "MT_MOON_B2F", "MTMOONB2F_JESSIE" },
+      { "hide_object", "MT_MOON_B2F", "MTMOONB2F_JAMES" },
+      { "fade", "in" },
+      { "play_default_music" },
+      { "set_flag", "EVENT_BEAT_MT_MOON_3_JESSIE_JAMES" },
+    }, {})
+    return true
+  end,
+}
+
+-- -------------------------------------------------------------------
+-- Rocket Hideout B4F (RocketHideoutB4FScript_455a5..Script13): the
+-- motto plays from off-screen FIRST, then the duo pops in at (25,10) /
+-- (24,10) and whichever of them shares the player's column ($18=24 or
+-- $19=25, EVENT_ROCKET_HIDEOUT_4_JESSIE_JAMES_ON_LEFT) walks the three
+-- tiles down to loom over the player while the other walks four and ends
+-- up beside him.  A loss
+-- re-hides them (RocketHideoutB4FResetScripts via EVENT_6A0), so the
+-- trigger re-arms clean.
+-- -------------------------------------------------------------------
+
+M.ROCKET_HIDEOUT_B4F = {
+  talk = {
+    TEXT_ROCKETHIDEOUTB4F_JESSIE = {
+      { "face_player" }, { "show_text", "_RocketHideoutJessieJamesText1" },
+    },
+    TEXT_ROCKETHIDEOUTB4F_JAMES = {
+      { "face_player" }, { "show_text", "_RocketHideoutJessieJamesText1" },
+    },
+  },
+
+  onStep = function(game, ow, x, y)
+    local f = game.save.flags
+    if y ~= 14 or (x ~= 24 and x ~= 25) then return false end
+    if f.EVENT_BEAT_ROCKET_HIDEOUT_4_JESSIE_JAMES then return false end
+    -- ON_LEFT: player under James's column (25); movement data pairs
+    -- RocketHideoutB4FJessieJamesMovementData_45605/45606 swap so the
+    -- column-mate walks 3, the other 4.
+    local onLeft = (x == 25)
+    ow.runner:run({
+      { "stop_music" },
+      { "play_music", "Music_MeetJessieJames" },
+      { "show_text", "_RocketHideoutJessieJamesText1" },
+      { "face_player_dir", "up" },
+      { "emote", "player", "shock", 30 },
+      { "show_object", "ROCKET_HIDEOUT_B4F", "ROCKETHIDEOUTB4F_JAMES" },
+      { "show_object", "ROCKET_HIDEOUT_B4F", "ROCKETHIDEOUTB4F_JESSIE" },
+      -- James (object 2) then Jessie (object 3), Script4..Script9 order.
+      -- RocketHideoutB4FJessieJamesMovementData_45605 is a lone $4 that FALLS
+      -- THROUGH into _45606 ($4 $4 $4 $ff), so MoveSprite_ (home/pathfinding.asm)
+      -- reads _45605 as FOUR steps and _45606 as three; $4 is DOWN in Yellow's
+      -- Func_5288 lookup (engine/overworld/movement.asm), which walks with no
+      -- collision test.  From (25,10)/(24,10) against a player on y=14 the
+      -- column-mate stops three down, right above him, and the other walks the
+      -- full four to stand alongside -- which is what the facings below assume.
+      -- Reading _45605 as a single step stranded whoever was off-column three
+      -- tiles away, so James never reached the player (#865).
+      { "walk_npc", 2, onLeft and { "down", "down", "down" }
+                              or { "down", "down", "down", "down" } },
+      { "face_object", 2, onLeft and "down" or "left" },
+      { "walk_npc", 3, onLeft and { "down", "down", "down", "down" }
+                              or { "down", "down", "down" } },
+      { "face_object", 3, onLeft and "right" or "down" },
+      { "show_text", "_RocketHideoutJessieJamesText2" },
+      -- RocketHideoutB4FScript10 saves _RocketHideoutJessieJamesText3 as the
+      -- end-battle text, so it prints as "ROCKET: Such a dreadful twerp!" on
+      -- the battle screen ahead of MoneyForWinningText (#866).
+      { "save_end_battle_text", "_RocketHideoutJessieJamesText3" },
+      { "start_battle", "trainer", "OPP_ROCKET", 43 },
+      { "check_battle_result", "win" },
+      { "jump_if_false", "lost" },
+      { "show_text", "_RocketHideoutJessieJamesText4" },
+      { "stop_music" },
+      { "play_music", "Music_MeetJessieJames" },
+      { "fade", "out" },
+      { "hide_object", "ROCKET_HIDEOUT_B4F", "ROCKETHIDEOUTB4F_JAMES" },
+      { "hide_object", "ROCKET_HIDEOUT_B4F", "ROCKETHIDEOUTB4F_JESSIE" },
+      { "fade", "in" },
+      { "play_default_music" },
+      { "set_flag", "EVENT_BEAT_ROCKET_HIDEOUT_4_JESSIE_JAMES" },
+      { "jump", "end" },
+      { "label", "lost" },
+      { "hide_object", "ROCKET_HIDEOUT_B4F", "ROCKETHIDEOUTB4F_JAMES" },
+      { "hide_object", "ROCKET_HIDEOUT_B4F", "ROCKETHIDEOUTB4F_JESSIE" },
+    }, {})
+    return true
+  end,
+}
+
+-- -------------------------------------------------------------------
+-- Pokemon Tower 7F (PokemonTower7FScript_60d2a..Script10): same beat
+-- one floor below Fuji, except the duo pops in BEFORE the motto and
+-- Jessie ($a=10 column) leads the walk-down; ON_LEFT ($b=11) hands the
+-- three-tile walk to James instead.  On a loss vanilla only resets the
+-- script counter (the blackout warp reloads the map anyway).
+-- -------------------------------------------------------------------
+
+M.POKEMON_TOWER_7F = {
+  talk = {
+    TEXT_POKEMONTOWER7F_JESSIE = {
+      { "face_player" }, { "show_text", "_PokemonTowerJessieJamesText1" },
+    },
+    TEXT_POKEMONTOWER7F_JAMES = {
+      { "face_player" }, { "show_text", "_PokemonTowerJessieJamesText1" },
+    },
+  },
+
+  onStep = function(game, ow, x, y)
+    local f = game.save.flags
+    if y ~= 12 or (x ~= 10 and x ~= 11) then return false end
+    if f.EVENT_BEAT_POKEMONTOWER_7_JESSIE_JAMES then return false end
+    local onLeft = (x == 11)   -- EVENT_POKEMONTOWER_7_JESSIE_JAMES_ON_LEFT
+    ow.runner:run({
+      { "stop_music" },
+      { "play_music", "Music_MeetJessieJames" },
+      { "show_object", "POKEMON_TOWER_7F", "POKEMONTOWER7F_JESSIE" },
+      { "show_object", "POKEMON_TOWER_7F", "POKEMONTOWER7F_JAMES" },
+      { "show_text", "_PokemonTowerJessieJamesText1" },
+      { "face_player_dir", "up" },
+      { "emote", "player", "shock", 30 },
+      -- Jessie (object 1) then James (object 2), Script1..Script6 order.
+      -- Same fall-through blob as the hideout: PokemonTower7FMovementData_60d7a
+      -- is a lone $4 running into _60d7b ($4 $4 $4 $FF), so _60d7a is FOUR
+      -- steps and _60d7b is three.  From (10,8)/(11,8) against a player on
+      -- y=12 the column-mate halts one tile above him and the other closes the
+      -- full four to his side; the single-step reading is why James only
+      -- "moved a bit" here (#865).
+      { "walk_npc", 1, onLeft and { "down", "down", "down", "down" }
+                              or { "down", "down", "down" } },
+      { "face_object", 1, onLeft and "right" or "down" },
+      { "walk_npc", 2, onLeft and { "down", "down", "down" }
+                              or { "down", "down", "down", "down" } },
+      { "face_object", 2, onLeft and "down" or "left" },
+      { "show_text", "_PokemonTowerJessieJamesText2" },
+      -- PokemonTower7FScript7 saves _PokemonTowerJessieJamesText3 as the
+      -- end-battle text: "ROCKET: You will regret this!" on the battle screen,
+      -- before the prize money (#866).
+      { "save_end_battle_text", "_PokemonTowerJessieJamesText3" },
+      { "start_battle", "trainer", "OPP_ROCKET", 44 },
+      { "check_battle_result", "win" },
+      { "jump_if_false", "end" },
+      { "show_text", "_PokemonTowerJessieJamesText4" },
+      { "stop_music" },
+      { "play_music", "Music_MeetJessieJames" },
+      { "fade", "out" },
+      { "hide_object", "POKEMON_TOWER_7F", "POKEMONTOWER7F_JESSIE" },
+      { "hide_object", "POKEMON_TOWER_7F", "POKEMONTOWER7F_JAMES" },
+      { "fade", "in" },
+      { "play_default_music" },
+      { "set_flag", "EVENT_BEAT_POKEMONTOWER_7_JESSIE_JAMES" },
+    }, {})
+    return true
+  end,
+}
+
+-- -------------------------------------------------------------------
+-- Silph Co 11F (SilphCo11FScript_6229c..Script14): the only site where
+-- the duo starts VISIBLE (toggleable_objects.asm keeps SILPHCO11F_JAMES
+-- / _JESSIE ON), flanking Giovanni at (2,8)/(3,8), so they are talkable
+-- before the ambush (SilphCo11FJessieJamesText = the full motto).  The
+-- trigger is the top row (y=3, x<4); EVENT_780/EVENT_781 pick one of
+-- three approach paths (SilphCo11FMovementData_622f5..62311, $5=up
+-- $6=left) that route James then Jessie up to the player without ever
+-- crossing the player's tile.  Their duo text lives in
+-- text/SilphCo10F.asm (_SilphCoJessieJamesText*).
+-- -------------------------------------------------------------------
+
+M.SILPH_CO_11F = {
+  talk = {
+    TEXT_SILPHCO11F_JESSIE = {
+      { "face_player" }, { "show_text", "_SilphCoJessieJamesText1" },
+    },
+    TEXT_SILPHCO11F_JAMES = {
+      { "face_player" }, { "show_text", "_SilphCoJessieJamesText1" },
+    },
+  },
+
+  onStep = function(game, ow, x, y)
+    if baseSilph11Step and baseSilph11Step(game, ow, x, y) then
+      return true
+    end
+    local f = game.save.flags
+    if y ~= 3 or x > 3 then return false end
+    if f.EVENT_BEAT_SILPH_CO_11F_JESSIE_JAMES then return false end
+    -- x==3 -> base path, x==2 -> EVENT_780 variant, x<=1 -> EVENT_781
+    local jamesDirs, jamesFace, jessieDirs, jessieFace
+    if x == 3 then
+      jamesDirs, jamesFace = { "up", "up", "up", "up", "up" }, "right"
+      jessieDirs, jessieFace = { "up", "up", "up", "up" }, "up"
+    elseif x == 2 then
+      jamesDirs, jamesFace = { "up", "up", "up", "up" }, "up"
+      jessieDirs, jessieFace = { "up", "up", "up", "up", "up" }, "left"
+    else
+      jamesDirs = { "up", "up", "left", "up", "up" }
+      jamesFace = "up"
+      jessieDirs = { "up", "up", "up", "left", "up", "up" }
+      jessieFace = "left"
+    end
+    ow.runner:run({
+      { "stop_music" },
+      { "play_music", "Music_MeetJessieJames" },
+      { "show_text", "_SilphCoJessieJamesText1" },
+      { "face_player_dir", "down" },
+      { "emote", "player", "shock", 30 },
+      -- James (object 4) then Jessie (object 6), Script5..Script10 order
+      { "walk_npc", 4, jamesDirs },
+      { "face_object", 4, jamesFace },
+      { "walk_npc", 6, jessieDirs },
+      { "face_object", 6, jessieFace },
+      { "show_text", "_SilphCoJessieJamesText2" },
+      -- SilphCo11FScript11 saves _SilphCoJessieJamesText3 (SilphCo11FText_624c2)
+      -- as the end-battle text: "ROCKET: Like always..." before the money (#866).
+      { "save_end_battle_text", "_SilphCoJessieJamesText3" },
+      { "start_battle", "trainer", "OPP_ROCKET", 45 },
+      { "check_battle_result", "win" },
+      { "jump_if_false", "end" },
+      { "show_text", "_SilphCoJessieJamesText4" },
+      { "stop_music" },
+      { "play_music", "Music_MeetJessieJames" },
+      { "fade", "out" },
+      { "hide_object", "SILPH_CO_11F", "SILPHCO11F_JAMES" },
+      { "hide_object", "SILPH_CO_11F", "SILPHCO11F_JESSIE" },
+      { "fade", "in" },
+      { "play_default_music" },
+      { "set_flag", "EVENT_BEAT_SILPH_CO_11F_JESSIE_JAMES" },
+    }, {})
+    return true
+  end,
+}
+
+return M
@@ -0,0 +1,152 @@
+-- The Viridian City old-man catch tutorial, Yellow's way
+-- (pokeyellow scripts/ViridianCity.asm, scripts/ViridianCity_2.asm,
+--  scripts/OaksLab.asm).  Registered on top of the shared tables by
+-- data/scripts/init.lua on a Yellow boot.
+--
+-- Yellow has TWO gambler objects where Red/Blue have one:
+--   * VIRIDIANCITY_OLD_MAN    at (17,5) -- a Red/Blue leftover; its
+--     toggle stays OFF forever in Yellow, no script ever shows it.
+--   * VIRIDIANCITY_OLD_MAN2   at (18,9) -- replaces the sleeper the
+--     moment the Pokédex is given (OaksLabOakGivesPokedexScript:
+--     HideObject TOGGLE_LYING_OLD_MAN / ShowObject TOGGLE_OLD_MAN_2).
+--
+-- This is the tutorial old man.  The Red/Blue "Are you in a hurry?"
+-- yes/no script must NOT run against him: Yellow's
+-- _ViridianCityOldManHadMyCoffeeNowText is the apology speech ("I've had
+-- my coffee now ... I'll show you how to catch POKéMON as my apology"),
+-- and the shared story.lua TEXT_VIRIDIANCITY_OLD_MAN rows hang an
+-- invented yes/no over it -- YES printed the TimeIsMoney alias
+-- (_ViridianCityOldManLosingMyTouchText) and NO ran the demo, every
+-- talk, forever (#617).
+--
+-- The real flow (ViridianCityCheckWaitingOldMan + ViridianCityOldMan2Text
+-- + ViridianCityOldManInitialCatchTrainingScript + ...EndInitial... +
+-- ViridianCityPostInitialCatchTraining): stepping into (19,9) -- the gap
+-- east of the sleeper's cell -- faces the old man right and the player
+-- left, prints the apology, and without any choice runs the demo battle
+-- (BATTLE_TYPE_OLD_MAN, RATTATA lvl 5), which he FAILS -- the ball shakes
+-- three times and breaks open.  After it, the same text pointer
+-- now prints _ViridianCityOldManLosingMyTouchText ("That didn't work!
+-- I must be losing my touch."), the old man walks off (down 6 with the
+-- player on (19,9), right 1 otherwise, Pikachu nudged out of the way
+-- first) and TOGGLE_OLD_MAN_2 hides.  A direct talk does the same.
+
+local M = {}
+
+local OLD_MAN2 = "VIRIDIANCITY_OLD_MAN2"
+
+-- Capture the FUNCTION, not the table: attachBase stores the module
+-- table itself, so once this file's onStep is attached the table's slot
+-- points back here -- delegating through the table would self-recurse.
+-- story5's VIRIDIAN_CITY.onStep chains story.lua's sleeping-old-man
+-- gate and its own gym-lock step (same pattern as yellow_jessie_james).
+local baseViridianStep = require("data.scripts.story5").VIRIDIAN_CITY.onStep
+
+-- pokeyellow text/ViridianCity.asm, _ViridianCityOldManHadMyCoffeeNowText
+-- and _ViridianCityOldManLosingMyTouchText, spelled with the extractor's
+-- markers (line -> \n, cont -> \v, para -> \f)
+local function text(game)
+  return {
+    apology = game.data.text._ViridianCityOldManHadMyCoffeeNowText
+      or "Ahh, I've had my\ncoffee now and I\vfeel great!\fSure, you can go\n"
+      .. "through!\fI'm sorry I was\nso rude to you!\fI see you're using\n"
+      .. "a POKéDEX.\fI'll show you how\nto catch POKéMON\vas my apology.",
+    losingMyTouch = game.data.text._ViridianCityOldManLosingMyTouchText
+      or "That didn't work!\nI must be losing\vmy touch.\fI've run out of\n"
+      .. "POKé BALLs too.\fI have to get some\nat POKéMON MART.",
+  }
+end
+
+-- The row list for the initial-tutorial branch, keyed by where the
+-- player stands when the battle ends (ViridianCityPostInitialCatchTraining
+-- reads wXCoord: (19,9) walks the old man down the corridor, anywhere
+-- else walks him right 1 after moving the follower Pikachu aside).
+local function oldMan2Rows(game, ow, npc)
+  local rows = {
+    { "show_text", "_ViridianCityOldManHadMyCoffeeNowText" },
+    -- ViridianCityOldManInitialCatchTrainingScript sets
+    -- EVENT_INITIAL_CATCH_TRAINING before the battle runs, and
+    -- ItemUseBall's .oldManBattle branch turns that event into anim data
+    -- $63: three shakes, then the ball breaks open.  The losing-my-touch
+    -- line below only follows a throw that failed (#636).
+    { "old_man_demo", "fail" },
+    { "set_flag", "EVENT_COMPLETED_CATCH_TRAINING" },
+    { "show_text", "_ViridianCityOldManLosingMyTouchText" },
+  }
+  if ow.player and ow.player.cellX == 19 then
+    rows[#rows + 1] =
+      { "walk_npc", npc.def.index,
+        { "down", "down", "down", "down", "down", "down" } }
+  else
+    -- ViridianCityMovePikachu (scripts/ViridianCity_2.asm): Pikachu
+    -- steps out of the old man's way before he turns right
+    local PikachuFollower = require("src.world.PikachuFollower")
+    local pika = ow and PikachuFollower.current(ow)
+    if pika then
+      rows[#rows + 1] = { "walk_npc", pika.def.index, { "right" } }
+    end
+    rows[#rows + 1] = { "walk_npc", npc.def.index, { "right" } }
+  end
+  rows[#rows + 1] =
+    { "hide_object", "VIRIDIAN_CITY", OLD_MAN2 }
+  return rows
+end
+
+-- The shared talk handler: TEXT_VIRIDIANCITY_OLD_MAN2's text_asm branch
+-- (ViridianCityOldMan2Text) on EVENT_COMPLETED_CATCH_TRAINING.
+local function oldMan2Talk(game, ow, npc, done)
+  if game.save.flags and game.save.flags.EVENT_COMPLETED_CATCH_TRAINING then
+    local TextBox = require("src.render.TextBox")
+    game.stack:push(TextBox.new(game, text(game).losingMyTouch, done))
+    return
+  end
+  ow.runner:run(oldMan2Rows(game, ow, npc), { npc = npc, onDone = done,
+    checkpointOnDone = "release_npc" })
+end
+
+M.VIRIDIAN_CITY = {
+  talk = {
+    TEXT_VIRIDIANCITY_OLD_MAN2 = oldMan2Talk,
+  },
+
+  -- Re-apply the Pokédex swap for a save that already holds the flag but
+  -- was never standing here when it fired (converted .sav imports, same
+  -- shape as story.lua's VIRIDIAN_CITY.onEnter).  Yellow shows OLD_MAN2,
+  -- not the Red/Blue OLD_MAN at (17,5), and also puts away a stray
+  -- OLD_MAN a save made by the pre-#617 build left standing.
+  onEnter = function(game, ow)
+    if not (game.save.flags and game.save.flags.EVENT_GOT_POKEDEX) then
+      return
+    end
+    local Commands = require("src.script.Commands")
+    local ctx = { save = game.save, game = game, overworld = ow }
+    Commands.hide_object(ctx, "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN_SLEEPY")
+    Commands.hide_object(ctx, "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN")
+    Commands.show_object(ctx, "VIRIDIAN_CITY", OLD_MAN2)
+  end,
+
+  -- ViridianCityCheckWaitingOldMan: with the Pokédex held and the
+  -- tutorial undone, (19,9) -- the gap east of the old man, the same
+  -- cell the sleeper used to gate -- faces him right, turns the player
+  -- left and starts the OLD_MAN2 flow with no choice.
+  onStep = function(game, ow, x, y)
+    if baseViridianStep and baseViridianStep(game, ow, x, y) then
+      return true
+    end
+    local flags = game.save.flags
+    if not flags.EVENT_GOT_POKEDEX then return false end
+    if flags.EVENT_COMPLETED_CATCH_TRAINING then return false end
+    if x ~= 19 or y ~= 9 then return false end
+    local man
+    for _, npc in ipairs(ow.npcs) do
+      if npc.def and npc.def.name == OLD_MAN2 then man = npc break end
+    end
+    if not man then return false end
+    man.facing = "right"
+    ow.player.facing = "left"
+    oldMan2Talk(game, ow, man, nil)
+    return true
+  end,
+}
+
+return M
@@ -0,0 +1,98 @@
+# Anbernic RG34XXSP (Stock OS 64-bit MOD)
+
+Download `gen1recomp-*-rg34xxsp-stockos64-mod.zip` from
+[Releases](https://github.com/bryanthaboi/gen1recomp/releases). This build
+targets **Stock OS 64-bit MOD** on the RG34XXSP with PortMaster installed
+(TF1).
+
+## Install
+
+1. Unzip the release on your computer. You get `Gen1recomp.sh` and a
+   `gen1recomp/` folder.
+2. Copy **both** onto the SD card under **`Roms/PORTS/`** so the layout is:
+
+   ```
+   Roms/PORTS/Gen1recomp.sh
+   Roms/PORTS/gen1recomp/
+   ```
+
+   On the device that path is `/mnt/mmc/Roms/PORTS/`. Keep the launcher and
+   the `gen1recomp/` folder as siblings — do not nest the `.sh` inside the
+   folder.
+3. Put your legal US Red and/or Blue `.gb` files inside the game folder:
+
+   ```
+   Roms/PORTS/gen1recomp/lovegame/
+   ```
+
+   Example: `Roms/PORTS/gen1recomp/lovegame/Pokemon - Red Version.gb`
+4. Eject the card, boot the handheld, open **Ports → Gen1recomp**.
+5. On the launcher, move the cursor with the D-pad or left stick, press **A**
+   to click. Choose the Red or Blue tab, then **Choose ROM** — with no file
+   picker on stock OS, that scans `lovegame/` for the `.gb` you dropped in.
+
+The port ships with `portable.txt` already in place, so after import the
+saves and ROM-derived cache stay next to the game on the SD card. See
+[Portable Mode](../README.md#portable-mode) for what that means.
+
+Only the canonical 1 MiB US carts import:
+
+- Red: `ea9bcae617fdf159b045185467ae58b2e4a48b9a`
+- Blue: `d7037c83e1ae5b39bde3c30787637ba1d4c48ce2`
+
+## Launcher controls
+
+| Input              | Action             |
+| ------------------ | ------------------ |
+| D-pad / left stick | Move cursor        |
+| A                  | Click              |
+| L1 / R1            | Switch tabs        |
+| Right stick        | Scroll lists       |
+| Start / Select     | Play or Choose ROM |
+
+In-game controls use the normal PortMaster / SDL pad map, rebindable under
+**OPTIONS → CONTROLS**.
+
+## Notes
+
+**GBC FX is off on this device.** The launcher exports `POKEPORT_GBCFX=0`,
+which hides the GBC FX row from OPTIONS, pins the level to OFF, and clears a
+level carried over in an `options.lua` from another machine. The H700's Mali
+GPU is in the same class as the phone GPUs that compile that present pass and
+then show a black frame (issue #136), and `love.system.getOS()` reports
+`"Linux"` here, so the Android gate would not have caught it. Every other
+display option — COLORS, TILT, ZOOM, VOID FILL, MAX FPS — works normally. If
+your device turns out to handle the pass, launch with `POKEPORT_GBCFX=1` to
+put the row back.
+
+**PERFORMANCE defaults to LOW here.** The OPTIONS → PERFORMANCE tier defaults
+to AUTO, which reads this device as an ARM Linux handheld and resolves to
+**LOW**: the 3D tilt and survey zoom stay off and the frame rate is capped,
+so the overworld runs smoothly on the H700 out of the box. Bump it to
+BALANCED or HIGH from OPTIONS if you want the extras and your device keeps
+up; see [Performance tier](new-features.md#performance-tier-low-end-devices).
+
+The pack bundles the LÖVE 11.5 aarch64 runtime from
+[PortMaster](https://portmaster.games/), so the device does not need a
+separate `love_11.5` runtime download on first launch. The launcher resolves
+paths relative to its own directory rather than PortMaster's `$directory`,
+because stock Anbernic firmware runs ports out of `roms/PORTS/` with its own
+casing and mount points.
+
+If a launch fails, `Roms/PORTS/gen1recomp/log.txt` holds the output of the
+last run.
+
+## Building the port
+
+Release runs build this automatically (see `.github/workflows/release.yml`).
+To build it by hand:
+
+```sh
+./build-rg34xxsp.sh --version 0.1.0   # -> dist/rg34xxsp/gen1recomp-rg34xxsp-stockos64-mod.zip
+```
+
+`install-rg34xxsp.sh` copies that pack straight onto a mounted SD card for
+local testing.
+
+Stock OS 64-bit MOD comes from
+[cbepx-me](https://github.com/cbepx-me/Anbernic-H700-RG-xx-StockOS-Modification).
@@ -38,7 +38,7 @@ the same core data and graphics into the source tree for verification.
 | | `src/core/SaveData.lua` | Lua-serialized save in the LÖVE save dir |
 | render | `src/render/Renderer.lua` | 160x144 canvas, integer nearest scaling |
 | | `src/render/TileRenderer.lua` | one SpriteBatch per map (8x8 quads) + border-block ring |
-| | `src/render/SpriteRenderer.lua` | 6-frame walker sheets, flipped right facing |
+| | `src/render/SpriteRenderer.lua` | variable-size anchored sprite sheets, 6-frame walkers and flipped right facing |
 | | `src/render/Font.lua` | glyph rendering via charmap (greedy longest match) |
 | | `src/render/TextBox.lua` | dialogue box: typewriter, `\n` line, `\v` scroll, `\f` page |
 | | `src/render/Camera.lua`, `Transition.lua` | follow camera, warp fades |
@@ -59,7 +59,7 @@ the same core data and graphics into the source tree for verification.
 | | `src/battle/Experience.lua`, `Catching.lua`, `TrainerAI.lua` | exp/levels, Gen 1 catch algorithm, AI |
 | | `src/battle/rulesets/` | `gen1_faithful` (default) vs `modern_clean` |
 | ui | `src/ui/*` | start menu, generic menu, yes/no box, party/bag lists |
-| | `tools/save-editor/` | Standalone save editor (`love . --editor`) |
+| | `tools/save-editor/` | Save editor: shipped in every build, opened from the launcher's Edit button or standalone with `love . --editor` |

 ## Map scripts

@@ -234,8 +234,12 @@ What was ported from pokered's engine code and where it came from.
  pre-battle text and engages the leader battle (badge/TM via
  data/scripts/victories.lua); post-badge talk prints the leader's
  post-battle advice text (Misty's is her TM11 explanation). The
-  originals' middle branch (beaten but TM not handed over) is
-  unreachable since the TM is granted with the victory. Giovanni's
+  originals' middle branch (beaten but TM not handed over,
+  CheckEventReuseA EVENT_GOT_TM*) is ported too: the victory's GiveItem
+  goes through the bag's capacity check, a full bag shows the leader's
+  "make room" text instead of the received lines and leaves
+  EVENT_GOT_TM* unset, and talking to the leader re-runs the ReceiveTM
+  script until the TM goes in (#797). Giovanni's
  farewell (`ViridianGymGiovanniText` .afterBeat) hides him inside a
  fade-to-black/fade-in Transition matching ViridianGym.asm's
  GBFadeOutToBlack → HideObject → GBFadeInFromBlack, persisted
@@ -1,131 +0,0 @@
-# Building a Blue Version of the port
-
-pokered builds Red and Blue from one source tree: the Makefile
-assembles everything twice with `rgbasm -D _RED` or `-D _BLUE`, and
-every in-game difference sits in an `IF DEF(_RED)` / `IF DEF(_BLUE)`
-block. Our extraction pipeline resolves those conditionals the same
-way (`tools/extract/util.py` `ASM_DEFINES`), so most of a Blue build
-falls out of re-running the extractors. Only three things are
-hand-ported on the Lua side and need swapping by hand.
-
-## What differs between Red and Blue
-
-| Where (pokered) | What |
-| --- | --- |
-| `data/wild/maps/*.asm` (34 files) | Version-exclusive encounters (Red: Ekans, Oddish, Growlithe, Mankey, Scyther, Electabuzz,  Blue: Sandshrew, Bellsprout, Vulpix, Meowth, Pinsir, Magmar) |
-| `data/pokemon/title_mons.asm` | The 16 title-screen Pokémon |
-| `engine/movie/title.asm` + `gfx/version.asm` | The "Red Version" / "Blue Version" ribbon |
-| `constants/player_constants.asm` | Preset names (Red: RED/ASH/JACK + BLUE/GARY/JOHN) |
-| `data/sgb/sgb_palettes.asm`, `sgb_border.asm` | Super Game Boy palettes and border |
-| `data/events/prizes.asm`, `prize_mon_levels.asm` | Game Corner prize mons, costs and levels |
-| `engine/movie/intro.asm`, `data/credits/credits_text.asm`, `engine/slots/slot_machine.asm`, `engine/battle/animations.asm`, `audio/sfx/save_3.asm` | Small gated tweaks (credits say "BLUE VERSION STAFF", etc.) |
-
-## Step 1,  flip the extraction define
-
-`tools/extract/util.py`:
-
-```python
-ASM_DEFINES = {"_RED"}   # -> {"_BLUE"}
-```
-
-Then regenerate everything (same as scripts/setup.sh does):
-
-```sh
-cd tools
-../.venv/bin/python3 build_data.py \
-    --pokered /Users/bryanbassett/Documents/development/pokered \
-    --out ../data/generated --assets ../assets/generated
-```
-
-This alone switches the wild encounters, preset names, SGB palettes
-and credits text. **Caveat:** `parse_preset_names` sanity-checks in
-`tools/extract/field.py:1193` expect "RED" in the player presets, 
-relax that check for a Blue build (Blue's presets are BLUE/GARY/JOHN
-for the player and RED/ASH/JACK for the rival).
-
-`tools/extract/palettes.py` uses its own raw reader with hardcoded
-`IF DEF(_BLUE)` skipping (around line 44),  invert that too, or port
-it to `read_asm` so `ASM_DEFINES` covers it.
-
-## Step 2,  title screen (hand-ported)
-
-`src/ui/TitleState.lua`:
-
-1. **Ribbon art.** The extractor writes
-   `assets/generated/title/red_version.png`; add `blue_version.png`
-   to `gfx.extract_title` in `tools/extract/gfx.py` (source:
-   `gfx/title/blue_version.png`, 64×8). In `TitleState:draw()`, the
-   Red strip needs two quads (tiles 0–1 "Red", skip, tiles 5–9
-   "Version",  `title.asm` `VersionOnTitleScreenText`). Blue's strip
-   prints its tiles contiguously (`db $61..$68`), so draw the whole
-   64×8 image at px (56, 64) and verify with the title driver
-   screenshot.
-
-2. **Title mons.** Replace `CYCLE_SPECIES` with Blue's list from
-   `data/pokemon/title_mons.asm`:
-
-   ```lua
-   local CYCLE_SPECIES = {
-     "SQUIRTLE", "CHARMANDER", "BULBASAUR", "MANKEY", "HITMONLEE",
-     "VULPIX", "CHANSEY", "AERODACTYL", "JOLTEON", "SNORLAX",
-     "GLOOM", "POLIWAG", "DODUO", "PORYGON", "GENGAR", "RAICHU",
-   }
-   ```
-
-## Step 3,  Game Corner prizes (hand-ported)
-
-`data/scripts/story3.lua` (~line 209) carries the Red prize tables.
-Blue's values (`prizes.asm` + `prize_mon_levels.asm`):
-
-| Prize | Cost | Level |
-| --- | --- | --- |
-| ABRA | 120 | 6 |
-| CLEFAIRY | 750 | 12 |
-| NIDORINO | 1200 | 17 |
-| PINSIR | 2500 | 20 |
-| DRATINI | 4600 | 24 |
-| PORYGON | 6500 | 18 |
-
-(TM prizes are identical in both versions.)
-
-## Step 4,  verify
-
-```sh
-luajit tests/run_tests.lua
-```
-
-Plus two spot checks:
-
-```sh
-# every grass table must have exactly 10 slots (a conditional-parsing
-# regression shows up as 19–20 slots)
-luajit -e 'local e=dofile("data/generated/encounters.lua")
-for m,d in pairs(e) do if type(d)=="table" and d.grass and #d.grass.slots>0
-  and #d.grass.slots~=10 then print("BAD",m,#d.grass.slots) end end'
-
-# a Blue exclusive should now appear (and Growlithe should not)
-grep -c VULPIX data/generated/encounters.lua
-grep -c GROWLITHE data/generated/encounters.lua
-```
-
-Title screenshot: run the driver in
-`tests/drivers/` style (`SHOT_DIR=... POKEPORT_DRIVER=... love .`) and
-eyeball the ribbon, title mon, and copyright row.
-
-## What you get for free / what to skip
-
- Free after re-extraction: encounters (incl. Super Rod groups), SGB
-  palettes, preset names, credits text, the gated sfx/animation
-  tweaks.
- Trades, gift Pokémon, story scripts, gym data: identical in Western
-  Red/Blue,  nothing to touch.
- Save files: a Red save loads fine, but dex AREA nests and new
-  encounters will be Blue's. Trainer parties are identical.
-
-## Making it a runtime toggle instead
-
-If you want one build with both versions, extraction would need to
-emit both branches keyed by version (e.g. `slots` / `slotsBlue`) and
-the three hand-ported spots would read a `save.version` or
-`conf.lua` flag. That is a bigger change than the rebuild above, 
-the flip-and-regenerate route needs no engine changes at all.
@@ -0,0 +1,615 @@
+# Pokémon Gold, Silver, and Crystal: A Systematic Engine, ASM, and Behavioral Comparison
+
+## Executive summary
+
+Pokémon Gold and Silver are best understood as **two data-configured builds of one engine**, whereas Pokémon Crystal is an **expanded, reorganized, Color-only derivative of that engine**. The `pret/pokegold` repository reproducibly builds the international Gold and Silver ROMs byte-for-byte, while `pret/pokecrystal` separately builds multiple international Crystal revisions and debug artifacts. This makes the two repositories unusually strong primary evidence: their output hashes correspond to known retail binaries rather than merely reimplementing observed behavior.
+
+The largest technical conclusion is that Crystal is **not a ground-up engine rewrite**. Core subsystems (the frame-driven sound interpreter, hardware-derived RNG, synchronized link-battle PRNG, wild-encounter probability machinery, party-mon record size, and much of the RTC pipeline) remain recognizably inherited from Gold/Silver. Crystal instead adds new ROM banks, reorganizes routines, introduces Color-specific rendering paths, fills formerly reserved fields in Pokémon records, redesigns SRAM placement, and layers Battle Tower, Mobile System GB, animated sprites, the female protagonist, Buena, Move Tutor, Suicune story logic, and Virtual Console hooks around the inherited core.
+
+The most important behavioral differences are therefore caused less by wholesale algorithm replacement than by **changed control flow and data**:
+
+| Area | Gold and Silver | Crystal | Technical consequence |
+|---|---|---|---|
+| Edition structure | One shared engine with edition-selected encounter, sprite, title, and other data | One enhanced-version build with regional/revision conditionals | Gold-to-Silver ports are mostly data substitutions; Gold/Silver-to-Crystal ports are architectural merges |
+| Display target | Runtime distinguishes DMG/SGB/CGB modes | Explicit Color-only path | Crystal code can assume CGB palettes, VRAM banking, and related presentation behavior more aggressively |
+| RNG core | Divider-register accumulator plus synchronized link PRNG | Same algorithms | Different outcomes normally arise from different call timing or paths, not a different generator |
+| Party records | Two bytes after Pokérus are reserved | Those same bytes become caught-time/gender/level/location metadata | Pokémon records remain structurally compatible despite Crystal gaining metadata |
+| Save layout | Main and backup data are fragmented among SRAM sections | Main and backup records become more contiguous; Crystal/Battle Tower/Mobile blocks are added | Whole `.sav` files are not drop-in interchangeable |
+| Battles | Standard Gen II battle engine | Inherited engine plus Battle Tower branches and selective bug fixes | Link-compatible behavior is intentionally retained in some otherwise-fixed cases |
+| Roaming Pokémon | Raikou, Entei, and Suicune use the roaming system | Only Raikou and Entei roam; Suicune becomes a scripted encounter | Encounter-state conversion requires special handling |
+| Graphics | Static Pokémon fronts and DMG/SGB-compatible layouts | Animated fronts, revised sprites, richer Color layouts | Animation introduces new graphics data, decompression, frame, and timing requirements |
+| Audio | Shared four-channel Game Boy music interpreter | Same interpreter plus new songs and call sites | Music ports are mostly data/pointer work rather than synthesizer rewrites |
+| Major fixed defects | Coin Case arbitrary code execution, first-save Hall of Fame corruption, Lucky Number box limit, and several map/text defects | Corrected | Crystal is safer, but not "bug-fixed Gen II" in the broad sense |
+| Persistent defects | Many Gen II battle, capture, item, and badge defects | Many remain | Mechanical compatibility often outweighed cleanup |
+
+Gold and Silver themselves have almost no meaningful engine-level divergence. Their scientifically interesting comparison is principally **which tables and assets are selected at assembly time**. Crystal is the meaningful engine comparison.
+
+The report assumes a technically literate audience familiar with low-level programming but not necessarily Game Boy internals. Unless explicitly stated, "Crystal" means the international English code represented by `pret/pokecrystal`; Japanese Mobile System GB and Australian/revision-specific behavior are treated as regional variants. "Scientific" here means reproducible binary-derived comparison, explicit source hierarchy, and separation of direct evidence from inference, not laboratory experimentation involving original development source code, which has not been publicly released.
+
+## Scope, evidence, and reproducibility
+
+### Source hierarchy
+
+The strongest sources are the two pret disassemblies:
+
+- [`pret/pokegold`](https://github.com/pret/pokegold), which builds exact Gold and Silver international ROM images.
+- [`pret/pokecrystal`](https://github.com/pret/pokecrystal), which builds Crystal international v1.0, v1.1, Australian, and debug images.
+
+The repositories identify exact SHA-1 outputs. Gold builds to `d8b8a3600a465308c9953dfa04f0081c05bdcb94`, Silver to `49b163f7e57702bc939d642a18f591de55d92dae`, Crystal international v1.0 to `f4cd194bdee0d04ca4eac29e09b8e4e9d818c133`, and Crystal international v1.1 to `f2f52230b536214ef7c9924f483392993e226cfb`. Those reproducible identities are critical: a label such as `BadgeStatBoosts` is a reverse-engineered name, but the emitted bytes and resulting behavior are those of the retail ROM.
+
+Secondary sources such as Bulbapedia and Serebii are useful for player-visible cross-checking, release differences, encounter availability, and historical context. The pret bug documents are stronger than ordinary wiki summaries for defects because they identify the responsible instructions and provide corrective diffs. Official Nintendo and Pokémon sources are most valuable for release/Virtual Console behavior and supported transfer paths, but they do not publish the games' assembly architecture.
+
+### Reproducible comparison method
+
+A rigorous comparison should operate at four levels:
+
+| Level | Method | What it establishes | Main limitation |
+|---|---|---|---|
+| Binary identity | Build each repository with its pinned RGBDS-compatible toolchain and verify SHA-1 | The source corresponds to the target retail ROM | Does not explain why bytes differ |
+| Source topology | Compare `main.asm`, `home.asm`, bank sections, include graphs, WRAM/SRAM declarations | Architectural additions, removals, and relocation | File organization can change without behavioral change |
+| Routine semantics | Compare labels, branches, register use, calls, data offsets, and side effects | Control-flow and algorithmic differences | Labels and comments are community-derived |
+| Behavioral validation | Run controlled emulator tests with trace logging and fixed input timing | Observable consequences and RNG/cycle sensitivity | Emulator accuracy and RTC state must be controlled |
+
+For a formal experiment, the recommended independent variables are edition, ROM revision, initial SRAM, RTC register state, boot hardware mode, input sequence, and link mode. Dependent variables include RNG bytes, encounter choice, battle result, SRAM writes, audio commands, VRAM/OAM writes, and cycle/frame number. Because the ordinary RNG reads the divider register, deterministic comparisons must start from a controlled boot state and reproduce input timing at frame or cycle precision.
+
+### Gold versus Silver as a build-configuration comparison
+
+The fact that `pokegold` emits both Gold and Silver from one repository is itself strong evidence that the two versions share the same broad code architecture. Edition differences are implemented through conditional assembly and alternate data or assets rather than through separate engines. The obvious behavioral results are version-specific wild Pokémon, title graphics, mascot-facing presentation, and selected NPC or table data; battle arithmetic, saves, RTC processing, audio interpretation, and link handling come from the same shared source.
+
+This distinction matters for analysis. Treating Gold, Silver, and Crystal as three equally separate engines exaggerates Gold/Silver differences and understates Crystal's structural changes. A better model is:
+
+```mermaid
+flowchart TD
+    GSC[Generation II design and data model]
+    GS[Gold/Silver shared engine]
+    GD[Gold-selected data and assets]
+    SD[Silver-selected data and assets]
+    C[Crystal derivative engine]
+    CF[Crystal-only feature modules]
+    CR[Crystal revisions and regional flags]
+
+    GSC --> GS
+    GS --> GD
+    GS --> SD
+    GS --> C
+    C --> CF
+    C --> CR
+```
+
+## ROM and engine architecture
+
+### Banked execution model
+
+The games execute on the Game Boy's LR35902-class CPU and are organized around a fixed home bank plus switchable ROM banks. Calls across banks generally pass through wrappers that save the current bank, select the target bank, call the routine, and restore the original bank. The `BattleRandom` wrapper is a concise example: `_BattleRandom` resides outside the home bank, so the wrapper saves `hROMBank`, uses the bank-switch restart vector, calls the routine, preserves its return value, and restores the previous bank.
+
+```asm
+BattleRandom::
+    ldh a, [hROMBank]
+    push af
+    ld a, BANK(_BattleRandom)
+    rst Bankswitch
+    call _BattleRandom
+    ...
+    pop af
+    rst Bankswitch
+    ret
+```
+
+Relevant sources: [Gold/Silver `home/random.asm`](https://github.com/pret/pokegold/blob/a0dad0957ac8a9ffa67e950ee3ab6715a212ded5/home/random.asm#L29-L46) and [Crystal `home/random.asm`](https://github.com/pret/pokecrystal/blob/8e8f7e20052a596371a77022f0392c285e51bbf1/home/random.asm#L29-L46).
+
+The repositories' top-level `main.asm` files are effectively link manifests for this architecture. Gold/Silver's file groups the battle core, encounters, party menu, RTC, phone, Pokégear, sprite animation, graphics loading, and other systems into named ROM sections. Crystal retains those categories but adds explicitly named feature sections and many additional modules.
+
+### Crystal as an extension and bank-layout rewrite
+
+Crystal's `main.asm` introduces a conspicuous `Crystal Features 1` section containing gender initialization, Kris-specific bag handling, Move Tutor, Crystal layouts, Celebi logic, the redesigned main menu, Mobile menu code, owned-Pokémon search, and Buena's menu. Nearby banks add Battle Tower trainer logic, caught-data handling, a revised stats screen, sliding battle intros, battle-scene checks, and the Color-only startup screen.
+
+That include topology supports three conclusions.
+
+First, Crystal preserves **vertical subsystem continuity**. The battle engine is still `engine/battle/core.asm`; encounters remain `engine/overworld/wildmons.asm`; Pokémon records still derive from the same party/box macros; and audio is still driven by the same interpreter.
+
+Second, Crystal adds **horizontal feature coupling**. Battle Tower touches battle setup, stat boosts, experience rules, saving, menus, SRAM, trainers, music, and link-like constraints. The female protagonist touches initialization, sprites, bag graphics, caught metadata, and menu presentation. Mobile support touches interrupts, SRAM, menus, communications, rankings, and audio.
+
+Third, code and data relocation is substantial enough that raw ROM addresses from Gold/Silver cannot generally be transplanted into Crystal. A symbolic port based on labels and structures is practical; a patch based on absolute offsets is brittle.
+
+### File and routine comparison
+
+| Subsystem | Gold/Silver source | Crystal source | ASM-level difference | Porting significance |
+|---|---|---|---|---|
+| Top-level bank graph | [`main.asm`](https://github.com/pret/pokegold/blob/a0dad0957ac8a9ffa67e950ee3ab6715a212ded5/main.asm) | [`main.asm`](https://github.com/pret/pokecrystal/blob/8e8f7e20052a596371a77022f0392c285e51bbf1/main.asm) | Crystal adds feature, Battle Tower, Mobile, gender, animation, and caught-data modules and relocates shared includes | Port by symbol and feature dependency, not ROM offset |
+| Ordinary RNG | [`home/random.asm`](https://github.com/pret/pokegold/blob/a0dad0957ac8a9ffa67e950ee3ab6715a212ded5/home/random.asm) | [`home/random.asm`](https://github.com/pret/pokecrystal/blob/8e8f7e20052a596371a77022f0392c285e51bbf1/home/random.asm) | Essentially identical routine and rejection-sampling helper | RNG-sensitive ports must preserve call timing |
+| Battle core | [`engine/battle/core.asm`](https://github.com/pret/pokegold/blob/a0dad0957ac8a9ffa67e950ee3ab6715a212ded5/engine/battle/core.asm) | [`engine/battle/core.asm`](https://github.com/pret/pokecrystal/blob/8e8f7e20052a596371a77022f0392c285e51bbf1/engine/battle/core.asm) | Crystal adds Battle Tower guards and conditional fixes while retaining link behavior | Mechanical changes can desynchronize unmodified peers |
+| Encounters | [`engine/overworld/wildmons.asm`](https://github.com/pret/pokegold/blob/a0dad0957ac8a9ffa67e950ee3ab6715a212ded5/engine/overworld/wildmons.asm) | [`engine/overworld/wildmons.asm`](https://github.com/pret/pokecrystal/blob/8e8f7e20052a596371a77022f0392c285e51bbf1/engine/overworld/wildmons.asm) | Same rate/slot pipeline; different swarm state and two rather than three roamers | World-state conversion needs special Suicune handling |
+| SRAM declaration | [`ram/sram.asm`](https://github.com/pret/pokegold/blob/a0dad0957ac8a9ffa67e950ee3ab6715a212ded5/ram/sram.asm) | [`ram/sram.asm`](https://github.com/pret/pokecrystal/blob/8e8f7e20052a596371a77022f0392c285e51bbf1/ram/sram.asm) | Crystal consolidates save/backup regions and adds GS Ball, Battle Tower, rankings, and Mobile blocks | Whole-save binary compatibility is lost |
+| Pokémon structures | [`pokemon_data_constants.asm`](https://github.com/pret/pokegold/blob/a0dad0957ac8a9ffa67e950ee3ab6715a212ded5/constants/pokemon_data_constants.asm#L69-L103) | [`pokemon_data_constants.asm`](https://github.com/pret/pokecrystal/blob/8e8f7e20052a596371a77022f0392c285e51bbf1/constants/pokemon_data_constants.asm#L69-L108) | Crystal assigns caught metadata to two bytes reserved in Gold/Silver | Record length remains compatible |
+| RTC/home time | [`home/time.asm`](https://github.com/pret/pokegold/blob/a0dad0957ac8a9ffa67e950ee3ab6715a212ded5/home/time.asm) | [`home/time.asm`](https://github.com/pret/pokecrystal/blob/8e8f7e20052a596371a77022f0392c285e51bbf1/home/time.asm) | Same RTC model; Crystal timer interrupt can dispatch Mobile timing | Emulator ports must emulate RTC and, for Japanese features, mobile timing assumptions |
+| Picture loading | [`engine/gfx/load_pics.asm`](https://github.com/pret/pokegold/blob/a0dad0957ac8a9ffa67e950ee3ab6715a212ded5/engine/gfx/load_pics.asm) | [`engine/gfx/load_pics.asm`](https://github.com/pret/pokecrystal/blob/8e8f7e20052a596371a77022f0392c285e51bbf1/engine/gfx/load_pics.asm) | Crystal has additional front-picture and animation-oriented handling | Static sprite replacement is insufficient |
+| Sound interpreter | [`audio/engine.asm`](https://github.com/pret/pokegold/blob/a0dad0957ac8a9ffa67e950ee3ab6715a212ded5/audio/engine.asm) | [`audio/engine.asm`](https://github.com/pret/pokecrystal/blob/8e8f7e20052a596371a77022f0392c285e51bbf1/audio/engine.asm) | Core interpreter is structurally the same | New Crystal music is primarily sequenced data and pointers |
+| Song table | [`audio/music_pointers.asm`](https://github.com/pret/pokegold/blob/a0dad0957ac8a9ffa67e950ee3ab6715a212ded5/audio/music_pointers.asm) | [`audio/music_pointers.asm`](https://github.com/pret/pokecrystal/blob/8e8f7e20052a596371a77022f0392c285e51bbf1/audio/music_pointers.asm#L97-L108) | Crystal appends ten named songs | Existing song IDs remain stable through the Gold/Silver range |
+
+The line counts of several Crystal files are larger, but line count alone is not a behavioral metric; comments, label quality, and source refactoring affect it. The stronger evidence is the presence of new branches, fields, tables, and externally observable side effects.
+
+### Hardware-mode divergence
+
+Gold/Silver initialization tests whether the console is a Game Boy Color and maintains non-CGB paths, including Super Game Boy initialization. Crystal includes an explicit `gbc_only.asm` module that displays the incompatibility message on non-CGB hardware. That is not merely marketing metadata: it changes what assumptions later rendering code may safely make about palettes, VRAM banking, and Color hardware.
+
+For a reverse port of Crystal features into Gold/Silver, every CGB-only feature falls into one of three categories: provide a monochrome/SGB fallback, disable it outside CGB mode, or intentionally convert the resulting ROM into a Color-only build. Skipping that decision produces subtle failures rather than one clean compile error: palette attributes, second-bank VRAM data, and tile-upload timing can all be implicated.
+
+## Save, RNG, clock, and entity state
+
+### Save architecture
+
+Gold/Silver divide their main game state into options, three player-data fragments, current-map data, Pokémon data, and a checksum. Backup pieces are distributed among several separately placed SRAM sections. The current PC box is separate, the fourteen inactive boxes occupy exactly two SRAM banks, and mail and Mystery Gift have dedicated regions.
+
+Crystal instead defines a contiguous `sGameData` consisting of player, map, and Pokémon data, pads the region, and stores a checksum. Its backup is similarly grouped. Crystal then adds a GS Ball flag, `sCrystalData`, Battle Tower progress and recent-trainer state, ranking records, Mobile communication data, offers, credentials, and Japanese Mobile-specific buffers. The source explicitly notes that the international `sCrystalData` location differs from Japanese Crystal.
+
+| Save component | Gold/Silver | Crystal |
+|---|---|---|
+| Options and corruption sentinels | Present | Present |
+| Main player/map/Pokémon data | Split into labeled player fragments inside the save region | Grouped into one contiguous main-game block |
+| Main checksum | 16-bit checksum after game data | 16-bit checksum after padded game-data region |
+| Backup | Fragmented among multiple SRAM sections | Consolidated backup game-data block |
+| Current box | Separate `curbox` structure | Separate full `box` structure plus padding |
+| Inactive boxes | Fourteen boxes over two SRAM banks | Same fourteen-box capacity over two banks |
+| Party and mailbox mail | Dedicated primary and backup regions | Same broad model |
+| GS Ball state | Absent | Primary and backup flags |
+| Battle Tower | Absent | Challenge state, streak, previous teams, reward |
+| Mobile/rankings | Absent | Several additional SRAM sections |
+| Full-file compatibility | Gold and Silver are closely related but still edition-specific | Not layout-compatible with Gold/Silver |
+
+Crystal's save routine makes the transactional sequence visible:
+
+```asm
+_SaveGameData:
+    farcall StageRTCTimeForSave
+    farcall BackupMysteryGift
+    call ValidateSave
+    call SaveOptions
+    call SavePlayerData
+    call SavePokemonData
+    call SaveBox
+    call SaveChecksum
+    call ValidateBackupSave
+    ...
+    farcall BackupGSBallFlag
+    farcall SaveRTC
+```
+
+Source: [Crystal `engine/menus/save.asm`](https://github.com/pret/pokecrystal/blob/8e8f7e20052a596371a77022f0392c285e51bbf1/engine/menus/save.asm#L255-L284). The routine stages RTC state, writes the primary data and box, computes the primary checksum, writes backup data and checksum, backs up party mail and GS Ball state, persists RTC state, and normalizes a completed Battle Tower reward state.
+
+The practical conclusion is precise: **do not migrate a Gold/Silver `.sav` to Crystal by copying the file or the main save block**. A converter should parse symbolic fields, validate checksums and sentinels, copy player/map/Pokémon/box/mail data field by field, initialize Crystal-only state, and regenerate Crystal checksums. Gold-to-Silver conversion is less structurally disruptive, but version-dependent event and encounter state should still be treated deliberately.
+
+### Party and boxed-Pokémon records
+
+One of Crystal's most elegant compatibility decisions is visible at the structure-definition level. In Gold/Silver, the two bytes after `MON_POKERUS` are simply reserved:
+
+```asm
+DEF MON_HAPPINESS rb
+DEF MON_POKERUS   rb
+                  rb_skip 2
+DEF MON_LEVEL     rb
+```
+
+In Crystal, the same positions are assigned to a two-byte caught-data field:
+
+```asm
+DEF MON_HAPPINESS  rb
+DEF MON_POKERUS    rb
+DEF MON_CAUGHTDATA rw
+DEF MON_LEVEL      rb
+```
+
+Sources: [Gold/Silver structure](https://github.com/pret/pokegold/blob/a0dad0957ac8a9ffa67e950ee3ab6715a212ded5/constants/pokemon_data_constants.asm#L83-L101) and [Crystal structure](https://github.com/pret/pokecrystal/blob/8e8f7e20052a596371a77022f0392c285e51bbf1/constants/pokemon_data_constants.asm#L83-L107).
+
+Crystal packs caught time and trainer gender into one byte and caught level and location into another. Because Game Freak repurposed reserved bytes instead of extending the record, `BOXMON_STRUCT_LENGTH` and `PARTYMON_STRUCT_LENGTH` remain compatible. Gold/Silver can carry those bytes without understanding them; Crystal can interpret them when present. This is a major reason Gen II Pokémon can move among Gold, Silver, and Crystal without a record-size translation layer.
+
+A second structure change appears in the base-species TM/HM compatibility bitset. Gold/Silver size it for `NUM_TM_HM`; Crystal sizes it for `NUM_TM_HM_TUTOR`, accommodating Move Tutor compatibility in the same species-data model. This means a straight copy of Gold/Silver base-stat records into Crystal must account for Crystal's expanded learnability domain even if the visible species stats are unchanged.
+
+### Item and party handling
+
+The basic inventory model (separate item pockets, held-item byte in each Pokémon record, party length of six, PC boxes, mail records, and item-dispatch routines) is inherited. Crystal's changes are concentrated in new consumers and UI behavior: Move Tutor eligibility, gender-specific player presentation, caught metadata, Battle Tower restrictions, and additional event items such as GS Ball state.
+
+Crystal did **not** comprehensively repair the item mechanics. Its documented defects still include Moon Ball not applying its intended multiplier, Love Ball checking the wrong gender relationship, Fast Ball applying to only a few species, three incorrect Heavy Ball weight cases, and status conditions failing to affect capture rate as intended. Those defects live in shared mechanical paths and are important when evaluating a "faithful" engine port: correcting them changes gameplay and may alter deterministic test vectors.
+
+### Ordinary RNG
+
+Gold/Silver and Crystal use the same ordinary RNG routine. It samples the hardware divider register and updates two one-byte accumulators, one by addition-with-carry and one by subtraction-with-carry:
+
+```asm
+ldh a, [rDIV]
+ld b, a
+ldh a, [hRandomAdd]
+adc b
+ldh [hRandomAdd], a
+
+ldh a, [rDIV]
+ld b, a
+ldh a, [hRandomSub]
+sbc b
+ldh [hRandomSub], a
+```
+
+Sources: [Gold/Silver](https://github.com/pret/pokegold/blob/a0dad0957ac8a9ffa67e950ee3ab6715a212ded5/home/random.asm#L13-L27) and [Crystal](https://github.com/pret/pokecrystal/blob/8e8f7e20052a596371a77022f0392c285e51bbf1/home/random.asm#L13-L27). The files are effectively identical, including the `RandomRange` rejection-sampling routine used to avoid simple modulo bias.
+
+This generator is not a self-contained seeded PRNG in the modern sense. Its output depends on divider phase, previous accumulator state, carry state, VBlank updates, and when the routine is reached. Consequently, adding an animation, menu delay, conditional call, or extra random-consuming feature can alter later outcomes even while the RNG instructions remain unchanged.
+
+### Link-battle PRNG
+
+Battles route randomness through `BattleRandom`. In non-link play, `_BattleRandom` ultimately uses the ordinary RNG. In linked battles, both systems consume a shared ten-byte random sequence and advance bytes with the recurrence:
+
+```
+x[n+1] = (5 * x[n] + 1) mod 256
+```
+
+The Gold/Silver and Crystal battle cores contain the same broad synchronization mechanism.
+
+This has a major compatibility consequence: a battle patch can be logically correct in isolation yet break link play if it causes one participant to make a different number or order of RNG calls. That is why Crystal sometimes preserves Gold/Silver behavior specifically in link battles. Synchronization depends on matching control flow, not merely using the same random-number formula.
+
+### RTC and time-of-day behavior
+
+Both codebases latch the MBC3-style real-time clock, read seconds, minutes, hours, and the low/high day registers, normalize time, add the player's selected starting offset, and derive the current time-of-day state. Crystal's `UpdateTime` remains a short chain of `GetClock`, `FixDays`, `FixTime`, and `GetTimeOfDay`.
+
+Crystal's source shows the day counter reduced modulo 140 for the game's weekly/event model, with status flags distinguishing an RTC count beyond 139 days and a hardware day-high overflow beyond 255 days. The displayed game time is formed by adding the new-game start offsets to RTC values with carry through seconds, minutes, hours, and day.
+
+The notable architectural addition is the Crystal timer interrupt's Mobile dispatch:
+
+```asm
+Timer::
+    push af
+    ldh a, [hMobile]
+    and a
+    jr z, .not_mobile
+    call MobileTimer
+.not_mobile
+    pop af
+    reti
+```
+
+Source: [Crystal `home/time.asm`](https://github.com/pret/pokecrystal/blob/8e8f7e20052a596371a77022f0392c285e51bbf1/home/time.asm#L2-L11). The ordinary RTC logic remains inherited; Japanese/mobile Crystal adds another timing consumer.
+
+For emulators, flash cartridges, and ports, SRAM alone is insufficient. RTC registers, halt/carry state, elapsed host time, and game offsets must be preserved consistently. A save imported without corresponding RTC state may be structurally valid yet produce incorrect daily events, phone behavior, berries, swarms, day-of-week encounters, or time-dependent evolutions.
+
+## Battles and encounters
+
+### Battle-engine inheritance
+
+The core Gen II battle model is shared: turn selection, speed ordering, accuracy, damage, stat stages, held items, status, volatile effects, experience, capture, AI, and link synchronization follow the same broad engine. Crystal's battle core is larger principally because it adds Battle Tower integration, additional presentation paths, and selective corrections.
+
+Crystal is therefore mechanically closer to a patched and extended Gold/Silver than to a later-generation ruleset. There are no abilities, natures, modern physical/special move split, or rewritten damage model. Its new content operates within Gen II's existing move and Pokémon structures.
+
+### Control-flow difference: Battle Tower exclusions
+
+Gold/Silver's `BadgeStatBoosts` exits for link battles and otherwise applies badge boosts. Crystal adds a second early return when `wInBattleTowerBattle` is nonzero:
+
+```asm
+ld a, [wLinkMode]
+and a
+ret nz
+
+ld a, [wInBattleTowerBattle]
+and a
+ret nz
+```
+
+Source: [Crystal `BadgeStatBoosts`](https://github.com/pret/pokecrystal/blob/8e8f7e20052a596371a77022f0392c285e51bbf1/engine/battle/core.asm#L6526-L6532). Gold/Silver have only the link-mode guard at the corresponding point.
+
+This tiny six-instruction addition is representative of Crystal's design. The stat algorithm was not replaced; Crystal introduced a new battle context and inserted a guard so adventure-only badge advantages do not leak into the standardized Battle Tower. Similar context checks appear around experience and other post-battle handling.
+
+### Selective fixes constrained by link compatibility
+
+The pret Crystal bug documentation explicitly states that Crystal fixed Gold/Silver's Reflect/Light Screen overflow and Present damage behavior only where doing so would not break ordinary cross-version link battles. Link-mode behavior retains the compatible path.
+
+That is an important historical engineering tradeoff. A fully corrected Crystal battle engine would disagree with Gold/Silver on intermediate values and potentially on RNG consumption, damage, fainting, or message sequence. Compatibility with the installed base was treated as a protocol requirement. Consequently, "Crystal fixed the bug" can mean **fixed in single-player but deliberately retained in linked simulation**.
+
+### Shared and persistent battle defects
+
+Crystal retains a substantial Gen II defect surface. Documented examples include:
+
+| Defect | Mechanical effect | Crystal status |
+|---|---|---|
+| "100%" secondary effects | Fail in 1/256 qualifying cases | Retained |
+| Belly Drum | May maximize Attack even when the HP requirement is not properly met | Retained |
+| Berserk Gene | Confusion duration can become 256 turns or inherit stale state | Retained |
+| Confusion damage | Can receive type-item and Explosion/Self-Destruct modifiers | Retained |
+| Beat Up | Can behave incorrectly and can desynchronize link battles | Retained |
+| Return/Frustration edge | Can produce zero damage at extreme happiness values | Retained |
+| Dragon boosting item | Dragon Scale is checked instead of Dragon Fang | Retained |
+| Glacier Badge | Special Defense boost depends incorrectly on overwritten accumulator state | Retained |
+| Capture status bonus | Burn, poison, and paralysis do not contribute as intended | Retained |
+| Specialty Balls | Multiple Apricorn-ball formulas target the wrong condition or table | Retained |
+
+These are documented against original Crystal code, not inferred from modern competitive summaries.
+
+The Glacier Badge defect is especially instructive at ASM level. The routine shifts a badge bitfield through register `b`, calls `BoostStat`, and later reuses register `a` as if it still contained the expected badge value. `BoostStat` can overwrite `a`, so whether Special Defense receives its boost depends on the Special Attack calculation's resulting register state. The bug survived Crystal even though the source gained an explicit comment identifying it.
+
+### Gold/Silver defects corrected in Crystal
+
+The `pokegold` bug document separates defects fixed in Crystal from defects still shared with it. It identifies seven clear Gold/Silver corrections: Coin Case arbitrary code execution, Hall of Fame corruption when no prior save exists, Lucky Number failure to inspect boxes 10-14, Present text overflow, surfing onto NPCs, fishing inside Cerulean Gym, and Route 15 capitalization.
+
+The Coin Case correction is one bytecode-level terminator change:
+
+```diff
+ text "Coins:"
+ line "@"
+ text_decimal wCoins, 2, 4
+-done
+text_end
+```
+
+Source: [`pokegold/docs/bugs_and_glitches.md`](https://github.com/pret/pokegold/blob/a0dad0957ac8a9ffa67e950ee3ab6715a212ded5/docs/bugs_and_glitches.md#L20-L34). The Gold/Silver terminator permits text-command execution to continue into unintended memory under exploitable conditions; Crystal ends the text stream correctly.
+
+The Hall of Fame correction adds a saved-at-least-once check and erases/initializes previous-save structures before attempting the Hall of Fame write. The Lucky Number correction changes the loop bound from the Japanese box count constant to the international fourteen-box count. Both are good examples of Crystal correcting localization-sensitive state assumptions rather than changing game design.
+
+### Encounter-rate algorithm
+
+Gold/Silver and Crystal use essentially the same high-level encounter pipeline:
+
+```mermaid
+flowchart TD
+    STEP[Eligible movement step]
+    RATE[Read morning/day/night or water rate]
+    MOD1[Apply radio modifier]
+    MOD2[Apply Cleanse Tag modifier]
+    ROLL[Call Random and compare with rate]
+    SLOT[Choose encounter slot]
+    ROAM[Check roaming Pokémon]
+    REPEL[Apply Repel level check]
+    BATTLE[Stage wild battle]
+
+    STEP --> RATE --> MOD1 --> MOD2 --> ROLL
+    ROLL -->|pass| SLOT
+    SLOT --> ROAM
+    ROAM --> REPEL
+    REPEL --> BATTLE
+```
+
+In both engines, `TryWildEncounter` gets the map rate, applies Pokémon March/Ruins of Alph doubling or Pokémon Lullaby halving, applies Cleanse Tag halving, draws an RNG byte, chooses a slot from grass or water probability tables, and checks Repel.
+
+Grass records contain separate morning, day, and night slot blocks; the active block is selected through `wTimeOfDay`. Water uses a separate rate and three-slot table. The structure constants remain seven grass slots and three water slots in both codebases.
+
+### Encounter-table differences
+
+Gold and Silver primarily diverge through edition-conditioned tables. Crystal has its own consolidated tables and changes both availability and placement. It makes several former Gold/Silver exclusives obtainable in one edition, while removing some species available in both base versions; Mareep's evolutionary family is a prominent Crystal omission. Crystal also moves species such as Sneasel to different locations.
+
+The engine/table distinction is important. An encounter may differ because:
+
+1. the map's encounter-rate byte changed;
+2. a morning/day/night slot changed;
+3. the slot's level changed;
+4. a swarm override changed;
+5. a roaming Pokémon was removed from the roaming subsystem;
+6. the map itself gained or lost encounter-enabled tiles.
+
+A robust diff should therefore compare map headers, wild tables, swarm flags, and roaming initialization, not merely produce a Pokédex availability list.
+
+### Swarms and roaming state
+
+Gold/Silver's swarm lookup is comparatively generic: it compares the current map against `wSwarmMapGroup` and `wSwarmMapNumber`. Crystal's code has explicit Dunsparce and Yanma swarm flags and corresponding map state. That is a data-model specialization, not just a changed encounter table.
+
+The roaming difference is even clearer. Gold/Silver initialize three records:
+
+```asm
+ld a, RAIKOU
+ld [wRoamMon1Species], a
+ld a, ENTEI
+ld [wRoamMon2Species], a
+ld a, SUICUNE
+ld [wRoamMon3Species], a
+```
+
+Crystal initializes only Raikou and Entei:
+
+```asm
+ld a, RAIKOU
+ld [wRoamMon1Species], a
+ld a, ENTEI
+ld [wRoamMon2Species], a
+```
+
+Sources: [Gold/Silver `InitRoamMons`](https://github.com/pret/pokegold/blob/a0dad0957ac8a9ffa67e950ee3ab6715a212ded5/engine/overworld/wildmons.asm#L471-L511) and [Crystal `InitRoamMons`](https://github.com/pret/pokecrystal/blob/8e8f7e20052a596371a77022f0392c285e51bbf1/engine/overworld/wildmons.asm#L476-L506).
+
+Gold/Silver's subsequent selection logic describes an equal choice among three beasts after the roaming check succeeds; Crystal changes the corresponding comment and index range to two. Suicune's removal is tied to Crystal's expanded Eusine/Suicune plot and scripted Tin Tower encounter.
+
+For save conversion, a Gold/Silver Suicune roaming record cannot simply remain active in Crystal. The converter must map capture/defeat/event state into Crystal's scripted Suicune flags or deliberately define a hybrid behavior.
+
+## Graphics and audio
+
+### Tile, palette, and sprite model
+
+All three games retain the Game Boy's tile-oriented rendering model: graphics are stored as compact tile data, decompressed or copied into VRAM, arranged through background/window tilemaps, and supplemented by hardware sprites through shadow OAM. Pokémon and many UI images use four-color source palettes, with separate palette data determining their actual colors. The pokecrystal FAQ explicitly notes the four-color paletted-PNG convention and the distinction between image data and palette data.
+
+Gold/Silver must support original Game Boy-style output and Super Game Boy behavior as well as Game Boy Color enhancements. Crystal's explicit Color-only startup path lets it make stronger use of CGB layout and palette machinery. Its top-level architecture adds `crystal_layouts.asm`, dedicated player graphics, revised map and battle presentation, and other CGB-focused modules.
+
+### Animated Pokémon sprites
+
+Crystal's headline renderer change is animated front sprites. Every Pokémon receives an entrance animation, and the status/profile viewer can play a longer animation; several designs, palettes, and back sprites were also revised. Crystal additionally gives the legendary beasts distinct overworld sprites and introduces richer trade-screen presentation.
+
+At the engine level, this requires more than storing extra frames. A full animation path needs:
+
+- a base front picture and additional frame or bitmask data;
+- frame sequencing and duration state;
+- tile-buffer reconstruction or differential tile updates;
+- synchronization with battle intro control flow;
+- palette and VRAM updates during safe LCD periods;
+- fallback behavior for static contexts such as link displays or icons.
+
+Crystal's `load_pics.asm` is correspondingly larger and is integrated with dedicated animation and battle-intro modules, while Gold/Silver's loader primarily services static front/back pictures. The exact file-size difference should not be treated as a performance measurement, but the added code paths confirm a broader graphics pipeline.
+
+Animated fronts can also alter RNG-observable timing indirectly. The ordinary RNG is updated from divider timing and VBlank activity; therefore, any test that compares post-animation random outcomes must control whether animations are enabled and how many frames elapsed. This is an inference from the animation and RNG architectures, not evidence that every animation directly invokes `Random`.
+
+### Color and protagonist handling
+
+Crystal adds player-gender initialization and Kris-specific bag/player graphics. The Pokémon record's caught-data bits can record whether the catcher was the boy or girl protagonist. This is an example of a feature spanning UI, overworld sprites, menus, Pokémon metadata, and save state rather than existing in one isolated "female player" switch.
+
+A Crystal-to-Gold/Silver backport must decide how to handle caught-by-girl metadata when Gold/Silver have no female protagonist UI. Structurally the bytes can survive because they were reserved, but Gold/Silver will not natively display or generate the metadata.
+
+### Sound-engine architecture
+
+The most striking audio result is how little the interpreter changed. Both repositories' `audio/engine.asm` identify themselves as the entire sound engine, update once per frame, parse music commands, maintain eight software channel structures (four music and four sound-effect channels), and ultimately drive the four Game Boy audio channels. Both implementations handle duty, envelope, frequency, vibrato, noise sampling, channel muting, low-health sound, and fades through the same broad code.
+
+```mermaid
+flowchart LR
+    SONG[Song bytecode]
+    PARSE[ParseMusic]
+    STATE[Per-channel WRAM state]
+    FX[Vibrato / pitch / envelope / noise]
+    MIX[Music-SFX priority and routing]
+    APU[Game Boy audio registers]
+
+    SONG --> PARSE --> STATE --> FX --> MIX --> APU
+```
+
+Crystal therefore does not introduce a new synthesizer. It extends the music corpus and invokes new songs in new contexts.
+
+### Crystal's additional music
+
+Gold/Silver's song pointer table ends at `Music_PostCredits`. Crystal retains that ordering and appends ten entries:
+
+| Crystal-only pointer entry | Use |
+|---|---|
+| `Music_Clair` | Clair-related scene |
+| `Music_MobileAdapterMenu` | Japanese Mobile menu |
+| `Music_MobileAdapter` | Mobile connectivity |
+| `Music_BuenasPassword` | Buena's Password |
+| `Music_LookMysticalMan` | Eusine encounter |
+| `Music_CrystalOpening` | Revised opening |
+| `Music_BattleTowerTheme` | Battle Tower battle/context |
+| `Music_SuicuneBattle` | Legendary-beast/Suicune battle theme |
+| `Music_BattleTowerLobby` | Battle Tower lobby |
+| `Music_MobileCenter` | Japanese Mobile Center |
+
+The pointer table labels these explicitly as "new to Crystal."
+
+Bulbapedia independently notes that Crystal gives the legendary beasts a unique battle theme and presents it as the first core-series special legendary battle music.
+
+From a porting perspective, bringing Crystal music into Gold/Silver primarily requires assigning ROM space, importing sequence data, adding pointer/constants entries, and adding selection call sites. Replacing the audio engine is generally unnecessary. However, preserving existing numeric song IDs is wise because map headers, scripts, battle setup, radio state, and fades refer to those constants.
+
+## Bugs, compatibility, porting, and reverse-engineering timeline
+
+### Bug and quirk matrix
+
+| Category | Gold/Silver | Crystal | Engineering interpretation |
+|---|---|---|---|
+| Coin Case text terminator | Exploitable continuation can permit arbitrary code execution | Correct terminator | Parser/data correction |
+| First-save Hall of Fame | Can corrupt PC boxes | Guard and initialization added | Save-state precondition correction |
+| Lucky Number boxes | International boxes 10-14 omitted | Uses full box count | Localization constant corrected |
+| Surf onto NPC | Possible | Facing-object check added | Collision precondition corrected |
+| Cerulean Gym fishing | Enabled by map fish group | Disabled | Map-header data correction |
+| Reflect/Light Screen overflow | Incorrect | Fixed outside compatible link path | Context-dependent battle fix |
+| Present damage | Incorrect | Fixed outside compatible link path | Protocol-preserving fix |
+| Glacier Badge Special Defense | Bugged | Still bugged | Shared inherited defect |
+| Apricorn specialty balls | Multiple formula defects | Still defective | Shared inherited mechanics |
+| Beat Up synchronization | Vulnerable | Still vulnerable | Shared link-engine defect |
+| Secondary-effect 1/256 failure | Present | Present | Shared probability comparison defect |
+| Animated-sprite quirks | Not applicable | New animation-specific defects possible | Feature expansion creates new failure surface |
+
+The Gold/Silver and Crystal bug documents should be read together. The Gold/Silver document intentionally lists only bugs that Crystal fixed; any shared defects are documented in the Crystal repository instead.
+
+Crystal is thus more polished but not mechanically "corrected" in a comprehensive sense. A modern source port must choose a compatibility target:
+
+- **Retail-faithful:** preserve all version-specific bugs and timing.
+- **Crystal-faithful:** preserve Crystal's selective fixes and its link-mode exceptions.
+- **Corrected Gen II:** repair documented defects, accepting that link compatibility and historical RNG traces may change.
+- **Hybrid:** gate corrections behind flags or negotiate them between identical modified link peers.
+
+### ROM revisions and regional code
+
+The Crystal repository builds international v1.0, v1.1, and Australian releases. Its FAQ states that v1.1 corrected some issues in the initial international release, while the Australian build is based on v1.1 and censors gambling references. Thus "Crystal behavior" is not completely singular even within English-language retail ROMs.
+
+A serious test report should always state the target hash rather than merely "Pokémon Crystal." Otherwise, an observed difference may be edition-level, v1.0/v1.1-level, Australian localization, Japanese Mobile code, Virtual Console patching, emulator behavior, or an altered ROM.
+
+### Link and trade compatibility
+
+Gold, Silver, and Crystal share the Gen II Pokémon record length and battle/link architecture, allowing ordinary same-generation trading and battling. The retained two-byte record size, shared `REDMON_STRUCT_LENGTH` conversion constant for Time Capsule interaction, and synchronized battle RNG are all source-level evidence of compatibility-oriented design.
+
+However, three distinct notions of compatibility must not be conflated:
+
+| Compatibility type | Status |
+|---|---|
+| Pokémon record compatibility | Strong: same record length; Crystal fills reserved bytes |
+| Link protocol/battle simulation compatibility | Strong for retail games, partly because Crystal preserves old link behavior |
+| Whole-save-file compatibility | Weak: Crystal's SRAM organization and added state differ substantially |
+| ROM patch-address compatibility | Weak: bank layout and code placement differ |
+| Feature-source portability | Moderate: shared architecture helps, but dependencies are broad |
+| Gen I Time Capsule data compatibility | Supported through dedicated conversion structures and restrictions |
+| Modern transfer compatibility | Supported from 3DS VC releases through Poké Transporter and Pokémon Bank |
+
+Nintendo's support documentation lists the Virtual Console releases of Gold, Silver, and Crystal as compatible with Poké Transporter. Transfers proceed into Pokémon Bank and can then move onward to Pokémon HOME, but that modern path is not a raw Gen II save conversion and is effectively one-way at later stages.
+
+### Virtual Console modifications
+
+Crystal's save code contains an explicit `vc_hook` after Hall of Fame insertion. The hook sets the primary and backup GS Ball flags to make the GS Ball quest and Celebi encounter available, with compile-time assertions pinning the expected SRAM addresses and flag value.
+
+```asm
+vc_hook Enable_GS_Ball_mobile_event
+vc_assert BANK(sGSBallFlag) == $1
+vc_assert BANK(sGSBallFlagBackup) == $1
+```
+
+Source: [Crystal `engine/menus/save.asm`](https://github.com/pret/pokecrystal/blob/8e8f7e20052a596371a77022f0392c285e51bbf1/engine/menus/save.asm#L157-L167).
+
+This is a fascinating compatibility shim: the original international cartridge retained GS Ball-related structures but lacked the original Japanese distribution path, so the Virtual Console wrapper activates the event through a targeted runtime hook. The Pokémon Company confirms that the Virtual Console version permits the Celebi encounter at Ilex Forest's shrine.
+
+The pret repositories also contain `vc` build material, and community GitHub discussion has addressed preserving or generating Virtual Console patches. A port targeting 3DS VC behavior should therefore compare not only the retail ROM but the external patch/hook layer.
+
+### Japanese Crystal and mapper/SRAM concerns
+
+Crystal's SRAM source reserves several Mobile sections and explicitly comments that a Mobile Easy Chat initialization routine uses an "MBC30 bank" available to Japanese Crystal but inaccessible with ordinary MBC3 behavior. This is direct evidence that regional hardware assumptions matter when emulating or reproducing Japanese Mobile features.
+
+An implementation that supports only the common international MBC3-style SRAM/RTC configuration may run the international game correctly yet fail Japanese Crystal's extended Mobile storage accesses. Conversely, allocating the larger memory blindly does not implement Mobile Adapter protocols, timer behavior, ranking checksums, or server-era workflows.
+
+### Porting guidance
+
+The safest migration strategy between the two disassemblies is subsystem-oriented:
+
+| Port direction | Recommended approach | Main hazard |
+|---|---|---|
+| Gold <-> Silver data | Preserve shared engine; switch edition tables/assets | Conditional data references and event assumptions |
+| Crystal feature -> Gold/Silver | Import feature plus all WRAM/SRAM, graphics, script, audio, and menu dependencies | DMG/SGB fallback and bank-space pressure |
+| Gold/Silver behavior -> Crystal | Replace data or selectively restore old branch | Crystal story/event state may expect new semantics |
+| Gold/Silver save -> Crystal | Parse and rebuild symbolic fields | Relocated blocks and Crystal-only state |
+| Crystal save -> Gold/Silver | Strip Crystal state and preserve common Pokémon/player data | Caught metadata becomes opaque; Suicune/Battle Tower state has no target |
+| Retail battle fix | Gate by non-link mode or require identical modified peers | RNG/control-flow desynchronization |
+| Crystal graphics -> DMG-compatible engine | Create monochrome layouts or make build CGB-only | Palette attributes and animation timing |
+| Japanese Mobile feature port | Emulate mapper, extended SRAM, timer, and communication assumptions | Hardware and defunct-service dependencies |
+
+Bank space is a concrete constraint. The pokecrystal FAQ describes the international ROM as 2 MiB divided across banks and notes that adding features can overflow fixed bank placement, requiring sections to be moved through the linker script. Crystal's extra features already consume carefully arranged banks, so a port that compiles at the object level can still fail at link time.
+
+The deepest practical rule is: **port invariants before routines**. Before copying code, define the target's expected record lengths, bank-switch convention, WRAM variables, SRAM addresses, script command set, palette mode, RNG call contract, and link-mode semantics. Once those invariants match, most inherited Gen II routines are straightforward. Without them, a perfectly copied routine can read the wrong field, switch to the wrong bank, write outside a save block, or desynchronize a link battle.
+
+### Release and reverse-engineering evidence timeline
+
+```mermaid
+timeline
+    title Gold, Silver, and Crystal technical lineage
+    1999-11-21 : Gold and Silver released in Japan
+    2000-10-15 : Gold and Silver released in North America
+    2000-12-14 : Crystal released in Japan
+    2001 : International Crystal releases
+         : Crystal adds Color-only presentation, animations, Battle Tower, and expanded Suicune story
+    2017-09-22 : Gold and Silver released for Nintendo 3DS Virtual Console
+    2018-01-26 : Crystal released for Nintendo 3DS Virtual Console
+               : VC hook enables the GS Ball and Celebi event
+    2026 : pret repositories reproducibly build exact retail revisions
+         : ASM-level bug catalogs and symbolic layouts support controlled comparison
+```
+
+Gold and Silver launched in Japan on November 21, 1999 and in North America on October 15, 2000; Crystal followed in Japan on December 14, 2000 and internationally in 2001. Gold/Silver reached 3DS Virtual Console in September 2017 and Crystal followed in January 2018.
+
+The current reverse-engineering record is better described as an evolving evidence base than as a single "discovery date." pret's labels, comments, and bug documentation have accumulated over thousands of repository commits, while the exact-build hashes provide a stable anchor to the retail binaries. Crystal's repository currently has substantially more history and feature documentation than `pokegold`, reflecting its role as the community's principal Gen II hacking platform rather than evidence that Crystal's retail source was inherently better documented.
+
+### Final technical assessment
+
+Gold and Silver are functionally sibling configurations of one engine. Their meaningful differences are overwhelmingly table-, asset-, and version-flag-driven. Crystal preserves that engine's defining architecture but turns it into a more specialized platform: Color-only graphics, animated Pokémon, richer event scripting, expanded persistent state, Mobile-era infrastructure, Battle Tower contexts, caught metadata, additional music, and selective defect correction.
+
+At ASM level, the most consequential changes are not usually exotic algorithms. They are small branches with large semantic reach:
+
+- a Battle Tower early return suppresses badge boosts;
+- two reserved Pokémon bytes acquire caught metadata without changing record size;
+- Suicune disappears from `InitRoamMons`;
+- save blocks become reorganized and gain new persistent domains;
+- a text terminator closes the Coin Case execution path;
+- link-mode checks preserve old arithmetic to avoid desynchronization;
+- a Virtual Console hook activates an otherwise inaccessible event;
+- a Mobile timer branch attaches a new subsystem to the interrupt path.
+
+That pattern explains both Crystal's compatibility and its porting difficulty. It remains recognizably the Gold/Silver engine, but its new features are woven through banks, state structures, control-flow conditions, graphics timing, SRAM, scripts, and presentation. The code is cousin-shaped, not copy-paste-shaped: the classic reverse-engineering booby trap wearing a tiny Suicune hat.
@@ -12,7 +12,7 @@ this port.

 | # | Mechanic | Value | Why the Game Boy had this limit | Where it lives here |
 |---|---|---|---|---|
-| 1 | Bag capacity | 20 item slots | `wNumBagItems` save block was a fixed 20-entry id/quantity array in SRAM | `src/inventory/Bag.lua:8` (`Bag.CAPACITY = 20`) |
+| 1 | Bag capacity | 20 item slots by default | `wNumBagItems` save block was a fixed 20-entry id/quantity array in SRAM | `Data.constants.bagSize`, read by `src/inventory/Bag.lua` (`Bag.capacity`) |
 | 2 | Party size | 6 Pokémon | `wPartyMon1..6` were 6 fixed save-RAM slots | `src/pokemon/Party.lua:5` (`Party.MAX = 6`) |
 | 3 | PC storage | 12 boxes × 20 Pokémon | `wBoxDataStart` / Bill's PC allocated a fixed 12×20 SRAM block | `src/pokemon/Boxes.lua:7-8` |
 | 4 | Moves per Pokémon | 4 | Fixed 4-move-slot field in the party/box Pokémon struct | `src/pokemon/Pokemon.lua:20`, enforced again in `src/battle/BattleState.lua:1941` |
@@ -38,6 +38,10 @@ this port.

 ## Notes

+- Mods may patch `constants.bagSize` through the public content registry. The
+  native `save.lua` format keeps every existing item when the configured
+  limit changes; exporting to a cartridge `.sav` still writes only the first
+  20 bag slots because the original SRAM layout has no room for more.
 - PC Box **overflow handling** was deliberately changed even though the
  20×12 box *shape* was kept faithful: instead of Gen 1's "full box discards
  or blocks the deposit," this port spills into the next box with room.
@@ -0,0 +1,316 @@
+# Gen 2 link play: what it takes
+
+This is a design document, not a feature announcement. Gold cannot link today
+and nothing in this document changes that on its own. What it does is state
+honestly what Gen 2 link play requires, where the Gen 1 protocol in `src/link/`
+stops working on a Gen 2 record, what the cart itself did, and which pieces of
+the work are self-contained enough to have been built already.
+
+The short version: the transport, the handshake and the fingerprint are
+generation-agnostic or nearly so, and those are done. The party wire format is
+half done (a codec exists, nothing sends it). The trade session, the trade UI
+and the lockstep battle are not started, and each is a real piece of work.
+
+Read `docs/mod-api-gen2-compat.md` beside this: it is the reference for what a
+Gold mod may touch, and the link fingerprint's whole job is to hash exactly that
+surface.
+
+## 1. What Gen 1 link play is
+
+`src/link/` is nine files and about four thousand lines:
+
+| File | Job |
+| --- | --- |
+| `Net.lua` | lua-enet transport, LAN host/join plus a relay for online play. JSON messages, no game types. |
+| `CodeEntry.lua` | the online join code widget. |
+| `Handshake.lua` | the `hello` both peers exchange and the compatibility verdict drawn from the two of them. |
+| `Fingerprint.lua` | a deterministic digest of the link surface: the slice of merged Data whose value decides whether two lockstep simulations stay identical. |
+| `Protocol.lua` | mon serialization, the record-subset negotiation, and the trade session state machine. |
+| `LinkState.lua` | the LINK menu, pairing, and the trade/battle hand-off. |
+| `LinkBattle.lua` | lockstep battle: both machines run `src/battle/BattleState.lua` from mirrored perspectives on a shared seed, exchanging one action per turn and a per-turn state hash. |
+| `Tournament.lua` | bracketed online play over the relay. |
+| `Json.lua` | the encoder the wire and several unrelated callers share. |
+
+Only three of those nine are shaped around Gen 1 game content: `Fingerprint`,
+`Protocol` and `LinkBattle`. `Net`, `Json`, `CodeEntry` and most of `Handshake`
+never look at a Pokemon.
+
+## 2. What the cart did
+
+pokegold's link code is `engine/link/link.asm` (2508 lines), and it is worth
+being precise about, because several of the port's design questions have a cart
+answer.
+
+**Three rooms, one wire.** `wLinkMode` is `LINK_TIMECAPSULE`,
+`LINK_TRADECENTER` or `LINK_COLOSSEUM` (`constants/serial_constants.asm`).
+`LinkCommunications` branches once, at the top, on whether the mode is the Time
+Capsule: `Gen2ToGen1LinkComms` for the Time Capsule and `Gen2ToGen2LinkComms`
+for everything else (`engine/link/link.asm:33`). Everything after that branch is
+shared -- the same byte exchange serves trading and battling, and the mode only
+decides what is in the buffer and what the game does afterwards.
+
+**What crosses the wire, in order** (`Gen2ToGen2LinkComms`,
+`engine/link/link.asm:202`):
+
+1. `SERIAL_RN_PREAMBLE_LENGTH + SERIAL_RNS_LENGTH` bytes: the shared battle
+   RNG state. Seven preamble bytes and ten seeds.
+2. `SERIAL_PREAMBLE_LENGTH + NAME_LENGTH + (1 + PARTY_LENGTH + 1) + 2 +
+   (PARTYMON_STRUCT_LENGTH + NAME_LENGTH * 2) * PARTY_LENGTH + 3` bytes: the
+   player name, the party count and species list, the **trainer ID**, six party
+   structs, six OT names and six nicknames.
+3. `SERIAL_PATCH_LIST_LENGTH` bytes: the patch list (see below).
+4. In the Trade Center only, the mail block: six mail messages then six mail
+   metadata structs (`Link_PrepPartyData_Gen2`, `engine/link/link.asm:810`).
+
+**The shared PRNG is the whole trick behind lockstep.** `_BattleRandom`
+(`engine/battle/core.asm:6650`) refuses the normal RNG whenever `wLinkMode` is
+non-zero and pulls from `wLinkBattleRNs` instead: ten seeds, each advanced by
+`a[n+1] = (a[n] * 5 + 1) % 256` when the stream runs out, with the count in
+`wLinkBattleRNCount`. Both machines exchange those ten bytes once, before the
+battle, and never again -- the external-clock side adopts the internal-clock
+side's numbers (`Link_CopyRandomNumbers`, `engine/link/link.asm:1115`). The port
+does the same thing with a Park-Miller stream seeded by the host
+(`LinkBattle.makeRng`), which is the same idea in a different arithmetic.
+
+**The patch list exists because the wire has reserved bytes.**
+`SERIAL_NO_DATA_BYTE` (`$fe`) may not appear in the payload, so
+`FixDataForLinkTransfer` (`engine/link/link.asm:556`) walks the party block,
+replaces every `$fe` with `$ff`, and records the offsets it touched in a
+200-byte list that ships alongside. Mail gets its own smaller version of this in
+`Link_PrepPartyData_Gen2`. The port's wire is JSON over enet and has no reserved
+bytes, so this whole mechanism has no analogue and needs none. It is worth
+knowing about only so nobody reimplements it by accident.
+
+**The Time Capsule is the cart's own answer to a cross-generation link.**
+`CheckTimeCapsuleCompatibility` (`engine/link/link.asm:1970`) refuses the party
+outright for exactly three reasons, and returns which one in `wScriptVar`:
+
+1. a species at or above `JOHTO_POKEMON` (`constants/pokemon_constants.asm:168`,
+   the 152 boundary),
+2. a move above `STRUGGLE`, i.e. any move Gen 1 does not have,
+3. any party member holding mail.
+
+If the party passes, `Link_PrepPartyData_Gen1` (`engine/link/link.asm:640`)
+rewrites every mon into the 44-byte `REDMON_STRUCT_LENGTH` layout:
+`ConvertMon_2to1` remaps the species index through `Pokered_MonIndices`
+(`engine/link/time_capsule_2.asm:1`), the Special stat is recomputed from
+`KantoMonSpecials` because Gen 1 has one Special and Gen 2 has two, and
+Magnemite and Magneton are shipped as pure Electric because their typing changed
+(`engine/link/link.asm:731`). Coming the other way, `Link_ConvertPartyStruct1to2`
+(`engine/link/link.asm:930`) reads the Gen 1 catch rate byte as the held item
+slot -- garbage, which is why `TimeCapsule_ReplaceTeruSama`
+(`engine/link/link.asm:1078`) maps the handful of catch rates that collide with
+real items through `data/items/catch_rate_items.asm` and turns everything else
+into a Berry. `ValidateOTTrademon` (`engine/link/time_capsule.asm:1`) then
+re-checks the incoming mon's types against the local base data and refuses
+anything that does not agree, with Magnemite and Magneton carved out again.
+
+The lesson the port should take from all of that: a cross-generation link is not
+a compatibility mode, it is a lossy conversion with a validator on each end, and
+the cart wrote roughly 400 lines for it. Refusing the pairing is the honest
+default until somebody wants to write those 400 lines.
+
+## 3. Where the Gen 1 protocol breaks on a Gen 2 record
+
+`Protocol.packMon` / `Protocol.unpackMon` are shaped around
+`src/pokemon/Pokemon.lua`. Against `src/battle/gen2/Mon.lua`, every one of these
+is wrong:
+
+| Gen 1 assumption | Gen 2 reality | Where |
+| --- | --- | --- |
+| `mon.exp` | `mon.experience` | `Mon.new`, `Mon.gainExperience` |
+| five DVs including `special` | four rolled DVs (`attack`/`defense`/`speed`/`special`) with `hp` **derived** from their low bits | `Mon.hpDV` |
+| `special` is one stat | `specialAttack` and `specialDefense` are two stats off one DV | `Mon.stats` |
+| `statExp` has five words | five words still, but the fifth feeds both special stats | `Mon.stats` |
+| no held item | `mon.item` decides damage, healing and flinching | `src/battle/gen2/Battle.lua` `heldEffect` |
+| stats recomputed with `src/pokemon/Stats.lua` | must go through `Mon.stats`, which is a different formula shape | `Mon.stats` |
+| exp curve via `src/pokemon/Growth.lua` (code) | curve coefficients are **data**, at `data.pokemon.growthRates` | `Mon.experienceForLevel` |
+| `mon.status` is `"SLP"` / `"PSN"` / `"BRN"` / `"PAR"` / `"FRZ"` | `"sleep"` / `"poison"` / `"burn"` / `"paralyze"` / `"freeze"` / `"toxic"` | `src/battle/Status.lua:62` vs `src/battle/gen2/Battle.lua:65` |
+| `mv.ppUps` | Gen 2 has no PP Ups modelled yet; moves carry `id`, `pp`, `maxPp` | `Mon.movesAtLevel` |
+| nothing else on the mon | `happiness`, `pokerus`, `caughtLevel`, `isEgg`/`eggSteps`, and the derived `shiny` / `gender` / `unownLetter` | `Mon.new` |
+| mail does not exist | mail is a **separate** block keyed by party slot, not a mon field | `src/core/gen2/Mail.lua:84`, and the cart agrees (`Link_PrepPartyData_Gen2`) |
+
+The status spelling is the sharpest of these. `packMon` puts `mon.status` on the
+wire verbatim and `unpackMon` keeps it verbatim, so a shared codec would move
+`"PSN"` onto a Gold party where nothing recognises it -- a mon that arrives
+"poisoned" and never takes poison damage. Any Gen 2 codec has to be a separate
+function with the generation baked into it, not a Gen 1 function with extra
+optional keys.
+
+Two things are *not* a problem, and it is worth saying so:
+
+- **Species and move ids are shared name spaces.** Both generations key
+  `data.pokemon` and `data.moves` by the same `TOTODILE` / `TACKLE` strings, so
+  the wire never needs the cart's index remap (`ConvertMon_2to1`). Ids, not
+  bytes, is what makes the port's protocol simpler than the cable's.
+- **The derived fields do not travel.** `shiny`, `gender` and `unownLetter` are
+  all functions of the DVs (`Mon.isShiny`, `Mon.gender`, `Unown.letterFromDVs`),
+  so the receiver recomputes them and a tampered packet cannot claim a shiny it
+  did not roll. Same reasoning as `unpackMon` recomputing stats.
+
+`LinkBattle.lua` breaks in a larger way. It calls
+`BattleState.makeBattler`, `src/battle/TurnOrder.lua` and Gen 1's damage
+pipeline directly. Gold's battle is `src/battle/gen2/Battle.lua`, a different
+object with a different event shape. The one piece of good news is that
+`Battle.new` already takes `opts.random` (`src/battle/gen2/Battle.lua:220`) --
+the injection seam a lockstep battle needs is there and does not have to be cut.
+
+## 4. The wire format for Gen 2
+
+Message types stay the ones `Protocol.lua` already documents (`hello`,
+`records`, `party`, `pick`, `confirm`, `action`, `event`, `bye`). Gen 2 adds
+fields, never renames -- the same rule the mod seams follow.
+
+**`hello`** gains one field, `generation` (1 or 2). A peer that omits it is
+generation 1 by construction: no released build has ever had Gen 2 link, so
+absent means Red/Blue/Yellow. This is implemented.
+
+**`party`** carries a list of packed mons whose shape is the Gen 2 one:
+
+```
+{ species, level, experience, hp, status, nickname,
+  dvs = { attack, defense, speed, special },   -- hp derived
+  statExp = { hp, attack, defense, speed, special },
+  moves = { { id, pp } ... },
+  item, happiness, pokerus, caughtLevel,
+  ot, otId, isEgg, eggSteps, extra }
+```
+
+and, in a trade, a parallel `mail` array indexed by the same wire position --
+separate exactly as `Link_PrepPartyData_Gen2` keeps it separate, because mail is
+SRAM the cart copies out of `sPartyMail`, not part of the party struct. The
+codec for the mon half is implemented; the mail half is not.
+
+**`records`** gains a third map, `heldItems`, beside `pokemon` and `moves`, so a
+subset trade can refuse a mon whose held item the other game would rebuild
+differently. Implemented.
+
+**`action` / `event`** for a lockstep Gen 2 battle are not designed here, because
+the design is downstream of a decision nobody has made yet: whether
+`src/battle/gen2/Battle.lua` grows a "replay these two actions" entry point or
+whether the link battle drives it through the same UI path a local battle uses.
+Guessing at a message shape before that is exactly the half-built protocol this
+document is meant to avoid.
+
+## 5. The fingerprint on Gold
+
+The fingerprint is the one part of the design that is fully answerable today,
+because it depends only on what a Gold mod can reach, and `src/mods/Schemas.lua`
+answers that exhaustively.
+
+The Gen 1 surface is species, moves, the type chart, statuses, move effects,
+constants and mod-declared link fields. The Gen 2 surface is the same idea over
+different tables, plus one registry Gen 1 does not have:
+
+| What | Gen 1 | Gen 2 | Why it is surface |
+| --- | --- | --- | --- |
+| species | `data.pokemon` | `data.pokemon` (Gen 2 shape) | base stats decide every damage roll; `evolutions` decides what a traded mon becomes |
+| exp curves | code (`src/pokemon/Growth.lua`) | `data.pokemon.growthRates` | the level a traded mon's experience buys |
+| moves | `data.moves` | `data.moves`, **plus `effectChance`** | Gen 2 stores the secondary-effect odds per move rather than per effect |
+| type chart | `data.type_chart` | same, **plus `foresightMatchups`** | Foresight rewrites Ghost's immunities mid-battle |
+| statuses | `data.statuses` | `data.gen2Statuses` | `statPenalty`, `cureOnSwitch`, `beforeMovePriority` |
+| move effects | `data.move_effects` | `data.gen2MoveEffects` | which effect is primary, secondary, or accuracy-checked |
+| held items | -- | `data.gen2HeldItems` | Leftovers, King's Rock, the type boosters: pure battle math, and the item travels with a traded mon |
+| link fields | `data.link_fields` | none (gated) | a mod-declared extra mon field; see below |
+
+Deliberately **not** hashed on either generation, and the reasoning is the same
+in both:
+
+- Names, dex entries, learnsets, TM/HM lists, sprite paths and `source`. None of
+  them changes a battle turn or a trade rebuild, and sprite paths differ between
+  two identical installs.
+- `catchRate` (#511). A ball thrown in a link battle is refused; hashing it split
+  Red/Blue from Yellow over two bytes.
+- Balls and item effects. Link battles allow no bag items on either cart.
+- `data.gen2Constants`. It is the ROM's ordered name lists -- `mapOrder`,
+  `spriteOrder`, `speciesOrder`, `heldEffectOrder` -- and it is an *index* space.
+  Every dispatch in the Gen 2 simulation goes by name (`Battle.heldEffect`
+  compares `record.heldEffect` strings, `moveEffectRecordFor` keys by
+  `EFFECT_*`), so reordering a constants list moves no battle math. Hashing it
+  would split two peers over a list neither of them dispatches on.
+- Breeding data (`eggGroups`, `eggMoves`, `eggSteps`). The Day-Care is local.
+  There is no link breeding and an egg's contents are decided before it is
+  traded.
+- Everything in the Gen 2-only registries that is not `held_items`:
+  `phone_contacts`, `decorations`, `apricorns`, `landmarks`, `radio_channels`.
+  None of them can be observed from inside a link session.
+
+`genderRatio` **is** hashed, unlike anything in the breeding block, because Gen 2
+has Attract and a gender disagreement is a battle-math disagreement.
+
+`link_fields` stays gated on Gen 2 (`Schemas.GEN2`). It is a mod's declaration
+that an extra mon field must survive the wire, and it can only be un-gated once
+there is a Gen 2 mon wire format with a session behind it. A registry that hashes
+into the fingerprint but that no packer reads would be a lie the fingerprint
+tells.
+
+The hook keeps its Gen 1 name and its Gen 1 arity. `link.fingerprint` is called
+as `(data, mods)` on both generations, and the generation is captured in the
+vanilla closure rather than passed as a third argument -- a Gen 1 mod that wraps
+the hook and forwards `nxt(data, mods)` therefore works verbatim on Gold, which
+a third argument would have quietly broken.
+
+## 6. Cross-generation pairing
+
+`Handshake.checkCompat` refuses a pairing whose two `generation` fields differ,
+with reason `generation_mismatch`, before any other check. This is deliberately
+a refusal and not a Time Capsule: section 2 costs roughly 400 lines of lossy
+conversion plus two validators, and shipping a menu that pairs a Gold game with a
+Red one and then rebuilds a Cyndaquil as whatever species index 155 happens to
+be in Red would be worse than refusing.
+
+If somebody does want the Time Capsule later, the cart's own rules are the spec,
+and the port has an advantage the cart did not: ids rather than indices, so
+`ConvertMon_2to1`'s remap table is unnecessary. What remains is real work:
+refuse species above the Kanto 151, refuse moves Gen 1 lacks, refuse held items
+and mail, fold `specialAttack`/`specialDefense` back into one Special
+(`KantoMonSpecials`, `data/pokemon/gen1_base_special.asm`), and re-validate types
+on arrival with Magnemite and Magneton carved out.
+
+## 7. What is built, and what is left
+
+**Built (this change).**
+
+- `Fingerprint.generationOf(data)`: reads `data.type_chart.generation`, then the
+  presence of the Gen 2-only Data namespaces, so the digest never has to be told
+  which game it is running in.
+- A Gen 2 link surface in `Fingerprint.lua`, tagged `[gen2]` so a Gen 2 digest
+  can never collide with a Gen 1 one, covering the table in section 5.
+- `Fingerprint.records(data, kind, generation)` for `pokemon`, `moves` and
+  `held_items` on Gold, which is what a subset trade negotiates on.
+- `Handshake.hello` carries `generation`; `checkCompat` refuses a cross-generation
+  pairing; `describe` explains it in the screen's own voice.
+- `held_items` counts as link surface for `Handshake.linkModified`, so a Gold mod
+  that gives Leftovers a different heal is correctly locked out of online play.
+  `growth_rates` counts too, and for a reason worth stating: a curve is an
+  `expForLevel` function, so the fingerprint serializes it as `?` and cannot
+  hash it at all. `Mon.growthFor` prefers the merged registry over the
+  extractor's coefficient rows, so a mod declaring `affects_link = false` could
+  otherwise rewrite every curve -- changing what level a traded mon's experience
+  buys -- and be caught by neither the digest nor the online gate.
+- `Protocol.packMon2` / `unpackMon2`: the Gen 2 party-struct codec, with the
+  receiver recomputing stats, experience, shininess and gender from real species
+  data the way `unpackMon` does. Nothing sends it yet.
+- `Protocol.recordsMessage` and `eligibleParty` understand held items, and
+  `TradeSession:_negotiate` builds our own side of the comparison by calling
+  `recordsMessage` rather than open-coding a subset of it. That is not a
+  refactor: the open-coded version left `heldItems` off our side only, and both
+  held-item arms of `eligibleParty` are guarded on our own map, so the whole
+  check was unreachable from the only caller that matters.
+
+**Not built.** Sized as honestly as I can:
+
+| Piece | Size | Why it is not here |
+| --- | --- | --- |
+| Mail on the wire | small (1-2 days) | needs `Mail.state(save).party` packed as a parallel array and the receiver writing it into its own slot; no consumer until the trade session exists |
+| Gen 2 trade session | medium (about a week) | `TradeSession` is generic in shape but `apply` calls `src/world/PikachuFollower`, Gen 1 pokedex fields and Gen 1 trade evolutions; Gold needs `src/core/gen2/TradeAnim.lua`, `src/core/gen2/Evolution.lua` (`EVOLVE_TRADE`) and the Gen 2 pokedex |
+| Gold LINK menu and trade UI | medium (about a week) | Gold's menus are `src/ui/gen2/`, its text box is Gen 2 chrome, and the Cable Club script needs the receptionist path; `LinkState.lua` draws with Gen 1 `TextBox` throughout |
+| Gen 2 lockstep battle | large (several weeks) | needs a deterministic-replay entry point into `src/battle/gen2/Battle.lua`, a Gen 2 action/event encoding, and a state hash over a much larger volatile-status set than Gen 1's; the `opts.random` seam exists, nothing else does |
+| Time Capsule | large | section 6 |
+| `link_fields` on Gen 2 | small, but blocked | needs the trade session first |
+
+The order matters: mail, session and UI are the trade half and can ship without
+the battle half, exactly as the cart's Trade Center and Colosseum are separate
+rooms. A Gold LINK menu that offers only TRADE is a complete feature. A Gold
+LINK menu that offers BATTLE before the lockstep battle exists is the failure
+this document was written to prevent.
@@ -0,0 +1,188 @@
+# Pokemon Gold: Gen 2 import, colour, menus, saving and battles
+
+Support for a canonical **Pokemon Gold** ROM
+(SHA-1 `d8b8a3600a465308c9953dfa04f0081c05bdcb94`, 2 MiB). Gen 2 extraction
+and overworld are separate from Red/Blue/Yellow -- never branched into
+`RomExtractor.lua` / Gen 1 `Map.lua`.
+
+## Pipeline
+
+| Piece | Role |
+| --- | --- |
+| `src/import/Rom.lua` (`decompressLz3`) | Gen 2 graphics compression (`home/decompress.asm`) |
+| `tools/make_gold_manifest.py` → `tools/rom_manifest_gold.json` | pret/pokegold constants + `pokegold.sym` |
+| `src/import/RomExtractorGen2.lua` | Gen 2 extract (dispatched from `RomImporter` when `version == "gold"`) |
+| `src/core/GameVersion.lua` | `gold` entry (`gold/` cache, `_gold` saves) |
+| `src/world/gen2/` | COLL_* world, NPCs, events, roofs |
+| `src/script/gen2/` | Opcodes + talk-oriented VM over extracted cmds |
+| `src/core/Game2.lua` | Gold's service owner (the Gen 2 peer of `src/core/Game.lua`): boot cinema, intro menu, world, START menu |
+| `src/core/gen2/Save.lua` | `save_gold.lua`, beside the Gen 1 saves |
+| `src/ui/gen2/` | Intro menu, naming keyboard, START menu + every submenu, battle screen |
+| `src/battle/gen2/` | Damage, stats/experience, HP bar, turn engine, catching, encounters |
+| `src/render/GbcPalette.lua` | One shader: a 4-shade sheet through a GBC palette |
+
+## What extracts
+
+| Area | Status |
+| --- | --- |
+| Constants | species/map/tileset/move/type/sprite/environment/palette/fish orders |
+| Font | `Font` (1bpp ink-on-transparent), `FontExtra` + `Frames` borders at $79–$7E, `FontBattleExtra` |
+| Tilesets | lz3 GFX → PNG; raw Meta (128×16) + Coll (128×4 COLL_* quads); Anim/PalMap pointers |
+| Roofs | 5 roof sheets + `MapGroupRoofs` (runtime: outdoor tilesets only) |
+| Maps | all 368: blocks, connections, warps, coord/bg/object events (+ `scriptKey`) |
+| Pokemon | `BaseData` (32B), names, front/back pics, plus Unown's 26 letter forms from `UnownPicPointers` |
+| Items | Names, prices, pockets, held effects, field/battle use, descriptions, TM/HM numbers and the move each teaches |
+| Marts | `Marts`' 34 shelves in MART_* order plus `BargainShopData`'s own item/price rows (`marts.lua`) |
+| Overworld sprites | `OverworldSprites` → PNG sheets + `sprites.lua` |
+| Scripts / text | disassembled cmds + decoded strings (`scripts.lua` / `text.lua`) |
+| Initial events | `InitializeEventsScript` → `initial_events.lua` |
+| Title | Tilemap + GBC tint; cloud band; Ho-Oh frames 1–5; trail; copyright splash |
+| Oak speech | `_OakText1–7`, `PokemonProfPic` / `CalPic`, Marill front; `oak_speech.lua` |
+| Pokemon / trainer pics | lz3 + column-major → row (`ImageWriter.columnsToRows`) |
+| Audio | banks dumped to `programs.bin`; Gen 2 ChipSynth driver (`runtime = true`) |
+| Palettes | `TilesetBGPalette`, `EnvironmentColorsPointers`, `MapObjectPals`, `RoofPals`, mon/trainer/HP-bar/exp-bar palettes, per-tileset `PalMap` |
+| Moves | `Moves` + names + descriptions, effect names, real percentages |
+| Type chart | `TypeMatchups` (plus the Foresight rows) and `TypeNames` with physical/special |
+| Pokemon | Base stats, evolutions and level-up moves (`EvosAttacks`), TM/HM lists, growth rates, egg groups, gender ratio |
+| Encounters | Grass (three time-of-day slot lists), water, fishing groups, headbutt tree sets |
+| Trainers | Every class's parties with moves/items, class names, attributes, `TrainerEncounterMusic` |
+| Pokedex | Entries (kind, height, weight, text) + the New and A-Z orderings |
+| Landmarks | Town-map positions and names, plus `SpawnPoints` |
+| Icons | Party-menu mon icons and the species → icon map |
+| Menu / HUD gfx | Naming-screen chrome, battle HUD border and bar tiles, exp bar |
+| Intro movie | The three acts' composed backgrounds, sprite sheets and fire frames |
+| Battle anims | all 428 scripts, 188 objects, 185 framesets, 216 OAM sets, 40 object sheets, the six OBJ palettes |
+| Field anims | stubs |
+
+Verified against a real Gold ROM: New Bark Town warps/objects/connections
+match `pokegold/maps/NewBarkTown.asm`. Retail EVENT_* numeric ids differ
+from pret’s current `const_def` order -- always take flags from the cart.
+
+## Play
+
+Launcher → Gold tab → Play opens `Game2` (`src/core/Game2.lua`):
+
+- Copyright → GameFreak Presents → GS intro stub → title (colored tilemap,
+  scrolling clouds, Ho-Oh flap, trails) → Oak speech (Marill cry + shrink)
+  → name pick → `src/world/gen2/World`
+- Drivers (`POKEPORT_DRIVER`) skip cinema straight to the map
+- New Bark Town with Johto tileset + roof overlay (outdoors only)
+- Walk on `COLL_*` permissions; doors / stairs / carpets
+- Elm's lab: scene walk-in, starter balls (`givepoke` + cutscene moves),
+  Elm phone number, aide Potion on exit (`verbosegiveitem`)
+- Connected neighbor strips + seamless edge crossings (Route 29 / 27)
+- Survey zoom (`-` / `=` / wheel / `4`)
+- Chris + map/neighbor NPCs; `SPRITEMOVEDATA_*` walk / spin / stand
+- New-game flags hide story NPCs (e.g. lab cop)
+- A: talk to facing NPC or read `BGEVENT_READ` signs via Gen 2 VM + TextBox
+
+Escape is START, not quit: quitting is the START menu's QUIT row and the
+intro menu's EXIT GAME.  Title / map music and script SFX/cries use the Gen 2
+channel driver.
+
+## Colour
+
+Gen 2 is CGB-native, so colour is part of a tile's identity rather than a tint
+over a 4-shade image.  `engine/gfx/color.asm` LoadMapPals is ported whole in
+`src/world/gen2/Palettes.lua`:
+
+1. the clock hour picks a daytime (`engine/rtc/rtc.asm` TimesOfDay), which a
+   map's own `PALETTE_*` can override (`ReplaceTimeOfDayPals`)
+2. `EnvironmentColorsPointers[environment][daytime]` names eight entries in the
+   shared `TilesetBGPalette` pool
+3. outdoors only, `RoofPals[mapGroup]` overwrites `PAL_BG_ROOF` colours 1-2 --
+   one roof tile sheet, a different colour per town
+4. each tile's slot comes from its tileset's `PalMap`, and each OW sprite's OBJ
+   palette from `MapObjectPals[daytime]` plus its own `PAL_OW_*`
+
+The map bake runs one shader pass per BG slot (eight per map) rather than one
+per tile, and re-bakes when the clock rolls into a new daytime.
+`POKEPORT_GOLD_HOUR=21` pins the hour for screenshots.
+
+## Still to do
+
+About fifty of AI_Smart's seventy per-effect handlers are unwritten, fishing
+and headbutt have engine support but no input path, and Mart, the summary
+screen, `.sav` interchange, Silver and mod-replaceable Gen 2 screens are all
+still open.
+
+## Verify
+
+```sh
+python3 tools/make_gold_manifest.py
+for t in rom_lz3 gen2_world gen2_audio gen2_oak_speech gen2_vm \
+         gen2_palettes gen2_battle gen2_menus gen2_save; do
+  luajit tests/${t}_test.lua
+done
+POKEPORT_IMPORT_TRACE=1 POKEPORT_IMPORT_ROM=/path/to/pokegold.gbc \
+  POKEPORT_IMPORT_ONLY=1 POKEPORT_FORCE_IMPORT=1 POKEPORT_GAME=gold love .
+POKEPORT_GAME=gold love .
+# copyright → GF presents → GS intro → title → CONTINUE/NEW GAME/OPTION
+# → Oak → name → the bedroom.  START opens the menu; grass starts a battle.
+
+# Screenshot drivers (need a display):
+POKEPORT_GAME=gold POKEPORT_DRIVER=tests/drivers/gold_menu_shots.lua love .
+POKEPORT_GAME=gold POKEPORT_DRIVER=tests/drivers/gold_palette_shots.lua love .
+POKEPORT_GAME=gold POKEPORT_DRIVER=tests/drivers/gold_battle_smoke.lua love .
+POKEPORT_GAME=gold POKEPORT_DRIVER=tests/drivers/gold_transition_shots.lua love .
+POKEPORT_GAME=gold POKEPORT_DRIVER=tests/drivers/gold_teacher_scene.lua love .
+POKEPORT_GAME=gold POKEPORT_BOOT_CINEMA=1 \
+  POKEPORT_DRIVER=tests/drivers/gold_boot_smoke.lua love .
+```
+
+`POKEPORT_IMPORT_TRACE=1` prints each of the 26 stages as it starts, and a
+headless import that fails now says so and exits non-zero rather than sitting
+in an error state that looks exactly like a hang.
+
+A Gold cache without `palettes.lua`, `moves.lua`, `encounters.lua`,
+`trainers.lua`, `pokedex.lua`, `landmarks.lua`, `icons.lua`, `menu_gfx.lua`,
+`intro.lua`, `std_scripts.lua` or `battle/hud/*.png` needs a re-import -- as
+does one whose back pics are still the front pic's size rather than 48x48 (see
+below), and one whose trainer classes have no `encounterMusic` (the sixth
+pass added `TrainerEncounterMusic` to the manifest, so the manifest has to be
+regenerated as well).  So does one whose `text.lua` has no `labels` table: that
+is the by-name seed for the text no script pointer reaches (the Day-Care and
+breeding block, the mart conversation, the Hall of Fame headers), and it needs
+a regenerated manifest too, because the seed reads those symbols by name.
+
+## Traps this port has already fallen into
+
+Worth knowing before touching the extractor:
+
+- **Back pics are always 6x6 (48x48).**  `BASE_PIC_SIZE`'s low nibble describes
+  the *front* pic only, so decoding a back at it reads the wrong tile count in
+  the wrong number of columns and produces garbage.
+- **`#`, `<POKE>` and `<PKMN>` have no font tile.**  They are compression bytes
+  ($54/$24/$4a) that PlaceString expands; the manifest charmap has to expand
+  them or "#DEX" renders as "DEX".
+- **FishGroups has no row for FISHGROUP_NONE**, so a group's row is its id minus
+  one.  Walking the constant list from the top reads every row shifted.
+- **Trainer groups have no end marker** -- the next group's label follows
+  immediately -- so a party scan needs the class's own member list to bound it.
+- **Pokedex entries are spread over four banks** and the cart derives the bank
+  arithmetically; take each species' own symbol instead.
+- **`EvosAttacksPointers` is `dw`, not `dba`**: the blobs share the table's bank.
+- Item ids past NUM_ITEMS (the TMs and HMs) have no ItemNames row; their name is
+  their TM number.
+- **`TrainerClassAttributes` rows are SEVEN bytes**, not eight:
+  `NUM_TRAINER_ATTRIBUTES` is `_RS` after three `rb` and two `rw`.  An
+  eight-byte stride walks one byte further off with every class, so the AI
+  flags come out as noise for everything past the first trainer -- and it
+  produces plausible values rather than an error, which is how it survived two
+  passes.  The row is {item1, item2, baseMoney, aiLo, aiHi, switchLo,
+  switchHi}: the base money is byte THREE.
+- **`dba_pic` does not store the real bank.**  For the three "Pics" sections
+  that sit above the 8-bit-friendly range it writes `$13`, `$14` or `$1f`, and
+  `FixPicBank` (engine/gfx/load_pics.asm) maps those back to `$1f`, `$20` and
+  `$2e`.  Any table of pic pointers -- `PokemonPicPointers`,
+  `UnownPicPointers`, `TrainerPicPointers` -- needs that mapping, or the read
+  lands in a completely different bank.
+- **A pic can run over the top of its bank.**  `GetLZByte` bumps the bank and
+  drops back to `$4000` when the read pointer passes `$8000`, so a compressed
+  pic near the top of a bank keeps going into the next one; slicing only to
+  `$8000` stops short of nine of the Unown letters.
+- **`BattleAnimObjects` rows are SIX bytes**, because `BATTLEANIMOBJ_LENGTH` is
+  `_RS - 1` -- the struct's runtime INDEX byte is not in the table.
+- **Unown has no `PokemonPicPointers` row of its own**; its twenty-six forms
+  come out of `UnownPicPointers` instead, and letter A stands in for the
+  species.
@@ -0,0 +1,126 @@
+# ASM Walk output format
+
+Every `section-NN-*.md` in this folder follows the structure below. The goal is a
+single place a bot author can look at to answer "for this stretch of the
+walkthrough, which maps, warps, objects, scripts, flags, items and trainers are
+involved, and where in the pokegold disassembly do they live?"
+
+Conventions:
+
+- Disassembly paths are written relative to the pokegold checkout root, e.g.
+  `maps/NewBarkTown.asm`, `data/maps/maps.asm`, `constants/event_flags.asm`.
+- Port paths are written relative to this repo root, e.g. `src/world/gen2/Map.lua`.
+- Coordinates are the raw asm values (map-block coordinates as written in the
+  `warp_event` / `object_event` / `bg_event` rows), not screen pixels.
+- Anything not verified by opening the file is omitted rather than guessed. If a
+  walkthrough claim could not be located in the asm, it goes under
+  "Unresolved / verify by hand".
+
+---
+
+# Section NN - <title>
+
+Source: `../section-NN-<slug>.txt`
+Maps covered: `MAP_A`, `MAP_B`, ...
+Badges / key milestones in this section: ...
+
+## 1. Route order
+
+Ordered list of map transitions the walkthrough takes, one row per hop.
+
+| # | Map constant | asm file | Enter via | Leaves via | Why (walkthrough beat) |
+|---|---|---|---|---|---|
+
+## 2. Maps
+
+Repeat this block per map.
+
+### MAP_<NAME>
+
+- Script: `maps/<Name>.asm`
+- Blocks: `maps/<Name>.blk` (if present)
+- Header: `data/maps/maps.asm` -> tileset, environment, location, music, phone, palette
+- Dimensions / attributes: `constants/map_constants.asm` (`map_const <NAME>, W, H`)
+- Connections: north/south/east/west map constants
+
+**Warps** (`def_warp_events`)
+
+| idx | x | y | destination map | dest warp |
+|---|---|---|---|---|
+
+**Coord events** (`def_coord_events`) - the scripted trip-wires a bot will hit
+
+| scene | x | y | script label | effect |
+|---|---|---|---|---|
+
+**BG events** (`def_bg_events`) - signs, hidden items
+
+| x | y | type | script/item |
+|---|---|---|---|
+
+**Object events** (`def_object_events`) - NPCs, item balls, trainers
+
+| const | sprite | x | y | movement | type | script label | event flag |
+|---|---|---|---|---|---|---|---|
+
+**Scripts of interest**
+
+For each script label the walkthrough actually depends on: label, a short prose
+summary of what the opcodes do, and the flags/items/battles it touches. Cite the
+label name so it can be grepped.
+
+**Flags and events**
+
+| constant | defined in | read/written by | meaning for a bot |
+|---|---|---|---|
+
+Include `EVENT_*` (`constants/event_flags.asm`), `ENGINE_*`
+(`constants/engine_flags.asm`), and any `SCENE_*` values
+(`constants/map_setup_constants.asm` / the map's own `object_const_def` block).
+
+**Items**
+
+| item | how obtained | source (label / bg_event / hidden) | one-time flag |
+|---|---|---|---|
+
+**Trainers**
+
+| const | class | id | party (`data/trainers/parties.asm` label) | script label | rematch/phone |
+|---|---|---|---|---|---|
+
+**Wild encounters**
+
+Table entry in `data/wild/johto_grass.asm` / `johto_water.asm` /
+`kanto_grass.asm` / `kanto_water.asm`, plus fishing (`data/wild/fish.asm`),
+headbutt (`data/wild/treemons.asm`) and rock smash where relevant. Note the
+morn/day/nite split.
+
+## 3. Blockers and gates
+
+What actually stops forward progress in this section, and the precise check.
+
+| Gate | Enforced by (file:label) | Requirement | Unlock condition |
+|---|---|---|---|
+
+Cover badge checks, HM field-move checks (`engine/overworld/`), key items,
+`EVENT_*` guards, and NPC-blocked tiles.
+
+## 4. Bot checklist
+
+The machine-actionable version: an ordered list of steps a scripted playthrough
+would execute. Each step names the map, the target coordinates or object const,
+the input intent (talk / walk / use item / battle), the precondition flag and the
+postcondition flag. Keep it literal enough that someone can turn a row into a
+driver command without reopening the asm.
+
+## 5. Port coverage
+
+Where this section's mechanics land in this repo, and what is missing.
+
+| Beat | Port file | Status |
+|---|---|---|
+
+## 6. Unresolved / verify by hand
+
+Anything the walkthrough asserts that could not be pinned to a specific asm
+location, plus any contradictions found between the two.
@@ -0,0 +1,535 @@
+# Section 00 - Chikorita, Cyndaquil, or Totodile?
+
+Source: `../section-00-chikorita-cyndaquil-or-totodile.txt`
+Maps covered: `MAP_PLAYERS_HOUSE_2F`, `MAP_PLAYERS_HOUSE_1F`, `MAP_NEW_BARK_TOWN`, `MAP_ELMS_LAB`
+Badges / key milestones in this section: no badge. Milestones are the new-game
+clock set, the #GEAR from Mom (`ENGINE_POKEGEAR`), the first rival encounter,
+and the starter (`EVENT_GOT_A_POKEMON_FROM_ELM`), which is what un-gates the
+walk west out of New Bark Town.
+
+Coordinate note: every `warp_event` / `coord_event` / `bg_event` /
+`object_event` x,y below is copied verbatim from the map asm. Those are 0-based
+walk-grid cells (2 per map block, so a `W`-block-wide map runs x = 0..2W-1),
+which is the same grid `src/world/gen2/Map.lua` calls a cell.
+
+## 1. Route order
+
+| # | Map constant | asm file | Enter via | Leaves via | Why (walkthrough beat) |
+|---|---|---|---|---|---|
+| 0 | (no map) | `engine/menus/intro_menu.asm` `NewGame` / `OakSpeech`, `engine/rtc/timeset.asm` `InitClock` | title screen -> NEW GAME | `InitializeWorld` -> `SPAWN_HOME` | "Choose new game and start… Professor Oak will ask you the time… he asks you what your name is" |
+| 1 | `MAP_PLAYERS_HOUSE_2F` | `maps/PlayersHouse2F.asm` | spawn `SPAWN_HOME` at (3,3), `data/maps/spawn_points.asm` | warp 1 at (7,0) | "You are in your room at the beginning. Exit the room" |
+| 2 | `MAP_PLAYERS_HOUSE_1F` | `maps/PlayersHouse1F.asm` | warp 3 at (9,0) | warp 1 (6,7) or warp 2 (7,7) | "you will meet your mom… You get the Pokegear… input the day of the week" |
+| 3 | `MAP_NEW_BARK_TOWN` | `maps/NewBarkTown.asm` | warp 2 at (13,5) | warp 1 at (6,3) | "Leave your house and head left to Professor Elm's lab. Notice the guy standing left of it" (rival at (3,2)) |
+| 4 | `MAP_ELMS_LAB` | `maps/ElmsLab.asm` | warp 1 (4,11) / warp 2 (5,11) | warp 1/2 back to New Bark Town | "go into Elm's lab… You get to pick your starter Pokémon" |
+| 5 | `MAP_NEW_BARK_TOWN` | `maps/NewBarkTown.asm` | warp 1 at (6,3) | west connection to `ROUTE_29` (`data/maps/attributes.asm`) | section ends here; the walk west to Route 29 / Cherrygrove belongs to section 01 |
+
+## 2. Maps
+
+### MAP_PLAYERS_HOUSE_2F
+
+- Script: `maps/PlayersHouse2F.asm`
+- Blocks: `maps/PlayersHouse2F.blk`
+- Header (`data/maps/maps.asm:478`): `map PlayersHouse2F, TILESET_PLAYERS_ROOM, INDOOR, LANDMARK_NEW_BARK_TOWN, MUSIC_NEW_BARK_TOWN, FALSE, PALETTE_DAY, FISHGROUP_SHORE`
+- Dimensions (`constants/map_constants.asm:443`): `map_const PLAYERS_HOUSE_2F, 4, 3` (4x3 blocks = 8x6 cells)
+- Connections: none (indoor)
+- Scene var: `wPlayersHouse2FSceneID` is *not* in `data/maps/scenes.asm`; the map has an empty `def_scene_scripts`
+
+**Warps** (`def_warp_events`)
+
+| idx | x | y | destination map | dest warp |
+|---|---|---|---|---|
+| 1 | 7 | 0 | `PLAYERS_HOUSE_1F` | 3 |
+
+**Coord events** (`def_coord_events`)
+
+None (the block is empty).
+
+**BG events** (`def_bg_events`)
+
+| x | y | type | script/item |
+|---|---|---|---|
+| 2 | 1 | `BGEVENT_UP` | `PlayersHousePCScript` |
+| 3 | 1 | `BGEVENT_READ` | `PlayersHouseRadioScript` |
+| 5 | 1 | `BGEVENT_READ` | `PlayersHouseBookshelfScript` |
+| 6 | 0 | `BGEVENT_IFSET` | `PlayersHousePosterScript` (guarded by `EVENT_PLAYERS_ROOM_POSTER`) |
+
+**Object events** (`def_object_events`)
+
+| const | sprite | x | y | movement | type | script label | event flag |
+|---|---|---|---|---|---|---|---|
+| `PLAYERSHOUSE2F_CONSOLE` | `SPRITE_CONSOLE` | 4 | 2 | `SPRITEMOVEDATA_STILL` | `OBJECTTYPE_SCRIPT` | `PlayersHouseGameConsoleScript` | `EVENT_PLAYERS_HOUSE_2F_CONSOLE` |
+| `PLAYERSHOUSE2F_DOLL_1` | `SPRITE_DOLL_1` | 4 | 4 | `SPRITEMOVEDATA_STILL` | `OBJECTTYPE_SCRIPT` | `PlayersHouseDoll1Script` | `EVENT_PLAYERS_HOUSE_2F_DOLL_1` |
+| `PLAYERSHOUSE2F_DOLL_2` | `SPRITE_DOLL_2` | 5 | 4 | `SPRITEMOVEDATA_STILL` | `OBJECTTYPE_SCRIPT` | `PlayersHouseDoll2Script` | `EVENT_PLAYERS_HOUSE_2F_DOLL_2` |
+| `PLAYERSHOUSE2F_BIG_DOLL` | `SPRITE_BIG_DOLL` | 0 | 1 | `SPRITEMOVEDATA_BIGDOLL` | `OBJECTTYPE_SCRIPT` | `PlayersHouseBigDollScript` | `EVENT_PLAYERS_HOUSE_2F_BIG_DOLL` |
+
+**Scripts of interest**
+
+- `PlayersHouse2FInitializeRoomCallback` (`callback MAPCALLBACK_NEWMAP`): runs
+  `special ToggleDecorationsVisibility`, sets
+  `EVENT_TEMPORARY_UNTIL_MAP_RELOAD_8` (read by `engine/phone/scripts/mom.asm`),
+  then `checkevent EVENT_INITIALIZED_EVENTS` -> if clear,
+  `jumpstd InitializeEventsScript`. This is the one-time world seeding for a new
+  game: `engine/events/std_scripts.asm:438` sets ~70 `EVENT_*` bits including
+  `EVENT_COP_IN_ELMS_LAB` (which *hides* the officer), `EVENT_RIVAL_CHERRYGROVE_CITY`,
+  `EVENT_ROUTE_30_YOUNGSTER_JOEY`, and finally `EVENT_INITIALIZED_EVENTS`
+  (`engine/events/std_scripts.asm:557`) so it never runs again.
+- `PlayersHouse2FSetUpTileDecorationsCallback` (`callback MAPCALLBACK_TILES`):
+  `special ToggleMaptileDecorations`.
+- `PlayersHouseRadioScript`: three-branch. Before `EVENT_GOT_A_POKEMON_FROM_ELM`
+  it plays `MUSIC_POKEMON_TALK`, prints four texts and sets
+  `EVENT_LISTENED_TO_INITIAL_RADIO`; after that flag it prints only
+  `PlayersRadioText4`; after `EVENT_GOT_A_POKEMON_FROM_ELM` it becomes the normal
+  `jumpstd Radio1Script`. Purely flavour, no gate.
+- `PlayersHousePCScript`: `special PlayersHousePC`, `iftrue .Warp` -> `warp NONE, 0, 0`
+  (the "leave the PC by warping in place" reload).
+
+**Flags and events**
+
+| constant | defined in | read/written by | meaning for a bot |
+|---|---|---|---|
+| `EVENT_INITIALIZED_EVENTS` | `constants/event_flags.asm:63` | read by `PlayersHouse2FInitializeRoomCallback`, set by `InitializeEventsScript` | first-load-only world seed; must be clear on a fresh save |
+| `EVENT_TEMPORARY_UNTIL_MAP_RELOAD_8` | `constants/event_flags.asm` | set here, read by `engine/phone/scripts/mom.asm:13` | "player is at home right now" |
+| `EVENT_LISTENED_TO_INITIAL_RADIO` | `constants/event_flags.asm:468` | `PlayersHouseRadioScript` | shortens the radio text on repeat |
+| `EVENT_PLAYERS_ROOM_POSTER` | `constants/event_flags.asm:378` | `conditional_event` in `PlayersHousePosterScript` | decoration present |
+
+**Items**: none on this map.
+
+**Trainers**: none.
+
+**Wild encounters**: none (indoor).
+
+### MAP_PLAYERS_HOUSE_1F
+
+- Script: `maps/PlayersHouse1F.asm`
+- Blocks: `maps/PlayersHouse1F.blk`
+- Header (`data/maps/maps.asm:477`): `map PlayersHouse1F, TILESET_PLAYERS_HOUSE, INDOOR, LANDMARK_NEW_BARK_TOWN, MUSIC_NEW_BARK_TOWN, FALSE, PALETTE_DAY, FISHGROUP_SHORE`
+- Dimensions (`constants/map_constants.asm:442`): `map_const PLAYERS_HOUSE_1F, 5, 4` (10x8 cells)
+- Connections: none (indoor)
+- Scene var: `wPlayersHouse1FSceneID` (`data/maps/scenes.asm:30`). Scene ids come
+  from declaration order in `def_scene_scripts` (`macros/scripts/maps.asm:25`):
+  `SCENE_PLAYERSHOUSE1F_MEET_MOM` = 0, `SCENE_PLAYERSHOUSE1F_NOOP` = 1. A new game
+  zeroes the scene, so scene 0 is live on the first visit.
+
+**Warps** (`def_warp_events`)
+
+| idx | x | y | destination map | dest warp |
+|---|---|---|---|---|
+| 1 | 6 | 7 | `NEW_BARK_TOWN` | 2 |
+| 2 | 7 | 7 | `NEW_BARK_TOWN` | 2 |
+| 3 | 9 | 0 | `PLAYERS_HOUSE_2F` | 1 |
+
+**Coord events** (`def_coord_events`)
+
+None. The Mom cutscene is a **scene script**, not a coord event: `scene_script
+PlayersHouse1FMeetMomScene, SCENE_PLAYERSHOUSE1F_MEET_MOM` -> `sdefer MeetMomScript`,
+so it fires on map entry from the stairs while the scene id is still 0.
+
+**BG events** (`def_bg_events`)
+
+| x | y | type | script/item |
+|---|---|---|---|
+| 0 | 1 | `BGEVENT_READ` | `PlayersHouse1FStoveScript` |
+| 1 | 1 | `BGEVENT_READ` | `PlayersHouse1FSinkScript` |
+| 2 | 1 | `BGEVENT_READ` | `PlayersHouse1FFridgeScript` |
+| 4 | 1 | `BGEVENT_READ` | `PlayersHouse1FTVScript` |
+
+**Object events** (`def_object_events`)
+
+| const | sprite | x | y | movement | type | script label | event flag |
+|---|---|---|---|---|---|---|---|
+| `PLAYERSHOUSE1F_MOM1` | `SPRITE_MOM` | 7 | 3 | `SPRITEMOVEDATA_STANDING_LEFT` (time `-1`) | `OBJECTTYPE_SCRIPT` | `MomScript` | `EVENT_PLAYERS_HOUSE_MOM_1` |
+| `PLAYERSHOUSE1F_MOM2` | `SPRITE_MOM` | 2 | 2 | `SPRITEMOVEDATA_STANDING_UP` (time `MORN`) | `OBJECTTYPE_SCRIPT` | `MomScript` | `EVENT_PLAYERS_HOUSE_MOM_2` |
+| `PLAYERSHOUSE1F_MOM3` | `SPRITE_MOM` | 7 | 3 | `SPRITEMOVEDATA_STANDING_LEFT` (time `DAY`) | `OBJECTTYPE_SCRIPT` | `MomScript` | `EVENT_PLAYERS_HOUSE_MOM_2` |
+| `PLAYERSHOUSE1F_MOM4` | `SPRITE_MOM` | 0 | 2 | `SPRITEMOVEDATA_STANDING_UP` (time `NITE`) | `OBJECTTYPE_SCRIPT` | `MomScript` | `EVENT_PLAYERS_HOUSE_MOM_2` |
+
+Note the object flags are inverted relative to intuition: a *set* event flag hides
+the object. Mom1 is the cutscene Mom (visible while `EVENT_PLAYERS_HOUSE_MOM_1`
+is clear); `MeetMomScript` ends by setting `EVENT_PLAYERS_HOUSE_MOM_1` and
+clearing `EVENT_PLAYERS_HOUSE_MOM_2`, which swaps in the three time-of-day Moms
+on the next map load.
+
+**Scripts of interest**
+
+- `MeetMomScript` (the whole Pokegear beat, `maps/PlayersHouse1F.asm:21`):
+  1. `applymovement PLAYER, PlayersHouseDownstairsMovement` (one `step DOWN`, i.e. off the stair tile).
+  2. `playmusic MUSIC_MOM`, `turnobject PLAYERSHOUSE1F_MOM1, UP`, `showemote EMOTE_SHOCK, PLAYERSHOUSE1F_MOM1, 15`.
+  3. `applymovement PLAYERSHOUSE1F_MOM1, MomWalksToPlayerMovement` (`slow_step RIGHT, RIGHT, UP`: (7,3) -> (9,2), beside the player at (9,1)).
+  4. `writetext ElmsLookingForYouText`, `getstring STRING_BUFFER_4, PokegearName` ("#GEAR"), `scall PlayersHouse1FReceiveItemStd` -> `jumpstd ReceiveItemScript` (`engine/events/std_scripts.asm:656`).
+  5. `setflag ENGINE_POKEGEAR`, `setflag ENGINE_PHONE_CARD`, `addcellnum PHONE_MOM`.
+  6. `setscene SCENE_PLAYERSHOUSE1F_NOOP`, `setevent EVENT_PLAYERS_HOUSE_MOM_1`, `clearevent EVENT_PLAYERS_HOUSE_MOM_2`.
+  7. `special SetDayOfWeek`, then the DST loop: `IsItDSTText` -> `yesorno` -> `special InitialSetDSTFlag` / `special InitialClearDSTFlag`, each confirmed by a second `yesorno` that loops back to `.SetDayOfWeek` on "no".
+  8. Phone-instructions branch (`.KnowPhone` / `.ExplainPhone`, both fall into `.FinishPhone`), then `applymovement PLAYERSHOUSE1F_MOM1, MomWalksBackMovement` and `special RestartMapMusic`.
+  Crucially the #GEAR is **not** an inventory item: it is two engine flags. There
+  is no `giveitem` in this script.
+- `MomScript` (talking to Mom afterwards): checks, in order,
+  `EVENT_FIRST_TIME_BANKING_WITH_MOM` -> `EVENT_TALKED_TO_MOM_AFTER_MYSTERY_EGG_QUEST`
+  -> `EVENT_GAVE_MYSTERY_EGG_TO_ELM` -> `EVENT_GOT_A_POKEMON_FROM_ELM`; in this
+  section all four are clear so it prints `HurryUpElmIsWaitingText`. The
+  `special BankOfMom` path is not reachable yet.
+
+**Flags and events**
+
+| constant | defined in | read/written by | meaning for a bot |
+|---|---|---|---|
+| `ENGINE_POKEGEAR` | `constants/engine_flags.asm:8` | set by `MeetMomScript` | Pokegear menu becomes usable |
+| `ENGINE_PHONE_CARD` | `constants/engine_flags.asm:6` | set by `MeetMomScript` | Pokegear PHONE card unlocked |
+| `EVENT_PLAYERS_HOUSE_MOM_1` | `constants/event_flags.asm:1129` | set by `MeetMomScript` | hides the cutscene Mom |
+| `EVENT_PLAYERS_HOUSE_MOM_2` | `constants/event_flags.asm:1130` | cleared by `MeetMomScript` | reveals the time-of-day Moms |
+| `SCENE_PLAYERSHOUSE1F_MEET_MOM` (0) / `SCENE_PLAYERSHOUSE1F_NOOP` (1) | `maps/PlayersHouse1F.asm:9-10` | `setscene` at step 6 | scene 0 must be live exactly once |
+| `PHONE_MOM` | `constants/phone_constants.asm` (via `addcellnum`) | `MeetMomScript` | Mom's number in the Pokegear |
+
+**Items**
+
+| item | how obtained | source (label / bg_event / hidden) | one-time flag |
+|---|---|---|---|
+| POKEGEAR (not an item - `ENGINE_POKEGEAR` + `ENGINE_PHONE_CARD`) | Mom cutscene | `MeetMomScript` | `EVENT_PLAYERS_HOUSE_MOM_1` / `SCENE_PLAYERSHOUSE1F_NOOP` |
+
+**Trainers**: none.
+
+**Wild encounters**: none (indoor).
+
+### MAP_NEW_BARK_TOWN
+
+- Script: `maps/NewBarkTown.asm`
+- Blocks: `maps/NewBarkTown.blk`
+- Header (`data/maps/maps.asm:475`): `map NewBarkTown, TILESET_JOHTO, TOWN, LANDMARK_NEW_BARK_TOWN, MUSIC_NEW_BARK_TOWN, FALSE, PALETTE_AUTO, FISHGROUP_OCEAN`
+- Dimensions (`constants/map_constants.asm:440`): `map_const NEW_BARK_TOWN, 10, 9` (20x18 cells)
+- Connections (`data/maps/attributes.asm:119-121`): `map_attributes NewBarkTown, NEW_BARK_TOWN, $05`, `connection west, Route29, ROUTE_29, 0`, `connection east, Route27, ROUTE_27, 0`
+- Scene var: `wNewBarkTownSceneID` (`data/maps/scenes.asm:28`).
+  `SCENE_NEWBARKTOWN_TEACHER_STOPS_YOU` = 0, `SCENE_NEWBARKTOWN_NOOP` = 1.
+- Fly point / spawn: `NewBarkTownFlypointCallback` sets `ENGINE_FLYPOINT_NEW_BARK`
+  (`constants/engine_flags.asm:79`) on every `MAPCALLBACK_NEWMAP`, and also
+  `clearevent EVENT_FIRST_TIME_BANKING_WITH_MOM`. `SPAWN_NEW_BARK` is
+  (13,6) in `data/maps/spawn_points.asm:27`.
+
+**Warps** (`def_warp_events`)
+
+| idx | x | y | destination map | dest warp |
+|---|---|---|---|---|
+| 1 | 6 | 3 | `ELMS_LAB` | 1 |
+| 2 | 13 | 5 | `PLAYERS_HOUSE_1F` | 1 |
+| 3 | 3 | 11 | `PLAYERS_NEIGHBORS_HOUSE` | 1 |
+| 4 | 11 | 13 | `ELMS_HOUSE` | 1 |
+
+**Coord events** (`def_coord_events`)
+
+| scene | x | y | script label | effect |
+|---|---|---|---|---|
+| `SCENE_NEWBARKTOWN_TEACHER_STOPS_YOU` (0) | 1 | 8 | `NewBarkTown_TeacherStopsYouScene1` | teacher walks 4x LEFT to (2,8), `follow`s the player and drags them back 4x RIGHT |
+| `SCENE_NEWBARKTOWN_TEACHER_STOPS_YOU` (0) | 1 | 9 | `NewBarkTown_TeacherStopsYouScene2` | same, 5 steps, teacher ends at (1,8) facing DOWN |
+
+These two cells are the entire west-exit gate. There is no coord event on the
+east side.
+
+**BG events** (`def_bg_events`)
+
+| x | y | type | script/item |
+|---|---|---|---|
+| 8 | 8 | `BGEVENT_READ` | `NewBarkTownSign` |
+| 11 | 5 | `BGEVENT_READ` | `NewBarkTownPlayersHouseSign` |
+| 3 | 3 | `BGEVENT_READ` | `NewBarkTownElmsLabSign` |
+| 9 | 13 | `BGEVENT_READ` | `NewBarkTownElmsHouseSign` |
+
+**Object events** (`def_object_events`)
+
+| const | sprite | x | y | movement | type | script label | event flag |
+|---|---|---|---|---|---|---|---|
+| `NEWBARKTOWN_TEACHER` | `SPRITE_TEACHER` | 6 | 8 | `SPRITEMOVEDATA_SPINRANDOM_SLOW` | `OBJECTTYPE_SCRIPT` | `NewBarkTownTeacherScript` | `-1` (always visible) |
+| `NEWBARKTOWN_FISHER` | `SPRITE_FISHER` | 12 | 9 | `SPRITEMOVEDATA_WALK_UP_DOWN`, `PAL_NPC_GREEN` | `OBJECTTYPE_SCRIPT` | `NewBarkTownFisherScript` | `-1` |
+| `NEWBARKTOWN_RIVAL` | `SPRITE_RIVAL` | 3 | 2 | `SPRITEMOVEDATA_STANDING_RIGHT` | `OBJECTTYPE_SCRIPT` | `NewBarkTownRivalScript` | `EVENT_RIVAL_NEW_BARK_TOWN` |
+
+**Scripts of interest**
+
+- `NewBarkTownRivalScript` (the "he'll push you out of the way" beat): no
+  `faceplayer`. Prints `NewBarkTownRivalText1` ("So this is the famous ELM #MON
+  LAB…"), `turnobject NEWBARKTOWN_RIVAL, LEFT`, prints `NewBarkTownRivalText2`,
+  then `follow PLAYER, NEWBARKTOWN_RIVAL` +
+  `applymovement PLAYER, NewBarkTown_RivalPushesYouAwayMovement` (`turn_head UP`,
+  `step DOWN`), `stopfollow`, `turnobject NEWBARKTOWN_RIVAL, DOWN`,
+  `playsound SFX_TACKLE`, `applymovement PLAYER, NewBarkTown_RivalShovesYouOutMovement`
+  (`fix_facing`, `jump_step DOWN`), and the rival steps RIGHT back to (3,2).
+  **It sets no flag** - it is repeatable and skippable. `EVENT_RIVAL_NEW_BARK_TOWN`
+  is only set much later, at `maps/MrPokemonsHouse.asm:122`.
+- `NewBarkTown_TeacherStopsYouScene1/2`: the "It's dangerous to go out without a
+  #MON!" block. Ends with `special RestartMapMusic` and does **not** change the
+  scene, so it re-fires every time you step on (1,8)/(1,9) until the scene id is
+  changed from Elm's Lab.
+- `NewBarkTownTeacherScript`: four-way text branch on
+  `EVENT_TALKED_TO_MOM_AFTER_MYSTERY_EGG_QUEST` / `EVENT_GAVE_MYSTERY_EGG_TO_ELM` /
+  `EVENT_GOT_A_POKEMON_FROM_ELM`; flavour only.
+- `NewBarkTownFlypointCallback`: `setflag ENGINE_FLYPOINT_NEW_BARK` on first entry.
+
+**Flags and events**
+
+| constant | defined in | read/written by | meaning for a bot |
+|---|---|---|---|
+| `SCENE_NEWBARKTOWN_TEACHER_STOPS_YOU` (0) | `maps/NewBarkTown.asm:8` | cleared to `SCENE_NEWBARKTOWN_NOOP` by `ElmDirectionsScript`'s `setmapscene NEW_BARK_TOWN, SCENE_NEWBARKTOWN_NOOP` | the west-exit gate |
+| `EVENT_RIVAL_NEW_BARK_TOWN` | `constants/event_flags.asm:1119` | set at `maps/MrPokemonsHouse.asm:122` | rival object hidden once set; clear (visible) all through this section |
+| `ENGINE_FLYPOINT_NEW_BARK` | `constants/engine_flags.asm:79` | `NewBarkTownFlypointCallback` | Fly destination registered |
+| `EVENT_FIRST_TIME_BANKING_WITH_MOM` | `constants/event_flags.asm` | cleared by `NewBarkTownFlypointCallback` | not reachable this section |
+
+**Items**: none. See "Unresolved" for the Everstone.
+
+**Trainers**: none. The rival encounter here is a conversation, not a battle.
+
+**Wild encounters**
+
+- No `def_grass_wildmons NEW_BARK_TOWN` entry exists in `data/wild/johto_grass.asm`.
+- Water (`data/wild/johto_water.asm:211`): `def_water_wildmons NEW_BARK_TOWN`,
+  `db 6 percent`, `db 20, TENTACOOL` / `db 15, TENTACOOL` / `db 20, TENTACRUEL`.
+  Needs Surf, unreachable this section.
+- Fishing: the header's `FISHGROUP_OCEAN` selects
+  `data/wild/fish.asm` `.Ocean_Old` (Magikarp 10 / Magikarp 10 / Tentacool 10),
+  `.Ocean_Good`, `.Ocean_Super`. No rod yet.
+- Headbutt: `data/wild/treemon_maps.asm:28` `treemon_map NEW_BARK_TOWN, TREEMON_SET_CITY`
+  -> `data/wild/treemons.asm:18` `TreeMonSet_City` (Venonat/Abra/Venomoth common,
+  Venonat/Magnemite/Abra/Venomoth rare, all L15). Needs TM02, far later.
+
+### MAP_ELMS_LAB
+
+- Script: `maps/ElmsLab.asm`
+- Blocks: `maps/ElmsLab.blk`
+- Header (`data/maps/maps.asm:476`): `map ElmsLab, TILESET_LAB, INDOOR, LANDMARK_NEW_BARK_TOWN, MUSIC_PROF_ELM, FALSE, PALETTE_DAY, FISHGROUP_SHORE`
+- Dimensions (`constants/map_constants.asm:441`): `map_const ELMS_LAB, 5, 6` (10x12 cells)
+- Connections: none (indoor)
+- Scene var: `wElmsLabSceneID` (`data/maps/scenes.asm:29`). Declaration order
+  gives `SCENE_ELMSLAB_MEET_ELM` = 0, `SCENE_ELMSLAB_CANT_LEAVE` = 1,
+  `SCENE_ELMSLAB_NOOP` = 2, `SCENE_ELMSLAB_MEET_OFFICER` = 3,
+  `SCENE_ELMSLAB_UNUSED` = 4, `SCENE_ELMSLAB_AIDE_GIVES_POTION` = 5,
+  `SCENE_ELMSLAB_AIDE_GIVES_POKE_BALLS` = 6 (the last one is a bare
+  `scene_const`, no script row).
+
+**Warps** (`def_warp_events`)
+
+| idx | x | y | destination map | dest warp |
+|---|---|---|---|---|
+| 1 | 4 | 11 | `NEW_BARK_TOWN` | 1 |
+| 2 | 5 | 11 | `NEW_BARK_TOWN` | 1 |
+
+**Coord events** (`def_coord_events`)
+
+| scene | x | y | script label | effect |
+|---|---|---|---|---|
+| `SCENE_ELMSLAB_CANT_LEAVE` (1) | 4 | 6 | `LabTryToLeaveScript` | Elm turns DOWN, `LabWhereGoingText`, `applymovement PLAYER, ElmsLab_CantLeaveMovement` (one `step UP`) |
+| `SCENE_ELMSLAB_CANT_LEAVE` (1) | 5 | 6 | `LabTryToLeaveScript` | same |
+| `SCENE_ELMSLAB_MEET_OFFICER` (3) | 4 | 5 | `MeetCopScript` | post-theft, next section |
+| `SCENE_ELMSLAB_MEET_OFFICER` (3) | 5 | 5 | `MeetCopScript2` | post-theft, next section |
+| `SCENE_ELMSLAB_AIDE_GIVES_POTION` (5) | 4 | 8 | `AideScript_WalkPotion1` | aide walks 2x RIGHT, gives POTION, walks back |
+| `SCENE_ELMSLAB_AIDE_GIVES_POTION` (5) | 5 | 8 | `AideScript_WalkPotion2` | aide walks 3x RIGHT, gives POTION, walks back |
+| `SCENE_ELMSLAB_AIDE_GIVES_POKE_BALLS` (6) | 4 | 8 | `AideScript_WalkBalls1` | 5x POKE_BALL, next section |
+| `SCENE_ELMSLAB_AIDE_GIVES_POKE_BALLS` (6) | 5 | 8 | `AideScript_WalkBalls2` | 5x POKE_BALL, next section |
+
+**BG events** (`def_bg_events`)
+
+| x | y | type | script/item |
+|---|---|---|---|
+| 2 | 1 | `BGEVENT_READ` | `ElmsLabHealingMachine` |
+| 6 | 1 | `BGEVENT_READ` | `ElmsLabBookshelf` |
+| 7 | 1 | `BGEVENT_READ` | `ElmsLabBookshelf` |
+| 8 | 1 | `BGEVENT_READ` | `ElmsLabBookshelf` |
+| 9 | 1 | `BGEVENT_READ` | `ElmsLabBookshelf` |
+| 0 | 7 | `BGEVENT_READ` | `ElmsLabTravelTip1` |
+| 1 | 7 | `BGEVENT_READ` | `ElmsLabTravelTip2` |
+| 2 | 7 | `BGEVENT_READ` | `ElmsLabTravelTip3` |
+| 3 | 7 | `BGEVENT_READ` | `ElmsLabTravelTip4` |
+| 6 | 7 | `BGEVENT_READ` | `ElmsLabBookshelf` |
+| 7 | 7 | `BGEVENT_READ` | `ElmsLabBookshelf` |
+| 8 | 7 | `BGEVENT_READ` | `ElmsLabBookshelf` |
+| 9 | 7 | `BGEVENT_READ` | `ElmsLabBookshelf` |
+| 9 | 3 | `BGEVENT_READ` | `ElmsLabTrashcan` |
+| 5 | 0 | `BGEVENT_READ` | `ElmsLabWindow` |
+
+**Object events** (`def_object_events`)
+
+| const | sprite | x | y | movement | type | script label | event flag |
+|---|---|---|---|---|---|---|---|
+| `ELMSLAB_ELM` | `SPRITE_ELM` | 5 | 2 | `SPRITEMOVEDATA_STANDING_DOWN` | `OBJECTTYPE_SCRIPT` | `ProfElmScript` | `-1` |
+| `ELMSLAB_ELMS_AIDE` | `SPRITE_SCIENTIST` | 2 | 9 | `SPRITEMOVEDATA_SPINRANDOM_SLOW`, `PAL_NPC_BLUE` | `OBJECTTYPE_SCRIPT` | `ElmsAideScript` | `EVENT_ELMS_AIDE_IN_LAB` |
+| `ELMSLAB_POKE_BALL1` | `SPRITE_POKE_BALL` | 6 | 3 | `SPRITEMOVEDATA_STILL` | `OBJECTTYPE_SCRIPT` | `CyndaquilPokeBallScript` | `EVENT_CYNDAQUIL_POKEBALL_IN_ELMS_LAB` |
+| `ELMSLAB_POKE_BALL2` | `SPRITE_POKE_BALL` | 7 | 3 | `SPRITEMOVEDATA_STILL` | `OBJECTTYPE_SCRIPT` | `TotodilePokeBallScript` | `EVENT_TOTODILE_POKEBALL_IN_ELMS_LAB` |
+| `ELMSLAB_POKE_BALL3` | `SPRITE_POKE_BALL` | 8 | 3 | `SPRITEMOVEDATA_STILL` | `OBJECTTYPE_SCRIPT` | `ChikoritaPokeBallScript` | `EVENT_CHIKORITA_POKEBALL_IN_ELMS_LAB` |
+| `ELMSLAB_OFFICER` | `SPRITE_OFFICER` | 5 | 3 | `SPRITEMOVEDATA_STANDING_UP`, `PAL_NPC_BLUE` | `OBJECTTYPE_SCRIPT` | `CopScript` | `EVENT_COP_IN_ELMS_LAB` |
+
+The ball order on screen is left-to-right **Cyndaquil (6,3), Totodile (7,3),
+Chikorita (8,3)** - not the Pokedex order the walkthrough's title uses. The
+officer is hidden all through this section because `InitializeEventsScript`
+*sets* `EVENT_COP_IN_ELMS_LAB` (`engine/events/std_scripts.asm:469`).
+
+**Scripts of interest**
+
+- `ElmsLabMeetElmScene` (scene 0) -> `sdefer ElmsLabWalkUpToElmScript`:
+  `applymovement PLAYER, ElmsLab_WalkUpToElmMovement` (nine `step UP` then
+  `turn_head RIGHT`, i.e. from the door at (4,11) up to (4,2) beside Elm at
+  (5,2)), `turnobject ELMSLAB_ELM, LEFT`, `writetext ElmText_Intro` (the Mr.
+  Pokemon errand speech), then `setscene SCENE_ELMSLAB_CANT_LEAVE`.
+- `CyndaquilPokeBallScript` / `TotodilePokeBallScript` / `ChikoritaPokeBallScript`:
+  identical shape. `checkevent EVENT_GOT_A_POKEMON_FROM_ELM` -> if set, just
+  `LookAtElmPokeBallScript`. Otherwise `turnobject ELMSLAB_ELM, DOWN`,
+  `reanchormap`, `pokepic <SPECIES>`, `cry <SPECIES>`, `closepokepic`,
+  `writetext Take<Species>Text`, `yesorno`; `iffalse DidntChooseStarterScript`
+  (fully cancellable, nothing is written). On yes:
+  `disappear ELMSLAB_POKE_BALL<n>`, `setevent EVENT_GOT_<SPECIES>_FROM_ELM`,
+  `ChoseStarterText`, `getmonname STRING_BUFFER_3`, `ReceivedStarterText`,
+  `playsound SFX_CAUGHT_MON`, then **`givepoke <SPECIES>, 5, BERRY`** - level 5,
+  holding a BERRY. Finally an `applymovement` that walks the player to (5,3),
+  directly below Elm, and `sjump ElmDirectionsScript`:
+  - Cyndaquil: `readvar VAR_FACING` / `ifequal RIGHT, ElmDirectionsScript` (skips the walk if you took it from the left side), else `AfterCyndaquilMovement` = LEFT, UP.
+  - Totodile: `AfterTotodileMovement` = LEFT, LEFT, UP.
+  - Chikorita: `AfterChikoritaMovement` = LEFT, LEFT, LEFT, UP.
+- `ElmDirectionsScript` - the one script that opens the section up:
+  `turnobject PLAYER, UP`, three Elm texts, `addcellnum PHONE_ELM`,
+  `playsound SFX_REGISTER_PHONE_NUMBER`, then
+  `setevent EVENT_GOT_A_POKEMON_FROM_ELM`,
+  `setevent EVENT_RIVAL_CHERRYGROVE_CITY`,
+  `setscene SCENE_ELMSLAB_AIDE_GIVES_POTION`,
+  `setmapscene NEW_BARK_TOWN, SCENE_NEWBARKTOWN_NOOP`.
+  That last opcode is what removes the teacher gate.
+- `AideScript_GivePotion` (reached by the (4,8)/(5,8) coord events once the scene
+  is 5): `writetext AideText_GiveYouPotion`, `verbosegiveitem POTION`,
+  `AideText_AlwaysBusy`, `setscene SCENE_ELMSLAB_NOOP`. One-shot, gated by the
+  scene id rather than an event flag.
+- `LabTryToLeaveScript`: the "you cannot walk out yet" push-back described above.
+- `ElmsLabHealingMachine` (bg_event at (2,1)): before
+  `EVENT_GOT_A_POKEMON_FROM_ELM` it just prints text; after, it offers a
+  `yesorno` -> `special HealParty`, `setval HEALMACHINE_ELMS_LAB`,
+  `special HealMachineAnim`. Free healing point for a bot from this section on.
+- `ProfElmScript`: long check chain. In this section every branch falls through
+  to `writetext ElmText_LetYourMonBattleIt` (after the starter) or
+  `ElmDescribesMrPokemonScript`. The `ElmGiveEverstoneScript` arm needs
+  `EVENT_SHOWED_TOGEPI_TO_ELM`; the Master Ball arm needs `ENGINE_RISINGBADGE`;
+  the S.S. Ticket arm needs `EVENT_BEAT_ELITE_FOUR`.
+
+**Flags and events**
+
+| constant | defined in | read/written by | meaning for a bot |
+|---|---|---|---|
+| `EVENT_GOT_A_POKEMON_FROM_ELM` | `constants/event_flags.asm:35` | set by `ElmDirectionsScript`; read by the ball scripts, `MomScript`, `NewBarkTownTeacherScript`, `PlayersHouseRadioScript`, `ElmsLabHealingMachine` | the section's terminal flag |
+| `EVENT_GOT_CYNDAQUIL_FROM_ELM` | `constants/event_flags.asm:36` | `CyndaquilPokeBallScript` | which starter (Totodile/Chikorita variants are the next two consts) |
+| `EVENT_CYNDAQUIL_POKEBALL_IN_ELMS_LAB` | `constants/event_flags.asm:993` | `disappear ELMSLAB_POKE_BALL1` | ball object removed |
+| `EVENT_TOTODILE_POKEBALL_IN_ELMS_LAB` | `constants/event_flags.asm:994` | `disappear ELMSLAB_POKE_BALL2` | ball object removed |
+| `EVENT_CHIKORITA_POKEBALL_IN_ELMS_LAB` | `constants/event_flags.asm:995` | `disappear ELMSLAB_POKE_BALL3` | ball object removed |
+| `EVENT_COP_IN_ELMS_LAB` | `constants/event_flags.asm:1188` | set by `InitializeEventsScript`, cleared at `maps/MrPokemonsHouse.asm:127` | officer hidden this section |
+| `EVENT_ELMS_AIDE_IN_LAB` | `constants/event_flags.asm:1187` | cleared at `maps/VioletPokecenter1F.asm:31`, set at `engine/phone/scripts/elm.asm:85` | aide visible (flag clear) this section |
+| `EVENT_RIVAL_CHERRYGROVE_CITY` | `constants/event_flags.asm` | set by `InitializeEventsScript` and again by `ElmDirectionsScript` | Cherrygrove rival still hidden |
+| `EVENT_GOT_EVERSTONE_FROM_ELM` | `constants/event_flags.asm:95` | `ElmGiveEverstoneScript` | **not reachable in this section** |
+| `SCENE_ELMSLAB_*` | `maps/ElmsLab.asm:11-17` | `setscene` / `setmapscene` | drives every coord event on the map |
+
+**Items**
+
+| item | how obtained | source (label / bg_event / hidden) | one-time flag |
+|---|---|---|---|
+| `POTION` | walk onto (4,8) or (5,8) on the way out after picking a starter | `AideScript_GivePotion` (`verbosegiveitem POTION`) | `SCENE_ELMSLAB_AIDE_GIVES_POTION` -> `SCENE_ELMSLAB_NOOP` |
+| starter, L5, holding `BERRY` | `givepoke` in the chosen ball script | `CyndaquilPokeBallScript` / `TotodilePokeBallScript` / `ChikoritaPokeBallScript` | `EVENT_GOT_<SPECIES>_FROM_ELM` + `EVENT_GOT_A_POKEMON_FROM_ELM` |
+| `EVERSTONE` | Elm, **after** showing him a hatched Togepi | `ElmGiveEverstoneScript` (`maps/ElmsLab.asm:341`) | `EVENT_GOT_EVERSTONE_FROM_ELM` |
+| `POKE_BALL` x5 | aide, after the Mystery Egg hand-off | `AideScript_GiveYouBalls` | `SCENE_ELMSLAB_AIDE_GIVES_POKE_BALLS` -> `SCENE_ELMSLAB_NOOP` |
+
+**Trainers**: none. No `loadtrainer` / `startbattle` anywhere in
+`maps/ElmsLab.asm`, `maps/NewBarkTown.asm`, `maps/PlayersHouse1F.asm` or
+`maps/PlayersHouse2F.asm`.
+
+**Wild encounters**: none (indoor).
+
+**Starter data** (`data/pokemon/evos_attacks.asm`, checked against the
+walkthrough's claims - all three match)
+
+| species | evolves | L5 known moves | later moves the FAQ names |
+|---|---|---|---|
+| `CHIKORITA` | `EVOLVE_LEVEL, 16, BAYLEEF`; Bayleef `EVOLVE_LEVEL, 32, MEGANIUM` | TACKLE (1), GROWL (1) | RAZOR_LEAF 8, REFLECT 12, POISONPOWDER 15, SYNTHESIS 22, BODY_SLAM 29, LIGHT_SCREEN 36, SAFEGUARD 43, SOLARBEAM 50 |
+| `CYNDAQUIL` | `EVOLVE_LEVEL, 14, QUILAVA`; Quilava `EVOLVE_LEVEL, 36, TYPHLOSION` | TACKLE (1), LEER (1) | SMOKESCREEN 6, EMBER 12, QUICK_ATTACK 19, FLAME_WHEEL 27, SWIFT 36, FLAMETHROWER 46 |
+| `TOTODILE` | `EVOLVE_LEVEL, 18, CROCONAW`; Croconaw `EVOLVE_LEVEL, 30, FERALIGATR` | SCRATCH (1), LEER (1) | RAGE 7, WATER_GUN 13, BITE 20, SCARY_FACE 27, SLASH 35, SCREECH 43, HYDRO_PUMP 52 |
+
+Note the FAQ's move lists are aspirational (they mix level-up moves with HM03 /
+HM04). At the moment you receive it the starter knows exactly its two level-1
+moves; Cyndaquil does **not** have Ember yet at L5.
+
+## 3. Blockers and gates
+
+| Gate | Enforced by (file:label) | Requirement | Unlock condition |
+|---|---|---|---|
+| Clock must be set before the world exists | `engine/menus/intro_menu.asm:494` `OakSpeech` -> `farcall InitClock` (`engine/rtc/timeset.asm:4`); default hour is 10 (`ld a, 10 ; default hour = 10 AM`) | hour then minute then a `YesNoBox` confirm each | answering "yes" to both confirmations |
+| Player must be named | `engine/menus/intro_menu.asm` `NamePlayer` -> `ShowPlayerNamingChoices` / `StorePlayerName` | pick a preset or type a name | any accepted name |
+| Cannot walk out of Elm's Lab before the errand speech ends | `maps/ElmsLab.asm` coord events (4,6) and (5,6) under `SCENE_ELMSLAB_CANT_LEAVE`, script `LabTryToLeaveScript` | scene id must leave 1 | `ElmDirectionsScript`'s `setscene SCENE_ELMSLAB_AIDE_GIVES_POTION` - i.e. take a starter |
+| Cannot leave New Bark Town west toward Route 29 | `maps/NewBarkTown.asm` coord events (1,8) and (1,9) under `SCENE_NEWBARKTOWN_TEACHER_STOPS_YOU`, scripts `NewBarkTown_TeacherStopsYouScene1/2` | scene id must leave 0 | `ElmDirectionsScript`'s `setmapscene NEW_BARK_TOWN, SCENE_NEWBARKTOWN_NOOP` |
+| Aide's Potion is scene-gated, not flag-gated | `maps/ElmsLab.asm` coord events (4,8)/(5,8), `AideScript_GivePotion` | be on scene 5 and step on x=4 or 5, y=8 | script itself does `setscene SCENE_ELMSLAB_NOOP` |
+| Everstone (listed by the FAQ under New Bark Town) | `maps/ElmsLab.asm:63,338-347` `ElmCheckEverstone` / `ElmGiveEverstoneScript` | `EVENT_SHOWED_TOGEPI_TO_ELM`, which needs a hatched Togepi in the party (`special FindPartyMonThatSpeciesYourTrainerID`) | many sections later |
+
+No HM field-move gate applies in this section: nothing under
+`engine/overworld/` (cut/surf/strength/whirlpool/waterfall/flash/fly) is
+consulted between the bedroom and the starter.
+
+## 4. Bot checklist
+
+| # | Map | Target | Intent | Precondition | Postcondition |
+|---|---|---|---|---|---|
+| 1 | - (main menu) | NEW GAME | menu select | fresh save | `NewGame` runs `ResetWRAM` |
+| 2 | - (`InitClock`) | hour, then minute, then yes/no per field | menu | in `OakSpeech` | RTC base written; default hour 10 |
+| 3 | - (`NamePlayer`) | any name | naming screen | after `OakText6` | `wPlayerName` set |
+| 4 | `PLAYERS_HOUSE_2F` | spawn (3,3) | - | `SPAWN_HOME` | `MAPCALLBACK_NEWMAP` runs `InitializeEventsScript` once; `EVENT_INITIALIZED_EVENTS` set |
+| 5 | `PLAYERS_HOUSE_2F` | warp 1 at (7,0) | walk onto | - | now on `PLAYERS_HOUSE_1F` warp 3 (9,0) |
+| 6 | `PLAYERS_HOUSE_1F` | (scene 0 auto-fires) | wait / mash A through `MeetMomScript` | `wPlayersHouse1FSceneID` == 0 | `ENGINE_POKEGEAR`, `ENGINE_PHONE_CARD`, `PHONE_MOM`, `EVENT_PLAYERS_HOUSE_MOM_1`, scene -> 1 |
+| 6a | `PLAYERS_HOUSE_1F` | DST `yesorno` pair | answer, then confirm | inside `MeetMomScript` | answering "no" to the confirm loops back to `.SetDayOfWeek` - a bot must confirm, not just answer |
+| 7 | `PLAYERS_HOUSE_1F` | warp 1 (6,7) or warp 2 (7,7) | walk onto | - | `NEW_BARK_TOWN` at warp 2 (13,5) |
+| 8 | `NEW_BARK_TOWN` | object `NEWBARKTOWN_RIVAL` at (3,2) | talk (optional) | rival visible while `EVENT_RIVAL_NEW_BARK_TOWN` clear | pushed one cell DOWN + a `jump_step DOWN`; **no flag set**, skippable |
+| 9 | `NEW_BARK_TOWN` | warp 1 at (6,3) | walk onto | avoid (1,8)/(1,9) until step 12 | `ELMS_LAB` at warp 1 (4,11) |
+| 10 | `ELMS_LAB` | (scene 0 auto-fires) | wait / mash A | `wElmsLabSceneID` == 0 | player auto-walked to (4,2); scene -> 1 (`CANT_LEAVE`) |
+| 11 | `ELMS_LAB` | ball object: (6,3) Cyndaquil / (7,3) Totodile / (8,3) Chikorita | face + A, answer **yes** to `yesorno` | `EVENT_GOT_A_POKEMON_FROM_ELM` clear | starter L5 w/ BERRY in party; `EVENT_GOT_<SP>_FROM_ELM`; ball disappears; auto-walk to (5,3); `ElmDirectionsScript` runs -> `EVENT_GOT_A_POKEMON_FROM_ELM`, `PHONE_ELM`, `ELMS_LAB` scene -> 5, `NEW_BARK_TOWN` scene -> 1 |
+| 12 | `ELMS_LAB` | (4,8) or (5,8) | walk onto on the way out | scene == 5 | `POTION` in bag; scene -> 2 (`NOOP`) |
+| 13 | `ELMS_LAB` | bg_event (2,1) | face UP + A -> yes (optional) | `EVENT_GOT_A_POKEMON_FROM_ELM` set | party healed (`special HealParty`) |
+| 14 | `ELMS_LAB` | warp 1 (4,11) or warp 2 (5,11) | walk onto | - | `NEW_BARK_TOWN` (6,3) |
+| 15 | `NEW_BARK_TOWN` | west edge past (1,8)/(1,9) | walk west | `NEW_BARK_TOWN` scene == 1 | crosses the `connection west, Route29` into `ROUTE_29` - section 01 |
+
+## 5. Port coverage
+
+| Beat | Port file | Status |
+|---|---|---|
+| Title -> NEW GAME -> Oak speech -> name pick -> naming screen -> bedroom | `src/ui/gen2/TitleState.lua`, `src/ui/gen2/MainMenu.lua`, `src/ui/gen2/OakSpeech.lua`, `src/ui/gen2/NamePick.lua`, `src/ui/gen2/NamingScreen.lua`; asserted end-to-end by `tests/drivers/gold_boot_smoke.lua` | implemented |
+| `InitClock` (the "what time is it?" / minute screens) | none - `src/ui/gen2/OakSpeech.lua:3` says outright "Gender select / InitClock are Crystal-later" | **missing** (bot step 2 has no screen to drive) |
+| `SPAWN_HOME` start at `PLAYERS_HOUSE_2F` (3,3) | `src/world/gen2/World.lua:228-232` (`START_MAP = "PLAYERS_HOUSE_2F"`, cites `data/maps/spawn_points.asm`) | implemented |
+| Map load, warps, collision, connections | `src/world/gen2/Map.lua`, `src/world/gen2/World.lua`; `tests/drivers/gold_walk_smoke.lua`, `tests/drivers/gold_warp_scene.lua` (asserts the New Bark door lands on `ELMS_LAB`) | implemented |
+| Scene scripts + coord events (the mechanism every gate in this section uses) | `src/world/gen2/World.lua:5011-5035` (`coordEvents` scan filtered by `self:scene()`, `sceneScripts` lookup), extracted by `src/import/RomExtractorGen2.lua:804-977` | implemented |
+| `MAPCALLBACK_NEWMAP` / `MAPCALLBACK_TILES`, `ToggleDecorationsVisibility`, `ToggleMaptileDecorations` | `src/script/gen2/Specials.lua:489-505`, `tests/drivers/gold_map_callbacks.lua`, `tests/gen2_map_callbacks_test.lua` | implemented |
+| `MeetMomScript` (emote, follow-free walk-in, `yesorno` under a prompt, mid-scene object swap) | driven by the VM; regression driver `tests/drivers/gold_mom_scene.lua` exists specifically for this scene; the Mom object-swap timing is commented at `src/world/gen2/World.lua:558-568,730` | implemented |
+| `special SetDayOfWeek` / `InitialSetDSTFlag` / `InitialClearDSTFlag` | `src/script/gen2/Specials.lua:836-860` | partial - the flags/RTC fields are written from the host clock, but no day-of-week picker UI is drawn, so the player never chooses |
+| Teacher west-exit gate | `tests/drivers/gold_teacher_scene.lua` (asserts `follow` drags the player back and she stands beside them) | implemented |
+| Rival push-out (`follow` + `jump_step` + `SFX_TACKLE`) | VM ops `follow`/`stopfollow` (`src/script/gen2/Opcodes.lua:117-118`), movement in `src/script/gen2/Movement.lua` | partial - opcodes present, no driver covering `NewBarkTownRivalScript` specifically |
+| Starter pick: `pokepic`, `cry`, `yesorno`, `disappear`, `givepoke SP, 5, BERRY` | `src/script/gen2/Opcodes.lua:91-92,51`; `src/script/gen2/Vm.lua:386-394` (`pokepic` -> `showPicFn`), `:439-445` (`givepoke` -> `givePokeFn` with species/level/held item) | partial - all opcodes implemented, but no driver or test in `tests/drivers/gold_*.lua` walks the Elm's Lab starter choice end to end |
+| `verbosegiveitem POTION` (aide) | `src/script/gen2/Vm.lua:490-510` (received text, SFX, "put in the ITEM POCKET") | implemented |
+| `addcellnum PHONE_MOM` / `PHONE_ELM`, Pokegear phone card | `src/script/gen2/Vm.lua:611`, `src/core/gen2/Phone.lua:137,146`, `src/ui/gen2/Pokegear.lua` | implemented |
+| `special HealParty` / `HealMachineAnim` (lab healing machine) | `src/script/gen2/Specials.lua:456` | implemented |
+| `special PlayersHousePC` + `warp NONE, 0, 0` | `src/script/gen2/Specials.lua:467-487`, `src/ui/gen2/PcMenu.lua` | implemented |
+| `special NameRival` (fires next section, from `CopScript`) | `src/script/gen2/Specials.lua:825-828` -> `World:nameRival` (`src/world/gen2/World.lua:4931`) | implemented |
+| Event-flag bitfield semantics (set flag = object hidden) | `src/world/gen2/Events.lua` (header comment cites `CheckObjectFlag` in `map_objects_2.asm`) | implemented |
+
+## 6. Unresolved / verify by hand
+
+- **Everstone.** The FAQ lists "Everstone" under "Items found in New Bark Town".
+  There is no Everstone item ball, hidden item or bg_event on `MAP_NEW_BARK_TOWN`,
+  `MAP_ELMS_LAB`, `MAP_PLAYERS_HOUSE_1F` or `MAP_PLAYERS_HOUSE_2F`. The only New
+  Bark Town Everstone is `ElmGiveEverstoneScript` (`maps/ElmsLab.asm:338-347`),
+  which requires `EVENT_SHOWED_TOGEPI_TO_ELM` - a hatched Togepi shown to Elm,
+  many sections later. Treat the FAQ line as forward-looking, not as an item to
+  collect here.
+- **"Pokegear" as an item.** The FAQ says "You get the Pokegear". In the asm it is
+  `setflag ENGINE_POKEGEAR` + `setflag ENGINE_PHONE_CARD`, with the item name
+  faked through `getstring STRING_BUFFER_4, PokegearName` ("#GEAR") into the
+  standard `ReceiveItemScript` text. Nothing enters the bag - a bot must not
+  check inventory for it.
+- **"Professor Oak will ask you the time. First answer what hour it is and what
+  minute it is."** `InitClock` (`engine/rtc/timeset.asm`) is reached from
+  `OakSpeech` *before* any Oak text is printed (`farcall InitClock` is the first
+  instruction of `OakSpeech`), so the clock screen actually comes first and Oak's
+  greeting second. The FAQ's ordering is the reverse.
+- **"even if you don't have the GBA on, the time will keep running"** - an RTC
+  hardware claim, nothing in the disassembly to cite; ignore.
+- **East exit toward Route 27.** `data/maps/attributes.asm:121` gives New Bark Town
+  a `connection east, Route27, ROUTE_27, 0`, and unlike the west side there is
+  *no* coord event guarding it. Whether a bot can actually walk east before
+  getting Surf depends on the shoreline tiles in `maps/NewBarkTown.blk`, which I
+  did not decode. Verify by hand before relying on the west gate as the only exit
+  block.
+- **Teacher gate coverage.** Only (1,8) and (1,9) carry coord events. If the map's
+  west connection strip is reachable at any other y, the gate has a hole. I read
+  the coord table but not the collision data, so this is unverified.
+- **Rival battle.** The FAQ says only that he pushes you; confirmed - there is no
+  `loadtrainer`/`startbattle` in `NewBarkTownRivalScript`. The first rival battle
+  is not in this section.
--- a/Show More
+++ b/Show More