@codeyam/codeyam-cli 0.1.0-staging.b6c4c78 → 0.1.0-staging.b8b17a5

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

@@ -16,8 +16,9 @@ import { APP_FORMATS, TECH_STACKS } from "../data/techStacks.js";
 import { getProjectRoot as getStateProjectRoot } from "../state.js";
 import initCommand from "./init.js";
 import { scanScenarioFiles, syncScenarioFilesToDatabase, backfillScenarioMetadata, migrateScenarioFormats, } from "../utils/scenariosManifest.js";
-import { clearEditorState, clearEditorUserPrompt, validateStepTransition, } from "../utils/editorScenarios.js";
-import { validateSeedData, detectSeedAdapter, } from "../utils/editorSeedAdapter.js";
+import { clearEditorState, clearEditorUserPrompt, validateStepTransition, backfillEntityShaOnScenarios, } from "../utils/editorScenarios.js";
+import { validateSeedData, detectSeedAdapter, validateSeedKeysAgainstPrisma, } from "../utils/editorSeedAdapter.js";
+import { deleteScenarioViaCli } from "../utils/editorDeleteScenario.js";
 import { buildEditorApiRequest, callEditorApi, EDITOR_API_SUBCOMMANDS, } from "../utils/editorApi.js";
 import { parseRegisterArg } from "../utils/parseRegisterArg.js";
 import { sanitizeGlossaryEntries } from "../utils/editorLoaderHelpers.js";
@@ -207,20 +208,27 @@ function printAppScenarioInstructions(pageName, route) {
     checkbox('Check existing scenarios: `codeyam editor scenarios`');
     console.log(chalk.dim('    Review existing scenarios — reuse and update their data rather than'));
     console.log(chalk.dim('    creating duplicates. Re-register with the same name to update a scenario.'));
-    checkbox('Cover key data states (at least 2-3 scenarios per page)');
-    console.log(chalk.yellow('    Each page needs its own scenarios — a detail page needs different data than the catalog'));
+    console.log();
+    console.log(chalk.bold.yellow('App scenarios vs component scenarios — these are DIFFERENT:'));
+    console.log(chalk.yellow('  App scenarios:       show the FULL PAGE with seeded data at a real route (/, /library, etc.)'));
+    console.log(chalk.yellow('  Component scenarios: show ONE COMPONENT in isolation at /isolated-components/...'));
+    console.log(chalk.yellow('  This step is about APP scenarios. Do NOT set "componentName" — that makes it a component scenario.'));
+    console.log();
+    checkbox('Identify every page/route in the app and ensure each has app-level scenarios');
+    console.log(chalk.dim("    Check the app's router/entry points for all distinct pages"));
+    console.log(chalk.yellow('    Every page needs at least 2-3 app scenarios — not just the main page'));
     if (pageName) {
         console.log(chalk.dim(`    Example: "${pageName} - Full Data", "${pageName} - Empty State"`));
     }
     else {
-        console.log(chalk.dim('    Catalog: "Full Catalog", "Empty Catalog", "Single Category"'));
-        console.log(chalk.dim('    Detail:  "Detail - With Reviews", "Detail - No Reviews", "Detail - High Rated"'));
+        console.log(chalk.dim('    Example: "Page - Full Data", "Page - Empty State", "Page - Error State"'));
     }
     console.log();
-    checkbox('Register each scenario with type "application" and the real page url:');
-    console.log(chalk.dim(`    codeyam editor register '{"name":"${pageName || 'Page'} - Full Data","type":"application","url":"${route || '/'}",...}'`));
-    console.log(chalk.yellow('    IMPORTANT: "url" MUST be the real page route — without it, the wrong page gets screenshotted.'));
-    console.log(chalk.yellow('    IMPORTANT: include "pageFilePath" with the source file that renders this route (e.g., "src/App.tsx").'));
+    checkbox('Register each scenario with type "application", the real page URL, and pageFilePath:');
+    console.log(chalk.dim(`    codeyam editor register '{"name":"${pageName || 'Page'} - Full Data",`));
+    console.log(chalk.dim(`      "type":"application","url":"${route || '/'}","pageFilePath":"src/path/to/Page.tsx",...}'`));
+    console.log(chalk.yellow('    Required fields: "type":"application", "url" (real route), "pageFilePath" (source file)'));
+    console.log(chalk.yellow('    Do NOT include "componentName" — that would make it a component scenario'));
     console.log();
     checkbox('Choose the right data approach for scenarios:');
     console.log(chalk.dim('    With seed adapter: add "seed":{...} to populate the database for each state'));
@@ -323,7 +331,8 @@ function printComponentCaptureInstructions() {
     console.log(chalk.dim(`         "componentName":"ComponentName","componentPath":"path/to/file.tsx",`));
     console.log(chalk.dim(`         "url":"/codeyam-isolate/ComponentName?s=Scenario",`));
     console.log(chalk.dim(`         "mockData":{"routes":{"/api/...":{"body":[...]}}}}'`));
-    console.log(chalk.dim('       url is a PATH (starts with /) — the proxy routes it and intercepts API calls'));
+    console.log(chalk.yellow('       IMPORTANT: url MUST be an isolation route (/codeyam-isolate/... or /isolated-components/...).'));
+    console.log(chalk.yellow('       Do NOT use real page URLs (like /library) for component scenarios.'));
     console.log(chalk.dim('       mockData.routes provides data for API calls the component makes internally'));
     console.log(chalk.dim('       (omit mockData if the component has no internal API calls)'));
     console.log(chalk.yellow('    5. IMPORTANT: Check the register response for `clientErrors` array'));
@@ -930,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
@@ -1419,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();
@@ -1439,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,10 +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>"}'`));
     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);
@@ -1858,10 +1870,8 @@ function printMigrateStep10(root) {
     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>"}'`));
     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):'));
@@ -2324,6 +2334,26 @@ async function handleAnalyzeImports(options = {}) {
         });
         console.log(summary || JSON.stringify({ imports, entities: entityData }));
     }
+    // Backfill entity_sha on scenarios registered before entities existed.
+    // This fixes the "missing data" UI state when scenarios were registered
+    // while analyze-imports was still running in the background.
+    try {
+        const { getDatabase } = await import('../../../packages/database/index.js');
+        const db = getDatabase();
+        const backfillResult = await backfillEntityShaOnScenarios(db, latestEntities.map((e) => ({
+            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.`));
+        }
+    }
+    catch {
+        /* non-fatal */
+    }
 }
 // ─── Validate-seed subcommand ─────────────────────────────────────────
 /**
@@ -2362,6 +2392,24 @@ function handleValidateSeed(jsonArg) {
                 : 0;
             console.log(chalk.dim(`  ${table}: ${rows} row(s)`));
         }
+        // Check seed keys against Prisma schema if available
+        const schemaPath = path.join(root, 'prisma', 'schema.prisma');
+        try {
+            if (fs.existsSync(schemaPath)) {
+                const schemaContent = fs.readFileSync(schemaPath, 'utf-8');
+                const warnings = validateSeedKeysAgainstPrisma(tables, schemaContent);
+                if (warnings.length > 0) {
+                    console.log();
+                    console.log(chalk.yellow('Prisma model name warnings:'));
+                    for (const w of warnings) {
+                        console.log(chalk.yellow(`  ⚠ ${w}`));
+                    }
+                }
+            }
+        }
+        catch {
+            // Schema not readable — skip Prisma validation
+        }
     }
     else {
         console.error(chalk.red('Seed data validation failed:'));
@@ -2371,6 +2419,27 @@ function handleValidateSeed(jsonArg) {
         process.exit(1);
     }
 }
+// ─── Delete subcommand ────────────────────────────────────────────────
+/**
+ * `codeyam editor delete <scenarioId>`
+ *
+ * Delete a scenario by ID via the running editor server.
+ */
+async function handleDelete(scenarioId) {
+    if (!scenarioId) {
+        console.error(chalk.red('Error: Missing scenario ID. Usage: codeyam editor delete <scenarioId>'));
+        process.exit(1);
+    }
+    const port = getServerPort();
+    const result = await deleteScenarioViaCli(scenarioId, port);
+    if (result.success) {
+        console.log(chalk.green(result.message));
+    }
+    else {
+        console.error(chalk.red(result.message));
+        process.exit(1);
+    }
+}
 // ─── Isolate subcommand ───────────────────────────────────────────────
 /**
  * `codeyam editor isolate "StarRating CategoryBadge DrinkCard"`
@@ -2845,23 +2914,108 @@ function handleChange(feature) {
 }
 // ─── Audit gate ─────────────────────────────────────────────────────
 /**
- * Silently check whether the audit passes. Returns true if allPassing,
- * false if any issues remain or the server is unreachable.
- * Used as a hard gate before steps 8+.
+ * Fetch the audit result from the server.
+ * Returns null if the server is unreachable.
  */
-async function checkAuditGate() {
+async function fetchAuditResult() {
     const port = getServerPort();
     try {
         const res = await fetch(`http://localhost:${port}/api/editor-audit`);
         if (!res.ok)
-            return false;
-        const data = await res.json();
-        return data?.summary?.allPassing === true;
+            return null;
+        return await res.json();
     }
     catch {
-        // Server not running or unreachable — can't verify, so don't block
+        return null;
+    }
+}
+/**
+ * Silently check whether the audit passes. Returns true if allPassing,
+ * false if any issues remain or the server is unreachable.
+ * Used as a hard gate before steps 8+.
+ *
+ * Auto-runs analyze-imports if the only failure is incomplete entities,
+ * then re-checks once.
+ */
+async function checkAuditGate() {
+    const data = await fetchAuditResult();
+    if (!data)
+        return true; // Server unreachable — don't block
+    if (data.summary?.allPassing === true)
         return true;
+    // If incomplete entities are the only issue, auto-fix with analyze-imports (once)
+    const { isAutoRemediable } = await import('../utils/editorAudit.js');
+    if (isAutoRemediable(data.summary, false)) {
+        try {
+            await handleAnalyzeImports({ silent: true });
+        }
+        catch {
+            return false;
+        }
+        // Re-check after fix
+        const retry = await fetchAuditResult();
+        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 ────────────────────────────────────────────────
 /**
@@ -2872,22 +3026,38 @@ async function checkAuditGate() {
  * have test files. Exits with code 1 if anything is missing.
  */
 async function handleAudit() {
-    const port = getServerPort();
-    const url = `http://localhost:${port}/api/editor-audit`;
-    let data;
-    try {
-        const res = await fetch(url);
-        if (!res.ok) {
-            console.error(chalk.red(`Error: Audit endpoint returned ${res.status}`));
-            process.exit(1);
-        }
-        data = await res.json();
-    }
-    catch (err) {
+    let data = await fetchAuditResult();
+    if (!data) {
         console.error(chalk.red('Error: Could not reach the CodeYam server. Is it running?'));
-        console.error(chalk.dim(`  ${err.message}`));
         process.exit(1);
     }
+    // Auto-fix incomplete entities — but only once.
+    // If analyze-imports runs and entities are STILL incomplete, report clearly
+    // instead of retrying. The analysis may have errors (e.g., stale entity
+    // references from refactoring) that can't be fixed by re-running.
+    const incompleteBeforeFix = data.incompleteEntities || [];
+    let autoRemediationFailed = false;
+    if (incompleteBeforeFix.length > 0) {
+        console.log(chalk.dim(`Running import analysis for ${incompleteBeforeFix.length} incomplete entit${incompleteBeforeFix.length !== 1 ? 'ies' : 'y'}...`));
+        try {
+            await handleAnalyzeImports({ silent: true });
+        }
+        catch {
+            // Fall through — the audit will still report them as incomplete
+        }
+        // Re-fetch audit results after the fix
+        data = await fetchAuditResult();
+        if (!data) {
+            console.error(chalk.red('Error: Could not reach the CodeYam server after analyze-imports.'));
+            process.exit(1);
+        }
+        // If entities are still incomplete after running analyze-imports,
+        // flag it so we can show a clear message instead of looping
+        const incompleteAfterFix = data.incompleteEntities || [];
+        if (incompleteAfterFix.length > 0) {
+            autoRemediationFailed = true;
+        }
+    }
     const { components, functions, summary } = data;
     console.log();
     console.log(chalk.bold.cyan('━━━ Editor Audit ━━━'));
@@ -2915,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();
@@ -2929,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;
@@ -2956,6 +3142,43 @@ async function handleAudit() {
         console.log(chalk.yellow('    Add these to .codeyam/glossary.json and run `codeyam editor analyze-imports`'));
         console.log();
     }
+    // Incomplete entities (scenarios without analyses)
+    const incompleteEntities = data.incompleteEntities || [];
+    if (incompleteEntities.length > 0) {
+        console.log(chalk.bold('Incomplete entities (need import analysis):'));
+        for (const e of incompleteEntities) {
+            console.log(`  ${chalk.red('✗')} ${e.name} — ${e.scenarioCount} scenario${e.scenarioCount !== 1 ? 's' : ''} but entity not analyzed`);
+        }
+        if (autoRemediationFailed) {
+            console.log(chalk.red('    analyze-imports was run automatically but these entities are STILL incomplete.'));
+            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'));
+        }
+        console.log();
+    }
+    // Miscategorized scenarios (component scenarios using real page URLs)
+    const miscategorizedScenarios = data.miscategorizedScenarios || [];
+    if (miscategorizedScenarios.length > 0) {
+        console.log(chalk.bold('Miscategorized scenarios (component with page URL):'));
+        for (const m of miscategorizedScenarios) {
+            console.log(`  ${chalk.red('✗')} ${m.componentName} at ${chalk.dim(m.url)} — ${m.scenarioNames.length} scenario${m.scenarioNames.length !== 1 ? 's' : ''}`);
+            for (const name of m.scenarioNames) {
+                console.log(chalk.dim(`      "${name}"`));
+            }
+        }
+        console.log(chalk.yellow('    Component scenarios must use isolation routes (/isolated-components/...).'));
+        console.log(chalk.yellow('    Either re-register as app scenarios (remove componentName, add pageFilePath)'));
+        console.log(chalk.yellow('    or re-register with an isolation URL.'));
+        console.log();
+    }
     // Summary
     const allOk = summary.allPassing;
     if (allOk) {
@@ -2976,12 +3199,21 @@ 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)`);
         }
         if (summary.missingFromGlossary > 0) {
             parts.push(`${summary.missingFromGlossary} file${summary.missingFromGlossary !== 1 ? 's' : ''} with scenarios not in glossary`);
         }
+        if (summary.incompleteEntities > 0) {
+            parts.push(`${summary.incompleteEntities} entit${summary.incompleteEntities !== 1 ? 'ies' : 'y'} need import analysis`);
+        }
+        if (summary.miscategorizedScenarios > 0) {
+            parts.push(`${summary.miscategorizedScenarios} component${summary.miscategorizedScenarios !== 1 ? 's' : ''} using page URLs instead of isolation routes`);
+        }
         console.log(chalk.red.bold('Audit failed: ') + parts.join(', '));
     }
     console.log();
@@ -3099,6 +3331,32 @@ async function handleScenarios() {
 }
 // ─── Scenario Coverage subcommand ───────────────────────────────────
 async function handleScenarioCoverage() {
+    // Safety net: heal any scenarios with null entity_sha before checking coverage
+    try {
+        const { getDatabase } = await import('../../../packages/database/index.js');
+        const { countScenariosNeedingEntityBackfill } = await import('../utils/editorScenarios');
+        const db = getDatabase();
+        const backfillCount = await countScenariosNeedingEntityBackfill(db);
+        if (backfillCount > 0) {
+            console.log(chalk.dim(`  Healing ${backfillCount} scenario(s) with unlinked entities...`));
+            await handleAnalyzeImports({ silent: true });
+            // Run backfill after analysis
+            const { backfillEntityShaOnScenarios } = await import('../utils/editorScenarios');
+            const entities = await loadEntities({});
+            if (entities && entities.length > 0) {
+                await backfillEntityShaOnScenarios(db, entities.map((e) => ({
+                    sha: e.sha,
+                    name: e.name,
+                    filePath: e.filePath || '',
+                    isDefaultExport: e.metadata?.notExported === false &&
+                        e.metadata?.namedExport === false,
+                })));
+            }
+        }
+    }
+    catch {
+        // Non-fatal — proceed with coverage check regardless
+    }
     const port = getServerPort();
     const url = `http://localhost:${port}/api/editor-scenario-coverage`;
     let data;
@@ -3246,7 +3504,20 @@ async function handleTemplate() {
             // Config parse error is non-fatal
         }
     }
-    // 5b. Write a fresh prototypeId so the proxy clears stale localStorage
+    // 5b. Mark the project as template-scaffolded so migration detection
+    // doesn't treat it as a pre-existing project that needs migration.
+    const now = new Date().toISOString();
+    const existingState = readState(root);
+    writeState(root, {
+        feature: '',
+        step: 0,
+        label: '',
+        startedAt: now,
+        featureStartedAt: now,
+        ...existingState,
+        scaffolded: true,
+    });
+    // 5c. Write a fresh prototypeId so the proxy clears stale localStorage
     const activeScenarioPath = path.join(root, '.codeyam', 'active-scenario.json');
     fs.writeFileSync(activeScenarioPath, JSON.stringify({ prototypeId: Date.now().toString() }), 'utf-8');
     // 6. Trigger editor-refresh so the server picks up the new project
@@ -3624,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();
@@ -3703,14 +3976,16 @@ const editorCommand = {
             await handleValidateSeed(argv.json || '');
             return;
         }
+        // Subcommand: codeyam editor delete <scenarioId>
+        if (argv.step === 'delete') {
+            await handleDelete(argv.json || '');
+            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;
         }
@@ -3807,6 +4082,9 @@ const editorCommand = {
                         'screenshot_path',
                         'viewport_width',
                         'viewport_height',
+                        'dimensions',
+                        'screenshot_paths',
+                        'page_file_path',
                         'created_at',
                         'updated_at',
                     ])
@@ -3895,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
@@ -4013,6 +4326,22 @@ const editorCommand = {
                                 // Non-fatal
                             }
                         }
+                        // Check if any scenarios have null entity_sha with file paths — heal on startup
+                        if (!needsAnalysis) {
+                            try {
+                                const { getDatabase } = await import('../../../packages/database/index.js');
+                                const { countScenariosNeedingEntityBackfill } = await import('../utils/editorScenarios');
+                                const db = getDatabase();
+                                const backfillCount = await countScenariosNeedingEntityBackfill(db);
+                                if (backfillCount > 0) {
+                                    console.log(chalk.dim(`  Found ${backfillCount} scenario(s) with unlinked entities — running import analysis...`));
+                                    needsAnalysis = true;
+                                }
+                            }
+                            catch {
+                                // Non-fatal
+                            }
+                        }
                     }
                     if (needsAnalysis) {
                         try {
@@ -4023,6 +4352,71 @@ 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.
+                try {
+                    const entities = await loadEntities({});
+                    if (entities && entities.length > 0) {
+                        const { getDatabase } = await import('../../../packages/database/index.js');
+                        const db = getDatabase();
+                        const result = await backfillEntityShaOnScenarios(db, entities.map((e) => ({
+                            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`));
+                        }
+                    }
+                }
+                catch {
+                    /* Non-fatal */
+                }
                 console.log();
                 console.log(`  Dashboard: ${url}`);
                 console.log('  Run "codeyam --help" for all commands');
@@ -4108,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);
                     }
                 }