feat!: installation only from a release, into an empty folder; upstream merge/verify and private-instance.md removed, dist adopt, shell-neutral instructions (#153)

Files changed:
- .gitea/workflows/ci.yml
- .gitea/workflows/release.yml
- AGENTS.md
- CHANGES.md
- DEVELOPMENT.md
- EVALS.md
- INSTALL.md
- README.md
- VERSION
- docs/ownership-and-templates.md
- instructions/CONTRACT.md
- instructions/bootstrap.md
- instructions/dev/dev-setup.md
- instructions/dev/stack-dev/SKILL.md
- instructions/gates.md
- instructions/ingest-large-tree.md
- instructions/kb-profiles.md
- instructions/mcp-read-server.md
- instructions/migrations/3.0.0-authoring-conventions.md
- instructions/preflight.md
- instructions/private-instance.md
- instructions/session-setup.md
- instructions/setup-instance.md
- instructions/upgrade-instance.md
- tools/CONTRACT.md
- tools/README.md
- tools/chemenu/cli.py
- tools/chemenu/cli_contract.py
- tools/chemenu/commands/dist_cmd.py
- tools/chemenu/commands/docs_verify.py
- tools/chemenu/commands/doctor.py
- tools/chemenu/commands/git_publish.py
- tools/chemenu/commands/upstream_cmd.py
- tools/chemenu/commands/work_cmd.py
- tools/chemenu/config.py
- tools/chemenu/ownership.py
- tools/chemenu/tests/test_cli.py
- tools/chemenu/tests/test_dist_cmd.py
- tools/chemenu/tests/test_instructions_shell.py
- tools/chemenu/tests/test_preflight.py
- tools/chemenu/tests/test_preflight_pwsh.py
- tools/chemenu/tests/test_run_budget.py
- tools/chemenu/tests/test_upstream_cmd.py
- tools/chemenu/toc.py
- tools/preflight.ps1
- tools/preflight.sh

instructions/upgrade-instance.md

@@ -1,20 +1,20 @@
 ---
 type: types/instruction.md
 name: upgrade-instance
-description: Carry out a stack release upgrade on an instance built from a tarball - read this release's notes, swap the machinery with dist upgrade, work the migration chain, verify, publish, and restart the session at the point where the new control plane starts to matter.
+description: Carry out a stack release upgrade on an instance installed from a release - read this release's notes, swap the machinery with dist upgrade, work the migration chain, verify, publish, and restart the session at the point where the new control plane starts to matter.
 manual: true
 ---
 # Upgrade this instance to a new stack release
 
-An instance built from a `dist export` tarball takes stack updates by copying a newer release
-over its machinery. This is the order in which that happens, what each step decides, and where
-the two known rough edges are. It ends with the instance on the new `VERSION`, its content
-version recorded, every check green, and the change published.
+An instance installed from a release takes stack updates by copying a newer release over its
+machinery. This is the order in which that happens, what each step decides, and where the two
+known rough edges are. It ends with the instance on the new `VERSION`, its content version
+recorded, every check green, and the change published.
 
-**This is the tarball path.** An instance that is a *clone* of the origin repo, sharing git
-history, takes updates by three-way merge (`tools/wikitool upstream merge`) and follows
-[private-instance.md](private-instance.md) instead. `git remote -v` answers which one this is:
-a clone carries an `upstream` remote pointing at the origin.
+**Every instance takes this path.** An instance comes from a release and carries the
+`.wikitool-release.json` that release wrote; `dist upgrade` refuses to run without it. A clone of
+the origin repository is a development checkout of the stack itself, not an instance, and is
+updated with git rather than with this file.
 
 **One thing this file deliberately does not know.** The copy you are reading shipped with the
 release this instance is *leaving*, not the one it is going to - so nothing specific to a
@@ -39,18 +39,19 @@ documents that arrive inside the tarball.
   `dist upgrade --dry-run` both report the true state, and the step that matches what they say
   is where this run continues.
 
-Not for setting up a new instance ([setup-instance.md](setup-instance.md)), not for preparing a
-fresh clone ([bootstrap.md](bootstrap.md)), and not for the clone-with-upstream path above.
+Not for setting up a new instance ([setup-instance.md](setup-instance.md)) and not for preparing
+a further checkout of this one ([bootstrap.md](bootstrap.md)).
 
 ## Steps
 
-1. **Take a session id and pass it on every call for the whole upgrade** - the form and the
-   reason are in [session-setup.md](session-setup.md). An upgrade is one of the longest runs
-   this stack has, and the iteration budget only sees it as one run if every call carries the
-   same id:
+1. **Take a session id and keep it for every call of the whole upgrade:** `upgrade-<target
+   version>`, set with the line for your shell from [session-setup.md](session-setup.md) § Steps
+   - which also says what to do on a harness that starts a fresh shell per command. An upgrade is
+   one of the longest runs this stack has, and the iteration budget only sees it as one run if
+   every call carries the same id. Then:
 
    ```bash
-   WIKITOOL_SESSION_ID=upgrade-<target-version> tools/wikitool version check
+   tools/wikitool version check
    ```
 
 2. **Read this release's notes before touching anything.** Two lines decide the rest of the run:
@@ -88,10 +89,11 @@ fresh clone ([bootstrap.md](bootstrap.md)), and not for the clone-with-upstream
    appeared in the meantime is refused before anything is downloaded, rather than applied unread.
 
    The offline alternative is the tarball path: with the feed unreachable, or an archive the
-   operator supplies, take the `.tar.gz` and its `.sha256` from the release page named in step 2,
-   check the archive against the checksum before unpacking, and pass the file as `<tarball>`
-   where the steps below say `--latest --expect <version>`. A tarball must unpack to exactly one
-   top-level directory. The checksum comes from the same host as the archive, so it catches a
+   operator supplies, the operator puts the `.tar.gz` and its `.sha256` side by side, from the
+   release page named in step 2, and you pass the archive as `<tarball>` where the steps below
+   say `--latest --expect <version>`. `dist upgrade` checks the archive against the `.sha256`
+   beside it before unpacking, and refuses one that does not match. A tarball must unpack to
+   exactly one top-level directory. The checksum comes from the same host as the archive, so it catches a
    damaged transfer, not a compromised host - who is trusted to publish releases is the
    operator's decision, made before this file starts ([INSTALL.md](../INSTALL.md) § "Version und
    Updates").
@@ -189,15 +191,15 @@ fresh clone ([bootstrap.md](bootstrap.md)), and not for the clone-with-upstream
    points at, is the other repairable shape - the `new` template from step 5 that nobody adopted.
    The fix is the ordinary adoption every `root: kb` type already needs, not a data migration:
    copy the shipped templates to their unsuffixed names, then fill the instance-owned parts
-   (language, template text, any extra fields) the way step 5 of
+   (language, template text, any extra fields) the way the authoring-conventions step of
    [setup-instance.md](setup-instance.md) describes for a fresh instance.
 
    ```bash
-   cp types/<name>.md.template types/<name>.md
-   cp kb/<collection>/COLLECTION.md.template kb/<collection>/COLLECTION.md
+   tools/wikitool dist adopt types/<name>.md.template types/<name>.schema.yaml.template kb/<collection>/COLLECTION.md.template
    ```
 
-   The `.template` files stay where they are - they are the source for the next upgrade's
+   `dist adopt` copies only what does not exist yet, so a file this instance already adopted
+   and filled is never touched. The `.template` files stay where they are - they are the source for the next upgrade's
    comparison. Any other failure is read against step 2's **Breaking Change:** line: if the
    release predicted it, the notes also say what fixes it; if it did not, stop and report it
    rather than improvising.
@@ -274,8 +276,8 @@ fresh clone ([bootstrap.md](bootstrap.md)), and not for the clone-with-upstream
 
 ## Scope
 
-For an instance that receives releases as tarballs. Not the origin repo, which has no upgrade
-path of its own, and not a clone with shared history - see the second paragraph. Anything about
+For an instance installed from a release. Not the origin repo, which has no upgrade path of its
+own - see the second paragraph. Anything about
 *writing* a migration document rather than running one is
 [migrate-corpus.md](migrate-corpus.md) § "Writing the migration document".