tibi-docs/plans/doku-ausbau.md

# Doku-Ausbau: Plan und Status

Lebendes Dokument. Der Orga-Agent aktualisiert Status, Sessions und Second-Opinion-Ergebnisse nach jedem Schritt. Stand: 2026-10-17.

## Regeln (kurz)

- Benennung: **tibi-server**, **tibi-admin** (Release Nova, Repo `tibi-admin-nova`). Projekte = eigenständige Websites/Shops/Intranet aus `tibi-svelte-starter`.
- Dev-Doku = Projektnutzung, keine Core-Entwicklung. Ton: Deutsch, Du-Form, kurze Sätze.
- Keine lange Prosa: Tabellen, Listen, Steps, Tabs, Code-Beispiele, Starlight-Komponenten.
- Code schlägt Doku: jede Aussage am Code verifiziert, Stempel `Verifiziert am <Commit> <Datum>`.
- `npm run build` in tibi-docs bleibt immer grün. Keine toten Links.

## Themenpakete

| Paket | Seiten | Agent | Status | Second Opinion | Abnahme |
|---|---|---|---|---|---|
| T-REF Referenz | schemas, hook-kontexte, token-köpfe, fehlercodes | general ses_ebb2308e0ffeybmgl7oG1Eyn0b | ✅ fertig | ✅ SO eingearbeitet (16 Schemas, 409/500-Legacy-Default, Login-Pfad) | Build + Links ✅ |
| T-PROJ-A Projekt Kern | sammlungen-anlegen, felder-widgets, abfragen-lesen, rechte-tokens | general ses_ebb2308d4ffev0H1z4mvNfsw5k | ✅ fertig | ✅ SO eingearbeitet (_count/_facet-Routen, required name+permissions, 25 Widgets) | Build + Links ✅ |
| T-PROJ-B Projekt Logik | hooks-schreiben, dateien-bilder, navigation-i18n, suche | general ses_ebb0d36b6ffeJ44pbErML0Z4X9 | ✅ fertig | ✅ SO eingearbeitet (SSR-Cache vs Dependencies, topK + YAML-rrf-Block) | Build + Links ✅ |
| T-PROJ-C Projekt Ship | ssr-website, jobs-actions, audit-backup, deploy | general ses_ebb0d36a7ffeY76nGYPhP0U5xR | ✅ fertig | ✅ SO eingearbeitet (cron-Pflicht korrigiert, Snapshot-Zitat + tags-Typo) | Build + Links ✅ |
| T-SERVER Server-Hand | konfiguration, betrieb, sicherheit, schnittstellen | general ses_ebb2308d3ffeCTZqqtzMszuDnH | ✅ fertig | ✅ SO eingearbeitet (MCP-Route fest, CORS-Merge, 429, kein Abo-Endpunkt) | Build + Links ✅ |
| T-ADMIN-A Admin I | ansichten-listen, eintrags-editor, medien, exporte | general ses_ebb0d36a5ffe0n1PbsS1E6V5HM | ✅ fertig | ✅ SO eingearbeitet (Custom-Export: db.loadAll/ctx.xlsx/contentType+blob, qm-Param) | Build + Links ✅ |
| T-ADMIN-B Admin II | aktionen, benutzer-rechte, ki-funktionen, setup, customizing | general ses_ebad2bf8affeZ9uV0HzJf2k357 | ✅ fertig | ✅ SO eingearbeitet (Test-Pläne 40/42 verlinkt, Widget-Enum klargestellt, toter Anker gefixt) | Build + Links ✅ |
| T-ANW-A Anwender I | anmelden, orientierung, lesen-suchen-filtern, eintrag-bearbeiten, medien | general ses_ebad2bf77ffeQm3uhj279Qrc09 | ✅ fertig | ✅ SO eingearbeitet (/ statt Strg+K, „Dateien hinzufügen", Tabelle statt Zeilen, Duplikat-Aside) | Build + Links ✅ |
| T-ANW-B Anwender II | seiten-bauen, benutzer-teams, exportieren, sichern, hilfe | general ses_ebad2bf75ffezS1KTRTQDO5GT5 | ✅ fertig | ✅ SO eingearbeitet (Snapshot-Reiter, „Exportieren", Benutzerverwaltung, echte Fehltexte) | Build + Links ✅ |
| T-SHOTS Screenshots | `src/assets/{anwender,admin}/*` NUR aus Mock-Projekt `corporate` (nie `t1`!), Auftrag: `plans/t-shots-arbeitsauftrag.md` | general ses_ebac0c7feffed3DYtWznC2bqzJ | ✅ fertig — Stand 17.10.: 66 WebP (49 Anwender, 17 Admin), <200 KB; 2 nicht darstellbare Motive kommentiert | ✅ Text-Abweichungen eingearbeitet (Live-Schalter, OK-Button, Reiter, Corporate-Blöcke) | Build + Links ✅ |
| T-PROJ-D Vollständigkeit | pagebuilder-dev, mcp-nutzen (36 Tools), llm-nutzen | general ses_ebac0c804ffe9vElWvaKTju4H9 | ✅ fertig | ✅ SO eingearbeitet (REST-only: sieben statt fünf) | Build + Links ✅ |
| T-FINISH Finish | index-Karten, uebersicht/konzept-Stempel, Voll-Linkcheck, AGENTS-Spiegelung | Orga (direkt) | ✅ fertig (v1) | — (Linkcheck: alle ok, 0 Hüllen, ADR-0003 angelegt) | Build 71 Seiten ✅ (Stand 17.10.) |
| T-PB Pagebuilder komplett | pagebuilder-dev + seiten-bauen: Overlay-Editor, Modi, Viewport, Overview/inline, drillDown | general ses_eb9584bafffekRtyPPBn7ORTeA | ✅ fertig | ✅ SO eingearbeitet (OK/blur-Pfad, <768-px-Hinweis) | Build + Links ✅ |
| T-TON Ton-Rewrite | alle 10 anwender-Seiten: professionell-per-du, UI-Namen aus de.json | general ses_eb95443a5ffe8IrJVmt1DcAReX | ✅ fertig | ✅ SO eingearbeitet („Bild hochladen", Sitzungs-Hinweis, Live-Qualifier, KI-Beschreibung, Browser-Zurück) | Build + Links ✅ |
| T-SHOTS-2 Pagebuilder-Shots | Overlay + Viewport (corporate), Einbau in seiten-bauen | general ses_eb9503e20ffetq8gZU0Ff5U06T | ✅ fertig (3 webp, Icon-Tooltip korrigiert) | ✅ Abweichung eingearbeitet | Build ✅ |
| T-COV Coverage-Inventar | Skript + Map: Controller- und System-Routen, Kontexte, Tools, Schemas, Komponenten, Test-Pläne | general ses_eb9584ba6ffeUrQq7fowAHlPXO | ✅ 341/341 zugeordnet (Zuordnung ist kein Tiefennachweis) | ✅ Map v1; Tiefe siehe `plans/coverage-report.json` | `npm run coverage` grün |

Legende: ⏳ offen · 🔄 läuft (Session-ID) · 👀 Review/SO läuft · ✅ fertig.

Der T-REF-Eintrag hält den damaligen Second-Opinion-Stand fest (16 Schemas). Das nachträglich ergänzte `embedding.schema.json` ist inzwischen in der aktuellen Fähigkeitsmatrix enthalten; Gesamtbestand: 17 Schemas.

## Fähigkeitszuordnung: Was ist wo abgedeckt

Jede Fähigkeit von tibi-server / tibi-admin braucht genau eine Dokustelle. Die Zuordnung zeigt den passenden Ort, beweist aber nicht, dass jedes Verhalten in voller Tiefe beschrieben ist. Dafür sind Coverage-Tiefenstufen und fachliche Reviews getrennt zu betrachten.

### tibi-server (`internal/*`)

| Baustein | Dokustelle | Status |
|---|---|---|
| config (Server-Config, Env, Admin-Tokens) | server/konfiguration | ✅ |
| controller + dbapi + dbcrud + mongocrud (Routen, CRUD, Filter) | server/schnittstellen, projekt/abfragen-lesen | ✅ |
| hook (24 Kontexte) + Lifecycle-Stufen (get/post/put/delete/audit) | reference/hook-kontexte, projekt/hooks-schreiben | ✅ |
| realtime (Hub, SSE) | server/schnittstellen | ✅ |
| llm (chat, providers, Budgets) | projekt/llm-nutzen | ⏳ Hülle |
| mcp (36 Tools, Transport, Scopes) | projekt/mcp-nutzen (+ server/schnittstellen Überblick) | ⏳ Hülle |
| image (Filter) + upload | projekt/dateien-bilder | ✅ |
| ratelimit (Login-Backoff, 429) | server/sicherheit | ✅ |
| suexec + Pfad-Schalter | server/sicherheit | ✅ |
| audit (TTL, Lesen) | projekt/audit-backup | ✅ |
| jobs (Cron) + actions | projekt/jobs-actions | ✅ |
| snapshots + backup/restore | projekt/audit-backup | ✅ |
| search (Textindex, RRF-Hybrid, Regenerate) | projekt/suche (+ projekt/sammlungen-anlegen für Index-YAML) | ✅ |
| embedding + vectorindex (inkl. Failover-Gruppen, Startprüfung/Quarantäne/Rückkehr, `goldenPath`, Status-Endpunkte) | server/konfiguration (Gruppen im Detail), server/betrieb (Status/Störungen), projekt/suche (Kurzüberblick) | ✅ |
| rankfusion (RRF-Formel) | projekt/suche | ✅ |
| permissions (public/user/token, Orgs/Teams-Matrix) | projekt/rechte-tokens | ✅ |
| filecleanup (automatisch, keine Config-Fläche) | kein eigener Artikel — Einzeiler in server/betrieb prüfen (T-FINISH) | ⏳ |
| cache (Hook-lokal) | projekt/hooks-schreiben (Kontext-Tabelle) | ✅ |
| mock, models, testsuite, utils, version, mgocrud.old (intern, keine Projekt-Fläche) | keine Doku nötig | — |
| SSR-Hooks + ssr-Collection + clear_cache | projekt/ssr-website | ✅ |
| CORS-Kaskade | server/sicherheit | ✅ |
| OpenAPI-Generator | reference/openapi + server/schnittstellen | ✅ |
| Deploy/Compose-Profile | projekt/deploy + server/betrieb | ✅ |

### tibi-admin (`frontend/src/...`)

| Baustein | Dokustelle | Status |
|---|---|---|
| Ansichten (Tabelle/Karten/Medien/Navigation) + Suche/Sort/Filter/Blättern | admin/ansichten-listen + anwender/lesen-suchen-filtern | ✅ |
| Editor + 25 Widgets + Fremdschlüssel + i18n | admin/eintrags-editor + anwender/eintrag-bearbeiten | ✅ |
| Medien (Grid, Upload, Editor, Lightbox) | admin/medien + anwender/medien | ✅ |
| Exporte (Listen + Custom-Skripte) | admin/exporte + anwender/exportieren | ✅ |
| Actions (Ausführen, Fortschritt) | admin/aktionen | ✅ |
| Benutzer/Teams/Orgs/Rollen/Tokens/Impersonation | admin/benutzer-rechte + anwender/benutzer-teams | ✅ |
| KI (Chat, Zusammenfassen, STT/TTS, Budgets) | admin/ki-funktionen | ✅ |
| Pagebuilder (Widget, Registry, CSS-Transform, Vorschau, Screenshots) | projekt/pagebuilder-dev + admin/medien (Thumbnail?) + anwender/seiten-bauen | ⏳ Hülle (dev), Rest ✅ |
| Setup (Docker, Mock, URLs) + Customizing (Views, Meta, Skripte) | admin/setup, admin/customizing | ✅ |
| CommandPalette, Shortcuts, Breadcrumb, Audit/history-UI, Backup/Snapshot-UI | verstreut in admin/* — T-FINISH prüft Erwähnung je Seite | ⏳ |

### tibi-types + Starter

| Baustein | Dokustelle | Status |
|---|---|---|
| 17 Schemas (project, collection, field, hooks, permissions, job, action, snapshot, embedding, ...) | reference/schemas + je Projekt-Seite | ✅ |
| Starter-Skill (Platzhalter, Registrierung, Pfad A/B) | einstieg/schnellstart + einstieg/neues-projekt | ✅ |
| Mock-Projekte (corporate/shop/blog/intranet/events/t1) | plans/t-shots-arbeitsauftrag.md (corporate für Shots) | ✅ |

## Wellen

- Welle 1: T-REF, T-PROJ-A, T-SERVER (Fundament, unabhängig voneinander).
- Welle 2: T-PROJ-B, T-PROJ-C, T-ADMIN-A.
- Welle 3: T-ADMIN-B, T-ANW-A, T-ANW-B.
- Danach: T-SHOTS, dann T-FINISH.

## Methode Vollständigkeit (v2 — messbar statt Gefühl)

Stufe 1 — Inventare (Skript `scripts/coverage-inventory.mjs`, Befehl `npm run coverage`): Routen aus `setup.go`, Hook-Kontexte aus `context_*.go`, MCP-Tools aus `tools_*.go`, Schema-Top-Level aus `tibi-types`, Admin-Komponenten (`*.svelte`), Test-Pläne (Liste). Jedes Item → genau eine Doku-Seite (`plans/coverage-map.json`). Unzugeordnete Items = Arbeitsliste mit Zahl.

Stufe 2 — Lücken-Pakete wie bisher (Generalist + Second Opinion), aber mit Inventar-Beleg.
Stufe 3 — Ton-Rewrite nach Stil-Guide (AGENTS.md §1), UI-Namen wörtlich aus `de.json`.

## Ausbau Tiefe (v3 — Tiefe statt Erwähnung, mit Second Opinion abgestimmt)

Befund: Das Inventar zählt Pakete statt Funktionen — „282/282" misst Tiefe grundsätzlich nicht. Neue Körnung: **Funktion**, neue Messlatte pro Item: `Erwähnung < Signatur < Signatur+Beispiel < Signatur+Beispiel+Fehler` (Ziel: Stufe 4 überall). Quelle fertig: `// args:`-Kommentare über jedem `Func*` in `context_*.go`.

Tiefenstufen-DoD: Referenz = Name + Signatur + Codeblock mit Symbol + Fehlerfall (skriptgeprüft). Anleitung = jeder H2 Schritt mit wörtlichem UI-Namen + prüfbarem Ergebnis. Anwender = jeder Schritt nennt UI-String wörtlich. Übersicht = jede Fähigkeit genau ein Link.

| Paket | Inhalt | Agent | Status | Second Opinion | Abnahme |
|---|---|---|---|---|---|
| P-DEPTH Messlatte | Map v2 Funktionskörnung + Depth-Mode im Skript (Gate vor allem Schreiben!) | general ses_eb9485d3cffeqGunIdpSLocnBq | ✅ fertig (66 Symbole, 0 auf Stufe 3/4 → ehrliche Null) | ✅ Orga-Entscheide (JS-signature zählt, context-Alias) eingebaut | `npm run coverage` mit Tiefenstufen ✅ |
| P-HOOKS-1 Daten | db, cache, request, response, fs (+ Referenz-Muster für alle) | general ses_eb9442455ffelLESMgDZZ40T4G | ✅ fertig (27 Symbole Stufe 4) | ✅ SO eingearbeitet (Zitat-Zeilen, configDir-Marker, Scanner per-###) | Build ✅ |
| P-HOOKS-2 Netze | http, smtp, channel, ratelimit | general ses_eb93e70f1fferm8NNuFeh6Ktn5 | ✅ fertig | ✅ SO-Spotcheck (smtp-Alias = Namensrest) | Stufe 4 ✅ |
| P-HOOKS-3 Sicherheit | jwt, user, bcrypt, crypto, cookie, exec, config | general ses_eb93e70e7ffedQM6Xqv9hH20oj | ✅ fertig | ✅ SO-Spotcheck (bcrypt-s, jwt-valid:false) | Stufe 4 ✅ |
| P-HOOKS-4 Medien | tpl, image, pdf | general ses_eb93e70e6ffepuNEqdv3N3uabP | ✅ fertig | ✅ SO (int64-Hinweis ergänzt) | Stufe 4 ✅ |
| P-HOOKS-5 Meta | base64, json, xml, charset, debug | general ses_eb93e70e5ffeuZXn6frVY3h2Do | ✅ fertig | ✅ SO-Spotcheck (dump/Kein-Fehlerfall ok) | Stufe 4 ✅ |
| P-MCP-D Tools-Tiefe | 36 Tools je Signatur+Beispiel+Fehler | general ses_eb93b206effe1eyg3y08aNDl7c | ✅ fertig (36/36 Stufe 4) | ✅ SO (9 REST-only, action_*-Kanon in mcp-nutzen, msg-vs-message präzisiert) | Build ✅ |
| P-LLM-D KI-Tiefe | Chat/Provider/Budget + ki-funktionen vertiefen | general ses_eb93435b4ffe2RV01zcGmhDqIb | ✅ fertig | ✅ SO (502-Config-Relativierung, Vision-Overlay, 4 fehlende Tools) | Build ✅ |
| P-UI-D Oberfläche | Shortcuts/CommandPalette/Breadcrumb/Audit-UI-Referenz | general ses_eb93435b3ffe7PMqEKHwW6lIby | ✅ fertig | ✅ SO (Undo/Redo, Ctrl+Shift+F-Bedingung) | Build ✅ |
| T-PEPP-A Komponenten-Projekt | projekt/*: Asides, Steps, Tabs, Cards, FileTree, del/ins, Code-Titel | general ses_eb9201da2ffe9RwCS1tpEdQoIu | ✅ fertig (alle Dateien ≤+17) | — (nur Darstellung) | Build ✅ |
| T-PEPP-B Komponenten-Rest | admin+reference+server+einstieg+index: gleiche Kur | general ses_eb9201d99ffe98zEJW1GP81efn | ✅ fertig (Code-Titel überall, Cards, del/ins) | — (nur Darstellung) | Build ✅ |
| T-KIANW KI-Anwender-Guide | NEU anwender/ki-nutzen.md + Mock-SSE-Screenshots (corporate) | general ses_eb9201d98ffeg0qr36c5jKrRKD | ✅ fertig (3 Shots, Datenverbleib ergänzt) | ✅ SO (Banner-Fußnote, Sprachausgabe-Fix) | Build ✅ |
| P-BLIND Blind-Read | Mini-Hook nur aus Doku bauen | general ses_eb93b2073ffemiWkRrQhctSfXR | ✅ DURCHGEFALLEN = gearbeitet (7 FAILs → alle am Code verifiziert + in hooks-schreiben/fehlercodes behoben) | — (Test-Ergebnis selbst) | 0 offene FAILs |

Kontrollen: Depth-Gate im Skript (gemapptes Item < Stufe Signatur = Fail), Blind-Read-Test pro Los (Generalist baut Mini-Hook nur aus der Seite), SO-Spotcheck 3 Zufalls-Funktionen gegen Code.

## Orga-Checkliste (Runde 3)

- [x] Plan-Datei angelegt (`plans/doku-ausbau.md`)
- [x] Welle 1 gestartet (T-REF, T-PROJ-A, T-SERVER) — 3 Agenten laufen im Hintergrund
- [x] Welle 1 Ergebnisse eingetroffen (je Paket: Dateien geschrieben?)
- [x] Welle 1 Build + Links geprüft
- [x] Second Opinion T-REF, T-PROJ-A, T-SERVER eingeholt und eingearbeitet
- [x] Welle 2 Ergebnisse + Build + Second Opinions (alle drei Pakete fertig)
- [x] Welle 3 Ergebnisse + Build + Second Opinions (alle drei Pakete fertig)
- [x] T-SHOTS: Screenshots erstellt und eingebunden (24 webp aus corporate, Text-Abweichungen korrigiert)
- [x] T-FINISH: Index, Stempel, Linkcheck, AGENTS-Spiegelung (55 Seiten, 0 Hüllen, ADR-0003)
- [x] Abschlussmeldung an User
- [x] Stil-Guide professionell-per-du in AGENTS.md (§1)
- [x] T-PB Ergebnis + Build + Second Opinion
- [x] T-COV Inventar + Map v1 erstellt; UI-Einträge waren zunächst Topic-Level, Tiefenstufen wurden danach ergänzt
- [x] T-TON gestartet (alle 10 Anwender-Seiten)
- [x] T-TON Ergebnis + Build + Second Opinion
- [x] T-SHOTS-2 gestartet (Overlay + Viewport, corporate)
- [x] T-SHOTS-2 Ergebnis eingebaut
- [x] Abschlussmeldung Runde 2 an User

## Orga-Checkliste Runde 3 (Tiefenausbau)

- [x] P-DEPTH gestartet (Messlatte, Gate)
- [x] P-DEPTH Ergebnis: Funktionskörnung + Depth-Mode, verifiziert (66 Symbole, ehrliche Null auf 3/4)
- [x] P-HOOKS-1 gestartet (Muster-Los Daten)
- [x] P-HOOKS-1 Ergebnis + Blind-Read + SO (27 Symbole Stufe 4, Scanner per-###, Zitat-Regel)
- [x] P-HOOKS-2 bis 5 parallel gestartet (nur Kapitel-Dateien, Shared-Edits beim Orga)
- [x] Lose 2-5 eingetroffen: Sidebar + Index-Links + Map-Umtrag (Orga), Build, SO-Spotcheck
- [x] Blind-Read-Test über alle 5 Kapitel (Mini-Hook nur aus Doku)
- [x] P-MCP-D + P-LLM-D + P-UI-D starten
- [x] Abschlussmeldung Runde 3 an User
- [x] Issue zu `reponse.header` im Server-Code angelegt: tibi-server #44
- [x] Issue zum `toggleUsers`-Kürzel angelegt: tibi-admin-nova #5

## Runde 4 — Audit und Umsetzung (2026-10-17)

Vollständige Prüfung von Code und Doku, dann Abarbeitung in Wellen. Übersicht, Befunde und Belege:
**`plans/doku-audit.md`** (mit Ausführungsprotokoll), Detailreports unter `plans/audit/`.

| Welle | Inhalt | Status |
|---|---|---|
| A | P1 Faktenfehler (8) + P2 Markdown/Hygiene | ✅ |
| B | P3 Server-Lücken (`feld-rechte.md`, `rest-system.md` neu, 8 Seiten vertieft) + P4 Admin-Interfaces | ✅ |
| C | P5 `reference/schema-properties.md` (generiert) + Starter-Kapitel + 5 neue Anwender-Seiten | ✅ |
| D | P7 Stil, Starlight, Struktur, UI-Text-Treue, Kontrast | ✅ |
| E | P6b Screenshots: 9 Admin- + 10 Anwender-Bilder aus `corporate` | ✅ |
| G | Screenshot-Nachtrag: restliche UI-Bereiche (8 Anwender + 9 Admin + Befehlspalette) | ✅ (66 Bilder gesamt) |
| F | P8 Meta (AGENTS.md, Werkzeuge, Issues) | ✅ |
| — | P9 Repo-Hygiene: 5 Alt-Kopien gelöscht (~6,1 GB), 6 mit unpushed Commits behalten | ✅ |
| H | Ton: Fehlerabschnitte auf Handbuch-Sprache (Regel in AGENTS.md §1, 12 Anwender-Seiten + 5 Stellen) | ✅ |
| I | Darstellung: Inline-Code-Chips für Dark Mode, 58 Seiten auf `.mdx` (Komponenten rendern jetzt), Render-Prüfung im Audit-Skript | ✅ |
| — | Issues in den Nachbar-Repos (13) | ✅ tibi-server #42–#48, tibi-admin-nova #2–#5, tibi-types #3/#4 |

**Neue Werkzeuge:** `scripts/audit-docs.mjs` (Struktur-/Link-/Bildprüfung, `plans/audit-report.json`),
`scripts/gen-schema-matrix.mjs` (`npm run gen:schemas` → `reference/schema-properties.md`).
**Neue Seiten:** `projekt/feld-rechte`, `reference/rest-system`, `reference/schema-properties`,
`projekt/tests`, `anwender/{verlauf-wiederherstellen,massenbearbeitung,aktionen,backup-einspielen,tastenkombinationen}`.
**Stand:** 70 Inhaltsseiten, 66 Screenshots (49 Anwender, 17 Admin), Build grün, Audit: 0 tote Links, 0 kaputte Tabellen.
**Offen:** Issues für die Nachbar-Repos (`plans/offene-issues.md`), Löschkandidaten `tibi-docs-legacy`,
`tibi-docs-kaputt`, `tibi-admin.bak*`, `tibi-server.bak` (Freigabe), Coverage v2 (Funktionskörnung).