# 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, **full migration complete**. Phases 1–7 (visual repaint) and 8–16 (structural layout overhaul) are both DONE. Phase 7 audit applied + 3 polish follow-ups (F1/F2/F3) applied. **304/304 tests passing** across 38 files. Branch is ready to ship as a single thematic PR.

---

## 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 | **DONE** | 3 commits `68c87fc8`, `16adf9f8`, `547e5262` — 57 radius collapses, 29 soft-shadow drops (1 kept: InstallPromptBanner), no display-weight bumps needed |
| 5 | ThemePreviewPanel rewrite | **DONE** | 2 commits `0c1496d2`, `d3141ac5` — panel rewritten against DESIGN.md palette, palette grid restyled (kept for theme-generation workshop) |
| 6 | hljs syntax highlighting | **DONE** | 1 commit `f66209f4` — 100% CSS-var references, 4-hue palette discipline, full hljs class coverage (66→111 LOC) |
| 7 | Visual QA pass | **DONE** | 5 commits `5ab0b19d` (audit doc) + `9329e5d9`, `862b856d`, `77edfdb4`, `bac89b1a` (inline fixes). Audit at `docs/reviews/2026-04-11-nexus-phase-7-visual-qa.md`. 0 blockers, 4 deviations, 12 follow-ups tracked. |
| **F1** | post-Phase-7 polish — brand color aliases | **DONE** | `c9ed4c92` — 7 files swapped from literal hexes to `bg-volt`/`bg-volt-pale`/`bg-forest`/`bg-silver` aliases |
| **F2** | post-Phase-7 polish — shadow-xs shadcn cleanup | **DONE** | `044a2571` — 6 shadcn primitives (select, input, textarea, toggle, checkbox, button) |
| **F3** | post-Phase-7 polish — DESIGN.md typography | **DONE** | `ec6c01b0` — Basier dropped, Inter-only confirmed in §3 + §9 |

**Note:** phases 4–7 shipped AFTER the structural overhaul (phases 8–16) per the user's sequencing decision — the layout overhaul had bigger leverage and the visual repaint layered cleanly on top.

---

## 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 — all resolved

1. **Light mode:** RESOLVED — shipped. Light-mode tokens in `index.css` `:root` validated via Phase 7 visual QA. Forest green downrank of volt in light mode works as designed.
2. **Basier font:** RESOLVED — **Inter only**. DESIGN.md §3 amended in follow-up F3 (commit `ec6c01b0`).
3. **Destructive color:** RESOLVED — `#ef4444` dark, `#dc2626` light, both shipped and audited.
4. **Role hue collapse vs preserve:** RESOLVED — `--chart-role-1..5` exception documented in `index.css`.
5. **Display 900:** RESOLVED — used in 72px ProjectCard hero and 96px Projects empty state (Phase 4 confirmed).
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 `nexus/design-system-migration` branch is now complete.** Phases 1–7 (visual repaint) + phases 8–16 (structural layout overhaul) + 3 post-Phase-7 polish follow-ups are all DONE. 304/304 tests passing. DESIGN.md compliance audit has zero blockers. Ready for PR creation.

### Immediate

1. **Create the PR** against `PAP-878-create-a-mine-tab-in-inbox`. The branch has ~70+ commits; the PR body should summarize the two overlapping tracks (visual repaint + structural overhaul) and link the audit doc at `docs/reviews/2026-04-11-nexus-phase-7-visual-qa.md`.
2. **Review the audit doc's remaining follow-ups** (F4–F12, tracked but not fixed in this branch). None are blockers. Each is a small independent commit that could land as its own PR later.

### After this branch merges

**Track B — Phase 11.5 per-project scoping (5 tabs)**

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 on the placeholder tabs, or milestone pull-in. Fans out into backend type changes (`Agent.projectId`, `Approval.payload.projectId`). Should be its own branch — don't mix with the design system PR.

**Track C — v1.7 content-generation tail**

All 9 Studio workshops shipped. Remaining scope is DRAFT placeholder asset styling (server-side) and any per-workshop refinement that comes out of real user sessions.

**Track D — v1.8 Recipe Registry milestone**

Planned, not yet started. Phase 14 stubbed the "Recipes" group in the command palette as a disabled placeholder. New branch, new milestone entry in `.planning/PROJECT.md`.

### Phase 7 audit follow-ups (12 tracked, 4 applied F1–F3 this session)

Applied: F1 (brand color aliases), F2 (shadow-xs cleanup), F3 (DESIGN.md Inter-only amendment).

Deferred to post-merge: F4–F12. See `docs/reviews/2026-04-11-nexus-phase-7-visual-qa.md` for the full list. None are blockers.

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