@jhizzard/termdeck 0.4.3 → 0.4.5

package/README.md

@@ -139,7 +139,7 @@ Restart Claude Code. Six MCP tools appear: `memory_remember`, `memory_recall`, `
 
 ### Tier 3 — Add Rumen for async learning
 
-Rumen is a separate npm package — `@jhizzard/rumen@0.4.3` — that ships as a Supabase Edge Function designed to run on a 15-minute `pg_cron` schedule. It's the async reflection layer over Mnestra: it reads recent session memories, cross-references them with your entire historical corpus via hybrid search, synthesizes insights via Claude Haiku, and writes the results back into `rumen_insights` (a new table alongside Mnestra's `memory_items`). TermDeck's Flashback and Claude Code's `memory_recall` both automatically benefit because insights flow back into the same database.
+Rumen is a separate npm package — `@jhizzard/rumen@0.4.5` — that ships as a Supabase Edge Function designed to run on a 15-minute `pg_cron` schedule. It's the async reflection layer over Mnestra: it reads recent session memories, cross-references them with your entire historical corpus via hybrid search, synthesizes insights via Claude Haiku, and writes the results back into `rumen_insights` (a new table alongside Mnestra's `memory_items`). TermDeck's Flashback and Claude Code's `memory_recall` both automatically benefit because insights flow back into the same database.
 
 **Rumen is live.** First full-kickstart run against a production Mnestra store on 2026-04-15 19:47 UTC: **111 sessions processed, 111 insights generated** in one pass. Insights surfaced patterns like "the error detection regex in Flashback misses `No such file or directory` — same class of blind spot as X" and "Practice sessions exist as a separate model but frontend components were built and never wired into the schedule view." The cognitive loop is closed.
 
@@ -163,7 +163,7 @@ Honest limits, stated upfront so the skeptic has nothing to chase:
 - **Not a replacement for reading docs.** It's the shortest path to a memory you already wrote. If the memory isn't there, the feature does nothing.
 - **Not fully local by default.** Tier 2+ reaches out to Supabase for storage and OpenAI for embeddings. Tier 1 is fully local. A fully-local Tier 2 (local Postgres + local embeddings) is on the roadmap.
 - **Not free forever.** Tier 2+ pays OpenAI fractions of a cent per memory for embeddings. Self-hosted embeddings via Ollama are on the roadmap.
-- **Not proven at scale.** v0.4.3, validated against 3,527 memories in one developer's production store. First full Rumen kickstart on 2026-04-15 processed 111 sessions into 111 insights in one pass. No multi-user data yet. Bug reports and issues welcome.
+- **Not proven at scale.** v0.4.5, validated against 3,527 memories in one developer's production store. First full Rumen kickstart on 2026-04-15 processed 111 sessions into 111 insights in one pass. No multi-user data yet. Bug reports and issues welcome.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Browser-based terminal multiplexer with metadata overlays, panel flashback memory recall, and AI-aware session management",
   "bin": {
     "termdeck": "./packages/cli/src/index.js"

package/packages/client/public/app.js

@@ -1852,6 +1852,15 @@
       const grid = document.getElementById('termGrid');
       grid.className = `grid-container layout-${layout}`;
 
+      // Orchestrator layout: set column count based on worker panels (total - 1)
+      if (layout === 'orch') {
+        const panelCount = grid.querySelectorAll('.term-panel').length;
+        const workerCount = Math.max(0, panelCount - 1);
+        grid.setAttribute('data-orch-cols', String(workerCount || panelCount));
+      } else {
+        grid.removeAttribute('data-orch-cols');
+      }
+
       // Remove focus/half states
       document.querySelectorAll('.term-panel').forEach(p => {
         p.classList.remove('focused', 'primary');
@@ -2019,6 +2028,20 @@
       }
     }
 
+    // Debounce: collapse a burst of calls (e.g. a window-resize drag firing
+    // dozens of events/sec) into a single invocation after `wait` ms of quiet.
+    function debounce(fn, wait) {
+      let timer = null;
+      return function debounced(...args) {
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(() => { timer = null; fn.apply(this, args); }, wait);
+      };
+    }
+
+    const fitAllDebounced = debounce(() => {
+      requestAnimationFrame(() => fitAll());
+    }, 100);
+
     // ===== ONBOARDING TOUR =====
     // Spotlight + tooltip walkthrough of every TermDeck surface. Runs once on
     // first visit (localStorage gate) and replays on demand via the "how this
@@ -2038,7 +2061,7 @@
       {
         target: '.topbar-center',
         title: 'Layout modes',
-        body: `Eight preset grid layouts — <kbd>1x1</kbd> through <kbd>4x2</kbd>, <strong>orch</strong> (1 large + stacked, for 4+1 sprints), plus <strong>control</strong> (aggregate activity feed). Click any layout to switch instantly; all terminals re-fit to the new grid. Keyboard shortcuts <kbd>Cmd+Shift+1</kbd>–<kbd>Cmd+Shift+7</kbd> (or <kbd>Ctrl+Shift+1</kbd>–<kbd>7</kbd>) do the same.`,
+        body: `Eight preset grid layouts — <kbd>1x1</kbd> through <kbd>4x2</kbd>, <strong>orch</strong> (4 workers across the top + 1 full-width orchestrator across the bottom, for 4+1 sprints), plus <strong>control</strong> (aggregate activity feed). Click any layout to switch instantly; all terminals re-fit to the new grid. Keyboard shortcuts <kbd>Cmd+Shift+1</kbd>–<kbd>Cmd+Shift+7</kbd> (or <kbd>Ctrl+Shift+1</kbd>–<kbd>7</kbd>) do the same.`,
       },
       {
         target: '#termSwitcher',
@@ -2555,15 +2578,21 @@
           ? 'active'
           : status === 'partial' ? 'partial' : 'not configured';
         const isCurrent = Number(tier.id) === currentTier + 1 && status !== 'active';
-        const cmds = (status === 'active' || tier.commands.length === 0)
-          ? ''
-          : `<div class="setup-cmds">${tier.commands.map((c) => {
-              const copyable = /^termdeck\s/.test(c);
-              return `<div class="setup-cmd">
-                <code>${escapeHtml(c)}</code>
-                ${copyable ? `<button type="button" class="setup-copy" data-copy="${escapeHtml(c)}">copy</button>` : ''}
-              </div>`;
-            }).join('')}</div>`;
+
+        // Sprint 23 T2: tier 2 renders a credential form instead of CLI commands
+        // when not active, so users can paste URL/keys directly in the browser.
+        const isCredentialForm = tier.id === '2' && status !== 'active';
+        const cmds = isCredentialForm
+          ? renderSetupCredentialForm()
+          : (status === 'active' || tier.commands.length === 0)
+            ? ''
+            : `<div class="setup-cmds">${tier.commands.map((c) => {
+                const copyable = /^termdeck\s/.test(c);
+                return `<div class="setup-cmd">
+                  <code>${escapeHtml(c)}</code>
+                  ${copyable ? `<button type="button" class="setup-copy" data-copy="${escapeHtml(c)}">copy</button>` : ''}
+                </div>`;
+              }).join('')}</div>`;
 
         return `
           <div class="setup-tier setup-tier-${status}${isCurrent ? ' setup-tier-next' : ''}">
