diff --git a/README.md b/README.md
index 14c5cc1..5312a05 100644
--- a/README.md
+++ b/README.md
@@ -50,6 +50,31 @@ workflow rebuilds this mirror + uploads the new wheel to PyPI.
 See [`docs/workspace-runtime-package.md`](https://github.com/Molecule-AI/molecule-core/blob/main/docs/workspace-runtime-package.md)
 for the full publishing flow.
 
+## PyPI is canonical, this git tree may lag
+
+**The PyPI wheel is the canonical artifact** for runtime consumers
+(workspace template images, the controlplane's runtime smoke harness,
+local `pip install` users). What's in PyPI and what's checked into this
+repo's git tree **may differ** — sometimes by hours, sometimes by days.
+
+Why: the [`publish-runtime`](https://github.com/Molecule-AI/molecule-core/blob/main/.github/workflows/publish-runtime.yml)
+workflow always publishes a fresh wheel built from `molecule-core`'s
+`staging` HEAD, but the git mirror push that updates this repo is a
+separate step and can lag (or, on transient failures, be skipped while
+the wheel still ships). The mirror exists for **human readability** and
+to give `mirror-guard` a concrete branch to enforce its
+"no direct PRs" policy against — not as the wire-truth artifact.
+
+**To check what's actually in a wheel:**
+
+```bash
+pip download molecule-ai-workspace-runtime==X.Y.Z --no-deps
+unzip -l molecule_ai_workspace_runtime-X.Y.Z-*.whl
+```
+
+If you're chasing "is module X in the published runtime yet?", trust
+the wheel listing, not this repo's `git log`.
+
 ## Why this split
 
 The runtime needs to ship as a PyPI artifact (so the 8 workspace template