From bd4aa680321181ffe770c5b507e8e991b5888a29 Mon Sep 17 00:00:00 2001
From: Evan Reichard <evan@reichard.io>
Date: Mon, 20 Jul 2026 08:04:27 -0400
Subject: [PATCH] docs: note boot stall next step and patch re-apply workflow

---
 HANDOFF.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/HANDOFF.md b/HANDOFF.md
index 2f9f5c3..55f8861 100644
--- a/HANDOFF.md
+++ b/HANDOFF.md
@@ -288,7 +288,16 @@ ADC ladders on GPIO1 & GPIO2; power button GPIO3; UC8253 @ 16 MHz.
 
 Next:
 
+0. **Boot stall**: firmware freezes after X3 panel init (display generation stays
+   at 2). Compare against native `make run` (which reaches the home screen);
+   suspect timers/interrupts or just slow TCG. `_scratch/dump-fb3.mjs` reproduces.
 1. **Browser SD storage**: add an uploaded or OPFS-backed SD block device.
+
+> Patch workflow: `scripts/build-qemu-wasm.sh` only re-applies
+> `qemu/patches/0002-qemu-wasm.patch` when the WASM source tree lacks the xteink
+> files. After editing the patch, `rm -rf _scratch/qemu-wasm-src` so `make
+> qemu-wasm` re-clones and re-applies it. The patch is regenerated from the
+> `_scratch/qemu-fix-src` worktree via `git diff --binary 610f8c69..HEAD`.
 2. **Full X4 rendering later**: SSD1677 is 800×480 controller / 480×800 portrait,
    BUSY active-high. Implement its RAM/window/update commands when needed.