# Waggle OS UX Refactor — Master Implementation Plan

> **This is a sequenced INDEX, not a re-paste.** Each phase references the detailed gap cards
> (`gap-cards/S00..S21.md`) and deltas (`deltas/*.md`) that carry the full build spec. It exists to
> put them in one coherent, dependency-ordered, full-stack sequence under the locked execution model.
> The PRD (`../Waggle_OS_UX_Refactor_Master_Handoff_Package/Waggle_OS_UX_Refactor_PRD.md`) is the
> source of truth; this plan resolves PRD §8, PRD §21 sprints, and Blueprint §19 roadmap into a single
> **Phase 0..6**. Every backend claim is grounded in `docs/backend-map/` or live source.

---

## 1. Executive summary, locked decisions, and the 8 non-negotiable product rules

### Executive summary

Waggle OS is today a single-route windowed desktop OS (`apps/web/src/components/os/Desktop.tsx` +
`Dock.tsx`; 27 `AppId` window types; no react-router) sitting on a deep, mostly-built backend substrate.
The refactor converts it into a **workspace-first Agent Desktop** whose spine is **Home Cockpit →
Workspace Desktop → Ctrl+K → visible Memory/Artifacts → Agents/Skills/Automations → governed Extend →
Team**. We deliver this as an **in-place incremental refactor** of `apps/web` + **targeted local-sidecar
extensions** — reusing `workspace-manager`, the `workspace-state` builder, the `.mind` schema, the
harvest pipeline, `install-audit`, and the approval/trust runtime. The total backend work resolves to
**53 endpoints** (35 net-new + 18 extend), **5 new sidecar route files** (`home.ts`, `command.ts`,
`artifacts.ts`, `agents.ts`, `mcps.ts`) + 1 alias plugin (`automations.ts`), **2 new JSON-file stores**
(`agents.json`, `artifacts.json`), **~13 new design-system components**, and **at most one conditional
SQLite migration** (`memory_frames.metadata`). All 21 numbered screens + the AppShell are covered.

### Locked decisions (founder, via PRD)

1. **In-place INCREMENTAL refactor** of `apps/web` + targeted backend extensions. NOT a rebuild.
2. **FULL-STACK** scope (net-new/extended backend APIs *and* frontend).
3. **Mockups are DIRECTIONAL** (PRD §24); PRD acceptance criteria win over pixels.
4. **Local-first by default** — desktop FE talks ONLY to the local sidecar (`:3333`).
5. **Backend-map is the contract reference**; ground every backend claim there or in live source.

### The 8 non-negotiable product rules (condensed handoff §"Non-negotiable product rules"; PRD §6)

1. **Workspace is the primary object.** Everything happens inside or across workspaces.
2. **Ctrl+K is always available** — search, launch, run, create, navigate, extend, from anywhere.
3. **Memory is visible, inspectable and editable** — source, confidence, scope, evidence, edit/delete.
4. **Artifacts are outcomes, not attachments** — documents/decks/sheets/dashboards/research are first-class.
5. **Connectors and MCPs live in Extend, not hidden Settings.**
6. **Agents must declare scope, model, memory, tools, skills, permissions, and autonomy** (no hidden access).
7. **No import or elevated tool access without explicit user approval.**
8. **Use existing backend foundations wherever possible** (do not duplicate backend state logic in the FE).

> PRD §20.4 "Avoid": do not add top-level apps that don't fit the IA; do not duplicate backend state
> calc in the FE; do not hide connectors/MCPs in Settings; **do not default to blank chat on launch**;
> do not let agents/automations gain hidden access.

---

## 2. Current state in one paragraph (from the inventories)

The FE is a **single `/` route** (`apps/web/src/pages/Index.tsx` → `BootScreen` → `Desktop`); all
"navigation" is window management in `useWindowManager.ts` keyed by `AppId` (27 ids in `lib/dock-tiers.ts`;
a stale 8-id `AppView` union and dead `terminal/calculator/notes` ids are cleanup candidates). The dock
(`Dock.tsx` + `lib/dock-tiers.ts`) already supports **zone-parent flyouts**, which is the hook for the new
Work/Intelligence/Extend/Team IA without a router. The single backend gateway is `lib/adapter.ts`
(~1930 LOC, ~150 methods); domain hooks (`useWorkspaces`, `useChat`, `useMemory`, …) wrap it. The
sidecar already serves **16 of 65** PRD §16 endpoints as-is and **30 more partially**; the rich substrate
already present includes: the `workspace-state` builder + `WorkspaceNow` block (Home/Workspace seed), the
full harvest engine (preview/commit/sources), `install_audit` + `trust-model` + the `confirmation.ts`
approval gate + persistent grants + the `approval_required` SSE event, the EU-AI-Act `ai_interactions`
append-only store, `cron` (the Automations capability), `teams.db` RBAC CRUD, and the `knowledge_*` graph.
The biggest **genuine gaps** are: **no Artifact entity/route** anywhere, **no sidecar `/api/agents/*`**
(only the cloud server has it), **MCP runtime never populated** (`local/index.ts:911`), and **memory has
no confidence/provenance/metadata column**. Design-wise the Hive DS (`ui/*`, ~50 shadcn primitives +
`waggle-theme.css` tokens) covers most needs; ~13 product-typed components are net-new.

---

## 3. Phase table (Phase 0..6)

> **Numbering reconciliation.** Three sources order the work slightly differently:
> **PRD §8** (Phase 0-5) and **PRD §21** (Sprint 1-9) put **Intelligence/builders (P3) BEFORE Extend
> (P4)**; the **Blueprint §19 roadmap** and the **condensed handoff sequence** put **Extend BEFORE
> builders**. The `backend-api-delta.md` already commits to the **PRD §8 ordering**. Because **the PRD
> wins** (locked decision 3 + "PRD acceptance criteria win"), this plan adopts **PRD §8 phase numbering**:
> P0 Align → P1 Core Runtime → P2 Work+Onboarding → **P3 Intelligence** → **P4 Extend** → P5 Team →
> **P6 Hardening** (PRD §21 Sprint 9 / Blueprint Phase 7, promoted to a first-class phase because PRD §26
> DoD #10 "all screens have required states" is otherwise the weakest-traced item — see coverage-check
> GAP-D4). Phases 3 and 4 are independent (see §4) and MAY be parallelized by separate streams, but the
> default sequence is PRD order.

