---
name: migrations
description: "Use when upgrading the wcz-layout package to a newer major version. Each major ships only its own inbound guide, versions/migrate-v<N-1>-to-v<N>.md, delivered by installing it. One major per pass."
metadata:
  type: lifecycle
  library: wcz-layout
  disable-model-invocation: "true"
---

# Upgrading wcz-layout

## 1. Find the source major

```bash
node -p "require('wcz-layout/package.json').version"  # installed
npm view wcz-layout version                           # latest published
ls node_modules/wcz-layout/skills/migrations/versions/
```

`package.json` names the installed major, not the one `src/` is written against.
Open the guide on disk and grep `src/` for the symbols on its `from` side —
`requirePermission`, `authenticationMiddleware`, `DataGridPremium`,
`useNotification` and the rest of the left-hand columns.

- Hits → `src/` is on that guide's `from` major. Apply that guide now, install nothing.
- No hits → the source major is the installed one. Go to step 2.

## 2. One pass per major

For each major from source + 1 up to the latest, in order:

```bash
npm install wcz-layout@<major>
ls node_modules/wcz-layout/skills/migrations/versions/
```

Re-list after every install — it replaced `versions/` and this skill. Read the
whole `migrate-v<from>-to-v<major>.md` it delivered, and whatever that guide says
to read first, before editing anything. Then work through it top to bottom.

Never skip a major: only `@10` carries the v9→v10 guide, so v9 → v11 is two
passes — install 10, apply, verify, install 11, apply, verify.

## 3. Verify before the next pass

```bash
npx vp check --fix
```

Formats, lints and type-checks. Fix everything it leaves behind, then:

```bash
npx vp dev
```

The app must start and render. Stop the dev server, then start the next pass.
Done when no guide is left unapplied and the installed version is the latest.