diff --git a/.env.example b/.env.example
index 32fac03a..8f044b7f 100644
--- a/.env.example
+++ b/.env.example
@@ -168,3 +168,18 @@ GSC_SERVICE_ACCOUNT=           # Search Console reporter service account email
 # Token goes in Authorization: Bearer header — never embed in the URL.
 MOLECULE_MCP_URL=                # e.g. https://api.molecule.ai or http://localhost:8080
 MOLECULE_MCP_TOKEN=              # workspace-scoped bearer token — NEVER COMMIT
+
+# ---- workspace-template image refresh ----
+# IMAGE_AUTO_REFRESH=true makes the platform poll GHCR every 5 min for digest
+# changes on each workspace-template-*:latest. When a digest moves the
+# platform pulls + force-recreates matching ws-* containers (same code path
+# as POST /admin/workspace-images/refresh). Closes the runtime CD chain to
+# zero operator steps.
+# Default in docker-compose.yml is "true" for local dev so the runtime → ws
+# loop is tight; explicit override here lets you turn it off when running a
+# long test that shouldn't be disturbed by a publish.
+IMAGE_AUTO_REFRESH=              # true|false; unset = inherit compose default (true for local dev)
+# GHCR_USER + GHCR_TOKEN are required only for private template images
+# (current workspace-template-* set is public; both can stay unset).
+GHCR_USER=
+GHCR_TOKEN=
diff --git a/docker-compose.yml b/docker-compose.yml
index 2be0d3f6..00a5a397 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -178,6 +178,15 @@ services:
       # public images (current state for all 8 templates).
       GHCR_USER: "${GHCR_USER:-}"
       GHCR_TOKEN: "${GHCR_TOKEN:-}"
+      # Auto-refresh workspace-template-* images. The watcher polls GHCR
+      # every 5 min; when a digest moves, it pulls and force-recreates any
+      # matching ws-* containers (existing /admin/workspace-images/refresh
+      # logic). Closes the runtime CD chain: merge → containers running
+      # new code, no operator step. Default ON for local dev because that's
+      # where the runtime → ws iteration loop is tightest. Set to "false"
+      # if you don't want the platform to mutate ws-* containers behind
+      # your back during a long-running test.
+      IMAGE_AUTO_REFRESH: "${IMAGE_AUTO_REFRESH:-true}"
     volumes:
       - ./workspace-configs-templates:/configs
       - ./org-templates:/org-templates:ro