pyramid/CLAUDE.md

# Pyramid – Arbeitsregeln für Claude

Pyramid ist Bernds eigener Matrix-Client (Flutter, kein FluffyChat-Fork). Bernd ist
**kein Entwickler** – er gibt Ziele und Prioritäten vor, Claude trifft die technischen
Entscheidungen und erklärt sie in einfachem Deutsch. Die App ist bei echten Nutzern im
Einsatz (u. a. Uta) – Stabilität und Datensicherheit gehen vor Feature-Tempo.

**Dies ist das einzige aktuelle Repo:** `C:\Users\nordm\pyramid - Kopie\`.
(`C:\Users\nordm\pyramid` und `C:\Users\nordm\MatrixPi\pyramid` sind veraltete
April-Schnappschüsse – dort NIE arbeiten.)

> **Bernds Entscheidungen zu den offenen Richtungsfragen stehen in `ANTWORTEN_BERND.md`
> (zuletzt 2026-07-05) – vor dem Abarbeiten von ROADMAP-Punkten lesen, sie sind maßgeblich.**

## Infrastruktur

- Homeserver: Continuwuity auf dem Pi5 (`steggi-matrix.work`)
- LiveKit/TURN: Hetzner „Leuchtturm" → `wss://livekit.steggi-matrix.work` (API-Key LKMatrixPi), coturn 94.130.78.116:3478
- Git-Remote: Gitea auf dem Pi (`http://192.168.178.71:3000/steggi/pyramid.git`) – Push = Backup
- Push-Benachrichtigungen: FCM + Sygnal auf dem Pi (Memory „Pyramid Push" lesen, bevor daran gearbeitet wird)
- Vollbackup vom 2026-07-03: `MatrixPi\backups\pyramid-kopie_backup_2026-07-03.tar.gz`

## Arbeitszyklus (IMMER einhalten)

Jede Session – egal ob frisch gestartet oder fortgesetzt – läuft so:

1. **Einlesen:** `PROGRESS.md` (letzter Stand, Stolperfallen) und `ROADMAP.md`
   (nächster offener Punkt) lesen. NIE Arbeit doppelt machen, die dort als erledigt steht.
2. **Einen Punkt nehmen:** den obersten nicht abgehakten Punkt des aktuellen Meilensteins
   aus `ROADMAP.md` – nicht mehrere gleichzeitig, keine Sprünge in spätere Meilensteine.
3. **Umsetzen & prüfen:** Nach der Änderung mindestens `flutter analyze` sauber bekommen;
   wo sinnvoll `flutter test` und `flutter run -d windows` (schnellster Praxistest).
4. **Protokollieren:** `PROGRESS.md` aktualisieren (Format siehe dort) und den Punkt in
   `ROADMAP.md` abhaken.
5. **Commit + Push:** kleiner `git commit` (`feat:`/`fix:`/`refactor:`/`chore:`) und
   `git push origin master` (Gitea = Backup). Lieber 5 kleine Commits als ein riesiger.
6. Weiter mit dem nächsten Punkt, solange Kontingent/Zeit da ist.

Wird eine Session mitten in einem Punkt abgebrochen (Limit erreicht), MUSS der letzte
Eintrag in `PROGRESS.md` den Zwischenstand beschreiben: was halb fertig ist, welche
Dateien angefasst wurden, was der nächste konkrete Handgriff ist.

## Qualitätsleitplanken

- **Kein Aussperren, kein Datenverlust:** Alles rund um Login, Sessions, Verschlüsselung
  und Key-Backup ist heilig. Der Uta-Random-Logout-Bug zeigt: Fehlerpfade dürfen NIE in
  einem stillen Logout enden. Änderungen daran immer mit Test: Login → Nachrichten →
  Logout → erneuter Login → alte verschlüsselte Nachrichten noch lesbar?
- **Nach dem Refactoring (M2) gilt:** keine Verhaltensänderung ohne Not – Refactoring
  heißt gleiche Funktion, bessere Struktur. Nach jedem Refactoring-Schritt App starten
  und Kernflows prüfen (Login, Raum öffnen, Nachricht senden, Voice-Channel beitreten).
- **Keine Secrets ins Repo:** Tokens, Recovery-Keys, Passwörter, Keystore-Dateien
  niemals committen (Signing-Keys liegen in `Documents\pyramid_keys_20260425.txt`).
- **Modularität (Bernd wichtig!):** Die Architektur muss aus austauschbaren Bausteinen
  bestehen – jedes Feature (Calls, Streaming, Push, Chat-Timeline, …) hinter einer klaren,
  schmalen Schnittstelle, sodass man einen alten Baustein durch einen neuen ersetzen kann,
  ohne den Rest anzufassen. Beim Refactoring (M2) ist das DAS Leitprinzip; bei jedem neuen
  Feature fragen: „Könnte man dieses Modul in einem Jahr komplett neu schreiben, ohne
  andere Module zu ändern?"
- **Abhängigkeiten:** neue Pakete nur mit gutem Grund, etabliert und gepflegt.
- **Umgebung beachten:** Auf dem Pi (SSH/tmux-Sessions) ist evtl. kein Flutter-Toolchain
  verfügbar. Dann trotzdem sauber arbeiten, aber jeden Schritt in PROGRESS.md als
  „UNGETESTET (Pi)" markieren – der nächste PC-Lauf holt `flutter analyze` + Praxistest nach.
- **Bernd fragen** nur bei echten Richtungsentscheidungen (UX-Geschmack, Priorität) –
  Fragen in PROGRESS.md unter „Fragen an Bernd" sammeln statt die Session zu blockieren.

## Nützliches Wissen

- Discord ist die UX-Referenz für Calls/Voice-Channels (Join/Leave, Nutzer-Lautstärke,
  Geräteauswahl, Noise Suppression, Streaming-Qualitätswahl).
- `CHANGES.md` ist ein automatisches Änderungslog (Hook) – nicht von Hand pflegen.
- Windows-Build ist der schnellste Testweg; Android-Release über das Release-Skript
  (siehe Commit d706ace), signiert – Play-Protect-Warnung siehe ROADMAP M6.