# Nexus Codebase Map

> **Purpose:** fast orientation for sessions that don't have the full conversation history loaded. This file is factual — generated by scanning the tree, not by reading intent docs. If something here contradicts a plan or spec, trust this file over the plans.
>
> **Branch:** `nexus/design-system-migration`
> **Last updated:** 2026-04-11 after Wave 3A completion. Phase 16a is running in the background at the time of this snapshot; see §7 and §8 for which files are expected to move.

---

## 1. Directory tree (`ui/src/`, 2 levels)

```
ui/src/
├── adapters/            — one subdir per AI adapter runtime (claude-local,
│                          codex-local, cursor, gemini-local, hermes-local,
│                          http, openclaw-gateway, opencode-local, pi-local,
│                          process). Mostly glue between the UI and backend
│                          provider clients.
├── api/                 — typed client wrappers, one file per backend surface
│                          (see §5 for the full list)
├── components/
│   ├── assistant/       — Phase 9 + 12 Assistant-route widgets
│   ├── frame/           — Phase 8 + 14 global chrome (icon rail, top strip,
│                          ⌘K button, global mic, mobile tab bar)
│   ├── onboarding/      — first-run wizard steps
│   ├── projects/        — Phase 11 hero-stat card, tab strip, per-project tabs
│   │   └── tabs/        — Phase 11 Overview + 5 TabPlaceholder tabs + Issues wire
│   ├── settings/        — Phase 13 single-column section cards
│   ├── studio/          — Phase 10 workshop grid + prompt bar + classifier
│   ├── transcript/      — run transcript viewer used by UX test lab
│   └── ui/              — shadcn-ish primitives (Button, Tooltip, Dialog, etc.)
├── context/             — React contexts (see §4)
├── fixtures/            — test fixtures
├── hooks/                — custom hooks (see §4)
├── lib/                 — pure utilities (router wrapper, company-selection,
│                          queryKeys, utils, instance-settings, etc.)
├── pages/               — route-level page components (see §3)
├── plugins/             — plugin host SDK internals
└── types/               — cross-cutting TypeScript types
```

**File sizes for orientation:**
- Largest page: `AgentDetail.tsx` (4104 L), `Inbox.tsx` (2028 L), `IssueDetail.tsx` (1696 L), `DesignGuide.tsx` (1532 L), `CompanyImport.tsx` (1355 L). These are legacy Paperclip pages.
- Largest Nexus-era pages: `ProjectDetail.tsx` (1006 L — Phase 11), `PersonalAssistant.tsx` (379 L — Phase 9), `StudioWorkshopDetail.tsx` (362 L — Phase 10), `Projects.tsx` (315 L — Phase 11 + Wave 2.5).
- Layout shell: `Layout.tsx` ~240 L (down from 510 L pre-Phase-8).

---

## 2. Route map (from `ui/src/App.tsx` `boardRoutes()`)

All routes are mounted under a company-prefixed root (`/:companyPrefix/*`) except `/instance/*` which is global.

