docs: bring top-level README up to date

README described only the initial v0.1.0-era bootstrap - no mention of
Authentik, coturn/TURN, monitoring, NetworkPolicies, backups, or the
Element Web/Call forks, all of which have been live for months. Also
fixed: broken TOC links (pointed to Google search instead of anchors),
stale mas-secrets.sops.yaml / ess-mas-custom-secrets references (actual
names are mas-secret.yaml / ess-mas-values-secret).

Added pointers to CLAUDE.md, docs/TASKS.md, Gitea Releases (new SemVer
scheme), the wiki, and deployment guides, plus a note recommending the
devcontainer as the primary way to get local tooling.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

README.md

@@ -4,18 +4,23 @@ Dieses Repository enthält die Infrastruktur-as-Code (IaC) für den Matrix-Homes
 
 ## 📑 Inhaltsverzeichnis
 
-1.  [Voraussetzungen & Lokale Tools](https://www.google.com/search?q=%231-voraussetzungen--lokale-tools)
-2.  [Architektur & Logik des Stacks](https://www.google.com/search?q=%232-architektur--logik-des-stacks)
-3.  [Aufbau des Repositories](https://www.google.com/search?q=%233-aufbau-des-repositories)
-4.  [Das Deployment (Aktueller Stand)](https://www.google.com/search?q=%234-das-deployment-aktueller-stand)
-5.  [Nützliche Befehle](https://www.google.com/search?q=%235-n%C3%BCtzliche-befehle)
-6.  [Troubleshooting & Known Issues](https://www.google.com/search?q=%236-troubleshooting--known-issues)
+1.  [Voraussetzungen & Lokale Tools](#1-voraussetzungen--lokale-tools)
+2.  [Architektur & Logik des Stacks](#2-architektur--logik-des-stacks)
+3.  [Aufbau des Repositories](#3-aufbau-des-repositories)
+4.  [Das Deployment (Aktueller Stand)](#4-das-deployment-aktueller-stand)
+5.  [Nützliche Befehle](#5-nützliche-befehle)
+6.  [Troubleshooting & Known Issues](#6-troubleshooting--known-issues)
+7.  [Weitere Ressourcen](#7-weitere-ressourcen)
 
 -----
 
 ## 1\. Voraussetzungen & Lokale Tools
 
-Um mit diesem Stack zu interagieren (Konfigurationen anzupassen, Secrets zu verschlüsseln, Fehler zu suchen), müssen folgende Tools lokal installiert sein:
+**Empfohlen: `.devcontainer/` nutzen** ("Reopen in Container" in VS Code, oder `docker build`
++ `docker run` manuell, siehe [`.devcontainer/README.md`](.devcontainer/README.md)) - bringt
+alle unten genannten Tools bereits fertig eingerichtet mit, ohne sie lokal zu installieren.
+
+Alternativ, um mit diesem Stack zu interagieren (Konfigurationen anzupassen, Secrets zu verschlüsseln, Fehler zu suchen), müssen folgende Tools lokal installiert sein:
 
 ### 🛠️ Benötigte CLI-Tools
 
@@ -70,9 +75,10 @@ Das Setup basiert auf einer modernen, modularen GitOps-Architektur:
 
   * **K3s**: Die leichtgewichtige Kubernetes-Distribution, die als Fundament dient.
   * **FluxCD**: Der GitOps-Controller. Er überwacht dieses Git-Repository. Ändert sich hier eine Datei, wendet Flux die Änderung automatisch im Cluster an.
-  * **SOPS**: Erlaubt es, Passwörter (z.B. SMTP) verschlüsselt in Git zu speichern. Flux entschlüsselt diese "on the fly" im Cluster.
+  * **SOPS + age**: Erlaubt es, Secrets verschlüsselt in Git zu speichern. Flux entschlüsselt diese "on the fly" im Cluster. Mehrere Secrets nutzen zusätzlich einen zweiten, eng gescopten age-Key für automatisierte Rotation (siehe coturn TURN-Secret unten).
   * **Traefik**: Der Ingress-Controller (Standard bei K3s). Er leitet Traffic von Port 80/443 an die richtigen internen Pods weiter.
   * **Cert-Manager**: Spricht mit Let's Encrypt und stellt automatisch gültige TLS-Zertifikate für alle Ingress-Routen aus.
+  * **NetworkPolicies**: Default-Deny Ingress für die `matrix`- und `authentik`-Namespaces, mit expliziten Allow-Regeln pro Komponente (`apps/production/networkpolicy.yaml`, `apps/authentik/networkpolicy.yaml`).
 
 ### Matrix Stack (ESS Community v26.4.0)
 
@@ -80,10 +86,17 @@ Die Suite ist ein "Umbrella Chart", das aus mehreren Microservices besteht:
 
   * **Synapse (`matrix.`):** Das eigentliche Backend (Homeserver) für die Chat-Nachrichten.
   * **Matrix Authentication Service (MAS) (`account.`):** Der OIDC-basierte Login-Server. Zwingend erforderlich für moderne Matrix-Clients.
-  * **Element Web (`domain.tld`):** Der Web-Client für die Endnutzer.
-  * **Matrix RTC (`mrtc.`):** Die SFU (Selective Forwarding Unit) für Audio-/Video-Calls.
+  * **Element Web (`domain.tld`):** Eigener Fork (`sorb/threadnet-web`) des Web-Clients für die Endnutzer - Custom Themes, Element Desktop Setup-Seiten, Element-Call-Anpassungen.
+  * **Matrix RTC (`mrtc.`):** Die SFU (Selective Forwarding Unit) für Audio-/Video-Calls, mit eigenem Element-Call-Fork (`sorb/threadnet-call`) für höhere Video-Defaults (bis 1440p/60fps).
+  * **coturn:** TURN/STUN-Server für WebRTC hinter NAT (`hostNetwork: true`, außerhalb der NetworkPolicy-Kontrolle, stattdessen über die Hetzner Cloud Firewall abgesichert). Shared Secret wird monatlich automatisiert rotiert.
   * **PostgreSQL:** Die relationale Datenbank für Synapse und MAS.
 
+### Identity & Observability
+
+  * **Authentik** (`auth.`, `account.`): OIDC-Identity-Provider für Matrix-Enrollment, Passwort-Recovery und optionales 2FA/Passkey. Flows/Provider/Application deklarativ als Authentik-Blueprints erfasst (`apps/authentik/authentik-blueprints.yaml`), nicht nur in der UI geklickt.
+  * **Monitoring**: Grafana Alloy sammelt Metriken/Logs, Remote-Write zu einem externen Prometheus/Loki-Stack.
+  * **Backups**: Nächtliche, verschlüsselte & deduplizierte Borg-Backups (Postgres-Dumps + Synapse-`media_store`) zu einer Hetzner Storage Box, getrennt nach Namespace, mit eigenen Repos/Passphrasen.
+
 -----
 
 ## 3\. Aufbau des Repositories
@@ -106,9 +119,14 @@ gitops/
 │       └── custom-configs/              # Eigene Anpassungen (Themes, Logging)
 │           ├── synapse-values.yaml      # Als ConfigMap
 │           ├── element-values.yaml      # Als ConfigMap
-│           └── mas-secrets.sops.yaml    # Als verschlüsseltes SOPS-Secret
+│           └── mas-secret.yaml          # Als verschlüsseltes SOPS-Secret
 ```
 
+Weitere Secret-Dateien liegen direkt unter `apps/production/` bzw. `apps/authentik/`
+(z.B. `coturn-secret.yaml`, `synapse-turn-secret.yaml`, `synapse-backup-secret.yaml`,
+`authentik-backup-secret.yaml`) - jede einzeln SOPS-verschlüsselt, nicht in `custom-configs/`
+gebündelt.
+
 **Abhängigkeits-Logik:** Flux installiert erst `infra-apps` (damit Namespaces und Repositories existieren) und danach `production-apps` (das eigentliche ESS-Chart).
 
 -----
@@ -156,7 +174,10 @@ spec:
       name: ess-synapse-custom
       valuesKey: values.yaml
     - kind: Secret
-      name: ess-mas-custom-secrets
+      name: ess-mas-values-secret
+      valuesKey: values.yaml
+    - kind: Secret
+      name: synapse-turn-secret
       valuesKey: values.yaml
   values:
     serverName: axion1337.chat
@@ -216,7 +237,7 @@ kubectl describe challenge <name> -n matrix
 Um ein Passwort im GitOps-Repo zu ändern, editiert man die verschlüsselte Datei direkt via SOPS (sie wird transparent entschlüsselt und beim Speichern wieder verschlüsselt):
 
 ```bash
-sops apps/production/custom-configs/mas-secrets.sops.yaml
+sops apps/production/custom-configs/mas-secret.yaml
 ```
 
 -----
@@ -244,4 +265,14 @@ sops apps/production/custom-configs/mas-secrets.sops.yaml
 ### Issue 4: Fehlende Zertifikate (`No resources found`)
 
   * **Ursache:** Manuelle Kustomize-Patches kollidieren mit dem Helm-Chart.
-  * **Lösung:** Manuelle Patches löschen und das native Feature des Charts nutzen: `certManager: true` auf der obersten (Root-)Ebene der `values` setzen. Das Chart erstellt daraufhin die korrekten Ingress-Annotations und Secrets von selbst.
+  * **Lösung:** Manuelle Patches löschen und das native Feature des Charts nutzen: `certManager: true` auf der obersten (Root-)Ebene der `values` setzen. Das Chart erstellt daraufhin die korrekten Ingress-Annotations und Secrets von selbst.
+
+-----
+
+## 7\. Weitere Ressourcen
+
+  * **`CLAUDE.md`** (`prod/`): Technische Referenz für KI-gestützte Arbeit an diesem Repo - Architektur, bekannte Chart-Quirks, Troubleshooting-Checkliste.
+  * **`docs/TASKS.md`**: Backlog-Pointer zu den [Gitea Issues](https://rohana.axion1337.de/sorb/axion1337.chat-gitops/issues) - Details werden nicht mehr doppelt gepflegt.
+  * **[Gitea Releases](https://rohana.axion1337.de/sorb/axion1337.chat-gitops/releases)**: Versionshistorie (SemVer, `vMAJOR.MINOR.PATCH` als Änderungsgrößen-Konvention, kein Kompatibilitätsvertrag - siehe [[00-TASKS]] Wiki für die Konvention).
+  * **[Wiki](https://rohana.axion1337.de/sorb/axion1337.chat-gitops/wiki)**: Ausführliche Historie, Incident-Notizen, Setup-Guides pro Komponente.
+  * **`docs/deployment-guides/`**: Detaillierte Guides für TURN-Server, Authentik, Monitoring, Element-Customization, Room-Policies.