diff --git a/.claude-context/sessions/2025-12-15-esp32-relay-automation.md b/.claude-context/sessions/2025-12-15-esp32-relay-automation.md
new file mode 100644
index 0000000..c012c68
--- /dev/null
+++ b/.claude-context/sessions/2025-12-15-esp32-relay-automation.md
@@ -0,0 +1,37 @@
+# ESP32 Bluetooth Relay Theatre Automation
+
+**Date:** 2025-12-15
+**Project:** moonlight-drive-in
+**Status:** resolved
+**Tags:** esp32, bluetooth, relay, pyserial, theatre-automation, lighting
+
+## Context
+Jess wanted the drive-in to control physical power — lights and other theatre effects — alongside video playback. An ESP32 8-channel Bluetooth relay board (separate repo `esp32-bluetooth-relay`) was built, and this session added the Python side so the player can switch relays as part of a show.
+
+## Key Decisions
+- **ESP32 relay over Bluetooth serial** (via `pyserial` on the Windows host's BT COM port) — cheap, no extra network config, and independent of the LAN.
+- **Separate `theatre_automation.py` layer** between the player and the relay driver — keeps show logic (what switches when) out of the low-level relay module.
+- **Relay control optional** — the player still runs if the relay isn't connected.
+- The earlier KAIYU Bluetooth LED controller route had been abandoned; smart plugs / USB relay boards were researched as alternatives, and the ESP32 relay was chosen.
+
+## Technical Details
+- `esp32_relay_controller.py` — relay driver (8 channels) over serial.
+- `theatre_automation.py` — maps player events to relay actions.
+- `test_relay.bat` — connection test script.
+- Dependency: `pyserial`.
+- Relay configuration examples and a reference guide are in the repo docs.
+
+## Code Changes
+- `esp32_relay_controller.py` — new.
+- `theatre_automation.py` — new.
+- `test_relay.bat` — new.
+- Python requirements — added `pyserial`.
+- `README.md` + integration guide + relay config examples.
+
+## Open Questions / Next Steps
+- Confirm which relay channels are wired to which theatre devices and record the mapping in the relay config.
+
+## Artifacts
+- `412fc3b` — Add ESP32 Bluetooth relay controller Python module
+- `bc3ab2f` — Add theatre automation integration for ESP32 relay control
+- Related repo: https://gitea.hideawaygaming.com.au/jessikitty/esp32-bluetooth-relay