waggle-os/docs/superpowers/specs/2026-05-23-waggle-os-ux-design.md

# Waggle OS — UX Design v1

**Date:** 2026-05-23
**Status:** Brainstorm output. Vision spec. Pick what to ship, defer the rest.
**Anchor metaphor:** Refined Desktop OS (A) with Honeycomb grafts (B) where signal-flow / cells / hive-amber tell the story better than a list or grid.
**Inputs:** existing UI surface (24 apps + 15 overlays in `apps/web/src/components/os/`), Hive DS tokens (`honey #e5a000` / `hive-950 #08090c` / `accent #a78bfa`), 8-cluster brainstorm + metaphor confirmation 2026-05-23.

> Effort tiers used below: **S** = ≤3 days, **M** = ≤2 weeks, **L** = multi-week. Tiers are best-guess and assume one focused engineer + Marko driving design review.

---

## 0. The anchor metaphor (and what it isn't)

Waggle stays a **desktop OS** in chrome: top status bar, bottom dock, free-floating `AppWindow` instances, overlays as modals/sheets. The familiar mental model is preserved (no learning curve) and the existing six months of `Desktop.tsx` / `Dock.tsx` / `AppWindow.tsx` investment is preserved.

The **honeycomb** is grafted in eight specific places — where the visual metaphor tells the story better than its alternative:

| # | Graft | Where it lives | Why hex beats the alternative |
|---|---|---|---|
| 1 | Dock items as hex tiles | `Dock.tsx` | A live "bee tile that glows when an agent is dancing" is the Waggle brand. Drop-in skin. |
| 2 | Status-bar crew presence | `StatusBar.tsx` | Tiny hex avatars showing who's working RIGHT NOW. Click → jump-to-window. |
| 3 | WaggleDance as literal honeycomb | `WaggleDanceApp.tsx` | Signal flow ON THE EDGES is the original honeybee dance — what was the metaphor *for* in the first place. |
| 4 | Mission Control hex grid | `MissionControlApp.tsx` | Agents-as-cells, glow=working, hover=status. Beats a list of "agent #3 / agent #7". |
| 5 | Spawn-agent persona tiles | `SpawnAgentDialog.tsx` / `PersonaSwitcher.tsx` | Persona = a "role-cell." Tile feel works. |
| 6 | MCP catalog as hex grid | `MarketplaceApp.tsx` / `connectors/BrandTile.tsx` | Connectors are nodes in a graph the user is building. Hex grid > rectangular tile grid. |
| 7 | Memory peripheral inspector | New right-rail in `ChatApp.tsx` | Hex mini-graph of what was recalled for this turn. "Why did I get this answer?" answerable at a glance. |
| 8 | Honey-amber "active" accent across the OS | `waggle-theme.css` | Universal: `honey` = live/working, `violet` = memory-touched, neutral = idle. Color semantics unified. |

**Stays as plain Desktop:** free-floating windows (parallelism preserved), `AppWindow` chrome, dialogs as dialogs, settings as a form. The OS does not force-cell everything — it cells the things **about agents and signal**, which is where the metaphor earns rent.

---

## 1. Spatial chrome & window choreography

**Today (in `components/os/`):** `Desktop.tsx` (551 LOC), `Dock.tsx` (170 LOC), `DockTray.tsx`, `AppWindow.tsx`, `BootScreen.tsx`, `StatusBar.tsx`, `WorkspaceBriefing.tsx`, `ContextMenu.tsx`. Free-floating windows with z-order management. Bottom dock with app icons. Top status bar.

