# PRD: Mosaic Stack Dashboard & Platform Implementation

## Metadata

- Owner: Jason Woltje
- Date: 2026-02-22
- Status: in-progress
- Best-Guess Mode: true

## Problem Statement

The Mosaic Stack web UI has a basic navigation and simple widget-based dashboard that doesn't match the production-ready design vision. The reference design (dashboard.html) defines a comprehensive command center UI with sidebar navigation, topbar, terminal panel, and multiple page layouts. The current implementation uses mismatched design tokens (raw Tailwind colors vs CSS variables), has no collapsible sidebar, no global terminal, and lacks the polished design system from the reference.

## Objectives

1. Implement the dashboard.html reference design as the production UI foundation
2. Establish a consistent CSS design token system that supports multiple themes
3. Build a responsive, accessible app shell with collapsible sidebar and full-width header
4. Create a theme system supporting installable theme packages
5. Build all dashboard pages (Dashboard, Projects, Workspace, Kanban, Files, Logs, Settings, Profile)
6. Implement real backend integration (no mock data)
7. Support multi-tenant configuration with RBAC
8. Implement federation (master-master and master-slave)
9. Build global terminal, project chat, and master chat session
10. Configure telemetry with opt-out support

## Completed Work

### MS15-DashboardShell (v0.0.15) — Complete

Design system + app shell + dashboard page. PRs #451-454.

- CSS design token system (colors, fonts, spacing, radii)
- App shell layout: collapsible sidebar + full-width header + main content
- Sidebar navigation with groups, icons, badges, active states, collapse/expand
- Responsive layout with hamburger at small breakpoints
- Light/dark theme matching reference design
- Mosaic logo spinner as global loading indicator
- Shared component updates in packages/ui
- Dashboard page: metrics strip, orchestrator sessions, quick actions, activity feed, token budget
- Grain overlay texture

### Go-Live MVP (v0.0.16) — Complete

Dashboard polish, task ingestion pipeline, agent cycle visibility, deploy + smoke test. PRs #458, #460, #462, #464.

- Fixed broken test suites and removed legacy unused widgets
- Visual + theme polish across all components
- Dashboard summary API endpoint (aggregated task counts, project counts, activity, jobs)
- Dashboard widgets wired to real API data (ActivityFeed, DashboardMetrics, OrchestratorSessions)
- WebSocket emits for job status/progress/step events
- Dashboard auto-refresh with polling + progress bars + step status indicators
- Deployed to mosaic.woltje.com, auth working via Authentik
- Release tag v0.0.16

### MS16+MS17-PagesDataIntegration (v0.0.17) — Complete

All pages built + wired to real API data. PRs #470-484 (15 PRs). Issues #466-469.

- Custom 404 pages (global + authenticated route groups)
- Settings root page with 4 category cards
- Tasks, Calendar, Knowledge pages wired to real API (238+ lines mock data removed)
- Projects list page with create/delete dialogs
- Project Workspace page with tabbed view (Tasks, Agent Sessions, Settings)
- Kanban board with drag-and-drop (@hello-pangea/dnd), 5 status columns, optimistic updates
- File Manager page with list/grid views, search, create/delete
- Logs & Telemetry page with auto-refresh, expandable rows, filters
- Profile page with user info and preferences
- All 5125 tests passing, CI pipeline #585 green
- Deployed and smoke-tested at mosaic.woltje.com

### MS18-ThemeWidgets (v0.0.18) — Complete

Theme package system, widget registry, WYSIWYG editor, Kanban filtering. PRs #493-505. Issues #487-491.

- 5 built-in themes (Dark, Light, Nord, Dracula, Solarized) as TypeScript theme packages
- ThemeProvider with dynamic CSS variable application and instant switching
- Theme selection UI in Settings with live preview swatches
- Widget definition registry with configurable sizing and schemas
- WidgetGrid dashboard with drag-and-drop layout (react-grid-layout)
- Widget picker drawer for adding widgets from registry
- Per-widget configuration dialog driven by configSchema
- Layout save/load/rename/delete via UserLayout API
- Tiptap WYSIWYG editor for knowledge entries with toolbar
- Markdown round-trip (import/export)
- Kanban board filtering by project, assignee, priority, search with URL persistence
- 1,195 web tests, 3,243 API tests passing

