@robbiesrobotics/alice-agents 1.5.7 → 1.5.9

package/templates/workspaces/olivia/MISSION_CONTROL_DESIGN_SPEC_v1.md

@@ -0,0 +1,1143 @@
+# Mission Control Pro — Complete Design Spec v1.0
+**Author:** Nadia (A.L.I.C.E. Design & UX Specialist)  
+**Status:** LOCKED — Felix implements from this. No design decisions during implementation.  
+**Date:** 2026-03-18
+
+---
+
+## TABLE OF CONTENTS
+
+1. [Emotional Target & Brand Philosophy](#1-emotional-target--brand-philosophy)
+2. [Design Token System](#2-design-token-system)
+3. [Brand Expression Guidelines](#3-brand-expression-guidelines)
+4. [Global Component Standards](#4-global-component-standards)
+5. [Mobile-First Breakpoints](#5-mobile-first-breakpoints)
+6. [Loading State Standard](#6-loading-state-standard)
+7. [Error State Standard](#7-error-state-standard)
+8. [Motion & Animation Principles](#8-motion--animation-principles)
+9. [First Login Experience](#9-first-login-experience)
+10. [Page Specs](#10-page-specs)
+    - [Login](#101-login)
+    - [Home (Dashboard)](#102-home-dashboard)
+    - [My Team](#103-my-team)
+    - [Sessions](#104-sessions)
+    - [Approvals](#105-approvals)
+    - [Workflows](#106-workflows)
+    - [Settings](#107-settings)
+11. [Copy & Language Standards](#11-copy--language-standards)
+
+---
+
+## 1. EMOTIONAL TARGET & BRAND PHILOSOPHY
+
+### The Emotional Target
+
+A user in Mission Control should feel:
+- **In control** — I can see everything, I can act on anything
+- **Informed** — I know what's happening right now, without digging
+- **Capable** — My team is running; I'm the one making it go
+- **Present** — This place feels alive, not archival
+
+A user should NOT feel:
+- Overwhelmed by data density
+- Confused about what to do next
+- Like they're managing tickets in a queue
+- Like they're looking at logs from a dead process
+
+### The Core Brand Story
+
+A.L.I.C.E. is a team of AI specialists, not a tool. Mission Control is where you manage that team. The design must reinforce this mental model at every touchpoint:
+
+- **Language:** "Your team" not "your agents." "In a session" not "running." "Waiting on you" not "pending."
+- **Presence:** Active agents should pulse. Running sessions should show live tickers. The UI communicates that your team is already working — you're checking in on them.
+- **Structure:** The layout should feel like a command center, not an admin panel. Information hierarchy matters: status first, then detail.
+
+### Palette Semantics (NON-NEGOTIABLE)
+
+| Color | Meaning | Do | Don't |
+|-------|---------|-----|-------|
+| Emerald-500 (`#00bb7f`) | Alive, working, healthy, success | Active status dots, success confirmations, primary CTAs | Decorative accents, borders for style |
+| Zinc-950/900 | Infrastructure, structure, the container | Backgrounds, surfaces | Text |
+| Zinc-400/500 | Secondary information, metadata | Supporting copy, timestamps | Primary actions |
+| Red-500 | Error, failure, danger | Error states only | Warning states |
+| Amber-400 | Warning, attention needed | Warnings, degraded states | Errors |
+| Blue-400 | Pending, in-progress, informational | Loading, pending approvals | Success |
+
+**The rule:** If you're using emerald, it must mean something is alive or succeeded. If nothing is alive or succeeded, don't use emerald.
+
+---
+
+## 2. DESIGN TOKEN SYSTEM
+
+### Canonical Token Values
+
+```css
+/* Backgrounds */
+--bg-base:     #09090b;   /* zinc-950 — page background */
+--surface-0:   #09090b;   /* zinc-950 — same as base */
+--surface-1:   #18181b;   /* zinc-900 — cards, panels */
+--surface-2:   #27272a;   /* zinc-800 — inputs, code blocks, nested surfaces */
+--surface-3:   #3f3f46;   /* zinc-700 — hover states on surface-2 */
+
+/* Text */
+--text-primary:   #fafafa;  /* zinc-50  — headings, important body */
+--text-secondary: #a1a1aa;  /* zinc-400 — supporting text, labels */
+--text-tertiary:  #71717a;  /* zinc-500 — placeholders, disabled, metadata */
+
+/* Borders */
+--border-subtle:  rgba(39,39,42,0.5);  /* zinc-800/50 */
+--border-default: #3f3f46;             /* zinc-700 */
+--border-strong:  #52525b;             /* zinc-600 */
+
+/* Accent */
+--accent:         #00bb7f;  /* emerald-500 — primary actions, active state */
+--accent-hover:   #00a36e;  /* emerald-600 — hover on accent elements */
+--accent-subtle:  rgba(0,187,127,0.1);  /* emerald for backgrounds/glows */
+--accent-text:    #00bb7f;  /* emerald text on dark surfaces */
+
+/* Status */
+--status-active:  #00bb7f;  /* emerald-500 */
+--status-error:   #ef4444;  /* red-500 */
+--status-warn:    #fbbf24;  /* amber-400 */
+--status-pending: #60a5fa;  /* blue-400 */
+--status-idle:    #52525b;  /* zinc-600 */
+
+/* Agent identity colors (intentional purple spectrum) */
+--agent-0: #8b5cf6;  /* violet-500 */
+--agent-1: #a855f7;  /* purple-500 */
+--agent-2: #c084fc;  /* purple-400 */
+--agent-3: #d946ef;  /* fuchsia-500 */
+--agent-4: #e879f9;  /* fuchsia-400 */
+--agent-5: #7c3aed;  /* violet-600 */
+--agent-6: #9333ea;  /* purple-600 */
+--agent-7: #a21caf;  /* fuchsia-700 */
+```
+
+### Token Usage Rules
+
+1. Never use raw hex values in components — always use tokens
+2. `--accent` is reserved for interactive/status meaning only
+3. Surface nesting: bg-base → surface-1 → surface-2 (max 3 levels deep)
+4. Agent colors are assigned by index at render time, stable per session
+
+---
+
+## 3. BRAND EXPRESSION GUIDELINES
+
+### The "A" Logo Mark
+
+**Logo anatomy:**
+- Square emerald box (`--accent`, 4px border-radius)
+- White "A" letterform, bold, centered
+- The box IS the brand mark — it appears everywhere the brand needs to be present
+
+**Usage rules:**
+
+| Context | Variant | Size | Spec |
+|---------|---------|------|------|
+| Sidebar (expanded) | Icon + wordmark "A.L.I.C.E." | Icon: 28×28px, text: 16px semibold | 8px gap between icon and text |
+| Sidebar (collapsed) | Icon only | 28×28px | Centered in sidebar |
+| Login page | Icon + wordmark stacked | Icon: 48×48px, text: 24px semibold | 12px gap, centered |
+| Browser tab (favicon) | Icon only | 16×16px | |
+| Email/notification | Icon only (if supported) | 32×32px | |
+
+**Spacing rule:** The logo always has at least its own width in clear space on each side.
+
+**Never:**
+- Stretch or recolor the emerald box
+- Use the wordmark without the icon mark
+- Place on a surface lighter than `--surface-1`
+- Use a different font for "A.L.I.C.E." — it is always the app's heading font, semibold
+
+### Wordmark Typography
+
+"A.L.I.C.E." uses the app's heading font (Inter or system font stack), weight 600, tracking normal. Never all-lowercase. The periods are part of the name.
+
+"Mission Control" appears as a subtitle below on login only — size 14px, `--text-secondary`, weight 400.
+
+---
+
+## 4. GLOBAL COMPONENT STANDARDS
+
+### The Decision: Hybrid with Clear Boundaries
+
+**AH (A.L.I.C.E. House) components win for:**
+- StatusDot / StatusBadge — all agent/session status indicators
+- AgentAvatar — all agent identity displays
+- SessionCard — all session list items
+- ApprovalCard — all approval items
+- SidebarNav — the global sidebar
+- PageHeader — top of every page
+- StatCard — dashboard metric cards
+
+**Shadcn wins for:**
+- Dialog / Sheet / Modal — all overlay/drawer patterns
+- DropdownMenu — all dropdown menus
+- Tooltip — all tooltips
+- Switch / Checkbox / RadioGroup — all form controls
+- Select / Combobox — all select inputs
+- Input / Textarea — all text inputs
+- Tabs — tab navigation within pages
+- Badge — generic status labels (but NOT agent/session status — use AH StatusBadge)
+- Table — data tables (but NOT sessions table — use AH SessionCard)
+- Skeleton — loading states
+- Toast / Sonner — notifications
+
+**The rule:** If an AH component exists for the concept, use it. Shadcn fills the gaps for generic form/overlay patterns. Never mix them on a single page without this justification.
+
+### No Mixing Rule
+
+A page may use both AH and shadcn components only when:
+1. They serve different levels (AH for domain concepts, shadcn for generic UI primitives)
+2. The AH component is not available for that specific pattern
+
+Settings was the offender — it now uses shadcn throughout (forms, inputs, tabs) with AH components only for agent-specific displays.
+
+---
+
+## 5. MOBILE-FIRST BREAKPOINTS
+
+### Breakpoint Scale
+
+```
+sm:  640px   — phone landscape / large phone
+md:  768px   — tablet portrait  
+lg:  1024px  — tablet landscape / small desktop
+xl:  1280px  — desktop
+2xl: 1536px  — wide desktop
+```
+
+### Sidebar Behavior by Breakpoint
+
+| Breakpoint | Sidebar | Content |
+|---|---|---|
+| < 640px (mobile) | Hidden, accessible via hamburger → Sheet overlay | Full width |
+| 640px–1023px (sm/md) | Collapsed icon rail (48px wide) | Remaining width |
+| 1024px–1279px (lg) | Expanded (220px) | Remaining width |
+| 1280px+ (xl) | Expanded (240px) | Remaining width |
+
+### Layout Grid by Breakpoint
+
+| Breakpoint | Columns | Gutter | Page padding |
+|---|---|---|---|
+| < 640px | 1 | 16px | 16px |
+| sm (640px+) | 1–2 | 16px | 24px |
+| md (768px+) | 2 | 24px | 32px |
+| lg (1024px+) | 2–3 | 24px | 32px |
+| xl (1280px+) | 3–4 | 32px | 40px |
+
+### What Changes at Each Breakpoint
+
+**< 640px (mobile):**
+- Sidebar hidden → hamburger menu in top bar
+- All tables become card stacks (no horizontal scroll)
+- Stat cards stack 1-per-row
+- Approvals: full-width stacked cards, approve/reject as full-width buttons
+- Sessions: full-width cards with truncated content
+- No inline split-panels; everything is single-column
+
+**640px–767px (sm):**
+- Sidebar icon rail visible
+- Stat cards: 2-per-row
+- Sessions: 2-column card grid
+- Approvals: still stacked but with horizontal action buttons
+
+**768px–1023px (md):**
+- Stat cards: 2–3-per-row
+- Sessions: list view or 2-column grid
+- Approvals: full layout minus detail panel
+
+**1024px+ (lg+):**
+- Full desktop layout
+- Approvals: master-detail panel layout
+- Sessions: full table or card list with metadata columns visible
+
+---
+
+## 6. LOADING STATE STANDARD
+
+### When to Use Skeleton vs Spinner
+
+| Pattern | Use When |
+|---------|---------|
+| **Skeleton** | Loading page-level content for the first time (data hasn't arrived yet, expected < 3s) |
+| **Skeleton** | Refreshing a list where we know the shape of content |
+| **Inline spinner** (16px) | A single action is in-flight (submitting a form, triggering an agent) |
+| **Button spinner** | A button has been clicked and is waiting for confirmation |
+| **Full-page spinner** | NEVER — always prefer skeleton |
+| **Overlay spinner** | Blocking modal action only (e.g., deleting an agent — can't navigate away) |
+
+### Skeleton Spec
+
+```
+Background: --surface-2 (#27272a)
+Shimmer: animate-pulse (opacity 0.4 → 1.0, duration 1.5s, ease-in-out)
+Border-radius: matches the component it's replacing
+Min-height: matches the approximate height of real content
+```
+
+**Skeleton variants to implement:**
+
+- `SkeletonStatCard` — 120px tall, full width of stat card
+- `SkeletonSessionCard` — 72px tall, full width of session card row
+- `SkeletonAgentCard` — matches AgentCard dimensions
+- `SkeletonApprovalCard` — matches ApprovalCard height
+- `SkeletonTableRow` — 3 lines: title, subtitle, badge
+- `SkeletonText` — generic line skeleton (widths: full, 75%, 50%)
+
+### Skeleton Counts
+
+| Page | Skeleton count on first load |
+|------|-----|
+| Home | 4× SkeletonStatCard, 3× SkeletonSessionCard |
+| My Team | 6× SkeletonAgentCard |
+| Sessions | 5× SkeletonSessionCard |
+| Approvals | 3× SkeletonApprovalCard |
+| Workflows | 4× SkeletonTableRow |
+| Settings | Section-level skeleton (don't skeleton individual fields) |
+
+### Transition from Skeleton → Content
+
+- Fade in: `opacity 0 → 1`, duration `200ms`, no layout shift
+- Stagger: 50ms delay between list items (max 5 items staggered, then simultaneous)
+
+---
+
+## 7. ERROR STATE STANDARD
+
+### Error Hierarchy
+
+**Level 1 — Inline field error:** Form validation failures
+- Red text below field, 12px, `--status-error`
+- Icon: `AlertCircle` (12px, inline before text)
+- Never use toast for field errors
+
+**Level 2 — Section error:** A card/section failed to load
+- Replace skeleton with an error card:
+  - Surface-1 background, red-500/20 border
+  - `AlertTriangle` icon (20px, `--status-error`)
+  - Message: "Couldn't load [section name]"
+  - CTA: "Try again" button (ghost, small)
+
+**Level 3 — Page-level error:** Full page failed (e.g., 500, auth failure)
+- Centered in content area
+- `AlertTriangle` icon (48px, `--status-error`)
+- Heading: "Something went wrong"
+- Body: Specific error message if available, otherwise: "We couldn't load this page. This is likely temporary."
+- CTA: Primary button "Reload page" + ghost button "Go home"
+
+**Level 4 — Toast notification:** Action failed (e.g., user triggered something that failed)
+- Sonner toast, variant: `error`
+- Duration: 5 seconds
+- Message: "[Action] failed — [brief reason if available]"
+- Example: "Couldn't approve task — please try again"
+
+### API Error Mapping
+
+| HTTP Status | UX Treatment |
+|-------------|-------------|
+| 401 | Redirect to login, no error shown |
+| 403 | Level 3 error: "You don't have access to this" |
+| 404 | Level 3 error: "[Resource] not found" |
+| 429 | Level 2 or 4 with "Too many requests — slow down" |
+| 500–503 | Level 3 with retry CTA |
+| Network offline | Persistent banner at top of page: "No connection — working offline" |
+
+---
+
+## 8. MOTION & ANIMATION PRINCIPLES
+
+### The Rule
+
+**Animate to communicate, never to decorate.**
+
+Every animation must answer the question: "what does this motion tell the user?" If there's no answer, remove it.
+
+### Animation Inventory
+
+| Element | Animation | Spec | Reason |
+|---------|-----------|------|--------|
+| Active status dot | Pulse ring (scale 1→1.5, opacity 1→0) | 2s loop, ease-in-out | "This agent is alive right now" |
+| Session duration ticker | Numeric increment | Real-time, no easing | Counter communicates live work |
+| Sidebar expand/collapse | Width transition | 150ms, ease-out | Spatial navigation |
+| Detail panel slide-in (Approvals) | Slide from right | 200ms, ease-out | Panel appears from its trigger |
+| Sheet/dialog open | Slide up (mobile) / fade+scale (desktop) | 200ms, ease-out | Standard shadcn behavior |
+| Page transitions | Fade | 150ms, ease | Not jarring |
+| Skeleton → content | Fade in | 200ms | Smooth reveal |
+| Toast appearance | Slide up from bottom | shadcn/sonner default | Don't override |
+| Button loading state | Spinner replaces text/icon | Immediate, no transition | Action feedback |
+| Hover on cards | Background shift to surface-2 | 100ms | Affordance |
+| Hover on nav items | Background shift | 100ms | Affordance |
+
+### What Does NOT Animate
+
+- Text content (no typewriter effects)
+- Color changes on status (instant — delayed color change is confusing)
+- Table sort/filter (instant)
+- Form inputs (instant focus ring)
+- Any "decorative" parallax or scroll effects
+- Stat card numbers (no counting animation — can feel like deception)
+
+### Reduced Motion
+
+All animations must respect `prefers-reduced-motion`. When reduced motion is enabled:
+- Remove pulsing status rings (show static dot)
+- Remove slide/fade transitions (instant show/hide)
+- Keep spinner (it's functional)
+- Keep duration ticker (it's informational)
+
+---
+
+## 9. FIRST LOGIN EXPERIENCE
+
+### The Problem
+
+A brand new Pro user has: 0 agents configured, 0 sessions, 0 approvals, 0 workflows. If we show empty states everywhere, it feels like a broken app. We need the first login to feel like a command center that's ready to activate — not a ghost town.
+
+### First Login Detection
+
+Detect "new user" state when: `agents.count === 0 && sessions.total === 0`
+
+This triggers the **Activation Mode** UX (described per-page below).
+
+### Global First Login Treatment
+
+**Welcome Banner** (appears once, dismissible, Home page only):
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  ⚡ Welcome to Mission Control                               │
+│  Your A.L.I.C.E. team is ready to be assembled. Start by   │
+│  adding your first specialist — they'll handle tasks,        │
+│  answer questions, and work while you sleep.                 │
+│                                                              │
+│  [Add your first agent →]              [Dismiss]             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+- Background: `--surface-1` with a subtle emerald-500/10 left border (4px)
+- Dismiss stores to localStorage, never shows again
+- CTA routes to My Team → Add Agent
+
+### First Login Per Page
+
+Each page spec below includes "First Login State" — what a zero-data user sees.
+
+---
+
+## 10. PAGE SPECS
+
+---
+
+### 10.1 LOGIN
+
+#### Layout Spec
+
+```
+All breakpoints: Single centered column
+Max-width: 400px
+Horizontal padding: 24px
+Vertical: Centered in viewport (flexbox, min-height 100vh)
+```
+
+**Structure:**
+```
+[A logo mark + "A.L.I.C.E." wordmark]  ← centered, 48px icon
+[Mission Control]                        ← 14px, text-secondary, 8px below wordmark
+[32px gap]
+[Email input]
+[Password input]  
+[16px gap]
+[Sign In — full width, primary button]
+[24px gap]
+[Forgot password — text link, centered, 14px]
+```
+
+#### Component Inventory (SHADCN throughout)
+
+- `Input` — email, password fields
+- `Button` — sign in (primary, full width)
+- Custom: Logo mark (AH component or inline SVG)
+- No card/surface wrapper — form floats directly on bg-base
+
+#### Empty / Zero State
+
+N/A — login has no empty state.
+
+#### Interaction Spec
+
+| Interaction | Behavior |
+|---|---|
+| Form submit | Button shows inline spinner (left of text), text stays visible, disabled state |
+| Failed login | Level 1 inline error below password field: "Incorrect email or password" |
+| Network error | Level 4 toast: "Sign in failed — check your connection" |
+| Success | Fade transition to Home (150ms) |
+| Enter key | Submits form if both fields populated |
+| Password field | Show/hide toggle (eye icon, right side of input) |
+
+#### Done Criteria
+
+- [ ] Logo matches sidebar exactly (same icon component)
+- [ ] Form is centered vertically on all screen sizes
+- [ ] Error states appear inline (not toast) for credential failures
+- [ ] Loading state on button during submission
+- [ ] Accessible: tab order Email → Password → Submit
+
+---
+
+### 10.2 HOME (DASHBOARD)
+
+#### Layout Spec
+
+**Desktop (lg+):**
+```
+PageHeader: "Mission Control" [greeting: "Good morning, Rob"]
+[Welcome Banner if first login]
+[Stat Cards row: 4 cards, equal width, gap-4]
+[16px gap]
+[2-column layout, 2/3 + 1/3]
+  Left: Active Sessions (list)
+  Right: Team Overview (mini-list of agents by status)
+[16px gap]
+[Recent Activity (full width, last 10 events)]
+```
+
+**Tablet (md):**
+```
+Stat cards: 2×2 grid
+Main layout: Single column (Sessions, then Team, then Activity)
+```
+
+**Mobile (< 640px):**
+```
+Stat cards: 2×2 grid (compact)
+All sections: stacked single column
+```
+
+#### Stat Card Spec
+
+4 cards:
+1. **Active Now** — count of currently running sessions (emerald if >0, zinc if 0)
+2. **Pending Approvals** — count awaiting action (amber if >0, zinc if 0)
+3. **Team Size** — count of configured agents
+4. **Sessions Today** — total sessions started today
+
+StatCard anatomy:
+```
+[Icon (24px)]  [Label (12px, text-tertiary, uppercase, tracking-wide)]
+[Value (32px, semibold, text-primary)]
+[Trend/subtitle (12px, text-secondary)]  ← optional
+```
+
+Surface-1 card, 16px padding, subtle border-default.
+
+#### Empty State Spec
+
+**First Login State (Activation Mode):**
+
+Replace stat cards with a single "Activation Panel":
+```
+┌──────────────────────────────────────────────────────┐
+│  Command Center — Standby                            │
+│                                                      │
+│  Your team hasn't been assembled yet.                │
+│  Add your first A.L.I.C.E. specialist to start.     │
+│                                                      │
+│  Step 1 ○ Add a specialist      [Go to My Team →]   │
+│  Step 2 ○ Start your first session                   │
+│  Step 3 ○ Configure a workflow                       │
+└──────────────────────────────────────────────────────┘
+```
+Background: surface-1, left border accent-subtle (2px emerald).
+
+**Active Sessions — empty (has agents, no running sessions):**
+```
+Icon: `Zap` (24px, text-tertiary)
+Text: "No active sessions"
+Sub: "Your team is standing by."
+CTA: none (this is fine — not every state needs a CTA)
+```
+
+**Team Overview — empty:**
+```
+Text: "No team members"
+CTA: [Add first specialist →] → routes to My Team
+```
+
+**Recent Activity — empty:**
+```
+Icon: `Clock` (24px, text-tertiary)  
+Text: "No recent activity"
+Sub: "Actions and events will appear here."
+```
+
+#### Component Inventory
+
+- AH: `StatCard`, `SessionCard` (mini variant), `AgentAvatar`, `StatusDot`
+- Shadcn: `Skeleton`, `Badge` (for activity labels)
+- Custom: `WelcomeBanner`, `ActivationPanel` (first login only)
+
+#### Interaction Spec
+
+| Interaction | Behavior |
+|---|---|
+| Stat card — Active Now click | Routes to Sessions, filtered to active |
+| Stat card — Pending Approvals click | Routes to Approvals |
+| Session card click | Opens session detail (sheet or navigate) |
+| Agent in Team Overview click | Routes to My Team, scrolls to agent |
+| Refresh | Pull-to-refresh on mobile; automatic 30s polling on desktop |
+
+#### Done Criteria
+
+- [ ] Stat cards show live data, emerald when nonzero for Active/Approvals
+- [ ] Active sessions show live duration tickers
+- [ ] Responsive: 4-col stat cards on desktop, 2×2 on mobile
+- [ ] First login: Activation Panel replaces stat cards
+- [ ] Welcome Banner appears once for new users, dismissible
+- [ ] Empty states use exact copy/icon spec above
+
+---
+
+### 10.3 MY TEAM
+
+#### Layout Spec
+
+**Desktop (lg+):**
+```
+PageHeader: "My Team" [subtitle: "N specialists"] [CTA: "Add Specialist" button]
+[Agent cards: CSS grid, 3 columns, gap-4]
+```
+
+**Tablet (md):**
+```
+Agent cards: 2 columns
+```
+
+**Mobile (< 640px):**
+```
+Agent cards: 1 column (full width stacked)
+CTA button: Full width below page header
+```
+
+#### Agent Card Spec
+
+```
+┌────────────────────────────────────────┐
+│ [Avatar: initials + agent color ring]  │
+│ [Name — 16px semibold]                 │
+│ [Role/specialty — 14px text-secondary] │
+│ [StatusDot + status label]             │
+│ ─────────────────────────────────────  │
+│ [Sessions today: N]  [Last active: Xm] │
+│                         [Configure →]  │
+└────────────────────────────────────────┘
+```
+
+- Card: surface-1, 20px padding, border-default, 8px border-radius
+- Avatar: 48×48px circle, initials (2-letter), colored background from `--agent-N` tokens
+- Status dot: 8px, pulsing ring if active
+- Hover: card lifts (border-strong, shadow-lg transition 100ms)
+
+#### Empty State Spec
+
+**First Login State:**
+```
+[Centered in content area]
+Icon: `Users` (48px, text-tertiary)
+Heading: "Assemble your team"
+Body: "Add your first A.L.I.C.E. specialist. Each one handles a domain — coding, research, writing, analysis. Your team works while you work (and while you sleep)."
+CTA: [Add your first specialist] — primary button
+```
+
+This is NOT a generic "no data" message. It tells the user what the product does and makes adding an agent feel like a meaningful action.
+
+**Search/filter returns no results:**
+```
+Icon: `SearchX` (32px, text-tertiary)
+Text: "No specialists match '[query]'"
+CTA: [Clear filter] — ghost button
+```
+
+#### Component Inventory
+
+- AH: `AgentCard`, `AgentAvatar`, `StatusDot`, `StatusBadge`, `PageHeader`
+- Shadcn: `Dialog` (add/edit agent), `Input` (search), `Select` (filter by status), `Skeleton`, `Button`
+
+#### Interaction Spec
+
+| Interaction | Behavior |
+|---|---|
+| Agent card click | Opens agent detail Sheet (right panel) |
+| "Configure" button | Same as card click — opens agent Sheet |
+| Agent status dot click | No action — it's informational only |
+| "Add Specialist" | Opens Dialog — multi-step: Name → Role → Config |
+| Add agent — step transitions | Slide left/right within dialog, no full dialog remount |
+| Delete agent | Confirmation dialog: "Remove [Name] from your team?" — destructive button |
+| Agent active | Pulsing emerald ring on avatar, status dot pulses |
+
+**Agent Add/Edit Dialog:**
+- Step 1: Name + emoji/avatar choice
+- Step 2: Role/specialty select (from preset list + custom)
+- Step 3: Model + config (API key, temperature, etc.)
+- Footer: [Back] [Next / Save]
+
+#### Done Criteria
+
+- [ ] Agent cards show correct status with pulsing dots for active agents
+- [ ] Agent color assignments are consistent (same agent always same color)
+- [ ] Empty state uses exact copy above — no generic "no agents found"
+- [ ] Add/edit dialog works as multi-step flow, not separate pages
+- [ ] Mobile: cards are full-width, scannable without horizontal scroll
+
+---
+
+### 10.4 SESSIONS
+
+#### Layout Spec
+
+**Desktop (lg+):**
+```
+PageHeader: "Sessions" [Filter bar] [New Session button]
+[Filter row: Status tabs (All / Active / Completed / Failed) + Search input + Date range]
+[Sessions list: full-width cards, stacked]
+```
+
+**Tablet (md):**
+```
+Same as desktop, filter row wraps to 2 rows
+```
+
+**Mobile (< 640px):**
+```
+PageHeader: "Sessions" [New Session button — icon only on mobile]
+Filter: Status tabs scroll horizontally (no wrap)
+Search: Below tabs, full width
+Sessions: Stacked cards, full width
+NO table view — always cards on mobile
+```
+
+**The sessions table on desktop is abolished.** Sessions are always cards. The table view caused mobile overflow issues and was harder to scan than cards.
+
+#### Session Card Spec (standard)
+
+```
+┌────────────────────────────────────────────────────────┐
+│ [StatusDot] [Session name/title — 14px semibold]   [▶] │
+│ [Agent name + avatar (16px)]   [Duration: 00:04:23]    │
+│ [Last message preview — 13px text-secondary, 1 line]   │
+│ [Tags/labels]                         [Started: 2h ago] │
+└────────────────────────────────────────────────────────┘
+```
+
+**Active session variant:**
+- Left border: 3px emerald (`--accent`)
+- Duration ticker: live, counts up in real-time
+- StatusDot: pulsing emerald
+
+**Failed session variant:**
+- Left border: 3px red-500
+- StatusDot: static red
+- Duration replaced with: "Failed · 4 min ago"
+
+**Pending session variant:**
+- Left border: 3px blue-400
+- StatusDot: static blue
+- Shows "Waiting for approval" instead of duration
+
+#### Empty State Spec
+
+**First Login (no sessions ever):**
+```
+Icon: `MessageSquare` (48px, text-tertiary) — the chat/conversation metaphor
+Heading: "No sessions yet"
+Body: "Sessions are conversations between you and your team. Start one to see your specialists in action."
+CTA: [Start a session] → Opens New Session dialog
+```
+
+**Filtered to Active — no active sessions:**
+```
+Icon: `Coffee` (32px, text-tertiary)  ← intentional: your team is at rest
+Text: "Your team is standing by"
+Sub: "No active sessions right now."
+CTA: [Start a session] — ghost button
+```
+
+**Filtered to Failed — no failures:**
+```
+Icon: `CheckCircle` (32px, --status-active)
+Text: "No failures"
+Sub: "All good."
+[No CTA]
+```
+
+**Search returns nothing:**
+```
+Icon: `SearchX` (32px, text-tertiary)
+Text: "No sessions match '[query]'"
+CTA: [Clear search]
+```
+
+#### Component Inventory
+
+- AH: `SessionCard`, `StatusDot`, `StatusBadge`, `AgentAvatar`, `PageHeader`
+- Shadcn: `Tabs` (status filter), `Input` (search), `Dialog` (new session), `Sheet` (session detail), `Skeleton`, `Button`, `Badge` (labels)
+
+#### Interaction Spec
+
+| Interaction | Behavior |
+|---|---|
+| Session card click | Opens session detail Sheet (slides in from right) |
+| Session detail Sheet | Shows full message history + metadata + actions |
+| Active session — live ticker | Updates every second, no flicker |
+| "New Session" button | Opens dialog: Select agent → Enter prompt → Start |
+| Status tab switch | Instant filter, no loading state if data cached |
+| Search | Debounce 300ms, searches name + agent + content preview |
+| Session — Stop button | Confirmation: "Stop this session?" — not destructive dialog, inline |
+| Session — Retry (failed) | Immediate action, shows button spinner, refreshes card |
+| Pull to refresh (mobile) | Refreshes list |
+
+#### Done Criteria
+
+- [ ] NO horizontal scroll on mobile — ever
+- [ ] Active sessions show live duration tickers
+- [ ] Status tabs filter instantly
+- [ ] Session cards have correct left-border color by status
+- [ ] Empty states use exact copy above
+- [ ] Session detail Sheet works on all breakpoints
+- [ ] First login empty state communicates what sessions ARE
+
+---
+
+### 10.5 APPROVALS
+
+#### Layout Spec
+
+**Desktop (lg+):**
+```
+PageHeader: "Approvals" [Badge: N pending]
+[Master-detail layout: 360px left panel + flexible right panel]
+Left: Scrollable list of approval cards
+Right: Selected approval detail (empty state if nothing selected)
+```
+
+**Tablet (md):**
+```
+Full-width list only — no detail panel
+Tapping an approval opens a Sheet (bottom sheet or right sheet)
+```
+
+**Mobile (< 640px): [CRITICAL — this was broken, now fixed]**
+```
+Full-width stacked cards
+NO side-by-side layout
+Tap to open detail Sheet (slides up from bottom)
+Approve / Reject buttons: full-width, stacked at bottom of Sheet
+```
+
+#### Approval Card Spec
+
+```
+┌────────────────────────────────────────────────────────┐
+│ [AgentAvatar 32px] [Agent name — 13px semibold]        │
+│ [Request title — 14px, text-primary, 2-line clamp]     │
+│ [Type badge: tool_call / file_write / etc.]             │
+│ [Waiting: 4m 32s ago] [→ Approve] [✕ Reject]          │
+└────────────────────────────────────────────────────────┘
+```
+
+**Selected state (desktop):** Highlighted with border-strong, background surface-2.
+
+#### Approval Detail Panel Spec (desktop right panel)
+
+```
+[Agent + request type header]
+[Full request context — code block or prose, scrollable]
+[Impact summary: what happens if approved / rejected]
+[Approve button — full width, primary (emerald)]
+[Reject button — full width, destructive (outline)]
+[Add note — optional textarea, shows on demand]
+```
+
+**Nothing selected state (desktop right panel):**
+```
+[Centered vertically]
+Icon: `MousePointerClick` (32px, text-tertiary)
+Text: "Select an approval to review"
+```
+
+#### Empty State Spec
+
+**No pending approvals:**
+```
+Icon: `CheckCircle2` (48px, --status-active)  ← emerald — this is a good thing
+Heading: "All caught up"
+Body: "No approvals waiting. Your team is running without blockers."
+[No CTA]
+```
+
+Note: This is the one empty state where we use emerald — because zero pending approvals IS a success state.
+
+**First Login (will look like the above since no agents = no approvals):**
+Same "All caught up" state — no special case needed here.
+
+#### Component Inventory
+
+- AH: `ApprovalCard`, `AgentAvatar`, `StatusBadge`, `PageHeader`
+- Shadcn: `Sheet` (mobile/tablet detail), `Textarea` (note input), `Button`, `Skeleton`, `Badge` (type labels), `ScrollArea` (for detail content)
+
+#### Interaction Spec
+
+| Interaction | Behavior |
+|---|---|
+| Card click (desktop) | Loads detail in right panel (150ms fade) |
+| Card click (mobile/tablet) | Opens bottom Sheet |
+| Approve (card inline) | Immediate optimistic update, card fades out (200ms), success toast |
+| Reject (card inline) | Immediate optimistic update, card fades out (200ms) |
+| Approve (detail panel) | Same optimistic update |
+| Add note | Textarea expands inline, "Submit with note" replaces "Approve" |
+| Empty right panel | Shows "Select an approval" message — see spec above |
+| Waiting timer | Live counter per card — updates every second |
+
+**Optimistic updates:** When a user approves/rejects, the card immediately leaves the list. If the action fails, the card comes back with an error toast: "Couldn't [approve/reject] — please try again"
+
+#### Done Criteria
+
+- [ ] Mobile: full-width stacked cards, NO overflow, Sheet for detail
+- [ ] Desktop: master-detail layout, right panel shows selection
+- [ ] Waiting timers are live
+- [ ] Optimistic updates on approve/reject
+- [ ] Empty state uses emerald (it IS a success state)
+- [ ] "All caught up" copy — not "No approvals found"
+
+---
+
+### 10.6 WORKFLOWS
+
+#### Layout Spec
+
+**Desktop (lg+):**
+```
+PageHeader: "Workflows" [CTA: "New Workflow" button]
+[Status filter tabs: All / Active / Draft / Archived]
+[Workflow table/list: full width]
+```
+
+**Mobile (< 640px):**
+```
+PageHeader: "Workflows" [New Workflow — icon button]
+Filter: Horizontal scrolling tabs
+Workflows: Stacked cards (not table rows)
+```
+
+#### Workflow Card/Row Spec
+
+**Desktop (table-like rows):**
+```
+[StatusDot] [Workflow name — 14px semibold] [Description — text-secondary, truncated]
+[Agent(s) — avatar stack] [Trigger: cron/event label] [Last run: Xh ago] [Run count]
+[Actions: Run now / Edit / Archive — overflow menu]
+```
+
+**Mobile (cards):**
+```
+[Workflow name + StatusDot]
+[Description — 2 lines]
+[Next run: Xh from now OR Last run: Xh ago]
+[Actions: kebab menu]
+```
+
+#### Empty State Spec
+
+**First Login / No Workflows:**
+```
+Icon: `GitBranch` (48px, text-tertiary)
+Heading: "No workflows yet"
+Body: "Workflows are automated sequences your team runs on a schedule or trigger. Set one up to let your team work independently."
+CTA: [Create your first workflow] — primary button
+```
+
+**Filter: Active — no active workflows:**
+```
+Icon: `Zap` (32px, text-tertiary)
+Text: "No active workflows"
+Sub: "Activate a workflow or create a new one."
+CTA: [New Workflow] — ghost button
+```
+
+**Filter: Archived:**
+```
+Icon: `Archive` (32px, text-tertiary)
+Text: "Nothing archived"
+```
+
+#### Component Inventory
+
+- AH: `StatusDot`, `AgentAvatar`, `PageHeader`, `StatusBadge`
+- Shadcn: `Table` (desktop rows), `Tabs` (filter), `DropdownMenu` (row actions), `Dialog` (workflow builder), `Sheet` (workflow detail/edit), `Skeleton`, `Button`
+
+#### Interaction Spec
+
+| Interaction | Behavior |
+|---|---|
+| Row click | Opens workflow detail Sheet |
+| "Run now" | Triggers run, button shows spinner, success toast when started |
+| "Edit" | Opens workflow edit Dialog/Sheet |
+| "Archive" | Confirmation inline: "Archive this workflow?" with undo toast |
+| Status toggle | Switch on row — optimistic, instant |
+| New workflow | Opens multi-step Dialog (trigger → agent → actions → review) |
+| Sort columns | Instant client-side sort if data loaded |
+
+#### Done Criteria
+
+- [ ] Mobile: workflows render as cards (no table overflow)
+- [ ] Run now action gives immediate feedback
+- [ ] Empty states use exact copy — specifically the "let your team work independently" framing
+- [ ] Workflow builder dialog is multi-step
+
+---
+
+### 10.7 SETTINGS
+
+#### Layout Spec
+
+**All breakpoints:**
+```
+PageHeader: "Settings"
+[Vertical tab navigation on left (desktop) / Horizontal tabs (mobile)]
+[Content panel on right (desktop) / Full width below tabs (mobile)]
+```
+
+**Desktop:** Left nav 200px, content fills remainder  
+**Mobile:** Tabs scroll horizontally at top, content below full-width
+
+**Settings Tabs:**
+1. General
+2. Account
+3. Team (agent defaults)
+4. Integrations
+5. Knowledge (previously standalone page — now settings sub-section)
+6. Notifications
+7. Billing
+
+#### Component Inventory (SHADCN THROUGHOUT — no AH mixing)
+
+- All `Input`, `Textarea`, `Select`, `Switch`, `Checkbox`, `RadioGroup` — Shadcn
+- All `Tabs` — Shadcn
+- `Button` — Shadcn
+- Section headers — custom styled (not AH PageHeader)
+- Knowledge base items — custom (not Knowledge page component)
+- Agent display in Team tab — AH `AgentAvatar` only (not full AgentCard)
+
+**The previous Settings problem was mixing AH page-level components in a sub-section context.** Settings uses shadcn primitives throughout. The only AH component allowed is `AgentAvatar` as a display element.
+
+#### Empty State Spec
+
+**Integrations — no connected integrations:**
+```
+Icon: `Plug` (32px, text-tertiary)
+Text: "No integrations connected"
+Sub: "Connect your tools to extend what your team can do."
+[Integration cards shown regardless — connection is the CTA]
+```
+
+**Knowledge — no documents:**
+```
+Icon: `BookOpen` (32px, text-tertiary)
+Text: "No knowledge sources"
+Sub: "Add documents or URLs to give your team context."
+CTA: [Add knowledge source] — primary button
+```
+
+**Notifications — no notification rules:**
+```
+Text: "Using default notification settings."
+[Settings form shown — not a blocking empty state]
+```
+
+#### Interaction Spec
+
+| Interaction | Behavior |
+|---|---|
+| Setting change | Auto-save with debounce 800ms, subtle "Saved" indicator (text fades in/out near the field) |
+| Explicit save forms | "Save changes" button, shows spinner on click |
+| Destructive actions | Confirmation dialog (e.g., delete account, clear knowledge base) |
+| Tab switch | Instant (no loading) |
+| Knowledge upload | Drop zone + file picker, progress bar during upload |
+| Integration connect | Opens OAuth flow or token input Sheet |
+
+**Auto-save indicator:**
+- Appears as "Saved ✓" in text-secondary/text-tertiary near the relevant section
+- Fades in at 200ms, waits 2s, fades out at 200ms
+- Does NOT use toast for individual setting saves
+
+#### Done Criteria
+
+- [ ] All form components are shadcn — no AH components except AgentAvatar
+- [ ] No mixed component systems on any settings tab
+- [ ] Auto-save works for toggle/select fields
+- [ ] Knowledge tab works equivalently to the previous standalone page
+- [ ] Mobile: horizontal scroll tabs, full-width content
+- [ ] Tabs are keyboard navigable
+
+---
+
+## 11. COPY & LANGUAGE STANDARDS
+
+### The Mental Model in Copy
+
+| Context | Use | Never use |
+|---------|-----|-----------|
+| Agent collection | "Your team" | "Your agents", "Your bots" |
+| Individual agent | "[Name], your [Role] specialist" | "Agent ID: xyz" |
+| Active session | "[Name] is in a session" | "Process running" |
+| Pending approval | "[Name] is waiting for you" | "Approval #4892 pending" |
+| Session history | "N sessions this week" | "N tasks completed" |
+| Idle agent | "[Name] is standing by" | "Agent idle" |
+
+### Empty State Copy Principles
+
+1. **Describe potential, not absence.** "No sessions yet" → "Sessions are conversations with your team. Start one."
+2. **First-person team language.** "Your team is standing by" not "No data found"
+3. **Emerald empty states are success states.** "All caught up" when approvals are empty.
+4. **Only use CTA in empty state if there's a clear next action.** Not every empty state needs a button.
+
+### Timestamps
+
+- < 1 minute: "Just now"
+- 1–59 minutes: "Xm ago"
+- 1–23 hours: "Xh ago"
+- Yesterday: "Yesterday at HH:MM"
+- Older: "Mar 14" or "Mar 14, 2025" if different year
+
+### Status Labels
+
+| Status | Display label |
+|--------|--------------|
+| active | "Active" |
+| running | "In session" |
+| idle | "Standing by" |
+| pending | "Waiting" |
+| failed | "Failed" |
+| offline | "Offline" |
+| disabled | "Disabled" |
+
+---
+
+## APPENDIX: DONE CRITERIA SUMMARY
+
+A page is "done" when:
+
+1. ✅ All breakpoints render without overflow or layout break
+2. ✅ All empty states show exact spec copy and icon (not placeholder text)
+3. ✅ Component system matches spec (no mixing violations)
+4. ✅ Loading states use correct skeleton variant
+5. ✅ Error states follow the 4-level hierarchy
+6. ✅ Active/live elements animate per the motion spec
+7. ✅ Reduced motion respected
+8. ✅ Token usage matches the canonical token system (no raw hex)
+9. ✅ First login experience shows Activation Mode content where specified
+10. ✅ Tab/keyboard navigation works on all interactive elements
+
+---
+
+*Spec locked. Implementation questions → Nadia. No design decisions in PRs.*