Philips CD-i decomp guide

What this system is like

CD-i games run on a Philips SCC68070 chip. It runs the same code as a Motorola 68000. Each game is a set of OS-9 program files on a CD. The game asks the CD-i operating system, called CD-RTOS, for almost everything. So most of your work is a stand-in for that system, not for raw chips.

For Path A, every reviewed port used static recompilation. A recompiler turns machine code into C. The ten tools81 ports share one Python recompiler. HotelMario-Decomp wrote its own. A runtime answers the game's system calls and draws the picture. A built-in interpreter runs any code the recompiler missed. Ten Windows ports by one author shipped in about three weeks from one shared design.

For Path B, two CD-i games already have matching decomps. Link: The Faces of Evil and Zelda: The Wand of Gamelon rebuild byte for byte with Apple's old MPW C 3.0 compiler. Every game function is in C. The compiler's runtime, the startup code and a few drawing routines are still assembly. Games built with Microware's OS-9 C compiler are harder. Nobody in these projects had that compiler, so their C cannot be byte-checked yet.

Path A runs fully on Windows with Visual Studio and Python. Path B needs WSL for the old-Mac compiler route. Expect weeks for Path A and months for Path B.

Two paths

Path A: Get it running on PC

You pull the game's OS-9 modules off the disc. A Python recompiler you write turns each module's 68000 code into C. A runtime in C stands in for CD-RTOS, the CD file manager, the MCD212 video and the audio. An interpreter runs code that loads at run time. A switch that runs everything in the interpreter gives you a reference to compare against.

1. Pick the game and pin the disc

   You choose one game and one exact disc. You hash the disc image so every check uses the same bytes. You look for work that already exists. Many CD-i games already have a port or a decomp.

   • Keep your own disc image outside the repo, for example D:/cdi-discs/<GAME>/<GAME>.bin and its .cue.
   • Hash it on Windows with certutil -hashfile "<GAME>.bin" SHA1, or in WSL with sha1sum "<GAME>.bin".
   • If you have a .chd, convert it with chdman extractcd -i <GAME>.chd -o <GAME>.cue -ob <GAME>.bin. chdman is one of the tools that come with MAME.
   • Note the region: PAL (Europe) or NTSC (USA). PAL games run 50 fields a second and need other video timing.
   • Note if the game needs the MPEG-1 Digital Video cartridge. Those games need a video decoder in the runtime.
   • Search GitHub for the game name plus CD-i. Check tools81, mstan, antonretro, Megamil-Decomp and ByteDecompiler.
   • Write SCOPE.md: game, region, disc SHA-1, goal, technique, first milestone and its check, and what is out of scope.
   Prompt for ClaudeCopy

   GOAL: Draft SCOPE.md for a Path A port of <GAME> (<REGION>) on Philips CD-i.
   READ FIRST: The SHA-1 of <ABSOLUTE_PATH_TO_BIN> (I will paste it), https://github.com/tools81/hotel-mario-static-recomp , https://github.com/mstan/cdirecomp
   FENCE: Create only `SCOPE.md` and `notes/prior-work.md`. Do not copy any disc file into the repo. Do not write code. Do not download any game, BIOS or disc image.
   CHECK: Run `certutil -hashfile <ABSOLUTE_PATH_TO_BIN> SHA1`. Done means its hash is the one in SCOPE.md, and SCOPE.md lists the disc file name and SHA-1, the region, PAL or NTSC, whether it needs the video cartridge, prior work with links, the first milestone with its check, and an out-of-scope list.
   BUDGET: Stop after 45 minutes of searching.
   IF BLOCKED: Stop. Do not guess a hash or a region. Tell me what is missing.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the hash line and the links you checked. 3) Files changed. 4) Prior work found. 5) New parking-lot items.

   Done whenSCOPE.md names the disc by SHA-1, the region and the first milestone, and you approved it.

   Proof this works: Hotel Mario Decomp, Zelda's Adventure, The Apprentice Recomp, https://docs.mamedev.org/tools/chdman.html

2. Set up the repo, tools and one check

   You make the repo and install the build tools. You copy the folder layout the reviewed ports use. You write one check command early, even before it has much to check. Game files never enter the repo.

   • Install Visual Studio 2022 Build Tools with the C++ workload: winget install Microsoft.VisualStudio.2022.BuildTools --override "--add Microsoft.VisualStudio.Workload.VCTools --includeRecommended --passive". Without --override, no C++ compiler is added.
   • Install CMake with winget install Kitware.CMake. Install Python and Git with winget install Python.Python.3.12 and winget install Git.Git. The ports need Python 3.8 or newer.
   • Make these folders: tools/ (Python), runtime/ (C), test/, docs/ and notes/. Add game.json for the game's modules and load addresses.
   • Put rom/, gen/, extracted/, build/, saves/ and tools/ext/ in .gitignore before any disc file is near the repo.
   • Write build.bat. It runs python tools\gen.py (only if that file exists: you write it in step 5), then cmake -S . -B build\cmake -G "Visual Studio 17 2022" -A x64, then cmake --build build\cmake --config Release --parallel.
   • Write tools\check.bat. It runs the build, the instruction tests and the headless compare from step 6. It prints PASS or FAIL.
   • Write CLAUDE.md, PROGRESS.md and notes/parking-lot.md. Read the tools81 READMEs for ideas. They have no licence, so do not copy their code.
   Prompt for ClaudeCopy

   GOAL: Make the empty project build with one command and give one PASS or FAIL check.
   READ FIRST: `SCOPE.md`, https://github.com/tools81/hotel-mario-static-recomp (README sections Building and Layout, for design only)
   FENCE: Create only `build.bat`, `tools/check.bat`, `CMakeLists.txt`, `.gitignore`, `game.json`, `CLAUDE.md`, `PROGRESS.md`, `notes/parking-lot.md` and empty `tools/`, `runtime/`, `test/` folders. Do not copy code from any repo with no licence. Do not install anything; tell me what is missing.
   CHECK: Run `build.bat` then `tools\check.bat`. Done means both exit with code 0 and `check.bat` prints PASS on the empty project. `git status` shows no file from `rom/`.
   BUDGET: Stop after 3 failed builds.
   IF BLOCKED: Stop. Paste the error. Do not work around a missing tool.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste both outputs. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenbuild.bat and tools\check.bat both exit 0 on a clean clone, and git status lists no game file.

   Proof this works: Hotel Mario Static Recomp, Link: The Faces of Evil Static Recomp, Kether

