@codeyam/codeyam-cli 0.1.0-staging.9574237 → 0.1.0-staging.a77070e

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

@@ -205,28 +205,45 @@ function checkbox(text) {
  * Prints seed-based scenarios, mock-based fallback, @ file prefix, externalApis, url requirement, and error checking.
  */
 function printAppScenarioInstructions(pageName, route) {
+    const root = process.cwd();
+    const hasSeedAdapter = !!detectSeedAdapter(root);
     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'));
-    console.log(chalk.dim('    Without seed adapter: add "mockData":{"routes":{"/api/...":{"body":[...]}}} to mock API responses'));
-    console.log(chalk.dim('    For external APIs (Stripe, weather, etc.): add "externalApis":{"GET https://...":{"body":[...],"status":200}}'));
+    if (hasSeedAdapter) {
+        checkbox(chalk.bold.red('REQUIRED: Every app scenario MUST include "seed" data — without it the page will be empty!'));
+        console.log(chalk.yellow('    A seed adapter exists — you MUST include "seed":{...} in every app scenario registration.'));
+        console.log(chalk.yellow('    An app scenario without seed data will render an empty page (no database rows = nothing to show).'));
+        console.log(chalk.dim('    "seed" maps table names to arrays of rows: "seed":{"user":[{"id":1,"name":"Alice"}],"article":[...]}'));
+        console.log(chalk.dim('    For external APIs: also add "externalApis":{"GET https://...":{"body":[...],"status":200}}'));
+    }
+    else {
+        checkbox('Include data in every app scenario — without it the page will be empty:');
+        console.log(chalk.dim('    Use "mockData":{"routes":{"/api/...":{"body":[...]}}} to mock API responses'));
+        console.log(chalk.dim('    For external APIs: add "externalApis":{"GET https://...":{"body":[...],"status":200}}'));
+    }
     checkbox('For large seed/mock data, write JSON to a temp file and use @ prefix:');
     console.log(chalk.dim('    Write JSON to .codeyam/tmp/scenario.json then register with:'));
     console.log(chalk.dim('    codeyam editor register @.codeyam/tmp/scenario.json'));
@@ -313,7 +330,7 @@ function printComponentCaptureInstructions() {
     console.log(chalk.dim('       The route defines a `scenarios` object mapping scenario names to props,'));
     console.log(chalk.dim('       reads `?s=ScenarioName` from the URL, and renders the component with those props.'));
     console.log(chalk.dim('       Wrap the component in a capture container with id="codeyam-capture":'));
-    console.log(chalk.dim('       <div id="codeyam-capture" style={{ display:"inline-block", padding:"20px" }}>'));
+    console.log(chalk.dim('       <div id="codeyam-capture" style={{ display:"inline-block" }}>'));
     console.log(chalk.dim('         <div style={{ width:"100%", maxWidth:"..." }}> ← match the app\'s container width'));
     console.log(chalk.dim('       e.g. card in a 3-col grid → maxWidth:"24rem", full-width component → omit maxWidth'));
     console.log(chalk.dim('       The screenshot captures just this wrapper, so the component fills the image.'));
@@ -324,7 +341,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'));
@@ -792,6 +810,7 @@ function printCycleOverview(root, state) {
         console.log(chalk.green('Start now: ') + chalk.bold('codeyam editor 1'));
         console.log(chalk.dim('  If the user already described what they want, pass it: codeyam editor 1 --prompt "their message"'));
     }
+    console.log(chalk.dim('If stuck on CLI commands, scenarios, or debugging, read: .codeyam/docs/editor-reference.md'));
     console.log();
 }
 // ─── Step 1: Plan ─────────────────────────────────────────────────────
@@ -931,13 +950,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
@@ -1420,8 +1455,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();
@@ -1440,18 +1473,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)');
@@ -1681,7 +1705,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();
@@ -1691,11 +1714,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);
@@ -1855,18 +1875,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):'));
@@ -2339,6 +2355,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.`));
@@ -2644,6 +2662,13 @@ async function handleRegister(jsonArg) {
             if (data.captureError)
                 parts.push(chalk.yellow(`captureError="${data.captureError}"`));
             console.log(prefix + parts.join(' '));
+            // Warn when application scenario is missing seed data
+            if (data.missingSeedWarning) {
+                console.log(chalk.red.bold('WARNING: No seed data in this application scenario!'));
+                console.log(chalk.yellow('  This scenario has type "application" but no "seed" data was provided.'));
+                console.log(chalk.yellow('  The page will render with an empty database — nothing will be visible.'));
+                console.log(chalk.yellow('  Re-register with "seed":{...} containing the database rows this page needs.'));
+            }
             // Surface client errors prominently so they can't be missed
             if (data.clientErrors && data.clientErrors.length > 0) {
                 console.log(chalk.red.bold(`⚠ WARNING: ${data.clientErrors.length} client error${data.clientErrors.length !== 1 ? 's' : ''} detected during capture:`));
@@ -2651,6 +2676,14 @@ async function handleRegister(jsonArg) {
                     console.log(chalk.red(`  → ${err}`));
                 }
                 console.log(chalk.yellow('  The screenshot may show an error screen instead of the actual component.'));
+                // Provide actionable debugging hints for HTTP/API errors
+                const hasApiResponseError = data.clientErrors.some((e) => e.includes('API response error:'));
+                const hasHttpError = data.clientErrors.some((e) => e.includes('HTTP error:'));
+                if (hasHttpError || hasApiResponseError) {
+                    console.log(chalk.yellow('  To debug: look at the "API response error" lines above — they show the exact API endpoint'));
+                    console.log(chalk.yellow('  that failed and what the server returned. Then check the scenario seed data to ensure'));
+                    console.log(chalk.yellow('  all IDs referenced in the URL exist in the seed, and that the route is correct.'));
+                }
                 console.log(chalk.yellow('  Fix the issue and re-register this scenario.'));
             }
             if (!res.ok) {
@@ -2676,6 +2709,53 @@ async function handleRegister(jsonArg) {
         process.exit(1);
     }
 }
+// ─── Glossary-add subcommand ──────────────────────────────────────────
+/**
+ * `codeyam editor glossary-add '{"name":"...", "filePath":"...", "description":"..."}'`
+ *
+ * Safely adds/updates entries in .codeyam/glossary.json via the CLI,
+ * avoiding hand-editing that breaks on unicode characters.
+ */
+async function handleGlossaryAdd(jsonArg) {
+    if (!jsonArg) {
+        console.error(chalk.red('Error: JSON argument required.'));
+        console.error(chalk.dim('  Usage: codeyam editor glossary-add \'{"name":"DrinkCard","filePath":"app/components/DrinkCard.tsx","description":"Displays a drink item"}\''));
+        console.error(chalk.dim('  For large payloads: codeyam editor glossary-add @.codeyam/tmp/entry.json'));
+        process.exit(1);
+    }
+    const parsed = parseRegisterArg(jsonArg);
+    if (parsed.error) {
+        console.error(chalk.red(`Error: ${parsed.error}`));
+        process.exit(1);
+    }
+    // Normalize to array
+    const items = Array.isArray(parsed.body) ? parsed.body : [parsed.body];
+    // Read existing glossary
+    const root = getProjectRoot();
+    const glossaryPath = path.join(root, '.codeyam', 'glossary.json');
+    let existing = [];
+    try {
+        const raw = JSON.parse(fs.readFileSync(glossaryPath, 'utf8'));
+        existing = sanitizeGlossaryEntries(raw);
+    }
+    catch {
+        // Glossary doesn't exist yet or can't be parsed — start fresh
+    }
+    // Merge
+    const { validateGlossaryEntry, mergeGlossaryEntries } = await import('../utils/glossaryAdd.js');
+    const result = mergeGlossaryEntries(existing, items);
+    // Report validation errors
+    for (const err of result.errors) {
+        console.error(chalk.red(`Error at index ${err.index}: ${err.message}`));
+    }
+    if (result.added === 0 && result.updated === 0 && result.errors.length > 0) {
+        process.exit(1);
+    }
+    // Write back with utf8 encoding to safely handle unicode
+    fs.mkdirSync(path.dirname(glossaryPath), { recursive: true });
+    fs.writeFileSync(glossaryPath, JSON.stringify(result.entries, null, 2), 'utf8');
+    console.log(`added=${result.added} updated=${result.updated} total=${result.entries.length}`);
+}
 // ─── Dependents subcommand ────────────────────────────────────────────
 /**
  * `codeyam editor dependents <EntityName>`
@@ -2907,23 +2987,150 @@ 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`);
+        const missing = (data.components || []).filter((c) => c.status === 'missing');
+        for (const c of missing) {
+            issues.push(`    → ${c.name}${c.filePath ? ` (${c.filePath})` : ''}`);
+        }
+    }
+    if (s.componentsWithErrors > 0) {
+        issues.push(`${s.componentsWithErrors} component(s) with client errors (browser API or runtime errors in captured scenarios)`);
+        const withErrors = (data.components || []).filter((c) => c.status === 'has_errors');
+        for (const c of withErrors) {
+            issues.push(`    → ${c.name}${c.filePath ? ` (${c.filePath})` : ''}`);
+        }
+    }
+    if (s.functionsMissing > 0) {
+        issues.push(`${s.functionsMissing} function(s) missing test files`);
+        const missing = (data.functions || []).filter((f) => f.status === 'missing');
+        for (const f of missing) {
+            issues.push(`    → ${f.name}${f.filePath ? ` (${f.filePath})` : ''}`);
+        }
+    }
+    if (s.functionsFailing > 0) {
+        issues.push(`${s.functionsFailing} function(s) with failing tests`);
+        const failing = (data.functions || []).filter((f) => f.status === 'failing');
+        for (const f of failing) {
+            issues.push(`    → ${f.name}${f.testFile ? ` (${f.testFile})` : ''}`);
+        }
+    }
+    if (s.functionsRunnerError > 0) {
+        issues.push(`${s.functionsRunnerError} function(s) with test runner errors (the runner crashed — not a test failure)`);
+        const runnerErrors = (data.functions || []).filter((f) => f.status === 'runner_error');
+        for (const f of runnerErrors) {
+            issues.push(`    → ${f.name}${f.testFile ? ` (${f.testFile})` : ''}`);
+        }
+    }
+    if (s.functionsNameMismatch > 0) {
+        issues.push(`${s.functionsNameMismatch} function(s) with test name mismatch`);
+        const mismatch = (data.functions || []).filter((f) => f.status === 'name_mismatch');
+        for (const f of mismatch) {
+            issues.push(`    → ${f.name}${f.testFile ? ` (${f.testFile})` : ''}`);
+        }
+    }
+    if (s.missingFromGlossary > 0)
+        issues.push(`${s.missingFromGlossary} file(s) with scenarios not in glossary`);
+    if (s.incompleteEntities > 0) {
+        const preCount = s.preExistingIncompleteEntities || 0;
+        if (preCount > 0 && preCount === s.incompleteEntities) {
+            issues.push(`${s.incompleteEntities} entity/entities need import analysis (pre-existing — not caused by your current changes, but must be fixed before proceeding)`);
+        }
+        else if (preCount > 0) {
+            issues.push(`${s.incompleteEntities} entity/entities need import analysis (${preCount} pre-existing — not from your changes)`);
+        }
+        else {
+            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 (s.scenariosNeedingRecapture > 0)
+        issues.push(`${s.scenariosNeedingRecapture} scenario(s) need recapture (dependency tree changed)`);
+    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 ────────────────────────────────────────────────
 /**
@@ -2934,28 +3141,49 @@ 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 ━━━'));
     console.log();
     // Components
     if (components.length > 0) {
+        // Build name frequency map for disambiguation
+        const componentNameCounts = new Map();
+        for (const c of components) {
+            componentNameCounts.set(c.name, (componentNameCounts.get(c.name) || 0) + 1);
+        }
         console.log(chalk.bold('Components (scenarios):'));
         for (const c of components) {
             const icon = c.status === 'ok' ? chalk.green('✓') : chalk.red('✗');
@@ -2969,7 +3197,11 @@ async function handleAudit() {
             else {
                 detail = chalk.red(' — no scenarios registered');
             }
-            console.log(`  ${icon} ${c.name}${detail}`);
+            // Show file path for failing components always, for OK only when name is ambiguous
+            const isDuplicate = (componentNameCounts.get(c.name) || 0) > 1;
+            const showPath = c.status !== 'ok' || isDuplicate;
+            const pathSuffix = showPath && c.filePath ? chalk.dim(` (${c.filePath})`) : '';
+            console.log(`  ${icon} ${c.name}${pathSuffix}${detail}`);
             if (c.clientErrors && c.clientErrors.length > 0) {
                 for (const err of c.clientErrors.slice(0, 3)) {
                     console.log(chalk.red(`      → ${err}`));
@@ -2977,6 +3209,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();
@@ -2991,6 +3231,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;
@@ -3018,6 +3266,69 @@ 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();
+    }
+    // Scenarios needing recapture (entity or dependency tree changed)
+    const scenariosNeedingRecapture = data.scenariosNeedingRecapture || [];
+    if (scenariosNeedingRecapture.length > 0) {
+        console.log(chalk.bold('Scenarios needing recapture (dependency tree changed):'));
+        for (const s of scenariosNeedingRecapture) {
+            const reason = s.status.status === 'impacted' && s.status.impactedBy?.length
+                ? `impacted by: ${s.status.impactedBy.map((d) => `${d.name} [${d.changeType}]`).join(', ')}`
+                : `${s.status.status}`;
+            console.log(`  ${chalk.red('✗')} ${s.scenarioName} ${chalk.dim(`(${s.entityName} — ${reason})`)}`);
+        }
+        console.log(chalk.yellow('    Re-register these scenarios to capture updated screenshots.'));
+        console.log();
+    }
+    // Duplicate glossary names (warning, not a failure)
+    const duplicateNames = data.duplicateNames || [];
+    if (duplicateNames.length > 0) {
+        console.log(chalk.bold('Duplicate names in glossary (confusing for audit):'));
+        for (const dn of duplicateNames) {
+            console.log(`  ${chalk.yellow('⚠')} "${dn.name}" appears ${dn.filePaths.length} times:`);
+            for (const fp of dn.filePaths) {
+                console.log(`      ${fp}`);
+            }
+        }
+        console.log(chalk.yellow('    Fix: remove duplicate entries or rename them to be unique in .codeyam/glossary.json'));
+        console.log();
+    }
     // Summary
     const allOk = summary.allPassing;
     if (allOk) {
@@ -3038,12 +3349,24 @@ 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`);
+        }
+        if (summary.scenariosNeedingRecapture > 0) {
+            parts.push(`${summary.scenariosNeedingRecapture} scenario${summary.scenariosNeedingRecapture !== 1 ? 's' : ''} need recapture`);
+        }
         console.log(chalk.red.bold('Audit failed: ') + parts.join(', '));
     }
     console.log();
@@ -3178,6 +3501,8 @@ async function handleScenarioCoverage() {
                     sha: e.sha,
                     name: e.name,
                     filePath: e.filePath || '',
+                    isDefaultExport: e.metadata?.notExported === false &&
+                        e.metadata?.namedExport === false,
                 })));
             }
         }
@@ -3723,7 +4048,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();
@@ -3762,6 +4089,11 @@ const editorCommand = {
             await handleRegister(argv.json || '');
             return;
         }
+        // Subcommand: codeyam editor glossary-add '{"name":"...", ...}'
+        if (argv.step === 'glossary-add') {
+            await handleGlossaryAdd(argv.json || '');
+            return;
+        }
         // Subcommand: codeyam editor analyze-imports
         if (argv.step === 'analyze-imports') {
             await handleAnalyzeImports();
@@ -3808,13 +4140,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;
         }
@@ -4002,6 +4331,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
@@ -4146,6 +4510,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.
@@ -4158,6 +4564,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`));
@@ -4252,8 +4660,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);
                     }
                 }