# Mission Scratchpad — MS18 Theme & Widget System

> Append-only log. NEVER delete entries. NEVER overwrite sections.
> This is the orchestrator's working memory across sessions.

## Original Mission Prompt

```
Close out MS16+MS17 mission and initialize new mission for MS18 — Theme/Widgets.
User confirmed: all 4 feature areas (themes, widgets, WYSIWYG, Kanban filtering).
WYSIWYG editor library: agent's choice → Tiptap selected.
```

## Planning Decisions

### 2026-02-23 — Scope & Architecture

**Decision: Tiptap for WYSIWYG editor**

- ProseMirror-based, headless (fits our CSS variable design system perfectly)
- Excellent markdown import/export via tiptap-markdown
- Battle-tested, TypeScript-first, largest React ecosystem
- Alternatives considered: Plate (Slate-based, more opinionated UI, smaller community)

**Decision: Theme packages as TypeScript files, not DB**

- Themes defined in `apps/web/src/themes/` as TS files exporting CSS variable maps
- Aligns with PRD's "installable packages from Mosaic Stack repo" concept
- No new Prisma model needed — `UserPreference.theme` (string field) already exists
- Theme files export: name, displayName, description, author, colorPreview, cssVariables
- Built-in themes: Dark (default), Light, Nord, Dracula, Solarized Dark
- ASSUMPTION: Theme packages are code-level packages (TS files), not runtime-installable npm packages. Rationale: keeps the system simple for MS18; runtime package loading can be added later.

**Decision: Dashboard migration to WidgetGrid**

- Current dashboard has hardcoded layout (DashboardMetrics, OrchestratorSessions, QuickActions, ActivityFeed, TokenBudget)
- Will migrate to WidgetGrid with these as default widget placements
- Need to seed WidgetDefinition records for the 7 registered widgets
- Default layout created on first visit if no UserLayout exists
- Existing dashboard components become widget implementations

**Decision: Kanban filtering approach**

- Add filter bar above columns (project, assignee, priority, search)
- User-level view: tasks assigned to current user across all projects
- Project-level view: all tasks in selected project
- Filters stored in URL params for shareability/bookmarkability

**Codebase findings:**

- 7 widgets already registered in WidgetRegistry.tsx
- WidgetGrid.tsx uses react-grid-layout (12-col, 100px row height)
- BaseWidget.tsx provides consistent wrapper with loading/error states
- Backend widget data endpoints exist (stat-card, chart, list, calendar-preview, active-projects, agent-chains)
- UserLayout model ready (workspace+user scoped, JSON layout, metadata)
- Widget definitions NOT seeded in DB — need seed data
- KnowledgeEntry.contentHtml field exists but unused (ready for WYSIWYG)

**Task structure: 17 tasks across 5 phases:**

- Phase 1 (Theme System): Theme architecture + built-in themes + theme UI + ThemeProvider upgrade
- Phase 2 (Widget Dashboard): Widget seeding + dashboard migration + picker UI + config UI + layout management
- Phase 3 (WYSIWYG): Tiptap setup + markdown round-trip + file manager integration
- Phase 4 (Kanban): Filtering + user-level view
- Phase 5 (Verification): Tests + theme verification + deploy

**Estimate:** ~500K tokens total across multiple sessions.

## Session Log

| Session | Date       | Milestone | Tasks Done                    | Outcome                                                           |
| ------- | ---------- | --------- | ----------------------------- | ----------------------------------------------------------------- |
| S1      | 2026-02-23 | MS18      | PLAN-001                      | Planning complete                                                 |
| S2      | 2026-02-23 | MS18      | THM-001, THM-002, THM-003     | Theme system complete — PRs #493, #494, #495                      |
| S3      | 2026-02-23 | MS18      | WDG-001–005, EDT-001–002      | Widget + editor complete — PRs #496–#501                          |
| S4      | 2026-02-24 | MS18      | KBN-001, VER-001–002, DOC-001 | Kanban filtering, tests, theme verification, docs — PRs #502–#504 |

## Open Questions

1. **Widget config schema**: How complex should per-widget configuration be? Start simple (title, data source) and extend later.
2. **Theme hot-reload**: ~~Should theme changes apply instantly or require page reload?~~ RESOLVED — Instant via CSS variable injection on html element.
3. **Tiptap extensions**: Which extensions to include? Start with: StarterKit, Markdown, Table, CodeBlockLowlight, Link, Image, Placeholder.

## Corrections

(none)