stack: Upgrade-Pfad bekommt eine eigene manual-Instruktion, INSTALL.md verweist darauf (#108)

Files changed:
- CHANGES.md
- INSTALL.md
- VERSION
- instructions/session-setup.md
- instructions/upgrade-instance.md
- tools/CONTRACT.md
- tools/chemenu/commands/dist_cmd.py
- tools/chemenu/tests/test_dist_upgrade.py

INSTALL.md

@@ -172,7 +172,10 @@ Update von 1.x auf 2.0.0" unten ist genau dieser Fall.
 Deshalb stehen in den Release-Notes eines MAJOR zwei getrennte Zeilen, und beide sind vor dem
 Update zu lesen: **Breaking Change:** sagt, was aufhört zu funktionieren und was diese Instanz
 dagegen tun muss; **Migration:** sagt, ob und wie der Korpus umgeschrieben wird (`none required`,
-wenn nicht). `tools/wikitool version notes` druckt den Eintrag.
+wenn nicht). `tools/wikitool version notes` druckt den Eintrag - allerdings nur dort, wo eine
+gefüllte `CHANGES.md` liegt, also im Ursprungs-Repo. Eine ausgelieferte Instanz bekommt die
+Datei als Stub und liest die Notes stattdessen auf der Release-Seite, die
+`.wikitool-release.json` als `release_url` nennt.
 
 ### Eine Instanz aktualisieren
 
@@ -180,81 +183,42 @@ Zwei Wege, je nachdem, wie diese Instanz entstanden ist. Ein **Clone mit gemeins
 Git-History** (`upstream`-Remote auf das Ursprungs-Repo, siehe
 [instructions/private-instance.md](instructions/private-instance.md)) nimmt Stack-Updates per
 echtem Drei-Wege-Merge: `tools/wikitool upstream merge`. Alles Folgende gilt für eine **Instanz
-aus einem Tarball**, ohne gemeinsame History - der Weg unten unter „Eine Instanz aktualisieren"
-nutzt sie.
+aus einem Tarball**, ohne gemeinsame History.
 
 Das Anwenden eines Updates schreibt in eine Instanz, die bereits Inhalt hat. Der Inhalt hat dabei
 eine **eigene Version**: `.wikitool-kb.json` sagt, in welcher Form die Seiten vorliegen,
 unabhängig davon, welche Maschinerie danebensteht. Genau dieser Unterschied ist der Zustand, in
 dem sich jede Instanz mitten im Upgrade befindet.
 
-1. **Vor dem Tausch** prüfen, was ansteht - solange `VERSION` noch die alte ist:
+**Die Durchführung selbst steht in `instructions/upgrade-instance.md`** - die Reihenfolge, was
+jeder Schritt entscheidet, wo die Agent-Sitzung neu gestartet werden muss, und die beiden Stellen,
+an denen heute Handarbeit nötig ist. Sie steht dort und nicht hier, weil sie von einer
+Agent-Sitzung ausgeführt wird; eine zweite Fassung derselben Schrittfolge an dieser Stelle wäre
+genau die Kopie, die irgendwann auseinanderläuft. Wer den Lauf selbst fahren will, liest dieselbe
+Datei.
 
