feat(#656): generate verification setup actions and expose wizard activation

.copilot/AGENT_GUIDE.md

@@ -51,6 +51,6 @@ The setup runner profile selects placement; it does not install the project's la
 
 Declare reviewed version prefixes in `.copilot/verification-prerequisites.json` (schemaVersion 1, runtimes such as java 17, node 24, pnpm 10). Copilot checks declared versions in the credential-free verification environment before each configured verification command; a missing or incompatible runtime blocks publication. Without this optional declaration, existing verification behavior remains and no language is inferred. Java provisioning may use `actions/setup-java`; `JAVA_HOME` and `PATH` survive isolation, while agent credentials and tool-option injection variables do not. Do not add an unreviewed bootstrap or weaken verification to work around a missing runtime. Read [verification prerequisites and same-job setup](https://docs.page/vypdev/copilot/security-operations/operations/verification#repository-verification-prerequisites).
 
-The optional repository-owned composite action prepares each candidate before verification. Review `.github/actions/copilot-verification-setup/action.yml` and its assets onto trusted main, update generated workflows, then enable `VERIFICATION_SETUP=true` (Action input `verification-setup`, disabled by default). GitHub Actions executes the trusted snapshot before each command with a fresh private HOME; candidate changes cannot replace it. Native post steps finish before profile cleanup. Setup failure blocks verification and commit/push. The local CLI cannot execute composite actions and fails closed when opted in. Read [repository-owned setup](https://docs.page/vypdev/copilot/security-operations/operations/verification#repository-owned-setup).
+The optional repository-owned composite action prepares each candidate before verification. Setup creates .github/actions/copilot-verification-setup/action.yml only if missing and preserves an existing consumer action and its assets. The shared terminal/web assistant offers explicit activation, disabled by default. Customize the generated failing placeholder before enabling; setup generation and installer PRs do not prove runtime readiness. Review `.github/actions/copilot-verification-setup/action.yml` and its assets onto trusted main, update generated workflows, then enable `VERIFICATION_SETUP=true` (Action input `verification-setup`, disabled by default). GitHub Actions executes the trusted snapshot before each command with a fresh private HOME; candidate changes cannot replace it. Native post steps finish before profile cleanup. Setup failure blocks verification and commit/push. The local CLI cannot execute composite actions and fails closed when opted in. Read [repository-owned setup](https://docs.page/vypdev/copilot/security-operations/operations/verification#repository-owned-setup).
 
 For the full contributor flow, read [repository collaboration](https://github.com/vypdev/copilot/blob/master/docs/agents/repository-collaboration.mdx). For drift and recovery, read [guidance troubleshooting](https://github.com/vypdev/copilot/blob/master/docs/agents/repository-guidance-troubleshooting.mdx).

.copilot/setup-manifest.json

@@ -12,7 +12,7 @@
     },
     ".copilot/AGENT_GUIDE.md": {
       "role": "guide",
-      "sha256": "4c453f9e76287c970d56787bd082fc2d7d8d432b191a96a7132e811657905dbc"
+      "sha256": "c3bd0df4bfdcbba2a007b1596a93480a3bb3145a6285e0a91809f3a93c3fbcd0"
     },
     ".copilot/repository-profile.json": {
       "role": "profile",

build/web/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="color-scheme" content="light dark" />
     <title>Copilot · Setup studio</title>
-    <script type="module" crossorigin src="./assets/index-CsboG2sG.js"></script>
+    <script type="module" crossorigin src="./assets/index-CNXf8Vmj.js"></script>
     <link rel="stylesheet" crossorigin href="./assets/index-CfyclPC5.css">
   </head>
   <body>

docs/configuration.mdx

@@ -63,7 +63,7 @@ PR bot approval uses the versioned `pullRequestApproval` setup object and `PR_AP
     ## Branch Management
 
     - `issue-managed-branches`: Create and verify a linked branch after `in-progress` (default: "true")
-    - `verification-setup`: Run the trusted main-branch composite action before each configured verification command in generated GitHub Actions callbacks (default: "false"). See [repository-owned setup](/security-operations/operations/verification#repository-owned-setup).
+    - `verification-setup`: Run the trusted main-branch composite action before each configured verification command in generated GitHub Actions callbacks (default: "false"). Setup's terminal/web question maps `repository.verificationSetup` to `VERIFICATION_SETUP` using the existing storage/reuse precedence. Setup creates `.github/actions/copilot-verification-setup/action.yml` only if missing and preserves an existing action and its assets. Customize the failing starter and review it onto `MAIN_BRANCH` before enabling; generation and activation do not prove readiness. See [repository-owned setup](/security-operations/operations/verification#repository-owned-setup) and [upgrade/rollback](/security-operations/operations/upgrade-rollback#upgrade-an-existing-copilot-repository).
     - `pre-branch-sdd`: Require a validated SDD before implementation for eligible issues (default: "false")
     - `branch-management-emoji`: Emoji for branched issues (default: "🧑‍💻")
 

docs/development/architecture.mdx

@@ -4,6 +4,18 @@ description: Clean Architecture boundaries for agent execution and workflow auto
 ---
 # Architecture
 
+Verification setup onboarding uses the shared repository questionnaire and the
+existing `repository.verificationSetup` boolean. The package supplies a native
+composite starter under `setup/actions/`; the filesystem adapter inspects only
+the fixed consumer path and creates it exclusively when absent. Existing action
+contents and auxiliaries are outside generator overwrite and retirement ownership.
+Installation review records create/preserve/blocked, activation and trusted main
+as semantic facts shared by terminal, web and batch PR presentation. Batch Git
+inventory permits the exact entrypoint and rejects unsafe parent/file modes or
+case collisions before rendering. See [the onboarding
+SDD](https://github.com/vypdev/copilot/blob/develop/specs/verification-setup-onboarding.md)
+and the [verification guide](/security-operations/operations/verification#repository-owned-setup).
+
 ### Setup runner profiles and installation parity
 
 `setup_runner_policy` owns pure registry validation, precedence, fixed job roles,

docs/security-operations/operations/upgrade-rollback.mdx

@@ -36,6 +36,101 @@ copilot --version
 
 Use `@latest` only when the latest published release is intentionally selected. Keep explicit versions for reproducible rollback procedures.
 
+## Upgrade an existing Copilot repository
+
+Copilot has three separate versioned layers:
+
+| Layer | What changes it | What still needs review |
+|---|---|---|
+| Installed CLI | `copilot upgrade` or an explicit npm/pnpm package version | The CLI prepares local files; it does not rewrite committed workflows merely by upgrading |
+| Remote Action reference | The Copilot `uses` references in committed workflows | `@v3` follows the published major tag; an exact version or commit SHA stays pinned until explicitly changed |
+| Generated workflow files | An approved `copilot setup --update-workflows` run | New jobs, inputs and native continuation steps must be committed, reviewed and merged |
+
+Moving a tag does not add steps to an old YAML file. Upgrading the CLI does not
+change the Action references in Git. A merge into `develop` is not a package or
+Action release: first select a [published release](https://github.com/vypdev/copilot/releases)
+that contains the required setup and native verification support.
+
+For verification setup adoption:
+
+**1. Record the existing installation.**
+
+Start with a clean branch, record the currently reviewed workflow references,
+and keep `VERIFICATION_SETUP=false` during preparation. Inspect the effective
+repository/organization value; a repository Variable overrides an inherited
+organization value.
+
+**2. Upgrade the CLI and preview.**
+
+Upgrade the CLI and confirm `copilot --version`. Preview the installation:
+
+```bash
+copilot upgrade
+copilot --version
+copilot setup --web --dry-run
+```
+
+**3. Regenerate and review workflows.**
+
+Apply a reviewed workflow upgrade:
+
+```bash
+copilot setup --web --update-workflows
+```
+
+The shared assistant also works in the terminal without `--web`. Keep the
+verification setup question disabled for this preparation pass. Review the
+displayed create/preserve result and changes before approval. The installer
+creates `.github/actions/copilot-verification-setup/action.yml` only if absent;
+existing action bytes and auxiliary files are preserved through upgrades.
+Generated workflows use `vypdev/copilot@v3`. If your repository pins versions
+or SHAs, review **every** Copilot `uses` reference, including native
+continuation/post steps, and apply the same chosen compatible published ref.
+Workflow backups are retained under `.copilot/setup-backups/`.
+
+**4. Customize and merge on trusted main.**
+
+Replace the starter's failing placeholder with reviewed project-specific
+dependency preparation. Commit the action, its auxiliary files and the updated
+workflows. Review and merge them onto the configured trusted `MAIN_BRANCH`;
+the installer PR's default target may differ from this trusted branch. Follow
+the repository's branch/promotion process until both contain the reviewed
+changes. Creating or merging an installer PR alone does not verify the runtime.
+
+**5. Activate verification setup.**
+
+Re-run the assistant and enable **Prepare dependencies with the repository
+verification setup action?**, or use:
+
+```yaml
+repository:
+  verificationSetup: true
+```
+
+Setup writes `VERIFICATION_SETUP` only when Variable management is enabled
+and follows the reviewed storage/reuse policy. With `--skip-variables`, update
+the effective Variable manually. Confirm that generated workflows pass the
+`verification-setup` input and that the trusted action has been customized.
+Choose **Customize** when changing an existing repository Variable; **Reuse**
+keeps existing values. If an organization value must differ for this project,
+select `VERIFICATION_SETUP` in the repository Variable overrides and review the
+scope before Apply.
+
+**6. Verify actual execution.**
+
+Run `copilot doctor --read-only`, then an authorized write/sync operation that
+actually executes the configured verification commands. Inspect the native
+action and verifier results; a doctor pass, dry run or already-aligned sync
+does not prove dependency preparation.
+
+To roll back adoption, first set the effective `VERIFICATION_SETUP=false` (or
+answer No with Variable management enabled). This stops the optional hook and
+retains the existing verification commands. Restore the previous reviewed
+workflow files and Action refs together if necessary, and install the prior CLI
+version explicitly. Consumer action files are retained; restore any owner changes
+through Git review instead of asking setup to overwrite or delete them. Inspect
+partial setup receipts and GitHub resources before retrying a failed upgrade.
+
 ## Rollback
 
 1. Restore the last known-good version variable.

docs/security-operations/operations/verification.mdx

@@ -135,15 +135,52 @@ flowchart LR
 Text equivalent: prepare the candidate, install its dependencies, verify it, then
 apply the existing publication guards. A separate CI job does not prepare this job.
 
-1. Review `.github/actions/copilot-verification-setup/action.yml` and its auxiliary
-   scripts onto your configured `main-branch` (normally production). Candidate or
-   model changes cannot activate a different setup implementation.
-2. Update the generated comment workflows with `copilot setup`. They contain the
-   native setup and continuation steps; an older callback cannot execute YAML.
-3. Enable Repository Variable `VERIFICATION_SETUP=true`, or plan it with setup
-   configuration `repository: { verificationSetup: true }`. The corresponding
-   boolean Action input is `verification-setup`; its default is `false`.
-4. Retry the authorized modification or `/copilot sync-branch --no-agent`.
+1. Run `copilot setup` or `copilot setup --web` with a published CLI version that
+   includes this onboarding support. The plan shows **Create the starter only if
+   missing** or **Preserve the existing project action** at
+   `.github/actions/copilot-verification-setup/action.yml`, plus the activation
+   state and configured trusted main branch. Setup creates this file even when
+   activation is disabled. It never overwrites an existing regular action,
+   changes its auxiliary files or retires it when you disable the option.
+2. Leave **Prepare dependencies with the repository verification setup action?**
+   disabled while preparing the action. The generated native composite contains
+   a failing placeholder with customization instructions. Replace that step with
+   your project's reviewed runtime and dependency setup; no language, version or
+   install command is inferred, and setup does not execute the action.
+3. Update the generated comment workflows with `copilot setup --update-workflows`
+   and review the complete diff. They need the native setup and continuation
+   steps; an older callback cannot execute YAML. Review the action, auxiliary
+   scripts and workflows onto the configured `main-branch` (`MAIN_BRANCH`, normally
+   production). Candidate or model changes cannot replace the trusted action.
+4. Enable the same question in the terminal/web assistant, or set non-secret
+   configuration `repository: { verificationSetup: true }`. With Variable
+   management enabled, setup plans `VERIFICATION_SETUP=true` using the selected
+   storage/reuse policy. Existing configured values are shown; the default is
+   `false`. If Variable management is skipped, set the effective GitHub Actions
+   Variable yourself. The corresponding boolean Action input is
+   `verification-setup`.
+   Choose **Customize** to change an existing repository Variable; **Reuse**
+   retains existing effective values. To override an inherited organization value
+   just for this repository, select `VERIFICATION_SETUP` under repository Variable
+   overrides and review its scope.
+5. Retry an authorized modification or `/copilot sync-branch --no-agent` that
+   actually needs configured verification. Inspect the native setup and verifier
+   results. A dry run, no-op sync, read-only doctor result, generated file or
+   installer PR does not establish runtime readiness.
+
+The starter deliberately fails until customized. Enabling the flag before the
+reviewed action is available on trusted main blocks verification and publication;
+it does not bypass the placeholder. Batch setup uses the same create/preserve
+rule and includes a missing starter in its installation PR. An existing action
+stays outside generator ownership and out of the update diff. Unsafe parent
+links, non-regular action paths and collisions block setup; inspect the path and
+review a fresh plan. If a file appears after review, setup preserves it and stops
+the stale creation. Dry-run, cancellation and declined approval create no starter.
+
+For an existing installation, follow the [three-layer upgrade and rollback
+procedure](/security-operations/operations/upgrade-rollback#upgrade-an-existing-copilot-repository).
+This repository's `setup_platform_smoke.yml` is internal CI and is not installed
+in consumer projects.
 
 Copilot captures the complete action directory from an immutable trusted Git SHA
 before candidate changes. The trusted origin ref must be available locally;

docs/setup-web.mdx

@@ -53,6 +53,18 @@ Choose **This repository** for your first installation. A new checkout offers **
 
 Choose **Basic guided setup** unless you need every advanced setting. Basic still asks for permission, branch, runner, Project, approval and storage decisions. **Customize every setting** exposes the advanced configuration. Use **Previous question** or the plan's **Change** controls to revise answers without losing the others.
 
+Both modes ask **Prepare dependencies with the repository verification setup
+action?** The default is disabled; configured and reused values remain visible.
+The plan shows whether `.github/actions/copilot-verification-setup/action.yml`
+will be created or preserved, the activation state and the configured trusted main
+branch. Apply creates a failing starter only when missing and preserves existing
+project actions and auxiliary files. Customize and review the action on
+`MAIN_BRANCH` before enabling `VERIFICATION_SETUP`, then exercise a real verifier.
+No dependency installation runs during setup. Follow the [upgrade and rollback
+guide](/security-operations/operations/upgrade-rollback#upgrade-an-existing-copilot-repository)
+for an existing installation; creating an installer PR does not establish runtime
+readiness.
+
 The six milestones are:
 
 ```text

docs/single-actions/workflow-and-cli.mdx

@@ -217,6 +217,16 @@ copilot setup
 
 Run it from the target repository root. Existing setup files are not overwritten unless you approve the update prompt or pass `--update-workflows`. The interactive flow installs the selected workflows/templates, asks for agent routing and operational settings, inspects the repository's effective Actions resources, and asks separately where Secrets and Variables should live. Organization scope requires an organization-owned repository and the corresponding organization permissions on the setup PAT. Existing repository resources take precedence over organization resources; setup preserves an inherited organization resource unless you explicitly request a repository override.
 
+Setup also creates `.github/actions/copilot-verification-setup/action.yml` only
+if missing. This project-owned action and its auxiliaries are preserved even
+with `--update-workflows`; they are never retired on deselection. The shared
+terminal/web repository question controls the existing boolean
+`repository.verificationSetup` / `VERIFICATION_SETUP`, disabled by default.
+Customize the generated failing placeholder and review it on configured
+`MAIN_BRANCH` before activation. Preview/cancel/decline creates no starter;
+setup does not infer or install dependencies. See the [ordered upgrade
+procedure](/security-operations/operations/upgrade-rollback#upgrade-an-existing-copilot-repository).
+
 The questionnaire is forward-only and immutable. Its stable stages are capabilities, issue workflow multi-select, agent runtime, model defaults, optional role overrides, repository, deployment, Bugbot, optional Projects, provisioning, storage, review, and confirmation. The issue workflow selector uses the usual `Space` to toggle and `Enter` to confirm; `All` is selected by default. `Ctrl-C` or end-of-input closes the prompt once, exits 130, and writes nothing. Declining the final plan exits 0 and also writes nothing; rerun setup or edit the config file to change earlier answers.
 
 The wizard covers these features: `issues`, `pullRequests`, `commits`, `issueComments`, `pullRequestComments`, `release`, `hotfix`, `agentProvisioning`, `credentialHealth`, `inactiveIssueClosure`, `issueTemplates`, and `pullRequestTemplate`. It also asks whether to generate repository agent guidance; this is enabled by default. The agent tasks are `planner`, `findings`, `reviewer`, `fixer`, and `tester`; each can use any of the three supported runtimes independently. Model provider, model, effort, branch strategy, locales, AI ignore patterns, project columns, Bugbot policy, and initial-tag creation are also configurable. Cursor is available as an experimental runtime and is called out in the review plan with its extra credential/checksum requirements.

package.json

@@ -40,6 +40,7 @@
     "build/api/index.js",
     "build/api/src/",
     "setup/ISSUE_TEMPLATE/",
+    "setup/actions/",
     "setup/workflows/",
     "setup/source-workflows/",
     "setup/pull_request_template.md",