| Route | Component | Status | Notes |
|---|---|---|---|
| (index) | `<Navigate to="dashboard">` | LEGACY | Phase 16b will redirect to `/assistant` |
| `dashboard` | `Dashboard` | LEGACY | Kill in Phase 16b — Assistant conversational home replaces it |
| `onboarding` | `OnboardingRoutePage` | ACTIVE | First-run wizard |
| `companies` | `Companies` | LEGACY | Single-workspace; kill in Phase 16b |
| `company/settings` | `CompanySettings` | LEGACY | Overlaps with instance settings — Phase 16b decision |
| `company/export/*` | `CompanyExport` | ACTIVE | Still useful for workspace export |
| `company/import` | `CompanyImport` | ACTIVE | Still useful for workspace import |
| `skills/*` | `CompanySkills` | ACTIVE | Skill Aggregator — linked from Settings §Skills |
| `settings` | `LegacySettingsRedirect` → `/instance/settings/general` | REDIRECT | Phase 13 redirect |
| `settings/*` | `LegacySettingsRedirect` | REDIRECT | Phase 13 |
| `plugins/:pluginId` | `PluginPage` | ACTIVE | Plugin system |
| `org` | `OrgChart` | LEGACY | Demoted — Phase 16b kill |
| `agents` → `/agents/all` | Redirect | LEGACY | Phase 16b: redirect to `/projects` |
| `agents/all`, `/active`, `/paused`, `/error` | `Agents` | LEGACY | Per-project tab now; Phase 16b kill |
| `agents/new` | `NewAgent` | ACTIVE | Per-project agent creation |
| `agents/:agentId`, `/:tab`, `/runs/:runId` | `AgentDetail` | ACTIVE | Agent detail still needed |
| `projects` | `Projects` | **ACTIVE (Phase 11 + Wave 2.5)** | Hero-stat card grid |
| `projects/:projectId` | `ProjectDetail` | **ACTIVE (Phase 11)** | Default sub-route |
| `projects/:projectId/overview` | `ProjectDetail` | **ACTIVE** | Phase 11 Overview tab |
| `projects/:projectId/issues` | `ProjectDetail` | **ACTIVE** | Phase 11 Issues tab (real wire) |
| `projects/:projectId/issues/:filter` | `ProjectDetail` | **ACTIVE** | Filter sub-route |
| `projects/:projectId/agents` | `ProjectDetail` | **ACTIVE (placeholder)** | Phase 11 TabPlaceholder |
| `projects/:projectId/gates` | `ProjectDetail` | **ACTIVE (placeholder)** | Phase 11 TabPlaceholder |
| `projects/:projectId/costs` | `ProjectDetail` | **ACTIVE (placeholder)** | Phase 11 TabPlaceholder |
| `projects/:projectId/activity` | `ProjectDetail` | **ACTIVE (placeholder)** | Phase 11 TabPlaceholder |
| `projects/:projectId/org` | `ProjectDetail` | **ACTIVE (placeholder)** | Phase 11 TabPlaceholder, hidden for single-agent |
| `projects/:projectId/configuration` | `ProjectDetail` | LEGACY preserved | Phase 11 kept for backwards compat |
| `projects/:projectId/budget` | `ProjectDetail` | LEGACY preserved | Phase 11 kept for backwards compat |
| `issues`, `issues/all`, `/active`, `/backlog`, `/done`, `/recent` | `Issues` / redirects | LEGACY | Phase 16b kill — redirect to `/projects` |
| `issues/:issueId` | `IssueDetail` | ACTIVE | Issue detail still needed |
| `routines`, `routines/:routineId` | `Routines` / `RoutineDetail` | LEGACY | Phase 13 linked from Settings; Phase 16b kill top-level |
| `execution-workspaces/:workspaceId` | `ExecutionWorkspaceDetail` | ACTIVE | Workspace detail |
| `goals`, `goals/:goalId` | `Goals` / `GoalDetail` | LEGACY | Phase 16b kill — folded into Overview milestones |
| `approvals`, `/pending`, `/all`, `/:approvalId` | `Approvals` / `ApprovalDetail` | LEGACY | Phase 11 demoted → per-project Gates tab; Phase 16b kill top-level |
| `costs` | `Costs` | LEGACY | Phase 16b kill |
| `activity` | `Activity` | LEGACY | Phase 16b kill |
| `inbox`, `/mine`, `/recent`, `/unread`, `/all`, `/new` | `Inbox` / redirects | LEGACY | Phase 16b kill — replaced by Assistant dot + ⌘K |
| `assistant` | `PersonalAssistant` | **ACTIVE (Phase 9 + 12)** | Default landing |
| `assistant/:conversationId` | `PersonalAssistant` | **ACTIVE** | Conversation-specific |
| `content-studio` | `ContentStudio` | **ACTIVE (Phase 10 + Wave 2.5)** | Workshop grid |
| `content-studio/:workshopSlug` | `ContentStudio` | **ACTIVE** | Phase 10 workshop detail |
| `convert`, `/:sourceFormat`, `/:sourceFormat/:targetFormat` | `ConvertPage` | LEGACY preserved | Kept for bookmark compat; Studio has Convert workshop |
| `design-guide` | `DesignGuide` | ACTIVE | Internal design reference |
| `tests/ux/runs` | `RunTranscriptUxLab` | ACTIVE | UX test lab |
| `:pluginRoutePath` | `PluginPage` | ACTIVE | Plugin runtime |
| `*` | `NotFoundPage` | ACTIVE | 404 |
| `/instance/settings/general` | `InstanceGeneralSettings` | **ACTIVE (Phase 13)** | Single-column settings |
| `/instance/settings/heartbeats` → `/general` | Redirect | REDIRECT | Phase 13 collapsed |
| `/instance/settings/experimental` → `/general` | Redirect | REDIRECT | Phase 13 collapsed |
| `/instance/settings/plugins`, `/:pluginId` | `PluginManager` / `PluginSettings` | ACTIVE | Plugin system keeps its own settings sub-tree |

