stack: Version 6.1.0 freigegeben

Files changed: - CHANGES.md - VERSION
docs: die Zahl der nachgezogenen Pfadliterale korrigiert (33, nicht 27)
2026-09-17 09:13:43 +02:00 · 2026-09-17 09:01:50 +02:00 · 2026-09-17 08:59:25 +02:00 · 2026-09-16 21:38:20 +02:00 · 2026-09-16 19:18:59 +02:00 · 2026-09-16 19:18:00 +02:00
55 changed files with 2178 additions and 229 deletions
@@ -59,6 +59,395 @@ concern - readable here, never shipped as something to parse.
 ---
 ## 6.1.0 - 2026-09-17 - Upgrade-Pfad und Iteration-Budget-Gate gehaertet, wiki/-Pfadliterale bereinigt
 **Author:** Torben Nehmer
 <!-- wikitool:bumps -->
 **High impact**
 - Session-Id-Fallback: Harness-Variable schliesst die Luecke zwischen Telemetrie-Join und Iteration-Budget-Gate
 **Medium impact**
 - Upgrade-Prozedur als eigene Instruktion statt als Prosa in INSTALL.md
 - Migrationsdokument prueft gegen eine festgehaltene Vorher-Ausgabe, Beispielverweis auf die .template-Form
 - dist upgrade: --take-release nimmt fuer einen lokal geaenderten Pfad die Release-Fassung
 - version notes antwortet auf einer ausgelieferten Instanz aus dem Release-Feed
 - new: scaffold materializes a schema default only for a required field
 **Low impact**
 - Stale `wiki/` path literals swept out of tools/ and types/, with a test guarding against the next rename
 - CHANGES.md/Guard-Docstring: die Zahl der nachgezogenen Pfadliterale korrigiert (33, nicht 27)
 <!-- /wikitool:bumps -->
 Dieser Kandidat sammelt, was ein getraceter 5.0.0-auf-6.0.0-Upgrade-Lauf auf einer echten Instanz
 offengelegt hat: ein fehlender Upgrade-Leitfaden, zwei falsche Verweise im Migrationsdokument,
 eine fehlende dritte Antwort in `dist upgrade` fuer eine lokal geaenderte Datei, und
 `version notes`, das auf einer ausgelieferten Instanz nie antworten konnte. Im selben Lauf zerfiel
 die Sitzung durch einen PID-basierten Session-Id-Fallback in 21 Telemetrie-Buckets, wodurch das
 Iteration-Budget-Gate strukturell unerreichbar blieb - behoben durch eine Registry bekannter
 Harness-Session-Variablen, mit einem SIGPIPE-Nebenbefund im CLI-Emitter gleich mit. Dazu,
 unabhaengig vom getraceten Lauf: ein Scaffold-Fix, der `obligation: required` nicht mehr in jede
 neue Instruktion schreibt, und eine Bereinigung von 33 stehengebliebenen `wiki/`-Pfadliteralen aus
 der `wiki/`-nach-`kb/`-Umbenennung, mit einem Test-Guard gegen die naechste Umbenennung.
 Kein Grenzuebertritt: jede Aenderung ist in beide Richtungen ein Drop-in, additiv gegenueber
 `6.0.1`.
 ### Upgrade-Prozedur als eigene Instruktion statt als Prosa in INSTALL.md
 Der Upgrade-Pfad einer ausgelieferten Instanz stand nur in INSTALL.md § "Eine Instanz
 aktualisieren" - einem Dokument fuer Menschen, das `AGENTS.md` § File naming ausdruecklich als
 *"never by an agent as instruction"* fuehrt. Ausgefuehrt wird er aber von einer Agent-Sitzung,
 jedes Mal. Der getracete 5.0.0-auf-6.0.0-Lauf auf einer echten Instanz zeigt, was daraus folgt:
 der erste Tool-Call listete `instructions/` mit, fand keine passende Instruktion, oeffnete die
 naechstliegende (`private-instance.md`, der falsche der beiden Wege) und fiel dann auf INSTALL.md
 zurueck. `migrate verify --from <commit vor dem Tausch>` - INSTALL.md Schritt 6, erster
 Pruefschritt - lief in 33 Werkzeugaufrufen kein einziges Mal, und die Agent-Sitzung wurde nie neu
 gestartet, obwohl `AGENTS.md` im selben Commit +44/-3 bekommen hatte. Die anschliessende Migration
 lief damit unter dem alten Kontrollplan.
 Dahinter lagen drei Reihenfolgen nebeneinander: die in INSTALL.md, die im Abschlussbericht von
 `dist upgrade`, und die tatsaechlich gelaufene. Genau der Zustand, den Invariante 8 verbietet.
 `instructions/upgrade-instance.md` ist jetzt die eine Fassung: dreizehn Schritte von der
 Sitzungs-Id bis zum zweiten Publish, mit dem Sitzungsneustart an der Stelle, an der der neue
 Kontrollplan zu gelten anfaengt - nach dem Publish der Maschinerie, vor der Migrationskette, und
 mit `migrate status` als Wiedereinstiegspunkt fuer die neue Sitzung. `manual: true`, weil die
 Prozedur einmal pro Release laeuft und nie implizit aufgegriffen werden darf; ein Skill wuerde
 seine `description` dafuer in jede Sitzung legen. Auffindbar ist sie ueber den Abschlussbericht
 von `dist upgrade`, der statt einer eigenen Schrittliste jetzt die Datei nennt und das Kommando,
 bei dem der Lauf weitergeht (`instructions sync`). INSTALL.md behaelt, was ein Mensch *vorher*
 entscheidet, und den einen Sonderfall, den die Instruktion nicht abdecken kann, weil es sie dort
 noch nicht gibt: den ersten Sprung auf `4.5.0`.
 Zwei Schritte der Instruktion sagen ausdruecklich, dass sie eine Luecke umgehen, und was sie
 ueberfluessig macht. Schritt 2 liest die Release-Notes von der Release-Seite statt mit
 `version notes`, weil eine Instanz ihre `CHANGES.md` als Stub bekommt und `dist upgrade` sie nie
 ueberschreibt - der Befehl kann dort nicht heute und nicht spaeter antworten. Schritt 6 nimmt fuer
 eine lokal veraenderte stackeigene Datei die Release-Fassung von Hand, weil es zu `--keep-local`
 kein Gegenstueck gibt; dabei geht der noetige Commit ueber `publish --no-push`, nicht ueber
 `git commit` - Invariante 5 kennt keine Ausnahme fuer "ist ja nur eine Vorbedingung", und genau
 diese Ausnahme hat sich der beobachtete Lauf genommen.
 `instructions/session-setup.md` sagt jetzt, dass ein `export` nur traegt, solange die Shell
 traegt. Mehrere Harnesses starten pro Tool-Call eine frische Shell - das Arbeitsverzeichnis
 ueberlebt, Shell-State nicht - und dann faellt jeder Aufruf auf seine eigene Parent-PID zurueck.
 Im gemessenen Lauf wurde eine Sitzung so zu 21 Telemetrie-Buckets mit hoechstens drei Aufrufen
 pro Bucket: das Iteration-Budget-Gate (60) und der Loop-Breaker (3 identische in Folge) konnten
 strukturell nicht ausloesen. Die Anleitung nennt deshalb die Inline-Form pro Aufruf und den
 Einzeiler, mit dem sich beantworten laesst, welcher Fall vorliegt.
 Verifiziert: `docs verify` (73 ausgelieferte Dokumente, 58 Referenzdateien),
 `instructions verify` (23 Instruktionen, 7 Skills) und 1276 Tests gruen - einer davon neu und auf
 genau die Stelle gerichtet, an der die Doppelung wieder entstehen wuerde: der Abschlussbericht
 von `dist upgrade` muss die Instruktion und ihr Wiedereinstiegskommando nennen, nicht eine zweite
 Kopie der Liste.
 Kein Grenzuebertritt: eine neue Instruktionsdatei und ein geaenderter Meldungstext sind in beide
 Richtungen ein Drop-in. Eine Instanz, die zurueckgeht, behaelt die Datei als ueberzaehlige Datei,
 und nichts liest sie automatisch - `manual: true` heisst genau das.
 ### Migrationsdokument prueft gegen eine festgehaltene Vorher-Ausgabe, Beispielverweis auf die .template-Form
 `instructions/migrations/6.0.0-type-guidance-split.md` verlangte in seinem Verifikationsschritt,
 die Ausgabe von `types describe <name>` muesse *"read the same as it did before this migration"* -
 ohne dass ein Schritt davor dieses Vorher festhielt. Eine Pruefung gegen einen Zustand, den
 niemand aufgeschrieben hat, faellt auf das Gedaechtnis des Ausfuehrenden zurueck, und bei ueber
 150 Zeilen Ausgabe je Typ ist das keins. Der getracete 6.0.0-Lauf hat entsprechend durch
 `| head -250` und `| tail -80` geprueft und *"structurally identical to before"* geurteilt; was
 das uebersah, lag in der Mitte der `source`-Ausgabe. Das Dokument schreibt die Ausgabe jetzt in
 einem eigenen Schritt **vor** der Aenderung in eine Datei und diffed hinterher, mit
 `grep -c '^## Authoring guidance'` als Ein-Zahl-Probe: zwei Koepfe sind richtig - einen setzt
 `types describe` selbst, einen bringt die Guidance-Datei mit.
 Als generisches Muster steht dasselbe jetzt in `instructions/migrate-corpus.md` § "Writing the
 migration document", weil es nicht an diesem einen Dokument haengt: `migrate verify` traegt seine
 Baseline im letzten Commit, ob jemand daran denkt oder nicht - eine Migration an der Maschinerie
 statt an `kb/` hat gar keine, und genau dort entsteht die Behauptung, die sich nicht widerlegen
 laesst.
 Zweiter Fehler im selben Dokument: der Beispielverweis auf `types/entity.md` zeigt in einer
 ausgelieferten Instanz auf die beim Setup adoptierte Kopie - also auf genau den Vorher-Zustand,
 den der Schritt entfernen laesst. Der Nachher-Zustand liegt dort unter
 `types/entity.md.template`, und im Ursprungs-Repo existiert diese Datei ueberhaupt nicht:
 `dist export` re-keyt `types/<name>.md` erst beim Export. Der Satz konnte in einer Instanz also
 nicht bloss unguenstig sein, er konnte dort nie stimmen. Dazu sagt der Schritt jetzt die Sprache
 des Pointer-Absatzes - englisch, weil Anleitungsprosa an einen Agenten Control Plane ist,
 unabhaengig davon, wem die Datei gehoert - und dass das auch fuer behaltene lokale Prosa gilt:
 die wird uebersetzt, nicht umbenannt. Die Tabelle dazu wird verlinkt statt kopiert
 (`types/type-spec.md` § "Who owns a type-spec"), und ein behaltener Abschnitt bekommt einen
 eigenen Namen statt der Ueberschrift, die `types describe` schon selbst setzt.
 Derselbe Defekt eine Ebene hoeher, gefunden beim Nachmessen: `types/source.md` trug hier im
 Ursprungs-Repo noch einen Rest-Abschnitt `## Authoring guidance` mit einem einzigen Bullet, der
 die `title_prefix`-Frontmatter wiederholte - `types describe source` gab drei Koepfe aus, die
 anderen drei Typen zwei. Die Sprachzentralisierung hat den Abschnitt uebersetzt, der
 Guidance-Split den Rest der Prosa ausgelagert und diesen Bullet stehenlassen. Die Datei wird beim
 Export zu `types/source.md.template`, also haette ihn jede neu aufgesetzte Instanz mit adoptiert.
 Entfernt, geprueft mit genau dem Muster, das der Schritt oben jetzt vorschreibt: Vorher-Datei,
 Diff, vier entfernte Zeilen und sonst nichts, alle vier Typen komponieren jetzt mit zwei Koepfen.
 Verifiziert: `docs verify` (73 ausgelieferte Dokumente, 58 Referenzdateien),
 `instructions verify` (23 Instruktionen, 7 Skills) und 1276 Tests gruen. Kein neuer Test: die
 Aenderung ist Prosa in zwei Instruktionen und ein entfernter Abschnitt aus einem Type-Spec -
 was hier mechanisch pruefbar waere, prueft `docs verify` bereits als Type-Spec gegen sein Schema.
 Kein Grenzuebertritt: in beide Richtungen ein Drop-in. Die Korrektur gilt denen, die noch
 upgraden - eine Instanz, die das Angebot bereits genommen hat, liest das Dokument nicht noch
 einmal. Fuer sie lohnt der eine Befehl, mit dem der Schaden hier gefunden wurde:
 `grep -c '^## Authoring guidance'` ueber `types describe <name>` fuer alle vier Typen, drei
 bedeutet einen Rest-Abschnitt im eigenen Type-Spec.
 ### dist upgrade: --take-release nimmt fuer einen lokal geaenderten Pfad die Release-Fassung
 `dist upgrade` kannte zwei Antworten auf eine lokal geaenderte Datei und die dritte, die man
 eigentlich will, war keine davon. `--keep-local` *behaelt* die Aenderung - und weil der neue Stamp
 die Release-Digest trotzdem schreibt, wird dieselbe Datei bei jedem kuenftigen Upgrade erneut
 gemeldet. Fuer eine Datei, die der Instanz gar nicht gehoert, ist das der dauerhaft falsche
 Zustand. Der andere angebotene Weg, "reconcile them by hand first", hatte kein Werkzeug: im
 getraceten 5.0.0-auf-6.0.0-Lauf war eine `kb/CONTRACT.md` durch ein Format-on-Save um
 Tabellen-Whitespace verschoben, und das kostete eine Handkopie aus dem entpackten Tarball, einen
 Commit nur zur Herstellung der Clean-Tree-Vorbedingung des naechsten Kommandos - und damit einen
 rohen `git commit`, an `AGENTS.md` Invariante 5 vorbei, die fuer "ist ja nur eine Vorbedingung"
 keine Ausnahme kennt.
 `--take-release <pfad>` ist die fehlende Antwort: schreibe fuer diesen Pfad die Release-Fassung,
 statt abzubrechen. Wiederholbar, weil der Pfad die Entscheidung *benennt* - `--keep-local` verliert
 nichts, `--take-release` verwirft eine lokale Aenderung, und die zwei sind darum nicht symmetrisch
 genug fuer ein pauschales Flag. Beide gelten pro Pfad und komponieren auf einem Aufruf, was der
 gemischte Fall braucht: eine Datei zuruecksetzen, eine andere behalten. Ohne `--keep-local` bricht
 ein blockierter Pfad, zu dem nichts gesagt wurde, weiter ab; ein `--take-release`-Pfad, der gar
 nicht blockiert ist, wird abgelehnt - auch im `--dry-run`, denn das ist ein Fehler im *Argument*
 und nicht ein Zustand des Baums, und ein still ignorierter Tippfehler haette ein erfolgreiches
 Upgrade gemeldet und die Aenderung behalten, die verworfen werden sollte.
 Anders als bei `--keep-local` ist die Drift danach **weg** und nicht bloss uebergangen: die Datei
 stimmt wieder mit der Digest ueberein, die der Stamp fuehrt, und verschwindet aus der Meldung.
 Dazu die Abbruchmeldung selbst, die den Fehlgriff mitverursacht hat. Sie nannte `--keep-local` und
 "reconcile by hand", sagte aber nicht, dass es zu `--keep-local` kein Gegenstueck gibt - der Lauf
 kuendigte woertlich an, *"I'll let the upgrade take the release's version"*, und rief das Kommando
 ohne Flag auf. Jetzt nennt sie alle drei Antworten mit fertig eingesetzter Kommandozeile, im Muster
 des Mass-Update-Gates, und sagt ausdruecklich, dass keine davon der Default ist.
 `instructions/upgrade-instance.md` Schritt 6 traegt entsprechend nicht mehr die Drei-Schritt-Handreparatur, sondern die Entscheidung und den Dry-Run, mit dem man sie vorher sieht.
 ### version notes antwortet auf einer ausgelieferten Instanz aus dem Release-Feed
 `version notes` liest die lokale `CHANGES.md`. Eine ausgelieferte Instanz bekommt die aber als
 neunzeiligen Stub ohne einen einzigen Versionseintrag, und `CHANGES.md` steht in
 `chemenu.ownership.is_upgrade_preserved` - `dist upgrade` ueberschreibt sie also nie. Der Stub
 bleibt der Stub, dauerhaft. Der Befehl konnte dort nicht nur heute nicht antworten, sondern nie,
 und das an genau der Stelle, an der die Antwort am meisten zaehlt: dem Grenzuebertritt, vor dem
 **Breaking Change:** und **Migration:** gelesen werden muessen. Der getracete
 5.0.0-auf-6.0.0-Lauf kam nur weiter, weil er die Release-Notes ueber einen MCP-Server holte - ein
 Weg, den die Anleitung nicht nannte und den eine Instanz ohne erreichbaren Server gar nicht hat.
 Fehlt der Eintrag lokal, fragt der Befehl jetzt den Feed aus `update_url` - denselben, den
 `version check` benutzt - und druckt den `body` des Release, den `release.yml` im Ursprungs-Repo
 ohnehin aus `version notes` baut. Drei Praezisierungen halten das von einem stillen Netzaufruf
 auseinander:
 - **Nur mit Release-Stamp.** Ein Baum ohne `.wikitool-release.json` ist ein Dev-Checkout und
  behaelt die alte Fehlermeldung. Damit kann der neue Pfad im Ursprungs-Repo und in CI nicht
  betreten werden - auch nicht von `release.yml`s eigenem `version notes`.
 - **stdout traegt nur die Notes.** Die Zeile, welcher Feed gefragt wird, und die, welche Version
  geantwortet hat, gehen nach stderr. `release.yml` leitet stdout in die Datei um, die es als
  Release-Body postet; alles andere dort waere Inhalt im Release.
 - **`--offline`** verweigert den Aufruf und scheitert mit der `release_url` aus dem Stamp. Dieselbe
  Seite nennt auch jeder Fehlerfall des Feeds, damit ein Lauf, der die Notes nicht lesen kann,
  wenigstens weiss, wo sie stehen. Ein leerer `body` ist ebenfalls ein Fehler: eine leere Antwort
  darf nicht als "dieses Release hat nichts zu melden" durchgehen.
 Gefragt werden kann nur das **neueste** Release: `update_url` ist die einzige URL, die der Stamp
 fuehrt, und eine `/releases/tags/<tag>`-URL daraus zusammenzusetzen waere eine geratene
 API-Form statt einer gelesenen (Invariante 7). Antwortet der Feed eine andere Version als die
 gefragte, wird das auf stderr benannt und die Notes werden trotzdem gedruckt - das ist nicht der
 Randfall, sondern der Hauptfall, weil die Notes *vor* dem Tausch gelesen werden, wenn `VERSION`
 noch das Release nennt, das verlassen wird.
 `instructions/upgrade-instance.md` Schritt 2 und INSTALL.md § "Version und Updates" tragen
 entsprechend nicht mehr den Hinweis, dass der Befehl auf einer Instanz nicht antwortet; damit ist
 auch die letzte der beiden Werkzeugluecken aus dieser Instruktion heraus, und ihr Vorwort nennt
 keine mehr.
 Bei der Gelegenheit zwei Eintraege aus `tools/CONTRACT.md` § "Future considerations (not
 implemented)" entfernt, die dort seit ihrer Umsetzung falsch standen: der MCP-Server-Wrapper und
 `dist upgrade` selbst. Beide sind im selben Dokument weiter oben als existierend beschrieben.
 ### Session-Id-Fallback: Harness-Variable schliesst die Luecke zwischen Telemetrie-Join und Iteration-Budget-Gate
 Gemessen an einem getracten Lauf (33 `wikitool`-Aufrufe, eine Sitzung): unter Claude Code, dessen
 Bash-Tool jeden Aufruf in einer frisch initialisierten Shell ausfuehrt, fiel `chemenu.session`
 ohne gesetztes `WIKITOOL_SESSION_ID` auf `os.getppid()` zurueck - eine neue "Sitzung" pro Aufruf.
 Der Lauf zerfiel so in 21 Telemetrie-Buckets (hoechster Bucket: 3 von 33 Aufrufen), und das
 Iteration-Budget-Gate (60 Aufrufe, Loop-Breaker bei 3 identischen in Folge) sah nie mehr als 3 von
 60 - strukturell unerreichbar, obwohl `AGENTS.md` es als eine der vier code-durchgesetzten
 Sicherungen fuehrt. Derselbe Bruch traf den Telemetrie-Join: Hook-Events (`prompt.submitted`)
 trugen die Harness-UUID, `wikitool.call`-Events die wechselnde PID - kein gemeinsamer Schluessel,
 und `eval score` bewertete 1-3 Aufrufe statt 33.
 `chemenu.session` bekommt eine dritte Stufe zwischen der expliziten Variable und dem
 PID-Fallback: eine kleine Registry bekannter Harness-Session-Variablen (`HARNESS_ENV_VARS`),
 heute mit einem verifizierten Eintrag, `CLAUDE_CODE_SESSION_ID`. Verifiziert heisst: gegen eine
 echte Sitzung gemessen, dass die Variable ueber Tool-Aufrufe hinweg stabil bleibt (anders als die
 Shell-PID) und exakt der Wert ist, den der `UserPromptSubmit`-Hook in die Trace schreibt - der
 Wert wird unveraendert als Schluessel uebernommen, kein Praefix, keine Umschreibung, sonst waere
 der Join wieder zerstoert. Ein Eintrag wird nur nach genau dieser Verifikation aufgenommen: ein
 Variablenname, der zufaellig existiert und etwas anderes bedeutet, waere ein stillerer Fehler als
 der PID-Fallback, den er ersetzt.
 `run_budget`s Zustandsdatei (`budget.json`) traegt je Eintrag jetzt die Herkunft seiner Id; faellt
 dieselbe Id-Zeichenkette unter eine andere Herkunft als die gespeicherte, beginnt ein neuer
 Zaehler statt einen fremden zu erben - ein Eintrag ohne das Feld (vor dieser Aenderung
 geschrieben) behaelt seinen Count unveraendert. `doctor` ist jetzt dreiwertig (`OK` fuer eine
 explizite Variable oder eine erkannte Harness-Variable, `WARN` nur noch fuer den reinen
 PID-Fallback), und sowohl `budget status` als auch der `session.start`-Event der `wikitool`-
 Telemetriequelle nennen die Herkunft der Id.
 Im selben Lauf gemessener Nebenbefund auf der Emitter-Seite: ein durch eine geschlossene Pipe
 abgebrochener, ansonsten erfolgreicher Aufruf (`... | head`) stand mit `exit_code: 1` in der
 Trace - Click faengt `BrokenPipeError` selbst ab und erzwingt `sys.exit(1)`, ununterscheidbar von
 einem echten Fehler. `cli.py` installiert jetzt vor jedem Dispatch einen Wrapper um
 `stdout`/`stderr`, der einen EPIPE-Schreibfehler schluckt, bevor Click ihn sieht, und markiert den
 Trace-Eintrag stattdessen mit `stdout_truncated: true` bei unveraendertem, dem tatsaechlichen
 Kommandoerfolg entsprechendem `exit_code`.
 Reproduziert mit Tests, die echte Subprozesse statt In-Process-Aufrufe verwenden - `os.getppid()`
 ist sonst ueber die Testlaufzeit hinweg konstant: 61 Aufrufe aus je eigenem Prozess mit nur der
 Harness-Variablen loesen das Gate jetzt aus, drei identische ebenso den Loop-Breaker; vor dieser
 Aenderung waeren beide Tests gruen und blind gewesen.
 `--minor`: additiv (ein neues optionales `source`-Feld in `budget.json`, die Id faellt weiterhin
 auf `getppid()` zurueck, wo keine Variable greift), keine der beiden Drop-in-Richtungen verletzt.
 ### new: scaffold materializes a schema default only for a required field
 `tools/wikitool new instruction --name "x"` schrieb bislang `obligation: required` in jede neue
 Instruktion. `obligation:` ist ein Migrationsfeld (`instructions/CONTRACT.md`
 § `instructions/migrations/`) - eine gewoehnliche Instruktion ist keine Migration und hat nichts,
 was laufen muesste. Ursache: `new_page._build_frontmatter()` materialisierte jedes
 Schema-`default:` unbesehen; ueber alle acht `types/*.schema.yaml` gibt es genau zwei
 (`entity`/`concept`s `provenance`, in `required:`; `instruction`s `obligation:`, nicht).
 Die Regel jetzt: ein Schema-`default:` wird nur fuer ein Feld materialisiert, das das Schema auch
 in `required:` fuehrt. Auf einem optionalen Feld ist ein `default:` eine Lese-Annahme (was ein
 fehlendes Feld bedeutet), keine Schreib-Vorgabe - sie hinzuschreiben macht aus der stillen
 Annahme eine ausgesprochene Behauptung. `instruction.obligation`s eigene Lese-Annahme steht
 unveraendert und unabhaengig in `kb_state.py` (`frontmatter.get("obligation") or REQUIRED`).
 Der `array`-Zweig direkt daneben (leere Liste fuer ein unbesetztes Array-Feld wie `tags:`) ist
 davon ausdruecklich nicht betroffen - er bleibt fuer optionale wie Pflichtfelder gleich, weil ein
 fehlender Schluessel sonst den Template-Filter-Suffix woertlich in den Body schreiben wuerde
 (`{related|bullets}` -> das Wort "bullets").
 `--patch`: kein Bestandsdokument aendert sich (`obligation:` stand bislang nur explizit oder auf
 den beiden Migrationsdokumenten), keine Migration noetig, und ein zurueckgerolltes Werkzeug
 schriebe das Feld nur wieder mit.
 ### Stale `wiki/` path literals swept out of tools/ and types/, with a test guarding against the next rename
 Die Wissensschicht wurde am 2026-08-21 von `wiki/` nach `kb/` umbenannt. Das Verzeichnis zog um,
 die Zeichenkette nicht: 33 Stellen nannten weiter einen Pfad, den es nicht mehr gibt. Gemeldet
 war davon eine - die Kopfzeile des Lint-Reports (``Scanned N pages under `wiki/` ``) - als
 kosmetischer Einzelfall. Der Scan selbst war immer korrekt: `run_lint(kb_dir)` laeuft ueber
 `kb/`, gezaehlt wird, was dort liegt. Falsch waren ausschliesslich die Beschriftungen.
 Dreizehn davon sind nutzersichtbar. Die Fehlermeldungen von `xref`, `cite`, `touch`,
 `move`, `rm`, `rename`, `raw accept` und `log status` nannten `wiki/`, ebenso die `--help`-Texte
 von `cite sync --all`, `provenance rebuild-index --dry-run` und `move --reconcile`. Dazu die
 `description:`-Felder in `types/type-spec.schema.yaml`, die ueber `types describe` und ueber jede
 Schema-Validierungsmeldung bei einem Agenten landen. Zwei Stellen waren doppelt falsch:
 `git_publish.py` und `run_budget.py` verwiesen auf `wiki/concepts/Mass-Update Gate.md`, waehrend
 die Seite unter `kb/concepts/workflows/Mass-Update Gate.md` liegt - dort war auch die
 Collection-Ebene veraltet.
 Nicht angefasst: `raw/` (unveraenderlich, was immer dort steht) und die Alteintraege dieser
 Datei. Beide sind Aufzeichnungen dessen, was zu ihrer Zeit galt, keine Wegweiser - dieselbe
 Unterscheidung, die `instructions/dev/issue-tracking.md` fuer den Tracker trifft.
 Dass es vier Wochen unbemerkt blieb, ist der eigentliche Befund: kein Check liest ein Pfadliteral
 in Quelltext. `docs verify` kam dafuer nicht in Frage, weil es `shipped_prose()` liest, also
 Markdown - der Grossteil des Defekts sass in `.py`-Zeichenketten. Der Guard ist deshalb ein Test:
 `tools/chemenu/tests/test_source_hygiene.py` scannt jede `.py`-Datei unter `tools/chemenu/` sowie
 `tools/wikitool` gegen eine Tabelle stillgelegter Stufenpfade. Die naechste Umbenennung traegt
 dort eine Zeile nach und bekommt jede vergessene Stelle als Testfehler, statt als Zeichenkette,
 die ein Jahr lang niemand liest. Die zwei Ausnahmen stehen bewusst als Liste mit Begruendung und
 nicht als geschickteres Muster: eine Fixture-URL, in der `wiki` ein Repository-Name ist, und die
 Guard-Datei selbst, die die stillgelegten Pfade ja gerade deklariert.
 `kb/entities/projects/Chemenu.md` trug denselben Fehler in einer Kerndaten-Zeile und wurde ueber
 `touch` nachgezogen. "Dreilagig" blieb dort stehen: das deckt sich mit der Concept-Seite
 `Three-Layer Architecture`, die `reports/` ausdruecklich als vierte *Phase* neben den drei
 Schichten fuehrt.
 `--patch`: keine Schnittstelle aendert sich, kein Verhalten, keine Migration. Ein
 zurueckgerolltes Werkzeug gibt nur wieder die alten Beschriftungen aus.
 ### CHANGES.md/Guard-Docstring: die Zahl der nachgezogenen Pfadliterale korrigiert (33, nicht 27)
 Der Eintrag darueber nannte 27 nachgezogene Stellen und "rund die Haelfte davon nutzersichtbar".
 Beides war falsch. Die 27 stammten aus einem `wc -l`, das nur `tools/**/*.py` gezaehlt hatte -
 `tools/wikitool`, `types/type-spec.md` und die vier `description:`-Felder in
 `types/type-spec.schema.yaml` fehlten darin. Nachgezaehlt am Commit selbst
 (`git show <sha> | grep -c '^-.*wiki/'`): 33, davon 32 im Stack und eine auf der Seite
 `Chemenu`. Nutzersichtbar sind davon dreizehn, also gut ein Drittel und nicht die Haelfte.
 Derselbe Zahlendreher stand im Docstring von `tools/chemenu/tests/test_source_hygiene.py`, wo er
 kuenftigen Lesern erklaert, wogegen der Guard schuetzt - dort ebenfalls korrigiert. Dass diese
 Korrektur einen eigenen Bump braucht, ist kein Formalismus: der Docstring liegt unter `tools/`,
 und das Version-Gate in `.gitea/workflows/ci.yml` ist nach Pfad geschnitten, nicht nach Absicht.
 `--patch`: reine Prosakorrektur, kein Verhalten, keine Schnittstelle.
 ---
 ## 6.0.1 - 2026-09-16 - docs toc/verify erreichen die .template-Form einer Referenzdatei
 **Author:** Torben Nehmer
 <!-- wikitool:bumps -->
 **High impact**
 - docs toc/verify erreichen die .template-Form einer Referenzdatei
 <!-- /wikitool:bumps -->
 ### docs toc/verify erreichen die .template-Form einer Referenzdatei
 `kb/CONVENTIONS.md.template` war 105 Zeilen lang und trug keine TOC-Region. `toc.target_files()`
 berechnete den Dateisatz ueber die *adoptierten* Namen, und eine Datei auf `.md.template` faellt
 aus jedem dieser Walks heraus - also hat `docs toc --apply` das Template nie angefasst und
 `docs verify` es nie gelesen. Eine Instanz, die es nach `instructions/setup-instance.md`
 adoptiert, bekam damit eine `kb/CONVENTIONS.md` ohne Region und fiel am `docs verify` in
 Schritt 13 derselben Anleitung um - dem Befehl, mit dem das Setup endet. Ausgeliefert war das in
 `6.0.0`.
 Eine in Scope stehende Datei nimmt ihr `<name>.template` jetzt mit hinein: das Template ist
 dasselbe Dokument einen Schritt frueher in seinem Leben, und wer es auslaesst, laesst die
 adoptierte Kopie den Fehler erben. `docs verify` prueft im Ursprungs-Repo damit 57 statt 56
 Referenzdateien, in einer frisch exportierten Instanz 59.
 Ausgeloest hat es ein Wachstum um sechs Zeilen: `f350999` hat das Template von 99 auf 105 Zeilen
 gebracht und damit ueber die Schwelle von 100. Seither war `ci.yml` auf jedem Push rot (Laeufe
 279 bis 289) - was als Flackern gelesen wurde, weil jeder Push zusaetzlich einen gruenen
 `release.yml`-Lauf erzeugt und die Paare wie Lauf und Wiederholung aussehen. Sie sind zwei
 verschiedene Workflows.
 Grenzuebertritt-Frage geprueft und verneint, gegen den dokumentierten Update-Weg: das Template ist
 stack-eigen (`ownership.is_stack_owned` - jede `.template` unter einer Content-Stage), steht nicht
 in `UPGRADE_PRESERVED_PATHS`, und `dist upgrade` schreibt es damit mit. Eine Instanz bekommt das
 reparierte Template also durch den Upgrade selbst, ohne Handarbeit; der Rueckweg funktioniert
 ebenso, weil die alte Maschinerie das Template gar nicht erst prueft. Handarbeit faellt nur an, wo
 eine Instanz ihr stack-eigenes Template lokal veraendert hat - `dist upgrade` meldet genau das als
 `blocked` und verlangt `--keep-local`.
 Verifiziert: `docs verify`/`instructions verify` gruen, 1275 Tests gruen (3 neu: das Template einer
 in Scope stehenden Datei steht im Dateisatz, ein `.template` ohne solche Datei daneben nicht
 (`USER.md.template`), und ein Template ueber der Schwelle ohne Region ist ein Befund - der letzte
 waere am heutigen Stand rot gewesen). Dazu der vollstaendige `setup-instance.md`-Replay gegen einen
 frischen `dist export`: `doctor`, `docs verify`, `instructions verify` und `lint` laufen in der
 frischen Instanz durch.
 ---
 ## 6.0.0 - 2026-09-15 - search: Pfad und Titel vollstaendig, Trunkierung sichtbar
 **Author:** Torben Nehmer
