chemenu/INSTALL.md

Installation

Dieses Dokument richtet sich an Menschen. Es gibt drei Wege: ein Release herunterladen (der normale Weg zu einer neuen Instanz), eine Distribution selbst exportieren, oder dieses Repo klonen (Torbens persönliche Wiki, samt Inhalt). Der agent-seitige Ablauf steckt in instructions/; hier stehen nur die menschlichen Teile - für die vollständige Kommandoreferenz siehe tools/CONTRACT.md.

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 derzeit privat, der Download braucht also ein Gitea-Token mit Lesezugriff (siehe Konfiguration):

BASE=https://gitea.nehmer.net/torben/chemenu/releases/download/v<version>
curl -LO -H "Authorization: token $WIKITOOL_UPDATE_TOKEN" $BASE/chemenu-stack-<version>.tar.gz
curl -LO -H "Authorization: token $WIKITOOL_UPDATE_TOKEN" $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>

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.
   • KB-Sprache - die exportierte Distribution bringt Deutsch mit: die Regel in kb/CONTRACT.md, das Vokabular in instructions/german-terminology.md und deutsche Abschnittsnamen in den Seitenvorlagen. Das ist eine Entscheidung dieser Ursprungsinstanz, keine Eigenschaft des Musters. Willst du eine andere Sprache, sag es vor dem ersten Ingest - danach ist es eine Migration jeder bereits angelegten Seite.
   • 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 Torbens Instanz selbst, oder einen Fork davon samt Inhalt:

git clone <repo-url>
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.

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

Eine Instanz aktualisieren

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

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

   tools/wikitool migrate status
   

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

3. Die Maschinerie aus dem Tarball über die Instanz kopieren: tools/, types/, instructions/, AGENTS.md, VERSION, .wikitool-release.json. Nicht anfassen: kb/, raw/, work/, .wikitool-kb.json und .git/ - das ist die Instanz selbst.

4. Achtung bei lokal angepassten Contract-Dateien: wer z. B. die KB-Sprache umgestellt hat (Schritt 5 in setup-instance.md), hat kb/CONTRACT.md und die Templates unter types/ verändert. Diese Änderungen vorher sichern und danach wieder einspielen. Welche Dateien das sind, verrät ein Vergleich gegen die sha256-Summen im files-Block der alten .wikitool-release.json.

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 der Migration>, dann doctor, docs verify, instructions verify und lint. Zum Schluss tools/wikitool instructions sync (die Skills sind Kopien) und die Agent-Session neu starten.

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.

Sonderfall: Update von 1.x auf 2.0.0

Mit 2.0.0 wurde das Ursprungs-Repo von torben/llm-wiki-test1 auf torben/chemenu umbenannt. Eine Instanz, die vor diesem Release exportiert wurde, trägt in .wikitool-release.json noch den alten Feed - und version check fragt damit einen Pfad ab, den es unter diesem Namen nicht mehr gibt. Der Befehl bricht also nicht kaputt, er erfährt nur nichts mehr. Einmalig überschreiben:

export WIKITOOL_UPDATE_URL="https://gitea.nehmer.net/api/v1/repos/torben/chemenu/releases/latest"
tools/wikitool version check

Danach den Tarball aus Weg A holen - er heißt seit 2.0.0 chemenu-stack-<version>.tar.gz statt llm-wiki-stack-<version>.tar.gz - und den Ablauf oben normal durchlaufen. Das mitkopierte .wikitool-release.json trägt den neuen Feed, die Variable wird danach nicht mehr gebraucht.

Zwei Nachräumarbeiten, weil Schritt 3 tools/ kopiert und nichts löscht: das alte Paket tools/wiki_tools/ bleibt neben dem neuen tools/chemenu/ liegen und kann weg - der tools/wikitool-Shim ruft seit 2.0.0 -m chemenu.cli auf und rührt es nicht mehr an. Und eigene Skripte, die from wiki_tools import … machen, müssen auf chemenu gezogen werden.

Eine Inhaltsmigration verlangt dieses Release nicht: migrate status bleibt leer, kb/ behält Schema und Shape.

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 - aber das Ursprungs-Repo ist derzeit privat, also wird ein Token gebraucht (siehe unten)

Privates Ursprungs-Repo. torben/chemenu ist nicht öffentlich lesbar. 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 also identisch aus. Für version check (und für den Download in Weg A) braucht es deshalb ein Gitea-Token mit Lesezugriff:

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

Wird das Repo öffentlich geschaltet, entfällt das Token ersatzlos - der Feed ist dann anonym lesbar und version check funktioniert ohne Konfiguration.

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.
• 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.