**Unprefixed redirect routes** (catch direct-entered non-company-prefixed URLs): every top-level route has a matching `UnprefixedBoardRedirect` variant. Phase 13 also added unprefixed redirect routes for the new project sub-routes.

---

## 3. Component inventory (frame + pages)

### `ui/src/components/frame/` (Phase 8 + 14 + 15)

| File | Lines* | Phase | Status | Purpose |
|---|---|---|---|---|
| `IconRail.tsx` | ~180 | 8 | ACTIVE | 56px left rail, 4 destinations, volt active state, Phase 11 gate-indicator dot |
| `IconRail.test.tsx` | ~200 | 8 | ACTIVE | 9 tests including gate-indicator dot |
| `ModeBreadcrumb.tsx` | ~110 | 8 | ACTIVE | Pure `deriveBreadcrumbSegments` + render component |
| `ModeBreadcrumb.test.tsx` | ~120 | 8 | ACTIVE | 22 tests (parameterized + rendered) |
| `CmdKButton.tsx` | ~30 | 8/14 | ACTIVE | Phase 14 rewired from synthetic keydown shim to `useCommandPalette().setOpen(true)` |
| `CmdKButton.test.tsx` | ~60 | 8/14 | ACTIVE | 2 tests + context consumer |
| `GlobalMicButton.tsx` | ~80 | 8/14 | ACTIVE | Phase 14 rewired from visual-only scaffold to `useVoice()` consumer |
| `GlobalMicButton.test.tsx` | ~80 | 8/14 | ACTIVE | 3 tests + context consumer |
| `TopStrip.tsx` | ~30 | 8 | ACTIVE | 48px sticky, composes breadcrumb + cmdK + mic |
| `TopStrip.test.tsx` | ~110 | 8 | ACTIVE | 4 tests; Wave 3A integration pass added context mocks |
| `MobileTabBar.tsx` | ~100 | 15 | ACTIVE | 56px bottom bar, 4 destinations, scroll-hide via `visible` prop |
| `MobileTabBar.test.tsx` | ~150 | 15 | ACTIVE | 12 tests |

*Lines are approximate; exact counts drift with commits.

**Pending (Phase 16a):** `destinations.ts` to consolidate the 4-destination config shared between `IconRail.tsx` and `MobileTabBar.tsx`.

### `ui/src/components/assistant/` (Phase 9 + 12)