@@ -57,7 +57,21 @@ flowchart TD
 - **Hooks enrich.** They add the tool calls the repo layer cannot see: file reads, greps,
  shell commands, prompts.
-Everything joins on `WIKITOOL_SESSION_ID`.
+Everything joins on one session id, resolved the same way by every source that has to pick
 one - see `chemenu.session`. The chain is `WIKITOOL_SESSION_ID`, then a harness's own session
 variable where one is registered (`chemenu.session.HARNESS_ENV_VARS` - Claude Code's
 `CLAUDE_CODE_SESSION_ID` today), then the parent process id. The middle step exists because
 the last one does not survive a harness that runs every tool call in its own freshly
 initialised shell: `os.getppid()` is then a new "session" per call, and neither the join nor
 the Iteration Budget Gate below can see more than one or two calls of a real run. A harness
 only earns an entry in that chain once a live session has been observed setting the variable,
 confirmed to be the exact id its own hooks write elsewhere in a trace - a name that merely
 looks plausible would mis-key a session more quietly than the pid fallback it replaced.
 A trace hook that only *observes* tool calls (a `PreToolUse`/`PostToolUse`-style wiring) does
 not by itself fix a harness whose events carry a different id than `wikitool`'s own emitter -
 the two still would not join. Wiring such a hook is only worth doing once this fallback chain
 already keys both sides on the same id.
 ## The trace
@@ -68,7 +82,7 @@ is [tools/chemenu/telemetry/schema.py](tools/chemenu/telemetry/schema.py).
 |---|---|
 | `v` | Schema version |
 | `ts` | ISO-8601 UTC, microsecond precision |
-| `session_id` | The join key. `WIKITOOL_SESSION_ID`, else the parent process id |
+| `session_id` | The join key - `chemenu.session`'s fallback chain: `WIKITOOL_SESSION_ID`, else a registered harness variable, else the parent process id |
 | `pid`, `seq` | `seq` counts **within one process**. Sort a trace by `(ts, pid, seq)` |
 | `source` | `wikitool`, `runner`, or a harness name |
 | `event` | See below |
@@ -202,8 +216,8 @@ same question the same way:
 | Git clone of this repo (dev checkout) | **on** (opt-out) | No `.wikitool-release.json` |
 | `dist export` tarball (a distributed instance) | **off** (opt-in) | `.wikitool-release.json` present |
-The form is read off `.wikitool-release.json`, the same stamp `version check` and `dist upgrade`
+The form is read off `.wikitool-release.json`, the same stamp `version check`, `dist upgrade` and
-already use to tell a distribution from the repo it came from - present means an operator never
+`version notes` already use to tell a distribution from the repo it came from - present means an operator never
 asked for telemetry, absent means this is the dev checkout the stack ships from, where the traces
 are its own measuring instrument (the rest of this file). A private instance
 (`instructions/private-instance.md`) is a git clone of an *export*, so it carries the stamp and
