@codeyam/codeyam-cli 0.1.12 → 0.1.14

package/analyzer-template/.build-info.json

@@ -1,10 +1,10 @@
 {
-  "buildTimestamp": "2026-03-17T15:17:00.245Z",
-  "buildTime": 1773760620245,
-  "gitCommit": "b282daf6fc6409b6a9facc3666589360a160dc1d",
+  "buildTimestamp": "2026-03-18T14:58:22.078Z",
+  "buildTime": 1773845902078,
+  "gitCommit": "4dda2c78ef15ac678fb9a0e8f4d270c514f30f81",
   "nodeVersion": "v20.20.1",
   "contentHash": "b046e014847d5b02d10d6795839ccd0d5117627cbd0be413260824610596a63d",
-  "buildNumber": 1071,
-  "semanticVersion": "0.1.1071",
-  "version": "0.1.1071 (2026-03-17T15:17+b046e01)"
+  "buildNumber": 1092,
+  "semanticVersion": "0.1.1092",
+  "version": "0.1.1092 (2026-03-18T14:58+b046e01)"
 }

package/analyzer-template/log.txt

@@ -1,7 +1,7 @@
 
-[3/17/2026, 3:17:00 PM] > codeyam-combo@1.0.0 mergeDependencies
-[3/17/2026, 3:17:00 PM] > node ./scripts/mergePackageJsonFiles.cjs
+[3/18/2026, 2:58:21 PM] > codeyam-combo@1.0.0 mergeDependencies
+[3/18/2026, 2:58:21 PM] > node ./scripts/mergePackageJsonFiles.cjs
 
 
-[3/17/2026, 3:17:00 PM] Merged dependencies into root package.json
+[3/18/2026, 2:58:22 PM] Merged dependencies into root package.json
 

package/codeyam-cli/src/cli.js

@@ -27,8 +27,11 @@ import memoryCommand from "./commands/memory.js";
 import editorCommand from "./commands/editor.js";
 import setupSimulationsCommand from "./commands/setup-simulations.js";
 import { syncMocksMiddleware } from "./utils/syncMocksMiddleware.js";
+import { telemetryMiddleware } from "./utils/telemetryMiddleware.js";
+import { captureEvent } from "./utils/telemetry.js";
 import { getDisplayVersion } from "./utils/versionInfo.js";
 import { simulationGateMiddleware, buildSimulationEpilogue, } from "./utils/simulationGateMiddleware.js";
+import telemetryCommand from "./commands/telemetry.js";
 // Install global signal handlers for automatic process cleanup
 // This ensures all child processes (analyzer, capture, etc.) are cleaned up on:
 // - Ctrl+C (SIGINT)
@@ -49,11 +52,13 @@ yargs(hideBin(process.argv))
     .usage('CodeYam local development CLI')
     .middleware(simulationGateMiddleware)
     .middleware(syncMocksMiddleware)
+    .middleware(telemetryMiddleware)
     // Core commands (always visible in help)
     .command(defaultCommand)
     .command(startCommand)
     .command(stopCommand)
     .command(memoryCommand)
+    .command(telemetryCommand)
     // Hidden commands (shown in epilogue when simulations are enabled)
     .command(withoutDescribe(initCommand))
     .command(withoutDescribe(updateConfigCommand))
@@ -81,6 +86,10 @@ yargs(hideBin(process.argv))
     .strict()
     .parseAsync()
     .catch((error) => {
+    captureEvent('cli_error', {
+        command: process.argv[2] ?? 'unknown',
+        error_type: error?.constructor?.name ?? 'Error',
+    });
     console.error('CLI Error:', error.message);
     process.exit(1);
 });

package/codeyam-cli/src/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../../src/cli.ts"],"names":[],"mappings":"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"}

package/codeyam-cli/src/commands/__tests__/editor.isolateArgs.test.js

