waggle-os/docs/ux-refactor/appshell-conversion-plan.md

# AppShell Conversion Plan — Phase 0 Spine Freeze (D1-b)

**Status:** CANONICAL CONTRACT — Phases 1+ implement this document.
**Authority:** Ratification register D1–D15 (2026-06-10), `docs/ux-refactor/deltas/open-questions.md` §"UX Refactor v2.1 — Ratification" > Brief v2.1 > `docs/UX_REFACTOR_STATE_AUDIT.md`.
**Decision implemented:** D1 option (b) — convert the windowed dock shell to **AppShell + left nav + single canvas + URL routes**, reusing every shipped screen component unchanged. B1 (2026-06-09, "keep windowed AppId nav, NO react-router") is superseded.
**Code baseline:** `main @ 9dfcc75`. File:line citations are against that commit; an in-flight D8/D9 naming sweep on this branch shifts a few cited lines by ±1 (comment/label-only diff: `Desktop.tsx`, `HomeCockpit.tsx`, `CommandCenter.tsx`, `adapter.ts`, `dock-tiers.ts` — e.g. dock `cockpit` label is already "Mission Control" at `dock-tiers.ts:97`).

D1 conditions this plan operationalizes:
1. Zero screen-component rewrites during conversion (one **derived** exception — §5.2, flagged §9.8: required by condition 4, not separately ratified; goes to the founder for explicit sign-off with this plan, before P1a).
2. URLs are the navigation contract; `waggle:open-app` becomes a shim (§2).
3. No window z-order code ships; `waggle-window-state-v1` migrates then clears (§3).
4. Chat = one widget inside Workspace Desktop, one per workspace (§4).
5. B4 ("alias, don't rename" `/api/*`) survives — this conversion touches **zero** server files (§8).

---

## 1. Canonical route map

Routing stack: `react-router-dom@^6.30.1`, already installed (`apps/web/src/App.tsx:2,20-28` — today exactly 2 routes: `/` and `*`). The conversion replaces the `/`→`Index`→`Desktop` chain with a layout route: `/` → `AppShell` (BootScreen gate + nav + StatusBar + overlays + `<Outlet/>`), index redirect → `/home`.

### 1.1 Frozen route groups (brief) → all 28 AppIds + dispositions

The full `AppId` union (28 ids) is `apps/web/src/lib/dock-tiers.ts:7-18`; the window registry `appConfig` and `renderAppContent` switch are `Desktop.tsx:82-115` and `:339-469`. Every id is dispositioned below — nothing is left implicit.

