docs(setup): document the existing validate+init stale-relay resync path

AGENTS.md

@@ -24,6 +24,7 @@ Things that break silently. Never violate; when in doubt, read the named module'
 
 - No LLM calls in the orchestrator control loop.
 - Sessions complete only on hook Stop events or window death — never on LLM prose. Never add another completion path. Post-session state is re-verified deterministically (`verify.py`).
+- The installed hook relay (`.bmad-loop/bmad_loop_hook.py`) is a copy laid down by `init`, so it goes stale when the orchestrator upgrades; `bmad-loop validate` flags that via the `hooks.relay-stale` warning, and `bmad-loop init` is the existing resync — re-run it to refresh the copy. That resync is reliable only when the relay was never installed before; if a stale marker already exists, re-running `init` after an upgrade that changes the registered command's shape can report "hooks already registered" without updating it (see [#563](https://github.com/bmad-code-org/bmad-loop/issues/563)).
 - `sprintstatus.advance()` is the orchestrator's sole write path to sprint-status.yaml (internally serialized cross-process since #469; the dev skill flips only spec frontmatter; the engine mirrors it onto the board pre-verify). Legal phase transitions live only in `statemachine.py`.
 - All git subprocess calls in `src/bmad_loop` go through the `_run_git` chokepoint in `verify.py` (timeouts, `LC_ALL=C`) — no bare subprocess git; `tests/test_portability_guard.py` enforces it. Tests, `scripts/`, and CI workflows deliberately spawn their own git: a harness must not depend on the artifact it validates.
 - Every new policy field needs an entry in `src/bmad_loop/data/settings/core.toml` (a sync test enforces defaults/options match `policy.py`). New core env vars register in `envvars.py`; plugin-owned env-var families stay with their plugin.

CHANGELOG.md

@@ -167,6 +167,9 @@ breaking changes may land in a minor release.
 
 ### Changed
 
+- **Docs: documented that bmad-loop validate detects a stale hook relay and bmad-loop init
+  resyncs it.**
+
 - **`bmad-loop diagnose --json` reports `schema_version: 4`.** Journal `path` values
   become `path_present`; stale-restore and merge filename lists become counts.
 

docs/setup-guide.md

@@ -325,6 +325,13 @@ bmad-loop validate --project <project-root>
 yet, or `bmad-sprint-planning` hasn't run). On a fresh project that is **expected** — read its
 output as a readiness checklist, not an install failure.
 
+`validate` also detects a stale copy of the installed hook relay
+(`.bmad-loop/bmad_loop_hook.py`) with the `hooks.relay-stale` warning, and `bmad-loop init` is
+the existing resync for it — re-run `init` to refresh the copy. That resync is reliable when
+the relay was never installed before, but re-running `init` after an upgrade that changes the
+registered command's shape can report "hooks already registered" without actually updating an
+already-stale entry; see [#563](https://github.com/bmad-code-org/bmad-loop/issues/563).
+
 For the dashboard itself, see [docs/tui-guide.md](tui-guide.md). For the full policy
 reference, see the [Policy section](../README.md#policy-bmad-looppolicytoml) of the README.