diff --git a/AGENTS.md b/AGENTS.md
index b47cb13..f3927e6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -59,6 +59,7 @@ Operational rule: **on any `release/*` branch, only bump the charts you actually
 - top-level `concurrency: { group: helm-chart-release, cancel-in-progress: false }`: all lines share one index, so releases must be serialized and an in-progress run must never be cancelled, or a release could be dropped.
 - `CR_SKIP_EXISTING: true`: already-released versions are skipped and the index is merged (not overwritten), so multiple branches are safe.
 - the GitHub Release tag is `<chart>-<version>` (e.g. `gateway-3.9.0`); the numbering rule keeps it unique across lines.
+- **a green release run does not mean published.** chart-releaser pushes one `gh-pages` commit per chart it releases, and pushes landing seconds apart get throttled: the Pages build is rejected before it runs (`status: errored`, `duration: 0`) while the workflow still reports success and the GitHub Release still exists. `charts.api7.ai` then keeps serving the previous `index.yaml`, so `helm repo update` never sees the new chart — and nothing alerts. Releasing two lines together (a `main` PR and a `release/*` PR merged back to back) reliably triggers it. After any release check `gh api repos/api7/api7-helm-chart/pages/builds --jq '.[0]'`; on a `duration: 0` error re-run it with `gh api --method POST repos/api7/api7-helm-chart/pages/builds` — the same commit builds fine on retry. `gh-pages`'s `index.yaml` is the source of truth for what chart-releaser produced; the served copy tells you what users can actually install.
 - `ci.yaml` (lint / ct install / helm-docs) also covers `release/**`.
 - after editing a chart, regenerate **every** chart's `README.md` with `helm-docs --chart-search-root=charts` — the CI check diffs all of them, not just the one you touched. Build the binary the way CI does, `go install github.com/norwoodj/helm-docs/cmd/helm-docs@v1.13.1`, and keep it first on `PATH` (the `helm-docs` pre-commit hook runs whatever it finds there). A **released** helm-docs binary — any version, v1.13.1's own tarball included — has a version string baked in and therefore appends an `Autogenerated from chart metadata...` footer to every README that has no `README.md.gotmpl`, which CI then rejects; a `go install` build carries no version string and omits the footer.