msd-core/docs/how-to/update-msd.md

# How to update MSD Core

Update an existing MSD Core install to the latest release, preview the changelog before committing, and recover any local customisations that the update would overwrite.

**What you need:** The same runtime MSD is installed for. The update command re-runs the installer under the hood, so it needs Node.js 24+, git and curl available (same requirement as the original install).

---

## The standard update path

From inside your AI runtime, run:

```bash
/msd-update
```

MSD will:

1. Detect the installed version and install scope (global or local).
2. Check the MSD repository's release tags (`vX.Y.Z`) for the latest release.
3. Fetch the changelog and show you what changed between your installed version and the latest.
4. Ask for confirmation before touching anything.
5. Back up any user-added files found inside MSD-managed directories to `msd-user-files-backup/`.
6. Run the bootstrap installer pinned to that release (`curl -fsSL https://msd.golem15.com | bash -s -- --ref vX.Y.Z --<runtime> --<scope>`).
7. Clear the update-check cache so the statusline indicator resets.
8. Offer to restore the user-added files it backed up in step 5.
9. Report whether locally modified MSD files were backed up to `msd-local-patches/`.

Before reporting completion, the installer checks each MSD-managed script and interpreter path written into runtime configuration, resolving the interpreter against the current install-time `PATH`. This only proves the path resolves now — a hook fired later under a different, more restricted `PATH` (e.g. a GUI launcher) can still fail even after this check passes.

If a script is missing, unreadable, has the wrong file type, lacks a required execute permission, or its interpreter cannot be resolved, the update fails and reports every invalid path, each tagged with what happens to that runtime's config next. For Claude Code and other settings.json-based runtimes, this check runs before the update writes settings.json, so nothing new is persisted (an earlier settings.json/settings.local.json migration, if one applied, is the one exception and stays applied) — reported as "not persisted". For Codex, this reverts config.toml/hooks.json along with the rest of that runtime's pre-install snapshot (skills/, agents/, msd-core/VERSION) — reported as "reverted". For Cursor, the runtime's config file is already written earlier in the update, ahead of this check, so a failure is reported but that file is left in place, broken — reported as "NOT reverted". Fix the reported path problem and rerun `/msd-update` — do not restart into the incomplete update.

Restart your runtime after a successful update to pick up new commands and agents.

---

## If the update target cannot be resolved