3. Pull out the modules and map the code

   You read the Green Book file system and copy the game's OS-9 modules out of the disc. Then you find every function. Symbol files and MacsBug names give you real names. The result is a ledger: one row per function, with a status.

   • Write tools/cdi_extract.py. It reads the disc's file system and writes modules to extracted/. Find the boot program from the disc label.
   • Do not trust file numbers to spot video and sound streams. On several discs every file has file number 1. Use the sector submode bits instead.
   • Write tools/os9mod.py to read each module header. It should recompute the header parity and the CRC-24, so you know the read is right.
   • Look for a <program>.stb symbol module and a <program>_data module. Read both. Hotel Mario's coverage was 21% before this.
   • Open each module in Ghidra 12.2 as raw 68000 code at its load address. Or build the ghidra-os9 loader for your Ghidra version.
   • Write tools/analyze.py: recursive descent from the entry points, plus jump tables, switch tables and the jsr N(a6) stub table.
   • Save the ledger to notes/functions.csv: address, size, name, source of the name, and status.
   Prompt for ClaudeCopy

   GOAL: Build the function ledger for <MODULE> of <GAME>.
   READ FIRST: `SCOPE.md`, `game.json`, the module at <ABSOLUTE_PATH_TO_EXTRACTED>/<MODULE>, and <MODULE>.stb if it exists.
   FENCE: Edit only `tools/os9mod.py`, `tools/analyze.py`, `notes/functions.csv` and `docs/CDI_NOTES.md`. Never write module bytes or listings into the repo.
   CHECK: Run `python tools/analyze.py <MODULE_INDEX>`. Done means `os9mod.py` reports the header parity and CRC-24 as correct, the ledger lists every function with address and size, and the script prints code coverage as a percent of the code area.
   BUDGET: Stop after 90 minutes or 3 tries at one pattern with no coverage gain.
   IF BLOCKED: Stop. Name the address range you cannot classify as code or data, and why.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the CRC line and the coverage line. 3) Files changed. 4) Patterns still missed. 5) New parking-lot items.

   Done whennotes/functions.csv lists every function, the CRC-24 checks out, and coverage is printed as a number.

   Proof this works: Hotel Mario Static Recomp, Laser Lords static recomp, Flintstones/Jetsons: Timewarp, https://github.com/moralrecordings/ghidra-os9

4. Boot the game on an interpreter first

   Before any recompiler, you run the game's own code in a 68000 interpreter. Your runtime answers the OS-9 calls. The goal is the first picture, like the Philips logo. This gives you a working reference for every later check.

   • Write your own small interpreter, or fetch Musashi the way HotelMario-Decomp does: git clone --depth 1 https://github.com/kstenerud/Musashi.git tools/ext/Musashi. It has an MIT licence.
   • Write runtime/os9.c. It handles TRAP #0 calls such as F$Load, F$Link, I$Read, F$Fork and F$Sleep.
   • Make every unknown call fail loud. Log the call, the address and the registers to saves/recomp.log, then stop.
   • Build the system globals block that address 0 points to. Keep its tick counter current. Hotel Mario hung at the logo without it.
   • Write runtime/cdfm.c for disc reads and runtime/video.c for the MCD212 display tables. Start with what the logo needs.
   • Add a headless mode: --headless --frames N --dump K writes every Kth frame as a picture. Claude reads these, not a window.
   • Record new call numbers in docs/CDI_NOTES.md, with the game address that proved each one.
   Prompt for ClaudeCopy

   GOAL: Boot <GAME> in the interpreter until the first logo frame appears in a headless dump.
   READ FIRST: `SCOPE.md`, `docs/CDI_NOTES.md`, `notes/functions.csv`, https://icdia.co.uk/docs/funcspec.html
   FENCE: Edit only `runtime/` and `docs/CDI_NOTES.md`. Do not edit `tools/`. No stubs that return success: an unknown call must stop the run with its number and address.
   CHECK: Run `build\cmake\Release\game.exe --headless --frames 600 --dump 60 --interp`. Done means `saves/` holds a frame that shows the logo and `saves/recomp.log` has no fatal error before field 600.
   BUDGET: Stop after 3 failed tries at the same call, or 60 minutes with no new call answered.
   IF BLOCKED: Stop. Name the call, its address and what the Green Book says. Do not invent its behaviour.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the log tail and the frame file name. 3) Files changed. 4) Calls added, with proof addresses. 5) New parking-lot items.

   Done whenA headless run with --interp writes a frame that shows the first logo, with no fatal error in the log.

   Proof this works: Hotel Mario Decomp, Hotel Mario Static Recomp, https://github.com/kstenerud/Musashi

5. Write the 68000-to-C recompiler

   Now you translate the mapped functions into C. Each 68000 function becomes one C function that works on a saved register set. Code the recompiler did not find falls back to the interpreter. The output goes to gen/ and is never edited by hand.

   • Write tools/m68k.py, a 68000 decoder. Check it against Capstone with pip install capstone on many instructions.
   • Write tools/gen.py. It reads the ledger and game.json and writes C files to gen/.
   • Compute condition flags only where a later instruction reads them. The Link port calls this flag liveness.
   • Turn calls through the jsr N(a6) stub table into direct C calls, with a guard check.
   • Send a jump to an unknown address back to the interpreter and log it. Do not crash. Voyeur's port did this.
   • List self-modifying code in game.json as interp_ranges, so the interpreter runs it from live bytes.
   • Keep the --interp switch working. It runs every function in the interpreter for comparison.
   Prompt for ClaudeCopy

   GOAL: Make `tools/gen.py` translate <MODULE> to C so the recompiled build reaches the same logo frame as step 4.
   READ FIRST: `CLAUDE.md`, `notes/functions.csv`, `game.json`, `runtime/` (only the dispatcher and CPU state files)
   FENCE: Edit only `tools/m68k.py`, `tools/gen.py` and the dispatcher file in `runtime/`. Never edit files in `gen/`; regenerate them. Do not change the interpreter.
   CHECK: Run `build.bat`, then `game.exe --headless --frames 600 --dump 60` and the same with `--interp`. Done means both runs write byte-identical frame files and `recomp.log` lists how many calls fell back to the interpreter.
   BUDGET: Stop after 4 failed builds in a row or 2 hours.
   IF BLOCKED: Stop. Paste the first instruction that decodes differently from Capstone.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the compare output and the fallback count. 3) Files changed. 4) Instruction types not yet handled. 5) New parking-lot items.

   Done whenThe recompiled and the --interp runs give byte-identical frames up to the logo, and the fallback count is logged.

   Proof this works: Link: The Faces of Evil Static Recomp, Voyeur (CD-i) static recompilation, Kether, https://pypi.org/project/capstone/

