feat: docs/ carries the operator's how-to guides, a configuration reference and the architecture and telemetry explanations carved out of README.md, INSTALL.md, INSTALL-MCP.md and EVALS.md; the last two retired (#190)

Files changed:
- .gitea/workflows/ci.yml
- .gitignore
- .vibe/hooks.toml
- AGENTS.md
- CHANGES.md
- EVALS.md
- INSTALL-MCP.md
- INSTALL.md
- README.md
- VERSION
- docs/dev/development.md
- docs/explanation/README.md
- docs/explanation/architecture.md
- docs/explanation/language-boundaries.md
- docs/explanation/telemetry-and-evaluation.md
- docs/how-to/README.md
- docs/how-to/browse-with-obsidian.md
- docs/how-to/capture-repository-docs.md
- docs/how-to/export-guidelines.md
- docs/how-to/ingest-a-source.md
- docs/how-to/maintain-the-wiki.md
- docs/how-to/query-the-wiki.md
- docs/how-to/run-the-weekly-review.md
- docs/how-to/set-up-the-mcp-server.md
- docs/how-to/trace-and-score-sessions.md
- docs/how-to/troubleshoot.md
- docs/how-to/update-an-instance.md
- docs/reference/README.md
- docs/reference/commands/distribution-and-versioning.md
- docs/reference/commands/instance-health.md
- docs/reference/commands/raw-material-and-uploads.md
- docs/reference/commands/telemetry.md
- docs/reference/commands/types-instructions-and-docs.md
- docs/reference/configuration.md
- instructions/dev/dev-setup.md
- instructions/dev/doc-pull-through.md
- instructions/dev/stack-build/SKILL.md
- instructions/dev/testing-conventions.md
- instructions/dev/version-parts.md
- instructions/setup-instance.md
- instructions/upgrade-instance.md
- reports/CONTRACT.md
- tools/.coveragerc
- tools/CONTRACT.md
- tools/README.md
- tools/chemenu/commands/dist_cmd.py
- tools/chemenu/commands/docs_verify.py
- tools/chemenu/commands/doctor.py
- tools/chemenu/commands/eval_cmd.py
- tools/chemenu/commands/git_publish.py
- tools/chemenu/commands/upload_cmd.py
- tools/chemenu/commands/version_cmd.py
- tools/chemenu/evals/__init__.py
- tools/chemenu/evals/scorecard.py
- tools/chemenu/evals/trajectory.py
- tools/chemenu/telemetry/policy.py
- tools/chemenu/tests/test_dist_cmd.py
- tools/chemenu/tests/test_git_publish.py
- tools/chemenu/tests/test_instructions_shell.py
- tools/chemenu/tests/test_pipeline_l0.py
- tools/chemenu/toc.py

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2

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

@@ -0,0 +1,145 @@
+# 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.
+- **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 <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.