diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ca2d3a0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,29 @@
+ESP32 automated reptile feeder and 3-zone climate monitor controlling up to 16 servo-driven feeding doors.
+
+![Adafruit PCA9685 16-channel PWM servo driver board and DHT22 climate sensor](docs/images/hero.png)
+
+**Status: in progress**
+
+### What it does
+* Controls up to 16 independent servo motors via PCA9685 I2C driver to open and close feeder hatch doors
+* Reads temperature and humidity across 3 enclosure zones using DHT22 sensors every 30 seconds
+* Exposes Web UI on port 80 and streams real-time MQTT telemetry to Home Assistant
+* Supports Over-The-Air (OTA) firmware updates for hands-off maintenance
+
+### Bill of Materials
+| Part | Quantity | Purpose |
+| :--- | :---: | :--- |
+| ESP32 Development Board | 1 | Microcontroller running Wi-Fi web server, MQTT, and OTA |
+| Adafruit PCA9685 PWM Driver | 1 | 16-Channel 12-bit PWM I2C servo controller board |
+| TowerPro Servos (SG90/MG996R) | Up to 16 | Actuators for opening/closing reptile feeding hatch doors |
+| DHT22 Temperature/Humidity Sensors | 3 | Multi-zone climate sensors on GPIO 6, 7, and 18 |
+| 5V 5A External DC Power Supply | 1 | High-current power source for servo motor rails |
+
+### How it works
+Firmware uses I2C (SDA GPIO 10, SCL GPIO 11) to offload PWM servo timing to the PCA9685 chip, avoiding ESP32 interrupt jitter. Sensor readings from 3 DHT22 pins are published to Home Assistant via MQTT every 30 seconds.
+
+### What broke
+* Initial simultaneous movement of multiple SG90 servos caused voltage sags on the 5V rail, causing the ESP32 to brown out until a dedicated 5V 5A external power supply was separated from the ESP32 logic power.
+
+### Links
+* Gitea Repository: [sam/reptile_feeder](https://gitea.lab.audasmedia.com.au/sam/reptile_feeder)
diff --git a/docs/images/README.md b/docs/images/README.md
new file mode 100644
index 0000000..7d3f1ae
--- /dev/null
+++ b/docs/images/README.md
@@ -0,0 +1,5 @@
+# Hardware Images Manifest
+
+`hero.png` — Transparent background cut-out of the Adafruit PCA9685 16-channel PWM servo driver board and DHT22 climate sensor layout for theme-agnostic README rendering.
+
+`hero-site.webp` — Portfolio dark-canvas render (1600×1000px, `#0b0d10` canvas with left gradient fade and `#8ecbff` rim light) for the portfolio resume site.
diff --git a/docs/images/hero-site.webp b/docs/images/hero-site.webp
new file mode 100644
index 0000000..9e41908
Binary files /dev/null and b/docs/images/hero-site.webp differ
diff --git a/docs/images/hero.png b/docs/images/hero.png
new file mode 100644
index 0000000..bcafacf
Binary files /dev/null and b/docs/images/hero.png differ