diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..058bce4
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,49 @@
+# Flipventory v2 – Claude Code Notes
+
+## Project context
+
+Inventory management for small/medium resellers who use "chaotic stockpiling":
+buy stuff in bulk, sort it later, track it through sale.
+
+Gitea repo: https://git.hohenberg.jp/martin/flipventory_v2  
+Original v1 repo (for reference): https://git.hohenberg.jp/martin/flipventory
+
+## Running the app
+
+```bash
+cp .env.example .env          # then edit SECRET_KEY at minimum
+uvicorn app.main:app --reload
+# → http://127.0.0.1:8000/docs
+```
+
+## Key business rules
+
+- `martin@hohenberg.jp` is ALWAYS admin. Enforced on every login in
+  `app/routers/auth.py`. Never remove this guard.
+- All other registered users are customers (`is_admin=False`).
+- Item hard-delete is admin-only. Customers archive items instead.
+
+## Tech stack
+
+- FastAPI 0.115 + uvicorn
+- SQLAlchemy 2.x (declarative ORM, SQLite default)
+- Pydantic v2 + pydantic-settings
+- JWT via python-jose (HS256), bcrypt via passlib
+
+## Gitea / tea CLI
+
+The `tea` CLI is at `~/bin/tea` and is logged in to `git.hohenberg.jp` as
+`martin`. Use it to work with issues:
+
+```bash
+tea issues list --login git.hohenberg.jp --repo martin/flipventory_v2
+tea issue create --login git.hohenberg.jp --repo martin/flipventory_v2 \
+    --title "..." --description "..."
+```
+
+## Commit conventions
+
+- Verbose, imperative commit messages
+- Format: `type: short summary\n\nLonger explanation`
+- Types: feat, fix, refactor, docs, test, chore
+- Always include `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`