diff --git a/README.md b/README.md
new file mode 100644
index 0000000..68d3cca
--- /dev/null
+++ b/README.md
@@ -0,0 +1,50 @@
+# FJR Tracker
+
+Small PHP webpage for tracking Yamaha FJR odometer and maintenance events.
+
+## Features
+
+- Current odometer overview
+- Km since purchase
+- Maintenance tracking for:
+  - oil changes
+  - front/rear tyre changes
+  - drive shaft oil
+  - brake pads
+  - registration/insurance
+- Recent event history
+- MQTT publishing for Home Assistant discovery and retained state topics
+
+## Files
+
+- `index.php` - single-page PHP app and MQTT publishing logic
+- `config.php` - local bike/app/MQTT configuration
+- `data/state.json` - current persisted state
+- `data/events.jsonl` - append-only event history
+- `img/` - bike images used by the page
+- `favicon.svg` - site icon
+
+## Runtime requirements
+
+- PHP with standard JSON/file functions
+- Webserver serving this directory
+- `mosquitto_pub` available on the server for MQTT publishing
+- Writable `data/` directory for the webserver user
+
+## MQTT
+
+On every saved event, the app publishes Home Assistant MQTT discovery plus retained state values using settings from `config.php`:
+
+- MQTT host/port
+- topic prefix
+- bike name/device metadata
+
+## Deployment
+
+This repo is deployed directly at:
+
+```text
+/var/www/html/fjr
+```
+
+Do not commit secrets or private credentials. Review `config.php` before sharing outside the private repository.