### MS19-ChatTerminal (v0.0.19) — Complete

Real terminal with PTY backend, chat streaming, orchestrator integration. PRs #515-522. Issues #508-512.

- NestJS WebSocket gateway (/terminal namespace) with node-pty for real shell sessions
- Terminal session persistence in PostgreSQL (Prisma model: TerminalSession)
- xterm.js integration with FitAddon, WebLinksAddon, CSS variable theme support
- Multi-session terminal tabs: create/close/rename, tab switching, session recovery
- SSE chat streaming with token-by-token rendering, abort/cancel support
- Master chat polish: model selector dropdown, temperature/maxTokens config, ChatEmptyState
- Orchestrator command system: /status, /agents, /jobs, /pause, /resume, /help
- Agent output terminal: SSE streaming from orchestrator, lifecycle indicators, read-only view
- Command autocomplete with keyboard navigation in chat input
- 328 MS19-specific tests (268 web + 60 API), 4744 total passing
- Deployed and smoke-tested at mosaic.woltje.com (CI #635 green)

### Bugfix: API Global Prefix (post-MS18) — Complete

PR #507. Fixed systemic 404 on all data endpoints.

- Added `setGlobalPrefix("api")` to NestJS with exclusions for /health and /auth/\*
- Normalized 6 federation controllers to remove redundant api/ prefix
- Fixed rollup CVE (GHSA-mw96-cpmx-2vgc) via pnpm override

## Scope

### In Scope (MS16+MS17 — Pages & Data Integration)

This is the active mission scope. MS16 (Pages) and MS17 (Backend Integration) are combined because the backend API modules already exist — the work is primarily frontend page creation and API wiring.

1. Projects list page with CRUD (wire to existing `/api/projects`)
2. Project workspace/detail page (wire to `/api/projects/:id`, `/api/tasks`, `/api/runner-jobs`)
3. Kanban board page with status-based columns (wire to existing `/api/tasks`)
4. File Manager page with tree/list view and CRUD (wire to existing `/api/knowledge`)
5. Logs & Telemetry page with log viewer and filtering (wire to `/api/runner-jobs`, job steps, events)
6. Settings root/index page linking to existing subpages
7. Custom 404 page for unknown routes
8. Wire `/tasks` page to real API data (currently mock)
9. Wire `/calendar` page to real API data (currently mock)
10. Wire `/knowledge` pages to real API data (currently mock)

### In Scope (Future Milestones — Documented for Planning)

11. Theme system with installable theme packages (MS18)
12. Widget system with installable widget packages, customizable sizes (MS18)
13. Global terminal: project/orchestrator level, smart (MS19)
14. Project-level orchestrator chat (MS19)
15. Master chat session: collapsible sidebar/slideout, always available (MS19)
16. Site stabilization: workspace context propagation for mutations (MS20)
17. Site stabilization: personalities API + UI (MS20)
18. Site stabilization: user preferences API endpoint (MS20)
19. Site stabilization: orchestrator 502 and WebSocket connectivity (MS20)
20. Site stabilization: credential management UI (MS20)
21. Site stabilization: terminal page route (MS20)
22. Site stabilization: favicon, dark mode dropdown fix (MS20)
23. Settings page for ALL environment variables, dynamically configurable via webUI (MS21)
24. Multi-tenant configuration with admin user management (MS21)
25. Team management with shared data spaces and chat rooms (MS21)
26. RBAC for file access, resources, models (MS21)
27. Federation: master-master and master-slave with key exchange (MS22)
28. Federation testing: 3 instances on Portainer (woltje.com domain) (MS22)
29. Agent task mapping configuration: system-level defaults, user-level overrides (MS23)
30. Telemetry: opt-out, customizable endpoint, sanitized data (MS23)
31. File manager with WYSIWYG editing: system/user/project levels (MS18)
32. User-level and project-level Kanban with filtering (MS18)
33. Break-glass authentication user (MS20)
34. Playwright E2E tests for all pages (MS23)
35. API documentation via Swagger (MS23)
36. Backend endpoints for all dashboard data (MS17 — already complete for existing modules)
37. Profile page linked from user card (MS16)

### Out of Scope

1. Mobile native app
2. Third-party marketplace for themes/widgets (initial implementation is local package management only)
3. Mobile native app deployment targets
4. Calendar system redesign (existing calendar implementation is retained)

## User/Stakeholder Requirements

1. The `jarvis` user must be able to log into mosaic.woltje.com via Authentik as administrator with access to all pages
2. A standard `jarvis-user` must operate at a lower permission level
3. A break-glass user must have access without Authentik authentication
4. All pages must be navigable without errors (no 404s from sidebar links)
5. Light and dark themes must work across all pages and components
6. Sidebar must be collapsible with open/close button; hidden by default at small breakpoints
7. Hamburger button visible at lower breakpoints for sidebar control
8. The Mosaic Stack logo icon must be the site-wide loading spinner
9. No mock data — all data pulled from backend APIs

## Functional Requirements

### FR-001: Design Token System

- CSS custom properties for all colors, spacing, typography, radii
- Dark theme as default (`:root`), light theme via `[data-theme="light"]`
- Fonts: Outfit (body), Fira Code (monospace)
- All components must use design tokens, never hardcoded colors
- **Status: COMPLETE (MS15)**

### FR-002: App Shell Layout

- CSS Grid: sidebar column + header row + main content
- Full-width header spanning above sidebar and content
- ASSUMPTION: Header spans full width including above sidebar area. The logo is in the header, not the sidebar. Rationale: User explicitly stated "The logo will NOT be part of the sidebar."
- **Status: COMPLETE (MS15)**

### FR-003: Sidebar Navigation

- Nav groups: Overview (Dashboard), Workspace (Projects, Project Workspace, Kanban, File Manager), Operations (Logs & Telemetry, Terminal), System (Settings)
- Collapsible: icon-only mode when collapsed
- Active state indicator (left border accent)
- User card in footer with avatar, name, role, online status
- ASSUMPTION: Sidebar footer user card navigates to Profile page. Rationale: Matches reference design behavior.
- **Status: COMPLETE (MS15+MS16) — Profile page added in PR #482.**

### FR-004: Header/Topbar

- Logo + brand wordmark (left)
- Search bar with keyboard shortcut hint
- System status indicator
- Terminal toggle button
- Notification bell with badge
- Theme toggle (sun/moon icon)
- User avatar button with dropdown (Profile, Account Settings, Sign Out)
- **Status: COMPLETE (MS15)**

### FR-005: Responsive Design

- Breakpoints: sm (640px), md (768px), lg (1024px), xl (1280px)
- Below md: sidebar hidden, hamburger button in header
- md-lg: sidebar can be toggled
- lg+: sidebar visible by default
- **Status: COMPLETE (MS15)**

### FR-006: Dashboard Page

- 6-cell metrics strip with colored top borders and trend indicators
- Active Orchestrator Sessions card with agent nodes
- Quick Actions 2x2 grid
- Activity Feed sidebar card
- Token Budget sidebar card with progress bars
- Wired to real API via `/api/dashboard/summary`
- **Status: COMPLETE (Go-Live MVP)**

### FR-007: Loading Spinner

- Mosaic logo icon (4 corner squares + center circle) with CSS rotation animation
- Used as global loading indicator across all pages
- Available as a shared component
- **Status: COMPLETE (MS15)**

### FR-008: Projects Page (MS16)

- Projects list view with card or table layout
- Project creation dialog/form
- Project detail view (name, description, status, created/updated timestamps)
- Wire to existing `/api/projects` (full CRUD already implemented)
- Navigate from sidebar → /projects
- **Status: COMPLETE (MS16) — PR #477. Card layout, create/delete dialogs, status badges.**

### FR-009: Project Workspace Page (MS16)

- Single-project view showing tasks, agent sessions, and project settings
- Task list for selected project
- Agent session history and status
- Wire to `/api/projects/:id`, `/api/tasks`, `/api/runner-jobs`
- Navigate from sidebar → /workspace (with project context)
- **Status: COMPLETE (MS16) — PR #479. Tabbed view (Tasks, Agent Sessions, Settings), project selector mode.**

### FR-010: Kanban Board Page (MS16)

- Drag-and-drop board with columns mapped to task status values
- Task cards showing title, assignee, priority, status
- Column headers with task counts
- Wire to existing `/api/tasks` (status field drives columns)
- Navigate from sidebar → /kanban
- **Status: COMPLETE (MS16) — PR #478. 5 columns (NOT_STARTED→ARCHIVED), @hello-pangea/dnd, optimistic updates.**

### FR-011: File Manager Page (MS16)

- Tree or list view of knowledge entries
- CRUD operations (create, read, update, delete)
- Search functionality
- Wire to existing `/api/knowledge` (full CRUD + search already implemented)
- Navigate from sidebar → /files
- **Status: COMPLETE (MS16) — PR #481. List+grid views, search, create/delete dialogs.**

### FR-012: Logs & Telemetry Page (MS16)

- Log viewer with timestamp, level, source, message columns
- Filtering by level, source, date range
- Auto-refresh for live logs
- Wire to existing runner-jobs, job steps, and events APIs
- Navigate from sidebar → /logs
- **Status: COMPLETE (MS16) — PR #480. Auto-refresh (5s polling), expandable rows, filters.**

### FR-013: Settings Root Page (MS16)

- Landing/index page for settings
- Category cards linking to existing subpages: Credentials, Domains, Personalities, Workspaces
- Navigate from sidebar → /settings (currently 404; subpages exist)
- **Status: COMPLETE (MS16) — PR #471. 4 category cards with icons and hover states.**

### FR-014: Custom 404 Page (MS16)

- Branded 404 page matching design system
- Helpful message and navigation link back to dashboard
- Applied to all unmatched routes within authenticated layout
- **Status: COMPLETE (MS16) — PR #472. Global + authenticated route-group 404 pages.**

### FR-015: Mock Data Elimination (MS16+MS17)

- `/tasks` page: replace mock data with `/api/tasks` calls
- `/calendar` page: replace mock data with `/api/events` calls
- `/knowledge` pages: replace mock data with `/api/knowledge` calls
- All pages must render real data from backend APIs
- **Status: COMPLETE (MS16+MS17) — PRs #473-#476. 238+ lines of mock data removed.**

### FR-016: Theme System (MS18) — COMPLETE

- 5 built-in themes (Dark, Light, Nord, Dracula, Solarized) as TypeScript theme packages
- ThemeProvider loads themes dynamically, applies CSS variables, instant switching
- Theme selection UI in Settings with live preview swatches
- UserPreference.theme persists selection across sessions
- **Status: COMPLETE (MS18) — PRs #493-495**

### FR-017: Terminal Panel (MS19) — COMPLETE

- Bottom drawer panel, toggleable from header and sidebar
- Real xterm.js terminal with PTY backend via WebSocket
- Multiple tabs: shell sessions, orchestrator agent output, build logs
- Terminal session persistence (create/close/rename tabs)
- Smart terminal operating at project/orchestrator level
- ASSUMPTION: Terminal backend uses node-pty for PTY management, communicating via WebSocket namespace (/terminal). Rationale: node-pty is the standard for Node.js terminal emulation, used by VS Code.
- ASSUMPTION: Terminal sessions are workspace-scoped and stored in PostgreSQL for recovery. Rationale: Consistent with existing workspace isolation pattern.
- **Status: COMPLETE (MS19) — PRs #515 (gateway), #517 (persistence), #518 (xterm.js), #520 (tabs), #522 (agent tabs). 60 API + 176 web tests.**

### FR-018: Chat Streaming & Master Chat (MS19) — COMPLETE

- Complete SSE streaming for token-by-token chat rendering
- Master chat sidebar (ChatOverlay) polish: model selector, conversation search, keyboard shortcuts
- Chat persistence via Ideas API (already implemented)
- ASSUMPTION: Chat streaming uses existing SSE infrastructure in LLM controller. Frontend needs streamChatMessage() completion. Rationale: Backend SSE is already working, only frontend wiring is missing.
- **Status: COMPLETE (MS19) — PRs #516 (streaming), #519 (polish). Model selector, temperature/maxTokens config, ChatEmptyState, Cmd+N/L shortcuts. 78 web tests.**

### FR-019: Project-Level Orchestrator Chat (MS19) — COMPLETE

- Chat context scoped to active project
- Can trigger orchestrator actions: spawn agent, check status, view jobs
- Command prefix system (/spawn, /status, /jobs) parsed in chat
- Agent output viewable in terminal tabs
- ASSUMPTION: Orchestrator commands route through existing web proxy (/api/orchestrator/\*) to orchestrator service. Rationale: Proxy routes already exist and handle auth.
- **Status: COMPLETE (MS19) — PRs #521 (commands), #522 (agent terminal). /status, /agents, /jobs, /pause, /resume, /help commands. Agent output streaming via SSE. 113 web tests.**

### FR-020: Site Stabilization & Feature Gaps (MS20) — IN PROGRESS

Runtime bugs and feature gaps discovered during live testing of mosaic.woltje.com.

**Workspace Context Propagation:**

- Domains page: "Workspace ID is required" when creating domains
- Projects page: "Workspace ID is required" when creating projects
- Credentials page: unable to add credentials (button disabled, feature stub)
- ASSUMPTION: The `useWorkspaceId()` hook + auto-detect in `apiRequest` from PR #532 handles reads, but mutation endpoints on some pages don't pass workspace ID correctly. Rationale: GET requests work after PR #532 but POST/mutation requests still fail on domains and projects pages.

**Missing API Endpoints:**

- `/api/personalities` — no controller/service exists; frontend expects GET/POST/PATCH/DELETE
- `/users/me/preferences` — listed in PRD API table but returns 404; frontend profile page depends on it
- ASSUMPTION: Personalities API follows existing NestJS module patterns (controller + service + DTO + Prisma model). Rationale: Consistent with all other API modules in the codebase.
- ASSUMPTION: User preferences endpoint is part of the existing users module but route is not registered. Rationale: PRD lists it as an existing endpoint.

**Orchestrator Connectivity:**

- All orchestrator-proxied endpoints return HTTP 502
- Orchestrator WebSocket connection fails ("Reconnecting to server...")
- Dashboard widgets: Agent Status, Task Progress, Orchestrator Events all error
- ASSUMPTION: The orchestrator service container runs but the Next.js API proxy cannot reach it. Root cause is likely environment variable or network configuration in Docker Swarm. Rationale: The orchestrator container exists in the compose file and has Traefik labels.

**UI/UX Issues:**

- Dark mode theming on Formality Level dropdown in Personalities page incorrect
- favicon.ico missing (404)
- Terminal sidebar link uses `#terminal` anchor instead of page route
- `useWorkspaceId` warning in console: no workspace ID in localStorage on fresh sessions
- ASSUMPTION: Terminal should have a dedicated page route `/terminal` that renders the terminal panel full-screen. Rationale: The sidebar has a Terminal link in the Operations section alongside Logs, implying it should be a navigable page.

**Credential Management:**

- "Add Credential" button is `disabled` in code — feature was stubbed as "coming soon"
- Need to implement credential creation UI and wire to existing `/api/credentials` CRUD endpoints
- ASSUMPTION: Credential CRUD frontend can use the existing `/api/credentials` API which was built during M7-CredentialSecurity. Rationale: Backend endpoints exist per audit.

### FR-021: Settings Configuration (Future — MS21)

- All environment variables configurable via UI
- Minimal launch env vars, rest configurable dynamically
- Settings stored in DB with RLS
- Theme selection, widget management, federation config, telemetry config

## Non-Functional Requirements

1. Security: All API endpoints require authentication. RBAC enforced. No PII in telemetry. Secrets never hardcoded.
2. Performance: Dashboard loads in <2s. No layout shift during theme toggle. Sidebar toggle is instant (<100ms animation).
3. Reliability: Break-glass auth ensures access when Authentik is down.
4. Observability: Telemetry with opt-out support. Wide-event logging. Customizable telemetry endpoint.

## Acceptance Criteria

### MS15-DashboardShell — COMPLETE

1. ~~Design tokens from dashboard.html are implemented in globals.css~~ DONE
2. ~~App shell shows full-width header with logo, collapsible sidebar, main content area~~ DONE
3. ~~Sidebar has all nav groups with icons, collapses to icon-only mode~~ DONE
4. ~~Hamburger button appears at mobile breakpoints, sidebar hidden by default~~ DONE
5. ~~Light/dark theme toggle works across all components~~ DONE
6. ~~Mosaic logo spinner is used as site-wide loading indicator~~ DONE
7. ~~Dashboard page shows metrics strip, orchestrator sessions, quick actions, activity feed, token budget~~ DONE
8. ~~All shared components in packages/ui use design tokens (no hardcoded colors)~~ DONE
9. ~~Lint, typecheck, and existing tests pass~~ DONE
10. ~~Grain overlay texture from reference is applied~~ DONE

### Go-Live MVP (v0.0.16) — COMPLETE

11. ~~Dashboard widgets wired to real API data~~ DONE
12. ~~WebSocket emits for agent job lifecycle~~ DONE
13. ~~Deployed to mosaic.woltje.com with auth working~~ DONE

### MS16+MS17 — Pages & Data Integration — COMPLETE

14. ~~All sidebar links navigate to functional pages (no 404s)~~ DONE
15. ~~Projects page: list, create, view project details~~ DONE
16. ~~Workspace page: view single project with tasks and agent sessions~~ DONE
17. ~~Kanban page: drag-and-drop board with task status columns~~ DONE
18. ~~File Manager page: tree/list view with CRUD operations~~ DONE
19. ~~Logs page: log viewer with filtering and auto-refresh~~ DONE
20. ~~Settings root page: category index linking to subpages~~ DONE
21. ~~Custom 404 page for unknown routes~~ DONE
22. ~~`/tasks` page uses real API data (no mock)~~ DONE
23. ~~`/calendar` page uses real API data (no mock)~~ DONE
24. ~~`/knowledge` pages use real API data (no mock)~~ DONE
25. ~~All new pages support light/dark theme~~ DONE
26. ~~All new pages are responsive (sm/md/lg/xl breakpoints)~~ DONE
27. ~~Lint, typecheck, and tests pass~~ DONE
28. ~~Deployed and smoke-tested at mosaic.woltje.com~~ DONE

### MS18 — Theme & Widget System — COMPLETE

29. ~~5+ themes with live preview and instant switching~~ DONE
30. ~~Theme selection UI in Settings with swatches~~ DONE
31. ~~UserPreference.theme persists across sessions~~ DONE
32. ~~WidgetGrid dashboard with drag/resize/add/remove~~ DONE
33. ~~Widget picker UI from registry~~ DONE
34. ~~Per-widget configuration dialog~~ DONE
35. ~~Layout save/load/rename/delete via API~~ DONE
36. ~~Tiptap WYSIWYG editor for knowledge entries~~ DONE
37. ~~Markdown round-trip (import/export)~~ DONE
38. ~~Kanban filtering by project, assignee, priority, search~~ DONE
39. ~~All features support all themes~~ DONE
40. ~~Lint, typecheck, tests pass~~ DONE

### MS19 — Chat & Terminal — COMPLETE

41. ~~Terminal panel has real xterm.js with PTY backend~~ DONE — PR #518
42. ~~Terminal supports multiple named sessions (tabs)~~ DONE — PR #520
43. ~~Terminal sessions persist and recover on reconnect~~ DONE — PR #517
44. ~~Chat streaming renders tokens in real-time (SSE)~~ DONE — PR #516
45. ~~Master chat sidebar accessible from any page (Cmd+Shift+J)~~ DONE — PR #519
46. ~~Master chat supports model selection and conversation management~~ DONE — PR #519
47. ~~Project-level chat can trigger orchestrator actions~~ DONE — PR #521
48. ~~Agent output viewable in terminal tabs~~ DONE — PR #522
49. ~~All features support all themes~~ DONE — CSS variables throughout
50. ~~Lint, typecheck, tests pass~~ DONE — 1441 web + 3303 API = 4744 total
51. ~~Deployed and smoke-tested~~ DONE — CI #635 green, web deployed to mosaic.woltje.com

### Full Project (All Milestones)

52. jarvis user logs in via Authentik, has admin access to all pages
53. jarvis-user has standard access at lower permission level
54. Break-glass user has access without Authentik
55. Three Mosaic Stack instances on Portainer with federation testing
56. Playwright tests confirm all pages, functions, theming work
57. No errors during site navigation
58. API documented via Swagger with proper auth gating
59. Telemetry working locally with wide-event logging
60. Mosaic Telemetry properly reporting to telemetry endpoint

## Constraints and Dependencies

1. Next.js 16 with App Router — all pages use server/client component patterns
2. Tailwind CSS 3.4 — design tokens must integrate with Tailwind's utility class system
3. BetterAuth for authentication — must maintain existing auth flow
4. Authentik as IdP at auth.diversecanvas.com — must remain operational
5. PostgreSQL 17 with Prisma — all settings stored in DB
6. Portainer for deployment — 3 instances needed for federation testing
7. packages/ui is shared across apps — changes affect all consumers
8. Backend API modules already exist for all page data needs — no new API endpoints required for MS16+MS17 scope

## Risks and Open Questions

1. **Risk**: Pages need to match the design system established in MS15. Inconsistency would degrade UX. Mitigation: Use existing design tokens and shared components exclusively. **RESOLVED** — All MS16+MS17 pages use design tokens consistently.
2. **Risk**: Kanban drag-and-drop adds complexity and potential for state bugs. Mitigation: Use a proven DnD library. **RESOLVED** — @hello-pangea/dnd selected (maintained fork of react-beautiful-dnd, better TS support). Optimistic updates with rollback on failure.
3. **Risk**: Mock data elimination may reveal backend API gaps or mismatches. Mitigation: Audit each API response shape against page needs during implementation. **RESOLVED** — All 3 mock-data pages wired successfully. No API gaps found.
4. ~~**Open**: Exact task status values for Kanban columns~~ **RESOLVED** — TaskStatus enum: NOT_STARTED, IN_PROGRESS, PAUSED, COMPLETED, ARCHIVED (5 columns).
5. ~~**Open**: Whether Workspace page should require project selection or show a default view~~ **RESOLVED** — Shows project selector when no project param, workspace detail when ?project=id.
6. ~~**Open**: File Manager page — should it be a direct mapping of Knowledge entries or a separate file abstraction?~~ **RESOLVED** — Direct mapping to Knowledge entries via /api/knowledge. API shape matches file manager needs.

## Existing Backend API Modules (Reference)

These 19 NestJS modules are already implemented with Prisma and available for frontend wiring:

| Module             | Endpoint                       | Capabilities          |
| ------------------ | ------------------------------ | --------------------- |
| Projects           | `/api/projects`                | Full CRUD             |
| Tasks              | `/api/tasks`                   | Full CRUD             |
| Layouts            | `/api/layouts`                 | Widget placement      |
| Widgets            | `/api/widgets`                 | Data endpoints        |
| Activity           | `/api/activity`                | Audit logs            |
| Dashboard          | `/api/dashboard/summary`       | Aggregated summary    |
| Knowledge          | `/api/knowledge`               | Full CRUD + search    |
| Ideas              | `/api/ideas`                   | Capture/CRUD          |
| Domains            | `/api/domains`                 | CRUD                  |
| Events             | `/api/events`                  | CRUD                  |
| Preferences        | `/api/users/me/preferences`    | User settings         |
| Workspace Settings | `/api/workspaces/:id/settings` | LLM config            |
| Runner Jobs        | `/api/runner-jobs`             | Job management        |
| Job Steps          | `/api/runner-jobs/:id/steps`   | Step tracking         |
| Agent Tasks        | `/api/agent-tasks`             | Agent task management |
| Credentials        | `/api/credentials`             | Encrypted storage     |
| Brain/AI           | `/api/brain`                   | Query/search          |
| WebSocket          | Real-time                      | Event broadcasting    |
| LLM                | `/api/llm/chat`                | Chat + SSE streaming  |
| Orchestrator Proxy | `/api/orchestrator/*`          | Agent mgmt proxy      |
| Telemetry          | Internal                       | Logging/monitoring    |

## Testing and Verification

1. Baseline: `pnpm lint && pnpm build` must pass
2. Situational: All sidebar links navigate without 404
3. Situational: Each new page renders with real API data
4. Situational: Theme toggle on each new page
5. Situational: Responsive verification at sm/md/lg/xl
6. E2E: Playwright tests for all page navigation (MS23)
7. E2E: Auth flow with Authentik (MS23)
8. Federation: Master-master and master-slave data access tests (MS21)

## Delivery/Milestone Intent

| Milestone                      | Version | Focus                                                             | Status      |
| ------------------------------ | ------- | ----------------------------------------------------------------- | ----------- |
| MS15-DashboardShell            | 0.0.15  | Design system + app shell + dashboard page                        | COMPLETE    |
| Go-Live MVP                    | 0.0.16  | Dashboard polish, ingestion, agent visibility, deploy             | COMPLETE    |
| MS16+MS17-PagesDataIntegration | 0.0.17  | All pages built + wired to real API data                          | COMPLETE    |
| MS18-ThemeWidgets              | 0.0.18  | Theme package system, widget registry, WYSIWYG, Kanban filtering  | COMPLETE    |
| MS19-ChatTerminal              | 0.0.19  | Global terminal, project chat, master chat session                | COMPLETE    |
| MS20-SiteStabilization         | 0.0.20  | Runtime bug fixes, missing endpoints, orchestrator connectivity   | IN PROGRESS |
| MS21-MultiTenant               | 0.0.21  | Multi-tenant, teams, RBAC, RLS enforcement, break-glass auth      | NOT STARTED |
| MS22-Federation                | 0.0.22  | Federation (M-M, M-S), 3 instances, key exchange, data separation | NOT STARTED |
| MS23-AgentTelemetry            | 0.0.23  | Agent task mapping, telemetry, wide-event logging                 | NOT STARTED |
| MS24-Testing                   | 0.0.24  | Playwright E2E, federation tests, documentation finalization      | NOT STARTED |

## Assumptions

1. ASSUMPTION: Header spans full width including above sidebar area. The logo is in the header, not the sidebar. Rationale: User explicitly stated "The logo will NOT be part of the sidebar."
2. ASSUMPTION: Sidebar footer user card navigates to Profile page. Rationale: Matches reference design behavior.
3. ASSUMPTION: Initial implementation supports dark/light from reference design. Multi-theme package system is a future milestone. Rationale: Foundation must be solid before extensibility.
4. ASSUMPTION: MS16 and MS17 are combined into a single mission because 19 backend API modules already exist with real Prisma business logic. The remaining work is primarily frontend page creation and API wiring. Rationale: Backend audit on 2026-02-22 confirmed all required endpoints are implemented.
5. ASSUMPTION: File Manager page maps to Knowledge entries rather than a separate file system abstraction. Rationale: `/api/knowledge` provides full CRUD + search which matches file manager needs. Can be extended later if needed.
6. ASSUMPTION: Theme packages are code-level TypeScript files (not runtime-installable npm packages). Each theme exports CSS variable overrides. Rationale: Keeps the system simple for MS18; runtime package loading can be added in a future milestone.
7. ASSUMPTION: WYSIWYG editor uses Tiptap (ProseMirror-based, headless). Rationale: Headless approach integrates naturally with the CSS variable design system, excellent markdown import/export, TypeScript-first, battle-tested.
8. ASSUMPTION: MS18 includes WYSIWYG editing for knowledge entries and Kanban filtering enhancements in addition to themes and widgets. These were originally listed separately but are grouped into MS18 per PRD scope items 24-25. Rationale: All are frontend-focused enhancements that build on the existing page infrastructure.
9. ASSUMPTION: The `useWorkspaceId()` hook + auto-detect in `apiRequest` from PR #532 handles reads, but mutation endpoints on some pages don't pass workspace ID correctly. Rationale: GET requests work after PR #532 but POST/mutation requests still fail on domains and projects pages.
10. ASSUMPTION: Personalities API follows existing NestJS module patterns (controller + service + DTO + Prisma model). Rationale: Consistent with all other API modules in the codebase.
11. ASSUMPTION: User preferences endpoint is part of the existing users module but route is not registered. Rationale: PRD lists it as an existing endpoint.
12. ASSUMPTION: The orchestrator service container runs but the Next.js API proxy cannot reach it. Root cause is likely environment variable or network configuration in Docker Swarm. Rationale: The orchestrator container exists in the compose file and has Traefik labels.
13. ASSUMPTION: Terminal should have a dedicated page route `/terminal` that renders the terminal panel full-screen. Rationale: The sidebar has a Terminal link in the Operations section alongside Logs, implying it should be a navigable page.
14. ASSUMPTION: Credential CRUD frontend can use the existing `/api/credentials` API which was built during M7-CredentialSecurity. Rationale: Backend endpoints exist per audit.
