docs/port/RUNNING.md

@@ -9,6 +9,36 @@ Everything below has been run. Where a number is quoted it was measured in this
 container, and where the container distorts it that is said rather than left for
 the reader to discover.
 
+## 0. Import the project once, on a checkout that has never run it
+
+```bash
+godot --headless --path port --import
+```
+
+🔴 **Skip this and the port looks broken rather than unimported.** Godot resolves
+`class_name` through `port/.godot/global_script_class_cache.cfg`, which is
+gitignored and is written at import time. Without it **every** class fails —
+`ScreenView`, `MenuAudio`, `Gamepad`, `MenuFlow`, `ExportTree` — and each failure
+cascades into a dozen more:
+
+```
+SCRIPT ERROR: Parse Error: Could not find type "ScreenView" in the current scope.
+SCRIPT ERROR: Parse Error: Cannot infer the type of "_pad" variable …
+ERROR: Failed to load script "res://scripts/boot.gd" with error "Parse error".
+```
+
+Thirty-odd parse errors naming half the project reads like a port that does not
+compile. It is one missing cache, and the import takes seconds. Measured on a
+fresh checkout 2026-09-26: before, 30 errors and a hang; after, **zero**.
+
+The container does not hit this because its image carries an imported tree, which
+is exactly why the step was never written down.
+
+⚠️ `--headless` **cannot capture**. Godot's dummy renderer never emits
+`frame_post_draw`, so `--capture=` under `--headless` would hang; the port
+detects it and says so. A capture needs a display — `xvfb-run -a godot …`, and
+note that **`xvfb-run` is not installed on every host**.
+
 ## 1. Build the asset tree
 
 The Godot project reads `export/`, never the disc.
@@ -17,7 +47,21 @@ The Godot project reads `export/`, never the disc.
 cargo run --release -p sylpheed-export -- export --disc /disc --out export
 ```
 
-Roughly four minutes, most of it transcoding two movies. It **rewrites `export/`
+Roughly four minutes, most of it transcoding two movies.
+
+🔴 **The exporter needs `ffmpeg` and `ffprobe` on PATH** — it shells out to them
+for both the movies and the audio. On a host, that means running it through the
+CI container built WITH them:
+
+```bash
+SYLPH_CI_IMAGE=sylph-ci:ffmpeg docker/ci/run \
+  cargo run --release -p sylpheed-export -- export --disc /disc --out export
+```
+
+`sylph-ci:local` has neither, and the failure arrives several minutes in, after
+the screens have already been written. Measured 2026-09-26 on `fabi-Hyrican-PC`:
+31 s to build, 4 min 11 s end to end, 149 MB of `export/`, and
+`sylpheed-export check` then validates all 16 screens. It **rewrites `export/`
 wholesale** — never hand-edit anything in there; hand-written decisions live in
 `authored/` beside it, and survive a re-export.