diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9aa4f6c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,30 @@
+Ultra-low-power ESP32 outdoor porch security light controller with LoRa communication, PIR motion waking, ambient light sensing, and battery voltage protection.
+
+![ESP32 porch light controller with SX127x LoRa module, PIR motion sensor, and VEML7700 lux meter](docs/images/hero.png)
+
+**Status: in progress**
+
+### What it does
+* Wakes from ESP32 deep sleep on PIR motion (GPIO 13) or scheduled RTC wakeups
+* Measures ambient lux via I2C VEML7700 sensor to prevent activating porch lights during daylight
+* Drives high-voltage porch security light relay (GPIO 12) upon valid night-time motion
+* Transmits motion alerts, battery voltage (GPIO 34), and status via SX127x SPI LoRa radio
+
+### Bill of Materials
+| Part | Quantity | Purpose |
+| :--- | :---: | :--- |
+| ESP32 Development Board | 1 | Main MCU utilizing RTC memory and deep sleep wake pins |
+| SX127x LoRa Module | 1 | Long-range 915MHz SPI radio transceiver (CS GPIO 5, RST GPIO 14, DIO0 GPIO 26) |
+| PIR Motion Sensor | 1 | Infrared motion detection connected to RTC_GPIO14 / GPIO 13 |
+| VEML7700 Lux Sensor | 1 | High-accuracy I2C ambient light sensor for daylight lockout |
+| Relay Module | 1 | Solid-state or mechanical relay on GPIO 12 switching 12V/240V porch light |
+| Voltage Divider Sensor | 1 | Resistor divider on GPIO 34 for monitoring battery pack voltage |
+
+### How it works
+The system remains in deep sleep drawing microamps until the PIR sensor triggers RTC_GPIO14 or the RTC timer expires. Upon waking, it reads ambient light from the VEML7700 sensor; if lux is below `MAX_LUX_THRESHOLD` (50 lux) and battery voltage is above `minimumPower` (11.0V), it energizes relay GPIO 12 for `lightOnDuration` (30s) and broadcasts a LoRa packet.
+
+### What broke
+* False wakeups caused by floating inputs on the PIR signal line during deep sleep were resolved by enabling internal RTC pull-down resistors on GPIO 13 before calling `esp_deep_sleep_start()`.
+
+### Links
+* Gitea Repository: [sam/Porch_Security_Light](https://gitea.lab.audasmedia.com.au/sam/Porch_Security_Light)
diff --git a/docs/images/README.md b/docs/images/README.md
new file mode 100644
index 0000000..7a26e39
--- /dev/null
+++ b/docs/images/README.md
@@ -0,0 +1,5 @@
+# Hardware Images Manifest
+
+`hero.png` — Transparent background cut-out of the ESP32 security light controller, SX127x LoRa transceiver, PIR motion sensor, and VEML7700 light sensor 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..ac9b721
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..a7ce41b
Binary files /dev/null and b/docs/images/hero.png differ