monorepo: one repository for the decoders, the port and the corpus

Merges the Godot port into the reverse-engineering repository, preserving both
histories -- 1019 commits of corpus plus the port's 31, brought in by subtree
merge and then moved into place so git can follow each file across the rename.

The reason is not tidiness. The two-repo split forced the exporter to depend on
the decoders by pinned revision, and that created a whole class of failure that
now disappears: a sha reachable only from a topic branch, orphaned by a
squash-merge, breaking a fresh checkout silently at build time. It also forced a
live read-only mount of one agent's working tree into another's container, which
is why a contract file could move mid-iteration. With a path dependency, a
decoder change and the exporter change it requires land in the same commit or
not at all.

Canary stays separate: it is a fork tracking upstream.

New structure for the long term:

  docs/game/     how the game is NAVIGATED -- menus, modals, prompts, alerts,
                 and in-game flight. Written so nobody rediscovers it. Mostly
                 open questions on purpose; the in-game tutorials are the
                 resource for the flight half.
  docs/port/MODDING.md
                 modding as a constraint on the exporter TODAY, not a later
                 feature: one logical asset in one file (the disc splits nearly
                 everything, and resolving that is the exporter's job), names a
                 person recognises, PNG/OGG/OGV/JSON only, base-and-overrides so
                 re-exporting is always safe, provenance in every file.
  data/base + data/mods
                 generated tree and drop-in overrides, both gitignored
  exchange/      transient inter-agent files, deliberately outside history
  docs/agents/   the team protocol

Both the README and the navigation doc lead with the correction that cost the
most: the oracle is the real game under Xenia Canary. Reborn's renderer is a
hypothesis under test, it has been wrong, and treating it as ground truth
propagated into three documents and both agents before a human caught it.

Scripted modding stays possible without being built: no screen name is hardcoded
in GDScript and there is no native code in port/, which is what Godot Mod Loader
needs to be able to substitute behaviour later.

.gitignore

@@ -21,3 +21,14 @@ Thumbs.db
 # Trunk build output
 dist/
 __pycache__/
+
+# ── The port ────────────────────────────────────────────────────────────────
+# Generated from the user's own disc. This repo stays clean-room: code, schemas,
+# authored mappings and documentation only -- never game content.
+/data/base/
+# Transient inter-agent files. Deliberately outside history: they are working
+# artefacts with provenance in their manifest, not results.
+/exchange/
+!/exchange/.gitkeep
+.godot/
+port/.godot/

Cargo.toml

@@ -3,6 +3,7 @@ members = [
     "crates/sylpheed-formats",
     "crates/sylpheed-viewer",
     "crates/sylpheed-cli",
+    "crates/sylpheed-export",
 ]
 resolver = "2"
 
@@ -11,7 +12,7 @@ version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 authors = ["Project Sylpheed Reborn Contributors"]
-repository = "https://github.com/sylpheed-reborn/sylpheed-reborn"
+repository = "https://git.mc02.dev/fabi/Sylpheed"
 
 [workspace.dependencies]
 # ── Format / parser crates ──────────────────────────────────────────────────

README.md

@@ -1,225 +1,66 @@
-# Project Sylpheed: Arc of Deception — Reborn
+# Sylpheed
 
-A clean-room, open-source reimplementation of **Project Sylpheed: Arc of Deception** (Xbox 360, 2006).
+A clean-room reverse engineering and port project for **Project Sylpheed: Arc of
+Deception** (Xbox 360, 2007).
 
-Built with **Rust** and the **Bevy** game engine. Runs natively on Windows, macOS, and Linux, and in the browser via WebAssembly.
+Three things live here, in one repository so that a change spanning them lands as
+one commit:
 
-> **Legal note:** This project contains no original game code or assets. You must own a legitimate copy of Project Sylpheed to use this engine. Assets remain the intellectual property of SETA Corporation / Square Enix.
+| | |
+|---|---|
+| **The decoders** | `crates/sylpheed-formats` — the disc's formats, read and verified disc-wide |
+| **The port** | `port/` — a Godot 4 project, plus `crates/sylpheed-export` which converts a disc into the open asset tree it reads |
+| **The corpus** | `docs/re/` — what has been reverse engineered, with its evidence, its retractions and its dead ends |
 
----
+**You need your own copy of the game.** No game content is in this repository and
+none ever will be. The exporter reads the disc you supply.
 
-## Current Status: Milestone 1 — Asset Explorer
+## The oracle is the real game
 
-- [x] XISO disc image reading via `xdvdfs`
-- [x] Xbox 360 texture de-tiling (Morton / Z-order)
-- [x] XPR2 texture container parsing
-- [x] Bevy custom `AssetLoader` for `.xpr` textures
-- [x] Orbit camera viewer
-- [x] CLI tools: extract, list, sniff, texture info, texture export
-- [x] GitHub Actions CI (Windows + macOS + Linux + WASM)
-- [x] WASM / web build target
-- [ ] Mesh format (reverse engineering in progress)
-- [ ] Audio format (XMA → PCM pipeline)
-- [ ] Mission data format
+> `sylpheed-cli` and the Explorer are **tools for verifying our decoding**. They
+> are hypotheses under test and they have been wrong. When something must be
+> checked against the truth, the truth is **the game running in Xenia Canary**,
+> captured — not any renderer of ours.
 
----
+This is stated first because getting it backwards is the most expensive mistake
+this project has made.
 
-## Repository Structure
+## Layout
 
 ```
-sylpheed-reborn/
-└── sylpheed-viewer/        ← Milestone 1: asset explorer (Rust/Bevy workspace)
-    ├── Cargo.toml          ← Workspace root
-    ├── crates/
-    │   ├── sylpheed-formats/   # Format parsers — no Bevy dependency
-    │   │   ├── xiso.rs         # XISO / XDVDFS disc image reader
-    │   │   ├── texture.rs      # XPR2 container + DXT de-tiling (Morton)
-    │   │   ├── vfs.rs          # Virtual filesystem + magic-byte sniffer
-    │   │   ├── mesh.rs         # Mesh parser (stub — RE in progress)
-    │   │   └── audio.rs        # Audio parser (stub — XMA TODO)
-    │   │
-    │   ├── sylpheed-viewer/    # Bevy application
-    │   │   ├── lib.rs          # App setup + WASM entry point
-    │   │   ├── main.rs         # Native binary entry point
-    │   │   ├── asset_loader.rs # Custom Bevy AssetLoaders
-    │   │   ├── camera.rs       # Orbit camera (LMB orbit, RMB pan, scroll zoom)
-    │   │   └── ui.rs           # egui file browser + RE notes panel
-    │   │
-    │   └── sylpheed-cli/       # Command-line tools
-    │       └── main.rs         # extract / list / sniff / texture info commands
-    │
-    ├── assets/             ← Extracted game files (gitignored)
-    ├── .github/workflows/
-    │   └── ci.yml          # CI: Windows + macOS + Linux + WASM
-    ├── Trunk.toml          # WASM build configuration
-    └── justfile            # All build recipes
+crates/
+  sylpheed-formats/   the decoders. Disc-wide verified; the corpus is its spec
+  sylpheed-cli/       headless tools -- render a screen, dump a table, probe audio
+  sylpheed-viewer/    the Explorer: a human's window onto the disc. STATIC data only
+  sylpheed-export/    disc -> the open, moddable asset tree
+port/                 the Godot 4 project. Reads open formats ONLY
+authored/             decisions that are NOT on the disc, each with its reason
+data/
+  base/               generated by the exporter. Gitignored, never hand-edited
+  mods/               drop-in overrides. Yours
+docs/
+  re/                 the corpus: findings, refutations, method traps
+  game/               how the game is navigated -- menus, modals, flight
+  port/               the port's mission, its handoff contract, modding rules
+  agents/             how the agent team works together
+tools/                capture harnesses, probes, the share tool
+exchange/             transient inter-agent files. NOT in git
+docker/               the agent containers
 ```
 
----
+## Where to start
 
-## Getting Started
+* [`docs/re/INDEX.md`](docs/re/INDEX.md) — what is decoded
+* [`docs/re/REFUTED.md`](docs/re/REFUTED.md) — what has been tested and died
+* [`docs/re/METHOD.md`](docs/re/METHOD.md) — traps this project has already paid for
+* [`docs/game/navigation.md`](docs/game/navigation.md) — how the game is navigated
+* [`docs/port/MODDING.md`](docs/port/MODDING.md) — why the asset tree looks the way it does
 
-### Prerequisites
+Xenia Canary is a **separate** repository: it is a fork tracking upstream, and it
+carries our instrumentation.
 
-```bash
-# Install Rust
-curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+## Conventions
 
-# Install just (task runner)
-cargo install just
-
-# For web builds only
-cargo install trunk
-rustup target add wasm32-unknown-unknown
-```
-
-#### Linux — Bevy system dependencies
-
-```bash
-sudo apt-get install -y \
-  libasound2-dev libudev-dev libwayland-dev \
-  libxkbcommon-dev libx11-dev libxi-dev pkg-config
-```
-
-### Step 1 — Extract your disc
-
-```bash
-cd sylpheed-viewer
-
-# Extract using the CLI tool
-just extract /path/to/project_sylpheed.iso
-
-# Or manually with xdvdfs
-cargo install xdvdfs-cli
-xdvdfs unpack project_sylpheed.iso ./assets/
-```
-
-### Step 2 — Run the viewer
-
-```bash
-cd sylpheed-viewer
-
-just run          # Native viewer
-just web          # WASM dev server → http://localhost:8080
-```
-
-The asset viewer opens an orbit camera scene. Use the left panel to browse extracted game files. Click a `.xpr` file to preview it as a texture.
-
----
-
-## Build Commands
-
-All commands run from the `sylpheed-viewer/` directory.
-
-```bash
-just run              # Run the native viewer (debug)
-just run-dev          # Run with hot-reloading
-just build-native     # Build native release binary
-just web              # WASM dev server at localhost:8080
-just build-web        # WASM release build → ./dist/
-
-just extract game.iso # Extract an ISO to ./assets/
-just sniff            # Identify file formats in ./assets/
-just sniff-unknown    # Show only unrecognised formats (RE focus)
-
-just test             # Run all tests
-just ci               # Full CI: fmt + lint + test + WASM check
-```
-
----
-
-## Technology Stack
-
-| Layer | Choice | Reason |
-|-------|--------|--------|
-| Language | **Rust** | Memory safety, performance, cross-platform |
-| Game engine | **Bevy 0.15** | ECS-first, WASM-native, data-driven |
-| XISO reading | **xdvdfs** | Pure Rust, reads Xbox 360 disc images |
-| Binary parsing | **binrw** | Derive-macro based, ideal for RE work |
-| Web bundler | **Trunk** | Bevy's standard WASM build tool |
-| CLI | **clap** | Asset extraction and inspection tools |
-| Debug UI | **bevy_egui** | In-viewer asset browser and RE notes panel |
-
----
-
-## Key Architectural Decisions
-
-**`sylpheed-formats` has zero Bevy dependency.** All binary format parsers live here and are testable with plain `cargo test`. Bevy integration is a thin layer on top in `sylpheed-viewer`.
-
-**WASM is a first-class target.** XISO reading is gated behind `#[cfg(not(target_arch = "wasm32"))]` since the browser can't read local files. On the web, assets must be pre-extracted and served over HTTP.
-
-**Modding is designed in from the start.** The virtual filesystem (`vfs.rs`) is the single choke point for all asset reads — a mod loader only needs to intercept that one layer to override any file.
-
----
-
-## Reverse Engineering Notes
-
-### Known file formats
-
-| Path pattern | Format | Status | Notes |
-|---|---|---|---|
-| `*.XPR`, `*.XPR2` | XPR2 texture | ✅ Parsing | DXT1/3/5, DXN, Morton de-tiling done |
-| `DEFAULT.XEX` | Xbox EXE 2 | 🔬 Study | Main executable — load in Ghidra (PPC BE) |
-| `*.XWB`, `*.XSB` | XACT audio | ⏳ TODO | Wave/sound banks; audio is XMA codec |
-| `*.pak`, `*.p00` | SETA archive | ⏳ Unknown | Paired header/data format |
-| mesh files | Unknown | ⏳ TODO | Run `just sniff-unknown` to find candidates |
-
-### RE workflow
-
-```bash
-# 1. Extract and map the disc
-just extract game.iso
-just sniff-unknown   # shows hex magic bytes of unknown files
-
-# 2. Hex-inspect candidates
-#    Groups of 12 bytes at offsets: likely f32 XYZ vertices
-#    Groups of 6 bytes:             likely u16 triangle indices
-
-# 3. Cross-reference in Ghidra
-#    Load DEFAULT.XEX with PowerPC Big-Endian processor
-#    Search string refs to file extensions → find load functions
-
-# 4. Implement parser
-#    Add binrw #[derive(BinRead)] struct in sylpheed-formats/src/mesh.rs
-#    cargo test -p sylpheed-formats
-```
-
-### Next steps (Milestone 2)
-
-1. **Mesh format** — fingerprint with `sniff-unknown`, implement `mesh.rs`
-2. **Audio** — parse XWB headers, batch-convert XMA to WAV via `ffmpeg`
-3. **Mission data** — format unknown; starts after mesh/texture loading works
-4. **Flight model** — document by playing the original; implement as Bevy system
-
----
-
-## Constraints
-
-1. **Never copy decompiled or disassembled game code** — reimplement behavior through observation only.
-2. **Assets stay gitignored** — `assets/` and `*.iso` are excluded. Never commit game files.
-3. **Keep `sylpheed-formats` Bevy-free** — parsers must be testable without a GPU.
-4. **WASM must always compile** — CI enforces `cargo check --target wasm32-unknown-unknown`.
-5. **`justfile` is the source of truth** for build commands — add new recipes there.
-
----
-
-## Milestone Roadmap
-
-| Milestone | Goal | Status |
-|---|---|---|
-| 1 | Asset Explorer | 🚧 In Progress |
-| 2 | Flying Tech Demo | ⏳ Planned |
-| 3 | Combat Prototype | ⏳ Planned |
-| 4 | Mission 1 Playable | ⏳ Planned |
-| 5 | Full Game (all 16 missions) | ⏳ Planned |
-| 6 | Mod SDK | ⏳ Planned |
-
----
-
-## Useful References
-
-- [xdvdfs](https://github.com/antangelo/xdvdfs) — XISO disc image reader (used in this project)
-- [Xenia emulator](https://github.com/xenia-canary/xenia-canary) — GPU/API reference (cloned at `../../xenia-canary/`)
-- [xboxdevwiki](https://xboxdevwiki.net) — Xbox 360 hardware documentation
-- [binrw docs](https://binrw.rs) — binary format parsing framework
-- [Free60 Project](https://free60project.github.io/wiki/) — open Xbox 360 hardware docs
+Confidence is per claim, never per document: ✅ `CONFIRMED` · 🟡 `PROBABLE` ·
+❔ `HYPOTHESIS` · ❌ `REFUTED`. A withdrawn result is kept with its reasoning
+rather than deleted — that is why the numbers here can be trusted.

crates/sylpheed-export/Cargo.toml

@@ -49,7 +49,13 @@ license.workspace = true
 # which a capture of the running game plainly shows. 5414db3 is the revision at
 # which that fix carries its disc-wide check (30 of 13 991 elements move, 4
 # become visible, 0 become invisible), not merely the one where it was written.
-sylpheed-formats = { git = "https://git.mc02.dev/fabi/Syplheed-Reborn.git", tag = "formats-pin-2026-08-29" }
+# A PATH dependency now that the decoders and the exporter live in one
+# repository. This deletes a whole class of failure that the two-repo split
+# created: no pinned revision to go stale, no tag to keep alive, no commit that
+# a squash-merge can orphan, and no way for the exporter to be built against a
+# decoder it was never tested with. A decoder change and the exporter change it
+# requires now land in the same commit or not at all.
+sylpheed-formats = { path = "../sylpheed-formats" }
 
 serde      = { version = "1", features = ["derive"] }
 serde_json = "1"

docs/game/navigation.md

@@ -0,0 +1,137 @@
+# How the game is navigated
+
+**Purpose:** so nobody has to rediscover this. Every screen, what reaches it,
+what input it takes, and every modal that can interrupt.
+
+**Status:** skeleton, filled from what the corpus already knows. Most rows are
+❔ and are *meant* to be — this page exists to be completed from the oracle, not
+to look finished.
+
+> ## ⚠️ The oracle is Xenia Canary running the real game
+>
+> Not `sylpheed-cli`, not the viewer, not any renderer of ours. Reborn is a tool
+> for *verifying our decoding*; it is a hypothesis under test and it has been
+> wrong. **Every row below is only as good as the capture behind it**, and a row
+> with no capture is a guess wearing a table cell.
+>
+> This is written here because the mistake has already been made once, by the
+> author of this file, and it propagated into three documents and both agents
+> before a human caught it.
+
+Confidence: ✅ measured from a capture · 🟡 inferred from disc data · ❔ unknown.
+
+## 1. The screen vocabulary ✅
+
+The executable carries its own list — a `.rdata` pointer array at `0x820A1630`,
+29 entries, index = GamePart id, confirmed against the factory-registration
+strings in the image:
+
+```
+ 0 GP_TITLE            10 GP_BUNK             20 GP_STAGE_CLEAR
+ 1 GP_ADVERTISE_DEMO   11 GP_READY_ROOM       21 GP_MISSION_LOG
+ 2 GP_SELECT_STORAGE   12 GP_HANGAR           22 GP_GAMEOVER
+ 3 GP_LOAD             13 GP_ARSENAL          23 GP_DEBRIEFING
+ 4 GP_SAVE             14 GP_PILOT_LOG        24 GP_DIALOG
+ 5 GP_EXTRAS           15 GP_SYSTEM           25 GP_TUTORIAL
+ 6 GP_MOVIE_THEATER    16 GP_DEMO            *26 GP_CHALLENGE
+ 7 GP_MISSION_SELECT   17 GP_MAIN_GAME        27 GP_LEADERBOARD
+ 8 GP_OPTIONS          18 GP_SELECTOR         28 GP_TEST
+ 9 GP_MOVIE            19 GP_PAUSE_MENU
+```
+
+This is the *vocabulary*, not the graph. **Which button reaches which id is
+not decoded** — that is the open question, and filling in §3 is what closes it.
+
+`GP_TEST` is named here and is not on the disc.
+
+## 2. Boot 🟡
+
+```
+developer logo splash  →  intro video  →  title / PRESS Ⓐ  →  main menu
+```
+
+* The splash is a **screen, not a video** ✅ — `logo1`–`logo4` are bound by the
+  movie manifest and have no `.wmv` on the disc.
+* The intro is `dat/movie/ADV.wmv` ✅.
+* ❔ What *drives* the order. It is observable; the data or code behind it is not
+  decoded.
+* ⚠️ **Two title states exist and look identical.** The title that ends the boot
+  accepts a single Ⓐ; the title the attract loop returns to accepts nothing —
+  Ⓐ, START, B, BACK, X, Y all ignored across dozens of delivered presses. They
+  draw **13 identical quads**, so they differ only to the guest. Capture the
+  first title after boot; do not tap during the boot.
+
+## 3. Screens
+
+One section per screen. Fill from a capture, and cite it.
+
+### GP_TITLE — main menu 🟡
+
+Five buttons, `ptbtn01`–`ptbtn05`, at x=542, y=162/242/322/401/482.
+
+| button | label | reaches | confidence |
+|---|---|---|---|
+| `ptbtn01` | ❔ | ❔ | |
+| `ptbtn02` | ❔ | ❔ | |
+| `ptbtn03` | ❔ | ❔ | |
+| `ptbtn04` | ❔ | ❔ | |
+| `ptbtn05` | ❔ | ❔ | |
+
+Labels are baked into the sprites — a human reads them in a minute, but **no
+decoded field says which GamePart a button opens.** If the labels are read by
+eye, say so; that is an authored mapping, not a disc fact.
+
+❔ Initial focus · ❔ wrap-around at the ends · ❔ whether left/right does
+anything · ❔ what B does.
+
+### GP_LOAD ❔ · GP_SAVE ❔ · GP_EXTRAS ❔ · GP_OPTIONS ❔ · GP_MISSION_SELECT ❔
+
+❔ Not documented. Known fragment: the path
+`title → LOAD GAME → slot 01 → YES → READY ROOM → TAKE OFF` reaches flight, and
+**stage select would not move** — 16 d-pad presses never left Stage 01.
+
+### GP_READY_ROOM ❔
+
+The largest UI archive on the disc; only 6 of 1 106 names resolve, and it is
+ISL-scripted. A probe found the pak holds briefing/tactical-map content rather
+than the Ready Room menu itself. Out of scope for the menu milestone.
+
+## 4. Modals, prompts and alerts
+
+The interrupting layer, and the one most likely to break a scripted run.
+
+| modal | seen at | default focus | notes |
+|---|---|---|---|
+| `Save game?` | after a mission | **YES** ✅ | cursor starts on YES |
+| `Do you want to develop this weapon?` | Arsenal | ❔ | |
+| ❔ overwrite / delete confirmations | Save/Load | ❔ | |
+| ❔ error and "not enough points" alerts | Arsenal | ❔ | |
+
+⚠️ **A 60 ms d-pad tap is ignored inside a dialog.** It moves the cursor on a
+menu and does nothing in a modal, so a script that works on menus silently picks
+the default in every prompt. Confirm which side the cursor is on before Ⓐ.
+
+## 5. In-game flight ❔
+
+Not started. **The in-game tutorials are the resource** — they teach the control
+scheme in the game's own words, which is exactly the documentation we want, and
+they are `S18`–`S23` on disc.
+
+To fill in: the control map (both stick modes if there are two), throttle,
+target select — Ⓐ pressed **twice**, not once, which a sweep that only ever
+tapped once "proved" did not exist — weapon cycling, the pause menu, and the
+HUD's readouts.
+
+## 6. Input traps, all measured ✅
+
+Real behaviours that read as bugs:
+
+* **F10 opens the emulator menu bar**, and any Xenia UI makes
+  `XamInputGetKeystrokeEx` return SUCCESS with an empty keystroke *before* any
+  driver is asked. The pad looks dead and is not.
+* **A signed-in profile is required** — hence `--create_profile_if_none`.
+* **A FIFO trace consumer that exits stalls the emulator**, which also reads as
+  a dead pad.
+* **The title is not input-ready for ~10 s** after it appears.
+* **Ⓐ on the first title succeeds about half the time**, and nothing measurable
+  predicts which. Five explanations have been eliminated. Budget retries.

docs/port/MODDING.md

@@ -0,0 +1,86 @@
+# Modding is a requirement, not a later feature
+
+The port has two goals, and the second one constrains the first: **the exported
+asset tree is a product**, not a build artefact. Someone who has never read this
+repository should be able to open the tree, understand what they are looking at,
+change something, and see it in the game.
+
+That is a design constraint on the **exporter**, today — not a milestone to add
+later. Custom *behaviour* (scripting) is a later milestone, but nothing built now
+may make it harder.
+
+## The five rules
+
+**1. One logical asset, one file. Never split.**
+
+A sprite is one PNG. A track is one OGG. A screen is one JSON. This is a real
+constraint and not a platitude, because **the disc does the opposite everywhere**:
+a `.pak` entry spans segment files, a bank holds several sub-waves, and a
+cutscene voice is a byte region of a continuous stream chunked across entries
+whose boundaries do not match the cues. All of that is the *exporter's* problem
+to resolve. If a modder has to reassemble anything, the export is unfinished.
+
+**2. Names a person recognises.**
+
+`screens/title/main_menu.json`, not `0x90822a39.json`. Where the disc's own name
+was never recovered — the six `*2D` archives, `GP_READY_ROOM` — emit a stable
+synthetic name **and say in the file that the real one is unknown**, so a modder
+can tell a recovered name from an invented one.
+
+**3. Modern, editable formats only.**
+
+| kind | format | why |
+|---|---|---|
+| data, layout, config | **JSON** | Godot parses it natively (`JSON.parse_string`); every tool speaks it |
+| images | **PNG** | RGBA8, lossless, opens anywhere |
+| audio | **Ogg Vorbis** | Godot-native, no licence trap |
+| video | **Ogg Theora** | the only format Godot 4 plays natively |
+| text | **UTF-8** | never UTF-16BE, whatever the disc did |
+
+Not XML: Godot's `XMLParser` is a SAX-style API needing a hand-written binding
+per schema, where JSON is one call. Not a custom binary container, ever — that
+would rebuild the exact wall this port exists to remove.
+
+**4. Base and overrides, never one merged pile.**
+
+```
+data/
+  base/     generated from your disc by the exporter. Gitignored. Rewritten
+            wholesale -- never hand-edit it, your changes will vanish.
+  mods/     drop-in overrides. Yours. The exporter never touches this.
+```
+
+A mod replaces a file by shadowing its path. A modder edits nothing under
+`base/`, so re-exporting is always safe, and "did I break it?" is answered by
+disabling a mod rather than by re-extracting the disc.
+
+**5. Provenance in every generated file.**
+
+Source archive, entry index, exporter version. It is what lets someone check a
+file against the disc instead of trusting it — and what stops the export drifting
+into an unverifiable fork of the original.
+
+## Not blocking scripted mods later
+
+Behaviour modding is a later milestone. Two decisions now keep the door open:
+
+* **The loader is data-driven and screen-agnostic.** No screen name is hardcoded
+  in GDScript. A screen is *whatever the JSON describes*, so a mod that adds a
+  new screen needs no engine change.
+* **No GDExtension, no native code in `port/`.** [Godot Mod Loader][gml] — the
+  established option, Godot 4.1–4.3, used by Brotato and Dome Keeper — works by
+  substituting **GDScript** at load time. A port whose logic lives in GDScript
+  stays moddable by it; one that hides logic in native code does not.
+
+Adopting a mod loader is a decision for that milestone. Making it *possible* is a
+constraint on this one.
+
+[gml]: https://github.com/GodotModding/godot-mod-loader
+
+## What this rules out, explicitly
+
+* Atlases or packed archives of sprites — one file per sprite.
+* Any format needing our code to read it.
+* Hash-named files.
+* Hand-edited files under `data/base/`.
+* Splitting one playable thing across files to mirror how the disc stored it.

godot-import/.gitignore

@@ -1,12 +0,0 @@
-# Generated from the user's own disc. This repo stays clean-room: code,
-# schemas, authored mappings and docs only -- never game assets.
-/export/
-
-# Rust
-/target/
-**/*.rs.bk
-
-# Godot
-.godot/
-/port/.godot/
-*.import

godot-import/Cargo.toml

@@ -1,8 +0,0 @@
-[workspace]
-resolver = "2"
-members = ["crates/sylpheed-export"]
-
-[workspace.package]
-version = "0.1.0"
-edition = "2021"
-license = "MIT"

godot-import/README.md

@@ -1,75 +0,0 @@
-# Sylpheed Godot
-
-A clean-room Godot 4 port of *Project Sylpheed: Arc of Deception*, starting with
-the menu shell: developer splash → intro video → title → main menu → submenus.
-
-**You need your own copy of the game.** Nothing in this repository is game
-content. An offline exporter reads the disc you supply and writes an open,
-moddable asset tree; the Godot project reads only that tree and never touches a
-disc format.
-
-```
-  your disc  ──▶  crates/sylpheed-export  ──▶  export/   ──▶  port/  (Godot 4)
-                  (Rust; decoders come from      JSON + PNG        reads ONLY
-                   sylpheed-formats)             + OGG + OGV       open formats
-```
-
-## Why the wall
-
-Two reasons, and the second is the interesting one:
-
-1. Godot cannot read IPFB archives, RATC bundles, T8aD textures, XMA banks or
-   WMV video, and it should not learn to.
-2. **Modding is a goal of this port.** If the runtime reads the original formats,
-   modding means reverse engineering. If it reads JSON and PNG, modding means
-   opening a file.
-
-## Where the knowledge comes from
-
-The decoders live in [`sylpheed-formats`][formats], pinned by revision — a
-separate project, where the reverse engineering happens. Its
-`docs/port/HANDOFF.md` is the contract: what has been decoded, what was measured
-off the running game, and what is known to be undecodable. Read it before
-assuming a value is on the disc.
-
-[formats]: https://git.mc02.dev/fabi/Syplheed-Reborn
-
-## Layout
-
-| | |
-|---|---|
-| `crates/sylpheed-export/` | disc → open formats. Regenerates `export/` wholesale |
-| `port/` | the Godot 4 project |
-| `authored/` | decisions that are **not** on the disc, each with its reason |
-| `export/` | generated, gitignored, never hand-edited |
-| `tools/` | verification harnesses that hold the port to the reference renderer |
-| `docs/` | the mission, the format spec, the agent's loop prompt |
-
-## Verifying
-
-**The oracle is the Xenia Canary capture and the game**, not either renderer.
-`sylpheed-cli screen render` is an explorer and extraction CLI for verifying
-decodes, and it can be wrong -- three times both it and the port agreed and both
-were wrong, each caught only by a capture.
-
-So `tools/verify-screen` is a **consistency check and a regression detector**,
-not a grade. It draws every exported screen both ways -- built from the same
-`sylpheed-formats` revision the exporter is pinned to -- and reports the largest
-per-channel difference in the frame:
-
-```
-tools/verify-screen              # every screen in the manifest
-tools/verify-screen main_menu    # one of them
-```
-
-A difference means the two moved apart; `docs/DECISIONS.md` says which one moved
-and why, rather than tuning the port until the number goes down. Correctness is
-checked against the captures indexed at `docs/re/captures/ORACLE-CAPTURES.md` --
-mind that they are not gamma-neutral, so RMSE against them has a floor.
-
-## Status
-
-**P1.** The exporter writes `GP_TITLE`'s twelve screen builds and their sprites,
-and the Godot project draws any of them statically at 1280x720 from that tree
-alone. `main_menu` matches the reference renderer to within 3/255 on every
-channel of every pixel. Next: P2, keyframe animation.