cpflow 4.1.1 → 5.0.0.rc.0

data/docs/ci-automation.md

@@ -0,0 +1,335 @@
+# GitHub Actions Flow for Review Apps, Staging, and Production
+
+This document describes the reusable GitHub Actions scaffolding generated by `cpflow generate-github-actions`.
+
+The goal is to bring the Heroku Flow model into any `cpflow` project:
+
+1. Comment `/deploy-review-app` on a pull request to create or update a review app.
+2. Push more commits to the PR to auto-redeploy that review app.
+3. Push to the staging branch to auto-deploy staging.
+4. Promote the already-built staging artifact to production from the Actions tab.
+5. Let a nightly workflow clean up stale review apps.
+
+## Quick Start
+
+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 the `cpflow-*` composite actions and workflows.
+4. Configure the GitHub [repository secrets and variables](#required-github-repository-settings) the workflows expect.
+5. Push the branch, then comment `/deploy-review-app` on a PR to spin up a review environment.
+
+See [Bootstrap a Project](#bootstrap-a-project) for command details, [Repo Readiness Checklist](#repo-readiness-checklist) for what "ready" means, and [AI Playbook](#ai-playbook) to run the rollout through an agent.
+
+## Bootstrap a Project
+
+Run these commands from the project root:
+
+```sh
+# Check the repo for common rollout blockers before generating files
+cpflow github-flow-readiness
+
+# Print the current AI rollout prompt for this repo, if you want to hand it to an agent
+cpflow ai-github-flow-prompt
+
+# Create .controlplane/ if it does not exist yet
+cpflow generate
+
+# Add reusable GitHub Actions for the Control Plane flow
+cpflow generate-github-actions
+
+# Or, run this instead when staging should trigger from a branch other than main/master:
+cpflow generate-github-actions --staging-branch develop
+```
+
+These local bootstrap commands do not require `cpln` to be installed yet. Install and
+log into the Control Plane CLI before any command that talks to the real platform.
+`cpflow github-flow-readiness` is the fastest gate: it exits non-zero when the repo is
+missing a production Dockerfile, missing Rails runtime files, pinned to a legacy
+Ruby or Bundler toolchain, or depends on exact-pinned gem or npm versions that do
+not appear to exist in the public registries.
+
+The second command writes namespaced files so they can coexist with an app's existing CI:
+
+- `.github/actions/cpflow-build-docker-image/action.yml`
+- `.github/actions/cpflow-delete-control-plane-app/action.yml`
+- `.github/actions/cpflow-delete-control-plane-app/delete-app.sh`
+- `.github/actions/cpflow-setup-environment/action.yml`
+- `.github/workflows/cpflow-review-app-help.yml`
+- `.github/workflows/cpflow-help-command.yml`
+- `.github/workflows/cpflow-deploy-review-app.yml`
+- `.github/workflows/cpflow-delete-review-app.yml`
+- `.github/workflows/cpflow-deploy-staging.yml`
+- `.github/workflows/cpflow-promote-staging-to-production.yml`
+- `.github/workflows/cpflow-cleanup-stale-review-apps.yml`
+
+`cpflow generate` also infers the app prefix from the repo directory, infers the
+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
+`config/database.yml` shows SQLite in production.
+
+`cpflow github-flow-readiness` checks public RubyGems and npm registry metadata
+for exact-pinned direct dependencies. In air-gapped or egress-restricted
+environments those checks may report `unknown` instead of failing hard; confirm
+the deployment runner has the package access your app needs before rollout.
+
+## Repo Readiness Checklist
+
+Before generating this flow, confirm that the target repository is already a
+deployable application rather than a partial sample:
+
+- the repo can be cloned and installed from scratch with published gem and npm
+  package versions
+- the repo does not depend on unpublished or inaccessible package versions unless
+  the deployment flow also provisions the credentials needed to fetch them
+- the repo is not just a historical generator snapshot pinned to an obsolete
+  Ruby or Bundler toolchain with no validated production build path
+- the app has its real runtime scaffold checked in, for example a complete Rails
+  app with the boot files needed to run `bin/rails` and `bin/dev`
+- the repo root maps to one deployable app; multi-app monorepos need a separate
+  rollout decision before using this one-app-per-repo flow
+- the production Dockerfile can build the app's assets and any SSR or renderer
+  bundles that production needs
+- any repo-defined frontend codegen or precompile hooks are preserved before
+  `rails assets:precompile`
+- the runtime workloads, release command, and required secrets are known well
+  enough to model in `.controlplane/`
+
+If any of those fail, stop and fix the application first. Do not merge
+`cpflow-*` workflows into a repository that is not yet runnable from a clean
+clone, because the result will be a misleading "deployment flow" for an app that
+still cannot build or boot.
+
+## Required `.controlplane/controlplane.yml` Structure
+
+The generated workflows assume that `.controlplane/controlplane.yml` defines:
+
+- one staging app
+- one review-app prefix with `match_if_app_name_starts_with: true`
+- one production app with `upstream` pointing to staging
+
+Typical shape:
+
+```yaml
+aliases:
+  common: &common
+    cpln_org: my-org-staging
+    default_location: aws-us-east-2
+    setup_app_templates:
+      - app
+      - postgres
+      - redis
+      - rails
+    app_workloads:
+      - rails
+    additional_workloads:
+      - postgres
+      - redis
+
+apps:
+  my-app-staging:
+    <<: *common
+
+  my-app-review:
+    <<: *common
+    match_if_app_name_starts_with: true
+    hooks:
+      post_creation: bundle exec rails db:prepare
+      pre_deletion: bundle exec rails db:drop
+
+  my-app-production:
+    <<: *common
+    allow_org_override_by_env: false
+    allow_app_override_by_env: false
+    cpln_org: my-org-production
+    upstream: my-app-staging
+    release_script: release_script.sh
+```
+
+Important points:
+
+- `REVIEW_APP_PREFIX` in GitHub Actions must match the review config key prefix, for example `my-app-review`.
+- `match_if_app_name_starts_with: true` is what allows a single config entry to back `my-app-review-123`, `my-app-review-456`, and cleanup commands like `cpflow cleanup-stale-apps -a my-app-review`.
+- `upstream: my-app-staging` is what lets the production promotion workflow copy the exact staging artifact.
+- If your main web workload is not named `rails`, set the optional `PRIMARY_WORKLOAD` repository variable described below.
+
+## Required GitHub Repository Settings
+
+Configure these repository secrets:
+
+- `CPLN_TOKEN_STAGING`: token for the staging Control Plane org
+- `CPLN_TOKEN_PRODUCTION`: token for the production Control Plane org
+
+Configure these repository variables:
+
+- `CPLN_ORG_STAGING`: staging org name, for example `company-staging`
+- `CPLN_ORG_PRODUCTION`: production org name, for example `company-production`
+- `STAGING_APP_NAME`: staging GVC name, for example `my-app-staging`
+- `PRODUCTION_APP_NAME`: production GVC name, for example `my-app-production`
+- `REVIEW_APP_PREFIX`: review-app prefix, for example `my-app-review`
+- `STAGING_APP_BRANCH`: optional branch that auto-deploys staging. If you use a custom branch, either pass it to `cpflow generate-github-actions --staging-branch BRANCH` during generation or edit `cpflow-deploy-staging.yml` so its `on.push.branches` list includes the same branch.
+- `PRIMARY_WORKLOAD`: optional workload name used to discover the public endpoint and do production health checks; defaults to `rails`
+- `DOCKER_BUILD_EXTRA_ARGS`: optional newline-delimited single `docker build` tokens passed through to `cpflow build-image`, for example `--build-arg=FOO=bar` or `--secret=id=npmrc,src=.npmrc`
+- `DOCKER_BUILD_SSH_KNOWN_HOSTS`: optional multi-line `known_hosts` content used with `DOCKER_BUILD_SSH_KEY` when the build needs SSH access to hosts other than GitHub.com
+
+Recommended org layout:
+
+- keep review apps and staging in a staging org that developers can access
+- keep production in a separate org with tighter access controls
+
+Optional repository secret for private dependency 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 Builds with Private Dependencies
+
+Some apps need extra Docker build configuration before the generated workflows are turnkey. Common examples are:
+
+- `pnpm`, `npm`, `yarn`, or Bundler dependencies pulled from private GitHub repositories
+- Dockerfiles that already use `RUN --mount=type=ssh`
+- builds that need extra `--build-arg`, `--secret`, or related `docker build` flags
+
+The generated `cpflow-build-docker-image` action supports this without hardcoding app-specific logic:
+
+- 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
+
+For example, a repo that installs private dependencies from GitHub during Docker build can set:
+
+```text
+DOCKER_BUILD_SSH_KEY=<private deploy key secret>
+DOCKER_BUILD_SSH_KNOWN_HOSTS=git.example.com ssh-ed25519 AAAA...
+DOCKER_BUILD_EXTRA_ARGS=--build-arg=BUNDLE_WITHOUT=development:test
+```
+
+The action will start an SSH agent, add the key, write `known_hosts`, and pass `--ssh=default` to `cpflow build-image`. When `DOCKER_BUILD_SSH_KNOWN_HOSTS` is unset, the generated action uses pinned GitHub.com host keys by default. If your Dockerfile relies on `RUN --mount=type=ssh`, validate the build locally with `cpflow build-image -a <app> --ssh=default` before relying on CI.
+
+## Generated Workflow Behavior
+
+`cpflow-review-app-help.yml`
+
+- Posts a quick reference when a pull request opens, including on fork-based PRs.
+
+`cpflow-help-command.yml`
+
+- Replies to `/help` on a pull request with the commands and required repo settings.
+
+`cpflow-deploy-review-app.yml`
+
+- Creates a review app when someone comments `/deploy-review-app`.
+- Redeploys an existing review app automatically on later PR pushes.
+- Creates a GitHub deployment and comments with the review URL and logs.
+- Leaves PR pushes alone until the first review app is explicitly requested, which keeps demo-app costs down.
+- Accepts `/deploy-review-app` only from trusted commenters (`OWNER`, `MEMBER`, or `COLLABORATOR`).
+- Skips fork-based PR deploys because the workflow builds Docker images with repository secrets.
+
+`cpflow-delete-review-app.yml`
+
+- Deletes the review app on `/delete-review-app`.
+- Also deletes it automatically when the pull request closes.
+- Accepts `/delete-review-app` only from trusted commenters (`OWNER`, `MEMBER`, or `COLLABORATOR`).
+
+`cpflow-deploy-staging.yml`
+
+- Builds and deploys the staging app on pushes to the generated staging branch filter.
+- Falls back to `main` or `master` when `STAGING_APP_BRANCH` is unset and no custom branch was generated.
+- Custom staging branches must be present in the workflow's `on.push.branches` filter; repository variables alone cannot trigger a branch GitHub Actions is not listening to.
+- Fails fast when required staging repo settings are missing instead of surfacing opaque `cpflow` errors.
+
+`cpflow-promote-staging-to-production.yml`
+
+- Manually promotes the staging artifact to production with a confirmation input.
+- Verifies that production has the env var names staging expects.
+- Runs a health check against `PRIMARY_WORKLOAD`.
+- Attempts a rollback of every configured application workload if the new production image does not come up healthy.
+- Creates a GitHub release after a successful promotion.
+
+`cpflow-cleanup-stale-review-apps.yml`
+
+- Runs nightly and on demand.
+- Deletes stale review apps using `cpflow cleanup-stale-apps`.
+
+## Composite Actions
+
+The generated workflows share these local composite actions:
+
+- `cpflow-setup-environment`: installs Ruby, the Control Plane CLI, and the `cpflow` gem, then logs into the target org
+- `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
+
+## Applying This to React on Rails Demo Apps
+
+This flow is a good fit for the React on Rails demo apps because they already follow the same basic assumptions:
+
+- the deployable app is a Rails project
+- the primary web workload is usually `rails`
+- review environments should be temporary and opt-in
+- staging should auto-follow a single branch
+- production should promote the already-tested staging image
+
+In practice, porting the flow into a demo app usually follows five phases.
+
+**Before generating:**
+
+1. Confirm the repo passes the readiness checklist above.
+2. Generate `.controlplane/` if the app does not have it yet.
+3. Generate the `cpflow-*` GitHub Actions files.
+
+**Verify the generated scaffold:**
+
+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`.
+
+**Adapt for the app's runtime:**
+
+7. Keep Node available in the final app image whenever Rails asset compilation or SSR depends on ExecJS or frontend package managers at build or runtime.
+8. Preserve repo-defined frontend precompile hooks, such as Shakapacker `precompile_hook` commands or React on Rails `config.auto_load_bundle = true`, before `rails assets:precompile`.
+9. Add any additional app workloads the app needs at runtime, for example `sidekiq`, a Node renderer, or any other process type that should deploy the same application image.
+10. Adjust `PRIMARY_WORKLOAD` only if the public workload is not named `rails`.
+
+**Wire up GitHub secrets, variables, and private builds:**
+
+11. Make sure the repo variables and secrets line up with the configured app names.
+12. If the Dockerfile pulls private dependencies over SSH, configure `DOCKER_BUILD_SSH_KEY`, add `DOCKER_BUILD_SSH_KNOWN_HOSTS` when the host is not GitHub.com, and validate that the image can build with `RUN --mount=type=ssh`.
+
+**Validate and push:**
+
+13. Validate the real production Docker build before relying on the workflows, especially if asset compilation or SSR requires Node, extra system packages, multiple processes, extra Docker build flags, or persistent writable paths.
+14. Expect review app deploys to run only for branches in the base repository; fork PRs still get help comments, but deploys are skipped because the workflow uses repository secrets.
+
+## AI Playbook
+
+If you want an AI agent to apply this flow to another project, start with
+`cpflow github-flow-readiness`, then use the standalone
+[AI rollout prompt](./ai-github-flow-prompt.md). It captures the exact wording,
+hard stop conditions, and definition of done for this workflow. You can also
+run `cpflow ai-github-flow-prompt` from inside the target repo to print the
+current prompt with that repo's default app prefix already filled in.
+
+Short version:
+
+```text
+Set up Control Plane GitHub Flow for this repo. Start with `cpflow github-flow-readiness` and stop on any reported blockers. The repo must be deployable from a clean clone, with published package versions and a production Dockerfile that can really build the app. Stop and report blockers for unpublished packages, inaccessible private dependencies, legacy toolchains, or missing production build paths instead of generating workflows blindly. Then run `cpflow generate` if `.controlplane/` is missing, run `cpflow generate-github-actions`, adapt the generated scaffold to the real workloads, document the required GitHub secrets and variables, validate the real build path locally, push the branch, and check the GitHub Actions results.
+```
+
+Expand that prompt with app-specific requirements before editing files:
+
+- verify the repo is a real deployable app, not a partial code sample or a demo pinned to unpublished package versions
+- stop and report a scope decision when the repo is a monorepo or contains multiple deployable apps without an already-decided single flow target
+- inspect the production Dockerfile and make sure it can build the app's assets in CI
+- 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
+- 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`
+- make sure sidecar caches or bundle directories live in writable paths for the runtime user, such as `tmp/`, instead of root-owned image paths
+- keep workflow files generic and put app names, org names, branch names, and Docker build knobs in repository `vars` and `secrets`
+
+When the agent applies this to a project, it should avoid hardcoding app names or org names into the workflow files. Those belong in repository `vars` and `secrets`.

data/docs/commands.md

@@ -11,6 +11,18 @@ This `-a` option is used in most of the commands and will pick all other app con
 
 ## Commands
 
+### `ai-github-flow-prompt`
+
+Prints a copy-paste prompt for an AI agent to roll out the reusable Control Plane GitHub Flow:
+- verifies the repo is deployable from a clean clone before generating files
+- scaffolds `.controlplane/` and `cpflow-*` GitHub Actions files when the repo qualifies
+- stops on external blockers or product decisions instead of forcing a broken rollout
+
+```sh
+# Prints the recommended AI rollout prompt for the current repo
+cpflow ai-github-flow-prompt
+```
+
 ### `apply-template`
 
 - Applies application-specific configs from templates (e.g., for every review-app)
@@ -93,13 +105,16 @@ cpflow config -a $APP_NAME
 
 - Copies an image (by default the latest) from a source org to the current org
 - The source app must be specified either through the `CPLN_UPSTREAM` env var or `upstream` in the `.controlplane/controlplane.yml` file
-- Additionally, the token for the source org must be provided through `--upstream-token` or `-t`
+- The token for the source org must be provided through `--upstream-token`/`-t` or the `CPLN_UPSTREAM_TOKEN` env var
 - A `cpln` profile will be temporarily created to pull the image from the source org
 
 ```sh
 # Copies the latest image from the source org to the current org.
 cpflow copy-image-from-upstream -a $APP_NAME --upstream-token $UPSTREAM_TOKEN
 
+# Equivalent call using an env var (avoids exposing the token via the OS process table).
+CPLN_UPSTREAM_TOKEN=$UPSTREAM_TOKEN cpflow copy-image-from-upstream -a $APP_NAME
+
 # Copies a specific image from the source org to the current org.
 cpflow copy-image-from-upstream -a $APP_NAME --upstream-token $UPSTREAM_TOKEN --image appimage:123
 ```
@@ -158,20 +173,66 @@ cpflow env -a $APP_NAME
 ### `exists`
 
 - Shell-checks if an application (GVC) exists, useful in scripts, e.g.:
+- Exits 0 when the app exists, 3 when it does not exist, and 64 for other errors.
 
 ```sh
-if [ cpflow exists -a $APP_NAME ]; ...
+cpflow exists -a "$APP_NAME"
+status=$?
+if [ "$status" -eq 0 ]; then
+  echo "exists"
+elif [ "$status" -eq 3 ]; then
+  echo "not found"
+else
+  echo "error: cpflow exists exited $status"
+fi
 ```
 
 ### `generate`
 
-Creates base Control Plane config and template files
+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
 
 ```sh
-# Creates .controlplane directory with Control Plane config and other templates
+# Creates .controlplane directory with Control Plane config and starter templates
 cpflow generate
 ```
 
+### `generate-github-actions`
+
+Creates GitHub Actions templates for a Heroku Flow style Control Plane pipeline:
+- on-demand review apps for pull requests
+- automatic staging deploys from your main branch
+- manual promotion from staging to production
+- nightly cleanup and PR help workflows
+
+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
+GitHub Actions push trigger and use it as the default STAGING_APP_BRANCH.
+
+```sh
+# Creates .github/actions and .github/workflows files for the Control Plane flow
+cpflow generate-github-actions
+
+# Creates the flow with staging deploys triggered from develop
+cpflow generate-github-actions --staging-branch develop
+```
+
+### `github-flow-readiness`
+
+Checks the current repository for common rollout blockers before adding the Control Plane GitHub flow:
+- Rails runtime scaffold present
+- modern Ruby and Bundler toolchain
+- installable exact-pinned direct gem and npm package versions
+- production Dockerfile presence and SQLite production hints
+
+```sh
+# Checks the current repo for common rollout blockers
+cpflow github-flow-readiness
+```
+
 ### `info`
 
 - Displays the diff between defined/available apps/workloads (apps equal GVCs)
@@ -354,13 +415,17 @@ cpflow ps:stop -a $APP_NAME -w $WORKLOAD_NAME -r $REPLICA_NAME
 ### `ps:wait`
 
 - Waits for workloads in app to be ready after re-deployment
+- Use Unix timeout command to set a maximum wait time (e.g., `timeout 300 cpflow ps:wait ...`)
 
 ```sh
 # Waits for all workloads in app.
 cpflow ps:wait -a $APP_NAME
 
 # Waits for a specific workload in app.
-cpflow ps:swait -a $APP_NAME -w $WORKLOAD_NAME
+cpflow ps:wait -a $APP_NAME -w $WORKLOAD_NAME
+
+# Waits for all workloads with a 5-minute timeout.
+timeout 300 cpflow ps:wait -a $APP_NAME
 ```
 
 ### `run`

data/docs/releasing.md

@@ -0,0 +1,153 @@
+# Releasing the Gem
+
+This project follows a changelog-first Ruby gem release process, modeled after
+the React on Rails release flow but without any npm publishing steps.
+
+## Release Process
+
+### 1. Update the Changelog
+
+Always update `CHANGELOG.md` before running the release task.
+
+1. Ensure all desired changes are merged to `main`.
+2. Run `/update-changelog release` to find merged PRs, add entries under the
+   right headings, compute the next version, stamp the version header, update
+   compare links, and open a changelog PR. Use `/update-changelog rc`,
+   `/update-changelog beta`, or an explicit version like
+   `/update-changelog 4.2.0.rc.1` when preparing a prerelease or fixed target
+   version.
+3. Review the generated changelog PR and verify the version number matches the
+   intended release level:
+   - Breaking changes: major
+   - Added features or enhancements: minor
+   - Fixes, improvements, deprecations, removals, or security updates: patch
+4. Merge the changelog PR before releasing.
+
+If updating the changelog manually, move the relevant `Unreleased` entries into
+a versioned header:
+
+   ```markdown
+   ## [4.2.0] - 2026-05-05
+   ```
+
+Then update the compare links at the bottom of `CHANGELOG.md`, including the
+`Unreleased` link and the new version link, and merge those changelog changes
+before releasing.
+
+The release task reads the latest versioned `CHANGELOG.md` header and can create
+the GitHub release from that section automatically.
+
+### 2. Run the Release Task
+
+The recommended command has no arguments:
+
+```bash
+bundle exec rake release
+```
+
+With no arguments, `rake release`:
+
+1. Reads the first versioned `CHANGELOG.md` header, such as `## [4.2.0]`.
+2. Uses that version when it is newer than the current gem version.
+3. Uses the current version if the changelog version matches the gem version
+   but has not been tagged yet.
+4. Falls back to a patch bump if no new changelog version is found.
+
+Other supported forms:
+
+```bash
+bundle exec rake "release[patch]"
+bundle exec rake "release[minor]"
+bundle exec rake "release[major]"
+bundle exec rake "release[4.2.0]"
+bundle exec rake "release[4.2.0.rc.1]"
+bundle exec rake "release[4.2.0,true]"
+```
+
+Use RubyGems version format for prereleases: `4.2.0.rc.1`, not
+`4.2.0-rc.1`.
+
+Full argument list:
+
+```bash
+bundle exec rake "release[version,dry_run,override_version_policy]"
+```
+
+Environment variables:
+
+```bash
+VERBOSE=1
+RUBYGEMS_OTP=<code>
+RELEASE_VERSION_POLICY_OVERRIDE=true
+GEM_RELEASE_MAX_RETRIES=<n>
+```
+
+### 3. What the Task Does
+
+`bundle exec rake release` performs the gem-only release:
+
+1. Requires a clean working tree.
+2. Verifies `gem-release` is available through Bundler.
+3. For real releases, verifies GitHub CLI authentication and write access.
+4. Pulls the latest changes with `git pull --rebase`.
+5. Resolves the target version from the changelog or explicit argument.
+6. Requires stable releases to run from `main`; prereleases may run from another
+   branch.
+7. Validates the target version is newer than the latest tag and is consistent
+   with the changelog section when the section indicates a bump level.
+8. Bumps `lib/cpflow/version.rb` and updates `Gemfile.lock`.
+9. Commits the version bump, tags `vX.Y.Z`, and pushes the commit and tags.
+10. Publishes the `cpflow` gem to RubyGems.org.
+11. Creates or updates the GitHub release from the matching changelog section.
+
+The older `bundle exec rake "create_release[4.2.0,false]"` task name remains as
+a compatibility alias, but new releases should use `bundle exec rake release`.
+
+### 4. Sync GitHub Release Notes Manually
+
+If the GitHub release was not created automatically, update and commit the
+matching changelog section, then run:
+
+```bash
+bundle exec rake "sync_github_release[4.2.0]"
+bundle exec rake "sync_github_release[4.2.0,true]"
+```
+
+`sync_github_release` reads notes from `CHANGELOG.md` and creates or updates the
+GitHub release for the corresponding `vX.Y.Z` tag.
+
+## Pre-Release Checklist
+
+Before running the release:
+
+1. `git checkout main`
+2. `git pull --rebase`
+3. `bundle install`
+4. `gh auth status`
+5. Confirm RubyGems credentials can publish `cpflow`.
+6. Confirm `CHANGELOG.md` has a committed section for the target version.
+7. Run a dry run:
+
+   ```bash
+   bundle exec rake "release[4.2.0,true]"
+   ```
+
+## If a Release Fails
+
+Check what was published before retrying:
+
+```bash
+gem list cpflow -r -a
+gh release view v4.2.0
+git tag -l v4.2.0
+```
+
+If the gem was published but GitHub release creation failed, fix GitHub CLI
+authentication or permissions and run:
+
+```bash
+bundle exec rake "sync_github_release[4.2.0]"
+```
+
+If the tag was pushed but the gem was not published, delete or correct the tag
+and version commit intentionally before trying again.

data/lib/command/ai_github_flow_prompt.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "../core/repo_introspection"
+
+module Command
+  class AiGithubFlowPrompt < Base
+    NAME = "ai-github-flow-prompt"
+    DESCRIPTION = "Prints the recommended AI prompt for adding the Control Plane GitHub Flow to a repo"
+    LONG_DESCRIPTION = <<~DESC
+      Prints a copy-paste prompt for an AI agent to roll out the reusable Control Plane GitHub Flow:
+      - verifies the repo is deployable from a clean clone before generating files
+      - scaffolds `.controlplane/` and `cpflow-*` GitHub Actions files when the repo qualifies
+      - stops on external blockers or product decisions instead of forcing a broken rollout
+    DESC
+    EXAMPLES = <<~EX
+      ```sh
+      # Prints the recommended AI rollout prompt for the current repo
+      cpflow ai-github-flow-prompt
+      ```
+    EX
+    WITH_INFO_HEADER = false
+    VALIDATIONS = [].freeze
+    REQUIRES_STARTUP_CHECKS = false
+
+    def call
+      puts prompt
+    end
+
+    private
+
+    def prompt
+      <<~PROMPT
+        Set up Control Plane GitHub Flow for this repo. Start with `cpflow github-flow-readiness` and stop on any reported blockers. The repo must be deployable from a clean clone: published package versions, complete runtime scaffold, and a production Dockerfile that can build the app. If any package version is unpublished, inaccessible from CI, or requires credentials that are not already modeled in the repo or GitHub settings, stop and report the blocker instead of generating workflow files. If the repo is a legacy sample pinned to an obsolete Ruby or Bundler toolchain, if it does not even have a production Dockerfile yet, or if it is a monorepo without an already-decided single app boundary for this flow, stop and report that as a prerequisite instead of forcing the rollout.
+
+        If `.controlplane/` is missing, run `cpflow generate`. Treat the generated app names as the repo-name default (`#{inferred_app_prefix}`) and rename them only if the project needs a different prefix. Then run `cpflow generate-github-actions` (or `cpflow generate-github-actions --staging-branch BRANCH` when staging should deploy from a branch other than `main`/`master`), keep review apps opt-in via `/deploy-review-app`, make sure any `STAGING_APP_BRANCH` repository variable is also present in the generated staging workflow's `on.push.branches` filter, and list the GitHub secrets and variables that must be configured.
+
+        Keep Node available in the final image if asset compilation or SSR depends on ExecJS, Yarn, `pnpm`, or npm after the main install layer. Make sure the generated Dockerfile uses a Ruby base image compatible with the app's declared Ruby requirement. Preserve repo-defined frontend build hooks: if `config/shakapacker.yml` defines a `precompile_hook`, or React on Rails enables `config.auto_load_bundle = true`, confirm the generated Dockerfile runs that codegen step before `rails assets:precompile`. If `config/database.yml` shows SQLite in production, confirm that the generated scaffold uses persistent `db` and `storage` volumes plus a release script that runs `rails db:prepare`; otherwise keep the default Postgres workload. If the public workload is not named `rails`, set `PRIMARY_WORKLOAD` or adjust the generated workflows. Inspect the Dockerfile and package sources for private GitHub dependencies or `RUN --mount=type=ssh`; if present, wire `DOCKER_BUILD_SSH_KEY`, optionally set `DOCKER_BUILD_SSH_KNOWN_HOSTS` for non-GitHub SSH hosts, and keep `DOCKER_BUILD_EXTRA_ARGS` to newline-delimited single tokens such as `--build-arg=FOO=bar`.
+
+        Run the real local validations you can: Docker build if feasible, repo tests or smoke checks, YAML validation, and any CI-equivalent build steps. Push the branch and check the GitHub Actions results. Only stop early for a real external blocker or a product decision that changes scope.
+      PROMPT
+    end
+
+    def inferred_app_prefix
+      RepoIntrospection.inferred_app_prefix(Dir.pwd)
+    end
+  end
+end