Chemenu 2.1.0 - deterministischer Wissenskompiler
Chemenu kompiliert Rohnotizen zu einem verlinkten, quellengebundenen Wiki: raw/ -> types/ + tools/ -> kb/ -> reports/. Was mechanisch ist, macht tools/wikitool; was Urteil braucht, macht ein Agent unter Contracts, deren Grenzen in Code durchgesetzt sind statt im Prompt. Dieser Commit ist der Startpunkt der oeffentlichen Historie. Die vorherige Entwicklung fand in einer privaten Instanz statt und ist nicht Teil dieses Repositorys; ihre Erzaehlung steht vollstaendig in CHANGES.md, das mit 44 Eintraegen von 0.1.0 bis 2.1.0 erhalten geblieben ist. Der mitgelieferte Korpus ist ein Testbett und eine Demo: 170 Seiten ueber den Stack selbst - Gates, Lint, Versionierung, Suche, das Wiki-Muster. Er dokumentiert das Werkzeug mit den eigenen Mitteln des Werkzeugs. Lizenz: AGPL-3.0 fuer den Stack (tools/, types/), CC-BY-4.0 fuer die Inhalte. Die Grenze zwischen beiden ist der Dateiplan, den dist export berechnet - siehe NOTICE.
This commit is contained in:
@@ -0,0 +1,199 @@
|
||||
---
|
||||
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 - KB-Sprache.** Frage den Nutzer, in welcher Sprache die Seiten unter
|
||||
`kb/` geschrieben werden sollen. Diese Instanz erbt aus dem Quell-Repo **Deutsch** - sowohl die
|
||||
Regel in [kb/CONTRACT.md](../kb/CONTRACT.md#language) als auch das Vokabular in
|
||||
[german-terminology.md](german-terminology.md) und die deutschen Abschnittsnamen in
|
||||
`tools/chemenu/sections.py`. Das ist eine Entscheidung der Ursprungsinstanz, keine
|
||||
Eigenschaft des Musters, und sie wird hier nicht stillschweigend weitergereicht.
|
||||
|
||||
- **Deutsch bestätigt:** nichts zu tun.
|
||||
- **Andere Sprache:** *vor dem ersten Ingest* umstellen, denn danach ist es eine Migration
|
||||
jeder vorhandenen Seite. Zu ändern sind der Abschnitt "Language" in `kb/CONTRACT.md`, die
|
||||
Tonfall-Beispiele und Hedge-Wörter darunter, die vier Page-Type-Templates in `types/`, die
|
||||
kanonischen Namen in `sections.py` (die bisherigen als Alias behalten) und die
|
||||
Beziehungslabels in `kb/CONTRACT.md` § Linking. `german-terminology.md` wird dann ersetzt
|
||||
oder gelöscht.
|
||||
|
||||
Unverändert bleibt in jedem Fall die eigentliche Regel: **jede Zeile einer Seite ist Prosa
|
||||
oder Identifier, und nur Prosa wird übersetzt.** Titel, Wikilink-Ziele, Cite-IDs, Enum-Werte,
|
||||
Tags, Befehle und Pfade folgen keiner KB-Sprache.
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user