diff --git a/.env.example b/.env.example
index 5b7a1f9..2980ba0 100644
--- a/.env.example
+++ b/.env.example
@@ -73,3 +73,12 @@ CMS_URL=http://localhost:3001
 
 # Sandbox provider (default: docker; alternatives: podman, vercel, daytona)
 # SANDCASTLE_PROVIDER=docker
+
+# Agent iteration budgets. Sandcastle's `run()` cuts the agent off after N
+# iterations (one iteration = one tool-use + response round-trip). The
+# repo's defaults are tuned for typical work; bump if an agent gets cut
+# mid-commit (you'll see "Reached max iterations" in .sandcastle/logs/).
+#
+# SANDCASTLE_DECOMPOSE_ITERATIONS=10     # decompose: read PRD, write epic + stories, commit
+# SANDCASTLE_IMPLEMENTER_ITERATIONS=30   # implementer: full TDD slice (red test → green impl → gates → commit)
+# SANDCASTLE_REVIEWER_ITERATIONS=10      # reviewer: read diff + task, return decision