mikkel/nexus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
nexus/CODEBASE-MAP.md

450 lines
28 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 **full migration completion**. Phases 1–7 (visual repaint) + phases 8–16 (structural layout overhaul) + 3 post-Phase-7 polish follow-ups (F1/F2/F3) all DONE. 24 files deleted across 16a (7) + 16b (17) + 1 via F-series (`useInboxBadge.ts`). **304/304 tests passing** across 38 files.
---
## 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 | **DONE** | `68c87fc8`, `16adf9f8`, `547e5262` — 57 radius collapses, 29 soft-shadow drops |
| 5 — ThemePreviewPanel rewrite | **DONE** | `0c1496d2`, `d3141ac5` — panel + palette grid restyled |
| 6 — hljs syntax highlighting | **DONE** | `f66209f4` — full hljs class coverage, 100% CSS-var references |
| 7 — Visual QA pass | **DONE** | `5ab0b19d` (audit doc) + `9329e5d9`, `862b856d`, `77edfdb4`, `bac89b1a` (inline fixes) |
| **F1** post-Phase-7 — brand color aliases | **DONE** | `c9ed4c92` — 7 files swapped from literal hexes |
| **F2** post-Phase-7 — shadow-xs shadcn cleanup | **DONE** | `044a2571` — 6 shadcn primitives |
| **F3** post-Phase-7 — DESIGN.md typography | **DONE** | `ec6c01b0` — Basier dropped, Inter-only |
### 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 |
### Phase 7 cleanup (applied)
| File | Status | Phase |
|---|---|---|
| `ui/src/hooks/useInboxBadge.ts` | **DELETED** | 7 (follow-up `bac89b1a`) |
All `/dashboard` hrefs across `SkillDetail.tsx`, `SkillBrowser.tsx`, `PluginManager.tsx`, `PluginSettings.tsx`, `PluginPage.tsx`, `NotFound.tsx`, `CompanyImport.tsx`, `ProjectDetail.tsx` (post-import navigate), `company-page-memory.ts`, and `useCompanyPageMemory.ts` were rewritten to `/assistant` in Phase 7 commit `862b856d`. Legitimate `/dashboard` survivors (plugin REST endpoints in `api/plugins.ts`, `api/dashboard.ts`, and live agent-tab routes in `AgentDetail.tsx:764,802`) are correct and intentional.
Reference in a new issue View git blame Copy permalink