-   ```bash
-   tools/wikitool migrate status
-   ```
+Was dieses Dokument beiträgt, ist die Entscheidung *davor* - welches Release, ob überhaupt, woher
+der Tarball kommt (§ „Version und Updates" und Weg A oben) - und der eine Sonderfall, den die
+Instruktion nicht abdecken kann, weil es sie dort noch nicht gibt:
 
-   Steht hier etwas aus, erst diese Migrationskette abschließen (Schritt 5 unten) - `dist upgrade`
-   verweigert den Tausch sonst von selbst.
+**Beim ersten Sprung auf `4.5.0` oder höher gibt es `dist upgrade` in der Instanz noch nicht** -
+es kam erst mit `4.5.0`. Dann das Werkzeug aus dem entpackten *neuen* Tarball verwenden, gegen die
+alte Instanz gerichtet:
 
-2. Release-Tarball herunterladen und die Release-Notes lesen (Weg A oben).
-3. **Maschinerie tauschen:**
+```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
+```
 
-   ```bash
-   tools/wikitool dist upgrade <tarball-oder-verzeichnis> --dry-run
-   ```
+`CHEMENU_ROOT` sagt dem Paket, auf welchen Korpus es zeigen soll (siehe § Konfiguration); ohne die
+Variable würde es den entpackten Tarball selbst für die Instanz halten. Ab dem zweiten Upgrade
+trägt die Instanz Kommando und Instruktion selbst, und der normale Weg greift.
 
-   **Beim ersten Sprung auf `4.5.0` oder höher gibt es dieses Kommando in der Instanz noch
-   nicht** - es kam erst mit `4.5.0`. Dann das Werkzeug aus dem entpackten *neuen* Tarball
-   verwenden, gegen die alte Instanz gerichtet:
-
-   ```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` sagt dem Paket, auf welchen Korpus es zeigen soll (siehe § Konfiguration);
-   ohne die Variable würde es den entpackten Tarball selbst für die Instanz halten. Ab dem
-   zweiten Upgrade trägt die Instanz das Kommando selbst und die kurze Form oben genügt.
-
-   Klassifiziert jede Datei aus dem `files`-Block der neuen `.wikitool-release.json`:
-   unverändert seit der Installation, lokal verändert oder gelöscht, neu im Release, oder aus dem
-   Release entfallen - und druckt die Migrationskette, die nach dem Tausch aussteht, ohne sie
-   auszuführen. Ohne `--dry-run` schreibt der Befehl; eine lokal veränderte oder gelöschte Datei
-   wird dabei **nie** stillschweigend überschrieben - der Lauf bricht mit der vollständigen Liste
-   ab, es sei denn `--keep-local` ist gesetzt (dann bleibt jede davon unangetastet, erneut
-   gemeldet). `--prune` entfernt zusätzlich Dateien, die der neue Release nicht mehr ausliefert
-   und die seit der Installation unverändert sind. Voraussetzungen: ein sauberer Arbeitsbaum
-   (kein Git-Repo ist ein WARN, keine Sperre), eine lokale `.wikitool-release.json` mit
-   `files`-Block (fehlt sie, siehe „Fallstricke" unten), und `.wikitool-kb.json` vorhanden.
-   Committet und pusht nichts (Invariante 5). Vollständiger Fehlerkontrakt:
-   [tools/CONTRACT.md](tools/CONTRACT.md).
-
-   Eine lokal veränderte Stack-Datei ist damit sichtbar, statt von Hand gegen die sha256-Summen
-   im `files`-Block geprüft werden zu müssen - genau der Schritt, der vor `4.5.0` hier stand.
-4. Bei einer Kompatibilitätsgrenze (`dist upgrade` meldet sie laut) die Release-Notes vor dem
-   nächsten Schritt lesen: **Breaking Change:** und **Migration:** im Eintrag von
-   `tools/wikitool version notes` sagen, was aufhört zu funktionieren und ob der Korpus
-   umgeschrieben werden muss.
-5. **Die Migrationskette abarbeiten.** `tools/wikitool migrate status` listet jetzt alle
-   offenen Migrationen in der Reihenfolge, in der sie laufen müssen - bei einem Sprung über
-   mehrere Versionen sind das mehrere. Für jede: das genannte Dokument unter
-   `instructions/migrations/` ausführen lassen (die Prozedur dazu ist
-   `instructions/migrate-corpus.md`), dann
-
-   ```bash
-   tools/wikitool migrate done <version>
-   ```
-
-   `done` verweigert jede Version, die nicht das nächste Glied ist - eine übersprungene
-   Migration hinterlässt einen Korpus in einer Form, die keine Version beschreibt. Ein
-   abgebrochenes Upgrade wird durch erneutes `migrate status` fortgesetzt.
-6. Prüfen: `tools/wikitool migrate verify --from <commit vor dem Tausch>`, dann `doctor`,
-   `docs verify`, `instructions verify` und `lint`. Zum Schluss
-   `tools/wikitool instructions sync` (die Skills sind Kopien) und die Agent-Session neu
-   starten. `dist upgrade` nennt diese Reihenfolge im eigenen Abschlussbericht, führt aber keinen
-   der Schritte selbst aus.
+Was `dist upgrade` dabei genau tut, klassifiziert und verweigert, steht in
+[tools/CONTRACT.md](tools/CONTRACT.md) - einschließlich des vollständigen Fehlerkontrakts. Eine
+lokal veränderte Stack-Datei ist damit sichtbar, statt von Hand gegen die sha256-Summen im
+`files`-Block geprüft werden zu müssen - genau der Schritt, der vor `4.5.0` hier stand.
 
 `doctor` warnt, solange `kb_version` hinter `VERSION` zurückliegt und noch Migrationen offen
 sind. Einer Instanz, die älter ist als `.wikitool-kb.json`, fehlt die Datei ganz - dann einmalig