codebyplan 1.13.52 → 1.13.53

package/templates/skills/cbp-setup-cd/SKILL.md

@@ -0,0 +1,291 @@
+---
+scope: org-shared
+name: cbp-setup-cd
+description: Detect configured CD surfaces, write/update .codebyplan/cd.json via `codebyplan cd init`, scaffold publish.yml and release-desktop.yml GitHub Actions workflows, and walk through environment/approval/OIDC setup. Interactive, idempotent.
+argument-hint: "[--force]"
+effort: xhigh
+allowed-tools: Read, Write, Edit, Bash(cat *), Bash(jq *), Bash(test *), Bash(ls *), Bash(diff *), Bash(codebyplan cd *), Bash(npx codebyplan cd *), AskUserQuestion
+---
+
+# CD Setup
+
+Configure `.codebyplan/cd.json`, scaffold `.github/workflows/publish.yml` and
+`.github/workflows/release-desktop.yml`, and record the credential env-var names needed
+at deploy time. Invoke at any time. Already-configured surfaces are preserved unless
+`--force` is passed.
+
+Pass `--force` to re-detect all surfaces and overwrite existing workflow files.
+
+## Arguments
+
+Inspect `$ARGUMENTS` for `--force`. If present, set `force_mode = true`.
+Absent: idempotent mode — existing surface keys in `.codebyplan/cd.json` are preserved;
+workflow files are not overwritten unless `--force`.
+
+## Step 1 — Detect configured surfaces + read current state
+
+Read detection signals and existing config:
+
+```bash
+cat .codebyplan/shipment.json 2>/dev/null || echo '{}'
+cat .codebyplan/cd.json 2>/dev/null || echo '{}'
+```
+
+**Surface detection signals** (derive from `shipment.json` + filesystem):
+
+| Surface | Signal |
+|---------|--------|
+| `npm` | `packages/*/package.json` with `publishConfig.access` set |
+| `tauri` | `apps/*/src-tauri/tauri.conf.json` present |
+| `vscode` | `apps/*/package.json` with `contributes` block |
+| `expo` | `apps/*/eas.json` present |
+| `vercel` | `.vercel/project.json` or `vercel.json` in any app |
+| `railway` | `apps/*/railway.toml` or `apps/*/Dockerfile` present |
+
+**Idempotency**: a surface already in `.codebyplan/cd.json` is "configured". A newly
+detected surface not yet in the file is "new". A surface in the file but no longer
+detected is "stale".
+
+Display a detection table:
+
+```
+Surface   | Detected | Configured | Workflow file
+--------- | -------- | ---------- | ----------------------------------------
+npm       | yes      | yes        | .github/workflows/publish.yml (present)
+tauri     | yes      | yes        | .github/workflows/release-desktop.yml (present)
+vscode    | no       | no         | —
+expo      | no       | no         | —
+```
+
+## Step 2 — Confirm surfaces to manage
+
+AskUserQuestion (multi-select):
+
+```
+Detected CD surfaces:
+<table from Step 1>
+
+Which surfaces should be managed by cd.json?
+Already-configured surfaces are pre-checked. Deselect to remove from cd.json.
+
+Select all that apply:
+A) npm       — publish.yml (GitHub Actions + OIDC)
+B) tauri     — release-desktop.yml (cross-platform Tauri build + signing)
+C) vscode    — VS Code marketplace publish (undetected — add eas.json to enable)
+D) expo      — EAS build + store submit (undetected)
+E) vercel    — Vercel production deploy (managed by Vercel GitHub integration)
+F) railway   — Railway deploy hook (managed by Railway GitHub integration)
+```
+
+In `--force` mode: re-ask even for already-configured surfaces.
+Otherwise: surfaces already in `cd.json` are preserved without re-asking.
+
+If an expected surface is MISSING from detection: add the detection signal (e.g.
+`publishConfig.access` in package.json, or `src-tauri/tauri.conf.json`) and re-run.
+To DROP a surface: deselect it here and re-run with `--force` to remove its key from
+`cd.json`, or edit `.codebyplan/cd.json` directly.
+
+## Step 3 — Collect credential env-var names (per surface)
+
+For each confirmed surface, collect only the env-var NAMES (never the values). Skip if
+`--force` is absent AND `credentials.env_var_names[]` is already non-empty in `cd.json`.
+
+Per-surface default name sets (accept defaults or override):
+
+| Surface | Default env-var names |
+| ------- | --------------------- |
+| `npm` (OIDC) | *(none — OIDC handles auth; record `[]`)* |
+| `npm` (token) | `NPM_TOKEN` |
+| `tauri` | `TAURI_SIGNING_PRIVATE_KEY`, `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`, `APPLE_CERTIFICATE`, `APPLE_CERTIFICATE_PASSWORD`, `APPLE_SIGNING_IDENTITY`, `APPLE_API_ISSUER`, `APPLE_API_KEY`, `APPLE_API_KEY_CONTENT`, `WINDOWS_CERTIFICATE`, `WINDOWS_CERTIFICATE_PASSWORD` |
+| `vscode` | `VSCE_PAT` |
+| `expo` | `EXPO_TOKEN` |
+
+Full var descriptions: [reference/github-actions-cd.md](reference/github-actions-cd.md) § Per-Surface Credential Var-Name Reference.
+
+Record collected names into `credentials.env_var_names[]`. Never write secret values.
+
+## Step 4 — Collect environment + approval config (per surface)
+
+For each confirmed surface, ask about GitHub Environments and approval gates. Skip if
+already configured in `cd.json` and `--force` is absent.
+
+AskUserQuestion per surface:
+
+```
+GitHub Environment config for [surface]:
+
+1. Deploy environment name (leave blank for none — e.g. "production"):
+   Environment: ___
+
+2. Require manual approval before deploy?
+   A) No — auto-deploy on push (recommended for npm OIDC / Tauri tag)
+   B) Yes — require a reviewer to approve the workflow run
+
+3. OIDC auth (exchange GitHub OIDC token for deploy credential)?
+   A) Yes — recommended for npm (no long-lived token; requires Trusted Publisher config on npmjs.com)
+   B) No — use a long-lived token from repository secrets
+```
+
+Record as `environment`, `approval_required`, and `oidc_auth` on the surface block.
+
+## Step 5 — Write .codebyplan/cd.json
+
+Run `codebyplan cd init` to write the config:
+
+```bash
+npx codebyplan cd init [--force]
+```
+
+The CLI writes `cd.json` from the collected surface data. If the CLI is unavailable (not
+yet on PATH), write the file directly via jq:
+
+```bash
+jq -n \
+  --argjson surfaces "$SURFACES_JSON" \
+  --argjson workflow "$WORKFLOW_JSON" \
+  '{surfaces: $surfaces, workflow: $workflow}' \
+  > .codebyplan/cd.json
+```
+
+Confirm by reading back the result:
+
+```bash
+cat .codebyplan/cd.json
+```
+
+Per-surface shape: `{ trigger, path_filter, approval_required, oidc_auth, version_gate,
+credentials: { env_var_names[] } }`. Credentials are env-var NAMES only — never values.
+Schema: `packages/codebyplan-package/src/lib/types.ts` (`CdConfig`).
+
+## Step 6 — Scaffold workflow files (diff-guarded)
+
+Preview each workflow before writing:
+
+```bash
+npx codebyplan cd scaffold-workflow --dry-run
+```
+
+For each workflow file that already exists, show a diff and ask before overwriting (unless
+`--force` is set):
+
+```bash
+diff .github/workflows/publish.yml <(npx codebyplan cd scaffold-workflow --workflow publish --dry-run)
+```
+
+AskUserQuestion (only when file exists and `--force` is absent):
+
+```
+.github/workflows/publish.yml already exists.
+Diff (existing → new):
+<diff output>
+
+Overwrite?
+A) Yes — adopt the scaffolded workflow (recommended — picks up latest template)
+B) No — keep existing workflow unchanged
+```
+
+Then write:
+
+```bash
+npx codebyplan cd scaffold-workflow [--force]
+```
+
+If the CLI errors (missing bin, not yet released), write from the canonical templates at
+`packages/codebyplan-package/templates/github-workflows/`:
+
+```bash
+cp packages/codebyplan-package/templates/github-workflows/publish.yml \
+   .github/workflows/publish.yml
+cp packages/codebyplan-package/templates/github-workflows/release-desktop.yml \
+   .github/workflows/release-desktop.yml
+```
+
+Only copy templates relevant to the confirmed surface set (npm → publish.yml;
+tauri → release-desktop.yml).
+
+After writing, update `cd.json` to record `workflow.workflows_scaffolded: true` and the
+current timestamp:
+
+```bash
+jq '.workflow.workflows_scaffolded = true | .workflow.scaffolded_at = "'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"' \
+  .codebyplan/cd.json > .codebyplan/cd.json.tmp \
+  && mv .codebyplan/cd.json.tmp .codebyplan/cd.json
+```
+
+## Step 7 — OIDC Trusted Publishing verification (npm surface)
+
+If the npm surface uses `oidc_auth: true`, walk the user through verifying the npmjs.com
+Trusted Publisher registration:
+
+```
+npm OIDC Trusted Publishing setup
+
+Verify these settings on npmjs.com → package → Settings → Trusted Publishers:
+
+  Publisher type : GitHub Actions
+  Repository owner: <github-org>
+  Repository name : <repo-slug>
+  Workflow filename: publish.yml
+  Environment     : (blank, unless you set a GitHub Environment above)
+
+If the Trusted Publisher is NOT configured, publish.yml will fail with E401.
+Configure it at: https://www.npmjs.com/package/<package-name>/access
+
+Configured? (Y/n)
+```
+
+If `n`: print the npmjs.com configuration URL and pause — the user must complete this
+before the first publish will succeed. Record the gap in `cd.json` as
+`workflow.npm_oidc_publisher_verified: false`.
+
+On `Y`: record `workflow.npm_oidc_publisher_verified: true`.
+
+Skip this step when `oidc_auth: false` for the npm surface.
+
+## Step 8 — Verify and report
+
+Re-read the config and confirm workflow files exist:
+
+```bash
+cat .codebyplan/cd.json
+test -f .github/workflows/publish.yml && echo "publish.yml present" || echo "publish.yml MISSING"
+test -f .github/workflows/release-desktop.yml && echo "release-desktop.yml present" || echo "release-desktop.yml MISSING"
+```
+
+Emit a summary:
+
+```
+CD Setup — Complete
+
+Surface | trigger       | path_filter                      | approval | oidc  | version_gate | workflow
+------- | ------------- | -------------------------------- | -------- | ----- | ------------ | --------
+npm     | push-to-main  | packages/codebyplan-package/**   | no       | yes   | yes          | publish.yml (present)
+tauri   | push-to-main  | apps/desktop/**                  | no       | no    | yes          | release-desktop.yml (present)
+
+cd.json:  .codebyplan/cd.json  (written)
+
+Next:
+  1. Add the credential env vars to GitHub repository secrets (Settings → Secrets and variables → Actions).
+  2. For npm OIDC: verify the Trusted Publisher on npmjs.com (Step 7 above).
+  3. Push a version bump to main to verify the publish.yml gate fires.
+  4. See reference/github-actions-cd.md for workflow anatomy and troubleshooting.
+```
+
+## Key Rules
+
+- Credentials are NEVER written to `cd.json` or this skill — var names only
+- Idempotent — re-running without `--force` preserves existing surface keys and workflow
+  files; it never clobbers a customized workflow
+- Diff-guarded — existing workflow files are shown as a diff before overwriting
+- Repos without `cd.json` fall back to the existing surface-detection path in `/cbp-ship`
+  — this skill writes the config that informs `/cbp-ship` Step 3 variant selection
+- This skill is org-shared; its template twin at
+  `packages/codebyplan-package/templates/skills/cbp-setup-cd/SKILL.md` must stay
+  byte-identical (GATE-6)
+
+## Additional resources
+
+- Workflow anatomy + OIDC + drift-guard: [reference/github-actions-cd.md](reference/github-actions-cd.md)
+- CD config schema: `packages/codebyplan-package/src/lib/types.ts` (`CdConfig`)
+- CD CLI commands: `packages/codebyplan-package/src/cli/cd.ts`
+- Surface detection signals: `packages/codebyplan-package/src/lib/cd-init.ts` (`detectSurfaces`, `normaliseSurfaceKey`)