@@ -0,0 +1,51 @@
+/**
+ * Tests that `codeyam editor isolate` correctly parses multiple component
+ * names whether passed as separate args or a single quoted string.
+ *
+ * Bug: `codeyam editor isolate A B C` failed because yargs .strict()
+ * rejected extra positionals beyond the two declared (step, json).
+ * Claude would then try one at a time, wasting time and tokens.
+ */
+import { parseIsolateArgs } from "../editorIsolateArgs.js";
+describe('parseIsolateArgs', () => {
+    it('should parse a single component name from json arg', () => {
+        expect(parseIsolateArgs('LogoMark', [])).toEqual(['LogoMark']);
+    });
+    it('should parse space-separated names from a single quoted json arg', () => {
+        // codeyam editor isolate "LogoMark AppHeader Button"
+        expect(parseIsolateArgs('LogoMark AppHeader Button', [])).toEqual([
+            'LogoMark',
+            'AppHeader',
+            'Button',
+        ]);
+    });
+    it('should parse comma-separated names from json arg', () => {
+        expect(parseIsolateArgs('LogoMark,AppHeader,Button', [])).toEqual([
+            'LogoMark',
+            'AppHeader',
+            'Button',
+        ]);
+    });
+    it('should collect extra positional args from argv._', () => {
+        // codeyam editor isolate LogoMark AppHeader Button
+        // yargs: json="LogoMark", argv._=["editor", "AppHeader", "Button"]
+        expect(parseIsolateArgs('LogoMark', ['editor', 'AppHeader', 'Button'])).toEqual(['LogoMark', 'AppHeader', 'Button']);
+    });
+    it('should deduplicate names from json and extras', () => {
+        expect(parseIsolateArgs('LogoMark', ['editor', 'LogoMark', 'AppHeader'])).toEqual(['LogoMark', 'AppHeader']);
+    });
+    it('should filter out empty strings', () => {
+        expect(parseIsolateArgs('LogoMark  AppHeader', [])).toEqual([
+            'LogoMark',
+            'AppHeader',
+        ]);
+    });
+    it('should return empty array when no names provided', () => {
+        expect(parseIsolateArgs(undefined, [])).toEqual([]);
+        expect(parseIsolateArgs('', [])).toEqual([]);
+    });
+    it('should filter out "editor" from argv._', () => {
+        expect(parseIsolateArgs(undefined, ['editor', 'LogoMark', 'AppHeader'])).toEqual(['LogoMark', 'AppHeader']);
+    });
+});
+//# sourceMappingURL=editor.isolateArgs.test.js.map

package/codeyam-cli/src/commands/__tests__/editor.isolateArgs.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor.isolateArgs.test.js","sourceRoot":"","sources":["../../../../../src/commands/__tests__/editor.isolateArgs.test.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;IAChC,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC5D,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;IACjE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kEAAkE,EAAE,GAAG,EAAE;QAC1E,qDAAqD;QACrD,MAAM,CAAC,gBAAgB,CAAC,2BAA2B,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;YAChE,UAAU;YACV,WAAW;YACX,QAAQ;SACT,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,CAAC,gBAAgB,CAAC,2BAA2B,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;YAChE,UAAU;YACV,WAAW;YACX,QAAQ;SACT,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,mDAAmD;QACnD,mEAAmE;QACnE,MAAM,CACJ,gBAAgB,CAAC,UAAU,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC,CAChE,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACvD,MAAM,CACJ,gBAAgB,CAAC,UAAU,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC,CAClE,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACzC,MAAM,CAAC,gBAAgB,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;YAC1D,UAAU;YACV,WAAW;SACZ,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACpD,MAAM,CAAC,gBAAgB,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;QAChD,MAAM,CACJ,gBAAgB,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC,CACjE,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/codeyam-cli/src/commands/editor.js

@@ -939,13 +939,29 @@ function printStep2(root, feature) {
         console.log();
         console.log(chalk.bold('Build the feature:'));
     }
+    else {
+        console.log(chalk.bold('Prepare the database for this feature:'));
+        checkbox('List existing scenarios: `codeyam editor scenarios`');
+        console.log(chalk.dim('    Review existing scenarios to find seed data that best demonstrates the feature.'));
+        console.log(chalk.dim("    Don't create throwaway seed data — use what's already been curated."));
+        checkbox('Pick the scenario with seed data most relevant to this feature');
+        console.log(chalk.dim("    Think: which existing data state best exercises the feature you're building?"));
+        console.log(chalk.dim('    A scenario with diverse, realistic data is usually the best starting point.'));
+        checkbox('Load that scenario to seed the database and preview it:');
+        console.log(chalk.dim(`    codeyam editor preview '{"scenarioId":"<id>","dimension":"${dim}"}'`));
+        console.log(chalk.dim('    This switches the active scenario, runs the seed adapter, and refreshes the preview.'));
+        console.log(chalk.dim('    If no existing scenario fits, use the default seed: npm run db:seed'));
+        console.log();
+    }
     console.log(chalk.bold('Checklist:'));
     checkbox('Create API routes that read from the database via Prisma');
