diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..246f2b0
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,56 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Project Overview
+
+`river_monitor.py` polls the UK Environment Agency's real-time flood-monitoring API for river level stations within a configurable radius, archives readings to a local SQLite database, and optionally generates a self-contained HTML dashboard.
+
+## Synology / Website Integration
+
+The primary deployment target is a Synology NAS running Web Station, alongside the `simon/web` Gitea repo (theatari.com). The poller runs via DSM Task Scheduler (`synology-task.sh`) every 15 minutes with `--no-html`, writing only to the SQLite database. A `river.php` page in the web repo reads the DB and renders the dashboard as part of the site.
+
+### Database
+
+The DB is written to `data/river_levels.db` inside the web repo on the Synology (path configured in `synology-task.sh`). That directory is already shielded from direct web access by `data/.htaccess`.
+
+**Schema:**
+
+```
+stations: station_id TEXT PK, label TEXT, river_name TEXT, lat REAL, lon REAL
+
+readings: id INTEGER PK, station_id TEXT, measure_id TEXT, unit TEXT,
+          qualifier TEXT, value REAL, date_time TEXT, fetched_at TEXT
+          UNIQUE(measure_id, date_time)
+```
+
+**Useful query — latest reading per station:**
+
+```sql
+SELECT s.label, s.river_name, r.value, r.unit, r.date_time
+FROM stations s
+JOIN readings r ON r.station_id = s.station_id
+WHERE r.date_time = (
+    SELECT MAX(date_time) FROM readings WHERE station_id = s.station_id
+)
+ORDER BY s.label;
+```
+
+**Useful query — recent history for sparklines (last 50 readings per station):**
+
+```sql
+SELECT station_id, value, date_time
+FROM readings
+WHERE station_id = ?
+ORDER BY date_time DESC
+LIMIT 50;
+```
+
+### Instructions for the web repo Claude
+
+When adding the river page to `simon/web`:
+
+- Create `river.php` following the same structure as `blog.php`: open the DB with `new SQLite3('data/river_levels.db', SQLITE3_OPEN_READONLY)`, include `includes/header.php` and `includes/footer.php`, and render using existing CSS classes and custom property variables (never hardcode colours).
+- Add a "River" nav link in **all 6 nav locations**: `index.html`, `links.html`, `gifs.html`, `games.html`, `contact.html`, and `includes/header.php`. Mark it active in `river.php` the same way blog pages mark the Blog link active via `blog_nav_active()`.
+- The page should show current level + a small trend sparkline per station, consistent with the existing card/grid style.
+- Chart.js (already used in the standalone dashboard) can be loaded from CDN the same way other external scripts are used on the site.