> [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.

## 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.

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; 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.

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 plan combines all Brix releases after the installed version through the target and lists project-relative actions. 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

```

The upgrade reconciles canonical files and exact dependencies, installs through Brix, refreshes project-pinned skills, and runs `brix verify`. A failed install or verification restores managed state across the standalone project or complete workspace. Review the resulting diff anyway; transactional does not mean application semantics can be inferred automatically.