refactor: Organize troubleshooting docs into docs/troubleshooting/

Move all Authentik troubleshooting guides into dedicated subdirectory:
- DIAGNOSTIK-AUTHENTIK-FLOW.md
- AUTHENTIK-FIX-TEMPLATE.md
- AUTHENTIK-INVITATION-FLOW-FIX.md
- AUTHENTIK-CREATE-INVITATION-FLOW.md

Add README.md with:
- Quick reference guide for each document
- Scenario-based navigation
- Known issues tracking
- Tips and best practices

This keeps the root directory clean and organizes related guides together.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

docs/troubleshooting/AUTHENTIK-CREATE-INVITATION-FLOW.md

@@ -0,0 +1,256 @@
+# 🆕 Authentik: Neuen Invitation Flow erstellen
+
+**Problem**: 
+- Nur ein `matrix-enrollment` Flow existiert
+- Wird für Standard-Signup + Invitations verwendet → Konflikt
+- Fehler: "Found existing plan for other flow, deleting plan"
+
+**Lösung**: Separaten `matrix-invitation` Flow für Einladungslinks erstellen.
+
+---
+
+## Schritt 1: Authentik Admin UI öffnen
+
+```bash
+kubectl port-forward -n authentik svc/authentik 9000:9000
+# Browser: http://localhost:9000/
+# Admin: akadmin / (password)
+```
+
+---
+
+## Schritt 2: Neuen Flow erstellen
+
+**Navigation**: Admin → Flows & Stages → Flows
+
+1. Klick **"Create"** (oben rechts)
+2. Fülle folgendes aus:
+
+```
+Name: matrix-invitation
+Slug: matrix-invitation
+Title: Matrix Enrollment via Invitation
+Description: Enrollment flow for users created via invitation links
+Designation: enrollment
+```
+
+3. **Speichern** (Save)
+
+---
+
+## Schritt 3: Stages zur Invitation Flow hinzufügen
+
+Nach dem Erstellen wirst du auf die Flow-Edit-Seite weitergeleitet.
+
+**Navigation**: Admin → Flows & Stages → Flows → `matrix-invitation` → Edit
+
+Klick auf "Add Stage" und folge dieser Reihenfolge:
+
+### Stage 1: Invite Stage (Invitation verarbeiten)
+
+1. Klick **"Add Stage"**
+2. Wähle: **"Invite Stage"**
+3. Konfiguriere:
+   ```
+   Name: Invite
+   Order: 1
+   ```
+4. **Save**
+
+Dann musst du das Binding setzen:
+- Klick auf die Stage in der Flow
+- Binding: **"Invite"** (oder "Invitation")
+- Required: **Yes**
+- **Save**
+
+### Stage 2: Identification Stage (Username überprüfen)
+
+1. Klick **"Add Stage"**
+2. Wähle: **"Identification Stage"** (nicht "Authenticate Stage")
+3. Konfiguriere:
+   ```
+   Name: Identification
+   Order: 2
+   User Fields: username (oder email)
+   Create Users as Inactive: NO
+   ```
+4. **Save**
+
+Binding setzen:
+- Binding: **"Identify"**
+- Required: **No**
+- **Save**
+
+### Stage 3: Prompt Stage (Daten abfragen: Username, Email, Name)
+
+1. Klick **"Add Stage"**
+2. Wähle: **"Prompt Stage"**
+3. Konfiguriere:
+   ```
+   Name: User Data
+   Order: 3
+   ```
+4. **Speichern (Save)**
+
+Dann **Fields hinzufügen**:
+- Klick auf die Stage
+- Klick **"Add Field"** für jedes Feld:
+
+#### Field 1: Username
+```
+Field Name: username
+Label: Username
+Type: text
+Required: Yes
+Placeholder: Choose a username
+```
+
+#### Field 2: Email
+```
+Field Name: email
+Label: Email Address
+Type: email
+Required: Yes
+Placeholder: your@email.com
+```
+
+#### Field 3: Name (Optional)
+```
+Field Name: name
+Label: Full Name
+Type: text
+Required: No
+Placeholder: Your Name
+```
+
+Alle Fields **Save**.
+
+Dann **Stage-Binding setzen**:
+- Binding: **"Prompt for data"** (oder "User Data")
+- Required: **Yes**
+- **Save**
+
+### Stage 4: Write Stage (User in DB erstellen)
+
+1. Klick **"Add Stage"**
+2. Wähle: **"Write Stage"** (oder "User Write Stage")
+3. Konfiguriere:
+   ```
+   Name: Create User
+   Order: 4
+   ```
+4. **Speichern (Save)**
+
+Dann **Field Bindings setzen**:
+- Klick auf die Stage
+- Unter "Field Bindings" oder "User Creation":
+  - `username` ← mapped von username Feld
+  - `email` ← mapped von email Feld
+  - `name` ← mapped von name Feld
+- **Save**
+
+Stage-Binding setzen:
+- Binding: **"Create or update user"**
+- Required: **Yes**
+- **Save**
+
+### Stage 5: Finish Stage (Abschluss)
+
+1. Klick **"Add Stage"**
+2. Wähle: **"Finish Stage"** (oder "User Login")
+3. Konfiguriere:
+   ```
+   Name: Finish
+   Order: 5
+   ```
+4. **Speichern (Save)**
+
+Stage-Binding:
+- Binding: **"Finish"** (oder "Complete enrollment")
+- Required: **Yes**
+- **Save**
+
+---
+
+## Schritt 4: Flow als Standard-Invitation setzen
+
+**Navigation**: Admin → System → Settings
+
+Suche nach "Invitation Flow" oder "Default Flows":
+1. Setze **"Invitation Flow"** auf `matrix-invitation`
+2. **Save**
+
+Alternativ:
+- Admin → Flows & Stages → Flows
+- Für jede Invitation/Group: 
+  - Klick auf Group/Invitation
+  - Setze "Enrollment Flow" auf `matrix-invitation`
+
+---
+
+## Schritt 5: Test mit neuem Einladungslink
+
+1. **Neuen Einladungslink erstellen**:
+   - Admin → Users & Groups → Invitations
+   - Klick **"Create"**
+   - Expiry: 7 days
+   - **Create & Copy Link**
+
+2. **Link öffnen** (neuer Browser/Inkognito):
+   - Link in Browser öffnen
+   - Sollte jetzt alle Felder zeigen:
+     - [ ] Username eingeben
+     - [ ] Email eingeben ← sollte jetzt da sein!
+     - [ ] Name eingeben (optional)
+     - [ ] "Weiter" oder "Sign in with Authentik"
+
+3. **Authentik Login** (falls Binding korrekt):
+   - Mit Authentik anmelden
+   - Enrollment abgeschlossen
+   - User sollte in Synapse erstellt sein
+
+---
+
+## Troubleshooting
+
+### Fehler: "Stage not found"
+- Stelle sicher, dass alle Stages ein **Binding** haben
+- Alle Bindings müssen **eindeutig** sein (nicht doppelt)
+- **Save** nach jeder Änderung
+
+### Felder werden nicht angezeigt
+- Prompt Stage überprüfen
+- Alle Fields müssen **Save** sein
+- Ggfs. Browser-Cache löschen
+
+### Fehler nach Enrollment
+- MAS Logs: `kubectl logs -f matrix-stack-matrix-authentication-service-6b994b9fcf-qqcxz -n matrix`
+- Authentik Logs: `kubectl logs -f -n authentik -l app.kubernetes.io/name=authentik`
+
+---
+
+## Erwartetes Ergebnis
+
+Nach dem Fix:
+1. Einladungslink öffnen → `matrix-invitation` Flow
+2. Username, Email, Name eingeben
+3. "Mit Authentik anmelden"
+4. Nach Login: User in Synapse erstellt
+5. Login zu ElementWeb möglich
+
+---
+
+## Checkliste
+
+- [ ] `matrix-invitation` Flow erstellt
+- [ ] 5 Stages in korrekter Reihenfolge (Invite → Identify → Prompt → Write → Finish)
+- [ ] Prompt Stage hat username, email, name Felder
+- [ ] Alle Stages haben korrektes Binding
+- [ ] `matrix-invitation` als Standard-Invitation-Flow gesetzt
+- [ ] Neuen Einladungslink erstellt und getestet
+- [ ] Test-User kann Email eingeben
+- [ ] Test-User in Synapse DB nach Login
+
+---
+
+**Sollte ca. 10-15 Minuten dauern!** 🚀

