diff --git a/README.md b/README.md
new file mode 100644
index 0000000..16e7812
--- /dev/null
+++ b/README.md
@@ -0,0 +1,28 @@
+ESP32 Wi-Fi and MQTT to LoRa UART gateway bridging Home Assistant commands to remote garden watering solenoids.
+
+![ESP32 MQTT-to-LoRa gateway controller connected to RA-01 radio module and solenoid water valve](docs/images/hero.png)
+
+**Status: in progress**
+
+### What it does
+* Connects to Wi-Fi network and subscribes to Home Assistant MQTT topics (`homeassistant/ESP32/control`)
+* Receives irrigation schedule triggers and valve pulse duration commands from Home Assistant
+* Converts incoming MQTT messages into long-range LoRa packets over Serial2 (TX GPIO 17, RX GPIO 16)
+* Controls remote battery-powered solenoid watering nodes across the garden without Wi-Fi coverage
+
+### Bill of Materials
+| Part | Quantity | Purpose |
+| :--- | :---: | :--- |
+| ESP32 Development Board | 1 | Microcontroller handling Wi-Fi, PubSubClient MQTT, and UART bridge |
+| RA-01 LoRa SX1278 Module | 1 | 433MHz / 915MHz UART LoRa transceiver connected to Serial2 (pins 16/17) |
+| 12V DC Solenoid Water Valve | 1 | Remote irrigation control valve operated by distant LoRa receiver node |
+| MOSFET Driver / Relay Module | 1 | High-current valve actuator driver circuit on receiver node |
+
+### How it works
+The central ESP32 bridge stays connected to the local MQTT broker (`192.168.20.30`). When Home Assistant publishes a watering trigger to `homeassistant/ESP32/control`, the callback function captures the payload and immediately re-transmits it via UART (`Serial2` at 9600 baud on pins 16/17) to the RA-01 LoRa transmitter, reaching valves up to hundreds of meters away.
+
+### What broke
+* Software serial baud rate mismatches initially corrupted LoRa packets; switching to hardware UART (`Serial2` on GPIO 16/17) eliminated buffer overruns and frame drops.
+
+### Links
+* Gitea Repository: [sam/LoraMqttWatering](https://gitea.lab.audasmedia.com.au/sam/LoraMqttWatering)
diff --git a/docs/images/README.md b/docs/images/README.md
new file mode 100644
index 0000000..1e98634
--- /dev/null
+++ b/docs/images/README.md
@@ -0,0 +1,5 @@
+# Hardware Images Manifest
+
+`hero.png` — Transparent background cut-out of the ESP32 Wi-Fi MQTT bridge controller, RA-01 LoRa radio module, and solenoid water valve control 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..94ce150
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..1e406d9
Binary files /dev/null and b/docs/images/hero.png differ