diff --git a/docs/upstream-sdio-wedge.md b/docs/upstream-sdio-wedge.md
new file mode 100644
index 0000000..78906be
--- /dev/null
+++ b/docs/upstream-sdio-wedge.md
@@ -0,0 +1,47 @@
+# SDIO wedge reproduction pack (esp-hosted-mcu #167 family)
+
+Evidence gathered overnight 2026-07-14→15 on Waveshare ESP32-P4-WIFI6-Touch-LCD-3.4C
+(ESP32-P4 host + ESP32-C6-MINI-1 slave, SDIO: CLK18 CMD19 D0-14 D1-15 D2-16 D3-17,
+slave reset GPIO54, on-board routed traces). Ready to post as an upstream issue
+comment when we choose to.
+
+## Signature
+
+```
+E H_SDIO_DRV: sdio_write_task: 0: Failed to send data: 258 72 72
+E H_SDIO_DRV: sdio_write_task: 1: Failed to send data: 258 72 72
+E H_SDIO_DRV: Unrecoverable host sdio state
+→ SW_CPU_RESET (H_TRANSPORT_RESTART_ON_FAILURE)
+```
+
+Decoded from `sdio_drv.c` `sdio_write_task`: a 72-byte frame (`len_to_send=72,
+data_left=72`, i.e. keepalive-sized) fails `_h_sdio_write_block` with
+`ESP_ERR_TIMEOUT` (258) on both retries — **after** `sdio_is_write_buffer_available()`
+reported credits. The slave's SDIO peripheral stops ACKing CMD53 between the credit
+read and the data write. Serial is completely silent for minutes before the event
+(idle link, WS ping traffic only).
+
+## Occurrence matrix (all: host IDF v5.5, matched host+slave versions)
+
+| Config | Time to wedge |
+|---|---|
+| 2.12.11, 4-bit, 40 MHz, PS default, DHCP client active | ~437 s |
+| 2.12.11, 1-bit, 20 MHz, PS default, DHCP active | ~297 s |
+| 2.12.11, 1-bit, 10 MHz, WIFI_PS_NONE, DHCP active | ~322 s, ~297 s |
+| 2.12.11, 1-bit, 10 MHz, WIFI_PS_NONE, **static IP (no dhcpc)** | **~783 s** |
+
+- Bus width, clock (40→10 MHz), and Wi-Fi power save have **no effect**.
+- Removing the DHCP client ~2.6×'d the survival time → trigger frequency correlates
+  with (small-packet?) TX activity, but idle WS keepalives eventually wedge it too.
+- Recovery: host auto-restart works every time (~15 s to reconnected).
+- 2.9.7 slave could not be tested: its image consistently rolls back on this C6
+  (bootloops back to the 2.12.11 OTA slot); 2.12.11↔2.12.11 is the tested pair.
+- esp-hosted 1.4.x is not comparable (no data path at all on IDF 5.5, see #47).
+
+## Current mitigation in DeskLock
+
+- `H_TRANSPORT_RESTART_ON_FAILURE` (default) + gong silenced on SW resets → the
+  device self-heals invisibly except ~15 s of CONNECTING face.
+- Static addressing (`192.168.86.53`) reduces wedge frequency to ~13 min MTBF.
+- Full raw serial history of every wedge in `scratchpad/nightwatch.log` captures
+  (session artifacts), timestamps in the repo's commit trail.