docs(port): the two steps a host needs that the container hides

Both were found by following RUNNING.md on this host from a clean checkout, and
both fail in a way that blames the wrong thing.

`godot --path port` without a prior `--import` produces THIRTY parse errors
naming half the project -- ScreenView, MenuAudio, Gamepad, MenuFlow, ExportTree
all "not declared", each cascading into "cannot infer the type of ..." -- and
then hangs. That reads like a port that does not compile. It is one gitignored
file: `port/.godot/global_script_class_cache.cfg`, which Godot writes at import
time and which `class_name` resolution needs. After `--headless --path port
--import`: zero errors, `main_menu` loads 16 elements and settles at t=56.

The exporter shells out to ffmpeg and ffprobe for the movies AND the audio, and
`sylph-ci:local` has neither -- so the documented `cargo run` fails minutes in,
after the screens are already written and it looks like it is working. The image
to use is `sylph-ci:ffmpeg`.

Neither bites in the agent container: its image carries an imported tree and its
own ffmpeg. That is exactly why neither was ever written down.

Also recorded: `--headless` CANNOT `--capture` (the dummy renderer never emits
`frame_post_draw`; the port detects this and says so), and `xvfb-run`, which its
message suggests, is not installed on every host -- it is not on this one.

Measured 2026-09-26 on fabi-Hyrican-PC: 31 s build, 4 min 11 s export, 149 MB,
`sylpheed-export check` validates all 16 screens against sylpheed.screen/3.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

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.