diff --git a/docs/03-flux.md b/docs/03-flux.md
index bc04eee..36746e3 100644
--- a/docs/03-flux.md
+++ b/docs/03-flux.md
@@ -402,7 +402,16 @@ What it does need, that podinfo/headlamp don't, is a way to notice when CI
 publishes a new image and roll it out — that's
 `apps/hello-app/image-automation.yaml`'s job
 (`ImageRepository`/`ImagePolicy`/`ImageUpdateAutomation`, all commented in
-that file).
+that file). One easy-to-miss requirement, worth calling out explicitly
+since getting it wrong fails silently: `ImageUpdateAutomation` must live
+in the *same namespace* as the `ImagePolicy` it targets — the controller
+only ever lists `ImagePolicy` objects from its own namespace, so a
+cross-namespace `$imagepolicy` marker matches nothing, and every
+reconcile just reports "repository up-to-date" with no error and no
+commit, no matter how correct the marker syntax, RBAC, or policy
+resolution otherwise are (see `image-automation.yaml`'s own comment for
+the exact controller source line this comes from). `GitRepository` itself
+is fine to reference cross-namespace, via `sourceRef.namespace`.
 
 Exercise the whole loop end to end. Unlike the rest of this stage, this
 runs on your **desktop** (the `maq` clone from `docs/01-bootstrap.md` step