@catladder/cli 0.0.0-main-8dbb6c76 → 0.0.0-main-a6b45abe

package/dist/bundles/skills/catladder-migrate-package-manager/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: catladder-migrate-package-manager
+description: Migrating a catladder project's node package manager — yarn → pnpm (via `pnpm import`, keeping the resolved versions) or pnpm → yarn — including the workspace file, the yarn-isms in scripts and catladder.ts, phantom dependencies, and what changes in the generated pipeline. Use when a project should switch package managers, when `pnpm import` is mentioned, or when a pnpm migration breaks builds or docker images. Triggers on "migrate to pnpm", "switch to pnpm", "yarn to pnpm", "use pnpm instead of yarn", "pnpm import", "back to yarn", "change package manager", "pnpm-workspace.yaml", "phantom dependency", "frozen-lockfile fails".
+---
+
+# Migrating the package manager (yarn ↔ pnpm)
+
+catladder supports **yarn** (classic and berry) and **pnpm** for the
+node build family, and autodetects which one a project uses. So the
+catladder side of this migration is nearly free — the work is in the
+repository: lockfile, workspace file, scripts, and the dependencies
+that only ever resolved because yarn hoisted them.
+
+Typical motivation: pnpm is substantially faster in CI (a real project
+saw lint 584s → 187s, app build 470s → 228s, docker builds 2–3× faster
+on warm caches).
+
+**Do this on a branch and expect several iterations.** The first
+pipeline will not be green. Plan for it instead of promising a one-shot
+migration.
+
+## What catladder detects, and what it generates
+
+Detection order (`packageManager` in `catladder.ts` → `packageManager`
+field in package.json → lockfile → yarn fallback):
+
+```ts
+// catladder.ts — only needed to override the detection
+packageManager: "pnpm",
+```
+
+Prefer the `packageManager` field in the root `package.json`
+(`"packageManager": "pnpm@11.6.0"`) — it drives local dev, corepack and
+catladder at once, and catladder installs *that* version in the docker
+build. Corepack's `+sha512…` integrity suffix is fine; catladder strips
+it before using the version as an npm spec.
+
+Once detected, catladder switches all of this automatically — no config
+change needed:
+
+| | yarn | pnpm |
+|---|---|---|
+| CI install | `yarn install --immutable` | `pnpm install --frozen-lockfile` |
+| download cache | `.yarn` zip cache | **none** — installing from the registry is cheaper than moving the store |
+| node_modules cache | mutable slot per build dir | **none** (measured: the archive costs more than the install it saves) |
+| docker prod install | `yarn workspaces focus --production` | `pnpm install --prod --frozen-lockfile --filter <pkg>...` |
+| audit job | `yarn npm audit … --all --recursive` | `pnpm audit --prod --audit-level critical` |
+| build/start defaults | `yarn build` / `yarn start` | `pnpm build` / `pnpm start` |
+
+The audit job is the one place where the two are not equivalent in
+practice: it is easy to have a yarn pipeline whose audit checked nothing
+(before catladder 5 the generated command lacked `--all --recursive`), so
+the pnpm job can turn up long-standing vulnerabilities. Read them as
+pre-existing, not as caused by the migration.
+
+Because the cache keys differ per package manager, the first pnpm
+pipeline runs **cold** (and rebuilds job images). Judge speed on the
+second run, not the first.
+
+## Step 0 — check the blockers
+
+- **node version** — pnpm 11 requires **node ≥ 22.13**, pnpm 10 only
+  ≥ 18.12. Check `.nvmrc` (and any explicit node version in job images):
+  the jobs switch with nvm, so an `.nvmrc` of `20` downgrades a node-22
+  image and pnpm 11 dies mid-install with
+  `ERR_UNKNOWN_BUILTIN_MODULE: No such built-in module: node:sqlite`.
+  Either bump `.nvmrc` to 22 in the same change, or pin
+  `"packageManager": "pnpm@10.x"`.
+- **`build: { type: "meteor" }`** — yarn-only in catladder; generation
+  fails outright. That component blocks the migration.
+- **Yarn PnP** (`nodeLinker: pnp`, `.pnp.cjs`) — the migration is bigger
+  than a lockfile swap: everything that relied on PnP resolution changes.
+  Say so before starting.
+- **Yarn plugins** (`.yarn/plugins`, `yarn workspaces focus`,
+  `yarn-plugin-*`) — no pnpm equivalent; each needs a decision.
+- **catladder version** — pnpm support landed in catladder 5. On an
+  older version, upgrade first.
+- **`docker: { yarnRebuildEnabled }`** in a build config — yarn-only;
+  it is silently ignored under pnpm. Remove it as cleanup.
+
+## Step 1 — inventory the yarn-isms
+
+Grep the repo, not just `catladder.ts`. Every one of these needs a
+decision *before* the lockfile changes:
+
+```bash
+grep -rn "yarn " --include=package.json --include="*.ts" --include="*.md" --include="*.yml" --include="*.yaml" --include=Dockerfile* .
+```
+
+Look at: package.json `scripts`, `catladder.ts`
+(`buildCommand`, `startCommand`, `postInstall`, `lint`/`test`/`audit`
+`command`, deploy `command`/`script`, `customJobs`), Dockerfiles,
+husky hooks, `lint-staged`, `.github/`-adjacent tooling, and the README.
+
+The mapping table is in
+[references/yarn-to-pnpm-differences.md](references/yarn-to-pnpm-differences.md)
+— read it before rewriting scripts; several of the entries there
+(root-script fallback, shell globs, the `pnpm run` banner) have caused
+silent, hard-to-debug breakage in production images.
+
+## Step 2 — write `pnpm-workspace.yaml` first
+
+`pnpm import` **requires the workspace file to exist already**, or it
+generates a lockfile for the root package only.
+
+Translate, in one file:
+
+```yaml
+packages: # from package.json "workspaces"
+  - "packages/*"
+  - "apps/*"
+
+overrides: # from package.json "resolutions"
+  some-pkg: 1.2.3
+
+patchedDependencies: # from yarn's .yarn/patches + resolutions patch: entries
+  some-pkg@1.2.3: patches/some-pkg.patch
+
+allowBuilds: # deps whose install scripts may run (see step 4)
+  esbuild: true
+  prisma: true
+
+minimumReleaseAge: 0 # pnpm 11 defaults to 1440 (min); 0 keeps yarn's behavior
+```
+
+On **pnpm 11+ nearly all settings live in `pnpm-workspace.yaml` only** —
+`pnpm.overrides` in package.json and non-auth settings in `.npmrc` are
+ignored (pnpm 10 read them; this reversal silently drops overrides).
+`.npmrc` keeps auth and registry settings.
+
+The yarn patches themselves (`.yarn/patches/*.patch`) can be reused as
+files; move them somewhere neutral (`patches/`) and reference them from
+`patchedDependencies`.
+
+## Step 3 — import the lockfile
+
+```bash
+pnpm import          # yarn.lock -> pnpm-lock.yaml, keeping resolved versions
+rm -rf yarn.lock node_modules **/node_modules .yarn/cache .yarn/install-state.gz
+pnpm install
+```
+
+`pnpm import` is what keeps this migration honest: it preserves the
+versions yarn had resolved instead of re-resolving every range. Do not
+skip it and run a bare `pnpm install` — that silently upgrades hundreds
+of transitive dependencies at the same time as the package manager
+changes, and you will not know which change broke what.
+
+Then set the `packageManager` field, and update `.gitignore`: `.yarn/*`
+entries out (keep `.yarn/patches` only if you left the patches there).
+Nothing pnpm-specific needs ignoring — the store lives outside the repo.
+
+## Step 4 — fix the fallout locally
+
+Work through these *before* touching CI; every one of them fails the
+same way in the pipeline, only slower.
+
+1. **Phantom dependencies** — pnpm does not hoist. Every package your
+   code imports must be in *its own* `package.json`. This is the single
+   biggest source of failures, and the nastiest ones surface only in the
+   docker image (a bundler happily resolved the hoisted copy at build
+   time; the prod install does not ship it). Fix by declaring, never by
+   `shamefully-hoist`.
+2. **Install scripts are not run** unless approved. `pnpm install`
+   prints the list it skipped → add them to `allowBuilds`
+   (pnpm 11; `onlyBuiltDependencies` list on pnpm 10). Missing prisma,
+   esbuild, sharp, playwright, husky, … show up as "works locally,
+   fails in the image".
+3. **Root `prepare` runs in the production install** (docker), where
+   devDependencies are absent: `"prepare": "husky || true"`.
+4. **Quote your globs.** yarn berry's built-in shell expands `**`;
+   pnpm's `sh` does not. `node build.mjs ./entrypoints/**/*.ts` silently
+   builds fewer files → a container that boots without its entrypoint.
+   Quote the pattern and let the tool expand it.
+5. **`pnpm run` prints a banner to stdout** — any script whose output is
+   piped needs `pnpm --silent run …`.
+6. **No root-script fallback**: yarn berry falls back to the root
+   package's scripts, pnpm does not. Inline shared scripts into each
+   workspace (the root `node_modules/.bin` *is* on the script PATH).
+
+Then, still locally: full build, typecheck, lint and test — and
+`docker build` at least one generated Dockerfile and boot the image.
+That catches phantom dependencies far faster than a pipeline round-trip.
+
+## Step 5 — regenerate the pipeline
+
+Nothing in `catladder.ts` needs to change beyond the yarn-isms from
+step 1 (and, optionally, an explicit `packageManager: "pnpm"`).
+
+```bash
+pnpm catenv
+```
+
+Commit the regenerated `.catladder-generated/`, `.gitlab-ci.yml` and
+`.github/workflows/catladder-*` with the rest — see `catladder-config`.
+
+Review the diff: install commands, cache keys/paths, the default
+build/lint/test commands and the docker install lines should have
+flipped to pnpm everywhere. Anything still saying `yarn` is a command
+you spelled out yourself in `catladder.ts` (step 1), not a default.
+
+## Step 6 — verify in CI
+
+- The first pipeline is cold and rebuilds job images — slow by design.
+- Expect the failures to arrive **in waves**: install → build → docker →
+  deploy. A green build job says nothing about the images.
+- If a docker job fails on `--frozen-lockfile`, the cause is almost
+  always a file missing from the build context (a workspace manifest, a
+  patch file) or a lockfile that was not regenerated after a
+  package.json edit.
+- Deploy at least one component to a review/dev environment and check it
+  actually boots — bundlers hide missing dependencies until runtime.
+- Compare timings against the **second** run.
+
+## Step 7 — hand over to the team
+
+Tell the user what changes for everyone:
+
+- `yarn <x>` → `pnpm <x>`; `yarn workspace a b` → `pnpm --filter a b`;
+  `yarn dlx` → `pnpm dlx`. The CLIs become `pnpm catenv` / `pnpm catladder`.
+- new dependencies must be declared where they are imported — the
+  hoisting safety net is gone
+- a dependency with an install script needs an `allowBuilds` entry
+- update the README / contributing docs and any developer onboarding
+  script in the same MR
+
+## The other direction: pnpm → yarn
+
+Mirrored, with one loss to state up front: **there is no importer back**.
+`yarn import` only reads npm lockfiles, so yarn berry has to re-resolve
+every range — the migration necessarily bumps transitive versions.
+Do it deliberately:
+
+1. Delete `pnpm-lock.yaml`, `pnpm-workspace.yaml`, and the `node_modules`
+   trees.
+2. Move `packages:` back into package.json `workspaces`, `overrides` →
+   `resolutions`, `patchedDependencies` → yarn's patch protocol,
+   `allowBuilds` → (yarn runs build scripts by default; nothing needed).
+3. `yarn install`, then re-run the whole local verification of step 4 —
+   the version drift is the risk here, not the tooling.
+4. Set `packageManager: "yarn@x.y.z"`, drop `packageManager: "pnpm"`
+   from `catladder.ts` if it was set, run `yarn catenv`, commit the
+   regenerated files.
+
+## Related skills
+
+- `catladder-builds` — the `build` config, pnpm gotchas per build type,
+  workspace builds
+- `catladder-config` — catladder.ts structure, `packageManager`,
+  regeneration
+- `catladder-pipelines` — caching, job images, debugging CI
+- `catladder-migrate-ci-backend` — moving between GitLab CI and GitHub
+  Actions
+- `catladder-migrate-release-method` — switching between
+  semantic-release and changesets

