Document cpflow app bootstrap (#748)

Author: justin808

.controlplane/readme.md

@@ -57,6 +57,21 @@ The matching Control Plane resources are:
 | Staging app | `react-webpack-rails-tutorial-staging` |
 | Staging app secret dictionary | `react-webpack-rails-tutorial-staging-secrets` |
 
+Bootstrap the persistent staging app once before the first merge-to-master
+deploy:
+
+```sh
+cpflow setup-app -a react-webpack-rails-tutorial-staging --org shakacode-open-source-examples-staging --skip-post-creation-hook
+```
+
+`setup-app` reads `setup_app_templates` from `.controlplane/controlplane.yml`
+and creates the app identity, app secret dictionary, app secret policy, policy
+binding, and template resources. Use `--skip-post-creation-hook` so first-time
+bootstrap does not try to run database setup before a Docker image exists. For
+later template updates on an existing persistent app, use
+`cpflow apply-template` and make sure the app identity still has `reveal`
+permission on the app secret policy.
+
 ### Production Promotion
 
 Production promotion is part of the default demo flow, but the production token
@@ -81,6 +96,9 @@ The matching Control Plane resources are:
 | Production app | `react-webpack-rails-tutorial-production` |
 | Production app secret dictionary | `react-webpack-rails-tutorial-production-secrets` |
 
+Bootstrap production the same way before the first promotion, using the
+production org and production-only secret values.
+
 All review, staging, and production secret dictionaries need these app runtime
 secrets:
 

.controlplane/shakacode-team.md

@@ -63,6 +63,18 @@ 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.
 
+Persistent staging and production apps must be bootstrapped once before the
+first deploy or promotion:
+
+```sh
+cpflow setup-app -a react-webpack-rails-tutorial-staging --org shakacode-open-source-examples-staging --skip-post-creation-hook
+cpflow setup-app -a react-webpack-rails-tutorial-production --org shakacode-open-source-examples-production --skip-post-creation-hook
+```
+
+Use `setup-app` for first-time bootstrap because it creates the app secret
+policy and identity binding. Use `cpflow apply-template` for later template
+updates to existing persistent apps.
+
 Advanced optional settings are documented upstream in the
 [`control-plane-flow` CI automation guide](https://github.com/shakacode/control-plane-flow/blob/main/docs/ci-automation.md).
 

.github/cpflow-help.md

@@ -39,6 +39,16 @@ Optional overrides exist for forks, clones, and unusual apps:
 ## Staging And Production
 
 Staging deploys use the same `CPLN_TOKEN_STAGING` secret plus `STAGING_APP_NAME`.
+Before the first staging deploy, bootstrap the persistent staging app once:
+
+```sh
+cpflow setup-app -a "$STAGING_APP_NAME" --org "$CPLN_ORG_STAGING" --skip-post-creation-hook
+```
+
+`setup-app` creates the app identity, app secret dictionary, app secret policy,
+policy binding, and template resources. For later template updates on an
+existing persistent app, use `cpflow apply-template` and make sure the app
+identity has `reveal` permission on the app secret policy.
 
 Production promotion is part of the generated flow, but keep it protected:
 
@@ -53,6 +63,9 @@ 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.
 
+Before the first promotion, bootstrap the production app the same way in the
+production org, using production-only secrets and values.
+
 ## Version Locking
 
 Generated wrappers pin Control Plane Flow once with the reusable workflow