waggle-os/docs/ux-refactor

Waggle OS UX Refactor — Analysis & Plan Index

This folder is the product-interpretation layer between the UX-Refactor PRD (the source of truth) and the code. It exists so an implementing agent can build the refactor screen-by-screen without re-deriving product decisions. Everything here is source-grounded against live code under apps/web/src, packages/server/src, and packages/hive-mind-core/src — every claim cites a real file (and line where load-bearing).

---

Executive summary (one paragraph)

Waggle OS today is a single-route windowed desktop OS (apps/web/src/components/os/Desktop.tsx

• Dock.tsx, 27 AppId window types, no react-router navigation) with a deep, mostly-built backend substrate (workspace-manager, workspace-state builder, .mind schema, harvest pipeline, install-audit, approval/trust runtime). The refactor turns it into a workspace-first Agent Desktop whose spine is Home Cockpit + Workspace Desktop + Command Center (Ctrl+K) + visible Memory + Artifacts + Agents/Skills/ Automations + a governed Extend layer + Team. The locked execution model is an in-place incremental refactor of apps/web plus targeted local-sidecar (Fastify) backend extensions — not a rebuild — because most PRD §16 endpoints either exist or can be aliased/extended over existing handlers; the master list resolves to 53 endpoints of real backend work (35 net-new + 18 extend), 5 new sidecar route files, 2 new JSON-file stores, and at most one conditional SQLite migration. All 21 numbered screens + the AppShell are covered by a gap card; the highest residual risks are cross-cutting (per-screen state coverage, approval/audit ownership, RBAC role unification, MCP runtime population).

The master plan is IMPLEMENTATION-PLAN.md. Start there once you have read the locked decisions below.

---

Locked decisions (do not relitigate)

1. Execution model = in-place INCREMENTAL REFACTOR of apps/web + targeted backend extensions. NOT a from-scratch / Lovable rebuild. Reuse the existing substrate (workspace-manager, workspace-state builder, .mind schema, install-audit, ai_interactions).
2. Scope = FULL-STACK. The plan covers net-new/extended backend APIs and frontend, because many PRD §16 endpoints do not exist yet.
3. Mockups are DIRECTIONAL visual reference (PRD §24), not pixel-perfect targets. PRD acceptance criteria win over pixels.
4. Local-first by default (PRD §6.7). The desktop frontend talks ONLY to the local sidecar (packages/server/src/local/index.ts, loopback :3333); the Clerk-gated cloud server is out of scope.
5. Backend-map is the contract reference (docs/backend-map/README.md + sections/ + DIAGRAMS/, audited ~96%). Ground every backend claim there or in live source.

---

Recommended reading order

1. This README — orientation + locked decisions.
2. PRD (source of truth) — ../Waggle_OS_UX_Refactor_Master_Handoff_Package/Waggle_OS_UX_Refactor_PRD.md.
3. IMPLEMENTATION-PLAN.md — the phased full-stack master plan (Phase 0..6).
4. Inventories (current state) — read the three _inventory/*.md before touching code.
5. Deltas (what changes) — deltas/*.md, especially backend-api-delta.md and open-questions.md.
6. Gap cards (per-screen build specs) — gap-cards/S00..S21.md, pulled in by the phase that owns them.
7. deltas/coverage-check.md — the adversarial completeness audit; read its "Concrete gaps to fix" list and confirm the plan addresses each.

---

Inventories — current state (_inventory/)

Doc	What it maps
_inventory/frontend.md	Every apps/web/src surface: 26 apps, 14 overlays, the window-manager/dock shell, the adapter.ts HTTP/SSE gateway (~150 methods), domain hooks, lib/types.ts, the ui/* DS primitives, and current-apps → new-IA bucket mapping.
_inventory/backend-routes.md	Every existing local-sidecar endpoint by domain + a PRD §16 cross-reference (65 endpoints: 16 EXIST / 30 PARTIAL / 19 MISSING).
_inventory/substrate-types.md	WorkspaceConfig vs §15.3, workspace-state outputs, .mind schema, memory frames, install-audit, and FE↔BE type drift.

Deltas — what the refactor adds/changes (deltas/)

Doc	What it specifies
deltas/backend-api-delta.md	The build contract. Consolidated, de-duplicated, phase-ordered master list of every endpoint to build/extend (53 with backend work) + schema migrations (§M). New route files + JSON stores + counts.
deltas/shared-types-delta.md	PRD §15.2 unions + entity shapes (Memory, Artifact, Agent, Skill, Automation, McpInstance, Command) — NEW vs MODIFY, and where each lives (@waggle/shared vs FE lib/types.ts).
deltas/design-system-delta.md	PRD §19 component list mapped to the live Hive DS: EXISTS vs BUILD-NEW (~13 new DS components), the --sem-* color-semantic alias layer, dark-default/light-variant, a11y obligations.
deltas/rbac-security-delta.md	PRD §17/§18: the two divergent RBAC planes, the approval/consent runtime (strong, reuse it), the three audit stores, and the security build order.
deltas/open-questions.md	The founder-ratification list: the 8 PRD §23 questions (§A), cross-cutting decisions blocking ≥2 screens (§B), screen-local questions (§C), each with a RECOMMENDED answer + the phase it blocks.
deltas/coverage-check.md	Adversarial completeness audit: 21/21 screens + 65/65 §16 endpoints + 11/11 DoD items traced; surfaces the cross-cutting gaps (screen×state grid, approval/audit owner, RBAC matrix, sessions-as-object, connector-sync stub, MCP runtime).

Gap cards — per-screen build specs (gap-cards/)

Each card carries: screen & purpose · required states · current-state-in-repo disposition · frontend work (keep-promote / rework / create, real paths) · backend work (PRD §16 mapping) · shared types · dependencies · effort · open questions.

Card	Screen	PRD §	Phase (this plan)
S00	AppShell + IA + Navigation	§1, §19.1, §20.3	0
S01	Home Cockpit	§12.1	1
S02	Workspace Desktop	§12.2	1
S03	Command Center (Ctrl+K)	§12.3	1
S04	Memory Center	§12.4	2
S05	Artifact Center	§12.5	2
S06	Skills Hub	§12.6	3
S07	Connector Hub	§12.7	4
S08	MCP Hub	§12.8	4
S09	Agent Center	§12.9	3
S10	Team Workspace	§12.11	5
S11	Automation Center	§12.10	3
S12	Onboarding · First Launch	§12.12	2
S13	Onboarding · Who Are You	§12.12	2
S14	Onboarding · Tool Discovery	§12.12	2
S15	Onboarding · Memory Import	§12.12	2
S16	Onboarding · Memory Review	§12.12	2
S17	Workspace Creation	§12.12	2
S18	Agent Builder	§12.9	3
S19	Skill Builder	§12.6	3
S20	Automation Builder	§12.10	3
S21	Marketplace / Extend Waggle	§12.13	4

---

How this set was assembled

The 3 inventories were read out of live source; the 22 gap cards were written one-per-screen against PRD §12 + the blueprint screen specs; the 6 deltas consolidate the cross-screen contracts (API, types, DS, RBAC) and the founder decisions; the coverage-check is an adversarial audit proving completeness against PRD §12 (screens), §16 (endpoints), and §26 (Definition of Done). The IMPLEMENTATION-PLAN.md sequences all of it into one phased Phase 0..6 program under the locked in-place refactor model.

Maintained alongside docs/backend-map/ (the source-grounded backend contract) and CLAUDE.md (the operating contract — verification commands in §2, file-org rules in §3).