**What's missing for "OS-feel":**
- No **snap zones / window tiling** — a real OS lets you halve, quadrant, full-screen via drag or keyboard.
- No **multi-monitor** support (Tauri supports it; the web shell doesn't address it).
- No **focus modes** — "agents working, leave me alone" / "I'm in a presentation" / "deep work" presets that dim/hide ambient surfaces.
- No **virtual desktops** that aren't workspaces — sometimes you want two views of the same workspace (chat + WaggleDance vs Files + Wiki) without swapping context.
- No **ambient "agent is running" peripheral indicator** — the dock bee icon doesn't pulse, the window edge doesn't honey-glow.
- No **OS-level transitions** between scenes (snap, slide, zoom-into-app).

**Recommended adds:**
1. **Hex dock skin** + active-cell honey glow + agent-progress ring around the active tile **[S]**. (Visible foundation for grafts 1+8 above.)
2. **Snap zones** (drag window to screen edge → halve/quadrant) using existing `AppWindow` resize handles **[S]**.
3. **Focus modes** — three presets in `StatusBar` ("Working / Focus / Presenting") that toggle right-rail visibility, dock animation, notification stream **[M]**.
4. **Pulse + glow when an agent in this window is doing work** — animated honey-amber border on `AppWindow`, decay-out when idle **[S]**.
5. **Virtual sub-views per workspace** (later, after cluster 5 — workspaces-as-scenes — lands) **[M]**.
6. **Multi-monitor support** via Tauri window-detach (open a window in a separate Tauri WebView on a second display) **[L]**.

---

## 2. The command surface — the omnibar

**Today:** `GlobalSearch.tsx` overlay + `LauncherApp.tsx`. Search is search-only. Launcher is a tool-launching surface. Neither is a true command palette.

**What's missing:** Marko's OS has 24+ apps, hundreds of memory frames, multiple agents, dozens of skills, and a marketplace. There is no single keystroke that gets you to anything. The most-used surface in any modern OS-of-AI (Raycast, Spotlight, Linear ⌘K) is the **fuzzy-routed omnibar**.

**Recommended:** ship **⌘K Omnibar** as the universal entry point:

| Verb prefix | What it does |
|---|---|
| (no prefix) | Fuzzy search across apps, recent windows, files, memory frames, skills |
| `>` | Run a command (open app, switch workspace, spawn agent, toggle focus mode) |
| `@` | Ask an agent — picks the right persona or routes to the active window's chat |
| `?` | Search memory ("what do I know about X") + inline answer card |
| `#` | Jump to skill / connector |
| `/` | Insert a slash-command into the active chat window |

Implementation moves:
1. **Build the omnibar shell** in `components/os/overlays/Omnibar.tsx`, hotkey `Ctrl/Cmd+K` (free up `GlobalSearch.tsx` for retirement or convert to the `?` namespace inside it) **[S]**.
2. **Wire the verb routers** — start with no-prefix + `>` + `?` (highest leverage), defer `@` / `#` / `/` to Phase 2 **[S]**.
3. **Persistent omnibar pill** in the status bar — always-visible `⌘K · ask anything` — beats a hidden shortcut for discoverability **[S]**.
4. **Fuzzy index** of (apps, workspaces, recent files, top-N memory frames, skills) refreshed on workspace-switch — sub-100ms response **[S/M]**.

---

## 3. Agent visibility & multi-agent choreography

**Today:** `AgentsApp.tsx`, `MissionControlApp.tsx`, `WaggleDanceApp.tsx`, `SpawnAgentDialog.tsx`. You can spawn, see, and run agents. You can observe WaggleDance signals.

**What's missing — the live picture:**
- **No status-bar presence layer.** When 3 agents are working you don't see it from the chrome.
- **No "is my agent stuck?" glance state.** You have to open MissionControl to know.
- **WaggleDance is a list, not a dance.** The literal honeycomb-with-signal-edges is the missing payoff.
- **No interrupt / hand-off / "stop and ask me" model** — agents either run autonomously or you cancel.
- **No agent-to-agent comm visualization.** When the orchestrator delegates to a sub-agent, you have to read logs.

**Recommended adds:**
1. **Status-bar crew presence row** — tiny hex avatars per running agent, honey-glow = working, violet-pulse = waiting on memory, red = stuck/errored. Click → jump-to-window. **[S]**
2. **Convert `MissionControlApp` to hex-grid view** — every running agent is a hex cell; cell color = state; hover = current tool; click = drill in. List view stays as a sub-tab. **[M]**
3. **Make `WaggleDanceApp` an actual honeycomb canvas** with signal-flow on edges (animated path when one agent broadcasts to another). This is where graft #3 finally pays. **[M]**
4. **Interrupt control on every running-agent window** — `Pause / Resume / Ask me / Cancel`. The "Ask me" puts the agent into the Approvals app and shows a notification. **[S]** (already partially wired via Approvals; surface the controls.)
5. **Hand-off UI in chat** — when persona A is wrong for a question, an inline card "Pass to persona B?" with a one-click migrate. **[M]**
6. **Agent-to-agent comm trace** — when a parent spawns a child, draw the edge in WaggleDance and link the windows; child window has a back-arrow to parent. **[S]**

---

## 4. Memory as first-class fabric

**Today:** `MemoryApp.tsx` with five tabs (Wiki / KnowledgeGraph / Harvest / Weaver / Evolution). Memory is **a destination** — you go to the Memory app to look at it.

**What's missing — memory as fabric:**
- **No peripheral memory inspector in chat.** Every chat turn fetches memory; the user can't see what was retrieved.
- **No "what does Waggle know about X" inspector** at the OS level — pin a noun, see the graph.
- **No provenance overlay** — when an agent answers, you can't see which frames backed each claim.
- **No time-travel** — "what did my memory look like last week?" is not a thing.
- **Memory isn't a verb** in the omnibar (cluster 2 fixes this).

**Recommended adds (this is your moat — bias toward shipping):**
1. **Right-rail memory peripheral inspector in `ChatApp`** — hex mini-graph showing which frames were recalled for the current turn, with hover-to-preview. Default-collapsed so it doesn't intrude. **[M]**
2. **Provenance citations in agent answers** — small `[1]` markers in the response, hover = the actual frame. Wire to the existing `KnowledgeGraphViewer`. **[M]**
3. **Memory inspector overlay** — pin a noun anywhere (selection menu → "What does Waggle know about this?") → mini-overlay with related frames + entity + concept. **[M]**
4. **Time-travel slider in MemoryApp** — a horizontal scrubber across the top: "show memory as of 2026-04-15". Backed by `bitemporal validity` already in `knowledge.ts`. **[M]**
5. **"Memory health" tile in Dashboard** — frames added today, stale clusters, dedup opportunities. Already partially in HarvestTab; promote to surface-level. **[S]**

---

## 5. Workspaces as scenes (not folders)

**Today:** `WorkspaceSwitcher.tsx` overlay + `WorkspaceRail.tsx` in `FilesApp`. Workspaces hold files and memory frames. They're filing cabinets.

**What's missing — workspaces as desktops:**
- **No persisted window layout per workspace** — switching workspaces resets the spatial arrangement.
- **No pinned dock per workspace** — same dock everywhere; you can't say "my Research workspace pins Wiki + Memory + Chat, my Founder workspace pins Cockpit + Compliance + Approvals."
- **No assigned crew per workspace** — same personas everywhere; no "this workspace's agents are X, Y, Z."
- **No memory scope per workspace** — you have to manually filter.
- **No autonomy tier per workspace** — Normal/Trusted/YOLO is global, but a "throwaway research" workspace wants YOLO while "production deploy" wants Trusted.

**Recommended adds (this is where workspaces become *scenes*):**
1. **Persist window-arrangement on workspace-switch** — when you leave a workspace, snapshot which apps were open + their positions; restore on return. **[S]**
2. **Per-workspace dock pinning** — workspace config stores `pinnedApps: string[]`; the dock renders the workspace's set first, then the global apps. **[S]**
3. **Workspace crew** — when you spawn an agent in a workspace, it sticks; the workspace stores `crew: AgentDef[]` and surfaces them in MissionControl + the status-bar presence row. **[M]**
4. **Per-workspace memory scope** as the default for in-workspace search (existing search likely supports it; promote to the UX). **[S]**
5. **Per-workspace autonomy tier** — `WorkspaceConfig.autonomy: Normal | Trusted | YOLO`; status-bar shows the active tier with a visible badge. **[S]**
6. **Workspace gallery overview** — when no workspace is active, show a hex grid of workspaces with thumbnails. New users see this; advanced users skip via `Cmd+1..9`. **[M]**

---

## 6. Input modalities & ambient capture

**Today:** `ChatApp` (text) + `VoiceApp` (voice). Both are destinations you go to.

**What's missing — ambient input:**
- **No always-listening hotkey** — hold `Cmd+Space` and talk, release to send. Doesn't require switching to VoiceApp.
- **No drag-anywhere file-routing** — drag a PDF onto the desktop; the OS asks "send to Files / ask agent about it / harvest into memory?"
- **No screenshot-to-agent** — `Cmd+Shift+4`, drag a region, the screenshot lands in the active chat or routes to an agent.
- **No QR pull-in from mobile** — Waggle doesn't have a real mobile companion, but a QR-scan-to-open-on-Waggle-OS pattern is achievable.
- **No "share my screen with my agent"** — for agents that benefit from visual context (UI debugging, design feedback).

**Recommended adds:**
1. **Push-to-talk hotkey** with floating overlay + waveform during capture + auto-route to active window's input or active chat. **[M]**
2. **Drag-to-desktop drop-target** with route picker (Files / Chat / Harvest / Skill). **[M]**
3. **Screenshot-to-agent** via Tauri global shortcut → image lands in active chat as attachment. **[M]**
4. **Mobile QR-handoff** — QR shown in StatusBar, mobile scans, message sent shows up in your active chat (no native app needed; web page + WebSocket). **[L]**
5. **Screen-share to agent** — Tauri can grab a screen region; pipe to a vision-capable model in the active window. Tier-gated (Pro+). **[L]**

---

## 7. Trust, autonomy & approval choreography

**Today:** `ApprovalsApp.tsx`, `VaultApp.tsx`, `CapabilitiesApp.tsx`, three-tier autonomy (`Normal / Trusted / YOLO`). Approvals open as modals. Audit trail is a list.

**What's missing — approvals as peripheral, not modal:**
- **Approvals interrupt your work** — modal blocks the active task instead of queueing peripherally.
- **No autonomy dial visible per agent** — the tier is global; the user can't see "this agent runs Trusted, this one Normal."
- **No "why is this agent doing this?" surface** — when an action surprises the user, there's no one-click "show me the chain of reasoning."
- **Audit trail is a flat log** — should be a scrubable replay (timeline of tool calls + memory hits + outputs).

**Recommended adds:**
1. **Approval inbox in the status bar** — pending approvals = a small honey-amber pip with a count; click expands a popover instead of a modal. Block-mode is opt-in per autonomy tier (YOLO never blocks, Normal blocks on critical only). **[S]**
2. **Autonomy dial visible per agent** in MissionControl + agent window header. Click to change scope (this run / this session / this workspace / global). **[S]**
3. **"Why?" button on every agent action** — opens a side-panel showing the prompt, the tool call, the memory frames retrieved, the reasoning trace. Wire to existing `ExecutionTraces`. **[M]**
4. **Audit replay** in `TimelineApp` — a video-scrubber-style timeline of agent actions; play/pause/seek. Pulls from existing trace store. **[M]**
5. **"This action is the kind of thing this agent does at Trusted tier" hint** — when an action triggers approval, show the autonomy threshold and a one-click "raise this agent to Trusted." **[S]**

---

## 8. Discoverability — the OS teaches you

**Today:** `OnboardingWizard.tsx` (one-shot, 8 steps) + `OnboardingTooltips.tsx` (post-onboarding hints). Both are first-run; they go silent after.

**What's missing — an OS keeps teaching:**
- **No tip-of-the-day surface** — users plateau at the 10 features they discovered week 1.
- **No "did you know your agent can…" prompts** — based on what the user just did.
- **No watching TUTOR persona** — surfaces a capability the user almost discovered but didn't.
- **No skill / connector recommendations** based on usage patterns.
- **No "you haven't tried X in 30 days, here's what's new" reactivation.**

**Recommended adds:**
1. **Tip-of-the-day in the status bar** — small honey-amber pip, click expands. One tip per day, dismissible permanently. Indexed by user action (don't show "spawn an agent" to a user who spawned one 5 minutes ago). **[S]**
2. **Capability recommender after every long-running task** — "this agent ran 12 tools — want me to distil it into a skill?" Already partially exists via D1 distillation; surface the prompt to the user. **[S]**
3. **TUTOR persona** as a 17th persona — read-only, watches recent user actions + memory + workspace state, periodically surfaces "I noticed you searched for X three times — here's a saved search." Off by default; opt-in. **[L]**
4. **Connector / skill recommender in the MarketplaceApp** — based on workspace topic + recent harvest, suggest 3 connectors. **[M]**
5. **Reactivation banner** for stale workspaces ("It's been 30 days since you opened 'Q1 Research' — here's what's changed: 12 new memory frames, 2 closed agents."). **[M]**

---

## 9. Cross-cutting design principles

These tie the 8 clusters together. They are the design language; everything new should obey them.

| Principle | Concrete rule |
|---|---|
| **Color semantics** | `honey #e5a000` = live/working/active; `accent #a78bfa` = memory-touched/recalled; neutral = idle. NO arbitrary color use. |
| **Peripheral-first** | Information about *agents working* / *memory in play* / *signals firing* lives in the right rail or status bar, not in modal interruptions. |
| **Motion = signal** | Animation is reserved for actual signal (agent active, memory hit, hand-off). Static UI = idle UI. No decorative motion. |
| **One omnibar, one entry** | `Cmd+K` is the universal entry point. Every app should be reachable through it. |
| **Hex where it's a signal-node, rectangle where it's content** | Cells of the OS (agents, dock items, personas, connectors) = hex. Content (text, files, dialogs) = rectangle. Never both for the same concept. |
| **Approvals are peripheral by default** | The OS interrupts only at YOLO-violations or user-explicit "approve me when..." rules. |
| **Memory is a verb everywhere** | `?` prefix in omnibar; `What do I know about X` from any selection; provenance on every agent answer. |
| **Workspaces are scenes, not folders** | Every workspace has its own dock, crew, autonomy tier, layout. |

---

## 10. Phased rollout suggestion

The 8 clusters compound. The right order is **the OS-feel pass first** (visible coherence + new omnibar + honeycomb grafts), **agent visibility + memory fabric second** (the differentiation moat), **scenes + ambient + tutor third** (the deepening).

### Phase 1 — The OS-feel pass (2–3 weeks)
Everything **S** that establishes the visual + interaction language:
- Hex dock skin + honey-active accent ⟶ §1.1
- Window snap zones ⟶ §1.2
- Agent-window honey-pulse on active work ⟶ §1.4
- ⌘K Omnibar with no-prefix + `>` + `?` verbs ⟶ §2.1–2.3
- Status-bar crew presence row ⟶ §3.1
- Memory health tile in Dashboard ⟶ §4.5
- Per-workspace dock pinning + autonomy tier ⟶ §5.2 + 5.5
- Tip-of-the-day in status bar ⟶ §8.1
- Approval inbox in status bar ⟶ §7.1
- Autonomy dial per agent ⟶ §7.2

**Outcome:** the OS *feels* like an OS. Differentiation is visible. No new agents, no new pipelines.

### Phase 2 — The differentiation moat (4–6 weeks)
The **M** items that lean into Waggle's unique surface (memory + multi-agent):
- WaggleDance as literal honeycomb canvas ⟶ §3.3
- Mission Control hex-grid view ⟶ §3.2
- Memory peripheral inspector in ChatApp ⟶ §4.1
- Provenance citations in agent answers ⟶ §4.2
- Memory inspector overlay (pin-a-noun) ⟶ §4.3
- Time-travel slider in MemoryApp ⟶ §4.4
- "Why?" button + audit replay ⟶ §7.3 + 7.4
- Hand-off UI in chat ⟶ §3.5
- Workspace crew + memory scope + scene restoration ⟶ §5.1, 5.3, 5.4
- Focus modes ⟶ §1.3

**Outcome:** the OS-of-AI moat is visible — memory as fabric, agents as a coordinated swarm, workspaces as scenes.

### Phase 3 — The deepening (multi-week, prioritize when Phase 2 is in users' hands)
The **L** items:
- Multi-monitor support ⟶ §1.6
- Push-to-talk + drag-to-desktop + screenshot-to-agent ⟶ §6.1–6.3
- Mobile QR-handoff ⟶ §6.4
- Screen-share to agent ⟶ §6.5
- TUTOR persona ⟶ §8.3
- Reactivation banners ⟶ §8.5

---

## 11. Open questions / decisions Marko owns

These are real decisions that affect the build; none have been settled in this brainstorm.

1. **TUTOR persona placement** — is it a 17th persona in `persona-data.ts`, a system service that any persona can speak through, or an explicit `tutor: true` flag on existing personas (so Research Researcher can have a tutor mode)?
2. **Always-listening privacy posture** — push-to-talk only (safe default), or always-listening behind a per-workspace opt-in? Audit/UI implications.
3. **Scene workspaces migration** — do existing workspaces become scenes automatically (lift their last window arrangement) or do users opt-in workspace-by-workspace?
4. **Approval inbox vs modal threshold** — what's the default for Normal tier? Currently inferred: modal on credential-touching + writes-outside-workspace, peripheral on everything else.
5. **Honey-amber agent-active glow intensity** — light pulse OK, but an agent that's been running for 30 minutes shouldn't strobe forever. Decay rule? (Suggestion: glow for first 30s, then steady-amber dot in the window header.)
6. **Free-floating windows vs forced tiling** — Phase 1 ships snap zones; does Phase 2 add a tile-everything mode for users who want it, or stay free-floating?
7. **Right-rail visibility default** — peripheral memory inspector default open or default closed? Opens-on-first-recall might be the right answer.
8. **Mobile companion form-factor** — is it a separate Tauri mobile build, a PWA, or just a web page with WebSocket? (Affects §6.4 effort.)

---

## 12. Implementation notes (deferred — for writing-plans)

Cross-references for the implementation plan author:

- **Dock skin** — `apps/web/src/components/os/Dock.tsx`, `apps/web/src/lib/persona-tier.ts` for tier styling already exists.
- **Omnibar** — net-new file `apps/web/src/components/os/overlays/Omnibar.tsx`; retire or namespace `GlobalSearch.tsx`.
- **Status-bar crew presence** — extend `StatusBar.tsx`; data source = WaggleDance signal bus + running-agent registry.
- **WaggleDance honeycomb** — `apps/web/src/components/os/apps/WaggleDanceApp.tsx`; signal-flow data already streams from the v2 bus (`packages/server/src/local/routes/waggle-dance.ts`).
- **Memory peripheral inspector** — `apps/web/src/components/os/apps/ChatApp.tsx` + memory recall events from `packages/agent/src/orchestrator.ts` `recallMemory()`.
- **Workspace scenes** — `packages/core/src/workspace-config.ts` extends with `pinnedApps`, `crew`, `autonomy`, `lastLayout`.
- **Time-travel slider** — `packages/core/src/mind/knowledge.ts` already has bitemporal validity (`valid_from` / `valid_to`); UI is the missing piece.

Each implementation plan will need its own tsconfig project verification (`packages/agent/tsconfig.json`, `apps/web/tsconfig.json`) and a Vitest pass.

---

## 13. What this design doesn't try to do

- It does not propose a redesign of the **landing page** (`apps/www/`) — explicitly out of scope per the brainstorm.
- It does not change **billing/tiers** — Stripe wiring is settled.
- It does not change **the agent loop** — that's the engine; this is the UI.
- It does not propose **a new design system** — Hive DS stays; honey/violet/hive-950 stay; we just *use them more consistently*.
- It does not propose **mobile-native ports** — §6.4 is a companion, not a port.
- It does not address **the KVARK on-prem enterprise surface** — that's a separate workstream.

---

*End of design doc. Awaiting review.*