diff --git a/docs/workflows/gh-aw-estc-pr-buildkite-detective.md b/docs/workflows/gh-aw-estc-pr-buildkite-detective.md
index d037619..bf43f6b 100644
--- a/docs/workflows/gh-aw-estc-pr-buildkite-detective.md
+++ b/docs/workflows/gh-aw-estc-pr-buildkite-detective.md
@@ -21,6 +21,8 @@ Ingress routes here when:
 - `github.event.context` contains `buildkite`, and
 - Dashboard gating allows `estc-pr-buildkite-detective` (or no dashboard issue is present, so all workflows are enabled).
 
+Ingress routing is based on those event and dashboard conditions only; it does not check whether `BUILDKITE_API_TOKEN` is present. If the consumer mapping from `BUILDKITE_LOGS_API_TOKEN` is missing, the required `workflow_call` secret contract fails and the detective job cannot start.
+
 The job `estc-pr-buildkite-detective` calls:
 
 - [elastic/ai-github-actions/.github/workflows/gh-aw-estc-pr-buildkite-detective.lock.yml@copilot/reduce-comment-spamming](https://github.com/elastic/ai-github-actions/blob/copilot/reduce-comment-spamming/.github/workflows/gh-aw-estc-pr-buildkite-detective.lock.yml)
diff --git a/docs/workflows/oblt-aw-client-template.md b/docs/workflows/oblt-aw-client-template.md
index 89a3fcd..d7f4973 100644
--- a/docs/workflows/oblt-aw-client-template.md
+++ b/docs/workflows/oblt-aw-client-template.md
@@ -42,7 +42,7 @@ Job-level permissions (`run-aw`; must stay at least as permissive as nested ingr
 Required secret mapping:
 
 - `COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}`
-- `BUILDKITE_API_TOKEN: ${{ secrets.BUILDKITE_LOGS_API_TOKEN }}` (only required when `estc-pr-buildkite-detective` is enabled; consumers without Buildkite CI can omit this secret — ingress skips the job when the secret is absent)
+- `BUILDKITE_API_TOKEN: ${{ secrets.BUILDKITE_LOGS_API_TOKEN }}` (required when handling failed Buildkite `status` events for `estc-pr-buildkite-detective`; ingress does not check secret presence before routing, and the called workflow requires this secret)
 
 Migration note: if your repository previously used `BUILDKITE_API_TOKEN` as the consumer-facing secret name, rename or duplicate it as `BUILDKITE_LOGS_API_TOKEN`.