fraim 2.0.129 → 2.0.130

package/dist/src/first-run/types.js

@@ -16,9 +16,8 @@ exports.derivePrimaryButtonLabel = derivePrimaryButtonLabel;
 exports.FIRST_RUN_ROW_IDS = [
     'node',
     'git',
+    'fraim',
     'agent',
-    'agent-login',
-    'project',
 ];
 exports.FIRST_RUN_PROMPT = 'Onboard this project';
 exports.FIRST_RUN_RESOURCES_URL = 'https://fraimworks.ai/resources.html';
@@ -60,36 +59,26 @@ function createInitialRows() {
     return [
         { id: 'node', label: 'Node.js', status: 'pending', verb: "we'll install" },
         { id: 'git', label: 'git', status: 'pending', verb: "we'll install" },
-        { id: 'agent', label: 'AI agent', status: 'pending', verb: "we'll set up Claude Code (recommended)" },
-        { id: 'agent-login', label: 'Sign in', status: 'pending', verb: "you'll sign in after install" },
-        { id: 'project', label: 'Project folder', status: 'pending', verb: 'pick a folder where FRAIM should work' },
+        { id: 'fraim', label: 'FRAIM', status: 'pending', verb: "we'll set up FRAIM" },
+        { id: 'agent', label: 'AI Employees', status: 'pending', verb: "we'll check for AI Employees" },
     ];
 }
 /**
  * State-derived primary-button label per R2.0. NEVER audience-derived.
  *
- * - "Open Hub": every row is ok, OR the project row is ok and every other
- *   row is ok-or-manual-required (i.e. the user explicitly handed
- *   themselves any remaining steps via Skip-and-continue, and there is no
- *   forward action the wizard can take).
+ * - "Get Started": every row is ok, OR every row is ok-or-manual-required
+ *   (skip-path: user explicitly handled remaining steps via Skip-and-continue).
+ *   Clicking "Get Started" shows the user-type selection screen (#367).
  * - "Continue": at least one row is ok and there is still wizard work to do.
  * - "Set up FRAIM": no rows ok yet.
- *
- * Manual-required is treated as "user-handled" for the Open-Hub gate so a
- * Skip-and-continue path doesn't strand the user on a dead-end Continue
- * button. It is treated as "in-progress / waiting on user" for the
- * Continue gate so a fresh state with only the manual project row open
- * still asks the user to continue picking a folder.
  */
 function derivePrimaryButtonLabel(rows) {
-    const projectRow = rows.find((row) => row.id === 'project');
-    const projectOk = projectRow?.status === 'ok';
     const allOk = rows.every((row) => row.status === 'ok');
     if (allOk)
-        return 'Open Hub';
-    // User-skipped path: project ok and every other row ok-or-manual-required.
-    if (projectOk && rows.every((row) => row.status === 'ok' || row.status === 'manual-required')) {
-        return 'Open Hub';
+        return 'Get Started';
+    // Skip-path: every row is ok-or-manual-required — nothing left for the wizard.
+    if (rows.every((row) => row.status === 'ok' || row.status === 'manual-required')) {
+        return 'Get Started';
     }
     if (rows.some((row) => row.status === 'ok'))
         return 'Continue';

package/dist/src/local-mcp-server/stdio-server.js

@@ -237,27 +237,21 @@ class FraimTemplateEngine {
         }
     }
     buildMissingConfigNotice(path, action) {
-        const metadata = FraimTemplateEngine.CONFIG_CONTEXT_METADATA[path];
-        const label = metadata?.label || `config value \`${path}\``;
-        const onboardingHint = metadata?.onboardingHint || `provide \`${path}\` in \`fraim/config.json\``;
+        const configReference = `\`${path}\``;
+        const onboardingHint = `set ${configReference} in \`fraim/config.json\``;
         if (action === 'REQUIRE') {
             return {
                 action,
                 path,
-                message: `${this.capitalizeFirst(label)} is required for this task but is not configured. Invoke the manager \`project-onboarding\` job and ${onboardingHint} before continuing.`
+                message: `Required config value ${configReference} is not configured. Invoke the manager \`project-onboarding\` job and ${onboardingHint} before continuing.`
             };
         }
         return {
             action,
             path,
-            message: `${this.capitalizeFirst(label)} is not configured. Invoke the manager \`project-onboarding\` job and ${onboardingHint}.`
+            message: `Config value ${configReference} is not configured. Invoke the manager \`project-onboarding\` job and ${onboardingHint}.`
         };
     }
-    capitalizeFirst(value) {
-        if (!value)
-            return value;
-        return value.charAt(0).toUpperCase() + value.slice(1);
-    }
     loadDeliveryTemplates() {
         if (this.deliveryTemplatesCache)
             return this.deliveryTemplatesCache;
@@ -362,24 +356,6 @@ class FraimTemplateEngine {
 }
 exports.FraimTemplateEngine = FraimTemplateEngine;
 FraimTemplateEngine.CONFIG_TEMPLATE_ACTIONS = new Set(['INFORM', 'NO_OP', 'REQUIRE']);
-FraimTemplateEngine.CONFIG_CONTEXT_METADATA = {
-    'customizations.architectureDoc': {
-        label: 'project-specific architecture document',
-        onboardingHint: 'provide the architecture document path in `fraim/config.json`'
-    },
-    'customizations.designSystem.path': {
-        label: 'project-specific design system',
-        onboardingHint: 'provide the design system path in `fraim/config.json`'
-    },
-    compliance: {
-        label: 'project compliance configuration',
-        onboardingHint: 'record the project compliance requirements in `fraim/config.json`'
-    },
-    'compliance.regulations': {
-        label: 'project compliance regulations',
-        onboardingHint: 'record the applicable compliance regulations in `fraim/config.json`'
-    }
-};
 FraimTemplateEngine.PROXY_ACTION_PREFIX = 'proxy.action.';
 FraimTemplateEngine.ISSUE_ACTIONS = new Set([
     'get_issue',
@@ -403,6 +379,7 @@ class FraimLocalMCPServer {
         this.engine = null;
         this.otlpServer = null;
         this.isShutdown = false;
+        this.mentoringResponseCache = null;
         this.writer = writer || process.stdout.write.bind(process.stdout);
         this.remoteUrl = process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
         this.apiKey = this.loadApiKey();
@@ -1710,6 +1687,14 @@ class FraimLocalMCPServer {
                     const mentor = this.getMentor(requestSessionId);
                     const tutoringResponse = await mentor.handleMentoringRequest(args);
                     this.log(`✅ Local seekMentoring succeeded for ${args.jobName}:${args.currentPhase}`);
+                    // Store response data for usage tracking (Bug fix: capture nextPhase and jobId)
+                    if (!this.mentoringResponseCache) {
+                        this.mentoringResponseCache = new Map();
+                    }
+                    this.mentoringResponseCache.set(requestId, {
+                        nextPhase: tutoringResponse.nextPhase,
+                        jobId: args.jobId || requestSessionId // Use jobId from args, fallback to sessionId
+                    });
                     // Quality enforcement (Issue #251).
                     //
                     // The local proxy owns seekMentoring for personalized-job support.
@@ -2015,7 +2000,7 @@ class FraimLocalMCPServer {
             return;
         }
         const toolName = request.params?.name;
-        const args = request.params?.arguments || {};
+        let args = request.params?.arguments || {};
         const requestSessionId = this.extractSessionIdFromRequest(request);
         if (toolName && requestSessionId) {
             const success = !response.error;
@@ -2023,6 +2008,20 @@ class FraimLocalMCPServer {
             if (!this.repoInfo) {
                 this.detectRepoInfo();
             }
+            // Bug fix: Enrich seekMentoring args with response data
+            if (toolName === 'seekMentoring' && this.mentoringResponseCache) {
+                const requestId = request.id;
+                const cachedResponse = this.mentoringResponseCache.get(requestId);
+                if (cachedResponse) {
+                    args = {
+                        ...args,
+                        nextPhase: cachedResponse.nextPhase,
+                        jobId: cachedResponse.jobId
+                    };
+                    this.mentoringResponseCache.delete(requestId); // Clean up
+                    this.log(`📊 Enriched seekMentoring args with nextPhase=${cachedResponse.nextPhase}, jobId=${cachedResponse.jobId}`);
+                }
+            }
             // Capture the current queue size before collection
             const beforeCount = this.usageCollector.getEventCount();
             try {

package/dist/src/local-mcp-server/usage-collector.js

@@ -82,6 +82,7 @@ class UsageCollector {
             repoIdentifier: this.repoIdentifier || undefined,
             agentName: this.agentName || undefined,
             agentModel: this.agentModel || undefined,
+            jobId: args.jobId || undefined, // Bug fix: capture jobId from enriched args
             args: Object.keys(analyticsArgs).length > 0 ? analyticsArgs : undefined
         };
         this.events.push(event);
@@ -117,6 +118,8 @@ class UsageCollector {
                     analyticsArgs.currentPhase = args.currentPhase;
                 if (args.status)
                     analyticsArgs.status = args.status;
+                if (args.nextPhase !== undefined)
+                    analyticsArgs.nextPhase = args.nextPhase; // Bug fix: capture nextPhase
                 const mentoringJobName = UsageCollector.resolveMentoringJobName(args);
                 if (mentoringJobName !== 'unknown')
                     analyticsArgs.jobName = mentoringJobName;

package/index.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * FRAIM Framework - Smart Entry Point

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.129",
+  "version": "2.0.130",
   "description": "FRAIM CLI - Framework for Rigor-based AI Management (alias for fraim-framework)",
   "main": "index.js",
   "bin": {
@@ -10,19 +10,19 @@
   "scripts": {
     "dev": "tsx --watch src/fraim-mcp-server.ts > server.log 2>&1",
     "dev:prod": "npm run build && node dist/src/fraim-mcp-server.js > server.log 2>&1",
-    "build": "tsc && npm run build:stubs && npm run build:fraim-brain && node scripts/copy-registry.js && node -e \"require('fs').copyFileSync('src/core/types.ts', 'registry/templates/manager/fraim-config-schema.ts')\" && npm run validate:registry && npm run validate:fraim-pro-assets && tsx scripts/validate-purity.ts",
+    "build": "tsx scripts/build-fraim-config-schema-template.ts && npm run typecheck:scripts && tsc && npm run build:stubs && npm run build:fraim-brain && node scripts/copy-registry.js && npm run validate:registry && npm run validate:fraim-pro-assets && tsx scripts/validate-purity.ts",
     "build:stubs": "tsx scripts/build-stub-registry.ts",
     "build:fraim-brain": "node scripts/generate-fraim-brain.js",
     "test-all": "npm run test && npm run test:isolated && npm run test:ui",
     "test": "node scripts/test-with-server.js",
-    "test:isolated": "npx tsx --test --test-reporter=spec tests/isolated/test-*.ts",
+    "test:isolated": "npx tsx --test --test-concurrency=1 --test-reporter=spec tests/isolated/test-*.ts",
     "test:smoke": "node scripts/test-with-server.js --tags=smoke",
     "test:coverage": "node scripts/test-with-server.js --tags=smoke --coverage",
     "test:stripe": "node scripts/test-with-server.js tests/test-stripe-payment-complete.ts",
     "test:stripe:ui": "playwright test tests/ui/test-payment-ui.spec.ts",
     "test:perf": "node scripts/test-with-server.js tests/performance/analytics-perf.ts",
-    "test:ui": "playwright test",
-    "test:ui:headed": "playwright test --headed",
+    "test:ui": "playwright test --workers=1",
+    "test:ui:headed": "playwright test --headed --workers=1",
     "hub:desktop": "npm run build && electron dist/src/ai-hub/desktop-main.js",
     "start:fraim": "tsx src/fraim-mcp-server.ts",
     "dev:fraim": "tsx --watch src/fraim-mcp-server.ts",
@@ -44,6 +44,7 @@
     "publish-fraim-only": "node scripts/publish-fraim.js",
     "publish-both-manual": "node scripts/publish-both.js",
     "validate:registry": "tsx scripts/verify-registry-paths.ts && npm run validate:jobs && npm run validate:skills && npm run validate:registry-references && npm run validate:platform-agnostic && npm run validate:template-namespaces && npm run validate:config-fallbacks && npm run validate:bootstrap-config-coverage && npm run validate:provider-action-mappings && npm run validate:fidelity && npm run validate:config-tokens && npm run validate:brain-mapping && npm run validate:template-syntax",
+    "typecheck:scripts": "tsc -p tsconfig.scripts.json --pretty false",
     "validate:registry-references": "tsx scripts/validate-registry-references.ts",
     "validate:brain-mapping": "tsx scripts/validate-brain-mapping.ts",
     "validate:fraim-pro-assets": "tsx scripts/validate-fraim-pro-assets.ts",
@@ -56,6 +57,7 @@
     "validate:provider-action-mappings": "tsx scripts/validate-provider-action-mappings.ts",
     "validate:fidelity": "tsx scripts/validate-fidelity.ts",
     "validate:config-tokens": "tsx scripts/validate-config-tokens.ts",
+    "validate:workspace-config": "tsx scripts/validate-workspace-config.ts",
     "validate:template-syntax": "tsx scripts/validate-template-syntax.ts",
     "validate:backup": "bash scripts/backup/validate-pitr-restore.sh"
   },

package/public/ai-hub/script.js

@@ -367,12 +367,22 @@ let renderedTrackerKey = null;
 function renderTracker(conv) {
   const tracker = els['tracker'];
   if (!tracker) return;
-  const stages = (conv.run && Array.isArray(conv.run.stages)) ? conv.run.stages : [];
+
+  // Issue #357: Defensive check - ensure conv.run exists before accessing stages
+  if (!conv.run) {
+    // Run hasn't been created yet or hasn't been folded into conversation
+    tracker.hidden = true;
+    renderedTrackerKey = null;
+    return;
+  }
+
+  const stages = Array.isArray(conv.run.stages) ? conv.run.stages : [];
   if (stages.length === 0) {
     tracker.hidden = true;
     renderedTrackerKey = null;
     return;
   }
+
   // Cache key so we only rebuild the DOM when the stage data changes.
   const key = stages.map((s) => `${s.phaseId}:${s.state}`).join('|') +
     '#' + (conv.run.currentPhase || '');
@@ -1240,11 +1250,22 @@ function wireEvents() {
   loadConversationsFromStorage();
   wirePopovers();
   wireEvents();
+
+  const urlParams = new URLSearchParams(window.location.search);
+  const isFirstRun = urlParams.get('firstRun') === 'true';
+
   try {
     await loadBootstrap();
   } catch (error) {
     showStatus(error.message, true);
+    return;
+  }
+
+  if (isFirstRun) {
+    renderFirstRunLanding();
+    return;
   }
+
   // If an active conversation belongs to the loaded project and is still running, resume polling.
   const conv = activeConversation();
   if (conv && conv.projectPath === state.projectPath) {
@@ -1255,3 +1276,168 @@ function wireEvents() {
     renderActive();
   }
 })();
+
+function renderFirstRunLanding() {
+  // Show first-run onboarding screen over the normal Hub UI.
+  // The user picks a project folder here; clicking Start fires the
+  // Project Onboarding job automatically (R4.3/R4.4).
+  const existing = document.getElementById('fraim-first-run-landing');
+  if (existing) existing.remove();
+
+  const overlay = document.createElement('div');
+  overlay.id = 'fraim-first-run-landing';
+  overlay.style.cssText = [
+    'position:fixed;inset:0;z-index:1000;',
+    'background:var(--bg,#f4f6f2);',
+    'display:flex;align-items:center;justify-content:center;',
+    'font-family:inherit;',
+  ].join('');
+
+  const card = document.createElement('div');
+  card.style.cssText = [
+    'background:#fff;border:1px solid var(--line,#e3e8df);border-radius:14px;',
+    'padding:32px;max-width:480px;width:90%;display:flex;flex-direction:column;gap:16px;',
+    'box-shadow:0 1px 2px rgba(20,40,30,.04);',
+  ].join('');
+
+  const title = document.createElement('h1');
+  title.textContent = "Let's get started";
+  title.style.cssText = 'font-size:22px;font-weight:600;margin:0;';
+  card.appendChild(title);
+
+  const desc = document.createElement('p');
+  desc.textContent = "Let's introduce your AI employees to their first project.";
+  desc.style.cssText = 'color:var(--muted,#6b7a72);margin:0;font-size:15px;';
+  card.appendChild(desc);
+
+  const folderLabel = document.createElement('label');
+  folderLabel.textContent = 'Project folder';
+  folderLabel.style.cssText = 'font-size:13px;color:var(--muted,#6b7a72);font-weight:600;';
+  card.appendChild(folderLabel);
+
+  const pickerRow = document.createElement('div');
+  pickerRow.style.cssText = 'display:flex;gap:8px;align-items:center;';
+
+  const folderInput = document.createElement('input');
+  folderInput.type = 'text';
+  folderInput.placeholder = 'Choose a folder…';
+  folderInput.readOnly = true;
+  folderInput.style.cssText = [
+    'flex:1;border:1px solid var(--line,#e3e8df);border-radius:8px;',
+    'padding:9px 12px;font-size:14px;color:var(--muted,#6b7a72);',
+    'background:var(--soft,#f7faf6);',
+  ].join('');
+  if (state.projectPath) {
+    folderInput.value = state.projectPath;
+    folderInput.style.color = 'var(--text,#1f2a24)';
+    folderInput.style.background = '#fff';
+  }
+
+  const browseBtn = document.createElement('button');
+  browseBtn.type = 'button';
+  browseBtn.textContent = 'Browse…';
+  browseBtn.style.cssText = [
+    'border:1px solid var(--line,#e3e8df);border-radius:8px;',
+    'background:transparent;color:var(--muted,#6b7a72);',
+    'padding:9px 14px;font-size:13px;font-weight:600;cursor:pointer;',
+  ].join('');
+  browseBtn.addEventListener('click', async () => {
+    try {
+      const response = await fetch('/api/ai-hub/project-path/pick', { method: 'POST' });
+      if (response.status === 204) return;
+      const payload = await response.json();
+      if (!response.ok) throw new Error(payload.error || 'Could not pick folder.');
+      if (payload.path) {
+        await loadBootstrap(payload.path);
+        folderInput.value = state.projectPath;
+        folderInput.style.color = 'var(--text,#1f2a24)';
+        folderInput.style.background = '#fff';
+        startBtn.disabled = false;
+        startBtn.style.opacity = '1';
+      }
+    } catch (err) {
+      showStatus(err.message, true);
+    }
+  });
+
+  pickerRow.appendChild(folderInput);
+  pickerRow.appendChild(browseBtn);
+  card.appendChild(pickerRow);
+
+  const startBtn = document.createElement('button');
+  startBtn.type = 'button';
+  startBtn.textContent = 'Start onboarding →';
+  startBtn.disabled = !state.projectPath;
+  startBtn.style.cssText = [
+    'background:var(--accent,#3d8a6e);color:#fff;border:none;border-radius:8px;',
+    'padding:11px 20px;font-size:14px;font-weight:600;cursor:pointer;',
+    'opacity:' + (state.projectPath ? '1' : '0.5') + ';',
+    'transition:opacity .15s;',
+  ].join('');
+  startBtn.addEventListener('click', async () => {
+    if (!state.projectPath) return;
+    startBtn.disabled = true;
+    startBtn.textContent = 'Starting…';
+    overlay.remove();
+    renderActive();
+    // Find the project-onboarding job from bootstrap, fall back to direct POST.
+    const job = (state.bootstrap && state.bootstrap.jobs || []).find((j) => j.id === 'project-onboarding');
+    const employeeId = state.selectedEmployeeId || 'claude';
+    if (job) {
+      await startRun(job, 'Onboard this project', employeeId);
+    } else {
+      // Job not in catalog yet (project not initialized) — POST directly.
+      try {
+        const run = await requestJson('/api/ai-hub/runs', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            projectPath: state.projectPath,
+            hostId: employeeId,
+            jobId: 'project-onboarding',
+            message: 'Onboard this project',
+          }),
+        });
+        const conv = {
+          id: newConversationId(),
+          projectPath: state.projectPath,
+          title: 'Project Onboarding',
+          jobId: 'project-onboarding',
+          jobTitle: 'Project Onboarding',
+          employeeId,
+          runId: run.id,
+          sessionId: run.sessionId || null,
+          status: 'running',
+          messages: [{ role: 'manager', text: 'Onboard this project', at: Date.now() }],
+          events: [],
+          artifacts: [],
+          lastUpdatedAt: Date.now(),
+        };
+        foldRunIntoConversation(conv, run);
+        upsertConversation(conv);
+        state.activeId = conv.id;
+        persistConversations();
+        renderRail();
+        renderActive();
+        startPolling();
+      } catch (err) {
+        showStatus(err.message, true);
+      }
+    }
+  });
+  card.appendChild(startBtn);
+
+  const switchLink = document.createElement('a');
+  switchLink.href = '#';
+  switchLink.textContent = 'Set up in my IDE instead';
+  switchLink.style.cssText = 'font-size:12px;color:var(--muted,#6b7a72);text-decoration:underline;text-align:center;';
+  switchLink.addEventListener('click', (e) => {
+    e.preventDefault();
+    overlay.remove();
+    renderActive();
+  });
+  card.appendChild(switchLink);
+
+  overlay.appendChild(card);
+  document.body.appendChild(overlay);
+}

package/public/first-run/error-frame.js

@@ -1,100 +1,100 @@
-/**
- * R6.1 — unified error-frame renderer.
- *
- * Exposes a single function `renderErrorFrame(frame, onAction)` which returns
- * a DOM Node containing exactly:
- *   - "What we tried" sentence
- *   - "What happened" verbatim stderr (last 12 lines, with a Show-full toggle
- *     that surfaces the rest on demand)
- *   - Up to three actions in fixed order (Retry / Try alternative / Skip and continue)
- *
- * The same renderer must be lifted into public/ai-hub/ in the v2 follow-up
- * (issue #355, "Hub-side error-frame adoption") so bootstrap and Hub share
- * one frame across surfaces.
- */
-(function () {
-  'use strict';
-
-  function escapeText(text) {
-    if (typeof text !== 'string') return '';
-    return text;
-  }
-
-  function truncateToLastLines(text, lineCount) {
-    if (typeof text !== 'string') return { visible: '', hidden: '' };
-    const lines = text.split(/\r?\n/);
-    if (lines.length <= lineCount) {
-      return { visible: text, hidden: '' };
-    }
-    const visible = lines.slice(-lineCount).join('\n');
-    const hidden = lines.slice(0, -lineCount).join('\n');
-    return { visible, hidden };
-  }
-
-  function renderErrorFrame(frame, onAction) {
-    const root = document.createElement('div');
-    root.className = 'error-frame';
-    root.setAttribute('data-testid', 'error-frame');
-    root.setAttribute('role', 'alert');
-
-    const whatTried = document.createElement('div');
-    whatTried.className = 'what-tried';
-    whatTried.setAttribute('data-testid', 'error-what-tried');
-    whatTried.textContent = escapeText(frame.whatTried || '');
-    root.appendChild(whatTried);
-
-    // Optional plain-language hint rendered ABOVE the verbatim stderr so
-    // a non-tech user reads "your install key was rejected — get a new
-    // one" before they parse `Request failed with status code 401`.
-    if (frame.hint) {
-      const hint = document.createElement('div');
-      hint.className = 'error-hint';
-      hint.setAttribute('data-testid', 'error-hint');
-      hint.textContent = escapeText(frame.hint);
-      root.appendChild(hint);
-    }
-
-    const { visible, hidden } = truncateToLastLines(frame.whatHappened || '', 12);
-    const whatHappened = document.createElement('pre');
-    whatHappened.className = 'what-happened';
-    whatHappened.setAttribute('data-testid', 'error-what-happened');
-    whatHappened.textContent = visible;
-    root.appendChild(whatHappened);
-
-    if (hidden) {
-      const showFull = document.createElement('button');
-      showFull.type = 'button';
-      showFull.className = 'show-full';
-      showFull.setAttribute('data-testid', 'error-show-full');
-      showFull.textContent = 'Show full output';
-      showFull.addEventListener('click', () => {
-        whatHappened.textContent = (hidden + '\n' + visible).trimEnd();
-        showFull.remove();
-      });
-      root.appendChild(showFull);
-    }
-
-    const actions = Array.isArray(frame.actions) ? frame.actions.slice(0, 3) : [];
-    const actionRow = document.createElement('div');
-    actionRow.className = 'actions';
-    for (const action of actions) {
-      const btn = document.createElement('button');
-      btn.type = 'button';
-      btn.className = 'action';
-      btn.setAttribute('data-testid', 'error-action');
-      btn.setAttribute('data-action-id', action.id);
-      btn.setAttribute('data-variant', action.variant || 'secondary');
-      btn.textContent = action.label || action.id;
-      btn.addEventListener('click', () => {
-        if (typeof onAction === 'function') {
-          onAction(action);
-        }
-      });
-      actionRow.appendChild(btn);
-    }
-    root.appendChild(actionRow);
-    return root;
-  }
-
-  window.FraimErrorFrame = { render: renderErrorFrame };
-})();
+/**
+ * R6.1 — unified error-frame renderer.
+ *
+ * Exposes a single function `renderErrorFrame(frame, onAction)` which returns
+ * a DOM Node containing exactly:
+ *   - "What we tried" sentence
+ *   - "What happened" verbatim stderr (last 12 lines, with a Show-full toggle
+ *     that surfaces the rest on demand)
+ *   - Up to three actions in fixed order (Retry / Try alternative / Skip and continue)
+ *
+ * The same renderer must be lifted into public/ai-hub/ in the v2 follow-up
+ * (issue #355, "Hub-side error-frame adoption") so bootstrap and Hub share
+ * one frame across surfaces.
+ */
+(function () {
+  'use strict';
+
+  function escapeText(text) {
+    if (typeof text !== 'string') return '';
+    return text;
+  }
+
+  function truncateToLastLines(text, lineCount) {
+    if (typeof text !== 'string') return { visible: '', hidden: '' };
+    const lines = text.split(/\r?\n/);
+    if (lines.length <= lineCount) {
+      return { visible: text, hidden: '' };
+    }
+    const visible = lines.slice(-lineCount).join('\n');
+    const hidden = lines.slice(0, -lineCount).join('\n');
+    return { visible, hidden };
+  }
+
+  function renderErrorFrame(frame, onAction) {
+    const root = document.createElement('div');
+    root.className = 'error-frame';
+    root.setAttribute('data-testid', 'error-frame');
+    root.setAttribute('role', 'alert');
+
+    const whatTried = document.createElement('div');
+    whatTried.className = 'what-tried';
+    whatTried.setAttribute('data-testid', 'error-what-tried');
+    whatTried.textContent = escapeText(frame.whatTried || '');
+    root.appendChild(whatTried);
+
+    // Optional plain-language hint rendered ABOVE the verbatim stderr so
+    // a non-tech user reads "your install key was rejected — get a new
+    // one" before they parse `Request failed with status code 401`.
+    if (frame.hint) {
+      const hint = document.createElement('div');
+      hint.className = 'error-hint';
+      hint.setAttribute('data-testid', 'error-hint');
+      hint.textContent = escapeText(frame.hint);
+      root.appendChild(hint);
+    }
+
+    const { visible, hidden } = truncateToLastLines(frame.whatHappened || '', 12);
+    const whatHappened = document.createElement('pre');
+    whatHappened.className = 'what-happened';
+    whatHappened.setAttribute('data-testid', 'error-what-happened');
+    whatHappened.textContent = visible;
+    root.appendChild(whatHappened);
+
+    if (hidden) {
+      const showFull = document.createElement('button');
+      showFull.type = 'button';
+      showFull.className = 'show-full';
+      showFull.setAttribute('data-testid', 'error-show-full');
+      showFull.textContent = 'Show full output';
+      showFull.addEventListener('click', () => {
+        whatHappened.textContent = (hidden + '\n' + visible).trimEnd();
+        showFull.remove();
+      });
+      root.appendChild(showFull);
+    }
+
+    const actions = Array.isArray(frame.actions) ? frame.actions.slice(0, 3) : [];
+    const actionRow = document.createElement('div');
+    actionRow.className = 'actions';
+    for (const action of actions) {
+      const btn = document.createElement('button');
+      btn.type = 'button';
+      btn.className = 'action';
+      btn.setAttribute('data-testid', 'error-action');
+      btn.setAttribute('data-action-id', action.id);
+      btn.setAttribute('data-variant', action.variant || 'secondary');
+      btn.textContent = action.label || action.id;
+      btn.addEventListener('click', () => {
+        if (typeof onAction === 'function') {
+          onAction(action);
+        }
+      });
+      actionRow.appendChild(btn);
+    }
+    root.appendChild(actionRow);
+    return root;
+  }
+
+  window.FraimErrorFrame = { render: renderErrorFrame };
+})();