reflectt-node 0.1.7 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reflectt-node",
-  "version": "0.1.7",
+  "version": "0.1.11",
   "description": "Coordinate your AI agent team. Shared tasks, memory, reflections, and presence. Self-host for free.",
   "main": "dist/index.js",
   "type": "module",
@@ -44,6 +44,7 @@
   "author": "Team Reflectt",
   "license": "Apache-2.0",
   "dependencies": {
+    "@browserbasehq/stagehand": "^3.1.0",
     "@fastify/cors": "^10.0.1",
     "@fastify/multipart": "^9.4.0",
     "@fastify/websocket": "^11.0.1",
@@ -87,6 +88,7 @@
     "README.md"
   ],
   "optionalDependencies": {
+    "@browserbasehq/stagehand": "^3.1.0",
     "@xenova/transformers": "^2.17.2"
   },
   "overrides": {

package/public/dashboard.js

@@ -726,9 +726,10 @@ async function loadPresence() {
 // ---- Tasks ----
 async function loadTasks(forceFull = false) {
   try {
-    const useDelta = !forceFull && lastTaskSync > 0;
+    // Force full load if we have no tasks yet (e.g. first load failed)
+    const useDelta = !forceFull && lastTaskSync > 0 && allTasks.length > 0;
     const qs = new URLSearchParams();
-    qs.set('limit', '80');
+    qs.set('limit', '200');
     if (useDelta) qs.set('updatedSince', String(lastTaskSync));
 
     const r = await fetch(BASE + '/tasks?' + qs.toString());
@@ -1384,16 +1385,8 @@ async function loadSharedArtifacts() {
     const pinnedRows = pinned.map(p => {
       const found = files.find(f => (String(f.name || '')).toLowerCase() === p.name.toLowerCase());
       if (!found) {
-        return `<div style="padding:10px 12px;border-bottom:1px solid var(--border-subtle)">
-          <div style="display:flex;align-items:center;justify-content:space-between;gap:10px">
-            <div style="font-size:13px;color:var(--text-bright);font-weight:600">${esc(p.label)}</div>
-            <span class="assignee-tag" style="color:var(--yellow)">missing</span>
-          </div>
-          <div style="font-size:11px;color:var(--text-muted);margin-top:4px">
-            To make this available here, create a symlink in the shared workspace:<br/>
-            <code>ln -s ../RYANS-THOUGHTS.md ~/.openclaw/workspace-shared/process/RYANS-THOUGHTS.md</code>
-          </div>
-        </div>`;
+        // Operator notes are optional. If not configured, do not show an operator-only instruction to end users.
+        return '';
       }
       const href = '/shared/view?path=' + encodeURIComponent(found.path);
       return `<div style="padding:10px 12px;border-bottom:1px solid var(--border-subtle)">
@@ -1422,9 +1415,13 @@ async function loadSharedArtifacts() {
       </div>`;
     }).join('');
 
+    const pinnedBox = pinnedRows
+      ? `<div style="border:1px solid var(--border-subtle);border-radius:8px;overflow:hidden">${pinnedRows}</div>
+         <div style="height:10px"></div>`
+      : '';
+
     body.innerHTML = `
-      <div style="border:1px solid var(--border-subtle);border-radius:8px;overflow:hidden">${pinnedRows}</div>
-      <div style="height:10px"></div>
+      ${pinnedBox}
       <div style="font-size:11px;color:var(--text-muted);margin:0 0 8px">Shared workspace directory: <code>process/</code></div>
       <div style="border:1px solid var(--border-subtle);border-radius:8px;overflow:hidden">${listRows}</div>
     `;
@@ -1460,6 +1457,7 @@ async function loadHealth() {
     const team = health.team || { blockers: [], overlaps: [], compliance: null, agents: [] };
     const agentsSummary = health.agentsSummary || { agents: [] };
     const idleNudgeDebug = health.idleNudgeDebug || null;
+    const scope = team.scope || null;
 
     healthAgentMap = new Map((team.agents || []).map(a => [String(a.agent || '').toLowerCase(), a]));
     const workflow = health.workflow || { agents: [] };
@@ -1528,6 +1526,16 @@ async function loadHealth() {
     const body = document.getElementById('health-body');
     let html = '';
 
+    if (scope) {
+      const orgHealthLink = scope.orgHealthUrl
+        ? ` <a href="${esc(scope.orgHealthUrl)}" target="_blank" rel="noopener">Open org-health</a>`
+        : '';
+      html += `<div class="blocker-item" style="border-left:4px solid var(--yellow);margin-bottom:12px">
+        <div class="blocker-agent">${esc(scope.label || 'Host-local health')}</div>
+        <div class="blocker-text">${esc(scope.message || '')}${orgHealthLink}</div>
+      </div>`;
+    }
+
     // Agent Health Grid
     if (displayAgents.length > 0) {
       html += '<div class="health-section"><div class="health-section-title">Agent Status</div><div class="health-grid">';
@@ -1806,6 +1814,18 @@ function normalizeEpochMs(v) {
   return v;
 }
 
+function hasReviewerDecision(task) {
+  const meta = task && task.metadata && typeof task.metadata === 'object' ? task.metadata : null;
+  const decision = meta && meta.reviewer_decision && typeof meta.reviewer_decision === 'object'
+    ? meta.reviewer_decision
+    : null;
+  return !!decision;
+}
+
+function shouldEscalateReviewerSla(task) {
+  return task && task.slaState === 'breach' && !hasReviewerDecision(task);
+}
+
 function renderReviewQueue() {
   const panel = document.getElementById('review-queue-panel');
   const body = document.getElementById('review-queue-body');
@@ -1817,11 +1837,23 @@ function renderReviewQueue() {
   const validating = allTasks
     .filter(t => t.status === 'validating')
     .map(t => {
-      const rawEntered = t.metadata?.entered_validating_at || t.updatedAt || t.createdAt;
+      const meta = t.metadata || {};
+      const reviewState = typeof meta.review_state === 'string' ? meta.review_state : '';
+      const reviewerDecision = meta.reviewer_decision;
+
+      // If reviewer has acted (needs_author or reviewer_decision recorded), the ball is with the assignee.
+      // We still track an SLA timer, but it should page the assignee (author), not the reviewer.
+      const waitOn = (reviewState === 'needs_author' || reviewerDecision != null) ? 'author' : 'reviewer';
+
+      const rawEntered = waitOn === 'author'
+        ? (reviewerDecision && reviewerDecision.decidedAt) || meta.review_last_activity_at || meta.entered_validating_at || t.updatedAt || t.createdAt
+        : meta.entered_validating_at || t.updatedAt || t.createdAt;
+
       const enteredAt = normalizeEpochMs(rawEntered) || now;
       const timeInReview = Math.min(Math.max(0, now - enteredAt), MAX_REVIEW_MS);
       const slaState = getReviewSlaState(timeInReview);
-      return { ...t, timeInReview, slaState, enteredAt };
+
+      return { ...t, timeInReview, slaState, enteredAt, waitOn, reviewState, hasReviewerDecision: reviewerDecision != null };
     })
     .sort((a, b) => {
       // Breaches first, then by time descending
@@ -1831,6 +1863,9 @@ function renderReviewQueue() {
       return b.timeInReview - a.timeInReview;
     });
 
+  const reviewerQueue = validating.filter(t => t.waitOn === 'reviewer');
+  const authorQueue = validating.filter(t => t.waitOn === 'author');
+
   if (validating.length === 0) {
     panel.style.display = '';
     count.textContent = '';
@@ -1846,16 +1881,29 @@ function renderReviewQueue() {
   }
 
   panel.style.display = '';
-  count.textContent = validating.length + ' awaiting review';
-  // Update sidebar badge
+  const reviewerBreachCount = reviewerQueue.filter(t => t.slaState === 'breach').length;
+  const authorBreachCount = authorQueue.filter(t => t.slaState === 'breach').length;
+
+  // Primary count is "awaiting reviewer" — author-wait tasks are tracked separately.
+  count.textContent = reviewerQueue.length + ' awaiting review';
+
+  // Update sidebar badge (reviewer queue only)
   const navReviewBadge = document.getElementById('nav-review-count');
-  if (navReviewBadge) navReviewBadge.textContent = validating.length;
+  if (navReviewBadge) navReviewBadge.textContent = String(reviewerQueue.length);
+
+  const headerExtra = (reviewerBreachCount > 0 || authorBreachCount > 0)
+    ? ' <span style="color:var(--red);font-size:11px;font-weight:600">'
+        + (reviewerBreachCount > 0 ? (reviewerBreachCount + ' reviewer breach' + (reviewerBreachCount > 1 ? 'es' : '')) : '')
+        + (reviewerBreachCount > 0 && authorBreachCount > 0 ? ' · ' : '')
+        + (authorBreachCount > 0 ? (authorBreachCount + ' author breach' + (authorBreachCount > 1 ? 'es' : '')) : '')
+      + '</span>'
+    : '';
 
-  const breachCount = validating.filter(t => t.slaState === 'breach').length;
-  const headerExtra = breachCount > 0
-    ? ' <span style="color:var(--red);font-size:11px;font-weight:600">' + breachCount + ' breach' + (breachCount > 1 ? 'es' : '') + '</span>'
+  const authorExtra = authorQueue.length > 0
+    ? ' <span style="color:var(--text-muted);font-size:11px;font-weight:500">· ' + authorQueue.length + ' awaiting author</span>'
     : '';
-  count.innerHTML = validating.length + ' awaiting review' + headerExtra;
+
+  count.innerHTML = reviewerQueue.length + ' awaiting review' + authorExtra + headerExtra;
 
   body.innerHTML = validating.map(t => {
     const reviewer = t.reviewer || '<span style="color:var(--yellow)">unassigned</span>';
@@ -1884,33 +1932,40 @@ function renderReviewQueue() {
 
   bindTaskLinkHandlers(body);
 
-  // SLA breach escalation: post to watchdog if any breach found
-  if (breachCount > 0) {
-    escalateReviewBreaches(validating.filter(t => t.slaState === 'breach'));
+  // SLA breach escalation: split reviewer-wait vs author-wait so we page the right person.
+  // shouldEscalateReviewerSla() suppresses escalation when reviewer_decision already exists.
+  if (reviewerBreachCount > 0) {
+    escalateReviewerBreaches(reviewerQueue.filter(shouldEscalateReviewerSla));
+  }
+  if (authorBreachCount > 0) {
+    escalateAuthorBreaches(authorQueue.filter(t => t.slaState === 'breach'));
   }
 }
 
-let lastReviewEscalationAt = 0;
+let lastReviewerEscalationAt = 0;
+let lastAuthorEscalationAt = 0;
 const REVIEW_ESCALATION_COOLDOWN = 20 * 60 * 1000; // 20m
 
-async function escalateReviewBreaches(breachedTasks) {
+async function escalateReviewerBreaches(breachedTasks) {
   const now = Date.now();
-  if (now - lastReviewEscalationAt < REVIEW_ESCALATION_COOLDOWN) return;
-  lastReviewEscalationAt = now;
+  if (now - lastReviewerEscalationAt < REVIEW_ESCALATION_COOLDOWN) return;
+  lastReviewerEscalationAt = now;
 
   const lines = breachedTasks.slice(0, 5).map(t => {
     const reviewer = t.reviewer || 'unassigned';
-    return '- ' + t.id + ' (' + (t.title || '').slice(0, 50) + ') — reviewer: @' + reviewer + ', waiting ' + formatDuration(t.timeInReview);
+    const prUrl = t.metadata?.review_handoff?.pr_url || t.metadata?.review_handoff?.prUrl || '';
+    const prPart = prUrl ? ' — ' + prUrl : '';
+    return '- ' + t.id + ' (' + (t.title || '').slice(0, 50) + ') — reviewer: @' + reviewer + ', waiting ' + formatDuration(t.timeInReview) + prPart;
   });
 
-  const content = '@owner Review SLA breach detected:\n' + lines.join('\n');
+  const content = 'Review overdue (reviewer SLA):\n' + lines.join('\n');
 
   try {
     await fetch(BASE + '/chat/messages', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
-        from: 'system',
+        from: 'dashboard',
         content,
         channel: 'general',
         timestamp: now
@@ -1921,6 +1976,36 @@ async function escalateReviewBreaches(breachedTasks) {
   }
 }
 
+async function escalateAuthorBreaches(breachedTasks) {
+  const now = Date.now();
+  if (now - lastAuthorEscalationAt < REVIEW_ESCALATION_COOLDOWN) return;
+  lastAuthorEscalationAt = now;
+
+  const lines = breachedTasks.slice(0, 5).map(t => {
+    const assignee = t.assignee || 'unassigned';
+    const prUrl = t.metadata?.review_handoff?.pr_url || t.metadata?.review_handoff?.prUrl || '';
+    const prPart = prUrl ? ' — ' + prUrl : '';
+    return '- ' + t.id + ' (' + (t.title || '').slice(0, 50) + ') — assignee: @' + assignee + ', waiting ' + formatDuration(t.timeInReview) + prPart;
+  });
+
+  const content = 'Author action needed (post-review):\n' + lines.join('\n');
+
+  try {
+    await fetch(BASE + '/chat/messages', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        from: 'dashboard',
+        content,
+        channel: 'general',
+        timestamp: now
+      })
+    });
+  } catch (err) {
+    console.error('Failed to escalate author breach:', err);
+  }
+}
+
 // ---- Feedback ----
 let feedbackData = null;
 
@@ -3020,13 +3105,21 @@ async function checkGettingStarted() {
 
 function dismissGettingStarted() {
   const panel = document.getElementById('getting-started');
-  if (panel) panel.classList.add('hidden');
+  if (panel) {
+    panel.classList.add('hidden');
+    panel.style.display = 'none';  // belt + suspenders
+  }
   try { localStorage.setItem('reflectt-gs-dismissed', '1'); } catch {}
 }
+// Expose globally for onclick handlers (safety net)
+window.dismissGettingStarted = dismissGettingStarted;
+window.dismissFirstBootBanner = dismissFirstBootBanner;
 
 updateClock();
 setInterval(updateClock, 30000);
 checkGettingStarted();
+// Retry getting-started check after 5s in case health wasn't ready at boot
+setTimeout(checkGettingStarted, 5000);
 refresh();
 connectEventStream();
 startAdaptiveRefresh();
@@ -3406,7 +3499,7 @@ function fileIcon(mimeType, name) {
 }
 
 function formatFileSize(bytes) {
-  if (!bytes) return '0 B';
+  if (typeof bytes !== 'number' || bytes <= 0) return '0 B';
   if (bytes < 1024) return bytes + ' B';
   if (bytes < 1048576) return (bytes / 1024).toFixed(1) + ' KB';
   return (bytes / 1048576).toFixed(1) + ' MB';
@@ -3455,7 +3548,7 @@ function renderFiles(files) {
     return '<div class="file-card" tabindex="0" role="button" aria-label="' + (f.originalName || f.filename) + '">' +
       '<div class="thumb" style="display:flex;align-items:center;justify-content:center;height:80px;background:var(--surface-raised);border-radius:var(--radius-sm);overflow:hidden">' + thumb + '</div>' +
       '<div class="card-name">' + (f.originalName || f.filename) + '</div>' +
-      '<div class="card-meta">' + formatFileSize(f.size) + ' · ' + timeAgo(f.uploadedAt || f.createdAt) + '</div>' +
+      '<div class="card-meta">' + formatFileSize(f.sizeBytes) + ' · ' + timeAgo(f.uploadedAt || f.createdAt) + '</div>' +
       '<div class="card-actions">' +
         '<a href="/files/' + f.id + '" download="' + (f.originalName || f.filename) + '" class="action-btn" aria-label="Download" onclick="event.stopPropagation()">⬇</a>' +
         '<button class="action-btn delete" aria-label="Delete" onclick="event.stopPropagation();deleteFile(\'' + f.id + '\')">🗑</button>' +
@@ -3468,7 +3561,7 @@ function renderFiles(files) {
     return '<div class="file-list-item" tabindex="0" role="button">' +
       '<span class="list-icon">' + icon + '</span>' +
       '<span class="list-name">' + (f.originalName || f.filename) + '</span>' +
-      '<span class="list-meta">' + formatFileSize(f.size) + '</span>' +
+      '<span class="list-meta">' + formatFileSize(f.sizeBytes) + '</span>' +
       '<span class="list-meta">' + timeAgo(f.uploadedAt || f.createdAt) + '</span>' +
       '<div class="list-actions">' +
         '<a href="/files/' + f.id + '" download="' + (f.originalName || f.filename) + '" class="action-btn" aria-label="Download" onclick="event.stopPropagation()">⬇</a>' +

package/public/design-tokens-platform.md

@@ -0,0 +1,118 @@
+# Design Tokens — Platform Mapping
+
+Source of truth: `/public/design-tokens.css`
+
+## iOS (Swift)
+
+```swift
+// Colors.swift — auto-generate from design-tokens.css
+import SwiftUI
+
+extension Color {
+    static let brandPrimary = Color(hex: "#7C3AED")
+    static let brandPrimaryLight = Color(hex: "#A78BFA")
+    static let brandPrimaryDark = Color(hex: "#5B21B6")
+
+    // Canvas states
+    static let stateFloor = Color(hex: "#1F2937")
+    static let stateListening = Color(hex: "#7C3AED")
+    static let stateThinking = Color(hex: "#6366F1")
+    static let stateRendering = Color(hex: "#8B5CF6")
+    static let stateAmbient = Color(hex: "#374151")
+    static let stateDecision = Color(hex: "#F59E0B")
+    static let stateUrgent = Color(hex: "#EF4444")
+    static let stateHandoff = Color(hex: "#10B981")
+
+    // Trust
+    static let trustActive = Color(hex: "#F87171")  // Red 400 — visible without alarming
+}
+
+// Dimensions.swift
+enum Dimension {
+    static let tapTargetMin: CGFloat = 44
+    static let tapTargetUrgent: CGFloat = 52
+    static let orbSizeIdle: CGFloat = 64
+    static let orbSizeTranscript: CGFloat = 44
+    static let trustIndicatorSize: CGFloat = 10
+    static let overrideBarHeight: CGFloat = 52
+    static let presenceDotSize: CGFloat = 8
+}
+
+// Animation.swift
+enum Timing {
+    static let fast: Double = 0.15
+    static let base: Double = 0.25
+    static let slow: Double = 0.35
+    static let canvas: Double = 0.5
+    static let orbGlow: Double = 1.8
+}
+```
+
+## Android (Kotlin)
+
+```xml
+<!-- colors.xml -->
+<color name="brand_primary">#FF7C3AED</color>
+<color name="brand_primary_light">#FFA78BFA</color>
+<color name="brand_primary_dark">#FF5B21B6</color>
+
+<color name="state_floor">#FF1F2937</color>
+<color name="state_listening">#FF7C3AED</color>
+<color name="state_thinking">#FF6366F1</color>
+<color name="state_rendering">#FF8B5CF6</color>
+<color name="state_ambient">#FF374151</color>
+<color name="state_decision">#FFF59E0B</color>
+<color name="state_urgent">#FFEF4444</color>
+<color name="state_handoff">#FF10B981</color>
+
+<color name="trust_active">#FFF87171</color> <!-- Red 400 -->
+
+<!-- dimens.xml -->
+<dimen name="tap_target_min">44dp</dimen>
+<dimen name="tap_target_urgent">52dp</dimen>
+<dimen name="orb_size_idle">64dp</dimen>
+<dimen name="orb_size_transcript">44dp</dimen>
+<dimen name="trust_indicator_size">10dp</dimen>
+<dimen name="override_bar_height">52dp</dimen>
+<dimen name="presence_dot_size">8dp</dimen>
+```
+
+```kotlin
+// Timing.kt
+object Timing {
+    const val FAST = 150L
+    const val BASE = 250L
+    const val SLOW = 350L
+    const val CANVAS = 500L
+    const val ORB_GLOW = 1800L
+}
+```
+
+## Important Notes
+
+**Canvas state colors are tint references, not solid fills.** The spec uses these as radial gradient tints. Platform implementations should apply them as gradient bases, not flat backgrounds. For v0 surfaces using solid fills, these values are acceptable approximations.
+
+**Trust indicator uses red-400 (#F87171)** — deliberately lighter than error red. Present and visible without being alarming. Both-sensors escalates to red-500 (#EF4444).
+
+## Token Categories
+
+| Category | Count | Notes |
+|----------|-------|-------|
+| Brand colors | 4 | Purple family |
+| Semantic colors | 8 | Success/warning/error/info + backgrounds |
+| Canvas states | 8 | Maps to state machine spec |
+| Trust | 4 | Mic/camera indicators |
+| Surface/bg | 6 | Light + dark mode |
+| Text | 6 | Primary through inverse |
+| Borders | 4 | Default/hover/focus/error |
+| Typography | 14 | Font family, size, weight, line-height |
+| Spacing | 12 | 0–64px scale |
+| Radius | 6 | 4px–full |
+| Shadows | 6 | sm through glow |
+| Transitions | 9 | Duration + easing |
+| Z-index | 8 | Layering scale |
+| Interactive | 3 | Tap targets + focus ring |
+| Canvas/orb | 5 | Orb dimensions + glow |
+| Override bar | 3 | Height/bg/blur |
+| Presence | 3 | Dot states |
+| **Total** | **~105** | |

package/public/design-tokens.css

@@ -0,0 +1,195 @@
+/* ═══════════════════════════════════════════════════════════════════════
+   Reflectt Design Tokens v0
+   ═══════════════════════════════════════════════════════════════════════
+   Single source of truth for all visual values across web, iOS, Android.
+   Platform implementations should map these to native equivalents:
+   - iOS: UIColor extensions + CGFloat constants
+   - Android: colors.xml + dimens.xml + attrs.xml
+   - Web: CSS custom properties (this file)
+
+   Usage: @import url('/design-tokens.css');
+   Or: <link rel="stylesheet" href="/design-tokens.css">
+   ═══════════════════════════════════════════════════════════════════════ */
+
+:root {
+  /* ── Brand Colors ─────────────────────────────────────────────────── */
+  --color-brand-primary: #7C3AED;       /* Purple 600 — main brand */
+  --color-brand-primary-light: #A78BFA; /* Purple 400 — hover/active */
+  --color-brand-primary-dark: #5B21B6;  /* Purple 800 — pressed */
+  --color-brand-accent: #8B5CF6;        /* Purple 500 — secondary accent */
+
+  /* ── Semantic Colors ──────────────────────────────────────────────── */
+  --color-success: #10B981;       /* Emerald 500 */
+  --color-success-bg: #D1FAE5;   /* Emerald 100 */
+  --color-warning: #F59E0B;       /* Amber 500 */
+  --color-warning-bg: #FEF3C7;   /* Amber 100 */
+  --color-error: #EF4444;         /* Red 500 */
+  --color-error-bg: #FEE2E2;     /* Red 100 */
+  --color-info: #3B82F6;          /* Blue 500 */
+  --color-info-bg: #DBEAFE;      /* Blue 100 */
+
+  /* ── Canvas State Colors ──────────────────────────────────────────── */
+  /* Maps to the 8-state machine from interface-os-v0-state-machine.html */
+  --color-state-floor: #1F2937;          /* Gray 800 — resting */
+  --color-state-listening: #7C3AED;      /* Purple 600 — active listening */
+  --color-state-thinking: #6366F1;       /* Indigo 500 — processing */
+  --color-state-rendering: #8B5CF6;      /* Purple 500 — outputting */
+  --color-state-ambient: #374151;        /* Gray 700 — passive monitoring */
+  --color-state-decision: #F59E0B;       /* Amber 500 — needs human input */
+  --color-state-urgent: #EF4444;         /* Red 500 — critical alert */
+  --color-state-handoff: #10B981;        /* Emerald 500 — transferring control */
+
+  /* ── Trust Indicator ──────────────────────────────────────────────── */
+  --color-trust-mic: #F87171;            /* Red 400 — visible without alarming */            /* Red — microphone active */
+  --color-trust-camera: #F87171;         /* Red — camera active */
+  --color-trust-mic-camera: #EF4444;  /* Red 500 — both sensors escalated */     /* Red 600 — both active */
+  --trust-indicator-size: 10px;
+  --trust-indicator-position-top: env(safe-area-inset-top, 8px);
+  --trust-indicator-position-left: 12px;
+  --trust-indicator-z-index: 9999;
+
+  /* ── Surface / Background ─────────────────────────────────────────── */
+  --color-bg-primary: #FFFFFF;
+  --color-bg-secondary: #F9FAFB;     /* Gray 50 */
+  --color-bg-tertiary: #F3F4F6;      /* Gray 100 */
+  --color-bg-elevated: #FFFFFF;
+  --color-bg-overlay: rgba(0, 0, 0, 0.5);
+  --color-bg-canvas: #0F0F0F;        /* Near-black for canvas surface */
+
+  /* ── Text ─────────────────────────────────────────────────────────── */
+  --color-text-primary: #111827;      /* Gray 900 */
+  --color-text-secondary: #6B7280;    /* Gray 500 */
+  --color-text-tertiary: #9CA3AF;     /* Gray 400 */
+  --color-text-inverse: #FFFFFF;
+  --color-text-link: #7C3AED;
+  --color-text-on-brand: #FFFFFF;
+
+  /* ── Borders ──────────────────────────────────────────────────────── */
+  --color-border-default: #E5E7EB;    /* Gray 200 */
+  --color-border-hover: #D1D5DB;      /* Gray 300 */
+  --color-border-focus: #7C3AED;
+  --color-border-error: #EF4444;
+
+  /* ── Typography ───────────────────────────────────────────────────── */
+  --font-family-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+  --font-family-mono: 'SF Mono', SFMono-Regular, ui-monospace, 'Cascadia Code', Menlo, monospace;
+
+  --font-size-xs: 0.75rem;     /* 12px */
+  --font-size-sm: 0.875rem;    /* 14px */
+  --font-size-base: 1rem;      /* 16px */
+  --font-size-lg: 1.125rem;    /* 18px */
+  --font-size-xl: 1.25rem;     /* 20px */
+  --font-size-2xl: 1.5rem;     /* 24px */
+  --font-size-3xl: 1.875rem;   /* 30px */
+
+  --font-weight-normal: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+  --font-weight-bold: 700;
+
+  --line-height-tight: 1.25;
+  --line-height-normal: 1.5;
+  --line-height-relaxed: 1.75;
+
+  /* ── Spacing ──────────────────────────────────────────────────────── */
+  --space-0: 0;
+  --space-1: 0.25rem;   /* 4px */
+  --space-2: 0.5rem;    /* 8px */
+  --space-3: 0.75rem;   /* 12px */
+  --space-4: 1rem;      /* 16px */
+  --space-5: 1.25rem;   /* 20px */
+  --space-6: 1.5rem;    /* 24px */
+  --space-8: 2rem;      /* 32px */
+  --space-10: 2.5rem;   /* 40px */
+  --space-12: 3rem;     /* 48px */
+  --space-16: 4rem;     /* 64px */
+
+  /* ── Border Radius ────────────────────────────────────────────────── */
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+  --radius-xl: 16px;
+  --radius-2xl: 24px;
+  --radius-full: 9999px;
+
+  /* ── Shadows ──────────────────────────────────────────────────────── */
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
+  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1);
+  --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1);
+  --shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1);
+  --shadow-glow-brand: 0 0 20px rgba(124, 58, 237, 0.3);
+  --shadow-glow-urgent: 0 0 20px rgba(239, 68, 68, 0.4);
+
+  /* ── Transitions ──────────────────────────────────────────────────── */
+  --transition-fast: 150ms;
+  --transition-base: 250ms;
+  --transition-slow: 350ms;
+  --transition-canvas: 500ms;    /* Canvas state transitions */
+
+  --easing-smooth: cubic-bezier(0.4, 0, 0.2, 1);
+  --easing-ease-out: cubic-bezier(0, 0, 0.2, 1);
+  --easing-ease-in: cubic-bezier(0.4, 0, 1, 1);
+  --easing-bounce: cubic-bezier(0.34, 1.56, 0.64, 1);
+  --easing-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275);
+
+  /* ── Z-Index Scale ────────────────────────────────────────────────── */
+  --z-base: 0;
+  --z-dropdown: 100;
+  --z-sticky: 200;
+  --z-overlay: 300;
+  --z-modal: 400;
+  --z-popover: 500;
+  --z-toast: 600;
+  --z-override-bar: 800;      /* Persistent controls */
+  --z-trust-indicator: 9999;   /* Non-dismissable, always on top */
+
+  /* ── Interactive Elements ─────────────────────────────────────────── */
+  --tap-target-min: 44px;      /* WCAG minimum */
+  --tap-target-urgent: 52px;   /* Enlarged in urgent state */
+  --focus-ring: 0 0 0 3px rgba(124, 58, 237, 0.4);
+
+  /* ── Canvas / Orb ─────────────────────────────────────────────────── */
+  --orb-size-idle: 64px;
+  --orb-size-active: 64px;
+  --orb-size-transcript: 44px;   /* Shrinks when transcript appears */
+  --orb-glow-duration: 1.8s;
+  --orb-color: var(--color-brand-primary);
+
+  /* ── Override Bar ─────────────────────────────────────────────────── */
+  --override-bar-height: 52px;
+  --override-bar-bg: rgba(0, 0, 0, 0.85);
+  --override-bar-blur: 20px;
+
+  /* ── Presence Dot ─────────────────────────────────────────────────── */
+  --presence-dot-size: 8px;
+  --presence-dot-active: #10B981;    /* Online */
+  --presence-dot-idle: #F59E0B;      /* Away */
+  --presence-dot-offline: #6B7280;   /* Disconnected */
+}
+
+/* ── Dark Mode ──────────────────────────────────────────────────────── */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-bg-primary: #111827;
+    --color-bg-secondary: #1F2937;
+    --color-bg-tertiary: #374151;
+    --color-bg-elevated: #1F2937;
+    --color-bg-overlay: rgba(0, 0, 0, 0.7);
+
+    --color-text-primary: #F9FAFB;
+    --color-text-secondary: #9CA3AF;
+    --color-text-tertiary: #6B7280;
+
+    --color-border-default: #374151;
+    --color-border-hover: #4B5563;
+
+    --color-success-bg: rgba(16, 185, 129, 0.15);
+    --color-warning-bg: rgba(245, 158, 11, 0.15);
+    --color-error-bg: rgba(239, 68, 68, 0.15);
+    --color-info-bg: rgba(59, 130, 246, 0.15);
+
+    --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.3);
+    --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.4);
+    --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.4);
+  }
+}