# 07 — FRONTEND REBUILD GUIDE (Lovable)

> **What this is.** The action-oriented, build-in-order playbook for rebuilding the Waggle OS web UI
> in Lovable against the **existing, unchanged Fastify sidecar**. The backend is the contract; the
> frontend is replaceable. Everything below is grounded in the backend map sections (`02c`, `03a–03g`,
> `04`) and the live `apps/web/src/` source. Field names, paths, ports, and tokens are quoted verbatim.
>
> **Companion docs (read alongside):**
> - `sections/04-feature-map.md` — full app↔endpoint matrix (the canonical screen list).
> - `sections/02c-shared-types-tiers.md` — wire types, Zod request schemas, the 5-tier capability matrix.
> - `sections/03a-api-chat-agents.md` — chat SSE event catalogue + approvals.
> - `sections/03f-api-realtime-ops.md` — the 4 SSE streams + ops endpoints.
> - `sections/03g-api-cloud-billing-kvark.md` — auth handshake, guards, Stripe.

---

## 0. The 60-second mental model

Waggle's UI is **a single-page "desktop OS"**, not a multi-route app. React Router has exactly two routes
(`/` → `<Index>`, `*` → `<NotFound>`). `Index` shows a boot screen then mounts `<Desktop>`, which **is** the
shell: it owns a window manager, a Dock, draggable app windows, and overlays. Apps are opened by `appId`,
not by URL. Everything talks to the backend through **one singleton adapter** pointed at the local Fastify
sidecar.

```
Lovable App
 └─ ServiceProvider (calls adapter.connect() once, exposes useService())
     └─ Desktop shell
         ├─ Dock (tier-filtered app launcher)
         ├─ WindowManager (open/close/focus windows by appId)
         │    └─ AppWindow × N → renderAppContent(appId) → <XxxApp />
         └─ Overlays (modals, rails, wizards)
     ── all of the above import the SAME `adapter` singleton ──
         └─ adapter → http://127.0.0.1:3333 (Fastify sidecar)
```

Build the adapter + ServiceProvider + Desktop shell **first**. Everything else is screens that call adapter
methods.

---

## 1. API base URL, transport, auth, headers, tier pattern

### 1.1 Base URL

| Concern | Value / behavior |
|---|---|
| Default server | `http://127.0.0.1:3333` (constant `DEFAULT_SERVER`) |
| Override | `localStorage["waggle:server-url"]`, settable via `adapter.setServerUrl(url)` |
| Resolution order | `ctorArg ?? localStorage["waggle:server-url"] ?? DEFAULT_SERVER` |
| Prefix | **None.** Every route hardcodes its own full path (`/api/...`, `/health`, `/ws`, `/v1/...`). Do **not** add a base prefix. |
| Same-origin reality | In the desktop binary the SPA is served BY the sidecar, so the page origin IS the API root (`http://localhost:3333` or `tauri://localhost`). For a Lovable web rebuild, hit `http://127.0.0.1:3333` explicitly; expect CORS to be pre-allowlisted for `localhost:5173/8080/8081/8082/3333/1420` and `tauri://localhost`. |

### 1.2 Auth handshake (two-step, no login form)

There is **no username/password UI** for the local sidecar. Auth is a boot-generated session token:

1. **Static shell loads token-free** — non-API GETs are auth-exempt.
2. **Fetch token once on connect:** `GET /api/auth/session-token` → `{ token }`. This route is auth-exempt
   but **same-origin gated**. Store it as `authToken`.
3. **Send Bearer on everything else:** every `/api/*` request must carry
   `Authorization: Bearer <token>`. Missing → `401 MISSING_TOKEN`; wrong → `401 INVALID_TOKEN`.
4. **WebSocket** (optional) uses the token in the query string: `GET /ws?token=<authToken>` (not a header).
   Wrong token closes the socket with code `4001`.

```
connect():
  GET /health                      → probe (fallback to DEFAULT_SERVER once if stored URL fails; persist working URL)
  GET /api/auth/session-token      → { token }; this.authToken = token
  set _connected = true
```

### 1.3 The single `fetch` wrapper (reproduce exactly)

Every request goes through one `adapter.fetch(path, init)`. It MUST:

- Add `Content-Type: application/json` **only when a body is present** and no content-type was supplied.
  (Body-less POSTs must NOT send a JSON content-type — this is a deliberate fix; sending it breaks some routes.)
- Add `Authorization: Bearer <authToken>` when the token is set.
- On HTTP **403** with body `{ error: 'TIER_INSUFFICIENT' }`, dispatch a global DOM event
  `window.dispatchEvent(new CustomEvent('waggle:tier-insufficient', { detail: { required, actual, message } }))`.
  This is the **only** trigger for the Upgrade modal.
- Use a timeout: **10s default, 30s for upload/ingest/harvest**. Throw `TimeoutError` / `NetworkError`.
- Handle rate limits: the sidecar enforces sliding-window limits (default **100/min**; `/api/chat` 120/min;
  `/api/vault/*/reveal` 5/min; `/api/backup` & `/api/restore` 2/min; `/api/browse/local/mkdir` 10/min).
  On `429`, read `Retry-After` and back off.

