14dd8dbfa5
Two orientation files for future sessions that may not have the full
conversation history loaded.
CODEBASE-MAP.md — factual scan of the tree:
1. ui/src/ directory tree with one-line descriptions
2. Full App.tsx route map with ACTIVE / LEGACY / REDIRECT /
PLACEHOLDER status per route
3. Component inventory for frame/, assistant/, studio/, projects/,
settings/ with phase attribution and file status
4. Context + hook map (13 contexts, 39 hooks)
5. API surface (34 files in src/api/)
6. CSS token map for dark and light modes with direct brand refs
7. Known issues — grep for TODO/FIXME/PHASE 11 DATA GAP/placeholder
8. Migration status verified against git log
PROJECT-STATUS.md — narrative status:
1. Current milestone (v1.7 Content Generation + parallel overhaul)
2. Design system phases 1-7 status (1-3 DONE, 4-7 PENDING)
3. Layout overhaul phases 8-16 status (8-15 DONE, 16a mid-flight,
16b pending)
4. Known placeholders — Phase 11 TabPlaceholders and Wave 2.5
TODO(phase-11.5) proxies in Projects.tsx
5. Blocked work — phase 11.5 per-project scoping tickets,
ChatMessageList migration hazard
6. Dead code inventory with ALIVE/DELETED markers
7. Route status — active, redirect, legacy pending deletion
8. Pending decisions from migration plan and layout spec
9. Ordered next actions — wait for 16a, review, dispatch 16b,
full test sweep
Both docs reference git commits and file paths so a fresh session
can cross-check against the actual tree without replaying the wave
history.
NOTE: This commit was originally attempted earlier and got tangled
with Phase 16a's staged deletions in a shared-working-tree race.
Phase 16a's subagent detected the mixed commit and reset it cleanly.
This is the re-commit using git commit -o <specific paths> to
scope strictly to the doc files, avoiding any in-flight phase 16a
work. See memory feedback_parallel_dispatch_shared_files for the
pattern.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
419 lines
26 KiB
Markdown
419 lines
26 KiB
Markdown
# 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.
|