# Nexus Project Status

> **Purpose:** snapshot of where the project is right now — what's shipped, what's blocked, what to do next. Generated by scanning git log + code + reading `.planning/` and `docs/`. If this file disagrees with any plan or spec, trust this file; the code is the source of truth.
>
> **Last updated:** 2026-04-11, **Wave 3B complete**. Phases 16a and 16b are both DONE and verified — 294/294 tests passing. The structural layout overhaul (phases 8–16) is fully shipped. Remaining scope on this branch is the visual repaint phases 4–7 and the Phase 11.5 backlog.

---

## 1. Current milestone

- **Version:** v1.7 — Content Generation
- **Branch:** `nexus/design-system-migration`
- **Active work:** the **Nexus layout and information architecture overhaul** (a separate, parallel track from the v1.7 content-generation milestone). The overhaul is delivered as phases 8–16 of `MIGRATION-PLAN.md` + the layout spec at `docs/specs/2026-04-11-nexus-layout-overhaul.md`.
- **v1.7 goal:** "Comprehensive content generation layer — agents produce visual, document, and media content as real deliverables." The layout overhaul reshapes how these generators are surfaced (Studio workshops) without changing their internals.
- **Main/upstream branch:** `PAP-878-create-a-mine-tab-in-inbox`. Nexus maintains display-layer differentiation; schema/API identifiers stay upstream-compatible for periodic rebases.

### v1.7 content-generation milestone status

Active requirements from `.planning/PROJECT.md` mapped to implementation:

| Requirement | Status | Where |
|---|---|---|
| Presentations & video via Remotion | DONE (v1.7 phase 44) | `PresentationPanel.tsx`, wired into Studio as the 9th workshop in Wave 2.5 |
| Placeholder assets with DRAFT styling | Partial — DRAFT manifest exists server-side | — |
| Theme & palette generator | DONE (v1.7 phase 41) | Studio `themes` workshop |
| Wallpapers & visual assets | DONE (v1.7 phase 42) | Studio `wallpapers` workshop |
| Diagram generation | DONE (v1.7 phase 41) | Studio `diagrams` workshop |
| Document generation (PDF) | DONE (v1.7 phase 43) | Studio `documents` workshop |
| Icon generation | DONE (v1.7 phase 41) | Studio `icons` workshop |
| Social media content | DONE (v1.7 phase 42) | Studio `social` workshop |
| Branding media kit | DONE (v1.7 phase 43) | Studio `brand-kits` workshop |
| Whisper voice input in web chat | DONE (v1.6 phase 37) | ChatInput voice mic — lifted into VoiceContext in layout phase 14 |
| Content types as installable Nexus skills | DONE (v1.7 phase 45) | 9 SKILL.md files, Creative group |

---

## 2. Design system migration status (phases 1–7, visual repaint)

Verified by `git log --oneline` on `nexus/design-system-migration`.

| Phase | Title | Status | Commits |
|---|---|---|---|
| 1 | Foundation — `index.css` tokens + Inter font | **DONE** | `e49144a4` |
| 2 | Status + role color dictionaries | **DONE** | `4b8f8178` |
| 3 | Raw utility sweep | **DONE** | `3a41ec7b` |
| 4 | Typography + radius audit | **PENDING** | No commits |
| 5 | ThemePreviewPanel rewrite | **PENDING** | No commits |
| 6 | hljs syntax highlighting | **PENDING** | No commits |
| 7 | Visual QA pass | **PENDING** | No commits |

**Note:** phases 4–7 are independent of the layout overhaul (phases 8–16) and can run before or after. The user explicitly chose to push the structural overhaul first because visual polish layers on top; the layout has bigger leverage.

---

## 3. Layout overhaul status (phases 8–16, structural)