-    checkbox('Seed the database with demo data');
-    checkbox('Create `.codeyam/seed-adapter.ts` so CodeYam can seed the database for scenarios');
-    console.log(chalk.dim('    The seed adapter reads a JSON file (path passed as CLI arg), wipes tables, inserts rows.'));
-    console.log(chalk.dim("    Use the project's own ORM (Prisma, Drizzle, etc.). See template for example."));
-    console.log(chalk.dim('    Run with: npx tsx .codeyam/seed-adapter.ts <path-to-seed-data.json>'));
+    if (!projectExists) {
+        checkbox('Seed the database with demo data');
+        checkbox('Create `.codeyam/seed-adapter.ts` so CodeYam can seed the database for scenarios');
+        console.log(chalk.dim('    The seed adapter reads a JSON file (path passed as CLI arg), wipes tables, inserts rows.'));
+        console.log(chalk.dim("    Use the project's own ORM (Prisma, Drizzle, etc.). See template for example."));
+        console.log(chalk.dim('    Run with: npx tsx .codeyam/seed-adapter.ts <path-to-seed-data.json>'));
+    }
     checkbox('Verify the dev server shows the changes');
     checkbox('If the feature involves auth, email, payments, or other common patterns: read FEATURE_PATTERNS.md');
     // Responsive design guidance when building a mobile-responsive web app
