> [Agent navigation index](/llms.txt)

# Dependency and Brix upgrades

Review complete dependency release histories, apply exact transactional updates, and upgrade Brix only after inspecting its canonical plan.

Start with a dry run. It is safe on a dirty tree and gives you the exact target plus release evidence.
Applying a Brix upgrade is different: commit all work first, use the reviewed exact version, inspect
the migration diff, and run verification separately after the transaction.

## Review dependency upgrades

Ask the project-pinned package engine to resolve exact candidates and collect every intervening release:

```sh
brix deps update --latest --dry-run --json
brix deps update date-fns --latest --dry-run --json
brix deps update --latest --minimum-release-age 1d --dry-run --json

```

The JSON plan has `schemaVersion: 2`, `kind: "dependency-upgrade-plan"`, and one entry for each changed direct dependency/version pair. Each entry identifies owning projects and includes chronological release history after the installed version through the target. Reject an unknown schema version.

The preview reads registry settings the way the package engine does: the user `.npmrc`
(`NPM_CONFIG_USERCONFIG`, or `~/.npmrc`), then the workspace and project `.npmrc`. Scoped
`@scope:registry` entries select each package's registry, and `//host/path/:_authToken` credentials
are sent only to URLs under that prefix. `--registry` overrides only the default registry.
`NODE_AUTH_TOKEN` and `NPM_TOKEN` are not sent on their own; reference them from `.npmrc`, for
example `//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}`. Packaged changelogs are read only
from tarballs served by the registry that published the metadata, and at most 20 MiB of each is
downloaded. Human-readable output removes terminal control and bidirectional formatting characters
from third-party release notes; JSON output keeps the original text, escaped.

A registry range such as `^4.0.0` that is saved as an exact release is reported from the version
installed before the update. At a workspace root, `brix deps update` covers the root and every
member, so shared catalog entries are reviewed together; select one member with `deps#<member>`.

Brix prefers changelog files shipped by the package, then matching GitHub releases. Preserve the source URL, publication time, and original notes when reviewing. `source: "unavailable"` means lookup completed without publisher notes; `source: "lookup-failed"` includes a provider failure and possible retry time. Neither should be silently omitted or replaced with invented changes.

Review breaking changes, deprecations, runtime and peer requirements, and the project's actual imports. Separate required migration edits from optional feature adoption.

## Apply dependency upgrades

Run the exact arguments you reviewed:

```sh
brix deps update date-fns --latest --dry-run --json
brix deps update date-fns --latest
brix verify

```

Brix updates exact versions and workspace catalogs transactionally. A direct exact peer used for testing is synchronized; in a workspace it becomes the same catalog reference as the installed dependency. Broad or peer-only declarations remain. Framework-owned runtime packages cannot be upgraded independently in a consumer application—upgrade Brix instead. Never edit dependency versions or run a package manager directly.

`brix deps add` checks the resulting manifests, so a Git, tarball, file, or alias specifier cannot
introduce a framework-owned package either; the transaction is restored instead. `@brix/react`
cannot be added or removed, and `brix` cannot be removed, with `brix deps`; use `brix upgrade` or
`brix workspace integrate react`.

Bulk and wildcard updates leave framework-owned declarations at their pinned versions. In a managed
project, `brix deps update --latest` and patterns such as `brix deps update "@types/*" --latest`
pass every other matching installed dependency to the package engine by name and report the
Brix-owned packages they kept for `brix upgrade`. When nothing outside Brix ownership matches, the
update reports that dependencies are current. A plain `--filter <package>` or `--filter ./<path>`
limits that selection to the filtered projects; graph, glob, and exclusion filters consider every
project's declarations. Naming a framework-owned package explicitly still
fails. External workspace applications may update the React, Vite, and other dependencies they own
directly; their Brix core and integrated React adapter still move through `brix upgrade`.

Projects keep pnpm's `minimumReleaseAge` cooldown at 1440 minutes (one day) or longer. A longer
cooldown is kept; a shorter one is reported by `brix doctor` and raised by `brix init`.
`minimumReleaseAgeExclude` may hold your own entries; Brix manages only exact `name@version`
exemptions for the oxlint, oxfmt, Vitest, and Panda versions this Brix release pins. `brix init`,
`brix create`, and `brix upgrade` replace that managed subset, and doctor rejects broad or stale
exemptions for those toolchains. Leaving the managed exemptions out only makes the cooldown stricter.