| Route | AppId(s) | Component (unchanged) | Nav zone | Notes |
|---|---|---|---|---|
| `/home` | `home` | `HomeCockpit` | Work | Launch surface. Replaces the launch-flip (`Desktop.tsx:192-206`): index route redirects `/` → `/home` unconditionally. `dashboard` (legacy `DashboardApp`, kept only "for back-compat with persisted window state", `Desktop.tsx:360-362`) is **KILLED** — the back-compat reason dies with `waggle-window-state-v1` (§3.3). |
| `/workspaces/:workspaceId/:tab?` | `workspace-desktop`, `chat` | `WorkspaceDesktopApp` (+ embedded `ChatWindowInstance`) | Work ("Chat" entry) | `:tab?` ∈ the 8 PRD §12.2 tabs already defined in `WorkspaceDesktopApp.tsx:53-72` (`overview` default, `chat`, `research`, `artifacts`, `memory`, `tasks`, `timeline`, `settings`). Chat widget = `/workspaces/:id/chat` (§4). `?session=<id>` reserved for session deep links (server already emits `action.route: /workspace/:id/session/:sid` at `routes/command.ts:152` — advisory only, FE parses result ids; B4 untouched). Bare `/workspaces` → redirect `/home` (Home IS the workspace selector per A2/Journey 1 — flagged §9). |
| `/memory/:mindScope?` | `memory` | `MemoryApp` (P1) → standalone `MemoryCenterApp` (P3, D2) | Work | P1 mounts the existing 7-tab `MemoryApp` at `/memory` (props re-hosted, §5.1). `:mindScope?` ∈ `personal\|workspace` is **reserved now, implemented in P3** with the D2 two-mind split. `?tab=graph\|timeline\|harvest\|weaver\|wiki\|evolution` addresses the legacy tabs (D2: capability stays reachable); `MemoryApp` has no `initialTab` prop today, so `?tab=` wiring is **P3 phase work, not conversion work** (exclusion §5.3). |
| `/artifacts` | `artifacts` | `ArtifactCenterApp` | Work | `?workspace=<id>` optional; wrapper passes `?workspace ?? activeWorkspaceId` (prop today: `Desktop.tsx:435`). |
| `/files` | `files` | `FilesAppTabs` | Work | **Flagged addition** (§9) — Work-zone primary-spine entry (`dock-tiers.ts:55`) the brief's group list omits. `?workspace=<id>` replaces the `filesViewWorkspaceId` local state plumbing (`Desktop.tsx:211,436-451`). |
| `/agents` | `agents` | `AgentsApp` | Intelligence | Internal detail/builder (AgentCenterDetail, AgentBuilder S18) stay component-internal; no `/agents/new` at conversion. |
| `/automations` | `scheduled-jobs` | `AutomationCenterApp` | Intelligence | `?tab=logs&automationId=<id>` replaces the Journey-16 CustomEvent payload (`Desktop.tsx:172-190`, consumer `AutomationCenterApp.tsx:104-114`). |
| `/skills` | `capabilities` | `CapabilitiesApp` | Intelligence | SkillBuilder (S19) stays internal (`CapabilitiesApp.tsx:393`). |
| `/connectors` | `connectors` | `ConnectorsApp` | Extend | Wrapper passes `personaId={activeWorkspace?.persona}` (today `Desktop.tsx:410`). |
| `/mcps` | `mcp-hub` | `MCPHubApp` | Extend | Same `personaId` prop (`Desktop.tsx:411`). |
| `/marketplace` | `marketplace` | `MarketplaceApp` | Extend | **Flagged addition** (§9) — the brief omits an Extend-zone group for it; it is a shipped S21 surface with a dock entry (`dock-tiers.ts:78`). |
| `/launcher` | `launcher` | `LauncherApp` | Extend (label "AI Tools") | **Flagged addition** (§9) — dock parity (`dock-tiers.ts:79`); also hosts S14 Tool Discovery per D6. Wrapper passes `activeWorkspaceId`. |
| `/room` | `room` | `RoomApp` | Intelligence | **Flagged addition** (§9) — dock entry `dock-tiers.ts:65` + Ctrl+Shift+R (`useKeyboardShortcuts.ts:70-74`). Wrapper builds `workspaceNames` map (today `Desktop.tsx:456-461`). |
| `/waggle-dance` | `waggle-dance` | `WaggleDanceApp` | Intelligence | **Flagged addition** (§9) — dock entry `dock-tiers.ts:66`. |
| `/approvals` | `approvals` | `ApprovalsApp` | Intelligence (nav hidden < TEAMS) | D5: tier-hidden, not stripped. Route registered; nav entry carries `minBillingTier:'TEAMS'` exactly as `dock-tiers.ts:68`. PRO visibility = post-launch consideration (D5), untouched here. |
| `/team` | `governance` | `TeamGovernanceApp` | Team (zone hidden < TEAMS) | **Reserved — does not ship in nav below TEAMS.** Identical semantics to today's `filterByBillingTier` (`dock-tiers.ts:84-88,135-149`): route renders the legacy app for TEAMS+; FREE/PRO never see the zone. No new Team work (D5). |
| `/settings` | `settings` | `SettingsApp` | System | `?tab=general\|models\|billing\|permissions\|team\|backup\|enterprise\|advanced` (internal tabs, `SettingsApp.tsx:34-42`) — URL→tab wiring is best-effort at conversion, same exclusion class as `/memory?tab=` (§5.3). |
| `/settings/vault` | `vault` | `VaultApp` | System | System-zone surfaces nest under `/settings/*` — flagged call §9. Renders full-canvas with System nav section active; NOT embedded inside SettingsApp's UI (zero-rewrite). |
| `/settings/profile` | `profile` | `UserProfileApp` | System (no nav entry — parity with today) | `?tab=identity` replaces the HarvestTab deep link (`memory/HarvestTab.tsx:298-299` dispatches `{appId:'profile', tab:'identity'}`); consumer keeps its `waggle:open-app` listener untouched via the shim's post-navigation re-dispatch (§2.3 — the listener is live-only; `UserProfileApp` never calls `consumeDeepLink`). |
| `/settings/mission-control` | `cockpit` | `CockpitApp` | System | D8: label "Mission Control" (already applied, `dock-tiers.ts:97`). "Command Center" is reserved for the Ctrl+K palette. |
| `/settings/timeline` | `timeline` | `TimelineApp` | System | Wrapper passes `workspaceId={activeWorkspaceId}` (today `Desktop.tsx:463`). |
| `/settings/events` | `events` | `EventsApp` | System | Props re-hosted from `useEvents` (§5.1). |
| `/settings/usage` | `telemetry` | `TelemetryApp` | System | Dock label "Usage & Cost" (`dock-tiers.ts:99`). |
| — KILLED | `dashboard` | `DashboardApp` | — | See `/home` row. No route. File removal deferred to dead-code phase work (CLAUDE.md §3.3 — not conversion work). |
| — KILLED | `voice` | `VoiceApp` | — | No dock entry, no live opener anywhere in `apps/web/src` (grep: zero `openApp('voice')` / `appId:'voice'` dispatch hits). No route. |
| — KILLED | `mission-control` | `MissionControlApp` | — | Not in any dock config; only reachable via dead `GlobalSearch.tsx:47` (retained-for-rollback, no live imports per audit §2d). D8 moves the "Mission Control" name to `CockpitApp`. No route. Its spawn affordance survives via the global `SpawnAgentDialog` overlay. |
| — KILLED | `backup` | `BackupApp` | — | Duplicated by SettingsApp's internal `backup` tab (`SettingsApp.tsx:34,42,733-766`; dock comment `dock-tiers.ts:100` "Backup stays in Settings"). Only opener was dead GlobalSearch. `/settings?tab=backup` is the address. |

Count check: 22 routed ids + `chat` (widget, §4) + `workspace-desktop` (= `/workspaces/:id`) + 4 killed = 28. ✓

### 1.2 Overlays — disposition: overlay-stays-overlay, mounted ONCE in AppShell

All overlays currently mounted in `Desktop.tsx:569-663` move verbatim into AppShell (global across every route). None becomes a route.

