fraim 2.0.304 → 2.0.306

package/README.md

@@ -313,9 +313,8 @@ Use these defaults:
 - `technical-design` after the spec is approved and you need the implementation plan, file touchpoints, and risk handling.
 - `feature-implementation` for code changes, bug fixes, and documentation updates that should be executed and validated.
 - `test-authoring` when you need reproduction coverage, missing tests, or stronger regression protection before implementation.
-- `browser-application-validation` or `ui-polish-validation` after user-facing UI changes or when the ask is explicitly browser validation.
-- `implementation-feature-review` when you need to verify the delivered behavior matches the feature spec.
-- `implementation-design-review` when you need to verify the code matches the approved technical design.
+- `iterative-quality-improvement` or `ui-polish-validation` after user-facing UI changes or when the ask is explicitly browser validation.
+- `independent-implementation-review` when you need an independent sign-off that the delivered behavior matches both the approved technical design and the feature spec.
 - `issue-retrospective` after the work is complete and you want durable learnings captured.
 
 Typical path for a larger feature:

package/dist/src/cli/commands/sync.js

@@ -293,8 +293,11 @@ const runSync = async (options) => {
         });
         if (result.success) {
             // Local-dev sync bypasses Layer 1 (machine-level sync) below, but scripts
-            // still need to land in ~/.fraim/scripts/ or the reported count is a lie.
+            // and docs still need to land in ~/.fraim/ or the reported counts are a lie.
             await (0, remote_sync_1.syncScriptsToUserDir)(localRegistryFiles);
+            await (0, remote_sync_1.syncDocsToUserDir)(localRegistryFiles);
+            const { ensureUserLevelDependencies: ensureLocalUserLevelDependencies } = await Promise.resolve().then(() => __importStar(require('../setup/user-level-sync')));
+            ensureLocalUserLevelDependencies();
             console.log(chalk_1.default.green(`Successfully synced ${result.employeeJobsSynced} ai-employee jobs, ${result.managerJobsSynced} ai-manager jobs, ${result.skillsSynced} skills, ${result.rulesSynced} rules, ${result.scriptsSynced} scripts, and ${result.docsSynced} docs from local server`));
             const fraimDir = (0, project_fraim_paths_1.getWorkspaceFraimDir)(projectRoot);
             removeLegacyVersionFromConfig(fraimDir);
@@ -354,6 +357,12 @@ const runSync = async (options) => {
     if (scriptsSynced > 0) {
         console.log(chalk_1.default.green(`  Synced ${scriptsSynced} scripts to ~/.fraim/scripts/`));
     }
+    // 1b2. Sync docs to ~/.fraim/docs/ (Issue #1508: machine-level docs, e.g.
+    // TROUBLESHOOTING.md, must exist on disk the same way scripts do)
+    const docsSynced = await (0, remote_sync_1.syncDocsToUserDir)(registryFiles);
+    if (docsSynced > 0) {
+        console.log(chalk_1.default.green(`  Synced ${docsSynced} docs to ~/.fraim/docs/`));
+    }
     // 1c. Refresh org home
     await refreshOrgCache(remoteUrl, apiKey);
     // 1d. Refresh manager home
@@ -361,9 +370,12 @@ const runSync = async (options) => {
     // 1e. Refresh MCP proxy launcher
     const { ensureFraimMcpLatestLauncher } = await Promise.resolve().then(() => __importStar(require('../mcp/fraim-mcp-latest-launcher')));
     ensureFraimMcpLatestLauncher();
-    // 1f. Ensure user-level directories
-    const { ensureUserLevelDirectories } = await Promise.resolve().then(() => __importStar(require('../setup/user-level-sync')));
+    // 1f. Ensure user-level directories and runtime dependencies (Issue #1508:
+    // synced scripts like the DOCX review layer require npm deps such as
+    // adm-zip; a plain sync must install them, not just create directories)
+    const { ensureUserLevelDirectories, ensureUserLevelDependencies } = await Promise.resolve().then(() => __importStar(require('../setup/user-level-sync')));
     ensureUserLevelDirectories();
+    ensureUserLevelDependencies();
     // 1g. Write sync metadata
     writeSyncMetadata('remote', remoteUrl);
     console.log(chalk_1.default.green('✅ Machine-level sync complete.'));

package/dist/src/cli/doctor/checks/scripts-checks.js

@@ -12,8 +12,73 @@ exports.getScriptsChecks = getScriptsChecks;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
+const module_1 = __importDefault(require("module"));
 const child_process_1 = require("child_process");
 const SCRIPTS_DIR = path_1.default.join(os_1.default.homedir(), '.fraim', 'scripts');
+// Conservative static-require extractor: only matches literal
+// require('name') / require("name") calls, not dynamic requires or imports.
+const STATIC_REQUIRE_PATTERN = /require\(\s*['"]([^'"]+)['"]\s*\)/g;
+/**
+ * Recursively list .js/.cjs files under a directory.
+ */
+function listNodeScripts(dir) {
+    const results = [];
+    let entries;
+    try {
+        entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        const fullPath = path_1.default.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            // Skip vendored dependency trees. A script that ships its own bundled
+            // library (e.g. ~/.fraim/scripts/lib/node_modules/@scope/pkg/...) is
+            // not itself a FRAIM script requiring dependency resolution — it IS a
+            // resolved dependency. Recursing into it produces false-positive
+            // warnings about that library's own devDependency-only files (e.g. a
+            // benchmark/test file requiring a module never meant to be installed
+            // under ~/.fraim/node_modules). Confirmed against a real machine: see
+            // issue #1508 manual validation.
+            if (entry.name === 'node_modules')
+                continue;
+            results.push(...listNodeScripts(fullPath));
+        }
+        else if (entry.isFile() && (entry.name.endsWith('.js') || entry.name.endsWith('.cjs'))) {
+            results.push(fullPath);
+        }
+    }
+    return results;
+}
+/**
+ * Extract external (non-relative, non-absolute, non-builtin) module names
+ * statically required by a script, using its own directory for resolution.
+ */
+function extractExternalRequires(scriptPath) {
+    let content;
+    try {
+        content = fs_1.default.readFileSync(scriptPath, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const modules = new Set();
+    let match;
+    STATIC_REQUIRE_PATTERN.lastIndex = 0;
+    while ((match = STATIC_REQUIRE_PATTERN.exec(content)) !== null) {
+        const moduleName = match[1];
+        if (moduleName.startsWith('.') ||
+            moduleName.startsWith('/') ||
+            /^[a-zA-Z]:[\\/]/.test(moduleName) ||
+            moduleName.startsWith('node:') ||
+            module_1.default.builtinModules.includes(moduleName)) {
+            continue;
+        }
+        modules.add(moduleName);
+    }
+    return Array.from(modules);
+}
 /**
  * Check if scripts directory exists
  */
@@ -211,6 +276,73 @@ function checkPythonAvailability() {
         }
     };
 }
+/**
+ * Check that synced Node scripts can resolve their external runtime
+ * dependencies (e.g. `require('adm-zip')`) from their own directory.
+ *
+ * Distinguishes delivery (the script file exists) from executability (the
+ * script's require statements actually resolve). Issue #1508: `doctor`
+ * reported the DOCX review scripts healthy while all six threw
+ * `Cannot find module 'adm-zip'` at require time.
+ *
+ * Does not execute the scripts — only statically parses `require(...)`
+ * calls and resolves them the way Node would from the script's directory.
+ */
+function checkNodeScriptDependencies() {
+    return {
+        name: 'Node script dependencies available',
+        category: 'scripts',
+        critical: false,
+        run: async () => {
+            if (!fs_1.default.existsSync(SCRIPTS_DIR)) {
+                return {
+                    status: 'passed',
+                    message: 'No scripts synced — Node dependency check skipped'
+                };
+            }
+            const scripts = listNodeScripts(SCRIPTS_DIR);
+            if (scripts.length === 0) {
+                return {
+                    status: 'passed',
+                    message: 'No Node scripts synced — Node dependency check skipped'
+                };
+            }
+            const unresolved = {};
+            for (const scriptPath of scripts) {
+                const externalModules = extractExternalRequires(scriptPath);
+                const relativeScriptPath = path_1.default.relative(SCRIPTS_DIR, scriptPath);
+                for (const moduleName of externalModules) {
+                    try {
+                        require.resolve(moduleName, { paths: [path_1.default.dirname(scriptPath)] });
+                    }
+                    catch {
+                        if (!unresolved[moduleName])
+                            unresolved[moduleName] = [];
+                        unresolved[moduleName].push(relativeScriptPath);
+                    }
+                }
+            }
+            const unresolvedModules = Object.keys(unresolved);
+            if (unresolvedModules.length === 0) {
+                return {
+                    status: 'passed',
+                    message: `All Node script dependencies resolve (${scripts.length} scripts checked)`,
+                    details: { scriptCount: scripts.length }
+                };
+            }
+            const summary = unresolvedModules
+                .map((moduleName) => `${moduleName} (${unresolved[moduleName].join(', ')})`)
+                .join('; ');
+            return {
+                status: 'warning',
+                message: `Unresolved Node script dependencies: ${summary}`,
+                suggestion: 'Run fraim sync to install user-level runtime dependencies.',
+                command: 'fraim sync',
+                details: { unresolved }
+            };
+        }
+    };
+}
 /**
  * Get all scripts checks
  */
@@ -219,6 +351,7 @@ function getScriptsChecks() {
         checkScriptsDirectoryExists(),
         checkScriptsSynced(),
         checkScriptsExecutable(),
+        checkNodeScriptDependencies(),
         checkPythonAvailability()
     ];
 }

package/dist/src/cli/setup/user-level-sync.js

@@ -69,6 +69,7 @@ const script_sync_utils_1 = require("../utils/script-sync-utils");
  */
 const USER_LEVEL_RUNTIME_DEPS = {
     'node-edge-tts': '*', // used by scripts/author-audio.js
+    'adm-zip': '^0.6.0', // used by scripts/communication/*.js (DOCX review layer) — matches root/packages/* manifests
 };
 /**
  * Ensure the user-level FRAIM directory structure exists.

package/dist/src/cli/utils/remote-sync.js

@@ -14,6 +14,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SYNCED_CONTENT_BANNER_MARKER = void 0;
 exports.fetchRegistryFiles = fetchRegistryFiles;
 exports.syncScriptsToUserDir = syncScriptsToUserDir;
+exports.syncDocsToUserDir = syncDocsToUserDir;
 exports.syncFromRemote = syncFromRemote;
 const axios_1 = __importDefault(require("axios"));
 const fs_1 = require("fs");
@@ -188,32 +189,51 @@ async function fetchRegistryFiles(remoteUrl, apiKey) {
     return response.data.files || [];
 }
 /**
- * Sync script files to the user-level ~/.fraim/scripts/ directory.
- * Extracted from syncFromRemote so it can run without a project root.
+ * Sync a registry file subset (filtered by `type`) into a machine-level
+ * `~/.fraim/<subdir>/` directory: clean that directory, then write each
+ * matching file. Shared by syncScriptsToUserDir and syncDocsToUserDir so the
+ * clean-then-write and path-safety logic exists in exactly one place.
  */
-async function syncScriptsToUserDir(files) {
-    const scriptFiles = files.filter(f => f.type === 'script');
-    if (scriptFiles.length === 0)
+async function syncTypedFilesToUserDir(files, type, subdir, label) {
+    const matchingFiles = files.filter(f => f.type === type);
+    if (matchingFiles.length === 0)
         return 0;
     const userDir = (0, script_sync_utils_1.getUserFraimDir)();
-    const scriptsDir = (0, path_1.join)(userDir, 'scripts');
-    if (!(0, fs_1.existsSync)(scriptsDir)) {
-        (0, fs_1.mkdirSync)(scriptsDir, { recursive: true });
+    const targetDir = (0, path_1.join)(userDir, subdir);
+    if (!(0, fs_1.existsSync)(targetDir)) {
+        (0, fs_1.mkdirSync)(targetDir, { recursive: true });
     }
-    cleanDirectory(scriptsDir, (candidatePath) => {
-        if ((0, path_1.resolve)(candidatePath) !== (0, path_1.resolve)(scriptsDir)) {
-            assertPathInsideDirectory(scriptsDir, candidatePath, 'script directory');
+    cleanDirectory(targetDir, (candidatePath) => {
+        if ((0, path_1.resolve)(candidatePath) !== (0, path_1.resolve)(targetDir)) {
+            assertPathInsideDirectory(targetDir, candidatePath, `${label} directory`);
         }
     });
-    for (const file of scriptFiles) {
-        const { filePath } = resolveUserRegistryFile(scriptsDir, file.path, 'script file');
+    for (const file of matchingFiles) {
+        const { filePath } = resolveUserRegistryFile(targetDir, file.path, `${label} file`);
         const fileDir = (0, path_1.dirname)(filePath);
         if (!(0, fs_1.existsSync)(fileDir)) {
             (0, fs_1.mkdirSync)(fileDir, { recursive: true });
         }
         (0, fs_1.writeFileSync)(filePath, file.content, 'utf8');
     }
-    return scriptFiles.length;
+    return matchingFiles.length;
+}
+/**
+ * Sync script files to the user-level ~/.fraim/scripts/ directory.
+ * Extracted from syncFromRemote so it can run without a project root.
+ */
+async function syncScriptsToUserDir(files) {
+    return syncTypedFilesToUserDir(files, 'script', 'scripts', 'script');
+}
+/**
+ * Sync docs files to the user-level ~/.fraim/docs/ directory.
+ * Mirrors syncScriptsToUserDir so machine-level docs (e.g. TROUBLESHOOTING.md)
+ * are materialized on disk the same way machine-level scripts are.
+ * Issue #1508: agent guidance promises ~/.fraim/docs/TROUBLESHOOTING.md exists
+ * after sync, but only project-level fraim/docs/ was ever written.
+ */
+async function syncDocsToUserDir(files) {
+    return syncTypedFilesToUserDir(files, 'docs', 'docs', 'docs');
 }
 /**
  * Sync jobs and scripts from remote FRAIM server

package/dist/src/config/persona-capability-bundles.js

@@ -53,8 +53,8 @@ exports.PERSONA_CAPABILITY_BUNDLES = {
     pam: {
         personaKey: 'pam',
         bundleId: 'persona-pam-core',
-        catalogMetadata: buildCatalogMetadata('pam', ['feature-specification', 'project-plan-creation', 'implementation-feature-review']),
-        protectedJobs: ['feature-specification', 'send-newsletter', 'send-thank-you-notes', 'experiment-tracking', 'project-plan-creation', 'implementation-feature-review', 'scrum-sprint-planning', 'mvp-validation-plan', 'sprint-planning', 'customer-prospect-discovery', 'interview-preparation', 'participant-recruitment', 'process-interview-notes', 'review-customer-development', 'triage-customer-needs'],
+        catalogMetadata: buildCatalogMetadata('pam', ['feature-specification', 'project-plan-creation', 'independent-implementation-review']),
+        protectedJobs: ['feature-specification', 'send-newsletter', 'send-thank-you-notes', 'experiment-tracking', 'project-plan-creation', 'independent-implementation-review', 'scrum-sprint-planning', 'mvp-validation-plan', 'sprint-planning', 'customer-prospect-discovery', 'interview-preparation', 'participant-recruitment', 'process-interview-notes', 'review-customer-development', 'triage-customer-needs'],
         protectedAliases: ['product-management', 'product-spec'],
         defaultHireMode: 'job',
         lockCopy: 'Hire PaM to unlock product-management work for this request.'
@@ -63,7 +63,7 @@ exports.PERSONA_CAPABILITY_BUNDLES = {
         personaKey: 'swen',
         bundleId: 'persona-swen-core',
         catalogMetadata: buildCatalogMetadata('swen', ['feature-implementation', 'technical-design', 'code-refactoring']),
-        protectedJobs: ['feature-implementation', 'technical-design', 'implementation-design-review', 'code-refactoring', 'pr-iteration', 'mobile-app-development', 'cloud-application-deployment', 'cloud-cost-optimization', 'cloud-performance-diagnosis', 'route-llm-spend-to-cloud-credits', 'set-up-cloud-cost-alerts', 'gitlabs-to-github', 'system-migration', 'cross-cloud-migration', 'data-pipeline-design', 'data-quality-monitoring', 'data-platform-architecture', 'write-dev-docs', 'database-schema-design', 'create-architecture', 'project-scaffolding', 'codebase-analysis-and-ideation', 'github-org-setup', 'google-workspace-setup', 'mobile-app-rejection-response', 'mobile-app-submission', 'application-replication-workflow'],
+        protectedJobs: ['feature-implementation', 'technical-design', 'code-refactoring', 'large-refactor-plan', 'pr-iteration', 'mobile-app-development', 'cloud-application-deployment', 'cloud-cost-optimization', 'cloud-performance-diagnosis', 'route-llm-spend-to-cloud-credits', 'set-up-cloud-cost-alerts', 'gitlabs-to-github', 'system-migration', 'cross-cloud-migration', 'data-pipeline-design', 'data-quality-monitoring', 'data-platform-architecture', 'write-dev-docs', 'database-schema-design', 'create-architecture', 'project-scaffolding', 'codebase-analysis-and-ideation', 'github-org-setup', 'google-workspace-setup', 'mobile-app-rejection-response', 'mobile-app-submission', 'application-replication-workflow'],
         protectedAliases: ['software-engineering', 'implementation'],
         defaultHireMode: 'job',
         lockCopy: 'Hire SWEn to unlock software-engineering delivery for this request.'
@@ -71,8 +71,8 @@ exports.PERSONA_CAPABILITY_BUNDLES = {
     qasm: {
         personaKey: 'qasm',
         bundleId: 'persona-qasm-core',
-        catalogMetadata: buildCatalogMetadata('qasm', ['test-authoring', 'browser-application-validation', 'ui-polish-validation']),
-        protectedJobs: ['test-authoring', 'browser-application-validation', 'ui-polish-validation', 'code-quality-assessment', 'test-quality-assessment', 'user-testing-and-bug-bash', 'broken-windows-detection-and-remediation', 'iterative-quality-improvement', 'accessibility-audit', 'api-testing', 'performance-benchmarking'],
+        catalogMetadata: buildCatalogMetadata('qasm', ['test-authoring', 'iterative-quality-improvement', 'ui-polish-validation']),
+        protectedJobs: ['test-authoring', 'ui-polish-validation', 'codebase-quality-assessment', 'test-quality-assessment', 'user-testing-and-bug-bash', 'iterative-quality-improvement', 'accessibility-audit', 'api-testing', 'performance-benchmarking'],
         protectedAliases: ['qa', 'quality-assurance'],
         defaultHireMode: 'job',
         lockCopy: 'Hire QAsm to unlock QA validation for this request.'
@@ -107,11 +107,11 @@ exports.PERSONA_CAPABILITY_BUNDLES = {
     sekhar: {
         personaKey: 'sekhar',
         bundleId: 'persona-sekhar-core',
-        catalogMetadata: buildCatalogMetadata('sekhar', ['security-review', 'ai-native-security-setup', 'security-findings-command-center']),
-        protectedJobs: ['security-review', 'ai-native-security-setup', 'security-findings-command-center', 'vulnerability-triage-and-remediation', 'compliance-review', 'compliance-continuous-monitoring', 'compliance-policy-authoring', 'compliance-questionnaire-response', 'compliance-requirements-detection', 'generate-audit-evidence', 'regulation-evidence-management', 'soc2-evidence-management'],
+        catalogMetadata: buildCatalogMetadata('sekhar', ['security-review', 'security-baseline-setup', 'vulnerability-triage-and-remediation']),
+        protectedJobs: ['security-review', 'security-baseline-setup', 'vulnerability-triage-and-remediation', 'compliance-review', 'compliance-continuous-monitoring', 'compliance-policy-authoring', 'compliance-questionnaire-response', 'compliance-requirements-detection', 'generate-audit-evidence', 'regulation-evidence-management', 'soc2-evidence-management'],
         protectedAliases: ['security', 'appsec'],
         defaultHireMode: 'job',
-        lockCopy: 'Hire SEChar to unlock security setup, review, and findings-command work for this request.'
+        lockCopy: 'Hire SEChar to unlock security setup, review, and remediation work for this request.'
     },
     travis: {
         personaKey: 'travis',

package/dist/src/core/quality-evidence.js

@@ -38,7 +38,7 @@ exports.QUALITY_REGISTRY = {
     'business-plan-creation': { stage: 'business-strategy', enforced: false },
     'branding-quality-audit': { stage: 'branding', enforced: true, telemetryKind: 'score' },
     // Product Quality
-    'code-quality-assessment': { stage: 'product-quality', enforced: true, telemetryKind: 'score' },
+    'codebase-quality-assessment': { stage: 'product-quality', enforced: true, telemetryKind: 'score' },
     // UI/UX Quality
     'ui-quality-assessment': { stage: 'ui-ux-quality', enforced: true, telemetryKind: 'score' },
     // Test Quality
@@ -151,7 +151,7 @@ const QUALITY_SCORE_DIMENSIONS = {
         'identityExpressiveness',
         'governanceReadiness'
     ],
-    'code-quality-assessment': [
+    'codebase-quality-assessment': [
         'typeSafety',
         'errorHandling',
         'architecture',

package/dist/src/services/demo-seed-service.js

@@ -5,7 +5,7 @@ const crypto_1 = require("crypto");
 const STAGE_JOBS = [
     { name: 'brainstorming', category: 'brainstorming', jobs: ['idea-exploration', 'opportunity-mapping'] },
     { name: 'customer-development', category: 'customer-development', jobs: ['interview-preparation', 'process-interview-notes', 'review-customer-development'] },
-    { name: 'product-building', category: 'product-building', jobs: ['feature-specification', 'technical-design', 'feature-implementation', 'pr-iteration'] },
+    { name: 'product-building', category: 'product-building', jobs: ['feature-specification', 'technical-design', 'feature-implementation'] },
     { name: 'fundraising', category: 'fundraising', jobs: ['investor-outreach', 'deck-iteration'] },
     { name: 'gtm', category: 'gtm', jobs: ['gtm-plan', 'channel-tests'] },
     { name: 'marketing', category: 'marketing', jobs: ['brand-creation', 'whitepaper-thought-leadership'] },
@@ -103,7 +103,7 @@ async function seedDemoDataForUser(dbService, userId) {
         { category: 'customer-development', jobName: 'process-interview-notes' },
         { category: 'business-strategy', jobName: 'review-business-strategy' },
         { category: 'branding', jobName: 'branding-quality-audit' },
-        { category: 'product-quality', jobName: 'code-quality-assessment' },
+        { category: 'product-quality', jobName: 'codebase-quality-assessment' },
         { category: 'ui-ux-quality', jobName: 'ui-quality-assessment' },
         { category: 'test-quality', jobName: 'test-quality-assessment' },
         { category: 'security', jobName: 'security-review' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.304",
+  "version": "2.0.306",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {

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

@@ -55,7 +55,7 @@
     }
 
     const { visible, hidden } = truncateToLastLines(frame.whatHappened || '', 12);
-    const whatHappened = document.createElement('pre');
+    const whatHappened = document.createElement('div');
     whatHappened.className = 'what-happened';
     whatHappened.setAttribute('data-testid', 'error-what-happened');
     whatHappened.textContent = visible;

package/public/first-run/script.js

@@ -584,6 +584,10 @@
     const existing = modal.querySelector('[data-testid="error-frame"]');
     if (existing) existing.remove();
     if (!window.FraimErrorFrame || typeof window.FraimErrorFrame.render !== 'function') return;
+    const status = modal.querySelector('[data-testid="agent-install-status"]');
+    if (status) status.remove();
+    const actions = modal.querySelector('.install-actions');
+    if (actions) actions.remove();
     const frame = window.FraimErrorFrame.render({
       whatTried: `We tried to set up ${opt.label}.`,
       whatHappened: message,
@@ -598,10 +602,9 @@
       } else if (action.id === 'alternative') {
         closeButton.click();
       } else if (action.id === 'manual') {
-        const status = modal.querySelector('[data-testid="agent-install-status"]');
-        if (status) {
-          status.textContent = 'Run npx fraim add-ide for manual setup, then return here when your local agent is ready.';
-          status.removeAttribute('data-tone');
+        const happened = modal.querySelector('[data-testid="error-what-happened"]');
+        if (happened) {
+          happened.textContent = 'Run npx fraim add-ide for manual setup, then return here when your local agent is ready.';
         }
       }
     });

package/public/first-run/styles.css

@@ -357,15 +357,16 @@ body {
   padding: 10px 12px;
 }
 .error-frame .what-happened {
-  background: #0d1410;
-  color: #f1c0c0;
-  font-family: "JetBrains Mono", "Cascadia Code", Consolas, monospace;
-  font-size: 12px;
+  background: #fff;
+  color: var(--text);
+  font-size: 14px;
+  line-height: 1.45;
   padding: 10px 12px;
   border-radius: 8px;
+  border: 1px solid #f0c9c9;
   max-height: 88px;
   overflow: auto;
-  white-space: pre;
+  white-space: pre-wrap;
   margin: 0;
 }
 .error-frame .show-full {