diff --git a/README.md b/README.md
new file mode 100644
index 0000000..39b09ac
--- /dev/null
+++ b/README.md
@@ -0,0 +1,46 @@
+# new-shapes
+
+A shape editor desktop application built with Java Swing. Supports rectangles, circles, triangles, text, shape collections, resize handles, and export to HTML/SVG.
+
+## Prerequisites
+
+- JDK >= 16 (project targets Java 16)
+- A graphical display (X11/Wayland) since this is a Swing GUI application
+
+## Bootstrap
+
+### With Nix (recommended)
+
+```sh
+nix develop
+```
+
+This drops you into a shell with JDK 17 and Maven 3.9.x preconfigured. No other setup needed.
+
+### Without Nix
+
+Install JDK 16+ and use the bundled Maven wrapper — no separate Maven installation required:
+
+```sh
+./mvnw --version   # downloads Maven 3.9.12 on first run
+```
+
+## Run the application
+
+```sh
+./mvnw compile exec:java -Dexec.mainClass="ovh.gasser.newshapes.App"
+```
+
+## Run tests
+
+```sh
+./mvnw test
+```
+
+To run the full verification pipeline (compile, test, JaCoCo coverage check with 50% minimum line coverage):
+
+```sh
+./mvnw verify
+```
+
+Coverage reports are generated in `target/site/jacoco/`.