tibi-docs/plans/audit/05-review-einstieg-server.md

Review: Einstieg + Server

• Umfang: src/content/docs/einstieg/*.md (4 Dateien), src/content/docs/server/*.md (5 Dateien). Alle vollständig gelesen.
• Datum: 2026-10-16.
• Geprüft gegen: AGENTS.md §1, tibi-server/internal/** (Code), tibi-svelte-starter (Compose, Makefile, api/, scripts/, .env), tibi-admin-nova/.../de.json (nur Stichworte), Server-HEAD 68b42785, Starter-HEAD e3f92ebf.
• Regel: Nur belegte Fehler stehen als FEHLER-INHALT; alles andere als PRUEFEN am Ende.

Befundtabelle

#	Datei:Zeile	Kategorie	Befund (kurz)	Vorschlag
1	konfiguration.md:21	FEHLER-INHALT	„bge-m3 → EMBEDDING_BGE-M3_*" ist falsch. normalizeEnvKeyName ersetzt - durch _ und uppercaset, Beleg tibi-server/internal/config/server.go:245-251,437-439. Korrekt wäre EMBEDDING_BGE_M3_*.	Beispiel korrigieren zu EMBEDDING_BGE_M3_*; Regel umformulieren („Bindestrich wird zu Unterstrich“).
2	konfiguration.md:99-105	FEHLER-INHALT	Gleicher Fehler im Beispielblock: 7× EMBEDDING_BGE-M3_* (TYPE, MODELPATH, DIMENSIONS, DOCUMENTPREFIX, QUERYPREFIX). Keine dieser Variablen greift. Beleg wie #1.	Alle Prefixe zu EMBEDDING_BGE_M3_* ändern.
3	betrieb.md:21	FEHLER-INHALT	„mongo (MongoDB 7)“ — der Starter pinnt image: gitbase.de/server/mongo:8 (docker-compose-local.yml, Service mongo).	Auf „MongoDB 8“ ändern.
4	schnittstellen.md:62	FEHLER-INHALT	„Alle Antworten sind gzip-komprimiert“ — falsch absolut. Ausgenommen sind .pdf/.mp4/.jpg/.jpeg/.png und /metrics. Beleg internal/controller/setup.go:151-154.	„Alle JSON-Antworten … (ausgenommen Mediendateien und /metrics)“.
5	neues-projekt.md:68,77	MD-FEHLER	$CODING_TIBISERVER_URL ist nirgends definiert: nicht in Starter-.env, nicht in der URL-Liste in schnellstart.md:51, in keinem Script. Nur -tibiserver-Host, inline gebaut in scripts/reload-local-tibi.sh:10. Befehle so nicht kopierbar.	Variable definieren (.env + schnellstart.md:51) oder Befehle auf dokumentierten Host umschreiben.
6	uebersicht.md:36	MD-FEHLER	„Verifiziert am 68b42785“ ohne Backticks; alle 4 anderen Server-Seiten nutzen `68b42785`.	Backticks ergänzen.
7	server/betrieb.md:6, konfiguration.md:6, schnittstellen.md:6, sicherheit.md:6	MD-FEHLER	Identische 8er-Importzeile (Aside, Tabs, TabItem, Steps, Card, CardGrid, Badge, FileTree), davon pro Seite 3–6 ungenutzt (z. B. betrieb: Tabs/TabItem/Card/CardGrid/FileTree ohne Verwendung; schnittstellen: Aside/Steps/Card/CardGrid/Badge/FileTree ohne Verwendung). Copy-Paste-Rest.	Je Seite nur importieren, was verwendet wird.
8	server/.md:1-4 vs einstieg/.md:1-4	MD-FEHLER	Frontmatter inkonsistent: Server-Seiten mit einfachen Quotes (title: '...'), Einstieg ohne.	Eine Form wählen (ohne Quotes, wie einstieg).
9	uebersicht.md:8-14	MD-FEHLER	Zwei Hinweis-Stile auf einer Seite: Blockquote (> **Handseite.** …) plus :::note.	Einen Stil wählen (Repo-Konvention: <Aside>).
10	konfiguration.md:41-43	STIL	„Das README-Beispiel ist unvollständig und nennt …“ + „README lügt an zwei Stellen“ + rohes <del>/<ins>-HTML. „Lügt“ ist unsachlich, HTML-Tags sind kein Doku-Stilmittel.	Sachlich: „Das README-Beispiel ist veraltet (noch Go 1.23 statt go 1.25.0/go1.25.7 laut go.mod).“ Version als Badge oder Code, kein <del>/<ins>.
11	neues-projekt.md:10	STIL	Agenten-Meta im Nutzertext: „Stand: am Code geprüft, nicht aus Alt-Doku.“ Für Leser wertlos.	Streichen; Prüfnachweis gehört in Commit/Plan, nicht auf die Seite.
12	neues-projekt.md:53	STIL	Belehrung an den Leser: „Keine Pfad-B-Schritte im lokalen Starter-Stack erfinden.“	Streichen oder in Ergebnis-Satz umwandeln („Im lokalen Stack entfällt Pfad B.“).
13	uebersicht.md:8	STIL	Maintainer-Meta („Wird vom Sync nie überschrieben (keep) …“) steht als erster Satz im Nutzertext.	In HTML-Kommentar oder ans Seitenende verschieben.
14	uebersicht.md:10, begriffe.md:8-18	STIL	Benennung uneinheitlich: „Tibi-server“, „Tibi-Server“, „Tibi-Admin“, „Tibi-Projekt“ — AGENTS.md §0 verlangt tibi-server / tibi-admin (klein).	Durchgehend Kleinschreibung wie in was-ist-tibi.md:10-11.
15	einstieg/.md vs server/.md	STIL	Codezaun-Sprache uneinheitlich: Einstieg sh, Server bash (bei identischem Inhalt Shell).	Einheitlich bash (oder sh) wählen.
16	schnittstellen.md:53-57	STIL	Recht-Spalte uneinheitlich: project.reload, project.regenerate-search, dann bloß „Projekt-Admin“ (Embedding-Status), dann project.backup / project.snapshot.	Überall Scope schreiben (Embedding-Status: welches Recht genau, Beleg setup.go:390 prüfen).
17	schnellstart.md:91	STIL	„nur wenn Server-Token vorhanden“ — vage Bedingung ohne Handlung.	Konkret: „… oder X-Admin-Token mit Scope project.create“ (falls belegbar, sonst streichen).
18	konfiguration.md:123	STIL	Tippfehler „namespace….)“ (vier Punkte + Klammer).	„namespace.…“ bzw. Beispiel wie sicherheit.md:21.
19	uebersicht.md:20	STIL	Card verspricht „inkl. Go-Version und Legacy-Default“ — Legacy-Default kommt in konfiguration.md nirgends vor (gemeint sind wohl die 201/204-Legacy-Codes aus schnittstellen.md:62).	Begriff klären oder streichen.
20	was-ist-tibi.md:30-35	STARLIGHT	Card mit Markdown-Link im Body („Loslegen“) ist kein klickbares Karten-Link.	LinkCard mit href nutzen, Text ohne Markdown-Link.
21	uebersicht.md:19-33	STARLIGHT	5× Card + [Lesen](…)-Link statt Karten-Link; doppelte Information (Titel + Link-Text identisch).	Auf LinkCard (link.href, link.description) umstellen.
22	neues-projekt.md:12-23	STARLIGHT	Setup-Checkliste als statischer text-Codeblock mit [ ] — nicht abhakbar, kein Fortschritt.	Steps + echte Task-List (- [ ] im Fließtext) oder Steps-Komponente pro Meilenstein.
23	neues-projekt.md:81-83	STARLIGHT	Wichtiger Token-Hinweis als :::caution (Syntax im Repo sonst nirgends, siehe PRUEFEN P1).	<Aside type="caution" title="…"> wie sicherheit.md:30.
24	schnellstart.md:8-10	STARLIGHT	:::danger für die Kern-Regel (Repo-Einzelfall).	<Aside type="danger" title="Kern-Regel aus dem Starter">.
25	konfiguration.md:46-77, schnittstellen.md:21-60	STARLIGHT	Tabs ohne syncKey — gewählte Tabs (z. B. „Minimal-Beispiel“/„Lokaler Dial“) gehen beim Seitenwechsel verloren.	syncKey ergänzen (z. B. syncKey="serverblick").
26	begriffe.md:6-19	STARLIGHT	Reine Tabelle ohne einzige Heading: kein tableOfContents, keine Sprungmarken, kein Aside, keine Weiterführung.	Je Oberbegriff (Namespace, Collection, …) als ##-Abschnitt oder Glossar-CardGrid; Tabelle als Kurzindex oben behalten.
27	schnittstellen.md:101	STRUKTUR	„Wie frage ich Daten ab?“ verlinkt auf /einstieg/begriffe/ statt auf die Abfrage-Seite.	Auf /projekt/abfragen-lesen/ zeigen; begriffe-Zeile streichen oder umbenennen.
28	was-ist-tibi.md:27-36	STRUKTUR	„Wo geht es weiter?“ nennt nur Schnellstart + Begriffe; „Neues Projekt“ (4. Sidebar-Eintrag) fehlt, obwohl schnellstart.md:94 darauf verweist.	Dritte Karte „Neues Projekt“ ergänzen.
29	schnellstart.md:85-92, neues-projekt.md:81-83	STRUKTUR	Token-Kopf-Wissen steht doppelt (Tabelle vs. Caution) plus drittes Mal in reference/token-koepfe.md. Drei Wahrheiten zu einer Tatsache.	Kurzfassung + ein Verweis auf reference/token-koepfe.md als Single Source.
30	schnellstart.md:73, neues-projekt.md:105-115	STRUKTUR	Nach „Abnahme“ endet der Pfad im Leeren: kein Verweis in Admin-/Anwender-Doku (erste Anmeldung, erste Inhalte).	„Nächster Schritt“-Box mit Links auf admin/- und anwender/-Seiten.
31	betrieb.md:62-70	LUECKE	Backup/Snapshot nur als „Fortschritts-Stream“ erwähnt; kein Wort zu Wiederherstellung, Retention, prune, obwohl Endpunkte existieren (setup.go:416-491).	Abschnitt „Sichern und Wiederherstellen“ mit backup-, snapshots- und prune-Befehlen.
32	betrieb.md	LUECKE	/api/v1/admin/shutdown (server.shutdown) kommt nur als Tabellenzelle in schnittstellen.md:32 vor; Betreiber-Seite ohne Stop-/Neustart-Prozedur.	Störungs-/Wartungsabschnitt um Shutdown + Audit-Spur (setup.go:772-798) ergänzen.
33	konfiguration.md:24-43	LUECKE	Beispielblöcke nur für DB/API/Mail + LLM/Embedding; audit, ratelimit, hook, mcp nur als Tabellenzeilen ohne YAML-Form.	Je ein Minimal-YAML pro Bereich (Defaults aus server.go sind belegt).
34	begriffe.md	LUECKE	Kein Eintrag zu Token-Arten (PAT/JWT/Admin-Token) und Scope-Syntax, obwohl Einstieg + Server ständig darauf verweisen.	2 Zeilen + Verweis auf reference/token-koepfe.md und server/sicherheit/.
35	einstieg/*.md	LUECKE	Mock-Modus wird nur in begriffe.md:19 definiert; schnellstart.md erwähnt MOCK nirgends, obwohl Starter start:mock (MOCK=1) kennt.	Schnellstart-Schritt „Starten“ um Mock-Hinweis ergänzen oder bewusst ausklammern.

Starlight-Potenzial (pro Seite)

• was-ist-tibi.md: Card → LinkCard (#20); ASCII-Diagramm (Z. 15-23) als Steps- oder nummerierte Liste mit je einem Satz Wirkung pro Pfeil.
• schnellstart.md: :::danger → <Aside type="danger"> (#24); Schritt 1-6 in <Steps> statt nummerierter Headings (konsistent zu betrieb.md:38).
• neues-projekt.md: Checkliste → Steps/Task-List (#22); :::caution → <Aside> (#23); FileTree um Stamm (./, docker-compose-local.yml, .env) erweitern.
• begriffe.md: Glossar-Struktur mit Headings + CardGrid-Kurzindex (#26); tableOfContents greift dann automatisch.
• uebersicht.md: Card → LinkCard (#21); Blockquote + :::note → ein <Aside type="note"> (#9).
• konfiguration.md: Tabs mit syncKey (#25); <del>/<ins> → Badge für go 1.25.0 (#10); Beispielblöcke (#33).
• betrieb.md: ungenutzte Imports entfernen (#7); Störungstabelle um Shutdown-Zeile erweitern (#32); Badge-Profilzeile (Z. 14) ans Seitenende in „Voraussetzungen“ wiederholen ist unnötig — streichen.
• sicherheit.md: ungenutzte Imports entfernen (#7); Token-Tabelle um PAT-Beispiel (tibi_pat_…) als bash-Block ergänzen; Checkliste (Steps) ist bereits Musterbeispiel — behalten.
• schnittstellen.md: Tabs mit syncKey (#25); API-Baum (Z. 10-17) als FileTree statt text-Block prüfen; Linkfix #27.

Unsichere Punkte

• P1. :::caution title="…", :::danger title="…", :::note title="…" (neues-projekt.md:81, schnellstart.md:8, uebersicht.md:12): Titel-Attribut ohne Klammern ist keine Standard-Starlight-Syntax ([Titel] wäre sie); Repo-Konvention ist <Aside>. Build-Rendering nicht geprüft — bitte Rendern verifizieren oder auf <Aside> umstellen.
• P2. schnellstart.md:73 („Anmeldung im Admin lokal: admin / admin“): im geprüften Server-Code keine Seed-Stelle gefunden (nur massenhaft GetLoginToken("admin","admin") in Tests). Vermutlich Starter-/Admin-Seed — bitte belegen oder als Starter-Fakt kennzeichnen.
• P3. Doku-Domäne *.code.testversion.online vs. Compose-Label online.testversion.code.subdomain=…: Abbildungsregel steht nicht im geprüften Repo-Ausschnitt (nur ein auskommentierter Host(...code.testversion.online) in docker-compose-local.yml). Bitte Traefik-Regel belegen.
• P4. betrieb.md:72-74 („Jobs laufen unter der Projekt-UID“, „Quotas und Nutzung landen in der LLM-Nutzungsablage“): Cron-Registrierung belegt (models/api.go:268, models/job.go:4, JOB_CONTEXT in models/function.go:276), suexec-Pfad für Jobs und „Nutzungsablage“ nicht explizit nachgewiesen.
• P5. sicherheit.md:42 („Globales CORS ist auskommentiert“): keine Default-config.yml im geprüften Stand gefunden; unbelegt, ob das für alle Deployments gilt.
• P6. neues-projekt.md:57/71 (project not found, GET /api/v1/project): String existiert in internal/filecleanup/cleanup.go:70, System-Projekt-CRUD via Project.Middleware (models/project.go:206) ist belegt; ob genau dieser String bei fehlender Registrierung erscheint, nicht end-to-end nachgewiesen.
• P7. neues-projekt.md:61-64 (Login via $CODING_TIBIADMIN_URL/api/login): Admin-Frontend-Proxy-Pfad, nicht gegen tibi-admin-nova-Code geprüft (Server-Route ist POST /api/v1/login, setup.go:728).