diff --git a/infra/zigbee2mqtt/DEVICES.md b/infra/zigbee2mqtt/DEVICES.md
new file mode 100644
index 0000000..4aefd49
--- /dev/null
+++ b/infra/zigbee2mqtt/DEVICES.md
@@ -0,0 +1,42 @@
+# Zigbee device notes
+
+Per-device quirks discovered during setup. Keep this file in sync as we
+encounter new devices.
+
+## ThirdReality Smart Button (3RSB22BZ) — Door Button
+
+**Has two pairing modes** — the button will only work with zigbee2mqtt
+in **Standard ZigBee mode**.
+
+| Mode | LED indicator | zigbee2mqtt compatible? |
+|---|---|---|
+| Standard ZigBee | blinks **blue only** | yes |
+| Echo ZigBee | blinks **blue + red alternating** | no |
+
+Switching modes depends on firmware version:
+
+- **Firmware ≥ 1.00.22** (most common): press the **back reset button**
+  (pinhole) **5 times within 5 seconds**.
+- **Firmware < 1.00.22**: hold the **front button + back reset button**
+  simultaneously for 5 seconds.
+
+The front button does NOT trigger a reset — only the back pinhole does.
+Holding the front button for any length of time only emits Zigbee
+`action` events (`single`, `hold`, `release`).
+
+If the button joins but zigbee2mqtt can't interview it correctly,
+check the LED — it's almost certainly in Echo mode.
+
+## ThirdReality Smart Plug Zigbee PROD (3RSP02028BZ / similar)
+
+Factory reset / pairing mode: **press and hold the side button for
+>10 seconds** until the LED flashes (red = ZigBee mode, green = BLE mode).
+
+Most plugs ship in **BLE mode** out of the box. To switch to ZigBee:
+hold button + insert into outlet + hold 10s + release + press button
+**twice immediately**. LED should flash **red** (ZigBee).
+
+To re-join an existing ZigBee network (e.g. after the dongle was
+swapped), **power-cycle** is usually sufficient — no reset needed. The
+plug retains the network_key and rejoins automatically when permit_join
+is open on the coordinator.