`UPDATE_TARGET_UNRESOLVED` means MSD could not identify an installed runtime to update. No update, cache clear, or installer run occurred. Rerun `/msd-update` from a valid installed runtime, or use the [standard installer](install-on-your-runtime.md#standard-install) for a fresh install.

---

## Flags

| Flag | What it does |
|------|--------------|
| `--sync` | After updating, sync skills from the MSD registry |
| `--reapply` | After updating, merge locally modified MSD files back in from `msd-local-patches/` |
| `--next` / `--rc` | Also consider prerelease tags (`vX.Y.Z-rc.N`), so a release candidate can be installed or refreshed (see ADR #660) |

```bash
/msd-update --sync        # Update and sync skills
/msd-update --reapply     # Update and reapply local patches
/msd-update --next        # Include release candidates
```

---

## Install or refresh a release candidate

MSD publishes release candidates as prerelease tags such as `v2.1.0-rc.1` (the RC channel established by ADR #660). To install or refresh from that channel:

```bash
/msd-update --next
# or equivalently:
/msd-update --rc
```

The full update flow applies — scope/runtime detection, changelog preview, custom-file backup, and cache clearing all run normally. The only difference is that `check-latest-version.cjs` also counts prerelease tags when it picks the latest version, and the installer is pinned to that tag.

Only `latest` and `next` are supported channels; no arbitrary channel can be passed (the script enforces an allowlist and exits with code 2 on an invalid tag).

Omitting `--next`/`--rc` targets the highest stable `vX.Y.Z` tag.

---

## Reviewing the changelog before updating

`/msd-update` always shows the changelog diff between your installed version and the latest *before* it asks for confirmation. You do not need to visit GitHub separately. The output looks like:

```text
## MSD Update Available

Installed: 1.39.0
Latest:    1.41.0

### What's New

---

[changelog entries for 1.40.0 and 1.41.0]

---

Proceed with update? [Yes, update now / No, cancel]
```

If the changelog cannot be fetched (no network access, forge outage), the update still proceeds after confirmation — it does not block on changelog availability.

---

## Recovering local customisations

### Files you added inside MSD-managed directories

If you placed custom files inside directories that MSD owns (for example, custom agents prefixed with `msd-` or extra files in `commands/msd/`), the installer detects them and copies them to `msd-user-files-backup/` before wiping those directories.

After the new version is installed, the update offers to put them back. You get a list of what was backed up, then a choice:

- **Restore them now** — each file is copied back to its original location and the update reports what it restored.
- **Leave them in the backup** — nothing is copied; the backup stays exactly where it is.

Either way the backup is **never deleted**, so declining is not destructive and you can restore later.

Before copying anything back, the restore runs a compatibility pass against the version that was just installed and attaches a warning to any file that looks like it may no longer work — one that references a workflow or `/msd:` command the new release retired, or a skill missing its `name` / `description` frontmatter. Warnings are advisory: the file is still restored, with the warning shown next to it, so you can decide whether to fix it.

Two cases are skipped rather than restored, because restoring would destroy something:

- The new release now ships a file at that exact path (your custom file would overwrite MSD's).
- A different file is already sitting at that path (restoring would overwrite your current version).

Both stay in the backup and are reported with the reason.

To restore later — or after an update where you declined — run the same operation directly:

```bash
node <config-dir>/msd-core/bin/msd-tools.cjs restore-custom-files --config-dir <config-dir> --apply
```

Drop `--apply` to preview what would be restored without writing anything.

Files you placed outside MSD-managed directories — custom agents not prefixed with `msd-`, custom commands outside `commands/msd/`, your `CLAUDE.md` files, and custom hooks — are never touched by the installer.

### MSD files you modified directly

If you edited a file that MSD installed (for example, tweaking an agent's system prompt), the installer detects the modification via a hash comparison against its manifest, backs the file up to `msd-local-patches/`, and then replaces it with the new version. After the update:

```bash
/msd-update --reapply
```

This merges your modifications from `msd-local-patches/` back into the newly installed files.

If you skipped `--reapply` after a previous update and want to apply patches now:

```bash
/msd-update --reapply
```

It is safe to run `--reapply` on its own without triggering a new download — if you are already on the latest version, MSD skips the install step and goes straight to reapplying patches.

---

## When the installer is unavailable

If the bootstrap installer fails due to an outage, network restrictions, or because you are working from the source repository, use the manual update procedure in [docs/manual-update.md](../manual-update.md). That document covers pulling the latest commit, building the hooks dist, and running `node bin/install.js` directly.

---

## If you are already on the latest version

`/msd-update` exits early with a confirmation message — no download, no install, no restart needed.

---

## Installer migrations

Each MSD release may include installer migrations that rename, move, or retire managed files. The migration layer runs automatically before the new package payload is written. Migrations that would affect files you have modified prompt for confirmation rather than acting silently. For the full design and runtime-configuration contract registry, see [docs/installer-migrations.md](../installer-migrations.md).

---

## Related

- [Install on your runtime](install-on-your-runtime.md)
- [Commands reference](../COMMANDS.md)
- [Manual update](../manual-update.md)
- [Installer migrations](../installer-migrations.md)
- [Docs index](../README.md)

## CLI version-skew warning

MSD warns (to stderr, non-blocking) when the resolved `msd-tools.cjs` is **outside your project root** while a project-local install exists — a sign that a global install (often a retired `@gsd-build/sdk` canary) is shadowing your project-local MSD. The warning names the resolved path and, for the `@gsd-build/sdk` case, gives the removal command:

```bash
npm uninstall -g @gsd-build/sdk
```

If you see this warning, remove the stale global package so `msd_run` resolves the project-local install.