tibi-docs/AGENTS.md

AGENTS.md — Tibi Doku

Regeln für alle Agenten, die an dieser Doku, am Tibi-Server / tibi-admin oder an Projekten aus tibi-svelte-starter arbeiten.

0. Benennung und Blickwinkel

• Wir nennen es tibi-server und tibi-admin (Release Nova, Repo tibi-admin-nova). Alte tibi-admin-Repos werden ignoriert.
• Backend = tibi-server (API) + tibi-admin (Bedienoberfläche). Projekte sind eigenständige Websites/Shops/Intranet aus tibi-svelte-starter.
• Entwickler-Doku beschreibt Projektnutzung (klonen, konfigurieren, bauen), keine Tibi-Core-Entwicklung.

1. Grundsatz

• Single Source: Code-Nähe schlägt Doku-Kopie. Details stehen in tibi-server/docs/ bzw. tibi-admin-nova/docs/ (Doku-Begriff: tibi-admin), diese Seite rendert nur. Code schlägt Doku: Bestandsdoku gilt als Behauptung, Quelle ist der Code (internal/*, tibi-types/schemas, frontend/src/lib, Tests, Test-Pläne).
• Definition of Done: Jede PR an tibi-server oder tibi-admin-nova, die API, Hooks, Collections, Permissions, Jobs, Realtime, LLM, Deploy oder UX ändert, aktualisiert auch die Docs — sonst ist die PR nicht fertig.
• Belegpflicht: Jede prüfbare Aussage trägt einen Stempel am Seitenende (ausgenommen: index.mdx, adr/0000-vorlage.md, ADRs ohne prüfbaren Inhalt und generierte Seiten wie reference/schema-properties.md): Verifiziert am <7-stelliger-hash> <JJJJ-MM-TT> (<repo>) — mehrere Quellen als Liste. Kein Hash ohne Prüfung, kein Datum ohne Prüftag.
• UI-Namen wörtlich: Jeder fett oder „zitierte" Bedienname muss wörtlich in ../tibi-admin-nova/frontend/src/lib/i18n/locales/de.json stehen. Findet man keinen String, beschreibt man die Wirkung („der Knopf oben rechts") statt einen Namen zu erfinden.
• Sprache: Deutsch, saubere Umlaute (ä ö ü ß), Du-Form, kurze Sätze. Ton: per Du, aber professionell — sachlich wie ein gutes Handbuch, niemals Babysprache. Keine belehrenden Binsen („wenn du nichts findest, verändere die Suche"), keine Verniedlichung („keine Angst"), keine erfundenen Floskeln. UI-Namen immer wörtlich aus de.json bzw. Screenshot. Anweisungen nennen den exakten Klickpfad; „Was-tun-wenn" nur für echte, am Code belegte Fälle.
• Ton in Fehlerabschnitten (verbindlich): Der Leser ist erwachsen und fachlich. Störungen werden als Tabelle beschrieben: Meldung | Bedeutung (Ursache) | Vorgehen. Verboten sind: „Wenn etwas schiefgeht", „Wenn nicht alles klappt", Arbeit für den Leser erfinden („notiere Aktion, Uhrzeit und Fehlermeldung"), Erziehungsfloskeln („prüfe Zeichen für Zeichen", „Feststelltaste beachten", „statt weiter zu raten", „höchstens drei Versuche"), Warnungen an die Vernunft („nicht blind", „doppelt anlegen vermeiden") und Verweise auf Betreuungspersonen („bitte deine Betreuung/Teamleitung um Prüfung/Freischaltung"). Stattdessen: Ursache benennen und die Instanz, die es löst — z. B. „Dafür ist das Recht allowSnapshots nötig; es wird am Projekt-Admin-Token gesetzt (Benutzer und Rechte)". Nebenwirkungen sachlich benennen: „Der Lauf ist nicht abbrechbar; ein zweiter Lauf löst Versand und Berechnung erneut aus."

2. Wo was hingehört — Stand: ausgebaut (keine Hüllen mehr)

Jede Seite nennt ihre Quelle-der-Wahrheit (Code zuerst), hat einen Stempel am Ende und mindestens einen Querverweis auf verwandte Seiten. Neue Fähigkeiten bekommen genau eine Dokustelle (Tabelle unter §3 „Vollständigkeit").

Ordner	Inhalt	Beispiel
einstieg/	Tutorials, Erste Schritte (Projekt-Blick)	Schnellstart, Neues Projekt, Begriffe
projekt/	Projekt-Entwickler baut eigenständige Website (Sammlungen → Deploy)	Hooks, SSR, Suche
server/	Handseiten (deutsch): Server-Sicht für Projekt-Entwickler und Betreiber. Die englische Core-Referenz liegt in ../tibi-server/docs/ und wird nicht synchronisiert	Konfiguration, Sicherheit
admin/	Handseiten (deutsch) zur Bedienoberfläche tibi-admin, teils mit Bezug auf ../tibi-admin-nova/docs/	Konzept, Editor, Exporte
anwender/	Redakteurs-Anleitungen im Verwaltungs-Backend (Aufgaben, keine Konzepte)	Anmelden, Medien
reference/	Teils generiert — nie von Hand (openapi, schema-properties), teils Code-Stand-Tabellen	Hook-Kontexte, Token-Köpfe
adr/	Architektur-Entscheide, Format siehe adr/0000-vorlage.md	Code-schlägt-Doku

3. Neue Seite anlegen

• Datei src/content/docs/<bereich>/<slug>.md mit Frontmatter title + description.
• Sobald die Seite eine Starlight-Komponente nutzt (<Aside>, <Steps>, <Tabs>, <Card>, <LinkCard>, <Badge>, <FileTree>), muss die Datei .mdx heißen. In reinem Markdown (.md) werden Komponenten-Tags nicht gerendert: sie landen als unbekannte HTML-Tags im Ergebnis, und die import-Zeile erscheint als sichtbarer Text auf der Seite (scripts/audit-docs.mjs prüft das gegen dist/).
• MDX-Regeln, die die Konvertierung erfüllen muss:
  • import … steht als erste Zeile vor dem Inhalt (nach dem Frontmatter).
  • Block-Komponenten: öffnendes Tag in eigener Zeile, Inhalt, schließendes Tag in eigener Zeile (nicht Text</Aside> in einer Zeile).
  • Kommentar-Hinweise als {/* … */} schreiben, nicht als <!-- … -->.
  • Geschweifte Klammern im Fließtext escapen (\{count\}) — in Code-Spans und Codeblöcken nicht nötig.
