Document session workflows: probe/app build switch, tmux serial monitor, board reset, black-control bits

PROJECT_MEMORY.md

@@ -207,25 +207,76 @@ nixpkgs-esp-dev.url = "github:dvdvgt/nixpkgs-esp-dev/update-v6.0.1";
 
 This fork has **few/no cached binary substitutes**, so `nix develop` compiles the entire ESP-IDF toolchain from source. This takes **a long time** on first run but we're keeping it for now since mainline `mirrexagon/nixpkgs-esp-dev` doesn't support ESP-IDF v6.0.1 yet.
 
+### ⚙️ Two firmware builds: app vs. bit-probe
+
+`firmware/main/CMakeLists.txt` selects which source compiles. To switch:
+- **App** (`temphummon.c`): `SRCS "temphummon.c"` — the normal temperature/humidity display
+- **Probe** (`bitprobe.c`): `SRCS "bitprobe.c"` — interactive bit-field explorer (BOOT-button
+  advance). Files `dpfinder`/`iconfinder` were folded into `bitprobe.c` across sessions.
+
+The project name is always `temphummon` (even when bitprobe is compiled), so the ELF/bin are
+named `temphummon.*` regardless. See the serial-monitor workflow below for how to watch output.
+
+### 🖥️ Serial monitor workflow (headless container)
+
+`idf.py monitor` needs a real TTY and fails in this container. Use a detached `tmux`
+session instead (tmux was installed:
+`apt-get install -y -qq tmux`):
+
+```bash
+PYENV=/nix/store/h1az2v5l5jx81jdqfzk5q6wnv40cgq4y-python3-3.13.12-env
+IDF_MON=/nix/store/4d83mx8ff4ffpcj0x8r4l2x3qd8z3z8k-source/tools/idf_monitor.py
+tmux new-session -d -s mon "cd /src/firmware && $PYENV/bin/python $IDF_MON \
+  -p /dev/ttyACM0 -b 115200 --toolchain-prefix riscv32-esp-elf- --target esp32h2 \
+  --revision 0 --decode-panic backtrace build/temphummon.elf build/bootloader/bootloader.elf \
+  2>&1 | tee /tmp/monitor.log"
+# read live log:  tr -d '\000' < /tmp/monitor.log | tail -20
+# stop:          tmux kill-session -t mon
+```
+
+To hard-reset the board (re-init a wedged panel) without reflashing:
+```bash
+$PYENV/bin/python -m esptool --chip esp32h2 -p /dev/ttyACM0 \
+  --before=default-reset --after=hard-reset chip-id
+```
+
+The flash tool needs the port free — kill the tmux monitor first (`tmux kill-session -t mon`).
+
+### ⚠️ Black-control bits (panel wedging) & I²C timeout
+
+Probing found several bits that flip the whole panel BLACK and wedge it until a hard
+re-init (RST pulse / board power-cycle): `f[2]` b4, `f[4]` b7, `f[13]` b1 (and `f[8]` b4
+caused an I²C hardware timeout). Avoid touching these when composing frames. A single
+`epd_write()` does not always clear the wedge — use `epd_lut_GC()` clear or reset the board.
+
 ---
 
 ## Build State
 
 ### ✅ Successful build
 
-The firmware compiles and links successfully for ESP32-H2 (RISC-V target). Size: `0x2b1b0` bytes (83% free).
+The firmware compiles and links successfully for ESP32-H2 (RISC-V target).
+Current `temphummon.c` build size: `0x2c580` bytes (83% free).
 
 ### Firmware behavior
 
 Current firmware (`main/temphummon.c`):
 - Initializes GPIOs (RST output, BUSY input) and I²C bus
-- Initializes display (power on, boost, temperature compensation)
+- Initializes display (RST pulse → `0x2B 0xA7 0xE0` power/boost/TSON → temp comp)
-- Clears display (full refresh cycle)
+- Clears display with **GC (full global refresh) LUT**, then updates with
+  **DU_WB (partial) LUT** every second
 - Reads internal CPU temperature, renders on top line as `188.8°C` with
   correct **decimal point** (`f[4]` bit5) and leading "1" (`f[0]`)
 - Renders fixed humidity sample on bottom line as `88.8%` (tens/ones/tenths
   + decimal `f[8]` bit5 + **percent sign** `f[10]` bit5), updates every 1s
-- Prints status via ESP_LOG
+  (`render_temp()` / `render_humidity()` helpers)
+- Prints status via ESP_LOG (`temphummon: T: 27.6°C` every 1s)
+- Bit 1 of `f[13]` (`0x02`) is NOT used for °C (leaves the degree circle incomplete)
+  — `0x05` = °C (bits 0+2) is the correct full-degree rendering
+
+⚠️ The display uses a dot-matrix glyph style.  A lone bit does not always
+produce a clean segment; the erase flash (white frame) is normal before each
+partial update.
 
 ### ✅ Hardware bringup (confirmed working)