| File | Phase | Status | Purpose |
|---|---|---|---|
| `AssistantInputBar.tsx` / `.test.tsx` | 9 | ACTIVE | Waveform + text input composite, anchored at chat bottom |
| `ActionStrip.tsx` / `.test.tsx` | 9/12 | ACTIVE | Promote / Attach / Memory / History 4-button row |
| `AssistantHomeGreeting.tsx` / `.test.tsx` | 9 | ACTIVE | Synthesized assistant-turn greeting when no active conversation |
| `HistorySheet.tsx` / `.test.tsx` | 9/15 | ACTIVE | Left slide-over (desktop), full-screen (mobile) |
| `MemorySheet.tsx` / `.test.tsx` | 9/15 | ACTIVE | Right slide-over (desktop), full-screen (mobile), wired to `assistantMemoryApi` |
| `BrainstormerPanel.tsx` / `.test.tsx` | 12 | ACTIVE | Goal / Acceptance / Gates / Engineer template form |
| `PromoteTransition.tsx` / `.test.tsx` | 12/15 | ACTIVE | 700ms compress-and-rise CSS animation + mobile takeover variant |

### `ui/src/components/studio/` (Phase 10 + Wave 2.5)

| File | Phase | Status | Purpose |
|---|---|---|---|
| `workshops.ts` / `.test.ts` | 10/2.5 | ACTIVE | 9-workshop data (Presentations added Wave 2.5) |
| `classifyIntent.ts` / `.test.ts` | 10/2.5 | ACTIVE | Keyword-based intent → workshop classifier; 38 test cases including pitch deck / slide deck patterns |
| `WorkshopCard.tsx` / `.test.tsx` | 10 | ACTIVE | Single card for the grid |
| `WorkshopGrid.tsx` / `.test.tsx` | 10 | ACTIVE | Responsive 3/2/1-column grid |
| `StudioPromptBar.tsx` / `.test.tsx` | 10 | ACTIVE | Freeform input → classifier → navigate or fall through to Assistant |

### `ui/src/components/projects/` (Phase 11)

| File | Status | Purpose |
|---|---|---|
| `ProjectCard.tsx` / `.test.tsx` | ACTIVE | Hero-stat card with 72px volt percentage |
| `BuilderTabStrip.tsx` / `.test.tsx` | ACTIVE | 7-tab strip with volt active underline, Org hidden for single-agent, horizontal scroll on mobile |
| `tabs/OverviewTab.tsx` / `.test.tsx` | ACTIVE | Phase 11 Overview with milestone checklist + Origin chat + Activity card |
| `tabs/IssuesTab.tsx` | ACTIVE | Thin wrapper around existing `IssuesList` with `projectId` prop (only tab with real wire) |
| `tabs/AgentsTab.tsx` | PLACEHOLDER | Phase 11 `TabPlaceholder` — see §7 |
| `tabs/GatesTab.tsx` | PLACEHOLDER | Phase 11 `TabPlaceholder` |
| `tabs/CostsTab.tsx` | PLACEHOLDER | Phase 11 `TabPlaceholder` |
| `tabs/ActivityTab.tsx` | PLACEHOLDER | Phase 11 `TabPlaceholder` |
| `tabs/OrgTab.tsx` | PLACEHOLDER | Phase 11 `TabPlaceholder` |
| `tabs/TabPlaceholder.tsx` | ACTIVE | Shared "PHASE 11 DATA GAP" card with per-tab rationale |

### `ui/src/components/settings/` (Phase 13)

| File | Status | Purpose |
|---|---|---|
| `SettingsSection.tsx` / `.test.tsx` | ACTIVE | Shared section card shell |
| `WorkspaceSection.tsx` / `.test.tsx` | ACTIVE | Root dir, theme, re-run onboarding, experimental toggles folded in |
| `LocalAISection.tsx` / `.test.tsx` | ACTIVE | Hermes / Whisper / Piper config |
| `CloudProvidersSection.tsx` / `.test.tsx` | ACTIVE | API keys (masked), Puter.js status |
| `SkillsSection.tsx` / `.test.tsx` | ACTIVE | Compact summary + link-out to Skill Aggregator |
| `RoutinesSection.tsx` / `.test.tsx` | ACTIVE | Compact read-only list + link-out to `/routines` |
| `TelegramSection.tsx` / `.test.tsx` | ACTIVE | Bot token, allowed chat IDs |
| `AboutSection.tsx` / `.test.tsx` | ACTIVE | Version, fork info, MIT |
| `DangerZoneSection.tsx` / `.test.tsx` | PLACEHOLDER | Disabled buttons — no server endpoints exist yet |

