docs: recommend @v1 over @main in reusable-workflow adoption snippets (#16)

Closes the README half of monorepo task #133. The v1 git tag now
exists at the current main HEAD (8b0fbac — includes the auto-promote
fail-loud fix from #15). Consumers should pin reusable-workflow refs
to @v1 so future breaking changes land on @v2 with @v1 staying
backward-compatible — same pattern as `actions/checkout@v4`.

This commit only updates the EXAMPLE adoption snippets in the
workflow headers. Existing consumers pinned at @main keep working
identically (the workflow content is unchanged); they migrate at
their own pace when next touching their CI. New consumers see @v1
as the recommended pin.

Touched:

  - auto-promote-branch.yml (also added a paragraph explaining the
    @v1 vs @main convention so future contributors don't reintroduce
    @main as the recommendation)
  - auto-promote-staging.yml (the snippet inside this file's header
    references auto-promote-branch.yml, also moved to @v1)
  - disable-auto-merge-on-push.yml
  - publish-template-image.yml

The validate-* workflows (validate-plugin.yml, validate-org-template.yml,
validate-workspace-template.yml) don't have adoption snippets in their
headers — adding canonical examples there is a separate scope and not
part of this PR.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.github/workflows/auto-promote-branch.yml

@@ -21,7 +21,7 @@ name: Auto-promote branch (reusable)
 #     administration: read     # read branch protection (REQUIRED — see below)
 #   jobs:
 #     promote:
-#       uses: Molecule-AI/molecule-ci/.github/workflows/auto-promote-branch.yml@main
+#       uses: Molecule-AI/molecule-ci/.github/workflows/auto-promote-branch.yml@v1
 #       with:
 #         from-branch: staging
 #         to-branch: main
@@ -29,6 +29,14 @@ name: Auto-promote branch (reusable)
 # Repo-agnostic by design — gates are read from the consuming repo's
 # branch protection at run time, not hardcoded here.
 #
+# `@v1` is a moving tag pointing at the latest 1.x release of
+# molecule-ci's reusable workflows (GitHub Actions convention, same
+# as `actions/checkout@v4`). Breaking changes get a new `@v2` tag
+# and the old `@v1` keeps working for existing consumers. Pinning to
+# `@main` is also accepted for forward-compat preview but is
+# unstable — any change merged here rolls out instantly to consumers
+# without a release boundary.
+#
 # `administration: read` is REQUIRED. Without it, the branch-protection
 # API returns 403 and the workflow refuses to fast-forward (fail-loud),
 # rather than silently degrading to --ff-only-only enforcement (which

.github/workflows/auto-promote-staging.yml

@@ -4,7 +4,7 @@ name: Auto-promote staging → main
 # `auto-promote-branch.yml` workflow factored out for org-wide reuse.
 # Other repos consume the same reusable workflow via:
 #
-#   uses: Molecule-AI/molecule-ci/.github/workflows/auto-promote-branch.yml@main
+#   uses: Molecule-AI/molecule-ci/.github/workflows/auto-promote-branch.yml@v1
 #
 # Excluded by policy: molecule-core + molecule-controlplane stay
 # manual per CEO directive 2026-04-24. Those repos do NOT call the

.github/workflows/disable-auto-merge-on-push.yml

@@ -22,7 +22,7 @@ name: Disable auto-merge on push
 #     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
 #
 # False-positive behavior: if a CI bot pushes (e.g. dependency-update
 # rebase, secret rotation), this also disables auto-merge for that

.github/workflows/publish-template-image.yml

@@ -17,7 +17,7 @@ name: Publish Workspace Template Image
 #     packages: write
 #   jobs:
 #     publish:
-#       uses: Molecule-AI/molecule-ci/.github/workflows/publish-template-image.yml@main
+#       uses: Molecule-AI/molecule-ci/.github/workflows/publish-template-image.yml@v1
 #       secrets: inherit
 #
 # Runner choice (2026-04-22): ubuntu-latest