torbenandClaude Opus 5.5
f9056c04f7
Files changed: - .gitea/workflows/ci.yml - .gitignore - .vibe/hooks.toml - AGENTS.md - CHANGES.md - EVALS.md - INSTALL-MCP.md - INSTALL.md - README.md - VERSION - docs/dev/development.md - docs/explanation/README.md - docs/explanation/architecture.md - docs/explanation/language-boundaries.md - docs/explanation/telemetry-and-evaluation.md - docs/how-to/README.md - docs/how-to/browse-with-obsidian.md - docs/how-to/capture-repository-docs.md - docs/how-to/export-guidelines.md - docs/how-to/ingest-a-source.md - docs/how-to/maintain-the-wiki.md - docs/how-to/query-the-wiki.md - docs/how-to/run-the-weekly-review.md - docs/how-to/set-up-the-mcp-server.md - docs/how-to/trace-and-score-sessions.md - docs/how-to/troubleshoot.md - docs/how-to/update-an-instance.md - docs/reference/README.md - docs/reference/commands/distribution-and-versioning.md - docs/reference/commands/instance-health.md - docs/reference/commands/raw-material-and-uploads.md - docs/reference/commands/telemetry.md - docs/reference/commands/types-instructions-and-docs.md - docs/reference/configuration.md - instructions/dev/dev-setup.md - instructions/dev/doc-pull-through.md - instructions/dev/stack-build/SKILL.md - instructions/dev/testing-conventions.md - instructions/dev/version-parts.md - instructions/setup-instance.md - instructions/upgrade-instance.md - reports/CONTRACT.md - tools/.coveragerc - tools/CONTRACT.md - tools/README.md - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/doctor.py - tools/chemenu/commands/eval_cmd.py - tools/chemenu/commands/git_publish.py - tools/chemenu/commands/upload_cmd.py - tools/chemenu/commands/version_cmd.py - tools/chemenu/evals/__init__.py - tools/chemenu/evals/scorecard.py - tools/chemenu/evals/trajectory.py - tools/chemenu/telemetry/policy.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_git_publish.py - tools/chemenu/tests/test_instructions_shell.py - tools/chemenu/tests/test_pipeline_l0.py - tools/chemenu/toc.py Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
195 lines
11 KiB
Markdown
195 lines
11 KiB
Markdown
# 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](tools/CONTRACT.md).
|
|
|
|
Den optionalen **MCP-Leseserver** richtet
|
|
[docs/how-to/set-up-the-mcp-server.md](docs/how-to/set-up-the-mcp-server.md) ein: derselbe
|
|
Korpus, lesend, für einen Konsumenten, der kein Terminal auf dieser Maschine ist.
|
|
|
|
<!-- dist:strip-start -->
|
|
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](docs/dev/development.md).
|
|
<!-- dist:strip-end -->
|
|
|
|
## 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:
|
|
|
|
<!-- wikitool:prerequisites -->
|
|
- **Python** ≥ 3.11
|
|
- **Git**
|
|
- **ripgrep (rg)**
|
|
<!-- /wikitool:prerequisites -->
|
|
|
|
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:
|
|
|
|
<!-- wikitool:prerequisites-windows -->
|
|
- **PowerShell 7 (pwsh)** ≥ 7
|
|
<!-- /wikitool:prerequisites-windows -->
|
|
|
|
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:
|
|
|
|
- <!-- setup-question: identity --> **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).
|
|
- <!-- setup-question: remote --> **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`.
|
|
- <!-- setup-question: kb-language --> **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`.
|
|
- <!-- setup-question: domain --> **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`).
|
|
- <!-- setup-question: personalization --> **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**.
|
|
- <!-- setup-question: environment --> **Umgebung** (optional) - Harness, MCP-Server, Remotes,
|
|
damit spätere Sitzungen nicht erneut fragen. „Weiß ich nicht“ ist eine gültige Antwort.
|
|
- <!-- setup-question: telemetry --> **Telemetrie** - standardmäßig aus; der Agent fragt nur, ob du
|
|
sie einschalten willst.
|
|
- <!-- setup-question: task-tracker --> **Aufgaben-Tracker** (optional) - siehe
|
|
[docs/reference/configuration.md](docs/reference/configuration.md#task-tracker).
|
|
|
|
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](docs/how-to/troubleshoot.md).
|
|
|
|
## Verifikation
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
tools/wikitool docs verify
|
|
tools/wikitool instructions verify
|
|
```
|
|
|
|
## Danach
|
|
|
|
- **Aktualisieren** auf ein neueres Release: [docs/how-to/update-an-instance.md](docs/how-to/update-an-instance.md).
|
|
- **Konfiguration** - Umgebungsvariablen und die Dateien pro Checkout:
|
|
[docs/reference/configuration.md](docs/reference/configuration.md).
|
|
- **Wenn etwas nicht geht:** [docs/how-to/troubleshoot.md](docs/how-to/troubleshoot.md).
|
|
- **Mit dem Wiki arbeiten:** [docs/how-to/](docs/how-to/README.md).
|