cpflow 6.0.0.rc.0 → 6.0.1

data/docs/ci-automation.md

@@ -23,7 +23,7 @@ End-to-end rollout in one view:
 
 1. `cpflow github-flow-readiness` — exits non-zero if the repo is not ready to deploy.
 2. `cpflow generate` — creates `.controlplane/` if missing.
-3. `cpflow generate-github-actions` — adds `cpflow-*` workflow wrappers and `.github/actions/cpflow-*` composite actions. Review-app, staging, cleanup, and helper workflows call upstream reusable workflows; production promotion is a normal caller-repo job so it can own the protected production Environment.
+3. `cpflow generate-github-actions` — adds `cpflow-*` workflow wrappers. Review-app, staging, cleanup, and helper workflows call upstream reusable workflows; production promotion is a normal caller-repo job so it can own the protected production Environment.
 4. Configure the [GitHub Actions secrets and variables](#github-actions-secrets-and-variables) the workflows expect.
 5. Push the branch, then comment `+review-app-deploy` on a PR to spin up a review environment.
 
@@ -69,7 +69,6 @@ The second command writes namespaced files so they can coexist with an app's exi
 - `.github/workflows/cpflow-deploy-staging.yml`
 - `.github/workflows/cpflow-promote-staging-to-production.yml`
 - `.github/workflows/cpflow-cleanup-stale-review-apps.yml`
-- `.github/actions/cpflow-*` (the local composite actions used by those workflows)
 - `bin/pin-cpflow-github-ref`
 - `bin/test-cpflow-github-flow`
 
@@ -77,7 +76,7 @@ The second command writes namespaced files so they can coexist with an app's exi
 Docker base Ruby version from `.ruby-version`, `.tool-versions`, or the app's
 `Gemfile`, preserves repo-defined frontend precompile hooks such as Shakapacker
 `precompile_hook` commands or React on Rails auto bundle generation, and
-switches to persistent SQLite `db` and `storage` templates when
+switches to persistent SQLite data and Active Storage templates when
 `config/database.yml` shows SQLite in production.
 
 `cpflow github-flow-readiness` checks public RubyGems and npm registry metadata
@@ -230,14 +229,74 @@ because they could change the target org name after normalization.
 
 Production promotion copies the exact image currently deployed on the selected
 staging workload. If that staging image is digest-pinned, the digest is used for
-the source copy while the production tag is derived from the tag portion. Tags
-with a `_<commit>` suffix keep that suffix in production; plain numeric tags are
-also valid and promote to the next plain production tag. The copy step uses
+the source copy while the production tag is derived from the tag portion. Staging tags must
+include a full lowercase 40-character Git commit SHA suffix (`_<commit>`),
+which is preserved in the new production tag. A staging image without that
+provenance stops promotion before approval. The copy step uses
 `docker buildx imagetools create --prefer-index=false --tag` with isolated
 Docker credentials, which preserves multi-architecture manifests, preserves
 single-platform manifest format when supported, and avoids pulling image layers
 onto the GitHub Actions runner.
 
+When you start production promotion, the **preview-promotion** job finishes
+before GitHub requests approval for the protected production Environment. Open
+the run summary’s **Commits ready for production** section before approving. It
+compares staging’s deployed primary-workload image with the last recorded
+successful `production-*` GitHub release. It links the full comparison, lists up
+to 100 commit subjects, and flags diverged history or staging behind production.
+Matching SHAs report no commits to promote. Release discovery checks the latest
+100 releases; missing production history or GitHub API failures produce an
+explicit availability notice. The preview uses the existing staging token and
+GitHub `contents: read` permission; it has no production token.
+
+The preview selects the primary workload from the staging app’s
+`app_workloads` configuration. `PRODUCTION_APP_NAME` and
+`CPLN_ORG_PRODUCTION` can remain production Environment variables. When staging
+and production have different primary-workload defaults, set `PRIMARY_WORKLOAD`
+as a repository variable shared by both jobs; the protected job rejects a
+workload-selection mismatch. A Control Plane read failure or invalid staging
+SHA fails the preview and prevents approval from starting.
+
+After approval, the protected job checks that staging still uses the captured
+image and, when a release baseline was available, that live production matches
+that release’s commit. A mismatch stops before copying or deploying an image;
+rerun after staging changes, or reconcile the production release record after an
+out-of-band production deployment. If production history was unavailable, the
+summary does not claim to know the production-to-staging diff.
+
+Existing repositories adopt this with
+`cpflow update-github-actions --workflows cpflow-promote-staging-to-production.yml`.
+Review and reapply downstream workflow customizations before committing the
+replacement. The bare update command preserves existing top-level workflows.
+
+### Recover a missing or stale production release record
+
+A successful production deployment and its GitHub release are separate jobs.
+If deployment succeeded but **create-github-release** failed, open that original
+Actions run and choose **Re-run failed jobs**. This retries release publication
+at the original promoted SHA; do not rerun the whole promotion merely to repair
+the record. Confirm the resulting `production-*` release targets the live
+production image’s SHA, then start a fresh promotion preview.
+
+After an out-of-band production deploy or rollback, an app maintainer should
+first verify the healthy live primary-workload image and its full commit suffix
+with `cpln workload get <primary-workload> --gvc <production-app> --org
+<production-org> -o json`. Use that SHA to publish a fresh release record; do not
+move an existing release tag. For example, after replacing `<verified-live-sha>`:
+
+```sh
+gh release create "production-$(date -u +%Y-%m-%d-%H%M%S)-0" \
+  --target <verified-live-sha> \
+  --title "Production state reconciliation" \
+  --notes "Records the verified live production commit after a manual deployment or rollback."
+```
+
+Run this in the app repository with the maintainer’s normal GitHub credentials.
+Verify the new tag’s commit and the live image agree, then rerun promotion to
+produce a fresh preview. If the live image has no commit suffix, establish its
+provenance and use a traceable image before recording a baseline; guessing a
+branch head would make the comparison misleading.
+
 Before copying the image, production promotion compares the environment variable
 names exposed by staging and production at both the GVC level and each configured
 app workload's container level. Variables present in staging are treated as
@@ -425,9 +484,11 @@ Recommended org layout:
   review/staging CI operations; use a dedicated review-app org only if you also customize the generated
   workflow/configuration to target that org separately
 
-Optional repository secret for private dependency builds:
+Optional repository secrets for Docker builds:
 
 - `DOCKER_BUILD_SSH_KEY`: private SSH key used when the Dockerfile needs `RUN --mount=type=ssh` to fetch private GitHub dependencies during image build
+- `DOCKER_BUILD_SECRETS`: staging build credentials as newline-delimited `id=value` entries supplied through BuildKit secret mounts. Values must be single-line; spaces and additional `=` characters are preserved. IDs may contain letters, digits, underscores, and hyphens, and must start with a letter or digit. Empty values and duplicate IDs are rejected. Leave this secret unset when the build does not need credentials.
+- `REVIEW_APP_DOCKER_BUILD_SECRETS`: separate credentials for review-app builds, using the same format. The generated review-app caller uses only this secret; it does not fall back to `DOCKER_BUILD_SECRETS`. Leave it unset to supply no BuildKit secrets to review apps.
 
 Optional repository variables for private dependency builds:
 
@@ -475,12 +536,11 @@ The generated flow uses these defaults:
   makes the newest intent fail closed instead of falling back to an older operation. This permission gate applies to every
   `+review-app-deploy` comment, whether or not a review app already exists. Later pushes to a base-repository branch PR
   redeploy automatically without another approval because the auto-push path (`pull_request` event) does not use the
-  comment permission gate. The reusable deploy workflow loads generated local actions through `actions/checkout`'s
-  default with no `ref:` override, which resolves to the commit GitHub recorded for the triggering event: the
-  pull-request merge revision for automatic same-repository deploys, the selected ref for manual dispatch, or the
-  default-branch revision for comment triggers. This keeps the wrapper and generated actions synchronized during an
-  upgrade or first-installation PR. Preserve the same-repository caller guard because pull-request workflow and action
-  code run with staging/review credentials;
+  comment permission gate. The reusable deploy workflow loads its composite actions from `shakacode/control-plane-flow`
+  at the commit the wrapper pins, never from the pull request's revision; see
+  [Where the actions run from](#where-the-actions-run-from). Preserve the same-repository caller guard because a
+  same-repository pull request can still change the wrapper and the application code that run with staging/review
+  credentials;
 - fork pull requests cannot deploy via the generated `pull_request` path because the caller workflow's job-level `if:`
   condition explicitly skips fork-originated runs. For `issue_comment` events, the caller `if:` restricts invocation to
   the exact command shape; the reusable workflow resolves repository permission before its deploy job runs, then its
@@ -516,11 +576,10 @@ generated staging/review org and make that token disposable and unable to access
 
 The PR-close teardown workflow runs trusted base-branch workflow code with repository secret access so it can delete fork
 PR review apps. The generated `cpflow-delete-control-plane-app` composite action script refuses to call `cpflow delete`
-on any app whose name does not match the review-app prefix. This shell-level guard is effective because the generated
-delete workflow loads generated actions through `actions/checkout`'s default with no `ref:` override, which resolves to
-the commit GitHub recorded for the triggering event (`GITHUB_SHA`, the base-branch tip under `pull_request_target`). Its
-separate app checkout has no `ref:` override either, so `pull_request_target` teardown uses base-branch code for both
-paths rather than PR or fork code. If you customize this
+on any app whose name does not match the review-app prefix. This shell-level guard is effective because the delete
+workflow loads that action from the wrapper-pinned `.cpflow` commit. Its separate app checkout has no `ref:` override,
+which resolves to the commit GitHub recorded for the triggering event (`GITHUB_SHA`, the base-branch tip under
+`pull_request_target`), so teardown reads base-branch configuration rather than PR or fork code. If you customize this
 workflow, never check out PR or fork code in the same job as the delete step; doing so could let a PR replace the guard
 script itself and would also make `hooks.pre_deletion` come from the PR's `controlplane.yml`. This is still not a token
 policy, so use a scoped staging service account limited to review/staging operations. A configured
@@ -570,6 +629,30 @@ The generated `cpflow-build-docker-image` action supports this without hardcodin
 - set `DOCKER_BUILD_SSH_KEY` if the Docker build needs SSH access to GitHub
 - optionally set `DOCKER_BUILD_SSH_KNOWN_HOSTS` when the SSH build host is not GitHub.com or you need custom host entries
 - set `DOCKER_BUILD_EXTRA_ARGS` when you need extra `docker build` flags
+- set `DOCKER_BUILD_SECRETS` for staging builds that need credentials such as a private package token or a source-map upload token
+- set `REVIEW_APP_DOCKER_BUILD_SECRETS` separately if review-app builds need credentials
+
+For example, store the following as the **value** of the `DOCKER_BUILD_SECRETS` GitHub Actions secret:
+
+```text
+sentry_auth_token=<source-map upload token>
+npm_token=<private package token>
+```
+
+The generated staging caller forwards `DOCKER_BUILD_SECRETS`. The review-app caller forwards `REVIEW_APP_DOCKER_BUILD_SECRETS`, the only build-secret parameter the reusable review-app workflow accepts, so review builds never receive the staging secret. The build action writes each value to a private temporary file, passes only its path through `--secret=id=...,src=...`, and removes the files on success or failure. Values are not passed as build arguments or persisted through `GITHUB_ENV`.
+
+A Dockerfile can consume a token only for the command that needs it:
+
+```dockerfile
+# syntax=docker/dockerfile:1
+ARG SENTRY_UPLOAD=false
+RUN --mount=type=secret,id=sentry_auth_token,env=SENTRY_AUTH_TOKEN \
+    SENTRY_UPLOAD=${SENTRY_UPLOAD} npm run build
+```
+
+If the application's build requires an explicit upload opt-in, pass `docker_build_extra_args: --build-arg=SENTRY_UPLOAD=true` in the caller workflow's `with` block, or add that token to `DOCKER_BUILD_EXTRA_ARGS`. The optional workflow input is appended after the repository variable, retaining existing build arguments. Token availability alone need not enable uploads. BuildKit secret values do not invalidate build caches; force the relevant build step to run again when rotating a credential requires repeating an upload.
+
+Every secret supplied to a review build is accessible to the PR-controlled Dockerfile, which can read and transmit it. Automatic rebuilds of an existing review app also receive these secrets; approval to create the app does not approve later commits. Configure only credentials whose access can be entrusted to anyone able to change the deployed branch, scoped to the minimum review-build permissions. Separate secret names reduce accidental sharing but do not prevent the Dockerfile from accessing supplied credentials. If a credential cannot be entrusted to branch authors, omit it from review builds or use a customized approval gate that approves each deployed commit. Apply the review-app security guidance above.
 
 For example, a repo that installs private dependencies from GitHub during Docker build can set:
 
@@ -708,18 +791,36 @@ wrapper-level `if:` guard shown in that file, for example
 ## Upstream Workflows And Actions
 
 Most generated workflows are intentionally small wrappers. The deployment
-logic and comment formatting live in upstream reusable workflows. The canonical
-composite actions live in this repository and the gem copies them into each
-downstream repository at `.github/actions/cpflow-*`; the reusable workflows use
-those regular local action paths. They separately check out the matching
-upstream ref at `.cpflow` for the `cpflow` runtime source. Production promotion
-is expanded into the caller repository so it can own `environment: production`,
-but follows the same local-action and `.cpflow` source split.
+logic and comment formatting live in upstream reusable workflows, and the
+composite actions they call live in this repository. Each job checks out
+`shakacode/control-plane-flow` at the pinned ref into `.cpflow`, then runs the
+actions as `./.cpflow/.github/actions/cpflow-*` and builds the `cpflow` runtime
+from the same checkout. A downstream repository carries the wrappers and one
+pinned ref, with no copies of the actions. Production promotion is expanded
+into the caller repository so it can own `environment: production`; it pins the
+same source in its own `.cpflow` checkout.
 
 - `cpflow-setup-environment`: installs Ruby, the Control Plane CLI, and `cpflow`, then logs into the target org. By default it builds `cpflow` from the checked-out upstream `control-plane-flow` ref; set the `CPFLOW_VERSION` repository variable only when you want to force a published RubyGems release.
 - `cpflow-build-docker-image`: builds and pushes the app image with the desired commit SHA
 - `cpflow-delete-control-plane-app`: safely deletes temporary apps and refuses to touch names outside the configured review-app prefix
 
+### Where the actions run from
+
+The actions that receive `CPLN_TOKEN_STAGING` come from
+`shakacode/control-plane-flow` at the commit the calling wrapper pins. For a
+reusable workflow that is `job.workflow_sha`; for production promotion it is the
+`ref:` of the `Checkout control-plane-flow actions` step.
+
+A same-repository pull request can change the wrapper, including its pinned
+ref, and the application code and `.controlplane/` configuration that the
+deployment builds. It cannot change the action code without changing that pin,
+so reviewing the pin reviews the actions. The review-app jobs check out caller
+files only under `app/`, and never at the workspace root.
+
+cpflow 6.0.0 instead ran copies of the actions from the caller repository at
+the triggering revision. See
+[Removing cpflow 6.0.0 action copies](#removing-cpflow-600-action-copies).
+
 ## Version Pins: GitHub Ref vs RubyGems
 
 Generated `cpflow-*` workflow files pin `shakacode/control-plane-flow` from
@@ -741,22 +842,22 @@ that input outside the production promotion setup step, regenerate with a newer
 
 There are two coordinated inputs, and they protect different things:
 
-- The GitHub ref locks the reusable workflow and the `.cpflow` runtime source
-  checkout that GitHub runs.
-- The installed Ruby gem supplies the generated local composite actions and
-  wrappers. `CPFLOW_VERSION`, when configured, separately locks the published
-  `cpflow` runtime installed by the setup action.
+- The GitHub ref locks the reusable workflow, its composite actions, and the
+  `.cpflow` runtime source checkout that GitHub runs.
+- The installed Ruby gem supplies the generated wrappers. `CPFLOW_VERSION`,
+  when configured, separately locks the published `cpflow` runtime installed by
+  the setup action.
 
 That means a downstream app cannot rely on the gem alone for GitHub Actions
 behavior. The safe stable path is still gem-driven for generation, but
-developers must commit the generated wrappers and local actions from the gem
-that matches the upstream release tag:
+developers must commit the generated wrappers from the gem that matches the
+upstream release tag:
 
 1. Publish a `cpflow` gem.
 2. Install or bundle that released gem in the downstream project.
 3. Run `cpflow generate-github-actions`.
-4. Commit the generated wrappers and `.github/actions/cpflow-*` files; the
-   wrappers should point to the matching upstream release tag such as `v5.0.0`.
+4. Commit the generated wrappers; they should point to the matching upstream
+   release tag such as `v5.0.0`.
 
 That release tag should point to the same source that produced the RubyGems
 release. Downstream production automation should use release tags, not `main` or
@@ -765,8 +866,8 @@ feature-branch refs.
 Generated cross-repository reusable-workflow calls deliberately use an exact
 release tag such as `v5.0.0`. This is the intentional downstream exception to
 the repository's full-SHA external-action policy: it keeps the installed gem,
-generated wrappers, generated local actions, and upstream workflow on one
-reviewed release update contract. It does not extend to external actions inside
+generated wrappers, and upstream workflow on one reviewed release update
+contract. It does not extend to external actions inside
 those workflows, which remain pinned to full commit SHAs with readable release
 comments. Unreleased downstream validation temporarily replaces the exact tag
 with the upstream PR's full commit SHA as described below; moving version
@@ -776,14 +877,14 @@ aliases and branches remain forbidden.
 
 Whenever a downstream repo updates the `cpflow` gem, update all checked-in
 GitHub Actions files in the same PR. The gem version does not make GitHub load
-new reusable workflow YAML or local action files by itself; GitHub uses the
-workflow ref and `.github/actions/cpflow-*` files committed in the repository.
+new reusable workflow YAML by itself; GitHub uses the workflow ref committed in
+the repository.
 
 For a new repository that does not have generated wrappers yet, run
 `cpflow generate-github-actions` first. Use the update command below for later
 gem upgrades.
 
-Use the installed gem to refresh the generated workflows and actions:
+Use the installed gem to refresh the generated files:
 
 ```sh
 cpflow update-github-actions
@@ -797,11 +898,111 @@ bundle exec cpflow update-github-actions
 bin/test-cpflow-github-flow bundle exec cpflow
 ```
 
-`cpflow update-github-actions` regenerates the workflow wrappers, local
-composite actions, and helper files from the installed gem, pins the wrapper
-`uses:` refs to `v<gem-version>`, and preserves a single custom staging branch
-from the existing generated staging workflow. Pass `--staging-branch BRANCH`
-when changing or restoring a custom staging branch explicitly.
+`cpflow update-github-actions` refreshes the generated helpers.
+It preserves every top-level workflow by default, including refs, triggers,
+permissions, and downstream deployment ownership. It does not create staging
+or production deployment workflows when another CI system owns those deploys.
+Select the wrappers you intend to replace explicitly; see
+`cpflow update-github-actions --help` for the current interface:
+
+```sh
+bundle exec cpflow update-github-actions --workflows \
+  cpflow-deploy-review-app.yml cpflow-delete-review-app.yml \
+  cpflow-cleanup-stale-review-apps.yml cpflow-help-command.yml \
+  cpflow-review-app-help.yml
+```
+
+Each selected wrapper is replaced in full with the installed gem's template
+and release ref. Review the diff and reapply downstream changes before
+committing. Unselected wrappers keep their refs: preservation is not evidence
+that old wrappers are compatible with the new release. Migrate wrapper
+contracts and source pins together, then run the validator in the same PR.
+For a selected staging wrapper, a single existing push branch or the default
+main/master pair can be inferred. Missing, malformed, or ambiguous branch
+configuration requires an explicit `--staging-branch BRANCH`; that option also
+requires selecting `cpflow-deploy-staging.yml`.
+
+### Removing cpflow 6.0.0 action copies
+
+cpflow 6.0.0 generated `.github/actions/cpflow-*` and ran those copies. Later
+releases load the actions from the pinned ref, so the copies are unused once
+every workflow has moved off 6.0.0:
+
+1. Update the gem, then replace the wrappers and the production promotion
+   workflow with `cpflow update-github-actions --workflows FILE...`. Reapply
+   downstream customizations.
+2. Confirm that no workflow is still pinned to cpflow 6.0.0 and that none has a
+   `uses: ./.github/actions/cpflow-*` line. In a workflow you maintain by hand,
+   change each such line to `uses: ./.cpflow/.github/actions/cpflow-*`.
+3. Delete the copies with `git rm -r .github/actions/cpflow-*`, delete any
+   downstream check that compares them with the gem, and run
+   `bin/test-cpflow-github-flow`.
+
+`cpflow update-github-actions` lists the copies it finds and never deletes
+them. A wrapper pinned to 6.0.0 runs them without naming them, and a full-SHA
+pin does not say which release it is, so the command cannot prove a copy is
+unused. Until step 3 the copies are harmless: a wrapper pinned to a later
+release never reads them. The validator fails when a workflow names a copy
+that is not checked in.
+
+### Preserving downstream validation
+
+The generated `bin/test-cpflow-github-flow` runs baseline checks followed by
+an optional executable `bin/test-cpflow-github-flow-custom`. The extension runs
+from the repository root with the cpflow command argv forwarded unchanged
+(for example, `bundle`, `exec`, `cpflow`), and its nonzero exit fails validation.
+The generator never creates or overwrites the custom extension. Baseline
+production checks apply when the generated production workflow exists;
+downstream-owned production workflows belong in the custom checks.
+
+An existing validator that differs from the installed template blocks the
+entire update before any writes. This includes unmodified validators from
+older releases: the updater cannot safely distinguish them from custom code.
+For a legacy installation such as HiChee's 5.3-to-6.0 RC migration:
+
+1. Save the old validator in version control and compare it with its original
+   release. Extract the downstream checks into `bin/test-cpflow-github-flow-custom`
+   and make it executable. If it is entirely downstream-specific, rename it
+   directly. Remove any call back to the generated validator to avoid recursion.
+2. Remove or rename the old `bin/test-cpflow-github-flow` after preserving those
+   checks, then run the update command with the selected wrappers. No override
+   flag bypasses this check. Do not use `generate-github-actions --force` as a
+   migration shortcut: it intentionally replaces the full generated flow.
+3. Run the new validator. Confirm that the custom checks execute and that a
+   failing custom check still fails the command. Repeating the updater with the
+   same selected workflows should produce no further diff.
+
+### Migrating trusted action allowlists
+
+Repositories using a closed `trusted_actions` policy must review these exact
+repositories used by the complete generated output:
+
+```yaml
+trusted_actions:
+  - actions/checkout
+  - docker/setup-buildx-action
+  - ruby/setup-ruby
+  - shakacode/control-plane-flow
+```
+
+Merge the needed entries into your existing policy rather than replacing it.
+`ruby/setup-ruby` is used by cpflow's setup action, including in
+review-app-only installations. `actions/checkout` and `docker/setup-buildx-action`
+are used directly by the generated production wrapper;
+`shakacode/control-plane-flow` supplies the reusable wrappers. Other existing
+downstream workflows may need additional entries. Upstream reusable workflows
+also use `actions/github-script`; reviewing that upstream implementation remains
+part of trusting `shakacode/control-plane-flow`.
+
+Allowlisting does not waive immutable pin requirements. For a policy requiring
+full SHAs, resolve and independently verify the chosen upstream release tag or
+test commit, then run `bin/pin-cpflow-github-ref --version <reviewed-version-tag>
+<full-sha>`. The helper writes that version/tag beside all cpflow SHA pins and
+updates obsolete same-line comments. The label is supplied by the caller; the
+helper does not contact GitHub or certify tag-to-SHA identity. For an unreleased
+test commit, use its source version tag as context and record the exact commit
+in the PR. Review the generated diff and run your repository's action security
+scanner after updating its allowlist.
 
 When keeping `cpflow` in an app Gemfile, leave a comment next to the gem entry
 so future dependency bumps include the wrapper update:
@@ -835,8 +1036,7 @@ action commit, so a moving branch named like `v5.0.0` cannot be used with
 runners that cannot reach GitHub should leave `CPFLOW_VERSION` unset and build
 `cpflow` from the checked-out ref instead. When testing an unreleased upstream
 commit SHA, leave `CPFLOW_VERSION` unset so the workflow builds `cpflow` from the
-same source that supplies the reusable workflow. Refresh the generated local
-actions from that checkout before testing as described below.
+same source that supplies the reusable workflow and its actions.
 
 ## Testing Unreleased Upstream Changes Downstream
 
@@ -849,14 +1049,13 @@ releasing it. Use an immutable commit SHA from the upstream PR branch:
 
    ```sh
    ruby /path/to/control-plane-flow/bin/cpflow update-github-actions
-   bin/pin-cpflow-github-ref <upstream-pr-sha>
+   bin/pin-cpflow-github-ref --version <reviewed-version-tag> <upstream-pr-sha>
    ```
 
-   The update command copies the PR checkout's canonical composite actions into
-   `.github/actions/cpflow-*`. The pin helper then updates every generated
+   The pin helper updates every generated
    reusable-workflow `uses:` ref plus the production workflow's pinned
    `control-plane-flow` checkout and setup validation ref. It accepts release
-   tags and full commit SHAs by default, rejects branch names such as `main` or
+   tags and full commit SHAs (with a reviewed `--version` label), rejects branch names such as `main` or
    `feature/foo`, and requires `--allow-moving-ref` for short-lived local
    experiments that should not be committed.
 
@@ -881,19 +1080,18 @@ releasing it. Use an immutable commit SHA from the upstream PR branch:
    matches the repository's installation state.
 
    For an existing installation, where `cpflow-deploy-review-app.yml` is already
-   present on the default branch, dispatch the workflow definition and generated
-   local actions from the unmerged downstream test branch against a suitable open
-   base-repository PR:
+   present on the default branch, dispatch the workflow definition from the
+   unmerged downstream test branch against a suitable open base-repository PR:
 
    ```sh
    gh workflow run cpflow-deploy-review-app.yml --ref <downstream-test-branch> -f pr_number=<pr-number>
    ```
 
-   The `--ref` selects the downstream wrapper and local-action commit under test;
+   The `--ref` selects the downstream wrapper commit under test;
    `pr_number` selects the application source to deploy. Do not use a
    `+review-app-deploy` comment for this pre-merge validation: `issue_comment`
    always loads the workflow definition from the default branch, so it cannot
-   validate unmerged wrappers or local actions.
+   validate unmerged wrappers.
 
    For a first installation, GitHub will not dispatch a workflow that does not
    yet exist on the default branch, even when `--ref` names the installation
@@ -914,9 +1112,9 @@ releasing it. Use an immutable commit SHA from the upstream PR branch:
    `bin/pin-cpflow-github-ref vX.Y.Z` only for a ref-only update when the
    generated templates are already current.
 
-For an existing installation, this tests the real reusable workflows, the
-unmerged regenerated local composite actions, and the source-built `cpflow` gem
-against one immutable upstream commit. A first installation gets the same remote
+For an existing installation, this tests the real reusable workflows, their
+composite actions, and the source-built `cpflow` gem against one immutable
+upstream commit. A first installation gets the same remote
 proof immediately after its locally validated files reach the default branch.
 Both paths avoid testing against a moving upstream branch.
 
@@ -961,7 +1159,7 @@ In practice, porting the flow into a demo app usually follows five phases.
 
 4. Update `.controlplane/controlplane.yml` with staging, review, and production entries.
 5. Confirm that the generated Dockerfile picked a Ruby base image compatible with the app's declared Ruby requirement.
-6. For SQLite-backed apps, confirm that the generated scaffold switched to persistent `db` and `storage` volumes, mounted them into the main workload, and added a release script that runs `rails db:prepare`.
+6. For SQLite-backed apps, confirm that the generated scaffold redirects every production database file into persistent `/app/data` (or keeps it under persistent `/app/storage`) without hiding image migrations under `/app/db`, mounts Active Storage at `/app/storage`, and adds a release script that runs `rails db:prepare`.
 
 **Adapt for the app's runtime:**
 
@@ -1005,7 +1203,7 @@ Expand that prompt with app-specific requirements before editing files:
 - make sure the generated Dockerfile uses a Ruby base image compatible with the app's declared Ruby requirement
 - preserve repo-defined frontend precompile hooks, such as Shakapacker `precompile_hook` commands or React on Rails `config.auto_load_bundle = true`
 - keep Node available in the final image if Rails or SSR depends on ExecJS, Yarn, or `pnpm` after the main `npm install` layer
-- if `config/database.yml` shows SQLite in production, confirm that `cpflow generate` emitted persistent `db` and `storage` volumes plus a `rails db:prepare` release script; otherwise keep the default Postgres workload
+- if `config/database.yml` shows SQLite in production, confirm that `cpflow generate` redirected every production database path into persistent `/app/data` or `/app/storage`, emitted both volumes without mounting over `/app/db`, and added a `rails db:prepare` release script; otherwise keep the default Postgres workload
 - inspect the production Dockerfile and package sources for private GitHub dependencies, and wire `DOCKER_BUILD_SSH_KEY` plus `DOCKER_BUILD_SSH_KNOWN_HOSTS` when the build uses `RUN --mount=type=ssh` against non-GitHub hosts
 - add extra `app_workloads` and template files for any runtime sidecars, workers, or renderer processes
 - make sure any sidecar process exposed to sibling workloads binds to `0.0.0.0` instead of container-local `localhost`

data/docs/commands.md

@@ -30,6 +30,7 @@ cpflow ai-github-flow-prompt
 - Picks templates from the `.controlplane/templates` directory
 - Templates are ordinary Control Plane templates but with variable preprocessing
 - Use `--preserve-existing-runtime` to retain each workload container's configured app image, even when the workload is unready, and skip existing secret resources entirely while applying other template changes
+- Use `--exclude-secret-template NAME` and `--exclude-policy-template NAME` to exclude exact named templates without changing workload image handling
 - Missing or invalid workload images use only an unambiguous app image from ready workloads; refresh fails before applying templates when no safe fallback exists
 
 **Preprocessed template variables:**
@@ -135,6 +136,7 @@ cpflow copy-image-from-upstream -a $APP_NAME --upstream-token $UPSTREAM_TOKEN --
 - Deletes the whole app (GVC with all workloads, all volumesets and all images) or a specific workload
 - Also unbinds the app from the secrets policy and any configured `shared_secret_grants` policies, as long as both the identity and each policy exist (and are bound)
 - For the app-specific secrets policy, removes every permission held by the app identity; for `shared_secret_grants`, removes only `reveal`
+- Removes a marked per-app dictionary and exact-target unbound policy for generated review credentials, including after the opt-in is removed from a dynamically matched review-app entry
 - Will ask for explicit user confirmation
 - Runs a pre-deletion hook before the app is deleted if `hooks.pre_deletion` is specified in the `.controlplane/controlplane.yml` file
 - If the hook exits with a non-zero code, the command will stop executing and also exit with a non-zero code
@@ -217,7 +219,7 @@ Creates base Control Plane config and template files for a Rails project:
 - infers the app prefix from the current directory and wires staging, review, and production entries
 - infers the Docker base Ruby version from `.ruby-version`, `.tool-versions`, or the app's `Gemfile`
 - preserves repo-defined asset precompile hooks, including React on Rails auto bundle generation
-- detects SQLite in `config/database.yml` and generates persistent `db` and `storage` volume templates instead of the default Postgres workload
+- detects SQLite in `config/database.yml` and generates persistent `/app/data` and `/app/storage` volume templates without hiding image migrations under `/app/db`
 
 ```sh
 # Creates .controlplane directory with Control Plane config and starter templates
@@ -232,8 +234,8 @@ Creates GitHub Actions templates for a Heroku Flow style Control Plane pipeline:
 - manual promotion from staging to production
 - nightly cleanup and PR help workflows
 
-It also copies cpflow's composite actions into `.github/actions/cpflow-*`
-so every local `uses:` target is checked in and can be audited directly.
+The workflows load cpflow's composite actions from this gem's repository at
+the ref each workflow pins, so no `.github/actions/cpflow-*` copies are generated.
 
 Pass `--staging-branch BRANCH` when staging should auto-deploy from a branch
 other than `main` or `master`; the generator will bake that branch into the
@@ -243,7 +245,7 @@ Pass `--force` to overwrite existing generated files. Prefer
 repo.
 
 ```sh
-# Creates workflow wrappers, local composite actions, and validation helpers
+# Creates workflow wrappers and validation helpers
 cpflow generate-github-actions
 
 # Creates the flow with staging deploys triggered from develop
@@ -558,13 +560,14 @@ cpflow run -a $APP_NAME --entrypoint /app/alternative-entrypoint.sh -- rails db:
 - Configures app to have org-level secrets with default name `"{APP_PREFIX}-secrets"`
   using org-level policy with default name `"{APP_PREFIX}-secrets-policy"` (names can be customized, see docs)
 - Creates identity for secrets if it does not exist
+- For dynamically named review apps with `generated_review_secret_keys`, checks an existing policy before writing credentials, creates a per-app dictionary, skips its secret template during initial setup, and fills missing disposable keys without printing or rotating values
 - Binds the app identity to any configured `shared_secret_grants` policies as part of the secrets setup flow; skipped when `--skip-secrets-setup` or `--skip-secret-access-binding` is provided, or `skip_secrets_setup` is set
 - Use `--skip-secrets-setup` to prevent the automatic setup of secrets,
   or set it through `skip_secrets_setup` in the `.controlplane/controlplane.yml` file
 - Runs a post-creation hook after the app is created if `hooks.post_creation` is specified in the `.controlplane/controlplane.yml` file
 - If the hook exits with a non-zero code, the command will stop executing and also exit with a non-zero code
 - Use `--skip-post-creation-hook` to skip the hook if specified in `controlplane.yml`
-- Use `--refresh-templates` to apply configured templates noninteractively to an existing app while preserving each workload's configured app image even when workloads are unready or use mixed image versions, skipping existing secret resources entirely, repairing secrets access bindings, and skipping the post-creation hook
+- Use `--refresh-templates` to apply configured templates noninteractively to an existing app while preserving each workload's configured app image even when workloads are unready or use mixed image versions, skipping existing secret templates (but filling missing opt-in generated review keys), repairing secrets access bindings, and skipping the post-creation hook
 
 ```sh
 cpflow setup-app -a $APP_NAME
@@ -588,25 +591,38 @@ cpflow terraform import
 
 ### `update-github-actions`
 
-Regenerates the cpflow workflow wrappers, local composite actions, and
-helper files from the currently installed cpflow gem. Use this after
-updating the cpflow gem so checked-in workflow wrappers move to the
-matching upstream release tag, for example `v5.3.0`, and the
-generated action implementations move with them.
+Refreshes helper files from the installed gem. Workflows load cpflow's
+composite actions from the pinned cpflow ref, so the command reports any
+`.github/actions/cpflow-*` copies left by cpflow 6.0.0 for you to delete
+once no workflow is pinned to 6.0.0. It never deletes them itself.
+All top-level workflows are preserved by default, including their refs,
+triggers, permissions, and deployment ownership. Use --workflows FILE...
+to explicitly add or replace named generated workflows. Replacement resets
+each selected workflow to its template and matching v6.0.1 ref;
+review and reapply any downstream customizations in the same PR.
 
-If the existing generated staging workflow uses a custom single staging
-branch, the command preserves it. Pass `--staging-branch BRANCH` to set or
-replace the generated staging branch explicitly.
+Selecting cpflow-deploy-staging.yml preserves a single existing push branch
+or the default main/master pair. Missing or ambiguous branches require
+--staging-branch BRANCH. This option requires selecting the staging workflow.
+
+A differing existing bin/test-cpflow-github-flow blocks all writes. Move
+downstream checks to executable bin/test-cpflow-github-flow-custom and
+remove or rename the old validator before updating. The generated validator
+invokes that extension after its baseline checks; the extension is never
+generated or overwritten. See docs/ci-automation.md for migration guidance.
 
 ```sh
-# After updating the cpflow gem, refresh every generated GitHub Actions file
+# Refresh helpers while preserving downstream workflows
 cpflow update-github-actions
 
 # When running cpflow through Bundler
 bundle exec cpflow update-github-actions
 
-# Preserve or set a custom staging branch
-cpflow update-github-actions --staging-branch develop
+# Explicitly replace the review-app wrapper
+cpflow update-github-actions --workflows cpflow-deploy-review-app.yml
+
+# Explicitly add or replace staging deployment from develop
+cpflow update-github-actions --workflows cpflow-deploy-staging.yml --staging-branch develop
 ```
 
 ### `version`