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, 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?
• Read the notes first
• What you say
• Where the agent stops
• Where the release comes from, and whom you trust
• Two first-time cases
• 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.

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.

What you say

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).

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

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:

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). 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, along with what the command classifies and refuses.