chemenu/INSTALL.md

Installation

Dieses Dokument richtet sich an Menschen. Es gibt genau einen Weg zu einer Chemenu-Instanz: Ein Agent installiert das neueste Release in ein leeres Verzeichnis, das du vorgibst. Die Schritte führt der Agent aus, nach instructions/setup-instance.md aus demselben Release. Hier steht, was du vorher bereitstellst, welchen Satz du ihm gibst, was er dich fragt und was zu tun ist, wenn er anhält. Die vollständige Kommandoreferenz steht in tools/CONTRACT.md.

Den optionalen MCP-Leseserver richtet docs/how-to/set-up-the-mcp-server.md ein: derselbe Korpus, lesend, für einen Konsumenten, der kein Terminal auf dieser Maschine ist.

Wer am Stack selbst arbeiten will, klont dieses Repo. Das ist eine Entwicklungsumgebung mit Demo-Korpus und keine Instanz; sie steht in docs/dev/development.md.

Was vorher da sein muss

Diese Programme prüft der Preflight, bevor irgendein wikitool-Befehl läuft. Installieren musst du sie selbst - der Agent tut es nie, auch nicht mit deiner Zustimmung. Wo eines fehlt, nennt der Preflight den Installationsbefehl für dein System. Die Liste wird aus tools/prerequisites.txt erzeugt, derselben Datei, die der Preflight liest:

• Python ≥ 3.11
• Git
• ripgrep (rg)

Dazu:

• Ein Agent-Harness: Claude Code, GitHub Copilot (in VS Code oder als CLI), Codex CLI oder Mistral Vibe.
• Ein leeres Verzeichnis, in dem die Instanz liegen soll, und dein Harness darin geöffnet. Leer heißt: nichts außer einem .git. Ein frisch geklontes, leeres Repo für deine Instanz ist also genau richtig - liegt dein Repo torben/nathan etwa in ~/src/nathan, installierst du dorthin, und der Agent übernimmt dessen origin als Ziel für publish.

Unter Windows zusätzlich, ebenfalls vom Preflight geprüft:

• PowerShell 7 (pwsh) ≥ 7

Und außerdem:

• PowerShell 7 als Standardterminal in VS Code. Windows PowerShell 5.1 reicht nicht, und WSL ist nicht vorgesehen.
• Execution Policy RemoteSigned - auf vielen Rechnern ab Werk gesetzt (Get-ExecutionPolicy -List zeigt es).
• Git for Windows. Es bringt Git Bash mit, in dem Claude Code seine Befehle ausführt.
• Ein Installationsverzeichnis mit höchstens 95 Zeichen, zum Beispiel C:\Chemenu. Windows erlaubt ohne eingeschaltete lange Pfade nur 259 Zeichen je Pfad, und die Dateien des Wikis brauchen den Rest. Wer Administratorrechte hat, kann stattdessen lange Pfade einschalten (LongPathsEnabled); verlangt wird das nicht.

Der Satz für den Agenten

Öffne das leere Verzeichnis in deinem Harness und gib dem Agenten diesen Satz:

Richte in diesem Verzeichnis eine neue Chemenu-Instanz ein. Hol dazu das neueste Release von https://gitea.nehmer.net/api/v1/repos/torben/chemenu/releases/latest und folge dessen Asset setup-instance.md. Lies vor dem Start des Preflights das Asset preflight.md aus demselben Release.

Damit liest der Agent die Beschreibung des neuesten Releases und daraus die beiden Anleitungen. Dann lädt er das passende Preflight-Skript (preflight.ps1 für PowerShell, preflight.sh für eine POSIX-Shell) mit einem Befehl seiner Shell ins Verzeichnis - nicht über den Browser, damit Windows die Datei nicht als „aus dem Internet“ markiert - und startet es. Das Skript lädt den Tarball desselben Releases, prüft dessen sha256, entpackt ihn in das Verzeichnis, löscht sich selbst und prüft dann im entpackten Baum, ob alles da ist.

Die Liste aller Releases: https://gitea.nehmer.net/torben/chemenu/releases. Das Repo ist öffentlich; der Download braucht weder Konto noch Token.

Was der Agent dich fragt

Raten darf der Agent keine dieser Antworten, und keine übernimmt er aus einem anderen Repo:

• **Autor-Identität** - Name und E-Mail für `git config`. Das ist zugleich der Autorname jeder künftig angelegten Wiki-Seite ($WIKI_AUTHOR überschreibt ihn bei Bedarf).
• **Remote** - bei einem leeren Klon nur die Bestätigung, dass origin stimmt; sonst eine URL, wenn du auf einen Server pushen willst. Ohne Remote bleibt die Instanz lokal, und jedes publish läuft mit --no-push.
• **Sprache und Ton der Seiten** - sie landen in kb/CONVENTIONS.md, dazu je Collection kb/<name>/COLLECTION.md. Fertige Profile, darunter ein vollständiges deutsches, hält instructions/kb-profiles.md bereit. Entscheide das vor dem ersten Ingest: Danach ist ein Wechsel der Abschnittsnamen eine Migration jeder bestehenden Seite. Titel, Wikilink-Ziele, Zitat-IDs, Schema-Werte, Tags, Befehle und Pfade folgen keiner Sprache - Act Runner heißt in jeder Instanz Act Runner.
• **Anwendungsgebiet** - woraus dieses Wiki seine Quellen zieht. Daraus schlägt der Agent eine source_type-Liste vor (bei einem Verein etwa Satzung, Protokoll, Spielbericht). Das ist ein Startpunkt, keine Festlegung: Später wird sie an echtem Bestand korrigiert (instructions/evolve-subtypes.md).
• **Personalisierung** - wer diese Instanz bedient (USER.md) und wie sie klingt (SOUL.md). Der Agent interviewt dich entlang der Vorlagen und schreibt deine Antworten wörtlich mit. Zwei Fragen beantwortest nur du: den Namen der Persona und die Themen, die bewusst draußen bleiben.
• **Umgebung** (optional) - Harness, MCP-Server, Remotes, damit spätere Sitzungen nicht erneut fragen. „Weiß ich nicht“ ist eine gültige Antwort.
• **Telemetrie** - standardmäßig aus; der Agent fragt nur, ob du sie einschalten willst.
• **Aufgaben-Tracker** (optional) - siehe docs/reference/configuration.md.