### 1.4 Read-side normalizers (reproduce or the UI crashes on `undefined`)

The backend and UI disagree on several field names. The adapter normalizes on read; you must too:

| Helper | Mapping |
|---|---|
| `unwrapArray<T>(data)` | accepts a raw array OR `{ results: [...] }` / `{ <key>: [...] }` envelope |
| `normalizeFrame(raw)` | frameType code `I/F/E/D/T/N` → `insight/fact/event/decision/task/entity`; `importance` string ↔ number 1–4 |
| `normalizeCronJob(raw)` | server `cronExpr/lastRunAt/nextRunAt` → client `schedule/lastRun/nextRun` |
| `getFleet()` | server `durationMs/tokensUsed` → client `duration/tokenUsage` |
| `getModelPricing()` | server `inputPer1k/outputPer1k` → client `inputCostPer1k/outputCostPer1k` |
| `getMemoryStats()` | server `frameCount/entityCount/relationCount` → client `frames/entities/relations`; tolerate `workspace:null` |
| `getModel()` | accepts raw `string` OR `{ model }` |

> **Tauri dual-path (skip for Lovable web).** A few memory methods (`addMemoryFrame`, `searchMemory`,
> `getKnowledgeGraph`, `getIdentity`) branch on `isTauri()` and use Rust IPC. A web rebuild always takes the
> `else` HTTP branch — ignore the IPC path entirely.

### 1.5 Tier gating pattern (read this before gating any feature)

- Fetch the user's tier from `GET /api/tier` → `{ tier, trialDaysRemaining?, trialExpired?, capabilities, usage }`.
- **Always run the stored tier through `getEffectiveTier(tier, trialStartedAt)` before reading
  capabilities** — an expired TRIAL must collapse to FREE gating. (`getEffectiveTier`, `getCapabilities`,
  `hasCapability` live in `@waggle/shared/tiers`; port them or reimplement.)
- Gate UI on `TierCapabilities` flags, not on the tier name. `-1` means **unlimited** (short-circuits to allowed).
- The **upgrade trigger is Skills + Connectors + Team features** — never agents/memory (`spawnAgents` is `true`
  in every tier; memory/embedding quotas are `-1` everywhere). The full matrix is in `02c §15.2`.
- Two distinct tier axes exist:
  - `BillingTier` = `'TRIAL'|'FREE'|'PRO'|'TEAMS'|'ENTERPRISE'` (entitlements).
  - `UserTier` = `'simple'|'professional'|'power'|'admin'` (UI density / dock complexity).
  - The Dock is computed from both via `getDockForTier(userTier, billingTier)`.

---

## 2. Real-time: which endpoints stream, and how to consume each

There are **five** streaming surfaces. Four are SSE (`EventSource`), one is the chat POST-SSE hybrid, plus an
optional WebSocket. **The chat stream is a POST, so you cannot use `EventSource` for it** — you parse the
response body manually.

### 2.1 Chat token stream — `POST /api/chat` (SSE-formatted body)

- **Not** a JSON endpoint and **not** `EventSource`-compatible (EventSource is GET-only). Issue a `fetch` POST,
  read `response.body.getReader()`, decode, and split on `\n\n`; each frame is `event: <name>\ndata: <json>`.
- All validation/auth happen **before** the server hijacks the reply. So a `400`/`403` comes back as normal
  JSON; anything after is SSE. Check `response.ok` / content-type before entering the stream loop.
- **Request body:** `{ message (required), workspace?/workspaceId?, model?, session?, persona?, autonomy?, shape? }`.
  `autonomy = { level: 'normal'|'trusted'|'yolo', expiresAt? }`.
- **Event catalogue** (handle ALL of these):

  | `event:` | `data` | Action |
  |---|---|---|
  | `token` | `{ content }` | append to streaming assistant text |
  | `step` | `{ content }` | render a progress line ("Recalling memories…", budget notes) |
  | `tool` | `{ name, input }` | show tool-call block (adapter normalizes name `tool`→`tool_start`) |
  | `tool_result` | `{ name, result, duration?, isError }` | close tool block (normalized `tool_result`→`tool_end`) |
  | `file_created` | `{ filePath, fileAction: 'write'|'edit'|'generate' }` | show "file created" affordance |
  | `approval_required` | `{ requestId, toolName, input, sourceWorkspaceId, ...trustMeta }` | **PAUSE.** Render approve/deny; resolve via `POST /api/approval/:requestId` |
  | `gepa_choices` | `{ original, expanded, clarifyingQuestions[], intent }` | offer ask-first clarification |
  | `model_switch` | `{ model, reason, primary }` | toast "switched to <model>" |
  | `notification` | `{ type:'workflow_captured', title, message, pattern }` | suggest saving a workflow |
  | `done` | `{ content, usage{inputTokens,outputTokens}, toolsUsed[], model, cost?, tokens? }` | **terminal success** |
  | `error` | `{ message }` | **terminal failure** (user-friendly only) |

  Tolerate two `done` usage shapes: agent-loop `{ inputTokens, outputTokens }` and echo/command-path
  `{ prompt_tokens, completion_tokens, total_tokens }`.

