diff --git a/docs/ESP32-PINOUT.md b/docs/ESP32-PINOUT.md
new file mode 100644
index 0000000..fe6a2c2
--- /dev/null
+++ b/docs/ESP32-PINOUT.md
@@ -0,0 +1,75 @@
+# ESP32 pinout reference
+
+For the original **ESP32-WROOM-32 / WROVER** devkit, which is what both boards
+in this project are. S3, C3, C6 and H2 have different maps entirely — and no
+Bluetooth Classic, so they cannot run board A at all.
+
+## Already in use
+
+| Pin | Board | Used for |
+| --- | --- | --- |
+| GPIO2 | A and B | onboard status LED |
+| GPIO16 | A and B | UART2 RX (link) |
+| GPIO17 | A and B | UART2 TX (link) |
+| GPIO25 | B | LED circuit 1 (Circle) |
+| GPIO26 | B | LED circuit 2 (Triangle) |
+
+## Free and safe for output
+
+Use these first. No strapping duties, no boot-time side effects.
+
+```
+4   13   14   18   19   21   22   23   27   32   33
+```
+
+That is eleven spare pins, which is plenty for more LEDs, a buzzer, servos or
+switches. GPIO21 and GPIO22 are the default I2C pins and GPIO18/19/23 the
+default SPI pins, but nothing in this project uses either bus, so they are free
+here.
+
+## Never use
+
+| Pin | Why |
+| --- | --- |
+| GPIO6–11 | wired to the on-board SPI flash chip. Touching these bricks the running firmware. |
+| GPIO12 | strapping pin (MTDI). Pulled high at boot it sets the flash voltage to 1.8V and the board will not boot. |
+| GPIO1, GPIO3 | UART0, the USB serial console. Using them breaks uploads and the serial monitor. |
+
+## Usable, with a catch
+
+| Pin | Catch |
+| --- | --- |
+| GPIO0 | strapping. Must be high at boot or the board enters flash-download mode. Has a button on most devkits. |
+| GPIO2 | strapping, and the onboard LED. Must be low or floating at boot. Fine as an output once running — this project uses it. |
+| GPIO5 | strapping. Outputs a PWM burst during boot, so anything attached will twitch at power-on. |
+| GPIO15 | strapping. Emits boot log noise unless pulled low. |
+
+## Input only — cannot drive an LED
+
+```
+34   35   36   39
+```
+
+These have no output drivers and no internal pull-ups. Fine for buttons with an
+external pull-up, or for analog input. Connect an LED and nothing happens.
+
+## Current limits
+
+A single pin is comfortable at about **12mA** and hard-limited near **40mA**.
+The whole chip should stay under roughly 200mA across all pins at once.
+
+Two or three small LEDs per pin is fine. Anything beyond about 20mA per circuit
+— which pre-wired "3V" LEDs sized for a coin cell often draw — wants a small
+NPN transistor or a logic-level MOSFET, with the pin driving the base or gate
+rather than the LED directly.
+
+## ADC note
+
+ADC2 pins (0, 2, 4, 12–15, 25–27) cannot be read with `analogRead()` while
+WiFi is active. Irrelevant to this project, which uses no WiFi and no analog
+input, but worth knowing before adding a potentiometer. ADC1 pins (32–39) work
+regardless.
+
+---
+
+Created by: Jess Rogerson (yelling commands at Claude.AI)