| Phase | Wave | Title | Status | Commits |
|---|---|---|---|---|
| 8 | 1 | Frame skeleton (IconRail + TopStrip + killed chrome) | **DONE** | 10 commits `332ed47b`…`2dbf2811` |
| 9 | 2 | Assistant mode (full-bleed chat + slide-overs + home greeting) | **DONE** | 8 commits `397e12a8`…`e43d5ec2` |
| 10 | 2 | Studio mode (9-workshop grid, Convert folded in, Presentations restored) | **DONE** | 5 commits `533490f1`…`cd6c172d` + Wave 2.5 |
| 11 | 2 | Projects + Builder mode (hero cards + tab strip + 5 placeholder tabs) | **DONE (with 5 TabPlaceholders)** | 7 commits `6010a105`…`1e855657` |
| 12 | 3A | Promote-to-project 700ms transition | **DONE** | 3 commits `d2d41886`, `70698b9e`, `b2775275` + 1 in `f41690ff` (attribution artifact) |
| 13 | 3A | Settings consolidation (single-column, 8 sections) | **DONE** | 6 commits `7aa98d38`…`1a0d611c` |
| 14 | 3A | Voice + ⌘K globalization | **DONE** | 6 commits `14ecbf00`…`9b772aa1` |
| 15 | 3A | Mobile parity (MobileTabBar + sheet variants) | **DONE** | 1 commit `4623c8ae` |
| **Wave 2 controller integration** | — | Wire routing + icon rail gate dot | **DONE** | `1b7e3d44` |
| **Wave 2.5 follow-ups** | — | Presentations workshop + ProjectCard derivatives + spec drift fix | **DONE** | `428f0336` |
| **Wave 3A controller integration** | — | TopStrip test providers + PromoteTransition mobile variant + Layout onSearch cleanup | **DONE** | `fb76b5ee` |
| 16a | 3B | Dead chrome cleanup (delete 7 files + DRY destinations + flex layout fix) | **DONE** | 4 commits `1b6727bb`, `59572900`, `a3102351`, `4ff707bd` |
| 16b | 3B | Vocabulary sweep + route cleanup + visual QA | **DONE** | 3 commits `548cfbdc`, `4d667caa`, `6924de3e` |

### Wave summary

- **Wave 1:** Phase 8 alone — foundational frame
- **Wave 2:** Phases 9, 10, 11 dispatched in parallel as 3 subagents
- **Wave 2.5:** Controller follow-up batching Presentations fix, ProjectCard derivatives, spec 8→9 drift
- **Wave 3A:** Phases 12, 13, 14, 15 dispatched in parallel as 4 subagents
- **Wave 3B:** Phase 16 split into 16a (dead code, running now) and 16b (vocabulary + routes, pending)

---

## 4. Known placeholders (from grep)

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

**Five per-project tabs shipped as `TabPlaceholder` because reusable list components with `projectId` props don't exist:**

| Tab | File | Missing |
|---|---|---|
| Agents | `ui/src/components/projects/tabs/AgentsTab.tsx` | `Agent` type has no `projectId`; `AgentList` isn't a standalone component |
| Gates | `ui/src/components/projects/tabs/GatesTab.tsx` | `Approval.payload.projectId` is untyped; `ApprovalsList` isn't a standalone |
| Costs | `ui/src/components/projects/tabs/CostsTab.tsx` | `CostsBreakdown` doesn't exist; `Costs.tsx` is 1100 lines inline |
| Activity | `ui/src/components/projects/tabs/ActivityTab.tsx` | `activityApi` supports server-side entity filtering but no standalone feed component |
| Org | `ui/src/components/projects/tabs/OrgTab.tsx` | `agentsApi.org()` returns company-wide tree with no per-project scoping. Backlog plan recommends dropping this tab entirely |

Each renders a "PHASE 11 DATA GAP" card with precise rationale; honest and diagnosable, not fabricated.

### ProjectCard hero-stat proxies — Wave 2.5 derivatives

**Five `TODO(phase-11.5)` annotations in `ui/src/pages/Projects.tsx`** (lines 20, 49, 171, 292, 299). The hero-stat card computes `progress` from `closed_issues / total_issues`, `nextGateName` from the first pending approval whose `payload.projectId` matches, and `lastActivity` from `max(project.updatedAt, newest issue.updatedAt)`. These proxies were the Wave 2.5 "don't ship em-dash city" compromise; real backend aggregates on `Project` are the backlog fix.

**Hard data gaps still rendering as em-dashes:**
- `phase` / `milestones` — no milestone field on the `Project` record. Overview tab shows "No milestones defined."
- `costBurnedCents` — no aggregate field. Card footer shows `—`.
- `originConversationId` — no link from project → conversation. Origin Chat card omitted.
- `activeAgentsCount` per project — hard-coded to 0.

