diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..f5cf241
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,11 @@
+# puppy-tracker — notes for Claude
+
+- **Every user-visible change must add an entry to `src/changelog.json`**
+  (newest first, `{ "date": "YYYY-MM-DD", "text": "..." }`). The update banner
+  shows users the entries their new version adds compared to the build they're
+  running, so a missing entry means the change ships silently. Internal-only
+  changes (refactors, server plumbing) don't need one.
+- Commit messages: no Claude attribution / Co-Authored-By lines.
+- Run locally: `nix develop -c sh -c 'cd server && go run . -static ../src -data /tmp/puppy.db -invite-code letmein'`
+- Architecture details are in `README.md` (offline-first PWA, LWW sync with
+  tombstones, per-user data scoping).