# 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.