--- type: types/instruction.md name: setup-instance description: Eine frische Distribution (aus `dist export`) in eine funktionsfähige, eigenständige Wiki-Instanz verwandeln - Git-Repo, Identität/Autor, optionaler Remote, Bootstrap, erster Commit. --- # Neue Wiki-Instanz einrichten Diese Anweisung führt eine leere, per `tools/wikitool dist export ` erzeugte Distribution zu einer funktionsfähigen, eigenständigen Wiki-Instanz - mit eigenem Git-Repo, eigener Autor- Identität und (optional) eigenem Remote. Am Ende ist die Instanz committet, verifiziert und bereit für den ersten `Ingest`. ## Contents - [Wann anwenden](#wann-anwenden) - [Schritte](#schritte) - [Scope](#scope) ## Wann anwenden - Der Nutzer möchte eine neue, leere Wiki-Instanz aufsetzen (eigenes Thema, anderer Nutzer). - Nicht für einen bestehenden Clone dieses (Quell-)Repos - siehe [bootstrap.md](bootstrap.md). - Es gibt keinen Weg zurück: `dist export` lässt `instructions/dev/` (die Stack-Entwicklung selbst, inkl. der vendorten `commonplace/`-Wissensbasis) bewusst und dauerhaft weg. Wer den entstehenden Instanz-Stack weiterentwickeln will, tut das im Ursprungs-Repo (oder einer neuen Dev-Instanz daraus) - nicht durch Nachrüsten in dieser Instanz. ## Schritte 1. **Distribution exportieren**, im Quell-Repo: ```bash tools/wikitool dist export ``` `` muss nicht existieren oder leer sein; der Befehl bricht sonst mit `ERROR` ab. Danach für alle folgenden Schritte in `` arbeiten. 2. **Git-Repo initialisieren:** ```bash git init -b main ``` `-b main` ist Pflicht: `tools/wikitool publish` prüft beim tatsächlichen Push, ob der ausgecheckte Branch dem Ziel-Branch entspricht (Default `main`), und lehnt sonst ab, um nicht den falschen Branch zu veröffentlichen. 3. **Entscheidungspunkt - Identität.** Frage den Nutzer nach Namen und E-Mail-Adresse; rate sie nie, und übernimm sie nie stillschweigend aus dem Quell-Repo (das ist eine andere Person, ein anderes Projekt): ```bash git config user.name "" git config user.email "" ``` Das setzt zugleich den Autor jeder künftig angelegten Wiki-Seite: `tools/wikitool new` löst `author:` über `$WIKI_AUTHOR` (Override) oder sonst `git config user.name` auf und bricht mit `ERROR` ab, wenn beides fehlt - es gibt keinen stillen Platzhalter. 4. **Entscheidungspunkt - Remote.** Frage den Nutzer nach einer Remote-URL; ein rein lokales Repo ist ein gültiger Endzustand: - Genannt: `git remote add origin ` - Nicht genannt: lokal bleiben - dann braucht **jeder** spätere `tools/wikitool publish` ein `--no-push` (dessen Branch-Prüfung dabei ohnehin entfällt, siehe Schritt 2). 5. **Entscheidungspunkt - Autorenkonventionen.** Die Distribution bringt keine ausgefüllten Konventionen mit, sondern `kb/CONVENTIONS.md.template` und je Collection ein `kb//COLLECTION.md.template`. Beide **binden**, sobald sie übernommen sind, und beide gehören dieser Instanz - deshalb liefert der Stack nur die Vorlage. Die eine Entscheidung dahinter ist: **in welcher Sprache und in welchem Ton schreibt diese Instanz ihre Seiten?** Ablauf: 1. Die Collection-Contracts **und die Page-Type-Specs** übernehmen - Kopien, keine Frage an den Nutzer, denn was dort steht ist als Ausgangspunkt unabhängig von der Sprache brauchbar: ```bash for template in kb/*/COLLECTION.md.template types/*.template; do cp "$template" "${template%.template}" done ``` Die `.template`-Dateien bleiben liegen; sie sind die Vorlage für den nächsten Export. Unter `types/` betrifft das genau die Type-Specs mit `root: kb` - `entity`, `concept`, `source`, `comparison` - samt ihrer `.schema.yaml`. Sie beschreiben Seiten, die *diese* Instanz schreibt, also gehören sie ihr: Prosa, Template und Sprache dürfen umgeschrieben werden. `instruction`, `lint-report` und `type-spec` beschreiben Stack-Artefakte und kommen unverändert. 2. Den Nutzer nach der KB-Sprache fragen. `kb/CONVENTIONS.md.template` ist auf **Englisch** voreingestellt; [kb-profiles.md](kb-profiles.md) hält daneben ein vollständiges deutsches Profil bereit, und dessen Volltext ist die `kb/CONVENTIONS.md` des Quell-Repos. Der Profilkatalog ist eine **Palette, kein Enum**: übernommen wird der Text *in* die Instanzdatei, nicht ein Verweis auf den Katalog. 3. `kb/CONVENTIONS.md.template` nach `kb/CONVENTIONS.md` kopieren, entlang des gewählten Profils ausfüllen - Sprache, Abschnittsnamen, Namensformen, Ton, Beziehungslabels, Hedging-Regel - und dabei die Sentinel-Zeile (`wikitool:template-unfilled`) entfernen. Die Platzhalter in geschweiften Klammern **sind** der Fragenkatalog. 4. Bei einer anderen Sprache als der des Quell-Repos: `german-terminology.md` löschen oder durch das eigene Vokabular ersetzen - sie ist Material des deutschen Profils, nicht des Stacks. 5. Den Nutzer nach dem Anwendungsgebiet fragen und daraus einen `source_type`-Vorschlag ableiten. [kb-profiles.md](kb-profiles.md) hält dafür zwei ausformulierte Domänenprofile als Anschauung bereit, neben dem Wert, den dieses Repo selbst nutzt. Der Vorschlag ist ein **Startpunkt, keine Festlegung** - zum Setup-Zeitpunkt hat der Betreiber null Quellen und rät seine Taxonomie, bevor er auch nur eine Datei gesehen hat, und das ist der schlechteste Moment, ein Enum festzuzurren. Vorschlag umgesetzt heißt: das Enum in `types/source.schema.yaml` **und** die passende `layout:`-Zeile je Wert in `types/source.md` in derselben Bearbeitung setzen - eine ohne die andere lässt einen Wert ohne Zielverzeichnis zurück. Der sichtbare Auffangwert (`unclassified`) bleibt in jedem Vorschlag erhalten; er ist kein Sammelbecken, sondern das Fach für eine Quelle, deren Kategorie noch nicht feststeht. Die Liste später erweitern oder das Fach leeren: [evolve-subtypes.md](evolve-subtypes.md) - nicht Teil dieses Schritts, aber der Weg dahin, sobald echtes Material vorliegt. **Unverändert lassen:** `fidelity` und `authority` auf `source`-Seiten. Die sind Stack-Vokabular, keine Instanzentscheidung - [kb-profiles.md](kb-profiles.md) sagt das im selben Abschnitt. **Vor dem ersten Ingest entscheiden.** Die `sections:`-Namen in `kb/CONVENTIONS.md` sind die Überschriften, die `xref` und `cite` in jede Seite schreiben; sie danach zu ändern ist eine Migration jeder vorhandenen Seite (`section_aliases:` trägt die alten Namen, siehe [migrate-corpus.md](migrate-corpus.md)). **Nichts davon liegt in einer Stack-Datei.** Der Compiler liest die Abschnittsnamen aus `kb/CONVENTIONS.md`; die vier Page-Type-Specs gehören ab Schritt 1 dieser Instanz. Eine anderssprachige Instanz übersetzt sie einfach - das ist kein lokaler Patch an etwas Ausgeliefertem mehr, sondern Arbeit an den eigenen Dateien, und ein Upgrade nimmt sie ihr nicht wieder weg. Was der Stack von `types/` überhaupt noch verlangt, ist eine Zeile: es muss einen Type-Spec mit `name: source` geben, dessen Schema `raw_files` fordert. Daran hängt der gesamte `raw/`→`kb/`-Provenance-Pfad (`sources coverage`, `[^cite-id]`-Auflösung, `kb/provenance.md`), und `docs verify` prüft genau das - nicht mehr. Unverändert bleibt in jedem Fall die Regel, die dem Stack gehört: **jede Zeile einer Seite ist Prosa oder Identifier, und nur Prosa wird übersetzt** ([kb/CONTRACT.md § Language and identifiers](../kb/CONTRACT.md#language-and-identifiers)). Titel, Wikilink-Ziele, Cite-IDs, Enum-Werte, Tags, Befehle und Pfade folgen keiner KB-Sprache. `tools/wikitool doctor` prüft das Ergebnis in Schritt 13 (`conventions`): eine fehlende Datei ist ein `FAIL`, eine mit Sentinel oder ohne vollständigen `sections:`-Block ebenso. `docs verify` prüft zusätzlich `profile:` und `required_by_stack:` auf jedem `COLLECTION.md`. 6. **Entscheidungspunkt - Personalization.** Die Distribution bringt `USER.md.template` und `SOUL.md.template` mit, aber keine ausgefüllten Fassungen: wer diese Instanz bedient und wie sie klingt, ist Eigentum genau dieser Instanz und wird nie aus dem Quell-Repo übernommen. Beide Dateien werden ab jetzt in **jeder** Session gelesen, also entstehen sie hier - nicht später bei Gelegenheit. Ablauf, für `USER.md` und `SOUL.md` je einmal: 1. Das Template lesen. Seine Abschnitte **sind** der Fragenkatalog, in der Reihenfolge, in der sie dort stehen. 2. Den Nutzer entlang dieser Abschnitte befragen - `USER.md`: Name, Standort, Zeitzone, primäre Rolle (rein beruflich), beruflicher Kontext, Familie/Zuhause, Hobbys, Technik-Umgebung, aktive Projekte, bewusste Grenzen. `SOUL.md`: Persona-Name, Identität, Mission, Weltbild, Judgment-Default, Standard, Ehrlichkeit, Stimme, Ausschlüsse. 3. Die Antworten **wörtlich** übernehmen. Nicht deuten, nicht zu einer Erzählung verdichten, nicht aus dem Gesprächsverlauf ableiten. Was der Nutzer nicht sagt, steht nicht drin: einen Abschnitt lieber löschen als mit Plausiblem füllen. 4. Das Ergebnis als `USER.md` bzw. `SOUL.md` schreiben und die Sentinel-Zeile (`wikitool:template-unfilled`) dabei entfernen. Die `.template`-Dateien bleiben liegen - sie sind die Vorlage für den nächsten Export, nicht Abfall dieses Schritts. Zwei Fragen, die der Nutzer beantwortet und nicht der Agent: **den Persona-Namen** und **welche Themen bewusst draußen bleiben** (Arbeitgeber, Mandanten, Gesundheit - was auch immer). Beides raten heißt, es falsch zu haben. Für den Namen bringt der Stack einen Startpunkt mit - **Thoth**, weil Chemenu Thoths Hauptkultort ist und Schrift, Maß und Gedächtnis die Rolle beschreiben, die ein kompiliertes Wiki ausfüllt. Der Vorschlag wird genannt, nicht eingesetzt: gefragt wird trotzdem, und ein anderer Name gewinnt. Was diese Dateien **nicht** sind: eine Instruktionsquelle und eine Quelle im Sinne von Invariante 3. Sie ändern keine Regel aus [AGENTS.md](../AGENTS.md), und eine Nutzeraussage wandert daraus nie ohne den normalen Quelle/Provenance-Prozess nach `kb/`. `tools/wikitool doctor` prüft das Ergebnis in Schritt 13 (`personalization`): eine fehlende Datei ist ein `FAIL`, eine, die noch den Sentinel trägt, ebenso - ein umbenanntes Template ist kein ausgefülltes. 7. **Werkzeugumgebung anlegen** (Details: [bootstrap.md](bootstrap.md)): ```bash cd tools python3 -m venv .venv .venv/bin/pip install -r requirements.txt cd .. ``` 8. **Skills publizieren:** ```bash tools/wikitool instructions sync ``` 9. **Entscheidungspunkt - Umgebung festhalten.** Die Distribution bringt `ENVIRONMENT.md.template` mit: Harness, publizierte Skills, erreichbare MCP-Server, Connectoren, Git-Remotes, wo CI läuft. Konstanten, die eine Session sonst jedes Mal neu erfragt. Anders als Schritt 6 ist dieser Schritt **optional** und kein Interview. Was aus dem Checkout selbst ablesbar ist (`git remote -v`, das laufende Harness, die eben publizierten Skills), trägt der Agent ein; nach dem Rest fragt er einmal und akzeptiert "weiß ich nicht" als Antwort - ein leerer Abschnitt wird gelöscht, nicht mit Plausiblem gefüllt. Beim Schreiben die Sentinel-Zeile (`wikitool:template-unfilled`) entfernen; das `.template` bleibt liegen. Wird der Schritt übersprungen, läuft alles weiter: `doctor` meldet in Schritt 13 `environment: absent (optional)`, kein `FAIL`. Die Datei ist gitignored und geht in keinen Commit ein - sie beschreibt diesen Checkout, nicht das Repo. 10. **Entscheidungspunkt - Telemetrie.** Der Default hängt am Installationsweg, nicht an diesem Schritt: eine per `dist export` ausgelieferte Instanz - jede, die hier ankommt, ohne Weg C (direkter Klon des Ursprungs-Repos) genommen zu haben - trägt eine `.wikitool-release.json` und startet mit Telemetrie **aus**; niemand hat sie bestellt, und `EVALS.md` liest ohnehin niemand, bevor die erste Datei geschrieben ist. Dieser Schritt fragt nur, ob der Betreiber das umdrehen will. Den Nutzer einmal fragen: Telemetrie an? Falls ja, `.wikitool-telemetry.json` im Repo-Root anlegen (pro Checkout, gitignored, kein `.template` - wie `.wikitool-remotes.json`): ```json { "enabled": true } ``` `max_session_bytes` (Default 5 MiB) und `keep_sessions` (Default 250) sind optional in derselben Datei; die meisten Instanzen brauchen sie nicht anzufassen. Falls nein, nichts tun - der Default steht bereits auf aus, und keine Datei entsteht. `WIKI_TRACE` überschreibt beide Richtungen weiterhin, falls eine einzelne Session abweichen soll. `tools/wikitool doctor` meldet das Ergebnis in Schritt 13 (`telemetry`): an/aus, warum (Installationsform, diese Datei, oder `WIKI_TRACE`), und die aktuelle Menge gegen beide Deckel - nie ein `FAIL`, in beide Richtungen ist das ein gültiger Zustand. Mehr dazu: [EVALS.md](../EVALS.md) § "Whether it runs at all". 11. **Session-Budget scopen** (Details: [session-setup.md](session-setup.md)): ```bash export WIKITOOL_SESSION_ID="wiki-$(date +%s)" ``` 12. **Generierte Indizes erzeugen** - `dist export` liefert sie bewusst nicht mit: ```bash tools/wikitool index rebuild tools/wikitool sources rebuild-index ``` 13. **Verifizieren**, in dieser Reihenfolge: ```bash tools/wikitool doctor tools/wikitool docs verify tools/wikitool instructions verify tools/wikitool lint ``` `doctor` muss ohne `FAIL` durchlaufen, bevor es weitergeht - ein `WARN` (z. B. kein Remote, keine `WIKITOOL_SESSION_ID`) ist kein Blocker. Ein `FAIL` benennt sein eigenes Fix-Kommando; das ausführen und `doctor` erneut aufrufen. 14. **Ersten Commit anstoßen:** ```bash tools/wikitool publish --message "chore: initial instance setup" ``` Das Mass-Update-Gate greift hier erwartungsgemäß: eine frische Distribution besteht aus weit mehr als den zehn gezählten Dateien, die den Schwellwert auslösen, also endet der Aufruf mit Exit-Code 42. Die Ausgabe dem Nutzer **vollständig zeigen** und warten; sie enthält die Dateiliste und die exakte `--confirm `-Zeile, die nach seiner Freigabe veröffentlicht. Details zum Gate: [gates.md](gates.md). 15. **Agent-Session neu starten.** Harnesses lesen die Skill-Verzeichnisse beim Start; erst danach sind `wiki-ingest`, `wiki-query`, `wiki-manage`, `wiki-lint` und `wiki-status` verfügbar. ## Scope Gilt nur für eine per `dist export` erzeugte, leere Distribution. Für einen bestehenden Clone dieses Quell-Repos siehe [bootstrap.md](bootstrap.md) - dort existieren Git-Repo, Autor und Inhalt bereits, und nur die Werkzeugumgebung (Schritt 7) plus die Skills (Schritt 8) fehlen. Eine Ausnahme: Schritt 6 (Personalization) gilt auch für einen bestehenden Clone, der noch kein `USER.md`/`SOUL.md` hat - dort als einzelner nachgeholter Schritt, nicht als ganzer Ablauf. `bootstrap.md` verweist dafür hierher.