# DESIGN-0.20.0 — Notifications + @mention Routing + Multi-model **Status:** Complete (Phases 1–3 delivered 2026-03-01) **Depends on:** v0.19.2 (Projects complete), EventBus + WebSocket hub (v0.9.x), `channel_models` table (v0.16.0 schema) **Prerequisite for:** v0.23.0 (Multi-Participant Channels — notifications become the backbone for participant events) --- ## Overview v0.20.0 delivers two complementary features: 1. **Notifications** — Persistent, user-targeted notification infrastructure with real-time WebSocket push and optional email transport. This is the event backbone for all future collaboration features (multi-participant channels, workflow assignment queues, presence). 2. **@mention Routing + Multi-model** — Channels can host multiple AI models. Users @mention a model (or user, for future multi-participant) to direct a message. The completion handler fans out to the addressed model(s). This builds on the existing `channel_models` table and `ChannelModel` store methods that have been in the schema since v0.16.0 but were never surfaced in UI. --- ## Phasing | Phase | Scope | Migration | Est. Effort | |-------|-------|-----------|-------------| | **1** | Notifications core (in-app) | `007_v0200_notifications.sql` | Medium-large | | **2** | @mention parsing + multi-model routing | None (uses existing `channel_models`) | Medium | | **3** | Email transport + user notification preferences | `008_v0200_notification_prefs.sql` | Medium | Each phase is a merge-ready deliverable. Phase 1 is the critical path — 2 and 3 can be reordered or deferred if needed. --- ## Phase 1 — Notifications Core (in-app) ### Data Model ```sql -- Postgres: 007_v0200_notifications.sql CREATE TABLE IF NOT EXISTS notifications ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, type VARCHAR(50) NOT NULL, -- e.g. 'role.fallback', 'kb.processing', 'grant.changed', 'project.invite' title VARCHAR(255) NOT NULL, body TEXT DEFAULT '', resource_type VARCHAR(50), -- 'channel', 'knowledge_base', 'project', 'team', etc. resource_id UUID, -- nullable — links notification to a navigable entity is_read BOOLEAN DEFAULT false, created_at TIMESTAMPTZ DEFAULT NOW() ); CREATE INDEX idx_notifications_user_unread ON notifications(user_id, is_read, created_at DESC); CREATE INDEX idx_notifications_user_created ON notifications(user_id, created_at DESC); ``` ```sql -- SQLite: 006_v0200_notifications.sql CREATE TABLE IF NOT EXISTS notifications ( id TEXT PRIMARY KEY, user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE, type TEXT NOT NULL, title TEXT NOT NULL, body TEXT DEFAULT '', resource_type TEXT, resource_id TEXT, is_read INTEGER DEFAULT 0, created_at TEXT DEFAULT (datetime('now')) ); CREATE INDEX IF NOT EXISTS idx_notifications_user_unread ON notifications(user_id, is_read, created_at DESC); CREATE INDEX IF NOT EXISTS idx_notifications_user_created ON notifications(user_id, created_at DESC); ``` **Design notes:** - No `updated_at` — notifications are immutable once created (only `is_read` flips). - `type` is a free-form string, not an enum. New notification sources don't require migration. Convention: `domain.action` (e.g. `role.fallback`, `kb.ready`, `grant.added`, `project.invite`). - `resource_type` + `resource_id` enable click-to-navigate. Frontend maps these to routes (e.g. `resource_type=channel` → `selectChat(resource_id)`). - No FK on `resource_id` — the referenced entity may be deleted; notification persists as historical record. ### Store Interface ```go // server/store/interfaces.go — addition to Stores type NotificationStore interface { Create(ctx context.Context, n *models.Notification) error ListByUser(ctx context.Context, userID string, limit, offset int, unreadOnly bool) ([]models.Notification, int, error) // returns items + total count MarkRead(ctx context.Context, id, userID string) error MarkAllRead(ctx context.Context, userID string) error Delete(ctx context.Context, id, userID string) error UnreadCount(ctx context.Context, userID string) (int, error) } ``` Both Postgres and SQLite implementations follow the established pattern. `ListByUser` returns paginated results with a total count for the unread badge. The `userID` parameter on `MarkRead`/`Delete` prevents cross-user access. ### Model ```go // server/models/models_notification.go type Notification struct { ID string `json:"id" db:"id"` UserID string `json:"user_id" db:"user_id"` Type string `json:"type" db:"type"` Title string `json:"title" db:"title"` Body string `json:"body" db:"body"` ResourceType string `json:"resource_type,omitempty" db:"resource_type"` ResourceID string `json:"resource_id,omitempty" db:"resource_id"` IsRead bool `json:"is_read" db:"is_read"` CreatedAt time.Time `json:"created_at" db:"created_at"` } ``` ### API Endpoints ``` GET /api/v1/notifications — list (paginated, ?unread_only=true, ?limit=20&offset=0) GET /api/v1/notifications/unread-count — { "count": 5 } PATCH /api/v1/notifications/:id/read — mark single read POST /api/v1/notifications/mark-all-read — mark all read for user DELETE /api/v1/notifications/:id — delete single ``` All endpoints are user-scoped (auth middleware injects `user_id`). No admin override — notifications are personal. ### Notification Service Centralized creation + dispatch. All notification sources go through this service, never insert directly. ```go // server/notifications/service.go type Service struct { store store.NotificationStore hub *events.Hub } func (s *Service) Notify(ctx context.Context, n *models.Notification) error { // 1. Persist if err := s.store.Create(ctx, n); err != nil { return err } // 2. Real-time push via WebSocket (if user is online) s.hub.SendToUser(n.UserID, events.Event{ Label: "notification.new", Payload: events.MustJSON(n), Ts: time.Now().UnixMilli(), }) return nil } // NotifyMany fans out to multiple users (e.g. team-wide grant change). func (s *Service) NotifyMany(ctx context.Context, userIDs []string, template models.Notification) error { for _, uid := range userIDs { n := template n.ID = store.NewID() n.UserID = uid _ = s.Notify(ctx, &n) // best-effort; log errors, don't fail batch } return nil } ``` ### EventBus Route Table Addition ```go // server/events/types.go — add to routeTable "notification.new": DirToClient, // targeted via Hub.SendToUser, not room-based "notification.read": DirToClient, // badge sync across tabs ``` ### Initial Notification Sources Wire these into existing code paths. Each source creates a `Notification` via `Service.Notify()`: | Source | Type | Trigger Point | Title Template | |--------|------|---------------|----------------| | Role fallback | `role.fallback` | `capabilities/resolver.go` (already emits EventBus) | "Model fallback: {primary} → {fallback}" | | KB processing complete | `kb.ready` | `knowledge_bases.go` → after indexing pipeline | "Knowledge base '{name}' ready ({n} chunks)" | | KB processing error | `kb.error` | `knowledge_bases.go` → on embedding/chunking failure | "Knowledge base '{name}' indexing failed" | | Group membership changed | `grant.changed` | `groups.go` → AddMember / RemoveMember | "You were added to group '{name}'" | | Project invite | `project.invite` | Future (v0.23.0+) — stub the type now | — | **Implementation order:** `role.fallback` first (already emits an EventBus event — just subscribe in notification service), then `kb.ready`/`kb.error` (high user value), then `grant.changed`. ### Frontend — Notification UI **Bell icon** (header bar, right of model selector): ``` ┌─────────────────────────────────────────────────┐ │ ☰ Chat Switchboard [model ▾] 🔔③ 👤 Jeff │ └─────────────────────────────────────────────────┘ ``` - `🔔` with `.notification-badge` (red circle, count) when `unreadCount > 0`. - Badge shows count capped at `9+`. - On click: toggle notification dropdown. **Notification dropdown:** ``` ┌──────────────────────────────────────┐ │ Notifications Mark all ✓ │ ├──────────────────────────────────────┤ │ ● KB "Sales Docs" ready (3 chunks) │ │ 2 minutes ago │ ├──────────────────────────────────────┤ │ ○ Model fallback: gpt-4 → gpt-3.5 │ │ 1 hour ago │ ├──────────────────────────────────────┤ │ ○ Added to group "Engineering" │ │ Yesterday │ ├──────────────────────────────────────┤ │ View all → │ └──────────────────────────────────────┘ ``` - `●` = unread, `○` = read. Unread items have subtle background highlight. - Click item: mark read + navigate to `resource_type`/`resource_id` (open chat, open KB in admin, etc.). - "Mark all ✓" → `POST /notifications/mark-all-read` → clear badge. - "View all →" opens full notification list in side panel (registered with `PanelRegistry`, same pattern as Notes/Preview/Project). - Dropdown max-height: 400px, scrollable. Shows latest 10 items. - Click-outside / Escape to close. **File:** `src/js/notifications.js` (new module, ~300-400 lines) **WebSocket handler:** ```javascript Events.on('notification.new', (payload) => { App.notifications.unshift(payload); App.unreadNotificationCount++; renderNotificationBadge(); // Optional: toast for high-priority notification types if (['kb.error', 'role.fallback'].includes(payload.type)) { UI.toast(payload.title, 'warning'); } }); ``` **Startup:** `GET /notifications/unread-count` on app init → set badge. Lazy-load full list on first dropdown open. ### Files Changed (Phase 1) **New files:** - `server/notifications/service.go` — notification service - `server/handlers/notifications.go` — API handlers - `server/store/postgres/notification.go` — Postgres store - `server/store/sqlite/notification.go` — SQLite store - `server/models/models_notification.go` — model struct - `server/database/migrations/007_v0200_notifications.sql` — Postgres migration - `server/database/migrations/sqlite/006_v0200_notifications.sql` — SQLite migration - `src/js/notifications.js` — frontend notification UI **Modified files:** - `server/store/interfaces.go` — add `NotificationStore` to `Stores` - `server/events/types.go` — add `notification.*` routes - `server/main.go` (or `server/routes.go`) — wire notification handler + service - `server/handlers/knowledge_bases.go` — emit `kb.ready` / `kb.error` notifications - `server/handlers/groups.go` — emit `grant.changed` notifications - `server/capabilities/resolver.go` — emit `role.fallback` notification (subscribe to existing EventBus event) - `src/js/app.js` — init notification module, add bell to header - `src/js/events.js` — add `notification.*` to known labels (documentation only, wildcard already works) - `src/css/style.css` — notification badge, dropdown, panel styles - `index.html` — notification bell element in header - Integration tests — notification CRUD + WebSocket delivery ### Checklist (Phase 1) - [x] Migration: `notifications` table (Postgres + SQLite) - [x] Model: `Notification` struct - [x] Store: `NotificationStore` interface + both implementations - [x] Service: `notifications.Service` with `Notify()` / `NotifyMany()` - [x] Handlers: 5 notification endpoints - [x] EventBus: `notification.new` + `notification.read` in route table - [x] Wire: notification service into knowledge_bases, groups, capabilities/resolver - [x] Frontend: `notifications.js` module - [x] Frontend: bell icon + unread badge in header - [x] Frontend: notification dropdown (list, mark read, navigate) - [x] Frontend: notification panel (full list, registered with PanelRegistry) - [x] Frontend: WebSocket handler for real-time push - [x] Frontend: toast for high-priority notification types - [x] Tests: notification store CRUD (both dialects) - [x] Tests: notification handler integration tests - [x] Tests: WebSocket delivery (via existing hub test pattern) --- ## Phase 2 — @mention Parsing + Multi-model Routing ### Concept Today, each channel has one active model (set via model selector or persona). The `channel_models` table (schema 001) already supports multiple models per channel — it's just never been populated with more than one, and the completion handler ignores it. Phase 2 activates this table: 1. Users can **add models** to a channel (up to N, configurable, default 5). 2. Messages can contain **@mentions** that route to specific models. 3. The completion handler **fans out** to mentioned model(s), producing one assistant response per model. 4. Without @mention, the **default** channel model responds (backward compatible). ### @mention Syntax ``` @claude-3-opus What do you think about this approach? @gpt-4 Can you review the code above? Hey @claude-3-opus and @gpt-4, compare your approaches. ``` Mentions resolve against the `display_name` of `channel_models` entries for the current channel. Resolution is case-insensitive, whitespace-normalized, with longest-match-first to handle model names that are substrings of others. **Why display_name, not model_id?** Model IDs are composite strings like `anthropic/claude-3-opus-20240229` — terrible UX. `display_name` is user-settable when adding a model to the channel, defaulting to a short friendly name derived from the model catalog (e.g. "Claude 3 Opus", "GPT-4"). ### Mention Parser ```go // server/mentions/parser.go type Mention struct { Raw string // "@claude-3-opus" as written Name string // "claude-3-opus" (normalized, no @) Start int // byte offset in message content End int // byte offset end Resolved *models.ChannelModel // nil if unresolved } // Parse extracts @mentions from message content and resolves them // against the channel's model roster. func Parse(content string, roster []models.ChannelModel) []Mention ``` **Parser rules:** - `@` followed by one or more non-whitespace characters. - Greedy: `@claude-3-opus-20240229` matches the full string, not just `@claude`. - Resolution: case-insensitive match against `display_name` with hyphens/spaces normalized. - Unresolved mentions are left as-is in the message (no error, no routing). - Mentions at any position in the message (start, middle, end). **Frontend-side autocomplete:** When user types `@` in the chat input, show a dropdown of channel models (fetched from `GET /channels/:id/models`). Selecting inserts the `@display_name` token. This reuses the `[[wikilink` autocomplete pattern from CM6 (v0.17.3) adapted for the plain textarea/CM6 chat input. ### Completion Handler Changes Current flow (simplified): ``` user message → resolve model → one completion → one assistant message ``` New flow: ``` user message → parse @mentions → resolve target model(s) → fan out completions → N assistant messages ``` ```go // In completion.go, after persisting user message: // 1. Load channel model roster roster, _ := h.stores.GetModels(ctx, channel.ID) // 2. Parse mentions mentions := mentions.Parse(req.Content, roster) // 3. Determine target models var targets []models.ChannelModel if len(mentions) > 0 { // Deduplicate resolved mentions seen := map[string]bool{} for _, m := range mentions { if m.Resolved != nil && !seen[m.Resolved.ID] { targets = append(targets, *m.Resolved) seen[m.Resolved.ID] = true } } } if len(targets) == 0 { // No mentions or none resolved → use default channel model (current behavior) targets = []models.ChannelModel{defaultModelFromRequest(req, channel, roster)} } // 4. Fan out: one completion per target model for _, target := range targets { // Each gets its own assistant message with model attribution go h.completeForModel(ctx, c, req, channel, messages, target) } ``` **Sequential vs parallel:** Start with **sequential** fan-out (simpler error handling, predictable message ordering). Parallel is a future optimization — the bottleneck is provider latency, not local compute. **Streaming:** Each model's response streams independently. Frontend receives SSE events tagged with model info: ```json {"event": "delta", "model": "claude-3-opus", "model_display": "Claude 3 Opus", "content": "..."} ``` Frontend renders each model's response in a separate message bubble with a model attribution label. ### Multi-model Channel UI **"Add model" button** in the model selector area (chat header): ``` ┌──────────────────────────────────────────────────────┐ │ Channel: Project Discussion │ │ Models: [Claude 3 Opus ✕] [GPT-4 ✕] [+ Add model] │ └──────────────────────────────────────────────────────┘ ``` - Model pills show `display_name`, click `✕` to remove. - `[+ Add model]` opens a dropdown of available models (filtered by user's accessible provider configs), with a "Display name" input field. - Default model indicated with a subtle star/highlight (the one that responds without @mention). - Click a model pill to set it as default. **API endpoints:** ``` GET /api/v1/channels/:id/models — list channel models POST /api/v1/channels/:id/models — add model to channel DELETE /api/v1/channels/:id/models/:modelId — remove model PATCH /api/v1/channels/:id/models/:modelId — update display_name, set default, system_prompt ``` These are mostly wrappers around the existing `SetModel`/`GetModels` store methods, with additional CRUD. ### Message Attribution Assistant messages from multi-model channels get a visual attribution: ``` ┌─────────────────────────────────────────┐ │ Claude 3 Opus │ │ I think the recursive approach is... │ ├─────────────────────────────────────────┤ │ GPT-4 │ │ I'd suggest an iterative solution... │ └─────────────────────────────────────────┘ ``` The `model` field on `messages` already stores the model ID. Frontend renders a label above multi-model assistant messages using the `display_name` from the channel model roster. ### Files Changed (Phase 2) **New files:** - `server/mentions/parser.go` — @mention parser - `server/mentions/parser_test.go` — parser unit tests - `server/handlers/channel_models.go` — channel model CRUD endpoints **Modified files:** - `server/handlers/completion.go` — fan-out logic, mention parsing integration - `server/handlers/channels.go` — wire channel model routes - `server/store/interfaces.go` — extend `ChannelStore` with `DeleteModel`, `UpdateModel` (if not already present) - `server/store/postgres/channel.go` — additional model CRUD - `server/store/sqlite/channel.go` — same - `src/js/chat.js` — model pills UI, @mention autocomplete, multi-model message rendering - `src/js/api.js` — channel model API methods - `src/css/style.css` — model pill styling, attribution labels ### Checklist (Phase 2) - [x] Mention parser: `mentions.Parse()` with case-insensitive resolution - [x] Parser tests: edge cases (no mentions, unresolved, multiple, overlapping names) - [x] Channel model CRUD handlers (4 endpoints) - [x] Store: `DeleteModel`, `UpdateModel` for both dialects - [x] Completion handler: mention extraction → target resolution → fan-out - [x] SSE streaming: model attribution in delta events - [x] Frontend: model pills in chat header - [x] Frontend: add/remove model UI - [x] Frontend: @mention autocomplete in chat input - [x] Frontend: model attribution labels on assistant messages - [x] Frontend: multi-stream rendering (sequential responses, distinct bubbles) - [x] Integration tests: multi-model completion fan-out - [x] Integration tests: channel model CRUD - [x] Backward compat: channels with no `channel_models` rows work exactly as today --- ## Phase 3 — Email Transport + Notification Preferences ### User Notification Preferences ```sql -- Postgres: 008_v0200_notification_prefs.sql CREATE TABLE IF NOT EXISTS notification_preferences ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, type VARCHAR(50) NOT NULL, -- notification type or '*' for default in_app BOOLEAN DEFAULT true, email BOOLEAN DEFAULT false, UNIQUE(user_id, type) ); ``` ```sql -- SQLite: 007_v0200_notification_prefs.sql CREATE TABLE IF NOT EXISTS notification_preferences ( id TEXT PRIMARY KEY, user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE, type TEXT NOT NULL, in_app INTEGER DEFAULT 1, email INTEGER DEFAULT 0, UNIQUE(user_id, type) ); ``` **Resolution chain:** Specific type preference → user's `*` default → system default (in_app=true, email=false). ### SMTP Configuration Admin settings (stored in `platform_settings` JSONB, same pattern as existing admin config): ```json { "notifications": { "email_enabled": false, "smtp_host": "", "smtp_port": 587, "smtp_user": "", "smtp_password": "", // encrypted via vault "smtp_from": "noreply@chat.example.com", "smtp_tls": true, "instance_name": "Chat Switchboard", "digest_enabled": false, "digest_interval": "daily" // "hourly" | "daily" | "weekly" } } ``` **Implementation:** `server/notifications/email.go` — wraps `net/smtp` with TLS support. Template rendering via Go `html/template` (no external dependency). Two templates per notification type: HTML + plaintext fallback. ### Email Service ```go // server/notifications/email.go type EmailTransport struct { config SMTPConfig vault *crypto.KeyResolver // decrypt SMTP password } func (t *EmailTransport) Send(ctx context.Context, to, subject, htmlBody, textBody string) error ``` ### Notification Service Updates The `Service.Notify()` method gains a preference check: ```go func (s *Service) Notify(ctx context.Context, n *models.Notification) error { prefs := s.resolvePrefs(ctx, n.UserID, n.Type) if prefs.InApp { s.store.Create(ctx, n) s.hub.SendToUser(n.UserID, ...) } if prefs.Email && s.email != nil { user, _ := s.stores.GetUser(ctx, n.UserID) if user.Email != "" { s.email.Send(ctx, user.Email, n.Title, renderHTML(n), renderText(n)) } } return nil } ``` ### Digest Mode Low-priority notifications (e.g. `grant.changed`) can batch into a periodic email digest: - Background goroutine checks on interval (hourly/daily). - Queries `notifications WHERE is_read = false AND created_at > last_digest_at`. - Groups by user, renders a single digest email per user. - Marks digested notifications with a `digested_at` timestamp (add column in this migration). **Deferred if complexity is too high for v0.20.0.** The core value is in-app + individual email. Digest is nice-to-have. ### User Preferences UI Settings → Notifications: ``` ┌────────────────────────────────────────────────┐ │ Notification Preferences │ ├────────────────────────────────────────────────┤ │ Type In-App Email │ │ ───────────────────── ─────── ───── │ │ Model fallback [✓] [ ] │ │ KB processing [✓] [✓] │ │ Group membership [✓] [ ] │ │ Default (all others) [✓] [ ] │ └────────────────────────────────────────────────┘ ``` ### Admin Settings UI Admin panel → System → Notifications: - Enable/disable email transport globally. - SMTP configuration form (host, port, user, password, from address, TLS toggle). - Test email button (sends to current admin's email). - Digest toggle + interval selector. ### Files Changed (Phase 3) **New files:** - `server/notifications/email.go` — SMTP transport - `server/notifications/templates.go` — HTML/text email templates - `server/notifications/digest.go` — digest aggregation (if not deferred) - `server/store/postgres/notification_prefs.go` — preference store - `server/store/sqlite/notification_prefs.go` — same - `server/database/migrations/008_v0200_notification_prefs.sql` - `server/database/migrations/sqlite/007_v0200_notification_prefs.sql` **Modified files:** - `server/notifications/service.go` — preference resolution, email dispatch - `server/store/interfaces.go` — `NotificationPreferenceStore` - `server/handlers/notifications.go` — preference CRUD endpoints - `server/handlers/admin.go` — SMTP config in admin settings - `src/js/admin-handlers.js` — notification admin UI - `src/js/app.js` — user notification preferences in settings modal ### Checklist (Phase 3) - [x] Migration: `notification_preferences` table (both dialects) - [x] Store: `NotificationPreferenceStore` interface + implementations - [x] Handlers: preference CRUD endpoints (GET/PUT per type) - [x] Notification service: preference resolution chain - [x] Email transport: SMTP with TLS, template rendering - [x] Email templates: HTML + plaintext for each notification type - [x] Admin UI: SMTP config + test email button - [x] User UI: notification preferences in Settings - [ ] Optional: digest mode (background goroutine + batched email) — deferred - [x] Tests: preference resolution chain - [x] Tests: email transport (mock SMTP) --- ## Cross-cutting Concerns ### Retention / Cleanup Notifications accumulate. Add a cleanup policy: - Default: retain 90 days, configurable via admin settings (`notifications.retention_days`). - Cleanup: background goroutine (daily) deletes `WHERE created_at < NOW() - retention`. - Same pattern as compaction scanner — register in `server/main.go` startup. ### Notification Count Performance The unread badge polls on app init, then stays current via WebSocket. No periodic polling. Badge syncs across tabs via `notification.read` event (one tab marks read → other tabs update badge). ### SQLite Considerations - No `LISTEN/NOTIFY` — WebSocket push uses `Hub.SendToUser()` directly (already in-process, no PG dependency). - `datetime('now')` for `created_at` (standard SQLite pattern). - `INTEGER` for booleans (standard). ### Mobile - Notification bell fits in mobile header (replace one of the existing icons or use hamburger menu). - Notification dropdown becomes full-screen overlay on mobile (same pattern as other dropdowns). - @mention autocomplete: same touch-friendly dropdown pattern as wikilink autocomplete. ### Security - Notifications are user-scoped. No cross-user access via API (every query includes `user_id` from auth context). - SMTP password encrypted at rest via vault (same pattern as API keys in v0.9.4). - Email transport validates `smtp_host` against SSRF allowlist (same pattern as `url_fetch`). - @mention parsing sanitized — no injection via display names (names are alphanumeric + hyphens only, validated on `channel_models` write). --- ## Dependency Map ``` Phase 1: Notifications Core ├── notifications table (migration) ├── NotificationStore (postgres + sqlite) ├── Notification Service (create + dispatch) ├── EventBus route (notification.new) ├── API endpoints (5) ├── Frontend: bell + dropdown + panel └── Wire: KB, groups, resolver → service Phase 2: @mention + Multi-model ← can start in parallel with Phase 1 ├── mentions/parser.go ├── channel_models CRUD endpoints ← table already exists ├── completion handler fan-out ├── Frontend: model pills + autocomplete └── Frontend: multi-stream rendering Phase 3: Email + Preferences ← depends on Phase 1 ├── notification_preferences table (migration) ├── SMTP transport ├── Email templates ├── Preference resolution in Service └── Admin + User settings UI ``` Phases 1 and 2 have no code-level dependency on each other — they touch different files and can be developed in parallel or in either order. Phase 3 strictly depends on Phase 1 (extends the notification service). --- ## Version Bump - `VERSION`: `0.19.2` → `0.20.0` after Phase 2 merge (or after Phase 1 if shipping incrementally as `0.20.0-rc1`). - Changelog entry after each phase merge. - No breaking API changes — all additions. --- ## What This Unblocks - **v0.23.0 Multi-Participant Channels:** Notifications become the backbone for participant join/leave, new message alerts, and assignment queue events. - **v0.25.0 Workflow Engine:** Stage transition notifications, assignment notifications, completion webhooks all route through the notification service. - **v0.22.0 Smart Routing:** Multi-model channels demonstrate the fan-out pattern that routing policies will generalize.