187 lines
13 KiB
Markdown
187 lines
13 KiB
Markdown
# 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.
|