diff --git a/.github/workflows/auto-promote-staging-pr.yml b/.github/workflows/auto-promote-staging-pr.yml
index b908378..21f4d3a 100644
--- a/.github/workflows/auto-promote-staging-pr.yml
+++ b/.github/workflows/auto-promote-staging-pr.yml
@@ -28,7 +28,7 @@ name: Auto-promote staging → main (PR-based, reusable)
 #     pull-requests: write
 #   jobs:
 #     promote:
-#       uses: Molecule-AI/molecule-ci/.github/workflows/auto-promote-staging-pr.yml@main
+#       uses: Molecule-AI/molecule-ci/.github/workflows/auto-promote-staging-pr.yml@v1
 #       with:
 #         gates: "ci.yml,e2e-staging-canvas.yml,e2e-api.yml,codeql.yml"
 #         force: ${{ github.event.inputs.force == 'true' }}
diff --git a/README.md b/README.md
index b7415c0..83fb730 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@ name: CI
 on: [push, pull_request]
 jobs:
   validate:
-    uses: Molecule-AI/molecule-ci/.github/workflows/validate-plugin.yml@main
+    uses: Molecule-AI/molecule-ci/.github/workflows/validate-plugin.yml@v1
 ```
 
 ### Workspace template repos (`molecule-ai-workspace-template-*`)
@@ -23,7 +23,7 @@ name: CI
 on: [push, pull_request]
 jobs:
   validate:
-    uses: Molecule-AI/molecule-ci/.github/workflows/validate-workspace-template.yml@main
+    uses: Molecule-AI/molecule-ci/.github/workflows/validate-workspace-template.yml@v1
 ```
 
 ### Org template repos (`molecule-ai-org-template-*`)
@@ -34,7 +34,7 @@ name: CI
 on: [push, pull_request]
 jobs:
   validate:
-    uses: Molecule-AI/molecule-ci/.github/workflows/validate-org-template.yml@main
+    uses: Molecule-AI/molecule-ci/.github/workflows/validate-org-template.yml@v1
 ```
 
 ### Any repo with auto-merge enabled
@@ -51,7 +51,7 @@ permissions:
   pull-requests: write
 jobs:
   disable-auto-merge-on-push:
-    uses: Molecule-AI/molecule-ci/.github/workflows/disable-auto-merge-on-push.yml@main
+    uses: Molecule-AI/molecule-ci/.github/workflows/disable-auto-merge-on-push.yml@v1
 ```
 
 When the team lands more PR-time guards in this repo, add them as additional jobs in the same caller — keeps each consuming repo's footprint to one file.
diff --git a/docs/template-contract.md b/docs/template-contract.md
index c9833d3..da4107f 100644
--- a/docs/template-contract.md
+++ b/docs/template-contract.md
@@ -54,7 +54,7 @@ name: CI
 on: [push, pull_request]
 jobs:
   validate:
-    uses: Molecule-AI/molecule-ci/.github/workflows/validate-workspace-template.yml@main
+    uses: Molecule-AI/molecule-ci/.github/workflows/validate-workspace-template.yml@v1
 ```
 
 The reusable workflow checks out `molecule-ci` itself (into `.molecule-ci-canonical`) and runs the canonical `validate-workspace-template.py` from there — so no per-repo vendoring of the script is needed. The legacy `.molecule-ci/scripts/` directory in each template repo is being phased out.