@@ -152,9 +152,12 @@ tools/wikitool version         # was läuft hier, und woher kommt es
 tools/wikitool version check   # gibt es ein neueres Release?
 ```
-`version check` ist der einzige Befehl, der ins Netz geht. Er fragt den Release-Feed der
+`version check` und `version notes` sind die einzigen Befehle, die ins Netz gehen, und beide
-Ursprungs-Instanz (`$WIKITOOL_UPDATE_URL` überschreibt; sonst der Wert aus dem Stamp). Ein
+fragen denselben Release-Feed der Ursprungs-Instanz (`$WIKITOOL_UPDATE_URL` überschreibt; sonst
-nicht erreichbarer Feed wird als Fehler gemeldet - **nie** als „aktuell".
+der Wert aus dem Stamp). `version check` ist dafür da; `version notes` greift nur dann darauf
 zurück, wenn die lokale `CHANGES.md` den Eintrag nicht hat - auf einer Instanz also immer, siehe
 unten - und sagt vorher auf stderr, welche URL es fragt. Ein nicht erreichbarer Feed wird als
 Fehler gemeldet - **nie** als „aktuell" und nie als „keine Notes".
 **Was die Versionsnummer aussagt:** kompatibel ist, was in der *linkesten von Null
 verschiedenen Stelle* übereinstimmt. `0.1.3 → 0.1.4` ist ein sicheres Update, `0.1.3 → 0.2.0`
@@ -172,7 +175,13 @@ 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 beide Zeilen - im Ursprungs-Repo aus der dort
 gefüllten `CHANGES.md`, auf einer ausgelieferten Instanz aus dem Release-Feed, weil die Instanz
 die Datei nur als Stub bekommt und ein Update sie nie überschreibt. Der Befehl fragt dabei immer
 das **neueste** Release: solange `VERSION` noch die alte Fassung nennt, antwortet er also mit
 einer anderen Version als der eigenen und sagt das auf stderr dazu. Ist der Feed nicht
 erreichbar, nennt die Fehlermeldung die Release-Seite, die `.wikitool-release.json` als
 `release_url` führt; `--offline` verlangt diesen Weg von vornherein.
 ### Eine Instanz aktualisieren
@@ -180,81 +189,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"
+aus einem Tarball**, ohne gemeinsame History.
 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:
+**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
+Was dieses Dokument beiträgt, ist die Entscheidung *davor* - welches Release, ob überhaupt, woher
-   tools/wikitool migrate status
+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`
+**Beim ersten Sprung auf `4.5.0` oder höher gibt es `dist upgrade` in der Instanz noch nicht** -
-   verweigert den Tausch sonst von selbst.
+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).
+```bash
-3. **Maschinerie tauschen:**
+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
+`CHEMENU_ROOT` sagt dem Paket, auf welchen Korpus es zeigen soll (siehe § Konfiguration); ohne die
-   tools/wikitool dist upgrade <tarball-oder-verzeichnis> --dry-run
+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
+Was `dist upgrade` dabei genau tut, klassifiziert und verweigert, steht in
-   nicht** - es kam erst mit `4.5.0`. Dann das Werkzeug aus dem entpackten *neuen* Tarball
+[tools/CONTRACT.md](tools/CONTRACT.md) - einschließlich des vollständigen Fehlerkontrakts. Eine
-   verwenden, gegen die alte Instanz gerichtet:
+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.
   ```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.
 `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
@@ -279,7 +249,7 @@ Ausnahmen (`kb/CONVENTIONS.md`, `kb/*/COLLECTION.md`, `.wikitool-kb.json`) in
 | Variable | Zweck | Fallback |
 |----------|-------|----------|
 | `WIKI_AUTHOR` | Override für den Autornamen neuer Source-Seiten | `git config user.name` - fehlt beides, bricht `new` mit `ERROR` ab |
-| `WIKITOOL_SESSION_ID` | Scopt das Iteration-Budget-Gate auf eine Aufgabe statt auf ein Terminal | Parent-Process-ID (siehe [instructions/session-setup.md](instructions/session-setup.md)) |
+| `WIKITOOL_SESSION_ID` | Scopt das Iteration-Budget-Gate auf eine Aufgabe statt auf ein Terminal | Eine vom Harness selbst gesetzte Sitzungs-Variable, wo eine bekannt ist (z. B. `CLAUDE_CODE_SESSION_ID`), sonst die Parent-Process-ID (siehe [instructions/session-setup.md](instructions/session-setup.md)) |
 | `WIKITOOL_UPDATE_URL` | Release-Feed, den `version check` abfragt | Wert aus `.wikitool-release.json`, sonst der Feed der Ursprungs-Instanz |
 | `WIKITOOL_UPDATE_TOKEN` | Gitea-Token für den Release-Feed | keiner - gegen `torben/chemenu` nicht nötig, nur für einen privaten Fork (siehe unten) |
 | `CHEMENU_ROOT` | Auf welchen Korpus das Paket zeigt - für einen Aufrufer, der nicht im Checkout selbst liegt | der Checkout, in dem das Paket liegt (`tools/wikitool` verhält sich ohne die Variable unverändert) |
@@ -1 +1 @@
-6.0.0
+6.1.0
@@ -51,6 +51,28 @@ The Iteration Budget Gate asks a fourth kind of question - not "is this instance
 itself (call count, repeated identical calls), not from anything about the content of any one
 call.
 ## A gate in code still has to be reachable
 Code beats prose for the reason above, but on its own it buys less than it looks like: a check
 that runs on every call is only as good as the thing it counts under. The Iteration Budget Gate
 scopes its counter to a session, and "session" was approximated by the parent process id whenever
 nothing set an explicit one. On a harness that runs every tool call in a freshly initialised
 shell, that approximation hands out a new session per call - so a traced run of thirty-three calls
 arrived as twenty-one sessions of one to three calls each, the ceiling of sixty was never
 approached, and the loop-breaker's window never held three calls at once to compare. The gate ran
 on every one of those calls, exactly as written, and refused nothing.
 That failure has no symptom of its own. A gate that fires announces that it exists; a gate that
 *cannot* fire looks identical to a gate nobody happened to need - the same clean runs, the same
 silence - and what finally told the two apart was reading a trace for an unrelated reason. So
 there is a third property to keep alongside living in code and carrying measured numbers: each
 gate has to leave evidence that it can still fire. The three that clear by token or by a
 deliberate edit have it by construction, because clearing one is a visible event in somebody's
 terminal. The budget gate, whose ordinary outcome is silence, is the one that had to be given
 it - which is why its session id now carries where it came from, into both the trace and
 `budget status`, so a session's own record answers the question instead of an investigation
 having to.
 ## Numbers that come from measurement, not intuition
 The iteration ceiling didn't start where it sits now. It used to run 15-25, borrowed from a
@@ -89,6 +89,11 @@ produces; `migration_kind:` (`mechanical` | `assisted`); and `obligation:`
 (`required` | `offered`, default `required`). It lives at
 `instructions/migrations/<version>-<slug>.md`.
 `wikitool new instruction` scaffolds none of the three: `migrates_to:` and `migration_kind:`
 have no schema `default:` at all, and an ordinary instruction's scaffold no longer materializes
 `obligation:`'s default either - all three are added by hand when a migration document is
 written, per [migrate-corpus.md](migrate-corpus.md).
 `migration_kind:` and `obligation:` are **two axes, not one**. The first says how the work is
 carried out, the second whether it has to happen at all:
@@ -43,7 +43,8 @@ touched; a row that does not apply needs no action.
 3. **A heading you changed means a table of contents to regenerate - by the tool, never by
   hand.** Every reference file over 100 lines carries one (`AGENTS.md`, the stage contracts,
   `kb/CONVENTIONS.md`, each `COLLECTION.md`, the flat `instructions/**.md` form, the
-   type-specs, the `docs/` pages - a `SKILL.md` is the one exception). Adding, renaming,
+   type-specs, the `docs/` pages - each with the `<name>.template` it ships as, where one
   exists, and a `SKILL.md` the one exception). Adding, renaming,
   reordering or deleting a `##`/`###` heading in one of them makes its region stale, and
   `docs verify` fails on stale exactly as it fails on missing:
@@ -120,6 +120,16 @@ Write it for a reader who has the new machinery and the old content, and who is
 changed, which pages are affected, how to tell a migrated page from an unmigrated one, and what
 `migrate verify` should report when it is done.
 **A verification step names its own baseline, and does it in an earlier step.** Where the
 document asks that something "read the same as before" - a composed `types describe` answer, a
 rendered index, any command's output - it says what to capture, where to put it, and at which
 point, so the check is a `diff` rather than a memory. Step 4's `migrate verify` needs none of
 that: its baseline is the last commit, which git holds whether or not anyone thought to keep it.
 A migration that changes machinery rather than `kb/` pages has no such baseline, and that is
 exactly where the unfalsifiable version has already slipped through - the 6.0.0 type-guidance
 split asked for output that "must read the same", named nothing to compare it against, and a
 stray section in the middle of one type-spec survived a check made in good faith.
 **Baseline: 1.0.0.** Migrations that predate it - the type-system move, the `confidence_base`
 backfill, the German section headings, the translation itself - have no documents and will not
 get any. An instance older than that is re-exported, not migrated.
@@ -56,7 +56,7 @@ upgrade(s) available"; taking it is not gated on anything else being current.
   shipped default.** Compare the type-spec's current prose (everything outside `## Frontmatter`
   and `## Template`) against the corresponding `types/<name>.guidance.md`:
-   - **Unchanged, or changed only in ways this instance is happy to lose:** proceed to step 3
+   - **Unchanged, or changed only in ways this instance is happy to lose:** proceed to step 4
     directly - the new guidance file already carries the improved version.
   - **Locally edited in a way worth keeping** (a house style note, an extra rule specific to
     this corpus): that edit has to move somewhere before the old prose is dropped. Either fold
@@ -65,28 +65,69 @@ upgrade(s) available"; taking it is not gated on anything else being current.
     instead of adding `guidance:` at all - both are legitimate; declining the stack default for
     one type is not an error.
-3. **Add `guidance: types/<name>.guidance.md` to the type-spec's frontmatter** - by hand, the same
+3. **Write down what `types describe` answers today, before changing anything.** Step 6 checks
   that the composed answer still reads the same, and that is only a check if the "before" was
   recorded somewhere other than your memory:
   ```bash
   tools/wikitool types describe <name> > /tmp/<name>-before.txt
   ```
   The whole output, per type-spec you are about to touch. Reading it through `head` or `tail`
   instead is how a difference in the middle of a 150-line answer survives the check - and a
   stray section in the middle of one type-spec is exactly what this step exists to catch.
 4. **Add `guidance: types/<name>.guidance.md` to the type-spec's frontmatter** - by hand, the same
   way any other type-spec frontmatter field is written (a type-spec is machinery, not a `kb/`
   page, so this is not a `wikitool touch` call). Do not remove `## Frontmatter` or `## Template`;
   only the generic prose around them is what the guidance file now carries.
-4. **Delete the now-duplicated prose from the type-spec**, keeping the H1, a short pointer to the
+5. **Delete the now-duplicated prose from the type-spec**, keeping the H1, a short pointer to the
-   guidance file (`types/entity.md`'s own current text is the worked example), `## Frontmatter`
+   guidance file, `## Frontmatter` and `## Template`. Where step 2 found a local edit worth
-   and `## Template`. Where step 2 found a local edit worth keeping and it lives in the
+   keeping and it lives in the type-spec's own body rather than a private guidance file, leave
-   type-spec's own body rather than a private guidance file, leave that part exactly where it is.
+   that part exactly where it is.
-5. **Verify:**
+   **The worked example is `types/<name>.md.template`, not `types/<name>.md`.** The latter is the
   copy this instance adopted at setup - it is the file you are editing, so it still shows the
   before-state. The `.template` beside it ships verbatim with every release and already carries
   the after-state: H1, pointer paragraph, and `guidance:` in the frontmatter. Read it for the
   shape; do not copy it wholesale, because its `## Frontmatter` and `## Template` are the
   stack's defaults and yours are yours.
   **The pointer paragraph is written in English**, like the H1 above it. It is authoring prose
   addressed to an agent, so it belongs to the control plane whether or not this instance owns
   the file it sits in - and so does any prose you keep beside it. A local note written in this
   instance's KB language before that rule existed is therefore translated, not relabelled:
   an English heading over a body in another language is the half-done version of this step.
   [types/type-spec.md](../../types/type-spec.md#who-owns-a-type-spec) has the part-by-part
   table; `## Frontmatter` and `## Template` are untouched by this migration either way.
   **Do not head a kept note `## Authoring guidance`.** `types describe` sets that heading itself
   and inlines the guidance file beneath it, which brings its own - so a third one out of the
   type-spec's body reads as a duplicated section in the composed answer. Give a local note a
   name of its own.
 6. **Verify against the file from step 3:**
   ```bash
-   tools/wikitool types describe <name>
+   tools/wikitool types describe <name> > /tmp/<name>-after.txt
   diff /tmp/<name>-before.txt /tmp/<name>-after.txt
   ```
-   The output must read the same as it did before this migration - the guidance prose composed
+   The two must read the same - the guidance prose composed ahead of the type-spec's own body,
-   ahead of the type-spec's own body, in one answer. A diff against the pre-migration output of
+   in one answer. Wording differences are expected only where step 2 found something to drop or
-   the same command, restricted to wording, is expected only where step 2 found something to
+   fold in; the structure (frontmatter fields, template block) must be byte-identical, and a
-   drop or fold in; the structure (frontmatter fields, template block) must be byte-identical.
+   heading that stands in the "after" but not in the "before" means prose was renamed where it
   should have been removed. One number catches the most likely version of that:
-6. **Record it:**
+   ```bash
   grep -c '^## Authoring guidance' /tmp/<name>-after.txt
   ```
   Two is correct - the one `types describe` sets, and the one the guidance file brings. Three
   means the type-spec's own body still carries a section of that name (step 5).
 7. **Record it:**
   ```bash
   tools/wikitool migrate done 6.0.0 --pages 0
@@ -7,11 +7,13 @@ description: Scope the wikitool iteration budget to the task by exporting a stab
 # Scope the session budget
 Every `wikitool` call is counted against a per-session iteration budget. A "session" is keyed
-by `WIKITOOL_SESSION_ID`, falling back to the parent process id when that variable is unset.
+by a fallback chain (`chemenu.session`): `WIKITOOL_SESSION_ID` first, then a harness's own
 session variable where one is registered (`CLAUDE_CODE_SESSION_ID` today), then the parent
 process id.
-Without an explicit id, the budget is scoped to whichever shell happened to run the command,
+Without an explicit id, and on a harness with no registered variable, the budget is scoped to
-so a task spanning several terminals is counted as several sessions - and one that reuses a
+whichever shell happened to run the command, so a task spanning several terminals is counted as
-shell inherits an unrelated count.
+several sessions - and one that reuses a shell inherits an unrelated count.
 ## Steps
@@ -23,8 +25,33 @@ export WIKITOOL_SESSION_ID="wiki-$(date +%s)"
 tools/wikitool sync
 ```
 **An `export` only carries if the shell carries.** Several agent harnesses run every tool call in
 a freshly initialised shell: the working directory survives, shell state - environment variables,
 functions - does not, so the variable is gone by the next call and each call falls back to whatever
 the chain's next step resolves to.
 On a harness with a registered variable in that chain (Claude Code, via `CLAUDE_CODE_SESSION_ID`),
 the fallback already keeps every call in one bucket without this step - but it scopes to the
 *whole* harness session, not to this one task, so a long-running session can carry unrelated prior
 work into the same count. Setting `WIKITOOL_SESSION_ID` explicitly still narrows the bucket to the
 task at hand, and remains the only way to scope it at all on a harness with no registered
 variable - each call falls back to its own parent pid there, and neither the 60-call ceiling nor
 the loop-breaker can ever trip (measured directly on a real upgrade run: 33 `wikitool` calls in
 one task split into 21 telemetry buckets under the pid fallback alone). On such a harness, pass
 the id **inline on every call** instead of `export`, keeping the same value for the whole task:
 ```bash
 WIKITOOL_SESSION_ID="wiki-1234" tools/wikitool sync
 WIKITOOL_SESSION_ID="wiki-1234" tools/wikitool new entity --name "..."
 ```
 Which of the three applies is answerable in one call: run `tools/wikitool budget status` twice in
 separate calls, and see whether it names the same id both times, and where that id came from -
 `budget status` prints both.
 Check the current state at any time with `tools/wikitool budget status`, which is never
-counted against the budget itself and prints the id it is counting under.
+counted against the budget itself and prints the id it is counting under, and its origin
 (`WIKITOOL_SESSION_ID`, a named harness variable, or the parent-pid fallback).
 **Why `sync` here, not just at publish time.** `publish` already pulls before it pushes, but a
 session that runs many `wikitool` calls before its first `publish` (an ingest, a multi-page
@@ -0,0 +1,231 @@
 ---
 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.
 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.
 **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.
 **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
 particular jump is written here. That belongs to the release notes (step 2) and to the migration
 documents that arrive inside the tarball.
 <!-- wikitool:toc -->
 ## Contents
 - [When to run](#when-to-run)
 - [Steps](#steps)
 - [Decision points](#decision-points)
 - [Scope](#scope)
 <!-- /wikitool:toc -->
 ## When to run
 - `tools/wikitool version check` reports `state: update` or `state: migration`, and the operator
  wants the new release installed.
 - An operator asks for the stack, the tooling or "the wiki software" to be brought up to date.
 - An interrupted upgrade is being resumed. Do not restart from step 1: `migrate status` and
  `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.
 ## 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:
   ```bash
   WIKITOOL_SESSION_ID=upgrade-<target-version> tools/wikitool version check
   ```
 2. **Read this release's notes before touching anything.** Two lines decide the rest of the run:
   **Breaking Change:** says what stops working and what this instance must do about it, and
   **Migration:** says whether the corpus has to be rewritten (`none required` when it does not).
   ```bash
   tools/wikitool version notes
   ```
   On an instance this answers out of the release feed, not out of the local `CHANGES.md` - that
   file arrives as a stub with no version entries and `dist upgrade` never overwrites it, so the
   command reads the notes off the release the feed publishes instead. Two things follow that are
   worth knowing before reading the output. It can only ask for the feed's *latest* release, so
   while `VERSION` still names the release being left, the version it answers with is **not** the
   one this tree declares - it says so on stderr, and that is the normal shape here rather than a
   fault. And if the feed cannot be reached, the error names the release page from
   `.wikitool-release.json`'s `release_url`; read it there and continue.
 3. **Ask what is already outstanding, while `VERSION` is still the old one:**
   ```bash
   tools/wikitool migrate status
   ```
   Anything in the outstanding chain is finished **before** the swap - `dist upgrade` refuses
   otherwise, and a chain that was already owed is not this release's business. The procedure is
   step 12's, run against the migration documents this instance already has. An `offered` upgrade
   listed separately blocks nothing and is decided later, in step 12.
 4. **Fetch the tarball and verify it.** `dist upgrade` downloads nothing; the file has to be
   there already. Take the `.tar.gz` and its `.sha256` from the release page found in step 2 and
   check them before unpacking. A tarball must unpack to exactly one top-level directory.
 5. **Dry-run the swap and read all four counts:**
   ```bash
   tools/wikitool dist upgrade <tarball> --dry-run
   ```
   `unchanged` / `new` / `locally changed` / `removed from the release`. The first two need no
   decision. `locally changed` is step 6. `removed` matters only if `--prune` is wanted, which is
   optional and never required.
 6. **Only if a file is reported as locally changed: decide whose file it is, then reconcile it.**
   The classification is against the sha256 the *installed* release recorded, so "locally
   changed" means the working tree differs from what this instance was given - deliberately or
   by a stray editor save.
   | Whose file | What to do |
   |---|---|
   | The instance's own | Cannot appear here, which is worth knowing so a report that looks like it is read again rather than acted on: a file the instance owns either ships only as `<name>.template` (`kb/CONVENTIONS.md`, each `COLLECTION.md`, `USER.md`/`SOUL.md`/`ENVIRONMENT.md`) and is never classified at all, or is seeded once and then kept out of the write set (`.wikitool-kb.json`, `CHANGES.md`) |
   | Machinery (a `CONTRACT.md`, anything under `tools/`, `types/`, `instructions/`, `AGENTS.md`, and every `<name>.template` beside an owned file) | It should not have local changes at all. Take the release's version: `--take-release <path>`, one per file |
   | Machinery this instance changed **on purpose** | `--keep-local` keeps every listed file untouched - but the new stamp records the release digest anyway, so the same file is reported again at every future upgrade. That is the right answer only for a difference the instance intends to carry indefinitely |
   The decision is per path, and the two flags compose - which is what a mixed report needs, one
   file reset and another kept. Preview it before it writes:
   ```bash
   tools/wikitool dist upgrade <tarball> --dry-run --take-release <path> [--take-release <path>]
   ```
   The preview marks every named path as one it would overwrite from the release, and a path that
   is not actually in the locally-changed list is refused *here* rather than in the writing run.
   Nothing else is needed: no copy out of the unpacked tarball by hand, and no commit made only
   to satisfy the next command's clean-tree precondition. Carry the flags you settled on into
   step 7.
   **Where `--keep-local` answers for some paths and `--take-release` for others, both go on the
   same call.** Without `--keep-local`, a locally changed path that no `--take-release` names
   still aborts the run: every one of them has to be answered for, and the abort's own text
   names the three answers with the command line already filled in.
 7. **Swap the machinery**, with whatever step 6 settled on. Note the commit the instance is on
   first - step 13 compares against it:
   ```bash
   git rev-parse --short HEAD          # the pre-swap commit; keep it
   tools/wikitool dist upgrade <tarball> [--take-release <path>] [--keep-local]
   ```
   It writes, and commits nothing.
 8. **Republish the skills.** `tools/wikitool instructions sync` - the published skill directories
   are copies, so until this runs the harness is still offering the previous release's skills.
 9. **Verify the machinery, and fix what the release said would need fixing:**
   ```bash
   tools/wikitool doctor
   tools/wikitool docs verify
   tools/wikitool instructions verify
   tools/wikitool lint
   ```
   A `docs verify` failure naming a missing or stale table of contents is repaired with
   `tools/wikitool docs toc --apply`, never by hand - a release that widened the set of files
   carrying a region will produce exactly that on files this instance adopted before the
   widening. 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.
 10. **Publish the machinery swap.** A release swap is far above the Mass-Update Gate's threshold,
    so expect exit 42. That is not an error and not yours to clear: reproduce the file breakdown
    it prints for the operator, stop, and publish with the token it named once they have
    approved it. See [gates.md](gates.md).
    Publishing here, before the content migrations, is deliberate. The intermediate state -
    new machinery, content still at the old shape - is a state the stack names rather than
    avoids (`.wikitool-kb.json` records it), and it keeps a 200-file swap out of the same commit
    as a content rewrite.
 11. **Restart the agent session.** Everything the previous steps replaced - `AGENTS.md`, the
    contracts, the type-specs, the skills - is still in the running session's context in its
    *old* form. A migration document written against a rule that arrived in this release will
    otherwise be carried out against the rule it replaced, and nothing checks that.
    The new session resumes at step 12. `tools/wikitool migrate status` is the resume point:
    it is stateful, so it says what is left without being told what already happened.
 12. **Work the migration chain.** `tools/wikitool migrate status` lists what is outstanding, in
    the order it has to run - a jump across several releases lists several. For each one, run
    the named document under `instructions/migrations/` following
    [migrate-corpus.md](migrate-corpus.md), then record it:
    ```bash
    tools/wikitool migrate done <version>
    ```
    An `offered` migration is a separate decision, not part of the chain: it changes a file this
    instance owns, blocks nothing, and recording it does not move `kb_version`. Take it or
    decline it deliberately; both are correct answers.
    **Whatever the migration changes, capture the before.** Where a document asks that some
    command's output "read the same as before", that is only checkable if the before was written
    down - redirect it to a file first and `diff` afterwards, rather than reading two long
    outputs from memory. Reading either one through `head` or `tail` is how a difference in the
    middle survives the check.
 13. **Verify the content, then publish.** Only after the chain has run, and against the commit
    noted in step 7:
    ```bash
    tools/wikitool migrate verify --from <pre-swap commit>
    tools/wikitool lint
    ```
    `migrate verify` is the only check that sees a page which lost a citation, a wikilink or a
    generated-region marker in the rewrite - `lint` reports a corpus that is internally
    consistent, which a corpus that quietly lost something still is. Then publish, the same way
    as in step 10.
 ## Decision points
 - **`version check` reports `state: migration` (a compatibility boundary)?** That is a statement
  about the machinery being a drop-in replacement, not about the corpus. A boundary crossing with
  an empty migration chain is normal and means the hand-work is elsewhere - which is precisely
  what step 2's **Breaking Change:** line names.
 - **`dist upgrade` refuses because the tree is not clean?** Commit or stash what is there first,
  and look at what it is: work in progress is committed through `publish`, an editor's stray
  reformatting of machinery is step 6's case.
 - **A required migration cannot be completed now?** Stop after step 10 and leave it. The
  intermediate state is legitimate and `migrate status` resumes it; what is not legitimate is
  recording a migration with `migrate done` that was not carried out - the version then describes
  a shape the corpus is not in.
 - **`doctor` reports `kb-version` behind `VERSION` after everything is done?** Correct when the
  release's chain was empty or carried only `offered` entries: an offer changes a file the
  instance owns, not the shape of its content, so the content version stays where it was.
 ## 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
 *writing* a migration document rather than running one is
 [migrate-corpus.md](migrate-corpus.md) § "Writing the migration document".
 What a human decides before any of this starts - which release, whether to take it at all, where
 the tarball comes from - is [INSTALL.md](../INSTALL.md) § "Version und Updates".
@@ -25,6 +25,18 @@ The frontmatter above is the one machine-read part. `sections:` names the headin
 generated regions render under. Safe to change at any time - each region is located by its
 marker pair, so a rename re-renders words and nothing else.
 <!-- wikitool:toc -->
 ## Contents
 - [Language](#language)
  - [Section headings](#section-headings)
 - [Naming](#naming)
 - [Tone](#tone)
 - [Relationship labels](#relationship-labels)
 - [Hedging](#hedging)
 - [Keeping this file honest](#keeping-this-file-honest)
 <!-- /wikitool:toc -->
 ## Language
 Pages are written in **{language}** - the `language:` in this file's own frontmatter, and the
@@ -3,7 +3,7 @@ type: types/entity.md
 entity_type: project
 tags: [wiki, llm, knowledge-base]
 created: 2026-08-04
-modified: 2026-09-02
+modified: 2026-09-17
 related:
  - implements: Personalization Plane
  - implements: Issue Label Scheme
@@ -56,7 +56,7 @@ Das Repository hat bereits ein deterministisches CLI, `tools/wikitool` (Python,
 - **Verantwortlich:** Torben
 - **Lizenz:** AGPL-3.0 (Stack: `tools/`, `types/`), CC-BY-4.0 (Inhalte)
 - **Repository:** `torben/chemenu` auf gitea.nehmer.net; bis 2026-09-01 `torben/llm-wiki-test1`
- **Architektur:** Dreilagig: raw/ (Quelle), wiki/ (Wissen), tools/ (deterministisches CLI)
+- **Architektur:** Dreilagig: raw/ (Quelle), kb/ (Wissen), tools/ (deterministisches CLI)
 ## Beziehungen
@@ -209,3 +209,9 @@ Alle Checklistenpunkte erledigt: 29 Seiten getouched, `migrate verify` 0 finding
 Korpusmigration zu #86/#60: confidence/confidence_base aus allen 152 betroffenen Entity-/Concept-Seiten entfernt (types/entity.schema.yaml, types/concept.schema.yaml deklarieren additionalProperties: false seit dem Stack-Teil von #60). Vier Einheiten entlang bestehender Area-Verzeichnisse (u1 kb/concepts/architectures+decisions+protocols+problems: 35, u2 kb/concepts/patterns+workflows: 45, u3 kb/entities/tools+people: 35, u4 kb/entities/technologies+projects+systems: 37), je per Skript work/confidence-removal/strip_confidence.py ueber chemenu.frontmatter_io.read_page/write_page (nie von Hand). migrate verify --from HEAD --fail-on-error zeigt fuer alle vier Einheiten 0 Befunde - modified:, Body, Referenzarrays und Feldreihenfolge unveraendert. lint --fail-on-error: 0 schema_validation_errors (voller Report unter reports/Lint Report 2026-09-10.md; die dort gemeldeten redundant_see_also-Funde sind vorbestehend, advisory und unabhaengig von dieser Migration). Ein Body-Treffer bleibt bewusst bestehen: kb/concepts/patterns/Confidence Scoring.md zitiert 'confidence: 0.XX' als YAML-Beispiel innerhalb eines Code-Blocks - das ist Content ueber das Pattern selbst, kein Frontmatter-Feld dieser Seite, und liegt ausserhalb des Body-unberuehrt-Scopes von #86. migrate done 5.0.0 --pages 152 gesetzt, kb_version steht auf 5.0.0. Workshop work/confidence-removal/ nach work/CONTRACT.md geschlossen und geloescht; die dauerhafte Ausgabe ist der bereinigte Korpus selbst. Naechster Schritt: ein gemeinsamer publish mit den Stack-Aenderungen aus #60 (kein eigener Publish fuer diese Einheit, siehe #60 Sequencing).
 ---
 ## [2026-09-17] update | Chemenu - Pfad kb/ in den Kerndaten korrigiert
 Die Kerndaten-Zeile "Architektur" nannte noch `wiki/` als Wissensschicht; das Verzeichnis heisst seit der Umbenennung am 2026-08-21 `kb/`. Nur der Pfad wurde nachgezogen - "Dreilagig" bleibt stehen, weil es sich mit [[Three-Layer Architecture]] deckt, wo `reports/` als vierte Phase neben den drei Schichten gefuehrt wird. Teil eines Stack-Durchgangs, der dieselbe veraltete Zeichenkette an 27 Stellen unter tools/ und types/ beseitigt hat.
 ---
@@ -89,7 +89,7 @@ tools/wikitool <command> --help
 | Command | Purpose |
 |---------|---------|
-| `new <type-name> --name "<Name>" [--type <path>] [--set field=value ...]` | Scaffold a page of any type. The type-spec drives fields, defaults, directory (`base_dir`/`layout`), title prefix, and template - `--set` is repeatable, and comma-separated values fill array fields. An element that itself contains a comma is written `\,`, or passed as its own repeated `--set` for that field - repeating an array field appends. See `types list`/`types describe`. |
+| `new <type-name> --name "<Name>" [--type <path>] [--set field=value ...]` | Scaffold a page of any type. The type-spec drives fields, directory (`base_dir`/`layout`), title prefix, and template - a schema `default:` is materialized only for a field the schema also lists in `required:` (an optional field's default is a reader-side assumption, not a scaffold-time value) - `--set` is repeatable, and comma-separated values fill array fields. An element that itself contains a comma is written `\,`, or passed as its own repeated `--set` for that field - repeating an array field appends. See `types list`/`types describe`. |
 | `new entity --name "<Name>" --set entity_type=<t> [--set tags=a,b] [--set related=X,Y] [--set sources="Source - Z"] [--set provenance=sourced\|general\|mixed]` | Scaffold `kb/entities/<subdir>/<Name>.md` |
 | `new concept --name "<Name>" --set concept_type=<t> ...` | Scaffold `kb/concepts/<Name>.md` |
 | `new source --name "<Name>" --set raw_files=raw/notes/x.md,raw/notes/y.md [--set source_url=<URL>] [--set entities=A,B] [--set concepts=C,D]` | Scaffold `kb/sources/Source - <Name>.md` (prefix added automatically) with a `raw_files:` list (rejects paths that don't exist) |
@@ -171,7 +171,7 @@ tools/wikitool <command> --help
 | `instructions verify` | Check the instruction layer: flat instructions validate against `types/instruction.schema.yaml`, each `SKILL.md` carries the frontmatter its harness reads, no `SKILL.md` carries a relative markdown link (`sync` copies it to a different depth than the source, so a `SKILL.md` references a target as a repo-root-relative plain path instead - see [instructions/CONTRACT.md](../instructions/CONTRACT.md) § "A skill's outbound reference is a plain path, not a link"), every published copy is byte-identical to its source, no instruction is left that nothing references, and nothing under `instructions/dev/` is referenced from outside it (a `<!-- dist:strip-start/end -->` block is exempt - see [instructions/CONTRACT.md](../instructions/CONTRACT.md)). Missing *every* copy is reported as "run sync", not as drift - that is a clean checkout |
 | `instructions list [--json]` | List the flat instructions with their descriptions. This is how the layer is discovered; `search` deliberately covers `kb/` only |
 | `docs verify` | Check the docs that mirror the code: every CLI command documented in this file's own § Commands table and, separately, in its § Error contracts table (both directions, checked per table, so a row dropped from one is not hidden by the same name surviving in the other, and only a name's presence in a row is checked, never the rest of that row's text), every directory under `kb/` has a `COLLECTION.md` and no directory outside it does, every collection declaring `profile:` and a `required_by_stack:` that agrees with the stack's own list, `kb/CONVENTIONS.md` naming all three tool-owned section headings if it exists at all, every stage contract present, every file under `types/` declaring `type: types/type-spec.md` validating against `types/type-spec.schema.yaml`, no pre-migration `type: entity` blocks left in the contracts, the `.gitignore` canaries clear in both directions (nothing ignored under `raw/`/`kb/`, `incoming/` ignored, everything ignored under `reports/` and the published skill directories), and no `.md`/`.template` file `dist export` would ship citing an issue number - the tracker exists only in the origin repo, so such a number in a distributed instance is a reference its reader can neither resolve nor recognise as unresolvable (a `<!-- dist:strip-start/end -->` region is exempt: it is already gone from the text the check reads, which is the export plan's, not the working tree's), every reference file `docs toc` covers carrying the current table-of-contents region for its own headings - missing and stale are one check, because the generator is idempotent - and every relative markdown link in one of those same reference files resolving to a file that actually exists (a target's `#anchor` suffix is stripped first; code fences and inline code spans are masked before scanning, so a passage showing link syntax as an example is not mistaken for a real reference). The name is about documentation parity, not about the `docs/` directory - it neither reads nor requires one, the same way `kb/` predates the collection it now checks |
-| `docs toc [--apply]` | Create, refresh or remove the generated table-of-contents region (`<!-- wikitool:toc -->` ... `<!-- /wikitool:toc -->`, placed after the title and before the first `##`) on every reference file over 100 lines, in the scope Anthropic's skill-authoring guidance names for a file previewed rather than read in full: `AGENTS.md`, every stage contract, `kb/CONVENTIONS.md`, every `kb/*/COLLECTION.md`, every flat `instructions/**.md` file, every `types/*.md` type-spec, and every `docs/` page. Computed from those categories rather than listed, so a file added later is in scope without a code change. `SKILL.md` is the one exception, and the same guidance is why: it places a skill body on the loading level that is read whole when the skill triggers, and aims its own TOC advice at the bundled reference files a skill points *at*. Human docs (`README.md`, `CHANGES.md`, `EVALS.md`, `INSTALL.md`, `tools/README.md`) are out of scope because AGENTS.md § File naming says no agent loads them as instruction. Dry-run by default (prints which files would change); `--apply` writes. `docs verify` checks the result stays current the same way it checks every other generated-from-code copy |
+| `docs toc [--apply]` | Create, refresh or remove the generated table-of-contents region (`<!-- wikitool:toc -->` ... `<!-- /wikitool:toc -->`, placed after the title and before the first `##`) on every reference file over 100 lines, in the scope Anthropic's skill-authoring guidance names for a file previewed rather than read in full: `AGENTS.md`, every stage contract, `kb/CONVENTIONS.md`, every `kb/*/COLLECTION.md`, every flat `instructions/**.md` file, every `types/*.md` type-spec, and every `docs/` page - each together with the `<name>.template` it ships as, where one exists. Computed from those categories rather than listed, so a file added later is in scope without a code change. A template is in scope because it is the same document one step earlier in its life: an instance adopts it by copying it back, so a region missing there is a region missing in the adopted file, which is how `kb/CONVENTIONS.md.template` came to grow past the threshold with no region and left every instance adopting it failing `docs verify` at the end of its own setup. `SKILL.md` is the one exception, and the same guidance is why: it places a skill body on the loading level that is read whole when the skill triggers, and aims its own TOC advice at the bundled reference files a skill points *at*. Human docs (`README.md`, `CHANGES.md`, `EVALS.md`, `INSTALL.md`, `tools/README.md`) are out of scope because AGENTS.md § File naming says no agent loads them as instruction. Dry-run by default (prints which files would change); `--apply` writes. `docs verify` checks the result stays current the same way it checks every other generated-from-code copy |
 ### Telemetry
@@ -185,10 +185,10 @@ tools/wikitool <command> --help
 | Command | Purpose |
 |---------|---------|
 | `dist export <target> [--dry-run] [--source-repo U] [--source-commit SHA] [--release-url U] [--update-url U]` | Write a contentless, distributable copy of this repo's machinery into an empty `<target>` directory: `AGENTS.md`/`README.md`/`EVALS.md` with any `<!-- dist:strip-start -->...<!-- dist:strip-end -->` region removed, `instructions/` (minus `instructions/dev/`), `types/` (the `root: kb` page type-specs and their schemas re-keyed as `.template`, the stack's own verbatim), `docs/` verbatim, `tools/` (no venv/caches), the `.github/hooks/`+`.vibe/` session-tracing config plus `.claude/settings.json`, `kb/CONTRACT.md` (no pages, no areas), the two flat anchors `raw/.gitkeep` and `incoming/.gitkeep` (both roots are flat now that a file's location under `raw/` is a date shard rather than a hand-picked type, so a fresh export no longer creates any type subdirectories under either root; `incoming/.gitkeep` is trackable and survives becoming a git repository, so a plain clone gets the directory without any bootstrap step re-creating it), `VERSION`, `USER.md.template`/`SOUL.md.template` plus `kb/CONVENTIONS.md.template` and each collection's contract re-keyed as `kb/<name>/COLLECTION.md.template` (the templates ship; the filled `USER.md`/`SOUL.md`/`kb/CONVENTIONS.md`/`kb/<name>/COLLECTION.md`/`types/<page-type>.md` never do - all of them bind their instance and none are the stack's to decide, and `find_leaks` refuses a plan carrying one), and a generated `.wikitool-release.json` stamp (version, export date, origin, and a sha256 per exported file - the base a later upgrade would compare against). The four origin options only fill stamp fields: `export` never calls git and cannot discover them. Refuses a non-empty target, and a tree with no `VERSION`. See `instructions/setup-instance.md`. One-way: there is no command that reconstructs a distributed instance into a dev instance - work on the stack in the origin repo (or a new dev instance exported from it) instead |
-| `dist upgrade <source> [--dry-run] [--keep-local] [--prune] [--pre]` | Apply a stack update `dist export` produced - the write half of `version check`. Never downloads anything: `<source>` is an already-fetched export directory or `.tar.gz` release archive (verified against a sibling `.sha256` if one is present; WARNs, does not block, if it is absent), which must unpack to exactly one top-level directory - the shape `.gitea/workflows/release.yml` packs. The write set is exactly the *new* `.wikitool-release.json`'s `files` block, minus what an export re-seeds from a blank template every time (`kb/log.md`, `raw/.gitkeep` - `chemenu.ownership.is_export_stub`) or seeds once and the instance owns from then on (`.wikitool-kb.json`, `CHANGES.md` - `chemenu.ownership.is_upgrade_preserved`), plus the stamp itself, always rewritten. Every candidate path is classified against the *local* `.wikitool-release.json`'s recorded digest for it: unchanged is overwritten silently, absent from the old stamp is created, and locally modified or locally deleted is **never** silently overwritten - the run aborts with the full list unless `--keep-local` says to proceed and leave every one of them untouched. After a `--keep-local` run the new stamp is still written whole, so it records the release's digest for files that were deliberately *not* written: the stamp is the baseline for the next comparison, not a literal inventory of what is on disk. That is what keeps a skipped file diverging - and therefore reported - on every later run, rather than quietly reading as current once it has been skipped once. A path in the old stamp but not the new one is reported as no longer part of the release and left alone unless `--prune` is passed, which removes it only if it is still unchanged since installation. Reports the migration chain the new machinery would owe (`chemenu.kb_state.chain` over the *new* tree's `instructions/migrations/`, read via a `directory` argument to `load_migrations`) but never runs any of it - there is no `migrate run`. Refuses before touching the source at all when: `VERSION` or `.wikitool-release.json` (with a `files` block) is missing locally, `.wikitool-kb.json` is missing, a migration is already outstanding against the *installed* machinery, or the working tree is dirty (not being a git repository at all is a WARN, not a refusal). Refuses after reading the source when: it carries no `VERSION`/`.wikitool-release.json`/`files` block, its version is older than or equal to the installed one (equal is a no-op success), or it is a pre-release (`-beta.N`) without `--pre`. Reports, but does not block on, a crossed compatibility boundary. Never touches git - no commit, no push (invariant 5). See `INSTALL.md` § "Eine Instanz aktualisieren" |
+| `dist upgrade <source> [--dry-run] [--keep-local] [--take-release <path>]... [--prune] [--pre]` | Apply a stack update `dist export` produced - the write half of `version check`. Never downloads anything: `<source>` is an already-fetched export directory or `.tar.gz` release archive (verified against a sibling `.sha256` if one is present; WARNs, does not block, if it is absent), which must unpack to exactly one top-level directory - the shape `.gitea/workflows/release.yml` packs. The write set is exactly the *new* `.wikitool-release.json`'s `files` block, minus what an export re-seeds from a blank template every time (`kb/log.md`, `raw/.gitkeep` - `chemenu.ownership.is_export_stub`) or seeds once and the instance owns from then on (`.wikitool-kb.json`, `CHANGES.md` - `chemenu.ownership.is_upgrade_preserved`), plus the stamp itself, always rewritten. Every candidate path is classified against the *local* `.wikitool-release.json`'s recorded digest for it: unchanged is overwritten silently, absent from the old stamp is created, and locally modified or locally deleted is **never** silently overwritten - the run aborts with the full list, and its text names the three answers with the command line already filled in, so that no reader takes any of them for the default. `--keep-local` proceeds and leaves every one of them untouched; `--take-release <path>` (repeatable) writes the release's version over the named path, discarding the local change, and re-creates it if it was locally deleted. The two are decided per path and compose on one call: without `--keep-local`, a locally changed path that no `--take-release` names still aborts the run. A `--take-release` path that this run does not report as locally changed is refused, in a `--dry-run` as well as a writing run - it is a mistake in the argument rather than a state of the tree, and a path that silently did nothing would report a successful upgrade while keeping the change it was asked to discard. After a `--keep-local` run the new stamp is still written whole, so it records the release's digest for files that were deliberately *not* written: the stamp is the baseline for the next comparison, not a literal inventory of what is on disk. That is what keeps a skipped file diverging - and therefore reported - on every later run, rather than quietly reading as current once it has been skipped once. A path taken with `--take-release` is the opposite case and the reason the flag exists: it was written, so it matches the digest the stamp records and stops being reported at all. A path in the old stamp but not the new one is reported as no longer part of the release and left alone unless `--prune` is passed, which removes it only if it is still unchanged since installation. Reports the migration chain the new machinery would owe (`chemenu.kb_state.chain` over the *new* tree's `instructions/migrations/`, read via a `directory` argument to `load_migrations`) but never runs any of it - there is no `migrate run`. Refuses before touching the source at all when: `VERSION` or `.wikitool-release.json` (with a `files` block) is missing locally, `.wikitool-kb.json` is missing, a migration is already outstanding against the *installed* machinery, or the working tree is dirty (not being a git repository at all is a WARN, not a refusal). Refuses after reading the source when: it carries no `VERSION`/`.wikitool-release.json`/`files` block, its version is older than or equal to the installed one (equal is a no-op success), it is a pre-release (`-beta.N`) without `--pre`, or `--take-release` names a path this run does not classify as locally changed. Reports, but does not block on, a crossed compatibility boundary. Never touches git - no commit, no push (invariant 5). The closing report carries no step list of its own: everything after the swap is one order, written in `instructions/upgrade-instance.md`, which the report names and which resumes at `instructions sync`. What a human decides *before* the swap - which release, whether to take it, where the tarball comes from - is `INSTALL.md` § "Version und Updates" |
 | `version show [--json]` | Print this instance's stack version and where it came from (development tree, or a distribution with its export date and origin). Bare `wikitool version` is an alias for this. Read-only, offline, and **exempt from the Iteration Budget Gate** |
-| `version check [--url U] [--timeout S] [--json]` | Ask the origin's release feed whether a newer stack exists, and whether the step crosses a compatibility boundary (`state: current\|update\|migration\|ahead`). **The only command in `wikitool` that makes a network call** - never reached implicitly from another command, needs no key, times out, and reports an unreachable feed as an error rather than as "up to date". The feed is `$WIKITOOL_UPDATE_URL`, else the release stamp's, else the built-in origin; `$WIKITOOL_UPDATE_TOKEN` is only needed if that feed is not readable anonymously. Read-only and exempt from the budget gate |
+| `version check [--url U] [--timeout S] [--json]` | Ask the origin's release feed whether a newer stack exists, and whether the step crosses a compatibility boundary (`state: current\|update\|migration\|ahead`). One of the **two** commands in `wikitool` that make a network call, and the only one whose whole job it is - `version notes` is the other, and only on a distributed instance. Never reached implicitly from another command, needs no key, times out, and reports an unreachable feed as an error rather than as "up to date". The feed is `$WIKITOOL_UPDATE_URL`, else the release stamp's, else the built-in origin; `$WIKITOOL_UPDATE_TOKEN` is only needed if that feed is not readable anonymously. Read-only and exempt from the budget gate |
-| `version notes [--version X.Y.Z]` | Print one version's `CHANGES.md` entry, for use as release notes (default: this tree's `VERSION`). Read-only and exempt from the budget gate |
+| `version notes [--version X.Y.Z] [--offline] [--url U] [--timeout S]` | Print one version's release notes (default: this tree's `VERSION`): the `CHANGES.md` entry where there is one, and where there is not, the feed's latest release notes. The fallback exists because an instance's `CHANGES.md` is a stub `dist upgrade` never overwrites (`chemenu.ownership.is_upgrade_preserved`), so the local file can never carry the entry - not today and not after any future release, which made the command permanently unanswerable exactly where the release notes are most needed. It is reached **only with a release stamp present**, i.e. only from a `dist export` tree: a dev checkout keeps the plain error, which is what keeps the origin repo and CI offline. **stdout carries nothing but the notes**; the line naming the feed being asked, and the one naming the release that answered, go to stderr - `release.yml` redirects stdout into the file it posts as the release body. Only the feed's *latest* release can be asked for (`update_url` is the one URL a stamp records, and composing a by-tag URL out of it would be guessing at an API shape), so a returned version other than the one asked for is named on stderr and printed anyway - the expected shape before an upgrade, where `VERSION` still names the release being left. `--offline` refuses the call and fails with the stamp's `release_url` instead. Read-only and exempt from the budget gate |
 | `version bump --major\|--minor\|--patch --title "<...>" [--impact high\|medium\|low] [--breaking "<what breaks>"] [--no-migration "<reason>"] [--migration-required] [--dry-run]` | Raise or continue the **one running candidate** between two releases - `VERSION` gets a `-beta.N` suffix, never a second fresh number per bump. `--major/--minor/--patch` is **max-wins escalation** against the last release (patch < minor < major): a `--patch` on a MINOR candidate only advances `N`, and escalation never steps back down. Opens the matching `CHANGES.md` entry on the first bump of a candidate (heading, date, author, and a machine-managed `<!-- wikitool:bumps -->` list of every `--title` collected so far, graded by `--impact`, default `medium`) and updates that same entry in place on every later bump of the same candidate - one entry per candidate, not one per bump. The list renders grouped under `**High/Medium/Low impact**` headings (empty groups omitted), except when every bump so far is `medium`, where it stays the flat, ungrouped list the region always had - `version regrade` corrects a grade after the fact. Refuses more or fewer than one part, an empty title, an unknown `--impact`, and a `VERSION`/newest-changelog-entry mismatch. Compatibility follows the **leftmost non-zero component** of the candidate's base, which for this stack (at `1.0.0` and up) means MAJOR: PATCH is a fix, MINOR a compatible capability, MAJOR a version that is **not a drop-in replacement** - any hand-work on update, or a downgrade that no longer works. Whether content must be migrated is a second, independent question. The bump that first escalates a candidate past the boundary requires `--breaking "<what stops working>"` and, on top of it, a migration document targeting the candidate's base or `--no-migration "<reason>"`; both are anchored just above the bump list, persist over later bumps of the same candidate without being repeated, and are refused on a bump that crosses nothing at all. The two then behave differently on a *second* crossing, because they answer different questions: a further `--breaking` **joins** the ones already recorded (one reason per crossing - rendered flat on the marker line while there is only one, as bullets under a bare marker from the second onward, and repeating a reason verbatim is a no-op), while a further `--no-migration` **replaces** the single line that says whether content has to change. A candidate crossing the boundary twice is the normal shape of a long-running one, and each crossing is a separate thing an operator has to act on; whether content migrates stays one yes/no about the candidate as a whole. There is deliberately no retraction path for a single accumulated `--breaking` reason - `--migration-required` retracts the migration line, and nothing retracts a breaking one. A later bump of the same candidate that finds out `--no-migration` was wrong after all retracts that line with `--migration-required` instead of restating `--no-migration` - refused without a migration document already targeting the new base, and without an existing `--no-migration` line to retract. Which part a change earns stays a judgment call: the command enforces that a crossing documents itself, never that the part was chosen correctly |
 | `version regrade [INDICES...] [--impact high\|medium\|low]` | List the running candidate's bump titles with their impact grade and 1-based rendered position (no arguments - the correction path for a `--impact` judgement made at bump time), or change one or more of them in a single call: `version regrade 3 7 --impact high` grades both against a single read of today's list, not position 3 first and then position 7 against whatever that produced. Touches only the topmost entry's bump list - never `VERSION`, never any other part of `CHANGES.md`. The bare listing is read-only and exempt from the Iteration Budget Gate, like `version notes`; a call with indices writes `CHANGES.md` and is counted like `version bump`. Refuses an index outside the rendered list's range, an unknown `--impact`, indices given without `--impact`, a missing `VERSION`/`CHANGES.md`, a `VERSION`/newest-changelog-entry mismatch, or a topmost entry with no bump list at all |
 | `version release [--title "<...>"] [--dry-run]` | Fix the running candidate: strip `VERSION`'s `-beta.N` suffix and close its `CHANGES.md` entry, ending the pre-release phase `version bump` started. Without `--title` the heading keeps whichever bump last set it; with it, the heading's title is replaced - the normal case for a candidate that collected several bump titles, since the entry wants a summarising heading rather than the most recent one. Leaves the entry's machine-managed bump-title list untouched, as the record of what happened. Refuses when the candidate collected two or more bumps and the entry still carries no summary paragraph (at least 200 non-whitespace characters) between the bump list and the first `### <bump title>` changeset heading; a candidate with exactly one bump is exempt, since there its own changeset already is the summary. `--dry-run` runs this check too and reports the same refusal. Commits nothing and pushes nothing (invariant 5) - the following `publish` moves `VERSION` onto `main`, which `release.yml` reacts to. Refuses when `VERSION` is already a release (no running candidate to fix), or when the changelog's newest entry does not match `VERSION` |
@@ -214,7 +214,7 @@ tools/wikitool <command> --help
 | Command | Purpose |
 |---------|---------|
-| `doctor [--json]` | Check that this instance is correctly configured: dependencies (Python, ripgrep), author resolution, stack version, git identity/branch/remote, published skills, kb/raw/reports/work/instructions structure, personalization (`USER.md`/`SOUL.md` present **and** filled - a file still carrying the template's sentinel is a `FAIL`, since a renamed template is not a filled one), the KB conventions (`kb/CONVENTIONS.md` present, unsentinelled, and naming all three tool-owned section headings - a `FAIL` on any of the three, because `xref`/`cite` write out of it), the environment note (`ENVIRONMENT.md` - optional, so absent is `OK`; a still-templated one is a `WARN`), generated files, whether the MCP `submit` tool is armed (`.wikitool-upload.json` present/absent/malformed, its limits, and how many submissions are waiting in `mcp-upload/` - absent is `OK` and means the write path does not exist at all, malformed is the one `FAIL` here, since a broken opt-in must not silently disable the limits it exists to enforce), `WIKITOOL_SESSION_ID`, and telemetry state (on/off, why - installation-form default, `.wikitool-telemetry.json`, or `WIKI_TRACE` - and the current session count/byte total against both caps; never `FAIL`, see [EVALS.md](../EVALS.md)). Read-only, exit 1 only on a `FAIL` (a missing remote, session id, or `VERSION` is a `WARN`, not a fault). Exempt from the Iteration Budget Gate |
+| `doctor [--json]` | Check that this instance is correctly configured: dependencies (Python, ripgrep), author resolution, stack version, git identity/branch/remote, published skills, kb/raw/reports/work/instructions structure, personalization (`USER.md`/`SOUL.md` present **and** filled - a file still carrying the template's sentinel is a `FAIL`, since a renamed template is not a filled one), the KB conventions (`kb/CONVENTIONS.md` present, unsentinelled, and naming all three tool-owned section headings - a `FAIL` on any of the three, because `xref`/`cite` write out of it), the environment note (`ENVIRONMENT.md` - optional, so absent is `OK`; a still-templated one is a `WARN`), generated files, whether the MCP `submit` tool is armed (`.wikitool-upload.json` present/absent/malformed, its limits, and how many submissions are waiting in `mcp-upload/` - absent is `OK` and means the write path does not exist at all, malformed is the one `FAIL` here, since a broken opt-in must not silently disable the limits it exists to enforce), the session id source (`OK` for `WIKITOOL_SESSION_ID` or a registered harness variable, `WARN` only for the bare parent-pid fallback - see `chemenu.session`), and telemetry state (on/off, why - installation-form default, `.wikitool-telemetry.json`, or `WIKI_TRACE` - and the current session count/byte total against both caps; never `FAIL`, see [EVALS.md](../EVALS.md)). Read-only, exit 1 only on a `FAIL` (a missing remote, session id, or `VERSION` is a `WARN`, not a fault). Exempt from the Iteration Budget Gate |
 ## Design notes
@@ -268,9 +268,12 @@ tools/wikitool <command> --help
  section): every invocation is recorded and checked in `main()` (`cli.py`)
  before Typer dispatches to any subcommand, so it applies uniformly without
  each command needing its own opt-in. State lives in the gitignored
-  `tools/.wikitool_session/budget.json`, keyed by `WIKITOOL_SESSION_ID` (or
+  `tools/.wikitool_session/budget.json`, keyed by `chemenu.session`'s fallback
-  the caller's parent process id as a fallback), so a new terminal/session
+  chain (`WIKITOOL_SESSION_ID`, else a registered harness session variable,
-  starts with a clean budget. Default ceiling: 60 calls/session, or 3
+  else the caller's parent process id), so a new terminal/session starts with
  a clean budget - and a bucket whose recorded origin no longer matches the
  current one starts a fresh count rather than inheriting a stranger's.
  Default ceiling: 60 calls/session, or 3
  identical calls in a row (whichever trips first). A call that left through
  `_util.fail()` - a rejected argument, or a read-only check reporting
  findings - is refunded: it declined instead of acting, and the contract's own
@@ -396,10 +399,10 @@ is atomic, and whether a retry is safe.
 | Command | Exit 1 means | Atomic? | Retry policy |
 |---------|--------------|---------|--------------|
 | `dist export` | Target exists and is not empty, is not a directory, or the tree has no readable `VERSION` | Yes - nothing is written until every file is planned | Point `<target>` at an empty (or new) directory and retry. Never merge into a non-empty one by hand |
-| `dist upgrade` | Missing local `VERSION`/`.wikitool-release.json`(`files`)/`.wikitool-kb.json`, a migration already outstanding against the installed machinery, a dirty working tree, a source with no `VERSION`/stamp/`files` block, a source version that is older than, equal to, or (without `--pre`) a pre-release relative to the installed one, or one or more locally changed files without `--keep-local` | **Yes for the refusal cases above - nothing is written.** Once writing starts it is a plain sequential file copy with no partial-state cleanup: an interruption mid-copy (killed process, disk full) can leave the tree part-old, part-new | For every refusal above: fix the named precondition and retry - none of them are transient. For locally changed files: reconcile them by hand and retry, or re-run with `--keep-local` to proceed and leave them untouched (repeatable - it reports the same files again on every subsequent run until they stop diverging). An interrupted write is not resumed automatically; compare the tree against the printed classification and finish or revert by hand |
+| `dist upgrade` | Missing local `VERSION`/`.wikitool-release.json`(`files`)/`.wikitool-kb.json`, a migration already outstanding against the installed machinery, a dirty working tree, a source with no `VERSION`/stamp/`files` block, a source version that is older than, equal to, or (without `--pre`) a pre-release relative to the installed one, a `--take-release` path that is not classified as locally changed (the one refusal a `--dry-run` also raises), or one or more locally changed files that neither `--keep-local` nor a `--take-release` answers for | **Yes for the refusal cases above - nothing is written.** Once writing starts it is a plain sequential file copy with no partial-state cleanup: an interruption mid-copy (killed process, disk full) can leave the tree part-old, part-new | For every refusal above: fix the named precondition and retry - none of them are transient. For a rejected `--take-release` path: correct it against the locally-changed list the refusal prints. For locally changed files, the refusal names all three answers with the re-run line filled in - `--take-release <path>` to write the release's version over it (which ends the divergence), `--keep-local` to leave them untouched (repeatable, and it reports the same files again on every subsequent run until they stop diverging), or reconcile by hand and retry. An interrupted write is not resumed automatically; compare the tree against the printed classification and finish or revert by hand |
 | `version show` | `VERSION` is missing or unparseable | Read-only | Fix `VERSION` and retry |
 | `version check` | The feed could not be reached, answered non-JSON, or carried no `tag_name`. **Never** answers "up to date" for a question it could not ask | Read-only, no local writes | A network failure is transient - retry once, then report it. HTTP 401/403 names `$WIKITOOL_UPDATE_TOKEN`; 404 means no release exists yet or the URL points at the wrong repo |
-| `version notes` | An unparseable `--version`, an unreadable `VERSION` when `--version` is omitted, a missing `CHANGES.md`, or no entry naming the requested version | Read-only | Fix the named argument or file, then retry. Safe to retry |
+| `version notes` | An unparseable `--version`, an unreadable `VERSION` when `--version` is omitted, or a missing `CHANGES.md`. No entry for the requested version is an error only where the feed cannot answer either: in a tree with no release stamp (a dev checkout - write the entry, or `version bump`), with `--offline`, or when the feed could not be reached or returned a release with an empty `body`. Every one of those failures names the stamp's `release_url` where it has one, so a run that cannot read the notes is still told where they are | Read-only | Fix the named argument or file, then retry. A feed failure is transient - retry once, then read the release page the error names. Safe to retry |
 | `version bump` | More or fewer than one of `--major/--minor/--patch`, an empty `--title`, an unknown `--impact`, a missing `VERSION`/`CHANGES.md`, `VERSION` and the changelog's newest entry naming different versions, an escalation to a boundary crossing without `--breaking` or with neither a migration document nor `--no-migration`, `--breaking`/`--no-migration` on a bump that crosses nothing, or `--migration-required` combined with `--no-migration`, on a bump with no running candidate, with no `--no-migration` line to retract, or without a migration document already targeting the new base | No - `VERSION` then `CHANGES.md` | **Not idempotent**: a second run escalates or continues the candidate again. If the outcome is uncertain, read `VERSION` and the top of `CHANGES.md` before retrying |
 | `version regrade` | A missing `VERSION`/`CHANGES.md`, `VERSION` and the changelog's newest entry naming different versions, a topmost entry with no bump list, an index outside the rendered list's range, indices given without `--impact`, or an unknown `--impact` | No - `CHANGES.md` only, and only when indices are given | The bare listing never writes anything. A write is **not idempotent** against a changed list: re-running the same indices after a first success regrades whatever is at those positions *now*, which may no longer be the same bumps - list again before retrying |
 | `version release` | A missing `VERSION`/`CHANGES.md`, `VERSION` already a release (no running candidate), `VERSION` and the changelog's newest entry naming different versions, or (from two bumps on) an entry with no summary paragraph above the changesets | No - `VERSION` then `CHANGES.md` | **Not idempotent**: a second run fails outright once the suffix is gone. If the outcome is uncertain, read `VERSION` before retrying - a release-shaped `VERSION` means it already ran |
@@ -451,16 +454,7 @@ Run by the LLM through the skills, on this cadence:
 ## Future considerations (not implemented)
 - MCP server wrapper exposing these same commands as native tool calls for
  MCP-capable agents, instead of shell invocation.
 - A pre-commit hook running `wikitool lint --fail-on-error` before every
  `wikitool publish`. CI already runs it on every push
  (`.gitea/workflows/ci.yml`), which catches it after the fact rather than
  before.
 - `dist upgrade`: apply a newer release to an instance that already has
  content. `version check` detects that one exists and says whether it crosses
  a compatibility boundary; applying it is the manual procedure in
  [INSTALL.md](../INSTALL.md) § "Eine Instanz aktualisieren". The `files` block
  of `.wikitool-release.json` is the groundwork - it records what the machinery
  looked like at install time, which is the only way to tell a file the
  instance edited from one it merely received.
@@ -3,6 +3,8 @@
 The root AGENTS.md holds the invariants that say when these commands are
 mandatory; tools/CONTRACT.md is the full per-command reference.
 """
 import errno
 import os
 import sys
 import time
@@ -50,6 +52,82 @@ except ModuleNotFoundError as exc:
 from chemenu.telemetry import emit  # noqa: E402 - after the dependency check
 class _BrokenPipeSwallow:
    """Wraps a stream so a write into a closed pipe is dropped instead of
    raised - installed on `sys.stdout`/`sys.stderr` before Typer/Click ever
    run, so Click's own broken-pipe handling (`click.core.BaseCommand.main`)
    never gets the chance to fire.
    Why not just read Click's outcome afterwards: Click already catches this
    exact case (`OSError` with `errno.EPIPE`) and turns it into `sys.exit(1)`
    to avoid a traceback - a clean-looking exit, but indistinguishable from a
    real failure to whatever reads that exit code next. `cli._run_traced`
    does exactly that: it is the trace, which recorded a truncated-but-
    otherwise-successful `types describe source | head -1` as a tool error
    (Gitea #110, measured against a real trace: `exit_code: 1` for a call the
    very next, unpiped, retry of which showed `exit_code: 0`).
    Swallowing the write here instead means Click's own handler never
    triggers, so the command finishes through its normal exit path - `0` for
    an otherwise-successful run - and `sigpipe` on this wrapper is the signal
    `_run_traced` reads to note the truncation without miscasting it as an
    error.
    """
    def __init__(self, wrapped):
        self._wrapped = wrapped
        self.sigpipe = False
    def _is_epipe(self, exc: OSError) -> bool:
        return exc.errno == errno.EPIPE
    def write(self, data):
        try:
            return self._wrapped.write(data)
        except OSError as exc:
            if not self._is_epipe(exc):
                raise
            self.sigpipe = True
            return len(data)
    def flush(self):
        try:
            self._wrapped.flush()
        except OSError as exc:
            if not self._is_epipe(exc):
                raise
            self.sigpipe = True
    def __getattr__(self, attr):
        return getattr(self._wrapped, attr)
 def _pacify_real_fd(stream) -> None:
    """Redirect a broken stream's real file descriptor to `os.devnull`.
    Swallowing the write in `_BrokenPipeSwallow` is not enough on its own:
    CPython still flushes the *real* underlying stream automatically at
    interpreter shutdown, by code this module does not control, and that
    flush hits the same closed pipe - printing "Exception ignored while
    flushing sys.stdout" (the well-known CPython caveat; see the standard
    library docs' "Note on SIGPIPE"). Once a pipe is known broken there is
    nothing left worth writing to it, so pointing the fd at `/dev/null`
    makes every later flush - ours or the interpreter's own - a normal
    write that always succeeds.
    """
    try:
        devnull = os.open(os.devnull, os.O_WRONLY)
        try:
            os.dup2(devnull, stream.fileno())
        finally:
            os.close(devnull)
    except (OSError, AttributeError):
        # AttributeError: a stream with no real fd at all (a test double, or
        # a harness that already replaced sys.stdout with something that
        # isn't a file) - nothing to redirect, same as the OSError case.
        pass
 app = typer.Typer(
    help="wikitool - deterministic operations for Chemenu (see AGENTS.md).",
    no_args_is_help=True,
@@ -127,6 +205,10 @@ def _run_traced(command: str, args: list[str], charged: bool = False) -> None:
    """
    started = time.monotonic()
    exit_code = 0
    real_stdout, real_stderr = sys.stdout, sys.stderr
    stdout_wrap = _BrokenPipeSwallow(real_stdout)
    stderr_wrap = _BrokenPipeSwallow(real_stderr)
    sys.stdout, sys.stderr = stdout_wrap, stderr_wrap
    try:
        app()
    except SystemExit as exc:
@@ -137,18 +219,22 @@ def _run_traced(command: str, args: list[str], charged: bool = False) -> None:
        exit_code = 1
        raise
    finally:
        if stdout_wrap.sigpipe:
            _pacify_real_fd(real_stdout)
        if stderr_wrap.sigpipe:
            _pacify_real_fd(real_stderr)
        sys.stdout, sys.stderr = real_stdout, real_stderr
        if charged and _util.declined():
            run_budget.refund()
-        emit(
+        attrs = {
-            "wikitool",
+            "command": command,
-            "wikitool.call",
+            "args": args,
-            {
+            "exit_code": exit_code,
-                "command": command,
+            "duration_ms": round((time.monotonic() - started) * 1000, 1),
-                "args": args,
+        }
-                "exit_code": exit_code,
+        if stdout_wrap.sigpipe or stderr_wrap.sigpipe:
-                "duration_ms": round((time.monotonic() - started) * 1000, 1),
+            attrs["stdout_truncated"] = True
-            },
+        emit("wikitool", "wikitool.call", attrs)
        )
 if __name__ == "__main__":
@@ -179,7 +179,7 @@ def rel_path(path: Path) -> str:
 def check_collision(name: str) -> None:
-    """Fail if any page under wiki/ already has `name` as its filename stem.
+    """Fail if any page under kb/ already has `name` as its filename stem.
    The stem *is* the page title and wikilinks resolve by title alone, so two
    files sharing a stem in different directories are indistinguishable to
@@ -38,7 +38,7 @@ app = typer.Typer(help="Manage [^cite-id] footnote citations and their Footnotes
 def _find_page(pages: dict[str, Page], title: str) -> Page:
    if title not in pages:
-        fail(f"No page titled '{title}' found under wiki/.")
+        fail(f"No page titled '{title}' found under kb/.")
    return pages[title]
@@ -100,7 +100,7 @@ def cite_add(
    pages = load_kb_pages(config.KB_DIR)
    page = _find_page(pages, page_title)
    if source not in pages:
-        fail(f"No page titled '{source}' found under wiki/ - citing a page that doesn't exist would be a dangling reference.")
+        fail(f"No page titled '{source}' found under kb/ - citing a page that doesn't exist would be a dangling reference.")
    marker_id, new_body, changed = upsert_citation(page, source, file)
    marker = f"[^{marker_id}]"
@@ -159,7 +159,7 @@ def sync_page(page: Page) -> tuple[str, bool, list[str], list[str]]:
@app.command("sync")
 def cite_sync(
    page_title: Optional[str] = typer.Option(None, "--page", help="Sync just this page"),
-    all_pages: bool = typer.Option(False, "--all", help="Sync every page under wiki/"),
+    all_pages: bool = typer.Option(False, "--all", help="Sync every page under kb/"),
    dry_run: bool = typer.Option(False, "--dry-run", help="Report what would change instead of writing"),
 ):
    """Prune orphan Footnotes definitions and re-render each page's block in
@@ -41,7 +41,7 @@ import tempfile
 from contextlib import contextmanager
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Callable, NamedTuple, Optional, Union
+from typing import Callable, NamedTuple, Optional, Sequence, Union
 import typer
@@ -659,8 +659,11 @@ def run_export(target: Path, dry_run: bool = False, origin: Optional[Origin] = N
 # (`ownership.is_export_stub`, `ownership.is_upgrade_preserved`), plus the
 # stamp itself. Every candidate path is classified against the *old* stamp's
 # recorded digest - unchanged, locally modified, or locally deleted - and a
-# modified/deleted file is never silently overwritten. This never calls a
+# modified/deleted file is never silently overwritten: the run aborts unless
-# release feed; the caller supplies an already-downloaded tree or archive.
+# `--keep-local` keeps it or `--take-release <path>` names it, which is the
 # difference between a file the instance means to carry and one that drifted.
 # This never calls a release feed; the caller supplies an already-downloaded
 # tree or archive.
@dataclass(frozen=True)
@@ -802,12 +805,68 @@ def _git_working_tree_status() -> Optional[str]:
    return result.stdout if result.returncode == 0 else None
 def _resolve_take_release(
    take_release: Optional[Sequence[str]], classification: FileClassification
 ) -> set[str]:
    """The blocked paths `--take-release` names, refusing any that is not
    actually blocked.
    A path that silently does nothing is the worse answer: the operator asked
    for a local change to be discarded and would be told the upgrade went
    fine, having kept it. Checked before `--dry-run` returns, so a typo
    surfaces in the preview rather than in the writing run."""
    if not take_release:
        return set()
    blocked = set(classification.blocked)
    wanted = {path.strip() for path in take_release if path.strip()}
    unknown = sorted(wanted - blocked)
    if unknown:
        listed = "\n".join(f"  - {path}" for path in classification.blocked) or "  (none)"
        fail(
            f"--take-release names {len(unknown)} path(s) that are not locally changed: "
            f"{', '.join(unknown)}. Only a path this run reports as locally modified or "
            f"locally deleted can be taken from the release. Reported as locally changed:\n"
            f"{listed}"
        )
        return set()  # unreachable: fail() raises typer.Exit
    return wanted
 def _refusal_for_blocked(
    source: Path, undecided: list[str], classification: FileClassification
 ) -> str:
    """The abort text for blocked paths no flag has answered for.
    It spells all three answers out with a ready-to-paste command line -
    the same shape the Mass-Update Gate uses for its `--confirm` line -
    because the one thing a reader must not take away is that any of them is
    the default. A run on a real instance read the old wording, which named
    only `--keep-local` and "reconcile by hand", as "the default takes the
    release's version" and called the command with no flag at all."""
    paths = " ".join(undecided)
    kept_again = (
        "they are reported again on every future upgrade"
        if len(classification.blocked) > 1
        else "it is reported again on every future upgrade"
    )
    return (
        f"{len(undecided)} locally changed file(s) (listed above) would be silently "
        f"overwritten. Nothing was written, and none of these three is the default:\n"
        f"  - take the release's version and discard the local change:\n"
        f"      dist upgrade {rel_path(source)} --take-release {paths}\n"
        f"  - keep every local change and upgrade around them ({kept_again}):\n"
        f"      dist upgrade {rel_path(source)} --keep-local\n"
        f"  - reconcile them by hand first, then re-run."
    )
 def _report_plan(
    classification: FileClassification,
    migration_chain: list["kb_state.Migration"],
    boundary_crossing: bool,
    local_version: "version_mod.Version",
    new_version: "version_mod.Version",
    taken: set[str] = frozenset(),
 ) -> None:
    console.print(f"{local_version} -> {new_version}")
    if boundary_crossing:
@@ -821,14 +880,18 @@ def _report_plan(
        f"{len(classification.blocked)} locally changed, {len(classification.removed)} removed "
        "from the release."
    )
    def _mark(relative: str) -> str:
        return " [cyan](--take-release: overwritten from the release)[/cyan]" if relative in taken else ""
    if classification.modified:
        console.print(f"[bold]Locally modified ({len(classification.modified)}):[/bold]")
        for relative in classification.modified:
-            console.print(f"  - {relative}")
+            console.print(f"  - {relative}{_mark(relative)}")
    if classification.deleted:
        console.print(f"[bold]Locally deleted ({len(classification.deleted)}):[/bold]")
        for relative in classification.deleted:
-            console.print(f"  - {relative}")
+            console.print(f"  - {relative}{_mark(relative)}")
    if classification.removed:
        console.print("[dim]No longer part of the release, not written or removed by default:[/dim]")
        for relative in classification.removed:
@@ -855,6 +918,13 @@ def upgrade_command(
        False, "--keep-local",
        help="Proceed even with locally changed files - leave each one untouched rather than aborting",
    ),
    take_release: list[str] = typer.Option(
        None, "--take-release",
        help="Overwrite this locally changed path with the release's version, discarding the local "
        "change. Repeatable, and each path must be one this run reports as locally changed. The "
        "counterpart to --keep-local, which keeps the change and reports it again on every future "
        "upgrade",
    ),
    prune: bool = typer.Option(
        False, "--prune",
        help="Also delete files the new release no longer ships, if they are unchanged since install",
@@ -872,13 +942,20 @@ def upgrade_command(
    against the *old* stamp's recorded digest: unchanged files are
    overwritten silently, new files are created, and a locally modified or
    deleted file is never silently overwritten - `dist upgrade` aborts unless
-    `--keep-local` says to leave it alone. Reports the migration chain the new
+    `--keep-local` says to leave it alone or `--take-release <path>` names it
    as one to overwrite from the release. Reports the migration chain the new
    machinery would owe without running any of it (there is no `migrate run`).
    Refuses on a missing local release stamp, a downgrade, a pre-release
-    source without `--pre`, or a dirty working tree. Never touches git.
+    source without `--pre`, a dirty working tree, or a `--take-release` path
    that is not locally changed. Never touches git.
    See Gitea #7 and `INSTALL.md` § "Eine Instanz aktualisieren"."""
    run_upgrade(
-        source, dry_run=dry_run, keep_local=keep_local, prune=prune, allow_pre=allow_pre
+        source,
        dry_run=dry_run,
        keep_local=keep_local,
        take_release=take_release,
        prune=prune,
        allow_pre=allow_pre,
    )
@@ -886,6 +963,7 @@ def run_upgrade(
    source: Path,
    dry_run: bool = False,
    keep_local: bool = False,
    take_release: Optional[Sequence[str]] = None,
    prune: bool = False,
    allow_pre: bool = False,
 ) -> None:
@@ -993,26 +1071,29 @@ def run_upgrade(
        )
        boundary_crossing = local_version.compat_key != new_version.compat_key
-        _report_plan(classification, migration_chain, boundary_crossing, local_version, new_version)
+        taken = _resolve_take_release(take_release, classification)
        _report_plan(
            classification, migration_chain, boundary_crossing, local_version, new_version, taken
        )
        # Dry-run's whole purpose is to preview this classification - including
        # the blocked list - without raising, so it must be checked before the
        # abort below rather than after: a blocked file must never turn
        # `--dry-run` into a non-zero exit, or the flag stops being safe to run
-        # freely.
+        # freely. A bad `--take-release` path is the other way round: it is a
        # mistake in the *argument*, not a state of the tree, so it is resolved
        # above this line and does exit non-zero here - catching a typo in the
        # preview is the whole point of previewing.
        if dry_run:
            success(f"Dry run: would upgrade {local_version} -> {new_version}. Nothing written.")
            return
-        if classification.blocked and not keep_local:
+        undecided = [path for path in classification.blocked if path not in taken]
-            fail(
+        if undecided and not keep_local:
-                f"{len(classification.blocked)} locally changed file(s) (listed above) would be "
+            fail(_refusal_for_blocked(source, undecided, classification))
                "silently overwritten. Pass --keep-local to upgrade anyway and leave every one of "
                "them untouched, or reconcile them by hand first. Nothing was written."
            )
            return
-        to_write = sorted(classification.unchanged + classification.new)
+        to_write = sorted(classification.unchanged + classification.new + sorted(taken))
        for relative in to_write:
            src = new_root / relative
            dst = config.ROOT / relative
@@ -1034,9 +1115,10 @@ def run_upgrade(
                    target.unlink()
                    pruned.append(relative)
-    skipped = classification.blocked if keep_local else []
+    skipped = undecided if keep_local else []
    summary = (
        f"Upgraded {local_version} -> {new_version}: {len(to_write)} file(s) written"
        + (f", {len(taken)} taken from the release (--take-release)" if taken else "")
        + (f", {len(skipped)} left untouched (--keep-local)" if skipped else "")
        + (f", {len(pruned)} pruned" if pruned else "")
        + "."
@@ -1045,8 +1127,13 @@ def run_upgrade(
        summary += (
            f" {len(migration_chain)} migration(s) now outstanding - run `wikitool migrate status`."
        )
    # One pointer rather than a second copy of the order: the steps after the
    # swap live in instructions/upgrade-instance.md, which ships with every
    # instance. Naming the resume *command* rather than a step number keeps this
    # line correct when that file's numbering moves.
    summary += (
-        " Nothing was committed. Now run, in order: `wikitool instructions sync`, `doctor`, "
+        " Nothing was committed and nothing is verified yet."
-        "`docs verify`, `instructions verify`, `lint` - then restart the agent session."
+        " `instructions/upgrade-instance.md` carries the order for everything that follows"
        " and resumes at `wikitool instructions sync`."
    )
    success(summary)
@@ -511,11 +511,13 @@ def check_toc_regions() -> list[str]:
 MARKDOWN_LINK_RE = re.compile(r"\[[^\]]*\]\(([^)\s]+)\)")
 # The suffix `dist export` re-keys an instance-owned file to, and the one
-# `setup-instance.md` renames away again. Spelled here rather than imported
+# `setup-instance.md` renames away again. Imported from `toc` rather than
-# from `ownership`, whose own `.template` handling answers a different
+# spelled again here: that module already decides which files are reference
-# question (which side an upstream merge keeps) over a narrower scope
+# material in both their forms, and this check runs over its scope. Not from
-# (paths under a content stage).
+# `ownership`, whose own `.template` handling answers a different question
-TEMPLATE_SUFFIX = ".template"
+# (which side an upstream merge keeps) over a narrower scope (paths under a
 # content stage).
 TEMPLATE_SUFFIX = toc.TEMPLATE_SUFFIX
 def is_external_or_anchor(target: str) -> bool:
@@ -24,6 +24,7 @@ from chemenu import config, conventions, kb_collections, version as version_mod
 from chemenu.commands import git_publish, instructions_cmd
 from chemenu.commands._util import rel_path
 from chemenu.session import ENV_VAR as SESSION_ENV_VAR
 from chemenu.session import session_id_source as _session_id_source
 console = Console()
@@ -414,12 +415,23 @@ def check_upload_intake() -> Check:
 def check_session_id() -> Check:
    """Three-valued, not two: an explicit `WIKITOOL_SESSION_ID` and a
    recognised harness variable (see `chemenu.session.HARNESS_ENV_VARS`) both
    keep a session's calls in one telemetry/budget bucket, so both are `OK`.
    Only the `getppid()` fallback - a fresh "session" on every call, on a
    harness that runs each tool call in its own shell - is a `WARN` (see
    Gitea #110)."""
    import os
    if os.environ.get(SESSION_ENV_VAR, "").strip():
        return Check("session-id", "OK", f"{SESSION_ENV_VAR}={os.environ[SESSION_ENV_VAR]}")
    source = _session_id_source()
    if source != "getppid() fallback":
        return Check("session-id", "OK", f"scoped by harness variable {source}")
    return Check(
-        "session-id", "WARN", f"{SESSION_ENV_VAR} is not set - budget falls back to the parent PID",
+        "session-id", "WARN",
        f"{SESSION_ENV_VAR} is not set and no harness session variable was found - "
        "budget falls back to the parent PID",
        "See instructions/session-setup.md",
    )
@@ -14,7 +14,7 @@ whose push failed leaves a real, unpushed commit sitting on the branch, and
 the next `publish` now pushes it instead of reporting "Nothing to commit"
 forever.
-Also implements the Mass-Update Gate (wiki/concepts/Mass-Update Gate.md):
+Also implements the Mass-Update Gate (kb/concepts/workflows/Mass-Update Gate.md):
 a push to origin/main is the one action in this system with a real,
 irreversible external effect (publicly visible commit history, possible CI
 triggers, other clients pulling). Small/normal publishes (< threshold
@@ -1,4 +1,4 @@
-"""Append correctly-formatted entries to wiki/log.md."""
+"""Append correctly-formatted entries to kb/log.md."""
 from __future__ import annotations
 import re
@@ -10,7 +10,7 @@ import typer
 from chemenu import config
 from chemenu.commands._util import fail, rel_path, success, today_iso
-app = typer.Typer(help="Manage wiki/log.md.")
+app = typer.Typer(help="Manage kb/log.md.")
 VALID_OPS = ["ingest", "query", "lint", "create", "update", "delete", "rename", "move"]
@@ -74,7 +74,7 @@ def log_status():
    `lint` - the deterministic trigger for the Maintenance Schedule's "every
    10 sources" full-lint cadence. Read-only."""
    if not config.LOG_FILE.exists():
-        success("No wiki/log.md yet; nothing logged.")
+        success("No kb/log.md yet; nothing logged.")
        return
    entries = parse_log_entries(config.LOG_FILE.read_text(encoding="utf-8"))
    count = ingests_since_last_lint(entries)
@@ -11,6 +11,10 @@ deterministic and stored in /types/; the content is judgment and provided by the
 Frontmatter defaults, enum validity, and required-ness all come from the
 type's `.schema.yaml` (via `TypeResolver`) - nothing here re-declares them.
 A schema `default:` is materialized only for a field the schema also lists
 in `required:` - an optional field's default is a reader-side assumption
 (what a missing field means), and writing it into every scaffolded page
 would turn that assumption into a stated claim instead (Gitea #109).
 Directory placement for subtype-driven types (currently just entities) also
 comes from the type-spec, via its `layout:` frontmatter (see
 `TypeResolver.get_layout`) - not a hand-maintained Python dict.
@@ -74,12 +78,22 @@ def _build_frontmatter(
    `explicit` supplies every CLI-derived value the caller already has;
    fields not in `explicit` get a type-appropriate default (today's date for
    date-formatted fields, the scaffold placeholder for `summary`, the
-    schema's own `default:` where declared, an empty list for arrays), or are
+    schema's own `default:` where declared *and the field is required*, an
-    omitted entirely if optional with no sensible default (e.g.
+    empty list for arrays), or are omitted entirely if optional with no
-    `source_url`). This is what lets frontmatter shape - and scaffold-time
+    sensible default (e.g. `source_url`). This is what lets frontmatter
-    defaults like `provenance: general` - follow the schema instead of being
+    shape - and scaffold-time defaults like `provenance: general` - follow
-    hand-declared per CLI command.
+    the schema instead of being hand-declared per CLI command.
    A `default:` on an *optional* field (e.g. `instruction.obligation`) is
    deliberately not materialized here: it documents what a reader should
    assume when the field is absent, not what the scaffold should write.
    Writing it anyway turned every scaffolded instruction into one that
    falsely claims `obligation: required` - a migration-only field - and
    the same read/write distinction is what the schema's own `default:`
    doc-comment (`types/instruction.schema.yaml`) already draws (Gitea
    #109).
    """
    required = set((schema or {}).get("required") or [])
    frontmatter: Dict[str, Any] = {"type": type_path}
    for field_name, field_schema in (schema or {}).get("properties", {}).items():
        if field_name == "type":
@@ -105,7 +119,7 @@ def _build_frontmatter(
            frontmatter[field_name] = resolved_author
        elif field_schema.get("format") == "date":
            frontmatter[field_name] = today
-        elif "default" in field_schema:
+        elif "default" in field_schema and field_name in required:
            frontmatter[field_name] = field_schema["default"]
        elif field_schema.get("type") == "array":
            frontmatter[field_name] = []
@@ -236,7 +236,7 @@ def rename_command(
    if references_only:
        if new not in pages:
            fail(
-                f"Neither '{old}' nor '{new}' is a page under wiki/. Repointing references "
+                f"Neither '{old}' nor '{new}' is a page under kb/. Repointing references "
                f"to '{new}' would just move the dangling reference; create the page first "
                "with `wikitool new ...`, or drop the reference with `wikitool xref remove`."
            )
@@ -316,7 +316,7 @@ def rm_command(
    pages = load_kb_pages(config.KB_DIR)
    target = pages.get(page_title)
    if target is None:
-        fail(f"No page titled '{page_title}' found under wiki/.")
+        fail(f"No page titled '{page_title}' found under kb/.")
    inbound = inbound_pages(pages, page_title)
    if inbound and not yes:
@@ -404,7 +404,7 @@ def move_command(
        None, "--page", help="Exact title of the page to move to its computed location"
    ),
    reconcile: bool = typer.Option(
-        False, "--reconcile", help="Move every page under wiki/ that is not at its computed location"
+        False, "--reconcile", help="Move every page under kb/ that is not at its computed location"
    ),
    dry_run: bool = typer.Option(False, "--dry-run", help="List what would move without writing"),
 ):
@@ -475,7 +475,7 @@ def move_command(
    target = pages.get(page_title)
    if target is None:
-        fail(f"No page titled '{page_title}' found under wiki/.")
+        fail(f"No page titled '{page_title}' found under kb/.")
    type_path = target.frontmatter.get("type")
    if not type_path:
@@ -171,7 +171,7 @@ def build_provenance_index(kb_dir: Path, raw_dir: Path) -> str:
@app.command("rebuild-index")
 def rebuild_index(
-    dry_run: bool = typer.Option(False, "--dry-run", help="Print the result instead of writing wiki/provenance.md"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Print the result instead of writing kb/provenance.md"),
 ):
    content = build_provenance_index(config.KB_DIR, config.RAW_DIR)
    provenance_file = config.KB_DIR / "provenance.md"
@@ -382,7 +382,7 @@ def raw_accept_command(
        pages = load_kb_pages(config.KB_DIR)
        target_page = pages.get(page)
        if target_page is None:
-            fail(f"No page titled '{page}' found under wiki/. Create it first, or omit --page.")
+            fail(f"No page titled '{page}' found under kb/. Create it first, or omit --page.")
        existing_rel = source_raw_files(target_page)
        if not existing_rel:
            fail(
@@ -7,7 +7,7 @@ This closes the gap documented in AGENTS.md's "Gates" section: unlike a
 prompt instruction ("stop after N steps"), this check runs
 in-process on every `wikitool` invocation and cannot be skipped by the
 calling agent "politely trying again". It mirrors the Mass-Update Gate
-pattern (see git_publish.py / wiki/concepts/Mass-Update Gate.md), but that
+pattern (see git_publish.py / kb/concepts/workflows/Mass-Update Gate.md), but that
 gate is scoped to the *size* of a single publish, while this one is scoped to
 *iteration volume* across a whole session (e.g. a wiki-ingest or wiki-lint run
 that could otherwise loop unbounded over many entity/concept pages).
@@ -144,6 +144,27 @@ def _session_id_source() -> str:
    return _shared_session_id_source()
 def _entry_for(state: dict, session_id: str) -> dict:
    """The state entry for this session id, starting a fresh counter if the
    same id string now carries a different origin than the one that wrote it.
    Two different id spaces (a `getppid()` integer, a harness UUID, an
    explicit `WIKITOOL_SESSION_ID`) are vanishingly unlikely to collide as
    strings - but "unlikely" is not "impossible", and inheriting a stranger's
    count on collision is exactly the silent mis-key #110 exists to close.
    An entry written before this field existed carries no `source` at all and
    is treated as compatible: it keeps its count rather than being reset the
    first time this ships, which would throw away real, in-flight state.
    """
    source = _session_id_source()
    entry = state.get(session_id)
    if entry is None or (entry.get("source") is not None and entry["source"] != source):
        entry = {"count": 0, "recent": []}
        state[session_id] = entry
    entry.setdefault("source", source)
    return entry
 def _load_state() -> dict:
    if not STATE_FILE.exists():
        return {}
@@ -247,7 +268,7 @@ def record_and_check(
    with _state_lock():
        session_id = _session_id()
        state = _load_state()
-        entry = state.setdefault(session_id, {"count": 0, "recent": []})
+        entry = _entry_for(state, session_id)
        recent = entry["recent"]
        call_signature = f"{command} {' '.join(args)}".strip()
@@ -232,7 +232,7 @@ def touch_command(
    pages = load_kb_pages(config.KB_DIR)
    page = pages.get(page_title)
    if page is None:
-        fail(f"No page titled '{page_title}' found under wiki/. Create it first with `wikitool new ...`.")
+        fail(f"No page titled '{page_title}' found under kb/. Create it first with `wikitool new ...`.")
    type_path = page.frontmatter.get("type")
    if not type_path:
@@ -19,10 +19,16 @@ number means, and `instructions/dev/version-parts.md` for the candidate model):
  rendered list - the correction path for the judgment `version bump
  --impact` made at the time, per Gitea #95's fix for an unreadably long,
  ungraded bump list.
- `version check` is the one command in `wikitool` that makes a network call.
+- `version notes` prints one version's release notes. In a tree that writes
-  It is deliberately its own command: nothing else reaches for it implicitly,
+  its own `CHANGES.md` that is a mechanical extraction from it; on a
-  it needs no key, it times out, and a feed that cannot be reached is reported
+  *distributed* instance, whose `CHANGES.md` is a stub `dist upgrade` never
-  as an error rather than silently answered as "up to date".
+  overwrites, it falls back to the release feed, because otherwise the command
  can never answer there - not today and not after any future release.
 - `version check` and that fallback are the only two network calls in
  `wikitool`, and neither is implicit: `check` exists for the call, `notes`
  announces the URL on stderr before asking and takes `--offline`. Both need
  no key, both time out, and a feed that cannot be reached is reported as an
  error rather than silently answered as "up to date" or "no notes".
 """
 from __future__ import annotations
@@ -32,10 +38,18 @@ from typing import Optional
 import typer
 from rich.console import Console
 from chemenu import config, version as version_mod
 from chemenu.commands._util import console, fail, rel_path, success, today_iso
 from chemenu.version import Version, VersionError
 # `version notes` is the one command whose stdout is consumed by a machine -
 # `release.yml` redirects it into the file it posts as the release body - so
 # everything it says *about* the notes goes here instead of onto the same
 # stream as the notes themselves.
 err = Console(stderr=True)
 app = typer.Typer(
    help="Report, bump, and check the stack version (see tools/CONTRACT.md).",
    invoke_without_command=True,
@@ -169,13 +183,48 @@ def notes_command(
    version: Optional[str] = typer.Option(
        None, "--version", help="Which entry to print (default: this tree's VERSION)"
    ),
    offline: bool = typer.Option(
        False, "--offline",
        help="Never ask the release feed: on a distributed instance, whose CHANGES.md carries no "
        "entry to print, fail with the release page instead of fetching the notes",
    ),
    url: Optional[str] = typer.Option(
        None, "--url", help="Release feed to ask for the fallback (default: the stamp's, as `version check`)"
    ),
    timeout: float = typer.Option(10.0, "--timeout", help="Seconds to wait for the feed"),
 ):
-    """Print one version's `CHANGES.md` entry, for use as release notes.
+    """Print one version's release notes: the `CHANGES.md` entry where there is
    one, the installed release's notes from the feed on a distributed instance,
    where there never is.
    Mechanical extraction, so the release workflow never has to parse markdown
-    in shell."""
+    in shell - which is also why **stdout carries nothing but the notes** and
    every line about where they came from goes to stderr. `release.yml` does
    `version notes > /tmp/release-notes.md`.
    The fallback is reached only with a release stamp present, i.e. only from a
    tree that came out of `dist export`. A dev checkout keeps the plain error,
    so this command cannot make a network call in the origin repository or in
    CI. See `version_mod.fetch_latest_notes` for why only the feed's *latest*
    release can be asked for."""
    run_notes(version=version, offline=offline, url=url, timeout=timeout)
 def run_notes(
    version: Optional[str] = None,
    offline: bool = False,
    url: Optional[str] = None,
    timeout: float = 10.0,
    fetcher: Optional[version_mod.Fetcher] = None,
 ) -> None:
    """`version notes` itself, free of Typer's option objects - the same split
    `dist_cmd.run_export` makes, and for the same reason. `fetcher` is the
    network seam: a test passes one, nothing else does."""
    import os
    try:
        wanted = Version.parse(version) if version else version_mod.read_version()
        stamp = version_mod.read_stamp()
    except VersionError as exc:
        fail(str(exc))
        return
@@ -186,13 +235,65 @@ def notes_command(
        return
    section = version_mod.changes_section(changes.read_text(encoding="utf-8"), wanted)
-    if section is None:
+    if section is not None:
        typer.echo(section, nl=False)
        return
    release_url = str((stamp or {}).get("release_url") or "").strip()
    if stamp is None or offline:
        fail(_no_entry_message(wanted, stamp is not None, release_url))
        return
    feed = url or version_mod.update_url(stamp)
    token = os.environ.get(version_mod.UPDATE_TOKEN_ENV, "").strip() or None
    err.print(
        f"[dim]{version_mod.CHANGES_FILENAME} has no entry for {wanted} - a distributed instance "
        f"receives it as a stub. Asking {feed}[/dim]"
    )
    try:
        latest, body, page = version_mod.fetch_latest_notes(feed, token, timeout, fetcher)
    except VersionError as exc:
        fail(
            f"{exc}. The notes for {wanted} are on the release page instead: "
            f"{release_url or '(no release_url in the release stamp)'}"
        )
        return
    if latest == wanted:
        err.print(f"[dim]These are {latest}'s notes, from {page or feed}[/dim]")
    else:
        err.print(
            f"[yellow]These are {latest}'s notes, not {wanted}'s[/yellow] - the feed publishes only "
            f"its latest release, and this tree declares {wanted}. That is the expected shape "
            f"before an upgrade, where VERSION still names the release being left. From "
            f"{page or feed}"
        )
    typer.echo(body)
 def _no_entry_message(wanted: Version, has_stamp: bool, release_url: str) -> str:
    """Why there is no entry, and where the notes are instead.
    Two trees land here and they are not the same mistake: a dev checkout that
    has not written its entry yet, and an instance that was told not to go
    online (the only way an instance reaches this at all). Naming the wrong one
    sends the reader to the wrong fix."""
    if not has_stamp:
        return (
            f"{version_mod.CHANGES_FILENAME} has no entry for {wanted} - "
            f"run `wikitool version bump` before releasing, or write the entry"
        )
-        return
+    where = (
-    typer.echo(section, nl=False)
+        f"Read them on the release page instead: {release_url}"
        if release_url
        else f"The release stamp records no `release_url` to point at - `wikitool version check` "
        f"names the feed this instance asks."
    )
    return (
        f"{version_mod.CHANGES_FILENAME} has no entry for {wanted}, and a distributed instance "
        f"never has one: it receives the file as a stub and `dist upgrade` never overwrites it. "
        f"--offline was passed, so the feed was not asked. {where}"
    )
@app.command("bump")
@@ -37,7 +37,7 @@ app = typer.Typer(help="Manage bidirectional cross-references between wiki pages
 def _find_page(pages: dict[str, Page], name: str) -> Page:
    if name not in pages:
-        fail(f"No page titled '{name}' found under wiki/. Create it first with `wikitool new ...`.")
+        fail(f"No page titled '{name}' found under kb/. Create it first with `wikitool new ...`.")
    return pages[name]
@@ -1,5 +1,5 @@
 """Read/write markdown files with YAML frontmatter, matching the formatting
-conventions already used across wiki/ (inline flow-style lists, unquoted
+conventions already used across kb/ (inline flow-style lists, unquoted
 dates).
 We deliberately avoid a generic yaml.dump() for the frontmatter block because
@@ -526,7 +526,7 @@ def _section(lines: list[str], title: str, items: list, formatter) -> None:
 def render_markdown(report: dict) -> str:
    lines = [f"# Structural Lint Report ({report['generated']})", ""]
-    lines.append(f"Scanned {report['page_count']} pages under `wiki/`. This report covers only")
+    lines.append(f"Scanned {report['page_count']} pages under `kb/`. This report covers only")
    lines.append("mechanically-verifiable structural issues; see the Semantic Review section")
    lines.append("below for judgment calls the LLM should complete.")
    lines.append("")
@@ -4,10 +4,35 @@ One definition, because the two must agree: if telemetry grouped events
 differently from the way the budget counts calls, a trace could not be read
 against the gate that refused it.
-A "session" is approximated by the parent process of this CLI invocation - the
+Three-step fallback chain, in order:
-agent's shell - unless the caller sets `WIKITOOL_SESSION_ID`. Skills set it
+
-explicitly so a session is scoped to a task rather than to a terminal window
+1. `WIKITOOL_SESSION_ID`, if the caller set one explicitly. Skills set it so a
-(see instructions/session-setup.md).
+   session is scoped to a task rather than to a terminal window (see
   instructions/session-setup.md).
 2. A harness's own session variable, from `HARNESS_ENV_VARS` below - checked
   only when nothing set the variable above.
 3. `os.getppid()` - the parent process of this CLI invocation. On a harness
   that runs every tool call in a freshly initialised shell (Claude Code's
   Bash tool does), this is a new "session" per call and neither the
   iteration-budget gate's ceiling nor its loop-breaker can ever trip - see
   Gitea #110, which measured a 33-call run splitting into 21 telemetry
   buckets under this fallback alone.
 Step 2 is what closes that gap without asking every skill to `export` a
 variable a harness already re-derives per call: `CLAUDE_CODE_SESSION_ID` is
 stable across a Claude Code session's tool calls (verified 2026-09-16,
 against a live session, across separate Bash invocations - the shell's own
 PID changed on every call, this variable did not) and is **exactly** the id
 the `UserPromptSubmit` hook writes into a trace's `session.start` and
 `prompt.submitted` events. Using it unmodified as the budget/telemetry key -
 no prefix, no rewriting - is what lets the hook's events and this module's
 events land in the same bucket.
 `HARNESS_ENV_VARS` only ever grows by a verified entry: a variable a real
 session was observed setting, confirmed to be the same id a harness's own
 hooks use elsewhere in a trace. A guessed name that happens to exist and
 means something else would be worse than the `getppid()` fallback it would
 replace - it would look like a fix and quietly mis-key a session instead.
 """
 from __future__ import annotations
@@ -16,15 +41,46 @@ import re
 ENV_VAR = "WIKITOOL_SESSION_ID"
 HARNESS_ENV_VARS: tuple[tuple[str, str], ...] = (
    ("CLAUDE_CODE_SESSION_ID", "claude-code"),
 )
 _UNSAFE = re.compile(r"[^A-Za-z0-9._-]+")
 def _harness_session() -> tuple[str, str] | None:
    """The first harness variable that is actually set, as `(value, harness)`."""
    for var, harness in HARNESS_ENV_VARS:
        value = os.environ.get(var)
        if value:
            return value, harness
    return None
 def session_id() -> str:
-    return os.environ.get(ENV_VAR) or str(os.getppid())
+    explicit = os.environ.get(ENV_VAR)
    if explicit:
        return explicit
    harness = _harness_session()
    if harness:
        return harness[0]
    return str(os.getppid())
 def session_id_source() -> str:
-    return ENV_VAR if os.environ.get(ENV_VAR) else "getppid() fallback"
+    """Where the id in `session_id()` came from - `ENV_VAR`, a harness
    variable name (with the harness named alongside it), or the `getppid()`
    fallback. `doctor`, `budget status` and the `wikitool` source's
    `session.start` event all read this so a session - or a trace - can say
    what it was keyed on, not just what the id happened to be."""
    if os.environ.get(ENV_VAR):
        return ENV_VAR
    harness = _harness_session()
    if harness:
        _, name = harness
        var = next(v for v, h in HARNESS_ENV_VARS if h == name)
        return f"{var} ({name})"
    return "getppid() fallback"
 def session_slug(value: str | None = None) -> str:
@@ -30,6 +30,7 @@ from pathlib import Path
 from chemenu import config
 from chemenu.session import session_id as current_session_id
 from chemenu.session import session_id_source as current_session_id_source
 from chemenu.session import session_slug
 from chemenu.telemetry import policy, schema, scrub
@@ -155,14 +156,22 @@ def _seed_session_header(target: Path, source: str, session: str) -> None:
    except FileExistsError:
        return
    with handle:
        attrs = {
            "harness": source,
            "completeness": list(schema.HARNESS_CAPABILITIES.get(source, ())),
            "synthesized": True,
        }
        # Only the `wikitool` source resolves its own session id through
        # chemenu.session's fallback chain - every other source hands `emit()`
        # an id its own hook payload already carried. Naming the chain's
        # outcome here is what lets a trace say what it was keyed on, not just
        # what the id happened to be (Gitea #110).
        if source == "wikitool":
            attrs["session_origin"] = current_session_id_source()
        header = schema.make_event(
            source,
            "session.start",
-            {
+            attrs,
                "harness": source,
                "completeness": list(schema.HARNESS_CAPABILITIES.get(source, ())),
                "synthesized": True,
            },
            session_id=session,
            seq=_next_seq(),
        )
@@ -6,6 +6,7 @@ import pytest
 from chemenu import config, conventions
 from chemenu.frontmatter_io import write_page
 from chemenu.session import HARNESS_ENV_VARS
 from chemenu.telemetry import policy as telemetry_policy
 from chemenu.type_resolver import resolver
@@ -13,6 +14,13 @@ from chemenu.type_resolver import resolver
 # that a test which needs one sets it itself and the rest run against the
 # tool's own defaults. `WIKI_TRACE_DIR` is deliberately absent: it is not a
 # leak but the redirect `isolated_trace_dir` installs one fixture below.
 #
 # The harness variables from `chemenu.session.HARNESS_ENV_VARS` are pulled in
 # here rather than duplicated: this suite runs *inside* Claude Code, so
 # `CLAUDE_CODE_SESSION_ID` is genuinely set in the real environment - without
 # clearing it, every session-fallback test would silently pick up this
 # session's real id instead of exercising the fallback it means to test
 # (Gitea #110).
 _WIKITOOL_ENV = (
    "WIKI_AUTHOR",
    "WIKI_TRACE",
@@ -24,7 +32,7 @@ _WIKITOOL_ENV = (
    "WIKITOOL_UPDATE_URL",
    "WIKITOOL_UPDATE_TOKEN",
    "CHEMENU_ROOT",
-)
+) + tuple(var for var, _harness in HARNESS_ENV_VARS)
 # Environment git reads for identity or for where its repo lives. A stray
 # `GIT_DIR` would point every fixture repo at the developer's checkout; the
@@ -0,0 +1,167 @@
 """The CLI dispatch wrapper: the budget/trace hook every command runs
 through (`cli.main`/`cli._run_traced`), and the broken-pipe handling that
 sits alongside it.
 Gitea #110's SIGPIPE side finding: a successful call whose output is cut off
 by a closed pipe (`wikitool types describe source | head -1`) used to record
 `exit_code: 1` in the trace - indistinguishable from a real tool failure, and
 reproduced verbatim by the very next, unpiped retry of the same command
 showing `exit_code: 0`. `cli._BrokenPipeSwallow` and `cli._pacify_real_fd`
 exist to close that gap; these tests exercise them without depending on a
 real OS pipe or Click's own internal handling, which is exactly the moving
 part being routed around.
 """
 import errno
 import json
 import sys
 import pytest
 from chemenu import cli
 def read_lines(path):
    return [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines()]
 class _FailingStream:
    """Raises EPIPE on the `fail_on`-th write - a fake stream standing in for
    a real pipe whose reader has already closed."""
    def __init__(self, fail_on=1):
        self.fail_on = fail_on
        self.calls = 0
        self.written = []
        self.flushed = False
    def write(self, data):
        self.calls += 1
        if self.calls >= self.fail_on:
            raise OSError(errno.EPIPE, "Broken pipe")
        self.written.append(data)
        return len(data)
    def flush(self):
        self.flushed = True
    def isatty(self):
        return False
 # --- _BrokenPipeSwallow ---
 def test_broken_pipe_swallow_absorbs_epipe_on_write():
    swallow = cli._BrokenPipeSwallow(_FailingStream(fail_on=1))
    n = swallow.write("hello")
    assert n == len("hello")
    assert swallow.sigpipe is True
 def test_broken_pipe_swallow_absorbs_epipe_on_flush():
    class _FlushFails:
        def flush(self):
            raise OSError(errno.EPIPE, "Broken pipe")
    swallow = cli._BrokenPipeSwallow(_FlushFails())
    swallow.flush()  # does not raise
    assert swallow.sigpipe is True
 def test_broken_pipe_swallow_reraises_unrelated_oserrors():
    class _Explodes:
        def write(self, data):
            raise OSError(errno.ENOSPC, "No space left on device")
    swallow = cli._BrokenPipeSwallow(_Explodes())
    with pytest.raises(OSError):
        swallow.write("x")
    assert swallow.sigpipe is False
 def test_broken_pipe_swallow_passes_through_normal_writes():
    wrapped = _FailingStream(fail_on=99)
    swallow = cli._BrokenPipeSwallow(wrapped)
    swallow.write("hello")
    assert wrapped.written == ["hello"]
    assert swallow.sigpipe is False
 def test_broken_pipe_swallow_proxies_unknown_attributes():
    wrapped = _FailingStream()
    swallow = cli._BrokenPipeSwallow(wrapped)
    assert swallow.isatty() is False
 # --- _pacify_real_fd ---
 def test_pacify_real_fd_is_a_best_effort_noop_without_a_real_descriptor():
    class _RaisesOSError:
        def fileno(self):
            raise OSError("not a real fd in this test")
    class _HasNoFilenoAtAll:
        pass
    cli._pacify_real_fd(_RaisesOSError())  # must not raise
    cli._pacify_real_fd(_HasNoFilenoAtAll())  # must not raise either
 # --- _run_traced: the trace records what actually happened ---
 def test_a_write_cut_off_by_a_closed_pipe_is_not_recorded_as_an_error(monkeypatch, tmp_path):
    monkeypatch.setenv("WIKI_TRACE_DIR", str(tmp_path))
    monkeypatch.setenv("WIKITOOL_SESSION_ID", "sigpipe-unit")
    stub = _FailingStream(fail_on=2)  # first write succeeds, second hits EPIPE
    monkeypatch.setattr(sys, "stdout", stub)
    def fake_app():
        sys.stdout.write("line one\n")
        sys.stdout.write("line two\n")  # truncated here, like `| head -1`
        raise SystemExit(0)
    monkeypatch.setattr(cli, "app", fake_app)
    with pytest.raises(SystemExit) as exc:
        cli._run_traced("types", ["describe", "source"])
    assert exc.value.code == 0
    records = read_lines(tmp_path / "sigpipe-unit" / "trace.jsonl")
    call = next(r for r in records if r["event"] == "wikitool.call")
    assert call["attrs"]["exit_code"] == 0
    assert call["attrs"]["stdout_truncated"] is True
 def test_a_real_failure_is_still_recorded_as_one(monkeypatch, tmp_path):
    """The unrelated-error path stays exactly as before: an actual failure
    keeps its exit code and carries no truncation flag."""
    monkeypatch.setenv("WIKI_TRACE_DIR", str(tmp_path))
    monkeypatch.setenv("WIKITOOL_SESSION_ID", "real-failure-unit")
    def fake_app():
        raise SystemExit(1)
    monkeypatch.setattr(cli, "app", fake_app)
    with pytest.raises(SystemExit) as exc:
        cli._run_traced("new", ["entity", "--name", ""])
    assert exc.value.code == 1
    records = read_lines(tmp_path / "real-failure-unit" / "trace.jsonl")
    call = next(r for r in records if r["event"] == "wikitool.call")
    assert call["attrs"]["exit_code"] == 1
    assert "stdout_truncated" not in call["attrs"]
 def test_an_ordinary_call_restores_the_real_streams_afterwards(monkeypatch, tmp_path):
    monkeypatch.setenv("WIKI_TRACE_DIR", str(tmp_path))
    monkeypatch.setenv("WIKITOOL_SESSION_ID", "restore-unit")
    real_stdout, real_stderr = sys.stdout, sys.stderr
    def fake_app():
        raise SystemExit(0)
    monkeypatch.setattr(cli, "app", fake_app)
    with pytest.raises(SystemExit):
        cli._run_traced("lint", [])
    assert sys.stdout is real_stdout
    assert sys.stderr is real_stderr
@@ -176,6 +176,140 @@ def test_keep_local_proceeds_and_leaves_the_changed_file_untouched(instance, tmp
    assert json.loads((instance / version_mod.RELEASE_STAMP_FILENAME).read_text())["version"] == "1.1.0"
 def test_refusal_names_all_three_answers_with_a_pasteable_take_release_line(
    instance, tmp_path, capsys
 ):
    """The abort a run actually reads has to rule out "the default takes the
    release's version" - a real 5.0.0 -> 6.0.0 run on an instance announced
    exactly that belief and then called `dist upgrade` with no flag. So the
    text names all three answers, says none of them is the default, and carries
    the `--take-release` line with the blocked paths already filled in."""
    (instance / "AGENTS.md").write_text("locally edited\n", encoding="utf-8")
    release = _release(
        tmp_path, "release", "1.1.0",
        {"AGENTS.md": "core v2\n", "tools/wikitool": "#!/bin/sh\n"},
    )
    with pytest.raises(typer.Exit):
        dist_cmd.run_upgrade(release)
    out = " ".join(capsys.readouterr().out.split())  # rich wraps; rejoin first
    assert "none of these three is the default" in out
    assert "--take-release AGENTS.md" in out
    assert "--keep-local" in out
    assert "reconcile them by hand" in out
 # --- --take-release: the other answer to a locally changed file ---------------
 def test_take_release_overwrites_the_named_path_and_clears_the_drift(instance, tmp_path):
    """The point of the flag, in one run rather than three hand steps: the
    local change is gone, and because the new stamp records the release digest
    for a file that now *matches* it, the path is no longer divergent - unlike
    `--keep-local`, which reports it again on every future upgrade."""
    (instance / "AGENTS.md").write_text("locally edited\n", encoding="utf-8")
    release = _release(
        tmp_path, "release", "1.1.0",
        {"AGENTS.md": "core v2\n", "tools/wikitool": "#!/bin/sh\n"},
    )
    dist_cmd.run_upgrade(release, take_release=["AGENTS.md"])
    assert (instance / "AGENTS.md").read_text(encoding="utf-8") == "core v2\n"
    stamp = json.loads((instance / version_mod.RELEASE_STAMP_FILENAME).read_text())
    assert stamp["version"] == "1.1.0"
    # The recorded digest and the file on disk agree again, so a second run
    # classifies it as unchanged rather than blocked.
    assert kb_state.compare_against_stamp({"AGENTS.md": stamp["files"]["AGENTS.md"]}) == {
        "AGENTS.md": kb_state.UNCHANGED
    }
 def test_take_release_recreates_a_locally_deleted_file(instance, tmp_path):
    (instance / "tools" / "wikitool").unlink()
    release = _release(
        tmp_path, "release", "1.1.0",
        {"AGENTS.md": "core\n", "tools/wikitool": "#!/bin/sh v2\n"},
    )
    dist_cmd.run_upgrade(release, take_release=["tools/wikitool"])
    assert (instance / "tools" / "wikitool").read_text(encoding="utf-8") == "#!/bin/sh v2\n"
 def test_take_release_and_keep_local_compose_per_path(instance, tmp_path):
    """The mixed case is the one a blanket flag could not express: two changed
    files, one to reset and one to keep."""
    (instance / "AGENTS.md").write_text("locally edited\n", encoding="utf-8")
    (instance / "tools" / "wikitool").write_text("#!/bin/zsh\n", encoding="utf-8")
    release = _release(
        tmp_path, "release", "1.1.0",
        {"AGENTS.md": "core v2\n", "tools/wikitool": "#!/bin/sh v2\n"},
    )
    dist_cmd.run_upgrade(release, take_release=["AGENTS.md"], keep_local=True)
    assert (instance / "AGENTS.md").read_text(encoding="utf-8") == "core v2\n"
    assert (instance / "tools" / "wikitool").read_text(encoding="utf-8") == "#!/bin/zsh\n"
 def test_a_blocked_path_not_named_by_take_release_still_aborts(instance, tmp_path):
    """Without `--keep-local` the run must say something about every blocked
    path, not just the ones it happened to name."""
    (instance / "AGENTS.md").write_text("locally edited\n", encoding="utf-8")
    (instance / "tools" / "wikitool").write_text("#!/bin/zsh\n", encoding="utf-8")
    release = _release(
        tmp_path, "release", "1.1.0",
        {"AGENTS.md": "core v2\n", "tools/wikitool": "#!/bin/sh v2\n"},
    )
    with pytest.raises(typer.Exit) as excinfo:
        dist_cmd.run_upgrade(release, take_release=["AGENTS.md"])
    assert excinfo.value.exit_code == 1
    # Nothing was written, including the path that *was* named.
    assert (instance / "AGENTS.md").read_text(encoding="utf-8") == "locally edited\n"
    assert json.loads((instance / version_mod.RELEASE_STAMP_FILENAME).read_text())["version"] == "1.0.0"
 def test_take_release_refuses_a_path_that_is_not_locally_changed(instance, tmp_path, capsys):
    """A typo that silently did nothing would report a successful upgrade while
    keeping the change the operator asked to discard."""
    (instance / "AGENTS.md").write_text("locally edited\n", encoding="utf-8")
    release = _release(
        tmp_path, "release", "1.1.0",
        {"AGENTS.md": "core v2\n", "tools/wikitool": "#!/bin/sh\n"},
    )
    with pytest.raises(typer.Exit) as excinfo:
        dist_cmd.run_upgrade(release, take_release=["AGENT.md"])
    assert excinfo.value.exit_code == 1
    out = " ".join(capsys.readouterr().out.split())
    assert "AGENT.md" in out  # the typo, named back
    assert "AGENTS.md" in out  # and the list of what *is* blocked
    assert (instance / "AGENTS.md").read_text(encoding="utf-8") == "locally edited\n"
 def test_a_bad_take_release_path_fails_in_the_dry_run_too(instance, tmp_path):
    """The one thing that turns `--dry-run` non-zero: not a state of the tree
    (a blocked file must never do that), but a mistake in the argument, which
    is exactly what a preview is for."""
    (instance / "AGENTS.md").write_text("locally edited\n", encoding="utf-8")
    release = _release(
        tmp_path, "release", "1.1.0",
        {"AGENTS.md": "core v2\n", "tools/wikitool": "#!/bin/sh\n"},
    )
    with pytest.raises(typer.Exit) as excinfo:
        dist_cmd.run_upgrade(release, dry_run=True, take_release=["types/entity.md"])
    assert excinfo.value.exit_code == 1
    assert (instance / "AGENTS.md").read_text(encoding="utf-8") == "locally edited\n"
 def test_dry_run_marks_the_paths_take_release_would_overwrite(instance, tmp_path, capsys):
    (instance / "AGENTS.md").write_text("locally edited\n", encoding="utf-8")
    release = _release(
        tmp_path, "release", "1.1.0",
        {"AGENTS.md": "core v2\n", "tools/wikitool": "#!/bin/sh\n"},
    )
    dist_cmd.run_upgrade(release, dry_run=True, take_release=["AGENTS.md"])
    out = " ".join(capsys.readouterr().out.split())
    assert "--take-release" in out
    assert (instance / "AGENTS.md").read_text(encoding="utf-8") == "locally edited\n"
 # --- the write set -----------------------------------------------------------
@@ -192,6 +326,24 @@ def test_unchanged_and_new_files_are_written_silently(instance, tmp_path):
    assert stamp["files"]["types/entity.md"] == _digest("new\n")
 def test_closing_report_points_at_the_upgrade_instruction(instance, tmp_path, capsys):
    """Everything after the swap has exactly one written order, and it is not
    this line: the report names the instruction that carries it and the command
    the run resumes at, rather than a second copy of the list that drifts
    (AGENTS.md invariant 8). A run that reads only this output must still be
    able to find the rest."""
    release = _release(
        tmp_path, "release", "1.1.0",
        {"AGENTS.md": "core\n", "tools/wikitool": "#!/bin/sh\n"},
    )
    dist_cmd.run_upgrade(release)
    out = " ".join(capsys.readouterr().out.split())  # rich wraps; rejoin first
    assert "instructions/upgrade-instance.md" in out
    assert "instructions sync" in out
@pytest.mark.parametrize("preserved", [".wikitool-kb.json", "CHANGES.md", "kb/log.md", "raw/notes/.gitkeep"])
 def test_seeded_once_paths_are_never_written_even_if_the_release_stamp_lists_them(
    instance, tmp_path, preserved
@@ -571,6 +571,33 @@ def test_every_reference_files_toc_is_current():
    assert docs_verify.check_toc_regions() == []
 def test_a_shipped_template_over_the_threshold_without_a_region_is_reported(tmp_path, monkeypatch):
    """Regression guard for the defect this scope extension fixes: the template
    an instance adopts was maintained by nothing and checked by nothing, so
    `kb/CONVENTIONS.md.template` grew past the threshold carrying no region -
    and every instance that adopted it got a `kb/CONVENTIONS.md` that fails
    `docs verify` at the end of `setup-instance.md`, the one command that step
    ends with. Before the template entered `toc.target_files()`, this check
    returned nothing here."""
    from chemenu import config, toc as toc_mod
    monkeypatch.setattr(config, "ROOT", tmp_path)
    (tmp_path / "kb").mkdir()
    long_body = "# Conventions\n\nIntro.\n" + "".join(
        f"\n## Section {i}\n\n" + "Body line.\n" * 12 for i in range(8)
    )
    assert toc_mod.needs_toc(long_body)
    # The adopted file is current; only the template it was adopted from is not.
    (tmp_path / "kb" / "CONVENTIONS.md").write_text(toc_mod.upsert(long_body), encoding="utf-8")
    (tmp_path / "kb" / "CONVENTIONS.md.template").write_text(long_body, encoding="utf-8")
    issues = docs_verify.check_toc_regions()
    assert len(issues) == 1
    assert "kb/CONVENTIONS.md.template" in issues[0]
    assert "docs toc --apply" in issues[0]
 def test_no_shipped_document_cites_an_issue():
    """Forward direction, against the real tree: a `#42` in a file `dist export`
    ships points at a board only the origin repo has, and the reader of a
@@ -58,7 +58,7 @@ def test_log_status_reports_zero_with_no_log_file(tmp_path, monkeypatch, capsys)
    monkeypatch.setattr(config, "LOG_FILE", tmp_path / "log.md")
    log_status()
-    assert "No wiki/log.md yet" in capsys.readouterr().out
+    assert "No kb/log.md yet" in capsys.readouterr().out
 def test_log_status_warns_at_the_ten_ingest_threshold(tmp_path, monkeypatch, capsys):
@@ -77,6 +77,23 @@ def test_new_entity_creates_page_with_expected_frontmatter(monkeypatch, kb_dir):
    assert "# gateway.example.net" in body
 def test_new_entity_still_materializes_empty_arrays_for_unset_optional_fields(monkeypatch, kb_dir):
    """Gitea #109 stops materializing an optional field's schema `default:`,
    but `tags`/`related`/`sources` are optional arrays with no `default:` at
    all - they must keep landing as `[]`, not disappear. Their absence would
    make `_apply_template_variables` fall back to the filter suffix rendered
    literally (`{related|bullets}` -> the word "bullets" left in the body)."""
    result = _invoke_new(monkeypatch, kb_dir, [
        "new", "entity", "--name", "Bare", "--set", "entity_type=tool",
    ])
    assert result.exit_code == 0, result.output
    fm, body = read_page(kb_dir / "entities/tools/Bare.md")
    assert fm["tags"] == []
    assert fm["related"] == []
    assert fm["sources"] == []
    assert "bullets" not in body
 def test_a_scaffolded_body_carries_no_tool_owned_region(monkeypatch, kb_dir):
    """A template must not scaffold the links or footnotes regions. They are
    generated between markers from frontmatter and re-rendered on every write,
@@ -403,6 +420,48 @@ def test_raw_files_error_points_at_the_comma_split(monkeypatch, kb_dir, raw_dir)
    assert "never rename the raw file" in result.output
 def _invoke_new_instruction(monkeypatch, tmp_path, args):
    """Invoke `new` for a `root: repo` type. `instruction` resolves its
    `base_dir:` against `config.ROOT`, not `config.KB_DIR` - unlike
    `_invoke_new`'s callers, patching `KB_DIR` alone would leave the scaffold
    writing into this checkout's real `instructions/` (Gitea #109's fixture
    note). Repointing `ROOT` pulls `TYPES_DIR` along with it, so
    `use_shipped_type_specs` restores the real, shipped type-specs."""
    import chemenu.config as config
    from chemenu.cli import app
    from chemenu.tests.conftest import use_shipped_type_specs
    monkeypatch.setattr(config, "ROOT", tmp_path)
    use_shipped_type_specs(monkeypatch)
    (tmp_path / "instructions").mkdir(parents=True, exist_ok=True)
    return runner.invoke(app, args)
 def test_new_instruction_omits_migration_only_default(monkeypatch, tmp_path):
    """Gitea #109: `obligation:` is a migration-only field (`instructions/
    migrations/*`) with a schema `default:` but no `required:` entry. The
    scaffold must not materialize it into an ordinary instruction."""
    result = _invoke_new_instruction(monkeypatch, tmp_path, [
        "new", "instruction", "--name", "probe",
    ])
    assert result.exit_code == 0, result.output
    fm, _body = read_page(tmp_path / "instructions/probe.md")
    assert "obligation" not in fm
 def test_new_instruction_explicit_obligation_is_still_written(monkeypatch, tmp_path):
    """The rule only suppresses the *implicit* default - an explicit
    `--set obligation=offered` (as when hand-scaffolding a migration
    document) must still land in the frontmatter."""
    result = _invoke_new_instruction(monkeypatch, tmp_path, [
        "new", "instruction", "--name", "probe-migration",
        "--set", "obligation=offered",
    ])
    assert result.exit_code == 0, result.output
    fm, _body = read_page(tmp_path / "instructions/probe-migration.md")
    assert fm["obligation"] == "offered"
 def test_source_page_accepts_a_raw_file_whose_name_has_a_comma(monkeypatch, kb_dir, raw_dir):
    import chemenu.config as config
@@ -1,8 +1,12 @@
 import json
 import os
 import subprocess
 import sys
 import pytest
 import typer
 from chemenu import config
 from chemenu.commands import run_budget
@@ -137,6 +141,39 @@ def test_override_bypasses_both_gates():
    assert state["test-session"]["count"] == 40
 def test_a_bucket_without_a_recorded_origin_keeps_its_count():
    """Grandfathering (#110 decision 1): an entry written before this field
    existed must not be reset the moment this ships - that would throw away
    real, in-flight state on every existing instance's first call after
    upgrading."""
    run_budget._save_state({"test-session": {"count": 5, "recent": ["lint"]}})
    run_budget.record_and_check("lint", [], override=False)
    entry = run_budget._load_state()["test-session"]
    assert entry["count"] == 6
    assert entry["source"] == "WIKITOOL_SESSION_ID"
 def test_a_bucket_with_a_different_recorded_origin_starts_over():
    """The same id string, stamped by a different origin than the one
    recorded, is treated as a stranger's bucket rather than inherited - the
    mechanism behind #110's 'no bucket is silently reinterpreted' criterion."""
    run_budget._save_state(
        {"test-session": {"count": 40, "recent": ["lint"], "source": "getppid() fallback"}}
    )
    run_budget.record_and_check("lint", [], override=False)
    entry = run_budget._load_state()["test-session"]
    assert entry["count"] == 1
    assert entry["source"] == "WIKITOOL_SESSION_ID"
 def test_a_bucket_with_the_same_recorded_origin_keeps_counting():
    run_budget._save_state(
        {"test-session": {"count": 7, "recent": ["lint"], "source": "WIKITOOL_SESSION_ID"}}
    )
    run_budget.record_and_check("lint", [], override=False)
    assert run_budget._load_state()["test-session"]["count"] == 8
 def test_save_state_writes_atomically_and_leaves_no_tmp_file(isolated_state):
    run_budget._save_state({"test-session": {"count": 1, "recent": []}})
    assert isolated_state.exists()
@@ -228,3 +265,51 @@ def test_status_command_reports_count(capsys):
    run_budget.status_command()
    out = capsys.readouterr().out
    assert "Calls so far: 1" in out
 # --- gate reproduced across separate processes (Gitea #110) ---
 #
 # `isolated_state`'s in-process monkeypatching cannot exercise the actual bug:
 # `os.getppid()` is constant within one test process. These spawn a fresh
 # Python subprocess per call - the same shape as Claude Code's Bash tool,
 # which runs every `wikitool` invocation in a freshly initialised shell - so
 # the parent pid really does differ call to call, and only a harness variable
 # (standing in for `CLAUDE_CODE_SESSION_ID`) can hold the run together.
 # Before the fallback chain existed, both tests below would be green *and*
 # blind: every call landed in its own one-or-two-call bucket, and neither
 # gate could ever see enough of one session to trip.
 def _spawn_call(tmp_path, monkeypatch, *, command="lint", args=(), override=False):
    monkeypatch.setenv("CHEMENU_ROOT", str(tmp_path))
    monkeypatch.setenv("CLAUDE_CODE_SESSION_ID", "harness-run")
    monkeypatch.delenv("WIKITOOL_SESSION_ID", raising=False)
    code = (
        "from chemenu.commands import run_budget\n"
        f"run_budget.record_and_check({command!r}, {list(args)!r}, override={override!r})\n"
    )
    return subprocess.run(
        [sys.executable, "-c", code],
        cwd=config._PACKAGE_ROOT / "tools",
        capture_output=True, text=True,
    )
 def test_the_iteration_budget_gate_trips_across_separate_shells(tmp_path, monkeypatch):
    for i in range(run_budget.DEFAULT_CALL_LIMIT):
        result = _spawn_call(tmp_path, monkeypatch, args=[f"--pass-{i}"])
        assert result.returncode == 0, result.stdout + result.stderr
    result = _spawn_call(tmp_path, monkeypatch, args=["--one-too-many"])
    assert result.returncode != 0
    assert "Iteration Budget Gate" in result.stdout
 def test_the_loop_breaker_trips_across_separate_shells(tmp_path, monkeypatch):
    args = ["add", "--a", "X", "--b", "Y"]
    for _ in range(run_budget.DEFAULT_LOOP_WINDOW):
        result = _spawn_call(tmp_path, monkeypatch, command="xref", args=args)
        assert result.returncode == 0, result.stdout + result.stderr
    result = _spawn_call(tmp_path, monkeypatch, command="xref", args=args)
    assert result.returncode != 0
    assert "Loop-Breaker" in result.stdout
@@ -0,0 +1,70 @@
 """Guard against a renamed stage leaving its old path standing in source.
 `wiki/` was renamed to `kb/` on 2026-08-21. The directory moved; the string did
 not, in 33 places - error messages, `--help` text, docstrings and the lint
 report's own header, all naming a directory that no longer exists. Nothing
 caught it, because no check reads a path literal in source.
 This is that check. It is deliberately a plain substring scan over the source
 tree rather than a `docs verify` check: `docs verify` reads `shipped_prose()`,
 which is markdown only, and the bulk of the defect sat in `.py` strings.
 """
 from __future__ import annotations
 from pathlib import Path
 TOOLS_DIR = Path(__file__).resolve().parents[2]
 # Retired stage path -> what replaced it. A future rename adds a row here in the
 # same change that does the renaming, which is what makes the next occurrence a
 # test failure instead of a string nobody reads for a year.
 RETIRED_STAGE_PATHS = {
    "wiki/": "kb/",
 }
 # Occurrences that are not stage paths at all. Kept as an explicit list with a
 # reason rather than dodged by a cleverer regex: an exception a reader can see
 # is worth more than one a pattern hides.
 ALLOWED = {
    # A fixture release URL, where `wiki` is a repository name in `owner/repo`.
    ("tests/test_dist_cmd.py", "https://example/torben/wiki/releases/tag/v0.3.1"),
 }
 SELF = Path(__file__).resolve()
 def _scanned_files() -> list[Path]:
    """Every source file in `tools/` a stale path literal could hide in.
    This module is excluded, and has to be: it is the one file whose job is to
    name the retired paths, so scanning it would make the guard fail on its own
    declaration.
    """
    candidates = [*(TOOLS_DIR / "chemenu").rglob("*.py"), TOOLS_DIR / "wikitool"]
    return sorted(path for path in candidates if path.resolve() != SELF)
 def test_no_retired_stage_path_survives_in_source():
    findings = []
    for path in _scanned_files():
        relative = path.relative_to(TOOLS_DIR / "chemenu" if path.suffix == ".py" else TOOLS_DIR)
        for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
            for retired, replacement in RETIRED_STAGE_PATHS.items():
                if retired not in line:
                    continue
                if any(key == str(relative) and excerpt in line for key, excerpt in ALLOWED):
                    continue
                findings.append(
                    f"{relative}:{number} names the retired path `{retired}` "
                    f"(now `{replacement}`): {line.strip()}"
                )
    assert findings == [], "Retired stage paths still in source:\n" + "\n".join(findings)
 def test_the_guard_actually_scans_something():
    """A scan that silently matches no file passes for the wrong reason."""
    scanned = _scanned_files()
    assert len(scanned) > 40
    assert TOOLS_DIR / "wikitool" in scanned
    assert SELF not in scanned
@@ -145,6 +145,30 @@ def test_session_id_falls_back_to_the_parent_process(monkeypatch):
    assert "getppid" in session.session_id_source()
 def test_session_id_prefers_a_harness_variable_over_getppid(monkeypatch):
    """The middle link of the chain (Gitea #110): a harness that sets its own
    session variable, but not WIKITOOL_SESSION_ID, still gets a stable id
    rather than falling all the way to the per-call parent pid."""
    monkeypatch.delenv("WIKITOOL_SESSION_ID", raising=False)
    monkeypatch.setenv("CLAUDE_CODE_SESSION_ID", "30d734d5-live-session")
    assert session.session_id() == "30d734d5-live-session"
    assert session.session_id_source() == "CLAUDE_CODE_SESSION_ID (claude-code)"
 def test_explicit_session_id_still_wins_over_a_harness_variable(monkeypatch):
    monkeypatch.setenv("WIKITOOL_SESSION_ID", "ingest-handbook/u2")
    monkeypatch.setenv("CLAUDE_CODE_SESSION_ID", "30d734d5-live-session")
    assert session.session_id() == "ingest-handbook/u2"
    assert session.session_id_source() == "WIKITOOL_SESSION_ID"
 def test_the_harness_id_is_used_unmodified_as_the_key():
    """Decision 1 in #110: no prefix, no rewriting - the value has to be
    exactly what a harness's own hook writes into a trace, or the two would
    stop joining on the same string."""
    assert session.HARNESS_ENV_VARS == (("CLAUDE_CODE_SESSION_ID", "claude-code"),)
 def test_the_core_event_set_is_what_every_harness_can_produce():
    """Guards the degradation rule: if a core event stops being available on one
    harness, this fails rather than the scorer silently reporting zero."""
@@ -185,6 +209,25 @@ def test_a_reported_session_start_is_not_shadowed_by_a_synthetic_one(monkeypatch
    assert "synthesized" not in records[0]["attrs"]
 def test_wikitool_s_own_header_names_where_its_session_id_came_from(monkeypatch, tmp_path):
    """Only the `wikitool` source resolves its own id through the fallback
    chain - naming that origin in its own header is what lets a trace say
    what it was keyed on, not just what the id happened to be (Gitea #110)."""
    monkeypatch.setenv("WIKI_TRACE_DIR", str(tmp_path))
    monkeypatch.setenv("CLAUDE_CODE_SESSION_ID", "harness-session")
    emit_mod.write_event("wikitool", "wikitool.call", {"command": "lint"},
                         session="harness-session")
    header = read_lines(tmp_path / "harness-session" / "trace.jsonl")[0]
    assert header["attrs"]["session_origin"] == "CLAUDE_CODE_SESSION_ID (claude-code)"
 def test_another_source_s_header_carries_no_session_origin(monkeypatch, tmp_path):
    monkeypatch.setenv("WIKI_TRACE_DIR", str(tmp_path))
    emit_mod.write_event("copilot-cli", "tool.post", {"tool_name": "bash"}, session="v4")
    header = read_lines(tmp_path / "v4" / "trace.jsonl")[0]
    assert "session_origin" not in header["attrs"]
 # --- reading back ---
 def test_a_trace_reads_back_in_time_order(monkeypatch, tmp_path):
@@ -170,6 +170,38 @@ def test_target_files_matches_the_documented_scope():
    assert not any(rel.endswith("SKILL.md") for rel in relatives)
 def test_target_files_takes_the_shipped_template_of_a_file_in_scope():
    """Integration check against the real repo: `kb/CONVENTIONS.md` is
    instance-owned and crosses the distribution boundary as
    `kb/CONVENTIONS.md.template`, so the template is the same document one step
    earlier in its life and is maintained here too. Left out, nothing wrote the
    region into it and nothing checked it - and the adopted copy inherited the
    gap, which is how a fresh instance came to fail `docs verify` at the end of
    its own setup."""
    from chemenu import config
    relatives = {f.relative_to(config.ROOT).as_posix() for f in toc.target_files()}
    assert "kb/CONVENTIONS.md.template" in relatives
    assert "kb/CONVENTIONS.md" in relatives  # both forms, not one replacing the other
 def test_target_files_takes_a_template_only_for_a_file_already_in_scope(tmp_path, monkeypatch):
    """The rule is "a file in scope carries its `.template` in with it", not
    "every `.template` in the tree" - `USER.md.template` has no business here,
    because `USER.md` itself is not reference material this region applies to."""
    from chemenu import config
    monkeypatch.setattr(config, "ROOT", tmp_path)
    (tmp_path / "kb").mkdir()
    for name in ("kb/CONVENTIONS.md", "kb/CONVENTIONS.md.template", "USER.md.template"):
        (tmp_path / name).write_text("# A file\n", encoding="utf-8")
    relatives = {f.relative_to(tmp_path).as_posix() for f in toc.target_files()}
    assert relatives == {"kb/CONVENTIONS.md", "kb/CONVENTIONS.md.template"}
 def test_target_files_lists_type_spec_once_despite_two_sources():
    """`types/type-spec.md` is both a stage contract and a `types/*.md` file;
    the set in `target_files` is what keeps that from being a special case."""
@@ -44,7 +44,7 @@ def _touch(**overrides):
 def test_touch_bumps_modified(touch_wiki):
    _touch(page_title="aurora")
    frontmatter, _ = read_page(touch_wiki / "entities/systems/aurora.md")
-    # Unquoted YAML dates round-trip as date objects, matching the rest of wiki/.
+    # Unquoted YAML dates round-trip as date objects, matching the rest of kb/.
    assert str(frontmatter["modified"]) == datetime.date.today().isoformat()
@@ -149,7 +149,7 @@ def test_get_layout_reads_entity_type_specs_own_layout_field():
        "person": "people",
    }
    assert all(spec.get("title") for spec in layout.values())
-    # Order drives wiki/index.md section order.
+    # Order drives kb/index.md section order.
    assert list(layout) == ["project", "system", "tool", "technology", "person"]
@@ -995,7 +995,7 @@ def test_release_refuses_when_version_and_changelog_disagree(tree):
 def test_notes_prints_the_entry_for_the_current_version(tree, capsys):
-    version_cmd.notes_command(version=None)
+    version_cmd.run_notes()
    assert "## 1.0.0" in capsys.readouterr().out
@@ -1008,7 +1008,7 @@ def test_notes_prints_a_running_candidates_full_entry(tree, capsys):
        major=False, minor=False, patch=True, title="Second bump",
        breaking=None, no_migration=None, migration_required=False, impact=None, dry_run=False,
    )
-    version_cmd.notes_command(version=None)
+    version_cmd.run_notes()
    out = capsys.readouterr().out
    assert "## 1.1.0-beta.2" in out
    assert "First bump" in out and "Second bump" in out
@@ -1016,7 +1016,115 @@ def test_notes_prints_a_running_candidates_full_entry(tree, capsys):
 def test_notes_fails_for_a_version_with_no_entry(tree):
    with pytest.raises(typer.Exit):
-        version_cmd.notes_command(version="9.9.9")
+        version_cmd.run_notes(version="9.9.9")
 # --- version notes on a distributed instance --------------------------------
 #
 # Such an instance receives CHANGES.md as a nine-line stub with no version
 # entries, and `dist upgrade` never overwrites it, so the local file it would
 # read can never carry the entry - not today and not after any future release.
 # The run that found this (a traced 5.0.0 -> 6.0.0 upgrade) only got past the
 # step because it read the release page through an MCP server, which is not a
 # path INSTALL.md named and not one every instance has.
 def _stamped(tree: Path, release_url: str = "https://example.invalid/releases/tag/v2.0.0") -> None:
    """Make `tree` read as a tree that came out of `dist export`. The stamp's
    presence is what gates the feed fallback: a dev checkout has none."""
    (tree / version_mod.RELEASE_STAMP_FILENAME).write_text(
        json.dumps(
            {
                "schema": version_mod.STAMP_SCHEMA,
                "version": "1.0.0",
                "release_url": release_url,
                "update_url": "https://example.invalid/api/v1/repos/x/y/releases/latest",
                "files": {},
            }
        ),
        encoding="utf-8",
    )
 def test_notes_falls_back_to_the_feed_when_the_instance_has_no_entry(tree, capsys):
    _stamped(tree)
    (tree / "CHANGES.md").write_text("# Changelog\n\nA stub, no entries.\n", encoding="utf-8")
    version_cmd.run_notes(
        fetcher=_feed({"tag_name": "1.0.0", "body": "## 1.0.0\n\n**Migration:** none required\n"})
    )
    captured = capsys.readouterr()
    assert "**Migration:** none required" in captured.out
    # stdout is consumed by `release.yml`'s redirect, so the provenance lines
    # must not be on it.
    assert "Asking" not in captured.out
    assert "Asking" in captured.err
 def test_notes_names_the_version_the_feed_answered_when_it_differs(tree, capsys):
    """The main case, not an edge one: the notes are read *before* the swap,
    while VERSION still names the release being left."""
    _stamped(tree)
    (tree / "CHANGES.md").write_text("# Changelog\n\nA stub.\n", encoding="utf-8")
    version_cmd.run_notes(fetcher=_feed({"tag_name": "2.0.0", "body": "## 2.0.0\n\nnotes\n"}))
    captured = capsys.readouterr()
    assert "## 2.0.0" in captured.out
    assert "not 1.0.0's" in " ".join(captured.err.split())
 def test_notes_offline_refuses_the_feed_and_names_the_release_page(tree, capsys):
    _stamped(tree)
    (tree / "CHANGES.md").write_text("# Changelog\n\nA stub.\n", encoding="utf-8")
    with pytest.raises(typer.Exit) as excinfo:
        version_cmd.run_notes(offline=True, fetcher=_feed({"tag_name": "2.0.0", "body": "x"}))
    assert excinfo.value.exit_code == 1
    out = " ".join(capsys.readouterr().out.split())
    assert "https://example.invalid/releases/tag/v2.0.0" in out
    assert "--offline was passed" in out
 def test_notes_on_an_unreachable_feed_still_hands_over_the_release_page(tree, capsys):
    """An instance that cannot reach the feed must not be left with only a
    network error: the page is the answer it was after."""
    _stamped(tree)
    (tree / "CHANGES.md").write_text("# Changelog\n\nA stub.\n", encoding="utf-8")
    def refusing(url: str, token, timeout: float) -> bytes:
        raise OSError("no route to host")
    with pytest.raises(typer.Exit):
        version_cmd.run_notes(fetcher=refusing)
    out = " ".join(capsys.readouterr().out.split())
    assert "https://example.invalid/releases/tag/v2.0.0" in out
 def test_notes_treats_an_empty_release_body_as_an_error(tree):
    """An empty answer must never read as "this release has nothing to
    report" - the two lines an operator needs are **Breaking Change:** and
    **Migration:**, and their absence is not the same as their being empty."""
    _stamped(tree)
    (tree / "CHANGES.md").write_text("# Changelog\n\nA stub.\n", encoding="utf-8")
    with pytest.raises(typer.Exit):
        version_cmd.run_notes(fetcher=_feed({"tag_name": "1.0.0", "body": "   "}))
 def test_notes_never_asks_a_feed_without_a_release_stamp(tree, capsys):
    """The guard that keeps the origin repo and CI offline: `release.yml` runs
    `version notes > /tmp/release-notes.md` in a tree that has no stamp, so it
    can never reach the fallback however its CHANGES.md looks."""
    (tree / "CHANGES.md").write_text("# Changelog\n\nno entry here\n", encoding="utf-8")
    def exploding(url: str, token, timeout: float) -> bytes:
        raise AssertionError("a tree with no release stamp must not ask a feed")
    with pytest.raises(typer.Exit):
        version_cmd.run_notes(fetcher=exploding)
    out = " ".join(capsys.readouterr().out.split())
    assert "version bump" in out  # the dev-checkout fix, not the instance one
 # --- version check ---------------------------------------------------------
@@ -23,7 +23,8 @@ precedent first.
 governs `wikitool` itself. `target_files()` walks every file-naming category
 AGENTS.md's own table calls agent-loaded: `AGENTS.md`, every stage contract,
 `kb/CONVENTIONS.md`, every `kb/*/COLLECTION.md`, every flat `instructions/**.md`
-file, every `types/*.md` type-spec, and every `docs/` page. One rule, and
+file, every `types/*.md` type-spec, and every `docs/` page - each together with
 the `<name>.template` it ships as, where one exists. One rule, and
 exactly one exception below it - which is the whole point, because a scope
 carrying several unexplained absences reads as an accident rather than a
 decision, and did: `docs/` and the page type-specs sat outside it for no
@@ -75,6 +76,14 @@ from chemenu import blocks, config, kb_collections, markdown_code
 REGION_NAME = "toc"
 HEADING_TEXT = "Contents"
 # The suffix `dist export` re-keys an instance-owned file to, and the one
 # `setup-instance.md` adopts away again. Lives here because this module is what
 # decides which files are reference material *in both their forms*;
 # `docs_verify` imports it rather than keeping a second spelling. `ownership.py`
 # keeps its own literal deliberately - it answers a different question (which
 # side an upstream merge keeps) over a narrower scope.
 TEMPLATE_SUFFIX = ".template"
 # The line threshold Anthropic's own guidance names. Measured on the body
 # with any existing TOC region stripped out first, so inserting or updating
 # the region can never be what pushes a file over the line.
@@ -120,6 +129,18 @@ def target_files() -> list[Path]:
    `types/type-spec.md` arrives twice - once as a stage contract, once from
    the `types/` walk - and the set at the bottom is what makes that a
    non-issue rather than something to special-case.
    **A file in scope carries its `.template` in with it.** An instance-owned
    reference file crosses the distribution boundary as `<name>.template` and
    is adopted by copying it back (`instructions/setup-instance.md`), so the
    template is the same document one step earlier in its life - the shipped
    form of a file this scope already covers. Leaving it out meant nothing
    maintained it and nothing checked it: `kb/CONVENTIONS.md.template` grew
    past the threshold carrying no region at all, and the first thing to notice
    was a fresh instance failing `docs verify` at the end of its own setup,
    because the adopted copy inherited the gap. `docs toc --apply` writes the
    region into the template as into anything else here; the instance's own
    later edits stay its business, and its own `docs toc` run answers for them.
    """
    files: list[Path] = [config.ROOT / "AGENTS.md"]
    files += [config.ROOT / rel for rel in _STAGE_CONTRACTS]
@@ -139,6 +160,13 @@ def target_files() -> list[Path]:
        directory = config.ROOT / subdir
        if directory.is_dir():
            files += sorted(directory.rglob("*.md"))
    files += [
        template
        for template in (
            path.with_name(path.name + TEMPLATE_SUFFIX) for path in tuple(files)
        )
        if template.is_file()
    ]
    return sorted({f for f in files if f.is_file()})
@@ -59,7 +59,7 @@ class TypeResolver:
        if not type_path.endswith('.md'):
            raise ValueError(f"Type path must end with .md: {type_path}")
-        # Try as repo-relative from /types/ or /wiki/**/types/
+        # Try as repo-relative from /types/ or /kb/**/types/
        if type_path.startswith('types/'):
            candidate = (self.repo_root / type_path).resolve()
            # Ensure it's within the repo - resolve() first so `..` segments