- **Approvals are blocking.** When `approval_required` arrives the agent is paused awaiting a server-side
  Promise (auto-denies after **5 min**). POST `{ approved: boolean, always?: boolean, reason?, sourceWorkspaceId }`
  to `/api/approval/:requestId`, echoing `sourceWorkspaceId` verbatim. `always:true` persists a grant.

### 2.2 The four GET SSE streams (`EventSource`)

| Endpoint | How to subscribe | Events you read |
|---|---|---|
| `GET /api/waggle/stream` | `new EventSource(url)` + `addEventListener('signal', …)` | `signal` → full `WaggleSignal` JSON. Initial `event: connected`. Heartbeat `: heartbeat` every 30s. |
| `GET /api/events/stream` | `addEventListener('audit', …)` | `audit` → full `AuditEvent` JSON. Initial `data:{"type":"connected"}`. |
| `GET /api/notifications/stream` | **mixed:** `onmessage` for unnamed frames + `addEventListener('subagent_status'|'workflow_suggestion', …)` | `notification` arrives as an **unnamed** `data:` frame (use `onmessage`); `subagent_status` and `workflow_suggestion` are **named** events. |
| `GET /api/harvest/progress` | `new EventSource(url)` | `{ phase, current, total, source }` progress frames. Adapter wraps as `{ ready: Promise, close }`. |

**EventSource caveat:** native `EventSource` cannot set an `Authorization` header. The sidecar gates these
streams by **same-origin** (the SPA is same-origin in production). For a cross-origin Lovable dev build you may
need to either (a) run behind a same-origin dev proxy to the sidecar, or (b) use a fetch-stream polyfill that
injects the Bearer header. The streams set `Access-Control-Allow-Origin` only for allowlisted origins.

### 2.3 WebSocket (optional) — `GET /ws?token=<authToken>`

Local sidecar `/ws` is an event-bus relay. Server→client frames `{ event, data }` for
`approval_required | step | tool | done | error | presence_update | notification`. Client→server
`{ type: 'approve'|'deny', requestId }`. The SSE streams already cover the UI's needs, so WS is **optional** for
the rebuild. (The cloud-server `/ws` is a separate Clerk+Redis team-chat gateway — not used by the local UI.)

### 2.4 Hook pattern for streams

Mirror the existing domain hooks: each owns local state + opens its stream on mount, returns close on unmount.

```ts
// useEvents → subscribeEvents (/api/events/stream)
// useNotifications → /api/notifications/stream (unread count, markRead, markAllRead)
// useRoomState → subscribeSubagentStatus (named 'subagent_status' on /api/notifications/stream)
// useWaggleDance → subscribeWaggleDance (/api/waggle/stream) + publish/ack
// useChat → POST /api/chat fetch-stream → parses into ContentBlock[]
```

---

## 3. Global state & providers the rebuild needs

**There is no Redux / Zustand / React Query.** State = React Context (one provider) + custom hooks + the
singleton adapter + a `window` CustomEvent bus. Reproduce these four layers.

### 3.1 The one provider

| Provider | Provides | Behavior |
|---|---|---|
| `ServiceProvider` / `useService()` | `{ adapter, connected, connecting, error, reconnect }` | calls `adapter.connect()` **once** on mount; wrap the whole app. (Plus shadcn `TooltipProvider` + a toast `Toaster`.) |

### 3.2 Domain hooks (the de-facto store)

Recreate these as the state layer — each wraps adapter calls + `useState`. The Desktop shell composes them.

| Hook | Owns |
|---|---|
| `useWorkspaces` | workspaces, **active workspace**, select/create/patch/delete/refresh — the workspace context every other call needs |
| `useChat` | `messages` (as `ContentBlock[]`), `isLoading`, `sendMessage`, `clearHistory`, `pendingApproval`, `approveAction`; parses the chat SSE stream |
| `useSessions` | per-workspace session CRUD (list/create/rename/delete/search/export) |
| `useMemory` | frames, stats, search, add/update/delete, `incrementFrameAccess` |
| `useKnowledgeGraph` | `{ nodes, edges }` |
| `useEvents` | audit steps + live SSE |
| `useNotifications` | notifications, `unreadCount`, markRead/markAllRead, live SSE |
| `useRoomState` | live sub-agent map (named `subagent_status` SSE) |
| `useWaggleDance` | signals, filter, ack, publish, live SSE |
| `useAgentStatus` | polls `/api/agent/status` |
| `useBilling` | **tier**, `startCheckout`, `openPortal`, `syncAfterCheckout` (auto-detects `?session_id=` on load) |
| `useFeatureGate` | `{ planTier, isEnabled, gate }` — the per-feature gate front-end |
| `useOnboarding` | persisted `OnboardingState` in `localStorage["waggle:onboarding"]` (`completed, step, tier, workspaceId, apiKeySet, templateId, personaId, tooltipsDismissed`); honors `?skipOnboarding=true`, `?forceWizard=true` |
| `useOfflineStatus` | polls `/health` for the offline pill |
| `useProviders` | `/api/providers` |
| `useWindowManager` | window open/close/focus/minimize + **per-window persona & autonomy** |
| `useOverlayState` | boolean flags for every overlay |
| `useKeyboardShortcuts` | global hotkeys → open app/overlay (Cmd+K global search, etc.) |