**Verification gate for EVERY phase** (CLAUDE.md §2 — run, do not claim):
```
npx tsc --noEmit --project packages/shared/tsconfig.json      # if shared types touched
npx tsc --noEmit --project packages/hive-mind-core/tsconfig.json  # if substrate/migration touched
npx tsc --noEmit --project packages/server/tsconfig.json      # sidecar routes (NOT typechecked by npm run build)
npx tsc --noEmit --project packages/agent/tsconfig.json       # if agent runtime touched
npm run build           # typechecks apps/web (the FE)
npm run test -- --run   # vitest unit
npm run lint            # ESLint repo-wide (no-explicit-any is error repo-wide per CLAUDE.md §10)
```
Build order matters (CLAUDE.md §2 / MEMORY 0601 S3): **shared → hive-mind-core → core → agent → server**.

---

### Phase 0 — Architecture alignment & IA freeze

- **Goal:** freeze the IA + route/vocabulary names; establish the shared-type spine + DS token layer that
  every later write-path depends on. No new endpoints. (PRD §8 Phase 0 / §21 Sprint 1 / Blueprint P0.)
- **Screens delivered:** **S00 (AppShell + IA + Navigation)** — partial: the shell reframe + nav labels +
  Ctrl+K provider skeleton. (Full Ctrl+K UX lands in P1/S03.)
- **Frontend tasks**
  - *Keep-promote:* `Dock.tsx` + `lib/dock-tiers.ts` zone-parent model → regroup dock entries into
    **Work / Intelligence / Extend / Team / System** zones (PRD §10 IA) — no react-router (see open-question
    **B1**, recommended: in-place dock reframe, keep windowed `AppId` navigation). `Desktop.tsx`
    `appConfig` + `renderAppContent` switch stays the navigation engine.
  - *Rework:* consolidate the dual app-id union onto `AppId`; delete stale `AppView` + dead ids
    (`terminal/calculator/notes`) (`_inventory/frontend.md` §b). Add the **global Ctrl+K provider** shell
    (compose `ui/command.tsx`; absorb `overlays/GlobalSearch.tsx`).
  - *Create:* `components/os/AppShell.tsx` (compose `ui/sidebar.tsx` + `ui/scroll-area.tsx`),
    `WorkspaceSwitcher` (compose `ui/command.tsx` + `ui/dropdown-menu.tsx`), the `--sem-*` token alias layer.
  - **DoD #1 launch-flip (coverage-check GAP-D1):** change the boot default route so launch lands in
    **Home Cockpit**, not blank chat — S00 explicitly owns this (`pages/Index.tsx`/`Desktop.tsx` initial
    window). Even though S01 builds later, the routing decision is frozen here.
- **Backend tasks** (no routes; `backend-api-delta.md` "Phase 0")
  - `WorkspaceConfig` V2 additive optional fields (`description, type, status, agentIds[], connectorIds[],
    mcpIds[], updatedAt, lastActiveAt`) on `packages/hive-mind-core/src/workspace-manager.ts:5-58` +
    `CreateWorkspaceOptions:60-95`. **JSON file (`workspace.json`) — NO DB migration.**
  - Write-side stamps: `updatedAt` in `update()` (`workspace-manager.ts:222`); `lastActiveAt` from the
    chat/agent loop.
- **Shared-types changes** (`shared-types-delta.md` §1): add the PRD §15.2 union block to
  `packages/shared/src/types.ts` (`WorkspaceType, Scope, Confidence, MemoryKind, ArtifactKind, AgentType,
  AutonomyLevel, ExtensionType`) + export `interface WorkspaceConfigV2`; FE imports them into
  `apps/web/src/lib/types.ts`. **Enums live once in `@waggle/shared`** (no cross-file union duplication).
- **Design-system pieces** (`design-system-delta.md` §b): add `--sem-work/-intelligence/-healthy/
  -attention/-risk` alias vars in `waggle-theme.css` mapping to existing `--status-*` tokens. No new base
  palette. Build `AppShell` + `WorkspaceSwitcher` (compose existing primitives).
- **Exit criteria → PRD acceptance:** IA + route names frozen (no major UX ambiguity, Blueprint P0);
  shared types compile across packages; **launch no longer defaults to blank chat** (DoD #1 routing
  decision committed); dock shows the 5 IA zones.
- **Verify:** full gate; specifically `tsc` on `shared` + `hive-mind-core` (V2 fields) + `apps/web`.

---

### Phase 1 — Core runtime: Home Cockpit, Workspace Desktop, Command Center (Ctrl+K)

- **Goal:** the daily spine. A returning user "can continue work in under 30 seconds" (Blueprint P2 exit).
  (PRD §8 Phase 1 / §21 Sprints 2-3 / Blueprint P1-P2.)
- **Screens delivered:** **S01 Home Cockpit**, **S02 Workspace Desktop**, **S03 Command Center (Ctrl+K)**
  (S00 Ctrl+K provider completed here).
