torben
6b300aa782
Files changed: - CHANGES.md - VERSION - instructions/evolve-subtypes.md - instructions/kb-profiles.md - instructions/setup-instance.md - kb/sources/COLLECTION.md
265 lines
14 KiB
Markdown
265 lines
14 KiB
Markdown
---
|
|
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 <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`.
|
|
|
|
## 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 <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:**
|
|
|
|
```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 "<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:
|
|
|
|
```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,
|
|
Confidence-Rubrik - 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 12 (`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/Confidence-Prozess nach `kb/`.
|
|
|
|
`tools/wikitool doctor` prüft das Ergebnis in Schritt 12 (`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 12
|
|
`environment: absent (optional)`, kein `FAIL`. Die Datei ist gitignored und geht in keinen
|
|
Commit ein - sie beschreibt diesen Checkout, nicht das Repo.
|
|
|
|
10. **Session-Budget scopen** (Details: [session-setup.md](session-setup.md)):
|
|
|
|
```bash
|
|
export WIKITOOL_SESSION_ID="wiki-$(date +%s)"
|
|
```
|
|
|
|
11. **Generierte Indizes erzeugen** - `dist export` liefert sie bewusst nicht mit:
|
|
|
|
```bash
|
|
tools/wikitool index rebuild
|
|
tools/wikitool sources rebuild-index
|
|
```
|
|
|
|
12. **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.
|
|
|
|
13. **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 <token>`-Zeile, die nach seiner Freigabe
|
|
veröffentlicht. Details zum Gate: [gates.md](gates.md).
|
|
|
|
14. **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.
|