### `ui/src/pages/` (key files)

| File | Phase | Status |
|---|---|---|
| `PersonalAssistant.tsx` | 9/12/14 | ACTIVE — canonical Assistant |
| `ContentStudio.tsx` | 10 | ACTIVE — workshop grid host |
| `StudioWorkshopDetail.tsx` | 10 | ACTIVE — per-workshop detail view |
| `Projects.tsx` | 11/2.5 | ACTIVE — hero-stat list with derivatives |
| `ProjectDetail.tsx` | 11 | ACTIVE — Builder tabs + legacy `configuration`/`budget` preserved |
| `InstanceGeneralSettings.tsx` | 13 | ACTIVE — single-column settings |
| `Dashboard.tsx` | — | LEGACY — Phase 16b kill |
| `Companies.tsx` | — | LEGACY — Phase 16b kill (single workspace) |
| `Issues.tsx`, `Agents.tsx`, `Approvals.tsx`, `Costs.tsx`, `Activity.tsx`, `OrgChart.tsx`, `Goals.tsx`, `Inbox.tsx`, `Routines.tsx` | — | LEGACY — Phase 16b kill/redirect |
| `ConvertPage.tsx` | — | LEGACY preserved — `/convert` route kept for compat |
| `AgentDetail.tsx`, `IssueDetail.tsx`, `ApprovalDetail.tsx`, `GoalDetail.tsx`, `RoutineDetail.tsx` | — | ACTIVE — detail pages still needed |

---

## 4. Context + hook map

### Contexts (`ui/src/context/`)

| Context | Provides | Main consumers |
|---|---|---|
| `CompanyContext` | `companies`, `selectedCompany`, `selectedCompanyId`, `setSelectedCompanyId` | Everything — it's the workspace selector |
| `DialogContext` | `openNewIssue`, `openNewProject`, `openNewGoal`, `openNewAgent`, `openOnboarding` | Layout, IconRail (nexus mark), Settings sections |
| `ThemeContext` | `theme` (`"dark"` \| `"light"`), `toggleTheme` | Settings Workspace section |
| `ToastContext` | `pushToast` | Across the app |
| `SidebarContext` | `isMobile`, legacy `sidebarOpen`/`setSidebarOpen` | Layout (reads `isMobile`) |
| `PanelContext` | Legacy `panelVisible` state | Unused post-Phase-8 (candidate for deletion) |
| `GeneralSettingsContext` | `keyboardShortcutsEnabled` | Keyboard shortcut hook |
| `BreadcrumbContext` | Legacy `breadcrumbs` state | Projects page calls `setBreadcrumbs` for BreadcrumbBar (now dead). Candidate to delete or repurpose. |
| **`VoiceContext`** (Phase 14) | `state`, `mediaStream`, `hasQueuedVoice`, `startListening`, `stopListening`, `drainQueue` | `GlobalMicButton`, `ChatInput`, `PersonalAssistant` queue drain |
| **`CommandPaletteContext`** (Phase 14) | `open`, `setOpen`, `toggle` + global Cmd+K listener | `CmdKButton`, `CommandPalette`, `Layout.onSearch` |
| `LiveUpdatesProvider` | SSE stream subscriptions | Chat, activity, project state |
| **`ChatPanelContext`** | Legacy `chatOpen`, `activeConversationId`, `scrollToMessageId` | `ChatMessageList` reads this — **Phase 16a migrating it off** |

### Hooks (`ui/src/hooks/`, 39 total)

