diff --git a/CLAUDE.md b/CLAUDE.md
index ebf653d..068ddbb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -15,6 +15,17 @@ The repo is a small monorepo with two deployables plus an e2e harness at the roo
 
 ## Common commands
 
+Local dev stack (preferred for everyday work):
+
+```powershell
+./scripts/dev-up.ps1          # starts Postgres + API + frontend (each in its own window)
+./scripts/dev-db.ps1 start    # just the Postgres container (named yeschef-pg, on :5432)
+./scripts/dev-db.ps1 reset    # nuke the dev DB volume — next start is a fresh DB
+./scripts/dev-db.ps1 status   # connection string + container state
+```
+
+`dev-db.ps1` provisions a `postgres:17` container that matches the connection string baked into `appsettings.json` (`Host=localhost;Database=yeschef;Username=yeschef;Password=yeschef`). The API auto-applies migrations on startup. With no SMTP configured locally, outgoing emails (invites, password reset) print to the API log window via `LoggingEmailSender` — that's where to copy the join/reset URL from when manually testing those flows.
+
 Frontend (run from `src/frontend`, use `npm --prefix src/frontend <cmd>` to avoid `cd`):
 
 ```powershell