- **Frontend tasks**
  - *Keep-promote:* `components/os/WorkspaceBriefing.tsx` → **Home Cockpit** widgets (PRD §20.1 named seed);
    `DashboardApp.tsx` (workspaces grid) folds into Home. `ChatWindowInstance` `WorkspaceBriefing` home
    screen is the precedent.
  - *Create (S01):* `HomeCockpit` (PRD §20.3) — greeting + ranked workspace cards + suggested actions +
    overnight summary + quick-capture. Retire `overlays/LoginBriefing.tsx`, absorb its catch-up into first
    paint (open-question **C1**).
  - *Create (S02):* `WorkspaceDesktop` as a **maximized `AppWindow`** (open-question **C4/A1** — fixed
    layout v1, no parallel grid engine) with the **8 §12.2 tabs** incl. the **Settings tab** (coverage-check
    G1) and a Tasks tab seeded from `WorkspaceState` (open-question **C7**). Sessions surface via Timeline +
    Ctrl+K (coverage-check G2 — document this, do not build a separate Sessions screen v1).
  - *Create (S03):* `CommandCenter` Ctrl+K overlay on the P0 provider; result groups for the 6 verbs
    (search/launch/create/run/navigate/extend). Reuse the chat approvals pipeline for gated commands
    (open-question **C9**).
- **Backend tasks** (`backend-api-delta.md` Phase 1)
  - **New `routes/home.ts`:** `GET /api/home/briefing` (NET-NEW; cross-workspace ranker over
    `buildWorkspaceState()`/`buildWorkspaceNowBlock()`), `GET /api/home/overnight` (NET-NEW; since-last-login
    window).
  - **Extend `memory.ts`:** `POST /api/quick-capture` (thin handler → memory write + awareness row for tasks).
  - **Extend `workspaces.ts`:** `GET /api/workspaces/:id/state` (thin route over the existing builder),
    `GET /api/workspaces/:id/activity` (thin alias over events).
  - **New `routes/command.ts`:** `GET /api/command/search` (federates memory/workspaces/skills/sessions),
    `GET /api/command/recent`, `GET /api/command/suggestions` (NET-NEW); `POST /api/command/execute`
    (EXTEND/alias over existing plural `/api/commands/execute` — **alias, don't rename**, open-question **B4**).
  - *No backend* for S02 Tasks/Members/status-bar (all exist; compose client-side).
- **Shared-types changes:** FE `Workspace` view-model gains `description?/type?/status?/…` (`shared-types-delta`
  §2b); NEW shared `Command`/`CommandResult` (`shared-types-delta` §9); seed identity on the greeting path
  (open-question **B8** — onboarding writes profile AND identity so Home greets by name).
- **Design-system pieces:** `WorkspaceCard`, `EmptyState`, `ErrorState`, `Skeleton` compositions,
  `ActivityFeed`, `Timeline` (extract from `TimelineApp.tsx` + `lib/timeline-events.ts`), the Ctrl+K
  `CommandCenter` shell with a11y (`aria-label`, focus trap from cmdk).
- **Exit criteria → PRD acceptance:** PRD §22.1 "land in Home Cockpit and continue useful work" +
  "use Ctrl+K to find and run all major actions"; DoD #1/#2/#3. Home renders first-run-empty + daily +
  attention + overnight-failure states (PRD §14.2); Ctrl+K covers all 6 verbs (PRD §12.3).
- **Verify:** full gate; `tsc` on `server` (new `home.ts`/`command.ts`) + `apps/web`.

---

### Phase 2 — Work layer: Memory Center, Artifact Center, Onboarding, Workspace Creation

- **Goal:** memory + outcomes are visible and actionable; the day-0 onboarding chain works end-to-end.
  (PRD §8 Phase 2 / §21 Sprints 4-5 / Blueprint P3.)
- **Screens delivered:** **S04 Memory Center**, **S05 Artifact Center**, **S12 First Launch**,
  **S13 Who Are You**, **S14 Tool Discovery**, **S15 Memory Import**, **S16 Memory Review**,
  **S17 Workspace Creation**.
- **Frontend tasks**
  - *Rework:* `MemoryApp.tsx` → **Memory Center** (PRD §20.2) with source/confidence/evidence/scope +
    edit/merge/archive/delete; keep the working Graph tab (open-question **A3** — ship in v1) and the
    Harvest/Weaver/Wiki/Evolution tabs.
  - *Create (S05):* `ArtifactCenter` (PRD §20.3) grid/table + DetailDrawer + cross-object related search.
  - *Rework onboarding (PRD §20.2):* keep `OnboardingWizard.tsx` shell, redesign into the 5-step
    profile→tool-discovery→import→review→workspace chain (S12-S17), retrofitting the new `BuilderStepper`.
    **Split Import (stages previews) from Review (commits)** — current code commits at S15; fix per
    open-question **C33** ("nothing imports without review/approval").
- **Backend tasks** (`backend-api-delta.md` Phase 2)
  - **Extend `memory.ts`:** `GET /api/memory` (alias), `GET /api/memory/:id` (NET-NEW thin),
    `POST /api/memory` (alias), `PATCH /api/memory/:id` (PATCH+bare id), `POST /api/memory/:id/archive`
    (NET-NEW thin), `DELETE /api/memory/:id` (alias), `POST /api/memory/merge` (NET-NEW logic).
  - **Extend `harvest.ts`:** `preview` returns all items + per-item `confidence` + normalized `kind`;
    `commit` accepts `{selectedIds}`; new thin `POST /api/harvest/sources/:id/sync`.
  - **New `routes/artifacts.ts`** (largest net-new domain — aggregation only, no new data store):
    `GET /api/artifacts`, `POST`, `GET/:id`, `PATCH/:id`, `DELETE/:id`, `GET /api/artifacts/search-related`.
    Backed by a lightweight **`artifacts.json` index** over the existing file/document/storage stores
    (open-question **A6** — classification rule: artifact = explicit produced output, not every input).
  - **Extend `workspaces.ts`** (S17): richer `POST /api/workspaces` body (Phase-0 V2 fields); optionally
    extend `WorkspaceTemplate` shape. Record connector/MCP ids as **intent**, do not install at create time
    (open-question **C35**).
  - **Extend `profile.ts`** (S13): add `workType/teamSize/goals` to the allow-list; write profile AND seed
    identity (open-question **B8**). *S12/S14 need ZERO net-new backend* (catalogs already have routes).
- **Shared-types changes:** NEW shared `Memory` entity + FE view-model (`shared-types-delta` §3); NEW
  `Artifact` everywhere (§4); adopt PRD §15.2 `MemoryKind` canonical + a pure `lib/harvest-kind-map.ts`
  (open-question **B6**); confidence: heuristic at preview, LLM reserved for the standing J08 queue
  (open-question **B2**).
- **Migrations** (`backend-api-delta.md` §M): **M1 — `memory_frames.metadata TEXT` (CONDITIONAL)** — ship
  it *only* if persisted confidence/scope/status becomes a real filter axis (open-questions **A8/B2**); the
  idempotent ADD-COLUMN pattern is at `hive-mind-core/src/mind/db.ts:116-124`. **M1' — `artifacts` index**
  is a JSON file (no DB). Default: preview-only confidence + in-app filtering needs **no migration**.
- **Design-system pieces:** `ConfidenceBadge`, `EvidenceChip` (promote the `MemoryApp.tsx` provenance
  pill), `EvidencePanel`, `DetailDrawer` (wrap `ui/sheet.tsx` right-side), `StatusBadge` (semantic +
  non-color indicator — the biggest a11y gap vs `ui/badge.tsx`), `ViewToggle`, `BuilderStepper`
  (retrofit onboarding), `MemoryCard`/`ArtifactRow`.
- **Exit criteria → PRD acceptance:** PRD §22.1 "inspect and edit memory"; DoD #4 (source/confidence/
  evidence/scope/edit/delete) + #5 (artifact outcome + related search, the "Germany GTM" cross-object
  acceptance PRD §12.5) + #6 (onboarding chain). Memory states §14.4 + Extension/Workspace states render.
