oleg.m/waggle-os
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

moving
Some checks failed
Installer Smoke / installer-smoke (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Oleg Maslov
2026-09-02 10:10:29 +02:00
commit 0c3e2ead3b
3841 changed files with 970576 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

335
docs/ux-refactor/2D-BUILD-PLAN.md Normal file
View File

@@ -0,0 +1,335 @@
# Phase 2D — Onboarding Chain · Build Plan
> Scope: the day-0 onboarding/first-run chain (PRD §12.12 / DoD #6). Execution model is LOCKED:
> **in-place incremental refactor** of `apps/web` + targeted sidecar extension. PRD acceptance criteria
> win over mockups (PRD §24). Every claim below is grounded in live source under
> `D:/Projects/waggle-os-ux-refactor` (paths cited inline).
>
> **Critical reuse note:** Harvest preview-classification (C33 unreviewed + B2 confidence + B6 kind) was
> already built in **Phase 2B.3** (`harvest-classify.ts`, `harvest.ts` preview/commit, `harvest-kind-map.ts`)
> and the Memory Center "Needs review" review surface was built in **Phase 2B-FE.2** (`MemoryCenterTab.tsx`).
> 2D **reuses** these; it does NOT rebuild classification, confidence, or the review queue.
---
## 1. CURRENT vs TARGET
### Current OnboardingWizard (8 steps, `apps/web/src/components/os/overlays/OnboardingWizard.tsx`)
`STEP_NAMES` (`OnboardingWizard.tsx:35`):
`welcome → why-waggle → tier → memory-import → template → persona → api-key → ready` (steps 0–7).
| Step | Component | Wired vs hardcoded |
|---|---|---|
| 0 welcome | `WelcomeStep` | Hardcoded brand copy; 3s auto-advance (`:136-141`). |
| 1 why-waggle | `WhyWaggleStep` | Hardcoded `VALUE_PROPS` (`constants.ts:111`); "Skip and set me up" escape hatch (`:271-304`). |
| 2 tier | `TierStep` | `selectedTier` → `onUpdate({tier})` (UI density, not billing). |
| 3 memory-import | `ImportStep` | **Wired**: `harvestPreview`/`harvestCommit`/`scanClaudeCode` (`:156-202`). Commits inline then `goToStep(4)`. |
| 4 template | `TemplateStep` | Hardcoded 15 `TEMPLATES` (`constants.ts:10`), `TEMPLATE_PERSONA` map. |
| 5 persona | `PersonaStep` | `ALL_ONBOARDING_PERSONAS` (`constants.ts:46`) + custom-persona create. |
| 6 api-key | `ModelTierStep` | Model/key; calls `handleFinish` → `adapter.createWorkspace` (`:306-354`). |
| 7 ready | `ReadyStep` | Auto-finish after 2s. |
State backbone: `useOnboarding.ts` `OnboardingState` (`:10-19`) = `{ completed, step, tier?, workspaceId?,
apiKeySet?, templateId?, personaId?, tooltipsDismissed? }`, localStorage key `waggle:onboarding`. Resume is
half-built: `state.step` persists; returning-user auto-complete via Tauri flag + `getWorkspaces().length>0`
(`:102-176`). `?forceWizard=true` (DEV) forces step 0.
**There is NO profile/"Who Are You" step, NO Tool Discovery step.** The current IA (tier/api-key/model) is the
OLD onboarding, not the PRD §12.12 flow.
### Target — PRD §12.12 5-step chain (S12–S17)
PRD order: **First Launch (S12) → Who Are You (S13) → Tool Discovery (S14) → Memory Import (S15) →
Memory Review (S16) → Workspace Creation (S17) → Home Cockpit**. Per the ratified C33 decision, Memory
**Review (S16) is NOT a blocking onboarding step** — import commits immediately as `status:'unreviewed'`,
and review happens later in the Memory Center "Needs review" filter / J08 queue. So the in-wizard chain is
effectively **5 interactive steps**: First Launch → Who Are You → Tool Discovery → Memory Import →
Workspace Creation, with a Ready/handoff terminal.
Target step mapping (keep the existing wizard shell + AnimatePresence switch; re-key `STEP_NAMES`):
```
0 first-launch (S12) rework WelcomeStep
1 who-are-you (S13) NEW WhoAreYouStep ← B8 profile + identity seed
2 tool-discovery (S14) NEW ToolDiscoveryStep (DEFERRABLE — see §6 note)
3 memory-import (S15) rework ImportStep — commit-as-unreviewed (C33)
4 workspace-create (S17) route through CreateWorkspaceDialog step bodies (or inline)
5 ready keep ReadyStep
```
> S16 Memory Review is delivered by the **already-shipped** Memory Center "Needs review" filter
> (`MemoryCenterTab.tsx:25-31`), NOT a wizard step. This is the C33 ratification (below).
### Explicit gate ratifications (verbatim, from `deltas/open-questions.md`)
- **B8** (`open-questions.md:28, :350`): *"Onboarding writes profile AND seeds the `identity` table."* /
*"Write profile + seed identity in the same onboarding commit. Rationale: prevents the two-store drift…
makes the Phase-1 Home greeting correct."* **[BLOCKS P1 greeting]**
- **C33** — RESOLVED to the middle path (`open-questions.md:45-53`): *"Commit-as-unreviewed, non-blocking
review: onboarding Import commits immediately (memory feels alive on first run), but frames land with
`status:'unreviewed'` + the B2 confidence score; Review is a **non-blocking** curation surface (Memory
Center "needs review" filter + the standing J08 queue), NOT a blocking onboarding step… Supersedes the
original §C C33 'blocking split' recommendation."*
- **B2** (`:39`): *"cheap heuristic at preview (source-trust × adapter-type × dedup), persisted in `metadata`…
LLM scoring reserved for the standing J08 queue."*
- **B6** (`:41`): *"PRD §15.2 canonical in `@waggle/shared`; pure harvest + display-category mapping helpers.
Drop FE `event`/`insight` drift."*
- **C28** (`:420`): language selector → *"static disabled `English (US)` chip (no i18n exists…)."*
- **C29** (`:422`): *"drop the auto-advance"* on the first-launch privacy screen.
- **C30** (`:424`): *"keep Work type as a distinct personalization signal; don't re-ask what the template
already implies."*
- **C31** (`:426`): Tool Discovery id-space → *"namespaced scheme (`connector:gmail` / `tool:cursor`)."*
- **C32** (`:428`): *"pre-select from `GET /api/tools/detect` with a visible 'detected' badge."*
- **C34** (`:433`): Hermes/Codex/Cursor tiles → *"render as `upload`/'Other' file pickers or 'coming soon' v1."*
- **C35** (`:435`): Workspace Creation → *"record connector/MCP ids as workspace *intent* on the config; do
NOT run install/OAuth at create time."*
- **C6** (`:373`): `WorkspaceType` = *"`project | client | research | personal` (+`team`/`organization`
reserved); `type` coexists with the free-string `group`."*
---
## 2. B8 — Identity seed ("capture who-you-are + greet by name")
### What already exists
- **Profile store** (`profile.ts`): `UserProfile` (`:41-94`) carries `name/role/company/industry/bio` +
writingStyle/brand/interests/language/timezone. `GET /api/profile` (`:162`) + `PUT /api/profile` (`:167`,
partial-merge allow-list `:172-196`). On save it ALSO mirrors a `User identity: …` P/I frame to personal
memory (`:201-224`). Stored in `profile.json` (file, no SQLite). Adapter: `getProfile`/`updateProfile`
(`adapter.ts:1357-1365`, typed `any`).
- **Identity table** (`identity.ts` route + `hive-mind-core/src/mind/identity.ts` `IdentityLayer`):
single-row per-mind `identity` table (`name/role/department/personality/capabilities/system_prompt`).
`GET /api/identity` (`:62`) + `POST /api/identity` upsert (`:104-156`). `IdentityLayer` exposes
`create/get/exists/update/toContext` (`identity.ts:18-73`). This is what backs the **Home greeting name**
via `adapter.getIdentity()` (`adapter.ts:742`).
- **UserProfileApp** (`apps/web/.../apps/UserProfileApp.tsx`, "My Profile") already renders a "Who Are You?"
Identity tab capturing Name/Role/Company/Industry/Bio with `INDUSTRIES` + chip-toggle patterns —
the **reuse target for the form fields**.
### The GAP to close (B8)
1. **No `setIdentity` adapter method.** `adapter.getIdentity()` exists (`:742`) but there is **no**
`adapter.setIdentity(...)` calling `POST /api/identity`. → ADD it.
2. **Onboarding never writes profile or identity.** The wizard has no profile step; `OnboardingState` has no
profile fields. → NEW `WhoAreYouStep` posts to `PUT /api/profile` AND `POST /api/identity` in one save.
3. **3 new profile fields** (`workType?`, `teamSize?`, `goals?: string[]`) are net-new on `UserProfile`
(S13 §5). `PUT /api/profile` allow-list (`:172-196`) must be EXTENDED to merge them; `DEFAULT_PROFILE`
(`:96-135`) extended; FE `UserProfile`/types updated.
4. **Identity-seed payload:** map profile → identity fields: `name→name`, `role→role`,
`industry→department` (or leave department blank), optionally `bio→personality`. `system_prompt` left
empty (the agent path already injects the profile frame). No schema change — `IdentityLayer.create/update`
already upserts.
Backend substrate: `profile.json` + the existing identity table. **No `.mind` migration.**
---
## 3. C33 — Import → review (the EXACT existing contract to reuse)
### Existing harvest preview/commit contract (Phase 2B.3 — DO NOT rebuild)
**`POST /api/harvest/preview`** (`harvest.ts:227-258`). Request `{ data, source }`. Response:
```ts
{
source: ImportSourceType,
itemCount: number, // true total
types: Record<string, number>, // count by ImportItemType
preview: ClassifiedItem[], // back-compat: first 10
items: ClassifiedItem[], // NEW: full list (capped at PREVIEW_ITEM_CAP=5000)
itemsTruncated: boolean,
}
// ClassifiedItem = { id, title, type, source, kind: MemoryKind, confidence: number } (harvest.ts:239-246)
```
`kind` from `importItemTypeToMemoryKind` (`harvest-classify.ts:32`); `confidence` (0–100) from
`harvestConfidence` (`harvest-classify.ts:66`, B2 heuristic = source-trust × item-type, no LLM).
**`POST /api/harvest/commit`** (`harvest.ts:265-582`). Request:
```ts
{ data?, source?, resumeFromRun?, selectedIds?: Array<string|number> } // harvest.ts:266-275
```
- `selectedIds` present + non-empty → filters items to that subset (`:344-347`); absent → commits ALL
(the C33 onboarding default).
- Each committed frame is stamped (`:449-456`), guarded on empty metadata, with:
```ts
{ kind: importItemTypeToMemoryKind(item.type), confidence: harvestConfidence(item),
status: 'unreviewed', sourceId: item.id }
```
→ exactly the C33 "commit-as-unreviewed" behavior. Response carries `saved`, `cognifySkippedReason`,
`wikiSkippedReason` (`no_real_embedder`), `runId`, etc.
**The review surface already exists.** `MemoryCenterTab.tsx` (Phase 2B-FE.2) has a **"Needs review"
status filter** (`:25-31`, `value:'unreviewed'`) + `MemoryCard` renders an "Needs review" badge
(`MemoryCard.tsx:18`). So S16's review is satisfied by Memory Center — **2D does not build a Review step.**
### The GAP the wizard must close
1. **Adapter `harvestCommit` cannot pass `selectedIds`.** Current signature
`harvestCommit(data, source)` (`adapter.ts:1898-1901`) — the body omits `selectedIds`. → WIDEN to
`harvestCommit(data, source, opts?: { selectedIds?, resumeFromRun? })`. (Backend already accepts it.)
2. **`harvestPreview`/`harvestCommit` typed `any`** (`adapter.ts:1893,1898`) — tighten to the shared
`HarvestPreview`/`HarvestCommitResult` shapes (repo bans `any`; CLAUDE.md §10 — `no-explicit-any` is error).
3. **`ImportStep` reads `result.preview` (first 10), not the classified `items[]`** with kind/confidence
(`OnboardingWizard.tsx:164` sets `importPreview` from `result.preview`). → rework to consume `items[]`
and render kind chips + confidence so the user sees what is being imported (matches S15 §4). Selection is
OPTIONAL per C33 (default = import all as unreviewed); if a "deselect" affordance is added it posts
`selectedIds`. **Minimum viable 2D = keep commit-all; just surface kind/confidence + the
"you can review later in Memory Center" pointer.**
4. **`ImportStepProps.importPreview` is `readonly unknown[]`** (`types.ts:39-40`) — widen to the classified
item type.
No backend change is required for C33 — the contract shipped in 2B.3. 2D is **FE wiring only** here.
---
## 4. S17 — Workspace creation: exists vs 2D adds
### Exists
- **Backend `POST /api/workspaces`** (`workspaces.ts:162-230`): accepts `name/group/icon/model/personaId/
templateId/storageType/storagePath/teamId/...`; enforces tier workspace-limit (403, `:194-203`);
auto-creates storage structure + starter skills + template starter-memory. `WorkspaceManager.create`
writes `workspace.json` (no SQLite).
- **Adapter `createWorkspace`** (`adapter.ts:253-260`): bridges `persona`→`personaId`.
- **Onboarding already creates a workspace** via `handleFinish`/`handleSkipSetup`
(`OnboardingWizard.tsx:278-326`) — bespoke `adapter.createWorkspace` calls, NOT the dialog.
- **`CreateWorkspaceDialog.tsx`** (1129 LOC): the full standalone modal (template/persona/storage/folder
picker). The richer S17 wizard (type picker, suggested capabilities, summary card) is a **separate S17
card** — most of that is the standalone-modal rework, not the onboarding embed.
### What 2D adds (minimal, onboarding-scoped)
2D needs a workspace-create **step in the chain**, not the full S17 modal rework. Minimal:
- Reuse the existing `handleFinish` create path (name + template + persona) OR render a trimmed
type-picker + name. Per **C6** add `type?: WorkspaceType` (`project|client|research|personal`) coexisting
with `group`; per **C35** record any selected connector/MCP ids as **intent** (config fields), not installs.
- Backend: EXTEND `POST /api/workspaces` Body + `WorkspaceManager.create` with the additive optional V2
fields (`description?, type?, status?, agentIds?, connectorIds?, mcpIds?`) — **JSON file, no migration**.
(This field extension is shared with the Phase-0 `WorkspaceConfig` V2 work and the standalone S17 card.)
- Adapter `createWorkspace` body type widened to carry `description/type` (+ capability-id arrays if used).
> The full stepped S17 wizard (Suggested Skills/Agents/Connectors/MCPs panels + summary card) is the
> **standalone S17 card's** scope. 2D's workspace-create is the onboarding-embedded variant; keep it thin
> and route it through the SAME create call so onboarding and the modal converge later (S17 §4 parity note).
---
## 5. WHAT ALREADY EXISTS (do-not-rebuild) vs NET-NEW
### Do-not-rebuild (verified present)
| Capability | Where | Status |
|---|---|---|
| Harvest preview w/ per-item `kind`+`confidence` | `harvest.ts:227-258` + `harvest-classify.ts` | DONE (2B.3) |
| Harvest commit w/ `selectedIds` + `status:'unreviewed'` stamp | `harvest.ts:265-456` | DONE (2B.3) |
| B2 heuristic confidence | `harvest-classify.ts:66` | DONE |
| B6 `ImportItemType→MemoryKind` (server) | `harvest-classify.ts:32` | DONE |
| B6 FE display-category map | `apps/web/src/lib/harvest-kind-map.ts` | DONE (2B.3) |
| Memory Center "Needs review" filter (the S16 review surface) | `MemoryCenterTab.tsx:25-31`, `MemoryCard.tsx:18` | DONE (2B-FE.2) |
| Profile store + `GET/PUT /api/profile` + identity-frame mirror | `profile.ts` | EXISTS |
| Identity table + `GET/POST /api/identity` + `IdentityLayer` | `identity.ts`, `mind/identity.ts` | EXISTS |
| `adapter.getProfile/updateProfile/getIdentity` | `adapter.ts:1357,1362,742` | EXISTS |
| Profile form fields/INDUSTRIES/chip-toggle to copy | `UserProfileApp.tsx` | EXISTS |
| Claude-Code auto-detect + harvest | `harvest.ts:831`, wizard `:182-202` | EXISTS |
| Connector catalog `GET /api/connectors`; tool-detect `GET /api/tools/detect` (S14) | `connectors.ts`, `tools.ts` | EXISTS |
| `POST /api/workspaces` + tier-limit + starter skills | `workspaces.ts:162` | EXISTS |
| Wizard shell (progress/dots/Back/Skip/AnimatePresence) | `OnboardingWizard.tsx:399-575` | EXISTS — keep |
| Resume backbone (`state.step` persist) | `useOnboarding.ts` | EXISTS |
### Net-new in 2D
- FE: `WhoAreYouStep.tsx` (S13); `ToolDiscoveryStep.tsx` + `lib/tool-recommendations.ts` (S14, deferrable);
reworked `WelcomeStep`/`FirstLaunchStep` (S12); reworked `ImportStep` (S15 surface kind/confidence);
workspace-create step (S17 thin); `lib/onboarding-profile.ts` (option constants + `buildProfilePreview`).
- Adapter: **`setIdentity(...)`** (new); `harvestCommit` 3rd `opts` arg; tighten `harvestPreview/harvestCommit`
types; widen `createWorkspace` body type.
- Backend: EXTEND `PUT /api/profile` allow-list (+`workType/teamSize/goals`) + `DEFAULT_PROFILE` + `UserProfile`;
EXTEND `POST /api/workspaces` + `WorkspaceManager.create` V2 fields. **No new route, no `.mind` migration.**
- Types: `OnboardingState` += `profileSeeded?`, `toolsUsed?: string[]` (localStorage, additive); shared
`WorkspaceType` (C6) + `HarvestPreview`/`HarvestCommitResult`; FE `UserProfile` (+3 fields).
- Wizard: re-key `STEP_NAMES`, the step switch (`:498-572`), progress math (`progressPct :396`, dots `:472`,
`aria-valuemax :426`), Back-range (`:444`), and the `goToStep(N)` auto-advances.
---
## 6. Minimal sub-phase build plan (each independently tsc + test verifiable)
> Verify gate per sub-phase (CLAUDE.md §2): `tsc` on touched packages
> (`shared → hive-mind-core → server`, then `npm run build` for apps/web), `npm run test -- --run`, `npm run lint`.
> Build order: shared → hive-mind-core → core → agent → server.
### 2D.1 — Backend + shared + adapter (no UI)
Ordered, each file with the exact change + contract:
1. `packages/shared/src/types.ts` — add `WorkspaceType = 'project'|'client'|'research'|'personal'` (C6;
`team`/`organization` reserved). (`MemoryKind` already canonical here from B6/2B.3 — do NOT redefine.)
2. `packages/server/src/local/routes/profile.ts` —
- `UserProfile` (`:41-94`): add `workType?: string; teamSize?: string; goals?: string[]`.
- `DEFAULT_PROFILE` (`:96-135`): add the three defaults (`''`, `''`, `[]`).
- `PUT` allow-list (`:172-196`): merge the three (`if (updates.workType != null) …`).
- Identity-frame mirror string (`:205-210`): optionally append role/industry (pure edit).
3. `packages/server/src/local/routes/workspaces.ts` — extend the `POST` Body (`:163-181`) + the
`WorkspaceManager.create(...)` call (`:223-230`) with additive optional `description?, type?, status?,
agentIds?, connectorIds?, mcpIds?` (JSON, no migration). (Coordinate with Phase-0 V2 field work.)
4. `packages/hive-mind-core/src/workspace-manager.ts` — add the same optional fields to `WorkspaceConfig` +
`CreateWorkspaceOptions`; persist in `create()`/`update()` (stamp `updatedAt`). **No DB migration.**
5. `apps/web/src/lib/adapter.ts` —
- NEW `async setIdentity(body): Promise<IdentityResponse>` → `POST /api/identity` (mirror `getIdentity`
`:742`).
- `harvestCommit` (`:1898`): add `opts?: { selectedIds?: Array<string|number>; resumeFromRun?: number }`
and include in the POST body.
- Tighten `harvestPreview`/`harvestCommit` return types to shared `HarvestPreview`/`HarvestCommitResult`
(drop `any`); `getProfile`/`updateProfile` to `UserProfile` (drop `any`).
- `createWorkspace` body type (`:253`): add `description?, type?: WorkspaceType, connectorIds?, mcpIds?`.
**Verify 2D.1:** tsc shared + hive-mind-core + server (+ apps/web build for adapter); add/extend route tests
(profile merge of 3 fields; identity upsert; commit `selectedIds` filter — the last already covered by 2B.3
tests, just confirm green).
### 2D.2 — Frontend (the chain)
1. `apps/web/src/lib/onboarding-profile.ts` (NEW, pure + `.test.ts`) — `WORK_TYPES`, `TEAM_SIZES`, `GOALS`
option constants + `buildProfilePreview(partial)` (keeps the step thin).
2. `apps/web/src/lib/types.ts` — promote shared `UserProfile` (+ `workType/teamSize/goals`); import
`WorkspaceType`, `HarvestPreview`/`HarvestCommitResult` from `@waggle/shared`.
3. `apps/web/src/hooks/useOnboarding.ts` — `OnboardingState` (`:10-19`): add additive optional
`profileSeeded?: boolean`, `toolsUsed?: string[]` (localStorage only).
4. `apps/web/.../onboarding/WelcomeStep.tsx` (rework → S12): align copy; add static `English (US)` chip
(C28) + privacy note; consume `useOfflineStatus`. `OnboardingWizard.tsx:136-141`: **drop the 3s
auto-advance** (C29).
5. `apps/web/.../onboarding/WhoAreYouStep.tsx` (NEW → S13/B8): Name/Role/Industry (reuse `UserProfileApp`
`INDUSTRIES`/chips) + WorkType/TeamSize/Goals + live preview. On Continue: `adapter.updateProfile(...)`
**AND** `adapter.setIdentity({name, role, department: industry})`. Props `{ profile, onChange,
onContinue, onBack, saving }`. Add `WhoAreYouStepProps` to `onboarding/types.ts`.
6. `apps/web/.../onboarding/ToolDiscoveryStep.tsx` (NEW → S14): grouped grid from `getConnectors` +
`detectTools` (pre-check detected, C32); namespaced ids `connector:*`/`tool:*` (C31); writes
`toolsUsed[]`. **DEFERRABLE** — if descoping 2D, omit this step and renumber; S14 has zero backend and
can land in a 2D follow-up. (Flag in the chain as optional.)
7. `apps/web/.../onboarding/ImportStep.tsx` (rework → S15): consume `result.items[]` (kind+confidence) not
`preview[]`; render kind chips + `ConfidenceBadge` (reuse `components/ui/confidence-badge`); add the
"review anytime in Memory → Needs review" pointer (C33). Hermes/Codex/Cursor = upload/"Other"/coming-soon
(C34). Keep commit-all default; commit still lands `unreviewed` server-side. Widen `ImportStepProps`.
8. `apps/web/.../onboarding/` workspace-create step (S17 thin): trimmed type-picker (C6) + name → existing
`handleFinish` create path; record connector/MCP intent ids (C35). (Full stepped S17 = separate card.)
9. `apps/web/.../overlays/OnboardingWizard.tsx` — re-key `STEP_NAMES` (`:35`) to
`first-launch/who-are-you/tool-discovery/memory-import/workspace-create/ready`; rewrite the step switch
(`:498-572`); fix progress math (`:396`, dots `:472`, `aria-valuemax :426`, Back-range `:444`); add
`handleProfileSave`; point import commit at the new step order; **remove the dead tier/api-key/model
steps from the chain** (or keep behind a flag — surgical, prefer removal of the now-orphaned wiring).
**Verify 2D.2:** `npm run build` (apps/web tsc), `npm run test -- --run` (new `onboarding-profile.test.ts`
+ any wizard tests), `npm run lint`. Manual: `?forceWizard=true` walks First Launch → Who Are You (writes
profile+identity → Home greets by name) → [Tool Discovery] → Import (commits unreviewed; appears in Memory
"Needs review") → Workspace Create → Home.
### Largest single risk
**The `OnboardingWizard.tsx` step-index rewire.** It re-keys `STEP_NAMES`, the AnimatePresence step switch,
progress %, the dot array, `aria-valuemax`, the Back-button range, AND every `goToStep(N)` literal
(`:174, :199, :300, :350` etc.) — plus removal of the orphaned tier/api-key/model handlers and their
step-local state (`selectedTier/apiKey/keyValid/...`, `:47-60`). An off-by-one or a stale `goToStep(4)`
strands the user mid-flow or skips identity-seed/commit. Mitigation: change the step set in ONE pass, drive
all navigation off `STEP_NAMES.indexOf(name)` (not magic numbers), keep an E2E that asserts the full chain
reaches Home, and verify resume (`state.step`) lands on the correct re-keyed step. This is exactly the churn
S13/S14/S15/S16 §7 all warn must be "rewired once, not per-card."

538
docs/ux-refactor/IMPLEMENTATION-PLAN.md Normal file
View File

@@ -0,0 +1,538 @@
# 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/`.*

121
docs/ux-refactor/README.md Normal file
View File

@@ -0,0 +1,121 @@
# 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`](./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`](./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`](./_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`](./_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`](./_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`](./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`](./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`](./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`](./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`](./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`](./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](./gap-cards/S00-appshell-ia.md) | AppShell + IA + Navigation | §1, §19.1, §20.3 | **0** |
| [S01](./gap-cards/S01-home-cockpit.md) | Home Cockpit | §12.1 | **1** |
| [S02](./gap-cards/S02-workspace-desktop.md) | Workspace Desktop | §12.2 | **1** |
| [S03](./gap-cards/S03-command-center.md) | Command Center (Ctrl+K) | §12.3 | **1** |
| [S04](./gap-cards/S04-memory-center.md) | Memory Center | §12.4 | **2** |
| [S05](./gap-cards/S05-artifact-center.md) | Artifact Center | §12.5 | **2** |
| [S06](./gap-cards/S06-skills-hub.md) | Skills Hub | §12.6 | **3** |
| [S07](./gap-cards/S07-connector-hub.md) | Connector Hub | §12.7 | **4** |
| [S08](./gap-cards/S08-mcp-hub.md) | MCP Hub | §12.8 | **4** |
| [S09](./gap-cards/S09-agent-center.md) | Agent Center | §12.9 | **3** |
| [S10](./gap-cards/S10-team-workspace.md) | Team Workspace | §12.11 | **5** |
| [S11](./gap-cards/S11-automation-center.md) | Automation Center | §12.10 | **3** |
| [S12](./gap-cards/S12-first-launch.md) | Onboarding · First Launch | §12.12 | **2** |
| [S13](./gap-cards/S13-who-are-you.md) | Onboarding · Who Are You | §12.12 | **2** |
| [S14](./gap-cards/S14-tool-discovery.md) | Onboarding · Tool Discovery | §12.12 | **2** |
| [S15](./gap-cards/S15-memory-import.md) | Onboarding · Memory Import | §12.12 | **2** |
| [S16](./gap-cards/S16-memory-review.md) | Onboarding · Memory Review | §12.12 | **2** |
| [S17](./gap-cards/S17-workspace-creation.md) | Workspace Creation | §12.12 | **2** |
| [S18](./gap-cards/S18-agent-builder.md) | Agent Builder | §12.9 | **3** |
| [S19](./gap-cards/S19-skill-builder.md) | Skill Builder | §12.6 | **3** |
| [S20](./gap-cards/S20-automation-builder.md) | Automation Builder | §12.10 | **3** |
| [S21](./gap-cards/S21-marketplace-extend.md) | 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).

608
docs/ux-refactor/_inventory/backend-routes.md Normal file
View File

@@ -0,0 +1,608 @@
# Backend Route Inventory — Waggle OS UX Refactor
> **Purpose.** Source-grounded inventory of every existing **local Fastify sidecar** endpoint, plus a
> cross-reference of every **PRD §16 target endpoint** against the current backend. This is the contract
> reference for the in-place incremental refactor (LOCKED execution model): we reuse the existing sidecar
> surface and add/extend only the net-new endpoints the PRD names.
>
> **Method.** Primary source = the audited backend-map (`docs/backend-map/sections/03a–03g`, 65/65 local
> routes documented, ~96% overall coverage per `docs/backend-map/AUDIT.md`). Spot-verified against
> `packages/server/src/local/routes/*.ts` for every PRD-critical path (grep/read).
>
> **Scope note.** Everything below is the **Local Sidecar** (`packages/server/src/local/index.ts` →
> `buildLocalServer()`, default loopback `:3333`, flat `/api/*`, Bearer session-token + same-origin
> guards). The desktop frontend talks ONLY to this server. A separate **Cloud server**
> (`packages/server/src/routes/*.ts`, Clerk-JWT, `:3100`) exists for SaaS/team deployments — its
> `/api/agents`, `/api/jobs`, `/api/scout`, `/api/suggestions` routes are **NOT** in the sidecar and are
> flagged explicitly where they collide with PRD paths. **KVARK** has no Fastify routes (in-process
> `KvarkClient` only).
---
## Part 1 — Existing Local Sidecar Endpoints (by domain)
All paths are relative to the sidecar base (`http://127.0.0.1:3333`). Source files are under
`packages/server/src/local/routes/`. SSE/streaming and non-JSON responses are noted.
### 1.1 Chat / Agent execution / Sessions (`03a`)
| Method | Path | Route file | Purpose |
|---|---|---|---|
| POST | `/api/chat` | `chat.ts` | The chat turn — **SSE** stream (token/step/tool/approval_required/done/error). Largest route (~1.7k LOC). |
| DELETE | `/api/chat/history` | `chat.ts` | Clear a session's in-RAM state (`?session=`). Does NOT delete on-disk `.jsonl`. |
| GET | `/api/history` | `agent.ts` | Load a session's messages (RAM-first then disk). |
| GET | `/api/agent/status` | `agent.ts` | Agent + cost snapshot. |
| GET | `/api/agent/cost` | `agent.ts` | Detailed cost breakdown (string summary). |
| POST | `/api/agent/cost/reset` | `agent.ts` | No-op cost reset stub. |
| GET | `/api/agent/model` | `agent.ts` | Current model. |
| PUT | `/api/agent/model` | `agent.ts` | Switch model (`{ model }`). |
| GET | `/api/agents/active` | `agent.ts` | Sub-agent orchestrator state (`{ workers, active }`). |
| POST | `/api/commands/execute` | `commands.ts` | Run a slash command out-of-band (subset of CommandContext). |
| POST | `/api/agent/run` | `agent-run.ts` | One-shot structured retrieval — **SSE** (distinct events from `/api/chat`). |
| GET | `/api/workspaces/:workspaceId/sessions` | `sessions.ts` | List sessions (`?hideEmpty=`). |
| GET | `/api/workspaces/:workspaceId/sessions/search` | `sessions.ts` | Full-text session search (`?q=&limit=`). |
| GET | `/api/workspaces/:workspaceId/sessions/:sessionId/export` | `sessions.ts` | Export one session as Markdown. |
| GET | `/api/workspaces/:workspaceId/sessions/:sessionId/timeline` | `sessions.ts` | Tool-event timeline. |
| POST | `/api/workspaces/:workspaceId/sessions` | `sessions.ts` | Create a session. |
| PATCH | `/api/sessions/:sessionId` | `sessions.ts` | Rename a session. |
| DELETE | `/api/sessions/:sessionId` | `sessions.ts` | Delete a session's `.jsonl`. |
| GET | `/api/sessions/:sessionId/summary` | `sessions.ts` | Structured post-session summary. |
| GET | `/api/agent-groups` | `agent-groups.ts` | List multi-agent group configs. |
| POST | `/api/agent-groups` | `agent-groups.ts` | Create a group. |
| PATCH | `/api/agent-groups/:id` | `agent-groups.ts` | Update a group. |
| DELETE | `/api/agent-groups/:id` | `agent-groups.ts` | Delete a group. |
| POST | `/api/agent-groups/:id/run` | `agent-groups.ts` | **Placeholder** — returns a queued stub, does NOT execute. |
### 1.2 Approvals (`03a` / `03e`)
| Method | Path | Route file | Purpose |
|---|---|---|---|
| POST | `/api/approval/:requestId` | `approval.ts` | Approve/deny a paused tool (`{ approved, always? }`). |
| GET | `/api/approval/pending` | `approval.ts` | List paused approvals (reconnect/recovery). |
| GET | `/api/approval/grants` | `approval.ts` | List persistent "always allow" grants. |
| DELETE | `/api/approval/grants/:id` | `approval.ts` | Revoke one grant. |
| POST | `/api/approval/grants/clear` | `approval.ts` | Wipe all grants. |
### 1.3 Memory / Knowledge graph (`03b`)
| Method | Path | Route file | Purpose |
|---|---|---|---|
| GET | `/api/memory/search` | `memory.ts` | Full-text frame search across personal + workspace minds. |
| GET | `/api/memory/frames` | `memory.ts` | List recent frames (Memory tab initial load). |
| POST | `/api/memory/frames` | `memory.ts` | Save a frame (optional entity extraction). |
| PUT | `/api/memory/frames/:id` | `memory.ts` | Edit a frame's content/importance. |
| PATCH | `/api/memory/frames/:id/access` | `memory.ts` | Increment `access_count`. |
| DELETE | `/api/memory/frames/:id` | `memory.ts` | Delete a frame. |
| GET | `/api/memory/stats` | `memory.ts` | Frame/entity/relation counts. |
| GET | `/api/memory/graph` | `knowledge.ts` | Read entities + relations (`?scope=all\|personal\|current`). No write/CRUD route. |
### 1.4 Wiki compiler (`03b`)
| Method | Path | Route file | Purpose |
|---|---|---|---|
| GET | `/api/wiki/pages` | `wiki.ts` | List compiled page metadata. |
| GET | `/api/wiki/pages/:slug` | `wiki.ts` | One page's metadata. |
| GET | `/api/wiki/pages/:slug/content` | `wiki.ts` | Full markdown content of a page. |
| POST | `/api/wiki/compile` | `wiki.ts` | Trigger compilation (503 if no real embedder). |
| GET | `/api/wiki/health` | `wiki.ts` | Compilation health report (503 if no real embedder). |
| GET | `/api/wiki/watermark` | `wiki.ts` | Current compilation watermark/state. |
| POST | `/api/wiki/export/obsidian` | `wiki.ts` | Write all pages to an Obsidian-vault dir. |
| POST | `/api/wiki/export/notion` | `wiki.ts` | Push pages to Notion (needs `notion-wiki-token` vault secret). |
### 1.5 Harvest (external AI export ingestion) (`03b`)
| Method | Path | Route file | Purpose |
|---|---|---|---|
| POST | `/api/harvest/preview` | `harvest.ts` | Parse an export, show what would import (no save). |
| POST | `/api/harvest/commit` | `harvest.ts` | Full pipeline: save → cognify → wiki recompile. |
| GET | `/api/harvest/sources` | `harvest.ts` | List registered harvest sources. |
| POST | `/api/harvest/sources` | `harvest.ts` | Register/update a source. |
| DELETE | `/api/harvest/sources/:source` | `harvest.ts` | Remove a source. |
| PATCH | `/api/harvest/sources/:source` | `harvest.ts` | Toggle auto-sync/interval. |
| GET | `/api/harvest/progress` | `harvest.ts` | **SSE** import progress stream. |
| GET | `/api/harvest/runs` | `harvest.ts` | List recent harvest runs. |
| GET | `/api/harvest/runs/latest-interrupted` | `harvest.ts` | Latest resumable run. |
| POST | `/api/harvest/runs/:id/abandon` | `harvest.ts` | Discard an interrupted run. |
| POST | `/api/harvest/extract-identity` | `harvest.ts` | LLM-extract identity facts from recent frames. |
| POST | `/api/harvest/scan-claude-code` | `harvest.ts` | Scan local `~/.claude` for Claude Code history. |
### 1.6 Legacy import / File ingestion / Identity / Documents / Erasure (`03b`)
| Method | Path | Route file | Purpose |
|---|---|---|---|
| POST | `/api/import/preview` | `import.ts` | Legacy ChatGPT/Claude export preview. |
| POST | `/api/import/commit` | `import.ts` | Legacy import + save to personal memory. |
| POST | `/api/ingest` | `ingest.ts` | Base64 file ingestion (images/pdf/docx/pptx/xlsx/csv/code/zip) → LLM text + frames. |
| GET | `/api/identity` | `identity.ts` | Read the structured identity record (upsert table). |
| POST | `/api/identity` | `identity.ts` | Create/update identity record. |
| GET | `/api/mind/identity` | `mind.ts` | Rendered identity **context string**. |
| GET | `/api/mind/awareness` | `mind.ts` | Awareness state context. |
| GET | `/api/mind/skills` | `mind.ts` | Loaded skills list. |
| GET | `/api/workspaces/:id/documents` | `documents.ts` | List tracked document versions. |
| POST | `/api/workspaces/:id/documents` | `documents.ts` | Register a new document version. |
| GET | `/api/workspaces/:id/documents/:name/versions` | `documents.ts` | List versions of one document. |
| POST | `/api/data/erase` | `data-erase.ts` | GDPR erasure (double-confirm; wipes at next startup). |
| POST | `/api/export` | `export.ts` | Generate + download a ZIP of all user data. |
### 1.7 Workspaces / Templates / Storage / Files / Tasks / Pins (`03c` + `04`)
| Method | Path | Route file | Purpose |
|---|---|---|---|
| GET | `/api/workspaces` | `workspaces.ts` | List workspaces (`?group=&teamId=`). |
| POST | `/api/workspaces` | `workspaces.ts` | Create a workspace (tier `workspaceLimit`). |
| GET | `/api/workspaces/:id` | `workspaces.ts` | Get one workspace. |
| GET | `/api/workspaces/:id/context` | `workspaces.ts` | "Workspace Now" catch-up block (summary/threads/prompts/state). |
| GET | `/api/workspaces/:id/files` | `workspaces.ts` | List ingested/registered files (file registry, newest first). |
| PUT | `/api/workspaces/:id` | `workspaces.ts` | Update workspace (full). |
| PATCH | `/api/workspaces/:id` | `workspaces.ts` | Partial update (`personaId:null` clears). |
| DELETE | `/api/workspaces/:id` | `workspaces.ts` | Delete workspace + mind DB. |
| GET | `/api/workspaces/:id/export` | `workspaces.ts` | Export workspace (`?format=briefing`→md, else JSON). |
| GET | `/api/workspaces/:id/cost` | `workspaces.ts` | Per-workspace spend vs budget + 7-day history. |
| GET | `/api/workspaces/:id/storage` | `workspaces.ts` | Virtual/linked storage stats. |
| GET | `/api/workspaces/:id/storage/files` | `workspaces.ts` | List files in workspace storage. |
| GET | `/api/workspaces/:id/storage/read` | `workspaces.ts` | Read a file (`?path=`, `?raw=`). |
| POST | `/api/workspaces/:id/storage/write` | `workspaces.ts` | Write a file. |
| DELETE | `/api/workspaces/:id/storage/delete` | `workspaces.ts` | Delete a file. |
| GET | `/api/workspace-templates` | `workspace-templates.ts` | List 15 built-in + user templates. |
| POST | `/api/workspace-templates` | `workspace-templates.ts` | Create a custom template. |
| PUT | `/api/workspace-templates/:id` | `workspace-templates.ts` | Update a custom template (403 if built-in). |
| DELETE | `/api/workspace-templates/:id` | `workspace-templates.ts` | Delete a custom template (403 if built-in). |
| POST | `/api/workspace-templates/generate` | `workspace-templates.ts` | AI-generate a template config. |
| GET | `/api/workspaces/:workspaceId/files/list` | `files.ts` | List managed files in a workspace storage dir (`?path=`). |
| POST | `/api/workspaces/:workspaceId/files/upload` | `files.ts` | Upload a file into workspace storage. |
| GET | `/api/workspaces/:workspaceId/files/download` | `files.ts` | Download a file (`?path=`). |
| POST | `/api/workspaces/:workspaceId/files/mkdir` | `files.ts` | Create a directory. |
| POST | `/api/workspaces/:workspaceId/files/delete` | `files.ts` | Delete a file/dir. |
| POST | `/api/workspaces/:workspaceId/files/move` | `files.ts` | Move a file. |
| POST | `/api/workspaces/:workspaceId/files/copy` | `files.ts` | Copy a file. |
| GET | `/api/tasks` | `tasks.ts` | List tasks across workspaces. |
| GET | `/api/workspaces/:id/tasks` | `tasks.ts` | List tasks for a workspace. |
| POST | `/api/workspaces/:id/tasks` | `tasks.ts` | Create a task. |
| PATCH | `/api/workspaces/:id/tasks/:taskId` | `tasks.ts` | Update a task. |
| DELETE | `/api/workspaces/:id/tasks/:taskId` | `tasks.ts` | Delete a task. |
| GET | `/api/workspaces/:id/pins` | `pins.ts` | List pinned messages. |
| POST | `/api/workspaces/:id/pins` | `pins.ts` | Add a pin. |
| PATCH | `/api/workspaces/:id/pins/:pinId` | `pins.ts` | Update pin status/label. |
| DELETE | `/api/workspaces/:id/pins/:pinId` | `pins.ts` | Remove a pin. |
### 1.8 Team / RBAC (`03c`)
> Two prefixes: `/api/team/*` = remote-server proxy (local fallbacks when disconnected); `/api/teams/*` = local CRUD (always works, `teams.db`).
| Method | Path | Route file | Purpose |
|---|---|---|---|
| POST | `/api/team/connect` | `team.ts` | Connect to remote team server. **Tier: TEAMS.** |
| POST | `/api/team/disconnect` | `team.ts` | Clear team-server config. |
| GET | `/api/team/status` | `team.ts` | Connection status. |
| GET | `/api/team/teams` | `team.ts` | List teams from remote server. |
| GET | `/api/team/members` | `team.ts` | List members (remote or local fallback). |
| GET | `/api/team/presence` | `team.ts` | Presence (`?workspaceId=`). |
| GET | `/api/team/activity` | `team.ts` | Recent activity from remote. |
| GET | `/api/team/messages` | `team.ts` | Recent WaggleDance messages. |
| GET | `/api/team/governance/permissions` | `team.ts` | Effective capability permissions. **Tier: ENTERPRISE.** |
| GET | `/api/team/memory/search` | `team.ts` | Search team memory frames. |
| POST | `/api/teams` | `team.ts` | Create a local team. |
| GET | `/api/teams` | `team.ts` | List teams the local user belongs to. |
| GET | `/api/teams/:id` | `team.ts` | Team detail + members + workspaces. |
| PUT | `/api/teams/:id` | `team.ts` | Update team (owner/admin). |
| DELETE | `/api/teams/:id` | `team.ts` | Delete team (owner only). |
| POST | `/api/teams/:id/members` | `team.ts` | Add/invite member (owner/admin). |
| PUT | `/api/teams/:id/members/:userId` | `team.ts` | Change member role (owner only). |
| PATCH | `/api/teams/:id/members/:userId` | `team.ts` | Change member role (owner/admin). |
| DELETE | `/api/teams/:id/members/:userId` | `team.ts` | Remove member. |
| GET | `/api/teams/:id/activity` | `team.ts` | Aggregated audit events across team workspaces. |
### 1.9 Personas / Settings / Tier / Profile (`03c`)
| Method | Path | Route file | Purpose |
|---|---|---|---|
| GET | `/api/personas` | `personas.ts` | List persona catalog. |
| POST | `/api/personas` | `personas.ts` | Create custom persona. **Tier: PRO.** |
| PATCH | `/api/personas/:id` | `personas.ts` | Update custom persona. |
| POST | `/api/personas/generate` | `personas.ts` | AI-generate a persona. **Tier: PRO.** |
| DELETE | `/api/personas/:id` | `personas.ts` | Delete custom persona. |
| GET | `/api/settings` | `settings.ts` | Read config (keys masked). |
| PUT | `/api/settings` | `settings.ts` | Update models/budgets/providers. |
| PATCH | `/api/settings` | `settings.ts` | Partial merge (non-provider). |
| POST | `/api/settings/test-key` | `settings.ts` | Validate API-key format (no network). |
| POST | `/api/settings/probe-provider` | `settings.ts` | Live-probe a STORED provider key by id (F3). |
| GET | `/api/settings/permissions` | `settings.ts` | Read autonomy/gates/overrides. |
| PUT | `/api/settings/permissions` | `settings.ts` | Save permission settings. |
| GET | `/api/tier` | `settings.ts` | **Authoritative tier source** (effective tier, trial, capabilities). |
| PATCH | `/api/tier` | `settings.ts` | Dev tier override (fail-closed). |
| POST | `/api/tier/start-trial` | `settings.ts` | Start the 15-day TRIAL. |
| GET | `/api/cloud-sync` | `settings.ts` | Cloud-sync status. |
| POST | `/api/cloud-sync/toggle` | `settings.ts` | Toggle cloud sync. **Tier: TEAMS.** |
| GET | `/api/admin/overview` | `settings.ts` | Admin dashboard data. **Tier: TEAMS.** |
| GET | `/api/admin/audit-export` | `settings.ts` | Export audit log. **Tier: TEAMS.** |
| GET | `/api/profile` | `profile.ts` | Full user profile. |
| PUT | `/api/profile` | `profile.ts` | Partial-merge profile update. |
| POST | `/api/profile/analyze-style` | `profile.ts` | LLM-analyze writing sample. |
| POST | `/api/profile/analyze-brand` | `profile.ts` | LLM-extract brand colors/fonts. |
| GET | `/api/profile/style` | `profile.ts` | Writing-style summary. |
| GET | `/api/profile/brand` | `profile.ts` | Brand profile. |
| POST | `/api/profile/research` | `profile.ts` | LLM-research user/company → bio. |
### 1.10 Marketplace / Skills / Plugins / Connectors / Tools (`03d`)
| Method | Path | Route file | Purpose |
|---|---|---|---|
| GET | `/api/marketplace/search` | `marketplace.ts` | FTS5 + faceted catalog search. |
| GET | `/api/marketplace/packs` | `marketplace.ts` | List capability packs. |
| GET | `/api/marketplace/packs/:slug` | `marketplace.ts` | Pack detail + packages. |
| GET | `/api/marketplace/enterprise-packs` | `marketplace.ts` | KVARK-gated packs. **Tier: ENTERPRISE.** |
| POST | `/api/marketplace/install` | `marketplace.ts` | Install a package (SecurityGate). **Tier: PRO.** |
| POST | `/api/marketplace/uninstall` | `marketplace.ts` | Uninstall a package. |
| GET | `/api/marketplace/installed` | `marketplace.ts` | List installed packages. |
| POST | `/api/marketplace/security-check` | `marketplace.ts` | Scan a package without installing. |
| GET | `/api/marketplace/sources` | `marketplace.ts` | List marketplace sources. |
| POST | `/api/marketplace/sources` | `marketplace.ts` | Add a user source + sync. |
| DELETE | `/api/marketplace/sources/:id` | `marketplace.ts` | Remove a user source. |
| GET | `/api/marketplace/categories` | `marketplace.ts` | Category taxonomy. |
| POST | `/api/marketplace/sync` | `marketplace.ts` | Manual catalog sync. |
| GET | `/api/marketplace/security-status` | `marketplace.ts` | Scanner availability + scan counts. |
| POST | `/api/marketplace/publish` | `marketplace.ts` | Publish a local skill to the catalog. **Tier: PRO.** |
| GET | `/api/skills/starter-pack/catalog` | `skills.ts` | Browse starter skills with state. |
| POST | `/api/skills/starter-pack` | `skills.ts` | Install all starter skills. |
| POST | `/api/skills/starter-pack/:id` | `skills.ts` | Install ONE starter skill. |
| GET | `/api/skills/capability-packs/catalog` | `skills.ts` | List capability packs with states. |
| POST | `/api/skills/capability-packs/:id` | `skills.ts` | Install all skills in a pack. |
| GET | `/api/skills` | `skills.ts` | List installed skills. |
| GET | `/api/skills/suggestions` | `skills.ts` | Contextual skill recommendations. |
| GET | `/api/skills/:name` | `skills.ts` | Full skill content. |
| POST | `/api/skills` | `skills.ts` | Create skill from raw `{ name, content }`. |
| POST | `/api/skills/create` | `skills.ts` | Create skill from structured template. |
| PUT | `/api/skills/:name` | `skills.ts` | Update skill content. |
| DELETE | `/api/skills/:name` | `skills.ts` | Delete skill. |
| GET | `/api/skills/hash-status` | `skills.ts` | Which skills changed on disk. |
| POST | `/api/skills/test` | `skills.ts` | Sandbox/dry-run a skill (prompt injection preview). |
| GET | `/api/audit/installs` | `skills.ts` | Recent install audit trail. |
| GET | `/api/plugins` | `skills.ts` | List installed plugins. |
| POST | `/api/plugins/install` | `skills.ts` | Install a plugin from a local dir. |
| DELETE | `/api/plugins/:name` | `skills.ts` | Uninstall a plugin. |
| GET | `/api/plugins/:name/tools` | `skills.ts` | List a plugin's tools + impl status. |
| GET | `/api/plugins/:name/tools/:toolName` | `skills.ts` | Get one tool's impl file. |
| PUT | `/api/plugins/:name/tools/:toolName` | `skills.ts` | Write a tool impl file. |
| DELETE | `/api/plugins/:name/tools/:toolName` | `skills.ts` | Delete a tool impl file. |
| POST | `/api/plugins/:name/tools` | `skills.ts` | Declare a new tool in the manifest. |
| GET | `/api/hooks` | `skills.ts` | List `pre:tool` deny rules. |
| POST | `/api/hooks` | `skills.ts` | Add a deny rule. |
| DELETE | `/api/hooks/:index` | `skills.ts` | Remove a rule by index. |
| GET | `/api/connectors` | `connectors.ts` | List all connector definitions. |
| GET | `/api/connectors/:id/health` | `connectors.ts` | Live health probe. |
| POST | `/api/connectors/:id/connect` | `connectors.ts` | Store credentials + re-init connector. |
| POST | `/api/connectors/:id/disconnect` | `connectors.ts` | Remove credential + sub-keys. |
| GET | `/api/tools/detect` | `tools.ts` | Scan machine for supported AI tools (AI-OS). |
| POST | `/api/tools/launch` | `tools.ts` | Spawn a tool with workspace env. |
| GET | `/api/tools/processes` | `tools.ts` | List tracked running processes. |
| POST | `/api/tools/kill` | `tools.ts` | Kill a tracked PID. |
| POST | `/api/tools/hooks` | `tools.ts` | Run hive-mind hook install/verify/uninstall. |
| GET | `/api/oauth/providers` | `oauth.ts` | List OAuth providers + token status. |
| GET | `/api/oauth/:provider/authorize` | `oauth.ts` | Build + redirect to provider OAuth URL. |
| GET | `/api/oauth/:provider/callback` | `oauth.ts` | Exchange code → token (HTML response). |
| GET | `/api/vault` | `vault.ts` | List secrets (no values) + suggestions. |
| POST | `/api/vault` | `vault.ts` | Add/update a secret. |
| DELETE | `/api/vault/:name` | `vault.ts` | Delete a secret. |
| POST | `/api/vault/:name/reveal` | `vault.ts` | Decrypt + return value (local-origin only). |
| GET | `/api/providers` | `providers.ts` | LLM + search providers, models, key status. |
> **Dev-only (not a production contract):** `marketplace-dev.ts` registers `/_dev/marketplace/{search,security-check,packs,health}` behind env `WAGGLE_DEV_MARKETPLACE=1`. Excluded from PRD cross-reference.
### 1.11 Evolution / Feedback / Telemetry / Compliance / Cost / Capabilities (`03e`)
| Method | Path | Route file | Purpose |
|---|---|---|---|
| GET | `/api/evolution/runs` | `evolution.ts` | List evolution runs. |
| GET | `/api/evolution/runs/:uuid` | `evolution.ts` | Single run detail. |
| POST | `/api/evolution/runs/:uuid/accept` | `evolution.ts` | Accept + deploy a run. |
| POST | `/api/evolution/runs/:uuid/reject` | `evolution.ts` | Reject a run. |
| GET | `/api/evolution/targets` | `evolution.ts` | Enumerate evolvable targets. |
| GET | `/api/evolution/baseline` | `evolution.ts` | Current baseline text for a target. |
| POST | `/api/evolution/run` | `evolution.ts` | Trigger a real run (JSON or **SSE**). |
| GET | `/api/evolution/status` | `evolution.ts` | Aggregate status counts. |
| POST | `/api/feedback` | `feedback.ts` | Record thumbs up/down on a message. |
| GET | `/api/feedback/stats` | `feedback.ts` | Improvement stats + trend. |
| GET | `/api/telemetry/summary` | `telemetry.ts` | Local telemetry summary. |
| GET | `/api/telemetry/events` | `telemetry.ts` | Query telemetry events. |
| DELETE | `/api/telemetry/events` | `telemetry.ts` | Clear all telemetry events. |
| GET | `/api/telemetry/status` | `telemetry.ts` | Telemetry enabled flag + count. |
| POST | `/api/telemetry/toggle` | `telemetry.ts` | Enable/disable telemetry. |
| POST | `/api/telemetry/track` | `telemetry.ts` | Record a single event (frontend). |
| GET | `/api/compliance/status` | `compliance.ts` | EU AI Act per-article status. |
| POST | `/api/compliance/export` | `compliance.ts` | Generate audit report (JSON). |
| POST | `/api/compliance/export-pdf` | `compliance.ts` | Generate audit report (PDF binary). |
| GET | `/api/compliance/interactions` | `compliance.ts` | List recorded AI interactions. |
| POST | `/api/compliance/interactions` | `compliance.ts` | Record an AI interaction. |
| GET | `/api/compliance/models` | `compliance.ts` | Model inventory for a date range. |
| GET | `/api/compliance/templates` | `compliance.ts` | List compliance report templates. |
| GET | `/api/compliance/templates/:id` | `compliance.ts` | Get one template. |
| POST | `/api/compliance/templates` | `compliance.ts` | Create a template. |
| PATCH | `/api/compliance/templates/:id` | `compliance.ts` | Update a template. |
| DELETE | `/api/compliance/templates/:id` | `compliance.ts` | Delete a template. |
| GET | `/api/cost/summary` | `cost.ts` | Cost dashboard (today/week/all-time + budget). |
| GET | `/api/cost/by-workspace` | `cost.ts` | Per-workspace cost. **Tier: TEAMS.** |
| GET | `/api/costs` | `cost.ts` | Alias → `/api/cost/summary`. |
| GET | `/api/capabilities/status` | `capabilities.ts` | Plugins/MCP/skills/tools/commands/hooks/workflows status. |
| POST | `/api/capabilities/plugins/:name/enable` | `capabilities.ts` | Enable a plugin. |
| POST | `/api/capabilities/plugins/:name/disable` | `capabilities.ts` | Disable a plugin. |
### 1.12 Workflows (`03e`)
| Method | Path | Route file | Purpose |
|---|---|---|---|
| GET | `/api/workflows` | `workflows.ts` | List built-in + custom workflow templates. |
| POST | `/api/workflows` | `workflows.ts` | Create a custom workflow template. |
| DELETE | `/api/workflows/:name` | `workflows.ts` | Delete a custom workflow template. |
### 1.13 Real-time / Ops (`03f`)
| Method | Path | Route file | Purpose |
|---|---|---|---|
| GET | `/api/waggle/signals` | `waggle-signals.ts` | List recent WaggleDance UI signals. |
| POST | `/api/waggle/signals` | `waggle-signals.ts` | Publish a UI signal. |
| PATCH | `/api/waggle/signals/:id/ack` | `waggle-signals.ts` | Acknowledge a signal. |
| GET | `/api/waggle/stream` | `waggle-signals.ts` | **SSE** signal stream. |
| POST | `/api/waggle-dance/signal` | `waggle-dance.ts` | v2 protocol bus: dispatch a signal. |
| GET | `/api/waggle-dance/signals` | `waggle-dance.ts` | v2 ring-buffer snapshot. |
| GET | `/api/events` | `events.ts` | Paginated audit-event listing. |
| GET | `/api/events/stats` | `events.ts` | Audit aggregates. |
| GET | `/api/events/stream` | `events.ts` | **SSE** live audit events. |
| POST | `/api/cron` | `cron.ts` | Create a cron schedule. |
| GET | `/api/cron` | `cron.ts` | List schedules. |
| GET | `/api/cron/:id` | `cron.ts` | Get one schedule. |
| PATCH | `/api/cron/:id` | `cron.ts` | Update a schedule. |
| DELETE | `/api/cron/:id` | `cron.ts` | Delete a schedule. |
| POST | `/api/cron/:id/trigger` | `cron.ts` | Manually run now (auto-enables). |
| GET | `/api/cron/:id/history` | `notifications.ts` | Cron execution history. |
| GET | `/api/notifications/stream` | `notifications.ts` | **SSE** notifications + subagent status. |
| GET | `/api/notifications` | `notifications.ts` | List persisted notifications. |
| POST | `/api/notifications/:id/read` | `notifications.ts` | Mark one read. |
| GET | `/api/notifications/history` | `notifications.ts` | List (alias, limit 100). |
| PATCH | `/api/notifications/:id/read` | `notifications.ts` | Mark one read (PATCH). |
| POST | `/api/notifications/read-all` | `notifications.ts` | Mark all read. |
| GET | `/api/offline/status` | `offline.ts` | Offline state. |
| POST | `/api/offline/queue` | `offline.ts` | Queue a message. |
| GET | `/api/offline/queue` | `offline.ts` | List queued messages. |
| DELETE | `/api/offline/queue/:id` | `offline.ts` | Remove one queued message. |
| DELETE | `/api/offline/queue` | `offline.ts` | Clear all queued messages. |
| POST | `/api/backup` | `backup.ts` | Build + stream encrypted backup archive. |
| POST | `/api/restore` | `backup.ts` | Restore from an archive (`preview?`). |
| GET | `/api/backup/metadata` | `backup.ts` | Last backup info. |
| GET | `/api/fleet` | `fleet.ts` | List active workspace sessions (Mission Control). |
| POST | `/api/fleet/spawn` | `fleet.ts` | Spawn a new agent session. |
| POST | `/api/fleet/:workspaceId/pause` | `fleet.ts` | Pause a session. |
| POST | `/api/fleet/:workspaceId/resume` | `fleet.ts` | Resume a session. |
| POST | `/api/fleet/:workspaceId/kill` | `fleet.ts` | Abort + close a session. |
| GET | `/api/litellm/status` | `litellm.ts` | LiteLLM router status. |
| POST | `/api/litellm/restart` | `litellm.ts` | Restart the router. |
| GET | `/api/litellm/models` | `litellm.ts` | Available model IDs. |
| GET | `/api/litellm/pricing` | `litellm.ts` | Static per-model pricing. |
| GET | `/api/local-inference/hardware` | `local-inference.ts` | Detect GPU/RAM/CPU. |
| GET | `/api/local-inference/models` | `local-inference.ts` | Recommend models that fit. |
| GET | `/api/local-inference/status` | `local-inference.ts` | Ollama/vLLM availability. |
| POST | `/api/local-inference/pull` | `local-inference.ts` | Pull a model via Ollama. |
| GET | `/v1/health/liveliness` | `anthropic-proxy.ts` | Built-in proxy health. |
| POST | `/v1/chat/completions` | `anthropic-proxy.ts` | OpenAI-compatible Anthropic proxy (**SSE** when `stream`). |
| GET | `/api/browse/local` | `browse.ts` | List directories (local-only). |
| POST | `/api/browse/local/mkdir` | `browse.ts` | Create a directory (local-only). |
| GET | `/api/browser-ext/health` | `browser-ext.ts` | Browser-extension health check. |
| GET | `/api/telegram/status` | `telegram.ts` | Telegram config status. |
| POST | `/api/telegram/config` | `telegram.ts` | Save Telegram creds. |
| POST | `/api/telegram/test` | `telegram.ts` | Send a test message. |
| POST | `/api/telegram/send` | `telegram.ts` | Send arbitrary text. |
| GET | `/api/weaver/status` | `weaver.ts` | Weaver subsystem status. |
| POST | `/api/weaver/trigger` | `weaver.ts` | Trigger a Weaver run. |
### 1.14 Bootstrap / Stripe billing / WebSocket (`03g`)
| Method | Path | Source | Purpose |
|---|---|---|---|
| GET | `/health` | `local/index.ts` (inline) | Health probe (auth-exempt). |
| GET | `/api/auth/session-token` | `local/index.ts` (inline) | Bootstrap session token (same-origin, auth-exempt). |
| GET | `/api/debug/logs` | `local/index.ts` (inline) | Support bundle (same-origin). |
| GET | `/api/docs` | `local/index.ts` (inline) | Auto-generated route/OpenAPI listing. |
| GET | `/ws` | `local/index.ts` (inline) | WebSocket event-bus relay (`?token=`). |
| GET | `/*` | `local/index.ts` (inline) | SPA fallback (serves `index.html`). |
| POST | `/api/stripe/create-checkout-session` | `stripe/` (`stripeRoutes`) | Start Stripe checkout (PRO/TEAMS). |
| POST | `/api/stripe/webhook` | `stripe/` | Stripe webhook (raw body, signature-verified). |
| POST | `/api/stripe/sync` | `stripe/` | Poll-fallback payment confirmation. |
| POST | `/api/stripe/create-portal-session` | `stripe/` | Stripe billing portal. **Tier: PRO.** |
---
## Part 2 — PRD §16 Target Endpoints → Cross-Reference
Status legend:
- **EXISTS** — a sidecar route already serves this exact (or path-equivalent) contract.
- **PARTIAL** — closest current capability exists but path/shape/semantics differ; the refactor extends/aliases rather than builds net-new.
- **MISSING** — no sidecar route provides this; net-new backend work required.
> Verification: every MISSING row was grep-confirmed absent from `packages/server/src/local/routes/*.ts`
> (`/api/share`, `/api/home`, `/api/quick-capture`, `/api/command`, `/api/artifacts`, `/api/automations`,
> `/api/mcps`, `/api/agents/:id/{run,pause,traces}`, `/api/skills/:id/{install,test}`,
> `/api/memory/merge`, `/api/memory/:id/archive`, `/api/connectors/:id/{sync,revoke}` — **0 matches**).
### 16.1 Home
| PRD endpoint | Status | Current path / note |
|---|---|---|
| `GET /api/home/briefing` | **MISSING** | No `/api/home/*` route. Data is assemblable from `GET /api/workspaces/:id/context` (greeting/summary/threads/pendingTasks/upcomingSchedules) + `GET /api/cost/summary`, but no Home aggregation endpoint exists. Net-new. |
| `POST /api/quick-capture` | **PARTIAL** | No `/api/quick-capture`. Closest: `POST /api/memory/frames` (`memory.ts`) writes a frame directly. Quick-capture = thin wrapper (default personal mind + `source`); extend rather than build new substrate. |
| `GET /api/home/overnight` | **MISSING** | No overnight-digest route. Inputs exist (`GET /api/events`, `GET /api/notifications`, `GET /api/cron/:id/history`) but no aggregation endpoint. Net-new. |
### 16.2 Workspaces
| PRD endpoint | Status | Current path / note |
|---|---|---|
| `GET /api/workspaces` | **EXISTS** | `workspaces.ts`. |
| `POST /api/workspaces` | **EXISTS** | `workspaces.ts`. |
| `GET /api/workspaces/:id` | **EXISTS** | `workspaces.ts`. |
| `PATCH /api/workspaces/:id` | **EXISTS** | `workspaces.ts` (also `PUT`). |
| `GET /api/workspaces/:id/state` | **PARTIAL** | No `/state` route. `GET /api/workspaces/:id/context` returns `workspaceState` as a sub-object. Either alias `/state` to that sub-object or add a thin route. |
| `GET /api/workspaces/:id/context` | **EXISTS** | `workspaces.ts` — the "Workspace Now" catch-up block. |
| `GET /api/workspaces/:id/activity` | **PARTIAL** | No per-workspace `/activity`. Closest: `GET /api/events?workspaceId=` (`events.ts`) and `GET /api/teams/:id/activity`. Add a thin `/activity` alias over the audit-event query. |
### 16.3 Command Center
| PRD endpoint | Status | Current path / note |
|---|---|---|
| `GET /api/command/search?q=` | **MISSING** | No `/api/command/*`. Note `commands.ts` is `/api/commands/execute` (slash-command exec, different shape). PRD's "command palette" search needs net-new (federate over workspaces/memory/skills/sessions). |
| `POST /api/command/execute` | **PARTIAL** | `POST /api/commands/execute` exists (note **plural** `commands`) but only runs slash commands with a subset CommandContext; PRD's generic command-palette execute is broader. Reuse/rename + extend. |
| `GET /api/command/recent` | **MISSING** | No recent-commands surface. Net-new (or derive client-side from session history). |
| `GET /api/command/suggestions` | **MISSING** | No command-suggestions route. Closest analog is `GET /api/skills/suggestions` (different domain). Net-new. |
### 16.4 Memory
| PRD endpoint | Status | Current path / note |
|---|---|---|
| `GET /api/memory` | **PARTIAL** | List is `GET /api/memory/frames`; search is `GET /api/memory/search`. PRD's bare `/api/memory` maps to `/frames` (alias or accept both). |
| `GET /api/memory/:id` | **MISSING** | No single-frame GET. Frames are addressable for PUT/PATCH/DELETE (`/api/memory/frames/:id`) but there is no `GET .../frames/:id`. Add a thin read route. |
| `POST /api/memory` | **PARTIAL** | `POST /api/memory/frames` exists. PRD bare path = alias of `/frames`. |
| `PATCH /api/memory/:id` | **PARTIAL** | `PUT /api/memory/frames/:id` edits content/importance (PRD uses `PATCH`; semantics match). Accept `PATCH` + bare path or alias. |
| `POST /api/memory/:id/archive` | **MISSING** | No archive action. `importance: 'deprecated'` exists as a value but no archive endpoint; closest mutation is `PUT /api/memory/frames/:id`. Net-new (or model archive as an importance/status edit). |
| `DELETE /api/memory/:id` | **PARTIAL** | `DELETE /api/memory/frames/:id` exists; PRD uses the bare `:id` path. Alias. |
| `POST /api/memory/merge` | **MISSING** | No frame-merge route. Net-new (dedup/merge of duplicate frames). |
| `GET /api/memory/graph` | **EXISTS** | `knowledge.ts`. |
### 16.5 Harvest
| PRD endpoint | Status | Current path / note |
|---|---|---|
| `POST /api/harvest/preview` | **EXISTS** | `harvest.ts`. |
| `POST /api/harvest/commit` | **EXISTS** | `harvest.ts`. |
| `GET /api/harvest/sources` | **EXISTS** | `harvest.ts`. |
| `POST /api/harvest/sources/:id/sync` | **PARTIAL** | No per-source `/sync` action. Sources are registered/toggled via `POST /api/harvest/sources`, `PATCH /api/harvest/sources/:source` (auto-sync config); the actual sync happens through `POST /api/harvest/commit`. Add a thin per-source `/sync` that resolves the source + calls commit. Note PRD uses `:id`; current sources are keyed by `:source` name. |
### 16.6 Artifacts
| PRD endpoint | Status | Current path / note |
|---|---|---|
| `GET /api/artifacts` | **PARTIAL** | No `/api/artifacts` domain. Closest substrates: workspace file registry `GET /api/workspaces/:id/files` (`workspaces.ts`), managed files `GET /api/workspaces/:workspaceId/files/list` (`files.ts`), and document versions `GET /api/workspaces/:id/documents` (`documents.ts`). PRD "artifacts" = a new unified abstraction over these; needs a net-new aggregation layer reusing the existing stores. |
| `POST /api/artifacts` | **PARTIAL** | Closest writes: `POST /api/ingest`, `POST /api/workspaces/:workspaceId/files/upload`, `POST /api/workspaces/:id/documents`. New artifact-create endpoint needed. |
| `GET /api/artifacts/:id` | **MISSING** | No artifact-by-id read. Net-new. |
| `PATCH /api/artifacts/:id` | **MISSING** | No artifact update. Net-new. |
| `DELETE /api/artifacts/:id` | **PARTIAL** | Closest: `POST /api/workspaces/:workspaceId/files/delete`, `DELETE /api/workspaces/:id/storage/delete`. New artifact-delete endpoint needed. |
| `GET /api/artifacts/search-related?q=` | **MISSING** | No related-artifact search. Net-new (could lean on memory/wiki search internally). |
### 16.7 Agents
> **Naming collision:** PRD's `/api/agents/*` (CRUD + run/pause/traces) matches the **Cloud** server's
> Clerk-gated `routes/agents.ts` (`/api/agents`, `/api/agents/:id`, etc.) — **NOT** the sidecar. The
> sidecar's agent surface is `/api/agent/*` (singular: status/cost/model) + `/api/agents/active` +
> `/api/agent-groups/*` + `/api/fleet/*`. So in the desktop (sidecar) context, the PRD §16.7 agent CRUD
> is **MISSING** locally even though a Clerk-gated cloud analog exists.
| PRD endpoint | Status | Current path / note |
|---|---|---|
| `GET /api/agents` | **MISSING (sidecar)** | Sidecar has `GET /api/agents/active` (live orchestrator state) only. Persona catalog `GET /api/personas` + groups `GET /api/agent-groups` are the closest "agent definitions". Cloud `GET /api/agents` (Clerk) is a separate server. |
| `POST /api/agents` | **MISSING (sidecar)** | No sidecar agent-create. Closest: `POST /api/personas` (custom persona) / `POST /api/agent-groups`. Cloud-only `POST /api/agents` exists (Clerk). |
| `GET /api/agents/:id` | **MISSING** | No sidecar agent-by-id. Net-new (or map onto persona/group id). |
| `PATCH /api/agents/:id` | **MISSING** | No sidecar route. Closest: `PATCH /api/personas/:id` / `PATCH /api/agent-groups/:id`. |
| `POST /api/agents/:id/run` | **PARTIAL** | No per-agent `/run`. Closest run paths: `POST /api/fleet/spawn` (`{ task, persona?, model? }` — real execution), `POST /api/agent/run` (one-shot retrieval SSE), `POST /api/agent-groups/:id/run` (placeholder stub). Wire `/agents/:id/run` onto fleet-spawn. |
| `POST /api/agents/:id/pause` | **PARTIAL** | No per-agent `/pause`. Closest: `POST /api/fleet/:workspaceId/pause`. Map agent→session and reuse. |
| `GET /api/agents/:id/traces` | **PARTIAL** | No per-agent `/traces`. Closest: session timeline `GET /api/workspaces/:wid/sessions/:sid/timeline` and the execution-trace store (no dedicated HTTP listing). Add a `/traces` route reading the trace store. |
### 16.8 Skills
| PRD endpoint | Status | Current path / note |
|---|---|---|
| `GET /api/skills` | **EXISTS** | `skills.ts`. |
| `POST /api/skills` | **EXISTS** | `skills.ts` (raw create; also `POST /api/skills/create` structured). |
| `PATCH /api/skills/:id` | **PARTIAL** | Update is `PUT /api/skills/:name` (keyed by **name**, method `PUT`). PRD uses `PATCH` + `:id`. Accept `PATCH` / alias name↔id. |
| `POST /api/skills/:id/test` | **PARTIAL** | Test exists but as `POST /api/skills/test` (body-driven, not per-id path). Add `:id` path variant or pass via body. |
| `POST /api/skills/:id/install` | **PARTIAL** | No per-skill `/install` by arbitrary id. Closest installs: `POST /api/skills/starter-pack/:id`, `POST /api/skills/capability-packs/:id`, and marketplace `POST /api/marketplace/install`. Add a unified `/skills/:id/install` that dispatches by source. |
### 16.9 Connectors / MCPs / Marketplace
| PRD endpoint | Status | Current path / note |
|---|---|---|
| `GET /api/connectors` | **EXISTS** | `connectors.ts`. |
| `POST /api/connectors/:id/connect` | **EXISTS** | `connectors.ts`. |
| `POST /api/connectors/:id/sync` | **MISSING** | No connector `/sync` action. Net-new (re-fetch from connected service). |
| `POST /api/connectors/:id/revoke` | **PARTIAL** | Closest: `POST /api/connectors/:id/disconnect` (removes vault creds + sub-keys). Same intent, different verb. Alias `/revoke` → disconnect or add. |
| `GET /api/mcps` | **PARTIAL** | No `/api/mcps`. MCP servers surface inside `GET /api/capabilities/status` (`mcpServers[]`); MCP catalog lives in `@waggle/shared` `mcp-catalog.ts` (no dedicated HTTP route). Net-new dedicated MCP listing endpoint (or extract from capabilities/status + catalog). |
| `POST /api/mcps/install` | **PARTIAL** | No `/api/mcps/install`. MCP servers are installed via the marketplace path (`POST /api/marketplace/install`) and plugin install (`POST /api/plugins/install`). Add an MCP-specific install or route through marketplace. |
| `POST /api/mcps/:id/test` | **MISSING** | No MCP test/health route. Closest analog: `GET /api/connectors/:id/health`. Net-new for MCP. |
| `POST /api/mcps/:id/revoke` | **MISSING** | No MCP revoke/uninstall by id. Closest: `DELETE /api/plugins/:name`. Net-new for MCP. |
| `GET /api/marketplace` | **PARTIAL** | Marketplace listing is `GET /api/marketplace/search` (+ `/packs`, `/installed`, `/categories`). PRD's bare `/api/marketplace` = alias of `/search` (default params). |
| `POST /api/marketplace/install` | **EXISTS** | `marketplace.ts` (**Tier: PRO**, SecurityGate). |
### 16.10 Automations
> **No `/api/automations/*` routes exist.** The underlying capability is **cron** (`cron.ts`,
> `/api/cron/*`), which provides full CRUD + trigger + history. "Automations" = a rename/extension of cron.
| PRD endpoint | Status | Current path / note |
|---|---|---|
| `GET /api/automations` | **PARTIAL** | Maps to `GET /api/cron` (`cron.ts`). Rename/alias the cron surface as "automations". |
| `POST /api/automations` | **PARTIAL** | Maps to `POST /api/cron`. |
| `PATCH /api/automations/:id` | **PARTIAL** | Maps to `PATCH /api/cron/:id`. |
| `POST /api/automations/:id/run` | **PARTIAL** | Maps to `POST /api/cron/:id/trigger` (auto-enables + runs). |
| `POST /api/automations/:id/pause` | **PARTIAL** | No `/pause`; equivalent is `PATCH /api/cron/:id { enabled: false }`. Add a thin `/pause` or use the enabled flag. |
| `GET /api/automations/:id/logs` | **PARTIAL** | Maps to `GET /api/cron/:id/history` (in `notifications.ts`). |
### 16.11 Team / RBAC
| PRD endpoint | Status | Current path / note |
|---|---|---|
| `GET /api/teams/:id` | **EXISTS** | `team.ts` (local CRUD; returns members + workspaces). |
| `POST /api/teams/:id/invite` | **PARTIAL** | Invite is `POST /api/teams/:id/members` (`{ userId?, email?, displayName?, role? }`). Same intent, different path name. Alias `/invite` → `/members`. |
| `PATCH /api/teams/:id/members/:memberId` | **EXISTS** | `team.ts` — `PATCH /api/teams/:id/members/:userId` (PRD's `:memberId` == `:userId`). Also `PUT` variant. |
| `GET /api/teams/:id/audit` | **PARTIAL** | Closest: `GET /api/teams/:id/activity` (aggregated audit events across team workspaces) and `GET /api/events`. Alias `/audit` → `/activity` or add. |
| `POST /api/share` | **MISSING** | No `/api/share` route anywhere in the repo (grep-confirmed). Sharing is implicit via team workspaces + `teamId` linkage; no explicit share endpoint. Net-new. |
---
## Part 3 — Summary Counts
### Existing local sidecar endpoints (Part 1)
| Domain group | Count |
|---|---|
| Chat / Agent exec / Sessions (`03a`) | 23 |
| Approvals (`03a`/`03e`) | 5 |
| Memory + Knowledge graph (`03b`) | 8 |
| Wiki (`03b`) | 8 |
| Harvest (`03b`) | 12 |
| Import / Ingest / Identity / Mind / Documents / Erase / Export (`03b`) | 13 |
| Workspaces / Templates / Storage / Files / Tasks / Pins (`03c`+`04`) | 38 |
| Team / RBAC (`03c`) | 20 |
| Personas / Settings / Tier / Profile (`03c`) | 26 |
| Marketplace / Skills / Plugins / Connectors / Tools / OAuth / Vault / Providers (`03d`) | 56 |
| Evolution / Feedback / Telemetry / Compliance / Cost / Capabilities (`03e`) | 31 |
| Workflows (`03e`) | 3 |
| Real-time / Ops (`03f`) | 60 |
| Bootstrap / Stripe / WebSocket (`03g`) | 10 |
| **Total existing local sidecar endpoints** | **313** |
> Aligns with the backend-map domain overview (~294 endpoints across 7 domains in `06-api-domains.md`;
> this inventory additionally counts inline bootstrap routes, the `/v1/*` proxy, weaver/tasks/files, and
> tier-gated billing routes individually). Dev-only `/_dev/marketplace/*` (4 routes, env-gated) and the
> separate Clerk-gated **Cloud** server routes are excluded.
### PRD §16 target endpoints (Part 2)
| Section | Total | EXISTS | PARTIAL | MISSING |
|---|---|---|---|---|
| 16.1 Home | 3 | 0 | 1 | 2 |
| 16.2 Workspaces | 7 | 5 | 2 | 0 |
| 16.3 Command Center | 4 | 0 | 1 | 3 |
| 16.4 Memory | 8 | 2 | 4 | 2 |
| 16.5 Harvest | 4 | 3 | 1 | 0 |
| 16.6 Artifacts | 6 | 0 | 3 | 3 |
| 16.7 Agents | 7 | 0 | 3 | 4 |
| 16.8 Skills | 5 | 2 | 3 | 0 |
| 16.9 Connectors/MCPs/Marketplace | 10 | 2 | 4 | 4 |
| 16.10 Automations | 6 | 0 | 6 | 0 |
| 16.11 Team/RBAC | 5 | 2 | 2 | 1 |
| **Total** | **65** | **16** | **30** | **19** |
**Headline:** Of 65 PRD §16 target endpoints, **16 EXIST** as-is, **30 are PARTIAL** (closest current
path exists — refactor extends/aliases over the existing substrate), and **19 are MISSING** (net-new
backend work). The MISSING set clusters in three net-new domains the PRD invents — **Home** (briefing/
overnight), **Command Center** (palette search/recent/suggestions), and **Artifacts** (unified
file/document/output abstraction) — plus **MCP-specific** management (test/revoke), **memory merge/
archive/by-id**, **per-agent run/traces**, and **`/api/share`**. None require a new data store: every
MISSING endpoint can be built over existing substrates (memory frames, file registry, document versions,
cron, audit events, execution traces, capabilities/status), consistent with the LOCKED in-place
incremental-refactor model.

380
docs/ux-refactor/_inventory/frontend.md Normal file
View File

@@ -0,0 +1,380 @@
# 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.

286
docs/ux-refactor/_inventory/substrate-types.md Normal file
View File

@@ -0,0 +1,286 @@
# Substrate & Types Inventory — UX Refactor
> Source-grounded inventory for the Waggle OS UX-refactor plan. Every claim cites a real file
> path (and line where load-bearing). Execution model is **in-place incremental refactor** of the
> existing substrate, not a rebuild. PRD = `docs/Waggle_OS_UX_Refactor_Master_Handoff_Package/Waggle_OS_UX_Refactor_PRD.md`.
---
## (a) WorkspaceConfig — current fields vs PRD §15.3 `WorkspaceConfigV2`
**Current type:** `WorkspaceConfig` in `packages/hive-mind-core/src/workspace-manager.ts:5-58`
(the persisted `workspace.json` shape; CRUD via `WorkspaceManager.create/list/get/update/delete`,
same file `:124-244`). The frontend mirror is `Workspace` in `apps/web/src/lib/types.ts:22-40`
(a DIFFERENT, lossy shape — see delta in §(e)).
PRD §15.3 target: `WorkspaceConfigV2` (PRD lines 961-985).
| PRD V2 field | Present in current `WorkspaceConfig`? | Notes / source |
|---|---|---|
| `id` | ✅ present | `:6` |
| `name` | ✅ present | `:7` |
| `description` | ❌ **MISSING** | not in config; would be new persisted field |
| `type` (`WorkspaceType`) | ❌ **MISSING** | no workspace-type concept; only `group` (free string) + `templateId` exist (`:8`, `:15`) |
| `group` | ✅ present | `:8` |
| `icon` | ✅ present | `:9` |
| `status` (`active`/`paused`/`archived`) | ❌ **MISSING** | no lifecycle status field anywhere in config |
| `model` | ✅ present | `:10` |
| `personaId` | ✅ present | `:13` |
| `templateId` | ✅ present | `:15` |
| `tools` | ✅ present | `:16` |
| `skills` | ✅ present | `:17` |
| `agentIds` | ❌ **MISSING** | no agent-membership array on workspace |
| `connectorIds` | ❌ **MISSING** | connectors are global (`/api/connectors`), not workspace-scoped in config |
| `mcpIds` | ❌ **MISSING** | MCPs tracked via `install_audit` / marketplace, not on workspace config |
| `storageType` | ✅ present | `:22` (`'virtual' \| 'local' \| 'team'`) — matches V2 exactly |
| `storagePath` | ✅ present | `:24` |
| `teamId` | ✅ present | `:31` |
| `teamRole` (`owner/admin/member/viewer`) | ✅ present | `:35` — matches V2 union exactly |
| `riskLevel` (`minimal/limited/high-risk/unacceptable`) | ✅ present | `:55` (`AIActRiskLevel`, defined `:3`) — matches V2 union exactly |
| `created` | ✅ present | `:27` (ISO string) |
| `updatedAt` | ❌ **MISSING** | `update()` overwrites `workspace.json` but stamps NO `updatedAt` (`:222-234`). Only `riskClassifiedAt` is auto-stamped on risk change (`:226-229`). |
| `lastActiveAt` | ❌ **MISSING** | not persisted. Frontend `Workspace.lastActive` (`apps/web/src/lib/types.ts:32`) is DERIVED at read time from session-file mtimes / frame `created_at` (see `workspace-context.ts:375-387` legacy path), never written back to config. |
**Extra current fields NOT in PRD V2 (keep — do not drop):** `personality` (`:11`),
`team` (legacy nullable string, `:18`), `storageConfig` (`:26`), `teamServerUrl`/`teamUserId`
(`:33`,`:37`), `budget` (`:41`), `tone` (`:45`), `optimizationEnabled`/`optimizationBudget`
(`:49`,`:51`), `riskClassifiedAt` (`:57`).
**Migration verdict:** All 7 missing V2 fields (`description`, `type`, `status`, `agentIds`,
`connectorIds`, `mcpIds`, `updatedAt`, `lastActiveAt`) live in a JSON file (`workspace.json`),
NOT in SQLite — so there is **no DB migration**. They are pure additive optional fields on the
`WorkspaceConfig` interface + `CreateWorkspaceOptions` (`workspace-manager.ts:60-95`), plus two
write-side touches: stamp `updatedAt` in `update()` (`:222`) and stamp `lastActiveAt` from the
agent loop / chat route. `type` and `status` need defaults for the ~existing workspaces
(`type` derivable from `templateId`/`group`; `status` defaults `'active'`).
---
## (b) Workspace-state builder outputs vs Home Cockpit + Workspace Desktop needs
**Builders (two layers):**
- `buildWorkspaceState()` → `WorkspaceState` — `packages/server/src/local/workspace-state.ts:234-311`.
Outputs (interface `:38-55`): `active`, `openQuestions`, `pending`, `blocked`, `completed`,
`stale`, `recentDecisions`, `nextActions`. Each is `StateItem[]` (`:30-36`:
`content / freshness('fresh'|'aging'|'stale') / source('memory'|'session'|'awareness') /
sourceId / dateLastTouched`), except `nextActions: string[]`.
- `buildWorkspaceNowBlock()` → `WorkspaceNowBlock` — `packages/server/src/local/routes/workspace-context.ts:191-404`.
Wraps `WorkspaceState` for backward-compat (`:14-29`): `workspaceName`, `summary`,
`recentDecisions[]`, `activeThreads[]`, `progressItems[]`, `nextActions[]`, `greeting`,
`pendingTasks[]`, `upcomingSchedules[]`, plus the raw `structuredState`.
**Data sources:** memory frames (`memory_frames`, via `MindDB`), session JSONL logs
(`extractProgressItems`/`extractOpenQuestions`/`classifyThreads` from `routes/sessions.js`,
imported `workspace-state.ts:16-23`), awareness layer (`awareness` table,
`extractAwarenessItems` `:122-138`), and cron schedules (`buildUpcomingSchedules`
`workspace-context.ts:169-187`). Freshness is timestamp-derived, not type-derived (`:63-72`).
### Coverage vs PRD §12.1 Home Cockpit (PRD lines 384-393)
| Home Cockpit FR | Backed by current builder? | Gap |
|---|---|---|
| Greeting + name + date/time | Partial — `greeting` exists (`buildTimeAwareGreeting` `workspace-context.ts:119-152`) | Greeting is workspace-scoped + time/inactivity-based; carries NO user name (identity name lives in `identity` table, not threaded in). Home is cross-workspace; builder is single-workspace. |
| Active/recent workspaces ranked by recency+priority | ❌ **MISSING** | Builder is **per-workspace**. No cross-workspace ranking aggregator exists. Home needs a NEW `GET /api/home/briefing` that fans out over `WorkspaceManager.list()` and ranks. |
| Overnight summary (memories consolidated, artifacts created, automations completed, failures) | ❌ **MISSING** | No "overnight"/time-windowed delta. `completed` exists but is session-derived, not a since-last-login diff. No artifact or automation counters. PRD §16.1 `GET /api/home/overnight` is net-new. |
| Upcoming meetings/events/tasks | Partial | `upcomingSchedules` (cron only, `:169-187`) + `pendingTasks` (`:158-163`). No calendar/meeting source. |
| Suggested next actions | ✅ present | `nextActions` (`deriveNextActions` `workspace-state.ts:182-218`) — but per-workspace, not blended cross-workspace. |
| Quick capture (note/task/link/file) | ❌ **MISSING** | No capture endpoint. PRD §16.1 `POST /api/quick-capture` is net-new (can write to `memory_frames` + `awareness`). |
### Coverage vs PRD §12.2 Workspace Desktop (PRD lines 423-429)
| Workspace Desktop need | Backed? | Gap |
|---|---|---|
| Header: name, **type**, **status**, team/avatars, share | Partial | name/team present; `type`+`status` are the missing `WorkspaceConfigV2` fields (§a). |
| Tabs: Overview/Chat/Research/Artifacts/Memory/Tasks/Timeline/Settings | Partial | Overview = `WorkspaceState`; Memory = `/api/memory/frames`; Timeline = `ai_interactions`/`execution_traces`; **Artifacts has no backing entity at all** (see §e). Tasks ≈ `pending`/`blocked` StateItems + `awareness` (no first-class task store locally). |
| Canvas widgets: chat, key artifacts, tasks, memory highlights, research, recent activity | Partial | memory highlights = `recentDecisions`/frames; recent activity = `active`/`activeThreads`; **artifacts widget unbacked**; "research overview" unbacked. |
| Right panel: info, members, last activity, quick actions | Partial | last activity derivable; members from `/api/team/members`; "last activity" needs `lastActiveAt` (§a missing). |
| Status bar: agents running, automations active, MCPs connected | Partial | agents via `/api/fleet`; MCPs connected derivable from `install_audit`/connectors; automations = cron. No single aggregate. |
**Verdict:** The per-workspace builder is a strong seed for **Workspace Desktop Overview** and
maps cleanly to `GET /api/workspaces/:id/state` (PRD §16.2 — note: route does NOT exist yet;
only `/api/workspaces/:id/context` exists, `workspaces.ts:311`). **Home Cockpit needs a NEW
cross-workspace aggregation layer** (`/api/home/briefing`, `/api/home/overnight`,
`/api/quick-capture` — all net-new) that fans the existing single-workspace builder over
`WorkspaceManager.list()` and adds overnight-delta + quick-capture write paths.
---
## (c) Mind schema tables & Memory provenance/confidence (PRD §15.4)
**Schema:** `packages/hive-mind-core/src/mind/schema.ts` (`SCHEMA_VERSION = '1'`, `:1`). Tables:
`meta`, `identity` (`:11`), `awareness` (`:24`), `sessions` (`:35`), **`memory_frames`** (`:47`),
`memory_frames_fts` (`:68`), `memory_frames_vec` (vec0 1024-d, `VEC_TABLE_SQL :261`),
`knowledge_entities` (`:75`), `knowledge_relations` (`:88`), `improvement_signals` (`:103`),
`install_audit` (`:119`), `procedures` (`:141`), `ai_interactions` (`:155`),
`execution_traces` (`:199`), `evolution_runs` (`:220`), `harvest_sources` (`:246`).
**`memory_frames` columns** (`:47-62`): `id, frame_type('I'|'P'|'B'), gop_id, t, base_frame_id,
content, importance(critical/important/normal/temporary/deprecated), source(user_stated/
tool_verified/agent_inferred/import/system), access_count, created_at, last_accessed`.
TS mirror: `MemoryFrame` in `mind/frames.ts:23-35` (note: `FrameSource` union in TS `:21` is
WIDER — adds `personal/workspace/team_sync` — than the DB CHECK; a latent drift).
### PRD §15.4 field-by-field (PRD lines 990-1013)
| PRD memory field | Backing in `memory_frames`? | Gap / where it fits |
|---|---|---|
| `id` | ✅ `id` | — |
| `kind` (`fact/decision/task/preference/strategy/learning/goal/entity`) | ❌ **MISSING** | Only `frame_type` (I/P/B) exists — an orthogonal axis. PRD `MemoryKind` is currently DERIVED heuristically (LIKE-matching content for "decision" in `workspace-state.ts:82-111`). Needs a `kind` column OR metadata. |
| `title` | ❌ **MISSING** | Frames are content-only; title is synthesized from first line (`workspace-state.ts:97-101`). |
| `content` | ✅ `content` | — |
| `scope` (`personal/workspace/team/organization`) | ⚠️ **IMPLICIT** | Not a column. Scope is encoded by WHICH `.mind` file the frame lives in (personal.mind vs workspace.mind), surfaced as `_mind` tag in the API (`memory.ts:200,209`). No `team`/`organization` scope on a single frame. |
| `workspaceId` | ⚠️ **IMPLICIT** | Per-file, not per-row (frames live in that workspace's `.mind`). |
| `teamId` | ❌ **MISSING** | team frames are a separate sync path; no `teamId` on frame. |
| `source` (origin label) | ✅ `source` | `:56` — but enum is provenance-CLASS (`user_stated`/`import`/...), not a source id/url. |
| `sourceId` | ❌ **MISSING** | Harvest provenance is embedded as a text prefix `[hm session:… src:…]` in `content` (`frames.ts:51-62`, `stripHmPrefix`), NOT a structured column. |
| `sourceUrl/path` | ❌ **MISSING** | Same — only in the text prefix / not structured. (`harvest_sources.source_path` exists at source-level `:251`, not per-frame.) |
| `confidence` (0-100) | ❌ **MISSING on frames** | NO confidence column on `memory_frames`. (Confidence DOES exist on `knowledge_relations.confidence REAL` `:93` — graph edges only.) Closest frame proxy is `importance` (categorical) + `source` (trust class). |
| `importance` | ✅ `importance` | `:54` — categorical, not numeric. |
| `evidence[]` | ❌ **MISSING** | No evidence list. Could map to FTS hits / `base_frame_id` lineage (`:52`) / related entities, but no first-class field. |
| `tags[]` | ❌ **MISSING** | No tags column. |
| `relatedMemoryIds[]` | ⚠️ Partial | `base_frame_id` (`:52`) gives I→P lineage only; no general relation. |
| `relatedArtifactIds[]` | ❌ **MISSING** | No artifact entity exists (§e). |
| `createdAt` | ✅ `created_at` | — |
| `updatedAt` | ❌ **MISSING** | Frames are append-only (P-frames supersede); `last_accessed` (`:60`) is access-time, not edit-time. |
| `lastAccessedAt` | ✅ `last_accessed` | `:60` |
| `status` | ⚠️ Partial | `importance='deprecated'` (`:55`) ≈ archived/deprecated; no explicit `active/conflict/trash` status. PRD §12.4 Memory tabs need Active/Trash + conflict/low-confidence states (PRD 498,504-513). |
### Metadata vs migration verdict
**Critical:** `memory_frames` has **NO `metadata` column** (unlike `awareness.metadata`,
`knowledge_entities.properties`, `knowledge_relations.properties`, `improvement_signals.metadata`,
`evolution_runs.artifacts_json` — all of which have a JSON blob). PRD §15.4's "use `metadata`
initially" assumes a metadata column that does not exist on frames today.
The migration runner already does idempotent additive `ADD COLUMN` on `memory_frames`
(it added `source` — `mind/db.ts:116-124`, pattern: `pragma_table_info` guard + `ALTER TABLE …
ADD COLUMN`). So the lowest-risk path is one migration adding a single nullable
`metadata TEXT NOT NULL DEFAULT '{}'` column to `memory_frames`, storing
`{kind, title, scope, sourceId, sourceUrl, confidence, tags, evidence, relatedMemoryIds, status}`
as JSON. This avoids touching the FTS/vec virtual tables and the IPB scoring logic.
PRD §15.4 itself endorses metadata-first, explicit-fields-later (PRD line 1013). If
`confidence` becomes a primary query/filter axis (PRD §12.4 "filter by confidence",
"low-confidence surfaced for review"), promote `confidence REAL` to a real column in a later
migration (precedent: same ADD-COLUMN pattern) so it's indexable.
---
## (d) install-audit — capabilities for Extend governance
**Store:** `InstallAuditStore` in `packages/core/src/install-audit.ts` (operates on `.mind`).
DDL duplicated in two places that MUST stay in sync (`install-audit.ts:54-74` and
`schema.ts:119-138` — comment warns of prior drift crash, `schema.ts:122-126`).
**Audit entry shape** (`InstallAuditEntry` `:24-37`):
`id, timestamp, capability_name, capability_type, source, version, risk_level, trust_source,
approval_class, action, initiator, detail`.
**Enums (governance-relevant):**
- `AuditCapabilityType` (`:22`): `native | skill | plugin | mcp | connector | marketplace` —
covers the entire PRD Extend layer (Connectors/MCPs/Marketplace/Skills).
- `AuditAction` (`:15`): `proposed | approved | installed | rejected | failed | blocked`.
- `AuditTrustSource` (`:17-19`): `builtin | starter_pack | local_user | third_party_verified |
third_party_unverified | unknown | security-gate`.
- `AuditApprovalClass` (`:20`): `standard | elevated | critical | blocked`.
- `AuditInitiator` (`:21`): `agent | user | system`.
- `AuditRiskLevel` (TS `:16`): `low | medium | high | critical`.
**Read API (in-store, not yet HTTP):** `getByCapability()` (`:125`), `getByAction()` (`:132`),
`getRecent(limit)` (`:139`), `getAll()` (`:146`).
**Write path (live):** the marketplace install route calls `fastify.auditStore.record(...)` on
every SecurityGate verdict (CRITICAL→403, HIGH gated, MEDIUM/LOW logged) —
`packages/server/src/local/routes/marketplace.ts:224-319`. So an audit trail is already being
written for installs.
**Gaps for Extend governance UI:**
1. **No HTTP endpoint surfaces the audit trail.** `getRecent`/`getByCapability` have no route
(grep over `packages/server/src/local/routes` finds writes only). The Extend governance view
(who installed what, when, risk, trust, approval) needs a NEW read route, e.g.
`GET /api/extend/audit` — there is no PRD §16 endpoint for this; it's an implied addition
to §16.9.
2. **`risk_level` enum drift (latent bug, not session-induced).** TS `AuditRiskLevel` includes
`'critical'` (`install-audit.ts:16`) but BOTH DDL CHECK constraints only allow
`('low','medium','high')` (`install-audit.ts:65` and `schema.ts:130`). A `record()` with
`riskLevel:'critical'` would throw a CHECK violation. The marketplace route sidesteps this by
mapping CRITICAL severity to `riskLevel:'high'` + `approvalClass:'blocked'` — but any future
caller passing `'critical'` crashes. Flag for the plan.
3. **Audit is per-`.mind` (per-workspace).** Governance across all installs (the Extend layer is
global) requires either querying personal.mind or aggregating — confirm which `.mind` the
`auditStore` decorator binds to.
---
## (e) Frontend types delta vs PRD §15.2-15.6
**Frontend types:** `apps/web/src/lib/types.ts`. Shared/server types: `packages/shared/src/types.ts`.
### PRD §15.2 target literal unions (PRD 944-954) — NONE currently exist in frontend
| PRD union | In `apps/web/src/lib/types.ts`? | Closest existing |
|---|---|---|
| `WorkspaceType` | ❌ **MISSING** | none |
| `Scope` (`personal/workspace/team/organization`) | ❌ **MISSING** | `_mind` informal tag only |
| `Confidence` (0-100) | ❌ **MISSING** | `MemoryFrame.importance: number` (`:124`) — different axis |
| `MemoryKind` | ❌ **MISSING** | `MemoryFrame.type` (`:120`: `fact/event/insight/decision/task/entity`) — OVERLAPS but mismatched (FE has `event`/`insight`; PRD has `preference`/`strategy`/`learning`/`goal`) |
| `ArtifactKind` | ❌ **MISSING** | none — no Artifact type at all |
| `AgentType` | ❌ **MISSING** | none (`AgentDef` in shared has no `type`) |
| `AutonomyLevel` | ❌ **MISSING** | none in FE types (autonomy exists conceptually in agent runtime) |
| `ExtensionType` | ❌ **MISSING** | none |
### §15.2 Frontend `Workspace` (types.ts:22-40) vs `WorkspaceConfigV2`
The FE `Workspace` is a **lossy projection** distinct from the persisted `WorkspaceConfig`:
has `persona` (string, vs config `personaId`), `hue`/`memoryCount`/`sessionCount`/`lastActive`/
`health`/`budget{used,limit}`/`shared` (DERIVED display fields, not persisted), but LACKS
`type`, `status`, `description`, `agentIds`, `connectorIds`, `mcpIds`, `updatedAt`. To reach V2
the FE type needs the same 7 additions as §(a) plus alignment of `persona`→`personaId`.
### §15.4 Memory — FE `MemoryFrame` (types.ts:118-127)
FE shape: `id, type(MemoryKind-ish), title, content, importance(number), timestamp, workspaceId,
metadata?`. Closer to PRD than the DB row (it HAS `title`, `metadata`, `workspaceId`), but
MISSING: `kind` (uses `type`), `scope`, `teamId`, `source`, `sourceId`, `sourceUrl`, `confidence`,
`evidence[]`, `tags[]`, `relatedMemoryIds[]`, `relatedArtifactIds[]`, `status`, `updatedAt`,
`lastAccessedAt`. Note the FE `MemoryFrame` does NOT match what `/api/memory/frames` returns
(server returns the raw DB row shape + `_mind`, normalized via `normalizeFrame`,
`memory.ts:230`) — a real FE/BE contract mismatch to reconcile.
### §15.5 Agents — `AgentDef` (`packages/shared/src/types.ts:36-47`)
Has: `id, userId, teamId, name, role, systemPrompt, model, tools, config, createdAt`.
MISSING vs PRD §15.5: `type(AgentType)`, `goal`, `description`, `personaId`, `autonomyLevel`,
`workspaceIds`, `memoryScopes`, `skillIds`, `connectorIds`, `mcpIds`, `permissions`, `status`,
`lastRunAt`, `successRate`. (`successRate` partially exists on `procedures.success_rate`
`schema.ts:147` and per-trace outcome in `execution_traces` `schema.ts:206` — derivable.)
FE also has a thin `Persona` (`types.ts:256-272`) and `AgentStatus` (`:249-254`) but no
full Agent entity.
### §15.6 Artifacts — **NO backing entity anywhere**
- No `Artifact` type in `apps/web/src/lib/types.ts` (closest is `FileEntry` `:42-50`:
`name/path/type/size/mimeType/modifiedAt/createdAt` — a raw filesystem entry, not an outcome
object with relations).
- No artifacts table in `schema.ts`. No `/api/artifacts*` routes (PRD §16.6 is entirely net-new).
- ALL of PRD §15.6 (`kind, status, previewUrl, relatedMemoryIds, relatedSessionIds,
relatedTaskIds, relatedAgentIds`, etc.) is greenfield. This is the single largest entity gap.
---
## Cross-cutting: API contract delta (PRD §16 vs live routes)
Grounded against `packages/server/src/local/routes/*`:
- **Exists, reusable:** `GET /api/workspaces` (`workspaces.ts:101`), `POST /api/workspaces`
(`:135`), `GET /api/workspaces/:id/context` (`:311`); `/api/memory/frames` GET/POST/PATCH/DELETE
(`memory.ts:188,237,448,551`), `/api/memory/search` (`:120`), `/api/memory/stats` (`:391`);
`/api/harvest/preview|commit|sources` (`harvest.ts:221,243,538`); marketplace + connectors +
personas + compliance + fleet + workflows routes.
- **PRD §16 endpoints that DO NOT EXIST (net-new):** `/api/home/briefing`, `/api/quick-capture`,
`/api/home/overnight` (§16.1); `/api/workspaces/:id/state`, `/api/workspaces/:id/activity`
(§16.2 — only `/context` exists); `/api/command/*` (§16.3); the PRD's `/api/memory` (current is
`/api/memory/frames`), `/api/memory/merge`, `/api/memory/graph`, `/api/memory/:id/archive`
(§16.4); ALL `/api/artifacts/*` (§16.6); `/api/agents/*` CRUD+run (§16.7); most `/api/skills/*`
and `/api/automations/*`; and the missing **install-audit read route** for Extend governance (§d).
These are the full-stack hooks the plan must scope (locked SCOPE: net-new + extended backend APIs).

197
docs/ux-refactor/_phase1-contract.md Normal file
View File

@@ -0,0 +1,197 @@
# UX-Refactor Phase 1 — Shared CONTRACT (binding)
> Authored by the Phase-1 contract agent (the ONLY agent that edits
> `packages/shared/src/types.ts` + `apps/web/src/lib/adapter.ts` +
> `apps/web/src/lib/types.ts` this run). Leaf builders (S01/S02/S03 FE + the
> sidecar route leaves) and the integrator MUST align to the names + shapes below.
>
> Grounded in: `shared-types-delta.md §9`, `backend-api-delta.md` Phase-1 group,
> gap cards `S01 §6`, `S02 §6`, `S03 §6`. Mockups are directional; PRD acceptance wins.
>
> **Verification:** `npx tsc --build packages/shared` → exit 0;
> `npx tsc --noEmit --project apps/web/tsconfig.json` → exit 0 (adapter + FE types
> resolve against the rebuilt shared dist). The `/api/*` routes do NOT exist yet —
> the adapter methods compile as fetch wrappers; the route leaves build the servers.
---
## 1. New shared types — `packages/shared/src/types.ts`
Added as a `// === UX-Refactor Command vocabulary (PRD §12.3 / shared-types-delta §9) ===`
block. Exported via the barrel (`packages/shared/src/index.ts` `export * from './types.js'`),
so `import { … } from '@waggle/shared'` resolves them. **String-literal unions, all exported.**
> Phase-0 already shipped the §15.2 unions (`WorkspaceType`, `Scope`, `Confidence`,
> `MemoryKind`, `ArtifactKind`, `AgentType`, `AutonomyLevel`, `ExtensionType`) and
> `WorkspaceConfigV2` in this same file. This run adds ONLY the Command vocabulary.
```ts
export type CommandCategory =
| 'search' | 'launch' | 'create' | 'run' | 'navigate' | 'extend';
export type CommandResultType =
| 'workspace' | 'memory' | 'artifact' | 'session' | 'person'
| 'agent' | 'skill' | 'command' | 'connector' | 'mcp' | 'automation';
export interface CommandAction {
route?: string;
endpoint?: string;
payload?: Record<string, unknown>;
}
export interface CommandResult {
id: string;
type: CommandResultType;
title: string;
subtitle?: string;
category: CommandCategory;
icon?: string;
requiresApproval?: boolean; // §12.3 permission-gated → approval prompt
action?: CommandAction;
}
export interface Command { // execute request body
id?: string; // structured command resolves via id
input?: string; // OR natural-language command string
category?: CommandCategory;
type?: CommandResultType;
workspaceId?: string;
payload?: Record<string, unknown>;
}
```
> **Field-name note (binding):** `shared-types-delta §9` is the source of truth, so
> `CommandResult` uses `category: CommandCategory` + `type: CommandResultType`.
> Gap card S03 §6 sketched alternate field names (`kind`/`objectType`) — those are
> SUPERSEDED. Leaves must use `category`/`type`. S03's local `SearchResult`
> interface (`GlobalSearch.tsx:17-25`) is replaced by this shared `CommandResult`.
---
## 2. New FE view-model types — `apps/web/src/lib/types.ts`
Added in a `// ── UX-Refactor Phase 1 view-models ──` block. The top of the file
now re-exports the shared Command vocabulary so palette FE can import the whole
contract from `lib/types`:
```ts
import type {
WorkspaceType, CommandCategory, CommandResultType, CommandResult, CommandAction,
} from '@waggle/shared';
export type { CommandCategory, CommandResultType, CommandResult, CommandAction };
```
### S01 — Home Cockpit
```ts
export interface RecentWorkspaceCard {
id: string; name: string; group: string;
summary?: string; lastActive: string;
pendingCount: number; continueSessionId?: string;
}
export interface SuggestedAction {
label: string; workspaceId: string; sessionId?: string; kind: string;
}
export interface UpNextItem {
id: string; label: string; workspaceId?: string; at?: string;
kind: 'event' | 'task' | 'schedule';
}
export interface HomeBriefing {
greeting: string; userName?: string; date: string;
recentWorkspaces: RecentWorkspaceCard[];
suggestedActions: SuggestedAction[];
upNext: UpNextItem[];
activeModels?: string[];
isFirstRun: boolean;
/** P2 amendment — J08 (D6): personal-mind memories with status 'unreviewed'.
* The FE types this optional for back-compat with pre-P2 sidecars. */
needsReviewCount: number;
}
export interface OvernightFailure {
id: string; label: string; automationId?: string; error: string; at: string;
}
export interface OvernightSummary {
consolidated: number; artifactsCreated: number; automationsCompleted: number;
failures: OvernightFailure[];
window?: { from: string; to: string };
}
export interface QuickCaptureInput {
kind: 'note' | 'task' | 'link' | 'file'; content: string; workspaceId?: string;
}
```
### S02 — Workspace Desktop
```ts
export interface WorkspaceStateItem {
id: string; content: string; date?: string;
freshness?: 'fresh' | 'aging' | 'stale';
}
export interface WorkspaceStateView { // FE mirror of server WorkspaceState
active: WorkspaceStateItem[];
openQuestions: WorkspaceStateItem[];
pending: WorkspaceStateItem[]; // pending + blocked seed the Tasks tab
blocked: WorkspaceStateItem[];
completed: WorkspaceStateItem[];
stale: WorkspaceStateItem[];
recentDecisions: WorkspaceStateItem[];
nextActions: SuggestedAction[];
}
export interface WorkspaceActivityEvent {
id: string | number; ts: string; type: string; actor?: string; summary: string;
}
```
> The FE `Workspace` interface already carries the Phase-0 optional V2 fields
> (`type`, `status`, `description`, `agentIds`, `connectorIds`, `mcpIds`,
> `updatedAt`) — leaves consume those; do not re-add them.
---
## 3. New adapter methods — `apps/web/src/lib/adapter.ts`
Pattern matched to existing siblings: thin `await this.fetch(path[, init])` →
`res.json()`. Base URL + bearer-token + 403-tier handling all come from the
shared `this.fetch()` wrapper. All exposed on the `LocalAdapter` instance
exported as `adapter` (and the default export). Routes are net-new (do not exist
yet) — these compile and run as fetch wrappers; calls will 404 until the route
leaves land.
| Method (signature) | HTTP | Endpoint | Screen |
|---|---|---|---|
| `getHomeBriefing(): Promise<HomeBriefing>` | GET | `/api/home/briefing` | S01 |
| `getHomeOvernight(since?: string): Promise<OvernightSummary>` | GET | `/api/home/overnight[?since=<iso>]` | S01 |
| `quickCapture(input: QuickCaptureInput): Promise<{ frameId: string }>` | POST | `/api/quick-capture` | S01 |
| `getWorkspaceState(id: string): Promise<WorkspaceStateView>` | GET | `/api/workspaces/:id/state` | S01, S02 |
| `getWorkspaceActivity(id: string, limit = 50): Promise<{ events: WorkspaceActivityEvent[] }>` | GET | `/api/workspaces/:id/activity?limit=` | S02 |
| `commandSearch(q: string, scope?: string): Promise<{ results: CommandResult[] }>` | GET | `/api/command/search?q=[&scope=]` | S00, S03 |
| `commandRecent(): Promise<{ recent: CommandResult[] }>` | GET | `/api/command/recent` | S03 |
| `commandSuggestions(): Promise<{ suggestions: CommandResult[] }>` | GET | `/api/command/suggestions` | S03 |
| `commandExecute(payload: Command): Promise<{ ok: boolean; result?: unknown }>` | POST | `/api/command/execute` | S00, S03 |
### Binding notes for the route + FE leaves
- **Response envelopes are exact.** `commandSearch` returns `{ results: CommandResult[] }`,
`commandRecent` returns `{ recent: CommandResult[] }`, `commandSuggestions` returns
`{ suggestions: CommandResult[] }` (distinct keys — do not collapse). `getWorkspaceActivity`
returns `{ events: [...] }`. `getHomeBriefing` / `getHomeOvernight` / `getWorkspaceState`
return the bare object (no envelope).
- **B4 (founder-ratified):** `commandExecute` posts to the **singular** `/api/command/execute`,
which the route leaf ALIASES onto the existing handler. The existing plural
`/api/commands/execute` (`adapter.executeCommand`) is NOT renamed and stays as-is.
- **C9:** the Command Center permission prompt (`CommandResult.requiresApproval`) reuses the
chat approvals pipeline (`useChat().pendingApproval` / `ApprovalRequest`), not a new mechanism.
- **C5/C7 do not change this contract** but constrain consumers: Overview chat is a read-only
preview deep-linking to the Chat tab; Tasks tab seeds from `WorkspaceStateView.pending` +
`.blocked`.
- **Artifact/agent facets** in `CommandResultType` are intentionally present-but-gated — S05/S09
substrate is not built yet; command search ships with the available facets only.
---
## 4. Files touched this run (scope lock)
- `packages/shared/src/types.ts` — added Command vocabulary block.
- `apps/web/src/lib/types.ts` — added Phase-1 FE view-models + shared re-export.
- `apps/web/src/lib/adapter.ts` — added 9 Phase-1 methods + 2 import lines.
- `docs/ux-refactor/_phase1-contract.md` — this note.
NOT touched (by contract): `Desktop.tsx`, `lib/dock-tiers.ts`, any `index.ts` route
registrar, any `routes/*.ts`, any component. Those belong to the leaf builders.

290
docs/ux-refactor/appshell-conversion-plan.md Normal file
View File

@@ -0,0 +1,290 @@
# 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)*

383
docs/ux-refactor/deltas/backend-api-delta.md Normal file
View File

@@ -0,0 +1,383 @@
# Backend API Delta — Waggle OS UX Refactor (Master List)
> **Purpose.** The single, consolidated, de-duplicated, **ordered** master list of every backend
> endpoint the UX refactor must build or extend, plus every `.mind`/relational schema migration
> required. This is the build contract for the LOCKED execution model: **in-place incremental
> refactor** of `apps/web` + targeted **local Fastify sidecar** extensions. Every endpoint is built
> over the existing substrate — no new database, minimal-to-zero SQLite migration (see §M).
>
> **Sources (all read & grounded):** PRD §16 (`docs/.../Waggle_OS_UX_Refactor_PRD.md:1060-1158`),
> PRD §8/§21 phase+sprint structure (`:212-253`, `:1304-1374`), PRD §15 data model (`:918-1057`);
> the 22 gap cards (`docs/ux-refactor/gap-cards/S00–S21`); the route/substrate inventories
> (`docs/ux-refactor/_inventory/{backend-routes,substrate-types,frontend}.md`); the audited
> backend-map (`docs/backend-map/sections/03a–03g`); and spot-verified live source under
> `packages/server/src/local/routes/*.ts`, `packages/server/src/local/workspace-state.ts`,
> `packages/hive-mind-core/src/{workspace-manager,mind/schema,mind/db}.ts`,
> `packages/core/src/{install-audit,cron-store}.ts`.
>
> **Scope.** Everything is the **Local Sidecar** (`packages/server/src/local/index.ts` →
> `buildLocalServer()`, loopback `:3333`, flat `/api/*`, Bearer session-token). The desktop frontend
> talks ONLY to this server. The Clerk-gated **Cloud** server (`packages/server/src/routes/*.ts`) is
> out of scope — where its routes collide with PRD paths (notably `/api/agents/*`) the sidecar work is
> still **net-new locally** and flagged.
---
## How to read this
Each row carries:
- **Method + Path** — the PRD/refactor contract path (PRD-literal where §16 names it).
- **Disposition** — `NET-NEW` (no route serves this; build it) · `EXTEND` (a real handler exists;
add alias/param/field/behavior) · `NET-NEW (thin dispatcher/alias)` (new path, delegates wholly to
existing handlers, no new logic).
- **Build target** — the exact route file to create or the existing file/handler/builder to extend
(with line where load-bearing). **Verified absent:** `agents.ts`, `artifacts.ts`, `home.ts`,
`command.ts`, `mcps.ts`, `automations.ts`, `quick-capture.ts` do **not** exist under
`packages/server/src/local/routes/` (grep-confirmed) — all are net-new files.
- **Substrate** — the store(s) it reads/writes.
- **Shape** — a 3–5 line request/response sketch.
- **Screens** — gap-card IDs that consume it.
Counts are in §Counts at the bottom. **De-dup note:** §16 lists 65 endpoints but several are consumed
by multiple screens (e.g. `/api/workspaces/:id/state` → S01+S02; `/api/skills/*` → S06+S19;
`/api/agents/*` → S09+S18; the cron→automations aliases → S11+S20; connector/MCP → S07+S08+S14+S17;
harvest → S15+S16). This master list states each endpoint **once**, attributing all consuming screens.
Endpoints that **EXIST as-is** with zero backend work (e.g. `GET /api/workspaces`, `GET /api/connectors`,
`GET /api/memory/graph`, the team CRUD core, the harvest engine) are **excluded** — they need only FE
wiring. Only NET-NEW + EXTEND backend work is listed.
---
## Phase 0 — Architecture alignment (PRD §8 Phase 0 / §21 Sprint 1)
No new endpoints. Backend-relevant work is **type alignment + shared additive fields** that later
phases write through. Land these first because Phase 1–5 write paths depend on them.
| Item | Disposition | Build target | Substrate | Notes / shape |
|---|---|---|---|---|
| `WorkspaceConfig` V2 additive fields | EXTEND (no route, no migration) | `packages/hive-mind-core/src/workspace-manager.ts:5-58` (interface) + `CreateWorkspaceOptions :60-95` | `workspace.json` (file, NOT SQLite) | Add optional `description, type(WorkspaceType), status('active'\|'paused'\|'archived'), agentIds[], connectorIds[], mcpIds[], updatedAt, lastActiveAt`. Default `status:'active'`; derive `type` from `templateId`/`group` for existing workspaces. **No DB migration** (JSON file). Consumed by S02/S17. |
| Stamp `updatedAt` on write | EXTEND | `workspace-manager.ts:222` (`update()` currently stamps nothing but `riskClassifiedAt`) | `workspace.json` | One-line write-side touch. |
| Stamp `lastActiveAt` | EXTEND | agent loop / chat route write-back | `workspace.json` | Currently `lastActive` is DERIVED at read from session mtimes (`workspace-context.ts:375-387`); persist it. |
| Shared frontend type unions | EXTEND (FE only) | `apps/web/src/lib/types.ts` | — | Add `WorkspaceType, Scope, Confidence, MemoryKind, ArtifactKind, AgentType, AutonomyLevel, ExtensionType` (PRD §15.2). Reconcile FE `MemoryFrame`/`Workspace` lossy projections against API shapes (substrate-types §e). |
---
## Phase 1 — Core runtime: Home, Workspace Desktop, Command Center (PRD §8 Phase 1 / §21 Sprint 2–3)
### 1a. Home Cockpit + Quick Capture (S01) — new `home.ts` + extend `memory.ts`
| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
|---|---|---|---|---|---|
| `GET /api/home/briefing` | **NET-NEW** | new `routes/home.ts`; fans `buildWorkspaceState()` (`workspace-state.ts:234`) / `buildWorkspaceNowBlock()` (`workspace-context.ts:191`) over `WorkspaceManager.list()` and ranks | `memory_frames`, session JSONL, `awareness`, `cron_schedules`, `identity` (for name) | `→ { greeting, userName, date, workspaces:[{id,name,rank,summary,pending,nextActions}], suggestedActions[] }`. Cross-workspace ranking aggregator (per-workspace builder is the seed; no cross-WS ranker exists today). | S01 |
| `GET /api/home/overnight` | **NET-NEW** | new `routes/home.ts`; aggregates over since-last-login window | `events`/`ai_interactions`, `notifications`, `cron_execution_history`, `memory_frames` | `?since=<iso> → { memoriesAdded, artifactsCreated, automationsCompleted, failures:[{source,error}], window:{from,to} }`. No time-windowed delta exists today. | S01 |
| `POST /api/quick-capture` | **EXTEND** (thin handler delegating to memory write) | `routes/memory.ts` `POST /api/memory/frames` (`:248`) as the write primitive; new thin handler or alias | `memory_frames` (personal `.mind`) + `awareness` (for `kind:task`) + `POST /api/ingest` (for `kind:file`) | `{ kind:'note'\|'task'\|'link'\|'file', content, workspaceId? } → { frameId }`. Defaults to personal mind, stamps `source:'quick-capture'`; `task` also writes an awareness row so it surfaces in `nextActions`. **No migration.** | S01 |
### 1b. Workspace Desktop (S02) — extend `workspaces.ts`
| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
|---|---|---|---|---|---|
| `GET /api/workspaces/:id/state` | **EXTEND** (thin route) | new thin route in `workspaces.ts` returning the `buildWorkspaceState()` sub-object already computed inside `/context` (`workspaces.ts:311`) | `memory_frames` + session JSONL + `awareness` | `→ WorkspaceState { active, openQuestions, pending, blocked, completed, stale, recentDecisions, nextActions }` (`workspace-state.ts:38-55`). `pending`+`blocked` seed the Tasks tab. No migration. | S01, S02 |
| `GET /api/workspaces/:id/activity` | **EXTEND** (thin alias) | new thin route over `GET /api/events?workspaceId=` (`events.ts`) | `ai_interactions` / `execution_traces` / `audit_events` | `?limit= → { events:[{ts,type,actor,summary}] }`. Per-workspace audit feed. No migration. | S02 |
> **No backend work** for S02 Tasks (`tasks.ts` CRUD EXISTS), Members (`/api/team/members` EXISTS),
> or status-bar feeds (`/api/fleet`, `/api/cron`, `/api/capabilities/status` all EXIST — compose
> client-side; an aggregate `/status` route is optional and deferred). Artifacts tab is **S05's**
> scope; S02 ships an interim file-registry view via existing `GET /api/workspaces/:id/files`.
### 1c. Command Center (Ctrl+K) (S00, S03) — new `command.ts`
| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
|---|---|---|---|---|---|
| `GET /api/command/search?q=` | **NET-NEW** | new `routes/command.ts` federating route | reads `/api/memory/search` (`memory.ts:120`), `WorkspaceManager.list()`, `/api/skills`, `/api/workspaces/:id/sessions/search` (`sessions.ts`) — **no new store** | `?q=&scope= → { results:[CommandResult{id,kind:'search'\|'launch'\|'create'\|'run'\|'navigate'\|'extend', objectType, title, subtitle?, score, requiresApproval?, payload?}] }`. Federates over ~4 substrates. | S00, S03 |
| `POST /api/command/execute` | **EXTEND** | existing `POST /api/commands/execute` (note **plural**, `commands.ts`) — extend for navigate/create/run/extend dispatch, OR add a singular `/command/execute` alias | command runtime + dispatch targets | `{ command, objectType?, payload?, workspaceId? } → { ok, result? }`. Current runs slash-commands with a subset CommandContext; PRD's palette execute is broader. | S00, S03 |
| `GET /api/command/recent` | **NET-NEW** (or client-derive first) | new `routes/command.ts` reading `ai_interactions` (or derive from session/event history) | `ai_interactions` (read-only) | `→ { recent:[{command,ts,objectType}] }`. No schema change. Cheapest v1 = client-side from session history; promote to server when a consumer needs cross-device. | S03 |
| `GET /api/command/suggestions` | **NET-NEW** | new `routes/command.ts` reusing `deriveNextActions` (`workspace-state.ts:182-218`) + folding in `/api/skills/suggestions` | read-only over `memory_frames`/`awareness`/`cron` | `→ { suggestions:[CommandResult] }`. No migration. | S03 |
---
## Phase 2 — Work layer: Memory Center, Artifact Center, Workspace Creation, Onboarding (PRD §8 Phase 2 / §21 Sprint 4–5)
### 2a. Memory Center (S04, S16) — extend `memory.ts` + ONE optional migration
| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
|---|---|---|---|---|---|
| `GET /api/memory` | **EXTEND** (alias) | accept bare path on existing `GET /api/memory/frames` (`memory.ts:188`) | `memory_frames` | `?scope=&kind=&confidence=&status= → { frames:[...] }`. Alias only. | S04 |
| `GET /api/memory/:id` | **NET-NEW** (thin) | new thin read in `memory.ts` over `FrameStore.getById(id)` (no `GET .../frames/:id` exists today) | `memory_frames` | `→ { frame }`. Drawer detail. No migration. | S04 |
| `POST /api/memory` | **EXTEND** (alias) | alias on `POST /api/memory/frames` (`memory.ts:248`) | `memory_frames` | `{ kind,title,content,scope,tags? } → { id }`. | S04 |
| `PATCH /api/memory/:id` | **EXTEND** | extend `PUT /api/memory/frames/:id` (`memory.ts:448`) to accept `PATCH` + bare `:id` | `memory_frames` (`FrameStore.update`) | `{ content?, importance?, status?, tags? } → { ok }`. | S04 |
| `POST /api/memory/:id/archive` | **NET-NEW** (thin) | new thin route; model archive as `FrameStore.update(id, importance:'deprecated')` OR `status` in the new metadata column | `memory_frames` | `→ { ok }`. No hard delete. | S04 |
| `DELETE /api/memory/:id` | **EXTEND** (alias) | alias bare `:id` over `DELETE /api/memory/frames/:id` (`memory.ts:551`) | `memory_frames` (`FrameStore.delete`) | `→ { ok }`. | S04 |
| `POST /api/memory/merge` | **NET-NEW** | new route in `memory.ts`; real logic (read N frames, synthesize merged content, write one, archive/delete originals) — reuse `FrameStore` + `findDuplicate` dedup | `memory_frames` | `{ frameIds:[...], strategy?:'concat'\|'llm' } → { mergedId, archived:[...] }`. Net-new logic, low schema risk. | S04 |
| Harvest preview/commit confidence + selection | **EXTEND** | `POST /api/harvest/preview` (`harvest.ts:221`) → return ALL items (or paged) + per-item `confidence` + normalized `kind`; `POST /api/harvest/commit` (`harvest.ts:243`) → accept `{ selectedIds?:[] }` filter before the `createIFrame` loop (`:382-409`) | in-memory parse (preview) / `memory_frames` (commit) | Honors the trust-gate AC ("nothing imports without approval"). Preview confidence needs a classifier (LLM or heuristic). Preview-only confidence needs **no** migration. | S16 |
### 2b. Artifact Center (S05) — new `artifacts.ts` (largest net-new domain; aggregation only)
> **Single largest entity gap:** no `Artifact` type, table, or `/api/artifacts*` route exists anywhere
> (substrate-types §e). The backend is a **thin net-new aggregation/normalization layer** over three
> existing stores — **NO new data store**. A lightweight `artifacts.json` index holds title/status/
> tags/relations; the bytes stay in the existing file/document/storage stores.
| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
|---|---|---|---|---|---|
| `GET /api/artifacts` | **NET-NEW** | new `routes/artifacts.ts`; normalize 3 stores | `GET /api/workspaces/:id/files` (`workspaces.ts:594`), document versions (`documents.ts`), storage files (`workspaces.ts /storage/files`) + `artifacts.json` index | `?workspaceId=&kind=&status= → { artifacts:[Artifact{id,title,kind,workspaceId,status,mimeType,storagePath,tags,relatedMemoryIds,...}] }`. | S02, S05 |
| `POST /api/artifacts` | **NET-NEW** | `artifacts.ts`; delegates byte-write to `POST /api/ingest` / `files/upload` / `documents` | file/document stores + `artifacts.json` | `{ title,kind,workspaceId,content?/file? } → { id }`. | S05 |
| `GET /api/artifacts/:id` | **NET-NEW** | `artifacts.ts`; resolve composite id → normalized Artifact + relations + preview meta | 3 stores + `documents.ts` versions | `→ { artifact, relatedVersions[], relatedMemoryIds[] }`. | S05 |
| `PATCH /api/artifacts/:id` | **NET-NEW** | `artifacts.ts`; update title/status/tags/relations in `artifacts.json` (move = re-point storagePath via `files/move`) | `artifacts.json` (+ `files/move`) | `{ title?, status?, tags?, relatedMemoryIds? } → { ok }`. | S05 |
| `DELETE /api/artifacts/:id` | **NET-NEW** (route) | `artifacts.ts`; remove index entry + optionally backing file via `files/delete`/`storage/delete` | `artifacts.json` + file stores | `?deleteBacking=bool → { ok }`. | S05 |
| `GET /api/artifacts/search-related?q=` | **NET-NEW** | `artifacts.ts`; lean on `memory_frames_fts` + wiki search internally | `memory_frames_fts`, sessions, tasks, fleet | `?q=&artifactId= → { related:[{type,id,title,score}] }`. | S05 |
### 2c. Workspace Creation (S17) — extend `workspaces.ts` write path
| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
|---|---|---|---|---|---|
| `POST /api/workspaces` (extend body) | **EXTEND** | `workspaces.ts:116-135` + `WorkspaceManager.create` (`workspace-manager.ts:60-95`) | `workspace.json` | Accept `description, type, status, skills[], agentIds[], connectorIds[], mcpIds[]` (the Phase-0 additive fields). **No DB migration.** | S17 |
| `GET /api/workspace-templates` (extend shape) | **EXTEND** (optional) | `workspace-templates.ts:33` | template store | Add `skills[]`/`mcps[]`/`type` to `WorkspaceTemplate` so a chosen template pre-populates all 4 suggestion panels. | S17 |
### 2d. Onboarding: First Launch, Who-Are-You, Tool Discovery, Memory Import (S12–S15)
| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
|---|---|---|---|---|---|
| `PUT /api/profile` (extend merge) | **EXTEND** | `profile.ts:167-228` allow-list (`:172-196`) + `UserProfile` (`:41-94`) + `DEFAULT_PROFILE` (`:96-135`) | `profile.json` (NOT SQLite) | Add `workType, teamSize, goals[]` to the merged-fields allow-list + interface. Already mirrors identity → memory P/I frame (`:201-224`). **No migration.** | S13 |
| `POST /api/harvest/sources/:id/sync` | **NET-NEW** (thin) | new thin route in `harvest.ts`; resolve registered source + re-run commit | `harvest_sources` + `memory_frames` | `→ { runId }`. Sync today = `POST /api/harvest/commit`. NOTE: current sources keyed by `:source` **name** (not `:id`) — keep name key or alias. No new substrate. | S15, S16 |
> **S12 First Launch + S14 Tool Discovery need ZERO net-new backend** — all source catalogs already
> have routes (`GET /api/connectors`, `GET /api/tools/detect`, `GET /api/offline/status`,
> `GET /api/workspaces`); selections persist client-side in `OnboardingState` (localStorage),
> optionally threaded via the extended `PUT /api/profile`. The full harvest engine
> (`preview/commit/sources/progress/scan-claude-code/runs/extract-identity` + `POST /api/ingest`)
> already EXISTS for S15 — only the `/sources/:id/sync` alias (above) and the S16 confidence/selection
> extension (Phase 2a) are new.
---
## Phase 3 — Intelligence layer: Agents, Skills, Automations (PRD §8 Phase 3 / §21 Sprint 6)
### 3a. Agent Center + Agent Builder (S09, S18) — new sidecar `agents.ts` + agent store
> **Naming collision:** `/api/agents/*` CRUD exists ONLY on the Clerk-gated **Cloud** server
> (`packages/server/src/routes/agents.ts`) — NOT the sidecar (confirmed absent). All of §16.7 is
> **net-new locally**: a new `packages/server/src/local/routes/agents.ts` registered in `local/index.ts`.
> **Persistence (recommended v1):** a `{dataDir}/agents.json` file store, mirroring the agent-groups
> JSON precedent (`agent-groups.ts:29`) — **no SQLite migration**. (Alternative: an `agents` table in
> `mind/schema.ts` with SCHEMA_VERSION bump — only if agents must be FTS/relation-queryable. See §M.)
| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
|---|---|---|---|---|---|
| `GET /api/agents` | **NET-NEW** | new `routes/agents.ts`; reads agent store; overlay live status from `/api/agents/active` + `/api/fleet` | `agents.json` (new) | `→ { agents:[Agent{id,name,type,goal,personaId,model,autonomyLevel,status,lastRunAt,successRate,...}] }`. May union saved agents + read-only personas for back-compat. | S09, S18 |
| `POST /api/agents` | **NET-NEW** | `agents.ts`; persist Agent (§15.5 fields); PRO-tier gate like `personas.ts:32` | `agents.json` + `install_audit` (if elevated tools/MCPs claimed) | `{ name,type,goal,model,personaId?,autonomyLevel,memoryScopes,skillIds,connectorIds,mcpIds,permissions } → { id }`. | S18 |
| `GET /api/agents/:id` | **NET-NEW** | `agents.ts` read over store | `agents.json` | `→ { agent }`. | S09, S18 |
| `PATCH /api/agents/:id` | **NET-NEW** | `agents.ts`; mirror `agent-groups.ts:74-90` PATCH shape | `agents.json` | `{ ...partial } → { ok }`. | S18 |
| `POST /api/agents/:id/run` | **EXTEND** | resolve agent → call real executor `POST /api/fleet/spawn` (`fleet.ts:66`, the only path that runs `runAgentLoop :185`). **Do NOT** use `agent-groups/:id/run` (stub `:105`). | fleet/orchestrator + `execution_traces` via `TraceRecorder` | `{ input?, workspaceId? } → { sessionId }`. Map agent persona/model/memoryScope/workspace onto spawn body. | S09, S18 |
| `POST /api/agents/:id/pause` | **EXTEND** | map agent→active session → `POST /api/fleet/:workspaceId/pause` (`fleet.ts:260`) | fleet | `→ { ok }`. | S09, S18 |
| `GET /api/agents/:id/traces` | **NET-NEW** (route over existing store) | new thin read over `execution_traces` (`mind/schema.ts:199`, written by `chat.ts`/`evolution.ts`, **no HTTP read today**), filtered by agent/session; fallback session timeline `sessions.ts` | `execution_traces` + `ai_interactions` | `?limit= → { traces:[{ts,step,tool,outcome,cost}] }`. | S09, S18 |
### 3b. Skills Hub + Skill Builder (S06, S19) — extend `skills.ts`
| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
|---|---|---|---|---|---|
| `PATCH /api/skills/:id` | **EXTEND** | add `PATCH` alias + `:id`↔`:name` over `PUT /api/skills/:name` (`skills.ts:506`) | `~/.waggle/skills/*.md` | `{ content? } → { ok }`. No new substrate. | S06, S19 |
| `POST /api/skills/:id/test` | **EXTEND** | add `:id` path variant routing to existing `POST /api/skills/test` (body-driven) | skill file + `parseSkillFrontmatter` | `{ testInput? } → { wouldInject, frontmatter }`. Sandbox/dry-run only; no execution. | S06, S19 |
| `POST /api/skills/:id/install` | **NET-NEW** (thin dispatcher) | new dispatcher over `POST /api/skills/starter-pack/:id`, `capability-packs/:id`, `marketplace/install` (keep `requireTier('PRO')` for marketplace-sourced) | `marketplace.db` + `MarketplaceInstaller` + `SecurityGate` + `install_audit` | `{ source:'starter'\|'pack'\|'marketplace' } → { installed }`. Resolves source + delegates. | S06 |
> Skill **create** is the existing structured `POST /api/skills/create` (`skills.ts:431` →
> `generateSkillMarkdown` + `redactSkillContent` + audit + hash) — the Builder's real target,
> **EXISTS**. Publish reuses `POST /api/marketplace/publish` (PRO). Optional later: extend
> `SkillFrontmatter` for structured inputs/outputs/memoryAccess (Builder Steps 3–4) — open question, not
> in §16.8. No `.mind` migration (skills are flat files; marketplace is `marketplace.db`).
### 3c. Automation Center + Automation Builder (S11, S20) — alias cron as automations
> **The capability is cron** (`cron.ts`, `/api/cron/*` — full CRUD + trigger + history). "Automations"
> = a rename/alias surface. **Zero MISSING, all PARTIAL.** Register a real `/api/automations/*` alias
> plugin (PRD vocabulary) OR point the new UI at `/api/cron`. Trigger/condition/actions ride in the
> existing `job_config TEXT` blob → **no `.mind` migration** for v1.
| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
|---|---|---|---|---|---|
| `GET /api/automations` | **EXTEND** (alias) | alias of `GET /api/cron` (`cron.ts:94`); reshape `toResponse` to expose `trigger/condition/actions/status` from `job_type`+`job_config` | `cron_schedules` | `→ { automations:[...] }`. | S11, S20 |
| `POST /api/automations` | **EXTEND** (alias) | alias of `POST /api/cron` (`cron.ts:67`); persist `trigger/condition/actions` into `job_config` (+ `cron_expr` for schedule triggers) | `cron_schedules` | `{ name,trigger,condition?,actions[],schedule? } → { id }`. | S11, S20 |
| `PATCH /api/automations/:id` | **EXTEND** (alias) | alias of `PATCH /api/cron/:id` (`cron.ts:124`) | `cron_schedules` | `{ ...partial } → { ok }`. **Note real bug:** FE `updateCronJob` calls `PUT /api/cron/:id` but only `PATCH` is registered (adapter.ts:836 vs cron.ts) — fix the adapter. | S11, S20 |
| `POST /api/automations/:id/run` | **EXTEND** (alias) | alias of `POST /api/cron/:id/trigger` (`cron.ts:174`; auto-enables + executes + notifies) | `cron_schedules` + executor (`index.ts:1379`) | `→ { runId }`. | S11, S20 |
| `POST /api/automations/:id/pause` | **NET-NEW** (thin) / EXTEND | add thin `/pause` route OR adapter calls `PATCH /api/cron/:id { enabled:false }` | `cron_schedules.enabled` + scheduler | `→ { ok }`. Add `/pause` for PRD contract. | S11, S20 |
| `GET /api/automations/:id/logs` | **EXTEND** (alias) | alias of `GET /api/cron/:id/history` (in `notifications.ts:202` → `cronStore.getExecutionHistory`) | `cron_execution_history` | `?limit= → { logs:[...] }`. | S11, S20 |
| `POST /api/automations/test` | **NET-NEW** | new dry-run route (PRD §12.10 "test before activate"); current `POST /api/cron/:id/trigger` really executes | cron executor (no-persist mode) | `{ trigger,actions[] } → { previewResult }`. No log/notify side-effects. | S20 |
---
## Phase 4 — Extend layer: Connectors, MCPs, Marketplace, Install Audit (PRD §8 Phase 4 / §21 Sprint 7)
### 4a. Connector Hub (S07, S14) — extend `connectors.ts`
| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
|---|---|---|---|---|---|
| `POST /api/connectors/:id/sync` | **NET-NEW** | new route in `connectors.ts` (`WaggleConnector` has `connect`/`healthCheck`/`execute` but **no `sync()`**) | vault sub-key `connector:<id>:lastSync` (or small store) + activity event + `install_audit` | `→ { lastSyncAt, ok }`. **Phased:** MVP = `healthCheck()` + stamp `lastSyncAt` + emit event; full data re-pull is a larger connector-SDK addition. No `.mind` migration. | S07 |
| `POST /api/connectors/:id/revoke` | **EXTEND** (alias) | alias to `POST /api/connectors/:id/disconnect` (`connectors.ts:107`) + write `install_audit` `action:'rejected'`/revoke | vault + `install_audit` | `→ { ok }`. Same intent, PRD verb. | S07 |
| `POST /api/connectors/:id/connect` (extend) | **EXTEND** | `connectors.ts:55` — add `auditStore.record(...)` on success | vault + `install_audit` | (audit-trail enrichment, no shape change). | S07, S14 |
| `GET /api/connectors` (extend payload) | **EXTEND** (optional) | `connectors.ts:6` — carry `category` (already on type, `types.ts:299`) + `lastSyncAt` so UI drops hardcoded CATEGORIES/sync-shim | connector registry | (payload enrichment). | S07, S14 |
| `GET /api/connectors/health` (aggregate) | **NET-NEW** (optional, mockup) | `connectors.ts` — fan `healthCheck()` across connectors | connector registry | `→ { connectors:[{id,status,lastSyncAt}], systemHealth }`. Optional v1; compose client-side otherwise. | S07 |
| `GET /api/connectors/activity` | **NET-NEW** (or use shared `/api/extend/audit?type=connector`) | reads `install_audit` rows filtered to `type:'connector'` | `install_audit` | `→ { activity:[...] }`. **Prefer the shared `/api/extend/audit`** (4c) which serves S07+S08+S21 with one route. No migration. | S07 |
### 4b. MCP Hub (S08, S17) — new `mcps.ts` + persisted MCP-config store + runtime population
> **The deepest backend gap in the Extend layer.** Today `mcpRuntime` is **empty and never populated**
> (`local/index.ts:911`); there is no `GET /api/mcps`, no persisted MCP-config store, no boot-time
> population. All routes live in a new `packages/server/src/local/routes/mcps.ts`. **Substrate decision:**
> persist installed MCP configs as a JSON file / `.mcp.json` (no migration) — confirm dataDir path +
> multi-workspace scoping (open question). The MCP catalog is static in `@waggle/shared mcp-catalog.ts`.
| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
|---|---|---|---|---|---|
| `GET /api/mcps` | **NET-NEW** | `routes/mcps.ts`; join static catalog (`@waggle/shared mcp-catalog.ts`) + installed-state (`capabilities/status.mcpServers[]`, `.mcp.json`, `marketplace mcp-registry.ts`) | catalog + `.mcp.json` + `install_audit` | `→ { mcps:[{id,name,status,installed,tools[],scope}] }`. Reads existing substrate; no migration. | S08, S17 |
| `POST /api/mcps/install` | **EXTEND** | route through existing marketplace installer `POST /api/marketplace/install` (already handles `installType:'mcp'` → writes `.mcp.json`, `installer.ts:580`) | `marketplace.db` + `.mcp.json` + `install_audit` | `{ mcpId } → { installed }`. Resolve MCP id → marketplace package → install. Audit already recorded. | S08 |
| `POST /api/mcps/:id/test` | **NET-NEW** | `mcps.ts`; resolve server, `start()` if needed, assert `isHealthy()` (`mcp-runtime.ts:94,399`) and/or `tools/list` round-trip | `McpRuntime` | `→ { ok, tools[], error? }`. Open question: live spawn-and-handshake vs static manifest validation. | S08 |
| `POST /api/mcps/:id/revoke` | **NET-NEW** | `mcps.ts`; `mcpRuntime.removeServer(name)` (`mcp-runtime.ts:327`) + delete persisted config + `install_audit` `action:'revoked'` | `McpRuntime` + `.mcp.json` + `install_audit` | `→ { ok }`. | S08 |
| `POST /api/mcps` (add custom) | **NET-NEW** | `mcps.ts`; persist config + add to runtime (blueprint API line 530) | `.mcp.json` + `McpRuntime` | `{ name, command, args[], env{}, workspaceId? } → { id }`. | S08 |
| `POST /api/mcps/:id/start` · `POST /api/mcps/:id/stop` | **NET-NEW** | `mcps.ts`; map to `McpRuntime` start/stop (PRD §12.8 start/stop) | `McpRuntime` | `→ { status }`. | S08 |
| `PATCH /api/mcps/:id/permissions` | **NET-NEW** | `mcps.ts` (blueprint API line 530) | `.mcp.json` config | `{ scope?, permissions? } → { ok }`. | S08 |
| `GET /api/mcps/:id/logs` | **NET-NEW** (phased) | `mcps.ts`; needs a ring-buffer of stderr/stateChange in `McpServerInstance` (no log capture today) | new in-memory ring buffer | `→ { logs:[...] }`. Defer to later phase if log-capture infra not built. | S08 |
> **Boot-time runtime population** (populate `mcpRuntime` from the persisted config at startup,
> `local/index.ts:911`) is the foundational non-route work item that unblocks all of the above.
### 4c. Marketplace / Extend + Install Audit (S21, shared S06/S07/S08)
| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
|---|---|---|---|---|---|
| `GET /api/marketplace` | **EXTEND** (alias) | bare path = alias of `GET /api/marketplace/search` with default params (`marketplace.ts:56`) | `marketplace.db` | `→ { results:[...] }`. | S21 |
| `GET /api/extend/audit` (shared governance read) | **EXTEND** (param) | the install-audit read route `GET /api/audit/installs` **already EXISTS** (`skills.ts:685`); add `?capability=` / `?type=` filter exposing `getByCapability()` (`install-audit.ts:125`) | `install_audit` | `?type=skill\|connector\|mcp\|marketplace&limit= → { entries:[AuditEntry] }`. Serves S06+S07+S08+S21 with one route. No migration. **Note:** substrate-types §d#1 listed this as missing; it is present — the work is the filter param, not a new route. | S06, S07, S08, S21 |
> **No `POST /api/share`** here — that is Phase 5 (Team). Per-workspace install scoping (§12.13) is
> net-new product surface; PRD §22 risk register says "start with catalog + install audit, postpone
> billing/public marketplace" — **defer to Phase 4 polish**.
---
## Phase 5 — Team intelligence: Team Workspace, RBAC, Sharing, Audit (PRD §8 Phase 5 / §21 Sprint 8)
> Team CRUD core EXISTS in `team.ts` (`teams.db`): `GET/POST/PUT/DELETE /api/teams`, `/:id`,
> `/members`, `/members/:userId`, `/activity`. No `.mind` migration for the team core (`teams.db`
> standalone; `team_capability_policies`/`overrides`/`requests` exist in migration `0001`).
| Method + Path | Disposition | Build target | Substrate | Shape | Screens |
|---|---|---|---|---|---|
| `POST /api/teams/:id/invite` | **EXTEND** (alias) | thin `/invite` alias forwarding to `POST /api/teams/:id/members` (`team.ts:581`, owner/admin gated) | `team_members` (`teams.db`) | `{ email?, userId?, role? } → { ok }`. No new substrate. | S10 |
| `GET /api/teams/:id/audit` | **EXTEND** (alias) | alias `/audit` → existing `GET /api/teams/:id/activity` (`team.ts:690`, reads `audit_events` via `getAuditDb`) | `audit_events` | `→ { events:[...] }`. Or add audit-export shape. No new store. | S10 |
| `PATCH /api/teams/:id/members/:memberId` (fix gate) | **EXTEND** (bug fix) | `team.ts:642` (`:userId`==`:memberId`); **fix PUT(owner-only `:615`) vs PATCH(owner/admin `:642`) role-gate inconsistency** | `team_members` | (behavior fix, no shape change). | S10 |
| `POST /api/share` | **NET-NEW** | new route (no `/api/share` anywhere — grep-confirmed); shares memory/artifact with role-appropriate perms | `workspace.json teamId` linkage + (if frame-level) `memory_frames` metadata | `{ objectType:'memory'\|'artifact'\|'workspace', objectId, teamId, role } → { ok }`. **Open:** frame-level scope needs the `memory_frames` metadata migration (§M); v1 may scope implicitly via workspace `teamId`. Gate behind TEAMS tier like `/api/team/*`. | S05, S10 |
| `POST /api/artifacts/:id/share` | **NET-NEW** (blueprint) | maps to `POST /api/share` + artifact scope; gate TEAMS | `artifacts.json` + team scope | `{ teamId, role } → { ok }`. Blueprint action not in §16.6; defer to Phase 5. | S05 |
| `GET /api/teams/:id/governance` (optional) | **NET-NEW** (optional) | surface `team_capability_policies`/`overrides`/`requests` (migration `0001`); Enterprise proxy `GET /api/team/governance/permissions` (`team.ts:418`) is the remote analog | `team_capability_policies` etc. | `→ { policies[], overrides[], requests[] }`. RBAC UI. | S10 |
---
## §M — Schema migrations required
> **Headline: the entire refactor needs AT MOST ONE conditional SQLite migration**, and it is
> deferrable. Every other "schema addition" is to a **JSON file** (`workspace.json`, `profile.json`,
> `agents.json`, `artifacts.json`, `.mcp.json`) — **not** a database — so it is a pure additive
> TypeScript-interface change with **no migration**. The migration runner already does idempotent
> additive `ADD COLUMN` on `memory_frames` (precedent: it added `source`, `mind/db.ts:116-124`;
> pattern = `pragma_table_info` guard + `ALTER TABLE … ADD COLUMN`).
### M1 — `memory_frames.metadata` (CONDITIONAL — Phase 2/Phase 5) — the only `.mind` SQLite migration
- **What:** add one nullable column `metadata TEXT NOT NULL DEFAULT '{}'` to `memory_frames`
(`mind/schema.ts:47`). Store `{kind, title, scope, sourceId, sourceUrl, confidence, tags, evidence,
relatedMemoryIds, relatedArtifactIds, status}` as JSON (PRD §15.4 fields; PRD endorses metadata-first,
`:1013`).
- **Why conditional:** `memory_frames` is the **only** mind table without a JSON blob column (unlike
`awareness.metadata`, `knowledge_entities.properties`, etc.). Needed ONLY when persisted
confidence/provenance/scope/status becomes a real **query/filter axis** (S04 Memory Center filters;
S16 persisted-confidence review; S10/S05 frame-level `/api/share` scope). **NOT needed** if S16
review is preview-only (pre-commit) and S04 filtering is in-app over the existing columns.
- **Risk:** low — single additive nullable column; avoids touching the FTS/vec virtual tables and IPB
scoring. **Promotion path:** if `confidence` becomes a primary indexed filter, a later migration adds
`confidence REAL` as a real column (same ADD-COLUMN pattern).
- **Screens:** S04, S16, S10, S05. **Build target:** `packages/hive-mind-core/src/mind/db.ts` migration
block + `mind/schema.ts`.
### M2 — `install_audit` risk-level CHECK fix (RECOMMENDED — pre-Phase 4, latent bug)
- **What:** the TS `AuditRiskLevel` includes `'critical'` (`install-audit.ts:16`) but **both** DDL CHECK
constraints allow only `('low','medium','high')` (`install-audit.ts:65` AND `schema.ts:130` — duplicated
DDL that must stay in sync). A `record({riskLevel:'critical'})` throws a CHECK violation.
- **Why:** Phase 4 connector/MCP/skill installs all route through `auditStore.record(...)`. The
marketplace route currently side-steps by mapping CRITICAL→`riskLevel:'high'`+`approvalClass:'blocked'`
(`marketplace.ts:224-319`) — but any new Extend caller passing `'critical'` crashes.
- **Fix (pick one):** (a) widen both CHECK constraints to include `'critical'` (additive CHECK migration
— needs table rebuild for SQLite CHECK change, or relax to no-CHECK), OR (b) lock the CRITICAL→`'high'`
mapping as the permanent contract and drop `'critical'` from the TS union. (b) is zero-migration.
- **Risk:** low. **Screens:** S06, S07, S08, S21 (all Extend installs). **Build target:**
`install-audit.ts:65` + `mind/schema.ts:130` (kept in sync) OR the TS union.
### M3 — `agents` table (OPTIONAL — Phase 3, NOT recommended for v1)
- **What:** an `agents` table in `mind/schema.ts` with a `SCHEMA_VERSION` bump.
- **Recommendation: do NOT do this for v1.** Persist agents to `{dataDir}/agents.json` (file store,
mirrors the `agent-groups.json` precedent `agent-groups.ts:29`) — **no migration, reversible.** Only
add the table if agents must be FTS/relation-queryable. PRD §14.4 non-goal favors minimal backend.
- **Screens:** S09, S18.
### Non-migrations (additive JSON-file / interface changes only — listed for completeness, NOT migrations)
- `WorkspaceConfig` V2 fields → `workspace.json` (Phase 0; substrate-types §a).
- `UserProfile` `workType/teamSize/goals` → `profile.json` (S13).
- `Agent` entity → `agents.json` (Phase 3, M3 alt).
- `Artifact` index → `artifacts.json` (Phase 2b).
- MCP installed configs → `.mcp.json` (Phase 4b).
- Automation `trigger/condition/actions` → existing `job_config TEXT` blob (Phase 3c; no schema change).
- `cron_schedules`/`cron_execution_history`/`notifications` tables already exist with lazy creation
(`cron-store.ts:135-157`) — no migration for Automations.
---
## Counts
> Counted as **distinct backend endpoints** (each method+path = 1). Endpoints that **EXIST as-is** and
> need only frontend wiring are **excluded**. Phase-0 non-route work (V2 fields, FE type unions, write-
> side stamps) is counted separately under "interface/field extensions", not as endpoints.
- **Total endpoints requiring backend work: 53** (NET-NEW + EXTEND, de-duplicated).
- **NET-NEW endpoints: 35**
- Home ×2 (`/home/briefing`, `/home/overnight`)
- Command ×3 (`/command/search`, `/command/recent`, `/command/suggestions`)
- Memory ×3 (`/memory/:id`, `/memory/:id/archive`, `/memory/merge`)
- Artifacts ×6 (GET, POST, `/:id`, PATCH `/:id`, DELETE `/:id`, `/search-related`)
- Agents ×5 (GET, POST, `/:id`, PATCH `/:id`, `/:id/traces`)
- Skills ×1 (`/skills/:id/install`)
- Automations ×1 (`/automations/test`)
- Connectors ×3 (`/:id/sync`, `/connectors/health`, `/connectors/activity`)
- MCPs ×8 (`GET /mcps`, `/:id/test`, `/:id/revoke`, `POST /mcps` custom, `/:id/start`, `/:id/stop`, `PATCH /:id/permissions`, `/:id/logs`)
- Team ×3 (`POST /api/share`, `POST /artifacts/:id/share`, `GET /teams/:id/governance`)
- *(Several MCP/connector/team items are blueprint-implied beyond the §16 literal list; `/api/automations/:id/pause` is counted under EXTEND as a thin alias over the cron `enabled` flag.)*
- **EXTEND endpoints: 18** (distinct backend touch-points; an EXTEND may be an alias, an added param, or added behavior)
- `/quick-capture` (delegates to memory write)
- `/workspaces/:id/state`, `/workspaces/:id/activity` (thin routes over existing builders/events)
- `/command/execute` (broaden dispatch)
- `/memory` GET, `/memory` POST, `/memory/:id` PATCH, `/memory/:id` DELETE (aliases over `/memory/frames*`)
- `/harvest/preview` + `/harvest/commit` (confidence + `selectedIds` selection)
- `/harvest/sources/:id/sync` (thin re-commit alias)
- `/workspaces` POST (richer body)
- `/agents/:id/run`, `/agents/:id/pause` (delegate to fleet)
- `/skills/:id` PATCH, `/skills/:id/test` (`:id` variants)
- 6× `/automations/*` aliases over `/cron/*` (GET, POST, PATCH, run, pause, logs)
- `/connectors/:id/revoke`, `/connectors/:id/connect` (+audit), `/connectors` GET (payload)
- `/mcps/install` (via marketplace installer)
- `/marketplace` (bare-path alias)
- `/extend/audit` filter param (over existing `/audit/installs`)
- `/teams/:id/invite`, `/teams/:id/audit`, `/teams/:id/members/:memberId` (alias + role-gate fix)
- **Phase-0 interface/field extensions (NOT endpoints): 5** — `WorkspaceConfig` V2 fields + `updatedAt`/
`lastActiveAt` write-stamps (`workspace-manager.ts`), FE type unions (`types.ts`), `UserProfile`
`workType/teamSize/goals` (`profile.ts`), `WorkspaceTemplate` shape, `Connector` interface fields.
- **PRD §16 cross-reference (from `_inventory/backend-routes.md`):** of 65 §16-literal endpoints —
**16 EXIST** as-is (FE wiring only), **30 PARTIAL** (→ EXTEND), **19 MISSING** (→ NET-NEW). This
master list adds ~16 blueprint-implied endpoints (MCP start/stop/logs/permissions/custom, connector
health/activity, automations/test, team governance, artifact-share, extend/audit) beyond the §16
literal set.
- **Schema migrations:** **1 conditional** SQLite (M1 `memory_frames.metadata`) + **1 recommended**
CHECK fix (M2 `install_audit` risk-level) + **1 optional/deferred** (M3 `agents` table — recommend
NOT doing in v1). Net likely-to-ship: **1** (`memory_frames.metadata`); **0 strictly required** if
S16 confidence stays preview-only and `/api/share` scopes implicitly via workspace `teamId`.
- **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`); plus reuse of `.mcp.json`, `workspace.json`, `profile.json`.

272
docs/ux-refactor/deltas/coverage-check.md Normal file
View File

@@ -0,0 +1,272 @@
# Coverage Check — Waggle OS UX Refactor (Adversarial Completeness Audit)
> **Role:** Coverage Critic. This document is a skeptical, traceability audit of whether the
> UX-refactor analysis (22 gap cards `S00–S21` + 3 deltas) is **complete** against the PRD's three
> contract axes: **§12 screens (1–21)**, **§16 API endpoints (65)**, and **§26 Definition of Done (11)**.
> It also flags PRD surfaces that fall **outside** the §12 numbered-screen list (§9.2/§11 objects,
> §13 journeys, §17 RBAC, §10.4 Extend nodes) that no card owns.
>
> **Method:** every row is grounded in the PRD, the gap cards, `backend-api-delta.md`, and the
> source-grounded `_inventory/backend-routes.md` §16 cross-reference (which the delta draws from).
> "COVERED" = some card/delta explicitly owns the requirement with a build target. "GAP" = skipped,
> implicit-only, or owned by no artifact.
>
> **Sources read:** PRD `docs/Waggle_OS_UX_Refactor_Master_Handoff_Package/Waggle_OS_UX_Refactor_PRD.md`
> (§9, §10, §11, §12 lines 371–662, §13 lines 666–832, §14, §16 lines 1060–1158, §17, §19, §26 lines
> 1485–1500); all `docs/ux-refactor/gap-cards/S00–S21.md`; `docs/ux-refactor/deltas/{backend-api-delta,
> design-system-delta,shared-types-delta}.md`; `docs/ux-refactor/_inventory/{backend-routes,frontend,
> substrate-types}.md`.
---
## Table 1 — PRD Screens (the 21 numbered screens + AppShell)
The 21 numbered screens are the blueprint deck expansion of PRD §12.1–§12.13. AppShell (S00) is the
chrome the PRD §1 spine mounts inside (not a §12 screen, but required by §19.1 + §20.3). **Verdict: all
21 numbered screens + the shell are COVERED by a gap card.** No numbered screen is missing.
| # | PRD screen (§ ref) | Status | Gap card |
|---|---|---|---|
| — | AppShell / IA / Navigation (§1, §19.1, §20.3) | COVERED | **S00** appshell-ia |
| 1 | Home Cockpit (§12.1) | COVERED | **S01** home-cockpit |
| 2 | Workspace Desktop (§12.2) | COVERED (with sub-gaps, see notes) | **S02** workspace-desktop |
| 3 | Command Center (Ctrl+K) (§12.3) | COVERED | **S03** command-center |
| 4 | Memory Center (§12.4) | COVERED | **S04** memory-center |
| 5 | Artifact Center (§12.5) | COVERED | **S05** artifact-center |
| 6 | Skills Hub + Skill Builder (§12.6) | COVERED | **S06** skills-hub (+ **S19** skill-builder) |
| 7 | Connector Hub (§12.7) | COVERED | **S07** connector-hub |
| 8 | MCP Hub (§12.8) | COVERED | **S08** mcp-hub |
| 9 | Agent Center + Agent Builder (§12.9) | COVERED | **S09** agent-center (+ **S18** agent-builder) |
| 10 | Automation Center + Builder (§12.10) | COVERED | **S11** automation-center (+ **S20** automation-builder) |
| 11 | Team Workspace (§12.11) | COVERED | **S10** team-workspace |
| 12 | Onboarding · First Launch (§12.12 step 1) | COVERED | **S12** first-launch |
| 13 | Onboarding · Who Are You (§12.12 step 2) | COVERED | **S13** who-are-you |
| 14 | Onboarding · Tool Discovery (§12.12 step 3) | COVERED | **S14** tool-discovery |
| 15 | Onboarding · Memory Import (§12.12 step 4) | COVERED | **S15** memory-import |
| 16 | Onboarding · Memory Review (§12.12 step 5) | COVERED | **S16** memory-review |
| 17 | Onboarding · Workspace Creation (§12.12 step 6) | COVERED | **S17** workspace-creation |
| 18 | Agent Builder (§12.9 stepper) | COVERED | **S18** agent-builder |
| 19 | Skill Builder (§12.6 stepper) | COVERED | **S19** skill-builder |
| 20 | Automation Builder (§12.10 stepper) | COVERED | **S20** automation-builder |
| 21 | Marketplace / Extend Waggle (§12.13) | COVERED | **S21** marketplace-extend |
**Note — Home Cockpit (§12.12 step 7 "Home Cockpit").** The 7th onboarding step is "land in Home
Cockpit," which is S01 (not a separate screen). Correctly folded. ✔
**Screen-level sub-gaps (not whole-screen misses, but skipped requirements inside a covered screen):**
- **G1 — Workspace Desktop tab parity (S02).** PRD §12.2 (line 426 + 436) names **8 tabs**: Overview,
Chat, Research/Notes, Artifacts, Memory, Tasks, Timeline, **Settings**. The S02 card's tab bar (line
20) lists **7** and omits a **Settings** tab; the card later maps "Settings → existing component" (line
86) but never lists Settings in the §12.2 tab enumeration it reproduces. Minor, but the per-workspace
Settings tab (needed by Journey 19 "Archive workspace" → "opens workspace settings") should be an
explicit S02 tab, not implied.
- **G2 — Sessions as a first-class navigable object.** PRD §9.2 + §11 glossary list **Session** as a
primary product object ("Should be navigable and related to memory/artifacts"). No gap card surfaces a
Sessions list/navigation view; S02 collapses sessions into the **Timeline** tab + Chat. The session
substrate is rich and unused at the screen level (`GET /api/workspaces/:id/sessions`,
`/sessions/search`, `/sessions/:id/timeline`, `/sessions/:id/export` all EXIST per
`_inventory/backend-routes.md:42–46`). Ctrl+K (S03) does federate session search, so sessions are
*findable* but not *browsable as an object class*. PRD §13 Journey 3 ("user reviews… sessions") and the
object hierarchy §9.2 imply a Sessions surface. **Decide:** explicit Sessions tab/sub-view in S02, or
document that Timeline+Ctrl+K is the intended session UX and amend the §11 "navigable" claim.
---
## Table 2 — PRD §16 Endpoints (all 65) — addressed in `backend-api-delta.md`?
`backend-api-delta.md` deliberately lists **only NET-NEW + EXTEND** backend work (49 of 65) and
**excludes the 16 EXISTS endpoints** (they need FE wiring only). For audit completeness, "addressed"
below = **either** carried in the delta's master table **or** explicitly enumerated as EXISTS-and-excluded
in the delta's de-dup note (lines 46–48) / counts cross-reference (line 372). Counts reconcile to the
`_inventory/backend-routes.md` §16 table (16 EXISTS / 30 PARTIAL / 19 MISSING = 65).
| §16 group | PRD endpoint | In delta? | Disposition / where |
|---|---|:--:|---|
| 16.1 Home | `GET /api/home/briefing` | YES | NET-NEW `home.ts` (delta 1a) |
| 16.1 | `POST /api/quick-capture` | YES | EXTEND → memory write (delta 1a) |
| 16.1 | `GET /api/home/overnight` | YES | NET-NEW `home.ts` (delta 1a) |
| 16.2 Workspaces | `GET /api/workspaces` | YES (EXISTS-excluded) | exists; FE wiring only (delta line 46) |
| 16.2 | `POST /api/workspaces` | YES | EXTEND richer body (delta 2c) |
| 16.2 | `GET /api/workspaces/:id` | YES (EXISTS-excluded) | exists; FE wiring only |
| 16.2 | `PATCH /api/workspaces/:id` | YES (EXISTS-excluded) | exists (also PUT); FE wiring only |
| 16.2 | `GET /api/workspaces/:id/state` | YES | EXTEND thin route (delta 1b) |
| 16.2 | `GET /api/workspaces/:id/context` | YES (EXISTS-excluded) | exists; the Home/Workspace seed |
| 16.2 | `GET /api/workspaces/:id/activity` | YES | EXTEND thin alias (delta 1b) |
| 16.3 Command | `GET /api/command/search?q=` | YES | NET-NEW `command.ts` (delta 1c) |
| 16.3 | `POST /api/command/execute` | YES | EXTEND over `/commands/execute` (delta 1c) |
| 16.3 | `GET /api/command/recent` | YES | NET-NEW / client-derive (delta 1c) |
| 16.3 | `GET /api/command/suggestions` | YES | NET-NEW (delta 1c) |
| 16.4 Memory | `GET /api/memory` | YES | EXTEND alias (delta 2a) |
| 16.4 | `GET /api/memory/:id` | YES | NET-NEW thin read (delta 2a) |
| 16.4 | `POST /api/memory` | YES | EXTEND alias (delta 2a) |
| 16.4 | `PATCH /api/memory/:id` | YES | EXTEND (PATCH+bare id) (delta 2a) |
| 16.4 | `POST /api/memory/:id/archive` | YES | NET-NEW thin (delta 2a) |
| 16.4 | `DELETE /api/memory/:id` | YES | EXTEND alias (delta 2a) |
| 16.4 | `POST /api/memory/merge` | YES | NET-NEW (delta 2a) |
| 16.4 | `GET /api/memory/graph` | YES (EXISTS-excluded) | exists (`knowledge.ts`); FE wiring only (delta line 47) |
| 16.5 Harvest | `POST /api/harvest/preview` | YES | EXTEND (confidence+items) (delta 2a) |
| 16.5 | `POST /api/harvest/commit` | YES | EXTEND (`selectedIds`) (delta 2a) |
| 16.5 | `GET /api/harvest/sources` | YES (EXISTS-excluded) | exists; FE wiring only |
| 16.5 | `POST /api/harvest/sources/:id/sync` | YES | NET-NEW thin (delta 2d) |
| 16.6 Artifacts | `GET /api/artifacts` | YES | NET-NEW `artifacts.ts` (delta 2b) |
| 16.6 | `POST /api/artifacts` | YES | NET-NEW (delta 2b) |
| 16.6 | `GET /api/artifacts/:id` | YES | NET-NEW (delta 2b) |
| 16.6 | `PATCH /api/artifacts/:id` | YES | NET-NEW (delta 2b) |
| 16.6 | `DELETE /api/artifacts/:id` | YES | NET-NEW (delta 2b) |
| 16.6 | `GET /api/artifacts/search-related?q=` | YES | NET-NEW (delta 2b) |
| 16.7 Agents | `GET /api/agents` | YES | NET-NEW `agents.ts` (delta 3a) |
| 16.7 | `POST /api/agents` | YES | NET-NEW (delta 3a) |
| 16.7 | `GET /api/agents/:id` | YES | NET-NEW (delta 3a) |
| 16.7 | `PATCH /api/agents/:id` | YES | NET-NEW (delta 3a) |
| 16.7 | `POST /api/agents/:id/run` | YES | EXTEND → fleet/spawn (delta 3a) |
| 16.7 | `POST /api/agents/:id/pause` | YES | EXTEND → fleet pause (delta 3a) |
| 16.7 | `GET /api/agents/:id/traces` | YES | NET-NEW over `execution_traces` (delta 3a) |
| 16.8 Skills | `GET /api/skills` | YES (EXISTS-excluded) | exists; FE wiring only |
| 16.8 | `POST /api/skills` | YES (EXISTS-excluded) | exists (+ `/skills/create`); Builder target |
| 16.8 | `PATCH /api/skills/:id` | YES | EXTEND (PATCH+id alias) (delta 3b) |
| 16.8 | `POST /api/skills/:id/test` | YES | EXTEND (:id variant) (delta 3b) |
| 16.8 | `POST /api/skills/:id/install` | YES | NET-NEW dispatcher (delta 3b) |
| 16.9 Conn/MCP/Mkt | `GET /api/connectors` | YES | EXISTS + optional payload EXTEND (delta 4a) |
| 16.9 | `POST /api/connectors/:id/connect` | YES | EXISTS + audit EXTEND (delta 4a) |
| 16.9 | `POST /api/connectors/:id/sync` | YES | NET-NEW (delta 4a) |
| 16.9 | `POST /api/connectors/:id/revoke` | YES | EXTEND alias → disconnect (delta 4a) |
| 16.9 | `GET /api/mcps` | YES | NET-NEW `mcps.ts` (delta 4b) |
| 16.9 | `POST /api/mcps/install` | YES | EXTEND via marketplace installer (delta 4b) |
| 16.9 | `POST /api/mcps/:id/test` | YES | NET-NEW (delta 4b) |
| 16.9 | `POST /api/mcps/:id/revoke` | YES | NET-NEW (delta 4b) |
| 16.9 | `GET /api/marketplace` | YES | EXTEND bare-path alias (delta 4c) |
| 16.9 | `POST /api/marketplace/install` | YES (EXISTS-excluded) | exists (PRO, SecurityGate); FE wiring |
| 16.10 Automations | `GET /api/automations` | YES | EXTEND alias → cron (delta 3c) |
| 16.10 | `POST /api/automations` | YES | EXTEND alias → cron (delta 3c) |
| 16.10 | `PATCH /api/automations/:id` | YES | EXTEND alias (+ FE PUT/PATCH bug fix) (delta 3c) |
| 16.10 | `POST /api/automations/:id/run` | YES | EXTEND alias → cron trigger (delta 3c) |
| 16.10 | `POST /api/automations/:id/pause` | YES | NET-NEW thin / EXTEND (delta 3c) |
| 16.10 | `GET /api/automations/:id/logs` | YES | EXTEND alias → cron history (delta 3c) |
| 16.11 Team/RBAC | `GET /api/teams/:id` | YES (EXISTS-excluded) | exists; FE wiring only |
| 16.11 | `POST /api/teams/:id/invite` | YES | EXTEND alias → `/members` (delta 5) |
| 16.11 | `PATCH /api/teams/:id/members/:memberId` | YES | EXTEND (role-gate bug fix) (delta 5) |
| 16.11 | `GET /api/teams/:id/audit` | YES | EXTEND alias → `/activity` (delta 5) |
| 16.11 | `POST /api/share` | YES | NET-NEW (delta 5) |
**Verdict: 65/65 PRD §16 endpoints are addressed** — 49 with explicit build targets, 16 acknowledged as
EXISTS-and-excluded (FE-wiring-only). **No §16 endpoint is silently dropped.** The delta additionally
adds ~16 blueprint-implied endpoints beyond the §16 literal set (MCP start/stop/logs/permissions/custom,
connector health/activity, automations/test, team governance, artifact-share, extend/audit) — over-, not
under-, coverage.
**Audit caveats on Table 2 (skeptical reads — these are scope decisions hidden as "addressed"):**
- **C1 — `POST /api/connectors/:id/sync` is "phased to a stub" (delta 4a, line 214).** Marked NET-NEW but
the MVP is explicitly only `healthCheck()` + a `lastSyncAt` stamp; "full data re-pull is a larger
connector-SDK addition." So the headline §12.7 acceptance ("**whether data is flowing**") is met only
cosmetically in v1. This is the load-bearing S07 gap and the delta admits it does not truly close it.
- **C2 — `GET /api/mcps/:id/logs` deferred (delta 4b, line 238).** No log-capture infra exists; PRD §12.8
lists "view logs" as a functional requirement and §16 implies logs visibility. Deferred to "a later
phase." So MCP "auditable" (§12.8 acceptance) is partially unmet at the route level for v1.
- **C3 — `POST /api/mcps/:id/test` open question unresolved (delta 4b, line 233).** "live spawn-and-
handshake vs static manifest validation" is undecided. The endpoint is listed but its semantics are not.
- **C4 — Boot-time `mcpRuntime` population (delta 4b, line 240).** This is flagged as "the foundational
non-route work item that unblocks all of [MCP]" — but it is **not an endpoint and not phased into a
sprint**. It is the single biggest hidden-effort item in the Extend layer and should be an explicit
Phase-4 task, not a footnote.
---
## Table 3 — PRD §26 Definition of Done (all 11) — addressed by a phase/card?
**Headline finding (CRITICAL): no gap card or delta references the Definition of Done by name.** A
grep for "Definition of Done" / "DoD" across all 22 cards + 3 deltas returns **0 matches**. The DoD is
the PRD's release-acceptance contract; the analysis satisfies most items *implicitly* but ships **no
DoD→phase/card traceability artifact**. The next planner must not assume DoD is closed just because the
screens are covered. Per-item mapping below.
| # | DoD item (§26) | Status | Where addressed / GAP |
|---|---|---|---|
| 1 | Home Cockpit replaces blank-chat launch behavior | COVERED (implicit) | S01 builds Home Cockpit; but **no card/delta states the launch-default flip** (today launch = workspace/chat per `frontend.md`). The *behavioral replacement* (boot route → Home) is an **S00 AppShell routing change** that S00 does not explicitly own. **GAP-D1:** name the default-route change. |
| 2 | Workspace Desktop is default runtime for workspace work | COVERED | S02 (`create-new` tabbed runtime); S00 routes to it. |
| 3 | Ctrl+K can search/launch/create/run/navigate/extend | COVERED | S03 + S00 (global provider); `CommandResult.kind` enum covers all 6 verbs (S03 line 136). |
| 4 | Memory Center exposes source/confidence/evidence/scope/edit/delete | COVERED (1 conditional dep) | S04 + S16; ConfidenceBadge/EvidenceChip/EvidencePanel in design-delta; **depends on M1 `memory_frames.metadata` migration** if confidence/scope become real filter axes (delta §M1). If M1 is skipped, "confidence/scope" is in-app-only — verify against §12.4 AC. |
| 5 | Artifact Center supports outcome search + related objects | COVERED | S05 + `GET /api/artifacts/search-related` (delta 2b). |
| 6 | Onboarding leads profile→tool-discovery→import→review→first workspace | COVERED | S12–S17 chain; S00/onboarding shell. |
| 7 | Agents, skills, automations, connectors, MCPs, marketplace have coherent IA | COVERED | S06–S11, S18–S21 all map to the Work/Intelligence/Extend IA (S00 §IA). |
| 8 | Team workspace supports shared intelligence + roles | COVERED (RBAC UI partial) | S10; **but RBAC UI is an open question** — `GET /api/teams/:id/governance` is "optional/NET-NEW" (delta 5) and PRD §17 role matrix has **no dedicated card** (see GAP-D2). |
| 9 | Sensitive actions are approval-gated and audited | COVERED (cross-cutting, no owner card) | ApprovalModal in design-delta; S03/S08/S18/S19/S20 reference approval; `/extend/audit` (delta 4c). **GAP-D3:** the approval+audit *pattern* is cross-cutting but **owned by no single card** — risk of inconsistent per-screen implementation. |
| 10 | All screens have required states (§14) | PARTIAL — **the weakest-traced DoD item** | design-delta builds EmptyState/ErrorState/Skeleton/StatusBadge (the *primitives*), but **no card carries a per-screen §14 state matrix**. State-keyword density is uneven across cards (S02, S18, S20, S21 are thin; S00/S12 are rich). §14.1 mandates 9 global states (Loading/Empty/Populated/Error/Offline/Syncing/Permission-denied/Partial/Approval) on *every* major screen. **GAP-D4:** no screen×state coverage grid exists. |
| 11 | Claude Code can continue from PRD without product interpretation | COVERED (this artifact set is the evidence) | The 22 cards + 3 deltas + this check are the interpretation layer; this is met by the existence of the analysis itself, modulo the open questions below. |
---
## Concrete gaps to fix (prioritized)
**CRITICAL (close before the impl plan is "done"):**
1. **GAP-D4 — No screen × §14-state coverage matrix.** DoD #10 requires *every* major screen to
implement the 9 global states (§14.1) plus its screen-specific states (§14.2–§14.7). The design-delta
ships the state *primitives* but no artifact proves each of S01–S21 wires Loading/Empty/Error/Offline/
Permission-denied/Approval. Cards S02, S18, S20, S21 are visibly thin on state enumeration. **Fix:**
add a 21×9 state-coverage grid (per-screen) to the impl plan; it is the single most under-traced DoD
item.
2. **GAP-D3 — Approval-gating + audit is cross-cutting but owned by no card.** DoD #9 + PRD §17.3 +
§18.1. ApprovalModal (design-delta #7) and `/extend/audit` (delta 4c) exist, but no card defines the
canonical "which actions are sensitive, what the approval payload is, what gets audited" contract.
Risk: each builder (S18/S19/S20) and S03/S08 re-implements approval differently. **Fix:** a dedicated
cross-cutting "Approval & Audit" spec section (or an S00 sub-card) naming the gated-action taxonomy.
3. **C4 — MCP boot-time runtime population is a hidden foundational task, not a sprint item.** Without it
none of the MCP routes function. **Fix:** elevate `mcpRuntime` population (`local/index.ts:911`) to an
explicit Phase-4 task with its own estimate.
**HIGH:**
4. **GAP-D1 — The blank-chat→Home launch-default flip (DoD #1) is unowned.** S01 builds the screen; no
card changes the boot route. **Fix:** assign the default-route change to S00 explicitly.
5. **GAP-D2 — PRD §17 RBAC role matrix (Owner/Admin/Contributor/Viewer × 6 capabilities) has no
dedicated card.** S10 covers Team Workspace and mentions RBAC, but the role×permission enforcement UI
+ the `GET /api/teams/:id/governance` route are "optional." DoD #8 ("supports… roles") and §17.2 are
only partially traced. PRD §20.3 lists `RBAC/Audit components` under Create. **Fix:** confirm S10 owns
the §17.2 matrix UI, or add an RBAC/Audit card.
6. **G2 — Sessions has no first-class screen** despite being a §9.2/§11 primary object. Collapsed into
S02 Timeline + Ctrl+K search. **Fix:** either add an explicit Sessions sub-view to S02 or document that
Timeline+Ctrl+K is the intended UX and soften the §11 "navigable" claim.
7. **C1 — Connector `/sync` MVP is a cosmetic stub** that does not meet §12.7's "whether data is
flowing" acceptance. **Fix:** flag in the plan that S07's headline AC is only partially met in v1;
schedule the real connector-SDK data-pull.
**MEDIUM:**
8. **G1 — S02 omits the §12.2 Settings tab** from its tab enumeration (7 vs PRD's 8). Needed for
Journey 19 (Archive workspace). **Fix:** add Settings to the S02 tab list.
9. **C2 — MCP `/:id/logs` deferred** vs §12.8 "view logs" functional requirement. **Fix:** confirm
v1-acceptable, or schedule the stderr ring-buffer.
10. **C3 — MCP `/:id/test` semantics undecided** (live handshake vs static validation). **Fix:** resolve
the open question before S08 build.
11. **Journeys §13 (20 journeys) are not cross-referenced to cards.** The analysis is screen-oriented;
no artifact maps the 20 user journeys (esp. J15 agent-approval, J16 automation-failure→Home-attention,
J19 archive, J20 delete-memory) to the screens that must implement each step. Most are implicitly
covered, but **J16** (overnight failure surfacing in Home "attention required") spans S01+S11+S20 and
is not explicitly owned end-to-end. **Fix:** a journey→screen trace table.
**LOW / acknowledged-by-design (not true gaps, listed so they are not re-litigated):**
12. **Models / External-tools Extend nodes (§10.4)** have no standalone Hub card — folded into S21
(Models = marketplace category federated from Settings→Models; external_tool = `ExtensionType`).
S21 line 132 raises the `ExtensionType` reconciliation open question (agent vs external_tool). This is
a deliberate fold, not a miss — but the `ExtensionType` union must be resolved (shared-types-delta).
13. **§16 EXISTS endpoints (16) excluded from the delta** — correct by design (FE-wiring-only), and
acknowledged in the delta de-dup note. Not a gap.
14. **Schema migrations** — at most M1 ships; M2 (install_audit CHECK) is a real latent bug the delta
caught (good); M3 (agents table) correctly deferred. No gap.
---
## Bottom line
- **Screens:** 21/21 numbered screens + AppShell COVERED. 2 intra-screen sub-gaps (S02 Settings tab;
Sessions-as-object).
- **§16 endpoints:** 65/65 addressed (49 build targets + 16 EXISTS-excluded). Coverage is complete; 4
scope caveats (connector-sync stub, MCP logs/test/boot) are admitted-but-soft.
- **§26 DoD:** 11/11 items map to *some* artifact, but **DoD is never named** and **2 items are only
partially traced** (#10 states matrix, #9 approval/audit owner) plus #1 (launch-flip) and #8 (RBAC
matrix) have unowned slices. **The biggest completeness risk is not a missing screen — it is the
absence of two cross-cutting traceability grids (screen×state, journey×screen) and an explicit
approval/audit + RBAC owner.**

173
docs/ux-refactor/deltas/design-system-delta.md Normal file
View File

@@ -0,0 +1,173 @@
# Design System Delta — Waggle OS UX Refactor
**Scope:** PRD §19 (Design System Requirements) + Blueprint "Design System Direction"
mapped against the live Hive DS in `apps/web/src`.
**Execution model (locked):** in-place incremental refactor — reuse existing shadcn/Hive
primitives in `apps/web/src/components/ui/*`; build NEW DS components only where PRD §19.1
names a concept with no existing reusable primitive.
**Grounding sources (read):**
- Tokens: `apps/web/src/index.css` (canonical palette + light theme), `apps/web/src/waggle-theme.css` (aliases), `apps/web/tailwind.config.ts` (token→utility wiring).
- Primitive inventory: `apps/web/src/components/ui/*` (49 files).
- PRD §19.1/§19.2/§19.3 — `docs/.../Waggle_OS_UX_Refactor_PRD.md` lines 1222-1261.
- Blueprint "Design System Direction" — `_blueprint_extracted.txt` lines 479-492.
- Ad-hoc precedents: `MemoryApp.tsx` (provenance chip), `TimelineApp.tsx` (timeline), `OnboardingWizard.tsx` (ad-hoc steps), `ApprovalsApp.tsx` (approvals).
---
## (a) PRD §19.1 Component List — EXISTS vs BUILD-NEW
PRD §19.1 (lines 1226-1242) lists 19 core components. Blueprint adds a few named variants
(ContextCard, MemoryCard, ArtifactRow, AgentCard, SkillCard, ConnectorCard, MCPRow,
AutomationRunRow, EvidencePanel, ApprovalModal — `_blueprint_extracted.txt` lines 487-488).
Mapping below merges both lists.
| PRD §19.1 component | Status | Existing file / build location | Notes |
|---|---|---|---|
| **AppShell** | BUILD-NEW (composes EXISTS) | new `components/os/AppShell.tsx`; compose `ui/sidebar.tsx` + `ui/scroll-area.tsx` | No single AppShell today; current shell is `os/Desktop.tsx` (windowing). PRD §20.3 lists AppShell as Create. Reuse `ui/sidebar.tsx` for left nav. |
| **Primary navigation** | EXISTS (extend) | `ui/sidebar.tsx`, `ui/navigation-menu.tsx` | Full sidebar primitive present (collapsible, rail, groups). Re-label to Work/Intelligence/Extend/Team IA (PRD §3.2). |
| **Workspace switcher** | BUILD-NEW (compose EXISTS) | new; compose `ui/command.tsx` + `ui/dropdown-menu.tsx` | Pattern exists in `sidebar.tsx` docs; assemble against workspace list. |
| **Command Center modal** | EXISTS (primitive) → BUILD-NEW (Ctrl+K shell) | primitive `ui/command.tsx` (cmdk: CommandDialog/Input/Group/Item); new `CommandCenter.tsx` | `ui/command.tsx` is full cmdk wrapper. PRD §20.3 + Blueprint require a global Ctrl+K provider/overlay on top — build the provider, reuse the primitive. Existing `overlays/GlobalSearch.tsx` is a prior, narrower attempt to fold in. |
| **Card: workspace** (ContextCard/MemoryCard/AgentCard/SkillCard/ConnectorCard) | EXISTS (base) → BUILD-NEW (typed variants) | base `ui/card.tsx`; new per-object cards under `components/os/cards/` | `ui/card.tsx` is the generic shadcn card (Header/Title/Content/Footer). Build typed object cards on top (each renders StatusBadge + actions). `.direction-d-card` / `.waggle-card-lift` utilities (`waggle-theme.css`) give the hover/lift treatment. |
| **ArtifactRow / MCPRow / AutomationRunRow** (table rows) | EXISTS (base) | `ui/table.tsx` | Blueprint density rule (line 491): cards for Home/Workspace, **tables** for Memory/Artifacts/Agents/Automations. Use `ui/table.tsx`; build row cell formatters only. |
| **Status badges** | EXISTS (base) → BUILD-NEW (StatusBadge variant) | base `ui/badge.tsx`; new `components/os/StatusBadge.tsx` | `ui/badge.tsx` has only default/secondary/destructive/outline — **no semantic status variants** and no icon/dot. Build `StatusBadge` mapping the state enums (PRD §14: running/paused/failed/healthy/...) to the color semantics in (b), with a **non-color dot + text label** (a11y §19.3). |
| **Confidence badges** | **BUILD-NEW** | new `components/os/ConfidenceBadge.tsx` | No confidence component exists. `MemoryApp.tsx` has no confidence rendering today (grep: only `provenance`). Renders 0-100 (PRD §15.4) as tiered band (high/med/low) with numeric + label; band color from semantics in (b). |
| **Source / evidence chips** (EvidenceChip + EvidencePanel) | **BUILD-NEW** (chip has ad-hoc precedent) | new `components/os/EvidenceChip.tsx` + `components/os/EvidencePanel.tsx` | Closest precedent: the inline provenance pill in `MemoryApp.tsx` (lines ~202-208, `readFrameProvenanceTool`) — promote to a reusable `EvidenceChip`. `EvidencePanel` (Blueprint line 488) is the grouped detail (source + sourceUrl/path + snippet) inside DetailDrawer. |
| **Timeline** | **BUILD-NEW** (logic exists) | new `components/os/Timeline.tsx`; reuse `lib/timeline-events.ts` | `TimelineApp.tsx` + `lib/timeline-events.ts` (`iconForEvent`/`colorForEvent`/`describeEvent`) hold the rendering logic, but it is app-specific, not a reusable DS component. Extract the grouped-by-day list into `Timeline`. |
| **Activity feed** | **BUILD-NEW** | new `components/os/ActivityFeed.tsx` | No reusable feed today. Distinct from Timeline: feed = reverse-chron event stream for Workspace right-panel "last activity" (PRD §12.2) + Home overnight summary (§12.1). Can share the row renderer with Timeline. |
| **Detail drawer** (DetailDrawer) | EXISTS (two bases) → BUILD-NEW (typed wrapper) | bases `ui/sheet.tsx` (right-side, Radix Dialog) and `ui/drawer.tsx` (vaul, bottom); new `components/os/DetailDrawer.tsx` | **Recommend `ui/sheet.tsx` side="right"** as the base — matches Blueprint "optional right context rail" (line 483) and is the standard detail surface for Memory/Artifact/Agent. `ui/drawer.tsx` (vaul) is bottom-sheet, keep for mobile/secondary. Build one `DetailDrawer` wrapper that takes header + EvidencePanel + actions. |
| **Builder stepper** (BuilderStepper) | **BUILD-NEW** | new `components/ui/stepper.tsx` (or `components/os/BuilderStepper.tsx`) | **No Stepper primitive exists.** `OnboardingWizard.tsx` hand-rolls step state (`useState(state.step)` + `goToStep`) with no shared progress UI. PRD §19.2: "Create flows use stepper patterns" — needed by Skill/Agent/Automation builders (PRD §12.6/§12.9/§12.10) + Onboarding. Build once, retrofit onboarding. |
| **Approval prompt** (ApprovalModal) | EXISTS (base + app) → BUILD-NEW (typed modal) | base `ui/alert-dialog.tsx`; existing app `os/apps/ApprovalsApp.tsx` + `overlays/SpawnAgentDialog.tsx`; new `components/os/ApprovalModal.tsx` | `ui/alert-dialog.tsx` (Radix) is the confirm base; `ApprovalsApp.tsx` already implements an approvals inbox surface. Build a shared `ApprovalModal` (declares: actor, requested action, scope, risk badge, approve/deny/modify) for the permission-gated flows (PRD §12.3 command exec, §12.9 agent elevation, §17.3 elevated actions). |
| **Empty state** | **BUILD-NEW** | new `components/os/EmptyState.tsx` | No reusable empty-state component (grep found none). Required on every major screen (PRD §14.1, §22.2). Build icon + headline + body + primary CTA. |
| **Error state** | **BUILD-NEW** (base exists) | base `ui/alert.tsx`; new `components/os/ErrorState.tsx` | `ui/alert.tsx` (default/destructive) covers inline alerts; build a full-surface `ErrorState` (illustration + retry) for screen-level errors (PRD §14.1). |
| **Skeleton loader** | EXISTS | `ui/skeleton.tsx` | Present. Compose per-surface skeletons (card grid / table rows). |
| **Table/list/grid view toggle** | **BUILD-NEW** (base exists) | base `ui/toggle-group.tsx`; new `components/os/ViewToggle.tsx` | `ui/toggle-group.tsx` (Radix, single/multiple) is the base. No `ViewToggle` exists. Build a 3-state (table/list/grid) toggle for Memory/Artifact/Agent surfaces (PRD §19.1 last item, Blueprint density rule). |
### Supporting primitives confirmed present (reuse, do not rebuild)
`ui/tabs.tsx` (workspace tabs PRD §12.2), `ui/dialog.tsx`, `ui/popover.tsx`, `ui/tooltip.tsx` + `ui/hint-tooltip.tsx`, `ui/progress.tsx`, `ui/avatar.tsx` (team avatar stack), `ui/select.tsx`/`ui/checkbox.tsx`/`ui/radio-group.tsx`/`ui/switch.tsx`/`ui/slider.tsx` (builder form fields), `ui/form.tsx` (+ react-hook-form), `ui/chart.tsx` (dashboards/Home metrics), `ui/resizable.tsx` (workspace panels), `ui/scroll-area.tsx`, `ui/separator.tsx`, `ui/breadcrumb.tsx`, `ui/sonner.tsx`/`ui/toast.tsx`/`ui/toaster.tsx` (notifications), `ui/dropdown-menu.tsx`/`ui/context-menu.tsx`, `ui/collapsible.tsx`/`ui/accordion.tsx`.
### Summary counts
- **EXISTS (reuse as-is):** Primary nav (sidebar), Skeleton, Tabs, plus the full supporting-primitive set above.
- **EXISTS-as-base → BUILD typed wrapper:** Command Center, object Cards, Status badge, Detail drawer, Approval modal, Error state, View toggle (7).
- **BUILD-NEW (no reusable base):** ConfidenceBadge, EvidenceChip, EvidencePanel, BuilderStepper, ActivityFeed, Timeline (DS extraction), EmptyState, AppShell, ViewToggle base-toggle exists but component new (≈8 net-new components).
---
## (b) Color Semantics → Hive DS Token Mapping
PRD/Blueprint semantic palette (Blueprint lines 485-486): **blue = command/work, purple =
intelligence, green = healthy/complete, orange = attention/automation, red = risk/failure.**
The Hive DS already ships these as CSS vars in `index.css` and exposes them as Tailwind
utilities via `tailwind.config.ts` (`status.*`, `honey.*`, `hive.*`). **No new base tokens
are required** — only a semantic-alias layer so components reference intent, not raw color.
| UX semantic | Meaning | Existing Hive token (dark, `index.css`) | Tailwind utility | Light-theme value (`index.css` `[data-theme="light"]`) |
|---|---|---|---|---|
| **Blue = command / work** | running, info, in-progress, command surfaces | `--status-info: #60a5fa` | `text-status-info` / `bg-status-info` | `#1d4ed8` (AA on cream, ratio 6.30) |
| **Purple = intelligence** | agents, AI/skills, memory-AI | `--status-ai: #a78bfa` (= DS accent `--accent: 270 60% 68%`) | `text-status-ai` / `bg-status-ai`; `accent` for AI brand | `#6d28d9` (ratio 6.68) |
| **Green = healthy / complete** | success, connected, completed, high confidence | `--status-healthy: #34d399` | `text-status-healthy` / `bg-status-healthy` | `#047857` (ratio 5.16) |
| **Orange = attention / automation** | warning, attention-required, automation, **medium confidence** | `--status-warning: #fbbf24` (NOT honey-brand) | `text-status-warning` / `bg-status-warning` | `#b45309` (ratio 4.72) |
| **Red = risk / failure** | error, failed, high-risk, revoked, **low confidence** | `--status-error: #f87171` (= shadcn `--destructive: 0 72% 63%`) | `text-status-error` / `bg-status-error` / `destructive` | `#b91c1c` (ratio 6.09) |
**Critical disambiguation — orange ≠ brand honey.** The Hive **brand/primary is honey gold**
(`--primary: 40 100% 45%` → `--honey-500: #e5a000`), used for primary CTAs, focus rings,
selection, and brand accents (`--ring`, `.glow-primary`, `--shadow-honey`). The UX "orange =
attention/automation" semantic must map to **`--status-warning` (#fbbf24)**, a distinct amber,
NOT to honey/primary. Keep "attention" and "brand action" visually separable:
- Brand / primary action → `bg-primary` / `honey-*`.
- Attention / automation status → `bg-status-warning` / `text-status-warning`.
**Confidence band mapping (ConfidenceBadge, PRD §15.4 `confidence: 0-100`):**
- high (≥ ~70) → green `status-healthy`
- medium (~40-69) → orange `status-warning`
- low (< ~40) → red `status-error`
(Thresholds are DS defaults; finalize against the memory scoring scale in `packages/hive-mind-core/src/mind/scoring`.)
**Implementation note — add a semantic alias layer.** Today components would have to reach
for `status-info`/`status-ai` directly. Add intent aliases in `waggle-theme.css` (`:root`
already holds `--success/--warning/--error` at lines 44-46) so the new layer reads:
```
--sem-work: var(--status-info); /* blue */
--sem-intelligence:var(--status-ai); /* purple */
--sem-healthy: var(--status-healthy); /* green */
--sem-attention: var(--status-warning);/* orange */
--sem-risk: var(--status-error); /* red */
```
`StatusBadge`/`ConfidenceBadge`/cards reference `--sem-*` so the mapping lives in one place
and inherits both dark and light themes automatically.
---
## (c) Dark-default + Light-variant Note
- **Dark is the default** (Blueprint line 484: "Dark default for desktop agent feel").
`index.css :root` IS the dark theme (background `222 20% 4%`); no `data-theme` attr needed.
- **Light variant exists and is complete** — `:root[data-theme="light"]` (index.css lines
140-221) overrides background, hive scale (inverted), honey (contrast-adjusted), **and all
`--status-*` + `--kg-*` tokens darkened for WCAG AA on the cream surface** (ratios documented
in source: healthy 5.16, warning 4.72, error 6.09, info 6.30, ai 6.68). Light mode is
explicitly intended for "data-heavy Memory/Artifact tables" (Blueprint line 484).
- **Consequence for new components:** because the semantic mapping in (b) references
`--status-*` (which the light block already overrides), every new component
(StatusBadge, ConfidenceBadge, EvidenceChip, etc.) inherits AA-correct light colors **for
free** as long as it uses tokens — never hardcode hex. This matches the CLAUDE.md §10
closed item "CR-2 hive-950 → semantic tokens" (do not reintroduce raw `hive-950` refs).
- **Theme switch mechanism:** toggling `data-theme="light"` on `:root` (the desktop wallpaper
overlay + honeycomb-bg already branch on it, index.css lines 269/277). New surfaces must not
assume a fixed background.
---
## (d) Accessibility Requirements (PRD §19.3 + Blueprint line 489-490)
PRD §19.3 (lines 1254-1261) + Blueprint "Keyboard-first... no color-only status, text labels
for all badges." Per-component obligations for the new/extended DS components:
1. **Full keyboard support.** Ctrl+K (`CommandCenter`) opens from anywhere via global key
handler; builders, drawers, modals are fully tab-navigable. cmdk (`ui/command.tsx`) and
Radix bases (`alert-dialog`, `sheet`, `dialog`, `toggle-group`) provide focus trap +
arrow-key nav out of the box — preserve, don't override.
2. **Visible focus states.** Use the DS focus ring (`--shadow-focus` / `--ring` = honey).
shadcn primitives already render `focus:ring-2 focus:ring-ring`; new wrappers must keep it.
3. **ARIA labels for command palette + builders.** `CommandCenter` needs `role`/`aria-label`
on the dialog + labelled groups; `BuilderStepper` needs `aria-current="step"` on the active
step and accessible step names (extend from `OnboardingWizard.tsx` `STEP_NAMES`).
4. **Sufficient contrast for dark theme.** Dark `--status-*` are bright on `#08-11` surfaces;
light variants are pre-darkened to ≥4.5:1 (documented in index.css). Do not place
`status-warning`/`status-info` as small text on light surfaces without the light token.
5. **Non-color status indicators (CRITICAL).** `StatusBadge` and `ConfidenceBadge` MUST pair
color with a **text label AND/OR a shape/icon** (dot, icon glyph). PRD §19.3 + Blueprint
"no color-only status" + "text labels for all badges." This is the single biggest gap vs
the current `ui/badge.tsx` (color-only). Confidence must show the number/label, not just a
colored band.
6. **Screen-reader-friendly tables/lists.** Memory/Artifact/Agent/Automation tables
(`ui/table.tsx`) need proper `<th scope>`, caption, and row `aria-label`; `ViewToggle`
needs labelled options ("table view"/"grid view"). `Timeline`/`ActivityFeed` use an ordered
list semantic with per-item timestamps in accessible text.
7. **Approval flows announce intent.** `ApprovalModal` must expose the requested action, scope,
and risk level as text (not icon-only) so denial/approval is an informed, SR-readable
decision (ties to PRD §17.3 elevated-action approval).
---
## Net build list (for the impl plan)
**New DS components to author** (under `components/ui/` for generic, `components/os/` for product-typed):
1. `StatusBadge` (extend `badge.tsx` with semantic variants + non-color indicator)
2. `ConfidenceBadge`
3. `EvidenceChip` (promote from `MemoryApp.tsx` provenance pill)
4. `EvidencePanel`
5. `BuilderStepper` / `stepper.tsx`
6. `DetailDrawer` (wrap `sheet.tsx` right-side)
7. `ApprovalModal` (wrap `alert-dialog.tsx`)
8. `ActivityFeed`
9. `Timeline` (extract from `TimelineApp.tsx` + `lib/timeline-events.ts`)
10. `EmptyState`
11. `ErrorState` (wrap `alert.tsx`)
12. `ViewToggle` (wrap `toggle-group.tsx`)
13. `AppShell` + `WorkspaceSwitcher` + `CommandCenter` (compose existing sidebar/command primitives)
14. Object cards: `WorkspaceCard`/`MemoryCard`/`ArtifactRow`/`AgentCard`/`SkillCard`/`ConnectorCard`/`MCPRow`/`AutomationRunRow`
**Token work:** add `--sem-*` alias layer in `waggle-theme.css` (no new base palette tokens).
All bases for the above already exist in `ui/*`; nothing requires a new dependency.

701
docs/ux-refactor/deltas/open-questions.md Normal file
View File

@@ -0,0 +1,701 @@
# Open Questions — UX Refactor (Founder Ratification)
> Source: PRD §23 (`docs/Waggle_OS_UX_Refactor_Master_Handoff_Package/Waggle_OS_UX_Refactor_PRD.md:1414-1424`)
> + the §9 "Open questions" sections of all 22 gap cards (`docs/ux-refactor/gap-cards/S00..S21`).
> Every recommendation is kept consistent with the **locked direction**: in-place incremental refactor
> of `apps/web` + targeted backend extensions, **full-stack** (net-new/extended APIs where PRD §16 has no
> route yet), **local-first** default. Mockups are directional (PRD §24); PRD acceptance criteria win.
>
> **How to use:** each question has (a) why it matters, (b) options + tradeoffs, (c) a RECOMMENDED answer
> for founder ratification, (d) the phase it blocks if unresolved. Questions are grouped: **§A** = the 8
> PRD §23 questions; **§B** = cross-cutting decisions surfaced by the gap cards that block ≥2 screens;
> **§C** = screen-local questions that block a single screen. Critical (Phase 1–2 blocking) items are
> flagged **[BLOCKS P1]** / **[BLOCKS P2]**.
---
## ✅ Founder Ratifications — 2026-06-09
The **spine (Phase 0/1) blockers are RATIFIED as recommended** (founder, 2026-06-09). Phase 0 is
unblocked; these are now locked decisions alongside the execution-model + full-stack scope locks:
- **B1** Shell topology → in-place dock reframe; keep windowed `AppId` nav; group the dock into
Work / Intelligence / Extend / Team zones. **No react-router.**
- **A1** Workspace Desktop → fixed widget layout v1.
- **A2** Home Cockpit → personal-only v1 (team strip later, behind RBAC).
- **B4** `/api/*` → alias PRD vocabulary onto existing routes (command / automations / connector-revoke); do not rename.
- **B8** Identity → onboarding writes profile **and** seeds the `identity` table.
## ✅ Founder Ratifications — Phase 2 gate (2026-06-09 S2)
The **Phase-2 blockers are RATIFIED as recommended** (founder, 2026-06-09), except **C33** which is
**held for discussion** (see note below). Locked Phase-2 decisions:
- **A6** Artifact storage → per-workspace `artifacts.json` index over the existing StorageProvider;
artifact = explicit produced output (not every ingested input). No `.mind` migration.
- **A8** Memory retention → soft-status in `metadata` (Archive = reversible; Deprecate = existing
`importance`); **Delete = hard delete behind a scope-and-consequence confirmation** (PRD J20).
≤1 additive migration.
- **B2** Confidence → cheap heuristic at preview (source-trust × adapter-type × dedup), persisted in
`metadata` only if it becomes a queryable filter; LLM scoring reserved for the standing J08 queue.
- **B6** `MemoryKind` → PRD §15.2 canonical in `@waggle/shared`; pure harvest + display-category mapping
helpers. Drop FE `event`/`insight` drift.
- **A3** Memory graph tab → **ship in v1** (substrate already renders).
- **C33** Import↔Review commit split → **RESOLVED to the middle path** (founder, 2026-06-09 S2, after
discussion). **Commit-as-unreviewed, non-blocking review:** onboarding Import commits immediately (memory
feels alive on first run), but frames land with `status:'unreviewed'` + the B2 confidence score; Review is
a **non-blocking** curation surface (Memory Center "needs review" filter + the standing J08 queue), NOT a
blocking onboarding step. Reads PRD "nothing imports without review/approval" (646/1207) as *nothing is
trusted/surfaced until reviewed*, not *nothing is written*. Rationale: importing one's own memories is
additive + reversible (A8 archive/delete), so a blocking first-run gate would be friction in the wrong
place (founder principle: friction reserved for irreversible/destructive actions). Reuses A8 soft-status
+ B2 confidence — no extra migration. Supersedes the original §C C33 "blocking split" recommendation.
## ✅ Founder Ratifications — Phase 3 gate (2026-06-10)
The **Phase-3 (Intelligence) items are RATIFIED as recommended** (founder, 2026-06-10). Locked:
- **B3** Agent entity → real Agent object in `{dataDir}/agents.json` referencing `personaId`; persona =
behavioral template field. `successRate`/`lastRun` derived at read from `execution_traces`. No `.mind`
migration (M3 not shipped).
- **C24** Automation triggers → schedule-only v1 (cron cadence); Event trigger deferred (no event→automation
dispatch substrate).
- **C26** Builder test-run → NET-NEW no-persist dry-run route (`POST /api/automations/test`); do NOT reuse
`cron/:id/trigger` (executes + auto-enables).
- **C13** Skill Builder publishes create-to-local (`POST /api/skills/create`); marketplace publish lives in S06/S21.
- **C14** Skill inputs/outputs → body markdown v1; no `SkillFrontmatter` extension.
- **C22** Agent Center tabs = All/Personal/Workspace/Team/Autonomous/Archive; Templates = side affordance.
- **C23** Agent `/run` → one-shot fleet-spawn into a chosen workspace (picker if multiple `workspaceIds`);
persistent always-running agents deferred.
- **C25** Automation condition step → advisory `jobConfig.condition` string, no evaluation engine v1.
- **C27** Analytics tiles → keep success-rate (from `cron_execution_history`); drop "hours saved" or label
it an explicit heuristic estimate.
- **C36** Skill scope vocabulary → PRD `organization` (align §15.2 `Scope` union).
- **C37** Skill test-run fidelity → preview-only (injected-prompt + parsed metadata) v1; live LLM dry-run deferred.
## ✅ Founder Ratifications — Phase 4 gate (2026-06-10)
The **Phase-4 (Extend) items are RATIFIED as recommended** (founder, 2026-06-10). Locked:
- **A4** Real-where-substrate-exists, catalog-for-the-rest: connectors connect + health-probe +
`lastSyncAt` stamp (background data re-pull deferred); MCPs install/start/stop/test via the existing
marketplace installer + stdio runtime; static catalog renders honest "available / not installed"
states — never fake entries (PRD §22.2).
- **A5** Marketplace → federate-at-read over the six local domains; no `marketplace.db` migration;
remote registry / public marketplace deferred (PRD §4.4 + §22).
- **B5** Tier vocabulary → document the mapping; all new gates route through `@waggle/shared tiers.ts`
(`TierCapabilities`); MCP Hub + Marketplace install gated **PRO+**.
- **B7** `ExtensionType` → `skill | agent | connector | mcp | model | template` (drop `external_tool`;
external tools surface via connectors/MCPs). Defined once in `@waggle/shared`.
- **C15 / M2** install-audit `critical` CHECK → ship the additive migration (live sighting:
`marketplace.ts:228` writes `critical`, silently rejected by the DDL CHECK today).
- **C16** Connector "sync now" v1 = re-probe health + stamp `lastSyncAt`.
- **C17** `revoke` purges OAuth tokens + writes the stronger audit entry (PRD §17.3); `disconnect`
stays the lighter alias.
- **C18** One shared `GET /api/extend/audit?type=` serving connectors + MCPs + marketplace.
- **C19** MCP scope = single-`workspaceId` config v1 (matches stdio runtime); N:N deferred.
- **C20** "Remote Registry" tab deferred (runtime is stdio-only); v1 points at the static catalog.
- **C21** MCP `test` = live spawn-and-`isHealthy()`/`tools/list` round-trip where cheap; static
manifest validation fallback.
- Foundational task (coverage-check C4): populate `mcpRuntime` at boot from persisted config
(`local/index.ts` registers none today) — explicit Phase-4 work item gating all MCP routes.
---
Remaining pending: **A7** (RBAC — ratify before S10/Phase 5) + Phase-5/6 screen-local items.
## §A — PRD §23 Open Questions (the canonical 8)
### A1. Widget customization in Workspace Desktop — fixed layout or true customization in v1?
*(PRD §23 Q1, line 1416; gap card S02 §9 Q1.)*
- **(a) Why it matters:** Determines whether S02 reuses the maximized `AppWindow` + fixed widget layout
(cheap, in-place) or builds a draggable/resizable grid (parallel layout system, large blast radius).
PRD §12.2 already says "configurable widgets in *later* phase; fixed default layout in initial release".
- **(b) Options:**
1. *Fixed layout v1* — one default widget arrangement; reuse window manager. Lowest cost, ships Phase 1.
2. *Customizable grid v1* — drag/resize/persisted layout. New layout engine, persistence, much larger.
3. *Fixed + per-tab presets* — fixed canvas but a couple of named presets. Middle cost.
- **(c) RECOMMENDED:** **(a) Fixed layout v1.** PRD §12.2 self-answers this; customization is explicitly
a later phase. Rationale: keeps Workspace Desktop a maximized window in the existing OS, zero parallel
layout system.
- **(d) Blocks:** **Phase 1** (Workspace Desktop, S02). **[BLOCKS P1]** — but the PRD text already
resolves it, so this is a confirm-not-debate.
### A2. Home Cockpit scope — personal-only, or team/global views too?
*(PRD §23 Q2, line 1417; gap card S01 §9 Q3, Q5.)*
- **(a) Why it matters:** Decides whether the briefing reads cross-workspace personal state only, or also
team/shared rows. S01 §9 Q3 flags that reading the user's *own* workspaces server-side is now safe
(same-user), while team/shared rows must still gate through `approvalGrantStore`/RBAC.
- **(b) Options:**
1. *Personal-only v1* — briefing aggregates the user's own workspaces; team rows deferred to Phase 5.
2. *Personal + team summary v1* — adds a shared-activity strip (needs RBAC + Team substrate live).
3. *Toggle (personal/team) v1* — most flexible, most work; team substrate not ready until S10.
- **(c) RECOMMENDED:** **(a) Personal-only v1**, with the briefing builder written so a team summary can
be appended later behind the existing RBAC gate. Rationale: Team Workspace (S10) is a Phase-5 screen;
Home must ship in Phase 1 without it. Local-first + own-data read is the safe boundary.
- **(d) Blocks:** **Phase 1** (Home Cockpit, S01). **[BLOCKS P1]**.
### A3. Memory Center graph view — v1 or later?
*(PRD §23 Q3, line 1418; gap card S04 §9 / line 232.)*
- **(a) Why it matters:** Whether the "Graph" tab ships in the first Memory Center cut.
- **(b) Options:**
1. *Ship graph in v1* — the `knowledge_entities`/`knowledge_relations` substrate + a graph render
already work (S04 line 232: "Graph already works, so keep").
2. *Defer graph* — tab hidden until a later polish pass.
- **(c) RECOMMENDED:** **(a) Ship in v1.** Rationale: the substrate exists and S04 already confirms it
renders; deferring would be removing working capability for no gain.
- **(d) Blocks:** **Phase 2** (Memory Center, S04). **[BLOCKS P2]** (scoping-only; default = keep).
### A4. Which connectors/MCPs are real in v1 vs seeded/mock catalog?
*(PRD §23 Q4, line 1419; gap cards S06 §9 Q3, S07 §9 Q1, S08 §9 Q4–Q5, S14 §9 Q1, S15 §9 Q3, S21 §9 Q2.)*
- **(a) Why it matters:** Touches six screens. Determines the empty/syncing states of the Marketplace,
Connector Hub, MCP Hub, Tool Discovery and Memory-Import surfaces, and whether onboarding can pull data
in-flow. The connector registry has ~31 real entries; the MCP catalog (`@waggle/shared mcp-catalog.ts`)
is static; MCP runtime is **stdio-only** (`mcp-runtime.ts:108-115`) and currently never populated
(`local/index.ts:911`).
- **(b) Options:**
1. *Real-where-the-substrate-exists, catalog-for-the-rest* — OAuth connectors that already have SDK
entries connect for real (health-probe + timestamp, no background data-sync — S07 §9 Q1); MCPs
install via the existing marketplace installer (`installer.ts:580` writes `.mcp.json`); everything
else renders from the static catalog with honest "available / not installed" states.
2. *All-mock catalog v1* — nothing actually connects; fastest UI, but violates PRD §22.2 ("no major
screen depends only on mocked data when backend support exists").
3. *All-real v1* — build connector background-sync + remote MCP transport now; out of scope per PRD §4.4.
- **(c) RECOMMENDED:** **(1) Real-where-it-exists, catalog-for-the-rest.** Connectors: connect + health
probe + `lastSyncAt` stamp (defer true data re-pull). MCPs: install/start/stop/test against the static
catalog via the existing installer + stdio runtime; defer "Remote Registry" transport. Marketplace/Tool
Discovery: render the live registry, never invent fake entries. Rationale: honors PRD §22.2 and the
local-first default while staying in-place.
- **(d) Blocks:** **Phase 4** (S07/S08/S21) and the onboarding **Phase 2** import flow (S14/S15). Not P1.
### A5. Marketplace — local catalog vs remote registry initially?
*(PRD §23 Q5, line 1420; gap card S21 §9 Q2, S08 §9 Q4.)*
- **(a) Why it matters:** Whether S21 federates the existing local domains (marketplace.db + connectors +
templates + personas + models) client-side, or invests in widening `marketplace.db`/`InstallationType`
to natively catalog all six extension kinds.
- **(b) Options:**
1. *Federate-at-read (local-first)* — S21 composes the six categories from existing domains; no DB
change; "Remote Registry" is a later tab. (S21 §9 Q2 recommendation.)
2. *Native unified catalog table* — widen `marketplace.db` for publish/install/version parity across
all six kinds. Enables update-tracking but is a real schema investment; conflicts with PRD §22
"postpone public marketplace".
- **(c) RECOMMENDED:** **(1) Federate-at-read, local catalog first.** Remote registry / public
marketplace billing stays out per PRD §4.4 + §22. Rationale: matches local-first + in-place; no
`marketplace.db` migration.
- **(d) Blocks:** **Phase 4** (Marketplace, S21). Not P1/P2.
### A6. Artifact storage — workspace filesystem, virtual store, or external references first?
*(PRD §23 Q6, line 1421; gap card S05 §9 Q1, Q2.)*
- **(a) Why it matters:** Artifacts have **no backing entity today** (the single largest entity gap,
S10 line 226). PATCH/relations/status/tags require a stable id + an index. The file registry mixes
ingested inputs with produced outputs, so a `kind`/`status` classification rule is also needed.
- **(b) Options:**
1. *Per-workspace `artifacts.json` index over the existing workspace FS/virtual store* — mirrors
`documents.json`; assigns stable ids, holds status/tags/relations; reuses the StorageProvider
(virtual | local | team) already in the repo. (S05 §9 Q1.)
2. *Composite synthetic id (`workspaceId:store:name`), no index* — cheapest, but can't persist
status/tags/relations (PATCH becomes impossible).
3. *External references only* — point at files elsewhere; defers the entity but breaks "artifacts are
first-class outcomes" (PRD §6.4).
- **(c) RECOMMENDED:** **(1) `artifacts.json` index over the existing workspace storage**, with a
classification rule: an artifact is an **explicit produced output** (generated doc/deck/sheet/etc. or
user-promoted file), not every ingested input. Rationale: gives PATCH/relations a home with no `.mind`
migration, reuses the StorageProvider, keeps local-first.
- **(d) Blocks:** **Phase 2** (Artifact Center, S05); also gates artifact-sharing in S10. **[BLOCKS P2]**.
### A7. Minimum viable RBAC for team mode?
*(PRD §23 Q7, line 1422; gap card S10 §9 Q1 (blocking), Q2.)*
- **(a) Why it matters:** Three role models disagree: PRD §17.2 (`Owner/Admin/Contributor/Viewer`),
blueprint (`+Member +Guest`), and the **live `teams.db` CHECK** (`owner/admin/member/viewer`,
`team.ts:21`). Picking wrong forces a DB CHECK migration + RBAC-logic rewrite. There is also a **real
bug**: `PUT …/members/:userId` is owner-only (`team.ts:624`) while `PATCH` on the same path is
owner/admin (`team.ts:649`).
- **(b) Options:**
1. *Keep the live 4-role union (`owner/admin/member/viewer`)* — map PRD "Contributor" → "Member",
defer "Guest". No DB migration, no RBAC rewrite. (S10 §9 Q1 recommendation.)
2. *Adopt PRD §17.2 four roles literally* — rename `member`→`contributor` in the DB CHECK + all
enforcement (migration + grep-everywhere).
3. *Adopt blueprint six roles (+Guest)* — new deny-by-default capability rules; largest scope.
- **(c) RECOMMENDED:** **(1) Keep the live union; Contributor==Member; defer Guest.** Also **align the
PUT/PATCH gate to owner+admin** (PRD uses PATCH; pick the broader gate consistently). Rationale:
in-place, zero migration, fixes a real inconsistency.
- **(d) Blocks:** **Phase 5** (Team Workspace, S10) — the `TeamRole` type + all member-management UI.
Not P1/P2, but **must be ratified before S10 coding starts** (S10 §6: "decision needed before coding").
### A8. Memory retention / delete / tombstone behavior?
*(PRD §23 Q8, line 1423; gap cards S04 §9 Q3, S16 §9 Q2.)*
- **(a) Why it matters:** PRD §14.4 distinguishes Deprecated / Archived / Deleted-tombstoned, but
`memory_frames` has only `importance:'deprecated'` today and no `status`/tombstone column; delete is a
hard `FrameStore.delete`. Determines whether an additive `.mind` migration is required and what
"archive" vs "delete" mean to the user.
- **(b) Options:**
1. *Soft-status via `metadata` JSON, hard-delete on Delete* — store `{status: active|archived|
deprecated}` in the existing `metadata TEXT` (idempotent `ADD COLUMN` pattern at `db.ts:122` if a
queryable column is needed); Delete = hard `FrameStore.delete`. Archive = reversible status.
2. *Full tombstone model* — Delete writes a tombstone row (retained, hidden, syncable) for audit/undo.
Heavier; needed only if team-sync conflict-resolution requires it.
3. *No status, delete-only* — simplest, but loses the Archived/Deprecated states PRD §14.4 requires.
- **(c) RECOMMENDED:** **(1) Soft-status in `metadata` (Archive = reversible status, Deprecate = existing
`importance`), Delete = hard delete with a scope-and-consequence confirmation** (PRD J20). Promote
`status` to a real column only if it becomes a primary filter axis. Defer full tombstones to the
team-sync phase. Rationale: local-first, one additive migration at most, satisfies §14.4 states.
- **(d) Blocks:** **Phase 2** (Memory Center, S04) — and shares the confidence/metadata migration
decision with the onboarding Memory Review (S16, see B2). **[BLOCKS P2]**.
---
## §B — Cross-cutting decisions (block ≥2 screens; not in PRD §23 but surfaced by gap cards)
### B1. Shell topology — keep the bottom-dock OS, or migrate to a left-rail / route-based shell?
*(Gap cards S00 §9 Q1–Q2, Q5; S01 §9 Q4; S11 §9 Q5/Q7; S20 §9 Q7.)*
- **(a) Why it matters:** This is the **Phase-0 IA freeze**. The live shell is a single-route windowed
OS with a bottom `Dock.tsx`; blueprint/mocks show a **left navigation** + `/home,/workspaces,…` route
groups. Every later screen's navigation/AppId/dock placement depends on this. Deep-linking + browser
back-button are the only things real routes buy.
- **(b) Options:**
1. *In-place dock reframe, keep `AppId`-keyed window navigation* — cheapest, preserves the OS feel and
multi-window runtime; no react-router. (S00 §9 Q1–Q2 recommendation.)
2. *Left rail + react-router routes* — closer to the mock, gains deep-linking, but a parallel layout +
conflicts with multi-window; large blast radius.
- **(c) RECOMMENDED:** **(1) In-place dock reframe; keep windowed `AppId` navigation.** Group dock
entries into Work / Intelligence / Extend / Team zones to satisfy the IA without a router. Rationale:
PRD §24 (mocks directional) + locked in-place direction. Revisit deep-linking only if it becomes a hard
requirement.
- **(d) Blocks:** **Phase 0 → Phase 1** (AppShell/IA, S00) — and the dock/AppId placement of S11/S20
("automations" zone) and S01 (`home` vs `cockpit`). **[BLOCKS P1]** — the IA freeze gates everything.
### B2. Memory confidence — heuristic-at-preview vs LLM-classify, and persisted vs preview-only?
*(Gap cards S04 §9 Q1, S16 §9 Q1–Q2; S15 §9.)*
- **(a) Why it matters:** `memory_frames` has no confidence today (only `knowledge_relations.confidence`,
edges-only, `schema.ts:93`). PRD §12.4 wants "filter by confidence" + "low-confidence surfaced for
review", and onboarding Memory Review (S16) + the standing J08 review queue both depend on it. Wiring
the existing `HarvestPipeline` classify/synthesize means paid Haiku/Sonnet calls per import (slow,
gated on a real embedder); a cheap heuristic avoids that.
- **(b) Options:**
1. *Cheap heuristic at preview (source-trust × adapter-type × dedup signal), persisted in `metadata`
when a queryable filter is needed* — fast, no per-import LLM cost; reserve LLM scoring for an opt-in
deep pass / the J08 standing queue. (S16 §9 Q1 recommendation.)
2. *LLM classify/synthesize at preview* — real confidence, but onboarding-latency + cost hit.
3. *No confidence v1* — drops a core PRD trust requirement (§12.4).
- **(c) RECOMMENDED:** **(1) Heuristic for onboarding v1; LLM classify reserved for the standing J08
queue.** Persist `{kind, confidence, sourceId, status}` in the existing `memory_frames.metadata TEXT`
via the idempotent `ADD COLUMN` pattern (`db.ts:122`) **only if** confidence/status become queryable
filters; preview-only needs no migration. Make this one decision once and reuse it across S04 + S16.
Rationale: honors PRD trust criteria within the onboarding latency budget, local-first, one additive
migration at most.
- **(d) Blocks:** **Phase 2** — onboarding Memory Review (S16, a day-0 J01 flow) and Memory Center
filters (S04). **[BLOCKS P2]**. Shares the migration with A8.
### B3. Agent vs Persona boundary, and where the Agent entity is stored.
*(Gap cards S09 §9 Q1, Q3; S18 §9 Q1, Q2.)*
- **(a) Why it matters:** Decides whether Phase 3 introduces a real persisted Agent object (distinct from
the 13/17 personas in `persona-data.ts`) or just re-skins the persona catalog. PRD §15.5 lists explicit
agent fields (model, autonomy, memoryScopes, skillIds, connectorIds, mcpIds, permissions, …) that a
persona does not carry.
- **(b) Options:**
1. *Real Agent entity in a JSON store (`{dataDir}/agents.json`), referencing `personaId`* — no `.mind`
migration, mirrors the `agent-groups.json` precedent; persona = behavioral template field of the
agent. (S09 §9 Q1/Q3 + S18 §9 Q1/Q2 recommendation.)
2. *`agents` table in `mind/schema.ts` (SCHEMA_VERSION bump)* — heavier; PRD §4.4 non-goal favors
minimal backend.
3. *No Agent entity; persona re-skin only* — can't satisfy PRD §12.9 explicit-scope requirements.
- **(c) RECOMMENDED:** **(1) Real Agent entity, JSON store, references `personaId`.** Derive
`successRate`/`lastRun` at read from `execution_traces` (avoid a third tally vocabulary). Rationale:
satisfies PRD §12.9/§15.5 with zero migration, in-place over the existing fleet/traces substrate.
- **(d) Blocks:** **Phase 3** (Agent Center S09 + Agent Builder S18). Not P1/P2.
### B4. `/api/*` vocabulary aliasing — singular command, automations, mcps, connectors revoke.
*(Gap cards S03 §9 Q1, S11 §9 Q4, S20 §9 Q4, S07 §9 Q3; backend-api-delta.)*
- **(a) Why it matters:** PRD §16 uses vocabulary (`/api/command/*`, `/api/automations/*`,
`/api/connectors/:id/revoke`) that differs from the live routes (`/api/commands/execute`, `/api/cron/*`,
`/api/connectors/:id/disconnect`). Renaming breaks existing callers (`adapter.executeCommand`,
`commands.ts`, `cron.ts`); aliasing keeps both contracts.
- **(b) Options:**
1. *Add PRD-vocabulary aliases alongside the live routes* — new `command.ts`/`automations.ts` alias
plugins that delegate to the existing registry/cron; existing callers unbroken. (S03/S11/S20
recommendations converge on this.)
2. *Hard-rename to PRD vocabulary* — clean surface, but breaking; needs exhaustive grep (CLAUDE.md §3.5).
- **(c) RECOMMENDED:** **(1) Alias, don't rename.** New singular/plural aliases that delegate to the
existing handlers; UI/adapter point at the PRD vocabulary. Rationale: in-place, non-breaking, matches
the backend-api-delta dispositions.
- **(d) Blocks:** **Phase 1** (Command Center S03) for `/api/command/*`; **Phase 3** (S11/S20) for
`/api/automations/*`; **Phase 4** (S07) for connector revoke. The command alias is **[BLOCKS P1]**.
### B5. Tier-vocabulary unification (`UserTier` / `BillingTier` / `PlanTier` + RBAC roles).
*(Gap cards S00 §9 Q3, S08 §9 Q6.)*
- **(a) Why it matters:** Three independent tier vocabularies gate the dock, billing, and feature access;
PRD §17 RBAC roles add a 4th axis. MCP Hub (S08) and the dock (S00) both need a single answer for
"is this gated PRO+ or power-user-density".
- **(b) Options:**
1. *Document the mapping, defer unification* — keep the three vocabularies, ship a single mapping table
and a `useFeatureGate` that reads the canonical `tiers.ts`; no cross-cutting rewrite now.
2. *Unify into one tier model now* — clean, but cross-cutting (billing + dock + features + RBAC) during
a high-velocity refactor.
- **(c) RECOMMENDED:** **(1) Document the mapping + route all new gates through `@waggle/shared tiers.ts`
(`TierCapabilities`); defer the unification refactor.** Gate MCP Hub + Marketplace install at **PRO+**
(matches the existing marketplace install gate). Rationale: avoids a cross-cutting rewrite mid-refactor;
reuses the canonical tier system; no parallel gate (S10 §6).
- **(d) Blocks:** **Phase 4** (S08 tier gate) primarily; informs the dock gate in Phase 0/1. Not P1
blocking if the mapping is documented.
### B6. `MemoryKind` / `ImportItemType` / FE `MemoryFrame.type` reconciliation.
*(Gap cards S04 §9 Q6, S16 §9 Q3.)*
- **(a) Why it matters:** Three vocabularies disagree: FE `MemoryFrame.type` (`event`/`insight`/…),
PRD §15.2 `MemoryKind` (`fact|decision|task|preference|strategy|learning|goal|entity`), and the harvest
adapter's 8 `ImportItemType` values. Memory Review categories (Memories/Decisions/Tasks/Artifacts/
Projects) need a 1:1 map. Wrong choice re-renders existing frames and changes the type-filter chips.
- **(b) Options:**
1. *Adopt PRD §15.2 `MemoryKind` as canonical; add a pure `lib/harvest-kind-map.ts` mapping
`ImportItemType → MemoryKind` and a display-category map* — drop FE `event`/`insight`, add
`preference/strategy/learning/goal`. (S04 §9 Q6 + S16 §9 Q3 direction.)
2. *Keep FE types, map PRD onto them* — less churn now, perpetuates drift (precedent: the FrameSource
TS-vs-DB drift the shared-types-delta warns against).
- **(c) RECOMMENDED:** **(1) PRD §15.2 `MemoryKind` canonical, in `@waggle/shared`; pure mapping helpers
for harvest + display categories.** Rationale: one source of truth (shared-types-delta §0 rule), avoids
perpetuating drift, keeps the import/review/center contract consistent.
- **(d) Blocks:** **Phase 2** (S04 + S16). **[BLOCKS P2]**.
### B7. `ExtensionType` union — add `agent`, keep `external_tool`, or both?
*(Gap card S21 §9 Q1; PRD §12.13 vs §15.2.)*
- **(a) Why it matters:** PRD §12.13 marketplace categories include **Agents** but `ExtensionType`
(§15.2) omits `agent` and adds `external_tool`. The two PRD sections contradict; S21's faceted catalog
needs a canonical union.
- **(b) Options:**
1. *`skill | agent | connector | mcp | model | template`* — matches the §12.13 visible categories;
drop `external_tool` (external tools surface via connectors/MCPs anyway).
2. *Keep §15.2 literally (`…| external_tool`, no agent)* — but then Agents have no marketplace category.
3. *Superset of 7 (`…| external_tool | agent`)* — covers both, at the cost of an unused-for-now member.
- **(c) RECOMMENDED:** **(1) `skill | agent | connector | mcp | model | template`.** Rationale: PRD §12.13
is the user-visible contract; external tools are already represented by connectors/MCPs, so `agent`
earns the slot. Define once in `@waggle/shared`.
- **(d) Blocks:** **Phase 4** (Marketplace, S21). Not P1/P2.
### B8. Identity store of record for onboarding profile.
*(Gap card S13 §9 Q1; S01 §9 (greeting name).)*
- **(a) Why it matters:** Two identity stores exist — `/api/profile` (current onboarding write path) and
`/api/identity` (the `identity` table that backs the Home greeting name / `adapter.getIdentity()`).
Writing only one leaves the other stale (e.g. Home greets with an empty name).
- **(b) Options:**
1. *Onboarding writes profile AND seeds identity* — single round-trip extension; Home greeting works
immediately. (S13 §9 Q1 direction.)
2. *Profile-only, derive identity lazily* — fewer writes, but Home greeting drift until first identity write.
- **(c) RECOMMENDED:** **(1) Write profile + seed identity in the same onboarding commit.** Rationale:
prevents the two-store drift the gap card flags; cheap; makes the Phase-1 Home greeting correct.
- **(d) Blocks:** **Phase 2** (onboarding S13) and the **Phase 1** Home greeting depends on identity
being populated. Practically **[BLOCKS P1]** for a correct greeting; functionally a small fix.
---
## §C — Screen-local questions (single-screen scope; ratify with the owning card)
> These do not block other screens. Each carries a default recommendation consistent with the locked
> direction; founder can rubber-stamp or override per screen. Cited to the gap card for full context.
- **C1. S01 Q1 — LoginBriefing fate.** Retire the modal; absorb catch-up into Home Cockpit's first paint
(~80% overlap). **Rec: retire + absorb.** *(Phase 1.)*
- **C2. S01 Q2 — "Overnight" time-window semantics** (since last close vs midnight vs 12h). **Rec: since
last app close, fallback midnight-local.** *(Phase 1.)*
- **C3. S01 Q6 — Quick-capture `file` destination** (default/personal store vs prompt for workspace).
**Rec: default personal store + optional workspace picker.** *(Phase 1/2.)*
- **C4. S02 Q1 — Workspace Desktop window vs full-bleed route.** **Rec: maximized `AppWindow`** (no
parallel layout system). *(Phase 1.)*
- **C5. S02 Q2 — Overview chat: live mini-composer vs read-only preview.** **Rec: read-only preview that
deep-links to the Chat tab** (avoids dual ChatApp render modes in v1). *(Phase 1.)*
- **C6. S02 Q3 / S17 Q1 — `WorkspaceType` enum values.** **Rec: `project | client | research | personal`
(+`team`/`organization` reserved); `type` coexists with the free-string `group`.** *(Phase 1/2.)*
- **C7. S02 Q6 — Tasks store of record** (`/api/workspaces/:id/tasks` vs `WorkspaceState`
`pending`/`blocked`). **Rec: seed Tasks from `WorkspaceState` for v1; reconcile to a first-class task
store only if editing is needed.** *(Phase 1.)*
- **C8. S03 Q4 — Natural-language commands** (heuristic vs LLM). **Rec: deterministic heuristic
intent-parse v1; LLM resolver later.** *(Phase 1.)*
- **C9. S03 Q5 — Palette permission prompt mechanism.** **Rec: reuse the chat approvals pipeline
(`approval.ts` + `pendingApproval`).** *(Phase 1.)*
- **C10. S04 Q2 — Conflict state: live recall-time vs persisted.** **Rec: live recall-time signal v1**
(`CombinedRetrieval.detectConflict`); persist only if a standing conflict queue is needed. *(Phase 2.)*
- **C11. S04 Q4 — Merge semantics.** **Rec: re-cognify/concatenate v1, archive originals (not hard
delete); LLM-synthesis later.** *(Phase 2.)*
- **C12. S05 Q5 — Artifact previews.** **Rec: icon + on-click `FilePreview` v1; no server thumbnails.** *(Phase 2.)*
- **C13. S06 Q2 / S19 Q1 — Skill Builder publish target** (local dir vs marketplace). **Rec: Builder =
create-to-local (`POST /api/skills/create`); install-by-id + marketplace publish live in S06/S21.** *(Phase 3.)*
- **C14. S06 Q4 / S19 Q2 — Inputs/Outputs persistence** (frontmatter vs body markdown). **Rec: body
markdown v1; extend `SkillFrontmatter` only if inputs/outputs must be queryable.** *(Phase 3.)*
- **C15. S06 Q6 / install-audit `critical` CHECK bug.** Real bug: `AuditRiskLevel` TS includes `critical`
but the DDL CHECK allows only `low/medium/high` (`install-audit.ts:65` vs `:16`) — a `record()` with
`critical` throws; skill/MCP/connector installs route through this path. **Rec: ship the one-line CHECK
migration to add `critical`** (additive, idempotent-migration pattern at `db.ts:122`), OR make the
marketplace `CRITICAL → 'high' + approvalClass:'blocked'` mapping the permanent contract. **Pick the
migration** for correctness. *(Phase 4; cross-cuts any install-audit write.)*
- **C16. S07 Q1 — Connector "sync now" semantics.** **Rec: v1 = re-probe health + stamp `lastSyncAt`**;
background data re-pull deferred. *(Phase 4.)*
- **C17. S07 Q3 — revoke vs disconnect.** **Rec: `revoke` purges OAuth tokens + writes a stronger audit
entry (PRD §17.3); `disconnect` is the lighter alias.** *(Phase 4.)*
- **C18. S07 Q4 / S08 — Audit route shape.** **Rec: one shared `GET /api/extend/audit?type=` serving
connectors + MCPs + marketplace**, bound to `personal.mind`. *(Phase 4.)*
- **C19. S08 Q2 — MCP scope model** (single `workspaceId` vs `mcpIds[]` N:N). **Rec: single-`workspaceId`
config v1 (matches the stdio runtime); N:N membership deferred.** *(Phase 4.)*
- **C20. S08 Q4 — "Remote Registry" tab.** **Rec: defer remote-transport MCPs (runtime is stdio-only);
v1 tab points at the static catalog / Composio gateway reference, no new transport.** *(Phase 4.)*
- **C21. S08 Q5 / S21 Q5 — MCP "test" semantics.** **Rec: live spawn-and-`isHealthy()`/`tools/list`
round-trip** where cheap; fall back to static manifest validation. *(Phase 4.)*
- **C22. S09 Q6 — Agent categories taxonomy.** **Rec: Templates is a side affordance, not a tab; tabs =
All/Personal/Workspace/Team/Autonomous/Archive.** *(Phase 3.)*
- **C23. S09 Q7 / S18 Q3 — `/run` target + lifecycle.** **Rec: fleet-spawn a one-shot into a chosen
workspace (picker if multiple `workspaceIds`); persistent always-running agents deferred.** *(Phase 3.)*
- **C24. S11 Q1 / S20 Q1 — Automation triggers: schedule-only vs event-driven.** **Rec: schedule-only v1
(cron cadence); gate/defer the "Event" trigger (no event→automation dispatch substrate today).** *(Phase 3.)*
- **C25. S11 Q2 / S20 Q2 — Condition step.** **Rec: store an advisory `jobConfig.condition` string (no
evaluation engine) v1.** *(Phase 3.)*
- **C26. S11 Q3 / S20 Q3 — Builder "test run".** **Rec: add a no-persist dry-run route (`POST
/api/automations/test`); do NOT reuse the real `cron/:id/trigger` which executes + auto-enables.** *(Phase 3.)*
- **C27. S11 Q6 — Analytics tiles.** **Rec: keep success-rate (derivable from `cron_execution_history`);
drop "hours saved" (no source) or label it an explicit heuristic estimate.** *(Phase 3.)*
- **C28. S12 Q1 — Onboarding language selector.** **Rec: static disabled `English (US)` chip (no i18n
exists; PRD §4.4 puts i18n out of first-phase scope).** *(Phase 2.)*
- **C29. S12 Q2 — First-launch 3s auto-advance on the privacy screen.** **Rec: drop the auto-advance**
(it fights the read-the-privacy-note intent). *(Phase 2.)*
- **C30. S13 Q3 — Work-type vs Industry vs Template axis.** **Rec: keep Work type as a distinct
personalization signal; don't re-ask what the template already implies (PRD §12.12).** *(Phase 2.)*
- **C31. S14 Q2 — Tool Discovery id-space.** **Rec: unify under a namespaced scheme
(`connector:gmail` / `tool:cursor`) so the recommender + S15 disambiguate.** *(Phase 2.)*
- **C32. S14 Q3 — Pre-check detected AI tools.** **Rec: pre-select from `GET /api/tools/detect` with a
visible "detected" badge** (J01 implies a trusted populated start). *(Phase 2.)*
- **C33. S15 Q2 / S16 Q5 — Import↔Review commit split.** **Rec: S15 stages previews, S16 commits the
approved selection** (PRD:646/1207 "nothing imports without review/approval"; current code commits at
S15 — fix). Splits onboarding into the Import + Review steps. *(Phase 2; correctness-relevant.)*
- **C34. S15 Q1 — Hermes/Codex/Cursor tiles.** **Rec: render as `upload`/"Other" file pickers or
"coming soon" v1** (they are AI-OS launcher/hook surfaces, not harvest adapters). *(Phase 2.)*
- **C35. S17 Q5 — Workspace Creation: install-on-create vs stage selections.** **Rec: record connector/
MCP ids as workspace *intent* on the config; do NOT run install/OAuth at create time.** *(Phase 2.)*
- **C36. S19 Q4 — Skill scope vocabulary** (`enterprise` vs PRD `organization`). **Rec: adopt PRD
`organization`** for the publish-scope picker (align to the §15.2 `Scope` union). *(Phase 3.)*
- **C37. S19 Q5 — Skill test-run fidelity.** **Rec: preview-only (injected-prompt + parsed metadata) v1**;
live LLM dry-run deferred. *(Phase 3.)*
---
## Phase-blocking summary (founder fast-path)
**Before Phase 0/1 coding** (the spine): ✅ **RATIFIED 2026-06-09** — **B1** (shell topology / IA freeze),
**A1** (fixed layout), **A2** (Home personal-only), **B4** (command alias), **B8** (identity seed for
greeting). **Phase 0 is unblocked.**
**Must ratify before Phase 2** (work + onboarding): **A6** (artifact storage entity), **A8** (memory
retention/delete), **B2** (confidence: heuristic + optional migration), **B6** (MemoryKind canonical),
**A3** (graph keep — default yes), plus the onboarding correctness item **C33** (Import stages / Review
commits).
**Phase 3+ (intelligence/extend/team), not blocking P1–P2:** **A4, A5, A7, B3, B5, B7** + all remaining
§C items. Note **A7** (RBAC) must be ratified before S10 coding specifically, and **C15** (install-audit
`critical` CHECK bug) should be fixed before any install-audit write path ships in Phase 4.
---
# UX Refactor v2.1 — Ratification of Decision Register D1–D15 (2026-06-10)
**Ratifies:** `docs/UX_REFACTOR_STATE_AUDIT.md` §8.3 · **Ratified by:** Marko Marković (founder)
**Authority chain (declared by this register, D10):** this ratification > Brief v2.1 > `docs/UX_REFACTOR_STATE_AUDIT.md` > blueprint handoff package > prior-plan docs (`docs/ux-refactor/`).
This document + Brief v2.1 + the audit **supersede all prior conflicting ratifications, explicitly including B1 (2026-06-09)**. This file is the **single decision log** going forward — no parallel ratification tracks.
## Structural (D1–D5)
### D1 — Shell topology: RATIFIED option (b) — AppShell via in-place conversion. **B1 is explicitly superseded.**
Convert to AppShell + left nav + single canvas + URL routes, reusing every shipped screen component as a route surface. Conditions:
1. **Zero screen-component rewrites during conversion**; screens mount under routes as-is. Divergences are phase work, not conversion work.
2. Brief route groups become **canonical addresses**; Ctrl+K command index and `handleSearchNavigate` retarget to routes; `waggle:open-app` CustomEvent deep links convert to URL navigation (the event bus may remain as an internal shim during transition, but **URLs are the contract**).
3. **No window z-order code ships** (`useWindowManager` z-order/focus/minimize/cascade retired). `waggle-window-state-v1` localStorage migrates or clears cleanly.
4. **Chat multi-instance:** chat becomes the widget inside Workspace Desktop (one per workspace, per blueprint "chat is one widget"). If conversion design surfaces a hard requirement for detached chat, propose it as a scoped exception ("D1-c lite") — do not silently keep windowing.
5. **B4 ("alias, don't rename" for `/api/*`) survives** — orthogonal to the shell and correct.
### D2 — Memory Center: RATIFIED — rework AND promote to standalone.
Standalone `MemoryCenterApp` (same shape as `ArtifactCenterApp`; audit §7.9 inconsistency resolved in favor of the standalone pattern). Top-level structure = **two-mind split**: "About you" (Personal Mind) / "About this work" (Workspace Mind, per workspace). Reuse `MemoryCenterTab` internals as the per-mind list. Confidence/metadata (B2, M1) carry over. Legacy MemoryApp tabs (Graph/Timeline/etc.) remain accessible from within the new surface or as secondary tabs — **do not delete capability, restructure the entry**.
### D3 — Auth gate: RATIFIED — full structural scope. All four audit conflicts in scope:
1. **Adapter-level pre-token deferral** (structural gate, not per-component convention).
2. **Throw-on-`!ok` mandated adapter-wide** — convert all silent-empty getters (`getMarketplace`, `getMcps`, `getPersonas`, `getModels`, `getWorkspaceTemplates`, `getTier`).
3. **401 → silent token refresh → single retry** (sidecar-restart recovery) — in scope.
4. **Boot-path surfaces in scope:** `Desktop.refreshTier` and `LoginBriefing` must never render silent-FREE / silent-empty on auth failure. **Tier resolution failing open to a rendered FREE state is classified as a monetization defect, severity-critical.**
Plus: error states never cache as valid-empty; focus/visibility revalidation on errored surfaces.
### D4 — Skill-write governance: RATIFIED — autonomy-aware gating, four bindings:
- **(i) Policy:** `create_skill` — normal autonomy = ask (in-chat approval card), trusted/yolo = auto-execute. `delete_skill` — **always ask, every autonomy level** (add to `isCriticalNeverAutopass`); destructive actions do not inherit autonomy. `read_skill` ungated. **Always-audit all three** outcomes with `initiator:'agent'`.
- **(ii) Surface:** the **in-chat SSE approval card is canonical** for agent skill writes. Brief §2.3's "same modal" is hereby interpreted as **same policy and risk taxonomy, not same component**. Align the card's risk display with the `ui/approval-modal.tsx` taxonomy (D15 work).
- **(iii) One write path — AMENDED ruling: do NOT route the agent tool through HTTP.** Extract a **shared skill-write service module** (create/update/delete + redaction + audit write inside the service) consumed by both `routes/skills.ts` and `skill-tools.ts`. One module, one audit trail, two callers.
- **(iv) Endpoint consolidation (absorbs D14):** raw `POST /api/skills` delegates to the audited service (or is deprecated in favor of `/api/skills/create`); `PUT` and `DELETE /api/skills/:name` enter the audit trail. **Provenance:** skill frontmatter `initiator`/`source` + `GET /api/skills` returns it + Skills Hub badge ("created by agent — review"), replacing the name-heuristic "Custom" classification for agent-created skills.
- **Persona exception RATIFIED:** read-only personas (planner/verifier) keep losing `create_skill`/`delete_skill` while retaining `read_skill`.
- **PM residual ruled (PRO-gate on skill creation):** skill creation — human and agent — **stays available at FREE for launch**. The self-evolving loop is the differentiator and must demo at the free tier. Marketplace installs remain PRO-gated. Reversible post-launch with data.
- **Two-seam WorkspaceDesktopApp edit RATIFIED (founder "go", 2026-06-10):** the derived edit from plan §5.2 — (a) controlled activeTab/onTabChange for URL-driven tabs, (b) chat widget embedded in the chat tab body — is signed off, scoped to exactly those two seams, test-pinned. P1a unblocked.
### D5 — Team zone: RATIFIED — keep tier-hidden. No stripping, no new work. Approvals-inbox PRO visibility: post-launch consideration, not launch scope.
## Scope clarifications (D6–D10) — defaults ratified, with notes
- **D6 — RATIFIED.** S14-in-Launcher and S16-as-needs-review-filter satisfy the launch cut. Consent is given at import initiation; review is quality control, not consent. **Verification item:** Home Cockpit must surface a "N memories need review" alert (journey J08); if absent, add as a small Phase-2 item.
- **D7 — RATIFIED.** `UpgradeModal` satisfies §2.2; no rename, no rebuild — tests pin it. Brief language amended to "Upgrade surface."
- **D8 — RATIFIED.** Relabel dock `cockpit` entry ("Mission Control"); **"Command Center" is reserved for the Ctrl+K palette.**
- **D9 — RATIFIED.** Sweep: code (the `HomeCockpit.tsx:145` user-visible "Win+K" pill is the must-fix; comments included) + `docs/ux-refactor/` prose. Handoff-package PDFs/docx get a one-page annotation (naming erratum), not regeneration.
- **D10 — RATIFIED, extended.** Commit the package's text files; gitignore (or LFS) the binaries. Authority chain declared (header above). Prune merged worktrees (`waggle-os-ux-refactor`, `waggle-os-ga`) and the 5 merged branches. Brief path corrections from audit §7 accepted (workspace-manager in hive-mind-core; state/context in server/local).
## Launch integrity (D11–D15) — all confirmed
- **D11 — RATIFIED.** Honor `WAGGLE_DATA_DIR` in `service.ts` with the same default; **one startup log line: resolved dataDir + tier**. Fix the stale "default to SOLO" comment while in there. Closes the split-brain with installer/launcher.
- **D12 — RATIFIED, launch-blocking for the desktop binary.** Refresh `app/src-tauri/resources/service.js` now; prefer build-time generation + untracking; CI staleness/hash gate is the minimum acceptable. **A binary shipping an April server is a release-stopping defect class.**
- **D13 — RATIFIED, both halves.** Document `build:packages` in the boot recipe AND alias `@waggle/shared`→src on the dev path so the class dies.
- **D14 — Folded into D4(iv). Closed.**
- **D15 — RATIFIED.** Launch-blocking from prior-plan P6: **per-screen state grid** (brief rule 10) + **approval/audit taxonomy consolidation** (brief rule 7, includes D4-ii alignment). Post-launch: connector `/sync` real implementation (stub stands), MCP logs.
## Additional items (no decision letter — just do)
- **Backlog flag:** investigate the teams-server boot error from the live probe (`Build failed: Fastify instance is already listening` when `CLERK_SECRET_KEY` is set) — classify noise vs defect. Post-launch unless it affects the solo boot path.
- **memory-mcp duplication (audit §7):** out of launch scope. Mark `packages/memory-mcp` dormant; canonical-package decision (vs `hive-mind-mcp-server`) deferred post-launch.
- **`WorkspaceBriefing.tsx`:** keep as ChatApp empty state; no merge into Home. Brief's keep-list note corrected.
- **Audit process rule going forward:** audits report, they don't mutate (no fast-forwards, no pid overwrites mid-audit; disclose if unavoidable).
## Phase sequence (unblocked)
**Phase 0** = D1 conversion plan + route map, naming sweep (D8/D9), doc authority (D10). Then **P1**=D3, **P2**=verify + J08 alert, **P3**=D2, **P4**=D11/D12 + FREE→Upgrade e2e re-run, **P5**=D4 ✅ (2026-06-12, 7 commits 73f2ed5→48292ef), **P7**=D15 scope ✅ (2026-06-12: Track B B1-B5 + Track A A1-A7; D15 closure bar MET). **Nothing from prior Phases 0–4 is rebuilt.**
---
## D3 implementation notes (P1b, 2026-06-11)
Recorded per the single-decision-log rule; full design + verification record in
`docs/ux-refactor/p1b-auth-gate-plan.md` + `p1b-plan-review-record.md`.
1. **fetchRaw exception class — ratified-flow-preserving deviation from the literal
"throw mandated adapter-wide" (D3-2).** Two caller classes keep non-throwing
semantics because their *error-path payload is load-bearing*: raw-Response
consumers (`installMarketplacePackage` — documented 403/SecurityGate status
handling) and body-envelope getters (`installMcp` + 6 MCP siblings +
`revokeConnector` — their 403/422 bodies carry `TIER_INSUFFICIENT` and the
`requiresApproval/blocked/severity` envelope that drives the D4 ApprovalModal
security flow). All six ruling-named getters throw as mandated. Adapter-level
envelope pins added (component tests mock the adapter and cannot see this layer).
2. **Plus-clause revalidation scope.** Wired: tier (ShellContext), useBilling,
useWorkspaces, LoginBriefing, MCPHubApp resolvableMcpNames, ComplianceDashboard
templates. Deferred to P7 with ledger: ChatWindowInstance FALLBACK_MODELS,
TemplatesView/AgentBuilder catalogs (their boot-race instance dies with the gate;
the 401-retry leg cures their restart instance; residual is genuine-5xx staleness).
3. **D3-4 extensions (same monetization-defect class):** useBilling (Settings→Billing
rendered FREE-as-fact + upgrade CTAs on failure) and the Settings→General
"{tier} plan" badge (separate getSettings-fed copy, now single-sourced from
resolved billing state).
4. **DISCOVERED, OUT OF P1b SCOPE — needs a founder ruling:** all five EventSource
SSE channels (notifications / events / subagent status / waggle signals / harvest
progress) are **401-dead in every default run since D1** — the server bearer-gates
all /api/* GETs, EventSource cannot send headers, no SSE route accepts ?token=
(only /ws does), and onerror handlers permanently close. Working only under
WAGGLE_TRUST_LOCALHOST=1. Fix = server auth model (per-route ?token= like /ws, or
exempt-with-validation) + client reconnect design — one coherent follow-up
("SSE auth + reconnect"). **Ask: ratify as P1b follow-up stage or P2 line item.**
---
## P2 implementation notes (verify + J08, 2026-06-11)
Recorded per the single-decision-log rule; full record in
`docs/ux-refactor/p2-verification-record.md`.
1. **P2 verification CLOSED.** Home (§12.1) + Desktop (§12.2) verified against Brief
v2.1 via a 4-lane adversarial workflow: 25/37 met or ratified-divergence, 12
confirmed gaps, 2 claims refuted. The HIGH (dead Artifacts feed — envelope
unwrap) + all tiny/small verified defects fixed; feature-shaped residuals
ledgered in the record (S02 tab embeds → P3/P7; status-bar chips, upNext
tasks, activeModels → P7).
2. **D6 J08 alert SHIPPED.** `needsReviewCount` rides `GET /api/home/briefing`
(personal-mind only, 200-frame bound matching the Memory Center's own window);
Home banner deep-links via `waggle:open-app {appId:'memory', filter:'unreviewed'}`
with a `?filter=` URL carrier + MemoryRoute cold-load re-stash (typed URLs and
the §2.3 shim share one mechanism, AutomationsRoute pattern).
3. **D3-4 extension:** WorkspaceDesktop revalidation arms only for the transient
offline state — deterministic 404/403 states do not auto-refetch on focus.
4. **Note (P1b-SSE follow-up):** the SSE ask above was ratified and SHIPPED as a
P1b follow-up (PR #15, main @ 4e3d65d) — closed before P2 started.
---
## P3 implementation notes (D2 two-mind Memory Center, 2026-06-11)
Recorded per the single-decision-log rule; full design + live-run findings in
`docs/ux-refactor/p3-memory-center-plan.md`.
1. **D2 SHIPPED in full.** Standalone `MemoryCenterApp` (ArtifactCenterApp shape, fully
controlled — URL is the only navigation authority): mind pills "About you" / "About this
work · {ws}" on the Memories view; all six legacy MemoryApp views survive as secondary
tabs (Timeline extracted verbatim to `memory/TimelineTab.tsx`; `MemoryApp.tsx` retired —
capability preserved, entry restructured). `/memory/:mindScope` + `?tab=` implemented
(conversion plan §5.3 #1-2 closed); `?filter=` J08 stash unchanged. S02-FR2 Memory part
closed: WorkspaceDesktop memory tab embeds the per-mind list (`consumeDeepLinks=false` so
the J08 stash stays with the /memory route).
2. **Server contract (additive):** `GET /api/memory?mind=personal|workspace` selects one
store; invalid mind or workspace-less `mind=workspace` is a 400 (a typo must not silently
become the merge view); omitted mind keeps the legacy merge (pinned). Workspace-mind
mutations now carry `workspace` from the FE — without it, PATCH/archive/delete/merge
missed the workspace store entirely (404 class, fixed + pinned).
3. **Cross-mind id-collision class:** per-mind SQLite autoincrements collide; the split makes
every view single-mind (mutation ambiguity structurally gone from the new UI); selection +
list clear on mind switch (cross-mind merge / stale-rows-under-wrong-pill pins). Full id
namespacing remains post-launch.
4. **Live-run defects fixed (pre-existing, surfaced by the mandatory smoke):**
KnowledgeGraphViewer crashed the surface on untyped entities (54/214 real rows; fixed via
single-entry node normalization, 'unknown' legend chip); Timeline duplicated React keys on
cross-mind id 36 (fixed via mind-qualified keys).
---
## P4 implementation notes (D11 + D12 + clean-install onboarding, 2026-06-11)
Recorded per the single-decision-log rule; full record in
`docs/ux-refactor/p4-launch-integrity-record.md`.
1. **D11 SHIPPED.** `resolveDataDir()` = option > `WAGGLE_DATA_DIR` > `~/.waggle` (split-brain with
installer/marketplace/memory-mcp closed); the ratified one-line startup log
`Data dir: <resolved> · tier: <effective>` via `readTierFromDataDir` (extracted; same
config.json + getEffectiveTier contract as `GET /api/tier`); both stale SOLO comments fixed.
Live-verified: env-pointed boot logged the tmp dir + tier FREE.
2. **D12 SHIPPED — preferred shape (generation + untracking).** `service.js`/`.map` untracked +
gitignored; `tauri.conf.json` `beforeBuildCommand` owns the full prep chain so a raw
`npx tauri build` ships a CURRENT server (previously: the April copy). Dev mode unaffected
(service.rs debug branch spawns service.ts via tsx). Pinned in tauri-config.test.ts.
3. **S4 founder flag RESOLVED — the clean-install skip was REAL.** `ensureDefault()` at boot +
the `getWorkspaces().length > 0` auto-complete evidence meant brand-new production users never
saw the wizard. Fix: server-authoritative `GET /api/onboarding/status` (completion flag
`<dataDir>/first-launch.flag` — same file as the Tauri IPC stamp — OR legacy evidence: any
personal-mind frame / >1 workspaces; the seeded stub is NOT evidence) +
`POST /api/onboarding/complete` stamped from `useOnboarding.update()` on completion. Fail
direction: toward showing the wizard. Live-verified clean dataDir → `completed:false`.
Accepted edge: a pre-flag returning user with zero frames + only the default workspace re-sees
the wizard once (no durable signal can distinguish them; class dies as flags stamp).
4. **FREE→Upgrade e2e re-ran:** Act 4 Tier Wall 6/6 on a fresh FREE install under
`WAGGLE_TRUST_LOCALHOST=1`; the unauthenticated first run's 3 failures are the documented
dock-era-spec-vs-P1b-bearer-gate class — spec-side token wiring stays ledgered with the P7 e2e
band.
5. **Two-round adversarial review (19 confirmed total / 34 refuted) — all confirmed findings
fixed,** headlined by: a HIGH in P4's own first cut (the D12 hook re-ran arch-parameterized
bundle scripts arch-blind — cross-arch macOS release legs would ship a non-launching Intel DMG;
hook trimmed to the arch-independent sidecar bundle + a fail-loud resources preflight); a
verified MED chain where the wizard's own step-1 profile write counted as returning-user
evidence (server-durable PENDING latch added — only explicit completion flips status once a
dataDir is identified as un-onboarded); the Tauri fs-flag now honors `WAGGLE_DATA_DIR` (Rust)
so the IPC fast-path and the server stamp share one file on every install shape; and the
sidecar bundle now compiles `@waggle/shared`/`@waggle/hive-mind-core` from SOURCE (esbuild
alias — the regenerated bundle used to embed stale gitignored dist silently). Full dispositions:
`docs/ux-refactor/p4-launch-integrity-record.md`.

202
docs/ux-refactor/deltas/rbac-security-delta.md Normal file
View File

@@ -0,0 +1,202 @@
# RBAC / Security / Audit Delta — Waggle OS UX Refactor
**Scope:** PRD §17 (RBAC & Permissions) + §18 (Security, Privacy, Compliance) + Blueprint "Architecture Package 8: Security Model".
**Execution model:** in-place incremental refactor of `apps/web` + targeted backend extensions (locked). Reuse `install-audit`, `ai_interactions`, `audit_events`, `teams.db`, `confirmation.ts`, `trust-model.ts`, `capability-governance`.
**Grounding:** every claim cites a real file/line. Backend-map sections 03c (workspace/team) and 03e (evolution/governance) are the contract reference.
---
## 0. TL;DR for the planner
The security substrate is **substantially built on the agent/runtime side and the local sidecar**, but the RBAC story is **split across two incompatible planes** and the UI surfaces barely exist.
| Capability | Built? | Where |
|---|---|---|
| Tool approval gate (write/destructive/connector) | ✅ Strong | `packages/agent/src/confirmation.ts` |
| Tiered autonomy (normal/trusted/yolo) | ✅ | `confirmation.ts` `needsConfirmationWithAutonomy` |
| Approval inbox + persistent grants | ✅ | `chat.ts` + `/api/approval/*` (03e §8) |
| Risk/trust classification for installs | ✅ | `packages/agent/src/trust-model.ts` |
| Install audit trail (append-only-ish) | ⚠️ Real table, **NOT** trigger-protected | `packages/core/src/install-audit.ts` |
| AI interaction audit (append-only, EU AI Act) | ✅ Trigger-protected | `compliance/interaction-store.ts` + schema triggers |
| Generic action audit (`audit_events`) | ⚠️ Real, **NOT** trigger-protected | `local/routes/events.ts` |
| RBAC role model (Owner/Admin/Member/Viewer) | ⚠️ **Two** divergent impls | `local/routes/team.ts` vs `routes/capability-governance.ts` |
| RBAC role **Guest** | ❌ Not in any schema | — |
| RBAC enforced at API layer | ⚠️ Local: ad-hoc per route; Cloud: `fastify.authenticate` | — |
| RBAC UI (member mgmt, role matrix, audit views) | ❌ Effectively none | — |
| Memory-import consent (preview → commit) | ✅ Backend; UI partial | `local/routes/harvest.ts` |
**Biggest risk:** the PRD's 5-role table (Owner/Admin/Contributor/Viewer + Blueprint's Guest) must be unified onto **one** role enum and **one** enforcement path. Today the local sidecar (`teams.db`) and the cloud Teams server (`capability-governance`) have separate role enums, separate role hierarchies, and separate enforcement primitives. Picking one is a §17 prerequisite, not a UI detail.
---
## 1. RBAC — current vs. required
### 1.1 PRD/Blueprint target
PRD §17.2 defines **Owner / Admin / Contributor / Viewer**. The Blueprint security model (line 156) and acceptance criteria (line 603) instead say **Owner / Admin / Member / Viewer / Guest**. These two source documents **disagree on role names** ("Contributor" vs "Member") and on whether "Guest" exists. PRD §24 (mockups directional) plus "PRD acceptance criteria win" means: the implementation must reconcile to a single enum. Recommendation: adopt the Blueprint 5-role set **Owner/Admin/Member/Viewer/Guest** because it is the superset and is already partly encoded in the local schema; map PRD "Contributor" → "Member".
PRD §17.3 permission principles (must hold):
- Agents inherit **minimum** permissions of assigned scope.
- MCPs require explicit scope (personal/workspace/team).
- Connectors require consent + revocation path.
- Automations only run actions allowed by the user/team role.
- Shared memories/artifacts display scope + access.
- **Elevated actions require human approval.**
### 1.2 What exists — TWO RBAC planes
**Plane A — Local sidecar (`teams.db`), the one the desktop frontend actually hits.**
`packages/server/src/local/routes/team.ts`:
- Schema (lines 61–73): `team_members.role CHECK (role IN ('owner','admin','member','viewer'))`. **No `guest`.**
- Enforcement is **ad-hoc, inline, per-route** (not middleware):
- Update team → owner/admin (line 532)
- Delete team → **owner only** (line 558)
- Add member → owner/admin (line 591)
- Change role → **owner only** on `PUT` (line 624); owner/admin on `PATCH` (line 650) — *PRD note: PUT/PATCH divergence is a real inconsistency*
- Remove member → owner/admin (anyone) or self; **never the owner** (lines 677–684)
- Identity is a **single local user** (`getLocalUserId` → `'local-user'`, line 85–92). There is no real multi-user auth on this plane — it is loopback-trust (backend-map 03c §5: "No auth header").
**Plane B — Cloud Teams server (`fastify.db`, Postgres-style), reached only via team-server proxy.**
`packages/server/src/routes/capability-governance.ts`:
- `ROLE_HIERARCHY = { member:1, admin:2, owner:3 }` (lines 6–10) — **numeric hierarchy, no viewer, no guest.**
- Real auth: every route has `preHandler: [fastify.authenticate]` and uses `request.userId`.
- `resolveTeam` checks membership → 403 "Not a member" (line 27–31); `requireAdmin` gates writes (line 36–43).
- This is where **capability policies / overrides / requests** live (per-role `allowedSources`, `blockedTools`, `approvalThreshold`) — the actual "Admin can install within policy" mechanism from PRD §17.2. Surfaced to the local app **read-only** via `GET /api/team/governance/permissions` (tier-gated ENTERPRISE, `team.ts` line 418).
> **Delta:** the two planes have **three** different role vocabularies (`owner/admin/member/viewer`, `member/admin/owner`, and the PRD's `Owner/Admin/Contributor/Viewer`), none of which has `Guest`. None enforce at a shared middleware. The capability-policy engine (the richest RBAC primitive) is cloud-only and the local app can only *read* it.
### 1.3 What must be built
1. **Single role enum** in `@waggle/shared` (`type TeamRole = 'owner'|'admin'|'member'|'viewer'|'guest'`). Migrate the `teams.db` CHECK constraint to add `guest`; add an explicit role→capability matrix matching PRD §17.2 (view/create/share/manage-people/install/manage-security columns).
2. **Shared enforcement helper** (`requireRole(min)` / `can(action, role, scope)`) used by both `local/routes/team.ts` (replace inline checks) and the cloud routes. Resolve the PUT/PATCH role-change divergence to one rule.
3. **Viewer/Guest read-only enforcement** — today `READONLY_TOOLS` + `PermissionManager.sandbox()` (`packages/agent/src/permissions.ts` lines 4–27) exist to lock an *agent* to read-only; reuse this primitive so a Viewer/Guest **session** assembles a sandboxed tool pool. This is the cleanest reuse: `isReadOnly` persona flag + role-driven `PermissionManager` whitelist.
4. **RBAC UI** (PRD §11.x Team Workspace, §20.3 "RBAC/Audit components"): member list with role dropdown (POST/PUT/PATCH/DELETE `/api/teams/:id/members*` already exist — 03c §1.3), invite flow (J13), "request access" on permission-denied (Blueprint J21, line 240), and the **role→capability matrix** as a readable table. None of this UI exists today.
---
## 2. Approval / consent gating — current vs. required
This is the **strongest** existing area. PRD §17.3 "elevated actions require human approval" and §18.1 "approval class for elevated/critical capabilities" are largely satisfied at runtime; the gap is UI consistency and a couple of surface flows.
### 2.1 The runtime approval gate (built)
`packages/agent/src/confirmation.ts`:
- `needsConfirmation(toolName, args)` (line 73) — gates writes (`write_file`, `edit_file`, git push/commit/pr/merge, `install_capability`, cross-workspace reads — `ALWAYS_CONFIRM` line 13), connector **writes** (name-derived, never trusts LLM args — line 76), and destructive bash (`DESTRUCTIVE_BASH_PATTERNS` line 35 + chain-operator bypass defense line 66).
- `getApprovalClass()` (line 122) → `standard|elevated|critical`.
- `needsConfirmationWithAutonomy(tool, args, level)` (line 224) — tiered autonomy: `normal|trusted|yolo` with a **critical-never-autopass blacklist** (`isCriticalNeverAutopass`, line 192) that holds even at YOLO (`rm -rf /`, `sudo`, force-push to main, etc.).
### 2.2 How it hooks into the loop (built)
`packages/server/src/local/routes/chat.ts` registers a **per-request `pre:tool` hook** (line 881):
- Reads effective `autonomyLevel` from permission settings (with expired-grant fallback to `normal`, line 363).
- `needsConfirmationWithAutonomy` decides; auto-pass at trusted/yolo emits `approval_auto` audit (line 902).
- **Persistent grants:** `server.agentState.approvalGrantStore.has(tool, args, workspaceId)` (line 921) silently resolves previously "always allowed" `(tool, args, sourceWorkspaceId)` triples.
- Otherwise: computes a `trust` assessment, sends an `approval_required` SSE event (line 959) with `approvalClass`, parks the call in `server.agentState.pendingApprovals` (line 975), and **audits** `approval_requested` / `approval_granted` / `approval_denied` (lines 967, 994, 998).
- Inbox + grants API: `/api/approval/:requestId`, `/api/approval/pending`, `/api/approval/grants*` (backend-map 03e §8).
> The approval/consent flow for **agent elevated actions** (PRD Journey 15, Blueprint J21) is therefore **fully wired backend-side**. The reusable hook point for the new UI is the `approval_required` SSE event + `GET /api/approval/pending` on reconnect.
### 2.3 The three PRD consent flows — where each hooks
| PRD consent flow | Backend status | Hook point | UI delta |
|---|---|---|---|
| **Memory import** (no import without review/approval — §18.2, J01/J08) | ✅ Two-phase exists: `POST /api/harvest/preview` → `POST /api/harvest/commit` (`local/routes/harvest.ts` lines 1–9; preview cap line 49). Identity suggestions stage to profile awaiting review (`IdentitySuggestion`, 03c §2.10). | preview/commit split + `harvest_sources` provenance | **Memory Review screen** (PRD §12.12 step 5) must render preview diff + per-item approve/edit/reject before calling commit. Low-confidence review queue (J08) needs the confidence fields PRD §15.4 recommends adding. |
| **Connector / MCP install** (consent + revocation — §17.3, J10/J11) | ✅ Risk classified by `trust-model.ts` `assessTrust` (line 318) → `riskLevel/approvalClass/permissions`. Install writes audit via `server.auditStore.record(...)` (marketplace.ts lines 224–308; skills.ts 212/315/475). Approval routed through the §2.2 gate (`install_capability` is in `ALWAYS_CONFIRM`). | `auditStore.record` + approval gate + `getApprovalClass` | **Connector Hub / MCP Hub install modal** (PRD §12.7/§12.8) must show the `TrustAssessment` (risk badge, permission summary, source label via `formatTrustSummary` line 392) and a **revoke** action. Revoke endpoints exist (`/api/connectors/:id/revoke`, `/api/mcps/:id/revoke` — PRD §16.9) but the audit "revoked" action and UI are gaps. |
| **Agent elevated action** (permission prompt — §17.3, J15) | ✅ Fully wired (§2.2). | `approval_required` SSE + `/api/approval/*` | **ApprovalModal** component (Blueprint line 488) — render `approvalClass`, tool + args, [Approve][Deny][Always allow]. Inbox view for `/api/approval/pending`. Today the approval UX is minimal/inline. |
### 2.4 What must be built (approval)
- **Unified ApprovalModal + Approvals Inbox** components consuming the existing SSE event + `/api/approval/*` + `/api/approval/grants*`. (Design-system component "ApprovalModal" is named in Blueprint line 488 but not implemented in the new IA.)
- **Autonomy selector UI** wired to `GET/PUT /api/settings/permissions` (`defaultAutonomy: normal|trusted|yolo` — 03c §2.8) with per-workspace overrides surfaced.
- **Revoke + "revoked" audit action** for connectors/MCPs (close the audit verb gap — `AuditAction` already includes `rejected/blocked` but not an explicit `revoked`; either add it or record as `rejected` with a detail).
---
## 3. Audit surfaces — current vs. required
PRD §18.1: "Append-only audit for AI interactions and sensitive actions." §18.3: "Audit logs should be immutable or append-only where feasible." There are **three distinct audit stores** today, with **inconsistent append-only guarantees**.
### 3.1 The three stores (all real, all SQLite)
| Store | Table | File | Append-only? | Purpose |
|---|---|---|---|---|
| **AI Interaction log** | `ai_interactions` (personal `.mind`) | `packages/core/src/compliance/interaction-store.ts` | ✅ **Yes** — `BEFORE UPDATE`/`BEFORE DELETE` triggers `RAISE(ABORT,...)` (`hive-mind-core/src/mind/schema.ts` lines 187–195) | EU AI Act Art. 12: model/provider/tokens/cost/tools/**inputText/outputText**/humanAction/riskContext/persona. |
| **Install audit** | `install_audit` (personal `.mind`) | `packages/core/src/install-audit.ts` | ⚠️ **No triggers** — `record()` is insert-only by convention but DELETE/UPDATE are not blocked; `clear()` exists (line 153) | Capability install trust trail: type/source/risk/trust_source/approval_class/action/initiator. |
| **Action audit** | `audit_events` (`audit.db`) | `packages/server/src/local/routes/events.ts` | ⚠️ **No triggers** — `pruneAuditEvents` deletes by age (line ~168) | Generic events: `tool_call`, `memory_write/delete`, `workspace_*`, `session_*`, `approval_*`, `export`, `cron_trigger`, `data_erase_requested` (lines 21–37). |
### 3.2 Deltas vs PRD §18
1. **Append-only consistency.** PRD wants AI interactions **and** sensitive actions append-only. Only `ai_interactions` is trigger-protected. To honor §18.1, add `BEFORE UPDATE/BEFORE DELETE → RAISE(ABORT)` triggers (or a tombstone column) to `install_audit` and to the sensitive subset of `audit_events` (`approval_*`, `memory_delete`, `workspace_delete`, `export`, `data_erase_requested`). The `pruneAuditEvents` retention sweep must then be reconciled with "append-only" (retention vs immutability is a real tension — resolve per §18.3 "where feasible", likely a tombstone/archive rather than hard delete for the sensitive subset).
2. **`install_audit` risk-level drift (latent bug).** The TS type `AuditRiskLevel` allows `'critical'` (install-audit.ts line 16) but the table `CHECK (risk_level IN ('low','medium','high'))` (line 65) **rejects** `'critical'`. Recording a critical install would throw. The file's own comment (lines 59–61) warns CHECK lists must stay in sync. **Fix before exposing the install-audit UI** (PRD §12.13, Sprint 7 "Install audit UI").
3. **Audit-event `userId` is unpopulated** on the local plane (single-user model). For the team audit views (PRD §11.5, J13) the `user_id` column exists (events.ts line 43/72) but nothing fills it. Wiring real `userId` is blocked on the unified-auth decision (§1).
### 3.3 Audit read/export surfaces (built)
- `GET /api/admin/audit-export?format=json|csv&from=&to=` — **TEAMS-gated** (settings.ts line 484, 03c §1.5). Reads `auditStore` (install_audit).
- `GET /api/teams/:id/activity` — aggregates `audit_events` across a team's workspaces (team.ts line 690, 03c §1.3).
- `GET /api/compliance/status` + `POST /api/compliance/export[-pdf]` — EU AI Act per-article report from `ai_interactions` (03e §5; `interaction-store.ts` `getOversightLog` line 144, `getModelInventory` line 116).
- TeamSync **pushes** audit events to the cloud team server fire-and-forget (events.ts lines 132–143).
### 3.4 What must be built (audit UI)
- **Audit Views** (PRD §11.5/§20.3, Blueprint "export audit" J24 line 249): a unified activity/audit feed that merges the three stores by scope (workspace/team) with filters (event type, actor, date) and CSV/PDF export buttons calling the existing endpoints. The data is there; the read-model needs a thin normalizer because the three tables have different columns.
- **Compliance app** surface (PRD §18.3, EU AI Act) — already has full backend (03e §5) incl. PDF; needs the per-article status cards + report-template CRUD UI.
- **Right-to-delete UX** (§18.2 archive/delete memory; `data_erase_requested` event already defined) + telemetry clear (`DELETE /api/telemetry/events`, 03e §4).
---
## 4. Cross-cutting security deltas (PRD §18.1)
| §18.1 requirement | Status | Note |
|---|---|---|
| Local-first storage default | ✅ | All persistence local (SQLite/JSON), backend-map 03c §3. |
| User-controlled sync/sharing | ⚠️ | Cloud-sync toggle TEAMS-gated (03c §1.5); per-object share (`POST /api/share`, PRD §16.11) UI absent. |
| Workspace-level isolation | ✅ | Per-workspace `*.mind`; `crossWorkspaceHints` permanently disabled for privacy (03c §5). Cross-workspace tools are approval-gated (confirmation.ts line 17). |
| Team RBAC | ⚠️ | Split planes — see §1. |
| Connector/MCP install audit | ✅ | `install_audit` + `trust-model` (see §2.3, §3). |
| Agent permission declarations | ⚠️ | Persona `tools`/`disallowedTools`/`isReadOnly` exist (CLAUDE.md §5); PRD §15.5 agent `permissions`/`memoryScopes` fields not yet a first-class persisted object. Agent Builder (PRD §12.9) must render+persist these. |
| Append-only audit | ⚠️ | Only `ai_interactions` (see §3.2). |
| Approval class for elevated/critical | ✅ | `getApprovalClass` / `trust-model` (§2). |
| Clear revoke/delete/export | ⚠️ | Endpoints mostly exist; UI is the gap. |
| Injection defense on external input | ✅ (must preserve) | `scanForInjection()` (CLAUDE.md §7.2) — connector/harvest input must keep calling it. |
| Secrets vault-only, masked | ✅ | API keys → encrypted vault, masked on read (03c §2.7). |
---
## 5. Recommended build order (security slice of the refactor)
1. **Decide the auth/identity model** (single-user local vs. real multi-user). Everything in §1 and the `userId` audit gap blocks on this. Minimum-viable per PRD Open Question §23.7: keep loopback single-user locally; treat cloud Teams server as the multi-user authority; the local app **mirrors** roles from the cloud `capability-governance` policies (read path already exists).
2. **Unify the role enum** in `@waggle/shared` (add `guest`; map Contributor→Member) + **shared `requireRole`/`can()` helper**; refactor `team.ts` inline checks and cloud routes onto it. Migrate `teams.db` CHECK.
3. **Fix `install_audit` risk-level CHECK drift** (§3.2.2) before any install-audit UI.
4. **Add append-only triggers** to `install_audit` + sensitive `audit_events` subset (§3.2.1), reconcile with retention.
5. **Build shared security components** (Blueprint line 488): `ApprovalModal`, role→capability **matrix** table, `EvidencePanel`, audit-feed normalizer. Wire to existing endpoints.
6. **Wire the three consent flows' UIs** (§2.3): Memory Review, Connector/MCP install-with-trust-assessment, Approvals Inbox.
7. **Role-driven read-only sandbox** for Viewer/Guest sessions via the existing `PermissionManager.sandbox()` + `READONLY_TOOLS` primitive (§1.3.3).
---
## 6. Reuse map (don't rebuild)
| Need | Reuse | File |
|---|---|---|
| Tool approval decision | `needsConfirmation` / `needsConfirmationWithAutonomy` / `getApprovalClass` | `packages/agent/src/confirmation.ts` |
| Install risk + permission summary | `assessTrust` / `formatTrustSummary` / `resolveTrustSource` | `packages/agent/src/trust-model.ts` |
| Read-only lockdown | `PermissionManager.sandbox()` + `READONLY_TOOLS` | `packages/agent/src/permissions.ts` |
| Install audit trail | `InstallAuditStore` | `packages/core/src/install-audit.ts` |
| AI-interaction audit (append-only) | `InteractionStore` + schema triggers | `packages/core/src/compliance/interaction-store.ts`, `hive-mind-core/src/mind/schema.ts:187` |
| Generic action audit | `emitAuditEvent` / `getAuditDb` | `packages/server/src/local/routes/events.ts` |
| Local team RBAC CRUD | `teamRoutes` | `packages/server/src/local/routes/team.ts` |
| Cloud capability governance (policies/overrides/requests) | `capabilityGovernanceRoutes` + `TeamCapabilityGovernance` | `packages/server/src/routes/capability-governance.ts` |
| Approval inbox + grants | `pendingApprovals` map + `approvalGrantStore` + `/api/approval/*` | `packages/server/src/local/routes/chat.ts` + `approval.ts` |
| Memory-import consent | `harvest/preview` → `harvest/commit` | `packages/server/src/local/routes/harvest.ts` |
| EU AI Act compliance report | `ComplianceStatusChecker` / `ReportGenerator` | `packages/core/src/compliance/*` |
---
## 7. Open questions for the founder/PM
1. **Role name reconciliation:** confirm Owner/Admin/**Member**/Viewer/Guest (Blueprint superset) over PRD §17.2's "Contributor". (Recommended.)
2. **Identity model (§23.7):** single-user-local + cloud-authoritative-multi-user, or real local accounts? Gates the audit `userId` and §1 enforcement.
3. **Append-only vs retention (§18.3):** for the sensitive `audit_events` subset, hard append-only (no prune) or tombstone-on-prune? EU buyers will ask.
4. **Guest scope:** Blueprint says "limited shared artifacts/memory; no agents/MCP" — confirm Guest gets a `PermissionManager.sandbox()` read-only session.
5. **Capability-policy reach:** should the rich cloud policy engine (allowedSources/blockedTools/approvalThreshold per role) be brought down to the **local** plane, or stay cloud-only with the local app reading it (current state)?

418
docs/ux-refactor/deltas/shared-types-delta.md Normal file
View File

@@ -0,0 +1,418 @@
# Shared Types Delta — UX Refactor
> Source of truth: PRD §15.2-15.6 (`docs/Waggle_OS_UX_Refactor_Master_Handoff_Package/Waggle_OS_UX_Refactor_PRD.md:942-1056`).
> Grounded against `apps/web/src/lib/types.ts`, `packages/shared/src/types.ts`, `packages/shared/src/mcp-catalog.ts`,
> `packages/hive-mind-core/src/mind/frames.ts`, and `docs/ux-refactor/_inventory/substrate-types.md`.
> Execution model is **in-place incremental refactor**: extend existing types, do not replace. NEW vs MODIFY is
> called out per type, with the current type cited.
---
## 0. Placement policy (where each type lives)
Two TS surfaces matter:
- **`packages/shared/src/types.ts`** — server/sidecar + cross-package domain types. Already holds `User`, `Team`,
`AgentDef`, `Task`, `WaggleMessage`, `ConnectorDefinition`, `ConnectorHealth` (`packages/shared/src/types.ts:4-313`).
Anything the **sidecar route layer must produce/persist** (entities, API payload shapes, RBAC) goes here so the
server (`packages/server/src/local/routes/*`) and the FE import one definition.
- **`apps/web/src/lib/types.ts`** — FE display/view-model types. Already holds `Workspace`, `MemoryFrame`,
`Persona`, `SkillPack`, `CronJob`, `Connector` (`apps/web/src/lib/types.ts:22-336`). These are intentionally
**lossy projections** of the persisted shapes (substrate-inventory §(e), `_inventory/substrate-types.md:233-237`).
**Rule for this delta:**
1. The PRD §15.2 literal **enums/unions** are domain vocabulary → **`packages/shared`** (single source), then
re-exported / imported by the FE. Avoid duplicating the union string lists in two files (drift risk —
precedent: the `FrameSource` TS-vs-DB drift, `_inventory/substrate-types.md:120-121`).
2. **Persisted entity shapes** (WorkspaceConfigV2, Agent, Artifact, Skill, Automation, MCP) → **`packages/shared`**
(server owns persistence; `WorkspaceConfig` itself currently lives in
`packages/hive-mind-core/src/workspace-manager.ts:5-58`, not shared — see §1 note).
3. **FE view-models** that the screens actually render → **`apps/web/src/lib/types.ts`**, built FROM the shared
entity (e.g. FE `Memory` adds derived `relevance`/UI flags). Where a FE thin type already exists
(`SkillPack`, `Connector`, `Persona`, `CronJob`), MODIFY it rather than add a parallel type.
`@waggle/shared` is already imported by the FE (it ships `ConnectorDefinition` etc.), so importing shared enums into
`apps/web` is an existing, supported path.
---
## 1. §15.2 Enums / literal unions — **ALL NEW** → `packages/shared/src/types.ts`
None of these exist in either FE or shared today (`_inventory/substrate-types.md:218-229`). Add as a new
`// === UX-Refactor vocabulary (PRD §15.2) ===` block in `packages/shared/src/types.ts`. Use string-literal unions
(repo rule: prefer unions over `enum`, `rules/typescript/coding-style.md`).
```ts
// === UX-Refactor vocabulary (PRD §15.2) ===
export type WorkspaceType =
| 'project' | 'client' | 'research' | 'personal' | 'team' | 'organization';
export type Scope = 'personal' | 'workspace' | 'team' | 'organization';
export type Confidence = number; // 0-100
export type MemoryKind =
| 'fact' | 'decision' | 'task' | 'preference'
| 'strategy' | 'learning' | 'goal' | 'entity';
export type ArtifactKind =
| 'document' | 'presentation' | 'spreadsheet' | 'dashboard'
| 'research' | 'code' | 'media' | 'design' | 'other';
export type AgentType = 'personal' | 'workspace' | 'team' | 'autonomous';
export type AutonomyLevel = 'manual' | 'guided' | 'medium' | 'high';
export type ExtensionType =
| 'skill' | 'connector' | 'mcp' | 'model' | 'template' | 'external_tool';
```
**Consumed by screens:** `WorkspaceType` → Workspace Desktop header + switcher (§12.2). `Scope` → Memory Center
tabs/filters, MCP scope, Team sharing (§12.4, §12.8, §12.11, §17.1). `Confidence` → Memory confidence badge
(§12.4, §19.1). `MemoryKind` → Memory Center type filter (§12.4). `ArtifactKind` → Artifact Center categories
(§12.5). `AgentType` → Agent Center categories (§12.9). `AutonomyLevel` → Agent Builder (§12.9). `ExtensionType`
→ Ctrl+K "Extend" section + Extend/Marketplace (§12.3, §12.7-12.8).
> **Drift watch:** `MemoryKind` OVERLAPS but does not match the existing FE `MemoryFrame.type`
> (`apps/web/src/lib/types.ts:120` = `'fact'|'event'|'insight'|'decision'|'task'|'entity'`) and the DB `frame_type`
> (`I|P|B`, an orthogonal axis — `_inventory/substrate-types.md:128`). Do NOT delete FE `type`; map it. The
> backend has no `kind` column today — `kind` is heuristically derived
> (`packages/server/src/local/routes/workspace-state.ts:82-111`) and lands in `metadata` per §3.
---
## 2. §15.3 `WorkspaceConfigV2` — MODIFY (two layers)
### 2a. Persisted config — MODIFY `WorkspaceConfig`
**Current:** `WorkspaceConfig` in `packages/hive-mind-core/src/workspace-manager.ts:5-58` (the `workspace.json`
shape). It already carries `id, name, group, icon, model, personaId, templateId, tools, skills, storageType,
storagePath, teamId, teamRole, riskLevel, created` (full mapping: `_inventory/substrate-types.md:18-42`).
**7 additive optional fields needed** (all JSON-file, NO DB migration — `_inventory/substrate-types.md:49-55`):
`description?`, `type` (`WorkspaceType`), `status` (`'active'|'paused'|'archived'`), `agentIds?`, `connectorIds?`,
`mcpIds?`, `updatedAt`, `lastActiveAt?`. Also extend `CreateWorkspaceOptions`
(`workspace-manager.ts:60-95`) for `description/type`, and add two write-side touches: stamp `updatedAt` in
`update()` (`workspace-manager.ts:222`), stamp `lastActiveAt` from the chat/agent loop.
Defaults for existing workspaces: `type` derivable from `templateId`/`group`; `status` defaults `'active'`.
Keep all extra current fields (`personality`, `team`, `storageConfig`, `budget`, `tone`,
`optimizationEnabled`, `riskClassifiedAt` — `_inventory/substrate-types.md:44-47`).
> **NEW shared alias:** export an `interface WorkspaceConfigV2` in `packages/shared/src/types.ts` matching PRD
> §15.3 exactly, and have `workspace-manager.ts` `WorkspaceConfig extends WorkspaceConfigV2` (plus its legacy
> extras). This gives the route layer the PRD contract type without moving the persistence struct.
### 2b. FE view-model — MODIFY `Workspace`
**Current:** `Workspace` in `apps/web/src/lib/types.ts:22-40` — a lossy projection (`persona: string` not
`personaId`; derived `hue/memoryCount/sessionCount/lastActive/health/budget/shared`;
`_inventory/substrate-types.md:233-237`).
Add (optional, to stay backward-compatible with derived usage): `description?`, `type?: WorkspaceType`,
`status?: 'active'|'paused'|'archived'`, `agentIds?: string[]`, `connectorIds?: string[]`, `mcpIds?: string[]`,
`updatedAt?: string`. Keep `persona`; optionally add `personaId?` and migrate consumers. Import `WorkspaceType`
from `@waggle/shared`.
**Consumed by:** Home Cockpit workspace cards (§12.1), Workspace Desktop header + right panel (§12.2),
Workspace switcher (§19.1).
---
## 3. §15.4 Memory with confidence/provenance — MODIFY FE + NEW shared + backend metadata
### 3a. Backend storage — metadata-first (one migration)
`memory_frames` has **NO `metadata` column** and no `confidence/kind/title/tags/scope/sourceId/sourceUrl/
status/updatedAt` (`_inventory/substrate-types.md:125-164`). PRD §15.4 endorses metadata-first
(PRD:1013). Lowest-risk: one additive `ALTER TABLE memory_frames ADD COLUMN metadata TEXT NOT NULL DEFAULT '{}'`
(idempotent ADD-COLUMN pattern already used for `source` — `packages/hive-mind-core/src/mind/db.ts:116-124`),
storing `{kind, title, scope, sourceId, sourceUrl, confidence, tags, evidence, relatedMemoryIds,
relatedArtifactIds, status}` as JSON. Promote `confidence REAL` to a real indexed column later IF it becomes a
primary filter axis (§12.4 "filter by confidence"). Existing columns map directly: `content`→`content`,
`created_at`→`createdAt`, `last_accessed`→`lastAccessedAt`, `importance`→`importance`, `source`→`source`.
### 3b. NEW shared `Memory` entity → `packages/shared/src/types.ts`
The route layer normalizes the DB row + `metadata` into the PRD shape (current normalizer is
`normalizeFrame`, `packages/server/src/local/routes/memory.ts:230`). Define the contract type once:
```ts
export interface Memory {
id: string;
kind: MemoryKind;
title: string;
content: string;
scope: Scope;
workspaceId?: string;
teamId?: string | null;
source: string; // provenance class — maps from frames.source (FrameSource)
sourceId?: string | null;
sourceUrl?: string | null; // PRD "sourceUrl/path"
confidence?: Confidence; // 0-100
importance: 'critical' | 'important' | 'normal' | 'temporary' | 'deprecated';
evidence?: string[];
tags?: string[];
relatedMemoryIds?: string[];
relatedArtifactIds?: string[];
status: 'active' | 'low_confidence' | 'conflict' | 'deprecated' | 'archived' | 'trash';
createdAt: string;
updatedAt?: string;
lastAccessedAt?: string;
}
```
`importance` reuses the existing `Importance` union from `frames.ts:20`. `source` stays a string keyed off
`FrameSource` (`frames.ts:21`) rather than re-declaring the enum (avoid the existing TS-vs-DB drift). `status`
enumerates the §12.4 Memory states (PRD:504-513) — superset of `importance='deprecated'`.
### 3c. FE view-model — MODIFY `MemoryFrame` (or add `Memory`)
**Current:** `MemoryFrame` in `apps/web/src/lib/types.ts:118-127` (`id/type/title/content/importance:number/
timestamp/workspaceId/metadata?`). It does NOT match what `/api/memory/frames` returns — a real FE/BE
mismatch to reconcile (`_inventory/substrate-types.md:239-247`).
Recommended: introduce FE `interface Memory` aligned to the shared `Memory` (import the shared type and add
only FE-derived display fields, e.g. `relevance?: number`). Keep `MemoryFrame` temporarily for back-compat,
then migrate Memory Center components off it. Do NOT silently widen `MemoryFrame.type`.
**Consumed by:** Memory Center cards/detail/filters (confidence badge, source/evidence chips, status states,
graph) — §12.4, §19.1. Home Cockpit "memory highlights" (§12.1). Workspace Desktop memory widget (§12.2).
---
## 4. §15.6 Artifact — **NEW everywhere** (largest gap)
No `Artifact` type, no artifacts table, no `/api/artifacts*` routes — entirely greenfield
(`_inventory/substrate-types.md:259-266`). Closest existing is `FileEntry` (`apps/web/src/lib/types.ts:42-50`),
a raw filesystem entry, NOT an outcome object with relations — do NOT overload it.
### 4a. NEW shared `Artifact` → `packages/shared/src/types.ts`
```ts
export type ArtifactStatus = 'draft' | 'ready' | 'in_review' | 'final' | 'archived';
export interface Artifact {
id: string;
title: string;
kind: ArtifactKind;
workspaceId: string;
teamId?: string | null;
createdBy: string;
source: string; // agent | user | import | automation
status: ArtifactStatus;
mimeType?: string;
storagePath?: string;
previewUrl?: string;
tags?: string[];
relatedMemoryIds?: string[];
relatedSessionIds?: string[];
relatedTaskIds?: string[];
relatedAgentIds?: string[];
createdAt: string;
updatedAt: string;
}
```
Backend: NEW `artifacts` table in `packages/hive-mind-core/src/mind/schema.ts` (keep the two-place DDL-sync
discipline noted for `install_audit`, `_inventory/substrate-types.md:171-172`) + NEW `/api/artifacts/*` routes
(PRD §16.6).
### 4b. FE — NEW `Artifact` view-model → `apps/web/src/lib/types.ts`
Import or re-shape the shared `Artifact`. **Consumed by:** Artifact Center grid/detail panel + cross-object
"Germany GTM" search (§12.5, acceptance criteria PRD:532); Workspace Desktop "key artifacts" widget (§12.2);
Ctrl+K Search results (§12.3); `relatedArtifactIds` on Memory (§3) and Agent (§5).
---
## 5. §15.5 Agent — MODIFY shared `AgentDef` + NEW FE `Agent`
### 5a. Shared — MODIFY `AgentDef`
**Current:** `AgentDef` in `packages/shared/src/types.ts:36-47` (`id, userId, teamId, name, role, systemPrompt,
model, tools, config, createdAt`). MISSING vs §15.5: `type, goal, description, personaId, autonomyLevel,
workspaceIds, memoryScopes, skillIds, connectorIds, mcpIds, permissions, status, lastRunAt, successRate`
(`_inventory/substrate-types.md:249-257`).
Add as optional fields (keep `userId/role/systemPrompt/config` — existing callers depend on them):
```ts
type?: AgentType;
goal?: string;
description?: string;
personaId?: string;
autonomyLevel?: AutonomyLevel;
workspaceIds?: string[];
memoryScopes?: Scope[];
skillIds?: string[];
connectorIds?: string[];
mcpIds?: string[];
permissions?: string[];
status?: 'idle' | 'running' | 'paused' | 'error' | 'archived';
lastRunAt?: string;
successRate?: number; // 0-1; derivable from execution_traces.outcome (schema.ts:206) / procedures.success_rate (schema.ts:147)
```
`type/autonomyLevel/memoryScopes` import from the §1 unions (same file). Backend: agents are not yet a
first-class persisted entity with these fields — `/api/agents/*` CRUD+run is net-new (PRD §16.7,
`_inventory/substrate-types.md:283`).
### 5b. FE — NEW `Agent` view-model → `apps/web/src/lib/types.ts`
The FE today has only thin `Persona` (`:256-272`) and `AgentStatus` (`:249-254`) — no full Agent entity.
Add an `Agent` view-model (import the extended `AgentDef`, or a FE projection of it) carrying the card fields
the screens render: goal, status, owner, workspace, capabilities, model, successRate, lastRun.
**Consumed by:** Agent Center cards/categories + Agent Builder steps (§12.9); Workspace Desktop status bar
"agents running" (§12.2); Home Cockpit (§12.1); FleetSession already partially covers runtime
(`apps/web/src/lib/types.ts:220-228`).
---
## 6. §12.6 Skill — MODIFY FE `SkillPack` (or add `Skill`)
PRD §15.2 has no standalone Skill interface, but §12.6 enumerates skill object fields explicitly: `name,
description, category, instructions, inputs, outputs, tools/data, memory access, owner, status, usage,
last used` (PRD:541).
**Current:** FE `SkillPack` (`apps/web/src/lib/types.ts:210-218`: `id, name, description, category, skills[],
installed, trust`) — a marketplace *pack*, not a single authored skill. Backend anchor is `ParsedSkill`/
`SkillFrontmatter` (`packages/agent/src/skill-frontmatter.ts:53-56`).
Recommended: NEW `interface Skill` (don't overload the pack) → place the entity in `packages/shared` (so
`/api/skills/*` CRUD, PRD §16.8, can produce it), FE view-model in `apps/web/src/lib/types.ts`:
```ts
export interface Skill {
id: string;
name: string;
description: string;
category: string;
instructions?: string;
inputs?: string[];
outputs?: string[];
tools?: string[]; // "tools/data"
memoryScopes?: Scope[]; // "memory access"
owner?: string;
status: 'draft' | 'active' | 'archived';
usageCount?: number;
lastUsedAt?: string;
trust?: 'verified' | 'community' | 'experimental'; // reuse SkillPack.trust vocabulary
}
```
Keep `SkillPack` for the marketplace-pack grouping; relate via `SkillPack.skills: string[]` → `Skill.id`.
**Consumed by:** Skills Hub tabs + Skill Builder (§12.6); Agent Builder skill assignment (§12.9); Ctrl+K "Run"
(§12.3); Workspace `skills[]` (§2).
---
## 7. §12.10 Automation — MODIFY FE `CronJob` → NEW `Automation`
PRD has no §15 Automation interface, but §12.10 lists fields: `name, trigger, condition, actions, agent,
notification, schedule, workspace, status` (PRD:605).
**Current:** FE `CronJob` (`apps/web/src/lib/types.ts:230-238`: `id, name, schedule, workspaceId, enabled,
lastRun, nextRun`) — schedule-only, no trigger/condition/actions. Backend anchor is `CronSchedule`
(`packages/shared/src/types.ts:162-174`) + `cron-store.ts`.
Recommended: NEW `interface Automation` superset of CronJob (cron is one trigger type). Entity in
`packages/shared` (server owns `/api/automations/*`, PRD §16.10), FE view-model in `apps/web/src/lib/types.ts`:
```ts
export type AutomationTriggerType = 'schedule' | 'event' | 'manual';
export interface Automation {
id: string;
name: string;
triggerType: AutomationTriggerType;
schedule?: string; // cron expr when triggerType === 'schedule'
condition?: string;
actions: string[];
agentId?: string;
notify?: boolean;
workspaceId: string;
status: 'active' | 'paused' | 'running' | 'failed';
lastRun?: string;
nextRun?: string;
}
```
Keep `CronJob` for the existing cron UI; `Automation` with `triggerType:'schedule'` projects onto it.
**Consumed by:** Automation Center tabs + Automation Builder (§12.10); Home Cockpit overnight/attention
(§12.1); Workspace Desktop status bar "automations active" (§12.2).
---
## 8. §12.7-12.8 Extension / Connector / MCP — MODIFY existing
### 8a. Connector — MODIFY FE `Connector`, reuse shared `ConnectorDefinition`
**Current shared (rich, keep):** `ConnectorDefinition` + `ConnectorHealth` + `ConnectorCredential` +
`ConnectorStatus` (`packages/shared/src/types.ts:249-313`) — already covers status, capabilities, category,
substrate, tools, setupGuide, lastSync via health. **Current FE (thin):** `Connector`
(`apps/web/src/lib/types.ts:280-285`: `id, name, type, status`).
Action: MODIFY the FE Connector Hub to consume the shared `ConnectorDefinition`/`ConnectorHealth` directly
(the FE already imports `@waggle/shared`), rather than the 4-field `Connector`. Optionally add `lastSyncAt?`,
`scope?: Scope` to `ConnectorHealth` for §12.7 "last sync" + §17.3 connector scope. **No new connector type
needed** — this is a consumption switch, not a new shape.
**Consumed by:** Connector Hub (§12.7), Ctrl+K Extend (§12.3), Workspace `connectorIds[]` (§2).
### 8b. MCP — NEW FE `McpInstance`, reuse shared `McpServer` catalog
**Current:** `McpServer` catalog entry in `packages/shared/src/mcp-catalog.ts:17-28` (`id, name, description,
author, category, url, installCmd, capabilities, official, logo`) — a *catalog* entry, not an *installed
instance* with runtime state. §12.8 needs installed-instance fields: `version, status, connected to, last
used, locality, risk, permissions, logs` (PRD:573).
Recommended: NEW `interface McpInstance` in `packages/shared` (installed-state, references catalog `id`):
```ts
export interface McpInstance {
id: string; // catalog McpServer.id
name: string;
version?: string;
status: 'installed' | 'running' | 'stopped' | 'error';
scope: Scope; // "locality": personal/workspace/team (§17.3)
connectedTo?: string[]; // workspace/agent ids
riskLevel?: 'low' | 'medium' | 'high' | 'critical';
permissions?: string[];
lastUsedAt?: string;
}
```
Install governance/audit already exists via `InstallAuditStore` + `AuditCapabilityType`
(`packages/core/src/install-audit.ts:22` includes `mcp|connector|skill|marketplace`) — the Extend view needs a
NEW `GET /api/extend/audit` read route (no write change; `_inventory/substrate-types.md:196-201`).
**Consumed by:** MCP Hub (§12.8), Ctrl+K Extend (§12.3), Workspace `mcpIds[]` (§2).
> **Flag (latent, pre-existing):** `AuditRiskLevel` TS includes `'critical'` but both DDL CHECKs allow only
> `low|medium|high` (`install-audit.ts:65`, `schema.ts:130`) — a `record({riskLevel:'critical'})` throws.
> `McpInstance.riskLevel` above includes `'critical'`; if it ever writes to audit, fix the CHECK first
> (`_inventory/substrate-types.md:202-207`).
---
## 9. §12.3 Command — NEW everywhere → `packages/shared` + FE
Command Center (Ctrl+K) needs a result/command shape (§12.3, §16.3 `/api/command/*` all net-new,
`_inventory/substrate-types.md:282`). No existing type.
NEW shared `Command` + `CommandResult`:
```ts
export type CommandCategory = 'search' | 'launch' | 'create' | 'run' | 'navigate' | 'extend';
export type CommandResultType =
| 'workspace' | 'memory' | 'artifact' | 'session' | 'person'
| 'agent' | 'skill' | 'command' | 'connector' | 'mcp' | 'automation';
export interface CommandResult {
id: string;
type: CommandResultType;
title: string;
subtitle?: string;
category: CommandCategory;
icon?: string;
requiresApproval?: boolean; // §12.3 permission-gated → approval prompt
action?: { route?: string; endpoint?: string; payload?: Record<string, unknown> };
}
```
`CommandResultType` deliberately spans every searchable object class (§12.3 FR "search across workspaces,
memory, artifacts, sessions, people, agents, skills, commands, connectors, MCPs"). FE imports these for the
command palette and result grouping.
**Consumed by:** Command Center (Ctrl+K) (§12.3) — the only consumer, but cross-cutting (it indexes every entity).
---
## 10. Summary table
| Type | NEW / MODIFY | Current (cite) | Lives in | Primary screens |
|---|---|---|---|---|
| §15.2 unions (8) | **NEW** | none (`_inventory:218-229`) | `packages/shared/src/types.ts` | all (vocabulary) |
| `WorkspaceConfigV2` | MODIFY | `workspace-manager.ts:5-58` + FE `Workspace` `types.ts:22-40` | shared (alias) + hive-mind-core (struct) + FE | §12.1, §12.2, switcher |
| `Memory` (+confidence/provenance) | MODIFY FE / NEW shared / +metadata col | FE `MemoryFrame` `types.ts:118-127`; `memory_frames` no metadata col (`_inventory:150-153`) | shared entity + FE view-model + DB migration | §12.4, §12.1, §12.2 |
| `Artifact` | **NEW** (all layers) | none (`_inventory:259-266`) | shared + DB table + FE | §12.5, §12.2, §12.3 |
| `Agent` | MODIFY shared / NEW FE | `AgentDef` `shared/types.ts:36-47` | shared (extend) + FE view-model | §12.9, §12.2 |
| `Skill` | MODIFY FE / NEW shared | FE `SkillPack` `types.ts:210-218`; `ParsedSkill` `skill-frontmatter.ts:53` | shared + FE | §12.6, §12.9 |
| `Automation` | MODIFY FE / NEW shared | FE `CronJob` `types.ts:230-238`; `CronSchedule` `shared:162-174` | shared + FE | §12.10, §12.1 |
| Connector | MODIFY (consume existing) | FE `Connector` `types.ts:280-285`; shared `ConnectorDefinition` `:276-302` | reuse shared | §12.7 |
| `McpInstance` | **NEW** (instance) | catalog `McpServer` `mcp-catalog.ts:17-28` | shared + FE | §12.8 |
| `Command`/`CommandResult` | **NEW** | none | shared + FE | §12.3 |
**Migration footprint:** WorkspaceConfigV2 = JSON-file only (no DB). Memory = 1 idempotent `ADD COLUMN metadata`.
Artifact = 1 new table + routes. Everything else is TS-type + route work (server CRUD net-new per PRD §16). No
literal-union duplication across files — enums live once in `packages/shared` and the FE imports them.

269
docs/ux-refactor/gap-cards/S00-appshell-ia.md Normal file
View File

@@ -0,0 +1,269 @@
# Gap Card — S00 · AppShell + Information Architecture + Navigation
> Screen ID: **S00** · UX-refactor planning track · grounded in live `apps/web/src` + `packages/*`.
> Execution model is **LOCKED**: in-place incremental refactor of the existing shell, not a rebuild.
> PRD = `docs/Waggle_OS_UX_Refactor_Master_Handoff_Package/Waggle_OS_UX_Refactor_PRD.md`.
> Disposition: **rework** (the shell exists and is strong; it is reframed + extended, not recreated).
---
## 1. Screen & purpose
S00 is the **application chrome and navigation spine** that every other screen mounts inside — it is
not a "screen" the user opens, it is the frame they always see. PRD §1 names the spine: Home Cockpit,
Workspace Desktop, Command Center (Ctrl+K), visible Memory, Extend layer, Team. S00 is the layer that
makes that spine reachable.
Per the blueprint Developer Handoff (`_blueprint_extracted.txt:498`), **AppShell** = "Global route
layout, sidebar, active workspace, top status, command palette provider." Its responsibilities:
- Persistent top status bar (workspace, model, memory trophy, trial, search, notifications, clock).
- Primary navigation expressing the six IA layers (PRD §10: Global / Work / Intelligence / Extend /
Team / System) — blueprint `_blueprint_extracted.txt:68-81` + page-3 `06_board_all_in_one.png`.
- Global, always-available command layer (Ctrl+K) — PRD §12.3, §6.3.
- Active-workspace context held in a global store and threaded to every surface
(`_blueprint_extracted.txt:512`).
- The container for empty / loading / error / offline / permission-denied states (PRD §14.1).
**Purpose:** collapse the current 27-app "app-launcher" mental model into the IA spine
(PRD §3.2, §3.3, §20.4 "do not add more top-level apps without fitting IA"), without rebuilding
the windowed runtime that already works.
---
## 2. Required states (PRD / Blueprint)
S00 itself is mostly stateless chrome, but it **hosts** the global states and must render them:
- **Global states (PRD §14.1, blueprint AC `:604`):** Loading, Empty, Populated, Error,
Offline/local-only, Syncing, Permission denied, Partial data, Approval required — every screen
inside the shell must support these; the shell provides the offline indicator + error boundary +
approval modal mounts.
- **Navigation states:** active layer/route highlighted; active workspace shown in status; open vs
minimized window indicators (current dock dots).
- **Command Center states (PRD §12.3):** Idle, Query active, Grouped results, No results, Permission
prompt, Command success, Command failure.
- **Offline / local-only (PRD §6.7, §14.1; blueprint `:516`):** shell degrades connectors/MCPs
gracefully while keeping local workspace + memory reachable; offline badge in status bar.
- **First-run vs returning:** onboarding wizard replaces the shell entirely on first launch
(current behavior, see §3); returning users land in the populated shell.
- **Accessibility (PRD §19.3, blueprint `:489`):** keyboard-first, Ctrl+K + tab nav, visible focus,
non-color status, text labels on all badges.
Layout direction (blueprint `:483`, directional only): "Desktop-first, **left navigation**, central
workspace canvas, optional right context rail, Ctrl+K overlay." Note this conflicts with the current
**bottom-dock** shell — see Open Questions Q1 (the PRD acceptance criteria, not the mock, win:
PRD §24 risk row "Visual mocks overfit implementation").
---
## 3. Current state in repo (disposition: **rework**)
**There is no `AppShell` / `AppLayout` / `GlobalLayout` component** — grep over `apps/web/src` for
`AppShell|GlobalLayout|AppLayout` returns **zero matches**. The shell's responsibilities are spread
across these real files:
| File | What it does today |
|---|---|
| `apps/web/src/components/os/Desktop.tsx` | **The de-facto AppShell.** Root OS shell: wires all domain hooks, the window manager, `appConfig` (per-`AppId` title/icon/pos/size, `:77-102`), `renderAppContent` (the `switch(win.appId)` app router, `:276-363`), all overlays, theme observer, trial/tier fetch, onboarding early-return (`:262-273`), the `waggle:open-app` CustomEvent bus (`:162-169`). ~550 LOC. |
| `apps/web/src/components/os/StatusBar.tsx` | Top bar (PRD "top status"): logo, workspace name, focused-window label, model, memory-frame trophy, dev tokens/cost, trial badge, **Search button (Ctrl+K)**, notifications bell, offline indicator, clock. |
| `apps/web/src/components/os/Dock.tsx` + `lib/dock-tiers.ts` + `DockTray.tsx` | **The de-facto primary navigation.** Bottom dock, tier-filtered `DockEntry[]`, `zone-parent` flyouts (Ops, Extend) via portal-to-body `DockTray`, open/minimized dots, Spawn Agent, Waggle badge. `dock-tiers.ts` is the canonical `AppId` union + `getDockForTier()`. |
| `apps/web/src/components/os/AppWindow.tsx` | Draggable/resizable/snappable window chrome (one per open app). The "windowed runtime" — orthogonal to IA but the thing the IA must keep. |
| `apps/web/src/hooks/useWindowManager.ts` | Window state machine (`WindowState[]`, persisted to `localStorage waggle-window-state-v1`), `openApp(AppId)` / `openChatForWorkspace(...)`, focus/minimize/cycle. **Navigation == window ops, keyed by `AppId`, NOT by URL.** |
| `apps/web/src/hooks/useOverlayState.ts` | All overlay open/close flags (global search, switchers, notifications, etc.) — the global "command palette state / overlay state" store. |
| `apps/web/src/components/os/overlays/GlobalSearch.tsx` | **The de-facto Command Center (Ctrl+K).** Ctrl+K palette, 5 categories (`command\|workspace\|memory\|session\|skill`, `:15`), but built on a **static `COMMANDS[]` array (`:40-64`)** that is hand-synced to `appConfig` (drift warning in-file `:33-39`) — no Create/Run/Extend categories, no backend command index. |
| `apps/web/src/hooks/useKeyboardShortcuts.ts` | Binds global hotkeys (Ctrl+K search, persona/workspace switchers, new chat, window cycle). |
| `apps/web/src/lib/types.ts` | Holds the **stale** `AppView` union (8 ids, `:3-11`). |
| `apps/web/src/pages/Index.tsx` (route `/`) + `App.tsx` | Single-route app: `BrowserRouter` → `/` → `BootScreen` → `Desktop`. **No per-app routes exist** (frontend inventory `frontend.md:9-13`). |
**Key structural facts driving the rework (not a rebuild):**
1. **Single-route windowed desktop, not a navigable app.** "Navigation" is window management by
`AppId`. The blueprint's `/home,/workspaces,/memory,…` route groups (`:81`) and "left navigation"
(`:483`) are **directional**; the in-place model expresses the six IA layers through the existing
**dock-zone model** (`dock-tiers.ts` `zone-parent`) + window manager — NOT by introducing
react-router routes (PRD §20.2 "App surfaces -> Work/Intelligence/Extend categories";
§20.4 "Do not add more top-level apps without fitting IA").
2. **Dual app-id union drift (cleanup target).** `AppId` (27 ids, canonical, `dock-tiers.ts:7-13`)
vs `AppView` (8 ids, stale, `types.ts:3-11`). `AppView` is unused by the window manager. Dead ids
`terminal` / `calculator` / `notes` are declared in `AppId` but have **no component / no
`appConfig` entry** (Desktop `:77-102`) — dead.
3. **Three overlapping tier vocabularies** the IA gating must reconcile (frontend inventory
`frontend.md:376`): `UserTier` (UI density `simple\|professional\|power\|admin`, `dock-tiers.ts:15`),
`BillingTier` (`FREE\|TRIAL\|PRO\|TEAMS\|ENTERPRISE`, `:17`), and `PlanTier`
(`solo\|teams\|business\|enterprise` in `lib/feature-gates.ts`). Dock filters on
`UserTier` × `BillingTier` (`getDockForTier`, `:127`).
4. **Marketplace is doubly represented** (standalone `MarketplaceApp`, no dock entry, + a section
inside `CapabilitiesApp`) — an IA-consolidation point (frontend inventory `frontend.md:374`).
5. **IA→existing-app mapping already drafted** in `frontend.md:357-364` (Global/Work/Intelligence/
Extend/Team/System buckets → current apps). S00 hardens that mapping into dock zones + labels.
**Why rework, not create-new:** Desktop/Dock/StatusBar/AppWindow/window-manager are functional,
test-covered, and PRD §20.1 explicitly says keep+promote the substrate. The deliverable is an IA
**reframe** (zone labels, consolidation, union dedup, command-index wiring), not a new shell.
---
## 4. Frontend work
> Principle (CLAUDE.md §3.3 surgical changes): extend the existing shell. Do not introduce
> react-router app routes. Express IA through dock zones + a shared app catalog.
### 4a. Consolidate to one app catalog (kills the drift)
- **Rework `lib/dock-tiers.ts` into / beside a `lib/app-catalog.ts`** that is the single source for:
`AppId`, per-app metadata (title, icon, default pos/size — currently siloed in `Desktop.appConfig`
`:77-102`), IA-layer membership (`Work|Intelligence|Extend|Team|System|Global`), and tier gating.
Derive **both** `appConfig` (Desktop) and `COMMANDS[]` (GlobalSearch `:40-64`) and `DockEntry[]`
from it. Fixes FR #13 drift (called out in `GlobalSearch.tsx:33-39`).
- **Delete the stale `AppView` union** (`types.ts:3-11`) and the dead `terminal`/`calculator`/`notes`
ids from `AppId` (exhaustive grep first per CLAUDE.md §3.5 — they appear in `dock-tiers.ts`,
possibly tests).
### 4b. IA reframe of the dock (the "primary navigation")
- **Rework `TIER_DOCK_CONFIG`** (`dock-tiers.ts:82-105`) so the power-tier dock zones map 1:1 to the
PRD IA layers: today there are 2 zone-parents (`Ops`, `Extend`); the target is the six-layer IA
(`frontend.md:357-364` mapping). Likely outcome: rename/regroup into **Work** (Home, Chat, Memory,
Files/Artifacts, Sessions), **Intelligence** (Personas/Agents, Skills, Automations, Room/Mission
Control), **Extend** (Connectors, MCPs, Marketplace, AI Tools), **Team**, **System** (Settings,
Vault, Profile, Backup, Telemetry). Keep the existing `zone-parent` + `DockTray` mechanism.
- Resolve **Marketplace double-representation** — one canonical surface (Extend), remove the orphan.
- Keep tier filtering (`filterByBillingTier`, `:111`); reconcile the three tier vocabularies into one
gating helper (or document the mapping) as part of this card so downstream cards inherit it.
### 4c. Extract an explicit `AppShell` boundary (optional, low-risk)
- `Desktop.tsx` is ~550 LOC and conflates shell + router + state wiring (CLAUDE.md §3.2/§4 favor
smaller files). Optionally extract a thin `AppShell` that owns: status bar + dock + overlay mounts +
error boundary + offline state, leaving `Desktop` to own only the window manager + `renderAppContent`.
This is the component the blueprint names (`:498`). **Not required for behavior** — flag as a clean-up
the plan can sequence late.
### 4d. Command Center upgrade (Ctrl+K) — depends on backend §16.3 (see §5)
- **Rework `GlobalSearch.tsx`** from static-list + client fuzzy-match into a backend-fed command index:
add the PRD §12.3 category sections **Search / Launch / Create / Run / Navigate / Extend** (today only
command/workspace/memory/session/skill exist), federated over `/api/command/search` when present.
Reuse `fuzzyMatch` (`lib/fuzzy-match.ts`) as the offline fallback. Add the Command Center states
(§2). Keep the `onNavigate(type,id)` → `Desktop.handleSearchNavigate` (`Desktop.tsx:217-225`)
wiring; extend it for Create/Run/Extend dispatch.
### 4e. Global store for shell state (blueprint `:512`)
- Today shell state is scattered (`useWorkspaces`, `useOverlayState`, ad-hoc `Desktop` `useState` for
tier/trial/theme). Consolidate the **global** slice the blueprint names — `{ activeWorkspaceId,
command palette state, user profile, connection/offline status, feature flags }` — behind a single
provider/hook so Home/Workspace/Command surfaces read one source. Reuse `useOverlayState`,
`useWorkspaces`, `useOfflineStatus`, `useBilling`/`useFeatureGate` rather than replacing them.
**Reuse targets:** `Desktop.tsx`, `Dock.tsx`/`DockTray.tsx`/`dock-tiers.ts`, `StatusBar.tsx`,
`AppWindow.tsx`, `useWindowManager`, `useOverlayState`, `GlobalSearch.tsx`, `useKeyboardShortcuts`,
`ErrorBoundary.tsx`, `useOfflineStatus`, `useBilling`/`useFeatureGate`.
**Props/state:** `AppShell` (if extracted) takes no props (reads global store); the app catalog is a
pure module; `Dock` keeps its current props (`tier`, `billingTier`, `onOpenApp`, `openApps`,
`minimizedApps`, `onSpawnAgent`, `waggleBadgeCount`); `GlobalSearch` keeps `{open,onClose,onNavigate}`
plus internal async result groups.
**Adapter methods/hooks:** S00 chrome needs none beyond what exists. The Command Center upgrade
(4d) needs new adapter methods `commandSearch(q)` / `commandExecute(...)` / `commandRecent()` /
`commandSuggestions()` added to `lib/adapter.ts` (the one contract surface, `frontend.md:380`) once
the backend routes (§5) land.
---
## 5. Backend work
**S00 as pure shell/IA/navigation needs NO new backend** — it is frontend chrome + client-side
window routing. The dependency is the **Command Center (4d)**, which the IA spine requires
(PRD §6.3 "Ctrl+K always available"; blueprint `:515` "command index should unify workspaces, memory,
artifacts, sessions, agents, skills, connectors, MCPs, actions and recent commands").
PRD §16.3 Command Center endpoints (cross-ref `backend-routes.md:444-451`):
| PRD §16 endpoint | Status | EXTEND vs NET-NEW · substrate · note |
|---|---|---|
| `GET /api/command/search?q=` | **MISSING** | **NET-NEW** federating route. No `/api/command/*` exists; `commands.ts` is `/api/commands/execute` (slash-exec, different shape). Touches no new store — fans out over `/api/memory/search` (`memory.ts`), `WorkspaceManager.list()` (`workspaces.ts`), `/api/skills`, `/api/workspaces/:id/sessions/search` (`sessions.ts`). New `command.ts` route under `packages/server/src/local/routes/`. |
| `POST /api/command/execute` | **PARTIAL** | **EXTEND** `POST /api/commands/execute` (note **plural** `commands`, `commands.ts`). Current runs slash commands with a subset CommandContext; PRD's generic palette execute is broader (navigate/create/run/extend dispatch). Extend or add a thin singular alias. |
| `GET /api/command/recent` | **MISSING** | **NET-NEW** (or derive client-side from session/window history — defer to client first). |
| `GET /api/command/suggestions` | **MISSING** | **NET-NEW**. Closest analog `GET /api/skills/suggestions` (`skills.ts`, different domain) is a pattern to copy, not reuse. |
**No `.mind` migration for S00.** None of the Command Center routes add a data store
(`backend-routes.md:604-607`: every MISSING endpoint is buildable over existing substrates). The
status bar's memory trophy already uses `GET /api/memory/stats` (`StatusBar.tsx:40`), and trial/tier
uses `GET /api/tier` (`Desktop.tsx:136`) — both EXIST.
> Note: a command-index that searches "artifacts" (PRD §12.3) is blocked on the Artifacts domain
> (PRD §16.6, entirely MISSING — `backend-routes.md:477-484`). S00's Command Center can ship the
> existing object types first and add Artifacts/Agents/Automations groups as those screens land.
---
## 6. Shared types needed (PRD §15 vs `lib/types.ts`)
S00 is mostly literal-union + nav typing. PRD §15.2 target unions — **none currently exist** in
`apps/web/src/lib/types.ts` (substrate-types `substrate-types.md:218-229`):
- **Reframe the IA into types:** introduce a `IALayer = 'global'|'work'|'intelligence'|'extend'|
'team'|'system'` union and attach it to the app-catalog entry type (new, in `lib/app-catalog.ts`
or `dock-tiers.ts`). Not a PRD §15 type but the type that makes the IA explicit.
- **Delete `AppView`** (`types.ts:3-11`) — superseded by `AppId` (§4a). Consolidate exports so
`AppId`/`UserTier`/`BillingTier`/`DockEntry` (currently in `dock-tiers.ts`) and the catalog type
live in one place.
- **Command Center types (for 4d):** extend `SearchCategory` (`GlobalSearch.tsx:15`) beyond
the 5 current values to PRD §12.3's Search/Launch/Create/Run/Navigate/Extend; add a `Command`
result type (PRD §11 glossary "Command" object). Add a `CommandResult` interface used by both the
adapter method return and the palette.
- **Tier reconciliation type:** a single helper type mapping `UserTier`↔`BillingTier`↔`PlanTier`
(currently three vocabularies across `dock-tiers.ts` + `feature-gates.ts`). Document or unify so
every downstream gap card inherits one gating contract.
PRD §15.2 entity unions (`WorkspaceType`, `Scope`, `Confidence`, `MemoryKind`, `ArtifactKind`,
`AgentType`, `AutonomyLevel`, `ExtensionType`) are **owned by their respective screens**, not S00 —
S00 only needs the nav/command/tier types above. Establishing the shared-types module location is an
S00 responsibility (blueprint Phase 0 "Define shared frontend types", PRD §8 Phase 0).
---
## 7. Dependencies (screens/phases first)
- **Blocks everything.** S00 is PRD Phase 0 / blueprint Phase 0 ("Freeze UX spine: route names,
screen inventory, navigation, naming, data scopes", `_blueprint_extracted.txt:581`) and PRD §21
Sprint 1 ("AppShell navigation, route map, shared types, command provider skeleton"). Every other
gap card (Home Cockpit S0x, Workspace Desktop, Memory Center, Extend, Team) mounts inside this shell
and consumes the app catalog + IA layering + global store defined here.
- **Internal ordering:** 4a (app catalog / union dedup) → 4b (dock IA reframe) → 4e (global store)
can all ship **frontend-only, no backend**. 4d (Command Center upgrade) is gated on backend §5
`/api/command/*` (PRD §21 Sprint 3) — ship the Ctrl+K **skeleton + static/offline fallback** in
Phase 0/Sprint 1 (matches "command provider skeleton", PRD §21 Sprint 1), then wire the backend
index in Sprint 3.
- **Depends on no other screen.** Consumes only existing substrate (`GET /api/tier`,
`GET /api/memory/stats`, `GET /api/workspaces`) which all EXIST.
---
## 8. Effort: **L**
Frontend-heavy reframe touching the highest-traffic, highest-blast-radius files in the app
(`Desktop.tsx` ~550 LOC, `Dock.tsx`, `dock-tiers.ts`, `GlobalSearch.tsx`, window manager) plus a
union/tier-vocabulary consolidation that requires exhaustive grep (CLAUDE.md §3.5) and the net-new
`/api/command/*` federating route. Not XL because it reuses the working windowed runtime wholesale
(no rebuild) and adds no data store / migration. The Command Center backend index pushes it from M→L.
---
## 9. Open questions
1. **Bottom dock vs left navigation.** Blueprint `:483` + mock `06_board_all_in_one.png` show
**left navigation**; the live shell is a **bottom dock** (`Dock.tsx`). Mocks are directional
(PRD §24); does the founder want the dock reframed-in-place (cheaper, keeps the OS feel) or
migrated to a left rail (closer to mock, larger blast radius)? Recommend in-place dock reframe
unless the left rail is a hard requirement.
2. **Routes vs window-IDs.** Blueprint `:81` asks for `/home,/workspaces,…` route groups; the app
is single-route windowed. Confirm we keep `AppId`-keyed window navigation (recommended, in-place)
rather than introducing react-router app routes (larger change, conflicts with multi-window).
Deep-linking/back-button behavior is the only thing real routes would buy.
3. **Tier-vocabulary unification.** Three tiers (`UserTier`/`BillingTier`/`PlanTier`) gate the dock,
billing, and features independently. Should S00 unify them into one model now (clean but
cross-cutting), or just document the mapping and defer? PRD §17 RBAC roles add a 4th axis.
4. **Command Center scope for v1 (PRD §23 Q-implied).** Which object types ship in the Ctrl+K index
first? Artifacts/Agents/Automations are blocked on their domains (§5 note). Propose:
workspaces + memory + sessions + skills + commands at launch, add the rest as screens land.
5. **AppShell extraction now or later?** Pull the shell out of `Desktop.tsx` (4c) up front for a
clean boundary, or defer to a polish pass to minimize churn during the high-velocity refactor?

197
docs/ux-refactor/gap-cards/S01-home-cockpit.md Normal file
View File

@@ -0,0 +1,197 @@
# Gap Card — S01 Home Cockpit
> Execution model: **in-place incremental refactor** of `apps/web` + targeted backend extensions.
> PRD source of truth: §12.1 (lines 373-410), §15 (data model), §16.1 (API), §20.1 (keep/promote).
> Mockup `screen_01_home_cockpit.png` is **directional** — acceptance criteria win over pixels.
---
## 1. Screen & purpose
Home Cockpit is the **daily executive briefing and launch surface** — the first thing the user
sees after boot, before opening any workspace. PRD §12.1: "Give the user a useful daily briefing
and immediate next actions." Acceptance bar (§12.1): user understands the day in <30 s, continues a
workspace in one click, opens Ctrl+K from the keyboard, and captures a note/task/link/file from Home.
This is a **new top-level surface** in the IA spine (PRD §1: spine item #1). Today there is no Home
Cockpit; the closest things are the per-workspace `WorkspaceBriefing` (chat home screen) and the
modal `LoginBriefing` (one-shot catch-up overlay). The mockup shows six regions: greeting + date,
"You were working on" (recent workspaces with Continue), "Overnight" (consolidated / artifacts /
failures counters), "Up next" (events/tasks), "Suggested next actions", "Quick capture", and an
"Active models" tile.
---
## 2. Required states (PRD §12.1 + Blueprint p.265/447)
Functional requirements (§12.1):
- Greeting with user name + date/time.
- Active/recent workspaces ranked by recency and priority, each with one-click Continue.
- Overnight summary: memories consolidated, artifacts created, automations completed, failures.
- Upcoming meetings/events/tasks ("Up next").
- Suggested next actions (memory/session/task/schedule-derived).
- Quick capture for note/task/link/file.
- Active models + current mode, only if relevant (do not clutter).
- Ctrl+K hint/access.
States to implement (§12.1 "States" + Blueprint line 447):
`Loading` · `First-run empty` · `Normal populated` · `Attention required` · `Offline/local-only` ·
`Overnight failure` · `Permission denied for shared/team data`.
---
## 3. Current state in repo — disposition: **partial (keep-promote + create-new)**
PRD §20.1 explicitly: `WorkspaceBriefing.tsx` → "seed for Home Cockpit widgets" (keep and promote).
There is **no `HomeCockpit` component today** — it is a §20.3 "Create" item. So the work is: extract
reusable widget logic from the two existing briefing surfaces, build a new full-screen `HomeCockpit`,
and wire it to a new cross-workspace aggregation endpoint.
Existing files that feed this screen:
| File | What it does | Reuse role |
|---|---|---|
| `apps/web/src/components/os/WorkspaceBriefing.tsx` (283 LOC) | Per-workspace "home screen" inside ChatApp when a chat has no messages. Fetches `GET /api/workspaces/:id/context`; renders greeting, stats bar, pending tasks, recent decisions, "I Remember" memories, recent threads, cross-workspace hints, persona skill chips, suggested prompts, upcoming schedules. Collapse state persisted per-workspace via `lib/workspace-briefing-state`. | **Keep-promote.** Its section components (memory list, pending tasks, decisions, suggested-prompt chips, upcoming schedules) are the widget vocabulary the Cockpit reuses. It is **per-workspace**, so it can't be the Cockpit as-is. |
| `apps/web/src/components/os/overlays/LoginBriefing.tsx` (363 LOC) | Modal "I remember…" catch-up shown once after boot. Already does **cross-workspace aggregation** client-side: `getWorkspaces()` → per-workspace `getWorkspaceContext()` (N calls) + `searchMemory('…','global')` + `getMemoryStats()`. Builds workspace summaries (memoryCount/sessionCount/lastActive/summary/pendingTasks), ranked memory highlights (`lib/briefing-highlights`), brag header (`lib/login-briefing-brag`), time-aware greeting + identity name. Has first-run empty hook (3 demo bubbles). Filters E2E/test workspaces. | **Keep-promote (heaviest reuse).** Its data-gathering and ranking is exactly the Cockpit's "You were working on" + greeting + first-run-empty logic — but it does the N+1 fan-out **on the client**, which §20.4 forbids ("do not duplicate backend state calculation in frontend"). Promote this logic **into the new `GET /api/home/briefing`** server route. |
| `apps/web/src/components/os/apps/DashboardApp.tsx` | Dock app `home` — Workspaces grid (select/create/open chat), brain-health tier. Currently the thing the `home` dock key opens. | **Rework/keep.** Becomes the workspaces-grid sub-view; Home Cockpit becomes the new default `home` surface. Not the briefing itself. |
| `apps/web/src/components/os/apps/CockpitApp.tsx` (315 LOC) | "Cockpit" = system/ops dashboard (health, cost, crons, connectors, weaver, event stats, compliance). Dock id `cockpit`. **Name collision only** — this is the ops Command-Center surface, NOT the PRD Home Cockpit. | **Out of scope / do not conflate.** Maps to PRD §12.3-ish ops, not §12.1. Flag the naming clash. |
| `apps/web/src/components/os/cockpit/ComplianceDashboard.tsx` | EU AI Act compliance tiles, hosted inside `CockpitApp`. | Not relevant to S01. |
Supporting lib (frontend, reuse as-is):
`lib/briefing-highlights.ts` (`selectBriefingHighlights` — importance-then-recency ranking),
`lib/login-briefing-brag.ts` (`computeBragSummary`/`formatBragLine`/`timeAgo`),
`lib/workspace-briefing-state.ts` (collapse persistence), `lib/persona-display.ts`,
`lib/skill-recommendations.ts` (persona skill chips). **Note:** `lib/suggested-actions.ts` is for
**chat follow-up chips** (regex over the last assistant message) — it is NOT the Home "suggested next
actions" generator; do not reuse it for the Cockpit. Suggested actions for Home come from
`buildWorkspaceState().nextActions` (backend) aggregated cross-workspace.
Backend builder already present (keep-promote, §20.1): `packages/server/src/local/workspace-state.ts`
`buildWorkspaceState()` → typed `WorkspaceState` (active/openQuestions/pending/blocked/completed/stale/
recentDecisions/`nextActions`) with freshness classification. This is the per-workspace next-action
engine the Home briefing aggregates over.
---
## 4. Frontend work
**Create** `apps/web/src/components/os/apps/HomeCockpitApp.tsx` (new top-level surface; register in
`Desktop.tsx` `appConfig` + `renderAppContent`, and make the `home` dock key open it instead of
`DashboardApp` — `DashboardApp` demotes to a "Workspaces" grid reachable from a Cockpit tile/Ctrl+K).
Widget components (extract from the two briefing files so logic is shared, not copy-pasted — CLAUDE.md
"many small files"):
- `home/GreetingHeader.tsx` — greeting + name + date/time (promote from `LoginBriefing` lines 84-95 +
`WorkspaceBriefing` greeting). Reuse `buildTimeAwareGreeting` semantics from backend; client just renders.
- `home/RecentWorkspacesPanel.tsx` — "You were working on": ranked workspace cards w/ Continue button →
`openChatForWorkspace(id)` (via `useWindowManager`). Promote `LoginBriefing` summaries list (lines 277-334).
- `home/OvernightPanel.tsx` — counters (consolidated / artifacts / automations done / failures); failure
rows expandable → Automation Center. **New** (no current equivalent).
- `home/UpNextPanel.tsx` — upcoming events/tasks/schedules. Reuse `upcomingSchedules` + `pendingTasks`
shapes; aggregate across workspaces.
- `home/SuggestedActionsPanel.tsx` — top N `nextActions` aggregated from `buildWorkspaceState`, each
routing to its workspace. **Not** `lib/suggested-actions.ts`.
- `home/QuickCapturePanel.tsx` — note/task/link/file input → `POST /api/quick-capture`. **New.**
- `home/ActiveModelsTile.tsx` — promote `ModelPilotCard` / `useProviders`; render only when relevant.
Data layer:
- New hook `hooks/useHomeBriefing.ts` → `adapter.getHomeBriefing()` + `adapter.getOvernight()`, with
the §12.1 state machine (loading/empty/populated/attention/offline/overnight-failure/permission-denied).
- Extend `lib/adapter.ts` (the single sidecar gateway) with `getHomeBriefing()`, `getOvernight()`,
`quickCapture(payload)`. Per the frontend inventory, all PRD §16 endpoints get added here.
- First-run empty: reuse `LoginBriefing`'s demo-bubble hook (lines 222-247).
- Offline/local-only: reuse `useOfflineStatus`; degrade overnight/team tiles, keep local workspaces.
- Ctrl+K hint: surface the existing `GlobalSearch` (Ctrl+K) — already wired in `useKeyboardShortcuts`.
**Decision required (Open Q):** does `LoginBriefing` (modal) survive alongside Home Cockpit, or does the
Cockpit absorb it? They overlap ~80%. Recommend: collapse `LoginBriefing` into the Cockpit's first paint
and retire the modal (avoid two catch-up surfaces).
---
## 5. Backend work (PRD §16.1)
| PRD endpoint | Status | Plan |
|---|---|---|
| `GET /api/home/briefing` | **MISSING** | **NET-NEW** route (new `routes/home.ts` registered in `local/index.ts`). Server-side aggregation that promotes `LoginBriefing`'s client N+1 fan-out: iterate `workspaceManager` workspaces → reuse per-workspace logic already in `routes/workspaces.ts` `/context` handler (greeting/summary/recentMemories/pendingTasks/upcomingSchedules) + `buildWorkspaceState()` (`workspace-state.ts`) for `nextActions`, ranked by recency/priority. Reuse `briefing-highlights` ranking server-side. **Substrate touched:** `memory_frames` (per-workspace `.mind`), session JSONL, `awareness`, `cron-store`. No new store. **Refactor over EXTEND:** factor the `/context` body into a shared builder so `/context` and `/home/briefing` don't duplicate SQL. |
| `POST /api/quick-capture` | **PARTIAL** | **EXTEND** `routes/memory.ts` (or thin new handler delegating to it). Closest existing write is `POST /api/memory/frames`. Quick-capture = thin wrapper: default to **personal** mind, stamp `source: 'quick-capture'`, accept `kind ∈ note|task|link|file`. For `task` also write an `awareness` row so it surfaces in `nextActions`; for `file` route through `POST /api/ingest`. **Substrate:** `memory_frames` (personal `.mind`), `awareness`. No migration. |
| `GET /api/home/overnight` | **MISSING** | **NET-NEW** route (same `routes/home.ts`). Aggregate from existing substrates — **no new store**: `cron`/automation runs via `GET /api/cron/:id/history` (`notifications.ts`) + cron-store; consolidation/artifact counts from `events.ts` audit events (`GET /api/events?since=`) and `weaver` status (`/api/weaver/status`); failures from cron history error rows + notifications. Returns `{ consolidated, artifactsCreated, automationsCompleted, failures[] }`. The `Overnight failure` state is driven by `failures.length > 0`. |
Notes for the implementer:
- **Reuse, don't reinvent (§20.4):** the per-workspace catch-up math lives in `routes/workspaces.ts`
lines 311-592 and `workspace-state.ts`. Extract the shared body before adding the cross-workspace loop.
- **Privacy gate (CRITICAL — already bit us):** cross-workspace content aggregation was previously a
privacy leak. `routes/workspaces.ts` lines 553-564 show `crossWorkspaceHints` is **deliberately
DISABLED** (returns `[]`) because the original iterated every workspace MindDB and returned content
snippets with no grant check (security review: `cowork/Code-Review_MultiMind_April-2026.md` Critical #1).
`GET /api/home/briefing` is the SAME pattern (read every workspace) — but for Home it is the user's
**own** workspaces, so it is legitimate for personal scope. **Team/shared workspace rows must respect
`approvalGrantStore` / team RBAC** (PRD §12.1 `Permission denied for shared/team data` state). Do not
leak team-workspace content the caller can't access.
- Tier: Home briefing must work on FREE/TRIAL (it's the daily landing surface). Team-overnight rows are
TEAMS-gated; gate the team slice, not the whole endpoint.
**No `.mind` schema migration required.** All three endpoints read existing tables (`memory_frames`,
`awareness`, audit `events`) and write only via existing frame/awareness paths. (PRD §15.4 confidence/
provenance fields are a *separate, later* migration — not needed for S01.)
---
## 6. Shared types needed (PRD §15 vs `lib/types.ts`)
Today `lib/types.ts` has `WorkspaceContext` (lines 66-85) — per-workspace, already carries
greeting/recentMemories/pendingTasks/upcomingSchedules/crossWorkspaceHints. **Reuse its sub-shapes.**
Add new interfaces (in `lib/types.ts`, mirrored server-side):
- `HomeBriefing { greeting; date; recentWorkspaces: RecentWorkspaceCard[]; suggestedActions: SuggestedAction[]; upNext: UpNextItem[]; activeModels?; isFirstRun: boolean }`
- `RecentWorkspaceCard { id; name; group; summary?; lastActive; pendingCount; continueSessionId? }`
- `OvernightSummary { consolidated: number; artifactsCreated: number; automationsCompleted: number; failures: OvernightFailure[] }`
- `OvernightFailure { id; label; automationId?; error; at }`
- `QuickCaptureInput { kind: 'note'|'task'|'link'|'file'; content; workspaceId? }`
- `SuggestedAction { label; workspaceId; sessionId?; kind }`
Align kinds with PRD §15.2 (`MemoryKind`, `ArtifactKind`) where they overlap. These are net-new vs the
current `lib/types.ts` (which has no Home/Overnight/QuickCapture types).
---
## 7. Dependencies (screens/phases first)
- **AppShell / IA (Sprint 1, PRD §21):** Home Cockpit is the default landing surface — needs the dock
`home` key repointed and the §10 IA buckets settled first.
- **Command Center (Ctrl+K) (S03):** §12.1 acceptance "open Ctrl+K from the keyboard" — `GlobalSearch`
already exists, so this is a soft dep (hint only).
- **Workspace Desktop (S02):** "Continue" routes into the per-workspace runtime; needs `openChatForWorkspace`
(already in `useWindowManager`) — soft dep.
- **Automation Center (S11):** overnight failure rows link there; can ship Home with the count + a stub link.
- Belongs to **Sprint 2 ("Home and workspace state")** per PRD §21 — after shell, alongside the
workspace-context/state API extension.
---
## 8. Effort: **L**
Frontend is mostly **promotion** of two existing briefing surfaces into shared widgets (medium), but the
backend adds **two net-new aggregation routes** (`/home/briefing`, `/home/overnight`) that must (a)
refactor the per-workspace `/context` body into a shared builder to avoid duplication and (b) re-implement
the cross-workspace aggregation **safely** behind the grant/RBAC gate that previously caused a privacy
leak. The security-sensitive cross-workspace read is what pushes this from M to L. Not XL — no new data
store, no schema migration, and the ranking/greeting logic already exists.
---
## 9. Open questions
1. **LoginBriefing fate:** retire the modal and absorb its catch-up into Home Cockpit's first paint, or
keep both? (~80% overlap; two catch-up surfaces is confusing.)
2. **"Overnight" semantics:** time-window = since last app close? since midnight local? last 12 h? Affects
the `since=` query for events/cron history.
3. **Cross-workspace personal read:** confirm reading the user's *own* workspaces server-side (for the
briefing) is acceptable now that it's same-user (the prior leak was content snippets without grant
checks). Team/shared rows still gate through `approvalGrantStore`/RBAC — confirm the gate boundary.
4. **`home` vs `cockpit` naming:** `CockpitApp` already owns "Cockpit" (ops). PRD calls S01 "Home Cockpit".
Final dock/app naming to avoid the collision (proposal: S01 = `home`/"Home"; keep ops as `cockpit`).
5. **DashboardApp role:** does the Workspaces grid live as a Cockpit tab, a Ctrl+K destination, or stay a
separate dock app? (Affects whether `home` dock key fully repoints to HomeCockpit.)
6. **Quick-capture `file` flow:** does a file capture upload into a default/personal store, or prompt for a
target workspace? `POST /api/ingest` needs a destination.

219
docs/ux-refactor/gap-cards/S02-workspace-desktop.md Normal file
View File

@@ -0,0 +1,219 @@
# Gap Card — S02 · Workspace Desktop
> Screen S02 of the Waggle OS UX-refactor. PRD §12.2 (lines 412-447). Execution model: **in-place
> incremental refactor** of `apps/web` + targeted sidecar extensions. Mockup
> (`screen_02_workspace_desktop.png`) is **directional**; PRD acceptance criteria win.
> Every claim grounded in repo source (paths cited).
---
## 1. Screen & purpose
**Purpose (PRD §12.2):** the primary runtime for a single bounded work context. It demotes chat
from "the whole product" to **one widget among many**, surfacing workspace state, artifacts, memory,
tasks, research, and activity on a single screen, with chat/agent interaction co-resident.
**Mockup reading** (`Waggle_OS_Handoff_Assets/screen_02_workspace_desktop.png`): a full-screen
(non-floating) layout for "Germany GTM Strategy" with:
- **Left nav rail** — Workspaces / Memory / Agents / Automations / Files / MCP Hub / Connectors + favourites + user tile.
- **Header** — workspace name + status pill ("Active"), team avatar stack, Share button, global search.
- **Tab bar** — Overview · Chat · Research · Artifacts · Memory · Tasks · Timeline.
- **Main canvas (Overview tab)** — multi-widget grid: AI workspace/chat preview, Key Artifacts list,
Tasks list, Memory highlights, Research overview (donut), Recent activity feed.
- **Right panel** — Workspace info, Members, Last activity, quick actions.
- (Implied) **status bar** — agents running / automations active / MCPs connected.
> The blueprint text page for "Screen 2 — Workspace Desktop" (`_blueprint_extracted.txt:675`) is an
> image-only placeholder; the only textual spec is PRD §12.2 + the §0/§9/§19 spine references
> (`_blueprint_extracted.txt:15,42,63,274,513,585`).
---
## 2. Required states (PRD/Blueprint)
**Functional requirements (PRD §12.2, lines 423-430):**
- Header: workspace name, **type**, **status**, team/avatar stack, share controls.
- Tabs: Overview, Chat, Research/Notes, Artifacts, Memory, Tasks, Timeline, Settings.
- Main canvas widgets: AI workspace/chat, key artifacts, tasks, memory highlights, research overview, recent activity.
- Right panel: workspace info, members, last activity, quick actions.
- Bottom/status bar: agents running, automations active, MCPs connected.
- Fixed default layout initial release; configurable widgets deferred to a later phase.
**States (PRD §12.2, lines 432-441):** No memory · Active work · Agent running · Artifact ready ·
Task blocked · Sync conflict · Permission denied · Offline.
**Acceptance criteria (PRD §12.2, lines 443-447):**
- Chat is one widget, not the whole product.
- Workspace state is always visible.
- User can reach memory, artifacts, agents, skills, tasks, automations, and settings from the workspace.
**Cross-cutting (Blueprint §state-rules):** server-derived state — "Home Cockpit and Workspace
Desktop must use server workspace-state/context APIs" (`_blueprint_extracted.txt:513`); cache
invalidation on memory import / artifact update / agent-run completion / connector sync / automation
completion / RBAC change (`:514`).
---
## 3. Current state in repo
**Disposition: `create-new` (the tabbed Workspace Desktop screen does not exist), reusing existing
substrate heavily.** There is **no** workspace-runtime surface today. The closest analog is a
chat-only floating window:
- **`apps/web/src/components/os/Desktop.tsx`** — root OS shell. `renderAppContent()` is a
`switch(win.appId)` (`:276-360`); a workspace "opens" only as `case 'chat'` →
`<ChatWindowInstance>` (`:278-296`). There is **no `case 'workspace'`** and no tabbed runtime.
Apps are floating windows (`AppWindow` chrome), not a full-screen workspace surface. `appConfig`
(`:77`) has no workspace entry.
- **`apps/web/src/components/os/apps/ChatWindowInstance.tsx`** — per-window wrapper: owns model
fetch + per-window persona/autonomy, renders only `<ChatApp>` (`:221-248`). Chat **is** the whole
window — the exact inversion PRD §12.2 forbids.
- **`apps/web/src/components/os/WorkspaceBriefing.tsx`** — ChatApp "home screen" shown when a session
has no messages. Fetches `GET /api/workspaces/:id/context` via `adapter.getWorkspaceContext()`
(`:57`) and renders greeting / stats / pending tasks / recent decisions / "I Remember" memories /
recent threads / cross-workspace hints / suggested prompts / upcoming schedules. **This is the
single best reuse seed** — it already consumes the "Workspace Now" block the Overview tab needs,
but it lives *inside* chat and is read-only (no artifacts, no tasks CRUD, no tabs, no right panel).
- **`apps/web/src/components/os/apps/DashboardApp.tsx`** — Workspaces grid (select/create/open-chat).
This is the workspace **list** (S01-adjacent), not the per-workspace runtime.
- **`apps/web/src/components/os/apps/RoomApp.tsx`** — live sub-agent tiles via `useRoomState` SSE
(`:24`); the "agents running" status indicator can be derived from this per-workspace.
- **`apps/web/src/components/os/overlays/ContextRail.tsx`** — right-side rail for a clicked
frame/entity (`ContextRailTarget`); a **reuse target for the right-panel detail pattern**, but it
is an overlay keyed to a single frame, not a persistent workspace info/members/activity panel.
**Tabs that already have a host component** (to embed, not rebuild): Memory → `MemoryApp.tsx`,
Timeline → `TimelineApp.tsx`, Chat → `ChatWindowInstance`/`ChatApp`, Settings →
`SettingsApp.tsx`. **Tabs with NO host:** Overview (new), Research/Notes (new), Artifacts (no
backing entity at all — see §5), Tasks (store exists server-side, never wired to FE — see §4/§5).
**Adapter gap (confirmed by grep on `apps/web/src/lib/adapter.ts`):** `getWorkspaceContext` (`:272`),
`getWorkspaceFiles` (`:277`), `getPins`/`addPin` (`:1353/:1361`), `getDocuments` (`:1371`) exist;
**no `getTasks` / `getWorkspaceState` / `getWorkspaceActivity` methods** (0 matches). So the Tasks
list, the `/state` Overview source, and the activity feed have no client plumbing yet.
---
## 4. Frontend work
### Components to create
| Component | Role | Reuse / source |
|---|---|---|
| `apps/WorkspaceApp.tsx` (new) | Full-screen workspace runtime shell: header (name/type/status/avatars/Share) + `Tabs` + right panel + status bar. Owns `activeTab` state. | `components/ui/tabs.tsx`; header layout from `StatusBar.tsx` + `chat-header-layout.ts`; tab gating via `useFeatureGate`. |
| `workspace/OverviewTab.tsx` (new) | Default tab: widget grid (chat preview, key artifacts, tasks, memory highlights, research, recent activity). | **Port the read-only sections of `WorkspaceBriefing.tsx`** (greeting/decisions/memories/threads) into widget cards; add artifacts/tasks/activity widgets. |
| `workspace/WorkspaceInfoPanel.tsx` (new) | Right panel: info, members, last activity, quick actions. | Members from `adapter.getTeamMembers()`; "last activity" from new activity hook; quick actions raise `waggle:open-app`. ContextRail stays a separate frame-detail overlay. |
| `workspace/TasksTab.tsx` (new) | Task list/board for the workspace. | Net-new FE; backs onto existing `/api/workspaces/:id/tasks` (server store exists, FE plumbing missing). |
| `workspace/ResearchTab.tsx` (new) | Research/Notes surface. | Lightweight: notes-as-frames (memory) + wiki pages (`adapter.getWikiPages`). Lowest-fidelity tab; can ship as "notes" v1. |
| `workspace/ArtifactsTab.tsx` (new) | Artifacts grid (see S05 dependency). | Backs onto new `/api/artifacts` (net-new) or interim file-registry view via `getWorkspaceFiles`/`getDocuments`. |
### Components to rework / wire
- **`Desktop.tsx`** — add `case 'workspace'` to `renderAppContent` + an `appConfig.workspace`
entry; route `openChatForWorkspace` callers that should open the *desktop* (not a chat window) to a
new `openWorkspace(workspaceId)`. Decide window-vs-fullscreen (recommend full-bleed window using
existing maximize path in `AppWindow.tsx` to avoid a parallel layout system). **Surgical** — do
not refactor the window manager.
- **`useWindowManager.ts`** — add `workspace` to the `AppId` consumption; reuse `workspaceId` field
already on `WindowState`. No new state shape.
- **Embed existing apps as tab panels** — Memory/Timeline/Chat/Settings render their existing
components scoped by `workspaceId` (already accepted props on `TimelineApp`, `ChatWindowInstance`).
### Adapter methods / hooks to add (`lib/adapter.ts` — the one contract surface)
- `getWorkspaceState(id)` → `GET /api/workspaces/:id/state` (Overview; PARTIAL backend, §5).
- `getWorkspaceActivity(id, {limit})` → `GET /api/workspaces/:id/activity` (activity feed; PARTIAL, §5).
- `getTasks(workspaceId)` / `createTask` / `updateTask` / `deleteTask` → `/api/workspaces/:id/tasks*`
(routes EXIST, adapter methods MISSING).
- New hook `useWorkspaceDesktop(workspaceId)` composing state + activity + tasks + members +
fleet (agents-running) + cron (automations) + capabilities/status (MCPs-connected) for the status
bar. Reuse `useRoomState` for live agents.
---
## 5. Backend work
Per PRD §16.2 plus the substrate the Overview/widgets/status-bar need. Cross-referenced against
backend-routes inventory + backend-map `03c`.
| PRD §16 endpoint | Status | Extend vs net-new · substrate · migration |
|---|---|---|
| `GET /api/workspaces/:id` | **EXISTS** | `workspaces.ts`. Header name/team. But `type`+`status` fields are **MISSING** on `WorkspaceConfig` (`hive-mind-core/src/workspace-manager.ts:5-58`) — additive JSON fields, **no DB migration** (workspace.json file). Default `status:'active'`; derive `type` from `templateId`/`group`. |
| `PATCH /api/workspaces/:id` | **EXISTS** | `workspaces.ts`. Used for status change / Share controls. Stamp `updatedAt` in `update()` (`workspace-manager.ts:222`, currently unstamped). |
| `GET /api/workspaces/:id/context` | **EXISTS** | `workspaces.ts:311` — the "Workspace Now" block (`buildWorkspaceNowBlock()`, `workspace-context.ts:191-404`). Direct feed for Overview widgets (greeting/decisions/memories/threads/pending/schedules). |
| `GET /api/workspaces/:id/state` | **PARTIAL → EXTEND** | No `/state` route. `buildWorkspaceState()` (`workspace-state.ts:234-311`) already produces `active/openQuestions/pending/blocked/completed/stale/recentDecisions/nextActions` and is surfaced *inside* `/context` as `workspaceState`. Add a thin `/state` route returning that sub-object directly (Overview/Tasks consume `pending`+`blocked` as task seeds). Substrate: `memory_frames` + session JSONL + `awareness`. No migration. |
| `GET /api/workspaces/:id/activity` | **PARTIAL → EXTEND** | No per-workspace `/activity`. Closest: `GET /api/events?workspaceId=` (`events.ts`) and `GET /api/teams/:id/activity`. Add a thin `/activity` alias over the audit-event query (substrate: `ai_interactions`/`execution_traces`/events). No migration. |
| Tasks: `GET/POST /api/workspaces/:id/tasks`, `PATCH/DELETE …/:taskId` | **EXISTS (server)** | `tasks.ts` (backend-routes §1.7). Only FE plumbing missing — no net-new backend. |
| Status bar feeds | **EXISTS, no aggregate** | agents → `GET /api/fleet` (`fleet.ts`); automations → `GET /api/cron` (`cron.ts`); MCPs connected → `GET /api/capabilities/status` (`mcpServers[]`) / `install_audit`. Compose client-side in v1; an aggregate `/status` route is optional. |
| Members / Share | **PARTIAL** | Members → `GET /api/team/members` (EXISTS). **Share** → PRD §16.11 `POST /api/share` is **MISSING** (grep-confirmed, backend-routes §16.11). Header Share button is net-new backend; for non-team workspaces it can be a no-op/disabled in v1. |
| Artifacts widget/tab | **MISSING (largest gap)** | No `Artifact` entity, table, or `/api/artifacts*` route anywhere (substrate-types §e; backend-routes §16.6). Interim: render the **file registry** `GET /api/workspaces/:id/files` (`workspaces.ts`) + document versions `GET /api/workspaces/:id/documents` (`documents.ts`) as "artifacts". Full Artifact Center is **S05's** scope — S02 should depend on it, not build it. |
**Migration flag:** the only `.mind` SQLite migration *adjacent* to this screen is the optional
`memory_frames.metadata`/`confidence`/`kind` additions (substrate-types §c) needed for richer Memory
**filters** — **not required for S02's Overview/Tasks/Timeline tabs**; defer to S04 (Memory Center).
S02's own missing fields (`type`, `status`, `updatedAt`, `lastActiveAt`) are JSON-file additive — **no
DB migration**.
---
## 6. Shared types needed (PRD §15 vs `lib/types.ts`)
- **`WorkspaceType`, `Scope`, `Confidence` literal unions** (PRD §15.2) — **none exist** in
`apps/web/src/lib/types.ts` (substrate-types §e). Add `WorkspaceType` + `WorkspaceStatus`
(`active`/`paused`/`archived`) for header.
- **`Workspace` → `WorkspaceConfigV2` alignment** (PRD §15.3) — FE `Workspace` (`types.ts:22-40`)
lacks `type`, `status`, `description`, `updatedAt`, `lastActiveAt` and uses `persona` vs config's
`personaId`. Add the 5 missing fields (optional) for header/last-activity; keep DERIVED display
fields.
- **`WorkspaceState` type** — exists server-side (`workspace-state.ts:38-55`) but is **not mirrored**
in FE `types.ts`. Add a FE `WorkspaceState` mirror for the new `getWorkspaceState` method.
- **`Task` type** — `lib/types.ts` has no Task interface (server `tasks.ts` shape only). Add one for
the Tasks tab.
- **`Artifact` type** — **greenfield** (PRD §15.6). Owned by S05; S02 imports it once defined.
- `WorkspaceContext` already exists in `types.ts` (consumed by `WorkspaceBriefing`) — reuse for Overview.
---
## 7. Dependencies (screens / phases first)
- **Phase 1 (Shell + Ctrl+K)** — `_blueprint_extracted.txt:582` — must land first: this screen is
opened *from* the shell/route map and the left nav. S02 needs the new `route`/`activeWorkspaceId`
global state + the `case 'workspace'` shell wiring.
- **Phase 2 (Home + Workspace)** — `_blueprint_extracted.txt:585` — S02 ships **with** S01 (Home
Cockpit); both share `/api/workspaces/:id/context` + `/state`. S01's cross-workspace briefing
reuses S02's per-workspace builder.
- **S05 Artifact Center** — hard dependency for the Artifacts tab/widget (entity + `/api/artifacts*`
are entirely net-new there). S02 must ship the Artifacts tab as an **interim file-registry view**
if S05 is not ready.
- **S04 Memory Center** — the Memory tab embeds `MemoryApp`; richer confidence/kind filters (and the
`memory_frames` metadata migration) live there, not in S02.
- **S03 Command Center (Ctrl+K)** — the header search + quick actions route through the command provider.
---
## 8. Effort
**XL.** Net-new full-screen tabbed runtime that re-architects the product's primary surface (chat →
one-widget), needs 5-6 new FE components + several adapter methods/hooks, 2 thin backend routes
(`/state`, `/activity`) + workspace `type`/`status`/`updatedAt`/`lastActiveAt` additive fields, and
is gated on S05 (Artifacts) for one full tab. The read-only Overview seed exists
(`WorkspaceBriefing`), which keeps it from being 2×XL, but the shell-integration + tab embedding +
status-bar aggregation breadth dominate.
---
## 9. Open questions
1. **Window vs full-screen.** Should the Workspace Desktop be a maximized `AppWindow` (reuse existing
window manager + chrome) or a dedicated full-bleed route bypassing the floating-window system? The
mockup is full-screen; the current OS is windowed. Recommend maximized-window to avoid a parallel
layout system — needs founder/eng confirmation.
2. **Chat-as-widget vs Chat-tab.** PRD says "chat is one widget" (Overview) AND lists a "Chat" tab.
Is the Overview chat widget a live mini-composer or a read-only preview that deep-links to the Chat
tab? Affects whether `ChatApp` must run in two render modes.
3. **`workspace.type` taxonomy.** PRD §15.2 names `WorkspaceType` but no enum values are given. Derive
from the 15 existing `workspace-templates` categories, or define a new fixed set?
4. **`status` lifecycle.** Who/what sets `paused`/`archived` (manual header action vs automation)?
PRD §12.2 lists the status states but not the transitions.
5. **Share scope.** `POST /api/share` is net-new (PRD §16.11). Is Share in S02's MVP, or stubbed
until Team Workspace (S10)? For a solo/non-team workspace, what does Share do?
6. **Tasks store of record.** Tasks tab — back onto the existing `/api/workspaces/:id/tasks` store, or
model tasks as `pending`/`blocked` `StateItem`s from `WorkspaceState` (which are session/awareness-
derived, not first-class)? These are two different sources of truth to reconcile.

182
docs/ux-refactor/gap-cards/S03-command-center.md Normal file
View File

@@ -0,0 +1,182 @@
# Gap Card — S03 · Command Center (Ctrl+K)
> Execution model is the LOCKED **in-place incremental refactor** of `apps/web` + targeted
> backend extensions. Mockup (`Waggle_OS_Handoff_Assets/screen_03_win_k_command_center.png`) is
> DIRECTIONAL only; PRD §12.3 acceptance criteria win. Every claim below is grounded in a real file.
---
## 1. Screen & purpose
The universal command layer — opens from anywhere with Ctrl+K / Cmd+K — for **search, launch,
create, run, navigate, and extend** across every major object type. PRD §12.3 (lines 449-482),
blueprint screen 3 (`_blueprint_extracted.txt:284-290, 633, 679`). It is the product's "primary
interaction" per blueprint line 19 ("Primary interaction: Ctrl+K") and the IA spine item #3
(PRD line 19). Goal: "No user needs to know where a feature lives to use it" (PRD line 482).
The mockup shows a centered modal titled "What do you want to do?" with: a search input
("Search anything…"), pill tabs (Show my tasks / Open … STM Strategy / Find market analysis /
Summarize…), five category columns — **Launch · Create · Run · Navigate** plus a Search bucket —
each listing object/action rows, a "Suggested for you" card strip (review reports, draft proposals),
and a footer "Type a natural-language command…". A second "Open in new window" affordance is top-right.
---
## 2. Required states (PRD/Blueprint)
PRD §12.3 functional requirements (lines 461-467):
- Opens from anywhere via Ctrl+K / Cmd+K.
- Searches across **workspaces, memory, artifacts, sessions, people, agents, skills, commands, connectors, MCPs**.
- Category sections: **Search, Launch, Create, Run, Navigate, Extend**.
- Supports **natural-language command input**.
- Displays **recent and suggested** actions.
- **Permission-gated actions show an approval prompt before execution.**
- Reachable by both mouse and keyboard.
PRD §12.3 states (lines 469-477) + blueprint (`:289-290`):
Idle · Query active · Grouped results · No results · Permission prompt · Command success · Command failure.
Acceptance (lines 479-482): every major object and action is reachable; no user needs to know where a feature lives.
---
## 3. Current state in repo
**Disposition: `rework`** (keep the proven overlay shell + keyboard nav + adapter calls; restructure
categories to Search/Launch/Create/Run/Navigate/Extend; add execute + permission-prompt + recent/suggested;
back it with the net-new `/api/command/*` provider).
- **`apps/web/src/components/os/overlays/GlobalSearch.tsx`** (362 lines) — the existing Ctrl+K/Cmd+K
overlay. Today it does **client-side federated search only** across 5 categories
(`SearchCategory = 'command' | 'workspace' | 'memory' | 'session' | 'skill'`, line 15):
- `command` = a **hardcoded static `COMMANDS` array** of 23 app ids (lines 40-64) that must be
hand-kept in sync with `appConfig` in `Desktop.tsx` (the file's own comment flags this drift as
"the cause of FR #13", lines 33-39).
- `workspace`/`session`/`skill` pre-fetched on open via `adapter.getWorkspaces()`,
`adapter.getSessions(ws.id)` (first 5 ws × 3 sessions, lines 98-127), `adapter.getSkills()` (lines 129-138).
- `memory` = debounced (300 ms, min 2 chars) server call `adapter.searchMemory(query, globalScope?'global')`
(lines 142-168) — the **only** server-backed category.
- Matching is client-side `fuzzyMatch` (`lib/fuzzy-match`, line 11/177-187); keyboard nav (↑/↓/Enter/Esc),
selection clamp, scroll-into-view all already work (lines 224-239).
- There is **no execute path** — every Enter calls `onNavigate(category, id)` (lines 231-235, 320),
i.e. it only *opens a window*. No Create/Run/Extend, no recent, no suggested, no permission prompt.
- **`Desktop.tsx` wiring** — `<GlobalSearch open onClose onNavigate={handleSearchNavigate} />` (`:464`),
toggled by `ov.toggleGlobalSearch` (Ctrl/Cmd+K via `useKeyboardShortcuts`, `:207`) and the StatusBar
search button (`:424`). `handleSearchNavigate` (`Desktop.tsx:217-225`) handles only `command`→`wm.openApp`,
`workspace`→`selectWorkspace`+`openChatForWorkspace`, `memory`→`openApp('memory')`. **No `session`/`skill`
navigation, no execute.**
- **`apps/web/src/components/os/overlays/KeyboardShortcutsHelp.tsx`** (92 lines) — static cheat-sheet
modal (`shortcuts` array, lines 9-32). Lists "⌘K → Global Search" (line 21). **Disposition `keep`** —
it is the separate `Cmd+?` help overlay, not the command center; only update its label if Ctrl+K is
rebranded "Command Center".
- **`adapter.executeCommand(command, workspaceId)`** (`lib/adapter.ts:1345-1350`) → `POST /api/commands/execute`
(note **plural** `commands`). Runs **slash commands only** (`/catchup`, `/status`, `/memory`, `/skills`);
workflow/spawn commands return "not available" (`packages/server/src/local/routes/commands.ts:1-87`).
Exists but is **not** the generic palette execute.
- **`adapter.searchSessions`** (`adapter.ts:424-427`), `adapter.searchMemory` (`:476-487`) exist and are
reusable as federation inputs. `lib/suggested-actions.ts` is **chat-message-scoped** (extracts follow-up
chips from the last assistant message) — NOT command-palette suggestions; do not reuse for §12.3 "suggested".
---
## 4. Frontend work
**Rework `GlobalSearch.tsx` → `CommandCenter.tsx`** (rename or keep filename; founder-directional).
Reuse 100% of the modal chrome, framer-motion animation, debounce, keyboard-nav, selection/scroll logic.
Concrete changes:
- **Expand `SearchCategory`** to the PRD §12.3 verbs: add `'create'`, `'run'`, `'navigate'`, `'extend'`
alongside `'search'` (today's `command/workspace/memory/session/skill` become **Search/Navigate** result
feeds). Category headers + ordering (`CATEGORY_LABELS`/`CATEGORY_ORDER`, lines 67-75) extend accordingly —
this matches the mockup's Launch/Create/Run/Navigate columns.
- **Replace client federation with a server provider.** Swap the multi-call client logic (lines 91-168)
for a single debounced `adapter.commandSearch(q, { scope })` → `GET /api/command/search?q=` (net-new
adapter method on `lib/adapter.ts`, the one contract surface). Keep the existing per-category calls only
as offline/fallback. Eliminates the hardcoded `COMMANDS`-vs-`appConfig` drift (FR #13).
- **Add an execute path.** New `onExecute(commandId|nlInput)` → `adapter.commandExecute()` →
`POST /api/command/execute`. On Enter for a Run/Create/Extend item (vs Navigate items which keep calling
`onNavigate`). Render the §12.3 **permission prompt** state inline before executing gated actions
(reuse the approvals pattern — `useChat().pendingApproval`/`approveAction` and `ApprovalRequest` type,
`lib/types.ts`), plus **command success / command failure** toasts (`hooks/use-toast`).
- **Recent + Suggested.** On idle (empty query), render two strips matching the mockup: "Recent" from
`adapter.commandRecent()` → `GET /api/command/recent`, and "Suggested for you" from
`adapter.commandSuggestions()` → `GET /api/command/suggestions`.
- **Natural-language input** (PRD line 464): when the query doesn't match a structured result, surface a
"Run as command: '<query>'" row that posts the raw string to execute.
- **New adapter methods** (4): `commandSearch`, `commandExecute`, `commandRecent`, `commandSuggestions`.
- **State**: keep local `query/selected/sections`; add `recent`, `suggested`, `pendingPermission`,
`executing` states. Props: extend `GlobalSearchProps` (line 27) with `onExecute` and a workspace-id
for execute scoping. New optional hook `useCommandCenter()` (wraps the 4 adapter calls + debounce) is the
clean home for the provider, mirroring the existing domain-hook pattern.
---
## 5. Backend work (PRD §16.3)
All four are MISSING from the sidecar (grep-confirmed in `backend-routes.md:448-451`; `/api/command/*` =
0 matches in `packages/server/src/local/routes/*.ts`). None needs a new data store — all federate over
existing substrate, consistent with the in-place model.
| PRD §16.3 endpoint | Status | Plan |
|---|---|---|
| `GET /api/command/search?q=` | **MISSING** | **NET-NEW** route file `packages/server/src/local/routes/command.ts`. Federates over existing reads: workspaces (`WorkspaceManager.list()`), memory (`MindDB` full-text, reuse `memory.ts` search), sessions (reuse `sessions.ts` `/sessions/search`), skills (`skills.ts`), connectors (`connectors.ts`), MCPs (from `capabilities/status` `mcpServers[]` + `@waggle/shared` `mcp-catalog.ts`), agents/personas (`personas.ts`+`agent-groups.ts`), and the app/command catalog (extract from a shared catalog to kill the `COMMANDS` drift). Substrate touched: read-only across `memory_frames`, sessions JSONL, install-audit/marketplace, workspace configs. **No `.mind` migration.** |
| `POST /api/command/execute` | **PARTIAL** | EXTEND, do **not** duplicate. `POST /api/commands/execute` (plural, `commands.ts`) already runs slash commands with a real `CommandContext`. Either (a) add a singular `/api/command/execute` alias that broadens the context to also dispatch Navigate/Create/Run/Extend intents (open app, create object, fleet-spawn, install), or (b) widen the existing plural route. Reuses `commandRegistry.execute`, `fleet/spawn`, `marketplace/install`. Substrate: same as the underlying action; add an **install-audit** write for gated executes (`InstallAuditStore.record`, `core/install-audit.ts`). **No migration.** |
| `GET /api/command/recent` | **MISSING** | **NET-NEW** (or derive client-side). Cheapest server path: record executed commands to `ai_interactions` / a small recents list and read back; or derive from session/event history (`events.ts`). Substrate: `ai_interactions` table (read) — no schema change required. |
| `GET /api/command/suggestions` | **MISSING** | **NET-NEW**. Reuse the **workspace-state next-actions** seed: `deriveNextActions` in `packages/server/src/local/workspace-state.ts:182-218` + `buildWorkspaceNowBlock` (`workspace-context.ts`) give cross-workspace suggestion candidates; `skills.ts` `/skills/suggestions` is the skill-domain analog to fold in. Substrate: read-only over memory/awareness/cron. **No migration.** |
Permission gating: the execute route should run gated actions through the existing approval/SecurityGate
path so the FE permission-prompt state has a real backend (reuse `approval.ts` + marketplace SecurityGate).
---
## 6. Shared types needed (PRD §15 vs lib/types.ts)
PRD §15 defines no dedicated Command type, but the palette needs a result/command union. Add to
`apps/web/src/lib/types.ts` (and mirror server-side in the route):
- `CommandResult { id; kind: 'search'|'launch'|'create'|'run'|'navigate'|'extend'; objectType: 'workspace'|'memory'|'artifact'|'session'|'person'|'agent'|'skill'|'connector'|'mcp'|'command'|'app'; title; subtitle?; icon?; score; requiresApproval?: boolean; payload? }` — supersedes the local `SearchResult` interface (`GlobalSearch.tsx:17-25`).
- `CommandExecuteRequest`/`CommandExecuteResult` (success/failure + optional permission descriptor).
- Reuse existing `ApprovalRequest` (`lib/types.ts`) for the permission-prompt state rather than inventing a new one.
- The `objectType` union overlaps PRD §15.2's missing unions (`ArtifactKind`, `AgentType`) and the absent
Artifact entity (substrate-types §e) — Artifact/Agent results are blocked until those screens land (see §7).
---
## 7. Dependencies (screens/phases first)
- **PRD Sprint 3 = Command Center** (PRD lines 1321-1326: indexed search provider, result groups,
command execution, recent/suggested) — this card IS Sprint 3. Depends on **Sprint 1 (Shell + Ctrl+K**,
blueprint `:582`) being the home of the command provider.
- **Search breadth is gated by other screens' substrate.** "artifacts" and "agents/people" facets need:
Artifacts (S05, PRD §16.6 — entirely net-new, substrate-types §e: no Artifact entity exists) and
Agents (S09, PRD §16.7 — sidecar agent CRUD MISSING). Ship Command Center with the **available** facets
(workspaces/memory/sessions/skills/commands/connectors/MCPs) and add artifact/agent facets when those
screens land. Do not block the whole screen on them.
- Execute's Create/Run/Extend intents lean on existing fleet-spawn / marketplace-install / cron — already present.
---
## 8. Effort
**L.** The FE overlay is largely reusable (shell, keyboard nav, debounce all done — that caps it below XL),
but the work spans: 4 net-new/extended backend routes federating across ~8 substrates, an execute +
permission-prompt path with audit writes, recent/suggested providers, a shared `CommandResult` type, and
killing the `COMMANDS`/`appConfig` drift — full-stack across multiple existing route files.
---
## 9. Open questions
1. **Route naming:** add singular `/api/command/*` (PRD-literal) as the new surface, or rename the existing
plural `/api/commands/execute`? Plural is already referenced by `adapter.executeCommand` + `commands.ts`.
Recommend: new singular `command.ts` + alias execute to the existing registry to avoid a breaking rename.
2. **"Open in new window"** affordance in the mockup (top-right) — is the Command Center expected to also
open as a persistent windowed app (an `AppId`), or is it modal-only? Affects whether it needs an
`appConfig`/dock entry vs staying an overlay.
3. **Suggested/recent scope:** cross-workspace blended, or scoped to the active workspace? PRD says
"recent and suggested" without scope; `deriveNextActions` is per-workspace today.
4. **Natural-language commands** (PRD line 464): heuristic intent-parse (cheap, deterministic) vs an LLM
round-trip? The existing `commands.ts` is registry-keyed; NL needs an intent resolver — confirm budget.
5. **Permission prompt reuse:** is the chat approvals pipeline (`approval.ts` + `useChat.pendingApproval`)
the intended mechanism for palette-initiated gated actions, or a lighter inline confirm?
6. The `COMMANDS`-vs-`appConfig` drift (FR #13) — confirm the shared app-catalog refactor is in-scope here
vs a separate cleanup (it is the right place to consolidate `AppId` and retire stale `AppView`).

267
docs/ux-refactor/gap-cards/S04-memory-center.md Normal file
View File

@@ -0,0 +1,267 @@
# Gap Card — S04 Memory Center
> Screen S04 of the Waggle OS UX Refactor. Execution model: **in-place incremental
> refactor** of `apps/web` + targeted backend extension over the existing `.mind`
> substrate. Mockup is directional; PRD §12.4 + §16.4 acceptance criteria win.
> Sources: PRD `docs/Waggle_OS_UX_Refactor_Master_Handoff_Package/Waggle_OS_UX_Refactor_PRD.md`
> (§12.4 lines 484-517, §16.4 lines 1086-1094, §15.4 lines 988-1013, §20.2 line 1276);
> backend-map `sections/03b-api-memory.md`, `sections/05b-subsystem-memory.md`;
> inventories under `docs/ux-refactor/_inventory/`.
---
## 1. Screen & purpose
Make memory **visible, trustworthy, searchable, and editable** (PRD §12.4). Every
memory item must answer: *what do I know, why do I know it, where did it come from,
how confident am I, can I edit it?* (PRD line 517).
Mockup (`screen_04_memory_center.png`, directional) shows a 3-pane layout:
- **Left rail** — search box, type/source/confidence/workspace/tag/date filter facets, scope tabs.
- **Center list** — memory cards (title, type icon, snippet, confidence/importance, source chip, date).
- **Right detail panel** — selected memory: content, type/source/evidence, confidence ring/score,
related memories, connected-graph mini-view, source-evidence chips, and an actions row
(edit / merge / archive / delete / share / add-to-workspace). A right-most column in the
mockup shows aggregate stats (frame count, distribution donut, top entities, recent activity).
This is the **Work-layer** "visible memory" pillar (PRD §1, §6 principle 2, §10.2).
---
## 2. Required states (PRD/Blueprint)
**Tabs (PRD §12.4):** `Active · Workspace · Team · Sources · Graph · Trash`.
**Filters (PRD §12.4):** type, source, confidence, importance, workspace, tag, date.
**Memory detail view fields (PRD §12.4 line 500):** content, type, source, evidence,
confidence, relevance, last used, tags, timeline, connected graph.
**Actions (PRD §12.4 line 502):** edit, merge, archive, delete, share, add to workspace/team;
show related memories + source evidence.
**Screen states (PRD §12.4 lines 504-513 + global §14.1/§14.4):** Empty memory · Importing ·
Consolidating · Active · Low confidence · Conflict · Deprecated · Source unavailable —
plus the global set Loading / Populated / Error / Offline-local-only / Permission-denied /
Partial-data / Approval-required, and the memory lifecycle states Raw/Imported/Working/
Consolidated/Active/Low-confidence/Conflicting/Deprecated/Archived/Deleted-tombstoned (§14.4).
**Acceptance (PRD line 517):** every memory exposes content + source + provenance + confidence
+ edit/delete. Privacy (§18.2): memory source and scope must be visible; user must be able
to archive/delete; team sharing requires explicit scope.
> Blueprint note: `_blueprint_extracted.txt` page 31 ("Screen 4 - Memory Center") is an
> image-only heading — no extra written spec beyond PRD. Cross-refs confirm the rework
> intent: line 571 "Turn `MemoryApp.tsx` into Memory Center with source/confidence/
> evidence/edit actions", line 296 "Visible memory with provenance and [confidence]".
---
## 3. Current state in repo
**Disposition: REWORK** (matches PRD §20.2 line 1276: `MemoryApp.tsx -> Memory Center`).
Substantial reuse of substrate + hook; the screen's tab axis, detail panel, and trust
surfacing are rebuilt.
**Primary component — `apps/web/src/components/os/apps/MemoryApp.tsx` (343 LOC).**
Today it is a 6-tab hub on a *different* axis than the PRD:
- `MEMORY_TABS` (line 46): `timeline | graph | harvest | weaver | wiki | evolution` — NOT the
PRD's `Active/Workspace/Team/Sources/Graph/Trash`. Only **Graph** overlaps 1:1.
- Left sidebar (line 119): search input (`onSearchChange`), a type-filter chip set
(`FRAME_TYPES`, line 21) + a min-importance range slider; flat chronological frame list.
- Detail pane (line 281): renders type icon, title, `type` chip, `importance: N/5`, timestamp,
markdown content, and a raw `metadata` JSON dump (line 310). **Edit button is a no-op
(line 289 — no handler); only Delete is wired.** No source, no confidence, no evidence,
no relevance, no related-memories, no tags, no timeline, no merge/archive/share.
- `readFrameProvenanceTool()` (line 32) already reads `metadata.tool|sourceTool|source` and
renders a small amber provenance badge (line 202) — the **only** trust signal present today.
- `ImportReminderBanner` (line 236) handles the "you have pending imports" nudge.
**Subcomponents — `apps/web/src/components/os/apps/memory/` (6 files):**
- `KnowledgeGraphViewer.tsx` → PRD **Graph** tab (keep-promote, reuse as-is).
- `HarvestTab.tsx` → maps to **Sources** tab inputs (keep; Sources tab wraps/extends it).
- `WeaverPanel.tsx`, `WikiTab.tsx`, `EvolutionTab.tsx`, `ImportReminderBanner.tsx` → these
are **out of the PRD Memory-Center tab set**. Per inventory `frontend.md` (f), Weaver/Wiki/
Evolution belong to the Intelligence layer (traces/distillation). The rework should **move
them off the Memory-Center tab bar** (relocate to their IA home or keep behind a secondary
surface) rather than delete — flag as IA cleanup, not in-scope deletion.
- Grep confirmed: **no file under `memory/` renders confidence/evidence/provenance** beyond the
inline badge in `MemoryApp.tsx`. The trust UI is greenfield.
**Hook — `apps/web/src/hooks/useMemory.ts` (81 LOC).** Provides `frames`, `selectedFrame`,
`filters{types,minImportance,searchQuery}`, `addFrame/editFrame/deleteFrame/incrementAccess/
refresh`, `stats{total,filtered,entities,relations}`. Calls `adapter.getMemoryFrames`,
`searchMemory`, `getMemoryStats`, `addMemoryFrame`, `updateMemoryFrame`, `deleteMemoryFrame`,
`incrementFrameAccess`. **Reuse and extend** (add merge/archive, scope/source/confidence/tag
filters, single-frame fetch).
**Wiring — `Desktop.tsx`:** `const memory = useMemory(activeWorkspaceId)` (line 107);
`<MemoryApp .../>` rendered for appId `memory` (lines 309-316) with `frames/selectedFrame/
searchQuery/stats/typeFilters/minImportance` + KG props (`knowledgeGraph`, `kgScope`). The
appId `memory` already exists in `AppId` (dock-tiers) — no new route needed (single-route
windowed desktop; inventory `frontend.md` §b).
**Frontend type — `apps/web/src/lib/types.ts:118-127` `MemoryFrame`:** `id,type,title,content,
importance:number,timestamp,workspaceId,metadata?`. Note inventory finding: this FE shape does
**not** match what `/api/memory/frames` returns (server `normalizeFrame` emits `source,
source_mind, frameType, accessCount, score, …`, `memory.ts:25-58`) — a real FE/BE contract
mismatch to reconcile in this rework.
---
## 4. Frontend work
**Rework `MemoryApp.tsx` → Memory Center** (keep file path per §20.2; do not create a parallel app).
Components to create/rework (small files, per house rules):
1. **`MemoryApp.tsx` (rework shell)** — replace the 6-tab bar with PRD tabs
`Active | Workspace | Team | Sources | Graph | Trash`. Keep the 3-pane layout
(rail / list / detail). State: `activeTab`, `filters`, `selectedFrameId`, `view`.
2. **`memory/MemoryFilterRail.tsx` (new)** — facet filters: type, source, confidence range,
importance, workspace, tag, date. Drives `useMemory().setFilters`.
3. **`memory/MemoryList.tsx` (new)** — extract the card list out of `MemoryApp`; each card shows
title, type icon, snippet, confidence badge, source chip, date. Loading/empty/error states.
4. **`memory/MemoryDetailPanel.tsx` (new)** — the PRD detail view: content + type + source +
`evidence[]` chips + `ConfidenceBadge` + relevance + last-used + tags + mini-timeline +
connected-graph snippet + related-memories list. Actions row: edit, merge, archive, delete,
share, add-to-workspace/team. Reuse design-system primitives from PRD §19.1
(`Confidence badges`, `Source/evidence chips`, `Status badges`, `Timeline`, `Detail drawer`,
`Approval prompt` for share/delete).
5. **`memory/MemoryEditDialog.tsx` (new)** — wire the currently-dead Edit button
(`MemoryApp.tsx:289`) to `useMemory().editFrame`.
6. **`memory/MemoryMergeDialog.tsx` (new)** — select 2+ frames → call merge adapter method.
7. **Reuse as-is:** `KnowledgeGraphViewer.tsx` (Graph tab), `ContextMenu.tsx`,
`HintTooltip`, `renderSimpleMarkdown`. **Relocate off this tab bar:** `WeaverPanel`,
`WikiTab`, `EvolutionTab`, `HarvestTab` (Harvest folds into the new **Sources** tab).
8. **`overlays/ContextRail.tsx`** is already the right-side full-context rail (`onContextRail`
prop, `MemoryApp.tsx:75,183`) — keep the integration.
**Hook/adapter work (`useMemory.ts` + `lib/adapter.ts`):**
- Extend `MemoryFilters` to `{ types, sources, minConfidence, minImportance, workspaceId,
tags, dateFrom, dateTo, scope, searchQuery }`; filter client-side first, push server-side
where the route supports it (`/api/memory/search` already accepts `since/until/workspace/scope`,
`memory.ts:117-120`).
- New adapter methods (thin wrappers; adapter is the single sidecar contract surface — inventory
`frontend.md` (c)): `getMemoryFrame(id)`, `archiveMemoryFrame(id)`, `mergeMemoryFrames(ids[])`,
`shareMemoryFrame(id, scope)` (Team tab). Team tab reuses existing `searchTeamMemory`
(`adapter.ts:489`).
- Reconcile `MemoryFrame` FE type vs server `normalizeFrame` output (add `source`, `sourceMind`,
`confidence`, `tags`, `evidence`, `status`, `relatedMemoryIds` — see §6).
**States to implement (all PRD-required):** Loading / Empty / Populated / Error / Offline /
Permission-denied / Importing / Consolidating / Low-confidence (badge) / Conflict (badge +
`conflictNote` from `CombinedRetrieval`, backend-map 05b §8) / Deprecated / Source-unavailable /
Trash.
---
## 5. Backend work (PRD §16.4 endpoints)
Status per inventory `backend-routes.md` Part 2 §16.4, re-verified against
`packages/server/src/local/routes/memory.ts` + `knowledge.ts`. Substrate = `memory_frames`
(+`_fts`/`_vec`) and `knowledge_entities/relations` in `packages/hive-mind-core/src/mind/`.
| PRD §16.4 endpoint | Status | Action — EXTEND existing vs NET-NEW · substrate |
|---|---|---|
| `GET /api/memory` | **PARTIAL** | EXTEND: alias/accept on existing `GET /api/memory/frames` (`memory.ts:188`). No new substrate. |
| `GET /api/memory/:id` | **MISSING** | NET-NEW thin route reading `FrameStore.getById(id)` (backend-map 05b §2). `memory_frames`. No migration. |
| `POST /api/memory` | **PARTIAL** | EXTEND: alias on `POST /api/memory/frames` (`memory.ts:237`). |
| `PATCH /api/memory/:id` | **PARTIAL** | EXTEND `PUT /api/memory/frames/:id` (`memory.ts:448`) to accept `PATCH` + bare `:id`. `FrameStore.update`. |
| `POST /api/memory/:id/archive` | **MISSING** | NET-NEW. Model archive as `FrameStore.update(id, importance:'deprecated')` (no hard delete) OR add `status` in the new `metadata` column (§6). `memory_frames`. |
| `DELETE /api/memory/:id` | **PARTIAL** | EXTEND: alias bare `:id` over `DELETE /api/memory/frames/:id` (`memory.ts:551`, → `FrameStore.delete`). |
| `POST /api/memory/merge` | **MISSING** | NET-NEW. Read N frames, synthesize merged content, write one frame, archive/delete the originals. Reuse `FrameStore` + dedup (`findDuplicate`, 05b §2). `memory_frames`. |
| `GET /api/memory/graph` | **EXISTS** | `knowledge.ts` `GET /api/memory/graph?scope=` — Graph tab. No work. |
**Adjacent reuse (no new endpoint):** Team tab → existing `GET /api/team/memory/search`
(`team.ts`, **Tier: TEAMS**, inventory backend-routes 1.8); Sources tab → existing
`GET /api/harvest/sources` (`harvest.ts`); stats column → existing `GET /api/memory/stats`
(`memory.ts:391`); conflict/relevance signals available from `CombinedRetrieval`
(backend-map 05b §8 `hasConflict`/`conflictNote`, `finalScore` relevance).
**.MIND MIGRATION FLAG (one, low-risk).** To back confidence / provenance-id / source-url /
tags / evidence / kind / title / status / relatedMemoryIds, `memory_frames` has **NO metadata
column today** (substrate-types.md (c): unlike `awareness.metadata` etc.). The migration runner
already does idempotent additive `ADD COLUMN` (precedent: it added `source`, `mind/db.ts:116-124`).
**Recommended:** ONE additive migration adding nullable
`metadata TEXT NOT NULL DEFAULT '{}'` to `memory_frames`, storing
`{kind,title,scope,sourceId,sourceUrl,confidence,tags,evidence,relatedMemoryIds,status}` as JSON.
This avoids touching the FTS5/vec0 virtual tables and the IPB scoring path. If `confidence`
becomes a primary filter/sort axis (PRD "filter by confidence" / "low-confidence surfaced"),
promote `confidence REAL` to a real indexable column in a later migration (same ADD-COLUMN
pattern). PRD §15.4 line 1013 explicitly endorses metadata-first.
> Latent-bug flag (not session-induced, surfaced by substrate-types.md (d)): `AuditRiskLevel`
> TS includes `'critical'` but the DDL CHECK allows only `low/medium/high` — irrelevant to S04
> but the same install-audit store backs Sources-tab provenance if surfaced; note for the plan.
---
## 6. Shared types needed (PRD §15 vs `lib/types.ts`)
PRD §15.2 unions — **none exist in `apps/web/src/lib/types.ts`** (substrate-types.md (e)):
- Add `MemoryKind = 'fact'|'decision'|'task'|'preference'|'strategy'|'learning'|'goal'|'entity'`
(PRD line 949). Current `MemoryFrame.type` (`types.ts:120`) uses `fact/event/insight/decision/
task/entity` — OVERLAPS but mismatched (`event`/`insight` vs PRD `preference/strategy/learning/
goal`). Reconcile.
- Add `Scope = 'personal'|'workspace'|'team'|'organization'` (line 945) — drives the Active/
Workspace/Team tab partition. Today scope is IMPLICIT (which `.mind` file; surfaced as `_mind`
tag, `memory.ts:34`).
- Add `Confidence = number` (0-100, line 946).
Extend `MemoryFrame` (PRD §15.4, lines 990-1013) toward: `kind, title, content, scope,
workspaceId, teamId, source, sourceId, sourceUrl, confidence, importance, evidence[], tags[],
relatedMemoryIds[], relatedArtifactIds[], createdAt, updatedAt, lastAccessedAt, status`.
`relatedArtifactIds[]` stays **deferred** (no Artifact entity exists yet — that's S05;
substrate-types.md (e)). Also fix the FE-type ↔ `normalizeFrame` mismatch noted in §3/§4.
---
## 7. Dependencies (screens/phases first)
- **Phase placement:** PRD §8 Phase 2 / Sprint 4 (Memory + Artifacts). Depends on **Phase 0**
(shared frontend types + AppShell/IA freeze — the §15.2 unions live there) and on the
workspace-state/context contract from Phase 1.
- **Workspace scope** (`scope`/`workspaceId`) presupposes the S01/S02 workspace-type-and-status
fields (`WorkspaceConfigV2`, substrate-types.md (a)) for the Workspace/Team partition; usable
with the implicit `_mind` scope before that lands, so soft dependency only.
- **Team tab** depends on TEAMS tier + the team substrate (S10 Team Workspace); gate behind
`useFeatureGate`/tier and degrade to a "Teams feature" empty state otherwise.
- **Sources tab** reuses Harvest (already shipped); the broader Memory Import onboarding (S15/S16)
is independent.
- **No dependency on S05 Artifacts** for v1 (defer `relatedArtifactIds`).
- Open question O3 (PRD line 1418): Graph view in v1 or later — Graph already works, so keep.
---
## 8. Effort: **L**
Frontend is a multi-pane rework with a brand-new trust/detail surface (confidence, evidence,
related, merge, archive, share) replacing a thin detail pane, plus 4-5 new subcomponents and a
hook/adapter/type reconciliation. Backend is mostly EXTEND/alias over existing memory routes
(7 of 8 endpoints), but the trust fields require **one additive `.mind` migration** + a real
`merge` endpoint + a `:id` read + an archive path — net-new logic, low schema risk. The single
migration and the FE/BE `MemoryFrame` contract reconciliation push this past M into L.
---
## 9. Open questions
1. **Confidence source.** `memory_frames` has no confidence today; `knowledge_relations.confidence`
exists (edges only, schema.ts:93). Do we (a) store confidence in the new `metadata` JSON,
(b) promote to a `REAL` column now for indexable low-confidence filtering, or (c) derive a
proxy from `source` trust-class + `importance` until real confidence is computed? (PRD §12.4
wants "filter by confidence" + "low-confidence surfaced for review".)
2. **Conflict detection surfacing.** `CombinedRetrieval.detectConflict` (05b §8) yields
`hasConflict`/`conflictNote` at recall time, not as a stored per-frame state. Is the PRD
"Conflict" state (§14.4) a live recall-time signal or a persisted frame status?
3. **Archive vs deprecate vs tombstone.** PRD §14.4 distinguishes Deprecated / Archived /
Deleted-tombstoned. `importance:'deprecated'` exists; is "archive" a distinct status (needs
the `metadata.status` field) or an alias of deprecate? Delete = hard `FrameStore.delete` or
tombstone? (PRD Open Question O8, line 1423.)
4. **Merge semantics.** Does `POST /api/memory/merge` LLM-synthesize a combined frame, or just
concatenate + re-cognify? What happens to the originals (archive vs hard delete)?
5. **Tab-relocation scope.** Confirm Weaver/Wiki/Evolution move OUT of the Memory-Center tab bar
to their Intelligence-layer home (frontend.md (f)) is in-scope for S04, or deferred to the IA
pass so S04 only adds the new tabs and leaves the legacy ones temporarily.
6. **`MemoryKind` reconciliation.** Drop FE `event`/`insight` and add PRD `preference/strategy/
learning/goal`? This changes existing frame rendering + the type-filter chips.

243
docs/ux-refactor/gap-cards/S05-artifact-center.md Normal file
View File

@@ -0,0 +1,243 @@
# Gap Card — S05 Artifact Center
> Execution model: **in-place incremental refactor** of `apps/web` + targeted backend extensions.
> Mockups are directional; PRD acceptance criteria win over pixels (PRD §24).
> Sources: PRD §12.5 + §16.6, blueprint p.32 (`_blueprint_extracted.txt:306-317, 525, 547`),
> mockup `screen_05_artifact_center.png`, baseline inventories under `docs/ux-refactor/_inventory/`,
> backend-map `sections/04-feature-map.md`.
---
## 1. Screen & purpose
The **Artifact Center** is the **outcome layer**: it organizes *outputs* (documents, presentations,
spreadsheets, dashboards, research, code, media, designs, other) as first-class **relational objects** —
not file attachments. PRD §12.5 purpose verbatim: "Organize outcomes, not just attachments." The
headline acceptance criterion (PRD line 532): **searching a topic (e.g. "Germany GTM") returns all
relevant outcome objects plus related memories, sessions, tasks, agents, and people — not just files.**
Mockup (directional): left filter rail (type / status / workspace / tag facets), a center **artifact
table** (icon, title, type, workspace, status badge, updated, owner) with a top search bar + view
toggle + pagination, and a right **detail panel** (preview thumbnail, metadata, related items, actions).
This is a **data-heavy table+detail screen**, the same shape the blueprint flags as acceptable in light
variant (`_blueprint_extracted.txt:484`).
The defining difference from today's Files app: an artifact is an **outcome with relations**
(`relatedMemoryIds / relatedSessionIds / relatedTaskIds / relatedAgentIds`,
`generatedByAgentId`, `status: draft|final|shared|generated`), addressable by a stable `id`, spanning
**all storage backends and all formats**. Today's Files app exposes only a raw filesystem tree scoped to
one workspace + one storage tab.
---
## 2. Required states (PRD / Blueprint)
PRD §12.5 functional requirements:
- Artifact **categories** (= `ArtifactKind`, PRD §15.2 line 950): `document | presentation |
spreadsheet | dashboard | research | code | media | design | other`.
- **Topic search returns artifacts + related memories/sessions/tasks/agents/people** (the §16.6
`GET /api/artifacts/search-related?q=` contract).
- **Detail panel**: preview, metadata, workspace, creator, updated time, access, status, tags, related
items, actions.
- **Actions**: open, share, duplicate, move, delete, relate to workspace/memory/session/task.
State model — PRD §14.1 global states (every major screen): Loading, Empty, Populated, Error,
Offline/local-only, Syncing, Permission denied, Partial data, Approval required.
Plus the **artifact-specific states** (PRD §14 line not enumerated but blueprint `:312-314, 458`):
**Draft, Final, Shared, Generated, External-missing (source unavailable), Permission denied.**
So the concrete states to build:
1. Loading (skeleton table + skeleton detail).
2. Empty ("no artifacts yet" — first-run / no outputs produced).
3. Populated (table + facets + detail).
4. Error (fetch failed).
5. Offline/local-only (sidecar unreachable — mirror FilesApp offline banner pattern).
6. Permission denied (team-scoped artifact the user can't view).
7. Per-row status badges: Draft / Final / Shared / Generated.
8. Source-unavailable (artifact row whose backing file/url is missing — show broken-link affordance).
---
## 3. Current state in repo (disposition: **create-new** for the screen; **keep-promote** the substrates)
**There is NO Artifact entity, type, route, or component anywhere.** Grep-confirmed:
- No `Artifact` type in `apps/web/src/lib/types.ts` (the only `Artifact` hit in `apps/web/src` is
`components/os/apps/memory/EvolutionTab.tsx`, referring to evolution `artifacts_json` — unrelated).
- No `artifacts` table in `packages/hive-mind-core/src/mind/schema.ts`.
- No `/api/artifacts/*` routes (grep over `packages/server/src/local/routes/*.ts`: 0 matches).
- Confirmed by `_inventory/substrate-types.md:259-266` ("**NO backing entity anywhere** … the single
largest entity gap") and `_inventory/backend-routes.md:476-484` (all 6 §16.6 rows PARTIAL/MISSING).
**The closest current surface is the Files app** (the current-component hint), which is **NOT an
artifact center** — disposition for it is **keep-as-is, do not retrofit**:
- `apps/web/src/components/os/apps/FilesAppTabs.tsx` — P16 three-tab (Virtual/Local/Team) wrapper that
remounts `FilesApp` per `storageType`. Storage-location switcher, not an outcome browser.
- `apps/web/src/components/os/apps/FilesApp.tsx` (735 LOC) — full file-manager: tree + list/grid +
preview + upload + rename/move/copy/delete + bulk ops + properties dialog + inline `VersionHistory`.
It is **path/workspace/storage-scoped** (`adapter.listFiles(workspaceId, currentPath)`), has no
cross-workspace aggregation, no type/status/relation model, no facet filtering by outcome kind.
- Sub-components `components/os/files/{FileTree,FilePreview,FileActions,FileUploadZone,SyntaxPreview,
WorkspaceRail}.tsx` — operate on `FileEntry` (`lib/types.ts:42-50`: `name/path/type/size/mimeType/
modifiedAt/createdAt`), a raw FS entry, not an outcome object.
**Three existing backend substrates the new Artifact layer must aggregate over (reuse, do not duplicate):**
1. **Workspace file registry** — `GET /api/workspaces/:id/files` (`workspaces.ts:594-606`) returns
`readFileRegistry(dataDir, id)` of `FileRegistryEntry { name, type, summary, sizeBytes, ingestedAt }`
(`routes/ingest.ts:125-130`). This is an **ingest log**, newest-first — closest thing to a
per-workspace "produced/ingested things" list, but no id, no status, no relations.
2. **Document version registry** — `GET /api/workspaces/:id/documents` +
`/documents/:name/versions` (`routes/documents.ts`, JSON at
`~/.waggle/workspaces/{id}/documents.json`, shapes `TrackedDocument`/`DocumentVersion`). Gives
versioning + size + createdAt keyed by name; already surfaced in FilesApp's `VersionHistory`
(`FilesApp.tsx:27-54`). No type/status/relations.
3. **Workspace storage files** — `GET /api/workspaces/:id/storage/files` + `/storage/read|write|delete`
(`workspaces.ts:885+`) — the actual byte store for virtual/local/team.
**Verdict:** the screen is **create-new** (`ArtifactCenter` is in PRD §20.3 "Create" list, line 1289).
The backend is **a thin net-new aggregation/normalization layer over the three existing stores** — no
new data store required (`_inventory/backend-routes.md:604-607`).
---
## 4. Frontend work
**New top-level app (dock id `artifacts`).** Register in `Desktop.tsx` `appConfig` + `renderAppContent`
switch, add `AppId` `'artifacts'` in `lib/dock-tiers.ts`, and a Work-bucket dock entry (the IA maps
Artifacts to the **Work** layer — `_inventory/frontend.md:360`). Do **not** route — this is a windowed
single-route desktop; opening is by `AppId` via `openApp` (`useWindowManager`).
Components to **create** (keep files small, ~200-400 LOC each per repo file-org rule):
- `components/os/apps/ArtifactCenterApp.tsx` — shell: search bar + view toggle + facet rail + table +
detail panel + pagination. Owns query/filter/selection state. Mirrors the FilesApp three-pane layout
idiom (rail / main / detail) so it feels native.
- `components/os/artifacts/ArtifactTable.tsx` (or `ArtifactRow.tsx` — blueprint names `ArtifactRow`,
`_blueprint_extracted.txt:487`) — list rows with icon/title/type/workspace/status badge/updated/owner.
- `components/os/artifacts/ArtifactFacetRail.tsx` — type/status/workspace/tag facet filters (left rail in mockup).
- `components/os/artifacts/ArtifactDetailPanel.tsx` — preview + metadata + related-items list + actions.
- `components/os/artifacts/ArtifactRelatedList.tsx` — renders related memories/sessions/tasks/agents;
clicking a related item should raise the relevant window via the existing `waggle:open-app`
CustomEvent (and/or `onContextRail` like FilesApp does, `FilesApp.tsx:206-208`).
**Reuse targets (do not rebuild):**
- Status/confidence badges, `Skeleton`, `Table`, view-toggle, `Pagination`, `HoverCard` — all exist in
`components/ui/*` (shadcn set, `_inventory/frontend.md:337-342`).
- Offline banner pattern + retry — copy from `FilesApp.tsx:384-389`.
- File preview for an artifact's backing file — reuse `components/os/files/FilePreview.tsx`.
- Empty-state idiom — `FilesApp.tsx:470-477`.
- Detail-panel metadata layout idiom — FilesApp Properties dialog (`FilesApp.tsx:667-729`).
- ContextRail for "show full context of this artifact" — `overlays/ContextRail.tsx` already exists
(extend `ContextRailTarget` with an `'artifact'` variant).
**New hook + adapter methods:**
- `hooks/useArtifacts.ts` — `{ artifacts, filters, setFilter, selected, select, search, refresh,
create, patch, remove, share }`; reads/writes through the adapter. Follow the `useMemory` shape
(`hooks/useMemory.ts`).
- Extend `lib/adapter.ts` (the single sidecar gateway, ~1930 LOC — new §16 methods land here per
`_inventory/frontend.md:380`) with: `getArtifacts`, `getArtifact`, `createArtifact`,
`patchArtifact`, `deleteArtifact`, `searchRelatedArtifacts`, `shareArtifact`.
**Props/state notes:** `ArtifactCenterApp` takes `{ workspaces?, activeWorkspaceId?, onSelectWorkspace?,
onContextRail? }` (same cross-workspace pattern FilesApp uses). It is **cross-workspace by default**
(the whole point vs FilesApp) — workspace becomes a *facet*, not a hard scope.
---
## 5. Backend work (PRD §16.6)
> No new data store. Every endpoint is a **net-new aggregation/normalization route** over the existing
> file registry + document versions + workspace storage. New file:
> `packages/server/src/local/routes/artifacts.ts`, registered in `local/index.ts`. The Artifact `id`
> can be a stable composite of `workspaceId + source-store + name/path` (or a registry-assigned id if a
> lightweight `artifacts.json` index is added per workspace, mirroring `documents.json`).
| PRD §16.6 endpoint | Status | Plan (EXTEND vs NET-NEW) + substrate |
|---|---|---|
| `GET /api/artifacts` | **PARTIAL → NET-NEW route** | No `/api/artifacts` domain. NET-NEW `GET /api/artifacts` in `artifacts.ts` that **fans out over `WorkspaceManager.list()`** and, per workspace, normalizes (a) file registry `GET /api/workspaces/:id/files` (`workspaces.ts:594`, `FileRegistryEntry`), (b) document versions `GET /api/workspaces/:id/documents` (`documents.ts`), into a unified `Artifact[]`. Supports `?workspaceId=&type=&status=&tag=&q=` facet filters. Cross-workspace = the differentiator. |
| `POST /api/artifacts` | **PARTIAL → NET-NEW route (thin)** | Closest writes that already persist bytes: `POST /api/ingest` (`ingest.ts`), `POST /api/workspaces/:id/files/upload` (`files.ts`), `POST /api/workspaces/:id/documents` (`documents.ts`), `POST /api/workspaces/:id/storage/write` (`workspaces.ts`). NET-NEW `POST /api/artifacts` records artifact metadata (kind/title/status/tags/relations + `generatedByAgentId`) in a per-workspace `artifacts.json` index and (optionally) writes the backing file via the storage route. |
| `GET /api/artifacts/:id` | **MISSING → NET-NEW** | Resolve composite id → normalized `Artifact` with relations + preview metadata. Reuse `documents.ts` version lookup for `relatedVersions`. |
| `PATCH /api/artifacts/:id` | **MISSING → NET-NEW** | Update title/status/tags/relations in the `artifacts.json` index (move = re-point `workspaceId`/`storagePath`; reuse `files/move`). |
| `DELETE /api/artifacts/:id` | **PARTIAL → NET-NEW route** | Closest: `POST /api/workspaces/:id/files/delete` (`files.ts`), `DELETE /api/workspaces/:id/storage/delete` (`workspaces.ts`). NET-NEW `DELETE /api/artifacts/:id` removes the index entry and (optionally) the backing file via those. |
| `GET /api/artifacts/search-related?q=` | **MISSING → NET-NEW (the headline endpoint)** | Federated search: query the normalized artifact index **plus** `GET /api/memory/search` (`memory.ts`), session search `GET /api/workspaces/:wid/sessions/search` (`sessions.ts`), tasks `GET /api/tasks` (`tasks.ts`), and fleet/agents (`GET /api/agents/active`/`/api/fleet`), returning grouped `{ artifacts, memories, sessions, tasks, agents }`. Internally can lean on existing FTS (`memory_frames_fts`, marketplace FTS5, wiki search). Delivers PRD line 532 acceptance. |
| `POST /api/artifacts/:id/share` (blueprint `:525`) | **MISSING → NET-NEW** | Blueprint adds a `/share` action not in PRD §16.6 list. Maps to the missing `POST /api/share` (`_inventory/backend-routes.md:551`) + team scope. Defer to the Team phase (see §7); gate behind TEAMS tier like `/api/team/*`. |
**Substrate touched:** workspace file registry (`ingest.ts` `FileRegistryEntry`), document versions
(`documents.ts` JSON), workspace storage (`workspaces.ts` storage routes), memory FTS
(`memory_frames_fts`), sessions JSONL, tasks store, fleet/orchestrator. **No `.mind` migration
required** for a metadata-first implementation: artifact metadata + relations live in a per-workspace
`artifacts.json` index (same pattern as `documents.json`). If artifacts must later be queryable in SQL
alongside frames, a future additive `artifacts` table in `schema.ts` follows the established
idempotent ADD-pattern (`mind/db.ts:116-124`) — flag, not now.
**Governance note:** if agent-generated artifacts (`generatedByAgentId`) need an audit trail, reuse
`InstallAuditStore`/`emitAuditEvent` (`workspaces.ts:631` already emits `workspace_update`) rather than
a parallel log.
---
## 6. Shared types needed (PRD §15.2 / §15.6 vs `lib/types.ts`)
**Net-new, none exist today** (`_inventory/substrate-types.md:226, 259-266`):
- `ArtifactKind` union (PRD §15.2 line 950) — add to `lib/types.ts` (and `packages/shared/src/types.ts`
if the sidecar route also imports it, to keep one contract).
- `ArtifactStatus = 'draft' | 'final' | 'shared' | 'generated'` (from blueprint states `:312`,
PRD §14 artifact states). Note blueprint also implies `external-missing`/`source-unavailable` —
model as a derived flag, not a status value.
- `Artifact` interface — PRD §15.6 (lines 1039-1056) ∪ blueprint `:547`: `id, title, kind, workspaceId,
teamId?, createdBy, generatedByAgentId?, source, status, mimeType?, storagePath?, previewUrl?,
summary?, tags[], relatedMemoryIds[], relatedSessionIds[], relatedTaskIds[], relatedAgentIds[],
createdAt, updatedAt`.
- `RelatedSearchResult` — the grouped `{ artifacts, memories, sessions, tasks, agents }` envelope for
`search-related`.
**Reconcile, don't fork:** define `Artifact`/`ArtifactKind`/`ArtifactStatus` **once** (shared package
preferred) so the sidecar route and the frontend hook share the contract — avoid the existing
FE↔BE `MemoryFrame` drift the inventory flags (`_inventory/substrate-types.md:246-247`). Optionally add
`relatedArtifactIds[]` to the memory side later (PRD §15.4) so the relation is bidirectional.
---
## 7. Dependencies (screens / phases first)
- **PRD Phase 2 — Work layer** (this screen's home; Memory Center is its sibling, Sprint 4). The
`search-related` federated endpoint is the binding dependency on Memory (FTS) + Sessions + Tasks.
- **AppShell / dock IA (Phase 0/1)** must exist first so `artifacts` registers as a Work-bucket dock
entry (consolidate on `AppId`, retire stale `AppView`).
- **Command Center (Ctrl+K) (Phase 1)** should index artifacts (`_blueprint_extracted.txt:515` — command
index unifies artifacts) — soft dependency; Artifact Center can ship before Ctrl+K wires it in.
- **`WorkspaceConfigV2` `type`/`status` fields** (S-workspace cards) help facet labels but are not
blocking.
- **Team Workspace / RBAC (Phase 5)** gates `POST /api/artifacts/:id/share` + permission-denied state.
Ship Artifact Center personal-scoped first; share/team-scope is a follow-on.
- **Agent run → artifact linkage** (PRD Journey 7, §15.6 `generatedByAgentId`) depends on the agent
runtime writing artifact records — a downstream integration, not a blocker for the read/browse screen.
---
## 8. Effort: **L**
Net-new full-stack surface: 5-6 new frontend components + a new hook + 7 new adapter methods, **plus**
a net-new backend aggregation domain (`artifacts.ts`, ~6 routes) that must normalize **three** existing
stores into one entity and a **federated** search across memory/sessions/tasks/agents. No new DB and
heavy component/route reuse keep it out of XL, but the cross-workspace aggregation + the
`search-related` federation + a brand-new shared `Artifact` contract make it clearly more than M.
---
## 9. Open questions
1. **Artifact identity & index.** Synthesize `id` as a composite (`workspaceId:store:name`), or add a
per-workspace `artifacts.json` index (mirroring `documents.json`) that assigns stable ids and holds
status/tags/relations? (PATCH/relations effectively require the latter.) → maps to PRD Open Q6
(storage: workspace FS vs virtual store vs external refs, PRD line 1421).
2. **What counts as an artifact in v1?** Only explicit outputs (generated docs/decks/etc.), or every
ingested file in the registry? The registry mixes ingested inputs with produced outputs — need a
classification rule for `kind`/`status`.
3. **`search-related` scope/cost.** Federating memory FTS + sessions + tasks + agents per query — cap
per-source result counts and run async result groups (PRD §24 perf mitigation), or a single indexed
provider? (Mirrors the Command Center search concern.)
4. **Share semantics (blueprint `/share` vs PRD `/api/share`).** Is `POST /api/artifacts/:id/share`
in-scope for the first Artifact Center cut, or deferred entirely to the Team phase?
5. **Preview generation.** `previewUrl`/thumbnails — generate server-side, reuse `FilePreview`
on-demand client-side, or skip thumbnails in v1 (icon + on-click preview only)?
6. **Bidirectional relations.** Do we add `relatedArtifactIds[]` to memory frames now (PRD §15.4) or
keep relations one-directional (artifact → others) in v1?

153
docs/ux-refactor/gap-cards/S06-skills-hub.md Normal file
View File

@@ -0,0 +1,153 @@
# Gap Card — S06 Skills Hub (+ Skill Builder)
> Screen 06 of the Waggle OS UX-refactor. Sources: PRD §12.6 + §16.8 + §15 (`docs/Waggle_OS_UX_Refactor_Master_Handoff_Package/Waggle_OS_UX_Refactor_PRD.md`),
> blueprint extract pp.33 + screen-table row 6 + states table (`_blueprint_extracted.txt`),
> mockup `Waggle_OS_Handoff_Assets/screen_06_skills_hub.png` (directional only),
> backend-map `sections/03d-api-marketplace-skills.md` + `sections/05g-subsystem-skills-marketplace-wiki.md`,
> and live repo grep/read. Execution model: **in-place incremental refactor** of `apps/web` + targeted backend extension.
---
## 1. Screen & purpose
**Skills Hub** — the surface where reusable capabilities (a "skill" = a Markdown file in `~/.waggle/skills/{name}.md`, injected into the agent system prompt) are browsed, installed, authored, tested, and assigned to agents/workspaces. Blueprint row 6: *"Reusable capabilities across users, workspaces and agents. Install, create, test, assign to agent/workspace, archive."* Acceptance criterion (PRD §12.6 / blueprint): *"A user can understand what a skill does, where it is used, and what access it has."*
The mockup shows a left rail of category/state filters, a **My Skills** table (name / category / status / usage / last-used columns), a **Marketplace** panel, a **Workspace Skills** table, a **Custom Skills** panel, and a **Create Skill** CTA — i.e. a unified library + marketplace + builder entry, replacing the current "Skills & Apps" pack-grid.
Per the locked IA (frontend.md §f), this is the **Intelligence** layer, expressed through the existing dock/window-manager (`AppId='capabilities'`, dock key `skills`) — NOT a new route. The PRD also pairs this screen with the **Skill Builder** (PRD §12.6 5-step stepper; PRD §20.3 lists `SkillBuilder` under "Create").
---
## 2. Required states (PRD / Blueprint)
PRD §12.6 functional requirements:
- **Skills Hub tabs:** My Skills · Marketplace · Custom Skills · Workspace Skills.
- **Skill object fields:** name, description, category, instructions, inputs, outputs, tools/data, memory access, owner, status, usage, last used.
- **Skill Builder steps:** Basic Info · Instructions · Inputs & Outputs · Tools & Data · Review & Create.
- Support **test run before publishing**.
- Skills can be **assigned to agents, workspaces, automations, or used directly**.
Blueprint per-object states (states table) for **Skills**: `Loading, empty, populated, error` + item states `Installed, draft, custom, workspace, marketplace, update available`; actions `Test, install, publish, archive, rollback`. PRD §14.7 Extension states also apply: `Available / Installed / Update available / Installing / Failed install / Risk approval required / Disabled-revoked`.
Global states every screen must implement (PRD §14.1): Loading · Empty · Populated · Error · Offline/local-only · Syncing · Permission denied · Partial data · Approval required.
**Trust/tier state (load-bearing):** custom skills + marketplace install/publish are PRO-gated; FREE = built-in skills only (`tiers.ts`; 05g §19). A `403 → upgrade` state is required on create/install/publish.
---
## 3. Current state in repo
**Disposition: `partial`** — strong backend + a real (but mislabelled) hub component exist; the screen needs **rework** of the FE component to the PRD tab/table model, plus a **net-new Skill Builder** and **thin backend extensions** for `:id/test`, `:id/install`, and skill scope (workspace/custom).
### Frontend (exists, reworkable)
- `apps/web/src/components/os/apps/CapabilitiesApp.tsx` — the live Skills surface ("**Skills & Apps**" header, line 339). Tabs are `installed | starter | marketplace | tools | audit` (line 80, 358) — a **pack-centric grid**, NOT the PRD's My/Marketplace/Custom/Workspace tabs. Renders `PackCard`/`PackDetail` over `SkillPack` (pack groupings), has skill **test preview** (`handleTestSkill` → `POST /api/skills/test`, lines 88-102), pack install with `403→UpgradeModal` routing (`handleInstallError`, lines 149-162), a `tools` read-only catalog, and an `audit` tab (`GET /api/audit/installs`). Reachable via dock key `skills` → `appId 'capabilities'` (`lib/dock-tiers.ts:64`).
- `apps/web/src/components/os/apps/MarketplaceApp.tsx` — standalone marketplace browser (search/install/uninstall over `/api/marketplace/*`); registered as `appId 'marketplace'` but **no dock entry points at it** (frontend.md §a). Marketplace is doubly-represented (here + folded into CapabilitiesApp) — an IA-cleanup point for this screen.
- Adapter methods already wired (`lib/adapter.ts`): `getSkills`, `createSkill`, `getStarterPacks`, `getCapabilityPacks`, `installPack`, plus full marketplace set (frontend.md §c).
- Types: `SkillPack` (`lib/types.ts:210-218`: id/name/description/category(5-enum)/skills[]/installed/trust) — a **pack** shape, NOT the PRD per-skill `Skill` object. No `Skill`/`SkillScope`/`SkillStatus`/`ExtensionType` type in FE (substrate-types.md §e).
### What does NOT exist (gaps)
- **No `SkillBuilder` component** anywhere (grep confirmed — the only `SkillBuilder`/`Custom Skill` string matches are upgrade-modal copy in `TrialExpiredModal.tsx`/`UpgradeModal.tsx`). PRD §12.6 5-step builder is **net-new FE**.
- **No "Workspace Skills" / "Custom Skills" scoping at runtime.** Skills are flat files in `~/.waggle/skills/` (05g §8); the prompt loader ignores frontmatter (`loadSkills`, 05g §2 note). A `SkillScope` (`personal|workspace|team|enterprise`) exists only in `skill-frontmatter.ts` frontmatter + the `promote_skill` path — not persisted/queryable by the skills route (grep `scope|workspace` in `routes/skills.ts` → **0 matches**). So the PRD's Workspace/Custom tabs have **no backing filter today**.
### Backend (mostly exists — see §5)
`packages/server/src/local/routes/skills.ts` already serves list/create/get/update/delete + `test` + `suggestions` + `hash-status` + starter/capability-pack catalogs + `/api/audit/installs`. Substrate detailed in 05g (skill-creator / -recommender / -usage / -retirement / -watcher) and 03d.
---
## 4. Frontend work
**Rework `CapabilitiesApp.tsx` → Skills Hub** (keep the file; this is the in-place refactor target), and **create `SkillBuilder`**. Reuse the existing window-manager surface (no new route); resolve the marketplace double-representation by making Skills Hub the canonical host and retiring/redirecting `MarketplaceApp`'s dead `appId`.
**Components to rework / create**
- **Rework** `CapabilitiesApp` tab model: `installed|starter|marketplace|tools|audit` → PRD **My Skills · Marketplace · Custom · Workspace** (keep `tools`/`audit` as secondary panels or fold `audit` into a detail-drawer "install history"). My Skills must render a **per-skill table** (name/category/status/usage/last-used per mockup), not just a pack grid.
- **Create** `SkillCard` / `SkillRow` (per-skill, distinct from `PackCard`) — design-system `SkillCard` is named in PRD §19.1 + blueprint components list. Show status badge (installed/draft/custom/workspace/update-available — PRD §14.7) and trust chip (reuse `lib/skill-pack-display.ts` `describeTrust`).
- **Create** `SkillBuilder.tsx` overlay (PRD §20.3 "Create") — `Builder stepper` (PRD §19.1) with the 5 steps. Pattern-match the existing builder/wizard idioms (`overlays/onboarding/*` step components, `CreateWorkspaceDialog`, `SpawnAgentDialog`). Step 5 "Review & Create" wires a **test run** before publish.
- **Create/extend** a `useSkills` hook (none exists today — `CapabilitiesApp` calls `adapter` directly via `Promise.allSettled`, lines 104-145). New hook returns `{ skills, packs, marketplace, install, create, test, refresh }`; keep `403→'waggle:tier-insufficient'` event routing (CapabilitiesApp lines 149-162) and `UpgradeModal` wiring intact.
**Reuse targets**
- `POST /api/skills/test` → already wired (`handleTestSkill`); reuse for builder Step 5 + per-skill test.
- `GET /api/skills/starter-pack/catalog` / `capability-packs/catalog` → already supply `state` per skill (`active|installed|available`); reuse for Marketplace/My-Skills state.
- `GET /api/skills/suggestions?context=` → recommended-skills strip.
- `dedupePacks`, `skill-pack-display`, `skill-recommendations`, `HintTooltip` — existing libs to keep.
**Props/state**
- `Skill` type (new, §6): `{ name, description, category, status, scope, usageCount, lastUsedAt, trust, instructions?, inputs?, outputs?, tools?, memoryAccess?, owner? }`.
- Builder form state mirrors `POST /api/skills/create` body (`{ name, description, steps[], tools?, category? }`) extended with inputs/outputs/memoryAccess once §5 lands.
**Adapter methods to add** (`lib/adapter.ts`): `testSkill(id, testInput?)` (path variant), `installSkill(id)` (unified dispatch), `updateSkill(id, patch)`, and scope-aware `getSkills({scope})` once the backend filter exists.
---
## 5. Backend work — PRD §16.8 endpoint-by-endpoint
> Cross-ref against backend-map 03d/05g + `routes/skills.ts`. Skills are flat files in `~/.waggle/skills/`; the marketplace is `~/.waggle/marketplace.db`. **No `.mind` migration is required for §16.8** — skills/marketplace are not in the `.mind` SQLite schema. (One optional migration is flagged below for the *install-audit critical column*, see "Cross-cutting".)
| PRD §16.8 endpoint | Status | Extend vs net-new | Substrate touched |
|---|---|---|---|
| `GET /api/skills` | **EXISTS** | as-is (`routes/skills.ts`, 05g §8) — returns `{ skills:[{name,length,preview}], count, directory }` | `~/.waggle/skills/*.md` |
| `POST /api/skills` | **EXISTS** | as-is — raw create `{name,content}`; structured create is `POST /api/skills/create` `{name,description,steps[],tools?,category?}` (the Builder's real target) | `~/.waggle/skills/*.md` + `redactSkillContent` + `skillHashStore` + install-audit |
| `PATCH /api/skills/:id` | **PARTIAL** | **EXTEND** existing `PUT /api/skills/:name` (keyed by **name**, method `PUT`). Add a `PATCH` alias and accept `:id`↔`:name`. No new substrate. | `~/.waggle/skills/*.md` |
| `POST /api/skills/:id/test` | **PARTIAL** | **EXTEND** existing `POST /api/skills/test` (body-driven `{skillName,testInput?}`) — add the `:id` path variant routing to the same handler. Sandbox/dry-run only (parses frontmatter, shows `wouldInject`); no execution. | skill file + `parseSkillFrontmatter` |
| `POST /api/skills/:id/install` | **PARTIAL** | **NET-NEW thin dispatcher** over existing installs: `POST /api/skills/starter-pack/:id`, `POST /api/skills/capability-packs/:id`, `POST /api/marketplace/install` (PRO-gated, SecurityGate). `/skills/:id/install` resolves the source and delegates. Keep the `requireTier('PRO')` gate for marketplace-sourced skills. | marketplace.db + `MarketplaceInstaller` + `SecurityGate` + install-audit |
**Result: 0 net-new domains, 0 net-new stores.** 16.8 is `2 EXISTS / 3 PARTIAL` (matches `backend-routes.md` §16.8). All gaps are aliases/dispatchers over existing handlers.
**Backend gaps the PRD §12.6 tab model implies but §16.8 does NOT enumerate (flag for the plan):**
1. **Workspace/Custom scope filtering.** PRD tabs (Workspace Skills, Custom Skills) need a queryable `scope`. Today `SkillScope` lives only in optional frontmatter and is ignored by the prompt loader. **Extend** `GET /api/skills` to parse `parseSkillFrontmatter` and return `scope` + a `?scope=` filter (custom = user-authored vs starter/marketplace; workspace = `scope: workspace` frontmatter). No store change — derive at read time. Net-new query param, reusing the existing parser (05g §2). The "Custom" tab can also be derived as "not in starter/capability-pack catalogs."
2. **Assign-to-workspace/agent.** PRD "assign to agent/workspace" — workspace config already has a `skills?: string[]` field (`WorkspaceConfig`, substrate-types.md §a; matches `WorkspaceConfigV2.skills`). Assignment is a `PATCH /api/workspaces/:id { skills }` (EXISTS) — no new endpoint, but the FE must wire it.
3. **Archive/rollback** (blueprint actions). `retireStaleSkills` (05g §6) **moves** skills to `~/.waggle/skills-archive/` (recoverable) — an archive substrate exists but has **no HTTP route**. A manual "archive"/"restore" pair would be net-new thin routes over `skill-retirement.ts`. Defer unless in MVP scope (PRD §12.6 lists archive in blueprint, not in §16.8).
4. **Publish.** `POST /api/marketplace/publish` (PRO-gated) already exists for skill→catalog publish (03d/05g §13) — reuse for the Builder's "publish to marketplace" path.
---
## 6. Shared types needed (PRD §15 vs `lib/types.ts`)
Currently the FE has only `SkillPack` (a pack grouping, `lib/types.ts:210-218`) — **no per-skill `Skill` type, no `SkillScope`/`SkillStatus`/`ExtensionType`** (substrate-types.md §e: all PRD §15.2 unions MISSING in FE).
Add to `apps/web/src/lib/types.ts` (FE), mirroring the existing backend `SkillFrontmatter`/`SkillTemplate` shapes (05g §2-3) so FE↔BE stay aligned:
```ts
type SkillScope = 'personal' | 'workspace' | 'team' | 'enterprise'; // matches skill-frontmatter.ts
type SkillStatus = 'installed' | 'draft' | 'custom' | 'workspace' | 'marketplace' | 'update-available';
type ExtensionType = 'skill' | 'connector' | 'mcp' | 'model' | 'template' | 'external_tool'; // PRD §15.2
interface Skill {
name: string; // file stem (id surrogate)
description: string;
category: string;
scope: SkillScope;
status: SkillStatus;
trust?: 'verified' | 'community' | 'experimental';
usageCount?: number; // from skill-usage.json (05g §5)
lastUsedAt?: string; // ISO
instructions?: string; // body
inputs?: string[]; outputs?: string[]; tools?: string[];
memoryAccess?: boolean; owner?: string;
}
```
Keep `SkillPack` for the pack-grid (starter/capability packs); `Skill` is the per-row object for My/Custom/Workspace tabs. Align `Skill.category` to the broader server `inferCategory` set (research/coding/knowledge/writing/planning/general — 05g §3), not the FE `SkillPack`'s 5-value enum.
---
## 7. Dependencies (screens/phases first)
- **PRD Phase 3 (Intelligence layer)** — Skills Hub + Skill Builder ship here (PRD §8, Sprint 6). Depends on **Phase 0/1 AppShell + IA + shared types** (`ExtensionType`, `Skill`) and the dock/zone IA being settled.
- **Soft dependency on S04 Memory** (memory-access declaration in skills — PRD field "memory access") and **S09 Agent Center** (skills assigned to agents — shared `skillIds` concept; `AgentDef` lacks `skillIds` today, substrate-types.md §e §15.5).
- **Shares the Extend-governance install-audit read surface** with S07 Connector / S08 MCP / Marketplace screens — the `GET /api/audit/installs` route exists (05g §8) and is already consumed by `CapabilitiesApp` AuditTab; the broader `GET /api/extend/audit` (substrate-types.md §d, gap 1) is shared across S06/S07/S08.
- **No dependency on Home/Command Center net-new domains.** Skills Hub can ship before those.
---
## 8. Effort
**M.** The backend is almost entirely present (2 EXISTS / 3 PARTIAL aliases-and-dispatchers, no new store, no `.mind` migration); the lift is FE: rework `CapabilitiesApp` from pack-grid to the PRD tab/table model, add a per-skill `Skill` type + `useSkills` hook, build the net-new 5-step `SkillBuilder`, and resolve the marketplace double-representation. Workspace/Custom scope filtering is a read-time derivation (cheap). Bumps toward L only if archive/rollback + full assign-to-agent wiring land in the same slice.
---
## 9. Open questions
1. **Tab semantics for "Custom" vs "Workspace":** is "Custom" = user-authored-not-from-catalog (derive by excluding starter/capability-pack ids) and "Workspace" = `scope: workspace` frontmatter? Confirm, since neither is a first-class persisted state today (skills are flat files; scope is optional frontmatter the loader ignores).
2. **Does the Builder publish to the local skills dir, the marketplace catalog, or both?** `POST /api/skills/create` (local) vs `POST /api/marketplace/publish` (PRO-gated catalog) are different targets — PRD §12.6 says "test run before publishing" but doesn't say which surface "publish" writes to.
3. **PRD §16.4 / §23 Q4 parity:** how much of the Marketplace tab is the live synced catalog (`/api/marketplace/search`, ~30 sources) vs seeded/mock entries in v1? Affects the Marketplace panel's empty/syncing states.
4. **Skill "inputs/outputs/memory access" persistence:** the current `SKILL.md` frontmatter (`skill-frontmatter.ts`) has `permissions` but **no structured inputs/outputs**. Builder Steps 3 ("Inputs & Outputs") + 4 ("Tools & Data") imply extending the frontmatter schema — confirm whether to extend `SkillFrontmatter` (and `generateSkillMarkdown`/`serializeFrontmatter`) or store these in skill body markdown only.
5. **Archive/rollback in MVP?** Blueprint lists `archive`/`rollback` as skill actions but PRD §16.8 omits them. `skill-retirement.ts` provides the move-to-archive substrate but no HTTP route — include now or defer to a later Extend-governance slice?
6. **Install-audit critical-column bug (cross-cutting, substrate-types.md §d gap 2):** `AuditRiskLevel` TS includes `'critical'` but both DDL CHECKs only allow `low/medium/high` — a `record()` with `'critical'` throws. Skill installs route through this audit path; confirm the plan picks up the one-line migration (or that the marketplace's CRITICAL→`'high'`+`approvalClass:'blocked'` mapping is the permanent contract).

190
docs/ux-refactor/gap-cards/S07-connector-hub.md Normal file
View File

@@ -0,0 +1,190 @@
# Gap Card — S07 · Connector Hub
> Execution model: **in-place incremental refactor** of `apps/web` + targeted backend extensions.
> PRD acceptance criteria win over the (directional) mockup. Every claim below is grounded in real files.
> PRD = `docs/Waggle_OS_UX_Refactor_Master_Handoff_Package/Waggle_OS_UX_Refactor_PRD.md`.
## 1. Screen & purpose
**Connector Hub** (PRD §12.7, blueprint Screen 7, dock app id `connectors`). Purpose: "Connect
external tools and data." It is the **Extend** layer surface for service connectors (distinct from
**S08 MCP Hub** — PRD §12.8 — which the current `ConnectorsApp` folds in as a second "MCP Servers" tab
via `McpCatalog`; the refactor should keep the catalog but the two are separate PRD screens).
PRD §12.7 acceptance criterion (the bar this card must hit):
> **"Users see exactly what tools are connected and whether data is flowing."**
The "whether data is flowing" half is the load-bearing gap — today there is no sync state, no last-sync
timestamp, and no recent-activity surface anywhere in the stack.
## 2. Required states (PRD/Blueprint)
PRD §12.7 functional requirements + blueprint Screen-7 state list (`_blueprint_extracted.txt:326-331`,
state list `:467`):
1. **Connected connectors** with **status** and **last sync**.
2. **Available connectors** grouped **by category**.
3. **Health surface**: health, recent sync activity, **token expiry**, and **errors**.
4. **Actions**: connect, **sync now**, manage, **revoke**, **reconnect**.
5. **Recommended** connectors based on onboarding + workspace needs.
6. State machine per blueprint: `connected · disconnected · expired token · syncing · failed · recommended`
(plus list-level `loading / empty / populated / error`).
7. RBAC/trust (PRD §17.3, §18.1): "Connectors require consent and revocation path" + "Connector/MCP
install audit" (append-only trust trail).
Mockup (`screen_07_connector_hub.png`, directional) adds visual chrome the PRD does not mandate but
implies: top tabs (Connected / Available / Recommended / Built by Waggle), a **Connector Summary** donut
(connected/syncing/error/disconnected counts), a **System Health** tile (API/sync/error-rate gauges), a
**Recent Activity** feed, and a "Need Help?" card. Treat these as direction, not a contract.
## 3. Current state in repo (disposition: **rework**)
**Frontend** — `apps/web/src/components/os/apps/ConnectorsApp.tsx` (356 LOC):
- Two-tab sidebar: **Services** (native connectors) + **MCP Servers** (`McpCatalog`). Filter rail = `all / connected / available`.
- Renders connectors from `adapter.getConnectors()` grouped by a **hardcoded** `CATEGORIES` map (`:41-50`)
+ hardcoded `SETUP_HINTS` (`:52-60`). Per-row expand reveals capability chips, setup steps, and a
token/API-key input.
- Connect flow (`handleConnect`, `:113-135`): writes credential via `adapter.addVaultSecret('connector:<id>')`
**then** calls `adapter.connectConnector(id)` (note: the adapter's `connectConnector` POSTs **no body** —
`adapter.ts:1161`; the credential is pre-seeded in vault). Disconnect = `adapter.disconnectConnector(id)`.
- `shouldResetCredentialInputs` (`:69-71`) is an exported, regression-tested pure guard
(`phase5b-connectors.test`) — **keep**, it prevents credential cross-submission.
- Subcomponents (`apps/web/src/components/os/apps/connectors/`): `BrandTile.tsx`, `brand-identity.ts`
(logo/colour identity — **keep, reuse**), `McpCatalog.tsx` + `McpServerCard.tsx` + `mcp-registry.ts`
(the MCP tab — belongs to **S08**, leave for that card).
- **What's MISSING in the UI vs PRD:** no last-sync, no health probe call, no "sync now", no "revoke"
(only disconnect), no recommended tab, no recent-activity feed, no summary/health tiles, no token-expiry
surfacing. `adapter.getConnectorHealth` **exists** (`adapter.ts:1156`) but is **never called** anywhere
(grep-confirmed) — the UI shows only the coarse list `status`.
**Backend** — `packages/server/src/local/routes/connectors.ts` (121 LOC): 4 routes —
`GET /api/connectors`, `GET /api/connectors/:id/health`, `POST /api/connectors/:id/connect`,
`POST /api/connectors/:id/disconnect`. Backed by `fastify.connectorRegistry` (`ConnectorRegistry` in
`packages/agent/src/connectors/connector-registry.ts`; **30** connectors registered via
`setup-connectors.ts`; per-connector `healthCheck()` impls exist in every
`packages/agent/src/connectors/*-connector.ts`).
**Disposition: rework** — the shell, brand tiles, category grouping, and connect/disconnect flow are
solid and reusable, but the screen is missing the entire "is data flowing?" dimension (sync/health/
activity/recommended/audit). This is additive rework on a good base, not a rebuild.
## 4. Frontend work
**Rework `ConnectorsApp.tsx` into the PRD Connector Hub** (keep MCP tab in place for S08):
- **Add tabs** matching PRD: `Connected · Available · Recommended` (mockup also shows "Built by Waggle" —
optional). The existing `all/connected/available` filter rail collapses into these tabs.
- **Per-row health + last sync**: lazy-call `adapter.getConnectorHealth(id)` for connected rows (already in
adapter, currently dead) to render `status` (connected/expired/error), `tokenExpiresAt` (token-expiry
badge), `lastChecked`, and (new) `lastSyncAt`. Extract a **new `ConnectorCard.tsx`** component
(blueprint names `ConnectorCard`, `:488`) from the inline row JSX (`:262-340`) — status pill, last-sync,
health dot, actions menu (Connect / Sync now / Manage / Revoke / Reconnect).
- **Recommended tab**: reuse the existing `recommendConnectors(personaId)` from `@waggle/shared`
(`connector-recommendations.ts:146`) — today wired **only** into the MCP tab (`McpCatalog.tsx:69`),
not service connectors. Forward `personaId` (already a prop, `:28`) to a recommended-connectors section.
- **Summary + health + activity tiles** (mockup, directional): a small **`ConnectorSummary`** donut from
client-side status counts (no new endpoint), a **System Health** tile from the new
`GET /api/connectors/health` aggregate (§5), and a **Recent Activity** feed from the new
`GET /api/connectors/activity` (sync/connect/revoke events). The blueprint's reusable `Timeline` and
`EvidencePanel` (`:488`) can host the activity list.
- **Actions wiring**: add `syncConnector(id)` → `POST /api/connectors/:id/sync`; add `revokeConnector(id)`
→ `POST /api/connectors/:id/revoke` (PRD verb; aliases existing disconnect); "Reconnect" reuses the
existing connect flow. Surface a `syncing` row state + toasts on `failed`.
- **State**: extend the local `Connector` interface (`:31-38`) with optional `lastSyncAt`, `tokenExpiresAt`,
`health`, `category`, `recommended`. **Move category off the hardcoded map** onto the
`ConnectorDefinition.category` field that already exists in `@waggle/shared` (`types.ts:299`) but is not
yet emitted by the row data — reconcile so the UI stops carrying its own `CATEGORIES`.
**Adapter (`apps/web/src/lib/adapter.ts`) — add 2 methods, reuse 1:**
- `syncConnector(id): POST /api/connectors/:id/sync` (NEW).
- `revokeConnector(id): POST /api/connectors/:id/revoke` (NEW; or alias to existing `disconnectConnector`).
- `getConnectorHealth(id)` already exists (`:1156`) — start calling it; optionally add
`getConnectorsHealth(): GET /api/connectors/health` aggregate + `getConnectorActivity()`.
## 5. Backend work (PRD §16.9 connectors subset)
> §16.9 spans Connectors + MCPs + Marketplace. This card scopes the **Connectors** rows only; MCP rows
> (`/api/mcps*`) and `/api/marketplace*` belong to **S08 / S13**.
| PRD §16.9 endpoint | Status | Action |
|---|---|---|
| `GET /api/connectors` | **EXISTS** | `connectors.ts:6` → `registry.getDefinitions()`. **EXTEND** the definition payload to carry `category` (already on the type, `types.ts:299`) + `lastSyncAt` so the UI drops its hardcoded `CATEGORIES`/sync-shim. |
| `POST /api/connectors/:id/connect` | **EXISTS** | `connectors.ts:55`. **EXTEND**: write an `install-audit` entry (see audit gap below) on success. |
| `POST /api/connectors/:id/sync` | **MISSING** | **NET-NEW** route in `connectors.ts`. No sync substrate exists — `WaggleConnector` (`connector-sdk.ts`) has `connect`/`healthCheck`/`execute` but **no `sync()`**. Minimum viable: probe `healthCheck()` + record a `lastSyncAt` timestamp (persist in vault sub-key `connector:<id>:lastSync` or a small store) + emit an activity event. Full sync (re-pull data) is a larger connector-SDK addition — flag as phased. |
| `POST /api/connectors/:id/revoke` | **PARTIAL** | Closest is `POST /api/connectors/:id/disconnect` (`connectors.ts:107`, removes `connector:<id>` + sub-keys). **EXTEND**: add a `/revoke` alias (or rename) that additionally writes an `install-audit` `action:'rejected'`/revoke entry. Same intent, PRD verb. |
**Additional backend work the PRD requires but §16.9 does not enumerate (implied by §18.1 / §12.7):**
- **Install/consent audit on connect & revoke (MISSING write path).** `connectors.ts` does **NOT** call
`fastify.auditStore.record(...)` (grep-confirmed — only `marketplace.ts:224-319` writes audit today).
PRD §18.1 mandates "Connector/MCP install audit". The substrate exists: `InstallAuditStore`
(`packages/core/src/install-audit.ts`) with `AuditCapabilityType` including `'connector'` (`:22`),
actions `installed/rejected` (`:15`). **EXTEND** connect/revoke to record entries. ⚠ **Latent enum-drift
bug** to avoid: TS `AuditRiskLevel` allows `'critical'` (`install-audit.ts:16`) but both DDL CHECKs only
allow `low/medium/high` (`install-audit.ts:65`, `schema.ts:130`) — pass `'high'`, never `'critical'`.
- **Audit read route (MISSING).** No HTTP surface lists the audit trail (`getRecent`/`getByCapability`
have no route). The Connector Hub's "Recent Activity" + the Extend trust-trail view need a NEW read,
e.g. `GET /api/connectors/activity` (or a shared `GET /api/extend/audit` filtered to `type:'connector'`).
Net-new but reads existing `install_audit` rows — no migration.
- **System-health aggregate (optional, mockup).** A `GET /api/connectors/health` that fans
`registry.healthCheck()` over connected connectors for the System-Health tile. Net-new thin aggregator;
no new substrate.
**`.mind` migration:** **None required.** `install_audit` already exists in `schema.ts:119`; connector
credentials live in the **vault**, not `.mind`. `lastSyncAt` can live as a vault sub-key or a tiny store —
no schema change. (The audit table's pre-existing `risk_level` CHECK drift is a code-discipline note, not
a migration.)
## 6. Shared types needed (PRD §15 vs `lib/types.ts`)
- **`ConnectorDefinition` / `ConnectorHealth` / `ConnectorStatus` already exist** in
`packages/shared/src/types.ts:266-312` and are the canonical contract — the FE should import these
instead of the ad-hoc local `Connector` interface in `ConnectorsApp.tsx:31-38` (a lossy duplicate).
- **`lib/types.ts` has a thin `Connector`** (frontend mirror, §(d) substrate inventory) — reconcile it to
the shared `ConnectorDefinition` shape (add `category`, `tokenExpiresAt`, `lastSyncAt`, optional `health`).
- **New optional fields:** `ConnectorDefinition.lastSyncAt?: string` (and surface `category` which is
already declared but not always populated). PRD §15.2 lists an `ExtensionType` union — connectors are one
member; not blocking for S07 but should be defined when S13 (Marketplace) lands.
- **`ConnectorRecommendation`** already exists (`connector-recommendations.ts:38`) — reuse as-is for the
Recommended tab.
## 7. Dependencies (screens/phases first)
- **Onboarding (S12, PRD §12.12 Tool Discovery / §16.1)** feeds the Recommended tab's "based on
onboarding" signal. `recommendConnectors(personaId)` works standalone today, so S07 is **not blocked** —
but the richer "based on workspace needs" recommendation improves once onboarding tool-discovery answers
are persisted.
- **S08 MCP Hub** shares this app shell (the MCP tab). Coordinate the tab split so reworking S07 doesn't
regress the MCP catalog; ideally S07 and S08 land in the same phase or S07 first with the MCP tab
untouched.
- **Extend trust-trail / Marketplace (S13)** shares the install-audit read route — build the audit write +
read once, consume in both. Sequence the audit endpoint before/with S07's Recent Activity.
- No hard dependency on Home/Workspace screens.
## 8. Effort: **M**
Frontend rework on a solid existing shell (new tabs, ConnectorCard extraction, wire two dead/easy adapter
paths) is modest. The backend lift is small-but-real: `/sync` and `/revoke` routes + audit write on
connect/revoke + an audit read route + a health aggregate — all over existing substrate (registry, vault,
`install_audit`), zero migration. The one true unknown (real data-pull `sync` in the connector SDK) is
phaseable to a health-probe-only v1, which keeps this **M** rather than **L**.
## 9. Open questions
1. **Sync semantics.** Does "sync now" mean (a) re-probe health + stamp `lastSyncAt` (v1, cheap), or
(b) re-pull/refresh cached connector data (needs a new `sync()` on `WaggleConnector` + a cache)? PRD
§12.7 says "show recent sync activity" but connectors are currently **runtime tools** (`execute(action)`),
not background data-syncers. Recommend v1 = health-probe + timestamp.
2. **`lastSyncAt` storage.** Vault sub-key (`connector:<id>:lastSync`) vs a small dedicated store vs an
`install_audit` derived value? Vault sub-key is lowest-risk and matches the existing `connector:<id>:email`
pattern.
3. **revoke vs disconnect.** Add `/revoke` as a true alias of `disconnect`, or have `revoke` additionally
purge OAuth tokens (`<provider>_oauth_token`, `oauth.ts`) + write a stronger audit entry? PRD §17.3
("revocation path") implies the latter for OAuth connectors.
4. **Audit scope.** Connector-specific `GET /api/connectors/activity` vs a shared
`GET /api/extend/audit?type=connector`? The latter serves S07 + S08 + S13 with one route (preferred).
5. **Audit `.mind` location.** `install_audit` is per-`.mind` (per-workspace). Connectors are **global**
(vault-scoped, not workspace-scoped). Confirm the audit-store decorator binds to `personal.mind` so the
global Connector Hub trail is consistent (substrate inventory §(d) flags this exact ambiguity).
6. **Token-expiry source.** `ConnectorHealth.tokenExpiresAt` is populated only on the fallback path
(`connectors.ts:49`); confirm each connector's `healthCheck()` surfaces real expiry, else the expired-token
state will never show for SDK-backed connectors.

270
docs/ux-refactor/gap-cards/S08-mcp-hub.md Normal file
View File

@@ -0,0 +1,270 @@
# Gap Card — S08 · MCP Hub
> UX-refactor planning artifact. Execution model is the LOCKED **in-place incremental refactor** of
> `apps/web` + targeted backend extensions. Mockup is directional; PRD acceptance criteria win.
> Every claim below cites a real file. PRD = `docs/Waggle_OS_UX_Refactor_Master_Handoff_Package/Waggle_OS_UX_Refactor_PRD.md`.
---
## 1. Screen & purpose
**MCP Hub** — the power-user capability-extension surface for Model Context Protocol servers (PRD §12.8,
PRD line 566-579). Belongs to the **Extend** IA layer (PRD §10.4; blueprint line 74, 81: route group
`/mcps`). Explicit blueprint directive: **"Do not bury Connectors/MCPs inside Settings"** (blueprint line 79).
Purpose (PRD §12.8): *"Enable power-user extension through Model Context Protocol servers."* MCPs are
auditable capability providers for power users and agents (blueprint line 140). The governing acceptance
criterion: **"MCPs are powerful but always visible, scoped, auditable, and reversible."** (PRD line 579).
Primary user journey — **J11 / Journey 9 "Install MCP"** (PRD lines 736-743; blueprint line 206-208):
power user opens MCP Hub → selects e.g. Postgres MCP → reviews risk and scope → approves installation →
MCP becomes available to selected workspace/agent → **install audit is recorded**.
Mockup (directional only — `screen_08_mcp_hub.png`): top toolbar with tabs (Installed / Available /
Marketplace / Custom / Remote Registry), search, "Add MCP Server" CTA; left an "Installed MCPs" table
(name, status pill, connected-to, last-used, scope, actions) over an "Available MCPs" category-filtered
grid; right rail with an "MCP Overview" donut (counts), "MCP Health", "Recent Activity" (audit/log feed),
and a "Custom MCP" add affordance.
---
## 2. Required states (PRD / Blueprint)
**Tabs (PRD §12.8 line 572):** Installed · Available · Marketplace · Custom · Remote Registry.
**MCP object fields (PRD §12.8 line 573):** name, description, version, status, **connected to**,
**last used**, **locality** (local/remote), **risk**, **permissions**, **logs**. Target schema
`Extension/MCP` (blueprint line 554, PRD §15.2 `ExtensionType`): `id, type, name, source, version,
endpoint, capabilities, riskLevel, approvalClass, status, health, installedAt, approvedBy`.
**Actions (PRD §12.8 line 574):** install · start/stop · test · scope · view logs · revoke · add custom MCP.
Risky MCPs require approval + audit trail (PRD line 575; blueprint line 161 "elevated connectors/MCPs …
require approval").
**Extension lifecycle states (PRD §14.7 lines 906-914):** Available · Installed · Update available ·
Installing · Failed install · **Risk approval required** · Disabled/revoked. Plus per-server runtime
status (blueprint line 334-335): installed; available; **running**; **stopped**; **error**; risk-approval-needed.
**Connector/MCP UI states (PRD §14.5 / blueprint line 467):** Loading, empty, populated, error.
**Scope (acceptance-critical):** an MCP must be scopeable to workspace and/or agent (PRD line 742;
blueprint line 207 "scope to workspace/agent"; line 601 "Connector and MCP installs are visible,
permissioned, health-checked and auditable"; line 600 "a workspace agent cannot run with hidden
memory/tool/MCP access").
**Offline degradation (blueprint line 516):** offline mode degrades MCPs gracefully while keeping local
workspace/memory available.
---
## 3. Current state in repo
**There is NO dedicated MCP Hub app today.** MCPs surface in three thin, mostly-static places:
1. **Static catalog (discovery only) — `apps/web/src/components/os/apps/connectors/McpCatalog.tsx`** +
**`McpServerCard.tsx`** + **`mcp-registry.ts`** (a re-export shim of `@waggle/shared`). Rendered as the
"MCP Servers" tab inside **`ConnectorsApp.tsx`** (`apps/web/src/components/os/apps/ConnectorsApp.tsx:197-205,348-349`).
The catalog data is `MCP_CATALOG` / `MCP_CATEGORIES` / `CATEGORY_EMOJI` in
**`packages/shared/src/mcp-catalog.ts`** (`McpServer` interface at `:17`; `MCP_CATALOG` at `:53`; 14
categories at `:30`). Per the backend-map (`05f` §12, lines 391-401), this catalog is **static and not
connected at runtime** — a discovery/install-command directory.
- **The only "install" UX is copy-a-shell-command-then-restart** (`McpServerCard.tsx:30-37,98-138`
copies `server.installCmd`; tooltip text `:111-116`: "Copy the command … Run it in your terminal …
Restart Waggle"). There is **no in-app install, start/stop, test, scope, revoke, logs, risk, or
status** — none of the PRD §12.8 actions/fields exist in the UI.
2. **Live runtime status (read-only) — `GET /api/capabilities/status`**
(`packages/server/src/local/routes/capabilities.ts:35-53,103-110`) returns
`mcpServers:[{name,state,healthy,tools}]` from the real runtime. **But the runtime is empty by default**
(see #3 below), so this list is always `[]` on a stock install.
3. **The MCP runtime engine (rich, but unwired) — `packages/agent/src/mcp/mcp-runtime.ts`.**
`McpRuntime` has the full lifecycle the PRD needs: `addServer(config)` (`:308`), `removeServer(name)`
(`:327`), `startAll`/`stopAll`, per-instance `start()/stop()/callTool()` (`McpServerInstance` `:102,154,178`),
`getServerStates()` (`:362`), `getHealthy()` (`:370`), `isServerHealthy(name)` (`:399`), and **per-workspace
scoping** via `McpServerConfig.workspaceId` (`:13`) + `getToolsForWorkspace(workspaceId)` (`:385`).
**CRITICAL GAP:** the runtime is instantiated empty — `const mcpRuntime = new McpRuntime()` with comment
*"empty by default"* (`packages/server/src/local/index.ts:911`), and **nothing ever calls `addServer()`**
(grep `mcpRuntime.addServer` / `.mcp.json` / `loadMcpConfig` → 0 matches in `packages/server/src`). So
there is no persistence layer that loads installed MCP configs at boot, and no HTTP route to install/
start/stop/test/remove a server.
**Install-audit substrate is present** (`AuditCapabilityType` includes `'mcp'` —
`packages/core/src/install-audit.ts:22`; `InstallAuditStore.record/getRecent/getByCapability` exist) but
**has no read HTTP route** (substrate-types inventory §d: writes only; `GET /api/audit/installs` exists in
`skills.ts` but is a generic recent-installs feed). MCP installs are not currently audited because there is
no MCP install path to audit.
**Adapter:** no `getMcps`/`installMcp`/`testMcp` methods in `apps/web/src/lib/adapter.ts` (grep → 0 matches).
**Disposition: `create-new`** (with substrate reuse). A net-new **MCPHub app** (`MCPHubApp.tsx`) promoted
out of ConnectorsApp's MCP tab, **plus net-new `/api/mcps/*` backend routes wiring the existing `McpRuntime`
+ a new persisted config store + install-audit**. The static catalog component (`McpCatalog`/`McpServerCard`)
is reused as the "Available"/"Marketplace" tab content. This is the single largest backend gap on the Extend
layer — the engine exists but is entirely unwired to UI or persistence.
---
## 4. Frontend work
**New IA placement:** add an `mcp-hub` (or reuse the dead `marketplace`-adjacent slot) `AppId` in
`apps/web/src/lib/dock-tiers.ts`, register chrome in `Desktop.tsx` `appConfig` + a `renderAppContent`
switch case (per frontend inventory §b lines 123-129), and add a dock entry under the **Extend** zone-parent
(`dock-tiers.ts` zone model). MCP Hub is power-user/PRO-tier-gated (PRD personas: power user/developer needs
MCPs — PRD line 151).
**Components to CREATE** (`apps/web/src/components/os/apps/`):
- `MCPHubApp.tsx` — shell with the 5 PRD tabs (Installed / Available / Marketplace / Custom / Remote
Registry). Mirror `ConnectorsApp.tsx`'s sidebar-tab + filter layout (`:183-216`) so it's visually
consistent with the Connector Hub it splits from.
- `mcp/InstalledMcpTable.tsx` — table of running/installed servers: name, status pill (running/stopped/
error/installing — maps `McpServerState` `mcp-runtime.ts:16`), connected-to, last-used, locality,
scope chip, row actions (start/stop, test, scope, view logs, revoke). Drives PRD §12.8 line 573-574.
- `mcp/AddCustomMcpForm.tsx` — Custom tab: `{ name, command, args[], env{}, workspaceId? }` → `POST /api/mcps`
(matches `McpServerConfig` `mcp-runtime.ts:8-14`). Reuse `injection-scanner` patterns server-side.
- `mcp/McpDetailPanel.tsx` (right rail) — MCP Overview counts, MCP Health, permissions/scope editor,
**logs viewer**, and the **risk/approval banner** ("Risk approval required" state). Reuse the approvals
surface pattern from `ApprovalsApp.tsx` / inline-chat approval (same backend `/api/approval/*`).
- `mcp/McpScopeDialog.tsx` — scope-to-workspace/agent picker (writes `workspaceId` onto the server config;
later, `mcpIds[]` onto workspace/agent per §6).
**Components to REUSE (keep-promote):**
- `McpCatalog.tsx` + `McpServerCard.tsx` + `mcp-registry.ts` → become the **Available** + **Marketplace** +
**Remote Registry** tab bodies. Today `McpServerCard` only shows a copy-command strip
(`McpServerCard.tsx:98-138`) — **rework** it to add a real **Install** button (calls the new
`installMcp` adapter method) while keeping copy-command as the offline fallback.
- `recommendConnectors` from `@waggle/shared` (already used `McpCatalog.tsx:15,69`) for "Recommended" tile.
- `LockedFeature.tsx` for tier gating; `ContextMenu.tsx` for row actions; shadcn `table`, `badge`, `dialog`,
`tabs`, `tooltip` primitives (`components/ui/*`, frontend inventory §e).
**Adapter methods to ADD** (`apps/web/src/lib/adapter.ts` — the single sidecar gateway, §c lines 162-265):
`getMcps()`, `installMcp(payload)`, `addCustomMcp(config)`, `startMcp(id)`, `stopMcp(id)`, `testMcp(id)`,
`scopeMcp(id, scope)`, `revokeMcp(id)`, `getMcpLogs(id)` — one per PRD §16.9 / §12.8 action.
**New hook:** `hooks/useMcps.ts` (mirrors the `useConnectors`-style pattern) returning
`{ installed, available, custom, install, start, stop, test, scope, revoke, refresh }`. Wire SSE/poll over
`/api/capabilities/status` or a new `/api/mcps` for live status (cache-invalidate on
"connector sync" / install completion per blueprint line 514).
---
## 5. Backend work (PRD §16.9 endpoints — all MCP rows)
> All net-new routes live in a new `packages/server/src/local/routes/mcps.ts`, registered in
> `local/index.ts`, wiring the already-built `McpRuntime` (`server.agentState.mcpRuntime`,
> decorated `local/index.ts:1361`). **No new SQLite table is strictly required** — but a persisted
> config source IS (see migration flag).
| PRD §16.9 endpoint | Status | Extend vs net-new + substrate it touches |
|---|---|---|
| `GET /api/mcps` | **PARTIAL → build net-new route over existing data** | No `/api/mcps` exists (grep-confirmed in backend-routes inventory, line 422 & §16.9 line 522). The data is **derivable today**: live runtime status from `McpRuntime.getServerStates()/getHealthy()/getAllTools()` (already surfaced in `capabilities.ts:35-53`), enriched with catalog metadata from `MCP_CATALOG` (`@waggle/shared`). **Net-new** thin route in `mcps.ts` that joins runtime state + persisted config + catalog into the `Extension/MCP` shape (§2). Touches: `McpRuntime` (agent), `MCP_CATALOG` (shared), new config store. |
| `POST /api/mcps/install` | **PARTIAL → net-new, route through existing install path** | No `/api/mcps/install` (inventory §16.9 line 523). Closest install paths are marketplace (`POST /api/marketplace/install` — SecurityGate + audit, `marketplace.ts:224-319`) and plugin install (`POST /api/plugins/install`). **Net-new** MCP install that: (a) persists an `McpServerConfig`, (b) calls `mcpRuntime.addServer(config)` + `start()` (`mcp-runtime.ts:308,102`), (c) runs the **SecurityGate + writes an `install_audit` row** with `capability_type:'mcp'` (`install-audit.ts:22`) — satisfying the "install audit is recorded" acceptance step (PRD line 743). Risky servers → return `risk approval required` state instead of starting. Tier: PRO (match marketplace). |
| `POST /api/mcps/:id/test` | **MISSING** | No MCP test/health route (inventory §16.9 line 524). Closest analog is `GET /api/connectors/:id/health`. **Net-new**: resolve the server, `start()` if needed, assert `isHealthy()` (`mcp-runtime.ts:94,399`) and/or do a `tools/list` round-trip, return health + discovered tools. Touches `McpRuntime`. |
| `POST /api/mcps/:id/revoke` | **MISSING** | No MCP revoke/uninstall by id (inventory §16.9 line 525). Closest: `DELETE /api/plugins/:name`. **Net-new**: `mcpRuntime.removeServer(name)` (`mcp-runtime.ts:327`) + delete persisted config + write `install_audit` `action:'rejected'`/`'revoked'`. Touches `McpRuntime` + config store + install-audit. |
| `GET /api/marketplace` | **PARTIAL** | Listing is `GET /api/marketplace/search` (`marketplace.ts`); the Marketplace tab reuses it. Alias of `/search` (inventory §16.9 line 526). Not MCP-specific work. |
| `POST /api/marketplace/install` | **EXISTS** | `marketplace.ts` (Tier PRO, SecurityGate) — reused by the Marketplace tab. |
**Additional routes implied by PRD §12.8 actions not in §16.9 list (net-new):**
- `POST /api/mcps` (add **custom** MCP) — blueprint API line 530 lists `GET/POST /mcps`. Persists config +
`addServer` + audit. **Net-new.**
- `POST /api/mcps/:id/start` and `POST /api/mcps/:id/stop` — PRD §12.8 "start/stop" action. Map to
`McpServerInstance.start()/stop()` (`mcp-runtime.ts:102,154`). **Net-new.**
- `PATCH /api/mcps/:id/permissions` (scope/permissions) — blueprint API line 530 (`PATCH /mcps/:id/permissions`).
Writes `workspaceId`/scope onto the persisted config (runtime honors it via `getToolsForWorkspace`,
`mcp-runtime.ts:385`). **Net-new.**
- `GET /api/mcps/:id/logs` — PRD §12.8 "view logs". No log capture exists in `McpServerInstance` today
(stderr is piped `:113` but not retained). **Net-new** + small runtime change to buffer stderr/state-change
events for retrieval.
- `GET /api/extend/audit` (or extend `/api/audit/installs`) — surface the install-audit trail for the MCP Hub
right-rail "Recent Activity". `InstallAuditStore.getRecent()` exists but has no MCP-scoped HTTP read
(substrate-types §d gap #1). **Net-new** (implied addition to §16.9, flagged in substrate inventory).
**Migration / persistence flag (IMPORTANT):**
- **No `.mind` SQLite migration is required for the MCP entity itself** — installed MCP configs can persist as
a JSON file (mirrors `workspace.json` / `.mcp.json` convention; note repo root already has an untracked
`.mcp.json` per git status) read at boot to populate `mcpRuntime.addServer()`. **This persistence layer is
entirely net-new** (today `mcpRuntime` is empty and never populated — `local/index.ts:911`). This is the
load-bearing backend gap: without it, "Installed" MCPs do not survive restart.
- **Install-audit DDL drift (latent, flag for the plan):** `AuditRiskLevel` TS includes `'critical'`
(`install-audit.ts:16`) but both CHECK constraints allow only `low|medium|high`
(`install-audit.ts:65`, `schema.ts:130`). Any MCP install recording `riskLevel:'critical'` would throw a
CHECK violation — map CRITICAL → `'high'` + `approvalClass:'blocked'` as marketplace.ts already does
(`marketplace.ts:224-319`), or fix the DDL.
---
## 6. Shared types needed (PRD §15 vs `lib/types.ts`)
- **`ExtensionType`** (PRD §15.2 line 953: `'skill'|'connector'|'mcp'|'model'|'template'|'external_tool'`)
— **MISSING** in `apps/web/src/lib/types.ts` (substrate-types §e: none of the §15.2 unions exist in FE).
Add it.
- **`Extension` / `Mcp` interface** (blueprint line 554: `id, type, name, source, version, endpoint,
capabilities, riskLevel, approvalClass, status, health, installedAt, approvedBy`) — **MISSING**. No
`Extension`/`Mcp` type anywhere in FE. Add to `lib/types.ts` (and ideally `packages/shared/src/types.ts`
so the sidecar route and FE share it). The existing `McpServer` (`@waggle/shared` `mcp-catalog.ts:17`:
`id,name,description,author,category,url,installCmd,capabilities,official?,logo?`) is the **catalog/discovery**
shape — distinct from the **installed-instance** `Mcp` shape; keep both, the Hub joins them by `id`.
- **Runtime types already exist server-side** and should be the source of truth for the route contract:
`McpServerConfig`, `McpServerState`, `McpToolInfo` (`packages/agent/src/mcp/mcp-runtime.ts:8-22`). Mirror
`McpServerState` (`'starting'|'ready'|'error'|'stopped'`) into the FE status union (map to PRD §14.7 states).
- **Reuse from install-audit:** `AuditCapabilityType`, `AuditRiskLevel`, `AuditApprovalClass`
(`packages/core/src/install-audit.ts:15-22`) for the riskLevel/approvalClass/audit fields — do not invent
parallel enums.
- **`mcpIds[]` on Workspace/Agent** (PRD §15.3 `WorkspaceConfigV2.mcpIds`, §15.5 Agent `mcpIds`) —
**MISSING** from both `WorkspaceConfig` (`workspace-manager.ts`, substrate-types §a) and `AgentDef`
(`packages/shared/src/types.ts:36-47`, §e). Needed for the "scope to workspace/agent" action. Additive
optional field (no DB migration — `workspace.json` is JSON).
---
## 7. Dependencies (screens / phases first)
- **Connector Hub (S07)** — MCP Hub is split OUT of `ConnectorsApp.tsx`'s MCP tab; do the Connector Hub
promotion first (or jointly) so the shared sidebar-tab/filter/health/state patterns are settled and the
MCP tab can be cleanly extracted. Same `Extend`-layer dock placement work.
- **Extend layer / dock-zone IA** — requires the new `AppId` + dock-zone wiring (frontend inventory §b/§d:
consolidate on `AppId`, add Extend zone entries). Blocks any new Extend app from being reachable.
- **Install-audit read route (§d gap)** — shared with Skills (S?) and Connectors governance; build once,
reuse across the Extend layer.
- **Approvals surface** — risk-approval flow reuses existing `/api/approval/*` + `ApprovalsApp` patterns;
no new approval substrate, but the wiring depends on that surface staying stable.
- **Marketplace** — the Marketplace tab reuses `GET /api/marketplace/search` + `POST /api/marketplace/install`
(already exist); ensure marketplace MCP packages are tagged so they route to the MCP install path.
- **Phase hint:** later phase. Backend wiring (persisted config store + runtime population + `/api/mcps/*`)
is the prerequisite for any non-static UI; the static catalog already ships, so this is a depth upgrade,
not a day-1 blocker. Sequence after Home/Workspace/Memory core screens.
---
## 8. Effort: **XL**
Largest Extend-layer gap: the runtime engine exists but is **completely unwired** (empty `McpRuntime`, no
persistence, no HTTP surface, copy-command-only UI). Requires a net-new persisted MCP-config store + boot-time
runtime population + ~8 net-new sidecar routes (install/start/stop/test/scope/revoke/logs + custom add) +
SecurityGate/audit integration + a full new app shell with 5 tabs, installed-table, detail/logs panel, scope
dialog, risk-approval flow, and adapter/hook layer — while preserving the static catalog as the
Available/Marketplace tabs. (Frontend-only would be M; the backend wiring + persistence + governance is what
pushes it to XL.)
---
## 9. Open questions
1. **Persistence location/format for installed MCP configs** — JSON file (`.mcp.json` at dataDir, mirroring
`workspace.json`; root already has an untracked `.mcp.json`) vs a new `install_audit`-adjacent table?
Recommendation: JSON file (no migration), but confirm the dataDir path + multi-workspace scoping model.
2. **Scope model** — is an MCP scoped by writing `workspaceId` onto its single config (1 server : 1 workspace,
per current `McpServerConfig.workspaceId`), or by an `mcpIds[]` membership array on each workspace/agent
(N:N)? PRD §15.3/§15.5 imply `mcpIds[]` (N:N); the runtime today only supports the single-`workspaceId`
field (`mcp-runtime.ts:13,385`). N:N needs a runtime change.
3. **Logs capture** — `McpServerInstance` pipes stderr but does not retain it (`mcp-runtime.ts:113`). Add a
ring-buffer of stderr + stateChange events for `GET /api/mcps/:id/logs`, or defer logs to a later phase?
4. **"Remote Registry" tab semantics** — is this the Composio gateway (already referenced in
`McpCatalog.tsx:106,294-301`), the official `modelcontextprotocol/servers` registry, or a remote
(HTTP/SSE-transport) MCP class distinct from local stdio? The runtime today is **stdio-only**
(`mcp-runtime.ts:108-115`); remote-transport MCPs would need a new transport in `McpServerInstance`.
5. **Install execution surface** — does in-app "Install" run `npx …` (spawn a child process to install the
package) in the sidecar, or only register config + rely on a globally-installed binary? Security review
needed (spawning installers vs the current copy-to-terminal model). Tauri IPC/CSP implications.
6. **Tier gate** — confirm MCP Hub is PRO+ (matches marketplace install gate) vs power-user-density-tier
(`UserTier`) only. Three tier vocabularies to reconcile (frontend inventory §f).

144
docs/ux-refactor/gap-cards/S09-agent-center.md Normal file
View File

@@ -0,0 +1,144 @@
# Gap Card — S09 Agent Center
> UX-refactor planning artifact. Execution model: **in-place incremental refactor** of `apps/web` + targeted backend extensions over the existing sidecar/substrate. Mockup is directional; PRD §12.9 + §16.7 acceptance criteria win.
> PRD: `docs/Waggle_OS_UX_Refactor_Master_Handoff_Package/Waggle_OS_UX_Refactor_PRD.md` (§12.9 lines 581-595, §16.7 lines 1112-1120, §15.5 lines 1015-1035).
---
## 1. Screen & purpose
**Agent Center** — manage agents as explicit, governed work actors (PRD §12.9, blueprint Screen 9, page 36). Per blueprint p.8 "Agent Model" (lines 125-136), an Agent is a scoped worker carrying goal, model, autonomy, memory scopes, skills, tools, MCPs, permissions — distinct from a Persona (a prompt+tools template). The Center is the list/manage surface; the **Agent Builder** (S18, PRD §12.9 + blueprint p.45) is the 5-step create flow.
Mockup (`screen_09_agent_center.png`, directional): top category tab strip (All Agents / Personal / Workspace / Team / Autonomous / Archive) + Templates + Filters + **Create Agent**; a KPI metric row (active count, success-rate avg, run counts, hours-saved, cost); a left list/table of agent rows (avatar, name, goal sub-line, type chip, model, status pill, success-rate bar, owner avatars, last-run, sparkline); a right rail (Agents by Type donut, Top Capabilities, Recent Activity, Quick Actions). Search + sort + pagination on the list.
---
## 2. Required states (PRD/Blueprint)
PRD §12.9 functional requirements:
- **Agent categories:** Personal, Workspace, Team, Autonomous, Templates, Archive (tabs).
- **Agent card/list** shows: goal, status, owner, workspace, capabilities, model, success rate, last run.
- **Agent Builder** steps: Basic Info → Capabilities → Memory & Tools → Permissions → Review & Create.
- **Agent fields** (§15.5): name, goal, description, persona/avatar, model, autonomy, type, memoryScopes, skillIds, connectorIds, mcpIds, permissions, status, createdBy, lastRunAt, successRate.
- **Agent safety:** no hidden tool/memory access; all elevated access reviewed (blueprint p.8: "Agent Builder must require model, goal, memory scope, skills/tools/MCPs and autonomy level"; "run logs link to execution_traces and ai_interactions"; "Autonomous agents require explicit schedule/trigger and stop/pause").
PRD agent state model (§14.5): Draft · Idle · Running · Paused · Failed · Waiting for approval · Completed · Archived. Blueprint p.18 (line 342): Idle; running; paused; failed; needs approval; archived.
Global states (§14.1) every screen must implement: Loading · Empty · Populated · Error · Offline/local-only · Syncing · Permission denied · Partial data · Approval required.
Acceptance: "User can explain what an agent can see and do before enabling it." (PRD line 595.)
---
## 3. Current state in repo (exact files + what they do)
**Disposition: `rework`** (the AgentsApp surface is a Personas manager, not the PRD Agent Center; the new IA needs an agent-as-actor object the current code does not model — but it reuses persona/group/fleet/trace substrate, so it is a rework + create-new-entity, not a from-scratch replacement).
Live frontend (grep-confirmed under `apps/web/src/components/os/apps/`):
- `AgentsApp.tsx` (346 LOC) — titled **"Personas"**, NOT "Agents". Two tabs: `agents` (= persona catalog) + `groups` (= agent groups). Loads `adapter.getPersonas()` + `adapter.getCapabilityStatus()` (for tool list) + `adapter.getAgentGroups()`. CRUD over **personas** (`createPersona/updatePersona/deletePersona/generatePersona`) and **groups** (`create/update/delete/runAgentGroup`). No goal/status/owner/successRate/last-run/autonomy concept; no category tabs; no KPI row; no run/pause controls on a card.
- `agents/AgentCard.tsx` (48 LOC) — avatar + name + description + delete (custom only) + chevron. No status pill, success bar, model, owner, last-run.
- `agents/AgentDetail.tsx` (108 LOC) — persona detail: tools list, suggested commands, workspace affinity. No run/pause/traces, no permissions panel.
- `agents/CreateAgentForm.tsx`, `CreateGroupForm.tsx`, `GroupCard.tsx`, `GroupDetail.tsx`, `GroupExecutionPanel.tsx` — persona/group create+exec UI. `CreateAgentForm` is a single form (name/description/icon/tools/systemPrompt), NOT the PRD 5-step Builder.
- `agents/types.ts` — `BackendPersona` (id/name/description/icon/affinity/commands/tools/systemPrompt/custom), `AgentGroup`, `GroupExecState`. **No Agent type with goal/autonomy/status/successRate.**
- `overlays/SpawnAgentDialog.tsx` (447 LOC) — ad-hoc sub-agent run: task + persona-override + model + parent-workspace; 2-step config→confirm with cost estimate; calls `adapter.spawnAgent()` → `POST /api/fleet/spawn`. This is the real "run an agent" path today, but it is launch-only, not a managed agent.
- `apps/MissionControlApp.tsx` (227 LOC) — live **fleet** sessions (`adapter.getFleet()`), per-session pause/resume/stop (`fleetAction`), plus team/activity tabs and AI-tool inventory. This is the closest existing "running agents" view; it shows sessions, not agent definitions.
- `apps/RoomApp.tsx` + `apps/WaggleDanceApp.tsx` + `apps/EventsApp.tsx` — live sub-agent tiles / coordination signals / event stream (run-time visibility, not agent management).
Registration: `agents` is an `AppId` in `lib/dock-tiers.ts` and routed in `Desktop.tsx` `renderAppContent`; `mission-control` is a separate AppId. Frontend inventory confirms: `AgentsApp` = "Personas manager" mapped to Intelligence bucket (`_inventory/frontend.md:29,361`).
Live backend (grep-confirmed, `_inventory/backend-routes.md` §16.7):
- Persona catalog CRUD: `/api/personas` GET/POST/PATCH/DELETE + `/generate` (`personas.ts`; POST/generate are **Tier: PRO**). 22 built-in personas in `packages/agent/src/persona-data.ts` + custom from disk (`05a:220-261`).
- Agent groups: `/api/agent-groups` GET/POST/PATCH/DELETE + `/run` — **`/run` is a placeholder stub, does NOT execute** (`03a:221`, JSON file `dataDir/agent-groups.json`).
- Sub-agent orchestrator state: `GET /api/agents/active` → `{ workers, active }` (`03a:136`).
- Fleet (real run/pause/resume/kill of sessions): `GET /api/fleet`, `POST /api/fleet/spawn`, `POST /api/fleet/:workspaceId/{pause,resume,kill}` (`backend-routes §1.13`).
- One-shot retrieval: `POST /api/agent/run` (SSE, separate path; `03a:228`).
- Trace store: `execution_traces` table (`mind/schema.ts:199`) with per-trace outcome/cost/duration; `TraceRecorder` auto-wires from agent loop (`05a:65`). **No HTTP listing route for traces** (`_inventory/backend-routes.md §16.7` → `/traces` PARTIAL).
**Key finding:** PRD's `/api/agents/*` (CRUD + run/pause/traces) is the **Cloud** server's Clerk-gated `routes/agents.ts`, NOT the sidecar. In the desktop (sidecar) context the entire §16.7 agent CRUD is **MISSING locally** (`backend-routes.md` §16.7 note, lines 488-492). There is **no persisted Agent entity** with PRD §15.5 fields anywhere local.
---
## 4. Frontend work
**Rework `AgentsApp.tsx` into the Agent Center** (keep the file; restructure). Concrete:
- **New `AgentCenter` shell** (rework `AgentsApp.tsx`): category tab strip (All / Personal / Workspace / Team / Autonomous / Templates / Archive) replacing the current Personas/Groups toggle. Keep Groups as a sub-view or fold groups under "Team/Autonomous". Add KPI metric row (active count, avg success rate, runs, est. hours saved, est. cost) — sourced from existing `getAgentStatus`/`getCostSummary`/`getFleet` + new agent list.
- **New `AgentRow`/rework `AgentCard.tsx`**: avatar, name, goal sub-line, type chip (`AgentType`), model, **status pill** (PRD §14.5 union), **success-rate bar**, owner avatar(s), last-run relative time, run/pause action buttons. Reuse `components/ui/badge` (status), `progress` (success bar), `avatar`. Status colors can follow `MissionControlApp` statusColors map.
- **Rework `AgentDetail.tsx`**: add Goal, Autonomy, Memory scope, Permissions panel, Run/Pause controls, and a **Traces** tab (links to `execution_traces` via new `/api/agents/:id/traces`).
- **New `AgentBuilder`** (PRD §20.3 "create"; blueprint S18): 5-step stepper (Basic Info → Capabilities → Memory & Tools → Permissions → Review & Create). Reuse the design-system **Builder stepper** (PRD §19.1) and the existing model picker `components/os/ModelSelector.tsx` + `lib/spawn-agent-helpers.ts` (model default selection) + persona/skill/connector/MCP multi-selects. `CreateAgentForm.tsx` (persona form) is a partial reuse target for the Basic Info + tools steps but must be extended to the agent contract.
- **Right rail**: Agents-by-Type donut (reuse `components/ui/chart`), Top Capabilities, Recent Activity (reuse fleet/events feed), Quick Actions.
- **Wire run/pause to fleet**: card "Run" → `/api/agents/:id/run` (which maps onto `fleet/spawn` per §5); "Pause" → `/api/agents/:id/pause` (maps onto `fleet/:wid/pause`). Keep `SpawnAgentDialog` as the quick-launch entry but have it also accept a saved agent id.
- **States**: implement all §14.1 globals — Loading (existing `Loader2`), Empty ("No agents — create one"), Error (existing error banner pattern in `AgentsApp`), Offline (`useOfflineStatus`), Permission denied (Team agents gated by `useBilling`/tier), Approval required (reuse `ApprovalsApp`/inline approval surface for elevated agent actions).
**Adapter methods/hooks (add to `lib/adapter.ts` — the single sidecar gateway):**
- `getAgents()`, `getAgent(id)`, `createAgent(body)`, `patchAgent(id, body)`, `runAgent(id, opts)`, `pauseAgent(id)`, `getAgentTraces(id)`.
- New `useAgents()` hook (mirror `useWorkspaces` shape: list/select/create/patch/run/pause/refresh). Reuse `useAgentStatus`, `useEvents`, `useRoomState`, `getFleet` for live run state.
**Shared types (FE):** add `Agent`, `AgentType`, `AutonomyLevel`, `AgentStatus`(state union) to `lib/types.ts` (see §6).
---
## 5. Backend work (PRD §16.7, against the local sidecar)
> Naming collision flagged: `/api/agents/*` CRUD currently exists ONLY on the Clerk-gated **Cloud** server (`packages/server/src/routes/agents.ts`), not the sidecar. The desktop talks only to the sidecar, so all of §16.7 is net-new **locally**. Add a new sidecar route file `packages/server/src/local/routes/agents.ts` registered in `local/index.ts`.
| PRD §16.7 endpoint | Status (sidecar) | Plan — EXTEND vs NET-NEW + substrate |
|---|---|---|
| `GET /api/agents` | **MISSING** | NET-NEW route. Backed by a **new agent store** (see migration note) — a persisted Agent entity. List can union saved agents + (optionally) derive read-only "agents" from `getPersonas()` for back-compat. Reuse `/api/agents/active` + `/api/fleet` to overlay live status. |
| `POST /api/agents` | **MISSING** | NET-NEW. Persist an Agent (§15.5 fields). Closest existing writes: `POST /api/personas` (custom persona) / `POST /api/agent-groups`. Record install/elevated-permission grant to `install_audit` if the agent claims elevated tools/MCPs. |
| `GET /api/agents/:id` | **MISSING** | NET-NEW read from the agent store (or map onto persona/group id for legacy). |
| `PATCH /api/agents/:id` | **MISSING** | NET-NEW. Closest: `PATCH /api/personas/:id` / `PATCH /api/agent-groups/:id`. |
| `POST /api/agents/:id/run` | **PARTIAL** | EXTEND: wire onto `POST /api/fleet/spawn` (`fleet.ts`, real execution — `{task, persona?, model?, parentWorkspaceId?}`). Resolve agent → persona+model+workspace, then spawn. Do NOT use `agent-groups/:id/run` (stub). Substrate: fleet/orchestrator + `execution_traces` via `TraceRecorder`. |
| `POST /api/agents/:id/pause` | **PARTIAL** | EXTEND: map agent→active session, reuse `POST /api/fleet/:workspaceId/pause`. |
| `GET /api/agents/:id/traces` | **PARTIAL** | EXTEND/NET-NEW thin route reading the `execution_traces` store (`mind/schema.ts:199`) filtered by agent/session; also expose `ai_interactions` links per blueprint p.8. No HTTP listing exists today — add one. Also reuse session timeline `GET /api/workspaces/:wid/sessions/:sid/timeline`. |
**Substrate touched:** persona catalog (`personas.ts` + `persona-data.ts`), agent-groups JSON store, fleet/sub-agent orchestrator (`05a`), `execution_traces` + `ai_interactions` tables, `install_audit` (for elevated-permission grants), `cron` (for Autonomous agents' schedule/trigger — blueprint p.8 line 136).
**.mind migration flag (REQUIRED for full §15.5 persistence):** there is **no Agent entity/table** in `mind/schema.ts` and personas live on disk (not as agents with goal/autonomy/status/successRate). Two options, lowest-risk first:
1. **JSON store (no DB migration):** persist agents to a `dataDir/agents.json` (mirroring the agent-groups JSON pattern, `03a:213`) — additive, reversible, no schema change. Recommended for v1.
2. **Mind table:** add an `agents` table to `mind/schema.ts` (bump `SCHEMA_VERSION`, use the established idempotent `ADD COLUMN`/`CREATE TABLE IF NOT EXISTS` migration pattern in `mind/db.ts`). Only if agents must be FTS/relation-queryable.
`successRate`/`lastRunAt` are **derivable** from `execution_traces.outcome` + `procedures.success_rate` (`schema.ts:147,206`) — compute at read time rather than store, per the §15.5 note that successRate "partially exists … derivable" (`substrate-types.md:255`).
---
## 6. Shared types needed (PRD §15 vs `lib/types.ts`)
None of the PRD §15.2 agent unions exist today (`substrate-types.md:218-229,249-257`). Add to `apps/web/src/lib/types.ts` (and mirror in `packages/shared/src/types.ts` if the cloud/agent runtime consumes them):
- `type AgentType = 'personal' | 'workspace' | 'team' | 'autonomous';` — **MISSING** (PRD §15.2 line 951).
- `type AutonomyLevel = 'manual' | 'guided' | 'medium' | 'high';` — **MISSING** (PRD §15.2 line 952).
- `type AgentRunState = 'draft' | 'idle' | 'running' | 'paused' | 'failed' | 'waiting_for_approval' | 'completed' | 'archived';` — **MISSING** (PRD §14.5). Note the existing FE `AgentStatus` (`types.ts:249-254`) is the cost/model snapshot, NOT this lifecycle union — keep both, distinct names.
- `interface Agent { id; name; goal; description?; type: AgentType; personaId?; avatar?; model?; autonomyLevel: AutonomyLevel; workspaceIds?: string[]; teamId?; memoryScopes?: Scope[]; skillIds?: string[]; connectorIds?: string[]; mcpIds?: string[]; permissions?: ...; status: AgentRunState; createdBy?; lastRunAt?; successRate?; createdAt; updatedAt }` — **MISSING entirely.** Closest is shared `AgentDef` (`packages/shared/src/types.ts:36-47`: id/userId/teamId/name/role/systemPrompt/model/tools/config/createdAt) which lacks goal/type/autonomy/status/scopes/successRate — extend or define `Agent` alongside it.
- `type Scope = 'personal' | 'workspace' | 'team' | 'organization';` — **MISSING** (PRD §15.2 line 946), shared by S06 Memory; define once.
The existing `BackendPersona` (`agents/types.ts:3-13`) stays for the persona catalog; the new `Agent` is a distinct object that may *reference* a `personaId`.
---
## 7. Dependencies (screens/phases first)
- **Phase 0 (Shell/IA)** — `Agent` shared types + `AgentType`/`AutonomyLevel`/`AgentRunState`/`Scope` unions must land first (consumed here + by S06 Memory + S18 Builder).
- **S04 Workspace Desktop** — Workspace agents are scoped by workspace; Agent Center's Workspace/Team tabs depend on `WorkspaceConfigV2.agentIds` (a §15.3 MISSING field, `substrate-types.md:32`) and `type`/`status`. Coordinate the workspace-config additive change.
- **S18 Agent Builder** — the create flow is a sibling screen (PRD §12.9 same section); Agent Center's "Create Agent" opens it. Plan together.
- **S11 Automation Center** — "Autonomous" agents need a schedule/trigger; depends on cron substrate shared with Automations.
- **S08 MCP Hub / S07 Connector Hub / S05 Skills Hub** — the Capabilities/Memory&Tools builder steps pick from those catalogs (`skillIds`/`connectorIds`/`mcpIds`); their list endpoints feed the multi-selects.
- **Approval surface** — elevated agent actions reuse `ApprovalsApp` + `/api/approval/*` (already exists).
- Lands in **Phase 3 (Intelligence layer)** per PRD §8 / Sprint 6 (§21).
---
## 8. Effort: **L**
Rework of a 6-file persona surface into a category-tabbed Agent Center, a net-new persisted Agent entity (JSON store v1) + 4 net-new sidecar routes + 3 extend-over-fleet/traces routes, new shared types, plus a 5-step Agent Builder (sibling). Not XL because the run/pause/trace substrate (fleet, execution_traces, orchestrator) already exists and is wired — the work is a management/persistence layer + IA over it, not new agent-execution machinery. Builder may split into its own card to keep this at L.
---
## 9. Open questions
1. **Agent vs Persona boundary:** does v1 introduce a true persisted Agent object distinct from Persona, or does Agent Center initially just re-skin the persona catalog with derived status? (Recommend: real Agent entity, JSON store, referencing `personaId`.)
2. **`/api/agents/*` collision:** confirm the desktop should get its OWN sidecar `agents.ts` rather than proxying the Clerk-gated cloud route (the sidecar has no Clerk). (Backend-map says local is MISSING; assume net-new sidecar.)
3. **Persistence choice:** JSON store (`agents.json`, no migration) vs `agents` table in `mind/schema.ts` (SCHEMA_VERSION bump)? PRD §14.4 non-goal favors minimal backend; JSON recommended for v1.
4. **successRate/lastRun:** derive at read from `execution_traces`/`procedures`, or persist on the agent? (Derive recommended; storing risks staleness.)
5. **Autonomous agents:** are these modeled as Agent + linked cron automation (S11), or a distinct entity? Blueprint p.8 says "explicit schedule/trigger" — likely an Agent that owns a cron id.
6. **Categories taxonomy:** PRD lists Personal/Workspace/Team/Autonomous/Templates/Archive (6); mockup shows All/Personal/Workspace/Team/Autonomous/Archive + a separate Templates control. Confirm whether Templates is a tab or a side affordance.
7. **Run target resolution:** when an agent has multiple `workspaceIds`, which workspace does `/run` spawn into? Needs a picker or a default.

274
docs/ux-refactor/gap-cards/S10-team-workspace.md Normal file
View File

@@ -0,0 +1,274 @@
# Gap Card — S10 · Team Workspace
> Screen S10 of the Waggle OS UX-refactor. Execution model is the LOCKED **in-place
> incremental refactor** of `apps/web` + targeted backend extensions. Mockups are
> directional; PRD acceptance criteria win. Every claim below is grounded in real files.
>
> Sources: PRD §12.11 (lines 613-626), §16.11 (1152-1158), §17 RBAC (1162-1187),
> §10.5 (329-338), §18 (1191-1218); blueprint `_blueprint_extracted.txt` lines 346-349,
> 470-473, 509, 514, 531-540, 542-545, J18/J19/J20/J21 (227-242); mockup
> `screen_10_team_workspace.png`.
---
## 1. Screen & purpose
**Purpose (PRD §12.11):** "Shared intelligence for teams." Team mode must feel like
**shared knowledge and shared outcomes**, not just a member list + chat (explicit
acceptance criterion, PRD line 626). It is the surface for the **Team layer** of the IA
(PRD §10.5): team workspace, members, roles/permissions, shared memory, shared artifacts,
shared skills, shared MCPs, and activity/audit.
This is a **Teams/Enterprise-tier** surface (PRD tier table; current placeholder gates it
to "Teams ($49/mo per seat) and Enterprise"). It is the UI home for RBAC (PRD §17) and the
team-governance API contract (PRD §16.11).
The mockup shows: workspace header with a team switcher + Invite/+ buttons; a metrics strip
(memory frames, agents, automations, tasks); a "Team Activity" feed; "Pinned" items;
"Team Members" panel with avatars/roles; a "Team Intelligence" summary card; "Upcoming"
events; and a "Team Goals" progress section. Treat as visual direction only.
---
## 2. Required states (PRD / Blueprint)
**Tabs (PRD §12.11, line 619):** Overview · Shared Memory · Shared Artifacts · Skills ·
Agents · MCPs · Automations · Settings.
**Overview content (PRD line 620):** team spaces, metrics, members, activity, pinned items,
team goals, upcoming events, team intelligence summary.
**Sharing (PRD line 621):** share memory / artifact / skill / MCP / automation **into team
scope subject to role**. Journeys: J19 share memory → choose scope → audit → appears in team
memory; J20 share artifact → team/workspace/member → permissions → activity feed (blueprint
234-239).
**Member management + RBAC (PRD line 622):** invite/member management (J18: invite → role
selected → accept → permissions applied, blueprint 227-228).
**RBAC roles (conflict to resolve — see §6):**
- PRD §17.2 table: **Owner / Admin / Contributor / Viewer**.
- Blueprint §RBAC model + role table: **Owner / Admin / Member / Viewer / Guest** (lines 156,
536-540, 603).
- Live substrate (`teams.db`): **owner / admin / member / viewer** (no contributor, no guest).
**Empty / loading / permission states (blueprint 470-473):** Loading, empty, populated,
**permission denied**; Invite pending, role conflict, shared/private, audit event. Member
actions: request access, change role, resend invite, export audit. J21: permission denied →
permission message → request access (**no silent failures or data leakage**, blueprint 240-242).
**Cache invalidation triggers (blueprint 514):** memory import, artifact update, agent run
completion, connector sync, automation completion, **RBAC change** — the Team Workspace must
re-fetch on any of these.
**Solo/offline behavior:** RBAC must be enforced at **both API and UI layers** (blueprint 162).
Local team CRUD already works in solo mode with a local userId (see §3).
---
## 3. Current state in repo (disposition: **rework**)
**Frontend — `apps/web/src/components/os/apps/TeamGovernanceApp.tsx` (45 lines):** a pure
**static placeholder**. It renders three hardcoded info cards (Role-Based Access / Tool
Governance / Audit Trail) + a tier-gate banner. **Zero data fetching, zero adapter calls, no
tabs, no members, no activity.** Registered as appId `governance` in `Desktop.tsx`/`Dock.tsx`
(see frontend inventory §a, line 47). The mockup's entire surface is unbuilt.
**Adapter — `apps/web/src/lib/adapter.ts`** has only the **remote-proxy** team methods:
`teamConnect` (`:1226`), `teamDisconnect`, `getTeamStatus` (`:1234`), `getTeamMembers`
(`:1239`), `getTeamActivity` (`:1247`), `getTeamMessages` (`:1255`), `searchTeamMemory`
(`:489`). **There are NO adapter methods for the local `/api/teams/*` CRUD** (create team,
get team detail, invite/add member, change role, remove member, team activity/audit). This is
the single biggest frontend wiring gap.
**Backend — substrate is strong and already live.** `packages/server/src/local/routes/team.ts`
exposes two prefixes:
- `/api/team/*` = **remote team-server proxy** with local fallbacks (connect/disconnect/status/
teams/members/presence/activity/messages/governance/memory-search). `/api/team/connect` is
`requireTier('TEAMS')` (`:110`); `/api/team/governance/permissions` is `requireTier('ENTERPRISE')`
(`:418`).
- `/api/teams/*` = **local SQLite CRUD on `teams.db`** (`teams` + `team_members` tables, DDL at
`team.ts:51-72`), works in **solo mode** via `getLocalUserId(dataDir)` (`:457`). Full CRUD:
`POST /api/teams` (`:460`, auto-adds creator as `owner`), `GET /api/teams` (`:492`),
`GET /api/teams/:id` (`:505`, returns team + members), `PUT /api/teams/:id` (`:523`),
`DELETE /api/teams/:id` (`:553`, owner-only), `POST /api/teams/:id/members` (`:581`,
owner/admin only — **this is invite/add**), `PUT`+`PATCH /api/teams/:id/members/:userId`
(`:615`/`:642`, role change), `DELETE /api/teams/:id/members/:userId` (`:665`),
`GET /api/teams/:id/activity` (`:690`, reads `audit_events` via `getAuditDb` from `events.js`,
`:713-722`).
**RBAC is already enforced server-side** with per-action checks: owner/admin gate add-member
(`:591`), owner-only gate role change in PUT (`:624`) but owner/admin in PATCH (`:649` — a
real inconsistency to fix, see §9), owner-only delete-team (`:558`), can't remove the owner
(`:682`), member self-removal allowed (`:677`). The local `team_members.role` CHECK constraint
is `('owner','admin','member','viewer')` (`team.ts:64`) — **no contributor, no guest**.
**Remote/cloud governance substrate (backend-map §02b):** the Postgres team layer
(`packages/server/src/db/schema.ts`, 20 tables) has `teams`, `team_members` (composite PK
`(team_id,user_id)`, role default `'member'`, 02b:93-101), `team_entities`/`team_relations`/
`team_resources` (shared KG + assets, 02b:181-228), and the three **team-capability governance**
tables added in migration `0001`: `team_capability_policies` (standing policy per role, 02b:232),
`team_capability_overrides` (one-off allow/deny, 02b:247), `team_capability_requests`
(request→decision queue, 02b:262). These back the per-role tool allow/deny + approval surfaces
the mockup/PRD imply, **but only on the cloud server** — the local `/api/team/governance/permissions`
proxy (`:418`) is the only sidecar window into them. **Note (02b:44): Postgres FKs are all
`ON DELETE no action` — no cascades; deleting a team/user is blocked if children reference it.**
**Disposition rationale — rework (not create-new):** the `governance` app slot, the dock entry,
the tier-gate, and (critically) the **entire local team CRUD + RBAC enforcement substrate already
exist**. The screen needs the placeholder component replaced with a real tabbed surface wired to
existing routes + new adapter methods — not a new app and not a new backend data store.
---
## 4. Frontend work
**Rework `TeamGovernanceApp.tsx`** (rename concept to "Team Workspace"; keep appId `governance`
to avoid touching `Desktop`/`Dock`/`dock-tiers` routing) into a tabbed shell. Reuse the existing
tabbed-app pattern (`MemoryApp.tsx` 6-tab model, `SettingsApp.tsx` 8-tab model, `ui/tabs.tsx`).
**Components to create** (keep files small, 200-400 LOC per CLAUDE.md §coding-style):
- `apps/team/TeamWorkspaceApp.tsx` (or in-place rework of `TeamGovernanceApp.tsx`) — tab shell:
Overview · Shared Memory · Shared Artifacts · Skills · Agents · MCPs · Automations · Settings.
Tier-gate stays (Teams/Enterprise) via existing `LockedFeature.tsx` / `useFeatureGate`.
- `apps/team/TeamOverviewTab.tsx` — metrics strip + activity feed + pinned + team goals +
upcoming + team-intelligence summary (mockup Overview).
- `apps/team/TeamMembersPanel.tsx` — member list with avatars + role badges + role-change
dropdown + remove (gated by current-user role). Reuse `ui/avatar`, `ui/badge`,
`ui/dropdown-menu`.
- `overlays/InviteMemberDialog.tsx` — invite by email/userId + role select (J18). Reuse
`ui/dialog`, `ui/select`. POSTs to `/api/teams/:id/members`.
- `apps/team/TeamActivityFeed.tsx` — audit/activity list (reuse `TimelineApp`/`EventsApp` row
styling). Export audit action (blueprint 472).
- `apps/team/ShareToTeamDialog.tsx` — scope picker (team/workspace/member) for sharing a
memory/artifact/skill/MCP/automation into team scope with role check (J19/J20). Surfaced
from Memory/Artifact screens too; lives here as the canonical component.
- `components/os/PermissionDenied.tsx` — shared "permission denied + request access" state
(J21) — reusable across Team tabs and elsewhere.
**Reuse targets:** `MemoryApp`'s frame list for the Shared Memory tab (filtered to team scope
via `searchTeamMemory`); `CapabilitiesApp`/`AgentsApp`/`ScheduledJobsApp` list rows for the
Skills/Agents/MCPs/Automations tabs (read-only team-scoped views first). `ContextMenu` for
row-level "Share to team".
**New hook — `hooks/useTeam.ts`** (mirror `useWorkspaces` shape): returns `{ team, members,
activity, currentUserRole, createTeam, invite, changeRole, removeMember, refresh }`. Drives
RBAC at the UI layer (blueprint 162): compute `currentUserRole` from `GET /api/teams/:id`
members + local userId, then hide/disable actions per PRD §17.2 capability matrix.
**New adapter methods** (add to `lib/adapter.ts` `LocalAdapter`, local `/api/teams/*` family —
this is where new PRD §16 endpoints land per frontend inventory §c): `getTeams`,
`getTeam(id)`, `createTeam`, `updateTeam`, `deleteTeam`, `inviteMember(id, {userId?, email?,
displayName?, role?})`, `changeMemberRole(id, userId, role)`, `removeMember(id, userId)`,
`getTeamAudit(id)`, and (for §16.11) `shareToTeam(...)`.
**State management (blueprint 511-514):** Team Workspace re-fetches on the RBAC-change cache
trigger + memory-import/artifact-update/automation-completion triggers. Use the existing
`QueryClient` invalidation pattern.
---
## 5. Backend work (PRD §16.11)
| PRD §16.11 endpoint | Status | Action |
|---|---|---|
| `GET /api/teams/:id` | **EXISTS** | `team.ts:505` — returns team + members. Wire adapter `getTeam`. No backend change. |
| `POST /api/teams/:id/invite` | **PARTIAL → EXTEND** | Invite is implemented as `POST /api/teams/:id/members` (`team.ts:581`, owner/admin gated). **Add a thin `/invite` alias** that forwards to the members handler (PRD uses `/invite`; substrate is `team_members` in `teams.db`). No new substrate. |
| `PATCH /api/teams/:id/members/:memberId` | **EXISTS** | `team.ts:642` (`:userId` == PRD `:memberId`); `PUT` variant at `:615`. **Fix the PUT/PATCH role-gate inconsistency** (PUT owner-only vs PATCH owner/admin — §9). Wire adapter `changeMemberRole`. |
| `GET /api/teams/:id/audit` | **PARTIAL → ALIAS** | Closest is `GET /api/teams/:id/activity` (`team.ts:690`, reads `audit_events` via `events.js` `getAuditDb`). **Alias `/audit` → the activity handler** (or add the audit-export shape). Substrate: `audit_events` table (events.ts). No new store. |
| `POST /api/share` | **MISSING → NET-NEW** | No `/api/share` route anywhere (grep-confirmed across `local/routes`). Sharing into team scope today is **implicit** (workspace `teamId` linkage at create + remote team-server frame sync). Net-new route accepting `{ kind: memory\|artifact\|skill\|mcp\|automation, id, scope: team\|workspace\|member, targetId }`, **role-checked** (PRD §17.2 "Can share"), writing into the team scope and emitting an audit event (reuse `emitAuditEvent`, already used in `team.ts:484`). Touches: `team_entities`/`team_resources` (cloud, 02b) for the synced object, `audit_events` (local) for the trail. For solo/local mode, share = tag the frame/artifact with team scope (note the FE/DB scope is implicit per-`.mind` today — see §6 + substrate-types §c). |
**Implied additional route (not in §16.11, flag for plan):** an **install-audit / governance read
route** for the Skills/Agents/MCPs tabs. `InstallAuditStore.getRecent/getByCapability` exist in
`packages/core/src/install-audit.ts` but **have no HTTP endpoint** (substrate-types §d). The
Team Workspace governance view (who installed what / risk / trust / approval) needs e.g.
`GET /api/extend/audit` or `GET /api/teams/:id/governance` surfacing `team_capability_policies/
overrides/requests`. The Enterprise proxy `GET /api/team/governance/permissions` (`team.ts:418`)
is the only existing window and is read-only + ENTERPRISE-gated.
**.mind migration:** **None required for the team CRUD/RBAC core** — `teams.db` is a standalone
SQLite file with its own DDL (created on demand). The Postgres `team_capability_*` tables already
exist (migration `0001`). The only schema-adjacent work is if team-scope sharing needs a
structured `scope`/`teamId` on `memory_frames` (currently implicit per-`.mind`; substrate-types
§c flags `teamId`/`scope` as MISSING columns) — that would be a metadata-column migration on
`memory_frames`, deferrable behind the implicit-scope approach for v1.
---
## 6. Shared types needed (PRD §15 vs `lib/types.ts`)
- **No `Team` / `TeamMember` / `TeamRole` types exist in `apps/web/src/lib/types.ts`.** Add
them (frontend inventory §d confirms the types.ts export list has no team entities). Source of
truth for the server shapes: `team.ts` `TeamRole = 'owner'|'admin'|'member'|'viewer'` (`:21`),
`MemberRow` (`team.ts:799-810` mapper).
- **RBAC role-union conflict — MUST be resolved before coding (decision needed, §9):**
- PRD §17.2 → `Owner | Admin | Contributor | Viewer`
- Blueprint → `Owner | Admin | Member | Viewer | Guest`
- Live `teams.db` CHECK → `owner | admin | member | viewer`
Recommendation: keep the live 4-role union (`owner/admin/member/viewer`) for v1 to avoid a DB
CHECK migration + RBAC-logic rewrite; treat PRD "Contributor" == "Member" and defer "Guest" as
a follow-up (it needs a new role + new deny-by-default capability rules). Surface this to the
founder per CLAUDE.md §3.1.
- **`Scope` union** (`personal/workspace/team/organization`) — MISSING in FE types
(substrate-types §e). Needed for `ShareToTeamDialog`. Add to `lib/types.ts` (PRD §15.2).
- **Capability/policy types** for the governance tabs (`team_capability_policies/overrides/
requests` shapes from 02b) — add FE types when that read route lands.
- Reuse existing `TierCapabilities` from `@waggle/shared` (`tiers.ts`) for the tier-gate; do not
invent a parallel gate.
---
## 7. Dependencies (screens / phases first)
- **RBAC role-model decision (§6/§9)** blocks the `TeamRole` type + all member-management UI —
resolve first.
- **`ShareToTeamDialog`** is cross-screen: it is invoked from S-Memory (J19) and S-Artifacts
(J20). Artifacts have **no backing entity at all** (substrate-types §e — the single largest
entity gap), so artifact-sharing depends on the Artifacts screen/entity landing first; memory-
sharing can ship independently against `memory_frames` + `searchTeamMemory`.
- **Permission-denied / request-access pattern (J21)** is shared with other screens — build the
reusable `PermissionDenied` component here, reuse elsewhere.
- Tier gating depends on `useFeatureGate`/`LockedFeature` (exist) — no new dependency.
- The remote/cloud governance tabs (per-role capability policies) depend on the **install-audit
read route** (§5 implied) which is itself a separate small backend task.
**Phase placement:** this is a **later-phase** screen. The foundational Work/Intelligence screens
(Home, Workspace Desktop, Memory, Agents) and the Artifacts entity should land first; Team
Workspace composes their list rows + shares into team scope.
---
## 8. Effort: **L**
The backend core is mostly EXISTS/PARTIAL (CRUD + RBAC enforcement + activity already live, only
`/invite` alias + `/audit` alias + the genuinely net-new `/api/share` + a governance read route),
but the **frontend is a from-zero rework of a 45-line placeholder into an 8-tab surface** with a
new hook, ~8 new components, ~10 new adapter methods, UI-layer RBAC gating, the shared
share/permission-denied components, and an unresolved role-model decision. Not XL because no new
data store and no `.mind` migration is required for v1; not M because of the tab/share/RBAC breadth
+ cross-screen coupling.
---
## 9. Open questions
1. **RBAC role model (blocking):** adopt PRD §17.2 (`Owner/Admin/Contributor/Viewer`), blueprint
(`+Member +Guest`), or keep the live `teams.db` 4-role union (`owner/admin/member/viewer`)?
Recommendation: keep live union for v1, map Contributor→Member, defer Guest. Needs founder sign-off.
2. **PUT vs PATCH role-gate inconsistency (real bug):** `PUT /api/teams/:id/members/:userId` is
**owner-only** (`team.ts:624`) but `PATCH` on the same path is **owner/admin** (`:649`). The PRD
uses PATCH. Which gate is correct — owner-only role changes, or owner+admin? Align both.
3. **`/api/share` scope semantics in solo/local mode:** memory frames have **no structured
`scope`/`teamId` column** (implicit per-`.mind`, substrate-types §c). For v1, model team-share as
(a) implicit via workspace `teamId` + remote sync, or (b) a `memory_frames` metadata migration?
Recommendation: (a) for v1, defer (b).
4. **Local vs remote team source of truth on this screen:** `/api/teams/*` (local `teams.db`, always
works) vs `/api/team/*` (remote proxy, TEAMS-gated). Does Team Workspace render local teams in solo
mode and switch to remote when connected, or remote-only? (Affects whether members/activity come
from `teams.db` or the team server.)
5. **Governance tabs depth for v1:** do the Skills/Agents/MCPs/Automations tabs render full
per-role capability policies (`team_capability_*` cloud tables) now, or ship read-only shared-item
lists first and defer the policy editor?
6. **Postgres no-cascade (02b:44):** deleting a team is blocked by FKs if `team_entities`/resources/
members reference it. The local `DELETE /api/teams/:id` deletes members first (`team.ts:563`) — does
the cloud delete path need an explicit child-cleanup order, and should the UI warn before delete?

249
docs/ux-refactor/gap-cards/S11-automation-center.md Normal file
View File

@@ -0,0 +1,249 @@
# Gap Card — S11 Automation Center
> UX-refactor implementation planning. Screen 11 of the 21-screen inventory.
> Execution model is LOCKED: in-place incremental refactor of `apps/web` + targeted
> backend extensions. The mockup is DIRECTIONAL; PRD acceptance criteria win over pixels.
> Every claim below is grounded in a real file (path + line where load-bearing).
>
> PRD: `docs/Waggle_OS_UX_Refactor_Master_Handoff_Package/Waggle_OS_UX_Refactor_PRD.md`
> §12.10 (lines 597-611), §16.10 (lines 1143-1150). Blueprint screen spec: `_blueprint_extracted.txt:354-359`.
---
## 1. Screen & purpose
**Automation Center + Automation Builder** — manage scheduled and event-driven work so
overnight/background runs are visible, reviewable, and stoppable (PRD §12.10; Definition of
Done #7 "automations… have coherent IA"; principle #9 "Automation with trust").
The PRD object is **Automation** (§11 glossary): "Scheduled/event-driven workflow using
triggers/actions/agents. Must be visible/stoppable." In the live repo this is **cron**:
`packages/core/src/cron-store.ts` (`CronStore`) + `packages/server/src/local/cron.ts`
(`LocalScheduler`) + `packages/server/src/local/routes/cron.ts` (`/api/cron/*`). The backend-map
is explicit: "Automations = a rename/extension of cron" (`_inventory/backend-routes.md:531`).
Two intelligence-layer surfaces overlap here and must NOT be double-built:
- **`ScheduledJobsApp.tsx`** (dock id `scheduled-jobs`) — the existing cron CRUD UI; this IS the
Automation Center seed.
- **`EventsApp.tsx`** (dock id `events`) — agent event/step stream + agent tree; this is the
closest existing analog for the Builder's "actions = agent task" and for History/Logs detail,
but it streams live `AgentStep`s, NOT cron execution rows. Different data source.
---
## 2. Required states (PRD / Blueprint)
**PRD §12.10 tabs:** Overview, Running, Scheduled, Triggers, History, Logs.
**Automation Builder steps:** Trigger → Condition → Actions → Review & Activate.
**Automation fields:** name, trigger, condition, actions, agent, notification, schedule, workspace, status.
**Actions:** run now, pause, edit, view logs, retry, disable.
**Cross-screen:** "Failed or risky automations surface in Home Cockpit attention required" (§12.10,
also Journey 16 / J17 `_blueprint_extracted.txt:224-226`, S01 Home Cockpit gap card dependency).
**States** (PRD §12.10 + §14.6 Automation states, lines 895-904; blueprint `:356-357`):
Draft, Scheduled, Running, Success, Failed, Paused, Awaiting approval, Disabled — plus the §14.1
global mandatory states: Loading, Empty, Populated, Error, Offline/local-only, Permission denied.
**Acceptance:** "Overnight work is visible, reviewable and stoppable" (PRD line 610; blueprint `:358-359`).
**Mockup (directional only):** header stat tiles (Active 8 / Scheduled 24 / Triggers 12 / Success
Rate 98.6% / Hours Saved 156h), an "Automation Health" donut (Healthy/Warning/Failed/Paused), a
"Running Automations" list with progress bars, a "Scheduled Automations" table (name / schedule /
next-run / workspace / status), a "Recent Activity" feed, and a "Popular Templates" rail. These map
to existing substrate (see §5) EXCEPT the analytics tiles (success-rate / hours-saved) and live
progress bars, which have no backing today — treat as derived/aspirational, not v1 blockers.
---
## 3. Current state in repo
**Disposition: `rework`** (promote + extend `ScheduledJobsApp` into Automation Center; the cron
substrate is solid and reused wholesale — this is the textbook in-place refactor case).
### Frontend (exists)
- **`apps/web/src/components/os/apps/ScheduledJobsApp.tsx`** — full cron CRUD UI. Single flat list +
inline create form. Calls `adapter.getCronJobs / createCronJob / updateCronJob / deleteCronJob /
triggerCronJob`. Create form already collects `jobType` (6 types via `CRON_JOB_TYPES`), schedule
(presets + custom cron via `CRON_SCHEDULE_PRESETS`), and an output channel (log/telegram). Per-row:
toggle enable/disable, Run-now (`triggerCronJob`, auto-enable handled), delete. **No tabs, no
history/logs view, no "Builder" stepper, no triggers concept.**
- **`apps/web/src/lib/cron-presets.ts`** — `CRON_JOB_TYPES` (6 job types w/ labels+descriptions),
`CRON_SCHEDULE_PRESETS` (6 cadences), `describeCronExpr`, `isPlausibleCronExpr`. Reuse as-is for
the Builder's schedule step.
- **`apps/web/src/components/os/apps/EventsApp.tsx`** — agent step stream (live/tree/replay tabs),
`buildAgentTree`. NOT cron-backed; relevant only as a visual pattern for History/Logs, not a data
source.
- **`apps/web/src/lib/types.ts:230-238`** — `CronJob { id, name, schedule, workspaceId, enabled,
lastRun?, nextRun? }`. Lossy projection (drops `jobType`, `jobConfig`, `nextRun` exists but
`lastRunAt`/`nextRunAt` are remapped to `lastRun`/`nextRun` by `normalizeCronJob` in `adapter.ts`).
- **`apps/web/src/lib/adapter.ts:811-851`** — cron methods. **Two defects to fix in the rework:**
1. `updateCronJob` (`:836`) issues **`PUT /api/cron/:id`**, but the server registers ONLY
`PATCH /api/cron/:id` (`routes/cron.ts:115-124`) — there is **no PUT cron route**
(grep-confirmed). The toggle in `ScheduledJobsApp.handleToggle` goes through this and would
404. Change to PATCH.
2. **No `getCronHistory` adapter method** exists, even though the route does (`/api/cron/:id/history`,
`notifications.ts:198-210`). History/Logs tabs need it added.
### Backend (exists, reused wholesale)
- **`packages/server/src/local/routes/cron.ts`** — POST/GET(list)/GET(:id)/PATCH/DELETE/POST(:id/trigger).
Trigger calls `server.scheduler.executeJob` and auto-enables disabled jobs (`:188-191`), emits a
`cron`-category notification (`:197-202`).
- **`packages/server/src/local/routes/notifications.ts:198-210`** — `GET /api/cron/:id/history`
→ `cronStore.getExecutionHistory(id, limit)` → `{ history, count }`.
- **`packages/core/src/cron-store.ts`** — `CronStore`: schedules table (`cron_schedules`), execution
history (`cron_execution_history` w/ `success`, `duration_ms`, `result_summary`, `error` — `:88-101`),
notifications. `recordExecution` (`:281`), `getExecutionHistory` (`:294`). 6 `CronJobType`s (`:15`):
`agent_task | memory_consolidation | workspace_health | proactive | prompt_optimization | monthly_assessment`.
- **`packages/server/src/local/cron.ts`** — `LocalScheduler`: tick loop, concurrency guard,
per-job failure tracking, **auto-disable after 5 consecutive failures** (`MAX_CONSECUTIVE_FAILURES`,
`:23,138-141`) — this maps directly to the §14.6 "Failed"/"Disabled" states.
- **`packages/server/src/local/setup-crons.ts`** + `executeJob` wiring (job-type dispatch) — confirm
which job types actually execute when planning the Builder's "Actions" step.
### What's MISSING entirely (net-new frontend, no backend store needed)
- **Trigger concept.** Cron is time-only (`cronExpr`). PRD §12.10 "Triggers" tab + Builder "Trigger"
step imply event-driven triggers (not just schedules). No event-trigger substrate exists; v1 should
scope Trigger = schedule-only, with event-trigger as an open question (see §9).
- **Condition concept.** No `condition` field on `CronSchedule`. Builder "Condition" step is net-new
(model as optional `jobConfig.condition`, no schema change).
- **Analytics** (success-rate %, hours-saved, health donut) — derivable from `cron_execution_history`
but no aggregation endpoint/UI today.
---
## 4. Frontend work
### Components to create / rework
| Component | Action | Notes |
|---|---|---|
| `ScheduledJobsApp.tsx` → **`AutomationCenterApp.tsx`** | **rework/rename** | Promote to tabbed shell: Overview / Running / Scheduled / Triggers / History / Logs (PRD §12.10). Keep the proven cron CRUD wiring; lift the existing flat list into the "Scheduled" tab. Add an Automation Health summary (counts by enabled/disabled/failed from existing data). Keep dock id `scheduled-jobs` OR add an alias (don't break `dock-tiers.ts` `AppId` union + `Desktop.renderAppContent` switch — `frontend.md:142-151`). Update `appConfig` title/icon in `Desktop.tsx`. |
| `AutomationBuilder.tsx` (overlay) | **create-new** | 4-step stepper (Trigger → Condition → Actions → Review & Activate) per PRD §12.10. Reuse the existing create-form fields (jobType, schedule presets, output channel) from `ScheduledJobsApp` + `cron-presets.ts`. Use the shadcn stepper-style pattern (PRD §19 "Builder stepper"); align with sibling builders (Agent/Skill builders, other S-cards). |
| `AutomationCard.tsx` | **create-new (small)** | Per-automation row: name, schedule summary (`describeCronExpr`), next-run, workspace, status badge (Running/Scheduled/Paused/Failed/Disabled), actions (run-now/pause/edit/logs/delete). Extract from current inline `ScheduledJobsApp` row JSX. |
| History/Logs tab content | **create-new** | List `cron_execution_history` rows (executed_at, duration, success/error, result_summary). Visual pattern can borrow `EventsApp` StepCard expand/collapse, but data = cron history, not `AgentStep`. |
### Reuse targets
- `cron-presets.ts` (schedule presets + job-type catalog + `describeCronExpr`) — as-is.
- `HintTooltip`, shadcn `tabs`/`table`/`badge`/`skeleton`/`dialog` (`components/ui/*`, `frontend.md:336-342`).
- Status-badge + skeleton/empty/error patterns already used across apps.
- `EventsApp` StepCard pattern (visual only) for the Logs detail rows.
### Adapter methods / hooks
- **Fix** `adapter.updateCronJob` → `PATCH` (currently `PUT`, 404s — `adapter.ts:837`).
- **Add** `adapter.getCronHistory(id, limit?)` → `GET /api/cron/:id/history` (route exists,
`notifications.ts:202`).
- **Add** `adapter.pauseCronJob(id)` thin helper → `PATCH /api/cron/:id { enabled:false }`
(PRD calls it "pause"; backend models it as `enabled:false` — `backend-routes.md:540`).
- **(Optional) Add** an `automations` alias namespace in the adapter so the new components read
PRD vocabulary while pointing at `/api/cron/*` — keeps the rename cosmetic, zero backend churn.
- **New hook `useAutomations`** (mirror `useWaggleDance`/`useNotifications` shape): wraps
list/create/update/delete/trigger/pause/history; optionally subscribes to the existing
`/api/notifications/stream` (`cron`-category events) for live status. No new SSE channel needed.
- Cross-screen: emit failed-automation count into the S01 Home Cockpit "attention required" feed
(PRD §12.10; consumes `cron_execution_history.success=0` + scheduler auto-disable signal).
### Props / state
- `AutomationCenterApp`: `activeTab`, `jobs: CronJob[]`, `loading`, `creating`, per-row `triggering`.
- `AutomationBuilder`: `step`, `{name, jobType, scheduleExpr, workspaceId, condition?, outputChannel}`,
`testing?` (Review step "test" before activate, per PRD §12.10 / Journey 12 step 5).
- Extend `CronJob` FE type with `jobType` + `jobConfig` (currently dropped by `normalizeCronJob`) so
the Builder can round-trip edits without re-deriving.
---
## 5. Backend work (PRD §16.10 endpoint-by-endpoint)
> Verdict for the whole section: **the cron substrate is complete; §16.10 is a rename/alias job, NOT
> net-new backend.** Backend-routes inventory: §16.10 = 0 EXISTS / 6 PARTIAL / 0 MISSING
> (`backend-routes.md:595`). All six "Automation" endpoints map onto existing `/api/cron/*` in
> `routes/cron.ts` + the history route in `notifications.ts`. Substrate touched: `cron_schedules` +
> `cron_execution_history` (in the personal/workspace `.mind` DB via `CronStore`). **No `.mind`
> migration required** (both tables already exist with lazy creation, `cron-store.ts:135-157`).
| PRD §16.10 endpoint | Status | EXTEND vs NET-NEW · substrate |
|---|---|---|
| `GET /api/automations` | **PARTIAL** | EXTEND: alias of `GET /api/cron` (`cron.ts:94`). Either register an `/api/automations` alias plugin that re-exports the cron handlers, or just point the new UI at `/api/cron`. Substrate: `cron_schedules`. |
| `POST /api/automations` | **PARTIAL** | EXTEND: alias of `POST /api/cron` (`cron.ts:67`). To support PRD `condition`, stash it in `jobConfig.condition` (no schema change — `job_config TEXT`). |
| `PATCH /api/automations/:id` | **PARTIAL** | EXTEND: alias of `PATCH /api/cron/:id` (`cron.ts:115`). |
| `POST /api/automations/:id/run` | **PARTIAL** | EXTEND: alias of `POST /api/cron/:id/trigger` (`cron.ts:172`; auto-enables + executes + emits notification). |
| `POST /api/automations/:id/pause` | **PARTIAL** | EXTEND: no dedicated `/pause`; equivalent is `PATCH /api/cron/:id { enabled:false }`. Add a thin `/pause` route OR have the adapter call PATCH (`backend-routes.md:540`). |
| `GET /api/automations/:id/logs` | **PARTIAL** | EXTEND: alias of `GET /api/cron/:id/history` (`notifications.ts:202` → `cronStore.getExecutionHistory`). Substrate: `cron_execution_history`. |
**Implied additions NOT in §16.10 (flag for plan):**
- **Overview/analytics aggregation** (mockup tiles: active/scheduled/success-rate/hours-saved + health
donut). No endpoint sums `cron_execution_history` today. Either compute client-side from per-job
history (cheap for small N) OR add a thin `GET /api/automations/summary`. Hours-saved has no source —
drop or stub. **Not a v1 blocker.**
- **Builder "test" before activate** (PRD §12.10 / Journey 12). `POST /api/cron/:id/trigger` runs a
real (auto-enabling) execution; there is no dry-run. Either reuse trigger as the "test run" (accepting
it really runs) OR scope test-run as an open question.
**.mind migration flag:** NONE. `cron_schedules` + `cron_execution_history` + `notifications` all
self-create (`cron-store.ts:135-157`). The only schema-adjacent change is storing `condition` inside
the existing `job_config` JSON blob.
---
## 6. Shared types needed (PRD §15 vs `lib/types.ts`)
PRD §15 has **no dedicated Automation type** (the §15.2 unions cover Workspace/Memory/Artifact/Agent
but not Automation). So the type work is FE-local:
- **Extend `CronJob`** (`lib/types.ts:230-238`) with `jobType: CronJobType` and `jobConfig?:
Record<string, unknown>` (both currently dropped on the FE side by `normalizeCronJob` —
`adapter.ts:818`). Keep the legacy `schedule`/`lastRun`/`nextRun` remap for back-compat.
- **Add `CronExecutionRow`** FE mirror of the server type (`cron-store.ts:48-57`:
`id, schedule_id, schedule_name, executed_at, duration_ms, success, result_summary, error`) for the
History/Logs tab — camelCased in the adapter.
- **Add an `AutomationStatus` union** for badge rendering: derived (not stored) from
`enabled` + last-history-row success + scheduler disabled-set: `'scheduled' | 'running' | 'paused' |
'failed' | 'disabled'`. Maps to PRD §14.6.
- The 6-member `CronJobType` union is **duplicated** in two places (`cron-presets.ts:15` and
`core/cron-store.ts:15`) — reuse `cron-presets.ts`'s for FE; do NOT add a third copy.
- No PRD §15.2 union (`AutonomyLevel`, `ExtensionType`, etc.) is required for this screen.
---
## 7. Dependencies (screens / phases first)
- **Phase 3 — Intelligence layer** (PRD §8 / Roadmap Sprint 6, lines 236-240, 1344-1351). Same sprint
as Agent Center/Builder + Skills Hub/Builder; the Automation Builder's "Actions = run an agent task"
step benefits from Agent Center existing first, but cron's `agent_task` job type already works
standalone, so it is **not a hard block**.
- **S01 Home Cockpit** (downstream consumer): failed/risky automations must surface in Home "attention
required" (PRD §12.10, §12.1). Coordinate the failed-count signal contract with the S01 gap card.
- **AppShell / dock IA** (Phase 0): the rename/relocation of `scheduled-jobs` into the Intelligence
bucket touches `dock-tiers.ts` `AppId` + `Desktop.tsx` `appConfig`/`renderAppContent`
(`frontend.md:142-151`). Sequence after the Phase-0 IA freeze.
- Builder stepper pattern should be shared across Agent/Skill/Automation builders — coordinate the
common stepper primitive (PRD §19.1 "Builder stepper") rather than three bespoke steppers.
---
## 8. Effort
**M.** The backend is essentially free (6 PARTIAL endpoints = thin aliases over existing cron routes +
two real adapter fixes). Frontend is a moderate rework: promote the existing single-list
`ScheduledJobsApp` to a 6-tab Center, build a 4-step Builder overlay, add a History/Logs tab over an
existing route, and wire the Home-Cockpit failed-automation signal. No new data store, no `.mind`
migration. Pushes toward L only if event-driven Triggers (vs schedule-only) are pulled into v1.
---
## 9. Open questions
1. **Triggers tab scope.** PRD §12.10 lists "Triggers" as a tab and a Builder step, but cron is
schedule-only. Is v1 schedule-only (Trigger = cron cadence), or must event-driven triggers (e.g.
"on harvest complete", "on memory conflict") ship? No event-trigger substrate exists today.
2. **Condition step.** Is a real condition engine required, or is storing an advisory
`jobConfig.condition` string (no evaluation) acceptable for v1?
3. **Builder "test run".** Only `POST /api/cron/:id/trigger` exists and it really executes (and
auto-enables). Is reusing trigger as "test" acceptable, or do we need a dry-run path?
4. **Rename vs alias.** Register a true `/api/automations/*` alias plugin (PRD vocabulary in the
network tab) or keep `/api/cron/*` and rename only in the UI/adapter? (Affects the backend-map
contract surface.)
5. **Dock relocation.** Move `scheduled-jobs` into a new Intelligence dock zone, or keep its current
dock slot and just retitle? Confirm against the Phase-0 IA freeze.
6. **Analytics tiles.** Mockup shows success-rate % and "Hours Saved 156h". Success-rate is derivable
from `cron_execution_history`; hours-saved has no source. Drop hours-saved, or define a heuristic?
7. **Scope of automation = workspace vs global.** Cron supports `workspaceId:'global'` → `'*'`
(`cron.ts:73-74`). Does the Center show all-workspace automations, or filter to the active workspace?

225
docs/ux-refactor/gap-cards/S12-first-launch.md Normal file
View File

@@ -0,0 +1,225 @@
# Gap Card — S12 First Launch (Onboarding Step 1)
> Screen S12 of the Waggle OS UX-refactor. PRD source of truth: §12.12 (Onboarding Flow,
> step 1 "First Launch - promise and privacy"), §13 Journey 1 step 2, §14.1 global states.
> Blueprint screen spec: `_blueprint_extracted.txt:365-372` (PAGE 14, row 12). Mockup
> (directional only, PRD §24): `Waggle_OS_Handoff_Assets/screen_12_first_launch.png`.
> Execution model: **in-place incremental refactor** of `apps/web` — KEEP the wizard shell,
> redesign the welcome step per PRD §20.2.
---
## 1. Screen & purpose
The very first thing a fresh-install user sees: a minimal **promise + privacy reassurance**
splash before any setup. It is onboarding step 1 of the 7-step flow (PRD §12.12: First Launch →
Who Are You → Tool Discovery → Memory Import → Memory Review → Workspace Creation → Home Cockpit).
Purpose (blueprint S12): "Minimal promise and privacy reassurance." Acceptance (blueprint S12):
**"No infrastructure overload before user intent"** — i.e. no API-key/tier/model questions on
this screen; only the brand promise, a privacy note, a language affordance, and a single
Continue action.
Mockup content (directional): Waggle "W" logo + wordmark top-left; centered hero logo;
`Welcome to Waggle`; tagline `Your work. Your memory. Your agents.`; primary `Continue →`
button; a 4-dot progress indicator; footer-left privacy line ("Your data is private. Stored
locally."); footer-right language selector showing `English (US)`.
---
## 2. Required states (PRD / Blueprint)
Blueprint S12 names exactly four states (`_blueprint_extracted.txt:369-370`), plus the PRD §14.1
global-state baseline that "every major screen must implement":
| State | Source | What it means on S12 |
|---|---|---|
| **Fresh install** | Blueprint S12 | Default: brand promise + privacy + Continue. The only state the current code renders. |
| **Resumed setup** | Blueprint S12 | User dismissed/closed mid-onboarding and returns; wizard re-opens at the saved step (not necessarily step 0). Resume should land on the persisted step, and First Launch should communicate "picking up where you left off" rather than re-greeting cold. |
| **Offline** | Blueprint S12 + PRD §14.1 | Sidecar unreachable. Screen must still render (it is pre-network) and must not block; surface a non-alarming offline indicator and keep Continue usable (downstream steps degrade, not this one). |
| **Local-only** | Blueprint S12 + PRD §6/§18.1 (local-first default) | Privacy promise must be truthful and visible: "your data is private / stored locally." This is the trust hook the whole onboarding leans on (PRD §12.12 acceptance: "Nothing imports without explicit review/approval"). |
| Interaction: **Continue** | Blueprint S12 | Advance to step 2 (Who Are You). |
| Interaction: **Change language** | Blueprint S12 + mockup | A language affordance. **No i18n infra exists** (see §3) — scope decision required (§9). |
| Interaction: **View privacy note** | Blueprint S12 + mockup | A privacy note / link, inline or expandable. |
PRD §14.1 also lists Loading / Error / Permission-denied as universal — for a pre-network welcome
splash these collapse to: render immediately (no loading gate), and offline == the only "error-ish"
state that matters here.
---
## 3. Current state in repo (exact files + what they do)
**Disposition: `rework`** (KEEP the wizard shell per PRD §20.2 "Onboarding wizard → simplify";
redesign the step-0 component and add the missing affordances).
### The shell (KEEP)
- `apps/web/src/components/os/overlays/OnboardingWizard.tsx` — full-screen early-return wizard
(`OnboardingWizard.tsx:399-576`). Holds 8 steps (`STEP_NAMES`, `:35`):
`welcome / why-waggle / tier / memory-import / template / persona / api-key / ready`.
Step 0 auto-advances after **3 s** (`:136-141`), Escape → Skip (`:86-96`), a top progress bar +
step dots + Back + "Skip setup" chrome (`:421-493`). Rendered by `Desktop.tsx:262-272` when
`!onboardingState.completed`. This shell is the reuse target.
- `apps/web/src/hooks/useOnboarding.ts` — `OnboardingState` (`:10-19`: `completed, step, tier?,
workspaceId?, apiKeySet?, templateId?, personaId?, tooltipsDismissed?`), persisted to
`localStorage` key `waggle:onboarding` (`:21`). Auto-completes for returning users via Tauri
first-launch flag (`:102-131`) and a sidecar `getWorkspaces().length > 0` check (`:139-176`).
`?forceWizard=true` (DEV) forces step 0 (`:47-57`). **This is the "resumed setup" backbone** —
`state.step` already persists, so resume is half-built.
### The screen itself (REWORK)
- `apps/web/src/components/os/overlays/onboarding/WelcomeStep.tsx` — the current step-0 component
(54 lines). Renders the Waggle logo, eyebrow `Your AI Operating System`, `Welcome to the Hive`,
tagline `Persistent memory. Workspace-native. Built for knowledge work.`, a `Continue →` button
(`:39-45`) + "or click anywhere". **Gaps vs S12:** copy differs from mockup ("Welcome to the
Hive" vs "Welcome to Waggle"; tagline differs); **no privacy note**, **no language selector**,
**no offline/local-only awareness**. It is a pure presentational component (props
`WelcomeStepProps` = `goToStep` + `onClickAnywhere`, `onboarding/types.ts:10-12`).
- `apps/web/src/components/os/overlays/onboarding/WhyWaggleStep.tsx` (step 1, the current 2nd
screen) carries the 3 `VALUE_PROPS` (constants `:111-115`) + the "Skip — quick setup" escape
hatch. Mentioned because the mockup's tagline-style promise overlaps WelcomeStep/WhyWaggle; the
rework should not duplicate value-prop content across both.
- `apps/web/src/components/os/overlays/onboarding/constants.ts` — `VALUE_PROPS` (`:111-115`),
`fadeSlide` motion preset (`:118-123`), `STEP_NAMES`. Reuse `fadeSlide` for the rework.
- `apps/web/src/components/os/overlays/onboarding/types.ts` — `WelcomeStepProps` (`:10-12`).
### Supporting state already present (REUSE)
- `apps/web/src/hooks/useOfflineStatus.ts` — `useOfflineStatus()` returns `offline:boolean`
(`:36-99`, 2-consecutive-failure tolerance). Backs the **offline** state. Already consumed by
`Desktop.tsx:112` and `StatusBar.tsx`; thread it into the welcome step.
- Privacy/local-only copy: **no dedicated component exists**, but the claim is true per PRD §6
("Local-first by default") / §18.1. EraseDataDialog / data-erase surfaces exist elsewhere
(`overlays/EraseDataDialog.tsx`) but there is no reusable "privacy note" primitive — net-new
small UI.
- **No i18n infrastructure** — grep for `i18next | react-i18next | useTranslation |
LanguageSelector | changeLanguage | navigator.language` over `apps/web/src` returns **0 matches**.
All UI copy is hardcoded English. The mockup's `English (US)` selector has **no backing system**.
---
## 4. Frontend work
**Reuse the wizard shell; rework step 0 into a proper First-Launch screen.**
### Components to create / rework
1. **REWORK `WelcomeStep.tsx`** (or rename to `FirstLaunchStep.tsx` keeping the same step-0 slot)
- Align copy to mockup: `Welcome to Waggle` + tagline `Your work. Your memory. Your agents.`
(PRD §24: mockup is directional — keep current eyebrow/brand voice if it reads better, but
the privacy promise + language + Continue affordances are required by blueprint, not optional).
- Add **privacy note** (footer-left): short line ("Your data is private. Stored locally.") with
a "view privacy note" expand (inline `Popover`/`HoverCard` from `components/ui/`, or a small
details disclosure). Maps blueprint interaction "view privacy note" + state "local-only".
- Add **offline awareness**: consume `useOfflineStatus()`; when offline, show a subtle indicator
(reuse the StatusBar offline visual language) and keep Continue enabled (this step is pre-network).
- Add **language affordance** (footer-right): see §9 open question — recommended v1 = a static,
disabled-looking `English (US)` chip (honest: only English ships) OR a minimal selector wired to
a new `OnboardingState.locale` that only persists the choice. Do **not** build full i18n in this
card's scope.
- Keep the existing **Continue** (`goToStep(1)`) + **click-anywhere** + **autoFocus** +
keyboard-reachable button (WelcomeStep already satisfies WCAG 2.1.1/2.2.1 — preserve).
2. **(Optional, recommended) reconsider the 3 s auto-advance** (`OnboardingWizard.tsx:136-141`).
A privacy-reassurance screen that auto-dismisses in 3 s undercuts the "read the privacy note"
intent. Rework: keep auto-advance only when no interaction, or drop it for S12. (Surgical change,
one `useEffect`.)
3. **"Resumed setup" copy hook** — when `state.step > 0` on mount (returning mid-flow), the shell
already restores the step; ensure First Launch isn't re-shown cold. Minimal: the existing
`state.step` restore (`OnboardingWizard.tsx:39`) already handles navigation; add a one-line
"Welcome back — picking up where you left off" variant if `state.step` was persisted > 0. Low
priority; the resume mechanic exists.
### Reuse targets
- Shell: `OnboardingWizard.tsx` (progress bar, dots, Skip, Back, AnimatePresence step swap).
- Motion: `fadeSlide` (`constants.ts:118-123`).
- Offline: `useOfflineStatus()`.
- UI primitives: `components/ui/{button,popover,hover-card,badge}.tsx` (shadcn set already present).
- Brand assets: `assets/waggle-logo.{png,jpeg}` (already imported by WelcomeStep, theme-aware via
`useIsLightTheme`).
### Props / state
- `WelcomeStepProps` (extend): add `offline: boolean` (from `useOfflineStatus`), and — if a
language chip is wired — `locale?: string` + `onLocaleChange?: (l: string) => void`.
- `OnboardingState` (`useOnboarding.ts:10-19`): optionally add `locale?: string` (additive,
localStorage-only, no backend). Resume already covered by existing `step` field.
### Adapter methods / hooks
- **None new required.** This screen is pre-network. `useOfflineStatus` already wraps the health
probe; `adapter.trackTelemetry('onboarding_step', …)` already fires on step change
(`OnboardingWizard.tsx:31-33, :132`). No new adapter method.
---
## 5. Backend work
**This screen needs effectively NO backend.** It is the pre-intent splash; every interaction is
local UI + localStorage. Cross-referenced against backend-routes inventory and backend-map §03c —
nothing on S12 maps to a missing PRD §16 endpoint.
| Capability needed | PRD §16 endpoint | Status | Note / what to EXTEND vs NET-NEW | Substrate / migration |
|---|---|---|---|---|
| Continue / advance step | — (none) | **EXISTS (client-only)** | Step state is `OnboardingState.step` in `localStorage` (`useOnboarding.ts`). No server call. | none |
| Offline / local-only state | — (no PRD §16 row) | **EXISTS** | Reuse `GET /api/offline/status` (`offline.ts`) + the health probe already used by `useOfflineStatus`. No new route. | none |
| Privacy note / local-first claim | — (none) | **EXISTS (static)** | Truthful per PRD §6/§18.1; copy-only. No endpoint. | none |
| Language change | — (none) | **MISSING (no infra)** | No i18n/locale backend anywhere (grep-confirmed). If a real selector is wanted, locale persists client-side in `OnboardingState.locale` (localStorage) — **net-new client field, NOT a server route**. Could later piggy-back on `PUT /api/profile` (`profile.ts`, EXISTS) or `PATCH /api/settings` (`settings.ts`, EXISTS) if locale must sync, but that is out of scope for v1. | none (no `.mind` migration) |
| Returning-user / resume detection | — (none) | **EXISTS** | `useOnboarding` already calls `adapter.getWorkspaces()` (`GET /api/workspaces`, EXISTS) + Tauri first-launch flag to auto-complete returning users. No change. | none |
**No `.mind` migration. No net-new route. No substrate touch.** S12 is the single cleanest screen
in the refactor from a backend standpoint.
---
## 6. Shared types needed (PRD §15 vs lib/types.ts)
- **None of the PRD §15.2 unions are touched by S12** (no WorkspaceType/Scope/MemoryKind/etc. on a
welcome splash).
- The only candidate type change is local: add optional `locale?: string` to `OnboardingState`
(`hooks/useOnboarding.ts:10-19`) **if** the language affordance is wired beyond a static chip.
This is a frontend-only interface field, not a PRD §15 shared type, and needs no `packages/shared`
change.
- `WelcomeStepProps` (`onboarding/types.ts:10-12`) gains `offline` (+ optional locale props). Local
to the onboarding folder.
---
## 7. Dependencies (screens / phases first)
- **Phase placement:** PRD Sprint 5 / Release Phase 2 ("Onboarding flow: Welcome, Profile, Tool
Discovery, Memory Import, Memory Review"). S12 is the **entry** of that sequence.
- **Hard dependency:** the wizard shell (`OnboardingWizard.tsx`) must remain the host — already
exists, so no blocker. S12 can be reworked independently of the later steps.
- **Sibling screens that share the shell** (do these in the same sprint to keep the rework
coherent): S13 Who Are You, S14 Tool Discovery, S15 Memory Import, S16 Memory Review, S17 Create
Workspace. S12 should land first because it sets the privacy/local-first framing the rest rely on.
- **No dependency on Home Cockpit / Workspace Desktop / Command Center backend work** — S12 is
pre-workspace and pre-network.
- **Decision dependency:** the language-selector scope question (§9) should be answered before
implementation so the footer affordance isn't built twice.
---
## 8. Effort
**S** — Single presentational component rework inside an existing, working shell; reuse
`useOfflineStatus` + existing motion/UI primitives; **zero backend, zero migration, zero shared-type
churn**. The only thing that could push it toward **M** is electing to build a real (even minimal)
language selector + `locale` plumbing instead of a static `English (US)` chip.
---
## 9. Open questions
1. **Language selector — real or honest-stub?** No i18n exists (grep-confirmed: 0 matches for
i18next/useTranslation/etc.). Options: (a) static disabled `English (US)` chip (truthful, S
effort, recommended v1); (b) minimal selector that persists `OnboardingState.locale` but only
English is wired (cosmetic); (c) defer the affordance entirely. PRD §24 lets us treat the mockup
as directional, and PRD §4.4 lists native/i18n work as out-of-first-phase scope — so (a) or (c)
align with the PRD. **Recommend (a).** Confirm before building.
2. **Keep the 3 s auto-advance on a privacy screen?** Current step-0 auto-advances after 3 s
(`OnboardingWizard.tsx:136-141`), which fights the "read the privacy note" intent. Drop it for
S12, or keep-but-pause-on-interaction?
3. **Copy alignment:** mockup says "Welcome to Waggle" / "Your work. Your memory. Your agents.";
current ships "Welcome to the Hive" / "Persistent memory. Workspace-native…". Which brand voice
wins? (PRD §24: pixels don't, but the privacy promise must be present either way.)
4. **"Resumed setup" UX:** the step is restored from `localStorage` already — is a distinct
"welcome back" treatment on First Launch wanted, or is silent step-restore sufficient?
5. **Privacy note content:** inline expandable text vs link to a privacy doc/URL? No privacy-policy
route or doc is wired today — needs copy + destination decided.

231
docs/ux-refactor/gap-cards/S13-who-are-you.md Normal file
View File

@@ -0,0 +1,231 @@
# Gap Card — S13 · Who Are You (Onboarding Profile)
> UX-refactor planning artifact. Execution model is **in-place incremental refactor** of `apps/web` +
> targeted backend extension. Every claim below is grounded in a real file. PRD = source of truth;
> mockup is directional (PRD §24). Screen index: **Onboarding Flow PRD §12.12 step 2** ("Who Are You").
---
## 1. Screen & purpose
The second onboarding step: capture the user's professional context so Waggle can personalize and
recommend. Per PRD §12.12 and the blueprint screen-spec table (PAGE 14, row 13): "Capture role,
industry, work type, team size and goals." Blueprint acceptance: **"Profile drives recommendations
but can be edited later."** Blueprint states: `Empty; partially complete; validation; saved`.
The mockup (`screen_13_who_are_you.png`) shows a single-step form inside the onboarding shell:
left rail step list (Welcome / Who are you / Tool discovery / Memory import / Review & confirm) + a
"Your data is private" reassurance card; center form with **Name, Role, Industry, Work type, Team
size, and a "What are your goals with Waggle?" multi-select chip group** (Build a second brain /
Improve team productivity / Automate recurring work / Make better decisions / Scale the business) +
free-text "Add other goal"; a right-hand live **"Your profile" preview panel** that mirrors the form
as the user types; Back / Continue footer. Mockup is directional — PRD/blueprint acceptance wins.
This profile drives downstream screens: Tool Discovery (S14) recommendations, Memory Import (S15)
source suggestions, Workspace Creation (S17) template/persona pre-fill, and the Home Cockpit greeting.
---
## 2. Required states (PRD/Blueprint)
From the blueprint screen-spec (PAGE 14, row 13) + PRD §14.1 global-state mandate:
- **Empty** — fresh form, nothing entered.
- **Partially complete** — some fields filled (Continue still allowed; profile is editable later).
- **Validation** — surface invalid/missing required input (blueprint lists "validation" as a state;
PRD acceptance says it must not block — soft validation, not a hard gate).
- **Saved** — profile persisted; advance to Tool Discovery.
- **Loading** (PRD §14.1) — restoring a resumed/partial profile on re-entry.
- **Offline / local-only** (PRD §14.1, §6.7) — sidecar unreachable; the step must still let the user
type and continue (write deferred / retried), mirroring the wizard's existing
"created locally, sync later" fallback (`OnboardingWizard.tsx:286-288`).
PRD §12.12 acceptance criteria that bind this screen: "Onboarding asks user questions, not
infrastructure questions"; "Profile drives recommendations." PRD §7.1 activation metric: "% of new
users who complete onboarding."
---
## 3. Current state in repo — disposition: **partial** (rework + create-new)
There is **no onboarding "Who Are You" profile step today.** The profile-capture *capability* exists
post-onboarding as a separate app, and the onboarding wizard does NOT collect it. Two surfaces are
relevant; both partially overlap the requirement:
**(a) `OnboardingWizard.tsx`** (`apps/web/src/components/os/overlays/OnboardingWizard.tsx`) — the
first-launch wizard. Its actual step order (`STEP_NAMES`, line 35) is:
`welcome → why-waggle → tier → memory-import → template → persona → api-key → ready` (8 steps,
0-indexed; rendered via the `step===N` switch at lines 499-571). **There is no profile/identity-capture
step at all.** Steps map to `onboarding/` components: `WelcomeStep, WhyWaggleStep, TierStep, ImportStep,
TemplateStep, PersonaStep, ModelTierStep, ReadyStep` (`onboarding/index.ts`). The wizard's data model
(`OnboardingState` in `hooks/useOnboarding.ts`) tracks `step/tier/templateId/personaId/workspaceId/
apiKeySet` — **no profile fields.** Disposition for the wizard: **rework** — insert a new profile step
and a `WhoAreYouStep` component; widen `OnboardingState` minimally (or post directly to `/api/profile`).
> Note: the wizard's IA (tier picker, API-key step, model-tier step) is the OLD onboarding, not the
> PRD §12.12 flow (Welcome → Who Are You → Tool Discovery → Memory Import → Memory Review → Workspace
> Creation → Home). PRD §20.2 explicitly lists "Onboarding wizard → simplify to user-oriented 5-step
> setup plus workspace creation." S13 is one slice of that larger onboarding rework; this card scopes
> only the profile step, but the planner must sequence it inside the onboarding-IA rework (see §7).
**(b) `UserProfileApp.tsx`** (`apps/web/src/components/os/apps/UserProfileApp.tsx`, 533 LOC) — the
post-onboarding "My Profile" app (dock id `profile`). A 4-tab surface: **Identity** (Name/Role/Company/
Industry/Bio + "Research Me" + harvest-suggestion accept/dismiss banner, lines 242-343), Writing Style,
Brand & Templates, Interests (interests chips + language, lines 483-520). Its Identity tab already
renders the heading "**Who Are You?**" (line 245) and captures Name/Role/Company/Industry/Bio via
`adapter.getProfile()` / `adapter.updateProfile()` (lines 86-102, 120-133). This is the **reuse target**
for the form fields, validation pattern, and adapter wiring — but it is NOT an onboarding step, it has
NO Work type / Team size / Goals, and it has NO live preview panel. Disposition: **keep-promote** the
field/adapter patterns; extract a shared profile-form so the onboarding step and the app don't diverge.
**Net:** the requirement is **partial** — backend persistence (`/api/profile`) + a structurally similar
form (UserProfileApp Identity tab) exist, but the *onboarding step itself*, the *3 new fields*
(work type / team size / goals), and the *live preview panel* are net-new frontend.
---
## 4. Frontend work
**Create:**
- `apps/web/src/components/os/overlays/onboarding/WhoAreYouStep.tsx` — the new step component
(matches the `*Step.tsx` sibling convention; default-exported from `onboarding/index.ts`). Renders:
Name (text), Role (text), Industry (`<select>` reusing `UserProfileApp.tsx:37-41` `INDUSTRIES`),
**Work type** (select/segmented — e.g. Strategy & Operations / Engineering / Sales / Marketing /
Research / Other), **Team size** (select — Just me / 2-10 / 11-50 / 50+), **Goals** (multi-select
chip group, reusing the chip-toggle pattern from `UserProfileApp.tsx:488-498` interests), free-text
"other goal", and the **live "Your profile" preview panel** (right column; pure derived view of
current form state). Props: `{ profile, onChange, onContinue, onBack, saving }`. Local form state
mirrored to a single `Partial<UserProfile>` object (immutable updates per repo coding-style).
- `apps/web/src/lib/onboarding-profile.ts` (optional helper) — the goal/work-type/team-size option
constants + a `buildProfilePreview()` pure function (testable, co-located `.test.ts`), keeping the
step component thin (CLAUDE.md §3.2, file-org rules).
**Rework:**
- `OnboardingWizard.tsx` — insert the new step into the flow after `WelcomeStep` per PRD §12.12 order.
Touches: `STEP_NAMES` (line 35), the step switch (lines 499-571), step-index math (`progressPct`
line 396, dots lines 472), and a `handleProfileSave` that calls `adapter.updateProfile(...)` (same
call UserProfileApp uses, `UserProfileApp.tsx:123-128`). Keep the existing offline "created locally"
fallback semantics (lines 286-288) for the profile write. NOTE: the current wizard IA (tier/api-key/
model steps) is being reworked to the PRD §12.12 5-step flow in a sibling card — coordinate the
step-index churn with that card to avoid double-editing the switch.
- `UserProfileApp.tsx` Identity tab — **optional consolidation**: extract the shared field set into the
new `onboarding-profile.ts` form so onboarding and the app render the same Name/Role/Industry/Goals
controls (avoids the documented "two parallel systems" anti-pattern,
`feedback_grep_capability_not_feature_name.md`). At minimum, add the 3 new fields here too so a user
can edit Work type / Team size / Goals after onboarding (blueprint: "can be edited later").
**Reuse targets (do not recreate):**
- `INDUSTRIES` + `INTEREST_OPTIONS` chip-toggle pattern — `UserProfileApp.tsx:31-41, 488-498`.
- `adapter.getProfile()` / `adapter.updateProfile()` — `lib/adapter.ts` (profile method block;
inventory `frontend.md:232`). Already typed and used.
- `@/components/ui/{input,select-ish}` shadcn primitives (`components/ui/*`, inventory §(e)).
- Onboarding shell chrome (progress bar, Back/Skip, step dots) — already in `OnboardingWizard.tsx`.
**Adapter methods/hooks:** no NEW adapter method needed for the happy path —
`adapter.updateProfile(partial)` (PUT `/api/profile`, partial-merge) already accepts arbitrary profile
fields and the backend persists unknown-to-old-UI fields once the route is widened (see §5). The
profile is read via `adapter.getProfile()`. No new hook required; step holds local state and posts on
Continue.
---
## 5. Backend work
PRD §16 has **no dedicated onboarding-profile endpoints** — the profile domain is served by the
existing `/api/profile*` routes (`packages/server/src/local/routes/profile.ts`), which are NOT in the
PRD §16 list but already exist and are the correct substrate. So there is nothing "MISSING" in PRD §16
terms; the work is **EXTEND** of an existing route, not net-new routing.
| Capability | Status | Route to EXTEND vs NET-NEW · substrate |
|---|---|---|
| Read profile for the step | **EXISTS** | `GET /api/profile` (`profile.ts:162-164`) returns the full `UserProfile` (defaults-merged). Reusable as-is. |
| Persist profile from the step | **PARTIAL → EXTEND** | `PUT /api/profile` (`profile.ts:167-228`) partial-merges, but its allow-list of merged fields (lines 172-196) does **not** include the 3 new fields (`workType`, `teamSize`, `goals`). EXTEND the merge block + the `UserProfile` interface (`profile.ts:41-94`) + `DEFAULT_PROFILE` (`:96-135`) to carry them. Substrate: `profile.json` under `dataDir` (NOT SQLite) — **no DB migration.** |
| Mirror identity → memory | **EXISTS (reuse)** | `PUT /api/profile` already writes a `User identity:` P/I frame to personal memory on save (`profile.ts:201-224`). Optionally append role/industry/goals to that string so the agent picks up the new context — pure edit, no schema change. |
**Net-new fields (frontend + backend, additive):** `workType?: string`, `teamSize?: string`,
`goals?: string[]`. All three are pure additive optional fields on the JSON-file `UserProfile` shape.
The mockup's Industry/Name/Role already map 1:1 to existing fields.
**Substrate touched:** `profile.json` (file store, `getProfilePath()` `profile.ts:137-139`) and
(reused) personal `.mind` `memory_frames` via the existing identity-mirror path.
**.mind migration:** **NONE.** Profile lives in `profile.json`, not SQLite (`profile.ts:152-156`).
The identity-mirror writes frames through the existing append-only API — no schema change.
> Optional alignment (flag, not required for S13): a parallel structured identity record exists at
> `POST /api/identity` → `identity` table (`identity.ts:104-156`, fields name/role/department/
> personality/capabilities/system_prompt). The onboarding step writes to `/api/profile` (the richer,
> file-backed shape the UI already uses), NOT `/api/identity`. The planner should decide whether
> onboarding should ALSO seed `/api/identity` (it backs `adapter.getIdentity()` / the Home greeting
> name) or leave that to the existing profile→frame mirror. Out of S13 scope but worth a one-line
> decision to avoid two divergent identity stores.
---
## 6. Shared types needed (PRD §15 vs `lib/types.ts`)
PRD §15.2 defines no profile/onboarding union (its unions are Workspace/Memory/Artifact/Agent-centric),
so there is no PRD §15 type to satisfy here. The relevant types are:
- **Frontend:** `apps/web/src/lib/types.ts` has **no `UserProfile` type** (the shape is declared
inline inside `UserProfileApp.tsx:45-52` and re-declared loosely in the new step). Recommend promoting
a shared `UserProfile` (with the 3 new fields) to `lib/types.ts` so the onboarding step, the app, and
the adapter return type share one contract (avoids the FE/BE drift the substrate inventory flags for
other entities). Low-cost, additive.
- **Backend:** `UserProfile` + `IdentitySuggestion` interfaces are exported from `profile.ts:31-94`.
Extend in place with the 3 new fields. (They are not in `packages/shared` today; keeping them in
`profile.ts` + mirroring an FE type is consistent with current layout.)
- New small unions for the option sets (`WorkType`, `TeamSize`, goal ids) can live in
`onboarding-profile.ts` as string-literal unions (repo coding-style prefers literal unions over enum).
---
## 7. Dependencies (screens / phases first)
- **Phase 2 (PRD §8)** — Onboarding flow is Phase 2 / Sprint 5 ("Who Are You" listed explicitly,
PRD §21 Sprint 5 + §8 Phase 2).
- **Onboarding-IA rework first.** S13 is one step inside the PRD §12.12 flow (Welcome → **Who Are You**
→ Tool Discovery → Memory Import → Memory Review → Workspace Creation → Home). The current wizard's
step order/IA differs from PRD §12.12; the step-index/switch churn in `OnboardingWizard.tsx` must be
coordinated with the sibling onboarding cards (S12 First Launch, S14 Tool Discovery, S15 Memory
Import, S16 Memory Review, S17 Workspace Creation) so the switch is rewired once, not per-card.
- **Downstream consumers of this profile:** S14 Tool Discovery (recommendations from work type/role —
PRD §12.12 acceptance "recommended from user selections"), S15 Memory Import (source suggestions),
S17 Workspace Creation (template/persona pre-fill), Home Cockpit greeting (name). S13 should land
before or with S14 since S14 consumes its output.
- **No backend prerequisite** — `/api/profile` GET/PUT already exist; the field extension is
self-contained and can ship independently of the Home/Workspace/Memory backend work.
---
## 8. Effort: **M**
One net-new step component + a live-preview panel + a thin backend field extension (3 additive JSON
fields, no migration) + onboarding wizard step insertion. The form fields, validation pattern, chip
toggles, and adapter wiring already exist in `UserProfileApp.tsx` to copy from, which keeps it out of
L. The "M" (not S) reflects: the live-preview panel is new UI, the wizard step-index/switch rewire is
fiddly and must be coordinated with the broader onboarding-IA rework, and a shared `UserProfile` type +
optional UserProfileApp consolidation add surface.
---
## 9. Open questions
1. **Identity store of record:** does onboarding write profile via `/api/profile` only (current UI
path), or ALSO seed `/api/identity` (the `identity` table that backs the Home greeting name /
`adapter.getIdentity()`)? Two identity stores exist; pick one to avoid drift. (§5 note.)
2. **Goal taxonomy:** are the 5 mockup goals (second brain / team productivity / automate recurring
work / better decisions / scale business) the canonical set, or directional? They likely feed S14
tool/connector recommendations — confirm the mapping owner.
3. **Work type vs Industry vs Persona/Template:** the existing onboarding already picks a template
(`TEMPLATE_PERSONA`, `constants.ts:28-44`) which implies a work domain. Does "Work type" duplicate
that signal, or is it a distinct axis used only for personalization? Resolve to avoid asking the
user the same thing twice (PRD §12.12: "asks user questions, not infrastructure").
4. **Validation hardness:** blueprint lists a "validation" state but PRD says profile is editable
later. Confirm Continue is never hard-blocked (soft-validate only) — assumed soft per PRD acceptance.
5. **Required vs optional fields:** which of Name/Role/Industry/Work type/Team size/Goals (if any) are
required to proceed? Assumed all optional (partial-complete is an allowed state).
6. **Pre-fill from harvest:** UserProfileApp already accepts harvest-extracted `identitySuggestions`
(`profile.ts:31-39`, `UserProfileApp.tsx:252-298`). Should the onboarding step pre-fill from those
if Memory Import (S15) ran first? In PRD §12.12 order, import comes AFTER Who Are You — so likely no
on first pass, but confirm whether a returning/resumed user sees suggestions here.

250
docs/ux-refactor/gap-cards/S14-tool-discovery.md Normal file
View File

@@ -0,0 +1,250 @@
# Gap Card — S14 Tool Discovery
> Screen 14 of the Waggle OS UX-refactor. Onboarding step 3 of 7 (PRD §12.12).
> Execution model: **in-place incremental refactor** of `apps/web` + targeted backend
> extension. Every claim below is grounded in repo source (paths cited).
> PRD = `docs/Waggle_OS_UX_Refactor_Master_Handoff_Package/Waggle_OS_UX_Refactor_PRD.md`.
---
## 1. Screen & purpose
"What tools do you use?" — the third onboarding step. The user selects the tools they
already use day-to-day (in plain product language, **not** an infra/connector setup
screen) so Waggle can recommend the right connectors, MCPs and skills downstream and
seed the Memory Import step (S15).
- **PRD §12.12** (step 3 of the 7-step onboarding flow): "Tool Discovery — ask which
tools are used." Acceptance: "Onboarding asks user questions, not infrastructure
questions"; "Connectors/MCPs/skills are **recommended from user selections**."
- **Blueprint** (`_blueprint_extracted.txt`):
- Screen index row 14 (`:381-384`): *"Ask what tools the user uses. Select tools, add
other, continue/back. States: No selection; selected; recommended; unsupported tool.
User-oriented language, not infra setup."*
- Mental model (`:54`): *"Tool discovery and harvest are core onboarding steps."*
- Journeys J01 (`:169`) and J02 (`:173`): Tool Discovery sits between *Who Are You*
(S13) and *Memory Import* (S15) on both the import and skip-import paths.
- **Mockup** (`screen_14_tool_discovery.png`, directional): two-column layout —
left = grouped selectable tool grid in **"Collaboration & Productivity"** (Gmail,
Calendar, Slack, GitHub, Notion, Jira, Salesforce) and **"AI & Developer Tools"**
(Claude, Claude Code, Cursor, Hermes, Codex, "Other tool"), each card with a
checkbox + "Select all" per group; right rail = **"You selected"** chip list +
**"What's next"** ("We'll suggest relevant connectors and MCPs", "Your data is
private"); left rail = the 7-step onboarding progress rail with "Tool discovery"
active; footer = Back / Continue.
---
## 2. Required states (PRD / Blueprint)
Blueprint S14 enumerates four states; the mockup adds layout affordances:
1. **No selection** — nothing chosen; "You selected" empty; Continue still allowed
(tool discovery is non-blocking, consistent with J02 skip-import).
2. **Selected** — one or more tools toggled; reflected in the "You selected" chip rail.
3. **Recommended** — "What's next" surfaces connectors/MCPs/skills derived from the
selections (PRD acceptance: recommendations come *from user selections*). This is a
silent default-ordering surface, not a friction step (per the project rule
`feedback_silent_recommendations_dont_ask.md`).
4. **Unsupported tool** — user adds a tool ("Other tool" / free-text) that Waggle has
no native connector for; captured as a profile signal, surfaced as "we'll watch for
this / available via MCP," never a hard error.
5. Plus: **Select-all per group**, **Back/Continue** nav, and per-group sections
("Collaboration & Productivity" vs "AI & Developer Tools").
Acceptance (PRD §12.12): user-oriented language; selections drive recommendations;
**nothing imports here** (import/consent is S15's job — this screen only records intent).
---
## 3. Current state in repo
**Disposition: `create-new`** (the step does not exist; substrate to feed it largely does).
### The onboarding wizard has NO Tool Discovery step today
`apps/web/src/components/os/overlays/OnboardingWizard.tsx` is an **8-step** wizard whose
`STEP_NAMES` (`:35`) are: `welcome, why-waggle, tier, memory-import, template, persona,
api-key, ready`. The step switch (`:498-572`) renders `WelcomeStep / WhyWaggleStep /
TierStep / ImportStep / TemplateStep / PersonaStep / ModelTierStep / ReadyStep`. **There
is no "what tools do you use?" step** anywhere in the flow. Step components live in
`apps/web/src/components/os/overlays/onboarding/` (`WelcomeStep, WhyWaggleStep, TierStep,
ImportStep, TemplateStep, PersonaStep, ModelTierStep, ReadyStep, constants.ts, types.ts,
index.ts`) — none is a tool picker.
> Note: the live wizard's step ordering (tier/template/persona/api-key) does **not** match
> the PRD's 7-step IA (Welcome → Who Are You → Tool Discovery → Memory Import → Memory
> Review → Workspace Creation → Home Cockpit). The refactor inserts Tool Discovery; the
> broader re-sequencing is a cross-screen concern (see §7).
### `OnboardingState` cannot persist a tool selection
`apps/web/src/hooks/useOnboarding.ts:10-19` — `OnboardingState` = `{ completed, step,
tier?, workspaceId?, apiKeySet?, templateId?, personaId?, tooltipsDismissed? }`. **No
`toolsUsed` / `selectedTools` field.** Persisted to `localStorage` key `waggle:onboarding`.
### Two SEPARATE substrates map to the mockup's two columns — neither is a "what tools do you use" survey
1. **SaaS / productivity column** → native **connector registry**.
`packages/agent/src/connector-registry.ts` `getDefinitions()` (`:59`) returns
`ConnectorDefinition[]` with live vault status. ~31 connectors are registered
(`packages/agent/src/connectors/index.ts`): GitHub, Slack, Jira, Gmail, Google
Calendar, Notion, Salesforce, HubSpot, Linear, Asana, Trello, Monday, Confluence,
Discord, Dropbox, etc. — a direct match for the mockup's Gmail/Calendar/Slack/GitHub/
Notion/Jira/Salesforce cards. `ConnectorDefinition` (`packages/shared/src/types.ts:276-302`)
already carries `id, name, displayName(via name), description, category` (`'productivity'
| 'development' | 'crm' | 'data' | 'communication' | 'storage' | 'integration'`),
`status`, `logoUrl`, `setupGuide` — exactly the fields a grouped, iconed tool grid needs.
Surfaced over HTTP at `GET /api/connectors` (`packages/server/src/local/routes/connectors.ts:6`).
2. **AI & Developer column** → **AI-OS tool detection** (DIFFERENT subsystem).
`packages/agent/src/tool-detection.ts` + `packages/shared/src/tool-detection.ts`:
`SUPPORTED_TOOLS` (`:23-31`) = `claude-code, claude-desktop, cursor, codex,
codex-desktop, hermes, openclaw`; `TOOL_DISPLAY_NAMES` (`:58`). Surfaced at
`GET /api/tools/detect` (`packages/server/src/local/routes/tools.ts`). This *detects
what is installed on the machine*; the mockup's AI/Developer column ("Claude, Claude
Code, Cursor, Hermes, Codex") aligns with this set but as a **self-report picker**, not
an install scan. The two can be merged: pre-check tools `tool-detection` already found.
### Recommendation engine — partial precedent, no connector recommender yet
`apps/web/src/lib/skill-recommendations.ts` is the existing template for "silent default
ordering from a user signal" (persona → 3-5 starter skills, `recommendSkills()` `:103`).
**There is no `connector-recommendations.ts`** (grep: only a *comment* in
skill-recommendations references the pattern; no file). The "What's next" rail needs a
new tool→connector/MCP/skill mapper following this same shape. `GET /api/skills/suggestions`
exists (`skills.ts`) but is context-driven, not tool-selection-driven.
**Reuse-not-rebuild verdict:** the *data* for both columns exists (`/api/connectors` +
`/api/tools/detect`); the *step UI*, the *state field*, and the *recommendation mapper*
are net-new. No new data store.
---
## 4. Frontend work
### Components to CREATE
| Component | Location | Role |
|---|---|---|
| `ToolDiscoveryStep.tsx` | `apps/web/src/components/os/overlays/onboarding/` | The step shell: grouped tool grid + "You selected" rail + "What's next" rail + Back/Continue. Mirrors the `*Step.tsx` prop contract (`goToStep`, controlled selection props). |
| `ToolGroup.tsx` (or inline) | same dir | One titled group ("Collaboration & Productivity" / "AI & Developer Tools") with a Select-all toggle and a grid of `ToolCard`s. |
| `ToolCard.tsx` | same dir | Single selectable tool tile (icon/logo + label + checkbox + selected ring). Reuse `components/ui/checkbox` + `card` + existing `connectors/BrandTile.tsx` icon pattern. |
### Reuse targets
- `components/os/apps/connectors/BrandTile.tsx` — already renders a branded connector
tile with logo; lift its icon/logo resolution into `ToolCard`.
- `components/ui/*` (`card`, `checkbox`, `badge`, `button`, `separator`) — DS primitives.
- `lib/skill-recommendations.ts` shape — model `connector-recommendations.ts` on it.
- Onboarding chrome (progress rail, Back/Continue/Skip) already exists in
`OnboardingWizard.tsx` (`:438-493`) — the step plugs into the existing AnimatePresence
switch; no new chrome.
### New lib helper
- `apps/web/src/lib/tool-recommendations.ts` — pure mapper
`recommendFromTools(selectedToolIds: string[]) => { connectors: string[]; mcps: string[];
skills: string[] }`, with a co-located `.test.ts` (matches `skill-recommendations.test.ts`).
Feeds the "What's next" rail. Tool ids reconciled across connector ids and `ToolId`.
### Wizard wiring (edits to existing files)
- `OnboardingWizard.tsx`: insert the step into `STEP_NAMES` (`:35`) and the step switch
(`:498-572`); thread `selectedTools` step-local state + `onUpdate({ toolsUsed })`; bump
the progress denominator (currently hard-coded `/7` `:396`, dots `[1..6]` `:472`,
`aria-valuemax={7}` `:426`) — these counts become inconsistent once a step is added and
the PRD re-sequence lands, so treat the step-count constants as a single thing to fix.
- `useOnboarding.ts`: add optional `toolsUsed?: string[]` (and optionally
`unsupportedTools?: string[]`) to `OnboardingState` (`:10-19`); additive, no migration
(localStorage).
### Data hooks
- Connector column: `adapter.getConnectors()` (`GET /api/connectors`) — already on the
adapter (`lib/adapter.ts`). No new hook strictly needed; a thin `useConnectors`-style
fetch in the step is fine, or reuse `ConnectorsApp`'s fetch pattern.
- AI/Dev column: `adapter.detectTools()` (`GET /api/tools/detect`) — already on the
adapter — to PRE-CHECK locally-installed AI tools.
---
## 5. Backend work (PRD §16 cross-reference)
S14 has **no dedicated PRD §16 endpoint** — it is an onboarding capture screen that reads
existing catalogs and writes the selection into onboarding/profile state. Required backend:
| Need | Status | Existing route/builder to EXTEND vs NET-NEW | Substrate |
|---|---|---|---|
| List SaaS/productivity tools (grid) | **EXISTS** | `GET /api/connectors` (`connectors.ts:6` → `connectorRegistry.getDefinitions()`). Already returns `category` + `logoUrl` for grouping/icons. No change. | connector registry (in-memory defs + vault status) |
| List AI/developer tools (+ pre-check installed) | **EXISTS** | `GET /api/tools/detect` (`tools.ts`, AI-OS). Returns per-tool `installed`. No change. | `tool-detection.ts` (FS/PATH probes) |
| Recommend connectors/MCPs/skills from selection ("What's next") | **PARTIAL** | Closest is `GET /api/skills/suggestions` (`skills.ts`, context-driven, wrong input). Recommended approach: do the mapping **client-side** in `lib/tool-recommendations.ts` (pure, testable, no round-trip) — no new endpoint. If server-side later: NET-NEW thin `GET /api/recommendations?tools=` over connector catalog + `mcp-catalog.ts` + starter-skills. | connector defs + `@waggle/shared` `mcp-catalog.ts` + starter skills |
| Persist the tool selection | **PARTIAL** | Two options: (a) **client-only** in `localStorage` via `OnboardingState.toolsUsed` (lowest risk, matches current onboarding persistence) — **recommended**; (b) write into the user profile via existing `PUT /api/profile` (`profile.ts:218`, partial-merge) so recommendations survive re-onboarding and feed S15. Prefer (a) for the step; optionally also (b) to thread selections into Memory Import. | `localStorage` and/or `profile` store |
**No net-new sidecar route is strictly required** for S14 itself, and **no `.mind`
migration** — both source catalogs already have HTTP routes, and the selection is small
UI state. (Contrast: S15 Memory Import and the Home/Artifacts screens DO need net-new
routes; S14 is the cheap one.)
> Adjacent (not S14-blocking): if the team later wants the "unsupported tool" free-text to
> become a real demand signal, the cheapest home is `PUT /api/profile` `unsupportedTools[]`
> — no new substrate.
---
## 6. Shared types needed (PRD §15 vs `lib/types.ts`)
- **`OnboardingState.toolsUsed?: string[]`** (+ optional `unsupportedTools?: string[]`) —
add to `apps/web/src/hooks/useOnboarding.ts:10-19`. Additive, optional.
- **`ToolRecommendation`** interface in the new `lib/tool-recommendations.ts` (mirrors
`SkillRecommendation` in `skill-recommendations.ts:20-27`).
- **Reuse, do not redefine:** `ConnectorDefinition` (`packages/shared/src/types.ts:276-302`)
for the SaaS column; `ToolId` / `DetectedTool` / `TOOL_DISPLAY_NAMES`
(`packages/shared/src/tool-detection.ts`) for the AI/Dev column.
- **PRD §15 note:** S14 does **not** introduce any of the missing §15.2 unions
(`WorkspaceType`, `Scope`, `MemoryKind`, `ArtifactKind`, …). It only needs the additive
onboarding field above, so it is **not** gated on the §15 type-alignment work that other
screens (Memory, Artifacts, Agents) require.
---
## 7. Dependencies (screens / phases first)
- **Onboarding re-sequence (cross-screen):** the live wizard order (tier/template/persona/
api-key) differs from the PRD 7-step IA. S14 slots between **S13 Who Are You** and
**S15 Memory Import** (J01/J02). Coordinate step insertion + progress-count fix once,
alongside the other onboarding screens (S12 First Launch, S13, S15, S16, S17) rather than
in isolation — they all touch `OnboardingWizard.tsx` + `useOnboarding.ts`.
- **Feeds S15 Memory Import:** selected tools should bias which import sources/connectors
S15 surfaces (PRD: recommendations from selections). S14 must land before/with S15.
- **Feeds Extend / Marketplace (S/connectors):** "What's next" recommendations point at
the same connector/MCP catalog those screens own.
- **No backend dependency** — `/api/connectors` and `/api/tools/detect` already exist, so
S14 frontend is **not blocked on any backend phase**.
- **Soft dependency:** `lib/tool-recommendations.ts` reuses the `skill-recommendations.ts`
pattern (already shipped).
---
## 8. Effort: **M**
Net-new step component + group/card subcomponents + a pure recommendation mapper + one
additive `OnboardingState` field + wizard-switch/progress-count wiring. **Zero net-new
backend routes and zero `.mind` migration** (both catalogs already have HTTP routes), which
keeps it out of L/XL. Larger than S (real new UI surface, two data sources to merge and
de-dupe, recommendation logic with tests, and the progress-count/step-sequence cleanup that
ripples through the wizard).
---
## 9. Open questions
1. **Catalog scope for the grid.** Mockup shows ~7 SaaS + ~5 AI tools, but the registry
has ~31 connectors. Show a **curated subset** (most common, matching the mockup) with a
"more" affordance, or the full grouped catalog? PRD says "user-oriented, not infra" →
leans curated. Needs a product call on the curated list.
2. **Two columns, two id-spaces.** SaaS column uses connector `id`s; AI/Dev column uses
`ToolId`. The "You selected" rail and `toolsUsed[]` need a unified id scheme (namespaced
e.g. `connector:gmail` / `tool:cursor`) so the recommender and S15 can disambiguate.
3. **Pre-check installed AI tools?** Should `GET /api/tools/detect` results pre-select the
AI/Dev cards (lower friction, "we already see Cursor") or stay unchecked until the user
opts in? J01 implies a populated, trusted start; lean pre-check + visible "detected" badge.
4. **Where do selections live long-term?** `localStorage` only (simplest), or also
`PUT /api/profile` so recommendations persist and feed Home/Extend after onboarding?
Profile-write is cheap and reusable but adds a server round-trip to the step.
5. **Recommendation placement: client vs server.** Recommend client-side
(`lib/tool-recommendations.ts`, pure + testable, no round-trip) per §5 — confirm the team
is fine deferring a `GET /api/recommendations` endpoint until a server-side consumer needs it.
6. **"Unsupported tool" handling.** Captured as a profile/demand signal only, or also
surfaced as "available via MCP" with a marketplace deep-link? Affects whether the free-text
needs any backend at all (recommend: capture-only for v1).

144
docs/ux-refactor/gap-cards/S15-memory-import.md Normal file
View File

@@ -0,0 +1,144 @@
# Gap Card — S15 Memory Import
> UX-refactor planning artifact. Execution model is **in-place incremental refactor** of `apps/web`
> + targeted backend extensions. Every claim is grounded in a real file (cited inline).
> Mockup is **directional** (PRD §24) — PRD acceptance criteria win over pixels.
---
## 1. Screen & purpose
**S15 = the Memory Import step of onboarding** (PRD §12.12 step 4; Blueprint screen 15, `_blueprint_extracted.txt:727`). It is the "Capture" surface where a new user connects/imports their existing AI history (Claude, Claude Code, Cursor, Hermes, Codex, ChatGPT, Gemini, Perplexity…) and work tools (Files, Notion, Google Drive, Slack) so Waggle's persistent memory starts non-empty.
PRD anchors:
- §12.12 step 4 "Memory Import — connect/import from AI tools, files, and work tools" (PRD:637).
- §16.5 Harvest API: `POST /api/harvest/preview`, `POST /api/harvest/commit`, `GET /api/harvest/sources`, `POST /api/harvest/sources/:id/sync` (PRD:1098-1101).
- Privacy gate: "No memory import without review/approval" (PRD:1207) and "Nothing imports without explicit review/approval" (PRD:646). **S15 produces the preview; the approval/commit decision is S16 Memory Review** (`_blueprint_extracted.txt:731`).
Mockup `screen_15_memory_import.png` (directional) shows a 3-region layout:
- **Left rail** — onboarding step list (Welcome / Why us / Tool discovery / Import memory [active] / Review & confirm) + a "Your data is private" footer card.
- **Center** — "Import your memory" with two grids: **AI Assistants & Coding Tools** (Claude, Claude Code, Cursor, Hermes, Codex, Other AI Tools — each a **Connect** action) and **Files & Workspace Tools** (Files, Notion, Google Drive, Slack — **Connect** actions). A primary **Continue** button bottom-right.
- **Right rail** — "What we import" (Conversations / Documents / Decisions / Artifacts / Code) and "You're in control" (review-before-import, never-shared, disconnect-anytime).
> Note the mockup is **Connect-centric** (OAuth/connector tiles) whereas the live onboarding step is **upload-centric** (file pickers). This is the core directional gap (see §2/§3).
---
## 2. Required states (PRD/Blueprint)
PRD §14.1 global states apply (Loading / Empty / Populated / Error / Offline-local-only / Syncing / Permission-denied / Partial / Approval-required). Concretely for S15:
| State | Trigger | Source of truth |
|---|---|---|
| Idle / source grid | step entered, no source picked | mockup center grids |
| Source auto-detected | sidecar finds local Claude Code at `~/.claude` | `POST /api/harvest/scan-claude-code` → `{found,itemCount,path}` |
| Preview / parsed | file uploaded or source connected; items parsed | `POST /api/harvest/preview` → `{itemCount, types, preview[]}` |
| Importing (live progress) | commit running | SSE `GET /api/harvest/progress` `{phase∈saving\|cognifying\|wiki-compile, current, total}` |
| Imported / done | commit returned | `POST /api/harvest/commit` `{saved, cognified, wikiCompiled, ...}` |
| No real embedder (degraded) | commit returns `cognifySkippedReason\|wikiSkippedReason = 'no_real_embedder'` | harvest commit response (05c §8) |
| Resume available | prior run interrupted | `GET /api/harvest/runs/latest-interrupted` |
| Connector consent / OAuth | "Connect" on Notion/Drive/Slack/Gmail | `GET /api/connectors`, `POST /api/connectors/:id/connect`, `GET /api/oauth/:provider/authorize` |
| Error | parse/commit/connect failure | per-call catch |
| Skipped | user declines (Journey 2, PRD:683-686) | navigates to next onboarding step |
| Privacy headline | always | mockup right rail; existing copy in `HarvestTab.tsx:362-365` |
**Approval boundary (load-bearing):** S15 ends at *preview*; the explicit approve-before-persist gate is **S16 Memory Review**. The live code today commits directly from S15 (no separate review screen) — a PRD-compliance gap, see §3.
---
## 3. Current state in repo (exact files + what they do)
Two existing surfaces already implement most of S15's *upload* path against the harvest substrate:
### 3a. Onboarding step (the real S15)
- `apps/web/src/components/os/overlays/OnboardingWizard.tsx` — step index **3** = `memory-import` (`STEP_NAMES` at `:35`). Holds import state (`importSource`/`importPreview`/`importing`/`importDone` `:64-72`), handlers `handleFileImport` (`:156-166` → `adapter.harvestPreview`), `handleImportCommit` (`:168-177` → `adapter.harvestCommit`, then `goToStep(4)`), Claude-Code auto-detect on mount (`:182-191` → `adapter.scanClaudeCode`) and `handleClaudeCodeHarvest` (`:193-202`). Renders `<ImportStep step===3>` at `:519-531`.
- `apps/web/src/components/os/overlays/onboarding/ImportStep.tsx` (192 LOC) — the actual S15 UI. 6 `SOURCE_TILES` (chatgpt/claude/gemini/perplexity/cursor/unknown, `:18-33`) as **file pickers** (`accept=".json,.txt,.md,.csv"` `:113`), Claude-Code detect banner (`:62-86`), preview list + "Import N items" (`:125-155`), done state (`:157-162`), and a text pointer to "Memory → Harvest for 14+ more sources" (`:167-173`).
- `apps/web/src/components/os/overlays/onboarding/types.ts:38-52` — `ImportStepProps`.
### 3b. Post-onboarding harvest hub (the "Memory → Harvest" surface)
- `apps/web/src/components/os/apps/MemoryApp.tsx` → **Harvest tab** → `apps/web/src/components/os/apps/memory/HarvestTab.tsx` (685 LOC). The full-featured sibling: connected-sources list with auto-sync toggle/remove (`:505-559`), 15-source selector (`SOURCE_ICONS :35-51`), upload **and** paste modes (`:582-639`), preview with type-count chips (`:642-679`), **live SSE progress bar** (`:420-447`), **resume/discard banner** (`:330-360`), **identity-suggestion nudge** post-commit (`:452-470`), dedup/enrichment summary (`:472-502`), `no_real_embedder` not yet surfaced as a distinct affordance.
- `apps/web/src/components/os/apps/memory/ImportReminderBanner.tsx` — nudge to revisit import.
### 3c. Adapter methods (the contract surface, `apps/web/src/lib/adapter.ts`)
`harvestPreview` (`:1684`), `harvestCommit` (`:1689`), `getHarvestSources` (`:1694`), `scanClaudeCode` (`:1699`), `extractHarvestIdentity` (`:1710`), plus (per frontend inventory) `subscribeHarvestProgress`, `getLatestInterruptedHarvestRun`, `resumeHarvestRun`, `abandonHarvestRun`, `removeHarvestSource`, `toggleHarvestAutoSync`. Connector side: `getConnectors`, `getConnectorHealth`, `connectConnector`, `disconnectConnector`.
### Disposition: **rework** (promote-and-extend, do NOT create-new)
The harvest *engine* and most of the *upload* UX already exist and are wired to the right endpoints. S15 needs to be **reworked** to (a) match the mockup's connect-grid IA, (b) **split commit out into S16 Memory Review** to satisfy the PRD "no import without review/approval" gate, and (c) reconcile the two near-duplicate surfaces (`ImportStep` vs `HarvestTab`) onto one shared component so onboarding and the standalone hub don't drift. This is squarely the locked in-place refactor model — reuse `harvest.ts` substrate, extend the frontend.
---
## 4. Frontend work
**Reuse targets (do not rebuild):** `HarvestTab.tsx` is the canonical, feature-complete harvest UI — its SSE progress, resume banner, identity nudge, and dedup summary should be the shared core. `ImportStep.tsx` is the lighter onboarding shell. The connector tiles in the mockup map to the existing `ConnectorsApp`/`connectors/BrandTile.tsx` patterns.
Concrete components:
1. **Extract a shared `MemorySourcePicker` + `HarvestPreview` + `HarvestProgress`** from `HarvestTab.tsx` (currently a 685-LOC monolith; CLAUDE.md §coding-style favors small files) into `components/os/apps/memory/` so both `HarvestTab` and the onboarding `ImportStep` consume one source of truth.
- Props: `sources: SourceTile[]`, `onPreview(data,source)`, `onConnect(connectorId)`, `preview`, `progress`, `result`, `mode: 'onboarding'|'hub'`.
2. **Rework `ImportStep.tsx`** to the mockup's two-grid layout: **AI Assistants & Coding Tools** (Claude, Claude Code, Cursor, Hermes, Codex, ChatGPT, Gemini, Perplexity, Other) + **Files & Workspace Tools** (Files=`/api/ingest` upload, Notion/Drive/Slack/Gmail = connector "Connect"). Add the right-rail "What we import" + "You're in control" panels (copy already exists in `HarvestTab.tsx:362-369`).
- Distinguish tile *kind*: `upload` (harvest file picker), `scan` (Claude Code local), `connect` (connector OAuth). Hermes/Codex are AI-tool launch/hook surfaces (`LauncherApp`/tool-detect) — for v1 they can be `upload`/"Other" or marked "coming soon" (open question OQ-1).
3. **Move the commit decision to S16 Memory Review.** S15's "Continue" should carry the parsed preview forward; the explicit **approve → `harvestCommit`** happens on S16. Update `OnboardingWizard.handleImportCommit` (`:168-177`) to defer commit, or have S15 stage previews and S16 commit them. (Satisfies PRD:646/1207.)
4. **Surface `no_real_embedder`** as a soft inline affordance ("semantic search/wiki won't update until you add an embedding key") using the `cognifySkippedReason`/`wikiSkippedReason` already in the commit response — currently unsurfaced in both UIs.
5. **Connector consent flow** for Files & Workspace Tools tiles: reuse `adapter.connectConnector` + OAuth redirect (`/api/oauth/:provider/authorize`); show "review permissions" before connect (PRD:1207, Journey 8).
6. **State coverage:** add explicit Loading/Error/Offline/Permission-denied/Approval-required renders per PRD §14.1 (HarvestTab has most; ImportStep is missing loading/offline).
Adapter: **no new methods required for the upload path** — all harvest + connector methods already exist (§3c). New methods needed only if backend adds `/api/harvest/sources/:id/sync` and a connector `/sync` (see §5).
---
## 5. Backend work (PRD §16.5 + adjacent)
Cross-referenced against `docs/backend-map/sections/05c-subsystem-harvest.md`, `03b-api-memory.md`, and the route inventory.
| PRD §16 endpoint | Status | Note / what to EXTEND vs NET-NEW | Substrate |
|---|---|---|---|
| `POST /api/harvest/preview` | **EXISTS** | `routes/harvest.ts` — `{data,source}` → `{itemCount,types,preview[]}` (05c §6). No change. | personal `.mind` |
| `POST /api/harvest/commit` | **EXISTS** | `routes/harvest.ts` — full ingest: parse → `FrameStore.createIFrame(gop='harvest',src='import')` → cognify → wiki recompile; SSE heartbeats; resumable run-store (05c §4). No change. | `memory_frames` (personal.mind) + KG + wiki |
| `GET /api/harvest/sources` | **EXISTS** | `routes/harvest.ts` → `{sources: HarvestSource[]}`. No change. | `harvest_sources` |
| `POST /api/harvest/sources/:id/sync` | **PARTIAL → EXTEND (net-new thin route)** | No per-source `/sync` action exists (route-inventory §16.5). Sources are registered via `POST /api/harvest/sources` and toggled via `PATCH /api/harvest/sources/:source`; actual re-sync runs through `POST /api/harvest/commit`. **Add a thin `POST /api/harvest/sources/:source/sync`** that resolves the source row and calls the existing commit path. **Path-key mismatch to resolve:** PRD uses `:id`; current sources are keyed by `:source` **name** (DELETE/PATCH both use `:source`, harvest.ts). Pick `:source` for consistency with siblings. | `harvest_sources` + commit pipeline |
**Adjacent endpoints S15 actually calls (not in §16.5 but load-bearing — all EXIST):**
- `POST /api/harvest/scan-claude-code` — local `~/.claude` dry-run scan (EXISTS, `harvest.ts`).
- `GET /api/harvest/progress` — **SSE** progress (EXISTS).
- `GET /api/harvest/runs/latest-interrupted`, `POST /api/harvest/runs/:id/abandon`, resume via `commit {resumeFromRun}` (all EXIST).
- `POST /api/harvest/extract-identity` — post-commit identity suggestions (EXISTS) — feeds S16/Profile, not S15 proper.
- `POST /api/ingest` — for the "Files" tile (base64 file → text + frames, EXISTS, `ingest.ts`).
- `GET /api/connectors`, `POST /api/connectors/:id/connect`, `GET /api/oauth/:provider/authorize|callback` — for Notion/Drive/Slack/Gmail "Connect" tiles (all EXIST; connectors defined under `packages/agent/src/connectors/*` incl. `notion-connector.ts`, `gdrive-connector.ts`, `slack-connector.ts`, `gmail-connector.ts`). A connector `POST /api/connectors/:id/sync` is **MISSING** (route-inventory §16.9) — net-new if the workspace-tools tiles must pull data immediately, but for S15 a "Connected" state without immediate pull is acceptable for v1.
**`.mind` migration flag:** **None required for S15's import path.** Harvest writes plain `memory_frames` via the existing `createIFrame` signature — no schema change. (The broader Memory Center migration for explicit `confidence`/`provenance`/`kind` per PRD §15.4 — a single additive `metadata TEXT` column on `memory_frames` — is owned by the **Memory Center / S16 Review** cards, not S15. Provenance today is a text prefix `[Harvest:<source>]` in `content`, per 05c §4, which S16 can parse for the "source/confidence" review chips.)
---
## 6. Shared types needed (PRD §15 vs `lib/types.ts`)
S15's wire shapes are harvest-specific and live in `packages/hive-mind-core/src/harvest/types.ts` (`UniversalImportItem`, `HarvestSource`, `HarvestRun`, `ImportSourceType`, `ImportItemType` — 05c §1). The frontend currently re-declares lossy local interfaces (`HarvestSource`/`PreviewResult` in `HarvestTab.tsx:16-33`; `claudeCodeDetected` shape inline). Gaps vs `apps/web/src/lib/types.ts`:
- **No shared `HarvestSource`/`HarvestRun`/`PreviewResult`/`ImportSourceType` in `lib/types.ts`** — each surface hand-rolls them. Promote a canonical `HarvestSource`, `HarvestPreview`, `HarvestCommitResult`, `ImportSourceType` into `lib/types.ts` (mirror the hive-mind-core shapes) so `ImportStep` and `HarvestTab` share one contract.
- PRD §15.2 `Scope` / `MemoryKind` / `Confidence` unions are **not** S15's concern (they belong to S16/Memory Center) — S15 only needs the import-item/source/run types.
- `adapter.harvestPreview`/`harvestCommit` are typed `Promise<any>` (`adapter.ts:1684,1689`) — tighten to the new shared result types (CLAUDE.md / ts-rules forbid `any`).
---
## 7. Dependencies (screens/phases first)
- **Belongs to PRD Phase 2 "Work layer" → Onboarding flow** (PRD:233) / Roadmap **Sprint 5** (PRD:1335-1342). Sequenced after S12 First Launch, S13 Who Are You, S14 Tool Discovery.
- **Tightly coupled to S16 Memory Review** — S15 produces the preview; **S16 owns the approve→commit gate**. The commit-deferral rework (§4.3) cannot land without S16 existing. Plan S15 + S16 as a pair.
- **Feeds S17 Create Workspace** (Journey 18: Memory Review finds projects → pre-fill workspace, PRD:812-817) — downstream, not blocking.
- **Connector tiles depend on the Extend-layer Connector Hub** patterns (Phase 4) for OAuth/consent; for S15 v1 the existing `connectors.ts` + `oauth.ts` routes are sufficient (no Connector Hub UI dependency).
- Shared-component extraction (§4.1) should land **before** reworking `ImportStep` so both surfaces converge rather than diverge further.
---
## 8. Effort: **M**
Backend is near-zero (one thin `/sync` alias; everything else EXISTS). The weight is frontend: extract a shared harvest component from a 685-LOC monolith, rebuild `ImportStep` to the two-grid connect layout, wire connector-OAuth tiles, surface `no_real_embedder`, and re-sequence commit into S16. Not L because no new substrate/migration and the engine is done; not S because it touches two surfaces + the S15/S16 approval split + type promotion.
---
## 9. Open questions
1. **Hermes / Codex / Cursor tiles** (mockup) — these are AI-coding *tools* surfaced via the AI-OS launcher/tool-detect + hooks (`LauncherApp`, `/api/tools/detect`), not harvest export adapters (Cursor falls through `UniversalAdapter`; Hermes/Codex have no harvest adapter, 05c §1 union). For v1: render as `upload`/"Other" file pickers, or as "Connect via hooks" using the AI-OS launcher, or "coming soon"? PRD §12.12 says "connect/import from AI tools" without specifying the mechanism.
2. **S15/S16 commit split** — confirm the intended boundary: does S15 commit-and-S16-reviews-the-result, or S15-stages-previews-and-S16-commits? PRD:646/1207 ("nothing imports without review/approval") argues for the latter; current code commits at S15. (PRD Open Question — not listed in §23 but implied.)
3. **Connector "Connect" without immediate pull** — for Notion/Drive/Slack in S15, is a "Connected" state (creds stored) sufficient, or must data pull happen in-onboarding (requires net-new `POST /api/connectors/:id/sync`, §16.9 MISSING)? Maps to PRD §23 Q4 ("which connectors/MCPs are real in v1 vs seeded/mock").
4. **Two-surface reconciliation** — should the post-onboarding harvest surface stay in `MemoryApp → Harvest tab`, or be promoted to the PRD's Memory Center "Sources" tab (PRD §12.4 tabs include "Sources")? Affects where the shared component lives.
5. **`no_real_embedder` UX** — block import, warn-and-proceed, or prompt for an embedding key inline? (Cognify/wiki silently skip today; semantic recall degrades.)

278
docs/ux-refactor/gap-cards/S16-memory-review.md Normal file
View File

@@ -0,0 +1,278 @@
# Gap Card — S16 Memory Review
> Screen 16 in the UX-refactor blueprint deck. Onboarding step 5 ("Memory Review — approve
> before importing") AND the standing low-confidence review queue (Journey J08). Execution
> model is LOCKED: in-place incremental refactor of `apps/web` + targeted backend extension.
> Every claim below is grounded in repo source.
---
## 1. Screen & purpose
**Purpose (PRD §12.12 step 5; Blueprint screen 16, line 392-399):** the **trust gate before
memory becomes active**. After the user connects/imports sources (S15 Memory Import), Waggle has
parsed-but-not-committed items. S16 lets the user *review what was found, by category, with source
and confidence, and explicitly approve (or edit/skip) before anything is written to active memory.*
- Blueprint mental model (line 55-57): the **Understand** layer "classify, deduplicate, extract
entities, map relationships and **score confidence**" — "Memory Review shows categories, source
and confidence."
- Two entry points, same surface:
1. **Onboarding** (J01 First-time setup): `… → Memory Import → Memory Review → Workspace Creation`.
2. **Standing low-confidence queue** (J08): `Home alert → Memory Review queue → inspect evidence
→ approve/edit/reject` so "uncertain memory does not silently influence work."
- Mockup (`screen_16_memory_review.png`, directional only): header "Review before importing";
5 category stat tiles **Memories 342 / Decisions 56 / Tasks 32 / Artifacts 41 / Projects 17**;
a category-tabbed table (Memories | Decisions | Tasks | Artifacts | Projects) of rows with
Content / Type / Source / Confidence columns; search + Filters; right rail "Import summary"
(per-category counts), "Top sources" (Claude/ChatGPT/Google Docs/Notion with item counts), and
a "Confidence guide" legend; footer actions **Back / Skip for now / Edit selections /
Approved & import ABS items**.
**PRD acceptance criteria win over pixels (§24).** The load-bearing ACs:
- §12.12: "Nothing imports without explicit review/approval."
- Blueprint S16 acceptance: "Trust gate before memory becomes active."
- J08: "Uncertain memory does not silently influence work."
---
## 2. Required states (PRD / Blueprint)
Blueprint S16 states (line 396-397) + onboarding row (line 474-476):
| State | Meaning |
|---|---|
| **Empty** | No items found / nothing to review (source had no recognizable content). |
| **Preview found** | Parsed items shown, grouped by category, awaiting approval. |
| **Low confidence** | Subset surfaced as uncertain — must be inspectable (evidence) and individually approve/edit/reject (J08). |
| **Source error** | A source failed to parse/connect; offer retry-source. |
| **Approved** | User approved; commit runs (progress) → items become active memory. |
| **Import partial** | Onboarding state: some sources imported, some failed/skipped. |
Required **interactions** (line 394-395, 476): Filter, expand (inspect evidence), **edit selection**,
**approve import**, skip, **back**, **retry source**.
---
## 3. Current state in repo
**Disposition: `rework` (frontend) + `partial` (backend).** A trust-gate preview→commit flow EXISTS
in two places but neither delivers the categorized, per-item-confidence, per-item-selectable review
the screen requires. The existing surfaces are a *thin preview list + commit-all*, not a review gate.
### 3a. Onboarding ImportStep (the closest match to S16)
- `apps/web/src/components/os/overlays/OnboardingWizard.tsx` — step index 3 is "memory-import"
(`STEP_NAMES` `:35`). It calls `adapter.harvestPreview(data, source)` and stores
`result.preview` (`:163-164`), then `adapter.harvestCommit(data, source)` on approve
(`:168-177`), then auto-advances to the template step. **There is no separate "Memory Review"
step** — preview and commit are folded into the single ImportStep.
- `apps/web/src/components/os/overlays/onboarding/ImportStep.tsx` — renders a flat
`importPreview.slice(0,10)` list (`:125-155`) with one "Import N items" button. **No category
tiles, no per-item Type/Source/Confidence columns, no per-row selection, no evidence expand, no
source-error/low-confidence states.** Just "preview found → commit all → Memories imported!".
- `STEP_NAMES`/dots are hardwired to 8 steps (`:35`, dots `:472`). Inserting a dedicated Review step
shifts the step indices (template/persona/api-key/ready are `4/5/6/7`) — a refactor touch-point.
### 3b. MemoryApp HarvestTab (post-onboarding harvest surface)
- `apps/web/src/components/os/apps/memory/HarvestTab.tsx` — the richer harvest UI: connected-source
chips, Claude Code auto-detect, SSE progress, resume banner. Its `PreviewResult` interface
(`:28-33`) is `{ source, itemCount, types: Record<string,number>, preview: {id,title,type}[] }`.
`types` gives a **per-`type` count map** (the seed for category tiles) but `preview` is capped at
10 items, carries **no confidence**, and commit is **all-or-nothing** (no selection).
- Reached today via `MemoryApp.tsx:272` (`<HarvestTab />`, the "Harvest" tab).
### 3c. Backend preview/commit contract (what the UI can rely on)
- `packages/server/src/local/routes/harvest.ts`:
- `POST /api/harvest/preview` (`:221-236`) returns `{ source, itemCount, types: countByField(items,'type'),
preview: items.slice(0,10).map(i => ({id,title,type,source})) }`. **No confidence field; first-10 only.**
- `POST /api/harvest/commit` (`:243`+) parses with the adapter and writes **every** item as a raw
frame: `FrameStore.createIFrame('harvest', label+content, 'normal', 'import', ts)` (`:403-409`).
**No selection input, no confidence, no per-item categorization beyond the adapter's `type`.**
- `adapter.harvestPreview/harvestCommit` (`apps/web/src/lib/adapter.ts:1684-1692`) — both typed `any`,
signature `(data, source)`. No `selectedIds`/`approve` params exist.
- **The 4-pass `HarvestPipeline` (classify→extract→synthesize w/ `confidence` + dedup/contradiction
flags) EXISTS but is NOT called by the commit route** (backend-map `05c` §3, §4, line 7, 110,
117). `DistilledKnowledge.provenance.confidence` is produced only inside that unused pipeline.
So **the confidence + categorization data the mockup shows has no production producer today** —
this is the central backend gap (see §5).
**Net:** the *trust-gate intent* (preview before commit, nothing imports without consent) is partly
honored; the *categorized, confidence-scored, per-item-approvable review surface* the screen
specifies is **not built**.
---
## 4. Frontend work
Create a real Review surface usable from BOTH onboarding and the standing J08 queue.
### Components to create
- **`overlays/onboarding/MemoryReviewStep.tsx`** (NEW) — onboarding step 5. Replaces the inline
preview block currently embedded in `ImportStep.tsx`. Renders the full review layout.
- **`apps/web/src/components/os/apps/memory/MemoryReview.tsx`** (NEW, shared) — the reusable review
panel (category tiles + tabbed table + right rail + footer actions). Both the onboarding step and
a Memory-app "Review" surface mount this so there is ONE review implementation.
- **`components/os/apps/memory/review/`** sub-parts (small files per CLAUDE.md file-org rule):
`CategoryStatTiles.tsx`, `ReviewTable.tsx` (Content/Type/Source/Confidence cols + row checkbox +
expand-for-evidence), `ImportSummaryRail.tsx` (per-category counts + Top sources + Confidence
guide legend), `ReviewFooter.tsx` (Back / Skip / Edit selections / Approve & import N).
### Reuse targets (do not rebuild)
- `ContextMenu.tsx`, `components/ui/{table,tabs,checkbox,badge,input,scroll-area,skeleton}.tsx`
(shadcn set per frontend inventory §e) for the table/tabs/empty/loading states.
- `ContextRail.tsx` (`overlays/ContextRail.tsx`, exports `ContextRailTarget`) as the evidence/inspect
pattern for "expand → inspect evidence" (J08) rather than inventing a new evidence panel.
- HarvestTab's SSE progress wiring (`/api/harvest/progress`, phases saving/cognifying/wiki-compile)
for the "Approved → importing" state — lift the subscription into the shared panel.
- Color semantics from Blueprint design system (line 485): green=healthy/high-confidence,
orange=attention/low-confidence, red=risk/error — map to existing Hive DS semantic tokens
(no `hive-950` literals; tokens in `waggle-theme.css`).
### Props / state (shared `MemoryReview`)
```ts
interface ReviewItem {
id: string; title: string; content: string;
kind: MemoryKind; // mapped from ImportItemType (see §6)
source: ImportSourceType; // for the Source column + Top-sources rail
confidence?: number; // 0-100; undefined until backend produces it (see §5)
selected: boolean; // default true for high-confidence, false/uncertain otherwise
evidence?: string[]; // for the expand/inspect row
}
interface MemoryReviewProps {
mode: 'onboarding' | 'queue';
items: ReviewItem[]; loading: boolean; error?: string;
onApprove: (selectedIds: string[]) => Promise<void>; // → harvestCommit w/ selection
onSkip: () => void; onBack?: () => void;
onRetrySource?: (source: ImportSourceType) => void;
}
```
- Local state: per-category selection, search query, active category tab, expanded-row id.
- `selected` semantics enforce the AC: low-confidence rows start **unselected** so nothing uncertain
imports silently (J08).
### Adapter / hook changes
- Extend `adapter.harvestCommit` to accept an optional `{ selectedIds }` (or `approvedIds`) param;
type the preview response properly (drop `any`): `HarvestPreview { source; itemCount;
types: Record<MemoryKind, number>; items: ReviewItem[] }` — note the preview must return **all**
items (or paginate), not `slice(0,10)`, for a real review (see §5).
- NEW hook `useMemoryReview(source, data)` (or fold into a `useHarvest` hook) owning preview fetch +
selection state + commit; consumed by both mount points.
- Onboarding `STEP_NAMES`/dots/`progressPct` in `OnboardingWizard.tsx` must add the Review step
(8→9 steps OR split import/review and re-key 4-7). Update `displayStep`, dot array (`:472`),
Back-button range (`:444`), and the `goToStep(4)` auto-advances in `handleImportCommit`/
`handleClaudeCodeHarvest` to land on Review, not Template.
---
## 5. Backend work
### PRD §16.5 Harvest endpoints
| PRD §16 endpoint | Status | Extend vs net-new / substrate |
|---|---|---|
| `POST /api/harvest/preview` | **EXISTS (extend)** | `harvest.ts:221`. Today returns `types` + first-10 `preview` with **no confidence** and **no full item list**. EXTEND to (a) return **all** items (or `?limit/offset` paging) and (b) attach a per-item `confidence` + normalized `kind`. Substrate: `UniversalImportItem` (already carries `type`); confidence must come from a classifier (see below). No `.mind` migration for preview (in-memory parse). |
| `POST /api/harvest/commit` | **EXISTS (extend)** | `harvest.ts:243`. Today commits **all** parsed items. EXTEND body to accept `{ selectedIds?: string[] }`; when present, filter `items` before the `createIFrame` loop (`:382-409`). Honors the trust-gate AC ("nothing imports without approval"). Substrate: writes to `memory_frames` in personal.mind via `FrameStore.createIFrame` — unchanged shape, just a filtered set. |
| `GET /api/harvest/sources` | **EXISTS** | `harvest.ts` (`HarvestSourceStore`). Powers the right-rail "Top sources" + connected-source chips. |
| `POST /api/harvest/sources/:id/sync` | **PARTIAL** | No per-source `/sync` route (backend-routes.md §16.5; grep-confirmed absent). Sync today = `POST /api/harvest/commit`. Add a thin `/sources/:source/sync` that resolves the registered source + re-runs commit. NOTE PRD path uses `:id`; current sources are keyed by `:source` **name** (`DELETE/PATCH /api/harvest/sources/:source`) — keep the name key or alias. Net-new thin route, no new substrate. |
### Confidence + categorization (the real backend gap — implied addition to §16.5)
The mockup's **Confidence column / Confidence guide / low-confidence queue (J08)** and the **5
category tiles** have **no production producer**:
- `memory_frames` has **NO `confidence` column** (substrate-types §c, line 137: confidence exists
only on `knowledge_relations.confidence`). Frames are written `importance='normal', source='import'`.
- The classifier that yields `{categories, value, confidence}` is the unused `HarvestPipeline`
(Pass 1 Classify Haiku + Pass 3 Synthesize → `DistilledKnowledge.provenance.confidence`),
bypassed by the commit route (05c line 7).
- Category counts beyond the adapter's raw `type` (8 `ImportItemType` values) require a
classify step; the adapter `type` alone gives a coarse grouping but not the mockup's
Memories/Decisions/Tasks/Artifacts/Projects taxonomy 1:1.
**Decision needed (Open Q):** to deliver real confidence, the refactor must either
(a) wire `HarvestPipeline`'s classify/synthesize into a **preview-time** scoring pass (cost: Haiku/
Sonnet LLM calls per import — slow + paid; gated on a real embedder/key), or
(b) ship a **cheap heuristic confidence** at preview time (source-trust × adapter-type × dedup
signal) and reserve LLM scoring for an opt-in deep pass. Given onboarding latency budgets, (b) is
the pragmatic v1; (a) for the standing J08 queue.
**`.mind` migration flag:** if confidence becomes a queryable/filterable frame property (Filters in
the mockup; J08 "low-confidence review queue" off Home), add a nullable `metadata TEXT DEFAULT '{}'`
column to `memory_frames` (substrate-types §c line 156-164: the migration runner already does
idempotent `ADD COLUMN` on `memory_frames`; pattern at `mind/db.ts:116-124`) and store
`{kind, confidence, sourceId, status}` there, OR promote `confidence REAL` to a real column if it's
a primary filter axis. **This is the only potential schema migration on this screen.** Preview-only
confidence (not persisted) needs no migration.
### Standing low-confidence queue (J08) backend
- "Home alert → Memory Review queue" needs a way to *list already-imported low-confidence frames*.
No route exists. Closest: `GET /api/memory/frames` (`memory.ts:188`) + a confidence/status filter.
This depends on confidence being persisted (above). Implied addition to §16.4 Memory, not §16.5.
---
## 6. Shared types needed (PRD §15 vs `lib/types.ts`)
- **`MemoryKind`** (PRD §15.2): MISSING in `apps/web/src/lib/types.ts` (substrate-types §e). FE
`MemoryFrame.type` exists but mismatches PRD (`event`/`insight` vs PRD `preference`/`strategy`/
`learning`/`goal`). The review needs a `MemoryKind` union AND a **mapping from the harvest
`ImportItemType`** (8 values: conversation/memory/instruction/preference/artifact/rule/decision/
document — 05c §1) to the review categories (Memories/Decisions/Tasks/Artifacts/Projects). That
map is a new pure helper (`lib/harvest-kind-map.ts`).
- **`Confidence`** (PRD §15.2, 0-100): MISSING. Add the type; add `confidence?: number` to the
review item shape (and later `MemoryFrame` once persisted).
- **`ReviewItem` / `HarvestPreview`** response types: NEW (replace the `any` on
`adapter.harvestPreview/harvestCommit`). Mirror the server contract; co-locate or add to
`lib/types.ts`.
- `ImportSourceType` already documented in 05c (24-value union) — import/re-declare for the Source
column + Top-sources rail.
---
## 7. Dependencies (screens / phases first)
- **Upstream (must precede):** S15 Memory Import — supplies the `{data, source}` (or connected
source) that S16 reviews. The `harvestPreview` call + source selection live there.
- **Shares substrate with:** S-Memory Center (§12.4) — the persisted-frame edit/archive/merge +
the J08 low-confidence queue read from the same `memory_frames` + confidence field. Build the
confidence-on-frames decision once and reuse.
- **Feeds:** S-Home Cockpit (§12.1) — the "low-confidence review" Home alert (J08) deep-links into
this surface; needs `/api/home/*` (separate gap) + the persisted-confidence read.
- **Onboarding flow (S-Onboarding):** inserting the Review step re-keys `OnboardingWizard` step
indices — coordinate with whoever owns the onboarding-flow gap card so step numbering is changed
once.
- **Phase hint:** core trust-gate (preview-with-selection + commit-selected + cheap heuristic
confidence) is an **early phase** (it gates onboarding J01, a day-0 flow). The persisted-confidence
column + LLM classify pass + standing J08 queue are a **later phase** (depend on the Memory Center
confidence decision).
---
## 8. Effort
**L.** The reusable review panel + onboarding step re-keying + adapter/preview type-tightening +
commit selection are M on their own; the confidence/categorization producer (heuristic v1 now,
optional LLM-classify + possible `memory_frames` metadata migration later) plus the J08 standing
queue push it to **L**. It is NOT XL because no new data store is required — everything writes to the
existing `memory_frames` substrate via `FrameStore`, and the preview/commit routes already exist to
extend rather than build net-new.
---
## 9. Open questions
1. **Confidence source (blocking design):** heuristic-at-preview (source-trust × type × dedup) vs
wiring the existing `HarvestPipeline` classify/synthesize for real LLM confidence? Latency/cost vs
fidelity. Recommendation: heuristic for onboarding v1, LLM for the J08 queue. (§5)
2. **Persist confidence?** If "Filters" + J08 queue need to query confidence on already-imported
frames, we need the `memory_frames` metadata/`confidence` migration. If review is preview-only
(pre-commit), no migration. Which scope is v1? (§5)
3. **Category taxonomy mapping:** mockup shows Memories/Decisions/Tasks/Artifacts/Projects, but the
adapter emits 8 `ImportItemType`s and PRD §15.2 `MemoryKind` is a different set. Which is canonical,
and what is the exact `ImportItemType → category` map (esp. "Projects" — Claude `projects[].docs`
land as `artifact` items per 05c §2)? (§6)
4. **Per-item edit:** the footer "Edit selections" + interaction "edit selection" — is this just
include/exclude (checkbox), or inline content/kind editing pre-commit? Pre-commit edit has no
route today (frames don't exist yet); would need to mutate the in-memory item set before commit.
5. **Onboarding step count:** split Import↔Review into two steps (8→9) or keep one screen with a
review sub-state? Affects `STEP_NAMES`, dots, progress, and the "Step N" label already softened to
avoid a fixed total (`OnboardingWizard.tsx:456-467`).
6. **Source-error / retry-source state:** S15 owns connect/parse; does S16 only *display* the partial
state and offer "retry source" (re-invoking S15's connect), or own retry itself?

223
docs/ux-refactor/gap-cards/S17-workspace-creation.md Normal file
View File

@@ -0,0 +1,223 @@
# Gap Card — S17 · Workspace Creation
> Execution model: **in-place incremental refactor** of `apps/web` + targeted backend extension.
> Mockup is **directional only** (PRD §24); PRD acceptance criteria win over pixels.
> Every claim below cites a real file. PRD = `docs/Waggle_OS_UX_Refactor_Master_Handoff_Package/Waggle_OS_UX_Refactor_PRD.md`.
---
## 1. Screen & purpose
**Screen 17 — Workspace Creation.** "Create a workspace with suggested capabilities" — the screen that
turns onboarding (or a manual "+ New Workspace") into the user's **first useful context**.
- PRD §12.12 step 6 ("Workspace Creation — create first useful context") + Journeys 1/2 (PRD lines 678,
685: "Creates first workspace" / "Creates workspace manually" → lands in Home Cockpit).
- Blueprint screen-table row 17 (`_blueprint_extracted.txt:402-409`): Purpose "Create a workspace with
suggested capabilities"; Interactions "Enter name/type, add suggestions, review, create"; States
"Empty; recommended; validation error; created"; Acceptance "Workspace becomes first useful context
after onboarding."
- Mockup `screen_17_create_workspace.png` (directional): a **4-step wizard** (Basic info → Preferences →
Review & create) with a **left form column** (Description, Workspace type = Project/Client/Research/
Personal cards), a **center "Suggested capabilities" column** (Suggested Skills / Suggested Agents /
Suggested Connectors / Suggested MCPs, each with "Add all"), and a **right "Workspace summary" card**
(name, type, description, "Includes: Skills/Agents/Connectors/MCPs" counts). Footer: Cancel /
"Next: Preferences →".
**Net:** the mockup reframes the existing single-pane modal as a **stepped wizard whose center of gravity
is recommended capabilities + a live summary**, driven by workspace *type* and persona — not just a name +
template picker.
---
## 2. Required states (PRD / Blueprint)
From the blueprint state list + PRD acceptance criteria:
1. **Empty** — fresh form, no name/type, nothing suggested yet.
2. **Recommended** — once type/persona/template chosen, Suggested Skills/Agents/Connectors/MCPs populate
(silent default ordering, per `feedback_silent_recommendations_dont_ask.md` — recommend, don't interrogate).
3. **Validation error** — name required (PRD acceptance: validation surfaced inline); tier workspace-limit
reached (FREE = 5; existing 403 path); local storage-path missing.
4. **Created** — workspace persisted, becomes active, transitions to Home Cockpit (S?) / Workspace Desktop.
5. (Onboarding-embedded variant) — same flow but rendered as **step 6 of the wizard**, no modal chrome,
handing off to step 7 Home Cockpit (PRD §12.12).
PRD §12.12 acceptance that bears on this screen: "Connectors/MCPs/skills are **recommended from user
selections**" and "Onboarding asks user questions, not infrastructure questions."
---
## 3. Current state in repo
**Disposition: `rework`** (keep + heavily extend the existing component; do not create-new — the modal,
its template/persona/storage/agent-group machinery, and the live folder picker are all reusable substrate).
| File | What it does today |
|---|---|
| `apps/web/src/components/os/overlays/CreateWorkspaceDialog.tsx` (1129 LOC) | The live create-workspace modal. Single scrolling pane (NOT stepped). Fields: Template picker (category filter + search + 15 built-ins + custom CRUD via `TemplateCreatorModal`), Workspace **Name**, **Group** (`STANDARD_GROUPS`), **Storage Type** (virtual/local/team) + path + `FolderPickerModal` (live `adapter.browseLocal`/`browseLocalMkdir`), **Agent** (single persona grid from `PERSONAS` OR agent-group picker), **Share with team** toggle. Calls `onCreate({ name, group, persona?, agentGroupId?, shared?, storageType?, storagePath?, templateId? })`. |
| `apps/web/src/components/os/overlays/WorkspaceSwitcher.tsx` | Quick-switch list only (filters E2E/test names). **Not a creation surface** — adjacent, unchanged by S17. |
| `apps/web/src/hooks/useWorkspaces.ts:27-51` | `createWorkspace(data)` → `adapter.createWorkspace(data)`, optimistic add + select, local fallback on error. |
| `apps/web/src/lib/skill-recommendations.ts:103` | `recommendSkills(personaId)` → persona→skill-chip map w/ universal fallback. **Already the seed for "Suggested Skills".** |
| `apps/web/src/components/os/overlays/OnboardingWizard.tsx:278,314` | Onboarding's own inline `adapter.createWorkspace(...)` call (the embedded variant) — bypasses this dialog today. |
**Gaps vs mockup/PRD in the current component:**
- **No stepped wizard** — it's one scrolling modal, not Basic info → Preferences → Review.
- **No "Workspace type"** concept (Project/Client/Research/Personal) — only `Group` (free-string chips) +
`templateId`. (`WorkspaceType` is a missing schema field — see §5/§6.)
- **No Suggested Agents / Suggested Connectors / Suggested MCPs panels.** Suggested *skills* logic exists
(`recommendSkills`) but is **not wired into this dialog**. Connectors are fetched but only used for the
template editor's chip list, not surfaced as workspace-scoped recommendations.
- **No "Workspace summary" / Includes-counts card** (the right rail in the mockup).
- **No `description` field.**
**Two real FE bugs to fix in passing (surgical, in-scope):**
1. `useWorkspaces.createWorkspace` typed signature (`useWorkspaces.ts:27`) **omits `storageType`,
`storagePath`, `agentGroupId`** even though the dialog passes them — they're silently dropped at the
type boundary (the object still flows through to `adapter.createWorkspace`, but the local-fallback path
`:35-46` and the type contract lose them). Widen the param type.
2. `CreateWorkspaceDialog.onCreate` payload uses `persona`/`shared` (FE display names) while the backend
POST expects `personaId` and has **no `shared`/`group→team` mapping** — `shared` is accepted by the
dialog but never reaches `POST /api/workspaces` (which has no `shared` field; team linkage is `teamId`).
Reconcile during rework.
---
## 4. Frontend work
**Rework `CreateWorkspaceDialog.tsx` into a 3-step wizard** (keep the file; restructure internals). Prefer
extracting step bodies into small co-located components to respect the 800-LOC ceiling (current file is
already 1129 LOC — this rework should *reduce* it by extracting).
Components to create (new, under `overlays/workspace-create/`):
- `WorkspaceTypePicker.tsx` — Project/Client/Research/Personal cards (drives type + default suggestions).
Maps to new `WorkspaceType` union (§6).
- `SuggestedCapabilities.tsx` — 4 sections (Skills/Agents/Connectors/MCPs) each with per-item add +
"Add all". Reuse `recommendSkills(personaId)` for Skills; derive Agents from `PERSONAS` +
`adapter.getAgentGroups()`; Connectors from `adapter.getConnectors()` (already fetched here); MCPs from
a new MCP list source (§5). Silent-default ordering (no "which tools?" prompt).
- `WorkspaceSummaryCard.tsx` — live right-rail: name, type, description, "Includes" counts (skills/agents/
connectors/mcps selected).
- `WizardStepper.tsx` — Basic info / Preferences / Review header (or reuse a stepper primitive if added).
Reuse targets (do NOT rebuild): `TemplateCreatorModal`, `FolderPickerModal`, `ChipPicker`, `Tooltip`,
`STORAGE_OPTIONS`, the persona grid, `STANDARD_GROUPS`, `LockedFeature` (tier gate), `useFeatureGate`
(`multi-workspace`), `useWorkspaces`.
State/props additions:
- Local state: `step` (0|1|2), `description`, `type` (`WorkspaceType`), `selectedSkills[]`,
`selectedAgentIds[]`, `selectedConnectorIds[]`, `selectedMcpIds[]`.
- Extend `onCreate(...)` payload to include `description, type, skills, agentIds, connectorIds, mcpIds`.
- Wire `recommendSkills` + a new `recommendCapabilities(type, personaId)` helper in
`apps/web/src/lib/` (extends existing skill-recommendations pattern) so suggestions react to
type/persona without a backend call where possible.
Adapter/hook:
- Widen `useWorkspaces.createWorkspace` param type (fix §3 bug 1) to carry the new fields + storage fields.
- `adapter.createWorkspace` already POSTs the body through (`lib/adapter.ts` `createWorkspace` → `POST
/api/workspaces`); new body fields ride along once the route accepts them (§5).
- For Suggested MCPs, add `adapter.getMcps()` if a `/api/mcps` (or capabilities-derived) source is built (§5).
Onboarding parity: route `OnboardingWizard` step 6 through the **same** step bodies (render without modal
chrome) instead of its bespoke `adapter.createWorkspace` calls (`OnboardingWizard.tsx:278,314`) — single
source of truth for the create flow.
---
## 5. Backend work (PRD §16.2 + suggestion sources)
§16.2 endpoints used by/adjacent to this screen:
| PRD endpoint | Status | Extend vs net-new / substrate |
|---|---|---|
| `POST /api/workspaces` | **EXISTS** | `workspaces.ts:116-135`. **EXTEND** the Body type + `WorkspaceManager.create` to accept `description`, `type` (`WorkspaceType`), `skills[]`, `agentIds[]`, `connectorIds[]`, `mcpIds[]`, `status`. These are additive fields on `WorkspaceConfig`/`CreateWorkspaceOptions` (`workspace-manager.ts:5-95`). Substrate: `workspace.json` (file, not SQLite). |
| `GET /api/workspaces` | **EXISTS** | `workspaces.ts:101`. Unchanged. |
| `GET /api/workspaces/:id` | **EXISTS** | `workspaces.ts`. Unchanged. |
| `PATCH /api/workspaces/:id` | **EXISTS** | Used post-create for edits; should accept the new fields too. |
| `GET /api/workspace-templates` | **EXISTS** (not in §16 but central here) | `workspace-templates.ts:33` (15 built-ins). Templates already carry `persona`, `connectors`, `suggestedCommands`, `starterMemory` — the seed for Suggested panels. May **EXTEND** the `WorkspaceTemplate` shape to add `skills[]`/`mcps[]`/`type` so a chosen template can pre-populate all 4 suggestion lists. |
Suggested-capabilities data sources (mockup center column):
- **Skills** — no new endpoint; FE `recommendSkills` + starter-pack catalog (`GET
/api/skills/starter-pack/catalog`, EXISTS). On create, the route already auto-installs starter skills
(`workspaces.ts:198-211`) and seeds template starter-memory frames (`:223-249`).
- **Agents** — `GET /api/personas` (EXISTS) + `GET /api/agent-groups` (EXISTS). No new endpoint.
- **Connectors** — `GET /api/connectors` (EXISTS). No new endpoint.
- **MCPs** — **PARTIAL/MISSING**: per backend-routes inventory §16.9, there is **no `GET /api/mcps`**.
MCP servers surface inside `GET /api/capabilities/status` (`mcpServers[]`) and the static catalog
`@waggle/shared` `mcp-catalog.ts`. **EXTEND** rather than net-new store: add a thin `GET /api/mcps`
read route that composes `capabilities/status` + `mcp-catalog`, OR have the FE read the existing catalog
+ capabilities/status directly for the Suggested-MCPs panel (lower-risk for S17; defer the dedicated
route to S20/MCP screen).
**No new data store needed.** Persisting `agentIds`/`connectorIds`/`mcpIds` on the workspace = additive
optional fields on the `workspace.json` config (substrate-types §a confirms: **no DB migration** — these
live in JSON, not SQLite). `WorkspaceManager.create/update` (`workspace-manager.ts:124-244`) writes the
JSON; `update()` should also stamp `updatedAt` (currently missing, substrate-types §a) — fold that in here
since we're extending the write path anyway.
**.mind migration:** **None required for S17.** (The memory-side `metadata`/`confidence` migration in
substrate-types §c belongs to the Memory screen, not workspace creation.)
---
## 6. Shared types needed (PRD §15 vs `lib/types.ts`)
- **`WorkspaceType`** (PRD §15.2/§15.3) — **MISSING** everywhere. New literal union; mockup implies
`'project' | 'client' | 'research' | 'personal'` (confirm exact set — see Open Questions). Add to FE
`apps/web/src/lib/types.ts` AND backend `WorkspaceConfig` (`workspace-manager.ts`). Keep the existing
free-string `group` (don't drop — substrate-types §a "keep, do not drop").
- **`WorkspaceConfigV2` deltas** (PRD §15.3, lines 961-985) touched by this screen: add `description`,
`type`, `status` (`'active'|'paused'|'archived'`, default `'active'`), `agentIds[]`, `connectorIds[]`,
`mcpIds[]`, `updatedAt`. (`storageType`/`storagePath`/`teamId`/`teamRole`/`riskLevel`/`created` already
present.) Per substrate-types §a these are **pure additive optional fields, no DB migration**.
- FE `Workspace` (`lib/types.ts:22-40`) is a lossy projection (`persona` string vs config `personaId`;
derived `memoryCount`/`lastActive`/etc.). Add the same `type`/`description`/`status` + capability-id
arrays; reconcile `persona`→`personaId` mapping at the adapter boundary (don't break the switcher,
which reads `ws.persona`).
---
## 7. Dependencies (screens / phases first)
- **Schema additions are foundational** — `WorkspaceType` + the V2 config fields are shared by S?? Home
Cockpit, S?? Workspace Desktop (header shows type/status, substrate-types §b), and the Agent/Artifact
screens. Land the type + `POST/PATCH /api/workspaces` extension as a **shared early phase** before the
S17 UI rework so downstream screens consume the same fields.
- **Suggested capabilities** depends on the Skills (recommendSkills, exists), Personas/Agent-groups
(exist), Connectors (exists) sources — all available now. Only **Suggested MCPs** has a missing/partial
backend; gate that panel behind the MCP source decision (don't block S17 on the dedicated `/api/mcps`).
- **Onboarding (S?? §12.12)** consumes this flow as step 6 — unify after the standalone modal rework so
both paths share one implementation.
- PRD roadmap places this in **Sprint 5 — Onboarding and workspace creation** (PRD line 1335).
---
## 8. Effort
**M.** The modal, template/persona/storage/agent-group machinery, folder picker, and skill-recommendation
helper all exist — the work is restructuring into a 3-step wizard, adding 3-4 small components (type picker,
suggested-capabilities, summary card), wiring existing suggestion sources, and additive (no-migration)
backend field extension on the workspace config. Pushed toward the high end of M by the Suggested-MCPs
source ambiguity, the onboarding-parity unification, and the two FE bugs to reconcile; not L because there
is no new data store and no `.mind` migration.
---
## 9. Open questions
1. **Exact `WorkspaceType` values.** Mockup shows Project/Client/Research/Personal. PRD §15.2 names
`WorkspaceType` but does not enumerate. Confirm the canonical set (and whether `type` replaces or
coexists with the existing free-string `group`/`STANDARD_GROUPS`). Recommendation: coexist — `type` is
the new structured axis, `group` stays as the user's organizational label.
2. **Suggested MCPs source for S17.** Build the thin `GET /api/mcps` now, or read `capabilities/status` +
`mcp-catalog` directly from the FE and defer the dedicated route to the MCP screen? (Lower-risk =
defer.)
3. **`shared`/team handoff.** The dialog has a "Share with team" toggle that currently never reaches the
backend (no `shared` field on `POST /api/workspaces`). For S17, does "share" set `teamId`/`teamRole`
(requires a team to exist + TEAMS tier), or is it deferred to the Team screen? Today it's a dead toggle.
4. **Wizard vs modal in onboarding.** Confirm the embedded onboarding variant should render the *same*
step bodies (preferred, single source of truth) vs keeping `OnboardingWizard`'s bespoke create call.
5. **Does S17 install/connect on create, or only stage selections?** PRD says recommend; mockup "Add all"
implies staging. Confirm that selected connectors/MCPs are *recorded as workspace intent* (ids on the
config) vs *actually installed/connected* at create time (the latter pulls in install-audit + connector
OAuth flows — much larger scope; recommend record-only for S17).

205
docs/ux-refactor/gap-cards/S18-agent-builder.md Normal file
View File

@@ -0,0 +1,205 @@
# Gap Card — S18 Agent Builder
> UX-refactor planning artifact. Execution model: **in-place incremental refactor** of
> `apps/web` + targeted backend extensions. Every claim is grounded in a real file.
> PRD = `docs/Waggle_OS_UX_Refactor_Master_Handoff_Package/Waggle_OS_UX_Refactor_PRD.md`
> (§12.9 + §16.7). Mockup (directional only) =
> `Waggle_OS_Handoff_Assets/screens_18_21_builders_and_marketplace.png`.
---
## 1. Screen & purpose
Create an **agent as an explicit work actor** through a guided stepper, with no hidden
memory/tool access. PRD §12.9: "Manage agents as explicit work actors… User can explain
what an agent can see and do before enabling it." Blueprint Screen 18 (`_blueprint_extracted.txt:410-416`):
"Create an agent with goal, model, autonomy, memory, skills and permissions. Configure,
test, review, create. States: Draft; validation; approval needed; created. Acceptance:
No agent has hidden memory/tool access."
The Agent Builder is the create-flow companion to the **Agent Center** (Screen 9, a
separate gap card). S18 is one of four builder/marketplace screens grouped in the same
mockup (18 Agent Builder, 19 Skill Builder, 20 Automation Builder, 21 Marketplace).
PRD §16.7 names the agent CRUD/run/traces API surface this builder writes to.
---
## 2. Required states (PRD / Blueprint)
**Builder steps (PRD §12.9, line 589):** `Basic Info → Capabilities → Memory & Tools → Permissions → Review & Create` (5-step stepper).
**Agent fields the builder must collect (PRD §12.9 line 590 + §15.5 lines 1015-1036):**
name, goal, description, persona/avatar, model, autonomyLevel (`manual|guided|medium|high`,
PRD §15.2), type (`personal|workspace|team|autonomous`), memoryScopes, skillIds,
connectorIds, mcpIds, permissions, status, workspaceIds, createdBy, lastRunAt, successRate.
**Per-screen states (blueprint `:413-414` + `:461-463`):**
- `Draft` — partially-filled builder, save without activating.
- `Validation` — required-field gating (goal, model, memory scope, skills/tools/MCPs, autonomy per blueprint `:134`).
- `Approval needed` — elevated permission selections require an approval prompt before create (PRD §12.9 "all elevated access is reviewed"; §17.3 "elevated actions require human approval").
- `Created` — agent appears in Agent Center + target workspace (Journey 10, PRD lines 746-753).
- Plus global states (PRD §14.1): Loading, Error, Offline/local-only, Permission denied.
**Hard acceptance gate (blueprint `:415-416`, `:134`):** "No agent has hidden memory/tool access" and "Agent Builder must require model, goal, memory scope, skills/tools/MCPs and autonomy level." The Review step must render the full effective permission/memory/tool surface before the user confirms.
**Test affordance:** blueprint `:413` "Configure, **test**, review, create" — a dry-run before create (analogous to Skill Builder's test). PRD §12.9 does not list test as a functional requirement; treat as optional (open question §9).
---
## 3. Current state in repo — disposition: **create-new** (builder) + **partial** (substrate reuse)
There is **no Agent Builder and no first-class Agent entity** today. The closest existing
surface is a **persona/agent-group** model, which is a strict subset of the PRD Agent.
**Existing frontend (the seed):**
- `apps/web/src/components/os/overlays/SpawnAgentDialog.tsx` — a 2-step dialog (`config → confirm`, `:29`) that spawns a **transient sub-agent** (task + persona + model + parent workspace) via `adapter.spawnAgent` → `POST /api/fleet/spawn`. It collects only `task/persona/model/workspaceMode` (`:37-44`); it has model-fetch with 3-tier fallback (`:50-99`) and a cost-estimate review pane (`:388-421`). It does **not** persist an agent definition — it fires a one-shot fleet job. This is the seed named in the task, but it is a *spawn* dialog, not a *builder*.
- `apps/web/src/components/os/apps/AgentsApp.tsx` — titled **"Personas"** (`:175`), two tabs (`agents`/`groups`, `:16`). Lists personas via `adapter.getPersonas()` (`:36`) and agent-groups via `adapter.getAgentGroups()` (`:38`). "New Persona" → `CreateAgentForm`.
- `apps/web/src/components/os/apps/agents/CreateAgentForm.tsx` — a **single-page** form (not a stepper) collecting `name/description/icon/systemPrompt/tools[]` (`:9`), with an "Generate with AI" box (`:58-81`) → `adapter.generatePersona`. This is the closest existing "create-an-agent" UI, but it maps to a **persona** (no goal/autonomy/model/memoryScope/connectors/mcps/permissions).
- `apps/web/src/components/os/apps/agents/AgentDetail.tsx` — read view showing icon/name/description/tools/commands/affinity (`:49-103`). No goal/model/autonomy/permissions/successRate/status.
**Existing backend (the substrate to reuse, not rebuild):**
- `packages/server/src/local/routes/personas.ts` — `GET/POST/PATCH/DELETE /api/personas` + `POST /api/personas/generate`. POST persists a custom `AgentPersona` to disk (`saveCustomPersona`, `:57`); fields are `id/name/description/icon/systemPrompt/modelPreference/tools/workspaceAffinity/suggestedCommands/defaultWorkflow` (`:45-56`). **No** goal/autonomy/memoryScopes/connectorIds/mcpIds/permissions/status. PRO-tier gated (`:32`).
- `AgentPersona` interface (`packages/agent/src/personas.ts`; full field list in `docs/backend-map/sections/05a-subsystem-agent-runtime.md:198-218`) already carries `suggestedSkills?/suggestedConnectors?/suggestedMcpServers?/disallowedTools?/isReadOnly?` — useful seed columns for the richer Agent.
- `packages/server/src/local/routes/agent-groups.ts` — `GET/POST/PATCH/DELETE /api/agent-groups` + `POST /api/agent-groups/:id/run` (the run is a **placeholder stub**, `:105-127` — returns a queued jobId, does not execute). Groups persist to `{dataDir}/agent-groups.json` (`:29`). This is the closest "agent persistence on disk via JSON file" precedent.
- `packages/server/src/local/routes/fleet.ts` — `POST /api/fleet/spawn` is the **only real agent-execution path** (`:66-257`): creates a session, emits Waggle signals, and **fire-and-forgets `runAgentLoop`** in the background (`:142-245`). `POST /api/fleet/:workspaceId/pause|resume|kill` (`:260-290`). This is what `/api/agents/:id/run` and `/pause` must wire onto.
- `execution_traces` table (`packages/hive-mind-core/src/mind/schema.ts:199`) is written from `chat.ts` and `evolution.ts` (grep-confirmed) but has **no HTTP read route** — `/api/agents/:id/traces` is net-new over this store.
**Why create-new, not rework:** the PRD Agent (§15.5) is a **superset** of persona — it
adds goal, autonomy, type, memoryScopes, connectorIds, mcpIds, permissions, status,
workspaceIds, lastRunAt, successRate. A persona is the *behavioral template*; a PRD Agent
is an *instantiated, scoped, governed actor*. Bending `CreateAgentForm`/persona-POST to
carry all of that would corrupt the persona contract (shared by the runtime prompt
composer). The clean model: **net-new Agent entity + 5-step builder**, with a persona
selected *as one field* of the agent. Heavy reuse of persona catalog, model picker,
tool catalog, fleet-spawn, and execution-traces underneath.
---
## 4. Frontend work
**Create new — `apps/web/src/components/os/overlays/AgentBuilder.tsx`** (or
`components/os/apps/agents/AgentBuilder.tsx` if hosted inside the Agents app shell).
A 5-step stepper matching PRD §12.9:
1. **Basic Info** — name, goal (required), description, persona/avatar picker, type (`AgentType`).
2. **Capabilities** — model (required), autonomyLevel (required), defaultWorkflow.
3. **Memory & Tools** — memoryScopes (required), skillIds, tools[] (required-ish per blueprint `:134`).
4. **Permissions** — connectorIds, mcpIds, explicit permissions; surface elevated-access warnings here (drives the "approval needed" state).
5. **Review & Create** — full effective surface (the "no hidden access" gate), then create.
**Reuse targets (do not rebuild):**
- **Stepper chrome:** there is no shared `BuilderStepper` primitive yet (PRD §19.1 lists "Builder stepper" as a design-system component to create). S18/S19/S20 all need it — build it **once** as `components/ui/builder-stepper.tsx` and share. (Cross-screen dependency — flag to the Skill Builder & Automation Builder cards.)
- **Model picker:** reuse `components/os/ModelSelector.tsx` (already used by Spawn/Settings/onboarding) instead of `SpawnAgentDialog`'s bespoke model-button grid (`SpawnAgentDialog.tsx:328-344`).
- **Persona picker:** reuse the persona grid pattern from `SpawnAgentDialog.tsx:258-276` + `PERSONAS` from `@/lib/personas`; or fetch live via `adapter.getPersonas()` (as `AgentsApp.tsx:36`).
- **Tool picker:** reuse the searchable checkbox list from `CreateAgentForm.tsx:104-145` (tools sourced from `adapter.getCapabilityStatus()` → flattened `ToolDef[]`, `AgentsApp.tsx:49-55`).
- **Skills/connectors/MCPs pickers:** `adapter.getSkills()`, `adapter.getConnectors()`, and MCP list (see §5 — MCP list endpoint is itself partial). Persona's `suggestedSkills/suggestedConnectors/suggestedMcpServers` (05a `:216-218`) can pre-seed recommendations.
- **Cost-estimate review pane:** lift from `SpawnAgentDialog.tsx:388-421` (`adapter.getModelPricing()`).
- **Approval prompt:** reuse the approvals pattern (`ApprovalsApp` / inline chat approvals) for the elevated-access gate; do not invent a new modal.
**Adapter methods to add (`apps/web/src/lib/adapter.ts` — the single sidecar gateway, ~150 methods):**
`getAgents()`, `createAgent(def)`, `getAgent(id)`, `patchAgent(id, partial)`, `runAgent(id, {task?})`,
`pauseAgent(id)`, `getAgentTraces(id)`. (Today the adapter has `getPersonas/createPersona/…`,
`spawnAgent`, `getFleet/fleetAction`, `getAgentGroups/…` — none of these is the PRD Agent CRUD.)
**Wiring:** register the builder open path through the existing `waggle:open-app` CustomEvent
/ overlay state (`useOverlayState`); add it as a "New Agent" entry in the Agents app (which
should be renamed/retitled from "Personas" to host both — Agent Center card decides final IA).
**Reuse SpawnAgentDialog** as the quick "run now without saving" path — keep it; it is a
different verb (ephemeral spawn) from the builder (persisted definition).
---
## 5. Backend work (PRD §16.7 endpoints)
> Naming collision (backend-routes inventory `:486-492`): the **Cloud** server has a
> Clerk-gated `routes/agents.ts` with `/api/agents` CRUD — but that is NOT the sidecar.
> The desktop frontend talks only to the **local sidecar**, where the sidecar agent surface
> is `/api/agent/*` (singular) + `/api/agents/active` + `/api/agent-groups/*` + `/api/fleet/*`.
> So in the desktop context every §16.7 row below is MISSING-or-PARTIAL **locally**.
| PRD §16.7 endpoint | Status (sidecar) | Extend vs net-new + substrate |
|---|---|---|
| `GET /api/agents` | **MISSING** | Net-new route. Reads a net-new agent-definition store. Closest existing "definitions": `GET /api/personas` (`personas.ts:15`) + `GET /api/agent-groups` (`agent-groups.ts:49`) — neither is the PRD Agent. |
| `POST /api/agents` | **MISSING** | Net-new. **Pattern to reuse:** agent-groups JSON-file persistence (`agent-groups.ts:29-43`, `{dataDir}/agent-groups.json`) → store agents at `{dataDir}/agents.json` (no SQLite, mirrors persona/group precedent). Validate goal/model/memoryScopes/autonomy/permissions. PRO-tier gate like `personas.ts:32`. |
| `GET /api/agents/:id` | **MISSING** | Net-new read over the new store. |
| `PATCH /api/agents/:id` | **MISSING** | Net-new partial-update (mirror `agent-groups.ts:74-90` PATCH shape). |
| `POST /api/agents/:id/run` | **PARTIAL** | **Extend, do not build new execution.** Resolve agent → call the real executor `POST /api/fleet/spawn` (`fleet.ts:66`, the only path that actually runs `runAgentLoop` `:185`). Map agent's persona/model/memoryScope/workspace onto the spawn body. (`/api/agent-groups/:id/run` is a stub — `agent-groups.ts:105` — do NOT reuse it as the model.) |
| `POST /api/agents/:id/pause` | **PARTIAL** | **Extend.** Map agent's running session → `POST /api/fleet/:workspaceId/pause` (`fleet.ts:260`). |
| `GET /api/agents/:id/traces` | **PARTIAL / net-new route** | No HTTP route reads traces today. The `execution_traces` table exists (`schema.ts:199`) and is written by `chat.ts`/`evolution.ts`. Add a thin read route over the execution-trace store, filtered by agent/session. Fallback: session timeline `GET /api/workspaces/:wid/sessions/:sid/timeline` (`sessions.ts`). |
**Substrate touched:** new `{dataDir}/agents.json` (file store — no DB migration);
`personas.ts` (read for persona field); `fleet.ts` (run/pause delegation);
`execution_traces` (read for traces); `install_audit` (write an audit entry on agent
create when elevated connectors/MCPs are attached — `InstallAuditStore`, see §d of the
substrate inventory; note the `risk_level='critical'` CHECK-constraint drift bug flagged
there `install-audit.ts:16` vs DDL `:65`).
**.mind migration:** **NONE required.** The agent definition lives in a JSON file (precedent:
persona disk store + `agent-groups.json`), not in SQLite. `lastRunAt`/`successRate` are
derived (successRate from `execution_traces.outcome` / `procedures.success_rate`
`schema.ts:147,206`), not new columns. This matches the LOCKED in-place model and the
backend-routes inventory verdict ("none require a new data store").
---
## 6. Shared types needed (PRD §15 vs `lib/types.ts`)
Per substrate inventory §(e): **none of the PRD §15.2 unions exist in `apps/web/src/lib/types.ts`.**
S18 needs:
- `AgentType = 'personal' | 'workspace' | 'team' | 'autonomous'` (PRD §15.2) — **MISSING**.
- `AutonomyLevel = 'manual' | 'guided' | 'medium' | 'high'` (PRD §15.2) — **MISSING** in FE (note: a *different* `AutonomyLevel` exists in `hooks/useWindowManager.ts` for chat windows — Normal/Trusted/YOLO; do **not** reuse, they are different vocabularies — flag the collision).
- `Scope = 'personal' | 'workspace' | 'team' | 'organization'` (for `memoryScopes`) — **MISSING**.
- A full **`Agent`** interface (PRD §15.5 fields) — **MISSING**. Today `packages/shared/src/types.ts` has a thin `AgentDef` (`:36-47`: id/userId/teamId/name/role/systemPrompt/model/tools/config/createdAt) lacking goal/type/autonomy/memoryScopes/skillIds/connectorIds/mcpIds/permissions/status/lastRunAt/successRate. Decide: extend `AgentDef` (shared, cloud-aligned) vs add a desktop-local `Agent` in `lib/types.ts`. Given the sidecar-only execution model, a **new `Agent` interface in `lib/types.ts` + a matching server-side type** is cleanest; keep `AgentDef` for the cloud path.
- `ExtensionType` (for the connector/mcp/skill pickers' provenance) — **MISSING** but shared with S19/S21.
Keep types consistent with the new `agents.json` shape (PRD §22.2 "Frontend types are
consistent with API contracts").
---
## 7. Dependencies (screens / phases first)
- **Phase 3 (Intelligence layer)** per PRD §8 / Sprint 6 — same phase as Agent Center (S9), Skill Builder (S19), Automation Builder (S20).
- **Agent Center (Screen 9)** — the builder's create result must land somewhere; the Agent Center list/card view + the new `Agent` type + `GET /api/agents` are a shared prerequisite. Sequence: define `Agent` type + agent store + `GET/POST /api/agents` **with** Agent Center, then layer the builder on top.
- **Shared `BuilderStepper` primitive** (PRD §19.1) — build once, shared by S18/S19/S20. Whichever builder ships first owns it.
- **Connector Hub (S?) / MCP Hub (S?)** — the Permissions step picks connectorIds/mcpIds; the MCP listing is itself PARTIAL (no `GET /api/mcps`; data lives in `capabilities/status.mcpServers[]` + `@waggle/shared mcp-catalog.ts`). The picker can read those existing surfaces without waiting for the full Hubs, but the canonical MCP list endpoint is a cross-card dependency.
- **Approval prompt** component (PRD §19.1) — reuse existing approvals plumbing; not a hard blocker.
- **AppShell / IA** (Phase 0/1) — the builder opens via the existing window-manager overlay path; no new routing (single-route windowed desktop, per frontend inventory §b).
---
## 8. Effort: **L**
Net-new 5-step builder UI + net-new `Agent` entity, store, and CRUD routes, plus
run/pause delegation onto fleet and a net-new traces read route — but **every backend
piece reuses an existing substrate** (persona catalog, agent-groups JSON-file precedent,
fleet-spawn executor, execution-traces store; no `.mind` migration). The heavy reuse and
absence of a DB migration keep it off XL; the breadth (4 new + 3 partial endpoints, a new
shared entity/type, a shared stepper primitive, and the elevated-access approval gate)
keeps it above M.
---
## 9. Open questions
1. **Agent vs persona boundary.** Confirm the model: persona = behavioral template (one
*field* of an agent) vs agent = scoped governed instance. This card assumes that split.
Should creating an agent ever auto-create a backing persona, or always reference one?
2. **Store location.** `{dataDir}/agents.json` (mirrors `agent-groups.json`) vs a new
`agents` row in personal `.mind`. This card recommends the JSON file (no migration,
matches precedent). Confirm.
3. **`/run` semantics.** Does Agent Builder's eventual run mean "fleet-spawn a one-shot in
a chosen workspace" (current real path) or "persistent agent that keeps running"? PRD
agent states include `Running/Paused/Completed` (§14.5) — confirm the lifecycle the
sidecar must support beyond fleet's ephemeral sessions.
4. **Test step.** Blueprint says "configure, **test**, review, create" (`:413`); PRD §12.9
omits test. Include a dry-run (like Skill Builder's `POST /api/skills/:id/test`) or defer?
5. **`successRate` source.** Derive from `execution_traces.outcome` vs `procedures.success_rate`
vs a new counter? (Both exist; pick one to avoid a third tally vocabulary.)
6. **Autonomy vocabulary collision.** PRD `AutonomyLevel` (`manual/guided/medium/high`) vs
the chat-window `AutonomyLevel` (Normal/Trusted/YOLO in `useWindowManager.ts`) vs the
agent-loop's tiered-autonomy. Which governs an agent's tool execution at run time?
7. **Cloud vs sidecar `/api/agents`.** The Cloud server already has Clerk-gated `/api/agents`
CRUD. Should the desktop sidecar's new routes share a contract/shape with it for future
sync, or stay independent?

242
docs/ux-refactor/gap-cards/S19-skill-builder.md Normal file
View File

@@ -0,0 +1,242 @@
# Gap Card — S19 · Skill Builder
> UX-refactor planning artifact. Execution model is LOCKED **in-place incremental refactor**
> of `apps/web` + targeted sidecar extensions. Mockups are directional (PRD §24);
> PRD acceptance criteria win. Every claim below is grounded in a cited file.
>
> Sources: PRD §12.6 + §16.8 (`docs/.../Waggle_OS_UX_Refactor_PRD.md`), Blueprint Screen 19
> (`_blueprint_extracted.txt:417-421`, state model `:464`), mockup
> `Waggle_OS_Handoff_Assets/screens_18_21_builders_and_marketplace.png`, backend-map
> `sections/03d` + `05g`, inventories under `docs/ux-refactor/_inventory/`.
---
## 1. Screen & purpose
**Skill Builder** — the *create/edit* surface for a reusable capability (Skill). PRD §12.6:
a stepper Builder ("Basic Info → Instructions → Inputs & Outputs → Tools & Data → Review & Create"),
with **test-run before publishing** and assignment to agents/workspaces/automations or direct use.
Blueprint Screen 19 (`_blueprint_extracted.txt:417-421`): *"Create reusable capability. Define
prompt, inputs/outputs, tools, memory access, test."* States: *Draft; test pass/fail; published;
archived.* Acceptance: *"Skills are inspectable and reusable by agents/automations"* (PRD §12.6
acceptance: *"a user can understand what a skill does, where it is used, and what access it has"*).
This is the **Builder half of the Intelligence layer's Skills surface** (S06 Skills Hub is the
browse/library half). PRD Roadmap puts both in Sprint 6 / Phase 3 (`PRD:344-351`, `:236-240`).
The mockup tile labelled "Skill Builder" shows a left form column (name/description/category +
instructions textarea) and a right column (tools picker + memory access + a Test panel + a primary
"Create Skill" action) — directional confirmation of the §12.6 stepper.
---
## 2. Required states (PRD / Blueprint)
PRD §14.1 global states (every screen) + Blueprint Skills row (`_blueprint_extracted.txt:464`):
*Loading, empty, populated, error; Installed, draft, custom, workspace, marketplace, update available;
recovery: Test, install, publish, archive, rollback.*
Builder-specific lifecycle (Blueprint Screen 19 `:417-421`): **Draft → test pass/fail → published →
archived**, with PRD global add-ons: **validation error**, **approval required** (skills that request
elevated tool/secret access), **offline/local-only**.
Stepper steps the Builder must implement (PRD §12.6 `:542`):
1. **Basic Info** — name, description, category.
2. **Instructions** — the prompt/steps body.
3. **Inputs & Outputs** — declared input params + expected output shape.
4. **Tools & Data** — tools/data + **memory access** (read scope).
5. **Review & Create** — summary + **Test run** + publish-to-scope (personal/workspace/team).
Per-state behaviours required:
- **Validation error** — name normalises to kebab-case; empty name/description/steps blocked
(backend already 400s on these — §5).
- **Test pass/fail** — inline Test panel showing the injected-prompt preview + parsed metadata.
- **Published** — confirmation + the new skill appears in the Hub (Installed list).
- **Approval required** — when declared tools include elevated/secret/code-exec permissions
(frontmatter `permissions` block exists — `skill-frontmatter.ts:40-48`).
---
## 3. Current state in repo
**Disposition: `create-new`** (frontend Builder), **`keep-promote`** (backend structured-create
contract). There is **no Skill Builder component anywhere in `apps/web/src`** — grep for
`SkillBuilder|Skill Builder|skill-builder` over `apps/web/src` returns **0 matches**. Skill creation
today is only available to the *agent* (the `create_skill` tool, `skill-creator.ts:8`), not to the
*user* via UI.
What exists today:
- `apps/web/src/components/os/apps/CapabilitiesApp.tsx` — "Skills & Apps". A **browse/install/test**
surface only. Tabs: `installed | starter | marketplace | tools | audit` (`:80`, `:358`). It lists
packs (`PackCard` `:190`), shows a detail drawer (`PackDetail` `:249`), installs
(`handleInstall`/`handleMarketplaceInstall` `:164,:174`), and **tests** an existing skill
(`handleTestSkill` → `POST /api/skills/test` `:88-102`). **It has NO create/edit form.** This is
the natural host to add a "+ Create Skill" entry point that launches the new Builder.
- `apps/web/src/lib/adapter.ts:652` — `createSkill({ name, description })` exists but is **lossy**:
it POSTs to `/api/skills/create` with only `{name,description}` (no `steps`/`tools`/`category`),
while the backend requires a non-empty `steps[]` (`skills.ts:434`). So the one adapter method that
targets the create route is under-specified and **has no caller** in `apps/web/src` (grep:
`createSkill` appears only at its definition). Needs rework to the full template shape.
- `apps/web/src/lib/types.ts:210` — `SkillPack` (`id/name/description/category/skills[]/installed/trust`).
This is a **pack/catalog** shape, NOT a skill-authoring shape (no instructions/inputs/outputs/tools).
- `packages/agent/src/skill-creator.ts:11` — `SkillTemplate` (`name, description, triggerPatterns[],
steps[], tools[], category`) + `generateSkillMarkdown()` (`:26`). This is the canonical authored-skill
model the backend writes from.
- `packages/agent/src/skill-frontmatter.ts:53` — `ParsedSkill`/`SkillFrontmatter` (name, description,
`scope` personal→workspace→team→enterprise `:27`, `permissions` block `:40-48`). This is the read/parse
side; the Builder's "memory access / permissions" + "scope" map onto this.
Conclusion: backend authoring contract is solid and reusable; the **frontend Builder UI is greenfield**,
and the **adapter method must be widened** to the full template.
---
## 4. Frontend work
**Create (new):**
- `apps/web/src/components/os/overlays/SkillBuilder.tsx` — a 5-step stepper modal/drawer. Place it in
`overlays/` (consistent with `CreateWorkspaceDialog.tsx`, `SpawnAgentDialog.tsx`). Reuse the DS
Builder-stepper pattern (PRD §19.1 lists "Builder stepper" as a core component — none exists yet, so
this is the **first stepper**; AgentBuilder S18 + AutomationBuilder S20 should share it — see §7).
- Step 1 Basic Info: `name`, `description`, `category` (select from the `SKILL_FAMILIES` family set
in `skills.ts:13-31`: writing/research/decision/planning/communication/code/creative — surface
these as the category options, not the narrower `SkillPack.category` 5-union).
- Step 2 Instructions: ordered `steps[]` editor (add/remove/reorder) + optional `triggerPatterns[]`
(maps directly to `SkillTemplate.steps`/`.triggerPatterns`).
- Step 3 Inputs & Outputs: `inputs[]` / `outputs[]` param rows. **Backend does not persist these
structured today** (§5) — render them into the markdown body for v1, or block on the §5 backend
extension.
- Step 4 Tools & Data: `tools[]` multiselect (source the tool catalog already enumerated in
`CapabilitiesApp.tsx:422-434` — extract that hardcoded list to a shared module to avoid a third
copy; the agent tool registry is `packages/agent/src/tools.ts`) + **memory access / scope**
(`SkillScope` personal/workspace/team — `skill-frontmatter.ts:27`) + a `permissions` toggle group
(`skill-frontmatter.ts:40-48`).
- Step 5 Review & Create: summary card + **Test** button (calls existing test route) + Create.
- Optional `apps/web/src/components/os/overlays/skill-builder/` substeps if the file exceeds ~400 LOC
(CLAUDE.md file-org rule).
**Rework:**
- `apps/web/src/lib/adapter.ts` — widen `createSkill` (`:652`) to
`createSkill(t: { name; description; steps: string[]; tools?: string[]; category?: string;
triggerPatterns?: string[] })` (full `SkillTemplate` shape, matching `skills.ts:424-430`). Add
`updateSkill(name, content)` → `PUT /api/skills/:name` (`skills.ts:506`) for edit, and reuse the
existing test call (CapabilitiesApp inlines `fetch('/api/skills/test')` `:91` — promote it to an
`adapter.testSkill(skillName, testInput?)` method so the Builder and CapabilitiesApp share one path).
- `apps/web/src/components/os/apps/CapabilitiesApp.tsx` — add a "+ Create Skill" button (header,
next to the grid/list toggle `:340`) that dispatches `waggle:open-app` or opens the Builder overlay
via `useOverlayState` (the overlay open/close registry — `hooks/useOverlayState.ts`, per frontend
inventory §c). Optionally render an edit affordance on installed custom skills.
**Wiring:**
- Register the overlay in `Desktop.tsx` (overlays block) + add a flag to `useOverlayState`.
- Ctrl+K "Create → Skill" command should open it (PRD §12.3 Create category; `GlobalSearch.tsx`
already loads skills `:129`).
**Props/state:** local stepper state object `{ step, name, description, category, steps[],
triggerPatterns[], inputs[], outputs[], tools[], scope, permissions, testResult, status }`. On
Create → `adapter.createSkill(template)`; on Test → `adapter.testSkill(name)`. No new global store;
optimistic insert into the Skills Hub list on success (CapabilitiesApp already refetches via
`getSkills`).
---
## 5. Backend work (PRD §16.8)
| PRD §16.8 endpoint | Status | Note / what to EXTEND vs NET-NEW | Substrate |
|---|---|---|---|
| `GET /api/skills` | **EXISTS** | `skills.ts:164` — list installed skills. Hub/Builder list source. | `~/.waggle/skills/*.md` files |
| `POST /api/skills` | **EXISTS** | `skills.ts:167` raw `{name,content}`; **`POST /api/skills/create` (`skills.ts:431`) is the structured one** the Builder should use (`{name,description,steps[],tools?,category?}` → `generateSkillMarkdown` + `redactSkillContent` + audit + hash). | skill files + `auditStore` + `skillHashStore` |
| `PATCH /api/skills/:id` | **PARTIAL** | Update is `PUT /api/skills/:name` keyed by **name**, method **PUT**, body `{content}` (`skills.ts:506-510`). PRD uses `PATCH`+`:id`. **EXTEND**: accept `PATCH` alias + name↔id mapping (skills have no numeric id — name *is* the id). | skill files |
| `POST /api/skills/:id/test` | **PARTIAL** | Test exists as **`POST /api/skills/test`** (body `{skillName, testInput?}`, `skills.ts:570-575`) — not a per-id path. **EXTEND**: add `:id`-path variant (or keep body-driven; Builder can call either). Returns injected-prompt preview + metadata. | skill files + starter dir |
| `POST /api/skills/:id/install` | **PARTIAL** | No unified per-skill install-by-id. Closest: `POST /api/skills/starter-pack/:id` (`skills.ts:161`), `POST /api/skills/capability-packs/:id` (`:163`), marketplace `POST /api/marketplace/install` (`marketplace.ts`, **Tier: PRO**, SecurityGate). **EXTEND**: add a dispatcher `/skills/:id/install` that routes by source — OR leave install to the Hub (S06) and have the *Builder* only create (create == installed, since authored skills write straight to `~/.waggle/skills/`). | skill files / marketplace |
**Net-new backend gap surfaced by the PRD stepper (NOT in §16.8, but needed for §12.6 Step 3):**
the structured-create contract (`SkillTemplate`, `skill-creator.ts:11`) has **no `inputs`/`outputs`
and no `memoryScopes` fields**. PRD §15 skill object (and Blueprint §551 "Skill … inputs, outputs,
requiredTools, requiredMemoryScopes") expects them. Two options, both in-place:
- **v1 (no migration, recommended):** Builder serialises inputs/outputs/memory-scope into the
markdown body via an extended `generateSkillMarkdown` (add optional `inputs?`/`outputs?`/`scope?` to
`SkillTemplate`); they round-trip as `## Inputs` / `## Outputs` / frontmatter `scope:` sections.
`parseSkillFrontmatter` already reads `scope` (`skill-frontmatter.ts:27`) and `permissions`.
- **v2 (later):** promote to structured frontmatter if inputs/outputs become a query/filter axis.
**No `.mind` migration.** Skills are **filesystem markdown** (`~/.waggle/skills/*.md`), not SQLite —
confirmed `skills.ts:46-49`. The only DB touch is the **install-audit** record on create
(`skills.ts:476`, writes to `.mind` install_audit) + the skill-hash store. The audit `record()` call
already passes `riskLevel:'low'` so it sidesteps the latent `risk_level` CHECK drift noted in
substrate-types §(d) — no new exposure.
**Security:** create/update already pass content through `redactSkillContent()` (strips
secrets+user-paths, `skills.ts:464,:521`) and guard path-traversal in the name (`:447`). The Builder
must NOT bypass these — always go through `/api/skills/create` / `PUT /api/skills/:name`, never write
files another way. Elevated `permissions` (codeExecution/secrets/network) in a skill should trigger
the §2 "approval required" UX (PRD §12.6 / §17.3 elevated-action approval) — currently no approval
gate fires on skill authoring; flag as an open item (§9).
---
## 6. Shared types needed (PRD §15 vs `lib/types.ts`)
PRD §15.2 declares `ExtensionType = 'skill' | ...` — **MISSING** in `apps/web/src/lib/types.ts`
(substrate-types §e). For S19 specifically:
- **Add `SkillTemplate` (authoring) FE type** mirroring `packages/agent/src/skill-creator.ts:11`
(currently the FE only has the catalog-shaped `SkillPack` `types.ts:210`). Fields:
`name, description, category, steps[], triggerPatterns[], tools[]` + PRD additions
`inputs[]`, `outputs[]`, `scope` (`SkillScope`), `permissions`. Keep `SkillPack` (catalog) distinct
from `SkillTemplate` (authoring) — they are different objects.
- **Reuse `SkillScope`** (`personal|workspace|team|enterprise`) from `skill-frontmatter.ts:27` rather
than redeclaring (export it through the FE if needed; PRD §15.2 `Scope` is the broader
personal/workspace/team/organization — reconcile: skills use the `enterprise` variant).
- `SkillPack.category` is a narrow 5-union (`types.ts:213`) that does **not** match the backend
`SKILL_FAMILIES` 7-set (`skills.ts:13`). Widen the FE category union to the family set so the Builder
category picker and the Hub badges agree.
---
## 7. Dependencies (screens/phases first)
- **Phase/Sprint:** PRD Sprint 6 / Phase 3 — Intelligence layer (`PRD:344-351`, `:236-240`).
- **Hard prereq — DS Builder Stepper component** (PRD §19.1). None exists. S19 is the cheapest place
to introduce it, but **S18 Agent Builder** and **S20 Automation Builder** share the exact same
stepper pattern — build the stepper as a reusable primitive (`components/ui/` or
`components/os/overlays/builder-stepper/`) so all three Builders consume it.
- **Sibling — S06 Skills Hub** (the browse/library half, hosted today by `CapabilitiesApp.tsx`).
S19 launches *from* the Hub and writes *into* it (created skill → Installed list). They should ship
together or S06 first.
- **Soft — Command Center (Ctrl+K) (S03)** for the "Create → Skill" entry (PRD §12.3); not blocking.
- **Soft — Agent Builder (S18) / Automation Builder (S20)** consume skills via `skillIds`
(PRD §15.5) — they depend on skills *existing*, not on the Builder UI. Skill→agent assignment is a
downstream wiring concern.
---
## 8. Effort: **M**
Backend is mostly **EXISTS/PARTIAL** (structured-create, test, update all present — only thin aliases
`PATCH`/`:id`-path + an optional `inputs/outputs/scope` extension to `generateSkillMarkdown`, no DB
migration). The frontend is a net-new 5-step stepper + adapter widening + a reusable stepper primitive
shared with S18/S20 — real but bounded UI work. Not S (greenfield component + 3 endpoint extensions);
not L (no new substrate, no migration, backend authoring path already proven via the `create_skill`
tool).
---
## 9. Open questions
1. **Install vs create semantics.** Authored skills write straight to `~/.waggle/skills/` (create ==
installed). Does PRD `POST /api/skills/:id/install` (§16.8) apply to the *Builder* at all, or only
to the *Hub/Marketplace* install flow? Recommend: Builder = create-only; install-by-id lives in S06.
2. **Inputs/Outputs persistence.** v1 markdown-body serialisation vs structured frontmatter — confirm
whether inputs/outputs need to be *queryable* (drives the v1-vs-v2 backend choice in §5).
3. **Approval gate on elevated skills.** Should authoring a skill that declares
`permissions: {codeExecution|secrets|network}` trigger the PRD §17.3 approval prompt at *create*
time, or only at *run* time? No gate fires today on authoring.
4. **Scope vocabulary reconciliation.** `SkillScope` uses `enterprise`; PRD §15.2 `Scope` uses
`organization`. Pick one for the Builder's publish-to-scope picker.
5. **Test-run fidelity.** `POST /api/skills/test` returns only the *injected-prompt preview* + parsed
metadata (`skills.ts:570`), it does **not** execute the skill against an LLM. Is preview-only
sufficient for the PRD "test pass/fail" state, or is a live dry-run expected? (Live run would be
net-new and lean on `/api/agent/run`.)
6. **Category source of truth.** Reconcile `SkillPack.category` (5-union) vs `SKILL_FAMILIES` (7-set)
vs `SkillTemplate.category` (free string) — which is canonical for the picker?

224
docs/ux-refactor/gap-cards/S20-automation-builder.md Normal file
View File

@@ -0,0 +1,224 @@
# Gap Card — S20 Automation Builder
> UX-refactor planning artifact. Execution model: **in-place incremental refactor** of
> `apps/web` + targeted backend extensions. Mockups are directional (PRD §24); PRD acceptance
> criteria win. Every claim is grounded in a real file path below.
>
> Sources: PRD §12.10 + §16.10 (`docs/Waggle_OS_UX_Refactor_Master_Handoff_Package/Waggle_OS_UX_Refactor_PRD.md`),
> Blueprint screen 20 (`_blueprint_extracted.txt:423-429`), mockup
> `Waggle_OS_Handoff_Assets/screens_18_21_builders_and_marketplace.png`, baseline inventories under
> `docs/ux-refactor/_inventory/`, backend-map `docs/backend-map/sections/03f-api-realtime-ops.md`.
---
## 1. Screen & purpose
A 4-step **stepper** builder that lets a user create a scheduled or event-driven workflow
("automation"). PRD §12.10 / Blueprint screen 20: *"Create scheduled or event-driven workflow.
Choose trigger/condition/actions/agent/notification, test, activate."*
PRD §12.10 fields (line 605): `name, trigger, condition, actions, agent, notification, schedule,
workspace, status`. Builder steps (PRD line 604): **Trigger → Condition → Actions → Review &
Activate**. This is the *create/edit* surface; the *list/run/pause/logs* surface is the sibling
**Automation Center** (screen 11, PRD §12.10 tabs Overview/Running/Scheduled/Triggers/History/Logs)
— scoped in its own card, but they share the same backend (cron) and types.
Mockup (directional, panel labelled "20. Automation Builder", top-right of
`screens_18_21_builders_and_marketplace.png`): left rail = step list (Trigger/Condition/Actions/
Review); center = config form with a **Trigger** block (schedule vs event), a **Condition** block,
an **Actions** list, an **Agent** selector and a **Notification** target; footer = Test +
Activate buttons.
---
## 2. Required states (PRD/Blueprint)
PRD §14.6 automation lifecycle states: `Draft, Scheduled, Running, Success, Failed, Paused,
Awaiting approval, Disabled`. Blueprint screen-20 states (`_blueprint_extracted.txt:428-429`):
**Draft; test fail; active; scheduled; approval needed.**
Builder-screen states (the create flow itself), composed with PRD §14.1 global states:
- **Draft / editing** — stepper in progress, per-step validation (e.g. invalid cron expr, no action chosen).
- **Test running / test pass / test fail** — dry-run a draft before activating (PRD line 604 "test").
- **Activating → Scheduled/Active** — on save the automation appears in Automation Center + Home overnight summary (PRD line 607, 611).
- **Approval required** — an automation whose actions touch an elevated/risky capability must surface an approval prompt (PRD §17.3 "Automations can only run actions allowed by the user/team role"; PRD line 607 "risky automations surface in Home").
- **Loading / Error / Offline / Permission-denied** — global states (PRD §14.1). Offline: degrade gracefully, keep draft local.
---
## 3. Current state in repo
**Disposition: `rework`** (promote the existing cron surface into the Trigger/Actions skeleton;
the Condition step + event-triggers + test/approval are net-new but build on cron — no new store).
Current implementation is the **cron** surface, not an "Automation Builder":
| Layer | File | What it does today |
|---|---|---|
| Frontend app | `apps/web/src/components/os/apps/ScheduledJobsApp.tsx` | Single-screen "Scheduled Jobs" manager (NOT a stepper). Inline create form with 4 fields: name, **jobType** (`<select>` over `CRON_JOB_TYPES`), **schedule** (preset `<select>` + custom cron), **outputChannel** (`log`/`telegram`). List rows: enable/disable toggle, run-now (`Play`), delete. `:55` create, `:93` toggle, `:102` delete, `:112` trigger. No condition, no agent picker, no test, no review step. |
| Form helpers | `apps/web/src/lib/cron-presets.ts` | `CRON_SCHEDULE_PRESETS` (6 cadences), `CRON_JOB_TYPES` (6 types), `describeCronExpr` / `isPlausibleCronExpr` cron→English. Reusable as-is for the Trigger step. |
| Adapter | `apps/web/src/lib/adapter.ts:815-845` | `getCronJobs`, `createCronJob`, `updateCronJob`, `deleteCronJob`, `triggerCronJob` → `/api/cron*`. |
| FE type | `apps/web/src/lib/types.ts:230-238` | `CronJob { id, name, schedule, workspaceId, enabled, lastRun?, nextRun? }` — **lossy**: drops `jobType`, `jobConfig`, `createdAt`; renames `cronExpr`→`schedule`, `nextRunAt`→`nextRun`. No `trigger`/`condition`/`actions`/`agent`/`notification`/`status` (the PRD §15/§12.10 automation shape). |
| Route | `packages/server/src/local/routes/cron.ts` | Full CRUD + `POST /api/cron/:id/trigger` (auto-enables on run, `:188`). |
| Store | `packages/core/src/cron-store.ts` | `CronStore` over `.mind`: `cron_schedules` (`:71`), `cron_execution_history` (`:88`), `notifications` (`:104`). Schedule row: `name, cron_expr, job_type, job_config, workspace_id, enabled, last_run_at, next_run_at`. **No trigger-type, condition, or actions columns** — `job_config` is a free JSON blob. |
| Scheduler | `packages/server/src/local/cron.ts` | `LocalScheduler` — 60 s tick, `getDue()` poll, `executeJob()` for manual trigger, auto-disable after 5 consecutive failures (`MAX_CONSECUTIVE_FAILURES`), `onJobComplete` notify callback. **Time-driven only.** |
| Executor (the real "actions") | `packages/server/src/local/index.ts:1379-1751` | `new LocalScheduler(cronStore, async (schedule) => switch(schedule.job_type){…})`. Cases: `memory_consolidation` (`:1381`, incl. `action:'index_reconcile'` marketplace sync), `workspace_health` (`:1504`), `proactive` (`:1525`, sub-actions morning_briefing/stale_workspace_check/task_reminder/capability_suggestion `:1561-1582`), `prompt_optimization` (`:1590`), `agent_task` (`:1722`, runs a `jobConfig.prompt` in a workspace), `monthly_assessment`. |
| History route | registered in `notifications.ts` | `GET /api/cron/:id/history` (backend-map `03f:147`) → execution rows. |
**Grep confirmation:** no `Automation`/`AutomationBuilder` component, no event-trigger code, no
`condition` field. The 13 frontend hits for "Automation|trigger|condition" are the word "trigger"
used in unrelated contexts (`triggerCronJob`, MCP triggers, marketplace) — confirmed none is an
automation builder. (`ScheduledJobsApp.tsx` is the only real match.)
**Mental model match:** what the user calls "trigger" today is **only a cron schedule** (time).
What the user calls "actions" today is **a single `jobType`** chosen from a fixed catalog (one
action per job). There is **no condition, no multi-action sequence, no per-automation agent
binding (except via `agent_task` prompt), and no event triggers.**
---
## 4. Frontend work
**New components (`apps/web/src/components/os/apps/automations/`):**
- `AutomationBuilder.tsx` — 4-step stepper (reuse the **Builder stepper** DS pattern from Agent/Skill
builders — PRD §19.1; align with `CreateAgentForm.tsx` in `apps/web/src/components/os/apps/agents/`).
Owns draft state `{ name, trigger, condition, actions[], agentId?, notification, schedule,
workspaceId, status:'draft' }`; submits via adapter (see §5).
- `TriggerStep.tsx` — radio: **Schedule** (reuse `cron-presets.ts` preset/custom `<select>` +
`describeCronExpr` preview — lift the schedule block straight out of `ScheduledJobsApp.tsx:195-223`)
vs **Event** (gated/"coming soon" if event triggers aren't built — see §5/§9). Workspace scope picker
(reuse `useWorkspaces`).
- `ConditionStep.tsx` — optional predicate (e.g. "only if N+ new frames", "only on weekdays"). **Net-new
concept** — no substrate; ship a minimal optional condition stored in `job_config.condition` (no DB
migration; see §5). Keep simple — PRD §3.2/§19.2 ("not forced during onboarding").
- `ActionsStep.tsx` — choose one or more actions. v1 maps to the existing `CRON_JOB_TYPES` catalog
(the only executable actions today, `index.ts` switch). For `agent_task`, surface an **Agent**
selector (reuse `useWorkspaces` + persona/agent picker from `agents/`) and a prompt field; for
`proactive`, surface the sub-action choice; plus a **Notification** target (reuse the
`log`/`telegram` `outputChannel` selector already in `ScheduledJobsApp.tsx:225-242`).
- `ReviewStep.tsx` — summary + **Test** button (dry-run, see §5) + **Activate** button.
- `AutomationCenter.tsx` (sibling, may be its own card) — promote `ScheduledJobsApp.tsx` into the
PRD §12.10 tabbed Center (Overview/Running/Scheduled/Triggers/History/Logs), wiring `GET
/api/cron/:id/history` for the Logs tab.
**Reuse targets:** `cron-presets.ts` (whole module), the schedule + output-channel JSX blocks in
`ScheduledJobsApp.tsx`, the stepper chrome from `agents/CreateAgentForm.tsx`, `useToast`,
`useWorkspaces`, `ui/select`/`ui/input`/`ui/dialog`.
**Adapter methods/hooks:** extend `lib/adapter.ts` cron methods to round-trip `jobType` +
`jobConfig` (currently `createCronJob` already accepts `jobConfig` — `:821`; the lossy FE `CronJob`
type is what drops it on read). Add `testAutomation(draft)` and (if added) `pauseCronJob(id)`,
`getCronHistory(id)`. New `useAutomations()` hook wrapping these (mirrors existing domain-hook
pattern). **Register the new app** in `Desktop.tsx` `appConfig` + `renderAppContent` switch and
the dock (`lib/dock-tiers.ts`), under the **Intelligence** IA bucket (PRD §10.3) — the existing
`scheduled-jobs` AppId can be renamed/aliased to `automations`.
---
## 5. Backend work (PRD §16.10)
> **Substrate verdict (matches the backend-routes inventory):** all six §16.10 endpoints are
> **PARTIAL** — the cron surface (`/api/cron*`) already provides full CRUD + trigger + history. The
> refactor **aliases/extends cron as "automations"**; no new store. `trigger`/`condition`/`actions`
> ride in the existing `job_config` JSON blob → **no `.mind` migration** for v1.
| PRD §16.10 endpoint | Status | Extend (existing) vs net-new + substrate it touches |
|---|---|---|
| `GET /api/automations` | **PARTIAL** | **Extend** `GET /api/cron` (`cron.ts:94`). Alias path; reshape `toResponse` to expose `trigger/condition/actions/status` derived from `job_type` + `job_config`. Substrate: `cron_schedules`. |
| `POST /api/automations` | **PARTIAL** | **Extend** `POST /api/cron` (`cron.ts:67`). Accept the richer automation body; persist `trigger`/`condition`/`actions` into `job_config` (and `cron_expr` for schedule triggers). Substrate: `cron_schedules`. |
| `PATCH /api/automations/:id` | **PARTIAL** | **Extend** `PATCH /api/cron/:id` (`cron.ts:124`). Substrate: `cron_schedules`. |
| `POST /api/automations/:id/run` | **PARTIAL** | **Extend** `POST /api/cron/:id/trigger` (`cron.ts:174`, runs `scheduler.executeJob`, auto-enables). Substrate: `cron_schedules` + executor switch (`index.ts:1379`). |
| `POST /api/automations/:id/pause` | **PARTIAL** | No `/pause` route. **Net-new thin route OR reuse** `PATCH /api/cron/:id {enabled:false}`. Add `/pause` alias for the PRD contract. Substrate: `cron_schedules.enabled` + scheduler `resetFailure`. |
| `GET /api/automations/:id/logs` | **PARTIAL** | **Extend/alias** `GET /api/cron/:id/history` (in `notifications.ts`; backend-map `03f:147`). Substrate: `cron_execution_history` (`cron-store.ts:88`). |
**Net-new beyond §16.10 (PRD requires, backend lacks):**
1. **Test / dry-run** (PRD line 604 "test"). No route today. **Net-new** `POST /api/automations/test`
that runs `scheduler.executeJob` against an unsaved draft (or a draft saved `enabled:false`) and
returns the result without scheduling. Touches the executor switch (`index.ts:1379-1751`) — must
make it callable with an ad-hoc schedule object, not only persisted rows.
2. **Condition evaluation** (PRD step 2). Net-new logic in the executor: before running actions, read
`job_config.condition` and short-circuit. No new table — `condition` is a JSON sub-field of
`job_config`. Keep predicate vocabulary minimal in v1.
3. **Event triggers** (PRD "event-driven", §14.6 "trigger fired", Blueprint "scheduled or
event-driven"). **Major net-new substrate gap** — `LocalScheduler` is **time-poll only**
(`cron.ts` `getDue()` on `next_run_at`). True event triggers need an event→automation dispatch
path (could hang off `server.eventBus` audit/notification stream — `03f:321-347`). **Recommend
deferring event triggers to a later phase**; ship schedule-triggers only in v1 and gate the
"Event" option (see §9, §8).
4. **Approval gate for risky actions** (PRD §17.3, line 607). When an automation's actions touch an
elevated capability, route through the existing approval/install-audit machinery
(`/api/approval/*`, `install-audit.ts`). Wiring net-new; substrate exists.
**`.mind` migration flag:** **None required for v1** (trigger/condition/actions live in the existing
`job_config TEXT` blob — `cron-store.ts:77`). A later migration could promote `trigger_type` /
`status` to real columns (the migration runner already does idempotent additive `ADD COLUMN` on
`.mind` tables — see substrate-types `§(c)` precedent) **only if** they become query/filter axes for
Automation Center tabs (Running/Scheduled/Triggers).
---
## 6. Shared types needed (PRD §15 vs `lib/types.ts`)
PRD §15.2 unions `AutonomyLevel` / `AgentType` are **MISSING** from `apps/web/src/lib/types.ts`
(per substrate-types `§(e)`). Blueprint §17 names an **Automation** entity (`_blueprint_extracted.txt:553`):
`id, scope, trigger, condition, actions, agentId, schedule, notificationTargets, status, lastRunAt,
nextRunAt`. None of this exists in FE types today.
- **Add `Automation` interface** to `lib/types.ts` (Blueprint shape above) replacing the lossy
`CronJob` (`types.ts:230`) — or layer it as a richer superset and have the adapter map cron rows
into it. Add `AutomationTriggerType = 'schedule' | 'event'`, `AutomationStatus = 'draft' |
'scheduled' | 'active' | 'running' | 'paused' | 'failed' | 'awaiting_approval' | 'disabled'`
(PRD §14.6), and an `AutomationAction` discriminated union keyed on the existing `CronJobType`
catalog (`cron-presets.ts:15`).
- Reconcile FE↔BE: the FE `CronJob` already mismatches the `/api/cron` response shape
(`cronExpr`→`schedule`, drops `jobType`/`jobConfig`) — fix this drift as part of the type work.
- Keep the canonical `CronJobType` union single-sourced (currently duplicated in
`cron-presets.ts:15` AND `packages/core/src/cron-store.ts:15` — flag the dup; do not add a third).
---
## 7. Dependencies (screens/phases first)
- **PRD Phase 3 (Intelligence layer)** — same phase as Agent/Skill builders; reuse their stepper.
- **Agent Builder (S18/agents)** must define the agent picker the `ActionsStep` agent selector binds
to (PRD §12.9). Soft dependency — can fall back to persona/`useWorkspaces` until Agent entity lands.
- **Automation Center (screen 11)** is the list/run/logs sibling — share types + adapter; build the
Center's Logs tab on the same `/api/cron/:id/history`.
- **Home Cockpit (S?)** — overnight summary + "attention required" must surface failed/risky
automations (PRD line 607, 611). Soft consumer dependency (Home reads automation status).
- **Approval surface (`ApprovalsApp` / `/api/approval/*`)** — for the risky-action gate (§5.4).
- **DS:** Builder stepper + Approval prompt primitives (PRD §19.1) shared across all builders.
---
## 8. Effort: **L**
Rework + extend is cheap (the cron store/route/executor + `cron-presets` + output-channel UI all
exist and are reusable), but the gap between "cron job manager" and the PRD's
**Trigger/Condition/Actions/Agent/Notification stepper + Test + approval-gated activate** is wide:
net-new Condition step, dry-run test endpoint, FE type reconciliation, and an Agent binding. The
**Event-trigger half is XL on its own** (no event-dispatch substrate) and is recommended **out of
v1 scope** — if it stays in, this becomes XL.
---
## 9. Open questions
1. **Event triggers in v1 or schedule-only?** `LocalScheduler` is time-poll only; true event triggers
need a new event→automation dispatch path off `server.eventBus`. Recommend defer + gate the "Event"
radio option. (Ties to PRD §23 open-question spirit on scope.)
2. **Condition vocabulary** — what predicates does v1 support? (frame-count threshold, day-of-week,
workspace-state flag?) PRD names "condition" but specifies no predicate set.
3. **One action or multiple per automation?** Today one `job_type` == one action. PRD says "actions"
(plural). v1 = single action mapped to `CronJobType`, or true multi-action sequence (needs executor
rework + ordering semantics in `job_config`)?
4. **Does `pause` get a dedicated route or reuse `PATCH …{enabled:false}`?** Affects the §16.10
contract surface and Automation Center.
5. **Which `.mind`** do automations live in — personal vs per-workspace? `cron_schedules.workspace_id`
is nullable + `'global'→'*'` normalized (`cron.ts:74`); confirm scope model for the §16.10 list.
6. **Risky-action approval class** — which actions are "elevated" (e.g. `agent_task` writing files,
marketplace `index_reconcile`)? Needs an approval-class mapping before the §5.4 gate can ship.
7. **Naming/AppId** — rename `scheduled-jobs` AppId → `automations`, or keep both (alias)? Affects dock
+ window-manager + the dead-id cleanup already flagged in the frontend inventory.

137
docs/ux-refactor/gap-cards/S21-marketplace-extend.md Normal file
View File

@@ -0,0 +1,137 @@
# Gap Card — S21 · Marketplace / Extend
> Execution model: **in-place incremental refactor** of `apps/web` + targeted backend extensions.
> Mockups directional only (PRD §24). PRD acceptance criteria win over pixels.
> Every claim grounded in real files (paths + lines below).
---
## 1. Screen & purpose
**Screen 21 — Marketplace / Extend Waggle** (PRD §12.13, lines 648-662; blueprint catalog row 21, `_blueprint_extracted.txt:432-439`).
The central, power-user extension surface. PRD §10.4 names the Extend layer as **Connectors, MCPs, Models, External tools, Marketplace** — S21 is the *Marketplace* node of that layer: a single place to discover, install, update, risk-approve, and audit **extensions of six kinds** (Skills, Agents, Connectors, MCPs, Models, Templates) without "hunting through settings" (PRD §12.13 acceptance criterion). It is the funnel for the PRO upgrade trigger (skills + connectors + marketplace are gated to PRO; `05g-subsystem-skills-marketplace-wiki.md:3`).
This card scopes the **Marketplace browse/install/audit** surface specifically. The sibling Extend surfaces — Connector Hub (S? / §12.7), MCP Hub (§12.8), Skills Hub (§12.6) — are separate screens that this one cross-links to; their per-domain CRUD lives in their own cards. S21 is the unified catalog + governance view across all extension types.
---
## 2. Required states (PRD / Blueprint)
**Functional requirements (PRD §12.13):**
- Categories: **Skills, Agents, Connectors, MCPs, Models, Templates** (6 facets).
- Search / filter / sort by **category, trust, popularity, source, risk**.
- Show per-item lifecycle: **installed, update available, risk approval (required), install failed**.
- Install actions **write to install audit**.
- Support **workspace / team scoping** of installs.
**Extension lifecycle states (PRD §14.7, lines 906-914):**
`Available · Installed · Update available · Installing · Failed install · Risk approval required · Disabled/revoked`.
**Acceptance criterion (PRD §12.13):** "Power users can extend Waggle without hunting through settings." Cross-cuts to §12.8 MCP acceptance ("powerful but always visible, scoped, auditable, and reversible") and the install-audit governance theme (`_blueprint_extracted.txt:43-45,95`: install audit is the "best basis for Extend governance").
**Journeys touching S21:** J8 install connector, J9 install MCP (audit recorded), J25 marketplace update → review changelog/risk (`_blueprint_extracted.txt:203,206,252`).
**Mockup (directional):** `screens_18_21_builders_and_marketplace.png` shows S21 as a card-grid catalog with a left category rail and per-card install affordances + trust badges — consistent with the spec; not a pixel target.
---
## 3. Current state in repo
**Disposition: `rework`** (the existing surfaces are reusable substrate but neither satisfies §12.13 — the catalog is hardwired to 3 of 6 categories and there is no unified Extend view with trust/risk/popularity/scope filters).
Marketplace is **doubly represented today** (frontend.md §f flags this as an IA cleanup point):
1. **`apps/web/src/components/os/apps/MarketplaceApp.tsx`** (258 lines, fully read) — standalone browser. Two tabs (`'search' | 'installed'`, `:26`). Calls `adapter.searchMarketplace` / `getMarketplaceInstalled` / `installMarketplacePackage` / `uninstallMarketplacePackage`. Renders a flat package list with a `scanBadge` (passed/failed Shield/AlertTriangle, `:141-145`), `installed` check, type/category/source chips (`:223-227`), and 403→`waggle:tier-insufficient` UpgradeModal routing (`:108-117`). **Registered in `Desktop.tsx`** appConfig `marketplace` (`Desktop.tsx:93`) + `renderAppContent` case (`:347`), but **NO dock entry points at it** — `dock-tiers.ts:67` comment: "Marketplace already a tab inside Skills & Apps — no separate dock entry". So `MarketplaceApp` is currently reachable only via `waggle:open-app` events, effectively orphaned.
2. **`apps/web/src/components/os/apps/CapabilitiesApp.tsx`** (478 lines, fully read) — "Skills & Apps", the live Extend surface (dock key `skills` → appId `capabilities`, `dock-tiers.ts:64`). 5 tabs: `installed | starter | marketplace | tools | audit` (`:80,358`). The `marketplace` tab lists `SkillPack`s via `getMarketplacePacks`; the `audit` tab (`AuditTab`, `:15-58`) reads `GET /api/audit/installs` and renders name/source/outcome/timestamp rows. It has a pack-detail drawer (`PackDetail`, `:249-334`) with trust label + bundled-skills + install. This is *pack-oriented* (curated bundles), not the faceted *package catalog* of §12.13.
**Backend already present (more than the inventory claimed):**
- Full marketplace route family: `packages/server/src/local/routes/marketplace.ts` — `search` (FTS5 + faceted, `:56`), `packs`, `packs/:slug`, `enterprise-packs` (ENTERPRISE), `install` (PRO + SecurityGate, `:180`), `uninstall` (`:377`), `installed` (`:396`), `security-check`, `sources` GET/POST/DELETE (`:446,457,533`), `categories` (`:567` → `PACKAGE_CATEGORIES`), `sync`, `security-status`, `publish` (PRO, `:685`). Sort facet supported via `?sort=` (`:72`).
- **Install-audit READ route EXISTS** — `GET /api/audit/installs` at `packages/server/src/local/routes/skills.ts:685-703` (returns normalized `{ entries: [{ capabilityName, capabilityType, source, riskLevel, trustSource, approvalClass, action, initiator, detail }] }`). **This corrects substrate-types.md §d gap #1, which claimed "No HTTP endpoint surfaces the audit trail."** The write path is live too (`marketplace.ts:224-319` records every SecurityGate verdict; `skills.ts:212,315,475`). `adapter.getAuditInstalls` already wires it (frontend.md, adapter `Misc`).
- Install-audit store: `packages/core/src/install-audit.ts` — `AuditCapabilityType = native|skill|plugin|mcp|connector|marketplace` (`:22`), full enums for action/trust/approval/risk; read API `getRecent/getByCapability/getByAction/getAll`.
**Critical limitation (grounded):** the marketplace catalog **only supports 3 install kinds** — `InstallationType = 'skill' | 'plugin' | 'mcp'` (`packages/marketplace/src/types.ts:185`), confirmed by `05g-subsystem-skills-marketplace-wiki.md:11` ("three installable package kinds — `skill`, `plugin`, `mcp`"). PRD §12.13 demands **six categories incl. Agents, Connectors, Models, Templates**, which have **no catalog representation today** (connectors are a separate `/api/connectors` registry with only `connect`/`disconnect`; templates are `/api/workspace-templates`; agents are personas/groups; models are `/api/litellm/models` + providers). So S21's "one catalog, six categories" is the central rework: a **federated catalog read** over the existing marketplace catalog + connector registry + template store + persona/agent catalog + model list, NOT a new package table.
---
## 4. Frontend work
**Strategy:** Consolidate the two marketplace surfaces into ONE Extend/Marketplace screen, retire the orphaned standalone, and give the new screen a federated faceted catalog. Keep `CapabilitiesApp`'s Skills-pack flow as the Skills facet; promote a real dock entry.
**Components to create:**
- `apps/web/src/components/os/apps/MarketplaceApp.tsx` — **rework in place** (reuse the file/appId so Desktop wiring + tests survive). Expand from 2 tabs to the §12.13 model: a left **category rail** (Skills / Agents / Connectors / MCPs / Models / Templates / All) + a top **filter bar** (trust, popularity, source, risk dropdowns + search) + a **catalog grid**. Reuse the existing `scanBadge`, 403→UpgradeModal routing (`:108-117`), and install/uninstall handlers verbatim.
- `apps/web/src/components/os/apps/extend/ExtensionCard.tsx` (new) — one card type rendering the §14.7 lifecycle badge (Available/Installed/Update available/Installing/Failed/Risk-approval/Disabled), trust chip, risk chip, source, popularity. Props: `{ ext: Extension; onInstall; onUpdate; onRevoke; onOpenDetail }`.
- `apps/web/src/components/os/apps/extend/ExtensionDetail.tsx` (new, or generalize `CapabilitiesApp`'s `PackDetail` `:249-334`) — detail drawer with permissions/scope, changelog (for "update available", J25), risk approval CTA, install-audit trail for this item (via `getAuditInstalls` filtered client-side, or a new `?capability=` query — see §5).
- `apps/web/src/components/os/apps/extend/InstallAuditPanel.tsx` (new, or lift `CapabilitiesApp`'s `AuditTab` `:15-58`) — shared Extend governance trail; reused by S21 + Connector/MCP hubs.
- `apps/web/src/lib/extension-catalog.ts` (new pure module + co-located `.test.ts`) — client-side **federation/normalization**: merge marketplace packages (`searchMarketplace`), connectors (`getConnectors`), templates (`getWorkspaceTemplates`), personas/groups (`getPersonas`/`getAgentGroups`), models (`getModels`/`getProviders`) into one `Extension[]` with a unified `{ type: ExtensionType, trust, risk, installed, updateAvailable, source, popularity }` shape; derive lifecycle state. Keeps the fat federation logic out of the component (file-org rule: many small files).
**Reuse targets:** `MarketplaceApp` install/uninstall + 403 handler; `CapabilitiesApp` `PackCard`/`PackDetail`/`AuditTab` + `lib/skill-pack-display.ts` (`describeTrust`, `summariseSkills`) + `lib/dedupe-packs.ts`; `components/ui/*` (card/badge/tabs/input/select/tooltip); `HintTooltip`.
**Adapter methods/hooks:** existing — `searchMarketplace`, `getMarketplacePacks`, `getMarketplaceInstalled`, `installMarketplacePackage`, `uninstallMarketplacePackage`, `getAuditInstalls`, `getConnectors`, `getWorkspaceTemplates`, `getPersonas`, `getModels`, `getProviders` (all in `lib/adapter.ts`, per frontend.md §c). **New adapter methods** to add for the §16.9 gaps: `getMcps`, `installMcp`, `testMcp`, `revokeMcp`, `syncConnector`, `revokeConnector` (see §5). New hook `hooks/useExtensions.ts` wrapping `extension-catalog.ts` (catalog + filters + install/update/revoke actions + react-query caching).
**IA cleanup (frontend.md §f):** decide one home for marketplace. Recommended: keep `MarketplaceApp` as the dedicated S21 Extend surface, add a real dock entry under the `extend` zone-parent (`dock-tiers.ts:62-71`), and have `CapabilitiesApp`'s `marketplace` tab deep-link into it (or drop that tab) to remove the double representation.
---
## 5. Backend work (PRD §16.9 endpoint-by-endpoint)
| PRD §16.9 endpoint | Status | EXTEND vs NET-NEW + substrate / .mind |
|---|---|---|
| `GET /api/connectors` | **EXISTS** | `connectors.ts:6`. No change. |
| `POST /api/connectors/:id/connect` | **EXISTS** | `connectors.ts:55`. No change. |
| `POST /api/connectors/:id/sync` | **MISSING** | **NET-NEW** thin action in `connectors.ts` (re-init/re-fetch from connected service). Touches connector credential resolution (vault) + connector definition; record an audit entry (`auditStore.record`, type `connector`). No `.mind` migration. |
| `POST /api/connectors/:id/revoke` | **PARTIAL** | **EXTEND** — alias to existing `POST /api/connectors/:id/disconnect` (`connectors.ts:107`, removes vault creds + sub-keys). Same intent, add `/revoke` route delegating to disconnect + write a `revoked` audit entry. |
| `GET /api/mcps` | **PARTIAL** | **EXTEND/NET-NEW** — no `/api/mcps`. MCP catalog lives in `@waggle/shared mcp-catalog.ts`; installed MCPs surface inside `GET /api/capabilities/status` (`mcpServers[]`) and the marketplace catalog (`waggle_install_type:'mcp'`, `marketplace/src/mcp-registry.ts`). Add a dedicated `GET /api/mcps` route that joins catalog + installed-state + `.mcp.json`. Reads existing substrate; no migration. |
| `POST /api/mcps/install` | **PARTIAL** | **EXTEND** — route through the existing marketplace installer (`POST /api/marketplace/install`, which already handles `installType:'mcp'` → writes `.mcp.json`, `installer.ts:580`). Add an MCP-specific endpoint that resolves an MCP id → marketplace package → install, OR keep marketplace install as the single path and have the FE call it. Audit already recorded. |
| `POST /api/mcps/:id/test` | **MISSING** | **NET-NEW** — no MCP health/test route. Closest analog is `GET /api/connectors/:id/health` (`connectors.ts:16`). Add an MCP test route (spawn/handshake the MCP server, report ok/error). No `.mind`. |
| `POST /api/mcps/:id/revoke` | **MISSING** | **NET-NEW** — no MCP revoke-by-id. Closest: `DELETE /api/plugins/:name` (`skills.ts`). Add an MCP revoke route (remove from `.mcp.json` + record `revoked` audit). |
| `GET /api/marketplace` | **PARTIAL** | **EXTEND** — bare path = alias of `GET /api/marketplace/search` with default params (`marketplace.ts:56`). Add alias or accept both. |
| `POST /api/marketplace/install` | **EXISTS** | `marketplace.ts:180` (PRO + SecurityGate). No change. |
**Plus implied additions for §12.13 (not in §16.9's list but required by FRs):**
- **Six-category catalog.** The §12.13 categories (Agents/Models/Templates) have **no marketplace representation** (`InstallationType` is `skill|plugin|mcp` only, `types.ts:185`). Two options: (a) widen `InstallationType` + catalog schema to add `agent|model|template` (a marketplace-DB change in `packages/marketplace`, NOT a `.mind` migration — `marketplace.db` is a separate SQLite store) and seed registries; or (b) **federate at read time** (preferred for incremental scope) — the FE `extension-catalog.ts` merges marketplace (skill/plugin/mcp) + `/api/connectors` + `/api/workspace-templates` + `/api/personas`+`/api/agent-groups` + `/api/litellm/models`. Option (b) needs **no backend change** beyond §16.9; option (a) is a later phase if a true unified catalog with publish/install for all 6 kinds is wanted.
- **Install-audit read for Extend governance.** **EXISTS** — `GET /api/audit/installs` (`skills.ts:685`). (Substrate inventory §d#1 said missing; it is present.) **Optional EXTEND:** add a `?capability=` / `?type=` filter param so the detail drawer can show per-item history without client-side filtering (currently only `?limit=`). The store already has `getByCapability()` (`install-audit.ts:125`) — just expose it.
- **Workspace/team scoping of installs (§12.13).** No per-workspace install scoping exists today (installs are global to `~/.waggle/`). This is net-new product surface; recommend deferring to Phase 4 polish (PRD §22 risk register flags "marketplace scope creep" — `PRD:1435` — "Start with catalog + install audit, postpone billing/public marketplace").
**`.mind` migration flag:** none required for S21. The audit table (`install_audit`) already exists in both DDL sites (`install-audit.ts:54` + `schema.ts:119`). **Latent bug to flag (substrate-types §d#2):** `AuditRiskLevel` TS includes `'critical'` (`install-audit.ts:16`) but both DDL CHECKs only allow `('low','medium','high')` (`install-audit.ts:65`, `schema.ts:130`) — a `record({riskLevel:'critical'})` throws. The marketplace route sidesteps it (maps CRITICAL→`high`+`blocked`, `marketplace.ts:228`). If S21 surfaces a true "critical risk approval" state that writes `critical`, this CHECK must be widened first (idempotent ADD/relax via the migration runner's ADD-COLUMN pattern, `mind/db.ts:116`).
---
## 6. Shared types needed (PRD §15 vs `lib/types.ts`)
- **`ExtensionType`** (PRD §15.2, line 953: `'skill' | 'connector' | 'mcp' | 'model' | 'template' | 'external_tool'`) — **MISSING** from `apps/web/src/lib/types.ts` (substrate-types §e). Add. Note PRD union has `external_tool` but §12.13 categories say "Agents" not "external_tool" — **reconcile**: §12.13 needs an `'agent'` category; PRD §15.2 `ExtensionType` lacks `agent` and adds `external_tool`. Flag as open question; likely the union should be `skill|agent|connector|mcp|model|template` (+ optional `external_tool`).
- **`Extension` interface** (new) — `{ id, name, description, type: ExtensionType, trust: AuditTrustSource-ish, risk: AuditRiskLevel, source, popularity?, version?, installed, updateAvailable, lifecycle: 'available'|'installed'|'update_available'|'installing'|'failed'|'risk_approval'|'disabled', scope?: Scope }`. No PRD §15 interface spells this out; derive from §12.13 + §14.7.
- **`Scope`** (PRD §15.2: `'personal'|'workspace'|'team'|'organization'`) — **MISSING**, needed for install scoping; add (shared with other Extend/Memory cards).
- Existing FE `MarketplacePackage` (local interface in `MarketplaceApp.tsx:8-18`) and `SkillPack` (`types.ts`) are narrower than `Extension`; `extension-catalog.ts` normalizes both into `Extension`.
- Reuse the canonical audit enums (`AuditTrustSource`, `AuditRiskLevel`, `AuditCapabilityType` from `packages/core/src/install-audit.ts:16-22`) rather than re-declaring trust/risk literals in the FE — export them or mirror minimally.
---
## 7. Dependencies (screens / phases first)
- **PRD phasing:** Extend layer = **Phase 4 / Sprint 7** (`PRD:241-245,1353-1357`). Comes after Work (Home/Workspace), Intelligence (Agents/Skills), so S21 should land in that phase.
- **Depends on / cross-links:**
- Connector Hub (§12.7) and MCP Hub (§12.8) screens — S21 federates their catalogs and shares the `InstallAuditPanel`; their `/sync`/`/revoke`/`/test` backend routes (§5) are shared deliverables.
- Skills Hub (§12.6) — S21's Skills facet reuses `CapabilitiesApp`'s pack flow.
- Agent Center (§12.9), Models (Settings→Models), Templates (workspace-templates) — needed as catalog sources for the 6-category federation.
- Dock IA refactor (`dock-tiers.ts` Extend zone) — S21 needs a real dock entry (currently none).
- UpgradeModal / tier gating (`waggle:tier-insufficient` event) — already wired; reuse.
- **Blocks:** nothing downstream; it is a leaf surface.
---
## 8. Effort
**L.** The frontend rework is moderate (consolidate 2 surfaces → 1 faceted catalog + extract shared `ExtensionCard`/`InstallAuditPanel` + new `extension-catalog.ts` federation). What pushes it to L: the **6-category federation** spans five different backend domains (marketplace, connectors, templates, personas/agents, models) each with a different shape, plus **6 net-new/extend §16.9 routes** (connector sync/revoke, mcps list/install/test/revoke) and the FE/BE type reconciliation. Not XL because no `.mind` migration, no new data store (federate-at-read), audit read route already exists, and install/uninstall + tier-gating + audit-trail plumbing are all already live.
---
## 9. Open questions
1. **`ExtensionType` reconciliation.** PRD §12.13 categories = Skills/Agents/Connectors/MCPs/Models/Templates (6, incl. **Agents**). PRD §15.2 `ExtensionType` = skill/connector/mcp/model/template/**external_tool** (6, incl. external_tool, **no agent**). Which is canonical — add `agent`, keep `external_tool`, or both (7)?
2. **Federate-at-read vs unified catalog table.** Ship S21 by federating existing domains client-side (no marketplace-DB change, fast), or invest in widening `InstallationType` + `marketplace.db` to natively catalog all 6 kinds (enables publish/install/version-tracking parity for agents/models/templates)? Recommend federate-first; revisit per §22 "postpone public marketplace".
3. **Install scoping (§12.13 "workspace/team scoping").** Installs are global to `~/.waggle/` today. Is per-workspace/per-team install scoping in scope for Phase 4, or deferred (it implies new persisted scope state on every installed capability)?
4. **"Update available" + changelog (J25).** No version/changelog tracking exists for installed packages beyond a `version` column on the marketplace package. Where does the "update available" signal come from — catalog sync diffing installed version vs latest, or a new field?
5. **MCP test semantics.** `POST /api/mcps/:id/test` — does "test" mean spawn-and-handshake the MCP server (live), or static manifest/permission validation? Affects whether it can run without launching a process.
6. **Should `MarketplaceApp` or `CapabilitiesApp` be the canonical S21 home** (IA double-representation, frontend.md §f)? Recommend `MarketplaceApp` reworked + real dock entry; `CapabilitiesApp` keeps Skills/Tools/Audit and drops its `marketplace` tab.

869
docs/ux-refactor/gold-standard-plan-2026-07-06.md Normal file
View File

@@ -0,0 +1,869 @@
# UX Gold-Standard Polish — Mission Plan (2026-07-06)
**Founder goal:** Polish Waggle OS UX to gold standard incl. images + icons; full rich
experience in **dark AND light**; beat Claude / ChatGPT / Codex / Hermes / Odyssey on UX.
Scope explicitly includes **onboarding** and the **landing site** (`apps/www`).
Use **nano-banana** (Gemini image gen; key in `~/.nano-banana/.env`) for imagery/icons.
**Done when 5 persona judges each grade ≥ 9/10** (in both themes).
## Starting state (verified 2026-07-06)
Functional UX bugs cleared across waves through 2026-07-05. Design system is production-grade:
"Warm-Hive / Hive DS", ~140 tokens, dark(default)+light(`:root[data-theme=light]`) near-parity
with a WCAG-AA guard test. Icons: lucide-react (155 files) + simple-icons (brands). Motion:
framer-motion + rich CSS keyframes. Type: Hanken Grotesk + JetBrains Mono, scale tops at 24px.
**The gap is imagery + refinement, not the token system.**
## The 5 Judge Personas (rubric — score /10 each, need all ≥9)
1. **Design Director** (ex-Apple/Linear) — visual craft: type hierarchy, spacing rhythm,
elevation, color vibrancy, motion, cohesion. "Would this win a design award?"
2. **Skeptical Knowledge Worker** (target: busy PM/consultant) — clarity, ease, first-run
comprehension, trust. "Would I switch from ChatGPT/Claude?"
3. **Competitor-Benchmark Critic** — explicit head-to-head vs Claude/ChatGPT/Codex/Hermes/
Odyssey. Scores RELATIVE to them.
4. **Accessibility & Theme-Parity Auditor** — contrast, both themes equally polished, focus
states, readability, WCAG AA.
5. **Brand / Emotional-Resonance Judge** — does "Warm-Hive" land? imagery cohesive + NON-generic
(anti-AI-slop)? memorability, delight.
Each judge returns: overall /10, per-surface notes, top-5 concrete fixes ranked by impact.
## Phases
- **P0 Baseline** — capture every surface dark+light (in progress) → 5-judge baseline scores +
prioritized critique. Establishes the gap.
- **P1 Assets (nano-banana)** — cohesive Warm-Hive imagery where it genuinely elevates:
- Complete the **22 persona avatars** (14 new; base template in `assets/personas/README.md`).
- **Empty-state spot illustrations** (flat honey-hex, transparent): marketplace, memory,
files, agents, artifacts, connectors, chat-first-run.
- **Onboarding** welcome/ready hero art.
- **Landing** hero + feature imagery + OG (as gaps found).
- Chrome stays crisp SVG/CSS (anti-slop) — raster only where it adds warmth.
- **P2 Icon hygiene** — replace ~18 stopgap emoji (NotificationInbox, Timeline/Harvest frame
types, ModelSelector, agent-avatar fallback) with lucide/custom SVG.
- **P3 Refinement** — add a display type tier for hero moments; richer elevation/gradient
application; light-mode honey vibrancy; motion polish; theme-parity fixes.
- **P4 Re-judge loop** — iterate until all 5 judges ≥9 in both themes.
## Asset generation — 14 new persona avatars (unique per persona)
Owners keep existing sprite; NEW avatars for the 14 sharers. Base template from README,
substitute [ACTION]. Distinct props:
consultant, project-manager, product-manager-senior, ops-manager, verifier,
executive-assistant, hr-manager, support-agent, marketer, creative-director,
legal-professional, finance-owner, data-engineer, recruiter.
## Constraints
- Surgical edits; match existing style; commit per phase; DO NOT push without founder OK.
- Substrate (`hive-mind-core`) off-limits (§7.5). This is a UI/asset arc.
- Gates each phase: `npm run typecheck:web`, `npm run test -- --run` (web), lint.
---
## Progress log (2026-07-06)
**Baseline 5-judge scores:** design 7 · knowledge-worker 7 · competitor 6.5 ·
a11y/parity 6.5 · brand 6.5 (min 6.5, avg 6.7). Consensus: strong ownable
identity, loses on consistency + a broken light onboarding + muddy light CTAs.
**Shipped (branch `feat/ux-gold-standard-2026-07-06`):**
- `d70002d7` — 22 unique persona avatars (nano-banana; was 8 shared across 22).
- `e20ff620` — Wave A: onboarding light scrim (was hard black) + honey token
decouple (light `--primary` vibrant #e5a512 for fills; new `--honey-text`
#9a6408 light / #e9a52c dark for text → 348 `text-primary`→`text-honey`).
- `3a8513ba` — Wave B: workspace shelf hides dev-noise (worst frame); plural
fixes; calm 'Trial ended' pill.
- `cb5dbf2b` — Wave C: lighter first-run backdrop + capped I-remember; light
honeycomb 0.06→0.10; settings warning via AA `--status-warning`.
- Landing (`apps/www`) rebuild: in-flight (subagent) — void sections, Meet-the-
hive bee grid, de-dup hero.
**Verified live:** onboarding light fixed (ivory + vibrant CTA); shelf clean.
Gates green each wave (web tsc 0, vitest 1339). Next: re-capture all + re-judge.
**Waves D+E (2026-07-06, later):**
- `6ecdb7bd` — Wave D: landing "Meet the hive" per-persona accents + reveal fix
(apps/www; the baseline "voids"/"duplicate hero" were fullPage-capture
artifacts — real DOM verified single-hero, all sections populated). ENV: a
corrupted `.next` cache 500'd the landing — cleared + restarted (port 3003).
- `a8ba9877` — Wave E: emoji→lucide across chrome (NotificationInbox, Timeline
×3 sites, Harvest, ModelSelector speed glyphs, UserProfile verbosity,
onboarding language pill). Agent avatars (user-choosable emoji) untouched.
- Round-2 re-capture done WITH backend live (first pass caught the sidecar
dead — restarted; offline shots would have judged the outage, not the UX).
Note: LoginBriefing modal no longer fires on /home (away-briefing renders
inline in the feed); stale offline shot removed from the judge set.
- Round-2 5-judge scoring: IN FLIGHT (wf_60dd30c2).
**Round-2 judging incident + long-tail fixes:**
- First round-2 workflow run judged the WRONG dir — Workflow `args` arrived
JSON-stringified, `args.dir` was undefined, script fell back to the baseline
default. Caught via `"dir"` in the result; script now parses args defensively
+ defaults to the round-2 dir. Silver lining: an independent 2nd baseline
read (avg 6.74 ≈ 6.7) confirms judge stability. Corrected run: in flight.
- `4841a4b2` — session-id never renders as a conversation title (chat briefing).
- `cb1b4669` — model-label heuristic: version digits re-join with dot
("Claude Opus 4.6" not "4 6"); regression-tested.
- `cc1c7abc` — Memory eyebrow: internal strategy line ("the thing that makes
you stay") replaced with user-facing verbs.
- Real chat THREAD captured (33-chat-thread-dark) — renders competitively
(bee avatar, persona+model attribution, structured markdown, 👍/👎).
**Round-2 verdict + Waves F/G (2026-07-06 late):**
- Round-2 CORRECTED scores: design 7 · kw 7 · competitor 7 · a11y 6.5 · brand 7
(min 6.5, avg 6.9; baseline 6.7). Onboarding-light fix + landing confirmed;
new convergent list: logo fork per theme, texture-through-content (dark),
workspace cards "mostly air", home marketing-copy-to-returning-user, memory
CONF dial + dupes, provider-chip checkmarks, landing carousel empty cells /
nav occlusion / pricing dead column, light micro-label AA.
- `32161b95` Wave G: ONE bee mark both themes (nano-banana regen of the dark
logo for ivory — replaces the unrelated W-wings png); SuggestedAgentCards +
ExtensionCard opaque (ghost-rectangle glitch); dark overlay 0.2→0.45.
- `0676eb38` Wave G2: light --text-dim/--text-muted/--muted-foreground → AA
(4.7:1 / 5.4:1); one-token fix across all light micro-labels.
- `f7f95fcd` Wave F-landing (subagent, gated): carousel never hollow (eager
next/image + masked fillers + vignette), [id] scroll-margin, KVARK third
card + trial-line move, feature-grid hover. www tsc 0 + next build + 10/10.
- `4386aa59` Wave G3: marketplace BrandTile identity tiles + humanized slugs.
- Wave F-app (workspace cards / home digest / CONF dial / provider chips):
subagent IN FLIGHT.
- Session-limit incident: first Wave F pair died on the API session cap
(resets 4:50am); relaunched clean after /login — no partial writes.
**Wave F complete + round-3 prep:**
- `9041d5a5` Wave F-app (subagent, reviewed + committed): workspace cards
whole-card target + real meta row (server list rows now carry a cheap
sessionCount readdir — NO memoryCount by design, MultiMindCache hazard);
Home factual delta line for returning users (marketing copy = day-0 only);
bell badge unclipped; ConfidenceRing NN%/'unscored' (no empty dial); Trust
list through shared dedup ×N; provider-chips finding = dev-vault false
positive (verified correct). +2 pre-existing test-mock completions.
Gates: web tsc 0 · server tsc 0 · vitest 1340/1340.
- Landing hive verified post-cache-restart (:3004): headline clears nav,
eager mascots, no hollow cells. NOTE: `.next` dev-cache corrupted TWICE
this session (Cannot find module './104.js' / ENOENT _document) — remedy:
kill dev server, rm -rf apps/www/.next, restart. `next build` is the gate.
- Sidecar restarted (tsx no-watch) to serve the sessionCount route.
- Round-3 capture agent in flight → judge round 3.
**Round 3 (in flight):**
- `003cf945` Overview no longer repeats the summary's quoted memory.
- Round-3 spot-check (own eyes): home factual hero ✓ (marketing copy gone),
workspace cards meta rows ✓ (sessionCount live from server), marketplace
brand tiles + humanized names ✓, memory-light AA + 'unscored' + ×9 dedup ✓,
eyebrow 'TRUST · INSPECT · CORRECT · FORGET' ✓.
- Round-3 5-judge scoring: wf_156837cb IN FLIGHT.
- Remaining known deferrals (founder/IA decisions, NOT blocking work items):
memory 8→3 tab collapse · marketplace search+NL input merge · chat session
title humanization (display guard shipped; server naming is product) ·
dev-data duplicate workspace names (data, not UI).
**Round 3 verdict + Wave H (2026-07-06 early morning):**
- Round-3 scores: design 7.3 · kw 7.4 · competitor 7.0 · a11y 7.2 · brand 7.3
(min 7.0, avg 7.24; trajectory 6.7 → 6.9 → 7.24).
- `9d6867a4` Wave H0: BOTH wallpapers regenerated (nano-banana) — lattice
edge-weighted, centers calm, light retires the swoosh for the same hex
language; dark overlay 0.45→0.3; ~10× smaller assets.
- `b84a12ad` Wave H (3 parallel workstreams, combined gate 1340/1340 + tsc 0):
chat chrome 6→3 layers (dup breadcrumb deleted, Agent Profile merged,
header subtitle hidden on Chat) · memory tabs → Trust/Memories/Timeline/
Graph/Advanced▾ with plain-language names + manifesto compact-after-first-
visit + Forgotten chip contrast · Model Pilot de-salad (neutral rows, 3px
role rails honey/clay/moss, neutral $ glyphs, single amber banner) ·
agents suggested grid full-width with 48px bees + why-lines · workspaces
lg-3col + HexAvatar 5-tone warm hash · overnight chips dedup ·
marketplace ONE smart input (filter on keystroke, NL on Enter).
- Round-4 capture in flight → judge round 4.
**Wave H tail + round 4 (2026-07-06 ~05:00):**
- `eff4db9b` 'Trial ended · Solo' pill → actionable (opens /settings?tab=billing).
- `a8c0eae7` all 13 landing bee mascots background-transparent (corner
flood-fill, interior line art preserved) — kills the pasted-black-square
seam without regenerating art.
- Round-4 spot-check: chat chrome 3-layer ✓ · memory Trust/Memories/Timeline/
Graph/Advanced▾ + compact hero ✓ · Model Pilot neutral rows + rails (light
warm) ✓ · agents full-width bee grid on calm canvas ✓.
- Round-4 5-judge scoring: wf_8a0b87a5 IN FLIGHT.
**Round 4 verdict + Wave I (2026-07-06 ~05:45):**
- Round-4 scores: design 7.4 · kw 7.5 · competitor 7.5 · a11y 7.3 · brand 7.5
(min 7.3, avg 7.44; trajectory 6.7 → 6.9 → 7.24 → 7.44).
- `1162987c` landing: vignette+masks removed (compensators for the old
opaque PNGs read as dark boxes behind the now-transparent bees) — seam
finally dead, verified live.
- `8c292ad1` Wave I (3 parallel workstreams, gate 1343/1343 + tsc 0):
chat 760px measure + persona-bee avatars + Default:-labeled top-bar chip +
enabled send state · home scoped review banner + real failure rows +
dup-card tags · memory deterministic hero + inlined segmented control +
12px AA provenance · marketplace Start-here band + one action weight +
neutral Not-scanned + brand-alias fix (namespaced ids) · Model Pilot
copper/sand rails · agents 22-bee roster strip + 'no runs yet' ·
onboarding scrim hive texture · transparent scrollbar tracks.
- ENV: apps/www .next webpack cache corrupted a 3rd time (dev-serve during
live edits); clean-restart recipe reaffirmed; port now :3005.
- Round-5 capture in flight → judge round 5.
---
## Round 5 + Wave J + ARC SYNTHESIS (2026-07-06 ~06:30)
**Round-5 scores:** design 7.7 · kw 7.2 · competitor 7.3 · a11y 7.3 · brand 7.3
(min 7.2, avg 7.36). **Trajectory: 6.7 → 6.9 → 7.24 → 7.44 → 7.36 — the curve
has PLATEAUED at ~7.4** (baseline was measured twice at 6.7/6.74, so inter-round
judge noise is ±0.2; rounds 4 and 5 are statistically identical).
**Wave J (final surgical residuals):** greeting trailing colon dropped server-
side (all 5 variants + test fixtures) · bell badge warm-family + ring (no more
alarm-red clash/overlap) · 25 `text-[var(--honey)]` link sites → AA
`--honey-text` (fixes 'Start a swarm'/link washout in light) · memory rows lead
with a bold title line + muted 2-line excerpt (no more log-output walls) ·
chat measure 760→680px (~72ch).
### Why the static-screenshot judge panel saturates near 7.4
1. **Motion & feel are invisible** — judges repeatedly withhold 8-9 for
"cinematic delight/signature motion", which screenshots cannot show. The
framer-motion system exists but can't be scored this way.
2. **Dev-data pollution costs points every round** — 5× "Research Hub" dupes,
"Blank Workspace" ×2, BENCH-SECRET/benchmark memories, an all-13-keys dev
vault (makes provider checks look meaningless). These are DATA, not UI;
archived/clean demo data or a seeded demo profile would lift every surface.
3. **Convergence exhausted** — rounds 1-4 fixes were convergent (3-5 judges
agreeing); round-5 lists are disjoint small-bore nits + re-raises of
already-verified items (provider checks = real dev vault; light CTA fill
was re-tuned twice) + judge-to-judge disagreement (760px measure "good" for
one judge, "90ch too long" for another).
4. **The rest is structural/product work**: marketplace featured/categories
merchandising depth · chat composer affordances (attachments/slash/voice) ·
landing light variant · memory deep IA beyond display-level regroup ·
workspace cards need real usage data to be "rich".
### What would actually reach the 9-bar (recommendation)
- **One signature motion moment** (memory "folding into the hive" on save;
honey streaming pulse in chat) — repeatedly requested by the brand judge.
- **A seeded demo profile** (clean workspaces with descriptions, real-looking
memories, one provider key) for demos/audits — biggest cheap lift.
- **Live-product judging** (video walkthrough or hands-on) instead of static
screenshots once motion ships.
- The structural items above as scoped arcs, not polish waves.
**Goal amended (founder, 2026-07-06 ~07:00): synthesis items now in scope.**
- Wave L (data): 53 dev-artifact workspaces ARCHIVED via local API (reversible
status flip; auth via the auth-exempt /api/auth/session-token bootstrap) —
45 ai-os-audit/flow + 2 e2e + 2 stresstest + research-hub-3/4/5 +
blank-workspace-2. Shelf now shows 6 real workspaces. research-hub-2 KEPT
(5 sessions = plausibly real work).
- `2be2ac9c` Wave K (signature motion, reduced-motion guarded): brain-trophy
'+N ⬡' memory-fold on real count increases · streaming bee breathes ·
onboarding glow-breathe. Verified live (computed animationName).
- `7beacbe0` Wave M: marketplace All shelf grouped by type with counts.
- Judge brief now carries a code-verified MOTION INVENTORY as secondary
signal (statics can't show it; honest disclosure, judges may discount).
- Round-6 capture in flight → judge round 6.
**Round 6 verdict + Wave N (2026-07-06 ~08:30):**
- Round-6 scores: design 7.7 · kw 7.7 · competitor 7.5 · a11y 7.8 · brand 7.8
(min 7.5, avg 7.7) — PLATEAU BROKEN (+0.34 avg over R4-5's ~7.4). Trajectory:
6.7 → 6.9 → 7.24 → 7.44 → 7.36 → 7.7.
- `478b0ac2` shelf hides archived behind an 'Archived (N)' disclosure (grid
was rendering archived rows — surfaced by the recapture).
- `d3d769ba` Wave N (N1 chrome lane + N2 chat + N3 truth + N4 marketplace/
landing; combined gate web tsc 0 · www tsc 0 · vitest 1343/1343): chat at
2 chrome bars w/ composer agent strip + hover Copy/real-Retry + honey user
bubble · bell count beside the glyph (overlap occluded the 14px bell —
cropped-crop diagnosis) · dark --text-dim AA bump · onboarding radial focal
fade + single-halo Continue · HexAvatar honey-band ramp + Created-line +
#id collision chip · memory md-stripped previews + 'to review' button-chip
+ unscored quiet chip · ModelGate disabled-state + failing-provider glyph ·
marketplace 860px column + human source-form chips + connected warmth ·
landing scrollbar + warm persona ramp · 8 BENCHMARK anchors deleted (API).
- Round-7 capture in flight → judge round 7.
**Round 7 verdict + Wave O (2026-07-06 ~09:30):**
- Round-7 scores: design 7.5 · kw 7.6 · competitor 7.8 · a11y **8.0** (first 8!)
· brand 7.5 (min 7.5, avg 7.68 — level with R6; composition improved).
Trajectory: 6.7 → 6.9 → 7.24 → 7.44 → 7.36 → 7.7 → 7.68.
- New #1s are structural: ELEVATION SYSTEM (all cards flat 1px hairline) +
CHIP TAXONOMY (5 pill styles in one viewport). Plus a 4/5 HIGH: home hero
self-contradiction ('away 1 day' vs 'last active 2d ago').
- Wave O in flight: O1 (home one-truth clause, composer chip grammar +
cropped-icons fix, memory title humanization, review-debt reframe) ·
O2 (shadow-token elevation sweep, full-slug collision chips, agents 6
suggestions + KPI relocation + meta legibility, provider chip state trio +
single alert, statusbar text bumps) · my lane DONE: unconditional
scrollbar-color (kills the recurring native-thumb artifact), light scrim
hex 0.04, landing filler fade completion, hero LoCoMo proof strip
(86.49 — canonical number only).
**Round 8 verdict (2026-07-06 ~10:30) — SESSION CLOSE:**
- Round-8: design **8.0** (home 8.5 · memory 8.3 · hero 8.5 · chat 8.0 ·
agents 8.0) · kw 7.5 · competitor 7.5 · a11y 7.4 · brand 7.5
(min 7.4, avg 7.58).
- Full trajectory: 6.7 → 6.9 → 7.24 → 7.44 → 7.36 → 7.7 → 7.68 → 7.58.
**Second plateau ~7.6-7.7.** Convergent queue emptied 3× (R4/R5/R7); R8
asks = 3 surface redesigns + regime artifacts (autoFocus CTA ring reads as
'stuck focus' in every capture; headless overlay scrollbars).
- Straggler BENCHMARK frame (id 529) deleted.
- QUEUED NEXT ARC: settings provider-selector redesign (6.8, worst) ·
workspace card anatomy v3 (7.0) · home card-system unification ·
judging-regime switch to video/live · founder branch review (29 commits,
NOT pushed).
---
## S2 — Wave P + mascot fix + R9 (2026-07-06 ~15:45, goal re-armed: 5×9/10)
**Wave P (`3fa98f81`) — the three queued structural redesigns, executed as 3
parallel Opus lanes** (spec: `wave-P-spec-2026-07-06.md`):
- Settings/ModelGate: pill row → filled provider TILE grid (keyed=honey-wash /
failing=risk-wash+glyph / unkeyed=quiet outline; ring on selected;
"Your providers"/"Add a provider" grouping) · Show density control anchored
to the rail foot (a11y: radiogroup no longer nested in tablist) · Models tab
de-duplicated (provider row-list removed — the tile grid is the one truth) ·
failing banner unified on --risk with the tile (was yellow-500).
- Workspaces: card v3 — flex-col + mt-auto footer on ONE baseline, honest
"Created X · active Y" activity line (verified: list rows carry NO summary
field), hover "Open →" affordance, min-h 132 (168 opened a dead band).
- Home: 3-tier card grammar — heroes r-xl + shadow-elevated + one eyebrow
anatomy (StartHere keeps honey border+gradient identity, drops shadow-honey);
tier-2 cards r-lg + shadow-card; tier-3 rows 14px flat.
- Gates: web tsc 0 · vitest 1355/1355. (One self-inflicted JSX-comment-in-
ternary broke vite mid-session — caught by browser QA + suite, fixed.)
**Mascots (`1fbb9cc2`):** Writer + Night Shift landing bees were rendered-
cartoon outliers → regenerated in the house flat-geometric style (nano-banana
pro + style refs), then DETERMINISTIC palette correction (measured refs at
~40° golden vs generations at ~30° orange → PIL hue shift + white→cream +
halo rim cleanup). Verified in-grid on :3005.
**Capture-regime fixes (live in R9 set):** activeElement.blur() before every
shot (kills the phantom "stuck focus" ring) + scrollbar-hide style (headless
overlay-thumb artifact) — both disclosed to judges as capture notes; 2 NEW
interaction-state shots (140 card-hover, 141 provider-tile-selected).
**Data hygiene:** 3 more BENCHMARK frames deleted via API (530, 501, 283 —
the q=BENCHMARK sweep missed prefix variants). ⚠ id 530 appeared AFTER 529's
deletion — something (likely the concurrent BEAM-benchmark session touching
benchmarks/ + hive-mind-* in this same worktree, uncommitted as of 15:45) is
re-inserting bench frames; recheck before any future capture.
**R9 judging in flight** (5-persona panel, wf_6ee59488-f11).
**Round 9 verdict + Wave Q (2026-07-06 ~16:00-16:45):**
- R9: design 7.7 · kw 7.4 · competitor 7.5 · a11y 7.6 · brand 7.4 (min 7.4,
avg 7.52) — statistically flat, BUT the home capture accidentally recorded a
REAL degraded boot (NoModelBanner + error glyph + "Catching you up" modal,
sidecar hiccup under concurrent-BEAM load) → all 5 judges made the
interruption stack their #1 ask; home-briefing-modal scored 6.5 (new worst).
R9's home number is not comparable to R8's clean 8.5.
- Wave Q (`1dc07a0f`, 4 Opus lanes): one-voice failure states (briefing error
= slim dismissible row, never a blocking modal; offline suppresses briefing;
modal recomposed opaque/one-grid) · provider tiles rest NEUTRAL (honey =
selection only, risk = error only; real segmented Show control; light
tablist cells; quiet-outline Validate) · memory humanizeMemoryTitle (slug →
meta chip) + one headline count + quiet zero chips + violet folded ·
status-bar chip scoped "New chats:" (relabel had to be re-applied by hand —
Lane D's claim didn't survive its own formatter) · solo self-presence 'Y'
chip dropped · theme-aware --user-bubble · trial pill → quiet "Solo plan" ·
light --honey #b57d12→#c07f00 (full-sat, AA 5.47/3.18).
- `fd6b0980`: ALL 22 persona avatars redrawn flat-geometric (4/5 judges:
"two mascot languages") — nano-banana pro + style refs + deterministic
hue-correction 30°→40°; personas.ts imports 1:1 by id. Landing Writer +
Night Shift mascots fixed earlier (`1fbb9cc2`).
- Gates: web tsc 0 · vitest 1362/1362.
- R10 capture: home CLEAN (modal dismissed; healthy content modal captured
separately as 142) · settings back at Essential tier · label-consistent
set (130-132 recaptured after the StatusBar relabel). Judging in flight.
**Round 10 verdict (2026-07-06 ~17:05):**
- R10: design 7.8 · kw 7.7 · competitor 7.6 · a11y 7.6 · brand 7.5
(**min 7.5 — new high** · avg 7.64). Trajectory: 6.7 → 6.9 → 7.24 → 7.44 →
7.36 → 7.7 → 7.68 → 7.58 → 7.52 → 7.64. Wave Q verdicts landed: home 8.4
("out-crafts Claude and ChatGPT"), memory 8.5, agents mascots "award-grade
brand asset", landing 8.6/8.4.
- NEW BUG the panel caught: settings 6.6 — shot 141 shows a browser-default
BLUE focus ring on the Anthropic tile beside OpenAI's honey selected border
(a `ring` utility missing its color token) — all 5 judges flagged it.
- Wave R launched (5 Opus lanes, wf_ab570c2d-953): A settings ring grammar +
Show re-home to content header + $$$ legend · B workspace card living
identity INCLUDING server list-row enrichment (memoryCount + last-session
line — the data blocker judges have hit 3 rounds running) · C marketplace
craft (chip grammar, submit affordance, warm Connected, START-HERE
re-curation) · D chrome truth (memory-count scope label, composer control
family, light elevation + light --attention AA, dark chip legibility, hex
wallpaper radial falloff) · E brand moments (mascots on onboarding/briefing/
chat-empty, memory stat order, landing LoCoMo flagship stat).
**Round 11 verdict (2026-07-06 ~18:05):**
- R11: design 7.5 · kw 7.8 · competitor 7.8 · a11y 7.8 · brand 7.8
(**avg 7.74 — best yet**; min 7.5 held by the design director alone; the
other FOUR judges posted their highest scores of the whole arc).
Trajectory: 6.7 → 6.9 → 7.24 → 7.44 → 7.36 → 7.7 → 7.68 → 7.58 → 7.52 →
7.64 → 7.74.
- Design director's thesis (the clearest roadmap of the arc): "The gap to
9/10 is not another hero — it's craft parity on the boring surfaces:
workspace card v3, the provider selector, one unified chip grammar, and
asset-level consistency (no platform emoji anywhere)."
- Wave R verdicts: landing 8.5 · home 8.0 · briefing modal 7.8 (was 6.5) ·
blue ring GONE (error+selected states called "excellent") · workspace
cards still the floor (6.8 — "Last:" prefix read as debris; bar keeps
rising: now they want fixed slots + a live signal per card).
---
## Round 12 verdict + PLATEAU ANALYSIS #2 — founder decision point (2026-07-06 ~19:00)
**R12: design 7.6 · kw 7.6 · competitor 7.7 · a11y 7.5 · brand 7.8 (min 7.5,
avg 7.64).** Full trajectory:
6.7 → 6.9 → 7.24 → 7.44 → 7.36 → 7.7 → 7.68 → 7.58 → 7.52 → 7.64 → 7.74 → 7.64.
### The measurement is now conclusive
R6-R12 = seven rounds oscillating in a **±0.1 band around ~7.65**, through FOUR
executed convergent waves (P/Q/R/S — every #1 ask of every round shipped and
verified fixed the following round: provider tiles, one-voice failure states,
blue-ring root cause, server-enriched living cards, logomarks, chip grammar,
emoji purge, light AA passes). Surfaces judged 8+ when captured clean: memory
8.4-8.5 · landing 8.4-8.6 · home 8.4 · onboarding 8.2 · chat 8.0. The panel's
own verdicts converge on one sentence: **beats Codex/Hermes/Odyssey outright on
identity and coherence; Claude/ChatGPT keep a micro-refinement edge on the
boring surfaces.**
### Why 5×9/10 is not reachable under THIS regime (evidence, not excuse)
1. **Whack-a-mole is measured**: each round's fixes verify green, and new
equal-weight nits appear (R10 asked Show→content-header; R11 called that
"floating"; R12 wants it "a contained segmented control"). Cross-round judge
self-disagreement is now documented in three consecutive rounds.
2. **The rubric pins the ceiling**: judges are instructed "9 = clearly
best-in-class, do NOT be generous" — under min-of-5 with ±0.2 per-judge
noise, a ~7.5 floor is the stable fixed point once real defects are gone.
3. **Static shots can't see the product's strongest layer**: motion, hover
tiers, streaming, transitions — the panel repeatedly withholds 8-9 for
"feel" that screenshots structurally cannot show (motion inventory
disclosure only partially compensates).
4. **Capture fragility costs real points**: two of the last four rounds lost
home points to TRANSIENT states caught mid-capture (R9 triple stack, R12
error-toast collision — the collision itself was a real Wave-Q defect, now
fixed: toast docked bottom-right).
### Decision needed (founder)
- **A. Accept & merge** — take the arc's result (6.7 → ~7.7 sustained, four
judges at 7.8, five surfaces at 8+; ~45 local commits, all gates green) and
merge `feat/ux-gold-standard-2026-07-06` after review. Remaining R12 nits
can ride normal polish waves on main.
- **B. Regime switch** — video/live walkthrough judging (shows motion, hover,
streaming). Requires new capture tooling (screen recording); scores would
not be comparable to the static trajectory. This is the only honest path
that could still move the number materially.
- **C. Continue static waves** — the data above says expected value per wave
is now ≈0 (±0.1 noise); not recommended.
### R12 asks banked for whatever comes next (all legitimate, none gate-moving)
marketplace metadata budget (dedupe connector chips, cap tags at 3+N) ·
workspace one-slot-order grammar + duplicate-chip → tooltip · real hover tier
(elevation+actions) across cards · memory triple-nav collapse · Show control
containment · dark agents search-input border · light input borders + mono-chip
contrast · landing diagram line weight + orphaned arrow.
---
## REGIME B — video/interaction judging (founder re-armed the goal 2026-07-06 S3)
Founder directive: continue to 5×9/10. Static waves measured EV≈0 → regime switch
executed (option B). Evidence: 9 Playwright-recorded user journeys (real app, real
data, human-cadence input), ffmpeg-decomposed to 2fps contact sheets + keyframes.
Tooling: scratchpad/{video-journey.mjs, make-filmstrips.py, judge-workflow-video.mjs}.
Scores NOT comparable to the static R1-R12 trajectory.
## Round 13-V1 verdict (video-regime BASELINE, product @ 74f95c73)
**design 7.0 · kw 7.1 · competitor 7.0 · a11y 7.0 · brand 7.3 — min 7.0, avg 7.08.**
Panel converges on five systemic gaps (each named by 4-5 of 5 judges):
1. **Interaction hygiene / state honesty**: returning-user boot flashes the wizard
(~1s); briefing modal = bare spinner ~4s with a blank region while cards stream;
memory hero renders a false "0 Memories in this hive" for ~3s on a TRUST surface
and re-spins on every tab switch (no cache).
2. **Hover tier is uneven**: workspace cards = best-in-app (honey hairline + Open→ +
overflow reveal); agents bee cards + "Browse all 22" strip = inert across 65s of
scripted hovering; chat message actions = two ~2:1 invisible icons.
3. **Theme switch**: judged worst scenario (4.5-5.5) — but the white flash/reload/
briefing-re-run/mixed-end-state were CAPTURE ARTIFACTS (script used page.goto +
end-of-recording theme flip; both fixed in kit v2). REAL s02 findings that stand:
BootScreen ignores theme (always dark), light "Start Working" CTA likely <4.5:1,
dark-hardcoded skeleton surfaces should be audited.
4. **Marketplace NL dead-end**: typing the promised natural-language query live-filters
to "No results" with no bridge to the semantic search the placeholder promises.
5. **No signature brand motion**: bees never respond to the cursor, hero moments load
behind generic arc spinners, the 448-counter pops instead of landing. Brand judge:
"competent plumbing wearing a honey coat."
What the regime CONFIRMED as wins: s06 settings "Fix it now" error→focus choreography
("best-in-class, period" — design 8.5), workspace-card hover grammar (8/7.5), memory
trust VOICE (8.5 brand), onboarding welcome + live greeting preview (8/8.5), honest
labeled loading with live escape hatches.
Capture-kit v2 changes (disclosed to judges next round): returning-user journeys seed
returning-user localStorage (wizard flash was fresh-profile-only — though the defect is
real for new-device users and is being fixed in product); s02 navigates via the app's
own sidebar and never flips theme mid-recording.
→ Wave T re-scoped around the five convergent gaps (spec: wave-T-spec-2026-07-06.md).
R12 static nits that don't touch judged journeys (settings Show containment, light
input tokens, www landing diagram) DEFERRED to a later polish wave.
## Round 14-V2 verdict (post-Wave-T, product @ c9cea553, kit v2)
**design 7.5 · kw 7.4 · competitor 7.3 · a11y 7.2 · brand 7.5 — min 7.2, avg 7.38**
(V1 baseline: min 7.0, avg 7.08 → +0.2 min / +0.30 avg. The video regime RESPONDS
to fixes — first cross-round improvement signal since the static plateau.)
Wave T fixes verified landed by judges: boot dark pre-paint + no wizard flash, briefing
opens full (~3.5s), theme swap atomic ("commits <500ms, no partial frames, light theme
is true craft parity"), memory false-zero gone, workspace hover grammar praised,
onboarding mascot breathing now VISIBLE (frame-luminance cycling), s06 still the
gold standard (8.5 design).
### Orchestrator verification pass (critical — 3 "repeat findings" were capture blind spots)
- **Agents hover tier + bee response WORK** (live before/after screenshots: honey
border + hairline bloom + lift on hover). The s07 script's `getByRole('heading')`
locator matched NOTHING on the real page → the glide silently no-oped in BOTH V1
and V2 → judges graded an unhovered page. Capture bug, not product bug.
- **Chat action row WORKS** (DOM probe: rest opacity 0.6 + translateY(2px) → hover
1.0 + 0; focus-within parity live). s04's hover target missed the turn; a 16px row
also under-reads in 400px contact-sheet cells. Part capture bug, part real ask
(judges want Claude/ChatGPT-level action visibility — legit escalation).
- **Marketplace NL bridge RENDERS** ("Press Enter — Waggle matches skills to this
job." live; R14 frames show it under a gray "No job matches … by name" line).
Judges saw it and want more: auto-run the semantic match / real CTA / nearest
matches. Legit escalation, not a regression.
### R14-V2 convergent asks (Wave U scope)
1. s03 flash-of-empty-state (5/5 HIGH): "No workspaces yet" renders ~0.5s before data
→ loading/empty/error must be three distinct states; skeleton cards.
2. Briefing interruption discipline (4/5 HIGH): fires on first Home visit even when
the session started elsewhere (s02 Settings→Home); duplicates the home hero story;
modal "2 workspaces" vs hero "6 workspaces waiting" number mismatch.
3. Marketplace NL escalation (4/5): run the promised matching, don't hint at it.
4. Boot warm-start (competitor HIGH): ~3.5s branded boot before every journey vs
Claude/ChatGPT ~1s time-to-content.
5. a11y text floor: agent-card 2nd lines ~2.3:1 dark; light amber tier labels ~3.1:1.
6. Memory: port BeeLoader/skeleton to "Loading memories…"; Memories tab hard cut into
a sparse composition; row actions visible-at-rest + focus parity.
7. One micro-motion tier on tab/panel swaps (Memory tabs, provider key panel).
Kit v3 (for R15): s07 hovers via data-testid card geometry; s04 hovers the real turn
(copy-button ancestor); every scenario logs HOVER-MISS instead of silently skipping.
## Round 15-V3 verdict (post-Wave-U, product @ b1505f90, kit v3)
**design 7.5 · kw 7.8 · competitor 7.6 · a11y 7.3 · brand 7.4 — min 7.3, avg 7.52.**
Regime-B trajectory: 7.08 → 7.38 → 7.52 avg; min 7.0 → 7.2 → 7.3. Still climbing.
kw 7.8 = highest single score of the regime. s07 agents 6.5→8 (hover finally SEEN),
s04 chat 7→7.5, s06 settings 8.5 again ("best-in-class"), s09 onboarding 8
("award-adjacent"). Judges called the briefing skeleton→content shape continuity
"genuine choreography" and the count-up + boot brand moment real wins.
Convergent asks (Wave V scope):
1. s03 empty-flash moved but survived (skeleton→empty→grid, cold-fetch vs 800ms floor
— the exact residual Wave U Lane A flagged). **FIXED inline post-round** (`32507dd9`):
ShellContext now forwards the real `loading` flag; heuristic deleted.
2. s05 memory (5/5): hero count must never paint 0 mid-load (recurs on tab return);
count-up once per session; Memories tab to Trust-hero parity (designed container,
result-count header, skeleton list — "one card floating in a black void").
3. Settings verdict double-truth (kw+competitor HIGH): banner flips "No working model"
→ "ready" → error; resolve provider health once ("Checking…" → single verdict).
4. Motion tier 2 (design+brand HIGH): hover lift 2-4px + glow bloom on cards; a
signature 300-400ms warm theme crossfade; choreographed (not hard-cut) surface
transitions; onboarding keeps the mascot across steps + eased step slide.
5. Loading vocabulary: chat "Loading workspace…" → parallelize with boot + thread
skeleton; marketplace keeps prior results dimmed during debounce (no list collapse);
MATCHES section stability.
6. a11y utility-text sweep (HIGH): Skip setup / Don't show again / statusbar chrome /
marketplace pills / sidebar section labels to AA; rest-state hints for hover-reveals;
tooltips+aria on composer chips and message actions.
## Round 16-V4 verdict (post-Wave-V, product @ 32ea9483, kit v3) — CONTAMINATED ROUND
**design 7.5 · kw 7.3 · competitor 7.6 · a11y 7.5 · brand 7.1 — min 7.1, avg 7.40**
(first drop of the regime — but decomposed, most of it is measurement artifact):
- **s01 "~10s near-black boot wall" = CAPTURE ARTIFACT.** s01 was the first recording
after Wave V's code change → vite cold re-transform. Verified warm: brand 0.6s,
content 2.0s. Kit v4 adds a route warmup pass before recording.
- **"Theme switch is a hard cut" = SAMPLING FLOOR.** The 360ms crossfade shipped and
is unit-tested; it spans <1 frame at 2fps. Kit v4 disclosure tells judges it is
code-verified; judge destination states.
- **Marketplace typing-void = REAL partial-fix gap** — an NL query keyword-filters
everything out, so Wave V's busy-dim had nothing to hold. FIXED post-round: while
the semantic match settles, pre-query rows stay visible (dimmed, inert, capped 6,
data-testid nl-stale-dim).
- Remaining real asks for the next wave: Memories tab density (still "one card in a
void" — the default curated view is the root cause, needs a view-default decision),
boot progressive reveal polish, briefing→home shared-element continuity (deferred),
hover amplitude unification (workspace cards vs agents cards).
Wins confirmed: s06 8.2 "best interaction of the set"; s05 Trust hero 7.8 with the
count-up "caught mid-flight — a felt moment"; s07 lift tier now SEEN ("card visually
raised, honey top edge"); light theme "a true second theme".
## Round 17-V5 verdict (clean round, product @ 08bc3632, kit v4)
**design 7.7 · kw 7.7 · competitor 7.6 · a11y 7.5 · brand 7.9 — min 7.5, avg 7.68.**
NEW REGIME HIGH. Clean trajectory: 7.08 → 7.38 → 7.52 → [7.40 contaminated] → 7.68;
min 7.0 → 7.2 → 7.3 → [7.1] → 7.5. Brand 7.9 = highest single judge score of the
entire arc (both regimes). Panel verdict shifted: "now beats Codex, Hermes, Odyssey";
Claude/ChatGPT hold the streaming + micro-choreography edge only.
Convergent asks (Wave W):
1. Signature entrance choreography (design HIGH): stagger card entrances ~40ms apart
with 8px rise+fade after skeletons resolve (recall cards, workspace grid, agent
cards); 150ms scale/fade menu entrance from its trigger. Long enough to read at 2fps.
2. Marketplace matching state: purpose-built result-row skeletons (the stale-dim fix
registered but "user stares at dimmed wrong content"); denser results layout.
3. Chat streaming arc UNPROVEN — s04 never sends (capture gap, kit v5) + make sure
the streaming visual state holds up when recorded.
4. Memory counter: a 2fps frame catches the count-up near 0 ("reads as a data bug") —
never paint a literal 0; skeleton→count-up starting visibly above zero.
5. Memories tab density (still "one card in a dark field") — default the tab to the
full recent list, curation as a filter, not the landing view.
6. Onboarding: amplify glow breathing (~3s cycle, visible at 2fps); directional slide
welcome→step 1. (low)
## Round 18-V6 verdict (post-Wave-W, product @ 58c23d29, kit v5) + PLATEAU ANALYSIS #3
**design 7.8 · kw 7.7 · competitor 7.7 · a11y 7.5 · brand 7.8 — min 7.5, avg 7.70.**
Per-surface JUMPS (the real signal): s04 chat 7.5→**8.3** (streaming arc finally
recorded — "agentic transparency Claude/ChatGPT/Codex don't match"), s05 memory →8.2,
s01 →8.2, s09 7.9. FIVE surfaces at 8.2-8.3. Verdict verbatim: "clearly BEATS Claude,
ChatGPT, and Codex."
### The aggregate has flattened — plateau signature #2 (video regime)
Clean-round avg: 7.08 → 7.38 → 7.52 → 7.68 → **7.70**. Per-round delta: +0.30, +0.14,
+0.16, **+0.02**. Min: 7.0 → 7.2 → 7.3 → 7.5 → **7.5** (pinned two rounds). This is the
SAME min-of-5 / "9 = do-not-be-generous" ceiling dynamic the static regime hit at
~7.65 — now reached at 7.70 with a far stronger verdict. The video regime bought
**+0.62 avg and a competitive-verdict flip** over four waves; it has now flattened.
### The remaining asks split three ways
1. **Verified-real defects** (ship regardless — Wave X): memory hero count-up shows a
floored "68" below its own "445 to review" (a Wave W Lane D REGRESSION — 15% floor
caught mid-count-up); dark-theme secondary-text AA; eyebrow micro-labels garbled at
9.5px/1.33px tracking; unselected onboarding chip contrast; scraped marketplace
names; memory scope-label clarity (449 "this hive" vs 553 "all minds").
2. **Motion amplitude** (spring hover, glow bloom, streaming aliveness) — named HIGH
3× but this is the 4th motion pass (hover tiers T/U, lift+bloom V, entrance W).
Diminishing returns; a modest overshoot bump folded into Wave X, no more.
3. **Structural** (the ONE material lever left): shared-element / route-transition
motion system across react-router changes (design+competitor HIGH). This is a real
framer-motion engineering arc, NOT a polish wave — plus ambient home-hex idle life
and true token-streaming (blocked by the dev echo provider returning whole blocks).
### DECISION POINT (founder) — mirrors the static-plateau close-out
The polish-wave engine has done its job: 6.7 static → 7.70 video, "beats the mainstream
field," five surfaces at 8+. Reaching 5×9 from here needs the **structural motion arc**
(route transitions + ambient life + real streaming), which is different work than the
fire-6-lanes-and-judge loop and carries real regression risk.
- **A. Accept & merge** the arc (Waves P-X, ~55 commits, all gates green) — the
evidence-recommended close: the number has flattened, the verdict is strong, the
remaining defects ship in Wave X.
- **B. Commission the structural motion arc** — route-transition system as a scoped
engineering project (not a wave); the only path that could move 7.70 materially,
with real infra risk and no comparability guarantee.
- **C. Keep firing polish waves** — measured EV ≈ +0.02/round; not recommended.
Recommendation: ship Wave X (real defects, in flight), run R19-V7 to confirm the
defects cleared, then **A** unless the founder wants to fund **B** as its own arc.
## Round 19-V7 verdict (post-Wave-X, product @ e8f6b41b) — ⚠ JUDGE MODEL CHANGED
**design 7.7 · kw 7.6 · competitor 7.6 · a11y 7.5 · brand 7.7 — min 7.5, avg 7.62.**
### ⚠ Comparability break: judges ran on OPUS 4.8, not Fable 5
The session main-loop model was switched to Opus 4.8 (1M) via /model before this
round. The judge agents inherit the session model, so R19's five judges are
`claude-opus-4-8[1m]` — R13→R18 were all `claude-fable-5`. **7.62 is a different,
generally harsher ruler; it is NOT a regression from Fable's 7.70.** For a clean
comparison next time, PIN the judge model to fable in judge-workflow-video.mjs
(add `model:'fable'` to the agent() opts) so the ruler is arc-stable regardless of
the main-loop model.
### What R19 actually proves (ruler-independent)
1. **Streaming was finally SEEN** (the kit-v5 s04 send landed): "the chat reply
visibly accretes line-by-line as a genuinely memory-grounded, non-hallucinated
answer" — chat rose to **8.0** (design/kw) after living at 7.2-7.5 all arc. The
one thing Claude/ChatGPT "own" is now on our board.
2. **Wave X defects cleared**: no judge re-flagged the "68 memories over 445 to
review" contradiction, the scraped marketplace names, or the specific dark
offenders (workspace meta / memory M-id) I fixed. The Opus a11y judge names
DIFFERENT, broader targets (top utility bar, onboarding subtitle, LIGHT-theme
eyebrows on cream) — a wider systemic sweep, not the fixed regressions.
3. **5/5 UNANIMOUS gap-to-9 = a motion SYSTEM**, not features/polish. Every judge,
independently, names the same structural lever: spatial continuity / shared-
element route transitions / spring physics / multi-tier hover (+ a signature
streaming reveal + drop the boot interstitial). Verbatim: "visual craft of a 9,
motion identity of a ~7"; "gap to 9 is not more features — it's a genuine motion
system." Verdict: "beats Codex decisively, beats ChatGPT on identity/info design,
roughly even with Claude."
### This CONFIRMS Plateau Analysis #3 with unanimity
The polish-wave engine is done. Five independent Opus judges converge that the ONLY
path from ~7.6-7.7 to 9 is the structural motion arc (option B) — the exact work I
scoped as a founder decision, not a wave. Firing more polish lanes is now
measured-EV≈0 AND explicitly named as the wrong tool by every judge.
→ **Recommendation stands: A (merge Waves P-X, ~59 commits, all gates green) unless
the founder funds B (the route-transition/spring/shared-element motion system) as a
dedicated engineering arc.** C (more polish waves) is contraindicated by all 5 judges.
---
## PATH-TO-9 REVIEW ROUNDS (goal: "judges agree on the path" — 2026-07-07)
Founder re-armed /goal: deep analysis of what reaches 9 — premium UX + power feeling +
earned addiction. Deliverable: docs/ux-refactor/path-to-9-2026-07-07.md, reviewed by the
same 5-persona panel (pinned model:'fable') acting as adversarial path reviewers.
- **PATH-1** (v1): 4/5 endorse (a11y withheld — the min gate, consistent). Predicted
8.3–9.0. 12 blocking amendments filed → ALL integrated in v2.
- **PATH-2** (v2): **5/5 ENDORSE — GOAL MET.** design 8.8 (high) · kw 9.0 (medium) ·
competitor 8.8 (high) · a11y 8.7 (high) · brand 9.0 (medium). Seven endorsement
conditions → integrated in v3 (default route-transition tier; motion retrofit;
input-during-warmup contract + first-interaction gate; streaming interaction
contract; side-by-side competitor evidence; affordance floor; reduced-motion
enforcement).
**v3 is the agreed executable contract**: Phase-0 motion vocabulary → Pillar 4 AA/
affordance floor (parallel) → Pillar 2 instant power feel → Pillar 3 aliveness loop →
Pillar 1 motion system, with kit v6 verification (≥12fps signature clips, keyboard-only
+ reduced-motion journeys, hard Playwright gates, Claude/ChatGPT side-by-sides) and
per-round success gates (min ≥8.0 after P4+P2 · ≥8.5 after P3 · 9-attempt after P1;
two flat rounds → stop and re-analyze).
## Round 20 (post-Phase-A+B, product @ b4f1abfe, kit v6, Fable ruler)
**design 7.9 · kw 7.9 · competitor 7.8 · a11y 7.7 · brand 7.6 — min 7.6, avg 7.78.**
Fable-ruler trajectory: R18 7.70 → **R20 7.78** (+0.08 avg, min 7.5→7.6). Five surfaces
at 8.0 (home/memory/settings/onboarding + s04 chat 7.8). **Verdict flipped: "a genuine
PEER to Claude/ChatGPT — wins decisively on identity + memory-native moments + the
surfaces around chat; beats Codex/Hermes/Odyssey on craft AND motion now."**
### v3 gate check: min ≥ 8.0 after Phases 4+2 → **NOT met (7.6), but the miss is the
UNBUILT pillars, not a Phase-A/B defect.** The convergence is unambiguous:
- **Streaming cadence = THE gap (4/5 HIGH)**: chunk/line reveal vs Claude/ChatGPT's
per-token blur-up + live caret. This is literally Pillar 3.1 (next phase). The
memory-search trace during generation is already judged "differentiated, no
competitor ships it" — only the raw-text micro-cadence trails.
- **Home ambient life + scroll-reveal (brand+design HIGH)**: Pillar 3 ambient / Pillar 1
entrance — also unbuilt.
- **Stronger honey-responds-to-touch hover (brand)**: Pillar 1.2 amplitude.
### Phase-A/B wins CONFIRMED on camera
Warm cache-first paint (recall cards INSIDE the hero, no interposing modal — the
double-catch-up collapse working, 3-day<7 threshold), non-blocking send queue
("user bubble commits instantly, composer clears"), Fix-it-now focus-jump, honest
reduced-motion degradation (s11: instant route change, static count), keyboard focus
rings visible (s10), light theme "proper re-tokening not an inverted hack."
### Verified residuals (fold into Phase C cleanup lane, not a separate round — streaming
caps the score so residuals alone can't reach 8.0):
1. Boot "~2s wall" for warm users = CAPTURE ARTIFACT (seed missing `waggle-booted`;
real returning users skip boot, gate-verified 459ms). Fix the capture seed +
verify product truth.
2. Card/row overflow ('…') actions keyboard-reachability (roving tabindex + focus
ring on the action) — s10 acceptance partially unverified (a11y+design HIGH).
3. Reduced-motion boot glow freeze (s11, 2 judges low).
4. A few tertiary-text eyebrow stragglers (RESEARCH HUB/START HERE, onboarding
subhead) + light-theme focus-ring visibility check (a11y).
5. Dense secondary surfaces (marketplace/models/memories rows) vertical rhythm (medium).
→ Proceed to Phase C (Pillar 3 aliveness — streaming headline) with the cleanup lane
folded in. The path is agreed (5/5); the gate-miss reason is the next phase's work.
## Round 21 (post-Phase-C, product @ 4a059907, kit v7, Fable ruler) — COACHMARK-CONTAMINATED
**design 7.6 · kw 7.8 · competitor 7.8 · a11y 7.7 · brand 7.7 — min 7.6, avg 7.72.**
Flat vs R20 (7.6/7.78) DESPITE streaming shipping — because a NEW capture artifact
dominated: the "Type / for 22 powerful commands" onboarding coach-mark occluded live
content in SIX scenarios (s01/s03/s04/s06/s07/s08). ALL 5 judges rated killing it HIGH;
design: "the single most un-premium, most-repeated tell... disqualifying for best-in-class."
### Root cause (a seed bug I introduced in kit v7, now fixed)
Kit v7 added `waggle_onboarding_complete: 'true'` to the capture seed. That is the LEGACY
migration key: useOnboarding.loadState() (L78) sees it, rewrites the onboarding blob to
`{completed:true, step:7}` WITHOUT tooltipsDismissed, so shouldShowCoachMarks fired.
NOT a product bug (real returning users carry the current blob, not the legacy key).
Fixed by removing the key from the seed; verified coach-mark GONE on home + chat.
### Real residuals addressed (C.1 polish, committed):
- Streaming STILL read chunk-buffered + "no caret" to design+competitor (2 HIGH). The
2px caret was invisible at video scale → widened to 3px rounded honey; CATCHUP_FRAMES
28→40 (~670ms reveal, ~8 frames at 12fps = unambiguously per-token). Verified: smooth
per-char growth 253→362 with the 3px caret visible.
- Light-theme recall-card 10px timestamp borderline on cream (a11y+design medium) →
--text-tertiary.
### Real Phase-C wins CONFIRMED (through the coachmark noise):
s05 count-up 445→449, s01 staggered I-REMEMBER + hero crossfade, s11 honest reduced-
motion (count snaps, routes crossfade, no lingering transform — "exactly what a design
jury rewards"), s10 keyboard focus rings "real and premium", s12 first-launch boot,
s02 coordinated theme crossfade. Verdict: "beats Codex/Hermes/Odyssey; ties/edges
ChatGPT; trails Claude ONLY on streaming finesse + never letting chrome cover content."
### Still-open for Phase D (the motion system — every judge's remaining ask):
hover tiers "tasteful-restrained → memorable" (multi-property lift+bloom, 3 judges);
ONE signature motion identity moment (count-up + glow-breathe are the seeds); route/
entrance choreography. These ARE Pillar 1 (Phase D). Gate min≥8.5 not met (7.6) but
the coachmark masked the true post-C number — Phase D + the clean re-capture is R22.
## Round 22 — the 9-attempt (all 4 pillars shipped @ 9b892ed9, kit v8) + PLATEAU ANALYSIS #4 (FINAL)
**design 7.6 · kw 7.9 · competitor 7.7 · a11y 7.5 · brand 7.6 — min 7.5, avg 7.66.**
### The measurement is conclusive: the executed path plateaued at ~7.6–7.8
Video-regime avg across the FULLY EXECUTED path (Fable ruler, comparable):
R20 (Pillars 4+2) 7.78 → R21 (Pillar 3, coachmark-masked, real ~7.9) 7.72 →
**R22 (Pillar 1, motion system) 7.66.** Three rounds flat-to-declining while
shipping the ENTIRE agreed path (motion vocabulary, AA floor, instant power feel,
aliveness/streaming, AND the full motion system). min pinned at 7.5. This is the
SAME min-of-5 ceiling dynamic that capped the static regime at 7.65 — now reached
at ~7.66 with a far stronger verdict.
### The judges CREDIT the whole path (uniform, strong)
"Clearly BEATS Codex, Hermes, Odyssey" (all 5); "edges Claude and ChatGPT on brand
identity and warmth" (brand); "a working motion system + memory-native surfaces the
competitors don't attempt" (kw/competitor); s13 hero morph = "genuine Apple/Linear-
grade spatial continuity that the chat competitors don't attempt for navigation"
(design); s05 memory "the product's soul... genuinely differentiated." The motion
system landed and is recognized.
### Why 9.0-MINIMUM is not reachable under this regime (evidence, 3 causes)
1. **The two persistent HIGH asks are substantially CAPTURE/DEV artifacts:**
- "Instant everywhere / the 459ms isn't visible / kill route-return skeletons"
(3 judges): each capture journey uses a FRESH browser context, so per-surface
caches are COLD on first visit within it. HOME cache-first is gate-verified at
459ms (real). Extending cache-first to EVERY surface is real Pillar-2 work but
the capture can't easily show warm per-surface returns, and it won't move min→9.
- "Buttery per-token streaming" (2 judges, persistent through R20/21/22 despite
TWO cadence retunes): the dev ECHO provider dumps WHOLE-BLOCK, so the cadence
smooths a block rather than pacing real tokens; a production streaming model
would read smoother. Plus markdown reflow at 12fps reads chunky. Dev-env + 12fps
artifact, not a shippable product deficit.
2. **The min-of-5 harsh rubric ("9 = do NOT be generous") + new equal-weight nits
every round** (R22: unselected onboarding chips, light small-caps labels — after
two prior AA sweeps closed the ones before). Documented whack-a-mole; the stable
fixed point once real defects are gone is ~7.5 min.
3. **2fps sampling structurally withholds credit** for the motion the product's
strongest layer now has (12fps strips only partially compensate).
### DECISION (founder) — the path is COMPLETE; this is a genuine budget call
The /goal ("done when judges agree on the path") was MET (PATH-2, 5/5 endorsed).
The path was then FULLY EXECUTED: 4 pillars, ~15 commits on main, every gate green,
every phase adversarially verified, 2 blocking motion bugs caught+fixed. Result:
6.7 static → 7.66 video with a "genuine peer to Claude/ChatGPT" verdict. 9.0-minimum
is not reachable for the measured reasons above.
- **A. Accept the executed arc** — merge/push the full path (Phases A–D), take the
result (strong, verified, "beats the field / peer to the leaders"). EV-recommended.
- **B. One targeted round on the two REAL (non-artifact) levers** — extend cache-
first paint to every surface (real, kw/competitor HIGH) + the 2 a11y nits. Measured
EV ≈ +0.1–0.2 avg, min maybe 7.5→7.7; will NOT reach 9. Streaming "buttery" needs
a real provider, not fixable in the echo-dev capture.
- **C. Stop and accept the plateau** — the number is a stable fixed point.
Recommendation: **A** (or B then A). C and "more full phases" have measured EV ≈ 0
(three flat rounds). Grinding past a measured plateau is the mistake this arc's
discipline exists to prevent (it caught two prior plateaus).

72
docs/ux-refactor/oss-sync-finding-2026-06-12.md Normal file
View File

@@ -0,0 +1,72 @@
# OSS Sync — Drift Analysis & Finding (2026-06-12)
> Triggered by "close the OSS re-split" after P5/D4 + #15 changed
> `packages/hive-mind-core/src/mind/{schema.ts,db.ts}` (the OSS-mirrored substrate).
> **Conclusion: NO forward-port needed — the OSS mirror is current for everything it
> actually carries.** This doc records the analysis so the obligation is provably
> closed and the next session doesn't re-flag a phantom gap.
## What was checked
OSS mirror clone: `/d/Projects/hive-mind` (remote `github.com/marolinik/hive-mind`),
on the maintainer branch `feature/mono-parity-2026-06-12`, top commit `23e15ff`
*"feat(core): mono-parity 2026-06-12 — forward-port of the waggle-os substrate arc"*
committed **02:59 today**.
`scripts/oss-drift-check.sh` flagged ~50 DIFFERS + 1 ONLY-IN-OSS + 5 ONLY-IN-MONO.
Each was run down:
| Drift item | Reality |
|---|---|
| **ONLY-IN-OSS `mind/llm-extractor.ts`** | Already reverse-ported to the monorepo as `harvest/extract-kg-entities.ts` (its header says so, "oss-drift triage D2, 2026-06-11"). The OSS keeps its standalone-executor original by curation. **Not a gap.** |
| **ONLY-IN-MONO `evolution-runs/execution-traces/improvement-signals.ts`** | Waggle-proprietary (barrel-exported in mono, consumed only by `@waggle/core`). The 02:59 sync correctly **stripped** them from OSS. **Intentional exclusion.** |
| **ONLY-IN-MONO `extract-kg-entities.ts`, `multi-mind.ts`** | OSS keeps `llm-extractor.ts` instead; multi-mind is a Waggle orchestration concern. Curation. |
| **~50 DIFFERS (mind/*, harvest/*)** | OSS-adaptation noise — `packages/core` vs `packages/hive-mind-core` layout, import-path rewrites, logger swaps. Not source drift. |
## The substrate changes this session — why none need porting
This session's only `hive-mind-core` substrate edits were:
- **P5/D4 `658884f`** — `'uninstalled'` in the **install_audit** action CHECK + its rebuild migration.
- **#15 `6fc8500`** — the **install_audit** `trust_source` CHECK + its rebuild migration.
Both are **entirely within the `install_audit` subsystem**, which the OSS substrate
**does not carry**:
- OSS `schema.ts` has **no `CREATE TABLE install_audit`** — only a vestigial comment line.
- OSS `db.ts` has **zero `install_audit` references** — the rebuild migration is absent.
`install_audit` is the capability-install trust trail (EU AI Act compliance / marketplace
governance) — Waggle-proprietary, same class as `evolution-runs`/`execution-traces`. Its
`InstallAuditStore` lives in `@waggle/core`, not the substrate. The 02:59 sync curated the
table + migration out. **So the P5/#15 deltas have nowhere to land on the OSS mirror.**
### c33da1e (content_hash boot fix) — also not needed
The mono boot-crash was: `SCHEMA_SQL` (with an inline `idx_frames_content_hash`) ran before
`runMigrations` added the column. The **OSS `db.ts` is structured differently** — its
`runMigrations` does `ensureColumn('content_hash')` **before** `applySql(SCHEMA_SQL)`
(db.ts:215→220), and the fresh path creates the column in the CREATE TABLE. So the OSS
already avoids the crash in both paths. **Not a gap.**
## Net
**The OSS mirror is in sync as of its 02:59 forward-port.** The "OSS re-split obligation"
flagged in prior handoffs was based on the assumption that any `schema.ts`/`db.ts` change
needs mirroring — but this session's specific changes are all in the OSS-excluded
`install_audit` subsystem. Nothing to push.
## ⚠️ Tooling/doc inaccuracies found (real, worth fixing)
The OSS sync is a **hand-curated forward-port on a feature branch** (the 02:59 model), NOT
the `scripts/oss-subtree-split.sh` script. The script is **stale and unsafe**:
1. It targets `packages/hive-mind-core` as the export root, but the OSS repo's layout is
`packages/core` — the branches it produces don't match the mirror.
2. It has **no proprietary-file filter**, yet CLAUDE.md §7.5 claims *"Files that must NOT
export … are handled by the subtree-split filter."* That filter **does not exist** in the
script. A literal `subtree split` + push per the stale docs would **leak**
`evolution-runs`/`execution-traces`/`improvement-signals.ts` to the public repo.
The real protection is the manual curation (the 02:59 sync did strip them).
**Recommendation:** update CLAUDE.md §7.5 to describe the actual process (curated
forward-port on a feature branch; `install_audit` + the three proprietary files are
OSS-excluded) and either fix `oss-subtree-split.sh` to add a real filter + correct layout,
or mark it deprecated. Deferred to the founder (it touches the authoritative §7.5 contract).

52
docs/ux-refactor/p1a-residuals.md Normal file
View File

@@ -0,0 +1,52 @@
# P1a Conversion — Review Residuals (2026-06-10)
Source: adversarial review workflow over 93c7dd0..a6dc2e4 (30 raw findings; 7 confirmed -> fixed in 4e1d763; 6 refuted; 17 LOW unverified, listed here for P7/backlog triage).
## LOW findings (unverified — triage in P7 Hardening)
- [ ] Acceptance check 1's literal grep is not zero: legacy zIndex/cascadeOffset parsing survives in the migration module (plan-internal inconsistency, undocumented residual)
- [ ] Shim does not runtime-guard event input: unknown appId navigates to '/undefined', and routeFor('backup') + queryString can compose a malformed double-'?' URL
- [ ] Onboarding-finish drops the wizard-supplied workspaceName — transiently re-opens the exact race the old handler's bug #4/#8 fix existed for
- [ ] ChatHost keep-alive set is append-only — deleted/nonexistent workspace ids keep a hidden live ChatWindowInstance, portal container, and persisted chat entry forever
- [ ] Autonomy auto-revert has no mount-time check — an already-expired elevated grant is honored for up to 10s after a widget mounts, and sits un-reverted in storage for never-mounted workspaces
- [ ] loadChatEntries returns a fresh object per call when localStorage is unavailable — unstable useSyncExternalStore snapshot (infinite-render class) in no-storage environments
- [ ] Settings dock-labels toggle (M-19/UX-4) is now inert — its only renderer died with Dock.tsx
- [ ] Offline guidance banner lost — only the compact StatusBar icon remains
- [ ] routeFor('backup') composes a malformed double-? URL if a deep link ever carries a tab
- [ ] StatusBar breadcrumb is blank on routed surfaces with no nav entry (e.g. /settings/profile), where the old shell showed the window title
- [ ] Stale dock-era copy in untouched overlays: KeyboardShortcutsHelp says Ctrl+Shift+0 opens 'Dashboard' (killed), tooltips say 'Click dock icons'
- [ ] Files workspace selection lost its session stickiness — resets to the active workspace on every nav re-entry
- [ ] Duplicate 10s autonomy auto-revert intervals (one per useChatWidgetState call site), including one keyed 'local-default'
- [ ] getSnapshot returns a fresh object identity per call when localStorage is unavailable — useSyncExternalStore infinite-render risk in storage-less environments
- [ ] Keep-alive structures never prune: visited[] + module-level containers Map keep full chat runtimes (SSE/polling/intervals) alive for deleted workspaces, with no close affordance
- [ ] routeFor('backup') already embeds '?tab=backup'; shim appends a second '?' if a tab-carrying dispatch ever targets it
- [ ] WorkspaceRoute.onTabChange pushes duplicate history entries on same-tab clicks and drops query params on tab switches
## Refuted at review (no action — recorded so they are not re-found)
- Shim re-dispatch is a double-rAF timing heuristic that can fire before the target route commits under startTransition — silently drops the UserProfileApp deep link (acceptance check 3, second half)
- IndexRedirect consumes the one-shot salvaged route inside a useState initializer — impure render that silently burns the salvage under StrictMode double-invoke or a discarded concurrent render
- waggle:open-app shim's double-rAF re-dispatch is a timing guess — under v7_startTransition the target route may not be committed yet, silently dropping the live-listener deep link (acceptance check 3)
- PersonaSwitcher lost the only path that clears a workspace's agent-group (agentGroupId can now never be unset)
- Playwright e2e/vision suites still target the retired dock/desktop shell — flip shipped without re-establishing their coverage
- Shim's double-rAF re-dispatch is a timing heuristic that can fire before the target route commits — Identity-tab deep link (acceptance check 3) silently lost
## Known follow-ups owned elsewhere
- tests/e2e + tests/vision Playwright suites partially retargeted (phase-ab-verification.spec.ts done in 4e1d763); full sweep of remaining dock-era specs = P7.
- package-lock.json sync deferred to a Linux-side regen (Windows regen drops 20 linux/darwin optional entries) — pre-existing, tracked since 0601_s3.
- Killed AppId FILES (DashboardApp/VoiceApp/MissionControlApp/BackupApp) still on disk per plan §5.3.4 — separate dead-code commit.
## Live-smoke findings (2026-06-10, vite:8080 + branch sidecar:3501 via SIDECAR_TARGET proxy)
**Acceptance checks live-verified:** #2 (14 routes by typed URL + 404, all render in shell), #3 (both shim consumer styles: /automations?tab=logs stash-preselect AND /settings/profile?tab=identity re-dispatch-preselect), #4 (Ctrl+K on routed surfaces; workspace result click -> URL change; browser Back), #6 (populated salvage -> /memory + chat-state researcher/trusted migrated + key removed; corrupt -> /home + key removed, no crash; deep-link entry wins over salvage while side effects still run), #7 (chat widget at /workspaces/:id/chat, 8 URL-driven tabs both directions, **SSE stream survived navigation**: 3711 chars at nav-away mid-stream -> 5924 complete on return; nav-Chat resolved the active workspace post review-fix). **#8 (wizard onFinish) NOT live-run** — would create a real workspace in ~/.waggle; covered by unit tests + review-verified wiring. Checks #1/#5/#9/#10 verified statically at build+review time.
**D3/P1b-scope confirmations observed live** (pre-existing class, NOT P1a regressions — the old shell had identical mount-time fetch races):
- [ ] Boot 401 burst pre-token; useWorkspaces fetch-once-no-recovery (hooks/useWorkspaces.ts:25) -> empty workspace list for the session when the race is lost; nav-Chat then falls back to /home
- [ ] HomeCockpit RecentWorkspacesPanel crashes into boundary on undefined briefing (HomeCockpit.tsx:324, undefined.length) when /api/home/briefing fails — same family as the fixed 0609 cold-load bug, different panel
- [ ] CockpitApp render error (undefined.totalInteractions) pre-data, recovers on refetch
- [ ] adapter default base is hardcoded 127.0.0.1:3333 — dev-against-alternate-sidecar requires localStorage waggle:server-url=http://localhost:8080 + SIDECAR_TARGET env on vite (recipe; consider deriving default from window.origin in dev)
**Cosmetic (P7):**
- [ ] StatusBar breadcrumb shows the matched nav entry ("Chat") on /workspaces/:id overview — consider workspace-name breadcrumb
- [ ] LoginBriefing re-shows on every hard reload (per-session dismissal) — correct SPA behavior, slightly noisy under multi-tab/hard-reload use

129
docs/ux-refactor/p1b-auth-gate-plan.md Normal file
View File

@@ -0,0 +1,129 @@
# P1b — D3 Structural Auth Gate: Conversion Plan v2 (2026-06-11)
**Authority:** D3 ruling in the v2.1 ratification register (`deltas/open-questions.md`, 2026-06-10) — RATIFIED, full structural scope. Live-confirmed targets: `p1a-residuals.md` "Live-smoke findings".
**Surface map:** 5-lane workflow audit 2026-06-11 against main @ `fa3797c`.
**Plan verification:** two adversarial workflow rounds (6 lenses, 38 agents): **24 confirmed findings (1 CRITICAL / 10 HIGH / 13 MEDIUM), 0 refuted, 16 LOWs** — all folded in below; full record in `p1b-plan-review-record.md`. v1 is in git history (2 commits back).
---
## 0. The problem, precisely
Three independent legs, each with its own fix:
1. **Boot race (pre-token 401 burst) — fetch layer.** `ServiceProvider` is the *outermost* provider (`App.tsx:52`); React runs child effects before parent effects, so on a warm boot every mount fetch (`getWorkspaces`, `getTier`, `getPermissions`, `getNotificationHistory`, LoginBriefing's batch) fires token-less **before `adapter.connect()` even starts** (`ServiceProvider.tsx:40`). Cold boot only wins by BootScreen animation luck (`AppShell.tsx:397-408`).
2. **Failure-as-data (silent-empty).** `adapter.fetch()` (`adapter.ts:185-216`) never throws on `!res.ok` — **~145 of ~190 public methods** parse HTTP error bodies as data or coalesce them to `[]`/defaults (audit lane 0). 42 methods already throw — throwing is the existing majority convention for mutations.
3. **No mid-session recovery.** The bearer token is per-process (`crypto.randomBytes(32)` at `index.ts:1384`, in-memory) — **it rotates on every sidecar restart**. Nothing client-side handles 401; a restart bricks every authed call (including chat: a stale-token `sendMessage` parses the 401 body as an SSE stream and yields nothing — silent dead chat) until full page reload.
Severity-critical instance (D3-4): `ShellContext.refreshTier` (`ShellContext.tsx:111-122`) — on an HTTP error `getTier()` parses the error body, `String(data.tier ?? 'FREE')` **actively sets billingTier to FREE** with no signal, no retry. A paying user on a lost boot race sees the FREE app.
**Discovered during plan verification — NOT fixable in this phase (see §1.4):** all five EventSource SSE channels (notifications, events, subagent status, waggle signals, harvest progress) are **401-dead in every default run since D1** — the server bearer-gates all `/api/*` GETs, EventSource cannot send headers, and none of those routes accept `?token=` (only `/ws` does, and `connectWebSocket` is dead code). The SSE half of the boot race is therefore a *server-side* defect; this plan fixes the fetch half and ledgers the SSE half loudly.
## 1. Design contract
### 1.1 Adapter core (Stage A)
**(a) Pre-token deferral — `ensureReady()` with a self-healing, bounded gate.**
Connect machinery:
- `connect()` memoizes its in-flight attempt in `this._connectPromise`, **assigned synchronously** (before the first await) so two same-tick calls — `OnboardingWizard.tsx:78` fire-and-forget + ServiceProvider's effect — share one probe. **A settled-SUCCESS memo is kept** (cleared only by `setServerUrl()`), so late `connect()` callers dedup instead of re-probing; `reconnect()` intent = `setServerUrl(current)`-style reset or an explicit `forceReconnect()` that clears the memo first.
- **Watchdog (HIGH fix):** `connect()` gets an end-to-end deadline (~15s AbortController spanning health probe + body reads + token fetch — `fetchWithTimeout` only bounds headers, `fetch-utils.ts:20-36`; the `res.json()` reads at `adapter.ts:142/167-175` are currently unbounded). The gate can therefore never wedge the app: connect always settles. This also converts any future client/server exempt-path drift (a true self-deadlock) into a loud bounded failure.
- **Epoch guard (MEDIUM fix):** `private _epoch = 0`; `setServerUrl()` increments it; every connect/healthProbe continuation (set `_connected`, write `authToken`, `baseUrl` mutation, localStorage persist) no-ops when its captured epoch is stale. **healthProbe single-flights** and runs its auto-discovery fallback on a LOCAL url variable, committing to `this.baseUrl`+localStorage only on success + epoch match — it is otherwise an unsynchronized `baseUrl` writer racing `useOfflineStatus`'s exempt `/health` probes.
Gate semantics (`ensureReady()`, awaited by `adapter.fetch()` unless the path is auth-exempt — `/health`, `/api/auth/session-token`, mirror of server `AUTH_EXEMPT_PATHS` `security-middleware.ts:238`):
- **In-flight attempt** → await its settlement (success or failure).
- **Settled-success** → pass through.
- **Settled-FAILURE → re-arm (HIGH fix):** kick ONE fresh memoized `connect()` and defer onto it. Cold-sidecar desktop boot (the *default* Tauri path: webview up before sidecar listens; main.tsx's kickoff gets instant ECONNREFUSED) no longer disarms the gate — each subsequent request re-attempts (single-flight, watchdog-bounded, fails fast while the sidecar is down) until one succeeds, making the gate self-healing instead of one-shot.
- **Never-attempted** → pass through. This keeps the **7** existing adapter unit-test files (not "~30" — v1 count corrected) behavior-identical. Production arms the gate structurally: a dedicated **`boot-connect.ts` imported as main.tsx's FIRST import** (import hoisting guarantees the attempt is in flight before any sibling module evaluates). Regression-locked: `adapter.authgate.test.ts` pins **zero network on adapter module import and on `new LocalAdapter()`** (5 test files index `mock.calls[0]` / assert exactly-one-fetch — a kickoff drifting into the adapter module or constructor breaks all 7).
- `ServiceProvider.connect()` awaits the same memoized promise and gains a **capped retry/backoff loop** (3 attempts ~1s/3s/9s) for the cold-sidecar window; on every settlement it dispatches a **`waggle:connect-settled` window event** — the shared revalidation bus consumed by Stage-B surfaces. **Constraint (test blast radius):** ServiceProvider may only call `connect()`/existing adapter members — 9 component test files render the *real* ServiceProvider over hand-rolled adapter mocks; any new adapter member referenced there TypeErrors them.
- `uploadFile` / `ingestFile` (**MEDIUM fix**) currently call `fetchWithTimeout` directly with hand-attached tokens — route both through the shared core (suppress the JSON content-type default for FormData bodies) so they inherit deferral + throw + retry; add to the Stage-A test matrix (401→refresh-retry multipart; 413→`AdapterHttpError` with the server's reason).
- SSE `subscribe*` methods: **explicitly NOT wired to `ensureReady()`** — none attach a token, so deferral merely delays an identical 401 (see §1.4). Their `if (!this._connected) return () => {}` noop guards stay as-is in P1b. `connectWebSocket` (`?token=` style, `adapter.ts:2536`) has zero callers — P7 dead-code ledger entry, do not wire.
**(b) Throw-on-`!ok` — at the chokepoint, not per-getter.**
- `adapter.fetch()` throws `AdapterHttpError` on `!res.ok` after the 403 dispatch (dispatch-then-throw). Shape: `class AdapterHttpError extends Error { status: number; body: unknown; code?: string }` — field-compatible with the incumbent rich-error consumers (`CapabilitiesApp.tsx:191-204` reads `err.status`/`e.body?.required`; `SkillBuilder.tsx:141`; `installSkill`/`installPack` `adapter.ts:914-920/960-966` already ship this shape). Body parsed best-effort via `res.clone().json()`.
- **Message pinned, message-first (HIGH fix — v1's error-first precedence inverted the incumbent convention pinned in `adapter.eraseData.test.ts`/`adapter.startTrial.test.ts`):** `AdapterHttpError.message := String(body.message ?? body.error ?? \`HTTP ${status}\`)`. For `{error:'TIER_INSUFFICIENT', message:'…'}` bodies this surfaces the human message; for plain `{error:'…'}` bodies it falls through to `error` — strictly better both ways. `eraseData`/`startTrial` keep their pinned `\`Erase failed (400): …\`` prefixes by catching `AdapterHttpError` and rethrowing in legacy format (~3 lines each; their existing `!ok` blocks become dead and are removed) — their 2 test files stay verbatim-green. `createSkill` (`adapter.ts:866-875`, message = `body.error`) simplifies onto the throwing fetch — message-first is a superset; test-pin message+status+body.
- New method `adapter.fetchRaw()` = today's semantics (never throws on status; still token + 403-dispatch + deferral + retry). **Two migration classes** (the v1 filter — "status-aware handling on the Response" — structurally missed body-envelope consumers):
- **Raw-Response callers:** `installMarketplacePackage` (callers check `res.status === 403` + SecurityGate `{blocked,severity}`: `MarketplaceApp.tsx:228-245`, `CapabilityRequestCard.tsx:54-62`) — documented raw contract `adapter.ts:981-995`. **NOT `uninstallMarketplacePackage`**: its only consumer ignores the Response and unconditionally toasts success (`MarketplaceApp.tsx:253-262`) — leaving it on throwing fetch fixes a silent false-success bug for free; test-pin that a 500 uninstall shows the failure toast and does NOT flip `installed:false`.
- **Body-envelope getters (CRITICAL finding):** typed getters whose *parsed error body* is load-bearing. Verified set: `installMcp` (`adapter.ts:1663-1671` — server sends `{installed:false, requiresApproval, blocked, severity, scanResult}` on 403/422 per `mcps.ts:249-259`; `MCPHubApp.tsx:156-182` branches `res.error === 'TIER_INSUFFICIENT'` AND drives the ApprovalModal HIGH-override / CRITICAL-non-overridable flow off `res.requiresApproval` — a chokepoint throw would kill that flow), plus `addCustomMcp` (`AddCustomMcpForm.tsx:53-68`, deliberate tier-403 inline-suppression), `updateMcpPermissions` (`MCPHubApp.tsx:240-247` — comment pins the never-throws contract), `revokeMcp` (`MCPHubApp.tsx:216-226`), `startMcp`/`stopMcp`/`testMcp` (`InstalledMcpList.tsx:54-78`). Migration: internals → `fetchRaw`, keep returning parsed body regardless of status.
- **Hard Stage-A exit criterion (promoted from v1's acceptance-note):** one adapter-level test per body-envelope getter (real method + mocked fetch returning the 422/403 envelope → parsed envelope returned, not thrown) + `installMarketplacePackage` raw passthrough + the `uninstallMarketplacePackage` pin. **No adapter-level raw/envelope pins exist anywhere today** — component tests mock the adapter methods and are structurally blind to a botched migration.
- Implementation sweep to close the class: grep components for `res.error` / `res.ok`-on-non-Response / `requiresApproval` / `blocked` / `scanResult` before finalizing the list.
- The 15 direct `adapter.fetch(` component call sites — verified per-site: **only BackupApp needs `fetchRaw`** (`BackupApp.tsx:41` maps 404→'empty' via `classifyMetadataStatus:21-25`; `:59`/`:89` branch `res.ok` with distinct server-fault messages incl. the 413 reason). The other 12 (TelemetryApp×2, SkillEditorDrawer, SkillBuilder, EvolutionTab×8) stay on throwing fetch — their `!ok→throw` branches become dead code, catch paths *improve*. Add a BackupApp component-level 404→empty test (`phase5b-backup.test.tsx` tests only the pure function — vacuous against a missed migration). Rule for stragglers: migrate only where non-2xx maps to a NON-error UI state or status/body drive UI a catch cannot reproduce.
- Getters with `unwrapArray`/`?? []` need no individual edits — post-throw they only see 2xx bodies. Keep the defensive coalescing.
- `sendMessage` (chat SSE generator, `adapter.ts:380-398`): verified consumer is **`useChat.ts:125`** (ChatWindowInstance only wires the hook). Today a stale/missing token = silent empty assistant bubble (401 body parsed as SSE, zero yields, catch never fires). With throw + 401-retry, chat survives sidecar restarts — this leg is verified sound. Stage B reworks the `useChat` catch (`:264-275`): branch on `AdapterHttpError` (status/body-derived message; suppress the inline message for tier-403 the UpgradeModal already handles), keep "Backend is offline" only for genuine network errors, and add the `!last` empty-array guard the stream updater has (`:133-136`). Test targets `useChat` with a rejecting `adapter.sendMessage`.
**(c) 401 → silent refresh → single retry.**
- In the shared request core: on `res.status === 401` (path not auth-exempt, not already retried): refresh token, re-issue once. Still-401 → normal failure path.
- **Token-versioned (MEDIUM fix):** each request records the token it was issued with; on 401, if `this.authToken !== issuedToken` the refresh already happened — skip it and retry immediately with the current token. This stops a post-restart straggler burst from chaining N sequential refreshes past the single-flight window.
- `refreshSessionToken()` is single-flight and — unlike the legacy best-effort `fetchSessionToken()` — **THROWS on failure** so the retry path fails fast with the true cause (refresh endpoint unreachable) instead of silently retrying token-less into a guaranteed second 401. Both pinned in `adapter.authgate.test.ts` (straggler-401 → exactly one token fetch; refresh-endpoint-down → loud failure).
- Treat ALL 401s as refreshable (`MISSING_TOKEN`/`INVALID_TOKEN`/code-less/`SESSION_TIMEOUT`) — refresh is harmless when it can't help; auth rejection happens in the server's `onRequest` hook before any handler side effect, so retrying non-GET is safe (`security-middleware.ts:316-340`). Never refresh-retry `/api/auth/session-token` itself.
### 1.2 Boot-path surfaces (Stage B)
Shared helper: **`useRevalidateOnError(errored, fn)`** — one new hook mirroring the `useOfflineStatus.ts:80-96` triple-listener (`online` + `visibilitychange→visible` + `focus`) **plus the `waggle:connect-settled` bus event**, firing one immediate revalidate, keyed to "last attempt errored" so healthy surfaces don't refetch per focus. The bus leg matters: focus never fires on the normal desktop launch where the window already has focus.
**(d) Tier — no silent FREE (severity-critical).**
- `ShellContext`: add `tierResolved: boolean` + `tierError`. `refreshTier` catch: set `tierError`, **touch neither `billingTier` NOR `trialInfo`** (MEDIUM fix — today's failure path also clobbers a previously-good trial countdown with undefineds; move the `setTrialInfo` inside the resolved branch). `tierResolved` set true on ANY successful response, even an unrecognized tier string (else the nag-gate stays closed on a healthy session). Initial `'FREE'` stays as the *fail-closed capability default* — verified correct for the nav: `getDockForTier` (`AppShell.tsx:193`) only HIDES TEAMS entries while unresolved, renders no upsell copy, and recomputes when tier resolves. **Do not wire `tierResolved` into the nav** (comment it as the intentional fail-closed consumer).
- Gate-vs-nag classification (verified table, full version in review record): TrialExpiredModal + StatusBar trial badges already structurally safe; UpgradeModal event-driven, safe; **the two defective nag surfaces are below**.
- `useBilling` (Settings→Billing tab, sole consumer `SettingsApp.tsx:99`): on refresh failure today, tier stays default-`'FREE'`, error stays null, and the tab renders "Free tier — upgrade to unlock all features" + FREE badge + purchase grid **as fact** (`SettingsApp.tsx:498-555`). Post-Stage-A every getTier failure funnels here — the fix is mandatory: resolved/error shape, unresolved/error rendering instead of the FREE card, revalidate via the shared helper. (Ratification note: useBilling is not one of D3-4's two named surfaces but is the same monetization-defect class — D3-4 extension, recorded in the decision log.)
- **NEW — second tier-as-fact surface (HIGH, found by verification):** SettingsApp's General tab renders a separate `'{tier} plan'` badge from its own `getSettings()`-fed state (`SettingsApp.tsx:54/157/239-241`, `.catch(() => {})`, `?? 'FREE'`) — visible to every user. Fix: derive the badge from the same resolved billing state as the Billing tab (single source, kills the two-tabs-disagree divergence). Test: a getSettings/getTier failure never renders "FREE plan".
**(e) `useWorkspaces` — resurrect the dead error channel + recovery.**
- catch: `setError(message)` (channel exists at `useWorkspaces.ts:9`, never set). Keep the previous list on failure. Recovery via `useRevalidateOnError` (focus + connect-settled). Workspace rail shows a retry affordance instead of a permanently empty list.
**(f) LoginBriefing — failure ≠ Day-0, and actually retries (HIGH fix).**
- Outer `catch { /* ignore */ }` (`LoginBriefing.tsx:162`) → `errored` flag → compact "couldn't load your briefing" line instead of the Day-0 demo bubbles; brag header stops rendering `'Loading…'` forever (`:192`).
- Defer the batch until connect-settled (consume `useService().connecting` like HomeCockpit `:443/:485`) **and wire `useRevalidateOnError`** — v1 promised "retrying" in the UI copy without wiring any mechanism; the ruling names this surface explicitly. Acceptance check asserts recovery, not just the errored line.
**(g) Crash-class verification (fixed-by-(b), test-pinned).**
- HomeCockpit `RecentWorkspacesPanel` (`HomeCockpit.tsx:160/324/573`): error-body briefing no longer passes `!briefing`. Add `?.` guard + test.
- `ComplianceDashboard.tsx:274` (verified: this IS the live-confirmed "CockpitApp undefined.totalInteractions" — sole deref in the tree, mounted by `CockpitApp.tsx:310`): post-throw lands in its existing catch → error panel + Retry. Add `?.` guard + test.
- `CreateWorkspaceDialog.tsx:661/665` (`setTemplates(undefined)`): verify existing `.catch` path + guard.
**(h) One-shot error-caches in plan-touched territory (MEDIUM ruling-fidelity fix).**
The plus clause ("error states never cache as valid-empty; focus/visibility revalidation on errored surfaces") carries no boot-path qualifier. Cheap wirings (~3 lines each, helper exists): `MCPHubApp.resolvableMcpNames` (`:110-116` — already connect-gated, so the adapter gate adds nothing there; its `.catch(() => new Set())` caches server faults as valid-empty for the session, hiding Install buttons) and `ComplianceDashboard.refreshTemplates` (`:109-112`, same class). The remaining one-shot caches (ChatWindowInstance `FALLBACK_MODELS`, TemplatesView, AgentBuilder catalogs) stay deferred to P7 — honest rationale: the 401-retry leg cures their *restart* instance and the live-confirmed D3 ledger scopes to boot-path; the narrowing is recorded as a D3 implementation note in the decision log (see §3), not self-granted silently.
### 1.3 Explicit non-goals (ledger, don't build)
- Deriving the adapter default base from `window.origin` in dev (p1a residual, not D3).
- Per-app one-shot caches beyond §1.2(h)'s two (P7, with the decision-log note).
- `getPermissions`' `.catch(() => {})` → stays (fails closed to `'normal'` autonomy — the safe direction; a boot-window failure pins 'normal' for the session, acceptable).
- Team-mode Clerk 401 semantics (different deployment; retry treats code-less 401s the same).
- `CapabilityRequestCard.tsx:55` any-403-as-tier (pre-existing) — P7.
- `connectWebSocket` dead code (`?token=null` when called pre-token) — P7 removal candidate.
- Stale `settings-tier-filter.ts:8-9` comment + orphaned `onboarding-tier-filter.ts` (zero prod consumers) — P7.
### 1.4 SSE channels — discovered defect, server-side, OUT of P1b scope (flagged to founder)
**Finding (CRITICAL, live-verified):** all five EventSource SSE channels are 401-dead in every default (D1-enforced) run — not a boot race, a permanent failure: the bearer hook gates every `/api/*` GET, EventSource cannot send headers, no SSE route accepts `?token=`, and the `subscribe*` noop-guards + `es.close()`-in-`onerror` mean nothing ever retries. Notifications, live events, subagent status, waggle signals, and harvest progress (silent: import works, no progress UI) only function under `WAGGLE_TRUST_LOCALHOST=1`.
**Why not fixed here:** the fix is a server auth-model change (the proven in-repo pattern is `/ws`: middleware-exempt + per-route `?token=` validation, `index.ts:2127-2134`) plus client reconnect design (stop closing in `onerror`, resubscribe on connect-settled) — one coherent follow-up ("SSE auth + reconnect"), not two halves. D3's ratified text is the adapter/fetch gate; expanding into server security middleware mid-phase without a register entry repeats the pattern the register exists to prevent.
**Ask:** ratify either (i) a P1b-follow-up stage in this PR (server `?token=` on 5 SSE routes + client lazy-open/reconnect), or (ii) a P2 line item. Until then: P1b changes nothing SSE-side; acceptance checks are scoped to the fetch layer.
## 2. Execution stages
**Stage A — adapter structural core.** `adapter.ts` + `boot-connect.ts` (+1-line main.tsx import): memoized connect + watchdog + epoch + healthProbe single-flight, `ensureReady` 4-state gate with settled-failure re-arm, `AdapterHttpError` (message-first pin), throw-on-`!ok`, `fetchRaw` + two-class migration (envelope getters + BackupApp), eraseData/startTrial legacy-prefix wrappers, 401-refresh-retry (token-versioned, throwing refresh, single-flight), uploadFile/ingestFile through the core. `adapter.authgate.test.ts`: deferral states ×4, same-tick dedup, watchdog (hung body → connect settles, gate releases), epoch (setServerUrl mid-flight → no clobber), retry (once-only, straggler single-fetch, refresh-down loud failure, loop guard), throw shape + message precedence, 403 dispatch on both paths, exempt paths, **zero network at module import / construction**, envelope pins (hard exit criterion), sendMessage throw. Run the 7 adapter test files + new. Commit.
**Stage B — boot-path surfaces.** `useRevalidateOnError` hook; `ShellContext` (tierResolved/tierError/trialInfo preservation); `useBilling` + SettingsApp Billing tab unresolved state + General-tab badge single-sourcing; `useWorkspaces` error+recovery + rail retry affordance; `LoginBriefing` (connect-gate, errored state, revalidation); `useChat` catch rework; crash guards (HomeCockpit/ComplianceDashboard/CreateWorkspaceDialog); §1.2(h) two wirings; ServiceProvider retry/backoff + `waggle:connect-settled` dispatch (existing-members-only constraint). Tests per surface (all net-new — verified zero existing render-level tests on these surfaces). Commit.
**Stage C — suite repair + acceptance.** Full FE suite (`node node_modules/vitest/vitest.mjs run --root apps/web`), FE tsc (`node node_modules/typescript/bin/tsc -p apps/web/tsconfig.app.json`). **Expected fallout (corrected by verification): approximately zero** — no adapter-level test pins silent-empty-on-`!ok` (the only silent-default pin, `adapter.memoryStats.test.ts:70-77`, mocks rejection and stays identical); eraseData/startTrial stay green via the legacy-prefix wrappers; the deliberate UX guard at `adapter.startTrial.test.ts:75` (server `message` surfaces) is *honored* by message-first precedence, not regressed. Any actual fallout gets root-caused, not pattern-matched. Commit.
Then: decision-log note (§3) → adversarial review workflow over the diff → fix confirmed findings → live smoke (§4) → PR → merge.
## 3. Decision-log note (append to open-questions.md under D3, one block)
Record as "D3 implementation notes (P1b, 2026-06-11)": (i) the fetchRaw/body-envelope exception class as a ratified-flow-preserving deviation from the literal "throw mandated adapter-wide" (preserves the D4/ApprovalModal security envelope and the documented raw marketplace contract); (ii) the boot-path scoping of the plus-clause revalidation with the P7 ledger for the remaining one-shot caches; (iii) useBilling + Settings-General badge as D3-4 extensions (same monetization-defect class); (iv) the §1.4 SSE defect + pending founder ruling.
## 4. Acceptance checks
1. **Warm-boot race dead (fetch layer):** with a delayed `/api/auth/session-token`, mount-time fetch-layer requests defer and resolve authed; live: boot network log shows zero fetch-layer 401s. (SSE GETs excluded — §1.4.)
2. **Sidecar-restart recovery (fetch layer):** restart sidecar mid-session → next authed call 401s → silent refresh → succeeds. Live: restart, click a workspace, list loads without reload. **Chat:** send after restart streams normally (was: silent empty bubble).
3. **Cold-sidecar boot recovery (new):** sidecar down at boot → surfaces show errors (not empty-as-fact); sidecar up + window focus (or connect-settled) → tier, workspaces, briefing recover without reload.
4. **Tier never silently FREE:** getTier failure → `billingTier` AND `trialInfo` untouched, `tierResolved=false`, no upsell nag, Billing tab + General badge show unresolved (not "FREE plan"); recovery on focus. Unit tests.
5. **Throw-on-`!ok` adapter-wide:** the six ruling-named getters reject with `AdapterHttpError` (status+body+message-first). Unit tests.
6. **403/UpgradeModal surface intact:** phase4b/phase3c regression tests green; 403 dispatch on both throwing and raw paths; **adapter-level envelope pins green (hard Stage-A exit criterion)**.
7. **useWorkspaces recovery:** failure → error set, list preserved; focus/connect-settled → refetch. Unit test.
8. **LoginBriefing failure state + recovery:** batch failure → no Day-0 bubbles, errored line; focus/connect-settled → briefing loads. Unit test.
9. **No hang, no drift:** never-connect tests pass through ungated (7 files unchanged); hung-body connect settles ≤ watchdog; failed connect re-arms (not disarms); zero network at module import/construction.
10. **Full FE suite green + FE tsc 0.**
## 5. Rollback
Single revertable arc on `feature/ux-refactor-p1b-authgate`; tag `checkpoint/pre-authgate-2026-06` = `fa3797c`. No data migrations, no localStorage schema changes. Stage A independently revertable.

46
docs/ux-refactor/p1b-plan-review-record.md Normal file
View File

@@ -0,0 +1,46 @@
# P1b Plan — Adversarial Review Record (2026-06-11)
Two workflow rounds over `p1b-auth-gate-plan.md` v1 (6 lenses; round 1's contract lane completed, 5 lanes re-ran in round 2 after a session-limit failure). **24 confirmed / 0 refuted / 16 LOW.** Every confirmed finding was independently verified by a skeptic agent against the live tree before acceptance. All are folded into plan v2; this file records them so they are not re-found, plus the LOW-grade confirmations of plan claims.
## Confirmed (folded into plan v2)
| # | Sev | Lens | Finding → v2 disposition |
|---|-----|------|--------------------------|
| 1 | CRITICAL | contract | `installMcp` is a typed JSON getter whose error body carries the ApprovalModal security envelope (`{requiresApproval, blocked, severity}` on 403/422); throw would kill the flow and the phase4b tests (method-level mocks) are blind → body-envelope migration class + adapter-level pins as hard Stage-A exit criterion |
| 2 | CRITICAL | sse-ws-auth | All five EventSource SSE channels 401-dead in EVERY default run since D1 (bearer-gated /api GETs; EventSource can't send headers; no `?token=` on those routes; only `/ws` has the pattern and `connectWebSocket` is dead code) → plan §1.4, founder ruling requested, P1b scope unchanged |
| 3 | HIGH | deadlock | Gate-never-released hang: `fetchWithTimeout` bounds headers only; connect's `res.json()` reads unbounded → connect watchdog (~15s end-to-end deadline) |
| 4 | HIGH | deadlock | Gate disarms after failed early connect (default Tauri cold-sidecar path) re-opening the ungated burst with no recovery (NetworkError never triggers the 401 leg; focus never fires on an already-focused window) → settled-failure re-arm + ServiceProvider backoff + `waggle:connect-settled` bus consumed by all Stage-B surfaces |
| 5 | HIGH | deadlock | SSE half of the boot race unfixed and v1's "if and only if they attach the token" conditional matched zero methods (noop-guards = session-long dead subscriptions) → §1.4 honest de-scope; subscribe* untouched; acceptance check 1 scoped to fetch layer |
| 6 | HIGH | test-blast | `adapter.eraseData.test.ts`/`adapter.startTrial.test.ts` pin method-level `Erase failed (400): <detail>` messages with **message-first** detail; v1's error-first precedence inverted it → message-first pin + legacy-prefix wrappers in both methods |
| 7 | HIGH | sse-ws-auth | Chat `sendMessage` silent-empty-bubble on stale/missing token; plan's (b)+(c) verified the correct fix; `useChat` catch defects confirmed → no design change; Stage B useChat rework retained |
| 8 | HIGH | tier-ui | Definitive gate-vs-nag table (nav = pure capability gate, do NOT wire tierResolved; TrialExpiredModal + StatusBar badges already safe; UpgradeModal event-driven safe) → §1.2(d) classification |
| 9 | HIGH | tier-ui | useBilling failure renders FREE-as-fact + upgrade CTAs in Settings→Billing with zero error indication; post-Stage-A every failure funnels there → mandatory reshape |
| 10 | HIGH | tier-ui | SECOND tier-as-fact surface missed by v1: SettingsApp General-tab `'{tier} plan'` badge fed by `getSettings` (`:54/157/239-241`) → single-source from resolved billing state |
| 11 | HIGH | d3-fidelity | LoginBriefing got no revalidation wiring while v1's own UI copy promised "retrying" (plus-clause violation on a ruling-named surface) → wired to `useRevalidateOnError`, acceptance asserts recovery |
| 12 | MEDIUM | deadlock | setServerUrl mid-flight: stale connect continuations clobber baseUrl/localStorage/token (fallback can persist DEFAULT_SERVER over the user's new URL) → epoch guard |
| 13 | MEDIUM | deadlock | Straggler 401s chain sequential refreshes past single-flight; refresh failure semantics unpinned (silent token-less retry) → token-versioned retry + throwing `refreshSessionToken` |
| 14 | MEDIUM | deadlock | healthProbe not single-flighted; races useOfflineStatus's exempt /health probes on shared `this.baseUrl` mutation → single-flight + local-var fallback + epoch commit |
| 15 | MEDIUM | deadlock | `uploadFile`/`ingestFile` bypass the chokepoint entirely (raw `fetchWithTimeout`, hand-attached token, unconditional `res.json()`) → routed through the shared core |
| 16 | MEDIUM | test-blast | "~30 adapter test files" wrong by ~4× (actual 7; 2 not behavior-identical) → corrected, eraseData/startTrial carved out |
| 17 | MEDIUM | test-blast | Stage C's expected-fallout class is empty (no silent-empty-on-!ok pins exist); real risk was a mechanical rewrite erasing the startTrial message-surfacing guard → Stage C expectation rewritten |
| 18 | MEDIUM | test-blast | Call-count tripwire: kickoff must stay OUT of adapter module scope/constructor (5 files index `mock.calls[0]`) → zero-network-at-import/construction pin |
| 19 | MEDIUM→LOW | test-blast | 9 component test files render real ServiceProvider over hand-rolled mocks → ServiceProvider existing-members-only constraint |
| 20 | MEDIUM | sse-ws-auth | SSE has zero restart/error recovery even where it could work (`es.close()` in onerror; once-only subscribes) → part of the §1.4 "SSE auth + reconnect" single follow-up |
| 21 | MEDIUM | tier-ui | refreshTier failure path also clobbers trialInfo (StatusBar trial countdown transiently wiped); tierResolved semantics for unrecognized-tier unpinned → both pinned in (d) |
| 22 | MEDIUM→LOW | tier-ui | Nav `getDockForTier` confirmed pure capability gate → do-not-touch advisory + comment |
| 23 | MEDIUM | d3-fidelity | P7 deferral defense factually wrong for its own exemplar (MCPHubApp already connect-gated; gate adds nothing) and plus-clause narrowing was self-granted → two cheap wirings in §1.2(h) + decision-log note §3 |
| 24 | HIGH | contract (r1) | (v1 round) `installMcp` misattribution — superseded by #1's fuller statement; plus `addCustomMcp`/`updateMcpPermissions`/`revokeMcp`/`startMcp`/`stopMcp`/`testMcp` body-envelope class, `useChat` consumer correction, `AdapterHttpError.message` pin, BackupApp-only among direct sites, uninstall false-success fix |
## LOW (verified clean / advisory — no plan change beyond what v2 already carries)
- ensureReady 3-state ambiguity + sync memo assignment + settled-success memo retention → pinned in v2 §1.1(a).
- "Pass-through stays armed by accident of the import graph" → `boot-connect.ts` first-import + zero-network pin close it structurally.
- Setup files clean; no test imports main.tsx/App.tsx; Stage B existing-suite fallout ≈ zero (all coverage net-new).
- No adapter-level raw/envelope pins exist anywhere (confirms blindness diagnosis) → hard exit criterion.
- `subscribeHarvestProgress` degrades silently under 401 (import works, no progress UI) — noted in §1.4.
- `connectWebSocket` dead code, builds `?token=null` pre-token → P7 ledger.
- Trial-expired modal verified already-safe; UpgradeModal verified safe; KvarkNudge doesn't exist (resolves to SettingsApp Enterprise CTAs — covered by the Billing-tab fix).
- useFeatureGate / settings-tier-filter / persona-tier / dock-nudge / onboarding-tier-filter all local-state driven — excluded; stale comment + orphaned file → P7.
- `ComplianceDashboard.tsx:274` verified as THE live-confirmed CockpitApp crash; its `refreshTemplates` valid-empty cache added to §1.2(h).
- Ruling coverage sweep: all four D3 sub-items + five live-confirmed targets covered; six named getters stay on throwing path; deviation-class note → §3.
- Scope-creep audit: nothing cut-worthy; useBilling tagged as D3-4 extension.

62
docs/ux-refactor/p1b-residuals.md Normal file
View File

@@ -0,0 +1,62 @@
# P1b Auth Gate — Review Residuals (2026-06-11)
Source: adversarial review workflow over `fa3797c..HEAD` (5 lenses, 23 agents; 17 confirmed → ALL fixed in `54ec629`; 0 refuted; 26 LOWs triaged below). Plan-review record: `p1b-plan-review-record.md`.
## LOW findings fixed alongside (in 54ec629)
- getJobStatus 404 console-spam from GroupDetail's 1.5s poll → 404s no longer logged
- ComplianceDashboard art19/art26 sibling derefs unguarded → `?.` guards
- useChat catch updater returned a clone (forfeited setState bail-out) → returns `prev`
- ServiceProvider retry-timer unmount race → `mounted` ref
- Watchdog TimeoutError message read "Request to connect() timed out" → carries baseUrl
- reconnect() silent no-op after success memo → `forceReconnect()`
- launchTool/killTool envelope mapping dead → fetchRaw (with the HIGH manageHooks fix)
## LOW residuals — ledgered, not fixed (P7 / by-design)
- [ ] **~30 dead `if (!res.ok)` blocks remain in adapter.ts** (installSkill, installPack, testSkill, getStarterPacks, getCapabilityPacks, getMarketplacePacks, runAgent, spawnAgent, cron family, wiki/compliance exporters, …) — unreachable post-chokepoint, behavior unchanged (AdapterHttpError is field-compatible incl. runAgent's C23 `{status,body}` consumer). Removing them is a large mechanical diff; P7 dead-code commit.
- [ ] **fetchRaw has one residual throw path**: a 401 whose token refresh fails (loud by design) propagates out of fetchRaw. Every envelope consumer has a catch fallback (verified at review). Acceptable: the alternative (swallowing refresh failures on the raw path) hides the true cause.
- [ ] **Adapter-gate re-arm successes don't dispatch `waggle:connect-settled`** — after ServiceProvider's 3 retries exhaust, a late sidecar recovery propagates to errored surfaces via the next request's re-arm + focus/online events, not the bus. Matches the plan's design; if desktop telemetry shows stuck-errored-until-focus sessions, dispatch the bus event from the adapter's re-arm success (needs a window-reference guard in the adapter).
- [ ] **Retry-loop `connecting` toggles re-run the 8 gated mount-loads per cycle** (~3 doomed loads over ~13s while the sidecar is down; error-panel→skeleton flicker). Bounded by the retry cap; cosmetic under a down sidecar.
- [ ] **HomeCockpit Retry click during a retry-in-flight window** can render a stuck skeleton until the next settle (its `cancelled` ref interplay with the now-toggling `connecting`). Self-heals on settle; P7 with the dock-era residuals.
- [ ] **ServiceProvider can broadcast `connected:true` from an epoch-stale connect** after `setServerUrl` mid-flight (adapter state stays correct; provider state diverges until next reconnect). Zero production `setServerUrl` callers today; the Settings server-URL flow should call `forceReconnect()` when built.
- [ ] **"Zero network at module import" pin is partially vacuous** (spy installed in beforeEach, after module eval). Constructor-time is genuinely pinned; import-time is structurally enforced by boot-connect.ts being the only module-scope caller. A vi.resetModules-based import-time pin is possible if this ever regresses.
- [ ] **subscribeHarvestProgress silently degrades under 401** (import works, no progress UI) — part of the §1.4 SSE follow-up.
- [ ] `connectWebSocket` dead code (builds `?token=null` pre-token) — P7 removal candidate (also §1.4's candidate auth pattern).
- [ ] Stale `settings-tier-filter.ts:8-9` comment + orphaned `onboarding-tier-filter.ts` — P7 cleanup.
- [ ] `CapabilityRequestCard.tsx:55` any-403-as-tier (pre-existing) — P7.
## Live-smoke scope notes
Acceptance checks 1–3 (boot 401s / restart recovery / cold-sidecar recovery) are fetch-layer only — the five EventSource SSE channels are 401-dead in default config **pre-existing since D1** (see §1.4 of the plan + decision-log note; founder ruling pending). Chat streaming (POST /api/chat) IS covered — it authenticates via headers.
## Live-smoke RESULTS (2026-06-11, vite:8080 + branch sidecar:3501 via SIDECAR_TARGET; browser base = localhost:8080)
- **✅ Check 1 — boot burst fully gated, ZERO fetch-layer 401s.** Warm-boot network log: `/health` → `/api/auth/session-token` FIRST, then 20+ API requests all 200 (workspaces, tier, permissions, briefing, identity, memory search/stats, per-workspace contexts). Pre-P1b this was a token-less 401 burst.
- **✅ Check 2 — stale-token recovery without reload.** Live sequence captured: `GET /api/memory/stats → 401` (stale token) → `GET /api/auth/session-token → 200` (silent single-flight refresh) → retried `GET /api/memory/stats → 200`. Same origin, no page reload, no user action.
- **✅ No crashes under server failure.** Sidecar killed mid-session: surfaces showed errors (vite proxy 500s), `useAgentStatus` logged + kept backing off, NO error-boundary hits, NO undefined-deref crashes (the HomeCockpit/ComplianceDashboard crash classes held). Healthy-path LoginBriefing rendered full real data (brag line, highlights, summaries).
- **✅ §1.4 SSE defect live-confirmed:** `/api/waggle/stream` + `/api/notifications/stream` EventSource 401s in console — exactly the ledgered pre-existing class.
- **Dev-env note (not a P1b defect):** with TWO sidecars running (branch:3501-via-proxy + long-running pre-refactor:3333), a kill-window health probe triggers the pre-existing FR#10 auto-discovery fallback to `DEFAULT_SERVER` (3333) and persists it — the smoke's second restart attempt hopped servers this way (then 404'd on post-refactor routes the old sidecar lacks). In production DEFAULT_SERVER == the configured URL, so the fallback is inert and restart recovery is purely the 401-refresh leg (demonstrated). Recipe: re-set `localStorage['waggle:server-url']` after any kill-window.
- Check 3 (cold-sidecar boot → errored surfaces → recovery on connect-settled/focus) is pinned by unit tests (`p1b-authgate-surfaces.test.tsx` recovery cases ×4 + ServiceProvider backoff); the dual-sidecar fallback magnet makes a clean live repro impractical in this dev env.
## P1b-SSE follow-up (founder-ratified 2026-06-11) — review residuals
Adversarial review (3 lenses, 8 agents): 5 confirmed (3 HIGH — all fixed: fan-out subscriptions, named-event listeners for audit/signal, handshake filter), 0 refuted, 17 LOWs. Ledgered LOWs:
- [ ] **Flapping server = constant 1s retry** (backoff resets in onopen; an open-then-drop loop never escalates) + each round fires a token refresh; two streams on /api/notifications/stream could brush the 100/min default rate limit in a pathological crash-loop. Acceptable for loopback; revisit if telemetry shows 429s.
- [ ] **No event replay on any channel** — events emitted during a backoff window are dropped (no `id:`/Last-Event-ID anywhere). Notifications could close the gap for free by refetching history on reopen — P7 candidate.
- [ ] **/api/harvest/progress is the only SSE route with no heartbeat** and an unguarded write in its listener — P7 server-side polish.
- [ ] **setServerUrl doesn't tear down live streams** (old-server events keep arriving until natural error; self-heals on next reopen). Zero production setServerUrl callers; fold into the future Settings server-URL flow.
- [ ] **Socket budget**: realistic ceiling 4 concurrent SSE sockets vs Chromium's 6/host HTTP/1.1 cap (2 fetch slots remain). Multiplexing events/waggle onto the notifications socket's named-event channel would collapse 3 sockets to 1 — P7.
- [ ] **Auth 401s bypass the rate limiter + non-constant-time token compare** — pre-existing properties of the header path inherited by the query transport; 256-bit CSPRNG token makes both moot on loopback.
- [ ] `?token=` (empty) reports MISSING_TOKEN instead of INVALID_TOKEN — cosmetic.
- [ ] Stale `_connected`-gate comments in room-parallel-agents.spec.ts mock + backend-map docs — P7 doc sweep.
Security lens verdict: query-token transport sound — GET-only, allowlist-only, header-absent-only; no leakage sink beyond the existing /ws posture (no server URL logging; EventSource URLs don't enter history/cache/referrer).
## P1b-SSE live-smoke RESULTS (2026-06-11)
- **✅ Server auth contract:** `GET /api/notifications/stream?token=<valid>` → 200 (stream holds); without token → 401. Verified via curl against the branch sidecar.
- **✅ Browser streams LIVE:** both always-mounted streams (`/api/waggle/stream`, `/api/notifications/stream`) connect **200 with the token attached** — the exact requests that were 401 in the P1b smoke the day before.
- **✅ Reconnect loop proven live:** sidecar killed mid-session → both streams errored → the loop reopened them with a FRESHLY REFRESHED token on capped backoff (console shows retries carrying a new token, not the stale one). After re-pointing at the proxy (dev-env step), streams reconnected **200 with the restarted process's rotated token** — error→refresh→reopen full cycle observed.
- **Dev-env artifact (same as the P1b smoke, ledgered):** during the kill window the health-probe fallback hops baseUrl to DEFAULT_SERVER (3333 = the long-running PRE-refactor sidecar without the new middleware), so backoff retries 401 against the wrong server until re-point/reload. Production has one server; the fallback is inert there.

103
docs/ux-refactor/p2-verification-record.md Normal file
View File

@@ -0,0 +1,103 @@
# P2 — Verification Record: Home Cockpit + Workspace Desktop vs Brief v2.1 (2026-06-11)
**Phase:** P2 per the ratified sequence (decision register, `deltas/open-questions.md`) — "verify + J08 alert".
**Scope verified:** PRD §12.1 (Home Cockpit) + §12.2 (Workspace Desktop) functional requirements, states,
and acceptance criteria, against main @ `4e3d65d` (post-P1a conversion, post-P1b auth gate).
**Method:** 4-lane verification workflow (Home FRs / Home states+AC / Desktop FRs / Desktop states+AC),
every claimed gap adversarially refuted by an independent agent; 2 scout lanes (J08 implementation map,
wizard onFinish live-run map). 20 agents. Then a 4-lens adversarial diff review (16 agents) over the fixes.
## Verdict
**25 of 37 verified items met or ratified-divergence; 12 confirmed gaps (1 HIGH, 5 MEDIUM, 6 LOW);
2 gap claims refuted (first-run empty state and AC-k reachability are MET).** The HIGH and all
tiny/small verified defects were fixed in this phase; feature-shaped gaps are ledgered below.
## Fixed in P2 (this phase)
| # | Sev | Item | Fix |
|---|-----|------|-----|
| G8 | HIGH | "Artifact ready" state dead — `getWorkspaceFiles` returned the `{files:[...]}` envelope; `normalizeArtifacts` silently rendered Artifacts empty forever | Envelope unwrap at the fetch layer (`adapter.ts`) + fetch-layer regression lock (`adapter.files.test.ts`) — component tests mock the adapter and were structurally blind here |
| G0 | MED | Greeting never showed the user's name (B8 backend half landed, FE never consumed `userName`); raw ISO date rendered verbatim | `personalizeGreeting()` server-side (name spliced into the first clause); `formatBriefingDate()` in `HomeCockpit` |
| G4 | MED | J08 alert absent (D6 verification item — Journey 6 step 1) | `needsReviewCount` on `GET /api/home/briefing` (personal-mind, 200-frame bound matching the Memory Center's own window) + attention banner with Review CTA + deep-link chain (below) |
| G1 | LOW | Ranking recency-only; PRD says "recency AND priority" | `applyPriorityRanking()` — bounded boost: each pending/blocked item buys up to 5×1h of effective recency |
| G10 | LOW | Header `type`/`status` hollow — context route never projected them | `/api/workspaces/:id/context` now projects `description`/`type`/`status` (FE already rendered all three) |
| G11 | LOW | Stale workspace URL claimed "server offline"; errored screen sticky | Duck-typed `AdapterHttpError` branching: 404 → "Workspace not found" + go-Home CTA, 403 → permission; Retry button + `useRevalidateOnError` (armed for the transient offline state only) |
**J08 deep-link chain (new):** Home banner → `waggle:open-app {appId:'memory', filter:'unreviewed'}` →
AppShell shim (stash + `/memory?filter=unreviewed`) → `MemoryRoute` re-stash on cold load
(AutomationsRoute pattern, so typed/refreshed URLs work) → `MemoryCenterTab` consumes (stash + live
event), validates against `STATUS_FILTERS`, seeds the status filter. Count and view share the same
bound (200) and the same mind (personal), so the number always matches what the user lands on.
**Diff review (4 lenses, adversarial):** 9 confirmed findings (0 critical/high; 2 medium — both test
gaps), 3 refuted. All 9 fixed pre-commit: MemoryRoute URL re-stash, revalidation gated to offline-only,
monotonic request guard in `MemoryCenterTab.load()` (also cures the pre-existing rapid-filter race),
`_phase1-contract.md` §2 amendment, queryString filter pin, route-level ranking inject pin,
focus-revalidation pin, needs-review comparison query corrected to `limit=200`.
## Met (verified with file:line evidence — highlights)
- Home: workspaces ranked w/ one-click Continue (real data, personal-only per A2), overnight summary
(memories/artifacts/automations/failures), suggested next actions, quick capture (all 4 kinds wired
to `/api/quick-capture`), Ctrl+K hint (D9 "Win+K" pill is gone), loading/first-run/normal/offline/
overnight-failure states, P1b error+retry path (cold-load crash guard survived conversion).
- Desktop: all 8 PRD tabs present + URL-driven (founder two-seam edit), chat-as-one-widget (D1-4)
with ChatHost keep-alive, 5/6 canvas widgets on real feeds, right panel, fixed layout, agents-running
indicator, no-memory/active/agent-running/permission/offline states.
- Refuted as gaps (i.e. actually met): Home first-run empty (Journey 2), Desktop AC-k reachability
(memory/artifacts/agents/skills/tasks/automations/settings all reachable from the workspace).
- Ratified divergences (PRD ≠ code is correct): D5 team/share tier-hidden; configurable widgets
later-phase.
## Residuals — ledgered, NOT fixed in P2
| Item | Sev | Size | Owner |
|------|-----|------|-------|
| S02-FR2: Memory/Timeline/Settings/Research tabs are placeholders (capability is 1 click away via left-nav routes) | MED | M | **P3 (D2)** for the Memory tab embed; rest P7 |
| S02-FR5: status bar — automations-active + MCPs-connected chips unbuilt (feeds exist) | MED | S | P7 |
| S01-R4: `upNext` only carries cron schedules; awareness 'task' rows never aggregated; 'event' has no calendar substrate (defensible deferral) | MED | S | P7 (tasks); register note (events) |
| S01-R7: `activeModels` never populated server-side; FE tile inert | LOW | S | P7 |
| S01-R2 aggravator: priority data only computed for the recency top-8 (`MAX_RANKED_WORKSPACES` fan-out cap) — a high-pending workspace outside the top-8 can't surface | LOW | S | P7 |
| S02-FR3: research-overview widget unbuilt (Research feature wholesale later-phase) | LOW | S | P7 / register note |
| S02-state-f: sync conflict N/A until team sync (Phase 5 founder-deferred) — record in the D15 state grid | LOW | doc | P7 (D15) |
| S02-AC-j residue: `status` can never be non-active (update route doesn't accept status/type) | LOW | S | P7 |
| J08 count bound: getRecent(200) scan undercounts past 200 unreviewed frames (consistent with the Memory Center view itself; large E-11 imports could exceed it — SQL count if exactness ever matters) | LOW | S | P7 |
| AppShell shim filter passthrough has no mounted-router test (queryString + route-level stash are pinned) | LOW | S | P7 |
## Acceptance check 8 — wizard onFinish seeding (LIVE-RUN, first ever)
**Result: PASS — after fixing two real defects the run itself surfaced.** Driven via Playwright
against a fresh sidecar (3333) + Vite dev (8080) with `?forceWizard=true`, three full wizard runs.
**Defect 1 (state):** `loadState()` re-evaluated the `?forceWizard` reset on every call — including
the `waggle:onboarding-sync` reload fired by every wizard save. The moment workspace-create persisted
`{workspaceId}`, the sync reload reset onboarding to `{completed:false, step:0}` and wiped it; `onFinish`
then ran with a fallback `local-*` id and the seeding chain silently broke (run 1 ended force-completed
by the returning-user auto-complete, user stranded on `/home`). Fix: once-per-page-load latch
(`forceWizardConsumed`), pinned by `p2-onboarding-forcewizard.test.ts`.
**Defect 2 (navigation):** the wizard finishes at pathname `/`; completing onboarding (normal-priority
state) commits before `handleOnboardingFinish`'s navigate (a `v7_startTransition` update), so the shell
mounts at `/`, `IndexRedirect` fires, and its `/home` navigation queues after the wizard's and wins.
Fix: one-shot `pendingWizardLanding` handoff — `IndexRedirect` honors the wizard's landing target.
Live-verified; not unit-pinned (module-internal handoff — the live smoke is the evidence; ledgered).
**Run 3 (post-fix) assertions, all green:** lands on `/workspaces/p2-smoke-three/chat` (real server id,
not `local-*`); widget header `P2 Smoke Three · general-purpose` (wizard persona active); composer
prefilled `Hello! What can you help me with?` (QW-1 starter, NOT sent); `waggle-chat-state-v1` persisted
the persona; zero chat-completion/LLM requests in the network log. Smoke workspaces deleted after.
**Flagged for founder (production-class, NOT fixed here):** the returning-user auto-complete
(`useOnboarding.ts` "Bug #2" effect) completes the wizard whenever a `useOnboarding` instance mounts
with `completed:false`, no `forceWizard` in the URL, and ≥1 workspace on the server. Its own comment
says the boot-time `wsManager.ensureDefault` stub counts. If `ensureDefault` seeds `default-workspace`
before first FE mount on a clean install, **a truly-new production user may never see onboarding at
all** (and the Tauri filesystem first-launch flag does not gate this effect). Needs a clean-install
verification (P4/D12 binary work is the natural place); until then this is a suspected
launch-integrity defect, not a confirmed one.
## Gates at close
FE tsc 0 · server tsc 0 (after `npm run build:packages`) · FE vitest 75 files green ·
server-local green · `npm run lint` exit 0. Suite counts in the session handoff.

120
docs/ux-refactor/p3-memory-center-plan.md Normal file
View File

@@ -0,0 +1,120 @@
# P3 — D2 Two-Mind Memory Center (plan, 2026-06-11)
> **STATUS (2026-06-11, end of session): SHIPPED.** All sections below built as designed,
> then hardened by a 36-agent adversarial review (19 confirmed findings incl. 1 HIGH — all
> fixed; see `p3-review-record.md`). Final gates: FE 874/874 · server-local 891/891 · both
> tsc 0 · lint 0. Live Playwright runs verified all six flows against real data twice
> (pre- and post-review-fixes) AND caught two pre-existing defects the unit suites couldn't
> see (fixed + documented in the Live-run findings section at the bottom).
**Ratification:** D2 (open-questions.md §527): standalone `MemoryCenterApp` (ArtifactCenterApp
shape), top-level two-mind split — "About you" (Personal Mind) / "About this work" (Workspace
Mind, per workspace). Reuse `MemoryCenterTab` internals as the per-mind list. Legacy MemoryApp
tabs remain accessible as secondary tabs — restructure the entry, don't delete capability.
Also in P3 per conversion plan §5.3 #1-2: `/:mindScope` implementation + `?tab=` URL→tab wiring;
plus the P2-ledgered S02-FR2 Memory-tab embed in WorkspaceDesktopApp.
## Verified current state
- `GET /api/memory` (memory-center.ts:137) **always merges** personal + workspace stores; no
mind-only selector. Response discriminator: `workspaceId` set ⇔ workspace mind.
- `MemoryCenterTab` is hardcoded personal-mind: `listMemories` without `workspaceId`, and its
mutations (`patchMemory`/`archiveMemory`/`deleteMemoryById`/`mergeMemories`) never pass
`workspaceId` — they would 404 on workspace-mind frames (candidateStores searches workspace
store only when the param is present).
- **Latent id-collision class:** personal and workspace minds are separate SQLite DBs with
colliding autoincrement frame ids. The merged list view can render key collisions and PATCH
`?workspace=X` shadows a personal frame with the same id. The two-mind split structurally
fixes the UI ambiguity (every view is single-mind); the merged legacy server behavior stays
for back-compat but the new UI never uses it.
- `/memory/:mindScope?` route param reserved in App.tsx:68; MemoryRoute reads + voids it.
- AppShell §2.3 shim stashes `{appId, tab, automationId, filter}` and navigates with
`queryString({tab, filter, ...})` — `?tab=` already arrives at the route; only `filter` is
re-stashed today.
- WorkspaceDesktopApp `memory` tab = `TabPlaceholder` (line 982).
- MemoryApp.tsx (347 ln): 7-tab shell (memories/timeline/graph/harvest/weaver/wiki/evolution);
'memories' → MemoryCenterTab; timeline = frames sidebar + detail pane (embedded JSX);
graph = KnowledgeGraphViewer (props from route hooks); harvest/weaver/wiki/evolution are
self-contained. Sole consumer: MemoryRoute.
## Design
1. **Server (additive):** `GET /api/memory` gains `mind=personal|workspace`.
- `mind=personal` → personal store only. `mind=workspace` → workspace store only
(requires `workspace` param → 400 without it; unknown workspace → empty results).
- No `mind` → legacy merge (back-compat; nothing else consumes it after this phase, but
the contract is public).
2. **Adapter:** `listMemories` gains `mind?: 'personal' | 'workspace'`.
3. **MemoryCenterTab** gains optional `{ mind = 'personal', workspaceId }` props.
- `listMemories({ mind, workspaceId: mind==='workspace' ? workspaceId : undefined, ... })`.
- All mutations pass `workspaceId` when mind is workspace (fixes the 404 class).
- Reload on mind/workspaceId change (load deps). Defaults keep the 3 p2 tests + the
WorkspaceDesktop embed call sites compatible.
4. **New `MemoryCenterApp.tsx`** — standalone shell, controlled like the ratified
WorkspaceDesktopApp two-seam pattern:
- Props: `{ mind, onMindChange, tab, onTabChange, workspaceId, workspaceName, ... }` +
pass-through frame/KG props for the legacy tabs (from the route's useMemory /
useKnowledgeGraph hooks, unchanged).
- Tab row = Memories · Timeline · Graph · Harvest · Weaver · Wiki · Evolution (visual
divider after Memories). Mind pills ("About you" / "About this work · {ws name}")
render only on the Memories tab — legacy tabs keep their own scoping (Graph has its
scope selector; Harvest writes personal by design).
- "About this work" with no active workspace → disabled pill + hint (Home selects
workspaces).
- ImportReminderBanner carries over above the tab bar.
5. **Timeline extraction:** MemoryApp's frames-sidebar + detail JSX moves to
`memory/TimelineTab.tsx` (same props, verbatim move). MemoryApp.tsx is then
consumer-less and is **deleted** — every one of its 7 views remains reachable in the new
shell (capability preserved; entry restructured, per D2).
6. **MemoryRoute:** validates `mindScope` (personal|workspace, default/unknown → personal)
and `?tab=` (known tab ids, default memories); keeps the `?filter=` stash (J08 unchanged —
default mind is personal, matching the personal-mind-only needsReviewCount). Mind switch →
`navigate('/memory/'+mind+search)`; tab switch → setSearchParams. URL is the single
source of truth (no internal state fork).
7. **WorkspaceDesktopApp:** memory TabPlaceholder → `<MemoryCenterTab mind="workspace"
workspaceId={workspaceId} />` (S02-FR2 Memory part).
## Tests
- server memory-center: mind=personal excludes workspace frames; mind=workspace excludes
personal; mind=workspace w/o workspace → 400; no mind → merge (regression pin).
- FE MemoryCenterTab: workspace mind passes mind+workspaceId to listMemories; patch/archive/
delete/merge carry workspaceId; personal default unchanged.
- FE MemoryCenterApp: pills render/switch; legacy tabs mount their components; pills hidden
on legacy tabs; disabled state w/o workspace.
- FE route: /memory/workspace lands workspace mind; ?tab=graph lands graph; invalid scope →
personal; /memory?filter=unreviewed still seeds the status filter (J08 pin).
- FE WorkspaceDesktopApp: memory tab renders the per-mind list (placeholder gone).
## Sequencing
1. `feat(ux)`: server mind param + adapter + MemoryCenterTab parameterization + tests.
2. `feat(ux)`: MemoryCenterApp + TimelineTab extraction + MemoryApp retirement + route wiring
+ WS desktop embed + tests.
3. Adversarial review workflow → fixes → live Playwright smoke (mind pills, tab deep-link,
J08 filter, workspace embed) → docs/decision-log note → commit/push.
## Out of scope
Namespacing frame ids across minds (server-wide change, post-launch); Research/Timeline/
Settings WorkspaceDesktop embeds (P7); memory-mcp canonical decision (deferred).
## Live-run findings (2026-06-11 smoke against real data)
1. **KnowledgeGraphViewer hard-crashed on untyped entities** — `n.type.toLowerCase()` threw
on the real 214-entity personal graph (54 rows with no `type`), sending the whole Memory
surface into its boundary. Pre-existing (the old MemoryApp Graph tab crashed identically);
the new `?tab=graph` deep link surfaced it. Fixed with a single-entry `safeNodes` memo
(`type || 'unknown'`, `label || String(id)`); 'unknown' joins the legend as a first-class
chip (verified live: 60 nodes, `unknown 54` chip, no boundary).
2. **Timeline duplicate React keys on real data** — frame id `36` exists in BOTH minds and the
legacy frames API merges them; `key={f.id}` duplicated. The exact cross-mind id-collision
class this plan documented. Fixed: `key={'${workspaceId ?? "personal"}:${id}'}`.
3. **Self-review (pre-smoke): stale rows under the new mind's pill** — on mind switch the old
list stayed rendered until the new fetch landed (`loading && length===0` gate). Fixed by
clearing the list in the mind-switch reset effect; pinned with a never-resolving second
fetch test.
Both live-run defects were invisible to the unit suites for the same reason as P2's
artifacts-envelope HIGH: tests mock the adapter above the layer where real data misbehaves.
The live run remains mandatory phase kit.

57
docs/ux-refactor/p3-review-record.md Normal file
View File

@@ -0,0 +1,57 @@
# P3 — D2 Two-Mind Memory Center: adversarial review record (2026-06-11)
**Workflow:** 6 dimension finders (races / contract / security / parity / tests / ux) → per-finding
adversarial refuter. 36 agents. **19 confirmed / 11 refuted.** First run was VOID (all finders hit
the session limit and returned nothing — recorded here because an empty "confirmed" list from a
dead run is indistinguishable from a clean one unless you check the failures block).
## The HIGH (confirmed independently by 5 of 6 dimensions)
**Cross-mind fall-through on mutations** — `candidateStores` pushed the personal store
unconditionally after the workspace store, and PATCH/archive/DELETE/merge acted on the first store
resolving the id. Frame ids collide across the per-mind SQLite DBs (observed on real data: id 36 in
both minds), so a stale workspace row whose id had vanished from the workspace store would resolve
to — and hard-delete/patch/merge-archive — an unrelated PERSONAL memory, returning 200. The path
became reachable for the first time in this phase (pre-P3, the UI never sent `workspace` on these
mutations). Verifier note: the "two concurrent surfaces" trigger is weak in the single-window app,
but background deletion lanes (W4.3 replace-on-update, compaction, cleanup_frames MCP) + open stale
lists make it ordinary anyway.
**Fix:** mind-strict resolution. `candidateStores(workspace, mind?)` — when the caller declares
`mind`, exactly that store is consulted, no fallback; `parseMind` 400s on invalid values. All five
single-memory routes + merge accept `mind`; the adapter threads it; MemoryCenterTab (the only
caller) always declares it. Legacy no-mind fall-through preserved and PINNED as back-compat.
Server pins: workspace-mind PATCH/archive/DELETE succeed; personal-only id + `mind=workspace` →
404 with the personal frame intact; merge never resolves its id set in personal; 400 contracts.
## Other confirmed findings → dispositions
| # | Sev | Finding | Disposition |
|---|-----|---------|-------------|
| 2 | MED | `mutate()`'s closured `await load()` beats the loadSeq guard — old-mind/old-filter rows can win after a mid-mutation mind/filter switch | FIXED: post-mutation refetch rides a `reloadTick` state through the load effect (always current props); pinned with a deferred-archive + mid-flight switch test |
| 3,15 | LOW/MED | In-flight old-mind response can commit into the reset→next-load window | FIXED: mind-switch reset effect bumps `loadSeq` (invalidates in-flight commits) |
| 5 | LOW | Reset/load keyed on raw `workspaceId` — personal-mind instances wiped on workspace churn | FIXED: keyed on effective `wsParam` |
| 18 | LOW | Misleading "No memories match these filters." during the 250ms debounce window after a switch | FIXED: reset effect sets `loading=true` |
| 7 | MED | Audit events stamped the REQUEST's workspaceId, not the resolved mind | FIXED: all five audit sites attribute `c.mind === 'workspace' ? workspace : 'personal'` (incl. POST-create unknown-workspace fallback) |
| 4,19 | LOW | `?filter=` stash strands when landing on a legacy tab; replays later | FIXED: route stashes only when the landing view is Memories |
| 10 | LOW | URL keeps advertising `?filter=` after the one-shot stash is consumed | FIXED: route strips the param post-consumption (`replace`); refresh/share can't re-seed a stale filter |
| 12 | MED | J08 cold-load route stash unpinned | FIXED: route-level pins (stash + strip; legacy-tab drop) |
| 13 | MED | No server test exercised ANY workspace-mind mutation | FIXED: mutation suite added (see HIGH pins) |
| 14 | MED | Cross-mind fall-through unpinned | FIXED: HIGH pin above |
| 11,17 | LOW | Workspace pill could announce pressed+disabled simultaneously; pills lacked group semantics | FIXED: `aria-pressed` only when enabled; `role="group"` labeled |
| 16 | LOW | Tab bar lacked tablist semantics | FIXED: `role="tablist"`/`role="tab"`/`aria-selected` |
## Refuted (11) — examples
XSS via the moved `dangerouslySetInnerHTML` (renderSimpleMarkdown's two defenses hold); path
traversal via the workspace param (getWorkspaceMindDb resolves from an allowlisted map);
mind+filter interaction double-counting (per-store getRecent precedes the merge slice exactly as
before); WorkspaceDesktopApp uncontrolled-mode regression (import is side-effect-free); StrictMode
double-stash (ref-latched); several parity claims (banner gating, context-rail wiring, KG scope
selector all carried over).
## Behavior change vs the pre-review build (review happened before anything was committed)
`?filter=` no longer survives in the URL after consumption, and a mind switch no longer carries it
(one-shot intent semantics) — the original "filter survives the switch" route pin was replaced
accordingly.

124
docs/ux-refactor/p4-launch-integrity-record.md Normal file
View File

@@ -0,0 +1,124 @@
# P4 — Launch integrity: D11 + D12 + clean-install onboarding (2026-06-11)
**Scope (ratified):** D11 (WAGGLE_DATA_DIR + startup log), D12 (stale tracked sidecar bundle —
release-stopping), the S4 founder flag (clean-install onboarding skip), FREE→Upgrade e2e re-run.
## D11 — dataDir split-brain closed
`startService` ignored `WAGGLE_DATA_DIR` while `local/index.ts` config, the marketplace installer,
and memory-mcp honored it — a custom install split state across two directories. Now:
`resolveDataDir()` = option > `WAGGLE_DATA_DIR` > `~/.waggle` (exported, unit-pinned), plus the
ratified ONE startup line — `Data dir: <resolved> · tier: <effective>` — via `readTierFromDataDir`
(extracted from the request-scoped reader; same config.json + `getEffectiveTier` contract as
`GET /api/tier`). Stale "default to SOLO" comments fixed in assert-tier.ts and settings.ts (the
canonical vocabulary is TRIAL/FREE/PRO/TEAMS/ENTERPRISE; legacy solo→FREE, basic→PRO via
`LEGACY_TIER_MAP`, verified in tiers.ts before asserting it in a comment).
**Live-verified:** sidecar booted with `WAGGLE_DATA_DIR=<tmp>` and NO option — log line printed the
tmp dir + `tier: FREE`; install landed in the env-pointed dir.
## D12 — the bundle is generated, never tracked
`app/src-tauri/resources/service.js` (esbuild output of service.ts) was COMMITTED — last refreshed
2026-04-30, six weeks behind the server. Every official build path (app npm scripts, both CI
workflows) already regenerates it, so the tracked copy only ever shipped through a raw
`npx tauri build` — exactly the stale-binary class the ruling names. Fix per the ratified
preference (build-time generation + untracking, stronger than the minimum CI hash gate):
- `service.js` + `service.js.map` untracked + gitignored (joining node.exe/native/ under the
existing "generated at build time" section).
- `tauri.conf.json` `beforeBuildCommand` regenerates the SIDECAR BUNDLE (+ vite build) — a raw
`npx tauri build` produces a current server instead of a stale (or, post-untracking, missing)
one. cwd=app/ on every invocation path (npm scripts, CI `cd app && npx @tauri-apps/cli@2 build`).
**Scope deliberately excludes bundle-native-deps/bundle-node (review HIGH):** those scripts are
arch-parameterized via `TARGET_ARCH`, which the hook env doesn't carry — in the cross-arch macOS
release matrix (arm64 runner, `--target x86_64-apple-darwin`) the hook's `process.arch` fallback
would have CLOBBERED the x64-staged Node runtime + native libs with arm64 binaries, shipping a
non-launching Intel DMG with green CI. build-sidecar emits portable JS — safe arch-blind. The
arch-parameterized staging stays solely in the explicit npm/CI steps that set TARGET_ARCH.
- **Stale-dist closure (review MED, verified by metafile probe):** `@waggle/shared` and
`@waggle/hive-mind-core` export only gitignored `dist/` (core/agent/server export src), so the
regenerated bundle silently embedded whatever dist was last compiled — the same stale-server
class, one layer down. build-sidecar.mjs now ALIASES both packages to `src/index.ts` (no subpath
imports exist — verified), so the bundle always compiles from source; clean checkouts build
without `build:packages`. Verified: post-alias bundle has 59 src files, 0 dist files for the two.
- Dev mode unaffected: `service.rs` debug branch spawns `service.ts` via tsx directly.
- Pinned in tauri-config.test.ts (beforeBuildCommand contains build-sidecar; gitignore covers both
files). Bundle regenerated locally post-D11 + post-alias to prove the script runs clean (6.5 MB).
## Clean-install onboarding skip — CONFIRMED, fixed
S4 flagged it as suspected; P4 confirmed by code: `buildLocalServer` calls
`wsManager.ensureDefault()` unconditionally at boot (index.ts:322), and useOnboarding's
returning-user auto-complete fired on `getWorkspaces().length > 0` — so every clean production
install auto-completed the wizard before first render. **A brand-new user never saw onboarding.**
(The Tauri first-launch flag never gated this effect; web/dev had no flag at all.)
**Fix — server-authoritative status:** new `routes/onboarding.ts`:
- `GET /api/onboarding/status` → completed if the flag `<dataDir>/first-launch.flag` exists (the
SAME file the Tauri `mark_first_launch_complete` command writes on default installs), OR legacy
evidence for pre-flag installs: any frame in the personal mind, or >1 workspaces (the seeded
default alone is NOT evidence). No flag + no evidence → `completed:false` → wizard runs (fail
toward showing onboarding, same direction as the Rust command's IO-error fallback).
- `POST /api/onboarding/complete` → idempotent flag stamp; fired (fire-and-forget) from
`useOnboarding.update()` whenever completion flips, alongside the Tauri IPC flag.
- The FE auto-complete effect now keys on this status; `?forceWizard` DEV bypass unchanged; adapter
failure keeps the wizard (a truly new user can still set up).
**Live-verified on a clean dataDir:** seeded default workspace present (count=1) and
`{"completed":false,"source":"none"}` — the wizard renders for new users.
**Accepted edge (documented, not fixed):** a legacy returning user with a fresh webview AND zero
frames AND only the default workspace (onboarded historically but never used memory) re-sees the
wizard once — no durable signal distinguishes them from a clean install; the flag stamps on their
re-completion and the class dies out.
## FREE→Upgrade e2e re-run
Act 4 "Tier Wall" (user-behavior.spec.ts) against a fresh FREE-tier sidecar: first run 3/6 failed
on 401s — the API-level spec predates the P1b bearer gate (the documented dock-era e2e advisory
band, not a product regression). Re-run under `WAGGLE_TRUST_LOCALHOST=1` (the sanctioned local
mode): **6/6 pass** — gated 403 carries what's-missing detail, upgrade URL valid, tier ladder
coherent, FREE retains meaningful endpoints, Stripe checkout URL shape valid, cost dashboard
teases value at FREE. Spec-side bearer wiring stays ledgered with the P7 e2e band.
## Review — 5-dimension adversarial workflow (run split across a session-limit reset)
First pass: 6 confirmed / 18 refuted, with the onboarding-logic finder + 17 verifiers killed by
the session limit (resumed after reset; final tally in the P4 commit message). Dispositions:
| Sev | Finding | Disposition |
|-----|---------|-------------|
| HIGH (×2 dims) | beforeBuildCommand re-ran arch-parameterized bundle scripts without TARGET_ARCH — cross-arch macOS release legs clobbered x64 staging with arm64 (non-launching Intel DMG, green CI) | FIXED: hook trimmed to build-sidecar (arch-independent) + vite build |
| MED | Regenerated bundle silently embedded stale @waggle/shared + hive-mind-core dist (verified empirically) | FIXED: esbuild alias → src/index.ts; 0 dist files in bundle post-fix |
| LOW (×2 dims) | Double-run of sidecar/native/node/vite on every scripted build path | FIXED by the HIGH trim (hook now adds only build-sidecar+vite; build-sidecar double-run costs ~2s) |
| LOW | Tauri fs-flag fast-path hardcodes ~/.waggle while the server flag lives in <dataDir> — divergence reachable on custom-WAGGLE_DATA_DIR desktop installs (flag says returning, dataDir un-onboarded) | LEDGERED (P7): requires the Rust shell to learn the dataDir; default installs (the shipped path) share one file. Server status remains the primary signal |
**Resumed run (post-limit-reset, against the already-fixed code): 13 confirmed / 16 refuted.**
The fresh onboarding-logic finder verified the full pre-completion-evidence chain and two more
clusters; all fixed:
| Sev | Finding (clustered) | Disposition |
|-----|---------------------|-------------|
| MED ×4 | **Wizard/system-origin evidence pollution** — step-1 `PUT /api/profile` writes a 'User identity:' frame pre-completion (verified to the exact line), C33 import frames, workspace-create, and even the monthly-assessment CRON frame all count as "returning user"; mid-wizard abandon + fresh WebView profile (or Back-nav to step 0 + reload) silently skips the wizard | FIXED: server-durable PENDING latch — the first status call that finds no flag + no evidence stamps `<dataDir>/onboarding-pending.flag`; thereafter only explicit completion flips the status. Kills every evidence producer at once. Pinned with the exact verified attack chain (identity frame after latch → still `completed:false`) + a real-returning-user no-latch pin |
| MED ×5 (4 dims) | **Tauri fs-flag divergence** — `flag_path()` hardcoded `~/.waggle` while D11 makes `WAGGLE_DATA_DIR` official; a stale home flag auto-skips onboarding against a brand-new custom dataDir (the fast-path bypasses the server status entirely) | FIXED in Rust: `flag_path()` honors non-empty `WAGGLE_DATA_DIR` first (same resolution order as `resolveDataDir`), so the IPC flag and the server stamp are the same file on EVERY install shape. Sequential cargo test pins the order incl. the empty-env fallthrough |
| MED | **D12 raw-path overclaim** — after the arch-safety trim, a raw `npx tauri build` could silently package a binary with NO Node runtime (the resources glob tolerates absent files) | FIXED: `check-sidecar-resources.mjs` preflight in beforeBuildCommand — missing runtime/native artifacts now FAIL the build with instructions, never ship silently |
| LOW | D11 startup log line unpinned (deleting it kept gates green) | FIXED: console spy in the D11 integration test asserts the line + dataDir + tier |
| LOW | onboardingRoutes registration on the real server unpinned | FIXED: source-pin (import + register) in onboarding-status.test.ts |
| LOW | Production spawn seam (service.rs → bundled service.js) is smoke-only territory | LEDGERED: binary-smoke class, P7/D15 grid |
Self-triaged from the first run's unverified pile (fixed regardless — trivially real):
- `resolveDataDir` env leg used `??` — a set-but-EMPTY `WAGGLE_DATA_DIR` yielded `''`. Now `||`
(pinned).
- **Mid-wizard auto-complete ejection** (the question the dead onboarding-logic finder was asked):
a C33 import during the wizard writes personal-mind frames = legacy evidence; a mid-wizard
refresh would auto-complete the wizard out from under the user. Guard added: `step > 0` never
auto-completes (pinned).
- D11 re-homing note: an install that previously had implicit `~/.waggle` data while the
launcher set `WAGGLE_DATA_DIR` elsewhere now follows the env var — that is the ratified D11
behavior (the split-brain closing), recorded here as an intentional flip.
## Gates
FE 878/878 · server suite + tsc + lint recorded in the P4 commit message · D11 8 pins · onboarding
5 server + 4 FE pins · D12 pin · live: D11 boot, clean-install status, Act 4 6/6.

28
docs/ux-refactor/p5-review-record.md Normal file
View File

@@ -0,0 +1,28 @@
# P5/D4 — Adversarial Review Record
> Multi-agent review of the P5/D4 skill-governance diff (`c33da1e..5969778`), run as a
> dynamic workflow: **6 dimension reviewers → 3-lens adversarial verification per finding**
> (correctness / security-and-data-integrity / reproduction; confirmed if ≥2 of 3 vote real).
> 33 agents, ~3.6M subagent tokens, ~12 min. Fixes in `cdcef3d`.
## Tally
**9 findings → 5 confirmed (4 distinct) / 4 refuted.**
| # | Sev | Votes | Dimension | Finding | Disposition |
|---|-----|-------|-----------|---------|-------------|
| 2/4 | **HIGH** | 3/3 + 2/3 | service | Sticky provenance aliased into the AUDIT row — an agent editing a user-authored skill was recorded `initiator:'user'`, violating D4(i) "always audit initiator:'agent'" | **FIXED** — decoupled `fileInitiator/fileSource` (sticky, → frontmatter) from `input.initiator/source` (actual actor, → audit row). Test asserts `audit[0].initiator==='agent'` on an agent-update-of-user-skill. |
| 1 | MED | 2/3 | migration | `rebuildForWidenedActionCheck` dropped both `idx_audit_*` indexes — SQLite `RENAME` carries index names to the legacy table, so `CREATE INDEX IF NOT EXISTS` no-ops and `DROP TABLE` takes them. (Shadowed today since prod opens via `MindDB.runMigrations` which uses the index-correct `db.ts` path — but a live latent landmine on the DEC-1 migration path.) | **FIXED** — `DROP INDEX IF EXISTS` before recreate (mirrors `db.ts`). Test asserts both indexes exist post-rebuild. |
| 3 | MED | 3/3 | ui | `GET /api/skills` preview leaked the stamped YAML frontmatter into the Hub row (`s.content.slice(0,200)` led with `---initiator: agent...`) | **FIXED** — preview derived from `parseSkillFrontmatter(raw).body`. Server test asserts no `---`/`initiator:` in preview. |
| 5 | LOW | 3/3 | ui | Agent skill wore BOTH `agent · review` AND the name-heuristic `custom` label + appeared in the Custom tab | **FIXED** — `initiator==='agent'` ⇒ status `installed`; provenance supersedes the `custom` heuristic per D4(iv). |
## Refuted (correctly dismissed, 0/3)
- **service-dim duplicate of #1** (index drop) — the migration-dim panel confirmed it 2/3; the service-dim panel refuted 0/3. The disagreement was itself signal of a real-but-shadowed latent bug; fixed regardless.
- **Unparseable-prior fallback** (LOW) — `writeSkill` falling back to caller provenance when the prior file is unreadable is correct/intended, not a leak.
- **Hash-store trims** (MED) — `computeSkillHash` over on-disk content vs `loadSkills` trim was traced to NOT break `hash-status`.
- **`auto_extract_skills` direct `fs.writeFileSync`** (MED) — out of D4 scope (not one of the three named tools); ledgered in the P5 plan's out-of-scope section. A candidate post-launch consolidation, not a P5 defect.
## Gate (post-fix)
tsc 0 (core/agent/server/apps-web) · 101 regression + 28 P5/fix tests green · lint 0. `cdcef3d`.

111
docs/ux-refactor/p5-skill-governance-plan.md Normal file
View File

@@ -0,0 +1,111 @@
# P5 — D4 Skill-Write Governance · Build Plan
> Phase sequence (open-questions.md:574): P1=D3 ✅ · P2=verify+J08 ✅ · P3=D2 ✅ ·
> P4=D11/D12 ✅ · **P5=D4** ← here · P7=D15 (card risk-taxonomy alignment, deferred).
> Decision text: `docs/ux-refactor/deltas/open-questions.md` §D4 (lines 537–543).
## What D4 ratified (four bindings)
- **(i) Policy.** `create_skill` — normal = ask (in-chat approval card), trusted/yolo =
auto-execute. `delete_skill` — always ask, every autonomy level. `read_skill` ungated.
Always-audit all three with `initiator:'agent'`.
- **(ii) Surface.** In-chat SSE approval card is canonical. Card↔`ui/approval-modal.tsx`
risk-taxonomy alignment is **D15/P7 — explicitly deferred, NOT P5.**
- **(iii) One write path.** Do NOT route the agent tool through HTTP. Extract a **shared
skill-write service module** (create/update/delete + redaction + audit inside the
service), consumed by both `routes/skills.ts` and `skill-tools.ts`. One module, one
audit trail, two callers.
- **(iv) Endpoint consolidation (absorbs D14).** `POST /api/skills` delegates to the
audited service. `PUT`/`DELETE /api/skills/:name` enter the audit trail. **Provenance:**
frontmatter `initiator`/`source` + `GET /api/skills` returns it + Skills Hub badge
("created by agent — review"), replacing the name-heuristic "Custom" classification.
- **Persona exception** (already shipped): read-only personas keep losing
`create_skill`/`delete_skill`, retain `read_skill`.
- **PM residual** (no code): skill creation stays FREE at launch — tier gate unchanged.
## Recon — current seams (verified 2026-06-12)
| Seam | File | State |
|------|------|-------|
| Agent tool | `packages/agent/src/skill-tools.ts` | create/delete write to disk + redact; **no audit, no provenance, no gate** |
| HTTP routes | `packages/server/src/local/routes/skills.ts` | `POST /api/skills`, `PUT`/`DELETE /:name` redact but **don't audit**; `POST /api/skills/create` (structured) DOES audit `action:'installed'` |
| Autonomy gate | `packages/agent/src/confirmation.ts` | declarative sets; chat.ts:900 calls `needsConfirmationWithAutonomy` |
| Frontmatter | `packages/agent/src/skill-frontmatter.ts` | parser+serializer; has name/description/scope/promoted_from/permissions — **no initiator/source** |
| Audit store | `packages/core/src/install-audit.ts` | `record()`; action enum **lacks a delete value** |
| Skills Hub UI | `apps/web/src/components/os/apps/skills/SkillRow.tsx`, `routes/SkillsRoute.tsx` | `custom` badge driven by name-heuristic |
## Decisions
### DEC-1 — Audit `action` for delete (the one real fork)
`AuditAction = 'proposed'|'approved'|'installed'|'rejected'|'failed'|'blocked'` — no
delete/uninstall value. The CHECK is duplicated in `packages/core/src/install-audit.ts`
**and** `packages/hive-mind-core/src/mind/schema.ts` (OSS-synced, §7.5). SQLite CHECK
can't be ALTERed → widening needs a table-rebuild migration on existing installs.
- create / update → `action:'installed'` (established convention — `routes/skills.ts`
structured-create already does this; a skill on disk = installed).
- delete → **needs a decision** (see status note). Options:
- **A (recommended): add `'uninstalled'`** to `AuditAction` + both schema CHECKs +
a rebuild migration. Fills a genuine pre-existing gap (no uninstall of ANY capability
is auditable today); additive/backward-compatible; honest trail. Cost: migration in
2 files + OSS drift check.
- **B: reuse `'rejected'`** with `detail:'deleted by agent'`. Zero migration, but
semantically muddy and pollutes rejection queries.
### DEC-2 — Shared service location
`packages/agent/src/skill-write-service.ts`. The agent package is already a server
dependency (`@waggle/agent` imported by `routes/skills.ts`), so one module serves both
callers. Signature (pure, deps injected — no hidden globals):
```
createSkillWrite({ skillsDir, name, content, initiator, source, auditStore?,
skillHashStore?, onChange? }) → { path, redactions, action }
updateSkillWrite({ … }) ; deleteSkillWrite({ skillsDir, name, initiator, auditStore?, … })
```
Redaction (`redactSkillContent`) + provenance frontmatter stamp + audit `record()` all
live inside the service. Callers stop doing these by hand.
### DEC-3 — Provenance frontmatter
Add `initiator?: 'agent'|'user'` and `source?: string` to `SkillFrontmatter` + parser +
`serializeFrontmatter`. The service stamps them on create (preserves on update). Legacy
skills with no frontmatter → treated as `initiator:'user'` (no badge). Name-heuristic
"Custom" classification retired in favor of `initiator==='agent'`.
## Build order (TDD, commit per step)
1. ✅ **D4(i) gating** — `confirmation.ts` sets + tests. (`73f2ed5`)
2. ✅ **DEC-1 audit enum** — founder picked **Option A**: `'uninstalled'` + widen-CHECK
migration in core `install-audit.ts` (belt-and-suspenders rebuild) AND hive-mind-core
`db.ts` runMigrations sentinel + `schema.ts` DDL. (`658884f`)
3. ✅ **DEC-3 frontmatter** — `initiator`/`source` in parser/serializer. (`f3bda5b`)
4. ✅ **DEC-2 service** — `skill-write-service.ts` (lossless provenance stamp). (`2b56b78`)
5. ✅ **Rewire agent** — `skill-tools.ts` create/delete via service. (`2b56b78`)
6. ✅ **Rewire HTTP** — `routes/skills.ts` POST/create/PUT/DELETE via service; `GET
/api/skills` returns provenance. (`29313a9`)
7. ✅ **UI badge** — `SkillRow.tsx` "agent · review" off provenance. (`48292ef`)
8. ⏳ Adversarial review workflow → record → final gates. (pending — needs opt-in)
## Status — implementation COMPLETE (2026-06-12)
All four D4 bindings shipped in 7 commits (`73f2ed5`→`48292ef`), NOT pushed.
Gates: tsc 0 across shared/hive-mind-core/core/agent/server/apps-web · 147 P5 tests
green (agent 96, core 22, server 20, FE 9) · lint 0.
**Remaining for P5 closeout:**
- **OSS re-split (§7.5):** `hive-mind-core/src/mind/{schema.ts,db.ts}` changed here first
(the `'uninstalled'` CHECK + migration sentinel). The `marolinik/hive-mind` mirror must
be regenerated via subtree-split before the next OSS release.
- **Adversarial review** (step 8) — every prior P-phase ran a multi-agent review workflow;
deferred pending explicit opt-in.
- **Decision-log + open-questions** phase-line update marking P5 done.
- **D4(ii)** card↔modal risk-taxonomy alignment stays **P7/D15** (out of P5 scope).
## Out of scope (ledgered)
- D4(ii) card↔modal risk-taxonomy alignment → **P7/D15**.
- Marketplace install PRO-gate (unchanged).
- `promote_skill`/`auto_extract_skills`/`retire_skills` audit (not named by D4; leave).

384
docs/ux-refactor/p7-d15-scope.md Normal file
View File

@@ -0,0 +1,384 @@
# P7 — D15 Launch Integrity · Scope (per-screen state grid + approval/audit taxonomy)
> **Phase sequence** (`docs/ux-refactor/deltas/open-questions.md:574`): P1=D3 ✅ ·
> P2=verify+J08 ✅ · P3=D2 ✅ · P4=D11/D12 ✅ · P5=D4 ✅ (2026-06-12, 7 commits
> 73f2ed5→48292ef) · **P7=D15 ← here. This is the LAST launch-blocker.**
>
> **Decision text:** `open-questions.md` §D15 (line 563) — *"Launch-blocking from
> prior-plan P6: per-screen state grid (brief rule 10) + approval/audit taxonomy
> consolidation (brief rule 7, includes D4-ii alignment). Post-launch: connector `/sync`
> real implementation (stub stands), MCP logs."* Plus §D4(ii) (line 539) — *"Align the
> card's risk display with the `ui/approval-modal.tsx` taxonomy (D15 work)."*
>
> **Scoping pass only.** Everything below is grounded in a read-only audit of
> `apps/web/src` (routes in `routes/*Route.tsx`, components in `components/os/apps/`) plus
> the backend taxonomy modules. No code was modified. Every claim cites `file:line`.
D15 has two structurally independent halves. **HALF 1** (brief rule 10) makes every screen
declare its loading / empty / error / populated states. **HALF 2** (brief rule 7) unifies
the risk/approval/audit vocabulary across five backend taxonomies and three frontend
approval surfaces — and closes the deferred **D4(ii)** in-chat-card↔modal alignment.
---
# HALF 1 — Per-Screen State Grid (brief rule 10)
Legend: **full** = all four states distinct and correct · **partial** = state exists but
is degraded/conflated · **missing** = no such state (the failure mode renders as a
*different* state, usually empty) · **n/a** = categorically inapplicable (static screen /
no data path).
The dominant defect class is **error-rendered-as-empty**: a fetch failure is swallowed
into `[]` so the user sees "No X yet" when the backend is actually down. On a trust /
monetization / activity surface this is a correctness defect, not cosmetics.
## State grid (all 30 screens)
| # | Screen | Route | loading | empty | error | populated | Worst gap |
|---|--------|-------|---------|-------|-------|-----------|-----------|
| 1 | Home Cockpit (S01) | `/home` | full | full | full | full | Overnight tile hidden when offline (`HomeCockpit.tsx:626`) instead of degraded placeholder; header pill only signal (149) |
| 2 | Workspace Desktop (S02) | `/workspaces/:id/:tab?` | full | full | full | full | research/timeline/settings tabs are static `TabPlaceholder` stubs (`WorkspaceDesktopApp.tsx:955-961,992-998,1000-1006`); best-effort feeds render partial-failure as empty (712-735) |
| 3 | Command Center (Win+K) | overlay (`AppShell.tsx:312`) | partial | full | **missing** | full | No in-surface error at all; search failure → silent fuzzy fallback (`CommandCenter.tsx:253-268`); **overlay outside any error boundary** (312 vs SurfaceBoundary-wrapped Outlet) — a render throw blanks the shell |
| 4 | Memory Center | `/memory/:mindScope?` | full | full | **partial** | full | Timeline sub-tab error-blind: `useMemory` captures `error` (`useMemory.ts:36`) but `MemoryRoute.tsx:103` never threads it → fetch failure shows "No memories found" (`TimelineTab.tsx:197-202`). Memories+Graph tabs are full. |
| 5 | Artifact Center | `/artifacts` | full | full | full | full | **Gold standard** — cold-load error (full-pane, `ArtifactCenterApp.tsx:242`) vs transient refetch error (inline banner, 258-263). No material gap. |
| 6 | Files | `/files` | partial | full | **missing** | full | All failures collapsed to `offline=true` (`FilesApp.tsx:157-158`) → cold load error shows "showing cached files" with NO cache; no loading branch in list pane (469-549) → in-flight looks empty; silent mutation catches (228,284,289) |
| 7 | Room | `/room` | **missing** | full | **missing** | full | SSE subscribe failure swallowed to `console.error` (`useRoomState.ts:39-41`), hook exposes no `error`/`connecting` → connecting, idle, and broken all render "No agents running" (`RoomApp.tsx:179-187`) |
| 8 | Agents — Center | `/agents` | full | full | full | full | No material gap; load gated on `connecting` (`AgentsApp.tsx:74-77`); stale-refresh banner (240-247) |
| 9 | Agents — Templates | `/agents` (toggle) | partial | full | **partial** | full | No `connecting` gate (`TemplatesView.tsx:76`) → 401 race; error only as banner AFTER loading clears (240-249); `getPersonas()` rejection silently falls back to local PERSONAS (52-56, `setError` NOT called) — backend failure invisible |
| 10 | Agents — Builder (S18) | `/agents` (New/template) | n/a | full | **partial** | full | Catalog failure → empty picker + single `catalogNote` (`AgentBuilder.tsx:146-148`) that doesn't say WHICH catalog failed |
| 11 | Skills (Capabilities Hub) | `/skills` | partial | full | **partial** | full | Packs-tab catalog failure leaves `error` null → "No catalog packs found" empty stands in for error (`CapabilitiesApp.tsx:533-538`); skills-tab error only when list empty (472) — stale list masks reload failure |
| 12 | Automations — Center | `/automations` | full | full | full | full | **Reference implementation** — loading + empty + error + stale-banner + partial-degradation notice all distinct (`AutomationCenterApp.tsx:262-290`) |
| 13 | Automations — Builder (S20) | `/automations` (New/Edit) | full | n/a | full | full | No gap — hydration race handled (`configPending`/`configUnavailable`, `AutomationBuilder.tsx:138-139`); C26 check fallback (223-224); approval fails closed (237-249) |
| 14 | Automations — Log list | `/automations` (Logs) | full | full | full | full | Leaf component fully covers 4 states (`AutomationLogList.tsx:24-37`); parent prefetches so loading/error props unreached (dead-but-correct) |
| 15 | Connector Hub | `/connectors` | full | full | full | full | `handleDisconnect` failure is console-only, no toast (`ConnectorsApp.tsx:170-175`) — inconsistent with connect/revoke; "Recommended" empty copy reused for "registry not loaded" (329) |
| 16 | MCP Hub | `/mcps` | full | full | full | full | `remote` (`MCPHubApp.tsx:359`)/`activity` (385) tabs render un-gated by the items-fetch `error` → server-down on those tabs shows no banner; catalog silently drops Install buttons when registry unreachable (`McpCatalog.tsx:85-86`) |
| 17 | Marketplace | `/marketplace` | full | full | full | full | Audit tab delegates to `InstallAuditPanel` (own states) → can disagree with marketplace health (`MarketplaceApp.tsx:335`); partial facet rejection silently drops sources (170-172); only all-rejected surfaces error (177) |
| 18 | Tool Launcher | `/launcher` | full | **missing** | full | full | Successful detection with `tools:[]` → blank scroll area, no "no tools detected" (`LauncherApp.tsx:366-371` loading-gated empty); no `connecting` gate (130-132) → cold-load 401 race |
| 19 | Install Audit Panel | embedded (`/connectors`,`/mcps`,`/marketplace`) | partial | full | full | full | Loading is an unconditional early-return (`InstallAuditPanel.tsx:92-98`) → every type-filter change/reload blanks the whole feed to a spinner (hosts explicitly avoid this); no `connecting` gate (90) |
| 20 | Team Governance | `/team` | n/a | n/a | partial | n/a | Static tier-upsell card, no data path (`TeamGovernanceApp.tsx:3-44`); only error coverage is the render-crash boundary. By design (D5 reserves Team work). |
| 21 | Approvals | `/approvals` | full | full | **missing** | full | Both fetches `.catch(() => ({pending:[],count:0}))` (`ApprovalsApp.tsx:77-78`) → server-down shows "No pending approvals" on a TEAMS trust surface; no error branch anywhere |
| 22 | Waggle Dance | `/waggle-dance` | full | full | **missing** | full | Hook tracks+returns `error` (`useWaggleDance.ts:58`) but `WaggleDanceApp.tsx:34` omits it from the destructure → load failure renders "No waggle dance signals yet" (86-91). Dead error state. |
| 23 | Settings | `/settings` | partial | n/a | **partial** | full | No top-level loading (defaults render immediately); `getSettings`/`getPermissions`/`getTeamStatus` swallow errors (`SettingsApp.tsx:156,163,165`); `getTelemetryStatus` has NO `.catch` (168-171) — unhandled rejection. Billing tab is gold standard (500-543). |
| 24 | Vault | `/settings/vault` | full | full | **missing** | full | `loadData` Promise.allSettled wrapped in `try{}catch{/*ignore*/}` (`VaultApp.tsx:104-120`) → vault-read failure shows "No secrets stored yet" (300); `handleReveal` failure silently ignored (182) |
| 25 | My Profile | `/settings/profile` | full | **missing** | **missing** | full | `getProfile().catch(() => {})` (`UserProfileApp.tsx:102`) + form always renders from `''` defaults (65-83) → never-configured, load-failed, and populated are indistinguishable; no empty, no error |
| 26 | Mission Control (Cockpit) | `/settings/mission-control` | partial | partial | full | full | **Error is the reference impl** — `offline` banner + Retry on all-rejected (`CockpitApp.tsx:82-93`). Gap: no body skeleton (header icon only, 77-78) → first paint shows "Unknown"/$0.0000; empty is per-tile not screen-level |
| 27 | Timeline | `/settings/timeline` | full | full | **missing** | full | `getTimeline` `.catch` only clears loading (`TimelineApp.tsx:84-86`), events stay `[]` → backend error shows "No activity in this period" (168-172). No-workspace guard (109-115) is well handled. |
| 28 | Events | `/settings/events` | **missing** | full | **missing** | full | No loading concept (only per-step spinners); `useEvents` exposes `error` (`useEvents.ts:35`) but `EventsRoute.tsx:16-20` discards it → both load-pending and load-failed show "No events yet" (`EventsApp.tsx:411-417`) |
| 29 | Usage & Telemetry | `/settings/usage` | full | partial | **missing** | full | Per-fetch `.catch(() => [])` (`TelemetryApp.tsx:29-30`) coerces failure into a zeroed populated dashboard (3 cards reading 0/$0.0000); `!data` empty (56-63) nearly unreachable; no error, no retry |
> **Reference implementations to copy from:** Artifact Center (#5, cold vs transient error
> split), Automations Center (#12, full 5-band grid incl. partial-degradation notice),
> Mission Control (#26, `offline`+Retry banner), and Memory Center's *Memories* tab
> (`MemoryCenterTab.tsx:298-329`, role=status/role=alert/Retry/context-empty). The fix
> pattern already exists in-repo on four screens — P7 propagates it, it does not invent it.
## Gaps to close — prioritized (rank = user-facing severity)
**Ranking rule (D15-aligned):** a **missing ERROR state on a core / trust / monetization
surface** ranks far above a missing EMPTY state on a settings sub-page. Error-rendered-as-
empty on a security surface is a *correctness* defect; a missing zero-tools message is
*polish*. The fix for the dominant class is mechanically identical everywhere (thread the
`error` the hook already captures + render an `role=alert` block with Retry).
### P0 — launch-blocking (missing ERROR on a core/trust/activity surface)
1. **Approvals — error→empty on a trust surface** (`ApprovalsApp.tsx:77-78`). A TEAMS
trust-control inbox shows "No pending approvals" when the server is down. **Highest
user trust cost.** Add an error branch + Retry; stop coercing fetch failure to `{pending:[]}`.
2. **Room — no loading AND no error** (`useRoomState.ts:39-41`, `RoomApp.tsx:179-187`).
The exact SSE-channel failure D3 revived in prior sessions renders identically to
"no agents." Add a `connecting`/`error` status flag to `useRoomState`; show connecting
skeleton + error+reconnect affordance.
3. **Command Center — no error state + no error boundary** (`CommandCenter.tsx:253-268`,
`AppShell.tsx:312`). The structural half is the real risk: the overlay sits **outside**
the only `SurfaceBoundary` (`AppShell.tsx:300/306`) so a render throw blanks the whole
shell. Wrap the overlay in an `AppErrorBoundary`; surface search/execute failures
in-body, not just as a toast.
4. **Files — error collapsed into a misleading "offline/cached" state**
(`FilesApp.tsx:157-158,385-389`). A cold-load 500/permission failure shows "showing
cached files" with no cache. Distinguish a real load error from offline; add a loading
branch to the list pane (469-549).
5. **Waggle Dance — dead error state** (`WaggleDanceApp.tsx:34` omits `error` the hook
already returns at `useWaggleDance.ts:58`). One-line destructure fix + render. **Lowest
effort in this tier** — the data is already there.
6. **Memory Center / Timeline sub-tab — error-blind** (`MemoryRoute.tsx:103` doesn't
thread `useMemory.error`; `TimelineTab.tsx:43-57` has no `error` prop). Thread + render.
Memory is the lock-in moat surface; a masked failure here is high cost.
### P1 — launch-blocking-adjacent (settings/secrets surfaces where error→empty hides failure)
7. **Vault — vault-read failure shows "No secrets stored yet"** (`VaultApp.tsx:104-120`).
Secrets surface; an invisible read failure is a trust problem. Add error/offline UI;
surface `handleReveal` failures (182).
8. **Settings — silent error swallows + one unhandled rejection**
(`SettingsApp.tsx:156,163,165` empty catches; **168-171 `getTelemetryStatus` has NO
`.catch`** — a real unhandled promise rejection). Add the missing catch (defect, not
polish); add a settings-form loading affordance; propagate load errors. Billing tab
(500-543) is the template to match.
9. **Timeline / Events / Usage&Telemetry — error→empty/zeroed** (`TimelineApp.tsx:84-86`;
`EventsRoute.tsx:16-20` discards `useEvents.error`; `TelemetryApp.tsx:29-30` `.catch(() => [])`
→ zeroed dashboard). Settings sub-pages, but the pattern (down backend looks like "you've
used nothing") is the same class. Thread `error` + render; add Events loading.
### P2 — nice-to-have (missing/partial states that don't mask a failure as success)
10. **Tool Launcher — missing empty state** (`LauncherApp.tsx:366-371`): zero-tools machine
shows a blank pane. Add a "no supported tools detected" empty + a `connecting` gate (130-132).
11. **My Profile — no empty, no error** (`UserProfileApp.tsx:102`): blank form for
never-configured AND load-failed. Add a distinct empty ("set up your profile") + error.
12. **Templates / Skills / MCP Hub / Connectors partial-error masking**: `connecting`
gates (`TemplatesView.tsx:76`), packs-tab error (`CapabilitiesApp.tsx:533-538`),
un-gated MCP `remote`/`activity` tabs (`MCPHubApp.tsx:359,385`), `handleDisconnect`
toast (`ConnectorsApp.tsx:170-175`). Real but lower-blast-radius.
13. **Loading polish**: `InstallAuditPanel.tsx:92-98` content-blanking reload; Mission
Control / Cockpit body skeletons (`CockpitApp.tsx:77-78`); Home offline overnight
placeholder (`HomeCockpit.tsx:626`). Flicker, not failure-masking.
14. **Workspace Desktop tab stubs** (`WorkspaceDesktopApp.tsx:955-961,992-998,1000-1006`):
research/timeline/settings are `TabPlaceholder`. These are *intentionally* deferred
(P3/P7 tab embeds, see `open-questions.md:621-622`) — flag, don't build in P7 unless
re-scoped.
---
# HALF 2 — Approval / Audit Taxonomy Consolidation (brief rule 7)
The risk/approval vocabulary is fragmented across **five backend taxonomies** with no
canonical source and **three frontend approval surfaces** that speak mutually-incompatible
dialects. The headline defect (and the named D4(ii) item): **the server already computes
the full trust taxonomy and emits it on the wire, but the frontend type drops it at the
boundary**, so the highest-risk approval (installing a third-party/unknown capability)
shows the user the *least* risk information.
## The fragmentation (five backend taxonomies, three FE surfaces)
| Source | Module | Risk enum | Approval enum | Notes |
|--------|--------|-----------|---------------|-------|
| Runtime gating | `agent/confirmation.ts:124` | `_riskLevel` string `low\|medium\|high` (139) | `ApprovalClass` `standard\|elevated\|critical` | own `getApprovalClass()` (126-143) hardcodes high→critical/medium→elevated (140-142) |
| Install assessment | `agent/trust-model.ts:17` | `RiskLevel` `low\|medium\|high` **(no critical)** | `ApprovalClass` `standard\|elevated\|critical` (27) | canonical `classifyRisk` (184) + `deriveApprovalClass` (196) — tops out at high→critical |
| Persisted audit | `core/install-audit.ts:19` | `AuditRiskLevel` `…\|critical` **(adds critical)** | `AuditApprovalClass` `…\|blocked` (23, **adds blocked**) | DDL CHECK (65-72), no `trust_source` CHECK; `AuditAction` 7-val incl. `uninstalled` |
| Audit DDL copy | `hive-mind-core/src/mind/schema.ts:148-149` | — | — | **hand-duplicated** CHECK lists (drift hazard, `install-audit.ts:62-64` admits it) |
| RBAC governance | `server/services/team-capability-governance.ts:23-28` | `RISK_LEVELS` keyed `none\|low\|medium\|high` **(adds none, no critical)** | `PermissionResult` `allowed\|blocked\|needs_approval\|source_not_allowed` | `riskExceedsThreshold` (34): a `critical` risk falls to `?? 0` → sorts *below* `low` |
| **FE in-chat card** | `apps/web/.../lib/types.ts:374-382` | **none** | **none** | `{requestId,toolName,description,input,rawJson,sourceWorkspaceId}` |
| **FE shared modal** | `components/ui/approval-modal.tsx:23-29` | `riskLevel` `low\|medium\|high` **only** | **none** | `{action,scope[],riskLevel}` — name-collides with the card's `ApprovalRequest`, different shape |
| **FE audit feed** | `extend/InstallAuditPanel.tsx:35-50` | free string (`String()`-coerced) | free string | the ONLY FE place that reads riskLevel+trustSource+approvalClass — post-hoc |
## Canonical target vocabulary (what P7 converges on)
Promote a single shared two-axis model to **`packages/shared/src/risk.ts`** (or a shared FE
type), imported everywhere instead of redeclared. Adopt the **widest** existing set as
canonical so no producer/store mismatch remains:
- **`RiskLevel = 'low' | 'medium' | 'high' | 'critical'`** — adopt the wider `AuditRiskLevel`
(`install-audit.ts:19`). `trust-model.ts` must gain a path to `'critical'` (today `classifyRisk`
tops out at high, `trust-model.ts:184-202`).
- **`ApprovalClass = 'standard' | 'elevated' | 'critical' | 'blocked'`** — adopt the wider
`AuditApprovalClass` (`install-audit.ts:23`). `'blocked'` must become a **derivable** outcome,
not a hand-written literal (today only `marketplace.ts:231` produces it).
- **`TrustSource`** — canonical at install-audit's **7-value** set incl. `'security-gate'`
(`install-audit.ts:20-22`); `trust-model.ts` 6-value set (19-25) is the narrow one.
- **`AssessmentMode = 'declared' | 'heuristic' | 'mixed'`** + `RiskFactor[]` +
`PermissionSummary` + human `explanation` — already in `trust-model.ts`, kept.
- **`AuditAction`** — canonical at the 7-value set incl. `'uninstalled'` (added in P5/D4).
- **Two axes, one rule:** `riskLevel` = how dangerous (severity color). `approvalClass` =
how strongly to gate (standard/elevated/critical/blocked). `trust-model.ts` already
separates them cleanly via `deriveApprovalClass`; the modal collapses to risk-only and
must learn `approvalClass`.
## Divergence table (issue | files | severity)
| # | Issue | Files | Sev |
|---|-------|-------|-----|
| 1 | Two `ApprovalRequest` types share a name, structurally disjoint — card `{requestId,toolName,description,input,rawJson,sourceWorkspaceId}` vs modal `{action,scope[],riskLevel}`. Cannot unify by component reuse without reconciling the type first (root of "same taxonomy, not same component"). | `lib/types.ts:374-382` ↔ `ui/approval-modal.tsx:23-29` | **HIGH** |
| 2 | **D4(ii) concrete bug:** server emits full `trustMeta` (riskLevel/approvalClass/trustSource/assessmentMode/explanation/permissions) for `install_capability`, FE card type declares none → risk crosses the wire and is **silently dropped**. Highest-risk approval shows least info. | `server/.../chat.ts:937-970` ↔ `ChatApp.tsx:240-289` (+ `lib/types.ts:374-382`) | **HIGH** |
| 3 | Risk scales unaligned — `trust-model` has two orthogonal axes (riskLevel + approvalClass, `critical`= never-auto-pass), the shared modal collapses to riskLevel low/med/high with no `approvalClass` → a `critical` install and a `high` install render identically. | `trust-model.ts:184-202` ↔ `ui/approval-modal.tsx:40-45` | **HIGH** |
| 4 | FE modal cannot REPRESENT `critical` that the audit store + security gate routinely record → a CRITICAL MCP install is demoted to a plain text notice instead of the risk-leveled modal it uses for HIGH. | `ui/approval-modal.tsx:28` ↔ `install-audit.ts:19`, `MCPHubApp.tsx:191-195` | **HIGH** |
| 5 | Two parallel surfaces render the same approval concept with incompatible vocabularies (modal riskLevel-only vs card no-risk vs audit free-string) — three approval/audit UIs, three field sets. | `approval-modal.tsx:23` · `ChatApp.tsx:222-290` · `InstallAuditPanel.tsx:26-45` | **HIGH** |
| 6 | `'blocked'` (`AuditApprovalClass`) is never DERIVABLE — both derive fns (`getApprovalClass`, `deriveApprovalClass`) top out at `critical`; `'blocked'` written only by a route literal (`marketplace.ts:231`). Derive path and persist path use non-substitutable enums. | `confirmation.ts:126` + `trust-model.ts:196` ↔ `install-audit.ts:23,70`, `marketplace.ts:231` | **HIGH** |
| 7 | `RiskLevel` (trust-model, 3-val) can NEVER emit `critical`, but `AuditRiskLevel` (4-val) accepts it → a `risk_level:'critical'` row can only be hand-written; producer narrower than store. | `trust-model.ts:17,318` ↔ `install-audit.ts:19` | **HIGH** |
| 8 | Modal consumers manufacture `riskLevel` client-side from heuristics/hardcodes, NOT from server TrustAssessment — displayed risk ≠ policy-engine risk; same install labelled differently in two places. | `MarketplaceApp.tsx:55-91` (derives) vs `ConnectorsApp.tsx:92`/`AgentBuilder.tsx:196`/`AutomationBuilder.tsx:254`/`MCPHubApp.tsx:216,226` (hardcode) ↔ `trust-model.ts:151-202` | **MEDIUM** |
| 9 | Trust metadata enriched ONLY for `tool==='install_capability'` (`chat.ts:939`); every other gated tool (fs writes, shell, cross-workspace) emits approval with no risk class, though they carry execution risk (`PERMISSION_RISK_POINTS` codeExecution=2/secrets=2). "Same policy" can't hold without a server risk path for non-install tools. | `chat.ts:937-970` ↔ `trust-model.ts:160-168` | **MEDIUM** |
| 10 | Plain-language action field mismatch — card's `description` (`lib/types.ts:377`, rendered `ChatApp.tsx:246-248`) is NEVER sent by the server (`chat.ts:966-970`) → card's human line is always empty; modal leads with `action`. | `ChatApp.tsx:246-248` ↔ `chat.ts:966-970` | **MEDIUM** |
| 11 | `team-capability-governance` `RISK_LEVELS` (`none\|low\|medium\|high`) is a 4th vocabulary using `none` (no other has it) and lacking `critical` → `riskExceedsThreshold` sorts a `critical` risk via `?? 0` *below* `low`. Silent RBAC mis-ordering. | `team-capability-governance.ts:23-39` | **MEDIUM** |
| 12 | Naming-axis confusion — same 3 buckets called `riskLevel` on some surfaces, `approvalClass` on others; they are NOT the same axis. Two-axis model exists in code but is collapsed inconsistently per surface. | `trust-model.ts:196-202` vs `approval-modal.tsx`/audit/chat trustMeta | **MEDIUM** |
| 13 | `_riskLevel` passed as an untyped string in tool args; `confirmation.ts:140-142` hardcodes high→critical/medium→elevated, **duplicating** `deriveApprovalClass` (`trust-model.ts:196-202`) in a second drift-prone place. | `confirmation.ts:139-142` ↔ `trust-model.ts:196-202` | **MEDIUM** |
| 14 | `install_audit` CHECK-constraint lists hand-duplicated; in-code comment admits "MUST stay in sync … drift silently crashes `auditStore.record()`." Two copies = no single source of truth. | `install-audit.ts:62-72` ↔ `hive-mind-core/src/mind/schema.ts:148-149` | **MEDIUM** |
| 15 | `AuditTrustSource` has 7 values incl. `security-gate`; `trust-model` `TrustSource` has 6, `resolveTrustSource` can never return it; trust_source CHECK is ABSENT from the DDL (`install-audit.ts:71`) → unconstrained at DB while TS claims a closed set. | `install-audit.ts:20-22,71` ↔ `trust-model.ts:19-25,67` | **LOW** |
| 16 | Audit feed prints `risk: <raw>` from a `String()`-coerced unknown (`InstallAuditPanel.tsx:143,35-50`) with no label/color, while the modal applies RISK_LABELS/RISK_CLASSES → same risk, two visual languages; audit can't be wrong-typed (accepts any string). | `InstallAuditPanel.tsx:35-50,143` ↔ `approval-modal.tsx:40-45,70-73` | **LOW** |
| 17 | `trustSource` is a taxonomized backend field surfaced on `trustMeta` (`chat.ts:954`) but shown in NO approval surface except a hand-built MarketplaceApp scope line (`MarketplaceApp.tsx:82-88`); 4 of 5 install surfaces omit the dimension that JUSTIFIES the risk. | `install-audit.ts:20-22` + `chat.ts:954` ↔ all builder consumers | **LOW** |
## D4(ii) — the specific card↔modal alignment work
D4(ii) ratified: *the in-chat SSE card is canonical*; "same modal" = **same policy and risk
taxonomy, not same component**. The card (`ChatApp.tsx:222-290`, fed by `useChat.ts`
`pendingApproval` + `lib/types.ts:374-382`) and `ui/approval-modal.tsx` must read the same
risk vocabulary. Concretely:
1. **Widen the FE card type** (`lib/types.ts:374-382`) to carry the trust fields the server
already emits — `riskLevel, approvalClass, trustSource, assessmentMode, explanation,
permissions`. **No parsing change needed** — the fields are already on the wire for
`install_capability` (`chat.ts:951-958`); `useChat.ts:252` casts straight to
`ApprovalRequest`, so once the type is widened TS stops hiding them.
2. **Render them in `ApprovalGate`** (`ChatApp.tsx:240-289`) — at minimum a risk badge +
trust-source line, using the **same RISK_LABELS/RISK_CLASSES** coloring as the modal
(`approval-modal.tsx:40-45,70-73`) so identical risk renders identically in both surfaces.
3. **Modal learns `approvalClass`** (`critical` especially) so a critical install no longer
renders identically to a high one, and so the modal can represent the `critical`/`blocked`
level the audit trail records (today it cannot — divergence #4).
4. **Critical-tier UX contract, decided once:** `deriveApprovalClass` marks high→`critical`
(full trust context + warning, never auto-pass). **The card today offers "Always allow"
(`ChatApp.tsx:267-274`) with NO risk gating** — a critical/high install can be permanently
granted in one click, which MCPHub's CRITICAL-non-overridable rule (`MCPHubApp.tsx:191-217`)
explicitly forbids. Gate "Always allow" by `approvalClass` so both surfaces honor the same
policy. **→ RATIFIED (founder, 2026-06-12): gate it.** A6 must hide/disable "Always allow"
on `critical` (and `high`) approvals — no permanent grant for the riskiest actions.
5. **Reconcile the plain-language field** — card `description` (never sent) vs modal `action`;
emit one agreed "what will happen" string server-side (or a shared `describeToolUse`
formatter) feeding both.
6. **(broader, see P7 order)** Extend server risk classification beyond `install_capability`
(`chat.ts:939` is the only enrichment branch) so the card has a risk class to show for
fs/shell/cross-workspace approvals — otherwise the two surfaces can only ever agree on
install events.
---
# PRIORITIZED P7 BUILD ORDER
TDD-friendly increments, commit-per-step, matching prior phase-plan cadence (complete →
verify → next). Each step states its verify gate. **`build:packages` first** (shared →
hive-mind-core → core → agent → server) on any cross-package change — the W4 stale-`dist/`
class (`open-questions.md:561`, D13). Run `tsc --noEmit` on touched packages; the server is
`tsx`-transpiled and NOT typechecked by `npm run build` (CLAUDE.md §2).
> **Sequencing RATIFIED (founder, 2026-06-12): Track B (P0 error states) FIRST, then Track A.**
> **A6 "Always allow" gate RATIFIED: gate by approvalClass (no permanent grant on critical/high).**
## STATUS — Track B DONE, Track A DONE (2026-06-12)
**Track B (P0 error states) — SHIPPED + reviewed + pushed.** B1–B5 + the 2 confirmed
review fixes (`548fbe8`→`9f3cf2a`); adversarial review 2 confirmed/9 refuted
(`p7-track-b-review-record.md`). FE 897/897.
**Track A (approval/audit taxonomy + D4(ii)) — SHIPPED + pushed (`7bbe5d8`→`7a8c374`):**
- A1 `7bbe5d8` — canonical `@waggle/shared/risk.ts` (widest-set enums + riskRank/sqlInList).
- A2a `7675802` — trust-model + confirmation re-pointed; classifyRisk +critical; deriveApprovalClass critical→critical + blocked-flag.
- A2b `d0b9aaa` — install-audit + team-governance; fixed critical-sorts-below-low RBAC defect.
- A3 `a412a8e` — install_audit CHECK single-sourced + OSS schema.ts parity test (no migration).
- A4 `239cc51` — server emits risk metadata for ALL gated tools (was install-only).
- A5 `dff44b8` — **D4(ii)**: card type widened + RiskBadge render via shared `risk-display`.
- A6 `3d9893f` — modal represents critical; **"Always allow" gated by approvalClass**.
- A7 `7a8c374` — shared `classifyInstallRisk` + audit-panel RISK_LABELS reuse.
**Post-launch divergences — ALL CLOSED (2026-06-12, founder "close them too"):**
- **#15** (`6fc8500`) — `install_audit.trust_source` DDL CHECK added (generated +
OSS-mirror parity-locked) with a rebuild migration; the column is no longer
unconstrained-at-DB while typed-closed in TS.
- **#8** (`c85c295`) — `actionRisk(kind)` in `risk-display` is now the single source
for the non-install approval surfaces' risk; AgentBuilder/AutomationBuilder/
ConnectorsApp/MCPHub/MarketplaceApp pull from it (0 scattered literals). The deeper
"displayed ≠ policy-engine risk" for these non-install actions stays an honest
action-kind default (no server TrustAssessment feed exists for non-install actions).
- **#17** (`3040a6a`) — `ApprovalModal` renders a structured `trustSource` line via
shared `TRUST_SOURCE_LABELS`; MarketplaceApp populates it (was a hand-built scope
string). Omitted when absent (no false provenance).
**D15 closure bar = Track A (A1–A7) + Track B P0 (B1–B5): MET. All 17 taxonomy
divergences now closed (HIGH #1–7 in A1–A6; MED/LOW #8/#14/#15/#16/#17 closed).**
## LAUNCH-BLOCKING (must ship for P7 to close D15)
**Track A — Approval/audit taxonomy + D4(ii) (HALF 2).** Order matters: the shared type is
the foundation everything else imports.
- **A1 — Shared risk module.** Create `packages/shared/src/risk.ts` exporting canonical
`RiskLevel`(+critical), `ApprovalClass`(+blocked), `TrustSource`(7-val), `AssessmentMode`,
`AuditAction`(7-val). *Verify:* unit tests assert each enum equals the widest existing set;
`tsc` shared green. *Commit:* `feat(shared): canonical risk/approval taxonomy (D15)`.
- **A2 — Backend imports the shared enums.** Re-point `trust-model.ts`, `confirmation.ts`,
`install-audit.ts`, `team-capability-governance.ts` at `@waggle/shared` risk types; give
`trust-model.classifyRisk` a `critical` path; make `deriveApprovalClass` emit `blocked`;
collapse the duplicate `getApprovalClass` mapping (`confirmation.ts:140-142`) onto the one
mapper. Fix `RISK_LEVELS` so `critical` sorts above `low` (div #11). *Verify:* existing
trust-model/confirmation tests stay green + new cases for critical/blocked; `tsc` agent+core+server.
*Commit:* `refactor(agent,core,server): single risk taxonomy source (D15)`.
- **A3 — Single audit CHECK source.** Generate/import the `install_audit` CHECK lists from the
canonical enums so `install-audit.ts` and `hive-mind-core/src/mind/schema.ts` cannot drift;
add the missing `trust_source` CHECK (div #14,#15). *Verify:* schema-parity test asserts both
CHECK strings derive from one constant; `auditStore.record()` round-trips a critical/blocked
row. **§7.5 OSS drift-check** (`scripts/oss-drift-check.sh`) since `schema.ts` is mirrored.
*Commit:* `fix(core,hive-mind-core): single-source install_audit CHECK constraints (D15)`.
- **A4 — Server risk path for ALL gated tools.** Extend the `chat.ts:939` enrichment branch so
every gated tool (not just `install_capability`) carries `riskLevel/approvalClass/trustSource`
on `approval_required`, derived from `PERMISSION_RISK_POINTS` (div #9). Emit a plain-language
action string (div #10). *Verify:* chat-route tests assert trustMeta present for a non-install
gated tool; server tsc. *Commit:* `feat(server): risk classification for all gated approvals (D15)`.
- **A5 — D4(ii): widen FE card type + render.** Widen `lib/types.ts:374-382` `ApprovalRequest`
with the trust fields; render risk badge + trust-source + explanation in `ApprovalGate`
(`ChatApp.tsx:240-289`) using shared RISK_LABELS/RISK_CLASSES. *Verify:* FE unit test —
an SSE payload with trustMeta renders a risk badge; `tsc -p apps/web/tsconfig.app.json`.
*Commit:* `feat(web): in-chat approval card renders server risk taxonomy — D4(ii) (D15)`.
- **A6 — Modal learns approvalClass + critical; gate "Always allow".** Add `approvalClass` to
`ui/approval-modal.tsx` + a `critical` RISK_LABELS/RISK_CLASSES entry; gate the card's
"Always allow" (`ChatApp.tsx:267-274`) by `approvalClass` (no permanent grant on critical).
*Verify:* FE tests — critical renders distinctly from high; "Always allow" hidden/disabled
on critical. *Commit:* `feat(web): approvalClass + critical tier in shared modal; gate Always-allow (D15)`.
- **A7 — Authoritative consumer risk.** Replace per-call-site `riskLevel` literals
(`ConnectorsApp.tsx:92`, `AgentBuilder.tsx:196`, `AutomationBuilder.tsx:254`,
`MCPHubApp.tsx:216,226`) with one shared classifier (generalize `installRiskFor`,
`MarketplaceApp.tsx:57-62`) keyed on action-kind + trust/scan signal; surface `trustSource`
in modal scope on all install surfaces (div #8,#17). Validate `InstallAuditPanel`
normalizer against the enums + reuse RISK_LABELS (div #16). *Verify:* FE tests — same
conceptual action yields same risk across surfaces. *Commit:* `refactor(web): authoritative shared risk classifier across approval surfaces (D15)`.
**Track B — State grid P0 errors (HALF 1).** Independent of Track A; parallelizable. Each is
the same mechanical fix (thread the `error` the hook already captures + `role=alert` + Retry).
- **B1 — Approvals error state.** `ApprovalsApp.tsx:77-78` — stop coercing to empty; add
error branch + Retry. *Verify:* FE test — failed fetch shows error, not "No pending approvals".
- **B2 — Room loading+error.** Add `connecting`/`error` to `useRoomState` (`useRoomState.ts:39-41`);
render connecting + error+reconnect in `RoomApp` (179-187). *Verify:* test — broken SSE ≠ empty.
- **B3 — Command Center error boundary + in-body error.** Wrap the overlay
(`AppShell.tsx:312`) in `AppErrorBoundary`; surface search/execute failures in-body. *Verify:*
test — a thrown ResultRow doesn't blank the shell.
- **B4 — Files real error vs offline.** Split cold-load error from `offline`
(`FilesApp.tsx:157-158`); add list-pane loading branch (469-549). *Verify:* test — 500 shows
error, not "cached files."
- **B5 — Waggle Dance + Memory/Timeline + Events + Settings catch.** One-line `error`
re-wires (`WaggleDanceApp.tsx:34`; `MemoryRoute.tsx:103`+`TimelineTab` prop;
`EventsRoute.tsx:16-20`) + the **`SettingsApp.tsx:168-171` missing `.catch`** (a real
unhandled-rejection defect — do not skip). *Verify:* per-screen test — failure ≠ empty.
## NICE-TO-HAVE (P2 — do if time; not gating D15 closure)
- **B6 — Vault + Settings + Timeline/Usage error states** (P1 list items 7-9): trust/secrets
matter but are lower-traffic; ship if A+B0 land with margin.
- **B7 — Tool Launcher empty, My Profile empty/error, Templates/Skills/MCP/Connectors partial
fixes, loading-flicker polish** (P2 list items 10-13).
- **B8 — `connecting` gates** on `TemplatesView.tsx:76`, `LauncherApp.tsx:130-132`,
`InstallAuditPanel.tsx:90` (cold-load 401 race; sibling apps already guard).
> **D15 closure bar:** Track A (A1–A7) **and** Track B P0 (B1–B5) are the launch-blocking
> minimum. B6–B8 are nice-to-have and may slip to a fast-follow without re-opening D15,
> provided no P0 error-as-empty remains on a core/trust surface.
---
# OUT OF SCOPE / POST-LAUNCH LEDGER
| Item | Why deferred | Anchor |
|------|--------------|--------|
| Connector `/sync` real implementation | D15 explicitly post-launch; stub stands | `open-questions.md:563` |
| MCP Hub "Logs" action | D15 explicitly post-launch; aria-disabled coming-soon today | `open-questions.md:563`, `InstalledMcpList.tsx:135-144` |
| Workspace Desktop research/timeline/settings tab bodies | Intentional `TabPlaceholder` stubs; tab embeds are P3/P7-tab-embed scope, deferred | `WorkspaceDesktopApp.tsx:955-1006`, `open-questions.md:621-622` |
| Team Governance real `/team` surface | D5 reserves Team work; static upsell card by design (RBAC Phase 5 founder-DEFERRED) | `TeamGovernanceApp.tsx:3-44`, `open-questions.md:547`, `project_rbac_phase5_deferred.md` |
| Marketplace partial-facet silent drop | Silent-by-design; only all-rejected surfaces error | `MarketplaceApp.tsx:170-179` |
| Workspace-scoped members (vs global roster) | Flagged Phase-5 gap in-code | `WorkspaceDesktopApp.tsx:722-724` |
| Builder catalog "which catalog failed" granularity | Partial-error nicety, not a masked-failure defect | `AgentBuilder.tsx:146-148` |
| `errorKind` auto-recover for `notfound`/`permission` mid-session | Intentionally non-revalidating; correct | `WorkspaceDesktopApp.tsx:662` |
| ChatWindowInstance FALLBACK_MODELS / status-bar chips / activeModels | P5→P7 ledgered residuals | `open-questions.md:594,621-622` |
| `memory-mcp` vs `hive-mind-mcp-server` canonical-package decision | Out of launch scope; mark dormant | `open-questions.md:568` |
| teams-server boot error (`Fastify instance is already listening`) | Solo boot path unaffected; classify post-launch | `open-questions.md:567` |
---
*Scope authored 2026-06-12. Read-only pass — no code modified, no tests/tsc run. Ground all
implementation against re-read source per CLAUDE.md §3.5 (context decay).*

63
docs/ux-refactor/p7-p5-live-smoke-record.md Normal file
View File

@@ -0,0 +1,63 @@
# P5 + P7 — Live Browser Smoke Record (2026-06-12)
> Real-browser verification of the launch-critical P5 (skill governance) + P7/D15
> (error states + risk taxonomy) work, run against a live local stack: sidecar
> (Fastify, :3333, anthropic-proxy provider) + vite dev server (:8080) + Playwright.
> Goal: confirm no real-browser gap that the unit/integration suites couldn't catch.
## Verdict: PASS (core goal met)
App boots clean and **every screen changed in P5/P7 renders correctly with 0 console
errors attributable to the changes**. The P5 provenance→badge chain is verified
end-to-end in the browser. One residual (live approval-card trigger) is unit-covered.
## What was verified
| Surface | Phase | Result |
|---------|-------|--------|
| Boot → `/home` (Home Cockpit) | regression | Renders full briefing; **0 console errors** |
| `/approvals` | B1 | Empty state ("No pending approvals") on the success path — correct; no error-as-empty, no crash |
| `/skills` (Skills Hub) | P5/D4iv | Renders; see end-to-end badge check below |
| `/room` | B2 | "idle-empty" — SSE subscribed OK, settled (not stuck connecting, not error); the connecting/error/idle distinction works |
| `/files` | B4 | Populated (real load) — no false cold-load error; `loadedPath` gating correct |
| `/settings/events` | B5 | Renders; no error boundary, no false "couldn't load" |
| `/memory` | B5 | Two-mind Memory Center renders; no error boundary |
| `/settings` | B5 | Renders; **no unhandled promise rejection** (the getTelemetryStatus `.catch` fix held) |
**Cumulative: 0 console errors** across all 8 screens (`all: true`).
### P5/D4iv provenance badge — verified END-TO-END in the browser
1. Wrote an agent-stamped skill (`initiator: agent`, `source: chat`) directly to
`~/.waggle/skills/smoke-agent-skill.md`.
2. `GET /api/skills` returned `{ initiator: 'agent', source: 'chat', preview: '<body>' }`
— provenance present **and the preview is the clean body, not the YAML frontmatter**
(confirms the P5-review fix #3 live).
3. Reloaded `/skills` → the skill row rendered the **"agent · review"** badge
(`rowHasBadge: true`, exactly 1 badge), and did NOT also wear the name-heuristic
"custom" label (P5-review fix #5). Cleaned up the smoke skill afterward.
## Residual (NOT verified live — unit-covered)
- **A5/A6 in-chat approval card with the risk badge + Always-allow gating** was not
triggered live: it needs a real workspace chat + a deterministic LLM tool-call to
produce an `approval_required` event, which is flaky. The attempt hit a routing stub
(`/workspaces/default/chat` 404s `/context` — `default` is not a real workspace id,
pre-existing, unrelated to P5/P7).
- **Coverage that stands in:** `p7-a5-approval-card-risk.test.tsx` (badge renders incl.
critical), `p7-a6-approval-gating.test.tsx` (modal represents critical; Always-allow
gated by approvalClass), and the A4 `classifyGatedToolRisk` unit tests. The FE data
path is a type-only widening (`useChat` casts the SSE payload straight to
`ApprovalRequest`), so the fields the A4 server enrichment sends are already present
at runtime — the unit tests exercise the render of exactly that shape.
- **To close fully** (post-launch nicety): drive a chat in a real workspace that elicits
a `write_file`/`bash` call and assert the card shows the RiskBadge + that "Always allow"
is hidden on a critical op.
## Environment notes (for the next smoke)
- Sidecar: `WAGGLE_SKIP_LITELLM=1 node --env-file=.env node_modules/tsx/dist/cli.mjs packages/server/src/local/start.ts` → :3333 (anthropic-proxy; ioredis ECONNREFUSED on :6381 is non-fatal noise; Redis not required).
- Vite: `npm run dev` → :8080, proxies `/api`,`/health`,`/ws` → 3333.
- `build:packages` must be green first (hive-mind-core exports only `dist/`).
- Stop servers by port via PowerShell `Stop-Process` (PID from `netstat -ano | grep ":<port> "`).
- `.playwright-mcp/` artifacts are gitignored.

42
docs/ux-refactor/p7-track-a-review-record.md Normal file
View File

@@ -0,0 +1,42 @@
# P7/D15 Track A — Adversarial Review Record
> Multi-agent review of the full Track A taxonomy diff (`7bbe5d8^..0f0a00e`): **6 dimension
> reviewers → 3-lens adversarial verification** (correctness / type-and-runtime-safety /
> reproduction; confirmed if ≥2 of 3 vote real). 30 agents, ~3.0M subagent tokens, ~13 min.
> Fixes in `1f8eab3`.
## Tally
**8 findings → 4 confirmed (3 distinct) / 4 refuted.**
| # | Sev | Votes | Dimension | Finding | Disposition |
|---|-----|-------|-----------|---------|-------------|
| 1/2 | MED+LOW | 3/3 + 2/3 | enum-exhaustiveness | `generateExplanation` (trust-model) had no `'critical'` branch — A2 widened RiskLevel 3→4 but this if-chain fell through to the `'high'` "Elevated risk" string. A critical capability's prose contradicted the "Critical" RiskBadge on the same approval card (badge says Critical, text says Elevated) — on precisely the most dangerous installs. tsc didn't catch it (if-chain, not exhaustive switch). | **FIXED** — added a `critical` branch + an `assertNeverRisk` exhaustiveness guard so the next RiskLevel widening fails tsc instead of silently mislabelling. Test: a 9-point assessment is `critical` and its explanation says "Critical risk", not "Elevated risk". |
| 3 | MED | 3/3 | a4-server-enrichment | A4 hardcoded `trustSource:'local_user'` for every non-install gated tool. `local_user` canonically means "user-created via create_skill", so a `git push` / `connector_*_send_email` / gated `bash` rendered **`Source: local_user`** on the in-chat card — a false provenance claim on the very surface whose job is to convey provenance. | **FIXED** — `trustSource` is now **omitted** in the heuristic branch (no real provenance signal exists for a shell/git/connector call; the FE already guards on `request.trustSource &&`, so the row disappears). |
| 4 | LOW | 2/3 | a4-server-enrichment | `describeToolUse` returned the generic `"Using <name>…"` default for `git_push`/`git_merge`/`git_pr`, connector writes, and cross-workspace reads, so the A4 `description` wasn't action-specific. | **FIXED** — added `git_push`/`merge`/`pr` cases + prefix handling for `connector_<id>_<action>` ("create issue via jira") and `read_other_workspace*`. |
### Folded in (refuted HIGH, but a cheap real hardening)
The `a5a6-fe-flow` HIGH — *"enrichment failure makes Always-allow fail OPEN for the
riskiest tool"* (1/3, refuted) — was nonetheless addressed: the `install_capability`
catch now **falls back to `classifyGatedToolRisk`** so `approvalClass` is NEVER absent.
A failed content-based assessment can no longer leave `approvalClass` undefined →
`canAlwaysAllow(undefined)===true` → "Always allow" shown on a critical install. The
panel refuted it as unlikely-to-throw, but closing the fail-open path is one line and
defensible, so it shipped.
## Refuted (4)
- **A3 parity test doesn't cover the db.ts migration sentinel** (MED, 1/3) — the parity
test pins the DDL CHECK lists; the migration sentinel is covered by the install-audit
migration test. Out of A3 scope.
- **Always-allow fail-open** (HIGH, 1/3) — refuted as unlikely, but hardened anyway (above).
- **Non-install hardcoded trustSource/assessmentMode** (LOW, 1/3) — the trustSource half
was the same root as #3 (fixed); assessmentMode `'heuristic'` is accurate, kept.
- **RiskBadge indexes shared maps with an unvalidated SSE risk string** (LOW, 0/3) — the
maps are exhaustive over RiskLevel and the badge only renders when `request.riskLevel`
is set by the server (a closed set); no unvalidated-index crash path.
## Gate (post-fix)
tsc 0 (agent/core/server) · agent 82 + chat-helpers 117 green · lint 0. `1f8eab3`.

45
docs/ux-refactor/p7-track-b-review-record.md Normal file
View File

@@ -0,0 +1,45 @@
# P7/D15 Track B — Adversarial Review Record
> Multi-agent review of the Track B error-state diff (`e797926..cce3ef0`): **5 per-screen
> reviewers → 3-lens adversarial verification** (correctness / state-machine-races /
> reproduction; confirmed if ≥2 of 3 vote real). 38 agents, ~2.3M subagent tokens.
> Fixes in `9f3cf2a`.
## Tally
**11 findings → 2 confirmed / 9 refuted.** Both confirmed were in B4 (Files), one root cause.
| # | Sev | Votes | Screen | Finding | Disposition |
|---|-----|-------|--------|---------|-------------|
| 1 | MED | 2/2 | files | Cross-directory nav failure: stale entries from the prior dir keep `files.length>0`, so the `offline && files.length===0` error gate is skipped → a failed `/sub` load renders "Empty directory" + a contradictory "showing cached files" banner | **FIXED** — `loadedPath` (set only on success); cold-error gate = `offline && !haveCurrentData` where `haveCurrentData = loadedPath===currentPath`. Regression test: nav into a failing subdir → error, not empty. |
| 2 | LOW | 2/2 | files | A known-empty dir (`[]` loaded OK) then a failed refresh → `files.length===0` → false "Couldn't load files" for a dir we proved empty | **FIXED** — same `loadedPath` signal: a failed refresh keeps `haveCurrentData` true → falls through to "Empty directory", not the cold error. Regression test: context-menu Refresh → reject → stays empty. |
Both fixed together by replacing `files.length` inference with an explicit `loadedPath`
load-outcome signal, making error / empty / cached-banner mutually exclusive regardless of
stale cross-directory data. `loading` initial state flipped to `true` so the first paint
isn't a false empty.
## Refuted (9, all 0–1/3)
The panel correctly dismissed every other finding, several with detailed traces:
- **Room "error UI dead in production" (HIGH, 1/3)** — claimed real SSE failures (401/drop)
never set `error`. Refuted: the adapter's reconnecting EventSource handles `onerror`
internally (close→backoff→token-refresh→reopen) and surfaces nothing to the hook *by
design* (D3 SSE-revival contract). `error` correctly fires only on a synchronous
subscribe throw; the async path is the adapter's job, not a Track B regression.
- **Approvals partial-success / poll-flash (HIGH+MED, 0/3)** — the single `error` does not
defeat partial success: `allSettled` still renders the fulfilled source; a transient poll
failure resolving to error-then-heal is the intended 5s-cadence behavior.
- **Room `connecting` sync-flip, error∧tiles coexistence (MED+LOW, 0/3)** — when `error` is
truthy the event callback never ran, so `workspaceMap` is empty and the ungated tile
blocks are unreachable; no state combo renders tiles beside the error.
- **Command Center boundary/portal, searchDegraded race (0/3)**, **B5 filter-masking /
gate-coverage (0/3)** — traced and dismissed.
## Gate (post-fix)
FE 897/897 · tsc 0 (apps/web) · lint 0. `9f3cf2a`.
> Note: several verifier agents hit a weekly model limit mid-run; both confirmed findings
> reached a clean 2/2 and the load-bearing refutals completed, so the verdict is sound.

146
docs/ux-refactor/path-exec-phase-A-spec-2026-07-07.md Normal file
View File

@@ -0,0 +1,146 @@
# Path-to-9 execution · PHASE A — motion vocabulary (Phase-0) + AA/affordance floor (Pillar 4)
### Contract: docs/ux-refactor/path-to-9-2026-07-07.md (v3, 5/5 panel-endorsed). Same honesty
### rules as waves P–X: surgical, both themes, testids/aria survive, reduced-motion gated.
Two sequential stages (stage 2 depends on stage 1's exports). Per-lane gate: related
vitest green + eslint 0 errors on touched files. NO benchmarks/**, NO packages/hive-mind-*.
## STAGE 1 (parallel lanes)
### Lane M — motion tokens + spring family + spec page (Phase-0 items 1,2,3,5,7)
NEW files only + index.css additions. Files: `apps/web/src/lib/motion/tokens.ts` (new),
`apps/web/src/lib/motion/tokens.test.ts` (new), `apps/web/src/pages/MotionSpec.tsx`
(new, DEV-only route), route wiring (find the router config; gate the route on
`import.meta.env.DEV`), `apps/web/src/index.css` (append motion custom props ONLY).
1. **The exported vocabulary** (`lib/motion/tokens.ts`) — THE single motion source:
```ts
export const SPRING = {
micro: { type: 'spring', stiffness: 550, damping: 35 }, // chips, presses, ≤150ms feel
standard: { type: 'spring', stiffness: 380, damping: 30 }, // hovers, panel/route fades
expressive: { type: 'spring', stiffness: 260, damping: 24 }, // hero morphs, settle gesture
} as const;
export const DUR = { fast: 0.15, base: 0.2, slow: 0.32, settle: 0.4 } as const; // seconds
export const EASE_OUT = [0.22, 1, 0.36, 1] as const; // cubic-bezier for non-spring CSS
export const STAGGER = { list: 0.04, brief: 0.08 } as const; // Wave W's 40ms / briefing 80ms
/** Signature-moment frequency taxonomy (Phase-0.7): FULL settle only on rare
* accrual milestones; MICRO for high-frequency actions; per-session cooldown. */
export const SIGNATURE = {
full: { moments: ['memory-saved-first-of-session', 'install-success', 'agent-spawned'], durS: DUR.settle, perSessionCooldownMs: 60_000 },
micro: { moments: ['send-arm', 'selection'], durS: DUR.fast },
} as const;
/** Reduced-motion mapping per tier (Phase-0.3) — documented AND consumed. */
export const REDUCED = {
routeTransition: 'crossfade-only', hover: 'color-shadow-only-no-transform',
settle: 'instant-state-color-pulse', streamingCaret: 'static',
countUp: 'instant-set', ambient: 'off',
} as const;
```
Tune values to FEEL right (the numbers above are starting points — validate on the
spec page); all three springs must share one physical character (same "material").
2. **CSS custom props** appended to index.css `:root` (both themes inherit — motion is
theme-invariant): `--mo-fast: 150ms; --mo-base: 200ms; --mo-slow: 320ms;
--mo-settle: 400ms; --mo-ease: cubic-bezier(0.22,1,0.36,1);` Nothing else in this file.
3. **Motion-spec page** (`/motion-spec`, DEV-only): sections demonstrating each spring
variant (click-to-replay), hover tier on a sample card, entrance stagger, exit
choreography (AnimatePresence in/out samples), the reduced-motion mapping table, and
an INVENTORY table of already-shipped motion (see Lane R's list) with its migration
status. This page is the arc's reviewable single source of motion truth.
4. Tests: token invariants (all springs share type, DUR ascending, SIGNATURE moments
disjoint, REDUCED covers every tier key).
### Lane T — text-tertiary + focus-ring token tiers + offender migration (Pillar 4 items 1 + 3)
Files: `apps/web/src/index.css` (token definitions ONLY — coordinate with Lane M: Lane M
appends motion props, Lane T appends color tokens; both are pure additions in different
blocks, no shared lines), `os/StatusBar.tsx`, `overlays/onboarding/WelcomeStep.tsx`,
`overlays/LoginBriefing.tsx` ("Don't show again"), plus the specific offender usages
listed below. Tests updated where classes are asserted.
1. **`--text-tertiary`**: a tier that is ≥4.5:1 on EVERY surface it appears over
(--bg, --bg-2, --surface, --surface-2) in BOTH themes. Compute (WCAG relative
luminance) and document the math in a comment next to the token. Dark: needs
≥ #a3987f-level; light: ≤ #6e6552-level. Verify per pair; show ratios.
2. **`--focus-ring` + `--line-affordance`** (Pillar 4.3, WCAG 1.4.11): non-text tier
≥3:1 against adjacent effective background BOTH themes — the light-theme honey ring
is the known risk (honey-on-ivory); compute and pick the light value accordingly
(e.g. a darker honey/ochre for light). Document ratios in-comment.
3. **Migrate the recurring offender families** onto --text-tertiary (verify each is
still a REAL failure first — several were fixed in Waves V/X; do not churn
compliant code): top utility bar (StatusBar plan/search/date cluster), onboarding
subtitle + privacy footnote ("Skip setup" was fixed — verify), "Don't show again",
unselected onboarding chips (raise rest contrast), card timestamps if any remain
sub-AA. Compute before/after ratios in the lane report.
### Lane G — the CI gates (Pillar 4 item 2 + verification plumbing)
NEW files: `scripts/ux-gates/contrast-tokens.mjs`, `scripts/ux-gates/text-color-guard.mjs`,
`scripts/ux-gates/contrast-runtime.mjs`, `scripts/ux-gates/README.md`; `package.json`
(root): three npm scripts (`ux:contrast`, `ux:color-guard`, `ux:contrast-runtime`).
Do NOT touch .github/workflows (wiring into CI is a follow-up once scripts are proven).
1. **contrast-tokens.mjs**: parse index.css (+ waggle-theme.css if it defines text
tokens), compute WCAG ratios for every (text-token × surface-token) pair in both
themes, assert the documented floors (--text/--text-2/--text-muted/--text-tertiary
≥4.5:1 on their allowed surfaces; --focus-ring/--line-affordance ≥3:1). Exit 1 on
failure with a table. Must run green against Lane T's final tokens.
2. **text-color-guard.mjs** (the generation-vector ban): scan apps/web/src (app
surfaces; exclude tests, the tokens file, MotionSpec) for NEW non-token text
colors: `text-[#`, raw hex in inline `style` color/background of text elements,
`text-hive-*` palette classes, and opacity-modified text tokens BELOW the safe
floor (`text-[var(--text-dim)]/40` style patterns; allow ≥/60 with a warning
list). Baseline file (`scripts/ux-gates/color-guard-baseline.json`) freezes
today's grandfathered instances; the gate fails only on NEW instances — a
ratchet, not a big-bang.
3. **contrast-runtime.mjs** (composition-aware, Playwright): against the dev server,
for each judged surface (/home, /workspaces, /memory, /agents, /marketplace,
/settings, chat), walk visible text nodes, compute EFFECTIVE fg/bg (composite
opacity up the tree; sample wallpaper/gradient via screenshot pixel at element
center when bg is an image), report all <4.5:1 (text) and <3:1 (focus indicators
— tab to 10 interactive elements per surface and measure the ring). Output a
JSON + human table; exit 1 on NEW failures vs a baseline. Seed localStorage
onboarding like the capture kit; run both themes.
## STAGE 2 (parallel lanes; imports from Lane M's tokens — stage 1 merged first)
### Lane R1 — retrofit: cards + entrances (Phase-0.6)
Files: `apps/AllWorkspacesApp.tsx`, `apps/agents/SuggestedAgentCards.tsx`,
`apps/extend/ExtensionCard.tsx`, their tests.
Migrate every duration/easing to the vocabulary: hover transitions → `--mo-fast/--mo-base`
+ `--mo-ease` (or SPRING.standard where framer-motion), entrance stagger → STAGGER.list
+ DUR.slow, lift/bloom timings → tokens. Acceptance: `grep -E "duration-(75|100|150|200|300|500)|duration: '?0\.[0-9]|ease-(linear|in-out|out)\b"` on these files returns
ONLY token-backed or justified-in-comment instances; zero raw magic numbers.
### Lane R2 — retrofit: memory + briefing + boot + theme (Phase-0.6)
Files: `apps/memory/MemoryTrustManage.tsx`, `apps/memory/MemoryCenterTab.tsx`,
`os/overlays/LoginBriefing.tsx`, `os/BootScreen.tsx`, `providers/ThemeProvider.tsx`
(+ index.css `.theme-transition` duration → var), tests.
Same acceptance as R1. The 600ms count-up, 360ms crossfade, briefing staggers, boot
phase timings all move onto DUR/STAGGER/custom props (keep the VALUES if they feel
right — tokenize, don't retune; note any value you deliberately change).
### Lane R3 — retrofit: chat + status chrome + keyframe sweep (Phase-0.6)
Files: `apps/ChatApp.tsx`, `os/StatusBar.tsx` (transition durations only — Lane T owns
its colors), `apps/WorkspaceDesktopApp.tsx`, index.css @keyframes durations where
referenced with magic numbers in components, tests.
Same acceptance. Also produce THE INVENTORY: a table (append to the motion-spec page's
inventory section — coordinate: R3 owns the final inventory content) of every motion
in the judged surfaces: name, file, tier, duration token, reduced-motion behavior.
## VERIFY STAGE (after stage 2; parallel)
- **Reviewer V1 (motion)**: adversarially verify Phase-0 acceptance — grep the judged
surfaces for non-token durations/easings (list any survivor with justification
status), confirm the spec page renders every tier, confirm reduced-motion mappings
are implemented not just documented (inspect the code paths).
- **Reviewer V2 (floor)**: run `node scripts/ux-gates/contrast-tokens.mjs` and
`node scripts/ux-gates/text-color-guard.mjs`; start dev servers if needed and run
`contrast-runtime.mjs` on at least /home + /settings both themes; report the tables.
Verify Lane T's in-comment math independently (recompute 3 spot pairs).
## Orchestrator after verify
Full tsc (web), full apps/web vitest, eslint on all touched files, browser smoke
(motion-spec page renders; one hover; theme flip), commit per stage or as one Phase-A
commit. Then Phase B (Pillar 2) spec.
## Deferred in Phase A (explicitly)
Competitive teardown side-by-sides (needs founder's Claude/ChatGPT sessions — flagged,
not skipped silently); .github/workflows wiring (after scripts prove stable); the
waggle-settle prototype (Pillar 1.3 — its own commissioned mini-arc later).

84
docs/ux-refactor/path-exec-phase-A2-spec-2026-07-07.md Normal file
View File

@@ -0,0 +1,84 @@
# Path-to-9 execution · PHASE A2 — complete the retrofit (R2/R3 died mid-flight) + V1/V2 findings
### Continues docs/ux-refactor/path-exec-phase-A-spec-2026-07-07.md after checkpoint `f2ab5896`.
### V1-motion reviewer FAILED acceptance with exact findings — they are the contract below.
### Same house rules. Per-lane gate: related vitest + eslint 0 errors. NO benchmarks/**, NO hive-mind.
## STAGE 1 (parallel — disjoint files)
### Lane R2 (retry) — memory + briefing + boot + theme retrofit
Files: `os/BootScreen.tsx`, `apps/memory/MemoryTrustManage.tsx`, `apps/memory/MemoryCenterTab.tsx`,
`providers/ThemeProvider.tsx`, `os/overlays/LoginBriefing.tsx`, tests. Do NOT touch index.css
(Stage-2 Lane R3 owns it) — ThemeProvider's JS-side 420ms timer aligns to the token value via
a shared constant/var read, or a comment-justified literal if the CSS var isn't readable there.
V1's exact survivors to tokenize (verify each live, then migrate to --mo-*/DUR/SPRING/STAGGER):
- BootScreen.tsx L89/144/151/163/182/194 — raw 0.5/0.3/0.4/0.2s + easeIn/Out.
- MemoryTrustManage.tsx L257 'card-enter 0.32s ease-out' + L605 '0.15s'.
- MemoryCenterTab.tsx L399 '0.15s'.
- LoginBriefing.tsx L297 raw duration:0.2 + ease:'easeOut' + local ENTER_STAGGER=0.08 literal
→ STAGGER.brief / DUR.base / EASE_OUT imports from lib/motion/tokens.
Tokenize, don't retune (values stay; only the source of truth changes). Reduced-motion
behavior of every migrated site must match the REDUCED mapping (most already gate via
useReducedMotion — verify, don't assume).
### Lane F2 — floor residuals + runtime-gate hardening
Files: locate-and-fix the THREE real near-AA residuals (V2's list, verify each live with
computed ratios before/after in the report): dark "workspace" label 4.38:1 (--text-dim over
--surface — likely Sidebar workspace sublabel), light "Solo" tier label 4.47:1, light
"Models" section label 3.88:1 (/settings). Informative text → --text-tertiary (or the
correct existing AA token); decorative-only text may stay dim WITH a justifying comment.
Plus `scripts/ux-gates/contrast-runtime.mjs` hardening: detect no-opaque-ancestor /
animating-opacity subtrees (the TrialExpiredModal false-positive cluster at 1.15–2.09:1 and
the two 'Fallback' 1.0:1 rows) and screenshot-sample those instead of CSS compositing.
Do NOT seed the baseline (post-stage-2 job — the tree is still moving).
## STAGE 2 (parallel — disjoint files; stage 1 merged)
### Lane R3 (retry) — chat + status chrome + index.css + THE INVENTORY TRUTH
Files: `apps/ChatApp.tsx`, `os/StatusBar.tsx`, `apps/WorkspaceDesktopApp.tsx`,
`apps/web/src/index.css` (reduce block + .theme-transition), `pages/MotionSpec.tsx`, tests.
V1's exact findings to close:
1. index.css `.theme-transition` L698 raw 360ms → `var(--mo-slow)` (or a dedicated
--mo-theme var if 360≠320 is deliberate — decide, justify in-comment; keep ThemeProvider's
JS timer consistent, coordinate value with what R2 left there).
2. index.css reduce block gates only 5 classes: extend `@media (prefers-reduced-motion)`
to cover EVERY in-use animated class per the REDUCED mapping — specifically honey-pulse
(used by StatusBar L152 with NO guard) and float (ChatApp L1003, unconditional). Audit
the rest of the @keyframes zoo: every class used in components either appears in the
reduce block or its component gates via useReducedMotion.
3. Dead inventory claims: 'hex-cursor caret static' and 'send-flash instant' are table text
with NO component applying those classes — either wire the real behavior or mark the
rows honestly as N/A-dead-class (do not fabricate).
4. Tokenize remaining raw durations in ChatApp (finish the partial edit), StatusBar,
WorkspaceDesktopApp.
5. **MotionSpec inventory TRUTH** (V1 blocking #3): the inventory currently claims '✓ R2'
/ 'ambient ✓' / 'signature ✓' for work that never landed and an honesty note stating
rows are 'applied in THIS commit' falsely. Rebuild the table from the ACTUAL tree state
after your own edits (grep, don't trust prior rows); every row's status must be
verifiable. The inventory misrepresenting reality is worse than no inventory.
### Lane R4 — the sweep: zero unjustified raw motion on judged surfaces
Files: everything under `apps/web/src/components/os/**` NOT owned by another lane this
phase (EXCLUDED: BootScreen, MemoryTrustManage, MemoryCenterTab, LoginBriefing, ChatApp,
StatusBar, WorkspaceDesktopApp, AllWorkspacesApp, SuggestedAgentCards, ExtensionCard,
onboarding WelcomeStep/WhoAreYouStep) + their tests.
Method: grep the scope for raw durations/easings (duration-NNN, duration-[NNNms] non-var,
`duration: 0.N`, transition inline styles, ease-out/in literals where a token exists);
migrate each to --mo-*/DUR/EASE_OUT; a site that is deliberately non-standard keeps a
one-line justifying comment instead. Report the FULL before/after list. Acceptance =
V1's criterion: zero UNJUSTIFIED non-token durations/easings across os/**.
## VERIFY (after stage 2)
- **V1'-motion (adversarial re-run)**: the same acceptance V1 failed — grep os/** for
unjustified raw motion (report every survivor), confirm the reduce block + component
guards cover every in-use animated class, confirm the MotionSpec inventory now matches
the tree (spot-verify 6 rows with grep), run the motion token tests.
- **V2'-runtime**: run contrast-tokens + text-color-guard (must stay green); run the
HARDENED contrast-runtime on /home + /settings both themes against the dev server
(vite 8080 — if down, start per handoff recipe or report inability); confirm the three
residuals now pass and the TrialExpiredModal cluster no longer false-positives; then
SEED contrast-runtime-baseline.json from this clean run (triage: the baseline must
contain only verified-acceptable rows, listed in your report) and re-run to prove exit 0.
## Orchestrator after verify
tsc web + full apps/web vitest + all three ux-gates green → commit "Phase A complete" →
launch Phase B (docs/ux-refactor/path-exec-phase-B-spec-2026-07-07.md).

132
docs/ux-refactor/path-exec-phase-B-spec-2026-07-07.md Normal file
View File

@@ -0,0 +1,132 @@
# Path-to-9 execution · PHASE B — instant power feel (Pillar 2)
### Contract: docs/ux-refactor/path-to-9-2026-07-07.md v3 §Pillar 2 (5/5 panel-endorsed).
### Prereq: Phase A merged (motion tokens exist — use SPRING/DUR/STAGGER + --mo-* vars for
### ALL new motion; the text-color guard is live — new text uses tokens).
Recon facts (verified pre-spec): Home loads via `adapter.getHomeBriefing()` +
`getHomeOvernight()` in HomeCockpit L549-589, gated on `connecting` settle, NO
persistence. LoginBriefing has its own module-scope `fetchBriefingData` + prefetch
(Wave T) — a SECOND data source (the drift-bug class the contract kills). Chat send
already renders an optimistic turn (ChatApp L741 comment); briefing landing state
machine `nextBriefingLanding` lives in AppShell (Wave U); BootScreen has `ready` prop +
850ms floor (Wave U). Session caches exist for memory (memory-list-cache.ts) and the
workspace shelf (module-scope in AllWorkspacesApp).
Per-lane gate: related vitest green + eslint 0 errors + `node scripts/ux-gates/text-color-guard.mjs`
clean on touched files. NO benchmarks/**, NO packages/hive-mind-*/**. NO cross-lane files.
## Lane H — home cache-first paint + one briefing truth + double-catch-up collapse (Pillar 2.1–2.4)
Files: `apps/HomeCockpit.tsx`, `os/overlays/LoginBriefing.tsx`, `os/AppShell.tsx`,
`os/BootScreen.tsx`, NEW `lib/home-cache.ts`, NEW `lib/briefing-source.ts`, tests.
The heart of the pillar — one lane so the data-unification isn't split across owners.
1. **Disk-persisted cache-first paint** (`lib/home-cache.ts`): persist the last
successful Home payload (briefing + overnight + the recall highlights) to
localStorage (versioned key, schema-guarded parse, size-capped). On mount,
HomeCockpit renders the cached payload IMMEDIATELY (before `connecting` settles,
before the sidecar answers) marked stale-invisible (no visual difference), then
refreshes silently. Day-0 (no cache) keeps today's skeleton path.
2. **Silent-refresh reconciliation CONTRACT** (v3 P2.3 — this is a TESTED contract):
when fresh data lands over a cached paint — (a) NO above-the-fold layout shift:
fixed-slot hero grammar (the Wave T card contract, applied to the hero) so text
swaps in place; (b) material deltas (counts, new items) animate via a small
honey delta pulse (use SPRING.micro/DUR.fast from Phase A — this is Pillar 3.3's
pulse, born here); (c) unit-test: cached render → fresh data with changed counts →
assert no element above the fold unmounts/remounts (key stability) and the
changed count carries the pulse class.
3. **ONE briefing truth** (`lib/briefing-source.ts`): extract LoginBriefing's
fetch+shape (fetchBriefingData/prefetch, highlights, workspace summaries,
brag counts) into this module. BOTH the home hero and the modal consume IT —
one fetch, one filter set, one count. Delete the second source. The
number-drift bug class dies here (regression-test: hero count === modal count
from the same mock).
4. **Double catch-up collapse** (v3 P2.4): the "I REMEMBER" recall cards render
INSIDE the home hero as its first staggered entrance (STAGGER.brief from
Phase A tokens); the modal fires ONLY on ≥7-day absences (N=7 per contract —
compute from the same lastActive the greeting uses), reusing the SAME card
component + briefing-source data. Update `nextBriefingLanding` gating in
AppShell accordingly (armed additionally requires awayDays ≥ 7). Tests: <7d →
no modal, cards in hero; ≥7d → modal (same data object as hero).
5. **Warm boot floor removal**: with cache-first paint, the BootScreen floor for
warm sessions drops — boot shows only until the shell mounts (brand flash
≤500ms; keep the full choreography for COLD/day-0 sessions where there is
nothing to paint). Keep Wave U's `ready` semantics for the cold path.
## Lane C — input-during-warmup + send-path budget + chat route-cache (Pillar 2.2, 2.5, 2.6-chat)
Files: `apps/ChatApp.tsx`, the chat state hook it uses (grep `useChat`/chat widget
state — verify real file), `os/WorkspaceDesktopApp.tsx` (entry interactivity only), tests.
1. **Composer accepts typing at paint**: the composer input must be enabled the
moment it renders — never disabled behind `connecting`/history-load. If a send
fires before the sidecar is ready: QUEUE it (one-deep queue is fine) with a
truthful per-message "waiting for connection…" state on the optimistic turn,
dispatch on ready, NEVER error or silently drop. Test: type+send while mocked
adapter is pending → message queued → adapter resolves → dispatched.
2. **Composer never locks on send**: verify (and lock with a test) that after send
the input clears and accepts the next message immediately while the previous
streams — no disabled window. If a lock exists, remove it.
3. **No dead clicks on cached surfaces**: WorkspaceDesktopApp entry — clicking a
tab/affordance during the entry skeleton either acts or shows a per-element
pending affordance (aria-busy + subtle shimmer), never nothing. Audit the entry
skeleton's click handling; fix silent swallows.
4. **Chat thread session cache**: mirror memory-list-cache — thread messages keyed
by (workspace, session) survive tab-away/return within the session; returning
renders instantly then refreshes silently. No re-skeleton on return.
## Lane K — keyboard-power layer (Pillar 2.7; double-yield with a11y)
Files: `os/WorkspaceActionsMenu.tsx` + `os/ContextMenu.tsx` (focus-reveal parity),
`apps/memory/MemoryTrustManage.tsx` (row-action focus parity ONLY — rest is Lane H/C
territory... verify no overlap; MemoryTrustManage is NOT touched by H/C in this phase),
`os/overlays/KeyboardShortcutsHelp.tsx`, `hooks/useKeyboardShortcuts.ts`, tests.
1. **Focus-reveal parity**: workspace-card kebab + memory-row actions (✓/✎/🗑)
reveal on :focus-within with visible focus-ring (the Phase-A `--focus-ring`
token), matching the chat action-row pattern (Wave T). Tab-through must reach
every action without a mouse.
2. **Hit areas**: kebab, memory row actions, modal ×, "Fix it now" → ≥40px
effective hit target (padding/pseudo-element expansion, no visual size change
needed). List each touched target + before/after size in the report.
3. **≤2-keystroke paths**: global shortcuts — new chat (existing? verify in
useKeyboardShortcuts; add if missing) and "open last workspace"; both reachable
from anywhere, documented in KeyboardShortcutsHelp.
4. **Shortcut cheat sheet**: verify KeyboardShortcutsHelp opens on `?` (and Cmd-/);
add the new shortcuts; ensure it lists the focus-reveal patterns ("Tab reaches
card actions").
## Lane R — route-cache: marketplace + agents (Pillar 2.6)
Files: `apps/MarketplaceApp.tsx`, `apps/AgentsApp.tsx`, NEW `lib/surface-cache.ts`
(generalize the memory-list-cache pattern: keyed session cache + test reset), tests.
1. Extract the proven pattern into `lib/surface-cache.ts` (typed, keyed, module-
scope, `resetForTests`). Do NOT migrate memory/workspaces onto it in this phase
(churn without yield — note as follow-up).
2. Marketplace: extensions list + facet state seed from cache on return; silent
refresh; no re-skeleton within a session.
3. Agents: roster + suggested cards seed from cache on return; same contract.
## Lane G2 — the hard interaction gate (v3 §3 verification)
NEW files: `scripts/ux-gates/warm-interaction-gate.mjs`, README update; root
package.json script `ux:warm-gate`. Playwright, mirrors capture-kit conventions
(seeded returning-user localStorage; disclose in output).
1. **Warm gate**: measure app-start → (a) home content visible, (b) composer
accepts a keystroke (type into it, assert value). FAIL if content >1000ms or
brand flash >500ms or first keystroke rejected. Print a timing table.
2. **Cold-start variant**: with the sidecar port BLOCKED (bad base URL env or
route-abort), assert cached paint still renders content + typing queues (needs
Lane H+C landed — the script probes, and reports which contracts hold; exits
1 only on regressions of landed contracts, with a --strict flag for full
enforcement once H+C merge).
## VERIFY STAGE (adversarial, after lanes)
- V1-instant: run `node scripts/ux-gates/warm-interaction-gate.mjs` against the dev
server (servers: vite 8080; sidecar recipe in the handoff) — report the ACTUAL
timing table; kill the sidecar and run the cold variant; try to refute Lane H/C
claims (type during warmup, click during skeletons, tab-away/return every cached
surface).
- V2-truth: refute the one-briefing-truth claim — grep for any remaining second
fetch path; run the reconciliation tests; force a count change through the mock
and check for above-fold remount; verify modal-vs-hero counts share one source.
- V3-keyboard: keyboard-only pass — Tab through home → workspaces → kebab →
memory rows → chat send; confirm every action reachable, focus-ring visible
(Phase-A token), no trap; report the actual traversal.
## Orchestrator after verify
tsc web + server, full apps/web vitest, ux-gates all green, browser smoke, commit.
Then: kit v6 build + R20 judge round (gate: min ≥ 8.0 per v3 §3) BEFORE Phase C.

120
docs/ux-refactor/path-exec-phase-C-spec-2026-07-07.md Normal file
View File

@@ -0,0 +1,120 @@
# Path-to-9 execution · PHASE C — the aliveness loop (Pillar 3) + R20 cleanup
### Contract: docs/ux-refactor/path-to-9-2026-07-07.md v3 §Pillar 3 (5/5 endorsed) + R20
### convergent residuals. R20 = min 7.6 avg 7.78; the #1 gap (4/5 HIGH) is streaming cadence.
### All new motion uses lib/motion/tokens.ts. Both themes. Reduced-motion per REDUCED map.
### Per-lane gate: related vitest green + eslint 0 errors + text-color-guard clean on touched files.
## Lane S1 — streaming cadence + honey caret (Pillar 3.1; THE headline, 4/5 HIGH)
Files: NEW `hooks/useStreamCadence.ts` (+ test), `components/os/apps/chat-blocks/TextBlock.tsx`,
`hooks/useChat.ts` (feed the cadence buffer only — do not change the SSE path), tests.
Root cause (verified): the SSE delivers chunks; TextBlock re-renders whole markdown per
chunk → judges read "line/chunk reveal" not "per-token fade." Fix = a render-side cadence
buffer (the v3-sanctioned option: "smooth chunks into a steady visible rhythm with ZERO
added latency to first token").
1. **useStreamCadence(rawText, isStreaming)** → `{ shown, caretVisible }`: keeps a target
string (the accumulated raw stream) and a `shown` length that advances on rAF toward
the target at a cadence that SCALES with backlog (reveal ~ max(minCharsPerFrame,
ceil(backlog / catchupFrames))) so it NEVER lags more than a small window and drains
fully within ~1 frame of stream end. FIRST characters reveal immediately (no buffering
delay before first paint). When !isStreaming, snap `shown` to full. Guard: rawText only
grows during a stream (never reveal past target; handle target shrink on reset).
2. **TextBlock consumes it**: render `renderChatMarkdown(shown)` (the smoothed prefix) with
a trailing honey caret (`--honey-text`, a soft blink via a token'd keyframe — NOT
animate-pulse; ~1s) at the reveal head. Reduced-motion: snap to full text, static caret
(REDUCED.streamingCaret). The existing capability-segment logic + markdown escaping stay.
3. **Hard-case markdown forms without popping** (v3 competitor acceptance): a code block +
a list must render progressively as the smoothed text crosses their boundaries — no
whole-block pop. renderChatMarkdown already escapes+emits; verify partial markdown
(unterminated ``` / partial list) degrades gracefully (renders as forming text, not raw
noise). Add a test with a chunked code-block+list input asserting monotonic reveal.
4. Zero added latency: unit-test that the first chunk's first chars are shown within one
rAF, and total reveal completes ≤1 frame after the last chunk.
## Lane S2 — streaming interaction contract (Pillar 3.1 cont'd; v3 competitor blocking)
Files: `components/os/apps/ChatApp.tsx` (scroll container + stop control), the chat scroll
hook if one exists (grep), tests.
1. **Auto-follow scroll that breaks INSTANTLY on user scroll** (input-primacy applied to
the stream): while streaming, keep the viewport pinned to the newest content; the moment
the user scrolls up, STOP auto-following and show a "Jump to latest ↓" affordance
(honey pill, bottom-right of the thread); clicking it re-pins. Re-pin automatically when
the user scrolls back to the bottom.
2. **Visible stop control**: a Stop button (replaces/augments send while streaming) that
halts output immediately mid-stream (wire to the existing SSE cancel — grep useChat for
the abort/cancel path; Lane C added streaming-by-id). The partial answer stays; the
composer returns to send.
3. Tests: auto-follow pins during stream; a simulated user scroll-up sets not-following +
shows the jump affordance; stop calls the cancel path and re-enables send.
## Lane AL — surprise-recall bloom · investment celebration · first-60s wow · home ambient
Files: `components/os/apps/chat-blocks/StepBlock.tsx` or the Auto-Recall chip component
(grep "Auto Recall"/recall chip), `apps/HomeCockpit.tsx` (briefing accrual line + ambient),
`overlays/onboarding/*` (first-task wiring — verify), NEW `components/os/warm/AmbientHiveGlow.tsx`
(+ test), tests.
1. **Surprise-recall bloom** (Pillar 3.2, rubric dim-6 — the product's unique dopamine):
when the Auto-Recall chip appears mid-chat (memory pulled into context), it blooms
honey for ~600ms (SPRING.micro scale + a honey glow that fades), drawing the eye to the
"it remembered" moment. Reduced-motion: instant, no bloom.
2. **Investment celebration** (Pillar 3.3): the home briefing states what ACCRUED since
last visit ("12 new memories · 2 decisions since Tuesday") sourced from real data
(briefing-source counts — honesty gate: bind to the exact number, no estimate). The
Phase-B DeltaNumber pulse already exists — reuse it on the accrual figure. If the
accrual delta isn't available from the current briefing payload, render nothing (never
fabricate) and note the data gap.
3. **First-60s wow** (Pillar 3.4): verify the first chat message after onboarding
demonstrably uses the just-entered profile ("As a consultant, you'll want…"). If the
wiring exists, ensure it's visible; if not, a minimal profile-aware opener. Verify the
onboarding→first-task handoff in code before adding anything.
4. **Home ambient hive life** (brand HIGH — AmbientHiveGlow.tsx): a slow honey radial
"breath" (very low amplitude opacity/scale, ~6s cycle) + optional faint hex-cell
shimmer behind the home hero zone, BELOW attention threshold (must not compete with
content — brand's "respectful, no gratuitous movement" WIN must survive). Reduced-motion:
static (REDUCED.ambient → off). Gate the whole thing behind a prop so it's home-only.
## Lane CL — R20 cleanup (verified residuals; several are a11y-HIGH double-yield)
Files: `os/BootScreen.tsx` (reduced-motion glow), `os/apps/AllWorkspacesApp.tsx` +
`apps/memory/MemoryTrustManage.tsx` (card/row overflow keyboard reach), the SectionLabel/
eyebrow usages flagged, the capture kit seed (scratchpad — orchestrator owns), tests.
1. **Reduced-motion boot glow freeze** (s11, 2 judges): the boot radial "breath" ramp must
be static under prefers-reduced-motion — audit BootScreen for any remaining ungated
glow (the logo loop was gated in A2; this is the background radial `bg-primary/5 blur`
if animated, + the progress area). Zero lingering animation under reduce.
2. **Card/row overflow ('…') keyboard reachability** (a11y+design HIGH): the workspace-card
kebab and memory-row actions must be reachable by Tab with a visible --focus-ring on the
ACTION itself (roving tabindex if they're in a menu; focus-visible reveal if hover-gated).
The s10 acceptance ("reach card actions without a mouse") must be provable — add a
keyboard test that tabs to a card, opens its menu via keyboard, and reaches Delete.
3. **Tertiary-text stragglers** (a11y): the eyebrow labels the runtime pass / judges still
flag (RESEARCH HUB, START HERE card eyebrows, onboarding subhead + on-device footnote)
→ --text-tertiary (verify each is a real sub-AA case with computed ratio; the SectionLabel
primitive was raised in Phase A — these may be one-off usages not on the primitive).
4. **Light-theme focus-ring visibility** (a11y): confirm --focus-ring reads on cream —
contrast-tokens already proves ≥4.03:1; add ONE light-theme focus-ring assertion to the
keyboard test or a spot check, and note the result (all R20 confirmed rings were dark).
5. Dense-surface rhythm (medium, if time): marketplace results + models grid + memories
list row vertical rhythm one step looser toward hero-surface craft. Scope-guard: only
spacing, no structural change; if it risks the busy lanes, defer with a note.
## Kit v7 (orchestrator, not a lane)
- Capture seed: add `waggle-booted: 'true'` + `waggle_onboarding_complete: 'true'` +
`waggle:login-briefing-dismissed: 'true'` to the returning-user addInitScript so s01
models the REAL returning user (boot skipped, cache-first ~459ms) — the R20 "2s boot
wall" was this seed gap (product truth is boot-skipped; gate-verified). KEEP one
first-launch boot showcase (s09 onboarding already covers first-run warmth; optionally a
dedicated s12_first_launch to preserve the praised boot choreography as its own journey).
- s04 stream window stays 12fps (judge the new per-char cadence there).
## VERIFY STAGE (adversarial, after lanes)
- **V1-streaming**: from the 12fps s04 stream window + code read — does the reveal read
per-character/word (not chunk)? Is the honey caret present + reduced-motion static? Does
a code-block+list form without popping (inspect useStreamCadence + a hard-case test)?
Does autoscroll break on user scroll + jump-to-latest appear + stop halt immediately?
- **V2-aliveness**: recall bloom fires on the Auto-Recall chip (reduced-motion instant);
briefing accrual binds to a real number (no fabrication); ambient glow is below
attention threshold + reduced-motion static; first-60s wiring verified.
- **V3-keyboard**: re-run the s10 acceptance — tab to a workspace card, open its overflow
menu by keyboard, reach Delete with a visible focus ring; confirm light-theme ring.
## Orchestrator after verify
tsc web + full apps/web vitest + all gates (contrast-tokens/text-color-guard/warm-gate) +
the runtime pass on /home,/settings both themes → commit → kit-v7 capture → R21 judge
(gate: min ≥ 8.5 per v3 §3 after Pillar 3) → Phase D (Pillar 1 motion system).

113
docs/ux-refactor/path-exec-phase-D-spec-2026-07-07.md Normal file
View File

@@ -0,0 +1,113 @@
# Path-to-9 execution · PHASE D — the motion system (Pillar 1) + home scroll-reveal
### Contract: docs/ux-refactor/path-to-9-2026-07-07.md v3 §Pillar 1 (5/5 endorsed, incl. the
### PATH-2 conditions: default route tier + hero morphs, focus/AT spec IN the component,
### interruptibility as acceptance criteria, commissioned waggle-settle prototype-first).
### The unanimous R19 #1 gap. Highest regression risk → scoped, feature-flagged, staged.
### All motion uses lib/motion/tokens.ts. Both themes. Reduced-motion per REDUCED map.
Recon (verified): router = react-router `<Routes>` in App.tsx; the layout route `/`
= AppShell whose single `<Outlet/>` (AppShell.tsx:449) renders the active route inside
`<main class="relative z-10 flex-1 overflow-hidden">`. `location`, `useNavigate`,
`AnimatePresence` already imported. ChatHost keep-alive portal is SEPARATE from the
Outlet (must not be wrapped — it protects in-flight SSE). Phase-0 spring family +
`--mo-*` tokens + REDUCED map exist. Hover tier = the shipped `hive-interactive`-style
classes on cards (Wave T/U/V). AmbientHiveGlow shipped Phase C (home breath).
## STAGE 1 (parallel; the two heavy motion lanes are independent)
### Lane RT — route-transition system (Pillar 1.1; PATH-2 design blocking)
Files: NEW `components/os/RouteTransition.tsx` (+ test), `components/os/AppShell.tsx`
(wrap the Outlet only), `lib/feature-flags.ts` or a local flag (verify the flag pattern),
tests.
1. **DEFAULT tier — fade-through crossfade + persistent chrome** on ALL top-level route
changes: wrap `<Outlet/>` in `<AnimatePresence mode="popLayout">` keyed by a ROUTE-GROUP
key (NOT the full pathname — a workspace tab change within /workspaces/:id must not
crossfade the whole surface; derive the key from the top segment: home/workspaces/
memory/agents/marketplace/settings/…). Enter/exit = opacity fade-through (150–200ms,
`--mo-base` + `EASE_OUT`); the sidebar + StatusBar are OUTSIDE the animated subtree
(persistent chrome — they never fade). NOT a global router rewrite.
2. **Interruptibility + input-primacy** (PATH-2 design blocking — ACCEPTANCE, tested):
a route change mid-transition redirects immediately (AnimatePresence popLayout allows
the new child in without waiting for exit); navigation/input NEVER waits on an exit
animation. Add a test: fire two navigations in quick succession → the final route wins,
no lock. Keep `mode="popLayout"` (not "wait") precisely so exits don't block enters.
3. **Focus + assistive-tech spec IN the component** (PATH-2 a11y blocking): on route
commit, move focus to the destination surface's primary heading / `<main>` landmark
(focus a `tabIndex={-1}` ref); set the EXITING subtree `inert`+`aria-hidden` for its
exit duration (focus/SR cursor can never land in it); announce the route via a polite
live region (route label). Ship these INSIDE RouteTransition, not as a follow-up.
4. **Reduced-motion**: crossfade → instant swap (REDUCED.routeTransition = 'crossfade-only'
means: under reduce, no opacity animation — instant), focus + announce still fire.
5. **Feature-flag** the whole thing (default ON in dev, but a kill switch) so a regression
is one flag flip. Verify the ChatHost keep-alive still works (SSE survives a route
change — do not wrap ChatHost).
### Lane HM — hero shared-element morphs (Pillar 1.1 hero cases)
Files: `apps/AllWorkspacesApp.tsx` + the workspace route/surface (`layoutId` on the card→
surface), `apps/memory/*` (Trust↔Memories tab morph), tests. Depends on Lane RT's
RouteTransition existing (Stage 1 both start; HM reads RT's exports — if RT isn't merged
yet, HM implements the layoutId pairs and notes the integration point).
1. **card→workspace-open**: the workspace card's hex avatar + name share a `layoutId` with
the destination workspace header, so opening a card GROWS it into the surface (framer
`layoutId` + `LayoutGroup`). Scope to this ONE pair; fall back to the default crossfade
if the destination header isn't mounted.
2. **Trust↔Memories tab morph**: the shared hero/container morphs between the two memory
tabs (layout animation on the tab panel), not a hard cut.
3. Interruptibility + reduced-motion (instant) as Lane RT item 2/4. Both morphs motion-safe.
## STAGE 2 (parallel; after Stage 1)
### Lane HV — hover amplitude: "honey responds to touch" (Pillar 1.2; brand HIGH ×3 rounds)
Files: the shared hover-tier class/util (grep where cards define hover — likely inline
Tailwind on AllWorkspacesApp/SuggestedAgentCards/ExtensionCard; if there's a shared
`hive-interactive` class in index.css, edit there; else create ONE and adopt), tests.
1. Bump the hover tier amplitude to a felt "honey blooms under the cursor": on hover/
focus-visible → lift (translate-y 2→4px), shadow step, honey border-warm, AND a soft
honey glow bloom (box-shadow with `--shadow-honey`/`--honey-glow`), 120–160ms
`--mo-fast` + spring feel. ONE implementation adopted by workspace cards, agent cards,
marketplace rows, provider tiles. Reduced-motion: keep color/shadow, drop translate.
2. Keep the brand judge's WIN ("respectful, not gratuitous") — bloom is subtle, not neon.
Light theme: verify the glow reads on ivory (Phase-A light --honey-glow / deeper honey).
### Lane SR — home day-story scroll-reveal (Pillar 1.1 entrance; R20 design HIGH)
Files: `apps/HomeCockpit.tsx` (+ the home section components), tests.
1. The home "day story" (I REMEMBER → START HERE → memory-review → WHILE YOU SLEPT →
pick-up cards) reveals on scroll: each section rises 8px + fades in as it enters the
viewport (IntersectionObserver + the `card-enter` / STAGGER grammar), once per section
per visit. So the scripted scroll reads as designed motion, not a static page.
Reduced-motion: all visible immediately, no rise/fade. Do not re-trigger on scroll-up.
## STAGE 3 (the signature gesture — prototype-first, PATH-2 brand blocking)
### Lane WS — the waggle-settle, commissioned + prototyped STANDALONE
Files: NEW `components/os/warm/WaggleSettle.tsx` (+ test) + a `/motion-spec` section
demonstrating it on exactly ONE moment (memory saved). Do NOT propagate to other moments
in this phase — the prototype is judged first (a mini standalone review), THEN rolled out
per the Phase-0 SIGNATURE frequency taxonomy in a later step.
1. A recognizably waggle-derived micro-choreography: a brief directional waggle-run
(the bee's figure-eight dance DNA — a small side-to-side + forward settle) → settle,
~300–400ms (DUR.settle, SPRING.expressive), honey. Reduced-motion: instant state +
color pulse (no path motion). It must read as "the waggle," not a generic scale-pop.
2. Wire it to ONE moment only: the memory-saved confirmation (find the save-memory
success path — grep). Render it there behind the SIGNATURE.full taxonomy gate
(per-session cooldown). Everything else waits for the standalone judge verdict.
## VERIFY STAGE (adversarial)
- **V1-motion-system**: RouteTransition — is the crossfade interruptible (the double-nav
test), is the focus/AT spec implemented (focus moves to heading, exiting tree inert,
route announced), does reduced-motion degrade to instant, does ChatHost SSE survive a
route change? Hero morphs — do the layoutId pairs animate (code-read + the 12fps
capture if available)?
- **V2-hover-scroll**: hover amplitude felt (inspect the class), light-theme glow reads,
reduced-motion drops translate; scroll-reveal fires once per section, reduced-motion off.
- **V3-a11y-regression**: the highest risk — a keyboard-only pass through 3 route changes
(focus lands on the destination heading each time, no focus trapped in an exiting tree,
route announced); reduced-motion Playwright pass asserting no route-transition opacity
animation under reduce.
## Orchestrator after verify
tsc web + full vitest + all ux-gates (contrast/text-guard/warm/runtime) + reduced-motion
gate + browser smoke (route changes crossfade, one card→workspace morph, hover bloom) →
commit → **standalone waggle-settle mini-judge** (is it "the waggle"? kitsch check) →
if approved, roll out per taxonomy → kit-v7 capture → **R22 judge (9-ATTEMPT: min ≥ 9.0)**.
If R22 min < 9 but ≥ 8.5, one convergent-fix round; if it plateaus, stop + re-analyze.

278
docs/ux-refactor/path-to-9-2026-07-07.md Normal file
View File

@@ -0,0 +1,278 @@
# Path to 9 — premium feel, power usability, habit formation
### The definitive analysis (2026-07-07, v3 FINAL) · goal: 5 persona judges ≥ 9/10 · founder framing: "premium UX + power feeling → addiction"
### PATH-2 panel: **5/5 ENDORSED** (predicted-if-executed 8.7–9.0). v3 integrates their 7 endorsement conditions. This is the agreed, executable path.
## 0. Standing and method
Evidence base: **7 video-judged rounds (R13–R19), 209 recorded fixes (88 HIGH), 10 shipped
waves (P–X, merged to main `8ee7ac82`)**, plus the 2026-05-28 addictiveness audit
(Hook-Model rubric, 7 iterations, 5.0 → 7.7). Scores: video regime avg 7.08 → 7.70
(Fable ruler), min pinned at 7.5 for three rounds. Two measured plateaus prove the
polish-wave engine is exhausted: per-round EV ≈ +0.02, and every remaining HIGH ask is
either structural or systemic — not surgical.
**The panel's own definition of the gap** (R19, 5/5 unanimous, verbatim): *"The product
has the VISUAL craft of a 9 … but the MOTION identity of a ~7. Gap to 9 is not more
features or more surfaces — it's a genuine motion system."* Secondary unanimous asks:
a shown, signature streaming moment; killing the boot interstitial; a systemic AA floor.
What a 9 means per lens (extracted from all 7 rounds' verdicts):
| Judge | Their 9 requires | Their current ceiling-setter |
|---|---|---|
| design-director | spatial continuity, spring physics, choreographed transitions, multi-tier hover | "surfaces cut/fade instead of transforming" |
| knowledge-worker | instant feel (no boot tax, no staged arrival), interactions that telegraph | "make it feel instant"; boot + skeleton dwell on every route |
| competitor-critic | streaming rhythm at Claude/ChatGPT level + a motion language they lack | "the exact axis the video regime exposes: pure motion signature" |
| a11y-theme-parity | systemic AA tertiary tier + keyboard-first hover-reveals + hit areas | "systemic dim secondary text… weighs heaviest" (THE min-score gate) |
| brand-resonance | the hive alive on WORKING surfaces: honey responds to touch, streaming heartbeat, ambient life | "the brand goes quiet on the working surfaces" |
## 1. Why the founder's "addiction" framing and the judges' "motion system" converge
The Hook Model (trigger → action → variable reward → investment) says habit forms when
each loop is *felt*. The judged deficits map directly onto the loop's felt moments:
- **Action feel** = the power feeling. Instant boot, sub-100ms responses to the cursor,
keyboard-first paths — Fogg's "ability" term. Today's boot tax + single-tier hovers
make every loop pay a toll; a power user's loop must feel FREE.
- **Variable reward** = the visible aliveness. Streaming heartbeat, surprise-recall
("I REMEMBER" cards), honey blooming under the cursor — the dopamine surface. Judges
keep scoring exactly these as the missing "signature moments."
- **Investment made visible** = memory counters, growth, compounding identity — the
product already OWNS this (Memory Trust 8.2, "category-defining"); it needs the loop
to *celebrate* accrual (count-ups, growth deltas in the briefing) rather than list it.
- **Triggers** are mostly outside the judged surface (digests, notifications) — real for
retention, invisible to this panel. They ride the roadmap but not the score.
So: **the same three workstreams that raise the judged score to 9 are the ones that
manufacture the addiction loop.** There is no tension between the founder ask and the
panel's path.
## 2. The path — four pillars + a phase-0 vocabulary, sequenced
### PHASE 0 · THE MOTION VOCABULARY (prerequisite; ships FIRST with Pillar 4) — [PATH-1: design blocking #2]
Before ANY new motion ships (including Pillar 3's aliveness moments):
1. **One spring FAMILY, not one config** — 2–3 named variants (`micro` / `standard` /
`expressive`) sharing a single physical character, tuned once, exported as motion
tokens. Kills the mixed CSS-ease/duration zoo. [design non-blocking, adopted]
2. **A motion-spec reference page** — an internal demo surface where every tier (spring
family, hover tiers, settle gesture, route transitions, reduced-motion mappings) is
demonstrable and reviewable. The arc's single source of motion truth. [design gap]
3. **Reduced-motion mapping defined for EVERY tier** (not just ambient): route
transitions degrade to crossfade; hover keeps color/shadow, drops translate;
settle gesture → instant state + color pulse; streaming caret → static cursor;
count-ups → instant set. [design gap + a11y]
4. **Interruptibility + input-primacy as ACCEPTANCE CRITERIA** [design blocking #1]:
every transition is interruptible and redirectable mid-flight; navigation and input
NEVER wait on an exit animation or transition completion. The motion system must
never fight the instant-feel pillar — this is a per-PR checklist item, not an
aspiration.
5. **Exit choreography in the same vocabulary**: AnimatePresence exit definitions for
cards, menus, modals, and route surfaces. [design non-blocking, adopted]
6. **RETROFIT of already-shipped motion** [PATH-2 design]: inventory every prior
motion pass (Wave T/U hover tiers, Wave V lift+bloom + theme crossfade, Wave W
entrance stagger, onboarding/streaming breathing) on the motion-spec page, then
migrate each onto the Phase-0 tokens and spring family. Acceptance: ZERO
non-token durations/easings on judged surfaces — one motion dialect, not two.
7. **Signature-moment frequency/intensity taxonomy** [brand blocking #2 + design/kw
non-blocking — 3 judges independently]:
- FULL settle (300–400ms): rare accrual milestones ONLY — memory saved (first per
session), install success, agent spawned.
- MICRO variant (≤150ms, same gesture DNA): high-frequency actions — send-arm,
selection.
- Per-session cooldowns on full-amplitude moments; routine actions never flourish.
### Pillar 1 · THE MOTION SYSTEM (structural; the unanimous #1; est. +0.6–0.9 panel-wide)
A dedicated engineering arc, NOT lanes. Builds ON the Phase-0 vocabulary.
1. **Spatial continuity — a base tier everywhere + two heroes** [PATH-2 design]:
(a) DEFAULT tier: a low-risk fade-through crossfade with persistent chrome
(150–200ms, Phase-0 `standard` spring) on ALL top-level sidebar route changes,
feature-flagged, subject to the Phase-0.4 interruptibility criteria — the
Settings↔Home pair is the template, not a one-off. Two morphs + five hard cuts
would read as three set pieces, not a system.
(b) HERO morphs (the only shared-element cases): card→workspace-open (the card
grows into the surface) and Trust↔Memories tab morph. Implementation:
framer-motion `layoutId` + `AnimatePresence mode="popLayout"` scoped to these
two (NOT a global router rewrite — that's the regression trap).
**Focus + assistive-tech spec ships INSIDE the transition component** [a11y
blocking #1]: on every shared-element route change, focus moves to the destination
surface's primary heading/main landmark; exiting AnimatePresence trees are set
`inert`/`aria-hidden` for their exit duration (focus and the SR virtual cursor can
never land in them); route changes are announced (document.title update + a polite
live region).
2. **Multi-tier hover — "honey responds to touch"**: rest → hover (120–160ms: lift
2-4px + shadow + honey border-warm + glow bloom) → press (scale .98) →
focus-visible (same tier, keyboard). ONE implementation (a `hive-interactive`
variant), adopted by cards, rows, chips, tiles. Can ship early (additive).
3. **The signature gesture — commissioned as a DESIGNED MOTION ASSET** [brand
blocking #1]: a recognizably waggle-derived micro-choreography (brief directional
waggle-run → settle, from the bee's actual figure-eight dance), prototyped and
judged STANDALONE on exactly one moment (memory saved) BEFORE any propagation.
Only after the panel scores the prototype does it roll out per the Phase-0
frequency taxonomy. Highest-upside, highest-kitsch-risk line in the path —
treated accordingly.
4. **Ambient hive life**: the breathing glow (already shipped on onboarding, judged
"the one unambiguously signature motion") recurs as idle ambient on Home hex-glow
and empty states. Amplitude discipline: ambient means BELOW attention threshold.
5. **Light-theme variants for every glow/bloom signature** [brand]: deeper honey,
tighter radius on ivory — the signatures must not vanish (or smear) in light.
Kit v6 captures each signature moment in BOTH themes.
6. **P1/P2 seam**: cache-first warm paint lands with one subtle designed micro-settle
rather than a raw instant pop. [design non-blocking, adopted]
### Pillar 2 · THE INSTANT POWER FEEL (perceived performance; est. +0.3–0.5, biggest for kw/competitor)
1. **Kill the returning-user boot tax**: warm sessions land on content <1s (brand
flash ≤500ms). Cache-first paint: the Home payload cache is **disk-persisted and
renders BEFORE the sidecar answers** — the day-30 morning desktop launch is the
moment that matters, not just SPA revisits. [kw gap, adopted]
2. **The input-during-warmup CONTRACT** [PATH-2 kw]: cache-first paint must be
INTERACTIVE, not just visible — (a) the composer accepts typing at paint; queued
sends dispatch when the sidecar is ready (never error, never silently drop);
(b) first click on any cached card either acts or shows a truthful per-element
pending state — never a dead click. The §3 hard gate measures time-to-first-
INTERACTION, not just time-to-content, and kit v6 records a cold-start variant
(sidecar down → app start → cached paint → first send).
3. **The silent-refresh reconciliation CONTRACT** [kw blocking]: when fresh data lands
over a cache-first paint — (a) NO above-the-fold layout shift; (b) material deltas
animate in via the Pillar 3.3 delta pulse instead of silently replacing content;
(c) the briefing modal (reserved for ≥7-day absences — N=7, decided) renders from
the SAME data source/component as the home hero cards, killing the number-drift
bug class permanently. Wrong-then-corrected is worse than slow; the contract is a
test, not a guideline.
4. **Collapse the double catch-up**: the "I REMEMBER" cards land INSIDE the home hero
as the first staggered entrance; the modal fires only on ≥7-day absences (same
component, same data — see 2.2).
5. **The send-path budget** [kw gap, adopted]: the single most repeated daily action
(send → first token) gets an explicit instant contract — optimistic user-bubble
echo, composer never locks on send, first-token latency never increased by any
visual layer.
6. **Route-cache everything judged**: chat thread, marketplace, agents join memory/
workspaces — tab returns instant, no re-skeleton. Marketplace's first-match wait
keeps its purpose-built skeletons (banked residual, R17). [kw]
7. **Keyboard-power layer**: focus-visible parity on every hover-reveal (kebab +
memory rows remain), ~40px hit areas, a ≤2-keystroke path from anywhere to
new-chat / last-workspace, and a discoverable shortcut cheat sheet (`?` / Cmd-/).
[kw non-blocking, adopted] Double yield: this is also the a11y judge's #2 ask.
### Pillar 3 · THE ALIVENESS LOOP (variable reward made visible; est. +0.3–0.5, brand/competitor)
1. **Streaming as a PIPELINE deliverable, then a visual one** [competitor blocking #1]:
first resolve the dev echo-provider's whole-block behavior — emit true token/chunk
streaming in the judged environment, or add a render-side cadence buffer that
smooths chunks into a steady visible rhythm with ZERO added latency to first token.
Acceptance: recorded s04 shows continuous sub-line accretion — no multi-second
block pops, no layout jank as markdown forms. THEN the branded layer: the
**streaming text caret** — a honey glow trailing the accreting text head (this is
what "bee-trail cursor" means; it is NEVER a pointer-following trail [brand
blocking #3]) + a subtle thinking pulse on the bee avatar during tool-trace.
Reduced-motion: static caret, no pulse. The caret never occludes text or targets.
[a11y] **Streaming INTERACTION contract** [PATH-2 competitor]: auto-follow scroll
breaks INSTANTLY on user scroll (input-primacy applied to the stream) with a
"jump to latest" affordance; a visible stop control halts output immediately;
the recorded s04 acceptance prompt forces hard-case progressive rendering (a
code block + a list/table) — markdown formation tested where Claude's streaming
craft is strongest.
2. **Surprise-recall as a first-class moment**: when Auto Recall lands mid-chat, the
memory chip blooms honey for ~600ms ("reward of the hunt", rubric dim 6 — the
product's unique dopamine no competitor can copy).
3. **Investment celebration with an HONESTY GATE** [brand non-blocking, adopted]:
count-ups and "+" delta pulses bind to the exact source-of-truth number — the
settled value is never floored, clamped, or estimated (regression-tested); animation
intermediates must never contradict a visible sub-stat (the Wave X lesson,
generalized). Briefing states what ACCRUED since last visit ("12 new memories ·
2 decisions"). Accessible treatment: one polite live announcement of the settled
number, never intermediate frames. [a11y]
4. **First-60s wow** (rubric dim 3): wire the first chat message to demonstrably use
the just-typed profile ("As a consultant, you'll want…") — the "it already knows
me" hook.
### Pillar 4 · THE AA FLOOR (systemic; unblocks the min-score judge; est. min 7.5→8+)
1. **Token-level tier**: define a `--text-tertiary` tier that is AA on EVERY surface
token (bg/bg-2/surface/surface-2) in BOTH themes; migrate the ~dozen recurring
offender families (top utility bar, timestamps, card meta, onboarding subtitle/
footnote, unselected chips).
2. **Close the GENERATION vector, not just today's instances** [a11y blocking #2]:
(a) a lint/CI guard banning new non-token text colors (raw hex, palette classes,
arbitrary values) on app surfaces; (b) contrast verification that models
COMPOSITION — opacity-modified text and text over wallpaper/gradient/wash measured
against effective background (a runtime axe-style pass on the judged surfaces).
Token-pair math alone buys one clean round; this buys a floor.
3. **The AFFORDANCE floor** [PATH-2 a11y]: non-text contrast (WCAG 1.4.11, ≥3:1
against adjacent effective background, both themes) for focus indicators,
input/chip borders, and state glyphs — a `--focus-ring`/border tier alongside
`--text-tertiary`, asserted in the same CI runtime pass. Explicit acceptance:
Pillar 1.2's focus-visible tier passes 3:1 in LIGHT (honey-on-ivory), MEASURED.
4. Hit-area and focus-visible items fold into Pillar 2.7 (double-yield, one
implementation).
## 3. Sequencing, risk, verification
**Order: Phase-0 + Pillar 4 (parallel, both token-level, zero-regression) → Pillar 2 →
Pillar 3 → Pillar 1** — with Pillar 1.2 (hover grammar) allowed early as additive.
Amended from v1: the motion vocabulary now PRECEDES all aliveness work. [design blocking #2]
**Competitive teardown at arc start** [competitor non-blocking, adopted]: record the
equivalent journeys on current Claude and ChatGPT (spot-check Hermes/Odyssey); extract
concrete numeric targets — warm time-to-content, visible token rhythm, transition/hover
timings. "At Claude/ChatGPT level" becomes measured, not remembered.
Risks: route transitions carry regression risk (scoped routes, feature-flag, the
Phase-0.4 interruptibility criteria, the P1.1 focus/AT spec); streaming choreography
must never delay tokens (P2.4 budget); ambient motion must never read as busy (brand:
"respectful, no gratuitous movement" is currently a WIN — don't lose it).
**Verification — kit v6** [design blocking #3 + competitor blocking #2 + a11y blocking #3]:
- Judges pinned `model:'fable'` (ruler stability; the R19 lesson).
- **Per-journey sampling matched to the deliverable, disclosed in the judge brief**:
transition/signature/streaming journeys delivered as ≥12fps micro-filmstrips or
short native-framerate clips (spring character, token cadence, and settle
choreography are invisible at 2–4fps — the arc's history proves measurement
failures eat rounds); 2fps contact sheets remain for static-composition journeys.
- **A keyboard-only journey**, recorded and judged like the mouse journeys: tab-through
home → open workspace → chat send → message actions via focus → memory row actions →
settings, visible focus indicators expected in every frame.
- **Warm time-to-first-INTERACTION as a HARD gate**: Playwright-measured, fails the
round if >1000ms to interactive content / >500ms brand flash. [kw, PATH-2]
- **Reduced-motion ENFORCEMENT** [PATH-2 a11y]: an automated Playwright pass with
`prefers-reduced-motion: reduce` emulated, asserting the Phase-0.3 mappings per
tier (route transitions crossfade-only; no transform animation on hover; settle →
instant state; static streaming caret; count-ups set instantly), run per round like
the contrast and warm-boot gates — plus one recorded reduced-motion spot-journey.
- New journeys: send→stream→settle (shipped v5), card→workspace-open transition,
tab-morph, warm-boot timing, cold-start-to-first-send, keyboard-only,
reduced-motion spot, waggle-settle prototype (standalone, both themes).
- **Side-by-side clips vs current Claude and ChatGPT** [PATH-2 competitor]: streaming
+ warm-launch journeys at minimum, from the arc-start teardown footage, refreshed
at the 9-attempt round and delivered in the judge brief — parity/beat claims judged
from paired evidence, not memory.
Success gates per round: min-of-5 ≥ 8.0 after Phase-0+P4+P2; ≥ 8.5 after P3; 9 attempt
after P1. If two consecutive rounds plateau below gate → stop, re-analyze (the
discipline that caught both prior plateaus).
## 4. What we deliberately do NOT do
- No more polish waves against the old ask lists (measured EV ≈ 0).
- No gamification-shaped addiction (streaks, badges, FOMO mechanics) — the panel would
score it as noise and it contradicts the trust-first brand voice that earns the 8.2s.
Addiction here = the loop feeling so good it self-reinforces, not manipulation.
- No global router rewrite; no motion on the working thread that competes with content;
no pointer-following effects of any kind.
- No unreviewed propagation of the signature gesture: prototype → panel → rollout.
## 5. Panel disposition — AGREED (goal met)
- **PATH-2** (v2): **5/5 ENDORSE** — design 8.8 (high) · kw 9.0 (medium) · competitor
8.8 (high) · a11y 8.7 (high) · brand 9.0 (medium). Seven endorsement conditions →
integrated in THIS v3: default route-transition tier + retrofit deliverable
(design); input-during-warmup contract + first-interaction gate (kw); streaming
interaction contract + side-by-side evidence (competitor); affordance floor +
reduced-motion enforcement (a11y). **The panel agrees on the path — v3 is the
executable contract for the arc.**
### PATH-1 disposition (for the record)
v1 review: design 8.7 endorse · kw 8.7 endorse · competitor 8.5 endorse · brand 9.0
endorse · a11y 8.3 WITHHELD. All 12 blocking amendments integrated above (Phase-0;
interruptibility; resequencing; silent-refresh contract; streaming pipeline rescope;
high-framerate verification; focus/AT spec; generation-vector CI; keyboard journey;
commissioned gesture; frequency taxonomy; caret disambiguation) plus 9 high-consensus
non-blocking adoptions (spring family, motion-spec page, reduced-motion per tier, exit
choreography, P1/P2 seam, send-path budget, disk-persisted cache, honesty gate,
competitive teardown, light-theme signatures, shortcut cheat sheet).

65
docs/ux-refactor/solo-team-migration-spec-2026-07-05.md Normal file
View File

@@ -0,0 +1,65 @@
# Solo-vs-Team Migration — Ratified Spec (2026-07-05)
Founder call: **collapse the funnel to Solo (free) vs Team (paid).** Kill PRO. Full clean.
Scout change-list: session tool-result `bhgz24e6c.txt` (6 areas, ~170 changes). This doc is
the ratified decision layer on top of it.
## Model
- **FREE tier value stays `FREE`** (no stored-value migration), **displays as "Solo"** via a
new `TIER_LABELS` map. `TIERS = ['TRIAL','FREE','TEAMS','ENTERPRISE']` (PRO removed).
- **PRO removed** from `TIERS` + `TIER_CAPABILITIES`. `parseTier('PRO')`/`'basic'` → `'FREE'`
(LEGACY_TIER_MAP: `basic:'FREE'`, add `pro:'FREE'`). Never null, never lock out a legacy sub.
- **FREE raised to old-PRO capability** (6 fields): `connectorLimit 5→-1`, `workspaceLimit 5→-1`,
`embeddingProviders +voyage,+openai` (NOT litellm), `customSkills false→true`,
`exportFormats +pdf,+json`, `auditLog none→basic`. **All TEAMS-only deltas stay off FREE**
(teamSkillLibrary, cloudSync, sharedWorkspaces, adminPanel, selfHosted, managedModelPool,
priorityModels, teamMembersLimit:1, auditLog stays `basic` not `full`, stripePriceId:null).
- **TEAMS unchanged** (paid $49/seat, keeps all collaboration/governance). **ENTERPRISE/KVARK**
unchanged. **TRIAL** = 15-day Team preview → falls back to Solo.
- New in `tiers.ts`: `TIER_LABELS: Record<Tier,string> = {TRIAL:'Trial', FREE:'Solo', TEAMS:'Team',
ENTERPRISE:'Enterprise'}` + `tierLabel(t)` helper (single source of truth for display names).
## Ratified sub-decisions (all "clean" defaults)
| # | Decision | Ruling |
|---|---|---|
| 1 | Personal-feature server gates: marketplace install **and** publish, mcps install + custom, personas create/generate, install_mcp cmd, connector_fetch cron, skill-audit | **All → free (Solo).** Remove the `requireTier('PRO')` gate (keep `validateBody` on personas). |
| 2 | Stripe **portal** gate | **Ungate to any authenticated user** (`requireTier('FREE')`); rely on the route's own NO_STRIPE_CUSTOMER 400. A legacy PRO sub (now FREE) must still reach the portal to self-cancel. |
| 3 | Solo session cap | **10** (old PRO cap). TEAMS stays 25. Set `tier-session-cap.ts` + `settings.ts:395` identically. |
| 4 | `settings.ts` /api/tier flags | `marketplace: true`, `customModels: true` (Solo gets BYO cloud models/embeddings). Keep kvark/governance at ENTERPRISE, cloud-sync/admin/audit-export at TEAMS. |
| 5 | Legacy PRO Stripe price → tier | `tierFromPriceId` maps legacy PRO/BASIC price IDs → **`'FREE'`** (keep reading the envs; only the return flips). Keep STRIPE_PRICE_PRO* envs (annotate legacy). |
| 6 | New checkout | **TEAMS only.** `checkout.ts` rejects anything but TEAMS. www checkout narrows to `teams`; www **webhook** keeps accepting `pro` for legacy events. |
| 7 | `feature-gates.ts` + `useFeatureGate.ts` | **DELETE both** (F31 root — kills the 'solo'/'business' vocabulary; the mapping reads the onboarding-complexity axis, not billing, so it's unfixable in place). Rewire the 2 consumers: PersonaSwitcher → personas always unlocked (remove lock scaffolding, clean); SettingsApp → canonical `parseTier(billing.tier)` + `tierSatisfies`. |
| 8 | web-only `BillingTier` union PRO slot | **Remove it fully** (clean). Renumber `BILLING_TIER_ORDER`; replace the magic `billingRank >= 3` TEAMS gate in AppShell with a named `>= BILLING_TIER_ORDER.TEAMS`. Coerce inbound `'PRO'` → `'FREE'` in ShellContext so it never reaches the dock. |
| 9 | Cost visibility (`/api/costs`, `/api/cost/by-workspace`) | **TEAMS** (reconcile both to one tier). |
| 10 | Settings 'enterprise' tab | Stays gated at **ENTERPRISE**. |
| 11 | UpgradeModal comparison | Trim FEATURE_ROWS to **Team-differentiating** caps (honest "what Team adds"). "Most popular" highlight → **Team** card. Enterprise stays a separate CTA block (no 3rd PlanCards column). |
| 12 | Marketplace **publish** | **Free (Solo)** — personal marketplace publishing. (The team *skill library* is the TEAMS feature; that's a different mechanism, stays TEAMS.) |
## Execution partition (file-disjoint → parallel-safe)
1. **Foundation** (`packages/shared/src/tiers.ts` only): the model change above + `TIER_LABELS`/
`tierLabel`. Then **`tsc --build packages/shared`** so `dist` carries the new exports (web +
server tsc read shared's `dist/index.d.ts`). MUST land before everything else.
2. **Consumers** (parallel, disjoint dirs): **(a) `packages/server`** — all gates/caps/settings-flags/
stripe/command-registry/cron per decisions 1-6,9. **(b) `apps/web` source** — delete feature-gates+
useFeatureGate, rewire PersonaSwitcher/SettingsApp, reframe all billing UI (PlanCards/UpgradeModal/
TrialExpiredModal/PaymentSuccess/Capabilities/MCPHub/useBilling/adapter/ShellContext/dock-tiers/
AppShell) to Solo/Team + `TIER_LABELS`, decisions 7,8,11,12. **(c) `apps/www`** — Pricing (2-tier),
css grid, messages/en.json, terms, www stripe routes (decision 6).
3. **Tests + docs** (after consumers): update every PRO test assertion (shared/core/server/web/e2e)
to the new contract; CLAUDE.md §1 tier table (drop PRO, Free→Solo, TRIAL→Team-preview, "4-tier"),
§10 M7/E-10 stripe note; `.env.example` legacy annotation.
4. **Verify**: `tsc --noEmit` on **shared + server + apps/web** (all three — build only checks web);
`npm run build:packages`; full `vitest run`; `git status`. Then browser QA.
## Critical gotchas
- **Blast-radius asymmetry**: `npm run build` typechecks only `apps/web`, whose PRO refs are all
loose-string (won't break). The real tsc tripwires are in `packages/shared` (Tier union) and the
tsx-transpiled `packages/server`. **Always run `npx tsc --noEmit -p packages/{shared,server}`.**
- **A missed `requireTier('PRO')` is worse than a wrong one**: with PRO gone from `TIER_ORDER`,
`TIER_ORDER['PRO']` is `undefined` → `n >= undefined` is `false` → **403s every user** (feature
permanently locked). Removing PRO from the union is the deliberate tripwire that surfaces them all.
- **Two semantic reversals** (`FREE.workspaceLimit` and `connectorLimit` 5→-1): their tests encode
the finite value "as the whole point"; rewrite them, and drop the now-wrong 5-workspace nag UI.

79
docs/ux-refactor/ux-audit-2026-07-04-part2.md Normal file
View File

@@ -0,0 +1,79 @@
# UX Audit — Browser Walkthrough 2026-07-04 · Part 2 (remaining surfaces)
Method: same real browser session as part 1 (headless Chromium, 1440×900, dev build
sidecar :3333 + vite :8080), continuing after `ux-audit-2026-07-04.md` (F1–F12).
Surfaces: Settings (all tabs + light mode), Marketplace, workspace tabs
(Files/Team/Memory/Artifacts), workspace switcher + grid, notifications, Memory
Center sub-tabs, New Agent flow, 900×700 resize. Screenshots `ux2-01`..`ux2-28`
in session scratchpad. Findings numbered F13+ to continue part 1.
Environment notes (not product findings):
- The tree carries heavy test-data pollution (≈50 `ai-os-audit-*` workspaces,
BENCHMARK memories). The *data* is dev noise, but every failure to cope with
it (sorting, dedup, counts, truncation) is real product signal — flagged as such.
- One transient blank-page/Vite 500 (`@/lib/coach-marks-gate` unresolved) occurred
while wave-1 fixes were being edited live in the same tree; recovered on reload.
- Verified in-session: the trial-expired modal did NOT re-fire across ~10
navigations — the F1 fix works. Escape-to-close works on Switch Workspace and
New Agent modals (good), but not on the briefing modal (F27).
## The story of part 2: the app contradicts itself
The deep surfaces are feature-rich and often well-designed in isolation, but they
disagree with each other about basic facts: which workspace you're in (F13), how
many workspaces exist (F14), which model you're on (F15), and whether your memory
graph has 9,420 relations or none at all (F16). Apple-benchmark polish is mostly
a consistency problem here, not a component-quality problem.
## Findings
| # | Sev | Finding | Evidence |
|---|-----|---------|----------|
| F13 | P1 | Workspace context is unstable: merely visiting `/` (Home) or `/workspaces` silently switches the active workspace — sidebar switcher + breadcrumb flip to `ai-os-audit-daniel-finance-…` while the Home "START HERE" card simultaneously says Research Hub is your most recent workspace. Context must never change without user action | ux2-12, ux2-22 |
| F14 | P1 | Workspace count/name chaos: Home says "**4** workspaces waiting for you", switcher lists ~14, grid says "All **55**", a notification says "across **54** workspaces". Three workspaces are all named "Research Hub" with no disambiguation; switcher has no current-workspace indicator, no search, and truncates long names at the exact point they become identical | ux2-20, ux2-21, ux2-12 |
| F15 | P1 | No single truth for "what model am I on": top-bar chip says `claude-sonnet-4-6`, Settings Model Pilot says Claude Opus 4.6 (and Fallback = Primary = Opus 4.6, a pointless failover default), New Agent modal offers only raw `ollama/minimax-m2.7:cloud`-style IDs with one preselected | ux2-01, ux2-28 |
| F16 | P1 | Memory numbers contradict across adjacent tabs: Timeline header "617 entities · 9420 relations" while Graph tab says "No knowledge graph data"; top-bar brain count 543 vs Trust page "452 memories in this hive"; Trust page headline sells trust directly above a "**0** high confidence & fresh" chip while individual rows are labeled "fresh" | ux2-25-Timeline, ux2-25-Graph, ux2-24 |
| F17 | P2 | "Erase All Data" (red, one click to schedule a full wipe) sits on the DEFAULT Essential→General settings tab as the 4th item a new user sees, directly under the theme picker. Belongs in Advanced behind a danger-zone pattern | ux2-02 |
| F18 | P2 | Permissions "Never ask" (yolo: auto-pass everything) is selectable with zero friction — no confirmation, no red/danger styling when active; renders exactly like the safe options. (Verified: shipped default is `normal`; this is about the switch UX, not the default) | ux2-05 |
| F19 | P2 | Files vs Artifacts tabs are indistinguishable: both empty states say "files/documents created in this workspace appear here". Files empty state offers no upload/create action (dead end); Artifacts' "Browse … in Library" pointer is plain text, not a link | ux2-16, ux2-19 |
| F20 | P2 | Marketplace lists the same integration 3× from three catalogs — `airtable` (mcp · marketplace · "Not scanned"), `Airtable` (connector · local registry), `Airtable` (mcp · MCP catalog) — with three different verbs (Add / Connect / Enable), inconsistent casing, and no guidance which to choose. "Not scanned" warning chip has no explanation | ux2-27 |
| F21 | P2 | Workspaces grid: category filters Virtual/Local/Team all show 0 while All=55 (filters that can never match); every card's metadata row renders as "—" placeholders; disabled "Table — soon" roadmap chip leaks unfinished scope into the UI | ux2-21 |
| F22 | P2 | Memory dedup failures are user-visible: the same BENCHMARK memory appears 3× as separate cards in Memories tab; login briefing "I REMEMBER" shows the same Imran fact twice (differing only by audit-run id) | ux2-25-Memories, ux2-11 |
| F23 | P2 | Wiki tab auto-compiles 220 entity pages with no quality floor — junk entities ("Act Aug", "Act Art", "Acquired March", "Abu Dhabi Airport") become first-class pages, and every page claims identical "30 sources · compiled 10d ago" metadata, which reads as broken | ux2-26-Wiki |
| F24 | P2 | Weaver tab is 3 stats + a "Run Now" button with zero explanation of what the Weaver does or what running it will change; "LAST DECAY: Never" is unexplained internal jargon. Compare Evolution tab, which explains itself well | ux2-26-Weaver |
| F25 | P2 | Notifications: badge says 9+ but panel shows 4 items, all batch-stamped the same second; copy is system-jargon ("Capability suggestion completed — Scheduled task ran successfully" — which suggestion? where?); "Connect your external tools" advice has no CTA/link to Connectors; timestamps are machine-format with seconds ("4. 7. 2026. 10:20:53") | ux2-22 |
| F26 | P2 | Team tab: a single row "You — Online" with avatar initials "YO" (literal initials of the word "You"), no invite affordance, no Teams-tier explainer — a dead end that also misses the natural upgrade moment | ux2-17 |
| F27 | P2 | Login-briefing modal: cannot be dismissed with Escape (other modals can), close ✕ has no accessible name, "Start Working" CTA is shown while content is still loading, and its "Good afternoon, Marko" heading duplicates the identical greeting on the Home page visible behind it | ux2-10, ux2-11 |
| F28 | P3 | At 900×700 the top OS bar breaks: "Waggle AI" wraps to two lines, breadcrumb truncates to "Ch…", Trial-expired chip collides with search. Sidebar never collapses (250px of 900px). Content areas themselves reflow acceptably | ux2-14, ux2-15 |
| F29 | P3 | Locale fragments: Serbian dates inside an all-English UI ("СУБОТА, 4. ЈУЛ", "Last active: 28. 6. 2026.", "суб 4. јул" in top bar) — either localize the whole product or pin the date locale to the UI language | ux2-12, ux2-13 |
| F30 | P3 | Copy/data nits: "1 memories"; memory card whose title duplicates its body verbatim; "GDPR Art.17 — kept from re-import" jargon in Memory tab corner; Harvest interrupted-banner says "saved 1 of 1 items" yet offers Resume (nothing left to resume); Timeline "50 of 50 frames" cap unexplained | ux2-13, ux2-18, ux2-26-Harvest |
| F31 | P3 | Tier naming drift: General tab + profile chip say FREE, Plan page's current-plan card is named "Solo" | ux2-02, ux2-03 |
| F32 | P3 | Stale state on fresh navigation: `/memory` reopens a leftover memory-detail drawer over the page; top OS-bar breadcrumb stays "Chat" while on Files/Team/Artifacts tabs | ux2-23, ux2-16 |
## What's already good (don't regress)
- Settings "Show: Essential / Standard / Everything" progressive disclosure —
genuinely Apple-like; plus the "Local-first" plain-language explainer.
- Plan page "What Waggle replaces" honest scorecard (✓/○/✗ with "only items that
genuinely don't need another tool open are marked covered").
- Backup tab: export/import + AES-256-GCM encrypted backup, clear copy.
- Permissions copy quality ("Auto-pass writes/edits; still gate git push,
install, cross-workspace") — precise and honest.
- Trust page concept and reassurance banner ("Nothing is remembered behind your
back…"), pencil/trash per-memory affordances, "Why did you do that?" view.
- Harvest tab: interrupted-harvest Resume/Discard banner, "data stays on this
device" trust strip, 16 platform chips + drop-zone, detected-tool re-harvest.
- Evolution tab empty state explains the propose→review→accept loop in 3 lines.
- New Agent modal: Existing/+New workspace toggle, collapsed persona override,
two-step "Review & Launch", clean Cancel.
- Light theme holds up on Settings/Home/Chat — no broken contrast or unstyled
tokens found (only pre-existing layout issues carry over).
- Switch Workspace modal: Escape works, "Ctrl+Tab to toggle" hint, one-line
purpose copy ("One workspace per project or area — each remembers its own work").
- F1 fix verified live: trial modal stayed dismissed across ~10 navigations.
## Suggested wave assignment
- Wave 1 (trust-critical consistency): F13, F14, F15, F16, F27 (Escape/a11y part).
- Wave 2 (safety + IA): F17, F18, F19, F20, F21, F25, F26.
- Wave 3 (polish): F22, F23, F24, F28–F32.

52
docs/ux-refactor/ux-audit-2026-07-04.md Normal file
View File

@@ -0,0 +1,52 @@
# UX Audit — Browser Walkthrough 2026-07-04
Method: real browser session (headless Chromium, 1440×900) against dev build
(sidecar :3333 + vite :8080), walked as a first-time user via `?forceWizard=true`.
Screenshots in session scratchpad `ux-01`..`ux-16`.
## The first-run interruption stack (the P0 story)
A new user's first 90 seconds today:
1. Onboarding ends with **"Let's go!"** — but the first task is **never sent**;
it sits prefilled in the composer (broken promise). *(F2)*
2. The instant the workspace loads, a **"Your 15-day trial has ended" modal**
covers everything. *(F1)*
3. Dismissing it immediately reveals a **4-step coach-mark carousel** over the
welcome panel. *(F5)*
4. Sending the message manually then fails: **"API key is invalid or expired"**
— even though onboarding's model step showed a green **"You have a working
model — you're ready to go."** *(F3)*
5. The error is dead-end small text: no Retry, no link to the settings screen
it names. *(F4)*
## Findings
| # | Sev | Finding | Evidence |
|---|-----|---------|----------|
| F1 | P0 | Trial-ended paywall modal re-fires on EVERY route navigation; "Continue with Free" dismissal is not persisted (fired 3× in 10 min: post-onboarding, `/`, `/memory`) | ux-07, ux-11, ux-12 |
| F2 | P0 | Onboarding final step "Let's go!" navigates to chat but does NOT send the chosen first task; text sits in composer | ux-08 |
| F3 | P0 | Model-gate step claims "You have a working model — you're ready to go" from key presence only; first real call 401s. Probe exists server-side (`llm-key-probe.ts`) but the claim isn't probe-backed | ux-03 vs ux-10 |
| F4 | P1 | Chat LLM error is inline small text, no Retry button, no link to "Settings > API Keys" it references | ux-10 |
| F5 | P1 | Coach-mark carousel fires immediately on first landing, stacking on top of the paywall dismissal; suppress on first-run landing / show later | ux-08 |
| F6 | P2 | Onboarding polish: (a) disabled "English (US)" pill looks clickable; (b) duplicate Back controls (header ← Back + footer Back); (c) all 8 "help with" chips preselected → zero signal; (d) template picker ignores stated role — no "Recommended" ranking (Strategy Consultant → no consulting-flavored guidance); (e) final step loses Back + step counter; (f) final-step suggestion chips not template/role-tailored (PRD/campaign chips inside Research Hub) | ux-01..06 |
| F7 | P2 | IA naming drift: sidebar "Agents & tasks" → page "Agent Center" (no tasks visible anywhere on it); sidebar "Library" → page/URL "Artifacts"; section label "EVERYTHING ELSE" is filler copy | ux-13, ux-14 |
| F8 | P2 | Sidebar active-state wrong on workspace Overview (highlights "Chat") | ux-15 |
| F9 | P3 | Welcome-back panel on a fresh workspace: "Here's where you left off … across 0 sessions"; should have a first-visit variant | ux-08 |
| F10 | P3 | ⌘K palette: ESC chip collides with close ✕ icon | ux-16 |
| F11 | P3 | Working-step accordion duplicates ("Worked across your memory, web & files" ×2 for one turn) | ux-10 |
| F12 | P3 | Agent Center: single row floats over a vast honeycomb void — needs a richer empty/sparse state (template suggestions) | ux-13 |
## What's already good (don't regress)
- Welcome hero: calm, single CTA, on-device trust line.
- Live greeting preview in who-are-you step.
- "Claude Code detected — 495 items — Import my history" one-click harvest.
- Chat working-state transparency (Auto Recall chip, timing).
- ⌘K palette structure (Jump to / Do).
- Trial modal's honest "You keep / You lose" framing (the content, not the timing).
## Wave plan
- Wave 1 (this session): F1, F2, F3/F4 (probe + actionable error), F5, F8, F9, F10.
- Wave 2: F6 (onboarding polish set), F7 (IA naming — product naming decision), F11, F12.

186
docs/ux-refactor/ux-transformation-report-2026-07-04.md Normal file
View File

@@ -0,0 +1,186 @@
# UX Transformation Report — 2026-07-04
Mission: experience Waggle OS as a real user (headless-Chromium walkthroughs of every
core journey), fix what breaks the experience, iterate until marginal. Benchmark: Apple.
**Commits:** `c03ca816` (wave 1) · `ad885d49` (wave 2) · `3091b04a` + `c04d049e` (wave 3) ·
`1e27933a` + `60616f8a` (wave 4) · `27e94077` (wave 5) · `8a4d2549` (wave-5 QA follow-up:
briefing dedup phrase-strip). All on local `main`, NOT pushed.
**Evidence:** `ux-audit-2026-07-04.md` (F1–F12), `ux-audit-2026-07-04-part2.md` (F13–F32),
`ux-wave2-plan-2026-07-04.md` (plan + deferred + incidental defects).
**Gates at close:** web tsc 0 · server tsc 0 · build:packages clean · web vitest 1323/1323 ·
every wave browser-verified by an independent QA agent (wave 1: 8/8, wave 2: 7/7 + regressions,
wave 4: 3 clean PASS + 4 patched post-QA, wave 5: verified — see below).
## Shipped
**Wave 1 — the first-run interruption stack (F1–F5, F8–F11):**
trial-paywall re-firing on every navigation → gated (session-once + 7-day snooze +
post-onboarding quiet window); "Let's go!" now actually sends the first task;
model-gate claim probe-backed (new `POST /api/settings/probe-provider`); LLM errors
became actionable ErrorBlocks (Retry + settings deep-link); coach marks defer on
first landing; sidebar active-state, fresh-workspace briefing copy, ⌘K collision.
**Wave 2 — the app no longer contradicts itself (F6, F7, F12–F16, F19, F21, F27):**
active workspace never silently switches; one source of truth for workspace counts
(dev-noise filter, switcher checkmark + overflow); friendly model labels everywhere +
fallback≠primary; Memory Graph scope fix (renders 1,698 nodes where it said "no data")
+ server stats undercount fix + scope-labeled counts; onboarding polish (Recommended
template from role, goals unselected, single Back, tailored suggestions, static
language badge); IA renames (Agents / Library / General); briefing-modal a11y
(focus trap, Escape, labeled close); failed turns re-render as ErrorBlock on reload.
**Wave 3 — QA residuals:** paywall never stacks on the briefing modal; probe banner
names the verified provider; step counter 4-of-5/5-of-5; redundant storage pill hidden.
**Wave 4 — root-cause dig + remaining-list cleanup (browser QA in flight):**
- **DB-flake ROOT-CAUSED** (not yet fixed — see below): `MultiMindCache` LRU evicts
and closes an in-use `MindDB` mid-turn; post-response writes then throw "database
connection is not open" and are silently swallowed. Confirmed exact mechanism.
Added a classifier + structured warn logs at the two silent seams (autoSaveFromExchange,
KG extraction) in `chat.ts` so it's now observable. **The real fix (pin/refcount on
MultiMindCache, or a reopen-on-closed-handle guard in db.ts) lives in
`packages/hive-mind-core/src/{multi-mind-cache,db}.ts` — off-limits to this arc per
§7.5 (substrate changes land there first, not as a side effect of a UI sprint).**
Also flagged: `WorkspaceSessionManager.closeIdleSessions()` is dead code (defined,
never invoked) — likely related, needs wiring to an interval.
- F22 memory dedup: fixed. Cards collapse by normalized content with a "×N" badge;
briefing highlights route through the same normalizer.
- F25 notifications: badge/panel count now share one derivation (no more independent
drift); copy humanized; dead deep-links corrected across 5 server files; relative
timestamps. QA-verified clean.
- F28 responsive: top bar protected (no-wrap brand, shrink-safe chips); sidebar
collapses to an icon rail with tooltips under `lg`. QA-verified clean.
- F15 long tail: model-label wired into ChatApp, TelemetryApp, WorkspaceDesktopApp,
ChatWindowInstance toast.
- F31 Solo→Free rename; F24 Weaver plain-language explainer + "Last Decay" tooltip.
QA-verified clean.
**Wave 4 post-QA patch round (browser-verified after fix):**
QA ran the fresh build and found F22 had NOT shipped despite the implementer's claim,
plus two partial misses. Root-caused and fixed all three directly (no new workflow):
- **F22 dedup — real root cause was different from the original hypothesis.** Live
data doesn't just differ by a stripped volatile token; a benchmark "anchor" memory
gets re-written repeatedly with more appended turns each time (same title, content
is a strict prefix of the next copy) — 6 visibly-duplicate cards, a growing chain
pass-1 exact-match dedup can never merge. Added a second dedup pass:
bucket by normalized title, absorb any entry whose content is a normalized prefix
of a longer sibling's. Also found the normalizer's volatile-token regexes missed
the *actual* live shapes: a raw epoch `Timestamp: 1782400441971` (not ISO-8601),
a bare `audit-<digits>` id (RUN_ID_RE required the literal word "run"), and a
`BENCH-SECRET-<token>`. Fixed all three; live-verified — the 6-card BENCHMARK
family now renders as one card with an accurate `×7` badge.
- **F15 StatusBar chip — real bug, not stale HMR.** `formatModelLabel`'s catalog-match
branch trusts any provider-catalog `name` that differs from the `id` as an
already-friendly display name — true for the static cloud catalog, but Ollama's
catalog `name` is *deliberately* the bare installed tag (`routes/providers.ts`
`fetchOllamaModels`, "Display name stays the bare tag"), so it short-circuited
before the heuristic humanized it. Fixed by skipping the catalog-trust branch for
`ollama/`-prefixed ids. Live-verified: chip now reads "Gemma4 (31b)".
- **F24 Weaver tooltip — NOT a bug.** Verified live after a full daemon + Vite
restart: the tooltip renders correctly (a real `[role=tooltip]` DOM node appears
on hover). QA's long-running session (hours, 4 waves of live edits) is the more
likely explanation than a code defect here — the same explanation QA itself gave
for the sidebar/model-chip tooltips not screenshotting.
- F30 copy nit: found the SAME missing-pluralization bug duplicated in two server
files (`workspace-context.ts` + `workspaces.ts`, 4 near-identical string templates
each) — fixed all 8 occurrences.
**Wave 5 — final polish (F32, F17/F18, F12, F23):**
- F32: top-bar breadcrumb now reflects the active workspace sub-tab (was stuck on
"Chat" for every tab — root cause: dock-tiers chat entry `route:'/workspaces'` was
the only longest-prefix match); context-rail/detail-drawer cleared on real route
change so it can't pin over the next page.
- F17 (safety posture, revertable): "Erase All Data" wrapped in a bordered all-tier
"Danger Zone" section at the bottom of General. **The implementer correctly refused
the literal "move to Advanced" plan** — Advanced is tier-gated (`settings-tier-filter.ts`
POWER_SETTINGS_TAB_IDS), so moving a GDPR Art.17 erase control there would hide it
from FREE/PRO tiers = a real compliance regression. Danger-zone framing resolves the
actual complaint (plain 4th item under the theme picker) without tier-gating.
- F18 (safety posture, revertable): "Never ask" (auto-pass-everything) autonomy level
now fires a one-time confirm on the transition INTO it + amber danger styling only
while selected. Default stays 'normal'; safe levels never gated/restyled.
- F12: Agent Center sparse state — 2-3 suggested-agent template cards render under the
list when ≤2 agents exist on the unfiltered tab (fills the honeycomb void).
- F23: Wiki tab display-level quality floor (hide entity pages with name <3 chars OR
<2 sources), all counts derive from the floored set. Conservative — catches genuinely
thin entities in clean data; a no-op on the benchmark-polluted dev corpus (whose junk
all reports "30 sources"). A fragment heuristic for those was deliberately NOT shipped
blind (false-positive-prone).
- Files-tab empty state: copy + "Open chat" CTA only — NO upload button, because
`getWorkspaceFiles` (ingest registry) and `uploadFile` (storage-provider fs) are
provably disjoint stores; an upload button would succeed yet leave the tab empty.
- W5D **surfaced a real contradiction, resolved conservatively**: the CreateWorkspaceDialog
"Free plan includes one workspace" copy — canonical `tiers.ts` says FREE=5 / PRO=unlimited,
but the legacy `feature-gates.ts` gates `multi-workspace` behind `minTier:'teams'`, so
the runtime blocks FREE (and PRO-as-'solo') at workspace #2. Quoting either "1" or "5"
contradicts a source and (for "5") creates a broken promise in the paywall's own dialog.
Made the copy number-free ("Upgrade to add more workspaces — each keeps its own separate
memory") pending a founder decision on the gate↔config mismatch (see below).
## Remaining high-impact issues (no product decision needed — just work)
_Reconciled 2026-07-05 after wave 5 + the workspace-limit resolve; several items
originally listed here shipped in wave 5 (F32 drawer/breadcrumb, Agents sparse-state
cards, wiki floor, workspace copy) and were removed._
1. **DB-flake real fix** — fully diagnosed (Wave 4): `MultiMindCache` LRU closes an
in-use `MindDB` mid-turn. Needs a substrate change in `packages/hive-mind-core`
(pin/refcount-aware eviction, or a reopen-on-closed-handle guard in `db.ts`) — a
separate arc per the OSS-sync policy (§7.5), not a UI-sprint side quest. Also wire
up the dead `WorkspaceSessionManager.closeIdleSessions()` while there. **Highest
real-user impact of anything remaining** (it silently drops post-turn memory writes).
2. **Files-tab Upload** — blocked on a design step: `getWorkspaceFiles` (ingest
registry, `files.jsonl`) and `uploadFile` (storage-provider fs) are disjoint stores,
so an upload button would succeed yet leave the tab empty. Needs the registry↔storage
merge first; until then the empty state is copy + "Open chat" only (shipped wave 5).
3. **W2G part C — server-side retry-dedup** — after a chat error, a local Retry can
leave a duplicated failed user+assistant pair on reload. ~4-file server-side change
(chat-persistence strip + retry-body handling). Cosmetic-on-reload only.
4. **F23 wiki fragment heuristic** — the conservative quality floor (name<3 / <2 sources)
shipped, but the named junk pages ("Act Aug", "Abu Dhabi Airport") are ≥4-char,
multi-word, all "30 sources" in the polluted dev corpus, so nothing catches them.
A fragment heuristic (all-words-≤3-chars, standalone month tokens) is false-positive
-prone — needs a clean corpus to tune against. Low value.
5. **Watch, not a task:** the wave-4 growing-composite dedup pass (same-title +
content-is-a-prefix) has only been validated against the one benchmark "anchor"
family. Watch for false negatives on other real duplicate shapes.
_Cosmetic tail: onboarding slug-collision still logs a single 409 (create path
auto-suffixes, so no user-visible break); cached workspace summaries keep old
"1 memories" text until regenerated (the generator is fixed)._
## Needs a product decision
- ~~**Workspace-limit gate ↔ config contradiction**~~ — RESOLVED (`593e6b40`). It
turned out to be a client↔server *sync bug*, not a business decision: the server
already enforces the canonical `tiers.ts` limit (FREE=5 / PRO=unlimited), only the
client dialog gated off the stale `feature-gates.ts` `multi-workspace` flag and
blocked at #2. Aligned the client to the same rule (new pure `canCreateWorkspaceAtTier`
mirroring the server, boundary property-tested); paywall copy now truthfully quotes
"The Free plan includes 5." **Still open (a real product decision, not this bug):**
the legacy `feature-gates.ts` still carries the outdated 'solo'/'business' tier
vocabulary (F31's deeper root) and the now-unreferenced `multi-workspace` entry — a
broader migration of that whole file onto the canonical 5-tier system is worth doing.
- **Model-gate truth-gap:** the gate verifies a provider key, not the workspace
chat's configured model (QA saw "Anthropic verified" while the chat's model 401'd).
Should the gate probe the actual default model instead?
- **F20 marketplace:** same integration listed 3× from three catalogs with three
verbs (Add/Connect/Enable) — needs a catalog-merge design, not a patch.
- ~~**F17/F18 safety UX**~~ — SHIPPED in wave 5 as a revertable posture change
(Danger Zone + "Never ask" confirm). If a stronger posture is wanted (e.g. move
Erase fully into Advanced *and* accept tier-gating it, or a higher-polish inline
amber confirm-row instead of a native `confirm()`), that's the remaining decision.
- **F29 locale:** Serbian date fragments inside an all-English UI — localize fully
or pin dates to UI language.
- **F26 Team tab:** dead end ("You — Online") that misses the Teams-tier upsell moment.
- **Sidebar active state on workspace Overview:** wave 1 made no spine item active
there (previously Chat, wrongly). Design may prefer the workspace pill to carry it.
## Environment notes for the next session
- Dev recipe: sidecar `WAGGLE_SKIP_LITELLM=1 node --env-file=.env node_modules/tsx/dist/cli.mjs
packages/server/src/local/start.ts` (RESTART after server edits — no watch);
`npm run dev` (vite :8080); browse CLI daemon for walkthroughs.
- esbuild trap: `npm i @esbuild/win32-x64@0.28.0 --no-save` if tsx fails on version mismatch.
- Tree has heavy dev-noise workspaces (`ai-os-audit-*`) — now filtered in UI counts,
but consider a real cleanup.

87
docs/ux-refactor/ux-wave2-plan-2026-07-04.md Normal file
View File

@@ -0,0 +1,87 @@
# UX Wave 2 Plan — 2026-07-04
Source audits: `ux-audit-2026-07-04.md` (F1–F12) + `ux-audit-2026-07-04-part2.md` (F13–F32).
Wave 1 (F1–F5, F8–F11) shipped in working tree; this wave targets the
trust-critical consistency cluster + part-1 leftovers.
## Clusters
### W2-A — Workspace context stability (F13, P1)
Visiting `/` or `/workspaces` must NEVER silently switch the active workspace.
Find what mutates active-workspace state on those routes (likely a "most recent"
auto-select effect in Home/grid mount) and make selection explicit-only (click).
Breadcrumb/switcher must agree with the workspace the user last chose.
### W2-B — One truth for workspace counts + switcher (F14 partial, P1)
Home "4 workspaces waiting", switcher ~14, grid "All 55", notification "54".
Diagnose each source (endpoint/filter). Likely: grid counts ALL incl. dev-noise
+ archived; home counts a "recent" subset; switcher caps at N without saying so.
Fix: single selector/source-of-truth for workspace counts; switcher gets
current-workspace checkmark + overflow indicator ("14 of 55 — view all").
Card metadata "—" placeholder rows (F21): hide missing metadata instead of "—";
filters that can never match (Virtual/Local/Team all 0 while All=55) either get
real predicates or are removed; drop the "Table — soon" chip.
### W2-C — One truth for the current model (F15, P1)
Top-bar chip `claude-sonnet-4-6` vs Settings Model Pilot "Claude Opus 4.6" vs
raw IDs in New Agent. Diagnose: chip probably shows per-chat model; Model Pilot
shows global default; New Agent lists raw router IDs. Fix: consistent display
names via one formatting util (grep for existing model-name formatter); Model
Pilot fallback must not default to == primary; New Agent model list uses same
labels as everywhere else.
### W2-D — Memory numbers agree (F16, P1)
Timeline "617 entities · 9420 relations" vs Graph tab "No knowledge graph data";
top-bar brain 543 vs Trust "452 memories"; Trust "0 high confidence & fresh"
above rows labeled "fresh". Diagnose each pair: different endpoints? stale
cache? per-workspace vs global scope? Graph-tab emptiness while KG has data is
the highest-value bug (feature looks broken). Fix root causes, not copy.
### W2-E — Onboarding polish batch (F6, P2)
(a) "English (US)" disabled-button pill → plain text badge (or working picker if
one exists); (b) remove duplicate footer "Back" (keep header ← Back);
(c) "help with" chips: default NONE selected (placeholder greeting preview until
≥1 chosen); (d) template picker: rank/badge "Recommended" from who-are-you
role/work-type (pure mapping + test); (e) final step: restore Back + step
counter; (f) final-step suggestion chips filtered to the chosen template.
### W2-F — IA naming + empty states (F7, F12, F19 partial, P2)
Align: sidebar "Agents & tasks" ↔ page "Agent Center" → both "Agents"; sidebar
"Library" ↔ page "Artifacts" → page header "Library" (artifacts remain the
content type); "EVERYTHING ELSE" section label → "Workspace-independent" intent,
pick something plain ("General"). Agent Center sparse state (1 row + honeycomb
void): add template suggestion cards under the row. Files tab empty state gets
an Upload action; Artifacts empty-state "Browse in Library" becomes a real link.
### W2-G — Briefing modal a11y + chat error history parity (F27 + wave-1 residual)
Login-briefing modal: Escape closes; ✕ gets aria-label; "Start Working" disabled
until content ready; drop duplicated greeting (visible identically on Home
behind it). Chat: persisted failed assistant turns ("Generation failed: …")
re-render as ErrorBlock on reload (reuse isAuthShapedError), and the
server-persisted failed pair must not duplicate after a local Retry + reload.
## Deferred to wave 3 (product decisions or heavier)
- F17 Erase-all placement, F18 Never-ask friction (safety UX — quick but opinion-laden)
- F20 marketplace triplicates (needs catalog-merge design)
- F22 dedup, F23 wiki quality floor, F24 weaver explainer
- F25 notifications rework, F26 team invite moment, F28 responsive top bar
- F29 locale, F30 copy nits, F31 tier naming (Solo vs Free), F32 stale drawer/breadcrumb
## Incidental defects from wave-1 QA (2026-07-04, not UX-wave scoped)
- Ollama cloud models fail every send with server error "The database connection
is not open" (reproducible across Retry; ErrorBlock renders it correctly).
Smells like the LiteLLM no-DB bearer-key class of bug — backend triage needed.
- Onboarding template pick that collides with an existing workspace slug 409s
and silently continues INTO the existing workspace — user never learns their
"new" workspace wasn't created. Needs suffixing or a visible choice.
- Transient F2 window: during the auto-sent first task's streaming, the text
briefly also sat in the composer before clearing — an Enter there would
double-send. Cosmetic, final state correct.
- The "The database connection is not open" send failure is provider-agnostic —
it hit an Anthropic retry too, not just Ollama cloud. Intermittent, not
reproducible on demand. Backend triage (the LiteLLM no-DB class, above).
- Probe truth-gap (deeper than the wave-3 copy fix): the model gate verifies a
PROVIDER KEY, not the workspace chat's configured default model. Product
decision whether the gate should probe the actual default model instead.
- Workspace switcher: the active row lacks the "· time ago" disambiguator when
`lastActive` is null, so it can't be told apart from same-named rows.

77
docs/ux-refactor/wave-P-spec-2026-07-06.md Normal file
View File

@@ -0,0 +1,77 @@
# Wave P — structural redesigns (2026-07-06 S2, goal: 5 judges ≥9/10)
Three lanes, one file-set each, no overlap. Grounding screenshots (what judges scored, R8):
`C:/Users/MarkoMarkovic/AppData/Local/Temp/claude/D--Projects-waggle-os/cd366627-6451-4ef6-b0d3-93a63ceb7678/scratchpad/shots/judge-round8/`
Shared vocabulary (index.css): shadows `--shadow-card/--shadow-elevated/--shadow/--shadow-sm/--shadow-honey`,
radii `--r-lg:18px / --r-xl:26px`, colors `--honey/--honey-text/--honey-wash/--honey-line`,
`--line-soft/--surface/--surface-2/--text/--text-2/--text-muted/--text-dim`, tones `--intel/--healthy/--risk/--attention` (+`-wash`).
Honesty contract (repo-wide): never render fabricated data; absent field ⇒ don't render.
## Lane 1 — Settings provider selector (`ModelGate.tsx` + `SettingsApp.tsx`) — worst surface 6.8
Judge ask (R7/R8 convergent): "11 identical check pills" → a REAL selector: filled tiles,
anchored density control, sub-nav structure.
1. **Provider tile grid** (ModelGate cloud tab, replaces the pill row; BOTH variants):
- `grid grid-cols-2 sm:grid-cols-3 xl:grid-cols-4 gap-2`. Tile = left-aligned mini-card,
`rounded-[12px] border p-3`, two rows:
row 1 name (13px semibold) + right-aligned state glyph (Check honey = keyed ·
AlertTriangle amber = keyed-but-probe-failed · none = no key);
row 2 quiet 11px meta: `N models` + state word ("Key in Vault" / "not responding" / "No key yet").
- Fill states: keyed → `bg-[var(--honey-wash)] border-[var(--honey-line)]`; failing → risk/amber wash;
unkeyed → transparent bg, `border-[var(--line-soft)] text-[var(--text-muted)]`.
- Selected tile: honey ring (`ring-2 ring-[var(--honey-line)]` or border-primary) + `shadow-[var(--shadow-card)]`.
- **Grouping**: when ≥1 keyed provider exists, two quiet group labels: "Your providers"
(keyed incl. failing) then "Add a provider" (rest). Zero keyed (onboarding first-run) ⇒ one flat grid, no labels.
- Keep: aria-pressed, keyboard focus-visible, existing handleSelect/probe logic untouched.
2. **Anchor the density control** (SettingsApp): move the floating top-right "Show Essential/Standard/Everything"
segmented control to the BOTTOM of the left tab rail (it gates which tabs exist — anchor it to what it controls).
Compact: caption "Show" (11px muted) above the 3 options stacked or segmented vertically. Keep
aria-label "Settings detail level" + `useOnboarding().tier` mechanics. Update `src/test/pr5-settings-reskin.test.tsx`
copy if it references "top-right" (behavioral assertions must keep passing).
3. **Models tab de-duplication** (SettingsApp models tab): the "Provider API Keys" row list now repeats the tile grid
1:1 — replace that list with one quiet line ("Keys live in the Vault — manage them above or in the Vault app.")
keeping the Lock note. Keep Search Providers section. Give the tab's three zones consistent section headers
(match the `SectionLabel` uppercase-rule treatment used on Home).
## Lane 2 — Workspace card v3 (`AllWorkspacesApp.tsx`) — 7.0
Judge ask: aligned meta baseline + activity preview + hover affordance. See `122-workspaces-dark.png`:
meta rows sit at different heights; description-less cards feel empty; no visible open cue.
1. **Aligned baseline**: card → `flex flex-col` + `min-h-[168px]`; meta footer gets `mt-auto pt-3` so
EVERY card's meta row sits on the same baseline regardless of body content.
2. **Body (activity preview, real data only)**: description (2-line clamp) when present; otherwise compose from
real fields ONLY: created line + last-activity, e.g. `Created 3w ago · active 2w ago`. Check whether the server
list rows carry a cached `summary` field (grep `summary` in lib/types + the /api/workspaces payload via
useWorkspaces/ShellContext); if a real summary exists, render it exactly like description. NO invented copy.
3. **Hover affordance**: on group-hover, a quiet `Open →` cue fades in at the footer right (next to the actions menu),
`text-[var(--honey-text)] opacity-0 group-hover:opacity-100`; keyboard focus shows it too (`focus-within`).
Keep existing whole-card click + menu stopPropagation + testids.
4. Keep dup-name disambiguation; move the group/slug chips into the SAME fixed header block so they don't push
the body around (header zone = fixed two-line height: title + one optional disambig/meta line).
5. Update `AllWorkspacesApp.test.tsx` only if assertions reference changed classes/copy; testids stay.
## Lane 3 — Home card system (`HomeCockpit.tsx` + `warm/OvernightHero.tsx`)
Judge ask (R7 #1 + R8): 3 card treatments in one viewport → ONE system with variants. See `121-home-dark.png`.
Unify to a 3-tier grammar:
- **Tier-1 hero** (StartHereCard + OvernightHero + FirstRunEmpty/empty-state cards): radius `rounded-[var(--r-xl)]`
(26px — StartHere is currently an off-system 22px), `shadow-[var(--shadow-elevated)]`, p-6/7.
StartHere keeps its honey identity (border honey-line + honey gradient) — it is THE action;
Overnight keeps surface gradient + glow. IDENTICAL eyebrow anatomy on both:
`flex items-center gap-2 font-mono text-[11px] uppercase tracking-[0.14em]` — StartHere: Sparkles + honey;
Overnight: DotLive intel + text-dim. (Only tone differs, never structure.)
- **Tier-2 card** (RecentWorkspacesPanel): `rounded-[var(--r-lg)]` (18) + `shadow-[var(--shadow-card)]`,
hover: honey-line border + `shadow-[var(--shadow)]` + lift (already mostly true — normalize).
- **Tier-3 row** (review banner + SuggestedActions rows): `rounded-[14px]`, flat (no shadow), hover border only.
Review banner stays honey-wash (it's an alert) but same radius/height grammar as suggested rows.
- Sweep any remaining `rounded-[26px]`/`rounded-[22px]` literals on home surfaces to the token tiers above.
- CAUTION: `formatBriefingDate` exact-node test (P2) — don't touch the date render. Home tests live in
`src/test/` (grep `home-cockpit` there); testids must survive.
## Per-lane gate (each lane runs before reporting)
- `npx vitest run <related test files>` green (find with: `npx vitest run --project` — or just run the specific
test files touching your surfaces, e.g. src/test/pr5-settings-reskin.test.tsx, AllWorkspacesApp.test.tsx,
and the home cockpit tests under src/test/).
- Confirm no new eslint errors in touched files (`npx eslint <files>`).
- Orchestrator runs full web tsc + vitest suite after all lanes merge.

83
docs/ux-refactor/wave-Q-spec-2026-07-06.md Normal file
View File

@@ -0,0 +1,83 @@
# Wave Q — R9 convergent fixes (2026-07-06 S2, goal 5×9/10)
R9: design 7.7 · kw 7.4 · competitor 7.5 · a11y 7.6 · brand 7.4 (min 7.4 avg 7.52).
Full verdicts: task output w1vqm327y. R9 shots:
`C:/Users/MARKOM~1/AppData/Local/Temp/claude/D--Projects-waggle-os/a6467fd9-181f-4689-a4ee-1d6dedbbfb17/scratchpad/shots/judge-round9/`
Same shared vocabulary + honesty contract as wave-P spec. Surgical edits; both themes; testids/aria survive.
## Lane A — home interruption stack (5/5 judges, ALL high) — worst surface 6.5
Evidence: `131-home-dark.png` — triple stack: NoModelBanner + home error state (red
triangle + ghosted Retry) + "Catching you up / Briefing unavailable" modal with its
OWN Retry. Judges: "never boot into a blocking modal stacked over two other warnings —
collapse to one problem, one voice."
Files: `overlays/LoginBriefing.tsx`, `model-gate/NoModelBanner.tsx`,
`apps/HomeCockpit.tsx`, + wherever LoginBriefing auto-open is decided (grep its mount).
1. **Briefing fetch failed ⇒ NO modal.** LoginBriefing must not auto-open in its
error/empty state — home renders normally with ONE slim inline dismissible row
("Briefing unavailable — Retry", quiet secondary-button Retry, honey-family glyph
NOT a red triangle; brand judge: make it a calm branded moment).
2. **One problem, one voice:** when the same root cause (sidecar unreachable) makes
both the NoModelBanner and the briefing error fire, suppress the second symptom —
the connection problem is announced once. (NoModelBanner already has its own
conditions — add the guard where home decides what to show, don't gut the banner.)
3. **Modal composition (for when it opens WITH content):** one alignment grid
(left-align header/body/footer), close X on the header baseline, no duplicated
Retry, light-mode surface = real elevated ivory token (currently muddy warm-gray).
4. Home error state (behind the modal today): keep, but honey-family tone + real
secondary-button Retry (a11y judge).
## Lane B — settings provider-grid state semantics (4/5 high)
Evidence: `137-settings-models-dark/light.png`, `141`. Judges: twelve honey-filled
keyed cards read as wallpaper — "reserve amber for the SELECTED card only, red only
for the erroring one"; Show control "reads as stray unstyled text"; light API-key/
Local-model segment unbalanced; "Validate & save looks permanently disabled".
Files: `model-gate/ModelGate.tsx`, `apps/SettingsApp.tsx`, their tests.
1. Tile rest state: neutral (`border-[var(--line-soft)]`, surface bg, NO honey wash).
Keyed signal = the small honey Check + "Key in Vault" meta only. Honey border/ring
is EXCLUSIVELY the selected tile. Failing tile keeps risk wash + glyph.
2. Show control at rail foot → real labeled segmented control (match the Essential/
Standard/Everything pill grammar used elsewhere: one bordered track, filled active
cell, 11px caption "Show" above). Keep aria + tier mechanics.
3. Light theme: the API key / Local model tablist — unselected tab must render as a
visible cell (quiet border or track bg), not ghost text on nothing.
4. Validate & save: empty-input state = quiet outline button + disabled cursor (not
gray-filled "broken"); enabled = full primary. Transition must be obvious.
## Lane C — memory truth & titles (4/5)
Evidence: `134-memory-dark/light.png`. Judges: raw "session handoff 2026 06 24 s2
warm hive pr8…" titles "puncture the memory-you-can-trust promise"; number story
552 vs 448 vs 445 vs 399 confusing; violet M-id/aging accent = unmanaged third hue;
"0 fresh" reads disabled.
Files: `lib/memory-text-normalize.ts` (+test), `apps/memory/*` (MemoryTrustManage,
MemoryTrust, MemoryCard…). The humanizer EXISTS — extend it, don't fork it.
1. Title humanization at render: strip leading date/slug/handoff tokens into the meta
row (e.g. "session handoff 2026 06 24 s2 warm hive pr8 landing shipped roadmap
complete" → title "Warm hive PR8 — landing shipped, roadmap complete" + meta
"session handoff · 2026-06-24"). Deterministic string transforms only — never
invent content not present in the string. Add cases to the existing test file.
2. Number story: ONE headline count; the overlapping-view chips (fresh/high-conf/
stale/to-review) visually subordinate (smaller, quieter) + keep the existing
"overlapping views" disclaimer adjacent to the chips it explains.
3. Zero-state chip: "0 fresh" → quiet zero styling (dim text, no wash) so it reads
"count is zero", not "disabled".
4. Violet M-id / aging accent → fold into the warm family (--text-dim / --attention);
no third hue on this surface.
## Lane D — small truths (kw high + competitor/brand mediums)
Files: `os/StatusBar.tsx`, chat composer strip + message bubbles (grep the Wave-N
"composer agent strip" in chat components), NOT LoginBriefing/NoModelBanner (Lane A's).
1. **Model truth (kw HIGH):** top bar says "Default: Claude Haiku 4.6" while the
thread + Model Pilot say Claude Opus 4.6 — two contradictory truths at once.
Fix by SCOPING the status-bar chip label (it is the new-chat default, e.g.
"New chats: Claude Haiku 4.6" — pick the shortest honest label) — do not fake
agreement; verify what each source actually reads before relabeling.
2. Composer chip grammar: group left = agent context (persona chip + Memory chip +
the anonymous 'Y' avatar — find out what 'Y' IS and label/tooltip or remove),
right = execution (Ask-first + model chip + layers). Visible gap between groups.
3. Light theme user bubble: pale green-grey → warm ivory-honey token (competitor low).
4. Trial chip: "Trial ended · Solo" amber pill screams on every screen — demote to
quiet neutral text-chip (keep click-through to plans). Notifications 9+ badge: leave.
## Per-lane gate
Related vitest files green + eslint on touched files. NO cross-lane file edits.
Orchestrator runs full web tsc + vitest after merge.

103
docs/ux-refactor/wave-R-spec-2026-07-06.md Normal file
View File

@@ -0,0 +1,103 @@
# Wave R — R10 convergent fixes (2026-07-06 S2, goal 5×9/10)
R10: design 7.8 · kw 7.7 · competitor 7.6 · a11y 7.6 · brand 7.5 (min 7.5 avg 7.64 —
new min high; loop moving again). Shots:
`C:/Users/MARKOM~1/AppData/Local/Temp/claude/D--Projects-waggle-os/a6467fd9-181f-4689-a4ee-1d6dedbbfb17/scratchpad/shots/judge-round10/`
Same vocabulary + honesty contract as waves P/Q. Surgical; both themes; testids/aria survive.
## Lane A — settings selection grammar + Show re-home (5/5 flagged the blue ring) — 6.6 worst
Evidence: `137-settings-models-dark/light.png`, `141-settings-provider-selected-dark.png`.
Files: `model-gate/ModelGate.tsx`, `apps/SettingsApp.tsx`, `os/ModelPilotCard.tsx`, tests.
1. **Kill the blue ring** (all 5 judges): shot 141 shows Anthropic with a browser/Tailwind
DEFAULT BLUE focus/ring while OpenAI wears the honey selected border — find every `ring`
utility in the tile grid missing an explicit ring color + the focus-visible outline, and
tokenize: honey ring = selected/focus, risk tint = error; never two ring languages at once.
An error tile that is ALSO selected shows risk ring only.
2. Dark segmented control (API key / Local model): real active state — filled cell
(bg-card + shadow-sm is too subtle in dark; add honey underline or stronger fill) to match
light's clarity.
3. **Re-home the Show control** (3/5): out of the rail foot → the CONTENT side: a compact
labeled control in the settings content header row (right-aligned, caption "Show"),
so it sits visually above the sections it gates. Keep aria + tier mechanics + tests.
4. ModelPilotCard: replace bare `$$$` glyphs with explicit cost text (e.g. "$$$ · ~$0.05/msg"
already exists as a legend at card foot — surface the per-row cost inline, or tooltip +
aria-label; judges called the glyphs cryptic).
## Lane B — workspace card living identity (5/5 HIGH, third round) — 7.0
Evidence: `132-workspaces-dark/light.png`, `140`. The card body still reads as reserved-but-empty;
Open is hover-only; two "Research Hub"s differ only by slug chip; dark cards near-vanish.
Files: `packages/server/src/**` (workspace list route), `apps/web/src/lib/types.ts`,
`apps/web/src/lib/adapter.ts`, `apps/AllWorkspacesApp.tsx` (+test).
1. **Server enrichment (the real unlock):** find GET /api/workspaces list route; the workspace
summary/description cache and per-workspace session/memory stores exist server-side. Extend
each list row with REAL fields where cheaply available: `memoryCount` (frame count for that
workspace mind) and `lastSessionTitle` or the cached summary line. NO N+1 explosion: batch
or reuse existing counts; if a count is expensive, skip it — never estimate. Typecheck
packages/server with its own tsconfig (it is NOT covered by npm run build).
2. Card render: body = description OR cached summary OR lastSessionTitle-composed line
("Last: <title> · 2w ago") — real strings only; memory count joins the meta footer (⬡ N).
3. `Open →` becomes a PERSISTENT quiet affordance (text-dim at rest, honey on hover) — no
more hover-only reveal; keep the whole-card click.
4. Duplicate names: promote the disambiguator — slug chip moves up beside the title at
readable weight (11.5px), not a whisper below it.
5. Dark theme: card border one token step up (line-soft → line) so cards stop vanishing
(a11y ask); keep light as is.
## Lane C — marketplace craft pass (4/5) — 7.3
Evidence: `136-marketplace-dark/light.png`.
Files: `apps/MarketplaceApp.tsx`, `apps/extend/*` (ExtensionCard, AgentSearchBox…).
1. One chip grammar: tag lozenges (mcp / Security / local registry…) restyle to the app-wide
quiet chip (11px, line-soft border, text-muted) — no third grammar.
2. Search submit: the honey up-arrow orb reads as scroll-to-top — swap to a labeled affordance
(e.g. ⏎ "Search" chip or magnifier-forward) — pick the least-chrome honest option.
3. 'Connected' pill: teal/green → the warm healthy token already used app-wide (--healthy is
sage — fine) BUT brand judge flags it as off-palette teal: verify which token it uses and
align to --healthy + healthy-wash grammar used on agents/home chips.
4. "Not scanned" shield-warning → neutral quiet chip "Safety scan pending" (kw), tooltip intact.
5. START HERE re-curation: lead with memory-feeding connectors (Gmail / Google Drive / Notion /
Slack — whichever of those exist in the catalog), demote 1Password; tighten row vertical
padding one step (density).
6. Listing identity: bump logo tile size one step so brand marks carry the row.
## Lane D — chrome truth + token passes (kw HIGH numbers + a11y tokens)
Files: `os/StatusBar.tsx`, `apps/ChatApp.tsx` (+ chat composer/empty files it imports),
`index.css` (ONLY this lane touches it).
1. **Numbers scope** (kw #1): status bar "552 memories" counts ALL minds; memory page counts
the personal mind (448). Make the scope visible in the chip itself — shortest honest label
(e.g. "552 memories · all minds"); do NOT change what is counted, label it.
2. Composer control family: persona chip, Memory chip, Ask-first, model chip → ONE species
(same height, radius, border/fill logic); the bare '>' collapse toggle gets an aria-label
+ tooltip ("Collapse agent strip") or a clearer icon.
3. Message attribution line (Waggle · Verifier · model): one size/contrast step up (a11y —
it is the only provenance signal on a turn).
4. index.css token pass:
- LIGHT: card elevation one step (slightly stronger --shadow-card + --line-soft on ivory);
light --attention #b57d12 → #9a6408 (matches --honey-text light, 4.64:1 AA — fixes
"aging — added 2w ago" micro-text) — verify attention-WASH stays as-is.
- DARK: muted chip legibility one token step (inactive filter chips sit below comfort —
bump the chip text token used there, NOT global --text-dim which was already tuned).
- Hex wallpaper: add a radial falloff/vignette so the pattern fades toward the content
column (design+brand: "wallpaper → compositional") — CSS mask/radial-gradient on the
wallpaper layer, both themes, subtle.
5. Chat empty state: place one flat-geometric bee mascot (assets/personas set) with a short
warm line — brand judge: "free the mascots". Only if ChatApp owns an empty-state block;
do not invent a new empty state.
## Lane E — brand moments + memory stats + landing stat (brand HIGH)
Files: `overlays/onboarding/WelcomeStep.tsx`, `overlays/LoginBriefing.tsx`,
`apps/memory/MemoryTrust*.tsx`, `apps/www/app/**` (landing hero stat only).
1. Onboarding welcome: one bee mascot moment (flat-geometric set — e.g. general-purpose bee)
beside/above the headline — placed calmly, not clip-art; both themes.
2. LoginBriefing (content state): mascot in the header ("Catching you up" + small bee);
differentiate I-REMEMBER sparkle cards from workspace cards (distinct container tint —
honey-wash vs surface); label the brain/chat micro-counts (aria + visible tooltip);
bottom scroll affordance (edge fade) when the list overflows.
3. Memory stat row: never lead with a zero — order chips by value desc (zero chips last,
already quiet-styled); keep the disclaimer.
4. Landing hero (apps/www): the 86.49% LoCoMo line gets flagship-stat weight — a stat chip /
larger mono treatment near the CTAs (competitor+design). Canonical number 86.49 ONLY.
Gate: `cd apps/www && npx next build` must pass (honest gate for www).
## Per-lane gate
Related vitest green + eslint on touched files; Lane B ALSO: npx tsc --noEmit -p packages/server/tsconfig.json.
NO cross-lane file edits. Orchestrator: full web tsc + vitest + www build after merge.

90
docs/ux-refactor/wave-S-spec-2026-07-06.md Normal file
View File

@@ -0,0 +1,90 @@
# Wave S — R11 convergent fixes: craft parity on the boring surfaces (goal 5×9/10)
R11: design 7.5 · kw 7.8 · competitor 7.8 · a11y 7.8 · brand 7.8 (avg 7.74 best-yet).
Design director: "the gap to 9 is craft parity on the boring surfaces."
Shots: `C:/Users/MARKOM~1/AppData/Local/Temp/claude/D--Projects-waggle-os/a6467fd9-181f-4689-a4ee-1d6dedbbfb17/scratchpad/shots/judge-round11/`
Same vocabulary + honesty contract as waves P/Q/R. Surgical; both themes; testids/aria survive.
## Lane A — settings provider selector, third pass (design 6.5)
Files: `model-gate/ModelGate.tsx`, `apps/SettingsApp.tsx`, tests. Evidence: 137 pair + 141.
1. **Provider logomarks**: the marketplace already renders brand logo tiles (see
`apps/extend/ExtensionCard.tsx` / its logo asset pattern — REUSE that asset/technique).
Each provider tile gets its brand mark (Anthropic, OpenAI, Google…) left of the name;
fall back to the existing letter-hex when no mark exists. Compress tile padding one step.
2. **API key / Local model control**: rebuild as a CONTENT-SIZED 2-segment control (inline-flex,
auto width, filled active cell reading as a tab) — kill the full-width band with phantom
trailing cells/hex dividers (a11y: "empty trailing cells after 'Local model'").
3. Error banner: put the action IN the banner — "Fix it now" button (focuses the failing
tile's key input) instead of prose-only.
4. Show control: dock it INTO the section header row it modifies (flush right of the
"MODEL CONFIGURATION" SectionLabel line) — judges still read it as floating.
5. kw: when Fallback === Primary, the existing warning row stays but add a one-click
"Use a cheaper fallback" suggestion ONLY if a strictly cheaper model exists in the
catalog (real data, no invention).
## Lane B — workspace card v3.1: fixed-slot contract (5/5, floor surface 6.8)
Files: `apps/AllWorkspacesApp.tsx` (+test). Evidence: 132 pair + 140.
1. **Fixed slots, every card identical rows**: (1) identity row: hex avatar + name +
storage badge; (2) tag row ALWAYS present (group chip + 'Personal' scope; slug moves to
a hover/tooltip detail — kw+a11y both want raw slugs out of the resting card; when two
names collide show a subtle "duplicate name" pill instead of the slug); (3) preview
line: real summary/description or last-session title — WITHOUT the "Last:" prefix
(judges: debris) — quote-style it instead: '"What matters here now?" · 2w ago';
suppress the preview when the newest session title is the canned assistant greeting
("Hello! What can you help me with?" — template text, not user data; omit, never
paraphrase); (4) metrics footer: ⬡ memories · sessions · Open →.
2. **One live signal per card**: derive a stable per-workspace accent hue from the name
hash (same technique HexAvatar already uses — reuse its hue derivation) and paint a
2px top border band on the card in that hue at 40% opacity. Deterministic, data-free,
differentiates cards without fabrication.
3. Keep: persistent Open →, dark border step, min-h 132, whole-card click.
4. a11y: remove the duplicated affordance objection by keeping ONE visible Open → (footer)
— do not add more.
## Lane C — one chip grammar, app-wide (design HIGH + a11y + kw)
Files: `apps/extend/ExtensionCard.tsx`, `apps/MarketplaceApp.tsx`,
`apps/memory/MemoryTrustManage.tsx`, `apps/AgentsApp.tsx` (status chips).
1. Codify TWO chip species and apply everywhere in these files:
FILLED chip = category/type (surface-2 bg, text-muted, 11px);
OUTLINE chip = status (transparent bg, tone border+text: healthy/attention/risk/neutral).
2. NO sentence chips: "Works as connector, MCP server & skill" → three glyph+word chips
("connector" / "MCP" / "skill") sharing one tooltip. Style orphan plain-text tokens
("local registry") as the filled species.
3. Memory mono metadata row (M-382 · session handoff · 2026-06-24 · s2 · source: imported):
compress to icon+short label with tooltip carrying the full provenance (brand judge:
"transparency without terminal dump") — keep M-id visible (it is the correction handle).
4. Agents status chips: dot+label pattern with semantic tones (idle=neutral dot,
running=healthy, error=risk) + one contrast step (a11y).
## Lane D — light-mode mood + status-chrome tokens (brand HIGH + a11y HIGH)
Files: `index.css` (ONLY this lane), `os/StatusBar.tsx`, `os/AppShell.tsx` (wallpaper layer
if that's where the light hex opacity lives — verify), light logo asset wiring in StatusBar.
1. LIGHT hex-pattern presence up (~2 steps opacity) on large canvases + a faint warm honey
radial wash behind hero zones — light must stop reading as a faded copy (brand).
2. Light logo tile: the top-left logo is a dark square in light — use the light logo asset
(waggle-logo.png already imported for light in StatusBar — verify it actually renders;
the DESIGN judge sees a dark tile, so something is off) or wrap in a themed tile.
3. Light muted-text audit (a11y HIGH): agents taglines / memory mono meta / chat meta line —
darken the light --text-dim/--text-muted one step to clear 4.5:1 at 11-12px; verify with
contrast math in the lane notes (compute, don't eyeball).
4. Light status-bar chrome ('Solo plan', Ctrl K chip, breadcrumbs) one contrast step.
5. StatusBar model chip label: "New chats:" → "Default model:" (kw R11: self-evident beats
clever; tooltip already disambiguates the open thread).
## Lane E — mascot/asset consistency + chat composition (brand HIGH ×2, design MEDI)
Files: `apps/ChatApp.tsx` + chat message components (turn avatar), `apps/agents/*` (Editorial
Critic row emoji), `overlays/onboarding/WelcomeStep.tsx`, `overlays/LoginBriefing.tsx`.
1. **Purge platform emoji**: chat turn header bee (currently a low-res emoji/raster at
~20px) → the persona's flat-geometric PNG from assets/personas at 36-40px (crisp,
transparent); agents' Editorial Critic 🤖 → the persona bee (it's a custom agent —
use its persona avatar via getPersonaAvatar, fallback general-purpose).
2. Onboarding mascot: kill the square tile seam — render the transparent PNG bare
(no tile bg/border; keep the glow as drop-shadow); verify against ivory in light.
3. Chat opening composition: collapse the dead band above the first message (competitor:
pull the thread start up under the header) — check the thread container's top spacing.
4. LoginBriefing: suppress boilerplate workspace rows — a row whose summary is the CANNED
template line ("Everything you discuss in X stays in context…") carries no information;
omit those rows (template copy ≠ data; never omit rows with real content).
## Per-lane gate
Related vitest green + eslint; NO cross-lane files. Orchestrator: full web tsc + vitest after merge.

111
docs/ux-refactor/wave-T-spec-2026-07-06.md Normal file
View File

@@ -0,0 +1,111 @@
# Wave T — R13-V1 convergent fixes: interaction hygiene + the missing motion layer
R13-V1 (video-regime baseline): design 7.0 · kw 7.1 · competitor 7.0 · a11y 7.0 ·
brand 7.3 (min 7.0, avg 7.08). Five systemic gaps named by 4-5 of 5 judges — this
wave ships all five. Evidence: scratchpad/video-r13/evidence (sheets + keyframes).
Same vocabulary + honesty contract as waves P-S. Surgical; both themes; testids/aria
survive. NO cross-lane files. Per-lane gate: related vitest green + eslint on touched
files. Orchestrator runs full gates + re-capture + R14-V2 after merge.
Judges' shared bar: "one perceivable hover/focus tier on every interactive element,
answered within ~100-160ms; zero wrong-state flashes; zero loading lies."
## Lane A — boot choreography + briefing bloom (all 5 judges)
Files: `os/AppShell.tsx`, `hooks/useOnboarding.ts`, `os/overlays/LoginBriefing.tsx`,
the BootScreen component (locate via AppShell render path), `index.html`, tests.
1. **Wizard flash for returning users** (s01 t≈4.0-4.5s): localStorage empty until the
async `/api/onboarding/status` P4 branch resolves → wizard mounts ~1s before home.
Hold the BootScreen until onboarding status is KNOWN (sync localStorage hit OR the
status fetch settles; cap the hold ~1.5s then fall through so a dead endpoint can't
brick boot). The wizard must never paint for a user the server knows is onboarded.
2. **Briefing opens as a ~4s bare spinner, then content pops unstaged** (design: "it
deserves a progressive reveal, not a spinner-then-dump"): prefetch the briefing
payload during BootScreen (boot already runs ~4s — fire loadBriefing's fetch at boot
start, cache at adapter/module level). Where prefetch hasn't landed, render 2 skeleton
highlight cards + 2 skeleton workspace rows (correct heights, shimmer) — never a
centered spinner in an empty box. When data arrives, stagger the recall cards in
(the existing per-card motion delays already do this — verify they fire on data
arrival, not only on mount). Keep the errored slim-row path exactly as-is.
3. **Boot pre-paint white frame**: set a dark background on `<html>` in `index.html`
(inline early style) so pre-hydration frames are hive-dark, not white.
4. **BootScreen ignores theme** (a11y/brand): when stored theme is light, boot in the
light palette — no dark→light whiplash at home mount.
5. **Light "Start Working" CTA parity** (a11y HIGH): in light theme the primary CTA
renders washed pale-honey with light text (<4.5:1). Same emphasis tier both themes:
saturated honey fill + dark text. Compute contrast in lane notes.
## Lane B — marketplace: NL promise bridge + metadata budget + row hover (4 judges)
Files: `apps/MarketplaceApp.tsx`, `apps/extend/ExtensionCard.tsx`, tests.
1. **NL dead-end** (brand HIGH: "the exact moment the brand should feel magical says
no"): when live keyword filtering finds nothing AND the query looks like natural
language (≥3 words), the empty state must bridge to the promised semantic search:
"Press Enter — Waggle matches skills to this job" + run it on Enter (the semantic
path already exists behind the Search button — wire, don't invent). Also stop the
first-keystroke full-list flash (debounce the filter ~150ms).
2. Metadata budget (R12): dedupe the repeated connector chip; cap visible tags at
3 + "+N" overflow chip (tooltip lists the rest). Two chip species only (Wave S
grammar — verify, don't rebuild).
3. Row hover tier: rest flat → hover/focus-visible = one elevation step (existing
shadow token) + primary action gains full contrast. 120-160ms ease-out.
## Lane C — workspace cards: grammar close-out (judged 8.0/7.5 — small lane)
Files: `apps/AllWorkspacesApp.tsx`, tests.
1. One-slot-order grammar audit: every card renders identical slot order/alignment
(identity → tags → preview → metrics); reserve, don't collapse, missing slots.
2. Duplicate-name chip → keep the pill but move the slug disambiguation into its
tooltip (R12: raw slug = data debris).
3. Kebab menu: drop the full-page dim/blur when the card actions menu opens —
modal-grade dimming is for modal-grade interruptions (design, low).
## Lane D — memory: loading truth + tab cache + count landing (all 5 judges)
Files: `apps/memory/*` (its surfaces/nav/hooks only), tests.
1. **Kill the false zero** (a11y: "a trust surface must not display wrong data even
for 3 seconds"): the hero stat renders skeleton/em-dash until the real count
arrives — `0` is a VALUE, never a loading state. Audit every count on the surface.
2. **Cache tab state**: Trust ↔ Memories switches must not re-fetch + re-spin; keep
fetched lists in state/cache keyed by tab for the session (staleness fine — the
surface has explicit refresh affordances elsewhere).
3. **Count-up landing** (brand): when the hero count first arrives, land it with a
~600ms count-up + settle; confidence rings draw in staggered. Honor
prefers-reduced-motion (instant set, no animation).
4. Triple-nav collapse (R12): fold the weakest of the three stacked nav tiers into a
compact control row. Do NOT remove destinations — only chrome.
## Lane E — chat: the daily surface answers the cursor (all 5 judges)
Files: `apps/ChatApp.tsx` + chat message components, tests.
1. **Message hover actions visible**: the two ~2:1 ghost icons under assistant
messages → a proper action row (copy/retry, 3:1 rest, 4.5:1 hover, slide/fade
reveal 120-160ms) that ALSO reveals on :focus-within (keyboard parity). Persistent
low-opacity hint at rest so the affordance is discoverable without hover.
2. **Composer chip hover/press states**: each chip (persona/memory/mode/model) gets a
visible hover step + pressed state; the existing send-ignition stays.
3. Entry loading: replace the bare "Loading workspace…" text with the thread skeleton
(message-shaped placeholders, correct rhythm).
## Lane F — agents surface + the signature motion (all 5 judges; brand HIGH ×2)
Files: `apps/AgentsApp.tsx`, `apps/agents/*`,
NEW shared `components/ui/BeeLoader.tsx` (+ its test) — the ONLY new file this wave.
1. **Hover tier on bee cards + "Browse all 22" strip** (design: "65 seconds of
hovering, pixel-identical frames"): workspace-card grammar (elevation step + honey
top hairline + affordance strengthen), 120-160ms, focus-visible parity.
2. **The bees respond** (brand: "the product's soul never moves"): on card hover the
bee avatar gets a ~200ms character response — a 2-3° tilt + 2px lift of the PNG
(transform only, no layout shift), settle on leave. Honor prefers-reduced-motion.
3. **BeeLoader — one signature loader**: a small waggle-dance loader (the bee mark
tracing a figure-eight waggle path, CSS/SVG only, ~1.2s loop, honey on transparent)
as a drop-in replacement for generic arc spinners. Ship the component + use it for
the agents surface's own loading states. (Other surfaces adopt it next wave — no
cross-lane files.)
4. Dark agents search-input border (R12): visible `--line` border + focus ring,
consistent with marketplace's labeled search.
## Deferred (do not touch this wave)
Settings Show-containment + light input tokens (R12; settings judged 8.5 best-in-app),
www landing diagram (not in the judged journeys), memory row-action focus parity beyond
chat's pattern (ride next wave), theme-switch "atomicity" work beyond Lane A items 3-5
(the reload/white-flash/mixed-state evidence was a capture artifact — kit v2 fixed).
## Per-lane gate
Related vitest green + eslint; NO cross-lane files; lane notes list files touched +
contrast math where required. Orchestrator after merge: web tsc, server tsc, full
vitest, browser QA pass, then R14-V2 capture (kit v2) + judge.

103
docs/ux-refactor/wave-U-spec-2026-07-06.md Normal file
View File

@@ -0,0 +1,103 @@
# Wave U — R14-V2 convergent fixes: state honesty round 2 + felt interaction
R14-V2: design 7.5 · kw 7.4 · competitor 7.3 · a11y 7.2 · brand 7.5 (min 7.2, avg
7.38; V1 was 7.0/7.08 — the regime responds to fixes). This wave ships the seven
convergent asks. Same vocabulary + honesty contract as waves P-T. Surgical; both
themes; testids/aria survive. NO cross-lane files. Per-lane gate: related vitest
green + eslint on touched files. Orchestrator: full gates + kit-v3 capture + R15-V3.
Verification context (read before "re-fixing" anything): the agents hover tier, bee
response, chat action-row reveal, and marketplace NL bridge ALL work in the live
product — R13/R14 capture scripts missed them (now fixed in kit v3). Wave U items
below are the judges' ESCALATIONS, not regressions. Do not rebuild what Wave T built
— strengthen exactly what each item names.
## Lane A — workspace shelf loading truth (5/5 judges, HIGH)
Files: `apps/AllWorkspacesApp.tsx` (+test).
1. The shelf renders "No workspaces yet — Create your first workspace" for ~0.5s
before data lands. Loading, empty, and error are THREE distinct states: while the
workspace query is unresolved, render 3 skeleton cards matching the fixed-slot
card geometry (min-h 132, identity/tag/preview/metrics slot shimmer); the empty
state (with its Create CTA) may render ONLY after a resolved, genuinely-empty
answer. Follow the memory surface's cache pattern (memory-list-cache.ts): seed
from session cache so a revisit shows last-known cards instantly.
2. Card kebab + row affordances: visible at rest at low opacity (the chat action-row
pattern from Wave T Lane E: rest ~0.6 → hover/focus-within 1.0) — hover-only
reveal excludes keyboard/touch (a11y). Keep the existing hover tier as-is.
## Lane B — briefing interruption discipline (4/5 judges, HIGH)
Files: `os/AppShell.tsx` (briefing gating only), `os/overlays/LoginBriefing.tsx`
(numbers reconciliation only), tests.
1. The "Catching you up" modal must fire ONLY on true session start AND only when
Home is the landing surface. In-session navigation to Home (s02: Settings→Home)
must never pop it. Gate on both (a) once per app session (in-memory flag, not
localStorage — a new session should show it again) and (b) the first mounted
surface being Home. When suppressed by (b), do NOT drop the content — the home
hero already tells the story (judges call the modal+hero a "double catch-up").
2. Numbers reconciliation: the modal says "2 workspaces" while the home hero says
"6 workspaces waiting" — the modal filters test/canned workspaces, the hero
doesn't (or vice versa). Find both sources, make them share ONE filtered count.
Never present two different truths about the same store in the same viewport.
## Lane C — marketplace NL: run the promise (4/5 judges)
Files: `apps/MarketplaceApp.tsx`, tests (+ the search box component if it lives in
a marketplace-owned file — verify with grep; if the search box is shared outside
marketplace, wire from MarketplaceApp side only).
1. When the debounced query is natural-language (≥3 words) and name-filtering finds
nothing: AUTO-RUN the semantic skill-match (the Search-button path) after a
~600ms settle, rendering ranked results inline under a quiet "Matched to your
request" section label. No dead-end frame: while matching, show the BeeLoader
(components/ui/BeeLoader.tsx) + "Matching skills to this job…".
2. Restyle the no-match composition: kill the gray "No job matches … by name" line
as the lead voice. If semantic matching also finds nothing, show 2-3 nearest
catalog entries ("Closest in the catalog") + the Free Zone escape as a real
button, not a text link.
3. Keep the existing filter behavior for 1-2 word queries exactly as-is.
## Lane D — boot warm-start (competitor HIGH)
Files: `os/AppShell.tsx` (boot hold logic), BootScreen component, tests.
1. Returning users wait ~3.5s of branded boot before every session vs ~1s
time-to-content on Claude/ChatGPT. The boot screen's minimum display time should
be perceptual, not fixed: when the shell's data dependencies (onboarding known +
briefing prefetch fired + workspace store warm) resolve early, exit boot at
~800ms-1s (enough for the brand moment, no dead air). Keep the current longer
hold ONLY while dependencies are genuinely unresolved. Do NOT remove the boot
screen or its choreography — shorten its floor.
2. Verify the exit is choreographed (existing fade), not a hard cut, at the shorter
floor. Reduced-motion: instant swap stays.
## Lane E — a11y text floor + micro-motion tier (a11y HIGH + competitor)
Files: `apps/agents/SuggestedAgentCards.tsx` (text tokens only), `apps/SettingsApp.tsx`
/ `model-gate/ModelGate.tsx` (light amber tier labels only), `apps/memory/MemoryCenterTab.tsx`
+ `apps/memory/MemoryTrustManage.tsx` (tab-swap motion + loading skeleton only), tests.
NOTE: this lane touches settings + memory files that no other Wave U lane touches —
verify with git status before editing that no other lane claimed them.
1. Agent-card second lines (the whisper tier) probe ~2.3:1 in dark — lift informative
text to ≥4.5:1 both themes (token step, not new colors). Compute in lane notes.
2. Light-theme amber tier labels in Model Pilot ("Primary/Fallback/Budget Saver")
probe ~3.1:1 — one token step darker in light. Compute in lane notes.
3. Memory "Loading memories…" generic spinner → skeleton rows (the surface's own row
heights) with BeeLoader only if a full-surface wait is unavoidable.
4. One micro-motion tier on panel swaps: Memory Trust↔Memories tab change gets a
~150ms fade-slide (motion-safe gated); same token timing as the Wave T hover tier.
Do NOT add route-level transitions (out of scope).
## Lane F — chat action row: Claude-level presence (4/5 judges, medium but daily)
Files: `apps/ChatApp.tsx` + the message action-row component, tests.
1. The Wave T reveal works (verified) but under-reads: raise rest opacity one step
(0.6 → 0.75), bump icon size 14→16px and row height accordingly, and give the
revealed state a surface (subtle --surface-2 pill behind the icons) so the row
reads as a toolbar, not floating glyphs. Keep the 150ms reveal + focus-within
parity exactly as shipped.
2. Send-button micro-pulse when it fills honey (brand ask): one ~200ms scale pulse
on the empty→ready transition, motion-safe gated, once per transition (no loop).
## Deferred
Memories-tab composition depth (needs product thought, not polish); route-level
shared-element transitions; onboarding chip-style unification (design minor);
BeeLoader adoption beyond marketplace/memory loading states.
## Per-lane gate
Related vitest green + eslint; NO cross-lane files; contrast math in lane notes
where demanded. Orchestrator after merge: web tsc + full vitest + browser QA +
kit-v3 capture + R15-V3 judge round.

92
docs/ux-refactor/wave-V-spec-2026-07-06.md Normal file
View File

@@ -0,0 +1,92 @@
# Wave V — R15-V3 convergent fixes: memory parity, single-truth banners, motion tier 2
R15-V3: design 7.5 · kw 7.8 · competitor 7.6 · a11y 7.3 · brand 7.4 (min 7.3, avg
7.52; regime trajectory 7.08 → 7.38 → 7.52). Same vocabulary + honesty contract as
waves P-U. Surgical; both themes; testids/aria survive. NO cross-lane files.
Per-lane gate: related vitest green + eslint on touched files.
Already fixed inline (do NOT redo): s03 empty-flash root cause — ShellContext now
forwards `workspacesLoading`; the shelf gates its empty state on it (`32507dd9`).
## Lane A — memory surface to hero parity (5/5 judges)
Files: `apps/memory/*` (MemoryTrustManage.tsx, MemoryCenterTab.tsx, memory-list-cache.ts), tests.
1. Hero count NEVER paints 0 mid-load, including tab RETURNS: gate on cache — show
the cached last-known count (or skeleton digit when truly unknown), never a
transient 0. The count-up animation runs ONCE per app session (module-level
flag, mirrors shelfSessionResolved), then settles instantly on later mounts.
2. Memories tab to Trust-hero standard: a designed container (result-count header
row "448 memories · filtered by X", aligned filter chips, consistent row grid) —
kill the "one card floating in a black void" composition. While the list loads:
skeleton rows (existing pattern), or when a filter pins results, an explicit
state label ("Showing 1 pinned result — loading the rest…").
3. Keep all existing behavior (cache, erase flows, testids) intact.
## Lane B — settings verdict single-truth (kw + competitor HIGH)
Files: `apps/SettingsApp.tsx`, `model-gate/ModelGate.tsx` (verdict/banner logic only), tests.
1. The status banner currently flips "No working model" → "you're ready to go" →
provider error within ~1s as async probes land. Introduce ONE resolution phase:
while any provider probe is in flight show a neutral "Checking your models…"
banner (BeeLoader mark optional), then render EXACTLY ONE final verdict. No
intermediate verdict may paint.
2. Do not slow the happy path: if all probes resolve <300ms, skip the checking
state entirely (verdict paints once, immediately).
## Lane C — motion tier 2: cards answer with lift + bloom (design + brand)
Files: `apps/AllWorkspacesApp.tsx`, `apps/agents/SuggestedAgentCards.tsx`,
`apps/extend/ExtensionCard.tsx`, tests.
1. Hover/focus-visible on workspace cards, bee cards, marketplace rows adds a
subtle translate lift (2-4px) + a honey glow bloom (shadow token step) ON TOP of
the existing ring/border tier. 150-200ms ease-out, motion-safe gated (reduced
motion keeps the color tier). Use existing --shadow-honey / timing tokens; if a
token is missing, note it — don't invent values inline.
2. Specialists strip: show the → arrow at rest (dim), brighten on hover (a11y
rest-hint ask). Audit these three files for other hover-only reveals; give each
a rest-state hint or focus-visible parity.
## Lane D — signature theme crossfade + route settle (brand HIGH)
Files: `providers/ThemeProvider.tsx` (or wherever the theme stamp lives — verify),
`index.css` (transition rules only), tests.
1. Theme switch: a 300-400ms warm crossfade ("sunset over the hive") instead of an
instant token swap — CSS transition on background/color tokens at the root, NOT
a JS animation; guard against transitioning layout properties (colors/opacity
only, no width/position). motion-safe gated; reduced-motion keeps the instant swap.
2. Verify the s02 Settings→Home gap: the route lands on Home whose shelf section
skeletons paint inside the FULL page scaffold (sidebar+header persist — they
should already; if a blank frame exists outside the shelf, find and close it).
3. Do NOT add route-level shared-element transitions (out of scope).
## Lane E — loading vocabulary close-out (design + kw)
Files: `os/WorkspaceDesktopApp.tsx` (entry loader only), `apps/MarketplaceApp.tsx` +
`apps/extend/AgentSearchBox.tsx` (debounce presentation only), tests.
1. Chat/workspace cold entry: replace the bare centered "Loading workspace…" text
with a layout-preserving skeleton (sidebar/header persist; thread-shaped
placeholders in the content area — reuse the WorkspaceBriefing skeleton idiom).
2. Marketplace: during the search debounce, keep prior results visible at reduced
opacity (dimmed, aria-busy) instead of collapsing the list between keystrokes;
stabilize the MATCHES section so it doesn't mount/unmount across adjacent
debounce ticks (reserve its container once shown until the query clears).
## Lane F — a11y utility-text sweep + chip semantics (a11y HIGH)
Files: `os/StatusBar.tsx`, `os/Sidebar.tsx`, `overlays/onboarding/WelcomeStep.tsx` +
the wizard step shell (mascot carry + step transition), `apps/ChatApp.tsx`
(aria/tooltips ONLY — no visual changes), tests.
1. AA sweep at 11-12px in BOTH themes (compute, don't eyeball; math in lane notes):
"Skip setup", "Don't show again", statusbar plan/search/date chrome, sidebar
section labels (PINNED · POWER TOOLS / GENERAL), marketplace suggestion pills
(if that token lives in a shared tier, fix the token, else note it).
2. Composer chips + message-action icons: aria-label + title tooltips on every
control (several have neither); no visual changes in this lane.
3. Onboarding: keep the (breathing) mascot as the persistent step header across
wizard steps (it currently swaps to a generic glyph after Welcome); ease the
step transition (slide/fade ~200ms, motion-safe). Replace the native OS
<select> for Industry with the app's themed select primitive (grep for an
existing themed select/dropdown — one exists in settings; reuse, don't build).
## Deferred
Briefing-modal row streaming (prefetch already covers the common path); route
shared-element transitions; marketplace row typography tier-up; s06 panel-swap
choreography (surface already at 8.5).
## Per-lane gate
Related vitest green + eslint on touched files; contrast math where demanded.
Orchestrator: web tsc + apps/web vitest suite + browser smoke + R16-V4 capture/judge.

80
docs/ux-refactor/wave-W-spec-2026-07-07.md Normal file
View File

@@ -0,0 +1,80 @@
# Wave W — R17-V5 convergent fixes: the motion identity wave
R17-V5: design 7.7 · kw 7.7 · competitor 7.6 · a11y 7.5 · brand 7.9 (min 7.5, avg
7.68 — regime high). Same vocabulary + honesty contract as waves P-V. Surgical;
both themes; testids/aria survive; ALL new animation motion-safe gated. NO
cross-lane files. Per-lane gate: related vitest green + eslint on touched files.
Design judge's thesis: "content lands as monolithic blocks after skeletons — a
staggered entrance (~40ms/card, 8px rise+fade, 300-500ms total) is the single
change that moves this from 'CSS transitions' to 'has a motion identity'."
The memory surface already ships a `card-enter` keyframe with 40ms stagger
(Wave V Lane A) — that is the house pattern; REUSE its keyframe/timing, don't
invent a second grammar.
## Lane A — entrance choreography: grids (design HIGH)
Files: `apps/AllWorkspacesApp.tsx`, `apps/agents/SuggestedAgentCards.tsx`, tests.
1. When the workspace grid resolves from skeleton→content, cards enter staggered:
~40ms apart, 8px rise + fade, ease-out, total ≤500ms. Reuse the memory
surface's `card-enter` animation (grep index.css). Runs ONCE per surface visit
(not on every filter keystroke — filtering re-sorts must NOT re-animate).
2. Same treatment for the six suggested-agent bee cards and the specialists strip
(strip after the cards, one beat later).
3. Reduced motion: instant, no rise/fade. Existing hover tiers untouched.
## Lane B — briefing recall cards + actions menu craft (design HIGH+MEDIUM)
Files: `os/overlays/LoginBriefing.tsx`, `os/WorkspaceActionsMenu.tsx`, tests.
1. The briefing modal opens fully composed when prefetched (the per-card motion
delays only fire on slow loads). Re-key the recall cards + workspace rows so
the stagger runs on EVERY modal open (base delay after modal mount, ~80ms/item,
8px rise+fade) — the product's hero moment deserves an entrance beat that
survives 2fps.
2. Actions menu (workspace card '…'): icons per action, roomier padding (match
the marketplace row density), destructive action visually separated, and a
150ms scale(0.96→1)/fade entrance transform-originating from the trigger
corner. KEEP the Escape-returns-focus behavior exactly (judges praised it).
## Lane C — marketplace matching skeletons + results density (design HIGH)
Files: `apps/MarketplaceApp.tsx`, `apps/extend/AgentSearchBox.tsx`, tests.
1. Replace the stale-dim block (data-testid nl-stale-dim) with 3 purpose-built
result-row skeletons under the "Matching skills to this job…" status —
row-shaped (icon square + two text lines + chip stubs), animate-pulse,
motion-reduce:animate-none. Kill the dimmed wrong-content moment.
2. Results view density: when the semantic match returns ≤3 hits, append a quiet
"More from the catalog" rail (nearestCatalog already exists — reuse) so a
2-hit answer doesn't strand the user in dark space.
## Lane D — memory counter 0-frame + Memories tab landing (design+kw)
Files: `apps/memory/MemoryTrustManage.tsx`, `apps/memory/MemoryCenterTab.tsx`, tests.
1. The once-per-session count-up starts at 0 — a 2fps frame catches "0 Memories"
above rendered rows ("reads as a data bug"). Start the animated display at
ceil(15% of target) so no frame ever shows 0/near-0 with data present; keep
the ~600ms ease and the once-per-session flag.
2. Memories tab lands on the full recent list (density), with the curated view as
a labeled filter chip instead of the default — kill "one card in a dark
field". Keep the result-count header from Wave V. If the curated default is
load-bearing somewhere else, say so in notes instead of forcing it.
## Lane E — chat streaming proof + onboarding beats (design HIGH + low)
Files: `apps/ChatApp.tsx` (streaming visuals only — verify what exists first),
`overlays/onboarding/WelcomeStep.tsx` + wizard step shell (glow + slide), tests.
1. Verify the send→streaming→settle visual arc: streaming indicator (typing
cursor / bee shimmer) while tokens arrive, settle beat when done. If it
already exists, polish only what reads poorly on video (indicator too subtle
→ one visible tier); if absent, add a minimal honey typing-cursor pulse.
2. Onboarding: amplify the mascot glow breathing to a ~3s cycle with a visibly
larger radius/opacity swing (still tasteful; motion-safe); directional slide
(~200ms) welcome→step-1 for spatial continuity.
## Kit v5 (orchestrator, not a lane)
s04 gains a send→streaming→settle beat: type the question, SEND it, hold ~8s
while the (echo-provider) response streams, then settle. Dev-store side effect
accepted (research-hub already carries test messages).
## Deferred
Shared-element continuity briefing→home (needs route-transition infra);
hover-amplitude unification pass; s06 panel-swap choreography (8.2 already).
## Per-lane gate
Related vitest green + eslint; contrast math N/A this wave (no text tokens);
every new animation motion-safe gated. Orchestrator: tsc + suite + R18-V6.

91
docs/ux-refactor/wave-X-spec-2026-07-07.md Normal file
View File

@@ -0,0 +1,91 @@
# Wave X — R18-V6 verified-real defects (NOT a motion-chase wave)
R18-V6: design 7.8 · kw 7.7 · competitor 7.7 · a11y 7.5 · brand 7.8 (min 7.5, avg
7.70). Verdict: "clearly beats Claude, ChatGPT, Codex." Five surfaces at 8.2-8.3.
This wave ships ONLY defects verified live by the orchestrator — not another
motion-amplitude pass (three already shipped: hover tiers T/U, lift+bloom V,
entrance stagger W; a fourth is diminishing-returns whack-a-mole). The one HIGH ask
that is NOT a polish wave — shared-element route transitions — is escalated to the
founder decision point (plan doc §Plateau-2), not attempted here.
Same contract as P-W. Surgical; both themes; testids/aria survive; motion-safe gates.
NO cross-lane files. Per-lane gate: related vitest green + eslint on touched files.
## Lane A — memory hero count-up contradiction (self-inflicted W regression, HIGH)
Files: `apps/memory/MemoryTrustManage.tsx`, tests.
Root cause (verified live + in code, MemoryTrustManage HeroCount L153-177): Wave W
Lane D floored the count-up at `ceil(total*0.15)` (=68 for a 449 hive) to avoid a "0"
frame, but the sub-stat chips ("445 to review", "399 stale") render their true values
immediately — so for ~600ms the hero shows a number BELOW its own sub-stats. A judge
caught "68 Memories" over "445 to review" and read it as a data bug.
1. Keep the felt count-up, kill the contradiction: hold the sub-stat chips (to-review
/ stale / high-confidence / fresh) in their skeleton until the hero count-up
SETTLES, then fade them in (a nice stagger — total lands, breakdown follows). The
hero total must never be visibly less than a rendered sub-stat. Reduced motion:
everything instant, no floor, no stagger.
2. Scope-label clarity: the hero says "N Memories in this hive" (449, current mind)
while the topbar shows 553 "all minds" — legitimately different scopes but the
delta reads as drift. Add a quiet scope qualifier so the two numbers are
self-explaining (e.g. hero stays "in this hive"; if a cross-mind total shows
anywhere on this surface, label it "across all minds"). Do not fabricate; use the
real scope the data already carries.
## Lane B — dark-theme secondary-text AA sweep (a11y HIGH)
Files: `apps/memory/*` (M-id/tag/meta rows), `os/StatusBar.tsx` (metadata chips),
`apps/AllWorkspacesApp.tsx` (card "N memories · N sessions · timestamp"), tests.
NOTE: Lane A also touches MemoryTrustManage — Lane B takes memory ROW metadata
(MemoryCenterTab / memory row components), Lane A takes the HERO. Verify no overlap
in the same file region; if a memory file is contested, Lane A wins that file and
Lane B notes the deferred lines. Prefer touching MemoryCenterTab + the row component,
not MemoryTrustManage.
1. Raise dark-theme secondary/metadata text to ≥4.5:1: memory-row IDs/tags (M-531),
provenance meta, workspace card meta line, statusbar chips. Compute each in lane
notes (token step, not new colors — most are --text-dim/--text-muted usages that
pass on --bg but fail on --bg-2/--surface-2; fix the USAGE, not the global token,
to avoid cross-surface blast radius — same discipline as Wave V Lane F).
2. Do NOT touch light theme (it already nails this per judges) unless a shared token
forces it — if so, note the light delta and re-verify light math.
## Lane C — micro-label legibility + unselected chip contrast (design MEDIUM + a11y HIGH)
Files: `components/os/warm/*` (SectionLabel / eyebrow primitive — grep for it),
`overlays/onboarding/*` (unselected work-type/team/help chips), tests.
1. The eyebrow micro-labels ("PINNED · POWER TOOLS" 9.5px/1.33px tracking, "WHILE YOU
SLEPT", "TRUST · INSPECT · CORRECT · FORGET") read as garbled at real size. Bump
the SectionLabel family to ≥10.5px and cut letter-spacing one step (heavy tracking
at tiny size is the legibility killer); verify the eyebrow still reads as an
eyebrow (uppercase, muted) not a heading. One primitive change propagates to all.
2. Unselected onboarding chips: raise their rest contrast so choices are legible
BEFORE selection (selected honey chips are fine; the unselected state fails). AA
math in lane notes.
## Lane D — hover overshoot + marketplace name humanization (competitor MEDIUM + low)
Files: `apps/AllWorkspacesApp.tsx` (hover timing only — coordinate w/ Lane B's
meta-text edit in the same file: Lane D owns the hover transition classes, Lane B owns
the meta-row text color; disjoint lines, but BOTH must land — orchestrator applies
Lane B first then Lane D rebases), `apps/agents/SuggestedAgentCards.tsx`,
`apps/extend/ExtensionCard.tsx` (hover), `lib/extension-catalog.ts` (name display), tests.
NOTE: AllWorkspacesApp is shared by Lanes A(no)/B/D — B=meta text color, D=hover
timing. If the executor can't guarantee disjoint regions, Lane D defers the
AllWorkspacesApp hover to notes and does agents+marketplace only. Flag it.
1. Give card/chip hover a crisper eased motion: 120-160ms with a slight scale
overshoot (1.0→1.02→1.0 settle) on top of the existing lift+bloom. Motion-safe
gated. This is the competitor's specific ask; keep it TASTEFUL (small overshoot,
not bouncy).
2. Marketplace result-name humanization: auto-generated names like
"awesome-claude-plugin-chatDeny-slides-creator" undercut the authored feel. Add a
display-name humanizer (strip "awesome-"/"-plugin" noise, title-case, collapse
dashes) applied at RENDER only (never mutate the id/install target). Pure function
+ unit test; leave the real id intact for install.
## Deferred to founder decision (NOT this wave)
- Shared-element / route-transition motion system (design+competitor HIGH) — a
structural framer-motion arc across react-router route changes, not a polish wave.
- Streaming token-caret "premium feel" — the dev echo provider returns complete
blocks, so real token streaming can't be shown without a live provider; this is a
capture/infra limit, flagged not faked.
- Ambient idle micro-life on the home hex-glow (brand HIGH) — net-new motion system.
## Per-lane gate
Related vitest green + eslint; contrast math in lane notes where demanded; every new
animation motion-safe gated. Orchestrator: tsc + suite + R19-V7 + decision-point log.