diff --git a/tooling/claude/dot-claude/instructions/canonical-commands.md b/tooling/claude/dot-claude/instructions/canonical-commands.md
index 5cb72b8f..eb986b90 100644
--- a/tooling/claude/dot-claude/instructions/canonical-commands.md
+++ b/tooling/claude/dot-claude/instructions/canonical-commands.md
@@ -18,3 +18,15 @@ For env var setup (`AUTOPLAY_HOST`, `PROJECT_ROOT_REMOTE`, etc.) see `two-host-w
 | Lint | `gdlint src/game/engine/src/` (runs on EDIT host, no toolchain needed) |
 
 Pair with `./run` wrappers when available — see `task-runner.md`.
+
+## First-run on a fresh apricot scratch dir
+
+Godot needs `src/game/.godot/global_script_class_cache.cfg` and `src/game/.godot/extension_list.cfg` to register `class_name`-declared GDScript classes (e.g. `AiTurnBridge`) and `gdextension` libraries (e.g. `GdGridState`, `GdCity`). These files are NOT committed and are NOT created by `rsync`; they're built by Godot on first project import.
+
+If a fresh scratch dir on apricot (`~/.cache/mc-src-<stamp>/`) shows `SCRIPT ERROR: Identifier "GdGridState" not declared in the current scope` or `Could not find type "AiTurnBridge"`, run a one-time import to build the cache:
+
+```
+ssh apricot 'cd ~/.cache/mc-src-<stamp> && timeout 60 flatpak run --user --filesystem=home org.godotengine.Godot --path src/game --headless --import 2>&1 | tail -5'
+```
+
+Subsequent runs (autoplay, GUT, batches) will then load extensions and class_name registrations correctly.