Wie dieses Handbuch aktuell bleibt

Dokumentation veraltet nicht, weil jemand nachlässig ist, sondern weil dieselbe Aussage an zwei Stellen steht und nur eine geändert wird. Dieses Handbuch hält deshalb je Aussage eine Quelle und lässt Wächter prüfen, was sich prüfen lässt. Was sich nicht prüfen lässt, steht hier ausdrücklich.

Eine Quelle je Aussage

Aussage	Quelle	Wie sie in die Seiten kommt
Verbindliches Verhalten	docs/spec/	verlinkt, nie abgeschrieben; bei Widerspruch gewinnt die Spec
Code, den eine Seite zeigt	die Datei im Repo, die auch gebaut wird (examples/first-app, Register der Apps)	Source.astro bindet sie wörtlich ein
Was eine Fläche tut	die Story im Storybook, mit den echten Toolkit-Komponenten	Story.astro bettet sie ein; die Id wird gegen den gebauten Index geprüft
Alle Hooks	der Dokumentationsblock über jedem exportierten Hook	pnpm docs:hooks erzeugt all-hooks.json, Storybook rendert sie
Pakete, Spec-Liste, Einstiege für Agenten	package.json der Pakete, docs/spec/README.md, all-hooks.json, examples/first-app	pnpm docs:agents erzeugt llms.txt und den Code-Block des App-Templates
Begriffe	das Begriffsregister der Familie (SKOS, docs/reference/rls.skos.jsonld)	Glossar-Seite, im Aufbau
Stand des Builds	Git-Commit, Versionen von App und Toolkit	prepare.mjs schreibt build-info.json, die Fußzeile zeigt es

Die Wächter

Jede Seite nennt im Frontmatter die Dateien, aus denen sie ihre Aussagen zieht (sources) und die Stories, die sie einbettet (stories). pnpm check:site fällt, wenn eine Quelldatei fehlt, eine Story-Id nicht im gebauten Storybook-Index steht, eine eingebettete Story nicht deklariert ist, ein Link zwischen Seiten ins Leere führt oder eine Übersetzung veraltet ist. Nach dem Build prüft es dazu jeden lokalen Link der fertigen Site. pnpm test:site prüft, dass der Wächter absichtlich beschädigte Seiten erkennt.

pnpm check:hooks und pnpm check:agents prüfen dasselbe für die erzeugten Teile: Ein exportierter Hook ohne vollständigen Block, eine Story-Id, die es nicht gibt, ein Paket ohne Beschreibung, oder eine erzeugte Datei, die nicht mehr zum Repo passt, macht CI rot. Alle laufen in .github/workflows/tests.yml; die Übersicht steht unter Mit Agenten arbeiten → Die Prüfungen.

Was automatisch mitwandert, und was nicht

Ändert sich eine Komponente, ändert sich ihre Story, und damit das Bild auf der Seite. Ändert sich das Beispiel, ändert sich der gezeigte Code. Ändert sich ein Hook-Kommentar, ändert sich die Referenz. Wird eine Quelldatei umbenannt oder gelöscht, fällt der Wächter.

Nicht automatisch: ob ein Satz noch stimmt. Wenn sich ein Verhalten ändert, das eine Seite beschreibt, meldet kein Wächter das; das ist die Dokumentationswirkung, die jeder PR benennt (Zusammen am Stack arbeiten). Besonders bei Berechtigungen, Datenhaltung und Deployment prüft ein Mensch.

Zwei Zugänge, dieselben Seiten

Die Site liest docs/handbook/<sprache>/; die Seiten liegen im Repo, damit sie im PR gelesen werden wie die Spec. Vor jedem Build schreibt prepare.mjs dieselben Seiten als Markdown nach /markdown/<sprache>/<seite>.md (eingebetteter Code ausgeschrieben, Stories als Links) und hängt sie an /llms.txt. Agenten lesen also, was Menschen lesen, nicht eine Kurzfassung.

Deutsch zuerst, Englisch danach

Deutsch ist die Wurzel (/handbuch/…), jede weitere Sprache ein Präfix (/en/handbuch/…). Eine Übersetzung nennt im Frontmatter ihre deutsche Quelle (translationOf) und deren Hash zum Zeitpunkt der Übersetzung (sourceHash). Ändert sich die deutsche Seite, stimmt der Hash nicht mehr, und der Wächter meldet die Übersetzung als prüfbedürftig. Eine Seite, die es nur auf Deutsch gibt, verlinkt der englische Index als deutsche Seite; Platzhalter gibt es nicht.

Lokal arbeiten

pnpm dev:site                                        # Vorschau mit Live-Reload, Stories aus dem laufenden Storybook (6006)
pnpm build:storybook && pnpm build:site && pnpm check:site && pnpm test:site
pnpm preview:site                                    # die gebaute Site, wie sie deployt wird

Deployt wird die Site zusammen mit Storybook und App aus deploy-prototypes.yml; die Fußzeile jeder Seite nennt Commit und Versionen des Standes, den du siehst.