diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b2d369e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,40 @@
+# Kimai Heatmap Plugin
+
+A GitHub-style activity heatmap for your [Kimai](https://www.kimai.org/) dashboard. See where your time went at a glance.
+
+![Activity Heatmap](docs/screenshot.png)
+
+## Features
+
+- Calendar heatmap showing daily tracked hours over the past year
+- Project filter dropdown
+- Click any day to jump to that day's timesheet
+- Streak counter and summary stats (total hours, daily average, busiest day)
+- Weekend visual distinction
+- Respects your configured start-of-week preference
+- Works with light and dark themes
+- Responsive — scrollable on small screens, resizes with the browser
+
+## Installation
+
+Copy the plugin into your Kimai `var/plugins/` directory:
+
+```bash
+cd /path/to/kimai
+git clone https://github.com/toph/kimai-heatmap.git var/plugins/KimaiHeatmapBundle
+bin/console kimai:reload
+```
+
+## Development
+
+Requires [Nix](https://nixos.org/):
+
+```bash
+nix develop
+process-compose up  # starts MariaDB + Kimai
+npm test            # run JS tests
+```
+
+## License
+
+MIT
diff --git a/docs/screenshot.png b/docs/screenshot.png
new file mode 100644
index 0000000..339a962
Binary files /dev/null and b/docs/screenshot.png differ