{"slug":"strategy/product-strategy/ui-spec","title":"IntegrateWise Continuity Bridge — Product UI Specification","section":"strategy","sectionLabel":"Strategy","status":"unclassified","type":"long-form","path":"strategy/product-strategy/ui-spec.mdx","bytes":217039,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Status: SUPERSEDED UI SNAPSHOT.** The old product name, multi-surface model,\n> OpenWebUI-like AI Home and permanent Twin destinations are historical. Current\n> UI authority is\n> [`../architecture/ARCHITECTURE_LOCK.md`](../architecture/ARCHITECTURE_LOCK.md),\n> [`../architecture/TWIN_BEHAVIOR.md`](../architecture/TWIN_BEHAVIOR.md) and\n> [`../architecture/FRONTEND_PLATFORM_API_AND_DISCOVERY_SPEC.md`](../architecture/FRONTEND_PLATFORM_API_AND_DISCOVERY_SPEC.md).\n>\n> **Version:** 1.0.0 | **Date:** 2026-07-03 | **Original Status:** Final Product Specification\n> **For:** IntegrateWise Engineering & Product Design Teams \n> **Scope:** Concrete UI specification for the 8 user-facing product components of the Continuity Bridge.\n\n---\n\n## Table of Contents\n\n1. [User Workbench](#1-user-workbench)\n2. [Overlay (Communication Layer)](#2-overlay-communication-layer)\n3. [AI Home (OpenWeb UI-like)](#3-ai-home)\n4. [Capability Fabric](#4-capability-fabric)\n5. [Ingress (UI Entry Points)](#5-ingress)\n6. [Audit Logs (Transparency Layer)](#6-audit-logs)\n7. [Browser Automation](#7-browser-automation)\n8. [Workflows](#8-workflows)\n\n---\n\n## Design System Foundations\n\n### Color Palette (Tailwind)\n\n```css\n:root {\n /* Primary: Deep Trust Blue */\n --iw-primary-50: #eff6ff;\n --iw-primary-100: #dbeafe;\n --iw-primary-200: #bfdbfe;\n --iw-primary-300: #93c5fd;\n --iw-primary-400: #60a5fa;\n --iw-primary-500: #3b82f6;\n --iw-primary-600: #2563eb;\n --iw-primary-700: #1d4ed8;\n --iw-primary-800: #1e40af;\n --iw-primary-900: #1e3a8a;\n\n /* Neutral: Slate — NOT gray for warmth */\n --iw-neutral-50: #f8fafc;\n --iw-neutral-100: #f1f5f9;\n --iw-neutral-200: #e2e8f0;\n --iw-neutral-300: #cbd5e1;\n --iw-neutral-400: #94a3b8;\n --iw-neutral-500: #64748b;\n --iw-neutral-600: #475569;\n --iw-neutral-700: #334155;\n --iw-neutral-800: #1e293b;\n --iw-neutral-900: #0f172a;\n\n /* Semantic */\n --iw-success: #22c55e;\n --iw-warning: #f59e0b;\n --iw-danger: #ef4444;\n --iw-info: #3b82f6;\n\n /* Confidence heat */\n --iw-confidence-high: #22c55e; /* ≥0.85 */\n --iw-confidence-medium: #f59e0b; /* 0.70–0.85 */\n --iw-confidence-low: #ef4444; /* <0.70 */\n\n /* Surface */\n --iw-surface: #ffffff;\n --iw-elevated: #f8fafc;\n --iw-canvas: #f1f5f9;\n --iw-overlay: rgba(15, 23, 42, 0.4);\n}\n```\n\n### Typography\n\n```css\n--iw-font-sans: \"Inter\", -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif;\n--iw-font-mono: \"JetBrains Mono\", \"Fira Code\", monospace;\n--iw-font-display: \"Inter\", sans-serif; /* Use variable weight for headings */\n\n/* Scale */\n--text-xs: 0.75rem; /* 12px — captions, tags */\n--text-sm: 0.875rem; /* 14px — body secondary, metadata */\n--text-base: 1rem; /* 16px — primary body */\n--text-lg: 1.125rem; /* 18px — section titles */\n--text-xl: 1.25rem; /* 20px — card titles */\n--text-2xl: 1.5rem; /* 24px — page titles */\n--text-3xl: 1.875rem; /* 30px — hero headings */\n```\n\n### Spacing Scale (Tailwind)\n\n```\n4px (1) — micro gaps, icon padding\n8px (2) — tight internal padding\n12px (3) — button padding, list gaps\n16px (4) — card padding, section gaps\n20px (5) — form field gaps\n24px (6) — panel internal padding\n32px (8) — major section separation\n40px (10) — page-level padding\n48px (12) — hero spacing\n64px (16) — major page sections\n```\n\n### Shadow & Elevation\n\n```css\n--shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.04);\n--shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.06), 0 2px 4px -1px rgba(0, 0, 0, 0.04);\n--shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.08), 0 4px 6px -2px rgba(0, 0, 0, 0.04);\n--shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.08), 0 10px 10px -5px rgba(0, 0, 0, 0.04);\n--shadow-twin: 0 0 0 1px rgba(59, 130, 246, 0.15), 0 4px 12px rgba(59, 130, 246, 0.12);\n```\n\n### Animation Tokens\n\n```css\n--ease-out: cubic-bezier(0.16, 1, 0.3, 1);\n--ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);\n--duration-fast: 150ms; /* micro-interactions */\n--duration-normal: 250ms; /* state transitions */\n--duration-slow: 400ms; /* panel movements */\n--duration-dramatic: 600ms; /* page transitions */\n```\n\n---\n\n## 1. User Workbench\n\n### 1.1 Overview\n\nThe User Workbench is the primary working surface of IntegrateWise. It is not a data viewer — it is where users perform actual work on unified data without switching contexts. It reads from the Adaptive Spine, queries the Capability Fabric for available actions, and is enriched by the Twin's inline insights.\n\n**User Journey Position:** Step 3 (WORK) of the 6-step flow: CONNECT → HYDRATE → **WORK** → AI → MEMORY → REPEAT.\n\n**Core Principles:**\n\n- One workbench. All tools. One truth. No tab switching.\n- Every action is governed and audited.\n- 8 projections adapt the interface to the user's role without changing the underlying data.\n- The Twin is ambient — present but not intrusive.\n\n---\n\n### 1.2 Layout / Wireframe Description\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ TOP BAR (64px) │\n│ ┌────┐ ┌────────────────────────────────────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ │\n│ │ IW │ │ 🔍 Search anything... ⌘K │ │ 🔔 │ │ ✨ │ │ 👤 │ │ ⚙️ │ │\n│ └────┘ └────────────────────────────────────┘ └────┘ └────┘ └────┘ └────┘ │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌──────────┐ ┌────────────────────────────────────┐ ┌────────────────┐ │\n│ │ ENTITY │ │ │ │ │ │\n│ │ EXPLORER │ │ DETAIL PANE │ │ ACTION PANEL │ │\n│ │ (240px) │ │ (Fluid, min 480px) │ │ (320px) │ │\n│ │ │ │ │ │ │ │\n│ │ ┌──────┐ │ │ ┌────────────────────────────┐ │ │ ┌────────────┐ │ │\n│ │ │Sales │◄─┼──┼──┤ ENTITY HEADER │ │ │ │ Quick │ │ │\n│ │ │CS │ │ │ │ [Icon] Acme Corporation │ │ │ │ Actions │ │ │\n│ │ │Fin │ │ │ │ ┌────────┬────────┐ │ │ │ │ • Email │ │ │\n│ │ │Exec │ │ │ │ │Tab:360 │Tab:Rel │ ... │ │ │ │ • Call │ │ │\n│ │ │Arch │ │ │ │ └────────┴────────┘ │ │ │ │ • Task │ │ │\n│ │ │Ops │ │ │ │ │ │ │ └────────────┘ │ │\n│ │ │Pers │ │ │ │ ┌────────────────────┐ │ │ │ ┌────────────┐ │ │\n│ │ │Dev │ │ │ │ │ ENTITY360 CONTENT │ │ │ │ │ Related │ │ │\n│ │ └──────┘ │ │ │ │ │ │ │ │ │ Entities │ │ │\n│ │ │ │ │ │ [traits] │ │ │ │ │ • Contact │ │ │\n│ │ Recently │ │ │ │ [timeline] │ │ │ │ │ • Deal │ │ │\n│ │ Viewed │ │ │ │ [memory] │ │ │ │ └────────────┘ │ │\n│ │ • Acme │ │ │ │ │ │ │ │ │ │\n│ │ • Widget │ │ │ └────────────────────┘ │ │ │ ┌────────────┐ │ │\n│ │ │ │ │ │ │ │ │ Governance │ │ │\n│ │ │ │ └────────────────────────────┘ │ │ │ Status │ │ │\n│ │ │ │ │ │ └────────────┘ │ │\n│ └──────────┘ └────────────────────────────────────┘ └────────────────┘ │\n│ │\n│ ┌──────────────────────────────────────────────────────────────────────┐ │\n│ │ TWIN ENRICHMENT BAR (48px, collapsible) │ │\n│ │ 💡 \"3 accounts show churn risk this week. Review →\" │ │\n│ └──────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌──────────────────────────────────────────────────────────────────────┐ │\n│ │ MEMORY PANEL (collapsible drawer, 200px when open) │ │\n│ │ What the system knows about this entity: │ │\n│ │ • Last interaction: 2 days ago (sent proposal) │ │\n│ │ • Sentiment: Positive (0.72) │ │\n│ │ • Key topics: renewal, pricing, expansion │ │\n│ └──────────────────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n### 1.3 Key UI Components\n\n#### 1.3.1 Top Navigation Bar\n\n```typescript\ninterface TopBarProps {\n tenant: { name: string; logo?: string };\n user: { displayName: string; avatar?: string; role: Role };\n projection: ProjectionType; // 'sales' | 'cs' | 'finance' | 'executive' | 'architecture' | 'operations' | 'personal' | 'developer'\n notificationCount: number;\n onSearchFocus: () => void;\n onCommandPalette: () => void;\n}\n```\n\n**Visual Spec:**\n\n- Height: `64px` (`h-16`)\n- Background: `--iw-surface` with `border-b border-neutral-200`\n- Left: IntegrateWise logo (`32px` square) + tenant name (truncated to `max-w-[160px]`)\n- Center: Universal search bar — `max-w-2xl`, `rounded-full`, `bg-neutral-100`, placeholder: \"Search anything...\"\n - Right inner: `⌘K` badge (`text-xs`, `bg-neutral-200`, `rounded`, `px-1.5`)\n - Focus state: `ring-2 ring-primary-200`, background transitions to white\n- Right cluster (gap-2):\n - Notification bell: `relative`, badge for unread count (`absolute -top-1 -right-1 bg-danger text-white text-[10px] w-4 h-4 rounded-full flex items-center justify-center`)\n - Twin sparkle icon: `text-primary-500`, pulses subtly when Twin is active\n - User avatar: `32px` circle, `dropdown` on click\n - Settings gear: `dropdown` with projection switcher, preferences, logout\n\n#### 1.3.2 Projection Switcher (Lens Selector)\n\n```typescript\ninterface ProjectionSwitcherProps {\n current: ProjectionType;\n available: ProjectionType[]; // filtered by RBAC\n onSwitch: (projection: ProjectionType) => void;\n}\n```\n\n**Visual Spec:**\n\n- Collapsible sidebar section, pinned to top of Entity Explorer\n- 8 icons in a vertical stack, `40px` each, `rounded-lg`\n- Active projection: `bg-primary-50 text-primary-700`, left border `3px` `bg-primary-500`\n- Inactive: `text-neutral-400`, hover: `bg-neutral-50 text-neutral-600`\n- Tooltip on hover: projection name + keyboard shortcut (`1`–`8`)\n- Switching animation: `fade` + `slide` on Detail Pane content, `200ms`\n\n#### 1.3.3 Entity Explorer (Left Sidebar)\n\n```typescript\ninterface EntityExplorerProps {\n projection: ProjectionType;\n entityTypes: EntityTypeInfo[]; // filtered by projection\n selectedEntityId?: string;\n recentEntities: RecentEntity[];\n onSelect: (entityId: string) => void;\n onCreate: (entityType: string) => void;\n}\n\ninterface EntityTypeInfo {\n type: string; // 'account', 'contact', 'deal', ...\n displayName: string;\n icon: string; // Lucide icon name\n count: number; // visible count in current projection\n isFavorite: boolean;\n}\n```\n\n**Visual Spec:**\n\n- Width: `240px` (`w-60`), collapsible to `64px` (`w-16`) — icons only\n- Background: `--iw-elevated` (`bg-slate-50`)\n- Section 1: Projection Switcher (see above)\n- Section 2: Entity Types (collapsible groups)\n - Each entity type: `icon` + `name` + `count` pill (`bg-neutral-200 text-neutral-600 text-xs rounded-full px-2`)\n - Selected: `bg-primary-50 text-primary-700`, right chevron\n - Hover: `bg-neutral-100`\n- Section 3: Recently Viewed (last 10, scrollable)\n - Each item: `avatar` (if contact) or `building` icon + `name` + `type` badge\n - Hover: show `pin` icon to favorite\n- Section 4: Quick Actions (sticky bottom)\n - \"+ Create\" button: `primary` style, opens flyout menu of entity types\n\n#### 1.3.4 Detail Pane (Center)\n\n```typescript\ninterface DetailPaneProps {\n entity: Entity360 | null;\n activeTab: DetailTab;\n onTabChange: (tab: DetailTab) => void;\n onAction: (capability: string, payload: unknown) => void;\n}\n\ntype DetailTab = \"entity360\" | \"relationships\" | \"timeline\" | \"memory\" | \"audit\" | \"knowledge\";\n```\n\n**Visual Spec:**\n\n- Fluid width: `flex-1`, min `480px`\n- Background: `--iw-surface` (`bg-white`)\n- Entity Header (`80px`):\n - Left: Entity type icon (`40px`, `rounded-lg`, `bg-primary-100 text-primary-600`) + entity name (`text-xl font-semibold`) + SSOC ID (muted, `text-xs`, `font-mono`)\n - Right: Action dropdown (favorite, share, archive) + status badge (if applicable)\n- Tab Bar (`44px`, `border-b`):\n - Tabs: `Entity360`, `Relationships`, `Timeline`, `Memory`, `Audit`, `Knowledge`\n - Active: `border-b-2 border-primary-500 text-primary-700`\n - Inactive: `text-neutral-500 hover:text-neutral-700`\n- Content area: scrollable, `p-6`\n\n**Entity360 Tab Content:**\n\n- Traits grid: `grid-cols-2` or `grid-cols-3` depending on viewport\n - Each trait: `label` (`text-xs uppercase tracking-wide text-neutral-500`) + `value` (`text-sm`)\n - Editable traits: click to edit, `inline` `input` or `select`, `blur` or `Enter` to save\n- Relationship mini-map: `200px` height, D3.js force-directed graph of linked entities\n- Timeline: vertical scrollable, `400px` max, reverse chronological\n - Each event: `dot` + `timestamp` + `action` + `actor` + `via` badge\n- Memory snippets: cards showing what the system knows (`text-sm`, `bg-amber-50 border border-amber-200 rounded-lg`)\n\n#### 1.3.5 Action Panel (Right Sidebar)\n\n```typescript\ninterface ActionPanelProps {\n entity: Entity360 | null;\n availableCapabilities: CapabilityInfo[]; // filtered by entity type + user role\n governanceStatus: GovernanceStatus | null;\n onExecute: (capability: string, payload: unknown) => void;\n onPropose: (capability: string, payload: unknown) => void;\n}\n```\n\n**Visual Spec:**\n\n- Width: `320px` (`w-80`), collapsible to `0` (hidden)\n- Background: `--iw-elevated` (`bg-slate-50`), `border-l border-neutral-200`\n- Section 1: Quick Actions (primary CTA buttons)\n - Up to 5 most-used capabilities for this entity type\n - Each button: `full-width`, `justify-start`, `gap-3`, icon + label + shortcut (if any)\n - Primary action: `bg-primary-600 text-white hover:bg-primary-700`\n - Secondary: `bg-white border border-neutral-200 hover:bg-neutral-50`\n- Section 2: Related Entities (linked list)\n - Each: `flex row`, `gap-3`, `py-2`, `border-b border-neutral-100`\n - Avatar/icon + name + relationship type badge (`owns`, `reports_to`, etc.)\n - Click: navigate to that entity (detail pane updates, history pushed)\n- Section 3: Governance Status (if applicable)\n - Pending proposals: `bg-warning-50 border border-warning-200 rounded-lg p-3`\n - Confidence badge: `rounded-full` with color by threshold\n - \"Review in My Desk\" link\n\n#### 1.3.6 Twin Enrichment Bar\n\n```typescript\ninterface TwinEnrichmentBarProps {\n insights: TwinInsight[];\n onDismiss: (insightId: string) => void;\n onAction: (insightId: string, action: \"accept\" | \"reject\" | \"view\") => void;\n}\n\ninterface TwinInsight {\n id: string;\n type: \"proposal\" | \"context\" | \"suggestion\" | \"alert\" | \"pattern\";\n message: string;\n confidence: number;\n entityId?: string;\n action?: { capability: string; payload: unknown; label: string };\n}\n```\n\n**Visual Spec:**\n\n- Height: `48px` (single line), expandable to `auto` (multi-line)\n- Background: `bg-primary-50 border-t border-primary-100`\n- Left: Sparkle icon (`text-primary-500`) + insight text (`text-sm text-primary-800`)\n- Right (if actionable): CTA button(s) + dismiss (`×`)\n- Dismissed insights animate out: `slide-up + fade`, `200ms`\n- If empty: bar collapses to `0px` with `transition-height`\n\n#### 1.3.7 Memory Panel (Bottom Drawer)\n\n```typescript\ninterface MemoryPanelProps {\n entity: Entity360 | null;\n memories: MemoryRecord[];\n isOpen: boolean;\n onToggle: () => void;\n}\n```\n\n**Visual Spec:**\n\n- Collapsible drawer, `200px` open, `0` closed\n- Handle: `w-12 h-1 bg-neutral-300 rounded-full mx-auto mt-2`\n- Content: `p-4`\n- Each memory snippet: `rounded-lg bg-amber-50 border border-amber-200 p-3 mb-2`\n - Content: `text-sm text-amber-900`\n - Meta: `text-xs text-amber-600 mt-1` — source, confidence, last accessed\n\n#### 1.3.8 Universal Search Bar\n\n```typescript\ninterface UniversalSearchProps {\n isOpen: boolean;\n query: string;\n results: SearchResult[];\n onQueryChange: (q: string) => void;\n onSelect: (result: SearchResult) => void;\n onClose: () => void;\n}\n\ninterface SearchResult {\n type: \"entity\" | \"capability\" | \"memory\" | \"knowledge\" | \"command\";\n id: string;\n title: string;\n subtitle: string;\n icon: string;\n score: number;\n entityType?: string;\n}\n```\n\n**Visual Spec:**\n\n- Modal overlay: `bg-black/40 backdrop-blur-sm`, `z-50`\n- Search container: `max-w-2xl mx-auto mt-24 bg-white rounded-xl shadow-2xl overflow-hidden`\n- Input: `w-full px-4 py-3 text-lg border-b border-neutral-200`, auto-focus\n - Left: `Search` icon. Right: `⌘K` badge (when empty)\n- Results: grouped by type, `max-h-96 overflow-y-auto`\n - Each result: `flex row gap-3 px-4 py-3 hover:bg-neutral-50 cursor-pointer`\n - Selected: `bg-primary-50`\n - Keyboard: `↑`/`↓` to navigate, `Enter` to select, `Esc` to close\n\n#### 1.3.9 Command Palette\n\n```typescript\ninterface CommandPaletteProps {\n isOpen: boolean;\n commands: Command[];\n onExecute: (command: Command) => void;\n onClose: () => void;\n}\n\ninterface Command {\n id: string;\n label: string;\n shortcut?: string; // e.g., '⌘E'\n category: \"navigation\" | \"action\" | \"projection\" | \"twin\" | \"system\";\n icon: string;\n action: () => void;\n}\n```\n\n**Visual Spec:**\n\n- Same container as Universal Search, but commands are static/preset\n- Grouped by category with headers (`text-xs uppercase text-neutral-400 font-semibold px-4 py-2`)\n- Each command: `flex row gap-3 px-4 py-2.5 hover:bg-neutral-50`\n - Left: `icon` (`16px`, `text-neutral-500`)\n - Center: `label` (`text-sm`)\n - Right: `shortcut` (`text-xs bg-neutral-100 rounded px-1.5 font-mono`)\n\n---\n\n### 1.4 Data Flow\n\n```\n┌──────────────────────────────────────────────────────────────────────────────┐\n│ DATA FLOW: User Workbench │\n├──────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ INBOUND (Read) │\n│ ───────────── │\n│ 1. Gateway → Discovery (GET /api/v1/discovery) │\n│ → projections, capabilities, navigation, personalization │\n│ │\n│ 2. Entity Explorer → L2 Service Binding (KV cache + D1 fallback) │\n│ → entity list by type + projection filter │\n│ │\n│ 3. Detail Pane → Entity360 Assembly (intelligence service binding) │\n│ → entity + related entities + timeline + memory + knowledge │\n│ │\n│ 4. Action Panel → Capability Registry (KV cache) │\n│ → capabilities filtered by entity type + user role + plan tier │\n│ │\n│ 5. Twin Enrichment → Twin Orchestrator DO (SSE stream) │\n│ → real-time insights based on current entity context │\n│ │\n│ OUTBOUND (Write) │\n│ ──────────────── │\n│ 1. Entity CRUD → store service binding → Pipeline Queue → Spine │\n│ 2. Capability Execution → Gateway → Capability Router (Hermes DO) │\n│ 3. Governance Proposal → Gateway → govern service → HITL DO │\n│ 4. Memory Reinforcement → continuity service (implicit, on entity view) │\n│ │\n│ SERVICES CALLED │\n│ ─────────────── │\n│ • gateway (auth, routing) │\n│ • l2 (projection queries, KV cache) │\n│ • store (entity CRUD) │\n│ • intelligence (Entity360 assembly) │\n│ • agent-registry (capability discovery) │\n│ • twin-orchestrator (SSE enrichment stream) │\n│ • govern (pending proposals) │\n│ • continuity (memory query) │\n│ • knowledge (RAG for entity context) │\n│ │\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n### 1.5 User Interactions\n\n#### Flow: Sales Rep Reviews an Account and Acts\n\n| Step | Action | System Response | UI Change |\n| ---- | -------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n| 1 | User opens app, already authenticated | Discovery returns available projections | Sales projection is active (from preference) |\n| 2 | User presses `⌘K` | Command palette opens | Modal overlay with focus on input |\n| 3 | User types \"Acme\" | Universal search queries Spine + Memory | Results show: Account \"Acme Corp\", Contact \"John @ Acme\", Deal \"Acme Expansion\" |\n| 4 | User selects \"Acme Corp\" account | Entity360 assembled, SSE stream opens to Twin | Detail pane loads account header, traits, timeline. Twin bar appears: \"Last contact: 5 days ago. Suggested: send follow-up.\" |\n| 5 | User clicks \"Send Follow-up Email\" in Action Panel | Capability invocation routed through Hermes, governance pre-check | If confidence ≥0.85: executes immediately. If 0.70–0.85: proposal queued in My Desk. If <0.70: shows reason for low confidence. |\n| 6 | User switches to CS projection (`2` key) | Same account, CS lens applied | Detail pane shows: health score, support tickets, NPS, churn risk. Twin bar updates: \"Churn risk: medium (0.62). 2 open tickets > 3 days.\" |\n| 7 | User clicks \"Review Tickets\" | Capability invocation to `platform.entity360.get` with `includeTickets=true` | Detail pane updates to show embedded ticket list |\n| 8 | User clicks Memory Panel handle | Drawer opens, queries `continuity` service | Memory snippets displayed: sentiment, key topics, last interaction |\n\n---\n\n### 1.6 States\n\n#### Empty States\n\n| State | Visual Treatment | Action |\n| ---------------------- | ------------------------------------------------------------------------------------- | ------------------------------ |\n| **No entity selected** | Detail pane: centered illustration + \"Select an entity to begin\" + suggested entities | Show recent + popular entities |\n| **No connected tools** | Entity Explorer: \"Connect your first tool\" CTA + connector marketplace link | Prompt to CONNECT step |\n| **No search results** | Search: \"No results for 'X'\" + \"Did you mean?\" + create entity option | Offer fuzzy match + create |\n| **No Twin insights** | Twin bar: collapsed to 0px, no handle visible | Silent — no UI for absence |\n| **No memory** | Memory panel: \"No accumulated memory yet. Interactions will appear here.\" | Inform + reassure |\n\n#### Loading States\n\n| Component | Loading Indicator | Duration Expectation |\n| -------------- | ------------------------------------------------- | ---------------------- |\n| Entity list | Skeleton rows (`animate-pulse`, `bg-neutral-200`) | <200ms (KV) |\n| Entity360 | Skeleton cards + shimmer on header | <2s (cache hit <100ms) |\n| Capabilities | Spinner in Action Panel | <50ms (KV) |\n| Search results | Inline spinner in search bar | <500ms |\n| Twin insights | `...` typing indicator in bar | <3s |\n\n#### Error States\n\n| Error | Visual Treatment | Recovery |\n| ---------------------- | ------------------------------------------------------------------- | ------------------------------------- |\n| **Entity not found** | \"Entity not found or access denied\" + 403 icon + \"Go back\" | Return to previous entity |\n| **Capability blocked** | Governance badge: \"Requires approval\" + \"Go to My Desk\" | Redirect to proposal |\n| **Network error** | Toast: \"Connection lost. Retrying...\" + offline indicator in header | Auto-retry SSE, manual retry for sync |\n| **Rate limited** | Toast: \"Too many requests. Slow down.\" + countdown | Disable rapid actions |\n| **Permission denied** | \"You don't have access to this\" + contact admin CTA | Read-only mode |\n\n#### Success States\n\n| Action | Feedback | Duration |\n| ------------------- | --------------------------------------------- | --------- |\n| Entity created | Toast: \"Account created\" + link to new entity | 3s |\n| Capability executed | Toast: \"Done\" + inline checkmark | 2s |\n| Proposal approved | Inline badge update: \"Approved → Executing\" | Immediate |\n| Memory reinforced | Subtle sparkle on Memory Panel icon | 500ms |\n| Projection switched | Content crossfade | 200ms |\n\n---\n\n### 1.7 Accessibility\n\n| Requirement | Implementation |\n| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |\n| **Keyboard navigation** | `Tab` cycles through all interactive elements. `Shift+Tab` reverse. `Enter`/`Space` activates. `Esc` closes modals/panels. |\n| **Command palette** | `⌘K` (Mac) / `Ctrl+K` (Win) opens. `↑`/`↓` navigates. `Enter` selects. `Esc` closes. |\n| **Projection shortcuts** | `1`–`8` switches projections. `Shift+number` opens in split view. |\n| **Screen reader** | All icons have `aria-label`. Entity list: `role=\"listbox\"`, `aria-activedescendant`. Detail pane: `aria-live=\"polite\"` for updates. |\n| **Focus management** | Focus trap in modals. Return focus after close. Visible focus ring: `ring-2 ring-primary-500 ring-offset-2`. |\n| **Color contrast** | All text meets WCAG AA (4.5:1). Confidence badges use shape + text, not just color. |\n| **Reduced motion** | `prefers-reduced-motion: reduce` disables animations. Transitions become instant. |\n| **Entity Explorer** | `aria-label=\"Entity Explorer\"`. Collapsible: `aria-expanded`. Tree items: `aria-selected`. |\n| **Twin Bar** | `aria-live=\"polite\"` so insights are announced. Dismiss button has `aria-label=\"Dismiss insight\"`. |\n| **Memory Panel** | `aria-label=\"Memory about this entity\"`. Drawer: `aria-hidden` when closed. |\n\n---\n\n### 1.8 Responsive Behavior\n\n| Breakpoint | Layout | Behavior |\n| ----------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| **Desktop (≥1280px)** | Full 3-column: Explorer (240px) + Detail (fluid) + Action (320px) | All panels visible. Twin bar and Memory drawer at bottom. |\n| **Tablet (768–1279px)** | 2-column: Explorer (collapsed to 64px icons) + Detail (fluid). Action panel as overlay drawer. | Action panel toggles via floating FAB. Memory drawer as bottom sheet. |\n| **Mobile (<768px)** | Single column: Detail pane only. Explorer as overlay drawer. Action panel as bottom sheet. | Swipe left from edge opens Explorer. Swipe right from edge opens Action panel. Bottom nav bar for common actions. |\n| **Mobile collapsed** | Only selected entity visible. Search is primary entry point. | Command palette becomes primary navigation. |\n\n---\n\n## 2. Overlay (Communication Layer)\n\n### 2.1 Overview\n\nThe Overlay is the **ambient, always-on communication layer**. It is not a separate page — it is a floating companion that lives alongside the Workbench. It carries the Twin's 5 communication channels: Proposals, Notifications, Morning Briefing, Workbench Enrichment, and Direct Messaging.\n\n**User Journey Position:** Cross-cutting. Present in all phases after HYDRATE. The Twin is ambient — it does not wait to be called.\n\n**Core Principles:**\n\n- Ephemeral: never takes over the screen.\n- Context-aware: shows insights based on what the user is looking at.\n- Dismissible: every message can be dismissed with one click or swipe.\n- Non-blocking: work continues underneath.\n\n---\n\n### 2.2 Layout / Wireframe Description\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ WORKBENCH CONTENT │ │\n│ │ │ │\n│ │ │ │\n│ │ │ │\n│ │ │ │\n│ │ │ │\n│ │ │ │\n│ │ │ │\n│ │ │ │\n│ │ │ │\n│ │ │ │\n│ │ │ │\n│ │ │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌──────────────────────────────────────────────────────────────────┐ │\n│ │ TWIN ENRICHMENT BAR (inline, above overlay) │ │\n│ │ 💡 \"3 accounts show churn risk...\" [Review] [Dismiss] │ │\n│ └──────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ MEMORY PANEL DRAWER (bottom, collapsible) │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─────┐ │\n│ │ ● │ ← FLOATING BUBBLE (bottom-right, 56px) │\n│ │ 🤖 │ • Subtle pulse when unread │\n│ └─────┘ • Color dot for priority │\n│ • Drag to reposition (within bounds) │\n│ │\n│ [OVERLAY EXPANDED STATE — slides in from right edge] │\n│ ┌────────────────────────────────────────────────────────┐ │\n│ │ OVERLAY PANEL (400px wide, max 80vh) │ │\n│ │ ┌──────────────────────────────────────────────────┐ │ │\n│ │ │ HEADER (48px) │ │ │\n│ │ │ [🤖] Twin [🔔] [✉️] [⚙️] │ │ │\n│ │ └──────────────────────────────────────────────────┘ │ │\n│ │ ┌──────────────────────────────────────────────────┐ │ │\n│ │ │ CONTEXT CHIP (current entity) │ │ │\n│ │ │ 📁 Acme Corp → What would you like to do? │ │ │\n│ │ └──────────────────────────────────────────────────┘ │ │\n│ │ ┌──────────────────────────────────────────────────┐ │ │\n│ │ │ MESSAGE STREAM (scrollable, reverse) │ │ │\n│ │ │ ┌────────────────┐ │ │ │\n│ │ │ │ 🔔 Notification │ \"Salesforce sync complete\" │ │ │\n│ │ │ └────────────────┘ │ │ │\n│ │ │ ┌────────────────────────────────────┐ │ │ │\n│ │ │ │ 💡 Proposal (confidence: 0.92) │ │ │ │\n│ │ │ │ \"Update Acme's renewal date to │ │ │ │\n│ │ │ │ July 15. It was pushed from SF.\" │ │ │ │\n│ │ │ │ [Approve] [Modify] [Dismiss] │ │ │ │\n│ │ │ └────────────────────────────────────┘ │ │ │\n│ │ │ ┌────────────────┐ │ │ │\n│ │ │ │ 🤖 Twin │ \"You usually review...\" │ │ │\n│ │ │ └────────────────┘ │ │ │\n│ │ │ ┌────────────────────────────────────┐ │ │ │\n│ │ │ │ 📊 Morning Briefing │ │ │ │\n│ │ │ │ 3 new deals, 2 proposals pending │ │ │ │\n│ │ │ │ [View Full Briefing] │ │ │ │\n│ │ │ └────────────────────────────────────┘ │ │ │\n│ │ └──────────────────────────────────────────────────┘ │ │\n│ │ ┌──────────────────────────────────────────────────┐ │ │\n│ │ │ QUICK INPUT BAR (56px) │ │ │\n│ │ │ [🎤] [Type a message or command...] [Send] │ │ │\n│ │ │ ┌──────────────────────────────────────────┐ │ │ │\n│ │ │ │ CAPABILITY BUTTONS: 📧 Email 📞 Call │ │ │ │\n│ │ │ │ 📋 Task 🔗 Link │ │ │ │\n│ │ │ └──────────────────────────────────────────┘ │ │ │\n│ │ └──────────────────────────────────────────────────┘ │ │\n│ └────────────────────────────────────────────────────────┘ │\n│ │\n│ [TOAST NOTIFICATIONS — top-right, stacked] │\n│ ┌────────────────────────────────────┐ │\n│ │ ✅ Salesforce sync completed │ ← auto-dismiss 5s │\n│ │ ⚠️ 3 proposals need review │ ← persistent until acted │\n│ └────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n### 2.3 Key UI Components\n\n#### 2.3.1 Floating Bubble\n\n```typescript\ninterface FloatingBubbleProps {\n unreadCount: number;\n priority: \"none\" | \"info\" | \"warning\" | \"proposal\";\n isOpen: boolean;\n onClick: () => void;\n onDragEnd: (position: { x: number; y: number }) => void;\n}\n```\n\n**Visual Spec:**\n\n- Size: `56px` circle (`w-14 h-14`)\n- Position: `fixed bottom-6 right-6`, `z-50`\n- Background: `bg-white shadow-lg border border-neutral-200`\n- Icon: Twin robot icon (`text-primary-600`, `24px`)\n- Unread badge: `absolute -top-1 -right-1 w-5 h-5 rounded-full text-[10px] font-bold flex items-center justify-center`\n - Priority info: `bg-primary-500 text-white`\n - Priority warning: `bg-warning-500 text-white`\n - Priority proposal: `bg-danger-500 text-white animate-pulse`\n- Pulse: `animate-subtle-pulse` when unread > 0 (not aggressive, 3s cycle)\n- Drag: `pointer-events-auto`, constrained to viewport minus `24px` padding\n- Hover: `scale-105`, `shadow-xl`, `transition-transform duration-200`\n- Open state: icon rotates `90°` to `×` (close indicator)\n\n#### 2.3.2 Overlay Panel (Slide-out Drawer)\n\n```typescript\ninterface OverlayPanelProps {\n isOpen: boolean;\n contextEntity?: { id: string; name: string; type: string };\n messages: OverlayMessage[];\n onClose: () => void;\n onSendMessage: (text: string) => void;\n onAction: (messageId: string, action: string) => void;\n}\n\ninterface OverlayMessage {\n id: string;\n type: \"notification\" | \"proposal\" | \"twin\" | \"briefing\" | \"user\";\n content: string;\n timestamp: Date;\n confidence?: number;\n actions?: { label: string; action: string; style: \"primary\" | \"secondary\" | \"danger\" }[];\n metadata?: Record;\n}\n```\n\n**Visual Spec:**\n\n- Width: `400px` (`w-[400px]`), max `90vw` on mobile\n- Height: `max-h-[80vh]`, `min-h-[400px]`\n- Position: `fixed right-0 bottom-0`, slides in from right\n- Background: `bg-white shadow-2xl border-l border-neutral-200 rounded-tl-2xl`\n- Animation: `translate-x-full` → `translate-x-0`, `400ms`, `ease-out`\n- Header (`48px`):\n - Left: Twin avatar (`32px`) + \"Twin\" label (`text-sm font-medium`)\n - Right: Notification bell + Message count + Settings (gear)\n- Context Chip (`40px`):\n - Shows current entity if user is viewing one\n - `bg-neutral-100 rounded-full px-3 py-1 text-xs flex items-center gap-2`\n - Clicking: \"What about this entity?\" quick query\n- Message Stream (`flex-1`, scrollable):\n - Reverse chronological (newest at bottom)\n - Each message: `rounded-lg p-3 mb-2 max-w-[90%]`\n - Type-specific styling:\n - **Notification:** `bg-neutral-50 border border-neutral-200`, left-aligned\n - **Proposal:** `bg-primary-50 border border-primary-200`, left-aligned, confidence badge\n - **Twin:** `bg-amber-50 border border-amber-200`, left-aligned\n - **Briefing:** `bg-blue-50 border border-blue-200`, left-aligned, full-width\n - **User:** `bg-primary-600 text-white`, right-aligned\n - Timestamp: `text-[10px] text-neutral-400 mt-1` on all messages\n- Input Bar (`56px`):\n - Text input: `flex-1 bg-neutral-100 rounded-full px-4 py-2 text-sm`\n - Placeholder: \"Ask the Twin anything...\" or context-aware: \"About Acme Corp...\"\n - Send button: `primary` icon button, disabled when empty\n - Voice input: `🎤` icon (optional, speech-to-text)\n- Capability Buttons (collapsible row above input):\n - Context-aware quick actions: `Email`, `Call`, `Task`, `Link`, `Summarize`\n - Each: `rounded-full bg-white border border-neutral-200 px-3 py-1 text-xs hover:bg-neutral-50`\n\n#### 2.3.3 Proposal Card (within Overlay)\n\n```typescript\ninterface ProposalCardProps {\n proposal: {\n id: string;\n summary: string;\n confidence: number;\n reasoningTrace: string;\n estimatedImpact?: { revenue?: number; timeSaved?: number; riskScore?: number };\n capability: string;\n payload: unknown;\n };\n onApprove: () => void;\n onModify: () => void;\n onReject: () => void;\n onDismiss: () => void;\n}\n```\n\n**Visual Spec:**\n\n- Container: `bg-primary-50 border border-primary-200 rounded-lg p-4`\n- Header: `💡` + \"Proposal\" + confidence badge\n - Confidence badge: `rounded-full px-2 py-0.5 text-xs font-bold`\n - `≥0.85`: `bg-success text-white` + \"Auto-approved\"\n - `0.70–0.85`: `bg-warning text-white` + \"Needs approval\"\n- Body: `text-sm text-primary-900` summary\n- Reasoning: collapsible `accordion`, `text-xs text-primary-600`\n- Impact: mini-metrics row if available (`revenue`, `timeSaved`)\n- Actions: `flex gap-2 mt-3`\n - `Approve`: `bg-primary-600 text-white rounded-md px-3 py-1.5 text-sm`\n - `Modify`: `bg-white border border-primary-300 text-primary-700 rounded-md px-3 py-1.5 text-sm`\n - `Reject`: `text-danger text-sm hover:underline`\n - `Dismiss`: `text-neutral-400 text-xs hover:text-neutral-600` (x icon)\n\n#### 2.3.4 Toast Notifications\n\n```typescript\ninterface ToastProps {\n id: string;\n type: \"success\" | \"warning\" | \"error\" | \"info\";\n message: string;\n duration: number; // ms, 0 = persistent\n action?: { label: string; onClick: () => void };\n onDismiss: () => void;\n}\n```\n\n**Visual Spec:**\n\n- Position: `fixed top-6 right-6`, `z-50`, stacked with `gap-2`\n- Container: `bg-white rounded-lg shadow-lg border px-4 py-3 min-w-[300px] max-w-[400px] flex items-start gap-3`\n- Border color by type:\n - Success: `border-success`\n - Warning: `border-warning`\n - Error: `border-danger`\n - Info: `border-primary`\n- Icon: `20px` by type (check, alert, x, info)\n- Message: `text-sm text-neutral-700`\n- Action: `text-sm font-medium text-primary-600 hover:text-primary-700` (if provided)\n- Dismiss: `×` icon, `text-neutral-400 hover:text-neutral-600`\n- Auto-dismiss: `duration` timer with thin progress bar at bottom (`h-0.5`)\n- Animation: `slide-in-right` + `fade`, `300ms`\n\n#### 2.3.5 Morning Briefing Card\n\n```typescript\ninterface MorningBriefingCardProps {\n briefing: {\n overnightChanges: ChangeSummary[];\n pendingProposals: number;\n scheduledTasks: TaskSummary[];\n memorySuggestions: string[];\n proactiveInsights: string[];\n };\n onViewFull: () => void;\n onDismiss: () => void;\n}\n```\n\n**Visual Spec:**\n\n- Full-width within overlay, `bg-blue-50 border border-blue-200 rounded-lg p-4 mb-3`\n- Header: `☀️` + \"Good morning, [Name]\" + `text-sm font-medium text-blue-900`\n- Sections (collapsible, default open):\n - Overnight changes: bullet list, `text-xs text-blue-700`\n - Pending proposals: `bg-warning-100 rounded px-2 py-1 text-xs` inline\n - Scheduled tasks: `text-xs`, strikethrough when checked\n - Memory suggestions: `italic text-xs text-blue-600`\n- Footer: \"View full briefing →\" link + dismiss\n\n---\n\n### 2.4 Data Flow\n\n```\n┌──────────────────────────────────────────────────────────────────────────────┐\n│ DATA FLOW: Overlay (Communication Layer) │\n├──────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ INBOUND (Real-time) │\n│ ─────────────────── │\n│ 1. SSE Stream: gateway → client (event stream) │\n│ → notifications, proposals, twin insights, briefing triggers │\n│ │\n│ 2. Context sync: Workbench selected entity → Overlay context chip │\n│ → when user navigates, Overlay knows what they're looking at │\n│ │\n│ 3. Discovery refresh: every 60s (KV cache) │\n│ → capability buttons update based on current context + role │\n│ │\n│ OUTBOUND (User actions) │\n│ ──────────────────────── │\n│ 1. Approve/Reject proposal → gateway → govern service → HITL DO │\n│ 2. Send message → gateway → twin-orchestrator DO → think service │\n│ 3. Quick action → capability invoke → Hermes → act → provider │\n│ 4. Dismiss → client-side (no server call, but telemetry logged) │\n│ │\n│ DATA SOURCES │\n│ ──────────── │\n│ • SSE: /v1/events (Server-Sent Events, persistent connection) │\n│ • Context: Workbench state (shared client-side store) │\n│ • Capabilities: Discovery KV cache (filtered by entity type + role) │\n│ • Proposals: govern service (pending for user) │\n│ • Notifications: notification queue (KV-backed) │\n│ │\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n### 2.5 User Interactions\n\n#### Flow: User Receives and Acts on a Proposal\n\n| Step | Action | System Response | UI Change |\n| ---- | ----------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------ |\n| 1 | Twin generates proposal (confidence 0.78) | Proposal queued in HITL DO, SSE event emitted | Floating bubble pulses orange, unread badge +1 |\n| 2 | User clicks floating bubble | Overlay panel slides in, message stream shows new proposal at bottom | Proposal card rendered with \"Needs approval\" badge |\n| 3 | User clicks \"Approve\" | Gateway → govern → HITL DO → ACT_QUEUE → act → provider | Proposal card updates: \"Approved → Executing...\" → \"Done ✅\" |\n| 4 | User types \"Why did you suggest that?\" in input | Gateway → twin-orchestrator DO → reasoning trace returned | Twin message appears: \"Based on the pattern...\" |\n| 5 | User dismisses overlay | Panel slides out, floating bubble returns to normal | Bubble shows no unread if all handled |\n\n---\n\n### 2.6 States\n\n#### Empty States\n\n| State | Visual Treatment |\n| ---------------- | ------------------------------------------------------------------------- |\n| **No messages** | \"You're all caught up. The Twin is watching.\" + subtle robot illustration |\n| **No context** | Context chip shows: \"No entity selected. Browse or search to begin.\" |\n| **Disconnected** | \"Reconnecting...\" + spinner in header. Retry button after 5s. |\n\n#### Loading States\n\n| Component | Indicator |\n| ---------------- | ------------------------------------------ |\n| Message stream | Skeleton messages (`animate-pulse`) |\n| Proposal card | Inline spinner on action buttons |\n| Send message | Input disabled + \"Thinking...\" placeholder |\n| SSE reconnecting | Header dot: `yellow` + \"Reconnecting...\" |\n\n---\n\n### 2.7 Accessibility\n\n| Requirement | Implementation |\n| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| **Keyboard** | `Esc` closes overlay. `Tab` traps within panel. `Enter` sends message. `↑`/`↓` navigates message history (in input). |\n| **Screen reader** | Messages: `aria-live=\"polite\"` on stream container. Proposals: `role=\"alert\"` + `aria-label=\"Proposal requiring approval\"`. |\n| **Focus** | When panel opens, focus moves to input. When closed, focus returns to trigger. |\n| **Motion** | Panel slides only if `prefers-reduced-motion: no-preference`. Otherwise: instant appear. |\n| **Contrast** | All message types meet AA. Proposal badges have text + color. |\n\n---\n\n### 2.8 Responsive Behavior\n\n| Breakpoint | Behavior |\n| -------------------- | ------------------------------------------------------------------------------------------------ |\n| **Desktop** | Panel: `400px` right-side drawer. Bubble: bottom-right. |\n| **Tablet** | Panel: `100vw` overlay from bottom (sheet). Bubble: bottom-right. |\n| **Mobile** | Panel: full-screen bottom sheet (`h-[90vh]`). Bubble: bottom-right, `48px`. Swipe down to close. |\n| **Mobile landscape** | Panel: `50vw` right-side drawer. |\n\n---\n\n## 3. AI Home\n\n### 3.1 Overview\n\nAI Home is the dedicated natural-language interface to the entire platform. It is where the user goes to \"talk to the AI\" directly — like OpenWeb UI, ChatGPT, or Claude. Unlike the Overlay (ambient), AI Home is an intentional destination: the user opens it to have a focused conversation with the Twin.\n\n**User Journey Position:** Step 4 (AI) — \"The AI knew what I needed before I asked.\"\n\n**Core Principles:**\n\n- Natural language is the primary input. The AI understands context, capabilities, and intent.\n- Every response is grounded in what the system knows (Memory, Entity360, Knowledge).\n- The AI can cite its sources. The user can verify.\n- The AI can invoke capabilities directly (with governance).\n- File uploads enable multimodal analysis.\n\n---\n\n### 3.2 Layout / Wireframe Description\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ TOP BAR (56px) │\n│ ┌────┐ ┌─────────────────┐ ┌────────────────────────────────────────────┐ │\n│ │ IW │ │ AI Home │ │ [Model: GPT-5 ▼] [New Chat] [Settings] │ │\n│ └────┘ └─────────────────┘ └────────────────────────────────────────────┘ │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌──────────┐ ┌────────────────────────────────────┐ ┌────────────────┐ │\n│ │ CHAT │ │ │ │ CONTEXT PANEL │ │\n│ │ HISTORY │ │ CHAT CANVAS │ │ (320px) │ │\n│ │ (260px) │ │ (Fluid, centered) │ │ │ │\n│ │ │ │ │ │ ┌────────────┐ │ │\n│ │ New Chat │ │ ┌────────────────────────────┐ │ │ │ Current │ │ │\n│ │ [+] │ │ │ │ │ │ │ Topic │ │ │\n│ │ │ │ │ [WELCOME / EMPTY STATE] │ │ │ │ • Entities │ │ │\n│ │ Today │ │ │ ┌────────────────────────┐ │ │ │ │ • Memory │ │ │\n│ │ ┌──────┐ │ │ │ │ \"What can I help │ │ │ │ │ • Knowledge│ │ │\n│ │ │Brief │ │ │ │ │ you with today?\" │ │ │ │ └────────────┘ │ │\n│ │ │Deal │ │ │ │ │ │ │ │ │ │ │\n│ │ └──────┘ │ │ │ │ [Quick starters] │ │ │ │ ┌────────────┐ │ │\n│ │ │ │ │ │ ┌────┐ ┌────┐ ┌────┐ │ │ │ │ │ Capabilities│ │ │\n│ │ Yesterday│ │ │ │ │Summ│ │Last│ │Create│ │ │ │ │ Available │ │ │\n│ │ ┌──────┐ │ │ │ │ │arize│ │Week│ │Task│ │ │ │ │ • 42 tools │ │ │\n│ │ │Churn │ │ │ │ │ └────┘ └────┘ └────┘ │ │ │ │ │ connected │ │ │\n│ │ └──────┘ │ │ │ └────────────────────────┘ │ │ │ └────────────┘ │ │\n│ │ │ │ │ │ │ │ │ │\n│ │ 7 Days │ │ │ [MESSAGES] │ │ │ ┌────────────┐ │ │\n│ │ ┌──────┐ │ │ │ │ │ │ │ Memory │ │ │\n│ │ │Q2 │ │ │ │ ┌────────────────────────┐ │ │ │ │ References │ │ │\n│ │ └──────┘ │ │ │ │ 👤 User │ │ │ │ │ (cited) │ │ │\n│ │ │ │ │ │ \"What should I do │ │ │ │ │ • Account │ │ │\n│ │ 30 Days │ │ │ │ about Acme Corp?\" │ │ │ │ │ history │ │ │\n│ │ ┌──────┐ │ │ │ └────────────────────────┘ │ │ │ │ • Past │ │ │\n│ │ │Sync │ │ │ │ │ │ │ │ │ decisions│ │ │\n│ │ └──────┘ │ │ │ ┌────────────────────────┐ │ │ │ └────────────┘ │ │\n│ │ │ │ │ │ 🤖 Twin │ │ │ │ │ │\n│ │ │ │ │ │ \"Based on the account │ │ │ │ ┌────────────┐ │ │\n│ │ │ │ │ │ health score (0.72) and │ │ │ │ │ File │ │ │\n│ │ │ │ │ │ 2 open tickets...\" │ │ │ │ │ Uploads │ │ │\n│ │ │ │ │ │ │ │ │ │ │ • Q2.pdf │ │ │\n│ │ │ │ │ │ [Tool Call: entity360] │ │ │ │ │ • logo.png │ │ │\n│ │ │ │ │ │ [Tool Call: memory] │ │ │ │ └────────────┘ │ │\n│ │ │ │ │ │ │ │ │ └────────────────┘ │\n│ │ │ │ │ │ [💡 Proposal card] │ │ │ │ │\n│ │ │ │ │ │ \"I suggest escalating │ │ │ │ │\n│ │ │ │ │ │ to CSM. Approve?\" │ │ │ │ │\n│ │ │ │ │ │ [Approve] [Dismiss] │ │ │ │ │\n│ │ │ │ │ └────────────────────────┘ │ │ │ │\n│ │ │ │ │ │ │ │ │\n│ │ │ │ │ ┌────────────────────────┐ │ │ │ │\n│ │ │ │ │ │ 👤 User │ │ │ │ │\n│ │ │ │ │ │ \"Show me the pipeline\" │ │ │ │ │\n│ │ │ │ │ └────────────────────────┘ │ │ │ │\n│ │ │ │ │ │ │ │ │\n│ │ │ │ │ ┌────────────────────────┐ │ │ │ │\n│ │ │ │ │ │ 🤖 Twin (generating) │ │ │ │ │\n│ │ │ │ │ │ [streaming dots] │ │ │ │ │\n│ │ │ │ │ └────────────────────────┘ │ │ │ │\n│ │ │ │ │ │ │ │ │\n│ │ │ │ └────────────────────────────┘ │ │ │\n│ │ │ │ │ │ │\n│ │ │ │ ┌────────────────────────────────┐ │ │\n│ │ │ │ │ INPUT BAR (72px) │ │ │\n│ │ │ │ │ ┌────┐ ┌─────────────────┐ ┌──┐ │ │\n│ │ │ │ │ │ 📎 │ │ Type a message... │ │⬆️│ [Capability │ │\n│ │ │ │ │ │ │ │ │ │ │ buttons row] │ │\n│ │ │ │ │ └────┘ └─────────────────┘ └──┘ │ │\n│ │ │ │ └────────────────────────────────┘ │ │\n│ │ │ │ │ │ │\n│ └──────────┘ └────────────────────────────────────┘ └────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n### 3.3 Key UI Components\n\n#### 3.3.1 Chat History Sidebar\n\n```typescript\ninterface ChatHistoryProps {\n sessions: ChatSession[];\n activeSessionId: string;\n onSelect: (sessionId: string) => void;\n onNewChat: () => void;\n onDelete: (sessionId: string) => void;\n onRename: (sessionId: string, title: string) => void;\n}\n\ninterface ChatSession {\n id: string;\n title: string; // auto-generated or user-edited\n preview: string; // last message preview\n timestamp: Date;\n messageCount: number;\n isPinned: boolean;\n}\n```\n\n**Visual Spec:**\n\n- Width: `260px` (`w-65`), collapsible to `0` on mobile\n- Background: `bg-slate-50 border-r border-neutral-200`\n- Top: \"New Chat\" button (`full-width`, `primary`, `gap-2`, `+` icon)\n- Grouped by date: \"Today\", \"Yesterday\", \"7 Days\", \"30 Days\"\n- Each session:\n - `flex row gap-3 px-3 py-2 rounded-lg hover:bg-neutral-100 cursor-pointer`\n - Icon: `message-square` or `pin` (if pinned)\n - Title: `text-sm truncate max-w-[180px]`\n - Preview: `text-xs text-neutral-400 truncate`\n - Right: `...` menu (rename, delete, pin)\n- Active: `bg-primary-50 text-primary-700 border-l-3 border-primary-500`\n- Empty: \"No conversations yet. Start one!\"\n\n#### 3.3.2 Chat Canvas (Message Stream)\n\n```typescript\ninterface ChatCanvasProps {\n messages: ChatMessage[];\n isGenerating: boolean;\n onRegenerate: (messageId: string) => void;\n onCopy: (text: string) => void;\n onFeedback: (messageId: string, feedback: \"good\" | \"bad\") => void;\n}\n\ninterface ChatMessage {\n id: string;\n role: \"user\" | \"assistant\" | \"system\";\n content: string;\n timestamp: Date;\n toolCalls?: ToolCallDisplay[];\n memoryCitations?: MemoryCitation[];\n fileAttachments?: FileAttachment[];\n proposal?: ProposalCardProps[\"proposal\"];\n}\n```\n\n**Visual Spec:**\n\n- Centered, `max-w-3xl`, `mx-auto`\n- Background: `bg-white` (subtle `bg-neutral-50` for AI messages)\n- Scrollable, reverse? No — scrollable top-to-bottom, auto-scroll to bottom on new messages\n- User messages: `ml-auto max-w-[80%] bg-primary-600 text-white rounded-2xl rounded-tr-sm px-4 py-3`\n- AI messages: `mr-auto max-w-[80%] bg-neutral-50 border border-neutral-200 rounded-2xl rounded-tl-sm px-4 py-3`\n- System/tool messages: `full-width bg-neutral-100 border border-neutral-200 rounded-lg px-4 py-2`\n- Message actions (AI only, on hover):\n - `Copy`, `Regenerate`, `👍`/`👎` feedback\n - Row of icons, `text-neutral-400 hover:text-neutral-600`, `gap-2`\n- Streaming state: `...` dots animation (`animate-bounce` on 3 dots)\n\n#### 3.3.3 Model Selector\n\n```typescript\ninterface ModelSelectorProps {\n models: AIModel[];\n selected: string;\n onSelect: (modelId: string) => void;\n}\n\ninterface AIModel {\n id: string;\n name: string;\n provider: \"openai\" | \"anthropic\" | \"openrouter\" | \"local\";\n description: string;\n capabilities: (\"text\" | \"vision\" | \"code\" | \"long-context\")[];\n isAvailable: boolean;\n}\n```\n\n**Visual Spec:**\n\n- Dropdown in top bar, right-aligned\n- Trigger: `rounded-full bg-neutral-100 px-3 py-1.5 text-sm flex items-center gap-2`\n- Selected model name + `▾` chevron\n- Dropdown: `bg-white rounded-lg shadow-lg border border-neutral-200 py-1 min-w-[240px]`\n- Each model:\n - `flex row gap-3 px-3 py-2.5 hover:bg-neutral-50`\n - Left: provider icon + model name (`text-sm font-medium`)\n - Right: capability badges (`text-[10px]`, `bg-neutral-100 rounded px-1`)\n - Description: `text-xs text-neutral-400` below name\n- Unavailable: `opacity-50 cursor-not-allowed`, tooltip: \"Enterprise plan required\"\n\n#### 3.3.4 Tool Call Display\n\n```typescript\ninterface ToolCallDisplayProps {\n toolCall: {\n id: string;\n capability: string;\n status: \"pending\" | \"running\" | \"success\" | \"error\";\n input?: unknown;\n output?: unknown;\n latencyMs?: number;\n };\n}\n```\n\n**Visual Spec:**\n\n- Inline within AI message, `full-width`\n- Container: `bg-neutral-100 rounded-lg border border-neutral-200 p-3 mb-2`\n- Header: `flex row gap-2 items-center`\n - Status icon: spinner (`pending`/`running`), check (`success`), x (`error`)\n - Capability name: `text-xs font-mono font-medium text-neutral-700`\n - Latency: `text-[10px] text-neutral-400` (if completed)\n- Expandable: `accordion` with input/output details\n - Input: `JSON` formatted, `font-mono text-xs bg-white rounded p-2`\n - Output: same, collapsed by default\n- Error: `bg-danger-50 border-danger-200`, error message shown inline\n\n#### 3.3.5 Memory Citation\n\n```typescript\ninterface MemoryCitationProps {\n citation: {\n memoryId: string;\n content: string;\n source: string;\n confidence: number;\n entityName?: string;\n };\n}\n```\n\n**Visual Spec:**\n\n- Inline within AI message, `inline-block` or `block` depending on context\n- Container: `bg-amber-50 border border-amber-200 rounded px-2 py-1 text-xs inline-flex items-center gap-1`\n- Icon: `bookmark` or `brain` (`text-amber-600`)\n- Text: truncated content + \"→\" link to full memory\n- Hover: tooltip shows full content + source + confidence\n- Click: opens Memory detail modal or navigates to entity\n\n#### 3.3.6 Capability Invocation Buttons (Bottom)\n\n```typescript\ninterface CapabilityButtonsProps {\n capabilities: { capability: string; label: string; icon: string }[];\n onInvoke: (capability: string) => void;\n}\n```\n\n**Visual Spec:**\n\n- Row of `rounded-full bg-white border border-neutral-200 px-3 py-1 text-xs` pills\n- Above input bar, `gap-2`, `flex-wrap`\n- Context-aware: changes based on conversation topic\n- Hover: `bg-neutral-50 shadow-sm`\n- Click: sends message with capability trigger + shows tool call display\n\n#### 3.3.7 File Upload\n\n```typescript\ninterface FileUploadProps {\n files: File[];\n maxSize: number; // bytes\n acceptedTypes: string[];\n onUpload: (files: File[]) => void;\n onRemove: (fileIndex: number) => void;\n}\n```\n\n**Visual Spec:**\n\n- Trigger: `📎` icon button in input bar, left side\n- Click: opens file picker\n- Drag-and-drop: entire chat canvas accepts drops (`border-2 border-dashed border-primary-400 bg-primary-50` when dragging)\n- Uploaded files: row of chips above input bar\n - Each chip: `bg-neutral-100 rounded-full px-3 py-1 text-xs flex items-center gap-2`\n - Icon by mime type (`image`, `pdf`, `document`)\n - Filename (truncated) + `×` to remove\n- Progress: inline `progress bar` if uploading to R2\n- Error (too large): `toast` with max size info\n\n---\n\n### 3.4 Data Flow\n\n```\n┌──────────────────────────────────────────────────────────────────────────────┐\n│ DATA FLOW: AI Home │\n├──────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ INBOUND │\n│ ─────── │\n│ 1. Chat sessions → D1 (chat_sessions table) + KV cache (recent) │\n│ 2. Messages → D1 (chat_messages) + SSE streaming for real-time │\n│ 3. Model catalog → static config + runtime health check │\n│ 4. Context Panel → assembled from current chat topic + memory │\n│ │\n│ OUTBOUND │\n│ ──────── │\n│ 1. User message → gateway → twin-orchestrator DO │\n│ → DO assembles Entity360 + Memory + Knowledge + Tools │\n│ → think service (LLM) → streaming response │\n│ 2. File upload → R2 (direct) → knowledge service (chunk + index) │\n│ 3. Capability invoke (from chat) → Hermes → act → provider │\n│ 4. Feedback → telemetry queue (implicit) │\n│ │\n│ SERVICES │\n│ ──────── │\n│ • gateway (auth, SSE routing) │\n│ • twin-orchestrator (per-user DO, session state) │\n│ • think (LLM orchestration, streaming) │\n│ • intelligence (context assembly) │\n│ • knowledge (RAG for uploaded docs) │\n│ • continuity (memory query) │\n│ • agent-registry (capability catalog for tool calls) │\n│ • store (chat session persistence) │\n│ │\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n### 3.5 User Interactions\n\n#### Flow: User Asks About an Account and Gets a Proposal\n\n| Step | Action | System Response | UI Change |\n| ---- | --------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------- |\n| 1 | User types \"What should I do about Acme Corp?\" | Message sent to twin-orchestrator DO | User message appears in canvas. AI shows \"Thinking...\" |\n| 2 | Twin assembles context: Entity360 for Acme + Memory + Knowledge | DO queries intelligence, continuity, knowledge | Tool call displays: `entity360.get` (success), `memory.query` (success) |\n| 3 | LLM generates response with proposal | Streaming response via SSE | AI message appears with inline memory citations |\n| 4 | Proposal generated (confidence 0.91) | Govern pre-check: auto-approve | Proposal card inline: \"I suggest escalating to CSM.\" + \"Approved\" badge |\n| 5 | User clicks \"Tell me more\" | Twin explains reasoning trace | New AI message with expanded reasoning |\n| 6 | User drags a PDF into chat | File uploaded to R2, indexed | File chip appears. Knowledge query includes document. |\n| 7 | User asks \"What does the contract say about renewals?\" | Knowledge RAG → LLM | AI cites knowledge chunks with page numbers |\n\n---\n\n### 3.6 States\n\n#### Empty States\n\n| State | Visual Treatment |\n| --------------------- | ---------------------------------------------------------------------------------------- |\n| **No chat selected** | Center: Twin avatar + \"What can I help you with today?\" + Quick starter cards (3×2 grid) |\n| **No history** | Sidebar: \"No conversations yet. Start one!\" |\n| **No context** | Context panel: \"Start a conversation to see context.\" |\n| **Model unavailable** | Selector: \"Unavailable\" badge + tooltip. Fallback to next model. |\n\n#### Loading States\n\n| Component | Indicator |\n| ---------------- | ----------------------------------- |\n| AI response | Streaming dots + \"Thinking...\" |\n| Tool call | Inline spinner with capability name |\n| File upload | Progress bar + \"Uploading...\" |\n| Context assembly | Subtle shimmer on Context Panel |\n| Session load | Skeleton message list |\n\n---\n\n### 3.7 Accessibility\n\n| Requirement | Implementation |\n| ----------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| **Keyboard** | `Tab` navigates input + buttons. `Enter` sends. `Shift+Enter` newline. `↑` recalls last message (in input). |\n| **Screen reader** | Messages: `aria-live=\"polite\"`. User messages: `aria-label=\"You said: ...\"`. AI messages: `aria-label=\"Twin said: ...\"`. |\n| **Focus** | Input always focusable. New messages scroll into view. |\n| **High contrast** | User messages: white on primary. AI messages: neutral-900 on neutral-50. |\n| **Motion** | `prefers-reduced-motion` disables streaming animation. Text appears instantly. |\n\n---\n\n### 3.8 Responsive Behavior\n\n| Breakpoint | Layout |\n| ------------------- | ------------------------------------------------------------------------------ |\n| **Desktop** | Full 3-column: History (260px) + Canvas (fluid) + Context (320px) |\n| **Tablet** | History collapsible (drawer). Canvas + Context visible. |\n| **Mobile** | Full-screen canvas. History via swipe from left. Context via swipe from right. |\n| **Mobile portrait** | Input bar fixed at bottom. Messages scroll above. |\n\n---\n\n## 4. Capability Fabric\n\n### 4.1 Overview\n\nThe Capability Fabric is the **\"what can I do?\" layer**. It is the user-facing discovery and execution surface for every named action the platform can perform. It answers the question: \"I have connected Salesforce, Slack, and Stripe — what can I do with them?\"\n\n**User Journey Position:** Post-CONNECT (Step 1), pre-WORK (Step 3). Users visit to discover capabilities after connecting tools, or to explore what's possible.\n\n**Core Principles:**\n\n- Discovery-first: show capabilities, not just tools.\n- Confidence and transparency: every capability shows what it does, what it needs, and how often it's used.\n- Try it: execute capabilities directly from the Fabric without leaving.\n- Living catalog: updates automatically as tools are connected/disconnected.\n\n---\n\n### 4.2 Layout / Wireframe Description\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ TOP BAR (64px) │\n│ ┌────┐ ┌─────────────────┐ ┌────────────────────────────────────────────┐ │\n│ │ IW │ │ Capability Fabric│ │ [🔍 Search] [Filter ▼] [View: Grid|List] │ │\n│ └────┘ └─────────────────┘ └────────────────────────────────────────────┘ │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌──────────────────────────────────────────────────────────────────────┐ │\n│ │ CONNECTED TOOLS GALLERY (horizontal scroll, 120px tall) │ │\n│ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ │\n│ │ │ [SF] │ │ [Slack]│ │ [Stripe]│ │ [GitHub]│ │ [+ Add]│ │ │\n│ │ │ ✓ Conn │ │ ✓ Conn │ │ ⚠ Sync │ │ ✓ Conn │ │ │ │ │\n│ │ │ 12 caps│ │ 8 caps │ │ 6 caps │ │ 15 caps│ │ │ │ │\n│ │ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ │ │\n│ └──────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌──────────────────────────────────────────────────────────────────────┐ │\n│ │ CATEGORY FILTERS (horizontal chips, 48px) │ │\n│ │ [All] [Sales] [Communication] [Finance] [Dev] [Platform] [AI] ... │ │\n│ └──────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌──────────────────────────────────────────────────────────────────────┐ │\n│ │ CAPABILITY GRID (main content) │ │\n│ │ │ │\n│ │ ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐ │ │\n│ │ │ [📧] │ │ [📊] │ │ [🤖] │ │ │\n│ │ │ Send Email │ │ Generate Report │ │ Analyze Sentiment │ │ │\n│ │ │ salesforce.contact │ │ platform.report │ │ twin.analyze │ │ │\n│ │ │ │ │ │ │ │ │ │\n│ │ │ \"Send a templated │ │ \"Generate a │ │ \"Analyze the │ │ │\n│ │ │ email to a │ │ pipeline report │ │ sentiment of │ │ │\n│ │ │ contact.\" │ │ for any entity.\" │ │ this account.\" │ │ │\n│ │ │ │ │ │ │ │ │ │\n│ │ │ ┌────────────────┐ │ │ ┌────────────────┐ │ │ ┌────────────────┐ │ │ │\n│ │ │ │ Used: 42× │ │ │ │ Used: 128× │ │ │ │ Used: 15× │ │ │ │\n│ │ │ │ Conf: 0.92 │ │ │ │ Conf: 0.88 │ │ │ │ Conf: 0.85 │ │ │ │\n│ │ │ └────────────────┘ │ │ └────────────────┘ │ │ └────────────────┘ │ │ │\n│ │ │ [Try It] [Details] │ │ [Try It] [Details] │ │ [Try It] [Details] │ │ │\n│ │ └────────────────────┘ └────────────────────┘ └────────────────────┘ │ │\n│ │ │ │\n│ │ ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐ │ │\n│ │ │ [⚠️] │ │ │ │ │ │ │\n│ │ │ Requires Approval │ │ ... more cards │ │ │ │ │\n│ │ │ (governed) │ │ │ │ │ │ │\n│ │ └────────────────────┘ └────────────────────┘ └────────────────────┘ │ │\n│ │ │ │\n│ └──────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ [CAPABILITY DETAIL SIDEBAR (drawer, 480px, from right)] │\n│ ┌────────────────────────────────────────────────────────────────┐ │\n│ │ [📧] Send Email │ │\n│ │ salesforce.contact.send_email │ │\n│ │ │ │\n│ │ Description: Send a templated email to a Salesforce contact. │ │\n│ │ │ │\n│ │ ┌────────────────────────────────────────────────────────┐ │ │\n│ │ │ PARAMETERS │ │ │\n│ │ │ • contact_id (string, required) │ │ │\n│ │ │ • template_id (string, optional) │ │ │\n│ │ │ • subject (string, optional) │ │ │\n│ │ │ • body (string, optional) │ │ │\n│ │ └────────────────────────────────────────────────────────┘ │ │\n│ │ │ │\n│ │ ┌────────────────────────────────────────────────────────┐ │ │\n│ │ │ REQUIRED PERMISSIONS │ │ │\n│ │ │ • salesforce:write │ │ │\n│ │ │ • capability:invoke │ │ │\n│ │ └────────────────────────────────────────────────────────┘ │ │\n│ │ │ │\n│ │ ┌────────────────────────────────────────────────────────┐ │ │\n│ │ │ AUDIT TRAIL │ │ │\n│ │ │ • Last used: 2 hours ago by alice@acme.com │ │ │\n│ │ │ • Success rate: 94% (47/50) │ │ │\n│ │ │ • Average latency: 1.2s │ │ │\n│ │ └────────────────────────────────────────────────────────┘ │ │\n│ │ │ │\n│ │ [Try It] [Add to Workflow] [Copy API Call] │ │\n│ │ │ │\n│ └────────────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n### 4.3 Key UI Components\n\n#### 4.3.1 Connected Tools Gallery\n\n```typescript\ninterface ConnectedToolsGalleryProps {\n connectors: Connector[];\n onAdd: () => void;\n onClick: (connectorId: string) => void;\n}\n\ninterface Connector {\n id: string;\n provider: string;\n displayName: string;\n icon: string;\n status: \"connected\" | \"disconnected\" | \"error\" | \"syncing\";\n capabilityCount: number;\n lastSyncAt?: Date;\n}\n```\n\n**Visual Spec:**\n\n- Horizontal scrollable row, `h-[120px]`, `gap-4`, `px-4`\n- Each card: `w-[140px] h-[100px] bg-white rounded-xl border border-neutral-200 p-3 flex flex-col justify-between`\n- Top: provider icon (`24px`) + status dot (`8px` circle, absolute top-right)\n - Connected: `bg-success`\n - Syncing: `bg-warning animate-pulse`\n - Error: `bg-danger`\n - Disconnected: `bg-neutral-300`\n- Middle: provider name (`text-sm font-medium`)\n- Bottom: capability count (`text-xs text-neutral-500`) + \"caps\"\n- \"+ Add\" card: `dashed border border-neutral-300 bg-neutral-50`, `+` icon, \"Connect tool\"\n- Hover: `shadow-md`, `border-primary-200`, `transition-all duration-200`\n\n#### 4.3.2 Category Filter Chips\n\n```typescript\ninterface CategoryFilterProps {\n categories: string[];\n active: string;\n onSelect: (category: string) => void;\n}\n```\n\n**Visual Spec:**\n\n- Horizontal scrollable row, `h-[48px]`, `gap-2`, `px-4 py-2`\n- Each chip: `rounded-full px-3 py-1 text-sm`\n- Active: `bg-primary-100 text-primary-700 border border-primary-200`\n- Inactive: `bg-white border border-neutral-200 text-neutral-600 hover:bg-neutral-50`\n- \"All\" is always first, selected by default\n\n#### 4.3.3 Capability Cards\n\n```typescript\ninterface CapabilityCardProps {\n capability: {\n id: string; // capability URI\n displayName: string;\n description: string;\n namespace: string;\n icon: string;\n usageCount: number;\n confidence: number;\n requiresApproval: boolean;\n oodaPhase: string;\n };\n onTry: () => void;\n onDetails: () => void;\n}\n```\n\n**Visual Spec:**\n\n- Grid: `grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4`\n- Card: `bg-white rounded-xl border border-neutral-200 p-5 hover:shadow-md hover:border-primary-200 transition-all duration-200`\n- Top row: icon (`32px`, `rounded-lg bg-primary-100 text-primary-600`) + capability name (`text-sm font-semibold`)\n- URI: `text-xs font-mono text-neutral-400 mt-1`\n- Description: `text-sm text-neutral-600 mt-2 line-clamp-2`\n- Stats row: `flex gap-3 mt-4 text-xs text-neutral-500`\n - `Used: N×` + `Conf: 0.XX`\n- Badge (if requires approval): `bg-warning-50 text-warning-700 border border-warning-200 rounded px-2 py-0.5 text-[10px] font-bold uppercase` \"Requires Approval\"\n- Actions: `flex gap-2 mt-4`\n - `Try It`: `bg-primary-600 text-white rounded-md px-3 py-1.5 text-sm`\n - `Details`: `bg-white border border-neutral-200 text-neutral-700 rounded-md px-3 py-1.5 text-sm`\n\n#### 4.3.4 Capability Detail Drawer\n\n```typescript\ninterface CapabilityDetailProps {\n capability: CapabilityInfo;\n onTry: () => void;\n onAddToWorkflow: () => void;\n onCopyApi: () => void;\n onClose: () => void;\n}\n```\n\n**Visual Spec:**\n\n- Drawer: `w-[480px]`, slides from right, `shadow-2xl`\n- Header: icon + name + URI (`font-mono text-xs`) + close `×`\n- Sections with `border-b border-neutral-200 pb-4 mb-4`:\n - Description: `text-sm text-neutral-700`\n - Parameters: table (`w-full text-sm`), columns: name, type, required, description\n - Required Permissions: tag list (`flex gap-2 flex-wrap`), each: `bg-neutral-100 rounded-full px-2 py-1 text-xs`\n - Audit Trail: mini stats cards (`grid-cols-3`), `bg-neutral-50 rounded-lg p-3`\n- Footer: `flex gap-3 sticky bottom-0 bg-white p-4 border-t`\n - `Try It` (primary), `Add to Workflow` (secondary), `Copy API Call` (secondary)\n\n---\n\n### 4.4 Data Flow\n\n```\n┌──────────────────────────────────────────────────────────────────────────────┐\n│ DATA FLOW: Capability Fabric │\n├──────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ INBOUND │\n│ ─────── │\n│ 1. Discovery → GET /api/v1/discovery │\n│ → connectors, capabilities, limits, features │\n│ 2. Capability details → agent-registry (KV cache, D1 fallback) │\n│ → schema, permissions, audit stats │\n│ 3. Usage stats → telemetry aggregation (D1) │\n│ │\n│ OUTBOUND (Try It) │\n│ ───────────────── │\n│ 1. User clicks \"Try It\" → form modal → gateway → Hermes → capability invoke │\n│ 2. Result shown inline in drawer or toast │\n│ 3. Add to Workflow → workflow editor opens with this capability pre-loaded │\n│ 4. Copy API Call → clipboard: curl + SDK code snippet │\n│ │\n│ SERVICES │\n│ ──────── │\n│ • gateway (discovery endpoint) │\n│ • agent-registry (capability metadata) │\n│ • connector (connector status) │\n│ • telemetry (usage stats) │\n│ • hermes (capability execution) │\n│ • workflow (workflow creation) │\n│ │\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n### 4.5 User Interactions\n\n#### Flow: User Discovers and Tries a Capability\n\n| Step | Action | System Response | UI Change |\n| ---- | ------------------------------------- | --------------------------------------- | --------------------------------------------------------- |\n| 1 | User opens Capability Fabric from nav | Discovery returns all capabilities | Gallery shows connected tools + grid of capability cards |\n| 2 | User clicks \"Salesforce\" filter | Capabilities filtered by namespace | Grid updates, only Salesforce capabilities shown |\n| 3 | User clicks \"Details\" on \"Send Email\" | Capability schema + audit stats fetched | Detail drawer slides in with params, permissions, history |\n| 4 | User clicks \"Try It\" | Modal form opens with parameters | Form with `contact_id` (entity picker), `subject`, `body` |\n| 5 | User fills form, clicks \"Execute\" | Gateway → Hermes → act → Salesforce | Inline result: \"Email sent successfully\" + message ID |\n| 6 | User clicks \"Copy API Call\" | Clipboard: curl command | Toast: \"Copied to clipboard\" |\n\n---\n\n### 4.6 States\n\n#### Empty States\n\n| State | Visual Treatment |\n| ----------------------------- | ----------------------------------------------------------------------------------------- |\n| **No connected tools** | Center: \"Connect your first tool to discover capabilities\" + CTA to Connector Marketplace |\n| **No capabilities in filter** | \"No capabilities match this filter. Try another.\" |\n| **Search no results** | \"No capabilities found for 'X'. Search entities or knowledge instead?\" |\n| **Connector error** | Card: red border + \"Connection error. Retry?\" |\n\n#### Loading States\n\n| Component | Indicator |\n| ---------------- | ------------------------------------- |\n| Gallery | Skeleton cards |\n| Grid | Skeleton cards with shimmer |\n| Detail drawer | Spinner in header + skeleton sections |\n| Try It execution | Inline spinner + \"Executing...\" |\n\n---\n\n### 4.7 Accessibility\n\n| Requirement | Implementation |\n| ----------------- | -------------------------------------------------------------------------------------------------- |\n| **Keyboard** | `Tab` navigates cards. `Enter` opens details. `Esc` closes drawer. Arrow keys scroll gallery. |\n| **Screen reader** | Cards: `role=\"button\"`, `aria-label=\"Capability: [name]. [description]. Press Enter for details.\"` |\n| **Focus** | Focus visible on all cards. Drawer traps focus. Return focus on close. |\n| **Search** | `aria-live=\"polite\"` on grid for filter results. |\n\n---\n\n### 4.8 Responsive Behavior\n\n| Breakpoint | Layout |\n| ----------- | ----------------------------------------------------------------------- |\n| **Desktop** | Full gallery + `4-col` grid. Detail drawer `480px`. |\n| **Tablet** | Gallery scrolls. `2-col` grid. Detail drawer `50vw`. |\n| **Mobile** | Gallery collapses to dropdown. `1-col` grid. Detail drawer full-screen. |\n\n---\n\n## 5. Ingress (UI Entry Points)\n\n### 5.1 Overview\n\nIngress is the **front door** of the platform. It covers every way a user or system enters IntegrateWise: sign-in, connector setup, MCP connections, API keys, webhooks, and team invites. Clean, minimal, and one-click where possible.\n\n**User Journey Position:** Step 1 (CONNECT) — \"One click and Salesforce is here.\"\n\n**Core Principles:**\n\n- One-click auth: minimize friction.\n- Progressive disclosure: don't overwhelm on first visit.\n- Trust signals: security badges, clear data handling, transparent scopes.\n- Self-service: users can connect tools without admin help.\n\n---\n\n### 5.2 Layout / Wireframe Description\n\n#### 5.2.1 Sign-in / Sign-up Page\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ │ │\n│ │ [IntegrateWise Logo] │ │\n│ │ │ │\n│ │ \"One click to make tools and AI │ │\n│ │ work for humans.\" │ │\n│ │ │ │\n│ │ ┌─────────────────────────────────────────────────────────────┐ │ │\n│ │ │ Sign in with Google │ │ │\n│ │ │ [Google icon] Continue with Google │ │ │\n│ │ └─────────────────────────────────────────────────────────────┘ │ │\n│ │ │ │\n│ │ ┌─────────────────────────────────────────────────────────────┐ │ │\n│ │ │ Sign in with GitHub │ │ │\n│ │ │ [GitHub icon] Continue with GitHub │ │ │\n│ │ └─────────────────────────────────────────────────────────────┘ │ │\n│ │ │ │\n│ │ ──────────── or ──────────── │ │\n│ │ │ │\n│ │ ┌─────────────────────────────────────────────────────────────┐ │ │\n│ │ │ Email address │ │ │\n│ │ │ [email@example.com] │ │ │\n│ │ └─────────────────────────────────────────────────────────────┘ │ │\n│ │ │ │\n│ │ ┌─────────────────────────────────────────────────────────────┐ │ │\n│ │ │ Password │ │ │\n│ │ │ [••••••••] [👁️] │ │ │\n│ │ └─────────────────────────────────────────────────────────────┘ │ │\n│ │ │ │\n│ │ [Sign In] (full-width, primary) │ │\n│ │ │ │\n│ │ [Forgot password?] | [Create account] │ │\n│ │ │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ 🔒 SOC 2 Type II • GDPR Compliant • TLS 1.3 │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n#### 5.2.2 Connector Marketplace\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ TOP BAR: IntegrateWise | [🔍 Search tools] | [👤 User] │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ \"Connect Your Tools\" │\n│ \"Search 200+ integrations and connect in one click.\" │\n│ │\n│ [Filter: All] [CRM] [Communication] [Finance] [Dev] [Storage] [AI] │\n│ │\n│ ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐ │\n│ │ [Salesforce logo] │ │ [HubSpot logo] │ │ [Slack logo] │ │\n│ │ Salesforce │ │ HubSpot │ │ Slack │ │\n│ │ CRM │ │ CRM │ │ Communication │ │\n│ │ │ │ │ │ │ │\n│ │ [Connect] │ │ [Connect] │ │ [Connect] │ │\n│ │ Popular │ │ Popular │ │ Connected ✓ │ │\n│ └────────────────────┘ └────────────────────┘ └────────────────────┘ │\n│ │\n│ ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐ │\n│ │ [Stripe logo] │ │ [GitHub logo] │ │ [Linear logo] │ │\n│ │ Stripe │ │ GitHub │ │ Linear │ │\n│ │ Finance │ │ Dev │ │ Dev │ │\n│ │ │ │ │ │ │ │\n│ │ [Connect] │ │ [Connect] │ │ [Connect] │ │\n│ │ │ │ │ │ │ │\n│ └────────────────────┘ └────────────────────┘ └────────────────────┘ │\n│ │\n│ [Show more tools →] │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n#### 5.2.3 MCP Connection Screen\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ \"Connect Your AI Assistant\" │\n│ │\n│ IntegrateWise acts as an MCP server. Your AI assistant (Claude, ChatGPT) │\n│ can discover and invoke all your connected tools through the Bridge. │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ MCP Endpoint │ │\n│ │ https://mcp.integratewise.ai/v1/mcp │ │\n│ │ [Copy] │ │\n│ │ │ │\n│ │ Authentication: Bearer │ │\n│ │ [Copy token] [Regenerate] │ │\n│ │ │ │\n│ │ ┌─────────────────────────────────────────────────────────────┐ │ │\n│ │ │ Setup Instructions │ │ │\n│ │ │ 1. Open Claude Desktop / ChatGPT │ │ │\n│ │ │ 2. Add MCP server: paste endpoint │ │ │\n│ │ │ 3. Authenticate with your JWT │ │ │\n│ │ │ 4. The AI will discover your capabilities automatically │ │ │\n│ │ └─────────────────────────────────────────────────────────────┘ │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ [Test Connection] [View Logs] │\n│ │\n│ Connection Status: 🟢 Connected | Last ping: 2s ago | Tools: 42 │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n#### 5.2.4 API Key Management\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ \"API Keys\" | [+ Create New Key] │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ Name │ Key Preview │ Scopes │ Created │ Actions│ │\n│ ├─────────────────────────────────────────────────────────────────────┤ │\n│ │ Production SDK │ iwak_••••••x3y │ read,write│ Jan 15 │ [•••] │ │\n│ │ CI/CD Pipeline │ iwak_••••••a9b │ read │ Mar 2 │ [•••] │ │\n│ │ Zapier Integration│ iwak_••••••k7m │ webhook │ Apr 10 │ [•••] │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ [Create Key Modal] │\n│ Name: [Production Webhook] │\n│ Scopes: [☑ read] [☑ write] [☑ webhook] [☐ admin] │\n│ Expiry: [90 days ▼] │\n│ [Create] [Cancel] │\n│ │\n│ ⚠️ Keys are shown only once. Copy and store securely. │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n#### 5.2.5 Webhook Dashboard\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ \"Webhook Dashboard\" | [+ Create Webhook] | [View Docs] │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ Endpoint: https://api.integratewise.ai/api/v1/webhooks/... │ │\n│ │ [Copy] [Regenerate Secret] [Test] │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ Recent Deliveries (last 24h) │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ Time │ Source │ Event │ Status │ Payload │ │\n│ ├─────────────────────────────────────────────────────────────────────┤ │\n│ │ 14:32 │ Salesforce│ opp.updated │ ✅ 200 │ [View] │ │\n│ │ 14:15 │ Stripe │ invoice.paid │ ✅ 200 │ [View] │ │\n│ │ 13:58 │ Slack │ message │ ⚠️ 429 │ [View] [Retry]│ │\n│ │ 12:20 │ HubSpot │ contact.created│ ❌ 500 │ [View] [Retry]│ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ [View all history →] │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n#### 5.2.6 Invite Team Members\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ \"Invite Team Members\" │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ Email addresses (one per line, or comma-separated) │ │\n│ │ [alice@acme.com ] │ │\n│ │ [bob@acme.com ] │ │\n│ │ [carol@acme.com ] │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ Role: [Member ▼] (Member | Admin | Viewer | TAM) │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ Message (optional) │ │\n│ │ [Join our IntegrateWise workspace to access unified tools...] │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ [☑] Send welcome email with getting started guide │\n│ │\n│ [Send Invites] (3 invites) │\n│ │\n│ Pending Invites │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ Email │ Role │ Sent │ Status │ Action │ │\n│ ├─────────────────────────────────────────────────────────────────────┤ │\n│ │ dave@acme.com │ Admin │ 2h ago │ Pending │ [Resend] │ │\n│ │ eve@acme.com │ Viewer │ 1d ago │ Expired │ [Resend] │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n### 5.3 Key UI Components\n\n#### 5.3.1 OAuth Sign-in Button\n\n```typescript\ninterface OAuthButtonProps {\n provider: \"google\" | \"github\" | \"microsoft\" | \"okta\";\n onClick: () => void;\n isLoading: boolean;\n}\n```\n\n**Visual Spec:**\n\n- Full-width: `w-full h-12 rounded-lg border flex items-center justify-center gap-3`\n- Google: `bg-white border-neutral-200 text-neutral-700 hover:bg-neutral-50`\n- GitHub: `bg-neutral-900 text-white hover:bg-neutral-800`\n- Loading: spinner replaces icon, `disabled` state\n- Focus: `ring-2 ring-primary-500 ring-offset-2`\n\n#### 5.3.2 Connector Card (Marketplace)\n\n```typescript\ninterface ConnectorCardProps {\n provider: string;\n displayName: string;\n category: string;\n icon: string;\n description: string;\n isPopular: boolean;\n isConnected: boolean;\n onConnect: () => void;\n}\n```\n\n**Visual Spec:**\n\n- `bg-white rounded-xl border border-neutral-200 p-5 hover:shadow-md transition-all`\n- Top: icon (`48px`) + `isPopular` ? ` Popular` badge (`bg-primary-100 text-primary-700 text-xs rounded-full px-2`) : null\n- Name: `text-base font-semibold mt-3`\n- Category: `text-xs text-neutral-500 uppercase tracking-wide`\n- Description: `text-sm text-neutral-600 mt-2 line-clamp-2`\n- Action:\n - Connected: `bg-success-50 text-success-700 border border-success-200 rounded-lg px-4 py-2 text-sm flex items-center gap-2` + check icon + \"Connected\"\n - Not connected: `bg-primary-600 text-white rounded-lg px-4 py-2 text-sm hover:bg-primary-700` + \"Connect\"\n- Clicking connected: opens connector settings modal (sync status, mappings, disconnect)\n\n#### 5.3.3 MCP Endpoint Card\n\n```typescript\ninterface McEndpointCardProps {\n endpoint: string;\n token: string;\n connectionStatus: \"connected\" | \"disconnected\" | \"testing\";\n toolCount: number;\n lastPingAt?: Date;\n onCopy: () => void;\n onRegenerate: () => void;\n onTest: () => void;\n}\n```\n\n**Visual Spec:**\n\n- `bg-neutral-50 rounded-xl border border-neutral-200 p-6`\n- Endpoint: `font-mono text-sm bg-white rounded-lg border border-neutral-200 px-3 py-2 flex justify-between items-center`\n - Copy button: `text-neutral-400 hover:text-neutral-600`\n- Token: same style, but masked (`iwak_••••••x3y`) with \"Show\" toggle\n- Status row: `flex items-center gap-2 mt-4`\n - Dot: `8px circle` + `text-sm`\n - Connected: green dot + \"Connected\"\n - Tools count: `text-xs text-neutral-500`\n - Last ping: `text-xs text-neutral-400`\n- Actions: `flex gap-3 mt-4`\n - `Test Connection` (secondary), `Regenerate Token` (danger, confirm modal)\n\n#### 5.3.4 API Key Table Row\n\n```typescript\ninterface ApiKeyRowProps {\n key: {\n id: string;\n name: string;\n preview: string; // last 4 chars\n scopes: string[];\n createdAt: Date;\n lastUsedAt?: Date;\n };\n onRevoke: () => void;\n onEdit: () => void;\n}\n```\n\n**Visual Spec:**\n\n- Table row: `border-b border-neutral-100 hover:bg-neutral-50`\n- Columns: Name (`text-sm font-medium`), Preview (`font-mono text-xs`), Scopes (`flex gap-1`), Created (`text-xs text-neutral-500`), Actions (`...` dropdown)\n- Scopes: each is `bg-neutral-100 rounded-full px-2 py-0.5 text-[10px]`\n- Actions dropdown: `Edit`, `Revoke` (with confirm)\n- Revoke: `bg-danger-50 text-danger` on hover, confirm modal with \"This will break integrations.\"\n\n#### 5.3.5 Webhook Delivery Row\n\n```typescript\ninterface WebhookDeliveryRowProps {\n delivery: {\n id: string;\n receivedAt: Date;\n provider: string;\n eventType: string;\n status: \"success\" | \"retry\" | \"failed\";\n statusCode: number;\n payload: unknown;\n };\n onViewPayload: () => void;\n onRetry: () => void;\n}\n```\n\n**Visual Spec:**\n\n- Table row: `border-b border-neutral-100`\n- Status: icon + `text-xs`\n - Success: `✅ text-success`\n - Retry: `⚠️ text-warning`\n - Failed: `❌ text-danger`\n- Time: `text-xs text-neutral-500`\n- Provider: `text-sm`\n- Event: `font-mono text-xs text-neutral-600`\n- Status code: `text-xs` + colored badge (2xx green, 4xx warning, 5xx danger)\n- Actions: `View` (opens payload drawer) + `Retry` (if failed)\n\n---\n\n### 5.4 Data Flow\n\n```\n┌──────────────────────────────────────────────────────────────────────────────┐\n│ DATA FLOW: Ingress (UI Entry Points) │\n├──────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ SIGN-IN / SIGN-UP │\n│ ────────────────── │\n│ 1. OAuth: User clicks provider → OAuth 2.0 flow → Gateway → tenants service │\n│ → JWT minted → session created → redirect to workbench │\n│ 2. Email/Password: POST /auth/login → Gateway → tenants → JWT │\n│ │\n│ CONNECTOR MARKETPLACE │\n│ ─────────────────────── │\n│ 1. Discovery → GET /api/v1/discovery → connectors list + available providers │\n│ 2. Connect → POST /api/v1/connect → OAuth flow → credential wall → sync │\n│ │\n│ MCP CONNECTION │\n│ ──────────────── │\n│ 1. GET /mcp/sessions → Gateway creates SSE session │\n│ 2. Token: JWT from current session (no separate API key needed) │\n│ 3. Test: POST /mcp/tools → verify catalog assembly │\n│ │\n│ API KEY MANAGEMENT │\n│ ──────────────────── │\n│ 1. CRUD: admin service → D1 api_keys table → KV cache invalidate │\n│ 2. Usage: gateway checks KV whitelist on every API key request │\n│ │\n│ WEBHOOK DASHBOARD │\n│ ───────────────── │\n│ 1. Read: webhook-ingress → D1 webhook_deliveries table │\n│ 2. Retry: POST /webhooks/retry → re-enqueue to webhook-ingress │\n│ │\n│ INVITE TEAM │\n│ ──────────── │\n│ 1. POST /iam/invite → iam service → email send → D1 invitation record │\n│ 2. Accept: link → gateway → tenants → user created → role assigned │\n│ │\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n### 5.5 User Interactions\n\n#### Flow: New User Signs Up and Connects Salesforce\n\n| Step | Action | System Response | UI Change |\n| ---- | ---------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------- |\n| 1 | User visits app, clicks \"Continue with Google\" | OAuth 2.0 flow initiated | Redirect to Google auth |\n| 2 | User grants consent | Redirect to IntegrateWise with code | Gateway exchanges code, JWT minted, workbench loads |\n| 3 | Onboarding: \"Connect your first tool\" CTA | Discovery shows no connectors | Marketplace opens with popular tools |\n| 4 | User clicks \"Connect\" on Salesforce card | OAuth flow to Salesforce | Salesforce auth window opens |\n| 5 | User grants Salesforce scopes | Redirect back, credential wall stores token, sync enqueued | Card updates: \"Connected ✓\" + \"Syncing...\" badge |\n| 6 | Sync completes (SSE notification) | Data flows through normalizer to Spine | Toast: \"Salesforce connected. 1,247 records synced.\" |\n| 7 | User clicks \"Go to Workbench\" | Workbench loads with Sales projection | Entity explorer shows accounts, contacts, deals |\n\n---\n\n### 5.6 States\n\n#### Empty States\n\n| State | Visual Treatment |\n| ---------------------- | --------------------------------------------------------------------- |\n| **No connectors** | Marketplace: \"Connect your first tool to get started\" + popular tools |\n| **No API keys** | \"No API keys yet. Create one for external integrations.\" |\n| **No webhooks** | \"No webhook deliveries yet. Connect a tool to receive events.\" |\n| **No pending invites** | \"No pending invitations. Invite your team to collaborate.\" |\n\n#### Error States\n\n| Error | Visual Treatment | Recovery |\n| --------------------------- | ---------------------------------------------------------------- | ---------------------------------- |\n| **OAuth failed** | \"Connection failed. [Provider] returned an error.\" + \"Try again\" | Retry OAuth flow |\n| **Invalid scopes** | \"This tool requires additional permissions.\" + scope list | Re-auth with correct scopes |\n| **Webhook secret mismatch** | \"Signature verification failed.\" + regenerate CTA | Regenerate secret, update provider |\n| **Invite expired** | \"This invitation has expired.\" + resend option | Resend invite |\n| **API key revoked** | \"Authentication failed. Key may be revoked.\" | Prompt to create new key |\n\n---\n\n### 5.7 Accessibility\n\n| Requirement | Implementation |\n| --------------- | ------------------------------------------------------------------------------------------ |\n| **Sign-in** | All inputs have `label`. Error messages: `aria-live=\"polite\"`. Focus on first error field. |\n| **Marketplace** | Cards: `role=\"button\"` or `role=\"link\"`. Filter: `aria-label=\"Filter by category\"`. |\n| **MCP screen** | Endpoint/token: `aria-label` on copy buttons. Status announced via `aria-live`. |\n| **Tables** | `scope=\"col\"` on headers. Row actions: `aria-label` per row. |\n| **Keyboard** | `Tab` navigates all fields. `Enter` submits forms. `Esc` closes modals. |\n\n---\n\n### 5.8 Responsive Behavior\n\n| Breakpoint | Behavior |\n| ----------- | -------------------------------------------------------------------------------------- |\n| **Desktop** | Centered auth card (`max-w-[400px]`). Marketplace: `3-col` grid. Tables: full width. |\n| **Tablet** | Auth card: `max-w-[360px]`. Marketplace: `2-col`. Tables: scrollable. |\n| **Mobile** | Auth card: full width with padding. Marketplace: `1-col`. Tables: card view (stacked). |\n\n---\n\n## 6. Audit Logs (Transparency Layer)\n\n### 6.1 Overview\n\nThe Audit Logs interface is the **\"what did the AI do?\" transparency layer**. It gives users and admins full visibility into every action the system took, every proposal it made, every piece of data it accessed, and every governance decision that was applied.\n\n**User Journey Position:** Cross-cutting. Accessible from any screen. Critical for compliance (SOC 2, GDPR) and trust.\n\n**Core Principles:**\n\n- Immutable: every log is append-only. No edits, no deletes.\n- Filterable: users can find what they're looking for in seconds.\n- Exportable: compliance requires exports (CSV, JSON, Parquet).\n- Permission-bound: users see only what they're allowed to see.\n\n---\n\n### 6.2 Layout / Wireframe Description\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ TOP BAR (64px) │\n│ ┌────┐ ┌─────────────────┐ ┌────────────────────────────────────────────┐ │\n│ │ IW │ │ Audit Logs │ │ [Export] [Filter ▼] [Date Range] [👤] │ │\n│ └────┘ └─────────────────┘ └────────────────────────────────────────────┘ │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌──────────────────────────────────────────────────────────────────────┐ │\n│ │ FILTER BAR (56px) │ │\n│ │ [Actor: All ▼] [Action: All ▼] [Via: All ▼] [Entity: Search...] │ │\n│ │ [Confidence: All ▼] [Status: All ▼] │ │\n│ └──────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌──────────────────────────────────────────────────────────────────────┐ │\n│ │ VIEW TOGGLE: [Timeline] [Table] [Governance] [Data Access] │ │\n│ └──────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌──────────────────────────────────────────────────────────────────────┐ │\n│ │ TIMELINE VIEW (default) │ │\n│ │ │ │\n│ │ Jun 3, 2026 │ │\n│ │ ───────────────────────────────────────────────────────────────────── │ │\n│ │ ┌──────────┐ │ │\n│ │ │ 14:32:15 │ ┌────────────────────────────────────────────────────┐ │ │\n│ │ │ │ │ 🤖 twin │ PROPOSED │ │ │\n│ │ │ ● │ │ │ \"Update renewal date for Acme Corp\" │ │ │\n│ │ │ │ │ Confidence: 0.78 │ │ │\n│ │ │ │ │ [View Details] [Go to My Desk] │ │ │\n│ │ └──────────┘ └────────────────────────────────────────────────────┘ │ │\n│ │ │ │\n│ │ ┌──────────┐ │ │\n│ │ │ 14:28:03 │ ┌────────────────────────────────────────────────────┐ │ │\n│ │ │ │ │ 👤 alice@acme │ APPROVED │ │ │\n│ │ │ ● │ │ │ Proposal #prop_001 approved │ │ │\n│ │ │ │ │ │ [View Details] │ │ │\n│ │ └──────────┘ └────────────────────────────────────────────────────┘ │ │\n│ │ │ │\n│ │ ┌──────────┐ │ │\n│ │ │ 14:27:55 │ ┌────────────────────────────────────────────────────┐ │ │\n│ │ │ │ │ 🔧 system │ SYNC │ │ │\n│ │ │ ● │ │ │ Salesforce incremental sync: 47 │ │ │\n│ │ │ │ │ │ records processed │ │ │\n│ │ │ │ │ │ [View Records] │ │ │\n│ │ └──────────┘ └────────────────────────────────────────────────────┘ │ │\n│ │ │ │\n│ │ Jun 2, 2026 │ │\n│ │ ───────────────────────────────────────────────────────────────────── │ │\n│ │ ┌──────────┐ │ │\n│ │ │ 09:15:22 │ ┌────────────────────────────────────────────────────┐ │ │\n│ │ │ │ │ 👤 bob@acme │ EXECUTED │ │ │\n│ │ │ ● │ │ │ salesforce.opportunity.update │ │ │\n│ │ │ │ │ │ Entity: Acme Corp (ssoc_001) │ │ │\n│ │ │ │ │ │ [View Details] [View Entity] │ │ │\n│ │ └──────────┘ └────────────────────────────────────────────────────┘ │ │\n│ │ │ │\n│ └──────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ [DETAIL DRAWER (from right, 520px)] │\n│ ┌────────────────────────────────────────────────────────────────────┐ │\n│ │ AUDIT EVENT DETAIL │ │\n│ │ │ │\n│ │ Event ID: aud_01H... │ │\n│ │ Timestamp: 2026-06-03 14:32:15 UTC │ │\n│ │ Actor: twin (agent: twin-orchestrator) │ │\n│ │ Action: PROPOSED │ │\n│ │ Via: twin (SSE) │ │\n│ │ │ │\n│ │ ┌────────────────────────────────────────────────────────────┐ │ │\n│ │ │ CAPABILITY INVOKED │ │ │\n│ │ │ twin.propose │ │ │\n│ │ │ Input: { entityId: \"ssoc_001\", ... } │ │ │\n│ │ └────────────────────────────────────────────────────────────┘ │ │\n│ │ │ │\n│ │ ┌────────────────────────────────────────────────────────────┐ │ │\n│ │ │ GOVERNANCE DECISION │ │ │\n│ │ │ Confidence: 0.78 │ │ │\n│ │ │ Decision: QUEUED (0.70–0.85 requires approval) │ │ │\n│ │ │ Rule: default_0.70_0.85 │ │ │\n│ │ └────────────────────────────────────────────────────────────┘ │ │\n│ │ │ │\n│ │ ┌────────────────────────────────────────────────────────────┐ │ │\n│ │ │ FULL PAYLOAD (SHA-256 verified) │ │ │\n│ │ │ { ... } │ │ │\n│ │ └────────────────────────────────────────────────────────────┘ │ │\n│ │ │ │\n│ │ [Export This Event] [View in My Desk] │ │\n│ └────────────────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n### 6.3 Key UI Components\n\n#### 6.3.1 Filter Bar\n\n```typescript\ninterface AuditFilterBarProps {\n filters: {\n actor?: string[];\n action?: string[];\n via?: string[];\n entityId?: string;\n confidenceRange?: [number, number];\n status?: string[];\n dateRange?: { start: Date; end: Date };\n };\n onFilterChange: (filters: AuditFilterBarProps[\"filters\"]) => void;\n availableFilters: { actors: string[]; actions: string[]; vias: string[]; statuses: string[] };\n}\n```\n\n**Visual Spec:**\n\n- Horizontal row, `h-[56px]`, `flex items-center gap-3 px-4`\n- Each filter: `rounded-lg bg-white border border-neutral-200 px-3 py-1.5 text-sm flex items-center gap-2`\n- Dropdowns: multi-select checkboxes\n- Entity search: `input` with `entity` icon, autocomplete from Spine\n- Date range: `DateRangePicker` (two inputs or calendar widget)\n- Clear all: `text-sm text-primary-600 hover:underline` when filters active\n\n#### 6.3.2 Timeline View\n\n```typescript\ninterface TimelineViewProps {\n events: AuditEvent[];\n onSelect: (eventId: string) => void;\n onLoadMore: () => void;\n hasMore: boolean;\n}\n\ninterface AuditEvent {\n id: string;\n timestamp: Date;\n actor: string; // 'user:', 'twin', 'system', 'agent:'\n action: string;\n via: string;\n entityId?: string;\n entityName?: string;\n confidence?: number;\n governanceDecision?: string;\n summary: string;\n payloadHash: string;\n}\n```\n\n**Visual Spec:**\n\n- Vertical timeline with `border-l-2 border-neutral-200` left gutter\n- Date headers: `text-xs font-semibold text-neutral-500 uppercase tracking-wide my-4`\n- Each event:\n - Time: `text-xs text-neutral-400 font-mono w-[72px] text-right pr-4`\n - Dot: `absolute -left-[5px] w-[10px] h-[10px] rounded-full` — color by action type\n - `proposed`: `bg-primary-500`\n - `approved/rejected`: `bg-success` or `bg-danger`\n - `executed`: `bg-neutral-700`\n - `sync`: `bg-info-500`\n - `error`: `bg-danger-500`\n - Card: `bg-white rounded-lg border border-neutral-200 p-4 hover:shadow-sm transition-shadow`\n - Header: `flex items-center gap-2`\n - Actor badge: `rounded-full px-2 py-0.5 text-[10px] font-bold uppercase`\n - `user`: `bg-neutral-100 text-neutral-700`\n - `twin`: `bg-primary-100 text-primary-700`\n - `system`: `bg-neutral-100 text-neutral-500`\n - Action: `text-sm font-medium`\n - Via: `text-xs text-neutral-400` in parentheses\n - Body: `text-sm text-neutral-600 mt-1` summary\n - Footer: `flex gap-3 mt-2 text-xs text-primary-600`\n - `View Details` + `Go to Entity` (if entityId) + `View in My Desk` (if proposal)\n- Infinite scroll: `IntersectionObserver` at bottom, spinner while loading\n\n#### 6.3.3 Governance Decision Badge\n\n```typescript\ninterface GovernanceBadgeProps {\n decision:\n | \"auto_approved\"\n | \"queued\"\n | \"discarded\"\n | \"rule_blocked\"\n | \"approved\"\n | \"rejected\"\n | \"modified\"\n | \"expired\";\n confidence?: number;\n}\n```\n\n**Visual Spec:**\n\n- Inline badge within event card\n- `rounded-full px-2 py-0.5 text-[10px] font-bold uppercase`\n- Colors:\n - `auto_approved`: `bg-success text-white`\n - `queued`: `bg-warning text-white`\n - `discarded`: `bg-neutral-200 text-neutral-600`\n - `rule_blocked`: `bg-danger text-white`\n - `approved`: `bg-success text-white`\n - `rejected`: `bg-danger text-white`\n - `modified`: `bg-info text-white`\n - `expired`: `bg-neutral-200 text-neutral-500`\n\n#### 6.3.4 Audit Detail Drawer\n\n```typescript\ninterface AuditDetailDrawerProps {\n event: AuditEvent;\n onClose: () => void;\n onExport: () => void;\n onNavigateToEntity: () => void;\n onNavigateToProposal: () => void;\n}\n```\n\n**Visual Spec:**\n\n- Drawer: `w-[520px]`, slides from right\n- Sections with `border-b border-neutral-200 pb-4 mb-4`:\n - Metadata: key-value grid, `grid-cols-[120px_1fr]`, `text-sm`\n - Capability Invoked: `bg-neutral-50 rounded-lg p-3`, capability URI + input JSON\n - Governance Decision: confidence badge + decision + rule name\n - Full Payload: `JSON` formatted, `font-mono text-xs bg-neutral-900 text-neutral-100 rounded-lg p-3 overflow-auto max-h-[300px]`\n - SHA-256: `font-mono text-xs text-neutral-400` with \"Verified\" checkmark\n- Footer: `flex gap-3 sticky bottom-0 bg-white p-4 border-t`\n - `Export This Event` (JSON), `View in My Desk` (if proposal)\n\n#### 6.3.5 Export Modal\n\n```typescript\ninterface ExportModalProps {\n isOpen: boolean;\n format: \"csv\" | \"json\" | \"parquet\";\n dateRange: { start: Date; end: Date };\n filters: AuditFilterBarProps[\"filters\"];\n onExport: () => void;\n onClose: () => void;\n}\n```\n\n**Visual Spec:**\n\n- Modal: `max-w-[480px]`, centered\n- Format: `flex gap-3` — radio cards with icon + label\n- Date range: pre-filled from current view, editable\n- Filters: summary of active filters\n- Estimate: \"~1,247 events (2.3 MB)\"\n- Action: `Export` (primary), `Cancel` (secondary)\n- Progress: inline spinner + \"Generating...\" then download trigger\n\n---\n\n### 6.4 Data Flow\n\n```\n┌──────────────────────────────────────────────────────────────────────────────┐\n│ DATA FLOW: Audit Logs │\n├──────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ INBOUND │\n│ ─────── │\n│ 1. Audit events → D1 spine_audit_log + governance_audit_log (append-only) │\n│ 2. Query: govern service (for governance) + gateway audit endpoint │\n│ 3. Aggregation: telemetry hub (for stats, usage) │\n│ │\n│ OUTBOUND │\n│ ──────── │\n│ 1. Filtered query → D1 with WHERE tenant_id + indexed filters │\n│ 2. Export → CSV/JSON/Parquet generation → R2 signed URL → download │\n│ 3. Navigation → workbench (entity) or My Desk (proposal) │\n│ │\n│ PERMISSIONS │\n│ ─────────── │\n│ • User view: own actions + twin proposals + entity access for own entities │\n│ • Admin view: all actions in tenant (cross-user) │\n│ • System events: admin + owner only │\n│ │\n│ SERVICES │\n│ ──────── │\n│ • govern (governance audit log) │\n│ • gateway (audit endpoint, export) │\n│ • l2 (cached queries) │\n│ • telemetry (aggregations) │\n│ │\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n### 6.5 User Interactions\n\n#### Flow: Admin Investigates a Twin Proposal\n\n| Step | Action | System Response | UI Change |\n| ---- | ------------------------------------------------- | ------------------------------------ | --------------------------------------------- |\n| 1 | Admin opens Audit Logs, filters by Actor = \"twin\" | Query returns twin events | Timeline shows only twin-generated events |\n| 2 | Admin clicks on \"PROPOSED\" event from Jun 3 | Detail drawer opens | Full payload, governance decision, confidence |\n| 3 | Admin clicks \"View in My Desk\" | Navigates to My Desk (governance) | Proposal shown with approve/reject options |\n| 4 | Admin clicks \"View Entity\" | Workbench loads with entity selected | Entity360 shows context at time of proposal |\n| 5 | Admin clicks \"Export This Event\" | JSON generated, download triggered | File: `audit_event_aud_01H.json` |\n\n---\n\n### 6.6 States\n\n#### Empty States\n\n| State | Visual Treatment |\n| -------------------------- | ------------------------------------------------------------------------------ |\n| **No events** | \"No audit events yet. Actions will appear here as they occur.\" |\n| **Filter returns nothing** | \"No events match these filters. Try broadening your search.\" + \"Clear filters\" |\n| **No permission** | \"You don't have access to audit logs. Contact your admin.\" |\n\n#### Loading States\n\n| Component | Indicator |\n| ------------- | ----------------------------------------- |\n| Timeline | Skeleton events with timeline dots |\n| Detail drawer | Spinner + skeleton sections |\n| Export | Modal with progress bar + \"Generating...\" |\n| Filter counts | `...` in dropdown badges while loading |\n\n---\n\n### 6.7 Accessibility\n\n| Requirement | Implementation |\n| ------------ | ----------------------------------------------------------------------------- |\n| **Timeline** | `role=\"list\"`. Each event: `role=\"listitem\"`. Date headers: `role=\"heading\"`. |\n| **Filters** | `aria-label` on each dropdown. Multi-select: `aria-expanded`. |\n| **Drawer** | Focus trap. `Esc` closes. Return focus to trigger. |\n| **Export** | Progress announced via `aria-live=\"polite\"`. Download link auto-focused. |\n| **Color** | Timeline dots use shape + position, not just color. Badges have text labels. |\n\n---\n\n### 6.8 Responsive Behavior\n\n| Breakpoint | Behavior |\n| ----------- | --------------------------------------------------------------------------------------- |\n| **Desktop** | Full timeline + `520px` detail drawer. Filter bar visible. |\n| **Tablet** | Timeline + `50vw` drawer. Filters in collapsible row. |\n| **Mobile** | Table view default (more compact). Timeline becomes vertical cards. Drawer full-screen. |\n\n---\n\n## 7. Browser Automation\n\n### 7.1 Overview\n\nBrowser Automation is the **workflow studio for browser-based tasks**. Unlike API-only capabilities, this runs actual browser automation: clicking, typing, scraping, and navigating websites. Users can record workflows by performing actions, then replay them in headless browsers.\n\n**User Journey Position:** Operations (Ops) projection primarily. Used by power users, admins, and developers.\n\n**Core Principles:**\n\n- Record by doing: no code required to start.\n- Visual workflow builder: drag, drop, and connect steps.\n- Safety first: human-in-the-loop for sensitive actions, screenshots for every step.\n- Reusable: workflows become capabilities in the Capability Fabric.\n\n---\n\n### 7.2 Layout / Wireframe Description\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ TOP BAR (64px) │\n│ ┌────┐ ┌──────────────────────────┐ ┌────────────────────────────────────┐ │\n│ │ IW │ │ Browser Automation Studio│ │ [New Workflow] [Import] [👤] │ │\n│ └────┘ └──────────────────────────┘ └────────────────────────────────────┘ │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌──────────┐ ┌────────────────────────────────────────┐ ┌────────────┐ │\n│ │ WORKFLOW │ │ WORKFLOW CANVAS │ │ PROPERTIES│ │\n│ │ LIBRARY │ │ (Visual Builder) │ │ PANEL │ │\n│ │ (240px) │ │ │ │ (280px) │ │\n│ │ │ │ ┌────┐ ┌────┐ ┌────┐ │ │ │ │\n│ │ Folders │ │ │Visit│────▶│Fill│────▶│Click│────▶ │ │ Selected: │ │\n│ │ ┌──────┐ │ │ │URL │ │Form│ │Btn │ │ │ Click │ │\n│ │ │Sales │ │ │ └────┘ └────┘ └────┘ │ │ \"Submit\" │ │\n│ │ │Flows │ │ │ │ │ │ │ │ │ │\n│ │ └──────┘ │ │ ▼ ▼ ▼ │ │ Selector: │ │\n│ │ ┌──────┐ │ │ [Screenshot] [Wait] [Screenshot] │ │ #submit │ │\n│ │ │CS │ │ │ │ │ button │ │\n│ │ │Flows │ │ │ ┌────────────────────────────────┐ │ │ │ │\n│ │ └──────┘ │ │ │ RECORDING INDICATOR (optional) │ │ │ Wait: │ │\n│ │ │ │ │ 🔴 Recording... [Stop] [Pause] │ │ │ 500ms │ │\n│ │ ┌──────┐ │ │ └────────────────────────────────┘ │ │ │ │\n│ │ │+[New]│ │ │ │ │ [Screenshot│ │\n│ │ └──────┘ │ │ ┌────────────────────────────────┐ │ │ on fail] │ │\n│ │ │ │ │ PREVIEW / HEADLESS BROWSER │ │ │ [☑] │ │\n│ │ │ │ │ (iframe or screenshot stream) │ │ │ │ │\n│ │ │ │ │ │ │ │ On Error: │ │\n│ │ │ │ │ [Screenshot of current state] │ │ │ [Stop] │ │\n│ │ │ │ │ │ │ │ [Retry 3x]│ │\n│ │ │ │ │ │ │ │ [Continue]│ │\n│ │ │ │ └────────────────────────────────┘ │ │ │ │\n│ └──────────┘ └────────────────────────────────────────┘ └────────────┘ │\n│ │\n│ ┌──────────────────────────────────────────────────────────────────────┐ │\n│ │ BOTTOM BAR: Triggers | Schedule | Safety | Logs │ │\n│ │ [Run Now] [Schedule: Daily 9am ▼] [HITL: ☑] [Domain: *.salesforce.com]│ │\n│ └──────────────────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n### 7.3 Key UI Components\n\n#### 7.3.1 Workflow Library (Left Sidebar)\n\n```typescript\ninterface WorkflowLibraryProps {\n folders: WorkflowFolder[];\n onSelect: (workflowId: string) => void;\n onCreate: () => void;\n onImport: () => void;\n}\n\ninterface WorkflowFolder {\n name: string;\n workflows: {\n id: string;\n name: string;\n lastRunAt?: Date;\n status?: \"success\" | \"failed\" | \"never\";\n }[];\n}\n```\n\n**Visual Spec:**\n\n- Width: `240px`, collapsible to `64px`\n- Background: `bg-slate-50 border-r border-neutral-200`\n- Folders: collapsible, `text-sm font-semibold uppercase text-neutral-500 px-3 py-2`\n- Each workflow: `flex row gap-2 px-3 py-2 rounded-lg hover:bg-neutral-100 cursor-pointer`\n - Name: `text-sm truncate`\n - Status dot: `8px circle` — `success` green, `failed` red, `never` gray\n- \"+ New\" button: `primary` at bottom, sticky\n\n#### 7.3.2 Workflow Canvas (Visual Builder)\n\n```typescript\ninterface WorkflowCanvasProps {\n nodes: WorkflowNode[];\n edges: WorkflowEdge[];\n onNodeAdd: (type: string, position: { x: number; y: number }) => void;\n onNodeConnect: (from: string, to: string) => void;\n onNodeSelect: (nodeId: string) => void;\n onNodeDelete: (nodeId: string) => void;\n isRecording: boolean;\n}\n\ninterface WorkflowNode {\n id: string;\n type: \"visit\" | \"click\" | \"type\" | \"wait\" | \"screenshot\" | \"extract\" | \"condition\" | \"loop\";\n position: { x: number; y: number };\n data: Record;\n}\n\ninterface WorkflowEdge {\n id: string;\n from: string;\n to: string;\n label?: string; // \"success\", \"fail\", \"always\"\n}\n```\n\n**Visual Spec:**\n\n- Background: `bg-white` with `dot-grid` pattern (subtle `bg-neutral-50` dots, `16px` spacing)\n- Drag-and-drop canvas: `@xyflow/react` or similar\n- Nodes: `rounded-lg bg-white border-2 shadow-sm min-w-[140px] p-3`\n - Header: icon + type name (`text-xs font-bold uppercase`) + color by type\n - `visit`: `border-blue-400`\n - `click`: `border-green-400`\n - `type`: `border-purple-400`\n - `wait`: `border-yellow-400`\n - `screenshot`: `border-gray-400`\n - `extract`: `border-orange-400`\n - `condition`: `border-pink-400`\n - Body: `text-xs text-neutral-600 mt-1` — e.g., \"https://...\", \"#submit-btn\"\n - Selected: `ring-2 ring-primary-500`, `border-primary-400`\n- Edges: `stroke-neutral-300 stroke-2`, arrowheads. Labels: `bg-white text-[10px]`\n- Recording indicator: `fixed top-1/2 left-1/2 transform -translate-x-1/2 -translate-y-1/2 bg-danger text-white rounded-lg px-4 py-2 shadow-lg flex items-center gap-2 z-50`\n - `🔴 Recording...` + `Stop` button\n\n#### 7.3.3 Properties Panel (Right Sidebar)\n\n```typescript\ninterface PropertiesPanelProps {\n selectedNode: WorkflowNode | null;\n onUpdate: (nodeId: string, data: Record) => void;\n}\n```\n\n**Visual Spec:**\n\n- Width: `280px`, `bg-slate-50 border-l border-neutral-200`\n- Empty: \"Select a node to edit properties\"\n- Node selected:\n - Header: node type icon + name + delete button (`🗑️`)\n - Form: `label` + `input`/`select`/`textarea` per property\n - Common properties:\n - `selector`: `input` with CSS selector validation\n - `wait`: `number` input (ms)\n - `screenshot on fail`: `checkbox`\n - `on error`: `select` (`stop`, `retry`, `continue`, `branch`)\n - Dynamic properties based on node type\n- Validation: `text-danger text-xs` inline, node border turns red if invalid\n\n#### 7.3.4 Headless Browser Preview\n\n```typescript\ninterface BrowserPreviewProps {\n screenshotUrl?: string;\n isRunning: boolean;\n currentUrl?: string;\n logs: BrowserLog[];\n}\n\ninterface BrowserLog {\n timestamp: Date;\n level: \"info\" | \"warn\" | \"error\";\n message: string;\n step?: number;\n screenshotUrl?: string;\n}\n```\n\n**Visual Spec:**\n\n- Panel: `bg-neutral-900 rounded-lg border border-neutral-700 overflow-hidden`\n- Header: `bg-neutral-800 px-3 py-2 flex items-center gap-2 text-xs text-neutral-300`\n - Mock browser chrome: `● ● ●` (red/yellow/green dots) + URL bar showing current URL\n- Body: `screenshot` or `iframe` of running browser\n - If running: screenshot refreshes every `2s` or on each step\n - If idle: \"Ready to run. Click 'Run Now' to start.\"\n- Step overlay: `absolute` box drawn on screenshot showing selector location (if click/type)\n\n#### 7.3.5 Trigger Configuration Panel\n\n```typescript\ninterface TriggerConfigProps {\n triggers: Trigger[];\n onAdd: (trigger: Trigger) => void;\n onRemove: (triggerId: string) => void;\n}\n\ntype Trigger =\n | { type: \"scheduled\"; cron: string; timezone: string }\n | { type: \"event\"; event: string; condition?: string }\n | { type: \"manual\" }\n | { type: \"ai_proposed\"; confidence: number };\n```\n\n**Visual Spec:**\n\n- Collapsible bottom panel, `h-[200px]` when open\n- Trigger list: `flex gap-3` cards\n - Each trigger: `bg-white rounded-lg border border-neutral-200 p-3 flex-1`\n - Icon by type: `⏰` scheduled, `⚡` event, `👆` manual, `🤖` AI\n - Config: `text-xs text-neutral-600` — e.g., \"Daily at 9:00 AM UTC\"\n - Remove: `×` icon\n- Add trigger: `+` button opens dropdown of trigger types\n\n#### 7.3.6 Safety Controls Panel\n\n```typescript\ninterface SafetyControlsProps {\n settings: {\n humanInTheLoop: boolean;\n rateLimit: number; // requests per minute\n allowedDomains: string[];\n blockedDomains: string[];\n maxExecutionTime: number; // seconds\n screenshotOnEveryStep: boolean;\n };\n onUpdate: (settings: SafetyControlsProps[\"settings\"]) => void;\n}\n```\n\n**Visual Spec:**\n\n- Tab or section within bottom panel\n- `bg-warning-50 border border-warning-200 rounded-lg p-4`\n- Header: `⚠️` + \"Safety Controls\" + `text-sm font-semibold`\n- Controls:\n - Human-in-the-loop: `toggle` + \"Pause before sensitive actions (form submits, deletes)\"\n - Rate limit: `slider` + `number` input (1–60 req/min)\n - Allowed domains: `tag input` (`flex gap-2 flex-wrap`), each domain is a removable chip\n - Blocked domains: same, but `bg-danger-50 text-danger`\n - Max execution time: `slider` (30s–10min)\n - Screenshot every step: `toggle`\n\n---\n\n### 7.4 Data Flow\n\n```\n┌──────────────────────────────────────────────────────────────────────────────┐\n│ DATA FLOW: Browser Automation │\n├──────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ INBOUND │\n│ ─────── │\n│ 1. Workflow definitions → D1 (workflow_definitions) │\n│ 2. Execution logs → D1 (workflow_executions) + R2 (screenshots) │\n│ 3. Library: D1 query by tenant + folder │\n│ │\n│ OUTBOUND │\n│ ──────── │\n│ 1. Record mode: Browser events → workflow DO → node sequence → D1 save │\n│ 2. Playback: workflow DO → browser automation worker → headless Chrome │\n│ → screenshots → R2 → execution log → D1 │\n│ 3. Trigger: cron DO / event queue → workflow DO enqueue │\n│ │\n│ SERVICES │\n│ ──────── │\n│ • workflow (workflow DO, execution engine) │\n│ • browser-automation (headless Chrome worker) │\n│ • scheduler (cron triggers) │\n│ • l2 (screenshot CDN via R2) │\n│ • govern (HITL for sensitive steps) │\n│ │\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n### 7.5 User Interactions\n\n#### Flow: User Records a Login Workflow\n\n| Step | Action | System Response | UI Change |\n| ---- | ----------------------------------------- | ----------------------------------------------- | ------------------------------------------------------- |\n| 1 | User clicks \"+ New Workflow\" | New workflow created in D1 | Blank canvas with start node |\n| 2 | User clicks \"Record\" button | Browser automation worker opens headless Chrome | Recording indicator appears, preview shows live browser |\n| 3 | User types URL, fills form, clicks submit | Each action captured as node | Nodes appear on canvas: Visit → Type → Type → Click |\n| 4 | User clicks \"Stop Recording\" | Recording ends, workflow saved | Recording indicator disappears. Nodes are editable. |\n| 5 | User clicks \"Run Now\" | Workflow DO executes in headless browser | Preview shows live screenshots. Step-by-step progress. |\n| 6 | Workflow completes | Screenshot saved to R2, log written to D1 | Toast: \"Workflow completed. 5 steps, 12s.\" + \"View log\" |\n| 7 | User clicks \"Schedule\" | Cron trigger created | Bottom panel shows \"Daily at 9am\" trigger card |\n\n---\n\n### 7.6 States\n\n#### Empty States\n\n| State | Visual Treatment |\n| -------------------- | --------------------------------------------------------------------------------------- |\n| **No workflows** | Library: \"No workflows yet. Create one or record your first automation.\" + tutorial CTA |\n| **No node selected** | Properties panel: \"Select a node to edit properties.\" |\n| **Preview idle** | \"Ready to run. Click 'Run Now' to see the browser in action.\" |\n| **No triggers** | \"No triggers set. This workflow can only be run manually.\" |\n\n#### Loading States\n\n| Component | Indicator |\n| --------- | ---------------------------------------------- |\n| Canvas | Skeleton nodes |\n| Recording | Red pulse indicator + \"Recording...\" |\n| Playback | Progress bar across steps + screenshot updates |\n| Preview | Spinner + \"Launching browser...\" |\n\n#### Error States\n\n| Error | Visual Treatment | Recovery |\n| ---------------------- | ----------------------------------------------------------- | ---------------------------------------- |\n| **Selector not found** | Node turns red. Log: \"Element '#submit' not found.\" | Edit selector, re-run. |\n| **Timeout** | Node turns red. Log: \"Timeout after 30s.\" | Increase wait, check URL. |\n| **Domain blocked** | Toast: \"Navigation to example.com blocked by safety rules.\" | Add to allowed domains or edit workflow. |\n| **HITL rejected** | Log: \"Human rejected step 4. Workflow halted.\" | Resume from step or abort. |\n\n---\n\n### 7.7 Accessibility\n\n| Requirement | Implementation |\n| -------------- | -------------------------------------------------------------------------------------------------------------------- |\n| **Canvas** | Nodes: `role=\"button\"`, `aria-label=\"[type] node: [description]\"`. Edges: `aria-label=\"Connection from [A] to [B]\"`. |\n| **Properties** | All inputs have `label`. Error messages: `aria-live=\"polite\"`. |\n| **Recording** | `aria-live=\"assertive\"` announces \"Recording started\" / \"Recording stopped\". |\n| **Preview** | Screenshots: `alt` text describes current step. If iframe, `title` attribute. |\n| **Keyboard** | `Tab` navigates nodes. `Enter` selects. `Delete` removes. `Ctrl+Z` undo. |\n\n---\n\n### 7.8 Responsive Behavior\n\n| Breakpoint | Behavior |\n| ----------- | --------------------------------------------------------------------- |\n| **Desktop** | Full 3-column: Library + Canvas + Properties. Bottom panel visible. |\n| **Tablet** | Library collapsible. Properties as overlay. Bottom panel `h-[160px]`. |\n| **Mobile** | Not supported for editing. Read-only: execution logs, run/pause. |\n\n---\n\n## 8. Workflows\n\n### 8.1 Overview\n\nWorkflows are **user-defined or AI-proposed sequences of actions**. They are the primary automation layer of the platform — from simple \"when X, do Y\" to complex multi-step business processes with branching, retries, and human approval.\n\n**User Journey Position:** Cross-cutting. Used in Sales (follow-up sequences), CS (health check workflows), Operations (sync + reconcile), and Architecture (CI/CD pipelines).\n\n**Core Principles:**\n\n- Visual first, code optional: anyone can build a workflow.\n- AI-assisted: the Twin proposes workflows based on observed patterns.\n- Reusable: templates and marketplace enable sharing.\n- Governed: every step is auditable, approval-gated where needed.\n\n---\n\n### 8.2 Layout / Wireframe Description\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ TOP BAR (64px) │\n│ ┌────┐ ┌──────────────────────────┐ ┌────────────────────────────────────┐ │\n│ │ IW │ │ Workflows │ │ [New Workflow] [Templates] [👤] │ │\n│ └────┘ └──────────────────────────┘ └────────────────────────────────────┘ │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌──────────────────────────────────────────────────────────────────────┐ │\n│ │ VIEW TABS: [My Workflows] [Team] [Marketplace] [AI Proposed] │ │\n│ └──────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌──────────────────────────────────────────────────────────────────────┐ │\n│ │ AI PROPOSED BANNER (if available) │ │\n│ │ ┌────────────────────────────────────────────────────────────────┐ │ │\n│ │ │ 🤖 \"I noticed you manually update deal stages 5× daily. │ │ │\n│ │ │ Want to automate it?\" [Review Proposal] [Dismiss] │ │ │\n│ │ └────────────────────────────────────────────────────────────────┘ │ │\n│ └──────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌──────────────────────────────────────────────────────────────────────┐ │\n│ │ WORKFLOW GRID / LIST │ │\n│ │ │ │\n│ │ ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐ │ │\n│ │ │ [🔁] │ │ [📧] │ │ [🤖] │ │ │\n│ │ │ Deal Stage Sync │ │ Follow-up Sequence │ │ Health Check Bot │ │ │\n│ │ │ │ │ │ │ │ │ │\n│ │ │ Trigger: Event │ │ Trigger: Scheduled │ │ Trigger: AI │ │ │\n│ │ │ Status: ✅ Active │ │ Status: ✅ Active │ │ Status: ⏸️ Paused │ │ │\n│ │ │ Runs: 1,247 │ │ Runs: 84 │ │ Runs: 12 │ │ │\n│ │ │ Last: 2 min ago │ │ Last: 1 hour ago │ │ Last: 3 days ago │ │ │\n│ │ │ │ │ │ │ │ │ │\n│ │ │ [Run] [Edit] [•••] │ │ [Run] [Edit] [•••] │ │ [Run] [Edit] [•••] │ │ │\n│ │ └────────────────────┘ └────────────────────┘ └────────────────────┘ │ │\n│ │ │ │\n│ │ [Workflow Marketplace →] │ │\n│ │ ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐ │ │\n│ │ │ [📊] Revenue Rec │ │ [🔄] Data Cleanup │ │ [📢] Slack Alert │ │ │\n│ │ │ [Install] │ │ [Install] │ │ [Install] │ │ │\n│ │ │ 128 installs │ │ 64 installs │ │ 312 installs │ │ │\n│ │ └────────────────────┘ └────────────────────┘ └────────────────────┘ │ │\n│ └──────────────────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n### 8.3 Key UI Components\n\n#### 8.3.1 Workflow Editor\n\n```typescript\ninterface WorkflowEditorProps {\n workflow: Workflow;\n nodes: WorkflowNode[];\n edges: WorkflowEdge[];\n onSave: (workflow: Workflow) => void;\n onRun: () => void;\n onPublish: () => void;\n isDirty: boolean;\n}\n\ninterface Workflow {\n id: string;\n name: string;\n description: string;\n trigger: Trigger;\n status: \"draft\" | \"active\" | \"paused\" | \"error\";\n isTemplate: boolean;\n owner: string;\n teamAccess: \"private\" | \"team\" | \"organization\";\n createdAt: Date;\n updatedAt: Date;\n}\n```\n\n**Visual Spec:**\n\n- Similar to Browser Automation canvas but with workflow-specific nodes\n- Node types:\n - `trigger`: `rounded-full bg-neutral-900 text-white`, start of workflow\n - `action`: `rounded-lg bg-white border-2 border-blue-400` — capability invoke\n - `condition`: `diamond shape bg-white border-2 border-pink-400` — if/else branch\n - `wait`: `rounded-lg bg-white border-2 border-yellow-400` — delay or wait for event\n - `loop`: `rounded-lg bg-white border-2 border-purple-400` — iterate over list\n - `governance`: `rounded-lg bg-white border-2 border-warning-400` — HITL gate\n - `end`: `rounded-full bg-neutral-200 text-neutral-500` — terminal\n- Toolbar: `fixed top-[80px] left-1/2 transform -translate-x-1/2 bg-white rounded-full shadow-md border px-4 py-2 flex gap-2 z-40`\n - Draggable node types: `Trigger`, `Action`, `Condition`, `Wait`, `Loop`, `Governance`, `End`\n - Each: `icon` + `label` (`text-xs`), `cursor-grab`\n- Save status: `bottom-left`, `text-xs text-neutral-400` — \"Saved\" / \"Unsaved changes\" / \"Saving...\"\n- Run button: `fixed bottom-6 right-6 bg-primary-600 text-white rounded-full w-14 h-14 shadow-lg flex items-center justify-center hover:bg-primary-700 z-50`\n\n#### 8.3.2 AI-Proposed Workflow Banner\n\n```typescript\ninterface AIProposalBannerProps {\n proposal: {\n id: string;\n description: string;\n observedPattern: string;\n confidence: number;\n estimatedImpact: { timeSaved: number; frequency: number };\n };\n onReview: () => void;\n onDismiss: () => void;\n}\n```\n\n**Visual Spec:**\n\n- Full-width banner: `bg-primary-50 border border-primary-200 rounded-xl p-4 mb-6 flex items-center gap-4`\n- Left: `🤖` icon (`40px`, `bg-primary-100 rounded-full p-2`)\n- Center: `text-sm text-primary-900`\n - Line 1: `font-medium` — description\n - Line 2: `text-xs text-primary-600` — \"Based on N observed actions\"\n- Right: `flex gap-2`\n - `Review Proposal`: `bg-primary-600 text-white rounded-lg px-4 py-2 text-sm`\n - `Dismiss`: `text-neutral-400 hover:text-neutral-600 text-sm`\n- Dismiss: collapses with `slide-up + fade`, `200ms`\n\n#### 8.3.3 Workflow Execution Dashboard\n\n```typescript\ninterface ExecutionDashboardProps {\n executions: WorkflowExecution[];\n onViewLog: (executionId: string) => void;\n onRerun: (executionId: string) => void;\n onCancel: (executionId: string) => void;\n}\n\ninterface WorkflowExecution {\n id: string;\n workflowId: string;\n workflowName: string;\n status: \"running\" | \"completed\" | \"failed\" | \"cancelled\" | \"waiting\";\n startedAt: Date;\n completedAt?: Date;\n triggeredBy: \"schedule\" | \"manual\" | \"event\" | \"ai\";\n stepCount: number;\n currentStep?: number;\n errorMessage?: string;\n}\n```\n\n**Visual Spec:**\n\n- Table: `w-full text-sm`\n- Columns: Status (icon + text), Workflow (name + link), Triggered By (badge), Started (time), Duration, Steps (progress), Actions\n- Status icons:\n - `running`: `spinner` + `text-info`\n - `completed`: `check` + `text-success`\n - `failed`: `x` + `text-danger`\n - `cancelled`: `slash` + `text-neutral-400`\n - `waiting`: `pause` + `text-warning`\n- Progress: `w-[100px] h-2 bg-neutral-200 rounded-full overflow-hidden` with `bg-primary-500` fill\n- Actions: `View Log` (drawer), `Rerun` (if completed/failed), `Cancel` (if running)\n\n#### 8.3.4 Workflow Templates Gallery\n\n```typescript\ninterface TemplateGalleryProps {\n templates: WorkflowTemplate[];\n onInstall: (templateId: string) => void;\n onPreview: (templateId: string) => void;\n}\n\ninterface WorkflowTemplate {\n id: string;\n name: string;\n description: string;\n category: string;\n author: string;\n installCount: number;\n isOfficial: boolean;\n previewNodes: WorkflowNode[];\n}\n```\n\n**Visual Spec:**\n\n- Grid: `grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4`\n- Card: `bg-white rounded-xl border border-neutral-200 p-5 hover:shadow-md transition-all`\n- Top: `text-xs text-neutral-400 uppercase` category + `isOfficial` ? `Official` badge : null\n- Name: `text-sm font-semibold`\n- Description: `text-xs text-neutral-600 mt-1 line-clamp-2`\n- Mini preview: `h-[80px] bg-neutral-50 rounded border border-neutral-200 mt-3` — static SVG or canvas of node layout\n- Footer: `flex items-center justify-between mt-3`\n - Left: author avatar + name (`text-xs`)\n - Right: install count (`text-xs text-neutral-400`) + `Install` button (`primary`)\n\n#### 8.3.5 Trigger Configuration Modal\n\n```typescript\ninterface TriggerConfigModalProps {\n trigger: Trigger | null;\n onSave: (trigger: Trigger) => void;\n onClose: () => void;\n}\n```\n\n**Visual Spec:**\n\n- Modal: `max-w-[560px]`\n- Type selector: `flex gap-3` — card radio buttons\n - `Time-based`: `⏰` + \"Run on a schedule\"\n - `Event-based`: `⚡` + \"Run when something happens\"\n - `Manual`: `👆` + \"Run when I click\"\n - `AI-proposed`: `🤖` + \"Let the AI decide when\"\n- Dynamic config based on type:\n - Time: `cron` input + timezone picker + \"Next 3 runs\" preview\n - Event: `select` event type + `condition` builder\n - Manual: no config needed\n - AI: `confidence` slider (0.70–0.95) + `max frequency` selector\n- Footer: `Save` (primary), `Cancel` (secondary)\n\n---\n\n### 8.4 Data Flow\n\n```\n┌──────────────────────────────────────────────────────────────────────────────┐\n│ DATA FLOW: Workflows │\n├──────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ INBOUND │\n│ ─────── │\n│ 1. Workflow definitions → D1 (workflow_definitions) │\n│ 2. Execution logs → D1 (workflow_executions) + KV (real-time status) │\n│ 3. Templates → D1 (workflow_templates) + R2 (previews) │\n│ 4. AI proposals → twin-orchestrator DO → user approval → D1 │\n│ │\n│ OUTBOUND │\n│ ──────── │\n│ 1. Create/Edit → Gateway → workflow service → D1 │\n│ 2. Run → Gateway → Hermes → workflow DO → capability invocations │\n│ 3. Trigger: cron DO / event queue → workflow DO enqueue │\n│ 4. AI proposal: twin → govern → user → workflow DO (if approved) │\n│ │\n│ SERVICES │\n│ ──────── │\n│ • workflow (workflow DO, execution engine) │\n│ • hermes (capability routing for action nodes) │\n│ • scheduler (cron triggers) │\n│ • twin-orchestrator (AI proposals) │\n│ • govern (approval for AI-proposed workflows) │\n│ • store (persistence) │\n│ │\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n### 8.5 User Interactions\n\n#### Flow: User Creates and Runs a Workflow from Template\n\n| Step | Action | System Response | UI Change |\n| ---- | ------------------------------------------------ | ------------------------------------------- | ---------------------------------------------------- |\n| 1 | User opens Workflows, clicks \"Templates\" | Templates fetched from D1 | Gallery of official + community templates |\n| 2 | User clicks \"Install\" on \"Revenue Recognition\" | Workflow definition copied to user's tenant | Editor opens with template pre-loaded |\n| 3 | User customizes trigger to \"Monthly, 1st at 9am\" | Cron trigger saved | Trigger node shows \"Monthly 9am\" |\n| 4 | User clicks \"Publish\" | Workflow status → `active` | Toast: \"Workflow active. Next run: July 1, 9:00 AM.\" |\n| 5 | Workflow runs on schedule | Execution log written, capabilities invoked | Execution dashboard shows \"Running\" → \"Completed\" |\n| 6 | User views execution log | Step-by-step trace fetched | Log drawer shows each node, input/output, latency |\n\n---\n\n### 8.6 States\n\n#### Empty States\n\n| State | Visual Treatment |\n| ------------------- | -------------------------------------------------------------------------------- |\n| **No workflows** | \"No workflows yet. Create one from scratch or install a template.\" + CTA buttons |\n| **No templates** | \"No templates available. Check back later.\" |\n| **No executions** | \"This workflow hasn't run yet. Click 'Run Now' to test.\" |\n| **No AI proposals** | \"The Twin is watching. When it spots a pattern, a proposal will appear here.\" |\n\n#### Loading States\n\n| Component | Indicator |\n| --------- | -------------------------------------- |\n| Editor | Skeleton nodes + \"Loading workflow...\" |\n| Gallery | Skeleton cards |\n| Dashboard | Skeleton table rows |\n| Execution | Real-time step progress + spinner |\n| Run | Inline button spinner + \"Running...\" |\n\n#### Error States\n\n| Error | Visual Treatment | Recovery |\n| --------------------- | ----------------------------------------------------------------------- | ------------------------ |\n| **Workflow invalid** | Node red border + \"Invalid configuration\" tooltip | Fix properties, re-save. |\n| **Execution failed** | Status: red + error message in log. Toast: \"Workflow failed at step 3.\" | View log, edit, rerun. |\n| **Trigger error** | \"Invalid cron expression\" inline. | Correct cron syntax. |\n| **Permission denied** | \"You don't have permission to edit this workflow.\" | Fork or request access. |\n\n---\n\n### 8.7 Accessibility\n\n| Requirement | Implementation |\n| ----------------- | -------------------------------------------------------------------- |\n| **Editor** | Same as Browser Automation canvas: `role` and `aria-label` on nodes. |\n| **Dashboard** | Table: `scope=\"col\"` headers. Row actions: `aria-label`. |\n| **Triggers** | `aria-live=\"polite\"` on cron preview. Slider: `aria-valuemin/max`. |\n| **Modals** | Focus trap. `Esc` closes. Return focus. |\n| **Notifications** | Toast: `aria-live=\"polite\"`. AI banner: `aria-live=\"polite\"`. |\n\n---\n\n### 8.8 Responsive Behavior\n\n| Breakpoint | Behavior |\n| ----------- | --------------------------------------------------------------------------- |\n| **Desktop** | Full editor canvas + side panels. Gallery `3-col`. Dashboard full table. |\n| **Tablet** | Editor: properties panel as overlay. Gallery `2-col`. Dashboard scrollable. |\n| **Mobile** | Editor: read-only, view executions. Gallery `1-col`. Dashboard: card view. |\n\n---\n\n## Appendix A: Shared TypeScript Interfaces\n\n```typescript\n// ============================================\n// SHARED UI TYPES\n// ============================================\n\nexport type ProjectionType =\n | \"sales\"\n | \"cs\"\n | \"finance\"\n | \"executive\"\n | \"architecture\"\n | \"operations\"\n | \"personal\"\n | \"developer\";\n\nexport type Role = \"owner\" | \"admin\" | \"member\" | \"viewer\" | \"api\" | \"tam\" | \"account_success\";\n\nexport type OodaPhase = \"observe\" | \"orient\" | \"decide\" | \"act\" | \"cross-phase\";\n\nexport interface Entity360 {\n primaryEntity: {\n id: string; // SSOC UUID\n type: string;\n providerId: string;\n displayName: string;\n traits: Record;\n };\n relatedEntities: RelatedEntity[];\n timeline: TimelineEvent[];\n memory: {\n lastInteraction: number; // timestamp\n sentiment: number; // -1 to 1\n keyTopics: string[];\n openTasks: number;\n };\n knowledge: KnowledgeChunk[];\n availableCapabilities: string[];\n}\n\nexport interface RelatedEntity {\n id: string;\n type: string;\n displayName: string;\n relationType: string;\n confidence: number;\n}\n\nexport interface TimelineEvent {\n timestamp: Date;\n action: string;\n actor: string;\n via: string;\n description: string;\n}\n\nexport interface KnowledgeChunk {\n id: string;\n documentId: string;\n content: string;\n source: string;\n pageNumber?: number;\n heading?: string;\n}\n\nexport interface CapabilityInfo {\n id: string; // capability URI\n displayName: string;\n description: string;\n namespace: string;\n oodaPhase: OodaPhase;\n requiresApproval: boolean;\n minConfidence: number;\n autoApproveThreshold: number;\n requiredRoles: string[];\n requiredScopes: string[];\n usageCount: number;\n averageConfidence: number;\n averageLatencyMs: number;\n isActive: boolean;\n isDeprecated: boolean;\n inputSchema?: Record;\n outputSchema?: Record;\n}\n\nexport interface GovernanceStatus {\n pendingProposals: number;\n autoApprovedToday: number;\n hitlToday: number;\n rejectedToday: number;\n}\n\nexport interface TwinInsight {\n id: string;\n type: \"proposal\" | \"context\" | \"suggestion\" | \"alert\" | \"pattern\";\n message: string;\n confidence: number;\n entityId?: string;\n entityName?: string;\n action?: { capability: string; payload: unknown; label: string };\n dismissible: boolean;\n}\n\nexport interface MemoryRecord {\n id: string;\n scope: \"personal\" | \"work\" | \"organization\" | \"ai\";\n tier: \"active\" | \"staging\" | \"archived\";\n content: string;\n confidence: number;\n source: string;\n ssocReferences: string[];\n accessCount: number;\n lastAccessedAt?: Date;\n createdAt: Date;\n}\n\nexport interface SearchResult {\n type: \"entity\" | \"capability\" | \"memory\" | \"knowledge\" | \"command\";\n id: string;\n title: string;\n subtitle: string;\n icon: string;\n score: number;\n entityType?: string;\n entityId?: string;\n}\n\nexport interface Command {\n id: string;\n label: string;\n shortcut?: string;\n category: \"navigation\" | \"action\" | \"projection\" | \"twin\" | \"system\";\n icon: string;\n action: () => void;\n}\n\nexport interface ChatSession {\n id: string;\n title: string;\n preview: string;\n timestamp: Date;\n messageCount: number;\n isPinned: boolean;\n}\n\nexport interface ChatMessage {\n id: string;\n role: \"user\" | \"assistant\" | \"system\";\n content: string;\n timestamp: Date;\n toolCalls?: ToolCallDisplay[];\n memoryCitations?: MemoryCitation[];\n fileAttachments?: FileAttachment[];\n proposal?: ProposalInline;\n isStreaming?: boolean;\n}\n\nexport interface ToolCallDisplay {\n id: string;\n capability: string;\n status: \"pending\" | \"running\" | \"success\" | \"error\";\n input?: unknown;\n output?: unknown;\n latencyMs?: number;\n}\n\nexport interface MemoryCitation {\n memoryId: string;\n content: string;\n source: string;\n confidence: number;\n entityName?: string;\n}\n\nexport interface FileAttachment {\n id: string;\n name: string;\n mimeType: string;\n size: number;\n url: string;\n thumbnailUrl?: string;\n}\n\nexport interface ProposalInline {\n id: string;\n summary: string;\n confidence: number;\n reasoningTrace?: string;\n estimatedImpact?: { revenue?: number; timeSaved?: number; riskScore?: number };\n capability: string;\n payload: unknown;\n}\n\nexport interface AuditEvent {\n id: string;\n timestamp: Date;\n actor: string;\n action: string;\n via: string;\n entityId?: string;\n entityName?: string;\n entityType?: string;\n capability?: string;\n confidence?: number;\n governanceDecision?: string;\n summary: string;\n payloadHash: string;\n metadata?: Record;\n}\n\nexport interface WorkflowNode {\n id: string;\n type: string;\n position: { x: number; y: number };\n data: Record;\n}\n\nexport interface WorkflowEdge {\n id: string;\n from: string;\n to: string;\n label?: string;\n}\n```\n\n---\n\n## Appendix B: CSS / Tailwind Quick Reference\n\n```css\n/* ============================================\n INTEGRATEWISE TAILWIND CONFIG EXTENSIONS\n ============================================ */\n\n/* Add to tailwind.config.js:\nmodule.exports = {\n theme: {\n extend: {\n colors: {\n 'iw-primary': {\n 50: '#eff6ff', 100: '#dbeafe', 200: '#bfdbfe', 300: '#93c5fd',\n 400: '#60a5fa', 500: '#3b82f6', 600: '#2563eb', 700: '#1d4ed8',\n 800: '#1e40af', 900: '#1e3a8a',\n },\n 'iw-neutral': {\n 50: '#f8fafc', 100: '#f1f5f9', 200: '#e2e8f0', 300: '#cbd5e1',\n 400: '#94a3b8', 500: '#64748b', 600: '#475569', 700: '#334155',\n 800: '#1e293b', 900: '#0f172a',\n },\n 'iw-success': '#22c55e',\n 'iw-warning': '#f59e0b',\n 'iw-danger': '#ef4444',\n },\n fontFamily: {\n sans: ['Inter', '-apple-system', 'BlinkMacSystemFont', 'Segoe UI', 'sans-serif'],\n mono: ['JetBrains Mono', 'Fira Code', 'monospace'],\n },\n animation: {\n 'subtle-pulse': 'subtle-pulse 3s ease-in-out infinite',\n },\n keyframes: {\n 'subtle-pulse': {\n '0%, 100%': { opacity: '1' },\n '50%': { opacity: '0.7' },\n },\n },\n },\n },\n};\n*/\n\n/* ============================================\n COMMON UTILITY PATTERNS\n ============================================ */\n\n/* Card base */\n.iw-card {\n @apply bg-white rounded-xl border border-iw-neutral-200 p-5\n hover:shadow-md transition-all duration-200;\n}\n\n/* Button primary */\n.iw-btn-primary {\n @apply bg-iw-primary-600 text-white rounded-lg px-4 py-2 text-sm\n hover:bg-iw-primary-700 active:bg-iw-primary-800\n focus:ring-2 focus:ring-iw-primary-500 focus:ring-offset-2\n disabled:opacity-50 disabled:cursor-not-allowed\n transition-colors duration-150;\n}\n\n/* Button secondary */\n.iw-btn-secondary {\n @apply bg-white border border-iw-neutral-200 text-iw-neutral-700 rounded-lg px-4 py-2 text-sm\n hover:bg-iw-neutral-50 active:bg-iw-neutral-100\n focus:ring-2 focus:ring-iw-primary-500 focus:ring-offset-2\n transition-colors duration-150;\n}\n\n/* Input base */\n.iw-input {\n @apply w-full bg-white border border-iw-neutral-200 rounded-lg px-3 py-2 text-sm\n focus:outline-none focus:ring-2 focus:ring-iw-primary-200 focus:border-iw-primary-400\n placeholder:text-iw-neutral-400\n transition-colors duration-150;\n}\n\n/* Badge */\n.iw-badge {\n @apply inline-flex items-center rounded-full px-2 py-0.5 text-[10px] font-bold uppercase tracking-wide;\n}\n\n/* Drawer overlay */\n.iw-drawer-overlay {\n @apply fixed inset-0 bg-black/40 backdrop-blur-sm z-40;\n}\n\n/* Drawer panel */\n.iw-drawer-panel {\n @apply fixed right-0 top-0 h-full bg-white shadow-2xl z-50\n transform transition-transform duration-400 ease-out;\n}\n\n/* Toast */\n.iw-toast {\n @apply fixed top-6 right-6 z-50 bg-white rounded-lg shadow-lg border px-4 py-3\n min-w-[300px] max-w-[400px] flex items-start gap-3\n animate-slide-in-right;\n}\n\n/* Skeleton */\n.iw-skeleton {\n @apply animate-pulse bg-iw-neutral-200 rounded;\n}\n\n/* Confidence badge */\n.iw-confidence-high {\n @apply bg-iw-success text-white;\n}\n.iw-confidence-medium {\n @apply bg-iw-warning text-white;\n}\n.iw-confidence-low {\n @apply bg-iw-danger text-white;\n}\n\n/* Scrollbar (subtle) */\n.iw-scrollbar::-webkit-scrollbar {\n width: 6px;\n}\n.iw-scrollbar::-webkit-scrollbar-track {\n background: transparent;\n}\n.iw-scrollbar::-webkit-scrollbar-thumb {\n background: #cbd5e1;\n border-radius: 3px;\n}\n.iw-scrollbar::-webkit-scrollbar-thumb:hover {\n background: #94a3b8;\n}\n```\n\n---\n\n## Appendix C: Keyboard Shortcuts Reference\n\n| Shortcut | Action | Context |\n| --------------------------- | ------------------------------ | ---------------------------- |\n| `⌘K` / `Ctrl+K` | Open Command Palette | Global |\n| `⌘/` / `Ctrl+/` | Toggle Overlay | Global |\n| `1`–`8` | Switch Projection | Workbench |\n| `⌘E` / `Ctrl+E` | Focus Entity Explorer | Workbench |\n| `⌘F` / `Ctrl+F` | Focus Universal Search | Workbench |\n| `Esc` | Close modal / drawer / overlay | Global |\n| `?` | Show keyboard shortcuts help | Global |\n| `Shift+1`–`Shift+8` | Open projection in split view | Workbench |\n| `⌘Enter` / `Ctrl+Enter` | Send message | AI Home |\n| `Shift+Enter` | New line in message | AI Home |\n| `↑` (in empty input) | Recall last message | AI Home |\n| `⌘S` / `Ctrl+S` | Save workflow | Workflow Editor |\n| `⌘R` / `Ctrl+R` | Run workflow | Workflow Editor |\n| `Delete` / `Backspace` | Delete selected node | Canvas (Workflow/Automation) |\n| `Ctrl+Z` / `⌘Z` | Undo | Canvas |\n| `Ctrl+Shift+Z` / `⌘Shift+Z` | Redo | Canvas |\n\n---\n\n> **End of Document**\n>\n> This specification is the definitive product UI reference for the IntegrateWise Continuity Bridge. All frontend implementations should conform to the layouts, components, data flows, states, accessibility requirements, and responsive behaviors described herein.\n>\n> For questions or clarifications, contact the Product Design team.\n"}