munin/internal/hilfe/seiten/weboberflaeche.md

Die Weboberfläche ist der Zugang für Menschen. Sie zeigt dasselbe Wissen, das
auch die Agenten sehen.

## Anmelden

Angemeldet wird mit dem API-Key des Projekts, also demselben, den auch das
KI-Werkzeug benutzt. Einen Benutzernamen gibt es nicht: Der Key bestimmt, wer
du bist, in welchem Projekt du arbeitest und was du darfst. Wird der Key
zurückgezogen, endet auch die Sitzung im Browser sofort.

## Finden

- **Suchen:** Das Suchfeld über der Eintragsliste durchsucht Titel,
  Schlagworte und Inhalt. Titel zählen am stärksten. Umlaute sind egal:
  „Uberblick“ findet auch „Überblick“. Ein Wortanfang reicht, „deploy“ findet
  auch „Deployment“. Ebenso findet „prozess“ den „Releaseprozess“ und
  „zertifikate“ das „Zertifikat“. Kleine Tippfehler gleicht die Suche aus,
  wenn sonst nichts passt: „deploymnet“ findet „Deployment“. Genaue Treffer
  stehen immer vor ungefähren.
- **Nach Schlagwort filtern:** In der Seitenleiste stehen die zehn häufigsten
  Schlagworte des Projekts. Ein Klick filtert die Liste. Gibt es mehr, führt
  *Alle Schlagworte…* zu einer Seite mit der vollständigen Liste, nach
  Häufigkeit oder alphabetisch sortiert und mit einem Filterfeld.
