moving

docs/design_handoff_waggle_app/README.md

@@ -0,0 +1,333 @@
+# Handoff: Waggle — App + Landing Refactor (the "warm Hive" concept)
+
+> A complete design concept for refactoring **Waggle OS** — the persistent-memory,
+> local-first, model-agnostic AI workspace (monorepo: `marolinik/waggle-os`,
+> memory substrate: `marolinik/hive-mind`). This package contains **22 interactive
+> HTML design references** plus the design-system stylesheet, and the brief to
+> recreate them in the real codebase.
+
+---
+
+## 1. Overview
+
+Waggle is a workspace-native AI agent platform: persistent memory that compounds,
+model-agnostic orchestration (Claude / GPT / Gemini / **local** models), a skills +
+connectors marketplace, a multi-agent "waggle-dance" swarm, and an "AI-OS" launcher
+that runs external coding agents (Claude Code, Cursor, Codex…) **inside a workspace's
+shared memory**. It ships as a **Tauri desktop app for Windows + macOS**.
+
+This concept is a top-to-bottom redesign addressing five problems found in the live
+product:
+
+1. **Overloaded navigation** — ~18 always-visible destinations across 5 zones.
+2. **Engineer-first language** — "Spawn", "Waggle-Dance", "MCPs", "GEPA".
+3. **Uniform 10–13px density** — reads as a control panel, never premium.
+4. **Five semantic colors firing at once** over glass + wallpaper + honeycomb.
+5. **Hidden differentiators** — memory, overnight work, coordination buried in tallies.
+
+The response is a **warmer "Hive" identity**, a **5-item spine + ⌘K command bar**
+(progressive disclosure), **plain-language labels with the technical term as a
+subtitle**, and **legible "hero moments"** for the differentiators.
+
+**Target users:** knowledge workers / operators (non-technical first), without
+removing any depth power users need.
+
+---
+
+## 2. About the design files (READ THIS FIRST)
+
+The files in `design-files/` are **design references created in HTML** — interactive
+prototypes that show intended **look, layout, copy, and behavior**. They are **not
+production code to copy verbatim.**
+
+**Your task:** recreate these designs inside the **existing Waggle codebase**
+(`apps/web` is React + TypeScript + Vite + Tailwind + shadcn/ui + React Router;
+`apps/www` is the Next.js marketing site), using its established components,
+routing, state, and data layer. Where this concept introduces a new pattern (e.g.
+the ⌘K palette, the warm token set), implement it in the codebase's idiom — don't
+paste HTML/inline styles.
+
+Two files are the entry points:
+- **`Waggle Reimagined.html`** — the concept narrative + an index that embeds every
+  app screen in an iframe. Open it first; its top nav links to every section.
+- **`Waggle Landing.html`** — the redesigned public marketing site (`apps/www`).
+
+Everything shares **one stylesheet: `design-files/styles/waggle.css`** — the source
+of truth for tokens (see §7).
+
+---
+
+## 3. Fidelity
+
+**High-fidelity.** Final colors, typography, spacing, radii, shadows, motion, and
+copy are all intentional and specified in §7 and the per-screen appendix (§10).
+Recreate the UI pixel-faithfully using the codebase's existing libraries — map the
+tokens in `waggle.css` onto the Tailwind theme / CSS variables, then build screens
+with shadcn/ui primitives styled to match.
+
+One caveat: the prototypes use vanilla JS for view-switching and the dark/light
+toggle. That plumbing is **demonstration scaffolding** — replace it with real React
+state, React Router routes, and the app's theme provider. The visuals, layout, and
+interaction *design* are what to preserve.
+
+---
+
+## 4. Information architecture (the spine)
+
+Collapse ~18 destinations into **5 everyday places**, with everything else reachable
+from **⌘K**:
+
+| Spine item        | Plain label        | Maps to existing routes / apps |
+|-------------------|--------------------|--------------------------------|
+| Home              | Home               | `/home` (HomeCockpit)          |
+| Chat              | Chat               | the agent runtime / chat       |
+| Memory            | Memory             | `/memory` + per-workspace Memory tab |
+| Agents & tasks    | Agents & tasks     | `/agents` + `/automations` + `/approvals` |
+| Library           | Library            | `/artifacts` + `/files` + `/skills` |
+
+**⌘K command bar** holds the full depth, each entry **plain-language with the
+technical term as a subtitle** (e.g. "Run a team of agents · waggle-dance · swarm";
+"Connect a tool · MCP servers"; "Launch a coding agent · Claude Code · Cursor").
+A **Pro mode** floats a "★ Pinned" group of power tools to the top of ⌘K.
+
+Reference: `screens/ia.html` (working sidebar + ⌘K + Pro toggle).
+
+---
+
+## 5. The screens (what's in this bundle)
+
+22 interactive references. Most use a top **segmented control** to switch
+variations or sub-views — that chrome is prototype-only; ship the chosen variation
+(noted per screen in §10) or wire the others as real routes/states.
+
+| # | File | Screen(s) | Notes |
+|---|------|-----------|-------|
+| — | `Waggle Reimagined.html` | Concept index + narrative | embeds all app screens; coverage map at the end |
+| — | `Waggle Landing.html` | Marketing site (`apps/www`) | hero, BYO-agent, proof (SOTA), self-evolve, personas, pricing, footer |
+| 01 | `screens/home.html` | Home / Cockpit | **ship variation A (Editorial)**; B/C are alternates |
+| 02 | `screens/chat.html` | Chat / agent runtime | **ship variation B (split work-canvas)** as default |
+| 03 | `screens/workspace.html` | Single workspace | **ship variation A (Overview+tabs)**; Memory stays a tab |
+| 04 | `screens/workspaces.html` | All-workspaces index | grid + table; storage badges; search/filter |
+| 05 | `screens/ia.html` | Sidebar + ⌘K command bar | calm spine + Pro-pinned |
+| 06 | `screens/launcher.html` | Launcher (AI-OS) | external agents share workspace memory |
+| 07 | `screens/storage.html` | Storage & Files | virtual/local/team model + file browser |
+| 08 | `screens/surfaces.html` | Power surfaces | Tools · Automations · Approvals · Vault · Usage |
+| 09 | `screens/marketplace.html` | Marketplace | agent-searchable; **shared install state ("sync")**; inline-in-chat |
+| 10 | `screens/onboarding.html` | First-run (6 steps) | includes the **required model gate** |
+| 11 | `screens/settings.html` | Settings | progressive disclosure; **Models + failover pilot** |
+| 12 | `screens/evolution.html` | Skill evolution + diffusion | the second moat |
+| 13 | `screens/auth.html` | Auth (Clerk) | sign in/up, OTP verify, SSO |
+| 14 | `screens/billing.html` | Billing (Stripe) | plans → checkout → success → manage |
+| 15 | `screens/habit.html` | Engagement / habit loop | streak, compounding, variable reward, nudges |
+| 16 | `screens/appsurfaces.html` | Agents · Room · Artifacts · Mission Control · Timeline · Profile | six routes, one rail |
+| 17 | `screens/benchmark.html` | Benchmarks | capability matrix vs competitors + LoCoMo SOTA |
+| 18 | `screens/platform.html` | Platform & roadmap | Tauri desktop, boot, 404, "coming next" |
+
+Per-screen detail (layout, components, copy, interactions, ship-this-variation) is
+in **§10**.
+
+---
+
+## 6. Global patterns (apply everywhere)
+
+- **App chrome:** left **sidebar** (5 items + workspace switcher + user row), main
+  column with a **`.shead`** (title + subtitle + primary action) over a scrolling
+  body. Power surfaces and Settings use a **secondary left rail** inside the main column.
+- **Density & scale:** body 16px / 1.55; never below 12px. Section labels are
+  11px mono, uppercase, `.12em` tracking, `--text-dim`, with a trailing hairline rule.
+- **One accent:** honey (`--honey`) is used sparingly — primary buttons, active nav,
+  key numbers, focus. Semantics (work/intel/healthy/attention/risk) are **desaturated**
+  and only for status, never decoration.
+- **Provenance everywhere:** any memory/fact/artifact shows a `⬡ source · when` line in
+  mono / `--intel`. This is a core trust pattern — keep it.
+- **Cards:** `--surface` bg, `1px solid --line-soft`, radius `--r-lg` (18px),
+  hover → `--honey-line` border + `translateY(-2px)` + `--shadow`.
+- **Buttons:** primary = honey bg / `#1a1407` text; ghost = `--surface` / `--line-strong`
+  border, hover honey border. Radius 9–13px. See §7.
+- **Dark + light:** every screen supports both via `[data-theme]`. The toggle in the
+  prototypes writes `localStorage['waggle-concept-theme']`; replace with the app theme
+  provider. Both themes are warm (warm graphite ↔ warm paper) — see §7.
+- **Motion:** entrances `cubic-bezier(.16,1,.3,1)` ~.7s, gated so content is visible
+  if JS/print/reduced-motion. Hover transitions .14–.18s. A live "breathing" dot
+  (`@keyframes breathe`) marks active/live status. Honor `prefers-reduced-motion`.
+- **Focus:** `2px solid --honey`, `2px` offset. Keep keyboard access on ⌘K, OTP, forms.
+
+---
+
+## 7. Design tokens (source of truth: `styles/waggle.css`)
+
+Map these onto the codebase's Tailwind theme + CSS variables. **Dark is default;**
+`[data-theme="light"]` overrides. All radii/type/shadow tokens are theme-independent.
+
+### Colors — Dark (default)
+```
+--bg:          #14110b   (app background, warm near-black)
+--bg-2:        #1a160f   (recessed panels, rails)
+--surface:     #1f1a12   (cards)
+--surface-2:   #272117   (hover / insets)
+--surface-3:   #322a1d   (chips, icon tiles)
+--line:        #38301f   (default border)
+--line-soft:   #2a2417   (subtle dividers)
+--line-strong: #4a4030   (emphasized border / scrollbar)
+--text:        #f6f1e4   (primary)
+--text-2:      #c8bfa9   (secondary)
+--text-muted:  #948a73   (tertiary / body-muted)
+--text-dim:    #6b6250   (labels, meta)
+```
+### Colors — Light (`[data-theme="light"]`)
+```
+--bg:#f7f1e4  --bg-2:#f1e9d8  --surface:#fffdf8  --surface-2:#f6efe0  --surface-3:#efe6d2
+--line:#e4d8be  --line-soft:#ede3cd  --line-strong:#d2c3a2
+--text:#211b11  --text-2:#5a5140  --text-muted:#847a64  --text-dim:#a99e85
+```
+### Accent — Honey (the one accent)
+```
+Dark:   --honey:#e9a52c  --honey-bright:#f6c45a  --honey-deep:#c07e16
+Light:  --honey:#b57d12  --honey-bright:#cf932a  --honey-deep:#92620a
+--honey-wash: rgba(honey, .10)   (tinted fills)
+--honey-line: rgba(honey, .28)   (tinted borders)
+--honey-glow: 0 0 0 1px rgba(honey,.25), 0 8px 30px -10px rgba(honey,.35)
+On honey buttons, text/icon color is #1a1407.
+```
+### Semantics (desaturated; status only) — Dark / Light
+```
+--work     #7aa6d6 / #3f72b0   (tasks, workspaces, blue)
+--intel    #b196dd / #7d57b8   (memory/intelligence, violet) — also provenance
+--healthy  #6cb78c / #3c8a5f   (complete/healthy, sage)
+--attention#e9a52c / #b57d12   (attention/automation = honey)
+--risk     #db8068 / #c0573c   (risk/failure, terracotta)
+Each has a matching *-wash at ~.12 alpha for tinted chips/fills.
+```
+### Typography
+```
+--sans:  'Hanken Grotesk', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif
+--mono:  'JetBrains Mono', ui-monospace, monospace
+--serif: var(--sans)   ← display intentionally uses the SAME grotesk (no book-serif)
+
+Display headlines: Hanken Grotesk 600, letter-spacing -0.02 to -0.03em.
+  - Hero (landing): clamp(40px, 5.6vw, 68px)
+  - Section H2:     clamp(28px, 3.8vw, 44px)
+  - Screen H1:      ~24–28px / 650
+Body: 14–16px / 400–550, line-height ~1.55.
+Labels/meta: 10–12px JetBrains Mono, uppercase, letter-spacing .10–.14em.
+Honey words in headlines are NOT italic — same weight, just --honey color.
+```
+### Radius / Shadow / Misc
+```
+--r-sm:8px  --r:12px  --r-lg:18px  --r-xl:26px   (pills/toggles: 999px)
+--shadow-sm: 0 1px 2px rgba(0,0,0,.4)
+--shadow:    0 4px 24px -8px rgba(0,0,0,.55), 0 1px 2px rgba(0,0,0,.4)
+--shadow-lg: 0 24px 60px -20px rgba(0,0,0,.7), 0 2px 8px rgba(0,0,0,.4)
+--shadow-pop:0 30px 80px -24px rgba(0,0,0,.8)
+(light theme has softer brown-tinted equivalents — see waggle.css)
+Hexagon motif: .hex { clip-path: polygon(50% 0,100% 25%,100% 75%,50% 100%,0 75%,0 25%); }
+  used for the brandmark, agent/workspace avatars, icon tiles.
+Honeycomb texture: .comb (inline SVG bg at ~.05 opacity) — very subtle, decorative only.
+Live dot: .dot-live → @keyframes breathe (2.4s).
+```
+
+---
+
+## 8. Cross-cutting behaviors to implement
+
+- **⌘K command palette** (`screens/ia.html`): global hotkey (⌘/Ctrl-K) toggles a
+  centered modal; fuzzy filter over grouped commands; arrow/Enter/Esc keyboard nav;
+  groups = Jump to / Do / Power tools; Pro mode prepends a "★ Pinned" group. Each
+  result = plain name + mono subtitle (technical term). Routes to real destinations.
+- **Theme:** dark default; persist user choice; both themes are warm. Use the app
+  theme provider, not localStorage scaffolding.
+- **Marketplace install = one shared state** (`screens/marketplace.html`): a single
+  install store drives the grid, the agent-suggestion picks, AND the inline-in-chat
+  card — installing anywhere reflects everywhere ("sync"). Type-aware one-click flows:
+  **skill** = instant Add; **connector** = "Connect" → auth → token to Vault;
+  **MCP** = "Enable" tools. Each fires a confirmation toast + updates an
+  "N in this workspace" bar.
+- **Onboarding model gate** (`screens/onboarding.html`, step 3): the flow **cannot
+  reach "first task" without a working model** — either a validated provider API key
+  or a detected/running local model. This mirrors the hard requirement that Waggle
+  needs ≥1 working model. The same gate's permanent home is Settings → Models.
+- **Model failover pilot** (`screens/settings.html`): Primary → **Fallback on
+  error** → **Budget/local model when daily budget hit**. Maps to the repo's
+  `defaultModel / fallbackModel / budgetModel` + `budgetThreshold / dailyBudget`.
+- **Provenance** on every memory/artifact/fact (see §6).
+- **Approvals**: agent actions that touch external systems gate on a risk-badged
+  approval card (inline in chat + an Approvals surface). "Always allow for this
+  workspace" is an option.
+
+---
+
+## 9. The marketing site (`Waggle Landing.html` → `apps/www`)
+
+Full content rewrite + new identity. Sections in order: nav → hero ("Your AI
+doesn't reset. Your work doesn't either.") → trust band → problem → 6 pillars →
+how-it-works (3 steps) → **Bring-your-own-agent** band (launch Claude Code/Cursor/Codex
+into shared memory) → **Proof** (LoCoMo SOTA: Waggle 87.66 vs Memori 81.95 /
+LangMem 78.05 / Mem0 62.47; +5.71pp, p<10⁻⁵; 92.75% single-hop; 100% local) →
+**Self-evolving** (skills improve 71→84→91% + diffuse across the hive) → personas
+(13) → pricing (Solo $0 / Pro $19 / Teams $49-seat + KVARK sovereign) → final CTA →
+footer. All copy is final; lift it verbatim. Reveal-on-scroll is JS-gated so content
+is always visible without JS (keep that property for SEO/no-JS).
+
+**Numbers come from the real benchmark docs / `hive-mind` repo. Keep them accurate;
+if the public claim must stay conservative until the SOTA PR merges, gate the headline.**
+
+---
+
+## 10. Per-screen specifications
+
+See **`SCREENS.md`** in this folder for the full per-screen breakdown (layout,
+components, exact copy, interactions, and **which variation to ship**).
+
+---
+
+## 11. Assets
+
+- **No raster assets / no external images.** All iconography is **inline SVG**
+  (1.7–1.8 stroke, round caps) — reuse the codebase's icon set (e.g. lucide) matched
+  to these shapes. The brandmark is the letter **W** in a `.hex` clip-path over a
+  honey gradient. The honeycomb texture is an inline SVG data-URI (`.comb` in
+  `waggle.css`).
+- **Fonts:** Hanken Grotesk + JetBrains Mono (Google Fonts). Self-host in the Tauri
+  app for offline use.
+- **Competitor / provider names** (Stripe, Clerk, Salesforce, Claude, GPT, etc.) are
+  shown as mono text/initials, not logos — swap in real logos per each brand's
+  guidelines if desired.
+
+---
+
+## 12. Tech mapping (existing monorepo)
+
+```
+apps/web   React + TS + Vite + Tailwind + shadcn/ui + React Router  → all app screens
+apps/www   Next.js marketing site                                   → Waggle Landing.html
+apps/browser-ext                                                    → roadmap (beta)
+packages/* core / memory (hive-mind) / agent runtime / connectors / mcp
+Desktop    Tauri (Windows + macOS)                                  → screens/platform.html
+Auth       Clerk    → screens/auth.html
+Billing    Stripe   → screens/billing.html
+```
+Recommended order: **(1)** tokens → Tailwind theme + theme provider; **(2)** app
+shell (sidebar + ⌘K); **(3)** Home, Chat, Workspace; **(4)** Marketplace + install
+store; **(5)** Settings (models/failover) + Onboarding gate; **(6)** the remaining
+surfaces; **(7)** Auth + Billing; **(8)** `apps/www` landing. Ship dark first.
+
+---
+
+## 13. Files in this bundle
+```
+design_handoff_waggle_app/
+├── README.md            ← this file
+├── SCREENS.md           ← per-screen specifications
+├── DESIGN_POV.md        ← designer's strategic contributions (incl. the built Trust layer)
+├── screenshots/         ← reference captures (1 per screen) + index
+│   ├── README.md
+│   └── 00–19 *.png
+└── design-files/
+    ├── Waggle Reimagined.html   ← concept index (open first)
+    ├── Waggle Landing.html      ← marketing site
+    ├── styles/waggle.css        ← design tokens (source of truth)
+    └── screens/*.html           ← 19 app-screen references
+```
+Open `design-files/Waggle Reimagined.html` in a browser and use its top nav to walk
+the whole concept; toggle dark/light with the ☾ button; try ⌘K inside the Navigation
+section.