- **Verify:** full gate; if M1 ships, `tsc` + `npm run test` on `hive-mind-core` (migration) + a migration
  round-trip test; `tsc` on `server` (new `artifacts.ts`) + `apps/web`.

---

### Phase 3 — Intelligence layer: Agents, Skills, Automations (+ builders)

- **Goal:** users can create/run the core intelligence objects with validation + review. (PRD §8 Phase 3 /
  §21 Sprint 6 / Blueprint P5 "Builders".) **Independent of Phase 4** (see §4).
- **Screens delivered:** **S09 Agent Center**, **S18 Agent Builder**, **S06 Skills Hub**, **S19 Skill
  Builder**, **S11 Automation Center**, **S20 Automation Builder**.
- **Frontend tasks**
  - *Rework:* `AgentsApp.tsx` (Personas) → **Agent Center** tabs (All/Personal/Workspace/Team/Autonomous/
    Archive; Templates is a side affordance — open-question **C22**); `CapabilitiesApp.tsx` → **Skills Hub**;
    `ScheduledJobsApp.tsx` → **Automation Center**.
  - *Create:* `AgentBuilder` (PRD §20.3, §12.9 stepper — declares goal/scope/model/memory/tools/skills/
    permissions/autonomy), `SkillBuilder` (§12.6 stepper), `AutomationBuilder` (§12.10 stepper). Reuse the
    `BuilderStepper` from P2.
