diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8fb753e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,85 @@
+# Hearts
+
+A multiplayer Hearts card game with real-time gameplay via WebSockets. Shares accounts with [Hokm](../hokm) — log in with the same credentials on both games.
+
+## Requirements
+
+- Docker & Docker Compose
+- [Hokm](../hokm) installed at `/root/hokm` (provides card assets and shared user accounts)
+
+## Install
+
+```bash
+git clone git@git.goyban.com:goyban/hearts.git
+cd hearts
+cp .env.example .env
+# edit .env — see below
+```
+
+Then start:
+
+```bash
+docker compose up -d --build
+```
+
+Or use the helper script (stops, rebuilds, and tails logs):
+
+```bash
+./rerun.sh
+```
+
+The game is available at:
+- HTTP: `http://<host>:4000`
+- HTTPS: `https://<host>:4443` (self-signed cert, needed for PWA install)
+
+## .env reference
+
+```dotenv
+# Secret used to sign JWT session tokens. Change this to a random string.
+JWT_SECRET=hearts-secret-change-me
+
+# Username that gets admin privileges (access to /admin panel).
+# Leave empty to disable admin.
+ADMIN_USERNAME=
+
+# HTTP and HTTPS ports (must match docker-compose.yml port mapping if changed).
+PORT=4000
+HTTPS_PORT=4443
+
+# Path to Hokm's users.json so Hokm accounts work here too.
+# Docker path (default, matches the volume mount in docker-compose.yml):
+SHARED_USERS_FILE=/hokm-data/users.json
+# If running directly with `node server.js` instead of Docker, use:
+# SHARED_USERS_FILE=/root/hokm/data/users.json
+
+# Optional: Resend (resend.com) for email verification codes on signup.
+# Leave blank to skip email verification entirely.
+RESEND_API_KEY=
+RESEND_FROM=noreply@example.com
+
+# Optional: Cloudflare Turnstile CAPTCHA on the signup form.
+# Get keys at dash.cloudflare.com → Turnstile.
+# Leave blank to disable CAPTCHA.
+TURNSTILE_SITE_KEY=
+TURNSTILE_SECRET=
+```
+
+### Minimum required changes
+
+| Variable | What to set |
+|---|---|
+| `JWT_SECRET` | Any long random string (e.g. `openssl rand -hex 32`) |
+| `ADMIN_USERNAME` | Your username, to unlock the admin panel |
+
+Everything else is optional.
+
+## Updating
+
+```bash
+git pull
+./rerun.sh
+```
+
+## Data
+
+Game data (users, stats, config) is stored in `./data/` which is bind-mounted into the container. It persists across restarts and rebuilds.