@@ -1428,8 +1444,6 @@ function printStep12(root, feature) {
 }
 // ─── Step 13: Present ─────────────────────────────────────────────────
 function printStep13(root, feature) {
-    const port = getServerPort();
-    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
     const isResuming = prevState?.step === 13;
     const now = new Date().toISOString();
@@ -1448,18 +1462,9 @@ function printStep13(root, feature) {
     console.log('Present the results to the user and get their approval.');
     console.log();
     console.log(chalk.bold('Checklist:'));
-    checkbox('Fetch all scenarios: `codeyam editor scenarios`');
-    console.log(chalk.dim('    Each scenario has a `changeStatus` field: "new", "edited", "impacted", or null.'));
-    checkbox('Pick the best scenario to showcase from this working session:');
-    console.log(chalk.dim('    Prefer scenarios with changeStatus "new" or "edited" (directly changed in this session).'));
-    console.log(chalk.dim('    For app-level scenarios, prefer those showing the new/changed functionality.'));
-    console.log(chalk.dim('    NEVER pick a scenario with changeStatus null — those are unchanged from a previous commit.'));
-    checkbox('Switch the preview to that scenario using its `id` and `dimension`:');
-    console.log(chalk.dim(`    codeyam editor preview '{"scenarioId":"<id>","dimension":"${dim}"}'`));
-    console.log(chalk.dim('    Use the dimension that matches the scenario — check its registered dimensions.'));
-    printDimensionGuidance(dim, dimNames);
     checkbox(`Show the results panel: \`codeyam editor show-results\``);
     console.log(chalk.dim('    This opens a visual panel below the terminal showing all scenarios with screenshots.'));
+    console.log(chalk.dim('    The preview automatically switches to the first app-level scenario.'));
     console.log(chalk.dim('    The user can click scenarios to switch the live preview.'));
     checkbox('Write a 1-2 sentence summary of what was built');
     checkbox('Report test count and audit status (one line)');
@@ -1689,7 +1694,6 @@ function printMigrateStep4(root) {
     }
     const { pageName, pageIndex, totalPages } = pageInfo;
     writeMigrationStepState(root, 4, pageName, pageIndex, totalPages);
-    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     console.log();
     console.log(chalk.bold.cyan(`━━━ Migration Step 4: Preview — ${pageName} (${pageIndex + 1}/${totalPages}) ━━━`));
     console.log();
@@ -1699,11 +1703,8 @@ function printMigrateStep4(root) {
     checkbox('Review all scenario screenshots for this page — do they look correct?');
     checkbox('Check for client errors: `codeyam editor client-errors`');
     checkbox('If any issues: fix the scenario data, re-register affected scenarios');
-    checkbox('Fetch all scenarios: `codeyam editor scenarios`');
-    checkbox('Pick the best scenario to showcase:');
-    console.log(chalk.dim(`    codeyam editor preview '{"scenarioId":"<id>","dimension":"${dim}"}'`));
-    printDimensionGuidance(dim, dimNames);
     checkbox('Show results: `codeyam editor show-results`');
+    console.log(chalk.dim('    The preview automatically switches to the first app-level scenario.'));
     console.log();
     console.log(chalk.dim('The user should now see their existing page with live screenshots in the preview.'));
     migrationStopGate(4, pageName, pageIndex, totalPages);
@@ -1863,18 +1864,14 @@ function printMigrateStep10(root) {
     }
     const { pageName, pageIndex, totalPages } = pageInfo;
     writeMigrationStepState(root, 10, pageName, pageIndex, totalPages);
-    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     console.log();
     console.log(chalk.bold.cyan(`━━━ Migration Step 10: Present — ${pageName} (${pageIndex + 1}/${totalPages}) ━━━`));
     console.log();
     console.log("Show results and commit this page's migration.");
     console.log();
     console.log(chalk.bold('Checklist:'));
-    checkbox('Fetch all scenarios: `codeyam editor scenarios`');
-    checkbox('Pick the best scenario to showcase:');
-    console.log(chalk.dim(`    codeyam editor preview '{"scenarioId":"<id>","dimension":"${dim}"}'`));
-    printDimensionGuidance(dim, dimNames);
     checkbox('Show results: `codeyam editor show-results`');
+    console.log(chalk.dim('    The preview automatically switches to the first app-level scenario.'));
     checkbox('Write a 1-2 sentence summary of what was migrated');
     console.log();
     console.log(chalk.bold('Present a selection menu (AskUserQuestion with these EXACT option labels):'));
@@ -2347,6 +2344,8 @@ async function handleAnalyzeImports(options = {}) {
             sha: e.sha,
             name: e.name,
             filePath: e.filePath || '',
+            isDefaultExport: e.metadata?.notExported === false &&
+                e.metadata?.namedExport === false,
         })));
         if (backfillResult.updated > 0 && !options.silent) {
             console.log(chalk.green(`Linked ${backfillResult.updated} scenario(s) to their entities.`));
@@ -2955,10 +2954,69 @@ async function checkAuditGate() {
         }
         // Re-check after fix
         const retry = await fetchAuditResult();
-        return retry?.summary?.allPassing === true;
+        if (retry?.summary?.allPassing === true)
+            return true;
     }
+    // Print specific failures so Claude knows what to fix without running audit separately
+    printAuditGateFailures(data);
     return false;
 }
