diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fb5d08c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,27 @@
+# Toadstool Tally
+
+PWA-friendly, cottagecore row counter for crochet/knitting projects. Manage projects and parts, set max stitches, lock/finish, and enjoy a themed experience with install support and offline caching.
+
+## Features
+- Add projects and parts; rename, delete, minimize, lock, or mark finished.
+- Increment/decrement counts, manual set, and per-part max stitch cap.
+- Dark/light toggle, focus mode (fullscreen + wake lock), haptic tick on count.
+- PWA ready: install prompt, manifest, service worker caching, offline-friendly.
+- Themed UI with footer artwork and responsive layout.
+
+## Development
+```bash
+# Open locally
+open index.html   # or use a simple HTTP server for PWA/service worker
+
+# Example dev server
+python3 -m http.server 8080
+```
+
+- Service worker requires an HTTP/HTTPS context; use a local server to test install/offline.
+- Data is stored in `localStorage`; clear it to reset.
+
+## PWA Notes
+- Manifest: `assets/site.webmanifest`
+- Service worker: `sw.js`
+- Install button appears when installable (desktop browsers that support `beforeinstallprompt`).