| Overlay | Trigger | Conversion delta |
|---|---|---|
| `CommandCenter` (Ctrl+K palette) | `useKeyboardShortcuts.ts:92-97` + StatusBar | None to component; `onNavigate` handler retargets to `navigate()` (§2.2). |
| `PersonaSwitcher` | Ctrl+Shift+P | Retargets the **active workspace chat widget** persona instead of "focused chat window" (`Desktop.tsx:583-604` focused-window resolution dies with focus tracking — §4.3). |
| `WorkspaceSwitcher` | Ctrl+Tab | `onSelect` → `navigate('/workspaces/'+id)` instead of `openChatForWorkspace`. |
| `CreateWorkspaceDialog`, `SpawnAgentDialog`, `NotificationInbox`, `KeyboardShortcutsHelp`, `OnboardingTooltips`, `LoginBriefing`, `UpgradeModal` (D7), `TrialExpiredModal` | unchanged | Mount relocation only. `LoginBriefing.onOpenWorkspace` → `navigate()`. UpgradeModal/TrialExpiredModal checkout-failure fallbacks (`wm.openApp('settings')`, `Desktop.tsx:651,661`) → `navigate('/settings')` — instance of §2.1 rule 3, noted so the conversion diff is fully accounted. |
| `OnboardingWizard` | `!onboardingState.completed` early-return (`Desktop.tsx:325-336`) | Stays a full-screen takeover at the AppShell layout level (renders INSTEAD of nav+canvas, any URL). Not a route at conversion. `onFinish` retargets per §2.2: seed chat widget (`{personaId, initialMessage}`, §4.2) + `navigate()` to the new workspace's chat tab. |
| `ContextRail` | per-surface `onContextRail` callbacks | This is the brief's **optional right rail** — stays an overlay panel owned by AppShell; surfaces keep their existing `onContextRail` props. |
| `GlobalSearch.tsx` | none (dead, "retained for rollback") | Deleted with the window manager (§3.2) — rollback is git, not dead files. |

### 1.3 Left-nav zone → route entry points