### Other placeholders

- `DangerZoneSection.tsx` renders `disabled` "Reset workspace" and "Delete all conversations" buttons — no server endpoints exist yet. Honest placeholder per plan.
- `PresentationPanel` has always-hardcoded generator — Studio fold-in via `componentKey: "presentation"`.

---

## 5. Blocked work

### Phase 11.5 — 5 per-project tab scoping tickets

Cannot proceed without one of:
- Adding `projectId` to the `Agent` shared type + reverse index (backend change)
- Adding typed `projectId` to `Approval.payload` (backend change)
- Extracting `AgentList` / `ApprovalsList` / `CostsBreakdown` / `ActivityFeed` / `OrgChart` as standalone projectId-aware components (frontend extraction — easier)

The backlog plan at `docs/plans/2026-04-11-nexus-phase-11-5-per-project-scoping.md` breaks this into 5 independent tickets. Trigger is UX pain or explicit milestone pull-in.

### ProjectCard real fields

Not strictly blocked — Wave 2.5 computes proxies — but the ideal fix adds real backend aggregate fields to the `Project` record:
- `milestoneProgress: number` (0–100)
- `milestones: ProjectMilestone[]`
- `nextGateName: string | null`
- `costBurnedCents: number`
- `originConversationId: string | null`
- `activeAgentsCount: number`

Backend ticket, not UI.

### Phase 16a hazard — `ChatMessageList` migration

`ChatMessageList.tsx` reads `activeConversationId` and `scrollToMessageId` from `ChatPanelContext`. Phase 16a MUST migrate this off before deleting the context. Phase 9's report explicitly flagged this. Phase 16a's instructions cover it; if Phase 16a reports BLOCKED on this item, that's the hazard firing.

---

## 6. Dead code inventory

**Post-Wave-3B snapshot — all 16a and 16b targets confirmed deleted via `ls` probe 2026-04-11.**

### Phase 16a dead chrome (7 files)

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

### Phase 16b dead pages + orphaned chat surfaces (17 files)

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

### Historical deletions

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

### Residual concerns flagged by 16b report

- **Dangling `/dashboard` hrefs** (non-blocking but cosmetic): `SkillDetail.tsx`, `SkillBrowser.tsx`, `PluginManager.tsx`, `PluginSettings.tsx`, `PluginPage.tsx`, `NotFound.tsx`, `CompanyImport.tsx`, `ProjectDetail.tsx` (post-import navigate), `AgentDetail.tsx` (agent self-detail crumbs), `company-page-memory.ts` (fallback), `useCompanyPageMemory.ts`. These now fall through to `NotFoundPage scope="board"`. Low-priority follow-up: rewrite to `/assistant` or project-specific equivalents.
- **Vocabulary sweep partial**: `CompanyImport.tsx` / `CompanyExport.tsx` / `CompanySkills.tsx` body copy, `OnboardingWizard` `level: "company"` enum (code identifier, not display), and internal thrown-error strings in `NewGoalDialog`, `NewIssueDialog`, `NewProjectDialog`, `AgentConfigForm`, `IssueDetail`, `ProjectDetail`, `GoalDetail` kept "company" verbatim because they are invariant exceptions not user-visible toasts. Acceptable per "workspace is display-only" rule.
- **`useInboxBadge.ts`** is now orphaned (Inbox.tsx deleted). Out of explicit 16b scope — left intact as a no-op hook. Low-value cleanup target.

---

## 7. Route status

From `ui/src/App.tsx boardRoutes()`. Marks reflect the **post-Wave-3B** state. All routes mount under a company-prefixed root (`/:companyPrefix/*`) except `/instance/*`.

### Active Nexus destinations