### 3.3 The four pieces of "global context" the rebuild must thread

1. **Workspace context** — `useWorkspaces.active`. Nearly every call accepts `workspace`/`workspaceId`
   (alias-accepted; omit ⇒ `personal` mind). The active workspace id flows into chat, memory, files, sessions,
   events. The window manager can override **persona** and **autonomy** per-window.
2. **Session** — the boot session token (`adapter.authToken`) for transport auth, plus the per-workspace
   chat session id (`useSessions`, defaults to the workspace id then `'default'`).
3. **Persona** — workspace-default persona, overridable per-chat-window. Passed as `persona` in the chat body.
4. **Tier** — `useBilling.tier` → `getEffectiveTier` → capabilities, consumed by `useFeatureGate`, the Dock, and
   the Upgrade/TrialExpired modals.

### 3.4 Cross-component `window` event bus (no library — wire these)

| Event | Dispatched by | Consumed by |
|---|---|---|
| `waggle:tier-insufficient` `{ required, actual, message }` | `adapter.fetch` on 403 `TIER_INSUFFICIENT` | `UpgradeModal` |
| `waggle:open-app` `{ appId, tab? }` | apps (e.g. `HarvestTab`) | `Desktop` → `wm.openApp(appId)` |

---

## 4. Screen-by-screen data contract