6. Prove the translation with tests

   A running game is not proof. You need tests that compare the recompiled code with the interpreter, one instruction at a time and over long runs. Every reviewed port did both. After this step, every change must keep these tests green.

   • Write tools/gen_tests.py. It makes random register states and runs each instruction both ways. Build it as insn_test.
   • Write ALU reference vectors with an independent model, as test/gen_alu_vectors.py. Build them as alu_test.
   • Run cmake --build build\cmake --config Release --target insn_test alu_test, then run both test programs.
   • Add scripted input: --script "field:key:dur,...". Add random input: --fuzz SEED. Add sound capture: --wav out.wav.
   • Run the same session twice, once with --interp. Compare every dumped frame and the WAV files byte for byte.
   • Run comparison runs in separate folders. Each run writes saves next to the program, and old saves change the result.
   • Add all of this to tools\check.bat, so one command runs it.
   Prompt for ClaudeCopy

   GOAL: Add instruction tests, ALU vectors and a headless interp-versus-recompiled compare to `tools\check.bat`.
   READ FIRST: `CLAUDE.md`, `tools/m68k.py`, https://github.com/tools81/hotel-mario-static-recomp (README section Debugging, for design only)
   FENCE: Edit only `tools/gen_tests.py`, `test/`, `tools/diffrun.py` and `tools/check.bat`. Do not change `tools/gen.py` or `runtime/` in this task. Do not loosen a comparison to make it pass.
   CHECK: Run `tools\check.bat`. Done means it runs at least 2,000 instruction tests, all ALU vectors and a 4,000-field fuzzed compare, and prints PASS. Then break one opcode on purpose and show that it prints FAIL.
   BUDGET: Stop after 90 minutes.
   IF BLOCKED: Stop. Paste the first failing instruction with both register sets.
   OTHER PROBLEMS: Real translation bugs go in `notes/parking-lot.md`. Do not fix them here.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the PASS output and the FAIL output from the broken opcode. 3) Files changed. 4) Test counts. 5) New parking-lot items.

   Done whentools\check.bat prints PASS, and it prints FAIL when one opcode is broken on purpose.

   Proof this works: Hotel Mario Static Recomp, Mutant Rampage: Bodyslam Static Recomp, Zelda: Wand of Gamelon Static Recomp, The Apprentice Recomp

7. Grind: calls, pictures, sound and coverage

   Now you play further, one problem at a time. Each unit is one missing OS call, one picture bug, one sound bug, or one code gap. Every unit has a scripted run that shows it. Each fix must keep tools\check.bat green.

   • Read saves/recomp.log for unknown calls and SetStat or GetStat codes. Each one is a unit.
   • Use --trace for system calls, --ramdump N for RAM and display tables, and --watch ADDR for one address.
   • Learn call numbers from the game's own wrapper code. The Green Book names calls but often gives no number.
   • Raise coverage by teaching analyze.py a new pattern, not by listing guessed addresses. Laser Lords went from 41% to 94% this way.
   • For PAL games set 625 lines, 280-line fields and 50 fields a second. Zelda's Adventure needed this.
   • Add a game-specific piece only through game.json hooks. Keep the shared runtime free of single-game hacks.
   • Mark each unit done in PROGRESS.md with the run that proves it.
   Prompt for ClaudeCopy

   GOAL: Fix one unit: <UNIT> (a missing call, a picture bug, a sound bug or a coverage gap) seen at field <FIELD>.
   READ FIRST: `CLAUDE.md`, `PROGRESS.md`, `docs/CDI_NOTES.md`, the last 50 lines of `saves/recomp.log`, and the run command: <SCRIPT_OR_FUZZ_SEED>
   FENCE: Edit only <FILES> in `runtime/` or `tools/analyze.py`, plus `docs/CDI_NOTES.md` and `PROGRESS.md`. Never edit `gen/`. No stub that fakes success. No guessed entry points.
   CHECK: Run the scripted run past field <FIELD> and `tools\check.bat`. Done means the unit's symptom is gone in the dumped frames or log, and check.bat prints PASS.
   BUDGET: Stop after 3 failed fixes or 60 minutes.
   IF BLOCKED: Stop. Give the address, the call or register, and what you know. Do not work around it.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the frame names, log lines and check output. 3) Files changed. 4) The cause, with the address that proves it. 5) New parking-lot items.

   Done whenThe unit's scripted run passes its field with no fatal log line, and tools\check.bat prints PASS.

   Proof this works: Laser Lords static recomp, Zelda's Adventure, Kether, Hotel Mario Static Recomp

8. Harden it and ship without game code

   You turn your test runs into a regression set, so old fixes stay fixed. You add long fuzz runs. Then you package a build that holds no game code. The player builds it from their own disc, or runs the disc's code in the interpreter.

   • Save each passing scripted run as a regression case in tests/regress/, with the hash of its final frame.
   • Run three long fuzz sessions, for example 30,000 fields each, with no fatal error.
   • If you add quicksaves, check that fields after a load match fields after the save.
   • Make blocking calls like F$Sleep return to the main loop, so the whole machine can be saved between fields.
   • Ship only tools and runtime. Voyeur's release runs the disc's own program in the interpreter, so it contains no game code.
   • Make the packaging script refuse to zip if any file holds game code or disc data. HotelMario-Decomp does this.
   • Build an installer with Inno Setup 6, as the tools81 ports do, or ship a plain zip.
   Prompt for ClaudeCopy

   GOAL: Build a regression set and a release package that holds no game code.
   READ FIRST: `CLAUDE.md`, `PROGRESS.md`, `tests/regress/`, https://github.com/tools81/voyeur-static-recomp (README, release notes, for design only)
   FENCE: Edit only `tests/regress/`, `tools/regress.bat`, `tools/package.ps1` and `installer/`. Do not edit `runtime/` or `gen/`. Do not change expected hashes of existing cases.
   CHECK: Run `tools\regress.bat` and `powershell -ExecutionPolicy Bypass -File tools\package.ps1`. Done means every regression case prints PASS, and the packager lists the zip contents and confirms no module, stream or `gen/` file is inside.
   BUDGET: Stop after 90 minutes.
   IF BLOCKED: Stop. Name the case that fails and its first differing frame.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: regress output and the zip listing. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenAll regression cases pass on a clean clone, and the release zip holds no game code or disc data.

   Proof this works: Voyeur (CD-i) static recompilation, Hotel Mario Decomp, Hotel Mario Static Recomp, https://jrsoftware.org/isinfo.php

Path B: Full decomp for porting

First you find which compiler built the game. Mac-built games used Apple MPW C 3.0, which runs in a Mac emulator, so their C can match byte for byte. Microware-built games need a compiler nobody here had. For those you rebuild the module from assembly first, then write C checked by tests against the running game. Last, you move the C onto a PC runtime and then onto other systems.

