upgrade-agent-native

# Upgrade Agent-Native ## Rule When an older Agent-Native app/branch needs to run on current packages, use `agent-native upgrade`. Never "fix" upgrade breakage with `pnpm patch`, `pnpm patch-commit`, `pnpm.patchedDependencies`, `pnpm.overrides`, `patchedDependencies`, `resolutions`, local patch artifacts, or edits under `node_modules/@agent-native/*` — especially not against `@agent-native/core` or `@agent-native/dispatch`. ## Why Agents often respond to a failed core bump by inventing framework patches and dispatch behavior overrides. That hides the real app-level break, drifts from upstream, and makes the next upgrade worse. The supported path is bump → install → refresh scaffold skills → verify, then fix **app** code only. ## How For the Core 0.198.0 package and import migration, follow the [Core 0.198.0 upgrade runbook](../../../packages/core/docs/content/upgrading-core-ui.mdx). It covers the preview and apply commands, Toolkit and optional peer packages, codemod limits, and a symbol-level path map. 1. **Preview migration codemods first** ```bash npx @agent-native/core@0.198.0 upgrade --codemods --dry-run ``` `--dry-run` previews the diff without writing. Do not manually edit imports before applying the codemod; the migration manifest is the source of truth for renamed specifiers and symbols. 2. **Apply the reviewed upgrade and codemods** ```bash npx @agent-native/core@0.198.0 upgrade --codemods ``` Use the versioned CLI while the app still has Core 0.196 or another older Core version: its local CLI carries an older migration manifest. After Core 0.198.0 is installed, `npx agent-native upgrade --codemods` (or `pnpm exec agent-native upgrade --codemods` from an already-installed CLI) uses the matching manifest. Either invocation applies supported codemods and runs the upgrade, including dependency installation, scaffold skill refresh, and typecheck when available. Do not run a second upgrade command just to apply the codemods. Afterward, run `npx agent-native doctor` from the app root. Its default `migration-manifest` and `feature-dependencies` checks report stale imports and missing optional peers detected from local settings. Confirm remote deployment settings separately because Doctor cannot inspect them. What it does: - Blocks (unless `--force`) when `@agent-native/*` overrides/patches exist - Rewrites non-local `@agent-native/*` dependency pins to `latest` - Runs the package manager install - Rewrites those pins to the exact versions the install resolved, so the committed manifest names one release instead of re-resolving next install - Runs `skills update scaffold --project` - Runs `typecheck` when the project has that script 3. **Pull upstream template changes (optional, separate from the bump)** `agent-native upgrade` moves package versions. It never touches files that were copied out of a template at scaffold time, so template fixes and improvements do not arrive with a bump. ```bash agent-native template status # recorded ref vs latest, drift counts agent-native template diff # what upstream changed, read-only agent-native template sync # 3-way merge it into the app ``` `sync` defaults to the ref matching the installed `@agent-native/core`, so run it after `upgrade`. It merges per file against a pristine baseline stored in `refs/agent-native/template-baseline/<app-path>`; files upstream did not touch are left alone, and real collisions get conflict markers. After resolving markers, run `agent-native template accept` — the baseline deliberately does not advance past an unresolved merge. Apps scaffolded before provenance existed have no baseline. Create one with `agent-native template baseline` before the first sync. 4. **If upgrade or typecheck fails** - Read the concrete error - Fix **app** source, actions, config, or env — not framework packages - Re-run `agent-native upgrade` or `pnpm typecheck` - Stop and ask the user if you cannot fix the app-level error Intentional app-level UI customization is a separate workflow. Read `customizing-agent-native` when the product needs to own a selectively copied component; do not use that path to reproduce framework runtime behavior or hide version skew. 5. **Dry-run / partial runs** ```bash agent-native upgrade --dry-run agent-native upgrade --skip-verify agent-native upgrade --skip-install # package.json bumps only agent-native doctor --only migration-manifest ``` `migration-manifest` has no opt-out. Run it in CI before upgrading to find imports that will break, then use `npx @agent-native/core@latest upgrade --codemods` to preview the supported rewrite. ## Don't - Don't add `pnpm.overrides`, `overrides`, `resolutions`, or `patchedDependencies` for any `@agent-native/*` package - Don't run `pnpm patch` or `pnpm patch-commit`, or commit files under `patches/`, for any dependency - Don't edit `node_modules/@agent-native/core` or `node_modules/@agent-native/dispatch` - Don't invent local "dispatch behavior" shims to paper over version skew - Don't keep iterating with more framework patches after a failed install - Don't skip `skills update scaffold --project` after a core bump (the upgrade command does this for you) ## Related Skills - **self-modifying-code** — Tier 4: framework packages are off limits - **agent-native-docs** — version-matched docs after the bump - **customizing-agent-native** — intentional app-owned UI copies, not upgrade patches - **portability** — keep app code provider-agnostic across upgrades