• Sidebar: jede Gruppe explizit in astro.config.mjs eintragen (beim Neuaufbau pro Bereich ergänzen; autogenerate erst nutzen, sobald der Ordner gepflegt befüllt ist).
• Bilder nach src/assets/, max. 200 KB, deutsche Alt-Texte.
• Screenshots: nur Mock-Projekt corporate (nie t1), Ablauf unter plans/t-shots-arbeitsauftrag.md. Anwender-Bilder nach src/assets/anwender/, Admin-Bilder nach src/assets/admin/, je ≤ 200 KB (WebP, 1440×900), deutscher Alt-Text im Markdown. Offene Motive stehen als <!-- Screenshot (T-SHOTS): … --> in der Seite.
• Vollständigkeit: neue Fähigkeit braucht genau eine Dokustelle — Tabelle in plans/doku-ausbau.md („Vollständigkeit") miterweitern.

4. Werkzeuge und Prüfschritte

node scripts/audit-docs.mjs   # Pflicht vor jedem Push: Frontmatter, Codeblöcke, Links, Anker, Bilder, Tabellen, Stil-Marker
npm run coverage              # Coverage-Inventar (Routen, Hook-Kontexte, MCP-Tools, Schemas, Komponenten)
npm run gen:schemas           # erzeugt reference/schema-properties.md aus ../tibi-types/schemas/config
npm run sync:openapi          # holt die OpenAPI-Spec (braucht TIBI_NAMESPACE und laufenden tibi-server)
npm run build                 # muss grün durchlaufen (prüft interne Links NICHT)

• scripts/audit-docs.mjs meldet tote Links/Anker, kaputte Tabellen, fehlende Alt-Texte und offene Platzhalter-Marker. Ergebnis muss „0 tote Links, 0 kaputte Tabellen" sein; verbleibende Marker sind zu begründen.
• Zusätzlich prüft das Skript das gebaute dist/: geleakte import-Zeilen, rohe <Aside>/<Steps>-Tags und fehlende Komponenten-Klassen. Erst npm run build, dann node scripts/audit-docs.mjs — so fällt auf, wenn eine Seite als .md statt .mdx angelegt wurde.
• scripts/gen-schema-matrix.mjs und reference/schema-properties.md sind ein Paar: Seite nie von Hand editieren, Schemas nie in der Doku nachpflegen — nur npm run gen:schemas laufen lassen.
• scripts/sync-server-docs.mjs ist stillgelegt (der Server-Sync erzeugte verwaiste Seiten ohne Sidebar-Eintrag). Nicht mehr aufrufen; die Datei wird entfernt, sobald niemand sie vermisst.
• server/uebersicht.md und admin/konzept.md sind Handarbeit.
• Screenshots werden mitgeliefert (statischer Build braucht sie).
• Nach Umbenennungen/Slug-Änderungen: astro dev (Container tibi-docs-docs-1) hält den Content-Graph im Speicher und teilt sich .astro/ mit astro build — sonst bricht der Dev-Server mit „slug … does not exist" ab. Deshalb docker restart tibi-docs-docs-1 und die Routen erneut prüfen (Ablauf in plans/doku-audit.md §18).

5. Verbote

• Keine Secrets, Tokens, Kundennamen oder interne Hosts in die Doku.
• Keine englischen Server-Docs duplizieren und übersetzen — lieber verlinken und bei Bedarf eigene deutsche Einstiegsseite.
• Keine toten Links: der Build prüft interne Links nicht — nach jeder Link-Änderung alle Links der Seite anklicken (lokal oder Code-URL), erst dann pushen.

6. Theming

• src/styles/custom.css ist an Nova angelehnt (Inter, --sl-color-accent Near-Black, Nova-Orange #c2410c als Zweitakzent). Farben nur dort ändern, nicht inline.
• Logo/Favicon: src/assets/favicon.svg (Nova-Supernova). Austausch nur gegen offizielles Nachfolge-Logo.