docs/troubleshooting/AUTHENTIK-FIX-TEMPLATE.md

@@ -0,0 +1,314 @@
+# ✅ Authentik Enrollment Flow – Reparatur-Template
+
+Basierend auf häufigen Problemen: Hier sind die wahrscheinlichsten Fixes.
+
+---
+
+## Problem 1: MAS kennt Authentik-OIDC nicht
+
+### Symptom
+- MAS zeigt "Sign in with Authentik" Button nicht
+- Logs: "upstream provider not configured"
+
+### Lösung
+
+**MAS Secret muss diesen Block enthalten:**
+
+```yaml
+# apps/production/custom-configs/mas-secret.yaml (decrypted)
+---
+matrixAuthenticationService:
+  upstream_oauth2_config:
+    issuer: "https://auth.axion1337.chat/application/o/matrix/"
+    client_id: "{{ CLIENT_ID_FROM_AUTHENTIK }}"
+    client_secret: "{{ CLIENT_SECRET_FROM_AUTHENTIK }}"
+    authorization_endpoint: "https://auth.axion1337.chat/application/o/authorize/"
+    token_endpoint: "https://auth.axion1337.chat/application/o/token/"
+    userinfo_endpoint: "https://auth.axion1337.chat/application/o/userinfo/"
+    scopes:
+      - "openid"
+      - "profile"
+      - "email"
+    user_mapping_provider:
+      type: "oidc"
+      config:
+        localpart_template: "{{ user.preferred_username }}"
+        display_name_template: "{{ user.name }}"
+        email_template: "{{ user.email }}"
+  
+  # Wichtig: Password-Login deaktivieren (da wir nur OIDC verwenden)
+  passwords:
+    enabled: false
+```
+
+**Wie ausfüllen:**
+
+1. Authentik Admin UI öffnen: `https://auth.axion1337.chat`
+2. Admin → Applications → Providers → "matrix-provider" (oder ähnlich)
+3. Folgende Werte kopieren:
+   - **Client ID**: Im Provider-Details zu sehen
+   - **Client Secret**: Im Provider-Details zu sehen (unter "Credentials")
+
+4. Local entschlüsseln (mit age-key):
+```bash
+cd gitops/
+sops -d -i apps/production/custom-configs/mas-secret.yaml
+```
+
+5. Datei öffnen und die Werte einfügen
+
+6. Wieder verschlüsseln:
+```bash
+sops -e -i apps/production/custom-configs/mas-secret.yaml
+```
+
+7. Commiten:
+```bash
+git add apps/production/custom-configs/mas-secret.yaml
+git commit -m "Fix: Configure MAS upstream OIDC for Authentik"
+git push
+```
+
+8. Flux triggern:
+```bash
+flux reconcile kustomization production-apps --with-source
+```
+
+9. Warten, dass MAS Pod neu startet:
+```bash
+kubectl get pods -n matrix -l app=matrix-authentication-service -w
+```
+
+---
+
+## Problem 2: Authentik Enrollment Flow ist kaputt
+
+### Symptom
+- User kommt zu Authentik-Login
+- Nach Login: "Error: Enrollment stage not found" oder ähnlich
+- Oder: Flow bricht ohne Fehlermeldung ab
+
+### Lösung
+
+**Authentik UI → Flows & Stages → Enrollment Flow überprüfen:**
+
+```
+Flows → Enrollment
+├── Stage 1: "Identify" (if not exists)
+│   └── Binding: "Identification (if not exists)"
+├── Stage 2: "Write" (wichtig!)
+│   └── Binding: "Create or update user"
+│   └── User Creation Policies: ???
+├── Stage 3: (optional) Weitere Datenerfassung
+└── Stage 4: "Finish"
+```
+
+**Häufiger Fehler**: "Write" Stage ist nicht korrekt mit den benötigten Feldern konfiguriert.
+
+**Fix:**
+
+1. Authentik Admin UI: `https://auth.axion1337.chat`
+2. **Flows & Stages** → **Stages**
+3. Nach "Write" Stage suchen (Filter: "write")
+4. Klick auf "Write Stage"
+5. **Field Bindings** überprüfen:
+   - [ ] `username` ← MUSS mit Authentik Username bindbar sein
+   - [ ] `email` ← MUSS vorhanden sein
+   - [ ] `name` ← Optional, aber empfohlen
+6. Alle sollten "required" sein (nicht optional)
+7. **Save**
+
+Dann zurück zu **Flows** → **Enrollment**:
+1. Stages überprüfen (oben)
+2. Bindings überprüfen:
+   - Each Stage hat "Binding" Feld
+   - "Write" Stage sollte mit "Create or update user" gebunden sein
+3. **Save**
+
+---
+
+## Problem 3: OIDC Token werden nicht korrekt zu Synapse weitergeleitet
+
+### Symptom
+- User kommt bis zu ElementWeb
+- Nach Login zu Authentik: "User not found in Synapse" oder Loop
+- Oder: User wird in Authentik angelegt, aber nicht in Synapse
+
+### Lösung
+
+Das ist komplexer und erfordert MAS-Konfiguration + Synapse-Konfiguration.
+
+**MAS Config (upstream_oauth2_config)** muss korrekt sein (siehe Problem 1).
+
+**Zusätzlich in MAS Secret:**
+
+```yaml
+# apps/production/custom-configs/mas-secret.yaml
+matrixAuthenticationService:
+  # ... upstream_oauth2_config ...
+  
+  # User-Provisioning Konfiguration
+  access:
+    # Benutzer aus OIDC Provider automatisch erzeugen
+    auto_provision: true
+    # Synapse URL
+    home_server: "https://matrix.axion1337.chat"
+```
+
+---
+
+## Problem 4: ElementWeb zeigt nicht automatisch OIDC-Button
+
+### Symptom
+- MAS läuft und hat OIDC konfiguriert
+- ElementWeb zeigt nur "Sign in with username" oder "SAML login"
+- Kein "Sign in with Authentik" Button
+
+### Lösung
+
+ElementWeb muss die MAS-Konfiguration kennen. Das geschieht über `.well-known/matrix/client`:
+
+**Test:**
+```bash
+curl https://axion1337.chat/.well-known/matrix/client | jq '.authentication'
+```
+
+Sollte zurückgeben:
+```json
+{
+  "flows": [
+    {
+      "stages": ["m.login.sso"]
+    }
+  ],
+  "identity_providers": [
+    {
+      "id": "authentik",
+      "name": "Authentik",
+      "icon": "...",
+      "brand": "custom"
+    }
+  ]
+}
+```
+
+Falls nicht: **ElementWeb Config in Element-Stack aktualisieren:**
+
+```yaml
+# apps/production/custom-configs/element-values.yaml
+elementWeb:
+  config:
+    auth:
+      sso_redirect_options:
+        immediate: false
+        on_welcome_page: true
+```
+
+**Dann:**
+```bash
+git add apps/production/custom-configs/element-values.yaml
+git commit -m "Fix: Enable SSO redirect in ElementWeb"
+git push
+flux reconcile kustomization production-apps --with-source
+```
+
+---
+
+## Problem 5: User kann sich anmelden, aber Boje ist nicht in Matrix
+
+### Symptom
+- Authentik-Login funktioniert
+- MAS zeigt User erfolgreich
+- ElementWeb Login funktioniert
+- **ABER**: User ist nicht in Synapse (check mit `kubectl exec -n matrix synapse ...`)
+
+### Lösung
+
+Das bedeutet: User wird nicht automatisch in Synapse provisioniert.
+
+**MAS muss User zu Synapse erstellen:**
+
+In MAS Secret, `access` Sektion:
+
+```yaml
+matrixAuthenticationService:
+  access:
+    # Synapse erlaubt neue User-Erstellung
+    homeserver: "https://matrix.axion1337.chat"
+    
+    # Optional: User automatisch erstellen
+    registration_enabled: true
+```
+
+**Synapse-seitig** muss auch User-Erstellung erlaubt sein:
+
+```yaml
+# apps/production/custom-configs/synapse-values.yaml
+synapse:
+  additional:
+    registration:
+      config: |
+        enable_registration: true
+        enable_registration_without_token: false
+        # Token wird von MAS bereitgestellt
+```
+
+---
+
+## Komplettes Test-Szenario
+
+Nach allen Fixes:
+
+1. **Browser 1**: `https://axion1337.chat` öffnen
+2. Auf ElementWeb "Sign in" klicken
+3. "Sign in with Authentik" klicken (sollte sichtbar sein)
+4. Authentik-Login durchführen (akadmin)
+5. Nach Login: Enrollment-Flow (nur falls neuer User)
+6. Zurück zu ElementWeb
+7. **Synapse prüfen**:
+```bash
+kubectl exec -it -n matrix deployment/synapse -- \
+  /usr/local/bin/psql -U synapse -d synapse -c "SELECT name, admin FROM users LIMIT 10;"
+```
+8. Neuer User sollte auftauchen
+
+---
+
+## Debugging-Commands (während Test)
+
+```bash
+# Live MAS logs (folgen)
+kubectl logs -n matrix -l app=matrix-authentication-service -f
+
+# Authentik logs
+kubectl logs -n authentik -l app.kubernetes.io/name=authentik -f
+
+# Port-Forward für manuelles Testen
+kubectl port-forward -n matrix svc/matrix-authentication-service 8765:8080
+
+# MAS Secret auslesen (im Cluster)
+kubectl get secret ess-mas-values-secret -n matrix -o jsonpath='{.data.values\.yaml}' | base64 -d
+
+# Synapse User-Liste
+kubectl exec -it -n matrix deployment/synapse -- \
+  /usr/local/bin/psql -U synapse -d synapse -c "SELECT name, admin, is_guest FROM users;"
+```
+
+---
+
+## Checkliste für erfolgreichen Fix
+
+- [ ] MAS Secret decrypted, upstream_oauth2_config eingetragen
+- [ ] Client ID + Secret von Authentik kopiert
+- [ ] MAS Secret re-encrypted und commited
+- [ ] Authentik Enrollment Flow überprüft
+- [ ] OIDC Provider in Authentik aktiv
+- [ ] OIDC Application "matrix" in Authentik existiert
+- [ ] MAS Pod neu gestartet (nach Secret-Change)
+- [ ] ElementWeb zeigt OIDC-Button
+- [ ] Test-Login durchgeführt
+- [ ] Neuer User in Synapse DB vorhanden
+
+---
+
+**Fragen?** → Siehe `DIAGNOSTIK-AUTHENTIK-FLOW.md` für tiefergehende Diagnose.

