diff --git a/README.md b/README.md
new file mode 100644
index 0000000..37a5dac
--- /dev/null
+++ b/README.md
@@ -0,0 +1,37 @@
+# Why is the DLR shut today?
+
+A single-page site that displays one randomly chosen message in the centre of
+the screen. The message changes on every page load and whenever the
+**Check again** button is pressed.
+
+The site is themed around the Docklands Light Railway colour scheme, with a
+toggle between:
+
+- **Modern colours** — the current DLR turquoise/teal branding.
+- **Original colours** — the 1987 DLR red-and-blue livery.
+
+The chosen theme is remembered between visits via `localStorage`.
+
+## Adding messages
+
+Edit `messages.js` and fill the `MESSAGES` array with your own reasons — one
+string per entry. Entries are inserted as plain text. Until you add some, the
+page shows a fallback prompt.
+
+## Running
+
+It is a static site with no build step. Open `index.html` in a browser, or
+serve the directory with any static file server, for example:
+
+```sh
+python3 -m http.server
+```
+
+## Files
+
+| File          | Purpose                                          |
+| ------------- | ------------------------------------------------ |
+| `index.html`  | Page structure.                                  |
+| `styles.css`  | Both colour schemes, selected via `data-theme`.  |
+| `messages.js` | The list of messages (fill this in).             |
+| `script.js`   | Random message selection and the theme toggle.   |