feat: dist upgrade - apply a stack update, not just detect one (#7)

Files changed:
- CHANGES.md
- INSTALL.md
- VERSION
- tools/CONTRACT.md
- tools/chemenu/commands/dist_cmd.py
- tools/chemenu/kb_state.py
- tools/chemenu/ownership.py
- tools/chemenu/tests/test_dist_upgrade.py

INSTALL.md

@@ -167,10 +167,17 @@ wenn nicht). `tools/wikitool version notes` druckt den Eintrag.
 
 ### Eine Instanz aktualisieren
 
-Das Anwenden eines Updates ist ein bewusst manueller Vorgang - es 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.
+Zwei Wege, je nachdem, wie diese Instanz entstanden ist. Ein **Clone mit gemeinsamer
+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.
+
+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:
 
@@ -178,19 +185,35 @@ dieser Unterschied ist der Zustand, in dem sich jede Instanz mitten im Upgrade b
    tools/wikitool migrate status
    ```
 
-2. Release-Tarball herunterladen und entpacken (Weg A), die Release-Notes lesen.
-3. Die **Maschinerie** aus dem Tarball über die Instanz kopieren: `tools/`, `types/`,
-   `instructions/`, `AGENTS.md`, `VERSION`, `.wikitool-release.json` - **und `kb/CONTRACT.md`**.
-   Die letzte Datei liegt unter einem Content-Verzeichnis, ist aber Stack-Eigentum: sie hält,
-   was `wikitool` erzwingt, und ist in jeder Instanz gleich. Nicht anfassen: alles andere unter
-   `kb/` und `raw/`, `work/`, `.wikitool-kb.json` und `.git/` - das ist die Instanz selbst,
-   `kb/CONVENTIONS.md` und die `kb/*/COLLECTION.md` eingeschlossen.
-4. Achtung bei lokal angepassten Stack-Dateien. Die Autorenkonventionen gehören **nicht** dazu:
-   `kb/CONVENTIONS.md` und die `kb/*/COLLECTION.md` liegen unter `kb/`, werden in Schritt 3
-   also ohnehin nicht angefasst - genau dafür ist der Schnitt da. Wer darüber hinaus etwas
-   unter `tools/`, `types/` oder `instructions/` verändert hat, sichert das vorher und spielt
-   es danach wieder ein. Welche Dateien das sind, verrät ein Vergleich gegen die sha256-Summen
-   im `files`-Block der alten `.wikitool-release.json`.
+   Steht hier etwas aus, erst diese Migrationskette abschließen (Schritt 5 unten) - `dist upgrade`
+   verweigert den Tausch sonst von selbst.
+
+2. Release-Tarball herunterladen und die Release-Notes lesen (Weg A oben).
+3. **Maschinerie tauschen:**
+
+   ```bash
+   tools/wikitool dist upgrade <tarball-oder-verzeichnis> --dry-run
+   ```
+
+   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
@@ -204,15 +227,30 @@ dieser Unterschied ist der Zustand, in dem sich jede Instanz mitten im Upgrade b
    `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 der Migration>`, dann `doctor`,
+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.
+   starten. `dist upgrade` nennt diese Reihenfolge im eigenen Abschlussbericht, führt aber keinen
+   der Schritte selbst aus.
 
 `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
 `tools/wikitool migrate baseline <version>` aufrufen; geraten wird nichts.
 
+**Fallstricke.** Eine Instanz ohne lokale `.wikitool-release.json` (oder eine ohne `files`-Block,
+aus der Zeit vor `4.5.0`) hat für `dist upgrade` keine Basis, gegen die es eine lokale Änderung
+erkennen könnte, und verweigert den Tausch - dafür gibt es heute keine Reparatur (siehe Gitea #7).
+Der Befehl lädt selbst nichts herunter: `<tarball-oder-verzeichnis>` muss vorher aus Weg A
+geholt werden, und ein Tarball muss genau ein Top-Level-Verzeichnis enthalten - die Form, in der
+`.gitea/workflows/release.yml` es baut.
+
+Vor `4.5.0` stand hier ein rein manueller Ablauf (Maschinerie von Hand kopieren, `kb/CONTRACT.md`
+eingeschlossen, sha256-Vergleich von Hand). `dist upgrade` ersetzt genau diesen Teil; wer ihn
+dennoch von Hand nachvollziehen will oder muss (ein Werkzeug, das `wikitool` selbst nicht
+ausführen kann), findet die Dateiliste im `files`-Block der `.wikitool-release.json` und die
+Ausnahmen (`kb/CONVENTIONS.md`, `kb/*/COLLECTION.md`, `.wikitool-kb.json`) in
+[tools/CONTRACT.md](tools/CONTRACT.md)s `dist upgrade`-Zeile.
+
 ### Sonderfall: Update von 1.x auf 2.0.0
 
 Mit `2.0.0` wurde das Ursprungs-Repo von `torben/llm-wiki-test1` auf `torben/chemenu`