1. Find out which compiler built the game

   You cannot match C without the original compiler. So you find it first. Each compiler leaves marks in the code. You test small functions with each candidate and keep the one that matches.

   • Look for MacsBug names after each rts and globals reached through register A5 at negative offsets. Those mean Apple MPW C.
   • A .stb symbol module means the Microware linker was used. a5 frames, arguments in d0 and d1, and calls to the cio trap library on trap #13 point to Microware C 3.2.
   • Calls to the CSL shared library point to Microware Ultra C. A 1996 user guide, "Preparing for Ultra C", says CSL is to Ultra C what CIO is to C 3.2.
   • Check library names too. HotelMario-Decomp used old _ev_* names and _T$ maths helpers to pick C 3.2.
   • For MPW C, test versions 3.0 to 3.3.1. Only 3.0 matched Link. C 3.1 compares chars as longs. C 3.2 and later clean the stack with addq.w, not addq.l.
   • Write the result and the proof into docs/COMPILER.md.
   Prompt for ClaudeCopy

   GOAL: Name the compiler (and version, if you can) that built <MODULE> of <GAME>, with proof.
   READ FIRST: `SCOPE.md`, `notes/functions.csv`, a Ghidra listing of 10 small functions (I will give addresses), https://github.com/ByteDecompiler/link-faces-of-evil/blob/main/docs/emulator.md , https://icdia.co.uk/microware/index.html
   FENCE: Create only `docs/COMPILER.md`. No code. Do not download any compiler, ROM or disk image.
   CHECK: Run `python tools/analyze.py <MODULE_INDEX>` and open `build/listing_<MODULE>.asm`. Done means every address in COMPILER.md shows the instruction you quote there, COMPILER.md names one compiler family, lists at least 3 code marks with addresses, and lists what would prove the exact version.
   BUDGET: Stop after 60 minutes.
   IF BLOCKED: Stop. Say which two compilers you cannot tell apart, and what test would decide.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: addresses and instruction lines. 3) Files changed. 4) Risks. 5) New parking-lot items.

   Done whendocs/COMPILER.md names the compiler family with at least three code marks and their addresses.

   Proof this works: Hotel Mario Decomp, https://github.com/ByteDecompiler/link-faces-of-evil, https://discmaster.textfiles.com/view/11868/2014.01.www.rtsi.com.tar/www.rtsi.com/OS9/MM1/TELECOM/linkup12_maint.lzh/ucc.doc

2. Get the compiler running, or choose tested C

   For MPW games, you run the compiler inside Basilisk II, a Mac emulator, with no clicking. For Microware games, you likely cannot get the compiler. Then you choose non-matching C that is checked by tests instead. Write the choice in SCOPE.md.

   • MPW route, in WSL: build Basilisk II from kanjitalk755/macemu with SDL2 and no GTK: in macemu/BasiliskII/src/Unix run ./autogen.sh --with-gtk=no, then make.
   • You also need a Mac ROM that you own. ByteDecompiler used one from a Quadra 630. You need a Mac disk image too, with System 7.5.3, MPW 3.3 and MPW C 3.0 on it.
   • Run one compile job with a script, like ByteDecompiler's emu/mpwrun.sh <job folder>. One run takes about 12 seconds there.
   • Keep a clean copy of the Mac disk. A forced stop leaves the disk dirty, and the next start halts at a dialog.
   • Microware route: HotelMario-Decomp did not have the C 3.2 compiler. Its C is checked only for being the same as the assembly.
   • os9exec runs OS-9/68000 programs on Windows. Whether it runs a Microware compiler you own was not tested.
   • Write the choice, matching or tested, into SCOPE.md and get the owner's approval.
   Prompt for ClaudeCopy

   GOAL: Compile one tiny test function with <COMPILER> and compare its bytes with the same function in the game.
   READ FIRST: `docs/COMPILER.md`, https://github.com/ByteDecompiler/link-faces-of-evil/blob/main/docs/emulator.md , https://github.com/kanjitalk755/macemu
   FENCE: Edit only `emu/` scripts, `tools/compile_one.sh` and `docs/COMPILER.md`. Never commit a Mac ROM, a system disk, MPW or any compiler file. Do not download any of them; I supply them at <ABSOLUTE_PATH_TO_EMU_FILES>.
   CHECK: Run `bash tools/compile_one.sh test/<FUNC>.c`. Done means it prints the compiled bytes and a byte compare with the game's function at <ADDRESS> that says SAME or names the first different byte.
   BUDGET: Stop after 2 hours.
   IF BLOCKED: Stop. Say which file or step is missing. Do not swap in a different compiler.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the compare output. 3) Files changed. 4) Run time per job. 5) New parking-lot items.

   Done whenOne test function compiles with no clicks, and the script prints a byte compare against the game's function.

   Proof this works: https://github.com/ByteDecompiler/link-faces-of-evil/blob/main/docs/emulator.md, Hotel Mario Decomp, https://github.com/peacedudes/os9exec

3. Rebuild the module byte for byte

   Before any C, you rebuild the module from assembly and prove it matches. Each function becomes one assembly file. A script joins them, fixes the header checks and compares the SHA-1. This is your one check for all of Path B.

   • In WSL, build vasm from the mirror: make CPU=m68k SYNTAX=mot. The tool is called vasmm68k_mot.
   • Write tools/split.py. It writes asm/<name>.s per function and data to bin/. Both folders stay out of git.
   • Reassemble each instruction and compare it with the original bytes. HotelMario-Decomp checks every one this way.
   • Write tools/build.py. It joins the pieces, recomputes the OS-9 header parity and CRC-24, and checks the SHA-1.
   • Make it print one clear line, like ByteDecompiler's OK: byte-identical to the original, or list each DIFFERS function.
   Prompt for ClaudeCopy

   GOAL: Rebuild <MODULE> from per-function assembly so its SHA-1 matches the original.
   READ FIRST: `docs/COMPILER.md`, `notes/functions.csv`, https://github.com/StarWolf3000/vasm-mirror
   FENCE: Edit only `tools/split.py`, `tools/build.py` and `config/`. `asm/`, `bin/` and `build/` are made by scripts and stay out of git. Never edit the expected SHA-1.
   CHECK: Run `python3 tools/split.py && python3 tools/build.py`. Done means it prints `OK: byte-identical to the original`. Then change one byte in one `.s` file and show it prints the function as DIFFERS.
   BUDGET: Stop after 3 hours or 5 failed rebuilds in a row.
   IF BLOCKED: Stop. Paste the first differing offset and the instruction there.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the OK line and the DIFFERS line from the test break. 3) Files changed. 4) Pieces that are data, not code. 5) New parking-lot items.

   Done whenpython3 tools/build.py prints the byte-identical line, and a deliberate one-byte change makes it fail.

   Proof this works: Hotel Mario Decomp, https://github.com/ByteDecompiler/link-faces-of-evil, https://github.com/StarWolf3000/vasm-mirror

