waggle-os/docs/design_handoff_waggle_app/SCREENS.md

# SCREENS.md — Per-screen specifications

Companion to `README.md`. Every screen shares the tokens in §7 and the global
patterns in §6 of the README; only screen-specific detail is below. **"Ship"** notes
which variation is the chosen default (others are alternates to wire as routes/state
or drop).

Prototype chrome to ignore when porting: the top **segmented control** (variation
switcher), the **☾ theme button**, and the **"· variation"** labels — all
demonstration-only.

---

## 01 · Home / Cockpit — `home.html`  → **Ship: Variation A (Editorial)**

**Purpose:** the daily landing. Opens with one human sentence, tells the overnight
story, offers one obvious next move.

**Layout:** single centered column, max-width 920px, 46px top padding.
- **Greeting:** mono date row (`--honey`) with a live dot + a **🔥 streak chip**
  (right-aligned pill, `--honey-wash` bg, `--honey-line` border). H1 = Hanken 600,
  clamp(34→52px); the word "ahead" is honey (not italic).
- **Overnight hero card:** radius `--r-xl`, gradient `--surface → --surface-2`,
  `--shadow`, a soft honey radial glow top-right. Mono eyebrow "While you slept"
  (`--intel` dot). Large statement line (Hanken 600, clamp 21→28px) with honey key
  numbers. Row of "run chips" (status dot + label) below.
- **"Pick up where you left off":** 2-col grid of workspace cards (hex avatar,
  title, time, summary, "Continue →", optional status badge).
- **"Waggle suggests":** stacked action rows (tinted icon tile, title, sub, arrow
  that slides on hover).
- **Ask bar:** pill, full-width, honey "+" icon, "⌘K" hint, honey send button.

**Copy (exact):** "Good morning, Mara." / "You're **ahead** of yesterday." ·
"While you slept" · "Waggle finished the **Q2 competitor teardown**, folded **14 new
memories** into the hive, and ran into **one snag** worth a look." · run chips:
"Teardown drafted · 9 competitors", "14 memories consolidated", "2 artifacts created",
"1 export failed".

**Variations:** A Editorial (ship) · B Focus (single centered ask + resume list) ·
C Operator (dense dashboard: overnight stats, active workspaces, up-next, agents,
a risk alert for the failed Salesforce export).

---

## 02 · Chat / agent runtime — `chat.html`  → **Ship: Variation B (Split work canvas)**

**Purpose:** the core work surface. Conversation leads; the agent's thinking, tool
calls, memory writes, and approvals reveal progressively; a live artifact builds in a
side canvas.

**Layout:** context header (workspace hex + name + "142 memories · 9 sources" +
**model pill** "auto · Claude Sonnet" + memory icon) → scrolling thread (max 760px,
narrows to ~620px when canvas open) → composer. **Variation B** adds a right **work
canvas** (~42% width) showing a live-drafting `teardown.md`.

**Thread components:**
- **User message:** `--surface` bubble, asymmetric radius `4px 14px 14px 14px`.
- **Bot message:** hex "W" avatar; "Waggle · Analyst · Claude Sonnet" meta.
- **Activity stream** (the "magic"): collapsible card, `--bg-2`, violet spark icon.
  Header "Worked across memory, web & files · 6 steps · 38s" + chevron. Steps each
  have a colored dot, text, and a **provenance pill** (`⬡ mem://hive · provenance
  kept`, mono, `--intel`). Default-open on the active turn.
- **Approval card:** `--honey-wash` bg, attention border, warning icon, "Approve
  before I leave your machine", mono target `Salesforce › Q2 Pricing`, "Approve &
  export" / "Not now".

**Composer:** rounded box, textarea, attach / "Persona: Analyst" / Tools chips, mono
"⏎ send · ⌘K commands" hint, honey send.

**Interaction:** clicking an activity header toggles its steps. Variation B canvas
has a blinking honey type-cursor on the live draft.