Each row = an OS app/overlay → the adapter methods/endpoints it calls → request/response summary. Paths are
verbatim and all `/api/*` are Bearer-gated. The `AppId` union (window content switch) is:
`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 unimplemented; `voice` is a static "Coming Soon" placeholder.)

### 4.1 Dock apps

| Screen (appId) | Key endpoints | Request → Response summary |
|---|---|---|
| **Chat** (`chat`) | `POST /api/chat` (SSE); `GET /api/history?workspace=&session=`; `DELETE /api/chat/history?session=`; `POST /api/approval/:id`; `POST /api/feedback`; `GET /api/memory/search?q=&scope=`; pins `GET/POST/DELETE /api/workspaces/:id/pins`; `POST /api/ingest`; `GET/PUT /api/agent/model`; `GET /api/settings`; `GET /api/team/members`; `PATCH /api/workspaces/:id` | Send `{message,workspace,session?,persona?,autonomy?,shape}` → SSE stream (§2.1). History → `{ sessionId, messages[{id,role,content,timestamp}], count }`. Feedback `{sessionId,messageIndex,rating,reason?,detail?}` → fire-and-forget. Pin `{messageContent,messageRole,label?}`. Model PUT `{model}`. |
| **Dashboard / Home** (`dashboard`) | `GET /api/memory/stats`; `GET /api/tasks` (raw) | stats → `{ personal, workspace, total }` each `{frames,entities,relations}`. Tasks → task list. |
| **Memory** (`memory`) — tabs: Frames, Knowledge Graph, Harvest, Wiki, Evolution | frames `GET/POST/PUT/DELETE /api/memory/frames`, `PATCH …/:id/access?workspace=`; `GET /api/memory/search?q=&scope=`; `GET /api/memory/graph?workspace=` (or `?scope=all\|personal`); `GET /api/memory/stats`; **Harvest:** `GET /api/harvest/sources`, `POST /api/harvest/scan-claude-code`, `POST /api/harvest/preview`, `POST /api/harvest/commit`, `GET /api/harvest/runs/latest-interrupted`, `POST /api/harvest/runs/:id/abandon`, `POST /api/harvest/extract-identity`, `GET /api/harvest/progress` (SSE), `PATCH/DELETE /api/harvest/sources/:source`; **Wiki:** `GET /api/wiki/pages`, `…/:slug`, `…/:slug/content`, `POST /api/wiki/compile`, `GET /api/wiki/health`, `POST /api/wiki/export/{obsidian,notion}`; **Evolution:** `GET/POST /api/evolution/{runs,runs/:id,run,targets,baseline,status}` (raw); **Weaver:** `GET /api/weaver/status`, `POST /api/weaver/trigger` | Frame (normalized) `{id,content,source,frameType,importance,timestamp,score?,gop,accessCount,…}`. Graph → `{ nodes:KGNode[], edges:KGEdge[] }`. Harvest preview `{data,source}` → `{ knowledgeExtracted[] }`; commit `{data,source}` / `{resumeFromRun}`. Wiki compile `{ mode:'incremental'\|'full', concepts? }`. |
| **Events & Logs** (`events`) | `GET /api/events?workspaceId=`; `GET /api/events/stream` (SSE) | `AgentStep[]` + live `audit` events `{id,timestamp,workspaceId,eventType,toolName?,input?,output?,model?,cost?,…}`. |
| **Skills & Apps** (`capabilities`) incl. Marketplace tab | `GET /api/skills`; `POST /api/skills/create`; `GET /api/skills/starter-pack/catalog`; `POST /api/skills/starter-pack/:skillId`; `GET /api/skills/capability-packs/catalog`; `GET /api/marketplace/packs`; `POST /api/marketplace/install`; `GET /api/audit/installs` + `GET /api/skills/test` (raw) | Skills `SkillPack[]` (forced `installed:true`). Install `{packageId}` → raw `Response` (403 → UpgradeModal). Create `{name,description}`. |
| **Connectors** (`connectors`) | `GET /api/connectors`; `GET /api/connectors/:id/health`; `POST /api/connectors/:id/connect`; `POST /api/connectors/:id/disconnect`; `POST /api/vault` | `ConnectorDefinition[]` (card: `{id,name,description,service,authType,status,capabilities[],substrate,tools[],logoUrl?,category?,setupGuide?}`). Add secret `{name,value,type?}`. |
| **Cockpit / Command Center** (`cockpit`) incl. Compliance | `GET /health`; `GET /api/agent/cost`; `GET /api/connectors`; `GET /api/cron`; `GET /api/vault`; `GET /api/capabilities/status`; `GET /api/audit/installs`; `GET /api/cost/summary`; `GET /api/weaver/status`; `GET /api/events/stats`; **Compliance:** `GET /api/compliance/status?workspaceId=`, `GET /api/compliance/templates`, `POST/PATCH/DELETE /api/compliance/templates*`, `POST /api/compliance/export`, `POST /api/compliance/export-pdf` (Blob) | health `{status,uptime,services[]}`; cost summary; event stats `{totalEvents,period,byType,byDay,topTools}`. |
| **Mission Control** (`mission-control`) | `GET /api/fleet`; `GET /api/team/members`; `GET /api/team/activity`; `GET /api/tools/detect`; `POST /api/fleet/:workspaceId/(pause\|resume\|kill)` | Fleet (normalized) `{workspaceId,workspaceName,personaId,model,status,lastActivity,duration,toolCount,tokenUsage,costEstimate}` + `{count,maxSessions}`. |
| **Waggle Dance** (`waggle-dance`) | `GET /api/waggle/signals`; `GET /api/waggle/stream` (SSE); `POST /api/waggle/signals`; `PATCH /api/waggle/signals/:id/ack` | `WaggleSignal{id,type,workspaceId,content,metadata?,timestamp,acknowledged}`. Publish `{type,content,workspaceId?,metadata?}`. |
| **Personas (Agents)** (`agents`) | `GET /api/personas`; `POST /api/personas`; `PATCH/DELETE /api/personas/:id`; `POST /api/personas/generate`; `GET /api/capabilities/status`; `GET /api/agent-groups`; `POST /api/agent-groups`; `PATCH/DELETE /api/agent-groups/:id`; `POST /api/agent-groups/:id/run`; `GET /api/jobs/:jobId`; `POST /api/jobs/:jobId/cancel` | Persona create `{name,description,icon?,systemPrompt,tools?}`. Generate `{prompt}` → `{name,description,systemPrompt,tools[]}`. Group create `{name,description?,strategy:'parallel'\|'sequential'\|'coordinator',members[{agentId,roleInGroup:'lead'\|'worker',executionOrder}]}`. Group run `{task,teamId?}` → queued stub. |
| **Files** (`files`) | `GET /api/workspaces/:id/files/list?path=`; `POST …/files/upload` (FormData, 30s); `GET …/files/download?path=` (Blob); `POST …/files/{mkdir,delete,move,copy}`; `GET …/documents`; `GET …/documents/:name/versions` | `FileEntry[]`. Move/copy `{from,to}`; delete/mkdir `{path}`. Upload `FormData(file,path)`. |
| **Scheduled Jobs** (`scheduled-jobs`) | `GET /api/cron`; `POST /api/cron`; `PUT /api/cron/:id`; `DELETE /api/cron/:id`; `POST /api/cron/:id/trigger` | CronJob (normalized) `{id,name,schedule,jobType,jobConfig,workspaceId,enabled,lastRun,nextRun,createdAt}`. Create `{name,cronExpr,jobType,jobConfig?,workspaceId?,enabled?}`. Trigger → `{triggered,autoEnabled?,schedule?}`. |
| **Marketplace** (`marketplace`) | `GET /api/marketplace/search?query=&limit=`; `GET /api/marketplace/installed`; `POST /api/marketplace/install`; `POST /api/marketplace/uninstall` | search/install/uninstall return **raw `Response`** for 403-aware handling. |
| **AI Tools / Launcher** (`launcher`) | `GET /api/tools/detect`; `POST /api/tools/launch`; `GET /api/tools/processes`; `POST /api/tools/kill`; `POST /api/tools/hooks` | detect → `{platform,detectedAt,tools[{id,displayName,installed,installedPath,version,hooksInstalled,…}]}`. Launch `{id,installedPath,workspaceId?,args?,cwd?}` → `{ok,pid,error?}`. Hooks `{id,action:'install'\|'verify'\|'uninstall',cliPath?}`. |
| **Room** (`room`) | `GET /api/notifications/stream` named `subagent_status` (SSE) | live sub-agent canvas `{agents[{id,name,role,status:'pending'\|'running'\|'done'\|'failed',task,toolsUsed,…}]}`. |
| **Approvals** (`approvals`, TEAMS+) | `GET /api/approval/pending`; `GET /api/approval/grants`; `POST /api/approval/:id`; `DELETE /api/approval/grants/:id`; `POST /api/approval/grants/clear` | pending `{pending[{requestId,toolName,input,timestamp}],count}`. |
| **Timeline** (`timeline`) | `GET /api/events?workspaceId=&limit=&from=` | `TimelineEvent[]`. |
| **Backup & Restore** (`backup`) | `GET /api/backup/metadata`; `POST /api/backup`; `POST /api/restore` (all raw) | backup streams `application/octet-stream` (`.waggle-backup`, ≤500MB). Restore `{ backup:<base64>, preview? }`. |
| **Usage & Telemetry** (`telemetry`) | `GET /api/cost/by-workspace`; `GET /api/events/stats` (raw) | cost-by-workspace + stats aggregates. |
| **Team Governance** (`governance`, TEAMS+) | none direct (props-driven sub-components) | renders governance UI. |
| **Settings** (`settings`) | `GET/PUT /api/settings`; `GET/PUT /api/settings/permissions`; `POST /api/settings/test-key`; `GET /api/providers`; `GET /api/telemetry/status`; `POST /api/telemetry/toggle`; `DELETE /api/telemetry/events`; `GET /api/team/status`; `POST /api/team/{connect,disconnect}`; `GET /api/export`, `/api/debug/logs` (raw) | Settings object; permissions `{defaultAutonomy,externalGates[],workspaceOverrides}`. Test key `{provider,apiKey}` → `{valid}`. |
| **Vault** (`vault`) | `GET /api/vault`; `POST /api/vault`; `DELETE /api/vault/:id`; `GET /api/connectors`; `POST /api/connectors/:id/(connect\|disconnect)` | secret `{name,value,type?}`. Vault reveal is rate-limited to 5/min. |
| **My Profile** (`profile`) | `GET/PUT /api/profile`; `POST /api/profile/analyze-style` `{text}`; `POST /api/profile/analyze-brand` `{description}`; `POST /api/profile/research` `{}` | profile object + analysis results. |

### 4.2 Overlays (rendered by Desktop, not windowed)

| Overlay | Key endpoints |
|---|---|
| **Onboarding wizard** (8 steps: Welcome, WhyWaggle, Tier, ModelTier, Import, Template, Persona, ApiKey, Ready) | `connect`, `GET /api/vault`, `/health`, `GET /api/providers`, `/api/v1/models`, harvest preview/commit, `POST /api/harvest/scan-claude-code`, import preview/commit, `POST /api/personas`, `POST /api/vault`, `POST /api/workspaces`, `PUT /api/settings` |
| **Login briefing** (session-start digest) | `GET /api/identity`, `GET /api/workspaces`, `GET /api/memory/search`, `GET /api/memory/stats`, `GET /api/workspaces/:id/context` |
| **Global search (Cmd+K)** | `GET /api/workspaces`, sessions, `GET /api/skills`, `GET /api/memory/search` |
| **Create workspace dialog** | `GET /api/browse/local?path=`, `POST /api/browse/local/mkdir`, `GET/POST/PUT/DELETE /api/workspace-templates*`, `POST /api/workspace-templates/generate`, `GET /api/connectors`, `GET /api/agent-groups` |
| **Persona switcher** | `GET /api/personas`, `GET /api/agent-groups` |
| **Spawn agent dialog** | `GET /api/litellm/models`, `/api/litellm/pricing`, `GET /api/providers`, `GET /api/agent/model`, `POST /api/workspaces`, `POST /api/fleet/spawn` (`{task,persona?,model?,parentWorkspaceId?}`) |
| **Erase data dialog (GDPR)** | `POST /api/data/erase` — header `X-Confirm-Erase: yes` + body `{ confirmation:'I UNDERSTAND THIS IS PERMANENT' }` |
| **Upgrade modal** | triggered by `waggle:tier-insufficient`; actions → `POST /api/tier/start-trial`, `POST /api/stripe/create-checkout-session` `{tier:'PRO'\|'TEAMS', billingPeriod?}` → `{url}` |
| **Trial expired modal** | `POST /api/stripe/create-checkout-session` |
| Workspace switcher / Notification inbox / Context rail / Keyboard help / Tooltips | props-driven or `lib/context-rail-fetch.ts`; no/minor direct calls |

### 4.3 Billing / tier endpoints (used across overlays + `useBilling`)

| Method | Path | Body → Response |
|---|---|---|
| GET | `/api/tier` | → `{ tier, trialDaysRemaining?, trialExpired?, capabilities, usage }` |
| POST | `/api/tier/start-trial` | → `{ tier, rawTier, trialStartedAt, trialDaysRemaining, trialExpired, capabilities }` (409 if already started) |
| POST | `/api/stripe/create-checkout-session` | `{ tier:'PRO'\|'TEAMS', billingPeriod?:'monthly'\|'annual' }` → `{ url }` (503 `STRIPE_NOT_CONFIGURED` if unset) |
| POST | `/api/stripe/sync` | `{ sessionId }` → `{ tier, customerId }` — **call this after the checkout redirect** (webhooks unreliable behind NAT) |
| POST | `/api/stripe/create-portal-session` | — → `{ url }` (requires PRO+) |

**Stripe flow for the rebuild:** open `{url}` from create-checkout-session → user pays → Stripe redirects to
`/payment-success?session_id=...` → `useBilling` detects `?session_id=` on load → `POST /api/stripe/sync` →
refresh tier. Render upgrade UI defensively when `503 STRIPE_NOT_CONFIGURED`.

---

## 5. Design system — Hive DS (dark default, desktop-OS metaphor)

The visual contract lives in `apps/web/src/index.css` (`@layer base` source of truth) + `waggle-theme.css`
(component aliases). It's a **shadcn-style HSL-variable system + a literal Hive palette**, with a `[data-theme="light"]`
override. **Default theme is dark.** Tailwind 4 + shadcn primitives + lucide icons.

### 5.1 Core brand tokens (the three the brief names)

| Token | Dark value | Role |
|---|---|---|
| Honey `--honey-500` | `#e5a000` | Primary brand / accent / focus ring / `--primary` (`40 100% 45%`) |
| Hive-950 `--hive-950` | `#08090c` | Deepest background / status bar; `--background` ≈ `222 20% 4%` |
| Accent (AI) `--status-ai` / `--accent` | `#a78bfa` / `270 60% 68%` | Secondary accent (AI, knowledge-concept highlights) |