- `/assistant` — PersonalAssistant (Phase 9+12+14)
- `/assistant/:conversationId` — PersonalAssistant
- `/content-studio` — ContentStudio (Phase 10 + Wave 2.5)
- `/content-studio/:workshopSlug` — ContentStudio workshop detail
- `/projects` — Projects hero-stat grid (Phase 11 + Wave 2.5)
- `/projects/:projectId/overview` — ProjectDetail Overview tab
- `/projects/:projectId/issues` — ProjectDetail Issues tab (real wire)
- `/projects/:projectId/agents` — ProjectDetail Agents tab (placeholder)
- `/projects/:projectId/gates` — ProjectDetail Gates tab (placeholder)
- `/projects/:projectId/costs` — ProjectDetail Costs tab (placeholder)
- `/projects/:projectId/activity` — ProjectDetail Activity tab (placeholder)
- `/projects/:projectId/org` — ProjectDetail Org tab (placeholder)
- `/projects/:projectId/configuration`, `/projects/:projectId/budget` — legacy preserved
- `/instance/settings/general` — Phase 13 single-column settings
- `/instance/settings/plugins`, `/instance/settings/plugins/:pluginId` — plugin subsystem

### Active detail pages (still needed from per-project / per-surface links)

- `/agents/new`, `/agents/:agentId`, `/agents/:agentId/:tab`, `/agents/:agentId/runs/:runId`
- `/issues/:issueId`
- `/execution-workspaces/:workspaceId`
- `/company/settings`, `/company/export/*`, `/company/import` — workspace export/import (kept)
- `/skills/*` (Skill Aggregator linked from Settings)
- `/design-guide`, `/tests/ux/runs`
- `/:pluginRoutePath` (plugin host)
- `/*` (NotFoundPage)

### Redirects (post-16b)

| From | To | Source |
|---|---|---|
| `/` (board index) | `/assistant` | Phase 16b |
| `/instance` | `/instance/settings/general` | Phase 13 |
| `/instance/settings/heartbeats` | `/instance/settings/general` | Phase 13 |
| `/instance/settings/experimental` | `/instance/settings/general` | Phase 13 |
| `/settings`, `/settings/*` | `/instance/settings/general` | Phase 13 |
| `/agents`, `/agents/all`, `/active`, `/paused`, `/error` | `/projects` | Phase 16b |
| `/issues`, `/issues/all`, `/active`, `/backlog`, `/done`, `/recent` | `/projects` | Phase 16b |
| `/convert`, `/convert/:sourceFormat`, `/convert/:sourceFormat/:targetFormat` | `/content-studio/convert` | Phase 16b |

### Deleted top-level routes (no longer mounted)

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

---

## 8. Pending decisions

### From MIGRATION-PLAN.md §10 — still unresolved for visual phases 4–7

1. **Light mode:** ship / drop / iterate? Light mode tokens already exist in `index.css` (`:root` block) but the visual phases to validate them haven't run.
2. **Basier font:** license / Inter only / free alternative? Current state: Inter everywhere. Decision pending.
3. **Destructive color:** current dark is `#ef4444`, light is `#dc2626`. Effectively resolved via the shipped tokens.
4. **Role hue collapse vs preserve:** resolved — `--chart-role-1..5` exception documented in `index.css`.
5. **Display 900:** resolved — used in the 72px ProjectCard hero and 96px empty state.
6. **Theme toggle UX:** resolved — binary light/dark, toggle in Settings Workspace section.
7. **Tokyo Night removal:** resolved — deleted in Phase 1 commit.

### From the layout overhaul

1. **Presentations workshop:** RESOLVED — added as 9th workshop in Wave 2.5 per user decision (C). Spec updated from 8→9.
2. **Phase 11 placeholder tabs:** RESOLVED — user accepted (A) + draft 11.5 plan. Both shipped.
3. **ProjectCard derivatives:** RESOLVED — user chose (B) compute from derivatives. Shipped in Wave 2.5.
4. **Phase 16 scope split:** RESOLVED — 16a (dead code + DRY + flex fix) and 16b (vocab + routes + visual QA).
5. **MobileTabBar FAB + badge:** RESOLVED — user chose (A) ship pure, no FAB/badge. ⌘K handles new-issue on mobile.

### Open for future milestones

- Recipe registry v1.8 — planned, not yet started. Phase 14 stubbed the "Recipes" group in the command palette as disabled placeholder.
- Phase 11.5 trigger — when does the `TabPlaceholder` UX pain justify promoting the 5 tickets to active work? User's call.
- Backend Project record enrichment (milestoneProgress, originConversationId, costBurnedCents, activeAgentsCount) — backlog.
- Phase 16b `/issues` and `/agents` redirect targets — confirmed in user's resume prompt: both redirect to `/projects`.

