@catladder/cli 0.0.0-next-ddc387fe → 0.0.0-next-d13ff46d

package/dist/bundles/skills/catladder-config/SKILL.md

@@ -117,3 +117,7 @@ escape hatches to shrink over time, not accumulate.
 - `catladder-releases` — releasing (semantic-release / changesets)
 - `catladder-pipelines` — how the generated pipelines work, debugging CI
 - `catladder-cli` — non-interactive CLI usage and command reference
+- `catladder-migrate-ci-backend` — moving a project between GitLab CI
+  and GitHub Actions
+- `catladder-migrate-release-method` — switching between
+  semantic-release and changesets

package/dist/bundles/skills/catladder-migrate-ci-backend/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: catladder-migrate-ci-backend
+description: Guiding a catladder project from one CI backend to the other — GitLab CI → GitHub Actions or GitHub Actions → GitLab CI — using the `pipelines` config to run both in parallel first, then cutting over. Covers the blockers to check up front (unsupported features, secrets vault, release tokens, container registry) and the manual cleanup a cut-over needs. Use when moving a project between GitLab and GitHub, enabling a second CI backend, or decommissioning one. Triggers on "migrate to github", "move to github actions", "switch from gitlab to github", "migrate to gitlab", "enable github pipeline", "run both pipelines", "gitRemote", "secrets-sync-github".
+---
+
+# Migrating between GitLab CI and GitHub Actions
+
+catladder generates pipelines for both CI systems from the same
+`catladder.ts`, and **both can be enabled at once**. That is what makes
+this migration safe: run the new backend in parallel with the old one on
+the same commits, compare, and only then cut over.
+
+```ts
+pipelines: {
+  gitlab: true,
+  github: { gitRemote: "github" },
+}
+```
+
+(`pipelineType: "gitlab"` is the deprecated single-backend form —
+replace it with `pipelines` as the first step.)
+
+Never do this as one big-bang commit. Work through the steps below and
+**stop at each decision point that is the user's to make** — creating
+repositories, pushing to a new host, and moving secrets are all
+outward-facing actions that need their explicit go-ahead.
+
+## Step 0 — scope it with the user
+
+Ask up front (once, with your reading of the repo attached):
+
+- **Direction and end state**: is the old backend going away, or do both
+  stay live permanently (some projects keep GitLab for releases and
+  GitHub for PR checks)?
+- **Repository**: does the target repo already exist, or must it be
+  created and pushed?
+- **Which backend owns releases** during the parallel phase — see step 6.
+- **Where secret values live afterwards** — see step 5. This is the one
+  that blocks decommissioning, so raise it early rather than at the end.
+
+## Step 1 — check the blockers before changing anything
+
+Read the project's `catladder.ts` and report what will *not* carry over.
+Going **GitLab → GitHub**:
+
+- **`deploy: { type: "pages" }`** — not supported on the GitHub backend.
+  Those components simply generate no deploy jobs there (a warning, not
+  a generation error), so the site silently stops being published.
+- **`agents`** (the Claude agent integration) — GitLab-only; agent jobs
+  are skipped on GitHub.
+- **Default branch must be `main`** — the generated GitHub main-branch
+  workflow triggers on `push: branches: [main]`. A project on `master`
+  or `develop` gets a workflow that never runs.
+- **`hooks.transformYamlBeforeWrite` / `transformFileBeforeWrite`** —
+  hooks run for the GitHub files too. Any hook that keys on
+  `.gitlab-ci.yml` or on GitLab's YAML shape needs revisiting; a hook
+  that blindly rewrites `data.include` will corrupt workflow files.
+- **`customJobs`** do carry over (they are platform-neutral job specs),
+  but anything GitLab-shaped *inside* them — raw `rules:`, `only:`,
+  GitLab-specific job keys — does not.
+- **`secrets.vault: "gitlab"`** (the default) requires a GitLab project.
+  See step 5.
+
+Going **GitHub → GitLab** the feature list is easier (GitLab supports
+everything the GitHub backend does), but still check the hooks, and note
+that GitLab needs a real access token for releases (step 6).
+
+Report this list to the user before touching the config. If a blocker
+has no first-class solution, that is worth an issue on catladder —
+https://git.panter.ch/catladder/catladder/-/issues.
+
+## Step 2 — get the repository onto the target host
+
+For a new GitHub repo: create it and push `main` plus **all tags**
+(the release job derives the version from the nearest `v*` tag — a
+tagless mirror re-releases `1.0.0`).
+
+Add it as a **second remote** rather than replacing `origin`, so the old
+backend keeps working during the parallel phase:
+
+```bash
+git remote add github git@github.com:<owner>/<repo>.git
+git push github main --tags
+```
+
+Ask before creating the repository or pushing — this publishes the code
+to a new host.
+
+## Step 3 — enable both backends
+
+```ts
+pipelines: {
+  gitlab: true,
+  github: { gitRemote: "github" },
+}
+```
+
+`gitRemote` tells catladder which git remote points at that CI system's
+repository (default `origin`). Then regenerate and commit:
+
+```bash
+yarn catenv
+```
+
+The two file sets live side by side and never collide:
+
+| backend | generated files |
+|---|---|
+| gitlab | `.gitlab-ci.yml`, `.catladder-generated/gitlab/` |
+| github | `.github/workflows/catladder-*.yml`, `.catladder-generated/github/scripts/` |
+
+Shared (generated once for both): `.catladder-generated/images/` and
+`.catladder-generated/catci/`.
+
+If the hosted runners of the new backend are smaller than the old ones,
+tune them per backend instead of globally:
+
+```ts
+github: { gitRemote: "github", runnerVariables: { TURBO_CONCURRENCY: "2" } },
+```
+
+## Step 4 — mirror the secrets to the new backend
+
+GitHub Actions cannot read the vault at runtime, so the values must be
+pushed into GitHub:
+
+```bash
+gh auth login
+yarn catladder project secrets-sync-github
+```
+
+This creates one **GitHub environment per catladder env** and writes
+each secret/variable into the environment(s) whose generated jobs
+actually reference it. (Environments are not cosmetic: GitHub caps a
+repository at 100 secrets, which a multi-env project blows through; the
+cap applies per environment.) Re-run it after every secret change for as
+long as both backends are live.
+
+Then verify:
+
+```bash
+yarn catladder project doctor
+```
+
+It compares the secret/variable *names* the generated workflows
+reference against what is actually set, per environment, and prints the
+command that heals each gap. Values cannot be compared — GitHub secrets
+are write-only by design.
+
+## Step 5 — the secrets vault is what actually blocks decommissioning
+
+`secrets.vault` defaults to `"gitlab"`: the GitLab project variables
+double as the **readable source of truth**, and the CI backends only
+ever get mirrored copies. GitHub secrets can never serve as that source.
+
+So if GitLab is going away, move the vault **before** deleting anything:
+
+```ts
+secrets: {
+  vault: { type: "bitwarden", collection: "catladder" },
+}
+```
+
+A safe order:
+
+1. `yarn catladder project secrets-pull <env>: --out /tmp/secrets.yml`
+   against the old vault (unset values show as `🚨 FILL ME`)
+2. switch `secrets.vault` in `catladder.ts`, `yarn catenv`
+3. `yarn catladder project secrets-push <env>: --file /tmp/secrets.yml`
+4. `yarn catladder project doctor`, then delete the temp file
+5. only now decommission the GitLab project
+
+Never commit the intermediate file, and see the `catladder-secrets`
+skill for the exact command surface.
+
+## Step 6 — releases and tokens
+
+- **GitLab** needs a `GL_TOKEN` project access token (named
+  `semantic-release`) to push the release commit and tag. It is created
+  and rotated by `yarn catladder project setup`.
+- **GitHub** needs nothing extra — the release jobs use the built-in
+  `github.token`. Tags pushed by that token do not retrigger workflows,
+  so the release job dispatches the tagged-release workflow explicitly;
+  that is built in and needs no configuration.
+- **Only one backend should own releases at a time.** Both backends
+  generate release jobs, and with `releases: { when: "auto" }` both would
+  try to tag the same commit. During the parallel phase, agree with the
+  user which backend releases; the other one's release job must stay
+  unclicked (`when: "manual"`) or the parallel phase must be short.
+
+See the `catladder-releases` skill for how the release jobs differ
+(GitLab manual job vs. GitHub dispatch workflow).
+
+## Step 7 — registry and the first run
+
+The container registry changes with the backend: `$CI_REGISTRY_IMAGE` on
+GitLab, `ghcr.io/<owner>/<repo>` on GitHub. Consequences to state
+explicitly:
+
+- The first pipeline on the new backend **rebuilds every job image and
+  every app image** — it will be slow, and that is expected, not a bug.
+- The deploy target must be able to **pull from the new registry**.
+  catladder does not manage image-pull credentials on the cluster or on
+  Cloud Run, so check GHCR package visibility / the pull secret with
+  whoever owns the target *before* pointing a real environment at it.
+
+## Step 8 — run both, compare, then cut over
+
+Let both pipelines run on the same commits until the new backend is
+green for all three triggers: a merge/pull request, the main branch, and
+a tagged release. Only then flip:
+
+```ts
+pipelines: { github: true }
+```
+
+```bash
+yarn catenv
+```
+
+⚠️ **catladder only cleans up backends that are still enabled** — the
+disabled backend's files stay behind and must be deleted by hand:
+
+- gitlab: `.gitlab-ci.yml` and `.catladder-generated/gitlab/`
+- github: `.github/workflows/catladder-*.yml` and
+  `.catladder-generated/github/scripts/`
+
+Then, if the new host becomes `origin`, update the remotes and drop the
+now-wrong `gitRemote`, regenerate once more, and finish with
+`yarn catladder project doctor`.
+
+## After the cut-over
+
+- Tell the team where the pipeline lives now and how manual actions
+  work there (on GitHub, manual jobs are dispatch workflows in the
+  Actions sidebar — `🚀 catladder create release`, `▶️ catladder deploy`,
+  `⏹️ catladder stop`, `↩️ catladder rollback`).
+- Revoke tokens that are no longer needed (`GL_TOKEN`).
+- Keep the old host readable until the vault migration is verified in
+  practice — a rotated secret is much cheaper to recover than a deleted
+  one.
+
+## Related skills
+
+- `catladder-config` — `catladder.ts` structure, `pipelines`, regeneration
+- `catladder-secrets` — vault, `secrets-sync-github`, secret commands
+- `catladder-releases` — release jobs and how they differ per backend
+- `catladder-pipelines` — triggers, generated file layout, debugging CI
+- `catladder-cli` — `project doctor`, `project setup`, non-interactive usage

