diff --git a/CLAUDE.md b/CLAUDE.md
index 0c20c32..8fc54dc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -688,3 +688,54 @@ Last resort only. 5/16" socket + 6" extension into auxiliary drive hole. Turn cl
 ## Testing
 
 No hardware-in-the-loop tests yet. Protocol implementations can be mocked for unit testing — `FirmwareProtocol` is an ABC with clear method contracts.
+
+## Documentation Site
+
+| Property | Value |
+|----------|-------|
+| Repo | `git@git.supported.systems:warehack.ing/birdcage-docs.git` |
+| Local path | `site/` (separate git repo, not a subtree) |
+| Framework | Astro + Starlight |
+| Domain | `birdcage.warehack.ing` |
+| Server | `warehack-ing@warehack.ing:~/birdcage-docs/` |
+| Container | `birdcage-docs` (caddy:2-alpine serving static files) |
+
+### Workflow
+
+```bash
+cd site/
+
+# Local development with HMR
+make dev          # Sets APP_ENV=dev, starts Astro dev server on :4321
+
+# Production build + deploy
+make prod         # Sets APP_ENV=prod, builds static site, serves via Caddy on :80
+
+# Other commands
+make logs         # Tail container logs
+make rebuild      # Down + up with fresh build
+make clean        # Remove containers + images
+```
+
+### Make Targets
+
+| Target | Description |
+|--------|-------------|
+| `up` | Build and start container |
+| `down` | Stop container |
+| `logs` | Tail container logs |
+| `rebuild` | Down + up with fresh build |
+| `dev` | Switch to dev mode (Astro dev server + HMR) |
+| `prod` | Switch to prod mode (static build + Caddy) |
+| `clean` | Remove containers, images, and volumes |
+
+### Deploying Updates
+
+```bash
+cd site/
+git add . && git commit -m "description"
+git push origin main
+ssh -A warehack-ing@warehack.ing "cd birdcage-docs && git pull && make prod"
+```
+
+TLS is automatic via caddy-docker-proxy (ACME + Vultr DNS challenge). New subdomains take ~2 minutes for certificate issuance.