deploy.yml: fix pipeline compile error 'missing closing brace' -- the documentation comment itself contained a literal dollar-brace sequence with invalid contents (dollar-brace CI_...), which Woodpecker's substitution engine parses even inside comments. Rewrote header to describe the rules in words without any literal dollar-brace sequences. Also removed backtick-quoted dollar-brace remnants from the vaultwarden case comment.

.woodpecker/deploy.yml

@@ -5,22 +5,27 @@ when:
 # ─────────────────────────────────────────────────────────────────────────────
 # IMPORTANT — Woodpecker variable substitution rules (learned the hard way):
 #
-#   Woodpecker pre-processes command strings BEFORE the shell runs them:
-#     - ${VAR}  is substituted at pipeline-compile time from Woodpecker's own
-#       metadata (CI_* vars). Secrets DO NOT exist in that map, so any braced
-#       reference to a secret-backed env var silently becomes an EMPTY STRING.
-#     - $$      is unescaped to a single $ and passed to the shell.
+#   Woodpecker pre-processes the ENTIRE yaml text (comments included!) before
+#   the shell runs anything:
+#     - A dollar sign followed by a braced variable name is substituted at
+#       pipeline-compile time from Woodpecker's own metadata (the CI_* vars).
+#       Secrets DO NOT exist in that map, so a braced reference to a
+#       secret-backed env var silently becomes an EMPTY STRING.
+#     - A double dollar sign is unescaped to a single dollar sign and passed
+#       through to the shell untouched.
 #
 #   Therefore:
-#     - Use ${CI_...} (braced, unescaped) ONLY for Woodpecker metadata vars.
-#     - Use $${VAR} for anything that must be resolved by the shell at runtime
-#       (i.e., every from_secret-backed environment variable).
-#     - Bare $VAR (no braces) also works for runtime resolution, but $${VAR}
-#       is preferred for anything adjacent to other characters.
+#     - Braced, single-dollar form: ONLY for Woodpecker CI_* metadata vars.
+#     - Double-dollar braced form: for everything that must be resolved by the
+#       shell at runtime (i.e., every from_secret-backed environment variable).
+#     - Bare single-dollar VAR (no braces) also passes through to the shell.
+#     - NEVER write a literal dollar-brace sequence in comments either — the
+#       substitution engine parses comments too and will fail the pipeline
+#       with "missing closing brace" on anything it cannot parse.
 #
 #   This was the root cause of a long-running "SWARM_MANAGER_IP secret is
-#   empty" failure: the braced references were being blanked at compile time
-#   before the shell ever saw them.
+#   empty" failure: braced references were blanked at compile time before the
+#   shell ever saw them.
 # ─────────────────────────────────────────────────────────────────────────────
 
 steps:
@@ -200,10 +205,10 @@ steps:
                 create_or_update_secret 'productivity_oidc_providers'       '$${PRODUCTIVITY_OIDC_PROVIDERS}'";;
             vaultwarden)
               # NOTE: vaultwarden_database_url cannot be rotated in-place — Swarm refuses
-              # to `docker secret rm` a secret referenced by a running service's spec.
-              # We provision under a versioned name (_v2) instead; vaultwarden.yaml maps
-              # it back to the same in-container filename via `target:`. The old secret
-              # is removed manually once the compose file cutover is confirmed healthy.
+              # to remove a secret referenced by a running service's spec. We provision
+              # under a versioned name instead; vaultwarden.yaml maps it back to the same
+              # in-container filename via target. The old secret is removed manually once
+              # the compose file cutover is confirmed healthy.
               ssh -o StrictHostKeyChecking=no root@$${SWARM_MANAGER_IP} "source /tmp/cs.sh
                 create_or_update_secret 'vaultwarden_admin_token'     '$${VAULTWARDEN_ADMIN_TOKEN}'
                 create_or_update_secret 'vaultwarden_database_url_v2' '$${VAULTWARDEN_DATABASE_URL}'";;