Audit + Umbau: Faktenfehler behoben, Server-/Admin-Lücken geschlossen, 49 Screenshots, Schema-Matrix generiert

- 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
This commit is contained in:
apairon committed 2026-10-17 01:49:35 +00:00
1 parent 1897bb50d9
commit 1928922e07
104 files changed
+4756 -1044

No files matched your search

+27 -12
View File
@@ -12,20 +12,25 @@ Regeln für alle Agenten, die an dieser Doku, am Tibi-Server / tibi-admin oder a
- **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: Gerüst steht, Hüllen mit Arbeitsaufträgen
## 2. Wo was hingehört — Stand: ausgebaut (keine Hüllen mehr)
Jede Hüllen-Seite enthält Abschnitt „Für spätere Agenten“ mit Quelle-der-Wahrheit (Code zuerst), Prüfschritten und Ziel-Struktur. Hüllen abarbeiten heißt: Code prüfen, Seite befüllen, `Verifiziert am <Commit> <Datum>` ergänzen.
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/` | **SYNC — nicht von Hand editieren**, Quelle `../tibi-server/docs/`; dazu Handseiten Betrieb | Konfiguration, Sicherheit |
| `admin/` | Teils SYNC aus `../tibi-admin-nova/docs/`, plus Handseiten | Konzept, Editor, Exporte |
| `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), teils Code-Stand-Tabellen | Hook-Kontexte, Token-Köpfe |
| `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
@@ -33,19 +38,29 @@ Jede Hüllen-Seite enthält Abschnitt „Für spätere Agenten“ mit Quelle-der
- 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 für Anwender-Seiten: nur Mock-Projekt `corporate` (nie `t1`), Ablauf unter `plans/t-shots-arbeitsauftrag.md`.
- 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. Sync-Workflow
## 4. Werkzeuge und Prüfschritte
```sh
# nach jeder Änderung in tibi-server/docs oder tibi-admin-nova/docs:
npm run sync
npm run build # muss fehlerfrei durchlaufen
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)
```
- `server/uebersicht.md` und `admin/konzept.md` sind Handarbeit und werden vom Sync nie überschrieben (`keep`) — Sync-Ziel für Admin ist `src/content/docs/admin/` (Repo bleibt `tibi-admin-nova`).
- Sync-Artefakte werden mitcommittet (statischer Build braucht sie).
- `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