# Upgrade every debuff package in one command

From 0.21, `npx debuff upgrade` moves a project to the latest debuff in one step. It sets every `@debuffjp/*` package in `package.json` to the new release together, installs with the project's own package manager, then runs the new version's `doctor --fix`, which also rewrites the project's agent skills for that version. `--dry-run` shows the plan first:

```text
●  @debuffjp/audio ^0.19.0 → ^0.20.0
●  @debuffjp/core ^0.19.0 → ^0.20.0
●  @debuffjp/input ^0.19.0 → ^0.20.0
●  @debuffjp/juice ^0.19.0 → ^0.20.0
●  @debuffjp/cli ^0.19.0 → ^0.20.0
●  @debuffjp/dev ^0.19.0 → ^0.20.0

[debuff] would move to 0.20.0
         what changed: https://github.com/debuffjp/debuff/blob/main/tooling/cli/CHANGELOG.md
```

## Why the packages move together

debuff's packages are released as one set, all at the same version, and they expect each other's exact behaviour. A project with `@debuffjp/core` 0.20 and `@debuffjp/dev` 0.19 can fail in ways that look like bugs in your game, so `debuff doctor` treats mismatched versions as a problem to fix. Upgrading one package by hand, then the next, passes through exactly that state. `upgrade` changes them all in one write.

## What it changes, and what it leaves alone

- **Every package in debuff's set**: the `@debuffjp/*` packages and `create-debuff`, in `dependencies` and `devDependencies`. Other packages, including `@debuffjp/tenten`, which ships on its own schedule, are left as they are.
- **The range style you chose**: `^0.19.0` becomes `^0.20.0`, an exact `0.19.0` becomes `0.20.0`, and `~` stays `~`.
- **Never a downgrade**: if a package already declares something newer than the latest release (a prerelease you're trying), it stays. `--to ` picks a version on purpose, including an older one.
- **Workspace and file links**: `workspace:` and `file:` entries are left alone, so it's safe to run inside a monorepo.

## The new version finishes the job

The command runs from the CLI you have, which is the old one. So after the install, it hands over to the newly installed CLI and runs its `doctor --fix`. That's the version that knows the new release's checks and has its agent skills, so the project's `.claude/skills/` and `.agents/skills/` end up describing the debuff it now runs. If any required check still fails afterwards, `upgrade` exits 2 and says to run `doctor` for the fixes.

For agents, `npx debuff upgrade --json` returns the plan, the install command it ran and the `doctor` result as one JSON document. The project's own agent guide tells agents to ask before upgrading, since a new release can change behaviour.

## Knowing when there's something to upgrade to

`npx debuff doctor` now says when a newer debuff is out, as advice that doesn't fail the check. And once a day, at the end of a command, the CLI prints one line on stderr when there's a newer release:

```text
debuff 0.21.0 is out (you have 0.20.0): npx debuff upgrade
```

It's quiet in all the places a line like that gets in the way: never with `--json`, never in CI, and never after `dev`, `create`, `doctor` or `upgrade`, which already cover it. `DEBUFF_UPDATE_CHECK=0` turns it off. The check asks the npm registry for the latest version with a short timeout, and when the registry can't be reached it says nothing.

Try it on a project:

```bash
npx debuff upgrade --dry-run
```