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

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

2.8 KiB Raw Blame History