---
name: upgrade
description: Bring an existing PS1 decomp repository (one bootstrapped by hand, or one psxdecomp bootstrapped earlier) to the current psxdecomp pins — audit, plan, apply --dry-run, then apply on the developer's word. Invoked as /psxdecomp:upgrade.
disable-model-invocation: true
argument-hint: "[--dry-run] [--fetch] [--take ACTION] [--repo DIR] | own KEY VALUE"
---

# /psxdecomp:upgrade

psxrecomp's migrate shape: **audit → plan → apply --dry-run → apply**. `PSXD="${CLAUDE_PLUGIN_ROOT}/scripts/psxd"`.

1. `"$PSXD" upgrade audit --repo <repo>` — show the `FAIL`/`WARN` rows.
2. `"$PSXD" upgrade plan --repo <repo>` — show the numbered actions. `[psxdecomp]` actions are applied by the script;
   `[manual]` ones (a PA3 or kit update, a pin to decide) are the developer's: give the command, never run it. In
   split mode the script also owns `docs/ops/psxdecomp-split.md`, the developer's release card (ship, the push gate,
   contributor PRs). The writing rule of the public files is four more
   actions: `ai-policy`, `ste-rule`, `style-hook` and `style-ratchet`. `style-public` is always `[manual]`: the
   developer adds `config/style-ratchet.txt` to `config/public-paths.txt`.

   Three actions cover the other builds of a game. `firewall-debug` is the script's. `record-oracle` and
   `oracle-public` are `[manual]`: give the command of the plan line.
3. `"$PSXD" upgrade apply --dry-run --repo <repo>` — the exact writes.
4. Stop here when `--dry-run` was given. Otherwise ask (AskUserQuestion: `Apply` recommended / `Stop`), then
   `"$PSXD" upgrade apply --repo <repo>` (add `--fetch` to clone `refs/` too).
5. The script never commits. Its last line, `COMMIT ...`, is the command that commits the paths it wrote.
   Run that command on the developer's word. If a router session is running in that repository, do not apply; say so.

Tell the developer what each plan line does, in one line each. Two plan lines and what to say:

<example>

```
PLAN 3 [psxdecomp] floor: write tools/psxd_floor.py and docs/ops/psxdecomp-floor.md (…) — missing or older …
PLAN 7 [manual] PA3: the repository is at 3.14.1, psxdecomp is tested on 3.14.2; update with PA3's own installer …

3. I can apply this one: it adds the floor's tool and its reference file. Nothing of yours changes.
7. This one is yours: run PA3's installer yourself, then `/psxdecomp:doctor`. I do not run it.
```

</example>

Two kinds of action need a word to the developer:

- An action that ends in `-edited` names a psxdecomp file or rule that the game edited. The script never overwrites
  it unasked. Show the difference. On the developer's word run `"$PSXD" upgrade apply --take <action> --repo <repo>`,
  where `<action>` is the name without `-edited`, as the plan line prints it. Another name is refused.
- `own` records a tool of the game's own in `[own]` of `config/psxdecomp.toml`. psxdecomp then delivers nothing in
  its place. The plan proposes a key for a path that it knows. For any other one, and for
  `/psxdecomp:upgrade own <key> <value>`, run `"$PSXD" upgrade own <key> "<value>" --repo <repo>`. The key is one of
  `debt`, `names`, `gate`, `toolchain`, `campaign`, `matcher`. The value is a path or a command of the repository.
- `PLAN FAIL` or `APPLY FAIL` with "is not TOML" means that `config/psxdecomp.toml` has a typo. Nothing is written
  until the developer repairs it. `APPLY FAIL <n> step(s)` means that a tool of the game refused one step: the other
  writes are made, and a second apply finishes after the repair.