diff --git a/IMPLEMENTATION.md b/IMPLEMENTATION.md
index dab2c4d..e5b54d9 100644
--- a/IMPLEMENTATION.md
+++ b/IMPLEMENTATION.md
@@ -240,7 +240,7 @@ Each type lives in `src/FrameProcessor/Domain/`. Tests in `tests/FrameProcessor.
 ### [x] 11.1 Run `PLAN.md` verification checklist top to bottom
 - All 8 steps pass (step 9, real frame, is optional from this codebase's perspective).
 
-### [ ] 11.2 README
+### [x] 11.2 README
 - Short `README.md` pointing at `SPEC.md`, `PLAN.md`, `CLAUDE.md` and showing the `docker compose up` + smoke-test commands.
 
 ---
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6031229
--- /dev/null
+++ b/README.md
@@ -0,0 +1,45 @@
+# Frame Processor
+
+Self-hosted ASP.NET Core (.NET 10) service that dithers and color-remaps images for
+Spectra 6 e-ink frames, persists the result to disk, and notifies the frame via MQTT.
+
+## Documentation
+
+- [`SPEC.md`](SPEC.md) — authoritative behavior contract.
+- [`PLAN.md`](PLAN.md) — implementation design and verification checklist.
+- [`CLAUDE.md`](CLAUDE.md) — load-bearing conventions and working notes.
+
+## Quick start
+
+```sh
+docker compose up --build
+```
+
+Brings up `frame-processor` on `:8080` plus a `mosquitto` broker on `:1883`.
+
+## Smoke tests
+
+```sh
+# Health (also reports MQTT connection state)
+curl http://localhost:8080/health
+
+# Upload a file
+curl -H "X-Api-Key: change-me" \
+     -F "image=@photo.jpg" \
+     http://localhost:8080/api/frames/living-room/image
+
+# Upload via URL
+curl -H "X-Api-Key: change-me" \
+     -H "Content-Type: application/json" \
+     -d '{"url":"https://example.com/photo.jpg"}' \
+     http://localhost:8080/api/frames/living-room/image-url
+
+# Fetch the processed PNG (the frame does this on MQTT signal)
+curl http://localhost:8080/i/aabbccddeeff.png > out.png
+
+# Watch MQTT publishes
+mosquitto_sub -t 'frames/#' -v
+```
+
+Configure frames in [`frames.json`](frames.json); service settings in
+[`appsettings.json`](appsettings.json) (or via `Mqtt__Host`-style env vars).