diff --git a/bin/genesis b/bin/genesis
index 38ff5e19..7025e892 100755
--- a/bin/genesis
+++ b/bin/genesis
@@ -254,7 +254,37 @@ define_command("create", {
 			"repository for the environment.",
 
 		"force|f" =>
-			"Create a new environment file even if it already exists."
+			"Create a new environment file even if it already exists.",
+
+		"prior-env=s" =>
+			"Name of the prior environment in the pipeline chain (the environment ".
+			"that must succeed before this one deploys).  Only used when a CI ".
+			"provider is configured in #C{.genesis/config}.  Omit or leave blank ".
+			"to designate this environment as a pipeline entrypoint.",
+
+		"require-pr" =>
+			"Require a pull-request gate before this environment deploys.  ".
+			"Only used when a CI provider is configured in #C{.genesis/config}.",
+
+		"manual" =>
+			"Require a manual CI trigger before this environment deploys.  ".
+			"Only used when a CI provider is configured in #C{.genesis/config}.",
+
+		"no-commit" =>
+			"Stage the new environment file but skip the git commit and ".
+			"environment branch creation.  Only applies when a CI ".
+			"provider is configured.",
+
+		"reason=s" =>
+			"Commit message for the environment commit.  Defaults to ".
+			"#C{Add environment <name>}.  Only applies when a CI ".
+			"provider is configured and #C{--no-commit} is not set.",
+
+		"no-fetch" =>
+			"Skip the pre-create refresh of pipeline environment branches from ".
+			"remote.  By default all env branches are fetched in one round-trip ".
+			"before checking for existing branches.  Use this flag when working ".
+			"offline or when the remote is temporarily unavailable.",
 	],
 	deprecated_options => [
 		"^prefix=s" =>
@@ -466,11 +496,34 @@ define_command("deploy", {
 			"specifically in the case of a failed partial deployments.\n\n".
 			"This option will allow you to specify a specfic state file to use for ".
 			"the deploy. You can use the `info` command to retrieve the state file",
+
+		'no-propagate' =>
+			"On manual-provider pipelines, `genesis deploy` automatically runs ".
+			"`genesis propagate <env>` after a successful deploy to push the ".
+			"freshly certified state to downstream environments.  Use this ".
+			"flag to skip that propagation.  Non-manual providers (concourse, ".
+			"github-actions) own their own propagation and are unaffected by ".
+			"this flag.",
+
+		'pull!' =>
+			"Pull propagated files from the prior environment's last successful ".
+			"deploy (or control HEAD for pipeline entry points) onto this ".
+			"environment branch before deploying.  No-op when the environment ".
+			"is already current.  Implied by #y{-F}/#y{--fix-checks}; use ".
+			"#y{--no-pull} to opt out.  No-op for non-pipeline repositories.",
+
+		'no-fetch' =>
+			"Skip the pre-deploy refresh of pipeline environment branches from ".
+			"remote.  By default all env branches are fetched in one round-trip ".
+			"before reading branch state.  Use this flag when working offline or ".
+			"when the remote is temporarily unavailable.",
 	],
 	args => {
 		'reason' =>
 			"An optional reason for deploying the environment.  This will be ".
-			"recorded in the exodus data for the deployment."
+			"recorded in the exodus data for the deployment.  When omitted and ".
+			"the env is on a pipeline-managed branch, genesis derives the reason ".
+			"from the control commit range being deployed."
 	}
 });
 
@@ -1191,13 +1244,15 @@ define_command("remove-secrets", {
 
 ### Repository Management commands {{{
 # genesis init - initialize a new Genesis repository {{{
-define_command("init", {
+define_command("repo-init", {
 		summary => "Initialize a new Genesis deployment repository.",
-		usage => "init [-k KIT/VERSION|-l path/to/local/kit] [-d directory] [--vault target] [name]",
+		usage => "repo-init [-k KIT] [<options...>] [name]",
+		alias => 'init',
 		description =>
 			"Create a new Genesis deployment repository, specific to the given kit type.",
 		function_group => Genesis::Commands::REPOSITORY,
 		scope => 'empty',
+		no_vault => 1,
 		option_group => Genesis::Commands::REPO_OPTIONS,
 		options => [
 			"kit|k=s" =>
@@ -1234,17 +1289,41 @@ define_command("init", {
 				"the '-deployments' suffix, but the option is still available for ".
 				"backward compatibility by setting the #Y{legacy_repo_suffix} option in ".
 				"the Genesis configuration file \$HOME/.genesis/config.yml to true.",
+
+			"no-commit" =>
+				"Stage the new repository contents but skip the initial commit. ".
+				"By default, #C{repo-init} commits the new repository automatically.",
+
+			"reason=s" =>
+				"Commit message for the initial commit.  Defaults to a message ".
+				"describing the new Genesis deployment.  Ignored if #C{--no-commit} ".
+				"is set.",
+
+			'force|f' =>
+				"If the target directory already exists, remove it and recreate ".
+				"(without this flag, you will be prompted to confirm ".
+				"replacement).  Also bypasses the check that the enclosing git ".
+				"repository is clean when creating the new repo as a ".
+				"subdirectory; use with care.",
+
+			'skip-vault' =>
+				"Defer vault configuration.  The repo will be created without a ".
+				"secrets provider.  You must configure one via #C{genesis secrets-provider} ".
+				"before creating environments.",
+
+			'with-ci' =>
+				"Enable CI pipeline support.  Sets up the control branch and ".
+				"configures the repo for branch-based pipeline topology.  ".
+				"Environments created with #C{genesis new} will be prompted ".
+				"for pipeline metadata (prior_env, gates).  Connect an ".
+				"automated provider later with #C{genesis repo config ci}.",
 		],
-		option_passthrough => 1,
+		extended_handlers => ['Genesis::Kit::Provider'],
 		arguments => [
 			"name?" =>
 				"If the name argument is not specified, it will default to the same ".
 				"name as the kit.  You must specify either name or kit."
 		],
-		extended_usage => sub {
-			require Genesis::Kit::Provider;
-			Genesis::Kit::Provider->opts_help();
-		}
 });
 
 # }}}
@@ -1302,12 +1381,86 @@ define_command("kit-provider", {
 		"export-config" =>
 			"Export the current kit provider information."
 	],
-	extended_usage => sub {
-			require Genesis::Kit::Provider;
-			Genesis::Kit::Provider->opts_help();
-	}
+	extended_handlers => ['Genesis::Kit::Provider'],
 });
 
+# }}}
+# PARKED: Tristan's CI-only repo-init define_command block -- kept
+# verbatim here for the upcoming merge meeting, but commented out so
+# it does NOT override our phased repo-init definition earlier in this
+# file.  The handler sub has been renamed in lib/Genesis/Commands/Repo.pm
+# to repo_configure_ci.  If this block is ever re-enabled, the final
+# dispatcher arg below must be updated to match that new name.
+#
+# genesis repo-init - one-time CI provider setup {{{
+# define_command("repo-init", {
+# 	summary => "Initialize CI configuration for this Genesis deployment repository.",
+# 	usage   => "repo-init [--ci-provider PROVIDER] [--git-uri URI] [--git-branch BRANCH] [--vault-url URL] [--pipeline-name NAME]",
+# 	description =>
+# 		"One-time setup that writes a #C{ci:} section to #C{.genesis/config} and ".
+# 		"generates the #C{.genesis/ci/} scaffold files required by the pipeline ".
+# 		"compiler.\n".
+# 		"\n".
+# 		"Errors if CI is already configured for this repository. Use ".
+# 		"#C{genesis repo-update} to modify an existing configuration.\n".
+# 		"\n".
+# 		"When required flags are omitted an interactive wizard collects them.",
+# 	function_group => Genesis::Commands::REPOSITORY,
+# 	scope          => 'repo',
+# 	option_group   => Genesis::Commands::REPO_OPTIONS,
+# 	options => [
+# 		'ci-provider|P=s' =>
+# 			"CI provider to configure: #C{concourse} (default), ".
+# 			"#C{github-actions}, or #C{none}.",
+#
+# 		'git-uri|g=s' =>
+# 			"Git repository URI (e.g. #C{git\@github.com:org/repo.git}).",
+#
+# 		'git-branch|b=s' =>
+# 			"Default branch for the source-control integration. Defaults to #C{main}.",
+#
+# 		'vault-url|V=s' =>
+# 			"Vault URL for the secrets integration ".
+# 			"(e.g. #C{https://vault.example.com:8200}).",
+#
+# 		'pipeline-name|n=s' =>
+# 			"Name written into #C{pipeline.yml} metadata. Defaults to the ".
+# 			"deployment type.",
+# 	],
+# }, 'Genesis::Commands::Repo::repo_configure_ci');
+# }}}
+# genesis repo-update - idempotent CI config update {{{
+define_command("repo-update", {
+	summary => "Update CI configuration for this Genesis deployment repository.",
+	usage   => "repo-update [--ci-provider PROVIDER] [--git-uri URI] [--git-branch BRANCH] [--vault-url URL] [--pipeline-name NAME]",
+	description =>
+		"Idempotent counterpart to #C{genesis repo-init}. Updates the CI ".
+		"configuration in #C{.genesis/config} and regenerates missing scaffold ".
+		"files in #C{.genesis/ci/}.\n".
+		"\n".
+		"When called with flags, only the specified values are changed; ".
+		"everything else is left as-is. A bare invocation (no flags) launches ".
+		"an interactive wizard pre-populated with the current configuration.",
+	function_group => Genesis::Commands::REPOSITORY,
+	scope          => 'repo',
+	option_group   => Genesis::Commands::REPO_OPTIONS,
+	options => [
+		'ci-provider|P=s' =>
+			"CI provider to configure: #C{concourse}, #C{github-actions}, or #C{none}.",
+
+		'git-uri|g=s' =>
+			"Git repository URI.",
+
+		'git-branch|b=s' =>
+			"Default branch for the source-control integration.",
+
+		'vault-url|V=s' =>
+			"Vault URL for the secrets integration.",
+
+		'pipeline-name|n=s' =>
+			"Name written into #C{pipeline.yml} metadata.",
+	],
+}, 'Genesis::Commands::Repo::repo_update');
 # }}}
 # }}}
 
@@ -1904,7 +2057,7 @@ define_command("pipeline-apply", {
 		'debug-dir=s' =>
 			"Write intermediate compiler artifacts to this directory.",
 	],
-}, 'Genesis::Commands::Pipeline::apply');
+}, 'Genesis::Commands::Pipelines::apply');
 # }}}
 # genesis pipeline-graph - write Mermaid pipeline.md {{{
 define_command("pipeline-graph", {
@@ -1923,7 +2076,67 @@ define_command("pipeline-graph", {
 		'platform|provider|p=s' =>
 			"CI provider: 'concourse' (default) or 'github-actions'.",
 	],
-}, 'Genesis::Commands::Pipeline::graph');
+}, 'Genesis::Commands::Pipelines::pipeline_graph');
+# }}}
+# genesis pipeline-status - show propagation state across all environments {{{
+define_command("pipeline-status", {
+	summary => "Show propagation status for all pipeline environments.",
+	usage   => "pipeline-status",
+	description =>
+		"Displays the propagation state of each environment in the pipeline ".
+		"DAG: last sync point, number of pending changes, and whether the ".
+		"environment is blocked by an ancestor that needs propagation first.",
+	function_group => Genesis::Commands::PIPELINE,
+	scope          => 'repo',
+	option_group   => Genesis::Commands::REPO_OPTIONS,
+	options => [
+		'no-fetch' =>
+			"Skip the pre-status refresh of pipeline environment branches from ".
+			"remote.  By default all env branches are fetched in one round-trip ".
+			"before reading branch state.  Use this flag when working offline or ".
+			"when the remote is temporarily unavailable.",
+	],
+}, 'Genesis::Commands::Pipelines::pipeline_status');
+# }}}
+# genesis propagate - propagate control branch changes to environment branches {{{
+define_command("propagate", {
+	summary => "Propagate changes from the control branch to environment branches.",
+	usage   => "propagate [options] [env]",
+	description =>
+		"Must be run from the control branch.  Identifies files that have ".
+		"changed since each environment branch was last synced, and copies ".
+		"them to the appropriate environment branches.\n\n".
+		"Without arguments, determines entry points by walking the DAG and ".
+		"finding the first environment that uses each changed file.\n\n".
+		"With an environment name, scopes propagation to that environment's ".
+		"children, sourced from the named env's last-deployed control commit.",
+	function_group => Genesis::Commands::PIPELINE,
+	scope          => 'repo',
+	option_group   => Genesis::Commands::REPO_OPTIONS,
+	options => [
+		'dry-run|n' =>
+			"Show what would be propagated without making changes.",
+
+		'commit=s' =>
+			"Control branch commit SHA to propagate from.  Defaults to ".
+			"HEAD of the control branch.",
+
+		'no-push' =>
+			"Skip pushing control and env branches to the remote after ".
+			"propagation.  By default, propagated branches are pushed.",
+
+		'no-fetch' =>
+			"Skip the pre-propagate refresh of pipeline environment branches ".
+			"from remote.  By default all env branches are fetched in one ".
+			"round-trip before computing diffs.  Use this flag when working ".
+			"offline or when the remote is temporarily unavailable.",
+	],
+	arguments => [
+		'env?' =>
+			"Environment that was just deployed.  Scopes propagation to ".
+			"its downstream children only.",
+	],
+}, 'Genesis::Commands::Pipelines::propagate');
 # }}}
 # genesis pipeline-describe - human-readable pipeline description {{{
 define_command("pipeline-describe", {
@@ -1942,7 +2155,7 @@ define_command("pipeline-describe", {
 		'platform|provider|p=s' =>
 			"CI provider: 'concourse' (default) or 'github-actions'.",
 	],
-}, 'Genesis::Commands::Pipeline::describe');
+}, 'Genesis::Commands::Pipelines::pipeline_describe');
 # }}}
 # genesis pipeline-diff - show compiled vs live pipeline delta {{{
 define_command("pipeline-diff", {
@@ -1968,12 +2181,12 @@ define_command("pipeline-diff", {
 		'skip-vault' =>
 			"Skip vault connectivity when compiling.",
 	],
-}, 'Genesis::Commands::Pipeline::diff');
+}, 'Genesis::Commands::Pipelines::diff');
 # }}}
-# genesis pipeline-status - show per-environment job health {{{
-define_command("pipeline-status", {
-	summary => "Show per-environment pipeline job health.",
-	usage   => "pipeline-status [<env>]",
+# genesis pipeline-jobs - show per-environment job health (Concourse) {{{
+define_command("pipeline-jobs", {
+	summary => "Show per-environment pipeline job health (Concourse).",
+	usage   => "pipeline-jobs [<env>]",
 	description =>
 		"Queries `fly jobs` and displays the status of each environment's ".
 		"deployment job.  Pass an environment name to filter to a single job.",
@@ -1996,7 +2209,7 @@ define_command("pipeline-status", {
 		'skip-vault' =>
 			"Skip vault connectivity when compiling.",
 	],
-}, 'Genesis::Commands::Pipeline::status');
+}, 'Genesis::Commands::Pipelines::status');
 # }}}
 # genesis pipeline-pause - pause an environment job or entire pipeline {{{
 define_command("pipeline-pause", {
@@ -2024,7 +2237,7 @@ define_command("pipeline-pause", {
 		'skip-vault' =>
 			"Skip vault connectivity when compiling.",
 	],
-}, 'Genesis::Commands::Pipeline::pause');
+}, 'Genesis::Commands::Pipelines::pause');
 # }}}
 # genesis pipeline-resume - resume an environment job or entire pipeline {{{
 define_command("pipeline-resume", {
@@ -2052,7 +2265,7 @@ define_command("pipeline-resume", {
 		'skip-vault' =>
 			"Skip vault connectivity when compiling.",
 	],
-}, 'Genesis::Commands::Pipeline::resume');
+}, 'Genesis::Commands::Pipelines::resume');
 # }}}
 # }}}
 
diff --git a/docs/workflows/auto-update.md b/docs/workflows/auto-update.md
new file mode 100644
index 00000000..292bd24e
--- /dev/null
+++ b/docs/workflows/auto-update.md
@@ -0,0 +1,291 @@
+# Auto-Update: update-genesis-assets
+
+The `update-genesis-assets` job automatically tracks new Genesis kit releases and
+Genesis binary releases, bumps the version file in your repository, and commits
+the result.  This removes the manual step of editing `kit.yml` every time the
+upstream kit or binary publishes a new version.
+
+---
+
+## When to enable
+
+Enable `update-genesis-assets` when:
+
+- Your kit version is pinned in a file that the pipeline checks out (e.g.
+  `kit.yml`, `.genesis/kits/cf.yml`)
+- You want each environment to pick up new versions automatically rather than
+  waiting for a manual commit
+- You operate a standard GitOps flow where pipeline-created commits on a branch
+  trigger downstream jobs
+
+Do **not** enable it when:
+
+- The kit version is managed by another system (e.g. Dependabot, a vendor
+  lock-in policy)
+- Your pipeline branch is frozen between releases and drift would cause
+  unexpected re-deploys
+
+---
+
+## Configuration
+
+```yaml
+configuration:
+  auto_update:
+    enabled:       true
+    kit:           cf              # kit name (cf → cf-genesis-kit on GitHub)
+    org:           genesis-community
+    file:          kit.yml        # repo-relative path to the version file
+    label:         concourse      # CI_LABEL in commit messages (default: concourse)
+    period:        24h            # release check frequency (default: 24h)
+    update_kit:    true           # bump kit version (default: true)
+    update_genesis: true          # bump genesis binary (default: true)
+    target_branch: auto-update    # push to this branch instead of the control branch
+    auth_token:    ((github-token))  # GitHub token for release checks (shared)
+    kit_auth_token: ((kit-token))   # per-kit override of auth_token
+    genesis_auth_token: ((genesis-token))  # per-genesis override of auth_token
+    api_url:       https://github.example.com/api/v3  # GitHub Enterprise only
+```
+
+### Required fields
+
+| Field | Description |
+|-------|-------------|
+| `enabled: true` | Opt-in — the job is not emitted without this |
+| `kit` | Kit name without the `-genesis-kit` suffix |
+| `org` | GitHub organization that owns the kit repository |
+| `file` | Path (relative to repo root) of the file Genesis reads for the kit version |
+
+All other fields have defaults or are omitted when not needed.
+
+---
+
+## How it works
+
+### Resources emitted
+
+When `update_kit: true` (default):
+
+```yaml
+- name: kit-release
+  type: github-release
+  icon: package-variant
+  check_every: 24h
+  source:
+    user:         genesis-community
+    repository:   cf-genesis-kit
+    access_token: ((github-token))
+```
+
+When `update_genesis: true` (default):
+
+```yaml
+- name: genesis-release
+  type: github-release
+  icon: leaf
+  check_every: 24h
+  source:
+    user:         genesis-community
+    repository:   genesis
+    access_token: ((github-token))
+```
+
+When `target_branch` differs from the control branch:
+
+```yaml
+- name: git-autoupdate
+  type: git
+  icon: source-branch
+  source:
+    uri:    https://github.com/org/repo.git
+    branch: auto-update
+```
+
+### Job structure
+
+```yaml
+- name: update-genesis-assets
+  plan:
+    - in_parallel:
+        - get: git
+        - get: kit-release
+          trigger: true
+        - get: genesis-release
+          trigger: true
+    - task: list-kits
+      ...
+    - task: update-genesis
+      ...
+    - task: fetch-kit
+      ...
+    - put: git          # or git-autoupdate when target_branch is set
+      params:
+        repository: git
+        rebase: true
+```
+
+Both `kit-release` and `genesis-release` trigger the job independently — a
+kit release does not need to coincide with a genesis release to trigger an
+update run.
+
+### Task scripts
+
+**`list-kits`** — calls `genesis list-kits` and writes available versions.
+
+**`update-genesis`** — runs `genesis fetch` to update the genesis binary in
+the worktree and commits:
+
+```
+[concourse] bump genesis to 2.8.14
+```
+
+**`fetch-kit`** — runs `genesis fetch-kit` to download the new kit version,
+updates `kit.yml`, and commits:
+
+```
+[concourse] bump kit cf to 2.3.1
+```
+
+The label in square brackets is controlled by `configuration.auto_update.label`
+(or the legacy `commit_label` key).
+
+---
+
+## Selective updates
+
+### Kit only (no genesis binary)
+
+```yaml
+configuration:
+  auto_update:
+    enabled:        true
+    kit:            cf
+    org:            genesis-community
+    file:           kit.yml
+    update_genesis: false
+```
+
+`genesis-release` is not checked out, the `update-genesis` task is not run,
+and no `genesis-release` resource is emitted.
+
+### Genesis binary only (no kit bump)
+
+```yaml
+configuration:
+  auto_update:
+    enabled:    true
+    kit:        cf
+    org:        genesis-community
+    file:       kit.yml
+    update_kit: false
+```
+
+`kit-release` is not checked out and `list-kits`/`fetch-kit` are not run.
+
+---
+
+## Pushing to a separate branch
+
+By default the auto-commit is pushed back to the control branch (the same
+branch the pipeline monitors).  To send it to a feature or auto-update branch:
+
+```yaml
+configuration:
+  auto_update:
+    enabled:       true
+    kit:           cf
+    org:           genesis-community
+    file:          kit.yml
+    target_branch: auto-update
+```
+
+A `git-autoupdate` resource is emitted that tracks `auto-update`.  The final
+`put:` step in the job uses `git-autoupdate` instead of `git`, so the
+auto-commits never land directly on the control branch.  A PR or manual merge
+from `auto-update` → control branch then triggers the normal pipeline.
+
+---
+
+## Auth
+
+### Shared token
+
+```yaml
+auth_token: ((github-token))
+```
+
+Used for both `kit-release` and `genesis-release`.
+
+### Per-resource overrides
+
+```yaml
+auth_token:         ((shared-token))
+kit_auth_token:     ((kit-specific-token))
+genesis_auth_token: ((genesis-specific-token))
+```
+
+`kit_auth_token` overrides `auth_token` for the kit resource only;
+`genesis_auth_token` overrides it for the genesis resource only.
+
+### GitHub Enterprise
+
+```yaml
+api_url: https://github.example.com/api/v3
+```
+
+Applied only to the `kit-release` resource (the genesis binary is always
+fetched from github.com).
+
+---
+
+## Legacy key mapping
+
+The following keys from earlier pipeline formats are accepted and normalized:
+
+| Legacy key | Current key |
+|------------|-------------|
+| `kit_version_file` | `file` |
+| `commit_label` | `label` |
+
+When `file` is present and `enabled` is not declared, `enabled` defaults to
+`true` for backwards compatibility.
+
+---
+
+## Auditing auto-commits
+
+Every commit the pipeline pushes follows the pattern:
+
+```
+[<label>] bump <component> to <version>
+```
+
+To list all auto-update commits on a branch:
+
+```sh
+git log --oneline --grep='\[concourse\]' origin/main
+```
+
+Substituting `concourse` with whatever `label` you configured.  To see only
+kit bumps:
+
+```sh
+git log --oneline --grep='\[concourse\] bump kit'
+```
+
+To see who triggered a given bump (which Concourse build):
+
+```sh
+git show <commit> --format="%B" | head -5
+```
+
+The commit message body includes the genesis command output, which records the
+kit version that was active before the bump.
+
+---
+
+## Concourse group
+
+The job is placed in a dedicated `genesis-updates` group so it does not
+clutter the main deployment view.  All release-tracking resources appear only
+in that group.
diff --git a/docs/workflows/bosh-config-tracking.md b/docs/workflows/bosh-config-tracking.md
new file mode 100644
index 00000000..40e43662
--- /dev/null
+++ b/docs/workflows/bosh-config-tracking.md
@@ -0,0 +1,205 @@
+# BOSH Config Drift Tracking
+
+Genesis pipelines can watch a BOSH director's cloud-config, runtime-config, and
+CPI-config for out-of-band changes.  When a config changes on the director,
+Concourse detects it through a `bosh-config` resource and re-triggers the
+associated jobs so operators are alerted (or so a pending-changes summary is
+regenerated).
+
+Tracking is **opt-in** and defaults to off.  Pipelines that do not need drift
+detection produce no extra resources or job steps.
+
+---
+
+## Configuration
+
+### Global default
+
+```yaml
+configuration:
+  track_bosh_configs: true          # cloud + runtime for every env
+  # or a subset:
+  track_bosh_configs: [cloud, runtime, cpi]
+```
+
+Accepted values:
+
+| Value | Types tracked |
+|-------|--------------|
+| `true` / `yes` / `1` | `cloud`, `runtime` |
+| `false` / `no` / `0` | none (off) |
+| `[cloud]` | cloud-config only |
+| `[runtime]` | runtime-config only |
+| `[cpi]` | CPI-config only |
+| `[cloud, runtime, cpi]` | all three |
+
+### Per-environment override
+
+Set `genesis.pipeline.track_bosh_configs` in an env YAML file to override the
+global default for that environment:
+
+```yaml
+# prod.yml
+genesis:
+  pipeline:
+    track_bosh_configs: cloud,runtime,cpi   # comma-separated types
+    # or:
+    track_bosh_configs: false               # suppress tracking for this env
+```
+
+The per-env value shadows the global `configuration.track_bosh_configs` for
+that env only.  Other envs continue to use the global setting.
+
+---
+
+## Emitted resources
+
+For each configured type and each environment, one `bosh-config` resource is
+emitted named `<alias>-<type>-config`:
+
+| Type | Resource name | Icon |
+|------|--------------|------|
+| `cloud` | `<alias>-cloud-config` | `cloud` |
+| `runtime` | `<alias>-runtime-config` | `run-fast` |
+| `cpi` | `<alias>-cpi-config` | `chip` |
+
+Example for a `sandbox` environment with `track_bosh_configs: true`:
+
+```yaml
+- name: sandbox-cloud-config
+  type: bosh-config
+  icon: cloud
+  source:
+    target:        https://sandbox.bosh.example.com:25555
+    client:        admin
+    client_secret: ((bosh-admin-secret))
+    ca_cert:       ((bosh-ca-cert))
+    config:        cloud
+    all:           true
+
+- name: sandbox-runtime-config
+  type: bosh-config
+  icon: run-fast
+  source:
+    target:        https://sandbox.bosh.example.com:25555
+    client:        admin
+    client_secret: ((bosh-admin-secret))
+    ca_cert:       ((bosh-ca-cert))
+    config:        runtime
+    all:           true
+```
+
+The source fields are derived automatically from the env's `targets:` entry —
+no manual configuration of BOSH credentials is required.
+
+---
+
+## How it affects jobs
+
+### Notify job (`notify-<alias>-deployment-changes`)
+
+When bosh-config tracking is enabled, the notify job gains a triggering `get:`
+for each tracked type.  This means a config change on the director automatically
+causes Concourse to run `ci-show-changes` and report the pending diff — even if
+no Git changes are staged.
+
+```yaml
+- get: sandbox-cloud-config
+  trigger: true
+- get: sandbox-runtime-config
+  trigger: true
+```
+
+### Auto-trigger deploy job (`<alias>-deployment`)
+
+When `auto: true` is set on an environment and bosh-config tracking is enabled,
+the deploy job also gets a triggering get for each type.  A config change will
+kick off the full deployment automatically.
+
+```yaml
+- get: sandbox-cloud-config
+  trigger: true
+- get: sandbox-runtime-config
+  trigger: true
+```
+
+### Redeploy job (`<alias>-redeploy`)
+
+Redeploy jobs include a non-triggering `get:` for each tracked config type so
+the task container has the latest config snapshot available.  These do not
+trigger the job on their own.
+
+---
+
+## Examples
+
+### All environments: cloud + runtime
+
+```yaml
+configuration:
+  track_bosh_configs: true
+```
+
+### Only the production environment tracks all three types
+
+```yaml
+configuration:
+  track_bosh_configs: [cloud, runtime]   # global: cloud + runtime
+
+# prod.yml
+genesis:
+  pipeline:
+    track_bosh_configs: cloud,runtime,cpi  # prod adds cpi
+```
+
+### Opt a specific environment out of global tracking
+
+```yaml
+configuration:
+  track_bosh_configs: true   # all envs by default
+
+# sandbox.yml
+genesis:
+  pipeline:
+    track_bosh_configs: false  # sandbox is too noisy, skip it
+```
+
+### Track only CPI-config globally
+
+```yaml
+configuration:
+  track_bosh_configs: [cpi]
+```
+
+---
+
+## BOSH config resource type
+
+The `bosh-config` resource type is provided by
+`cfcommunity/bosh-config-resource`.  It is automatically declared as a resource
+type in the pipeline when any `bosh-config` resource is emitted — no manual
+`resource_types:` entry is needed.
+
+The `all: true` flag in the source causes the resource to track **all named
+configs** of the given type (cloud, runtime, or cpi) rather than a single
+named config.  This is the correct setting for monitoring the complete director
+state.
+
+---
+
+## OCFP mode
+
+When `configuration.ocfp: true` is set, each `bosh-config` resource source also
+includes a `name:` field set to the environment's full genesis env name (e.g.
+`us-west-1-sandbox`).  This narrows tracking to the specific named config used
+by that environment rather than all configs on the director.
+
+---
+
+## Workaround: manual resource declaration
+
+If fine-grained control is needed beyond what the built-in tracking supports
+(for example, watching a specific named config rather than `all: true`), declare
+the resource manually via the `ci.yml` pass-through and omit
+`track_bosh_configs` for that environment.  The pass-through resource will be
+merged into the generated pipeline by the Concourse provider.
diff --git a/docs/workflows/bosh-upgrade-locks.md b/docs/workflows/bosh-upgrade-locks.md
new file mode 100644
index 00000000..b13e609e
--- /dev/null
+++ b/docs/workflows/bosh-upgrade-locks.md
@@ -0,0 +1,186 @@
+# BOSH Upgrade Locks
+
+Genesis pipelines that manage a BOSH director alongside the deployments it hosts automatically wire a shared upgrade-lock to prevent a director upgrade from racing against a child deployment.
+
+## Overview
+
+When a child deployment's YAML file declares `genesis.bosh_env: <director-env>` and the named director is also present in the same pipeline, Genesis:
+
+1. Emits one shared `<director-alias>-bosh-lock` Concourse resource for the director.
+2. Each child's deploy (and redeploy) job acquires that shared lock before deploying, preventing the director from being upgraded while a child is in flight.
+3. The director's own deploy job also acquires its shared lock, preventing a child from deploying while the director is being upgraded.
+
+Locks are implemented with the `cfcommunity/locker-resource` via the OCF Locker service.
+
+## Configuration
+
+### Declaring the parent director
+
+In each child deployment's YAML file:
+
+```yaml
+# cf-lab.yml
+genesis:
+  env: cf-lab
+  bosh_env: bosh-lab     # name of the director env in this pipeline
+```
+
+`bosh_env` is read at pipeline-gen time. Genesis resolves the relationship only when the named director env is also included in the current pipeline — if the director lives in a separate, manually managed pipeline, the key is ignored and the child behaves as a standalone env.
+
+### Locker integration (required)
+
+BOSH upgrade locks require a locker integration. Add it to your `ci.yml`:
+
+```yaml
+integrations:
+  locker:
+    url:      https://locker.example.com
+    username: ((locker-username))
+    password: ((locker-password))
+```
+
+If a child env has a pipeline-managed BOSH director but no locker is configured, `genesis ci describe` will error early with instructions to either add the locker block or opt out with `bosh_upgrade_lock: false`.
+
+### Opting out per environment
+
+To disable the shared lock for a specific child — for example, a non-production env that does not need coordinated upgrades:
+
+```yaml
+# cf-lab.yml
+genesis:
+  env: cf-lab
+  bosh_env: bosh-lab
+  pipeline:
+    locks:
+      bosh_upgrade: false
+```
+
+An opted-out child falls back to standalone behaviour: its deploy job acquires a per-env `bosh-lock` resource scoped to its BOSH director URL, without coordinating with the director's own lock.
+
+The `locks:` block is extensible — future lock types will be added as sibling keys under it.
+
+## Lock topology
+
+There are three cases based on a deployment's relationship to its BOSH director:
+
+### Director
+
+A deployment is a director when at least one other pipeline env declares it as its `bosh_env`.
+
+- **Resource**: `<alias>-bosh-lock` using `lock_name: <alias>-bosh-upgrade`.  
+  A named lock is used rather than a BOSH URL so the pattern works for `bosh-create-env` directors (which have no known URL at pipeline-gen time).
+- **Deploy job**: acquires `<alias>-bosh-lock` (`dont-upgrade-bosh-on-me`), then `<alias>-deployment-lock` (`i-need-to-deploy-myself`).
+
+### Child (bosh_parent set, bosh_upgrade_lock=true)
+
+- **Resource**: no own `bosh-lock` resource — the director's shared resource is referenced directly.
+- **Deploy job**: acquires `<director-alias>-bosh-lock` (`dont-upgrade-bosh-on-me`), then `<alias>-deployment-lock`.
+
+### Standalone (no pipeline-managed parent)
+
+The traditional behaviour for envs whose BOSH director is not in the same pipeline.
+
+- **Resource**: `<alias>-bosh-lock` using `bosh_lock: <bosh-url>`.
+- **Deploy job**: acquires `<alias>-bosh-lock`, then `<alias>-deployment-lock`.
+
+## Lock keys
+
+| Key | Purpose |
+|-----|---------|
+| `dont-upgrade-bosh-on-me` | Held by child deploys on the director's bosh-lock; blocks a director upgrade from starting while a child is deploying |
+| `i-need-to-deploy-myself` | Held by each env's deploy on its own deployment-lock; serializes concurrent deploys of the same env |
+
+Both keys are released unconditionally in the job's `ensure` block.
+
+## Example: lab pipeline
+
+```
+bosh-lab  ──►  cf-lab
+          ──►  shield
+```
+
+```yaml
+# bosh-lab.yml
+genesis:
+  env: bosh-lab
+
+# cf-lab.yml
+genesis:
+  env: cf-lab
+  bosh_env: bosh-lab
+  pipeline:
+    prior_env: bosh-lab
+
+# shield.yml
+genesis:
+  env: shield
+  bosh_env: bosh-lab
+  pipeline:
+    prior_env: bosh-lab
+```
+
+Generated resources:
+
+| Name | Lock type | Source |
+|------|-----------|--------|
+| `bosh-lab-bosh-lock` | shared director | `lock_name: bosh-lab-bosh-upgrade` |
+| `bosh-lab-deployment-lock` | per-env deploy | `lock_name: bosh-lab-deployment` |
+| `cf-lab-deployment-lock` | per-env deploy | `lock_name: cf-lab-deployment` |
+| `shield-deployment-lock` | per-env deploy | `lock_name: shield-deployment` |
+
+Both `cf-lab-deployment` and `shield-deployment` jobs lock `bosh-lab-bosh-lock` before deploying. The `bosh-lab-deployment` job also locks `bosh-lab-bosh-lock` — so an upgrade cannot proceed while any child is deploying, and children cannot deploy while an upgrade is running.
+
+## Pipeline description annotation
+
+The `genesis ci describe` output identifies directors with a `DIRECTOR` annotation in the Mermaid diagram node label:
+
+```
+bosh-lab([bosh-lab\nDIRECTOR]) --> cf-lab
+bosh-lab([bosh-lab\nDIRECTOR]) --> shield
+```
+
+## Cross-pipeline directors
+
+If the BOSH director is managed by a separate pipeline (not listed in `env_dir`), `bosh_env` is silently ignored and the env falls back to standalone lock behaviour. This means you can safely declare `bosh_env` in all child YAML files regardless of whether the director is co-located in the same pipeline.
+
+## Debugging stuck locks
+
+A stuck lock means a previous job acquired the lock and never released it — either because the Concourse job was killed at the OS level (not just aborted), the worker crashed, or a bug prevented the `ensure` block from running.
+
+### Identifying the stuck lock
+
+In Concourse, a failed `put` to a locker resource with `lock_op: lock` will show the key and `locked_by` value in the task output:
+
+```
+Lock 'dont-upgrade-bosh-on-me' is already held by 'cf-lab-deployment'
+```
+
+This tells you which key is stuck (`dont-upgrade-bosh-on-me`) and which job last acquired it (`cf-lab-deployment`).
+
+### Releasing manually
+
+Use the OCF Locker HTTP API to release a stuck key directly:
+
+```bash
+# List all locks on the resource
+curl -u locker-user:locker-pass \
+  https://locker.example.com/locks/<lock-name>
+
+# Force-release a specific key
+curl -u locker-user:locker-pass -X DELETE \
+  https://locker.example.com/locks/<lock-name>/<key>
+```
+
+For BOSH upgrade locks:
+- `<lock-name>` is `<director-alias>-bosh-upgrade` (the `lock_name` from the resource source)
+- `<key>` is `dont-upgrade-bosh-on-me`
+
+For deployment locks:
+- `<lock-name>` is `<env>-deployment`
+- `<key>` is `i-need-to-deploy-myself`
+
+### Preventing recurrence
+
+If a Concourse worker crashes repeatedly without releasing locks, consider:
+- Increasing the Concourse worker `drain_timeout` so the worker has time to run `ensure` blocks on shutdown
+- Adding an alert on the locker service when a key is held longer than the expected maximum deploy duration
diff --git a/docs/workflows/deployment-status-signals.md b/docs/workflows/deployment-status-signals.md
new file mode 100644
index 00000000..526c55bd
--- /dev/null
+++ b/docs/workflows/deployment-status-signals.md
@@ -0,0 +1,179 @@
+# Deployment Status Signals
+
+Genesis pipelines can emit structured deployment status events — success, failure, abort, and error — through a generic signal abstraction backed by the `cfcommunity/shuttle-resource` Concourse custom resource type.
+
+## Overview
+
+When `status_signal` is configured, every deploy and redeploy job in the pipeline emits a Concourse put step for each of its four outcome hooks (`on_success`, `on_failure`, `on_abort`, `on_error`). External consumers — other pipelines, automation, dashboards — can get these signals to gate work on upstream deployment outcomes.
+
+The signal resource for each environment is named `<env>-signal`. The shuttle resource writes a small status record to a backing store (S3, GCS, or local file), which Concourse polls as a versioned resource.
+
+## Configuration
+
+### Global configuration
+
+Set `status_signal` in the `configuration:` block of your `ci.yml`:
+
+```yaml
+configuration:
+  status_signal:
+    backend: s3
+    bucket:            genesis-signals
+    region:            us-east-1
+    access_key_id:     ((aws-access-key-id))
+    secret_access_key: ((aws-secret-access-key))
+```
+
+This applies to every environment in the pipeline unless overridden or disabled per-env.
+
+### Backends
+
+**`file`** — Writes signal records to the Concourse worker filesystem. Useful for local testing or single-worker setups.
+
+```yaml
+status_signal:
+  backend: file
+  path: /tmp/genesis-signals    # defaults to /tmp/genesis-signals
+```
+
+**`s3`** — Writes to an S3 bucket. Suitable for multi-worker pipelines and cross-pipeline consumers.
+
+```yaml
+status_signal:
+  backend: s3
+  bucket:            genesis-signals
+  region:            us-east-1
+  access_key_id:     ((aws-access-key-id))
+  secret_access_key: ((aws-secret-access-key))
+  endpoint:          https://s3.example.com   # optional, for S3-compatible stores
+```
+
+**`gcs`** — Writes to a Google Cloud Storage bucket.
+
+```yaml
+status_signal:
+  backend: gcs
+  bucket:   genesis-signals
+  json_key: ((gcs-service-account-json))
+```
+
+### Optional global keys
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `prefix` | *(empty)* | Prepended to the per-env prefix: `<prefix>/<env>`. If unset, prefix is just the env name. |
+| `image` | `cfcommunity/shuttle-resource` | Override the shuttle resource Docker image. |
+| `image_tag` | `latest` | Override the image tag. |
+
+### Per-environment overrides
+
+In each environment's YAML file under `genesis.pipeline`:
+
+```yaml
+# sandbox.yml
+genesis:
+  env: sandbox
+  pipeline:
+    status_signal: s3           # override backend for this env only
+    signal_prefix: acme/sandbox # override prefix for this env
+```
+
+To disable signals for a specific environment:
+
+```yaml
+genesis:
+  env: prod
+  pipeline:
+    status_signal: false
+```
+
+| Value | Meaning |
+|-------|---------|
+| *(absent)* | Uses global config |
+| `file`, `s3`, `gcs` | Enables signals, overrides backend |
+| `true` / `1` | Enables signals, uses global backend |
+| `false` / `no` / `0` | Disables signals for this env |
+
+## Signal resource prefix
+
+The per-environment signal resource stores records under a prefix path. The effective prefix is resolved as follows:
+
+1. `signal_prefix` in the env's YAML — used verbatim
+2. Global `prefix` + `/` + env name (e.g., `mypipeline/sandbox`)
+3. Just the env name if no global prefix is set
+
+## Outcome hooks
+
+Each deploy and redeploy job emits a put step to `<alias>-signal` for all four Concourse outcome hooks:
+
+| Hook | Signal `status` |
+|------|----------------|
+| `on_success` | `success` |
+| `on_failure` | `failure` |
+| `on_abort` | `abort` |
+| `on_error` | `error` |
+
+The put params are:
+
+```yaml
+put: sandbox-signal
+params:
+  status: success
+  deployment: sandbox-deployment
+```
+
+When Slack/email notifications are also configured, the `on_success` and `on_failure` hooks combine both steps in an `in_parallel` block. The `on_abort` and `on_error` hooks emit the signal put directly (no notification for abort/error).
+
+## Cross-pipeline gating
+
+A downstream pipeline can gate on upstream deploy success by getting the signal resource:
+
+```yaml
+resources:
+  - name: sandbox-signal
+    type: shuttle
+    source:
+      backend: s3
+      bucket: genesis-signals
+      region: us-east-1
+      access_key_id:     ((aws-access-key-id))
+      secret_access_key: ((aws-secret-access-key))
+      prefix: sandbox
+
+jobs:
+  - name: integration-tests
+    plan:
+      - get: sandbox-signal
+        trigger: true
+        version: { status: success }
+      - task: run-tests
+        ...
+```
+
+## Redeploy signal trigger
+
+When an environment has `redeploy: signal` set, the `redeploy-<env>` job automatically triggers off the signal resource instead of running manually:
+
+```yaml
+genesis:
+  env: prod
+  pipeline:
+    redeploy: signal
+    status_signal: s3
+```
+
+This creates a `get: prod-signal, trigger: true, version: {status: success}` step at the top of the redeploy job plan. The redeploy fires whenever a successful deployment signal arrives for that env — useful for chaining a post-deploy health-check or forcing a redeploy after upstream changes.
+
+If `redeploy: signal` is set but no global `status_signal` is configured, the job falls back to manual trigger behaviour (no auto-trigger resource is wired).
+
+## Pipeline description annotation
+
+The `genesis ci describe` output annotates each environment with its active features:
+
+```
+Pipeline: cf
+Workflow: cf
+  sandbox              sandbox-deployment  [auto]  [REDEPLOY:CRON, SIGNAL:s3]
+  preprod              preprod-deployment  [manual] (triggered by sandbox)  [SIGNAL:s3]
+  prod                 prod-deployment     [manual] (triggered by preprod)  [REDEPLOY:SIGNAL, SIGNAL:s3]
+```
diff --git a/docs/workflows/notification-styles.md b/docs/workflows/notification-styles.md
new file mode 100644
index 00000000..4900328a
--- /dev/null
+++ b/docs/workflows/notification-styles.md
@@ -0,0 +1,135 @@
+# Notification Styles
+
+Genesis pipelines can emit Slack notifications for pipeline events. Four styles control what gets notified, when, and how. Styles can be combined with per-environment overrides and `@mentions` on failure.
+
+## Configuration
+
+Notification config lives in the `slack:` block of your pipeline integrations:
+
+```yaml
+# .genesis/ci/integrations.yml  (multi-file format)
+# — or —
+# integrations section of ci.yml  (legacy format)
+
+slack:
+  webhook:  ((slack-webhook))
+  channel:  '#deployments'
+  style:    grouped           # per-env | grouped | minimal | none
+  mentions_on_failure:
+    - '@sre-oncall'
+  per_env_overrides:
+    lm-aws-useast1-hs-prod:
+      channel:  '#prod-deployments'
+      mentions_on_failure:
+        - '@prod-sre'
+```
+
+All keys except `webhook` and `channel` are optional.
+
+## Styles
+
+### `per-env` (default)
+
+A pending-changes notification job (`notify-<env>-<type>-changes`) is created for every non-auto environment. The deploy job depends on the notify job — it runs only after the operator acknowledges the changes. All envs share the global Slack channel unless overridden.
+
+```
+notify-sandbox-deployment-changes  →  sandbox-deployment
+notify-prod-deployment-changes     →  prod-deployment
+```
+
+**Use when**: you want humans to review and approve each deployment manually.
+
+### `grouped`
+
+Same notify jobs as `per-env`, but they are collected into a separate `notifications` Concourse group rather than sitting inline with the deploy pipeline. Deploy jobs do not depend on notify jobs — they can run independently.
+
+```
+Group: my-pipeline
+  sandbox-deployment, prod-deployment
+
+Group: notifications
+  notify-sandbox-deployment-changes, notify-prod-deployment-changes
+```
+
+**Use when**: you want pending-change visibility but don't want notifications to gate deployments.
+
+### `minimal`
+
+No pending-changes notify jobs are created. Slack notifications are emitted only on failure (via the `on_failure` hook). Success is silent.
+
+```
+sandbox-deployment  (on_failure → Slack alert)
+prod-deployment     (on_failure → Slack alert)
+```
+
+**Use when**: you only want to know about failures — lab pipelines, automated CI loops, high-frequency deploy pipelines where success noise is unwanted.
+
+### `none`
+
+No Slack notifications at all. No `slack` resource, no notify jobs, no outcome hooks. The `slack-notification` Concourse resource type is also omitted.
+
+**Use when**: throwaway or local test pipelines where notifications are irrelevant.
+
+## Decision matrix
+
+| Scenario | Recommended style |
+|----------|------------------|
+| Production pipeline, manual approvals required | `per-env` |
+| Large pipeline, separate ops notification channel | `grouped` |
+| Automated CI, alert on failures only | `minimal` |
+| Lab / ephemeral test environment | `none` |
+| High-frequency nightly deploys | `minimal` |
+
+## `mentions_on_failure`
+
+A list of Slack handles or role mentions prepended to failure notification text. Applies globally unless overridden per env.
+
+```yaml
+slack:
+  mentions_on_failure:
+    - '@sre-oncall'
+    - '@platform-team'
+```
+
+Output for a failure: `@sre-oncall @platform-team: test-pipeline: Deployment to prod-deployment failed`
+
+Mentions are **never** added to success notifications.
+
+## Per-environment overrides
+
+Any environment can override the global `channel` and/or `mentions_on_failure`:
+
+```yaml
+slack:
+  channel: '#deployments'
+  mentions_on_failure: []
+  per_env_overrides:
+    lm-aws-useast1-hs-prod:
+      channel:  '#prod-critical'
+      mentions_on_failure:
+        - '@prod-sre'
+```
+
+The override key is the environment name as declared in the env YAML file. Any keys absent from the override inherit from the global config.
+
+## Backward compatibility
+
+The legacy `notifications: grouped` format in `ci.yml` is still recognized:
+
+| Legacy value | New equivalent |
+|-------------|---------------|
+| `notifications: grouped` | `slack.style: grouped` |
+| `notifications: inline` (or absent) | `slack.style: per-env` |
+
+The old `integrations.notifications` array format is also still accepted. Genesis will normalize it automatically:
+
+```yaml
+# Old format — still works
+integrations:
+  notifications:
+    - type: slack
+      webhook: ((hook))
+      channel: '#ci'
+```
+
+This is treated as `style: per-env` (or `grouped` if `notifications: grouped` is also set). New pipelines should use the `slack:` block directly.
diff --git a/docs/workflows/pipeline-propagation.md b/docs/workflows/pipeline-propagation.md
new file mode 100644
index 00000000..60021d7f
--- /dev/null
+++ b/docs/workflows/pipeline-propagation.md
@@ -0,0 +1,108 @@
+# Pipeline Propagation
+
+Genesis propagates environment configuration through a controlled branch topology where each environment's files live on their own git branch. The `genesis propagate` command advances those branches when the upstream `control` branch changes.
+
+## Overview
+
+The pipeline uses a control branch (commonly `main` or `control`) where all shared and per-environment files are committed. `genesis propagate` walks the topology and, for each environment, commits only the files relevant to that environment onto the environment's own branch. Concourse monitors those per-env branches and triggers deployments when they change.
+
+## Branch Topology
+
+Each environment has a corresponding git branch (e.g., `sandbox`, `preprod`, `prod`). The `genesis.pipeline.prior_env` key in each environment YAML file defines the propagation order:
+
+```yaml
+# prod.yml
+genesis:
+  env: prod
+  pipeline:
+    prior_env: preprod
+```
+
+This makes `preprod` the upstream of `prod` — Concourse deploys `preprod` first, then triggers `prod`.
+
+## PR-Based Propagation
+
+For environments that require review before deployment, set `require_pr: true`:
+
+```yaml
+# prod.yml
+genesis:
+  env: prod
+  pipeline:
+    prior_env: preprod
+    require_pr: true
+```
+
+When `require_pr` is set, `genesis propagate` creates a `propagate/<env>/<control-sha>` branch instead of pushing directly to the env branch, then opens (or updates) a GitHub Pull Request for review. Merging the PR is what triggers the Concourse deploy.
+
+### Idempotency
+
+Re-running `genesis propagate` with the same control SHA updates the existing PR rather than creating a new one. The check uses the GitHub API to find an open PR with the matching head branch — this works across machines and CI runs.
+
+### Propagation Flags
+
+| Flag | Behavior |
+|------|----------|
+| `--dry-run` | Shows what would happen; no remote changes |
+| `--no-push` | Commits locally but does not push or open PRs |
+
+### GitHub Credentials
+
+PR creation requires a GitHub token with `repo` scope. Set `GITHUB_AUTH_TOKEN` in the environment. The token is validated before any git operations begin.
+
+## Redeploy Lane
+
+The redeploy lane lets you force-redeploy an environment without any content changes — useful for recovering from a failed deployment, rotating credentials, or periodic health-checks.
+
+### Configuration
+
+In the environment's YAML file under `genesis.pipeline`:
+
+```yaml
+genesis:
+  pipeline:
+    redeploy: manual          # or: cron, signal
+    redeploy_cron_start: "04:00"   # only required for cron mode
+    redeploy_cron_stop:  "05:00"   # only required for cron mode
+```
+
+### Trigger Modes
+
+**`manual`** — A `redeploy-<env>` Concourse job is created with no auto-trigger. An operator triggers it via the UI or `fly trigger-job`.
+
+**`signal`** — Identical to `manual` in pipeline terms; the naming convention communicates that the trigger is expected from an external automated system rather than a human.
+
+**`cron`** — A Concourse `time` resource is created for the environment and wired as the job trigger. The job runs automatically whenever Concourse observes the time window.
+
+```yaml
+# Daily redeploy between 04:00–05:00 UTC
+genesis:
+  pipeline:
+    redeploy: cron
+    redeploy_cron_start: "04:00"
+    redeploy_cron_stop:  "05:00"
+```
+
+When no `redeploy_cron_start` / `redeploy_cron_stop` are specified, they default to `04:00` and `05:00` UTC.
+
+### What the Redeploy Job Does
+
+- Acquires the same dual locks as a normal deploy (`<env>-bosh-lock` and `<env>-deployment-lock`), ensuring it coordinates with in-flight normal deploys.
+- Gets the current env branch and git resource (no trigger, no change detection).
+- Runs `ci-pipeline-deploy` with `PREVIOUS_ENV=~` (no cache, no propagation from upstream).
+- Does **not** generate or push a cache after deploying — only normal deploys advance the cache.
+- Does **not** trigger downstream environments.
+
+### Pipeline Groups
+
+Any pipeline that has at least one env with `redeploy` configured will emit a `redeploy` group in Concourse, separate from the main workflow group. This keeps the redeploy jobs visible but out of the main deployment flow.
+
+### Mermaid Diagram Annotation
+
+Environments with redeploy configured are annotated in the auto-generated pipeline Mermaid diagram:
+
+```
+sandbox --> preprod[(preprod\nREDEPLOY)] --> prod
+```
+
+Annotations can combine: `PR+MANUAL+REDEPLOY` for an env that has all three flags set.
diff --git a/docs/workflows/task-library.md b/docs/workflows/task-library.md
new file mode 100644
index 00000000..11d9d152
--- /dev/null
+++ b/docs/workflows/task-library.md
@@ -0,0 +1,150 @@
+# Task Library
+
+A task library lets you version-control custom pipeline task files in a separate git repository and reference them by name from any Genesis pipeline job. This keeps operator-written task logic out of the environment repository.
+
+## Configuration
+
+Task library config lives under `configuration.task_library` in `ci/configuration.yml` (multi-file format) or in the `configuration:` section of `pipeline.yml`:
+
+```yaml
+configuration:
+  task_library:
+    uri:           https://github.com/org/pipeline-tasks.git
+    branch:        main             # optional, default 'main'
+    path:          tasks            # optional subdirectory within the repo
+    resource_name: tasks            # optional Concourse resource name, default 'tasks'
+    auth:
+      type:        ssh-key          # 'ssh-key' or 'token'
+      private_key: ((library-key))  # for ssh-key
+```
+
+All keys except `uri` are optional.
+
+## How it works
+
+### Concourse
+
+When `task_library` is configured, Genesis:
+
+1. Declares a `git` resource (named by `resource_name`, default `tasks`) pointing at the external repository.
+2. Adds a `get: tasks` (non-triggering) step to every deploy and redeploy job's `in_parallel` block.
+3. Adds `{ name: tasks }` to the inputs list of every task config, making the library available at `/tmp/build/<id>/tasks/` inside the running task.
+4. Sets the `GENESIS_TASK_LIBRARY_PATH` environment variable in each task to the path where task YAML files can be found:
+   - Without `path`: `tasks` (equals the resource_name)
+   - With `path: tasks`: `tasks/tasks`
+
+### GitHub Actions
+
+`Provider::GithubActions` adds an equivalent `actions/checkout@v4` step that checks out the task library repository into the `path` subdirectory of the runner workspace. Token-based auth is forwarded as a `${{ secrets.* }}` expression.
+
+## Authentication for private repositories
+
+### SSH key
+
+```yaml
+task_library:
+  uri:  git@github.com:org/private-tasks.git
+  auth:
+    type:        ssh-key
+    private_key: ((task-library-key))
+```
+
+### Personal access token / GitHub App token
+
+```yaml
+task_library:
+  uri:  https://github.com/org/private-tasks.git
+  auth:
+    type:     token
+    password: ((library-token))
+```
+
+`username` defaults to `x-oauth-basic` when omitted (works with GitHub PATs and Apps). Supply an explicit `username` if your git host requires one.
+
+## Path resolution
+
+The `GENESIS_TASK_LIBRARY_PATH` variable tells a genesis task where to look for library task files at runtime:
+
+| Configuration | `GENESIS_TASK_LIBRARY_PATH` |
+|---------------|----------------------------|
+| `resource_name: tasks` (no path) | `tasks` |
+| `resource_name: tasks`, `path: tasks` | `tasks/tasks` |
+| `resource_name: lib`, `path: ci/tasks` | `lib/ci/tasks` |
+
+Within a running task the full file path would be `$GENESIS_TASK_LIBRARY_PATH/<task-name>.yml`.
+
+## Example: shared ops tasks
+
+```yaml
+# ci/configuration.yml
+configuration:
+  task_library:
+    uri:    https://github.com/my-org/genesis-pipeline-tasks.git
+    branch: stable
+    path:   tasks
+    auth:
+      type:     token
+      password: ((github-tasks-token))
+```
+
+Resulting Concourse pipeline fragment:
+
+```yaml
+resources:
+  - name: tasks
+    type: git
+    icon: source-repository
+    source:
+      uri:      https://github.com/my-org/genesis-pipeline-tasks.git
+      branch:   stable
+      username: x-oauth-basic
+      password: ((github-tasks-token))
+
+jobs:
+  - name: sandbox-deployment
+    plan:
+      - do:
+        - in_parallel:
+            - get: sandbox-changes
+            - get: git
+            - get: tasks
+              trigger: false
+        - task: bosh-deploy
+          config:
+            inputs:
+              - name: sandbox-changes
+              - name: git
+              - name: tasks
+            params:
+              GENESIS_TASK_LIBRARY_PATH: tasks/tasks
+              ...
+```
+
+## GitHub Actions equivalent
+
+For the same configuration, `Provider::GithubActions` adds:
+
+```yaml
+steps:
+  - name: Checkout repository
+    uses: actions/checkout@v4
+    with:
+      fetch-depth: 0
+
+  - name: Checkout task library (tasks)
+    uses: actions/checkout@v4
+    with:
+      repository: my-org/genesis-pipeline-tasks
+      ref:        stable
+      path:       tasks/tasks
+      token:      ${{ secrets.GITHUB_TASKS_TOKEN }}
+```
+
+## Decision matrix
+
+| Scenario | Recommended config |
+|----------|--------------------|
+| Shared ops tasks across multiple pipelines | `task_library` with a dedicated repo |
+| Single pipeline, few tasks | Inline task config (no library needed) |
+| Private tasks repo | `auth: { type: token, password: ... }` |
+| Monorepo with tasks in a subdirectory | `uri: <same-repo>`, `path: <subdir>` |
diff --git a/lib/Genesis/CI/Compiler.pm b/lib/Genesis/CI/Compiler.pm
index 6a272402..0c97a697 100644
--- a/lib/Genesis/CI/Compiler.pm
+++ b/lib/Genesis/CI/Compiler.pm
@@ -9,6 +9,14 @@ use Genesis::CI::Compiler::ScriptDiscovery;
 use Genesis::CI::Compiler::ASTBuilder;
 use Genesis::CI::Compiler::PipelineDescriptor;
 
+# Register as the owner of the ci: section in .genesis/config.
+# This runs at module load time so Top.pm's _validate_config() can
+# delegate ci: section validation to us when we're loaded.
+{
+	require Genesis::Top;
+	Genesis::Top->register_config_section('ci', __PACKAGE__);
+}
+
 ### Constructor {{{
 
 # new - create a new compiler instance {{{
@@ -90,7 +98,23 @@ sub compile {
 	eval { require $provider_info->{file} } ## no critic
 		or bail("Failed to load CI provider '%s': %s", $provider_type, $@);
 
-	my $provider = $provider_info->{class}->new(ast => $ast, top => $self->{top});
+	# Extract provider options from parsed config (ci.provider: section)
+	# and merge with any caller-supplied opts.  Normalize caller opts from their
+	# CLI form (ci-* prefixed, hyphenated) to config/schema form (unprefixed, underscored)
+	# so that provider_option() and provider_config() always see consistent keys.
+	require Genesis::CI::Compiler::PipelineProvider;
+	my $provider_opts = {
+		%{ $parsed->{provider} || {} },
+		%{ Genesis::CI::Compiler::PipelineProvider->normalize_provider_opts(
+			$opts{provider_opts} || {}
+		) },
+	};
+
+	my $provider = $provider_info->{class}->new(
+		ast           => $ast,
+		top           => $self->{top},
+		provider_opts => $provider_opts,
+	);
 	my $raw_output = $provider->generate_from_ast($ast);
 
 	# Wrap raw output into file map using provider's output_files manifest
@@ -145,6 +169,77 @@ sub can_compile_from_env_files {
 	);
 }
 
+# }}}
+# can_compile_from_genesis_config - detect if ci: section exists in .genesis/config {{{
+#
+# Returns true when $top has a Genesis::Config with a ci: key, meaning
+# CI configuration is embedded inline in .genesis/config rather than in
+# separate files under .genesis/ci/.
+sub can_compile_from_genesis_config {
+	my ($class, $top) = @_;
+	return 0 unless $top && $top->can('config');
+	return 0 unless eval { $top->config->has('ci') };
+	return 1;
+}
+
+# }}}
+# validate_config_section - validate the ci: section delegated by Top.pm {{{
+#
+# Called by Top::_validate_config() when this module is loaded and a ci: key
+# exists in .genesis/config.  Performs structural validation; detailed
+# cross-reference checks happen later in Compiler::Validator during compile().
+sub validate_config_section {
+	my ($class, $data, $top) = @_;
+
+	return unless defined $data;
+	bail("'ci' configuration in .genesis/config must be a hash")
+		unless ref($data) eq 'HASH';
+
+	# Validate ci.provider section against the provider's own schema.
+	# The 'manual' provider has no compiler class — skip validation.
+	if (my $provider_data = $data->{provider}) {
+		bail("'ci.provider' must be a hash")
+			unless ref($provider_data) eq 'HASH';
+		# The 'manual' provider has no compiler class — skip validation.
+		return if ($provider_data->{type} || '') eq 'manual';
+
+		my $type = $provider_data->{type};
+		bail("'ci.provider.type' is required") unless $type;
+
+		# Load provider class to get its schema
+		my $provider_info = eval { $class->_resolve_provider_class($type) };
+		if ($@) {
+			bail("'ci.provider.type' is '%s', which is not a known CI provider type.  ".
+				"Valid types: %s", $type,
+				join(', ', Genesis::CI::Compiler::PipelineProvider->known_providers()));
+		}
+
+		eval { require $provider_info->{file} };  ## no critic
+		if ($@) {
+			bail("Failed to load CI provider '%s' for config validation: %s", $type, $@);
+		}
+
+		my $schema   = $provider_info->{class}->provider_options_schema();
+		my $defaults = $provider_info->{class}->provider_options_defaults();
+
+		# Check required keys
+		for my $key (sort keys %$schema) {
+			my $spec = $schema->{$key};
+			next unless $spec->{required};
+			bail("'ci.provider.%s' is required for provider type '%s'", $key, $type)
+				unless defined $provider_data->{$key};
+		}
+
+		# Check unknown keys
+		for my $key (sort keys %$provider_data) {
+			next if exists $schema->{$key};
+			bail("'ci.provider.%s' is not a recognized option for provider type '%s'.  ".
+				"Valid options: %s",
+				$key, $type, join(', ', sort keys %$schema));
+		}
+	}
+}
+
 # }}}
 # }}}
 ### Internal Methods {{{
@@ -180,8 +275,10 @@ sub _apply_provider_overrides {
 		my $base_path = "$dir/override-base-${filename}";
 		open(my $fh, '>', $base_path)
 			or bail("Cannot write temporary override base %s: %s", $base_path, $!);
-		print $fh $content;
-		close $fh;
+		print $fh $content
+			or bail("Cannot write to temporary override base %s: %s", $base_path, $!);
+		close $fh
+			or bail("Cannot flush temporary override base %s: %s", $base_path, $!);
 
 		my ($merged_yaml, $rc) = run(
 			'spruce', 'merge', $base_path, $override_file
diff --git a/lib/Genesis/CI/Compiler/AST.pm b/lib/Genesis/CI/Compiler/AST.pm
index e077e40c..703a6b47 100644
--- a/lib/Genesis/CI/Compiler/AST.pm
+++ b/lib/Genesis/CI/Compiler/AST.pm
@@ -132,9 +132,9 @@ sub trigger_names {
 sub resources_matching {
 	my ($self, $pattern) = @_;
 
-	my $regex = $pattern;
-	$regex =~ s/\*/.*/g;
-	$regex =~ s/\?/./g;
+	my $regex = join('', map {
+		$_ eq '*' ? '.*' : $_ eq '?' ? '.' : quotemeta($_)
+	} split(/([*?])/, $pattern, -1));
 	$regex = qr/^$regex$/;
 
 	my @matching;
@@ -149,9 +149,9 @@ sub resources_matching {
 sub targets_matching {
 	my ($self, $pattern) = @_;
 
-	my $regex = $pattern;
-	$regex =~ s/\*/.*/g;
-	$regex =~ s/\?/./g;
+	my $regex = join('', map {
+		$_ eq '*' ? '.*' : $_ eq '?' ? '.' : quotemeta($_)
+	} split(/([*?])/, $pattern, -1));
 	$regex = qr/^$regex$/;
 
 	my @matching;
@@ -350,7 +350,7 @@ the generic pipeline and should not be accessed by providers directly.
   my $resources      = $ast->pipeline_resources;
   my $jobs           = $ast->jobs;
   my $groups         = $ast->groups;
-  my $dot            = $ast->graphviz;
+  my $dot            = $ast->mermaid;
   my $text           = $ast->description;
 
 =head1 SEE ALSO
diff --git a/lib/Genesis/CI/Compiler/ASTBuilder.pm b/lib/Genesis/CI/Compiler/ASTBuilder.pm
index 23f424f6..61dc10b7 100644
--- a/lib/Genesis/CI/Compiler/ASTBuilder.pm
+++ b/lib/Genesis/CI/Compiler/ASTBuilder.pm
@@ -3,6 +3,7 @@ use strict;
 use warnings;
 
 use Genesis;
+use Genesis::Top ();
 use Genesis::CI::Compiler::AST;
 use JSON::PP;
 
@@ -58,13 +59,22 @@ sub _build_from_legacy {
 
 	# Branches
 	my $branches = {
-		live          => $p->{git}{branch} || 'master',
+		Genesis::Top::CI_PIPELINE_CONTROL_KEY() => $p->{git}{branch} || 'master',
 		target_prefix => 'target/',
 	};
 
 	# Integrations (already normalized by parser)
 	my $integrations = $parsed->{integrations};
 
+	# Normalize Slack config; apply legacy style flag
+	_normalize_slack_config($integrations);
+	if (my $s = $integrations->{slack}) {
+		$s->{style} //= do {
+			my $raw = $p->{notifications} || '';
+			$raw eq 'grouped' ? 'grouped' : 'per-env';
+		};
+	}
+
 	# Targets (already normalized by parser)
 	my $targets_data = $parsed->{targets}{targets} || $parsed->{targets};
 
@@ -92,6 +102,7 @@ sub _build_from_legacy {
 		},
 		'require-passed-caches' => $p->{'require-passed-caches'},
 	};
+	_normalize_auto_update($configuration->{auto_update});
 
 	# Provider config - include legacy raw pipeline data for Concourse bridge
 	my $provider_config = $parsed->{provider_config} || {};
@@ -173,8 +184,21 @@ sub _build_legacy_workflows {
 			my ($ef_nodes) = $self->_build_from_env_files($env_dir);
 			for my $env (keys %nodes) {
 				my $ef = $ef_nodes->{$env} or next;
-				$nodes{$env}{require_pr} = $ef->{require_pr};
-				$nodes{$env}{manual}     = $ef->{manual};
+				$nodes{$env}{require_pr}          = $ef->{require_pr};
+				$nodes{$env}{manual}              = $ef->{manual};
+				$nodes{$env}{redeploy}            = $ef->{redeploy};
+				$nodes{$env}{redeploy_cron_start} = $ef->{redeploy_cron_start};
+				$nodes{$env}{redeploy_cron_stop}  = $ef->{redeploy_cron_stop};
+				$nodes{$env}{status_signal}       = $ef->{status_signal};
+				$nodes{$env}{signal_prefix}       = $ef->{signal_prefix};
+				# bosh_parent only valid if the director is also in this pipeline
+				my $bp    = $ef->{bosh_parent} // '';
+				my $locks = $ef->{locks} || {};
+				$nodes{$env}{bosh_parent}       = (exists $nodes{$bp}) ? $bp : '';
+				$nodes{$env}{bosh_upgrade_lock} =
+					exists $locks->{bosh_upgrade}
+						? _truthy($locks->{bosh_upgrade})
+						: 1;
 			}
 		}
 
@@ -216,13 +240,19 @@ sub _build_from_multi_file {
 
 	# Branches
 	my $branches = $pipeline->{branches} || {
-		live          => 'main',
-		target_prefix => 'target/',
+		Genesis::Top::CI_PIPELINE_CONTROL_KEY() => 'main',
+		target_prefix                            => 'target/',
 	};
 
 	# Integrations
 	my $integrations = $parsed->{integrations} || {};
 
+	# Normalize Slack config; default style if absent
+	_normalize_slack_config($integrations);
+	if (my $s = $integrations->{slack}) {
+		$s->{style} //= 'per-env';
+	}
+
 	# Targets (legacy accessor)
 	my $targets_data = $parsed->{targets}{targets} || $parsed->{targets} || {};
 
@@ -249,6 +279,7 @@ sub _build_from_multi_file {
 
 	# Configuration
 	my $configuration = $pipeline->{configuration} || {};
+	_normalize_auto_update($configuration->{auto_update});
 
 	# Provider config
 	my $provider_config = $parsed->{provider_config} || {};
@@ -378,36 +409,92 @@ sub _build_workflow_graph {
 sub _build_from_env_files {
 	my ($self, $dir) = @_;
 
-	my (%nodes, %prior_envs);
-
 	opendir(my $dh, $dir) or return ({}, []);
 	my @files = sort grep { /\.ya?ml$/i && -f "$dir/$_" } readdir($dh);
 	closedir $dh;
 
+	# Pass 1: enumerate valid environments (Top::has_env filters out
+	# shared parent config files like lmelt.yml that lack `genesis.env`
+	# and kit info) and collect their genesis.pipeline data.
+	my $top = $self->{top};
+	my (%pipeline_data, %file_exists);
 	for my $file (@files) {
-		my $pipeline_data = _read_genesis_pipeline_keys("$dir/$file");
-		next unless %$pipeline_data;
-
 		(my $env = $file) =~ s/\.ya?ml$//i;
+		next unless $top && $top->has_env($env);
+		$file_exists{$env} = 1;
+		my $data = _read_genesis_pipeline_keys("$dir/$file");
+		$pipeline_data{$env} = $data if %$data;
+	}
+
+	# Identify envs referenced as prior_env — these are pipeline entrypoints
+	# that may have no genesis.pipeline block themselves (Phase C design).
+	my %referenced_upstream;
+	for my $env (keys %pipeline_data) {
+		my $upstream = $pipeline_data{$env}{prior_env} or next;
+		$referenced_upstream{$upstream} = 1;
+	}
 
+	# Pass 2: every valid env becomes a node (so envs without any
+	# genesis.pipeline block still appear in the DAG — useful for
+	# pipeline-status), plus any upstream reference that resolves to a
+	# file on disk.
+	my %nodes;
+	my %prior_env_map;
+	my %envs_to_include = (
+		(map { $_ => ($pipeline_data{$_} // {}) } keys %file_exists),
+		map { $_ => {} } grep { $file_exists{$_} } keys %referenced_upstream,
+	);
+
+	for my $env (sort keys %envs_to_include) {
+		my $data = $pipeline_data{$env} || {};
+		my $rd = $data->{redeploy} || '';
+		if ($rd && $rd !~ /^(manual|cron|signal)$/) {
+			$rd = _truthy($rd) ? 'manual' : '';
+		}
+		my $ss = $data->{status_signal} || '';
+		if ($ss && $ss !~ /^(false|no|0|file|s3|gcs)$/i && _truthy($ss)) {
+			$ss = '1';  # truthy shorthand → "enabled, use global config"
+		} elsif ($ss && $ss =~ /^(false|no|0)$/i) {
+			$ss = '0';  # normalized disabled
+		}
 		$nodes{$env} = {
-			stage_name  => $env,
-			target_name => $env,
-			alias       => $env,
-			genesis_env => $env,
-			auto        => 0,
-			type        => 'deployment',
-			require_pr  => _truthy($pipeline_data->{require_pr}),
-			manual      => _truthy($pipeline_data->{manual}),
+			stage_name          => $env,
+			target_name         => $env,
+			alias               => $env,
+			genesis_env         => $env,
+			auto                => 0,
+			type                => 'deployment',
+			require_pr          => _truthy($data->{require_pr}),
+			manual              => _truthy($data->{manual}),
+			redeploy            => $rd,
+			redeploy_cron_start => $data->{redeploy_cron_start} || '',
+			redeploy_cron_stop  => $data->{redeploy_cron_stop}  || '',
+			status_signal       => $ss,
+			signal_prefix       => $data->{signal_prefix} || '',
+			bosh_parent         => '',  # resolved in second pass below
+			bosh_upgrade_lock   => 1,   # default: enabled
+			track_bosh_configs  => $data->{track_bosh_configs},
 		};
+		$prior_env_map{$env} = $data->{prior_env} if $data->{prior_env};
+	}
 
-		$prior_envs{$env} = $pipeline_data->{prior_env}
-			if $pipeline_data->{prior_env};
+	# Second pass: resolve bosh_parent from genesis.bosh_env — only when the
+	# named director is also a pipeline-managed env in this same node set.
+	for my $env (sort keys %envs_to_include) {
+		my $data   = $pipeline_data{$env} || {};
+		my $be     = $data->{_bosh_env}  || '';
+		next unless $be && exists $nodes{$be};
+		my $locks = $data->{locks} || {};
+		$nodes{$env}{bosh_parent}       = $be;
+		$nodes{$env}{bosh_upgrade_lock} =
+			exists $locks->{bosh_upgrade}
+				? _truthy($locks->{bosh_upgrade})
+				: 1;
 	}
 
 	my @edges;
-	for my $env (sort keys %prior_envs) {
-		my $upstream = $prior_envs{$env};
+	for my $env (sort keys %prior_env_map) {
+		my $upstream = $prior_env_map{$env};
 		push @edges, { from => $upstream, to => $env }
 			if exists $nodes{$upstream};
 	}
@@ -419,15 +506,91 @@ sub _build_from_env_files {
 # }}}
 ### Internal Helpers {{{
 
-# _read_genesis_pipeline_keys - extract genesis.pipeline.* from a YAML file {{{
+# _normalize_auto_update - normalize auto_update config to internal representation {{{
+#
+# Accepts both the legacy format (file, label) and the v2 format
+# (kit_version_file, commit_label, enabled, update_genesis, update_kit,
+# target_branch).  Normalizes in-place so downstream code only needs to
+# read the internal keys.
 #
-# Reads a YAML file line-by-line looking for the nested structure:
+# Internal keys after normalization:
+#   enabled        — 0/1; legacy: enabled when 'file' is present
+#   file           — kit version file path (from kit_version_file or file)
+#   label          — commit prefix (from commit_label or label)
+#   update_genesis — 0/1, default 1
+#   update_kit     — 0/1, default 1
+#   target_branch  — optional branch override for the push commit
+sub _normalize_auto_update {
+	my ($au) = @_;
+	return unless ref($au) eq 'HASH';
+
+	# Key aliases: v2 names → internal names
+	$au->{file}  //= $au->{kit_version_file} if defined $au->{kit_version_file};
+	$au->{label} //= $au->{commit_label}     if defined $au->{commit_label};
+
+	# Feature flag defaults
+	$au->{update_genesis} //= 1;
+	$au->{update_kit}     //= 1;
+
+	# enabled: legacy path auto-enables when 'file' is declared;
+	# v2 path requires explicit enabled: true
+	if (!defined $au->{enabled}) {
+		$au->{enabled} = defined($au->{file}) ? 1 : 0;
+	} else {
+		$au->{enabled} = _truthy($au->{enabled}) ? 1 : 0;
+	}
+}
+
+# }}}
+# _normalize_slack_config - normalize Slack notification config to integrations.slack {{{
+#
+# Accepts either the new structured format:
+#   integrations.slack: { webhook, channel, style, mentions_on_failure, per_env_overrides }
+# or the legacy notifications array format:
+#   integrations.notifications: [{ type: slack, webhook, channel, ... }]
+#
+# Normalizes integrations.slack in-place.  The caller is responsible for
+# defaulting the style key afterwards (since it depends on the source format).
+sub _normalize_slack_config {
+	my ($integrations) = @_;
+
+	if (my $s = $integrations->{slack}) {
+		# New format already present — ensure structural defaults
+		$s->{mentions_on_failure} //= [];
+		$s->{per_env_overrides}   //= {};
+		return 1;
+	}
+
+	# Legacy format: extract Slack entry from the notifications array
+	my $notifs = $integrations->{notifications} || [];
+	$notifs = [] unless ref($notifs) eq 'ARRAY';
+	my ($sn) = grep { ref($_) eq 'HASH' && ($_->{type} || '') eq 'slack' } @$notifs;
+	return 0 unless $sn;
+
+	$integrations->{slack} = {
+		webhook             => $sn->{webhook},
+		channel             => $sn->{channel},
+		username            => $sn->{username},
+		icon_url            => $sn->{icon},
+		mentions_on_failure => [],
+		per_env_overrides   => {},
+		# style: set by caller based on legacy notifications: flag
+	};
+	return 0;
+}
+
+# }}}
+# _read_genesis_pipeline_keys - extract genesis-level and genesis.pipeline.* keys {{{
+#
+# Reads a YAML file line-by-line capturing:
 #   genesis:
+#     bosh_env: <value>      (genesis-level — stored as _bosh_env)
 #     pipeline:
-#       key: value
+#       key: value           (pipeline sub-keys — stored directly)
+#       locks:
+#         bosh_upgrade: val  (stored as locks->{bosh_upgrade})
 #
-# Returns a hashref of the pipeline sub-keys (may be empty).
-# No external YAML parser needed — only flat scalar values are extracted.
+# Returns a hashref (may be empty).  No external YAML parser needed.
 sub _read_genesis_pipeline_keys {
 	my ($file) = @_;
 
@@ -436,7 +599,7 @@ sub _read_genesis_pipeline_keys {
 	close $fh;
 
 	my %result;
-	my ($in_genesis, $in_pipeline) = (0, 0);
+	my ($in_genesis, $in_pipeline, $in_locks) = (0, 0, 0);
 
 	for my $line (@lines) {
 		chomp $line;
@@ -445,28 +608,56 @@ sub _read_genesis_pipeline_keys {
 		# Top-level key resets context
 		if ($line =~ /^([a-zA-Z_][a-zA-Z0-9_]*):\s*(.*)$/) {
 			my $key = $1;
-			$in_genesis  = ($key eq 'genesis') ? 1 : 0;
+			$in_genesis  = $key eq 'genesis' ? 1 : 0;
 			$in_pipeline = 0;
+			$in_locks    = 0;
 			next;
 		}
 
 		# 'pipeline:' under genesis (2-space indent)
 		if ($in_genesis && $line =~ /^  pipeline:\s*$/) {
 			$in_pipeline = 1;
+			$in_locks    = 0;
 			next;
 		}
 
-		# Another 2-space key under genesis resets pipeline context
-		if ($in_genesis && $line =~ /^  [a-zA-Z]/) {
+		# Other 2-space keys under genesis: capture selected ones, reset pipeline context
+		if ($in_genesis && $line =~ /^  ([a-zA-Z_][a-zA-Z0-9_]*):\s*(.*)$/) {
+			my ($k, $v) = ($1, $2);
 			$in_pipeline = 0;
+			$in_locks    = 0;
+			if ($k eq 'bosh_env') {
+				$v =~ s/\s*#.*$//;
+				$v =~ s/^\s+|\s+$//g;
+				$v =~ s/^(["'])(.*)\1$/$2/;
+				$result{_bosh_env} = $v;
+			}
+			next;
+		}
+
+		# 'locks:' sub-section under genesis.pipeline (4-space, no inline value)
+		if ($in_pipeline && $line =~ /^    locks:\s*$/) {
+			$in_locks = 1;
+			next;
+		}
+
+		# 6-space keys under genesis.pipeline.locks
+		if ($in_locks && $line =~ /^      ([a-zA-Z_][a-zA-Z0-9_]*):\s*(.*)$/) {
+			my ($k, $v) = ($1, $2);
+			$v =~ s/\s*#.*$//;
+			$v =~ s/^\s+|\s+$//g;
+			$v =~ s/^(["'])(.*)\1$/$2/;
+			$result{locks}{$k} = $v;
 			next;
 		}
 
-		# 4-space keys under genesis.pipeline
+		# 4-space keys under genesis.pipeline (non-locks)
 		if ($in_pipeline && $line =~ /^    ([a-zA-Z_][a-zA-Z0-9_]*):\s*(.*)$/) {
 			my ($k, $v) = ($1, $2);
-			$v =~ s/\s*#.*$//;   # strip inline comment
+			$in_locks = 0;
+			$v =~ s/\s*#.*$//;    # strip inline comment
 			$v =~ s/^\s+|\s+$//g; # trim
+			$v =~ s/^(["'])(.*)\1$/$2/; # unquote surrounding quotes
 			$result{$k} = $v;
 		}
 	}
diff --git a/lib/Genesis/CI/Compiler/Parser.pm b/lib/Genesis/CI/Compiler/Parser.pm
index 4d4532d1..5fa75f1c 100644
--- a/lib/Genesis/CI/Compiler/Parser.pm
+++ b/lib/Genesis/CI/Compiler/Parser.pm
@@ -3,6 +3,7 @@ use strict;
 use warnings;
 
 use Genesis;
+use Genesis::Top ();
 use Genesis::CI::Layout;
 use JSON::PP;
 
@@ -27,9 +28,14 @@ sub new {
 sub parse {
 	my ($self) = @_;
 
-	# Determine parsing mode: multi-file (.genesis/ci/) or legacy single file
+	# Determine parsing mode, in priority order:
+	#   1. .genesis/ci/ directory  (multi-file)
+	#   2. .genesis/config ci: key (inline genesis-config)
+	#   3. Legacy ci.yml file      (single-file legacy)
 	if ($self->{ci_dir} && -d $self->{ci_dir}) {
 		return $self->_parse_multi_file($self->{ci_dir});
+	} elsif ($self->{top} && eval { $self->{top}->config->has('ci') }) {
+		return $self->_parse_genesis_config($self->{top}->config->get('ci'));
 	} elsif ($self->{file} && -f $self->{file}) {
 		return $self->_parse_legacy_file($self->{file});
 	} elsif ($self->{ci_dir}) {
@@ -37,7 +43,8 @@ sub parse {
 	} elsif ($self->{file}) {
 		bail("CI configuration file '%s' not found", $self->{file});
 	} else {
-		bail("No CI configuration file or directory specified");
+		bail("No CI configuration found: no .genesis/ci/ directory, no ci: section ".
+			"in .genesis/config, and no ci.yml file");
 	}
 }
 
@@ -99,6 +106,57 @@ sub _parse_multi_file {
 	return \%parsed;
 }
 
+# }}}
+# }}}
+### Genesis Config Parser {{{
+
+# _parse_genesis_config - parse the ci: section from .genesis/config {{{
+#
+# Maps the ci: sub-keys directly to the same normalized structure produced by
+# _parse_multi_file(), so all downstream stages (Validator, ASTBuilder, etc.)
+# are format-agnostic.
+#
+# Expected ci: structure (all optional except targets + integrations):
+#
+#   ci:
+#     targets:         { name: { type, connection, ... } }  # required
+#     integrations:    { vault: {...}, source_control: {...} }  # required
+#     pipeline:        { workflows: {...}, ... }             # optional
+#     scripts:         { script_id: { path, ... } }         # optional
+#     provider_config: { concourse: {...} }                  # optional
+sub _parse_genesis_config {
+	my ($self, $data) = @_;
+
+	my %parsed;
+
+	$parsed{pipeline}        = $data->{pipeline}        || {};
+	$parsed{targets}         = $data->{targets}         || {};
+	$parsed{scripts}         = $data->{scripts}         || {};
+	$parsed{provider}        = $data->{provider}        || {};
+	$parsed{provider_config} = $data->{provider_config} || {};
+
+	# Accept both nested (ci.integrations.*) and flat (ci.vault:, ci.source_control:) formats.
+	# Flat keys win only if the nested key is absent so explicit ci.integrations: always takes precedence.
+	my %integ = %{ $data->{integrations} || {} };
+	$integ{vault}          //= $data->{vault}          if $data->{vault}          && !$integ{vault};
+	$integ{source_control} //= $data->{source_control} if $data->{source_control} && !$integ{source_control};
+	$parsed{integrations} = \%integ;
+
+	# When no pipeline section is provided, workflow topology is derived from
+	# genesis.pipeline.* keys in environment YAML files (same as multi-file
+	# with no pipeline.yml).  Point ASTBuilder at the repo root.
+	unless (%{$parsed{pipeline}}) {
+		$parsed{env_dir} = $self->{top} ? $self->{top}->path() : '.';
+	}
+
+	$parsed{_source_format} = 'genesis-config';
+	$parsed{_source_path}   = $self->{top}
+		? $self->{top}->path('.genesis/config')
+		: '.genesis/config';
+
+	return \%parsed;
+}
+
 # }}}
 # }}}
 ### Legacy Single-File Parser {{{
@@ -126,8 +184,8 @@ sub _parse_legacy_file {
 			version => '1.0',
 		},
 		branches => {
-			live          => $p->{git}{branch} || 'master',
-			target_prefix => 'target/',
+			Genesis::Top::CI_PIPELINE_CONTROL_KEY() => $p->{git}{branch} || 'master',
+			target_prefix                            => 'target/',
 		},
 	};
 
diff --git a/lib/Genesis/CI/Compiler/PipelineDescriptor.pm b/lib/Genesis/CI/Compiler/PipelineDescriptor.pm
index 7a6aa5d9..6db1200d 100644
--- a/lib/Genesis/CI/Compiler/PipelineDescriptor.pm
+++ b/lib/Genesis/CI/Compiler/PipelineDescriptor.pm
@@ -3,6 +3,7 @@ use strict;
 use warnings;
 
 use Genesis;
+use Genesis::Top ();
 use JSON::PP;
 
 ### Constructor {{{
@@ -47,13 +48,34 @@ sub describe {
 	push @resources, $self->_git_resource($ast);
 	push @resources, @{$self->_notification_resources($ast)};
 
+	# Task library resource (optional external git repo for custom tasks)
+	if (my $tlr = $self->_task_library_resource($ast)) {
+		push @resources, $tlr;
+	}
+
 	# Process each workflow
 	for my $wf_name (sort $ast->workflow_names) {
 		my $workflow = $ast->workflows->{$wf_name};
 		my $wf_data  = $self->_extract_workflow_data($ast, $workflow);
 
+		# Error early if bosh-upgrade locks are needed but locker is not configured.
+		my $locker = $ast->integrations->{locker} || {};
+		for my $env (@{$wf_data->{environments}}) {
+			my $parent = $wf_data->{bosh_parent}{$env} || '';
+			next unless $parent && ($wf_data->{bosh_upgrade_lock}{$env} // 1);
+			bail(
+				"Environment '%s' has a pipeline-managed BOSH director ('%s') but no\n".
+				"locker integration is configured.\n".
+				"Add a 'locker:' block to your integrations configuration, or set\n".
+				"  genesis:\n    pipeline:\n      locks:\n        bosh_upgrade: false\n".
+				"in %s.yml to opt out.",
+				$env, $parent, $env
+			) unless $locker->{url};
+		}
+
 		my @wf_job_names;
 		my @notify_job_names;
+		my @redeploy_job_names;
 		for my $env (@{$wf_data->{environments}}) {
 			my $alias         = $wf_data->{aliases}{$env} || $env;
 			my $is_auto       = $wf_data->{auto}{$env};
@@ -65,14 +87,22 @@ sub describe {
 			)};
 
 			# Locker resources
-			my $locker = $ast->integrations->{locker} || {};
 			if ($locker->{url}) {
 				push @resources, @{$self->_locker_resources(
-					$ast, $env, $alias, $deploy_type, $is_create_env
+					$ast, $env, $alias, $deploy_type, $is_create_env, $wf_data
 				)};
 			}
 
-			unless ($is_auto) {
+			# Signal resource
+			my $signal_cfg = $self->_env_signal_config($ast, $env, $wf_data);
+			if ($signal_cfg) {
+				push @resources, $self->_signal_resource(
+					$ast, $env, $alias, $signal_cfg
+				);
+			}
+
+			my $notif_style_env = $self->_effective_notif_style($ast);
+			unless ($is_auto || $notif_style_env eq 'minimal' || $notif_style_env eq 'none') {
 				my $nj = $self->_notify_job(
 					$ast, $env, $alias, $deploy_type, $trigger_from,
 					$is_create_env, $wf_data
@@ -88,17 +118,35 @@ sub describe {
 			);
 			push @jobs, $dj;
 			push @wf_job_names, $dj->{name};
+
+			# Redeploy lane
+			my $redeploy_mode = $wf_data->{redeploy}{$env} || '';
+			if ($redeploy_mode) {
+				if ($redeploy_mode eq 'cron') {
+					my $start = $wf_data->{redeploy_cron_start}{$env} || '04:00';
+					my $stop  = $wf_data->{redeploy_cron_stop}{$env}  || '05:00';
+					push @resources, $self->_redeploy_resource(
+						$ast, $env, $alias, $start, $stop
+					);
+				}
+				my $rj = $self->_redeploy_job(
+					$ast, $env, $alias, $deploy_type, $redeploy_mode,
+					$is_create_env, $wf_data
+				);
+				push @jobs, $rj;
+				push @redeploy_job_names, $rj->{name};
+			}
 		}
 
 		# Auto-update resources and job
 		my $auto_update = $config->{auto_update};
-		if ($auto_update && defined $auto_update->{file}) {
+		if ($auto_update && $auto_update->{enabled}) {
 			push @resources, @{$self->_auto_update_resources($ast)};
 			push @jobs, $self->_auto_update_job($ast);
 		}
 
 		# Groups
-		my $group_notifications = ($config->{notifications}{style} || 'inline') eq 'grouped';
+		my $group_notifications = $self->_effective_notif_style($ast) eq 'grouped';
 		my $custom_groups = $config->{groups};
 
 		if (ref($custom_groups) eq 'HASH') {
@@ -150,12 +198,19 @@ sub describe {
 			}
 		}
 
-		if ($auto_update && defined $auto_update->{file}) {
+		if ($auto_update && $auto_update->{enabled}) {
 			push @groups, {
 				name => 'genesis-updates',
 				jobs => ['update-genesis-assets'],
 			};
 		}
+
+		if (@redeploy_job_names) {
+			push @groups, {
+				name => 'redeploy',
+				jobs => [sort @redeploy_job_names],
+			};
+		}
 	}
 
 	my $pipeline = {
@@ -201,13 +256,17 @@ sub mermaid {
 			? _topological_sort($graph)
 			: sort @{$wf_data->{environments}};
 
-		# Emit edges; node shapes are defined inline on first appearance as target
+		# Emit edges; node shapes are defined inline on first appearance
 		my %shape_defined;
 		for my $env (@order) {
 			next unless $out_edges{$env};
 
 			my $from_alias = $wf_data->{aliases}{$env} || $env;
 			my $from_id    = _mermaid_id($from_alias);
+			my $from_ref   = $shape_defined{$from_id}
+				? $from_id
+				: _mermaid_node_def($from_alias, $nodes->{$env},
+				    $wf_data->{is_bosh_director}{$env});
 			$shape_defined{$from_id} = 1;
 
 			for my $to_env (@{$out_edges{$env}}) {
@@ -215,9 +274,10 @@ sub mermaid {
 				my $to_id    = _mermaid_id($to_alias);
 				my $to_ref   = $shape_defined{$to_id}
 					? $to_id
-					: _mermaid_node_def($to_alias, $nodes->{$to_env});
+					: _mermaid_node_def($to_alias, $nodes->{$to_env},
+					    $wf_data->{is_bosh_director}{$to_env});
 				$shape_defined{$to_id} = 1;
-				push @lines, "  $from_id --> $to_ref";
+				push @lines, "  $from_ref --> $to_ref";
 			}
 		}
 
@@ -225,7 +285,8 @@ sub mermaid {
 		for my $env (@order) {
 			next if $in_any_edge{$env};
 			my $alias = $wf_data->{aliases}{$env} || $env;
-			push @lines, "  " . _mermaid_node_def($alias, $nodes->{$env});
+			push @lines, "  " . _mermaid_node_def($alias, $nodes->{$env},
+				$wf_data->{is_bosh_director}{$env});
 		}
 	}
 
@@ -269,6 +330,8 @@ sub description {
 		push @lines, sprintf("Workflow: %s",
 			$wf_name eq 'default' ? $name : $wf_name);
 
+		my $signal_global = ($ast->configuration || {})->{status_signal};
+
 		for my $env (@order) {
 			my $alias     = $wf_data->{aliases}{$env} || $env;
 			my $is_auto   = $wf_data->{auto}{$env};
@@ -278,8 +341,22 @@ sub description {
 			my $mode   = $is_auto ? 'auto' : 'manual';
 			my $source = $trigger_a ? " (triggered by $trigger_a)" : '';
 
-			push @lines, sprintf("  %-20s %s-$deploy_type  [%s]%s",
-				$alias, $alias, $mode, $source);
+			# Annotations: REDEPLOY, SIGNAL
+			my @annot;
+			my $redeploy_mode = $wf_data->{redeploy}{$env} || '';
+			push @annot, 'REDEPLOY:' . uc($redeploy_mode) if $redeploy_mode;
+			if ($signal_global) {
+				my $ss = $wf_data->{status_signal}{$env} // '';
+				unless ($ss =~ /^(false|no|0)$/i) {
+					my $backend = ($ss =~ /^(file|s3|gcs)$/) ? $ss
+						: ($signal_global->{backend} || 'file');
+					push @annot, "SIGNAL:$backend";
+				}
+			}
+			my $annot_str = @annot ? '  [' . join(', ', @annot) . ']' : '';
+
+			push @lines, sprintf("  %-20s %s-$deploy_type  [%s]%s%s",
+				$alias, $alias, $mode, $source, $annot_str);
 		}
 		push @lines, "";
 	}
@@ -295,7 +372,8 @@ sub description {
 sub _resource_types {
 	my ($self, $ast) = @_;
 
-	my $registry = ($ast->configuration || {})->{registry} || {};
+	my $config   = $ast->configuration || {};
+	my $registry = $config->{registry} || {};
 	my $prefix   = $registry->{uri} ? "$registry->{uri}/" : '';
 
 	my %rs;
@@ -304,17 +382,47 @@ sub _resource_types {
 		$rs{password} = _unwrap_ref($registry->{password});
 	}
 
-	return [map {{
+	my @types = map {{
 		name   => $_->[0],
 		type   => 'registry-image',
 		source => { %rs, repository => "$prefix$_->[1]" },
 	}} (
-		['script',             'cfcommunity/script-resource'],
-		['email',              'pcfseceng/email-resource'],
-		['slack-notification', 'cfcommunity/slack-notification-resource'],
-		['bosh-config',        'cfcommunity/bosh-config-resource'],
-		['locker',             'cfcommunity/locker-resource'],
-	)];
+		['script',      'cfcommunity/script-resource'],
+		['email',       'pcfseceng/email-resource'],
+		['bosh-config', 'cfcommunity/bosh-config-resource'],
+		['locker',      'cfcommunity/locker-resource'],
+	);
+
+	# slack-notification type only when Slack is configured and not suppressed
+	if ($self->_effective_notif_style($ast) ne 'none') {
+		my $has_slack = $ast->integrations->{slack}
+			|| do {
+				my $nn = $ast->integrations->{notifications} || [];
+				scalar grep { ref($_) eq 'HASH' && ($_->{type}||'') eq 'slack' } @$nn;
+			};
+		if ($has_slack) {
+			push @types, {
+				name   => 'slack-notification',
+				type   => 'registry-image',
+				source => { %rs, repository => "${prefix}cfcommunity/slack-notification-resource" },
+			};
+		}
+	}
+
+	# Shuttle resource type for deployment status signals
+	if (my $signal = $config->{status_signal}) {
+		my $img = (ref $signal eq 'HASH' ? $signal->{image}     : undef)
+			|| 'cfcommunity/shuttle-resource';
+		my $tag = (ref $signal eq 'HASH' ? $signal->{image_tag} : undef)
+			|| 'latest';
+		push @types, {
+			name   => 'shuttle',
+			type   => 'registry-image',
+			source => { %rs, repository => "$prefix$img", tag => $tag },
+		};
+	}
+
+	return \@types;
 }
 
 # }}}
@@ -324,7 +432,7 @@ sub _git_resource {
 
 	my $sc     = $ast->integrations->{source_control} || {};
 	my $uri    = $self->_git_uri($sc);
-	my $branch = $sc->{default_branch} || $ast->branches->{live} || 'main';
+	my $branch = $sc->{default_branch} || $ast->branches->{Genesis::Top::CI_PIPELINE_CONTROL_KEY()} || 'main';
 
 	my $source = { uri => $uri, branch => $branch };
 
@@ -341,23 +449,91 @@ sub _git_resource {
 	return { name => 'git', type => 'git', icon => 'github', source => $source };
 }
 
+# }}}
+# _task_library_resource - git resource for the external task library {{{
+#
+# Returns a git resource hashref when configuration.task_library is declared,
+# undef otherwise.  The resource is named by resource_name (default 'tasks').
+sub _task_library_resource {
+	my ($self, $ast) = @_;
+	my $tl = ($ast->configuration || {})->{task_library};
+	return undef unless $tl && ref($tl) eq 'HASH' && $tl->{uri};
+
+	my $name   = $tl->{resource_name} || 'tasks';
+	my $branch = $tl->{branch}        || 'main';
+
+	my %source = ( uri => $tl->{uri}, branch => $branch );
+
+	if (my $auth = $tl->{auth}) {
+		if (($auth->{type} || '') eq 'ssh-key') {
+			$source{private_key} = _unwrap_ref($auth->{private_key});
+		} else {
+			$source{username} = _unwrap_ref($auth->{username}) || 'x-oauth-basic';
+			$source{password} = _unwrap_ref($auth->{password});
+		}
+	}
+
+	return {
+		name   => $name,
+		type   => 'git',
+		icon   => 'source-repository',
+		source => \%source,
+	};
+}
+
+# }}}
+# _task_library_get - get step for the task library resource {{{
+#
+# Returns { get => $name, trigger => false } when the library is configured,
+# undef otherwise.
+sub _task_library_get {
+	my ($self, $ast) = @_;
+	my $tl = ($ast->configuration || {})->{task_library};
+	return undef unless $tl && ref($tl) eq 'HASH' && $tl->{uri};
+	my $name = $tl->{resource_name} || 'tasks';
+	return { get => $name, trigger => JSON::PP::false };
+}
+
+# }}}
+# _task_library_path - resolve a task name to its file path in the library {{{
+#
+# Returns "<resource_name>/<path>/<name>.yml" (with path omitted when empty).
+sub _task_library_path {
+	my ($self, $ast, $task_name) = @_;
+	my $tl = ($ast->configuration || {})->{task_library};
+	return undef unless $tl && ref($tl) eq 'HASH' && $tl->{uri};
+	my $rn   = $tl->{resource_name} || 'tasks';
+	my $path = $tl->{path}          || '';
+	return $path ? "$rn/$path/$task_name.yml" : "$rn/$task_name.yml";
+}
+
 # }}}
 # _notification_resources - build slack/email resources {{{
 sub _notification_resources {
 	my ($self, $ast) = @_;
 
 	my @resources;
-	my $notifications = $ast->integrations->{notifications} || [];
 
-	for my $notif (@$notifications) {
-		if ($notif->{type} eq 'slack') {
+	# Structured Slack config (new format or legacy-normalized)
+	if ($self->_effective_notif_style($ast) ne 'none') {
+		my $slack = $self->_resolve_slack_config($ast, undef);
+		if ($slack) {
 			push @resources, {
 				name   => 'slack',
 				type   => 'slack-notification',
 				icon   => 'slack',
-				source => { url => _unwrap_ref($notif->{webhook}) },
+				source => { url => _unwrap_ref($slack->{webhook}) },
 			};
-		} elsif ($notif->{type} eq 'email') {
+		}
+	}
+
+	# Legacy email / other notification backends
+	my $notifications = $ast->integrations->{notifications} || [];
+	$notifications = [] unless ref($notifications) eq 'ARRAY';
+	for my $notif (@$notifications) {
+		next unless ref($notif) eq 'HASH';
+		next if ($notif->{type} || '') eq 'slack';  # handled via integrations.slack
+		if (($notif->{type} || '') eq 'email') {
 			push @resources, {
 				name   => 'email',
 				type   => 'email',
@@ -370,6 +546,7 @@ sub _notification_resources {
 			};
 		}
 	}
+
 	return \@resources;
 }
 
@@ -381,7 +558,7 @@ sub _env_resources {
 	my @resources;
 	my $sc   = $ast->integrations->{source_control} || {};
 	my $uri  = $self->_git_uri($sc);
-	my $br   = $sc->{default_branch} || $ast->branches->{live} || 'main';
+	my $br   = $sc->{default_branch} || $ast->branches->{Genesis::Top::CI_PIPELINE_CONTROL_KEY()} || 'main';
 	my $root = $sc->{root} || '.';
 	my $pr   = ($root eq '.') ? '' : "$root/";
 
@@ -423,38 +600,42 @@ sub _env_resources {
 		};
 	}
 
-	# BOSH config resources (non-create-env)
+	# BOSH config resources — emitted only when track_bosh_configs is configured
 	unless ($is_create_env) {
-		my $target = $ast->targets->{$env} || {};
-		my $conn   = $target->{connection} || {};
-		my $auth   = $conn->{auth} || {};
-		my $tagged = ($ast->configuration || {})->{tagged};
-		my %to = $tagged ? (tags => [$env]) : ();
-
-		my $ocfp = ($ast->configuration || {})->{ocfp};
-		my $config_name = 'default';
-		if ($ocfp) {
-			$config_name = $wf_data->{genesis_envs}{$env} || $env;
-		}
-
-		my %bs = (
-			target        => $conn->{url},
-			client        => $auth->{client_id},
-			client_secret => _unwrap_ref($auth->{client_secret}),
-			ca_cert       => _unwrap_ref($conn->{ca_cert}),
-		);
-		$bs{name} = $config_name if $ocfp;
+		my $types = $self->_bosh_config_types($ast, $env, $wf_data);
+		if (@$types) {
+			my $target = $ast->targets->{$env} || {};
+			my $conn   = $target->{connection} || {};
+			my $auth   = $conn->{auth} || {};
+			my $tagged = ($ast->configuration || {})->{tagged};
+			my %to = $tagged ? (tags => [$env]) : ();
+
+			my $ocfp = ($ast->configuration || {})->{ocfp};
+			my $config_name = 'default';
+			if ($ocfp) {
+				$config_name = $wf_data->{genesis_envs}{$env} || $env;
+			}
 
-		push @resources, {
-			name => "$alias-cloud-config", type => 'bosh-config',
-			icon => 'script-text', %to,
-			source => { %bs, config => 'cloud', all => JSON::PP::true },
-		};
-		push @resources, {
-			name => "$alias-runtime-config", type => 'bosh-config',
-			icon => 'script-text', %to,
-			source => { %bs, config => 'runtime', all => JSON::PP::true },
-		};
+			my %bs = (
+				target        => $conn->{url},
+				client        => $auth->{client_id},
+				client_secret => _unwrap_ref($auth->{client_secret}),
+				ca_cert       => _unwrap_ref($conn->{ca_cert}),
+			);
+			$bs{name} = $config_name if $ocfp;
+
+			my %_bc_suffix = (cloud => 'cloud-config', runtime => 'runtime-config', cpi => 'cpi-config');
+			my %_bc_icon   = (cloud => 'cloud', runtime => 'run-fast', cpi => 'chip');
+			for my $type (@$types) {
+				push @resources, {
+					name   => "$alias-$_bc_suffix{$type}",
+					type   => 'bosh-config',
+					icon   => $_bc_icon{$type},
+					%to,
+					source => { %bs, config => $type, all => JSON::PP::true },
+				};
+			}
+		}
 	}
 
 	return \@resources;
@@ -462,8 +643,18 @@ sub _env_resources {
 
 # }}}
 # _locker_resources - build locker resources for an environment {{{
+#
+# Three cases:
+#   Director  (is_bosh_director=1):  emits <alias>-bosh-lock as a shared named
+#                                    lock; all children will acquire this resource.
+#   Child     (bosh_parent set, bosh_upgrade_lock=1):  emits only the
+#                                    deployment-lock — bosh-lock is the director's.
+#   Standalone (no pipeline parent): emits per-env bosh-lock pointing to the
+#                                    BOSH director URL (legacy behaviour).
+#
+# All cases emit <alias>-deployment-lock for intra-env deploy serialization.
 sub _locker_resources {
-	my ($self, $ast, $env, $alias, $deploy_type, $is_create_env) = @_;
+	my ($self, $ast, $env, $alias, $deploy_type, $is_create_env, $wf_data) = @_;
 
 	my @resources;
 	my $locker = $ast->integrations->{locker} || {};
@@ -480,17 +671,36 @@ sub _locker_resources {
 		ca_cert             => $locker->{ca_cert},
 	);
 
-	unless ($is_create_env) {
-		my $target = $ast->targets->{$env} || {};
-		my $conn   = $target->{connection} || {};
+	my $bosh_parent    = $wf_data->{bosh_parent}{$env}       || '';
+	my $bu_lock        = $wf_data->{bosh_upgrade_lock}{$env} // 1;
+	my $is_director    = $wf_data->{is_bosh_director}{$env}  || 0;
+
+	if ($is_director) {
+		# Shared bosh-upgrade lock — children acquire this during their deploys.
+		# Use lock_name (named lock) so no BOSH URL is required at pipeline-gen time.
 		push @resources, {
 			name   => "$alias-bosh-lock",
 			type   => 'locker',
 			icon   => 'shield-lock-outline',
 			%to,
-			source => { %locker_source, bosh_lock => $conn->{url} },
+			source => { %locker_source, lock_name => "$alias-bosh-upgrade" },
 		};
+	} elsif (!$bosh_parent || !$bu_lock) {
+		# Standalone or opted-out child: per-env bosh-lock using the BOSH URL.
+		unless ($is_create_env) {
+			my $target = $ast->targets->{$env} || {};
+			my $conn   = $target->{connection} || {};
+			push @resources, {
+				name   => "$alias-bosh-lock",
+				type   => 'locker',
+				icon   => 'shield-lock-outline',
+				%to,
+				source => { %locker_source, bosh_lock => $conn->{url} },
+			};
+		}
 	}
+	# Children with bosh_parent + bosh_upgrade_lock: no own bosh-lock resource —
+	# they acquire the director's <director-alias>-bosh-lock instead.
 
 	push @resources, {
 		name   => "$alias-deployment-lock",
@@ -522,8 +732,10 @@ sub _notify_job {
 		if $passed_job && !$config->{'require-passed-caches'};
 
 	unless ($is_create_env) {
-		push @gets, { get => "$alias-cloud-config",   %to, trigger => JSON::PP::true };
-		push @gets, { get => "$alias-runtime-config", %to, trigger => JSON::PP::true };
+		my %_bc_suffix = (cloud => 'cloud-config', runtime => 'runtime-config', cpi => 'cpi-config');
+		for my $type (@{$self->_bosh_config_types($ast, $env, $wf_data)}) {
+			push @gets, { get => "$alias-$_bc_suffix{$type}", %to, trigger => JSON::PP::true };
+		}
 	}
 
 	my $task_cfg = $self->_task_config($ast, $env, $alias, $trigger_from, $wf_data,
@@ -531,7 +743,8 @@ sub _notify_job {
 
 	my $pipeline_name = $ast->metadata->{name} || 'genesis-pipeline';
 	my $notif = $self->_notification_step($ast,
-		"$pipeline_name: Changes staged for $env-$deploy_type");
+		"$pipeline_name: Changes staged for $env-$deploy_type",
+		{ env => $env });
 
 	my @plan = (
 		{ in_parallel => \@gets },
@@ -562,8 +775,8 @@ sub _deploy_job {
 	my $trigger    = $is_auto ? JSON::PP::true : JSON::PP::false;
 	my $passed     = $trigger_from ? $wf_data->{aliases}{$trigger_from} : '';
 	my $passed_job = $passed ? "$passed-$deploy_type" : '';
-	my $pass_cache = $config->{'require-passed-caches'};
-	my $inline     = ($config->{notifications}{style} || 'inline') eq 'inline';
+	my $pass_cache  = $config->{'require-passed-caches'};
+	my $inline      = $self->_effective_notif_style($ast) eq 'per-env';
 
 	my $srcdir = $pass_cache
 		? ($trigger_from ? "$alias-cache" : "$alias-changes")
@@ -574,8 +787,10 @@ sub _deploy_job {
 	# Resource gets
 	my @gets;
 	if (!$is_create_env && $is_auto) {
-		push @gets, { get => "$alias-cloud-config",   %to, trigger => JSON::PP::true };
-		push @gets, { get => "$alias-runtime-config", %to, trigger => JSON::PP::true };
+		my %_bc_suffix = (cloud => 'cloud-config', runtime => 'runtime-config', cpi => 'cpi-config');
+		for my $type (@{$self->_bosh_config_types($ast, $env, $wf_data)}) {
+			push @gets, { get => "$alias-$_bc_suffix{$type}", %to, trigger => JSON::PP::true };
+		}
 	}
 	if ($is_auto || !$inline) {
 		push @gets, { get => "$alias-changes", trigger => $trigger };
@@ -596,6 +811,11 @@ sub _deploy_job {
 			if $gp;
 	}
 
+	# Task library (optional external git resource with custom task files)
+	if (my $tl_get = $self->_task_library_get($ast)) {
+		push @gets, $tl_get;
+	}
+
 	# Deploy task
 	my $deploy_task = {
 		task => 'bosh-deploy', %to,
@@ -619,22 +839,36 @@ sub _deploy_job {
 	my @unlock_steps;
 	my $locker = $ast->integrations->{locker} || {};
 	if ($locker->{url}) {
-		unless ($is_create_env) {
+		my $bosh_parent = $wf_data->{bosh_parent}{$env}       || '';
+		my $bu_lock     = $wf_data->{bosh_upgrade_lock}{$env} // 1;
+		my $is_director = $wf_data->{is_bosh_director}{$env}  || 0;
+
+		my $bosh_lock_alias;
+		if ($bosh_parent && $bu_lock) {
+			# Child: acquire director's shared bosh-lock
+			$bosh_lock_alias = $wf_data->{aliases}{$bosh_parent} || $bosh_parent;
+		} elsif ($is_director || !$is_create_env) {
+			# Director or standalone non-create-env: acquire own bosh-lock
+			$bosh_lock_alias = $alias;
+		}
+
+		if ($bosh_lock_alias) {
 			push @lock_steps, {
-				put => "$alias-bosh-lock", %to,
+				put => "$bosh_lock_alias-bosh-lock", %to,
 				params => {
 					lock_op => 'lock', key => 'dont-upgrade-bosh-on-me',
 					locked_by => "$env-$deploy_type",
 				},
 			};
 			push @unlock_steps, {
-				put => "$alias-bosh-lock", %to,
+				put => "$bosh_lock_alias-bosh-lock", %to,
 				params => {
 					lock_op => 'unlock', key => 'dont-upgrade-bosh-on-me',
 					locked_by => "$env-$deploy_type",
 				},
 			};
 		}
+
 		push @lock_steps, {
 			put => "$alias-deployment-lock", %to,
 			params => {
@@ -659,10 +893,11 @@ sub _deploy_job {
 
 	unless ($is_create_env) {
 		for my $errand (@{$config->{errands} || []}) {
-			push @do, {
-				task => "$errand-errand", %to,
-				config => $self->_errand_config($ast, $env, $errand, $bindir, $srcdir),
-			};
+			my $tl_file = $self->_task_library_path($ast, $errand);
+			push @do, $tl_file
+				? { task => "$errand-errand", %to, file => $tl_file }
+				: { task => "$errand-errand", %to,
+				    config => $self->_errand_config($ast, $env, $errand, $bindir, $srcdir) };
 		}
 	}
 
@@ -679,14 +914,9 @@ sub _deploy_job {
 		}
 	}
 
-	my $fail = $self->_notification_step($ast,
-		"$name: Deployment to $env-$deploy_type failed");
-	my $succ = $self->_notification_step($ast,
-		"$name: Successfully deployed $env-$deploy_type");
-
+	my %hooks = $self->_outcome_hooks($ast, $env, $alias, $deploy_type, $wf_data, 0);
 	my $plan_step = {};
-	$plan_step->{on_failure} = $fail if $fail;
-	$plan_step->{on_success} = $succ if $succ;
+	$plan_step->{$_} = $hooks{$_} for sort keys %hooks;
 	$plan_step->{ensure} = { do => \@unlock_steps } if @unlock_steps;
 	$plan_step->{do} = \@do;
 
@@ -699,57 +929,378 @@ sub _deploy_job {
 }
 
 # }}}
-# _auto_update_resources - build kit-release and genesis-release resources {{{
+# _redeploy_resource - Concourse time resource for cron-mode redeploy {{{
+sub _redeploy_resource {
+	my ($self, $ast, $env, $alias, $start, $stop) = @_;
+
+	my $config = $ast->configuration || {};
+	my $tagged = $config->{tagged};
+	my %to = $tagged ? (tags => [$env]) : ();
+
+	return {
+		name   => "$alias-redeploy-cron",
+		type   => 'time',
+		icon   => 'clock-outline',
+		%to,
+		source => {
+			start    => $start,
+			stop     => $stop,
+			location => 'UTC',
+		},
+	};
+}
+
+# }}}
+# _redeploy_job - redeploy job for an environment {{{
+#
+# Redeploys an environment without change detection or cache generation.
+# Trigger modes: manual (no auto-trigger), cron (time resource), signal (like manual).
+sub _redeploy_job {
+	my ($self, $ast, $env, $alias, $deploy_type, $trigger_mode,
+		$is_create_env, $wf_data) = @_;
+
+	my $config = $ast->configuration || {};
+	my $sc     = $ast->integrations->{source_control} || {};
+	my $root   = $sc->{root} || '.';
+	my $tagged = $config->{tagged};
+	my %to     = $tagged ? (tags => [$env]) : ();
+	my $name   = $ast->metadata->{name} || 'genesis-pipeline';
+
+	my $bindir = 'git';
+	my $srcdir = "$alias-changes";
+	$bindir .= "/$root" if $root ne '.';
+
+	# Resource gets — no change-detection triggers
+	my $signal_cfg = $self->_env_signal_config($ast, $env, $wf_data);
+	my @gets;
+	if ($trigger_mode eq 'cron') {
+		push @gets, {
+			get     => "$alias-redeploy-cron",
+			trigger => JSON::PP::true,
+		};
+	} elsif ($trigger_mode eq 'signal' && $signal_cfg) {
+		push @gets, {
+			get     => "$alias-signal",
+			trigger => JSON::PP::true,
+			version => { status => 'success' },
+		};
+	}
+	push @gets, { get => "$alias-changes", trigger => JSON::PP::false };
+	push @gets, { get => 'git', trigger => JSON::PP::false }
+		unless $config->{'require-passed-caches'};
+	unless ($is_create_env) {
+		my %_bc_suffix = (cloud => 'cloud-config', runtime => 'runtime-config', cpi => 'cpi-config');
+		for my $type (@{$self->_bosh_config_types($ast, $env, $wf_data)}) {
+			push @gets, { get => "$alias-$_bc_suffix{$type}", %to, trigger => JSON::PP::false };
+		}
+	}
+
+	# Task library
+	if (my $tl_get = $self->_task_library_get($ast)) {
+		push @gets, $tl_get;
+	}
+
+	# Deploy task — reuses ci-pipeline-deploy with no prior_env
+	my $deploy_task = {
+		task => 'bosh-redeploy', %to,
+		config => $self->_task_config($ast, $env, $alias, undef, $wf_data,
+			{ command        => 'ci-pipeline-deploy',
+			  genesis_bindir => $bindir,
+			  genesis_srcdir => $srcdir }),
+		ensure => { put => 'git', params => { repository => 'out/git' } },
+	};
+	my @priv = @{$config->{task}{privileged} || []};
+	$deploy_task->{privileged} = JSON::PP::true if grep { $_ eq $alias } @priv;
+
+	# Locker steps — mirrors _deploy_job lock topology
+	my @lock_steps;
+	my @unlock_steps;
+	my $locker = $ast->integrations->{locker} || {};
+	if ($locker->{url}) {
+		my $bosh_parent = $wf_data->{bosh_parent}{$env}       || '';
+		my $bu_lock     = $wf_data->{bosh_upgrade_lock}{$env} // 1;
+		my $is_director = $wf_data->{is_bosh_director}{$env}  || 0;
+
+		my $bosh_lock_alias;
+		if ($bosh_parent && $bu_lock) {
+			$bosh_lock_alias = $wf_data->{aliases}{$bosh_parent} || $bosh_parent;
+		} elsif ($is_director || !$is_create_env) {
+			$bosh_lock_alias = $alias;
+		}
+
+		if ($bosh_lock_alias) {
+			push @lock_steps, {
+				put => "$bosh_lock_alias-bosh-lock", %to,
+				params => {
+					lock_op => 'lock', key => 'dont-upgrade-bosh-on-me',
+					locked_by => "$env-redeploy",
+				},
+			};
+			push @unlock_steps, {
+				put => "$bosh_lock_alias-bosh-lock", %to,
+				params => {
+					lock_op => 'unlock', key => 'dont-upgrade-bosh-on-me',
+					locked_by => "$env-redeploy",
+				},
+			};
+		}
+
+		push @lock_steps, {
+			put => "$alias-deployment-lock", %to,
+			params => {
+				lock_op => 'lock', key => 'i-need-to-deploy-myself',
+				locked_by => "$env-redeploy",
+			},
+		};
+		push @unlock_steps, {
+			put => "$alias-deployment-lock", %to,
+			params => {
+				lock_op => 'unlock', key => 'i-need-to-deploy-myself',
+				locked_by => "$env-redeploy",
+			},
+		};
+	}
+
+	my @do;
+	push @do, @lock_steps;
+	push @do, { in_parallel => \@gets };
+	push @do, $deploy_task;
+
+	my %hooks = $self->_outcome_hooks($ast, $env, $alias, $deploy_type, $wf_data, 1);
+	my $plan_step = {};
+	$plan_step->{$_} = $hooks{$_} for sort keys %hooks;
+	$plan_step->{ensure} = { do => \@unlock_steps } if @unlock_steps;
+	$plan_step->{do} = \@do;
+
+	return {
+		name   => "redeploy-$alias",
+		public => JSON::PP::true,
+		serial => JSON::PP::true,
+		plan   => [$plan_step],
+	};
+}
+
+# }}}
+# _env_signal_config - resolve effective signal config for an env {{{
+#
+# Returns a hashref with the merged global+per-env signal config, or undef
+# if signals are not configured or explicitly disabled for this env.
+sub _env_signal_config {
+	my ($self, $ast, $env, $wf_data) = @_;
+
+	my $global = ($ast->configuration || {})->{status_signal};
+	return undef unless $global && ref($global) eq 'HASH';
+
+	my $env_setting = $wf_data->{status_signal}{$env} // '';
+
+	# Explicitly disabled for this env
+	return undef if $env_setting =~ /^(false|no|0)$/i;
+
+	# Effective backend: per-env backend override or global
+	my $backend = $global->{backend} || 'file';
+	$backend = $env_setting if $env_setting =~ /^(file|s3|gcs)$/;
+
+	# Effective prefix: per-env override, or global-base/env, or just env name
+	my $env_prefix    = $wf_data->{signal_prefix}{$env} || '';
+	my $global_prefix = $global->{prefix} || '';
+	my $prefix = $env_prefix
+		|| ($global_prefix ? "$global_prefix/$env" : $env);
+
+	return { %$global, backend => $backend, prefix => $prefix };
+}
+
+# }}}
+# _signal_resource - build per-env signal (shuttle) resource {{{
+sub _signal_resource {
+	my ($self, $ast, $env, $alias, $signal_cfg) = @_;
+
+	my $config  = $ast->configuration || {};
+	my $tagged  = $config->{tagged};
+	my %to      = $tagged ? (tags => [$env]) : ();
+	my $backend = $signal_cfg->{backend} || 'file';
+	my $prefix  = $signal_cfg->{prefix}  || $env;
+
+	my %source = (backend => $backend, prefix => $prefix);
+
+	if ($backend eq 's3') {
+		$source{bucket}            = $signal_cfg->{bucket} || 'genesis-signals';
+		$source{region}            = $signal_cfg->{region} || 'us-east-1';
+		$source{access_key_id}     = _unwrap_ref($signal_cfg->{access_key_id});
+		$source{secret_access_key} = _unwrap_ref($signal_cfg->{secret_access_key});
+		$source{endpoint}          = $signal_cfg->{endpoint}
+			if $signal_cfg->{endpoint};
+	} elsif ($backend eq 'gcs') {
+		$source{bucket}   = $signal_cfg->{bucket} || 'genesis-signals';
+		$source{json_key} = _unwrap_ref($signal_cfg->{json_key});
+	} elsif ($backend eq 'file') {
+		my $base = $signal_cfg->{path} || '/tmp/genesis-signals';
+		$source{path} = "$base/$prefix";
+	}
+
+	return {
+		name   => "$alias-signal",
+		type   => 'shuttle',
+		icon   => 'broadcast',
+		%to,
+		source => \%source,
+	};
+}
+
+# }}}
+# _signal_put_step - build a put step to emit a deployment status signal {{{
+sub _signal_put_step {
+	my ($self, $alias, $status, $env, $deploy_type) = @_;
+	return {
+		put    => "$alias-signal",
+		params => {
+			status     => $status,
+			deployment => "$env-$deploy_type",
+		},
+	};
+}
+
+# }}}
+# _outcome_hooks - build on_success/on_failure/on_abort/on_error plan hooks {{{
+#
+# Combines notification steps (success/failure) with signal put steps (all four
+# outcomes).  Returns a hash with only the keys that have actual content.
+sub _outcome_hooks {
+	my ($self, $ast, $env, $alias, $deploy_type, $wf_data, $is_redeploy) = @_;
+
+	my $name      = $ast->metadata->{name} || 'genesis-pipeline';
+	my $action    = $is_redeploy ? 'Redeploy of'    : 'Deployment to';
+	my $ok_action = $is_redeploy ? 'redeployed'     : 'deployed';
+	my $ok_msg    = "$name: Successfully ${ok_action} $env-$deploy_type";
+	my $fail_msg  = "$name: $action $env-$deploy_type failed";
+
+	my $signal_cfg  = $self->_env_signal_config($ast, $env, $wf_data);
+	my $notif_style = $self->_effective_notif_style($ast);
+
+	my %hooks;
+	for my $outcome (qw(success failure abort error)) {
+		my @steps;
+
+		# Notifications: suppressed entirely for 'none'; success suppressed for 'minimal'
+		if ($outcome eq 'success'
+			&& $notif_style ne 'minimal' && $notif_style ne 'none') {
+			my $notif = $self->_notification_step($ast, $ok_msg, { env => $env });
+			push @steps, @{$notif->{in_parallel}} if $notif;
+		} elsif ($outcome eq 'failure' && $notif_style ne 'none') {
+			my $notif = $self->_notification_step($ast, $fail_msg,
+				{ env => $env, is_failure => 1 });
+			push @steps, @{$notif->{in_parallel}} if $notif;
+		}
+
+		# Signal: all four outcomes
+		if ($signal_cfg) {
+			push @steps, $self->_signal_put_step($alias, $outcome, $env, $deploy_type);
+		}
+
+		next unless @steps;
+		$hooks{"on_$outcome"} = @steps == 1 ? $steps[0] : { in_parallel => \@steps };
+	}
+
+	return %hooks;
+}
+
+# }}}
+# _auto_update_resources - build kit-release, genesis-release, and optional
+# git-autoupdate resources based on the active auto_update flags {{{
 sub _auto_update_resources {
 	my ($self, $ast) = @_;
 
 	my $config      = $ast->configuration || {};
 	my $auto_update = $config->{auto_update} || {};
+	my $sc          = $ast->integrations->{source_control} || {};
+	my $period      = $auto_update->{period} || '24h';
+	my $api_url     = $auto_update->{api_url};
+	my $auth_token  = _unwrap_ref($auto_update->{auth_token} || '');
 
 	my @resources;
-	push @resources, {
-		name        => 'kit-release',
-		icon        => 'package-variant',
-		type        => 'github-release',
-		check_every => $auto_update->{period} || '24h',
-		source      => {
-			user         => $auto_update->{org},
-			repository   => "$auto_update->{kit}-genesis-kit",
-			access_token => _unwrap_ref($auto_update->{kit_auth_token}
-				|| $auto_update->{auth_token} || ''),
-			($auto_update->{api_url}
-				? (github_api_url => $auto_update->{api_url}) : ()),
-		},
-	};
 
-	push @resources, {
-		name        => 'genesis-release',
-		type        => 'github-release',
-		icon        => 'leaf',
-		check_every => $auto_update->{period} || '24h',
-		source      => {
-			user         => 'genesis-community',
-			repository   => 'genesis',
-			access_token => _unwrap_ref($auto_update->{genesis_auth_token}
-				|| $auto_update->{auth_token} || ''),
-		},
-	};
+	# kit-release: GitHub release feed for the configured kit
+	if ($auto_update->{update_kit} // 1) {
+		push @resources, {
+			name        => 'kit-release',
+			icon        => 'package-variant',
+			type        => 'github-release',
+			check_every => $period,
+			source      => {
+				user         => $auto_update->{org},
+				repository   => "$auto_update->{kit}-genesis-kit",
+				access_token => _unwrap_ref($auto_update->{kit_auth_token} || $auth_token),
+				($api_url ? (github_api_url => $api_url) : ()),
+			},
+		};
+	}
+
+	# genesis-release: GitHub release feed for the genesis binary
+	if ($auto_update->{update_genesis} // 1) {
+		push @resources, {
+			name        => 'genesis-release',
+			type        => 'github-release',
+			icon        => 'leaf',
+			check_every => $period,
+			source      => {
+				user         => 'genesis-community',
+				repository   => 'genesis',
+				access_token => _unwrap_ref($auto_update->{genesis_auth_token} || $auth_token),
+			},
+		};
+	}
+
+	# git-autoupdate: separate push resource when target_branch differs from
+	# the pipeline control branch (e.g., operator wants commits on a dedicated branch)
+	my $control_branch = $sc->{default_branch}
+		|| $ast->branches->{Genesis::Top::CI_PIPELINE_CONTROL_KEY()}
+		|| 'main';
+	my $target_branch = $auto_update->{target_branch} || '';
+	if ($target_branch && $target_branch ne $control_branch) {
+		my $uri = $self->_git_uri($sc);
+		my %source = (uri => $uri, branch => $target_branch);
+		if ($sc->{auth}) {
+			if (($sc->{auth}{type} || '') eq 'ssh-key') {
+				$source{private_key} = _unwrap_ref($sc->{auth}{private_key});
+			} else {
+				$source{username} = _unwrap_ref($sc->{auth}{username});
+				$source{password} = _unwrap_ref($sc->{auth}{password});
+			}
+		}
+		push @resources, {
+			name   => 'git-autoupdate',
+			type   => 'git',
+			icon   => 'source-branch',
+			source => \%source,
+		};
+	}
 
 	return \@resources;
 }
 
 # }}}
 # _auto_update_job - build update-genesis-assets job {{{
+#
+# Emits three optional task steps, each guarded by a flag:
+#   list-kits      — pre-flight kit availability check  (update_kit: true)
+#   update-genesis — embed newer genesis binary          (update_genesis: true)
+#   fetch-kit      — sed kit version + commit           (update_kit: true)
+#
+# The push target defaults to the pipeline control branch via 'git'.  When
+# target_branch is set to a different branch, a dedicated 'git-autoupdate'
+# resource (emitted by _auto_update_resources) is used for the put step.
 sub _auto_update_job {
 	my ($self, $ast) = @_;
 
-	my $config      = $ast->configuration || {};
-	my $sc          = $ast->integrations->{source_control} || {};
-	my $root        = $sc->{root} || '.';
-	my $auto_update = $config->{auto_update} || {};
-	my $task_cfg    = $config->{task} || {};
-	my $reg         = $config->{registry} || {};
-	my $pfx         = $reg->{uri} ? "$reg->{uri}/" : '';
+	my $config         = $ast->configuration || {};
+	my $sc             = $ast->integrations->{source_control} || {};
+	my $root           = $sc->{root} || '.';
+	my $auto_update    = $config->{auto_update} || {};
+	my $update_kit     = $auto_update->{update_kit}     // 1;
+	my $update_genesis = $auto_update->{update_genesis} // 1;
+
+	my $task_cfg = $config->{task} || {};
+	my $reg      = $config->{registry} || {};
+	my $pfx      = $reg->{uri} ? "$reg->{uri}/" : '';
 
 	my $img_src = {
 		repository => "$pfx" . ($task_cfg->{image} || 'genesiscommunity/concourse'),
@@ -760,24 +1311,49 @@ sub _auto_update_job {
 		$img_src->{password} = _unwrap_ref($reg->{password});
 	}
 
-	my $git_genesis_dir = 'git';
+	# Path helpers for repos rooted in a subdirectory
+	my $git_genesis_dir     = 'git';
 	my $genesis_config_path = '';
-	my $path_prefix = '';
-	my $subdir_msg = '';
+	my $path_prefix         = '';
+	my $subdir_msg          = '';
 	if ($root ne '.') {
-		$git_genesis_dir .= "/$root";
-		$genesis_config_path = " -C '$root'";
-		$path_prefix = "$root/";
-		$subdir_msg = " under $root";
+		$git_genesis_dir     .= "/$root";
+		$genesis_config_path  = " -C '$root'";
+		$path_prefix          = "$root/";
+		$subdir_msg           = " under $root";
 	}
+	my $pushd_cmd = ($root eq '.') ? '' : "pushd '$root' &> /dev/null\n";
+	my $popd_cmd  = ($root eq '.') ? '' : "popd &> /dev/null\n";
 
-	my $user_name = ($sc->{commit_author} ? $sc->{commit_author}{name}  : undef)
+	my $user_name  = ($sc->{commit_author} ? $sc->{commit_author}{name}  : undef)
 		|| 'Concourse Bot';
 	my $user_email = ($sc->{commit_author} ? $sc->{commit_author}{email} : undef)
 		|| 'concourse@pipeline';
-	my $ci_label  = $auto_update->{label} || 'concourse';
-	my $kit_name  = $auto_update->{kit};
+	my $ci_label   = $auto_update->{label} || $auto_update->{commit_label} || 'concourse';
+	my $kit_name   = $auto_update->{kit}   || '';
+
+	# Determine which git resource receives the auto-commit push
+	my $control_branch = $sc->{default_branch}
+		|| $ast->branches->{Genesis::Top::CI_PIPELINE_CONTROL_KEY()}
+		|| 'main';
+	my $target_branch = $auto_update->{target_branch} || '';
+	my $push_resource = ($target_branch && $target_branch ne $control_branch)
+		? 'git-autoupdate'
+		: 'git';
 
+	# -----------------------------------------------------------------------
+	# in_parallel gets — only include resources that are enabled
+	# kit-release and genesis-release both trigger when their flag is set.
+	# -----------------------------------------------------------------------
+	my @parallel_gets = ({ get => 'git' });
+	push @parallel_gets, { get => 'kit-release',     trigger => JSON::PP::true }
+		if $update_kit;
+	push @parallel_gets, { get => 'genesis-release', trigger => JSON::PP::true }
+		if $update_genesis;
+
+	# -----------------------------------------------------------------------
+	# list-kits — pre-flight: confirm kit version exists in remote registry
+	# -----------------------------------------------------------------------
 	my $list_kits_task = {
 		task   => 'list-kits',
 		config => {
@@ -793,8 +1369,9 @@ sub _auto_update_job {
 		},
 	};
 
-	my $pushd_cmd = ($root eq '.') ? '' : "pushd '$root' &> /dev/null\n";
-	my $popd_cmd  = ($root eq '.') ? '' : "popd &> /dev/null\n";
+	# -----------------------------------------------------------------------
+	# update-genesis — embed newer genesis binary if upstream > embedded
+	# -----------------------------------------------------------------------
 	my $update_genesis_script = <<"SCRIPT";
 chmod +x ../genesis-release/genesis
 upstream="\$(../genesis-release/genesis -v 2>/dev/null | sed -e 's/Genesis v\\([^ ]*\\) .*/\\1/')"
@@ -835,6 +1412,10 @@ SCRIPT
 		},
 	};
 
+	# -----------------------------------------------------------------------
+	# fetch-kit — fetch kit version from GitHub release, sed version file,
+	# commit if changed
+	# -----------------------------------------------------------------------
 	my $fetch_kit_script = <<"SCRIPT";
 version="\$(cat ../kit-release/version)"
 ${pushd_cmd}if ! .genesis/bin/genesis --no-color list-kits \${GENESIS_KIT_NAME} | grep "v\$version\\\$"; then
@@ -871,21 +1452,23 @@ SCRIPT
 		},
 	};
 
+	# -----------------------------------------------------------------------
+	# Assemble plan — only include steps for enabled features
+	# -----------------------------------------------------------------------
+	my @plan = ({ in_parallel => \@parallel_gets });
+	push @plan, $list_kits_task      if $update_kit;
+	push @plan, $update_genesis_task if $update_genesis;
+	push @plan, $fetch_kit_task      if $update_kit;
+	push @plan, {
+		put    => $push_resource,
+		params => { repository => $push_resource, rebase => JSON::PP::true },
+	};
+
 	return {
-		name => 'update-genesis-assets',
-		plan => [
-			{
-				in_parallel => [
-					{ get => 'git' },
-					{ get => 'kit-release', trigger => JSON::PP::true },
-					{ get => 'genesis-release' },
-				],
-			},
-			$list_kits_task,
-			$update_genesis_task,
-			$fetch_kit_task,
-			{ put => 'git', params => { repository => 'git', rebase => JSON::PP::true } },
-		],
+		name   => 'update-genesis-assets',
+		public => JSON::PP::true,
+		serial => JSON::PP::true,
+		plan   => \@plan,
 	};
 }
 
@@ -927,7 +1510,7 @@ sub _task_config {
 		CACHE_DIR            => "$alias-cache",
 		OUT_DIR              => 'out/git',
 		WORKING_DIR          => "$alias-changes",
-		GIT_BRANCH           => $sc->{default_branch} || $ast->branches->{live} || 'main',
+		GIT_BRANCH           => $sc->{default_branch} || $ast->branches->{Genesis::Top::CI_PIPELINE_CONTROL_KEY()} || 'main',
 		GIT_AUTHOR_NAME      => ($sc->{commit_author} ? $sc->{commit_author}{name}  : undef)
 			|| 'Concourse Bot',
 		GIT_AUTHOR_EMAIL     => ($sc->{commit_author} ? $sc->{commit_author}{email} : undef)
@@ -961,6 +1544,16 @@ sub _task_config {
 	push @inputs, { name => "$alias-cache" } if $passed;
 	push @inputs, { name => 'git' } unless $config->{'require-passed-caches'};
 
+	# Task library input — expose library files to the running task
+	if (my $tl = $config->{task_library}) {
+		if (ref($tl) eq 'HASH' && $tl->{uri}) {
+			my $rn   = $tl->{resource_name} || 'tasks';
+			my $path = $tl->{path}          || '';
+			push @inputs, { name => $rn };
+			$params{GENESIS_TASK_LIBRARY_PATH} = $path ? "$rn/$path" : $rn;
+		}
+	}
+
 	return {
 		platform       => 'linux',
 		image_resource => { type => 'registry-image', source => $img_src },
@@ -1001,7 +1594,7 @@ sub _cache_task_config {
 		CURRENT_ENV       => $env,
 		WORKING_DIR       => 'out/git',
 		OUT_DIR           => 'cache-out/git',
-		GIT_BRANCH        => $sc->{default_branch} || $ast->branches->{live} || 'main',
+		GIT_BRANCH        => $sc->{default_branch} || $ast->branches->{Genesis::Top::CI_PIPELINE_CONTROL_KEY()} || 'main',
 		GIT_AUTHOR_NAME   => ($sc->{commit_author} ? $sc->{commit_author}{name}  : undef)
 			|| 'Concourse Bot',
 		GIT_AUTHOR_EMAIL  => ($sc->{commit_author} ? $sc->{commit_author}{email} : undef)
@@ -1078,6 +1671,18 @@ sub _errand_config {
 
 	my $subdir = ($root eq '.') ? '' : "/$root";
 
+	my @inputs = ({ name => 'out' }, { name => $srcdir });
+
+	# Task library input for errands
+	if (my $tl = $config->{task_library}) {
+		if (ref($tl) eq 'HASH' && $tl->{uri}) {
+			my $rn   = $tl->{resource_name} || 'tasks';
+			my $path = $tl->{path}          || '';
+			push @inputs, { name => $rn };
+			$params{GENESIS_TASK_LIBRARY_PATH} = $path ? "$rn/$path" : $rn;
+		}
+	}
+
 	return {
 		platform       => 'linux',
 		image_resource => { type => 'registry-image', source => $img_src },
@@ -1087,35 +1692,104 @@ sub _errand_config {
 			dir  => "out/git$subdir",
 			args => ['ci-pipeline-run-errand'],
 		},
-		inputs => [{ name => 'out' }, { name => $srcdir }],
+		inputs => \@inputs,
 	};
 }
 
+# }}}
+# _effective_notif_style - resolve the active notification style {{{
+#
+# Returns: 'per-env' | 'grouped' | 'minimal' | 'none'
+# Sources: integrations.slack.style (new format), or legacy
+# configuration.notifications.style mapped to per-env/grouped.
+sub _effective_notif_style {
+	my ($self, $ast) = @_;
+
+	my $slack = $ast->integrations->{slack};
+	return $slack->{style} || 'per-env' if $slack;
+
+	# Legacy fallback: check notifications array + configuration style flag
+	my $notifs = $ast->integrations->{notifications} || [];
+	$notifs = [] unless ref($notifs) eq 'ARRAY';
+	my ($sn) = grep { ref($_) eq 'HASH' && ($_->{type} || '') eq 'slack' } @$notifs;
+	if ($sn) {
+		my $old = ($ast->configuration || {})->{notifications}{style} || 'inline';
+		return $old eq 'grouped' ? 'grouped' : 'per-env';
+	}
+
+	return 'none';
+}
+
+# }}}
+# _resolve_slack_config - return effective Slack config for an env {{{
+#
+# Returns a merged hashref (global + per-env override) or undef when Slack
+# is not configured or style is 'none'.
+sub _resolve_slack_config {
+	my ($self, $ast, $env) = @_;
+
+	my $slack = $ast->integrations->{slack};
+
+	# Legacy fallback: build from old notifications array
+	unless ($slack) {
+		my $notifs = $ast->integrations->{notifications} || [];
+		$notifs = [] unless ref($notifs) eq 'ARRAY';
+		my ($sn) = grep { ref($_) eq 'HASH' && ($_->{type} || '') eq 'slack' } @$notifs;
+		return undef unless $sn;
+		my $old = ($ast->configuration || {})->{notifications}{style} || 'inline';
+		$slack = {
+			webhook             => $sn->{webhook},
+			channel             => $sn->{channel},
+			username            => $sn->{username},
+			icon_url            => $sn->{icon},
+			style               => $old eq 'grouped' ? 'grouped' : 'per-env',
+			mentions_on_failure => [],
+			per_env_overrides   => {},
+		};
+	}
+
+	return undef if ($slack->{style} || 'per-env') eq 'none';
+
+	# Merge per-env override
+	my %cfg = %$slack;
+	if ($env) {
+		my $override = ($slack->{per_env_overrides} || {})->{$env} || {};
+		$cfg{$_} = $override->{$_} for keys %$override;
+	}
+
+	return \%cfg;
+}
+
 # }}}
 # _notification_step - build notification plan step {{{
+#
+# opts: { env => '', is_failure => 0 }
+# Returns { in_parallel => [...] } or undef.
 sub _notification_step {
-	my ($self, $ast, $message) = @_;
+	my ($self, $ast, $message, $opts) = @_;
+	$opts ||= {};
+	my $env        = $opts->{env}        // '';
+	my $is_failure = $opts->{is_failure} // 0;
 
-	my $notifications = $ast->integrations->{notifications};
-	return undef unless $notifications && ref($notifications) eq 'ARRAY'
-		&& @$notifications;
+	my $slack = $self->_resolve_slack_config($ast, $env);
+	return undef unless $slack;
 
-	my @steps;
-	for my $notif (@$notifications) {
-		if ($notif->{type} eq 'slack') {
-			push @steps, {
-				put    => 'slack',
-				params => {
-					channel  => $notif->{channel},
-					username => $notif->{username} || 'runwaybot',
-					icon_url => $notif->{icon},
-					text     => $message,
-				},
-			};
-		}
+	my $text = $message;
+	if ($is_failure && @{$slack->{mentions_on_failure} || []}) {
+		$text = join(' ', @{$slack->{mentions_on_failure}}) . ': ' . $text;
 	}
 
-	return @steps ? { in_parallel => \@steps } : undef;
+	my @steps = ({
+		put    => 'slack',
+		params => {
+			channel  => $slack->{channel},
+			username => $slack->{username} || 'runwaybot',
+			icon_url => $slack->{icon_url} || $slack->{icon},
+			text     => $text,
+		},
+	});
+
+	return { in_parallel => \@steps };
 }
 
 # }}}
@@ -1130,7 +1804,11 @@ sub _extract_workflow_data {
 	my $nodes = $graph->{nodes} || {};
 	my $edges = $graph->{edges} || [];
 
-	my (%will_trigger, %triggers, %auto, %aliases, %genesis_envs);
+	my (%will_trigger, %triggers, %auto, %aliases, %genesis_envs,
+	    %redeploy, %redeploy_cron_start, %redeploy_cron_stop,
+	    %status_signal, %signal_prefix,
+	    %bosh_parent, %bosh_upgrade_lock, %is_bosh_director,
+	    %track_bosh_configs);
 
 	for my $edge (@$edges) {
 		push @{$will_trigger{$edge->{from}}}, $edge->{to};
@@ -1138,9 +1816,23 @@ sub _extract_workflow_data {
 	}
 	for my $n (keys %$nodes) {
 		my $nd = $nodes->{$n};
-		$auto{$n}         = 1 if $nd->{auto};
-		$aliases{$n}      = $nd->{alias}       || $n;
-		$genesis_envs{$n} = $nd->{genesis_env} || $n;
+		$auto{$n}                = 1 if $nd->{auto};
+		$aliases{$n}             = $nd->{alias}               || $n;
+		$genesis_envs{$n}        = $nd->{genesis_env}         || $n;
+		$redeploy{$n}            = $nd->{redeploy}            || '';
+		$redeploy_cron_start{$n} = $nd->{redeploy_cron_start} || '';
+		$redeploy_cron_stop{$n}  = $nd->{redeploy_cron_stop}  || '';
+		$status_signal{$n}       = $nd->{status_signal}       // '';
+		$signal_prefix{$n}       = $nd->{signal_prefix}       || '';
+		$bosh_parent{$n}         = $nd->{bosh_parent}         || '';
+		$bosh_upgrade_lock{$n}   = $nd->{bosh_upgrade_lock}   // 1;
+		$track_bosh_configs{$n}  = $nd->{track_bosh_configs}
+			if defined $nd->{track_bosh_configs};
+	}
+	# Derive which envs are pipeline BOSH directors (referenced as bosh_parent)
+	for my $n (keys %bosh_parent) {
+		my $parent = $bosh_parent{$n};
+		$is_bosh_director{$parent} = 1 if $parent;
 	}
 
 	if ($workflow->{_legacy}) {
@@ -1154,12 +1846,21 @@ sub _extract_workflow_data {
 	}
 
 	return {
-		environments => (@$edges ? [_topological_sort($graph)] : [sort keys %$nodes]),
-		auto         => \%auto,
-		aliases      => \%aliases,
-		genesis_envs => \%genesis_envs,
-		will_trigger => \%will_trigger,
-		triggers     => \%triggers,
+		environments        => (@$edges ? [_topological_sort($graph)] : [sort keys %$nodes]),
+		auto                => \%auto,
+		aliases             => \%aliases,
+		genesis_envs        => \%genesis_envs,
+		will_trigger        => \%will_trigger,
+		triggers            => \%triggers,
+		redeploy            => \%redeploy,
+		redeploy_cron_start => \%redeploy_cron_start,
+		redeploy_cron_stop  => \%redeploy_cron_stop,
+		status_signal       => \%status_signal,
+		signal_prefix       => \%signal_prefix,
+		bosh_parent         => \%bosh_parent,
+		bosh_upgrade_lock   => \%bosh_upgrade_lock,
+		is_bosh_director    => \%is_bosh_director,
+		track_bosh_configs  => \%track_bosh_configs,
 	};
 }
 
@@ -1182,6 +1883,37 @@ sub _git_uri {
 	}
 }
 
+# }}}
+# _normalize_bosh_config_types - coerce track_bosh_configs to a list of types {{{
+#
+# Accepts: undef/false/""/0 → []
+#          true/yes/1       → [cloud, runtime]
+#          [cloud,runtime,cpi] (arrayref) → filtered list
+#          "cloud,runtime"  (comma string) → split and filtered
+sub _normalize_bosh_config_types {
+	my ($val) = @_;
+	return [] unless defined $val && $val ne '';
+	if (ref($val) eq 'ARRAY') {
+		return [grep { /^(?:cloud|runtime|cpi)$/ } @$val];
+	}
+	my $s = lc("$val");
+	return []                   if $s =~ /^(?:false|no|0)$/;
+	return ['cloud', 'runtime'] if $s =~ /^(?:true|yes|1)$/;
+	my @types = split /[\s,]+/, $s;
+	return [grep { /^(?:cloud|runtime|cpi)$/ } @types];
+}
+
+# }}}
+# _bosh_config_types - resolve track_bosh_configs for an env (per-env then global) {{{
+sub _bosh_config_types {
+	my ($self, $ast, $env, $wf_data) = @_;
+	my $track = $wf_data->{track_bosh_configs} || {};
+	my $val = exists $track->{$env}
+		? $track->{$env}
+		: ($ast->configuration || {})->{track_bosh_configs};
+	return _normalize_bosh_config_types($val);
+}
+
 # }}}
 # _unwrap_ref - unwrap secret_ref hash or return scalar {{{
 sub _unwrap_ref {
@@ -1267,21 +1999,19 @@ sub _mermaid_id {
 # }}}
 # _mermaid_node_def - node reference with optional gate shape annotation {{{
 sub _mermaid_node_def {
-	my ($alias, $node) = @_;
+	my ($alias, $node, $is_director) = @_;
 	$node ||= {};
-	my $id  = _mermaid_id($alias);
-	my $pr  = $node->{require_pr} || 0;
-	my $man = $node->{manual}     || 0;
-
-	if ($pr && $man) {
-		return "$id([$alias\\nPR+MANUAL])";
-	} elsif ($pr) {
-		return "$id([$alias\\nPR])";
-	} elsif ($man) {
-		return "$id([$alias\\nMANUAL])";
-	} else {
-		return $id;
-	}
+	my $id = _mermaid_id($alias);
+
+	my @labels;
+	push @labels, 'DIRECTOR' if $is_director;
+	push @labels, 'PR'       if $node->{require_pr};
+	push @labels, 'MANUAL'   if $node->{manual};
+	push @labels, 'REDEPLOY' if $node->{redeploy};
+
+	return @labels
+		? "$id([$alias\\n" . join('+', @labels) . "])"
+		: $id;
 }
 
 # }}}
diff --git a/lib/Genesis/CI/Compiler/PipelineProvider.pm b/lib/Genesis/CI/Compiler/PipelineProvider.pm
index 7f753f6f..73410ac6 100644
--- a/lib/Genesis/CI/Compiler/PipelineProvider.pm
+++ b/lib/Genesis/CI/Compiler/PipelineProvider.pm
@@ -4,7 +4,30 @@ use warnings;
 
 use Genesis;
 use JSON::PP;
+use Getopt::Long qw/GetOptionsFromArray/;
+
+### Provider Registry {{{
+# Maps provider type strings to their class and file paths.
+# Used by parse_cli_opts(), all_cli_opts_help(), and the compiler itself.
+
+my %_providers = (
+	'concourse' => {
+		class => 'Genesis::CI::Concourse',
+		file  => 'Genesis/CI/Compiler/Providers/Concourse.pm',
+	},
+	'github-actions' => {
+		class => 'Genesis::CI::GithubActions',
+		file  => 'Genesis/CI/Compiler/Providers/GithubActions.pm',
+	},
+);
+
+# known_providers - return list of known provider type strings {{{
+sub known_providers {
+	return sort keys %_providers;
+}
 
+# }}}
+# }}}
 ### Constructor {{{
 
 # new - create a new provider instance {{{
@@ -16,8 +39,9 @@ sub new {
 		if $class eq __PACKAGE__;
 
 	return bless({
-		ast => $opts{ast},
-		top => $opts{top},
+		ast           => $opts{ast},
+		top           => $opts{top},
+		provider_opts => $opts{provider_opts} || {},
 	}, $class);
 }
 
@@ -33,6 +57,13 @@ sub platform_name {
 	bug("Subclass '%s' must implement platform_name()", ref($self));
 }
 
+# }}}
+# provider_type - return canonical type string, e.g. 'concourse' {{{
+sub provider_type {
+	my ($self) = @_;
+	bug("Subclass '%s' must implement provider_type()", ref($self));
+}
+
 # }}}
 # generate_from_ast - generate platform-specific output from AST {{{
 sub generate_from_ast {
@@ -47,6 +78,278 @@ sub output_files {
 	bug("Subclass '%s' must implement output_files()", ref($self));
 }
 
+# }}}
+# }}}
+### Prerequisite Checking {{{
+
+# check_prereqs - returns 1 if toolchain is present, 0 + error() if not {{{
+sub check_prereqs {
+	return 1;
+}
+
+# }}}
+# }}}
+### Provider Options Contract {{{
+# These methods define the provider options system, modelled after
+# Genesis::Kit::Provider.  Subclasses override them to expose their
+# platform-specific flags, help text, and config-section schemas.
+
+# cli_opts - Getopt::Long option specs for deploy-time command-line flags {{{
+#
+# Returns a list of Getopt::Long spec strings, e.g.:
+#   qw( ci-target=s  ci-team=s  ci-pause  ci-expose )
+#
+# All CI-provider opts are prefixed with 'ci-' to avoid collisions with
+# top-level genesis option names (--target, --dry-run, etc.).
+#
+# Subclasses override to declare their provider-specific options.
+# Base implementation returns empty list (no provider-specific opts).
+sub cli_opts {
+	return qw//;
+}
+
+# }}}
+# cli_opts_help - formatted help text for cli_opts() {{{
+#
+# Returns a multi-line string (heredoc) documenting each option.
+# Format mirrors Genesis::Kit::Provider::Github::opts_help():
+#
+#   --ci-target <value>  (required)
+#       The fly target to deploy to.
+#
+#   --ci-team <value>  (optional, default: "main")
+#       The Concourse team name.
+#
+# %config may include:
+#   valid_types  - arrayref of provider type strings to show help for
+#
+# Subclasses override to document their specific options.
+sub cli_opts_help {
+	my ($class, %config) = @_;
+	return '';
+}
+
+# }}}
+# provider_options_schema - schema for the ci.provider: config section {{{
+#
+# Returns a hashref whose structure mirrors Top::_repo_config_schema():
+#
+#   {
+#     type      => { type => 'string', required => 1, description => '...' },
+#     target    => { type => 'string', description => '...' },
+#     team      => { type => 'string', default => 'main', description => '...' },
+#     expose    => { type => 'boolean', default => 0,    description => '...' },
+#     ...
+#   }
+#
+# The base class always contributes the common 'type' key; subclasses add
+# their own keys.  Used by validate_config_section() in Compiler.pm and
+# _validate_multi_file() in Validator.pm.
+sub provider_options_schema {
+	return {
+		type => {
+			type        => 'string',
+			required    => 1,
+			description => 'CI provider type (concourse, github-actions)',
+		},
+	};
+}
+
+# }}}
+# provider_options_defaults - default values for provider options {{{
+#
+# Returns a flat hashref of key => default_value.  Keys match those in
+# provider_options_schema().  Values here are NOT included in the config()
+# output — only explicitly-set non-default values are saved.
+sub provider_options_defaults {
+	return {};
+}
+
+# }}}
+# provider_config - return stored provider options (non-defaults only) {{{
+#
+# Returns a hashref suitable for round-tripping through the ci.provider:
+# config section — i.e. the type key plus any explicitly-set values that
+# differ from provider_options_defaults().
+sub provider_config {
+	my ($self) = @_;
+	my $defaults = $self->provider_options_defaults();
+	my $opts     = $self->{provider_opts} || {};
+	my %out = ( type => $self->provider_type() );
+	for my $k (keys %$opts) {
+		next unless defined $opts->{$k};
+		next if exists $defaults->{$k}
+		     && defined $defaults->{$k}
+		     && "$defaults->{$k}" eq "$opts->{$k}";
+		$out{$k} = $opts->{$k};
+	}
+	return \%out;
+}
+
+# }}}
+# provider_option - get a single provider option, applying defaults {{{
+sub provider_option {
+	my ($self, $key) = @_;
+	my $opts     = $self->{provider_opts} || {};
+	my $defaults = $self->provider_options_defaults();
+	return exists $opts->{$key}     ? $opts->{$key}
+	     : exists $defaults->{$key} ? $defaults->{$key}
+	     : undef;
+}
+
+# }}}
+# describe_provider - structured hash describing this provider instance {{{
+#
+# Returns a hash suitable for human-readable display, analogous to
+# Genesis::Kit::Provider::Github::status().
+#
+#   type    => 'concourse'
+#   label   => 'Concourse'       # human platform name
+#   extras  => [qw(Target Team Pipeline)]   # keys to show in order
+#   Target  => 'my-target'
+#   Team    => 'main'
+#   Pipeline => 'cf'
+#   status  => 'ok'              # or error message
+#
+# Subclasses override to add platform-specific fields.
+sub describe_provider {
+	my ($self) = @_;
+	return (
+		type   => $self->provider_type(),
+		label  => $self->platform_name(),
+		extras => [],
+		status => 'ok',
+	);
+}
+
+# }}}
+# }}}
+### Class Methods — Provider Options Parsing {{{
+
+# parse_cli_opts - two-pass CLI option parsing (mirrors Kit::Provider::parse_opts) {{{
+#
+# Usage:
+#   Genesis::CI::Compiler::PipelineProvider->parse_cli_opts(
+#       \@ARGV,           # args array (modified in place)
+#       \%opts,           # options hash (populated in place)
+#       $provider_type,   # optional: already-known provider type
+#   );
+#
+# Pass 1: parse --ci-provider <type> (if not already known)
+# Pass 2: load provider class, get cli_opts(), parse provider-specific flags
+#
+# Returns 1. Remaining unparsed args are put back into $args.
+sub parse_cli_opts {
+	my ($class, $args, $opts, $provider_type) = @_;
+
+	Getopt::Long::Configure(
+		qw(pass_through permute no_auto_abbrev no_ignore_case bundling)
+	);
+
+	# Collect args up to '--'
+	my $opt_args = [];
+	while (scalar(@$args) && $args->[0] ne '--') {
+		push @$opt_args, shift @$args;
+	}
+
+	# Pass 1: extract --ci-provider if not already known
+	unless ($provider_type) {
+		GetOptionsFromArray($opt_args, $opts, 'ci-provider=s');
+		$provider_type = $opts->{'ci-provider'} // $opts->{platform};
+	}
+
+	# Pass 2: load provider and parse provider-specific flags
+	if ($provider_type && exists $_providers{$provider_type}) {
+		my $info = $_providers{$provider_type};
+		eval { require $info->{file} }  ## no critic
+			or bail("Failed to load CI provider '%s': %s", $provider_type, $@);
+
+		my @extra_opts = $info->{class}->cli_opts();
+		GetOptionsFromArray($opt_args, $opts, @extra_opts) if @extra_opts;
+	}
+
+	# Return unparsed args to caller
+	while (scalar(@$opt_args)) { unshift @$args, pop @$opt_args }
+
+	return 1;
+}
+
+# }}}
+# cli_key_to_config_key - convert a ci-* CLI key to its config/schema key {{{
+#
+# The convention is: strip the 'ci-' prefix, convert hyphens to underscores.
+# Examples:
+#   ci-target        => target
+#   ci-team          => team
+#   ci-pipeline-name => pipeline_name
+#   ci-pause         => pause
+#   ci-expose        => expose
+#
+# Non-ci-prefixed keys are returned unchanged (already in config form).
+sub cli_key_to_config_key {
+	my ($class, $key) = @_;
+	$key =~ s/^ci-//;
+	$key =~ s/-/_/g;
+	return $key;
+}
+
+# }}}
+# normalize_provider_opts - convert a hash of CLI-keyed opts to config keys {{{
+sub normalize_provider_opts {
+	my ($class, $opts) = @_;
+	my %out;
+	for my $k (keys %{ $opts || {} }) {
+		$out{ $class->cli_key_to_config_key($k) } = $opts->{$k};
+	}
+	return \%out;
+}
+
+# }}}
+# cli_opt_keys - return parsed option key names for a given provider type {{{
+#
+# Strips Getopt::Long type suffixes (=s, !, +, etc.) leaving bare key names.
+# Used by the commands layer to copy matching options from get_options without
+# hardcoding provider-specific names.
+sub cli_opt_keys {
+	my ($class, $provider_type) = @_;
+	my $info = $_providers{$provider_type} or return ();
+	eval { require $info->{file} }  ## no critic
+		or bail("Failed to load CI provider '%s': %s", $provider_type, $@);
+	return map { (split /[=!+:]/, $_)[0] } $info->{class}->cli_opts();
+}
+
+# }}}
+# all_cli_opts_help - assembled help text for all known providers {{{
+#
+# Prints shared CI flags, then delegates to each provider's cli_opts_help().
+# Mirrors Genesis::Kit::Provider::opts_help() in structure.
+sub all_cli_opts_help {
+	my ($class, %config) = @_;
+
+	$config{valid_types} ||= [sort keys %_providers];
+
+	# Load all provider classes for their help text
+	for my $type (sort keys %_providers) {
+		eval { require $_providers{$type}{file} };  ## no critic
+	}
+
+	my $provider_help = join('',
+		map  { $_providers{$_}{class}->cli_opts_help(%config) }
+		grep { eval { require $_providers{$_}{file}; 1 } }  ## no critic
+		sort keys %_providers
+	);
+
+	return <<EOF;
+CI PROVIDER OPTIONS
+
+  --ci-provider <type>  (optional, defaults to "concourse")
+      The CI provider to use for pipeline generation and deployment.
+      Available types: ${\ join(', ', sort keys %_providers) }
+
+$provider_help
+EOF
+}
+
 # }}}
 # }}}
 ### Shared Helper Methods {{{
@@ -148,9 +451,9 @@ sub topological_sort {
 sub matches_pattern {
 	my ($self, $name, $pattern) = @_;
 
-	my $regex = $pattern;
-	$regex =~ s/\*/.*/g;
-	$regex =~ s/\?/./g;
+	my $regex = join('', map {
+		$_ eq '*' ? '.*' : $_ eq '?' ? '.' : quotemeta($_)
+	} split(/([*?])/, $pattern, -1));
 
 	return $name =~ /^$regex$/;
 }
diff --git a/lib/Genesis/CI/Compiler/Providers/Concourse.pm b/lib/Genesis/CI/Compiler/Providers/Concourse.pm
index 4290907f..bda1cc48 100644
--- a/lib/Genesis/CI/Compiler/Providers/Concourse.pm
+++ b/lib/Genesis/CI/Compiler/Providers/Concourse.pm
@@ -10,6 +10,17 @@ use Genesis::CI::Legacy;
 use Genesis::CI::Compiler::PipelineDescriptor;
 use JSON::PP;
 
+### Provider Constants {{{
+
+use constant {
+	DEFAULT_TEAM            => 'main',
+	DEFAULT_PIPELINE_NAME   => undef,    # falls back to deployment_type from Top
+	DEFAULT_EXPOSE          => 0,
+	DEFAULT_PAUSE_AFTER_SET => 0,
+	DEFAULT_INSECURE        => 0,
+};
+
+# }}}
 ### Class Methods {{{
 
 # new - constructor for compiler pipeline path {{{
@@ -19,8 +30,9 @@ sub new {
 	# Compiler construction path: receives AST and optionally top
 	if ($opts{ast}) {
 		return bless({
-			ast => $opts{ast},
-			top => $opts{top},
+			ast           => $opts{ast},
+			top           => $opts{top},
+			provider_opts => $opts{provider_opts} || {},
 		}, $class);
 	}
 
@@ -30,23 +42,265 @@ sub new {
 }
 
 # }}}
-# init - initialize Concourse provider {{{
+# init - initialize Concourse provider (trait interface path) {{{
 sub init {
 	my ($class, %opts) = @_;
 
 	my $self = bless({
-		file      => $opts{file},
-		top       => $opts{top},
-		layout    => $opts{layout},
-		_platform => $opts{platform} || '',
-		config    => undef,
-		ast       => undef,
-		errors    => [],
+		file          => $opts{file},
+		top           => $opts{top},
+		layout        => $opts{layout},
+		_platform     => $opts{platform} || '',
+		provider_opts => $opts{provider_opts} || {},
+		config        => undef,
+		ast           => undef,
+		errors        => [],
 	}, $class);
 
 	return $self;
 }
 
+# }}}
+# }}}
+### Provider Options System {{{
+# Modelled after Genesis::Kit::Provider::Github — each method mirrors its
+# kit-provider counterpart so the patterns are interchangeable.
+
+# provider_type - canonical type string {{{
+sub provider_type { 'concourse' }
+
+# }}}
+# check_prereqs - returns 1 if fly is in PATH, 0 + error() if not {{{
+sub check_prereqs {
+	my ($self) = @_;
+
+	my ($fly_path) = run({ stderr => 0 }, 'type -p fly');
+	chomp($fly_path //= '');
+	unless ($fly_path) {
+		error(
+			"Cannot deploy Concourse pipeline: the #C{fly} CLI was not found in ".
+			"your PATH.\n".
+			"  Install it from your Concourse server:\n".
+			"    #C{<concourse-url>/api/v1/cli?arch=amd64&platform=<linux|darwin|windows>}\n".
+			"  Or log in via the Concourse UI and download fly from the bottom-right icon.",
+		);
+		return 0;
+	}
+
+	return 1;
+}
+
+# }}}
+# cli_opts - Getopt::Long specs for deploy-time command-line flags {{{
+#
+# All CI provider options are prefixed with 'ci-' to avoid clashing with
+# top-level genesis option names.
+sub cli_opts {
+	qw/
+		ci-target=s
+		ci-team=s
+		ci-pipeline-name=s
+		ci-pause
+		ci-expose
+		ci-insecure
+	/;
+}
+
+# }}}
+# cli_opts_help - formatted help text for Concourse CLI flags {{{
+sub cli_opts_help {
+	my ($class, %config) = @_;
+	return '' unless grep { $_ eq 'concourse' } @{$config{valid_types} || ['concourse']};
+	return <<'EOF';
+  CI Provider `concourse`:
+
+    Deploys Genesis pipelines to a Concourse CI server using the fly CLI.
+    Requires a configured fly target (see: fly login).
+
+    --ci-target <name>  (required if not set in .genesis/config ci.provider.target)
+        The fly target alias that identifies the Concourse server.
+        Create a target with: fly login -t <name> -c <url>
+
+    --ci-team <name>  (optional, default: "main")
+        The Concourse team to use when setting the pipeline.
+        Must match an existing team on the target Concourse server.
+
+    --ci-pipeline-name <name>  (optional, default: deployment type from .genesis/config)
+        Override the pipeline name used in Concourse.
+        Defaults to the repository's deployment_type (e.g., "cf", "bosh").
+
+    --ci-pause  (optional, default: false)
+        Leave the pipeline in a paused state after fly set-pipeline completes.
+        By default the pipeline is unpaused immediately after being set.
+
+    --ci-expose  (optional, default: false)
+        Run fly expose-pipeline after setting, making the pipeline publicly
+        viewable without authentication.  Useful for open-source pipelines.
+
+    --ci-insecure  (optional, default: false)
+        Skip TLS certificate verification when communicating with Concourse.
+        Passes --skip-ssl-validation (-k) to all fly commands.  Use when the
+        Concourse server uses a self-signed or otherwise untrusted certificate.
+
+  Pipeline features are driven by configuration files, not CLI flags.
+  The following sections are controlled in ci/configuration.yml (or the
+  legacy ci.yml):
+
+    Notification styles (integrations.slack.style):
+        per-env  — pending-changes notify job gates each deployment (default)
+        grouped  — notify jobs exist but do not block deployments
+        minimal  — no notify jobs; Slack alerts on failure only
+        none     — no Slack resource or notifications at all
+
+    BOSH upgrade locks (genesis.pipeline.locks.bosh_upgrade):
+        Automatically wired when a pipeline manages a BOSH director alongside
+        child deployments.  Prevents a director upgrade from racing a child
+        deploy.  Requires a locker integration.  Opt out per-env with:
+            genesis:
+              pipeline:
+                locks:
+                  bosh_upgrade: false
+
+    Task library (configuration.task_library):
+        Declares an external git repository of custom task files.  The repo
+        is checked out as a Concourse git resource and made available as an
+        input to every deploy task.  Configure uri, branch, path, and auth.
+
+EOF
+}
+
+# }}}
+# provider_options_schema - schema for ci.provider: when type=concourse {{{
+#
+# Keys map directly to the ci.provider: sub-keys in .genesis/config.
+# This schema is used by:
+#   - Genesis::CI::Compiler::validate_config_section()
+#   - Genesis::CI::Compiler::Validator::_validate_multi_file()
+#
+# NOTE: notification styles, BOSH upgrade locks, and task library are
+# configuration-level features (ci/configuration.yml), not provider-level
+# options — they are documented in the cli_opts_help and POD below.
+sub provider_options_schema {
+	return {
+		type => {
+			type        => 'string',
+			required    => 1,
+			description => 'Provider type (must be "concourse")',
+		},
+		target => {
+			type        => 'string',
+			description => 'Fly target alias (fly login -t <target>)',
+		},
+		url => {
+			type        => 'string',
+			description => 'Concourse API URL (informational; used by fly login)',
+		},
+		team => {
+			type        => 'string',
+			default     => DEFAULT_TEAM,
+			description => 'Concourse team name',
+		},
+		pipeline_name => {
+			type        => 'string',
+			description => 'Pipeline name override (defaults to deployment_type)',
+		},
+		expose => {
+			type        => 'boolean',
+			default     => DEFAULT_EXPOSE,
+			description => 'Make pipeline publicly viewable (fly expose-pipeline)',
+		},
+		pause_after_set => {
+			type        => 'boolean',
+			default     => DEFAULT_PAUSE_AFTER_SET,
+			description => 'Leave pipeline paused after fly set-pipeline',
+		},
+		insecure => {
+			type        => 'boolean',
+			default     => DEFAULT_INSECURE,
+			description => 'Skip TLS certificate verification (fly --skip-ssl-validation)',
+		},
+	};
+}
+
+# }}}
+# provider_options_defaults - default values for all Concourse options {{{
+sub provider_options_defaults {
+	return {
+		team            => DEFAULT_TEAM,
+		expose          => DEFAULT_EXPOSE,
+		pause_after_set => DEFAULT_PAUSE_AFTER_SET,
+		insecure        => DEFAULT_INSECURE,
+	};
+}
+
+# }}}
+# normalize_provider_opts - remap ci-pause (CLI) to pause_after_set (schema key) {{{
+sub normalize_provider_opts {
+	my ($class, $opts) = @_;
+	my $normalized = $class->SUPER::normalize_provider_opts($opts);
+	if (exists $normalized->{pause} && !exists $normalized->{pause_after_set}) {
+		$normalized->{pause_after_set} = delete $normalized->{pause};
+	}
+	return $normalized;
+}
+
+# }}}
+# describe_provider - structured self-description for display {{{
+#
+# Mirrors Genesis::Kit::Provider::Github::status() — returns a hash with
+# type, label, an ordered 'extras' list, and a per-key status structure.
+# Also surfaces the active notification style and task library when an AST
+# is already resolved (i.e., after parse() has been called).
+sub describe_provider {
+	my ($self) = @_;
+
+	my $target    = $self->provider_option('target')        || '(not set)';
+	my $team      = $self->provider_option('team')          || DEFAULT_TEAM;
+	my $pipe_name = $self->provider_option('pipeline_name') || '(deployment type)';
+	my $expose    = $self->provider_option('expose')    ? 'yes' : 'no';
+	my $paused    = $self->provider_option('pause_after_set') ? 'yes' : 'no';
+	my $insecure  = $self->provider_option('insecure')  ? 'yes' : 'no';
+
+	my @extras = qw(Target Team Pipeline Expose PauseAfterSet Insecure);
+	my %desc = (
+		type          => 'concourse',
+		label         => 'Concourse',
+		Target        => $target,
+		Team          => $team,
+		Pipeline      => $pipe_name,
+		Expose        => $expose,
+		PauseAfterSet => $paused,
+		Insecure      => $insecure,
+		status        => 'ok',
+	);
+
+	# Augment with pipeline-level feature summary when AST is available
+	if (my $ast = $self->{ast}) {
+		my $descriptor = Genesis::CI::Compiler::PipelineDescriptor->new(ast => $ast);
+
+		# Notification style
+		my $notif_style = $descriptor->_effective_notif_style($ast);
+		push @extras, 'NotifStyle';
+		$desc{NotifStyle} = $notif_style;
+
+		# Task library
+		my $tl = ($ast->configuration || {})->{task_library};
+		if ($tl && ref($tl) eq 'HASH' && $tl->{uri}) {
+			push @extras, 'TaskLibrary';
+			my $rn = $tl->{resource_name} || 'tasks';
+			$desc{TaskLibrary} = "$rn ($tl->{uri})";
+		}
+
+		# BOSH upgrade lock summary
+		my $has_locker = ($ast->integrations->{locker} || {})->{url} ? 'yes' : 'no';
+		push @extras, 'BoshLocks';
+		$desc{BoshLocks} = $has_locker;
+	}
+
+	$desc{extras} = \@extras;
+	return %desc;
+}
+
 # }}}
 # }}}
 ### Trait Interface Implementation {{{
@@ -101,7 +355,6 @@ sub parse {
 
 	$self->{ast}    = $ast;
 	$self->{config} = $parsed;
-	$self->{layout} = $self->{layout};
 
 	return $self;
 }
@@ -128,67 +381,108 @@ sub generate {
 
 # }}}
 # deploy - deploy pipeline to Concourse via fly CLI {{{
+#
+# Option resolution priority (highest to lowest):
+#   1. Caller-supplied %opts (from command-line flags via parse_cli_opts)
+#   2. provider_opts stored in $self (loaded from ci.provider: in .genesis/config)
+#   3. Legacy $self->{layout} (backward compat)
+#   4. Built-in defaults (team: main, etc.)
 sub deploy {
 	my ($self, %opts) = @_;
-	
-	my $target = $opts{target} || $self->{layout};
-	my $pipeline_name = $self->{config}{pipeline}{name};
-	my $dry_run = $opts{'dry-run'};
-	my $yes = $opts{yes};
-	my $paused = $opts{paused};
-	
+
 	bail("Must call parse() before deploy()") unless $self->{config};
-	
+
+	# All keys use config-file names (target, team, pipeline_name, pause_after_set, expose).
+	# Callers are responsible for normalizing cli-prefixed keys before calling deploy().
+
+	# --- Resolve options from three tiers ---
+
+	# Target: call-site override > provider_opts > legacy layout
+	my $target = $opts{target}
+		// $self->provider_option('target')
+		// $self->{layout};
+	bail("No Concourse target specified.  Use --ci-target or set ci.provider.target in .genesis/config")
+		unless $target;
+
+	# Team: call-site override > provider_opts > default
+	my $team = $opts{team}
+		// $self->provider_option('team')
+		// DEFAULT_TEAM;
+
+	# Pipeline name: call-site override > provider_opts > config name > deployment_type
+	my $pipeline_name = $opts{pipeline_name}
+		// $self->provider_option('pipeline_name')
+		// $self->{config}{pipeline}{name}
+		// ($self->{top} ? $self->{top}->type : undef);
+	bail("Cannot determine pipeline name — set ci.provider.pipeline_name or ensure deployment_type is set")
+		unless $pipeline_name;
+
+	# Pause/expose/dry-run/insecure: call-site override > provider_opts > defaults
+	my $dry_run  = $opts{'dry-run'};
+	my $yes      = $opts{yes};
+	my $pause    = $opts{pause_after_set}
+		// $self->provider_option('pause_after_set')
+		// DEFAULT_PAUSE_AFTER_SET;
+	my $expose   = $opts{expose}
+		// $self->provider_option('expose')
+		// _yaml_bool(($self->{config}{pipeline} || {})->{public}, DEFAULT_EXPOSE);
+	my $insecure = $opts{insecure}
+		// $self->provider_option('insecure')
+		// DEFAULT_INSECURE;
+
 	my $yaml = $self->generate();
-	
+
 	if ($dry_run) {
 		output({raw => 1}, $yaml);
 		return;
 	}
-	
-	# Pause pipeline before updating
+
+	my $k_flag = $insecure ? ' -k' : '';
+
+	# Pause pipeline before updating (safe to do even when not found yet)
 	my ($out, $rc) = run(
-		'fly -t $1 pause-pipeline -p $2',
+		"fly${k_flag} -t \$1 pause-pipeline -p \$2",
 		$target, $pipeline_name
 	);
 	bail("Could not pause pipeline '%s': %s", $pipeline_name, $out)
 		unless $rc == 0 || $out =~ /pipeline '.*' not found/;
-	
+
 	# Write pipeline to temp file
 	my $dir = workdir;
 	mkfile_or_fail("${dir}/pipeline.yml", $yaml);
-	
+
 	# Upload pipeline
-	my $yes_flag = $yes ? '-n' : '';
+	my $yes_flag  = $yes ? ' -n' : '';
+	my $team_flag = " --team=$team";
 	run({
 		interactive => 1,
-		onfailure => "Could not upload pipeline $pipeline_name"
+		onfailure => "Could not upload pipeline $pipeline_name",
 	},
-		'fly -t $1 set-pipeline '.$yes_flag.' -p $2 -c $3/pipeline.yml',
+		"fly${k_flag} -t \$1 set-pipeline${yes_flag}${team_flag} -p \$2 -c \$3/pipeline.yml",
 		$target, $pipeline_name, $dir
 	);
-	
-	# Unpause pipeline (unless --paused)
-	unless ($paused) {
+
+	# Unpause pipeline (unless ci.provider.pause or --ci-pause override)
+	unless ($pause) {
 		run({
 			interactive => 1,
-			onfailure => "Could not unpause pipeline $pipeline_name"
+			onfailure => "Could not unpause pipeline $pipeline_name",
 		},
-			'fly -t $1 unpause-pipeline -p $2',
+			"fly${k_flag} -t \$1 unpause-pipeline -p \$2",
 			$target, $pipeline_name
 		);
 	}
-	
-	# Set visibility (public/private)
-	my $action = $self->{config}{pipeline}{public} ? 'expose' : 'hide';
+
+	# Set visibility (expose vs hide)
+	my $action = $expose ? 'expose' : 'hide';
 	run({
 		interactive => 1,
-		onfailure => "Could not $action pipeline $pipeline_name"
+		onfailure => "Could not $action pipeline $pipeline_name",
 	},
-		'fly -t $1 '.$action.'-pipeline -p $2',
+		"fly${k_flag} -t \$1 ${action}-pipeline -p \$2",
 		$target, $pipeline_name
 	);
-	
+
 	return;
 }
 
@@ -319,7 +613,7 @@ sub graph_md {
 }
 
 # }}}
-# generate_description - alias for describe(); called by Genesis::Commands::Pipeline {{{
+# generate_description - alias for describe(); called by Genesis::Commands::Pipelines {{{
 sub generate_description { $_[0]->describe() }
 
 # }}}
@@ -402,27 +696,165 @@ Genesis::CI::Concourse - Concourse CI provider implementation
 =head1 DESCRIPTION
 
 Genesis::CI::Concourse implements the Genesis::CI trait interface for
-Concourse CI. It handles parsing ci.yml configuration, generating Concourse
-pipeline YAML, and deploying pipelines via the fly CLI.
+Concourse CI.  It handles parsing configuration, generating Concourse pipeline
+YAML, and deploying pipelines via the fly CLI.
+
+The native pipeline compiler (C<PipelineDescriptor>) produces fully-resolved
+Concourse YAML.  The following sections document every first-class feature.
+
+=head2 Deployment propagation
+
+Environments form a directed graph; each env's git branch is updated after its
+upstream deploys successfully.  The graph is derived from C<genesis.pipeline.prior_env>
+keys in each environment YAML file, or from explicit C<stages:> declarations in
+C<pipeline.yml>.
+
+=head2 Notification styles (C<integrations.slack.style>)
+
+Four styles control what gets notified, when, and how.
+
+  integrations:
+    slack:
+      webhook:  ((slack-webhook))
+      channel:  '#deployments'
+      style:    grouped       # per-env | grouped | minimal | none
+
+B<per-env> (default) — A C<notify-E<lt>envE<gt>-E<lt>typeE<gt>-changes> job is
+created for every non-auto environment.  The deploy job depends on the notify
+job, so deployment is gated on operator acknowledgement.
+
+B<grouped> — Same notify jobs as C<per-env>, but they are collected into a
+separate C<notifications> Concourse group.  Deploy jobs do not depend on them.
+
+B<minimal> — No notify jobs.  Slack notifications fire only on failure via the
+C<on_failure> hook.  Success is silent.
+
+B<none> — No Slack resource, no notify jobs, no hooks.  The
+C<slack-notification> resource type is also omitted from the pipeline.
+
+=head3 mentions_on_failure
+
+A list of Slack handles prepended to failure notification text only:
+
+  slack:
+    mentions_on_failure:
+      - '@sre-oncall'
+
+=head3 per_env_overrides
+
+Override C<channel> and/or C<mentions_on_failure> for a specific environment:
+
+  slack:
+    channel: '#deployments'
+    per_env_overrides:
+      prod:
+        channel: '#prod-critical'
+        mentions_on_failure:
+          - '@prod-sre'
+
+=head2 BOSH upgrade locks (C<genesis.pipeline.locks.bosh_upgrade>)
 
-This implementation currently delegates to Genesis::CI::Legacy for the heavy
-lifting, but provides a clean interface for future refactoring.
+When a child deployment's YAML declares C<genesis.bosh_env: E<lt>directorE<gt>> and
+the named director is also in the pipeline, Genesis wires a shared upgrade lock:
+
+=over 4
+
+=item Director — emits C<E<lt>aliasE<gt>-bosh-lock> as a named Concourse locker
+resource (C<lock_name: E<lt>aliasE<gt>-bosh-upgrade>).  Its deploy job acquires
+the lock before upgrading.
+
+=item Child — acquires the director's shared C<bosh-lock> before deploying,
+blocking any concurrent director upgrade.  No own bosh-lock resource is emitted.
+
+=item Standalone — acquires a per-env C<bosh-lock> by BOSH URL (legacy behaviour
+for envs whose director is not in the same pipeline).
+
+=back
+
+Requires a C<locker:> integration.  Opt out per-env:
+
+  genesis:
+    pipeline:
+      locks:
+        bosh_upgrade: false
+
+=head2 Redeploy lane (C<genesis.pipeline.redeploy>)
+
+A separate C<redeploy-E<lt>envE<gt>> job redeploys without change detection or
+cache promotion.  Three trigger modes:
+
+B<manual> — operator triggers via Concourse UI or C<fly trigger-job>.
+
+B<cron> — a C<time> resource triggers within a daily window
+(C<redeploy_cron_start> / C<redeploy_cron_stop>, default 04:00–05:00 UTC).
+
+B<signal> — triggers off the environment's C<E<lt>envE<gt>-signal> resource
+(version C<{status: success}>).  Requires C<status_signal> to be configured.
+
+=head2 Deployment status signals (C<configuration.status_signal>)
+
+Every deploy and redeploy job emits C<on_success>, C<on_failure>, C<on_abort>,
+and C<on_error> put steps to a per-environment C<E<lt>envE<gt>-signal> resource
+backed by C<cfcommunity/shuttle-resource>.  Supported backends: C<file>, C<s3>,
+C<gcs>.
+
+  configuration:
+    status_signal:
+      backend: s3
+      bucket:  my-genesis-signals
+      region:  us-east-1
+      access_key_id:     ((aws-access-key))
+      secret_access_key: ((aws-secret-key))
+
+Per-env backend or prefix override in the env YAML:
+
+  genesis:
+    pipeline:
+      status_signal: gcs
+      signal_prefix: my-pipeline/prod
+
+Disable for a specific env:
+
+  genesis:
+    pipeline:
+      status_signal: false
+
+=head2 Task library (C<configuration.task_library>)
+
+Declare an external git repository of custom task files.  Genesis emits a
+C<tasks> git resource, adds a non-triggering C<get: tasks> step to every deploy
+and redeploy job, and passes the library as an input to every running task.
+
+  configuration:
+    task_library:
+      uri:           https://github.com/org/pipeline-tasks.git
+      branch:        main              # optional, default 'main'
+      path:          tasks             # optional subdirectory within the repo
+      resource_name: tasks             # optional resource name, default 'tasks'
+      auth:
+        type:        ssh-key           # or 'token'
+        private_key: ((library-key))   # for ssh-key
+        # — or —
+        password: ((library-token))    # for token (username defaults to x-oauth-basic)
+
+The C<GENESIS_TASK_LIBRARY_PATH> environment variable is set in each task to the
+resolved path (C<E<lt>resource_nameE<gt>> or C<E<lt>resource_nameE<gt>/E<lt>pathE<gt>>).
 
 =head1 SYNOPSIS
 
-  # Via trait interface (legacy path)
+  # Via trait interface
   use Genesis::CI;
   my $ci = Genesis::CI->new(
     type   => 'concourse',
     file   => 'ci.yml',
     top    => $top_obj,
-    layout => 'default'
+    layout => 'default',
   );
   $ci->parse();
   my $yaml = $ci->generate();
   $ci->deploy(target => 'prod', yes => 1);
 
-  # Via compiler pipeline (new path)
+  # Via compiler pipeline
   my $result = Genesis::CI->compile(
     ci_dir   => '.genesis/ci',
     provider => 'concourse',
@@ -433,69 +865,79 @@ lifting, but provides a clean interface for future refactoring.
 
 =head2 generate_from_ast($ast)
 
-Generate Concourse pipeline YAML from a Genesis::CI::Compiler::AST.
-For legacy-sourced ASTs, bridges to Legacy::generate_pipeline_concourse_yaml().
-For modern ASTs, generates Concourse YAML natively.
+Generate Concourse pipeline YAML from a C<Genesis::CI::Compiler::AST>.
+Legacy-sourced ASTs are bridged to C<Legacy::generate_pipeline_concourse_yaml()>.
+Modern ASTs are generated natively via C<PipelineDescriptor>.
 
 =head2 output_files()
 
-Returns hash describing generated files.
+Returns a hash describing generated output files.
 
 =head1 TRAIT INTERFACE METHODS
 
 =head2 init(%opts)
 
-Initialize Concourse provider instance.
+Initialize a Concourse provider instance via the trait path.
 
 =head2 parse()
 
-Parse and validate ci.yml configuration for Concourse.
+Parse and validate the CI configuration.  Populates C<$self-E<gt>{ast}>.
 
 =head2 generate()
 
-Generate Concourse pipeline YAML.
+Generate Concourse pipeline YAML.  Must be called after C<parse()>.
 
 =head2 deploy(%opts)
 
-Deploy pipeline to Concourse via fly CLI.
+Deploy the pipeline to Concourse via the fly CLI.
 
-Options: target, dry-run, yes, paused
+Options: C<target>, C<team>, C<pipeline_name>, C<pause_after_set>, C<expose>,
+C<insecure>, C<dry-run>, C<yes>.
 
 =head2 platform_name()
 
-Returns "Concourse".
+Returns C<"Concourse">.
 
 =head2 file_extension()
 
-Returns ".yml".
+Returns C<".yml">.
 
 =head1 CONCOURSE-SPECIFIC METHODS
 
 =head2 graph_md()
 
-Generate pipeline.md content containing a Mermaid flowchart LR diagram.
+Generate C<pipeline.md> content containing a Mermaid flowchart LR diagram.
+Director environments are annotated with C<DIRECTOR>.
 
 =head2 describe()
 
-Print human-readable pipeline description to stdout.
+Print a human-readable pipeline description to stdout.  Each environment is
+annotated with gate mode (C<PR>, C<MANUAL>), redeploy mode
+(C<REDEPLOY:MANUAL|CRON|SIGNAL>), and signal backend (C<SIGNAL:file|s3|gcs>).
+
+=head2 describe_provider()
+
+Return a structured description hash for CLI display.  When an AST is
+available (after C<parse()>), the description includes C<NotifStyle>,
+C<TaskLibrary>, and C<BoshLocks> fields.
 
 =head1 ACCESSORS
 
 =head2 config()
 
-Returns parsed pipeline configuration.
+Returns the parsed configuration.
 
 =head2 top()
 
-Returns Genesis::Top object.
+Returns the C<Genesis::Top> object.
 
 =head2 layout()
 
-Returns layout name.
+Returns the layout name.
 
 =head1 SEE ALSO
 
-Genesis::CI, Genesis::CI::GithubActions, Genesis::CI::Legacy
+L<Genesis::CI>, L<Genesis::CI::Legacy>, L<Genesis::CI::Compiler::PipelineDescriptor>
 
 =cut
 
diff --git a/lib/Genesis/CI/Compiler/Validator.pm b/lib/Genesis/CI/Compiler/Validator.pm
index 9e1573ca..11a7a75e 100644
--- a/lib/Genesis/CI/Compiler/Validator.pm
+++ b/lib/Genesis/CI/Compiler/Validator.pm
@@ -3,6 +3,7 @@ use strict;
 use warnings;
 
 use Genesis;
+use Genesis::Top ();
 use JSON::PP;
 
 ### Constructor {{{
@@ -438,10 +439,78 @@ sub _validate_multi_file {
 	# Validate integrations section
 	$self->_validate_integrations_section($parsed->{integrations});
 
+	# Validate provider options section (ci.provider: or provider-config/concourse.yml)
+	$self->_validate_provider_section($parsed->{provider})
+		if $parsed->{provider};
+
 	# Cross-reference validation
 	$self->_validate_cross_references($parsed);
 }
 
+# }}}
+# _validate_provider_section - validate ci.provider: options against provider schema {{{
+#
+# Called when a 'provider' key is present in the parsed config (inline in
+# .genesis/config or as provider-config/concourse.yml).  Loads the named
+# provider class and validates subkeys against its provider_options_schema().
+sub _validate_provider_section {
+	my ($self, $provider) = @_;
+
+	unless (ref($provider) eq 'HASH') {
+		$self->_error("'provider' section must be a hash");
+		return;
+	}
+
+	my $type = $provider->{type};
+	unless ($type) {
+		$self->_error("'provider.type' is required");
+		return;
+	}
+
+	# Load provider class to get its schema
+	require Genesis::CI::Compiler::PipelineProvider;
+	my %known = map { $_ => 1 } Genesis::CI::Compiler::PipelineProvider->known_providers();
+	unless ($known{$type}) {
+		$self->_error(sprintf(
+			"'provider.type' is '%s', which is not a known CI provider.  Valid types: %s",
+			$type, join(', ', sort keys %known)
+		));
+		return;
+	}
+
+	# Dynamically load provider to get its schema
+	my $provider_info;
+	eval {
+		require Genesis::CI::Compiler;
+		$provider_info = Genesis::CI::Compiler->_resolve_provider_class($type);
+		require $provider_info->{file};  ## no critic
+	};
+	if ($@) {
+		$self->_warn("Could not load provider '$type' for schema validation: $@");
+		return;
+	}
+
+	my $schema = $provider_info->{class}->provider_options_schema();
+
+	# Check required keys
+	for my $key (sort keys %$schema) {
+		my $spec = $schema->{$key};
+		next unless $spec->{required};
+		$self->_error(sprintf("'provider.%s' is required for provider type '%s'", $key, $type))
+			unless defined $provider->{$key};
+	}
+
+	# Check unknown keys
+	for my $key (sort keys %$provider) {
+		unless (exists $schema->{$key}) {
+			$self->_error(sprintf(
+				"'provider.%s' is not a recognized option for provider type '%s'.  Valid options: %s",
+				$key, $type, join(', ', sort keys %$schema)
+			));
+		}
+	}
+}
+
 # }}}
 # _validate_pipeline_section - validate pipeline.yml structure {{{
 sub _validate_pipeline_section {
@@ -452,25 +521,27 @@ sub _validate_pipeline_section {
 		return;
 	}
 
+	# Empty pipeline section means env-file-topology mode (no pipeline.yml).
+	# Topology is derived from genesis.pipeline.* in env files; nothing to validate here.
+	return unless %$pipeline;
+
 	# Metadata
 	if ($pipeline->{metadata}) {
-		$self->_error("'metadata.name' is required")
+		$self->_error("'pipeline.metadata.name' is required")
 			unless $pipeline->{metadata}{name};
 	}
 
 	# Branches
 	if ($pipeline->{branches}) {
-		$self->_error("'branches.live' is required")
-			unless $pipeline->{branches}{live};
+		$self->_error("'pipeline.branches." . Genesis::Top::CI_PIPELINE_CONTROL_KEY() . "' is required")
+			unless $pipeline->{branches}{Genesis::Top::CI_PIPELINE_CONTROL_KEY()};
 	}
 
-	# Workflows
+	# Workflows are optional — absent means topology is derived from env files
 	if ($pipeline->{workflows}) {
 		for my $wf_name (keys %{$pipeline->{workflows}}) {
 			$self->_validate_workflow($wf_name, $pipeline->{workflows}{$wf_name});
 		}
-	} else {
-		$self->_error("'workflows' section is required in pipeline.yml");
 	}
 }
 
@@ -576,20 +647,20 @@ sub _validate_integrations_section {
 	my ($self, $integrations) = @_;
 
 	unless ($integrations && ref($integrations) eq 'HASH') {
-		$self->_error("Invalid or empty integrations.yml");
+		$self->_error("'integrations' section is missing or invalid");
 		return;
 	}
 
 	# Vault is required
 	unless ($integrations->{vault}) {
-		$self->_error("'vault' section is required in integrations.yml");
+		$self->_error("'integrations.vault' is required (set ci.integrations.vault or ci.vault)");
 	} elsif (!$integrations->{vault}{url}) {
-		$self->_error("'vault.url' is required in integrations.yml");
+		$self->_error("'integrations.vault.url' is required");
 	}
 
 	# Source control is required
 	unless ($integrations->{source_control}) {
-		$self->_error("'source_control' section is required in integrations.yml");
+		$self->_error("'integrations.source_control' is required (set ci.integrations.source_control or ci.source_control)");
 	}
 }
 
@@ -611,12 +682,14 @@ sub _validate_cross_references {
 			next unless $trigger->{pattern};
 
 			my $pattern = $trigger->{pattern};
-			my $regex = $pattern;
-			$regex =~ s/\*/.*/g;
+			my $regex = join('', map {
+				$_ eq '*' ? '.*' : $_ eq '?' ? '.' : quotemeta($_)
+			} split(/([*?])/, $pattern, -1));
+			$regex = qr/^$regex$/;
 
 			my $matched = 0;
 			for my $target_name (keys %$targets) {
-				if ($target_name =~ /^$regex$/) {
+				if ($target_name =~ $regex) {
 					$matched = 1;
 					last;
 				}
diff --git a/lib/Genesis/CI/Layout.pm b/lib/Genesis/CI/Layout.pm
index f174e8cf..90cd2fcc 100644
--- a/lib/Genesis/CI/Layout.pm
+++ b/lib/Genesis/CI/Layout.pm
@@ -113,8 +113,9 @@ sub parse {
 	my @expansion_pool = $known ? @$known : @envs;
 	my %auto_envs;
 	for my $pattern (@auto_patterns) {
-		my $regex = $pattern;
-		$regex =~ s/\*/.*/g;
+		# Build a safe regex: escape metacharacters in literal segments,
+		# then replace \* (escaped asterisk) with .* for glob semantics.
+		my $regex = join('.*', map { quotemeta($_) } split(/\*/, $pattern, -1));
 		$regex = qr/^$regex$/;
 
 		my $matched = 0;
diff --git a/lib/Genesis/CI/Legacy.pm b/lib/Genesis/CI/Legacy.pm
index ad295649..035cce64 100644
--- a/lib/Genesis/CI/Legacy.pm
+++ b/lib/Genesis/CI/Legacy.pm
@@ -276,7 +276,6 @@ sub validate_pipeline {
 						push @errors, "Unrecognized `pipeline.email.smtp.$_' key found."
 							unless m/^(host|port|username|password)$/;
 					}
-				} else {
 				}
 			}
 		}
diff --git a/lib/Genesis/CI/Propagation.pm b/lib/Genesis/CI/Propagation.pm
new file mode 100644
index 00000000..1e97ea54
--- /dev/null
+++ b/lib/Genesis/CI/Propagation.pm
@@ -0,0 +1,91 @@
+package Genesis::CI::Propagation;
+
+use strict;
+use warnings;
+
+# compute_propagation_targets - determine which envs receive files directly {{{
+#
+# Pure function: no git, no IO.  Given a DAG topology, per-env
+# propagation diffs, and (optionally) per-env deploy diffs, returns
+# which environments are direct entry points for propagation and
+# which files each receives.
+#
+# Two diffs per env:
+#   - propagation_diff: files on control HEAD that aren't yet on this
+#     env's branch.  Used to decide what to copy when the env is an
+#     entry point.
+#   - deploy_diff: files on control HEAD that haven't yet been
+#     DEPLOYED from this env (branch may have them, but exodus
+#     audit shows an older commit).  Used to detect ancestors that
+#     have in-flight propagations — descendants must wait.
+#
+# An environment is a direct entry point when:
+#   1. Its propagation_diff is non-empty, AND
+#   2. NONE of its propagation_diff files overlap with any ancestor's
+#      deploy_diff (i.e., no ancestor is sitting on an undeployed copy
+#      of the same file).
+#
+# This keeps commits travelling as a unit: a file can't cascade past
+# an ancestor that has received it on-branch but not yet deployed it.
+#
+# When deploy_diff is omitted, it falls back to propagation_diff —
+# preserving the original single-diff behaviour for callers that
+# aren't yet deployment-aware.
+#
+# Args (named):
+#   dag_order         => \@ordered_env_names   (topologically sorted)
+#   parent_of         => \%parent_map          (env => parent_env or undef)
+#   env_changed       => \%propagation_diff    (env => \@files to copy)
+#   env_undeployed    => \%deploy_diff         (env => \@files pending deploy)
+#                                               (optional; defaults to env_changed)
+#   scope             => \@scoped_env_names    (optional: subset to consider)
+#
+# Returns: hashref  { env_name => \@files_to_propagate }
+#          Only entry point envs appear in the result.
+sub compute_propagation_targets {
+	my (%args) = @_;
+
+	my @dag_order      = @{$args{dag_order}      || []};
+	my %parent_of      = %{$args{parent_of}      || {}};
+	my %env_changed    = %{$args{env_changed}    || {}};
+	my %env_undeployed = %{$args{env_undeployed} || \%env_changed};
+	my @scope          = @{$args{scope}          || \@dag_order};
+
+	my %in_scope = map { $_ => 1 } @scope;
+
+	my %targets;
+
+	for my $env_name (@scope) {
+		next unless $env_changed{$env_name};
+		next unless @{$env_changed{$env_name}};
+
+		my %my_files = map { $_ => 1 } @{$env_changed{$env_name}};
+
+		# Walk up the DAG checking for overlap with any ancestor's
+		# undeployed set (what the ancestor is still sitting on).
+		my $has_ancestor_overlap = 0;
+		my $ancestor = $parent_of{$env_name};
+		while ($ancestor) {
+			if ($env_undeployed{$ancestor} && @{$env_undeployed{$ancestor}}) {
+				for my $f (@{$env_undeployed{$ancestor}}) {
+					if ($my_files{$f}) {
+						$has_ancestor_overlap = 1;
+						last;
+					}
+				}
+			}
+			last if $has_ancestor_overlap;
+			$ancestor = $parent_of{$ancestor};
+		}
+
+		unless ($has_ancestor_overlap) {
+			$targets{$env_name} = $env_changed{$env_name};
+		}
+	}
+
+	return \%targets;
+}
+
+# }}}
+
+1;
diff --git a/lib/Genesis/CI/Provider.pm b/lib/Genesis/CI/Provider.pm
new file mode 100644
index 00000000..2d487854
--- /dev/null
+++ b/lib/Genesis/CI/Provider.pm
@@ -0,0 +1,223 @@
+package Genesis::CI::Provider;
+use strict;
+use warnings;
+
+use Genesis;
+use Getopt::Long qw/GetOptionsFromArray/;
+
+### Class Methods {{{
+
+# new - builder for creating new instance of derived class based on config {{{
+sub new {
+	my ($class, %config) = @_;
+	bug("%s->new is calling %s->new illegally", $class, __PACKAGE__)
+		if $class ne __PACKAGE__;
+
+	my $type = $config{type} || 'manual';
+
+	my $obj;
+	if ($type eq 'concourse') {
+		require Genesis::CI::Provider::Concourse;
+		$obj = Genesis::CI::Provider::Concourse->new(%config);
+	} elsif ($type eq 'github-actions') {
+		require Genesis::CI::Provider::GithubActions;
+		$obj = Genesis::CI::Provider::GithubActions->new(%config);
+	} elsif ($type eq 'manual') {
+		require Genesis::CI::Provider::Manual;
+		$obj = Genesis::CI::Provider::Manual->new(%config);
+	} else {
+		bail("Unknown CI provider type '%s'. Valid types: concourse, github-actions, manual", $type);
+	}
+
+	my @errors = $obj->validate_config;
+	bail(
+		"Invalid CI provider configuration for type '%s':\n%s",
+		$type, join("\n", map { "  - $_" } @errors)
+	) if @errors;
+
+	return $obj;
+}
+
+# }}}
+# init - builder for creating new instance based on CLI options {{{
+sub init {
+	my ($class, %opts) = @_;
+	bug("%s->init is calling %s->init illegally", $class, __PACKAGE__)
+		if $class ne __PACKAGE__;
+
+	my $type = $opts{'ci-provider'} || 'manual';
+
+	if ($type eq 'concourse') {
+		require Genesis::CI::Provider::Concourse;
+		return Genesis::CI::Provider::Concourse->init(%opts);
+	} elsif ($type eq 'github-actions') {
+		require Genesis::CI::Provider::GithubActions;
+		return Genesis::CI::Provider::GithubActions->init(%opts);
+	} elsif ($type eq 'manual') {
+		require Genesis::CI::Provider::Manual;
+		return Genesis::CI::Provider::Manual->init(%opts);
+	} else {
+		bail("Unknown CI provider type '%s'. Valid types: concourse, github-actions, manual", $type);
+	}
+}
+
+# }}}
+# parse_opts - two-pass extraction: first --ci-provider, then provider-specific flags {{{
+sub parse_opts {
+	my ($class, $args, $ci_opts) = @_;
+	Getopt::Long::Configure(qw(pass_through permute no_auto_abbrev no_ignore_case bundling));
+
+	# Stop at '--'
+	my $opt_args = [];
+	while (scalar(@$args) && $args->[0] ne '--') {
+		push @$opt_args, shift @$args;
+	}
+
+	# First pass: extract --ci-provider
+	GetOptionsFromArray($opt_args, $ci_opts, qw/ci-provider=s/);
+	my $type = $ci_opts->{'ci-provider'};
+
+	# Second pass: extract provider-specific flags
+	my @extra_opts;
+	if (!$type || $type eq 'manual') {
+		require Genesis::CI::Provider::Manual;
+		@extra_opts = Genesis::CI::Provider::Manual->opts();
+	} elsif ($type eq 'concourse') {
+		require Genesis::CI::Provider::Concourse;
+		@extra_opts = Genesis::CI::Provider::Concourse->opts();
+	} elsif ($type eq 'github-actions') {
+		require Genesis::CI::Provider::GithubActions;
+		@extra_opts = Genesis::CI::Provider::GithubActions->opts();
+	} else {
+		bail("Unknown CI provider type '%s'. Valid types: concourse, github-actions, manual", $type);
+	}
+
+	GetOptionsFromArray($opt_args, $ci_opts, @extra_opts) if @extra_opts;
+
+	# Return non-option args to $args
+	while (scalar(@$opt_args)) { unshift @$args, pop @$opt_args }
+
+	return 1;
+}
+
+# }}}
+# opts_slot - key name for this handler's parsed options in $COMMAND_OPTIONS {{{
+sub opts_slot { 'ci_provider' }
+
+# }}}
+# opts - base class has no options of its own {{{
+sub opts {
+	qw//;
+}
+
+# }}}
+# opts_help - aggregate usage docs from all providers {{{
+sub opts_help {
+	my ($class, %config) = @_;
+	bug("%s->opts_help is calling %s->opts_help illegally", $class, __PACKAGE__)
+		if $class ne __PACKAGE__;
+
+	require Genesis::CI::Provider::Concourse;
+	require Genesis::CI::Provider::GithubActions;
+	require Genesis::CI::Provider::Manual;
+
+	$config{type_default_msg} ||= '(optional, defaults to "manual")';
+	$config{valid_types}      ||= [qw(concourse github-actions manual)];
+
+	<<EOF;
+CI PROVIDERS
+
+Genesis can configure a CI/CD pipeline for your deployment repository.
+Each provider type requires its own set of options.
+
+  General CI Provider Options:
+
+    --ci-provider <type> $config{type_default_msg}
+        The type of CI provider to configure.  Valid types:
+        concourse, github-actions, manual.
+
+${\Genesis::CI::Provider::Concourse->opts_help(%config)
+}${\Genesis::CI::Provider::GithubActions->opts_help(%config)
+}${\Genesis::CI::Provider::Manual->opts_help(%config)
+}
+EOF
+}
+
+# }}}
+# }}}
+### Instance Methods {{{
+
+# label - human-readable name for this provider {{{
+sub label {
+	$_[0]->{label} // 'CI Provider';
+}
+
+# }}}
+# config - returns hash for .genesis/config ci.provider section (abstract) {{{
+sub config {
+	my ($self) = @_;
+	bug("Abstract Method: %s class must define 'config'", ref($self));
+}
+
+# }}}
+# check_prereqs - returns 1 if toolchain is present, 0 + error() if not {{{
+sub check_prereqs {
+	return 1;
+}
+
+# }}}
+# validate_config - check stored config fields; returns list of error strings {{{
+#
+# Called by Provider->new after the subclass object is constructed.
+# Subclasses override this to assert that all required fields are present and
+# well-formed.  Returning an empty list means the config is valid.
+# No network calls should be made here — this is a fast, local check only.
+sub validate_config {
+	return ();
+}
+
+# }}}
+# interactive_wizard - prompt the user for provider config interactively (abstract) {{{
+sub interactive_wizard {
+	my ($self, $top) = @_;
+	bug("Abstract Method: %s class must define 'interactive_wizard'", ref($self));
+}
+
+# }}}
+# }}}
+
+1;
+
+=head1 NAME
+
+Genesis::CI::Provider - CI provider factory and base class
+
+=head1 DESCRIPTION
+
+Genesis::CI::Provider is the factory and abstract base class for CI provider
+configuration management.  It follows the same pattern as Genesis::Kit::Provider.
+
+Concrete subclasses: Concourse, GithubActions, Manual.
+
+=head1 SYNOPSIS
+
+  # Parse CLI opts (two-pass: --ci-provider first, then provider-specific)
+  my %ci_opts;
+  Genesis::CI::Provider->parse_opts(\@ARGV, \%ci_opts);
+
+  # Build provider object from CLI opts
+  my $provider = Genesis::CI::Provider->init(%ci_opts);
+
+  # Get config hash for .genesis/config ci.provider section
+  my %cfg = $provider->config();
+
+  # Reconstruct from stored config
+  my $provider = Genesis::CI::Provider->new(type => 'concourse', target => 'prod');
+
+=head1 SEE ALSO
+
+Genesis::Kit::Provider, Genesis::CI::Compiler
+
+=cut
+
+# vim: ts=2 sw=2 sts=2 noet fdm=marker foldlevel=1
diff --git a/lib/Genesis/CI/Provider/Concourse.pm b/lib/Genesis/CI/Provider/Concourse.pm
new file mode 100644
index 00000000..2a186587
--- /dev/null
+++ b/lib/Genesis/CI/Provider/Concourse.pm
@@ -0,0 +1,407 @@
+package Genesis::CI::Provider::Concourse;
+use strict;
+use warnings;
+
+use base 'Genesis::CI::Provider';
+use Genesis;
+use Genesis::UI;
+
+use POSIX qw(mktime);
+
+use constant {
+	DEFAULT_TEAM => 'main',
+};
+
+### Class Methods {{{
+
+# init - create a new Concourse provider from CLI options {{{
+#
+# Two modes:
+#   1. Existing target: --ci-target <name> (looks up url/team/insecure
+#      from ~/.flyrc)
+#   2. New target: --ci-url <url> --ci-team <team> [--ci-insecure]
+#      [--ci-target <name>]  (derives target name if not specified)
+#
+sub init {
+	my ($class, %opts) = @_;
+
+	my $has_target = $opts{'ci-target'};
+	my $has_new    = $opts{'ci-url'} || $opts{'ci-team'} || $opts{'ci-insecure'};
+
+	if ($has_target) {
+		# Check if the target already exists in flyrc
+		my $flyrc = "$ENV{HOME}/.flyrc";
+		my $entry;
+		if (-f $flyrc) {
+			my $data = load_yaml_file($flyrc);
+			$entry = $data->{targets}{$opts{'ci-target'}}
+				if ref($data) eq 'HASH' && ref($data->{targets}) eq 'HASH';
+		}
+
+		if ($entry) {
+			# Existing target — reject conflicting flags
+			bail(
+				"Target '%s' already exists in ~/.flyrc.\n".
+				"  Cannot combine --ci-target with --ci-url, --ci-team, ".
+				"or --ci-insecure when the target already exists.",
+				$opts{'ci-target'}
+			) if $has_new;
+
+			return $class->new(
+				type     => 'concourse',
+				target   => $opts{'ci-target'},
+				url      => $entry->{api},
+				team     => $entry->{team} || DEFAULT_TEAM,
+				insecure => $entry->{insecure} ? 1 : 0,
+			);
+		}
+
+		# Target name provided but doesn't exist yet — fall through
+		# to new-target creation below (--ci-url and --ci-team required)
+	}
+
+	# New target: --ci-url and --ci-team are required; --ci-target is
+	# an optional name override (derived from url/team if omitted).
+	bail(
+		"Concourse CI provider requires --ci-target (existing fly target) ".
+		"or --ci-url and --ci-team (new target)"
+	) unless $opts{'ci-url'} && $opts{'ci-team'};
+
+	my $target = $opts{'ci-target'}
+		// _derive_target_name($opts{'ci-url'}, $opts{'ci-team'});
+
+	return $class->new(
+		type     => 'concourse',
+		target   => $target,
+		url      => $opts{'ci-url'},
+		team     => $opts{'ci-team'},
+		insecure => $opts{'ci-insecure'} ? 1 : 0,
+	);
+}
+
+# }}}
+# new - create a Concourse provider from stored config {{{
+sub new {
+	my ($class, %config) = @_;
+	$class = ref($class) || $class;
+	bless({
+		label           => 'Concourse',
+		target          => $config{target},
+		url             => $config{url},
+		team            => $config{team}            || DEFAULT_TEAM,
+		insecure        => $config{insecure}        ? 1 : 0,
+		min_fly_version => $config{min_fly_version} || undef,
+	}, $class);
+}
+
+# }}}
+# check_prereqs - verify fly CLI is present and meets min version {{{
+sub check_prereqs {
+	my ($self) = @_;
+
+	my ($fly_path) = run({ stderr => 0 }, 'type -p fly');
+	chomp($fly_path //= '');
+	unless ($fly_path) {
+		error(
+			"Concourse CI provider requires the #C{fly} CLI but it was not found in PATH.\n".
+			"  Download it from your Concourse server's home page or:\n".
+			"    #C{<concourse-url>/api/v1/cli?arch=amd64&platform=<linux|darwin|windows>}"
+		);
+		return 0;
+	}
+
+	if ($self->{min_fly_version}) {
+		my ($ver_out) = run({ stderr => 0 }, 'fly --version');
+		chomp($ver_out //= '');
+		if ($ver_out && $ver_out =~ /^(\d+)\.(\d+)\.(\d+)/) {
+			my @got = ($1+0, $2+0, $3+0);
+			my @min = map { $_ + 0 } split(/\./, $self->{min_fly_version}, 3);
+			push @min, 0 while @min < 3;
+			for my $i (0..2) {
+				if ($got[$i] < ($min[$i]//0)) {
+					error(
+						"Concourse CI provider requires fly >= %s but found %s.\n".
+						"  Upgrade fly from your Concourse server.",
+						$self->{min_fly_version}, $ver_out
+					);
+					return 0;
+				}
+				last if $got[$i] > ($min[$i]//0);
+			}
+		}
+	}
+
+	return 1;
+}
+
+# }}}
+# opts - Getopt::Long spec for Concourse-specific CLI flags {{{
+sub opts {
+	qw/
+		ci-target=s
+		ci-url=s
+		ci-team=s
+		ci-insecure
+	/;
+}
+
+# }}}
+# opts_help - usage documentation for Concourse options {{{
+sub opts_help {
+	my ($class, %config) = @_;
+	return '' unless grep { $_ eq 'concourse' } @{$config{valid_types} || []};
+
+	<<'EOF';
+  CI Provider `concourse`:
+
+    Use an existing fly target:
+
+    --ci-target <name>
+        An existing Concourse target name from ~/.flyrc.  URL, team, and
+        TLS settings are read from the target.  Cannot be combined with
+        --ci-url, --ci-team, or --ci-insecure when the target exists.
+
+    Or specify a new target:
+
+    --ci-url <url> (required for new targets)
+        The Concourse server URL (e.g. https://ci.example.com).
+
+    --ci-team <name> (required for new targets)
+        The Concourse team name.
+
+    --ci-target <name> (optional for new targets)
+        Override the fly target name.  Defaults to a name derived from
+        the URL and team (e.g. ci/platform).
+
+    --ci-insecure (optional flag)
+        Skip TLS certificate verification when connecting to the Concourse
+        server.  Equivalent to fly's --skip-ssl-validation flag.
+
+    When neither --ci-target nor --ci-url is provided, an interactive
+    wizard guides target selection or creation.
+
+EOF
+}
+
+# }}}
+# }}}
+### Instance Methods {{{
+
+# label - human-readable name for this provider {{{
+sub label { 'Concourse' }
+
+# }}}
+# validate_config - assert required fields are present in stored config {{{
+sub validate_config {
+	my ($self) = @_;
+	my @errors;
+	push @errors, "'target' is required for the Concourse provider"
+		unless $self->{target};
+	push @errors, "'url' must begin with http:// or https://"
+		if $self->{url} && $self->{url} !~ m{^https?://};
+	return @errors;
+}
+
+# }}}
+# config - returns hash for .genesis/config ci.provider section {{{
+sub config {
+	my ($self) = @_;
+	my %cfg = (type => 'concourse');
+	$cfg{target}   = $self->{target}   if defined $self->{target};
+	$cfg{url}      = $self->{url}      if defined $self->{url};
+	$cfg{team}     = $self->{team}     if defined $self->{team} && $self->{team} ne DEFAULT_TEAM;
+	$cfg{insecure} = 1                 if $self->{insecure};
+	return %cfg;
+}
+
+# }}}
+# interactive_wizard - select existing target or create a new one {{{
+sub interactive_wizard {
+	my ($self, $top) = @_;
+
+	my ($target, $url, $team, $insecure);
+
+	# --- Gather existing targets from fly targets + flyrc ---
+	my @fly_targets = _load_fly_targets();
+
+	if (@fly_targets) {
+		# Compute column widths for aligned display
+		my ($w_name, $w_api, $w_team) = (0, 0, 0);
+		for (@fly_targets) {
+			$w_name = length($_->{name}) if length($_->{name}) > $w_name;
+			$w_api  = length($_->{api})  if length($_->{api})  > $w_api;
+			$w_team = length($_->{team}) if length($_->{team}) > $w_team;
+		}
+
+		my @choices = map {{
+			value   => $_->{name},
+			label   => sprintf("#C{%-${w_name}s}  %-${w_api}s  %-${w_team}s  %s%s",
+				$_->{name}, $_->{api}, $_->{team},
+				$_->{insecure} ? "#Yi{insecure}" : "#G{secure}  ",
+				$_->{expired}  ? "  #R{EXPIRED!}" : ""),
+			summary => $_->{name},
+		}} @fly_targets;
+
+		push @choices, { separator => 1 };
+		push @choices, {
+			value   => '__new__',
+			label   => '#Yi{Create a new Concourse target}',
+			summary => '(new target)',
+		};
+
+		my $selection = new_prompt_for_choice(
+			header      => "Select a Concourse target:",
+			choices     => \@choices,
+			default     => $self->{target},
+			description => "target",
+		);
+
+		if ($selection ne '__new__') {
+			my ($selected) = grep { $_->{name} eq $selection } @fly_targets;
+			$target   = $selected->{name};
+			$url      = $selected->{api};
+			$team     = $selected->{team};
+			$insecure = $selected->{insecure};
+
+			# Re-authenticate if the token has expired
+			if ($selected->{expired}) {
+				info "\nRe-authenticating expired target #C{%s}...\n", $target;
+				my @cmd = ('fly', '-t', $target, 'login', '-n', $team);
+				push @cmd, '-k' if $insecure;
+				run({ interactive => 1,
+					  onfailure   => "fly login failed for target '$target'" },
+					@cmd);
+			}
+		}
+	}
+
+	# Create a new target: prompt for details and run fly login
+	unless ($target) {
+		$url = prompt_for_line(undef,
+			"Concourse URL (e.g. https://ci.example.com): ", '');
+		bail("A Concourse URL is required.") unless $url && $url =~ m{^https?://};
+
+		$team = prompt_for_line(undef,
+			sprintf("Team name [%s]: ", DEFAULT_TEAM), DEFAULT_TEAM);
+		$team = DEFAULT_TEAM unless $team && $team =~ /\S/;
+
+		$insecure = prompt_for_boolean(
+			"Skip TLS certificate verification? [y|n] ", 0);
+
+		$target = _derive_target_name($url, $team);
+
+		info "\nLogging in to #C{%s} as team #C{%s} (target: #C{%s})...\n",
+			$url, $team, $target;
+		my @cmd = ('fly', '-t', $target, 'login',
+			'-c', $url, '-n', $team);
+		push @cmd, '-k' if $insecure;
+		run({ interactive => 1,
+			  onfailure   => "fly login failed for target '$target'" },
+			@cmd);
+	}
+
+	return $self->new(
+		type     => 'concourse',
+		target   => $target,
+		url      => $url,
+		team     => $team,
+		insecure => $insecure ? 1 : 0,
+	);
+}
+
+# }}}
+
+# _load_fly_targets - merge fly targets output with flyrc insecure flags {{{
+sub _load_fly_targets {
+	my @targets;
+
+	my $flyrc = "$ENV{HOME}/.flyrc";
+	my %flyrc_data;
+	if (-f $flyrc) {
+		my $data = load_yaml_file($flyrc);
+		if (ref($data) eq 'HASH' && ref($data->{targets}) eq 'HASH') {
+			%flyrc_data = %{$data->{targets}};
+		}
+	}
+
+	my ($fly_out) = run({ stderr => '/dev/null' },
+		'fly targets --print-table-headers');
+	if ($fly_out && $fly_out =~ /\S/) {
+		my @lines = split /\n/, $fly_out;
+		my @rows = parse_fixed_width_table(@lines);
+		for my $row (@rows) {
+			my $name = $row->{name} // next;
+			my $flyrc_entry = $flyrc_data{$name} // {};
+			push @targets, {
+				name     => $name,
+				api      => $row->{url}  // '(unknown)',
+				team     => $row->{team} // DEFAULT_TEAM,
+				insecure => $flyrc_entry->{insecure} ? 1 : 0,
+				expired  => _token_expired($row->{expiry}),
+			};
+		}
+	}
+	return @targets;
+}
+
+# }}}
+# _derive_target_name - build a target name from url and team {{{
+sub _derive_target_name {
+	my ($url, $team) = @_;
+	# https://ci.example.com → ci
+	# https://pipes.scalecf.net → pipes
+	(my $host = $url) =~ s{^https?://}{}; $host =~ s{[:/].*}{};
+	my $subdomain = (split /\./, $host)[0] // $host;
+	return $team eq 'main' ? $subdomain : "$subdomain/$team";
+}
+
+# }}}
+# _token_expired - check if a fly targets expiry string is in the past {{{
+my %_months = (
+	Jan => 0, Feb => 1, Mar => 2, Apr => 3, May => 4,  Jun => 5,
+	Jul => 6, Aug => 7, Sep => 8, Oct => 9, Nov => 10, Dec => 11,
+);
+sub _token_expired {
+	my ($expiry_str) = @_;
+	return 0 unless $expiry_str && $expiry_str =~ /\S/;
+
+	# fly targets format: "Sat, 08 Feb 2025 18:53:16 UTC"
+	if ($expiry_str =~ /(\d{2})\s+(\w{3})\s+(\d{4})\s+(\d{2}):(\d{2}):(\d{2})\s+UTC/) {
+		my ($day, $mon, $year, $hour, $min, $sec) = ($1, $2, $3, $4, $5, $6);
+		return 0 unless defined $_months{$mon};
+		my $exp = eval {
+			local $ENV{TZ} = 'UTC';
+			POSIX::mktime($sec, $min, $hour, $day, $_months{$mon}, $year - 1900);
+		};
+		return 0 unless $exp;
+		return $exp < time() ? 1 : 0;
+	}
+	return 0;
+}
+
+# }}}
+# }}}
+
+1;
+
+=head1 NAME
+
+Genesis::CI::Provider::Concourse - Concourse CI provider for Genesis repo-init
+
+=head1 DESCRIPTION
+
+Manages Concourse-specific CI configuration in .genesis/config ci.provider.
+
+=head1 SYNOPSIS
+
+  my $p = Genesis::CI::Provider::Concourse->init(
+    'ci-target'   => 'prod',
+    'ci-team'     => 'platform',
+    'ci-insecure' => 0,
+  );
+  my %cfg = $p->config;
+  # { type => 'concourse', target => 'prod', team => 'platform' }
+
+=cut
+
+# vim: ts=2 sw=2 sts=2 noet fdm=marker foldlevel=1
diff --git a/lib/Genesis/CI/Provider/GithubActions.pm b/lib/Genesis/CI/Provider/GithubActions.pm
new file mode 100644
index 00000000..540849af
--- /dev/null
+++ b/lib/Genesis/CI/Provider/GithubActions.pm
@@ -0,0 +1,156 @@
+package Genesis::CI::Provider::GithubActions;
+use strict;
+use warnings;
+
+use base 'Genesis::CI::Provider';
+use Genesis;
+use Genesis::UI;
+
+use constant {
+	DEFAULT_BRANCH => 'main',
+};
+
+### Class Methods {{{
+
+# init - create a new GithubActions provider from CLI options {{{
+sub init {
+	my ($class, %opts) = @_;
+
+	bail("GitHub Actions CI provider requires --ci-github-repo (format: org/repo)")
+		unless $opts{'ci-github-repo'};
+
+	bail("--ci-github-repo must be in 'org/repo' format")
+		unless $opts{'ci-github-repo'} =~ m{^[^/]+/[^/]+$};
+
+	$class->new(
+		type   => 'github-actions',
+		repo   => $opts{'ci-github-repo'},
+		branch => $opts{'ci-github-branch'} || DEFAULT_BRANCH,
+	);
+}
+
+# }}}
+# new - create a GithubActions provider from stored config {{{
+sub new {
+	my ($class, %config) = @_;
+	bless({
+		label  => 'GitHub Actions',
+		repo   => $config{repo},
+		branch => $config{branch} || DEFAULT_BRANCH,
+	}, $class);
+}
+
+# }}}
+# opts - Getopt::Long spec for GitHub Actions-specific CLI flags {{{
+sub opts {
+	qw/
+		ci-github-repo=s
+		ci-github-branch=s
+	/;
+}
+
+# }}}
+# opts_help - usage documentation for GitHub Actions options {{{
+sub opts_help {
+	my ($class, %config) = @_;
+	return '' unless grep { $_ eq 'github-actions' } @{$config{valid_types} || []};
+
+	<<'EOF';
+  CI Provider `github-actions`:
+
+    --ci-github-repo <org/repo> (required)
+        The GitHub repository to configure workflows for, in "org/repo"
+        format (e.g. "myorg/my-deployment-repo").
+
+    --ci-github-branch <branch> (optional, defaults to "main")
+        The branch that workflow dispatch events and pushes will trigger
+        pipeline runs on.  Defaults to "main".
+
+EOF
+}
+
+# }}}
+# }}}
+### Instance Methods {{{
+
+# label - human-readable name for this provider {{{
+sub label { 'GitHub Actions' }
+
+# }}}
+# validate_config - assert required fields are present in stored config {{{
+sub validate_config {
+	my ($self) = @_;
+	my @errors;
+	push @errors, "'repo' is required for the GitHub Actions provider"
+		unless $self->{repo};
+	push @errors, "'repo' must be in 'org/repo' format"
+		if $self->{repo} && $self->{repo} !~ m{^[^/]+/[^/]+$};
+	return @errors;
+}
+
+# }}}
+# config - returns hash for .genesis/config ci.provider section {{{
+sub config {
+	my ($self) = @_;
+	my %cfg = (type => 'github-actions');
+	$cfg{repo}   = $self->{repo}   if defined $self->{repo};
+	$cfg{branch} = $self->{branch} if defined $self->{branch} && $self->{branch} ne DEFAULT_BRANCH;
+	return %cfg;
+}
+
+# }}}
+# interactive_wizard - prompt user for GitHub Actions configuration {{{
+sub interactive_wizard {
+	my ($self, $top, %opts) = @_;
+
+	my $repo = $opts{'ci-github-repo'};
+	unless ($repo && $repo =~ m{^[^/]+/[^/]+$}) {
+		$repo = prompt_for_line(undef,
+			"GitHub repository (org/repo format): ", '');
+		bail("GitHub Actions CI provider requires a repository")
+			unless $repo && $repo =~ /\S/;
+		bail("Repository must be in 'org/repo' format")
+			unless $repo =~ m{^[^/]+/[^/]+$};
+	}
+
+	my $branch;
+	if (exists $opts{'ci-github-branch'}) {
+		$branch = $opts{'ci-github-branch'} || DEFAULT_BRANCH;
+	} else {
+		$branch = prompt_for_line(undef,
+			sprintf("Default branch [%s]: ", DEFAULT_BRANCH), DEFAULT_BRANCH);
+		$branch = DEFAULT_BRANCH unless $branch && $branch =~ /\S/;
+	}
+
+	return $self->new(
+		type   => 'github-actions',
+		repo   => $repo,
+		branch => $branch,
+	);
+}
+
+# }}}
+# }}}
+
+1;
+
+=head1 NAME
+
+Genesis::CI::Provider::GithubActions - GitHub Actions CI provider for Genesis repo-init
+
+=head1 DESCRIPTION
+
+Manages GitHub Actions-specific CI configuration in .genesis/config ci.provider.
+
+=head1 SYNOPSIS
+
+  my $p = Genesis::CI::Provider::GithubActions->init(
+    'ci-github-repo'   => 'myorg/my-deployment',
+    'ci-github-branch' => 'main',
+  );
+  my %cfg = $p->config;
+  # { type => 'github-actions', repo => 'myorg/my-deployment' }
+
+=cut
+
+# vim: ts=2 sw=2 sts=2 noet fdm=marker foldlevel=1
diff --git a/lib/Genesis/CI/Provider/Manual.pm b/lib/Genesis/CI/Provider/Manual.pm
new file mode 100644
index 00000000..a829e2b9
--- /dev/null
+++ b/lib/Genesis/CI/Provider/Manual.pm
@@ -0,0 +1,79 @@
+package Genesis::CI::Provider::Manual;
+use strict;
+use warnings;
+
+use base 'Genesis::CI::Provider';
+use Genesis;
+
+### Class Methods {{{
+
+# init - create a Manual provider (no options needed) {{{
+sub init {
+	my ($class, %opts) = @_;
+	$class->new(type => 'manual');
+}
+
+# }}}
+# new - create a Manual provider {{{
+sub new {
+	my ($class, %config) = @_;
+	bless({ label => 'Manual' }, $class);
+}
+
+# }}}
+# opts_help - usage documentation for Manual provider {{{
+sub opts_help {
+	my ($class, %config) = @_;
+	return '' unless grep { $_ eq 'manual' } @{$config{valid_types} || []};
+
+	<<'EOF';
+  CI Provider `manual`:
+
+    This provider type disables automated pipeline management.  Genesis
+    will scaffold the repository structure but no CI system will be
+    automatically configured.  Use this when you manage your pipeline
+    entirely outside of Genesis or through a separate process.
+
+    No additional options are required.
+
+EOF
+}
+
+# }}}
+# }}}
+### Instance Methods {{{
+
+# label - human-readable name for this provider {{{
+sub label { 'Manual' }
+
+# }}}
+# config - returns hash for .genesis/config ci.provider section {{{
+sub config {
+	my ($self) = @_;
+	return (type => 'manual');
+}
+
+# }}}
+# interactive_wizard - no prompts needed for Manual {{{
+sub interactive_wizard {
+	my ($self, $top) = @_;
+	return $self->new(type => 'manual');
+}
+
+# }}}
+# }}}
+
+1;
+
+=head1 NAME
+
+Genesis::CI::Provider::Manual - Manual (no-automation) CI provider for Genesis repo-init
+
+=head1 DESCRIPTION
+
+A no-op CI provider for repositories that manage their pipelines manually.
+Takes no additional options and stores only C<< type => 'manual' >> in config.
+
+=cut
+
+# vim: ts=2 sw=2 sts=2 noet fdm=marker foldlevel=1
diff --git a/lib/Genesis/Commands.pm b/lib/Genesis/Commands.pm
index 4b245751..c38807af 100644
--- a/lib/Genesis/Commands.pm
+++ b/lib/Genesis/Commands.pm
@@ -177,6 +177,12 @@ sub define_command { # {{{
 	};
 
 	$PROPS{$name} = {%$default_props, %$props};
+
+	# extended_handlers implies option_passthrough: the main parser
+	# must leave unrecognised flags in @args for the handlers to claim.
+	if ($PROPS{$name}{extended_handlers}) {
+		$PROPS{$name}{option_passthrough} = 1;
+	}
 	my $fn_require = '';
 	if (ref($fn) ne "CODE") {
 		if (defined($fn)) {
@@ -282,6 +288,31 @@ sub parse_options { # {{{
 
 	my $args = shift;
 	my $args_copy = [@$args];
+
+	# Validate extended handlers once, up front, before any option
+	# parsing.  This is the single gateway for both command execution
+	# and help rendering (prepare_command always calls parse_options
+	# first), so we validate here rather than duplicating in
+	# command_help.  Each handler class must be loadable and must
+	# implement the required contract methods.
+	if (my $handlers = $PROPS{$COMMAND}{extended_handlers}) {
+		for my $class (@$handlers) {
+			(my $file = $class) =~ s|::|/|g;
+			eval { require "$file.pm" };
+			bail(
+				"Extended handler #C{%s} for command #C{%s} could not be loaded:\n%s",
+				$class, $COMMAND, $@
+			) if $@;
+			for my $method (qw(parse_opts opts_help opts_slot)) {
+				bail(
+					"Extended handler #C{%s} for command #C{%s} does not implement ".
+					"the required #C{%s} method.",
+					$class, $COMMAND, $method
+				) unless $class->can($method);
+			}
+		}
+	}
+
 	my @base_spec = keys %{({map {@$_} @global_options[0..$PROPS{$COMMAND}{option_group}]})};
 
 	my @opts_spec = (
@@ -328,6 +359,31 @@ sub parse_options { # {{{
 	shift @$args if ($args->[0]||'') eq '--';
 	@COMMAND_ARGS = (@$args);
 
+	# Extended handlers: each registered handler class gets a chance to
+	# consume its flags from @COMMAND_ARGS and populate a slot in
+	# $COMMAND_OPTIONS.  Handlers run in declared order so each sees
+	# only what prior handlers left behind.  The classes were already
+	# required and validated at the top of this sub.
+	if (my $handlers = $PROPS{$COMMAND}{extended_handlers}) {
+		for my $class (@$handlers) {
+			my %slot;
+			$class->parse_opts(\@COMMAND_ARGS, \%slot);
+			$COMMAND_OPTIONS->{$class->opts_slot()} = \%slot;
+		}
+
+		# After all handlers have run, anything still looking like an
+		# option is unclaimed -- reject it the same way the main parser
+		# would without option_passthrough.
+		my @unknown = grep { /^-/ } @COMMAND_ARGS;
+		if (@unknown) {
+			command_usage(1, sprintf(
+				"Unknown option%s: %s",
+				@unknown > 1 ? 's' : '',
+				join(', ', @unknown)
+			));
+		}
+	}
+
 	# Extract Core options
 	$ENV{NOCOLOR}        = 'y' if defined($COMMAND_OPTIONS->{color}) && !delete($COMMAND_OPTIONS->{color});
 	$ENV{QUIET}          = 'y' if  delete($COMMAND_OPTIONS->{quiet});
@@ -650,8 +706,26 @@ sub command_usage { # {{{
 		$out .= "#i{To see only global options, use }#g{${\(humanize_bin)}} #y{--globals}\n";
 	}
 
-	# TODO: Integrate extended usage better than just dumping it at the end
-	if (ref($PROPS{$command}{extended_usage}) eq "CODE") {
+	# Extended usage: render help from registered handlers (preferred),
+	# or fall back to legacy extended_usage closure if no handlers are
+	# registered.
+	# Extended handlers were already required and validated in
+	# parse_options (which always runs before command_help via
+	# prepare_command).
+	if (my $handlers = $PROPS{$command}{extended_handlers}) {
+		my $extended_usage = '';
+		for my $class (@$handlers) {
+			my $help = $class->opts_help();
+			if ($help) {
+				$help =~ s/\s*$//s;
+				$extended_usage .= $help . "\n";
+			}
+		}
+		if ($extended_usage =~ /\S/) {
+			$out .= "\n#Wku{Extended Usage Information}\n";
+			$out .= "\n$extended_usage\n";
+		}
+	} elsif (ref($PROPS{$command}{extended_usage}) eq "CODE") {
 		my $extended_usage = $PROPS{$command}{extended_usage}->();
 		if ($extended_usage) {
 			$extended_usage =~ s/\s*$//s;
diff --git a/lib/Genesis/Commands/Env.pm b/lib/Genesis/Commands/Env.pm
index 2f525aba..ba58b5f9 100644
--- a/lib/Genesis/Commands/Env.pm
+++ b/lib/Genesis/Commands/Env.pm
@@ -71,60 +71,228 @@ sub create {
 	# check version prereqs
 	$kit->check_prereqs() or exit 86;
 
+	# Pipeline-aware repos require new environments to be created on the
+	# control branch so the topology is visible to pipeline tooling and
+	# the environment branch can be cut from the right point.
+	my $ci_configured = $top->ci_configured;
+	my $git;
+	if ($ci_configured) {
+		require Service::Git;
+		# track_branch so that prepare_branch's checkout to the env
+		# branch is restored back to control before we return.
+		$git = Service::Git->new('.', track_branch => 1);
+		my $control = Genesis::Top::DEFAULT_CONTROL_BRANCH();
+		my $branch = $git->current_branch;
+		if (!defined($branch) || $branch ne $control) {
+			bail(
+				"Creating environments requires being on the #C{%s} branch, ".
+				"but you are currently on #C{%s}.\n\n".
+				"    git checkout %s\n",
+				$control,
+				$branch // '<detached HEAD>',
+				$control
+			);
+		}
+
+		# Refresh env branches so branch_exists checks and reconciliation
+		# see teammate-created branches that aren't in the local clone yet.
+		unless (get_options->{'no-fetch'}) {
+			require Genesis::Commands::Pipelines;
+			Genesis::Commands::Pipelines::_fetch_pipeline_envs($top, $git);
+		}
+	}
+
 	# create the environment
 	info("\nSetting up new environment #C{$name} based on kit %s ...", $kit->id);
 	my $env = $top->create_env($name, $kit, %{get_options()});
 	bail "Failed to create environment $name" unless $env;
 
-	# Phase C: prompt for pipeline metadata when CI provider is configured
-	if ($top->config->has('ci.provider')) {
+	# Phase C: write pipeline metadata when CI provider is configured.
+	# Runs interactively when in a controlling terminal; honours --prior-env,
+	# --require-pr, and --manual flags for non-interactive (scripted) use.
+	if ($ci_configured) {
+		my $ci_type = $top->config->get('ci.provider.type') // 'unknown';
 		info(
-			"\n#G{Pipeline configuration} (ci.provider: #C{%s})\n",
-			$top->config->get('ci.provider')
+			"\n#G{Pipeline configuration} (ci provider: #C{%s})\n",
+			$ci_type
 		);
 
-		my $prior_env = prompt_for_line(
-			"Prior environment (leave blank if this is the pipeline entrypoint):",
-			"prior env",
-			"",
-		);
+		my %cli_opts = %{get_options()};
+		my $interactive = in_controlling_terminal;
 
-		my $require_pr = prompt_for_boolean(
-			"Require a PR gate before this environment deploys? [y|n]",
-			"n",
-		);
+		my $prior_env;
+		if (exists $cli_opts{'prior-env'}) {
+			$prior_env = $cli_opts{'prior-env'} // '';
+			if (length($prior_env)) {
+				my %known = map { $_->name => 1 } $top->envs();
+				bail(
+					"--prior-env '%s' does not match any environment in this repository.",
+					$prior_env
+				) unless $known{$prior_env};
+			}
+		} elsif ($interactive) {
+			my @existing = grep { $_->name ne $name } $top->envs();
+			if (@existing) {
+				my @env_names = map { $_->name } @existing;
+				my @choices = map {{ value => $_, label => $_ }} @env_names;
+				push @choices, { separator => 1 };
+				push @choices, {
+					value => '',
+					label => '#Yi{(none — pipeline entrypoint)}',
+					summary => '(entrypoint)',
+				};
+				$prior_env = new_prompt_for_choice(
+					header      => "Select prior environment (must succeed before this one):",
+					choices     => \@choices,
+					description => "environment",
+				);
+			} else {
+				$prior_env = '';
+				info("No other environments found — #C{%s} will be the pipeline entrypoint.", $name);
+			}
+		}
 
-		my $manual = prompt_for_boolean(
-			"Require a manual CI trigger before this environment deploys? [y|n]",
-			"n",
-		);
+		# --- require_pr / manual ---
+		my $require_pr;
+		if (exists $cli_opts{'require-pr'}) {
+			$require_pr = $cli_opts{'require-pr'} ? 1 : 0;
+		} elsif ($interactive) {
+			$require_pr = prompt_for_boolean(
+				"Require a PR gate before this environment deploys? [y|n]",
+				"n",
+			);
+		}
 
-		if (length($prior_env)) {
+		my $manual;
+		if (exists $cli_opts{manual}) {
+			$manual = $cli_opts{manual} ? 1 : 0;
+		} elsif ($interactive) {
+			$manual = prompt_for_boolean(
+				"Require a manual CI trigger before this environment deploys? [y|n]",
+				"n",
+			);
+		}
+
+		# Write pipeline: section when there is something to record.
+		# Entrypoints (no prior_env) can still carry manual: true.
+		if (length($prior_env // '') || $require_pr || $manual) {
 			my $pipeline_yaml = "  pipeline:\n";
-			$pipeline_yaml .= "    prior_env: $prior_env\n";
-			$pipeline_yaml .= "    require_pr: true\n" if $require_pr;
-			$pipeline_yaml .= "    manual: true\n"     if $manual;
+			$pipeline_yaml .= "    prior_env:    $prior_env\n" if length($prior_env // '');
+			$pipeline_yaml .= "    require_pr:   true\n"       if $require_pr;
+			$pipeline_yaml .= "    manual:       true\n"       if $manual;
 
 			my $file     = $env->path($env->file);
 			my $contents = slurp($file);
-			unless ($contents =~ /^  pipeline:/m) {
-				$contents =~ s/^(  env:\s+\S[^\n]*\n)/$1$pipeline_yaml/m;
-				mkfile_or_fail($file, $contents);
+
+			if ($contents =~ /^\s+pipeline:/m) {
+				info(
+					"#Y{Note}: pipeline section already present in #C{%s}, skipping injection.",
+					$env->file
+				);
+			} else {
+				my $injected = ($contents =~ s/^((\s+)env:\s+\S[^\n]*\n)/$1$pipeline_yaml/m);
+				if ($injected) {
+					mkfile_or_fail($file, $contents);
+					info("#G{Pipeline metadata written to} #C{%s}", $env->file);
+				} else {
+					warning(
+						"Could not inject pipeline metadata into #C{%s}: ".
+						"'env:' key not found at expected indentation. ".
+						"Add the pipeline section manually:\n%s",
+						$env->file, $pipeline_yaml
+					);
+				}
 			}
+		} else {
+			info(
+				"#C{%s} is a pipeline entrypoint with no gate flags — no pipeline section written.",
+				$name
+			);
+		}
+	}
 
-			info("#G{Pipeline metadata written to} #C{%s}", $env->file);
+	# Git operations: stage, commit, and create an environment branch.
+	# Only when CI is configured and --no-commit is not set.
+	my %cli_opts_git = %{get_options()};
+	if ($ci_configured) {
+		my $env_file = $env->file;
+		$git->add($git->prefixed($env_file));
+
+		if ($cli_opts_git{'no-commit'}) {
+			info "Skipping commit (#C{--no-commit} set); #C{%s} remains staged.", $env_file;
 		} else {
-			info("No prior environment — #C{%s} is a pipeline entrypoint, no pipeline section written.", $name);
+			my $message = $cli_opts_git{reason}
+				|| "Add environment $name";
+			$git->commit($message);
+
+			my $sha = $git->sha('HEAD', short => 1);
+			info "#G{Committed} #C{%s} -- %s", $sha // '<unknown>', $message;
+
+			# Create the environment branch (if needed) and reconcile it
+			# with the files this env depends on.  prepare_branch handles
+			# both the fresh-create case (cut from current commit, prune
+			# unrelated files) and the existing-branch case (add files
+			# that this env adds without disturbing files owned by other
+			# deployments sharing the same branch).
+			my $branch_existed = $git->branch_exists($name);
+			my ($added, $removed) = $env->prepare_branch;
+			info "Environment branch #C{%s} %s (%d added, %d removed).",
+				$name, $branch_existed ? 'reconciled' : 'created',
+				scalar(@$added), scalar(@$removed);
+
+			# For automated CI providers, the pipeline needs to be
+			# rebuilt to include a job for the new environment branch.
+			my $provider_type = $top->config->get('ci.provider.type') || 'manual';
+			if ($provider_type ne 'manual') {
+				if (in_controlling_terminal) {
+					if (prompt_for_boolean(
+						"Rebuild the CI pipeline to include #C{$name}? [y|n]", "y"
+					)) {
+						info "Rebuilding pipeline...";
+						# TODO: call genesis repipe equivalent
+						warning("Automated pipeline rebuild not yet implemented.  Run #C{genesis repipe} manually.");
+					}
+				} else {
+					info "Run #C{genesis repipe} to update the pipeline with the new environment.";
+				}
+			}
 		}
 	}
 
+	# Generate secrets.  Non-fatal — the env file, pipeline metadata, and
+	# git branch are already in place; secrets can be retried later with
+	# `genesis add-secrets` or will be generated at deploy time.
+	my $secrets_ok = eval { $env->add_secrets(verbose => 1, import => 1) };
+	if (!$secrets_ok) {
+		my $err = $@ || '';
+		$err =~ s/\s+$//;
+		warning(
+			"Secret generation incomplete for #C{%s}.%s\n".
+			"Run #C{genesis add-secrets '%s'} to retry, or secrets will be\n".
+			"generated at deploy time.",
+			$name,
+			$err ? "\n$err" : '',
+			$name
+		);
+	}
+
 	# let the user know
-	info(
-		"New environment $env->{name} provisioned!\n\n".
-		"To deploy, run this:\n\n".
-		"  #C{genesis deploy '%s'}\n",
-		$env->{name}
-	);
+	if ($ci_configured && !$cli_opts_git{'no-commit'}) {
+		info(
+			"\nNew environment #C{%s} provisioned!\n\n".
+			"To deploy, switch to the environment branch and run:\n\n".
+			"  #C{git checkout '%s'}\n".
+			"  #C{genesis deploy '%s'}\n",
+			$env->{name}, $name, $env->{name}
+		);
+	} else {
+		info(
+			"\nNew environment #C{%s} provisioned!\n\n".
+			"To deploy, run this:\n\n".
+			"  #C{genesis deploy '%s'}\n",
+			$env->{name}, $env->{name}
+		);
+	}
 }
 
 sub edit {
@@ -688,6 +856,95 @@ sub manifest {
 	output {raw => 1}, $content;
 }
 
+# _derive_deploy_reason - build a default --reason from the pipeline commit range {{{
+#
+# Reads the last successful deployment's `git.commit` from exodus and
+# compares it to the env branch HEAD.  If equal, this is a redeploy —
+# returns a "Redeploy of <sha>" stub.  If different, walks commits in
+# the `$last_deployed..$branch_head` range on the env branch and
+# delegates to _format_pipeline_reason to produce the audit string.
+#
+# Returns undef if vault is unreachable (caller falls back to the
+# operator-provided or default reason).
+sub _derive_deploy_reason {
+	my ($env, $git) = @_;
+
+	my $env_v = eval { $env->with_vault };
+	return undef unless $env_v;
+
+	my $dep = eval { $env_v->deployments->latest_successful };
+	my $last_deployed = $dep ? ($dep->lookup('git.commit') || '') : '';
+
+	my $branch_head = $git->sha($env->name);
+	return undef unless $branch_head;
+
+	if ($last_deployed && $last_deployed eq $branch_head) {
+		return sprintf("Redeploy of %s", $git->sha($branch_head, short => 1));
+	}
+
+	my $range = $last_deployed ? "$last_deployed..$branch_head" : $branch_head;
+
+	# Scope the history to commits that actually touched files this env
+	# depends on.  Without this filter, multi-deploy repos (e.g. bosh and
+	# vault sharing one env branch) would surface propagation markers
+	# from sibling deployments whose subjects are irrelevant to the deploy
+	# being reasoned about.
+	my @dep_files = $env->propagation_files;
+	my @lines = $git->log_subjects(
+		$range,
+		limit => 50,
+		paths => \@dep_files,
+	);
+
+	return _format_pipeline_reason(
+		\@lines,
+		sub { $git->sha($_[0], short => 1) },
+		sub {
+			my ($subject) = $git->log_subjects($_[0], limit => 1, format => '%s');
+			$subject //= '';
+			$subject =~ s/\s+$//;
+			return $subject;
+		},
+	);
+}
+
+# _format_pipeline_reason - pure formatter for the derived deploy reason {{{
+#
+# Inputs:
+#   \@log_lines   — output of `git log --format='%H %s'` for the range
+#   $short_sha    — callback: sha => abbreviated-sha (kept for API
+#                   compatibility; may be unused)
+#   $subject_of   — callback: sha => commit subject line
+#
+# Extracts `[pipeline] control@<sha>` markers from the env-branch log
+# lines, flips them into oldest-first order, and produces a reason
+# string made up of the control commit subjects (SHAs are omitted
+# because exodus already records `git.control_commit`).  For a single
+# commit the subject is returned verbatim; for multiple commits a
+# bulleted list is produced.  Returns undef if no markers are found.
+sub _format_pipeline_reason {
+	my ($log_lines, $short_sha, $subject_of) = @_;
+
+	my @controls;
+	for my $line (@{$log_lines || []}) {
+		next unless $line =~ /\[pipeline\] control\@([0-9a-f]+)/;
+		push @controls, $1;
+	}
+	return undef unless @controls;
+
+	@controls = reverse @controls;  # log is newest-first; reason reads oldest-first
+
+	my @subjects = map { $subject_of->($_) } @controls;
+
+	return $subjects[0] if @subjects == 1;
+
+	return join("\n",
+		sprintf("%d commits:", scalar @subjects),
+		map { "  - $_" } @subjects,
+	);
+}
+
+# }}}
 sub deploy {
 	option_defaults(
 		redact   => ! -t STDOUT,
@@ -697,10 +954,139 @@ sub deploy {
 	my ($env_name, $reason) = @_;
 
 	my %options = %{get_options()};
-	my @invalid_create_env_opts = grep {$options{$_}} (qw/fix dry-run fix-stemcells/);
+	my @invalid_create_env_opts = grep {$options{$_}} (qw/fix fix-stemcells/);
+
+	# --pull: explicitly requested, or implied by -F/--fix-checks unless --no-pull.
+	# Remove 'pull' from %options so it is not forwarded to $env->deploy().
+	my $do_pull;
+	if (exists $options{pull}) {
+		$do_pull = delete($options{pull}) ? 1 : 0;
+	} elsif ($options{'fix-checks'}) {
+		$do_pull = 1;
+	} else {
+		$do_pull = 0;
+	}
+
+	# --no-fetch: skip the pre-deploy env-branch refresh (offline use).
+	# Remove from %options so it is not forwarded to $env->deploy().
+	my $no_fetch = delete($options{'no-fetch'}) ? 1 : 0;
+
+	# When CI is configured, switch to the environment's branch and
+	# pull from remote BEFORE loading the env -- otherwise all the
+	# preflight work (cloud-config download, manifest viability,
+	# secret checks, stemcell checks) would run against whatever
+	# branch the operator happened to be on.  The post-deploy git
+	# work (commit + push manifest artifacts, auto-cascade) runs in
+	# Genesis::Env::_post_deploy after the deploy itself.
+	my $top = Genesis::Top->new('.');
+	my $pipeline_git;
+	my $pipeline_branch;
+	if ($top->ci_configured) {
+		require Service::Git;
+		$pipeline_git = Service::Git->new('.', track_branch => 1);
+		(my $branch_name = $env_name) =~ s{^.*/}{};
+		$branch_name =~ s/\.ya?ml$//;
+		$pipeline_branch = $branch_name;
+
+		# Fetch all pipeline env branches in one round-trip before any
+		# branch-state reads (branch_exists, checkout, pull_ff_only).
+		# This ensures teammate-created branches and propagation commits
+		# are visible before we act on them.
+		unless ($no_fetch) {
+			require Genesis::Commands::Pipelines;
+			Genesis::Commands::Pipelines::_fetch_pipeline_envs($top, $pipeline_git);
+		}
+
+		my $current = $pipeline_git->current_branch // '';
+		if ($current ne $branch_name) {
+			bail(
+				"Working tree has uncommitted changes.  Commit or stash them\n".
+				"before deploying."
+			) unless $pipeline_git->is_clean;
+			bail(
+				"Environment branch #C{%s} does not exist.\n".
+				"Create it with #C{genesis new %s} on the control branch.",
+				$branch_name, $branch_name
+			) unless $pipeline_git->branch_exists($branch_name);
+			info "\nSwitching to environment branch #C{%s}...", $branch_name;
+			$pipeline_git->checkout($branch_name);
+			# Reload Top now that the working tree is on the env branch
+			$top = Genesis::Top->new('.');
+		}
+
+		if (my $remote = $pipeline_git->default_remote) {
+			info "Pulling latest #C{%s} from #C{%s}...", $branch_name, $remote;
+			$pipeline_git->pull_ff_only($branch_name, $remote);
+		}
+	}
 
 	$options{'disable-reactions'} = ! delete($options{reactions});
-	my $env = Genesis::Top->new('.')->load_env($env_name)->with_vault()->with_bosh();
+	my $env = $top->load_env($env_name)->with_vault()->with_bosh();
+
+	# CI-only checks for pipeline-managed environments.
+	if ($top->ci_configured) {
+		my $prior = eval { $env->lookup('genesis.pipeline.prior_env', '') } // '';
+		if ($prior) {
+			# Hard invariant (no --yes override): the pipeline predecessor must
+			# have been successfully deployed at least once.  Without this guard
+			# a deploy could proceed past an env that skipped its predecessor,
+			# leaving the pipeline DAG in an inconsistent state.
+			_assert_prior_env_deployed($env, $prior);
+
+			# Warn when manually deploying outside of a pipeline job.
+			# GENESIS_HONOR_ENV is set by ci-pipeline-deploy; its absence
+			# means we are running at a terminal, not inside Concourse.
+			# Skip the warning when the configured provider is 'manual' --
+			# in that mode the operator IS the pipeline, so the warning
+			# is just noise.
+			my $provider_type = $top->config->get('ci.provider.type') || '';
+			if ($provider_type ne 'manual' && !$ENV{GENESIS_HONOR_ENV}) {
+				warning(
+					"\nManually deploying #C{%s}, which is managed by a Genesis pipeline.\n".
+					"The pipeline is the preferred deploy path — manual deploys bypass\n".
+					"change-detection, propagation gating, and approval gates.\n\n".
+					"The deployment will still record a #C{git.control_commit} so that\n".
+					"cascade propagation continues to work after this deploy.",
+					$env->name
+				);
+				unless ($options{yes} || !in_controlling_terminal()) {
+					prompt_for_boolean(
+						"Continue with manual deploy? [y|n]", 0
+					) || bail("Aborted.");
+				}
+			}
+		}
+	}
+
+	# --pull: pull propagated files from the prior env (or control HEAD for
+	# entry points) onto the env branch before deploying.  No-op when the
+	# env branch is already current or when CI is not configured.
+	if ($do_pull && $top->ci_configured && $pipeline_git) {
+		my $prior = eval { $env->lookup('genesis.pipeline.prior_env', '') } // '';
+
+		# Upgrade to track_branch so DESTROY returns us to the branch we were
+		# on before the pull (e.g. control), not to the env branch.
+		$pipeline_git = Service::Git->new('.', track_branch => 1);
+
+		bail(
+			"Environment branch #C{%s} does not exist.\n".
+			"Create it with #C{genesis new %s} on the control branch.",
+			$pipeline_branch, $pipeline_branch
+		) unless $pipeline_git->branch_exists($pipeline_branch);
+
+		# Switch to the env branch.  _pre_deploy will find us already there.
+		if (($pipeline_git->current_branch // '') ne $pipeline_branch) {
+			bail(
+				"Working tree has uncommitted changes.  Commit or stash them\n".
+				"before deploying with --pull."
+			) unless $pipeline_git->is_clean;
+			$pipeline_git->checkout($pipeline_branch);
+		}
+
+		my $source_sha = _get_source_sha_for_pull($env, $prior, $pipeline_git);
+		_apply_pull_propagation($env, $pipeline_branch, $source_sha, $pipeline_git)
+			if $source_sha;
+	}
 
 	my $deployment_files = $env->deployment_cache_path_lookup('existing');
 	if (scalar(keys %$deployment_files)) {
@@ -748,6 +1134,15 @@ sub deploy {
 		}
 	}
 
+	# Derive a default reason from the pipeline commit range when the
+	# env is on a pipeline branch and no --reason was supplied.
+	if (!defined($reason) && $pipeline_git && $pipeline_branch) {
+		if (my $derived = _derive_deploy_reason($env, $pipeline_git)) {
+			$reason = $derived;
+			$env->notify("derived deploy reason from pipeline history:\n%s", $reason);
+		}
+	}
+
 	# Check if the user is compelled to provide a reason for the deployment
 	if (my $min_size = $env->deployment_change_reason_required_size_policy) {
 		# TODO: Maybe prompt for a reason if it wasn't provided
@@ -777,16 +1172,22 @@ sub deploy {
 	}
 
 	info "\nPreparing to deploy #C{%s}:\n  - based on kit #c{%s}\n  - using Genesis #c{%s}", $env->name, $env->kit->id, $Genesis::VERSION;
+	if ($pipeline_branch) {
+		info "  - from branch #c{%s}", $pipeline_branch;
+	}
 	if ($env->use_create_env) {
 		info "  - as a #M{create-env} deployment.";
 	} else {
 		info "  - to '#M{%s}' BOSH director at #c{%s}.", $env->bosh->{alias}, $env->bosh->{url};
 	}
 	# Specify the environment iaas and scale
-	info(
-		"  - to a #Y{%s}-scale #G{%s} IaaS target",
-		$env->scale, $env->iaas
-	);
+	my $scale = $env->scale;
+	if ($scale) {
+		info("  - to a #Y{%s}-scale #G{%s} IaaS target", $scale, $env->iaas);
+	} else {
+		info("  - targeting #G{%s} IaaS", $env->iaas);
+	}
+	info "";
 
 	# Check if the kit supports the environment's IaaS
 	if (my $supported_iaas = $env->kit->metadata('supports')) {
@@ -802,43 +1203,48 @@ sub deploy {
 	if (! $env->use_create_env) {
 		# TODO: refactor to clean this up a bit
 
-		if ($env->cpi_enabled) {
-			if ($env->has_hook('cpi-config')) {
-				$env->notify("checking CPI config for #C{%s} deployment...", $env->name); #FIXME: move this into the _check_cpi_config method
-				my $check_result = $env->_check_cpi_config();
+		# CPI config management is an OCFP concern.  Non-OCFP envs have
+		# CPI config managed externally (typically via the director's
+		# cloud-config), so skip the check/fix and the default-CPI notify.
+		if ($env->is_ocfp) {
+			if ($env->cpi_enabled) {
+				if ($env->has_hook('cpi-config')) {
+					$env->notify("checking CPI config for #C{%s} deployment...", $env->name); #FIXME: move this into the _check_cpi_config method
+					my $check_result = $env->_check_cpi_config();
 
-				bail(
-					"Cannot provide the required CPI config: %s",
-					$check_result->{msg}
-				) if $check_result->{fatal}; # Should we just set a flag instead, and skip to next check?
+					bail(
+						"Cannot provide the required CPI config: %s",
+						$check_result->{msg}
+					) if $check_result->{fatal}; # Should we just set a flag instead, and skip to next check?
 
-				if ($check_result->{state} ne 'ok') {
-					if ($dryrun) {
-						dryrun(
-							"CPI config check failed: %s\n\nThis would be fixed if not in dry-run mode.",
-							$check_result->{msg}
-						);
-					} else {
-						# Just going to force the fix for now
-						my $fix_result = $env->_fix_cpi_config(
-							$check_result->{state},
-							$check_result->{fix_data},
-							noprompt => 1,
-						);
-						bail(
-							"Could not update required CPI config: %s",
-							$fix_result->{msg}
-						) unless $fix_result->{result} eq 'ok';
+					if ($check_result->{state} ne 'ok') {
+						if ($dryrun) {
+							dryrun(
+								"CPI config check failed: %s\n\nThis would be fixed if not in dry-run mode.",
+								$check_result->{msg}
+							);
+						} else {
+							# Just going to force the fix for now
+							my $fix_result = $env->_fix_cpi_config(
+								$check_result->{state},
+								$check_result->{fix_data},
+								noprompt => 1,
+							);
+							bail(
+								"Could not update required CPI config: %s",
+								$fix_result->{msg}
+							) unless $fix_result->{result} eq 'ok';
+						}
 					}
 				}
+			} else {
+				# Use the cpi config provided by the director (via exodus data)
+				$env->notify(
+					"Using %s CPI config from #M{%s} BOSH director...",
+					scalar $env->director_exodus_lookup('default_cpi_config','default'),
+					$env->bosh->{alias}
+				);
 			}
-		} else {
-			# Use the cpi config provided by the director (via exodus data)
-			$env->notify(
-				"Using %s CPI config from #M{%s} BOSH director...",
-				$env->director_exodus_lookup('default_cpi_config','default'),
-				$env->bosh->{alias}
-			);
 		}
 
 		if ($env->can_build_cloud_configs) {
@@ -1008,12 +1414,16 @@ sub deploy {
 				}
 			} else {
 				warning(
-					"Kit %s does not provide a cloud-config hook, so cloud configs will ".
-					"not be generated.  Ensure that the BOSH director has the necessary ".
-					"cloud config in place.",
+					"Kit #C{%s} does not provide a cloud-config hook, so cloud configs ".
+					"will not be generated.  Ensure that the BOSH director has the ".
+					"necessary cloud config in place.",
+					$env->kit->id,
 				);
 			}
-		} else {
+		} elsif ($env->is_ocfp) {
+			# OCFP env opted out via genesis.manage-cloud-configs: false.
+			# For non-OCFP envs the cloud-config is always externally
+			# managed, so skip the warning entirely — it's not actionable.
 			warning(
 				"Cloud Configs will not be generated for this deployment.  ".
 				"Ensure that the BOSH director has the necessary cloud config in place."
@@ -1146,6 +1556,122 @@ sub deploy {
 	}
 }
 
+# _assert_prior_env_deployed - hard invariant: prior_env must have a successful deploy {{{
+#
+# Bails unconditionally (no --yes override) when the prior_env has never
+# produced a successful deployment.  Called from deploy() when CI is
+# configured and genesis.pipeline.prior_env is set.
+sub _assert_prior_env_deployed {
+	my ($env, $prior_name) = @_;
+
+	# exodus_mount already ends with '/'; construct the deployments path directly.
+	my $prior_deploys = $env->exodus_mount . $prior_name . '/' . $env->type . '/deployments';
+	my $deploys = eval { $env->vault->get_path($prior_deploys) };
+
+	if ($deploys && ref($deploys) eq 'HASH') {
+		for my $entry (values %$deploys) {
+			next unless ref($entry) eq 'HASH';
+			my $result = $entry->{result} // '';
+			# 'post-failed' means the BOSH deploy itself succeeded; env is running.
+			return if $result eq 'success' || $result eq 'post-failed';
+		}
+	}
+
+	bail(
+		"Cannot deploy #C{%s}: its pipeline predecessor #C{%s} has\n".
+		"never been successfully deployed.\n\n".
+		"Deploy #C{%s} first, then retry.",
+		$env->name, $prior_name, $prior_name
+	);
+}
+
+# }}}
+# _get_source_sha_for_pull - determine the control SHA to use for a --pull {{{
+#
+# Entry-point envs (no prior_env): returns control HEAD so the env
+# gets the latest committed control content.
+#
+# Downstream envs: returns the git.control_commit from the prior_env's
+# last successful deployment — the certified control state that was in
+# effect when the predecessor last shipped.  Falls back to control HEAD
+# with a warning when no record is found.
+sub _get_source_sha_for_pull {
+	my ($env, $prior_name, $git) = @_;
+
+	my $control = Genesis::Top::DEFAULT_CONTROL_BRANCH();
+
+	unless ($prior_name) {
+		# Entry point: pull from control HEAD.
+		return $git->sha($control);
+	}
+
+	# Access the prior env's last successful deployment directly via vault.
+	my $prior_deploys = $env->exodus_mount . $prior_name . '/' . $env->type . '/deployments';
+	my $deploys = eval { $env->vault->get_path($prior_deploys) };
+
+	if ($deploys && ref($deploys) eq 'HASH') {
+		for my $ts (sort { $b cmp $a } keys %$deploys) {
+			my $entry = $deploys->{$ts};
+			next unless ref($entry) eq 'HASH';
+			my $result = $entry->{result} // '';
+			next unless $result eq 'success' || $result eq 'post-failed';
+
+			# get_path unflattens vault data: git.control_commit → {git}{control_commit}
+			my $ctl = (ref($entry->{git}) eq 'HASH') ? $entry->{git}{control_commit} : undef;
+			return $ctl if $ctl;
+		}
+	}
+
+	warning(
+		"Prior environment #C{%s} has no #C{git.control_commit} in its\n".
+		"last successful deployment.  Falling back to control HEAD for pull.",
+		$prior_name
+	);
+	return $git->sha($control);
+}
+
+# }}}
+# _apply_pull_propagation - pull propagated files from source_sha onto env branch {{{
+#
+# Diffs the propagation files between the env branch and the source SHA.
+# If there are changes, checks out the updated files from source_sha,
+# removes any deleted files, and commits with a [pipeline] control@<sha>
+# (pulled) marker.  Notifies and returns without committing when the env
+# branch is already current.
+sub _apply_pull_propagation {
+	my ($env, $env_branch, $source_sha, $git) = @_;
+
+	my @dep_files = $env->propagation_files;
+	unless (@dep_files) {
+		info "  #Yi{%s}: no propagation files defined — nothing to pull.", $env_branch;
+		return;
+	}
+
+	my $diff = $git->diff_files($env_branch, $source_sha, @dep_files);
+	my @to_copy = @{$diff->{changed}};
+	my @to_rm   = @{$diff->{deleted}};
+
+	unless (@to_copy || @to_rm) {
+		info "  #Yi{%s}: already current — no propagation changes to pull.", $env_branch;
+		return;
+	}
+
+	my $total     = scalar(@to_copy) + scalar(@to_rm);
+	my $sha_short = $git->sha($source_sha, short => 1) // substr($source_sha, 0, 8);
+
+	info "  #C{%s}: pulling %d file%s from control\@%s",
+		$env_branch, $total, $total == 1 ? '' : 's', $sha_short;
+
+	$git->checkout_file($source_sha, $_) for @to_copy;
+	$git->rm(@to_rm) if @to_rm;
+
+	my $msg = sprintf("[pipeline] control\@%s -> %s (pulled)", $sha_short, $env_branch);
+	$git->commit($msg, @to_copy);
+
+	info "  #G{%s}: propagation pull committed.", $env_branch;
+}
+
+# }}}
 sub terminate {
 	my ($env, $reason, @extras) = @_;
 	command_usage(1) if @extras || !defined($env);
diff --git a/lib/Genesis/Commands/Info.pm b/lib/Genesis/Commands/Info.pm
index 3c0b63a5..cbcd3d53 100644
--- a/lib/Genesis/Commands/Info.pm
+++ b/lib/Genesis/Commands/Info.pm
@@ -537,16 +537,20 @@ sub environments {
 		my %deployments_by_name;
 		if (scalar @repos) {
 			$root =~ s{/?$}{/};
+			my $root_display = $label eq '@current' ? '.'
+				: $label eq '@parent'  ? '..'
+				: $label =~ /^@/       ? humanize_path($root)
+				: $label;
 			if ($json) {
 				info(
 					"\nReading %s under deployment root #C{%s}",
 					$group_by eq 'env' ? "environments" : "repositories",
-					humanize_path($root, root_map => $root_map) =~ s{/?$}{/}r =~ s{>\e\[0m/$}{>\e\[0m}r
+					$root_display
 				);
 			} else {
 				info(
-					"\nDeployment root #C{%s} contains the following %s:",
-					humanize_path($root, root_map => $root_map) =~ s{/?$}{/}r =~ s{>\e\[0m/$}{>\e\[0m}r,
+					"\nDeployment root #C{%s} contains the following\n%s:\n",
+					$root_display,
 					$group_by eq 'env' ? "environments" : "repositories"
 				);
 			}
@@ -554,9 +558,18 @@ sub environments {
 			my ($i,$j) = (0,0);
 			for my $repo (@repos) {
 				__processing($i, scalar(@repos), $j) if ($show_details && ($group_by eq 'env' || $json));
-				my $top = Genesis::Top->new($repo, silent_vault_check => 1, allow_no_vault => 1);
+				my ($top, @envs);
+				eval {
+					$top = Genesis::Top->new($repo, silent_vault_check => 1, allow_no_vault => 1);
+					@envs = $top->envs;
+				};
+				if ($@) {
+					my $err = $@;
+					$err =~ s/\s+$//;
+					warning("Skipping #C{%s}: %s", basename($repo), $err);
+					next;
+				}
 				my $repo_label = basename($top->path);
-				my @envs = $top->envs; # Do the heavy lifting to determine which files are environments
 				@envs = grep {$_->name =~ qr($filter_env)} @envs if $filter_env;
 				__processing(++$i, scalar(@repos), $j) if ($show_details && ($group_by eq 'env' || $json));
 
diff --git a/lib/Genesis/Commands/Pipeline.pm b/lib/Genesis/Commands/Pipeline.pm
deleted file mode 100644
index be67c427..00000000
--- a/lib/Genesis/Commands/Pipeline.pm
+++ /dev/null
@@ -1,593 +0,0 @@
-package Genesis::Commands::Pipeline;
-use strict;
-use warnings;
-
-use Genesis;
-use Genesis::Commands;
-use Genesis::Top;
-use Genesis::CI::Compiler;
-use JSON::PP;
-use File::Basename qw/dirname/;
-
-### Public Command Functions {{{
-
-# apply - compile and deploy pipeline (replaces genesis repipe) {{{
-sub apply {
-	my ($layout) = @_;
-	option_defaults(config => 'ci.yml');
-
-	my $opts     = get_options;
-	my $platform = $opts->{platform} || 'concourse';
-
-	bail("--output-dir requires --platform")
-		if $opts->{'output-dir'} && !$opts->{platform};
-	bail("--debug-dir requires --platform")
-		if $opts->{'debug-dir'} && !$opts->{platform};
-
-	my $top = _get_top($opts);
-	my $result = _compile($top, $platform, $opts);
-
-	_dump_debug_artifacts($opts->{'debug-dir'}, $result, $platform)
-		if $opts->{'debug-dir'};
-
-	my $ast    = $result->{ast};
-	my $output = $result->{output};
-
-	my $name = $ast->metadata->{name}
-		or bail("Pipeline AST has no name defined");
-
-	# --output-dir: write artifacts to directory and exit
-	if (my $out_dir = $opts->{'output-dir'}) {
-		mkdir_or_fail($out_dir);
-		for my $file (sort keys %$output) {
-			mkfile_or_fail("$out_dir/$file", $output->{$file});
-			info("Wrote #C{%s/%s}", $out_dir, $file);
-		}
-		mkfile_or_fail("$out_dir/ast.json",
-			JSON::PP->new->pretty->canonical->encode({%$ast}));
-		info("Wrote #C{%s/ast.json}", $out_dir);
-		exit 0;
-	}
-
-	if ($platform eq 'concourse') {
-		my $yaml = $output->{'pipeline.yml'}
-			or bail("Concourse provider did not produce pipeline.yml");
-
-		if ($opts->{'dry-run'}) {
-			output({raw => 1}, $yaml);
-			exit 0;
-		}
-
-		my $target = $opts->{target} || $layout || $name;
-
-		my ($out, $rc) = run('fly -t $1 pause-pipeline -p $2', $target, $name);
-		bail("Could not pause #c{%s} pipeline: %s", $name, $out)
-			unless $rc == 0 || $out =~ /pipeline '.*' not found/;
-
-		my $yes = $opts->{yes} ? ' -n ' : '';
-		my $dir = workdir;
-		mkfile_or_fail("$dir/pipeline.yml", $yaml);
-		run({ interactive => 1, onfailure => "Could not upload pipeline $name" },
-			'fly -t $1 set-pipeline '.$yes.' -p $2 -c $3/pipeline.yml',
-			$target, $name, $dir);
-
-		unless ($opts->{paused}) {
-			run({ interactive => 1, onfailure => "Could not unpause pipeline $name" },
-				'fly -t $1 unpause-pipeline -p $2',
-				$target, $name);
-		}
-
-		my $public = $ast->configuration->{public} || 0;
-		my $action = $public ? 'expose' : 'hide';
-		run({ interactive => 1, onfailure => "Could not $action pipeline $name" },
-			'fly -t $1 '.$action.'-pipeline -p $2',
-			$target, $name);
-
-	} elsif ($platform eq 'github-actions') {
-		if ($opts->{'dry-run'}) {
-			for my $file (sort keys %$output) {
-				output "#G{--- %s ---}", $file;
-				output({raw => 1}, $output->{$file});
-			}
-			exit 0;
-		}
-		for my $file (sort keys %$output) {
-			my $path = ".github/workflows/$file";
-			mkdir_or_fail(dirname($path));
-			mkfile_or_fail($path, $output->{$file});
-			info("Wrote #C{%s}", $path);
-		}
-		info("GitHub Actions workflows written. Commit and push to activate.");
-
-	} else {
-		bail("Unsupported platform '%s' for pipeline apply", $platform);
-	}
-
-	exit 0;
-}
-
-# }}}
-# graph - write pipeline.md with Mermaid flowchart (replaces genesis graph) {{{
-sub graph {
-	my ($layout) = @_;
-	option_defaults(config => 'ci.yml');
-
-	my $opts     = get_options;
-	my $platform = $opts->{platform} || 'concourse';
-	my $top      = Genesis::Top->new('.');
-
-	my $result   = _compile($top, $platform, $opts);
-	my $ast      = $result->{ast};
-	my $provider = $result->{provider};
-
-	my $md;
-	if ($provider->can('graph_md')) {
-		$md = $provider->graph_md();
-	} else {
-		$md = _mermaid_md($ast);
-	}
-
-	mkfile_or_fail('pipeline.md', $md);
-	info("Wrote #C{pipeline.md}");
-	exit 0;
-}
-
-# }}}
-# describe - human-readable pipeline progression (replaces genesis describe) {{{
-sub describe {
-	my ($layout) = @_;
-	option_defaults(config => 'ci.yml');
-
-	my $opts     = get_options;
-	my $platform = $opts->{platform} || 'concourse';
-	my $top      = Genesis::Top->new('.');
-
-	my $result   = _compile($top, $platform, $opts);
-	my $ast      = $result->{ast};
-	my $provider = $result->{provider};
-
-	if ($provider->can('generate_description')) {
-		$provider->generate_description($ast);
-	} else {
-		_print_description($ast, $platform);
-	}
-	exit 0;
-}
-
-# }}}
-# diff - show compiled vs live pipeline delta {{{
-sub diff {
-	option_defaults(config => 'ci.yml');
-
-	my $opts     = get_options;
-	my $platform = $opts->{platform} || 'concourse';
-
-	bail("diff is only supported for the 'concourse' platform")
-		unless $platform eq 'concourse';
-
-	my $top    = _get_top($opts, skip_vault => 1);
-	my $result = _compile($top, $platform, $opts);
-	my $ast    = $result->{ast};
-	my $output = $result->{output};
-
-	my $name   = $ast->metadata->{name}
-		or bail("Pipeline AST has no name defined");
-	my $target = $opts->{target} || $name;
-
-	my $compiled = $output->{'pipeline.yml'}
-		or bail("Concourse provider did not produce pipeline.yml");
-
-	my $dir = workdir;
-	mkfile_or_fail("$dir/compiled.yml", $compiled);
-
-	my ($live, $rc) = run('fly -t $1 get-pipeline -p $2', $target, $name);
-	if ($rc != 0) {
-		info("#Y{Pipeline '%s' does not exist on target '%s' — nothing to diff against.}",
-			$name, $target);
-		info("Run #C{genesis pipeline-apply} to deploy it first.");
-		exit 0;
-	}
-	mkfile_or_fail("$dir/live.yml", $live);
-
-	my ($diff_out, $diff_rc) = run(
-		'diff -u --label live --label compiled $1 $2',
-		"$dir/live.yml", "$dir/compiled.yml"
-	);
-
-	if ($diff_rc == 0) {
-		info("#G{No differences} — compiled pipeline matches live pipeline.");
-	} else {
-		output({raw => 1}, $diff_out);
-	}
-	exit 0;
-}
-
-# }}}
-# status - show per-env job health {{{
-sub status {
-	my ($filter_env) = @_;
-	option_defaults(config => 'ci.yml');
-
-	my $opts     = get_options;
-	my $platform = $opts->{platform} || 'concourse';
-
-	bail("status is only supported for the 'concourse' platform")
-		unless $platform eq 'concourse';
-
-	my $top    = _get_top($opts, skip_vault => 1);
-	my $result = _compile($top, $platform, $opts);
-	my $ast    = $result->{ast};
-	my $name   = $ast->metadata->{name}
-		or bail("Pipeline AST has no name defined");
-	my $target = $opts->{target} || $name;
-
-	my ($json_out, $rc) = run('fly -t $1 jobs -p $2 --json', $target, $name);
-	bail("Could not get jobs for pipeline '%s' on target '%s': %s", $name, $target, $json_out)
-		unless $rc == 0;
-
-	my $jobs;
-	eval { $jobs = JSON::PP->new->decode($json_out) };
-	bail("Failed to parse fly jobs output: %s", $@) if $@;
-
-	output "#G{Pipeline}: #C{%s}  (#Yi{target}: %s)", $name, $target;
-	output "";
-
-	my $col_w = 40;
-	output "  %-${col_w}s  %-10s  %s", "Environment", "Status", "Notes";
-	output "  %s  %s  %s", '-' x $col_w, '-' x 10, '-' x 20;
-
-	for my $job (sort { $a->{name} cmp $b->{name} } @$jobs) {
-		next if $filter_env && $job->{name} ne $filter_env;
-
-		my $status = _job_status_label($job);
-		my @notes;
-		push @notes, 'paused'  if $job->{paused};
-		push @notes, 'errored' if ($job->{finished_build} || {})->{status} eq 'errored';
-
-		output "  %-${col_w}s  %-10s  %s",
-			$job->{name},
-			$status,
-			join(', ', @notes) || '';
-	}
-	output "";
-	exit 0;
-}
-
-# }}}
-# pause - pause env job or entire pipeline {{{
-sub pause {
-	my ($env) = @_;
-	option_defaults(config => 'ci.yml');
-
-	my $opts     = get_options;
-	my $platform = $opts->{platform} || 'concourse';
-
-	bail("pause is only supported for the 'concourse' platform")
-		unless $platform eq 'concourse';
-
-	my $top    = _get_top($opts, skip_vault => 1);
-	my $result = _compile($top, $platform, $opts);
-	my $ast    = $result->{ast};
-	my $name   = $ast->metadata->{name}
-		or bail("Pipeline AST has no name defined");
-	my $target = $opts->{target} || $name;
-
-	if ($env) {
-		run({ interactive => 1,
-		      onfailure => "Could not pause job '$env' in pipeline '$name'" },
-			'fly -t $1 pause-job -p $2 -j $3',
-			$target, $name, $env);
-		info("Paused job #C{%s} in pipeline #C{%s}", $env, $name);
-	} else {
-		run({ interactive => 1,
-		      onfailure => "Could not pause pipeline '$name'" },
-			'fly -t $1 pause-pipeline -p $2',
-			$target, $name);
-		info("Paused pipeline #C{%s}", $name);
-	}
-	exit 0;
-}
-
-# }}}
-# resume - resume env job or entire pipeline {{{
-sub resume {
-	my ($env) = @_;
-	option_defaults(config => 'ci.yml');
-
-	my $opts     = get_options;
-	my $platform = $opts->{platform} || 'concourse';
-
-	bail("resume is only supported for the 'concourse' platform")
-		unless $platform eq 'concourse';
-
-	my $top    = _get_top($opts, skip_vault => 1);
-	my $result = _compile($top, $platform, $opts);
-	my $ast    = $result->{ast};
-	my $name   = $ast->metadata->{name}
-		or bail("Pipeline AST has no name defined");
-	my $target = $opts->{target} || $name;
-
-	if ($env) {
-		run({ interactive => 1,
-		      onfailure => "Could not resume job '$env' in pipeline '$name'" },
-			'fly -t $1 unpause-job -p $2 -j $3',
-			$target, $name, $env);
-		info("Resumed job #C{%s} in pipeline #C{%s}", $env, $name);
-	} else {
-		run({ interactive => 1,
-		      onfailure => "Could not resume pipeline '$name'" },
-			'fly -t $1 unpause-pipeline -p $2',
-			$target, $name);
-		info("Resumed pipeline #C{%s}", $name);
-	}
-	exit 0;
-}
-
-# }}}
-# }}}
-### Internal Helpers {{{
-
-# _compile - detect config source and run the compiler {{{
-sub _compile {
-	my ($top, $platform, $opts) = @_;
-
-	my %compiler_opts = (top => $top);
-
-	my $ci_dir = '.genesis/ci';
-	if (-d $ci_dir && -f "$ci_dir/pipeline.yml") {
-		$compiler_opts{ci_dir} = $ci_dir;
-		info("Using multi-file configuration from #C{%s/}", $ci_dir);
-	} elsif (Genesis::CI::Compiler->can_compile_from_env_files($ci_dir)) {
-		$compiler_opts{ci_dir}  = $ci_dir;
-		$compiler_opts{env_dir} = '.';
-		info("Using env-file topology with config from #C{%s/}", $ci_dir);
-	} else {
-		$compiler_opts{file} = $opts->{config} || 'ci.yml';
-		info("Using legacy configuration from #C{%s}", $compiler_opts{file});
-	}
-
-	my $compiler = Genesis::CI::Compiler->new(%compiler_opts);
-	return $compiler->compile(provider => $platform);
-}
-
-# }}}
-# _get_top - create a Genesis::Top object, with or without vault {{{
-sub _get_top {
-	my ($opts, %defaults) = @_;
-
-	my $skip = $opts->{'skip-vault'} || $defaults{skip_vault};
-	if ($skip) {
-		return Genesis::Top->new('.');
-	}
-
-	my $top = Genesis::Top->new('.', vault => $opts->{vault});
-	bail(
-		"No vault specified or configured.\n".
-		"Use --skip-vault to compile without vault access."
-	) unless $top->vault;
-	return $top;
-}
-
-# }}}
-# _mermaid_md - generate Mermaid pipeline.md from a bare AST {{{
-sub _mermaid_md {
-	my ($ast) = @_;
-
-	my $name  = $ast->metadata->{name} || 'genesis-pipeline';
-	my @lines = ('flowchart LR');
-
-	for my $wf_name ($ast->workflow_names) {
-		my $wf = $ast->workflows->{$wf_name};
-		next unless $wf->{graph};
-
-		my $nodes = $wf->{graph}{nodes} || {};
-		my $edges = $wf->{graph}{edges} || [];
-
-		my %in_any_edge;
-		for my $edge (@$edges) {
-			$in_any_edge{$edge->{from}} = 1;
-			$in_any_edge{$edge->{to}}   = 1;
-		}
-
-		for my $edge (@$edges) {
-			my $from = $nodes->{$edge->{from}}{alias} || $edge->{from};
-			my $to   = $nodes->{$edge->{to}}{alias}   || $edge->{to};
-			($from) =~ s/[^a-zA-Z0-9_]/_/g;
-			($to)   =~ s/[^a-zA-Z0-9_]/_/g;
-			push @lines, "  $from --> $to";
-		}
-
-		for my $n (sort keys %$nodes) {
-			next if $in_any_edge{$n};
-			my $alias = $nodes->{$n}{alias} || $n;
-			$alias =~ s/[^a-zA-Z0-9_]/_/g;
-			push @lines, "  $alias";
-		}
-	}
-
-	my $mermaid = join("\n", @lines) . "\n";
-	return "# Pipeline: $name\n\n\`\`\`mermaid\n${mermaid}\`\`\`\n";
-}
-
-# }}}
-# _print_description - human-readable AST description {{{
-sub _print_description {
-	my ($ast, $platform) = @_;
-
-	output "#G{Pipeline}: #C{%s}", $ast->metadata->{name} || '(unnamed)';
-	output "  #Yi{Platform}: %s", $platform;
-	output "  #Yi{Source}:   %s", $ast->metadata->{source} || 'unknown';
-	output "";
-
-	my $integrations = $ast->integrations || {};
-	if (my $sc = $integrations->{source_control}) {
-		output "#G{Source Control}:";
-		output "  Provider:   %s", $sc->{provider}   || 'unknown';
-		output "  Repository: %s", $sc->{repository} || 'unknown';
-	}
-
-	my @targets = $ast->target_names;
-	if (@targets) {
-		output "";
-		output "#G{Targets}: (%d)", scalar @targets;
-		output "  - #C{%s}", $_ for sort @targets;
-	}
-
-	my @workflows = $ast->workflow_names;
-	if (@workflows) {
-		output "";
-		output "#G{Workflows}: (%d)", scalar @workflows;
-		for my $wf_name (sort @workflows) {
-			my $wf = $ast->workflows->{$wf_name};
-			output "  #Yi{%s} (%s)", $wf_name, $wf->{type} || 'deployment';
-
-			if ($wf->{graph} && $wf->{graph}{nodes}) {
-				my $nodes = $wf->{graph}{nodes};
-				my @order = eval { $ast->workflow_stage_order($wf_name) };
-				my @stages = @order
-					? map { $nodes->{$_}{alias} || $_ } @order
-					: sort keys %$nodes;
-				output "    Progression: %s", join(' -> ', @stages);
-			}
-		}
-	}
-
-	output "";
-}
-
-# }}}
-# _dump_debug_artifacts - write compiler intermediates to a directory {{{
-sub _dump_debug_artifacts {
-	my ($debug_dir, $result, $platform) = @_;
-
-	mkdir_or_fail($debug_dir);
-
-	my $json = JSON::PP->new->pretty->canonical;
-
-	if ($result->{parsed}) {
-		mkfile_or_fail("$debug_dir/01-parsed.json", $json->encode($result->{parsed}));
-		info("Debug: wrote #C{%s/01-parsed.json}", $debug_dir);
-	}
-
-	if (my $ast = $result->{ast}) {
-		my %source;
-		for my $key (qw(branches integrations targets workflows configuration
-		                provider_config triggers resources)) {
-			my $accessor = $ast->can($key);
-			$source{$key} = $accessor->($ast) if $accessor;
-		}
-		$source{metadata} = $ast->metadata;
-		$source{scripts}  = $ast->scripts;
-
-		mkfile_or_fail("$debug_dir/02-ast-source.json", $json->encode(\%source));
-		info("Debug: wrote #C{%s/02-ast-source.json}", $debug_dir);
-
-		if ($ast->pipeline && %{$ast->pipeline}) {
-			my %pipeline    = %{$ast->pipeline};
-			my $pipeline_md = delete $pipeline{pipeline_md};
-			my $description = delete $pipeline{description};
-			delete $pipeline{mermaid};
-
-			mkfile_or_fail("$debug_dir/03-pipeline.json", $json->encode(\%pipeline));
-			info("Debug: wrote #C{%s/03-pipeline.json}", $debug_dir);
-
-			if ($pipeline_md) {
-				mkfile_or_fail("$debug_dir/04-pipeline.md", $pipeline_md);
-				info("Debug: wrote #C{%s/04-pipeline.md}", $debug_dir);
-			}
-			if ($description) {
-				mkfile_or_fail("$debug_dir/05-description.txt", $description);
-				info("Debug: wrote #C{%s/05-description.txt}", $debug_dir);
-			}
-		}
-	}
-
-	if ($result->{output}) {
-		if (ref($result->{output}) eq 'HASH') {
-			for my $file (sort keys %{$result->{output}}) {
-				mkfile_or_fail("$debug_dir/06-output-$file", $result->{output}{$file});
-				info("Debug: wrote #C{%s/06-output-%s}", $debug_dir, $file);
-			}
-		} else {
-			mkfile_or_fail("$debug_dir/06-output.yml", $result->{output});
-			info("Debug: wrote #C{%s/06-output.yml}", $debug_dir);
-		}
-	}
-
-	info("Debug artifacts written to #C{%s/}", $debug_dir);
-}
-
-# }}}
-# _job_status_label - derive a display status from a fly jobs JSON entry {{{
-sub _job_status_label {
-	my ($job) = @_;
-	return 'paused' if $job->{paused};
-	my $fb = $job->{finished_build} || {};
-	return $fb->{status} || 'pending';
-}
-
-# }}}
-# }}}
-
-1;
-
-=head1 NAME
-
-Genesis::Commands::Pipeline - Pipeline management command suite
-
-=head1 DESCRIPTION
-
-Implements the C<genesis pipeline-*> command family, replacing the legacy
-C<repipe>, C<graph>, and C<describe> commands with a unified interface.
-
-Commands are registered in C<bin/genesis> as flat names for 3.0.x
-compatibility (C<genesis pipeline-apply>, C<genesis pipeline-graph>, etc.)
-and the legacy C<repipe>/C<graph>/C<describe> remain as aliases.
-
-=head1 COMMANDS
-
-=over 4
-
-=item B<pipeline-apply> [--platform PROVIDER] [--dry-run] [--paused]
-
-Compile and deploy the pipeline. Replaces C<genesis repipe>.
-Defaults to Concourse. Supports C<--dry-run> (print YAML only) and
-C<--output-dir> (write artifacts to a directory).
-
-=item B<pipeline-graph> [--platform PROVIDER]
-
-Compile pipeline and write C<pipeline.md> containing a Mermaid flowchart.
-Replaces C<genesis graph>.
-
-=item B<pipeline-describe> [--platform PROVIDER]
-
-Compile pipeline and print a human-readable ordered progression.
-Replaces C<genesis describe>.
-
-=item B<pipeline-diff> [--target TARGET]
-
-Compare compiled pipeline YAML against the live pipeline via
-C<fly get-pipeline>. Shows unified diff or reports no differences.
-
-=item B<pipeline-status> [<env>] [--target TARGET]
-
-Query C<fly jobs> for per-environment job status. Optionally filter to a
-single environment.
-
-=item B<pipeline-pause> [<env>] [--target TARGET]
-
-Pause a specific environment's job, or the entire pipeline if no env given.
-
-=item B<pipeline-resume> [<env>] [--target TARGET]
-
-Resume a specific environment's job, or the entire pipeline if no env given.
-
-=back
-
-=head1 SEE ALSO
-
-Genesis::Commands::Pipelines (legacy), Genesis::CI::Compiler
-
-=cut
-
-# vim: ts=2 sw=2 sts=2 noet fdm=marker foldlevel=1 nu
diff --git a/lib/Genesis/Commands/Pipelines.pm b/lib/Genesis/Commands/Pipelines.pm
index 1d07602c..1114ac86 100644
--- a/lib/Genesis/Commands/Pipelines.pm
+++ b/lib/Genesis/Commands/Pipelines.pm
@@ -10,101 +10,1314 @@ use Genesis::Top;
 use Genesis::Env;
 use Genesis::CI::Legacy qw//;
 use Genesis::CI::Compiler;
+use Genesis::CI::Propagation;
+use Service::Git;
+use Service::Github;
 use Service::Vault::Remote;
 
 use File::Basename qw/dirname/;
 use File::Path qw/rmtree/;
 use JSON::PP;
 
+### Public Commands {{{
+
+# embed - embed Genesis binary in the repository {{{
 sub embed {
 	command_usage(1) if @_;
-
-	# FIXME: update .genesis/config with new version info
 	Genesis::Top->new('.')->embed($ENV{GENESIS_CALLBACK_BIN} || $0);
 }
 
-sub repipe {
-	warning("'genesis repipe' is deprecated and will be removed in a future version.  Use 'genesis pipeline-apply' instead.");
+# }}}
+# apply - compile and deploy pipeline (replaces genesis repipe) {{{
+sub apply {
+	my ($layout) = @_;
 	option_defaults(config => 'ci.yml');
-	my $layout = $_[0];
 
-	# Resolve --provider/--platform into a canonical platform value
-	my $platform = get_options->{platform};
+	my $opts     = get_options;
+	my $platform = $opts->{platform} || 'concourse';
+
+	bail("--output-dir requires --platform")
+		if $opts->{'output-dir'} && !$opts->{platform};
+	bail("--debug-dir requires --platform")
+		if $opts->{'debug-dir'} && !$opts->{platform};
+
+	my $top = _get_top($opts);
+
+	# Short-circuit on the 'manual' provider: it has no pipeline to apply
+	# — Genesis is the CLI you run at your terminal, there is no CI to
+	# generate or deploy.
+	if (($top->config->get('ci.provider.type') // '') eq 'manual') {
+		bail(
+			"Manual provider has no pipeline to apply.\n\n".
+			"#i{Genesis is your CLI - deploys happen at your terminal, ".
+			"not in a hosted pipeline.}\n\n".
+			"To use a real CI provider, change #C{ci.provider.type} in ".
+			"#C{.genesis/config} to one of: #C{concourse}, #C{github-actions}, ".
+			"then re-run #C{genesis pipeline-apply}."
+		);
+	}
+
+	my $result = _compile_pipeline($top, $platform);
+
+	_dump_debug_artifacts($opts->{'debug-dir'}, $result, $platform)
+		if $opts->{'debug-dir'};
+
+	my $ast    = $result->{ast};
+	my $output = $result->{output};
+	my $name   = $ast->metadata->{name}
+		or bail("Pipeline AST has no name defined");
+
+	if (my $out_dir = $opts->{'output-dir'}) {
+		mkdir_or_fail($out_dir);
+		for my $file (sort keys %$output) {
+			mkfile_or_fail("$out_dir/$file", $output->{$file});
+			info("Wrote #C{%s/%s}", $out_dir, $file);
+		}
+		mkfile_or_fail("$out_dir/ast.json",
+			JSON::PP->new->pretty->canonical->encode({%$ast}));
+		info("Wrote #C{%s/ast.json}", $out_dir);
+		exit 0;
+	}
+
+	if ($platform eq 'concourse') {
+		my $provider = $result->{provider};
+
+		if ($opts->{'dry-run'}) {
+			my $yaml = $output->{'pipeline.yml'}
+				or bail("Concourse provider did not produce pipeline.yml");
+			output({raw => 1}, $yaml);
+			exit 0;
+		}
+
+		$provider->check_prereqs() or exit 86;
+
+		my %deploy_opts = %{ $provider->normalize_provider_opts(
+			$result->{provider_cli_opts} || {}
+		) };
+		$deploy_opts{target}          //= $opts->{target} // $layout // $name;
+		$deploy_opts{pause_after_set} //= $opts->{paused};
+		$provider->deploy(%deploy_opts, yes => $opts->{yes});
+
+	} elsif ($platform eq 'github-actions') {
+		if ($opts->{'dry-run'}) {
+			for my $file (sort keys %$output) {
+				output "#G{--- %s ---}", $file;
+				output({raw => 1}, $output->{$file});
+			}
+			exit 0;
+		}
+		for my $file (sort keys %$output) {
+			my $path = ".github/workflows/$file";
+			mkdir_or_fail(dirname($path));
+			mkfile_or_fail($path, $output->{$file});
+			info("Wrote #C{%s}", $path);
+		}
+		info("GitHub Actions workflows written. Commit and push to activate.");
+
+	} else {
+		bail("Unsupported platform '%s' for pipeline apply", $platform);
+	}
+
+	exit 0;
+}
+
+# }}}
+# pipeline_status - show propagation state across all environments {{{
+sub pipeline_status {
+
+	my $top = Genesis::Top->new('.');
+	bail("CI is not configured for this repository.")
+		unless $top->ci_configured;
+
+	my $git     = Service::Git->new('.');
+	my $control = Genesis::Top::DEFAULT_CONTROL_BRANCH();
 
-	bail("--output-dir requires --provider")
-		if get_options->{'output-dir'} && !$platform;
+	# Build the DAG
+	require Genesis::CI::Compiler::ASTBuilder;
+	my $builder = Genesis::CI::Compiler::ASTBuilder->new(
+		top     => $top,
+		env_dir => $top->path,
+	);
+	my ($nodes, $edges) = $builder->_build_from_env_files($top->path);
+
+	bail("No environments with pipeline metadata found.")
+		unless %$nodes;
 
-	bail("--skip-vault requires --provider")
-		if get_options->{'skip-vault'} && !$platform;
+	my (%children, %has_parent, %parent_of);
+	for my $edge (@$edges) {
+		push @{$children{$edge->{from}}}, $edge->{to};
+		$has_parent{$edge->{to}} = 1;
+		$parent_of{$edge->{to}} = $edge->{from};
+	}
 
-	bail("--debug-dir requires --provider")
-		if get_options->{'debug-dir'} && !$platform;
+	# Topological order
+	my @dag_order;
+	my @queue = sort grep { !$has_parent{$_} } keys %$nodes;
+	my %visited;
+	while (@queue) {
+		my $env = shift @queue;
+		next if $visited{$env}++;
+		push @dag_order, $env;
+		push @queue, sort @{$children{$env} || []};
+	}
 
-	# New compiler pipeline when --provider/--platform is specified
-	if ($platform) {
-		my $top;
-		if (get_options->{'skip-vault'}) {
-			$top = Genesis::Top->new('.');
+	# Refresh env branch refs from remote before reading status so the
+	# display reflects teammate commits, not just local state.
+	_fetch_pipeline_envs($top, $git)
+		unless get_options->{'no-fetch'};
+
+	my $head       = $git->sha($control);
+	my $head_short = $git->sha($head, short => 1);
+
+	# Gather state for each env
+	my %env_state;   # env => { branch_sha, deployed_sha, changed, ... }
+	my %env_changed; # for propagation target computation
+	for my $env_name (@dag_order) {
+		my %state = ( name => $env_name );
+
+		unless ($git->branch_exists($env_name)) {
+			$state{status} = 'no-branch';
+			$env_state{$env_name} = \%state;
+			next;
+		}
+
+		# Branch column: the CONTROL sha that was most recently propagated
+		# to this env (read from the `[pipeline] control@<sha>` marker on
+		# the env branch) — not the env-branch's own HEAD sha.
+		my ($branch_ctl) = _resolve_propagation_base($env_name, $git);
+		$state{branch_sha} = $branch_ctl
+			? $git->sha($branch_ctl, short => 1)
+			: undef;
+
+		my $env = eval { $top->load_env($env_name) };
+		unless ($env) {
+			$state{status} = 'error';
+			$state{error}  = _summarize_load_error($@);
+			$env_state{$env_name} = \%state;
+			next;
+		}
+
+		# Deploy column: the CONTROL sha certified by the last successful
+		# deployment (exodus git.control_commit).  Also used below to
+		# determine deployed-vs-pending status.
+		my $dep_ctl = '';
+		my $env_v = eval { $env->with_vault };
+		if ($env_v) {
+			my $dep = eval { $env_v->deployments->latest_successful };
+			$dep_ctl = $dep ? ($dep->lookup('git.control_commit') || '') : '';
+		}
+		$state{deployed_sha} = $dep_ctl
+			? $git->sha($dep_ctl, short => 1)
+			: undef;
+
+		my @dep_files = $env->propagation_files;
+		my $diff = $git->diff_files($env_name, $head, @dep_files);
+
+		if (@{$diff->{all}}) {
+			$state{changed} = $diff->{all};
+			$state{count}   = scalar @{$diff->{all}};
+			$env_changed{$env_name} = $diff->{all};
+		} else {
+			# Synced — check if branch's control sha matches deploy's
+			my $deployed = ($dep_ctl && $branch_ctl && $dep_ctl eq $branch_ctl) ? 1 : 0;
+			$state{status} = $deployed ? 'deployed' : 'awaiting-deploy';
+		}
+
+		$env_state{$env_name} = \%state;
+	}
+
+	# Run entry point algorithm to determine who's blocked
+	my $targets = Genesis::CI::Propagation::compute_propagation_targets(
+		dag_order   => \@dag_order,
+		parent_of   => \%parent_of,
+		env_changed => \%env_changed,
+	);
+
+	for my $env_name (@dag_order) {
+		my $state = $env_state{$env_name};
+		next if $state->{status};  # already resolved (synced, no-branch, error)
+
+		if ($targets->{$env_name}) {
+			$state->{status} = 'pending';
 		} else {
-			$top = Genesis::Top->new('.', vault=>get_options->{vault});
-			bail("No vault specified or configured.\n".
-				"Use --skip-vault with --platform to compile without vault access."
-			) unless $top->vault;
+			# Has changes but not an entry point — blocked by ancestor
+			my $blocker = $parent_of{$env_name};
+			while ($blocker && !$env_changed{$blocker}) {
+				$blocker = $parent_of{$blocker};
+			}
+			$state->{status}  = 'blocked';
+			$state->{blocker} = $blocker;
+		}
+	}
+
+	# Pre-fetch open propagation PRs from GitHub if any env uses require_pr.
+	# One paginated API call covers all envs; non-fatal if credentials are
+	# absent or the call fails — display degrades to [PR required] for all.
+	my %gh_open_prs;  # env_name => PR object for the most-recent open propagation PR
+	{
+		my $has_require_pr = grep { ($nodes->{$_}{require_pr} // 0) } keys %$nodes;
+		if ($has_require_pr && $ENV{GITHUB_AUTH_TOKEN}) {
+			my ($gh_owner, $gh_repo) = _github_owner_repo_from_remote($git);
+			if ($gh_owner && $gh_repo) {
+				my $github = Service::Github->new(org => $gh_owner);
+				eval {
+					my $prs = $github->list_prs("$gh_owner/$gh_repo", state => 'open');
+					for my $pr (@$prs) {
+						if ($pr->{head}{ref} =~ m{^propagate/([^/]+)/}) {
+							$gh_open_prs{$1} //= $pr;
+						}
+					}
+				};
+				# Silently degrade on error — status output continues without PR info
+			}
 		}
-		return _repipe_compiled($top, $layout);
 	}
 
-	my $top = Genesis::Top->new('.', vault=>get_options->{vault});
+	# Display
+	my $pipeline_name = $top->config->get('ci.name') || $top->type;
+	my $provider_type = $top->config->get('ci.provider.type') || 'manual';
+
+	output "\n#G{Pipeline}: #C{%s}  #Yi{provider}: %s  #Yi{control}: %s",
+		$pipeline_name, $provider_type, $head_short;
+	output "";
+
+	# Compute column width: widest (indent + name) across all envs
+	my $col_width = 0;
+	my %depth_of;
+	for my $env_name (@dag_order) {
+		my $depth = 0;
+		my $p = $parent_of{$env_name};
+		while ($p) { $depth++; $p = $parent_of{$p}; }
+		$depth_of{$env_name} = $depth;
+		my $w = ($depth * 2) + length($env_name);
+		$col_width = $w if $w > $col_width;
+	}
+
+	# SHA columns: fixed-width (7-char short SHA + padding).  Displays
+	# the env branch's HEAD and the last successfully deployed commit
+	# side by side so drift is visually obvious.
+	my $sha_col = sub {
+		my ($sha) = @_;
+		return sprintf("%-7s", defined($sha) ? $sha : '-');
+	};
+
+	output "  %s  #u{%-7s}  #u{%-7s}  #u{%s}",
+		' ' x $col_width, 'branch', 'deploy', 'status';
+
+	for my $env_name (@dag_order) {
+		my $state  = $env_state{$env_name};
+		my $status = $state->{status};
+		my $depth  = $depth_of{$env_name};
+		my $indent = '  ' x $depth;
+		my $pad    = $col_width - ($depth * 2) - length($env_name);
+		$pad = 0 if $pad < 0;
+		my $name_col = sprintf("%s%s%s", $indent, $env_name, ' ' x $pad);
+		my $branch   = $sha_col->($state->{branch_sha});
+		my $deployed = $sha_col->($state->{deployed_sha});
+
+		if ($status eq 'deployed') {
+			output "  #G{%s}  %s  %s  #G\@{+}#G{deployed}",
+				$name_col, $branch, $deployed;
+		} elsif ($status eq 'awaiting-deploy') {
+			output "  #C{%s}  %s  %s  #Y\@{O}#Y{synced, pending deploy}",
+				$name_col, $branch, $deployed;
+		} elsif ($status eq 'pending') {
+			my $req_pr  = ($nodes->{$env_name} || {})->{require_pr} // 0;
+			if ($req_pr) {
+				my $open_pr = $gh_open_prs{$env_name};
+				if ($open_pr) {
+					output "  #C{%s}  %s  %s  #Y\@{!}#Y{%d pending} #Yi{[PR #%d open: %s]}",
+						$name_col, $branch, $deployed, $state->{count},
+						$open_pr->{number}, $open_pr->{html_url};
+				} else {
+					output "  #C{%s}  %s  %s  #Y\@{!}#Y{%d pending} #Yi{[PR required]}",
+						$name_col, $branch, $deployed, $state->{count};
+				}
+			} else {
+				output "  #C{%s}  %s  %s  #Y\@{!}#Y{%d pending}",
+					$name_col, $branch, $deployed, $state->{count};
+			}
+		} elsif ($status eq 'blocked') {
+			output "  #C{%s}  %s  %s  #Y\@{!}#Yi{blocked by %s} (%d files)",
+				$name_col, $branch, $deployed, $state->{blocker}, $state->{count};
+		} elsif ($status eq 'no-branch') {
+			output "  #K{%s}  %-7s  %-7s  #K\@{*}#K{not propagated}",
+				$name_col, '-', '-';
+		} elsif ($status eq 'error') {
+			# Branch SHA is git-only — we already have it even if the env
+			# itself couldn't be loaded.  Surface what we know plus the
+			# reason instead of pretending the row is blank.
+			my $reason = $state->{error} || 'unknown reason';
+			output "  #R{%s}  %s  %-7s  #R\@{-}#R{load error}: #Ri{%s}",
+				$name_col, $branch, '-', $reason;
+		}
+	}
+
+	output "";
+	exit 0;
+}
+
+# }}}
+# propagate - route control branch changes to environment branches {{{
+#
+# Must be run from the control branch.  Optional positional argument
+# names an environment whose children should be the propagation scope
+# (cascade after deploy).  Without it, all envs are candidates and
+# the entry point algorithm determines which receive files.
+#
+# Always sources files from control HEAD (or --commit).
+sub propagate {
+	my ($after_env) = @_;
+
+	my $opts    = get_options;
+	my $dry_run = $opts->{'dry-run'};
+	my $no_push = $opts->{'no-push'};
+	my $top     = Genesis::Top->new('.');
+
+	bail("CI is not configured for this repository.")
+		unless $top->ci_configured;
+
+	my $git     = Service::Git->new('.', track_branch => !$dry_run);
+	my $control = Genesis::Top::DEFAULT_CONTROL_BRANCH();
+
 	bail(
-		"No vault specified or configured."
-	) unless $top->vault;
+		"Propagation must be run from the #C{%s} branch (currently on #C{%s}).",
+		$control, $git->current_branch // '<detached>'
+	) unless ($git->current_branch // '') eq $control;
 
-	(my $pipeline, $layout) = Genesis::CI::Legacy::parse(get_options->{config}, $top, $layout);
+	# Bail on uncommitted changes — even on --dry-run.  Propagation
+	# operates on committed state; uncommitted edits to env files
+	# would silently make a dry-run misrepresent reality.
+	bail(
+		"Working tree has uncommitted changes.  Commit or stash them\n".
+		"before running propagate."
+	) unless $git->is_clean;
+
+	# Build the DAG from control branch env files
+	require Genesis::CI::Compiler::ASTBuilder;
+	my $builder = Genesis::CI::Compiler::ASTBuilder->new(
+		top     => $top,
+		env_dir => $top->path,
+	);
+	my ($nodes, $edges) = $builder->_build_from_env_files($top->path);
 
-	option_defaults(target => $layout);
-	my $yaml = Genesis::CI::Legacy::generate_pipeline_concourse_yaml($pipeline, $top);
-	if (get_options->{'dry-run'}) {
-		output({raw => 1}, $yaml);
-		exit 0;
+	bail("No environments with pipeline metadata found.")
+		unless %$nodes;
+
+	my (%children, %has_parent, %parent_of);
+	for my $edge (@$edges) {
+		push @{$children{$edge->{from}}}, $edge->{to};
+		$has_parent{$edge->{to}} = 1;
+		$parent_of{$edge->{to}} = $edge->{from};
+	}
+
+	# Topological order (BFS from roots)
+	my @dag_order;
+	my @queue = sort grep { !$has_parent{$_} } keys %$nodes;
+	my %visited;
+	while (@queue) {
+		my $env = shift @queue;
+		next if $visited{$env}++;
+		push @dag_order, $env;
+		push @queue, sort @{$children{$env} || []};
+	}
+
+	# Refresh env branch refs so diff computations see teammate commits.
+	_fetch_pipeline_envs($top, $git)
+		unless $opts->{'no-fetch'};
+
+	# Resolve the control SHA that will be the source of this propagation.
+	#
+	# Root propagation (no after_env): use control HEAD so freshly-pushed
+	# commits reach the first tier immediately.  This preserves the
+	# "always HEAD" principle that solves the lost-no-op problem.
+	#
+	# Cascade propagation (after_env given): use <after_env>'s last
+	# successfully deployed git.control_commit.  Descendants receive the
+	# exact control state that was CERTIFIED at the ancestor — not
+	# whatever happens to be on HEAD now.  This keeps commits travelling
+	# as a unit down the chain even while control keeps advancing.
+	my $control_sha = $opts->{commit} || $git->sha('HEAD');
+
+	# Determine scope
+	my @scope;
+	if ($after_env) {
+		bail("Environment #C{%s} is not in the pipeline topology.", $after_env)
+			unless $nodes->{$after_env};
+
+		# Verify the after_env has been propagated AND deployed
+		my ($last_sync) = _resolve_propagation_base($after_env, $git);
+		bail(
+			"Environment #C{%s} has never been propagated to.\n".
+			"Run #C{genesis propagate} without arguments first.",
+			$after_env
+		) unless $last_sync;
+
+		my $after_load = eval { $top->load_env($after_env) };
+		if ($after_load) {
+			# Cascade requires a successful deployment with a recorded
+			# git.control_commit.  The env branch being ahead of that
+			# deployment is FINE — cascade intentionally propagates
+			# the certified (last deployed) control state, not whatever
+			# is currently on the env branch.  New changes on control
+			# flow through a fresh root-propagate + deploy cycle.
+			my $env_v = eval { $after_load->with_vault };
+			unless ($env_v) {
+				warning(
+					"Could not verify deployment status for #C{%s} (vault unavailable).\n".
+					"Ensure it has been deployed before cascading.",
+					$after_env
+				);
+			} elsif (!$opts->{commit}) {
+				my $dep = $env_v->deployments->latest_successful;
+				bail(
+					"Environment #C{%s} has never been successfully deployed.\n".
+					"Deploy it before cascading to downstream environments.",
+					$after_env
+				) unless $dep;
+
+				my $certified = $dep->lookup('git.control_commit');
+				bail(
+					"Environment #C{%s} has no #C{git.control_commit} in its\n".
+					"last successful deployment (pre-pipeline deploy?).\n".
+					"Cannot propagate safely - redeploy #C{%s} to record it.",
+					$after_env, $after_env
+				) unless $certified;
+
+				$control_sha = $certified;
+			}
+		}
+
+		my %child_set;
+		my @expand = @{$children{$after_env} || []};
+		while (@expand) {
+			my $e = shift @expand;
+			next if $child_set{$e}++;
+			push @expand, @{$children{$e} || []};
+		}
+		@scope = grep { $child_set{$_} } @dag_order;
+		unless (@scope) {
+			info "\n#Yi{Environment %s has no downstream environments - nothing to propagate.}",
+				$after_env;
+			exit 0;
+		}
+	} else {
+		@scope = @dag_order;
+	}
+
+	my $control_short = $git->sha($control_sha, short => 1);
+	if ($after_env) {
+		info "\n#G{Propagating from} #C{%s} #G{@} #C{%s} #G{(certified by %s)}\n",
+			$control, $control_short, $after_env;
+	} else {
+		info "\n#G{Propagating from} #C{%s} #G{@} #C{%s}\n",
+			$control, $control_short;
+	}
+
+	# Build per-env diffs.  Two diffs per env:
+	#   env_changed    — files on control not yet on the env branch
+	#                    (what we'd copy if this env were an entry point)
+	#   env_undeployed — files on control not yet DEPLOYED from this env
+	#                    (branch may have them but exodus shows an older
+	#                    commit).  Used by the entry-point algorithm so
+	#                    descendants don't cascade past an ancestor that
+	#                    has received a change on-branch but not yet
+	#                    deployed it.
+	my (%env_changed, %env_changed_detail, %env_undeployed, %env_skipped_ahead);
+	for my $env_name (@scope) {
+		next unless $git->branch_exists($env_name);
+		my $env = eval { $top->load_env($env_name) };
+		next unless $env;
+
+		my @dep_files = $env->propagation_files;
+		next unless @dep_files;
+
+		# Cascade-only safety: if this env's last propagation marker
+		# already references a commit equal-to or descended-from
+		# $control_sha, the env is at-or-ahead of the cascade source.
+		# Propagating now would REGRESS its state to an older commit.
+		# Skip the diff entirely so the env shows up in the summary
+		# as "ahead of cascade source" rather than getting silently
+		# rolled back.
+		if ($after_env) {
+			my ($env_last_sync) = _resolve_propagation_base($env_name, $git);
+			if ($env_last_sync
+				&& $git->is_ancestor($control_sha, $env_last_sync)) {
+				$env_skipped_ahead{$env_name} = $git->sha($env_last_sync, short => 1);
+				next;
+			}
+		}
+
+		my $diff = $git->diff_files(
+			$env_name, $control_sha, @dep_files
+		);
+		if (@{$diff->{all}}) {
+			$env_changed{$env_name}        = $diff->{all};
+			$env_changed_detail{$env_name} = $diff;
+		}
+
+		# Compute the undeployed set (for cascade-blocking).
+		#
+		# Anchor is the last-successful deploy's `git.control_commit`
+		# (the control SHA that was propagated when this env last
+		# deployed).  Diff that against control HEAD and filter by
+		# dep_files to get "what's changed on control since this env
+		# last shipped."
+		#
+		# Fallback (no exodus record, vault down, or pre-pipeline
+		# deploy): conservatively treat everything the env would
+		# receive via propagation as undeployed — blocks descendants
+		# from cascading past an env whose state we can't verify.
+		my $last_ctl_sha;
+		my $env_v = eval { $env->with_vault };
+		if ($env_v) {
+			my $dep = eval { $env_v->deployments->latest_successful };
+			$last_ctl_sha = $dep ? ($dep->lookup('git.control_commit') || '') : '';
+		}
+		if ($last_ctl_sha) {
+			my $udiff = $git->diff_files(
+				$last_ctl_sha, $control_sha, @dep_files
+			);
+			$env_undeployed{$env_name} = $udiff->{all} if @{$udiff->{all}};
+		} elsif ($env_changed{$env_name}) {
+			# No deploy history: use the env branch's own pending set
+			$env_undeployed{$env_name} = $env_changed{$env_name};
+		}
+	}
+
+	# Determine entry points
+	my $env_propagate = Genesis::CI::Propagation::compute_propagation_targets(
+		dag_order      => \@dag_order,
+		parent_of      => \%parent_of,
+		env_changed    => \%env_changed,
+		env_undeployed => \%env_undeployed,
+		scope          => \@scope,
+	);
+
+	# Pre-flight: build GitHub service once for all require_pr envs in scope.
+	# Owner/repo is resolved from the remote URL; credentials are validated
+	# against the API before touching any branches.  With --no-push, GitHub
+	# is not contacted (no push, no PR) so credentials are not required.
+	my ($gh_owner, $gh_repo, $github);
+	if (!$dry_run) {
+		my $needs_github = grep {
+			$env_propagate->{$_} && ($nodes->{$_}{require_pr} // 0)
+		} @scope;
+		if ($needs_github) {
+			($gh_owner, $gh_repo) = _github_owner_repo_from_remote($git);
+			bail(
+				"Could not determine GitHub owner/repo from remote URL.\n".
+				"Ensure the origin remote points to a GitHub repository."
+			) unless $gh_owner && $gh_repo;
+
+			unless ($no_push) {
+				bail(
+					"GitHub credentials required for PR-based propagation.\n".
+					"Set the GITHUB_AUTH_TOKEN environment variable."
+				) unless $ENV{GITHUB_AUTH_TOKEN};
+
+				$github = Service::Github->new(org => $gh_owner);
+				my $authed_user = $github->get_authorized_user;
+				bail(
+					"GitHub credentials are invalid or lack sufficient permissions.\n".
+					"Verify GITHUB_AUTH_TOKEN is a valid Personal Access Token."
+				) unless $authed_user;
+			}
+		}
+	}
+
+	# Propagate to entry point envs
+	my $propagated = 0;
+	my @pushed_branches;
+	my @pr_targets;
+	my $error;
+	for my $env_name (@scope) {
+		next unless $env_propagate->{$env_name};
+
+		my $detail  = $env_changed_detail{$env_name}
+			|| { changed => $env_propagate->{$env_name}, deleted => [], renamed => {} };
+		my @to_copy = @{$detail->{changed}};
+		my @to_rm   = @{$detail->{deleted}};
+		my %renames = %{$detail->{renamed}};
+		my $total      = scalar(@to_copy) + scalar(@to_rm);
+		my $msg        = sprintf("[pipeline] control\@%s -> %s", $control_short, $env_name);
+		my $require_pr = $nodes->{$env_name}{require_pr} // 0;
+		my $prop_branch = "propagate/$env_name/$control_short";
+
+		if ($dry_run) {
+			info "  #C{%s}: %d file%s to propagate", $env_name, $total, $total == 1 ? '' : 's';
+			for my $f (@to_copy) {
+				my ($old) = grep { $renames{$_} eq $f } keys %renames;
+				my ($disp_f)   = $git->unprefixed($f);
+				my ($disp_old) = $old ? $git->unprefixed($old) : ();
+				my $note = $old ? " #Yi{(renamed from $disp_old)}" : '';
+				info "    #G{M} %s%s", $disp_f, $note;
+			}
+			info "    #R{D} %s", $_ for $git->unprefixed(@to_rm);
+			info "    #Yi{commit}: %s", $msg;
+			if ($require_pr) {
+				info "    #Yi{PR}: would open %s -> %s", $prop_branch, $env_name;
+			}
+			$propagated++;
+		} elsif ($require_pr) {
+			# PR-based propagation: commit onto a short-lived propagation branch.
+			# Idempotency is checked via the GitHub API when credentials are
+			# available (normal run), or via local branch existence when not
+			# (--no-push).  If an open PR is found on the remote, the branch is
+			# fetched rather than re-created.
+			eval {
+				my $existing_pr;
+
+				if ($github) {
+					my $prs = $github->list_prs("$gh_owner/$gh_repo",
+						head  => $prop_branch,
+						base  => $env_name,
+						state => 'open',
+					);
+					($existing_pr) = grep { $_->{head}{ref} eq $prop_branch } @$prs;
+				}
+
+				if ($existing_pr) {
+					unless ($git->branch_exists($prop_branch)) {
+						$git->fetch_branch($prop_branch);
+					}
+					$git->checkout($prop_branch);
+					info "  #Yi{%s}: PR #%d already open, reusing branch #C{%s}",
+						$env_name, $existing_pr->{number}, $prop_branch;
+				} elsif ($git->branch_exists($prop_branch)) {
+					# --no-push re-run: local branch exists, no PR yet
+					$git->checkout($prop_branch);
+					info "  #Yi{%s}: reusing local propagation branch #C{%s}",
+						$env_name, $prop_branch;
+				} else {
+					$git->checkout($env_name);
+					$git->create_branch($prop_branch);
+					$git->checkout($prop_branch);
+					$git->checkout_file($control_sha, $_) for @to_copy;
+					$git->rm(@to_rm)                      if @to_rm;
+					$git->commit($msg, @to_copy);
+					info "  #G{%s}: committed %d file%s to #C{%s}",
+						$env_name, $total, $total == 1 ? '' : 's', $prop_branch;
+					for my $f (@to_copy) {
+						my ($old) = grep { $renames{$_} eq $f } keys %renames;
+						my ($disp_f)   = $git->unprefixed($f);
+						my ($disp_old) = $old ? $git->unprefixed($old) : ();
+						my $note = $old ? " #Yi{(renamed from $disp_old)}" : '';
+						info "    #G{M} %s%s", $disp_f, $note;
+					}
+					info "    #R{D} %s", $_ for $git->unprefixed(@to_rm);
+				}
+
+				push @pushed_branches, $prop_branch unless $no_push;
+				push @pr_targets, {
+					env      => $env_name,
+					branch   => $prop_branch,
+					detail   => $detail,
+					existing => $existing_pr,
+				};
+				$propagated++;
+			};
+			if ($@) {
+				$error = $@;
+				$git->reset_working_tree;
+				warning("PR propagation to #C{%s} failed: %s",
+					$env_name, $error =~ s/\s+$//r);
+				last;
+			}
+		} else {
+			eval {
+				$git->checkout($env_name);
+				$git->checkout_file($control_sha, $_) for @to_copy;
+				$git->rm(@to_rm)                      if @to_rm;
+				$git->commit($msg, @to_copy);
+				info "  #G{%s}: propagated %d file%s", $env_name, $total, $total == 1 ? '' : 's';
+				for my $f (@to_copy) {
+					my ($old) = grep { $renames{$_} eq $f } keys %renames;
+					my ($disp_f)   = $git->unprefixed($f);
+					my ($disp_old) = $old ? $git->unprefixed($old) : ();
+					my $note = $old ? " #Yi{(renamed from $disp_old)}" : '';
+					info "    #G{M} %s%s", $disp_f, $note;
+				}
+				info "    #R{D} %s", $_ for $git->unprefixed(@to_rm);
+				push @pushed_branches, $env_name;
+				$propagated++;
+			};
+			if ($@) {
+				$error = $@;
+				$git->reset_working_tree;
+				warning("Propagation to #C{%s} failed: %s",
+					$env_name, $error =~ s/\s+$//r);
+				last;
+			}
+		}
+	}
+
+	# Restore branch explicitly (DESTROY would too, but be clear)
+	$git->restore_branch unless $dry_run;
+	bail("Propagation aborted due to error.") if $error;
+
+	# Push control and propagated/PR branches to remote
+	if ($propagated && !$dry_run && !$no_push) {
+		my $remote = $git->default_remote;
+		if ($remote) {
+			info "\n#G{Pushing} to #C{%s}...", $remote;
+			my $results = $git->push($remote, $control, @pushed_branches);
+			for my $branch (@pushed_branches) {
+				if ($results->{$branch}) {
+					info "  #G{%s}: pushed", $branch;
+				} else {
+					warning("Failed to push #C{%s} to #C{%s}.", $branch, $remote);
+				}
+			}
+		}
+
+		# Open or update GitHub PRs for require_pr environments.
+		# $github is only set when credentials were validated; @pr_targets
+		# is only populated for require_pr envs; both guards are needed.
+		if (@pr_targets && $github) {
+			my $owner_repo = "$gh_owner/$gh_repo";
+			info "\n#G{Opening pull requests} on #C{%s}...", $owner_repo;
+			for my $pt (@pr_targets) {
+				my $pr_env    = $pt->{env};
+				my $pr_branch = $pt->{branch};
+				my $pr_title  = sprintf("[pipeline] propagate control\@%s to %s",
+					$control_short, $pr_env);
+				my $pr_body = _build_pr_body($pr_env, $control_sha, $control_short, $pt->{detail});
+				eval {
+					my $pr = _find_or_open_pr(
+						$github, $owner_repo, $pr_branch, $pr_env,
+						$pr_title, $pr_body, $pt->{existing}
+					);
+					info "  #G{%s}: PR #%d %s", $pr_env, $pr->{number}, $pr->{html_url};
+				};
+				if ($@) {
+					warning("Failed to open/update PR for #C{%s}: %s",
+						$pr_env, $@ =~ s/\s+$//r);
+				}
+			}
+		}
+	}
+
+	# Report any envs we deliberately skipped because they were already
+	# at-or-ahead of the cascade source (avoids silent regressions).
+	if (%env_skipped_ahead) {
+		info "";
+		for my $env_name (sort keys %env_skipped_ahead) {
+			info "  #Y{%s}: skipped - already at #C{%s} (more recent %s commit)",
+				$env_name, $env_skipped_ahead{$env_name}, $control;
+		}
 	}
 
-	my ($out,$rc) = run(
-		'fly -t $1 pause-pipeline -p $2',
-		get_options->{target}, $pipeline->{pipeline}{name}
+	if ($propagated) {
+		info "\n#G{Done.} %s %d environment%s.",
+			$dry_run ? "Would propagate to" : "Propagated to",
+			$propagated, $propagated == 1 ? '' : 's';
+	} elsif (%env_skipped_ahead) {
+		info "\n#Yi{No changes to propagate (downstream envs already up-to-date or ahead).}";
+	} else {
+		info "\n#Yi{No changes to propagate.}";
+	}
+	exit 0;
+}
+
+# _fetch_pipeline_envs - bulk-fetch all pipeline env branches in one round-trip {{{
+#
+#   _fetch_pipeline_envs($top, $git)
+#
+# Walks the pipeline DAG to collect env names, then calls fetch_branches
+# with a single git fetch (one auth prompt regardless of branch count).
+# Control and any other non-env branches are never included in the
+# refspecs.  No-op when CI is not configured or no remote is reachable.
+# Silently swallows fetch errors so offline use never aborts a command.
+sub _fetch_pipeline_envs {
+	my ($top, $git) = @_;
+	return unless $top->ci_configured;
+	my $remote = $git->default_remote;
+	return unless $remote;
+	require Genesis::CI::Compiler::ASTBuilder;
+	my $builder = Genesis::CI::Compiler::ASTBuilder->new(
+		top     => $top,
+		env_dir => $top->path,
 	);
-	bail("Could not pause #c{%s} pipeline: $out", $pipeline->{pipeline}{name})
-		unless $rc == 0 || $out =~ /pipeline '.*' not found/;
+	my ($nodes) = $builder->_build_from_env_files($top->path);
+	return unless $nodes && %$nodes;
+	eval { $git->fetch_branches([sort keys %$nodes], $remote) };
+}
+
+# }}}
+# _resolve_propagation_base - find the control SHA to diff from for an env branch {{{
+#
+# Resolution order:
+#   1. Scan commit log for most recent [pipeline] control@<sha> → use that
+#      (warns if it's not the HEAD commit, meaning manual commits were added)
+#   2. No propagation commit found → branch was spawned from control, use
+#      git merge-base as the starting point
+#
+# Returns: ($control_sha_full, $manual_commits_on_top)
+# _summarize_load_error - extract a short, actionable reason from a
+# load_env failure for the pipeline-status display.  bail() output is
+# multi-line and decorated; we strip the noise and keep the first
+# substantive line.
+sub _summarize_load_error {
+	my ($err) = @_;
+	return 'unknown reason' unless defined($err) && length($err);
+
+	# Strip ANSI color escapes and structural prose
+	$err =~ s/\e\[[0-9;]*m//g;
+	$err =~ s/\[FATAL\]\s*//g;
+	$err =~ s/Environment\s+\S+\s+could not be loaded:\s*//g;
+	$err =~ s/Please fix the above errors and try again\.\s*//g;
+
+	# Take the first non-blank line that looks like a reason
+	my $reason;
+	for my $line (split /\n/, $err) {
+		$line =~ s/^\s*-\s+//;     # bullet prefix
+		$line =~ s/^\s+|\s+$//g;
+		next unless length $line;
+		next if $line =~ /^at \S+ line \d+/;  # perl trace frames
+		$reason = $line;
+		last;
+	}
+	$reason //= 'unknown reason';
+
+	# Trim to fit on one terminal row alongside the rest of the row
+	$reason = substr($reason, 0, 80) . '...' if length($reason) > 80;
+	return $reason;
+}
+
+sub _resolve_propagation_base {
+	my ($branch, $git) = @_;
+	$git ||= Service::Git->new('.');
+	my $control = Genesis::Top::DEFAULT_CONTROL_BRANCH();
+
+	# Scan log for propagation markers
+	my @lines = $git->log_subjects($branch);
+	my $depth = 0;
+	for my $line (@lines) {
+		if ($line =~ /^[0-9a-f]+ \[pipeline\] control\@([0-9a-f]+)/) {
+			my $full = $git->sha($1);
+			if ($depth > 0) {
+				warning(
+					"Branch #C{%s} has %d manual commit%s on top of the last propagation.",
+					$branch, $depth, $depth == 1 ? '' : 's'
+				);
+			}
+			return ($full, $depth);
+		}
+		$depth++;
+	}
+
+	# No propagation commit — use merge-base with control
+	my $merge_base = $git->merge_base($control, $branch);
+	return ($merge_base, 0) if $merge_base;
+
+	return (undef, 0);
+}
+# }}}
+# _verify_deployed - check that an env's propagated state was deployed {{{
+#
+# Compares the env branch HEAD against the git.commit field in the
+# latest successful deployment's exodus audit data.  Requires vault.
+# Warns and allows cascade if vault is unavailable.
+sub _verify_deployed {
+	my ($env_name, $env, $git) = @_;
+
+	my $branch_head = $git->sha($env_name);
+
+	# Vault access is required — soft-fail if unavailable
+	my $env_with_vault = eval { $env->with_vault };
+	unless ($env_with_vault) {
+		warning(
+			"Could not verify deployment status for #C{%s} (vault unavailable).\n".
+			"Ensure it has been deployed before cascading.",
+			$env_name
+		);
+		return;
+	}
+
+	my $deployment = $env_with_vault->deployments->latest_successful;
+	bail(
+		"Environment #C{%s} has never been successfully deployed.\n".
+		"Deploy it before cascading to downstream environments.",
+		$env_name
+	) unless $deployment;
+
+	my $deployed_commit = $deployment->lookup('git.commit') || '';
+	if ($deployed_commit && $deployed_commit ne $branch_head) {
+		bail(
+			"Environment #C{%s} has been propagated but not yet deployed\n".
+			"with the latest changes.  Deploy it before cascading to\n".
+			"downstream environments.",
+			$env_name
+		);
+	} elsif (!$deployed_commit) {
+		# Pre-pipeline deployment (no git context in exodus) — warn only
+		warning(
+			"Environment #C{%s} was deployed before pipeline tracking was enabled.\n".
+			"Cannot verify deployment state — ensure it has been deployed.",
+			$env_name
+		);
+	}
+}
+# }}}
+# _github_owner_repo_from_remote - parse owner and repo from the git remote URL {{{
+#
+# Supports SSH (git@github.com:owner/repo.git) and HTTPS formats.
+# Returns (owner, repo) or (undef, undef) on failure.
+sub _github_owner_repo_from_remote {
+	my ($git) = @_;
+	my $url = $git->remote_url($git->default_remote) or return (undef, undef);
+	if ($url =~ m{github\.com[:/]([^/]+)/([^/.]+?)(?:\.git)?\s*$}) {
+		return ($1, $2);
+	}
+	return (undef, undef);
+}
+# }}}
+# _build_pr_body - compose the pull request description {{{
+sub _build_pr_body {
+	my ($env_name, $control_sha, $control_short, $detail) = @_;
+	my @changed = @{$detail->{changed} || []};
+	my @deleted = @{$detail->{deleted} || []};
+	my %renames = %{$detail->{renamed} || {}};
+
+	my @lines = (
+		"Propagating `control\@$control_short` to `$env_name`",
+		"",
+		"**Control SHA:** \`$control_sha\`",
+		"",
+	);
+
+	if (@changed) {
+		push @lines, "**Changed files:**";
+		for my $f (@changed) {
+			my ($old) = grep { $renames{$_} eq $f } keys %renames;
+			push @lines, $old ? "- \`$f\` *(renamed from \`$old\`)*" : "- \`$f\`";
+		}
+		push @lines, "";
+	}
+
+	if (@deleted) {
+		push @lines, "**Deleted files:**";
+		push @lines, "- \`$_\`" for @deleted;
+		push @lines, "";
+	}
+
+	push @lines, "---";
+	push @lines, "_[pipeline] control\@$control_short -> ${env_name}_";
+
+	return join("\n", @lines);
+}
+# }}}
+# _find_or_open_pr - create a PR or update the existing one for this propagation branch {{{
+#
+# Accepts an optional $existing PR object (pre-fetched during the propagation
+# loop) to avoid a redundant list_prs call.  Falls back to querying GitHub
+# when $existing is not provided.
+sub _find_or_open_pr {
+	my ($github, $owner_repo, $prop_branch, $env_name, $title, $body, $existing) = @_;
+
+	unless ($existing) {
+		my $prs = $github->list_prs($owner_repo,
+			head  => $prop_branch,
+			base  => $env_name,
+			state => 'open',
+		);
+		($existing) = grep { $_->{head}{ref} eq $prop_branch } @$prs;
+	}
+
+	return $existing
+		? $github->update_pr($owner_repo, $existing->{number},
+			title => $title,
+			body  => $body,
+		)
+		: $github->create_pr($owner_repo,
+			head  => $prop_branch,
+			base  => $env_name,
+			title => $title,
+			body  => $body,
+		);
+}
+# }}}
+
+# }}}
+# pipeline_graph - write pipeline.md with Mermaid flowchart {{{
+sub pipeline_graph {
+	my ($layout) = @_;
+	option_defaults(config => 'ci.yml');
+
+	my $opts = get_options;
+	my $top  = Genesis::Top->new('.');
+
+	# For env-file topology, build the DAG directly.
+	if ($top->ci_configured) {
+		my $env_dir = $top->path;
+		require Genesis::CI::Compiler::ASTBuilder;
+		my $builder = Genesis::CI::Compiler::ASTBuilder->new(
+			top     => $top,
+			env_dir => $env_dir,
+		);
+		my ($nodes, $edges) = $builder->_build_from_env_files($env_dir);
+		my $md = _topology_to_mermaid_md($top, $nodes, $edges);
+		mkfile_or_fail('pipeline.md', $md);
+		info("Wrote #C{pipeline.md}");
+		exit 0;
+	}
+
+	# Full compiler path for legacy/multi-file configurations
+	my $platform = $opts->{platform} || 'concourse';
+	my $result   = _compile_pipeline($top, $platform);
+	my $ast      = $result->{ast};
+	my $provider = $result->{provider};
+
+	my $md = $provider->can('graph_md')
+		? $provider->graph_md()
+		: _ast_to_mermaid_md($ast);
+
+	mkfile_or_fail('pipeline.md', $md);
+	info("Wrote #C{pipeline.md}");
+	exit 0;
+}
+
+# }}}
+# pipeline_describe - human-readable pipeline progression {{{
+sub pipeline_describe {
+	my ($layout) = @_;
+	option_defaults(config => 'ci.yml');
+
+	my $opts     = get_options;
+	my $top      = Genesis::Top->new('.');
+
+	# For env-file topology (manual provider or genesis-config CI),
+	# build the DAG directly without the full compiler/provider chain.
+	if ($top->ci_configured) {
+		my $env_dir = $top->path;
+		require Genesis::CI::Compiler::ASTBuilder;
+		my $builder = Genesis::CI::Compiler::ASTBuilder->new(
+			top     => $top,
+			env_dir => $env_dir,
+		);
+		my ($nodes, $edges) = $builder->_build_from_env_files($env_dir);
+		_describe_topology($top, $nodes, $edges);
+		exit 0;
+	}
+
+	# Full compiler path for legacy/multi-file configurations
+	my $platform = $opts->{platform} || 'concourse';
+	my $result   = _compile_pipeline($top, $platform);
+	my $ast      = $result->{ast};
+	my $provider = $result->{provider};
+
+	if ($provider->can('generate_description')) {
+		$provider->generate_description($ast);
+	} else {
+		_describe_ast($ast, $platform);
+	}
+	exit 0;
+}
+
+# }}}
+# diff - show compiled vs live pipeline delta {{{
+sub diff {
+	option_defaults(config => 'ci.yml');
+
+	my $opts     = get_options;
+	my $platform = $opts->{platform} || 'concourse';
+
+	bail("diff is only supported for the 'concourse' platform")
+		unless $platform eq 'concourse';
+
+	my $top    = _get_top($opts, skip_vault => 1);
+	my $result = _compile_pipeline($top, $platform);
+	my $ast    = $result->{ast};
+	my $output = $result->{output};
+
+	my $name   = $ast->metadata->{name}
+		or bail("Pipeline AST has no name defined");
+	my ($target, $k_flag) = _concourse_fly_flags($result, $opts, $name);
+
+	my $compiled = $output->{'pipeline.yml'}
+		or bail("Concourse provider did not produce pipeline.yml");
 
-	my $yes = get_options->{yes} ? ' -n ' : '';
 	my $dir = workdir;
-	mkfile_or_fail("${dir}/pipeline.yml", $yaml);
-	run({ interactive => 1, onfailure => "Could not upload pipeline $pipeline->{pipeline}{name}" },
-		'fly -t $1 set-pipeline '.$yes.' -p $2 -c $3/pipeline.yml',
-		get_options->{target}, $pipeline->{pipeline}{name}, $dir);
+	mkfile_or_fail("$dir/compiled.yml", $compiled);
 
-	run(
-		{ interactive => 1, onfailure => "Could not unpause pipeline $pipeline->{pipeline}{name}" },
-		'fly -t $1 unpause-pipeline -p $2',
-		get_options->{target}, $pipeline->{pipeline}{name}
-	) unless (get_options->{paused});
+	my ($live, $rc) = run("fly${k_flag} -t \$1 get-pipeline -p \$2", $target, $name);
+	if ($rc != 0) {
+		info("#Y{Pipeline '%s' does not exist on target '%s' — nothing to diff against.}",
+			$name, $target);
+		info("Run #C{genesis pipeline-apply} to deploy it first.");
+		exit 0;
+	}
+	mkfile_or_fail("$dir/live.yml", $live);
+
+	my ($diff_out, $diff_rc) = run(
+		'diff -u --label live --label compiled $1 $2',
+		"$dir/live.yml", "$dir/compiled.yml"
+	);
+
+	if ($diff_rc == 0) {
+		info("#G{No differences} — compiled pipeline matches live pipeline.");
+	} else {
+		output({raw => 1}, $diff_out);
+	}
+	exit 0;
+}
+
+# }}}
+# status - show per-env job health {{{
+sub status {
+	my ($filter_env) = @_;
+	option_defaults(config => 'ci.yml');
+
+	my $opts     = get_options;
+	my $platform = $opts->{platform} || 'concourse';
+
+	bail("status is only supported for the 'concourse' platform")
+		unless $platform eq 'concourse';
+
+	my $top    = _get_top($opts, skip_vault => 1);
+	my $result = _compile_pipeline($top, $platform);
+	my $ast    = $result->{ast};
+	my $name   = $ast->metadata->{name}
+		or bail("Pipeline AST has no name defined");
+	my ($target, $k_flag) = _concourse_fly_flags($result, $opts, $name);
+
+	my ($json_out, $rc) = run("fly${k_flag} -t \$1 jobs -p \$2 --json", $target, $name);
+	bail("Could not get jobs for pipeline '%s' on target '%s': %s", $name, $target, $json_out)
+		unless $rc == 0;
+
+	my $jobs;
+	eval { $jobs = JSON::PP->new->decode($json_out) };
+	bail("Failed to parse fly jobs output: %s", $@) if $@;
+
+	output "#G{Pipeline}: #C{%s}  (#Yi{target}: %s)", $name, $target;
+	output "";
+
+	my %job_by_name = map { $_->{name} => $_ } @$jobs;
+
+	my @ordered_names;
+	for my $wf_name ($ast->workflow_names) {
+		my @stage_order = eval { $ast->workflow_stage_order($wf_name) };
+		if (@stage_order) {
+			my $nodes = ($ast->workflows->{$wf_name} || {})->{graph}{nodes} || {};
+			push @ordered_names, map { $nodes->{$_}{alias} || $_ } @stage_order;
+		}
+	}
+	my %seen = map { $_ => 1 } @ordered_names;
+	push @ordered_names, sort grep { !$seen{$_} } keys %job_by_name;
+
+	my $col_w = 40;
+	output "  %-${col_w}s  %-10s  %s", "Environment", "Status", "Notes";
+	output "  %s  %s  %s", '-' x $col_w, '-' x 10, '-' x 20;
+
+	for my $job_name (@ordered_names) {
+		next if $filter_env && $job_name ne $filter_env;
+		my $job = $job_by_name{$job_name} or next;
+
+		my $status = _job_status_label($job);
+		my @notes;
+		push @notes, 'paused'  if $job->{paused};
+		push @notes, 'errored' if ($job->{finished_build} || {})->{status} eq 'errored';
+
+		output "  %-${col_w}s  %-10s  %s",
+			$job_name,
+			$status,
+			join(', ', @notes) || '';
+	}
+	output "";
+	exit 0;
+}
+
+# }}}
+# pause - pause env job or entire pipeline {{{
+sub pause {
+	my ($env) = @_;
+	option_defaults(config => 'ci.yml');
+
+	my $opts     = get_options;
+	my $platform = $opts->{platform} || 'concourse';
+
+	bail("pause is only supported for the 'concourse' platform")
+		unless $platform eq 'concourse';
+
+	my $top    = _get_top($opts, skip_vault => 1);
+	my $result = _compile_pipeline($top, $platform);
+	my $ast    = $result->{ast};
+	my $name   = $ast->metadata->{name}
+		or bail("Pipeline AST has no name defined");
+	my ($target, $k_flag) = _concourse_fly_flags($result, $opts, $name);
+
+	if ($env) {
+		run({ interactive => 1,
+		      onfailure => "Could not pause job '$env' in pipeline '$name'" },
+			"fly${k_flag} -t \$1 pause-job -p \$2 -j \$3",
+			$target, $name, $env);
+		info("Paused job #C{%s} in pipeline #C{%s}", $env, $name);
+	} else {
+		run({ interactive => 1,
+		      onfailure => "Could not pause pipeline '$name'" },
+			"fly${k_flag} -t \$1 pause-pipeline -p \$2",
+			$target, $name);
+		info("Paused pipeline #C{%s}", $name);
+	}
+	exit 0;
+}
+
+# }}}
+# resume - resume env job or entire pipeline {{{
+sub resume {
+	my ($env) = @_;
+	option_defaults(config => 'ci.yml');
+
+	my $opts     = get_options;
+	my $platform = $opts->{platform} || 'concourse';
 
-	my $action = ($pipeline->{pipeline}{public} ? 'expose' : 'hide');
-	run({ interactive => 1, onfailure => "Could not $action pipeline $pipeline->{pipeline}{name}" },
-		'fly -t $1 '.$action.'-pipeline -p $2',
-		get_options->{target}, $pipeline->{pipeline}{name});
+	bail("resume is only supported for the 'concourse' platform")
+		unless $platform eq 'concourse';
 
+	my $top    = _get_top($opts, skip_vault => 1);
+	my $result = _compile_pipeline($top, $platform);
+	my $ast    = $result->{ast};
+	my $name   = $ast->metadata->{name}
+		or bail("Pipeline AST has no name defined");
+	my ($target, $k_flag) = _concourse_fly_flags($result, $opts, $name);
+
+	if ($env) {
+		run({ interactive => 1,
+		      onfailure => "Could not resume job '$env' in pipeline '$name'" },
+			"fly${k_flag} -t \$1 unpause-job -p \$2 -j \$3",
+			$target, $name, $env);
+		info("Resumed job #C{%s} in pipeline #C{%s}", $env, $name);
+	} else {
+		run({ interactive => 1,
+		      onfailure => "Could not resume pipeline '$name'" },
+			"fly${k_flag} -t \$1 unpause-pipeline -p \$2",
+			$target, $name);
+		info("Resumed pipeline #C{%s}", $name);
+	}
 	exit 0;
 }
 
+# }}}
+# }}}
+### Deprecated Commands {{{
+
+# repipe - deprecated; delegates to apply {{{
+sub repipe {
+	warning("'genesis repipe' is deprecated and will be removed in a future version.  Use 'genesis pipeline-apply' instead.");
+	apply(@_);
+}
+
+# }}}
+# graph - deprecated; legacy graphviz without --platform, modern pipeline.md with {{{
 sub graph {
 	warning("'genesis graph' is deprecated and will be removed in a future version.  Use 'genesis pipeline-graph' instead.");
 	option_defaults(config => 'ci.yml');
 	my $layout = $_[0];
-	my $top = Genesis::Top->new('.');
+	my $top    = Genesis::Top->new('.');
 
-	# New compiler pipeline when --platform is specified
 	if (get_options->{platform}) {
-		return _graph_compiled($top, $layout);
+		return pipeline_graph($layout);
 	}
 
 	(my $pipeline, $layout) = Genesis::CI::Legacy::parse(get_options->{config}, $top, $layout);
@@ -113,29 +1326,22 @@ sub graph {
 	exit 0;
 }
 
+# }}}
+# describe - deprecated; delegates to pipeline_describe {{{
 sub describe {
 	warning("'genesis describe' is deprecated and will be removed in a future version.  Use 'genesis pipeline-describe' instead.");
-	option_defaults(config => 'ci.yml');
-	my $layout = $_[0];
-	my $top = Genesis::Top->new('.');
-
-	# New compiler pipeline when --platform is specified
-	if (get_options->{platform}) {
-		return _describe_compiled($top, $layout);
-	}
-
-	(my $pipeline, $layout) = Genesis::CI::Legacy::parse(get_options->{config}, $top, $layout);
-	Genesis::CI::Legacy::generate_pipeline_human_description($pipeline);
-	exit 0;
+	pipeline_describe(@_);
 }
 
+# }}}
+# }}}
+### CI Task Commands {{{
+
 sub ci_pipeline_deploy {
 	command_usage(1) if @_;
 
 	info("[#G{genesis} ci-pipeline-deploy] v#G{$Genesis::VERSION}\n");
 
-	# TODO: support detection of required vars in the prepare_command step. (maybe
-	# show optional variables with a ? after them, or ?1a ?1b to show either/or
 	my @undefined = grep { !$ENV{$_} }
 		qw/CURRENT_ENV GIT_BRANCH OUT_DIR WORKING_DIR VAULT_ROLE_ID VAULT_SECRET_ID VAULT_ADDR/;
 	push @undefined, "CACHE_DIR" if ($ENV{PREVIOUS_ENV} && ! $ENV{CACHE_DIR});
@@ -145,21 +1351,18 @@ sub ci_pipeline_deploy {
 		"The pipeline must specify either GIT_PRIVATE_KEY, or GIT_USERNAME and ".
 		"GIT_PASSWORD"
 	) unless $ENV{GIT_PRIVATE_KEY} || ($ENV{GIT_USERNAME} && $ENV{GIT_PASSWORD});
-	# FIXME: Support Bearer Token
 
 	_vault_auth();
 
 	_propagate_previous_passed_files();
 
-	# Load the environment in order to check other required variables
 	my $workdir = $ENV{WORKING_DIR};
 	$workdir .= "/$ENV{GIT_GENESIS_ROOT}" if (defined($ENV{GIT_GENESIS_ROOT}) && $ENV{GIT_GENESIS_ROOT} ne "");
 	pushd $workdir;
 	my $env = Genesis::Top->new('.')->load_env($ENV{CURRENT_ENV})->with_vault();
 
 	if ($env->use_create_env) {
-		# Make sure that state is up to date. Keep environment changes local to this scope.
-		my $tmp = workdir;
+		my $tmp     = workdir;
 		my $git_env = _get_git_env($tmp);
 		run({ onfailure   => "Could not reset to the latest state file from origin. State file may not exist, which occurs if the proto bosh has not been deployed once manually.",
 			interactive => 1,
@@ -168,7 +1371,7 @@ sub ci_pipeline_deploy {
 			$ENV{GIT_BRANCH}, $ENV{CURRENT_ENV});
 	}
 
-	_bail_on_missing_pipeline_environment_variables(@undefined); # FIXME -- is this needed?
+	_bail_on_missing_pipeline_environment_variables(@undefined);
 
 	info "Preparing to deploy #C{%s}:\n  - based on kit #c{%s}", $env->name, $env->kit->id;
 	if ($env->use_create_env) {
@@ -180,11 +1383,11 @@ sub ci_pipeline_deploy {
 
 	my $result;
 	my %deploy_opts = (
-		redact => !envset('CI_NO_REDACT'),
-		'disable-reactions' => 0,
-		'yes' => 1,
+		redact               => !envset('CI_NO_REDACT'),
+		'disable-reactions'  => 0,
+		'yes'                => 1,
 	);
-	$ENV{BOSH_NON_INTERACTIVE} = 'true'; # Doesn't work without this...
+	$ENV{BOSH_NON_INTERACTIVE} = 'true';
 	eval {
 		$result = $env->with_bosh
 		              ->download_required_configs('deploy')
@@ -193,7 +1396,6 @@ sub ci_pipeline_deploy {
 
 	if ($@ || !$result) {
 		error "#R{Deployment failed!}\n%s", $@ || "";
-		# Make sure to commit the state file in the case of failure
 		if ($env->use_create_env) {
 			popd;
 			_commit_changes(
@@ -206,13 +1408,10 @@ sub ci_pipeline_deploy {
 	}
 
 	if ($ENV{PREVIOUS_ENV}) {
-		## rm cache dir
-		## copy previous env cache dir
-		# leaving as system calls for Concourse so output shows up in log
 		system("rm -rf .genesis/config .genesis/kits .genesis/cached") == 0 or exit 1;
-		system("git checkout .genesis/config"); # ignore failure for git checkout so that
-		system("git checkout .genesis/kits");   # we don't cause problems if these files dont
-		system("git checkout .genesis/cached"); # yet exist in the working tree (but did in the cache tree)
+		system("git checkout .genesis/config");
+		system("git checkout .genesis/kits");
+		system("git checkout .genesis/cached");
 	}
 	popd;
 	_commit_changes($ENV{WORKING_DIR}, $ENV{OUT_DIR}, $ENV{GIT_BRANCH},
@@ -238,7 +1437,6 @@ sub ci_show_changes {
 
 	my $mismatches = _propagate_previous_passed_files();
 
-	# Load the environment in order to check other required variables
 	my $workdir = $ENV{WORKING_DIR};
 	$workdir .= "/$ENV{GIT_GENESIS_ROOT}" if (defined($ENV{GIT_GENESIS_ROOT}) && $ENV{GIT_GENESIS_ROOT} ne "");
 	pushd $workdir;
@@ -297,7 +1495,7 @@ current_variables="$(bosh int <(bosh curl "/deployments/${deployment}/variables"
 bosh diff-config --json \
 		 --from-content <(bosh int <(spruce merge --fallback-append <(echo "${current_configs}") <(echo "${current_manifest}") <(echo "${current_variables}"))) \
 		 --to-content <(bosh int <(spruce merge --fallback-append <(echo "${new_configs}") <(echo "${new_manifest}") <(echo "${new_variables}")) -l ${vars_file}) \
-		 | jq -r '.Tables[0].Rows[0] | if (.diff == "" ) then "No differences found." else .diff end'
+		 | jq -r '.Tables[0].Rows[0] | if (.diff == "" ) then "[32;1mNo differences found.[0m" else .diff end'
 EOF
 
 	my %envvars = $env->get_environment_variables();
@@ -320,10 +1518,9 @@ EOF
 				$differences += 1; last;
 			}
 			my $cache_file = slurp("$ENV{CACHE_DIR}/$_");
-			my $work_file = slurp("$ENV{WORKING_DIR}/$_");
-			unless ($cache_file eq $work_file) { $differences += 1; last; };
+			my $work_file  = slurp("$ENV{WORKING_DIR}/$_");
+			unless ($cache_file eq $work_file) { $differences += 1; last; }
 		}
-
 		@extra = () unless $differences;
 	}
 
@@ -356,23 +1553,8 @@ sub ci_generate_cache {
 
 	command_usage(1) if @_;
 
-	# environment variables we should have
-	#   CURRENT_ENV     - Name of the current environment
-	#   GIT_BRANCH      - Name of the git branch to push commits to. post-deploy
-	#   GIT_PRIVATE_KEY - Private Key to use for pushing commits, post-deploy, ssh
-	#   GIT_USERNAME    - Username to use for pushing commits, post-deploy, https
-	#   GIT_PASSWORD    - Password to use for pushing commits, post-deploy, https
-	#   PREVIOUS_ENV    - Name of the previous env, or null if none
-	#   CACHE_DIR       - Path to the directory of the previous environment's cache
-	#   WORKING_DIR     - Path to the directory to deploy/work from
-	#   OUT_DIR         - Path to the directory to output to
-	#
-	# TODO: Detect if we need to run genesis from a different directory, based
-	# on the min genesis version of the environment for cached, changes, or git
-	# repo.
 	my @undefined = grep { !$ENV{$_} }
-		qw/CURRENT_ENV GIT_BRANCH
-			 WORKING_DIR OUT_DIR/;
+		qw/CURRENT_ENV GIT_BRANCH WORKING_DIR OUT_DIR/;
 	push(@undefined, 'CACHE_DIR') if $ENV{PREVIOUS_ENV} && ! $ENV{CACHE_DIR};
 	_bail_on_missing_pipeline_environment_variables(@undefined);
 	bail("The pipeline must specify either GIT_PRIVATE_KEY, or GIT_USERNAME and GIT_PASSWORD")
@@ -414,18 +1596,6 @@ sub ci_pipeline_run_errand {
 
 	command_usage(1) if @_;
 
-	# environment variables we should have
-	#   CURRENT_ENV         - Name of the current environment
-	#   ERRAND_NAME         - Name of the Smoke Test errand to run
-	#
-	#   VAULT_ROLE_ID       - Vault RoleID to authenticate to Vault with
-	#   VAULT_SECRET_ID     - Vault SecretID to authenticate to Vault with
-	#   VAULT_ADDR          - URL of the Vault to use for credentials retrieval
-	#   VAULT_SKIP_VERIFY   - Whether or not to enforce SSL/TLS validation
-	#   VAULT_NAMESPACE     - Set for enterprise vaults that require namespaces
-	#   VAULT_NO_STRONGBOX  - Set true for non Genesis vault deployments
-	#   VAULT_SECRETS_MOUNT - Set if vault secrets are not found under /secret
-
 	my @undefined = grep { !$ENV{$_} }
 		qw/CURRENT_ENV ERRAND_NAME VAULT_ROLE_ID VAULT_SECRET_ID VAULT_ADDR/;
 	_bail_on_missing_pipeline_environment_variables(@undefined);
@@ -437,170 +1607,79 @@ sub ci_pipeline_run_errand {
 	exit 0;
 }
 
-### Compiler Pipeline Functions {{{
-
-# _repipe_compiled - deploy pipeline using the new compiler system {{{
-sub _repipe_compiled {
-	my ($top, $layout) = @_;
-	my $platform = get_options->{platform};
-
-	my $result = _compile_pipeline($top, $platform);
-	my $ast    = $result->{ast};
-	my $output = $result->{output};
-
-	my $name = $ast->metadata->{name}
-		or bail("Pipeline AST has no name defined");
-
-	# --output-dir: write artifacts to directory and exit
-	if (my $out_dir = get_options->{'output-dir'}) {
-		mkdir_or_fail($out_dir);
-		for my $file (sort keys %$output) {
-			mkfile_or_fail("$out_dir/$file", $output->{$file});
-			info("Wrote #C{%s/%s}", $out_dir, $file);
-		}
-		mkfile_or_fail("$out_dir/ast.json",
-			JSON::PP->new->pretty->canonical->encode({%$ast}));
-		info("Wrote #C{%s/ast.json}", $out_dir);
-		info("Pipeline artifacts written to #C{%s/}", $out_dir);
-		exit 0;
-	}
-
-	# For concourse, output is { 'pipeline.yml' => $yaml_string }
-	if ($platform eq 'concourse') {
-		my $yaml = $output->{'pipeline.yml'}
-			or bail("Concourse provider did not produce pipeline.yml");
-
-		if (get_options->{'dry-run'}) {
-			output({raw => 1}, $yaml);
-			exit 0;
-		}
-
-		option_defaults(target => $layout || $name);
-
-		my ($out,$rc) = run(
-			'fly -t $1 pause-pipeline -p $2',
-			get_options->{target}, $name
-		);
-		bail("Could not pause #c{%s} pipeline: $out", $name)
-			unless $rc == 0 || $out =~ /pipeline '.*' not found/;
-
-		my $yes = get_options->{yes} ? ' -n ' : '';
-		my $dir = workdir;
-		mkfile_or_fail("${dir}/pipeline.yml", $yaml);
-		run({ interactive => 1, onfailure => "Could not upload pipeline $name" },
-			'fly -t $1 set-pipeline '.$yes.' -p $2 -c $3/pipeline.yml',
-			get_options->{target}, $name, $dir);
-
-		run(
-			{ interactive => 1, onfailure => "Could not unpause pipeline $name" },
-			'fly -t $1 unpause-pipeline -p $2',
-			get_options->{target}, $name
-		) unless (get_options->{paused});
-
-		my $public = $ast->configuration->{public} || 0;
-		my $action = ($public ? 'expose' : 'hide');
-		run({ interactive => 1, onfailure => "Could not $action pipeline $name" },
-			'fly -t $1 '.$action.'-pipeline -p $2',
-			get_options->{target}, $name);
-
-	} elsif ($platform eq 'github-actions') {
-		# GitHub Actions outputs workflow YAML files to .github/workflows/
-		if (get_options->{'dry-run'}) {
-			for my $file (sort keys %$output) {
-				output "#G{--- %s ---}", $file;
-				output({raw => 1}, $output->{$file});
-			}
-			exit 0;
-		}
-
-		for my $file (sort keys %$output) {
-			my $path = ".github/workflows/$file";
-			mkdir_or_fail(dirname($path));
-			mkfile_or_fail($path, $output->{$file});
-			info("Wrote #C{%s}", $path);
-		}
-		info("GitHub Actions workflows written. Commit and push to activate.");
-	} else {
-		bail("Unsupported platform '%s' for repipe", $platform);
-	}
-
-	exit 0;
-}
-
 # }}}
-# _graph_compiled - write pipeline.md with Mermaid flowchart {{{
-sub _graph_compiled {
-	my ($top, $layout) = @_;
-	my $platform = get_options->{platform};
-
-	my $result   = _compile_pipeline($top, $platform);
-	my $ast      = $result->{ast};
-	my $provider = $result->{provider};
-
-	# Use provider's graph_md method if available
-	my $md;
-	if ($provider->can('graph_md')) {
-		$md = $provider->graph_md();
-	} else {
-		$md = _ast_to_mermaid_md($ast);
-	}
-
-	mkfile_or_fail('pipeline.md', $md);
-	info("Wrote #C{pipeline.md}");
-	exit 0;
-}
-
 # }}}
-# _describe_compiled - describe compiled pipeline in human-readable form {{{
-sub _describe_compiled {
-	my ($top, $layout) = @_;
-	my $platform = get_options->{platform};
-
-	my $result   = _compile_pipeline($top, $platform);
-	my $ast      = $result->{ast};
-	my $provider = $result->{provider};
-
-	# Use provider's describe method if available
-	if ($provider->can('generate_description')) {
-		$provider->generate_description($ast);
-		exit 0;
-	}
+### Internal Compiler Helpers {{{
 
-	# Fall back to generic AST-based description
-	_describe_ast($ast, $platform);
-	exit 0;
-}
-
-# }}}
-# _compile_pipeline - run the compiler pipeline and return results {{{
+# _compile_pipeline - detect config source and compile; returns result hash {{{
 sub _compile_pipeline {
 	my ($top, $platform) = @_;
 
 	my %compiler_opts = (top => $top);
 
-	# Detect configuration source
-	my $ci_dir = '.genesis/ci';
-	if (-d $ci_dir && -f "$ci_dir/pipeline.yml") {
+	# Priority order:
+	#   1. .genesis/ci/pipeline.yml or targets.yml  (multi-file)
+	#   2. ci: section in .genesis/config           (genesis-config)
+	#   3. Legacy ci.yml / --config file            (backward compat)
+	my $ci_dir = $top->path('.genesis/ci');
+	if (-d $ci_dir && (-f "$ci_dir/pipeline.yml" || -f "$ci_dir/targets.yml")) {
 		$compiler_opts{ci_dir} = $ci_dir;
-		info("Using multi-file configuration from #C{%s/}", $ci_dir);
+		info("Using multi-file CI configuration from #C{.genesis/ci/}");
+	} elsif (Genesis::CI::Compiler->can_compile_from_genesis_config($top)) {
+		info("Using inline CI configuration from #C{.genesis/config}");
 	} else {
-		$compiler_opts{file} = get_options->{config} || 'ci.yml';
-		info("Using legacy configuration from #C{%s}", $compiler_opts{file});
+		$compiler_opts{file} = get_options->{config} || $top->path('ci.yml');
+		info("Using legacy CI configuration from #C{%s}", $compiler_opts{file});
+	}
+
+	# Parse provider-specific CLI flags
+	my %provider_cli_opts;
+	{
+		require Genesis::CI::Compiler::PipelineProvider;
+		my @argv = ();
+		Genesis::CI::Compiler::PipelineProvider->parse_cli_opts(
+			\@argv, \%provider_cli_opts, $platform
+		);
+		for my $key (Genesis::CI::Compiler::PipelineProvider->cli_opt_keys($platform)) {
+			$provider_cli_opts{$key} = get_options->{$key}
+				if defined get_options->{$key};
+		}
 	}
 
 	my $compiler = Genesis::CI::Compiler->new(%compiler_opts);
-	my $result = $compiler->compile(provider => $platform);
+	my $result   = $compiler->compile(
+		provider      => $platform,
+		provider_opts => \%provider_cli_opts,
+	);
 
-	# Dump debug artifacts if --debug-dir is specified
 	if (my $debug_dir = get_options->{'debug-dir'}) {
 		_dump_debug_artifacts($debug_dir, $result, $platform);
 	}
 
+	$result->{provider_cli_opts} = \%provider_cli_opts;
 	return $result;
 }
 
 # }}}
-# _dump_debug_artifacts - write compiler intermediates to debug directory {{{
+# _get_top - create Genesis::Top, optionally skipping vault {{{
+sub _get_top {
+	my ($opts, %defaults) = @_;
+
+	my $skip = $opts->{'skip-vault'} || $defaults{skip_vault};
+	if ($skip) {
+		return Genesis::Top->new('.');
+	}
+
+	my $top = Genesis::Top->new('.', vault => $opts->{vault});
+	bail(
+		"No vault specified or configured.\n".
+		"Use --skip-vault to compile without vault access."
+	) unless $top->vault;
+	return $top;
+}
+
+# }}}
+# _dump_debug_artifacts - write compiler intermediates to a directory {{{
 sub _dump_debug_artifacts {
 	my ($debug_dir, $result, $platform) = @_;
 
@@ -608,18 +1687,16 @@ sub _dump_debug_artifacts {
 
 	my $json = JSON::PP->new->pretty->canonical;
 
-	# 1. Parsed config (what the parser produced)
 	if ($result->{parsed}) {
 		mkfile_or_fail("$debug_dir/01-parsed.json",
 			$json->encode($result->{parsed}));
 		info("Debug: wrote #C{%s/01-parsed.json}", $debug_dir);
 	}
 
-	# 2. AST source representation (internal Genesis concepts)
 	if (my $ast = $result->{ast}) {
 		my %source;
 		for my $key (qw(branches integrations targets workflows configuration
-						provider_config triggers resources)) {
+		                provider_config triggers resources)) {
 			my $accessor = $ast->can($key);
 			$source{$key} = $accessor->($ast) if $accessor;
 		}
@@ -630,10 +1707,8 @@ sub _dump_debug_artifacts {
 			$json->encode(\%source));
 		info("Debug: wrote #C{%s/02-ast-source.json}", $debug_dir);
 
-		# 3. Resolved generic pipeline (what PipelineDescriptor produced)
 		if ($ast->pipeline && %{$ast->pipeline}) {
-			# Write pipeline structure (minus visualization/description for readability)
-			my %pipeline = %{$ast->pipeline};
+			my %pipeline    = %{$ast->pipeline};
 			my $mermaid     = delete $pipeline{mermaid};
 			my $pipeline_md = delete $pipeline{pipeline_md};
 			my $description = delete $pipeline{description};
@@ -642,13 +1717,11 @@ sub _dump_debug_artifacts {
 				$json->encode(\%pipeline));
 			info("Debug: wrote #C{%s/03-pipeline.json}", $debug_dir);
 
-			# 4. Mermaid pipeline.md
 			if ($pipeline_md) {
 				mkfile_or_fail("$debug_dir/04-pipeline.md", $pipeline_md);
 				info("Debug: wrote #C{%s/04-pipeline.md}", $debug_dir);
 			}
 
-			# 5. Human description
 			if ($description) {
 				mkfile_or_fail("$debug_dir/05-description.txt", $description);
 				info("Debug: wrote #C{%s/05-description.txt}", $debug_dir);
@@ -656,7 +1729,6 @@ sub _dump_debug_artifacts {
 		}
 	}
 
-	# 6. Provider output (final platform-specific YAML)
 	if ($result->{output}) {
 		if (ref($result->{output}) eq 'HASH') {
 			for my $file (sort keys %{$result->{output}}) {
@@ -674,7 +1746,7 @@ sub _dump_debug_artifacts {
 }
 
 # }}}
-# _ast_to_mermaid_md - fallback Mermaid pipeline.md from a bare AST {{{
+# _ast_to_mermaid_md - generate pipeline.md Mermaid content from a bare AST {{{
 sub _ast_to_mermaid_md {
 	my ($ast) = @_;
 
@@ -715,7 +1787,90 @@ sub _ast_to_mermaid_md {
 }
 
 # }}}
-# _describe_ast - describe AST contents in human-readable form {{{
+# _topology_to_mermaid_md - mermaid flowchart from nodes+edges {{{
+sub _topology_to_mermaid_md {
+	my ($top, $nodes, $edges) = @_;
+
+	my $name  = $top->config->get('ci.name') || $top->type;
+	my @lines = (
+		"---",
+		"config:",
+		"  flowchart:",
+		"    useMaxWidth: false",
+		"---",
+		"flowchart TD",
+	);
+
+	# Declare nodes with explicit labels so names aren't truncated
+	my %declared;
+	for my $n (sort keys %$nodes) {
+		my $label = $nodes->{$n}{alias} || $n;
+		(my $id = $n) =~ s/[^a-zA-Z0-9_]/_/g;
+		push @lines, "  ${id}[\"$label\"]";
+		$declared{$n} = $id;
+	}
+
+	for my $edge (@$edges) {
+		push @lines, "  $declared{$edge->{from}} --> $declared{$edge->{to}}";
+	}
+
+	my $mermaid = join("\n", @lines) . "\n";
+	return "# Pipeline: $name\n\n\`\`\`mermaid\n${mermaid}\`\`\`\n";
+}
+
+# }}}
+# _describe_topology - human-readable env-file topology description {{{
+sub _describe_topology {
+	my ($top, $nodes, $edges) = @_;
+
+	my $name = $top->config->get('ci.name') || $top->type;
+	my $provider_type = $top->config->get('ci.provider.type') || 'manual';
+	output "\n#G{Pipeline}: #C{%s}", $name;
+	output "  #Yi{Provider}: %s", $provider_type;
+	output "";
+
+	unless (%$nodes) {
+		output "#Yi{No environments with pipeline metadata found.}";
+		output "";
+		return;
+	}
+
+	# Build adjacency: parent → [children]
+	my %children;
+	my %has_parent;
+	for my $edge (@$edges) {
+		push @{$children{$edge->{from}}}, $edge->{to};
+		$has_parent{$edge->{to}} = 1;
+	}
+
+	# Roots are nodes with no incoming edge
+	my @roots = sort grep { !$has_parent{$_} } keys %$nodes;
+
+	output "#G{Environment progression}:";
+	output "";
+
+	my $print_tree;
+	$print_tree = sub {
+		my ($env, $indent) = @_;
+		my $node = $nodes->{$env};
+		my @flags;
+		push @flags, '#Y{manual}'     if $node->{manual};
+		push @flags, '#M{require_pr}' if $node->{require_pr};
+		my $flag_str = @flags ? '  (' . join(', ', @flags) . ')' : '';
+		output "%s#C{%s}%s", $indent, $env, $flag_str;
+		for my $child (sort @{$children{$env} || []}) {
+			$print_tree->($child, "$indent  ");
+		}
+	};
+
+	for my $root (@roots) {
+		$print_tree->($root, '  ');
+	}
+	output "";
+}
+
+# }}}
+# _describe_ast - human-readable AST description {{{
 sub _describe_ast {
 	my ($ast, $platform) = @_;
 
@@ -724,25 +1879,20 @@ sub _describe_ast {
 	output "  #Yi{Source}:   %s", $ast->metadata->{source} || 'unknown';
 	output "";
 
-	# Integrations
 	my $integrations = $ast->integrations || {};
 	if (my $sc = $integrations->{source_control}) {
 		output "#G{Source Control}:";
-		output "  Provider:   %s", $sc->{provider} || 'unknown';
+		output "  Provider:   %s", $sc->{provider}   || 'unknown';
 		output "  Repository: %s", $sc->{repository} || 'unknown';
 	}
 
-	# Targets
 	my @targets = $ast->target_names;
 	if (@targets) {
 		output "";
 		output "#G{Targets}: (%d)", scalar @targets;
-		for my $name (sort @targets) {
-			output "  - #C{%s}", $name;
-		}
+		output "  - #C{%s}", $_ for sort @targets;
 	}
 
-	# Workflows
 	my @workflows = $ast->workflow_names;
 	if (@workflows) {
 		output "";
@@ -768,10 +1918,36 @@ sub _describe_ast {
 }
 
 # }}}
+# _concourse_fly_flags - derive (target, k_flag) from compiled result + CLI opts {{{
+#
+# Target resolution: explicit --target CLI opt > ci.provider.target config > pipeline name.
+# k_flag is ' -k' when insecure is set, '' otherwise.
+sub _concourse_fly_flags {
+	my ($result, $opts, $name) = @_;
+	my $provider = $result->{provider};
+	my $target   = $opts->{target}
+		// ($provider->can('provider_option') ? $provider->provider_option('target') : undef)
+		// $name;
+	my $insecure = $provider->can('provider_option')
+		? ($provider->provider_option('insecure') // 0) : 0;
+	my $k_flag   = $insecure ? ' -k' : '';
+	return ($target, $k_flag);
+}
+
 # }}}
+# _job_status_label - derive a display status from a fly jobs JSON entry {{{
+sub _job_status_label {
+	my ($job) = @_;
+	return 'paused' if $job->{paused};
+	my $fb = $job->{finished_build} || {};
+	return $fb->{status} || 'pending';
+}
 
-### Support functions
+# }}}
+# }}}
+### CI Task Helpers {{{
 
+# _vault_auth - authenticate to vault using AppRole credentials from env {{{
 sub _vault_auth {
 	my @missing_variables = grep {
 		!exists($ENV{$_}) || !defined($ENV{$_})
@@ -781,18 +1957,18 @@ sub _vault_auth {
 		join(", ", @missing_variables)
 	) if @missing_variables;
 
-	# TODO: This should be handled by repo or env vault yaml entries (#BETTERVAULTTARGET)
 	Service::Vault::Remote->create(
 		$ENV{VAULT_ADDR},
 		'deployments-vault',
-		skip_verify => envset("VAULT_SKIP_VERIFY"),
-		namespace => $ENV{VAULT_NAMESPACE},
+		skip_verify  => envset("VAULT_SKIP_VERIFY"),
+		namespace    => $ENV{VAULT_NAMESPACE},
 		no_strongbox => envset("VAULT_NO_STRONGBOX"),
-		mount => $ENV{VAULT_SECRETS_MOUNT}
+		mount        => $ENV{VAULT_SECRETS_MOUNT}
 	)->connect_and_validate();
 }
 
-# _bail_on_missing_pipeline_environment_variables - provide consistent error message when missing pipeline environment variables {{{
+# }}}
+# _bail_on_missing_pipeline_environment_variables - consistent error for missing CI env vars {{{
 sub _bail_on_missing_pipeline_environment_variables {
 	if (@_) {
 		error("The following #R{required} environment variables have not been defined:");
@@ -804,12 +1980,12 @@ sub _bail_on_missing_pipeline_environment_variables {
 }
 
 # }}}
-# _propagate_previous_passed_files - copy cached files from previous pipeline environment {{{
+# _propagate_previous_passed_files - copy cached files from previous pipeline env {{{
 sub _propagate_previous_passed_files {
 
 	return unless $ENV{PREVIOUS_ENV};
 
-	bail "No CACHE_DIR set - cannot propagate passed values" unless $ENV{CACHE_DIR};
+	bail "No CACHE_DIR set - cannot propagate passed values"   unless $ENV{CACHE_DIR};
 	bail "No WORKING_DIR set - cannot propagate passed values" unless $ENV{WORKING_DIR};
 
 	my $workdir  = $ENV{WORKING_DIR};
@@ -819,7 +1995,7 @@ sub _propagate_previous_passed_files {
 		$cachedir .= "/$ENV{GIT_GENESIS_ROOT}";
 	}
 
-	my @cachables=(
+	my @cachables = (
 		".genesis/cached",
 		".genesis/config",
 		".genesis/kits"
@@ -832,26 +2008,24 @@ sub _propagate_previous_passed_files {
 	) for (@cachables);
 
 	info "\n#C{Copying over cached files from $ENV{PREVIOUS_ENV} environment:}";
-
 	run(
 		{ onfailure => "#R{[ERROR]} Failed to copy '$cachedir/$_' to '$workdir/$_'", interactive => 1 },
 		'cp', '-Rv', "$cachedir/$_", "$workdir/$_"
 	) for (@cachables);
 
-  my $env = Genesis::Top->new($workdir)->load_env($ENV{CURRENT_ENV});
+	my $env = Genesis::Top->new($workdir)->load_env($ENV{CURRENT_ENV});
 	my @files = map {(my $s = $_) =~ s/^\.\///; $s}
 		grep {$_ !~ /^not-shared/}
 		$env->relate($ENV{PREVIOUS_ENV},'','not-shared');
 	return {
 		missing => [grep {-f "$workdir/$_" && ! -f "$cachedir/$_"} @files],
 		extra   => [grep {-f "$cachedir/$_" && ! -f "$workdir/$_"} @files],
-	}
+	};
 }
 
 # }}}
-# _get_git_env - setup a git configuration in the 'home' directory under the given dir, and return env {{{
+# _get_git_env - set up git credentials in a temp home dir, return env hash {{{
 sub _get_git_env {
-
 	my ($env_dir) = @_;
 	my %env;
 	$env{HOME}                = "$env_dir/home";
@@ -871,8 +2045,8 @@ Host *
   LogLevel QUIET
   IdentityFile $env_dir/home/.ssh/key
 EOF
-		$env{GIT_SSH_COMMAND}     = "ssh -F $env_dir/home/.ssh/config";
-	};
+		$env{GIT_SSH_COMMAND} = "ssh -F $env_dir/home/.ssh/config";
+	}
 	if ($ENV{GIT_USERNAME}) {
 		mkdir_or_fail( "$env_dir/home", 0700);
 		mkfile_or_fail("$env_dir/home/credential-helper.sh", 0755, <<'EOF');
@@ -884,39 +2058,25 @@ EOF
 	}
 
 	return wantarray ? %env : \%env;
-
 }
 
 # }}}
-# _commit_changes - commit changes back to genesis that incorporate the upstream values {{{
+# _commit_changes - commit post-deploy changes back to the git repo {{{
 sub _commit_changes {
 	my ($indir, $outdir, $branch, $message, $filter) = @_;
 
-	# the below copying of files into new repos from older repos is all
-	# done in the name of avoiding merge conflicts, or weird errors when
-	# rebasing, and git discovers that there are no changes after you rebase
-
-	# remove any old directories if they are left over (only really happens when
-	# debugging a failed run)
 	run(
 		{onfailure => "#R{[ERROR]} Failed to remove remnant of previous changes commit"},
 		'rm -rf "$1"', $outdir
 	) if -d $outdir;
 
-	# create an output git repo based off of latest origin/$branch
 	run({ interactive => 1, passfail => 1},
 		'cp -R "$1" "$2"', $indir, $outdir) or exit 1;
 	pushd $outdir;
 
-	my $tmp = workdir;
+	my $tmp     = workdir;
 	my $git_env = _get_git_env($tmp);
 
-	# What's Going On?
-	#   reset --hard : reset the repo to the current commit on branch
-	#   clean -df:     remove any untracked files (ie the new cached files)
-	#   checkout:      ensure we're on the named branch, to correctly push later
-	#   pull origin:   ensure we're up-to-date with any changes that may have
-	#                  happened during pipeline
 	run({ onfailure   => "Could not reset to the newest applicable ref in git",
 		  interactive => 1,
 		  env => $git_env },
@@ -924,13 +2084,12 @@ sub _commit_changes {
 		$branch);
 	popd;
 
-	# find and copy (or remove if appropriate) all potential changes to the outdir
 	pushd $indir;
 	my @output = lines(run({env => $git_env}, 'git status --porcelain'));
 	popd;
 	info "Detected the following changes in repo:" if @output;
 	for my $change (@output) {
-		my ($action,$file)= $change =~ /^(..).(.*)$/;
+		my ($action,$file) = $change =~ /^(..).(.*)$/;
 		next if $filter && ref($filter) && ref($filter) =~ /^regexp$/i && $file !~ $filter;
 		if ($action =~ /.D/) {
 			info "  - #R{removed:} $file";
@@ -941,7 +2100,6 @@ sub _commit_changes {
 		} else {
 			mkdir_or_fail(dirname("$outdir/$file"));
 			info "  - ".($action eq "??" ? "#G{added:}   " : "#Y{changed:} ").$file;
-
 			run(
 				{ onfailure => "Could not copy changed files to output directory" },
 				'cp -Rv "$1" "$2"', "$indir/$file", "$outdir/$file"
@@ -949,12 +2107,10 @@ sub _commit_changes {
 		}
 	}
 
-	# check if any changes actually exist in the outdir (potential changes may have alread
-	# been tracked after $indir's commit, so they could disappear here), then commit them
 	pushd $outdir;
 	my ($output, undef) = run({env => $git_env}, 'git status --porcelain');
 	if ($output) {
-		run({ interactive => 1, # print output to Concourse log
+		run({ interactive => 1,
 			  env => $git_env },
 			'git add -A && '.
 			'git status && '.
@@ -962,6 +2118,73 @@ sub _commit_changes {
 			'git commit -m "$1"', "CI commit: $message");
 	}
 }
+
+# }}}
 # }}}
 
 1;
+
+=head1 NAME
+
+Genesis::Commands::Pipelines - Pipeline management command suite
+
+=head1 DESCRIPTION
+
+Implements the C<genesis pipeline-*> command family and the legacy
+C<repipe>, C<graph>, C<describe>, C<embed>, and C<ci-*> commands.
+
+=head1 COMMANDS
+
+=over 4
+
+=item B<pipeline-apply> [--platform PROVIDER] [--dry-run] [--paused]
+
+Compile and deploy the pipeline. Defaults to Concourse. Supports
+C<--dry-run> (print YAML only) and C<--output-dir> (write artifacts).
+
+=item B<pipeline-graph> [--platform PROVIDER]
+
+Compile pipeline and write C<pipeline.md> containing a Mermaid flowchart.
+
+=item B<pipeline-describe> [--platform PROVIDER]
+
+Compile pipeline and print a human-readable ordered progression.
+
+=item B<pipeline-diff> [--target TARGET]
+
+Compare compiled pipeline YAML against the live pipeline via
+C<fly get-pipeline>.
+
+=item B<pipeline-status> [<env>] [--target TARGET]
+
+Query C<fly jobs> for per-environment job status.
+
+=item B<pipeline-pause> [<env>] [--target TARGET]
+
+Pause a specific environment's job, or the entire pipeline.
+
+=item B<pipeline-resume> [<env>] [--target TARGET]
+
+Resume a specific environment's job, or the entire pipeline.
+
+=item B<repipe> (deprecated)
+
+Alias for C<pipeline-apply>.
+
+=item B<graph> (deprecated)
+
+Legacy graphviz output without C<--platform>; C<pipeline-graph> with it.
+
+=item B<describe> (deprecated)
+
+Alias for C<pipeline-describe>.
+
+=back
+
+=head1 SEE ALSO
+
+Genesis::CI::Compiler, Genesis::CI::Legacy
+
+=cut
+
+# vim: ts=2 sw=2 sts=2 noet fdm=marker foldlevel=1 nu
diff --git a/lib/Genesis/Commands/Repo.pm b/lib/Genesis/Commands/Repo.pm
index 4b662767..477bf000 100644
--- a/lib/Genesis/Commands/Repo.pm
+++ b/lib/Genesis/Commands/Repo.pm
@@ -5,23 +5,597 @@ use warnings;
 
 use Genesis;
 use Genesis::Commands;
+use Genesis::Term qw/in_controlling_terminal/;
 use Genesis::Top;
-use Genesis::Kit::Provider;
+use Genesis::UI;
+use Service::Git;
 
 use Cwd qw/getcwd abs_path/;
-use File::Basename qw/basename/;
+use File::Basename qw/basename dirname/;
 use File::Path qw/rmtree/;
 use JSON::PP qw/encode_json/;
 
+# ==============================================================================
+# repo-init (replaces init)
+# ==============================================================================
+
+sub repo_init {
+	_repo_init_validate();
+	_repo_init_report(scalar _repo_init_execute());
+	exit 0;
+}
+
+# -- Phase 1: Validation (parse + validate + gather + prompt) ------------------
+#
+# Order within validation:
+#   1. Parse options and derive values (fast, no side effects)
+#   2. Check invalid option combinations (fast bail)
+#   3. Gather data: validate local sources, detect git repo (no network)
+#   4. Subdir preflight: dirty check, control-branch check
+#   5. Check destructive prerequisites (existing directory, before network)
+#   6. Validate remote kit availability (network calls)
+#   7. Prompt for missing info (vault, CI provider wizard)
+#   8. Store derived values and summarize intent
+#
+sub _repo_init_validate {
+	# Passthrough options (e.g. --kit-provider-*) have already been
+	# parsed by the framework's extended_handlers and are available in
+	# get_options()->{kit_provider}.  @args from get_args()
+	# contains only true positional arguments.
+	my %opts = %{get_options()};
+	my @args = get_args();
+
+	# --- 1. Parse and derive ---
+
+	my $name = $args[0];
+	my $kit_file;
+
+	# Check if kit is a local file path
+	if ($opts{kit} && $opts{kit} =~ m#(?:.*/)?([^/]+)-\d+\.\d+\.\d+(?:-rc\.?\d+)?\.t(?:ar\.)?gz#) {
+		$kit_file = $opts{kit};
+		$name = $1 unless $name;
+	}
+
+	# Derive name from kit or link-dev-kit if not specified
+	unless ($name) {
+		if ($opts{kit} && !$kit_file) {
+			($name = $opts{kit}) =~ s|/.*||;
+		} elsif ($opts{'link-dev-kit'}) {
+			$name = basename($opts{'link-dev-kit'});
+		}
+	}
+
+	my $dir = $opts{directory} || $name;
+	my $parent_dir = abs_path(getcwd());
+	my $target_path = "$parent_dir/$dir";
+
+	# --- 2. Check invalid option combinations ---
+
+	bail(
+		"You must specify a deployment name, a kit (-k), or a dev link target (-l)."
+	) unless $name;
+
+	bail(
+		"You can only specify one of kit (-k) or link to a kit (-l)."
+	) if $opts{kit} && $opts{'link-dev-kit'};
+
+	bail(
+		"Cannot specify both --vault and --skip-vault."
+	) if $opts{vault} && $opts{'skip-vault'};
+
+	my $with_ci = $opts{'with-ci'};
+
+	# --- 3. Gather data: validate local sources, detect git repo ---
+
+	# Validate local kit sources exist
+	if ($kit_file) {
+		bail("Local compiled kit file '%s' not found.", $kit_file)
+			unless -f $kit_file;
+	}
+	if ($opts{'link-dev-kit'}) {
+		bail("Dev kit link target '%s' not found.", $opts{'link-dev-kit'})
+			unless -e $opts{'link-dev-kit'};
+	}
+
+	# Check git author config
+	if ($ENV{GIT_AUTHOR_NAME}) {
+		$ENV{GIT_COMMITTER_NAME} ||= $ENV{GIT_AUTHOR_NAME};
+	} else {
+		run({ onfailure => 'Please setup git: git config --global user.name "Your Name"' },
+			'git config user.name');
+	}
+	if ($ENV{GIT_AUTHOR_EMAIL}) {
+		$ENV{GIT_COMMITTER_EMAIL} ||= $ENV{GIT_AUTHOR_EMAIL};
+	} else {
+		run({ onfailure => 'Please setup git: git config --global user.email your@email.com' },
+			'git config user.email');
+	}
+
+	# Guardrail: forbid creating a new Genesis repo inside (or under) an
+	# existing one.  Nested Genesis repos are never correct in this
+	# ecosystem -- pipeline tooling, kit discovery, and .genesis/config
+	# resolution all assume a single enclosing deployment root.
+	if (my $enclosing = _find_enclosing_genesis_repo()) {
+		bail(
+			"Cannot create a new Genesis deployment repository inside an ".
+			"existing one.\n  Enclosing deployment repo: #C{%s}",
+			humanize_path($enclosing)
+		);
+	}
+
+	# Auto-detect whether we're inside an existing (non-Genesis) git
+	# worktree.  If so, the new repo is created as a subdirectory with no
+	# separate .git -- it will share history with the surrounding repo.
+	# This is reported in the plan below so the user can notice an
+	# unexpected enclosure.
+	my $use_subdir = Service::Git->is_inside_work_tree('.');
+
+	# In subdir mode, require the enclosing repo to have no staged or
+	# unstaged changes to tracked files.  Untracked files are fine.
+	# This means that if execution fails and we need to roll back the
+	# index, we can do so without risking the user's in-progress work.
+	# #C{-F|--force} bypasses this check for users who understand the
+	# risk (e.g. scripted environments, known-safe index).
+	if ($use_subdir && !$opts{force}) {
+		my $enclosing_git = Service::Git->new('.');
+		unless ($enclosing_git->is_clean) {
+			bail(
+				"Cannot create a Genesis deployment repository inside an ".
+				"enclosing git repository that has uncommitted changes to ".
+				"tracked files.\n".
+				"  Please commit, stash, or discard them first, ".
+				"or rerun with #C{-F|--force} to bypass this check."
+			);
+		}
+	}
+
+	# In subdir mode AND when a CI provider is being configured,
+	# require the enclosing repo to be on the CI control branch.
+	# Genesis pipeline tooling treats this branch as the single source
+	# of truth from which environment branches are cut
+	# (#C{genesis new}) and against which deploys are validated
+	# (#C{genesis deploy}).  We do not rename or create branches in
+	# the enclosing repo -- the user must set this up themselves.  No
+	# #C{--force} bypass: this is a topology requirement, not a safety
+	# check.
+	#
+	# Without #C{--ci-provider}, no pipeline topology is being
+	# established, so the branch name is irrelevant at this point.
+	my $control_branch = Genesis::Top::DEFAULT_CONTROL_BRANCH();
+	if ($use_subdir && $with_ci) {
+		my $enclosing_git = Service::Git->new('.');
+		my $branch = $enclosing_git->current_branch;
+		if (!defined($branch) || $branch ne $control_branch) {
+			bail(
+				"Configuring a CI provider requires the enclosing git ".
+				"repository to be on a branch named #C{%s}, but it is ".
+				"currently on #C{%s}.\n".
+				"  Please switch to the #C{%s} branch before running ".
+				"#C{repo-init --ci-provider ...}:\n\n".
+				"    git checkout %s\n\n".
+				"  or, if it doesn't exist yet:\n\n".
+				"    git checkout -b %s\n",
+				$control_branch,
+				$branch // '<detached HEAD>',
+				$control_branch,
+				$control_branch,
+				$control_branch
+			);
+		}
+	}
+
+	# --- 4. Check destructive prerequisites (before expensive network calls) ---
+
+	my $replace_existing = 0;
+	if (-e $target_path) {
+		if ($opts{force}) {
+			$replace_existing = 1;
+		} elsif (in_controlling_terminal && Genesis::UI::prompt_for_boolean(
+			"Directory #C{$dir} already exists. Replace it? [y|n] ", 0
+		)) {
+			$replace_existing = 1;
+		} else {
+			bail("Cannot create repository: directory #C{$dir} already exists. Use -F to force replacement.");
+		}
+	}
+
+	# --- 5. Validate remote kit availability (network, after directory check) ---
+
+	my ($resolved_kit_name, $resolved_kit_version, $kit_provider);
+	if ($opts{kit} && !$kit_file) {
+		($resolved_kit_name, $resolved_kit_version) = split('/', $opts{kit}, 2);
+
+		# Kit provider options were parsed by the framework's
+		# extended_handlers into the kit_provider slot.
+		my %provider_opts = %{$opts{kit_provider} // {}};
+		$kit_provider = eval { Genesis::Kit::Provider->init(%provider_opts) };
+		bail("Could not initialize kit provider: %s", $@) if $@;
+
+		if ($resolved_kit_version && $resolved_kit_version ne 'latest') {
+			my @versions = eval { $kit_provider->kit_versions($resolved_kit_name) };
+			my $exists = grep { $_->{version} eq $resolved_kit_version } @versions;
+			bail("Kit '%s/%s' not found from %s.",
+				$resolved_kit_name, $resolved_kit_version, $kit_provider->label) unless $exists;
+		} else {
+			$resolved_kit_version = eval { $kit_provider->latest_version_of($resolved_kit_name) };
+			bail("Kit '%s' not found or no versions available from %s.",
+				$resolved_kit_name, $kit_provider->label) unless $resolved_kit_version;
+		}
+	}
+
+	# --- 6. Prompt for missing info ---
+	#
+	# Interactive steps are deferred until here so we don't waste the
+	# user's time if validation is going to bail (directory exists,
+	# kit not found, wrong branch, etc.).
+
+	my $vault_target;
+	if ($opts{'skip-vault'}) {
+		# explicitly skipped
+	} elsif ($opts{vault}) {
+		$vault_target = $opts{vault};
+	} else {
+		my $vault = _select_vault_target();
+		$vault_target = $vault->{name} if $vault;
+	}
+
+	# --with-ci just sets a flag; provider details come later via
+	# `genesis repo config ci`.  No provider object needed at init time.
+
+	# --- 7. Store derived values and summarize intent ---
+
+	option_defaults(
+		_name                 => $name,
+		_dir                  => $dir,
+		_parent_dir           => $parent_dir,
+		_target_path          => $target_path,
+		_kit_file             => $kit_file,
+		_kit_provider         => $kit_provider,
+		_with_ci              => $with_ci,
+		_use_subdir           => $use_subdir,
+		_vault_target         => $vault_target,
+		_replace_existing     => $replace_existing,
+		_resolved_kit_name    => $resolved_kit_name,
+		_resolved_kit_version => $resolved_kit_version,
+	);
+
+	my @plan;
+	if ($resolved_kit_name) {
+		push @plan, "kit: #C{$resolved_kit_name/$resolved_kit_version}";
+	} elsif ($kit_file) {
+		push @plan, "kit: #C{$kit_file} (local)";
+	} elsif ($opts{'link-dev-kit'}) {
+		push @plan, "kit: dev link to #C{$opts{'link-dev-kit'}}";
+	} else {
+		push @plan, "kit: #Yi{empty dev directory}";
+	}
+	push @plan, "vault: #C{$vault_target}" if $vault_target;
+	push @plan, "vault: #Yi{deferred}" unless $vault_target;
+	push @plan, "ci: #C{enabled} (manual provider)" if $with_ci;
+	push @plan, "subdirectory of enclosing git repo: #C{yes} (no separate .git, auto-detected)" if $use_subdir;
+	info "\nCreating #C{%s} deployment repository in #M{%s/}:", $name, $dir;
+	info "  %s", $_ for @plan;
+	info "";
+
+	return 1;
+}
+
+# -- Phase 2: Execution -------------------------------------------------------
+#
+# All validation is complete. This phase only does work — no prompts, no bails
+# on user input. Failures here are unexpected errors.
+#
+sub _repo_init_execute {
+	my (
+		# Derived and validated values from validation phase (prefixed with _)
+		$name,             # derived name of the deployment/repo
+		$dir,              # target directory name (derived from name or specified by user)
+		$parent_dir,       # parent directory where repo will be created (usually cwd)
+		$target_path,      # full path to the target directory ($parent_dir/$dir)
+		$kit_file,         # optional local kit file to copy into the repo
+		$kit_spec,         # optional remote kit name[/version] to download
+		$kit_provider,     # optional pre-built kit provider (from validation, with cached versions)
+		$use_subdir,       # whether to create the repo as a subdirectory of an existing git repo
+		$vault_target,     # vault target to configure, or undef to skip vault
+		$replace_existing, # whether to remove existing target directory if it exists
+		$linked_dev_kit,   # optional path to a local dev kit to link into the repo
+		$with_ci,          # enable CI pipeline support (manual provider)
+
+		# User provided options (validated but not altered)
+		$directory,        # optional custom directory name override
+		$kits_path,        # optional custom kits path
+		$no_commit,        # skip the initial commit (stage only)
+		$reason,           # optional commit message override
+	) = get_options()->@{qw/
+		_name _dir _parent_dir _target_path _kit_file kit _kit_provider _use_subdir _vault_target
+		_replace_existing link-dev-kit _with_ci directory kits-path no-commit reason
+	/};
+
+	# Remove existing directory if validation approved it
+	if ($replace_existing && -e $target_path) {
+		info "Removing existing directory #C{%s}...", $dir;
+		rmtree $target_path;
+	}
+
+	# Resolve link-dev-kit to absolute path before we potentially chdir
+	my $abs_dev_target;
+	if ($linked_dev_kit) {
+		$abs_dev_target = abs_path($linked_dev_kit);
+	}
+
+	# Build create options for Top->create
+	my %create_opts;
+	if ($vault_target) {
+		$create_opts{vault} = $vault_target;
+	} else {
+		$create_opts{skip_vault} = 1;
+	}
+	$create_opts{directory} = $directory if $directory;
+
+	# Kits path handling
+	my $kit_path;
+	if (defined $kits_path) {
+		$kit_path = abs_path($kits_path // $ENV{HOME}.'/.genesis/kits');
+		mkdir_or_fail($kit_path) unless -d $kit_path;
+	}
+
+	# Create the repo via Top->create (pass kit_provider if we already built one)
+	$create_opts{kit_provider} = $kit_provider if $kit_provider;
+	my $top = Genesis::Top->create($parent_dir, $name, %create_opts, kits_path => $kit_path);
+	$top->embed($ENV{GENESIS_CALLBACK_BIN} || $0) if $with_ci;
+
+	my $root = $top->path;
+	my $human_root = humanize_path($root);
+	my $kit_desc = "";
+
+	pushd($root);
+	eval {
+		# Kit setup
+		if ($abs_dev_target) {
+			symlink_or_fail($abs_dev_target, "./dev");
+			$kit_desc = "linked to kit at #C{$abs_dev_target}";
+		} elsif ($kit_file) {
+			my $target = $top->path(".genesis/kits");
+			mkdir_or_fail($target);
+			my $abs_src = $kit_file =~ m#^/# ? $kit_file : abs_path($ENV{GENESIS_CALLER_DIR}."/".$kit_file);
+			copy_or_fail($abs_src, $target);
+			$kit_desc = "using locally provided compiled kit #C{$kit_file}";
+		} elsif ($kit_spec) {
+			my ($kit_name, $kit_version) = $top->download_kit($kit_spec);
+			$kit_desc = "using the #C{$kit_name/$kit_version} kit";
+		} else {
+			mkdir_or_fail("./dev");
+			$kit_desc = "with an empty development kit in #C{$human_root/dev}";
+		}
+
+		# CI: write manual provider to config
+		if ($with_ci) {
+			_create_ci_scaffold($top, root => ($use_subdir ? $dir : '.'));
+		}
+
+		# Only create a new .git when we're not already sitting inside
+		# an enclosing git worktree; in subdir mode we share the
+		# parent's .git and just stage into its index.  In standalone
+		# mode, if --with-ci is set, force the initial branch name to
+		# the control branch so the initial commit lands there instead
+		# of whatever git's init.defaultBranch happens to be.
+		# #C{git symbolic-ref HEAD} works on all git versions, unlike
+		# #C{git init -b} which requires >= 2.28.
+		my $repo_git;
+		unless ($use_subdir) {
+			if ($with_ci) {
+				my $branch = Genesis::Top::DEFAULT_CONTROL_BRANCH();
+				$repo_git = Service::Git->create('.', initial_branch => $branch);
+			} else {
+				$repo_git = Service::Git->create('.');
+			}
+		} else {
+			$repo_git = Service::Git->new('.');
+		}
+		$repo_git->add('.');
+
+		# Check if the only staged changes are metadata-only (the
+		# "Last updated" comment and/or updater/creator_version in
+		# .genesis/config).  If so, roll them back — re-running
+		# repo-init with --force on the same kit version shouldn't
+		# produce a commit with no meaningful content.
+		my ($diff_names) = run({}, 'git diff --cached --name-only -- .');
+		if ($diff_names && $diff_names =~ /\S/) {
+			my @changed = grep { /\S/ } split /\n/, $diff_names;
+			if (@changed == 1 && $changed[0] =~ m{\.genesis/config$}) {
+				my ($diff_content) = run({}, 'git diff --cached -- .genesis/config');
+				my @meaningful = grep {
+					/^[-+]/ && !/^[-+]{3}\s/ &&
+					$_ !~ /^[-+]\s*#\s*Last updated by\b/ &&
+					$_ !~ /^[-+]\s*(updater_version|creator_version):/
+				} split /\n/, $diff_content;
+				unless (@meaningful) {
+					run({}, 'git checkout -- .genesis/config');
+				}
+			}
+		}
+
+		# Show a summary of what we just staged so the user can see
+		# exactly what the initial commit (or leftover stage) contains.
+		my ($stat) = run({}, 'git diff --cached --stat -- .');
+		if ($stat && $stat =~ /\S/) {
+			info "\n#G{Files staged for initial commit:}";
+			info "  %s", $_ for split /\n/, $stat;
+			info "";
+		} else {
+			info "\nNo changes to commit — repository contents are unchanged.";
+			$kit_desc = "unchanged (already up to date)";
+		}
+
+		# Commit unless the user explicitly opted out or there is
+		# nothing staged.
+		if (!$stat || $stat !~ /\S/) {
+			# nothing to commit — already reported above
+		} elsif ($no_commit) {
+			info "Skipping initial commit (#C{--no-commit} set); files remain staged.";
+		} else {
+			my $message = $reason || "Initial Genesis repo for $name";
+			if ($use_subdir) {
+				run({ onfailure => "Failed to commit initial repository in $human_root/" },
+					'git', 'commit', '-m', $message, '--', '.');
+			} else {
+				$repo_git->commit($message);
+			}
+
+			my $sha = $repo_git->sha('HEAD', short => 1);
+			info "#G{Committed} #C{%s} -- %s", $sha // '<unknown>', $message;
+		}
+	};
+	my $err = $@;
+	eval { popd };  # always restore cwd; swallow errors to not mask $err
+
+	# On failure, return only what the report phase needs to clean up
+	# and bail -- the $top object may be in a partial state and its
+	# accessors (vault, etc.) are not safe to call.
+	if ($err) {
+		return {
+			error        => $err,
+			root         => $root,
+			human_root   => $human_root,
+			target_path  => $target_path,
+			parent_dir   => $parent_dir,
+			use_subdir   => $use_subdir,
+		};
+	}
+
+	# Success: the repository is created and (if requested) committed.
+	# Resolving the vault URL for the report is not part of the
+	# command's core purpose -- if it trips a runtime error, warn the
+	# user but do NOT fail the command (the repo is already on disk).
+	my %result = (
+		error         => undef,
+		root          => $root,
+		human_root    => $human_root,
+		name          => $name,
+		kit_desc      => $kit_desc,
+		ci_provider   => $with_ci ? 'manual' : undef,
+		vault_skipped => $vault_target ? 0 : 1,
+		vault         => $vault_target,
+		submodule     => $use_subdir,
+	);
+	eval {
+		$result{vault} = $vault_target
+			? ($top->vault ? $top->vault->url : $vault_target)
+			: undef;
+	};
+	if (my $housekeeping_err = $@) {
+		warning(
+			"Repository was created successfully, but a post-commit ".
+			"housekeeping step failed (non-fatal):\n%s",
+			$housekeeping_err
+		);
+	}
+	return \%result;
+}
+
+# -- Phase 3: Report ----------------------------------------------------------
+#
+# Handles both success and failure.  On failure, cleans up any partial
+# initialization (removing the new directory and, in subdir mode,
+# unstaging from the enclosing repo's index) before bailing with an
+# appropriate message.  On success, prints the summary.
+#
+sub _repo_init_report {
+	my ($result) = @_;
+
+	if ($result->{error}) {
+		debug(
+			"removing incomplete Genesis repository at #C{%s} due to failed creation",
+			$result->{root}
+		);
+		# In subdir mode, unstage anything we added to the enclosing
+		# repo's index before deleting the directory so the parent
+		# repo's working state is left clean.  This is safe because
+		# validation ensured the parent repo had no other tracked
+		# changes (or the user passed --force); the pathspec scopes
+		# the reset strictly to what we just staged.
+		if ($result->{use_subdir}) {
+			eval {
+				run({ dir => $result->{parent_dir} },
+					'git', 'reset', 'HEAD', '--', $result->{target_path});
+			};
+		}
+		rmtree $result->{root} if -e $result->{root};
+		bail(
+			"Failed to create Genesis repository at #C{%s}:\n%s",
+			$result->{human_root}, $result->{error}
+		);
+	}
+
+	success "\nGenesis repository #C{%s} created successfully.\n", $result->{name};
+}
+
+# -- Helpers -------------------------------------------------------------------
+
+# Walk upward from the current working directory looking for an
+# enclosing Genesis deployment repository.  Returns the absolute path
+# of the enclosing repo if found, otherwise undef.
+#
+# The global #C{in_repo_dir()} helper only checks cwd, and almost every
+# consumer downstream uses #C{Genesis::Top->new('.')} which assumes
+# cwd IS the repo root -- so teaching the global helper to walk up
+# would ripple.  This variant is scoped to #C{repo-init}'s guardrail
+# against creating a nested deployment repo.
+sub _find_enclosing_genesis_repo {
+	my $dir = abs_path(getcwd());
+	while (defined($dir) && length($dir) > 1) {
+		return $dir if Genesis::Top->is_repo($dir);
+		my $parent = dirname($dir);
+		last if $parent eq $dir;
+		$dir = $parent;
+	}
+	return undef;
+}
+
+sub _select_vault_target {
+	my $configure = Genesis::UI::prompt_for_boolean(
+		"Would you like to configure a secrets vault now? [y|n] ", 1
+	);
+	return undef unless $configure;
+
+	require Service::Vault::Remote;
+	my $vault = eval { Service::Vault::Remote->target(undef) };
+	return $vault;
+}
+
+sub _create_ci_scaffold {
+	my ($top, %opts) = @_;
+
+	my %provider_cfg;
+	if (ref($opts{provider})) {
+		%provider_cfg = $opts{provider}->config();
+	} else {
+		%provider_cfg = (type => $opts{provider} || 'manual');
+	}
+
+	my %ci = (
+		enabled  => Genesis::Config::TRUE,
+		provider => \%provider_cfg,
+		name     => $top->config->get('deployment_type'),
+	);
+	$ci{repo} = { root => $opts{root} } if $opts{root};
+
+	$top->config->set('ci', \%ci);
+	$top->config->save;
+}
+
+
+# ==============================================================================
+# Legacy init (preserved for backward compatibility, aliased to repo-init)
+# ==============================================================================
+
 sub init {
 	my %options;
-	# FIXME: The following might work, but it may need some tweaking as it used to
-	# run before the regular option parser.
 	Genesis::Kit::Provider->parse_opts(\@_, \%options);
 	append_options(%options);
 	%options = %{get_options()};
 
-	command_usage(1) if @_ > 1; # name is now optional if kit specified
+	command_usage(1) if @_ > 1;
 	command_usage(1, "You can only specify one of kit (-k) or link to a kit (-L)")
 		if scalar(grep {$_ =~ /^(?:kit|link-dev-kit)$/} keys %options) > 1;
 
@@ -117,8 +691,31 @@ sub init {
 		run({ onfailure => "Failed to initialize a git repository in $human_root/" },
 			'git init && git add .');
 
-		run({ onfailure => "Failed to commit initial Genesis repository in $human_root/" },
-			'git commit -m "Initial Genesis Repo"');
+		# Show a summary of what was staged
+		my ($stat) = run({}, 'git diff --cached --stat');
+		if ($stat && $stat =~ /\S/) {
+			info "\n#G{Files staged for initial commit:}";
+			for my $line (split /\n/, $stat) {
+				info "  %s", $line;
+			}
+			info "";
+		}
+
+		my $do_commit;
+		if ($options{commit}) {
+			$do_commit = 1;
+		} elsif ($options{'no-commit'}) {
+			$do_commit = 0;
+		} else {
+			$do_commit = prompt_for_boolean(
+				"Commit initial state? [y|n]", "y"
+			);
+		}
+
+		if ($do_commit) {
+			run({ onfailure => "Failed to commit initial Genesis repository in $human_root/" },
+				'git commit -m "Initial Genesis Repo"');
+		}
 	};
 	my $err = $@;
 	popd;
@@ -131,8 +728,12 @@ sub init {
 	exit 0;
 }
 
+# ==============================================================================
+# Other repo commands
+# ==============================================================================
+
 sub secrets_provider {
-	command_usage(1) if @_ > 1; # target is optional
+	command_usage(1) if @_ > 1;
 
 	my %options = %{get_options(qw(interactive clear))};
 	$options{target} = shift if scalar(@_);
@@ -152,7 +753,7 @@ sub secrets_provider {
 	my %vault_info = $top->vault_status;
 	if (%vault_info) {
 		if ($vault_info{status} eq "unauthenticated") {
-			eval {$top->vault->authenticate}; # Try to auto-authenticate
+			eval {$top->vault->authenticate};
 			%vault_info = $top->vault_status;
 		}
 		info(
@@ -238,5 +839,346 @@ sub kit_provider {
 	info("         Kits: %s\n\n", $kit_list) if $info{status} eq "ok";
 }
 
+# PARKED: this is Tristan's CI-only repo-init handler from the upstream
+# merge.  It conflicts with our phased repo-init at the top of this file
+# (both registered under the same command name, causing Perl to redefine
+# our sub).  Renamed to repo_configure_ci as a parking slot until the
+# folding meeting resolves how his CI-scaffold logic merges into our
+# _create_ci_scaffold.  Not currently dispatched by any command.
+sub repo_configure_ci {
+	my %options = %{get_options()};
+	command_usage(1) if @_;
+
+	my $top = Genesis::Top->new('.', no_vault => 1);
+
+	bail(
+		"CI provider already configured (#C{%s}).\n".
+		"Use #C{genesis repo-update} to modify the existing configuration.",
+		$top->config->get('ci.provider')
+	) if $top->config->has('ci.provider');
+
+	my $cfg = _ci_wizard(\%options, $top, _empty_ci_defaults($top));
+	_write_ci_config($top, $cfg);
+
+	info(
+		"\n#G{CI configuration initialized}\n".
+		"  Provider : #C{%s}\n".
+		"  Config   : #C{.genesis/config}\n".
+		"  Scaffold : #C{.genesis/ci/}\n\n".
+		"Add environment targets to #C{.genesis/ci/targets.yml}, then run\n".
+		"#C{genesis pipeline-apply} to deploy the pipeline.\n",
+		$cfg->{ci_provider}
+	);
+	exit 0;
+}
+
+sub repo_update {
+	my %options = %{get_options()};
+	command_usage(1) if @_;
+
+	my $top = Genesis::Top->new('.', no_vault => 1);
+
+	unless ($top->config->has('ci.provider')) {
+		warning(
+			"CI provider is not configured for this repository.\n".
+			"Use #C{genesis repo-init} to set up CI from scratch."
+		);
+	}
+
+	my @flag_keys = keys %options;
+
+	if (@flag_keys) {
+		# Non-interactive: apply only the provided flags, leave everything else alone
+		_apply_ci_flags(\%options, $top);
+	} else {
+		# Bare invocation: full wizard with existing values pre-populated
+		my $cfg = _ci_wizard(\%options, $top, _existing_ci_defaults($top));
+		_write_ci_config($top, $cfg);
+	}
+
+	info(
+		"\n#G{CI configuration updated}\n".
+		"  Provider : #C{%s}\n".
+		"  Config   : #C{.genesis/config}\n".
+		"  Scaffold : #C{.genesis/ci/}\n",
+		$top->config->get('ci.provider') // '(none)'
+	);
+	exit 0;
+}
+
+### Private helpers ###########################################################
+
+# _empty_ci_defaults - blank defaults for repo_configure_ci wizard
+sub _empty_ci_defaults {
+	my ($top) = @_;
+	return {
+		ci_provider   => 'concourse',
+		git_uri       => '',
+		git_branch    => 'main',
+		vault_url     => '',
+		pipeline_name => $top->type,
+	};
+}
+
+# _existing_ci_defaults - load current values for repo_update wizard
+sub _existing_ci_defaults {
+	my ($top) = @_;
+
+	my $defaults = _empty_ci_defaults($top);
+	$defaults->{ci_provider} = $top->config->get('ci.provider')
+		if $top->config->has('ci.provider');
+
+	my $ci_dir = $top->path('.genesis/ci');
+	if (-f "$ci_dir/integrations.yml") {
+		eval {
+			my $raw = slurp("$ci_dir/integrations.yml");
+			# Extract vault.url: capture only within the vault: block, stopping
+			# before the next top-level key (no leading spaces) to avoid matching
+			# url: keys in other sections.
+			if ($raw =~ /^vault:\s*\n((?:[ \t]+[^\n]*\n)*)/m) {
+				my $vault_block = $1;
+				$defaults->{vault_url} = $1 if $vault_block =~ /url:\s*(\S+)/;
+			}
+			# source_control.uri and default_branch are unique keys in our schema
+			if ($raw =~ /uri:\s*(\S+)/) {
+				$defaults->{git_uri} = $1;
+			}
+			if ($raw =~ /default_branch:\s*(\S+)/) {
+				$defaults->{git_branch} = $1;
+			}
+		};
+	}
+
+	if (-f "$ci_dir/pipeline.yml") {
+		eval {
+			my $raw = slurp("$ci_dir/pipeline.yml");
+			if ($raw =~ /name:\s*(\S+)/) {
+				$defaults->{pipeline_name} = $1;
+			}
+		};
+	}
+
+	return $defaults;
+}
+
+# _ci_wizard - prompt for any config values not supplied as flags
+sub _ci_wizard {
+	my ($options, $top, $defaults) = @_;
+
+	my $ci_provider = $options->{'ci-provider'} // do {
+		prompt_for_choice(
+			"CI provider:",
+			[qw(concourse github-actions none)],
+			$defaults->{ci_provider},
+		);
+	};
+
+	my $pipeline_name = $options->{'pipeline-name'} // do {
+		prompt_for_line(
+			"Pipeline name:",
+			"pipeline name",
+			$defaults->{pipeline_name},
+		);
+	};
+
+	my $git_uri = $options->{'git-uri'} // do {
+		prompt_for_line(
+			"Git repository URI (e.g. git\@github.com:org/repo.git):",
+			"git uri",
+			$defaults->{git_uri},
+		);
+	};
+
+	my $git_branch = $options->{'git-branch'} // do {
+		prompt_for_line(
+			"Default branch:",
+			"branch",
+			$defaults->{git_branch},
+		);
+	};
+
+	my $vault_url = $options->{'vault-url'} // do {
+		prompt_for_line(
+			"Vault URL (e.g. https://vault.example.com:8200):",
+			"vault url",
+			$defaults->{vault_url},
+		);
+	};
+
+	return {
+		ci_provider   => $ci_provider,
+		pipeline_name => $pipeline_name,
+		git_uri       => $git_uri,
+		git_branch    => $git_branch,
+		vault_url     => $vault_url,
+	};
+}
+
+# _apply_ci_flags - non-interactive partial update (repo_update with flags)
+sub _apply_ci_flags {
+	my ($options, $top) = @_;
+
+	unless ($top->config->has('ci.provider') || exists $options->{'ci-provider'}) {
+		warning(
+			"CI provider not configured and --ci-provider not given.\n".
+			"Run #C{genesis repo-init} to perform initial CI setup."
+		);
+	}
+
+	if (exists $options->{'ci-provider'}) {
+		my $provider = $options->{'ci-provider'};
+		bail(
+			"Unknown CI provider '#R{%s}'. Valid values: concourse, github-actions, none.",
+			$provider
+		) unless grep { $_ eq $provider } qw(concourse github-actions none);
+		$top->config->set('ci.provider', $provider, 1);
+	}
+
+	my $ci_dir = $top->path('.genesis/ci');
+	mkdir_or_fail($ci_dir) unless -d $ci_dir;
+
+	# Update integrations.yml in-place if any integration flags were given
+	my @integration_flags = grep { exists $options->{$_} } qw(git-uri git-branch vault-url);
+	if (@integration_flags && -f "$ci_dir/integrations.yml") {
+		my $raw = slurp("$ci_dir/integrations.yml");
+		if (exists $options->{'vault-url'}) {
+			my $v = $options->{'vault-url'};
+			$raw =~ s/^(\s{0,4}url:\s*)\S+/$1$v/m;
+		}
+		if (exists $options->{'git-uri'}) {
+			my $v = $options->{'git-uri'};
+			$raw =~ s/^(\s{0,4}uri:\s*)\S+/$1$v/m;
+		}
+		if (exists $options->{'git-branch'}) {
+			my $v = $options->{'git-branch'};
+			$raw =~ s/^(\s{0,4}default_branch:\s*)\S+/$1$v/m;
+		}
+		mkfile_or_fail("$ci_dir/integrations.yml", $raw);
+	} elsif (@integration_flags) {
+		# integrations.yml doesn't exist yet - need full defaults to write it
+		my $defaults  = _existing_ci_defaults($top);
+		$defaults->{'vault-url'}   = $options->{'vault-url'}   if exists $options->{'vault-url'};
+		$defaults->{'git-uri'}     = $options->{'git-uri'}     if exists $options->{'git-uri'};
+		$defaults->{'git-branch'}  = $options->{'git-branch'}  if exists $options->{'git-branch'};
+		_write_integrations($ci_dir, $defaults);
+	}
+
+	# Write provider override scaffold if provider changed and file is absent
+	if (exists $options->{'ci-provider'} && $options->{'ci-provider'} ne 'none') {
+		_write_if_absent("$ci_dir/ci-overrides-$options->{'ci-provider'}.yml",
+			_overrides_scaffold($options->{'ci-provider'}));
+	}
+
+	# Ensure other scaffold stubs exist
+	_write_if_absent("$ci_dir/targets.yml",  _targets_scaffold());
+	_write_if_absent("$ci_dir/resources.yml", _resources_scaffold());
+}
+
+# _write_ci_config - write config key and scaffold directory for init/full update
+sub _write_ci_config {
+	my ($top, $cfg) = @_;
+
+	my $provider = $cfg->{ci_provider};
+
+	$top->config->set('ci.provider', $provider, 1);
+
+	my $ci_dir = $top->path('.genesis/ci');
+	mkdir_or_fail($ci_dir) unless -d $ci_dir;
+
+	# integrations.yml — always write (contains wizard-collected values)
+	_write_integrations($ci_dir, $cfg);
+
+	# Remaining scaffold files: write only if absent (preserve manual edits on update)
+	_write_if_absent("$ci_dir/targets.yml",   _targets_scaffold());
+	_write_if_absent("$ci_dir/resources.yml", _resources_scaffold());
+	if ($provider ne 'none') {
+		_write_if_absent("$ci_dir/ci-overrides-${provider}.yml",
+			_overrides_scaffold($provider));
+	}
+}
+
+# _write_integrations - write .genesis/ci/integrations.yml from collected config
+sub _write_integrations {
+	my ($ci_dir, $cfg) = @_;
+
+	my $vault_url     = $cfg->{vault_url}   // $cfg->{'vault-url'}   // '';
+	my $git_uri       = $cfg->{git_uri}     // $cfg->{'git-uri'}     // '';
+	my $git_branch    = $cfg->{git_branch}  // $cfg->{'git-branch'}  // 'main';
+
+	mkfile_or_fail("$ci_dir/integrations.yml", <<"YAML");
+---
+vault:
+  url: $vault_url
+  namespace: genesis
+  auth:
+    type: approle
+    role_id: ((vault-role-id))
+    secret_id: ((vault-secret-id))
+  options:
+    tls_verify: true
+
+source_control:
+  provider: github
+  uri: $git_uri
+  default_branch: $git_branch
+  root: "."
+  auth:
+    type: ssh-key
+    private_key: ((github-deploy-key))
+  commit_author:
+    name: Concourse Bot
+    email: ci\@example.com
+YAML
+}
+
+sub _write_if_absent {
+	my ($path, $content) = @_;
+	mkfile_or_fail($path, $content) unless -f $path;
+}
+
+sub _targets_scaffold {
+	return <<'YAML';
+---
+# targets.yml - BOSH director targets for pipeline deployments.
+# Add one stanza per environment. The key name must match the environment
+# name used in pipeline topology declarations (genesis.pipeline.prior_env).
+#
+# Example:
+#   sandbox:
+#     name: sandbox
+#     alias: us-west-1-sandbox
+#     type: bosh-director
+#     tags: []
+#     connection:
+#       url: https://bosh.sandbox.example.com:25555
+#       auth:
+#         type: basic
+#         client_id: admin
+#         client_secret: ((sandbox-bosh-password))
+#       ca_cert: ((sandbox-bosh-ca))
+targets: {}
+YAML
+}
+
+sub _resources_scaffold {
+	return <<'YAML';
+---
+# resources.yml - Additional CI resources.
+# Add custom Concourse resource definitions or GitHub Actions inputs here.
+resources: []
+YAML
+}
+
+sub _overrides_scaffold {
+	my ($provider) = @_;
+	return <<"YAML";
+---
+# ci-overrides-${provider}.yml
+# Spruce-merged over generated pipeline YAML after provider output.
+# Supports all spruce operators: (( grab )), (( inject )), (( append )), etc.
+# Leave empty or remove this file to use the default generated pipeline.
+YAML
+}
+
 1;
 # vim: fdm=marker:foldlevel=0:noet
diff --git a/lib/Genesis/Commands/Utility.pm b/lib/Genesis/Commands/Utility.pm
index ef9e5b2a..794c95d6 100644
--- a/lib/Genesis/Commands/Utility.pm
+++ b/lib/Genesis/Commands/Utility.pm
@@ -101,20 +101,15 @@ sub multi_select_prompt_handler {
 sub secret_line_prompt_handler {
 	my ($prompt,%opts) = @_;
 	my $secret = delete $opts{secret};
-	my $env = delete $opts{env};
+	my $secrets_base = delete $opts{secrets_base};
 	validate_prompt_opts("secret-line", \%opts, qw(echo));
 
-	my $vault;
-	if ($env && $env->kit->feature_compatibility('2.7.0-rc4')) {
-		$secret = $env->secrets_base.$secret unless $secret =~ /^\//;
-		$vault = $env->vault;
-	} else {
-		$secret = "secret/$secret";
-		require Service::Vault::Remote;
-		$vault = Service::Vault::Remote->current || Service::Vault::Remote->rebind();
-	}
-	my ($path, $key) = split /:/, $secret;
+	require Service::Vault::Remote;
+	my $vault = Service::Vault::Remote->current || Service::Vault::Remote->rebind();
 	bail("No vault selected!") unless $vault;
+
+	$secret = $secrets_base.$secret unless $secret =~ /^\//;
+	my ($path, $key) = split /:/, $secret;
 	print "\n";
 	$vault->query(
 		{ interactive => 1, onfailure => "Failed to save data to #C{$secret} in vault" },
@@ -123,21 +118,16 @@ sub secret_line_prompt_handler {
 sub secret_block_prompt_handler {
 	my ($prompt,%opts) = @_;
 	my $secret = delete $opts{secret};
-	my $env = delete $opts{env};
+	my $secrets_base = delete $opts{secrets_base};
 	validate_prompt_opts("secret-block", \%opts, ());
 	my $file = mkfile_or_fail(workdir()."/param", prompt_for_block($prompt));
 
-	my $vault;
-	if ($env && $env->kit->feature_compatibility('2.7.0-rc4')) {
-		$secret = $env->secrets_base.$secret unless $secret =~ /^\//;
-		$vault = $env->vault;
-	} else {
-		$secret = "secret/$secret";
-		require Service::Vault::Remote;
-		$vault = Service::Vault::Remote->current || Service::Vault::Remote->rebind();
-	}
-	my ($path, $key) = split /:/, $secret;
+	require Service::Vault::Remote;
+	my $vault = Service::Vault::Remote->current || Service::Vault::Remote->rebind();
 	bail("No vault selected!") unless $vault;
+
+	$secret = $secrets_base.$secret unless $secret =~ /^\//;
+	my ($path, $key) = split /:/, $secret;
 	print "\n";
 	$vault->query(
 		{ onfailure => "Failed to save data to #C{$secret} in vault" },
@@ -173,14 +163,8 @@ sub ui_prompt_for {
 	my $use_vault = ($type =~ /^secret-/);
 	if ($use_vault) {
 		get_options->{secret} = $path;
-		eval {
-			require Genesis::Top;
-			get_options->{env} = Genesis::Top->new($ENV{GENESIS_ROOT})->load_env($ENV{GENESIS_ENVIRONMENT});
-		};
-		if ($@) {
-			debug "Failed in ui-prompt-for attempting to load environment:\n$@";
-			bail "Cannot prompt for secrets outside a kit hook";
-		}
+		get_options->{secrets_base} = $ENV{GENESIS_SECRETS_BASE}
+			|| bail("Cannot prompt for secrets: GENESIS_SECRETS_BASE not set (not in a kit hook?)");
 	}
 
 	bail(
diff --git a/lib/Genesis/Config.pm b/lib/Genesis/Config.pm
index 00d57932..276a9574 100644
--- a/lib/Genesis/Config.pm
+++ b/lib/Genesis/Config.pm
@@ -265,8 +265,10 @@ sub validate {
 			# Set default only if not loaded or explicitly set
 			$self->_update_source('default', $key, $schema->{$key}{default});
 		} elsif ($schema->{$key}{required} and ! struct_has($self->{loaded_values}, $key) and ! struct_has($self->{set_values}, $key)) {
-			push @errors, "#R{$key}: missing required key";
-			next;
+			if (_is_required($schema->{$key}{required}, $self->_contents)) {
+				push @errors, "#R{$key}: missing required key";
+				next;
+			}
 		}
 	}
 
@@ -366,6 +368,29 @@ sub _signature {
 	my $explicit = priority_merge($self->{set_values}, $self->{loaded_values});
 	return sha1_hex(JSON::PP->new->canonical->encode($explicit));
 }
+# }}}
+# _is_required - evaluate whether a 'required' constraint is active {{{
+#   1              → always required
+#   'sibling'      → required when sibling is truthy
+#   { sibling => v } → required when sibling eq v
+#
+# Multiple hash keys are OR'd together.  Future: support arrayref values
+# for multi-match on a single sibling, and negation (e.g. { '!key' => v }).
+sub _is_required {
+	my ($req, $siblings) = @_;
+	return 0 unless $req;
+	return 1 unless ref($req) || $req =~ /\D/;
+	if (ref($req) eq 'HASH') {
+		for my $dep (keys %$req) {
+			return 1 if exists($siblings->{$dep}) && defined($siblings->{$dep})
+				&& $siblings->{$dep} eq $req->{$dep};
+		}
+		return 0;
+	}
+	# String (non-numeric): truthy check on named sibling
+	return $siblings->{$req} ? 1 : 0;
+}
+
 # }}}
 # _validate_key - validate a value against a schema {{{
 sub _validate_key {
@@ -419,7 +444,9 @@ sub _validate_key {
 					my $source = $loaded_is_empty_hash ? 'loaded' : 'default';
 					$self->_update_source($source, "$key.$subkey", $subschema->{default});
 				} elsif ($subschema->{required} and ! exists($value->{$subkey})) {
-					push @errors, "#R{$key}: missing required key #ri{$subkey}";
+					if (_is_required($subschema->{required}, $value)) {
+						push @errors, "#R{$key}: missing required key #ri{$subkey}";
+					}
 				}
 			}
 			# Refetch value to include newly-added defaults for recursive validation
@@ -590,6 +617,9 @@ sub _validate_key {
 		if (defined($value)) {
 			push @errors, "#R{$key}: expected null, not #ri{".($value ? $value : "<null>")."}";
 		}
+	} elsif ($type eq 'opaque') {
+		# Passthrough — any value accepted, sub-keys not validated here.
+		# Used for config sections delegated to other modules (see Top::register_config_section).
 	} elsif ($type eq 'any') {
 		# Do nothing
 	} else {
diff --git a/lib/Genesis/Env.pm b/lib/Genesis/Env.pm
index 86020a5e..b66e3eda 100644
--- a/lib/Genesis/Env.pm
+++ b/lib/Genesis/Env.pm
@@ -340,9 +340,19 @@ sub create {
 	my $env = $class->new(get_opts(\%opts, qw(name top kit)));
 	my $create_env = $opts{'create-env'};
 
-	# environment must not already exist...
-	die "Environment file $env->{file} already exists.\n"
-		if -f $env->path($env->{file});
+	# environment must not already exist (unless --force)
+	my $env_path = $env->path($env->{file});
+	if (-f $env_path) {
+		die "Environment file $env->{file} already exists.\n"
+			unless $opts{force};
+		# Move the existing file out of the way so the new hook
+		# starts fresh and $self->exists returns false.  The .old
+		# file is kept for reference (manual diff / re-create).
+		my $old_path = "${env_path}.old";
+		rename($env_path, $old_path)
+			or bail("Could not move existing %s to %s: %s", $env->{file}, "$env->{file}.old", $!);
+		notice("\nMoved existing #C{%s} to #C{%s.old}", $env->{file}, $env->{file});
+	}
 
 	# Sanitize the vault descriptor, if present
 	if ($opts{vault}) {
@@ -389,15 +399,30 @@ sub create {
 			$env->{__params}{genesis}{use_create_env} = 0;
 			$env->{__params}{genesis}{bosh_env} = $bosh_env//$opts{name};
 		} else {
-			# Complicated state: the kit allows but does not require create-env.
-			warning(
-				"\nKit #M{%s} supports both bosh and create-env deployment.  No --create-env ".
-				"option specified, so using bosh deployment method.",
-				$env->kit->id
-			) unless defined($create_env) || $bosh_env;
+			# Kit allows but does not require create-env.  When neither
+			# --create-env nor --bosh-env is given, default based on
+			# whether the kit is a BOSH director: director kits default
+			# to create-env (they create the director itself), everything
+			# else defaults to bosh deployment.  This matches the
+			# pre-2.8.0 heuristic and the use_create_env accessor logic.
 			bail(
 				"Cannot specify a bosh environment for environments that use create-env deployment method."
 			) if $create_env && $bosh_env;
+			unless (defined($create_env) || $bosh_env) {
+				if ($env->is_bosh_director) {
+					$create_env = 1;
+					warning(
+						"\nNo #C{--bosh-env} specified — defaulting to #C{create-env} deployment ".
+						"for this BOSH director kit."
+					);
+				} else {
+					warning(
+						"\nKit #M{%s} supports both bosh and create-env deployment.  No --create-env ".
+						"option specified, so using bosh deployment method.",
+						$env->kit->id
+					);
+				}
+			}
 			$env->{__params}{genesis}{use_create_env} = $create_env//0;
 			$env->{__params}{genesis}{bosh_env} = $create_env ? '' : $bosh_env || $opts{name};
 		}
@@ -419,7 +444,7 @@ sub create {
 	bail("No vault specified or configured.")
 		unless $env->vault;
 
-	my ($results) = $env->remove_secrets(all => 1, no_populate => 1);
+	my ($results) = $env->remove_secrets(all => 'purge');
 	bail "Cannot continue with existing secrets for this environment"
 		if ($results->{abort} || $results->{error});
 
@@ -455,14 +480,74 @@ sub create {
 		}
 	}
 
-	if (! $env->add_secrets(verbose=>1, import => 1)) {
-		$env->remove_secrets(all => 1, 'no-prompt' => 1);
-		unlink $env->file;
-		return undef;
-	}
 	return $env;
 }
 
+# }}}
+# genesis_config_block - generate a YAML genesis: config block for injection into env files {{{
+sub genesis_config_block {
+	my ($self) = @_;
+
+	# Perl analogue of the legacy bash helper `genesis_config_block`, but
+	# prefers inferred/declared values from the env object.
+	my @out = ('genesis:');
+	push @out, "  env:<pad>".$self->{name};
+
+	# bosh_env: only emit when not create-env, and when it differs from the env name
+	my $bosh_env_desc = $self->bosh_env->{description} // '';
+	push @out, "  bosh_env:<pad>$bosh_env_desc"
+		if !$self->use_create_env && $bosh_env_desc ne '' && $bosh_env_desc ne $self->name;
+
+	# vault: prefer env-configured value; omit if unset
+	my $vault_desc = $self->lookup('genesis.vault', undef);
+	push @out, "  vault:<pad>$vault_desc"
+		if defined($vault_desc) && $vault_desc ne '';
+
+	# min_version: prefer env value, else use current runtime (except development)
+	my $min_version = $self->lookup(['genesis.min_version','genesis.minimum_version'], undef);
+	$min_version //= $Genesis::VERSION unless $Genesis::VERSION eq '(development)';
+	push @out, "  min_version:<pad>$min_version"
+		if defined($min_version) && $min_version ne '';
+
+	# secrets/exodus/ci: derived from env
+	push @out, '  secrets_path:<pad>'.$self->secrets_slug unless $self->secrets_slug eq $self->default_secrets_slug;
+	push @out, '  secrets_mount:<pad>'.$self->secrets_mount unless $self->secrets_mount eq $self->default_secrets_mount;
+	push @out, '  exodus_mount:<pad>'.$self->exodus_mount unless $self->exodus_mount eq $self->default_exodus_mount;
+	push @out, '  ci_mount:<pad>'.$self->ci_mount unless $self->ci_mount eq $self->default_ci_mount;
+
+	# root_ca_path: optional
+	my $root_ca_path = $self->root_ca_path;
+	push @out, "  root_ca_path:<pad>$root_ca_path"
+		if defined($root_ca_path) && $root_ca_path ne '';
+
+	# credhub_env: optional
+	my $credhub_env = $self->lookup('genesis.credhub_env', '');
+	push @out, "  credhub_env:<pad>$credhub_env" if $credhub_env ne '';
+
+	# Determine padding for alignment based on longest key
+	my $max_key_length = 0;
+	for my $line (@out) {
+		next unless $line =~ /^(\s*\S+):<pad>/;
+		my $key_length = length($1);
+		$max_key_length = $key_length if $key_length > $max_key_length;
+	}
+	for my $line (@out) {
+		next unless $line =~ /^(\s*\S+):<pad>/;
+		my $key_length = length($1);
+		$line =~ s/<pad>/ ' ' x ($max_key_length - $key_length + 2)/e;
+	}
+
+	return join("\n", @out)."\n\n";
+}
+
+# }}}
+# write_manifest - write the environment file manifest to disk {{{
+sub write_manifest {
+	my ($self, $content) = @_;
+	my $path = $self->path($self->{file});
+	mkfile_or_fail($path, 0644, $content);
+}
+
 # }}}
 # exists - returns true if the given environment exists {{{
 sub exists {
@@ -763,7 +848,7 @@ sub file   { $_[0]->{file};   }
 sub kit    { $_[0]->{kit}    || bug("Incompletely initialized environment '".$_[0]->name."': no kit specified"); }
 sub top    { $_[0]->{top}    || bug("Incompletely initialized environment '".$_[0]->name."': no top specified"); }
 
-# }}}
+# }}
 # Delegations: type, path {{{
 sub type   { $_[0]->top->type; }
 sub path   { shift->top->path(@_); }
@@ -952,7 +1037,11 @@ sub use_create_env {
 sub can_build_cloud_configs {
 	my $self = shift;
 	return 0 unless $self->feature_compatibility("3.1.0-rc.9");
-	return 0 unless $self->lookup('genesis.manage-cloud-configs')//1;
+	# Cloud-config generation is an OCFP-only concern; non-OCFP envs
+	# have their cloud-config managed externally regardless of whether
+	# the kit happens to provide a cloud-config hook.
+	return 0 unless $self->is_ocfp;
+	return 0 unless $self->lookup('genesis.manage-cloud-configs', 1);
 	return 1;
 }
 
@@ -1168,6 +1257,321 @@ sub actual_environment_files {
 	return @$ref;
 }
 
+# }}}
+# propagation_files - git-root-relative paths this env depends on for pipeline propagation {{{
+#
+# Returns the unified pathspec that propagation and pruning operate
+# over: kit dependencies (env file hierarchy, kit archive, config,
+# reaction scripts) prefixed with the git prefix so they're
+# git-root-relative, plus any `genesis.pipeline.required_files`
+# declared on the env (already git-root-relative).
+#
+# All returned paths are relative to the git root — no caller
+# should apply `Service::Git->prefixed` on top.
+sub propagation_files {
+	my ($self) = @_;
+	my %files;
+
+	# Env file hierarchy (ancestors + self) — kit-relative
+	for my $f ($self->actual_environment_files) {
+		$f =~ s{^\./}{};
+		$files{$f} = 1;
+	}
+
+	# Kit source (compiled tarball or dev directory)
+	if ($self->kit->is_dev) {
+		$files{'dev/'} = 1;
+	} else {
+		my $source = $self->kit->{source};
+		if ($source) {
+			my $rel = $source;
+			$rel =~ s{^\Q${\$self->path}\E/?}{};
+			$files{$rel} = 1;
+		}
+	}
+
+	# Config
+	$files{'.genesis/config'} = 1;
+
+	# Reaction scripts
+	my $reactions = $self->lookup('genesis.reactions', {});
+	if (ref($reactions) eq 'HASH') {
+		for my $phase (values %$reactions) {
+			next unless ref($phase) eq 'ARRAY';
+			for my $action (@$phase) {
+				next unless ref($action) eq 'HASH' && $action->{script};
+				$files{"bin/$action->{script}"} = 1;
+			}
+		}
+	}
+
+	require Service::Git;
+	my $git = Service::Git->new('.');
+
+	# Prefix kit-relative paths to git-root-relative
+	my %out = map { $_ => 1 } $git->prefixed(sort keys %files);
+
+	# Merge required_files — already git-root-relative, validated
+	$out{$_} = 1 for $self->required_files;
+
+	return sort keys %out;
+}
+
+# }}}
+# required_files - list additional paths that should travel with this env's branch {{{
+#
+# Reads `genesis.pipeline.required_files` (inherited via env file
+# hierarchy — so pipeline-wide defaults can be declared in a parent
+# env file like `lmelt.yml` and apply to every child that doesn't
+# override).
+#
+# Path templates (user-facing, Top-root-relative):
+#   - `<env>` is substituted with the environment's name
+#   - Glob metacharacters (`*`, `?`, `[`) are expanded against the
+#     deployment top root (i.e., the kit subdirectory)
+#   - Anything else is used verbatim as a Top-root-relative path
+#
+# Returns git-root-relative paths for internal use — callers pass
+# them straight to git.  User-facing output should strip the git
+# prefix before display.
+sub required_files {
+	my ($self) = @_;
+
+	my $entries = $self->lookup('genesis.pipeline.required_files', []);
+	return () unless ref($entries) eq 'ARRAY' && @$entries;
+
+	require Service::Git;
+	my $git  = Service::Git->new('.');
+	my $root = $git->root;
+	return () unless $root;
+
+	# Top root = git root + git prefix (e.g., "$repo/bosh" for a bosh/ kit)
+	my $top_root = $root;
+	if (my $prefix = $git->prefix) {
+		(my $p = $prefix) =~ s{/$}{};
+		$top_root = "$root/$p" if length $p;
+	}
+
+	my @top_relative = __PACKAGE__->_resolve_required_files(
+		$entries, $self->name, $top_root
+	);
+	return $git->prefixed(@top_relative);
+}
+
+# _resolve_required_files - pure helper for required_files path resolution {{{
+#
+# Takes a list of raw path templates, an env name, and a root path
+# (conceptually the deployment Top root).  Returns sorted unique
+# paths relative to that root:
+#   - `<env>` is substituted with the env name
+#   - Glob patterns are expanded against the filesystem under the
+#     provided root
+#   - Literal paths are passed through verbatim
+#
+# Rejects entries that would escape the root (absolute paths,
+# `~/...`, or any `..` segment).  Bail()s on violation so config
+# errors surface loudly.
+#
+# Exposed as a class method so unit tests can exercise the logic
+# without constructing an Env or touching Service::Git.
+sub _resolve_required_files {
+	my ($class, $entries, $env_name, $root) = @_;
+	return () unless ref($entries) eq 'ARRAY' && @$entries;
+	return () unless defined $root && length $root;
+
+	require File::Glob;
+
+	my %out;
+	for my $raw (@$entries) {
+		next unless defined $raw && length $raw;
+		(my $path = $raw) =~ s/<env>/$env_name/g;
+
+		bail(
+			"genesis.pipeline.required_files entry #C{%s} escapes the deployment root.\n".
+			"  Paths must be relative to the deployment root — no #R{/}, #R{~/}, or #R{..} allowed.",
+			$raw
+		) if $path =~ m{^/} || $path =~ m{^~} || $path =~ m{(?:^|/)\.\.(?:/|$)};
+
+		if ($path =~ m{[*?\[]}) {
+			my @matches = File::Glob::bsd_glob("$root/$path");
+			for my $abs (@matches) {
+				(my $rel = $abs) =~ s{^\Q$root/\E}{};
+				$out{$rel} = 1 if length $rel;
+			}
+		} else {
+			$out{$path} = 1;
+		}
+	}
+
+	return sort keys %out;
+}
+
+# }}}
+
+# }}}
+# prepare_branch - create or reconcile this env's branch with the files it needs {{{
+#
+# Reconciles the environment branch with this env's propagation_files set:
+#
+#   1. Creates the branch from the current commit if it doesn't yet exist
+#      (so that newly-created envs land on a fresh branch off control HEAD).
+#   2. Adds any files this env needs that aren't already on the branch
+#      (the multi-deployment-per-repo case: branch was created when only
+#      the bosh deployment existed; now we're adding a vault env file
+#      that needs to land on the same branch).
+#   3. Removes tracked files under our git prefix that this env no longer
+#      depends on, keeping .genesis/ wholesale.  Files outside our prefix
+#      are left alone — other deployments sharing this repo own them.
+#
+# All add/remove changes land in a single commit on the env branch and
+# the original branch is restored before returning.
+#
+# Options:
+#   dry_run => 1   — return the planned add/remove sets without changing
+#                    anything on disk or in git
+#
+# Returns: ($added_arrayref, $removed_arrayref).  Either may be empty.
+sub prepare_branch {
+	my ($self, %opts) = @_;
+
+	require Service::Git;
+	my $git    = Service::Git->new('.');
+	my $branch = $self->name;
+	my @keep   = $self->propagation_files;
+
+	# Must not be on the env branch (we need to copy files INTO it from
+	# the current branch's HEAD).
+	unless ($opts{dry_run}) {
+		bail(
+			"Cannot prepare #C{%s} while on that branch.  Switch to the control branch first.",
+			$branch
+		) if ($git->current_branch // '') eq $branch;
+	}
+
+	# propagation_files returns git-root-relative paths already
+	my %keep_set = map { $_ => 1 } @keep;
+
+	# Compute the add/remove sets.  When the branch doesn't exist yet, we
+	# treat the current HEAD as its starting tree (so "tracked" is what
+	# the new branch would inherit before reconciliation).
+	my $branch_exists = $git->branch_exists($branch);
+	my $tree_ref      = $branch_exists ? $branch : 'HEAD';
+	my @tracked       = $git->ls_tree($tree_ref, $git->prefix);
+	my %tracked_set   = map { $_ => 1 } @tracked;
+
+	my @to_add = grep { !$tracked_set{$_} } @keep;
+
+	my @to_remove;
+	for my $file (@tracked) {
+		next if $file =~ m{^\Q@{[$git->prefix]}\E\.genesis/};
+		next if $keep_set{$file};
+		# Don't touch anything outside our prefix — other deployments in
+		# this repo may own files on this branch (multi-deploy repos),
+		# and users may keep hand-added artifacts (CI config, notes, etc.)
+		# that we don't know about.
+		next if $git->prefix && $file !~ m{^\Q@{[$git->prefix]}\E};
+		push @to_remove, $file;
+	}
+
+	# Nothing to do AND branch already exists: idempotent no-op.
+	return ([], []) if $branch_exists && !@to_add && !@to_remove;
+	return (\@to_add, \@to_remove) if $opts{dry_run};
+
+	# Source SHA for any add operations: whatever the current branch
+	# points at.  For a brand-new branch this is also the branch's HEAD.
+	my $source_sha = $git->sha('HEAD');
+
+	# We're about to swap branches, and the target branch may not have
+	# the deployment subdirectory the user is currently in (multi-deploy
+	# repos: branch was created when only the bosh deployment existed,
+	# now we're adding vault/<env>.yml).  After the checkout, popping
+	# back to a now-vanished cwd would fatal.  Step up to the git root
+	# for the duration of the swap; restore_branch puts us back on a
+	# branch where the original cwd exists again.
+	pushd($git->{root});
+
+	# Create the branch off the current commit if it didn't exist.
+	$git->create_branch($branch) unless $branch_exists;
+
+	$git->checkout($branch);
+
+	# checkout_file creates any missing parent directories itself, so a
+	# brand-new deployment subdirectory (vault/, jumpbox/, etc.) on a
+	# branch that didn't have it before materializes naturally.
+	$git->checkout_file($source_sha, $_) for @to_add;
+	$git->rm(@to_remove) if @to_remove;
+
+	my $msg;
+	if (!$branch_exists) {
+		# First time we're committing on this branch.  Even with no
+		# add/remove (everything from HEAD already belonged), record an
+		# empty seed commit so the branch has a distinct propagation
+		# anchor.  Skip when there's literally nothing different from
+		# HEAD — the branch already starts there.
+		$msg = sprintf("Initialize %s branch (%d added, %d removed)",
+			$branch, scalar(@to_add), scalar(@to_remove));
+	} else {
+		$msg = sprintf("Reconcile %s branch (%d added, %d removed)",
+			$branch, scalar(@to_add), scalar(@to_remove));
+	}
+
+	if (@to_add || @to_remove) {
+		$git->commit($msg, @to_add);
+	}
+
+	# Switch back to control before popping back to the original cwd —
+	# that cwd lives on control (we just came from there) and may not
+	# exist on the env branch.
+	$git->restore_branch;
+	popd;
+
+	return (\@to_add, \@to_remove);
+}
+
+# }}}
+# propagation_diff - files that changed between this env branch and a control commit {{{
+#
+# Compares this environment's branch against a target commit on the
+# control branch, filtered to only files this env depends on.
+# Returns a list of repo-relative paths that need propagating.
+#
+# The target_sha is embedded in the propagation commit message so
+# downstream environments can trace which control state they deployed.
+sub propagation_diff {
+	my ($self, $target_sha) = @_;
+	$target_sha ||= 'control';
+
+	my @pathspec = $self->propagation_files;
+	return () unless @pathspec;
+
+	my $env_branch = $self->name;
+	my ($diff_out, $rc) = run(
+		{ passfail => 1 },
+		'git', 'diff', '--name-only', "$env_branch..$target_sha", '--', @pathspec
+	);
+	return () if $rc || !$diff_out;
+
+	return grep { /\S/ } split /\n/, $diff_out;
+}
+
+# }}}
+# last_propagated_sha - extract the control SHA from the last propagation commit {{{
+sub last_propagated_sha {
+	my ($self) = @_;
+	my ($log, $rc) = run(
+		{ passfail => 1 },
+		'git', 'log', '--format=%s', $self->name, '--', '.'
+	);
+	return undef if $rc || !$log;
+
+	for my $line (split /\n/, $log) {
+		if ($line =~ /control\@([0-9a-f]+)/) {
+			return $1;
+		}
+	}
+	return undef;
+}
+
 # }}}
 # relate - get hierarchal file relationships with another environment {{{
 sub relate {
@@ -1458,28 +1862,61 @@ sub scale {
 
 # }}}
 # iaas - returns the iaas for the environment {{{
+#
+# Resolution order:
+#   1. kit.iaas (explicit — works for both OCFP and non-OCFP)
+#   2. kit.features (non-OCFP only: silently upconvert IaaS feature)
+#   3. Director exodus data (inherited from parent BOSH director)
+#   4. Bail with context-appropriate message
+#
+my @_known_iaas = qw(vsphere aws azure google openstack warden);
 sub iaas {
 	my ($self) = @_;
-	my $iaas = $self->lookup('kit.iaas');
 
+	# 1. Explicit kit.iaas (OCFP sets this; non-OCFP may also use it)
+	my $iaas = $self->lookup('kit.iaas');
 	return lc($iaas) if $iaas;
 
-	bail(
-		"No IaaS type set for %s environment, which uses a create-env deployment. ".
-		"Please set the `kit.iaas` in the enviroment file -- you can use #G{%s ".
-		"%s edit} to do this.",
-		$self->name,
-		humanize_bin(),
-		humanize_path($self->path($self->name))
-	) if $self->use_create_env;
+	# 2. Non-OCFP: silently derive from kit.features.
+	#    Check kit.features directly via lookup (returns from __params
+	#    cache during create) — do NOT call is_ocfp()/has_feature()
+	#    which triggers features() → features hook → get_environment_variables
+	#    → iaas() recursion.
+	my @features = @{$self->lookup('kit.features', [])};
+	my $is_ocfp = grep { $_ eq 'ocfp' } @features;
+	unless ($is_ocfp) {
+		for my $f (@features) {
+			return lc($f) if grep { $f eq $_ } @_known_iaas;
+		}
+	}
 
-	eval {$iaas = $self->director_exodus_lookup('iaas') }; # FIXME: How to handle multiple CPIs?
+	# 3. Inherit from the BOSH director's exodus data
+	unless ($self->use_create_env) {
+		eval { $iaas = $self->director_exodus_lookup('iaas') }; # FIXME: How to handle multiple CPIs?
+		return lc($iaas) if $iaas;
+	}
 
+	# 4. Nothing found — bail with appropriate guidance
+	if ($is_ocfp) {
+		bail(
+			"No IaaS type set for OCFP environment %s. ".
+			"Set #C{kit.iaas} in the environment file or ensure it is ".
+			"inherited from the parent BOSH director.",
+			$self->name,
+		);
+	} elsif ($self->use_create_env) {
+		bail(
+			"No IaaS type found for %s environment (create-env deployment). ".
+			"Set #C{kit.iaas} in the environment file or include the IaaS ".
+			"as a kit feature (e.g. #C{features: [vsphere, ...]}).",
+			$self->name,
+		);
+	}
 	bail(
 		"No IaaS type set for %s environment, and no default IaaS type set for ".
 		"deployments under %s bosh director.",
 		$self->name, $self->bosh->alias
-	) if ! $iaas && $self->kit->requires_iaas($self);
+	) if $self->kit->requires_iaas($self);
 
 	return lc($iaas//'');
 }
@@ -1816,8 +2253,12 @@ sub get_environment_variables {
 		$env{GENESIS_KIT_PATH}                 = $self->kit->path;
 		$env{GENESIS_MIN_VERSION_FOR_KIT}      = $self->kit->genesis_version_min();
 		if ($self->exists) {
-			$env{GENESIS_ENV_IAAS}               = $self->iaas();
-			$env{GENESIS_ENV_SCALE}              = $self->scale();
+			# Skip iaas/scale for the features hook — they're derived
+			# from features and calling them here recurses via bosh.
+			if ($hook ne 'features') {
+				$env{GENESIS_ENV_IAAS}               = $self->iaas();
+				$env{GENESIS_ENV_SCALE}              = $self->scale();
+			}
 			$env{GENESIS_ENV_KIT_OVERRIDE_FILES} = join(' ', $self->kit->env_override_files);
 		}
 
@@ -1876,11 +2317,21 @@ sub credhub_connection_env {
 	my ($credhub_src,$credhub_src_key) = $self->lookup(
 		['genesis.credhub_env','genesis.bosh_env','params.bosh','genesis.env','params.env']
 	);
+
+	# create-env environments have genesis.bosh_env = '' (empty string)
+	# which lookup finds as "defined".  Fall through to the next keys
+	# so we don't try to parse an empty string as a BOSH env descriptor.
+	if ($credhub_src_key && $credhub_src_key eq 'genesis.bosh_env' && !length($credhub_src // '')) {
+		($credhub_src,$credhub_src_key) = $self->lookup(
+			['genesis.env','params.env']
+		);
+	}
+
 	my %env=();
 
 	my $credhub_info = {};
 	$env{GENESIS_CREDHUB_EXODUS_SOURCE_OVERRIDE} = "";
-	if ($credhub_src_key eq 'genesis.bosh_env') {
+	if ($credhub_src_key && $credhub_src_key eq 'genesis.bosh_env') {
 		my ($bosh_alias,$bosh_dep_type,$bosh_exodus_vault,$bosh_exodus_mount) = $self->_parse_bosh_env($credhub_src);
 		$bosh_alias //= $self->name;
 		$bosh_dep_type //= 'bosh';
@@ -3156,11 +3607,13 @@ sub deploy {
 		? $self->_deploy_create_env(%opts, noprompt => $noprompt)
 		: $self->_deploy_to_bosh(%opts, noprompt => $noprompt);
 
-	my $deploy_completed = gettimeofday;
-	$self->notify(
-		"BOSH deployment completed in %s",
-		pretty_duration($deploy_completed - $self->{deployment_state}{deploy_started}, undef,undef, '','','-',1)
-	);
+	if (defined $self->{deployment_state}{deploy_started}) {
+		my $deploy_completed = gettimeofday;
+		$self->notify(
+			"BOSH deployment completed in %s",
+			pretty_duration($deploy_completed - $self->{deployment_state}{deploy_started}, undef,undef, '','','-',1)
+		);
+	}
 
 	# Run post-deployment phase
 	return $self->_post_deploy(%opts, noprompt => $noprompt);
@@ -3240,6 +3693,24 @@ sub _pre_deploy {
 	my ($self, %opts) = @_;
 	my $noprompt = delete($opts{noprompt});
 
+	# Snapshot the working tree (modified + untracked) before the
+	# deploy runs, scoped to our deployment prefix.  _post_deploy
+	# diffs against this to know which files this deploy actually
+	# produced.  Branch checkout + pull happens earlier (in
+	# Genesis::Commands::Env::deploy) so the preflight checks above
+	# this method run on the env-branch view.
+	if ($self->top->ci_configured) {
+		require Service::Git;
+		my $git    = Service::Git->new('.');
+		my $branch = $self->name;
+		my $prefix = $git->prefix // '';
+		my $pre    = $git->status($prefix || '.');
+
+		$self->{deployment_state}{pipeline_git}       = $git;
+		$self->{deployment_state}{pipeline_branch}    = $branch;
+		$self->{deployment_state}{pre_deploy_unclean} = $pre;
+	}
+
 	# Generate and store the deployment manifest (pruned and unpruned versions)
 	my $pruned_deploy_manifest = $self->manifest_provider->deployment(subset=>'pruned',notify=>1);
 	my $unpruned_deploy_manifest = $self->manifest_provider->deployment(notify=>0);
@@ -3451,8 +3922,10 @@ sub _deploy_create_env {
 		info "[[  - >>no previous deployment of this environment found in the deployment archive.";
 	}
 
-	# Confirm deployment
-	if (in_controlling_terminal && !$noprompt) {
+	# Confirm deployment (skip on dry-run — nothing destructive to confirm)
+	if ($opts{'dry-run'}) {
+		# no confirmation needed
+	} elsif (in_controlling_terminal && !$noprompt) {
 		prompt_for_boolean(
 			"Proceed with BOSH create-env for the #C{${\($self->name)}}? [y|n] ",1
 		) or $self->_cleanup_and_bail("Aborted!\n");
@@ -3482,6 +3955,16 @@ sub _deploy_create_env {
 	my @bosh_opts;
 	push @bosh_opts, "--$_" for grep { $opts{$_} } qw/recreate skip-drain/;
 
+	# Dry-run: skip the bosh create-env call but report what would deploy.
+	# bosh create-env doesn't support --dry-run natively, but we've already
+	# merged the manifest, checked secrets, and validated configs by this point.
+	if ($opts{'dry-run'}) {
+		$self->notify("dry-run: skipping #C{bosh create-env} (not supported by BOSH CLI)");
+		$self->notify("manifest: #C{%s}", humanize_path($state->{manifest_path}));
+		$state->{results} = ['(dry-run)', 0];
+		return $state->{ok} = 1;
+	}
+
 	# Execute deployment
 	$state->{deploy_started} = gettimeofday;
 	my @results = $self->bosh->create_env(
@@ -3531,14 +4014,6 @@ sub _post_deploy {
 
 	$self->notify("#G{Deployment successful.}") if $deployment_ok;
 
-	# Process post-deploy reactions
-	if ($self->_reactions && !$state->{disable_reactions}) {
-		$state->{reaction_vars}{GENESIS_DEPLOY_RC} = ($state->{results}[1]);
-		$self->_process_reactions('post-deploy', $state->{reaction_vars}) or warning(
-			"Environment post-deploy reaction failed!  Manual intervention may be needed."
-		);
-	}
-
 	# Save deployment log
 	my $manifest_store = $self->top->config->get('manifest_store','hybrid');
 	mkfile_or_fail(
@@ -3569,6 +4044,14 @@ sub _post_deploy {
 
 	# bail out early if the deployment failed;
 	if (!$deployment_ok) {
+		# Reactions on failure: GENESIS_DEPLOY_RC != 0 lets scripts skip.
+		if ($self->_reactions && !$state->{disable_reactions}) {
+			$state->{reaction_vars}{GENESIS_DEPLOY_RC} = ($state->{results}[1]);
+			$self->_process_reactions('post-deploy', $state->{reaction_vars}) or warning(
+				"Environment post-deploy reaction failed!  Manual intervention may be needed."
+			);
+		}
+
 		if (!$opts{"dry-run"} && $self->has_hook('post-deploy')) {
 			# Call post-deploy hook with the pre-deploy data in case of cleanup on failure
 			$self->run_hook('post-deploy', rc => $state->{results}[1], interactive => !$noprompt, data => $state->{predeploy_data});
@@ -3646,6 +4129,14 @@ sub _post_deploy {
 		exodus_overrides => $exodus_overrides
 	);
 
+	# Reactions on success: run AFTER exodus so `genesis bosh --self` works.
+	if ($self->_reactions && !$state->{disable_reactions}) {
+		$state->{reaction_vars}{GENESIS_DEPLOY_RC} = ($state->{results}[1]);
+		$self->_process_reactions('post-deploy', $state->{reaction_vars}) or warning(
+			"Environment post-deploy reaction failed!  Manual intervention may be needed."
+		);
+	}
+
 	# Clean up deployment cache
 	$self->deployment_cache_cleanup;
 
@@ -3660,6 +4151,100 @@ sub _post_deploy {
 		);
 	}
 
+	# CI-configured branch finalization: commit + push the deploy's
+	# manifest artifacts on the env branch, then run the auto-cascade
+	# (manual-provider only).  Non-manual providers (concourse, gha)
+	# own their own cascade, so we skip the cascade in those cases
+	# but still commit + push the manifest.
+	if ($self->top->ci_configured) {
+		my $git    = $state->{pipeline_git};
+		my $branch = $state->{pipeline_branch};
+
+		# Commit and push manifest artifacts that landed under
+		# .genesis/manifests/ during this deploy.  When manifest_store
+		# is 'repository' or 'hybrid' (the default), genesis writes
+		# the rendered manifest plus state/creds files there; without
+		# this step those files would be left untracked on the env
+		# branch and either lost on the next checkout or clobbered by
+		# the auto-cascade's checkout of control below.  No-op when
+		# nothing new ended up under .genesis/manifests/.
+		if ($deployment_ok && $git && $branch) {
+			my $pre = $state->{pre_deploy_unclean} || {};
+			my $prefix = $git->prefix // '';
+			# prefixed() returns a list; force scalar/list-ctx assignment
+			# so we get the path string, not the element count.
+			my ($manifests_subpath) = $git->prefixed('.genesis/manifests');
+
+			# Diff post-deploy working tree against the pre-deploy baseline.
+			my $post = $git->status($prefix || '.');
+			my (@new_manifests, @other);
+			for my $path (sort keys %$post) {
+				my $code = $post->{$path};
+				# Skip files already in this state pre-deploy.
+				next if exists($pre->{$path}) && $pre->{$path} eq $code;
+				if ($path =~ m{^\Q$manifests_subpath\E(?:/|$)}) {
+					push @new_manifests, $path;
+				} else {
+					push @other, sprintf("%s %s", $code, $path);
+				}
+			}
+
+			if (@other) {
+				warning(
+					"Deploy left unexpected working-tree changes outside #C{%s/}:\n%s\n\n".
+					"These are not being committed.  Review and clean up manually.",
+					$manifests_subpath,
+					join("\n", map {"  $_"} @other)
+				);
+			}
+
+			if (@new_manifests) {
+				$git->add($manifests_subpath);
+
+				my $sha_short = $git->sha('HEAD', short => 1) // '<unknown>';
+				my $msg = sprintf("[deploy] %s @ %s", $self->name, $sha_short);
+				$git->commit($msg);
+
+				if (my $remote = $git->default_remote) {
+					$self->notify(
+						"Rebasing #C{%s} onto #C{%s/%s} before push...",
+						$branch, $remote, $branch
+					);
+					$git->pull_rebase($branch, $remote);
+
+					$self->notify(
+						"Pushing #C{%s} deploy artifacts to #C{%s}...",
+						$branch, $remote
+					);
+					my $results = $git->push($remote, $branch);
+					bail("Failed to push %s to %s after deploy", $branch, $remote)
+						unless $results->{$branch};
+				}
+			}
+		}
+
+		# Auto-cascade propagation (manual-provider only).
+		if (($self->top->config->get('ci.provider.type') || '') eq 'manual'
+			&& !$opts{'no-propagate'}) {
+
+			require Service::Git;
+			require Genesis::Top;
+			my $cgit    = Service::Git->new('.');
+			my $control = Genesis::Top::DEFAULT_CONTROL_BRANCH();
+			my $current = $cgit->current_branch // '';
+			$cgit->checkout($control) if $current && $current ne $control;
+
+			$self->notify("Propagating to downstream environments from #C{%s}...", $self->name);
+			my $bin = $ENV{GENESIS_CALLBACK_BIN} || 'genesis';
+			system($bin, 'propagate', $self->name);
+			warning(
+				"Propagation failed (rc=%d).  Deploy itself succeeded;\n".
+				"run #C{genesis propagate %s} manually to retry.",
+				($? >> 8), $self->name
+			) if $? != 0;
+		}
+	}
+
 	# Run post-deploy hook
 	$self->run_hook(
 		'post-deploy',
@@ -4456,14 +5041,61 @@ sub rotate_secrets {
 sub remove_secrets {
 	my ($self, %opts) = @_;
 
+	# Modes:
+	#   all => 'purge'  — pre-create: wipe vault paths without a
+	#                     secrets plan (env file may not exist yet)
+	#   all => 1        — interactive: wipe with plan-based labeling
+	#   (neither)       — targeted removal by filter
+	#
+	# Legacy: all => 1, no_populate => 1 is treated as all => 'purge'
+	if ($opts{all} && $opts{no_populate}) {
+		$opts{all} = 'purge';
+		delete $opts{no_populate};
+	}
+
 	my $store = $self->secrets_store(%opts);
 
-	# Determine secrets_store from kit - assume vault for now (credhub ignored)
 	if ($opts{all}) {
-		# TODO: extract this to a method in Genesis::Env::Secrets::Store
 		my @paths = $store->store_paths();
 		return ({empty => 1}) unless scalar(@paths);
 
+		# Purge mode: called from create() before the env file exists.
+		# We can't build a secrets_plan (the blueprint hook needs the
+		# env file), so skip plan-based labeling and just wipe the
+		# vault paths directly after prompting with raw paths.
+		if ($opts{all} eq 'purge') {
+			unless ($opts{'no-prompt'}) {
+				die_unless_controlling_terminal(
+					"\nCannot prompt for confirmation to remove all secrets outside a ".
+					"controlling terminal.  Use #C{-y|--no-prompt} option to provide ".
+					"confirmation to bypass this limitation."
+				);
+				warning(
+					"\nExisting secrets found under '#C{%s}' from a previous run.\n".
+					"The following %d path(s) will be removed:\n",
+					$self->secrets_base, scalar(@paths)
+				);
+				my $prefix = $store->base =~ s/^\///r;
+				for my $full_path (sort @paths) {
+					info(bullet("#C{%s}", $full_path =~ s/^$prefix//r));
+				}
+				my $response = prompt_for_line(undef, "Type 'yes' to remove these secrets; anything else will abort","");
+				if ($response ne 'yes') {
+					return ({abort => 1}, sprintf(
+						"Keeping all existing secrets under '#C{%s}'.",
+						$store->base
+					));
+				}
+			}
+			output {pending => 1}, "Deleting existing secrets under '#C{%s}'...", $store->base;
+			my ($out,$rc) = $store->service->query('rm', '-rf', $store->base);
+			if ($rc) {
+				my $msg = "Failed to remove secrets under '#C{%s}':\n%s";
+				return ({error => 1}, sprintf($msg, $store->base, $out));
+			}
+			return ({success => 1}, "#G{All applicable secrets removed.}");
+		}
+
 		my $plan = $self->secrets_plan(%opts, silent => 1);
 		unless ($opts{'no-prompt'}) {
 			die_unless_controlling_terminal(
@@ -4991,7 +5623,7 @@ sub _check_secrets {
 		}	if ($secrets_results->{error});
 
 		if ($secrets_results->{missing}) {
-			my $msg = "#{missing secrets detected}";
+			my $msg = "#R{missing secrets detected}";
 			if ($self->is_vaultified && grep {$_->{source} eq 'manifest'} ($self->secrets_plan->secrets)) {
 				$msg .= csprintf(
 					" (you may need to run '#g{%s add-secrets} #Y{--import}' to import them from credhub)",
@@ -5545,8 +6177,17 @@ sub _cap_yaml_file {
 	my $cap_file  = $self->workpath("fin.yml");
 
 	my $now = strftime(EXODUS_TIME_FORMAT, gmtime());
-	my $bosh_target = $self->use_create_env ? "~" : $self->bosh_env->{description};
-	my $bosh_exodus_path = $self->use_create_env ? "~" : $self->bosh->exodus_path;
+	my ($bosh_target, $bosh_exodus_path);
+	if ($self->use_create_env) {
+		$bosh_target = "~";
+		$bosh_exodus_path = "~";
+	} else {
+		$bosh_target = $self->bosh_env->{description};
+		# Prefer live director; fall back to bosh_env-derived path when
+		# the parent director hasn't been deployed yet.
+		my $bosh = eval { $self->bosh };
+		$bosh_exodus_path = $bosh ? $bosh->exodus_path : $self->bosh_env->{exodus_path};
+	}
 	mkfile_or_fail($cap_file, 0644, <<EOF);
 ---
 name: (( concat genesis.env "-$type" ))
@@ -5746,12 +6387,24 @@ sub _parse_bosh_env {
 	my ($name, $dep_type, $vault_url, $exodus_mount) =
 		($bosh_env_description) =~ m/^([^\/\@]+)(?:\/([^\@]+))?(?:@(?:(https?:\/\/[^\/]+)?(?:\/|$))?(.*))?$/;
 
+	# Synthesize the BOSH director's exodus path from parsed components.
+	# This allows callers to reference the path without needing a live
+	# director (e.g., during env creation before the parent is deployed).
+	my $mount = $exodus_mount;
+	unless ($mount) {
+		(my $sm = $self->secrets_mount) =~ s#/?$#/#;
+		$mount = "${sm}exodus/";
+	}
+	$mount =~ s#/?$#/#;
+	my $bosh_exodus_path = sprintf("%s%s/%s", $mount, $name, $dep_type || 'bosh');
+
 	return wantarray ? ($name, $dep_type, $vault_url, $exodus_mount) : {
-		name         => $name,
-		dep_type     => $dep_type,
-		vault_url    => $vault_url,
-		exodus_mount => $exodus_mount,
-		description  => $bosh_env_description,
+		name              => $name,
+		dep_type          => $dep_type,
+		vault_url         => $vault_url,
+		exodus_mount      => $exodus_mount,
+		exodus_path       => $bosh_exodus_path,
+		description       => $bosh_env_description,
 	};
 }
 
@@ -5867,13 +6520,17 @@ sub _get_stemcell_status {
 					$result->{alt_existing_cpis} = $available{$targets[0]}->{cpis};
 				}
 			} else {
-				# No stemcells available for the desired os
+				# No stemcells available for the desired os.  $newest is
+				# undef (no entry in %newest_by_os for this OS), so there
+				# are no existing-CPI stemcells to report.
 				$result->{alt} = Service::BOSH::Stemcell->find(
 					$self->iaas,
 					$os,
 					$version
 				);
-				$result->{alt_existing_cpis} = $available{$newest}{cpis};
+				$result->{alt_existing_cpis} = defined($newest)
+					? $available{$newest}{cpis}
+					: [];
 			}
 
 				# If using a non-default CPI, check if the latest version is available for it
diff --git a/lib/Genesis/Env/DeploymentManager.pm b/lib/Genesis/Env/DeploymentManager.pm
index a5e4a8b3..cbc8692e 100644
--- a/lib/Genesis/Env/DeploymentManager.pm
+++ b/lib/Genesis/Env/DeploymentManager.pm
@@ -327,6 +327,37 @@ sub _base_deployment_content {
 			bosh          => $ENV{BOSH_USERNAME} || $ENV{BOSH_USER} || $ENV{BOSH_CLIENT} || undef,
 		};
 
+		# Git context for pipeline propagation tracking (CI-only)
+		if ($env->top->ci_configured) {
+			eval {
+				require Service::Git;
+				my $git = Service::Git->new('.');
+				$base->{git} = {
+					branch => $git->current_branch,
+					commit => $git->sha('HEAD'),
+				};
+				# Prefer the control commit recorded by the last pipeline propagation
+				# on this branch ([pipeline] control@<sha> in the commit message).
+				my @log = $git->log_subjects($git->current_branch, limit => 20);
+				for my $line (@log) {
+					if ($line =~ /\[pipeline\] control\@([0-9a-f]+)/) {
+						$base->{git}{control_commit} = $git->sha($1);
+						last;
+					}
+				}
+				# Fallback: entrypoint envs (no prior_env) are never the target of
+				# `genesis propagate`, so they never get the [pipeline] control@sha
+				# marker — this is the normal path for them.  Also covers bootstrap
+				# and emergency manual deploys of downstream envs.
+				unless ($base->{git}{control_commit}) {
+					my $control_branch = $env->top->ci_control_branch;
+					my $sha = eval { $git->sha($control_branch) };
+					$base->{git}{control_commit} = $sha if $sha;
+				}
+			};
+			# Non-fatal — git context is supplementary
+		}
+
 		$base->{artifacts} = $self->_base_artifacts($action);
 
 		if ($action eq 'deploy') {
diff --git a/lib/Genesis/Env/Secrets/Store/Vault.pm b/lib/Genesis/Env/Secrets/Store/Vault.pm
index 8d34183b..7bd5857a 100644
--- a/lib/Genesis/Env/Secrets/Store/Vault.pm
+++ b/lib/Genesis/Env/Secrets/Store/Vault.pm
@@ -116,7 +116,8 @@ sub store_data {
 		if (defined $data) {
 			$self->{__data} = $data;
 		} else {
-			warning("Vault export returned no data for %s", $self->base);
+			warning("Vault export returned no data for %s", $self->base)
+				if $self->env->exists;
 		}
 	}
 	return $self->{__data} // {};
diff --git a/lib/Genesis/Kit/Provider.pm b/lib/Genesis/Kit/Provider.pm
index 2ba61ee3..b70f7a7f 100644
--- a/lib/Genesis/Kit/Provider.pm
+++ b/lib/Genesis/Kit/Provider.pm
@@ -65,6 +65,10 @@ sub default_provider {
 	return Genesis::Kit::Provider::GenesisCommunity->new();
 }
 
+# }}}
+# opts_slot - key name for this handler's parsed options in $COMMAND_OPTIONS {{{
+sub opts_slot { 'kit_provider' }
+
 # }}}
 # opts -  list of options supported by init method {{{
 sub opts {
diff --git a/lib/Genesis/Secret/SSH.pm b/lib/Genesis/Secret/SSH.pm
index eeaeb00a..d7c38bf5 100644
--- a/lib/Genesis/Secret/SSH.pm
+++ b/lib/Genesis/Secret/SSH.pm
@@ -85,25 +85,52 @@ sub _validate_value {
 	my ($self, %opts) = @_;
 	my $values = $self->value;
 	my %results;
-	my $fifo_file="genesis-ssh-1.fifo";
-
-	$fifo_file =~ s/-(\d+)\.fifo$/"-${\($1+1)}.fifo"/e while ( -e $fifo_file );
-	my ($rendered_public,$priv_rc) = run('mkfifo -m 600 "$2"; echo "$1">"$2"|ssh-keygen -y -f "$2"; rm "$2"', $values->{private}, $fifo_file);
-	$results{priv} = [
-		!$priv_rc,
-		"Valid private key"
-	];
-
-	$fifo_file =~ s/-(\d+)\.fifo$/"-${\($1+1)}.fifo"/e while ( -e $fifo_file );
-	my ($pub_sig,$pub_rc) = run('mkfifo -m 600 "$2"; echo "$1">"$2"|ssh-keygen -B -f "$2"; rm "$2"', $values->{public}, $fifo_file);
-	$results{pub} = [
-		!$pub_rc,
-		"Valid public key"
-	];
+
+	# ssh-keygen needs `-f <path>` and refuses to load private keys
+	# from regular files with broad permissions or from /dev/stdin
+	# (pipe perms 0660).  Use a NAMED PIPE in a private temp dir:
+	# - data flows through memory, not disk
+	# - mkfifo -m 600 yields 0600 perms on the fifo node
+	# - ssh-keygen's permission check is skipped for non-regular files
+	# - bash background-writer handles the open/open rendezvous so we
+	#   don't deadlock the way the older inline pipe construct did
+	require File::Temp;
+	my $tmpdir = File::Temp->newdir('genesis-ssh-XXXXXXXX', TMPDIR => 1);
+	chmod 0700, "$tmpdir";
+
+	my $counter = 0;
+	my $with_fifo = sub {
+		my ($content, @cmd) = @_;
+		my $fifo = "$tmpdir/key-" . (++$counter) . ".fifo";
+		# bash -c: mkfifo with 0600, background-write, run command
+		# reading from the fifo, then unlink.  The single-quoted
+		# heredoc-style content goes via env var to avoid argv length
+		# limits and to keep it out of the trace_args formatting.
+		local $ENV{__GENESIS_SSH_FIFO} = $fifo;
+		local $ENV{__GENESIS_SSH_KEY}  = $content;
+		return run(
+			'mkfifo -m 600 "$__GENESIS_SSH_FIFO" && '.
+			'{ printf %s\\\\n "$__GENESIS_SSH_KEY" > "$__GENESIS_SSH_FIFO" & } && '.
+			'"$@" -f "$__GENESIS_SSH_FIFO"; '.
+			'rc=$?; wait; rm -f "$__GENESIS_SSH_FIFO"; exit $rc',
+			@cmd
+		);
+	};
+
+	my ($rendered_public, $priv_rc) = $with_fifo->(
+		$values->{private}, 'ssh-keygen', '-y'
+	);
+	$results{priv} = [ !$priv_rc, "Valid private key" ];
+
+	my ($pub_sig, $pub_rc) = $with_fifo->(
+		$values->{public}, 'ssh-keygen', '-B'
+	);
+	$results{pub} = [ !$pub_rc, "Valid public key" ];
 
 	if (!$priv_rc) {
-		$fifo_file =~ s/-(\d+)\.fifo$/"-${\($1+1)}.fifo"/e while ( -e $fifo_file );
-		my ($rendered_sig,$rendered_rc) = run('mkfifo -m 600 "$2"; echo "$1">"$2"|ssh-keygen -B -f "$2"; rm "$2"', $rendered_public, $fifo_file);
+		my ($rendered_sig, $rendered_rc) = $with_fifo->(
+			$rendered_public, 'ssh-keygen', '-B'
+		);
 		$results{agree} = [
 			$rendered_sig eq $pub_sig,
 			"Public/Private key Agreement"
diff --git a/lib/Genesis/Top.pm b/lib/Genesis/Top.pm
index 14e2a2ca..43e7b0eb 100644
--- a/lib/Genesis/Top.pm
+++ b/lib/Genesis/Top.pm
@@ -19,6 +19,38 @@ use Genesis::Config;
 use Cwd ();
 use File::Path qw/rmtree/;
 
+# ---- Constants --------------------------------------------------------------
+#
+# Default name of the CI "control" branch -- the branch from which
+# environment branches are cut by 'genesis new' and against which
+# 'genesis deploy' validates its working state.  Captured as a constant
+# (and a config key) so it can change without rippling through the
+# codebase; not currently exposed to end users.
+use constant DEFAULT_CONTROL_BRANCH  => 'control';
+use constant CI_PIPELINE_CONTROL_KEY => 'control'; # key in pipeline.branches{} hash for the control branch
+use constant LATEST_CONFIG_VERSION   => 3;
+
+### Config Section Delegation Registry {{{
+# Modules may register themselves as handlers for specific top-level keys in
+# .genesis/config.  Top.pm owns the core schema; registered handlers own their
+# section's schema and validation.  This pattern is reusable for any future
+# section beyond ci:.
+#
+#   Genesis::Top->register_config_section('ci', 'Genesis::CI::Compiler');
+#
+# The handler class must implement:
+#   validate_config_section($data, $top)  # called after core schema validation
+
+my %_config_section_handlers;
+
+# register_config_section - register a module as owner of a config section {{{
+sub register_config_section {
+	my ($class, $section, $handler) = @_;
+	$_config_section_handlers{$section} = $handler;
+}
+
+# }}}
+# }}}
 ### Class Methods {{{
 
 # _build - common construction logic for bare Genesis::Top object {{{
@@ -117,7 +149,7 @@ sub create {
 	my $self = $class->_build($path, %opts);
 	$self->mkdir(".genesis");
 
-	$self->{__kit_provider} = Genesis::Kit::Provider->init(%opts);
+	$self->{__kit_provider} = $opts{kit_provider} || Genesis::Kit::Provider->init(%opts);
 	# Override vault if specified (will be saved to config later)
 	$self->{__vault} = Service::Vault::Remote->target($opts{vault}) if $opts{vault};
 	my $kits_path = '';
@@ -139,7 +171,7 @@ sub create {
 
 		# Write new configuration - Set defaults
 		$self->config->set('deployment_type',$name);
-		$self->config->set('version',2);
+		$self->config->set('version', LATEST_CONFIG_VERSION);
 		$self->config->set('creator_version', $Genesis::VERSION);
 		$self->config->set('minimum_version', $Genesis::VERSION) unless $Genesis::VERSION eq '(development)';
 		$self->config->set('manifest_store', 'exodus');
@@ -154,10 +186,12 @@ sub create {
 			}
 		}
 
-		# Only set vault configuration if not using no_vault (and only allow no_vault in tests)
-		if ($opts{no_vault}) {
+		# Set vault configuration if available
+		if ($opts{no_vault} || $opts{skip_vault}) {
+			# no_vault: test contexts only
+			# skip_vault: user explicitly deferred via --skip-vault (legacy mode)
 			bail("no_vault option can only be used in test contexts")
-				if $ENV{GENESIS_COMMAND};
+				if $opts{no_vault} && $ENV{GENESIS_COMMAND};
 		} else {
 			$self->config->set('secrets_provider', {
 				url       => $self->vault->url,
@@ -939,6 +973,33 @@ sub type {
 	return $self->config->get("deployment_type");
 }
 
+# }}}
+# ci_control_branch - return the configured CI control branch name {{{
+#
+# Returns the branch name that Genesis pipeline tooling treats as the
+# source of truth for this deployment repository.  Reads from
+# #C{ci.control_branch} in #C{.genesis/config}, defaulting to the
+# value of the #C{DEFAULT_CONTROL_BRANCH} constant.  Intentionally
+# not exposed as a user-facing option at this time.
+sub ci_control_branch {
+	my ($self) = @_;
+	return $self->config->get('ci.control_branch', DEFAULT_CONTROL_BRANCH);
+}
+
+# }}}
+# ci_enabled - return whether CI pipeline is enabled {{{
+sub ci_enabled {
+	my ($self) = @_;
+	return $self->config->get('ci.enabled');
+}
+
+# }}}
+# ci_configured - return whether CI is enabled AND has a provider configured {{{
+sub ci_configured {
+	my ($self) = @_;
+	return $self->config->get('ci.enabled') && $self->config->has('ci.provider.type');
+}
+
 # }}}
 # version - return the version of the cofiguration schema {{{
 sub version {
@@ -1141,6 +1202,8 @@ sub download_kit {
 # _validate_config - validate the configuration of the repo {{{
 sub _validate_config {
 	my ($self) = @_;
+	return 1 if $self->{__config_validated};
+	$self->{__config_validated} = 1;
 	my $config_version = $self->config->get(version => 1);
 	if ($config_version == 1 || $config_version =~ /^\d+\.\d+\.\d+(-[A-Za-z0-9_-]\.?\d+)?$/) {
 
@@ -1153,7 +1216,61 @@ sub _validate_config {
 		$self->_upgrade_config_to_v2($config_version, $upgrade_automatically);
 
 	} elsif ($config_version == 2){
+		$self->config->validate($self->_repo_config_schema_v2());
+		$self->{__config_disk_version} = 2;
+
+		# Check for legacy ci.yml — bail until post-MVP migration is implemented.
+		# Only flag it if it looks like a pipeline config (has 'pipeline:' key),
+		# not an environment file (which would have 'kit:' or 'genesis:').
+		my $ci_yml = $self->path('ci.yml');
+		if (-f $ci_yml && _is_legacy_ci_file($ci_yml)) {
+			bail(
+				"Legacy CI configuration detected at #C{%s}.\n".
+				"Pipeline support requires a v3 config.  Please run:\n\n".
+				"  genesis repo-init --upgrade\n\n".
+				"to migrate your CI configuration into the v3 config format.",
+				$ci_yml
+			);
+		}
+
+		# Augment in-memory with v3 defaults so downstream code sees
+		# a uniform v3 shape.  These go into the 'default' layer and
+		# will NOT be persisted to disk on save.
+		$self->config->_update_source('default', 'ci', {
+			enabled => Genesis::Config::FALSE,
+		});
+
+	} elsif ($config_version == 3){
 		$self->config->validate($self->_repo_config_schema());
+		$self->{__config_disk_version} = 3;
+
+		# Detect legacy ci.yml alongside v3 config
+		my $ci_yml = $self->path('ci.yml');
+		if (-f $ci_yml && _is_legacy_ci_file($ci_yml)) {
+			if ($self->config->get('ci.enabled') && $self->config->has('ci.provider.type')) {
+				bail(
+					"Legacy #C{%s} conflicts with the v3 CI configuration.\n".
+					"Remove it — CI is already configured in #C{.genesis/config}.",
+					$ci_yml
+				);
+			} else {
+				bail(
+					"Legacy CI configuration detected at #C{%s}.\n".
+					"Pipeline support requires migrating this into the v3 config.  Please run:\n\n".
+					"  genesis repo-init --upgrade\n\n".
+					"to migrate your CI configuration into the v3 config format.",
+					$ci_yml
+				);
+			}
+		}
+
+		# Delegate validation of registered sections to their owning modules
+		for my $section (sort keys %_config_section_handlers) {
+			next unless $self->config->has($section);
+			my $handler = $_config_section_handlers{$section};
+			$handler->validate_config_section($self->config->get($section), $self)
+				if $handler->can('validate_config_section');
+		}
 	} else {
 		bail "Genesis deployment repo configuration version $config_version is not supported";
 	}
@@ -1226,8 +1343,8 @@ sub _upgrade_config_to_v2 {
 }
 
 # }}}
-# _repo_config_schema - return the repository configuration validation schema {{{
-sub _repo_config_schema {
+# _repo_config_schema_v2 - v2 configuration validation schema {{{
+sub _repo_config_schema_v2 {
 	my ($self) = @_;
 	return {
 		deployment_type => {
@@ -1310,6 +1427,60 @@ sub _repo_config_schema {
 	};
 }
 
+# }}}
+# _repo_config_schema - v3 configuration validation schema (superset of v2) {{{
+sub _repo_config_schema {
+	my ($self) = @_;
+	return {
+		%{$self->_repo_config_schema_v2()},
+		version => {
+			type           => '"3"',
+			required       => 1,
+			description    => 'Configuration schema version'
+		},
+		ci => {
+			type           => 'hash',
+			description    => 'CI pipeline configuration',
+			schema => {
+				enabled => {type => 'boolean', default => Genesis::Config::FALSE, description => 'Whether CI pipeline is active'},
+				provider => {
+					type        => 'hash',
+					required    => 'enabled',
+					description => 'CI provider connection details',
+					schema => {
+						type     => {type => 'enum', values => ['concourse', 'gha', 'manual'], description => 'CI system type'},
+						target   => {type => 'string', description => 'Provider target name (e.g., fly target)'},
+						url      => {type => 'string', description => 'Provider API URL'},
+						team     => {type => 'string', description => 'Provider team/org'},
+						insecure => {type => 'boolean', default => Genesis::Config::FALSE, description => 'Skip TLS verification'},
+					}
+				},
+				name => {type => 'string', description => 'Pipeline name (defaults to deployment_type)'},
+				repo => {
+					type        => 'hash',
+					description => 'Repository layout settings',
+					schema => {
+						root => {type => 'string', default => '.', description => 'Path to deployment root within the git repo'},
+					}
+				},
+			}
+		},
+	};
+}
+
+# }}}
+# _is_legacy_ci_file - detect whether ci.yml is a pipeline config (not an env file) {{{
+sub _is_legacy_ci_file {
+	my ($path) = @_;
+	open my $fh, '<', $path or return 0;
+	while (<$fh>) {
+		return 1 if /^pipeline:/;
+		return 0 if /^kit:/ || /^genesis:/;
+	}
+	close $fh;
+	return 0;
+}
+
 # }}}
 
 1;
diff --git a/lib/Genesis/UI.pm b/lib/Genesis/UI.pm
index e99024cf..7489a046 100644
--- a/lib/Genesis/UI.pm
+++ b/lib/Genesis/UI.pm
@@ -1,4 +1,7 @@
 package Genesis::UI;
+use v5.20;
+use warnings;
+use strict;
 
 use base 'Exporter';
 our @EXPORT = qw/
@@ -130,7 +133,8 @@ sub __prompt_for_block {
 	$prompt = "$prompt (Enter <CTRL-D> to end)";
 	(my $line = $prompt) =~ s/./-/g;
 	print csprintf("%s","\n$prompt\n$line\n");
-	open(my $in, '<&', fileno(STDIN)) or $in = \*STDIN;
+	my $in;
+	open($in, '<&', fileno(STDIN)) or $in = \*STDIN;
 	my @data = <$in>;
 	return join("", @data);
 }
@@ -427,7 +431,7 @@ sub new_prompt_for_choice {
 			}
 			my $label = $choice->{label} // $choice->{value};
 			$max_label_len = max($max_label_len, length($label)+ $max_number_width + 2); # 2 for column separator 
-			push @{$sections{$section_headers[-1] //= []}}, $choice;
+			push @{$sections->{$section_headers[-1] //= []}}, $choice;
 		}
 		$columns = int($max_width / $max_label_len);
 		$col_width = int($max_width / $columns);
@@ -454,8 +458,13 @@ sub new_prompt_for_choice {
 
 	# Display header
 	my $form = $options{header}."\n";
+	my %selection_map;
+	my $default_choice;
 	# Handle user input
 	my $display_choices = sub {
+		my $section_offset = 0;
+		%selection_map = ();
+		$default_choice = undef;
 
 		for my $section_header (@section_headers) {
 			if ($section_header) {
@@ -467,7 +476,7 @@ sub new_prompt_for_choice {
 					$form .= csprintf("\n  #Wku{%s}\n", $section_header);
 				}
 			}
-			my $section_choices = $sections{$section_header};
+			my $section_choices = $sections->{$section_header};
 		};
 		
 		# Calculate item ranges for pagination
@@ -487,7 +496,7 @@ sub new_prompt_for_choice {
 			}
 			
 			# Calculate number of columns that fit
-			my $cols = max(1, int($terminal_width / ($max_label_len + 2)));
+			my $cols = max(1, int(terminal_width() / ($max_label_len + 2)));
 			
 			# Display items in columns
 			my $col = 0;
@@ -556,7 +565,7 @@ sub new_prompt_for_choice {
 				my $choice = $i+1-$section_offset;
 				$selection_map{$choice} = $choices->[$i];
 				$form .= csprintf("\n  %*s) %s", $iw, $choice, $choices->[$i]{label});
-				$default_choice = $choice if $i == $default_idx;
+				$default_choice = $choice if defined($default_idx) && $i == $default_idx;
 			}
 		}
 		
diff --git a/lib/Service/BOSH/Director.pm b/lib/Service/BOSH/Director.pm
index cb55352d..b205d334 100644
--- a/lib/Service/BOSH/Director.pm
+++ b/lib/Service/BOSH/Director.pm
@@ -143,6 +143,7 @@ sub from_exodus {
 # }}}
 # from_alias - create a BOSH director object that uses a local config alias {{{
 sub from_alias {
+	debug("from_alias called with %d args: [%s]", scalar(@_)-1, join(', ', map {defined($_) ? "'$_'" : 'undef'} @_[1..$#_]));
 	my ($class, $alias, $env, %opts) = @_;
 
 	my $config_home = $opts{config_home} || "$ENV{HOME}/.bosh/config";
@@ -177,6 +178,9 @@ sub from_environment {
 	#
 	# 2. We need to indicate if we want the self or parent BOSH director
 
+	debug("from_environment: BOSH_ALIAS=%s BOSH_ENVIRONMENT=%s BOSH_CLIENT=%s BOSH_DEPLOYMENT=%s",
+		$ENV{BOSH_ALIAS}//'(undef)', $ENV{BOSH_ENVIRONMENT}//'(undef)',
+		$ENV{BOSH_CLIENT}//'(undef)', $ENV{BOSH_DEPLOYMENT}//'(undef)');
 	if (is_valid_uri($ENV{BOSH_ENVIRONMENT}) && $ENV{BOSH_CLIENT}) {
 		return $class->new(
 			$ENV{BOSH_ALIAS},
@@ -188,7 +192,8 @@ sub from_environment {
 			deployment => $ENV{BOSH_DEPLOYMENT}
 		);
 	} else {
-		return $class->from_alias($ENV{BOSH_ALIAS} || $ENV{BOSH_ENVIRONMENT}, deployment => $ENV{BOSH_DEPLOYMENT});
+		return $class->from_alias($ENV{BOSH_ALIAS} || $ENV{BOSH_ENVIRONMENT}, undef,
+			$ENV{BOSH_DEPLOYMENT} ? (deployment => $ENV{BOSH_DEPLOYMENT}) : ());
 	}
 }
 
@@ -539,7 +544,11 @@ sub stemcells {
 	)->{Tables}[0]{Rows};
 	for my $stemcell (@$stemcell_rows) {
 		my $id = sprintf('%s@%s', $stemcell->{os}, $stemcell->{version}) =~ s/\*$//r;
-		my $cpi = $stemcell->{cpi} // '<default>';
+		# BOSH reports default-cpi stemcells with cpi == '' (defined but
+		# empty); normalize both undef and empty to '<default>' so the
+		# downstream `in_array('<default>', cpis)` lookup succeeds.
+		my $cpi = $stemcell->{cpi};
+		$cpi = '<default>' unless defined($cpi) && length($cpi);
 		$stemcells{$id} //= {
 			id => $id,
 			name => $stemcell->{name},
@@ -548,7 +557,7 @@ sub stemcells {
 			os => $stemcell->{os},
 			cpis => []
 		};
-		push @{$stemcells{$id}{cpis}}, $cpi if $cpi;
+		push @{$stemcells{$id}{cpis}}, $cpi;
 	}
 
 	return wantarray ? %stemcells : \%stemcells;
diff --git a/lib/Service/Credhub.pm b/lib/Service/Credhub.pm
index a26618fc..e90784d8 100644
--- a/lib/Service/Credhub.pm
+++ b/lib/Service/Credhub.pm
@@ -251,8 +251,18 @@ sub set {
 		$rc
 	) if $rc;
 	my $result = read_json_from($out, $rc, $err);
-	$self->{cached}{$path} = $result->{value} // $value
-		if defined($self->{cached});
+	# Cache the value credhub returned — except when it's redacted.
+	# Older credhub CLIs returned the actual value in the set
+	# response; newer ones return "<redacted>".  When we see the
+	# redacted sentinel, drop the cache entry so the next get()
+	# pulls the live value from credhub for verification.
+	if (defined($self->{cached})) {
+		if (defined($result->{value}) && $result->{value} ne '<redacted>') {
+			$self->{cached}{$path} = $result->{value};
+		} else {
+			delete $self->{cached}{$path};
+		}
+	}
 	return ($result->{id});
 }
 
diff --git a/lib/Service/Git.pm b/lib/Service/Git.pm
new file mode 100644
index 00000000..e5a5b29e
--- /dev/null
+++ b/lib/Service/Git.pm
@@ -0,0 +1,614 @@
+package Service::Git;
+
+use strict;
+use warnings;
+
+use Genesis qw/run bail debug trace/;
+use File::Basename qw/dirname/;
+
+### Class State {{{
+my %_instances;  # keyed by resolved git root path
+# }}}
+
+### Constructor & Lifecycle {{{
+
+# new - get or create a Git service instance for a repository {{{
+#
+# Flyweight: returns the existing instance if one already exists for
+# the same .git-controlled repo.  This prevents competing objects
+# from stepping on each other's branch tracking or caches.
+#
+#   my $git = Service::Git->new($path);   # or ->new() for cwd
+#   my $git = Service::Git->new($path, track_branch => 1);
+#
+# With track_branch => 1, the current branch is saved and restored
+# when the object goes out of scope (DESTROY).  If the instance
+# already exists and track_branch is requested, it upgrades the
+# existing instance.
+sub new {
+	my ($class, $path, %opts) = @_;
+	$path ||= '.';
+
+	my ($root) = run({}, 'git', '-C', $path, 'rev-parse', '--show-toplevel');
+	chomp $root if defined $root;
+	bail("Not a git repository: %s", $path) unless $root;
+
+	# Return existing instance for this repo
+	if (my $existing = $_instances{$root}) {
+		# Upgrade to track_branch if requested and not already tracking
+		if ($opts{track_branch} && !$existing->{_track_branch}) {
+			$existing->{_track_branch} = 1;
+			$existing->{_original_branch} //= $existing->current_branch;
+		}
+		return $existing;
+	}
+
+	my ($prefix) = run({}, 'git', '-C', $path, 'rev-parse', '--show-prefix');
+	chomp $prefix if defined $prefix;
+	$prefix //= '';
+
+	my $self = bless {
+		root           => $root,
+		prefix         => $prefix,
+		_branch_cache  => {},
+		_track_branch  => $opts{track_branch} || 0,
+		_original_branch => undef,
+	}, $class;
+
+	if ($self->{_track_branch}) {
+		$self->{_original_branch} = $self->current_branch;
+	}
+
+	$_instances{$root} = $self;
+	return $self;
+}
+
+# }}}
+# create - initialize a new git repository and return an instance {{{
+#
+#   my $git = Service::Git->create($path);
+#   my $git = Service::Git->create($path, initial_branch => 'control');
+#
+# Runs git init at the given path, optionally setting the initial
+# branch name.  Returns a Service::Git instance for the new repo.
+sub create {
+	my ($class, $path, %opts) = @_;
+	$path ||= '.';
+
+	my @init = ('git', 'init');
+	if ($opts{initial_branch}) {
+		# git symbolic-ref works on all versions (git init -b requires >= 2.28)
+		run({ onfailure => "Failed to initialize git in $path" },
+			"cd \Q$path\E && git init && git symbolic-ref HEAD refs/heads/$opts{initial_branch}");
+	} else {
+		run({ onfailure => "Failed to initialize git in $path" },
+			'git', '-C', $path, 'init');
+	}
+
+	return $class->new($path, %opts);
+}
+
+# }}}
+# DESTROY - restore original branch on process exit {{{
+#
+# With flyweight caching, the instance lives for the process lifetime.
+# DESTROY fires during global cleanup, restoring the branch if needed.
+sub DESTROY {
+	my ($self) = @_;
+	return unless $self->{_track_branch} && $self->{_original_branch};
+	my $current = eval { $self->current_branch };
+	return unless $current && $current ne $self->{_original_branch};
+	# Reset any partial changes before switching
+	run({ dir => $self->{root}, passfail => 1 },
+		'git', 'checkout', '--', '.');
+	run({ dir => $self->{root}, passfail => 1 },
+		'git', 'checkout', $self->{_original_branch});
+	trace("Service::Git: restored branch %s", $self->{_original_branch});
+	delete $_instances{$self->{root}};
+}
+
+# }}}
+# }}}
+
+### Accessors {{{
+
+# root - git toplevel directory (cached) {{{
+sub root { $_[0]->{root} }
+
+# }}}
+# prefix - subdir offset within git repo (cached, e.g., "bosh/") {{{
+sub prefix { $_[0]->{prefix} }
+
+# }}}
+# }}}
+
+### Branch Operations {{{
+
+# current_branch - name of HEAD branch (cached, invalidated on checkout) {{{
+sub current_branch {
+	my ($self) = @_;
+	my ($branch) = run({ dir => $self->{root} },
+		'git', 'rev-parse', '--abbrev-ref', 'HEAD');
+	chomp $branch if defined $branch;
+	$self->{_current_branch} = $branch;
+	return $branch;
+}
+
+# }}}
+# checkout - switch to a branch {{{
+#
+# Saves the original branch for restore_branch / DESTROY.
+sub checkout {
+	my ($self, $branch) = @_;
+	$self->{_original_branch} //= $self->current_branch
+		if $self->{_track_branch};
+	run({ dir => $self->{root}, onfailure => "Failed to checkout '$branch'" },
+		'git', 'checkout', $branch);
+	delete $self->{_current_branch};
+	return $self;
+}
+
+# }}}
+# restore_branch - return to the branch we were on before any checkout {{{
+sub restore_branch {
+	my ($self) = @_;
+	return unless $self->{_original_branch};
+	my $current = $self->current_branch;
+	if ($current ne $self->{_original_branch}) {
+		run({ dir => $self->{root}, passfail => 1 },
+			'git', 'checkout', $self->{_original_branch});
+		delete $self->{_current_branch};
+	}
+	return $self;
+}
+
+# }}}
+# create_branch - create a new branch at the given ref (default HEAD) {{{
+sub create_branch {
+	my ($self, $name, $ref) = @_;
+	my @cmd = ('git', 'branch', $name);
+	push @cmd, $ref if $ref;
+	run({ dir => $self->{root}, onfailure => "Failed to create branch '$name'" },
+		@cmd);
+	$self->{_branch_cache}{$name} = 1;
+	return $self;
+}
+
+# }}}
+# branch_exists - check if a branch exists (cached) {{{
+sub branch_exists {
+	my ($self, $name) = @_;
+	return $self->{_branch_cache}{$name}
+		if exists $self->{_branch_cache}{$name};
+	my $exists = run({ dir => $self->{root}, passfail => 1 },
+		'git', 'rev-parse', '--verify', $name);
+	$self->{_branch_cache}{$name} = $exists ? 1 : 0;
+	return $self->{_branch_cache}{$name};
+}
+
+# }}}
+# }}}
+
+### Queries {{{
+
+# sha - return the commit SHA for a ref {{{
+#
+#   $git->sha('HEAD')                  # full SHA
+#   $git->sha('HEAD', short => 1)      # abbreviated
+#   $git->sha($branch)                 # resolve branch to SHA
+#   $git->sha($short_sha)             # expand short to full
+sub sha {
+	my ($self, $ref, %opts) = @_;
+	return $self->rev_parse($ref // 'HEAD', %opts);
+}
+
+# }}}
+# rev_parse - resolve a ref via git rev-parse (low-level) {{{
+#
+# Options:
+#   short => 1   — return abbreviated SHA
+sub rev_parse {
+	my ($self, $ref, %opts) = @_;
+	my @cmd = ('git', 'rev-parse');
+	push @cmd, '--short' if $opts{short};
+	push @cmd, $ref;
+	my ($sha) = run({ dir => $self->{root} }, @cmd);
+	chomp $sha if defined $sha;
+	return $sha;
+}
+
+# }}}
+# merge_base - find the common ancestor of two refs {{{
+sub merge_base {
+	my ($self, $a, $b) = @_;
+	my ($sha) = run({ dir => $self->{root} }, 'git', 'merge-base', $a, $b);
+	chomp $sha if defined $sha;
+	return $sha;
+}
+
+# }}}
+# is_ancestor - true if $maybe_ancestor is an ancestor of (or equal to) $descendant {{{
+#
+#   $git->is_ancestor($a, $b)  # true if A == B, or A is reachable from B
+sub is_ancestor {
+	my ($self, $maybe_ancestor, $descendant) = @_;
+	return 0 unless defined $maybe_ancestor && defined $descendant;
+	my $ok = run(
+		{ dir => $self->{root}, passfail => 1 },
+		'git', 'merge-base', '--is-ancestor', $maybe_ancestor, $descendant
+	);
+	return $ok ? 1 : 0;
+}
+
+# }}}
+# is_clean - true if working tree has no modified/staged/conflicted files {{{
+#
+# Ignores untracked files — they don't affect branch switching.
+sub is_clean {
+	my ($self) = @_;
+	my ($status) = run({ dir => $self->{root} }, 'git', 'status', '--porcelain');
+	my @dirty = grep { /^[^?]/ } split /\n/, ($status || '');
+	return !@dirty;
+}
+
+# }}}
+# status - working-tree state as a {path => XY-code} hashref {{{
+#
+# Wraps `git status --porcelain` and parses each line into the
+# two-character status code and the path.  Optional pathspec args
+# limit the report to those paths (relative to git root).  Includes
+# untracked files (`??`) -- callers can filter if they only want
+# tracked-file changes.
+sub status {
+	my ($self, @pathspecs) = @_;
+	my @cmd = ('git', 'status', '--porcelain');
+	push @cmd, '--', @pathspecs if @pathspecs;
+	my ($out) = run({ dir => $self->{root} }, @cmd);
+	my %unclean;
+	for my $line (split /\n/, ($out // '')) {
+		next unless length $line;
+		# Format: "XY path" — two-char status, single space, path.
+		my $code = substr($line, 0, 2);
+		my $path = substr($line, 3);
+		$unclean{$path} = $code if length $path;
+	}
+	return \%unclean;
+}
+
+# }}}
+# pull_ff_only - fast-forward a branch from a remote, bail on divergence {{{
+#
+# Defaults to `default_remote` when no remote is given.  No-op when
+# no remote is configured.  Bails (via run's onfailure) when the
+# pull would require a non-fast-forward.
+sub pull_ff_only {
+	my ($self, $branch, $remote) = @_;
+	$remote //= $self->default_remote;
+	return $self unless $remote;
+	run({ dir => $self->{root},
+		  onfailure => "Failed to fast-forward $branch from $remote -- ".
+		               "resolve the divergence and retry" },
+		'git', 'pull', '--ff-only', $remote, $branch);
+	delete $self->{_branch_cache}{$branch};
+	return $self;
+}
+
+# }}}
+# pull_rebase - rebase the current branch on top of remote/<branch> {{{
+#
+# Used to integrate concurrent updates before a push.  Defaults to
+# `default_remote` when no remote is given.  No-op when no remote
+# is configured.  Bails (via run's onfailure) when rebase fails.
+sub pull_rebase {
+	my ($self, $branch, $remote) = @_;
+	$remote //= $self->default_remote;
+	return $self unless $remote;
+	run({ dir => $self->{root},
+		  onfailure => "Failed to rebase $branch on $remote/$branch -- ".
+		               "resolve the divergence and push manually" },
+		'git', 'pull', '--rebase', $remote, $branch);
+	return $self;
+}
+
+# }}}
+# diff_files - structured diff between two refs, filtered by pathspecs {{{
+#
+# Returns a hashref:
+#   {
+#     changed => \@files,     # added, modified, or type-changed
+#     deleted => \@files,
+#     renamed => \%old_to_new,
+#     all     => \@all_files, # union of changed + deleted
+#   }
+#
+# Pathspecs are relative to git root (caller should prefix if needed).
+sub diff_files {
+	my ($self, $from, $to, @pathspecs) = @_;
+	my @cmd = ('git', 'diff', '--name-status', $from, $to);
+	push @cmd, '--', @pathspecs if @pathspecs;
+	my ($out) = run({ dir => $self->{root} }, @cmd);
+
+	my (@changed, @deleted, %renamed);
+	for my $line (grep { /\S/ } split /\n/, ($out || '')) {
+		if ($line =~ /^D\t(.+)$/) {
+			push @deleted, $1;
+		} elsif ($line =~ /^R\d*\t(.+)\t(.+)$/) {
+			$renamed{$1} = $2;
+			push @deleted, $1;
+			push @changed, $2;
+		} elsif ($line =~ /^[AMT]\t(.+)$/) {
+			push @changed, $1;
+		}
+	}
+	return {
+		changed => \@changed,
+		deleted => \@deleted,
+		renamed => \%renamed,
+		all     => [@changed, @deleted],
+	};
+}
+
+# }}}
+# diff_names - simple list of changed file names between two refs {{{
+sub diff_names {
+	my ($self, $from, $to, @pathspecs) = @_;
+	my @cmd = ('git', 'diff', '--name-only', $from, $to);
+	push @cmd, '--', @pathspecs if @pathspecs;
+	my ($out) = run({ dir => $self->{root} }, @cmd);
+	return grep { /\S/ } split /\n/, ($out || '');
+}
+
+# }}}
+# ls_tree - list files on a ref under a prefix {{{
+sub ls_tree {
+	my ($self, $ref, $path) = @_;
+	$path //= '';
+	my ($out) = run({ dir => $self->{root} },
+		'git', 'ls-tree', '-r', '--name-only', $ref, $path);
+	return grep { /\S/ } split /\n/, ($out || '');
+}
+
+# }}}
+# log_subjects - return commit subjects for a branch {{{
+#
+# Options:
+#   limit  => N       — max number of entries
+#   format => '...'   — custom format (default: %H %s)
+sub log_subjects {
+	my ($self, $branch, %opts) = @_;
+	my $fmt = $opts{format} || '%H %s';
+	my @cmd = ('git', 'log', "--format=$fmt", $branch);
+	push @cmd, "-$opts{limit}" if $opts{limit};
+	# Optional pathspec filter: only commits that touched any of these
+	# git-root-relative paths.  Used to scope the env-branch history to
+	# what's relevant to a particular deployment (e.g., bosh vs vault in
+	# a multi-deploy repo).
+	if ($opts{paths} && @{$opts{paths}}) {
+		push @cmd, '--', @{$opts{paths}};
+	}
+	my ($out) = run({ dir => $self->{root} }, @cmd);
+	return split /\n/, ($out || '');
+}
+
+# }}}
+# show_file - read file content from a specific ref {{{
+sub show_file {
+	my ($self, $ref, $path) = @_;
+	my ($content, $rc) = run({ dir => $self->{root}, passfail => 0 },
+		'git', 'show', "$ref:$path");
+	return $content;
+}
+
+# }}}
+# }}}
+
+### Working Tree Operations {{{
+
+# checkout_file - extract a file from a ref into the working tree {{{
+sub checkout_file {
+	my ($self, $ref, $file) = @_;
+	# Ensure parent directory exists
+	my $full_path = "$self->{root}/$file";
+	my $dir = dirname($full_path);
+	if (!-d $dir) {
+		require File::Path;
+		File::Path::make_path($dir);
+	}
+	run({ dir => $self->{root}, onfailure => "Failed to checkout $file from $ref" },
+		'git', 'checkout', $ref, '--', $file);
+	return $self;
+}
+
+# }}}
+# add - stage files {{{
+sub add {
+	my ($self, @files) = @_;
+	return unless @files;
+	run({ dir => $self->{root} }, 'git', 'add', @files);
+	return $self;
+}
+
+# }}}
+# rm - remove files from index and working tree {{{
+sub rm {
+	my ($self, @files) = @_;
+	return unless @files;
+	run({ dir => $self->{root}, passfail => 1 },
+		'git', 'rm', '-f', '-q', '--', @files);
+	return $self;
+}
+
+# }}}
+# commit - stage files and commit {{{
+#
+#   $git->commit("message");              # commit staged changes
+#   $git->commit("message", @files);      # add files then commit
+sub commit {
+	my ($self, $message, @files) = @_;
+	$self->add(@files) if @files;
+	run({ dir => $self->{root}, onfailure => "Failed to commit" },
+		'git', 'commit', '-m', $message);
+	return $self;
+}
+
+# }}}
+# reset_working_tree - discard all working tree changes to tracked files {{{
+sub reset_working_tree {
+	my ($self) = @_;
+	run({ dir => $self->{root}, passfail => 1 },
+		'git', 'checkout', '--', '.');
+	return $self;
+}
+
+# }}}
+# }}}
+
+### Remote Operations {{{
+
+# default_remote - first configured remote name (cached) {{{
+sub default_remote {
+	my ($self) = @_;
+	return $self->{_default_remote} if exists $self->{_default_remote};
+	my ($out) = run({ dir => $self->{root} }, 'git', 'remote');
+	if ($out && $out =~ /\S/) {
+		chomp $out;
+		$self->{_default_remote} = (split /\n/, $out)[0];
+	} else {
+		$self->{_default_remote} = undef;
+	}
+	return $self->{_default_remote};
+}
+
+# }}}
+# remote_url - fetch the fetch URL for a named (or default) remote {{{
+sub remote_url {
+	my ($self, $remote) = @_;
+	$remote //= $self->default_remote;
+	return undef unless $remote;
+	my ($url) = run({ dir => $self->{root} }, 'git', 'remote', 'get-url', $remote);
+	chomp $url if defined $url;
+	return $url;
+}
+
+# }}}
+# fetch_branch - fetch a specific branch from remote into a local ref {{{
+#
+# Uses the forced refspec (+refs/heads/branch:refs/heads/branch) so the
+# local ref is created or updated regardless of fast-forward status.
+# Safe for propagation branches that are written-once and never rebased.
+sub fetch_branch {
+	my ($self, $branch, $remote) = @_;
+	$remote //= $self->default_remote;
+	return $self unless $remote;
+	run({ dir => $self->{root}, onfailure => "Failed to fetch '$branch' from '$remote'" },
+		'git', 'fetch', $remote,
+		"+refs/heads/$branch:refs/heads/$branch");
+	$self->{_branch_cache}{$branch} = 1;
+	return $self;
+}
+
+# }}}
+# fetch_branches - fetch multiple branches from remote in one call {{{
+#
+#   $git->fetch_branches(\@names)           # use default remote
+#   $git->fetch_branches(\@names, $remote)  # explicit remote
+#
+# Builds all refspecs and issues a single git fetch so credentials are
+# only prompted once regardless of how many branches are listed.
+# Force-updates local refs to match remote; safe for pipeline env
+# branches because local divergence there is a bug, not a workflow.
+# Silently skips the currently checked-out branch (git refuses to
+# update an active branch via refspec).  Returns $self.
+sub fetch_branches {
+	my ($self, $names, $remote) = @_;
+	$remote //= $self->default_remote;
+	return $self unless $remote && $names && @$names;
+	my $current  = $self->current_branch // '';
+	my @refspecs = map { "+refs/heads/$_:refs/heads/$_" }
+	               grep { $_ ne $current } @$names;
+	return $self unless @refspecs;
+	run({ dir => $self->{root}, passfail => 1 },
+		'git', 'fetch', $remote, @refspecs);
+	$self->{_branch_cache}{$_} = 1 for grep { $_ ne $current } @$names;
+	return $self;
+}
+
+# }}}
+# push - push branches to a remote {{{
+#
+#   $git->push(@branches);              # push to default remote
+#   $git->push($remote, @branches);     # push to specific remote
+#
+# Returns a hashref of branch => success (1/0).
+sub push {
+	my ($self, @args) = @_;
+	# If first arg looks like a remote name (not a branch we know), use it
+	my $remote;
+	if (@args && !$self->branch_exists($args[0])) {
+		$remote = shift @args;
+	}
+	$remote ||= $self->default_remote;
+	return {} unless $remote;
+
+	my %results;
+	for my $branch (@args) {
+		my $ok = run({ dir => $self->{root}, passfail => 1 },
+			'git', 'push', $remote, $branch);
+		$results{$branch} = $ok ? 1 : 0;
+	}
+	return \%results;
+}
+
+# }}}
+# }}}
+
+### Utility {{{
+
+# prefixed - prepend the git prefix to repo-relative paths {{{
+#
+# Converts paths relative to the deployment repo root into paths
+# relative to the git root.  No-op when prefix is empty.
+#
+#   my @git_paths = $git->prefixed(@repo_paths);
+sub prefixed {
+	my ($self, @paths) = @_;
+	my $p = $self->{prefix};
+	return @paths unless $p;
+	return map { "${p}$_" } @paths;
+}
+
+# }}}
+# unprefixed - strip the git prefix from git-root-relative paths {{{
+#
+# Inverse of `prefixed`.  Converts git-root-relative paths into
+# Top-root-relative paths for user-facing display.  Paths that don't
+# start with the prefix are left untouched (so sibling-dir paths
+# outside the deployment Top root remain identifiable).
+#
+#   my @user_paths = $git->unprefixed(@git_paths);
+sub unprefixed {
+	my ($self, @paths) = @_;
+	my $p = $self->{prefix};
+	return @paths unless $p;
+	return map { my $q = $_; $q =~ s{^\Q$p\E}{}; $q } @paths;
+}
+
+# }}}
+# in_repo - true if we're inside a subdirectory of the git root {{{
+sub in_repo {
+	return defined $_[0]->{root};
+}
+
+# }}}
+# is_inside_work_tree - check if a path is inside a git work tree {{{
+sub is_inside_work_tree {
+	my ($class, $path) = @_;
+	$path ||= '.';
+	return run({ passfail => 1 },
+		'git', '-C', $path, 'rev-parse', '--is-inside-work-tree');
+}
+
+# }}}
+# }}}
+
+1;
diff --git a/lib/Service/Github.pm b/lib/Service/Github.pm
index 7aa064aa..c7939a1e 100644
--- a/lib/Service/Github.pm
+++ b/lib/Service/Github.pm
@@ -6,6 +6,7 @@ use Genesis;
 use Genesis::UI;
 use Genesis::Term qw/csprintf/;
 
+use JSON::PP;
 use Time::HiRes qw/gettimeofday/;
 use Digest::SHA qw/sha1_hex/;
 
@@ -482,6 +483,133 @@ sub validate_ssh_key {
 	return $key =~ /^(ssh-rsa|ssh-dss|ssh-ed25519|ecdsa-sha2-nistp256|ecdsa-sha2-nistp384|ecdsa-sha2-nistp521)\s+[A-Za-z0-9+\/]+[=]{0,3}(\s+.+)?$/;
 }
 
+# }}}
+# pulls_url - URL for the GitHub pull requests API {{{
+#
+#   $gh->pulls_url('org/repo')         # list endpoint
+#   $gh->pulls_url('org/repo', 42)     # single-PR endpoint
+sub pulls_url {
+	my ($self, $owner_repo, $number) = @_;
+	my $url = sprintf("%s/repos/%s/pulls", $self->base_url, $owner_repo);
+	$url .= "/$number" if defined $number;
+	return $url;
+}
+
+# }}}
+# list_prs - list pull requests for a repository {{{
+#
+# Options:
+#   state  - 'open' (default), 'closed', or 'all'
+#   head   - filter by head branch (bare branch name; owner: prefix added automatically)
+#   base   - filter by base (target) branch
+#
+# Returns an arrayref of PR objects from the GitHub API.
+sub list_prs {
+	my ($self, $owner_repo, %opts) = @_;
+	bail("Missing owner/repo for list_prs") unless $owner_repo;
+
+	my $state = $opts{state} || 'open';
+	my $url   = $self->pulls_url($owner_repo) . "?state=$state&per_page=100";
+	$url .= "&base=" . $opts{base} if $opts{base};
+	# GitHub requires owner:branch format for cross-fork head filter
+	if ($opts{head}) {
+		my ($owner) = split m{/}, $owner_repo;
+		$url .= "&head=$owner:$opts{head}";
+	}
+
+	my @all_prs;
+	while ($url) {
+		my ($code, $msg, $data, $headers) = curl("GET", $url, undef, undef, 0, $self->{creds});
+		bail(
+			"Failed to list pull requests for #C{%s}: HTTP %s - %s",
+			$owner_repo, $code, $msg
+		) unless $code == 200;
+
+		my $page;
+		eval { $page = load_json($data); 1 }
+			or bail("Failed to parse pull request list from GitHub: %s", $@);
+		push @all_prs, @$page if ref($page) eq 'ARRAY';
+
+		# Follow Link: <url>; rel="next" pagination header
+		$url = undef;
+		if ($headers) {
+			my ($link_hdr) = grep { s/^Link:\s*//i } split /[\r\n]+/, $headers;
+			if ($link_hdr) {
+				($url) = grep { s/^<(.*)>; rel="next"$/$1/ } split /,\s*/, $link_hdr;
+			}
+		}
+	}
+	return \@all_prs;
+}
+
+# }}}
+# create_pr - create a pull request {{{
+#
+# Required options: head (source branch), base (target branch), title
+# Optional:         body
+#
+# Returns the PR object (hashref) from the GitHub API.
+sub create_pr {
+	my ($self, $owner_repo, %opts) = @_;
+	bail("Missing owner/repo for create_pr")  unless $owner_repo;
+	bail("Missing head branch for create_pr") unless $opts{head};
+	bail("Missing base branch for create_pr") unless $opts{base};
+	bail("Missing title for create_pr")       unless $opts{title};
+
+	my $payload = JSON::PP->new->encode({
+		title => $opts{title},
+		body  => $opts{body} // '',
+		head  => $opts{head},
+		base  => $opts{base},
+	});
+
+	my ($code, $msg, $data) = curl(
+		"POST", $self->pulls_url($owner_repo),
+		{'Content-Type' => 'application/json'}, $payload, 0, $self->{creds}
+	);
+	bail(
+		"Failed to create pull request for #C{%s}: HTTP %s - %s",
+		$owner_repo, $code, $msg
+	) unless $code == 201;
+
+	my $pr;
+	eval { $pr = load_json($data); 1 }
+		or bail("Failed to parse create_pr response from GitHub: %s", $@);
+	return $pr;
+}
+
+# }}}
+# update_pr - update an existing pull request {{{
+#
+# opts: title, body, state ('open' or 'closed')
+#
+# Returns the updated PR object.
+sub update_pr {
+	my ($self, $owner_repo, $number, %opts) = @_;
+	bail("Missing owner/repo for update_pr") unless $owner_repo;
+	bail("Missing PR number for update_pr")  unless defined $number;
+
+	my %update;
+	$update{title} = $opts{title} if defined $opts{title};
+	$update{body}  = $opts{body}  if defined $opts{body};
+	$update{state} = $opts{state} if defined $opts{state};
+
+	my $payload = JSON::PP->new->encode(\%update);
+	my ($code, $msg, $data) = curl(
+		"PATCH", $self->pulls_url($owner_repo, $number),
+		{'Content-Type' => 'application/json'}, $payload, 0, $self->{creds}
+	);
+	bail(
+		"Failed to update pull request #%d for #C{%s}: HTTP %s - %s",
+		$number, $owner_repo, $code, $msg
+	) unless $code == 200;
+
+	my $pr;
+	eval { $pr = load_json($data); 1 }
+		or bail("Failed to parse update_pr response from GitHub: %s", $@);
+	return $pr;
+}
+
 # }}}
 # }}}
 
diff --git a/t/ci-compiler.t b/t/ci-compiler.t
index 24d1696c..0c9e1bf6 100644
--- a/t/ci-compiler.t
+++ b/t/ci-compiler.t
@@ -48,7 +48,7 @@ ok !$@, "loaded Concourse provider" or diag $@;
 subtest 'AST - construction and accessors' => sub {
 	my $ast = Genesis::CI::Compiler::AST->new(
 		metadata     => { name => 'test-pipe', version => '2.0', source => 'modern' },
-		branches     => { live => 'main', target_prefix => 'target/' },
+		branches     => { control => 'main', target_prefix => 'target/' },
 		integrations => {
 			vault => { url => 'https://vault.example.com' },
 			source_control => {
@@ -88,7 +88,7 @@ subtest 'AST - construction and accessors' => sub {
 
 	# Accessors
 	is $ast->metadata->{name}, 'test-pipe', "metadata name accessor works";
-	is $ast->branches->{live}, 'main', "branches accessor works";
+	is $ast->branches->{control}, 'main', "branches accessor works";
 	is $ast->integrations->{vault}{url}, 'https://vault.example.com', "integrations accessor works";
 	is $ast->configuration->{public}, 1, "configuration accessor works";
 
@@ -326,7 +326,7 @@ subtest 'ASTBuilder - legacy format' => sub {
 	is $ast->metadata->{name}, 'my-legacy-pipeline', "legacy pipeline name preserved";
 	is $ast->metadata->{source}, 'legacy', "source marked as legacy";
 	is $ast->metadata->{source_file}, 'ci.yml', "source_file preserved";
-	is $ast->branches->{live}, 'master', "branch preserved from legacy git.branch";
+	is $ast->branches->{control}, 'master', "branch preserved from legacy git.branch";
 	ok $ast->provider_config->{concourse}{_legacy_pipeline_raw}, "legacy raw data preserved in provider_config";
 };
 
@@ -341,7 +341,7 @@ subtest 'ASTBuilder - modern format' => sub {
 				version => '2.0',
 			},
 			branches => {
-				live => 'main',
+				control => 'main',
 				target_prefix => 'deploy/',
 			},
 			workflows => {
@@ -374,7 +374,7 @@ subtest 'ASTBuilder - modern format' => sub {
 	my $ast = $builder->build($parsed, $scripts);
 	isa_ok $ast, 'Genesis::CI::Compiler::AST', "build returns an AST for modern format";
 	is $ast->metadata->{name}, 'modern-pipeline', "modern metadata preserved";
-	is $ast->branches->{live}, 'main', "branches preserved from modern format";
+	is $ast->branches->{control}, 'main', "branches preserved from modern format";
 
 	# Workflows should have been processed into graph form
 	my $wf = $ast->workflows->{deploy};
@@ -399,7 +399,7 @@ subtest 'ASTBuilder - modern format populates generic fields' => sub {
 		_source_format => 'multi-file',
 		pipeline => {
 			metadata => { name => 'generic-test', version => '2.0' },
-			branches => { live => 'main' },
+			branches => { control => 'main' },
 			workflows => {
 				deploy => {
 					type   => 'deployment',
@@ -436,7 +436,7 @@ subtest 'ASTBuilder - no auto-population without explicit triggers/resources' =>
 		_source_format => 'multi-file',
 		pipeline => {
 			metadata  => { name => 'no-auto-pop-test' },
-			branches  => { live => 'main' },
+			branches  => { control => 'main' },
 			workflows => {},
 			# No explicit triggers or resources
 		},
@@ -555,6 +555,52 @@ subtest 'ASTBuilder - _build_from_env_files: prior_env referencing unknown env i
 	is scalar(@$edges), 0, "no edge added for unknown prior_env";
 };
 
+subtest 'ASTBuilder - _build_from_env_files: entrypoint with no pipeline block is included when referenced' => sub {
+	my $tmp = tempdir(CLEANUP => 1);
+
+	# lab.yml — pipeline entrypoint; Phase C convention writes NO pipeline block
+	open my $fh, '>', "$tmp/lab.yml" or die $!;
+	print $fh "---\ngenesis:\n  env: lab\n";
+	close $fh;
+
+	# nonprod.yml — references lab as prior_env
+	open $fh, '>', "$tmp/nonprod.yml" or die $!;
+	print $fh "---\ngenesis:\n  pipeline:\n    prior_env: lab\n";
+	close $fh;
+
+	my $builder = Genesis::CI::Compiler::ASTBuilder->new();
+	my ($nodes, $edges) = $builder->_build_from_env_files($tmp);
+
+	ok exists $nodes->{lab},     "lab node present despite no genesis.pipeline block";
+	ok exists $nodes->{nonprod}, "nonprod node present";
+	is scalar(@$edges), 1, "one edge";
+	is $edges->[0]{from}, 'lab',    "edge from: lab";
+	is $edges->[0]{to},   'nonprod', "edge to: nonprod";
+	is $nodes->{lab}{require_pr}, 0, "lab require_pr defaults to 0";
+	is $nodes->{lab}{manual},     0, "lab manual defaults to 0";
+};
+
+subtest 'ASTBuilder - _build_from_env_files: unreferenced files without pipeline block excluded' => sub {
+	my $tmp = tempdir(CLEANUP => 1);
+
+	# infra.yml — genesis block but no pipeline sub-key, not referenced
+	open my $fh, '>', "$tmp/infra.yml" or die $!;
+	print $fh "---\ngenesis:\n  env: infra\n";
+	close $fh;
+
+	# lab.yml — has pipeline block and references nothing
+	open $fh, '>', "$tmp/lab.yml" or die $!;
+	print $fh "---\ngenesis:\n  pipeline:\n    require_pr: false\n";
+	close $fh;
+
+	my $builder = Genesis::CI::Compiler::ASTBuilder->new();
+	my ($nodes, $edges) = $builder->_build_from_env_files($tmp);
+
+	ok  exists $nodes->{lab},   "lab included (has pipeline block)";
+	ok !exists $nodes->{infra}, "infra excluded (no pipeline block, not referenced)";
+	is scalar(@$edges), 0, "no edges";
+};
+
 subtest 'ASTBuilder - _build_from_env_files: non-existent dir returns empty' => sub {
 	my $builder = Genesis::CI::Compiler::ASTBuilder->new();
 	my ($nodes, $edges) = $builder->_build_from_env_files('/does/not/exist/xyz');
@@ -861,7 +907,7 @@ subtest 'Validator - DAG cycle detection' => sub {
 		_source_format => 'multi-file',
 		pipeline => {
 			metadata => { name => 'test' },
-			branches => { live => 'main' },
+			branches => { control => 'main' },
 			workflows => {
 				cycle => {
 					graph => {
@@ -895,7 +941,7 @@ subtest 'Validator - valid multi-file config' => sub {
 		_source_format => 'multi-file',
 		pipeline => {
 			metadata  => { name => 'test-pipeline' },
-			branches  => { live => 'main' },
+			branches  => { control => 'main' },
 			workflows => {
 				deploy => {
 					type   => 'deployment',
@@ -1010,7 +1056,7 @@ subtest 'Concourse - native generation from modern AST' => sub {
 			source          => 'modern',
 			deployment_type => 'cf',
 		},
-		branches => { live => 'main' },
+		branches => { control => 'main' },
 		integrations => {
 			vault => {
 				url  => 'https://vault.example.com',
@@ -1247,7 +1293,7 @@ subtest 'Concourse - output_files' => sub {
 subtest 'Concourse - generate_from_ast routes to native for non-legacy' => sub {
 	my $ast = Genesis::CI::Compiler::AST->new(
 		metadata => { name => 'test', source => 'modern' },
-		branches => { live => 'main' },
+		branches => { control => 'main' },
 		integrations => {
 			source_control => { provider => 'github', repository => 'org/repo' },
 		},
@@ -1283,7 +1329,7 @@ subtest 'Concourse - locker resources generated when locker configured' => sub {
 			source          => 'modern',
 			deployment_type => 'cf',
 		},
-		branches => { live => 'main' },
+		branches => { control => 'main' },
 		integrations => {
 			vault => {
 				url  => 'https://vault.example.com',
@@ -1350,7 +1396,7 @@ subtest 'Concourse - locker resources generated when locker configured' => sub {
 subtest 'Concourse - locker skips bosh-lock for create-env' => sub {
 	my $ast = Genesis::CI::Compiler::AST->new(
 		metadata => { name => 'ce-test', deployment_type => 'bosh', source => 'modern' },
-		branches => { live => 'main' },
+		branches => { control => 'main' },
 		integrations => {
 			vault => { url => 'https://vault.example.com' },
 			source_control => {
@@ -1401,7 +1447,7 @@ subtest 'Concourse - locker skips bosh-lock for create-env' => sub {
 subtest 'Concourse - auto-update job generated' => sub {
 	my $ast = Genesis::CI::Compiler::AST->new(
 		metadata => { name => 'autoupdate-test', deployment_type => 'cf', source => 'modern' },
-		branches => { live => 'main' },
+		branches => { control => 'main' },
 		integrations => {
 			vault => { url => 'https://vault.example.com' },
 			source_control => {
@@ -1467,7 +1513,7 @@ subtest 'Concourse - auto-update job generated' => sub {
 subtest 'Concourse - grouped notifications' => sub {
 	my $ast = Genesis::CI::Compiler::AST->new(
 		metadata => { name => 'grouped-test', deployment_type => 'cf', source => 'modern' },
-		branches => { live => 'main' },
+		branches => { control => 'main' },
 		integrations => {
 			vault => { url => 'https://vault.example.com' },
 			source_control => {
@@ -1523,7 +1569,7 @@ subtest 'Concourse - grouped notifications' => sub {
 subtest 'Concourse - custom groups' => sub {
 	my $ast = Genesis::CI::Compiler::AST->new(
 		metadata => { name => 'custom-groups-test', deployment_type => 'cf', source => 'modern' },
-		branches => { live => 'main' },
+		branches => { control => 'main' },
 		integrations => {
 			vault => { url => 'https://vault.example.com' },
 			source_control => {
@@ -1584,7 +1630,7 @@ subtest 'Concourse - custom groups' => sub {
 subtest 'Concourse - OCFP config name support' => sub {
 	my $ast = Genesis::CI::Compiler::AST->new(
 		metadata => { name => 'ocfp-test', deployment_type => 'cf', source => 'modern' },
-		branches => { live => 'main' },
+		branches => { control => 'main' },
 		integrations => {
 			vault => { url => 'https://vault.example.com' },
 			source_control => {
@@ -1966,6 +2012,836 @@ subtest 'Compiler - override lookup uses ci_dir' => sub {
 		"override in wrong directory is not applied";
 };
 
+### ============================================================ ###
+### AST - glob metacharacter safety
+### ============================================================ ###
+
+subtest 'AST - targets_matching escapes regex metacharacters in literal segments' => sub {
+	my $ast = Genesis::CI::Compiler::AST->new(
+		targets => {
+			'aws.dev-sandbox' => { type => 'bosh-director' },
+			'awsXdev-sandbox' => { type => 'bosh-director' },  # should NOT match 'aws.dev-*'
+			'aws.dev-prod'    => { type => 'bosh-director' },
+		},
+	);
+
+	my @matched = $ast->targets_matching('aws.dev-*');
+	is scalar(@matched), 2, "targets_matching 'aws.dev-*' matches 2 (dot is literal)";
+
+	@matched = $ast->targets_matching('awsXdev-*');
+	is scalar(@matched), 1, "targets_matching 'awsXdev-*' matches only 1 (no false positive)";
+
+	@matched = $ast->targets_matching('aws.dev-sandbox');
+	is scalar(@matched), 1, "exact match with dot finds exactly 1";
+};
+
+subtest 'AST - resources_matching escapes regex metacharacters in literal segments' => sub {
+	my $ast = Genesis::CI::Compiler::AST->new(
+		resources => {
+			'git.repo'   => { type => 'git' },
+			'gitXrepo'   => { type => 'git' },   # should NOT match 'git.repo'
+			'git.config' => { type => 'git' },
+		},
+	);
+
+	my @matched = $ast->resources_matching('git.repo');
+	is scalar(@matched), 1, "resources_matching 'git.repo' matches only 1 (dot is literal)";
+
+	@matched = $ast->resources_matching('git.*');
+	is scalar(@matched), 2, "resources_matching 'git.*' matches 2 git.* entries";
+};
+
+### ============================================================ ###
+### Validator - env-file-topology mode (no pipeline.yml)
+### ============================================================ ###
+
+subtest 'Validator - multi-file without pipeline.yml passes validation' => sub {
+	my $v = Genesis::CI::Compiler::Validator->new();
+
+	# When no pipeline.yml exists, the parser sets pipeline => {}.
+	# The validator must not require 'workflows' in this case.
+	$v->validate({
+		_source_format => 'multi-file',
+		pipeline       => {},   # empty: no pipeline.yml, topology from env files
+		integrations   => {
+			vault          => { url => 'https://vault.example.com' },
+			source_control => { provider => 'github', repository => 'org/repo' },
+		},
+		targets => {
+			sandbox => { type => 'bosh-director', connection => { url => 'https://bosh' } },
+		},
+	});
+
+	ok !$v->has_errors,
+		"empty pipeline section (env-file-topology mode) passes without 'workflows required' error"
+		or diag join("\n", @{$v->errors});
+};
+
+### ============================================================ ###
+### Phase E: Genesis Config Delegation Tests
+### ============================================================ ###
+
+# Minimal mock objects for testing without loading Genesis::Top / Genesis::Config.
+# We only need duck-typed config->has/get and top->path/config.
+
+{
+	package MockConfig;
+	sub new {
+		my ($class, %data) = @_;
+		return bless { data => \%data }, $class;
+	}
+	sub has { my ($self, $k) = @_; return exists $self->{data}{$k} }
+	sub get { my ($self, $k) = @_; return $self->{data}{$k} }
+}
+
+{
+	package MockTop;
+	sub new {
+		my ($class, %opts) = @_;
+		return bless { config => $opts{config}, base => $opts{base} || '/fake' }, $class;
+	}
+	sub config { $_[0]->{config} }
+	sub path {
+		my ($self, $rel) = @_;
+		return defined $rel ? "$self->{base}/$rel" : $self->{base};
+	}
+}
+
+my $_ci_data = {
+	targets => {
+		sandbox => {
+			type       => 'bosh-director',
+			connection => { url => 'https://bosh.sandbox.example.com' },
+		},
+		prod => {
+			type       => 'bosh-director',
+			connection => { url => 'https://bosh.prod.example.com' },
+		},
+	},
+	integrations => {
+		vault => {
+			url  => 'https://vault.example.com',
+			auth => {
+				role_id   => { secret_ref => 'secret/ci:role_id' },
+				secret_id => { secret_ref => 'secret/ci:secret_id' },
+			},
+		},
+		source_control => {
+			provider   => 'github',
+			repository => 'org/repo',
+			auth       => { type => 'ssh-key', private_key => { secret_ref => 'secret/ci:private_key' } },
+		},
+	},
+	pipeline => {
+		workflows => {
+			deploy => {
+				type   => 'deploy',
+				stages => [qw(sandbox prod)],
+			},
+		},
+	},
+};
+
+subtest 'Compiler - can_compile_from_genesis_config: false without top' => sub {
+	ok !Genesis::CI::Compiler->can_compile_from_genesis_config(undef),
+		"returns false when top is undef";
+	ok !Genesis::CI::Compiler->can_compile_from_genesis_config(
+		bless({}, 'NoConfigMethods')
+	), "returns false when top has no config method";
+};
+
+subtest 'Compiler - can_compile_from_genesis_config: detects ci: in config' => sub {
+	my $top_with_ci = MockTop->new(
+		config => MockConfig->new(ci => $_ci_data),
+	);
+	ok(Genesis::CI::Compiler->can_compile_from_genesis_config($top_with_ci),
+		"returns true when top->config has ci: key");
+
+	my $top_without_ci = MockTop->new(
+		config => MockConfig->new(deployment_type => 'cf'),
+	);
+	ok(!Genesis::CI::Compiler->can_compile_from_genesis_config($top_without_ci),
+		"returns false when top->config has no ci: key");
+};
+
+subtest 'Compiler - validate_config_section: accepts valid ci structure' => sub {
+	eval { Genesis::CI::Compiler->validate_config_section($_ci_data, undef) };
+	ok !$@, "valid ci structure passes without error" or diag $@;
+};
+
+subtest 'Compiler - validate_config_section: rejects missing targets' => sub {
+	my $bad = { %$_ci_data, targets => {} };  # empty targets
+	eval { Genesis::CI::Compiler->validate_config_section($bad, undef) };
+	like $@, qr/ci\.targets.*required/i, "empty targets triggers error";
+
+	my $no_targets = { %$_ci_data };
+	delete $no_targets->{targets};
+	eval { Genesis::CI::Compiler->validate_config_section($no_targets, undef) };
+	like $@, qr/ci\.targets.*required/i, "missing targets triggers error";
+};
+
+subtest 'Compiler - validate_config_section: rejects missing source_control' => sub {
+	my $bad = {
+		%$_ci_data,
+		integrations => { vault => { url => 'https://vault' } },  # no source_control
+	};
+	eval { Genesis::CI::Compiler->validate_config_section($bad, undef) };
+	like $@, qr/source_control.*required/i, "missing source_control triggers error";
+};
+
+subtest 'Parser - genesis-config: produces correct normalized structure' => sub {
+	my $top = MockTop->new(
+		config => MockConfig->new(ci => $_ci_data),
+		base   => '/myrepo',
+	);
+
+	my $parser = Genesis::CI::Compiler::Parser->new(top => $top);
+	my $parsed = eval { $parser->parse() };
+	ok !$@, "parse() succeeds with genesis-config source" or diag $@;
+
+	is $parsed->{_source_format}, 'genesis-config', "_source_format is 'genesis-config'";
+	like $parsed->{_source_path}, qr{\.genesis/config$}, "_source_path ends with .genesis/config";
+
+	ok ref($parsed->{targets}) eq 'HASH', "targets is a hash";
+	ok exists $parsed->{targets}{sandbox},  "sandbox target present";
+	ok exists $parsed->{targets}{prod},     "prod target present";
+
+	ok ref($parsed->{integrations}) eq 'HASH', "integrations is a hash";
+	ok $parsed->{integrations}{vault}{url}, "vault url present";
+
+	ok ref($parsed->{pipeline}) eq 'HASH',    "pipeline is a hash";
+	ok $parsed->{pipeline}{workflows},         "workflows present (from ci.pipeline)";
+
+	# env_dir must NOT be set when a pipeline section is provided
+	ok(!$parsed->{env_dir},
+		"env_dir not set when pipeline section is provided");
+
+	# ci.provider: must be propagated into $parsed->{provider} so that
+	# Compiler->compile() can populate provider_opts from stored config.
+	ok ref($parsed->{provider}) eq 'HASH', "provider is a hash";
+};
+
+subtest 'Parser - genesis-config: provider key propagated from ci.provider' => sub {
+	my $ci_with_provider = {
+		%$_ci_data,
+		provider => { type => 'concourse', target => 'prod', team => 'platform' },
+	};
+	my $top = MockTop->new(
+		config => MockConfig->new(ci => $ci_with_provider),
+		base   => '/myrepo',
+	);
+	my $parser = Genesis::CI::Compiler::Parser->new(top => $top);
+	my $parsed = eval { $parser->parse() };
+	ok !$@, "parse() succeeds with provider in ci" or diag $@;
+
+	is_deeply $parsed->{provider},
+		{ type => 'concourse', target => 'prod', team => 'platform' },
+		"ci.provider data round-trips through parser into parsed->{provider}";
+};
+
+subtest 'Parser - genesis-config: sets env_dir when no pipeline section' => sub {
+	my $ci_no_pipeline = { %$_ci_data };
+	delete $ci_no_pipeline->{pipeline};
+
+	my $top = MockTop->new(
+		config => MockConfig->new(ci => $ci_no_pipeline),
+		base   => '/myrepo',
+	);
+
+	my $parser = Genesis::CI::Compiler::Parser->new(top => $top);
+	my $parsed = eval { $parser->parse() };
+	ok !$@, "parse() succeeds when ci has no pipeline key" or diag $@;
+
+	ok $parsed->{env_dir}, "env_dir is set when no pipeline section";
+	is $parsed->{env_dir}, '/myrepo', "env_dir is top->path()";
+	is_deeply $parsed->{pipeline}, {}, "pipeline is empty hash (env-file topology mode)";
+};
+
+subtest 'Parser - genesis-config: fallback order (ci_dir missing, file missing)' => sub {
+	my $top = MockTop->new(
+		config => MockConfig->new(ci => $_ci_data),
+	);
+
+	# Neither ci_dir nor file exist; should fall through to genesis-config
+	my $parser = Genesis::CI::Compiler::Parser->new(
+		ci_dir => '/nonexistent/ci',
+		file   => '/nonexistent/ci.yml',
+		top    => $top,
+	);
+	my $parsed = eval { $parser->parse() };
+	ok !$@, "falls through to genesis-config when ci_dir and file are absent" or diag $@;
+	is $parsed->{_source_format}, 'genesis-config',
+		"_source_format is genesis-config after fallthrough";
+};
+
+subtest 'Validator - genesis-config format routes to multi-file validation' => sub {
+	my $v = Genesis::CI::Compiler::Validator->new();
+
+	$v->validate({
+		_source_format => 'genesis-config',
+		pipeline       => {
+			workflows => {
+				deploy => {
+					type   => 'deployment',
+					stages => [
+						{ name => 'sandbox' },
+						{ name => 'prod' },
+					],
+				},
+			},
+		},
+		integrations   => {
+			vault          => { url => 'https://vault.example.com' },
+			source_control => { provider => 'github', repository => 'org/repo' },
+		},
+		targets => {
+			sandbox => { type => 'bosh-director', connection => { url => 'https://bosh' } },
+			prod    => { type => 'bosh-director', connection => { url => 'https://bosh' } },
+		},
+		scripts         => {},
+		provider_config => {},
+	});
+
+	ok !$v->has_errors,
+		"genesis-config format passes multi-file validation"
+		or diag join("\n", @{$v->errors});
+};
+
+subtest 'Top - register_config_section stores handler' => sub {
+	# Verify the registration mechanism works by calling it directly
+	# (Compiler.pm registered 'ci' when it was loaded at the top of this file)
+	# We test by creating a custom handler for a synthetic section.
+
+	{
+		package FakeHandler;
+		our $called = 0;
+		sub validate_config_section { $called = 1 }
+	}
+
+	Genesis::Top->register_config_section('_test_section_', 'FakeHandler');
+
+	# Calling validate_config_section through the registry requires _validate_config
+	# to run, which needs a real repo.  We just verify registration succeeded by
+	# checking the handler is retrievable.
+	ok $FakeHandler::called == 0, "handler not yet called (no config loaded)";
+	Genesis::Top->register_config_section('_test_section_', 'FakeHandler');
+	ok 1, "re-registering same section does not error";
+};
+
+### ============================================================ ###
+### Phase E Provider Options System Tests
+### ============================================================ ###
+
+subtest 'PipelineProvider - known_providers lists registered types' => sub {
+	my @providers = Genesis::CI::Compiler::PipelineProvider->known_providers();
+	ok scalar(@providers) >= 1, "at least one provider registered";
+	ok grep { $_ eq 'concourse' } @providers, "concourse is registered";
+};
+
+subtest 'PipelineProvider - base class cli_opts returns empty list' => sub {
+	# We cannot call cli_opts on the abstract base directly (bug guard),
+	# so we test via the Concourse subclass and verify the pattern instead.
+	my @opts = Genesis::CI::Concourse->cli_opts();
+	ok scalar(@opts) > 0, "Concourse declares at least one CLI opt";
+	ok grep { $_ eq 'ci-target=s' } @opts, "ci-target=s declared";
+	ok grep { $_ eq 'ci-team=s'   } @opts, "ci-team=s declared";
+	ok grep { $_ eq 'ci-pause'    } @opts, "ci-pause declared (boolean flag)";
+	ok grep { $_ eq 'ci-expose'   } @opts, "ci-expose declared (boolean flag)";
+};
+
+subtest 'Concourse - cli_opts_help contains required option documentation' => sub {
+	my $help = Genesis::CI::Concourse->cli_opts_help(valid_types => ['concourse']);
+	ok length($help) > 0,                          "help text is non-empty";
+	like $help, qr/--ci-target/,                   "documents --ci-target";
+	like $help, qr/--ci-team/,                     "documents --ci-team";
+	like $help, qr/--ci-pipeline-name/,            "documents --ci-pipeline-name";
+	like $help, qr/--ci-pause/,                    "documents --ci-pause";
+	like $help, qr/--ci-expose/,                   "documents --ci-expose";
+	like $help, qr/required/i,                     "marks required options";
+	like $help, qr/optional.*default|default.*optional/i, "marks optional options with defaults";
+	like $help, qr/main/,                          "shows default team 'main'";
+};
+
+subtest 'Concourse - cli_opts_help hidden when type not in valid_types' => sub {
+	my $help = Genesis::CI::Concourse->cli_opts_help(valid_types => ['github-actions']);
+	is $help, '', "help empty when concourse not in valid_types";
+};
+
+subtest 'Concourse - provider_options_schema has correct structure' => sub {
+	my $schema = Genesis::CI::Concourse->provider_options_schema();
+	ok ref($schema) eq 'HASH',            "schema is a hash";
+	ok exists $schema->{type},            "'type' key present";
+	ok $schema->{type}{required},         "'type' is required";
+	ok exists $schema->{target},          "'target' key present";
+	ok exists $schema->{team},            "'team' key present";
+	ok exists $schema->{expose},          "'expose' key present";
+	ok exists $schema->{pause_after_set}, "'pause_after_set' key present";
+	is $schema->{team}{default}, 'main',  "team default is 'main'";
+};
+
+subtest 'Concourse - provider_options_defaults returns expected defaults' => sub {
+	my $defaults = Genesis::CI::Concourse->provider_options_defaults();
+	ok ref($defaults) eq 'HASH',          "defaults is a hash";
+	is $defaults->{team},            'main', "team default is 'main'";
+	is $defaults->{expose},          0,      "expose default is false";
+	is $defaults->{pause_after_set}, 0,      "pause_after_set default is false";
+};
+
+subtest 'Concourse - provider_config omits default values' => sub {
+	# Only non-defaults should appear in config output
+	my $ast = Genesis::CI::Compiler::AST->new();
+	my $provider = Genesis::CI::Concourse->new(
+		ast           => $ast,
+		provider_opts => {
+			type   => 'concourse',
+			target => 'my-target',
+			team   => 'main',      # this IS the default — should be omitted
+			expose => 0,           # this IS the default — should be omitted
+		},
+	);
+	my $config = $provider->provider_config();
+	ok ref($config) eq 'HASH',          "provider_config returns hash";
+	is $config->{type},   'concourse',  "type always present";
+	is $config->{target}, 'my-target',  "non-default target included";
+	ok !exists $config->{team},         "default team omitted";
+	ok !exists $config->{expose},       "default expose omitted";
+};
+
+subtest 'Concourse - provider_config includes non-default values' => sub {
+	my $ast = Genesis::CI::Compiler::AST->new();
+	my $provider = Genesis::CI::Concourse->new(
+		ast           => $ast,
+		provider_opts => {
+			type            => 'concourse',
+			team            => 'my-team',   # non-default
+			pause_after_set => 1,           # non-default
+		},
+	);
+	my $config = $provider->provider_config();
+	is $config->{team},            'my-team', "non-default team included";
+	is $config->{pause_after_set}, 1,         "non-default pause_after_set included";
+};
+
+subtest 'Concourse - provider_option applies defaults when not set' => sub {
+	my $ast = Genesis::CI::Compiler::AST->new();
+	my $provider = Genesis::CI::Concourse->new(ast => $ast);
+
+	is $provider->provider_option('team'),   'main', "team defaults to 'main'";
+	is $provider->provider_option('expose'),  0,     "expose defaults to 0";
+	is $provider->provider_option('target'), undef,  "target has no default";
+};
+
+subtest 'Concourse - provider_option prefers stored opts over defaults' => sub {
+	my $ast = Genesis::CI::Compiler::AST->new();
+	my $provider = Genesis::CI::Concourse->new(
+		ast           => $ast,
+		provider_opts => { team => 'custom-team' },
+	);
+	is $provider->provider_option('team'), 'custom-team',
+		"stored team overrides default";
+};
+
+subtest 'Concourse - describe_provider returns structured hash' => sub {
+	my $ast = Genesis::CI::Compiler::AST->new();
+	my $provider = Genesis::CI::Concourse->new(
+		ast           => $ast,
+		provider_opts => {
+			target => 'prod-concourse',
+			team   => 'genesis',
+		},
+	);
+	my %info = $provider->describe_provider();
+
+	is $info{type},   'concourse',  "type is 'concourse'";
+	is $info{label},  'Concourse',  "label is 'Concourse'";
+	is $info{status}, 'ok',         "status is 'ok'";
+	ok ref($info{extras}) eq 'ARRAY', "extras is an arrayref";
+	ok grep { $_ eq 'Target' } @{$info{extras}}, "Target in extras";
+	ok grep { $_ eq 'Team'   } @{$info{extras}}, "Team in extras";
+	is $info{Target}, 'prod-concourse', "Target value correct";
+	is $info{Team},   'genesis',        "Team value correct";
+};
+
+subtest 'PipelineProvider - all_cli_opts_help covers all providers' => sub {
+	my $help = Genesis::CI::Compiler::PipelineProvider->all_cli_opts_help();
+	like $help, qr/CI PROVIDER OPTIONS/,   "contains header";
+	like $help, qr/--ci-provider/,         "documents --ci-provider";
+	like $help, qr/concourse/,             "mentions concourse";
+	like $help, qr/--ci-target/,           "includes Concourse-specific flag";
+};
+
+subtest 'PipelineProvider - parse_cli_opts two-pass extraction' => sub {
+	# Simulate argv that includes a provider-specific flag
+	my @argv = ('--ci-target', 'my-fly-target', '--ci-team', 'ops', '--other-flag');
+	my %opts;
+
+	Genesis::CI::Compiler::PipelineProvider->parse_cli_opts(
+		\@argv, \%opts, 'concourse'
+	);
+
+	is $opts{'ci-target'}, 'my-fly-target', "ci-target extracted";
+	is $opts{'ci-team'},   'ops',           "ci-team extracted";
+	ok grep { $_ eq '--other-flag' } @argv, "unknown flag left in argv";
+};
+
+subtest 'Compiler - validate_config_section validates ci.provider' => sub {
+	# Valid with a correct provider section
+	my $valid_data = {
+		%$_ci_data,
+		provider => { type => 'concourse', target => 'my-target' },
+	};
+	eval { Genesis::CI::Compiler->validate_config_section($valid_data, undef) };
+	ok !$@, "valid ci.provider section passes" or diag $@;
+
+	# Unknown provider type
+	my $bad_type = {
+		%$_ci_data,
+		provider => { type => 'kubernetes' },
+	};
+	eval { Genesis::CI::Compiler->validate_config_section($bad_type, undef) };
+	like $@, qr/not a known CI provider/i, "unknown provider type fails";
+
+	# Unknown option key for concourse
+	my $bad_key = {
+		%$_ci_data,
+		provider => { type => 'concourse', bogus_option => 'foo' },
+	};
+	eval { Genesis::CI::Compiler->validate_config_section($bad_key, undef) };
+	like $@, qr/not a recognized option/i, "unknown provider option key fails";
+};
+
+subtest 'Validator - provider section validated in multi-file path' => sub {
+	my $v = Genesis::CI::Compiler::Validator->new();
+
+	# Valid provider section
+	$v->validate({
+		_source_format  => 'multi-file',
+		pipeline        => {},
+		targets         => { sandbox => { type => 'bosh-director', connection => { url => 'https://bosh' } } },
+		integrations    => {
+			vault          => { url => 'https://vault.example.com' },
+			source_control => { provider => 'github', repository => 'org/repo' },
+		},
+		provider        => { type => 'concourse', target => 'my-target', team => 'main' },
+		scripts         => {},
+		provider_config => {},
+	});
+	ok !$v->has_errors, "valid provider section passes validator"
+		or diag join("\n", @{$v->errors});
+
+	# Unknown option
+	$v->validate({
+		_source_format  => 'multi-file',
+		pipeline        => {},
+		targets         => { sandbox => { type => 'bosh-director', connection => { url => 'https://bosh' } } },
+		integrations    => {
+			vault          => { url => 'https://vault.example.com' },
+			source_control => { provider => 'github', repository => 'org/repo' },
+		},
+		provider        => { type => 'concourse', unknown_key => 'bad' },
+		scripts         => {},
+		provider_config => {},
+	});
+	ok $v->has_errors, "unknown provider key triggers validation error";
+	like join(' ', @{$v->errors}), qr/not a recognized option/i,
+		"error message identifies the unknown key";
+};
+
+### ============================================================ ###
+### PipelineProvider - check_prereqs
+### ============================================================ ###
+
+subtest 'PipelineProvider - base class check_prereqs returns 1' => sub {
+	# Base class has no prereqs; GHA provider inherits this no-op default.
+	eval { require 'Genesis/CI/Compiler/Providers/GithubActions.pm' };
+	if ($@) {
+		pass 'skipped: GithubActions provider not available';
+		return;
+	}
+	my $gha = Genesis::CI::GithubActions->new(
+		ast => Genesis::CI::Compiler::AST->new(
+			metadata     => { name => 'test', version => '2.0', source => 'modern' },
+			branches     => { control => 'main', target_prefix => 'target/' },
+			integrations => { source_control => { provider => 'github', repository => 'org/repo' } },
+			targets      => {},
+			workflows    => {},
+		),
+		top => undef,
+		provider_opts => {},
+	);
+	ok $gha->check_prereqs(), 'GithubActions PipelineProvider check_prereqs returns 1';
+};
+
+subtest 'PipelineProvider::Concourse - check_prereqs returns 1 when fly present' => sub {
+	my $fly = `which fly 2>/dev/null`;
+	chomp $fly;
+	unless ($fly) {
+		pass 'skipped: fly not installed in this environment';
+		return;
+	}
+	my $ast = Genesis::CI::Compiler::AST->new(
+		metadata     => { name => 'test', version => '2.0', source => 'modern' },
+		branches     => { control => 'main', target_prefix => 'target/' },
+		integrations => { source_control => { provider => 'github', repository => 'org/repo' } },
+		targets      => {},
+		workflows    => {},
+	);
+	my $p = Genesis::CI::Concourse->new(ast => $ast, top => undef, provider_opts => {});
+	ok $p->check_prereqs(), 'check_prereqs returns 1 when fly is present';
+};
+
+subtest 'PipelineProvider::Concourse - check_prereqs returns 0 when fly absent' => sub {
+	local $ENV{PATH} = '/nonexistent';
+	my $ast = Genesis::CI::Compiler::AST->new(
+		metadata     => { name => 'test', version => '2.0', source => 'modern' },
+		branches     => { control => 'main', target_prefix => 'target/' },
+		integrations => { source_control => { provider => 'github', repository => 'org/repo' } },
+		targets      => {},
+		workflows    => {},
+	);
+	my $p = Genesis::CI::Concourse->new(ast => $ast, top => undef, provider_opts => {});
+	my $result = $p->check_prereqs();
+	ok !$result, 'check_prereqs returns 0 when fly is not in PATH';
+};
+
+### ============================================================ ###
+### Concourse insecure option
+### ============================================================ ###
+
+subtest 'Concourse - insecure in provider_options_schema' => sub {
+	my $schema = Genesis::CI::Concourse->provider_options_schema();
+	ok exists $schema->{insecure},              "'insecure' key present in schema";
+	is $schema->{insecure}{type}, 'boolean',    "insecure type is boolean";
+	ok !$schema->{insecure}{required},          "insecure is not required";
+	is $schema->{insecure}{default}, 0,         "insecure default is 0";
+};
+
+subtest 'Concourse - insecure in provider_options_defaults' => sub {
+	my $defaults = Genesis::CI::Concourse->provider_options_defaults();
+	ok exists $defaults->{insecure},  "insecure present in defaults";
+	is $defaults->{insecure}, 0,      "insecure default is 0 (false)";
+};
+
+subtest 'Concourse - ci-insecure declared in cli_opts' => sub {
+	my @opts = Genesis::CI::Concourse->cli_opts();
+	ok grep { $_ eq 'ci-insecure' } @opts, "ci-insecure declared (boolean flag)";
+};
+
+subtest 'Concourse - insecure omitted from provider_config when default (false)' => sub {
+	my $ast = Genesis::CI::Compiler::AST->new();
+	my $provider = Genesis::CI::Concourse->new(
+		ast           => $ast,
+		provider_opts => { type => 'concourse', target => 't', insecure => 0 },
+	);
+	my $config = $provider->provider_config();
+	ok !exists $config->{insecure}, "insecure omitted when false (matches default)";
+};
+
+subtest 'Concourse - insecure included in provider_config when true' => sub {
+	my $ast = Genesis::CI::Compiler::AST->new();
+	my $provider = Genesis::CI::Concourse->new(
+		ast           => $ast,
+		provider_opts => { type => 'concourse', target => 't', insecure => 1 },
+	);
+	my $config = $provider->provider_config();
+	is $config->{insecure}, 1, "insecure=1 included in provider_config";
+};
+
+subtest 'Concourse - provider_option insecure defaults to 0' => sub {
+	my $ast      = Genesis::CI::Compiler::AST->new();
+	my $provider = Genesis::CI::Concourse->new(ast => $ast);
+	is $provider->provider_option('insecure'), 0, "insecure defaults to 0";
+};
+
+subtest 'Concourse - describe_provider includes Insecure field' => sub {
+	my $ast = Genesis::CI::Compiler::AST->new();
+	my $provider = Genesis::CI::Concourse->new(
+		ast           => $ast,
+		provider_opts => { target => 'myci', insecure => 1 },
+	);
+	my %info = $provider->describe_provider();
+	ok grep { $_ eq 'Insecure' } @{$info{extras}}, "Insecure in extras list";
+	is $info{Insecure}, 'yes', "Insecure field is 'yes' when insecure=1";
+};
+
+### ============================================================ ###
+### Concourse normalize_provider_opts override
+### ============================================================ ###
+
+subtest 'Concourse - normalize_provider_opts remaps ci-pause to pause_after_set' => sub {
+	my $normalized = Genesis::CI::Concourse->normalize_provider_opts({
+		'ci-pause' => 1,
+	});
+	ok !exists $normalized->{pause},          "raw 'pause' key not present after remap";
+	is $normalized->{pause_after_set}, 1,     "pause_after_set=1 after remapping ci-pause";
+};
+
+subtest 'Concourse - normalize_provider_opts does not remap if pause_after_set already set' => sub {
+	my $normalized = Genesis::CI::Concourse->normalize_provider_opts({
+		'ci-pause'       => 0,
+		'pause_after_set' => 1,
+	});
+	is $normalized->{pause_after_set}, 1,
+		"explicit pause_after_set wins over ci-pause when both present";
+};
+
+subtest 'Concourse - normalize_provider_opts handles full CLI key set' => sub {
+	my $normalized = Genesis::CI::Concourse->normalize_provider_opts({
+		'ci-target'        => 'myci',
+		'ci-team'          => 'platform',
+		'ci-pipeline-name' => 'cf-deploy',
+		'ci-pause'         => 1,
+		'ci-expose'        => 0,
+		'ci-insecure'      => 1,
+	});
+	is $normalized->{target},          'myci',      "target normalized";
+	is $normalized->{team},            'platform',  "team normalized";
+	is $normalized->{pipeline_name},   'cf-deploy', "pipeline_name normalized";
+	is $normalized->{pause_after_set}, 1,           "pause_after_set normalized from ci-pause";
+	is $normalized->{expose},          0,           "expose normalized";
+	is $normalized->{insecure},        1,           "insecure normalized";
+	ok !exists $normalized->{pause},                "no stale 'pause' key present";
+};
+
+### ============================================================ ###
+### provider_config boolean comparison (PipelineProvider)
+### ============================================================ ###
+
+subtest 'PipelineProvider - provider_config skips undef opts' => sub {
+	my $ast = Genesis::CI::Compiler::AST->new();
+	my $provider = Genesis::CI::Concourse->new(
+		ast           => $ast,
+		provider_opts => { type => 'concourse', team => undef },
+	);
+	my $config = $provider->provider_config();
+	ok !exists $config->{team}, "undef opt not included in provider_config";
+};
+
+subtest 'PipelineProvider - provider_config keeps boolean false when non-default' => sub {
+	my $ast = Genesis::CI::Compiler::AST->new();
+	# expose default is 0; setting expose=>0 explicitly should still omit it
+	# insecure default is 0; setting insecure=>1 should include it
+	my $provider = Genesis::CI::Concourse->new(
+		ast           => $ast,
+		provider_opts => { type => 'concourse', expose => 0, insecure => 1 },
+	);
+	my $config = $provider->provider_config();
+	ok !exists $config->{expose},  "expose=0 (matches default) omitted";
+	is $config->{insecure}, 1,     "insecure=1 (non-default) included";
+};
+
+### ============================================================ ###
+### validate_config_section: source_control must be a hash
+### ============================================================ ###
+
+### ============================================================ ###
+### Parser: flat-format vault/source_control normalization
+### ============================================================ ###
+
+subtest 'Parser - genesis-config: flat vault/source_control lifted into integrations' => sub {
+	my $flat_ci = {
+		targets => {
+			sandbox => { type => 'bosh-director', connection => { url => 'https://bosh' } },
+		},
+		vault => {
+			url  => 'https://vault.example.com',
+			auth => { role_id => { secret_ref => 'secret/ci:role_id' } },
+		},
+		source_control => {
+			provider   => 'github',
+			repository => 'org/repo',
+		},
+		pipeline => {},
+	};
+
+	my $top = MockTop->new(config => MockConfig->new(ci => $flat_ci), base => '/repo');
+	my $parser = Genesis::CI::Compiler::Parser->new(top => $top);
+	my $parsed = eval { $parser->parse() };
+	ok !$@, "flat-format config parses without error" or diag $@;
+
+	ok ref($parsed->{integrations}) eq 'HASH', "integrations is a hash";
+	ok $parsed->{integrations}{vault},
+		"ci.vault lifted into integrations.vault";
+	is $parsed->{integrations}{vault}{url}, 'https://vault.example.com',
+		"vault url preserved";
+	ok $parsed->{integrations}{source_control},
+		"ci.source_control lifted into integrations.source_control";
+	is $parsed->{integrations}{source_control}{provider}, 'github',
+		"source_control provider preserved";
+};
+
+subtest 'Parser - genesis-config: nested integrations.* takes precedence over flat' => sub {
+	my $mixed_ci = {
+		targets       => { sandbox => { type => 'bosh-director', connection => { url => 'u' } } },
+		vault         => { url => 'https://flat-vault.example.com' },   # flat — should be ignored
+		integrations  => {
+			vault          => { url => 'https://nested-vault.example.com' },  # nested wins
+			source_control => { provider => 'github', repository => 'org/repo' },
+		},
+		pipeline => {},
+	};
+
+	my $top = MockTop->new(config => MockConfig->new(ci => $mixed_ci), base => '/repo');
+	my $parser = Genesis::CI::Compiler::Parser->new(top => $top);
+	my $parsed = eval { $parser->parse() };
+	ok !$@, "mixed flat+nested parses without error" or diag $@;
+	is $parsed->{integrations}{vault}{url}, 'https://nested-vault.example.com',
+		"nested integrations.vault takes precedence over flat ci.vault";
+};
+
+### ============================================================ ###
+### Validator: workflows optional in pipeline section
+### ============================================================ ###
+
+subtest 'Validator - pipeline section with metadata but no workflows is valid' => sub {
+	my $v = Genesis::CI::Compiler::Validator->new();
+	$v->validate({
+		_source_format => 'genesis-config',
+		pipeline       => { name => 'cf', branches => { control => 'main', propagation => 'push' } },
+		integrations   => {
+			vault          => { url => 'https://vault.example.com' },
+			source_control => { provider => 'github', repository => 'org/repo' },
+		},
+		targets => {
+			sandbox => { type => 'bosh-director', connection => { url => 'https://bosh' } },
+		},
+	});
+	ok !$v->has_errors,
+		"pipeline with name/branches but no workflows passes validation (env-file topology)"
+		or diag join("\n", @{$v->errors});
+};
+
+subtest 'Validator - validate_config_section: accepts flat-format source_control' => sub {
+	my $flat = {
+		targets        => { sandbox => { type => 'bosh-director', connection => { url => 'u' } } },
+		source_control => { provider => 'github', repository => 'org/repo' },
+		# no integrations: key at all
+	};
+	eval { Genesis::CI::Compiler->validate_config_section($flat, undef) };
+	ok !$@, "flat ci.source_control accepted by validate_config_section" or diag $@;
+};
+
+subtest 'Compiler - validate_config_section: rejects scalar source_control' => sub {
+	my $bad = {
+		%$_ci_data,
+		integrations => { source_control => 1 },
+	};
+	eval { Genesis::CI::Compiler->validate_config_section($bad, undef) };
+	like $@, qr/source_control.*must be a hash/i,
+		"scalar source_control triggers error";
+};
+
+subtest 'Compiler - validate_config_section: accepts hash source_control' => sub {
+	my $good = {
+		%$_ci_data,
+		integrations => {
+			source_control => { provider => 'github', repository => 'org/repo' },
+		},
+	};
+	eval { Genesis::CI::Compiler->validate_config_section($good, undef) };
+	ok !$@, "hash source_control passes validation" or diag $@;
+};
+
 done_testing;
 
 # vim: ts=2 sw=2 sts=2 noet fdm=marker foldlevel=1 nu
diff --git a/t/ci-pipeline.t b/t/ci-pipeline.t
index 49a6519c..59cb6c57 100644
--- a/t/ci-pipeline.t
+++ b/t/ci-pipeline.t
@@ -14,7 +14,7 @@ $ENV{GENESIS_LIB}     ||= 'lib';
 use_ok 'Genesis::CI::Compiler::Parser';
 use_ok 'Genesis::CI::Compiler::ASTBuilder';
 use_ok 'Genesis::CI::Compiler';
-use_ok 'Genesis::Commands::Pipeline';
+use_ok 'Genesis::Commands::Pipelines';
 
 ### ============================================================ ###
 ### Phase A — env-files topology without pipeline.yml
@@ -159,17 +159,19 @@ YAML
 ### Phase B — Genesis::Commands::Pipeline module
 ### ============================================================ ###
 
-subtest 'Commands::Pipeline module loads correctly' => sub {
-	can_ok 'Genesis::Commands::Pipeline', 'apply';
-	can_ok 'Genesis::Commands::Pipeline', 'graph';
-	can_ok 'Genesis::Commands::Pipeline', 'describe';
-	can_ok 'Genesis::Commands::Pipeline', 'diff';
-	can_ok 'Genesis::Commands::Pipeline', 'status';
-	can_ok 'Genesis::Commands::Pipeline', 'pause';
-	can_ok 'Genesis::Commands::Pipeline', 'resume';
+subtest 'Commands::Pipelines module loads correctly' => sub {
+	can_ok 'Genesis::Commands::Pipelines', 'apply';
+	can_ok 'Genesis::Commands::Pipelines', 'pipeline_graph';
+	can_ok 'Genesis::Commands::Pipelines', 'pipeline_describe';
+	can_ok 'Genesis::Commands::Pipelines', 'diff';
+	can_ok 'Genesis::Commands::Pipelines', 'status';
+	can_ok 'Genesis::Commands::Pipelines', 'pause';
+	can_ok 'Genesis::Commands::Pipelines', 'resume';
+	can_ok 'Genesis::Commands::Pipelines', 'graph';
+	can_ok 'Genesis::Commands::Pipelines', 'describe';
 };
 
-subtest 'Commands::Pipeline - _compile helper: detects multi-file config' => sub {
+subtest 'Commands::Pipelines - _compile_pipeline helper: detects multi-file config' => sub {
 	my $tmp = tempdir(CLEANUP => 1);
 	mkpath("$tmp/.genesis/ci");
 
@@ -190,7 +192,7 @@ YAML
 
 	my $top = bless({}, 'Genesis::Top');  # stub
 	my $result = eval {
-		Genesis::Commands::Pipeline::_compile($top, 'concourse', {})
+		Genesis::Commands::Pipelines::_compile_pipeline($top, 'concourse')
 	};
 	# This will bail due to no vault/spruce in test environment, but we just
 	# check the compiler path was resolved correctly
@@ -203,7 +205,7 @@ YAML
 	chdir($orig);
 };
 
-subtest 'Commands::Pipeline - _mermaid_md generates valid Mermaid markdown' => sub {
+subtest 'Commands::Pipelines - _ast_to_mermaid_md generates valid Mermaid markdown' => sub {
 	my $ast = Genesis::CI::Compiler::AST->new(
 		metadata  => { name => 'test-pipeline' },
 		workflows => {
@@ -225,7 +227,7 @@ subtest 'Commands::Pipeline - _mermaid_md generates valid Mermaid markdown' => s
 		},
 	);
 
-	my $md = Genesis::Commands::Pipeline::_mermaid_md($ast);
+	my $md = Genesis::Commands::Pipelines::_ast_to_mermaid_md($ast);
 
 	like $md, qr/^# Pipeline: test-pipeline/m, "H1 heading present";
 	like $md, qr/```mermaid/,                  "mermaid fence open";
@@ -235,7 +237,7 @@ subtest 'Commands::Pipeline - _mermaid_md generates valid Mermaid markdown' => s
 	like $md, qr/```/,                          "mermaid fence close";
 };
 
-subtest 'Commands::Pipeline - _print_description does not die' => sub {
+subtest 'Commands::Pipelines - _describe_ast does not die' => sub {
 	my $ast = Genesis::CI::Compiler::AST->new(
 		metadata     => { name => 'test-pipeline', source => 'multi-file' },
 		integrations => {
@@ -259,25 +261,25 @@ subtest 'Commands::Pipeline - _print_description does not die' => sub {
 		},
 	);
 
-	eval { Genesis::Commands::Pipeline::_print_description($ast, 'concourse') };
-	ok !$@, "_print_description does not die: $@";
+	eval { Genesis::Commands::Pipelines::_describe_ast($ast, 'concourse') };
+	ok !$@, "_describe_ast does not die: $@";
 };
 
-subtest 'Commands::Pipeline - _job_status_label returns expected labels' => sub {
-	is Genesis::Commands::Pipeline::_job_status_label({ paused => 1 }),
+subtest 'Commands::Pipelines - _job_status_label returns expected labels' => sub {
+	is Genesis::Commands::Pipelines::_job_status_label({ paused => 1 }),
 		'paused', "paused job returns 'paused'";
 
-	is Genesis::Commands::Pipeline::_job_status_label({
+	is Genesis::Commands::Pipelines::_job_status_label({
 		paused => 0,
 		finished_build => { status => 'succeeded' },
 	}), 'succeeded', "succeeded job";
 
-	is Genesis::Commands::Pipeline::_job_status_label({
+	is Genesis::Commands::Pipelines::_job_status_label({
 		paused => 0,
 		finished_build => { status => 'failed' },
 	}), 'failed', "failed job";
 
-	is Genesis::Commands::Pipeline::_job_status_label({
+	is Genesis::Commands::Pipelines::_job_status_label({
 		paused => 0,
 	}), 'pending', "job with no build is pending";
 };
diff --git a/t/ci-provider.t b/t/ci-provider.t
new file mode 100644
index 00000000..99ae4b8c
--- /dev/null
+++ b/t/ci-provider.t
@@ -0,0 +1,460 @@
+#!perl
+use strict;
+use warnings;
+
+use Test::More;
+use lib 'lib';
+
+$ENV{GENESIS_TESTING} = "yes";
+$ENV{GENESIS_LIB}     ||= 'lib';
+
+use_ok 'Genesis::CI::Provider';
+use_ok 'Genesis::CI::Provider::Concourse';
+use_ok 'Genesis::CI::Provider::GithubActions';
+use_ok 'Genesis::CI::Provider::Manual';
+
+### ============================================================ ###
+### Factory: Genesis::CI::Provider->new
+### ============================================================ ###
+
+subtest 'Provider->new dispatches on type' => sub {
+	my $c = Genesis::CI::Provider->new(type => 'concourse', target => 'myci');
+	isa_ok $c, 'Genesis::CI::Provider::Concourse', 'type=concourse';
+
+	my $g = Genesis::CI::Provider->new(type => 'github-actions', repo => 'org/repo');
+	isa_ok $g, 'Genesis::CI::Provider::GithubActions', 'type=github-actions';
+
+	my $m = Genesis::CI::Provider->new(type => 'manual');
+	isa_ok $m, 'Genesis::CI::Provider::Manual', 'type=manual';
+
+	my $def = Genesis::CI::Provider->new();  # no type → manual
+	isa_ok $def, 'Genesis::CI::Provider::Manual', 'no type → manual';
+};
+
+subtest 'Provider->new rejects unknown type' => sub {
+	eval { Genesis::CI::Provider->new(type => 'bogus') };
+	like $@, qr/Unknown CI provider type/i, 'unknown type bails';
+};
+
+### ============================================================ ###
+### Factory: Genesis::CI::Provider->init
+### ============================================================ ###
+
+subtest 'Provider->init dispatches on ci-provider opt' => sub {
+	my $c = Genesis::CI::Provider->init(
+		'ci-provider' => 'concourse',
+		'ci-url'      => 'https://ci.example.com',
+		'ci-team'     => 'main',
+	);
+	isa_ok $c, 'Genesis::CI::Provider::Concourse', 'ci-provider=concourse';
+
+	my $g = Genesis::CI::Provider->init(
+		'ci-provider'      => 'github-actions',
+		'ci-github-repo'   => 'myorg/myrepo',
+	);
+	isa_ok $g, 'Genesis::CI::Provider::GithubActions', 'ci-provider=github-actions';
+
+	my $m = Genesis::CI::Provider->init('ci-provider' => 'manual');
+	isa_ok $m, 'Genesis::CI::Provider::Manual', 'ci-provider=manual';
+
+	my $def = Genesis::CI::Provider->init();  # no ci-provider → manual
+	isa_ok $def, 'Genesis::CI::Provider::Manual', 'no ci-provider → manual';
+};
+
+subtest 'Provider->init rejects unknown type' => sub {
+	eval { Genesis::CI::Provider->init('ci-provider' => 'jenkins') };
+	like $@, qr/Unknown CI provider type/i, 'unknown type bails';
+};
+
+### ============================================================ ###
+### parse_opts - two-pass extraction
+### ============================================================ ###
+
+subtest 'parse_opts extracts --ci-provider and general args' => sub {
+	my @args = ('--ci-provider', 'concourse', '--ci-target', 'myci', 'other-arg');
+	my %opts;
+	Genesis::CI::Provider->parse_opts(\@args, \%opts);
+
+	is $opts{'ci-provider'}, 'concourse', 'ci-provider extracted';
+	is $opts{'ci-target'},   'myci',      'ci-target extracted';
+	is_deeply \@args, ['other-arg'], 'non-option arg left in @args';
+};
+
+subtest 'parse_opts stops at -- sentinel' => sub {
+	my @args = ('--ci-provider', 'concourse', '--', '--ci-target', 'x');
+	my %opts;
+	Genesis::CI::Provider->parse_opts(\@args, \%opts);
+
+	is $opts{'ci-provider'}, 'concourse', 'ci-provider extracted before --';
+	ok !defined $opts{'ci-target'}, 'ci-target not extracted (after --)';
+	is_deeply \@args, ['--', '--ci-target', 'x'], 'args after -- preserved';
+};
+
+subtest 'parse_opts handles manual (no extra opts)' => sub {
+	my @args = ('--ci-provider', 'manual', 'leftover');
+	my %opts;
+	Genesis::CI::Provider->parse_opts(\@args, \%opts);
+
+	is $opts{'ci-provider'}, 'manual', 'ci-provider=manual';
+	is_deeply \@args, ['leftover'], 'non-option preserved';
+};
+
+subtest 'parse_opts handles github-actions flags' => sub {
+	my @args = ('--ci-provider', 'github-actions',
+	            '--ci-github-repo', 'acme/deploy',
+	            '--ci-github-branch', 'release');
+	my %opts;
+	Genesis::CI::Provider->parse_opts(\@args, \%opts);
+
+	is $opts{'ci-provider'},      'github-actions', 'ci-provider';
+	is $opts{'ci-github-repo'},   'acme/deploy',    'ci-github-repo';
+	is $opts{'ci-github-branch'}, 'release',        'ci-github-branch';
+	is_deeply \@args, [], 'all args consumed';
+};
+
+subtest 'parse_opts defaults to manual when no --ci-provider' => sub {
+	my @args = ('other-arg');
+	my %opts;
+	Genesis::CI::Provider->parse_opts(\@args, \%opts);
+	ok !defined $opts{'ci-provider'}, 'ci-provider undef when not supplied';
+	is_deeply \@args, ['other-arg'], 'non-option preserved';
+};
+
+### ============================================================ ###
+### opts_help
+### ============================================================ ###
+
+subtest 'opts_help aggregates all providers' => sub {
+	my $help = Genesis::CI::Provider->opts_help();
+	like $help, qr/CI PROVIDERS/,      'header present';
+	like $help, qr/--ci-provider/,     'general flag documented';
+	like $help, qr/concourse/,         'concourse section present';
+	like $help, qr/github-actions/,    'github-actions section present';
+	like $help, qr/manual/,            'manual section present';
+	like $help, qr/--ci-target/,       'concourse flag in help';
+	like $help, qr/--ci-github-repo/,  'gha flag in help';
+};
+
+### ============================================================ ###
+### Genesis::CI::Provider::Concourse
+### ============================================================ ###
+
+subtest 'Concourse->opts returns Getopt spec' => sub {
+	my @opts = Genesis::CI::Provider::Concourse->opts();
+	ok grep { $_ eq 'ci-target=s' } @opts, 'ci-target=s present';
+	ok grep { $_ eq 'ci-team=s'   } @opts, 'ci-team=s present';
+	ok grep { $_ eq 'ci-insecure' } @opts, 'ci-insecure present';
+};
+
+subtest 'Concourse->init requires --ci-target or --ci-url+--ci-team' => sub {
+	eval { Genesis::CI::Provider::Concourse->init() };
+	like $@, qr/requires --ci-target/i, 'bails without ci-target or url+team';
+};
+
+subtest 'Concourse defaults team to main and insecure to 0' => sub {
+	my $p = Genesis::CI::Provider::Concourse->new(type => 'concourse', target => 'ci.example.com');
+	is $p->{team},    'main', 'team defaults to main';
+	is $p->{insecure}, 0,     'insecure defaults to 0';
+};
+
+subtest 'Concourse->init honours all opts (new-target path)' => sub {
+	my $p = Genesis::CI::Provider::Concourse->init(
+		'ci-url'      => 'https://ci.example.com',
+		'ci-team'     => 'platform',
+		'ci-target'   => 'ci.example.com',
+		'ci-insecure' => 1,
+	);
+	is $p->{target},   'ci.example.com', 'target set';
+	is $p->{team},     'platform',       'team set';
+	is $p->{insecure}, 1,                'insecure set';
+};
+
+subtest 'Concourse->config omits default team' => sub {
+	my $p = Genesis::CI::Provider::Concourse->new(
+		type   => 'concourse',
+		target => 'myci',
+	);
+	my %cfg = $p->config;
+	is   $cfg{type},   'concourse', 'type present';
+	is   $cfg{target}, 'myci',      'target present';
+	ok !exists $cfg{team},     'default team omitted';
+	ok !exists $cfg{insecure}, 'insecure omitted when false';
+};
+
+subtest 'Concourse->config includes non-default team and insecure' => sub {
+	my $p = Genesis::CI::Provider::Concourse->new(
+		type     => 'concourse',
+		target   => 'ci',
+		team     => 'ops',
+		insecure => 1,
+	);
+	my %cfg = $p->config;
+	is $cfg{team},     'ops', 'non-default team in config';
+	is $cfg{insecure}, 1,     'insecure in config';
+};
+
+subtest 'Concourse->label' => sub {
+	my $p = Genesis::CI::Provider::Concourse->new(type => 'concourse', target => 'x');
+	is $p->label, 'Concourse', 'label is Concourse';
+};
+
+subtest 'Concourse->opts_help contains required flag docs' => sub {
+	my $help = Genesis::CI::Provider::Concourse->opts_help(
+		valid_types => [qw(concourse)]
+	);
+	like $help, qr/--ci-target/,   'ci-target documented';
+	like $help, qr/--ci-team/,     'ci-team documented';
+	like $help, qr/--ci-insecure/, 'ci-insecure documented';
+};
+
+subtest 'Concourse->opts_help empty when not in valid_types' => sub {
+	my $help = Genesis::CI::Provider::Concourse->opts_help(
+		valid_types => [qw(github-actions)]
+	);
+	is $help, '', 'empty when concourse not in valid_types';
+};
+
+### ============================================================ ###
+### Genesis::CI::Provider::GithubActions
+### ============================================================ ###
+
+subtest 'GithubActions->opts returns Getopt spec' => sub {
+	my @opts = Genesis::CI::Provider::GithubActions->opts();
+	ok grep { $_ eq 'ci-github-repo=s'   } @opts, 'ci-github-repo=s present';
+	ok grep { $_ eq 'ci-github-branch=s' } @opts, 'ci-github-branch=s present';
+};
+
+subtest 'GithubActions->init requires --ci-github-repo' => sub {
+	eval { Genesis::CI::Provider::GithubActions->init() };
+	like $@, qr/requires --ci-github-repo/i, 'bails without ci-github-repo';
+};
+
+subtest 'GithubActions->init validates org/repo format' => sub {
+	eval { Genesis::CI::Provider::GithubActions->init('ci-github-repo' => 'invalid-no-slash') };
+	like $@, qr/org\/repo/i, 'bails on bad format';
+};
+
+subtest 'GithubActions->init defaults branch to main' => sub {
+	my $p = Genesis::CI::Provider::GithubActions->init('ci-github-repo' => 'acme/deploy');
+	is $p->{branch}, 'main', 'branch defaults to main';
+};
+
+subtest 'GithubActions->config omits default branch' => sub {
+	my $p = Genesis::CI::Provider::GithubActions->new(
+		type => 'github-actions',
+		repo => 'acme/deploy',
+	);
+	my %cfg = $p->config;
+	is   $cfg{type}, 'github-actions', 'type present';
+	is   $cfg{repo}, 'acme/deploy',    'repo present';
+	ok !exists $cfg{branch}, 'default branch omitted';
+};
+
+subtest 'GithubActions->config includes non-default branch' => sub {
+	my $p = Genesis::CI::Provider::GithubActions->new(
+		type   => 'github-actions',
+		repo   => 'acme/deploy',
+		branch => 'release',
+	);
+	my %cfg = $p->config;
+	is $cfg{branch}, 'release', 'non-default branch in config';
+};
+
+subtest 'GithubActions->label' => sub {
+	my $p = Genesis::CI::Provider::GithubActions->new(
+		type => 'github-actions', repo => 'acme/x'
+	);
+	is $p->label, 'GitHub Actions', 'label is GitHub Actions';
+};
+
+### ============================================================ ###
+### Genesis::CI::Provider::Manual
+### ============================================================ ###
+
+subtest 'Manual->opts returns empty list' => sub {
+	my @opts = Genesis::CI::Provider::Manual->opts();
+	is scalar @opts, 0, 'Manual has no opts';
+};
+
+subtest 'Manual->init returns Manual object' => sub {
+	my $m = Genesis::CI::Provider::Manual->init();
+	isa_ok $m, 'Genesis::CI::Provider::Manual', 'Manual->init returns Manual';
+};
+
+subtest 'Manual->config returns only type' => sub {
+	my $m = Genesis::CI::Provider::Manual->new(type => 'manual');
+	my %cfg = $m->config;
+	is_deeply \%cfg, { type => 'manual' }, 'config is {type => manual}';
+};
+
+subtest 'Manual->label' => sub {
+	my $m = Genesis::CI::Provider::Manual->new(type => 'manual');
+	is $m->label, 'Manual', 'label is Manual';
+};
+
+### ============================================================ ###
+### check_prereqs
+### ============================================================ ###
+
+subtest 'check_prereqs: base Provider always returns 1' => sub {
+	# Base class has no prereqs; all three concrete providers inherit this
+	# as a no-op default except where they override it.
+	my $m = Genesis::CI::Provider::Manual->new(type => 'manual');
+	ok $m->check_prereqs(), 'Manual->check_prereqs returns 1';
+
+	my $g = Genesis::CI::Provider::GithubActions->new(
+		type => 'github-actions', repo => 'acme/x'
+	);
+	ok $g->check_prereqs(), 'GithubActions->check_prereqs returns 1';
+};
+
+subtest 'check_prereqs: Concourse returns 1 when fly is in PATH' => sub {
+	# Only run if fly is actually installed in this environment.
+	my $fly = `which fly 2>/dev/null`;
+	chomp $fly;
+	if ($fly) {
+		my $p = Genesis::CI::Provider::Concourse->new(
+			type => 'concourse', target => 'test'
+		);
+		ok $p->check_prereqs(), 'check_prereqs returns 1 when fly is present';
+	} else {
+		pass 'skipped: fly not installed in this environment';
+	}
+};
+
+subtest 'check_prereqs: Concourse returns 0 when fly is absent' => sub {
+	# Temporarily shadow PATH so fly cannot be found.
+	local $ENV{PATH} = '/nonexistent';
+	my $p = Genesis::CI::Provider::Concourse->new(
+		type => 'concourse', target => 'test'
+	);
+	my $result = $p->check_prereqs();
+	ok !$result, 'check_prereqs returns 0 when fly is not in PATH';
+};
+
+subtest 'check_prereqs: Concourse min_fly_version satisfied' => sub {
+	my $fly = `which fly 2>/dev/null`;
+	chomp $fly;
+	unless ($fly) {
+		pass 'skipped: fly not installed in this environment';
+		return;
+	}
+	# Require a minimum of 0.0.1 — any real fly version will satisfy this.
+	my $p = Genesis::CI::Provider::Concourse->new(
+		type           => 'concourse',
+		target         => 'test',
+		min_fly_version => '0.0.1',
+	);
+	ok $p->check_prereqs(), 'check_prereqs passes with trivially low min version';
+};
+
+subtest 'check_prereqs: Concourse min_fly_version not satisfied' => sub {
+	my $fly = `which fly 2>/dev/null`;
+	chomp $fly;
+	unless ($fly) {
+		pass 'skipped: fly not installed in this environment';
+		return;
+	}
+	# Require an impossibly high minimum — should fail.
+	my $p = Genesis::CI::Provider::Concourse->new(
+		type            => 'concourse',
+		target          => 'test',
+		min_fly_version => '9999.0.0',
+	);
+	my $result = $p->check_prereqs();
+	ok !$result, 'check_prereqs returns 0 when fly version too old';
+};
+
+### ============================================================ ###
+### validate_config — per-provider field validation
+### ============================================================ ###
+
+subtest 'validate_config: Manual always passes' => sub {
+	my $m = Genesis::CI::Provider::Manual->new(type => 'manual');
+	my @errors = $m->validate_config;
+	is scalar @errors, 0, 'Manual has no required fields';
+};
+
+subtest 'validate_config: Concourse passes with target' => sub {
+	my $p = Genesis::CI::Provider::Concourse->new(
+		type => 'concourse', target => 'my-ci',
+	);
+	my @errors = $p->validate_config;
+	is scalar @errors, 0, 'no errors when target is present';
+};
+
+subtest 'validate_config: Concourse fails without target' => sub {
+	my $p = Genesis::CI::Provider::Concourse->new(type => 'concourse');
+	my @errors = $p->validate_config;
+	ok scalar @errors > 0, 'errors returned when target missing';
+	like $errors[0], qr/target.*required/i, 'error mentions target';
+};
+
+subtest 'validate_config: Concourse passes with target and valid url' => sub {
+	my $p = Genesis::CI::Provider::Concourse->new(
+		type   => 'concourse',
+		target => 'my-ci',
+		url    => 'https://ci.example.com',
+	);
+	my @errors = $p->validate_config;
+	is scalar @errors, 0, 'no errors with target and valid https url';
+};
+
+subtest 'validate_config: Concourse rejects malformed url' => sub {
+	my $p = Genesis::CI::Provider::Concourse->new(
+		type   => 'concourse',
+		target => 'my-ci',
+		url    => 'not-a-url',
+	);
+	my @errors = $p->validate_config;
+	ok scalar @errors > 0, 'error returned for malformed url';
+	like $errors[0], qr/url.*http/i, 'error mentions url format';
+};
+
+subtest 'validate_config: GithubActions passes with valid repo' => sub {
+	my $p = Genesis::CI::Provider::GithubActions->new(
+		type => 'github-actions', repo => 'acme/deploy',
+	);
+	my @errors = $p->validate_config;
+	is scalar @errors, 0, 'no errors when repo is valid';
+};
+
+subtest 'validate_config: GithubActions fails without repo' => sub {
+	my $p = Genesis::CI::Provider::GithubActions->new(type => 'github-actions');
+	my @errors = $p->validate_config;
+	ok scalar @errors > 0, 'errors returned when repo missing';
+	like $errors[0], qr/repo.*required/i, 'error mentions repo';
+};
+
+subtest 'validate_config: GithubActions fails on bad repo format' => sub {
+	my $p = Genesis::CI::Provider::GithubActions->new(
+		type => 'github-actions', repo => 'noslash',
+	);
+	my @errors = $p->validate_config;
+	ok scalar @errors > 0, 'errors returned for bad repo format';
+	like $errors[0], qr/org.repo/i, 'error mentions org/repo format';
+};
+
+subtest 'Provider->new bails when validate_config returns errors' => sub {
+	# Concourse with no target should be rejected by the factory
+	eval { Genesis::CI::Provider->new(type => 'concourse') };
+	like $@, qr/Invalid CI provider configuration/i, 'factory bails on invalid config';
+	like $@, qr/target.*required/i, 'bail message includes field-level error';
+};
+
+subtest 'Provider->new accepts valid Concourse config' => sub {
+	my $p = Genesis::CI::Provider->new(type => 'concourse', target => 'prod');
+	isa_ok $p, 'Genesis::CI::Provider::Concourse', 'valid Concourse config accepted';
+};
+
+subtest 'Provider->new bails on invalid GithubActions config' => sub {
+	eval { Genesis::CI::Provider->new(type => 'github-actions') };
+	like $@, qr/Invalid CI provider configuration/i, 'factory bails on missing repo';
+};
+
+subtest 'Provider->new accepts valid GithubActions config' => sub {
+	my $p = Genesis::CI::Provider->new(type => 'github-actions', repo => 'org/repo');
+	isa_ok $p, 'Genesis::CI::Provider::GithubActions', 'valid GHA config accepted';
+};
+
+done_testing;
diff --git a/t/unit-tests/genesis-cli.t b/t/unit-tests/genesis-cli.t
index b83cc82f..52a2b135 100644
--- a/t/unit-tests/genesis-cli.t
+++ b/t/unit-tests/genesis-cli.t
@@ -77,6 +77,7 @@ subtest 'genesis terminate' => sub {
 	$args[0] = mock 'Genesis::Env' => {
 		name => 'my-env',
 		type => 'my-type',
+		deployment_change_reason_required_size_policy => 0,
 		notify => sub {
 			my ($self, $msg) = @_;
 			info("[my-env/my-type] ".$msg);
@@ -126,6 +127,7 @@ subtest 'genesis terminate' => sub {
 	$args[0] = mock 'Genesis::Env' => {
 		name => 'my-env',
 		type => 'my-type',
+		deployment_change_reason_required_size_policy => 0,
 		notify => sub {
 			my ($self, $msg) = @_;
 			info("[my-env/my-type] ".$msg);
@@ -176,6 +178,7 @@ subtest 'genesis terminate' => sub {
 	$args[0] = mock 'Genesis::Env' => {
 		name => 'my-env',
 		type => 'my-type',
+		deployment_change_reason_required_size_policy => 0,
 		notify => sub {
 			my ($self, $msg) = @_;
 			info("[my-env/my-type] ".$msg);
@@ -256,4 +259,466 @@ EOF
 
 };
 
+subtest 'genesis repo-init' => sub {
+	plan tests => 17;
+
+	ok(has_command('repo-init'), "repo-init command is registered");
+	ok(is_equivalent_command('init' => 'repo-init'), "init is an alias for repo-init");
+	like(command_properties('repo-init')->{usage}, qr/repo-init.*\[.*options/, "usage string mentions repo-init and options");
+
+	is(command_properties('repo-init')->{function_group}, Genesis::Commands::REPOSITORY, "repo-init belongs to repository group");
+	is(command_properties('repo-init')->{scope}, 'empty', "repo-init has empty scope (no existing repo needed)");
+
+	my %opts = command_properties('repo-init')->{options}->@*;
+
+	# Existing init options preserved
+	ok(exists $opts{'kit|k=s'}, "repo-init has --kit option");
+	ok(exists $opts{'link-dev-kit|l=s'}, "repo-init has --link-dev-kit option");
+	ok(exists $opts{'directory|d=s'}, "repo-init has --directory option");
+	ok(exists $opts{'vault=s'}, "repo-init has --vault option");
+
+	# New options
+	ok(exists $opts{'sub!'}, "repo-init has toggleable --sub option for subrepo detection");
+	ok(exists $opts{'skip-vault'}, "repo-init has --skip-vault option to defer vault config");
+	ok(exists $opts{'ci-provider=s'}, "repo-init has --ci-provider option");
+	ok(exists $opts{'force|F'}, "repo-init has --force option");
+
+	not_ok(command_properties('repo-init')->{deprecated}, "repo-init is not deprecated");
+
+	my $subref = $Genesis::Commands::RUN{'repo-init'};
+	is(ref($subref), 'CODE', "repo-init command has a subroutine reference");
+	cmp_deeply(scalar(closed_over($subref)), {
+		'$fn' => \'Genesis::Commands::Repo::repo_init',
+		'$fn_require' => \'Genesis/Commands/Repo.pm',
+		'$name' => \'repo-init',
+	}, "repo-init command routes to Repo::repo_init");
+
+	# init alias resolves to repo-init via GENESIS_COMMANDS
+	is($Genesis::Commands::GENESIS_COMMANDS{init}, 'repo-init',
+		"init alias resolves to repo-init");
+};
+
+subtest 'repo-init option processing' => sub {
+	plan tests => 18;
+
+	# Basic invocation with kit and name
+	prepare_command('repo-init', '-k', 'bosh', 'my-bosh');
+	build_command_environment;
+	my %opts = %{get_options()};
+	my @args = get_args();
+	is($opts{kit}, 'bosh', "kit option parsed correctly");
+	is($args[0], 'my-bosh', "name argument passed through");
+
+	# With --skip-vault
+	prepare_command('repo-init', '-k', 'bosh', '--skip-vault', 'my-bosh');
+	build_command_environment;
+	%opts = %{get_options()};
+	ok($opts{'skip-vault'}, "--skip-vault flag is set");
+	ok(!$opts{vault}, "vault is not set when skip-vault used");
+
+	# With --vault
+	prepare_command('repo-init', '-k', 'bosh', '--vault', 'my-vault', 'my-bosh');
+	build_command_environment;
+	%opts = %{get_options()};
+	is($opts{vault}, 'my-vault', "--vault value parsed correctly");
+	ok(!$opts{'skip-vault'}, "skip-vault not set when vault specified");
+
+	# With --ci-provider
+	prepare_command('repo-init', '-k', 'cf', '--ci-provider', 'concourse', 'my-cf');
+	build_command_environment;
+	%opts = %{get_options()};
+	is($opts{'ci-provider'}, 'concourse', "--ci-provider concourse parsed");
+
+	prepare_command('repo-init', '-k', 'cf', '--ci-provider', 'github-actions', 'my-cf');
+	build_command_environment;
+	%opts = %{get_options()};
+	is($opts{'ci-provider'}, 'github-actions', "--ci-provider github-actions parsed");
+
+	prepare_command('repo-init', '-k', 'cf', '--ci-provider', 'manual', 'my-cf');
+	build_command_environment;
+	%opts = %{get_options()};
+	is($opts{'ci-provider'}, 'manual', "--ci-provider manual parsed");
+
+	# With --sub
+	prepare_command('repo-init', '-k', 'bosh', '--sub', 'my-bosh');
+	build_command_environment;
+	%opts = %{get_options()};
+	is($opts{sub}, 1, "--sub flag sets sub to true");
+
+	# With --no-sub
+	prepare_command('repo-init', '-k', 'bosh', '--no-sub', 'my-bosh');
+	build_command_environment;
+	%opts = %{get_options()};
+	is($opts{sub}, 0, "--no-sub flag sets sub to false");
+
+	# Without --sub (not specified)
+	prepare_command('repo-init', '-k', 'bosh', 'my-bosh');
+	build_command_environment;
+	%opts = %{get_options()};
+	ok(!defined($opts{sub}), "sub is undefined when not specified");
+
+	# With --directory
+	prepare_command('repo-init', '-k', 'bosh', '-d', '/tmp/my-repo', 'my-bosh');
+	build_command_environment;
+	%opts = %{get_options()};
+	is($opts{directory}, '/tmp/my-repo', "--directory parsed correctly");
+
+	# With --link-dev-kit
+	prepare_command('repo-init', '-l', '/path/to/dev-kit', 'my-dev');
+	build_command_environment;
+	%opts = %{get_options()};
+	is($opts{'link-dev-kit'}, '/path/to/dev-kit', "--link-dev-kit parsed correctly");
+	ok(!$opts{kit}, "kit not set when link-dev-kit used");
+
+	# Name defaults from kit when not specified
+	prepare_command('repo-init', '-k', 'shield');
+	build_command_environment;
+	@args = get_args();
+	is(scalar(@args), 0, "no positional args when name not specified");
+
+	# All options together
+	prepare_command('repo-init', '-k', 'bosh', '--ci-provider', 'concourse', '--skip-vault', '--sub', '-d', '/tmp/test', 'my-bosh');
+	build_command_environment;
+	%opts = %{get_options()};
+	@args = get_args();
+	is($opts{kit}, 'bosh', "kit parsed in combined invocation");
+	is($args[0], 'my-bosh', "name parsed in combined invocation");
+};
+
+subtest 'repo-init validation' => sub {
+	plan tests => 10;
+
+	require Genesis::Commands::Repo;
+	delete $ENV{GENESIS_IGNORE_EVAL}; # Allow bail() to die instead of exit
+	$ENV{GIT_AUTHOR_NAME} = 'Test User';
+	$ENV{GIT_AUTHOR_EMAIL} = 'test@example.com';
+	$ENV{GIT_COMMITTER_NAME} = 'Test User';
+	$ENV{GIT_COMMITTER_EMAIL} = 'test@example.com';
+
+	# Setup local kit fixtures for validation tests (no network access)
+	my $vt_devkit = workdir('validation-devkit');
+	my $vt_tarball = workdir('validation-tarball');
+	mkfile_or_fail("$vt_tarball/bosh-0.0.1.tar.gz", "fake kit tarball");
+
+	# Valid cases
+	prepare_command('repo-init', '-k', "$vt_tarball/bosh-0.0.1.tar.gz", 'my-bosh');
+	build_command_environment;
+	lives_ok { Genesis::Commands::Repo::_repo_init_validate() }
+		"valid: local kit tarball + name passes";
+
+	prepare_command('repo-init', '-l', $vt_devkit, '--skip-vault', 'my-bosh');
+	build_command_environment;
+	lives_ok { Genesis::Commands::Repo::_repo_init_validate() }
+		"valid: link-dev-kit + skip-vault passes";
+
+	prepare_command('repo-init', '-k', "$vt_tarball/bosh-0.0.1.tar.gz", '--ci-provider', 'concourse', 'my-bosh');
+	build_command_environment;
+	lives_ok { Genesis::Commands::Repo::_repo_init_validate() }
+		"valid: ci-provider concourse passes";
+
+	prepare_command('repo-init', '-l', $vt_devkit, '--ci-provider', 'manual', 'my-bosh');
+	build_command_environment;
+	lives_ok { Genesis::Commands::Repo::_repo_init_validate() }
+		"valid: ci-provider manual passes";
+
+	prepare_command('repo-init', '-k', "$vt_tarball/bosh-0.0.1.tar.gz", '--ci-provider', 'github-actions', 'my-bosh');
+	build_command_environment;
+	lives_ok { Genesis::Commands::Repo::_repo_init_validate() }
+		"valid: ci-provider github-actions passes";
+
+	# Name derived from link-dev-kit when not specified
+	prepare_command('repo-init', '-l', $vt_devkit);
+	build_command_environment;
+	lives_ok { Genesis::Commands::Repo::_repo_init_validate() }
+		"valid: name derived from link-dev-kit";
+
+	# Invalid: --vault and --skip-vault together
+	prepare_command('repo-init', '-l', $vt_devkit, '--vault', 'my-vault', '--skip-vault', 'my-bosh');
+	build_command_environment;
+	throws_ok { Genesis::Commands::Repo::_repo_init_validate() }
+		qr/Cannot specify both --vault and --skip-vault/,
+		"rejects --vault with --skip-vault";
+
+	# Invalid: --kit and --link-dev-kit together
+	prepare_command('repo-init', '-k', "$vt_tarball/bosh-0.0.1.tar.gz", '-l', $vt_devkit, 'my-bosh');
+	build_command_environment;
+	throws_ok { Genesis::Commands::Repo::_repo_init_validate() }
+		qr/only specify one of kit.*or link/i,
+		"rejects --kit with --link-dev-kit";
+
+	# Invalid: no name, no kit, no link-dev-kit
+	prepare_command('repo-init');
+	build_command_environment;
+	throws_ok { Genesis::Commands::Repo::_repo_init_validate() }
+		qr/must specify a deployment name/i,
+		"rejects empty invocation";
+
+	# Invalid: bad ci-provider value
+	prepare_command('repo-init', '-l', $vt_devkit, '--ci-provider', 'jenkins', 'my-bosh');
+	build_command_environment;
+	throws_ok { Genesis::Commands::Repo::_repo_init_validate() }
+		qr/Invalid --ci-provider 'jenkins'/,
+		"rejects invalid ci-provider value";
+};
+
+subtest 'repo-init execution (integration)' => sub {
+	plan tests => 56;
+
+	require Genesis::Commands::Repo;
+	local $Genesis::VERSION = '3.2.0-rc2';
+	delete $ENV{GENESIS_IGNORE_EVAL};
+	$ENV{GIT_AUTHOR_NAME} = 'Test User';
+	$ENV{GIT_AUTHOR_EMAIL} = 'test@example.com';
+	$ENV{GIT_COMMITTER_NAME} = 'Test User';
+	$ENV{GIT_COMMITTER_EMAIL} = 'test@example.com';
+
+	# Local kit fixtures (no network access)
+	my $devkit = Cwd::abs_path('t/src/simple');
+	my $kit_tarball = Cwd::abs_path('t/repos/compiled-kit-test/.genesis/kits/compiled-0.0.1.tar.gz');
+
+	# Test 1: Basic --sub --skip-vault creates directory without .git
+	my $basedir = workdir('repo-init-test-1');
+	pushd($basedir);
+	# Init a git repo so --sub detection works
+	run('git init 2>/dev/null');
+
+	prepare_command('repo-init', '-l', $devkit, '--sub', '--skip-vault', 'bosh');
+	build_command_environment;
+Genesis::Commands::Repo::_repo_init_validate();
+	my $result = Genesis::Commands::Repo::_repo_init_execute();
+
+	ok(-d "$basedir/bosh", "bosh directory created");
+	ok(-d "$basedir/bosh/.genesis", ".genesis directory created");
+	ok(-f "$basedir/bosh/.genesis/config", ".genesis/config created");
+	ok(!-e "$basedir/bosh/.git", "no .git in subdirectory mode");
+	ok(-l "$basedir/bosh/dev", "dev symlink created for linked dev kit");
+	ok(!-d "$basedir/bosh/.genesis/bin", "no .genesis/bin without CI provider");
+
+	# Verify config has no secrets_provider
+	my $config_text = slurp("$basedir/bosh/.genesis/config");
+	unlike($config_text, qr/secrets_provider/, "config has no secrets_provider when skip-vault");
+	like($config_text, qr/deployment_type: bosh/, "config has correct deployment_type");
+
+	# Verify result hash
+	is($result->{name}, 'bosh', "result name is bosh");
+	ok($result->{vault_skipped}, "result vault_skipped is true");
+	ok(!$result->{vault}, "result vault is undef");
+	ok($result->{submodule}, "result submodule is true");
+	popd;
+
+	# Test 2: --no-sub creates .git (using kit tarball)
+	my $basedir2 = workdir('repo-init-test-2');
+	pushd($basedir2);
+	run('git init 2>/dev/null');
+
+	prepare_command('repo-init', '-k', $kit_tarball, '--no-sub', '--skip-vault', 'bosh');
+	build_command_environment;
+	Genesis::Commands::Repo::_repo_init_validate();
+	my $result2 = Genesis::Commands::Repo::_repo_init_execute();
+
+	ok(-d "$basedir2/bosh/.git", ".git created in --no-sub mode");
+	ok(!$result2->{submodule}, "result submodule is false");
+	popd;
+
+	# Test 3: --force replaces existing directory
+	my $basedir3 = workdir('repo-init-test-3');
+	pushd($basedir3);
+	mkdir_or_fail("$basedir3/bosh");
+	mkfile_or_fail("$basedir3/bosh/sentinel.txt", "should be removed");
+
+	prepare_command('repo-init', '-l', $devkit, '--no-sub', '--skip-vault', '-F', 'bosh');
+	build_command_environment;
+	Genesis::Commands::Repo::_repo_init_validate();
+	my $result3 = Genesis::Commands::Repo::_repo_init_execute();
+
+	ok(-d "$basedir3/bosh/.genesis", ".genesis created after force replace");
+	ok(!-f "$basedir3/bosh/sentinel.txt", "old sentinel file removed by force");
+	popd;
+
+	# Test 4: Name derived from link-dev-kit basename
+	my $basedir4 = workdir('repo-init-test-4');
+	pushd($basedir4);
+
+	prepare_command('repo-init', '-l', $devkit, '--no-sub', '--skip-vault');
+	build_command_environment;
+	Genesis::Commands::Repo::_repo_init_validate();
+	my $result4 = Genesis::Commands::Repo::_repo_init_execute();
+
+	ok(-d "$basedir4/simple/.genesis", "directory named from dev-kit basename");
+	is($result4->{name}, 'simple', "name derived from dev-kit");
+	popd;
+
+	# Test 5: Existing directory without --force bails (non-interactive)
+	my $basedir5 = workdir('repo-init-test-5');
+	pushd($basedir5);
+	mkdir_or_fail("$basedir5/bosh");
+
+	prepare_command('repo-init', '-l', $devkit, '--no-sub', '--skip-vault', 'bosh');
+	build_command_environment;
+	throws_ok {
+		Genesis::Commands::Repo::_repo_init_validate();
+	} qr/already exists.*-F/i,
+		"bails on existing directory in non-interactive mode";
+	popd;
+
+	# Test 6: Custom --directory (using kit tarball)
+	my $basedir6 = workdir('repo-init-test-6');
+	pushd($basedir6);
+
+	prepare_command('repo-init', '-k', $kit_tarball, '--no-sub', '--skip-vault', '-d', 'my-custom-dir', 'bosh');
+	build_command_environment;
+	Genesis::Commands::Repo::_repo_init_validate();
+	my $result6 = Genesis::Commands::Repo::_repo_init_execute();
+
+	ok(-d "$basedir6/my-custom-dir/.genesis", "custom directory created via --directory");
+	ok(!-e "$basedir6/bosh", "default 'bosh' directory not created when --directory used");
+	my $cfg6 = slurp("$basedir6/my-custom-dir/.genesis/config");
+	like($cfg6, qr/deployment_type: bosh/, "config deployment_type is still bosh despite custom dir name");
+	popd;
+
+	# Test 7: Custom name different from kit
+	my $basedir7 = workdir('repo-init-test-7');
+	pushd($basedir7);
+
+	prepare_command('repo-init', '-l', $devkit, '--no-sub', '--skip-vault', 'my-boshen');
+	build_command_environment;
+	Genesis::Commands::Repo::_repo_init_validate();
+	my $result7 = Genesis::Commands::Repo::_repo_init_execute();
+
+	ok(-d "$basedir7/my-boshen/.genesis", "directory uses custom name, not kit name");
+	ok(!-e "$basedir7/simple", "default dev-kit name directory not created");
+	is($result7->{name}, 'my-boshen', "result name matches custom name");
+	my $cfg7 = slurp("$basedir7/my-boshen/.genesis/config");
+	like($cfg7, qr/deployment_type: my-boshen/, "config deployment_type uses custom name");
+	popd;
+
+	# Test 8: --link-dev-kit creates symlink
+	my $basedir8 = workdir('repo-init-test-8');
+	my $devkit_dir = workdir('repo-init-test-8-devkit');
+	mkdir_or_fail("$devkit_dir/hooks");
+	mkfile_or_fail("$devkit_dir/kit.yml", "name: testkit\nversion: 0.0.1\n");
+	pushd($basedir8);
+
+	prepare_command('repo-init', '-l', $devkit_dir, '--no-sub', '--skip-vault', 'my-devkit');
+	build_command_environment;
+Genesis::Commands::Repo::_repo_init_validate();
+	my $result8 = Genesis::Commands::Repo::_repo_init_execute();
+
+	ok(-d "$basedir8/my-devkit/.genesis", ".genesis created for linked dev kit");
+	ok(-l "$basedir8/my-devkit/dev", "dev is a symlink");
+	is(Cwd::abs_path(readlink("$basedir8/my-devkit/dev")), Cwd::abs_path($devkit_dir), "dev symlink points to correct target");
+	like($result8->{kit_desc}, qr/linked.*kit/i, "result kit_desc mentions linked kit");
+	popd;
+
+	# Test 9: Auto-detect git repo → subdirectory mode (no --sub flag)
+	my $basedir9a = workdir('repo-init-test-9a');
+	pushd($basedir9a);
+	run('git init 2>/dev/null');
+
+	prepare_command('repo-init', '-l', $devkit, '--skip-vault', 'bosh');
+	build_command_environment;
+	Genesis::Commands::Repo::_repo_init_validate();
+	my $result9a = Genesis::Commands::Repo::_repo_init_execute();
+
+	ok(!-e "$basedir9a/bosh/.git", "auto-detected git repo: no .git created");
+	ok($result9a->{submodule}, "auto-detected git repo: result submodule is true");
+	popd;
+
+	# Test 10: Outside git repo without --sub → standalone with .git
+	my $basedir10 = workdir('repo-init-test-10');
+	pushd($basedir10);
+	# Do NOT run git init — this is not a git repo
+
+	prepare_command('repo-init', '-l', $devkit, '--skip-vault', 'bosh');
+	build_command_environment;
+	Genesis::Commands::Repo::_repo_init_validate();
+	my $result10 = Genesis::Commands::Repo::_repo_init_execute();
+
+	ok(-d "$basedir10/bosh/.git", "outside git repo: .git created");
+	ok(!$result10->{submodule}, "outside git repo: result submodule is false");
+	popd;
+
+	# Test 11: Config values are correct (using kit tarball)
+	my $basedir11 = workdir('repo-init-test-11');
+	pushd($basedir11);
+
+	prepare_command('repo-init', '-k', $kit_tarball, '--no-sub', '--skip-vault', 'my-cf');
+	build_command_environment;
+	Genesis::Commands::Repo::_repo_init_validate();
+	my $result11 = Genesis::Commands::Repo::_repo_init_execute();
+
+	my $cfg11 = slurp("$basedir11/my-cf/.genesis/config");
+	like($cfg11, qr/deployment_type: my-cf/, "config has deployment_type: my-cf");
+	like($cfg11, qr/version: 2/, "config has version: 2");
+	like($cfg11, qr/creator_version: 3\.2\.0-rc2/, "config has correct creator_version");
+	like($cfg11, qr/minimum_version: 3\.2\.0-rc2/, "config has minimum_version");
+	like($cfg11, qr/manifest_store: exodus/, "config has manifest_store: exodus");
+	unlike($cfg11, qr/secrets_provider/, "config has no secrets_provider when skip-vault");
+	unlike($cfg11, qr/kit_provider/, "config has no kit_provider (using default genesis-community)");
+	popd;
+
+	# Test 12: --ci-provider concourse writes config and creates ci dir
+	my $basedir12 = workdir('repo-init-test-12');
+	pushd($basedir12);
+
+	prepare_command('repo-init', '-l', $devkit, '--no-sub', '--skip-vault', '--ci-provider', 'concourse', 'bosh');
+	build_command_environment;
+	Genesis::Commands::Repo::_repo_init_validate();
+	my $result12 = Genesis::Commands::Repo::_repo_init_execute();
+
+	my $cfg12 = slurp("$basedir12/bosh/.genesis/config");
+	like($cfg12, qr/ci:/, "concourse: config has ci: section");
+	like($cfg12, qr/type: concourse/, "concourse: ci.provider.type set");
+	like($cfg12, qr/enabled: true/, "concourse: ci.enabled is true");
+	like($cfg12, qr/name: bosh/, "concourse: ci.pipeline.name matches deployment type");
+	ok(-d "$basedir12/bosh/.genesis/ci", "concourse: .genesis/ci/ directory created");
+	ok(-d "$basedir12/bosh/.genesis/bin", "concourse: genesis binary embedded for pipeline");
+	is($result12->{ci_provider}, 'concourse', "concourse: result ci_provider correct");
+	popd;
+
+	# Test 13: --ci-provider manual
+	my $basedir13 = workdir('repo-init-test-13');
+	pushd($basedir13);
+
+	prepare_command('repo-init', '-k', $kit_tarball, '--no-sub', '--skip-vault', '--ci-provider', 'manual', 'my-cf');
+	build_command_environment;
+	Genesis::Commands::Repo::_repo_init_validate();
+	my $result13 = Genesis::Commands::Repo::_repo_init_execute();
+
+	my $cfg13 = slurp("$basedir13/my-cf/.genesis/config");
+	like($cfg13, qr/type: manual/, "manual: ci.provider.type set");
+	ok(-d "$basedir13/my-cf/.genesis/ci", "manual: .genesis/ci/ directory created");
+	is($result13->{ci_provider}, 'manual', "manual: result ci_provider correct");
+	popd;
+
+	# Test 14: --ci-provider github-actions
+	my $basedir14 = workdir('repo-init-test-14');
+	pushd($basedir14);
+
+	prepare_command('repo-init', '-l', $devkit, '--no-sub', '--skip-vault', '--ci-provider', 'github-actions', 'bosh');
+	build_command_environment;
+	Genesis::Commands::Repo::_repo_init_validate();
+	my $result14 = Genesis::Commands::Repo::_repo_init_execute();
+
+	my $cfg14 = slurp("$basedir14/bosh/.genesis/config");
+	like($cfg14, qr/type: github-actions/, "github-actions: ci.provider.type set");
+	is($result14->{ci_provider}, 'github-actions', "github-actions: result ci_provider correct");
+	popd;
+
+	# Test 15: No --ci-provider → no ci: in config, no .genesis/ci/
+	my $basedir15 = workdir('repo-init-test-15');
+	pushd($basedir15);
+
+	prepare_command('repo-init', '-l', $devkit, '--no-sub', '--skip-vault', 'bosh');
+	build_command_environment;
+	Genesis::Commands::Repo::_repo_init_validate();
+	my $result15 = Genesis::Commands::Repo::_repo_init_execute();
+
+	my $cfg15 = slurp("$basedir15/bosh/.genesis/config");
+	unlike($cfg15, qr/^ci:/m, "no-provider: config has no ci: section");
+	ok(!-d "$basedir15/bosh/.genesis/ci", "no-provider: no .genesis/ci/ directory");
+	ok(!$result15->{ci_provider}, "no-provider: result ci_provider is undef");
+	popd;
+};
+
 done_testing;
diff --git a/t/unit-tests/genesis_ci_pipeline_descriptor-auto-update.t b/t/unit-tests/genesis_ci_pipeline_descriptor-auto-update.t
new file mode 100644
index 00000000..e56ecbb9
--- /dev/null
+++ b/t/unit-tests/genesis_ci_pipeline_descriptor-auto-update.t
@@ -0,0 +1,520 @@
+#!/usr/bin/env perl
+use strict;
+use warnings;
+
+use lib 't';
+use lib 'lib';
+use Test::More;
+use Test::Deep;
+
+$ENV{GENESIS_TESTING} = 'yes';
+$ENV{GENESIS_LIB}   ||= 'lib';
+
+use_ok 'Genesis::CI::Compiler::AST';
+use_ok 'Genesis::CI::Compiler::ASTBuilder';
+use_ok 'Genesis::CI::Compiler::PipelineDescriptor';
+
+# =========================================================================
+# Helpers
+# =========================================================================
+
+sub _ast_for {
+	my (%o) = @_;
+
+	my %config = (
+		task     => { image => 'genesiscommunity/concourse', version => 'latest' },
+		registry => {},
+	);
+	$config{auto_update} = $o{auto_update} if $o{auto_update};
+
+	my %integrations = (
+		source_control => {
+			provider       => 'github',
+			repository     => 'org/repo',
+			default_branch => $o{control_branch} || 'main',
+			($o{sc_auth} ? (auth => $o{sc_auth}) : ()),
+		},
+		vault => { url => 'https://vault.example.com' },
+	);
+
+	my $env = 'sandbox';
+	return Genesis::CI::Compiler::AST->new(
+		metadata     => { name => 'test-pipeline', deployment_type => 'deployment' },
+		branches     => { control => $o{control_branch} || 'main' },
+		integrations => \%integrations,
+		targets      => {
+			$env => {
+				type       => 'bosh-director',
+				connection => {
+					url     => 'https://bosh.example.com:25555',
+					ca_cert => 'ca',
+					auth    => { client_id => 'admin', client_secret => 'secret' },
+				},
+			},
+		},
+		workflows => {
+			default => {
+				name  => 'default',
+				type  => 'deployment',
+				graph => {
+					nodes => {
+						$env => {
+							alias => $env, stage_name => $env, genesis_env => $env,
+							auto => 0, type => 'deployment', require_pr => 0,
+							manual => 0, redeploy => '', redeploy_cron_start => '',
+							redeploy_cron_stop => '', status_signal => '',
+							signal_prefix => '', bosh_parent => '', bosh_upgrade_lock => 1,
+						},
+					},
+					edges => [],
+				},
+			},
+		},
+		configuration => \%config,
+	);
+}
+
+# Run AST through ASTBuilder normalization path (multi-file)
+sub _ast_via_builder {
+	my (%o) = @_;
+
+	require Genesis::CI::Compiler::ASTBuilder;
+
+	my $au_raw = $o{auto_update};
+	my $parsed = {
+		_source_format => 'multi-file',
+		integrations   => {
+			source_control => {
+				provider       => 'github',
+				repository     => 'org/repo',
+				default_branch => 'main',
+			},
+			vault => { url => 'https://vault.example.com' },
+		},
+		pipeline => {
+			configuration => {
+				task         => { image => 'genesiscommunity/concourse', version => 'latest' },
+				registry     => {},
+				auto_update  => $au_raw,
+			},
+		},
+		targets => {},
+	};
+
+	my $builder = Genesis::CI::Compiler::ASTBuilder->new();
+	return $builder->build($parsed, {});
+}
+
+sub _describe {
+	my ($ast) = @_;
+	Genesis::CI::Compiler::PipelineDescriptor->new(ast => $ast)->describe();
+}
+
+sub _find_job {
+	my ($pipeline, $name) = @_;
+	my ($j) = grep { $_->{name} eq $name } @{$pipeline->{jobs}};
+	return $j;
+}
+
+sub _find_resource {
+	my ($pipeline, $name) = @_;
+	my ($r) = grep { $_->{name} eq $name } @{$pipeline->{resources}};
+	return $r;
+}
+
+sub _find_group {
+	my ($pipeline, $name) = @_;
+	my ($g) = grep { $_->{name} eq $name } @{$pipeline->{groups}};
+	return $g;
+}
+
+sub _plan_tasks {
+	my ($job) = @_;
+	return grep { ref $_ eq 'HASH' && $_->{task} } @{$job->{plan} || []};
+}
+
+sub _plan_puts {
+	my ($job) = @_;
+	return grep { ref $_ eq 'HASH' && $_->{put} } @{$job->{plan} || []};
+}
+
+sub _parallel_gets {
+	my ($job) = @_;
+	my ($step) = grep { ref $_ eq 'HASH' && $_->{in_parallel} } @{$job->{plan} || []};
+	return $step ? @{$step->{in_parallel}} : ();
+}
+
+sub _task_params {
+	my ($job, $task_name) = @_;
+	my ($t) = grep { ref $_ eq 'HASH' && ($_->{task} || '') eq $task_name } @{$job->{plan}};
+	return $t ? %{($t->{config} || {})->{params} || {}} : ();
+}
+
+# =========================================================================
+# 1. Opt-out: no auto_update or enabled: false → no job emitted
+# =========================================================================
+subtest 'No auto_update config: no update-genesis-assets job' => sub {
+	my $ast = _ast_for();
+	my $pl  = _describe($ast);
+
+	ok(!_find_job($pl, 'update-genesis-assets'), 'no job without auto_update');
+	ok(!_find_resource($pl, 'kit-release'),      'no kit-release without auto_update');
+	ok(!_find_resource($pl, 'genesis-release'),  'no genesis-release without auto_update');
+	ok(!_find_group($pl, 'genesis-updates'),     'no genesis-updates group');
+};
+
+subtest 'enabled: false suppresses emission' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled => 0,
+		kit     => 'cf',
+		org     => 'genesis-community',
+		file    => 'lm.yml',
+	});
+	my $pl = _describe($ast);
+
+	ok(!_find_job($pl, 'update-genesis-assets'), 'no job when enabled: false');
+};
+
+# =========================================================================
+# 2. Basic emission: enabled: true emits job + resources + group
+# =========================================================================
+subtest 'enabled: true emits update-genesis-assets job' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled => 1,
+		kit     => 'cf',
+		org     => 'genesis-community',
+		file    => 'lm.yml',
+	});
+	my $pl = _describe($ast);
+
+	ok(_find_job($pl,      'update-genesis-assets'), 'job emitted');
+	ok(_find_resource($pl, 'kit-release'),           'kit-release resource emitted');
+	ok(_find_resource($pl, 'genesis-release'),       'genesis-release resource emitted');
+	ok(_find_group($pl,    'genesis-updates'),       'genesis-updates group emitted');
+};
+
+subtest 'genesis-updates group contains update-genesis-assets' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+	});
+	my $g = _find_group(_describe($ast), 'genesis-updates');
+	cmp_deeply($g->{jobs}, ['update-genesis-assets'], 'group lists exactly the update job');
+};
+
+# =========================================================================
+# 3. Kit-release resource config
+# =========================================================================
+subtest 'kit-release resource points at correct GitHub repo' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+	});
+	my $r = _find_resource(_describe($ast), 'kit-release');
+
+	is($r->{type},          'github-release',        'type is github-release');
+	is($r->{source}{user},  'genesis-community',     'org correct');
+	is($r->{source}{repository}, 'cf-genesis-kit',   'repo is kit-genesis-kit');
+};
+
+subtest 'kit-release check_every defaults to 24h' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+	});
+	my $r = _find_resource(_describe($ast), 'kit-release');
+	is($r->{check_every}, '24h', 'default check period');
+};
+
+subtest 'kit-release check_every uses configured period' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml', period => '12h',
+	});
+	my $r = _find_resource(_describe($ast), 'kit-release');
+	is($r->{check_every}, '12h', 'custom period respected');
+};
+
+subtest 'kit-release auth_token passthrough' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled        => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+		kit_auth_token => { secret_ref => 'github-kit-token' },
+	});
+	my $r = _find_resource(_describe($ast), 'kit-release');
+	is($r->{source}{access_token}, '((github-kit-token))', 'kit_auth_token unwrapped');
+};
+
+subtest 'kit-release falls back to auth_token when kit_auth_token absent' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled    => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+		auth_token => { secret_ref => 'github-token' },
+	});
+	my $r = _find_resource(_describe($ast), 'kit-release');
+	is($r->{source}{access_token}, '((github-token))', 'auth_token fallback');
+};
+
+subtest 'kit-release api_url for GitHub Enterprise' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+		api_url => 'https://api.github.example.com',
+	});
+	my $r = _find_resource(_describe($ast), 'kit-release');
+	is($r->{source}{github_api_url}, 'https://api.github.example.com', 'api_url set');
+};
+
+# =========================================================================
+# 4. Genesis-release resource config
+# =========================================================================
+subtest 'genesis-release resource always points at genesis-community/genesis' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+	});
+	my $r = _find_resource(_describe($ast), 'genesis-release');
+
+	is($r->{type},               'github-release',    'type is github-release');
+	is($r->{source}{user},       'genesis-community', 'user is genesis-community');
+	is($r->{source}{repository}, 'genesis',           'repo is genesis');
+};
+
+subtest 'genesis-release genesis_auth_token passthrough' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled              => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+		genesis_auth_token   => { secret_ref => 'genesis-token' },
+	});
+	my $r = _find_resource(_describe($ast), 'genesis-release');
+	is($r->{source}{access_token}, '((genesis-token))', 'genesis_auth_token unwrapped');
+};
+
+# =========================================================================
+# 5. Job plan structure: gets trigger correctly
+# =========================================================================
+subtest 'Both enabled: both resources trigger' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+	});
+	my $job   = _find_job(_describe($ast), 'update-genesis-assets');
+	my @gets  = _parallel_gets($job);
+
+	my ($kit_get) = grep { ($_->{get} || '') eq 'kit-release'     } @gets;
+	my ($gen_get) = grep { ($_->{get} || '') eq 'genesis-release' } @gets;
+
+	ok($kit_get->{trigger}, 'kit-release triggers');
+	ok($gen_get->{trigger}, 'genesis-release triggers');
+};
+
+# =========================================================================
+# 6. update_genesis: false — skip genesis tasks and resource
+# =========================================================================
+subtest 'update_genesis: false omits genesis-release resource' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled        => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+		update_genesis => 0,
+	});
+	my $pl = _describe($ast);
+
+	ok(!_find_resource($pl, 'genesis-release'), 'no genesis-release resource');
+	ok(_find_resource($pl,  'kit-release'),     'kit-release still present');
+};
+
+subtest 'update_genesis: false omits update-genesis task from job' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled        => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+		update_genesis => 0,
+	});
+	my $job   = _find_job(_describe($ast), 'update-genesis-assets');
+	my @tasks = _plan_tasks($job);
+
+	ok(!grep({ $_->{task} eq 'update-genesis' } @tasks), 'no update-genesis task');
+	ok(grep({ $_->{task} eq 'list-kits'       } @tasks), 'list-kits still present');
+	ok(grep({ $_->{task} eq 'fetch-kit'       } @tasks), 'fetch-kit still present');
+};
+
+subtest 'update_genesis: false omits genesis-release get' => sub {
+	my $ast  = _ast_for(auto_update => {
+		enabled => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+		update_genesis => 0,
+	});
+	my $job  = _find_job(_describe($ast), 'update-genesis-assets');
+	my @gets = _parallel_gets($job);
+
+	ok(!grep({ ($_->{get} || '') eq 'genesis-release' } @gets),
+		'no genesis-release get');
+};
+
+# =========================================================================
+# 7. update_kit: false — skip kit tasks and resource
+# =========================================================================
+subtest 'update_kit: false omits kit-release resource' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled    => 1, kit => 'cf', org => 'genesis-community',
+		update_kit => 0,
+	});
+	my $pl = _describe($ast);
+
+	ok(!_find_resource($pl, 'kit-release'),    'no kit-release resource');
+	ok(_find_resource($pl,  'genesis-release'), 'genesis-release still present');
+};
+
+subtest 'update_kit: false omits list-kits and fetch-kit tasks' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled => 1, kit => 'cf', org => 'genesis-community', update_kit => 0,
+	});
+	my $job   = _find_job(_describe($ast), 'update-genesis-assets');
+	my @tasks = _plan_tasks($job);
+
+	ok(!grep({ $_->{task} eq 'list-kits'  } @tasks), 'no list-kits task');
+	ok(!grep({ $_->{task} eq 'fetch-kit'  } @tasks), 'no fetch-kit task');
+	ok(grep({ $_->{task} eq 'update-genesis' } @tasks), 'update-genesis still present');
+};
+
+# =========================================================================
+# 8. commit_label / label param
+# =========================================================================
+subtest 'commit_label maps to CI_LABEL in update-genesis and fetch-kit tasks' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled      => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+		commit_label => '[pipeline]',
+	});
+	my $job = _find_job(_describe($ast), 'update-genesis-assets');
+	my %gp  = _task_params($job, 'update-genesis');
+	my %fp  = _task_params($job, 'fetch-kit');
+
+	is($gp{CI_LABEL}, '[pipeline]', 'CI_LABEL in update-genesis');
+	is($fp{CI_LABEL}, '[pipeline]', 'CI_LABEL in fetch-kit');
+};
+
+subtest 'label key (legacy) maps to CI_LABEL' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+		label   => 'concourse',
+	});
+	my $job = _find_job(_describe($ast), 'update-genesis-assets');
+	my %gp  = _task_params($job, 'update-genesis');
+	is($gp{CI_LABEL}, 'concourse', 'label key used directly');
+};
+
+subtest 'CI_LABEL defaults to concourse when neither commit_label nor label set' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+	});
+	my $job = _find_job(_describe($ast), 'update-genesis-assets');
+	my %gp  = _task_params($job, 'update-genesis');
+	is($gp{CI_LABEL}, 'concourse', 'default CI_LABEL');
+};
+
+# =========================================================================
+# 9. fetch-kit task: KIT_VERSION_FILE from file / kit_version_file
+# =========================================================================
+subtest 'fetch-kit KIT_VERSION_FILE from file key' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+	});
+	my $job = _find_job(_describe($ast), 'update-genesis-assets');
+	my %p   = _task_params($job, 'fetch-kit');
+	is($p{KIT_VERSION_FILE}, 'lm.yml', 'KIT_VERSION_FILE set from file key');
+};
+
+# =========================================================================
+# 10. target_branch: pushes to control branch by default
+# =========================================================================
+subtest 'Default push uses git resource (control branch)' => sub {
+	my $ast = _ast_for(auto_update => {
+		enabled => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+	});
+	my $job = _find_job(_describe($ast), 'update-genesis-assets');
+	my ($put) = _plan_puts($job);
+
+	is($put->{put},                  'git', 'puts to git resource');
+	is($put->{params}{repository},   'git', 'repository param is git');
+	ok($put->{params}{rebase},       'rebase: true set');
+	ok(!_find_resource(_describe($ast), 'git-autoupdate'), 'no git-autoupdate resource');
+};
+
+subtest 'target_branch different from control branch emits git-autoupdate resource' => sub {
+	my $ast = _ast_for(
+		control_branch => 'main',
+		auto_update    => {
+			enabled       => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+			target_branch => 'auto-commits',
+		},
+	);
+	my $pl  = _describe($ast);
+	my $r   = _find_resource($pl, 'git-autoupdate');
+
+	ok($r, 'git-autoupdate resource emitted');
+	is($r->{type},           'git',           'type is git');
+	is($r->{source}{branch}, 'auto-commits',  'branch is target_branch');
+};
+
+subtest 'target_branch: put uses git-autoupdate resource' => sub {
+	my $ast = _ast_for(
+		control_branch => 'main',
+		auto_update    => {
+			enabled       => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+			target_branch => 'auto-commits',
+		},
+	);
+	my $job = _find_job(_describe($ast), 'update-genesis-assets');
+	my ($put) = _plan_puts($job);
+
+	is($put->{put},                'git-autoupdate', 'puts to git-autoupdate');
+	is($put->{params}{repository}, 'git-autoupdate', 'repository param matches');
+};
+
+subtest 'target_branch equal to control branch: no git-autoupdate resource' => sub {
+	my $ast = _ast_for(
+		control_branch => 'main',
+		auto_update    => {
+			enabled       => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+			target_branch => 'main',
+		},
+	);
+	ok(!_find_resource(_describe($ast), 'git-autoupdate'), 'no extra resource needed');
+};
+
+# =========================================================================
+# 11. ASTBuilder normalization: v2 keys mapped correctly
+# =========================================================================
+subtest 'ASTBuilder: kit_version_file normalized to file' => sub {
+	my $ast = _ast_via_builder(auto_update => {
+		enabled          => 1,
+		kit              => 'cf',
+		org              => 'genesis-community',
+		kit_version_file => 'lm.yml',
+	});
+	my $au = ($ast->configuration || {})->{auto_update};
+	is($au->{file},    'lm.yml', 'file set from kit_version_file');
+	is($au->{enabled}, 1,        'enabled preserved');
+};
+
+subtest 'ASTBuilder: commit_label normalized to label' => sub {
+	my $ast = _ast_via_builder(auto_update => {
+		enabled      => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+		commit_label => '[pipeline]',
+	});
+	my $au = ($ast->configuration || {})->{auto_update};
+	is($au->{label}, '[pipeline]', 'label set from commit_label');
+};
+
+subtest 'ASTBuilder: enabled defaults to 1 when file is set (legacy compat)' => sub {
+	my $ast = _ast_via_builder(auto_update => {
+		kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+	});
+	my $au = ($ast->configuration || {})->{auto_update};
+	is($au->{enabled}, 1, 'enabled auto-set when file present');
+};
+
+subtest 'ASTBuilder: enabled defaults to 0 when no file and no explicit enabled' => sub {
+	my $ast = _ast_via_builder(auto_update => {
+		kit => 'cf', org => 'genesis-community',
+	});
+	my $au = ($ast->configuration || {})->{auto_update};
+	is($au->{enabled}, 0, 'enabled defaults to 0 without file');
+};
+
+subtest 'ASTBuilder: update_genesis and update_kit default to 1' => sub {
+	my $ast = _ast_via_builder(auto_update => {
+		enabled => 1, kit => 'cf', org => 'genesis-community', file => 'lm.yml',
+	});
+	my $au = ($ast->configuration || {})->{auto_update};
+	is($au->{update_genesis}, 1, 'update_genesis defaults to 1');
+	is($au->{update_kit},     1, 'update_kit defaults to 1');
+};
+
+done_testing;
diff --git a/t/unit-tests/genesis_ci_pipeline_descriptor-bosh-configs.t b/t/unit-tests/genesis_ci_pipeline_descriptor-bosh-configs.t
new file mode 100644
index 00000000..f4b4f8dd
--- /dev/null
+++ b/t/unit-tests/genesis_ci_pipeline_descriptor-bosh-configs.t
@@ -0,0 +1,423 @@
+#!/usr/bin/env perl
+use strict;
+use warnings;
+
+use lib 't';
+use lib 'lib';
+use Test::More;
+use Test::Deep;
+
+$ENV{GENESIS_TESTING} = 'yes';
+$ENV{GENESIS_LIB}   ||= 'lib';
+
+use_ok 'Genesis::CI::Compiler::AST';
+use_ok 'Genesis::CI::Compiler::PipelineDescriptor';
+
+# =========================================================================
+# Helpers
+# =========================================================================
+
+sub _ast_for {
+	my (%o) = @_;
+
+	my $env   = $o{env}   || 'sandbox';
+	my $alias = $o{alias} || $env;
+
+	my %integrations = (
+		source_control => { provider => 'github', repository => 'org/repo' },
+		vault          => { url => 'https://vault.example.com' },
+	);
+	$integrations{slack} = $o{slack} if $o{slack};
+
+	my %config = (
+		task     => { image => 'genesiscommunity/concourse', version => 'latest' },
+		registry => {},
+	);
+	$config{track_bosh_configs} = $o{track_bosh_configs}
+		if exists $o{track_bosh_configs};
+
+	my %node = (
+		alias               => $alias,
+		stage_name          => $env,
+		genesis_env         => $env,
+		auto                => $o{auto} // 0,
+		type                => 'deployment',
+		require_pr          => 0,
+		manual              => 0,
+		redeploy            => '',
+		redeploy_cron_start => '',
+		redeploy_cron_stop  => '',
+		status_signal       => '',
+		signal_prefix       => '',
+		bosh_parent         => '',
+		bosh_upgrade_lock   => 1,
+	);
+	$node{track_bosh_configs} = $o{env_track_bosh_configs}
+		if exists $o{env_track_bosh_configs};
+
+	return Genesis::CI::Compiler::AST->new(
+		metadata     => { name => 'test-pipeline', deployment_type => 'deployment' },
+		branches     => { control => 'main' },
+		integrations => \%integrations,
+		targets      => {
+			$env => {
+				type       => 'bosh-director',
+				connection => {
+					url     => 'https://bosh.example.com:25555',
+					ca_cert => 'fake-ca',
+					auth    => { client_id => 'admin', client_secret => 'secret' },
+				},
+			},
+		},
+		workflows => {
+			default => {
+				name  => 'default',
+				type  => 'deployment',
+				graph => {
+					nodes => { $env => \%node },
+					edges => $o{edges} || [],
+				},
+			},
+		},
+		configuration => \%config,
+	);
+}
+
+# Build AST with two envs, the second triggered by the first
+sub _two_env_ast {
+	my (%o) = @_;
+	my %config = (
+		task     => { image => 'genesiscommunity/concourse', version => 'latest' },
+		registry => {},
+	);
+	$config{track_bosh_configs} = $o{track_bosh_configs}
+		if exists $o{track_bosh_configs};
+
+	my %nodes = (
+		sandbox => {
+			alias => 'sandbox', stage_name => 'sandbox', genesis_env => 'sandbox',
+			auto => 1, type => 'deployment', require_pr => 0,
+			manual => 0, redeploy => '', redeploy_cron_start => '',
+			redeploy_cron_stop => '', status_signal => '',
+			signal_prefix => '', bosh_parent => '', bosh_upgrade_lock => 1,
+		},
+		prod => {
+			alias => 'prod', stage_name => 'prod', genesis_env => 'prod',
+			auto => 0, type => 'deployment', require_pr => 0,
+			manual => 0, redeploy => '', redeploy_cron_start => '',
+			redeploy_cron_stop => '', status_signal => '',
+			signal_prefix => '', bosh_parent => '', bosh_upgrade_lock => 1,
+		},
+	);
+	if (exists $o{prod_track_bosh_configs}) {
+		$nodes{prod}{track_bosh_configs} = $o{prod_track_bosh_configs};
+	}
+
+	my %targets = map { $_ => {
+		type => 'bosh-director',
+		connection => { url => "https://$_.example.com:25555", ca_cert => 'ca',
+		                auth => { client_id => 'admin', client_secret => 'secret' } },
+	}} qw(sandbox prod);
+
+	return Genesis::CI::Compiler::AST->new(
+		metadata     => { name => 'test-pipeline', deployment_type => 'deployment' },
+		branches     => { control => 'main' },
+		integrations => {
+			source_control => { provider => 'github', repository => 'org/repo' },
+			vault          => { url => 'https://vault.example.com' },
+		},
+		targets      => \%targets,
+		workflows    => {
+			default => {
+				name  => 'default',
+				type  => 'deployment',
+				graph => {
+					nodes => \%nodes,
+					edges => [{ from => 'sandbox', to => 'prod' }],
+				},
+			},
+		},
+		configuration => \%config,
+	);
+}
+
+sub _describe {
+	my ($ast) = @_;
+	Genesis::CI::Compiler::PipelineDescriptor->new(ast => $ast)->describe();
+}
+
+sub _find_resource {
+	my ($pipeline, $name) = @_;
+	my ($r) = grep { $_->{name} eq $name } @{$pipeline->{resources}};
+	return $r;
+}
+
+sub _find_job {
+	my ($pipeline, $name) = @_;
+	my ($j) = grep { $_->{name} eq $name } @{$pipeline->{jobs}};
+	return $j;
+}
+
+# Return get steps from the parallel block of a job's plan.
+# Deploy jobs wrap everything in plan[0]{do}; notify jobs use a flat plan array.
+sub _job_gets {
+	my ($pipeline, $job_name) = @_;
+	my $job = _find_job($pipeline, $job_name) or return ();
+	my $plan  = $job->{plan} || [];
+	my $steps = ($plan->[0] && $plan->[0]{do}) ? $plan->[0]{do} : $plan;
+	my ($parallel) = grep { ref $_ eq 'HASH' && $_->{in_parallel} } @$steps;
+	return $parallel ? @{$parallel->{in_parallel}} : ();
+}
+
+# Return get names from a job's parallel block
+sub _get_names {
+	my ($pipeline, $job_name) = @_;
+	return map { ref $_ eq 'HASH' && $_->{get} ? $_->{get} : () }
+		_job_gets($pipeline, $job_name);
+}
+
+# =========================================================================
+# AC7 — Opt-in: default off
+# =========================================================================
+subtest 'Default (no track_bosh_configs): no bosh-config resources emitted' => sub {
+	my $pl = _describe(_ast_for());
+
+	ok(!_find_resource($pl, 'sandbox-cloud-config'),
+		'No cloud-config resource by default');
+	ok(!_find_resource($pl, 'sandbox-runtime-config'),
+		'No runtime-config resource by default');
+	ok(!_find_resource($pl, 'sandbox-cpi-config'),
+		'No cpi-config resource by default');
+};
+
+subtest 'track_bosh_configs: false suppresses all resources' => sub {
+	my $pl = _describe(_ast_for(track_bosh_configs => 0));
+
+	ok(!_find_resource($pl, 'sandbox-cloud-config'),   'No cloud-config with false');
+	ok(!_find_resource($pl, 'sandbox-runtime-config'), 'No runtime-config with false');
+};
+
+# =========================================================================
+# AC2 — Concourse emits bosh-config resources when configured
+# =========================================================================
+subtest 'track_bosh_configs: true emits cloud-config and runtime-config' => sub {
+	my $pl = _describe(_ast_for(track_bosh_configs => 1));
+
+	ok(_find_resource($pl, 'sandbox-cloud-config'),   'cloud-config resource emitted');
+	ok(_find_resource($pl, 'sandbox-runtime-config'), 'runtime-config resource emitted');
+	ok(!_find_resource($pl, 'sandbox-cpi-config'),    'cpi-config not emitted for true');
+};
+
+subtest 'track_bosh_configs: [cloud, runtime, cpi] emits all three types' => sub {
+	my $pl = _describe(_ast_for(track_bosh_configs => ['cloud', 'runtime', 'cpi']));
+
+	ok(_find_resource($pl, 'sandbox-cloud-config'),   'cloud-config emitted');
+	ok(_find_resource($pl, 'sandbox-runtime-config'), 'runtime-config emitted');
+	ok(_find_resource($pl, 'sandbox-cpi-config'),     'cpi-config emitted');
+};
+
+# =========================================================================
+# AC3 — Resource connection derived from env's bosh target
+# =========================================================================
+subtest 'bosh-config resource source derived from env target connection' => sub {
+	my $pl = _describe(_ast_for(track_bosh_configs => 1));
+	my $r  = _find_resource($pl, 'sandbox-cloud-config');
+
+	ok($r, 'cloud-config resource present');
+	is($r->{type}, 'bosh-config', 'type is bosh-config');
+	is($r->{source}{target}, 'https://bosh.example.com:25555', 'target URL correct');
+	is($r->{source}{client}, 'admin', 'client from auth.client_id');
+	is($r->{source}{client_secret}, 'secret', 'client_secret from auth.client_secret');
+	is($r->{source}{ca_cert}, 'fake-ca', 'ca_cert from connection.ca_cert');
+	is($r->{source}{config}, 'cloud', 'config type is cloud');
+	ok($r->{source}{all}, 'all: true set');
+};
+
+subtest 'runtime-config resource source correct' => sub {
+	my $pl = _describe(_ast_for(track_bosh_configs => 1));
+	my $r  = _find_resource($pl, 'sandbox-runtime-config');
+
+	is($r->{source}{config}, 'runtime', 'config type is runtime');
+	is($r->{source}{target}, 'https://bosh.example.com:25555', 'target correct');
+};
+
+subtest 'cpi-config resource source correct' => sub {
+	my $pl = _describe(_ast_for(track_bosh_configs => ['cpi']));
+	my $r  = _find_resource($pl, 'sandbox-cpi-config');
+
+	ok($r, 'cpi-config resource present');
+	is($r->{source}{config}, 'cpi', 'config type is cpi');
+	is($r->{type}, 'bosh-config', 'resource type is bosh-config');
+};
+
+# =========================================================================
+# AC4 — Subset selection
+# =========================================================================
+subtest 'track_bosh_configs: [cloud] emits only cloud-config' => sub {
+	my $pl = _describe(_ast_for(track_bosh_configs => ['cloud']));
+
+	ok(_find_resource($pl, 'sandbox-cloud-config'),    'cloud-config emitted');
+	ok(!_find_resource($pl, 'sandbox-runtime-config'), 'runtime-config NOT emitted');
+	ok(!_find_resource($pl, 'sandbox-cpi-config'),     'cpi-config NOT emitted');
+};
+
+subtest 'track_bosh_configs: [runtime] emits only runtime-config' => sub {
+	my $pl = _describe(_ast_for(track_bosh_configs => ['runtime']));
+
+	ok(!_find_resource($pl, 'sandbox-cloud-config'),  'cloud-config NOT emitted');
+	ok(_find_resource($pl, 'sandbox-runtime-config'), 'runtime-config emitted');
+	ok(!_find_resource($pl, 'sandbox-cpi-config'),    'cpi-config NOT emitted');
+};
+
+subtest 'track_bosh_configs: [cpi] emits only cpi-config' => sub {
+	my $pl = _describe(_ast_for(track_bosh_configs => ['cpi']));
+
+	ok(!_find_resource($pl, 'sandbox-cloud-config'),   'cloud-config NOT emitted');
+	ok(!_find_resource($pl, 'sandbox-runtime-config'), 'runtime-config NOT emitted');
+	ok(_find_resource($pl, 'sandbox-cpi-config'),      'cpi-config emitted');
+};
+
+subtest 'track_bosh_configs: [cloud, cpi] emits cloud and cpi but not runtime' => sub {
+	my $pl = _describe(_ast_for(track_bosh_configs => ['cloud', 'cpi']));
+
+	ok(_find_resource($pl, 'sandbox-cloud-config'),    'cloud-config emitted');
+	ok(!_find_resource($pl, 'sandbox-runtime-config'), 'runtime-config NOT emitted');
+	ok(_find_resource($pl, 'sandbox-cpi-config'),      'cpi-config emitted');
+};
+
+# =========================================================================
+# AC5 — Per-env override
+# =========================================================================
+subtest 'Per-env track_bosh_configs overrides global default (off)' => sub {
+	my $ast = _ast_for(
+		env_track_bosh_configs => ['cloud'],
+	);
+	my $pl = _describe($ast);
+
+	ok(_find_resource($pl, 'sandbox-cloud-config'),    'cloud-config emitted via per-env');
+	ok(!_find_resource($pl, 'sandbox-runtime-config'), 'runtime-config not in per-env list');
+};
+
+subtest 'Per-env false overrides global true' => sub {
+	my $ast = _two_env_ast(
+		track_bosh_configs      => 1,
+		prod_track_bosh_configs => 0,
+	);
+	my $pl = _describe($ast);
+
+	ok(_find_resource($pl, 'sandbox-cloud-config'),   'sandbox gets cloud-config (global)');
+	ok(!_find_resource($pl, 'prod-cloud-config'),     'prod suppressed by per-env false');
+};
+
+subtest 'Per-env superset overrides global subset' => sub {
+	my $ast = _two_env_ast(
+		track_bosh_configs      => ['cloud'],
+		prod_track_bosh_configs => ['cloud', 'runtime', 'cpi'],
+	);
+	my $pl = _describe($ast);
+
+	ok(_find_resource($pl, 'sandbox-cloud-config'),    'sandbox gets cloud (global)');
+	ok(!_find_resource($pl, 'sandbox-runtime-config'), 'sandbox no runtime (global)');
+	ok(_find_resource($pl, 'prod-cloud-config'),       'prod gets cloud');
+	ok(_find_resource($pl, 'prod-runtime-config'),     'prod gets runtime');
+	ok(_find_resource($pl, 'prod-cpi-config'),         'prod gets cpi');
+};
+
+# =========================================================================
+# Job get-step wiring
+# =========================================================================
+subtest 'Auto env deploy job: bosh-config gets trigger when configured' => sub {
+	my $pl = _describe(_ast_for(auto => 1, track_bosh_configs => 1));
+	my @names = _get_names($pl, 'sandbox-deployment');
+
+	ok(grep({ $_ eq 'sandbox-cloud-config'   } @names), 'cloud-config get in auto deploy');
+	ok(grep({ $_ eq 'sandbox-runtime-config' } @names), 'runtime-config get in auto deploy');
+};
+
+subtest 'Auto env deploy job: no bosh-config gets when not configured' => sub {
+	my $pl = _describe(_ast_for(auto => 1));
+	my @names = _get_names($pl, 'sandbox-deployment');
+
+	ok(!grep({ $_ eq 'sandbox-cloud-config'   } @names), 'no cloud-config get');
+	ok(!grep({ $_ eq 'sandbox-runtime-config' } @names), 'no runtime-config get');
+};
+
+subtest 'Auto env deploy job: subset [cloud] adds only cloud get' => sub {
+	my $pl = _describe(_ast_for(auto => 1, track_bosh_configs => ['cloud']));
+	my @names = _get_names($pl, 'sandbox-deployment');
+
+	ok(grep({ $_ eq 'sandbox-cloud-config' } @names),    'cloud-config get present');
+	ok(!grep({ $_ eq 'sandbox-runtime-config' } @names), 'runtime-config get absent');
+};
+
+my $_slack = { channel => '#deploys', webhook => '((slack-webhook))' };
+
+subtest 'Notify job: bosh-config gets trigger when configured' => sub {
+	my $pl = _describe(_ast_for(track_bosh_configs => 1, slack => $_slack));
+	my @names = _get_names($pl, 'notify-sandbox-deployment-changes');
+
+	ok(grep({ $_ eq 'sandbox-cloud-config'   } @names), 'cloud-config get in notify job');
+	ok(grep({ $_ eq 'sandbox-runtime-config' } @names), 'runtime-config get in notify job');
+};
+
+subtest 'Notify job: no bosh-config gets when not configured' => sub {
+	my $pl = _describe(_ast_for(slack => $_slack));
+	my @names = _get_names($pl, 'notify-sandbox-deployment-changes');
+
+	ok(!grep({ $_ eq 'sandbox-cloud-config'   } @names), 'no cloud-config get in notify');
+	ok(!grep({ $_ eq 'sandbox-runtime-config' } @names), 'no runtime-config get in notify');
+};
+
+subtest 'Notify job: bosh-config gets are triggering' => sub {
+	my $pl = _describe(_ast_for(track_bosh_configs => 1, slack => $_slack));
+	my @gets = _job_gets($pl, 'notify-sandbox-deployment-changes');
+	my ($cc) = grep { ref $_ eq 'HASH' && ($_->{get}||'') eq 'sandbox-cloud-config' } @gets;
+
+	ok($cc, 'cloud-config get found');
+	ok($cc->{trigger}, 'cloud-config get triggers notify job');
+};
+
+# =========================================================================
+# Resource icons
+# =========================================================================
+subtest 'Cloud-config resource has cloud icon' => sub {
+	my $pl = _describe(_ast_for(track_bosh_configs => ['cloud']));
+	my $r  = _find_resource($pl, 'sandbox-cloud-config');
+	is($r->{icon}, 'cloud', 'cloud icon set');
+};
+
+subtest 'Runtime-config resource has run-fast icon' => sub {
+	my $pl = _describe(_ast_for(track_bosh_configs => ['runtime']));
+	my $r  = _find_resource($pl, 'sandbox-runtime-config');
+	is($r->{icon}, 'run-fast', 'run-fast icon set');
+};
+
+subtest 'CPI-config resource has chip icon' => sub {
+	my $pl = _describe(_ast_for(track_bosh_configs => ['cpi']));
+	my $r  = _find_resource($pl, 'sandbox-cpi-config');
+	is($r->{icon}, 'chip', 'chip icon set');
+};
+
+# =========================================================================
+# Multi-env — correct resources per env with independent targets
+# =========================================================================
+subtest 'Two-env pipeline emits per-env bosh-config resources' => sub {
+	my $pl = _describe(_two_env_ast(track_bosh_configs => 1));
+
+	ok(_find_resource($pl, 'sandbox-cloud-config'),   'sandbox-cloud-config emitted');
+	ok(_find_resource($pl, 'sandbox-runtime-config'), 'sandbox-runtime-config emitted');
+	ok(_find_resource($pl, 'prod-cloud-config'),      'prod-cloud-config emitted');
+	ok(_find_resource($pl, 'prod-runtime-config'),    'prod-runtime-config emitted');
+};
+
+subtest 'Two-env: each resource has its own director target' => sub {
+	my $pl = _describe(_two_env_ast(track_bosh_configs => 1));
+
+	my $sb = _find_resource($pl, 'sandbox-cloud-config');
+	my $pr = _find_resource($pl, 'prod-cloud-config');
+
+	is($sb->{source}{target}, 'https://sandbox.example.com:25555', 'sandbox target');
+	is($pr->{source}{target}, 'https://prod.example.com:25555',    'prod target');
+};
+
+done_testing;
diff --git a/t/unit-tests/genesis_ci_pipeline_descriptor-bosh-locks.t b/t/unit-tests/genesis_ci_pipeline_descriptor-bosh-locks.t
new file mode 100644
index 00000000..6ec5a988
--- /dev/null
+++ b/t/unit-tests/genesis_ci_pipeline_descriptor-bosh-locks.t
@@ -0,0 +1,548 @@
+#!/usr/bin/env perl
+use strict;
+use warnings;
+
+use lib 't';
+use lib 'lib';
+use File::Temp qw/tempdir/;
+use Test::More;
+use Test::Deep;
+
+$ENV{GENESIS_TESTING} = 'yes';
+$ENV{GENESIS_LIB}   ||= 'lib';
+
+use_ok 'Genesis::CI::Compiler::AST';
+use_ok 'Genesis::CI::Compiler::ASTBuilder';
+use_ok 'Genesis::CI::Compiler::PipelineDescriptor';
+
+# =========================================================================
+# Helpers
+# =========================================================================
+
+sub _write {
+	my ($path, $content) = @_;
+	open my $fh, '>', $path or die "Cannot write $path: $!";
+	print $fh $content;
+	close $fh;
+}
+
+sub _node {
+	my (%o) = @_;
+	return {
+		alias               => $o{alias}             || $o{env},
+		stage_name          => $o{env},
+		genesis_env         => $o{env},
+		auto                => $o{auto}              // 0,
+		type                => 'deployment',
+		require_pr          => 0,
+		manual              => 0,
+		redeploy            => '',
+		redeploy_cron_start => '',
+		redeploy_cron_stop  => '',
+		status_signal       => '',
+		signal_prefix       => '',
+		bosh_parent         => $o{bosh_parent}       || '',
+		bosh_upgrade_lock   => $o{bosh_upgrade_lock} // 1,
+	};
+}
+
+sub _target {
+	my (%o) = @_;
+	return $o{create_env}
+		? { type => 'bosh-create-env' }
+		: {
+			type       => 'bosh-director',
+			connection => {
+				url     => $o{url} || 'https://bosh.example.com:25555',
+				ca_cert => 'fake-ca',
+				auth    => { client_id => 'admin', client_secret => 'secret' },
+			},
+		};
+}
+
+# Build an AST with one or more envs.
+# envs: arrayref of hashrefs (env, alias, bosh_parent, bosh_upgrade_lock, create_env, url)
+# with_locker: 0/1
+# edges: arrayref of {from, to} hashrefs
+sub _ast {
+	my (%o) = @_;
+
+	my (%nodes, %targets);
+	for my $spec (@{$o{envs}}) {
+		my $env = $spec->{env};
+		$nodes{$env}   = _node(%$spec);
+		$targets{$env} = _target(%$spec);
+	}
+
+	my %integrations = (
+		source_control => { provider => 'github', repository => 'org/repo' },
+		vault          => { url => 'https://vault.example.com' },
+	);
+	if ($o{with_locker}) {
+		$integrations{locker} = {
+			url      => 'https://locker.example.com',
+			username => 'locker-user',
+			password => 'locker-pass',
+		};
+	}
+
+	return Genesis::CI::Compiler::AST->new(
+		metadata     => { name => 'test-pipeline', deployment_type => 'deployment' },
+		branches     => { control => 'main' },
+		integrations => \%integrations,
+		targets      => \%targets,
+		workflows    => {
+			default => {
+				name  => 'default',
+				type  => 'deployment',
+				graph => {
+					nodes => \%nodes,
+					edges => $o{edges} || [],
+				},
+			},
+		},
+		configuration => {
+			task     => { image => 'genesiscommunity/concourse', version => 'latest' },
+			registry => {},
+		},
+	);
+}
+
+sub _describe {
+	my ($ast) = @_;
+	Genesis::CI::Compiler::PipelineDescriptor->new(ast => $ast)->describe();
+}
+
+sub _mermaid {
+	my ($ast) = @_;
+	Genesis::CI::Compiler::PipelineDescriptor->new(ast => $ast)->mermaid();
+}
+
+sub _find_job {
+	my ($pipeline, $name) = @_;
+	my ($j) = grep { $_->{name} eq $name } @{$pipeline->{jobs}};
+	return $j;
+}
+
+sub _find_resource {
+	my ($pipeline, $name) = @_;
+	my ($r) = grep { $_->{name} eq $name } @{$pipeline->{resources}};
+	return $r;
+}
+
+sub _do_block {
+	my ($job) = @_;
+	return ($job->{plan}[0] || {})->{do} || [];
+}
+
+sub _ensure_do {
+	my ($job) = @_;
+	return (($job->{plan}[0] || {})->{ensure} || {})->{do} || [];
+}
+
+# Returns all put steps in a do-block that are locker operations
+sub _lock_puts {
+	my ($do) = @_;
+	return grep {
+		ref $_ eq 'HASH'
+		&& exists $_->{put}
+		&& ref($_->{params}) eq 'HASH'
+		&& exists $_->{params}{lock_op}
+	} @$do;
+}
+
+# =========================================================================
+# 1. Standalone env: per-env bosh-lock uses bosh_lock (URL), deployment-lock uses lock_name
+# =========================================================================
+subtest 'Standalone env: bosh-lock uses bosh_lock URL source' => sub {
+	my $ast      = _ast(
+		envs        => [{ env => 'sandbox', url => 'https://bosh.sb:25555' }],
+		with_locker => 1,
+	);
+	my $pipeline = _describe($ast);
+
+	my $bl = _find_resource($pipeline, 'sandbox-bosh-lock');
+	ok $bl, 'sandbox-bosh-lock resource emitted';
+	is $bl->{type}, 'locker', 'type is locker';
+	like $bl->{source}{bosh_lock}, qr{https://bosh\.sb}, 'source.bosh_lock is BOSH URL';
+	ok !$bl->{source}{lock_name}, 'no lock_name for standalone bosh-lock';
+
+	my $dl = _find_resource($pipeline, 'sandbox-deployment-lock');
+	ok $dl, 'sandbox-deployment-lock resource emitted';
+	like $dl->{source}{lock_name}, qr/sandbox-deployment/, 'deployment-lock uses lock_name';
+};
+
+# =========================================================================
+# 2. Director env: bosh-lock uses lock_name (not bosh_lock URL)
+# =========================================================================
+subtest 'Director env: bosh-lock uses lock_name, not bosh_lock URL' => sub {
+	my $ast = _ast(
+		envs => [
+			{ env => 'bosh-lab',  url => 'https://bosh.lab:25555' },
+			{ env => 'cf-lab',    bosh_parent => 'bosh-lab' },
+		],
+		with_locker => 1,
+	);
+	my $pipeline = _describe($ast);
+
+	my $bl = _find_resource($pipeline, 'bosh-lab-bosh-lock');
+	ok $bl, 'bosh-lab-bosh-lock resource emitted';
+	is $bl->{source}{lock_name}, 'bosh-lab-bosh-upgrade', 'lock_name is <alias>-bosh-upgrade';
+	ok !$bl->{source}{bosh_lock}, 'no bosh_lock URL in director lock source';
+};
+
+# =========================================================================
+# 3. Child env: no own bosh-lock resource; only deployment-lock
+# =========================================================================
+subtest 'Child env: no own bosh-lock resource, only deployment-lock' => sub {
+	my $ast = _ast(
+		envs => [
+			{ env => 'bosh-lab' },
+			{ env => 'cf-lab',  bosh_parent => 'bosh-lab' },
+		],
+		with_locker => 1,
+	);
+	my $pipeline = _describe($ast);
+
+	my $own_bl = _find_resource($pipeline, 'cf-lab-bosh-lock');
+	ok !$own_bl, 'child cf-lab has no own bosh-lock resource';
+
+	my $dl = _find_resource($pipeline, 'cf-lab-deployment-lock');
+	ok $dl, 'child cf-lab has deployment-lock resource';
+};
+
+# =========================================================================
+# 4. Director deploy job acquires its own bosh-lock with correct key
+# =========================================================================
+subtest 'Director deploy job: acquires own bosh-lock (dont-upgrade-bosh-on-me)' => sub {
+	my $ast = _ast(
+		envs => [
+			{ env => 'bosh-lab' },
+			{ env => 'cf-lab', bosh_parent => 'bosh-lab' },
+		],
+		with_locker => 1,
+	);
+	my $pipeline = _describe($ast);
+	my $job      = _find_job($pipeline, 'bosh-lab-deployment');
+	my @locks    = _lock_puts(_do_block($job));
+
+	my ($bosh_lock) = grep { $_->{put} eq 'bosh-lab-bosh-lock' } @locks;
+	ok $bosh_lock, 'director job locks bosh-lab-bosh-lock';
+	is $bosh_lock->{params}{key}, 'dont-upgrade-bosh-on-me', 'key is dont-upgrade-bosh-on-me';
+	is $bosh_lock->{params}{lock_op}, 'lock', 'lock_op is lock';
+
+	my ($deploy_lock) = grep { $_->{put} eq 'bosh-lab-deployment-lock' } @locks;
+	ok $deploy_lock, 'director job also locks bosh-lab-deployment-lock';
+	is $deploy_lock->{params}{key}, 'i-need-to-deploy-myself', 'key is i-need-to-deploy-myself';
+};
+
+# =========================================================================
+# 5. Child deploy job acquires director's bosh-lock, not its own
+# =========================================================================
+subtest 'Child deploy job: acquires director bosh-lock, not own' => sub {
+	my $ast = _ast(
+		envs => [
+			{ env => 'bosh-lab' },
+			{ env => 'cf-lab', bosh_parent => 'bosh-lab' },
+		],
+		with_locker => 1,
+	);
+	my $pipeline = _describe($ast);
+	my $job      = _find_job($pipeline, 'cf-lab-deployment');
+	my @locks    = _lock_puts(_do_block($job));
+
+	my ($dir_lock) = grep { $_->{put} eq 'bosh-lab-bosh-lock' } @locks;
+	ok $dir_lock, 'child job acquires bosh-lab-bosh-lock (director)';
+	is $dir_lock->{params}{key},      'dont-upgrade-bosh-on-me', 'key is dont-upgrade-bosh-on-me';
+	is $dir_lock->{params}{locked_by}, 'cf-lab-deployment',       'locked_by is cf-lab-deployment';
+
+	my ($own_lock) = grep { $_->{put} eq 'cf-lab-bosh-lock' } @locks;
+	ok !$own_lock, 'child job does NOT acquire cf-lab-bosh-lock';
+
+	my ($deploy_lock) = grep { $_->{put} eq 'cf-lab-deployment-lock' } @locks;
+	ok $deploy_lock, 'child job still acquires cf-lab-deployment-lock';
+};
+
+# =========================================================================
+# 6. Unlock steps mirror lock steps
+# =========================================================================
+subtest 'Deploy job: ensure block has matching unlock steps' => sub {
+	my $ast = _ast(
+		envs => [
+			{ env => 'bosh-lab' },
+			{ env => 'cf-lab', bosh_parent => 'bosh-lab' },
+		],
+		with_locker => 1,
+	);
+	my $pipeline   = _describe($ast);
+	my $job        = _find_job($pipeline, 'cf-lab-deployment');
+	my @unlocks    = _lock_puts(_ensure_do($job));
+
+	my ($dir_unlock) = grep { $_->{put} eq 'bosh-lab-bosh-lock' } @unlocks;
+	ok $dir_unlock, 'ensure block unlocks bosh-lab-bosh-lock';
+	is $dir_unlock->{params}{lock_op}, 'unlock', 'lock_op is unlock';
+
+	my ($deploy_unlock) = grep { $_->{put} eq 'cf-lab-deployment-lock' } @unlocks;
+	ok $deploy_unlock, 'ensure block unlocks cf-lab-deployment-lock';
+};
+
+# =========================================================================
+# 7. Opt-out (bosh_upgrade_lock: false): child treated as standalone
+# =========================================================================
+subtest 'Opt-out (bosh_upgrade_lock=false): child gets own bosh-lock, not director lock' => sub {
+	my $ast = _ast(
+		envs => [
+			{ env => 'bosh-lab', url => 'https://bosh.lab:25555' },
+			{ env => 'cf-lab', bosh_parent => 'bosh-lab', bosh_upgrade_lock => 0,
+			  url => 'https://bosh.lab:25555' },
+		],
+		with_locker => 1,
+	);
+	my $pipeline = _describe($ast);
+
+	my $own_bl = _find_resource($pipeline, 'cf-lab-bosh-lock');
+	ok $own_bl, 'cf-lab gets own bosh-lock when bosh_upgrade_lock=false';
+	like $own_bl->{source}{bosh_lock}, qr{https://bosh\.lab}, 'source.bosh_lock is BOSH URL';
+
+	my $job   = _find_job($pipeline, 'cf-lab-deployment');
+	my @locks = _lock_puts(_do_block($job));
+
+	my ($own_lock) = grep { $_->{put} eq 'cf-lab-bosh-lock' } @locks;
+	ok $own_lock, 'opt-out child acquires own bosh-lock';
+
+	my ($dir_lock) = grep { $_->{put} eq 'bosh-lab-bosh-lock' } @locks;
+	ok !$dir_lock, 'opt-out child does NOT acquire director bosh-lock';
+};
+
+# =========================================================================
+# 8. Multi-child: both children acquire the same director lock resource
+# =========================================================================
+subtest 'Multi-child: both children acquire the shared director bosh-lock' => sub {
+	my $ast = _ast(
+		envs => [
+			{ env => 'bosh-lab' },
+			{ env => 'cf-lab',  bosh_parent => 'bosh-lab' },
+			{ env => 'shield',  bosh_parent => 'bosh-lab' },
+		],
+		with_locker => 1,
+	);
+	my $pipeline = _describe($ast);
+
+	# Only one bosh-lab-bosh-lock resource
+	my @director_locks = grep { ($_->{name} || '') eq 'bosh-lab-bosh-lock' }
+		@{$pipeline->{resources}};
+	is scalar(@director_locks), 1, 'exactly one bosh-lab-bosh-lock resource emitted';
+
+	# cf-lab job acquires director lock
+	my $cf_job    = _find_job($pipeline, 'cf-lab-deployment');
+	my @cf_locks  = _lock_puts(_do_block($cf_job));
+	my ($cf_dir)  = grep { $_->{put} eq 'bosh-lab-bosh-lock' } @cf_locks;
+	ok $cf_dir, 'cf-lab job acquires bosh-lab-bosh-lock';
+
+	# shield job acquires director lock
+	my $sh_job    = _find_job($pipeline, 'shield-deployment');
+	my @sh_locks  = _lock_puts(_do_block($sh_job));
+	my ($sh_dir)  = grep { $_->{put} eq 'bosh-lab-bosh-lock' } @sh_locks;
+	ok $sh_dir, 'shield job acquires bosh-lab-bosh-lock';
+
+	# Neither child has its own bosh-lock resource
+	ok !_find_resource($pipeline, 'cf-lab-bosh-lock'),  'cf-lab has no own bosh-lock';
+	ok !_find_resource($pipeline, 'shield-bosh-lock'),   'shield has no own bosh-lock';
+};
+
+# =========================================================================
+# 9. bosh-create-env director: lock_name-based lock (no BOSH URL available)
+# =========================================================================
+subtest 'bosh-create-env director: bosh-lock uses lock_name, not bosh_lock URL' => sub {
+	my $ast = _ast(
+		envs => [
+			{ env => 'bosh-mgmt', create_env => 1 },
+			{ env => 'cf-mgmt',   bosh_parent => 'bosh-mgmt' },
+		],
+		with_locker => 1,
+	);
+	my $pipeline = _describe($ast);
+
+	my $bl = _find_resource($pipeline, 'bosh-mgmt-bosh-lock');
+	ok $bl, 'bosh-mgmt-bosh-lock resource emitted';
+	is $bl->{source}{lock_name}, 'bosh-mgmt-bosh-upgrade',
+		'lock_name is bosh-mgmt-bosh-upgrade (not URL-based)';
+	ok !$bl->{source}{bosh_lock},
+		'no bosh_lock URL in create-env director lock source';
+};
+
+# =========================================================================
+# 10. Error: bosh_parent set but no locker configured
+# =========================================================================
+subtest 'Error: bosh_parent with no locker integration causes bail' => sub {
+	my $ast = _ast(
+		envs => [
+			{ env => 'bosh-lab' },
+			{ env => 'cf-lab', bosh_parent => 'bosh-lab' },
+		],
+		with_locker => 0,   # no locker!
+	);
+	my $d = Genesis::CI::Compiler::PipelineDescriptor->new(ast => $ast);
+
+	my $err;
+	eval { $d->describe(); 1 } or do { $err = $@ };
+
+	ok $err, 'describe() died when bosh_parent set but no locker';
+	like $err, qr/locker/i,        'error mentions locker';
+	like $err, qr/bosh_upgrade/i, 'error mentions bosh_upgrade opt-out';
+	like $err, qr/cf-lab/i,        'error names the offending env';
+	like $err, qr/bosh-lab/i,      'error names the parent director';
+};
+
+# =========================================================================
+# 11. Redeploy job: same BOSH lock topology as deploy job
+# =========================================================================
+subtest 'Redeploy job: child acquires director bosh-lock, not own' => sub {
+	my $ast = _ast(
+		envs => [
+			{ env => 'bosh-lab' },
+			{ env => 'cf-lab', bosh_parent => 'bosh-lab',
+			  redeploy => 'manual' },
+		],
+		with_locker => 1,
+	);
+
+	# Patch redeploy into the node so the redeploy job is emitted
+	my $node = $ast->workflows->{default}{graph}{nodes}{'cf-lab'};
+	$node->{redeploy} = 'manual';
+
+	my $pipeline = _describe($ast);
+	my $rj       = _find_job($pipeline, 'redeploy-cf-lab');
+	ok $rj, 'redeploy-cf-lab job emitted';
+
+	my @locks   = _lock_puts(_do_block($rj));
+	my ($dlock) = grep { $_->{put} eq 'bosh-lab-bosh-lock' } @locks;
+	ok $dlock, 'redeploy job acquires bosh-lab-bosh-lock (director)';
+	is $dlock->{params}{locked_by}, 'cf-lab-redeploy',
+		'locked_by is cf-lab-redeploy';
+};
+
+# =========================================================================
+# 12. ASTBuilder reads genesis.bosh_env from env files
+# =========================================================================
+subtest 'ASTBuilder reads genesis.bosh_env and sets bosh_parent on child nodes' => sub {
+	my $tmp = tempdir(CLEANUP => 1);
+
+	_write("$tmp/bosh-lab.yml", <<'YAML');
+---
+genesis:
+  env: bosh-lab
+  pipeline: {}
+YAML
+
+	_write("$tmp/cf-lab.yml", <<'YAML');
+---
+genesis:
+  env: cf-lab
+  bosh_env: bosh-lab
+  pipeline:
+    prior_env: bosh-lab
+YAML
+
+	_write("$tmp/shield.yml", <<'YAML');
+---
+genesis:
+  env: shield
+  bosh_env: bosh-lab
+  pipeline:
+    prior_env: bosh-lab
+YAML
+
+	_write("$tmp/prod.yml", <<'YAML');
+---
+genesis:
+  env: prod
+  bosh_env: external-bosh
+  pipeline: {}
+YAML
+
+	my $builder = Genesis::CI::Compiler::ASTBuilder->new(env_dir => $tmp);
+	my $parsed  = {
+		_source_format  => 'multi-file',
+		env_dir         => $tmp,
+		pipeline        => {},
+		targets         => {},
+		integrations    => {},
+		scripts         => {},
+		provider_config => {},
+	};
+	my $ast   = $builder->build($parsed, {});
+	my $nodes = $ast->workflows->{default}{graph}{nodes};
+
+	is $nodes->{'cf-lab'}{bosh_parent},  'bosh-lab',
+		'cf-lab: bosh_parent=bosh-lab (director in same pipeline)';
+	is $nodes->{shield}{bosh_parent},    'bosh-lab',
+		'shield: bosh_parent=bosh-lab (director in same pipeline)';
+	is $nodes->{'bosh-lab'}{bosh_parent}, '',
+		'bosh-lab: no bosh_parent (it is the director)';
+	is $nodes->{prod}{bosh_parent}, '',
+		'prod: bosh_parent empty (external-bosh not in pipeline)';
+};
+
+# =========================================================================
+# 13. ASTBuilder: bosh_upgrade_lock: false opt-out is respected
+# =========================================================================
+subtest 'ASTBuilder: bosh_upgrade_lock: false disables lock for that env' => sub {
+	my $tmp = tempdir(CLEANUP => 1);
+
+	_write("$tmp/bosh-lab.yml", <<'YAML');
+---
+genesis:
+  env: bosh-lab
+  pipeline: {}
+YAML
+
+	_write("$tmp/cf-lab.yml", <<'YAML');
+---
+genesis:
+  env: cf-lab
+  bosh_env: bosh-lab
+  pipeline:
+    prior_env: bosh-lab
+    locks:
+      bosh_upgrade: false
+YAML
+
+	my $builder = Genesis::CI::Compiler::ASTBuilder->new(env_dir => $tmp);
+	my $parsed  = {
+		_source_format  => 'multi-file',
+		env_dir         => $tmp,
+		pipeline        => {},
+		targets         => {},
+		integrations    => {},
+		scripts         => {},
+		provider_config => {},
+	};
+	my $ast   = $builder->build($parsed, {});
+	my $nodes = $ast->workflows->{default}{graph}{nodes};
+
+	is $nodes->{'cf-lab'}{bosh_parent},       'bosh-lab',
+		'cf-lab: bosh_parent still set';
+	is $nodes->{'cf-lab'}{bosh_upgrade_lock}, 0,
+		'cf-lab: bosh_upgrade_lock=0 (opt-out)';
+};
+
+# =========================================================================
+# 14. Mermaid: director node gets DIRECTOR annotation
+# =========================================================================
+subtest 'Mermaid: director node annotated with DIRECTOR label' => sub {
+	my $ast = _ast(
+		envs => [
+			{ env => 'bosh-lab' },
+			{ env => 'cf-lab', bosh_parent => 'bosh-lab' },
+		],
+		edges       => [{ from => 'bosh-lab', to => 'cf-lab' }],
+		with_locker => 1,
+	);
+	my $mermaid = _mermaid($ast);
+
+	like   $mermaid, qr/bosh-lab.*DIRECTOR/,  'bosh-lab node includes DIRECTOR annotation';
+	unlike $mermaid, qr/cf-lab.*DIRECTOR/,    'cf-lab child does not get DIRECTOR label';
+};
+
+done_testing;
diff --git a/t/unit-tests/genesis_ci_pipeline_descriptor-notifications.t b/t/unit-tests/genesis_ci_pipeline_descriptor-notifications.t
new file mode 100644
index 00000000..4eed7601
--- /dev/null
+++ b/t/unit-tests/genesis_ci_pipeline_descriptor-notifications.t
@@ -0,0 +1,601 @@
+#!/usr/bin/env perl
+use strict;
+use warnings;
+
+use lib 't';
+use lib 'lib';
+use File::Temp qw/tempdir/;
+use Test::More;
+use Test::Deep;
+
+$ENV{GENESIS_TESTING} = 'yes';
+$ENV{GENESIS_LIB}   ||= 'lib';
+
+use_ok 'Genesis::CI::Compiler::AST';
+use_ok 'Genesis::CI::Compiler::ASTBuilder';
+use_ok 'Genesis::CI::Compiler::PipelineDescriptor';
+
+# =========================================================================
+# Helpers
+# =========================================================================
+
+sub _write {
+	my ($path, $content) = @_;
+	open my $fh, '>', $path or die "Cannot write $path: $!";
+	print $fh $content;
+	close $fh;
+}
+
+# Build a minimal AST with configurable Slack notification config.
+# slack_cfg: hashref placed directly at integrations.slack
+# legacy_notifications: arrayref placed at integrations.notifications (old format)
+# legacy_style: string placed at configuration.notifications.style (old format)
+sub _ast_for {
+	my (%o) = @_;
+
+	my $env   = $o{env}   || 'sandbox';
+	my $alias = $o{alias} || $env;
+
+	my %integrations = (
+		source_control => { provider => 'github', repository => 'org/repo' },
+		vault          => { url => 'https://vault.example.com' },
+	);
+
+	if ($o{slack_cfg}) {
+		$integrations{slack} = $o{slack_cfg};
+	} elsif ($o{legacy_notifications}) {
+		$integrations{notifications} = $o{legacy_notifications};
+	}
+
+	my %config = (
+		task     => { image => 'genesiscommunity/concourse', version => 'latest' },
+		registry => {},
+	);
+	$config{notifications} = { style => $o{legacy_style} }
+		if $o{legacy_style};
+
+	my %node = (
+		alias               => $alias,
+		stage_name          => $env,
+		genesis_env         => $env,
+		auto                => $o{auto} // 0,
+		type                => 'deployment',
+		require_pr          => 0,
+		manual              => 0,
+		redeploy            => '',
+		redeploy_cron_start => '',
+		redeploy_cron_stop  => '',
+		status_signal       => '',
+		signal_prefix       => '',
+		bosh_parent         => '',
+		bosh_upgrade_lock   => 1,
+	);
+
+	my %nodes = ($env => \%node);
+	my %targets = (
+		$env => {
+			type       => 'bosh-director',
+			connection => {
+				url     => 'https://bosh.example.com:25555',
+				ca_cert => 'fake-ca',
+				auth    => { client_id => 'admin', client_secret => 'secret' },
+			},
+		},
+	);
+
+	# Multi-env support
+	if ($o{extra_envs}) {
+		for my $eenv (@{$o{extra_envs}}) {
+			my $en = $eenv->{env};
+			$nodes{$en} = {
+				alias               => $en,
+				stage_name          => $en,
+				genesis_env         => $en,
+				auto                => $eenv->{auto} // 0,
+				type                => 'deployment',
+				require_pr          => 0,
+				manual              => 0,
+				redeploy            => '',
+				redeploy_cron_start => '',
+				redeploy_cron_stop  => '',
+				status_signal       => '',
+				signal_prefix       => '',
+				bosh_parent         => '',
+				bosh_upgrade_lock   => 1,
+			};
+			$targets{$en} = {
+				type       => 'bosh-director',
+				connection => { url => 'https://bosh.example.com:25555',
+				    ca_cert => 'c', auth => { client_id => 'u', client_secret => 's' } },
+			};
+		}
+	}
+
+	return Genesis::CI::Compiler::AST->new(
+		metadata     => { name => 'test-pipeline', deployment_type => 'deployment' },
+		branches     => { control => 'main' },
+		integrations => \%integrations,
+		targets      => \%targets,
+		workflows    => {
+			default => {
+				name  => 'default',
+				type  => 'deployment',
+				graph => {
+					nodes => \%nodes,
+					edges => $o{edges} || [],
+				},
+			},
+		},
+		configuration => \%config,
+	);
+}
+
+sub _describe {
+	my ($ast) = @_;
+	Genesis::CI::Compiler::PipelineDescriptor->new(ast => $ast)->describe();
+}
+
+sub _find_job {
+	my ($pipeline, $name) = @_;
+	my ($j) = grep { $_->{name} eq $name } @{$pipeline->{jobs}};
+	return $j;
+}
+
+sub _find_resource {
+	my ($pipeline, $name) = @_;
+	my ($r) = grep { $_->{name} eq $name } @{$pipeline->{resources}};
+	return $r;
+}
+
+sub _find_rtype {
+	my ($pipeline, $name) = @_;
+	my ($r) = grep { $_->{name} eq $name } @{$pipeline->{resource_types}};
+	return $r;
+}
+
+sub _outcome_hook {
+	my ($job, $hook) = @_;
+	return ($job->{plan}[0] || {})->{$hook};
+}
+
+# =========================================================================
+# 1. style: per-env — notify jobs created, inline with deploy
+# =========================================================================
+subtest 'per-env style: notify jobs created and inlined with deploy' => sub {
+	my $ast = _ast_for(
+		env      => 'sandbox',
+		slack_cfg => {
+			webhook => '((slack-hook))',
+			channel => '#deployments',
+			style   => 'per-env',
+			mentions_on_failure => [],
+			per_env_overrides   => {},
+		},
+	);
+	my $pipeline = _describe($ast);
+
+	my $nj = _find_job($pipeline, 'notify-sandbox-deployment-changes');
+	ok $nj, 'notify job created for non-auto env';
+
+	my $dj = _find_job($pipeline, 'sandbox-deployment');
+	my $gets = $dj->{plan}[0]{do};
+	my ($par) = grep { ref $_ eq 'HASH' && $_->{in_parallel} } @$gets;
+	my ($changes_get) = grep { ($_->{get}||'') eq 'sandbox-changes' }
+		@{$par->{in_parallel}};
+	ok $changes_get->{passed}, 'deploy job gets sandbox-changes with passed dependency';
+	like $changes_get->{passed}[0], qr/notify-sandbox/, 'passed references notify job';
+
+	my $rt = _find_rtype($pipeline, 'slack-notification');
+	ok $rt, 'slack-notification resource type emitted';
+
+	my $slack_res = _find_resource($pipeline, 'slack');
+	ok $slack_res, 'slack resource emitted';
+};
+
+# =========================================================================
+# 2. style: grouped — notify jobs created, in separate group, deploy independent
+# =========================================================================
+subtest 'grouped style: notify jobs in separate group, deploy gets changes directly' => sub {
+	my $ast = _ast_for(
+		env      => 'sandbox',
+		slack_cfg => {
+			webhook => '((slack-hook))',
+			channel => '#deployments',
+			style   => 'grouped',
+			mentions_on_failure => [],
+			per_env_overrides   => {},
+		},
+	);
+	my $pipeline = _describe($ast);
+
+	my $nj = _find_job($pipeline, 'notify-sandbox-deployment-changes');
+	ok $nj, 'notify job created for grouped style';
+
+	# 'notifications' group must exist
+	my ($notif_group) = grep { $_->{name} eq 'notifications' } @{$pipeline->{groups}};
+	ok $notif_group, 'notifications group emitted';
+	ok grep({ $_ eq 'notify-sandbox-deployment-changes' } @{$notif_group->{jobs}}),
+		'notify job is in the notifications group';
+
+	# Deploy job must NOT depend on notify job (gets changes directly)
+	my $dj   = _find_job($pipeline, 'sandbox-deployment');
+	my $do   = $dj->{plan}[0]{do};
+	my ($par) = grep { ref $_ eq 'HASH' && $_->{in_parallel} } @$do;
+	my ($cg)  = grep { ($_->{get}||'') eq 'sandbox-changes' }
+		@{$par->{in_parallel}};
+	ok !$cg->{passed}, 'deploy job gets sandbox-changes WITHOUT passed dependency';
+};
+
+# =========================================================================
+# 3. style: minimal — no notify jobs; only on_failure hook
+# =========================================================================
+subtest 'minimal style: no notify jobs, only on_failure hook in deploy' => sub {
+	my $ast = _ast_for(
+		env      => 'sandbox',
+		slack_cfg => {
+			webhook => '((slack-hook))',
+			channel => '#deployments',
+			style   => 'minimal',
+			mentions_on_failure => [],
+			per_env_overrides   => {},
+		},
+	);
+	my $pipeline = _describe($ast);
+
+	ok !_find_job($pipeline, 'notify-sandbox-deployment-changes'),
+		'no notify job for minimal style';
+
+	my $dj = _find_job($pipeline, 'sandbox-deployment');
+	ok !_outcome_hook($dj, 'on_success'), 'no on_success hook for minimal style';
+	ok  _outcome_hook($dj, 'on_failure'), 'on_failure hook present for minimal style';
+
+	ok _find_resource($pipeline, 'slack'), 'slack resource still emitted for minimal';
+};
+
+# =========================================================================
+# 4. style: none — no notifications at all
+# =========================================================================
+subtest 'none style: no slack resources, no notify jobs, no hooks' => sub {
+	my $ast = _ast_for(
+		env      => 'sandbox',
+		slack_cfg => {
+			webhook => '((slack-hook))',
+			channel => '#deployments',
+			style   => 'none',
+			mentions_on_failure => [],
+			per_env_overrides   => {},
+		},
+	);
+	my $pipeline = _describe($ast);
+
+	ok !_find_job($pipeline, 'notify-sandbox-deployment-changes'),
+		'no notify job for none style';
+	ok !_find_resource($pipeline, 'slack'),
+		'no slack resource for none style';
+	ok !_find_rtype($pipeline, 'slack-notification'),
+		'no slack-notification resource type for none style';
+
+	my $dj = _find_job($pipeline, 'sandbox-deployment');
+	ok !_outcome_hook($dj, 'on_success'), 'no on_success hook';
+	ok !_outcome_hook($dj, 'on_failure'), 'no on_failure hook';
+};
+
+# =========================================================================
+# 5. mentions_on_failure prepended to failure notification text
+# =========================================================================
+subtest 'mentions_on_failure prepended to failure notification text' => sub {
+	my $ast = _ast_for(
+		env      => 'prod',
+		slack_cfg => {
+			webhook             => '((slack-hook))',
+			channel             => '#alerts',
+			style               => 'per-env',
+			mentions_on_failure => ['@sre-oncall', '@prod-sre'],
+			per_env_overrides   => {},
+		},
+	);
+	my $pipeline = _describe($ast);
+
+	my $dj       = _find_job($pipeline, 'prod-deployment');
+	my $on_fail  = _outcome_hook($dj, 'on_failure');
+	ok $on_fail, 'on_failure hook present';
+
+	# Unwrap: on_failure may be a single put or in_parallel
+	my $put = ref($on_fail) eq 'HASH' && $on_fail->{in_parallel}
+		? $on_fail->{in_parallel}[0]
+		: $on_fail;
+	like $put->{params}{text}, qr/\@sre-oncall/,  'mention @sre-oncall in failure text';
+	like $put->{params}{text}, qr/\@prod-sre/,    'mention @prod-sre in failure text';
+
+	# Success hook must NOT have mentions
+	my $on_succ = _outcome_hook($dj, 'on_success');
+	if ($on_succ) {
+		my $sput = ref($on_succ) eq 'HASH' && $on_succ->{in_parallel}
+			? $on_succ->{in_parallel}[0]
+			: $on_succ;
+		unlike $sput->{params}{text}, qr/\@sre-oncall/, 'no mention in success text';
+	}
+};
+
+# =========================================================================
+# 6. per_env_overrides: different channel and mentions for specific env
+# =========================================================================
+subtest 'per_env_overrides: env uses its own channel and mentions' => sub {
+	my $ast = _ast_for(
+		env      => 'sandbox',
+		extra_envs => [{ env => 'prod' }],
+		slack_cfg => {
+			webhook             => '((slack-hook))',
+			channel             => '#deployments',
+			style               => 'per-env',
+			mentions_on_failure => [],
+			per_env_overrides   => {
+				prod => {
+					channel             => '#prod-alerts',
+					mentions_on_failure => ['@prod-oncall'],
+				},
+			},
+		},
+	);
+	my $pipeline = _describe($ast);
+
+	# Sandbox notify job should use global channel
+	my $sb_nj   = _find_job($pipeline, 'notify-sandbox-deployment-changes');
+	ok $sb_nj, 'sandbox notify job present';
+	my $sb_put  = $sb_nj->{plan}[-1];
+	$sb_put = $sb_put->{in_parallel}[0] if ref($sb_put) eq 'HASH' && $sb_put->{in_parallel};
+	is $sb_put->{params}{channel}, '#deployments', 'sandbox uses global channel';
+
+	# Prod notify job should use override channel
+	my $prod_nj = _find_job($pipeline, 'notify-prod-deployment-changes');
+	ok $prod_nj, 'prod notify job present';
+	my $prod_put = $prod_nj->{plan}[-1];
+	$prod_put = $prod_put->{in_parallel}[0] if ref($prod_put) eq 'HASH' && $prod_put->{in_parallel};
+	is $prod_put->{params}{channel}, '#prod-alerts', 'prod uses override channel';
+
+	# Prod failure hook should have mentions
+	my $prod_dj   = _find_job($pipeline, 'prod-deployment');
+	my $on_fail   = _outcome_hook($prod_dj, 'on_failure');
+	my $fail_put  = ref($on_fail) eq 'HASH' && $on_fail->{in_parallel}
+		? $on_fail->{in_parallel}[0] : $on_fail;
+	like $fail_put->{params}{text}, qr/\@prod-oncall/, 'prod failure has mention';
+	is   $fail_put->{params}{channel}, '#prod-alerts',  'prod failure uses override channel';
+
+	# Sandbox failure hook should NOT have mentions
+	my $sb_dj    = _find_job($pipeline, 'sandbox-deployment');
+	my $sb_fail  = _outcome_hook($sb_dj, 'on_failure');
+	my $sf_put   = ref($sb_fail) eq 'HASH' && $sb_fail->{in_parallel}
+		? $sb_fail->{in_parallel}[0] : $sb_fail;
+	unlike $sf_put->{params}{text}, qr/\@prod-oncall/, 'sandbox failure has no prod mention';
+	is     $sf_put->{params}{channel}, '#deployments',  'sandbox failure uses global channel';
+};
+
+# =========================================================================
+# 7. Legacy notifications: grouped backward compat
+# =========================================================================
+subtest 'Legacy notifications: grouped maps to grouped style' => sub {
+	my $ast = _ast_for(
+		env                  => 'sandbox',
+		legacy_notifications => [
+			{ type => 'slack', webhook => '((hook))', channel => '#ci',
+			  username => 'bot', icon => 'http://icon' }
+		],
+		legacy_style => 'grouped',
+	);
+	my $pipeline = _describe($ast);
+
+	my $nj = _find_job($pipeline, 'notify-sandbox-deployment-changes');
+	ok $nj, 'notify job created (grouped compat)';
+
+	my ($notif_group) = grep { $_->{name} eq 'notifications' } @{$pipeline->{groups}};
+	ok $notif_group, 'notifications group emitted for legacy grouped style';
+
+	my $rt = _find_rtype($pipeline, 'slack-notification');
+	ok $rt, 'slack-notification resource type emitted';
+};
+
+# =========================================================================
+# 8. Legacy notifications: inline (default) maps to per-env style
+# =========================================================================
+subtest 'Legacy notifications: inline maps to per-env (notify job with passed dep)' => sub {
+	my $ast = _ast_for(
+		env                  => 'sandbox',
+		legacy_notifications => [
+			{ type => 'slack', webhook => '((hook))', channel => '#ci',
+			  username => 'bot', icon => 'http://icon' }
+		],
+		# no legacy_style → defaults to inline → maps to per-env
+	);
+	my $pipeline = _describe($ast);
+
+	my $nj = _find_job($pipeline, 'notify-sandbox-deployment-changes');
+	ok $nj, 'notify job created for legacy inline style';
+
+	my $dj   = _find_job($pipeline, 'sandbox-deployment');
+	my $do   = $dj->{plan}[0]{do};
+	my ($par) = grep { ref $_ eq 'HASH' && $_->{in_parallel} } @$do;
+	my ($cg)  = grep { ($_->{get}||'') eq 'sandbox-changes' }
+		@{$par->{in_parallel}};
+	ok $cg->{passed}, 'deploy job has passed dependency (inline/per-env behavior)';
+
+	my ($notif_group) = grep { $_->{name} eq 'notifications' } @{$pipeline->{groups}};
+	ok !$notif_group, 'no separate notifications group for inline style';
+};
+
+# =========================================================================
+# 9. Legacy notifications: no Slack configured → no slack resources or jobs
+# =========================================================================
+subtest 'No Slack config: no slack resource, no notify jobs' => sub {
+	my $ast = _ast_for(env => 'sandbox');
+	my $pipeline = _describe($ast);
+
+	ok !_find_job($pipeline, 'notify-sandbox-deployment-changes'),
+		'no notify job when no Slack configured';
+	ok !_find_resource($pipeline, 'slack'), 'no slack resource';
+	ok !_find_rtype($pipeline, 'slack-notification'), 'no slack-notification resource type';
+};
+
+# =========================================================================
+# 10. auto env: no notify job regardless of style
+# =========================================================================
+subtest 'auto env: no notify job even with per-env style' => sub {
+	my $ast = _ast_for(
+		env  => 'sandbox',
+		auto => 1,
+		slack_cfg => {
+			webhook => '((hook))',
+			channel => '#ci',
+			style   => 'per-env',
+			mentions_on_failure => [],
+			per_env_overrides   => {},
+		},
+	);
+	my $pipeline = _describe($ast);
+
+	ok !_find_job($pipeline, 'notify-sandbox-deployment-changes'),
+		'no notify job for auto env';
+};
+
+# =========================================================================
+# 11. minimal: deploy job gets changes directly (no passed dependency)
+# =========================================================================
+subtest 'minimal style: deploy job gets changes directly' => sub {
+	my $ast = _ast_for(
+		env      => 'sandbox',
+		slack_cfg => {
+			webhook => '((hook))',
+			channel => '#ci',
+			style   => 'minimal',
+			mentions_on_failure => [],
+			per_env_overrides   => {},
+		},
+	);
+	my $pipeline = _describe($ast);
+
+	my $dj   = _find_job($pipeline, 'sandbox-deployment');
+	my $do   = $dj->{plan}[0]{do};
+	my ($par) = grep { ref $_ eq 'HASH' && $_->{in_parallel} } @$do;
+	my ($cg)  = grep { ($_->{get}||'') eq 'sandbox-changes' }
+		@{$par->{in_parallel}};
+	ok !$cg->{passed}, 'minimal: deploy gets changes without passed dependency';
+};
+
+# =========================================================================
+# 12. ASTBuilder: legacy notifications array normalized to integrations.slack
+# =========================================================================
+subtest 'ASTBuilder normalizes legacy notifications array to integrations.slack' => sub {
+	my $tmp = tempdir(CLEANUP => 1);
+
+	_write("$tmp/sandbox.yml", <<'YAML');
+---
+genesis:
+  env: sandbox
+  pipeline: {}
+YAML
+
+	my $builder = Genesis::CI::Compiler::ASTBuilder->new(env_dir => $tmp);
+	my $parsed  = {
+		_source_format  => 'multi-file',
+		env_dir         => $tmp,
+		pipeline        => {},
+		targets         => {},
+		integrations    => {
+			notifications => [
+				{ type => 'slack', webhook => 'https://hooks.slack.com/test',
+				  channel => '#ci', username => 'bot', icon => 'http://icon' }
+			],
+		},
+		scripts         => {},
+		provider_config => {},
+	};
+	my $ast = $builder->build($parsed, {});
+
+	my $slack = $ast->integrations->{slack};
+	ok $slack, 'integrations.slack created from legacy notifications array';
+	is $slack->{webhook}, 'https://hooks.slack.com/test', 'webhook preserved';
+	is $slack->{channel}, '#ci',                          'channel preserved';
+	is $slack->{style},   'per-env',                      'default style is per-env';
+	is ref($slack->{mentions_on_failure}), 'ARRAY',       'mentions_on_failure is array';
+	is ref($slack->{per_env_overrides}),   'HASH',        'per_env_overrides is hash';
+};
+
+# =========================================================================
+# 13. ASTBuilder: legacy notifications: grouped sets style to grouped
+# =========================================================================
+subtest 'ASTBuilder: legacy notifications: grouped → style: grouped' => sub {
+	my $tmp = tempdir(CLEANUP => 1);
+	_write("$tmp/sandbox.yml", <<'YAML');
+---
+genesis:
+  env: sandbox
+  pipeline: {}
+YAML
+
+	my $builder = Genesis::CI::Compiler::ASTBuilder->new(env_dir => $tmp);
+	my $parsed  = {
+		_source_format  => 'legacy',
+		env_dir         => $tmp,
+		pipeline        => {},
+		targets         => {},
+		integrations    => {
+			notifications => [
+				{ type => 'slack', webhook => 'https://hooks.slack.com/test',
+				  channel => '#ci' }
+			],
+		},
+		scripts         => {},
+		provider_config => {},
+		_legacy_raw     => {
+			pipeline => {
+				notifications => 'grouped',
+				name          => 'test',
+				git           => { branch => 'main' },
+			},
+		},
+	};
+
+	my $ast = $builder->build($parsed, {});
+	my $slack = $ast->integrations->{slack};
+	ok $slack, 'integrations.slack present';
+	is $slack->{style}, 'grouped', 'legacy notifications: grouped maps to style: grouped';
+};
+
+# =========================================================================
+# 14. New slack: config directly in integrations
+# =========================================================================
+subtest 'New slack: config block used directly from integrations' => sub {
+	my $tmp = tempdir(CLEANUP => 1);
+	_write("$tmp/sandbox.yml", <<'YAML');
+---
+genesis:
+  env: sandbox
+  pipeline: {}
+YAML
+
+	my $builder = Genesis::CI::Compiler::ASTBuilder->new(env_dir => $tmp);
+	my $parsed  = {
+		_source_format  => 'multi-file',
+		env_dir         => $tmp,
+		pipeline        => {},
+		targets         => {},
+		integrations    => {
+			slack => {
+				webhook             => '((slack-webhook))',
+				channel             => '#deployments',
+				style               => 'minimal',
+				mentions_on_failure => ['@sre'],
+				per_env_overrides   => {},
+			},
+		},
+		scripts         => {},
+		provider_config => {},
+	};
+	my $ast = $builder->build($parsed, {});
+
+	my $slack = $ast->integrations->{slack};
+	ok $slack, 'integrations.slack preserved as-is';
+	is $slack->{style},               'minimal', 'style preserved';
+	is $slack->{mentions_on_failure}[0], '@sre', 'mentions_on_failure preserved';
+};
+
+done_testing;
diff --git a/t/unit-tests/genesis_ci_pipeline_descriptor-redeploy.t b/t/unit-tests/genesis_ci_pipeline_descriptor-redeploy.t
new file mode 100644
index 00000000..f43f32df
--- /dev/null
+++ b/t/unit-tests/genesis_ci_pipeline_descriptor-redeploy.t
@@ -0,0 +1,490 @@
+#!/usr/bin/env perl
+use strict;
+use warnings;
+
+use lib 't';
+use lib 'lib';
+use File::Temp qw/tempdir/;
+use Test::More;
+use Test::Deep;
+
+$ENV{GENESIS_TESTING} = 'yes';
+$ENV{GENESIS_LIB}   ||= 'lib';
+
+use_ok 'Genesis::CI::Compiler::AST';
+use_ok 'Genesis::CI::Compiler::ASTBuilder';
+use_ok 'Genesis::CI::Compiler::PipelineDescriptor';
+
+# =========================================================================
+# Helpers
+# =========================================================================
+
+sub _write {
+	my ($path, $content) = @_;
+	open my $fh, '>', $path or die "Cannot write $path: $!";
+	print $fh $content;
+	close $fh;
+}
+
+# Minimal AST with one env and configurable node attributes.
+sub _ast_for {
+	my (%opts) = @_;
+
+	my $env        = $opts{env}        || 'sandbox';
+	my $alias      = $opts{alias}      || $env;
+	my $redeploy   = $opts{redeploy}   || '';
+	my $cron_start = $opts{cron_start} || '';
+	my $cron_stop  = $opts{cron_stop}  || '';
+	my $with_locker = $opts{with_locker} // 1;
+	my $create_env  = $opts{create_env} // 0;
+
+	my $target_type = $create_env ? 'bosh-create-env' : 'bosh-director';
+	my %target = (type => $target_type);
+	unless ($create_env) {
+		$target{connection} = {
+			url       => 'https://bosh.example.com:25555',
+			ca_cert   => 'fake-ca',
+			auth      => { client_id => 'admin', client_secret => 'secret' },
+		};
+	}
+
+	my %integrations = (
+		source_control => { provider => 'github', repository => 'org/repo' },
+		vault          => { url => 'https://vault.example.com' },
+	);
+	if ($with_locker) {
+		$integrations{locker} = {
+			url      => 'https://locker.example.com',
+			username => 'locker-user',
+			password => 'locker-pass',
+		};
+	}
+
+	return Genesis::CI::Compiler::AST->new(
+		metadata     => { name => 'test-pipeline', deployment_type => 'deployment' },
+		branches     => { control => 'main' },
+		integrations => \%integrations,
+		targets      => { $env => \%target },
+		workflows    => {
+			default => {
+				name  => 'default',
+				type  => 'deployment',
+				graph => {
+					nodes => {
+						$env => {
+							alias               => $alias,
+							stage_name          => $env,
+							genesis_env         => $env,
+							auto                => 0,
+							type                => 'deployment',
+							require_pr          => 0,
+							manual              => 0,
+							redeploy            => $redeploy,
+							redeploy_cron_start => $cron_start,
+							redeploy_cron_stop  => $cron_stop,
+						},
+					},
+					edges => [],
+				},
+			},
+		},
+		configuration => {
+			task     => { image => 'genesiscommunity/concourse', version => 'latest' },
+			registry => {},
+		},
+	);
+}
+
+sub _describe {
+	my ($ast) = @_;
+	my $d = Genesis::CI::Compiler::PipelineDescriptor->new(ast => $ast);
+	return $d->describe();
+}
+
+# =========================================================================
+# 1. ASTBuilder reads redeploy attributes from env files
+# =========================================================================
+subtest 'ASTBuilder reads redeploy config from env files' => sub {
+	my $tmp = tempdir(CLEANUP => 1);
+
+	_write("$tmp/sandbox.yml", <<'YAML');
+---
+genesis:
+  env: sandbox
+  pipeline:
+    redeploy: manual
+YAML
+	_write("$tmp/staging.yml", <<'YAML');
+---
+genesis:
+  env: staging
+  pipeline:
+    prior_env: sandbox
+    redeploy: cron
+    redeploy_cron_start: "04:00"
+    redeploy_cron_stop:  "05:00"
+YAML
+	_write("$tmp/prod.yml", <<'YAML');
+---
+genesis:
+  env: prod
+  pipeline:
+    prior_env: staging
+YAML
+
+	my $builder = Genesis::CI::Compiler::ASTBuilder->new(env_dir => $tmp);
+	my $parsed  = {
+		_source_format => 'multi-file',
+		env_dir        => $tmp,
+		pipeline       => {},
+		targets        => {},
+		integrations   => {},
+		scripts        => {},
+		provider_config => {},
+	};
+	my $ast = $builder->build($parsed, {});
+	my $nodes = $ast->workflows->{default}{graph}{nodes};
+
+	is $nodes->{sandbox}{redeploy},            'manual', 'sandbox: redeploy=manual';
+	is $nodes->{sandbox}{redeploy_cron_start}, '',       'sandbox: no cron_start';
+
+	is $nodes->{staging}{redeploy},            'cron',   'staging: redeploy=cron';
+	is $nodes->{staging}{redeploy_cron_start}, '04:00',  'staging: cron_start=04:00';
+	is $nodes->{staging}{redeploy_cron_stop},  '05:00',  'staging: cron_stop=05:00';
+
+	is $nodes->{prod}{redeploy}, '', 'prod: no redeploy';
+};
+
+# =========================================================================
+# 2. redeploy: true / truthy shorthand normalises to 'manual'
+# =========================================================================
+subtest 'ASTBuilder normalises truthy redeploy value to "manual"' => sub {
+	my $tmp = tempdir(CLEANUP => 1);
+
+	_write("$tmp/sandbox.yml", <<'YAML');
+---
+genesis:
+  env: sandbox
+  pipeline:
+    redeploy: true
+YAML
+
+	my $builder = Genesis::CI::Compiler::ASTBuilder->new(env_dir => $tmp);
+	my $parsed  = {
+		_source_format => 'multi-file',
+		env_dir        => $tmp,
+		pipeline       => {},
+		targets        => {},
+		integrations   => {},
+		scripts        => {},
+		provider_config => {},
+	};
+	my $ast = $builder->build($parsed, {});
+	my $nodes = $ast->workflows->{default}{graph}{nodes};
+
+	is $nodes->{sandbox}{redeploy}, 'manual',
+		'truthy redeploy normalised to "manual"';
+};
+
+# =========================================================================
+# 3. No redeploy configured → no redeploy job or group emitted
+# =========================================================================
+subtest 'No redeploy config: no redeploy job or group emitted' => sub {
+	my $ast      = _ast_for(env => 'sandbox', redeploy => '');
+	my $pipeline = _describe($ast);
+
+	my @redeploy_jobs = grep { $_->{name} =~ /^redeploy-/ } @{$pipeline->{jobs}};
+	is scalar @redeploy_jobs, 0, 'no redeploy jobs emitted';
+
+	my @redeploy_groups = grep { $_->{name} eq 'redeploy' } @{$pipeline->{groups}};
+	is scalar @redeploy_groups, 0, 'no redeploy group emitted';
+};
+
+# =========================================================================
+# 4. Manual trigger mode
+# =========================================================================
+subtest 'Manual trigger: redeploy job emitted with no auto-trigger resource' => sub {
+	my $ast      = _ast_for(env => 'sandbox', redeploy => 'manual', with_locker => 0);
+	my $pipeline = _describe($ast);
+
+	# Job is present
+	my ($job) = grep { $_->{name} eq 'redeploy-sandbox' } @{$pipeline->{jobs}};
+	ok $job, 'redeploy-sandbox job emitted';
+	is $job->{serial}, 1, 'job is serial';
+
+	# No cron time resource
+	my @cron_res = grep { ($_->{name} || '') =~ /redeploy-cron/ } @{$pipeline->{resources}};
+	is scalar @cron_res, 0, 'no cron time resource for manual mode';
+
+	# All gets in plan have trigger=false
+	my $plan_step = $job->{plan}[0];
+	my $do = $plan_step->{do} || $plan_step;
+	my ($parallel) = grep { ref $_ eq 'HASH' && exists $_->{in_parallel} }
+		(ref $do eq 'ARRAY' ? @$do : ($do));
+	ok $parallel, 'in_parallel step found in plan';
+	for my $get (@{$parallel->{in_parallel}}) {
+		next unless ref $get eq 'HASH' && exists $get->{trigger};
+		is $get->{trigger}, 0,
+			"get $get->{get} has trigger=false in manual mode";
+	}
+
+	# Group emitted
+	my ($group) = grep { $_->{name} eq 'redeploy' } @{$pipeline->{groups}};
+	ok $group, 'redeploy group emitted';
+	ok grep { $_ eq 'redeploy-sandbox' } @{$group->{jobs}},
+		'redeploy group contains redeploy-sandbox';
+};
+
+# =========================================================================
+# 5. Signal trigger mode (same as manual from pipeline perspective)
+# =========================================================================
+subtest 'Signal trigger: behaves identically to manual (no auto-trigger)' => sub {
+	my $ast      = _ast_for(env => 'sandbox', redeploy => 'signal', with_locker => 0);
+	my $pipeline = _describe($ast);
+
+	my ($job) = grep { $_->{name} eq 'redeploy-sandbox' } @{$pipeline->{jobs}};
+	ok $job, 'redeploy-sandbox job emitted for signal mode';
+
+	my @cron_res = grep { ($_->{name} || '') =~ /redeploy-cron/ } @{$pipeline->{resources}};
+	is scalar @cron_res, 0, 'no cron time resource for signal mode';
+};
+
+# =========================================================================
+# 6. Cron trigger mode
+# =========================================================================
+subtest 'Cron trigger: time resource emitted; job gets it with trigger=true' => sub {
+	my $ast = _ast_for(
+		env        => 'sandbox',
+		redeploy   => 'cron',
+		cron_start => '04:00',
+		cron_stop  => '05:00',
+		with_locker => 0,
+	);
+	my $pipeline = _describe($ast);
+
+	# Time resource
+	my ($cron_res) = grep { ($_->{name} || '') eq 'sandbox-redeploy-cron' }
+		@{$pipeline->{resources}};
+	ok $cron_res, 'sandbox-redeploy-cron time resource emitted';
+	is $cron_res->{type},            'time',   'resource type is time';
+	is $cron_res->{source}{start},   '04:00',  'source.start correct';
+	is $cron_res->{source}{stop},    '05:00',  'source.stop correct';
+	is $cron_res->{source}{location},'UTC',    'source.location is UTC';
+
+	# Job
+	my ($job) = grep { $_->{name} eq 'redeploy-sandbox' } @{$pipeline->{jobs}};
+	ok $job, 'redeploy-sandbox job emitted';
+
+	# Cron get has trigger=true
+	my $plan_step = $job->{plan}[0];
+	my $do = $plan_step->{do} || $plan_step;
+	my ($parallel) = grep { ref $_ eq 'HASH' && exists $_->{in_parallel} }
+		(ref $do eq 'ARRAY' ? @$do : ($do));
+	ok $parallel, 'in_parallel step found in plan';
+
+	my ($cron_get) = grep { ref $_ eq 'HASH' && ($_->{get} || '') eq 'sandbox-redeploy-cron' }
+		@{$parallel->{in_parallel}};
+	ok $cron_get,                'cron get step present';
+	is $cron_get->{trigger}, 1,  'cron get has trigger=true';
+};
+
+# =========================================================================
+# 7. Cron trigger defaults (no explicit start/stop)
+# =========================================================================
+subtest 'Cron trigger: defaults to 04:00-05:00 when no times specified' => sub {
+	my $ast = _ast_for(
+		env        => 'sandbox',
+		redeploy   => 'cron',
+		with_locker => 0,
+	);
+	my $pipeline = _describe($ast);
+
+	my ($cron_res) = grep { ($_->{name} || '') eq 'sandbox-redeploy-cron' }
+		@{$pipeline->{resources}};
+	ok $cron_res, 'time resource emitted with defaults';
+	is $cron_res->{source}{start}, '04:00', 'default start 04:00';
+	is $cron_res->{source}{stop},  '05:00', 'default stop 05:00';
+};
+
+# =========================================================================
+# 8. Dual-lock: redeploy job acquires both locks when locker configured
+# =========================================================================
+subtest 'Redeploy job acquires bosh-lock and deployment-lock' => sub {
+	my $ast      = _ast_for(env => 'sandbox', redeploy => 'manual', with_locker => 1);
+	my $pipeline = _describe($ast);
+
+	my ($job) = grep { $_->{name} eq 'redeploy-sandbox' } @{$pipeline->{jobs}};
+	ok $job, 'redeploy-sandbox job present';
+
+	my $plan_step = $job->{plan}[0];
+	my $do = $plan_step->{do};
+	ok $do, 'plan has do block (with locks)';
+
+	my @lock_puts = grep {
+		ref $_ eq 'HASH' && $_->{put} && $_->{put} =~ /lock$/
+	} @$do;
+
+	my @bosh_locks = grep { $_->{put} eq 'sandbox-bosh-lock' } @lock_puts;
+	my @depl_locks = grep { $_->{put} eq 'sandbox-deployment-lock' } @lock_puts;
+
+	is scalar @bosh_locks, 1, 'sandbox-bosh-lock acquired';
+	is scalar @depl_locks, 1, 'sandbox-deployment-lock acquired';
+
+	is $bosh_locks[0]{params}{lock_op},   'lock', 'bosh-lock op=lock';
+	is $bosh_locks[0]{params}{locked_by}, 'sandbox-redeploy',
+		'bosh-lock locked_by=sandbox-redeploy';
+	is $depl_locks[0]{params}{locked_by}, 'sandbox-redeploy',
+		'deployment-lock locked_by=sandbox-redeploy';
+
+	# ensure block releases locks
+	my $ensure = $plan_step->{ensure};
+	ok $ensure, 'ensure block present for lock release';
+	my @unlock_puts = grep {
+		ref $_ eq 'HASH' && $_->{put} && $_->{put} =~ /lock$/
+	} @{$ensure->{do} || []};
+	is scalar @unlock_puts, 2, '2 unlock steps in ensure';
+};
+
+# =========================================================================
+# 9. create-env: redeploy skips bosh-lock (no BOSH director to protect)
+# =========================================================================
+subtest 'Redeploy job skips bosh-lock for create-env targets' => sub {
+	my $ast = _ast_for(
+		env        => 'sandbox',
+		redeploy   => 'manual',
+		with_locker => 1,
+		create_env  => 1,
+	);
+	my $pipeline = _describe($ast);
+
+	my ($job) = grep { $_->{name} eq 'redeploy-sandbox' } @{$pipeline->{jobs}};
+	ok $job, 'redeploy-sandbox job present for create-env';
+
+	my $plan_step = $job->{plan}[0];
+	my $do = $plan_step->{do};
+
+	my @bosh_locks = grep {
+		ref $_ eq 'HASH' && ($_->{put} || '') eq 'sandbox-bosh-lock'
+	} @$do;
+	is scalar @bosh_locks, 0, 'no bosh-lock for create-env';
+
+	my @depl_locks = grep {
+		ref $_ eq 'HASH' && ($_->{put} || '') eq 'sandbox-deployment-lock'
+	} @$do;
+	is scalar @depl_locks, 1, 'deployment-lock still acquired for create-env';
+};
+
+# =========================================================================
+# 10. Redeploy job uses ci-pipeline-deploy command
+# =========================================================================
+subtest 'Redeploy task uses ci-pipeline-deploy command' => sub {
+	my $ast      = _ast_for(env => 'sandbox', redeploy => 'manual', with_locker => 0);
+	my $pipeline = _describe($ast);
+
+	my ($job) = grep { $_->{name} eq 'redeploy-sandbox' } @{$pipeline->{jobs}};
+	ok $job, 'redeploy-sandbox job present';
+
+	my $plan_step = $job->{plan}[0];
+	my $do = $plan_step->{do};
+	my ($task_step) = grep {
+		ref $_ eq 'HASH' && ($_->{task} || '') eq 'bosh-redeploy'
+	} @$do;
+	ok $task_step, 'bosh-redeploy task step found';
+
+	my $args = $task_step->{config}{run}{args};
+	ok $args && grep { $_ eq 'ci-pipeline-deploy' } @$args,
+		'task runs ci-pipeline-deploy';
+};
+
+# =========================================================================
+# 11. Redeploy job does NOT appear in workflow deploy group
+# =========================================================================
+subtest 'Redeploy job does not pollute the main workflow group' => sub {
+	my $ast      = _ast_for(env => 'sandbox', redeploy => 'manual', with_locker => 0);
+	my $pipeline = _describe($ast);
+
+	my ($main_group) = grep { $_->{name} ne 'redeploy' } @{$pipeline->{groups}};
+	ok $main_group, 'main group present';
+
+	my @redeploy_in_main = grep { /^redeploy-/ } @{$main_group->{jobs} || []};
+	is scalar @redeploy_in_main, 0,
+		'redeploy job not listed in main workflow group';
+};
+
+# =========================================================================
+# 12. Multiple envs — only envs with redeploy config get redeploy jobs
+# =========================================================================
+subtest 'Multiple envs: only configured envs get redeploy jobs' => sub {
+	my $ast = Genesis::CI::Compiler::AST->new(
+		metadata     => { name => 'multi-test', deployment_type => 'deployment' },
+		branches     => { control => 'main' },
+		integrations => {
+			source_control => { provider => 'github', repository => 'org/repo' },
+			vault          => { url => 'https://vault.example.com' },
+		},
+		targets => {
+			sandbox  => { type => 'bosh-director', connection => {
+				url => 'https://bosh.sb.example.com', ca_cert => 'c',
+				auth => { client_id => 'u', client_secret => 's' } } },
+			staging  => { type => 'bosh-director', connection => {
+				url => 'https://bosh.st.example.com', ca_cert => 'c',
+				auth => { client_id => 'u', client_secret => 's' } } },
+			prod     => { type => 'bosh-director', connection => {
+				url => 'https://bosh.pd.example.com', ca_cert => 'c',
+				auth => { client_id => 'u', client_secret => 's' } } },
+		},
+		workflows => {
+			default => {
+				name  => 'default',
+				type  => 'deployment',
+				graph => {
+					nodes => {
+						sandbox => { alias => 'sandbox', stage_name => 'sandbox',
+							auto => 0, type => 'deployment',
+							require_pr => 0, manual => 0,
+							redeploy => '',    redeploy_cron_start => '', redeploy_cron_stop => '' },
+						staging => { alias => 'staging', stage_name => 'staging',
+							auto => 0, type => 'deployment',
+							require_pr => 0, manual => 0,
+							redeploy => 'manual', redeploy_cron_start => '', redeploy_cron_stop => '' },
+						prod    => { alias => 'prod', stage_name => 'prod',
+							auto => 0, type => 'deployment',
+							require_pr => 0, manual => 0,
+							redeploy => 'cron',   redeploy_cron_start => '03:00', redeploy_cron_stop => '04:00' },
+					},
+					edges => [
+						{ from => 'sandbox', to => 'staging' },
+						{ from => 'staging', to => 'prod' },
+					],
+				},
+			},
+		},
+		configuration => {
+			task     => { image => 'genesiscommunity/concourse', version => 'latest' },
+			registry => {},
+		},
+	);
+
+	my $pipeline = _describe($ast);
+
+	my @redeploy_jobs = grep { $_->{name} =~ /^redeploy-/ } @{$pipeline->{jobs}};
+	is scalar @redeploy_jobs, 2, 'only 2 redeploy jobs (staging + prod)';
+
+	my %rj = map { $_->{name} => 1 } @redeploy_jobs;
+	ok $rj{'redeploy-staging'}, 'redeploy-staging present';
+	ok $rj{'redeploy-prod'},    'redeploy-prod present';
+	ok !$rj{'redeploy-sandbox'}, 'no redeploy-sandbox';
+
+	# Cron resource only for prod
+	my @cron_res = grep { ($_->{name} || '') =~ /redeploy-cron/ } @{$pipeline->{resources}};
+	is scalar @cron_res, 1, 'one cron time resource (for prod only)';
+	is $cron_res[0]{name}, 'prod-redeploy-cron', 'cron resource named prod-redeploy-cron';
+
+	# Redeploy group lists both
+	my ($rg) = grep { $_->{name} eq 'redeploy' } @{$pipeline->{groups}};
+	ok $rg, 'redeploy group emitted';
+	is_deeply [sort @{$rg->{jobs}}], ['redeploy-prod', 'redeploy-staging'],
+		'redeploy group lists staging and prod';
+};
+
+done_testing;
diff --git a/t/unit-tests/genesis_ci_pipeline_descriptor-signal.t b/t/unit-tests/genesis_ci_pipeline_descriptor-signal.t
new file mode 100644
index 00000000..6d3fea4b
--- /dev/null
+++ b/t/unit-tests/genesis_ci_pipeline_descriptor-signal.t
@@ -0,0 +1,562 @@
+#!/usr/bin/env perl
+use strict;
+use warnings;
+
+use lib 't';
+use lib 'lib';
+use File::Temp qw/tempdir/;
+use Test::More;
+use Test::Deep;
+
+$ENV{GENESIS_TESTING} = 'yes';
+$ENV{GENESIS_LIB}   ||= 'lib';
+
+use_ok 'Genesis::CI::Compiler::AST';
+use_ok 'Genesis::CI::Compiler::ASTBuilder';
+use_ok 'Genesis::CI::Compiler::PipelineDescriptor';
+
+# =========================================================================
+# Helpers
+# =========================================================================
+
+sub _write {
+	my ($path, $content) = @_;
+	open my $fh, '>', $path or die "Cannot write $path: $!";
+	print $fh $content;
+	close $fh;
+}
+
+# Build a minimal AST with one env and configurable signal/notification/redeploy attributes.
+sub _ast_for {
+	my (%opts) = @_;
+
+	my $env           = $opts{env}           || 'sandbox';
+	my $alias         = $opts{alias}         || $env;
+	my $redeploy      = $opts{redeploy}      || '';
+	my $status_signal = $opts{status_signal} // '';
+	my $signal_prefix = $opts{signal_prefix} || '';
+	my $with_locker   = $opts{with_locker}   // 0;
+	my $create_env    = $opts{create_env}    // 0;
+	my $signal_cfg    = $opts{signal_cfg};     # global status_signal config hashref
+
+	my $target_type = $create_env ? 'bosh-create-env' : 'bosh-director';
+	my %target = (type => $target_type);
+	unless ($create_env) {
+		$target{connection} = {
+			url     => 'https://bosh.example.com:25555',
+			ca_cert => 'fake-ca',
+			auth    => { client_id => 'admin', client_secret => 'secret' },
+		};
+	}
+
+	my %integrations = (
+		source_control => { provider => 'github', repository => 'org/repo' },
+		vault          => { url => 'https://vault.example.com' },
+	);
+	if ($with_locker) {
+		$integrations{locker} = {
+			url      => 'https://locker.example.com',
+			username => 'locker-user',
+			password => 'locker-pass',
+		};
+	}
+	if (my $notif = $opts{notifications}) {
+		$integrations{notifications} = $notif;
+	}
+
+	my %config = (
+		task     => { image => 'genesiscommunity/concourse', version => 'latest' },
+		registry => {},
+	);
+	$config{status_signal} = $signal_cfg if $signal_cfg;
+
+	return Genesis::CI::Compiler::AST->new(
+		metadata     => { name => 'test-pipeline', deployment_type => 'deployment' },
+		branches     => { control => 'main' },
+		integrations => \%integrations,
+		targets      => { $env => \%target },
+		workflows    => {
+			default => {
+				name  => 'default',
+				type  => 'deployment',
+				graph => {
+					nodes => {
+						$env => {
+							alias               => $alias,
+							stage_name          => $env,
+							genesis_env         => $env,
+							auto                => 0,
+							type                => 'deployment',
+							require_pr          => 0,
+							manual              => 0,
+							redeploy            => $redeploy,
+							redeploy_cron_start => '',
+							redeploy_cron_stop  => '',
+							status_signal       => $status_signal,
+							signal_prefix       => $signal_prefix,
+						},
+					},
+					edges => [],
+				},
+			},
+		},
+		configuration => \%config,
+	);
+}
+
+sub _describe {
+	my ($ast) = @_;
+	my $d = Genesis::CI::Compiler::PipelineDescriptor->new(ast => $ast);
+	return $d->describe();
+}
+
+# Extract the plan's do-block from a job's plan[0]
+sub _do_block {
+	my ($job) = @_;
+	my $step = $job->{plan}[0] or return [];
+	return $step->{do} || [];
+}
+
+# Find the in_parallel step within a do-block
+sub _parallel_gets {
+	my ($do) = @_;
+	my ($par) = grep { ref $_ eq 'HASH' && exists $_->{in_parallel} } @$do;
+	return $par ? $par->{in_parallel} : [];
+}
+
+# =========================================================================
+# 1. shuttle resource_type emitted when status_signal is globally configured
+# =========================================================================
+subtest 'shuttle resource_type emitted when status_signal configured' => sub {
+	my $ast = _ast_for(
+		env        => 'sandbox',
+		signal_cfg => { backend => 'file', path => '/tmp/signals' },
+		status_signal => '1',
+	);
+	my $pipeline = _describe($ast);
+
+	my @shuttle = grep { ($_->{name} || '') eq 'shuttle' } @{$pipeline->{resource_types}};
+	is scalar @shuttle, 1, 'one shuttle resource_type entry';
+	is $shuttle[0]{type}, 'registry-image', 'shuttle type is registry-image';
+	like $shuttle[0]{source}{repository}, qr/shuttle/, 'repository contains "shuttle"';
+};
+
+# =========================================================================
+# 2. No shuttle resource_type when status_signal is not configured globally
+# =========================================================================
+subtest 'No shuttle resource_type when status_signal not configured' => sub {
+	my $ast      = _ast_for(env => 'sandbox');
+	my $pipeline = _describe($ast);
+
+	my @shuttle = grep { ($_->{name} || '') eq 'shuttle' } @{$pipeline->{resource_types}};
+	is scalar @shuttle, 0, 'no shuttle resource_type when signal not configured';
+};
+
+# =========================================================================
+# 3. File backend: signal resource emitted with correct source
+# =========================================================================
+subtest 'File backend: signal resource has correct source' => sub {
+	my $ast = _ast_for(
+		env        => 'sandbox',
+		signal_cfg => { backend => 'file', path => '/tmp/genesis-signals' },
+		status_signal => '1',
+	);
+	my $pipeline = _describe($ast);
+
+	my ($res) = grep { ($_->{name} || '') eq 'sandbox-signal' } @{$pipeline->{resources}};
+	ok $res, 'sandbox-signal resource emitted';
+	is $res->{type}, 'shuttle', 'resource type is shuttle';
+	is $res->{source}{backend}, 'file', 'source.backend = file';
+	like $res->{source}{path}, qr{/tmp/genesis-signals}, 'source.path contains base path';
+};
+
+# =========================================================================
+# 4. S3 backend: signal resource has correct source fields
+# =========================================================================
+subtest 'S3 backend: signal resource has bucket/region/credentials' => sub {
+	my $ast = _ast_for(
+		env        => 'sandbox',
+		signal_cfg => {
+			backend           => 's3',
+			bucket            => 'my-signals',
+			region            => 'eu-west-1',
+			access_key_id     => 'AKID',
+			secret_access_key => 'SECRET',
+		},
+		status_signal => '1',
+	);
+	my $pipeline = _describe($ast);
+
+	my ($res) = grep { ($_->{name} || '') eq 'sandbox-signal' } @{$pipeline->{resources}};
+	ok $res, 'sandbox-signal resource emitted';
+	is $res->{source}{backend},            's3',           'source.backend = s3';
+	is $res->{source}{bucket},             'my-signals',   'source.bucket correct';
+	is $res->{source}{region},             'eu-west-1',    'source.region correct';
+	is $res->{source}{access_key_id},      'AKID',         'source.access_key_id correct';
+	is $res->{source}{secret_access_key},  'SECRET',       'source.secret_access_key correct';
+};
+
+# =========================================================================
+# 5. GCS backend: signal resource has bucket and json_key
+# =========================================================================
+subtest 'GCS backend: signal resource has bucket and json_key' => sub {
+	my $ast = _ast_for(
+		env        => 'sandbox',
+		signal_cfg => {
+			backend  => 'gcs',
+			bucket   => 'gcs-signals',
+			json_key => 'gcs-service-account-json',
+		},
+		status_signal => '1',
+	);
+	my $pipeline = _describe($ast);
+
+	my ($res) = grep { ($_->{name} || '') eq 'sandbox-signal' } @{$pipeline->{resources}};
+	ok $res, 'sandbox-signal resource emitted';
+	is $res->{source}{backend},  'gcs',                      'source.backend = gcs';
+	is $res->{source}{bucket},   'gcs-signals',              'source.bucket correct';
+	is $res->{source}{json_key}, 'gcs-service-account-json', 'source.json_key correct';
+};
+
+# =========================================================================
+# 6. Per-env disable: status_signal=false suppresses signal for that env
+# =========================================================================
+subtest 'Per-env disable: status_signal=false suppresses signal resource' => sub {
+	my $ast = Genesis::CI::Compiler::AST->new(
+		metadata     => { name => 'test-pipeline', deployment_type => 'deployment' },
+		branches     => { control => 'main' },
+		integrations => {
+			source_control => { provider => 'github', repository => 'org/repo' },
+			vault          => { url => 'https://vault.example.com' },
+		},
+		targets => {
+			sandbox => { type => 'bosh-director', connection => {
+				url => 'https://bosh.sb', ca_cert => 'c',
+				auth => { client_id => 'u', client_secret => 's' } } },
+			prod    => { type => 'bosh-director', connection => {
+				url => 'https://bosh.pd', ca_cert => 'c',
+				auth => { client_id => 'u', client_secret => 's' } } },
+		},
+		workflows => {
+			default => {
+				name  => 'default',
+				type  => 'deployment',
+				graph => {
+					nodes => {
+						sandbox => {
+							alias => 'sandbox', stage_name => 'sandbox',
+							genesis_env => 'sandbox', auto => 0, type => 'deployment',
+							require_pr => 0, manual => 0,
+							redeploy => '', redeploy_cron_start => '', redeploy_cron_stop => '',
+							status_signal => '1', signal_prefix => '',
+						},
+						prod => {
+							alias => 'prod', stage_name => 'prod',
+							genesis_env => 'prod', auto => 0, type => 'deployment',
+							require_pr => 0, manual => 0,
+							redeploy => '', redeploy_cron_start => '', redeploy_cron_stop => '',
+							status_signal => '0', signal_prefix => '',
+						},
+					},
+					edges => [{ from => 'sandbox', to => 'prod' }],
+				},
+			},
+		},
+		configuration => {
+			task        => { image => 'genesiscommunity/concourse', version => 'latest' },
+			registry    => {},
+			status_signal => { backend => 'file', path => '/tmp/signals' },
+		},
+	);
+	my $pipeline = _describe($ast);
+
+	my ($sb_res) = grep { ($_->{name} || '') eq 'sandbox-signal' } @{$pipeline->{resources}};
+	ok $sb_res, 'sandbox-signal resource emitted (enabled)';
+
+	my ($pd_res) = grep { ($_->{name} || '') eq 'prod-signal' } @{$pipeline->{resources}};
+	ok !$pd_res, 'prod-signal resource NOT emitted (disabled per-env)';
+};
+
+# =========================================================================
+# 7. Prefix: per-env signal_prefix overrides global prefix
+# =========================================================================
+subtest 'Per-env signal_prefix overrides global prefix in resource source' => sub {
+	my $ast = _ast_for(
+		env           => 'sandbox',
+		signal_cfg    => { backend => 'file', path => '/tmp/sig', prefix => 'mypipeline' },
+		status_signal => '1',
+		signal_prefix => 'custom-prefix',
+	);
+	my $pipeline = _describe($ast);
+
+	my ($res) = grep { ($_->{name} || '') eq 'sandbox-signal' } @{$pipeline->{resources}};
+	ok $res, 'sandbox-signal resource emitted';
+	is $res->{source}{prefix}, 'custom-prefix', 'per-env signal_prefix used instead of global';
+};
+
+# =========================================================================
+# 8. All four outcome hooks emitted when signal is configured
+# =========================================================================
+subtest 'All four outcome hooks emitted when signal configured' => sub {
+	my $ast = _ast_for(
+		env        => 'sandbox',
+		signal_cfg => { backend => 'file' },
+		status_signal => '1',
+	);
+	my $pipeline = _describe($ast);
+
+	my ($job) = grep { $_->{name} eq 'sandbox-deployment' } @{$pipeline->{jobs}};
+	ok $job, 'sandbox-deployment job present';
+
+	my $plan_step = $job->{plan}[0];
+	for my $hook (qw(on_success on_failure on_abort on_error)) {
+		ok exists $plan_step->{$hook}, "$hook hook present";
+		my $h = $plan_step->{$hook};
+		if (ref $h eq 'HASH' && $h->{put}) {
+			is $h->{put}, 'sandbox-signal', "$hook put targets sandbox-signal";
+			(my $outcome = $hook) =~ s/^on_//;
+			is $h->{params}{status}, $outcome, "$hook params.status = $outcome";
+		}
+	}
+};
+
+# =========================================================================
+# 9. Notification + signal combined into in_parallel
+# =========================================================================
+subtest 'Notification and signal combined into in_parallel in hooks' => sub {
+	my $ast = _ast_for(
+		env        => 'sandbox',
+		signal_cfg => { backend => 'file' },
+		status_signal => '1',
+		notifications => [
+			{ type => 'slack', webhook => 'https://hooks.slack.com/services/test' },
+		],
+	);
+	my $pipeline = _describe($ast);
+
+	my ($job) = grep { $_->{name} eq 'sandbox-deployment' } @{$pipeline->{jobs}};
+	ok $job, 'sandbox-deployment job present';
+
+	my $plan_step = $job->{plan}[0];
+
+	# on_success: notification + signal → in_parallel
+	my $success = $plan_step->{on_success};
+	ok $success, 'on_success hook present';
+	ok exists $success->{in_parallel}, 'on_success uses in_parallel when both present';
+	my @sp = @{$success->{in_parallel}};
+	my @slack_steps = grep { ref $_ eq 'HASH' && ($_->{put} || '') eq 'slack' } @sp;
+	my @signal_steps = grep { ref $_ eq 'HASH' && ($_->{put} || '') eq 'sandbox-signal' } @sp;
+	is scalar @slack_steps,  1, 'one slack step in on_success in_parallel';
+	is scalar @signal_steps, 1, 'one signal step in on_success in_parallel';
+
+	# on_failure: notification + signal → in_parallel
+	my $failure = $plan_step->{on_failure};
+	ok $failure, 'on_failure hook present';
+	ok exists $failure->{in_parallel}, 'on_failure uses in_parallel when both present';
+
+	# on_abort: signal only (no notification) → direct put, not in_parallel
+	my $abort = $plan_step->{on_abort};
+	ok $abort, 'on_abort hook present';
+	ok !exists $abort->{in_parallel}, 'on_abort is a direct put (no notification)';
+	is $abort->{put}, 'sandbox-signal', 'on_abort put targets sandbox-signal';
+
+	# on_error: same as abort
+	my $error = $plan_step->{on_error};
+	ok $error, 'on_error hook present';
+	ok !exists $error->{in_parallel}, 'on_error is a direct put (no notification)';
+};
+
+# =========================================================================
+# 10. No hooks when neither signal nor notifications configured
+# =========================================================================
+subtest 'No outcome hooks when neither signal nor notifications configured' => sub {
+	my $ast      = _ast_for(env => 'sandbox');
+	my $pipeline = _describe($ast);
+
+	my ($job) = grep { $_->{name} eq 'sandbox-deployment' } @{$pipeline->{jobs}};
+	ok $job, 'sandbox-deployment job present';
+
+	my $plan_step = $job->{plan}[0];
+	for my $hook (qw(on_success on_failure on_abort on_error)) {
+		ok !exists $plan_step->{$hook}, "no $hook hook when no signal or notifications";
+	}
+};
+
+# =========================================================================
+# 11. Redeploy job also gets all four outcome hooks
+# =========================================================================
+subtest 'Redeploy job also gets signal outcome hooks' => sub {
+	my $ast = _ast_for(
+		env           => 'sandbox',
+		redeploy      => 'manual',
+		signal_cfg    => { backend => 'file' },
+		status_signal => '1',
+	);
+	my $pipeline = _describe($ast);
+
+	my ($job) = grep { $_->{name} eq 'redeploy-sandbox' } @{$pipeline->{jobs}};
+	ok $job, 'redeploy-sandbox job present';
+
+	my $plan_step = $job->{plan}[0];
+	for my $hook (qw(on_success on_failure on_abort on_error)) {
+		ok exists $plan_step->{$hook}, "redeploy job has $hook hook";
+	}
+};
+
+# =========================================================================
+# 12. Signal redeploy trigger: redeploy=signal + signal configured
+#     → get sandbox-signal with trigger=true, version={status: success}
+# =========================================================================
+subtest 'Signal redeploy trigger: gets signal resource with trigger=true' => sub {
+	my $ast = _ast_for(
+		env           => 'sandbox',
+		redeploy      => 'signal',
+		signal_cfg    => { backend => 'file' },
+		status_signal => '1',
+	);
+	my $pipeline = _describe($ast);
+
+	my ($job) = grep { $_->{name} eq 'redeploy-sandbox' } @{$pipeline->{jobs}};
+	ok $job, 'redeploy-sandbox job emitted';
+
+	my $do   = _do_block($job);
+	my $gets = _parallel_gets($do);
+
+	my ($sig_get) = grep { ref $_ eq 'HASH' && ($_->{get} || '') eq 'sandbox-signal' } @$gets;
+	ok $sig_get, 'sandbox-signal get step present in redeploy job';
+	is $sig_get->{trigger}, 1, 'trigger=true on signal get';
+	is_deeply $sig_get->{version}, { status => 'success' },
+		'version filter is {status: success}';
+};
+
+# =========================================================================
+# 13. Signal redeploy without signal configured → no signal get, no trigger
+# =========================================================================
+subtest 'Signal redeploy without global signal config: no signal get' => sub {
+	my $ast = _ast_for(env => 'sandbox', redeploy => 'signal');
+	my $pipeline = _describe($ast);
+
+	my ($job) = grep { $_->{name} eq 'redeploy-sandbox' } @{$pipeline->{jobs}};
+	ok $job, 'redeploy-sandbox job emitted';
+
+	my $do   = _do_block($job);
+	my $gets = _parallel_gets($do);
+
+	my @sig_gets = grep { ref $_ eq 'HASH' && ($_->{get} || '') =~ /signal/ } @$gets;
+	is scalar @sig_gets, 0, 'no signal get when global config absent';
+
+	# All gets should have trigger=false (manual-like behaviour)
+	for my $g (@$gets) {
+		next unless ref $g eq 'HASH' && exists $g->{trigger};
+		is $g->{trigger}, 0,
+			"$g->{get} has trigger=false when no signal config";
+	}
+};
+
+# =========================================================================
+# 14. ASTBuilder reads status_signal from env files
+# =========================================================================
+subtest 'ASTBuilder reads status_signal config from env files' => sub {
+	my $tmp = tempdir(CLEANUP => 1);
+
+	_write("$tmp/sandbox.yml", <<'YAML');
+---
+genesis:
+  env: sandbox
+  pipeline:
+    status_signal: s3
+    signal_prefix: my-pipeline/sandbox
+YAML
+	_write("$tmp/prod.yml", <<'YAML');
+---
+genesis:
+  env: prod
+  pipeline:
+    prior_env: sandbox
+    status_signal: false
+YAML
+	_write("$tmp/staging.yml", <<'YAML');
+---
+genesis:
+  env: staging
+  pipeline:
+    prior_env: sandbox
+YAML
+
+	my $builder = Genesis::CI::Compiler::ASTBuilder->new(env_dir => $tmp);
+	my $parsed  = {
+		_source_format => 'multi-file',
+		env_dir        => $tmp,
+		pipeline       => {},
+		targets        => {},
+		integrations   => {},
+		scripts        => {},
+		provider_config => {},
+	};
+	my $ast   = $builder->build($parsed, {});
+	my $nodes = $ast->workflows->{default}{graph}{nodes};
+
+	is $nodes->{sandbox}{status_signal}, 's3',
+		'sandbox: status_signal=s3';
+	is $nodes->{sandbox}{signal_prefix},  'my-pipeline/sandbox',
+		'sandbox: signal_prefix read correctly';
+	is $nodes->{prod}{status_signal}, '0',
+		'prod: status_signal=false normalised to 0';
+	is $nodes->{staging}{status_signal}, '',
+		'staging: no status_signal = empty string';
+};
+
+# =========================================================================
+# 15. Per-env backend override: env-level status_signal=gcs overrides global file
+# =========================================================================
+subtest 'Per-env backend: env-level status_signal overrides global backend' => sub {
+	my $ast = Genesis::CI::Compiler::AST->new(
+		metadata     => { name => 'test-pipeline', deployment_type => 'deployment' },
+		branches     => { control => 'main' },
+		integrations => {
+			source_control => { provider => 'github', repository => 'org/repo' },
+			vault          => { url => 'https://vault.example.com' },
+		},
+		targets => {
+			sandbox => { type => 'bosh-director', connection => {
+				url => 'https://bosh.sb', ca_cert => 'c',
+				auth => { client_id => 'u', client_secret => 's' } } },
+		},
+		workflows => {
+			default => {
+				name  => 'default',
+				type  => 'deployment',
+				graph => {
+					nodes => {
+						sandbox => {
+							alias => 'sandbox', stage_name => 'sandbox',
+							genesis_env => 'sandbox', auto => 0, type => 'deployment',
+							require_pr => 0, manual => 0,
+							redeploy => '', redeploy_cron_start => '', redeploy_cron_stop => '',
+							status_signal => 'gcs', signal_prefix => '',
+						},
+					},
+					edges => [],
+				},
+			},
+		},
+		configuration => {
+			task          => { image => 'genesiscommunity/concourse', version => 'latest' },
+			registry      => {},
+			status_signal => {
+				backend  => 'file',    # global default is file
+				bucket   => 'my-gcs-bucket',
+				json_key => 'json-sa-key',
+			},
+		},
+	);
+	my $pipeline = _describe($ast);
+
+	my ($res) = grep { ($_->{name} || '') eq 'sandbox-signal' } @{$pipeline->{resources}};
+	ok $res, 'sandbox-signal resource emitted';
+	is $res->{source}{backend}, 'gcs',
+		'per-env status_signal=gcs overrides global file backend';
+	is $res->{source}{bucket}, 'my-gcs-bucket', 'bucket from global config preserved';
+};
+
+done_testing;
diff --git a/t/unit-tests/genesis_ci_pipeline_descriptor-task-library.t b/t/unit-tests/genesis_ci_pipeline_descriptor-task-library.t
new file mode 100644
index 00000000..c8d0a182
--- /dev/null
+++ b/t/unit-tests/genesis_ci_pipeline_descriptor-task-library.t
@@ -0,0 +1,371 @@
+#!/usr/bin/env perl
+use strict;
+use warnings;
+
+use lib 't';
+use lib 'lib';
+use Test::More;
+use Test::Deep;
+
+$ENV{GENESIS_TESTING} = 'yes';
+$ENV{GENESIS_LIB}   ||= 'lib';
+
+use_ok 'Genesis::CI::Compiler::AST';
+use_ok 'Genesis::CI::Compiler::PipelineDescriptor';
+
+# =========================================================================
+# Helpers
+# =========================================================================
+
+sub _ast_for {
+	my (%o) = @_;
+
+	my $env   = $o{env}   || 'sandbox';
+	my $alias = $o{alias} || $env;
+
+	my %integrations = (
+		source_control => { provider => 'github', repository => 'org/repo' },
+		vault          => { url => 'https://vault.example.com' },
+	);
+
+	my %config = (
+		task     => { image => 'genesiscommunity/concourse', version => 'latest' },
+		registry => {},
+	);
+	$config{task_library} = $o{task_library} if $o{task_library};
+	$config{errands}      = $o{errands}      if $o{errands};
+
+	my %node = (
+		alias               => $alias,
+		stage_name          => $env,
+		genesis_env         => $env,
+		auto                => $o{auto} // 0,
+		type                => 'deployment',
+		require_pr          => 0,
+		manual              => 0,
+		redeploy            => '',
+		redeploy_cron_start => '',
+		redeploy_cron_stop  => '',
+		status_signal       => '',
+		signal_prefix       => '',
+		bosh_parent         => '',
+		bosh_upgrade_lock   => 1,
+	);
+
+	return Genesis::CI::Compiler::AST->new(
+		metadata     => { name => 'test-pipeline', deployment_type => 'deployment' },
+		branches     => { control => 'main' },
+		integrations => \%integrations,
+		targets      => {
+			$env => {
+				type       => 'bosh-director',
+				connection => {
+					url     => 'https://bosh.example.com:25555',
+					ca_cert => 'fake-ca',
+					auth    => { client_id => 'admin', client_secret => 'secret' },
+				},
+			},
+		},
+		workflows    => {
+			default => {
+				name  => 'default',
+				type  => 'deployment',
+				graph => {
+					nodes => { $env => \%node },
+					edges => $o{edges} || [],
+				},
+			},
+		},
+		configuration => \%config,
+	);
+}
+
+sub _describe {
+	my ($ast) = @_;
+	Genesis::CI::Compiler::PipelineDescriptor->new(ast => $ast)->describe();
+}
+
+sub _find_resource {
+	my ($pipeline, $name) = @_;
+	my ($r) = grep { $_->{name} eq $name } @{$pipeline->{resources}};
+	return $r;
+}
+
+sub _find_job {
+	my ($pipeline, $name) = @_;
+	my ($j) = grep { $_->{name} eq $name } @{$pipeline->{jobs}};
+	return $j;
+}
+
+sub _deploy_gets {
+	my ($pipeline, $job_name) = @_;
+	my $job = _find_job($pipeline, $job_name) or return ();
+	my $do  = ($job->{plan}[0] || {})->{do} || [];
+	my ($parallel) = grep { ref $_ eq 'HASH' && $_->{in_parallel} } @$do;
+	return $parallel ? @{$parallel->{in_parallel}} : ();
+}
+
+sub _errand_steps {
+	my ($pipeline, $job_name) = @_;
+	my $job = _find_job($pipeline, $job_name) or return ();
+	my $do  = ($job->{plan}[0] || {})->{do} || [];
+	return grep { ref $_ eq 'HASH' && ($_->{task} || '') =~ /-errand$/ } @$do;
+}
+
+sub _task_inputs {
+	my ($pipeline, $job_name) = @_;
+	my $job = _find_job($pipeline, $job_name) or return ();
+	my $do  = ($job->{plan}[0] || {})->{do} || [];
+	# Find the deploy task step (has 'task' key and 'config' with inputs)
+	my ($deploy) = grep { ref $_ eq 'HASH' && $_->{task} && $_->{config} } @$do;
+	return $deploy ? @{($deploy->{config} || {})->{inputs} || []} : ();
+}
+
+sub _task_params {
+	my ($pipeline, $job_name) = @_;
+	my $job = _find_job($pipeline, $job_name) or return ();
+	my $do  = ($job->{plan}[0] || {})->{do} || [];
+	my ($deploy) = grep { ref $_ eq 'HASH' && $_->{task} && $_->{config} } @$do;
+	return $deploy ? %{($deploy->{config} || {})->{params} || {}} : ();
+}
+
+# =========================================================================
+# 1. No task library: pipeline unchanged
+# =========================================================================
+subtest 'No task_library config: no tasks resource, no library input' => sub {
+	my $ast = _ast_for();
+	my $pl  = _describe($ast);
+
+	ok(!_find_resource($pl, 'tasks'),
+		'No tasks resource without task_library config');
+
+	my @gets = _deploy_gets($pl, 'sandbox-deployment');
+	ok(!grep({ ref $_ eq 'HASH' && ($_->{get} || '') eq 'tasks' } @gets),
+		'No tasks get step in deploy job without task_library config');
+
+	my @inputs = _task_inputs($pl, 'sandbox-deployment');
+	ok(!grep({ ref $_ eq 'HASH' && ($_->{name} || '') eq 'tasks' } @inputs),
+		'No tasks input in task config without task_library config');
+};
+
+# =========================================================================
+# 2. Basic task library: resource declared, get step added, input added
+# =========================================================================
+subtest 'task_library configured: tasks resource emitted' => sub {
+	my $ast = _ast_for(task_library => {
+		uri    => 'https://github.com/org/pipeline-tasks.git',
+		branch => 'main',
+	});
+	my $pl = _describe($ast);
+
+	my $r = _find_resource($pl, 'tasks');
+	ok($r, 'tasks git resource present');
+	is($r->{type}, 'git',                                      'type is git');
+	is($r->{source}{uri}, 'https://github.com/org/pipeline-tasks.git', 'uri correct');
+	is($r->{source}{branch}, 'main',                           'branch correct');
+	is($r->{icon}, 'source-repository',                        'icon set');
+};
+
+subtest 'task_library: deploy job fetches tasks resource' => sub {
+	my $ast = _ast_for(task_library => {
+		uri => 'https://github.com/org/pipeline-tasks.git',
+	});
+	my $pl   = _describe($ast);
+	my @gets = _deploy_gets($pl, 'sandbox-deployment');
+
+	my ($tl_get) = grep { ref $_ eq 'HASH' && ($_->{get} || '') eq 'tasks' } @gets;
+	ok($tl_get,                       'tasks get step present in deploy job');
+	ok(!$tl_get->{trigger},           'tasks get does not trigger');
+};
+
+subtest 'task_library: task config receives tasks input' => sub {
+	my $ast    = _ast_for(task_library => {
+		uri => 'https://github.com/org/pipeline-tasks.git',
+	});
+	my $pl     = _describe($ast);
+	my @inputs = _task_inputs($pl, 'sandbox-deployment');
+
+	my ($tl_in) = grep { ref $_ eq 'HASH' && ($_->{name} || '') eq 'tasks' } @inputs;
+	ok($tl_in, 'tasks input present in task config');
+};
+
+# =========================================================================
+# 3. Custom resource_name
+# =========================================================================
+subtest 'task_library: custom resource_name used throughout' => sub {
+	my $ast = _ast_for(task_library => {
+		uri           => 'https://github.com/org/tasks.git',
+		resource_name => 'pipeline-tasks',
+	});
+	my $pl = _describe($ast);
+
+	ok(_find_resource($pl, 'pipeline-tasks'), 'resource uses custom name');
+	ok(!_find_resource($pl, 'tasks'),         'default name not created');
+
+	my @gets = _deploy_gets($pl, 'sandbox-deployment');
+	my ($tl_get) = grep { ref $_ eq 'HASH' && ($_->{get} || '') eq 'pipeline-tasks' } @gets;
+	ok($tl_get, 'deploy job fetches pipeline-tasks');
+
+	my @inputs = _task_inputs($pl, 'sandbox-deployment');
+	my ($tl_in) = grep { ref $_ eq 'HASH' && ($_->{name} || '') eq 'pipeline-tasks' } @inputs;
+	ok($tl_in, 'task config input uses pipeline-tasks');
+};
+
+# =========================================================================
+# 4. Path resolution: GENESIS_TASK_LIBRARY_PATH param
+# =========================================================================
+subtest 'task_library without path: GENESIS_TASK_LIBRARY_PATH = resource_name' => sub {
+	my $ast = _ast_for(task_library => {
+		uri => 'https://github.com/org/tasks.git',
+	});
+	my $pl = _describe($ast);
+	my %p  = _task_params($pl, 'sandbox-deployment');
+	is($p{GENESIS_TASK_LIBRARY_PATH}, 'tasks',
+		'GENESIS_TASK_LIBRARY_PATH is resource_name when no path set');
+};
+
+subtest 'task_library with path: GENESIS_TASK_LIBRARY_PATH = resource_name/path' => sub {
+	my $ast = _ast_for(task_library => {
+		uri  => 'https://github.com/org/tasks.git',
+		path => 'tasks',
+	});
+	my $pl = _describe($ast);
+	my %p  = _task_params($pl, 'sandbox-deployment');
+	is($p{GENESIS_TASK_LIBRARY_PATH}, 'tasks/tasks',
+		'GENESIS_TASK_LIBRARY_PATH includes subdirectory');
+};
+
+subtest 'task_library with custom resource_name and path' => sub {
+	my $ast = _ast_for(task_library => {
+		uri           => 'https://github.com/org/tasks.git',
+		resource_name => 'lib',
+		path          => 'ci/tasks',
+	});
+	my $pl = _describe($ast);
+	my %p  = _task_params($pl, 'sandbox-deployment');
+	is($p{GENESIS_TASK_LIBRARY_PATH}, 'lib/ci/tasks',
+		'GENESIS_TASK_LIBRARY_PATH = resource_name/path');
+};
+
+# =========================================================================
+# 5. Auth passthrough for private repos
+# =========================================================================
+subtest 'task_library: ssh-key auth passed to git resource source' => sub {
+	my $ast = _ast_for(task_library => {
+		uri  => 'git@github.com:org/tasks.git',
+		auth => {
+			type        => 'ssh-key',
+			private_key => { secret_ref => 'task-library-key' },
+		},
+	});
+	my $pl = _describe($ast);
+	my $r  = _find_resource($pl, 'tasks');
+
+	ok($r, 'tasks resource present');
+	is($r->{source}{private_key}, '((task-library-key))',
+		'private_key unwrapped from secret_ref');
+	ok(!exists $r->{source}{username}, 'no username for ssh-key');
+};
+
+subtest 'task_library: token auth passed to git resource source' => sub {
+	my $ast = _ast_for(task_library => {
+		uri  => 'https://github.com/org/tasks.git',
+		auth => {
+			type     => 'token',
+			password => { secret_ref => 'library-token' },
+		},
+	});
+	my $pl = _describe($ast);
+	my $r  = _find_resource($pl, 'tasks');
+
+	ok($r, 'tasks resource present');
+	is($r->{source}{username}, 'x-oauth-basic',      'default username for token');
+	is($r->{source}{password}, '((library-token))',  'password unwrapped');
+};
+
+subtest 'task_library: token auth with explicit username' => sub {
+	my $ast = _ast_for(task_library => {
+		uri  => 'https://github.com/org/tasks.git',
+		auth => {
+			type     => 'token',
+			username => 'my-bot',
+			password => '((library-pass))',
+		},
+	});
+	my $pl = _describe($ast);
+	my $r  = _find_resource($pl, 'tasks');
+
+	is($r->{source}{username}, 'my-bot',          'explicit username preserved');
+	is($r->{source}{password}, '((library-pass))', 'password scalar preserved');
+};
+
+# =========================================================================
+# 6. AC3 — Jobs reference library tasks by name (path resolution)
+# =========================================================================
+subtest 'No task_library: errand uses inline config' => sub {
+	my $ast = _ast_for(errands => ['smoke-tests']);
+	my $pl  = _describe($ast);
+	my ($step) = _errand_steps($pl, 'sandbox-deployment');
+
+	ok($step,                           'errand step present');
+	ok(exists $step->{config},          'inline config used without task_library');
+	ok(!exists $step->{file},           'no file reference without task_library');
+};
+
+subtest 'task_library: errand uses file reference resolved from library' => sub {
+	my $ast = _ast_for(
+		errands      => ['smoke-tests'],
+		task_library => { uri => 'https://github.com/org/tasks.git' },
+	);
+	my $pl   = _describe($ast);
+	my ($step) = _errand_steps($pl, 'sandbox-deployment');
+
+	ok($step,                           'errand step present');
+	is($step->{file}, 'tasks/smoke-tests.yml',
+		'file reference is resource_name/errand-name.yml');
+	ok(!exists $step->{config},         'no inline config when library configured');
+};
+
+subtest 'task_library with path: errand file includes subdirectory' => sub {
+	my $ast = _ast_for(
+		errands      => ['acceptance-tests'],
+		task_library => { uri => 'https://github.com/org/tasks.git', path => 'tasks' },
+	);
+	my $pl   = _describe($ast);
+	my ($step) = _errand_steps($pl, 'sandbox-deployment');
+
+	is($step->{file}, 'tasks/tasks/acceptance-tests.yml',
+		'file path is resource_name/path/errand-name.yml');
+};
+
+subtest 'task_library with custom resource_name: errand file uses resource_name' => sub {
+	my $ast = _ast_for(
+		errands      => ['validate'],
+		task_library => {
+			uri           => 'https://github.com/org/tasks.git',
+			resource_name => 'pipeline-tasks',
+			path          => 'errands',
+		},
+	);
+	my $pl   = _describe($ast);
+	my ($step) = _errand_steps($pl, 'sandbox-deployment');
+
+	is($step->{file}, 'pipeline-tasks/errands/validate.yml',
+		'file path uses custom resource_name and path');
+};
+
+subtest 'task_library: multiple errands each get their own file reference' => sub {
+	my $ast = _ast_for(
+		errands      => ['smoke-tests', 'acceptance-tests'],
+		task_library => { uri => 'https://github.com/org/tasks.git', path => 'tasks' },
+	);
+	my $pl    = _describe($ast);
+	my @steps = _errand_steps($pl, 'sandbox-deployment');
+
+	is(scalar @steps, 2, 'two errand steps emitted');
+	my %files = map { $_->{task} => $_->{file} } @steps;
+	is($files{'smoke-tests-errand'},      'tasks/tasks/smoke-tests.yml');
+	is($files{'acceptance-tests-errand'}, 'tasks/tasks/acceptance-tests.yml');
+};
+
+done_testing;
diff --git a/t/unit-tests/genesis_ci_propagation-core.t b/t/unit-tests/genesis_ci_propagation-core.t
new file mode 100644
index 00000000..af4a8ddd
--- /dev/null
+++ b/t/unit-tests/genesis_ci_propagation-core.t
@@ -0,0 +1,347 @@
+#!/usr/bin/env perl
+use strict;
+use warnings;
+
+use lib 't';
+use lib 'lib';
+use Test::More;
+use Test::Deep;
+
+use_ok 'Genesis::CI::Propagation';
+
+# DAG topology used across most tests:
+#
+#   mgmt (root)
+#     └── lab
+#           └── qa
+#                 ├── np1 → prod1
+#                 └── np2 → prod2
+
+my @dag_order = qw(mgmt lab qa np1 np2 prod1 prod2);
+my %parent_of = (
+	lab   => 'mgmt',
+	qa    => 'lab',
+	np1   => 'qa',
+	np2   => 'qa',
+	prod1 => 'np1',
+	prod2 => 'np2',
+);
+
+sub propagate {
+	my (%env_changed) = @_;
+	return Genesis::CI::Propagation::compute_propagation_targets(
+		dag_order   => \@dag_order,
+		parent_of   => \%parent_of,
+		env_changed => \%env_changed,
+	);
+}
+
+sub propagate_scoped {
+	my ($scope, %env_changed) = @_;
+	return Genesis::CI::Propagation::compute_propagation_targets(
+		dag_order   => \@dag_order,
+		parent_of   => \%parent_of,
+		env_changed => \%env_changed,
+		scope       => $scope,
+	);
+}
+
+# =========================================================================
+# Scenario 1: Pure shared change
+# A change to a shared file (used by all) should only target the root.
+# =========================================================================
+subtest 'scenario 1: pure shared change targets root only' => sub {
+	my $targets = propagate(
+		mgmt  => ['lmelt.yml'],
+		lab   => ['lmelt.yml'],
+		qa    => ['lmelt.yml'],
+		np1   => ['lmelt.yml'],
+		np2   => ['lmelt.yml'],
+		prod1 => ['lmelt.yml'],
+		prod2 => ['lmelt.yml'],
+	);
+
+	cmp_deeply $targets, {
+		mgmt => bag('lmelt.yml'),
+	}, "only mgmt is an entry point for shared file";
+};
+
+# =========================================================================
+# Scenario 2: Pure leaf change
+# A file used only by a non-root env goes directly to that env.
+# =========================================================================
+subtest 'scenario 2: pure leaf change targets leaf directly' => sub {
+	my $targets = propagate(
+		lab => ['lmelt-vsphere-canwest-1-lab.yml'],
+	);
+
+	cmp_deeply $targets, {
+		lab => bag('lmelt-vsphere-canwest-1-lab.yml'),
+	}, "lab is direct entry point for its own leaf file";
+};
+
+# =========================================================================
+# Scenario 3: Mixed shared + leaf in one commit
+# Shared file overlap blocks the leaf env — must wait for cascade.
+# =========================================================================
+subtest 'scenario 3: mixed shared + leaf blocks downstream' => sub {
+	my $targets = propagate(
+		mgmt => ['lmelt.yml'],
+		lab  => ['lmelt.yml', 'lmelt-vsphere-canwest-1-lab.yml'],
+	);
+
+	cmp_deeply $targets, {
+		mgmt => bag('lmelt.yml'),
+	}, "lab is blocked because lmelt.yml overlaps with mgmt";
+};
+
+# =========================================================================
+# Scenario 4: Independent changes to different tiers
+# No overlap between the entry points — both propagate simultaneously.
+# =========================================================================
+subtest 'scenario 4: independent changes create parallel entry points' => sub {
+	my $targets = propagate(
+		mgmt => ['lmelt-vsphere-canwest-1-mgmt.yml'],
+		qa   => ['ops/prod-extras.yml'],
+	);
+
+	cmp_deeply $targets, {
+		mgmt => bag('lmelt-vsphere-canwest-1-mgmt.yml'),
+		qa   => bag('ops/prod-extras.yml'),
+	}, "mgmt and qa are independent entry points";
+};
+
+# =========================================================================
+# Scenario 5: New commit while previous in-flight (after mgmt caught up)
+# mgmt already has the shared file (diff empty), lab gets both.
+# =========================================================================
+subtest 'scenario 5: lab unblocked when mgmt is caught up' => sub {
+	# mgmt was already propagated — diff is empty
+	# lab still needs lmelt.yml (from earlier commit) + lab.yml (new commit)
+	my $targets = propagate(
+		lab => ['lmelt.yml', 'lmelt-vsphere-canwest-1-lab.yml'],
+	);
+
+	cmp_deeply $targets, {
+		lab => bag('lmelt.yml', 'lmelt-vsphere-canwest-1-lab.yml'),
+	}, "lab is entry point when mgmt has no changes (already caught up)";
+};
+
+# =========================================================================
+# Scenario 6: Superseded propagation
+# New propagation overwrites previous — latest desired state wins.
+# =========================================================================
+subtest 'scenario 6: superseded propagation targets same env' => sub {
+	# mgmt's diff shows lmelt.yml changed (new version superseding old)
+	my $targets = propagate(
+		mgmt  => ['lmelt.yml'],
+		lab   => ['lmelt.yml'],
+		qa    => ['lmelt.yml'],
+	);
+
+	cmp_deeply $targets, {
+		mgmt => bag('lmelt.yml'),
+	}, "mgmt receives superseding change, downstream blocked";
+};
+
+# =========================================================================
+# Scenario 7: The "lost no-op" — lab.yml only change with shared pending
+# When using HEAD: mgmt is caught up, lab gets everything.
+# =========================================================================
+subtest 'scenario 7: no-op commit picked up on next propagation' => sub {
+	# State: mgmt already has lmelt.yml (propagated earlier)
+	# lab.yml changed in a later commit
+	# lab still needs lmelt.yml (never propagated to lab)
+	# Using HEAD: mgmt diff is empty (caught up), lab gets both
+	my $targets = propagate(
+		lab => ['lmelt.yml', 'lmelt-vsphere-canwest-1-lab.yml'],
+	);
+
+	cmp_deeply $targets, {
+		lab => bag('lmelt.yml', 'lmelt-vsphere-canwest-1-lab.yml'),
+	}, "lab gets both files when mgmt is caught up";
+};
+
+# =========================================================================
+# Scenario 8: Rapid-fire commits
+# Multiple commits accumulated — single propagation captures all.
+# =========================================================================
+subtest 'scenario 8: rapid-fire commits handled correctly' => sub {
+	# Commit A: lmelt.yml
+	# Commit B: lab.yml
+	# Commit C: lmelt.yml again
+	# Single propagation at HEAD (C):
+	my $targets = propagate(
+		mgmt => ['lmelt.yml'],
+		lab  => ['lmelt.yml', 'lmelt-vsphere-canwest-1-lab.yml'],
+		qa   => ['lmelt.yml'],
+	);
+
+	cmp_deeply $targets, {
+		mgmt => bag('lmelt.yml'),
+	}, "only mgmt targeted — lab/qa blocked by shared lmelt.yml overlap";
+};
+
+# =========================================================================
+# After mgmt deploys (rapid-fire follow-up)
+# =========================================================================
+subtest 'scenario 8b: after mgmt deploys, lab gets all accumulated changes' => sub {
+	# mgmt caught up (diff empty), lab still needs both files
+	my $targets = propagate(
+		lab => ['lmelt.yml', 'lmelt-vsphere-canwest-1-lab.yml'],
+		qa  => ['lmelt.yml'],
+	);
+
+	cmp_deeply $targets, {
+		lab => bag('lmelt.yml', 'lmelt-vsphere-canwest-1-lab.yml'),
+	}, "lab is entry point, qa blocked by lmelt.yml overlap with lab";
+};
+
+# =========================================================================
+# Scoped propagation (simulating cascade from env branch)
+# After mgmt deploys: scope is mgmt's children and descendants only.
+# =========================================================================
+subtest 'scoped propagation: cascade after mgmt deploy' => sub {
+	my $targets = propagate_scoped(
+		[qw(lab qa np1 np2 prod1 prod2)],
+		lab  => ['lmelt.yml', 'lmelt-vsphere-canwest-1-lab.yml'],
+		qa   => ['lmelt.yml'],
+		np1  => ['lmelt.yml'],
+		np2  => ['lmelt.yml'],
+	);
+
+	cmp_deeply $targets, {
+		lab => bag('lmelt.yml', 'lmelt-vsphere-canwest-1-lab.yml'),
+	}, "lab is entry point within scope, qa/np blocked by overlap";
+};
+
+# =========================================================================
+# Deep chain: change only affects prod1
+# =========================================================================
+subtest 'deep chain: leaf change at prod1 skips all intermediates' => sub {
+	my $targets = propagate(
+		prod1 => ['lmelt-vsphere-canwest-1-prod1.yml'],
+	);
+
+	cmp_deeply $targets, {
+		prod1 => bag('lmelt-vsphere-canwest-1-prod1.yml'),
+	}, "prod1 is direct entry point, all intermediates skipped";
+};
+
+# =========================================================================
+# Fan-out: change affects both np branches independently
+# =========================================================================
+subtest 'fan-out: independent changes to np1 and np2' => sub {
+	my $targets = propagate(
+		np1 => ['lmelt-vsphere-canwest-1-np1.yml'],
+		np2 => ['lmelt-vsphere-canwest-1-np2.yml'],
+	);
+
+	cmp_deeply $targets, {
+		np1 => bag('lmelt-vsphere-canwest-1-np1.yml'),
+		np2 => bag('lmelt-vsphere-canwest-1-np2.yml'),
+	}, "np1 and np2 are independent entry points (different parents)";
+};
+
+# =========================================================================
+# No changes at all
+# =========================================================================
+subtest 'no changes: empty result' => sub {
+	my $targets = propagate();
+	cmp_deeply $targets, {}, "no changes → no targets";
+};
+
+# =========================================================================
+# Overlap through grandparent (not just direct parent)
+# =========================================================================
+subtest 'grandparent overlap: qa blocked by mgmt via shared file' => sub {
+	my $targets = propagate(
+		mgmt => ['lmelt.yml'],
+		qa   => ['lmelt.yml', 'lmelt-vsphere-canwest-1-qa.yml'],
+	);
+
+	# qa's ancestor chain: qa → lab → mgmt
+	# mgmt has lmelt.yml, qa has lmelt.yml → overlap
+	cmp_deeply $targets, {
+		mgmt => bag('lmelt.yml'),
+	}, "qa blocked by grandparent mgmt through lmelt.yml overlap";
+};
+
+# =========================================================================
+# Partial overlap: some files overlap, some don't — still blocked
+# =========================================================================
+subtest 'partial overlap: any shared file blocks the env' => sub {
+	my $targets = propagate(
+		mgmt => ['lmelt.yml'],
+		lab  => ['lmelt.yml', 'ops/lab-only.yml'],
+	);
+
+	cmp_deeply $targets, {
+		mgmt => bag('lmelt.yml'),
+	}, "lab blocked even though ops/lab-only.yml is independent — lmelt.yml overlaps";
+};
+
+# =========================================================================
+# Deploy-aware overlap: ancestor has a synced-but-undeployed file.
+# env_changed for the ancestor is empty (already propagated) but its
+# env_undeployed is non-empty — descendant must still be blocked.
+# =========================================================================
+subtest 'synced-but-undeployed ancestor blocks descendants' => sub {
+	my $targets = Genesis::CI::Propagation::compute_propagation_targets(
+		dag_order      => \@dag_order,
+		parent_of      => \%parent_of,
+		env_changed    => {
+			# mgmt already has lmelt.yml propagated — nothing to copy
+			lab => ['lmelt.yml', 'lmelt-vsphere-canwest-1-lab.yml'],
+		},
+		env_undeployed => {
+			# mgmt is "synced, pending deploy" — holds lmelt.yml in flight
+			mgmt => ['lmelt.yml'],
+			lab  => ['lmelt.yml', 'lmelt-vsphere-canwest-1-lab.yml'],
+		},
+	);
+
+	cmp_deeply $targets, {}, "lab blocked: mgmt has undeployed lmelt.yml";
+};
+
+# =========================================================================
+# Deploy-aware overlap: undeployed files differ from propagation files.
+# Descendant's files that do NOT overlap with ancestor's undeployed set
+# are allowed through.
+# =========================================================================
+subtest 'deploy_diff only blocks on actual overlap' => sub {
+	my $targets = Genesis::CI::Propagation::compute_propagation_targets(
+		dag_order      => \@dag_order,
+		parent_of      => \%parent_of,
+		env_changed    => {
+			lab => ['lmelt-vsphere-canwest-1-lab.yml'],
+		},
+		env_undeployed => {
+			# mgmt has undeployed mgmt-only.yml — doesn't overlap with lab
+			mgmt => ['lmelt-vsphere-canwest-1-mgmt.yml'],
+			lab  => ['lmelt-vsphere-canwest-1-lab.yml'],
+		},
+	);
+
+	cmp_deeply $targets, {
+		lab => bag('lmelt-vsphere-canwest-1-lab.yml'),
+	}, "lab allowed: mgmt's undeployed set is disjoint from lab's changes";
+};
+
+# =========================================================================
+# env_undeployed defaults to env_changed when not supplied (backwards-
+# compatible with callers that haven't been updated to track deploy state).
+# =========================================================================
+subtest 'env_undeployed defaults to env_changed when omitted' => sub {
+	# Using the original single-diff helper — same result as before
+	my $targets = propagate(
+		mgmt => ['lmelt.yml'],
+		lab  => ['lmelt.yml', 'ops/lab-only.yml'],
+	);
+
+	cmp_deeply $targets, {
+		mgmt => bag('lmelt.yml'),
+	}, "omitting env_undeployed preserves original single-diff behaviour";
+};
+
+done_testing;
diff --git a/t/unit-tests/genesis_commands_env_reason-core.t b/t/unit-tests/genesis_commands_env_reason-core.t
new file mode 100644
index 00000000..8ff02a4e
--- /dev/null
+++ b/t/unit-tests/genesis_commands_env_reason-core.t
@@ -0,0 +1,83 @@
+#!/usr/bin/env perl
+use strict;
+use warnings;
+
+use lib 't';
+use lib 'lib';
+
+use Test::More;
+
+use_ok 'Genesis::Commands::Env';
+
+# Pure-function tests for _format_pipeline_reason.  The callbacks are
+# stubs — no git or vault involved.
+
+my $short = sub { substr($_[0], 0, 7) };
+my $subjects = {
+	'a1b2c3d4e5f6' => 'Refactor bosh envs to hierarchical config',
+	'b2c3d4e5f6a1' => 'Move cloud-config into bosh/ and declare as required_files',
+	'c3d4e5f6a1b2' => 'Use GENESIS_CALLBACK_BIN for in-script genesis calls',
+};
+my $subject_of = sub { $subjects->{$_[0]} // '' };
+
+subtest 'no propagation markers returns undef' => sub {
+	is(
+		Genesis::Commands::Env::_format_pipeline_reason(
+			['h1 First commit', 'h2 Second commit'],
+			$short, $subject_of,
+		),
+		undef,
+	);
+};
+
+subtest 'empty input returns undef' => sub {
+	is(
+		Genesis::Commands::Env::_format_pipeline_reason([], $short, $subject_of),
+		undef,
+	);
+	is(
+		Genesis::Commands::Env::_format_pipeline_reason(undef, $short, $subject_of),
+		undef,
+	);
+};
+
+subtest 'single propagation marker: subject only, no SHA prefix' => sub {
+	# git log is newest-first
+	my @log = (
+		'env_sha1 [pipeline] control@a1b2c3d4e5f6 -> lmelt-vsphere-canwest-1-mgmt',
+	);
+	my $got = Genesis::Commands::Env::_format_pipeline_reason(\@log, $short, $subject_of);
+	is($got, 'Refactor bosh envs to hierarchical config');
+};
+
+subtest 'multi-commit: count header + bulleted subjects, oldest-first' => sub {
+	# log is newest-first — reason should reverse to oldest-first
+	my @log = (
+		'env_sha3 [pipeline] control@c3d4e5f6a1b2 -> lmelt-vsphere-canwest-1-mgmt',
+		'env_sha2 [pipeline] control@b2c3d4e5f6a1 -> lmelt-vsphere-canwest-1-mgmt',
+		'env_sha1 [pipeline] control@a1b2c3d4e5f6 -> lmelt-vsphere-canwest-1-mgmt',
+	);
+	my $got = Genesis::Commands::Env::_format_pipeline_reason(\@log, $short, $subject_of);
+	is($got, join("\n",
+		'3 commits:',
+		'  - Refactor bosh envs to hierarchical config',
+		'  - Move cloud-config into bosh/ and declare as required_files',
+		'  - Use GENESIS_CALLBACK_BIN for in-script genesis calls',
+	));
+};
+
+subtest 'non-marker lines are skipped' => sub {
+	my @log = (
+		'env_sha2 [pipeline] control@b2c3d4e5f6a1 -> lmelt-vsphere-canwest-1-mgmt',
+		'env_sha1b Hotfix on env branch',
+		'env_sha1 [pipeline] control@a1b2c3d4e5f6 -> lmelt-vsphere-canwest-1-mgmt',
+	);
+	my $got = Genesis::Commands::Env::_format_pipeline_reason(\@log, $short, $subject_of);
+	is($got, join("\n",
+		'2 commits:',
+		'  - Refactor bosh envs to hierarchical config',
+		'  - Move cloud-config into bosh/ and declare as required_files',
+	));
+};
+
+done_testing;
diff --git a/t/unit-tests/genesis_commands_repo_ci-core.t b/t/unit-tests/genesis_commands_repo_ci-core.t
new file mode 100644
index 00000000..bd30857c
--- /dev/null
+++ b/t/unit-tests/genesis_commands_repo_ci-core.t
@@ -0,0 +1,401 @@
+#!/usr/bin/env perl
+use strict;
+use warnings;
+
+use lib 't';
+use helper;
+
+use Genesis;
+use Genesis::Config;
+use_ok 'Genesis::Commands::Repo';
+use_ok 'Genesis::Top';
+
+my $tmp = workdir();
+
+### Helpers ###################################################################
+
+# Minimal .genesis/config that looks like a Genesis repo
+sub make_repo {
+	my ($dir, %opts) = @_;
+	my $genesis_dir = "$dir/.genesis";
+	mkdir_or_fail($genesis_dir);
+
+	my $content = "---\ncreator_version: 3.0.0\ndeployment_type: test-kit\nversion: 2\n";
+	if ($opts{ci_provider}) {
+		$content .= "ci:\n  provider: $opts{ci_provider}\n";
+	}
+	mkfile_or_fail("$genesis_dir/config", $content);
+	return $dir;
+}
+
+### Tests #####################################################################
+
+subtest 'repo_init writes ci.provider to .genesis/config' => sub {
+	my $dir = workdir("repo-init-1");
+	make_repo($dir);
+
+	# Call the private _write_ci_config logic directly via a Genesis::Config
+	# object so we test the config writing without needing a full Top object.
+	my $config = Genesis::Config->new("$dir/.genesis/config", 1);
+	$config->set('ci.provider', 'concourse', 1);
+
+	my $config2 = Genesis::Config->new("$dir/.genesis/config");
+	ok $config2->has('ci.provider'), "ci.provider key written";
+	is $config2->get('ci.provider'), 'concourse', "ci.provider value is 'concourse'";
+};
+
+subtest 'repo_init scaffold: targets.yml created' => sub {
+	my $dir = workdir("repo-init-scaffold");
+	make_repo($dir);
+	mkdir_or_fail("$dir/.genesis/ci");
+
+	Genesis::Commands::Repo::_write_if_absent(
+		"$dir/.genesis/ci/targets.yml",
+		Genesis::Commands::Repo::_targets_scaffold()
+	);
+
+	ok -f "$dir/.genesis/ci/targets.yml", "targets.yml exists";
+	my $content = slurp("$dir/.genesis/ci/targets.yml");
+	like $content, qr/targets:\s*\{\}/, "contains empty targets map";
+	like $content, qr/bosh-director/, "contains bosh-director comment";
+};
+
+subtest 'repo_init scaffold: resources.yml created' => sub {
+	my $dir = workdir("repo-init-resources");
+	make_repo($dir);
+	mkdir_or_fail("$dir/.genesis/ci");
+
+	Genesis::Commands::Repo::_write_if_absent(
+		"$dir/.genesis/ci/resources.yml",
+		Genesis::Commands::Repo::_resources_scaffold()
+	);
+
+	ok -f "$dir/.genesis/ci/resources.yml", "resources.yml exists";
+	my $content = slurp("$dir/.genesis/ci/resources.yml");
+	like $content, qr/resources:\s*\[\]/, "contains empty resources list";
+};
+
+subtest 'repo_init scaffold: ci-overrides file created' => sub {
+	my $dir = workdir("repo-init-overrides");
+	make_repo($dir);
+	mkdir_or_fail("$dir/.genesis/ci");
+
+	Genesis::Commands::Repo::_write_if_absent(
+		"$dir/.genesis/ci/ci-overrides-concourse.yml",
+		Genesis::Commands::Repo::_overrides_scaffold('concourse')
+	);
+
+	ok -f "$dir/.genesis/ci/ci-overrides-concourse.yml", "override file exists";
+	my $content = slurp("$dir/.genesis/ci/ci-overrides-concourse.yml");
+	like $content, qr/ci-overrides-concourse/, "contains provider name in header";
+	like $content, qr/spruce/i, "references spruce in comment";
+};
+
+subtest 'repo_init scaffold: integrations.yml written with provided values' => sub {
+	my $dir = workdir("repo-init-integrations");
+	make_repo($dir);
+	my $ci_dir = "$dir/.genesis/ci";
+	mkdir_or_fail($ci_dir);
+
+	my $cfg = {
+		ci_provider   => 'concourse',
+		pipeline_name => 'my-pipeline',
+		git_uri       => 'git@github.com:example/repo.git',
+		git_branch    => 'main',
+		vault_url     => 'https://vault.example.com:8200',
+	};
+	Genesis::Commands::Repo::_write_integrations($ci_dir, $cfg);
+
+	ok -f "$ci_dir/integrations.yml", "integrations.yml exists";
+	my $content = slurp("$ci_dir/integrations.yml");
+	like $content, qr|https://vault\.example\.com:8200|, "vault url present";
+	like $content, qr|git\@github\.com:example/repo\.git|, "git uri present";
+	like $content, qr/default_branch:\s*main/, "branch present";
+};
+
+subtest '_write_if_absent: does not overwrite existing file' => sub {
+	my $dir = workdir("repo-init-absent");
+	make_repo($dir);
+	mkdir_or_fail("$dir/.genesis/ci");
+
+	mkfile_or_fail("$dir/.genesis/ci/targets.yml", "---\ncustom: true\n");
+
+	Genesis::Commands::Repo::_write_if_absent(
+		"$dir/.genesis/ci/targets.yml",
+		Genesis::Commands::Repo::_targets_scaffold()
+	);
+
+	my $content = slurp("$dir/.genesis/ci/targets.yml");
+	like $content, qr/custom: true/, "existing content preserved";
+	unlike $content, qr/targets: \{\}/, "scaffold not written over existing file";
+};
+
+subtest 'repo_init guard: errors if ci.provider already set' => sub {
+	my $dir = workdir("repo-init-guard");
+	make_repo($dir, ci_provider => 'concourse');
+
+	# We test the guard condition in isolation by reading the config directly
+	my $config = Genesis::Config->new("$dir/.genesis/config");
+	ok $config->has('ci.provider'), "guard precondition: ci.provider is set";
+
+	# The actual bail() in repo_init would fire here; we just verify the
+	# config state that triggers it rather than calling the full command
+	# (which requires a Top object and exits via bail).
+	is $config->get('ci.provider'), 'concourse', "guard sees correct provider value";
+};
+
+subtest 'repo_update --ci-provider: _apply_ci_flags updates only provider' => sub {
+	my $dir = workdir("repo-update-provider");
+	make_repo($dir, ci_provider => 'concourse');
+	my $ci_dir = "$dir/.genesis/ci";
+	mkdir_or_fail($ci_dir);
+
+	# Pre-populate integrations.yml with known content
+	mkfile_or_fail("$ci_dir/integrations.yml", <<'YAML');
+---
+vault:
+  url: https://vault.example.com:8200
+source_control:
+  uri: git@github.com:org/repo.git
+  default_branch: main
+YAML
+
+	my $config = Genesis::Config->new("$dir/.genesis/config", 1);
+
+	# Simulate what _apply_ci_flags does for --ci-provider only
+	$config->set('ci.provider', 'github-actions', 1);
+
+	my $config2 = Genesis::Config->new("$dir/.genesis/config");
+	is $config2->get('ci.provider'), 'github-actions', "provider updated to github-actions";
+
+	# integrations.yml should be unchanged
+	my $integrations = slurp("$ci_dir/integrations.yml");
+	like $integrations, qr|https://vault\.example\.com:8200|, "integrations.yml untouched";
+};
+
+subtest 'repo_update _apply_ci_flags: patches integrations.yml fields in place' => sub {
+	my $dir = workdir("repo-update-integrations");
+	make_repo($dir, ci_provider => 'concourse');
+	my $ci_dir = "$dir/.genesis/ci";
+	mkdir_or_fail($ci_dir);
+
+	mkfile_or_fail("$ci_dir/integrations.yml", <<'YAML');
+---
+vault:
+  url: https://old-vault.example.com:8200
+source_control:
+  uri: git@github.com:org/old-repo.git
+  default_branch: master
+YAML
+
+	# Simulate _apply_ci_flags with --vault-url and --git-branch
+	my $raw = slurp("$ci_dir/integrations.yml");
+	my $new_vault = 'https://new-vault.example.com:8200';
+	my $new_branch = 'main';
+	$raw =~ s/^(\s{0,4}url:\s*)\S+/$1$new_vault/m;
+	$raw =~ s/^(\s{0,4}default_branch:\s*)\S+/$1$new_branch/m;
+	mkfile_or_fail("$ci_dir/integrations.yml", $raw);
+
+	my $content = slurp("$ci_dir/integrations.yml");
+	like   $content, qr|https://new-vault\.example\.com:8200|, "vault url updated";
+	like   $content, qr/default_branch:\s*main/,               "branch updated to main";
+	unlike $content, qr/master/,                               "old branch removed";
+	like   $content, qr|git\@github\.com:org/old-repo\.git|,   "git uri unchanged";
+};
+
+subtest '_existing_ci_defaults: reads values from integrations.yml' => sub {
+	my $dir = workdir("repo-defaults");
+	make_repo($dir, ci_provider => 'concourse');
+	my $ci_dir = "$dir/.genesis/ci";
+	mkdir_or_fail($ci_dir);
+
+	mkfile_or_fail("$ci_dir/integrations.yml", <<'YAML');
+---
+vault:
+  url: https://vault.corp.example.com:8200
+  namespace: genesis
+source_control:
+  uri: git@github.com:corp/deployments.git
+  default_branch: trunk
+YAML
+
+	# Test the extraction logic from _existing_ci_defaults in isolation
+	my $raw = slurp("$ci_dir/integrations.yml");
+	my ($vault_url, $git_uri, $git_branch);
+	($vault_url) = $raw =~ /url:\s*(\S+)/;
+	($git_uri)   = $raw =~ /uri:\s*(\S+)/;
+	($git_branch) = $raw =~ /default_branch:\s*(\S+)/;
+
+	is $vault_url,  'https://vault.corp.example.com:8200', "vault url extracted";
+	is $git_uri,    'git@github.com:corp/deployments.git', "git uri extracted";
+	is $git_branch, 'trunk',                               "branch extracted";
+};
+
+### Config v3 validation tests ################################################
+
+$Genesis::RC = Genesis::Config->new("$ENV{HOME}/.genesis/config");
+
+sub make_v3_repo {
+	my ($dir, %opts) = @_;
+	my $genesis_dir = "$dir/.genesis";
+	mkdir_or_fail($genesis_dir);
+
+	my $version = $opts{version} // 3;
+	my $content = "---\ncreator_version: 3.2.0\ndeployment_type: test-kit\nversion: $version\n";
+	if ($opts{ci}) {
+		$content .= "ci:\n";
+		for my $key (sort keys %{$opts{ci}}) {
+			my $val = $opts{ci}{$key};
+			if (ref($val) eq 'HASH') {
+				$content .= "  $key:\n";
+				for my $subkey (sort keys %$val) {
+					$content .= "    $subkey: $val->{$subkey}\n";
+				}
+			} else {
+				$content .= "  $key: $val\n";
+			}
+		}
+	}
+	mkfile_or_fail("$genesis_dir/config", $content);
+	return $dir;
+}
+
+subtest 'v2 config loads and augments ci.enabled default' => sub {
+	my $dir = make_v3_repo(workdir("v2-augment"), version => 2);
+
+	my $top = Genesis::Top->new($dir, no_vault => 1);
+	ok !$top->ci_enabled, "ci_enabled is false for v2 config";
+	ok !$top->ci_configured, "ci_configured is false for v2 config";
+	is $top->config->get('ci.enabled'), 0, "ci.enabled defaults to false";
+	is $top->config->get_source('ci'), 'default', "ci section comes from default layer";
+};
+
+subtest 'v2 config with ci.yml bails' => sub {
+	my $dir = make_v3_repo(workdir("v2-ci-yml"), version => 2);
+	mkfile_or_fail("$dir/ci.yml", "---\npipeline:\n  layouts:\n    - sandbox\n");
+
+	my $top = Genesis::Top->new($dir, no_vault => 1);
+	eval { $top->config };
+	like $@, qr/Legacy CI configuration/, "v2 + ci.yml bails with migration message";
+	like $@, qr/repo-init --upgrade/, "bail message mentions upgrade command";
+};
+
+subtest 'v3 config validates with CI disabled' => sub {
+	my $dir = make_v3_repo(workdir("v3-disabled"), ci => { enabled => 'false' });
+
+	my $top = Genesis::Top->new($dir, no_vault => 1);
+	ok !$top->ci_enabled, "ci_enabled is false";
+	ok !$top->ci_configured, "ci_configured is false";
+};
+
+subtest 'v3 config validates with CI enabled and provider' => sub {
+	my $dir = make_v3_repo(workdir("v3-enabled"), ci => {
+		enabled  => 'true',
+		provider => { type => 'concourse', target => 'pipes/lmelt', url => 'https://pipes.example.com', team => 'lmelt' },
+		name => 'bosh',
+	});
+
+	my $top = Genesis::Top->new($dir, no_vault => 1);
+	ok $top->ci_enabled, "ci_enabled is true";
+	ok $top->ci_configured, "ci_configured is true";
+	is $top->config->get('ci.provider.type'), 'concourse', "provider type is concourse";
+	is $top->config->get('ci.provider.target'), 'pipes/lmelt', "provider target correct";
+	is $top->config->get('ci.name'), 'bosh', "ci name correct";
+};
+
+subtest 'v3 config bails when enabled but no provider' => sub {
+	my $dir = make_v3_repo(workdir("v3-no-provider"), ci => { enabled => 'true' });
+
+	my $top = Genesis::Top->new($dir, no_vault => 1);
+	eval { $top->config };
+	like $@, qr/missing required key/, "bails when enabled without provider";
+	like $@, qr/provider/, "bail message references provider";
+};
+
+subtest 'v3 config with ci.yml and CI configured bails with conflict' => sub {
+	my $dir = make_v3_repo(workdir("v3-conflict"), ci => {
+		enabled  => 'true',
+		provider => { type => 'concourse', target => 'pipes/test', url => 'https://ci.example.com', team => 'test' },
+	});
+	mkfile_or_fail("$dir/ci.yml", "---\npipeline:\n  layouts:\n    - sandbox\n");
+
+	my $top = Genesis::Top->new($dir, no_vault => 1);
+	eval { $top->config };
+	like $@, qr/conflicts/, "v3 + ci.yml + configured CI bails with conflict message";
+};
+
+subtest 'v3 config with ci.yml and CI not configured bails with migrate' => sub {
+	my $dir = make_v3_repo(workdir("v3-migrate"), ci => { enabled => 'false' });
+	mkfile_or_fail("$dir/ci.yml", "---\npipeline:\n  layouts:\n    - sandbox\n");
+
+	my $top = Genesis::Top->new($dir, no_vault => 1);
+	eval { $top->config };
+	like $@, qr/Legacy CI configuration/, "v3 + ci.yml + disabled CI bails with migrate message";
+	like $@, qr/repo-init --upgrade/, "mentions upgrade command";
+};
+
+subtest 'v3 config rejects unknown ci keys' => sub {
+	my $dir = workdir("v3-unknown-key");
+	mkdir_or_fail("$dir/.genesis");
+	mkfile_or_fail("$dir/.genesis/config", <<EOF);
+---
+creator_version: 3.2.0
+deployment_type: test-kit
+version: 3
+ci:
+  enabled: false
+  bogus_key: should_fail
+EOF
+
+	my $top = Genesis::Top->new($dir, no_vault => 1);
+	eval { $top->config };
+	like $@, qr/unknown configuration key/, "rejects unknown key in ci section";
+	like $@, qr/bogus_key/, "error mentions the offending key";
+};
+
+subtest 'v3 config rejects invalid provider type' => sub {
+	my $dir = workdir("v3-bad-provider");
+	mkdir_or_fail("$dir/.genesis");
+	mkfile_or_fail("$dir/.genesis/config", <<EOF);
+---
+creator_version: 3.2.0
+deployment_type: test-kit
+version: 3
+ci:
+  enabled: true
+  provider:
+    type: jenkins
+EOF
+
+	my $top = Genesis::Top->new($dir, no_vault => 1);
+	eval { $top->config };
+	like $@, qr/jenkins|expected/, "rejects invalid provider type enum value";
+};
+
+subtest 'v2 config write-back does not persist ci defaults' => sub {
+	my $dir = make_v3_repo(workdir("v2-writeback"), version => 2);
+
+	my $top = Genesis::Top->new($dir, no_vault => 1);
+	# ci.enabled should be accessible
+	is $top->config->get('ci.enabled'), 0, "ci.enabled is available via get";
+
+	# But _explicit_contents (what gets saved) should NOT have ci
+	my $explicit = $top->config->_explicit_contents;
+	ok !exists $explicit->{ci}, "ci section not in explicit contents (won't persist)";
+};
+
+subtest 'new repos created with LATEST_CONFIG_VERSION' => sub {
+	is Genesis::Top::LATEST_CONFIG_VERSION(), 3, "LATEST_CONFIG_VERSION is 3";
+};
+
+subtest 'ci_control_branch returns constant for MVP' => sub {
+	my $dir = make_v3_repo(workdir("v3-control"), ci => {
+		enabled  => 'true',
+		provider => { type => 'concourse', target => 'pipes/test', url => 'https://ci.example.com', team => 'test' },
+	});
+
+	my $top = Genesis::Top->new($dir, no_vault => 1);
+	is $top->ci_control_branch, 'control', "ci_control_branch returns 'control'";
+};
+
+done_testing;
diff --git a/t/unit-tests/genesis_config-core.t b/t/unit-tests/genesis_config-core.t
index e744a0da..a8ac3861 100644
--- a/t/unit-tests/genesis_config-core.t
+++ b/t/unit-tests/genesis_config-core.t
@@ -894,6 +894,56 @@ subtest 'validate() integer type accepts zero and rejects leading zeros' => sub
 	);
 };
 
+subtest 'conditional required (polymorphic)' => sub {
+	local $ENV{NOCOLOR} = 1;
+	my $schema = {
+		mode => {type => 'string', required => 1},
+		target => {type => 'string', required => 'mode'},
+		url => {type => 'string', required => {mode => 'remote'}},
+		port => {type => 'number', required => {mode => 'remote'}},
+	};
+
+	# mode=local, no target → fails (required => 'mode' means required when mode is truthy)
+	my $c1 = Genesis::Config->new(undef, 0, {mode => 'local'});
+	throws_ok(
+		sub { $c1->validate($schema) },
+		qr/target: missing required key/,
+		"required => 'sibling': fails when sibling is truthy and key missing"
+	);
+
+	# mode=local, target present, no url → ok (url only required when mode eq 'remote')
+	my $c2 = Genesis::Config->new(undef, 0, {mode => 'local', target => '/tmp'});
+	lives_ok(
+		sub { $c2->validate($schema) },
+		"required => {mode => 'remote'}: passes when mode is 'local'"
+	);
+
+	# mode=remote, target present, no url → fails
+	my $c3 = Genesis::Config->new(undef, 0, {mode => 'remote', target => 'srv1'});
+	throws_ok(
+		sub { $c3->validate($schema) },
+		qr/url: missing required key/,
+		"required => {mode => 'remote'}: fails when mode is 'remote' and key missing"
+	);
+
+	# mode=remote, all present → passes
+	my $c4 = Genesis::Config->new(undef, 0, {mode => 'remote', target => 'srv1', url => 'http://x', port => 8080});
+	lives_ok(
+		sub { $c4->validate($schema) },
+		"required => {mode => 'remote'}: passes when all keys present"
+	);
+
+	# required => 0 means not required
+	my $schema2 = {
+		name => {type => 'string', required => 0},
+	};
+	my $c5 = Genesis::Config->new(undef, 0, {});
+	lives_ok(
+		sub { $c5->validate($schema2) },
+		"required => 0 means not required"
+	);
+};
+
 done_testing;
 
 # vim: ts=2 sw=2 sts=2 noet fdm=marker foldlevel=1 nu
diff --git a/t/unit-tests/genesis_env_required_files-core.t b/t/unit-tests/genesis_env_required_files-core.t
new file mode 100644
index 00000000..225f1506
--- /dev/null
+++ b/t/unit-tests/genesis_env_required_files-core.t
@@ -0,0 +1,140 @@
+#!/usr/bin/env perl
+use strict;
+use warnings;
+
+use lib 't';
+use lib 'lib';
+
+use Test::More;
+use Test::Deep;
+use Test::Fatal;
+use File::Temp qw/tempdir/;
+use File::Path qw/make_path/;
+
+use_ok 'Genesis::Env';
+
+# Build a small scratch tree for glob resolution
+my $root = tempdir(CLEANUP => 1);
+make_path("$root/cloud-config");
+make_path("$root/overrides");
+for my $rel (qw(
+	cloud-config/lmelt.yml
+	cloud-config/lmelt-vsphere-canwest-1-mgmt.yml
+	cloud-config/lmelt-vsphere-canwest-1-lab.yml
+	overrides/net.yml
+	overrides/storage.yml
+)) {
+	open my $fh, '>', "$root/$rel" or die $!;
+	close $fh;
+}
+
+subtest 'empty / malformed inputs return empty' => sub {
+	is_deeply([Genesis::Env->_resolve_required_files(undef, 'x', $root)], []);
+	is_deeply([Genesis::Env->_resolve_required_files([], 'x', $root)], []);
+	is_deeply([Genesis::Env->_resolve_required_files(['foo'], 'x', undef)], []);
+	is_deeply([Genesis::Env->_resolve_required_files(['foo'], 'x', '')], []);
+	is_deeply([Genesis::Env->_resolve_required_files(
+		[undef, '', 'keep'], 'x', $root
+	)], ['keep'], 'skips undef/empty entries');
+};
+
+subtest '<env> placeholder substitution' => sub {
+	is_deeply(
+		[Genesis::Env->_resolve_required_files(
+			['cloud-config/<env>.yml'],
+			'lmelt-vsphere-canwest-1-mgmt',
+			$root,
+		)],
+		['cloud-config/lmelt-vsphere-canwest-1-mgmt.yml'],
+	);
+};
+
+subtest 'literal paths pass through verbatim even if nonexistent' => sub {
+	is_deeply(
+		[Genesis::Env->_resolve_required_files(
+			['cloud-config/absent.yml', 'overrides/net.yml'],
+			'any',
+			$root,
+		)],
+		['cloud-config/absent.yml', 'overrides/net.yml'],
+		'literal paths returned whether or not they exist',
+	);
+};
+
+subtest 'glob expansion is relative to git root' => sub {
+	my @got = Genesis::Env->_resolve_required_files(
+		['overrides/*.yml'],
+		'whatever',
+		$root,
+	);
+	is_deeply(\@got, ['overrides/net.yml', 'overrides/storage.yml']);
+};
+
+subtest 'placeholder + glob combine naturally' => sub {
+	# <env> expanded first, then glob
+	my @got = Genesis::Env->_resolve_required_files(
+		['cloud-config/lmelt-vsphere-canwest-1-*.yml'],
+		'ignored',
+		$root,
+	);
+	is_deeply(\@got, [
+		'cloud-config/lmelt-vsphere-canwest-1-lab.yml',
+		'cloud-config/lmelt-vsphere-canwest-1-mgmt.yml',
+	]);
+};
+
+subtest 'duplicates are de-duplicated; output sorted' => sub {
+	my @got = Genesis::Env->_resolve_required_files(
+		[
+			'overrides/net.yml',
+			'overrides/*.yml',           # also matches overrides/net.yml
+			'cloud-config/<env>.yml',
+		],
+		'lmelt-vsphere-canwest-1-mgmt',
+		$root,
+	);
+	is_deeply(\@got, [
+		'cloud-config/lmelt-vsphere-canwest-1-mgmt.yml',
+		'overrides/net.yml',
+		'overrides/storage.yml',
+	]);
+};
+
+subtest 'unmatched glob returns nothing' => sub {
+	is_deeply(
+		[Genesis::Env->_resolve_required_files(
+			['no-such-dir/*.yml'],
+			'x',
+			$root,
+		)],
+		[],
+	);
+};
+
+subtest 'path-safety rule bails on escape attempts' => sub {
+	for my $bad (
+		'/etc/passwd',
+		'/absolute/cloud-config.yml',
+		'~/secrets.yml',
+		'../escape.yml',
+		'cloud-config/../../escape.yml',
+		'a/b/../c/../../d.yml',
+	) {
+		like(
+			exception {
+				Genesis::Env->_resolve_required_files([$bad], 'x', $root);
+			},
+			qr/escapes/,
+			"rejects $bad",
+		);
+	}
+
+	# '..' embedded in a filename (not a segment) is allowed
+	is_deeply(
+		[Genesis::Env->_resolve_required_files(['foo..bar.yml'], 'x', $root)],
+		['foo..bar.yml'],
+		"'..' inside a filename is not treated as traversal",
+	);
+};
+
+done_testing;
diff --git a/t/unit-tests/genesis_top-core.t b/t/unit-tests/genesis_top-core.t
index e5c259e2..0241d112 100644
--- a/t/unit-tests/genesis_top-core.t
+++ b/t/unit-tests/genesis_top-core.t
@@ -199,7 +199,7 @@ subtest 'repo creation with no_vault' => sub {
 
 	# Verify config contents
 	my $config = $top->config->_explicit_contents;
-	is($config->{version}, 2, "config has version 2");
+	is($config->{version}, 3, "config has version 3 (LATEST_CONFIG_VERSION)");
 	is($config->{deployment_type}, "testkit", "config has correct deployment_type");
 	is($config->{creator_version}, "3.1.0", "config has creator_version");
 
@@ -216,7 +216,7 @@ subtest 'repo creation with no_vault' => sub {
 	# Verify the actual .genesis/config file matches expected structure
 	yaml_is get_file("$tmp/.genesis/config"), <<EOF, ".genesis/config file has correct content";
 ---
-version: 2
+version: 3
 deployment_type: testkit
 creator_version: "3.1.0"
 minimum_version: "3.1.0"
diff --git a/t/unit-tests/genesis_ui-choice.t b/t/unit-tests/genesis_ui-choice.t
index a276a621..19d7f440 100644
--- a/t/unit-tests/genesis_ui-choice.t
+++ b/t/unit-tests/genesis_ui-choice.t
@@ -525,4 +525,95 @@ subtest 'new_prompt_for_choice header auto-generated when omitted' => sub {
 	like($out, qr/Select one of the following/, 'auto-generated header shown');
 };
 
+# ── Regression tests for bugs found during FWT-915/919 ──────────────────────
+
+subtest 'new_prompt_for_choice no default does not auto-select first item' => sub {
+	plan tests => 3;
+
+	# Without a default, pressing Enter should re-prompt (not select
+	# item 1).  Feed blank + valid selection to verify re-prompting
+	# occurred.  Bug: undef == 0 in numeric context made the first
+	# item the implicit default.
+	set_stdin("\n2\n");
+	my $result;
+	my $out = combined_from {
+		$result = new_prompt_for_choice(
+			header  => "Pick:",
+			choices => [qw(alpha beta gamma)],
+			# no default
+		);
+	};
+	reset_stdin();
+
+	is($result, 'beta', 'blank enter without default re-prompts; second input accepted');
+	my @prompts = ($out =~ /Select choice >/g);
+	cmp_ok(scalar @prompts, '>=', 2, 'prompt appeared at least twice (re-prompted after blank enter)');
+	like($out, qr/No default/, 'error message shown on blank enter without default');
+};
+
+subtest 'new_prompt_for_choice separator does not corrupt numbering' => sub {
+	plan tests => 2;
+
+	# Choices with a separator: the separator should not get a number,
+	# and items after it should be numbered contiguously.
+	# Bug: $section_offset was a package global that leaked between
+	# calls, causing items to start at 0 instead of 1.
+	set_stdin("3\n");
+	my $result;
+	my $out = combined_from {
+		$result = new_prompt_for_choice(
+			header  => "Pick:",
+			choices => [
+				{value => 'a', label => 'Alpha'},
+				{value => 'b', label => 'Beta'},
+				{separator => 1},
+				{value => 'c', label => 'Gamma'},
+			],
+		);
+	};
+	reset_stdin();
+
+	is($result, 'c', 'item after separator selected by correct number');
+	like($out, qr/1\) Alpha.*2\) Beta.*3\) Gamma/s,
+		'items numbered 1-3 with separator consuming no number');
+};
+
+subtest 'new_prompt_for_choice numbering correct across sequential calls' => sub {
+	plan tests => 2;
+
+	# Two calls in a row: the second call should start numbering at 1,
+	# not carry over $section_offset from the first call.
+	# Bug: $section_offset was a package global.
+
+	# First call — has a separator
+	set_stdin("1\n");
+	my $r1;
+	combined_from {
+		$r1 = new_prompt_for_choice(
+			header  => "First:",
+			choices => [
+				{value => 'x'},
+				{separator => 1},
+				{value => 'y'},
+			],
+		);
+	};
+	reset_stdin();
+
+	is($r1, 'x', 'first call: item 1 selected correctly');
+
+	# Second call — should not be affected by the first
+	set_stdin("1\n");
+	my $r2;
+	my $out = combined_from {
+		$r2 = new_prompt_for_choice(
+			header  => "Second:",
+			choices => [qw(a b c)],
+		);
+	};
+	reset_stdin();
+
+	is($r2, 'a', 'second call: numbering starts fresh at 1');
+};
+
 done_testing;
diff --git a/t/unit-tests/service_github-pr.t b/t/unit-tests/service_github-pr.t
new file mode 100644
index 00000000..b7ec4d02
--- /dev/null
+++ b/t/unit-tests/service_github-pr.t
@@ -0,0 +1,423 @@
+use strict;
+use warnings;
+
+use lib 'lib';
+use lib 't';
+
+use Test::More;
+use Test::Exception;
+
+BEGIN {
+	use_ok 'Service::Github';
+}
+
+# ============================================================
+# Mock Infrastructure (same pattern as service_github-mocked.t)
+# ============================================================
+
+my @curl_calls;
+my @curl_responses;
+
+{
+	no warnings 'redefine';
+	*Service::Github::curl = sub {
+		push @curl_calls, [@_];
+		my $resp = shift @curl_responses;
+		return (500, 'No mock response queued', '', '') unless $resp;
+		return @$resp;
+	};
+}
+
+sub queue_curl_response { push @curl_responses, [@_] }
+sub reset_mocks         { @curl_calls = (); @curl_responses = () }
+
+{
+	no warnings 'redefine';
+	*Service::Github::info    = sub {};
+	*Service::Github::error   = sub {};
+	*Service::Github::trace   = sub {};
+	*Service::Github::debug   = sub {};
+	*Service::Github::warning = sub {};
+}
+
+sub new_gh {
+	my (%args) = @_;
+	local $ENV{GITHUB_USER}       = delete $args{GITHUB_USER}       if exists $args{GITHUB_USER};
+	local $ENV{GITHUB_AUTH_TOKEN} = delete $args{GITHUB_AUTH_TOKEN} if exists $args{GITHUB_AUTH_TOKEN};
+	return Service::Github->new(%args);
+}
+
+require JSON::PP;
+sub encode_json { JSON::PP->new->encode(shift) }
+sub decode_json { JSON::PP->new->decode(shift) }
+
+sub make_pr {
+	my (%opts) = @_;
+	return {
+		number   => $opts{number}   // 1,
+		title    => $opts{title}    // 'Test PR',
+		body     => $opts{body}     // '',
+		state    => $opts{state}    // 'open',
+		html_url => $opts{html_url} // 'https://github.com/org/repo/pull/1',
+		head     => { ref => $opts{head_ref} // 'propagate/myenv/abc1234' },
+		base     => { ref => $opts{base_ref} // 'myenv' },
+	};
+}
+
+# ============================================================
+# pulls_url
+# ============================================================
+
+subtest 'pulls_url' => sub {
+	plan tests => 3;
+
+	my $gh = Service::Github->new(org => 'myorg');
+
+	is(
+		$gh->pulls_url('myorg/myrepo'),
+		'https://api.github.com/repos/myorg/myrepo/pulls',
+		'list endpoint'
+	);
+
+	is(
+		$gh->pulls_url('myorg/myrepo', 42),
+		'https://api.github.com/repos/myorg/myrepo/pulls/42',
+		'single-PR endpoint with number'
+	);
+
+	is(
+		$gh->pulls_url('myorg/myrepo', 0),
+		'https://api.github.com/repos/myorg/myrepo/pulls/0',
+		'number 0 is included (defined check)'
+	);
+};
+
+# ============================================================
+# list_prs
+# ============================================================
+
+subtest 'list_prs' => sub {
+	plan tests => 7;
+
+	subtest 'returns arrayref of PRs on 200' => sub {
+		plan tests => 4;
+		reset_mocks();
+		my $gh = new_gh(GITHUB_AUTH_TOKEN => 'tok');
+		my @prs = (make_pr(number => 1), make_pr(number => 2));
+		queue_curl_response(200, '200 OK', encode_json(\@prs), '');
+
+		my $result = $gh->list_prs('org/repo');
+		is(ref($result), 'ARRAY', 'returns arrayref');
+		is(scalar(@$result), 2, 'two PRs returned');
+		is($result->[0]{number}, 1, 'first PR number');
+		is($result->[1]{number}, 2, 'second PR number');
+	};
+
+	subtest 'default state is open' => sub {
+		plan tests => 1;
+		reset_mocks();
+		my $gh = new_gh(GITHUB_AUTH_TOKEN => 'tok');
+		queue_curl_response(200, '200 OK', encode_json([]), '');
+		$gh->list_prs('org/repo');
+		like($curl_calls[0][1], qr/state=open/, 'URL includes state=open by default');
+	};
+
+	subtest 'filters by base branch' => sub {
+		plan tests => 1;
+		reset_mocks();
+		my $gh = new_gh(GITHUB_AUTH_TOKEN => 'tok');
+		queue_curl_response(200, '200 OK', encode_json([]), '');
+		$gh->list_prs('org/repo', base => 'myenv');
+		like($curl_calls[0][1], qr/base=myenv/, 'URL includes base filter');
+	};
+
+	subtest 'filters by head branch with owner prefix' => sub {
+		plan tests => 1;
+		reset_mocks();
+		my $gh = new_gh(GITHUB_AUTH_TOKEN => 'tok');
+		queue_curl_response(200, '200 OK', encode_json([]), '');
+		$gh->list_prs('myorg/repo', head => 'propagate/myenv/abc1234');
+		like($curl_calls[0][1], qr/head=myorg%3Apropagate.*abc1234|head=myorg:propagate.*abc1234/,
+			'URL includes head filter with owner prefix');
+	};
+
+	subtest 'follows Link header pagination' => sub {
+		plan tests => 4;
+		reset_mocks();
+		my $gh = new_gh(GITHUB_AUTH_TOKEN => 'tok');
+
+		my $page1 = [make_pr(number => 1), make_pr(number => 2)];
+		my $page2 = [make_pr(number => 3)];
+		my $next_url = 'https://api.github.com/repos/org/repo/pulls?page=2&state=open';
+
+		# Page 1: returns Link header with rel="next"
+		queue_curl_response(200, '200 OK', encode_json($page1),
+			"Link: <$next_url>; rel=\"next\", <https://api.github.com/repos/org/repo/pulls?page=1>; rel=\"first\"\r\n");
+		# Page 2: no Link header
+		queue_curl_response(200, '200 OK', encode_json($page2), '');
+
+		my $result = $gh->list_prs('org/repo');
+		is(scalar(@curl_calls), 2,           'two curl calls made (two pages)');
+		is($curl_calls[1][1],   $next_url,   'second call uses next URL from Link header');
+		is(scalar(@$result),    3,           'all three PRs returned');
+		is($result->[2]{number}, 3,          'last PR from page 2 included');
+	};
+
+	subtest 'bails on non-200 response' => sub {
+		plan tests => 1;
+		reset_mocks();
+		my $gh = new_gh(GITHUB_AUTH_TOKEN => 'tok');
+		queue_curl_response(403, 'Forbidden', '{}', '');
+		dies_ok { $gh->list_prs('org/repo') } 'bails on 403';
+	};
+
+	subtest 'bails when owner_repo missing' => sub {
+		plan tests => 1;
+		reset_mocks();
+		my $gh = Service::Github->new();
+		dies_ok { $gh->list_prs('') } 'bails with empty owner_repo';
+	};
+};
+
+# ============================================================
+# create_pr
+# ============================================================
+
+subtest 'create_pr' => sub {
+	plan tests => 6;
+
+	subtest 'creates PR and returns PR object' => sub {
+		plan tests => 5;
+		reset_mocks();
+		my $gh = new_gh(GITHUB_AUTH_TOKEN => 'tok');
+		my $pr = make_pr(number => 7, title => 'my title', html_url => 'https://github.com/o/r/pull/7');
+		queue_curl_response(201, 'Created', encode_json($pr), '');
+
+		my $result = $gh->create_pr('org/repo',
+			head  => 'propagate/myenv/abc1234',
+			base  => 'myenv',
+			title => 'my title',
+			body  => 'some body',
+		);
+		is(ref($result), 'HASH',                'returns hashref');
+		is($result->{number},   7,              'PR number');
+		is($result->{title},    'my title',     'PR title');
+		is($result->{html_url}, 'https://github.com/o/r/pull/7', 'PR url');
+
+		is($curl_calls[0][0], 'POST', 'uses POST method');
+	};
+
+	subtest 'payload includes required fields' => sub {
+		plan tests => 4;
+		reset_mocks();
+		my $gh = new_gh(GITHUB_AUTH_TOKEN => 'tok');
+		queue_curl_response(201, 'Created', encode_json(make_pr()), '');
+
+		$gh->create_pr('org/repo',
+			head  => 'propagate/env/abc',
+			base  => 'env',
+			title => 'the title',
+			body  => 'the body',
+		);
+		my $payload = decode_json($curl_calls[0][3]);
+		is($payload->{head},  'propagate/env/abc', 'head in payload');
+		is($payload->{base},  'env',               'base in payload');
+		is($payload->{title}, 'the title',         'title in payload');
+		is($payload->{body},  'the body',          'body in payload');
+	};
+
+	subtest 'bails when head missing' => sub {
+		plan tests => 1;
+		my $gh = Service::Github->new();
+		dies_ok {
+			$gh->create_pr('org/repo', base => 'env', title => 'T')
+		} 'bails without head';
+	};
+
+	subtest 'bails when base missing' => sub {
+		plan tests => 1;
+		my $gh = Service::Github->new();
+		dies_ok {
+			$gh->create_pr('org/repo', head => 'branch', title => 'T')
+		} 'bails without base';
+	};
+
+	subtest 'bails when title missing' => sub {
+		plan tests => 1;
+		my $gh = Service::Github->new();
+		dies_ok {
+			$gh->create_pr('org/repo', head => 'branch', base => 'env')
+		} 'bails without title';
+	};
+
+	subtest 'bails on non-201 response' => sub {
+		plan tests => 1;
+		reset_mocks();
+		my $gh = new_gh(GITHUB_AUTH_TOKEN => 'tok');
+		queue_curl_response(422, 'Unprocessable', '{"message":"validation failed"}', '');
+		dies_ok {
+			$gh->create_pr('org/repo',
+				head => 'branch', base => 'env', title => 'T')
+		} 'bails on 422';
+	};
+};
+
+# ============================================================
+# update_pr
+# ============================================================
+
+subtest 'update_pr' => sub {
+	plan tests => 5;
+
+	subtest 'updates PR and returns updated object' => sub {
+		plan tests => 4;
+		reset_mocks();
+		my $gh = new_gh(GITHUB_AUTH_TOKEN => 'tok');
+		my $updated = make_pr(number => 3, title => 'new title');
+		queue_curl_response(200, 'OK', encode_json($updated), '');
+
+		my $result = $gh->update_pr('org/repo', 3,
+			title => 'new title',
+			body  => 'new body',
+		);
+		is(ref($result), 'HASH',        'returns hashref');
+		is($result->{number}, 3,        'PR number');
+		is($result->{title}, 'new title', 'updated title');
+		is($curl_calls[0][0], 'PATCH',  'uses PATCH method');
+	};
+
+	subtest 'PATCH URL contains PR number' => sub {
+		plan tests => 1;
+		reset_mocks();
+		my $gh = new_gh(GITHUB_AUTH_TOKEN => 'tok');
+		queue_curl_response(200, 'OK', encode_json(make_pr(number => 99)), '');
+		$gh->update_pr('org/repo', 99, title => 'T');
+		like($curl_calls[0][1], qr{/pulls/99$}, 'URL ends with /pulls/99');
+	};
+
+	subtest 'only sends provided fields' => sub {
+		plan tests => 2;
+		reset_mocks();
+		my $gh = new_gh(GITHUB_AUTH_TOKEN => 'tok');
+		queue_curl_response(200, 'OK', encode_json(make_pr()), '');
+		$gh->update_pr('org/repo', 1, title => 'just title');
+		my $payload = decode_json($curl_calls[0][3]);
+		ok(exists $payload->{title},  'title included');
+		ok(!exists $payload->{body},  'body omitted when not provided');
+	};
+
+	subtest 'bails when owner_repo missing' => sub {
+		plan tests => 1;
+		my $gh = Service::Github->new();
+		dies_ok { $gh->update_pr('', 1, title => 'T') } 'bails with empty owner_repo';
+	};
+
+	subtest 'bails on non-200 response' => sub {
+		plan tests => 1;
+		reset_mocks();
+		my $gh = new_gh(GITHUB_AUTH_TOKEN => 'tok');
+		queue_curl_response(404, 'Not Found', '{}', '');
+		dies_ok { $gh->update_pr('org/repo', 999, title => 'T') } 'bails on 404';
+	};
+};
+
+# ============================================================
+# find_or_open_pr (via create vs update logic)
+# ============================================================
+
+subtest 'idempotency: open new PR when none exists' => sub {
+	plan tests => 3;
+	reset_mocks();
+	my $gh = new_gh(GITHUB_AUTH_TOKEN => 'tok');
+
+	# list_prs returns empty → create_pr is called
+	queue_curl_response(200, 'OK', encode_json([]), '');
+	queue_curl_response(201, 'Created', encode_json(make_pr(number => 5)), '');
+
+	# Call list_prs then create_pr manually (simulates _find_or_open_pr logic)
+	my $prs = $gh->list_prs('org/repo', head => 'propagate/env/abc', base => 'env');
+	my ($existing) = grep { $_->{head}{ref} eq 'propagate/env/abc' } @$prs;
+	ok(!$existing, 'no existing PR found');
+
+	my $pr = $gh->create_pr('org/repo',
+		head  => 'propagate/env/abc',
+		base  => 'env',
+		title => '[pipeline] propagate control@abc to env',
+		body  => 'some body',
+	);
+	is($pr->{number}, 5,      'new PR number returned');
+	is($curl_calls[1][0], 'POST', 'POST used to create');
+};
+
+subtest 'idempotency: update existing PR when head matches' => sub {
+	plan tests => 3;
+	reset_mocks();
+	my $gh = new_gh(GITHUB_AUTH_TOKEN => 'tok');
+
+	my $existing_pr = make_pr(
+		number   => 12,
+		head_ref => 'propagate/env/abc1234',
+		base_ref => 'env',
+	);
+	# list_prs returns the existing PR
+	queue_curl_response(200, 'OK', encode_json([$existing_pr]), '');
+	# update_pr response
+	queue_curl_response(200, 'OK', encode_json(make_pr(number => 12, title => 'updated')), '');
+
+	my $prs = $gh->list_prs('org/repo',
+		head => 'propagate/env/abc1234', base => 'env');
+	my ($found) = grep { $_->{head}{ref} eq 'propagate/env/abc1234' } @$prs;
+	ok($found, 'existing PR found');
+
+	my $pr = $gh->update_pr('org/repo', $found->{number},
+		title => 'updated',
+		body  => 'updated body',
+	);
+	is($pr->{number}, 12,     'existing PR number returned');
+	is($curl_calls[1][0], 'PATCH', 'PATCH used to update');
+};
+
+# ============================================================
+# _find_or_open_pr: pre-passed existing skips list_prs call
+# ============================================================
+
+subtest '_find_or_open_pr: pre-passed existing skips list_prs' => sub {
+	plan tests => 3;
+	reset_mocks();
+	my $gh = new_gh(GITHUB_AUTH_TOKEN => 'tok');
+
+	my $existing = make_pr(number => 7, head_ref => 'propagate/env/abc');
+	# Only one curl call should be made (update_pr PATCH), no list_prs GET
+	queue_curl_response(200, 'OK', encode_json(make_pr(number => 7, title => 'updated')), '');
+
+	# Simulate what _find_or_open_pr does when $existing is pre-passed
+	my $pr = $gh->update_pr('org/repo', $existing->{number},
+		title => 'updated title',
+		body  => 'updated body',
+	);
+	is(scalar(@curl_calls), 1,    'only one curl call (no list_prs)');
+	is($curl_calls[0][0], 'PATCH', 'PATCH used directly');
+	is($pr->{number}, 7,           'correct PR number');
+};
+
+subtest 'pagination: two-page list with Link header' => sub {
+	plan tests => 3;
+	reset_mocks();
+	my $gh = new_gh(GITHUB_AUTH_TOKEN => 'tok');
+
+	my $page1 = [make_pr(number => 10), make_pr(number => 11)];
+	my $page2 = [make_pr(number => 12)];
+	my $next  = 'https://api.github.com/repos/org/repo/pulls?state=open&page=2';
+	queue_curl_response(200, 'OK', encode_json($page1),
+		"Link: <$next>; rel=\"next\"\r\n");
+	queue_curl_response(200, 'OK', encode_json($page2), '');
+
+	my $result = $gh->list_prs('org/repo', state => 'open');
+	is(scalar(@curl_calls), 2,   'two pages fetched');
+	is(scalar(@$result),    3,   'all three PRs from both pages');
+	is($result->[2]{number}, 12, 'last PR from page 2 present');
+};
+
+done_testing;
+
+# vim: ts=2 sw=2 sts=2 noet