munin/internal/hilfe/seiten/begriffe.md

Wie alles zusammenhängt

Workspace (z. B. eine Abteilung)
 └── Projekt (z. B. ein Team oder ein Vorhaben)
      ├── Einträge   ← das eigentliche Wissen
      └── Zugänge    ← API-Keys mit Rolle

Die Begriffe

Workspace Ein Bereich für eine Abteilung oder eine größere Gruppe von Teams. Jeder Workspace liegt in einer eigenen Datenbankdatei. Workspaces sehen sich gegenseitig nie: Die Trennung ist technisch erzwungen, nicht nur eine Filtereinstellung. Mit einem Projekt-Key bist du immer in genau einem Workspace. Du musst ihn nicht auswählen.

Projekt Die Einheit, in der Wissen geteilt wird, meist ein Team oder ein Vorhaben. Jedes Projekt hat eigene Einträge, eigene Zugänge und eine eigene Suche. Projekte sehen sich gegenseitig nicht, auch nicht innerhalb desselben Workspace.

Eintrag Ein Stück Wissen: Titel, Inhalt in Markdown, Schlagworte. Ein guter Eintrag beantwortet genau eine Frage, etwa „Wie läuft das Deployment?“ oder „Warum nutzen wir SQLite?“.

Bezeichner (slug) Der kurze, dauerhafte Name eines Eintrags, zum Beispiel deployment-prozess. Er steht in der Adresse und dient als Schlüssel gegen Dubletten: Wer zweimal mit demselben Bezeichner schreibt, aktualisiert den Eintrag, statt einen zweiten anzulegen. Erlaubt sind a-z, 0-9, - und _.

Schlagworte (tags) Ordnen Einträge thematisch ein, zum Beispiel ops oder sicherheit. Es gibt keine Ordner. Wo etwas „hingehört“, ist selten eindeutig, deshalb kann ein Eintrag mehrere Schlagworte tragen. Besser wenige, einheitliche Schlagworte als viele leicht verschiedene.

Verweis [[bezeichner]] im Inhalt verlinkt auf einen anderen Eintrag. Die Gegenrichtung entsteht automatisch: Jeder Eintrag zeigt, welche anderen auf ihn verweisen. Ein Verweis darf auch auf einen Eintrag zeigen, den es noch nicht gibt. Das markiert eine Lücke, die jemand füllen sollte. Steht die Schreibweise in Code (zwischen Backticks oder in einem Codeblock), ist sie kein Verweis, sondern ein Beispiel, und bleibt so stehen.

Fassung (version) Zählt bei jeder Änderung eines Eintrags hoch. Die vorherigen Fassungen bleiben erhalten und lassen sich über Verlauf ansehen vergleichen. Ein gelöschter Eintrag behält seinen Verlauf, solange er im Papierkorb liegt.

Papierkorb Gelöschte Einträge liegen dort 30 Tage, bevor sie endgültig verschwinden. Für Agenten und die Suche sind sie sofort unsichtbar; Menschen mit Schreibrecht können sie zurückholen.

Herkunft Jeder Eintrag vermerkt, ob zuletzt ein Mensch (über die Weboberfläche) oder ein Agent (über MCP) geschrieben hat, und unter welchem Zugangsnamen.

Kuratiert Ein Haken, den ein Mensch setzt, wenn er einen Eintrag geprüft hat. Einträge ohne diesen Haken sind Beobachtungen, keine bestätigten Fakten. Agenten sehen den Haken und können danach filtern; in der Suche stehen kuratierte Einträge bei sonst gleicher Relevanz weiter vorn. Ein Agent ändert einen kuratierten Eintrag nur mit Begründung. Dabei fällt der Haken weg, und der Eintrag steht auf der Nutzungsseite zur Prüfung, bis ein Mensch ihn wieder setzt.

API-Key (Zugang) Ein Schlüssel, der mit wk_ beginnt und genau zu einem Projekt gehört. Er dient zur Anmeldung im Browser und im KI-Werkzeug. Munin speichert nur eine Prüfsumme, daher wird der Key beim Anlegen ein einziges Mal angezeigt.

Protokoll Hält fest, wer wann etwas geschrieben oder gelöscht hat, wer sich angemeldet hat (auch Fehlversuche) und wann Zugänge angelegt oder zurückgezogen wurden. Lesen und Suchen stehen nicht darin. Protokolleinträge werden nach 90 Tagen automatisch gelöscht.

Suchprotokoll Hält getrennt davon fest, was Agenten mit recall gesucht haben und ob sie etwas gefunden haben, ohne Adresse. Die Nutzungsseite wertet es aus. Weil Anfragen Inhalt sind, wird es nach 30 Tagen gelöscht und verschwindet mit dem Projekt.

Rollen

Jeder Key hat genau eine Rolle.

Rolle	Darf	Gedacht für
read	lesen und suchen	Agenten, die nur Auskunft geben sollen
write	zusätzlich schreiben und löschen	der Normalfall für Menschen und beaufsichtigte Agenten
admin	zusätzlich die Zugänge des Projekts verwalten	Menschen, die für das Projekt verantwortlich sind

Darüber stehen zwei Verwaltungszugänge, die nicht an ein Projekt gebunden sind und nur für die Weboberfläche gelten:

• Der Workspace-Admin verwaltet in genau einem Workspace die Projekte und ihre Zugänge und kann alle Projekte dort lesen (siehe Zugänge und Sicherheit).
• Der Plattform-Admin meldet sich mit einem eigenen Admin-Token an, legt Workspaces und Projekte an und kommt an jedes Projekt.