@@ -2600,26 +2629,263 @@
           }).catch(() => {});
         });
       });
+
+      const credSaveBtn = tiersEl.querySelector('#setupCredSave');
+      if (credSaveBtn) {
+        credSaveBtn.addEventListener('click', submitSetupCredentials);
+      }
+      const credForm = tiersEl.querySelector('#setupCredForm');
+      if (credForm) {
+        credForm.addEventListener('keydown', (e) => {
+          if (e.key === 'Enter' && !e.shiftKey) {
+            e.preventDefault();
+            submitSetupCredentials();
+          }
+        });
+      }
+    }
+
+    // Sprint 23 T2 — credential form for Tier 2.
+    // Uses inline styles because wizard CSS is owned by T1 this sprint; these
+    // stubs fall back to CSS vars already defined in style.css so they inherit
+    // theme colours automatically.
+    function renderSetupCredentialForm() {
+      const inputStyle = 'width:100%;padding:6px 8px;background:var(--bg, #0f1017);color:var(--text, #e2e3e8);border:1px solid var(--border, #2a2c3a);border-radius:4px;font-family:monospace;font-size:12px;margin-top:4px;box-sizing:border-box;';
+      const labelStyle = 'display:block;font-size:11px;color:var(--text-dim, #8a8d9a);margin-top:10px;';
+      const helpStyle = 'font-size:10px;color:var(--text-dim, #8a8d9a);margin-top:3px;min-height:12px;';
+      const btnStyle = 'margin-top:14px;padding:8px 18px;background:var(--accent, #7aa2f7);color:#000;border:none;border-radius:4px;font-weight:600;cursor:pointer;font-size:12px;';
+      return `
+        <form class="setup-credentials" id="setupCredForm" autocomplete="off" style="margin-top:10px;padding:12px;background:rgba(0,0,0,0.2);border-radius:6px;border:1px solid var(--border, #2a2c3a);">
+          <div style="font-size:11px;color:var(--text-dim, #8a8d9a);margin-bottom:4px;">
+            Paste your Supabase + OpenAI credentials. They are written to <code>~/.termdeck/secrets.env</code> (chmod 600) and never leave this machine.
+          </div>
+          <label style="${labelStyle}">
+            Supabase URL
+            <input type="text" name="supabaseUrl" placeholder="https://xxxxxx.supabase.co" spellcheck="false" autocapitalize="off" autocorrect="off" style="${inputStyle}">
+          </label>
+          <div class="setup-cred-status" data-field="supabase" style="${helpStyle}"></div>
+          <label style="${labelStyle}">
+            Service Role Key
+            <input type="password" name="supabaseServiceRoleKey" placeholder="sb_secret_..." spellcheck="false" autocomplete="new-password" style="${inputStyle}">
+          </label>
+          <label style="${labelStyle}">
+            OpenAI API Key
+            <input type="password" name="openaiApiKey" placeholder="sk-proj-..." spellcheck="false" autocomplete="new-password" style="${inputStyle}">
+          </label>
+          <div class="setup-cred-status" data-field="openai" style="${helpStyle}"></div>
+          <label style="${labelStyle}">
+            Database URL
+            <input type="password" name="databaseUrl" placeholder="postgresql://postgres:...@...pooler.supabase.com:6543/postgres" spellcheck="false" autocomplete="new-password" style="${inputStyle}">
+          </label>
+          <div class="setup-cred-status" data-field="database" style="${helpStyle}"></div>
+          <label style="${labelStyle}">
+            Anthropic API Key <span style="opacity:0.6;">(optional — powers session-log summaries)</span>
+            <input type="password" name="anthropicApiKey" placeholder="sk-ant-..." spellcheck="false" autocomplete="new-password" style="${inputStyle}">
+          </label>
+          <div class="setup-cred-error" id="setupCredError" style="font-size:11px;margin-top:10px;min-height:14px;"></div>
+          <button type="button" class="setup-cred-save" id="setupCredSave" style="${btnStyle}">Save &amp; Connect</button>
+        </form>
+      `;
+    }
+
+    async function submitSetupCredentials() {
+      const form = document.getElementById('setupCredForm');
+      if (!form) return;
+      const btn = document.getElementById('setupCredSave');
+      const errorEl = document.getElementById('setupCredError');
+      const statuses = form.querySelectorAll('.setup-cred-status');
+
+      // Reset state
+      if (errorEl) { errorEl.textContent = ''; errorEl.style.color = ''; }
+      statuses.forEach((el) => { el.textContent = ''; el.style.color = ''; });
+
+      const body = {
+        supabaseUrl: (form.supabaseUrl.value || '').trim(),
+        supabaseServiceRoleKey: (form.supabaseServiceRoleKey.value || '').trim(),
+        openaiApiKey: (form.openaiApiKey.value || '').trim(),
+        anthropicApiKey: (form.anthropicApiKey.value || '').trim(),
+        databaseUrl: (form.databaseUrl.value || '').trim()
+      };
+
+      const missing = [];
+      if (!body.supabaseUrl) missing.push('Supabase URL');
+      if (!body.supabaseServiceRoleKey) missing.push('Service Role Key');
+      if (!body.openaiApiKey) missing.push('OpenAI API Key');
+      if (!body.databaseUrl) missing.push('Database URL');
+      if (missing.length) {
+        if (errorEl) {
+          errorEl.textContent = `Please fill in: ${missing.join(', ')} (Anthropic is optional).`;
+          errorEl.style.color = 'var(--red, #f7768e)';
+        }
+        return;
+      }
+
+      if (btn) { btn.disabled = true; btn.textContent = 'Validating…'; }
+      try {
+        const res = await fetch(`${API}/api/setup/configure`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(body)
+        });
+        let data = {};
+        try { data = await res.json(); } catch { data = {}; }
+
+        if (data && data.validation) {
+          for (const field of ['supabase', 'openai', 'database']) {
+            const result = data.validation[field];
+            if (!result) continue;
+            const el = form.querySelector(`.setup-cred-status[data-field="${field}"]`);
+            if (el) {
+              el.textContent = (result.ok ? '✓ ' : '✗ ') + (result.detail || '');
+              el.style.color = result.ok ? 'var(--green, #9ece6a)' : 'var(--red, #f7768e)';
+            }
+          }
+        }
+
+        if (res.ok && data && data.success) {
+          if (errorEl) {
+            errorEl.textContent = (data.detail || 'Credentials saved.') + ' Running migrations…';
+            errorEl.style.color = 'var(--green, #9ece6a)';
+          }
+          if (btn) btn.textContent = 'Migrating…';
+          await runSetupMigrations(errorEl);
+          setTimeout(() => { refreshSetupStatus(); }, 600);
+        } else {
+          if (errorEl) {
+            errorEl.textContent = (data && data.error) || `Configuration failed (HTTP ${res.status})`;
+            errorEl.style.color = 'var(--red, #f7768e)';
+          }
+        }
+      } catch (err) {
+        if (errorEl) {
+          errorEl.textContent = `Request failed: ${err && err.message ? err.message : String(err)}`;
+          errorEl.style.color = 'var(--red, #f7768e)';
+        }
+      } finally {
+        if (btn) { btn.disabled = false; btn.textContent = 'Save & Connect'; }
+      }
+    }
+
+    // Sprint 23 audit fix: chain /api/setup/migrate after credentials save so
+    // the wizard fulfills the sprint mission ("write config AND run migrations")
+    // in a single click instead of leaving the user to run `termdeck init`.
+    async function runSetupMigrations(statusEl) {
+      try {
+        const res = await fetch(`${API}/api/setup/migrate`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: '{}'
+        });
+        let data = {};
+        try { data = await res.json(); } catch { data = {}; }
+        if (statusEl) {
+          if (res.ok && data && data.ok) {
+            statusEl.textContent = `Migrations applied (${data.applied}/${data.total}). Tier 2 active.`;
+            statusEl.style.color = 'var(--green, #9ece6a)';
+          } else {
+            const applied = (data && data.applied != null) ? `${data.applied}/${data.total} applied` : '';
+            const detail = (data && data.error) ? data.error : `HTTP ${res.status}`;
+            statusEl.textContent = `Migrations failed: ${detail}${applied ? ` (${applied})` : ''}`;
+            statusEl.style.color = 'var(--red, #f7768e)';
+          }
+        }
+      } catch (err) {
+        if (statusEl) {
+          statusEl.textContent = `Migration request failed: ${err && err.message ? err.message : String(err)}`;
+          statusEl.style.color = 'var(--red, #f7768e)';
+        }
+      }
     }
 
     async function maybeAutoOpenSetupWizard() {
-      // Auto-open only when the server reports firstRun=true and we're not
-      // already in the middle of the onboarding tour. Silent-fail if the
-      // endpoint doesn't exist (server predates Sprint 19 T1).
+      // First-run users get the full wizard; returning users with at least
+      // tier 1 configured get a brief welcome-back toast (Sprint 23 T4).
+      // Silent-fail if the endpoint doesn't exist (server predates Sprint 19 T1).
       try {
         const res = await fetch(`${API}/api/setup`);
         if (!res.ok) return;
         const data = await res.json();
-        if (data && data.firstRun && !tourState.active) {
+        if (!data || tourState.active) return;
+        if (data.firstRun) {
           setTimeout(() => {
             if (!tourState.active && !setupModalOpen) openSetupModal();
           }, 800);
+        } else if (Number(data.tier) >= 1) {
+          setTimeout(() => {
+            if (!tourState.active && !setupModalOpen) showWelcomeBackToast(data);
+          }, 800);
         }
       } catch {
         // API not available — skip silently
       }
     }
 
+    // Sprint 23 T4: returning-user welcome-back toast. Non-blocking, dismisses
+    // on click or after 5s. Inline-styled so we don't touch style.css (T1's
+    // ownership). The config button still opens the full wizard.
+    function showWelcomeBackToast(data) {
+      const existing = document.getElementById('welcomeBackToast');
+      if (existing) existing.remove();
+
+      const tier = Number(data.tier) || 1;
+      const tierNames = {
+        1: 'TermDeck core',
+        2: 'TermDeck + Mnestra',
+        3: 'TermDeck + Mnestra + Rumen',
+        4: 'Full stack + projects'
+      };
+      const stackLabel = tierNames[tier] || 'TermDeck';
+
+      const tiers = data.tiers || {};
+      const mnestraDetail = (tiers[2] && tiers[2].detail) || '';
+      const rumenDetail = (tiers[3] && tiers[3].detail) || '';
+
+      const memMatch = mnestraDetail.match(/([\d,]+)\s*memories/i);
+      const memoryCount = memMatch ? memMatch[1] : null;
+      const rumenMatch = rumenDetail.match(/last job\s+([^,]+?)(?:\s+ago|,|$)/i);
+      const rumenAgo = rumenMatch ? rumenMatch[1].trim() : null;
+
+      const parts = [`Stack: ${stackLabel}.`];
+      if (memoryCount) parts.push(`${memoryCount} memories.`);
+      if (rumenAgo) parts.push(`Last Rumen job: ${rumenAgo} ago.`);
+
+      const toast = document.createElement('div');
+      toast.id = 'welcomeBackToast';
+      toast.setAttribute('role', 'status');
+      toast.style.cssText = [
+        'position:fixed',
+        'top:64px',
+        'right:16px',
+        'z-index:9999',
+        'max-width:360px',
+        'padding:10px 14px',
+        'background:rgba(20,22,28,0.95)',
+        'color:#cdd6f4',
+        'border:1px solid rgba(137,180,250,0.35)',
+        'border-radius:6px',
+        'box-shadow:0 4px 18px rgba(0,0,0,0.4)',
+        'font:12px/1.45 ui-monospace,SFMono-Regular,Menlo,monospace',
+        'cursor:pointer',
+        'opacity:0',
+        'transition:opacity 180ms ease'
+      ].join(';');
+      toast.innerHTML = `
+        <div style="font-weight:600;color:#89b4fa;margin-bottom:2px">Welcome back</div>
+        <div>${parts.map(p => escapeHtml(p)).join(' ')}</div>
+      `;
+
+      document.body.appendChild(toast);
+      requestAnimationFrame(() => { toast.style.opacity = '1'; });
+
+      const dismiss = () => {
+        clearTimeout(timer);
+        toast.style.opacity = '0';
+        setTimeout(() => toast.remove(), 200);
+      };
+      toast.addEventListener('click', dismiss);
+      const timer = setTimeout(dismiss, 5000);
+    }
+
     function fmtUptime(sec) {
       const s = Math.floor(sec);
       const h = Math.floor(s / 3600);
@@ -2675,10 +2941,8 @@
       if (e.target.id === 'tourBackdrop') endTour();
     });
 