Key Nexus-era hooks:
- `useAssistantHomeStatus` (Phase 9) — composes projects/agents/gates/activity for the home greeting
- `useGateIndicator` (Phase 11) — pending gate count for the IconRail volt dot
- `usePromoteToProject` (Phase 12) — state machine for the promote animation
- `useStreamingChat` (v1.3) — SSE chat stream
- `useChatConversations` / `useChatMessages` / `useChatSearch` / `useChatBookmarks` / `useChatFileUpload` (v1.3)
- `useVoiceMode` / `useVadRecorder` / `usePiperTts` (v1.6) — voice primitives; `useVadRecorder` is now orphaned post-Phase-14 (Phase 16a deletes)
- `useBrainstormerDefault` (v1.3) — brainstormer workflow default
- `useHardwareInfo` (v1.5) — hardware probe for onboarding
- `useInboxBadge` — legacy, still consumed by pre-Phase-15 code
- `useKeyboardShortcuts` — wired to `CommandPaletteContext` via Phase 14
- `useMediaQuery` — single-breakpoint helper (768px)
- `useNexusMode` — mode detection (Assistant vs Project Builder)
- `useOfflineQueue`, `useOnlineStatus`, `useInstallPrompt` (v1.3 PWA)
- `useStreamingChat`, `useContentJob` (v1.7 content gen)

---

## 5. API surface (`ui/src/api/`, 34 files)

```
access, activity, agents, approvals, assets, assistantMemory (Phase 9),
auth, budgets, chat, client (HTTP base), companies, companySkills,
contentJobs, convert, costs, dashboard, execution-workspaces, goals,
hardware, health, heartbeats, index (re-exports), instanceSettings,
issues, ollama, plugins, projects, push, puter-proxy, routines,
secrets, sidebarBadges, skillGroups, skillRegistry, telegram,
transcribe, (+ more)
```

**Phase 9 Assistant integration added:** `assistantMemoryApi` wired to MemorySheet — shape: `{ companyId, facts: string[], updatedAt }`, methods: `getMemory`, `appendFact`, `clearMemory`.

**Phase 14 voice integration:** reuses `/api/transcribe` from v1.6, no new endpoints.

**Phase 11 derivatives:** `Projects.tsx` composes `projectsApi.list` + `issuesApi.list` + `approvalsApi.list(_, "pending")` to derive per-project progress % from `closed_issues / total_issues` (see §7 for the TODO annotations).

---

## 6. CSS token map (`ui/src/index.css`, 951 lines)

### Dark mode (`.dark` — 158px from line 147)
```
--background     #000000       (pure black)
--foreground     #ffffff
--card           #141414       (near-black input fill)
--popover        #141414
--primary        #faff69       (NEON VOLT — the brand)
--primary-foreground #151515
--secondary      #166534       (forest green)
--secondary-foreground #ffffff
--muted          #141414
--muted-foreground #a0a0a0    (silver)
--accent         #141414
--accent-foreground #faff69
--destructive    #ef4444
--warning        #f59e0b
--success        #166534
--border         rgba(65, 65, 65, 0.8)   (charcoal — workhorse)
--input          #141414
--ring           #faff69
--chart-1..5     volt, forest, silver, pale-yellow, red
--sidebar        #000000
```

### Light mode (`:root` — from line 87)
```
--background     #fafafa       (near-white)
--foreground     #0a0a0a
--card           #ffffff
--primary        #166534       (forest — volt downranked per MIGRATION-PLAN §5)
--primary-foreground #ffffff
--secondary      #f1f5f1
--muted-foreground #6b6b6b
--destructive    #dc2626
--warning        #b45309
--border         rgba(20, 20, 20, 0.12)
--ring           #166534
--volt           #4f5100       (dark olive — light-mode volt downrank)
```

### Direct brand references (in both modes)
```
--volt / --volt-pale / --volt-border
--forest / --forest-dark
--near-black / --hover-gray / --silver
--charcoal-border / --charcoal-divider
```

### Chart role palette exception
Dark mode reserves `--chart-role-1` through `--chart-role-5` as 5 muted hues (olive, teal, violet, amber, gray) for agent-role differentiation. Documented as a deliberate exception to DESIGN.md's "single chromatic accent" rule.

### `@theme inline` block (lines 25-85)
Maps CSS vars to Tailwind `--color-*` tokens so `text-primary`, `bg-card`, `border-border`, etc. all resolve correctly.

