chemenu/INSTALL.md

Installation

Dieses Dokument richtet sich an Menschen. Es gibt vier Wege: ein Release herunterladen (der normale Weg zu einer neuen Instanz), eine Distribution selbst exportieren, dieses Repo klonen (Testbett und Demo, samt Beispielkorpus), oder eine private Instanz mit diesem Repo als Upstream aufsetzen. Der agent-seitige Ablauf steckt in instructions/; hier stehen nur die menschlichen Teile - für die vollständige Kommandoreferenz siehe tools/CONTRACT.md.

Den optionalen MCP-Leseserver installiert und betreibt INSTALL-MCP.md: derselbe Korpus, lesend, für einen Konsumenten, der kein Terminal auf dieser Maschine ist.

Voraussetzungen

• Python 3.11 oder neuer
• git
• ripgrep (rg) - wird von search und sources coverage gebraucht

Weg A: Release herunterladen

Der kürzeste Weg zu einer eigenen Instanz - kein Checkout dieses Repos nötig. Jedes Release trägt genau einen dist export-Baum plus eine Prüfsumme. Das Repo ist öffentlich, der Download braucht also weder Konto noch Token:

BASE=https://gitea.nehmer.net/torben/chemenu/releases/download/v<version>
curl -LO $BASE/chemenu-stack-<version>.tar.gz
curl -LO $BASE/chemenu-stack-<version>.tar.gz.sha256
sha256sum -c chemenu-stack-<version>.tar.gz.sha256
tar xzf chemenu-stack-<version>.tar.gz
cd chemenu-stack-<version>

Die Prüfsumme ist nicht Zierde: Sie ist das Einzige, was einen unterbrochenen Download von einem vollständigen unterscheidet, und sha256sum -c muss OK sagen, bevor irgendetwas entpackt wird.

Danach weiter mit Schritt 2 aus Weg B: den Agenten instructions/setup-instance.md ausführen lassen. Der entpackte Baum ist bereits eine Distribution - Schritt 1 (dist export) entfällt.

Die Liste der Releases: https://gitea.nehmer.net/torben/chemenu/releases.

Weg B: Neue, leere Instanz selbst exportieren

Dasselbe Ergebnis aus einem Checkout dieses Repos - für einen Stand, der noch kein Release hat. Zwei Schritte, von denen nur der erste rein menschlich ist:

1. Zielverzeichnis wählen und die Distribution dorthin exportieren, aus einem Checkout dieses Repos:

   tools/wikitool dist export /pfad/zur/neuen/instanz
   

   Das Ziel muss leer sein oder noch nicht existieren. dist export kopiert die Maschinerie (Werkzeuge, Typen, Instruktionen, die Collection-Contracts) ohne Wiki-Inhalt, ohne Git-Historie und ohne instructions/dev/ (Stack-Entwicklung selbst, inkl. der vendorten commonplace/-Wissensbasis) - dauerhaft, ohne Restore-Weg.

