# 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> ()` — 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](/admin/benutzer-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//.md` mit Frontmatter `title` + `description`. - **Sobald die Seite eine Starlight-Komponente nutzt (`` 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 `` 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 ```sh 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 `