waggle-os/docs/ux-refactor/_inventory/frontend.md

Frontend Inventory — apps/web/src

Baseline for the Waggle OS UX-refactor planning track. Enumerates the current web frontend so all downstream planners share one ground-truth map. Every entry is grounded in source under D:/Projects/waggle-os/apps/web/src. Execution model is locked as an in-place incremental refactor of this code — this is the surface that gets extended, not replaced.

Entry point chain: main.tsx → App.tsx (ServiceProvider → QueryClientProvider → TooltipProvider → BrowserRouter) → pages/Index.tsx (route /) → BootScreen then Desktop. There is no react-router-based navigation between apps — routing is a single / page; all "navigation" is window management inside Desktop.tsx.

---

(a) App shells, overlays, and OS-level components

components/os/apps/* — per-app window content (26 top-level + 3 sub-dirs)

File	1-line role
ChatApp.tsx	Core chat surface: message list + block rendering + composer + autonomy picker + persona header. The product's primary work surface.
ChatWindowInstance.tsx	Per-window wrapper around ChatApp — owns session selection, model selector, autonomy state, WorkspaceBriefing home screen; one instance per chat window.
DashboardApp.tsx	"Home" / Workspaces grid — lists workspaces, select/create, opens chat per workspace. Mapped to dock key home.
MemoryApp.tsx	Memory hub with 6 tabs: Timeline (frames), Graph (KG), Harvest (import other-AI convos), Weaver (distillation), Wiki (compiled pages), Evolution (self-evolving prompts).
FilesApp.tsx	File-manager layout shell (FileTree + FilePreview + FileActions + FileUploadZone).
FilesAppTabs.tsx	P16 three-tab wrapper around FilesApp — Virtual / Local / Team storage; remounts FilesApp per storageType. This is what Desktop renders for files.
AgentsApp.tsx	"Personas" manager — list/create/edit personas + agent groups; uses agents/ subcomponents.
ConnectorsApp.tsx	Connectors manager with 2 tabs: Services (native connectors w/ status+actions) and MCP Servers (catalog).
CapabilitiesApp.tsx	"Skills & Apps" — starter packs, capability packs, and a Marketplace packs section (marketplace is folded in here, not a separate dock entry).
MarketplaceApp.tsx	Standalone marketplace browser (search/install/uninstall packages). Registered in Desktop appConfig as marketplace but no dock entry points at it (CapabilitiesApp hosts the surface).
CockpitApp.tsx	"Command Center" — system health, agent activity, cost/usage tiles; hosts cockpit/ComplianceDashboard.
MissionControlApp.tsx	Fleet/spawn overview + AI-tool inventory tile; "Spawn Agent" entry point.
RoomApp.tsx	The Room canvas — live sub-agent tiles across all workspaces via useRoomState SSE.
WaggleDanceApp.tsx	Multi-agent coordination signal feed (discovery/handoff/insight/alert/coordination) with detail pane + ack.
EventsApp.tsx	Agent event/log stream (think/tool_call/tool_result/response/error/spawn) with filter + autoscroll + abort.
TimelineApp.tsx	Per-workspace chronological timeline of tool/model/cost events (GET /api/events).
TelemetryApp.tsx	"Usage & Telemetry" — token/cost/tool-call totals, telemetry enable/clear.
ScheduledJobsApp.tsx	Cron jobs manager (list/create/update/delete/trigger).
ApprovalsApp.tsx	Approvals inbox (Phase B.3) — Pending requests tab + grants tab; same backend as inline chat approvals.
BackupApp.tsx	Backup & Restore — backup metadata, create/restore; 404 treated as "no backups yet".
SettingsApp.tsx	Settings shell with 8 tabs: General, Models, Billing, Permissions, Team, Backup, Enterprise, Advanced.
VaultApp.tsx	Secret vault — Secrets tab (add/delete keys) + additional tab(s).
UserProfileApp.tsx	"My Profile" — identity questionnaire, writing-style analysis, brand extraction, research (tabbed).
VoiceApp.tsx	Voice interaction surface (speech recognition / TTS).
TeamGovernanceApp.tsx	Team Governance panel (Teams-tier; roles/permissions surface).
LauncherApp.tsx	AI-OS tool launcher dock surface — detect/install-hooks/launch external AI tools (claude-code/cursor/claude-desktop launch cohort; codex/hermes/openclaw stubbed).

Sub-directories under apps/:

• agents/ — AgentCard.tsx, AgentDetail.tsx, CreateAgentForm.tsx, CreateGroupForm.tsx, GroupCard.tsx, GroupExecutionPanel.tsx (Personas/agent-group UI parts).
• chat-blocks/ — BlockRenderer.tsx, ModelSwitchBlock.tsx, StepBlock.tsx, ToolUseBlock.tsx (renders the ContentBlock union inside chat messages).
• cockpit/ — ComplianceDashboard.tsx.
• connectors/ — BrandTile.tsx, McpServerCard.tsx.
• files/ — FileActions.tsx, FilePreview.tsx, FileTree.tsx, FileUploadZone.tsx, SyntaxPreview.tsx, WorkspaceRail.tsx.
• memory/ — EvolutionTab.tsx, WeaverPanel.tsx, WikiTab.tsx.

components/os/overlays/* — modals, drawers, switchers (14)

File	1-line role
OnboardingWizard.tsx	First-launch wizard (rendered as full-screen early-return from Desktop when !onboardingState.completed); uses onboarding/ step components.
OnboardingTooltips.tsx	Post-wizard "Tour" overlay (4 slides: commands, dock, memory, closing).
LoginBriefing.tsx	Session-start "I remember…" briefing — memory highlights + cross-workspace catch-up with workspace links.
GlobalSearch.tsx	Ctrl+K command palette + global search; navigates commands/workspaces/memory.
PersonaSwitcher.tsx	Persona picker (two-tier: universal modes + workspace specialists; hover tagline/bestFor/wontDo). Operates on focused chat window's persona or patches workspace.
WorkspaceSwitcher.tsx	Workspace quick-switcher list (filters E2E/test artefact names).
SpawnAgentDialog.tsx	Spawn a sub-agent (task + persona + model + parent workspace).
CreateWorkspaceDialog.tsx	New-workspace dialog (name/group/persona/template).
NotificationInbox.tsx	Notifications drawer (mark read / mark all read).
KeyboardShortcutsHelp.tsx	Keyboard shortcuts cheat-sheet modal.
ContextRail.tsx	Right-side rail showing full context for a clicked frame/entity (Phase C.1). Exports ContextRailTarget.
UpgradeModal.tsx	Upgrade/start-trial modal; calls startTrial / createCheckoutSession.
TrialExpiredModal.tsx	Trial-expired blocking modal → upgrade.
EraseDataDialog.tsx	GDPR Art. 17 erasure confirmation (3-state); triggered from Settings → General.

Sub-directory overlays/onboarding/: WelcomeStep.tsx, TierStep.tsx, ApiKeyStep.tsx, ReadyStep.tsx.

components/os/*.tsx — shell/runtime + shared OS components (12)

File	1-line role
Desktop.tsx	Root OS shell. Wires all domain hooks + window manager + overlays; holds appConfig (title/icon/pos/size per appId) and renderAppContent (the appId→component switch).
Dock.tsx	Bottom dock — renders tier-filtered DockEntry[], zone-parent flyouts (via DockTray), open/minimized indicators, Spawn Agent button, Waggle badge.
DockTray.tsx	Portal-to-body flyout popover for a dock zone-parent's children.
AppWindow.tsx	Draggable/resizable/snappable/maximizable window chrome (title bar, min/max/close, edge+corner resize, left/right/top snap, position persistence).
StatusBar.tsx	Top bar — logo, workspace name, focused-window label, model, memory-frame trophy count, dev tokens/cost, trial badge, Search button, notifications bell, offline indicator, clock.
BootScreen.tsx	Animated boot splash (5 phases, click/key to skip); shown before Desktop.
ErrorBoundary.tsx	App-level error boundary (AppErrorBoundary) wrapping each window's content + the whole app.
ContextMenu.tsx	Generic right-click context menu primitive (used by MemoryApp frames etc.).
LockedFeature.tsx	Tier-gated "locked" overlay/badge for features above the user's plan.
ModelSelector.tsx	Reusable model picker (Settings/Onboarding/workspace-create/spawn); fetches via useProviders.
ModelPilotCard.tsx	3-lane model fallback visualizer (Primary → Fallback → Budget Saver).
WorkspaceBriefing.tsx	ChatApp "home screen" when no messages — greeting/memories/decisions/tasks/suggested prompts from GET /api/workspaces/:id/context.

---

(b) Shell / runtime — how the window manager, dock, and nav work

There is no per-app route. The window manager is hooks/useWindowManager.ts, consumed by Desktop.tsx. App opening is keyed by AppId, not by URL.

Window manager (useWindowManager(workspaces, { defaultAutonomy }))

• State: windows: WindowState[] (persisted to localStorage key waggle-window-state-v1, version-gated), focusedInstanceId, z-index counter, cascade counter.
• WindowState fields: instanceId, appId, workspaceId?, workspaceName?, personaId?/personaLabel?, templateLabel?, initialMessage?, autonomyLevel?/autonomyExpiresAt?, zIndex, minimized, cascadeOffset.
• How apps open by appId: openApp(id: AppId) — for non-chat apps it reuses an existing window of that appId (focus + un-minimize) or pushes a new WindowState; for chat it always allows multiples. openChatForWorkspace(workspaceId, name?, personaOverride?, initialMessage?) — reuses the workspace's existing chat window unless a personaOverride is given (deliberate second specialist); seeds per-window persona + inherited defaultAutonomy.
• Per-window controls: setWindowPersona, setWindowAutonomy (TTL auto-revert every 10 s), closeApp, minimizeApp, focusWindow, cycleWindowFocus (Ctrl+), closeTopWindow, minimizeTopWindow, getWindowTitle`.
• Reconciliation: migrates restored chat windows off the local-default placeholder onto the first real workspace; never deletes windows for missing workspaces.
• Derived: openAppIds, minimizedAppIds (drive dock indicators).

How Desktop renders a window

appConfig: Record<string, {title, icon, pos, size}> keyed by appId provides chrome defaults. renderAppContent(win: WindowState) is a switch (win.appId) mapping each appId to its component with props. Position resolved via getSavedPosition(appId) (from lib/window-positions.ts) or computeCascadePosition (from lib/window-cascade.ts). Cross-component waggle:open-app CustomEvent lets any surface raise a window.

Dock + nav (Dock.tsx + lib/dock-tiers.ts)

• getDockForTier(tier: UserTier, billingTier: BillingTier) returns a DockEntry[], recursively filtered by minBillingTier.
• DockEntry.type ∈ 'app' | 'zone-parent' | 'separator'. Zone-parents (Ops, Extend) open a DockTray flyout of child apps.
• TIER_DOCK_CONFIG defines docks per UserTier (simple/professional/power/ admin; power===admin===POWER_CONFIG). UserTier is the UI density tier (from onboarding), distinct from the billing tier.
• Clicking a dock app calls onOpenApp(id) → Desktop routes chat to openChatForWorkspace, everything else to openApp.

The two app-id unions (IMPORTANT for the refactor)

• AppId (canonical, in lib/dock-tiers.ts, re-exported from Dock.tsx) — 27 ids: chat, dashboard, memory, events, capabilities, connectors, cockpit, mission-control, settings, vault, profile, terminal, calculator, notes, waggle-dance, files, agents, scheduled-jobs, marketplace, voice, room, approvals, timeline, backup, telemetry, governance, launcher. (terminal/calculator/notes are declared but have no app component / appConfig entry — dead ids.)
• AppView (legacy, in lib/types.ts) — only 8 ids: chat, dashboard, memory, events, capabilities, cockpit, mission-control, settings. Stale/partial union, superseded by AppId. Not used by the window manager. Flag for cleanup.

Keyboard shortcuts (hooks/useKeyboardShortcuts.ts, wired in Desktop)

onOpenApp, onToggleGlobalSearch (Ctrl+K), onTogglePersonaSwitcher, onToggleWorkspaceSwitcher, onToggleKeyboardHelp, onCloseTopWindow, onMinimizeTopWindow, onNewChatWindow; plus Ctrl+` window cycle in the WM itself.

---

(c) Data layer — adapter singleton, ServiceProvider, domain hooks

lib/adapter.ts — LocalAdapter singleton (exported adapter)

The single HTTP/SSE gateway to the Fastify sidecar. All fetch go through adapter.fetch(path, init) (adds base URL, auth token, content-type, 403/tier handling). Base URL resolved from getServerUrl(). Full method → endpoint map (grounded in line numbers in adapter.ts):

Connection / system: connect() (/api/auth/session-token, health), setServerUrl/getServerUrl, fetch, getSystemHealth (/api/health via connect), connectWebSocket.

Workspaces / templates: getWorkspaces GET /api/workspaces; createWorkspace POST /api/workspaces; updateWorkspace PUT /api/workspaces/:id; patchWorkspace PATCH /api/workspaces/:id; deleteWorkspace DELETE; getWorkspaceContext GET /api/workspaces/:id/context; getWorkspaceFiles …/files; getWorkspaceTemplates GET /api/workspace-templates; createWorkspaceTemplate/updateWorkspaceTemplate/ deleteWorkspaceTemplate; generateTemplateFromPrompt …/generate.

Files / browse: browseLocal GET /api/browse/local; browseLocalMkdir; listFiles …/files/list; uploadFile …/files/upload; downloadFile; createDirectory …/files/mkdir; deleteFile; moveFile; copyFile.

Chat / sessions / history: sendMessage (async generator over SSE) POST /api/chat; abortAgent POST /api/agent/abort; clearHistory DELETE /api/chat/history; getHistory GET /api/history; getSessions …/sessions; createSession; renameSession; deleteSession; searchSessions …/sessions/search; exportSession …/sessions/:id/export.

Memory / KG / identity: getMemoryFrames GET /api/memory/frames; addMemoryFrame; updateMemoryFrame; deleteMemoryFrame; incrementFrameAccess …/frames/:id/access; searchMemory GET /api/memory/search; searchTeamMemory /api/team/memory/search; getKnowledgeGraph GET /api/memory/graph; getMemoryStats /api/memory/stats; getIdentity /api/identity; getMindIdentity/getMindAwareness/getMindSkills /api/mind/*.

Agent / models / providers: getEvents GET /api/events; getTimeline /api/events; subscribeEvents SSE /api/events/stream; getEventStats /api/events/stats; getAgentStatus /api/agent/status; getAgentCost /api/agent/cost; setModel/getModel /api/agent/model; getModels /api/litellm/models; getProviders /api/providers; getLiteLLMStatus /api/litellm/status; getModelPricing /api/litellm/pricing; getLocalInferenceHardware/-Models/-Status/pullLocalModel /api/local-inference/*.

Skills / capabilities / marketplace: getSkills /api/skills; createSkill; getStarterPacks /api/skills/starter-pack/catalog; getCapabilityPacks /api/skills/capability-packs/catalog; installPack /api/skills/starter-pack/:id; getCapabilitiesStatus/getCapabilityStatus /api/capabilities/status; getMarketplacePacks /api/marketplace/packs; searchMarketplace/getMarketplaceInstalled/ installMarketplacePackage/uninstallMarketplacePackage/installMarketplacePack/ uninstallMarketplacePack /api/marketplace/*.

Fleet / agents / groups / jobs: getFleet /api/fleet; fleetAction /api/fleet/:ws/:action; spawnAgent /api/fleet/spawn; getPersonas/createPersona/ deletePersona/updatePersona/generatePersona /api/personas*; getAgentGroups/ createAgentGroup/deleteAgentGroup/updateAgentGroup/runAgentGroup /api/agent-groups*; getJobStatus /api/jobs/:id; cancelJob …/cancel.

Cron: getCronJobs/createCronJob/updateCronJob/deleteCronJob/triggerCronJob /api/cron*.

Notifications / approvals: subscribeNotifications SSE /api/notifications/stream; getNotificationHistory; markNotificationRead; markAllNotificationsRead; getPendingApprovals /api/approval/pending; respondApproval /api/approval/:id; getApprovalGrants/revokeApprovalGrant/clearApprovalGrants /api/approval/grants*; subscribeSubagentStatus (SSE, drives Room); subscribeHarvestProgress.

Settings / permissions / keys: getSettings/saveSettings /api/settings; getPermissions/savePermissions /api/settings/permissions; testApiKey /api/settings/test-key.

Connectors / vault / profile: getConnectors /api/connectors; getConnectorHealth; connectConnector/disconnectConnector; getVault/addVaultSecret/deleteVaultSecret /api/vault*; getProfile/updateProfile/analyzeWritingStyle/analyzeBrand/ researchProfile /api/profile*.

Team: teamConnect/teamDisconnect/getTeamStatus/getTeamMembers/getTeamActivity/ getTeamMessages /api/team/*.

Costs / telemetry: getCosts /api/costs; getCostByWorkspace; getCostSummary /api/cost/summary; getTelemetryStatus/toggleTelemetry/clearTelemetry/trackTelemetry /api/telemetry/*.

Billing / tier / data: syncStripeCheckout /api/stripe/sync; createCheckoutSession /api/stripe/create-checkout-session; createPortalSession; getTier /api/tier; startTrial /api/tier/start-trial; eraseData /api/data/erase.

Harvest / import: importPreview/importCommit /api/import/*; harvestPreview/harvestCommit /api/harvest/*; getHarvestSources; scanClaudeCode /api/harvest/scan-claude-code; extractHarvestIdentity; getLatestInterruptedHarvestRun; resumeHarvestRun; abandonHarvestRun; removeHarvestSource; toggleHarvestAutoSync.

Wiki: getWikiPages/getWikiPage/getWikiPageContent/compileWiki/getWikiHealth/ getWikiWatermark/exportWikiToObsidian/exportWikiToNotion /api/wiki/*.

Compliance: getComplianceStatus/exportComplianceReportPdf/exportComplianceReport/ getComplianceInteractions/getComplianceModels/listComplianceTemplates/ createComplianceTemplate/updateComplianceTemplate/deleteComplianceTemplate /api/compliance/*.

Misc: getWeaverStatus /api/weaver/status; getAuditInstalls /api/audit/installs; ingestFile /api/ingest; executeCommand /api/commands/execute; getPins/addPin/removePin /api/workspaces/:id/pins*; getDocuments/getDocumentVersions …/documents*; submitFeedback /api/feedback; getWaggleSignals/publishWaggleSignal/ acknowledgeWaggleSignal /api/waggle/signals*; subscribeWaggleDance SSE /api/waggle/stream; AI-OS tools: detectTools /api/tools/detect, launchTool /api/tools/launch, getToolProcesses /api/tools/processes, killTool /api/tools/kill, manageHooks /api/tools/hooks.

providers/ServiceProvider.tsx

The only React provider for the adapter. Calls adapter.connect() on mount, exposes { adapter, connected, connecting, error, reconnect } via useService(). Note: most hooks import adapter directly rather than via useService — context is mainly for connection status.

Domain hooks (hooks/*) — name → adapter methods / endpoints

Hook	Returns / role	Adapter methods used
useWorkspaces	workspaces, activeWorkspace(Id), select/create/delete/patch, refresh	getWorkspaces, createWorkspace, deleteWorkspace, patchWorkspace
useChat({workspaceId,sessionId,persona,autonomy})	messages, isLoading, sendMessage, clearHistory, pendingApproval, approveAction	getHistory, sendMessage (SSE), clearHistory, respondApproval
useSessions	sessions, activeSessionId, create/delete/rename	getSessions, createSession, deleteSession, renameSession
useMemory	filtered frames, selectedFrame, filters, add/edit/delete/incrementAccess, stats	getMemoryFrames, searchMemory, getMemoryStats, addMemoryFrame, updateMemoryFrame, deleteMemoryFrame, incrementFrameAccess
useKnowledgeGraph	nodes, edges, scope (current/personal/all), refresh	getKnowledgeGraph
useEvents	steps, filter, autoScroll	getEvents, subscribeEvents (SSE)
useAgentStatus	model/tokens/cost/isActive/offline (polled, backoff)	getAgentStatus
useNotifications	notifications, unreadCount, markRead, markAllRead	getNotificationHistory, subscribeNotifications (SSE), markNotificationRead, markAllNotificationsRead
useWaggleDance	signals (filtered), allSignals, publish, acknowledge, refresh	getWaggleSignals, subscribeWaggleDance (SSE), publishWaggleSignal, acknowledgeWaggleSignal
useRoomState	per-workspace live/recent sub-agent map, totalLive	subscribeSubagentStatus (SSE) → lib/room-state-reducer.ts
useProviders	providers, models, search providers, available/active models	getProviders
useBilling	tier, refreshTier, syncAfterCheckout, startCheckout, openPortal	getTier, syncStripeCheckout, createCheckoutSession, createPortalSession
useFeatureGate	planTier, isEnabled(feature), gate(feature)	(none; reads useOnboarding + lib/feature-gates)
useOnboarding	onboarding state (localStorage waggle:onboarding), update/complete/reset/replayTour	getWorkspaces (returning-user auto-complete) + tauri-bindings
useOverlayState	all overlay open/close flags + toggles	(none; pure UI state)
useWindowManager	window list + all window ops (see §b)	(none; localStorage only)
useEvents/useSessions/useMemory etc. are workspace-scoped
useKeyboardShortcuts	binds global hotkeys to callbacks	(none)
useDockLabels, useDockNudge	dock label visibility + milestone nudges	(none / local)
useDeveloperMode, useIsLightTheme, useOfflineStatus, useContainerWidth, useFocusTrap, use-mobile, use-toast	UI/utility hooks	(none)

lib/ also holds many pure helper + state modules (most with co-located .test.ts): brain-health, briefing-highlights, browse-breadcrumbs, chat-header-layout, context-rail-fetch, cron-presets, dedupe-packs, dock-labels, dock-nudge, feature-gates, fetch-utils, fuzzy-match, login-briefing(-brag), memory-recall-toast, modal-drag, onboarding-skip, onboarding-tier-filter, persona-tier, persona-tooltip, persona-display, personas, posthog, providers, render-markdown, room-state-reducer, settings-tier-filter, shape-selection, skill-pack-display, skill-recommendations, spawn-agent-helpers, status-bar-focus, suggested-actions, tauri-bindings, timeline-events, tiers, utils, waggle-signals, window-cascade, window-positions, workspace-briefing-state, workspace-groups, kg-export, launcher-prompt-args, context-menu-index, decode-entities.

---

(d) lib/types.ts — exported types

Type aliases / unions: AppView (legacy 8-id, stale — see §b), StorageType, TemplateCategory, ContentBlock (union).

Interfaces: StorageConfig, Workspace, FileEntry, WorkspaceTemplate, WorkspaceContext, ChatMessage, ToolExecution, ApprovalRequest, MemoryFrame, AgentStep, TimelineEvent, TextContentBlock, StepContentBlock, ToolUseContentBlock, ModelSwitchContentBlock, ErrorContentBlock, Session, SkillPack, FleetSession, CronJob, Notification, AgentStatus, Persona (incl. tagline/bestFor/wontDo/isReadOnly), SystemHealth, Connector, StreamEvent, Settings, KGNode, KGEdge, ModelPricing, WaggleSignal.

Notable type sources outside types.ts: AppId/UserTier/BillingTier/ DockEntry in lib/dock-tiers.ts; WindowState/AutonomyLevel in hooks/useWindowManager.ts; OnboardingState in hooks/useOnboarding.ts; PlanTier/FeatureGate in lib/feature-gates.ts; Provider/ProviderModel/ SearchProvider in hooks/useProviders.ts; RoomAgent/WorkspaceAgents in lib/room-state-reducer.ts; ContextRailTarget in overlays/ContextRail.tsx.

---

(e) Design-system primitives — components/ui/* (shadcn/ui, ~50)

Standard shadcn/ui set: accordion, alert, alert-dialog, aspect-ratio, avatar, badge, breadcrumb, button, calendar, card, carousel, chart, checkbox, collapsible, command, context-menu, dialog, drawer, dropdown-menu, form, hover-card, input, input-otp, label, menubar, navigation-menu, pagination, popover, progress, radio-group, resizable, scroll-area, select, separator, sheet, sidebar, skeleton, slider, sonner, switch, table, tabs, textarea, toast, toaster, toggle, toggle-group, tooltip. Waggle-specific addition: hint-tooltip.tsx (HintTooltip, used across StatusBar/AppWindow). Toast plumbing duplicated in both components/ui/use-toast.ts and hooks/use-toast.ts. Theming via waggle-theme.css + index.css (Hive DS semantic tokens: honey/hive-950/accent; data-theme on <html> toggles dark/light, observed by Desktop). Also components/NavLink.tsx (single router NavLink, near-unused given single-route app).

---

(f) Current apps → new IA buckets (PRD §10)

PRD IA layers: Global, Work (10.2), Intelligence (10.3), Extend (10.4), Team (10.5), System (10.6). Mapping the existing apps/surfaces to the locked Work / Intelligence / Extend / Team / System buckets:

Bucket (PRD)	Existing apps / surfaces
Global (cross-cutting)	GlobalSearch (Ctrl+K), NotificationInbox, StatusBar, Dock, BootScreen, LoginBriefing, OnboardingWizard/Tooltips.
Work	DashboardApp (Home Cockpit/Workspaces), ChatApp/ChatWindowInstance + WorkspaceBriefing (Sessions), MemoryApp (Memory: Timeline/Graph/Harvest/Weaver/Wiki), FilesApp(Tabs) (Artifacts), TimelineApp, EventsApp (session/agent activity), WorkspaceSwitcher/CreateWorkspaceDialog.
Intelligence	AgentsApp (+agents/ + PersonaSwitcher + SpawnAgentDialog) = Agents; CapabilitiesApp (Skills); ScheduledJobsApp (Automations); RoomApp + MissionControlApp + WaggleDanceApp (multi-agent orchestration); MemoryApp → Evolution tab (traces/evolutions); ApprovalsApp (agent governance/decisions).
Extend	ConnectorsApp (Connectors + MCP catalog), MarketplaceApp + CapabilitiesApp marketplace section (Marketplace), LauncherApp (External tools), ModelSelector/ModelPilotCard + Settings→Models (Models).
Team	TeamGovernanceApp (members/roles), searchTeamMemory surface (shared memory), Settings→Team tab, CockpitApp → ComplianceDashboard (activity/audit).
System	SettingsApp (8 tabs: General/Models/Billing/Permissions/Team/Backup/Enterprise/Advanced), VaultApp (Security/secrets), UserProfileApp (Profile), BackupApp (Backup/restore + data), TelemetryApp (usage), EraseDataDialog (data deletion), UpgradeModal/TrialExpiredModal (Billing/plan).

Refactor-relevant observations (grounded, for downstream planners):

• The product is a single-route windowed desktop, not a navigable app. The new IA's Work/Intelligence/Extend/Team/System "layers" must be expressed through the existing dock zones (dock-tiers.ts zone-parent model) + window manager, not new routes.
• Dual app-id union drift: AppId (27, canonical) vs AppView (8, stale in types.ts). The refactor should consolidate on AppId; AppView and the dead ids terminal/calculator/notes are cleanup candidates.
• Marketplace is doubly represented (standalone MarketplaceApp with no dock entry + a section inside CapabilitiesApp) — IA cleanup point.
• UserTier (UI density: simple/professional/power/admin) ≠ BillingTier (FREE/TRIAL/PRO/TEAMS/ENTERPRISE) ≠ PlanTier (solo/teams/business/enterprise in feature-gates). Three overlapping tier vocabularies the new IA gating will have to reconcile.
• Adapter is a fat single file (lib/adapter.ts, ~1930 lines, ~150 methods) and is the one contract surface to the sidecar — new PRD §16 endpoints get added here.