2. Den Agenten dort arbeiten lassen. Öffne das Zielverzeichnis in deinem Agent-Harness (Claude Code, GitHub Copilot, Codex CLI, Mistral Vibe) und lass es instructions/setup-instance.md ausführen. Diese Anweisung fragt dich dabei explizit nach:

   • Autor-Identität (Name + E-Mail für git config) - wird nie geraten oder aus einem anderen Repo übernommen, und ist zugleich der Autorname jeder künftig angelegten Wiki-Seite ($WIKI_AUTHOR überschreibt dies bei Bedarf).
   • Remote (optional) - eine URL, wenn du das Repo auf einen Server pushen willst; sonst bleibt die Instanz lokal, und jedes publish läuft mit --no-push.
   • Autorenkonventionen - Sprache, Abschnittsnamen, Namensformen, Ton, Beziehungslabels und Hedging-Regel stehen in kb/CONVENTIONS.md, dazu je Collection die Regeln in kb/<name>/COLLECTION.md. Die Distribution bringt davon nur die .template-Dateien mit: das sind Entscheidungen dieser Instanz, keine Eigenschaft des Musters, und nichts davon liegt unter tools/ oder types/. Fertige Profile - darunter ein vollständiges deutsches - hält instructions/kb-profiles.md bereit; es ist eine Palette, kein Enum. Sag die Sprache vor dem ersten Ingest - danach ist ein Wechsel der Abschnittsnamen eine Migration jeder bereits angelegten Seite.
   • Anwendungsgebiet - woraus dieses Wiki seine Quellen zieht. Daraus schlägt der Agent eine source_type-Liste vor (bei einem Verein etwa Satzung, Protokoll, Spielbericht statt Transkript, Analyse, Artikel) und setzt sie in types/source.schema.yaml und types/source.md ein. Das ist ein Startpunkt, keine Festlegung: zu diesem Zeitpunkt hat die Instanz null Quellen, die Taxonomie ist also geraten, bevor jemand Material gesehen hat. Sie wird später an echtem Bestand korrigiert - instructions/evolve-subtypes.md beschreibt, wie ein Wert dazukommt und wie das Auffangfach unclassified wieder leer wird. Nicht zur Wahl stehen fidelity und authority: die beiden sind Stack-Vokabular und in jeder Domäne dieselben.
   • Personalization - wer diese Instanz bedient (USER.md) und wie sie klingt (SOUL.md). Die Distribution bringt nur USER.md.template und SOUL.md.template mit: persönlicher Inhalt gehört nicht in jede exportierte Kopie, aber beide Dateien werden in jeder Session gelesen, sind also Betriebsvoraussetzung. Der Agent interviewt dich entlang der Template-Abschnitte und schreibt deine Antworten wörtlich mit - inklusive der beiden Fragen, die er nicht raten darf: der Persona-Name und die Themen, die bewusst draußen bleiben.

   Danach ist die Instanz initialisiert, verifiziert und committet.

   Was von der Sprachwahl unberührt bleibt: die Trennung zwischen Prosa und Identifiern. Seitentitel, Wikilink-Ziele, Zitat-IDs, Schema-Werte, Tags, Befehle und Pfade folgen keiner KB-Sprache, sondern dem etablierten Namen der Sache - Act Runner heißt in jeder Instanz Act Runner.

Weg C: Dieses Repo klonen

Für die Arbeit am Stack selbst, oder um sich den mitgelieferten Korpus als begehbares Beispiel anzusehen. Was hier liegt, ist ein Testbett und eine Demo, keine produktive Wissensbasis: rund 170 Seiten, die den Stack selbst dokumentieren - Gates, Lint, Versionierung, Suche, das Wiki-Muster. Wer eigenes Wissen sammeln will, nimmt Weg A oder B und fängt mit einem leeren kb/ an.

git clone https://gitea.nehmer.net/torben/chemenu.git
cd chemenu

Danach den Agenten instructions/bootstrap.md ausführen lassen (Werkzeugumgebung + Skills publizieren). Git-Repo, Autor-Identität und Inhalt existieren hier bereits.

Ein Clone, der älter ist als die Personalization-Dateien, hat kein USER.md/SOUL.md - doctor meldet dafür personalization: FAIL. Das ist einmalig nachzuholen: nur Schritt 6 (Personalization) aus instructions/setup-instance.md, nicht der ganze Ablauf. bootstrap.md verweist an derselben Stelle darauf.

ENVIRONMENT.md fehlt nach einem Clone immer - die Datei ist gitignored, weil sie einen Checkout beschreibt und nicht das Repo. Sie ist optional; wer sie anlegt, spart jeder folgenden Session die Fragen nach Harness, MCP-Servern und Remote. Vorlage: ENVIRONMENT.md.template, Ablauf: Schritt 5 in instructions/bootstrap.md.

