# Notes for an agent working inside this container

Read this before starting a dynamic-RE run. Everything here is something that
already went wrong once.

## The container fixes three old traps for you

* **The display outlives the turn.** Xvfb and openbox are children of PID 1, not
  of your shell. The old "Xvfb dies on its own every few minutes" note is gone —
  you no longer have to wrap a whole session in one blocking foreground call to
  keep it alive.
* **The toolchain is real.** `tools/re-capture/rebuild_canary.sh` exists because
  the old box had no cmake/ninja/clang and only runtime sonames, so it hand-
  relinked object files. **Do not use it here.** Use `build-canary`.
* **numpy and Pillow are installed.** `entities2.py`, `flight_probe.py` and the
  image oracles work. Their absence used to look like a logic bug.

## Method (the part that matters more than the tooling)

* **Measure the oracle; never infer it.** A session with zero Canary runs is a
  red flag.
* **Trace upstream to where data first goes wrong**, rather than patching the
  symptom you can see.
* **Try to refute before believing.** Record demotions rather than editing them
  away — `docs/re/README.md` has the ✅/🟡/❔ convention, and a withdrawn result
  is more useful than a quietly deleted one.
* **A probe that never performs the action will "prove" the action does not
  exist.** The "targeting is automatic" conclusion came from a sweep that only
  ever tapped once; target select is Ⓐ pressed *twice*.
* **Do not poll faster than the guest updates** — it manufactures a clean curve
  out of noise. `rate-curve-aliased-BAD.csv` is committed as the bad example.

## Running the emulator

```bash
run-canary                       # correct audio/pad/display flags baked in
pad.py tap A ; pad.py dpad down  # scripted input (--hid=file, no uinput)
screenshot ~/shots/now.png       # cropped to the GAME surface, not the window
python3 tools/re-capture/gmem.py find hex:820af844 400
```

* **One emulator at a time.** `run-canary` enforces it with a lockfile.
* Boot is slow cold, ~25 s once the shader/code caches are warm — so a
  launch-and-dump fits in a single call.
* **Screens: classify by whole-image statistics** (`screen_id.py`), not named
  pixels. Named-pixel oracles are only valid while the game image sits at a
  known place, and nothing errors when it moves.

## Verifying your own work

* Reborn's disc-gated tests **self-skip** without `SYLPHEED_DISC`. A green run
  with it unset means almost nothing. `build-reborn test` wires it up for you.
* Prefer a headless self-verify over "it compiles": `sylpheed-cli mesh render`,
  `screen render`, `save info` all produce checkable artifacts.
* A Bevy system-parameter conflict is invisible to the type checker and panics
  at startup. If you touch viewer systems, *run the binary*, don't just build it.

## The Godot port

The primary objective — see `docs/port/MISSION.md`. Two binaries are installed:

```bash
godot-headless --path port/ --script res://tools/check.gd   # no display needed
DISPLAY=:99 godot --path port/                              # windowed, under Xvfb
screenshot ~/shots/godot.png                                # then capture it
```

* **Godot is pinned to one version** in the Dockerfile. An engine bump changes
  rendering, and this project diffs Godot's output against a reference renderer —
  so do not upgrade it to fix a bug without saying that is what you did.
* **`sylpheed-cli screen render` is the reference.** When Godot draws a screen,
  render the same build with the CLI and compare. Where they disagree, one of
  them is wrong; say which, and why, rather than tuning until they match.
* **ffmpeg has libtheora**, which is the transcode target for video. Keep the
  exact command in the exporter config — a modder who dislikes the quality should
  be able to re-run it, not reverse-engineer what you did.
* **Never commit anything under `export/`.** It is generated from the user's own
  disc and gitignored. Code, schemas, `authored/` mappings and docs only.

## Reporting

State what you measured, what you assumed, and what you could not settle. If a
result is withdrawn, say so and keep the reasoning — that is the corpus's whole
convention, and the reason its numbers can be trusted.