diff --git a/esp32/README.md b/esp32/README.md
new file mode 100644
index 0000000..3b02723
--- /dev/null
+++ b/esp32/README.md
@@ -0,0 +1,83 @@
+# ESP32 Build Tools for Spider Runtime
+
+Build system for compiling the Spider Runtime for the ESP32
+microcontroller using the Espressif Xtensa toolchain.
+
+---
+
+## Requirements
+
+- [ESP-IDF v5.x](https://dl.espressif.com/dl/esp-idf/) installed
+- MSYS2 or any Unix-like shell
+- `spider-runtime` repository cloned at the same level as this repo
+
+Expected folder structure:
+```
+Internship/
+    spider-runtime/
+    spider-micro-buildtools/
+        esp32/   ← you are here
+```
+
+Add the Xtensa toolchain to your PATH before building:
+```bash
+export PATH=$PATH:/c/Espressif/tools/xtensa-esp-elf/<version>/xtensa-esp-elf/bin
+```
+
+---
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `Makefile` | Build recipe for ESP32 using `xtensa-esp-elf-g++` |
+| `gen_makefile.py` | Regenerates the Makefile (run if Makefile gets corrupted) |
+| `main_esp32.cpp` | ESP32 entry point, replaces the desktop `main()` |
+
+---
+
+## Build
+```bash
+make
+```
+
+Output: `out/spider_esp32.elf`
+
+To clean and rebuild from scratch:
+```bash
+make cleaner
+make
+```
+
+---
+
+## Flash to ESP32
+
+**Step 1 — Convert to flashable binary:**
+```bash
+xtensa-esp-elf-objcopy -O binary out/spider_esp32.elf out/spider_esp32.bin
+```
+
+**Step 2 — Connect your ESP32 via USB and find the COM port**
+
+On Windows, check Device Manager under "Ports (COM & LPT)".
+
+**Step 3 — Flash:**
+```bash
+esptool.py --chip esp32 --port COM3 --baud 115200 write_flash 0x1000 out/spider_esp32.bin
+```
+
+Replace `COM3` with your actual port.
+
+---
+
+## Compiler Flags
+
+| Flag | Purpose |
+|------|---------|
+| `-DESP32` | Activates ESP32 detection in `distro_mcu.hpp` |
+| `-DSPIDER_DISTRO_MICRO` | Enables microcontroller mode |
+| `-DSPIDER_OS_NONE` | Declares bare-metal, no OS |
+| `-mlongcalls` | Required for Xtensa memory layout |
+| `-fno-exceptions -fno-rtti` | Disable unavailable C++ features |
+| `-O0` | No optimizations, faster development builds |
\ No newline at end of file