Weg D: Private Instanz mit diesem Repo als Upstream

Die Kombination aus A und C: eine eigene, nicht öffentliche Instanz, die weiterhin Stack-Updates von hier zieht - per git merge statt per Tarball, also mit echtem Drei-Wege-Merge statt cp -r.

Das ist der Weg mit dem höchsten Einsatz, weil ein Checkout dann zwei Remotes hat und git beim Push nicht unterscheidet, welcher welcher ist. Ein falsches --remote legt privaten Inhalt auf ein öffentliches Repo, und ein Force-Push holt das nicht zurück - die Objekte bleiben per SHA abrufbar, bis auf dem Server die Reflogs verfallen.

Dagegen gibt es das Publish-Remote-Gate, und die Anleitung setzt es an die Stelle, an der es wirkt: vor dem ersten publish. Vollständiges Vorgehen: instructions/private-instance.md.

Version und Updates

Jede Instanz trägt die Version des Stacks (Werkzeuge, Typen, Instruktionen, Contracts) - nicht die ihres Inhalts. Sie steht in VERSION, und eine per Release oder dist export erzeugte Instanz trägt zusätzlich .wikitool-release.json mit Herkunft und Exportdatum.

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 Ursprungs-Instanz ($WIKITOOL_UPDATE_URL überschreibt; sonst der Wert aus dem Stamp). Ein nicht erreichbarer Feed wird als Fehler gemeldet - nie als „aktuell".

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 nicht, und ab 1.0.0 liest sich dieselbe Regel als das gewohnte „MAJOR bricht". version check sagt das direkt (state: update vs. state: migration).

Was diese Stelle beantwortet, ist ob die neue Version ein Drop-in-Ersatz ist - ob sich die Maschinerie einfach darüberkopieren lässt und ob die alte danach noch zurückkann. Ob Inhalt migriert werden muss, ist eine zweite, unabhängige Frage. Ein MAJOR-Sprung kann eine leere Migrationskette haben und trotzdem Handarbeit verlangen: umbenannter Release-Feed, umbenanntes Artefakt, umbenannter Import- oder Kommandoname, geänderte Envvar - kb/ bleibt dabei unangetastet, das Update ist trotzdem keins zum Drüberkopieren. Der Abschnitt „Sonderfall: 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.

Eine Instanz aktualisieren

Zwei Wege, je nachdem, wie diese Instanz entstanden ist. Ein Clone mit gemeinsamer Git-History (upstream-Remote auf das Ursprungs-Repo, siehe instructions/private-instance.md) nimmt Stack-Updates per echtem Drei-Wege-Merge: tools/wikitool upstream merge. Alles Folgende gilt für eine Instanz aus einem Tarball, ohne gemeinsame History - der Weg unten unter „Eine Instanz aktualisieren" nutzt sie.

Das Anwenden eines Updates schreibt in eine Instanz, die bereits Inhalt hat. Der Inhalt hat dabei eine eigene Version: .wikitool-kb.json sagt, in welcher Form die Seiten vorliegen, unabhängig davon, welche Maschinerie danebensteht. Genau dieser Unterschied ist der Zustand, in dem sich jede Instanz mitten im Upgrade befindet.

1. Vor dem Tausch prüfen, was ansteht - solange VERSION noch die alte ist:

   tools/wikitool migrate status
   

   Steht hier etwas aus, erst diese Migrationskette abschließen (Schritt 5 unten) - dist upgrade verweigert den Tausch sonst von selbst.

2. Release-Tarball herunterladen und die Release-Notes lesen (Weg A oben).

3. Maschinerie tauschen:

   tools/wikitool dist upgrade <tarball-oder-verzeichnis> --dry-run
   

   Beim ersten Sprung auf 4.5.0 oder höher gibt es dieses Kommando in der Instanz noch nicht - es kam erst mit 4.5.0. Dann das Werkzeug aus dem entpackten neuen Tarball verwenden, gegen die alte Instanz gerichtet:

   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.

   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

   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 tools/wikitool migrate baseline <version> aufrufen; geraten wird nichts.