@@ -77,7 +77,7 @@ class TypeResolver:
            # Ensure it's within the repo and starts with types/ or has types/ in path
            try:
                candidate.relative_to(self.repo_root)
-                # Allow relative paths that resolve to types/ or wiki/**/types/
+                # Allow relative paths that resolve to types/ or kb/**/types/
                if 'types' in str(candidate.relative_to(self.repo_root).parts):
                    if candidate.exists() and candidate.is_file():
                        return candidate
@@ -300,8 +300,8 @@ class TypeResolver:
    def get_layout(self, type_path: str, source_file: Path = None) -> Optional[Dict[str, Dict[str, str]]]:
        """Return a type-spec's `layout:` frontmatter - a map of subtype value
        to `{dir, title}`, declaring where instances of each subtype are
-        written under wiki/ and what section title/order to use in
+        written under kb/ and what section title/order to use in
-        wiki/index.md. This is the single source of truth for directory
+        kb/index.md. This is the single source of truth for directory
        placement, so callers (e.g. `new_page.py`, `index_build.py`) never
        need a hand-maintained `entity_type -> subdirectory` Python dict.
@@ -349,8 +349,12 @@ def fetch_latest(
    The network call sits behind `fetcher` so every caller above this line -
    and every test - can run without a network. This is the one place in
-    `wikitool` that talks to a remote host, and it is reached only from
+    `wikitool` that talks to a remote host, and only two commands reach it:
-    `version check`, never implicitly from another command.
+    `version check`, whose whole job it is, and `version notes` on a
    *distributed* instance, whose local `CHANGES.md` is a stub with no entry to
    print (see `fetch_latest_notes`). Neither is implicit - `check` exists for
    the call, and `notes` announces the URL it is asking before it asks, on
    stderr, and takes `--offline` for a caller that wants none of it.
    """
    fetch = fetcher or _urlopen_fetch
    try:
