diff --git a/.gitea/workflows/publish.yml b/.gitea/workflows/publish.yml
index 2e12f90..047f8bb 100644
--- a/.gitea/workflows/publish.yml
+++ b/.gitea/workflows/publish.yml
@@ -11,10 +11,12 @@
 # GITEA_-prefixed names cannot be created. GITEA_TOKEN / GITHUB_TOKEN cannot push packages.
 #
 # Safety gate: branch protection on main, NOT a needs: dependency in this file.
-# The PR test jobs (fast-checks, api, harness in ci.yml) run on pull_request — they never
-# run in the same workflow invocation as publish.yml. Tests gate the PR; main is trusted to
-# be green because direct push and force push are blocked and the three required checks
-# (CI / fast-checks, CI / api, CI / harness) must pass before merge.
+# The PR test jobs (fast-checks, api, harness, gate in ci.yml) run on pull_request — they
+# never run in the same workflow invocation as publish.yml. Tests gate the PR; main is
+# trusted to be green because direct push and force push are blocked and the two required
+# checks (CI / fast-checks, CI / gate) must pass before merge. CI / api and CI / harness
+# are conditionally skipped on doc-only PRs and are gated via the always-running CI / gate
+# aggregate rather than being required directly.
 #
 # To bump the milestone tag at a milestone boundary: edit MILESTONE below.