diff --git a/README.md b/README.md
index 7431479..83b4a32 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,15 @@
 
 # Home‑Assistant Sunrise Alarm  
-**Turn your smart lights into a natural alarm clock**  
----
+_Turn your smart lights into a natural alarm clock_
 
-## Table of Contents
-1. [What it is & how it works](#what-it-is-&-how-it-works)  
-2. [Two‑step installation](#two‑step-installation)  
-   * 2.1 [sunrise‑simulation](#sunrise‑simulation)  
-   * 2.2 [sunrise‑alarm](#sunrise‑alarm)  
-3. [Configurable variables](#configurable-variables)  
-   * 3.1 `sunrise‑simulation` script variables  
-   * 3.2 `sunrise‑alarm` automation variables  
-4. [Customising the experience](#customising-the-experience)  
-5. [Troubleshooting & FAQ](#troubleshooting-&-faq)  
-6. [License](#license)  
+This script turns any compatible light (or group of lights) into a soft‑sunrise / sunset alarm.
+It gradually ramps the brightness and the colour temperature over a user‑defined period
 
+The script can also run in reverse mode, turning the light down to simulate a sunset.
+
+This project is made up of two blueprints
+- `sunrise-simulation.yaml`: Simulates a sunset/sunrise on a group of lights based on user-defined parameters
+- `sunrise-alarm.yaml`: Thin wrapper that calls the simulation script when trigger occurs.
 ---
 
 ## 1. What it is & how it works  
@@ -64,7 +59,7 @@
 2. **Create the automation**  
    * Pick an `input_datetime` that represents the clock you want to use as the alarm.  
    * Pick an `input_boolean` that toggles the alarm on or off.
-   * Choose a `offset_duration`
+   * Choose an `offest_duration` for how long before/after to start the sunrise arc relative to the alarm time. You'll usually want this to be the same as `duration` defined in the previous script, this time _negative_, so that the peak (end) of the arc aligns with the alarm time.
    * Choose the `sunrise‑simulation` script you created in the previous step for the `alarm_script` field.  
    * Save – you now have a ready‑to‑run alarm!