apairon
1928922e07
- Audit: plans/doku-audit.md (Befunde, Phasen P1-P9, Ausführungsprotokoll) + plans/audit/ (8 Detailreports) + plans/offene-issues.md - Werkzeuge: scripts/audit-docs.mjs (Links/Anker/Bilder/Tabellen), scripts/gen-schema-matrix.mjs (npm run gen:schemas) - Neue Seiten: projekt/feld-rechte, reference/rest-system, reference/schema-properties, projekt/tests, 5 Anwender-Seiten - Fehler behoben: EMBEDDING_BGE_M3_*-Env, allowSnapshots, MCP-Scopes (.read/.create/.update), meta.views, loadAll-Signatur, OpenAPI-Endpunkt, MongoDB 8, Befehlspalette - Screenshots: 9 Admin + 10 Anwender aus Mock-Projekt corporate (t1 entfernt), 49 Bilder gesamt - AGENTS.md: Sync-Behauptung richtiggestellt, Belegpflicht/UI-Namen/Screenshot-Regeln, Werkzeug-Abschnitt - Build: 71 Seiten grün, 0 tote Links, 0 kaputte Tabellen
75 lines
6.2 KiB
Markdown
75 lines
6.2 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.
|
||
|
||
## 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.
|