package/dist/bundles/skills/catladder-migrate-package-manager/references/yarn-to-pnpm-differences.md

@@ -0,0 +1,135 @@
+# yarn → pnpm: what actually differs
+
+Companion to the `catladder-migrate-package-manager` skill. Everything
+here has bitten a real catladder project during a migration.
+
+## Command mapping
+
+| yarn | pnpm |
+|---|---|
+| `yarn` / `yarn install` | `pnpm install` |
+| `yarn install --immutable` (`--frozen-lockfile` classic) | `pnpm install --frozen-lockfile` |
+| `yarn add x` / `yarn add -D x` | `pnpm add x` / `pnpm add -D x` |
+| `yarn remove x` | `pnpm remove x` |
+| `yarn up x` (berry) | `pnpm update x` |
+| `yarn <script>` | `pnpm <script>` (or `pnpm run <script>`) |
+| `yarn workspace pkg <script>` | `pnpm --filter pkg <script>` |
+| `yarn workspaces foreach …` | `pnpm -r <script>` |
+| `yarn workspaces focus --production` | `pnpm install --prod --filter pkg...` |
+| `yarn run -T x` / `yarn -T x` (berry top-level) | `x` (root `node_modules/.bin` is on the script PATH) |
+| `yarn dlx x` | `pnpm dlx x` |
+| `yarn node x` / `yarn exec x` | `pnpm exec x` |
+| `yarn npm audit --environment production --all --recursive` | `pnpm audit --prod` |
+| `yarn bin x` | `pnpm bin x` |
+
+## Configuration mapping
+
+| yarn | pnpm |
+|---|---|
+| package.json `workspaces` | `packages:` in `pnpm-workspace.yaml` |
+| package.json `resolutions` | `overrides:` in `pnpm-workspace.yaml` |
+| `.yarn/patches/*` + `patch:` resolutions | `patchedDependencies:` in `pnpm-workspace.yaml` |
+| `.yarnrc.yml` settings | `pnpm-workspace.yaml` (auth/registry stay in `.npmrc`) |
+| `.yarnrc.yml` `npmScopes` / auth | `.npmrc` |
+| `catalog:` / `catalogs:` in `.yarnrc.yml` | `catalog:` / `catalogs:` in `pnpm-workspace.yaml` |
+| (yarn runs install scripts by default) | `allowBuilds:` map — pnpm 11; `onlyBuiltDependencies:` list on pnpm 10 |
+| `.yarn/cache` (zip cache) | the content-addressable store (catladder points it at a project-local `.pnpm-store`) |
+
+**pnpm 11 reads settings from `pnpm-workspace.yaml` only.** A
+`pnpm` section in package.json (`pnpm.overrides`,
+`pnpm.patchedDependencies`) works on pnpm 10 and is *silently ignored*
+on 11 — the opposite of what most migration guides written for pnpm 10
+say. `.npmrc` keeps auth/registry settings and nothing else.
+
+## Behavioral differences that break things
+
+**No hoisting → phantom dependencies.** yarn flattens
+`node_modules`, so a package you never declared is importable anyway.
+pnpm's symlinked layout does not. Every undeclared import fails —
+sometimes only inside the production docker image, where the bundler is
+no longer there to paper over it. The fix is always to declare the
+dependency; `shamefully-hoist` only postpones the failure.
+
+**Install scripts are opt-in.** `pnpm install` skips dependency build
+scripts and prints the list. Anything with a native build or a
+generator step (prisma, esbuild, sharp, playwright, husky, …) needs an
+`allowBuilds` entry, or it is missing at runtime.
+
+**The root `prepare` script runs during `--prod` installs.** In the
+docker image, devDependencies are gone: `"prepare": "husky"` fails the
+build. Use `"prepare": "husky || true"`.
+
+**`pnpm run` writes a banner to stdout.** yarn does not. Any script
+whose output is piped or captured (`pnpm build:x > out.json`, generated
+supergraph schemas, …) must use `pnpm --silent run …`.
+
+**Scripts run in `sh`, not yarn's built-in shell.** yarn berry ships a
+POSIX-ish shell that expands `**` recursively; `sh` does not. An
+unquoted `./src/**/*.ts` silently matches *fewer* files. Quote the
+pattern and let the receiving tool expand it. This is the failure mode
+that ships a container missing half its entrypoints and still boots the
+build job green.
+
+**No root-script fallback.** yarn berry falls back to the root
+package's scripts when a workspace has none; pnpm errors. Inline shared
+scripts into each workspace, or add a thin per-workspace wrapper.
+
+**`--frozen-lockfile` verifies every importer.** pnpm checks that every
+workspace listed in the lockfile exists on disk, and that every
+`patchedDependencies` patch file is present with the right hash — which
+is why catladder copies all workspace manifests and all patch files into
+the docker build context.
+
+**Version drift in `--prod` installs.** `pnpm install --prod` on a
+node_modules tree from a *different* lockfile does not prune orphaned
+`.pnpm` directories — never reuse one branch's node_modules for another
+lockfile, and never a yarn tree for a pnpm branch.
+
+**Nothing is cached.** A yarn pipeline caches its zip cache and
+node_modules; a pnpm pipeline caches neither, and does not copy a store
+into docker images either. pnpm installs a 3800-package monorepo from
+the registry in 30-40s, which is less than it costs to move a 1 GB
+store or a 1.3 GB node_modules tree through a CI cache — measured
+side-by-side, caching made jobs about twice as slow on gitlab. Two
+consequences when migrating: CI pulls more from the registry than the
+yarn setup did (worth a registry proxy if that matters to you), and
+`.pnpm-store` should not appear anywhere in the repo or a build
+context.
+
+**Docker images must not carry the store.** If a store is copied into
+an image, it lands in a layer below `node_modules`, pnpm cannot hardlink
+across the overlay boundary, and every package is copied instead — the
+install gets *slower* (28s vs 10s from the registry) and the image
+carries the packages twice. Let the `--prod` install download, into a
+store outside the app directory that the same `RUN` layer deletes.
+
+**pnpm 11 needs node ≥ 22.13** (pnpm 10: ≥ 18.12), and it does not fail
+politely: it prints a `warn:` line and then crashes on
+`No such built-in module: node:sqlite`. In CI this bites even when the
+job image ships node 22 — the jobs run `nvm install` from `.nvmrc`, so
+an `.nvmrc` of `20` downgrades the image right before the install.
+
+**`pnpm audit` needs no scope flags.** It audits every workspace and the
+whole transitive tree by default, which is what `yarn npm audit` only does
+with `--all --recursive` (without them it checks the current workspace's
+*direct* dependencies — in a monorepo root that is usually nothing at all).
+Expect the pnpm audit job to surface vulnerabilities the yarn one never
+reported. In return `--prod` is stricter than yarn's
+`--environment production`: yarn still reports a devDependency of a
+workspace, pnpm does not.
+
+**`minimumReleaseAge`** defaults to 1440 minutes on pnpm 11: freshly
+published versions are refused. Set it to `0` while migrating (it is a
+supply-chain feature worth enabling deliberately later, not something to
+discover mid-migration).
+
+## catladder-specific notes
+
+- The `packageManager` field feeds the pnpm version installed in the
+  docker build; corepack's `+sha512…` integrity suffix is stripped.
+- `build: { type: "meteor" }` is yarn-only in catladder and fails
+  generation under pnpm.
+- `docker: { yarnRebuildEnabled }` applies to yarn berry only.
+- The job image ships pnpm; custom `jobImage`s and custom
+  `dockerfileContent` images get a `npm install -g pnpm@<version>`
+  fallback injected, so they work too — but they pay for it on every job.

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

@@ -0,0 +1,234 @@
+---
+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
+- `catladder-migrate-package-manager` — migrating between yarn and pnpm