docs/troubleshooting/AUTHENTIK-INVITATION-FLOW-FIX.md

@@ -0,0 +1,244 @@
+# 🔧 Authentik Invitation Flow Fix – Für Einladungslinks
+
+**Problem**: 
+- Standard Enrollment (akadmin): ✅ funktioniert
+- Invitation Flow (Boje über Einladungslink): ❌ Nur Username gefragt, keine Email
+- Nach Enrollment: "Fehler fehlende Rechte"
+
+**Root Cause**: Invitation Flow erfasst nicht alle erforderlichen Felder (Email) für OIDC-Token-Generation.
+
+---
+
+## Phase 1: Diagnose im Authentik Admin UI
+
+```bash
+# Authentik Admin UI öffnen
+kubectl port-forward -n authentik svc/authentik 9000:9000
+# Browser: http://localhost:9000/
+# Admin credentials: akadmin / (password)
+```
+
+### 1.1 Überprüfe: Welche Flows existieren?
+
+**Navigation**: Admin → Flows & Stages → Flows
+
+Suche nach diesen Flows:
+- [ ] `enrollment` – Standard Enrollment (für akadmin)
+- [ ] `invitation` – Invitation Flow (für Einladungslinks)
+- [ ] `default-authentication-flow` – Standard Login
+
+### 1.2 Überprüfe: Standard Enrollment Flow (funktioniert)
+
+**Navigation**: Flows → `enrollment` öffnen
+
+**Stages sollten sein:**
+```
+1. Identify (if not exists)
+   └─ Binding: "Identification (if not exists)"
+
+2. Write
+   └─ Binding: "Create or update user"
+   └─ Field bindings MUST include:
+      ├─ username
+      ├─ email  ← WICHTIG
+      └─ name (optional)
+
+3. (optional) Weitere Stages
+
+4. Finish
+```
+
+**Wichtig**: Alle Felder müssen "required" sein (nicht optional).
+
+### 1.3 Überprüfe: Invitation Flow (wahrscheinlich kaputt)
+
+**Navigation**: Flows → `invitation` öffnen
+
+**Problem**: Wahrscheinlich fehlt die "Email" Stage hier!
+
+**Sollte sein:**
+```
+1. Invite Stage
+   └─ Binding: "Invite user"
+
+2. Identification (if not exists)
+   └─ Binding: "Identify"
+
+3. Prompt Stage (für zusätzliche Daten!)
+   └─ Binding: "Prompt for data"
+   └─ Fields: username, email, name, password
+
+4. Write
+   └─ Binding: "Create or update user"
+
+5. Finish
+```
+
+---
+
+## Phase 2: Reparatur der Invitation Flow
+
+### Schritt 1: Neue "Prompt Stage" erstellen (falls nicht existiert)
+
+**Navigation**: Admin → Flows & Stages → Stages
+
+1. Klick "Create"
+2. Name: `invitation-prompt` oder ähnlich
+3. Type: **"Prompt Stage"**
+4. Configure:
+   - [ ] **Fields to Prompt**:
+     - Username (required)
+     - Email (required) ← WICHTIG
+     - Name (optional)
+     - Password (optional, da OIDC)
+
+5. Save
+
+### Schritt 2: Invitation Flow reparieren
+
+**Navigation**: Admin → Flows & Stages → Flows → `invitation`
+
+**Stages in dieser Reihenfolge:**
+
+```
+Stage 1: Invite Stage
+├─ Binding: "Invite"
+├─ Required: Yes
+
+Stage 2: Identification Stage
+├─ Binding: "Identify" (oder "Identification (if not exists)")
+├─ Required: No
+
+Stage 3: [NEUE STAGE] Prompt für Email/Username
+├─ Type: "Prompt Stage"
+├─ Binding: "Prompt for data"
+├─ Fields:
+│  ├─ username (required)
+│  ├─ email (required) ← ENTSCHEIDEND
+│  └─ name (optional)
+├─ Required: Yes
+
+Stage 4: Write
+├─ Binding: "Create or update user"
+├─ User Creation Policies: (standard)
+├─ Required: Yes
+
+Stage 5: Finish
+├─ Binding: "Finish"
+├─ Required: Yes
+```
+
+**Speichern** und Testen!
+
+---
+
+## Phase 3: Teste Invitation Flow
+
+### Test 1: Neuen Einladungslink erstellen
+
+**Navigation**: Admin → Users & Groups → Invitations
+
+1. Klick "Create"
+2. Expiry: 7 days
+3. Create & Copy Link
+
+### Test 2: Einladungslink öffnen (in neuem Browser/Inkognito)
+
+1. Link öffnen
+2. Enrollment Flow sollte jetzt:
+   - [ ] Username eingeben
+   - [ ] **Email eingeben** ← Das sollte jetzt da sein!
+   - [ ] Name eingeben (optional)
+   - [ ] "Sign in with Authentik" klicken (falls Authentik-Binding korrekt)
+
+3. Nach Authentik-Login: User in Synapse erstellt?
+   ```bash
+   kubectl exec -it -n matrix matrix-stack-postgres-0 -- \
+     psql -U synapse -d synapse -c "SELECT name FROM users WHERE created_ts > now() - interval '5 minutes';"
+   ```
+
+### Test 3: Prüfe MAS Logs auf Fehler
+
+```bash
+kubectl logs -f matrix-stack-matrix-authentication-service-6b994b9fcf-qqcxz -n matrix | grep -i "error\|fail\|boje"
+```
+
+---
+
+## Phase 4: Häufige Fehler & Lösungen
+
+### Fehler 1: "Fehlende Rechte" nach Enrollment
+
+**Symptom**: Enrollment abgeschlossen, aber Fehler auf Berechtigungsseite
+
+**Ursachen**:
+- [ ] Email-Feld wurde nicht erfasst
+- [ ] OIDC-Token hat unvollständige Daten
+- [ ] Synapse User konnte nicht erstellt werden (Duplikat?)
+
+**Lösung**:
+1. Authentik Logs prüfen: `kubectl logs -n authentik -l app.kubernetes.io/name=authentik -f | grep -i "error\|invitation"`
+2. MAS Logs prüfen: `kubectl logs -f matrix-stack-matrix-authentication-service-6b994b9fcf-qqcxz -n matrix | grep -i "boje\|error"`
+3. Synapse Logs prüfen: `kubectl logs -f -n matrix matrix-stack-synapse-0 | grep -i "boje\|register"`
+
+### Fehler 2: "Stage not found" oder "Flow invalid"
+
+**Ursache**: Invitation Flow hat Binding-Fehler
+
+**Lösung**:
+1. Admin UI → Flows → Invitation Flow öffnen
+2. Alle Stages überprüfen, dass sie korrekt gebunden sind
+3. Keine leeren/ungültigen Bindings
+4. Save & Retry
+
+### Fehler 3: Email-Feld wird nicht angezeigt
+
+**Ursache**: Prompt Stage hat email nicht in Fields
+
+**Lösung**:
+1. Admin UI → Flows → Stages → Prompt Stage öffnen
+2. Edit → Fields überprüfen
+3. Email hinzufügen if missing:
+   - Field name: `email`
+   - Type: `email`
+   - Required: Yes
+4. Save
+
+---
+
+## Erwarteter Ablauf nach Fix
+
+1. Browser öffnet Einladungslink → Enrollment Flow
+2. "Username eingeben" → z.B. "boje"
+3. **"Email eingeben"** ← Sollte jetzt da sein
+4. "Name eingeben" (optional)
+5. "Weiter" oder "Mit Authentik anmelden"
+6. Authentik Login
+7. Enrollment abgeschlossen
+8. User "boje" in Synapse DB angelegt
+9. Login zu ElementWeb möglich
+
+---
+
+## Checkliste
+
+- [ ] Authentik Admin UI geöffnet (port-forward 9000)
+- [ ] Standard Enrollment Flow überprüft (funktioniert mit akadmin)
+- [ ] Invitation Flow überprüft
+- [ ] Prompt Stage existiert mit email field
+- [ ] Invitation Flow hat alle 5 Stages in korrekter Reihenfolge
+- [ ] Neuen Einladungslink erstellt und getestet
+- [ ] Test-User hat Email eingeben können
+- [ ] Test-User in Synapse DB nach Login
+- [ ] MAS Logs zeigen keine Fehler
+
+---
+
+**Frage**: Stimmt das mit deiner Beobachtung überein - dass bei der Einladung **nur Username** gefragt wurde, aber **nicht die Email**?
+
+Wenn ja, dann ist der Fix:
+1. Prompt Stage erstellen/reparieren (mit email field)
+2. Zur Invitation Flow hinzufügen
+3. Testen
+
+Soll ich dir noch mehr Detailschritte geben?

