Guide

Willkommen bei der Capability Engine — einer Plattform für LLM-gepflegte Wissens-Wikis. Dieser Guide erklärt, wie das System funktioniert und wie du im Web-UI damit arbeitest.

Dieser Guide lebt als Markdown-Datei im Repository (apps/web/content/guide.md) und wird direkt aus dieser Datei gerendert. Änderungen an der Datei erscheinen automatisch auf dieser Seite. Wie das gepflegt wird, steht unter Diesen Guide aktuell halten.

Was ist ein Wiki hier?

Ein Wiki ist eine isolierte Wissensdatenbank. Du bringst Quellen hinein (Notizen und Dokumente); ein LLM analysiert sie und baut sie ins Wiki ein — es schreibt Zusammenfassungs-Seiten, pflegt Entitäten und Konzepte, hält Querverweise aktuell und markiert Widersprüche. Das Ergebnis ist browsebar, versioniert und verdichtet sich über die Zeit zu einem gepflegten Artefakt statt eines Chat-Verlaufs.

Zwei Prinzipien prägen die Bedienung:

LLM-kuratiert: Seiten werden vom LLM geschrieben, nicht direkt von Hand. Du lenkst über Quellen und Anweisungen und prüfst Vorschläge.
Review vor Commit: Jede vorgeschlagene Änderung landet als Changeset in der Inbox. Erst nach deiner Freigabe wird sie als neue Revision übernommen.

Wikis sind strikt voneinander getrennt — es gibt bewusst keine Links zwischen verschiedenen Wikis.

Navigation

Innerhalb eines Wikis führt die Tab-Leiste zu den Kernbereichen:

Tab	Zweck
Browse	Seiten der Wissensbasis durchblättern und lesen
Suche	Hybride Suche (Volltext + semantisch) innerhalb dieses Wikis
Quellen	Notiz / Dokument hinzufügen, Ingest anstoßen, Quell-Status sehen
Inbox	Offene Changesets prüfen, Diffs ansehen, freigeben oder ablehnen
Aktivität	Chronologischer Stream aller Ereignisse (Ingest, Approve, …)
Konfiguration	Ontologie, Konventionen und Validierungsregeln des Wikis

Über die globale Kopfzeile erreichst du außerdem Wikis (Übersicht), diesen Guide, die Konfiguration (System-Status) und das Changelog.

Der typische Ablauf

Quelle hinzufügen  →  Ingest (LLM)  →  Changeset in der Inbox  →  Review  →  Freigabe  →  Seite(n) im Wiki

Wiki wählen oder anlegen — auf der Übersicht (Wikis) siehst du je Wiki die Anzahl Seiten und offener Changesets. „Neues Wiki" legt eines an.
Quelle einbringen — im Tab Quellen eine Notiz eintippen oder ein Dokument hochladen. Danach Ingestieren auslösen.
Warten auf den Vorschlag — der Ingest läuft asynchron. Das LLM liest die Quelle, gleicht sie gegen bestehende Seiten ab und erzeugt ein Changeset.
Review in der Inbox — Vorschlag öffnen, Diff pro Seite prüfen, Widersprüche beachten, dann Freigeben oder Ablehnen.
Browsen — freigegebene Änderungen erscheinen als neue Seiten/Revisionen unter Browse.

Quellen hinzufügen

Im Tab Quellen gibt es drei Wege, Wissen einzubringen:

Notiz — Freitext, wird as-is übernommen. Ideal für kurze Fakten, Beobachtungen oder Zwischenstände.
Dokument-Upload — PDF, DOCX, PPTX oder XLSX. Die Datei wird via markitdown nach Markdown konvertiert (inkl. Tabellen). Uploads bis 25 MB.
Direkt-Import (Bündel) — ein Paket aus fertigen Markdown-Seiten (Markdown + Frontmatter) direkt importieren, ohne LLM-Ingest. Nützlich für Migrationen. Der Import-Report zeigt an, was angelegt/aktualisiert wurde.

Jede Quelle hat einen Status (z. B. extracted, ingested). Über den Button in der Quell-Zeile stößt du den Ingest an.

Ingest & Changesets

Beim Ingest bekommt das LLM den Quelltext plus die Konfiguration/Ontologie des Wikis und den bestehenden Index. Es entscheidet, welche Seiten es anlegt (create), ergänzt/ändert (update / amend) oder archiviert (archive) — und bündelt diese Operationen als Changeset. Es committet nichts direkt.

Ein Changeset besteht aus mehreren Items. Jedes Item trägt:

eine Begründung (warum diese Änderung),
optional ein Widerspruchs-Flag mit Schweregrad,
den vorgeschlagenen Seiteninhalt (als Diff sichtbar).

Damit die Wissensbasis nicht zerfasert, ordnet sich der Ingest der festen Ontologie des Wikis unter (siehe Seitentypen) und erfindet keine eigenen Typen.

Review-Inbox

Die Inbox listet alle offenen (proposed) Changesets. Öffne eines, um:

den Diff pro Seite zu sehen (alt → neu),
Widersprüche hervorgehoben zu bekommen,
das Changeset freizugeben (Approve) oder abzulehnen (Reject).

Beim Freigeben wird pro Item eine neue Revision erzeugt, die Seite aktualisiert, Links werden neu aufgelöst und die geänderten Seiten neu eingebettet (für die semantische Suche).

Validierung: Vor der Übernahme laufen die Validierungsregeln des Wikis (siehe Konfiguration). Schlägt eine Regel an, wird das im Review sichtbar. Für begründete Ausnahmen gibt es eine Force-Approve-Option.

Widerspruchs-Schweregrade

Schweregrad	Bedeutung
`soft`	leichter Konflikt / Nuance — meist unkritisch
`scope-mismatch`	Aussage passt thematisch nicht recht zur Seite
`hard`	echter Widerspruch zu bestehendem Wissen — bewusst entscheiden

Browse & Seiten lesen

Unter Browse liest du die Seiten. Eine Seitenansicht zeigt:

Seitentyp und Status als Badge,
den gerenderten Markdown-Inhalt,
Ausgehende Links und Backlinks in der Seitenleiste,
einen Link zu den Revisionen.

Wikilinks: Im Text verweist [[Zielseite]] auf eine andere Seite desselben Wikis. Aufgelöste Links speisen automatisch Backlinks und den Wissensgraphen.

Seitentypen

Jedes Wiki nutzt ein festes Set an Seitentypen. Üblich sind:

Typ	Inhalt
`summary`	Zusammenfassungs-/Themenseite
`entity`	konkrete Entität (Person, Organisation, Ding …)
`concept`	abstraktes Konzept / Begriff
`index`	Katalog-/Übersichtsseite

Welche Typen und Konventionen gelten, legt die Konfiguration des Wikis fest.

Revisionen, Diff & Rollback

Jede Änderung erzeugt eine immutable Revision — die Historie ist lückenlos. Über Revisionen (in der Seitenansicht) siehst du die Zeitleiste, kannst zwei Revisionen vergleichen (Diff) und bei Bedarf auf einen früheren Stand zurückrollen. Ein Rollback legt dabei eine neue Revision an — es löscht keine Historie.

Suche

Die Suche arbeitet hybrid: Postgres-Volltextsuche kombiniert mit semantischer Vektorsuche (pgvector). Treffer zeigen Seitentyp, einen Snippet und woher der Treffer kommt (matched_via). Die Suche ist immer auf ein Wiki begrenzt.

Aktivität

Der Aktivitäts-Tab ist eine append-only Chronik: Ingest, Approve, Reject, Rollback usw. — mit Akteur und Zeitstempel. Gut, um nachzuvollziehen, wie sich ein Wiki entwickelt hat.

Konfiguration

Pro Wiki konfigurierst du:

Ontologie · Seitentypen — welche Typen erlaubt sind.
Konventionen — Stil-/Struktur-Regeln, an die sich der Ingest hält.
Validierungsregeln — Checks, die beim Freigeben erzwungen werden (CRUD in der UI). Sie sichern Qualität, bevor eine Änderung ins Wiki geht.
Beschreibung & Roh-Config (JSON) — für Feinjustierung.

System-Konfiguration

Über die Kopfzeile führt Konfiguration zu einer rein lesenden Übersicht der laufenden System-Einstellungen (nicht pro Wiki, sondern für den ganzen Dienst). Sie zeigt gruppiert, was ein- oder ausgeschaltet ist — etwa die Ingest-Flags, ob Authentifizierung aktiv ist oder welches LLM-Standardmodell läuft.

Nicht editierbar — Werte werden ausschließlich über Umgebungsvariablen beim Deployment gesetzt.
Secrets sind maskiert — Passwörter/Schlüssel erscheinen nur als Fingerprint (z. B. 13*****bc), Verbindungs-URLs ohne Passwort.

Rollen & Zugriff

Der Zugriff wird pro Wiki über Keycloak geregelt:

Rolle	Darf
`Owner`	alles inkl. Konfiguration & Zugriffsverwaltung
`Editor`	Quellen einbringen und Changesets freigeben
`Viewer`	lesen und suchen

Noch nicht enthalten

Bewusst (noch) nicht im Funktionsumfang — auf der Roadmap für spätere Phasen:

geplante Lint-Jobs (automatische Gesundheitsprüfung ganzer Wikis),
Web-URL- / Feed- / Medien-Ingest,
Graph-Visualisierung der Verlinkung,
direkte manuelle Seitenbearbeitung und Kommentare.

Was pro Release dazukommt, steht im Changelog.

Diesen Guide aktuell halten

Dieser Guide ist eine einzige Markdown-Datei — eine Quelle der Wahrheit:

apps/web/content/guide.md   →  wird live unter /guide gerendert

Wer ein Feature ändert oder hinzufügt, aktualisiert im selben Merge-Request diese Datei. Kein separater Redaktions-Schritt, keine Doppelpflege. Neue Absätze oder Tabellen erscheinen nach dem Deploy automatisch hier.