# 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 3B completion** (phases 16a and 16b DONE). Route map and component inventory rescanned against current `ui/src/App.tsx` and filesystem. 24 files deleted across 16a (7) + 16b (17). 294/294 tests passing.

---

## 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 (post-16b):**
- Largest remaining legacy pages: `AgentDetail.tsx` (4104 L), `IssueDetail.tsx` (1696 L), `DesignGuide.tsx` (1532 L), `CompanyImport.tsx` (1355 L). `Inbox.tsx` (2028 L) was deleted in 16b.
- 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()`, post-16b)

All routes mount under a company-prefixed root (`/:companyPrefix/*`) except `/instance/*` which is global. Rescanned 2026-04-11 after 16b.

| Route | Component | Status | Notes |
|---|---|---|---|
| (board index) | `<Navigate to="assistant">` | REDIRECT | Phase 16b — default landing is Assistant |
| `onboarding` | `OnboardingRoutePage` | ACTIVE | First-run wizard |
| `company/settings` | `CompanySettings` | ACTIVE | Workspace settings (kept — still different from instance settings) |
| `company/export/*` | `CompanyExport` | ACTIVE | Workspace export |
| `company/import` | `CompanyImport` | ACTIVE | Workspace import |
| `skills/*` | `CompanySkills` | ACTIVE | Skill Aggregator — linked from Settings §Skills |
| `settings`, `settings/*` | `LegacySettingsRedirect` → `/instance/settings/general` | REDIRECT | Phase 13 |
| `plugins/:pluginId` | `PluginPage` | ACTIVE | Plugin system |
| `agents`, `agents/all`, `/active`, `/paused`, `/error` | `<Navigate to="/projects">` | REDIRECT | Phase 16b — global list replaced by per-project Agents tab |
| `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` | `<Navigate to="/projects">` | REDIRECT | Phase 16b — global list replaced by per-project Issues tab |
| `issues/:issueId` | `IssueDetail` | ACTIVE | Issue detail still needed |
| `execution-workspaces/:workspaceId` | `ExecutionWorkspaceDetail` | ACTIVE | Workspace detail |
| `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` | `<Navigate to="content-studio/convert">` | REDIRECT | Phase 16b — folded into Studio |
| `design-guide` | `DesignGuide` | ACTIVE | Internal design reference |
| `tests/ux/runs` | `RunTranscriptUxLab` | ACTIVE | UX test lab |
| `:pluginRoutePath` | `PluginPage` | ACTIVE | Plugin runtime |
| `*` | `NotFoundPage` scope="board" | 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 |

### Deleted top-level routes (no longer mounted, post-16b)

`dashboard`, `companies`, `org`, `goals`, `goals/:goalId`, `costs`, `activity`, `inbox`, `inbox/*`, `approvals`, `approvals/*`, `routines`, `routines/:routineId`. All fall through to `NotFoundPage scope="board"`.

**Unprefixed redirect routes** (catch direct-entered non-company-prefixed URLs): `UnprefixedBoardRedirect` variants exist for `issues/:issueId`, `skills/*`, `settings`, `settings/*`, `agents/new`, `agents/:agentId`, `agents/:agentId/:tab`, `agents/:agentId/runs/:runId`, `projects`, `projects/:projectId`, `projects/:projectId/overview`, `projects/:projectId/issues`, `projects/:projectId/issues/:filter`, `projects/:projectId/agents`, `projects/:projectId/gates`, `projects/:projectId/costs`, `projects/:projectId/activity`, `projects/:projectId/org`, `projects/:projectId/configuration`, `tests/ux/runs`.

---

## 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.

**Post-16a:** `destinations.ts` consolidates the 4-destination config shared between `IconRail.tsx` and `MobileTabBar.tsx` (commit `a3102351`).

### `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, post-16b)

| 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 |
| `AgentDetail.tsx`, `IssueDetail.tsx` | — | ACTIVE — detail pages still needed |
| `NewAgent.tsx`, `ExecutionWorkspaceDetail.tsx` | — | ACTIVE |
| `CompanySettings.tsx`, `CompanyExport.tsx`, `CompanyImport.tsx`, `CompanySkills.tsx` | — | ACTIVE — workspace-level surfaces |
| `PluginManager.tsx`, `PluginSettings.tsx`, `PluginPage.tsx` | — | ACTIVE |
| `DesignGuide.tsx`, `RunTranscriptUxLab.tsx`, `NotFound.tsx` | — | ACTIVE |
| `Auth.tsx`, `BoardClaim.tsx`, `CliAuth.tsx`, `InviteLanding.tsx` | — | ACTIVE — auth flow |
| `Dashboard.tsx`, `Companies.tsx`, `Inbox.tsx`, `Inbox.test.tsx`, `Issues.tsx`, `Agents.tsx`, `Approvals.tsx`, `ApprovalDetail.tsx`, `Costs.tsx`, `Activity.tsx`, `OrgChart.tsx`, `Goals.tsx`, `GoalDetail.tsx`, `Routines.tsx`, `RoutineDetail.tsx`, `ConvertPage.tsx` | — | **DELETED** — Phase 16b |

---

## 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 |

### 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` / `usePiperTts` (v1.6) — voice primitives; `useVadRecorder` deleted in Phase 16a
- `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 | **DONE** | 4 commits (`1b6727bb`, `59572900`, `a3102351`, `4ff707bd`) — 7 files deleted, destinations extracted, flex layout fix |
| 16b — Vocabulary sweep + route cleanup | 3B | **DONE** | 3 commits (`548cfbdc`, `4d667caa`, `6924de3e`) — 17 files deleted, routes collapsed to redirects, instance-settings whitelist cleaned |

### 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` — DONE (both 16a and 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 — post-Wave-3B snapshot

All 24 files in the 16a + 16b target list are confirmed deleted (verified via `ls` probe 2026-04-11).

### Phase 16a (7 files deleted)

| File | Reason |
|---|---|
| `ui/src/components/ChatPanel.tsx` | Phase 8 unmounted from Layout |
| `ui/src/context/ChatPanelContext.tsx` | Migrated ChatMessageList off first (`1b6727bb`) |
| `ui/src/components/Sidebar.tsx` | Phase 8 unmounted |
| `ui/src/components/BreadcrumbBar.tsx` | Phase 8 unmounted |
| `ui/src/components/PropertiesPanel.tsx` | Phase 8 unmounted |
| `ui/src/components/VoiceMicButton.tsx` | Phase 14 orphaned |
| `ui/src/hooks/useVadRecorder.ts` | Phase 14 orphaned |

### Phase 16b (17 files deleted)

| File | Reason |
|---|---|
| `ui/src/pages/Dashboard.tsx` | Replaced by Assistant conversational home |
| `ui/src/pages/Companies.tsx` | Single-workspace mode |
| `ui/src/pages/Goals.tsx` / `GoalDetail.tsx` | Folded into Overview milestones |
| `ui/src/pages/Costs.tsx` | Demoted to per-project Costs tab |
| `ui/src/pages/Activity.tsx` | Demoted to per-project Activity tab |
| `ui/src/pages/OrgChart.tsx` | Demoted to per-project Org tab |
| `ui/src/pages/Inbox.tsx` / `Inbox.test.tsx` | Replaced by Assistant dot + ⌘K |
| `ui/src/pages/ConvertPage.tsx` | Folded into Studio Convert workshop |
| `ui/src/pages/Approvals.tsx` / `ApprovalDetail.tsx` | Demoted to per-project Gates tab |
| `ui/src/pages/Routines.tsx` / `RoutineDetail.tsx` | Linked from Settings sub-surface only |
| `ui/src/pages/Issues.tsx` | Global list removed; per-project IssuesTab keeps the wire |
| `ui/src/pages/Agents.tsx` | Global list removed |
| `ui/src/components/ChatSearchDialog.tsx` | Orphaned — no consumers after Phase 8 |
| `ui/src/components/ChatBookmarkList.tsx` | Orphaned — no consumers after Phase 8 |

### Historical

| File | Phase |
|---|---|
| `ui/src/components/InstanceSidebar.tsx` | 13 |
| `ui/src/components/MobileBottomNav.tsx` | 15 |

### Residual cleanup targets (not deleted, flagged)

- `ui/src/hooks/useInboxBadge.ts` — orphaned after `Inbox.tsx` deletion, left intact (out of 16b scope).
- Dangling `/dashboard` hrefs in `SkillDetail.tsx`, `SkillBrowser.tsx`, `PluginManager.tsx`, `PluginSettings.tsx`, `PluginPage.tsx`, `NotFound.tsx`, `CompanyImport.tsx`, `ProjectDetail.tsx`, `AgentDetail.tsx`, `company-page-memory.ts`, `useCompanyPageMemory.ts` — now fall through to `NotFoundPage scope="board"`. Low-priority rewrite to `/assistant` or project-specific equivalents.