docs/troubleshooting/DIAGNOSTIK-AUTHENTIK-FLOW.md

@@ -0,0 +1,261 @@
+# 🔍 Authentik Enrollment Flow – Diagnostik & Reparaturplan
+
+**Symptom**: 
+- `akadmin` wurde manuell in Matrix-DB angelegt (funktioniert)
+- `Boje` wurde nur in Authentik erstellt, nicht in Matrix-DB (kaputt)
+- Beide sollen denselben Enrollment Flow verwenden
+
+**Vermutung**: Die Authentik → MAS → Synapse Kette ist unterbrochen
+
+---
+
+## Phase 1: Diagnose (Bestandsaufnahme)
+
+### 1.1 Authentik Logs prüfen
+
+```bash
+# Authentik Server logs
+kubectl logs -n authentik -l app.kubernetes.io/name=authentik -f | grep -i "oauth\|oidc\|enroll\|flow"
+
+# Worker logs
+kubectl logs -n authentik -l app.kubernetes.io/component=worker -f | grep -i "enroll"
+```
+
+**Worauf achten**:
+- Fehler bei "Enrollment create"?
+- OIDC Token-Probleme?
+- Flow-Validierungsfehler?
+
+### 1.2 MAS (Matrix Authentication Service) Logs prüfen
+
+```bash
+# MAS logs
+kubectl logs -n matrix -l app=matrix-authentication-service -f | grep -i "oauth\|upstream\|user\|oidc"
+```
+
+**Worauf achten**:
+- Verbindung zu Authentik erfolgreich?
+- Token-Validierung fehlgeschlagen?
+- User-Provisioning-Fehler?
+
+### 1.3 Synapse Logs prüfen
+
+```bash
+# Synapse logs (für User-Erstellung)
+kubectl logs -n matrix -l app=synapse -f | grep -i "user\|provision\|register\|auth"
+```
+
+**Worauf achten**:
+- User-Registrierungs-Fehler?
+- Provisioning-Fehler?
+- Authentifizierungsprobleme?
+
+---
+
+## Phase 2: Authentik UI Überprüfung
+
+### 2.1 Enrollment Flow inspizieren
+
+```bash
+# Authentik UI öffnen
+kubectl port-forward -n authentik svc/authentik 9000:9000
+# → Browser: http://localhost:9000
+# → Admin UI → Flows & Stages → "Enrollment" Flow suchen
+```
+
+**Checklist**:
+- [ ] Flow existiert und heißt "Enrollment"
+- [ ] Reihenfolge der Stages:
+  1. Identify (optional)
+  2. Write (User-Erstellung)
+  3. Enrollment (if-condition für neuen User)
+  4. Verification (optional)
+- [ ] "Write Stage" bindet sich an:
+  - [ ] Username
+  - [ ] Email
+  - [ ] Name
+- [ ] Alle Bindings sind "required" (nicht optional)
+
+### 2.2 OIDC Provider in Authentik prüfen
+
+```bash
+# Über Authentik UI:
+# Admin → Applications → Providers → "matrix-provider" (oder ähnlich)
+```
+
+**Checklist**:
+- [ ] Provider existiert
+- [ ] Name: z.B. "matrix-provider"
+- [ ] Client Type: "Confidential"
+- [ ] Redirect URIs enthalten:
+  - [ ] `https://account.axion1337.chat/upstream/callback/*`
+  - [ ] `https://account.axion1337.chat/upstream/callback/01KQDJTR1ZVTG8JQ220F5BNBFZ` (exact)
+- [ ] Scopes: `openid profile email`
+- [ ] Client ID + Secret kopiert?
+
+### 2.3 OIDC Application in Authentik
+
+```bash
+# Admin → Applications → Applications → "matrix"
+```
+
+**Checklist**:
+- [ ] Application existiert mit Slug "matrix"
+- [ ] Provider ist zugewiesen
+- [ ] Enrollment Flow ist zugewiesen (nicht "deny")
+- [ ] Enrollment Flow ist die richtige (die von oben)
+
+### 2.4 Test-User "Boje" inspizieren
+
+```bash
+# Admin → Directory → Users → "Boje"
+```
+
+**Checklist**:
+- [ ] Username: `boje`
+- [ ] Email: `boje@...` (vorhanden?)
+- [ ] Groups: Falls erforderlich, die richtigen Groups zugewiesen?
+- [ ] Status: Active oder Disabled?
+- [ ] Sessions: Aktive Logins?
+
+---
+
+## Phase 3: MAS Konfiguration überprüfen
+
+### 3.1 Current MAS Secret auslesen
+
+Da der age-key nicht lokal verfügbar ist, müssen wir die Konfiguration im Cluster prüfen:
+
+```bash
+# MAS Config im Cluster auslesen (nicht verschlüsselt)
+kubectl get secret ess-mas-values-secret -n matrix -o jsonpath='{.data.values\.yaml}' | base64 -d | yq . | head -100
+```
+
+**Worauf achten**:
+- [ ] `upstream_oauth2_config` Block existiert
+- [ ] `upstream_oauth2_config.issuer`: `https://auth.axion1337.chat/application/o/matrix/`
+- [ ] `upstream_oauth2_config.client_id`: Authentik Client ID
+- [ ] `upstream_oauth2_config.client_secret`: Authentik Client Secret (*)
+- [ ] `upstream_oauth2_config.scopes`: `["openid", "profile", "email"]`
+- [ ] `upstream_oauth2_config.user_mapping_provider`:
+  - `type`: "oidc"
+  - `config.localpart_template`: `{{ user.preferred_username }}`
+  - `config.display_name_template`: `{{ user.name }}`
+  - `config.email_template`: `{{ user.email }}`
+
+### 3.2 MAS Pod exec – Config live prüfen
+
+```bash
+# MAS Config im laufenden Pod inspizieren
+kubectl exec -it -n matrix deployment/matrix-authentication-service -- cat /etc/mas/config.yaml | grep -A50 upstream_oauth2_config
+```
+
+**Worauf achten**:
+- Config ist syntaktisch korrekt (YAML)?
+- Indentierung ist richtig?
+- Werte sind vorhanden?
+
+### 3.3 MAS OIDC Discovery prüfen
+
+```bash
+# Authentik OIDC Discovery Endpoint
+curl -s https://auth.axion1337.chat/application/o/matrix/.well-known/openid-configuration | jq .
+
+# Sollte zurückgeben:
+# {
+#   "issuer": "https://auth.axion1337.chat/application/o/matrix/",
+#   "token_endpoint": "https://auth.axion1337.chat/application/o/token/",
+#   "authorization_endpoint": "...",
+#   ...
+# }
+```
+
+---
+
+## Phase 4: Login-Flow Testen
+
+### 4.1 MAS Login UI öffnen
+
+```bash
+# Port-Forward zu MAS
+kubectl port-forward -n matrix svc/matrix-authentication-service 8765:8080
+# → Browser: http://localhost:8765
+```
+
+**Test**:
+1. Auf MAS-Seite: "Sign in with Authentik" klicken
+2. Authentik-Login durchführen
+3. Auf Enrollment Flow warten
+4. Neuen User erstellen (Test-Username, Email, Password)
+5. Nach erfolgreicher Registrierung: Matrix home_server erhalten?
+
+### 4.2 Fehlerberichte
+
+Falls Fehler auftritt:
+- [ ] Screenshot des Fehlers
+- [ ] MAS logs auslesen: `kubectl logs -n matrix -l app=matrix-authentication-service --tail=50`
+- [ ] Authentik logs auslesen: `kubectl logs -n authentik -l app.kubernetes.io/name=authentik --tail=50`
+
+---
+
+## Phase 5: Reparaturschritte (nachdem Diagnose klar ist)
+
+### Falls MAS-Config fehlerhaft:
+
+```bash
+# 1. Secrets entschlüsseln (lokale Umgebung mit age-key erforderlich)
+sops -d apps/production/custom-configs/mas-secret.yaml > /tmp/mas-secret-decrypted.yaml
+
+# 2. Editor öffnen und Konfiguration reparieren
+vim /tmp/mas-secret-decrypted.yaml
+# → upstream_oauth2_config überprüfen und korrigieren
+
+# 3. Wieder verschlüsseln
+sops -e /tmp/mas-secret-decrypted.yaml > apps/production/custom-configs/mas-secret.yaml
+
+# 4. Commiten
+git add apps/production/custom-configs/mas-secret.yaml
+git commit -m "Fix: Correct MAS upstream_oauth2_config for Authentik integration"
+
+# 5. Flux triggern
+flux reconcile kustomization production-apps --with-source
+```
+
+### Falls Authentik Enrollment Flow fehlerhaft:
+
+1. Admin UI öffnen: `kubectl port-forward -n authentik svc/authentik 9000:9000`
+2. Flows → Enrollment Flow öffnen
+3. Stages überprüfen und in richtige Reihenfolge bringen:
+   - **Identify**: Benutzer identifizieren
+   - **Write**: Benutzer in DB speichern
+   - **Enrollment**: Weitere Felder (optional)
+   - **Finish**: Abschluss
+4. Speichern
+5. Neuen Test-User erstellen und Enrollment durchlaufen
+
+---
+
+## Erwartete Endergebnisse
+
+Nach erfolgreichem Fix:
+1. Benutzer klickt "Sign in with Authentik" auf MAS
+2. Authentik-Login-Seite wird angezeigt
+3. Nach Login: Enrollment Flow wird angezeigt
+4. User füllt Formular aus
+5. Nach "Finish": Authentik erstellt User UND verbindet zu Matrix
+6. User wird in Matrix-DB angelegt (`_matrix_auth` prefix)
+7. User kan sich bei ElementWeb anmelden
+
+---
+
+## 🎯 Nächster Schritt
+
+Bitte folgende Diagnostik durchlaufen und mir die Output berichte:
+
+1. **MAS Logs** (letzten 30 Zeilen)
+2. **Authentik Logs** (letzten 30 Zeilen) 
+3. **MAS Secret (entschlüsselt)** – upstream_oauth2_config Block
+4. **Authentik OIDC Discovery** Output
+5. **Screenshots** der Authentik UI (Enrollment Flow, OIDC Provider, Application)
+
+Damit kann ich dann genau sehen, wo der Bruch in der Kette ist! 🔗