+/**
+ * Print a concise summary of audit failures for the gate block message.
+ * This gives Claude immediate context about what to fix without needing
+ * to run `codeyam editor audit` as a separate step.
+ */
+function printAuditGateFailures(data) {
+    const s = data.summary;
+    if (!s)
+        return;
+    const issues = [];
+    if (s.componentsMissing > 0)
+        issues.push(`${s.componentsMissing} component(s) missing scenarios`);
+    if (s.componentsWithErrors > 0)
+        issues.push(`${s.componentsWithErrors} component(s) with client errors (browser API or runtime errors in captured scenarios)`);
+    if (s.functionsMissing > 0)
+        issues.push(`${s.functionsMissing} function(s) missing test files`);
+    if (s.functionsFailing > 0)
+        issues.push(`${s.functionsFailing} function(s) with failing tests`);
+    if (s.functionsRunnerError > 0)
+        issues.push(`${s.functionsRunnerError} function(s) with test runner errors (the runner crashed — not a test failure)`);
+    if (s.functionsNameMismatch > 0)
+        issues.push(`${s.functionsNameMismatch} function(s) with test name mismatch`);
+    if (s.missingFromGlossary > 0)
+        issues.push(`${s.missingFromGlossary} file(s) with scenarios not in glossary`);
+    if (s.incompleteEntities > 0)
+        issues.push(`${s.incompleteEntities} entity/entities need import analysis`);
+    if (s.miscategorizedScenarios > 0)
+        issues.push(`${s.miscategorizedScenarios} component(s) using page URLs instead of isolation routes`);
+    if (issues.length > 0) {
+        console.error(chalk.yellow('\nAudit failures:'));
+        for (const issue of issues) {
+            console.error(chalk.yellow(`  • ${issue}`));
+        }
+    }
+    // Surface client error details inline — these are the most common cause of
+    // Claude looping because the errors require code fixes, not audit re-runs.
+    if (data.components) {
+        const withErrors = data.components.filter((c) => c.status === 'has_errors' && c.clientErrors?.length > 0);
+        if (withErrors.length > 0) {
+            console.error(chalk.yellow('\nClient errors found:'));
+            for (const c of withErrors) {
+                console.error(chalk.red(`  ${c.name}:`));
+                for (const err of c.clientErrors.slice(0, 3)) {
+                    console.error(chalk.red(`    → ${err}`));
+                }
+                if (c.clientErrors.length > 3) {
+                    console.error(chalk.dim(`    … and ${c.clientErrors.length - 3} more`));
+                }
+            }
+            console.error(chalk.yellow('\nFix: Fix the code errors above, then re-capture the affected scenarios.'));
+            console.error(chalk.yellow('If errors reference browser APIs (localStorage, sessionStorage, window, document),'));
+            console.error(chalk.yellow('create a universal mock: codeyam detect-universal-mocks'));
+        }
+    }
+    console.error(chalk.dim('\nRun `codeyam editor audit` for full details.\n'));
+}
 // ─── Audit subcommand ────────────────────────────────────────────────
 /**
  * `codeyam editor audit`
@@ -3027,6 +3085,14 @@ async function handleAudit() {
                 if (c.clientErrors.length > 3) {
                     console.log(chalk.dim(`      … and ${c.clientErrors.length - 3} more`));
                 }
+                // Detect browser API errors and provide actionable guidance
+                const browserApiPattern = /\b(localStorage|sessionStorage|window\.|document\.|navigator\.|indexedDB|matchMedia|ResizeObserver|IntersectionObserver|MutationObserver)\b/;
+                const hasBrowserApiErrors = c.clientErrors.some((err) => browserApiPattern.test(err));
+                if (hasBrowserApiErrors) {
+                    console.log(chalk.yellow(`      ⚠ These errors are caused by browser APIs that don't exist during server-side analysis.`));
+                    console.log(chalk.yellow(`      Fix: Create a universal mock to stub the missing API. Run: codeyam detect-universal-mocks`));
+                    console.log(chalk.yellow(`      DO NOT re-run the audit or analyze-imports — the error will persist until a mock is created.`));
+                }
             }
         }
         console.log();
@@ -3041,6 +3107,14 @@ async function handleAudit() {
                 case 'ok':
                     detail = chalk.dim(` (${f.testFile})`);
                     break;
+                case 'runner_error':
+                    detail = chalk.red(` — test runner crashed: ${f.testFile}`);
+                    if (f.errorMessage) {
+                        detail += `\n      ${chalk.red(f.errorMessage)}`;
+                        detail += `\n      ${chalk.yellow('Note: This is NOT a test failure — the test runner itself could not execute.')}`;
+                        detail += `\n      ${chalk.yellow('Try running the test manually: npx vitest run ' + f.testFile)}`;
+                    }
+                    break;
                 case 'failing':
                     detail = chalk.red(` — tests failing: ${f.testFile}`);
                     break;
@@ -3077,9 +3151,13 @@ async function handleAudit() {
         }
         if (autoRemediationFailed) {
             console.log(chalk.red('    analyze-imports was run automatically but these entities are STILL incomplete.'));
-            console.log(chalk.red('    This usually means the analysis had errors — check the output above for details.'));
-            console.log(chalk.yellow('    Common causes: stale entity references from refactoring, missing source files.'));
-            console.log(chalk.yellow('    Try: run `codeyam editor analyze-imports` manually to see the full error output.'));
+            console.log(chalk.red('    DO NOT re-run analyze-imports or the audit in a loop — the result will be the same.'));
+            console.log(chalk.yellow('    This means the analysis failed for these entities. Common causes:'));
+            console.log(chalk.yellow('      • Entity code uses browser APIs (localStorage, window, document) — create a universal mock'));
+            console.log(chalk.yellow('      • Source file was renamed/deleted but glossary still references the old path'));
+            console.log(chalk.yellow('      • Entity has import errors that prevent analysis'));
+            console.log(chalk.yellow('    To investigate: run `codeyam editor analyze-imports` (without --silent) to see the full error.'));
+            console.log(chalk.yellow('    To fix browser API issues: run `codeyam detect-universal-mocks`'));
         }
         else {
             console.log(chalk.yellow('    Run `codeyam editor analyze-imports` to analyze these entities'));
@@ -3121,6 +3199,9 @@ async function handleAudit() {
         if (summary.functionsFailing > 0) {
             parts.push(`${summary.functionsFailing} function${summary.functionsFailing !== 1 ? 's' : ''} with failing tests`);
         }
+        if (summary.functionsRunnerError > 0) {
+            parts.push(`${summary.functionsRunnerError} function${summary.functionsRunnerError !== 1 ? 's' : ''} with test runner errors (not test failures — see details above)`);
+        }
         if (summary.functionsNameMismatch > 0) {
             parts.push(`${summary.functionsNameMismatch} function${summary.functionsNameMismatch !== 1 ? 's' : ''} with test name mismatch (missing top-level describe)`);
         }
@@ -3267,6 +3348,8 @@ async function handleScenarioCoverage() {
                     sha: e.sha,
                     name: e.name,
                     filePath: e.filePath || '',
+                    isDefaultExport: e.metadata?.notExported === false &&
+                        e.metadata?.namedExport === false,
                 })));
             }
         }
@@ -3812,7 +3895,9 @@ const editorCommand = {
                 describe: 'Debug: output directory for the bundle',
             });
         }
-        return builder;
+        // Allow extra positional args for subcommands like `isolate A B C`
+        // without yargs rejecting them as unknown.
+        return builder.strict(false);
     },
     handler: async (argv) => {
         const root = getProjectRoot();
@@ -3897,13 +3982,10 @@ const editorCommand = {
             return;
         }
         // Subcommand: codeyam editor isolate "StarRating CategoryBadge DrinkCard"
+        // Also supports: codeyam editor isolate StarRating CategoryBadge DrinkCard
         if (argv.step === 'isolate') {
-            const names = [];
-            if (argv.json)
-                names.push(...argv.json.split(/[\s,]+/).filter(Boolean));
-            // Collect any extra positional args (yargs puts them in argv._)
-            const extras = argv._.filter((a) => typeof a === 'string' && a !== 'editor');
-            names.push(...extras);
+            const { parseIsolateArgs } = await import('./editorIsolateArgs.js');
+            const names = parseIsolateArgs(argv.json, argv._);
             handleIsolate(names);
             return;
         }
@@ -4091,6 +4173,41 @@ const editorCommand = {
                 catch {
                     // Non-fatal — migration failure shouldn't block editor startup
                 }
+                // Auto-seed on fresh clone: if no scenario has ever been activated
+                // (active-scenario.json doesn't exist), seed the application database
+                // with the first application scenario that has seed data.
+                const activeScenarioPath = path.join(projectRoot, '.codeyam', 'active-scenario.json');
+                if (!fs.existsSync(activeScenarioPath)) {
+                    try {
+                        const { getDatabase: getDb } = await import('../../../packages/database/index.js');
+                        const seedDb = getDb();
+                        const appScenario = await seedDb
+                            .selectFrom('editor_scenarios')
+                            .select(['id', 'name', 'type'])
+                            .where('project_id', '=', project.id)
+                            .where('type', '=', 'application')
+                            .orderBy('created_at', 'asc')
+                            .executeTakeFirst();
+                        if (appScenario) {
+                            const seedFile = path.join(projectRoot, '.codeyam', 'editor-scenarios', `${appScenario.id}.seed.json`);
+                            if (fs.existsSync(seedFile)) {
+                                const { switchActiveScenario } = await import('../utils/editorScenarioSwitch.js');
+                                const seedResult = await switchActiveScenario({
+                                    scenarioId: appScenario.id,
+                                    scenarioName: appScenario.name || undefined,
+                                    scenarioType: appScenario.type || undefined,
+                                    projectRoot,
+                                });
+                                if (seedResult.seedResult?.success) {
+                                    console.log(chalk.green(`  Auto-seeded database with scenario: ${appScenario.name || appScenario.id}`));
+                                }
+                            }
+                        }
+                    }
+                    catch {
+                        // Non-fatal — auto-seed is best-effort
+                    }
+                }
                 // `codeyam editor` (no step) always implies editor mode.
                 // The empty-folder heuristic is no longer needed here — running this
                 // command IS the signal.  We still detect empty folders so that
@@ -4235,6 +4352,48 @@ const editorCommand = {
                         }
                     }
                 }
+                // Backfill page_file_path for application scenarios that have a URL but
+                // no page_file_path. This resolves the file from the URL using Next.js
+                // routing conventions, enabling syncScenarioEntityShas to link them to
+                // entities. Covers fresh clones where JSON files lack pageFilePath.
+                try {
+                    const { getDatabase: getDb } = await import('../../../packages/database/index.js');
+                    const pfpDb = getDb();
+                    const unresolved = await pfpDb
+                        .selectFrom('editor_scenarios')
+                        .select(['id', 'url'])
+                        .where('project_id', '=', project.id)
+                        .where('component_name', 'is', null)
+                        .where('page_file_path', 'is', null)
+                        .where('url', 'is not', null)
+                        .execute();
+                    if (unresolved.length > 0) {
+                        const { scanPageFilePaths: scanPfp } = await import('../utils/entityChangeStatus.server.js');
+                        const { matchUrlToPageFile } = await import('../utils/routePatternMatching');
+                        const { allFiles: pfpFiles } = scanPfp(projectRoot);
+                        let pfpResolved = 0;
+                        for (const row of unresolved) {
+                            const r = row;
+                            if (!r.url)
+                                continue;
+                            const matched = matchUrlToPageFile(r.url, pfpFiles);
+                            if (matched) {
+                                await pfpDb
+                                    .updateTable('editor_scenarios')
+                                    .set({ page_file_path: matched })
+                                    .where('id', '=', r.id)
+                                    .execute();
+                                pfpResolved++;
+                            }
+                        }
+                        if (pfpResolved > 0) {
+                            console.log(chalk.green(`  Resolved page_file_path for ${pfpResolved} scenario(s) from URL`));
+                        }
+                    }
+                }
+                catch {
+                    /* Non-fatal — page_file_path backfill from URL */
+                }
                 // Backfill entity_sha on scenarios that were synced before entities existed.
                 // This runs independently of analyze-imports so fresh clones and file-synced
                 // scenarios get linked to their entities even when auto-analyze doesn't trigger.
@@ -4247,6 +4406,8 @@ const editorCommand = {
                             sha: e.sha,
                             name: e.name,
                             filePath: e.filePath || '',
+                            isDefaultExport: e.metadata?.notExported === false &&
+                                e.metadata?.namedExport === false,
                         })));
                         if (result.updated > 0) {
                             console.log(chalk.green(`  Linked ${result.updated} scenario(s) to their entities`));
@@ -4341,8 +4502,9 @@ const editorCommand = {
                 if (step >= 8) {
                     const auditOk = await checkAuditGate();
                     if (!auditOk) {
-                        console.error(chalk.red.bold('BLOCKED: The audit has not passed. Run `codeyam editor audit` and fix all issues before proceeding.'));
-                        console.error(chalk.yellow('Every function and hook must have a test file. Every component must have scenarios.'));
+                        // checkAuditGate() already printed specific failure details above
+                        console.error(chalk.red.bold('BLOCKED: The audit has not passed. Fix the issues listed above before proceeding.'));
+                        console.error(chalk.yellow('DO NOT re-run the audit in a loop — fix the underlying issues first.'));
                         process.exit(1);
                     }
                 }