diff --git a/.changeset/review-otlp-secrets-docs.md b/.changeset/review-otlp-secrets-docs.md
new file mode 100644
index 00000000..628f947d
--- /dev/null
+++ b/.changeset/review-otlp-secrets-docs.md
@@ -0,0 +1,5 @@
+---
+"review": patch
+---
+
+Document the `GH_AW_OTEL_SENTRY_ENDPOINT` / `GH_AW_OTEL_SENTRY_AUTHORIZATION` secrets as a hard install prerequisite (README required-secrets section plus the comment on the `observability:` block). A consuming repo without them does not degrade gracefully: the compiled lock feeds the empty endpoint into the MCP gateway's OTLP config, whose schema rejects it, and the agent job dies at startup (observed on Khan/actions#241). Repos without Sentry must comment out the `observability:` block in their installed review.md and recompile.
diff --git a/workflows/review/README.md b/workflows/review/README.md
index 6f43c20b..7bb5ec24 100644
--- a/workflows/review/README.md
+++ b/workflows/review/README.md
@@ -209,6 +209,15 @@ measurements to run after the suite exists.
 - `ANTHROPIC_API_KEY` — used by the `claude` engine.
 - `KHAN_ACTIONS_BOT_TOKEN` — referenced by `config.md`'s `add-reviewer` (the default
   `GITHUB_TOKEN` cannot request organization teams as reviewers).
+- `GH_AW_OTEL_SENTRY_ENDPOINT` and `GH_AW_OTEL_SENTRY_AUTHORIZATION` — the Sentry
+  OTLP traces endpoint and `x-sentry-auth` header value read by the
+  `observability:` block (value formats are documented at the block in
+  `review.md`). Hard-required while that block is present: a missing secret
+  compiles to an empty endpoint URL, the MCP gateway's OTLP config schema
+  rejects it, and the agent job dies at startup instead of skipping trace
+  export (observed on Khan/actions#241). A repo without these secrets must
+  comment out the `observability:` block in its installed `review.md` as a
+  local edit (which `gh aw update` preserves) and recompile.
 
 ## Versioning
 
diff --git a/workflows/review/review.md b/workflows/review/review.md
index 4d4c88ba..3a592ead 100644
--- a/workflows/review/review.md
+++ b/workflows/review/review.md
@@ -141,6 +141,11 @@ network:
 # (Settings → Secrets and variables → Actions): GH_AW_OTEL_SENTRY_ENDPOINT — the Sentry
 # OTLP traces endpoint with `/v1/traces` stripped (…/api/<project>/integration/otlp) — and
 # GH_AW_OTEL_SENTRY_AUTHORIZATION — the `sentry sentry_key=<public-key>` header value.
+# Both secrets are hard-required while this block is present: a missing one compiles to
+# an empty value that the MCP gateway's OTLP config schema rejects, so the agent job
+# dies at startup instead of skipping trace export. A repo without them must comment
+# this block out in its installed review.md (a local edit `gh aw update` preserves)
+# and recompile.
 observability:
   otlp:
     endpoint: