@codeyam/codeyam-cli 0.1.12 → 0.1.13

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

@@ -1,10 +1,10 @@
 {
-  "buildTimestamp": "2026-03-17T15:17:00.245Z",
-  "buildTime": 1773760620245,
-  "gitCommit": "b282daf6fc6409b6a9facc3666589360a160dc1d",
+  "buildTimestamp": "2026-03-17T22:42:54.370Z",
+  "buildTime": 1773787374370,
+  "gitCommit": "6af1ab46096de2c86af4f0947046703a16ac9786",
   "nodeVersion": "v20.20.1",
   "contentHash": "b046e014847d5b02d10d6795839ccd0d5117627cbd0be413260824610596a63d",
-  "buildNumber": 1071,
-  "semanticVersion": "0.1.1071",
-  "version": "0.1.1071 (2026-03-17T15:17+b046e01)"
+  "buildNumber": 1087,
+  "semanticVersion": "0.1.1087",
+  "version": "0.1.1087 (2026-03-17T22:42+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/17/2026, 10:42:54 PM] > codeyam-combo@1.0.0 mergeDependencies
+[3/17/2026, 10:42:54 PM] > node ./scripts/mergePackageJsonFiles.cjs
 
 
-[3/17/2026, 3:17:00 PM] Merged dependencies into root package.json
+[3/17/2026, 10:42:54 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":";AAEA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACzD,0BAA0B;AAC1B,OAAO,WAAW,MAAM,iBAAiB,CAAC;AAC1C,OAAO,cAAc,MAAM,oBAAoB,CAAC;AAChD,OAAO,aAAa,MAAM,mBAAmB,CAAC;AAC9C,OAAO,eAAe,MAAM,qBAAqB,CAAC;AAClD,OAAO,cAAc,MAAM,oBAAoB,CAAC;AAChD,OAAO,kBAAkB,MAAM,yBAAyB,CAAC;AACzD,OAAO,YAAY,MAAM,kBAAkB,CAAC;AAC5C,OAAO,WAAW,MAAM,iBAAiB,CAAC;AAC1C,OAAO,cAAc,MAAM,oBAAoB,CAAC;AAChD,OAAO,mBAAmB,MAAM,0BAA0B,CAAC;AAC3D,OAAO,aAAa,MAAM,mBAAmB,CAAC;AAC9C,OAAO,oBAAoB,MAAM,oCAAoC,CAAC;AACtE,OAAO,YAAY,MAAM,kBAAkB,CAAC;AAC5C,OAAO,mBAAmB,MAAM,0BAA0B,CAAC;AAC3D,OAAO,aAAa,MAAM,mBAAmB,CAAC;AAC9C,OAAO,YAAY,MAAM,kBAAkB,CAAC;AAC5C,OAAO,gBAAgB,MAAM,sBAAsB,CAAC;AACpD,OAAO,mBAAmB,MAAM,0BAA0B,CAAC;AAC3D,OAAO,WAAW,MAAM,iBAAiB,CAAC;AAC1C,OAAO,eAAe,MAAM,qBAAqB,CAAC;AAClD,OAAO,aAAa,MAAM,mBAAmB,CAAC;AAC9C,OAAO,aAAa,MAAM,mBAAmB,CAAC;AAC9C,OAAO,uBAAuB,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EACL,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,kCAAkC,CAAC;AAE1C,+DAA+D;AAC/D,gFAAgF;AAChF,oBAAoB;AACpB,YAAY;AACZ,wBAAwB;AACxB,iCAAiC;AACjC,wBAAwB;AACxB,qBAAqB,EAAE,CAAC;AAExB,gEAAgE;AAChE,8DAA8D;AAC9D,SAAS,eAAe,CAAC,GAAQ;IAC/B,OAAO,EAAE,GAAG,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AACrC,CAAC;AAED,4BAA4B;AAC5B,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;KACzB,UAAU,CAAC,SAAS,CAAC;KACrB,OAAO,CAAC,iBAAiB,EAAE,CAAC;KAC5B,KAAK,CAAC,+BAA+B,CAAC;KACtC,UAAU,CAAC,wBAAwB,CAAC;KACpC,UAAU,CAAC,mBAAmB,CAAC;IAChC,yCAAyC;KACxC,OAAO,CAAC,cAAc,CAAC;KACvB,OAAO,CAAC,YAAY,CAAC;KACrB,OAAO,CAAC,WAAW,CAAC;KACpB,OAAO,CAAC,aAAa,CAAC;IACvB,mEAAmE;KAClE,OAAO,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC;KACrC,OAAO,CAAC,eAAe,CAAC,mBAAmB,CAAC,CAAC;KAC7C,OAAO,CAAC,eAAe,CAAC,uBAAuB,CAAC,CAAC;KACjD,OAAO,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC;KACxC,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC;KACvC,OAAO,CAAC,eAAe,CAAC,kBAAkB,CAAC,CAAC;KAC5C,OAAO,CAAC,eAAe,CAAC,mBAAmB,CAAC,CAAC;KAC7C,OAAO,CAAC,eAAe,CAAC,gBAAgB,CAAC,CAAC;KAC1C,OAAO,CAAC,eAAe,CAAC,eAAe,CAAC,CAAC;KACzC,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;KACtC,OAAO,CAAC,eAAe,CAAC,oBAAoB,CAAC,CAAC;KAC9C,OAAO,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC;KACxC,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC;KACvC,OAAO,CAAC,eAAe,CAAC,eAAe,CAAC,CAAC;KACzC,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;KACtC,OAAO,CAAC,eAAe,CAAC,mBAAmB,CAAC,CAAC;KAC7C,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC;KACvC,OAAO,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC;KACrC,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC;KACvC,QAAQ,CAAC,uBAAuB,EAAE,CAAC;KACnC,aAAa,CAAC,CAAC,CAAC;KAChB,IAAI,EAAE;KACN,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC;KAClB,MAAM,EAAE;KACR,UAAU,EAAE;KACZ,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACf,OAAO,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAC3C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"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
@@ -2955,10 +2971,67 @@ 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.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 +3100,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();
@@ -3077,9 +3158,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'));
@@ -3812,7 +3897,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 +3984,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 +4175,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 +4354,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.
@@ -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);
                     }
                 }