diff --git a/docs/ci.md b/docs/ci.md
index 6c6e4e2e..cddcf88b 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -45,6 +45,22 @@ blocks merge.
 `hive-forge ci-rerun --pr N` dispatches a `workflow_dispatch` retrigger
 without an empty commit.
 
+**`ci-rerun --pr` verifies the code but does not reliably move the PR's own
+status checks.** Measured directly (raw `GET /repos/.../actions/tasks`
+JSON): a genuine PR-triggered run carries `event: pull_request` with the
+`#<n>` pseudo-ref as its `head_branch`; a `ci-rerun --pr`-dispatched run
+carries `event: workflow_dispatch` with the real branch name instead.
+Forgejo's PR commit-status tracking appears scoped to `pull_request`-event
+runs specifically, so a dispatched run — even a genuinely successful one —
+never writes to that status slot. Reproduced with three dispatches on one
+PR over 20+ minutes, all genuinely green, the PR's own status unmoved
+throughout. **Always re-check `pr-status` after a dispatch and believe
+what it says — don't push a commit just to unwedge it, that's the
+empty-commit anti-pattern this verb exists to avoid.** If the code is
+verified green (`hive-forge ci-log --run <n> --job 0`, verdict is the
+last line) but the status is stuck, ask the operator to click "rerun" in
+the forge web UI — it's CSRF-gated, so only they can do it.
+
 ### Running checks locally
 
 Don't run `nix flake check` directly — it dispatches to the shared build farm and
diff --git a/hive-forge/src/verbs/ci_rerun.rs b/hive-forge/src/verbs/ci_rerun.rs
index db038425..00a822de 100644
--- a/hive-forge/src/verbs/ci_rerun.rs
+++ b/hive-forge/src/verbs/ci_rerun.rs
@@ -25,7 +25,9 @@
 //!   `artifact-get`) and dispatches the SAME workflow on the SAME ref the
 //!   run used (the run record's `prettyref` + `workflow_id`).
 //!
-//! Dispatch re-runs the whole workflow, so there is no single-job variant.
+//! Dispatch re-runs the whole workflow (no single-job variant). ⚠️ `--pr`
+//! verifies the code but doesn't reliably move the PR's own status
+//! checks — see `docs/ci.md`'s "CI checks" for why; re-check `pr-status`.
 
 use anyhow::{Context as _, Result, bail};
 use clap::Args as ClapArgs;