The nav consumes the **same data** the dock consumes today: `POWER_CONFIG` 5 IA zones + `filterByBillingTier` + `getDockForTier` (`dock-tiers.ts:50-153` — survives unchanged as the nav model; `Dock.tsx`/`DockTray.tsx` renderers die). Each entry gains a `route` field next to its `appId` (additive change to `dock-tiers.ts`, the transition's appId→route table — §2.3).

- **Work:** Home→`/home` · Chat→`/workspaces/<active>/chat` (no active workspace → `/home`) · Memory→`/memory` · Files→`/files` · Artifacts→`/artifacts`
- **Intelligence:** Agent Center→`/agents` · Skills Hub→`/skills` · Automation Center→`/automations` · Room→`/room` · Waggle Dance→`/waggle-dance` · Approvals→`/approvals` (TEAMS+)
- **Extend:** Connector Hub→`/connectors` · MCP Hub→`/mcps` · Marketplace→`/marketplace` · AI Tools→`/launcher`
- **Team (hidden < TEAMS):** Team Governance→`/team`
- **System:** Settings→`/settings` · Vault→`/settings/vault` · Mission Control→`/settings/mission-control` · Timeline→`/settings/timeline` · Events & Logs→`/settings/events` · Usage & Cost→`/settings/usage`

The `simple`/`professional` UI-complexity tiers (`TIER_DOCK_CONFIG`, `dock-tiers.ts:105-128`) keep filtering the nav exactly as they filter the dock today.

---

## 2. Navigation contract — URL is the single source of truth

### 2.1 The contract

1. **AppShell layout route** owns: BootScreen gate (FR #23 sequencing moves from `pages/Index.tsx:14-36` into the layout), onboarding takeover, StatusBar, left nav, global overlays, the persistent ChatHost (§4.2), and `<Outlet/>` as the single canvas.
2. **Active nav state derives from the URL** (`useLocation` prefix match against the entry's `route`). No `openAppIds`/`minimizedAppIds` indicator state (`useWindowManager.ts:438-451` dies).
3. **Every navigation is `navigate()`.** No surface raises a window. Browser/Tauri back-forward works by construction.

### 2.2 Existing navigation surfaces — retarget table

| Surface today | Evidence | Becomes |
|---|---|---|
| `handleSearchNavigate` (palette result clicks) | `Desktop.tsx:258-288` — type-prefixed ids: `workspace:`→`openWorkspaceDesktop`, `session:<ws>:<sid>`→`openChatForWorkspace`, `memory:`→`openApp('memory')`, `skill:`/`connector:`/`mcp:`→hub apps, `command:`→`openApp(bareId)` | Pure function `routeForSearchResult(type,id)` → `navigate()`: `workspace:`→`/workspaces/:id` · `session:`→`/workspaces/:ws/chat?session=:sid` · `memory:`→`/memory` · `skill:`→`/skills` · `connector:`→`/connectors` · `mcp:`→`/mcps` · `command:`→`routeFor(appId)` fallback · `person:`→no-op (parity: unhandled today too — the server intentionally doesn't federate `person` yet, `routes/command.ts:22-24`; retarget to `/team` when it federates). This makes `routeForSearchResult` total over `NAVIGABLE_TYPES` (`CommandCenter.tsx:66-68`). `CommandCenter.tsx` itself is untouched (its `onNavigate(type,id)` prop contract holds, `CommandCenter.tsx:170,351-360`). |
| Keyboard Ctrl+Shift+0-9 | `useKeyboardShortcuts.ts:16-27,86-90` | `onOpenApp(id)` handler → `navigate(routeFor(id))`. Map entries pointing at killed ids retarget: `0:dashboard`→`/home`, `4:cockpit`→`/settings/mission-control`. Hook unchanged; only the Desktop-supplied callback changes. |
| Dock clicks | `Desktop.tsx:564-567` | Nav entry click → `navigate(entry.route)`; Chat special-case resolves active workspace (§1.3). |
| Launch-flip | `Desktop.tsx:192-206` | Deleted — index redirect `/`→`/home` subsumes it. |
| `waggle:open-app` CustomEvent | dispatchers: `HomeCockpit.tsx:255`, `MarketplaceApp.tsx:265`, `CapabilitiesApp.tsx:509`, `MissionControlApp.tsx:57`, `memory/HarvestTab.tsx:298`; Desktop listener `Desktop.tsx:178-190` | **Internal shim during transition** (§2.3). |
| `handleOnboardingFinish` (wizard `onFinish`) | `Desktop.tsx:309-313` — `selectWorkspace` + `wm.openChatForWorkspace(workspaceId, workspaceName, personaId, firstMessage)` + `refreshWorkspaces`. First-run critical path: lands the user in chat with the wizard-chosen persona and the QW-1 starter prompt prefilled (bug #4/#8/P1 fixes, comment block `Desktop.tsx:297-308`) | `selectWorkspace` + seed the workspace's chat widget with `{personaId, initialMessage: firstMessage}` via the ChatHost seed API (§4.2) + `navigate('/workspaces/'+workspaceId+'/chat')` + `refreshWorkspaces`. Verified by acceptance check 8. |

### 2.3 The `waggle:open-app` shim (D1 condition 2)

Dispatching components are screen components — rewriting their dispatch sites would violate D1 condition 1. So:

- AppShell installs ONE listener (replacing `Desktop.tsx:178-190`): `{appId, tab?, automationId?}` → `navigate(routeFor(appId) + queryString({tab, automationId}))` **and** keeps calling `stashDeepLink` (`lib/app-deeplink.ts:21-24`) so the mount-time consumer (`AutomationCenterApp.tsx:104-114` — the ONLY `consumeDeepLink` caller in the tree) works unchanged. The other consumer, `UserProfileApp.tsx:105-118`, **never reads the stash** — it has only a *live* `waggle:open-app` listener, which today works because the dispatcher (HarvestTab) and an already-mounted profile window can coexist. Under the single canvas they cannot, so after `navigate()` the shim **re-dispatches the same event once, on the tick after the target route has rendered** (detail marked `redispatch: true`; the shim ignores its own re-dispatches). The freshly mounted live listener catches the re-dispatch — zero screen-component edits, D1 condition 1 intact, and acceptance check 3's tab-preselect holds for both consumer styles (stash-on-mount and live-listener).
- `routeFor(appId, ctx?: { activeWorkspaceId?: string })` is the §1.1 table as code, co-located with `dock-tiers.ts`. A **function, not a `Record<AppId, string>`**: `chat` and `workspace-desktop` resolve to parameterized routes (`/workspaces/:id(/chat)`; no active workspace → `/home`, §1.3) that a static record cannot express. All three chat-capable consumers — the nav Chat entry (§1.3), Ctrl+Shift+1 (§2.2), and this shim (theoretical arm: no dispatcher emits `appId:'chat'` today) — resolve through it, so the chat special-case is implemented exactly once.
- **Slated for removal** (tracked exclusion, post-conversion phase work): dispatch sites migrate to `useNavigate`/`Link`, consumers migrate to `useSearchParams`, then the event listener + `app-deeplink.ts` are deleted. URLs are the contract from day one; the event is plumbing.

---

## 3. Window-manager retirement inventory (D1 condition 3)

### 3.1 Code that DIES (no z-order code ships — brief §6.5)

| Unit | Evidence | Verdict |
|---|---|---|
| z-order: `topZRef`, `nextZ()`, `zIndex` on `WindowState` | `useWindowManager.ts:122,190,44` | DELETE |
| Focus: `focusedInstanceId`, `focusWindow`, `cycleWindowFocus` + Ctrl+` listener, dangling-focus reassignment | `useWindowManager.ts:124,390-426,373-384` | DELETE (Ctrl+` shortcut retires) |
| Minimize: `minimizeApp`, `minimizeTopWindow`, `minimized`, `minimizedAppIds`; Ctrl+Shift+M / Ctrl+W handlers | `useWindowManager.ts:386-388,412-414,439-451`; `useKeyboardShortcuts.ts:56-67` | DELETE |
| Cascade: `cascadeCounter`, `cascadeOffset`, `computeCascadePosition` | `useWindowManager.ts:123`; `lib/window-cascade.ts` | DELETE |
| Open/close: `openApp`, `openChatForWorkspace`, `openWorkspaceDesktop`, `closeApp`, `closeTopWindow` | `useWindowManager.ts:192-309,363-365,408-410` | DELETE — replaced by `navigate()` (chat seeding logic relocates, §4) |
| Persistence: `loadPersistedWindows`/`savePersistedWindows` on `waggle-window-state-v1` | `useWindowManager.ts:7,54-84,186-188` | DELETE after one-shot migration (§3.3) |
| `AppWindow.tsx` (drag via framer-motion `useDragControls`, 8-direction resize) | 321 LOC; drag `:70,:232-236`, resize `:18-21,:73-176` | DELETE |
| `Dock.tsx` + `DockTray.tsx` renderers | audit §2a | DELETE — replaced by AppShell nav rendering the same `dock-tiers.ts` data |
| `lib/window-positions.ts` (`getSavedPosition`), `lib/status-bar-focus.ts` (`buildStatusBarFocus`) | `Desktop.tsx:67,536,515-525` | DELETE — StatusBar breadcrumb derives from the matched route's title instead |
| `overlays/GlobalSearch.tsx` (dead) | audit §2d | DELETE |
| Workspace-reconciliation sweep for restored chat windows | `useWindowManager.ts:155-183` | DELETE — chat instances are route/widget-scoped, no restored-window orphans exist (its one legacy duty, re-homing `'local-default'`-stamped chat state, is performed once by §3.3 steps 2–3) |

Deletion, not retention: D1-3 says no z-order code *ships*. Rollback is the git tag (§6), not dead files on disk.

### 3.2 What SURVIVES (transitional shim)

- **Per-chat persona/autonomy state**: `WindowState.personaId/autonomyLevel/autonomyExpiresAt` + `setWindowPersona`/`setWindowAutonomy` + the 10s autonomy auto-revert interval (`useWindowManager.ts:316-361`) relocate into a new `useChatWidgetState(workspaceId)` hook owned by the ChatHost (§4.2). Logic moves verbatim; the keying changes from `instanceId` to `workspaceId`. `WindowState.initialMessage` (`useWindowManager.ts:30`) relocates as the one-shot payload of the §4.2 chat seed API (it is transient intent, not persisted state — not part of the `waggle-chat-state-v1` key).
- `getWindowTitle`'s chat-title composition (`useWindowManager.ts:428-436`) → chat widget header label.
- **`useDockNudge`** (M-24/ENG-3 session-10/50 zone nudges — `Desktop.tsx:218-223`; `lib/dock-nudge.ts` + tests): relocates verbatim into AppShell. The IA zones it points at survive as nav zones (§1.3), so the behavior stays meaningful; the copy strings that say "dock" (`dock-nudge.ts:25,60-61`) retarget to the left nav — a lib copy edit, not a screen-component edit (D1-1 intact).
- `useWindowManager.ts` itself is deleted once both relocations land; it does NOT survive as a runtime shim.

### 3.3 `waggle-window-state-v1` migration → clear

One-shot, on first AppShell boot, before first render of the canvas:

1. Read + parse the key (same validation as `loadPersistedWindows`, `useWindowManager.ts:54-72`).
2. **Initial-route salvage:** highest-`zIndex` non-minimized window → `routeFor(appId)` (chat → `/workspaces/:workspaceId/chat`; a chat stamped with the `'local-default'` pre-fetch placeholder → `/home`) → seed the initial navigation. No windows / parse failure → `/home`.
3. **Chat-state salvage:** for each `appId==='chat'` entry, write `{personaId, autonomyLevel, autonomyExpiresAt}` keyed by `workspaceId` into the new chat-widget state store (last-write-wins when multiple windows share a workspace — the multi-instance case collapses per §4). Entries keyed `'local-default'` (the placeholder today's reconciliation sweep re-homes onto the first real workspace, `useWindowManager.ts:167-172` — sweep deleted in §3.1) re-key to the first real workspace when the chat-state store first sees the real workspace list (the migration itself runs pre-fetch); one-shot legacy re-key mirroring the deleted sweep — new widget state is never placeholder-stamped, so the re-key dies with the §2.3 shim cleanup.
4. `localStorage.removeItem('waggle-window-state-v1')` — unconditionally, including on parse failure. No dual-format support, ever.

---

## 4. Chat-as-widget design (D1 condition 4)

### 4.1 Current semantics being mapped

- Chat is the ONLY multi-instance app: singleton-per-workspace unless an explicit `personaOverride` spawns a second window on the same workspace (`useWindowManager.ts:223-268`; Ctrl+Shift+N via `handleNewChatWindow`, `Desktop.tsx:233-239`; PersonaSwitcher acting on the focused chat window, `Desktop.tsx:583-604`).
- `ChatWindowInstance` (per-window chat runtime: own `useChat`/`useSessions`, persona + autonomy header controls) receives everything via props (`ChatWindowInstance.tsx:50+`; render site `Desktop.tsx:341-358`).
- `WorkspaceDesktopApp` already has a `chat` tab whose body is a **placeholder that deep-links out** via `onOpenChat` (`WorkspaceDesktopApp.tsx:65,86-90,851`; "the shell never embeds a live composer itself", `:88`).

### 4.2 Target

- **One chat widget per workspace**, living at `/workspaces/:id/chat`: the `chat` tab body renders `ChatWindowInstance` (unchanged component) instead of the placeholder; `onOpenChat` callers inside the component (Overview preview widget `:161-199`, header button `:469`) retarget to the chat tab — which they already do semantically ("deep-links to the Chat tab", `:29`).
- **ChatHost keep-alive:** AppShell hosts a `ChatHost` that mounts one `ChatWindowInstance` per *visited* workspace this session, keyed by `workspaceId`, hidden (not unmounted) when the route is elsewhere. This preserves today's behavior where an open chat window keeps streaming while the user works in other windows — route unmounting would kill in-flight `useChat` SSE streams, which IS a hard requirement (an agent run must survive navigation). This is shell plumbing, not a screen rewrite.
- Per-widget persona/autonomy state: `useChatWidgetState(workspaceId)` (§3.2), persisted under a new versioned key (`waggle-chat-state-v1`), seeded by the §3.3 migration.
- **Chat seed API (imperative, one-shot):** `useChatWidgetState`/ChatHost expose `seedChat(workspaceId, {personaId?, initialMessage?})`; the widget consumes the seed on its first mount for that workspace. This is the post-conversion carrier for what `WindowState.initialMessage`/`personaId` carry today into the `ChatWindowInstance` `initialPersona`/`initialMessage` props (`useWindowManager.ts:30`, `Desktop.tsx:350-351`) — without it, wizard chat seeding dies with `openChatForWorkspace` (§3.1). Sole conversion-time caller: the wizard `onFinish` retarget (§2.2). Reusable by HomeCockpit `onContinue` when `?session=` seeded restore lands (§5.3 #5).
- PersonaSwitcher (Ctrl+Shift+P) targets the active workspace's widget; fallback to patching the workspace record stays (`Desktop.tsx:595-601` logic, re-hosted).
- Ctrl+Shift+N ("new chat window") retires as a window spawner; it navigates to the active workspace's chat tab. New-session affordance already exists inside `ChatWindowInstance` via `useSessions`.

### 4.3 D1-c lite (detached chat) — **NOT NEEDED**

Searched for a hard requirement; none exists in code. The only capability lost is *N concurrent same-workspace chat windows with different personas* (Phase A.2 convenience, `useWindowManager.ts:219-221`). Nothing depends on it: each window runs an independent `useChat` session; no cross-instance coordination, no feature consumes the multiplicity (PersonaSwitcher/Ctrl+Shift+N merely create it). Per-workspace persona switching survives in the widget header (`onPersonaChange` prop, `Desktop.tsx:352`). Cross-WORKSPACE parallelism survives fully: ChatHost keeps every visited workspace's widget alive (§4.2). Verdict: ship without the exception; if dogfood surfaces real demand for side-by-side personas, propose D1-c lite then — do not pre-build it.

---

## 5. Zero-rewrite mounting plan (D1 condition 1)

### 5.1 Mechanism: route wrappers re-host Desktop's prop plumbing

`Desktop.tsx` is today's single integrator: it owns the domain hooks (`useWorkspaces`, `useMemory`, `useEvents`, `useKnowledgeGraph`, `useAgentStatus`, `useNotifications`, `useWaggleDance`, `useOnboarding`, `useOfflineStatus` — `Desktop.tsx:119-128`) and feeds props in `renderAppContent`. The conversion relocates, never rewrites:

- **AppShell context** hosts the cross-cutting hooks once (workspaces/tier/notifications/onboarding/offline/agent-status — everything StatusBar + nav + overlays need).
- **One thin wrapper per route** (`apps/web/src/routes/*.tsx`, new files) reads route params + shell context, hosts any surface-local hooks, and renders the existing component **with byte-identical props**. `AppErrorBoundary` wraps each route surface exactly as it wraps window content today (`Desktop.tsx:556-558`).

| Screen | Props needed (source today) | Wrapper supplies |
|---|---|---|
| `HomeCockpit` | `onContinue`/`onOpenWorkspaceDesktop`/`onCreateWorkspace` (`Desktop.tsx:363-382`) | `navigate('/workspaces/:id/chat')` / `navigate('/workspaces/:id')` / open CreateWorkspaceDialog overlay |
| `WorkspaceDesktopApp` | `workspaceId`, `workspaceName`, `onOpenChat` (`Desktop.tsx:392-406`) | `useParams().workspaceId`; `onOpenChat`→chat tab |
| `MemoryApp` | 12+ props from `useMemory` + `useKnowledgeGraph` + `onContextRail` (`Desktop.tsx:412-423`) | wrapper hosts both hooks (heaviest re-host; verbatim move) |
| `ArtifactCenterApp` | `activeWorkspaceId`, `workspaceName` (`Desktop.tsx:435`) | `?workspace` ?? shell context |
| `FilesAppTabs` | `workspaceId`, `workspaces`, `onSelectWorkspace`, `onContextRail` (`Desktop.tsx:436-451`) | `?workspace` param replaces `filesViewWorkspaceId` state |
| `AgentsApp` | `workspaces` (`Desktop.tsx:434`) | shell context |
| `AutomationCenterApp`, `CapabilitiesApp`, `MarketplaceApp`, `SettingsApp`, `VaultApp`, `UserProfileApp`, `BackupApp`*, `TelemetryApp`, `CockpitApp`, `WaggleDanceApp`, `ApprovalsApp`, `TeamGovernanceApp` | zero props (`Desktop.tsx:407-409,430-433,452-453,462,464-466`) | mount bare (*BackupApp killed) |
| `ConnectorsApp` / `MCPHubApp` | `personaId` (`Desktop.tsx:410-411`) | shell context |
| `EventsApp` | `useEvents` bundle + `onAbort` (`Desktop.tsx:424-429`) | wrapper hosts `useEvents` |
| `TimelineApp` / `RoomApp` / `LauncherApp` | workspaceId / names map / activeWorkspaceId (`Desktop.tsx:454-463`) | shell context |
| `ChatWindowInstance` | full prop set (`Desktop.tsx:341-358`) | ChatHost + `useChatWidgetState` (§4.2) |

### 5.2 The ONE sanctioned component edit

`WorkspaceDesktopApp` must (a) accept a controlled `activeTab`/`onTabChange` pair (today internal state, `:615`) so `:tab?` is URL-driven, and (b) render the chat widget in the `chat` tab body (today a placeholder, `:851`). This is **derived from D1 condition 4**, not a discretionary rewrite — condition 4's chat-widget-inside-Workspace-Desktop cannot ship without both seams. The register itself never ratified a screen edit (condition 1 reads "screens mount under routes as-is"), so these two seams require **explicit founder sign-off as part of the Phase 0 ratification of this plan, before P1a starts** — scoped to exactly those two seams, test-pinned, everything else in the file untouched.

### 5.3 Exclusions — divergences that are PHASE work, not conversion work

1. `/memory?tab=` + `/settings?tab=` URL→internal-tab wiring (components lack tab props) → P3 (D2 rework) / P7.
2. Memory two-mind `/:mindScope` implementation → P3 (D2).
3. `waggle:open-app` dispatch-site + consumer migration off the shim → post-conversion cleanup (§2.3).
4. Dead-file removal beyond the §3.1 inventory (`DashboardApp`, `VoiceApp`, `MissionControlApp`, `BackupApp` files) → dead-code commit per CLAUDE.md §4.
5. `?session=` chat session-targeted restore (chat runtime doesn't accept a sessionId seed yet — `Desktop.tsx:366-373` comment) → carries as the existing known gap, URL shape reserved now.
6. D3 auth-gate, D2, D4, D11/D12 — own phases per the ratified sequence.

---

## 6. Transition sequencing

| Step | Content | Class |
|---|---|---|
| **P0 (this doc)** | Route map + contract frozen. No code. | — |
| **P1a — conversion** | Tag `checkpoint/pre-appshell-2026-06`. Then one PR: AppShell layout + nav (from `dock-tiers.ts` data) + route wrappers + ChatHost + §3.3 migration + retarget table (§2.2) + §3.1 deletions + §5.2 edit. FE-only; `packages/server` diff = **empty** (B4). | Mechanical: routes/wrappers/nav/retargets/deletions. **Risky:** ChatHost keep-alive + chat-state migration; `WorkspaceDesktopApp` tab control; MemoryApp hook re-host. Risk is isolated in NEW files + the one sanctioned edit. |
| **P1b — D3** | Adapter-level auth gate lands ON the converted shell (gate once, on one spine). | per ratification |
| **P2+** | Verify+J08, D2 (P3), D11/D12 (P4), D4 (P5), D15 (P7) — per the ratified phase sequence. | — |
| **Rollback** | Conversion is one revertable PR: screen components untouched (±§5.2) ⇒ `git revert` of the conversion merge restores the windowed shell byte-for-byte. The §3.3 migration deletes `waggle-window-state-v1`, so a rollback boots to the empty-desktop launch-flip (`home` opens) — accepted, not data loss. | — |

Note (flagged §9): the ratification's phase list reads "P1=D3" and left the conversion *build* implicit ("Phase 0 = D1 conversion plan"). This plan assigns the build to P1a, ahead of D3, so the structural auth gate is built once against the final spine instead of being re-plumbed after.

---

## 7. Launch-cut screen inventory lock (audit §3, frozen)

20 in-scope blueprint screens — verdicts restated from `docs/UX_REFACTOR_STATE_AUDIT.md` §3; this table is the Phase 0 freeze. No screen is rebuilt by the conversion.

| S# | Screen | Verdict | Component | Route (per §1) |
|---|---|---|---|---|
| 1 | Home Cockpit | exists | `HomeCockpit.tsx` | `/home` |
| 2 | Workspace Desktop | exists | `WorkspaceDesktopApp.tsx` | `/workspaces/:id` |
| 3 | Command Center (Ctrl+K) | exists | `overlays/CommandCenter.tsx` | overlay (global) |
| 4 | Memory Center | exists (tab; D2 promotes P3) | `MemoryApp.tsx` + `memory/MemoryCenterTab.tsx` | `/memory` |
| 5 | Artifact Center | exists | `ArtifactCenterApp.tsx` | `/artifacts` |
| 6 | Skills Hub | exists | `CapabilitiesApp.tsx` | `/skills` |
| 7 | Connector Hub | exists | `ConnectorsApp.tsx` | `/connectors` |
| 8 | MCP Hub | exists | `MCPHubApp.tsx` | `/mcps` |
| 9 | Agent Center | exists | `AgentsApp.tsx` | `/agents` |
| 10 | Team Workspace | DEFERRED (legacy app tier-hidden, D5) | `TeamGovernanceApp.tsx` | `/team` (reserved) |
| 11 | Automation Center | exists | `AutomationCenterApp.tsx` | `/automations` |
| 12 | First Launch | exists | `onboarding/WelcomeStep.tsx` | OnboardingWizard takeover |
| 13 | Who Are You | exists | `onboarding/WhoAreYouStep.tsx` | (wizard) |
| 14 | Tool Discovery | partial — relocated to Launcher (D6 ratified) | `LauncherApp.tsx` | `/launcher` |
| 15 | Memory Import | exists | `onboarding/ImportStep.tsx` | (wizard) |
| 16 | Memory Review | partial — relocated to Memory Center "Needs review" (D6) | `memory/MemoryCenterTab.tsx` | `/memory` |
| 17 | Create Workspace | exists | `onboarding/WorkspaceCreateStep.tsx` + `CreateWorkspaceDialog.tsx` | (wizard) + overlay |
| 18 | Agent Builder | exists | `agents/AgentBuilder.tsx` | inside `/agents` |
| 19 | Skill Builder | exists | `skills/SkillBuilder.tsx` | inside `/skills` |
| 20 | Automation Builder | exists | `automations/AutomationBuilder.tsx` | inside `/automations` |
| 21 | Marketplace / Extend | exists | `MarketplaceApp.tsx` | `/marketplace` (flagged) |

---

## 8. Acceptance checks (conversion done = ALL pass)

1. **No z-order code ships (brief §6.5):** `grep -rn "zIndex\|nextZ\|cascadeOffset\|minimizeApp\|focusWindow\|buildStatusBarFocus" apps/web/src` → zero hits outside CSS/z-index utility classes; `useWindowManager.ts`, `AppWindow.tsx`, `window-cascade.ts`, `window-positions.ts`, `status-bar-focus.ts` (+ its `.test.ts`), `Dock.tsx`, `DockTray.tsx`, `GlobalSearch.tsx` do not exist.
2. **Every §1.1 routed screen reachable by typing its URL** into a fresh tab (post-boot, post-onboarding) — including param forms `/workspaces/:id/chat` and `/automations?tab=logs&automationId=x`. Unknown URLs → existing `NotFound`.
3. **Deep links are URLs:** dispatching `waggle:open-app {appId:'scheduled-jobs', tab:'logs', automationId}` changes `location` to `/automations?tab=logs&automationId=…` AND the Logs tab preselects (stash consumed on mount, §2.3); HarvestTab's "Open Profile" lands on `/settings/profile?tab=identity` **with the Identity tab preselected** (the shim's post-render re-dispatch reaches `UserProfileApp`'s live listener, §2.3).
4. **Ctrl+K works on every route** (palette mounts in AppShell); a `workspace:` result click changes the URL to `/workspaces/:id`; browser Back returns to the prior route.
5. **B4 untouched:** `git diff main --stat -- packages/` for the conversion PR is **empty**. All `/api/*` aliases (`/api/automations`, `/api/command/*`, …) keep answering — FE adapter calls unchanged.
6. **Migration clean (D1-3):** boot with a populated `waggle-window-state-v1` → lands on the salvaged route, chat persona/autonomy preserved per workspace, key **absent** from localStorage afterward; boot with a corrupt value → `/home`, key absent, no crash.
7. **Chat-as-widget (D1-4):** one chat per workspace at `/workspaces/:id/chat`; an in-flight agent stream survives navigating to `/memory` and back (ChatHost keep-alive); persona change in the widget header does not mutate the workspace record.
8. **First-run chat seeding (wizard onFinish):** completing the onboarding wizard lands on `/workspaces/<newId>/chat` with the wizard-chosen persona active in the widget header and the QW-1 starter prompt prefilled in the composer — behavioral parity with `handleOnboardingFinish` (`Desktop.tsx:309-313`) via the §4.2 seed API.
9. **Zero-rewrite (D1-1):** `git diff main --stat -- apps/web/src/components/os/apps apps/web/src/components/os/overlays` shows changes ONLY in `WorkspaceDesktopApp.tsx` (§5.2); all other screen/overlay files byte-identical.
10. **Gates:** FE vitest suite green (`--root apps/web`); `tsc -p apps/web/tsconfig.app.json` 0 errors; lint 0.

---

## 9. Deviations & flagged calls

Calls made here (not deferred). Each is reversible at route level without touching screens.

1. **`/marketplace` added** — the brief's 11 route groups omit the shipped S21 Extend surface (`dock-tiers.ts:78`). A dock-reachable screen with no URL would fail acceptance check 2. Top-level route, Extend zone.
2. **`/files` added** — Work-zone primary-spine entry (`dock-tiers.ts:55`) omitted by the brief. Same reasoning.
3. **`/launcher` (AI Tools) and `/room`, `/waggle-dance` added** — Extend/Intelligence dock entries omitted by the brief; `/launcher` additionally hosts the D6-ratified S14 relocation, and Room has a shipped keyboard shortcut. Killing them would strip ratified/shipped capability; Phase 0 freezes them as routes.
4. **System-zone surfaces nest under `/settings/*`** (vault, profile, mission-control, timeline, events, usage) instead of new top-level groups — keeps the brief's 11-group spine intact while giving every System surface a URL. They render full-canvas; SettingsApp is not modified.
5. **Four AppIds killed** (no route): `dashboard` (back-compat shim obsoleted by §3.3), `voice` + `mission-control`/`MissionControlApp` (no live opener anywhere — dead surfaces; D8 reassigns the "Mission Control" name to CockpitApp), `backup`/`BackupApp` (duplicated by `SettingsApp` `?tab=backup`). Files deleted in a later dead-code commit, not the conversion PR.
6. **`/approvals` ships tier-hidden (TEAMS), `/team` reserved + tier-hidden** — exact D5 parity with today's `filterByBillingTier`; "reserve /team, do NOT ship" is implemented as no-nav-below-TEAMS + no new Team code.
7. **Bare `/workspaces` redirects to `/home`** — no workspace-list screen exists; Home is the selector (A2). Building a list screen would be net-new scope.
8. **`WorkspaceDesktopApp` is the single sanctioned component edit** (controlled tab + chat-tab embed) — derived from D1 condition 4 itself, NOT separately ratified (the register's condition 1 says "as-is"); the two seams go to the founder for explicit sign-off with this plan, before P1a. Held to two seams and pinned by tests (§5.2).
9. **Conversion build assigned to P1a, before D3** — the ratification's phase list says "P1=D3" but leaves the D1 build unassigned; building the shell first means the structural auth gate is wired once, on the final spine.
10. **D1-c lite NOT invoked** — no hard detached-chat requirement found in code (§4.3); concurrent same-workspace multi-persona windows are consciously dropped. Re-proposable post-dogfood with evidence.
11. **Window-manager files deleted, not retained-for-rollback** — D1-3's "no z-order code ships" is read literally; rollback = `checkpoint/pre-appshell-2026-06` tag + single PR revert. The dead `GlobalSearch.tsx` goes with them.
12. **ChatHost keep-alive mounting** (one live `ChatWindowInstance` per visited workspace, hidden off-route) — not in the brief, but required so route navigation cannot kill in-flight agent SSE streams; this is the conversion's only behavioral guarantee carried over from windowing. Non-chat surfaces accept standard route remount semantics (server-side state, refetch on entry).

---
*Authored 2026-06-10 · Phase 0, UX Refactor v2.1 Launch Cut · implements ratified D1(b)*