- **Backend tasks** (`backend-api-delta.md` Phase 3)
  - **New `routes/agents.ts`** (sidecar `/api/agents/*` is absent — only the cloud server has it):
    `GET /api/agents`, `POST`, `GET/:id`, `PATCH/:id` (NET-NEW over a new **`agents.json`** store, mirrors
    `agent-groups.json` — open-question **B3**); `POST /api/agents/:id/run` (EXTEND → real executor
    `POST /api/fleet/spawn`, NOT the `agent-groups/:id/run` stub), `POST /api/agents/:id/pause` (EXTEND →
    fleet pause), `GET /api/agents/:id/traces` (NET-NEW read over `execution_traces`).
  - **Extend `skills.ts`:** `PATCH /api/skills/:id` + `POST /api/skills/:id/test` (`:id` variants over the
    existing name-keyed handlers); `POST /api/skills/:id/install` (NET-NEW dispatcher: starter/pack/
    marketplace). Skill **create** is the existing `POST /api/skills/create` (the Builder's real target).
  - **New `automations.ts` alias plugin over cron:** `GET/POST/PATCH /api/automations`, `/:id/run`,
    `/:id/pause`, `/:id/logs` (all EXTEND aliases over `/api/cron/*`); `POST /api/automations/test`
    (NET-NEW no-persist dry-run — do NOT reuse `cron/:id/trigger` which executes+auto-enables,
    open-question **C26**). Also fix the FE bug: `updateCronJob` calls `PUT` but only `PATCH` is registered
    (`adapter.ts:836` vs `cron.ts`). Triggers/conditions/actions ride the existing `job_config TEXT` blob —
    **no migration**. Schedule-only triggers v1; defer Event triggers (open-question **C24**).
- **Shared-types changes:** MODIFY shared `AgentDef` with §15.5 fields + NEW FE `Agent` view-model
  (`shared-types-delta` §5); NEW `Skill` entity (§6); NEW `Automation` superset of `CronJob` (§7). Adopt PRD
  `organization` skill-scope vocabulary (open-question **C36**).
- **Migrations:** **M3 — `agents` table is OPTIONAL and NOT recommended for v1** (use `agents.json`). No
  required migration in this phase.
- **Design-system pieces:** `AgentCard`, `SkillCard`, `AutomationRunRow`, `BuilderStepper` reuse,
  `ApprovalModal` (wrap `ui/alert-dialog.tsx`) for agent-elevation/automation-test approvals.
- **Exit criteria → PRD acceptance:** PRD §22.1 "create a workspace, agent, skill, and automation"; DoD #7
  (coherent IA across agents/skills/automations). Agent states §14.5 + Automation states §14.6 render;
  agent declares all §12.9 fields (rule #6); automation failures surface to Home (Journey 16 — wire the
  `home/overnight` failure feed to S11/S20).
- **Verify:** full gate; `tsc` on `agent` (if runtime touched) + `server` (new `agents.ts`/`automations.ts`)
  + `apps/web`.

---

### Phase 4 — Extend layer: Connectors, MCPs, Marketplace, Install Audit

- **Goal:** capabilities are discoverable, installable, and **governed** (Blueprint P4 exit). (PRD §8
  Phase 4 / §21 Sprint 7.) **Independent of Phase 3** (see §4).
- **Screens delivered:** **S07 Connector Hub**, **S08 MCP Hub**, **S21 Marketplace / Extend Waggle**.
- **Frontend tasks**
  - *Rework:* `ConnectorsApp.tsx` → **Connector Hub** (lift connectors out of the Services/MCP-tabs shell);
    the MCP catalog tab → standalone **MCP Hub**; consolidate the **doubly-represented Marketplace**
    (`MarketplaceApp.tsx` + the `CapabilitiesApp` marketplace section) into one **Marketplace / Extend**
    surface (`_inventory/frontend.md` §f IA cleanup).
  - *Create:* the unified Extend faceted catalog (S21) federating the six local domains client-side
    (open-question **A5** — federate-at-read, no `marketplace.db` migration). Install modals render the
    `TrustAssessment` (risk badge + permission summary via `formatTrustSummary`) + a revoke action.
- **Backend tasks** (`backend-api-delta.md` Phase 4)
  - **Extend `connectors.ts`:** `POST /api/connectors/:id/sync` (NET-NEW, **phased stub** — MVP =
    `healthCheck()` + stamp `lastSyncAt`; full data re-pull deferred, coverage-check **C1**/open-question
    **C16**), `POST /api/connectors/:id/revoke` (EXTEND alias → disconnect + audit), `connect` (+audit),
    `GET /api/connectors` (payload enrichment), optional `/health` + `/activity`.
  - **New `routes/mcps.ts` + the foundational runtime work:** `GET /api/mcps`, `POST /api/mcps/install`
    (via the existing marketplace installer → writes `.mcp.json`), `POST /api/mcps/:id/test`,
    `/:id/revoke`, `POST /api/mcps` (custom), `/:id/start`, `/:id/stop`, `PATCH /:id/permissions`,
    `GET /:id/logs` (phased — deferred if no log-capture infra, coverage-check **C2**). **CRITICAL
    foundational task (coverage-check C4):** populate `mcpRuntime` at boot from persisted config
    (`local/index.ts:911` is empty today) — this is not a route, it is the work item that unblocks ALL MCP
    routes; treat it as an explicit, estimated Phase-4 task. MCP `test` semantics (live handshake vs static
    validation) must be resolved first (coverage-check **C3** / open-question **C21**).
  - **Marketplace + shared audit:** `GET /api/marketplace` (bare-path alias), `GET /api/extend/audit?type=`
    (EXTEND — the read route exists at `/api/audit/installs`; add the filter param to serve S06/S07/S08/S21
    with one route, open-question **C18**).
- **Shared-types changes:** MODIFY FE Connector to consume shared `ConnectorDefinition`/`ConnectorHealth`
  (`shared-types-delta` §8a — a consumption switch, no new shape); NEW `McpInstance` (§8b); resolve the
  `ExtensionType` union to `skill|agent|connector|mcp|model|template` (open-question **B7**).
- **Migrations:** **M2 — `install_audit` risk-level CHECK fix (RECOMMENDED, pre-Phase-4).** The TS
  `AuditRiskLevel` includes `'critical'` but both DDL CHECKs allow only `low/medium/high`
  (`install-audit.ts:65` + `schema.ts:130`) → a `record({riskLevel:'critical'})` throws. Pick: widen the
  CHECK (additive migration) **or** lock the CRITICAL→`'high'`+`approvalClass:'blocked'` mapping as the
  permanent contract (zero-migration). Fix **before** any Extend install-audit write path ships
  (coverage-check **C15**).
- **Design-system pieces:** `ConnectorCard`, `MCPRow`, `ApprovalModal` reuse for install-risk approval,
  the install-audit feed (normalizer over the three audit stores).
- **Exit criteria → PRD acceptance:** PRD §22.1 "install/revoke connector/MCP with audit trail"; DoD #7;
  Extension states §14.7 render; MCP "auditable/permissioned/health-checked" (§12.8) — with the documented
  v1 caveats (connector-sync stub C1, MCP logs C2). Tier-gate MCP/Marketplace install at **PRO+** through
  `@waggle/shared tiers.ts` (open-question **B5**).
- **Verify:** full gate; if M2 ships as a migration, `tsc` + test on `hive-mind-core`/`core`; `tsc` on
  `server` (new `mcps.ts`) + `apps/web`; smoke the boot-time MCP runtime population.

---

### Phase 5 — Team intelligence: Team Workspace, RBAC, Sharing, Audit views

- **Goal:** team workflows are permissioned + auditable (Blueprint P6 exit). (PRD §8 Phase 5 / §21 Sprint 8.)
- **Screens delivered:** **S10 Team Workspace** (+ the RBAC/Audit components PRD §20.3 — see RBAC-owner note).
- **Frontend tasks**
  - *Rework/create:* `TeamGovernanceApp.tsx` + `searchTeamMemory` surface → **Team Workspace** with the
    **role→capability matrix** table (PRD §17.2), member list with role dropdown (CRUD endpoints exist),
    invite flow (Journey 13), "request access" on permission-denied. **RBAC matrix has no dedicated card
    today (coverage-check GAP-D2)** — S10 must own the §17.2 matrix UI (or add an RBAC/Audit card).
  - *Create:* unified **Audit Views** (normalize the three audit stores by scope) + CSV/PDF export buttons
    over the existing endpoints; per-object **Share** UI.
- **Backend tasks** (`backend-api-delta.md` Phase 5; `rbac-security-delta.md`)
  - **Extend `team.ts`:** `POST /api/teams/:id/invite` (alias → `/members`), `GET /api/teams/:id/audit`
    (alias → `/activity`), **fix the PUT(owner-only) vs PATCH(owner/admin) role-gate inconsistency** on
    `members/:memberId` (`team.ts:615` vs `:642` — open-question **A7**).
  - **NEW `POST /api/share`** (no such route exists) — share memory/artifact/workspace with role perms;
    gate behind TEAMS tier. **NEW `POST /api/artifacts/:id/share`** (blueprint). Optional
    `GET /api/teams/:id/governance` (surface capability policies/overrides/requests).
- **Shared-types changes:** unify the role enum in `@waggle/shared` — `TeamRole =
  owner|admin|member|viewer(|guest)`, map PRD "Contributor"→"Member", defer/decide Guest (open-question
  **A7** + rbac-delta §1). Add a shared `requireRole`/`can()` helper used by both `team.ts` and cloud routes.
- **Migrations:** keep the live `teams.db` 4-role union (no migration) per the recommended A7 answer; a
  `teams.db` CHECK migration is **only** needed if Guest is adopted. Frame-level `/api/share` scope may need
  M1 (`memory_frames.metadata`) — v1 can scope implicitly via workspace `teamId`.
- **Design-system pieces:** role→capability matrix table, `ApprovalModal`/audit-feed reuse, avatar stack.
- **Exit criteria → PRD acceptance:** PRD §22.1 "team user can share memory/artifact with role-appropriate
  permissions"; DoD #8 (shared intelligence + roles) + #9 (approval-gated + audited). Workspace
  permission-denied + archived states render (PRD §14.3 / Journey 19).
- **Verify:** full gate; `tsc` on `shared` (role enum) + `server` (team routes) + `apps/web`; RBAC
  enforcement tests.

---

### Phase 6 — Hardening: states, a11y, approval/audit consistency, performance, dogfood

- **Goal:** close the cross-cutting DoD items the screen phases leave under-traced. (PRD §21 Sprint 9 /
  Blueprint P7. Promoted to a first-class phase because PRD §26 DoD #10 + #9 are otherwise the weakest
  links — coverage-check GAP-D3/GAP-D4.)
- **Screens delivered:** none new — every S00-S21 screen gets its **§14 state matrix** completed.
- **Frontend + cross-cutting tasks**
  - **Screen × §14-state coverage grid (GAP-D4).** Build/verify all **9 global states** (PRD §14.1:
    Loading/Empty/Populated/Error/Offline/Syncing/Permission-denied/Partial/Approval) on every major screen
    + each screen's specific states (§14.2-§14.7). Cards S02/S18/S20/S21 are visibly thin on state
    enumeration — close them. The DS primitives (`EmptyState`/`ErrorState`/`Skeleton`/`StatusBadge`) ship in
    P0-P3; this phase wires them per-screen and proves coverage in a grid artifact.
  - **Approval & Audit as a cross-cutting contract (GAP-D3).** No single card owns the "which actions are
    sensitive, what the approval payload is, what gets audited" taxonomy today, risking per-builder drift.
    Define the canonical gated-action taxonomy + `ApprovalModal` contract once (an S00 sub-spec) and retrofit
    S03/S08/S18/S19/S20. Reuse the built runtime: `needsConfirmationWithAutonomy`, the `approval_required`
    SSE event, `/api/approval/*`, persistent grants (rbac-delta §2).
  - **Journey → screen trace (coverage-check #11).** Verify the 20 PRD §13 journeys end-to-end, especially
    J15 (agent approval), J16 (overnight failure → Home attention, spans S01+S11+S20), J19 (archive), J20
    (delete memory).
  - **A11y, performance, real-data dogfood, visual polish** (PRD §19.3 + §21 Sprint 9). Light-mode QA on
    data-heavy Memory/Artifact tables (Blueprint).
- **Backend tasks:** append-only triggers on the sensitive `install_audit`/`audit_events` subset (rbac-delta
  §3.2, reconcile with retention); resolve any deferred Phase-4 caveats (connector-sync real pull, MCP logs)
  if scheduled.
- **Exit criteria → PRD acceptance:** PRD §22.2 technical acceptance (every new screen has loading/empty/
  error/offline/permission states; sensitive actions approval-gated; types consistent with API; no
  mock-only screens where backend exists); DoD #9 + #10 + #11. All §22.3 QA scenarios pass.
- **Verify:** full gate + `npm run test:e2e` (Playwright) + visual regression; the per-screen state grid is
  the acceptance artifact.

---

## 4. Critical path / dependency notes

```
P0 (IA freeze + shared types + V2 fields + --sem-* tokens)
   └─ blocks EVERYTHING (every write-path uses V2 fields; every component uses the token layer & unions)
P1 (Home, Workspace, Ctrl+K)
   ├─ S01 Home depends on workspace-state builder (exists) + S03 Ctrl+K (greeting depends on identity seed, B8)
   ├─ S03 Ctrl+K provider skeleton starts in P0, completes in P1; S01/S02 consume it
   └─ blocks P2 (Memory/Artifact detail surfaces are reached via Workspace tabs + Ctrl+K)
P2 (Memory, Artifacts, Onboarding, Workspace Creation)
   ├─ Artifact entity (artifacts.json) is the single largest net-new domain; gates artifact-share in P5
   ├─ Memory metadata decision (M1) shared by S04 + S16; resolve B2/A8 BEFORE coding
   └─ Onboarding Import/Review split (C33) is correctness-relevant
P3 (Agents, Skills, Automations + builders)  ──┐ independent of P4
P4 (Connectors, MCPs, Marketplace)           ──┤ may run in parallel by separate streams
   ├─ P4 has the deepest hidden task: MCP boot-time runtime population (C4) — unblocks ALL MCP routes
   ├─ M2 install-audit CHECK fix must land BEFORE any Extend install-audit write (C15)
   └─ both P3 & P4 reuse the BuilderStepper (P2) and ApprovalModal
P5 (Team, RBAC, Sharing)
   ├─ depends on Artifact (P2) for artifact-share and on the unified role enum (A7) ratified before S10
   └─ frame-level /api/share may need M1 (P2) if not scoped via workspace teamId
P6 (Hardening)
   └─ depends on ALL screens existing; closes the cross-cutting DoD #9/#10/#11
```

**Hard blockers to ratify before coding starts:** the Phase-blocking founder items in §7. **Single biggest
hidden-effort item:** MCP boot-time runtime population (P4). **Single largest net-new domain:** Artifacts
(P2). **Most error-prone reuse:** alias-don't-rename the command/automations/connector-revoke vocabularies
(B4) — exhaustive grep on any rename per CLAUDE.md §3.5.

---

## 5. Net-new backend endpoint master list (summary)

Full per-endpoint spec (method/path/disposition/build-target/substrate/shape/screens) lives in
[`deltas/backend-api-delta.md`](./deltas/backend-api-delta.md). Summary counts:

- **Total endpoints requiring backend work: 53** (de-duplicated NET-NEW + EXTEND).
  - **NET-NEW: 35** — Home ×2, Command ×3, Memory ×3, Artifacts ×6, Agents ×5, Skills ×1, Automations ×1,
    Connectors ×3, MCPs ×8, Team ×3.
  - **EXTEND: 18** — quick-capture, workspace state/activity, command/execute, 4× memory aliases,
    harvest preview/commit + sources/sync, workspaces POST, agents run/pause, skills :id/test, 6×
    automations aliases over cron, connectors revoke/connect/payload, mcps/install, marketplace bare,
    extend/audit filter, team invite/audit/members-gate-fix.
- **PRD §16 cross-reference:** of the 65 §16-literal endpoints — **16 EXIST** (FE wiring only), **30
  PARTIAL** (→ EXTEND), **19 MISSING** (→ NET-NEW). The delta adds **~16 blueprint-implied** endpoints
  beyond the literal §16 set (MCP start/stop/logs/permissions/custom, connector health/activity,
  automations/test, team governance, artifact-share, extend/audit) — over-, not under-, coverage. All
  **65/65 §16 endpoints are addressed** (coverage-check Table 2).
- **New sidecar route files: 5** (`home.ts`, `command.ts`, `artifacts.ts`, `agents.ts`, `mcps.ts`) + 1
  alias plugin (`automations.ts` → cron). **New JSON-file stores: 2** (`agents.json`, `artifacts.json`).
- **Schema migrations:** **1 conditional** (M1 `memory_frames.metadata`, P2/P5) + **1 recommended** (M2
  `install_audit` CHECK fix, pre-P4) + **1 optional/deferred** (M3 `agents` table — NOT for v1). Net
  likely-to-ship: **1**; **0 strictly required** if S16 confidence stays preview-only and `/api/share`
  scopes via workspace `teamId`.
- **Phase-0 non-endpoint work:** 5 interface/field extensions (`WorkspaceConfig` V2 + write-stamps, FE type
  unions, `UserProfile` fields, `WorkspaceTemplate` shape, `Connector` fields).

---

## 6. Risk register

PRD §24 risks + risks surfaced by the coverage-check / deltas:

| # | Risk | Source | Impact | Mitigation (in this plan) |
|---|---|---|---|---|
| R1 | UX becomes too complex | PRD §24 | High | Keep Home/Workspace/Ctrl+K as the spine (P0-P1); hide power features behind the IA zones until needed. |
| R2 | Backend not ready for all screens | PRD §24 | Med | In-place reuse + thin adapters; mock catalog only where safe (PRD §22.2); **A4** = real-where-substrate-exists. |
| R3 | Memory trust issues | PRD §24 | High | Source/confidence/evidence/review/edit/delete (P2); ConfidenceBadge + EvidencePanel; heuristic-then-LLM (**B2**). |
| R4 | Agent safety | PRD §24 | High | Explicit permissions + approval prompts + audit (rule #6/#7); reuse `confirmation.ts` + approval SSE. |
| R5 | Marketplace scope creep | PRD §24 | Med | Federate-at-read local catalog (**A5**); postpone billing/public marketplace + remote registry (PRD §4.4). |
| R6 | Team RBAC complexity | PRD §24 | Med | Keep the live 4-role union (**A7**); shared `requireRole`/`can()`; defer Guest. |
| R7 | Global-search performance | PRD §24 | Med | Local indexed providers + async result groups (S03). |
| R8 | Visual mocks overfit | PRD §24 | Med | PRD acceptance > pixels (locked decision 3). |
| R9 | **Per-screen state coverage under-traced (DoD #10)** | coverage-check GAP-D4 | High | **Phase 6** state-coverage grid; primitives shipped P0-P3. |
| R10 | **Approval/audit owned by no card (DoD #9)** | coverage-check GAP-D3 | High | Phase 6 cross-cutting Approval&Audit spec (S00 sub-spec); reuse built runtime. |
| R11 | **MCP runtime never populated** (unblocks all MCP routes) | coverage-check C4 | High | Explicit, estimated **Phase-4** boot-time population task (not a footnote). |
| R12 | RBAC role-vocabulary divergence (3 enums, no Guest, PUT/PATCH gate bug) | rbac-delta §1 | Med | Unify enum in `@waggle/shared` (P5); fix the gate; ratify **A7** before S10. |
| R13 | install-audit `critical` CHECK throws on write | coverage-check C15 / rbac §3.2 | Med | **M2** fix before any Extend install write (pre-P4). |
| R14 | Connector `/sync` is a cosmetic stub vs §12.7 "data flowing" | coverage-check C1 | Med | Flag v1 partial; schedule real connector-SDK pull (Phase 6/post-v1). |
| R15 | Sessions not a first-class browsable object | coverage-check G2 | Low | Document Timeline+Ctrl+K as the v1 session UX; soften the §11 "navigable" claim. |
| R16 | Sidecar type errors ship undetected (`tsx` transpile-only) | CLAUDE.md §2 | Med | Run `tsc --project packages/server` in every phase gate (not just `npm run build`). |
| R17 | Build-order/stale-dist hides breakage behind green CI | MEMORY 0601 S3 | Med | Enforce shared→hive-mind-core→core→agent→server; nuclear-clean before release verify. |

---

## 7. Founder sign-off gate (open questions to answer before each phase)

Full options + tradeoffs + RECOMMENDED answers in [`deltas/open-questions.md`](./deltas/open-questions.md).
**Coding on a phase MUST NOT start until its blocking questions are ratified.**

### Before Phase 0/1 (the spine) — `[BLOCKS P1]` — ✅ ALL RATIFIED 2026-06-09 (founder)
All five spine recommendations ratified as-is; **Phase 0 is unblocked.**
- **B1** ✅ **RATIFIED** Shell topology — in-place dock reframe, keep windowed `AppId` nav (no react-router);
  group dock into Work/Intelligence/Extend/Team zones. The IA freeze; gates everything.
- **A1** ✅ **RATIFIED** Workspace Desktop layout — fixed layout v1 (PRD §12.2 self-answers).
- **A2** ✅ **RATIFIED** Home Cockpit scope — personal-only v1; team summary appended later behind RBAC.
- **B4** ✅ **RATIFIED** `/api/*` vocabulary — alias, don't rename (command/automations/connector-revoke).
- **B8** ✅ **RATIFIED** Identity store of record — onboarding writes profile AND seeds identity (correct greeting).

### Before Phase 2 (work + onboarding) — `[BLOCKS P2]`
- **A6** Artifact storage — *Rec: `artifacts.json` index over existing workspace storage; artifact = produced output.*
- **A8** Memory retention/delete — *Rec: soft-status in metadata (Archive reversible), hard delete with consequence confirm.*
- **B2** Memory confidence — *Rec: cheap heuristic at preview; LLM reserved for the standing J08 queue.*
- **B6** `MemoryKind` reconciliation — *Rec: PRD §15.2 `MemoryKind` canonical in `@waggle/shared` + pure map helpers.*
- **A3** Memory graph view — *Rec: ship in v1 (substrate works); default = keep.*
- **C33** Import↔Review commit split — *Rec: S15 stages previews, S16 commits (fix current commit-at-S15).*
- **M1 decision** — ship `memory_frames.metadata` only if confidence/scope/status becomes a real filter axis.

### Before Phase 3 / 4 / 5 (not P1/P2-blocking, but ratify before the owning screen)
- **B3** Agent vs Persona boundary + store — *Rec: real Agent entity in `agents.json` referencing `personaId`.* (P3)
- **C24/C26** Automation triggers + test-run — *Rec: schedule-only v1; no-persist dry-run route.* (P3)
- **A4** Which connectors/MCPs are real — *Rec: real-where-substrate-exists, catalog-for-the-rest.* (P4)
- **A5/B7** Marketplace local-vs-remote + `ExtensionType` — *Rec: federate-at-read; `skill|agent|connector|mcp|model|template`.* (P4)
- **B5** Tier-vocabulary — *Rec: document mapping, route gates through `tiers.ts`, MCP/Marketplace install = PRO+.* (P4)
- **C21/C3** MCP `test` semantics — *Rec: live spawn-and-`isHealthy()`/`tools/list`; fall back to static validation.* (P4, resolve before S08)
- **C15** install-audit `critical` CHECK — *Rec: ship the migration (M2) for correctness.* (pre-P4)
- **A7** Minimum-viable RBAC — *Rec: keep live `owner/admin/member/viewer`, Contributor==Member, defer Guest, fix PUT/PATCH gate.* (ratify before S10)

---

## 8. Definition of Done checklist (PRD §26)

The refactor is done when all 11 hold. Mapped to the phase that delivers each (coverage-check Table 3):

- [ ] **1. Home Cockpit replaces blank-chat launch behavior.** — P0 (routing flip, GAP-D1) + P1 (screen).
- [ ] **2. Workspace Desktop is the default runtime for workspace work.** — P0 (route) + P1 (S02).
- [ ] **3. Ctrl+K can search, launch, create, run, navigate, and extend.** — P0 (provider) + P1 (S03; all 6 verbs).
- [ ] **4. Memory Center exposes source, confidence, evidence, scope, and edit/delete.** — P2 (S04/S16; M1 if filterable).
- [ ] **5. Artifact Center supports outcome search and related objects.** — P2 (S05; `/search-related`).
- [ ] **6. Onboarding leads profile → tool-discovery → import → review → first workspace.** — P2 (S12-S17 chain).
- [ ] **7. Agents, skills, automations, connectors, MCPs, marketplace have coherent IA.** — P3 + P4 (Work/Intelligence/Extend zones).
- [ ] **8. Team workspace supports shared intelligence and roles.** — P5 (S10 + RBAC matrix, GAP-D2).
- [ ] **9. Sensitive actions are approval-gated and audited.** — cross-cutting; ownership consolidated in **P6** (GAP-D3).
- [ ] **10. All screens have required states.** — **P6** screenק14-state grid (the weakest-traced item, GAP-D4).
- [ ] **11. Claude Code can continue implementation from this PRD without product interpretation.** — this doc set is the evidence.

**Plus PRD §22.2 technical acceptance** (verify in P6): no mock-only screens where backend exists; new
components have loading/empty/error/offline/permission states; sensitive actions approval-gated; state
derivation centralized in the backend; FE types consistent with API contracts; existing foundations reused.

---

*Synthesized from PRD §6/§8/§14/§16/§20/§21/§26, Blueprint §19 roadmap, the condensed implementation
handoff, the 3 inventories, the 22 gap cards (S00-S21), and the 6 deltas. All file/line citations are
grounded in live source or the audited `docs/backend-map/`.*