docs: capture preload-vs-import-cache foot-gun + Mac black-scene recovery

CLAUDE.md

@@ -112,6 +112,17 @@ Non-negotiable canon highlights (full rationale in CONCEPT.md):
   editor after new commits land. If a pull ever refuses over generated
   sidecars anyway, they're safe to delete wholesale:
   `git clean -f '*.uid'` (add `'*.import'` if named) — then pull.
+  **If a pulled scene runs black / actors invisible / no input**
+  (stale local import cache): quit the editor, `rm -rf .godot`, pull,
+  reopen, and let the reimport bar finish BEFORE pressing Play. The
+  `.godot/` cache is gitignored and fully regenerable.
+- **Code-created sprites/resources use runtime `load()`, never
+  `preload()`.** `preload` is a compile-time dependency: if the
+  cross-machine import cache is stale, it fails at parse time and
+  kills the whole script (movement + logic gone, not just the
+  texture). `load()` degrades a missing resource to a null texture
+  and keeps the script alive. (Lesson paid 2026-08-14, commit
+  `62e86f9`.)
 - GDScript for design iteration; C# reserved for hot paths (none
   yet).
 - 2D, pixel-first: integer scaling, nearest-neighbor filtering

persistent-memory.md

@@ -118,3 +118,12 @@ _As of 2026-08-07 (post-falsifier):_
   physics signal flush (projectile `body_entered` → death → spawn) —
   Godot blocks collision setup mid-flush. Spawn via
   `add_child.call_deferred()` from any death/hit signal path.
+- `[2026-08-14]` `preload()` of an imported texture in a code-created
+  sprite breaks the WHOLE script at compile time if the other
+  machine's import cache is stale (Mac editor after pull: black scene,
+  no movement — preload can't resolve the not-yet-imported resource).
+  Use runtime `load()` (null-degrades) for code-created sprites; fix
+  `62e86f9`. Recovery for a victim machine: quit editor, `rm -rf
+  .godot`, pull, reopen, let reimport finish. Committed state was
+  provably sound (fresh clone ran clean) — the bug was purely the
+  consumer's stale cache.