Upgrade

sdxc upgrade

sdxc upgrade moves every @sdxc/* package your package.json lists to its version at the target release, and remix to the version that release declares. It installs, then prints a prompt for an AI agent with the release notes of the packages your code imports, so the agent edits the code for exactly the changes you crossed. Install and pin covers why a release is one exact date.

Pick the release

sdxc upgrade               # the latest release
sdxc upgrade 2026.10.14    # a release you name

The project's release is the newest date among its @sdxc pins. Each package moves to its newest version published on or before the target date, since a release republishes only the packages that changed. A target older than the project's release is refused: upgrade only moves forward. A package.json that lists no @sdxc/* package, or pins none to an exact release, is refused too.

Catch up lagging packages

The move includes packages pinned behind the release you are already on, so sdxc upgrade, or sdxc upgrade <your release>, catches them up even when no newer release is out. It reports "up to date" only when no pin would change:

The @sdxc packages are up to date at 2026.10.14

sdxc doctor points at the same fix when it finds a package behind.

Breaking changes

Before it changes package.json, upgrade lists the breaking changes between the two releases in the packages your code imports, and asks whether to go on. A no leaves package.json as it was. Without a terminal, or with no breaking change to list, it goes on without asking.

Then it writes each pin, prints every change on stderr, and installs with the project's package manager:

package.json: @sdxc/jwt 2026.9.1 -> 2026.10.14
package.json: @sdxc/result 2026.10.1 -> 2026.10.14
package.json: remix 3.0.0 -> 3.1.0

--no-install stops after package.json and prints the install command and the prompt command to run next. A failed install says the same, so you can fix it and carry on.

The prompt for your agent

Once installed, upgrade runs the new release of @sdxc/kit to write the prompt, so the notes come from the release you installed. Progress goes to stderr and only the prompt goes to stdout, so it pipes into your agent's command line or clipboard; --output upgrade.md writes it to a file instead.

The prompt is Markdown, in this order:

• What to do: apply each breaking change's migration, adopt the features and fixes, then verify.

• ## Remix, when remix moved, with a link to its release notes.

• ## Breaking changes, ## Features and ## Fixes: each note in full, for the packages the code imports only. Notes with nothing for a consumer to do, such as docs and tests, stay in the GitHub Releases.

• ## Older releases, linking the full notes of releases too old for the changelog the kit ships.

• ## Vendored components: copies made with sdxc ui add whose source changed since, with the ui diff and ui update commands for each.

• ## Verify: the project's own check, typecheck and test scripts, as your package manager runs them.

• ## Documentation: the reference page of each package the code imports.

The prompt covers each caught-up package from the version it was pinned to, and every other package from the project's release.

Write the prompt again

To write the prompt later, name the release you moved from. Pass --since <package>@<old version> once per package that lagged behind it, and --remix-from when remix moved:

sdxc upgrade --prompt --from 2026.10.14 --since @sdxc/jwt@2026.9.1

--prompt writes the prompt of the installed @sdxc/kit and refreshes the AGENTS.md section below, leaving package.json as it is. It takes --from and no release.

AGENTS.md

The same step rewrites the sdxc section of AGENTS.md, the lines between <!-- sdxc:start … --> and <!-- sdxc:end -->, from the new release's template, and keeps everything outside them as you wrote it. Move a rule you added inside the section below it, so the next upgrade keeps it. A project whose AGENTS.md has no section, or no AGENTS.md at all, keeps its file, and the prompt links the release's section for your agent to add.

A full upgrade

sdxc upgrade --output upgrade.md
# hand upgrade.md to your agent, let it edit and run the Verify commands
sdxc ui list
sdxc doctor

ui list shows the copies still behind, and doctor confirms every pin and install matches the new release before you commit.

Where to go next

• Check a project — find a package behind the release or an install that differs from package.json.

• Versioning — what a dated release number records.