diff --git a/.controlplane/readme.md b/.controlplane/readme.md
index 735f133a..b0518bd2 100644
--- a/.controlplane/readme.md
+++ b/.controlplane/readme.md
@@ -89,6 +89,19 @@ self-review, and consider disabling administrator bypass. Do not store
 promotion wrapper does not use `secrets: inherit`; GitHub exposes the production
 token only after the environment approval gate passes.
 
+If promotion fails with
+`CPLN_TOKEN_PRODUCTION is not set. Add it as a secret on the 'production' GitHub Environment.`,
+the token is missing from the environment scope. A repository or organization
+secret with the same name is not enough for this workflow. Create or verify the
+environment secret with:
+You need permission to manage repository environments and secrets to run these
+commands.
+
+```sh
+gh secret set CPLN_TOKEN_PRODUCTION --repo shakacode/react-webpack-rails-tutorial --env production
+gh secret list --repo shakacode/react-webpack-rails-tutorial --env production
+```
+
 The matching Control Plane resources are:
 
 | Resource | Name |
diff --git a/.controlplane/shakacode-team.md b/.controlplane/shakacode-team.md
index cd4926c6..01b828eb 100644
--- a/.controlplane/shakacode-team.md
+++ b/.controlplane/shakacode-team.md
@@ -59,6 +59,19 @@ passes `production_environment: production`; the upstream reusable workflow runs
 its production job in that environment, and GitHub injects the production token
 only after approval.
 
+If promotion fails with
+`CPLN_TOKEN_PRODUCTION is not set. Add it as a secret on the 'production' GitHub Environment.`,
+the token is missing from the environment scope. A repository or organization
+secret with the same name is not enough for this workflow. Create or verify the
+environment secret with:
+You need permission to manage repository environments and secrets to run these
+commands.
+
+```sh
+gh secret set CPLN_TOKEN_PRODUCTION --repo shakacode/react-webpack-rails-tutorial --env production
+gh secret list --repo shakacode/react-webpack-rails-tutorial --env production
+```
+
 Generated caller workflows pass only the named secrets each upstream workflow
 needs. They do not use `secrets: inherit`; `CPLN_TOKEN_PRODUCTION` is supplied
 only by the protected `production` Environment after approval.
diff --git a/.github/cpflow-help.md b/.github/cpflow-help.md
index 77b20ee2..f4f9be88 100644
--- a/.github/cpflow-help.md
+++ b/.github/cpflow-help.md
@@ -70,6 +70,19 @@ prevent self-review. The generated promotion wrapper passes only the staging
 token from repository secrets; GitHub injects `CPLN_TOKEN_PRODUCTION` only after
 the environment approval gate passes.
 
+If promotion fails with
+`CPLN_TOKEN_PRODUCTION is not set. Add it as a secret on the 'production' GitHub Environment.`,
+the token is missing from the environment scope. A repository or organization
+secret with the same name is not enough for this workflow. Create or verify the
+environment secret with:
+You need permission to manage repository environments and secrets to run these
+commands.
+
+```sh
+gh secret set CPLN_TOKEN_PRODUCTION --repo shakacode/react-webpack-rails-tutorial --env production
+gh secret list --repo shakacode/react-webpack-rails-tutorial --env production
+```
+
 Before the first promotion, bootstrap the production app the same way in the
 production org, using production-only secrets and values.