-    // Resize handler
-    window.addEventListener('resize', () => {
-      requestAnimationFrame(() => fitAll());
-    });
+    // Resize handler — debounced so a resize drag doesn't re-fit every frame.
+    window.addEventListener('resize', fitAllDebounced);
 
     // Re-render the tour on viewport changes so the spotlight tracks resizes
     window.addEventListener('resize', () => {

package/packages/client/public/index.html

@@ -41,7 +41,7 @@
         <button class="layout-btn" data-layout="3x2">3x2</button>
         <button class="layout-btn" data-layout="2x4">2x4</button>
         <button class="layout-btn" data-layout="4x2">4x2</button>
-        <button class="layout-btn" data-layout="orch" title="Orchestrator: 1 large left + stacked right">orch</button>
+        <button class="layout-btn" data-layout="orch" title="Orchestrator: 4 workers across top, 1 full-width orchestrator across bottom">orch</button>
         <button class="layout-btn control-btn" data-layout="control" title="Aggregate activity feed">control</button>
       </div>
     </div>

package/packages/client/public/style.css

@@ -312,14 +312,25 @@
     .grid-container.layout-4x2 { grid-template-columns: 1fr 1fr 1fr 1fr; grid-template-rows: 1fr 1fr; }
     .grid-container.layout-2x4 { grid-template-columns: 1fr 1fr; grid-template-rows: 1fr 1fr 1fr 1fr; }
 
-    /* Orchestrator: 1 large left panel (60%), remaining stack on the right (40%). */
+    /* Orchestrator: workers across the top (60%), one full-width orchestrator
+       panel across the bottom (40%). The last panel is always the orchestrator.
+       JS sets a data-orch-cols attribute on the grid to match the worker count. */
+    /* Orchestrator: 2x2 workers on top (60%), full-width orchestrator bottom (40%) */
     .grid-container.layout-orch {
-      grid-template-columns: 3fr 2fr;
-      grid-template-rows: repeat(4, 1fr);
+      grid-template-columns: repeat(2, 1fr);
+      grid-template-rows: 2fr 2fr 2fr;
     }
-    .grid-container.layout-orch .term-panel:first-child {
-      grid-row: 1 / span 4;
-      grid-column: 1;
+    .grid-container.layout-orch .term-panel:last-child {
+      grid-column: 1 / -1;
+      grid-row: 3;
+    }
+    /* Single panel: fill entire grid */
+    .grid-container.layout-orch[data-orch-cols="0"] {
+      grid-template-rows: 1fr;
+      grid-template-columns: 1fr;
+    }
+    .grid-container.layout-orch[data-orch-cols="0"] .term-panel:last-child {
+      grid-row: 1;
     }
 
     /* Focus mode: single terminal fills the grid */
@@ -344,7 +355,8 @@
       border-radius: var(--tg-radius);
       overflow: hidden;
       transition: border-color 0.2s;
-      min-height: 0;
+      min-height: 150px;
+      min-width: 200px;
     }
 
     .term-panel:hover { border-color: var(--tg-border-active); }
@@ -2278,3 +2290,57 @@
     ::-webkit-scrollbar-track { background: transparent; }
     ::-webkit-scrollbar-thumb { background: var(--tg-border); border-radius: 3px; }
     ::-webkit-scrollbar-thumb:hover { background: var(--tg-border-active); }
+
+    /* ===== RESPONSIVE BREAKPOINTS (Sprint 23 T1) =====
+       13" MacBook Air (1280x800 / 1440x900) up through 27" iMac (2560x1440).
+       Goals: (1) compact toolbar on short viewports to reclaim vertical space
+       for terminals, (2) collapse wide grids (3x2, 4x2) to 2 columns on
+       narrow viewports so panels never drop below readable size (combined
+       with the 200px min-width on .term-panel). */
+
+    /* Short viewports (13" laptops at 1280x800 / 1440x900): shrink the two
+       toolbar rows from 74px to 64px total, and tighten button padding so
+       the quick-launch + layout buttons still fit on one row at 1280px. */
+    @media (max-height: 800px) {
+      .topbar-row-1 { height: 36px; }
+      .topbar-row-2 { height: 28px; }
+      .layout-btn { padding: 3px 7px; font-size: 10px; }
+      .topbar-right button { padding: 3px 6px; font-size: 10px; }
+      .topbar-ql-btn { padding: 3px 6px; font-size: 10px; }
+    }
+
+    /* Narrow viewports: 3x2 (6 panels) and 4x2 (8 panels) become
+       too cramped below ~1280px given the 200px panel min-width. Degrade to
+       2 columns and add rows so every panel stays visible. */
+    @media (max-width: 1280px) {
+      .grid-container.layout-3x2 {
+        grid-template-columns: repeat(2, 1fr);
+        grid-template-rows: repeat(3, 1fr);
+      }
+      .grid-container.layout-4x2 {
+        grid-template-columns: repeat(2, 1fr);
+        grid-template-rows: repeat(4, 1fr);
+      }
+    }
+
+    /* Very narrow viewports (rare — sub-1024 widths): also collapse 2x4
+       and orch to something sane. 2x4 already uses 2 columns, so we just
+       let it scroll; orch falls back to a single-column stack. */
+    @media (max-width: 900px) {
+      .grid-container.layout-orch {
+        grid-template-columns: 1fr;
+        grid-template-rows: repeat(var(--orch-worker-rows, 3), 1fr) 1.2fr;
+      }
+      .grid-container.layout-orch .term-panel:last-child {
+        grid-column: 1;
+      }
+      .grid-container { overflow: auto; }
+    }
+
+    /* Large viewports (27" iMac and ultrawide monitors): keep panels filling
+       their allocated grid area. Raise the panel floor so a single terminal
+       in 1x1 mode on a 2560-wide display still fills its space rather than
+       sitting at the 150px min. */
+    @media (min-width: 1920px) {
+      .term-panel { min-height: 200px; min-width: 300px; }
+    }

package/packages/server/src/index.js

@@ -3,6 +3,7 @@
 
 const express = require('express');
 const http = require('http');
+const https = require('https');
 const { WebSocketServer } = require('ws');
 const path = require('path');
 const os = require('os');
@@ -252,6 +253,171 @@ function createServer(config) {
     }
   });
 
