moving

docs/plans/UX-NORTHSTAR-2026-06-13.md

@@ -0,0 +1,117 @@
+# UX North Star — Competitive Position + Refactor Plan (2026-06-13)
+
+Founder directive: analyse the competition (Claude Cowork, OpenClaw/Hermes, Codex,
+Claude Code) and refactor Waggle to be best-in-class using its advantages. Concrete
+defect named: **manipulating workspaces is not possible**. Mental model to land:
+**one project / area of life = one workspace**.
+
+---
+
+## 1. Competitive teardown (what each does best, what Waggle takes)
+
+### Claude Cowork (Anthropic)
+- **Best at:** outcome-framing. Work is a *task you delegate*, not a chat. Results are
+  artifacts (files, decks, docs) you can open, not transcripts you scroll. Zero-jargon
+  UI for non-technical users; parallel tasks with calm progress surfaces.
+- **Weak vs us:** no persistent cross-session memory substrate; cloud-only; no
+  sovereignty story; no multi-workspace "second brain" accumulation.
+- **Take:** artifact-first results, delegate-and-walk-away framing, calm progress.
+
+### Claude Code (Anthropic)
+- **Best at:** power growth curve — skills, hooks, MCP, subagents compose; trust
+  through verification (shows its work, runs gates). Session→memory continuity via
+  CLAUDE.md/memory is *manual* though.
+- **Weak vs us:** terminal-first, engineer-only; memory is files the user curates.
+- **Take:** verification-before-done as UX (show receipts), capability composition.
+
+### Codex (OpenAI)
+- **Best at:** background parallelism — fire N tasks, each in a sandbox, review diffs
+  async. Strong "work happens while you're away" loop (the #1 retention loop in
+  agentic products).
+- **Weak vs us:** PR/repo-centric, engineer-only, no memory between tasks.
+- **Take:** the away-loop — "what got done while you were gone" must be the first
+  thing every return-visit shows (we have LoginBriefing/overnight — deepen it).
+
+### OpenClaw / Hermes agent
+- **Best at:** proactivity + presence — heartbeat check-ins, messaging-native
+  (lives where you already are), personality, viral delight. Feels *alive*.
+- **Weak vs us:** chaotic setup, no governance/audit, single-mind (no workspace
+  isolation), safety posture.
+- **Take:** proactive heartbeat moments (digest, "I noticed X"), personality
+  without cosplay; we already have isolation + governance they can't match.
+
+## 2. Waggle's structural advantages (the moat to amplify)
+1. **Persistent per-workspace memory** (mind substrate, SOTA-benchmarked) — nobody
+   else has workspace-isolated, locally-owned, growing memory.
+2. **Local-first sovereignty** (Tauri binary, your disk, KVARK story).
+3. **Non-technical OS metaphor** — dock, workspaces, personas; Cowork is the only
+   competitor even trying for this audience.
+4. **Governance/audit/EU-AI-Act** posture — enterprise-credible.
+5. **Harvest** — import your ChatGPT/Claude/Gemini history: instant moat-fill.
+
+## 3. Gap map (verified against code 2026-06-13)
+
+| # | Gap | Evidence | Severity |
+|---|-----|----------|----------|
+| G1 | **Workspace manipulation impossible from UI** — no rename/archive/delete/icon anywhere. Switcher is select-only; Home cards have no menu; Desktop header shows status but can't change it | `WorkspaceSwitcher.tsx` (list-only), grep: zero rename/delete affordances for workspaces vs full sets for files/artifacts/memories/agents | **P0** |
+| G2 | Server PUT/PATCH `/api/workspaces/:id` body types omit `status`/`description` — archive inexpressible over API despite data model + manager support | `routes/workspaces.ts:755,782` vs `workspace-manager.ts:66` | **P0** |
+| G3 | `deleteWorkspace` orphaned — exists in `useWorkspaces` but not exposed via ShellContext, no UI | `useWorkspaces.ts:60`, `ShellContext.tsx` | **P0** |
+| G4 | Hook error-swallowing: delete/patch apply optimistic state even on failure | `useWorkspaces.ts:61,71` | P0 (rides along) |
+| G5 | "One project/area = one workspace" mental model not stated anywhere in UI copy | switcher/create dialog copy | P1 |
+| G6 | No workspace reorder/pin; no archived section | data model has no `order`; switcher flat | P1 |
+| G7 | Archived workspaces (once settable) would still show everywhere — list consumers don't filter status | switcher, home briefing | P0 (ships with G1) |
+| G8 | Tasks CRUD adapter gap — server board (routes/tasks.ts) had full CRUD, zero adapter methods, read-only tab | verified | P1 |
+| G9 | /api/evolution/run hang (carried from 0613 S1) | prior handoff | P2 (separate arc) |
+| ~~G10~~ | ~~MCP logs disabled / ChatHost leak~~ — recon claims, did NOT verify against code (no disabled logs affordance in MCPHubApp; no interval/listener in ChatHost) | grep 2026-06-13 | dropped |
+
+## 4. Plan
+
+### Phase A — Workspace manipulation, end-to-end (P0, this session)
+1. **Server:** PUT+PATCH accept `status` (validated enum) + `description`; tests.
+2. **Adapter + hook:** widen `patchWorkspace` to `status|description|icon`; expose
+   `deleteWorkspace` via ShellContext; fix error-swallowing (throw → caller toasts,
+   revert optimistic state on failure).
+3. **`WorkspaceActionsMenu`** (new, reusable kebab): Rename · Archive/Restore ·
+   Export briefing · Delete (type-name-to-confirm + "memory will be permanently
+   deleted" warning). Mounted in: Home workspace cards, WorkspaceSwitcher rows,
+   Workspace Desktop header.
+4. **Switcher upgrade:** "+ New workspace" footer (opens existing CreateWorkspaceDialog),
+   archived section (collapsed), mental-model subtitle copy.
+5. **Filter `status==='archived'`** from: switcher main list, Ctrl+Tab cycle, home
+   briefing recents (server-side), dashboard grid.
+6. **Tests:** server route status round-trip + 400 invalid; FE menu actions.
+
+### Phase B — Mental model + away-loop deepening (P1, next)
+- Creation flow copy: "What project or area is this for?" — name suggestions.
+- Workspace cards show living state (memory growth since last visit).
+- Return-visit: LoginBriefing leads with "while you were away" outcomes (Codex loop).
+
+### Phase C — Delight/proactive (P2, later)
+- Heartbeat digest (OpenClaw take) via existing automations.
+- Artifact-first result rendering in chat (Cowork take).
+- G8 items; G9 evolution hang (separate debug arc).
+
+---
+## 5. Shipped this session (2026-06-13 S2)
+
+| Commit | What |
+|---|---|
+| `1b8948d` | Phase A complete: G1-G4+G7 — WorkspaceActionsMenu (rename / archive·restore / export / type-to-confirm delete) on Home cards + switcher rows + Desktop header; server status/description on PUT+PATCH (validated) + PATCH audit parity; deleteWorkspace exposed through ShellContext; error-honest hooks; switcher + New workspace, Archived section, mental-model copy |
+| `c7e85a3` | Live-smoke fixes: portal menu/dialogs out of transformed ancestors (archived-row menu was off-viewport); CreateWorkspaceDialog AnimatePresence unkeyed-children React error storm (pre-existing) |
+| (3rd) | Phase B: G8 real task board in Desktop Tasks tab (server CRUD was UI-orphaned — add / cycle status / delete + memory signals); G5 creation copy "What project or area is this for?"; toStateItemViews key-collision fix (pre-existing live React errors) |
+
+| (4th) | Phase C2: artifact-first chat — completed write_file/edit_file blocks render as openable artifact cards (icon + name + Open in Files); AppDeepLink gains `path`; FilesApp consumes it (navigate + select + preview). C1 heartbeat digest verified ALREADY SHIPPED (setup-crons + proactive-handlers → notification eventBus → Home "Up next") |
+
+All flows live-verified in the running app (full lifecycle + task persistence,
+0 console errors). Gates: FE 964/964, server-local 931/931 + 9 lifecycle, tsc 0+0, lint clean.
+
+**Residuals:** G6 reorder/pin (P1, needs an `order` field — defer until demand);
+G9 evolution-run hang (separate debug arc); Phase B item "away-loop deepening"
+largely pre-existing (LoginBriefing already leads with away-summary). Phase C
+artifact card: live render against a REAL agent file-write not yet observed
+(historical sessions had no persisted tool blocks) — covered by 8 unit tests
+on the exact BlockRenderer path; worth one glance during the next real agent run.
+
+*Verified file evidence in section 3; recon agents' raw reports superseded by direct
+reads (two of their "CRITICAL missing screens" were stale-doc artifacts — Workspace
+Desktop and Artifact Center both exist and are routed).*