# AGENTS.md — Tibi Doku

Regeln für alle Agenten, die an dieser Doku oder an Tibi-Server / Tibi-Admin-Nova arbeiten.

## 1. Grundsatz

- **Single Source:** Code-Nähe schlägt Doku-Kopie. Details stehen in `tibi-server/docs/` bzw. `tibi-admin-nova/docs/`, diese Seite rendert nur.
- **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.
- **Sprache:** Deutsch, saubere Umlaute (ä ö ü ß), Du-Form für Anleitungen, kurze Sätze.

## 2. Wo was hingehört (Diátaxis) — Stand: Neuaufbau

Aktuell existiert nur `einstieg/`. Weitere Bereiche werden sauber neu aufgebaut;
pro Bereich Seite anlegen, Sidebar-Gruppe in `astro.config.mjs` ergänzen.

| Ordner | Inhalt | Beispiel |
|---|---|---|
| `einstieg/` | Tutorials, Erste Schritte | Schnellstart, Begriffe |
| `server/` (geplant) | **SYNC — nicht von Hand editieren**, Quelle `../tibi-server/docs/` | Collections, Hooks |
| `nova/` (geplant) | Teils SYNC aus `../tibi-admin-nova/docs/`, plus Konzeptseite | Sammlungen, Export |
| `anwender/` (geplant) | Redakteurs-Anleitungen (Aufgaben, keine Konzepte) | Anmelden, Pflegen |
| `reference/` (geplant) | **Generiert — nie von Hand**, OpenAPI/Typen/Schema | openapi.md |
| `adr/` (geplant) | Architektur-Entscheide, Format siehe Vorlage im Git-Verlauf (`adr/0000-vorlage.md`) | Starlight-Entscheid |

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

## 4. Sync-Workflow

```sh
# nach jeder Änderung in tibi-server/docs oder tibi-admin-nova/docs:
npm run sync
npm run build   # muss fehlerfrei durchlaufen
```

- `server/uebersicht.md` und `nova/konzept.md` sind Handarbeit und werden vom Sync nie überschrieben (`keep`) — beim Neuaufbau zuerst diese beiden Seiten neu anlegen, dann syncen.
- Sync-Artefakte werden mitcommittet (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.