# AGENTS.md: Dependency and framework upgrades

## Before
- Record the baseline: current versions, and test/lint/build results (`npm test`, etc.). Note pre-existing failures.
- Read the changelog and migration guide for every major version you cross. List the breaking changes that affect this codebase (search for the affected APIs with `rg`).

## Doing the upgrade
- One package (or one tightly coupled group, e.g. `react` + `react-dom` + `@types/react`) per step and per commit.
- Use the package manager, not manual edits: `pnpm up <pkg>@<version>`, `uv add <pkg>==<version>`, `go get <mod>@<version>`, `cargo update -p <crate>`. Commit the lockfile.
- Run official codemods where they exist (e.g. `npx @next/codemod`, `npx storybook upgrade`) and review their diff.
- Fix deprecations as you go; don't silence warnings.
- Don't jump multiple majors at once if the guide recommends stepping through each.

## Verify each step
- Install from clean, then typecheck, lint, tests, and build. Smoke-test the app's main flows.
- If something breaks and the fix is unclear, revert that step and report rather than piling on workarounds (patches, `--legacy-peer-deps`, `overrides`).

## Report
A table of package, from, to, breaking changes handled, and follow-ups. Flag anything requiring runtime/environment changes (Node/Python version, env vars, infrastructure).