### 5.2 Full palette (use the CSS variables, never hard-code hex)

- **Hive grays** (cold undertone): `--hive-950 #08090c → --hive-50 #f0f2f7` (12 steps). Surfaces:
  `--surface-card: var(--hive-850)`, `--surface-panel: var(--hive-800)`, `--surface-overlay: rgba(8,9,12,0.88)`.
- **Honey scale:** `--honey-600 #b87a00 … --honey-50 #fffbeb`, plus `--honey-glow rgba(229,160,0,0.12)`,
  `--honey-pulse rgba(229,160,0,0.06)`.
- **Status:** `--status-healthy #34d399`, `--status-warning #fbbf24`, `--status-error #f87171`,
  `--status-info #60a5fa`, `--status-ai #a78bfa`.
- **Knowledge-graph nodes:** `--kg-person #4A90D9`, `--kg-project #50C878`, `--kg-concept #9B59B6`,
  `--kg-org #E67E22`, `--kg-default #95A5A6`.
- **shadcn semantic vars** (HSL triplets, consumed via `hsl(var(--x))`): `--background, --foreground, --card,
  --popover, --primary (40 100% 45%), --secondary, --muted, --accent (270 60% 68%), --destructive, --border,
  --input, --ring (40 100% 45%), --radius 0.75rem`. Sidebar + chart vars mirror these.
