torben/chemenu
1
1 Fork 0
Code Issues 35 Pull Requests Actions Packages Releases 37 Activity

feat!: installation only from a release, into an empty folder; upstream merge/verify and private-instance.md removed, dist adopt, shell-neutral instructions (#153)
CI / verify (push) Successful in 5m19s
Details
CI / pwsh (push) Successful in 1m55s
Details
Release / release (push) Successful in 36s
Details

Browse Source 
Files changed:
- .gitea/workflows/ci.yml
- .gitea/workflows/release.yml
- AGENTS.md
- CHANGES.md
- DEVELOPMENT.md
- EVALS.md
- INSTALL.md
- README.md
- VERSION
- docs/ownership-and-templates.md
- instructions/CONTRACT.md
- instructions/bootstrap.md
- instructions/dev/dev-setup.md
- instructions/dev/stack-dev/SKILL.md
- instructions/gates.md
- instructions/ingest-large-tree.md
- instructions/kb-profiles.md
- instructions/mcp-read-server.md
- instructions/migrations/3.0.0-authoring-conventions.md
- instructions/preflight.md
- instructions/private-instance.md
- instructions/session-setup.md
- instructions/setup-instance.md
- instructions/upgrade-instance.md
- tools/CONTRACT.md
- tools/README.md
- tools/chemenu/cli.py
- tools/chemenu/cli_contract.py
- tools/chemenu/commands/dist_cmd.py
- tools/chemenu/commands/docs_verify.py
- tools/chemenu/commands/doctor.py
- tools/chemenu/commands/git_publish.py
- tools/chemenu/commands/upstream_cmd.py
- tools/chemenu/commands/work_cmd.py
- tools/chemenu/config.py
- tools/chemenu/ownership.py
- tools/chemenu/tests/test_cli.py
- tools/chemenu/tests/test_dist_cmd.py
- tools/chemenu/tests/test_instructions_shell.py
- tools/chemenu/tests/test_preflight.py
- tools/chemenu/tests/test_preflight_pwsh.py
- tools/chemenu/tests/test_run_budget.py
- tools/chemenu/tests/test_upstream_cmd.py
- tools/chemenu/toc.py
- tools/preflight.ps1
- tools/preflight.sh
This commit is contained in:
torben committed 2026-10-01 22:12:09 +02:00
1 parent d0f08d1fba
commit a6d07f97c4
46 files changed
+1314 -1936
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

INSTALL.md
+135 -182
View File
@@ -1,167 +1,154 @@
# 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
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** installiert und betreibt
[INSTALL-MCP.md](INSTALL-MCP.md): derselbe Korpus, lesend, für einen Konsumenten, der kein
Terminal auf dieser Maschine ist.
## Voraussetzungen
<!-- 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 [DEVELOPMENT.md](DEVELOPMENT.md).
<!-- dist:strip-end -->
- Python 3.11 oder neuer
- git
- [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) - wird von `search` und
`sources coverage` gebraucht
- Nur unter Windows zusätzlich: PowerShell 7 (`pwsh`). Windows PowerShell 5.1 reicht nicht, und
WSL ist nicht vorgesehen.
## Was vorher da sein muss
Ob das alles da ist, prüft der Preflight (`tools/preflight.sh`, unter Windows in PowerShell 7
`tools/preflight.ps1`), bevor irgendein
`wikitool`-Befehl läuft - der erste Schritt jeder Einrichtung, siehe
[instructions/preflight.md](instructions/preflight.md). Die maßgebliche Liste steht in
`tools/prerequisites.txt`. Fehlt etwas, hält der Agent an und zeigt eine Anleitung mit dem
Befehl, der es behebt; installieren muss man selbst, der Agent tut es nie.
- **Python 3.11 oder neuer, git und [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`).**
Die maßgebliche Liste steht in `tools/prerequisites.txt`; der Preflight prüft sie, bevor
irgendein `wikitool`-Befehl läuft. Installieren musst du selbst - der Agent tut es nie, auch
nicht mit deiner Zustimmung.
- **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`.
## Weg A: Release herunterladen
Unter Windows zusätzlich:
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:
- **PowerShell 7** (`pwsh`), in VS Code als Standardterminal eingestellt. 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.
```bash
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>
```
## Der Satz für den Agenten
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.
Öffne das leere Verzeichnis in deinem Harness und gib dem Agenten diesen Satz:
Statt dieser Befehle von Hand trägt jedes Release auch den Preflight selbst als Datei
(`preflight.sh`, unter Windows `preflight.ps1`). In einen leeren Ordner geladen und dort
gestartet, lädt er das Release herunter, prüft die Prüfsumme, entpackt es nach `chemenu/` neben
sich (mit `--into <Pfad>` woandershin; ein vorhandenes Ziel wird nie angefasst) und führt dann
den Preflight im entpackten Baum aus, siehe [instructions/preflight.md](instructions/preflight.md).
> 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.
Danach weiter mit Schritt 2 aus Weg B: den Agenten
[instructions/setup-instance.md](instructions/setup-instance.md) ausführen lassen. Der
entpackte Baum ist bereits eine Distribution - Schritt 1 (`dist export`) entfällt.
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 der Releases: <https://gitea.nehmer.net/torben/chemenu/releases>.
Die Liste aller Releases: <https://gitea.nehmer.net/torben/chemenu/releases>. Das Repo ist
öffentlich; der Download braucht weder Konto noch Token.
## Weg B: Neue, leere Instanz selbst exportieren
## Was der Agent dich fragt
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:
Raten darf der Agent keine dieser Antworten, und keine übernimmt er aus einem anderen Repo:
1. **Zielverzeichnis wählen** und die Distribution dorthin exportieren, aus einem Checkout
dieses Repos:
- **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 [Konfiguration](#konfiguration).
```bash
tools/wikitool dist export /pfad/zur/neuen/instanz
```
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.
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.
## Wenn der Agent anhält
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` - ohne das Flag
bricht `publish` mit Exit 1 ab, bevor es committet.
- **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**.
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.
Danach ist die Instanz initialisiert, verifiziert und committet.
**Beim Herunterladen und Entpacken** (das Skript aus dem Release, bevor es einen Baum gibt):
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`.
- **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>`.
## Weg C: Dieses Repo klonen
**Im entpackten Baum** (jeder weitere Lauf ist `tools/preflight.sh` bzw. unter PowerShell
`pwsh -NoProfile -ExecutionPolicy Bypass -File tools/preflight.ps1`):
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.
- **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`.
```bash
git clone https://gitea.nehmer.net/torben/chemenu.git
cd chemenu
```
Danach den Agenten `instructions/bootstrap.md` ausführen lassen (Preflight + 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](instructions/private-instance.md).
Hält der Agent an einer anderen Stelle an und ist die Ursache nicht offensichtlich, bietet er dir
einen Fehlerbericht an - siehe [Troubleshooting](#troubleshooting).
## 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.
nicht die ihres Inhalts. Sie steht in `VERSION`, daneben `.wikitool-release.json` mit Herkunft
und Exportdatum des Releases.
```bash
tools/wikitool version # was läuft hier, und woher kommt es
@@ -203,12 +190,6 @@ erreichbar, nennt die Fehlermeldung die Release-Seite, die `.wikitool-release.js
### 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](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.
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
@@ -245,8 +226,8 @@ auf demselben Host wie der Feed.
**Beim ersten Sprung auf ein Release, das `--latest` kennt, gibt es die Option in der Instanz
noch nicht** - die Instruktion, die dort steht, gehört zum Release, das die Instanz verlässt.
Dann den Tarball einmal von Hand holen (Weg A oben), prüfen und `dist upgrade <tarball>` geben;
ab dem Release danach trägt die Instanz `--latest` selbst.
Dann Tarball und `.sha256` einmal von der Release-Seite holen, nebeneinander ablegen und
`dist upgrade <tarball>` geben; ab dem Release danach trägt die Instanz `--latest` selbst.
**Beim ersten Sprung auf `4.5.0` oder höher gibt es `dist upgrade` in der Instanz noch nicht** -
es kam erst mit `4.5.0`. Dann das Werkzeug aus dem entpackten *neuen* Tarball verwenden, gegen die
@@ -275,7 +256,7 @@ sind. Einer Instanz, die älter ist als `.wikitool-kb.json`, fehlt die Datei gan
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.
Mit `<tarball-oder-verzeichnis>` lädt der Befehl selbst nichts herunter; die Datei muss vorher
aus Weg A geholt werden. Nur `--latest` lädt, und ein Tarball muss in beiden Fällen genau ein
von der Release-Seite geholt werden. Nur `--latest` lädt, und ein Tarball muss in beiden Fällen 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`
@@ -293,22 +274,20 @@ Ausnahmen (`kb/CONVENTIONS.md`, `kb/*/COLLECTION.md`, `.wikitool-kb.json`) in
| `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 | 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) |
| `WIKITOOL_UPDATE_TOKEN` | Gitea-Token für den Release-Feed | keiner - gegen `torben/chemenu` nicht nötig, nur gegen einen Feed in einem nicht öffentlichen Repo |
| `WIKITOOL_TASKS_CONFIG` | Pfad zu einer Tracker-Konfiguration, die `task`, `review` und `doctor` statt `.wikitool-tasks.json` lesen - um einen Checkout der Reihe nach gegen mehrere Tracker laufen zu lassen | die `.wikitool-tasks.json` im Repo-Root. Nennt die Variable eine Datei, die es nicht gibt, ist das ein Fehler und nie „kein Tracker konfiguriert" |
| `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` / `WIKI_TRACE_DIR` | Telemetrie abschalten bzw. aus dem Arbeitsbaum heraus umlenken | Aus - 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.
`version check`, `dist upgrade --latest` und die Installation 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**.
**Telemetrie ist in einer Instanz aus.** Jede Instanz trägt die `.wikitool-release.json` ihres
Releases, und daran erkennt `chemenu.telemetry.policy`, dass niemand Telemetrie bestellt hat.
Das gilt auch für jeden weiteren Klon der Instanz, weil die Datei mit dem ersten Commit ins Repo
kommt. Nur ein Klon des Ursprungs-Repos zur Entwicklung trägt keine; dort sind die Traces das
Messinstrument, mit dem der Stack sich selbst bewertet, und sie stehen auf **an**.
Wer den Default umdrehen will, legt `.wikitool-telemetry.json` im Repo-Root an (pro Checkout,
gitignored, kein `.template` - genau wie `.wikitool-remotes.json`):
@@ -322,18 +301,6 @@ Richtungen und schlägt diese Datei. `wikitool doctor` meldet den aktuellen Zust
warum, und die Menge gegen beide Deckel); mehr dazu in [EVALS.md](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:
```bash
export WIKITOOL_UPDATE_TOKEN="<gitea-token>"
tools/wikitool version check
```
**Tool-Pfade - schreibt der Preflight, nicht der Mensch.** `.wikitool-tools.json` im Repo-Root
hält die absoluten Pfade von Python, git und ripgrep, so wie der Preflight sie auf diesem Rechner
gefunden hat; `wikitool` startet git und rg von dort statt über `PATH`. Pro Checkout und
@@ -475,25 +442,16 @@ tools/wikitool instructions verify
Preflight ist in diesem Checkout noch nicht durchgelaufen, oder seit dem letzten Update nicht
mehr: `tools/preflight.sh` ausführen, siehe
[instructions/preflight.md](instructions/preflight.md). In PowerShell 7 unter Windows heißt der
Aufruf `pwsh -NoProfile -ExecutionPolicy Bypass -File tools/preflight.ps1`; das `-ExecutionPolicy Bypass` gilt nur für diesen
einen Prozess und ändert keine Einstellung.
- **Unter Windows meldet der Preflight die PowerShell-Ausführungsrichtlinie** (`Restricted` oder
`AllSigned`) - die Ausgabe nennt die eine Zeile, die man in einem PowerShell-7-Fenster ausführt
(`Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned`). Setzt eine
Gruppenrichtlinie sie, hilft nur die IT, oder man arbeitet aus Git Bash mit `tools/wikitool`.
`doctor` zeigt den Stand unter `execution-policy`.
- **Unter Windows meldet der Preflight „Mark of the Web“** - das Repo wurde mit dem Browser
geladen und im Explorer entpackt; Windows hält dann jede Datei für „aus dem Internet“ und
PowerShell verweigert die Skripte. Einmal im entpackten Ordner, in PowerShell 7:
`Get-ChildItem -Recurse -File | Unblock-File`. Wer mit `git clone` oder `Invoke-WebRequest`
lädt, hat die Markierung nicht. `doctor` zeigt den Stand unter `script-marks`.
Aufruf `pwsh -NoProfile -ExecutionPolicy Bypass -File tools/preflight.ps1`; das
`-ExecutionPolicy Bypass` gilt nur für diesen einen Prozess und ändert keine Einstellung. Was
seine Ausgabe dann bedeuten kann, steht unter [Wenn der Agent anhält](#wenn-der-agent-anhält).
- **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.
Den Personalisierungs-Schritt aus `instructions/setup-instance.md` ausführen lassen; bei einem
weiteren Klon einer älteren Instanz 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
@@ -526,8 +484,3 @@ tools/wikitool instructions verify
Urteil eines Modells und lässt einen Rest übrig - lies das Bündel vor dem Teilen. Die
Zuordnung, die Prüfliste und die Kandidatendatei enthalten Originale und liegen neben, nie im
Bündel. Es wird nirgends hochgeladen - den Kanal wählst du selbst.
- **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.