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](/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/<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

```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 `<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.