diff --git a/README.md b/README.md
index 0448383..3c9f7a0 100644
--- a/README.md
+++ b/README.md
@@ -1,76 +1,30 @@
-# Smart Fish Feeder (ESP32 + MQTT)
+Automated aquarium feeder and DS18B20 water temperature monitoring system integrated with Home Assistant via MQTT.
 
-An automated aquarium feeder system based on the ESP32. It dispenses food via a motor pulse triggered by Home Assistant and continuously monitors tank temperature.
+![ESP32 aquarium feeder controller with DS18B20 waterproof temperature probe](docs/images/hero.png)
 
-## ⚡ Features
-*   **Remote Feeding:** Trigger a measured feed pulse via MQTT (`tank/feed`).
-*   **Temperature Monitoring:** Reports water temp every 10 seconds via MQTT (`tank/temperature`).
-*   **Home Assistant Integration:** Fully compatible with HA Dashboards and Automation.
-*   **Safe Power Design:** Optically isolated power rails (ESP32 vs Motor) to prevent brownouts.
+**Status: running**
 
-## 🛠 Hardware List
-*   **Microcontroller:** ESP32-D0WD-V3 (DevKitC)
-*   **Actuator:** DC Motor (3V-6V) with auger/screw mechanism
-*   **Switching:** N-Channel MOSFET (IRFZ44N)
-*   **Sensor:** DS18B20 Waterproof Temperature Sensor
-*   **Protection:** 
-    *   1N5822 Schottky Diode (Flyback protection)
-    *   10kΩ Pull-down Resistor (Gate to GND)
-*   **Power:** 
-    *   USB-C (5V) for ESP32
-    *   External 5V/12V DC Adapter for Motor
+### What it does
+* Triggers automated 0.5-second motor feed cycles on demand or on schedule via Home Assistant MQTT (`tank/feed`)
+* Monitors aquarium water temperature continuously using a waterproof DS18B20 sensor probe
+* Reports temperature updates over MQTT (`tank/temperature`) every 10 seconds
+* Optically isolates motor high-current power rails from ESP32 logic power to prevent brownouts
 
-## 🔌 Wiring & Pinout
+### Bill of Materials
+| Part | Quantity | Purpose |
+| :--- | :---: | :--- |
+| ESP32 DevKitC Board | 1 | Microcontroller running Wi-Fi, MQTT client, and OneWire protocol |
+| 3V-6V DC Feeder Motor | 1 | Drives auger screw mechanism for dispensing fish food |
+| IRFZ44N N-Channel MOSFET | 1 | Low-side solid-state switch driving DC motor from GPIO 27 / GPIO 2 |
+| DS18B20 Waterproof Probe | 1 | Submersible temperature sensor on GPIO 14 |
+| 1N5822 Schottky Diode | 1 | Flyback diode across motor terminals protecting MOSFET against inductive spikes |
+| Resistors (10kΩ & 4.7kΩ) | 2 | Gate pull-down (10kΩ) and OneWire bus pull-up (4.7kΩ) |
 
-**⚠️ CRITICAL:** The ESP32 and Motor Power Supply must share a **Common Ground**, but 5V lines should remain separate to prevent noise/brownouts.
+### How it works
+The ESP32 drives the IRFZ44N MOSFET gate via GPIO 27 / GPIO 2 to pulse the 5V/12V DC motor for 500ms when an MQTT feed payload is received. The DS18B20 waterproof probe communicates via OneWire on GPIO 14 to report water temperature every 10 seconds.
 
-### GPIO Config
-| Component | Pin | ESP32 GPIO | Notes |
-| :--- | :--- | :--- | :--- |
-| **MOSFET Gate** | Left Leg | **GPIO 27** | Use 10kΩ Pull-down to GND |
-| **Temp Data** | Yellow Wire | **GPIO 14** | Requires 4.7kΩ Pull-up (if not on module) |
+### What broke
+* Inductive kickback from the DC motor initially caused random ESP32 reboots during feeding pulses until a 1N5822 Schottky flyback diode was installed across the motor terminals and common ground was established.
 
-### Circuit Diagram (MOSFET)
-*   **Gate (Left):** -> GPIO 27
-*   **Drain (Middle):** -> Motor Negative (-)
-*   **Source (Right):** -> Common GND
-*   **Motor (+):** -> External Power 5V
-*   **Diode:** Across Motor Terminals (Silver stripe to +5V)
-
-## 💻 Firmware Configuration
-
-**Dependencies (Arduino IDE):**
-*   `PubSubClient` (Nick O'Leary)
-*   `OneWire`
-*   `DallasTemperature`
-
-**Setup:**
-1.  Update `ssid`, `pass`, and `mqtt_server` in `fish_feeder.ino`.
-2.  Set `MOTOR_PIN` (Default: 27) and `TEMP_PIN` (Default: 14).
-3.  Upload.
-
-## 🏠 Home Assistant Integration
-
-### 1. Manual Configuration (YAML)
-Add to `configuration.yaml` to create entities:
-
-```yaml
-mqtt:
-  sensor:
-    - name: "Fish Tank Temperature"
-      state_topic: "tank/temperature"
-      unit_of_measurement: "°C"
-      device_class: temperature
-      unique_id: "fishtank_temp_01"
-
-  button:
-    - name: "Feed Fish"
-      command_topic: "tank/feed"
-      payload_press: "pulse"
-      icon: mdi:fish
-      unique_id: "fishtank_feed_btn"
-```
-
-### 2. Dashboard (Lovelace)
-*   **Temperature:** Use a `Gauge` card linked to `sensor.fish_tank_temperature`.
-*   **Feeder:**
+### Links
+* Gitea Repository: [sam/fish_feeder_temperature](https://gitea.lab.audasmedia.com.au/sam/fish_feeder_temperature)
diff --git a/docs/images/README.md b/docs/images/README.md
new file mode 100644
index 0000000..ae41a90
--- /dev/null
+++ b/docs/images/README.md
@@ -0,0 +1,5 @@
+# Hardware Images Manifest
+
+`hero.png` — Transparent background cut-out of the ESP32 aquarium feeder controller, DS18B20 temperature probe, and MOSFET motor driver circuit 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..61e6bd2
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..afbfa88
Binary files /dev/null and b/docs/images/hero.png differ