- **Step/event colors** (event stream): `--step-running/-success/-pending/-error/-thinking/-search/-web/-tool/-writing`.

### 5.3 Typography, radius, shadows, motion

- **Fonts:** headings `Space Grotesk`; body `DM Sans` (fallback Inter/system); mono `JetBrains Mono`. Imported
  from Google Fonts in `index.css`. `--font-sans`, `--font-mono` aliases exist.
- **Type scale:** `--text-micro 11 → --text-display 24` (micro 11, caption 12, body-sm 13, body 14, title 16,
  heading 20, display 24).
- **Radius:** `--radius: 0.75rem`.
- **Shadows:** `--shadow-card`, `--shadow-elevated`, `--shadow-overlay`, `--shadow-honey` (honey glow),
  `--shadow-focus` (2px honey ring).
- **Signature motifs:** glassmorphism (`.glass` / `.glass-strong` — backdrop blur 20–30px), honeycomb hex
  background (`.honeycomb-bg`, SVG data-URI at 3% honey opacity), hex avatar clip-path (`.hex-avatar`),
  hex streaming cursor (`.hex-cursor`), honey-pulse on memory-save, heartbeat on health dot, float on the bee
  mascot, token-fade on streamed text. Selection + thin 5px scrollbars are honey/hive themed.
- **Interaction utilities:** `.waggle-interactive`, `.waggle-card-lift`, `.waggle-nav-hover`, `.waggle-press`,
  `.direction-d-card` (the canonical card: hive-700 border → honey-500 + honey-shadow on hover).

### 5.4 Light mode

`:root[data-theme="light"]` flips the hive scale (cream `#fdfcf9` bg, dark text), darkens honey + status +
KG colors for WCAG AA on cream, and softens shadows. Toggle by setting `data-theme="light"` on `:root`.
**Ship dark first**; light is a polish pass.

### 5.5 Layout — the desktop OS metaphor

- **Desktop**: full-viewport, `overflow:hidden` body, honeycomb wallpaper + `.desktop-overlay` wash.
- **Dock**: launcher rail (bottom/side) built from `lib/dock-tiers.ts`. Entries are `app | zone-parent
  (collapsible group) | separator`, each with `icon` (lucide), `label`, `color`. `getDockForTier(userTier,
  billingTier)` filters by `minBillingTier` (e.g. `governance` & `approvals` are TEAMS+; empty zone-parents are
  dropped). `simple` tier shows ~6 apps; `power`/`admin` show the full set incl. Ops + Extend zone groups.