---

## 9. Next actions (ordered)

The structural layout overhaul (phases 8–16) is complete. The remaining scope on this branch is the visual repaint tail and a backend-dependent backlog item.

### Track A — Visual migration phases 4–7 (RECOMMENDED NEXT)

Pure frontend, no backend dependencies, unblocked. Recommended first because (a) it's the only remaining DESIGN.md compliance gap, (b) it completes the design system migration as a single thematic branch unit, and (c) the work is self-contained to ~3 files + one QA sweep.

1. **Phase 4 — Typography + radius audit.** Grep `rounded-xl`, `rounded-2xl`, `rounded-3xl` and bump down to `rounded-lg` (8px) or `rounded-sm` (4px). Bump display moments to `font-black` (900). Replace soft shadows with border + inset "pressed" depth.
2. **Phase 5 — ThemePreviewPanel rewrite.** `ui/src/components/ThemePreviewPanel.tsx` currently showcases Catppuccin. Rewrite against volt/forest/silver palette. Update `ThemePaletteGrid.tsx` or deprecate.
3. **Phase 6 — hljs syntax highlighting.** Replace the 3 theme rule sets in `ui/src/index.css` with a single DESIGN.md-compliant block (neon + white on dark, terminal aesthetic per §4).
4. **Phase 7 — Visual QA pass.** Walk every top-level route (Assistant, Studio, Projects, ProjectDetail, Settings, Skills, Plugins, Onboarding, Invite, Auth). Compare against DESIGN.md §3–§7. File issues as a punch list commit.

### Track B — Phase 11.5 per-project scoping (blocked on backend or extraction work)

See backlog plan `docs/plans/2026-04-11-nexus-phase-11-5-per-project-scoping.md`. 5 tabs × (extract standalone component + add `projectId` prop or backend field). Trigger: explicit UX pain or milestone pull-in. Not recommended as immediate next because it fans out into backend type changes.

### Track C — Low-value follow-ups (defer until needed)

- Rewrite residual `/dashboard` hrefs in `SkillDetail`, `SkillBrowser`, `PluginManager`, `PluginSettings`, `PluginPage`, `NotFound`, `CompanyImport`, `ProjectDetail`, `AgentDetail`, `company-page-memory.ts`, `useCompanyPageMemory.ts` → `/assistant` or project-specific equivalents.
- Delete orphaned `ui/src/hooks/useInboxBadge.ts`.
- Dedicated vocabulary sweep for `CompanyImport.tsx` / `CompanyExport.tsx` / `CompanySkills.tsx` body copy.

### Other possible pivots

- Switch back to the v1.7 content-generation milestone work (all 9 workshops shipped, remaining is DRAFT placeholder assets).
- Move to the v1.8 Recipe Registry milestone.

### Recommendation

**Tackle Track A (visual migration phases 4–7) next.** Rationale: finishes the design-system-migration branch cleanly, no cross-cutting dependencies, unblocks a clean PR for the full Wave 1–3B + 4–7 package. Phase 11.5 is better as a separate branch after this one merges.

### Hard hazards to remember

- **Upstream sync:** all commits on this branch use `[nexus]` (or `feat(nexus):`/`refactor(nexus):`) prefix. Don't rename backend identifiers. `company` in TypeScript/API/DB stays; `workspace` is display-only.
- **DESIGN.md is law:** anything conflicting with DESIGN.md loses. Pure black canvas, volt `#faff69` accent, forest `#166534` secondary, Inter 900 display, sharp 4/8 radii, charcoal `rgba(65,65,65,0.8)` borders.
- **No terminal for users:** zero-terminal principle. Every surface must be reachable through the UI.
- **Shared-file dispatch rule:** for parallel subagents editing shared files (`PersonalAssistant.tsx`, `Layout.tsx`, `App.tsx`, `main.tsx`), each subagent must `git add` only its own new files. Controller handles shared-file integration commit. See `~/.claude/projects/-opt-nexus/memory/feedback_parallel_dispatch_shared_files.md`.
