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.

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.
• 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.
• 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).

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.