- **Windows**: each open app is a draggable/resizable `AppWindow` keyed by `appId`; content via a
  `renderAppContent(appId)` switch. Windows carry per-window persona + autonomy.
- **Overlays**: modals/rails/wizards rendered directly by Desktop, gated by `useOverlayState` flags.
- **BootScreen**: shown until `localStorage["waggle-booted"]`, then Desktop mounts.

---

## 6. Prioritized rebuild order

Build in dependency order. Each phase is independently demoable.

**Phase 0 — Foundation (nothing renders without this).**
1. `adapter` singleton: base URL + `localStorage["waggle:server-url"]`, `connect()` (health probe + session-token
   bootstrap), the `fetch` wrapper (conditional content-type, Bearer, 403→`waggle:tier-insufficient`,
   10s/30s timeouts, 429 handling), and the §1.4 read normalizers.
2. `ServiceProvider` / `useService()` calling `adapter.connect()` once.
3. Hive DS tokens (`index.css` + `waggle-theme.css`), dark default, fonts, shadcn vars.
4. The `window` event bus (§3.4).

**Phase 1 — Shell.**
5. Desktop shell: `useWindowManager` (open by `appId`), Dock from `dock-tiers.ts`, `AppWindow` + `renderAppContent`
   switch, BootScreen, `useOverlayState`, `useKeyboardShortcuts` (Cmd+K).
6. `useWorkspaces` (active workspace context) + Workspace switcher + Create-workspace dialog.
7. `useBilling` + tier gating (`getEffectiveTier` → capabilities → `useFeatureGate`) + Upgrade/TrialExpired modals.

**Phase 2 — The product's core loop (Chat).**
8. **Chat** (`chat`) end-to-end: `POST /api/chat` fetch-stream parser → `ContentBlock[]`, all SSE events,
   inline approvals (`POST /api/approval/:id`), history, model switch, pins, feedback. This is the single
   highest-value screen — do it first and well.
9. **Dashboard / Home** (`dashboard`) — cheap, gives a landing surface (`/api/memory/stats`, `/api/tasks`).

**Phase 3 — Memory moat (the strategic lock-in).**
10. **Memory** (`memory`): Frames + Knowledge Graph tabs first, then **Harvest** (import is the moat: scan +
    preview/commit + progress SSE), then Wiki, then Evolution.
11. **Files** (`files`) — workspace file CRUD + upload/download.

**Phase 4 — Real-time ops + agents.**
12. **Events** (`events`, SSE), **Room** (`room`, `subagent_status` SSE), **Waggle Dance** (`waggle-dance`, SSE).
13. **Personas/Agents** (`agents`) + Spawn agent dialog + Mission Control (`mission-control`, fleet).
14. **Scheduled Jobs** (`scheduled-jobs`), **Notifications** inbox.

**Phase 5 — Extensibility + monetization surfaces.**
15. **Skills & Apps** (`capabilities`) + **Marketplace** (`marketplace`) + **Connectors** (`connectors`) +
    **Vault** (`vault`) — these are the upgrade triggers; wire 403→Upgrade carefully.
16. **Settings** (`settings`), **My Profile** (`profile`), **Cockpit** (`cockpit`) + Compliance.

**Phase 6 — Governance / admin / polish.**
17. **Approvals** (`approvals`, TEAMS+), **Team Governance** (`governance`, TEAMS+), **Timeline** (`timeline`),
    **Telemetry** (`telemetry`), **Backup** (`backup`), **Erase data** (GDPR).
18. **Onboarding wizard** (8 steps) + Login briefing + Global search polish.
19. **Light mode** pass.

**Rationale:** Phases 0–1 are non-negotiable scaffolding. Chat (Phase 2) is the product. Memory/Harvest (Phase 3)
is the strategic moat ("free forever" lock-in). Real-time + agents (Phase 4) prove the "OS" thesis.
Monetization surfaces (Phase 5) are where tier gating earns money. Governance + polish (Phase 6) come last.

---

## 7. Gotchas checklist (the things that bite a rebuild)

- [ ] Chat is **POST-SSE**, not `EventSource` — parse the body stream manually.
- [ ] Body-less POSTs must **not** send `Content-Type: application/json`.
- [ ] `EventSource` can't send Bearer headers — the SSE streams are **same-origin gated**; proxy or polyfill in dev.
- [ ] Run tier through **`getEffectiveTier`** before gating (expired TRIAL → FREE).
- [ ] `-1` in any capability/limit means **unlimited**, not "zero/disabled".
- [ ] Reproduce the §1.4 read normalizers or the UI breaks on renamed fields.
- [ ] Echo back `sourceWorkspaceId` verbatim when resolving approvals.
- [ ] After Stripe redirect, call `POST /api/stripe/sync { sessionId }` — do not trust the webhook for desktop.
- [ ] Handle two `done` usage shapes (agent-loop vs echo/command path).
- [ ] `/api/notifications/stream`: `notification` is an **unnamed** frame (`onmessage`); the others are named events.
- [ ] All `/api/*` paths are **flat** — no plugin prefix; the literal path in the table IS the path.
- [ ] Respect rate limits (chat 120/min, vault reveal 5/min, backup/restore 2/min) — handle `429` + `Retry-After`.