diff --git a/CLAUDE.md b/CLAUDE.md
index 6e97a8b..25d2686 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -91,7 +91,21 @@ Non-negotiable canon highlights (full rationale in CONCEPT.md):
   An upgrade is an operator decision applied to both machines at
   once.
 - Headless verification: `godot --headless` works on nh3-dev for
-  scripts, tests, and imports.
+  scripts, tests, and imports. Smoke gate:
+  `~/bin/godot --headless --path . res://tests/smoke.tscn` (exit 0
+  pass / 1 fail; run 3x to catch flakes). After adding scenes/assets,
+  import first: `~/bin/godot --headless --import --path .`
+- **Generated sidecars ship with their sources.** Run the headless
+  import BEFORE committing new scripts/assets so `.uid` / `.import`
+  sidecars land in the same commit — otherwise the other machine's
+  editor mints untracked copies and its next `git pull` refuses to
+  merge. Enforced on nh3-dev by a local `.git/hooks/pre-commit`
+  (not versioned — recreate on fresh clones: refuse staged-new `.gd`
+  without a tracked `.uid`).
+- **Two-machine hygiene (Mac editor side):** pull BEFORE opening the
+  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.
 - 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 184ccf6..b9e994d 100644
--- a/persistent-memory.md
+++ b/persistent-memory.md
@@ -14,15 +14,6 @@ mech auto-battler rogue-lite. Design canon lives in the advisor repo (see
 CLAUDE.md); this repo builds what canon ratifies. Current mission is the
 greybox falsifier (ROADMAP.md v1) that tests the design's three core bets.
 
-## Tools and conventions
-
-- Smoke gate: `~/bin/godot --headless --path . res://tests/smoke.tscn`
-  (exit 0 pass / 1 fail; run 3x to catch flakes). After adding new
-  scenes/assets, import first: `~/bin/godot --headless --import --path .`
-- New GDScript files: run the headless import BEFORE committing so
-  Godot's `.uid` sidecars land in the SAME commit as their scripts (see
-  Tried and abandoned, 2026-08-07).
-
 ## Current state / in-flight
 
 _As of 2026-08-07:_