diff --git a/.woodpecker/pr-review.yml b/.woodpecker/pr-review.yml
index 846ba963..02847bb9 100644
--- a/.woodpecker/pr-review.yml
+++ b/.woodpecker/pr-review.yml
@@ -49,9 +49,12 @@
 # Triggering: pull_request only — automatic on PR open + push-to-open-PR. To
 # re-review a PR, push a commit (the new head sha clears the dedup marker below
 # and earns a fresh review). There is deliberately no manual PIPELINE trigger:
-# Woodpecker exposes `--var` values to YAML `${...}` substitution and `when`
-# filters only, NOT as a step's shell environment, so a `--var PR=<n>` re-review
-# would silently no-op (the step would find no PR number and exit green).
+# Woodpecker exposes a --var only to YAML variable substitution and `when`
+# filters, NOT to a step's shell environment, so a --var PR=<n> re-review would
+# silently no-op (the step would find no PR number and exit green).
+# (Note: keep literal dollar-brace out of THIS file entirely, even in comments —
+# Woodpecker runs its variable substitution over the whole YAML text, comments
+# included, and an unparseable one errors the pipeline before any step runs.)
 when:
   - event: pull_request