+  // POST /api/setup/configure - Sprint 23 T2
+  // Accepts pasted credentials from the browser wizard, validates each,
+  // then writes ~/.termdeck/secrets.env (chmod 600) and updates
+  // ~/.termdeck/config.yaml with rag.enabled: true plus ${VAR} references.
+  // Security: the bind guardrail refuses non-loopback binds without auth,
+  // so this endpoint only ever responds on 127.0.0.1 in the default config.
+  app.post('/api/setup/configure', async (req, res) => {
+    const b = req.body || {};
+    const supabaseUrl = typeof b.supabaseUrl === 'string' ? b.supabaseUrl.trim() : '';
+    const supabaseServiceRoleKey = typeof b.supabaseServiceRoleKey === 'string' ? b.supabaseServiceRoleKey.trim() : '';
+    const openaiApiKey = typeof b.openaiApiKey === 'string' ? b.openaiApiKey.trim() : '';
+    const anthropicApiKey = typeof b.anthropicApiKey === 'string' ? b.anthropicApiKey.trim() : '';
+    const databaseUrl = typeof b.databaseUrl === 'string' ? b.databaseUrl.trim() : '';
+
+    const missing = [];
+    if (!supabaseUrl) missing.push('supabaseUrl');
+    if (!supabaseServiceRoleKey) missing.push('supabaseServiceRoleKey');
+    if (!openaiApiKey) missing.push('openaiApiKey');
+    if (!databaseUrl) missing.push('databaseUrl');
+    if (missing.length) {
+      return res.status(400).json({
+        success: false,
+        error: `Missing required credentials: ${missing.join(', ')}`
+      });
+    }
+
+    if (!/^https?:\/\//i.test(supabaseUrl)) {
+      return res.status(400).json({
+        success: false,
+        error: 'supabaseUrl must start with http:// or https://'
+      });
+    }
+
+    const [supaRes, oaiRes, dbRes] = await Promise.all([
+      validateSupabase(supabaseUrl, supabaseServiceRoleKey).catch((e) => ({ ok: false, detail: e.message })),
+      validateOpenAI(openaiApiKey).catch((e) => ({ ok: false, detail: e.message })),
+      validateDatabase(databaseUrl).catch((e) => ({ ok: false, detail: e.message }))
+    ]);
+    const validation = { supabase: supaRes, openai: oaiRes, database: dbRes };
+
+    const allValid = validation.supabase.ok && validation.openai.ok && validation.database.ok;
+    if (!allValid) {
+      return res.status(400).json({
+        success: false,
+        validation,
+        error: 'One or more credentials failed validation'
+      });
+    }
+
+    try {
+      if (!fs.existsSync(SETUP_CONFIG_DIR)) {
+        fs.mkdirSync(SETUP_CONFIG_DIR, { recursive: true });
+      }
+
+      const secretsBody = buildSecretsEnv({
+        SUPABASE_URL: supabaseUrl,
+        SUPABASE_SERVICE_ROLE_KEY: supabaseServiceRoleKey,
+        OPENAI_API_KEY: openaiApiKey,
+        ANTHROPIC_API_KEY: anthropicApiKey,
+        DATABASE_URL: databaseUrl
+      });
+      const tmpPath = SETUP_SECRETS_PATH + '.tmp';
+      fs.writeFileSync(tmpPath, secretsBody, { mode: 0o600 });
+      fs.renameSync(tmpPath, SETUP_SECRETS_PATH);
+      try { fs.chmodSync(SETUP_SECRETS_PATH, 0o600); } catch (err) {
+        console.warn('[setup] chmod 600 on secrets.env failed:', err.message);
+      }
+
+      process.env.SUPABASE_URL = supabaseUrl;
+      process.env.SUPABASE_SERVICE_ROLE_KEY = supabaseServiceRoleKey;
+      process.env.OPENAI_API_KEY = openaiApiKey;
+      if (anthropicApiKey) process.env.ANTHROPIC_API_KEY = anthropicApiKey;
+      process.env.DATABASE_URL = databaseUrl;
+
+      updateConfigYamlForRag(config);
+
+      _setupCache = null;
+      _setupCachedAt = 0;
+
+      console.log('[setup] Credentials saved, RAG enabled via wizard');
+
+      return res.json({
+        success: true,
+        tier: 2,
+        detail: 'Secrets saved, RAG enabled',
+        validation
+      });
+    } catch (err) {
+      console.error('[setup] /api/setup/configure write failed:', err.message);
+      return res.status(500).json({
+        success: false,
+        validation,
+        error: `Failed to write config: ${err.message}`
+      });
+    }
+  });
+
+  // POST /api/setup/migrate - auto-run all 7 bootstrap migrations (Sprint 23 T3)
+  // Invoked by the browser setup wizard after credentials are saved. Reloads
+  // ~/.termdeck/secrets.env so DATABASE_URL picks up T2's just-written value
+  // without a server restart, then streams per-migration status to the server
+  // log and returns an aggregate result to the client. Idempotent — all seven
+  // migration files (6 Mnestra + 1 transcript) are authored with IF NOT EXISTS
+  // / CREATE OR REPLACE so re-runs are safe.
+  const { migrationRunner: _migrationRunner, dotenv: _dotenv } = require('./setup');
+  let _migrateInFlight = false;
+  app.post('/api/setup/migrate', async (req, res) => {
+    if (_migrateInFlight) {
+      return res.status(409).json({ ok: false, error: 'Migration already in progress' });
+    }
+    _migrateInFlight = true;
+
+    // Invalidate the /api/setup cache — tier status will shift once migrations land.
+    _setupCache = null;
+    _setupCachedAt = 0;
+
+    try {
+      // Re-read secrets.env so a freshly saved DATABASE_URL is visible without
+      // a restart. dotenv-io will not clobber pre-set process.env entries.
+      try {
+        const secrets = _dotenv.readSecrets();
+        for (const [k, v] of Object.entries(secrets)) {
+          if (process.env[k] === undefined || process.env[k] === '') {
+            process.env[k] = v;
+          }
+        }
+      } catch (_err) { /* optional refresh — fall back to explicit lookup */ }
+
+      const databaseUrl = _migrationRunner.resolveDatabaseUrl(req.body && req.body.databaseUrl);
+      if (!databaseUrl) {
+        _migrateInFlight = false;
+        return res.status(400).json({
+          ok: false,
+          error: 'DATABASE_URL not set. Save credentials in the setup wizard first.'
+        });
+      }
+
+      const total = _migrationRunner.listAllMigrations().length;
+      console.log(`[setup] /api/setup/migrate starting (${total} migrations)`);
+
+      const events = [];
+      const result = await _migrationRunner.runAll({
+        databaseUrl,
+        onProgress: (event) => {
+          events.push(event);
+          if (event.type === 'step' && event.status === 'running') {
+            console.log(`[setup] Migration ${event.index}/${event.total}: ${event.file}...`);
+          } else if (event.type === 'step' && event.status === 'done') {
+            console.log(`[setup] Migration ${event.index}/${event.total}: ${event.file} ✓ (${event.elapsedMs}ms)`);
+          } else if (event.type === 'step' && event.status === 'failed') {
+            console.error(`[setup] Migration ${event.index}/${event.total}: ${event.file} ✗ ${event.error}`);
+          }
+        }
+      });
+
+      console.log(`[setup] Migrations ${result.ok ? 'complete' : 'halted'} (${result.applied}/${result.total} applied)`);
+      res.json({ ok: result.ok, ...result, events });
+    } catch (err) {
+      console.error('[setup] /api/setup/migrate failed:', err.message);
+      res.status(500).json({ ok: false, error: err.message, code: err.code || null });
+    } finally {
+      _migrateInFlight = false;
+    }
+  });
+
   // GET /api/sessions - list all active sessions
   app.get('/api/sessions', (req, res) => {
     res.json(sessions.getAll());
@@ -973,6 +1139,193 @@ function createServer(config) {
   return { app, server, wss, sessions, rag, db, transcriptWriter };
 }
 
+// ==================== Setup-configure helpers (Sprint 23 T2) ====================
+// Scoped to module level so they can be unit tested without spinning the server.
+// Each validator resolves to { ok: boolean, detail: string } — never throws.
+
+function validateSupabase(url, key) {
+  return new Promise((resolve) => {
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch (err) {
+      return resolve({ ok: false, detail: `invalid URL: ${err.message}` });
+    }
+    const client = parsed.protocol === 'http:' ? http : https;
+    const probePath = '/rest/v1/';
+    const req = client.request({
+      protocol: parsed.protocol,
+      hostname: parsed.hostname,
+      port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+      path: probePath,
+      method: 'GET',
+      headers: {
+        apikey: key,
+        Authorization: `Bearer ${key}`
+      },
+      timeout: 8000
+    }, (r) => {
+      let body = '';
+      r.on('data', (c) => { body += c; });
+      r.on('end', () => {
+        // 200 = PostgREST OpenAPI doc served, 404 = URL reachable but no doc —
+        // both indicate the host + key passed the edge auth check.
+        if (r.statusCode === 200 || r.statusCode === 404) {
+          resolve({ ok: true, detail: `Supabase reachable (HTTP ${r.statusCode})` });
+        } else if (r.statusCode === 401 || r.statusCode === 403) {
+          resolve({ ok: false, detail: `Authentication failed (HTTP ${r.statusCode}) — check service role key` });
+        } else {
+          resolve({ ok: false, detail: `Unexpected response HTTP ${r.statusCode}` });
+        }
+      });
+    });
+    req.on('error', (err) => resolve({ ok: false, detail: err.message }));
+    req.on('timeout', () => { req.destroy(); resolve({ ok: false, detail: 'timeout after 8s' }); });
+    req.end();
+  });
+}
+
+function validateOpenAI(key) {
+  return new Promise((resolve) => {
+    const payload = JSON.stringify({
+      model: 'text-embedding-3-small',
+      input: 'termdeck setup test'
+    });
+    const req = https.request({
+      hostname: 'api.openai.com',
+      port: 443,
+      path: '/v1/embeddings',
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${key}`,
+        'Content-Length': Buffer.byteLength(payload)
+      },
+      timeout: 10000
+    }, (r) => {
+      let body = '';
+      r.on('data', (c) => { body += c; });
+      r.on('end', () => {
+        if (r.statusCode === 200) {
+          resolve({ ok: true, detail: 'Embedding test succeeded' });
+          return;
+        }
+        let msg = `HTTP ${r.statusCode}`;
+        try {
+          const parsed = JSON.parse(body);
+          if (parsed && parsed.error && parsed.error.message) msg = parsed.error.message;
+        } catch (_err) { /* ignore body parse */ }
+        resolve({ ok: false, detail: msg });
+      });
+    });
+    req.on('error', (err) => resolve({ ok: false, detail: err.message }));
+    req.on('timeout', () => { req.destroy(); resolve({ ok: false, detail: 'timeout after 10s' }); });
+    req.write(payload);
+    req.end();
+  });
+}
+
+async function validateDatabase(connStr) {
+  let pgMod;
+  try { pgMod = require('pg'); } catch (err) { pgMod = null; }
+  if (!pgMod) return { ok: false, detail: 'pg module not installed' };
+
+  const pool = new pgMod.Pool({
+    connectionString: connStr,
+    max: 1,
+    connectionTimeoutMillis: 6000
+  });
+  try {
+    const t0 = Date.now();
+    const r = await pool.query('SELECT 1 AS ok');
+    const ms = Date.now() - t0;
+    if (r.rows[0] && r.rows[0].ok === 1) {
+      return { ok: true, detail: `connected in ${ms}ms` };
+    }
+    return { ok: false, detail: 'unexpected query result' };
+  } catch (err) {
+    return { ok: false, detail: err.message };
+  } finally {
+    await pool.end().catch(() => {});
+  }
+}
+
+function buildSecretsEnv(vars) {
+  const secretsPath = path.join(os.homedir(), '.termdeck', 'secrets.env');
+  const existing = {};
+  if (fs.existsSync(secretsPath)) {
+    try {
+      const raw = fs.readFileSync(secretsPath, 'utf-8');
+      for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) continue;
+        const eq = trimmed.indexOf('=');
+        if (eq === -1) continue;
+        const k = trimmed.slice(0, eq).trim();
+        if (!k) continue;
+        let v = trimmed.slice(eq + 1).trim();
+        if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+          v = v.slice(1, -1);
+        }
+        existing[k] = v;
+      }
+    } catch (err) {
+      console.warn('[setup] Could not parse existing secrets.env:', err.message);
+    }
+  }
+  const merged = { ...existing };
+  for (const [k, v] of Object.entries(vars)) {
+    if (v != null && v !== '') merged[k] = v;
+  }
+  const lines = [
+    '# TermDeck secrets — written by setup wizard',
+    '# Do not commit this file.',
+    ''
+  ];
+  for (const [k, v] of Object.entries(merged)) {
+    const needsQuote = /[\s#"']/.test(v);
+    lines.push(needsQuote ? `${k}="${String(v).replace(/"/g, '\\"')}"` : `${k}=${v}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+function updateConfigYamlForRag(runningConfig) {
+  const yaml = require('yaml');
+  const configPath = path.join(os.homedir(), '.termdeck', 'config.yaml');
+  let parsed = {};
+  if (fs.existsSync(configPath)) {
+    try {
+      parsed = yaml.parse(fs.readFileSync(configPath, 'utf-8')) || {};
+    } catch (err) {
+      console.warn('[setup] config.yaml parse failed, starting from empty:', err.message);
+      parsed = {};
+    }
+  }
+  parsed.rag = parsed.rag || {};
+  parsed.rag.enabled = true;
+  if (!parsed.rag.supabaseUrl) parsed.rag.supabaseUrl = '${SUPABASE_URL}';
+  if (!parsed.rag.supabaseKey) parsed.rag.supabaseKey = '${SUPABASE_SERVICE_ROLE_KEY}';
+  if (!parsed.rag.openaiApiKey) parsed.rag.openaiApiKey = '${OPENAI_API_KEY}';
+  if (!parsed.rag.anthropicApiKey) parsed.rag.anthropicApiKey = '${ANTHROPIC_API_KEY}';
+
+  if (fs.existsSync(configPath)) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    try { fs.copyFileSync(configPath, `${configPath}.${ts}.bak`); } catch (err) {
+      console.warn('[setup] config.yaml backup failed:', err.message);
+    }
+  }
+  fs.writeFileSync(configPath, yaml.stringify(parsed), 'utf-8');
+
+  if (runningConfig) {
+    runningConfig.rag = runningConfig.rag || {};
+    runningConfig.rag.enabled = true;
+    runningConfig.rag.supabaseUrl = process.env.SUPABASE_URL;
+    runningConfig.rag.supabaseKey = process.env.SUPABASE_SERVICE_ROLE_KEY;
+    runningConfig.rag.openaiApiKey = process.env.OPENAI_API_KEY;
+    if (process.env.ANTHROPIC_API_KEY) runningConfig.rag.anthropicApiKey = process.env.ANTHROPIC_API_KEY;
+  }
+}
+
 // Start server
 if (require.main === module) {
   // Minimal flag parsing for direct-invocation users (the CLI wrapper has its own).

package/packages/server/src/setup/index.js

@@ -10,5 +10,6 @@ module.exports = {
   yaml: require('./yaml-io'),
   supabaseUrl: require('./supabase-url'),
   migrations: require('./migrations'),
-  pgRunner: require('./pg-runner')
+  pgRunner: require('./pg-runner'),
+  migrationRunner: require('./migration-runner')
 };

package/packages/server/src/setup/migration-runner.js

@@ -0,0 +1,136 @@
+// Unified migration runner for the setup wizard and `termdeck init --mnestra`.
+//
+// Applies the full 7-migration bootstrap sequence in order:
+//   1-6. Mnestra schema + RPCs (bundled under ./mnestra-migrations)
+//   7.   termdeck_transcripts table (repo root: config/transcript-migration.sql)
+//
+// Every migration file is authored with IF NOT EXISTS / CREATE OR REPLACE so
+// re-running the sequence is a no-op on an already-configured database.
+
+const fs = require('fs');
+const path = require('path');
+
+const dotenv = require('./dotenv-io');
+const migrations = require('./migrations');
+const pgRunner = require('./pg-runner');
+
+const TRANSCRIPT_MIGRATION = path.resolve(
+  __dirname, '..', '..', '..', '..', 'config', 'transcript-migration.sql'
+);
+
+// Build the ordered list of absolute migration file paths. The transcript
+// migration lives outside the Mnestra bundle so we tack it on at the end.
+function listAllMigrations() {
+  const mnestra = migrations.listMnestraMigrations();
+  const files = mnestra.slice();
+  if (fs.existsSync(TRANSCRIPT_MIGRATION)) {
+    files.push(TRANSCRIPT_MIGRATION);
+  }
+  return files;
+}
+
+// Resolve DATABASE_URL from (in order) an explicit argument, process.env, or
+// a freshly-loaded ~/.termdeck/secrets.env. The wizard path needs the third
+// branch because it may have just written secrets.env without restarting the
+// server, so process.env won't have picked up the new value.
+function resolveDatabaseUrl(explicit) {
+  if (explicit) return explicit;
+  if (process.env.DATABASE_URL) return process.env.DATABASE_URL;
+  const secrets = dotenv.readSecrets();
+  return secrets.DATABASE_URL || null;
+}
+
+// Run the full migration sequence. Options:
+//   - databaseUrl:   override URL (otherwise resolved per the rules above)
+//   - onProgress:    (event) => void, fires for 'start'|'step'|'done'|'error'
+// Returns { ok, applied, failed, results } where `results` is one entry per
+// migration file: { file, ok, elapsedMs, error? }.
+async function runAll({ databaseUrl, onProgress } = {}) {
+  const url = resolveDatabaseUrl(databaseUrl);
+  if (!url) {
+    const err = new Error(
+      'DATABASE_URL not set. Save credentials in the setup wizard (or set it in ~/.termdeck/secrets.env) and try again.'
+    );
+    err.code = 'NO_DATABASE_URL';
+    throw err;
+  }
+
+  const files = listAllMigrations();
+  if (files.length === 0) {
+    const err = new Error('No migration files found. TermDeck install looks corrupted.');
+    err.code = 'NO_MIGRATIONS';
+    throw err;
+  }
+
+  const emit = (event) => { if (typeof onProgress === 'function') onProgress(event); };
+
+  emit({ type: 'start', total: files.length });
+
+  let client;
+  try {
+    client = await pgRunner.connect(url);
+  } catch (err) {
+    emit({ type: 'error', phase: 'connect', message: err.message });
+    throw err;
+  }
+
+  const results = [];
+  let appliedCount = 0;
+  let failedCount = 0;
+
+  try {
+    for (let i = 0; i < files.length; i++) {
+      const file = files[i];
+      const base = path.basename(file);
+      const stepIdx = i + 1;
+      emit({ type: 'step', index: stepIdx, total: files.length, file: base, status: 'running' });
+
+      const result = await pgRunner.applyFile(client, file);
+      const entry = {
+        file: base,
+        ok: result.ok,
+        elapsedMs: result.elapsedMs,
+        ...(result.error ? { error: result.error } : {})
+      };
+      results.push(entry);
+
+      if (result.ok) {
+        appliedCount++;
+        emit({
+          type: 'step',
+          index: stepIdx,
+          total: files.length,
+          file: base,
+          status: 'done',
+          elapsedMs: result.elapsedMs
+        });
+      } else {
+        failedCount++;
+        emit({
+          type: 'step',
+          index: stepIdx,
+          total: files.length,
+          file: base,
+          status: 'failed',
+          error: result.error
+        });
+        // Stop on first failure — later migrations usually depend on earlier ones.
+        break;
+      }
+    }
+  } finally {
+    try { await client.end(); } catch (_err) { /* ignore */ }
+  }
+
+  const ok = failedCount === 0 && appliedCount === files.length;
+  emit({ type: 'done', ok, applied: appliedCount, failed: failedCount, total: files.length });
+
+  return { ok, applied: appliedCount, failed: failedCount, total: files.length, results };
+}
+
+module.exports = {
+  listAllMigrations,
+  resolveDatabaseUrl,
+  runAll,
+  TRANSCRIPT_MIGRATION
+};