package/templates/skills/cbp-setup-cd/reference/github-actions-cd.md

@@ -0,0 +1,231 @@
+# GitHub Actions CD Reference
+
+Workflow anatomy, OIDC setup, drift-guard guidance, and per-surface credential
+var-name lists for the `codebyplan cd` scaffold.
+
+## Overview
+
+GitHub Actions CD runs on every push to main (path-filtered per surface). The
+`codebyplan cd scaffold-workflow` command writes `.github/workflows/publish.yml`
+(npm surface) and `.github/workflows/release-desktop.yml` (Tauri surface) from
+bundled canonical templates.
+
+Workflow triggers:
+
+```yaml
+# publish.yml (npm surface)
+on:
+  push:
+    branches: [main, 'feat/**']
+    paths: ['packages/<package>/**']
+  workflow_dispatch:
+    inputs:
+      dry_run: { type: boolean, default: false }
+
+# release-desktop.yml (Tauri surface)
+on:
+  push:
+    branches: [main]
+    paths: ['apps/desktop/**']
+  workflow_dispatch: {}
+```
+
+## publish.yml Structure (npm surface)
+
+Key sections of the scaffolded npm workflow:
+
+| Section | What it does |
+| ------- | ------------ |
+| `check-version` job | Reads `package.json` version, compares against npm registry, sets `should_publish` output |
+| `publish-codebyplan` job | Builds the package, upgrades npm for OIDC, publishes via `npm publish --access public --tag <dist_tag>` |
+| `tag-and-release` job | Creates a `v<version>` git tag and GitHub release (idempotent) |
+| `id-token: write` permission | Required for OIDC Trusted Publishing — no long-lived `NPM_TOKEN` needed |
+
+The `check-version` job enforces several guards:
+
+- **main push + stable version**: compares committed version against npm registry; publishes only when version is strictly greater.
+- **main push + prerelease version**: skipped — prerelease versions on main require `workflow_dispatch` or a `feat/**` branch.
+- **feat/** push + stable version**: skipped — feat branches require a prerelease version (e.g. `1.2.0-beta.1`).
+- **feat/** push + prerelease version**: publishes only if the exact version is not already on npm (exact-version guard).
+- **workflow_dispatch**: always publishes (recovery / forced re-publish path).
+
+Scaffold only this workflow:
+
+```bash
+npx codebyplan cd scaffold-workflow --workflow publish
+```
+
+Path filters are baked into the workflow templates (they are not a CLI flag) — edit
+the generated `.github/workflows/publish.yml` `paths:` block directly if your package
+lives elsewhere.
+
+## release-desktop.yml Structure (Tauri surface)
+
+Key sections of the scaffolded Tauri workflow:
+
+| Section | What it does |
+| ------- | ------------ |
+| `check-version` job | Reads `apps/desktop/src-tauri/tauri.conf.json` version, checks whether `desktop-v<version>` tag exists |
+| `build` job (matrix) | Builds macOS (arm64 + x86_64) and Windows (x86_64) using `tauri-apps/tauri-action` |
+| `notify` job | Downloads `latest.json` from the GitHub release, posts release metadata to the CodeByPlan API |
+| `contents: write` permission | Required to create tags and GitHub releases |
+
+The build matrix:
+
+| Platform | Target | Label |
+| -------- | ------ | ----- |
+| `macos-latest` | `aarch64-apple-darwin` | macOS (Apple Silicon) |
+| `macos-latest` | `x86_64-apple-darwin` | macOS (Intel) |
+| `windows-latest` | `x86_64-pc-windows-msvc` | Windows (x86_64) |
+
+Windows leg is skipped when `WINDOWS_CERTIFICATE` secret is absent — lets macOS-only
+notarized releases ship while the Windows EV cert is being procured.
+
+## OIDC Setup for npm Publish
+
+npm Trusted Publishing (OIDC) eliminates long-lived `NPM_TOKEN` secrets. GitHub exchanges
+a short-lived OIDC token for a publish credential at workflow runtime.
+
+**Requirements:**
+
+1. npm >= 11.5.1 (the workflow upgrades npm before publishing — no manual action needed).
+2. A Trusted Publisher entry on npmjs.com configured for this repo + workflow.
+3. `id-token: write` permission on the publish job (already in the scaffolded template).
+4. No `registry-url:` on `actions/setup-node` — that would inject `_authToken` into
+   `.npmrc`, shadowing the OIDC exchange and causing `E404`.
+
+**Configuring the Trusted Publisher on npmjs.com:**
+
+1. Go to `https://www.npmjs.com/package/<package-name>/access`.
+2. Under **Trusted Publishers**, click **Add a publisher**.
+3. Fill in:
+   - Publisher type: `GitHub Actions`
+   - Repository owner: `<github-org>`
+   - Repository name: `<repo-slug>`
+   - Workflow filename: `publish.yml`
+   - Environment: (blank unless a GitHub Environment is used)
+4. Save.
+
+After the first successful publish, no further action is needed unless the workflow
+filename or repo changes.
+
+**Prerelease dist-tag routing:**
+
+The workflow computes the dist-tag from the version string:
+
+| Version | dist-tag |
+| ------- | -------- |
+| `1.2.3` | `latest` |
+| `1.2.3-beta.1` | `beta` |
+| `1.2.3-rc.1` | `rc` |
+
+Consumers install the stable channel with `npm install <pkg>` and the prerelease channel
+with `npm install <pkg>@beta`.
+
+## Drift Guard
+
+Both workflow files may be adopted from the canonical templates via:
+
+```bash
+npx codebyplan cd scaffold-workflow [--force]
+```
+
+Without `--force`, the skill shows a diff of the existing file vs the template before
+overwriting. **Never silently overwrite a customized workflow** — always diff first and
+confirm.
+
+Drift from the canonical template accumulates when:
+
+- The repo patches a workflow inline (e.g. changes `node-version`).
+- A new version of the template ships in `codebyplan` but the repo has not re-run
+  `/cbp-setup-cd`.
+
+Recommended practice: re-run `/cbp-setup-cd` after each `codebyplan` version bump that
+mentions workflow changes in its changelog; review the diff before accepting.
+
+## Per-Surface Credential Var-Name Reference
+
+Credential ENV VAR NAMES only — never the values. Set these as GitHub repository secrets
+at Settings → Secrets and variables → Actions.
+
+### npm surface (OIDC — no long-lived token required)
+
+When `oidc_auth: true` (recommended):
+
+| Var name | Purpose |
+| -------- | ------- |
+| *(none required)* | OIDC handles auth via Trusted Publisher; no secret needed |
+
+When `oidc_auth: false` (fallback):
+
+| Var name | Purpose |
+| -------- | ------- |
+| `NPM_TOKEN` | Long-lived npm automation token (scoped to the package) |
+
+### tauri surface
+
+| Var name | Required | Purpose |
+| -------- | -------- | ------- |
+| `TAURI_SIGNING_PRIVATE_KEY` | Yes | Updater artifact signing (all platforms) |
+| `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` | Yes | Passphrase for the signing key |
+| `APPLE_CERTIFICATE` | macOS only | Base64-encoded `.p12` developer certificate |
+| `APPLE_CERTIFICATE_PASSWORD` | macOS only | Password for the `.p12` certificate |
+| `APPLE_SIGNING_IDENTITY` | macOS only | Certificate common name (`Developer ID Application: …`) |
+| `APPLE_API_ISSUER` | macOS only | App Store Connect API issuer UUID |
+| `APPLE_API_KEY` | macOS only | App Store Connect API key ID |
+| `APPLE_API_KEY_CONTENT` | macOS only | Contents of the `.p8` API key file (for notarization) |
+| `WINDOWS_CERTIFICATE` | Windows only | Base64-encoded EV certificate (`.pfx`) |
+| `WINDOWS_CERTIFICATE_PASSWORD` | Windows only | Password for the `.pfx` certificate |
+| `CODEBYPLAN_API_KEY` | notify job | API key for posting release metadata to the CodeByPlan API |
+
+The Windows leg is skipped automatically when `WINDOWS_CERTIFICATE` is absent — macOS
+notarized releases can ship independently while the Windows EV cert is being procured.
+
+### vscode surface
+
+| Var name | Required | Purpose |
+| -------- | -------- | ------- |
+| `VSCE_PAT` | Yes | VS Code Marketplace Personal Access Token |
+
+### expo surface
+
+| Var name | Required | Purpose |
+| -------- | -------- | ------- |
+| `EXPO_TOKEN` | Yes | EAS build + submit token |
+
+## Troubleshooting
+
+**publish.yml fails with `E401 Unauthorized`** — npm Trusted Publishing is not configured
+on npmjs.com. Follow the OIDC Setup section above. Common mistake: the workflow filename in
+the Trusted Publisher entry does not match the actual workflow filename (e.g. `release.yml`
+vs `publish.yml`).
+
+**publish.yml fails on `check if publish needed`** — GitHub Actions billing block or
+spending-limit hit. Read the run annotations in the GitHub Actions UI, fix billing, run
+`gh run rerun --failed <run-id>`, then merge manually if needed.
+
+**release-desktop.yml: macOS build fails with `code signing error`** — the Apple
+certificate in `APPLE_CERTIFICATE` secret is expired or the `APPLE_SIGNING_IDENTITY`
+does not match the certificate's common name exactly. Verify with `security find-identity
+-p codesigning -v` on a local Mac.
+
+**release-desktop.yml: Windows leg skipped unexpectedly** — the `WINDOWS_CERTIFICATE`
+secret may be empty or set to a blank string. An empty (but present) secret evaluates to
+`''`, which the `env.HAS_WINDOWS_CERT` check treats as absent. Verify the secret value in
+Settings → Secrets.
+
+**Version already published on npm, workflow skips** — expected behavior for the stable
+channel on main. If a re-publish is needed, use `workflow_dispatch` with `dry_run: false`.
+
+**release-desktop.yml: tag already exists** — the `check-version` job detects the tag and
+sets `should_release=false`. To re-release the same version, delete the `desktop-v<x>` tag
+and re-run the workflow.
+
+## Provider Roadmap
+
+Additional CD provider reference docs are planned:
+
+- `reference/gitlab-cd.md` — GitLab CI/CD release pipelines
+- `reference/circleci-cd.md` — CircleCI release orbs
+
+These will follow the same structure as this document when authored.

package/templates/skills/cbp-setup-ci/SKILL.md

@@ -0,0 +1,175 @@
+---
+scope: org-shared
+name: cbp-setup-ci
+description: Detect CI platforms, write/update .codebyplan/ci.json, scaffold the GitHub Actions CI workflow, and enforce the required CI status check on the main branch. Interactive, idempotent.
+argument-hint: "[--force]"
+effort: xhigh
+allowed-tools: Read, Write, Edit, Bash(cat *), Bash(jq *), Bash(test *), Bash(ls *), Bash(codebyplan ci *), Bash(npx codebyplan ci *), Bash(gh api *), Bash(gh auth *), AskUserQuestion
+---
+
+# CI Setup
+
+Configure `.codebyplan/ci.json`, scaffold `.github/workflows/ci.yml`, and register the
+required GitHub status check so every PR runs a uniform CI gate.
+
+Invoke at any time. Already-configured platforms are preserved unless `--force` is passed.
+Pass `--force` to re-detect all platforms and overwrite existing platform keys.
+
+## Arguments
+
+Inspect `$ARGUMENTS` for `--force`. If present, set `force_mode = true`.
+Absent: idempotent mode — existing platform keys in `.codebyplan/ci.json` are preserved;
+`ci.yml` is not overwritten unless `--force`.
+
+## Step 1 — Detect platforms + read current state
+
+Run detection and read the existing config:
+
+```bash
+npx codebyplan ci init --dry-run --json
+cat .codebyplan/ci.json 2>/dev/null || echo '{}'
+```
+
+The first command lists detected platform slugs without writing any files. The second reads
+the current config for the idempotency check.
+
+Display a detection table:
+
+```
+Platform  | Detected | Configured | Status
+--------- | -------- | ---------- | ------
+next_js   | yes      | yes        | configured
+package   | yes      | no         | new
+nestjs    | no       | no         | absent
+tauri     | no       | no         | absent
+vscode    | no       | no         | absent
+expo      | no       | no         | absent
+```
+
+Also show workflow + required-check state if `.codebyplan/ci.json` exists:
+
+```bash
+jq '.workflow // {}' .codebyplan/ci.json 2>/dev/null
+```
+
+## Step 2 — Confirm the detected set
+
+`codebyplan ci init` writes ci.json from signal-based auto-detection (next.config /
+`@nestjs/core` / tauri.conf.json / `@types/vscode` / expo / a `packages/` dir) — it does NOT
+accept an explicit platform list. So this step CONFIRMS the detected set; it is not a free
+selector (a deselected platform cannot be withheld from `ci init`, and an undetected one
+cannot be added through it).
+
+AskUserQuestion (single choice):
+
+```
+Detected platforms: <list from Step 1>.
+These (merged with any already in .codebyplan/ci.json) will be written. Proceed?
+
+A) Proceed — write the detected platforms (recommended)
+B) Cancel — stop without writing
+```
+
+If an expected platform is MISSING: add its detection signal (e.g. a `next.config.ts`, or
+`@nestjs/core` in package.json) and re-run — detection is signal-based, not free-form.
+To DROP a platform: remove its signal and re-run with `--force`, or edit `.codebyplan/ci.json`
+directly. Without `--force`, existing platform keys are always preserved.
+
+## Step 3 — Write .codebyplan/ci.json
+
+Run `codebyplan ci init` to write the detected platforms:
+
+```bash
+npx codebyplan ci init [--force]
+```
+
+The CLI deep-merges newly confirmed platforms into the existing config; existing keys are
+left unchanged without `--force`. Confirm by reading back the result:
+
+```bash
+npx codebyplan ci init --dry-run --json
+```
+
+## Step 4 — Scaffold GitHub Actions workflow
+
+Preview, then write `.github/workflows/ci.yml`:
+
+```bash
+npx codebyplan ci scaffold-workflow --dry-run
+```
+
+If the workflow already exists and `--force` is not set, confirm with the user before
+writing. Then write:
+
+```bash
+npx codebyplan ci scaffold-workflow [--force] [--pnpm-version 10] [--node-version 22]
+```
+
+The scaffolded workflow installs pnpm + Node, caches the pnpm store, installs deps with
+`pnpm install --frozen-lockfile`, and runs full-repo checks under a single job named
+**Lint + typecheck + test + build**.
+
+If the CLI errors (network, missing bin), print the manual workflow template from
+`reference/github-actions.md` and continue — workflow authoring is non-fatal.
+
+## Step 5 — Enforce required status check
+
+Register the GitHub required status check on the main branch:
+
+```bash
+npx codebyplan ci enforce-check [--branch main] [--check-name "Lint + typecheck + test + build"]
+```
+
+Behaviour:
+- `workflow.required_check_enforced: true` already in `ci.json` — skip and report.
+- `gh auth` not configured or API call fails with a permissions error — print the manual
+  fallback and point to `reference/github-actions.md` § Manual Setup.
+- On success: the CLI writes `workflow.required_check_enforced: true` to `ci.json`.
+
+**Name-match rule**: `--check-name` MUST equal `jobs.<job-id>.name` in `ci.yml` exactly.
+A mismatch leaves the required check permanently pending. The default
+`"Lint + typecheck + test + build"` matches the scaffolded template.
+
+## Step 6 — Verify and report
+
+Re-read the config and confirm the workflow file exists:
+
+```bash
+cat .codebyplan/ci.json
+test -f .github/workflows/ci.yml && echo "ci.yml present" || echo "ci.yml MISSING"
+jq '.workflow' .codebyplan/ci.json
+```
+
+Emit a summary:
+
+```
+CI Setup — Complete
+
+Platform  | unit_test       | typecheck            | build            | lint        | e2e
+--------- | --------------- | -------------------- | ---------------- | ----------- | ---------
+next_js   | pnpm turbo test | pnpm turbo typecheck | pnpm turbo build | eslint.json | e2e.json
+package   | pnpm turbo test | pnpm turbo typecheck | pnpm turbo build | eslint.json | e2e.json
+
+Workflow:  .github/workflows/ci.yml  (present)
+Req check: Lint + typecheck + test + build  (enforced: yes)
+
+Next: push a branch and open a PR to verify the CI gate fires.
+```
+
+## Key Rules
+
+- Idempotent — re-running without `--force` preserves all existing platform keys and the
+  workflow file; it never clobbers a customized `ci.yml`
+- The required-check name MUST match `jobs.<job-id>.name` in `ci.yml` exactly — a mismatch
+  leaves the required check permanently pending
+- Repos without `ci.json` fall back via `codebyplan ci resolve <category>` — this skill
+  writes the config that resolve reads
+- This skill is org-shared; its template twin at
+  `packages/codebyplan-package/templates/skills/cbp-setup-ci/SKILL.md` must stay
+  byte-identical (GATE-6)
+
+## Additional resources
+
+- GitHub Actions workflow anatomy + required-check setup: [reference/github-actions.md](reference/github-actions.md)
+- CI config schema: `packages/codebyplan-package/src/lib/types.ts` (`CiConfig`)
+- Platform detection signals: `packages/codebyplan-package/src/lib/ci-init.ts` (`detectPlatforms`)