Dependency updates reject `--no-save`: unchanged declarations can hide Git-to-registry replacements in the lockfile. Use `--dry-run` for a preview that restores the prior project state. Default and named catalog references remain intact, and failed transactions restore manifests, catalogs, the lockfile, and installed state.

## Upgrade Brix

Ask the target Brix CLI for its canonical project or workspace plan:

```sh
brix upgrade --dry-run --json
brix upgrade --version next --dry-run --json

```

For a stable project, the command without a selector follows the stable channel. The explicit `next` example is the optional prerelease workflow.

The JSON plan has `schemaVersion: 1` and `kind: "upgrade-plan"`; reject unknown schema versions in automation. It combines the release notes of every Brix release after the installed version through the target and lists project-relative actions. Releases are ordered by SemVer from the target's changelog: stable releases plus releases on the target's prerelease channel. When the installed version is a preview, superseded `next`, or maintenance release absent from that changelog, `data.fromListed` is `false`. `data.direction` is `upgrade`, `reconcile`, or `downgrade`; an explicit older `--version` produces an empty release list, so review the newer installed changes yourself. `--json` requires `--dry-run`. Review application usages and distinguish:

- canonical edits Brix will apply
- manual semantic migration in application code
- optional features that should not be enabled without an explicit decision

Apply the same target only after review:

```sh
brix upgrade --version 'v<reviewed-version>'

```

Replace `<reviewed-version>` with the exact target shown by the plan, for example a stable SemVer
or canonical `next.N` version. Reusing only `stable` or `next` may resolve a newer release if one was
published after your review. A project already pinned to `next` follows that channel; preview and
other exact prereleases remain frozen until you select another target explicitly.

`brix upgrade` updates the global CLI and the current project or workspace pin together;
`brix launcher update` changes only the global CLI. The `--version` of an upgrade selects the
release for that operation only: it does not freeze the global CLI at the reviewed tag, and later
`create`, `init`, and `brix launcher update` runs follow the launcher's persisted selection. Use
`brix launcher update --version <selector>` to change that selection. A real project or workspace upgrade requires a
committed, clean Git working tree with no untracked files; ignored files are allowed. Brix checks
this before updating the global CLI. Dry runs remain
available with a dirty worktree or outside Git.

The upgrade reconciles canonical configuration and exact dependencies, installs through Brix, and
refreshes project-pinned skills. In a workspace, the shared catalog entries for every package the
target release pins (`brix`, the root's oxfmt, oxlint, oxlint-tsgolint, and Varlock, React and its
types for React members, Contentful packages for Contentful apps, and Storybook packages where
Storybook is integrated) move to the target versions, so members that reference them with
`catalog:` follow the release. `brix doctor` resolves those catalog references and reports a stale
entry with `brix upgrade` as the repair. The workspace upgrade also moves inline registry versions
in any member, including external projects, into the default catalog, as `brix doctor` requires.
Changing a declaration to `catalog:` makes the package engine resolve that dependency again, so its
lockfile entries and peer variants can change even when its version does not. `brix upgrade --dry-run`
lists each `catalog <name>@<version>` addition and each member manifest it updates. Installation or migration failure restores managed state across the
standalone project or complete workspace. It does not run lint, tests, builds, or `brix verify`.
After success, review the migration diff, apply required code migrations, then run `brix verify`
separately; a verification failure cannot undo the completed upgrade. Same-version project commands
still reconcile managed state, and progress describes a reconcile rather than a version upgrade.

## Complete a framework migration

A successful upgrade transaction updates canonical configuration, exact dependencies, and
project-pinned skills. It does not rewrite components, custom mocks, generated sources, or
application semantics. The release notes included in the upgrade plan are the migration checklist:
for every release in the range, classify each breaking entry as applicable or not applicable to
each workspace member and shared library before changing code.

Move framework-owned packages such as Preact, MSW, Panda, Vite, Vitest, Playwright, Storybook, and
an integrated `@brix/react` only through `brix upgrade`. Never install them independently to
resolve a migration error. Breaking releases may remove or rename public exports without
compatibility aliases; `brix check` reports each affected import, and the release notes name its
replacement.

