diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..0d597e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,39 @@
+# McWaddams Site
+
+Personal portfolio and blog site generator built with Astro.
+
+- **Production**: https://mcwaddams.warehack.ing
+- **Git**: `git@git.supported.systems:warehack.ing/mcwaddams-site.git`
+- **Server**: `ssh -A warehack-ing@warehack.ing`, repo at `~/mcwaddams-site`
+
+## Stack
+
+- Astro (static output)
+- Docker multi-stage build (Node builder -> Caddy prod)
+- caddy-docker-proxy on external `caddy` network
+
+## Environment
+
+Copy `.env.example` to `.env`:
+
+```env
+COMPOSE_PROJECT_NAME=mcwaddams-site
+DOMAIN=mcwaddams.warehack.ing
+```
+
+## Commands
+
+```bash
+make up        # Build and start production container
+make down      # Stop container
+make logs      # Tail container logs
+make restart   # Stop + start
+make status    # Show running containers
+make clean     # Remove containers, images, volumes
+```
+
+## Deploy to Production
+
+```bash
+ssh -A warehack-ing@warehack.ing "cd ~/mcwaddams-site && git pull && make up"
+```