---

## 7. Known issues (grep for TODO / FIXME / PHASE 11 DATA GAP / placeholder / TabPlaceholder)

### Phase 11.5 data gaps — tracked for backlog plan at `docs/plans/2026-04-11-nexus-phase-11-5-per-project-scoping.md`

| File:line | What's missing |
|---|---|
| `Projects.tsx:20` | `// Each proxy is marked with a // TODO(phase-11.5) comment and will be replaced by a real backend field when it lands` (comment block documenting the derivative strategy) |
| `Projects.tsx:49` | `TODO(phase-11.5): replace with server-side aggregates on the Project record` |
| `Projects.tsx:171` | `TODO(phase-11.5): replace with server-side aggregates on Project record` |
| `Projects.tsx:292` | `TODO(phase-11.5): replace with real milestoneProgress from the Project record` |
| `Projects.tsx:299` | `TODO(phase-11.5): replace with the real next-gate slot on the Project record` |

### Phase 11 per-project tab placeholders (5 tabs)

Every tab except `IssuesTab` renders `TabPlaceholder` with a "PHASE 11 DATA GAP" rationale. Files: `AgentsTab.tsx`, `GatesTab.tsx`, `CostsTab.tsx`, `ActivityTab.tsx`, `OrgTab.tsx`. Each explains the specific gap (e.g., "Agent type has no projectId field"). See Phase 11.5 plan for fix tickets.

### Other markers in the tree

~40 files match `TODO|FIXME|placeholder`. Most are normal in-code TODOs on legacy Paperclip pages (Inbox, CompanySettings, AgentDetail) that are slated for Phase 16b deletion. The Phase 11.5 tags are the high-signal ones.

### Pre-existing typescript errors (not Nexus-overhaul-related, but present)

Unrelated to the design system migration, these have been flagged across review cycles:
- `AgentConfigForm.tsx:351` — stale API ref
- `OnboardingSummaryStep.test.tsx` — missing `onRootDirChange` prop in ~7 test cases
- `ui/command.tsx:57` — bigint ReactNode type
- `useKeyboardShortcuts.ts:25` — FIXED in Phase 14 (was the missing-onSearch destructure)
- `useVadRecorder.ts:58` — stale Silero VAD options (file slated for Phase 16a deletion)
- `PersonalAssistant.tsx:231-234` — FIXED in Phase 9 (was stale toast tones)

---

## 8. Migration status (verified against `git log --oneline`)

### MIGRATION-PLAN.md phases 1–7 (visual repaint)

| Phase | Status | Key commits |
|---|---|---|
| 1 — Tokens + Inter font | **DONE** | `e49144a4` feat(nexus): design system phase 1 tokens and inter font |
| 2 — Status + role color dictionaries | **DONE** | `4b8f8178` feat(nexus): design system phase 2 status and role color dictionaries |
| 3 — Raw utility sweep | **DONE** | `3a41ec7b` feat(nexus): design system phase 3 raw utility sweep |
| 4 — Typography + radius audit | **PENDING** | No commits yet |
| 5 — ThemePreviewPanel rewrite | **PENDING** | No commits yet |
| 6 — hljs syntax highlighting | **PENDING** | No commits yet |
| 7 — Visual QA pass | **PENDING** | No commits yet |

### Layout overhaul phases 8–16 (structural)

