chore: snapshot notifications hardening and css/docs alignment

docs/index.md

@@ -1,6 +1,6 @@
 # Dokumentation
 
-Letzte Aktualisierung: 2026-03-18
+Letzte Aktualisierung: 2026-03-19
 
 Diese Dokumentation ist nach dem Diataxis-Modell in vier Quadranten gegliedert: Tutorials zum Lernen, How-to Guides zum Nachschlagen von Aufgaben, Explanation zum Verstehen und Reference zum Nachschlagen von Fakten.
 
@@ -101,4 +101,6 @@ Diese Dokumentation ist nach dem Diataxis-Modell in vier Quadranten gegliedert:
   - Alle CLI-Kommandos (`php bin/console`), Bootstrap-Helfer, Anleitung neue Kommandos.
 - `/docs/reference-module-manifest-contract.md`
   - Verbindlicher Runtime- und Manifest-Contract fuer Module (V1.1).
+- `/docs/reference-notifications-module.md`
+  - Verbindliche Referenz fuer Notifications (Events, Guardrails, Dedupe, Bell-Vertrag, Tests).
 - Agent-Workflow (Rollen, State-Machine, Contracts): siehe `/.agents/workflow.md`

docs/reference-frontend-css.md

@@ -1,6 +1,6 @@
 # Frontend CSS
 
-Letzte Aktualisierung: 2026-03-06
+Letzte Aktualisierung: 2026-03-19
 
 ## Ziel
 
@@ -76,3 +76,10 @@ Regel: Vendor-Overrides nur für Bibliotheks-Selektoren; projektspezifische UI-S
 3. Wird die Gruppe auf der Zielseite wirklich geladen (`style_groups`)?
 4. Gibt es ungewollte Seiteneffekte auf anderen Seiten?
 5. Sind bestehende Variablen/Konventionen eingehalten?
+
+## Module-CSS Token-Regel
+
+1. Modul-CSS nutzt primär Core-Tokens (`--app-*`) statt eigener Farbwerte.
+2. Modul-spezifische Variablen sind als Alias erlaubt, muessen aber auf Core-Tokens mappen.
+3. Keine Legacy-/Phantom-Tokens (`--app-text`, `--app-hover`, `--app-border-light`) neu einführen.
+4. Harte Hex-Fallbacks nur als Ausnahmefall, nicht als Standard.

docs/reference-notifications-module.md

@@ -0,0 +1,115 @@
+# Notifications Modul (V1)
+
+Letzte Aktualisierung: 2026-03-19
+
+## Ziel
+
+Referenz fuer das Modul `notifications`: Event-Registrierung, Erzeugungsregeln, Guardrails, Frontend-Vertrag und Testbarkeit.
+
+## Scope v1
+
+- In-App Notifications (Bell + Dropdown), kein E-Mail-Channel.
+- Core-5 Eventtypen:
+  - `user.created`
+  - `user.deleted`
+  - `user.activated`
+  - `user.deactivated`
+  - `user.assignment_changed`
+- Dedupe fuer diese Typen mit 30 Minuten Fenster.
+
+## Modul-Verkabelung
+
+Kanonische Quelle: `modules/notifications/module.php`
+
+- `event_listeners`
+  - mappt Eventtyp -> Listenerklasse + Methode `handle`.
+- `ui_slots`
+  - `topbar.right_item`: Bell-Template
+  - `layout.head_style`: Modul-CSS fuer Topbar + Dropdown
+  - `runtime.component`: Bell-JS (`initNotificationBell`)
+- `permissions`
+  - `notifications.view`
+- `authorization_policies`
+  - `NotificationsAuthorizationPolicy`
+- `layout_context_providers`
+  - liefert `notifications.nav.unread_count` in den Layout-Context
+- `session_providers`
+  - synchronisiert `module.notifications.unread_count` aus DB
+
+## Event -> Notification Fluss
+
+1. Ein User-Lifecycle-Workflow dispatcht ein Domain-Event (z. B. `user.activated`).
+2. Der in `module.php` registrierte Listener verarbeitet das Payload.
+3. Listener ruft `NotificationService` auf.
+4. `NotificationService` orchestriert Empfaenger/Fan-out und Dedupe-Metadaten.
+5. `NotificationRepository` persistiert in `user_notifications`.
+6. Bell-Endpunkte lesen tenant-scoped Daten und aktualisieren den Session-`unread_count`.
+
+## Datenvertrag Notification
+
+Persistierter Kernvertrag:
+
+- `type` (string)
+- `title` (string)
+- `body` (nullable string)
+- `link` (nullable string)
+- `data` (nullable JSON)
+
+Dedupe-Metadaten (intern):
+
+- `dedupe_fingerprint`
+- `dedupe_bucket`
+- `dedupe_until`
+
+## Guardrails (Server)
+
+- Alle Bell-Endpunkte erzwingen:
+  - Login
+  - Ability `notifications.view`
+- POST-Endpunkte (`mark-read`, `delete`) pruefen CSRF.
+- Tenant-Scope wird serverseitig aus `current_tenant` erzwungen.
+- SQL ausschliesslich im Repository (`NotificationRepository`), Service nur Orchestrierung.
+
+## Guardrails (Frontend)
+
+- Endpunkte werden mit App-Base-URL gebaut (kein harter Root-Pfad).
+- Fehlerpfade laufen ueber zentrale Telemetrie (`warn_once`).
+- A11y-Klickzeilen im Dropdown sind lokal gestylt, damit globale `[role="button"]` Regeln nicht durchschlagen.
+- Default-`details/summary`-Chevron wird pro Komponente ueber `data-summary-chevron="none"` deaktiviert.
+
+## Template/Partial Best Practice
+
+- Core-Partials immer ueber `templatePath('partials/...')` einbinden.
+- Keine fragilen relativen Tiefenpfade auf Core-Templates verwenden.
+- Modulinterne Templates bleiben lokal relativ zum Modul.
+
+## CSS Token Best Practice (Module)
+
+- Modul-CSS soll auf Core-Variablen aufsetzen (z. B. `--app-color`, `--app-muted-color`, `--app-dropdown-*`, `--app-action-danger-*`).
+- Modul-spezifische Aliase sind ok (`--app-notification-*`), solange sie auf Core-Tokens mappen.
+- Harte Hex-Fallbacks nur als Ausnahme; Standard ist tokenbasiert.
+
+## Tests
+
+### Unit
+
+- Listener-Tests fuer alle Core-5 Typen:
+  - Empfaengerregeln
+  - Actor-Exclusion
+  - ungultige/leere Payloads
+- Service-Tests fuer Dedupe (created vs suppressed)
+- Policy-Tests fuer `notifications.view`
+
+### Integration/Flow
+
+- End-to-End fuer create/delete/activate/deactivate/assignment-change.
+- Bell-Endpunkte mit Tenant-Scope und Permission-Pruefung.
+- Bulk-Flows dispatchen konsistent.
+
+### Manueller Smoke
+
+1. Zwei Admins im selben Tenant, einer als Actor.
+2. Actor fuehrt User-Aktion aus.
+3. Zweiter Admin sieht Bell-Badge + Listeneintrag.
+4. Wiederholung innerhalb 30 Minuten erzeugt kein Duplikat.
+