apairon
6aabd842e9
- AGENTS.md: neue Pflichtregel 'Ton in Fehlerabschnitten' (Tabelle Meldung|Bedeutung|Vorgehen; verbotene Muster + Ersatzformen) - anwender/*: 12 Seiten umgeschrieben - 'Wenn etwas schiefgeht'/'Wenn nicht alles klappt' -> 'Fehler'-Tabellen; 'bitte deine Betreuung/Teamleitung' -> konkrete Instanz mit Link; 'Zeichen fuer Zeichen', 'hoechstens drei Versuche', 'statt weiter zu raten' entfernt - hilfe.md komplett neu: Fehleruebersicht + Zustaendigkeiten als Tabellen (Titel 'Hilfe bei Stoerungen') - admin/ki-funktionen: Produkt-Zitat als solches belassen; projekt/audit-backup, sammlungen-anlegen, llm-nutzen entbelehrt - Belege nachgezogen: upload.maxBodySize/allowedMimeTypes, Konflikt = Unique-Index (409/500), Passwort-Reset in der Benutzerverwaltung - Build 71 Seiten gruen, 0 tote Links/Tabellen
77 lines
7.1 KiB
Markdown
77 lines
7.1 KiB
Markdown
# 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`.
|
||
- 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.
|
||
- `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.
|