diff --git a/CLAUDE.md b/CLAUDE.md
index bc1a8cd..eca20c6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -27,6 +27,23 @@ docs it indexes.
 - **Language is Go (ADR-001).** Do not introduce Python or a second language. If you think you
   need one, that's a new ADR with a real justification, not a default.
 
+## Deploying: a push does not deploy
+
+Tapir runs on the koala k3s cluster under Flux GitOps. Pushing here only builds the image;
+`kubectl set image` is reverted by Flux drift correction within seconds. The manifest bump is
+manual: Flux image-automation in `mathias/infra` covers only `supervisor`, not tapir (infra#111
+is closed, but `k3s/flux/flux-system/image-automation.yaml` has no tapir policy).
+
+1. CI (`.gitea/workflows/ci.yml`) builds and pushes `localhost:5000/tapir:<short-sha>` on the
+   main push.
+2. In `mathias/infra`, bump `image:` in `k3s/apps/tapir/deployment.yaml` to that sha; commit to
+   `main` (infra's own rules and full `task check` apply).
+3. On koala: `flux reconcile kustomization apps --with-source`, then
+   `kubectl -n tapir rollout status deploy/tapir`. Both need per-action approval in a session.
+4. Confirm the running image is the new sha and the startup log shows the new code.
+
+Runbook and why: brain `homelab/failures/flux-reverts-kubectl-set-image-deploy-via-git`.
+
 ## Things that look reusable but are NOT — read before "reusing"
 
 These caused real mistakes that were caught and corrected; the corrections are load-bearing.