4. Set up names, globals and the ledger

   Matching C needs to know where every global and call target lives. You write config files for these. You also set up a Ghidra project with the names applied. The ledger now tracks each function as asm, matching or tested.

   • Write config/functions.txt with every piece in module order, and config/symbols.txt with globals and their offsets.
   • For MPW games, write config/jumptable.txt. A jsr N(a5) call goes through the jump table to another segment.
   • Put every global in include/game.h as extern, with its A5 offset in a comment.
   • Sort the functions by size. ByteDecompiler lists them with tools/scripts/gamefuncs.py ... --list, smallest first.
   • Write a script that loads the names into Ghidra. ByteDecompiler uses tools\ghidra_setup.ps1 for this.
   • Add a status column to notes/functions.csv: asm, matching, tested or blocked.
   Prompt for ClaudeCopy

   GOAL: Write the config files and headers so any function can be built from C by name.
   READ FIRST: `notes/functions.csv`, `docs/COMPILER.md`, https://github.com/ByteDecompiler/link-faces-of-evil/blob/main/CONTRIBUTING.md
   FENCE: Edit only `config/`, `include/game.h`, `tools/` name scripts and `notes/functions.csv`. Do not write any `src/*.c` yet. Do not rename a function that has a MacsBug or `.stb` name.
   CHECK: Run `python3 tools/build.py`. Done means it still prints the byte-identical line, and every global used by the 20 smallest functions has a `symbols.txt` line.
   BUDGET: Stop after 2 hours.
   IF BLOCKED: Stop. Name the global or call target you cannot place.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the build line and counts of names. 3) Files changed. 4) Unknowns left. 5) New parking-lot items.

   Done whenThe build still matches, and the ledger has a status column with every function set to asm.

   Proof this works: https://github.com/ByteDecompiler/link-faces-of-evil/blob/main/CONTRIBUTING.md, Hotel Mario Decomp

5. Match one function end to end

   You take one small function all the way: C file, compile, place, rebuild, check. This proves the whole chain before you run many workers. Start with a function of 10 to 30 instructions.

   • Make src/<name>.c with #include "game.h". ByteDecompiler keeps one function per file.
   • Run python3 tools/build.py. A function that compiles but does not match prints DIFFERS.
   • Add --diff to see the differing lines. Or use asm-differ, which supports m68k.
   • Read the matching tips in ByteDecompiler's CONTRIBUTING.md. Write operations in the same order as the game does. Start docs/MATCHING_TIPS.md with what you learn here.
   • On the Microware route, mark the function tested instead. Its check is the differential run from step 8.
   Prompt for ClaudeCopy

   GOAL: Turn <FUNC> at <ADDRESS> into C that builds to the same bytes.
   READ FIRST: `asm/<FUNC>.s`, `include/game.h`, `config/symbols.txt`, https://github.com/ByteDecompiler/link-faces-of-evil/blob/main/CONTRIBUTING.md
   FENCE: Edit only `src/<FUNC>.c`, `docs/MATCHING_TIPS.md`, plus new `extern` lines in `include/game.h` and `config/symbols.txt`. No inline assembly. Do not edit `tools/build.py`, `asm/` or the expected SHA-1.
   CHECK: Run `python3 tools/build.py`. Done means it prints the byte-identical line and lists <FUNC> as built from C.
   BUDGET: Stop after 5 meaningfully different attempts.
   IF BLOCKED: Stop. Paste the `--diff` output for your best attempt and your best guess at the cause.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the build output. 3) Files changed. 4) What you learned, for the tips file. 5) New parking-lot items.

   Done whenpython3 tools/build.py prints the byte-identical line with one function built from C.

   Proof this works: https://github.com/ByteDecompiler/link-faces-of-evil, https://github.com/simonlindholm/asm-differ

6. Match the rest in parallel

   Now many workers each take one function. Each works in its own git worktree. The lead merges one at a time and rebuilds after each merge. Easy functions go first. Sister games on the same engine can give you many functions for free.

   • Start workers with claude --worktree <name>. List small gitignored inputs in .worktreeinclude so each worktree can build.
   • Give each worker one function and its asm file path. Never give it the whole listing.
   • After each merge, run python3 tools/build.py on the main branch. A match in a worktree is not a match after merge.
   • Check sister games. Wand of Gamelon reused 280 of its 359 functions from the Link decomp.
   • Send functions that fail 5 times to the hard queue in the ledger.
   • Add every new compiler habit to docs/MATCHING_TIPS.md as a general rule, not a note about one function.
   Prompt for ClaudeCopy

   GOAL: As lead, pick the next <N> functions marked asm and give one to each worker.
   READ FIRST: `notes/functions.csv`, `PROGRESS.md`, `docs/MATCHING_TIPS.md`
   FENCE: Edit only `notes/functions.csv`, `PROGRESS.md` and merges of `src/*.c`. Workers edit only their own `src/<FUNC>.c`. No worker edits `include/game.h` without asking you first.
   CHECK: After each merge run `python3 tools/build.py`. Done means all merged functions build from C and the line says byte-identical.
   BUDGET: Each worker stops after 5 attempts. Stop the batch after <HOURS> hours.
   IF BLOCKED: Stop the batch. Report which merge broke the build and revert it.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the final build line. 3) Functions matched, failed and sent to hard. 4) New tips. 5) New parking-lot items.

   Done whenEvery merged function builds from C, and the build on the main branch prints the byte-identical line.

   Proof this works: https://github.com/ByteDecompiler/zelda-wand-of-gamelon, https://github.com/ByteDecompiler/link-faces-of-evil

7. Name everything and pull out the data

   Matching C with names like func_1234 is not a usable source. You name globals, structs and fields. You document the data files on the disc. Regional discs go into one source with a version header.

   • Name globals and fields after what the code does with them. Keep the game's own function names, typos included.
   • Put numbers that differ between regions in include/version.h, picked at build time.
   • Find each global's offset in other regions with a script, like ByteDecompiler's tools/port_symbols.py --version fr.
   • Write docs/data.md for the disc files, picture formats and save layout.
   • Write extractors for pictures and sound to folders outside git. Never commit what they write.
   Prompt for ClaudeCopy

   GOAL: Name the globals and struct fields used by <SUBSYSTEM> and document them.
   READ FIRST: `include/game.h`, `src/` files for <SUBSYSTEM>, `notes/functions.csv`
   FENCE: Edit only names and comments in `include/game.h`, `src/` files for <SUBSYSTEM>, and `docs/data.md`. Do not change code shape. Do not rename functions that have original names.
   CHECK: Run `python3 tools/build.py` for every version you support. Done means each prints the byte-identical line.
   BUDGET: Stop after 2 hours.
   IF BLOCKED: Stop. List the names you cannot work out, with the addresses that use them.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: each build line. 3) Files changed. 4) Names still unknown. 5) New parking-lot items.

   Done whenAll supported versions still match, and the subsystem has no placeholder names left.

   Proof this works: https://github.com/ByteDecompiler/link-faces-of-evil, Hotel Mario Decomp

