# 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. ## 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) ## 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. - **An offered migration.** A required migration is simply carried out. An *offered* one 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. 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 ` is called once, and nothing is guessed. ## Where the release comes from, and whom you trust `tools/wikitool dist upgrade --latest --expect ` 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 `). 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 `. 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-.tar.gz CHEMENU_ROOT="$PWD" chemenu-stack-/tools/wikitool \ dist upgrade chemenu-stack-.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.