package/dist/bundles/skills/catladder-migrate-release-method/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: catladder-migrate-release-method
+description: Migrating a catladder project from one release method to another — semantic-release (conventional commits) ↔ changesets (`.changeset/*.md` files) — including backfilling changesets for everything merged since the last release tag so the changelog and the version bump stay correct. Use when switching `releases.method`, adopting changesets in a project that has been releasing with semantic-release, or going back. Triggers on "switch to changesets", "migrate to changesets", "adopt changesets", "use changesets instead", "back to semantic-release", "change the release method", "backfill changesets".
+---
+
+# Migrating the release method
+
+catladder projects release either with **semantic-release** (version
+derived from conventional commit messages) or with **changesets**
+(version derived from `.changeset/*.md` files that developers write
+deliberately). The method is one field in `catladder.ts`:
+
+```ts
+releases: {
+  when: "manual",
+  method: "changesets", // "semantic-release" (default) | "changesets"
+}
+```
+
+Flipping that field is **not** the whole migration. Read
+`catladder-releases` first if you are unsure how either method works.
+
+## Why a config flip is not enough
+
+The two methods disagree about where "what changed since the last
+release" lives:
+
+| | semantic-release | changesets |
+|---|---|---|
+| source of the bump | commit messages since the last `v*` tag | pending `.changeset/*.md` |
+| changelog text | generated from those commits | the changeset summaries |
+
+Everything up to and including the **last `v*` tag** is already written
+into `CHANGELOG.md` — that part is settled and must not be touched.
+But everything merged **after** that tag is exactly what semantic-release
+would have released next, and after the switch the release job can no
+longer see it. Without a backfill:
+
+- those changes silently disappear from the changelog, and
+- the next version is likely too small (a `feat:` merged since the tag
+  releases as a patch, or nothing releases at all).
+
+So the migration is: **backfill changesets for the commits since the
+last release tag, then flip the config, in one merge request.**
+
+## Step 1 — establish the range
+
+Work on a branch (never directly on the main branch).
+
+```bash
+git fetch --tags
+git describe --tags --abbrev=0 --match "v[0-9]*"
+```
+
+That is the same tag the release job uses. Then list the candidates:
+
+```bash
+git log <tag>..HEAD --no-merges --pretty=format:"%h %s"
+```
+
+Cases:
+
+- **No `v*` tag at all** — the project has never released. There is
+  nothing to backfill; the first changesets release will be `1.0.0`
+  regardless of the bump levels. Skip to step 5.
+- **The tag is the current HEAD** — nothing merged since the release,
+  nothing to backfill. Skip to step 5.
+
+## Step 2 — drop what is not user-facing
+
+From that list, remove:
+
+- `chore(release): X.Y.Z` commits (semantic-release's own commits)
+- pure `chore:` / `ci:` / `build:` / `test:` / internal-refactor commits
+- documentation-only changes, unless the docs *are* the product
+
+Keep everything a user of this app would notice. When a commit message
+is too vague to judge, look at the diff (`git show <sha> --stat`) before
+deciding — do not guess from the subject line alone.
+
+## Step 3 — group the remaining commits
+
+A changeset is **one user-facing change**, not one commit. Several
+commits that built the same feature belong in one changeset; one commit
+that shipped two unrelated things belongs in two.
+
+**Decide yourself** when the remaining set is small (roughly ≤ 5
+commits) and the grouping is obvious — then show the user the resulting
+changesets and let them correct.
+
+**Ask the user first** when there are many commits, or when the grouping
+is genuinely ambiguous. Ask once, with a concrete proposal attached
+rather than an open question — for example:
+
+- the proposed grouping as a list ("these 4 commits → one changeset
+  *Export endpoint*"), asking whether to merge or split any of them
+- the commits you could not classify: user-facing or internal?
+- any change they consider **breaking** — that alone decides whether the
+  next release is a major
+
+Do not ask about things you can answer from the diff.
+
+## Step 4 — pick the bump level per changeset
+
+- **major** — breaking change (`feat!:`/`fix!:`, or a `BREAKING CHANGE:`
+  footer, or anything that forces consumers to adapt)
+- **minor** — a new feature (`feat:`)
+- **patch** — fixes, performance, reverts, and anything else user-facing
+
+Only the **highest** pending bump decides the next version, but write
+the honest level on each changeset anyway: the changelog groups by it.
+Note that `0.x` versions get no special treatment — a minor bump on
+`v0.3.1` produces `0.4.0`.
+
+## Step 5 — write the changeset files
+
+One file per changeset, `.changeset/<kebab-case-slug>.md`:
+
+```md
+---
+"<appName>": minor
+---
+
+One or two sentences describing the change from the user's perspective.
+```
+
+- The package name in the frontmatter is **ignored** (catladder versions
+  from git tags, not from package.json) — use the project's `appName`
+  for readability.
+- Write the summary for someone reading the changelog, not the commit
+  log: what changed and why it matters, not `refactor foo helper`.
+- Reference the MR/PR or issue when it helps the reader.
+
+Also add `.changeset/README.md` so the next developer knows what the
+folder is:
+
+````md
+# Changesets
+
+This repo releases with catladder's `changesets` release method: every
+user-facing change merges together with a changeset file in this
+directory. The release job consumes all pending changesets — the highest
+bump (applied to the last `v*` tag) becomes the new version, the
+summaries become the changelog entries.
+
+Write one by hand (`.changeset/<descriptive-name>.md`):
+
+```md
+---
+"<appName>": minor
+---
+
+One or two sentences describing the change from the user's perspective.
+```
+
+Bump levels: `major` (breaking), `minor` (feature), `patch` (fix).
+The package name in the frontmatter is ignored — only the bump counts.
+`yarn changeset` also works if you prefer the interactive prompt.
+
+No pending changesets on the main branch means the release job is a
+no-op.
+````
+
+## Step 6 — flip the config and regenerate
+
+```ts
+releases: {
+  when: "manual",       // unchanged — `when` is independent of `method`
+  method: "changesets",
+}
+```
+
+```bash
+yarn catenv
+```
+
+Commit the regenerated files (`.catladder-generated/`, `.gitlab-ci.yml`,
+`.github/workflows/catladder-*`) together with the config change and the
+changesets — see the `catladder-config` skill.
+
+## Step 7 — verify before merging
+
+- State the expected outcome explicitly: *last tag `vX.Y.Z` + highest
+  pending bump = next release `vA.B.C`*. If that is not what the user
+  expects, the bump levels are wrong.
+- The merge request now runs the **`🦋 changeset check`** job. It should
+  report the pending changesets and that same version. A yellow check
+  only means "this MR adds no changeset" — for the migration MR itself
+  that is not the case, so expect it green.
+- Do **not** hand-write `CHANGELOG.md`. The release job prepends the new
+  section; anything you write by hand there gets duplicated.
+- Leave any `.releaserc` / `release.config.js` alone if the project has
+  one — it becomes inert, and deleting it is a separate cleanup.
+
+## Step 8 — hand over to the team
+
+After merging, tell the user what changes for everyone:
+
+- every user-facing MR now needs a `.changeset/*.md` file; the
+  `🦋 changeset check` job warns (without blocking) when one is missing
+- commit messages no longer decide the version — conventional commits
+  are still nice, but purely cosmetic now
+- if something was merged without a changeset and must ship anyway, the
+  **force release** escape hatch releases a patch (GitLab:
+  `⚠️ force create release`, GitHub: the *force* checkbox of the
+  `🚀 catladder create release` workflow)
+
+## The other direction: changesets → semantic-release
+
+Same shape, mirrored, with one loss to flag up front:
+
+1. **Pending changesets are not converted.** Their summaries would
+   simply vanish from the changelog. Either cut one last changesets
+   release first (draining `.changeset/`), or fold each summary into the
+   changelog by hand before removing the files. Tell the user which one
+   you are doing.
+2. Commits since the last tag must carry conventional messages for
+   semantic-release to see them — history cannot be rewritten after the
+   fact, so accept that the first semantic-release version may
+   under-report. Say so rather than silently releasing a patch.
+3. Set `method: "semantic-release"` (or drop the field — it is the
+   default), run `yarn catenv`, commit the regenerated files.
+4. Delete `.changeset/` including its `README.md`.
+5. From then on the version comes from commit messages again, and the
+   `🦋 changeset check` job disappears from MR pipelines.
+
+## Related skills
+
+- `catladder-releases` — how both methods work, the release jobs and the
+  security-audit gate
+- `catladder-config` — catladder.ts structure and regeneration
+- `catladder-migrate-ci-backend` — migrating between GitLab CI and
+  GitHub Actions

package/dist/bundles/skills/catladder-pipelines/SKILL.md

@@ -93,3 +93,5 @@ Useful CLI commands (see the `catladder-cli` skill for invocation):
 - `catladder-releases` — the `taggedRelease` flow and security-audit gate
 - `catladder-secrets` — env vars and secret management
 - `catladder-cli` — non-interactive CLI usage and command reference
+- `catladder-migrate-ci-backend` — moving between GitLab CI and GitHub
+  Actions (running both in parallel, then cutting over)

package/dist/bundles/skills/catladder-releases/SKILL.md

@@ -127,3 +127,6 @@ the `security` commands in the `catladder-cli` reference.
 - `catladder-config` — catladder.ts structure and regeneration
 - `catladder-pipelines` — the `taggedRelease` trigger and stage/prod deploys
 - `catladder-cli` — `project ci` and `security` commands
+- `catladder-migrate-release-method` — switching an existing project
+  between semantic-release and changesets (incl. backfilling changesets
+  for everything merged since the last release tag)

package/dist/bundles/skills/catladder-secrets/SKILL.md

@@ -107,3 +107,5 @@ suspecting anything else.
 - `catladder-deploys` — runtime deploy config
 - `catladder-pipelines` — how the generated pipelines work
 - `catladder-cli` — non-interactive CLI usage and command reference
+- `catladder-migrate-ci-backend` — moving between CI backends (the vault
+  is what blocks decommissioning the old one)

package/dist/skills/catladder-config/SKILL.md

@@ -117,3 +117,7 @@ escape hatches to shrink over time, not accumulate.
 - `catladder-releases` — releasing (semantic-release / changesets)
 - `catladder-pipelines` — how the generated pipelines work, debugging CI
 - `catladder-cli` — non-interactive CLI usage and command reference
+- `catladder-migrate-ci-backend` — moving a project between GitLab CI
+  and GitHub Actions
+- `catladder-migrate-release-method` — switching between
+  semantic-release and changesets

package/dist/skills/catladder-migrate-ci-backend/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: catladder-migrate-ci-backend
+description: Guiding a catladder project from one CI backend to the other — GitLab CI → GitHub Actions or GitHub Actions → GitLab CI — using the `pipelines` config to run both in parallel first, then cutting over. Covers the blockers to check up front (unsupported features, secrets vault, release tokens, container registry) and the manual cleanup a cut-over needs. Use when moving a project between GitLab and GitHub, enabling a second CI backend, or decommissioning one. Triggers on "migrate to github", "move to github actions", "switch from gitlab to github", "migrate to gitlab", "enable github pipeline", "run both pipelines", "gitRemote", "secrets-sync-github".
+---
+
+# Migrating between GitLab CI and GitHub Actions
+
+catladder generates pipelines for both CI systems from the same
+`catladder.ts`, and **both can be enabled at once**. That is what makes
+this migration safe: run the new backend in parallel with the old one on
+the same commits, compare, and only then cut over.
+
+```ts
+pipelines: {
+  gitlab: true,
+  github: { gitRemote: "github" },
+}
+```
+
+(`pipelineType: "gitlab"` is the deprecated single-backend form —
+replace it with `pipelines` as the first step.)
+
+Never do this as one big-bang commit. Work through the steps below and
+**stop at each decision point that is the user's to make** — creating
+repositories, pushing to a new host, and moving secrets are all
+outward-facing actions that need their explicit go-ahead.
+
+## Step 0 — scope it with the user
+
+Ask up front (once, with your reading of the repo attached):
+
+- **Direction and end state**: is the old backend going away, or do both
+  stay live permanently (some projects keep GitLab for releases and
+  GitHub for PR checks)?
+- **Repository**: does the target repo already exist, or must it be
+  created and pushed?
+- **Which backend owns releases** during the parallel phase — see step 6.
+- **Where secret values live afterwards** — see step 5. This is the one
+  that blocks decommissioning, so raise it early rather than at the end.
+
+## Step 1 — check the blockers before changing anything
+
+Read the project's `catladder.ts` and report what will *not* carry over.
+Going **GitLab → GitHub**:
+
+- **`deploy: { type: "pages" }`** — not supported on the GitHub backend.
+  Those components simply generate no deploy jobs there (a warning, not
+  a generation error), so the site silently stops being published.
+- **`agents`** (the Claude agent integration) — GitLab-only; agent jobs
+  are skipped on GitHub.
+- **Default branch must be `main`** — the generated GitHub main-branch
+  workflow triggers on `push: branches: [main]`. A project on `master`
+  or `develop` gets a workflow that never runs.
+- **`hooks.transformYamlBeforeWrite` / `transformFileBeforeWrite`** —
+  hooks run for the GitHub files too. Any hook that keys on
+  `.gitlab-ci.yml` or on GitLab's YAML shape needs revisiting; a hook
+  that blindly rewrites `data.include` will corrupt workflow files.
+- **`customJobs`** do carry over (they are platform-neutral job specs),
+  but anything GitLab-shaped *inside* them — raw `rules:`, `only:`,
+  GitLab-specific job keys — does not.
+- **`secrets.vault: "gitlab"`** (the default) requires a GitLab project.
+  See step 5.
+
+Going **GitHub → GitLab** the feature list is easier (GitLab supports
+everything the GitHub backend does), but still check the hooks, and note
+that GitLab needs a real access token for releases (step 6).
+
+Report this list to the user before touching the config. If a blocker
+has no first-class solution, that is worth an issue on catladder —
+https://git.panter.ch/catladder/catladder/-/issues.
+
+## Step 2 — get the repository onto the target host
+
+For a new GitHub repo: create it and push `main` plus **all tags**
+(the release job derives the version from the nearest `v*` tag — a
+tagless mirror re-releases `1.0.0`).
+
+Add it as a **second remote** rather than replacing `origin`, so the old
+backend keeps working during the parallel phase:
+
+```bash
+git remote add github git@github.com:<owner>/<repo>.git
+git push github main --tags
+```
+
+Ask before creating the repository or pushing — this publishes the code
+to a new host.
+
+## Step 3 — enable both backends
+
+```ts
+pipelines: {
+  gitlab: true,
+  github: { gitRemote: "github" },
+}
+```
+
+`gitRemote` tells catladder which git remote points at that CI system's
+repository (default `origin`). Then regenerate and commit:
+
+```bash
+yarn catenv
+```
+
+The two file sets live side by side and never collide:
+
+| backend | generated files |
+|---|---|
+| gitlab | `.gitlab-ci.yml`, `.catladder-generated/gitlab/` |
+| github | `.github/workflows/catladder-*.yml`, `.catladder-generated/github/scripts/` |
+
+Shared (generated once for both): `.catladder-generated/images/` and
+`.catladder-generated/catci/`.
+
+If the hosted runners of the new backend are smaller than the old ones,
+tune them per backend instead of globally:
+
+```ts
+github: { gitRemote: "github", runnerVariables: { TURBO_CONCURRENCY: "2" } },
+```
+
+## Step 4 — mirror the secrets to the new backend
+
+GitHub Actions cannot read the vault at runtime, so the values must be
+pushed into GitHub:
+
+```bash
+gh auth login
+yarn catladder project secrets-sync-github
+```
+
+This creates one **GitHub environment per catladder env** and writes
+each secret/variable into the environment(s) whose generated jobs
+actually reference it. (Environments are not cosmetic: GitHub caps a
+repository at 100 secrets, which a multi-env project blows through; the
+cap applies per environment.) Re-run it after every secret change for as
+long as both backends are live.
+
+Then verify:
+
+```bash
+yarn catladder project doctor
+```
+
+It compares the secret/variable *names* the generated workflows
+reference against what is actually set, per environment, and prints the
+command that heals each gap. Values cannot be compared — GitHub secrets
+are write-only by design.
+
+## Step 5 — the secrets vault is what actually blocks decommissioning
+
+`secrets.vault` defaults to `"gitlab"`: the GitLab project variables
+double as the **readable source of truth**, and the CI backends only
+ever get mirrored copies. GitHub secrets can never serve as that source.
+
+So if GitLab is going away, move the vault **before** deleting anything:
+
+```ts
+secrets: {
+  vault: { type: "bitwarden", collection: "catladder" },
+}
+```
+
+A safe order:
+
+1. `yarn catladder project secrets-pull <env>: --out /tmp/secrets.yml`
+   against the old vault (unset values show as `🚨 FILL ME`)
+2. switch `secrets.vault` in `catladder.ts`, `yarn catenv`
+3. `yarn catladder project secrets-push <env>: --file /tmp/secrets.yml`
+4. `yarn catladder project doctor`, then delete the temp file
+5. only now decommission the GitLab project
+
+Never commit the intermediate file, and see the `catladder-secrets`
+skill for the exact command surface.
+
+## Step 6 — releases and tokens
+
+- **GitLab** needs a `GL_TOKEN` project access token (named
+  `semantic-release`) to push the release commit and tag. It is created
+  and rotated by `yarn catladder project setup`.
+- **GitHub** needs nothing extra — the release jobs use the built-in
+  `github.token`. Tags pushed by that token do not retrigger workflows,
+  so the release job dispatches the tagged-release workflow explicitly;
+  that is built in and needs no configuration.
+- **Only one backend should own releases at a time.** Both backends
+  generate release jobs, and with `releases: { when: "auto" }` both would
+  try to tag the same commit. During the parallel phase, agree with the
+  user which backend releases; the other one's release job must stay
+  unclicked (`when: "manual"`) or the parallel phase must be short.
+
+See the `catladder-releases` skill for how the release jobs differ
+(GitLab manual job vs. GitHub dispatch workflow).
+
+## Step 7 — registry and the first run
+
+The container registry changes with the backend: `$CI_REGISTRY_IMAGE` on
+GitLab, `ghcr.io/<owner>/<repo>` on GitHub. Consequences to state
+explicitly:
+
+- The first pipeline on the new backend **rebuilds every job image and
+  every app image** — it will be slow, and that is expected, not a bug.
+- The deploy target must be able to **pull from the new registry**.
+  catladder does not manage image-pull credentials on the cluster or on
+  Cloud Run, so check GHCR package visibility / the pull secret with
+  whoever owns the target *before* pointing a real environment at it.
+
+## Step 8 — run both, compare, then cut over
+
+Let both pipelines run on the same commits until the new backend is
+green for all three triggers: a merge/pull request, the main branch, and
+a tagged release. Only then flip:
+
+```ts
+pipelines: { github: true }
+```
+
+```bash
+yarn catenv
+```
+
+⚠️ **catladder only cleans up backends that are still enabled** — the
+disabled backend's files stay behind and must be deleted by hand:
+
+- gitlab: `.gitlab-ci.yml` and `.catladder-generated/gitlab/`
+- github: `.github/workflows/catladder-*.yml` and
+  `.catladder-generated/github/scripts/`
+
+Then, if the new host becomes `origin`, update the remotes and drop the
+now-wrong `gitRemote`, regenerate once more, and finish with
+`yarn catladder project doctor`.
+
+## After the cut-over
+
+- Tell the team where the pipeline lives now and how manual actions
+  work there (on GitHub, manual jobs are dispatch workflows in the
+  Actions sidebar — `🚀 catladder create release`, `▶️ catladder deploy`,
+  `⏹️ catladder stop`, `↩️ catladder rollback`).
+- Revoke tokens that are no longer needed (`GL_TOKEN`).
+- Keep the old host readable until the vault migration is verified in
+  practice — a rotated secret is much cheaper to recover than a deleted
+  one.
+
+## Related skills
+
+- `catladder-config` — `catladder.ts` structure, `pipelines`, regeneration
+- `catladder-secrets` — vault, `secrets-sync-github`, secret commands
+- `catladder-releases` — release jobs and how they differ per backend
+- `catladder-pipelines` — triggers, generated file layout, debugging CI
+- `catladder-cli` — `project doctor`, `project setup`, non-interactive usage

package/dist/skills/catladder-migrate-release-method/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: catladder-migrate-release-method
+description: Migrating a catladder project from one release method to another — semantic-release (conventional commits) ↔ changesets (`.changeset/*.md` files) — including backfilling changesets for everything merged since the last release tag so the changelog and the version bump stay correct. Use when switching `releases.method`, adopting changesets in a project that has been releasing with semantic-release, or going back. Triggers on "switch to changesets", "migrate to changesets", "adopt changesets", "use changesets instead", "back to semantic-release", "change the release method", "backfill changesets".
+---
+
+# Migrating the release method
+
+catladder projects release either with **semantic-release** (version
+derived from conventional commit messages) or with **changesets**
+(version derived from `.changeset/*.md` files that developers write
+deliberately). The method is one field in `catladder.ts`:
+
+```ts
+releases: {
+  when: "manual",
+  method: "changesets", // "semantic-release" (default) | "changesets"
+}
+```
+
+Flipping that field is **not** the whole migration. Read
+`catladder-releases` first if you are unsure how either method works.
+
+## Why a config flip is not enough
+
+The two methods disagree about where "what changed since the last
+release" lives:
+
+| | semantic-release | changesets |
+|---|---|---|
+| source of the bump | commit messages since the last `v*` tag | pending `.changeset/*.md` |
+| changelog text | generated from those commits | the changeset summaries |
+
+Everything up to and including the **last `v*` tag** is already written
+into `CHANGELOG.md` — that part is settled and must not be touched.
+But everything merged **after** that tag is exactly what semantic-release
+would have released next, and after the switch the release job can no
+longer see it. Without a backfill:
+
+- those changes silently disappear from the changelog, and
+- the next version is likely too small (a `feat:` merged since the tag
+  releases as a patch, or nothing releases at all).
+
+So the migration is: **backfill changesets for the commits since the
+last release tag, then flip the config, in one merge request.**
+
+## Step 1 — establish the range
+
+Work on a branch (never directly on the main branch).
+
+```bash
+git fetch --tags
+git describe --tags --abbrev=0 --match "v[0-9]*"
+```
+
+That is the same tag the release job uses. Then list the candidates:
+
+```bash
+git log <tag>..HEAD --no-merges --pretty=format:"%h %s"
+```
+
+Cases:
+
+- **No `v*` tag at all** — the project has never released. There is
+  nothing to backfill; the first changesets release will be `1.0.0`
+  regardless of the bump levels. Skip to step 5.
+- **The tag is the current HEAD** — nothing merged since the release,
+  nothing to backfill. Skip to step 5.
+
+## Step 2 — drop what is not user-facing
+
+From that list, remove:
+
+- `chore(release): X.Y.Z` commits (semantic-release's own commits)
+- pure `chore:` / `ci:` / `build:` / `test:` / internal-refactor commits
+- documentation-only changes, unless the docs *are* the product
+
+Keep everything a user of this app would notice. When a commit message
+is too vague to judge, look at the diff (`git show <sha> --stat`) before
+deciding — do not guess from the subject line alone.
+
+## Step 3 — group the remaining commits
+
+A changeset is **one user-facing change**, not one commit. Several
+commits that built the same feature belong in one changeset; one commit
+that shipped two unrelated things belongs in two.
+
+**Decide yourself** when the remaining set is small (roughly ≤ 5
+commits) and the grouping is obvious — then show the user the resulting
+changesets and let them correct.
+
+**Ask the user first** when there are many commits, or when the grouping
+is genuinely ambiguous. Ask once, with a concrete proposal attached
+rather than an open question — for example:
+
+- the proposed grouping as a list ("these 4 commits → one changeset
+  *Export endpoint*"), asking whether to merge or split any of them
+- the commits you could not classify: user-facing or internal?
+- any change they consider **breaking** — that alone decides whether the
+  next release is a major
+
+Do not ask about things you can answer from the diff.
+
+## Step 4 — pick the bump level per changeset
+
+- **major** — breaking change (`feat!:`/`fix!:`, or a `BREAKING CHANGE:`
+  footer, or anything that forces consumers to adapt)
+- **minor** — a new feature (`feat:`)
+- **patch** — fixes, performance, reverts, and anything else user-facing
+
+Only the **highest** pending bump decides the next version, but write
+the honest level on each changeset anyway: the changelog groups by it.
+Note that `0.x` versions get no special treatment — a minor bump on
+`v0.3.1` produces `0.4.0`.
+
+## Step 5 — write the changeset files
+
+One file per changeset, `.changeset/<kebab-case-slug>.md`:
+
+```md
+---
+"<appName>": minor
+---
+
+One or two sentences describing the change from the user's perspective.
+```
+
+- The package name in the frontmatter is **ignored** (catladder versions
+  from git tags, not from package.json) — use the project's `appName`
+  for readability.
+- Write the summary for someone reading the changelog, not the commit
+  log: what changed and why it matters, not `refactor foo helper`.
+- Reference the MR/PR or issue when it helps the reader.
+
+Also add `.changeset/README.md` so the next developer knows what the
+folder is:
+
+````md
+# Changesets
+
+This repo releases with catladder's `changesets` release method: every
+user-facing change merges together with a changeset file in this
+directory. The release job consumes all pending changesets — the highest
+bump (applied to the last `v*` tag) becomes the new version, the
+summaries become the changelog entries.
+
+Write one by hand (`.changeset/<descriptive-name>.md`):
+
+```md
+---
+"<appName>": minor
+---
+
+One or two sentences describing the change from the user's perspective.
+```
+
+Bump levels: `major` (breaking), `minor` (feature), `patch` (fix).
+The package name in the frontmatter is ignored — only the bump counts.
+`yarn changeset` also works if you prefer the interactive prompt.
+
+No pending changesets on the main branch means the release job is a
+no-op.
+````
+
+## Step 6 — flip the config and regenerate
+
+```ts
+releases: {
+  when: "manual",       // unchanged — `when` is independent of `method`
+  method: "changesets",
+}
+```
+
+```bash
+yarn catenv
+```
+
+Commit the regenerated files (`.catladder-generated/`, `.gitlab-ci.yml`,
+`.github/workflows/catladder-*`) together with the config change and the
+changesets — see the `catladder-config` skill.
+
+## Step 7 — verify before merging
+
+- State the expected outcome explicitly: *last tag `vX.Y.Z` + highest
+  pending bump = next release `vA.B.C`*. If that is not what the user
+  expects, the bump levels are wrong.
+- The merge request now runs the **`🦋 changeset check`** job. It should
+  report the pending changesets and that same version. A yellow check
+  only means "this MR adds no changeset" — for the migration MR itself
+  that is not the case, so expect it green.
+- Do **not** hand-write `CHANGELOG.md`. The release job prepends the new
+  section; anything you write by hand there gets duplicated.
+- Leave any `.releaserc` / `release.config.js` alone if the project has
+  one — it becomes inert, and deleting it is a separate cleanup.
+
+## Step 8 — hand over to the team
+
+After merging, tell the user what changes for everyone:
+
+- every user-facing MR now needs a `.changeset/*.md` file; the
+  `🦋 changeset check` job warns (without blocking) when one is missing
+- commit messages no longer decide the version — conventional commits
+  are still nice, but purely cosmetic now
+- if something was merged without a changeset and must ship anyway, the
+  **force release** escape hatch releases a patch (GitLab:
+  `⚠️ force create release`, GitHub: the *force* checkbox of the
+  `🚀 catladder create release` workflow)
+
+## The other direction: changesets → semantic-release
+
+Same shape, mirrored, with one loss to flag up front:
+
+1. **Pending changesets are not converted.** Their summaries would
+   simply vanish from the changelog. Either cut one last changesets
+   release first (draining `.changeset/`), or fold each summary into the
+   changelog by hand before removing the files. Tell the user which one
+   you are doing.
+2. Commits since the last tag must carry conventional messages for
+   semantic-release to see them — history cannot be rewritten after the
+   fact, so accept that the first semantic-release version may
+   under-report. Say so rather than silently releasing a patch.
+3. Set `method: "semantic-release"` (or drop the field — it is the
+   default), run `yarn catenv`, commit the regenerated files.
+4. Delete `.changeset/` including its `README.md`.
+5. From then on the version comes from commit messages again, and the
+   `🦋 changeset check` job disappears from MR pipelines.
+
+## Related skills
+
+- `catladder-releases` — how both methods work, the release jobs and the
+  security-audit gate
+- `catladder-config` — catladder.ts structure and regeneration
+- `catladder-migrate-ci-backend` — migrating between GitLab CI and
+  GitHub Actions

package/dist/skills/catladder-pipelines/SKILL.md

@@ -93,3 +93,5 @@ Useful CLI commands (see the `catladder-cli` skill for invocation):
 - `catladder-releases` — the `taggedRelease` flow and security-audit gate
 - `catladder-secrets` — env vars and secret management
 - `catladder-cli` — non-interactive CLI usage and command reference
+- `catladder-migrate-ci-backend` — moving between GitLab CI and GitHub
+  Actions (running both in parallel, then cutting over)

package/dist/skills/catladder-releases/SKILL.md

@@ -127,3 +127,6 @@ the `security` commands in the `catladder-cli` reference.
 - `catladder-config` — catladder.ts structure and regeneration
 - `catladder-pipelines` — the `taggedRelease` trigger and stage/prod deploys
 - `catladder-cli` — `project ci` and `security` commands
+- `catladder-migrate-release-method` — switching an existing project
+  between semantic-release and changesets (incl. backfilling changesets
+  for everything merged since the last release tag)

package/dist/skills/catladder-secrets/SKILL.md

@@ -107,3 +107,5 @@ suspecting anything else.
 - `catladder-deploys` — runtime deploy config
 - `catladder-pipelines` — how the generated pipelines work
 - `catladder-cli` — non-interactive CLI usage and command reference
+- `catladder-migrate-ci-backend` — moving between CI backends (the vault
+  is what blocks decommissioning the old one)

package/package.json

@@ -53,7 +53,7 @@
     }
   ],
   "license": "MIT",
-  "version": "0.0.0-next-ddc387fe",
+  "version": "0.0.0-next-d13ff46d",
   "scripts": {
     "lint": "eslint \"src/**/*.ts\"",
     "lint:fix": "eslint \"src/**/*.ts\" --fix",