diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2ff71d8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,57 @@
+# ZIFI32 — ESP32 WiFi/SPI module for ZX Evolution
+
+Firmware and hardware for the ESP32-S3-based WiFi/SPI module ("ZiFi32") used
+by the ZX Evolution / TS-Conf ("Pentevo") retro-computer platform. Adds
+WiFi, a WAV/XM/MOD/S3M audio tracker, and (new in this fork, work in
+progress) an SMB2/3 network share that exposes the machine's real SD card
+to any Windows/macOS/Linux client.
+
+**Base source**: [tslabs/zx-evo](https://github.com/tslabs/zx-evo/tree/master/pentevo/esp32).
+See [`firmware/README.md`](firmware/README.md) for the full list of changes
+made in this fork and their current status.
+
+## Requirements
+
+- The ZX Evolution/TS-Conf board's own **core firmware must be built with
+  VDAC2 and ESP32 (ZiFi32) peripheral support enabled** - without both, the
+  core won't recognize this module on the SPI bus at all, and won't drive
+  the FT8xx video chip either.
+- The **RESET jumper on the IDE connector must be installed** - see
+  [`hardware/connection_diagram.webp`](hardware/connection_diagram.webp).
+
+## Repository layout
+
+| Path                | What's there |
+|---------------------|--------------|
+| `src/`               | ESP32 firmware source (ESP-IDF project) |
+| `firmware/`          | Ready-to-flash compiled binaries + flashing instructions + changelog |
+| `hardware/`          | Adapter board connection diagram, PCB photo, Gerber files |
+| `doc/`               | Protocol/design notes |
+| `test/`              | Original upstream SPI protocol test scripts (Python, Raspberry Pi) |
+| `spi_gpio_probe/`    | Standalone diagnostic firmware - logs raw SPI pin edges, used for bring-up debugging, NOT the main firmware |
+
+## Quick start
+
+1. Flash `firmware/esp-spi.bin` (+ bootloader/partition table) to the ESP32-S3
+   module - see [`firmware/README.md`](firmware/README.md#flashing) for the
+   exact `esptool.py` command.
+2. Wire it up per [`hardware/connection_diagram.webp`](hardware/connection_diagram.webp)
+   (adapter PCB Gerbers are in [`hardware/gerber/`](hardware/gerber/) if you're
+   making your own board - see the photo in [`hardware/pcb_photo.jpg`](hardware/pcb_photo.jpg)).
+3. Make sure the ZX Evolution core firmware requirement above is met.
+4. Build from source instead of flashing the prebuilt binary: ESP-IDF
+   **v6.1** (not `v6.1-rc1`), `idf.py build flash`.
+
+## Status
+
+WiFi, audio tracker playback, and the SMB2/3 VFS bridge (browse, download,
+upload, delete over a real SD card) all work against real hardware. The VFS
+bridge is still **actively being developed** - directory creation, in-place
+file truncation on overwrite, and live directory-change notifications aren't
+implemented yet. Full details in [`firmware/README.md`](firmware/README.md).
+
+## License
+
+This repository vendors [libsmb2](https://github.com/sahlberg/libsmb2)
+(LGPL-2.1) under `src/third_party/libsmb2` - see its own `COPYING` and
+`LICENCE-LGPL-2.1.txt` there.