| Phase | Wave | Status | Commit count / notes |
|---|---|---|---|
| 8 — Frame skeleton | 1 | **DONE** | 10 commits (`332ed47b`…`2dbf2811`) |
| 9 — Assistant mode | 2 | **DONE** | 8 commits (`397e12a8`…`e43d5ec2`) |
| 10 — Studio mode | 2 | **DONE** | 5 commits (`533490f1`…`cd6c172d`), Presentations added as 9th workshop in Wave 2.5 |
| 11 — Projects + Builder mode | 2 | **DONE** | 7 commits (`6010a105`…`1e855657`), 5 tabs shipped as TabPlaceholder — see Phase 11.5 backlog |
| 12 — Promote-to-project transition | 3A | **DONE** | 3 commits (`d2d41886`, `70698b9e`, `b2775275`) + 1 attribution artifact in Phase 13's `f41690ff` |
| 13 — Settings consolidation | 3A | **DONE** | 6 commits (`7aa98d38`…`1a0d611c`) |
| 14 — Voice + ⌘K globalization | 3A | **DONE** | 6 commits (`14ecbf00`…`9b772aa1`) |
| 15 — Mobile parity | 3A | **DONE** | 1 commit (`4623c8ae`) |
| **Wave 2 integration** | — | **DONE** | `1b7e3d44` (routing + IconRail gate indicator) |
| **Wave 2.5** | — | **DONE** | `428f0336` (Presentations + ProjectCard derivatives + spec 8→9) |
| **Wave 3A integration** | — | **DONE** | `fb76b5ee` (TopStrip test provider mocks + PromoteTransition mobile variant + Layout onSearch cleanup) |
| 16a — Dead chrome cleanup | 3B | **IN PROGRESS** | Subagent running in background at time of this snapshot |
| 16b — Vocabulary sweep + route cleanup | 3B | **PENDING** | Blocked on 16a |

### Non-overhaul commits mixed in

- `137bd3d0` fix(nexus): unblank assistant page on piper-tts import error (fixed a namespace import bug surfaced at session start)
- `43ca8d30` docs(nexus): layout overhaul spec (spec commit itself)
- `2a42f4ab` docs(nexus): phase 8 frame skeleton implementation plan
- `3f0d3377` docs(nexus): wave 2 implementation plans (phases 9, 10, 11)
- `87b45c73` docs(nexus): wave 3 plans (phases 12-16) + phase 11.5 backlog

### Plans committed but not yet executed

All five Wave 3 plans + Phase 11.5 backlog plan live at:
- `docs/plans/2026-04-11-nexus-phase-11-5-per-project-scoping.md` — backlog
- `docs/plans/2026-04-11-nexus-phase-12-promote-transition.md` — DONE
- `docs/plans/2026-04-11-nexus-phase-13-settings-consolidation.md` — DONE
- `docs/plans/2026-04-11-nexus-phase-14-voice-cmdk-globalization.md` — DONE
- `docs/plans/2026-04-11-nexus-phase-15-mobile.md` — DONE
- `docs/plans/2026-04-11-nexus-phase-16-cleanup.md` — IN PROGRESS as 16a, pending as 16b

The layout overhaul spec is at `docs/specs/2026-04-11-nexus-layout-overhaul.md`. It was amended post-Wave-2 to reflect the 8→9 workshop count (Presentations restoration).

---

## Appendix: Dead code files slated for deletion (pre-16a snapshot)

| File | Status | Reason |
|---|---|---|
| `ui/src/components/ChatPanel.tsx` | ALIVE | Phase 8 unmounted from Layout; Phase 16a deletes |
| `ui/src/context/ChatPanelContext.tsx` | ALIVE | Phase 16a deletes AFTER migrating ChatMessageList off it |
| `ui/src/components/Sidebar.tsx` | ALIVE | Phase 8 unmounted; Phase 16a deletes |
| `ui/src/components/BreadcrumbBar.tsx` | ALIVE | Phase 8 unmounted; Phase 16a deletes |
| `ui/src/components/PropertiesPanel.tsx` | ALIVE | Phase 8 unmounted; Phase 16a deletes |
| `ui/src/components/VoiceMicButton.tsx` | ALIVE | Phase 14 orphaned; Phase 16a deletes |
| `ui/src/hooks/useVadRecorder.ts` | ALIVE | Phase 14 orphaned; Phase 16a deletes |
| `ui/src/components/InstanceSidebar.tsx` | **DELETED** | Phase 13 deleted |
| `ui/src/components/MobileBottomNav.tsx` | **DELETED** | Phase 15 deleted |

Phase 16a is expected to move all 7 ALIVE entries to DELETED.