chemenu/instructions/setup-instance.md

type, name, description

type	name	description
types/instruction.md	setup-instance	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 <ziel> 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
• Schritte
• 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.
• 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:

   tools/wikitool dist export <ziel>
   

   <ziel> muss nicht existieren oder leer sein; der Befehl bricht sonst mit ERROR ab. Danach für alle folgenden Schritte in <ziel> arbeiten.

2. Git-Repo initialisieren:

   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):

   git config user.name "<Name>"
   git config user.email "<E-Mail>"
   

   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 <url>
   • 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/<name>/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:

      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 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 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 - 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 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).

   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). 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, 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):

   cd tools
   python3 -m venv .venv
   .venv/bin/pip install -r requirements.txt
   cd ..
   

8. Skills publizieren:

   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):

    { "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 § "Whether it runs at all".

11. Session-Budget scopen (Details: session-setup.md):

export WIKITOOL_SESSION_ID="wiki-$(date +%s)"

12. Generierte Indizes erzeugen - dist export liefert sie bewusst nicht mit:

    tools/wikitool index rebuild
    tools/wikitool sources rebuild-index
    

13. Verifizieren, in dieser Reihenfolge:

    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:

    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 <token>-Zeile, die nach seiner Freigabe veröffentlicht. Details zum Gate: 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 - 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.