---

## 03 · Workspace — `workspace.html`  → **Ship: Variation A (Overview + tabs)**

**Purpose:** the calm home for one project; makes memory tangible.

**Layout:** header (breadcrumb, 46px hex avatar, title, meta row "1 agent live · 142
memories · 9 sources · updated 2h", "Memory"/"Continue" buttons) → **tab bar**
(Overview · Chat 3 · Memory 142 · Artifacts 7 · Files 12 · Team 4; honey underline on
active) → content. Overview = 2-col grid (1.7fr / 1fr):
- **Left:** summary card; **"What Waggle knows"** (fact rows, each with a hex check
  tile + `⬡ source · when` provenance); **"Recent work"** (artifact rows, ext tile +
  name + provenance + time).
- **Right:** Status card (agent live, model, memories +6 today, 3 to review); Up next;
  Team (avatar rows).

**Memory stays a tab** here (do NOT make the graph the default). Variation B
(Memory-forward, with the knowledge-graph viz) is an **alternate**, not the default.

---

## 04 · All workspaces — `workspaces.html`

**Purpose:** answers "where are all my workspaces?" The full shelf (Home = your day;
this = everything).

**Layout:** header ("Workspaces" + "New workspace"), toolbar (search "…or ask the
agent to find one" + storage filter pills All/Local/Virtual/Team), then **Grid** or
**Table** (segmented). Cards: hex avatar, title, **storage badge** (Local=honey,
Virtual=intel, Team=healthy), summary, meta (memories, "agent live", "N to review",
"Open →"). 8 sample workspaces across all three storage types. A note explains it's
reachable from rail, ⌘K, or any workspace switcher.

---

## 05 · Sidebar + ⌘K — `ia.html`

**Purpose:** the calm spine + the command bar holding all depth.

**Sidebar:** workspace switcher pill (hex + name + chevron) → 5 nav items (Home, Chat,
Memory, Agents & tasks [badge 2], Library) with honey active state (left honey bar +
`--honey-wash`) → "Everything else" → **⌘K tile** → spacer → user row.
**Pro variation** inserts a "Pinned · power tools" group (Agent swarm, Connectors,
Approvals [badge]).

**⌘K palette:** centered modal over a dim/blur scrim; search input + "esc" chip;
grouped results (Jump to / Do / Power tools), each = icon + **plain name** + mono
**subtitle** (technical term) + optional shortcut. First result auto-selected.
**Pro mode** prepends "★ Pinned · Pro" (honey group header + star markers). Hotkey
⌘/Ctrl-K toggles; Esc closes; clicking a result routes + closes.

**Key copy patterns:** "Run a team of agents · waggle-dance · swarm" · "Connect a
tool · MCP servers · 21 tools" · "Launch a coding agent · Claude Code · Cursor · Codex"
· "Tune the agent · GEPA optimizer" · "Secrets · encrypted vault".

---

## 06 · Launcher (AI-OS) — `launcher.html`

**Purpose:** detect & launch external coding agents **into a workspace's shared
memory**. (The shipped app calls this "minimal-viable" — this makes it first-class.)

**Variation A (Launch):** header + platform pill "⌘ macOS · 7 tools scanned"; an
optional **launch-with-a-task** prompt box (with "Sent to: Claude Code, Cursor ·
Ignored by: Claude Desktop"); **Detected** tool cards (Claude Code [Hooks active,
Running], Cursor, Codex [hooks soon], Claude Desktop [no-prompt]) each with
installed/version/path, badges, and **Launch in workspace / Stop / Install·Verify
hooks** actions; **Not installed** group (Hermes, OpenClaw); a **"Running now"** panel
(PID + duration + Stop).

**Variation B (How memory is shared):** a 3-node flow — `Claude Code →
WAGGLE_WORKSPACE_ID → 5 hive-mind hooks → your hive` — plus three cards (recalls on
start / commits as it works / reversible & local) and a provenance example
`⬡ remembered from Claude Code · 14:22 · session a1f9`.

**Implementation note:** the env var `WAGGLE_WORKSPACE_ID` and the SessionStart/Stop/
PreCompact/etc. hooks are real repo concepts — wire to the actual launcher service.

---

## 07 · Storage & Files — `storage.html`

**Purpose:** make the filesystem legible — where a workspace lives (virtual/local/team).

**Variation A (Where it lives):** a "live location" card (hex avatar, "Local · private"
pill) showing the real on-disk tree (`~/Waggle/workspaces/competitive-intelligence/`
→ `hive.mind` 3.2 MB · 142 memories, `files/`, `artifacts/`, `workspace.json`); then
**three storage-type cards** — Virtual (Waggle-managed, intel), Local (a folder on
your machine, honey, "this one"), Team (shared/synced, healthy) — each with a privacy
pill; then a local-first reassurance.

**Variation B (Files):** classic browser — left folder tree, breadcrumb + New
folder/Upload, a file table with a **Source/provenance column** (incl. `board-brief.md`
"made by Claude Code"), and a status bar naming the exact local path.

**Maps to repo `StorageType = 'virtual' | 'local' | 'team'`.**

---

## 08 · Power surfaces — `surfaces.html`

**Purpose:** the long tail on one consistent template, behind ⌘K. Left rail switches
**Tools · Automations · Approvals · Vault · Usage**; main = `.shead` + rows.
- **Tools:** connected integrations (Salesforce/Slack/GitHub), MCP servers (21 tools),
  available connectors.
- **Automations:** scheduled jobs with **working enable/pause toggles**; the failed
  "Q2 pipeline sync → Salesforce" (auth expired) with "Fix & retry".
- **Approvals:** risk-badged action cards (Approve/Deny/Always-allow) + recently decided.
- **Vault:** masked keys (`sk-ant-•••3a9f`) with Rotate/Reveal/Renew; "encrypted,
  never shown to a model".
- **Usage:** spend stat cards, per-model bars, per-workspace breakdown, budget.

Build ONE row/card/toggle component set and reuse — the consistency is the usability fix.

---

## 09 · Marketplace — `marketplace.html`

**Purpose:** skills + connectors + MCP as **one shelf**, agent-searchable, super simple.

**Variation A (Browse & ask):** centered **agent-search bar** ("Describe what you want
to do…" → "Ask the agent"); example chips; **agent-suggestion box** that recommends a
connector + skill + tool, each with a "why" reason and an install button; an
**"N in this workspace" bar** (chips); category filter (All/Skills/Connectors/MCP);
card grid (kind badge, name, desc, install count, Add button).

**Variation B (Inline in chat):** the same picker surfaced mid-conversation — Waggle
offers a missing Salesforce connector with a vault-aware approval ("token goes to your
vault"), then shows the connected follow-up.

**CRITICAL — shared install state ("sync"):** one store powers the grid, the agent
picks, AND the inline card. Type-aware one-click flows with progress→done micro-states:
**skill** Add→Adding…→Added (instant); **connector** Connect→Signing in…→Connected
(~1.1s, token→vault); **MCP** Enable→Enabling…→Enabled. Each fires a toast and updates
the count bar. Installing in any view reflects in all of them.

---

## 10 · Onboarding — `onboarding.html`

**Purpose:** ≤2-minute first-run, ending **inside the work**, not on a blank screen.

**6 steps** (full-screen takeover, progress bar, Back/Skip/Continue):
1. **Welcome** — "The workspace that remembers." local-first reassurance.
2. **About you** — name + role (single-select chips) + team size.
3. **Give it a brain (MODEL GATE)** — two tabs: **API key** (provider chips +
   live-validated key field, "✓ valid", "encrypted in your local vault") OR **local
   model** (detected Qwen running / Llama to pull). **Hard gate: cannot proceed to
   step 6 without one.**
4. **Import** — ChatGPT / Claude / Cursor / Start fresh (imported locally).
5. **Template** — Research / Strategy / Engineering / Sales / Writing / Custom.
6. **First task** — ask field + suggested tasks → opens straight into the workspace.

The model gate is the single most important time-to-first-value fix — its permanent
home is Settings → Models (screen 11).

---

## 11 · Settings — `settings.html`

**Purpose:** calm, progressive-disclosure settings; **Models leads** with failover.

**Layout:** left rail (General · **Models** · Permissions · Plan · Team · Backup ·
Advanced) + a top-right **"Show: Essential / Standard / Everything"** control —
Advanced only appears at "Everything" (progressive disclosure).

**Models (lead):** a banner confirming ≥1 working model; the **"Model pilot" failover
chain** — **Primary** (Claude Sonnet, key set) → trigger "if it errors" → **Fallback**
(GPT-4o) → trigger "when you hit your daily budget" → **Budget** (Qwen local, running);
a **daily budget** input (switch at 80%); read-only provider-key list (manage in
Vault); local models list. **Maps to `defaultModel/fallbackModel/budgetModel` +
`budgetThreshold/dailyBudget`.**

**Other tabs:** General (theme cards, language, local-first on-always, erase data);
Permissions (default approval level radios + always-require list); Plan (Pro trial +
upgrade paths + KVARK); Team (connect a team server); Backup (export/import/encrypted
backup); Advanced (dev mode, telemetry, prompt shape, debug).

---

## 12 · Skill evolution + diffusion — `evolution.html`

**Purpose:** the second moat — skills improve themselves AND spread.

**Variation A (Evolution):** a skill card ("Competitor teardown") with a **version
ladder** v1 71% → v2 84% → v3 91% (best), each a scored bar + note; the v3 carries
"GEPA optimized · judged by 3 models". A "how it improves" explainer (optimizer
proposes, 3-model judge scores, ships only if it wins, old versions kept).

**Variation B (Diffusion):** two maps — a **skill** propagating from Research-synth to
2 agents + 1 teammate; a **tool recipe** (Salesforce export config) spreading across 2
workspaces. Signals `⬡ waggle-dance · skill_share` / `model_recipe`. "Suggest-then-
adopt; secrets stay per-vault."

---

## 13 · Auth (Clerk) — `auth.html`

**Purpose:** simple sign-in, with honest "account is optional / local-first" framing.

**Layout:** split — left brand panel ("Your work follows you, everywhere." + trust
lines: "An account is optional — Waggle runs fully local without one") / right form.
**States:** Sign in (Google/Apple SSO + email/password) · Sign up (with local-first
note) · **Verify** (6-box OTP, auto-advance, backspace nav) · **SSO/enterprise** (SAML/
SCIM note → Teams/KVARK). Continue routes to Home. Build with Clerk components themed
to the tokens.

---

## 14 · Billing (Stripe) — `billing.html`

**Purpose:** frictionless upgrade. **4 states (segmented):**
- **Plans:** monthly/annual toggle (−20%), 3 cards (Solo current / **Pro popular** /
  Teams), honey "Most popular".
- **Checkout:** 2-col — card form (email, card 4242…, expiry/CVC, name, country,
  "encrypted & secure", "Powered by Stripe") + **order summary** (plan row, line items,
  promo, trial-aware "Due today $19", "won't be charged until …").
- **Success:** healthy check ring, "You're Pro.", receipt, "Start using Pro" / "Manage".
- **Manage:** current plan, billing cycle (switch to annual), payment method (VISA
  ···4242, Update), next charge, **invoices** (Paid + PDF), change plan / cancel.

Use Stripe Checkout/Customer Portal where possible; theme to tokens. Pricing: Solo $0
/ Pro $19 / Teams $49-seat.

---

## 15 · Habit loop — `habit.html`

**Purpose:** document the engagement layer — "momentum, not manipulation."

**Content:** a 4-stage loop (Trigger → Action → Variable reward → Investment); then 4
concrete mechanics — **daily streak** (week dots + "12-day streak"), **compounding
memory** ("142 · +14 this week · top 8% by depth"), **while you were away** (variable
reward chips), **gentle nudges** (earned, not spam); closing **ethics note** (anchored
to real value, no dark patterns, all toggle-off-able). The **streak chip also appears
on Home** (screen 01). This is a spec/principles screen — implement the mechanics in
Home/notifications, not as a standalone page.

---

## 16 · App surfaces — `appsurfaces.html`

Six routes on one rail (ship as real routes):
- **Agents** — Working now / Idle / "Run a team of agents" (swarm). Status badges.
- **Room** — work alongside agents **live**: shared stage of turns + participants
  panel (you host, agents live, teammate invited, "everyone shares this memory").
- **Artifacts** — 3-col card grid with ext tiles + **provenance** (incl. "made by
  Claude Code").
- **Mission Control** — hive health: stat row + local services list (memory engine,
  agent runtime, local model, Salesforce sync [auth expired], team sync [not connected]).
- **Timeline** — one chronological activity stream with source tags.
- **Profile** — what Waggle knows about you: name/role, "how I like to work" chips
  (every agent reads these), known-facts list, persona chips. This powers agent behavior.

---

## 17 · Benchmarks — `benchmark.html`

**Purpose:** honest positioning + the one real lab result. **2 views:**
- **Capabilities:** category framing ("They automate tasks. Waggle remembers you.") —
  two cards (Task agents = Claude Code/Codex/Cowork/Hermes/Odysseus vs Waggle = memory
  layer + workspace) + an **11-row capability matrix** (Waggle column honey-highlighted;
  ●/◐/○). Deliberately gives competitors ● on "deep terminal coding" (the last row) —
  credible, not stacked. Labeled "a positioning view, not a lab benchmark."
- **Memory SOTA:** the LoCoMo bars (87.66 / 81.95 / 78.05 / 62.47) + stats (+5.71pp,
  p<10⁻⁵; 92.75% single-hop; 100% local 58–83ms) + method/caveat.

Keep the matrix honest and the numbers accurate to the `hive-mind` benchmark.

---

## 18 · Platform & roadmap — `platform.html`

**Purpose:** the Tauri desktop story + roadmap. **4 views:**
- **Desktop (now):** a desktop-window mock with **macOS ↔ Windows** title-bar toggle
  (traffic lights vs min/max/close), a mini app inside; spec tiles (~12 MB, local,
  auto-update signed/notarized, Win·Mac, Linux soon).
- **Boot:** honey hex mark (pulsing), "Warming the hive…", checklist (memory engine
  ready, local model online, loading workspaces [spinner], restoring session).
- **Coming next:** channel cards — Desktop (now) · Browser extension (beta) ·
  **Messaging (WhatsApp/Telegram/iMessage) — coming next** · **Mobile (iOS/Android) —
  coming next**.
- **404:** big honey "404", "This cell of the hive is empty.", back-to-Home / ⌘K.

---

## Ship-variation summary

| Screen | Ship this | Alternates (wire as routes/state or drop) |
|--------|-----------|-------------------------------------------|
| Home | A Editorial | B Focus, C Operator |
| Chat | B Split work-canvas | A Conversation-first |
| Workspace | A Overview+tabs (Memory = tab) | B Memory-forward graph |
| Workspaces | Grid default | Table |
| Launcher | A Launch (B = explainer) | — |
| Storage | A Where-it-lives + B Files (both real) | — |
| Marketplace | A Browse+ask + B inline (both real) | — |
| Settings | Models-first, Essential default | Standard/Everything levels |
| Evolution / Benchmark / Platform | both views are real tabs | — |