diff --git a/INSTALL.md b/INSTALL.md index e7f2c35..f94c370 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,10 +1,11 @@ # 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](tools/CONTRACT.md). +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](tools/CONTRACT.md). ## Voraussetzungen @@ -16,19 +17,22 @@ Kommandoreferenz siehe [tools/CONTRACT.md](tools/CONTRACT.md). ## 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](#konfiguration)): +trägt genau einen `dist export`-Baum plus eine Prüfsumme. Das Repo ist öffentlich, der Download +braucht also weder Konto noch Token: ```bash BASE=https://gitea.nehmer.net/torben/chemenu/releases/download/v -curl -LO -H "Authorization: token $WIKITOOL_UPDATE_TOKEN" $BASE/chemenu-stack-.tar.gz -curl -LO -H "Authorization: token $WIKITOOL_UPDATE_TOKEN" $BASE/chemenu-stack-.tar.gz.sha256 +curl -LO $BASE/chemenu-stack-.tar.gz +curl -LO $BASE/chemenu-stack-.tar.gz.sha256 sha256sum -c chemenu-stack-.tar.gz.sha256 tar xzf chemenu-stack-.tar.gz cd chemenu-stack- ``` +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](instructions/setup-instance.md) ausführen lassen. Der entpackte Baum ist bereits eine Distribution - Schritt 1 (`dist export`) entfällt. @@ -82,10 +86,14 @@ Zwei Schritte, von denen nur der erste rein menschlich ist: ## Weg C: Dieses Repo klonen -Für Torbens Instanz selbst, oder einen Fork davon samt Inhalt: +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. ```bash -git clone +git clone https://gitea.nehmer.net/torben/chemenu.git cd chemenu ``` @@ -102,6 +110,21 @@ Checkout* beschreibt und nicht das Repo. Sie ist optional; wer sie anlegt, spart 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). + ## Version und Updates Jede Instanz trägt die Version des **Stacks** (Werkzeuge, Typen, Instruktionen, Contracts) - @@ -199,22 +222,23 @@ behält Schema und Shape. | `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](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) | +| `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) | -**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: +**Gegen das Ursprungs-Repo braucht es kein Token.** `torben/chemenu` ist öffentlich lesbar; +`version check` und der Download in Weg A funktionieren ohne Konfiguration. + +**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="" 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 ```bash @@ -259,6 +283,12 @@ tools/wikitool instructions verify sondern die Aufforderung, die Ausgabe einem Menschen zu zeigen: sie enthält die vollständige Dateiliste und die exakte `--confirm `-Zeile, die nach Freigabe veröffentlicht. Details: [instructions/gates.md](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