chemenu/docs/how-to/update-an-instance.md

# Update an instance

Bring an instance installed from a release up to a newer release of the stack: the tools, types,
instructions and contracts. Your pages stay yours. The agent carries out the upgrade by following
[instructions/upgrade-instance.md](../../instructions/upgrade-instance.md), which sets the order of
the steps, what each one decides, and where the session has to restart. This page covers the
decision before it, and what you'll see along the way.

<!-- wikitool:toc -->
## Contents

- [What is running, and is there something newer?](#what-is-running-and-is-there-something-newer)
- [Read the notes first](#read-the-notes-first)
- [What you say](#what-you-say)
- [Where the agent stops](#where-the-agent-stops)
- [Where the release comes from, and whom you trust](#where-the-release-comes-from-and-whom-you-trust)
- [Two first-time cases](#two-first-time-cases)
- [Pitfalls](#pitfalls)
<!-- /wikitool:toc -->

## What is running, and is there something newer?

Every instance carries the version of the **stack**, not of its content. It is in `VERSION`, and
`.wikitool-release.json` beside it records where the release came from and when it was exported.

```bash
tools/wikitool version         # what runs here, and where it came from
tools/wikitool version check   # is there a newer release?
tools/wikitool version notes   # what the newest release changes
```

`version check`, `version notes` and `dist upgrade --latest` are the only commands that go to the
network. All three ask the same release feed: the one named in the stamp, unless
`WIKITOOL_UPDATE_URL` overrides it. A feed that cannot be reached is reported as an error, **never**
as "up to date" and never as "no notes".

## Read the notes first

What a version number promises: two versions are compatible when they agree in the *leftmost
non-zero part*. `0.1.3 → 0.1.4` is a safe update and `0.1.3 → 0.2.0` is not. From `1.0.0` on, the
same rule reads as the familiar "a MAJOR breaks". `version check` says which case you are in
(`state: update` or `state: migration`).

That number only answers whether the new machinery can simply be copied over the old. Whether your
*content* has to be migrated is a second, independent question. So the release notes of a MAJOR
carry two separate lines, and both are worth reading before you start:

- **Breaking Change:** what stops working, and what this instance has to do about it.
- **Migration:** whether and how the pages are rewritten (`none required` when they are not).

`version notes` prints both. On an instance it reads them from the release feed, because an
instance's own `CHANGES.md` is a stub that an update never overwrites. It always asks for the
**newest** release, so while `VERSION` still names the old one, it answers with a version other than
the one installed, and says so on stderr. If the feed cannot be reached, the error names the release
page recorded as `release_url` in `.wikitool-release.json`. `--offline` sends you there directly.

Why the two questions are kept apart: [version-model.md](../explanation/version-model.md).

## What you say

```text
Update this instance to the latest release
```

## Where the agent stops

In the order you'll meet them:

- **The release notes.** The agent shows you both lines before it touches anything. A migration the
  instance already owes from an earlier release is finished first.
- **A stack file you changed by hand.** `dist upgrade` lists every file that differs from what the
  installed release shipped, instead of overwriting it silently. For each one, you decide: take the
  release's version, or keep yours. Keeping yours means the file is reported again at every future
  upgrade.
- **The preflight.** A new release may need other tools than the old one. If something is missing,
  the preflight stops with exit 42 and says what to install, exactly as during installation.
- **The first publish.** The swapped machinery is published on its own, before any content changes.
  That is far more than ten files, so the Mass-Update Gate (exit 42) shows you the list and the
  `--confirm` line.
- **The session restart.** The running session still holds the *old* `AGENTS.md`, contracts and
  skills, so the agent asks you to restart it before migrating content. The new session picks up
  where the old one stopped.
- **A required migration.** The agent carries it out, and may come back to you with a question
  while doing so: a migration document can reach a point that is yours to decide, such as a page
  that contradicts another.
- **An offered migration.** It changes a file the instance owns, so taking it or declining it is
  your decision.
- **The second publish,** of the migrated content, behind the same gate.

**A required migration can also be interrupted.** If the agent cannot complete one now, it stops
after the first publish and leaves it. That is a valid state: new machinery, content still in its
old form. `doctor` keeps warning until the migration is done, and a later session resumes with
`tools/wikitool migrate status`. The agent never records a migration it did not carry out, because
the content's version would then describe a shape the pages are not in.

**A migration can also be owed per checkout.** Most migrations rewrite pages: they are done once,
and every other clone of the instance receives the result with its next pull. The 10.0.0 migration
moves settings instead, out of gitignored files that belong to one checkout, so a pull does not
carry it. After another clone has pulled the new release, run `tools/wikitool config migrate`
there too. Until then `doctor` reports each leftover file as a `FAIL`, and a command that needs
one of those settings stops with exit 42 and names that command. `migrate done` is still recorded
only once per instance
([10.0.0-settings-tiers.md](../../instructions/migrations/10.0.0-settings-tiers.md)).

If a step fails for a reason that isn't obvious, the agent stops and offers you a bug report rather
than improvising ([Troubleshoot](troubleshoot.md)).

`doctor` warns as long as the content's version (`kb_version` in `.wikitool-kb.json`) is behind
`VERSION` and migrations are still open. An instance older than `.wikitool-kb.json` has no such file
at all. In that case `tools/wikitool migrate baseline <version>` is called once, and nothing is
guessed.

## Where the release comes from, and whom you trust

`tools/wikitool dist upgrade --latest --expect <version>` asks the release feed for its newest
release, downloads the tarball and its `.sha256` into a scratch directory, checks one against the
other and applies the release. The scratch directory is removed on every exit, including
`--dry-run`. `--expect` is the version `version notes` showed you: the feed only knows its *newest*
release, and `--expect` refuses **before** downloading if a newer one has appeared since, rather
than applying something nobody read. Pre-releases (`-beta.N`) need `--pre`.

**What the checksum does, and what it does not do.** The `.sha256` comes from the same feed as the
tarball. It protects against a damaged transfer, not against a compromised feed. Whether a release
is genuine rests on your trust in the host whose feed the instance asks (`update_url` in the stamp).
Nothing forces https. A configured `http://` feed is a deliberate choice. `WIKITOOL_UPDATE_TOKEN`
is sent only to downloads on the same host as the feed.

**Offline, or with a tarball from someone else:** put the tarball and its `.sha256` side by side,
and the agent passes the file instead of `--latest` (`dist upgrade <tarball>`). A tarball has to
unpack to exactly one top-level directory, which is the shape the release workflow builds.

## Two first-time cases

**The first jump to a release that knows `--latest`:** the option does not exist in the instance
yet, because the instruction there belongs to the release being left. Fetch the tarball and the
`.sha256` once from the release page, put them side by side, and run `dist upgrade <tarball>`. From
the next release on, the instance has `--latest` itself.

**The first jump to `4.5.0` or later:** `dist upgrade` itself does not exist in the instance yet,
because it arrived with `4.5.0`. Use the tool from the unpacked *new* tarball and point it at the old
instance:

```bash
tar -xzf chemenu-stack-<version>.tar.gz
CHEMENU_ROOT="$PWD" chemenu-stack-<version>/tools/wikitool \
  dist upgrade chemenu-stack-<version>.tar.gz --dry-run
```

`CHEMENU_ROOT` tells the package which corpus to work on ([configuration](../reference/configuration.md)).
Without it, the package would take the unpacked tarball itself for the instance. From the second
upgrade on, the instance carries the command and the instruction itself.

## Pitfalls

- An instance without a local `.wikitool-release.json`, or with one that has no `files` block (from
  before `4.5.0`), gives `dist upgrade` nothing to detect a local change against, so it refuses
  the swap. There is no repair for that today.
- Given a tarball or directory, `dist upgrade` downloads nothing. Only `--latest` downloads.
- To follow the swap by hand anyway, perhaps with a tool `wikitool` cannot run, use the file list in
  the `files` block of `.wikitool-release.json`. The exceptions - `kb/CONVENTIONS.md`, every
  `kb/*/COLLECTION.md`, `.wikitool-kb.json` - are in the
  [`dist upgrade` record](../reference/commands/distribution-and-versioning.md#dist-upgrade), along
  with what the command classifies and refuses.