8. Run the C on a PC runtime with tests

   Matching C still needs a CD-i to run. Now you build the C as a PC program on your Path A runtime. You compare it with the interpreter running the original code. For Microware games, this is the main check.

   • Compile src/*.c with your PC compiler into the Path A runtime, in place of the recompiled module.
   • Replace OS-9 calls with calls into your runtime. Keep the same behaviour and the same RAM layout at first.
   • Run scripted sessions with the C build and with --interp. Compare every frame and the WAV files.
   • HotelMario-Decomp swaps functions from assembly to C one at a time and keeps the port playable throughout.
   • Mark each function tested in the ledger only after a session that calls it passes the compare.
   Prompt for ClaudeCopy

   GOAL: Build <GAME> from `src/*.c` on the PC runtime and pass the regression set.
   READ FIRST: `CLAUDE.md`, `tests/regress/`, the runtime's module loader, `notes/functions.csv`
   FENCE: Edit only `port/` glue files and `CMakeLists.txt`. Do not change `src/*.c` logic: a fix there must keep `tools/build.py` matching. Never edit expected frame hashes.
   CHECK: Run `tools\regress.bat --c-build`. Done means every case gives the same frames and audio as the `--interp` reference, and `python3 tools/build.py` still matches.
   BUDGET: Stop after 3 failed fixes on one case.
   IF BLOCKED: Stop. Give the first differing field, the function running there and both RAM values.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: regress output and the build line. 3) Files changed. 4) Functions now marked tested. 5) New parking-lot items.

   Done whenThe C build passes every regression case against the interpreter, and the matching build still matches.

   Proof this works: Hotel Mario Decomp, Hotel Mario Static Recomp

9. Port it to a new system

   You put the CD-i parts behind a small interface: video, sound, disc and input. You fix byte order, because the 68000 is big-endian and most new systems are not. Then you build for the new system and run the same regression set.

   • Use SDL2 for window, input and sound, as HotelMario-Decomp does with SDL 2.32.10.
   • Swap bytes when the C reads big-endian data from the disc or from RAM tables.
   • Check every pointer stored in a 32-bit field. On a 64-bit PC a pointer does not fit.
   • HotelMario-Decomp builds for 3DS with devkitPro. It plays on a real New 3DS, but that build is not released.
   • Builds that embed translated game code cannot be shared. Plan a build-from-your-disc step for every target.
   • Run the regression set on the new system and compare its frames with the PC build.
   Prompt for ClaudeCopy

   GOAL: Build <GAME> for <TARGET> and pass the regression cases that do not need a mouse.
   READ FIRST: `CLAUDE.md`, `port/` interface headers, `tests/regress/`, <TARGET_SDK_DOCS>
   FENCE: Edit only `port/<TARGET>/` and the build file for <TARGET>. Do not edit `src/` logic or the PC port. Do not put game code or data in any release file.
   CHECK: Run the regression cases on <TARGET> or its emulator. Done means each case's frames match the PC build's frames.
   BUDGET: Stop after 3 hours on one failing case.
   IF BLOCKED: Stop. Name the first case that fails and whether the cause is byte order, pointer size or timing.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the frame compare. 3) Files changed. 4) Cases still failing. 5) New parking-lot items.

   Done whenThe new build passes the same regression cases as the PC build, with matching frames.

   Proof this works: Hotel Mario Decomp, https://github.com/libsdl-org/SDL/releases/tag/release-2.32.10

Tools you need

Skills and add-ons

Read any skill before you install it. A skill is a set of instructions that Claude will follow. See Tools and Skills for the full list and safety notes.

Claude setup for this system

Cut CD-i work by OS call and by function. On Path A, one unit is one missing call, one picture or sound bug, or one code gap. Each has a scripted run that shows it. On Path B, one unit is one function from the ledger. Every unit has one check: tools\check.bat with the interp compare, or python3 tools/build.py printing byte-identical. Keep disc images outside the repo and give Claude their absolute paths.

Which model and effort for each job

The model and effort names come from one shared table, so they stay the same on every guide. See Claude Setup for the reasons.

How many sessions at once

Lines for this project's CLAUDE.md

- Read `SCOPE.md` and `PROGRESS.md` at the start of every session.
- Never edit files in `gen/`. They are made from the disc. Fix `tools/gen.py`, `tools/analyze.py` or `runtime/`, then regenerate.
- Disc images live at `<ABSOLUTE_PATH_TO_DISCS>`. Never copy them, extracted modules, RAM dumps or frame dumps into the repo.
- Never download a game, BIOS, Mac ROM, compiler or disc image. Ask me.
- The one check is `tools\check.bat` (Path A) or `python3 tools/build.py` (Path B). No pasted output means not done.
- No stubs. An unknown OS call or register must stop the run with its number and address. Never return a made-up success.
- Report how much code ran in the interpreter. Never present interpreter fallback as recompiled code.
- Give the address and the Ghidra or listing lines for every claim about code. Ghidra draft C is a guess until checked against the assembly.
- Do not edit expected hashes, fuzz seeds, regression cases or the check scripts. Ask me first.
- `game.json` holds real facts about the game only. Do not use it to hide a recompiler bug.
- Write each new call number to `docs/CDI_NOTES.md` with the game address that proves it.
- Do not copy code from repos with no licence. Read them for ideas only.
- In a worktree, use absolute paths for discs and tools. Gitignored files are not copied in.
- Write side issues in `notes/parking-lot.md` and dead ends in `notes/findings.md`. Do not act on them.
- Do not commit or push without my OK. Start every report with DONE, PARTIAL or BLOCKED.

Keep the context small

• Never let Claude read gen/. Hotel Mario alone has 34,045 translated instructions. Have it grep for one address instead.
• Give Claude 50 lines of saves/recomp.log, not the whole log. Turn on one trace option at a time.
• Pass a Ghidra address, not pasted assembly. Let the MCP server or a subagent fetch it.
• Keep docs/CDI_NOTES.md as the one place for call numbers, so Claude does not search the Green Book each time.
• On Path B, give each worker its function's asm/<name>.s path and its ledger row only.
• Add Read deny rules for gen/**, extracted/**, saves/** and the disc folder.
• Clear the chat after each unit. The ledger and the findings file carry the state.

More prompts for this system

Each step above has its own prompt. These extra prompts cover the rest of the work. Fill in the parts in <ANGLE_BRACKETS>.

GOAL: Tell me if <GAME> (<REGION>) suits Path A, Path B, or both, and draft SCOPE.md.
READ FIRST: The disc SHA-1 (I will paste it), the list of files on the disc from `python tools/cdi_extract.py --list <ABSOLUTE_PATH_TO_CUE>`, https://github.com/ByteDecompiler , https://github.com/tools81
FENCE: Create only `SCOPE.md` and `notes/prior-work.md`. No code. Do not copy or download any disc, BIOS or ROM.
CHECK: Run `certutil -hashfile <ABSOLUTE_PATH_TO_BIN> SHA1` and `python tools/cdi_extract.py --list <ABSOLUTE_PATH_TO_CUE>`. Done means SCOPE.md matches both outputs and lists the disc SHA-1, region, module names, `.stb` files found, video cartridge yes or no, compiler guess with proof, prior work with links, the chosen path, the first milestone with its check, and an out-of-scope list.
BUDGET: 60 minutes.
IF BLOCKED: Stop. Say what you could not check.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: tool outputs. 3) Files changed. 4) Risks you see. 5) New parking-lot items.

GOAL: List every function in <MODULE> with address, size, name and how the name was found.
READ FIRST: `game.json`, <ABSOLUTE_PATH_TO_EXTRACTED>/<MODULE>, <MODULE>.stb if present, `docs/CDI_NOTES.md`
FENCE: Edit only `tools/analyze.py` and `notes/functions.csv`. Read-only everywhere else. No listings or module bytes in the repo.
CHECK: Run `python tools/analyze.py <MODULE_INDEX>`. Done means the ledger has one row per function, names come from `.stb` or MacsBug where present, and coverage of the code area is printed as a percent.
BUDGET: 90 minutes, or 3 tries at one pattern with no gain.
IF BLOCKED: Stop. Name the address range you cannot classify.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: coverage line and row count. 3) Files changed. 4) Patterns still missed. 5) New parking-lot items.

GOAL: Handle OS call <CALL_NAME_OR_NUMBER> that stops <GAME> at field <FIELD>.
READ FIRST: The last 50 lines of `saves/recomp.log`, `docs/CDI_NOTES.md`, the game's wrapper at <ADDRESS>, https://icdia.co.uk/docs/funcspec.html
FENCE: Edit only `runtime/os9.c` or `runtime/cdfm.c`, and `docs/CDI_NOTES.md`. Never edit `gen/`. No handler that returns success without doing the work.
CHECK: Run `game.exe --headless --frames <FIELD+600> --dump 60` and `tools\check.bat`. Done means the run passes field <FIELD> with no fatal line and check.bat prints PASS.
BUDGET: Stop after 3 failed tries or 45 minutes.
IF BLOCKED: Stop. Give the call, its registers and what the Green Book says.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: log tail and check output. 3) Files changed. 4) The call number and its proving address. 5) New parking-lot items.

GOAL: Make the recompiler find the code at <ADDRESS> by teaching `analyze.py` the pattern that reaches it.
READ FIRST: The fallback lines in `saves/recomp.log`, the Ghidra listing around the caller at <CALLER_ADDRESS>, `tools/analyze.py`
FENCE: Edit only `tools/analyze.py`. Do not add the address to `extra_entries` unless you prove no general pattern reaches it. Never edit `gen/`.
CHECK: Run `build.bat` and `tools\check.bat`. Done means the fallback for <ADDRESS> is gone, coverage did not fall, and check.bat prints PASS.
BUDGET: Stop after 3 tries or 60 minutes.
IF BLOCKED: Stop. Show the instructions that reach the address and say why no rule fits.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: coverage before and after. 3) Files changed. 4) The pattern you added. 5) New parking-lot items.

GOAL: Write `src/<FUNC>.c` so `tools/build.py` builds <FUNC> from C with the same bytes.
READ FIRST: `asm/<FUNC>.s`, `include/game.h`, `config/symbols.txt`, `docs/MATCHING_TIPS.md`
FENCE: Edit only `src/<FUNC>.c`, plus new `extern` lines in `include/game.h` and `config/symbols.txt`. No inline assembly. Never edit `tools/`, `asm/` or the expected SHA-1.
CHECK: Run `python3 tools/build.py`. Done means it prints the byte-identical line and <FUNC> is no longer listed as DIFFERS.
BUDGET: 5 meaningfully different attempts, each in a new file `scratch/<FUNC>_<N>.c`.
IF BLOCKED: Stop. Paste the `--diff` of your best attempt and the cause you suspect.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: build output. 3) Files changed. 4) A general tip for `MATCHING_TIPS.md`, if any. 5) New parking-lot items.

GOAL: Pick the next <N> units from the ledger and start one worker per unit, each in its own worktree.
READ FIRST: `notes/functions.csv` or the open-units list in `PROGRESS.md`, `CLAUDE.md`
FENCE: Edit only `PROGRESS.md` and the ledger status column. Each worker edits only the files its card names. Do not give two workers the same runtime file.
CHECK: After each worker reports, rerun its check on the main branch after merge. Done means each merged unit passes there, and the ledger shows the new status.
BUDGET: Stop the batch after <HOURS> hours or 2 broken merges.
IF BLOCKED: Stop. Revert the bad merge and report it.
OTHER PROBLEMS: Collect workers' parking-lot items into `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: check output after each merge. 3) Units done, failed and sent to hard. 4) Ledger counts. 5) New parking-lot items.

GOAL: Find the cause of <SYMPTOM> at field <FIELD>. Do not fix it yet.
READ FIRST: The run command <COMMAND>, the last 50 lines of `saves/recomp.log`, `docs/CDI_NOTES.md`, `notes/findings.md`
FENCE: Read-only, except new notes in `notes/findings.md`. You may run `--trace`, `--ramdump <FIELD>`, `--watch <ADDR>` and `--interp` runs.
CHECK: Run <COMMAND> and <COMMAND> `--interp` in two fresh folders, then compare the dumps with `fc /b`. Done means you show the first field where the two runs differ, or prove they do not differ, and name the code or runtime part that causes it, with an address.
BUDGET: 60 minutes.
IF BLOCKED: Stop. List what you ruled out and what data you still need.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: trace lines or RAM bytes. 3) Files changed. 4) The cause and a proposed fix. 5) New parking-lot items.

GOAL: Check that the work in commits <RANGE> is real.
READ FIRST: `git diff <RANGE>`, `CLAUDE.md`, `PROGRESS.md`
FENCE: Read-only. Do not fix anything. Write findings only to `notes/verify-<DATE>.md`.
CHECK: Rerun `tools\check.bat` or `python3 tools/build.py` on a clean checkout. Done means you report the check output and whether the diff touches `gen/`, expected hashes, seeds, regression cases, check scripts, or adds a handler that fakes success, or more interpreter use.
BUDGET: 45 minutes.
IF BLOCKED: Stop. Say what you could not run.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: check output. 3) Files changed (should be only the notes file). 4) Each problem with file and line. 5) New parking-lot items.

GOAL: Give me the status of <GAME> in numbers.
READ FIRST: `PROGRESS.md`, `notes/functions.csv`, `saves/recomp.log` from the last regression run, `notes/parking-lot.md`
FENCE: Read-only.
CHECK: Run `tools\check.bat` (Path A) or `python3 tools/build.py` (Path B) and paste the summary lines. Done means you report: coverage percent, interpreted share, open OS calls, regression cases passing out of total, and on Path B functions matched, tested and asm, all copied from files or fresh command output.
BUDGET: 15 minutes.
IF BLOCKED: Stop. Say which number you could not get.
OTHER PROBLEMS: None; list them in the report.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the numbers and where each came from. 3) Files changed: none. 4) Top three risks. 5) Parking-lot count.

GOAL: Write what the next session needs into the ledger files.
READ FIRST: This session's work, `PROGRESS.md`, `notes/findings.md`
FENCE: Edit only `PROGRESS.md`, `notes/findings.md` and `notes/parking-lot.md`.
CHECK: Run `git diff --stat` and `git status`. Done means only the three files above changed, and PROGRESS.md has: what works now with the proving command, the unit in progress and its state, the next three units, and dead ends added to findings.md.
BUDGET: 15 minutes.
IF BLOCKED: Stop. Say what you could not confirm.
OTHER PROBLEMS: Add them to `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the new PROGRESS.md section. 3) Files changed. 4) Next three units. 5) New parking-lot items.

GOAL: Give me a plain answer on whether <GOAL> can be done, and what the options are.
READ FIRST: `SCOPE.md`, `docs/COMPILER.md`, `notes/findings.md`, the reports of failed tries
FENCE: Read-only, except a new section in `notes/findings.md`.
CHECK: Run the last failing check once more and paste its output. Done means you answer CAN, CANNOT or UNKNOWN, with the facts behind it, and list 2 or 3 options with their cost in time and what each gives up.
BUDGET: 30 minutes.
IF BLOCKED: Say UNKNOWN and what would decide it.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) CAN, CANNOT or UNKNOWN. 2) Proof: the facts. 3) Files changed. 4) Options. 5) New parking-lot items.

GOAL: Ask me before you leave the fence for <CHANGE>.
READ FIRST: `SCOPE.md`, the current task card
FENCE: Make no change. Write only the request.
CHECK: Run `git status`. Done means it shows no changed files, and you give me: the change, why the current unit needs it, the files it touches, the risk to the checks, and a smaller choice if one exists.
BUDGET: 10 minutes.
IF BLOCKED: Stop and say so.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) BLOCKED (waiting for my answer). 2) Proof: the facts. 3) Files changed: none. 4) The request. 5) New parking-lot items.

Keep Claude on task

These are the detours Claude tends to take on this system, and the rule that stops each one. The full method is on Stay on Task.

Problems other projects hit

How long it takes

What makes it faster or slower

• Whether you reuse a design. The tools81 ports shipped ten games in about three weeks once the first one worked.
• How many OS calls the game uses. Zelda's Adventure needed many more than Link, such as extra processes and events.
• Extra hardware. The MPEG cartridge, a cdi_bpsys extension or PAL timing each add runtime work.
• Code loaded at run time and self-modifying code. Each needs interpreter handling and more test runs.
• The compiler, on Path B. MPW C 3.0 runs in a Mac emulator. The Microware compilers were not found.
• Sister games. Wand of Gamelon reused 280 of 359 matched functions from Link.
• Your review time. Each unit needs a look at its proof, and that is your 10 to 15 hours a week.

The facts behind these numbers

Projects reviewed (11)

RecompLauncher lists fewer than 10 games for CD-i: 10 projects for 9 games. All 10 were reviewed. One project came from outside it (Voyeur), which makes 10 games. Eight more CD-i game repos were found, all for games already covered. Some of them appear here as outside evidence.

What each project teaches

What we could not check

• How much AI the tools81 ports used. Only the store flags them; the repos say nothing and show one commit each.
• Whether HotelMario-Decomp or the ByteDecompiler decomps used AI. None of them says.
• How long the two ByteDecompiler matching decomps really took. Their public history is one to three commits.
• Whether a Microware OS-9 C 3.2 or Ultra C compiler can be found today, or whether os9exec can run one.
• Whether ghidra-os9 builds against Ghidra 12.2. Its last change was in 2022.
• GhidraMCP 2.0 targets Ghidra 12.1.4, while the newest Ghidra is 12.2. Mixing them was not tried.
• Whether chdman extractcd handles the byte-swapped track of a CD-i Ready disc. The Apprentice wrote its own reader for this.
• Whether asm-differ works with these OS-9 modules. No reviewed CD-i project used it.
• The scripts tools\check.bat, tools\regress.bat, tools/diffrun.py, tools/compile_one.sh and the headless flag names are suggestions modeled on the tools81 READMEs. You write them.
• Which CD-i BIOS each emulator needs for a given game. Never download one; dump your own player.
• The tools81 repos and HotelMario-Decomp state no licence, so reusing their code is not allowed by default.
• The CD-i release year (1991) and CPU clock (15.5 MHz) come from Wikipedia only.
• The winget line with --override for the C++ workload was put together from Microsoft docs. It was not run during this check.
• Whether the winget MAME package includes chdman. The MAME docs list it as a tool that comes with MAME.
• No step, prompt or script in this guide was run on a real CD-i disc during the check. Commands were checked against each tool's docs only.
• The Voyeur card says its release date is unknown. The live repo shows release v1.0.0 on 2026-11-12, so the guide uses that.

Sources

• Hotel Mario static recomp README (tools81)
• HotelMario-Decomp README (antonretro)
• cdirecomp README, AGENTS.md and PRINCIPLES.md
• HotelMarioRecomp README
• Link: The Faces of Evil decompilation
• Link decomp: how the compiler was found
• Link decomp: CONTRIBUTING and matching tips
• Zelda: The Wand of Gamelon decompilation
• Zelda CD-i native recompilation (Megamil-Decomp)
• ICDIA: CD-i Full Functional Specification (Green Book)
• ICDIA: CD-i technical documentation (MCD212, SCC68070)
• ICDIA: Microware OS-9 documents
• MAME CD-i driver source
• MAME chdman documentation
• CeDImu README and manual
• ghidra-os9 Ghidra extension
• os9exec README
• Musashi README
• vasm mirror README
• GhidraMCP README
• CD-i (Wikipedia)
• Ghidra README and releases (JDK 25)
• Basilisk II build notes (kanjitalk755/macemu)
• Install WSL (Microsoft Learn)
• Visual Studio Build Tools workload ids
• Visual Studio command-line install switches
• Claude Code worktrees and .worktreeinclude
• Preparing for Ultra C (1996 user guide, CIO and CSL)