@polderlabs/bizar 10.7.2 → 10.11.0

package/bizar-dash/PLAN.md

@@ -1,1135 +0,0 @@
-# PLAN.md — Dashboard v8 Rewrite (Implementation Plan)
-
-> Companion to `DESIGN.md`. This document covers **how** we build the
-> rewrite; the design doc covers **what** it looks like. Read both
-> together. Scope: complete deletion of the v7 dashboard (F-040 + F-041)
-> and greenfield build of v8 in its place.
-
----
-
-## Table of contents
-
-1. [Goals & non-goals](#1--goals--non-goals)
-2. [Architecture decisions](#2--architecture-decisions)
-3. [Tech stack](#3--tech-stack)
-4. [File structure](#4--file-structure)
-5. [Component library breakdown](#5--component-library-breakdown)
-6. [Data model & API surface](#6--data-model--api-surface)
-7. [Routing](#7--routing)
-8. [State management](#8--state-management)
-9. [Real-time updates](#9--real-time-updates)
-10. [Theme system](#10--theme-system)
-11. [Settings model](#11--settings-model)
-12. [Migration / deletion of old dashboard](#12--migration--deletion-of-old-dashboard)
-13. [Phased implementation plan](#13--phased-implementation-plan)
-14. [Sprint schedule](#14--sprint-schedule)
-15. [Testing strategy](#15--testing-strategy)
-16. [Integration with Bizar harness](#16--integration-with-bizar-harness)
-17. [Risks & open questions](#17--risks--open-questions)
-
----
-
-## 1 · Goals & non-goals
-
-### Goals
-
-1. **Replace v7 dashboard with a clean v8** built around the shadcn
-   preset `b7kBsBkh7b` and the user-supplied OKLch theme.
-2. **Ship a custom component library** at `bizar-dash/src/web/ui/`
-   with 100+ primitives, controls, feedback, data, navigation,
-   kanban, and popup components.
-3. **Topbar + sidebar shell** with six top-level nav groups and
-   hierarchical sub-routes.
-4. **Kanban-first experience** — drag-and-drop, filters, group-by,
-   sort, density toggle, keyboard shortcuts, right-click context
-   menus on every card.
-5. **Long-horizon goal tracking** as a first-class page with progress
-   visualization, milestones, and goal→task breakdown.
-6. **Right-click context menus everywhere** — no browser defaults on
-   interactive surfaces, no `window.confirm` / `window.alert` /
-   `window.prompt`.
-7. **Command palette (Cmd+K)** with three scopes: Actions, Navigate,
-   Settings.
-8. **Hierarchical settings** with 16 sections, each with auto-saving
-   fields and Cmd+K discoverability.
-9. **Real-time updates** via the existing WebSocket feed (no new
-   transport).
-10. **Power-user density** by default, with a comfortable toggle.
-
-### Non-goals (v8.0)
-
-- No mobile native apps. Mobile web is responsive but desktop-first.
-- No new backend endpoints. We consume the existing REST + WS surface.
-- No new MCP tools. We surface existing tool outputs only.
-- No auth/identity changes. Single-user local dashboard for now.
-- No telemetry/analytics. Optional later via opt-in settings.
-- No plugin/theme marketplace. Internal-only.
-- No multi-tenant workspace switching UI (the data model supports it
-  via `workspace_id`, but the UI ships single-workspace for v8.0).
-
----
-
-## 2 · Architecture decisions
-
-| # | Decision | Why | Alternatives considered |
-|--|--|--|--|
-| AD-01 | **Delete the entire `bizar-dash/` v7 code, rebuild from scratch.** | The v7 design system (F-040) and mobile pass (F-041) conflict with the new aesthetic (green accent, no Norse dark mode, no gradients, gradient-free). Incremental migration would carry old patterns forward. | (a) Incremental rewrite (rejected: mixes generations). (b) Side-by-side `bizar-dash-v8/` (rejected: two trees to maintain). |
-| AD-02 | **Use shadcn preset `b7kBsBkh7b` as bootstrap.** | User-specified. The preset ships OKLch tokens + Tailwind config matching the supplied theme. | Custom Tailwind config (rejected: reinvents the wheel). |
-| AD-03 | **TanStack Router for routing.** | Type-safe routes, file-based or code-based, built-in loader/action model, first-class search-param typing. The settings tree, kanban filters, and goal detail views all benefit. | React Router (rejected: weaker type safety). |
-| AD-04 | **TanStack Query for server state.** | Already in the Bizar ecosystem; cache invalidation on WS events is first-class; optimistic mutations are idiomatic. | SWR (rejected: weaker mutation story). Redux Toolkit Query (rejected: heavier, no use). |
-| AD-05 | **Zustand for local UI state.** | Sidebar collapse, density mode, palette open/close, theme — small, fast, no boilerplate. | React Context only (rejected: prop drilling for cross-cutting state). Jotai (rejected: atoms too granular). |
-| AD-06 | **dnd-kit for drag-and-drop.** | Accessible by default (keyboard sensors, screen-reader announcements), `useDraggable`/`useDroppable` are the right primitive for kanban, `restrictToVerticalAxis` for column drag, `DragOverlay` for the floating card. | react-beautiful-dnd (rejected: unmaintained). Native HTML5 DnD (rejected: accessibility nightmare). |
-| AD-07 | **TanStack Table for the kanban's tabular view.** | Headless, sortable, filterable, virtualizable, supports row selection and column resize — all the power-user table features without imposing UI. | AG Grid (rejected: heavy, license-gated). |
-| AD-08 | **Recharts for charts.** | Already used in v7. SVG-based, themeable via tokens, sufficient for our chart needs (line, bar, area, pie, sparkline). | Visx (rejected: too low-level for our time budget). D3 (rejected: hand-rolled charts cost more than they save). ECharts (rejected: not React-native). |
-| AD-09 | **cmdk for the command palette.** | Used by Linear, Raycast, Vercel — the same UX we want. | Headless combobox (rejected: rebuild what cmdk already does). |
-| AD-10 | **Radix UI primitives under every interactive component.** | Accessibility is solved (focus management, keyboard nav, ARIA), behavior is unstyled, theming is via our tokens. | Headless UI (rejected: smaller primitive set). React Aria (rejected: harder to compose). |
-| AD-11 | **React Hook Form + Zod for forms.** | Already in the Bizar ecosystem. Schema-first validation matches our MCP tool registration. | Formik (rejected: legacy). |
-| AD-12 | **date-fns for date math.** | Tree-shakeable, immutable, locale-aware. Used by the kanban and goal views. | Day.js (rejected: OOP-style chains, less composable). Luxon (rejected: heavier). |
-| AD-13 | **No Tailwind in `ui/`.** | All `ui/` components consume CSS variables only. Tailwind utility classes are used at the page/view layer to compose components, never inside `ui/` itself. | (a) Tailwind everywhere (rejected: leaks utility classes into primitives). (b) CSS-in-JS (rejected: runtime cost). |
-| AD-14 | **No CSS modules, no styled-components.** | Plain CSS files co-located with each component (`Button.tsx` + `Button.css`). Tokens are global. | CSS Modules (rejected: heavier, same outcome). |
-| AD-15 | **No state-management library inside `ui/`.** | `ui/` is presentational. All data, WS, and mutation logic lives in `views/`, `hooks/`, and `stores/`. | (a) Allow data in `ui/` (rejected: leaks, untestable in isolation). |
-| AD-16 | **Single WebSocket connection.** | All live data flows over `/ws/dashboard`. Per-feature subscriptions multiplexed via message-type discrimination. | (a) One WS per feature (rejected: connection overhead). (b) SSE (rejected: one-way). |
-| AD-17 | **No new dependencies unless justified.** | The Bizar harness is conservative on deps. Each new dep must be approved in a sprint contract. | — |
-
-
----
-
-## 3 · Tech stack
-
-### Runtime
-
-| Layer | Choice | Version |
-|--|--|--|
-| Build | Vite | 5+ |
-| Language | TypeScript (strict) | 5.5+ |
-| UI framework | React | 19 |
-| Routing | TanStack Router | 1.x |
-| Server state | TanStack Query | 5.x |
-| UI state | Zustand | 4.x |
-| Forms | React Hook Form + Zod | latest |
-| DnD | dnd-kit | 6.x |
-| Tables | TanStack Table | 8.x |
-| Virtualization | TanStack Virtual | 3.x |
-| Charts | Recharts | 2.x |
-| Date | date-fns | 3.x |
-| Icons | lucide-react | latest |
-| Toasts | sonner | 1.x |
-| Command palette | cmdk | 0.2.x |
-| Primitives | Radix UI | latest |
-| Class merge | clsx + tailwind-merge | latest |
-
-### Why no Tailwind inside `ui/`
-
-Tailwind utility classes leak implementation details. If a future
-maintainer changes `Button.tsx` and removes a class, there's no
-compiler error — just a silent regression. Co-located plain CSS
-keeps the surface tight and reviewable.
-
-### pnpm workspaces
-
-The dashboard lives in `bizar-dash/` and shares the root
-`pnpm-workspace.yaml`. All third-party deps are pinned at the root
-in `pnpm-lock.yaml`.
-
----
-
-## 4 · File structure
-
-```
-bizar-dash/
-├── DESIGN.md              # this rewrite's design system
-├── PLAN.md                # this file
-├── ARCHITECTURE.md        # module-level doc (rewritten for v8)
-├── CONSTRAINTS.md         # module-level rules
-├── README.md              # developer quick-start
-├── package.json
-├── tsconfig.json
-├── vite.config.ts
-├── vitest.config.ts
-├── playwright.config.ts   # visual + keyboard E2E
-├── public/
-│   ├── favicon.svg
-│   └── fonts/             # Inter + JetBrains Mono subsets
-├── scripts/
-│   ├── check-design-tropes.sh   # banned-pattern audit (§12 DESIGN)
-│   ├── check-arch.sh            # moved from repo root
-│   └── test-in-container.sh
-├── src/
-│   ├── server/                  # unchanged from v7 (REST + WS)
-│   │   ├── api.mjs
-│   │   ├── ws.mjs
-│   │   └── routes/
-│   ├── web/
-│   │   ├── main.tsx
-│   │   ├── App.tsx
-│   │   ├── routes.tsx
-│   │   ├── lib/
-│   │   │   ├── ws.ts                  # WS singleton + typed subscribe
-│   │   │   ├── api.ts                 # typed fetch wrapper
-│   │   │   ├── query-client.ts        # TanStack Query setup
-│   │   │   └── types.ts               # shared TS types
-│   │   ├── stores/
-│   │   │   ├── theme.ts
-│   │   │   ├── density.ts
-│   │   │   ├── palette.ts             # Cmd+K open state
-│   │   │   ├── sidebar.ts             # collapse state
-│   │   │   └── selection.ts           # current kanban/agents selection
-│   │   ├── ui/                        # the library (no business logic)
-│   │   │   ├── index.ts               # barrel
-│   │   │   ├── primitives/
-│   │   │   ├── controls/
-│   │   │   ├── feedback/
-│   │   │   ├── data/
-│   │   │   ├── navigation/
-│   │   │   ├── kanban/
-│   │   │   ├── popups/
-│   │   │   ├── theme/
-│   │   │   ├── hooks/
-│   │   │   ├── utils/
-│   │   │   └── styles/
-│   │   │       ├── reset.css
-│   │   │       ├── tokens.css         # generated from §3 DESIGN
-│   │   │       └── globals.css
-│   │   ├── views/
-│   │   │   ├── Overview/
-│   │   │   ├── Tasks/
-│   │   │   ├── Goals/
-│   │   │   ├── Agents/
-│   │   │   ├── Activity/
-│   │   │   ├── Memory/
-│   │   │   ├── Libraries/
-│   │   │   └── Settings/
-│   │   ├── icons/                     # domain icons
-│   │   └── shell/                     # AppShell + Topbar + Sidebar
-│   │       ├── AppShell.tsx
-│   │       ├── Topbar.tsx
-│   │       ├── Sidebar.tsx
-│   │       └── StatusBar.tsx
-│   └── shared/
-│       └── tokens.json          # source of truth for tokens.css
-└── tests/
-    ├── unit/                    # vitest
-    │   ├── ui/                  # per-component
-    │   └── views/               # per-view
-    ├── e2e/                     # playwright
-    │   ├── smoke.spec.ts
-    │   ├── keyboard.spec.ts
-    │   └── visual.spec.ts
-    └── a11y/                    # axe-core
-```
-
-
----
-
-## 5 · Component library breakdown
-
-The full inventory lives in DESIGN.md §8. This section is the
-**build order** — which components ship in which sprint.
-
-### Wave 1 — Foundation (Sprint 1)
-
-Tokens, theme, layout shell, and the 11 primitives. Everything else
-depends on these.
-
-- `ui/styles/{reset,tokens,globals}.css`
-- `ui/theme/{ThemeProvider,ThemeToggle,DensityProvider,useTheme,useDensity}.tsx`
-- `ui/primitives/*` (11 components)
-- `shell/{AppShell,Topbar,Sidebar,StatusBar}.tsx`
-
-### Wave 2 — Controls & feedback (Sprint 2)
-
-Buttons, inputs, dialogs, popovers — the bulk of the form system.
-
-- `ui/controls/*` (20 components)
-- `ui/feedback/*` (16 components)
-- `ui/utils/{cx,formatters,useHotkeys,useFocusTrap,useMediaQuery,useReducedMotion,useDebouncedValue,useLocalStorage}.ts`
-
-### Wave 3 — Data display (Sprint 3)
-
-Cards, tables, charts, avatars, badges — everything for showing
-information.
-
-- `ui/data/*` (24 components)
-
-### Wave 4 — Navigation (Sprint 4)
-
-Sidebar/nav wiring, tabs, menus, command palette, pagination.
-
-- `ui/navigation/*` (23 components)
-- `ui/popups/*` (8 components)
-- `stores/{palette,sidebar,selection}.ts`
-
-### Wave 5 — Kanban (Sprint 5)
-
-The centerpiece. Card, column, board, filters, group-by, sort,
-density, context menu, drag overlay, detail drawer.
-
-- `ui/kanban/*` (15 components)
-- `hooks/useTasks.ts` (query + mutations)
-- `views/Tasks/*`
-
-### Wave 6 — Views (Sprint 6-8)
-
-Overview, Goals, Agents, Activity, Memory, Libraries, Settings —
-one sprint per major view.
-
-### Wave 7 — Polish (Sprint 9)
-
-Empty states, error states, motion audit, accessibility audit,
-keyboard walkthrough, visual regression, banned-trope scan.
-
-
----
-
-## 6 · Data model & API surface
-
-The dashboard consumes the existing REST + WS surface. No new
-endpoints in v8. The data model is documented per-view in
-`views/<name>/README.md`.
-
-### 6.1 Core entities
-
-```ts
-// Shared types — src/web/lib/types.ts
-
-type ID = string;        // UUID v4 or short slug
-type ISODate = string;   // ISO-8601 UTC
-type Priority = 'p0' | 'p1' | 'p2' | 'p3' | 'p4';
-type Status = 'backlog' | 'todo' | 'in_progress' | 'in_review' | 'done' | 'cancelled';
-
-interface Task {
-  id: ID;
-  workspace_id: ID;
-  project_id: ID;
-  title: string;
-  description?: string;
-  status: Status;
-  priority: Priority;
-  assignee_agent_id?: ID;
-  labels: string[];
-  due_at?: ISODate;
-  estimate_min?: number;
-  parent_goal_id?: ID;
-  parent_task_id?: ID;
-  created_at: ISODate;
-  updated_at: ISODate;
-}
-
-interface Goal {
-  id: ID;
-  workspace_id: ID;
-  title: string;
-  description?: string;
-  cadence: 'weekly' | 'monthly' | 'quarterly' | 'annual';
-  progress_pct: number;          // 0..100, derived from task weights
-  milestones: Milestone[];
-  task_ids: ID[];
-  status: 'active' | 'paused' | 'completed' | 'archived';
-  review_at?: ISODate;
-  created_at: ISODate;
-  updated_at: ISODate;
-}
-
-interface Agent {
-  id: ID;
-  type: 'coder' | 'tester' | 'reviewer' | 'system-architect'
-      | 'planner' | 'researcher' | 'performance-engineer'
-      | 'security-auditor' | 'memory-specialist';
-  display_name: string;
-  status: 'idle' | 'busy' | 'offline' | 'errored';
-  current_task_id?: ID;
-  tokens_used: number;
-  cost_usd: number;
-  registered_at: ISODate;
-  last_active_at: ISODate;
-}
-
-interface ActivityEvent {
-  id: ID;
-  workspace_id: ID;
-  type: 'task_created' | 'task_updated' | 'task_completed'
-      | 'agent_spawned' | 'agent_terminated' | 'routing_decision'
-      | 'cost_reserved' | 'cost_committed' | 'memory_distilled'
-      | 'consensus_proposed' | 'goal_progress' | 'system';
-  actor: { kind: 'user' | 'agent' | 'system'; id?: ID };
-  target?: { kind: 'task' | 'goal' | 'agent' | 'memory'; id: ID };
-  payload: Record<string, unknown>;
-  created_at: ISODate;
-}
-```
-
-### 6.2 REST endpoints (consumed, unchanged)
-
-| Method | Path | Purpose |
-|--|--|--|
-| GET | `/api/tasks` | List tasks (filters: `?status=&assignee=&label=`) |
-| POST | `/api/tasks` | Create task |
-| PATCH | `/api/tasks/:id` | Update task |
-| DELETE | `/api/tasks/:id` | Archive task |
-| POST | `/api/tasks/reorder` | Move task across columns |
-| GET | `/api/goals` | List goals |
-| POST | `/api/goals` | Create goal |
-| PATCH | `/api/goals/:id` | Update goal |
-| GET | `/api/agents` | List agents |
-| GET | `/api/activity?since=` | Activity events since timestamp |
-| GET | `/api/memory?q=` | Memory search |
-| GET | `/api/distill/patterns` | Distilled patterns |
-| GET | `/api/cost/status` | Cost gate status |
-| GET | `/api/routing/decisions?limit=` | Recent routing decisions |
-| GET | `/api/skills` | Skills |
-| GET | `/api/mcps` | MCP servers |
-| GET | `/api/hooks` | Hook config |
-| GET/PATCH | `/api/settings/:section` | Settings CRUD |
-
-### 6.3 WebSocket messages (consumed, unchanged)
-
-| Type | Direction | Payload |
-|--|--|--|
-| `tasks:change` | server→client | `{ task: Task }` |
-| `tasks:delete` | server→client | `{ id: ID }` |
-| `agents:change` | server→client | `{ agent: Agent }` |
-| `goals:change` | server→client | `{ goal: Goal }` |
-| `activity:event` | server→client | `{ event: ActivityEvent }` |
-| `routing:decision` | server→client | `{ decision: RoutingDecision }` |
-| `cost:tick` | server→client | `{ reservation: CostReservation }` |
-| `system:status` | server→client | `{ health, version, build }` |
-
-### 6.4 Settings payload (v8)
-
-Settings are stored under `/api/settings/:section`. v8 adds the
-following sections: `general`, `appearance`, `agents`, `goals`,
-`tasks`, `skills`, `mcps`, `hooks`, `routing`, `memory`,
-`notifications`, `security`, `integrations`, `billing`, `team`,
-`advanced`. Each is a Zod-validated object; the server rejects
-unknown keys.
-
----
-
-## 7 · Routing
-
-### 7.1 Route tree (TanStack Router, code-based)
-
-```ts
-// src/web/routes.tsx
-const rootRoute = createRootRoute({ component: AppShell });
-
-const indexRoute = createRoute({
-  getParentRoute: () => rootRoute,
-  path: '/',
-  component: OverviewPage,
-});
-
-const tasksRoute = createRoute({
-  getParentRoute: () => rootRoute,
-  path: 'tasks',
-  component: TasksLayout,
-});
-
-const tasksIndex = createRoute({
-  getParentRoute: () => tasksRoute,
-  path: '/',
-  component: TasksKanban,    // default view
-  validateSearch: z.object({
-    group: z.enum(['status', 'assignee', 'label', 'priority', 'due', 'project']).optional(),
-    assignee: z.string().optional(),
-    label: z.string().optional(),
-    q: z.string().optional(),
-  }),
-});
-
-const tasksListRoute = createRoute({
-  getParentRoute: () => tasksRoute,
-  path: 'list',
-  component: TasksList,
-});
-
-const tasksCalendarRoute = createRoute({
-  getParentRoute: () => tasksRoute,
-  path: 'calendar',
-  component: TasksCalendar,
-});
-
-// ... goals, agents, activity, memory, libraries, settings ...
-
-const routeTree = rootRoute.addChildren([
-  indexRoute,
-  tasksRoute.addChildren([tasksIndex, tasksListRoute, tasksCalendarRoute]),
-  // ...
-]);
-```
-
-### 7.2 Route guards
-
-- `/settings/*` requires `localStorage.bizar_workspace_id` to be set;
-  otherwise redirects to `/setup`.
-- `/agents/:id` validates `:id` is a valid agent id; otherwise 404.
-- All other routes are open.
-
-### 7.3 Search params
-
-Each route that supports filters declares a `validateSearch` Zod
-schema. Filters survive reloads via URL state. The kanban view
-serializes its filters into the URL so a deep link reproduces the
-exact view.
-
----
-
-## 8 · State management
-
-### 8.1 Server state (TanStack Query)
-
-```ts
-// src/web/lib/query-client.ts
-export const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 30_000,
-      gcTime: 5 * 60_000,
-      refetchOnWindowFocus: false,
-      retry: 1,
-    },
-  },
-});
-```
-
-Query keys are namespaced: `['tasks']`, `['tasks', filters]`,
-`['goals']`, `['agents']`, `['activity', since]`, `['settings', section]`.
-
-WS events invalidate the relevant keys:
-
-```ts
-ws.on('tasks:change', () => {
-  queryClient.invalidateQueries({ queryKey: ['tasks'] });
-});
-```
-
-### 8.2 UI state (Zustand)
-
-Stores live at `src/web/stores/`. Each store is a single Zustand
-slice with no nested state.
-
-```ts
-// stores/palette.ts
-interface PaletteState {
-  open: boolean;
-  scope: 'actions' | 'navigate' | 'settings';
-  toggle: () => void;
-  setScope: (scope: PaletteState['scope']) => void;
-}
-```
-
-Other stores: `theme`, `density`, `sidebar` (collapsed), `selection`
-(current kanban/agents selection for bulk actions).
-
-### 8.3 Form state (React Hook Form)
-
-Forms auto-save on blur; explicit save button is reserved for
-multi-field forms in settings. Schema is Zod, error rendering uses
-`react-hook-form`'s `formState.errors` mapped to `Field`'s error slot.
-
-### 8.4 URL state (TanStack Router search params)
-
-Anything filterable lives in the URL. The kanban view's group,
-assignee, label, and search query are all in the URL.
-
-
----
-
-## 9 · Real-time updates
-
-### 9.1 WS singleton
-
-```ts
-// src/web/lib/ws.ts
-class DashboardWS {
-  private ws: WebSocket | null = null;
-  private listeners = new Map<string, Set<(payload: unknown) => void>>();
-  private status: 'connecting' | 'open' | 'reconnecting' | 'closed' = 'closed';
-  private reconnectAttempts = 0;
-
-  connect() {
-    if (this.ws) return;
-    this.status = 'connecting';
-    this.ws = new WebSocket('/ws/dashboard');
-    this.ws.onopen = () => { this.status = 'open'; this.reconnectAttempts = 0; };
-    this.ws.onclose = () => {
-      this.status = 'closed';
-      const delay = Math.min(30_000, 1000 * 2 ** this.reconnectAttempts++);
-      setTimeout(() => this.connect(), delay);
-    };
-    this.ws.onmessage = (event) => {
-      const { type, payload } = JSON.parse(event.data);
-      this.listeners.get(type)?.forEach((cb) => cb(payload));
-      this.listeners.get('*')?.forEach((cb) => cb({ type, payload }));
-    };
-  }
-
-  on(type: string, cb: (payload: unknown) => void): () => void {
-    const set = this.listeners.get(type) ?? new Set();
-    set.add(cb);
-    this.listeners.set(type, set);
-    return () => set.delete(cb);
-  }
-
-  getStatus() { return this.status; }
-}
-
-export const ws = new DashboardWS();
-```
-
-### 9.2 Hook
-
-```ts
-// src/web/ui/hooks/useWebSocket.ts
-export function useWebSocket<T>(
-  type: string,
-  handler: (payload: T) => void,
-) {
-  useEffect(() => {
-    ws.connect();
-    return ws.on(type, handler as (p: unknown) => void);
-  }, [type, handler]);
-}
-```
-
-### 9.3 Cache invalidation pattern
-
-```ts
-// src/web/lib/ws-invalidate.ts
-ws.on('tasks:change', () => queryClient.invalidateQueries({ queryKey: ['tasks'] }));
-ws.on('tasks:delete', () => queryClient.invalidateQueries({ queryKey: ['tasks'] }));
-ws.on('agents:change', () => queryClient.invalidateQueries({ queryKey: ['agents'] }));
-ws.on('goals:change', () => queryClient.invalidateQueries({ queryKey: ['goals'] }));
-ws.on('activity:event', () => queryClient.invalidateQueries({ queryKey: ['activity'] }));
-ws.on('routing:decision', () => queryClient.invalidateQueries({ queryKey: ['routing'] }));
-ws.on('cost:tick', () => queryClient.invalidateQueries({ queryKey: ['cost'] }));
-ws.on('system:status', () => queryClient.invalidateQueries({ queryKey: ['system'] }));
-```
-
-### 9.4 Status indicator
-
-The topbar shows a status pill driven by `ws.getStatus()`:
-- `open` → green pulse, "Live"
-- `reconnecting` → amber pulse, "Reconnecting"
-- `closed` → red dot, "Offline"
-
----
-
-## 10 · Theme system
-
-### 10.1 Provider
-
-```tsx
-// src/web/ui/theme/ThemeProvider.tsx
-export function ThemeProvider({ children }: { children: React.ReactNode }) {
-  const [theme, setTheme] = useState<'light' | 'dark' | 'system'>(
-    () => (localStorage.getItem('bizar.theme') as any) ?? 'system',
-  );
-  const resolved = useMemo(() => resolveTheme(theme), [theme]);
-
-  useEffect(() => {
-    document.documentElement.classList.toggle('dark', resolved === 'dark');
-    localStorage.setItem('bizar.theme', theme);
-  }, [theme, resolved]);
-
-  return (
-    <ThemeContext.Provider value={{ theme, setTheme, resolved }}>
-      {children}
-    </ThemeContext.Provider>
-  );
-}
-```
-
-### 10.2 Tokens
-
-`tokens.css` is generated from `src/shared/tokens.json` by a small
-build script. The JSON is the source of truth; the CSS is generated
-on every `pnpm build`. Any token added to the JSON must also be
-added to DESIGN.md §3 — this is checked in CI.
-
-### 10.3 Token generation
-
-```ts
-// scripts/generate-tokens.ts
-import tokens from '../src/shared/tokens.json';
-import fs from 'node:fs';
-
-const light = generateCSS(':root', tokens.light);
-const dark = generateCSS('.dark', tokens.dark);
-const fs_write = `${light}\n\n${dark}\n`;
-fs.writeFileSync('src/web/ui/styles/tokens.css', fs_write);
-```
-
-### 10.4 Density
-
-Density is a separate concern, also a provider. The `<html>`
-element carries `data-density="compact|comfortable"`. CSS reads
-the attribute to swap row heights and padding.
-
----
-
-## 11 · Settings model
-
-### 11.1 Server-side schema
-
-Each setting section is a Zod schema. The server validates on every
-PATCH. The client mirrors the schema in `src/web/lib/settings-schemas.ts`.
-
-```ts
-// src/web/lib/settings-schemas.ts
-import { z } from 'zod';
-
-export const AgentsSettingsSchema = z.object({
-  defaultRosterSize: z.number().int().min(1).max(64).default(8),
-  maxConcurrent: z.number().int().min(1).max(64).default(16),
-  enabledTypes: z.array(z.enum(AGENT_TYPES)).default(AGENT_TYPES),
-  autoSpawnOnSession: z.boolean().default(true),
-  restartOnConfigChange: z.boolean().default(false),
-});
-```
-
-### 11.2 Settings store
-
-Settings are stored under `/api/settings/:section` (one file per
-section). The UI hydrates from the server on mount, mirrors to
-TanStack Query cache, and auto-saves on blur.
-
-```ts
-export function useSettings<T>(section: string) {
-  return useQuery({
-    queryKey: ['settings', section],
-    queryFn: () => api.get(`/api/settings/${section}`),
-    staleTime: Infinity, // settings rarely change
-  });
-}
-
-export function useUpdateSettings(section: string) {
-  return useMutation({
-    mutationFn: (data: unknown) => api.patch(`/api/settings/${section}`, data),
-    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['settings', section] }),
-  });
-}
-```
-
-### 11.3 Auto-save
-
-Field blur triggers `useUpdateSettings.mutate(fieldValue)`. On
-success: green checkmark flash for 1s. On error: inline error,
-toast, no revert (settings don't auto-revert).
-
-### 11.4 Settings sidebar (in-page)
-
-The settings layout (`views/Settings/SettingsLayout.tsx`) renders a
-secondary sidebar on the left of the page with the 16 sections,
-each linking to its route. Active section uses `--sidebar-accent`.
-
-### 11.5 Cmd+K integration
-
-Every settings key is a Command Palette entry. The palette's
-Settings scope renders one entry per settings section with its
-icon, name, and the parent breadcrumb.
-
-
----
-
-## 12 · Migration / deletion of old dashboard
-
-### 12.1 What gets deleted
-
-Everything inside `bizar-dash/src/web/` from the v7 release:
-
-```
-bizar-dash/src/web/
-├── ui/                  # DELETE all (F-040 primitives, controls, data, feedback, layout, navigation, styles, theme, utils)
-├── views/               # DELETE all (Overview, Tasks, Agents, Active, Skills, Memory, Mods, Schedules, Settings, Mobile*, Chat, Chat*)
-├── components/          # DELETE all
-├── hooks/               # DELETE all (replaced by ui/hooks + stores)
-├── lib/                 # KEEP only what v8 reuses (ws, api, types, query-client)
-├── locales/             # DELETE all (v8 is en-only for now)
-├── mobile/              # DELETE all (F-041 mobile pass — replaced by responsive web)
-├── styles/              # KEEP only what v8 needs
-├── App.tsx              # REPLACE
-├── MobileApp.tsx        # DELETE
-├── main.tsx             # REPLACE
-├── mobile.html          # DELETE
-├── mobile.tsx           # DELETE
-└── index.html           # REPLACE
-```
-
-Plus:
-
-- `bizar-dash/DESIGN.md` — replaced by the new DESIGN.md (this rewrite)
-- `bizar-dash/ARCHITECTURE.md` — replaced with v8 module doc
-- `bizar-dash/CONSTRAINTS.md` — replaced with v8 constraints
-- `bizar-dash/README.md` — replaced
-- `feature_list.json` — F-040 and F-041 entries are **reverted to not_started** and re-scoped as v8 sprints (§14)
-
-### 12.2 What stays
-
-- `bizar-dash/src/server/` — REST API and WebSocket server (unchanged).
-- `bizar-dash/scripts/` — keeps `check-arch.sh` (renamed if needed);
-  deletes other shell helpers that v8 doesn't reuse.
-- `bizar-dash/package.json`, `tsconfig.json`, `vite.config.ts`,
-  `vitest.config.ts` — replace with v8 versions.
-- `bizar-dash/dist/` — generated; rebuilt on `pnpm build`.
-- `bizar-dash/plans/`, `skills/`, `templates/`, `tests/` — module
-  metadata; preserve what v8 still consumes.
-
-### 12.3 Migration script
-
-A single bash script handles the destructive phase:
-
-```sh
-#!/usr/bin/env bash
-# scripts/v8-migrate.sh — run once at the start of Sprint 0
-set -euo pipefail
-
-cd "$(dirname "$0")/.."
-
-# 1. Delete the old web/ subtree (except shared lib/)
-rm -rf src/web/ui src/web/views src/web/components src/web/hooks
-rm -rf src/web/locales src/web/mobile src/web/styles
-rm -f src/web/App.tsx src/web/MobileApp.tsx src/web/main.tsx
-rm -f src/web/mobile.html src/web/mobile.tsx src/web/index.html
-
-# 2. Reset F-040 and F-041 in feature_list.json
-node scripts/v8-feature-list-reset.mjs
-
-# 3. Clear v8 token
-git mv DESIGN.md DESIGN.md.v7-bak || true
-git mv ARCHITECTURE.md ARCHITECTURE.md.v7-bak || true
-git mv CONSTRAINTS.md CONSTRAINTS.md.v7-bak || true
-git mv README.md README.md.v7-bak || true
-
-echo "v8 migration complete. Old artifacts in *.v7-bak; delete after v8.0 ships."
-```
-
-### 12.4 Rollback plan
-
-If v8.0 fails its gate (post-Sprint 9), revert to v7.0.0 via git.
-The `*.v7-bak` files preserve DESIGN.md, ARCHITECTURE.md,
-CONSTRAINTS.md, README.md so a revert restores documentation as
-well as code.
-
----
-
-## 13 · Phased implementation plan
-
-### Sprint 0 — Bootstrap (½ day)
-
-- Branch `worktree-v8-dashboard-rewrite` off `master`.
-- Run `scripts/v8-migrate.sh`.
-- `pnpm dlx shadcn@latest init --preset b7kBsBkh7b` (creates
-  `components.json`, `tailwind.config.ts`, baseline `globals.css`).
-- Override `tailwind.config.ts` to consume only our token CSS
-  variables (no utility classes leak into `ui/`).
-- Replace generated `globals.css` with our `tokens.css` from §3
-  DESIGN.
-
-**Exit gate:** `pnpm dev` boots a blank page with our token CSS
-applied. `pnpm check:design-tropes` exits 0.
-
-### Sprint 1 — Foundation
-
-- `ui/styles/{reset,tokens,globals}.css` (delivered)
-- `ui/theme/{ThemeProvider,ThemeToggle,DensityProvider,useTheme,useDensity}.tsx`
-- `ui/primitives/*` (11 components, each with `.test.tsx`)
-- `shell/{AppShell,Topbar,Sidebar,StatusBar}.tsx`
-
-**Exit gate:** App shell renders with sidebar + topbar. Theme
-toggle works. Density toggle works. 11 primitives have unit tests.
-
-### Sprint 2 — Controls & feedback
-
-- `ui/controls/*` (20 components)
-- `ui/feedback/*` (16 components)
-- `ui/utils/*` (8 utilities)
-
-**Exit gate:** Form playground page exercises every control +
-feedback component. Visual screenshot matches DESIGN §3 tokens.
-
-### Sprint 3 — Data display
-
-- `ui/data/*` (24 components)
-- `views/Overview/*` (uses StatTile, Chart, DataTable, BarList)
-
-**Exit gate:** Overview page renders against live `/api/agents`,
-`/api/tasks`, `/api/cost/status`. Visual screenshot at 1440 / 1100.
-
-### Sprint 4 — Navigation
-
-- `ui/navigation/*` (23 components)
-- `ui/popups/*` (8 components)
-- `stores/{palette,sidebar,selection}.ts`
-- Command palette wired with Actions + Navigate scopes.
-
-**Exit gate:** Cmd+K opens palette with all 6 nav items + 10+
-actions. Keyboard walkthrough passes for every nav item.
-
-### Sprint 5 — Kanban (the main focus)
-
-- `ui/kanban/*` (15 components)
-- `hooks/useTasks.ts`
-- `views/Tasks/*` (Kanban view + List view + Calendar view)
-- Right-click context menu on every card
-- Drag-and-drop across columns (with keyboard alternative)
-- Filters: status, assignee, label, priority, due, search
-- Group-by: status / assignee / label / priority / due / project
-- Sort: created / updated / priority / due
-- Density: compact / comfortable
-- Detail drawer (right side)
-
-**Exit gate:** 100 tasks in seeded data render in <100ms. Drag
-works via mouse + keyboard. Right-click menu opens on every card.
-URL state survives reload.
-
-### Sprint 6 — Goals + Agents
-
-- `views/Goals/*` — list, detail, milestones, progress
-- `views/Agents/*` — roster, detail, live status
-
-**Exit gate:** Goal → task breakdown visible. Agent roster shows
-live status with WS updates. Detail drawer works for both.
-
-### Sprint 7 — Activity + Memory + Libraries
-
-- `views/Activity/*` — event log + comm log + routing decisions
-- `views/Memory/*` — vault browser + distillation patterns
-- `views/Libraries/*` — Skills / MCPs / Hooks in a tabbed page
-
-**Exit gate:** Activity feed live-updates via WS. Memory search
-hits the existing `/api/memory?q=`. Libraries page shows all
-skills/MCPs/hooks with right-click context menus.
-
-### Sprint 8 — Settings (16 sections)
-
-- `views/Settings/*` — hierarchical with in-page sidebar
-- `lib/settings-schemas.ts` — Zod schemas for all 16 sections
-- Cmd+K Settings scope wired
-
-**Exit gate:** Every settings section renders, auto-saves, and
-survives reload. Cmd+K "Settings" scope lists every section.
-
-### Sprint 9 — Polish & verification
-
-- Empty/loading/error states for every view
-- Motion audit (every transition matches §6)
-- Accessibility audit (`pnpm check:a11y`)
-- Visual regression at 1440 / 1100 / 768 / 390
-- Keyboard walkthrough (`pnpm check:keyboard`)
-- Banned-trope scan (`pnpm check:design-tropes`)
-- Mobile responsive pass (single breakpoint at 768px; no mobile-
-  native apps)
-- Performance: lighthouse > 90 on `/tasks`
-
-**Exit gate:** All 5 checks green. L09 layers 1+2+3 all green.
-PROGRESS.md updated; release notes drafted.
-
-
----
-
-## 14 · Sprint schedule
-
-Sprint length: **3 working days** each. Total: 9 sprints × 3 = ~27
-working days, or roughly **5–6 calendar weeks** with a single full-
-time engineer + review.
-
-| Sprint | Focus | Feature IDs | Days |
-|--|--|--|--|
-| **S0** | Bootstrap (delete old, init preset) | F-042 | 0.5 |
-| **S1** | Foundation (tokens, primitives, shell) | F-043 | 3 |
-| **S2** | Controls + feedback | F-044 | 3 |
-| **S3** | Data display + Overview | F-045 | 3 |
-| **S4** | Navigation + palette + popups | F-046 | 3 |
-| **S5** | Kanban (the centerpiece) | F-047 | 4 |
-| **S6** | Goals + Agents | F-048 | 3 |
-| **S7** | Activity + Memory + Libraries | F-049 | 3 |
-| **S8** | Settings (16 sections) | F-050 | 3 |
-| **S9** | Polish + verification | F-051 | 2.5 |
-
-Total: **28 working days** ≈ **5.5 calendar weeks**.
-
-### Feature ID assignments
-
-`F-042` through `F-051` are reserved for the v8 sprint. `F-040`
-(F-040 redesign) and `F-041` (mobile UI pass) are reset to
-`not_started` and treated as historical context — their evidence
-is preserved in `docs/decisions/DEC-026-v8-dashboard-rewrite.md`
-but they do not count toward VCR.
-
-### Sprint contracts
-
-Each sprint starts with a sprint contract template (see
-`templates/sprint-contract.md`). The contract includes:
-- Scope (which files, which features)
-- Definition of Done (L09 layers 1+2+3)
-- Exclusions (what is *not* in scope)
-- Risks + mitigations
-- Reviewer (Forseti)
-
-### WIP=1 rule
-
-Per CLAUDE.md, only one feature active at a time. Each sprint ships
-one feature (`F-NNN`) end-to-end. We do **not** ship partial
-features; the gate is the gate.
-
----
-
-## 15 · Testing strategy
-
-### 15.1 Unit (vitest)
-
-Every component in `ui/` has a colocated `.test.tsx`. Patterns:
-- AAA (Arrange / Act / Assert).
-- `@testing-library/react` for rendering + queries.
-- `userEvent` (not `fireEvent`) for interactions.
-- `vitest-axe` for a11y assertions.
-- One snapshot per visual state (default, hover, focus, disabled,
-  loading, error).
-- Aim: 80%+ coverage per component file.
-
-### 15.2 Integration (vitest)
-
-Per-view integration tests render the full view against a mocked
-MSW server. Cover:
-- Initial load → first paint
-- User action → optimistic update → server confirm
-- User action → server error → revert + toast
-- WS event → cache invalidation → re-render
-
-### 15.3 E2E (playwright)
-
-`tests/e2e/` covers the critical user flows:
-- `smoke.spec.ts` — boot the app, land on Overview, navigate to
-  every route, no console errors.
-- `keyboard.spec.ts` — walk through every interactive element
-  using only Tab + Enter + arrow keys. Cmd+K, Shift+F10, Esc.
-- `visual.spec.ts` — screenshot diff at 1440 / 1100 / 768 / 390.
-- `kanban.spec.ts` — drag a card across columns, verify URL state,
-  verify the move persists after reload.
-- `settings.spec.ts` — change a setting, verify auto-save, verify
-  Cmd+K shows it.
-
-### 15.4 Accessibility (axe-core)
-
-`tests/a11y/` runs axe-core against every route. CI fails if any
-page has a critical violation. Manual screen-reader pass on Tasks,
-Goals, Settings, and Command Palette before each release.
-
-### 15.5 Visual regression (playwright visual)
-
-Screenshot diff against committed baselines. Baseline PR is
-generated automatically; reviewer approves deltas before merge.
-
-### 15.6 Performance
-
-Lighthouse runs in CI on `/tasks` with seeded data. Targets:
-- LCP < 1.5s
-- TBT < 200ms
-- CLS < 0.05
-- Performance score ≥ 90
-
-### 15.7 Banned-trope scan
-
-`scripts/check-design-tropes.sh` greps the codebase for the §12
-DESIGN banned patterns. Runs on every PR; CI fails on hit.
-
----
-
-## 16 · Integration with Bizar harness
-
-### 16.1 MCP tools (no changes)
-
-v8 consumes the same 22+ MCP tools that v7 did. No new tools.
-
-### 16.2 Plugin shim
-
-The dashboard never imports from `plugins/bizar/`. Per CLAUDE.md
-L10: "Skill must not import from `bizar-dash/` (cross-layer)."
-The reverse is also true — dashboard imports nothing from the
-plugin layer.
-
-### 16.3 Data flow
-
-```
-┌─────────────────┐    REST + WS    ┌──────────────────┐
-│  bizar-dash     │◄──────────────►│  bizar-dash      │
-│  src/web/       │                 │  src/server/     │
-│  (React SPA)    │                 │  (Express + WS)  │
-└─────────────────┘                 └──────────────────┘
-                                            │
-                                            ▼
-                                   ┌──────────────────┐
-                                   │  plugins/bizar   │
-                                   │  (MCP server)    │
-                                   └──────────────────┘
-                                            │
-                                            ▼
-                                   ┌──────────────────┐
-                                   │  packages/sdk    │
-                                   │  (Claude Code    │
-                                   │   Agent SDK)     │
-                                   └──────────────────┘
-```
-
-### 16.4 Build pipeline
-
-- `pnpm dev` — Vite dev server on `:5173`, proxied to `node
-  src/server/main.mjs` on `:8787` for REST + WS.
-- `pnpm build` — Vite production build → `dist/`.
-- `pnpm preview` — serve `dist/` + `src/server/`.
-- `make dashboard-dev` — orchestrator target that runs both in
-  watch mode.
-
-### 16.5 CI gates
-
-- `pnpm typecheck` — TypeScript strict, 0 errors.
-- `pnpm test` — vitest, all unit + integration.
-- `pnpm e2e` — playwright smoke + keyboard.
-- `pnpm check:design-tropes` — banned patterns.
-- `pnpm check:a11y` — axe-core.
-- `pnpm check:visual` — screenshot diff (advisory, manual approve).
-- `pnpm check:arch` — architectural rules (skill/dashboard/SDK
-  boundaries).
-- `make check` — full pipeline; existing in CLAUDE.md.
-
-### 16.6 Release
-
-- v8.0 ships when all 10 sprints (F-042..F-051) are passing.
-- v8.0.1+ is patch-only on v8.0; no new features until v8.1.
-- The `*.v7-bak` files are deleted at v8.0 release.
-
----
-
-## 17 · Risks & open questions
-
-| # | Risk | Likelihood | Impact | Mitigation |
-|--|--|--|--|--|
-| R-01 | shadcn preset `b7kBsBkh7b` is unverified / doesn't resolve as expected | Med | High | Appendix A of DESIGN.md documents the fallback: override `components.json`, run `shadcn add` for each missing primitive. The plan still holds; §3 is the contract. |
-| R-02 | TanStack Router file-based routing is incompatible with the existing Vite build | Low | Med | Sprint 0 verifies routing setup before committing. Code-based routing works as fallback. |
-| R-03 | dnd-kit keyboard sensors don't cover all kanban interactions | Med | Med | Sprint 5 includes a manual keyboard walkthrough; we write a custom keyboard sensor if needed. |
-| R-04 | The existing REST endpoints don't match v8's data shape | Low | High | Sprint 0 includes an endpoint audit. Where shapes diverge, v8 adapts (Zod parse + map) without changing the server. |
-| R-05 | Performance regression on `/tasks` with 1000+ tasks | Med | Med | Virtualization via TanStack Virtual; pagination on the list view; lazy-render off-screen columns. Lighthouse gate in §15.6 catches it. |
-| R-06 | Custom-popup right-click interferes with browser gestures | Low | Low | `oncontextmenu` returns `false` only on our interactive surfaces. Long-press on touch (650ms) opens the same menu. |
-| R-07 | Settings schema sprawl — 16 sections × N fields each | High | Med | Settings schemas are Zod-validated end-to-end. Each section is its own Zod schema. Cmd+K surfaces them. We resist adding new sections unless justified. |
-| R-08 | v7 mobile users break (no MobileApp.tsx) | Med | Med | The new design is responsive web; mobile users get the same responsive UI at 390px. Communicate the change in v8 release notes. |
-| R-09 | Real-time updates overwhelm the kanban with WS events | Low | Med | WS events invalidate query keys; React Query batches invalidations. No re-render storm because TanStack Query debounces identical fetches. |
-| R-10 | Single-engineer timeline (5–6 weeks) slips | Med | Med | Each sprint ships a working app (compiles + boots + 1 view). If Sprint 5 (kanban) slips, v8.0 ships without goals/agents (deferred to v8.1). |
-
-### Open questions for the operator
-
-1. **shadcn preset ID.** Confirm `b7kBsBkh7b` is the intended
-   preset; if not, provide the correct one and we re-run Sprint 0.
-2. **Mobile.** Confirm mobile-web responsive (no native app) is the
-   right scope for v8.
-3. **Settings depth.** Are 16 sections the right level? Some teams
-   prefer fewer, deeper sections; others prefer more, flatter ones.
-4. **Routing library.** Confirm TanStack Router (vs. React Router).
-5. **Drag-and-drop library.** Confirm dnd-kit (vs. Pragmatic drag
-   and drop, the newer alternative).
-6. **Multi-workspace UI.** Confirm single-workspace for v8 (vs.
-   switching UI in the topbar).
-
----
-
-**End of PLAN.md — v8.0.0**