# Guides

**Guides** sind Anleitungen für Setup- und Konfigurations-Aufgaben die wiederholt vorkommen — aber nicht notfall-getrieben wie Runbooks. Sie sind das **"How do we do X here"** der Firma.

## Unterschied zu Runbooks
- **Runbook:** "Der Loco-Sync ist kaputt — was jetzt?" → reagiert auf Probleme
- **Guide:** "Wie integriere ich eine neue App mit Authentik OIDC?" → proaktive Einrichtung

## Unterschied zu ADRs
- **ADR:** "Warum haben wir diese Entscheidung getroffen?"
- **Guide:** "Wie setze ich diese Entscheidung für einen neuen Service um?"

Typisch: Eine ADR legt das Pattern fest, der Guide zeigt wie man es anwendet.

## Aktuelle Guides

### Authentik
- **[authentik-oauth2-provider.md](authentik-oauth2-provider.md)** — Wie richtet man einen nativen OIDC-Provider in Authentik für eine neue App ein? Template-based, wurde zum ersten Mal für Forgejo genutzt, ist jetzt wiederverwendbar für OpenProject, Nextcloud, Grafana, etc.

## Wann neue Guides schreiben
- Wenn eine Setup-Sequenz mehr als einmal vorkommen wird
- Wenn sie mehr als 5 Schritte hat
- Wenn die korrekte Reihenfolge nicht offensichtlich ist
- Wenn es Gotchas gibt die man schnell vergessen würde

Wenn es nur einmalig ist und nie wieder vorkommt: Kein Guide, sondern direkt als ADR dokumentieren (falls eine Entscheidung drinsteckt).