When an agent performs the migration, ask it to load the project-pinned `brix-upgrading-projects`
skill and follow any release-specific procedure it references. Require a report of applicable
usages, automatic changes, manual changes, blockers, and executed checks for every member.

### Regenerate managed output

Regenerate output whose generator changed rather than editing it by hand:

- Run `brix env types` and commit `src/env.generated.d.ts`. Generation is provider-free; do not
  fetch production secrets to finish an offline migration.
- When the managed MSW version changes, run `brix msw init public --save` from each owning
  application with its existing public directory, review the worker diff, and keep the worker out
  of production entries.
- Rerun existing `brix openapi generate` workflows and review the generated schemas and types.
  Update callers whose inferred types change; do not loosen generated schemas to silence errors.
- When Panda changes, rebuild design-system libraries in dependency order (base, brand, then
  applications and catalogs) before verifying styles. See
  [design-system composition](/docs/styling-components.md#extend-base-brand-app).
- Run `brix release init` so generated release and promotion workflows reference the new version;
  see [publishing releases](/docs/releases-publishing.md#configure-project-releases).

### Review behavior that tooling cannot migrate

Runtime and test-library upgrades change behavior that type checking cannot see. Exercise
hydration, portals, ref attachment, effect cleanup, and mount/unmount transitions in browser tests,
not only the initial render. Recheck HTTP mocks and fake timers, browser snapshot baselines, and the
runtime's supported browsers against your product policy. When a release tightens a security
default, such as stricter static-path decoding, rename or adapt the affected input instead of
weakening the default globally; any exception needs security review and a regression test.

Optional upstream capabilities that arrive with a dependency update are not automatically
supported Brix features. Adopt them only through an explicit decision and Brix's supported facades,
and do not cite upstream performance notes as measured improvements for your application.

### Verify the migration

Run `brix check`, focused Node, browser, and type tests for affected code, then `brix verify`,
including configured Storybook catalogs and production hydration or interaction checks. Record
not-applicable items for members without the affected features. Unsupported imports, browser-policy
conflicts, and untested lifecycle changes remain explicit blockers rather than silent omissions.

## Recover from a failed update

Transactions and restored dependency previews normalize stable symlinked parents, but reject
symlink-managed roots and unsupported nested links before mutation. Ordinary package links inside `node_modules`
and generated skill links remain supported. Do not change managed paths concurrently.

Ctrl-C or `SIGTERM` during an update is deferred until the transaction restores the previous
manifests, lockfile, and installed state; Brix then exits by that signal. Repeated deliveries of
the same signal are ignored so they cannot interrupt rollback. Installed dependencies are not
copied: when `node_modules` changed, rollback reinstalls the restored lockfile with
`--frozen-lockfile`. A failed reinstall is reported as an incomplete rollback; the restored
manifests and lockfile stay in place, so run `brix install` after fixing its cause. A dry run
restores its snapshot once, the same way, when the preview itself succeeded.

On POSIX, cancelling a package-engine step signals its process group. Once the group leader exits,
remaining members are sent SIGKILL after 500 ms, followed by a bounded 50 ms scheduling grace.
This is best effort, not proof that writers have stopped before rollback. Detached processes in
other groups are not covered. Windows signals only the
direct child; stop remaining install processes before recovery or retrying.

Treat installation/migration failure separately from a later test failure. The former attempts to
restore managed project files and installed state. The latter happens after a successful upgrade:
fix the application migration or deliberately restore your previous committed project state and
run `brix install`. Do not assume that a failed `brix verify` rolled the upgrade back.

The global CLI update is independent and can remain updated after project rollback. Normal project
commands still use the project's pin; use `brix launcher rollback` only when you also intend to
restore the previous global CLI. After a launcher rollback, `create` and `init` stop refreshing the
global CLI automatically until `brix launcher update`, `brix upgrade`, or an explicit
`create --version` selects a release again. If rollback itself is incomplete, preserve the reported backups
and private diagnostic log before retrying. Review logs for secrets before sharing them.

Rollback attempts every snapshotted path even if an earlier restoration fails. An incomplete
rollback reports the failed paths and retains backups of the paths it could not restore, with their
location; successfully restored paths do not make the overall transaction successful.

For publishing the upgraded project, continue to [project releases](/docs/releases-publishing.md);
an upgrade changes the local project and does not publish a release.