docs/troubleshooting/README.md

@@ -0,0 +1,112 @@
+# 🔧 Troubleshooting Guides
+
+Dieser Ordner enthält detaillierte Troubleshooting- und Reparaturanleitungen für häufige Probleme bei der Authentik/MAS/Matrix Integration.
+
+---
+
+## 📖 Guides
+
+### 1. **DIAGNOSTIK-AUTHENTIK-FLOW.md**
+**Für**: Vollständige Diagnose des Authentik Enrollment Flows  
+**Wann**: Wenn Sie systematisch überprüfen möchten, ob die gesamte OIDC-Kette (Authentik → MAS → Synapse) funktioniert  
+**Umfasst**:
+- Authentik Logs analysieren
+- MAS Konfiguration überprüfen
+- OIDC Discovery testen
+- Enrollment Flow inspizieren
+- Fehlersuche mit Debugging-Commands
+
+**Status**: Nutzer Boje - Nur in Authentik erstellt, nicht in Synapse
+
+---
+
+### 2. **AUTHENTIK-FIX-TEMPLATE.md**
+**Für**: Konkrete Reparaturen bei MAS/Authentik Integration  
+**Wann**: Wenn Sie wissen, welches Problem Sie haben und schnelle Lösungen suchen  
+**Behandelt**:
+- Problem 1: MAS kennt Authentik-OIDC nicht
+- Problem 2: Authentik Enrollment Flow kaputt
+- Problem 3: OIDC Token werden nicht weitergeleitet
+- Problem 4: ElementWeb zeigt keinen OIDC-Button
+- Problem 5: User in Authentik aber nicht in Synapse
+
+**Status**: Best Practices für häufige Probleme
+
+---
+
+### 3. **AUTHENTIK-INVITATION-FLOW-FIX.md**
+**Für**: Reparatur des Invitation Flows bei Einladungslinks  
+**Wann**: Wenn Nutzer via Einladungslink nicht korrekt erstellt werden  
+**Problem**: Invitation Flow erfasst nur Username, nicht Email/Name  
+**Lösung**:
+- Prompt Stage mit Email-Feld erstellen/reparieren
+- Zur Invitation Flow hinzufügen
+- Testen mit neuem Einladungslink
+
+**Status**: Nutzer Klaus - Fehler "kein ausstehender benutzer Anfrage wurde verweigert"
+
+---
+
+### 4. **AUTHENTIK-CREATE-INVITATION-FLOW.md** ⭐ **WICHTIGSTE ANLEITUNG**
+**Für**: Neuen separaten Invitation Flow erstellen  
+**Wann**: Wenn nur ein `matrix-enrollment` Flow existiert (Standard + Invitations gemeinsam)  
+**Root Cause**: Flow-Konflikt durch gemeinsamen Flow  
+**Lösung** (Schritt-für-Schritt):
+1. Neuen Flow `matrix-invitation` erstellen
+2. 5 Stages konfigurieren (Invite → Identify → Prompt → Write → Finish)
+3. Email-Feld in Prompt Stage hinzufügen
+4. Invitations auf neuen Flow setzen
+5. Testen
+
+**Zeitaufwand**: ~20 Minuten  
+**Status**: Aktuell für Klaus/Boje notwendig
+
+---
+
+## 🎯 Schneller Einstieg
+
+### Szenario 1: "Enrollment funktioniert nicht, ich weiß nicht warum"
+→ **Start**: `DIAGNOSTIK-AUTHENTIK-FLOW.md`
+
+### Szenario 2: "Einladungslink funktioniert nicht"
+→ **Start**: `AUTHENTIK-CREATE-INVITATION-FLOW.md` (wenn nur ein Flow existiert)  
+→ oder `AUTHENTIK-INVITATION-FLOW-FIX.md` (wenn zwei Flows existieren)
+
+### Szenario 3: "Ich kenne das Problem und brauche Lösungen"
+→ **Start**: `AUTHENTIK-FIX-TEMPLATE.md`
+
+### Szenario 4: "Alles ist kaputt, ich brauche alles Schritt-für-Schritt"
+→ **Start**: `AUTHENTIK-CREATE-INVITATION-FLOW.md` → `AUTHENTIK-FIX-TEMPLATE.md` → `DIAGNOSTIK-AUTHENTIK-FLOW.md`
+
+---
+
+## 📋 Bekannte Probleme
+
+| Problem | Nutzer | Guide | Status |
+|---------|--------|-------|--------|
+| Nur Standard Enrollment funktioniert | akadmin ✅ | - | Resolved |
+| User nur in Authentik, nicht in Synapse | Boje | `DIAGNOSTIK-AUTHENTIK-FLOW.md` | In Progress |
+| Einladungslink-Fehler: "kein ausstehender benutzer" | Klaus | `AUTHENTIK-CREATE-INVITATION-FLOW.md` | In Progress |
+| OIDC-Integration unklar | General | `AUTHENTIK-FIX-TEMPLATE.md` | Reference |
+
+---
+
+## 🔗 Verwandte Dokumentation
+
+- `../README.md` – Hauptdokumentation & Architektur
+- `../TASKS.md` – Aufgabenliste & Meilensteine
+- `../deployment-guides/` – Deployment-Anleitungen für andere Components
+
+---
+
+## 💡 Tipps
+
+- **Immer Logs überprüfen** bevor man herumrät: `kubectl logs -f -n <namespace> <pod>`
+- **Browser-Cache löschen** nach Authentik-Änderungen
+- **Port-Forward nutzen** für lokales Testen: `kubectl port-forward -n authentik svc/authentik 9000:9000`
+- **Kleine Tests machen** (einen User mit Invitation testen, nicht 10 auf einmal)
+
+---
+
+**Zuletzt aktualisiert**: 2026-05-18  
+**Verfasser**: Claude Code + Thore