Changeset 0.28.0.1 (#173)

docs/ICD/notifications.md

@@ -0,0 +1,44 @@
+# Notifications
+
+Real-time notification infrastructure with WebSocket delivery and
+optional email transport.
+
+### CRUD
+
+```
+GET    /notifications                → paginated list
+GET    /notifications/unread-count   → { "count": 5 }
+PATCH  /notifications/:id/read       → mark one as read
+POST   /notifications/mark-all-read  → mark all as read
+DELETE /notifications/:id
+```
+
+Notification object:
+
+```json
+{
+  "id": "uuid",
+  "user_id": "uuid",
+  "type": "role.fallback|memory.extracted|system.announcement|...",
+  "title": "Role Fallback Triggered",
+  "body": "Primary model unavailable, using fallback",
+  "metadata": {},
+  "read": false,
+  "created_at": "..."
+}
+```
+
+### Preferences
+
+Users control per-type delivery:
+
+```
+GET    /notifications/preferences            → { "preferences": [...] }
+PUT    /notifications/preferences/:type      ← { "in_app": true, "email": false }
+DELETE /notifications/preferences/:type       → reset to default
+```
+
+Resolution: specific type pref → user wildcard `*` pref → system
+default (`in_app=true`, `email=false`).
+
+---