@@ -378,14 +382,18 @@ def fetch_latest(
    return Version.parse(tag)
-def fetch_latest_release(
+def _fetch_latest_object(
    url: str,
-    token: Optional[str] = None,
+    token: Optional[str],
-    timeout: float = 10.0,
+    timeout: float,
-    fetcher: Optional[Fetcher] = None,
+    fetcher: Optional[Fetcher],
-) -> tuple[Version, Optional[str], Optional[str]]:
+) -> tuple[Version, dict]:
-    """`fetch_latest` plus the two display fields a report wants: the release's
+    """`fetch_latest`'s version plus the whole release object it came out of.
-    own page and its publication date."""
+
    `fetch_latest` deliberately answers one question and validates only the
    field that answers it. The two callers below want further fields off the
    same response, and neither may make a second request for them - so the
    payload is captured on the way through rather than re-fetched."""
    fetch = fetcher or _urlopen_fetch
    captured: dict = {}
@@ -399,12 +407,61 @@ def fetch_latest_release(
            pass
        return payload
-    version = fetch_latest(url, token, timeout, capturing)
+    return fetch_latest(url, token, timeout, capturing), captured
 def fetch_latest_release(
    url: str,
    token: Optional[str] = None,
    timeout: float = 10.0,
    fetcher: Optional[Fetcher] = None,
 ) -> tuple[Version, Optional[str], Optional[str]]:
    """`fetch_latest` plus the two display fields a report wants: the release's
    own page and its publication date."""
    version, captured = _fetch_latest_object(url, token, timeout, fetcher)
    html_url = captured.get("html_url") or captured.get("url")
    published = captured.get("published_at") or captured.get("created_at")
    return version, (str(html_url) if html_url else None), (str(published) if published else None)
 def fetch_latest_notes(
    url: str,
    token: Optional[str] = None,
    timeout: float = 10.0,
    fetcher: Optional[Fetcher] = None,
 ) -> tuple[Version, str, Optional[str]]:
    """The latest release's notes text, its version, and its own page.
    This is what makes `version notes` answer on a distributed instance at
    all. Such an instance receives `CHANGES.md` as a nine-line stub with no
    version entries, and `dist upgrade` never overwrites it
    (`ownership.is_upgrade_preserved`), so the local file it would read can
    never carry the entry - not today and not after any future release. The
    release the feed publishes carries the same text in its `body`, because
    `release.yml` builds that body out of `version notes` in the origin repo.
    Only the feed's *latest* release can be asked for: `update_url` is the one
    URL a release stamp records, and composing a `/releases/tags/<tag>` URL out
    of it would be guessing at an API shape rather than reading a recorded one
    (AGENTS.md invariant 7). The caller therefore compares the returned version
    against what it asked for and says so - which is not the edge case but the
    main one: an operator reads the notes *before* the swap, while `VERSION`
    still names the release being left.
    Raises `VersionError` for an unreachable feed, a non-release answer, or a
    release with an empty body - an empty answer must never read as "this
    release has no breaking change to report"."""
    version, captured = _fetch_latest_object(url, token, timeout, fetcher)
    body = str(captured.get("body") or "").strip()
    if not body:
        raise VersionError(
            f"{url} answered with release {version} but no notes text (`body` is empty) - "
            "nothing to print, and an empty answer must not read as 'nothing to report'"
        )
    html_url = captured.get("html_url") or captured.get("url")
    return version, body, (str(html_url) if html_url else None)
 # --- CHANGES.md ------------------------------------------------------------
 #
 # The changelog is prose and stays the author's job. What is mechanical is the
@@ -18,7 +18,7 @@ if [ ! -x "$DIR/.venv/bin/python" ]; then
 fi
 # Do NOT cd into $DIR: that would resolve relative CLI arguments (e.g.
-# --markdown "wiki/Lint Report.md") against tools/ instead of the caller's cwd.
+# --markdown "kb/Lint Report.md") against tools/ instead of the caller's cwd.
 # Add $DIR to PYTHONPATH instead so `chemenu` is importable regardless of
 # where this script is invoked from.
 export PYTHONPATH="$DIR${PYTHONPATH:+:$PYTHONPATH}"
@@ -44,10 +44,6 @@ how to write a conforming page is [types/source.guidance.md](source.guidance.md)
 | `concepts` | No | Titles of the concepts mentioned in this source |
 | `summary` | Yes | One-liner for `kb/index.md` |
 ## Authoring guidance
 - The title starts with "Source - ", followed by the name of the source
 ## Template
 The block below is page material, so it is written in this instance's KB language
@@ -126,6 +126,13 @@ Each type is at least two files, and a `root: kb` type may be three:
 | `types/<name>.schema.yaml` | The machine-checkable half: fields, types, enums, defaults, required-ness, `additionalProperties: false` |
 | `types/<name>.guidance.md` (optional, `root: kb` only) | The stack-owned authoring contract: when to use the type, when not to, and mechanism-level advice that holds regardless of this instance's own enum values or template text - linked from the type-spec's own `guidance:` field. `types/type-guidance.md` is its contract |
 **A `default:` is materialized by `wikitool new` only for a field the schema also lists in
 `required:`.** On an optional field, `default:` documents what a reader should assume when the
 field is absent - writing it into every scaffolded page turns that silent assumption into a
 stated claim instead. `instruction.obligation` is the field this was fixed for: a migration-only
 axis, unrelated to an ordinary instruction, whose `default: required` used to land in every
 newly scaffolded instruction regardless.
 This file is the self-referential root contract every type-spec is validated against, and
 `type-guidance.md` is validated against it the same way `lint-report.md` is - itself a
 non-instantiable, contract-only type. `tools/wikitool types describe <name>` composes all of a
@@ -171,7 +178,7 @@ genuinely that uniform. Once the default was removed and the pages reclassified
 actually were, the field split into six areas with none of them small. Declare `layout` for
 *every* enum value once it does: a value missing from it still gets a directory (`subtype_dir`
 falls back to naively pluralizing the value's own name), but that directory carries no title in
-`wiki/index.md`, which is a silent gap rather than a deliberate flat collection. Leaving a whole
+`kb/index.md`, which is a silent gap rather than a deliberate flat collection. Leaving a whole
 type's `layout` off is for the case in the paragraph above - no subtype field to key on at all
 - not for a subtype field one has simply not gotten around to mapping. A `dir:` must be a single
 path segment, because an area is as deep as a page goes.
@@ -26,8 +26,8 @@ properties:
    type: object
    description: >-
      Optional map of subtype value -> {dir, title}, declaring where instances
-      of each subtype are written under wiki/ and what section title/order to
+      of each subtype are written under kb/ and what section title/order to
-      use in wiki/index.md. Only types with subtype-driven directory
+      use in kb/index.md. Only types with subtype-driven directory
      placement (e.g. entity) need this; omit for types with a single flat
      directory.
    additionalProperties:
@@ -46,11 +46,11 @@ properties:
  base_dir:
    type: string
    description: >-
-      Directory, relative to the wiki root (wiki/), where instances of this
+      Directory, relative to the KB root (kb/), where instances of this
      type are written - e.g. `entities`. Required on every instantiable
      type; omit only for types that are never instantiated as pages (e.g.
      type-spec itself). Combined with `layout:` for subtype-driven
-      placement, giving wiki/<base_dir>/<layout[subtype].dir>/<Title>.md.
+      placement, giving kb/<base_dir>/<layout[subtype].dir>/<Title>.md.
    pattern: "^[a-z][a-z0-9/_-]*$"
  title_prefix:
    type: string
Author	SHA1	Message	Date
torben	11c400c670	stack: Version 6.1.0 freigegeben CI / verify (push) Successful in 55s Details Release / release (push) Successful in 41s Details Files changed: - CHANGES.md - VERSION	2026-09-17 09:13:43 +02:00
torben	9a1be6acde	docs: die Zahl der nachgezogenen Pfadliterale korrigiert (33, nicht 27) CI / verify (push) Successful in 55s Details Release / release (push) Successful in 37s Details Files changed: - CHANGES.md - VERSION - tools/chemenu/tests/test_source_hygiene.py	2026-09-17 09:01:50 +02:00
torben	24cd221b21	fix: stale `wiki/` path literals nach kb/ nachgezogen, mit Test-Guard gegen die naechste Umbenennung CI / verify (push) Successful in 55s Details Release / release (push) Successful in 39s Details Files changed: - CHANGES.md - VERSION - kb/entities/projects/Chemenu.md - kb/log.md - tools/chemenu/commands/_util.py - tools/chemenu/commands/cite_cmd.py - tools/chemenu/commands/git_publish.py - tools/chemenu/commands/log_append.py - tools/chemenu/commands/page_ops.py - tools/chemenu/commands/provenance_cmd.py - tools/chemenu/commands/raw_cmd.py - tools/chemenu/commands/run_budget.py - tools/chemenu/commands/touch.py - tools/chemenu/commands/xref.py - tools/chemenu/frontmatter_io.py - tools/chemenu/lint_core.py - tools/chemenu/tests/test_log_append.py - tools/chemenu/tests/test_source_hygiene.py - tools/chemenu/tests/test_touch.py - tools/chemenu/tests/test_type_resolver.py - tools/chemenu/type_resolver.py - tools/wikitool - types/type-spec.md - types/type-spec.schema.yaml	2026-09-17 08:59:25 +02:00
torben	aa31d431fc	new: scaffold materializes a schema default only for a required field CI / verify (push) Successful in 57s Details Release / release (push) Successful in 37s Details Files changed: - CHANGES.md - VERSION - instructions/CONTRACT.md - tools/CONTRACT.md - tools/chemenu/commands/new_page.py - tools/chemenu/tests/test_new_page.py - types/type-spec.md	2026-09-16 21:38:20 +02:00
torben	4284f101c8	docs: why-gates-are-code haelt fest, dass ein Gate in Code auch erreichbar sein muss CI / verify (push) Successful in 53s Details Files changed: - docs/why-gates-are-code.md	2026-09-16 19:18:59 +02:00
torben	e4e2332e01	session: Harness-Session-Variable schliesst die Luecke im Session-Id-Fallback (Telemetrie-Join, Iteration-Budget-Gate); SIGPIPE-Nebenbefund im Emitter behoben CI / verify (push) Successful in 52s Details Release / release (push) Successful in 36s Details Files changed: - CHANGES.md - EVALS.md - INSTALL.md - VERSION - instructions/session-setup.md - tools/CONTRACT.md - tools/chemenu/cli.py - tools/chemenu/commands/doctor.py - tools/chemenu/commands/run_budget.py - tools/chemenu/session.py - tools/chemenu/telemetry/writer.py - tools/chemenu/tests/conftest.py - tools/chemenu/tests/test_cli.py - tools/chemenu/tests/test_run_budget.py - tools/chemenu/tests/test_telemetry_emit.py	2026-09-16 19:18:00 +02:00
torben	536093f6c9	docs: INSTALL.md/EVALS.md ziehen nach, dass version notes den Feed mitfragt (#107 ) CI / verify (push) Successful in 43s Details Nachzug aus der Abschlussphase. INSTALL.md behauptete, version check sei der einzige Befehl, der ins Netz geht - seit 6.1.0-beta.4 sind es zwei. EVALS.md nennt version notes als dritten Nutzer der Stamp-Unterscheidung Instanz/Dev-Checkout, die genau diese Fallback-Grenze traegt. Prosa-only, ausserhalb des CI-Version-Gates, deshalb kein Bump. Files changed: - EVALS.md - INSTALL.md	2026-09-16 17:56:04 +02:00
torben	0c98080964	version notes: Fallback auf den Release-Feed, wenn die Instanz keinen lokalen Eintrag hat (#107 ) CI / verify (push) Successful in 46s Details Release / release (push) Successful in 36s Details Befund 2 aus dem getraceten 5.0.0-auf-6.0.0-Upgrade-Lauf. Eine ausgelieferte Instanz bekommt CHANGES.md als Stub und dist upgrade ueberschreibt sie nie, der Befehl konnte dort also nie antworten - an genau der Stelle, an der Breaking Change und Migration gelesen werden muessen. Fehlt der Eintrag lokal, wird der Feed aus update_url gefragt. Nur mit Release-Stamp, damit Ursprungs-Repo und CI den Pfad nicht betreten koennen; stdout traegt nur die Notes, Herkunft nach stderr; --offline verweigert den Aufruf und nennt die release_url, so wie jeder Feed-Fehlerfall auch. Dazu zwei seit ihrer Umsetzung falsche Eintraege aus tools/CONTRACT.md "Future considerations" entfernt: MCP-Server-Wrapper und dist upgrade. Files changed: - CHANGES.md - INSTALL.md - VERSION - instructions/upgrade-instance.md - tools/CONTRACT.md - tools/chemenu/commands/version_cmd.py - tools/chemenu/tests/test_version_cmd.py - tools/chemenu/version.py	2026-09-16 17:54:39 +02:00
torben	72d01beef8	dist upgrade: --take-release nimmt fuer einen lokal geaenderten Pfad die Release-Fassung (#107 ) CI / verify (push) Successful in 45s Details Release / release (push) Successful in 37s Details Befund 3 aus dem getraceten 5.0.0-auf-6.0.0-Upgrade-Lauf. --keep-local behielt die Drift und meldete sie bei jedem kuenftigen Upgrade erneut, der andere Weg "reconcile by hand" hatte kein Werkzeug und kostete Handkopie, Vorbedingungs- Commit und damit einen rohen git commit an Invariante 5 vorbei. --take-release <pfad> ist wiederholbar, komponiert pro Pfad mit --keep-local, lehnt einen nicht blockierten Pfad auch im --dry-run ab und beendet die Drift statt sie zu uebergehen. Die Abbruchmeldung nennt jetzt alle drei Antworten mit eingesetzter Kommandozeile und sagt, dass keine der Default ist. Files changed: - CHANGES.md - VERSION - instructions/upgrade-instance.md - tools/CONTRACT.md - tools/chemenu/commands/dist_cmd.py - tools/chemenu/tests/test_dist_upgrade.py	2026-09-16 17:35:14 +02:00
torben	0e09cf41ea	docs: Migrationsdokument haelt das Vorher fest und verweist auf die .template-Form, Rest-Abschnitt aus types/source.md entfernt (#107 ) CI / verify (push) Successful in 46s Details Release / release (push) Successful in 37s Details Files changed: - CHANGES.md - VERSION - instructions/migrate-corpus.md - instructions/migrations/6.0.0-type-guidance-split.md - types/source.md	2026-09-16 15:44:11 +02:00
torben	504149c7c4	stack: Upgrade-Pfad bekommt eine eigene manual-Instruktion, INSTALL.md verweist darauf (#108 ) CI / verify (push) Successful in 48s Details Release / release (push) Successful in 36s Details 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	2026-09-16 14:04:16 +02:00
torben	f3c80747a5	docs toc/verify: die .template-Form einer Referenzdatei steht im Dateisatz, Version 6.0.1 freigegeben (schliesst #106 ) CI / verify (push) Successful in 48s Details Release / release (push) Successful in 41s Details Files changed: - CHANGES.md - VERSION - instructions/dev/doc-pull-through.md - kb/CONVENTIONS.md.template - tools/CONTRACT.md - tools/chemenu/commands/docs_verify.py - tools/chemenu/tests/test_docs_verify.py - tools/chemenu/tests/test_toc.py - tools/chemenu/toc.py	2026-09-16 06:43:36 +02:00