torben/chemenu
1
1
Fork 0
Code Issues 24 Pull Requests Actions Packages Releases 32 Activity

stack: TOC-Scope auf types/ und docs/, Sprachregeln nach AGENTS.md zentralisiert, alle Templates auf Control-Plane-Sprache, --breaking akkumuliert (schliesst #99)
CI / verify (push) Successful in 45s
Details
Release / release (push) Successful in 36s
Details

Browse Source 
Files changed:
- AGENTS.md
- CHANGES.md
- ENVIRONMENT.md.template
- SOUL.md
- SOUL.md.template
- USER.md.template
- VERSION
- docs/ownership-and-templates.md
- docs/version-model.md
- instructions/CONTRACT.md
- instructions/dev/doc-pull-through.md
- instructions/dev/stack-close/SKILL.md
- instructions/dev/stack-dev/SKILL.md
- instructions/dev/version-parts.md
- instructions/setup-instance.md
- kb/CONVENTIONS.md
- kb/CONVENTIONS.md.template
- kb/concepts/COLLECTION.md
- kb/sources/COLLECTION.md
- tools/CONTRACT.md
- tools/chemenu/commands/types_cmd.py
- tools/chemenu/commands/version_cmd.py
- tools/chemenu/tests/test_toc.py
- tools/chemenu/tests/test_version_cmd.py
- tools/chemenu/toc.py
- tools/chemenu/version.py
- types/comparison.md
- types/concept.md
- types/entity.md
- types/lint-report.md
- types/source.md
This commit is contained in:
Torben Nehmer
2026-09-15 16:21:02 +02:00
parent c0dc2129bb
commit c64479fe02
31 changed files with 1093 additions and 603 deletions
Download Patch File Download Diff File Expand all files Collapse all files
instructions/setup-instance.md
+173 -180
View File
@@ -1,83 +1,83 @@
---
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.
description: Turn a fresh distribution (from `dist export`) into a working, self-contained wiki instance - git repo, identity/author, optional remote, bootstrap, first commit.
---
# Neue Wiki-Instanz einrichten
# Set up a new wiki instance
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`.
This instruction takes an empty distribution produced by `tools/wikitool dist export <target>`
and turns it into a working, self-contained wiki instance - with its own git repo, its own
author identity and (optionally) its own remote. At the end the instance is committed, verified
and ready for its first ingest.
<!-- wikitool:toc -->
## Contents
- [Wann anwenden](#wann-anwenden)
- [Schritte](#schritte)
- [When to run](#when-to-run)
- [Steps](#steps)
- [Scope](#scope)
<!-- /wikitool:toc -->
## Wann anwenden
## When to run
- 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.
- The user wants to set up a new, empty wiki instance (their own subject, a different person).
- Not for an existing clone of this (source) repo - see [bootstrap.md](bootstrap.md).
- There is no way back: `dist export` deliberately and permanently leaves out
`instructions/dev/` (stack development itself, including the vendored `commonplace/` knowledge
base). Anyone who wants to develop the resulting instance's stack further does that in the
origin repo (or a new dev instance made from it) - not by retrofitting it into this instance.
## Schritte
## Steps
1. **Distribution exportieren**, im Quell-Repo:
1. **Export the distribution**, in the source repo:
```bash
tools/wikitool dist export <ziel>
tools/wikitool dist export <target>
```
`<ziel>` muss nicht existieren oder leer sein; der Befehl bricht sonst mit `ERROR` ab. Danach
für alle folgenden Schritte in `<ziel>` arbeiten.
`<target>` must not exist, or must be empty; otherwise the command aborts with `ERROR`. Work
inside `<target>` for every step that follows.
2. **Git-Repo initialisieren:**
2. **Initialize the git repo:**
```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.
`-b main` is mandatory: on the actual push, `tools/wikitool publish` checks that the
checked-out branch matches the target branch (default `main`) and refuses otherwise, so that
the wrong branch is never published.
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):
3. **Decision point - identity.** Ask the user for their name and email address; never guess
them, and never quietly carry them over from the source repo (that is a different person and
a different project):
```bash
git config user.name "<Name>"
git config user.email "<E-Mail>"
git config user.name "<name>"
git config user.email "<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.
This also sets the author of every wiki page created from now on: `tools/wikitool new`
resolves `author:` from `$WIKI_AUTHOR` (an override) or else from `git config user.name`, and
aborts with `ERROR` when both are missing - there is no silent placeholder.
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).
4. **Decision point - remote.** Ask the user for a remote URL; a purely local repo is a valid
end state:
- Given: `git remote add origin <url>`
- Not given: stay local - then **every** later `tools/wikitool publish` needs a `--no-push`
(which also drops its branch check, see step 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?**
5. **Decision point - authoring conventions.** The distribution ships no filled-in conventions,
only `kb/CONVENTIONS.md.template` and one `kb/<name>/COLLECTION.md.template` per collection.
Both **bind** once adopted, and both belong to this instance - which is why the stack ships
the template alone. The one decision behind them is: **in which language and in what tone
does this instance write its pages?**
Ablauf:
Procedure:
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:
1. Adopt the collection contracts **and the page type-specs** - copies, no question to the
user, because what they say is usable as a starting point regardless of language:
```bash
for template in kb/*/COLLECTION.md.template types/*.template; do
@@ -85,110 +85,107 @@ bereit für den ersten `Ingest`.
done
```
Die `.template`-Dateien bleiben liegen; sie sind die Vorlage für den nächsten Export.
The `.template` files stay where they are; they are the source for the next 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.
Under `types/` this covers exactly the type-specs with `root: kb` - `entity`, `concept`,
`source`, `comparison` - along with their `.schema.yaml`. They describe pages *this*
instance writes, so they belong to it: prose, template and language may all be rewritten.
`instruction`, `lint-report` and `type-spec` describe stack artifacts and arrive
unchanged.
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.
2. Ask the user for the KB language. `kb/CONVENTIONS.md.template` defaults to **English**;
[kb-profiles.md](kb-profiles.md) additionally holds a complete German profile, whose full
text is the source repo's own `kb/CONVENTIONS.md`. The profile catalogue is a **palette,
not an enum**: what gets adopted is the text *into* the instance file, not a reference to
the catalogue.
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.
3. Copy `kb/CONVENTIONS.md.template` to `kb/CONVENTIONS.md`, fill it in along the chosen
profile - language, section names, naming forms, tone, relationship labels, hedging rule -
and remove the sentinel line (`wikitool:template-unfilled`) while doing so. The
placeholders in curly braces **are** the list of questions.
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.
4. For a language other than the source repo's: delete `german-terminology.md` or replace it
with your own vocabulary - it is material belonging to the German profile, not to the
stack.
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.
5. Ask the user about the subject area and derive a `source_type` proposal from it.
[kb-profiles.md](kb-profiles.md) holds two worked domain profiles as illustration, beside
the value this repo uses itself. The proposal is a **starting point, not a commitment** -
at setup time the operator has zero sources and is guessing a taxonomy before having seen
a single file, which is the worst possible moment to pin an enum down. Carrying out the
proposal means setting the enum in `types/source.schema.yaml` **and** the matching
`layout:` line per value in `types/source.md` in the same edit - one without the other
leaves a value with no target directory. The visible catch-all (`unclassified`) survives
every proposal; it is not a dumping ground but the slot for a source whose category is not
settled yet. Extending the list later, or emptying that slot:
[evolve-subtypes.md](evolve-subtypes.md) - not part of this step, but the way there once
real material exists.
**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.
**Leave unchanged:** `fidelity` and `authority` on `source` pages. Those are stack
vocabulary, not an instance decision - [kb-profiles.md](kb-profiles.md) says so in the
same section.
**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
**Decide before the first ingest.** The `sections:` names in `kb/CONVENTIONS.md` are the
headings `xref` and `cite` write into every page; changing them afterwards is a migration of
every existing page (`section_aliases:` carries the old names, see
[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.
**None of this lives in a stack file.** The compiler reads the section names from
`kb/CONVENTIONS.md`; the four page type-specs have belonged to this instance since step 1. An
instance in another language simply translates them - that is no longer a local patch to
something shipped, but work on its own files, and an upgrade does not take it away again.
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.
What the stack still requires of `types/` is one line: there must be a type-spec with
`name: source` whose schema requires `raw_files`. The entire `raw/`→`kb/` provenance path
hangs on it (`sources coverage`, `[^cite-id]` resolution, `kb/provenance.md`), and
`docs verify` checks exactly that - no more.
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.
What stays untouched in every case is the rule the stack owns: **every line of a page is
either prose or an identifier, and only prose is translated** ([kb/CONTRACT.md § Language and
identifiers](../kb/CONTRACT.md#language-and-identifiers)). Titles, wikilink targets, cite ids,
enum values, tags, commands and paths follow no KB language.
`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
`tools/wikitool doctor` checks the result in step 13 (`conventions`): a missing file is a
`FAIL`, and so is one carrying the sentinel or lacking a complete `sections:` block.
`docs verify` additionally checks `profile:` and `required_by_stack:` on every
`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.
6. **Decision point - personalization.** The distribution ships `USER.md.template` and
`SOUL.md.template`, but no filled-in versions: who operates this instance and how it sounds
is the property of this instance alone and is never carried over from the source repo. Both
files are read in **every** session from now on, so they come into being here - not later,
when the occasion arises.
Ablauf, für `USER.md` und `SOUL.md` je einmal:
Procedure, once each for `USER.md` and `SOUL.md`:
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.
1. Read the template. Its sections **are** the list of questions, in the order they appear.
2. Interview the user along those sections - `USER.md`: name, location, time zone, primary
role (professional only), professional context, family/home, hobbies, technical
environment, active projects, deliberate boundaries. `SOUL.md`: persona name, identity,
mission, worldview, judgment default, standard, honesty, voice, exclusions.
3. Take the answers **verbatim**. Do not interpret, do not compress into a narrative, do not
infer from the course of the conversation. What the user does not say does not go in:
better to delete a section than to fill it with something plausible.
4. Write the result as `USER.md` and `SOUL.md` respectively, removing the sentinel line
(`wikitool:template-unfilled`) in the process. The `.template` files stay where they are -
they are the source for the next export, not this step's leftovers.
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.
Two questions the user answers rather than the agent: **the persona name** and **which topics
deliberately stay out** (employer, clients, health - whatever they are). Guessing either
means getting it wrong. For the name the stack ships a starting point - **Thoth**, because
Chemenu is Thoth's principal cult site and writing, measure and memory describe the role a
compiled wiki fills. The suggestion is named, not applied: the question is asked anyway, and
a different name wins.
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/`.
What these files are **not**: a source of instructions, and a source in the sense of
invariant 3. They change no rule from [AGENTS.md](../AGENTS.md), and a user's statement never
travels from them into `kb/` without the normal source/provenance process.
`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.
`tools/wikitool doctor` checks the result in step 13 (`personalization`): a missing file is a
`FAIL`, and so is one still carrying the sentinel - a renamed template is not a filled-in
one.
7. **Werkzeugumgebung anlegen** (Details: [bootstrap.md](bootstrap.md)):
7. **Create the tool environment** (details: [bootstrap.md](bootstrap.md)):
```bash
cd tools
@@ -197,67 +194,63 @@ bereit für den ersten `Ingest`.
cd ..
```
8. **Skills publizieren:**
8. **Publish the skills:**
```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.
9. **Decision point - record the environment.** The distribution ships
`ENVIRONMENT.md.template`: harness, published skills, reachable MCP servers, connectors, git
remotes, where CI runs. Constants a session would otherwise ask about every time.
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.
Unlike step 6, this step is **optional** and not an interview. Whatever can be read off the
checkout itself (`git remote -v`, the running harness, the skills just published) the agent
fills in; for the rest it asks once and accepts "I don't know" as an answer - an empty
section is deleted, not filled with something plausible. Remove the sentinel line
(`wikitool:template-unfilled`) when writing; the `.template` stays where it is.
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.
If the step is skipped, everything still works: `doctor` reports
`environment: absent (optional)` in step 13, not a `FAIL`. The file is gitignored and enters
no commit - it describes this checkout, not the 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.
10. **Decision point - telemetry.** The default follows the installation path, not this step: an
instance delivered via `dist export` - every instance that arrives here without having taken
route C (a direct clone of the origin repo) - carries a `.wikitool-release.json` and starts
with telemetry **off**; nobody asked for it, and nobody reads `EVALS.md` before the first
file is written anyway. This step only asks whether the operator wants to reverse that.
Den Nutzer einmal fragen: Telemetrie an? Falls ja, `.wikitool-telemetry.json` im
Repo-Root anlegen (pro Checkout, gitignored, kein `.template` - wie
`.wikitool-remotes.json`):
Ask the user once: telemetry on? If yes, create `.wikitool-telemetry.json` in the repo root
(per checkout, gitignored, no `.template` - like `.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.
`max_session_bytes` (default 5 MiB) and `keep_sessions` (default 250) are optional in the
same file; most instances need not touch them. If no, do nothing - the default is already
off, and no file is created. `WIKI_TRACE` still overrides in both directions, should a
single session need to differ.
`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:
`tools/wikitool doctor` reports the result in step 13 (`telemetry`): on/off, why
(installation form, this file, or `WIKI_TRACE`), and the current volume against both caps -
never a `FAIL`, since both directions are a valid state. More on this:
[EVALS.md](../EVALS.md) § "Whether it runs at all".
11. **Session-Budget scopen** (Details: [session-setup.md](session-setup.md)):
11. **Scope the session budget** (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:
12. **Build the generated indexes** - `dist export` deliberately does not ship them:
```bash
tools/wikitool index rebuild
tools/wikitool sources rebuild-index
```
13. **Verifizieren**, in dieser Reihenfolge:
13. **Verify**, in this order:
```bash
tools/wikitool doctor
@@ -266,32 +259,32 @@ bereit für den ersten `Ingest`.
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.
`doctor` must run through without a `FAIL` before anything continues - a `WARN` (no remote,
no `WIKITOOL_SESSION_ID`, say) is not a blocker. A `FAIL` names its own fix command; run it
and call `doctor` again.
14. **Ersten Commit anstoßen:**
14. **Make the first commit:**
```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).
The Mass-Update Gate fires here as expected: a fresh distribution consists of far more than
the ten counted files that trip the threshold, so the call ends with exit code 42. Show the
output to the user **in full** and wait; it contains the file list and the exact
`--confirm <token>` line that publishes once they approve. Details on the 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.
15. **Restart the agent session.** Harnesses read the skill directories at startup; only
afterwards are `wiki-ingest`, `wiki-query`, `wiki-manage`, `wiki-lint` and `wiki-status`
available.
## 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.
Applies only to an empty distribution produced by `dist export`. For an existing clone of this
source repo see [bootstrap.md](bootstrap.md) - there the git repo, author and content already
exist, and only the tool environment (step 7) plus the skills (step 8) are missing.
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.
One exception: step 6 (personalization) also applies to an existing clone that has no
`USER.md`/`SOUL.md` yet - there as a single catch-up step, not as a whole procedure.
`bootstrap.md` points here for it.