Am Ende legt der Agent den ersten Commit an. Dabei hält das Mass-Update-Gate an (Exit 42), weil eine neue Instanz aus weit mehr als zehn Dateien besteht. Das ist erwartet: Der Agent zeigt dir die Dateiliste und die --confirm-Zeile, und erst nach deiner Freigabe wird veröffentlicht. Danach startest du die Agent-Sitzung im selben Verzeichnis neu, damit sie die Skills lädt.

Wenn der Agent anhält

Der Preflight hält mit Exit 42 an, wenn du etwas tun musst. Seine Ausgabe nennt in einem nummerierten Block, was fehlt, warum, den Befehl, der es behebt, und wie es weitergeht. Der Agent zeigt dir diesen Block unverändert, setzt eine Übersetzung höchstens darunter und wartet. Sag ihm Bescheid, wenn du fertig bist; dann prüft er erneut. Ausweichen oder selbst installieren darf er nicht.

Beim Herunterladen und Entpacken (das Skript aus dem Release, bevor es einen Baum gibt):

• Werkzeuge zum Laden oder Entpacken fehlen (Exit 42). Unter Linux und macOS braucht das Skript curl, tar und sha256sum (oder shasum), unter Windows nur das tar.exe aus Windows 10/11. Installiere, was die Ausgabe nennt; unter Windows liefert Git for Windows alles für Git Bash mit.
• Das Verzeichnis ist zu lang (Exit 42, nur Windows ohne lange Pfade). Nimm ein kürzeres, etwa C:\Chemenu, öffne es im Harness und gib den Satz dort noch einmal.
• Das Verzeichnis ist nicht leer (Exit 1). Es darf nichts enthalten außer dem Skript und einem .git. Räume es selbst auf oder nimm ein anderes - der Agent löscht dort nichts.
• Download fehlgeschlagen oder Prüfsumme falsch (Exit 1). Es wurde nichts entpackt. Prüf die Internetverbindung und lass es erneut versuchen; einen anderen Download-Weg sucht der Agent nicht. Ohne direkten Download kannst du Tarball und .sha256 von der Release-Seite selbst nebeneinander ablegen; der Agent startet das Skript dann mit --archive <tarball>.

Im entpackten Baum (jeder weitere Lauf ist tools/preflight.sh bzw. unter PowerShell pwsh -NoProfile -ExecutionPolicy Bypass -File tools/preflight.ps1):

• Ein Werkzeug fehlt - Python, git, ripgrep, unter Windows auch PowerShell 7. Die Ausgabe nennt den Installationsbefehl für dein System. Ist es schon installiert, nur woanders, nenn dem Agenten den Pfad; er reicht ihn mit --set <werkzeug>=<pfad> weiter.
• Eine Version ist zu alt - zum Beispiel Python unter 3.11. Neuere Version installieren oder deren Pfad nennen.
• Ein genannter Pfad funktioniert nicht - der Pfad muss auf das Programm selbst zeigen, nicht auf seinen Ordner.
• Die Python-Umgebung (tools/.venv) oder ihre Bibliotheken ließen sich nicht einrichten. Die Ausgabe zeigt, was Python oder pip gemeldet haben. Meist blockiert ein Proxy oder ein Sicherheitsprogramm den Download; das klärt, wer deinen Rechner betreut.
• Skripte tragen die Markierung „aus dem Internet“ (nur Windows). Das passiert, wenn das Release im Browser geladen und im Explorer entpackt wurde. Einmal im Verzeichnis, in PowerShell 7: Get-ChildItem -Recurse -File | Unblock-File. doctor zeigt den Stand unter script-marks.
• Die Execution Policy verbietet Skripte (Restricted oder AllSigned, nur Windows). Die Ausgabe nennt die eine Zeile für ein PowerShell-7-Fenster (Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned). Setzt eine Gruppenrichtlinie sie, hilft nur die IT - oder du arbeitest aus Git Bash mit tools/wikitool. doctor zeigt den Stand unter execution-policy.
• Das Installationsverzeichnis ist zu lang (nur Windows ohne lange Pfade). Die Instanz muss in ein kürzeres Verzeichnis umziehen, etwa C:\Chemenu.

Hält der Agent an einer anderen Stelle an und ist die Ursache nicht offensichtlich, bietet er dir einen Fehlerbericht an - siehe docs/how-to/troubleshoot.md.

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), den Aufgaben-Tracker (.wikitool-tasks.json - fehlt sie, ist das OK; ist ein Provider konfiguriert, zusätzlich ob sein Lesepfad bereitsteht und seine API gerade antwortet, beides nie ein FAIL) 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

Danach

• Aktualisieren auf ein neueres Release: docs/how-to/update-an-instance.md.
• Konfiguration - Umgebungsvariablen und die Dateien pro Checkout: docs/reference/configuration.md.
• Wenn etwas nicht geht: docs/how-to/troubleshoot.md.
• Mit dem Wiki arbeiten: docs/how-to/.