README.md

@@ -312,8 +312,10 @@ examples/              the ~15-line stub a consuming repo drops in
 
 The image is published to `gitea.stevedudenhoeffer.com/steve/gadfly`. Every push to `main`
 rebuilds and republishes `:latest` (plus `:sha-<short>`); pushing a `v*` tag publishes that
-pinned version (plus `:latest`). Pin consumers to a `:vN` tag for stability, or track
-`:latest` to ride main.
+pinned version (plus `:latest`). Pin full-stub consumers to a `:vN` image tag for stability, or track
+`:latest` to ride main. Reusable-workflow consumers likewise pin the workflow ref —
+`review-reusable.yml@v1` (a curated tag moved on releases, so central swarm tuning propagates) or
+a full `@<sha>` for an immutable pin; avoid `@main`.
 
 ## Configuration (advanced)
 

examples/reusable.yml

@@ -14,9 +14,10 @@
 # Forward ONLY the secrets the reviewer uses (least privilege) — see the
 # `secrets:` block below. GITEA_TOKEN is automatic. `secrets: inherit` also works
 # but hands the reusable EVERY secret in your repo (registry/deploy/db creds the
-# review never touches), so prefer the explicit form. Pin @<sha> to an immutable
-# Gadfly commit (not @main) so a push there can't change what runs with your
-# secrets.
+# review never touches), so prefer the explicit form. Pin @<ref>: use the @v1
+# release tag (a curated pointer moved on deliberate releases) for auto-updating
+# stability, or a full @<sha> for an immutable pin. Avoid @main — it moves on
+# every push and would change what runs with your forwarded secrets.
 #
 # For custom named endpoints (GADFLY_ENDPOINT_<NAME>) or a provider the reusable
 # doesn't map, use the full stub in adversarial-review.yml instead.
@@ -48,9 +49,9 @@ jobs:
     if: >-
       github.event_name != 'issue_comment'
       || (github.event.issue.pull_request && github.actor == 'your-username')
-    # Pin @<sha> to an immutable Gadfly commit (replace @main below) so a push to
-    # gadfly can't silently change the code that runs with your forwarded secrets.
-    uses: steve/gadfly/.gitea/workflows/review-reusable.yml@main
+    # @v1 = curated release tag (auto-updates on releases); swap for a full @<sha>
+    # if you want an immutable pin. Don't use @main (moves on every push).
+    uses: steve/gadfly/.gitea/workflows/review-reusable.yml@v1
     # Forward ONLY what the reviewer needs. Add provider keys you use
     # (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, GADFLY_API_KEY) and/or
     # GADFLY_ENDPOINT_M1/M5; drop the findings ones if you don't run telemetry.