From 0111e50b2a9ad694deade9e4a58e3a626ac9a09f Mon Sep 17 00:00:00 2001
From: Vuong Hoang <vh@phasefinal.com>
Date: Fri, 14 Aug 2026 22:55:57 -0700
Subject: [PATCH] docs: capture preload-vs-import-cache foot-gun + Mac
 black-scene recovery

---
 CLAUDE.md            | 11 +++++++++++
 persistent-memory.md |  9 +++++++++
 2 files changed, 20 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index b251b83..2c5489f 100644
--- a/CLAUDE.md
+++ b/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
diff --git a/persistent-memory.md b/persistent-memory.md
index 0189fa5..3be95e9 100644
--- a/persistent-memory.md
+++ b/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.