Fallstricke. Eine Instanz ohne lokale .wikitool-release.json (oder eine ohne files-Block, aus der Zeit vor 4.5.0) hat für dist upgrade keine Basis, gegen die es eine lokale Änderung erkennen könnte, und verweigert den Tausch - dafür gibt es heute keine Reparatur. Der Befehl lädt selbst nichts herunter: <tarball-oder-verzeichnis> muss vorher aus Weg A geholt werden, und ein Tarball muss genau ein Top-Level-Verzeichnis enthalten - die Form, in der .gitea/workflows/release.yml es baut.

Vor 4.5.0 stand hier ein rein manueller Ablauf (Maschinerie von Hand kopieren, kb/CONTRACT.md eingeschlossen, sha256-Vergleich von Hand). dist upgrade ersetzt genau diesen Teil; wer ihn dennoch von Hand nachvollziehen will oder muss (ein Werkzeug, das wikitool selbst nicht ausführen kann), findet die Dateiliste im files-Block der .wikitool-release.json und die Ausnahmen (kb/CONVENTIONS.md, kb/*/COLLECTION.md, .wikitool-kb.json) in tools/CONTRACT.mds dist upgrade-Zeile.

Konfiguration

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)
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)
WIKI_TRACE / WIKI_TRACE_DIR	Telemetrie abschalten bzw. aus dem Arbeitsbaum heraus umlenken	Hängt vom Installationsweg ab - siehe unten
WIKI_TRACE_MAX_SESSION_BYTES / WIKI_TRACE_KEEP_SESSIONS	Byte-Deckel je Session-Trace bzw. wie viele Session-Verzeichnisse die Retention behält	5 MiB je Session, 250 Verzeichnisse

Gegen das Ursprungs-Repo braucht es kein Token. torben/chemenu ist öffentlich lesbar; version check und der Download in Weg A funktionieren ohne Konfiguration.

Telemetrie-Default hängt vom gewählten Weg ab, nicht von einem festen Schalter. Weg A und Weg B erzeugen eine .wikitool-release.json (Weg A trägt sie schon im Release, Weg B schreibt sie beim Export) - daran erkennt chemenu.telemetry.policy, dass niemand Telemetrie bestellt hat, und der Default steht auf aus. Weg C (dieses Repo geklont) trägt keine solche Datei - hier sind die Traces das Messinstrument, mit dem der Stack sich selbst bewertet, und der Default steht auf an. Weg D erbt den Default von der Distribution, aus der die private Instanz entstand, also ebenfalls aus.

Wer den Default umdrehen will, legt .wikitool-telemetry.json im Repo-Root an (pro Checkout, gitignored, kein .template - genau wie .wikitool-remotes.json):

{ "enabled": true, "max_session_bytes": 5242880, "keep_sessions": 250 }

Alle drei Schlüssel sind optional. WIKI_TRACE überschreibt enabled weiterhin in beide Richtungen und schlägt diese Datei. wikitool doctor meldet den aktuellen Zustand (an/aus, warum, und die Menge gegen beide Deckel); mehr dazu in EVALS.md § "Whether it runs at all".

Für einen privaten Fork schon. Wer den Stack in ein eigenes, nicht öffentliches Repo legt und WIKITOOL_UPDATE_URL auf dessen Feed zeigen lässt, stößt auf eine Eigenheit, die man kennen sollte: Gitea antwortet anonymen Aufrufern für ein unsichtbares Repo mit demselben 404 wie für ein gar nicht existierendes. Ein fehlendes Release und ein fehlender Zugriff sehen dann identisch aus - „kein Update gefunden" wäre in dem Fall schlicht gelogen. Dagegen hilft ein Gitea-Token mit Lesezugriff:

export WIKITOOL_UPDATE_TOKEN="<gitea-token>"
tools/wikitool version check

Verifikation

tools/wikitool doctor

Prüft in einem Aufruf: Abhängigkeiten, Autor-Auflösung, Git-Identität/Branch/Remote, publizierte Skills, Struktur (Collection-Contracts, generierte Dateien), Personalization (USER.md/SOUL.md vorhanden und ausgefüllt), die optionale Umgebungsnotiz (ENVIRONMENT.md) und die Session-ID. OK/WARN sind unbedenklich (ein fehlender Remote z. B. ist ein gültiger Endzustand); nur ein FAIL bricht mit exit 1 ab, und jede Zeile nennt ihr eigenes Fix-Kommando.

Danach zusätzlich:

tools/wikitool docs verify
tools/wikitool instructions verify

Troubleshooting

• wikitool: venv not found - Schritt "Werkzeugumgebung anlegen" aus instructions/bootstrap.md bzw. instructions/setup-instance.md wurde noch nicht ausgeführt.
• Der Agent bietet keine Skills an (wiki-ingest, wiki-query, ...) - .agents/skills/ und .claude/skills/ sind generiert und nicht committet. tools/wikitool instructions sync ausführen, dann die Agent-Session neu starten (Harnesses lesen Skills nur beim Start).
• doctor meldet personalization: FAIL - USER.md/SOUL.md fehlen, oder sie tragen noch die Sentinel-Zeile aus dem Template (ein umbenanntes Template ist kein ausgefülltes). Den Personalization-Schritt (6) aus instructions/setup-instance.md ausführen lassen; bei einer Instanz nach Weg C ist das der einzige nachzuholende Schritt.
• doctor meldet environment: WARN - ENVIRONMENT.md existiert, trägt aber noch die Sentinel-Zeile aus dem Template. Ausfüllen (Vorlage: ENVIRONMENT.md.template) und die Zeile entfernen, oder die Datei löschen - sie ist optional, und absent ist ein gültiger Endzustand.
• new bricht mit "No author configured" ab - weder $WIKI_AUTHOR noch git config user.name sind gesetzt. git config user.name "<Name>" ausführen, oder WIKI_AUTHOR exportieren.
• publish endet mit Exit-Code 42 (Mass-Update-Gate) - erwartetes Verhalten bei ≥10 gezählten Dateien (z. B. beim allerersten Commit einer neuen Instanz). Das ist kein Fehler, sondern die Aufforderung, die Ausgabe einem Menschen zu zeigen: sie enthält die vollständige Dateiliste und die exakte --confirm <token>-Zeile, die nach Freigabe veröffentlicht. Details: instructions/gates.md.
• publish endet mit Exit-Code 42 (Publish-Remote-Gate) - dieser Checkout hat eine .wikitool-remotes.json, und das angesteuerte Remote steht nicht darin. Ebenfalls kein Fehler: Die Ausgabe nennt die Push-URL, an die geschrieben würde, und die erlaubten. Anders als beim Mass-Update-Gate gibt es hier keinen Token und keine Flagge - stimmt das Ziel wirklich, trägt der Mensch dessen URL selbst in die Datei ein. Ein Agent, der die Datei anfasst, um an der Verweigerung vorbeizukommen, öffnet ein Gate aus eigenem Antrieb.
• Ich will am Tool-Stack selbst weiterarbeiten (nicht nur Wiki-Inhalt betreiben) - eine neue Instanz hat dafür keinen Weg: dist export lässt instructions/dev/ (Stack-Entwicklung, inkl. der vendorten commonplace/-Wissensbasis) bewusst und dauerhaft weg, ohne Restore-Mechanismus. Für Stack-Entwicklung im Ursprungs-Repo arbeiten (oder eine neue Dev-Instanz daraus exportieren) statt in dieser Instanz nachzurüsten.