docs: clarify env names are configurable, roles are positional

README.md

@@ -214,6 +214,8 @@ Promotions are triggered via `workflow_dispatch` on the generated `promote.yaml`
 | `dev-to-prod` | Full cascade through all environments |
 | `uat-to-prod` | Partial cascade from uat onward |
 
+These modes are generated from your configured environment names (`dev`, `test`, `uat`, `prod` shown here as an example); roles are positional, with the last environment as the release stage.
+
 The same artifacts built on the first merge are promoted through the chain; nothing is rebuilt.
 
 ---

docs/src/content/docs/configuration.md

@@ -53,6 +53,24 @@ ci:
 | `manifest_key` | string | No | `ci` | Top-level key inside the manifest file |
 | `action_folder` | string | No | `manage-release` | Folder name for the manage-release action |
 
+:::note[Environment names are yours; roles are positional]
+The `environments` list is fully configurable. cascade attaches no meaning to specific
+labels: `dev`, `test`, `uat`, `staging`, and `prod` are illustrative examples used
+throughout these docs, not reserved names. Roles are decided by position in the list, not
+by name. The last environment is the release stage (prod), the second-to-last is the
+prerelease environment, and the publish boundary is the final crossing into the last
+environment. The count is structural too: zero environments is release-only, one
+environment generates a single-environment Release workflow, and two or more enable the
+full promote cascade.
+
+**Naming.** Environment, build, and deploy names become GitHub Actions job IDs and
+output-variable keys, so keep them identifier-safe: use letters, digits, and underscores
+(hyphens are read as subtraction in GitHub Actions expressions). The reserved
+generator-owned names `environment` and `dry_run` cannot be used as `dispatch_inputs`. Any
+`gha_environment` value maps to a real GitHub Environment, so GitHub's own naming rules
+apply there.
+:::
+
 ### cli_version
 
 Controls which CLI version the generated workflows install via setup-cli:

docs/src/content/docs/workflows.md

@@ -213,7 +213,7 @@ This prevents unnecessary deploys (e.g., don't redeploy CDK if only services cha
 
 ### Promotion Modes
 
-The mode dropdown is generated from the configured `environments` list.
+The mode dropdown is generated from the configured `environments` list. The env names and the resulting `<from>-to-<to>` modes come from your own configuration, not from fixed names; roles are positional (last = release stage, second-to-last = prerelease).
 
 **Default mode** advances the chain by one logical step (next env, or release/prod at the boundary).