- **Verweisen folgen:** Unter jedem Eintrag steht, welche anderen Einträge auf
  ihn verweisen, und unter *Auch verwandt* die Einträge, die über einen
  Zwischeneintrag mit ihm verknüpft sind (siehe [unten](#verwandte-eintraege)).
- **Veraltete Einträge:** Einträge, die seit über einem Jahr niemand geändert
  hat, tragen die Marke *veraltet*. Neben dem Suchfeld steht dann ein Link wie
  *3 veraltet*, der die Liste auf genau diese Einträge filtert. Die Zahl steht
  auch auf der Nutzungsseite. Ein veralteter Eintrag kann noch stimmen, sollte
  aber geprüft werden: Stimmt er noch, einmal speichern (oder kuratieren), dann
  zählt er wieder als aktuell; sonst korrigieren oder löschen.
- **Tastenkürzel:** `/` springt ins Suchfeld, `n` legt einen neuen Eintrag an,
  `e` bearbeitet den angezeigten Eintrag, `Strg+Enter` (Mac: `Cmd+Enter`)
  speichert im Formular. Die Buchstaben gelten nur, wenn gerade kein
  Eingabefeld aktiv ist, und nur, wo die Rolle das darf.
- **Graph:** Unter *Graph* in der Seitenleiste zeigt Munin, wie die Einträge
  über Verweise zusammenhängen. Gestrichelte Knoten sind Verweisziele, zu denen
  es noch keinen Eintrag gibt. Mausrad zoomt, Ziehen verschiebt, ein Klick
  öffnet den Eintrag. Beschriftet sind zunächst nur die wichtigsten Knoten;
  beim Hineinzoomen rücken die Knoten auseinander und weitere Namen
  erscheinen. Zeigt die Maus auf einen Knoten, treten er und seine direkten
  Nachbarn hervor. Bei sehr großen Projekten zeigt der Graph nur die 150 am
  stärksten verknüpften Einträge.

## Schreiben

Mit der Rolle `write` oder `admin` gibt es über der Liste den Knopf
**Neuer Eintrag** und in jedem Eintrag **Bearbeiten**.

| Feld | Bedeutung |
|---|---|
| Titel | Worum es geht, am besten als Frage oder klares Thema |
| Bezeichner | Der dauerhafte Name, siehe [Begriffe](/hilfe/begriffe). Leer lassen, dann wird er aus dem Titel abgeleitet. |
| Schlagworte | Durch Komma getrennt. Möglichst vorhandene wiederverwenden. |
| Inhalt | Markdown (siehe unten) |
| Kuratiert | Haken setzen, wenn der Inhalt geprüft und verlässlich ist |

**Bevor du einen neuen Eintrag anlegst**, such kurz, ob es das Thema schon gibt.
Ergänzen ist fast immer besser als ein zweiter Eintrag.

### Gibt es schon?

Beim Tippen des Titels eines neuen Eintrags zeigt Munin darunter vorhandene
Einträge mit ähnlichem Titel, samt der Wörter, die sie gemeinsam haben. Das
ist dieselbe Prüfung, mit der Munin bei Agenten nachfragt, bevor sie einen
zweiten Eintrag zum selben Thema anlegen. Hier ist es nur ein Hinweis:
Passt einer, öffne ihn (der Link geht in einem neuen Tab auf) und schreib dort
weiter. Ist es ein anderes Thema, einfach speichern.

### Ungespeicherte Änderungen

Wer im Formular etwas geändert hat und die Seite verlässt, ohne zu speichern,
etwa durch einen Klick in der Seitenleiste, bekommt eine Rückfrage des
Browsers. Den Wortlaut legt der Browser fest.

### Markdown im Inhalt

Unterstützt werden die üblichen Auszeichnungen:

```markdown
## Zwischenüberschrift

Normaler Text mit **fett**, *kursiv* und `Code`.

- Aufzählung
- noch ein Punkt

1. Nummerierte Schritte
2. zweiter Schritt

[Ein Link](https://example.org)

Siehe auch [[anderer-eintrag]].
```

Dazu kommen die Erweiterungen, die man von GitHub oder GitLab kennt:

```markdown
| Umgebung | Adresse        |
|----------|----------------|
| Test     | test.intern    |
| Prod     | prod.intern    |

- [x] erledigt
- [ ] noch offen

~~veraltet~~ — durchgestrichen

https://example.org wird ohne Klammern zum Link.
```

Codeblöcke stehen zwischen drei Backticks. Eingebettetes HTML wird aus
Sicherheitsgründen nicht ausgeführt.

### Verweise mit Autovervollständigung

Tippe `[[` in das Inhaltsfeld. Munin schlägt passende Einträge vor. Mit den
Pfeiltasten auswählen und mit Enter oder Tab übernehmen, oder einfach anklicken.
Eingefügt wird der Bezeichner, nicht der Titel.

### Vorschau

Über dem Inhaltsfeld wechselst du zwischen **Schreiben** und **Vorschau**. Die
Vorschau zeigt den Eintrag genau so, wie er nach dem Speichern aussehen wird.

### Wenn jemand gleichzeitig ändert

Hat jemand anderes (ein Mensch oder ein Agent) den Eintrag geändert, während du
ihn bearbeitet hast, meldet Munin beim Speichern einen Konflikt, statt die
fremde Änderung zu überschreiben. Dein Text bleibt im Formular erhalten. Öffne
den Eintrag in einem zweiten Tab, übernimm dort deine Änderungen in den
aktuellen Stand und speichere dann dort.

## Verwandte Einträge

Unter einem Eintrag stehen zwei Listen:

- **Verweist hierher:** Einträge, die mit `[[…]]` direkt auf diesen verweisen.
- **Auch verwandt:** Einträge, die über einen **Zwischeneintrag** verknüpft
  sind, mit dem Hinweis *über …*. Verweist „Deployment“ auf „Pipeline“ und
  „Pipeline“ auf „Runner“, steht unter „Deployment“: *Runner, über pipeline*.

So findet man Zusammenhänge, die kein Suchwort gemeinsam haben, aber von
jemandem bewusst verknüpft wurden. Agenten bekommen dasselbe über das Werkzeug
`related`.

## Verlauf und Vergleich

In jedem Eintrag führt **Fassung n, Verlauf ansehen** zu allen früheren
Fassungen. Bei jeder Fassung zeigt **Änderungen ansehen** Zeile für Zeile, was
sich zur nächsten Fassung geändert hat. So lässt sich nachvollziehen, was ein
Agent geändert hat.

Mit Schreibrecht holt **Wiederherstellen** (im Verlauf oder auf der
Vergleichsseite) eine alte Fassung mit einem Klick zurück: Titel, Inhalt und
Schlagworte. Dabei geht nichts verloren — der bisherige Stand wird selbst zu
einer Fassung im Verlauf, und das Protokoll vermerkt, welche Fassung
zurückgeholt wurde. Hat jemand den Eintrag geändert, während du den Verlauf
angesehen hast, wird nichts überschrieben; prüfe dann den neuen Stand und
versuche es erneut.

Der Haken **Kuratiert** bleibt beim Wiederherstellen so, wie er gerade ist. Hat
ein Agent einen geprüften Eintrag geändert (dabei fällt der Haken weg) und
holst du den geprüften Stand zurück, setze den Haken danach wieder.

## Papierkorb

**Löschen** legt einen Eintrag in den Papierkorb, egal ob ein Mensch in der
Oberfläche löscht oder ein Agent über `forget`. Der Eintrag verschwindet sofort
aus Liste, Suche, Graph und allen Antworten an Agenten. Mit Verlauf und
Schlagworten bleibt er aber 30 Tage erhalten; danach entfernt Munin ihn
endgültig.

Den Papierkorb findest du mit Schreibrecht in der Seitenleiste. Dort steht zu
jedem Eintrag, wer ihn wann gelöscht hat:

- **Wiederherstellen** holt einen Eintrag unverändert zurück.
- **Endgültig löschen** entfernt ihn sofort, samt Verlauf. Das ist gedacht für
  Inhalte, die nicht 30 Tage liegen bleiben sollen, etwa ein versehentlich
  abgelegtes Passwort. Rückgängig machen lässt sich das nicht.
- Ein Klick auf den **Namen eines Zugangs** zeigt nur, was dieser gelöscht hat.
  Hat ein Agent zu gründlich aufgeräumt, holt *Alle … wiederherstellen* alles
  auf einmal zurück.

Wer mit Leserecht angemeldet ist, sieht den Papierkorb nicht. Oft wird ein
Eintrag ja gerade deshalb gelöscht, weil nicht jeder ihn sehen soll.

Legst du einen Eintrag mit einem Bezeichner an, der noch im Papierkorb liegt,
holt Munin den alten Eintrag zurück und überschreibt ihn. Der gelöschte Stand
steht dann im Verlauf, und ein Hinweis sagt dir, dass das passiert ist.

Veraltetes trotzdem lieber überarbeiten als löschen: Überarbeitetes bleibt
auffindbar, und der Verlauf zeigt, was sich geändert hat.

## Viele Einträge auf einmal

Mit Schreibrecht hat die Eintragsliste vor jedem Eintrag ein Auswahlkästchen.
Unter der Liste gibt es für alle ausgewählten Einträge zwei Aktionen:

- **Schlagworte ändern:** hinzufügen oder entfernen, mehrere durch Komma
  getrennt, dann *Anwenden*. Praktisch, um ein Schlagwort umzubenennen: das
  neue hinzufügen, das alte entfernen.
- **In den Papierkorb:** legt alle ausgewählten Einträge nach einer Rückfrage
  in den Papierkorb, wie das Löschen eines einzelnen Eintrags. Danach stehst
  du wieder in derselben Liste, mit derselben Suche oder demselben Filter. War
  es zu viel, holt der Papierkorb alles mit *Alle … wiederherstellen* in einem
  Zug zurück.

## Import

Mit der Rolle `admin` gibt es in der Seitenleiste den Punkt *Import*. Dort
lässt sich ein ZIP-Archiv mit Markdown-Dateien hochladen. Jede Datei wird ein
Eintrag. Das passt für drei Fälle:

- **Wiederherstellen** aus dem Markdown-Export: das ZIP aus *Als ZIP herunterladen*
  direkt hochladen, oder den Ordner eines Projekts aus dem Exportverzeichnis
  des Servers packen und hochladen. Schlagworte, Autor, Herkunft, Prüfvermerk und
  Änderungsdatum bleiben erhalten.
- **Umzug** eines Projekts auf einen anderen Server oder in einen anderen
  Workspace, auf demselben Weg.
- **Vorhandene Dokumentation** übernehmen. Der Bezeichner kommt aus dem
  Dateinamen, der Titel aus der ersten Überschrift `# …`. Unterordner sind
  erlaubt, im Projekt stehen die Einträge danach aber nebeneinander.

Gibt es einen Bezeichner schon, wird die Datei entweder **übersprungen**
(Standard) oder sie **überschreibt** den Eintrag. Beim Überschreiben wandert
der bisherige Stand in den Verlauf, verloren geht also nichts. Dateien, die
nichts ändern würden, werden in beiden Fällen nicht geschrieben. Derselbe
Import lässt sich deshalb gefahrlos wiederholen.

**Nur Vorschau** ist beim ersten Hochladen angehakt. Die Tabelle zeigt dann
für jede Datei, was passieren würde, ohne etwas zu schreiben. Passt alles,
dasselbe Archiv ohne den Haken noch einmal hochladen.

Nicht übernommen wird der Verlauf, denn der Export enthält nur den aktuellen
Stand. Ein importierter Eintrag beginnt deshalb wieder bei Fassung 1.

## Export als ZIP

Mit der Rolle `admin` steht über der Eintragsliste der Knopf *Als ZIP
herunterladen*. Ein Klick lädt alle Einträge des Projekts als ZIP-Archiv herunter: je Eintrag
eine Markdown-Datei mit allen Feldern im Kopf, dazu eine Übersicht
`_index.md`. Der Papierkorb und der Verlauf älterer Fassungen sind nicht
enthalten.

Das Archiv passt unverändert in den [Import](#import), in dieses oder ein
anderes Projekt, auch auf einem anderen Server. Jeder Download steht im
Protokoll.

## Protokoll

Unter *Protokoll* in der Seitenleiste steht, wer im Projekt wann etwas
geschrieben, gelöscht oder sich angemeldet hat.