@codeyam/codeyam-cli 0.1.20 → 0.1.22

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

@@ -21,6 +21,7 @@ import { validateSeedData, detectSeedAdapter, validateSeedKeysAgainstPrisma, } f
 import { deleteScenarioViaCli } from "../utils/editorDeleteScenario.js";
 import { buildEditorApiRequest, callEditorApi, EDITOR_API_SUBCOMMANDS, } from "../utils/editorApi.js";
 import { parseRegisterArg } from "../utils/parseRegisterArg.js";
+import { classifyRegistrationResult } from "../utils/registerScenarioResult.js";
 import { sanitizeGlossaryEntries } from "../utils/editorLoaderHelpers.js";
 import { readMigrationState, writeMigrationState, advanceToNextPage, completePage, getMigrationResumeInfo, } from "../utils/editorMigration.js";
 const __filename = fileURLToPath(import.meta.url);
@@ -210,6 +211,34 @@ function checkbox(text) {
     const highlighted = text.replace(/`([^`]+)`/g, (_m, code) => chalk.cyan(code));
     console.log(`  ${chalk.dim('[ ]')} ${highlighted}`);
 }
+/**
+ * Instructions for creating/updating .codeyam/data-structure.json.
+ * Only prints creation instructions if the file doesn't exist yet.
+ * If it exists, reminds Claude to update it if data models changed.
+ */
+function printDataStructureInstructions() {
+    const root = getProjectRoot();
+    const dsPath = path.join(root, '.codeyam', 'data-structure.json');
+    const exists = fs.existsSync(dsPath);
+    if (!exists) {
+        console.log(chalk.bold('Create the data structure config:'));
+        checkbox('Create `.codeyam/data-structure.json` describing all data sources');
+        console.log(chalk.dim("  This file tells the editor what data the app uses and how it's stored."));
+        console.log(chalk.dim('  The file is a JSON array. Each entry describes one data source:'));
+        console.log(chalk.dim('  { "name": "Drink", "description": "...", "category": "datastore", "order": 1,'));
+        console.log(chalk.dim('    "fields": [{ "name": "id", "type": "number", "isId": true, "required": true }, ...] }'));
+        console.log();
+        console.log(chalk.dim('  category: "datastore" for persisted data (DB, localStorage)'));
+        console.log(chalk.dim('           "mock-api" for mocked external API responses'));
+        console.log(chalk.dim('  order: 1 = primary data store, 2 = secondary, etc.'));
+        console.log(chalk.dim('  Do NOT include types only used as component props.'));
+    }
+    else {
+        checkbox('If this feature changes data models, update `.codeyam/data-structure.json`');
+        console.log(chalk.dim('  Add new tables, update fields, or change descriptions to match.'));
+    }
+    console.log();
+}
 /**
  * Shared app scenario registration instructions used by editor Step 8 and migration Steps 1/6.
  * Prints seed-based scenarios, mock-based fallback, @ file prefix, externalApis, url requirement, and error checking.
@@ -328,7 +357,7 @@ function printExtractionPlanInstructions() {
  */
 function printComponentCaptureInstructions() {
     checkbox('Create isolation route dirs: `codeyam editor isolate ComponentA ComponentB ...`');
-    console.log(chalk.dim('    This creates app/codeyam-isolate/layout.tsx (with production notFound() guard) and'));
+    console.log(chalk.dim('    This creates app/isolated-components/layout.tsx (with production notFound() guard) and'));
     console.log(chalk.dim('    a directory per component. List ALL components that need isolation routes.'));
     checkbox('For each visual component:');
     console.log(chalk.dim('    1. Read the source AND find where it is used in the app to understand:'));
@@ -340,8 +369,8 @@ function printComponentCaptureInstructions() {
     console.log(chalk.dim('       — Different visual states: loading, error, disabled, selected, hover'));
     console.log(chalk.dim('       — Boundary values: single item vs many, min/max ratings, very long names'));
     console.log(chalk.dim('    3. Create ONE isolation route per component with a scenarios map and ?s= query param:'));
-    console.log(chalk.dim('       Remix:   app/routes/codeyam-isolate.ComponentName.tsx → /codeyam-isolate/ComponentName'));
-    console.log(chalk.dim('       Next.js: app/codeyam-isolate/ComponentName/page.tsx → /codeyam-isolate/ComponentName'));
+    console.log(chalk.dim('       Remix:   app/routes/isolated-components.ComponentName.tsx → /isolated-components/ComponentName'));
+    console.log(chalk.dim('       Next.js: app/isolated-components/ComponentName/page.tsx → /isolated-components/ComponentName'));
     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":'));
@@ -354,9 +383,9 @@ function printComponentCaptureInstructions() {
     console.log(chalk.dim('    4. Wait 2 seconds for HMR, then register + capture each scenario:'));
     console.log(chalk.dim(`       codeyam editor register '{"name":"ComponentName - Scenario",`));
     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(`         "url":"/isolated-components/ComponentName?s=Scenario",`));
     console.log(chalk.dim(`         "mockData":{"routes":{"/api/...":{"body":[...]}}}}'`));
-    console.log(chalk.yellow('       IMPORTANT: url MUST be an isolation route (/codeyam-isolate/... or /isolated-components/...).'));
+    console.log(chalk.yellow('       IMPORTANT: url MUST be an isolation route (/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)'));
@@ -366,7 +395,7 @@ function printComponentCaptureInstructions() {
     console.log(chalk.dim('    Isolation routes are committed to git — the layout guard blocks them in production'));
     console.log();
     console.log(chalk.bold('  Bulk registration: write all component scenarios to a temp file as an array:'));
-    console.log(chalk.dim('    [{"name":"Comp - Default","componentName":"Comp","componentPath":"...","url":"/codeyam-isolate/Comp?s=Default"}, ...]'));
+    console.log(chalk.dim('    [{"name":"Comp - Default","componentName":"Comp","componentPath":"...","url":"/isolated-components/Comp?s=Default"}, ...]'));
     console.log(chalk.dim('    codeyam editor register @.codeyam/tmp/scenarios.json'));
 }
 /**
@@ -419,7 +448,9 @@ function stopGate(current, opts) {
     // Skip step 1 (no feature name yet — task starts at step 2)
     if (current >= 2) {
         console.log(chalk.bold.cyan('━━━ TASK ━━━'));
-        console.log(chalk.cyan('Mark your current task (if any) as complete.'));
+        console.log(chalk.cyan('Before creating the task below, delete ALL existing tasks:'));
+        console.log(chalk.cyan('  1. Run TaskList to find all tasks'));
+        console.log(chalk.cyan('  2. Run TaskUpdate with status "deleted" for EACH task returned'));
         console.log(chalk.cyan('Then create a new task with this EXACT title (copy verbatim):'));
         console.log();
         let taskTitle;
@@ -978,6 +1009,7 @@ function printStep2(root, feature) {
         console.log(chalk.dim('  Key: import { prisma } from "@/app/lib/prisma" in API routes.'));
         console.log(chalk.dim('  Key: Seed scripts must use the adapter pattern (see prisma/seed.ts).'));
         console.log();
+        printDataStructureInstructions();
     }
     else {
         console.log(chalk.bold('Prepare the database for this feature:'));
@@ -992,6 +1024,7 @@ function printStep2(root, feature) {
         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();
+        printDataStructureInstructions();
     }
     stopGate(2);
 }
@@ -1326,7 +1359,13 @@ function printStep9(root, feature) {
     console.log();
     checkbox('Run `codeyam editor audit` to verify all components have scenarios and all functions/hooks have tests');
     console.log(chalk.red.bold('    The audit is a HARD GATE — step 10 will refuse to run until the audit passes.'));
-    console.log(chalk.dim('    When audit passes, the import graph is built automatically for change tracking.'));
+    console.log(chalk.dim('    The audit auto-fixes incomplete entities by running targeted analysis on just the affected files.'));
+    console.log(chalk.dim('    If the audit reports issues (including pre-existing ones), fix ALL of them — do not skip.'));
+    console.log(chalk.dim('    Re-run `codeyam editor audit` until all checks pass. Do NOT run `codeyam editor analyze-imports`'));
+    console.log(chalk.dim('    — the audit runs targeted analysis automatically and is much faster.'));
+    console.log(chalk.dim('    If the audit reports "MANUAL ANALYSIS REQUIRED" for any entities,'));
+    console.log(chalk.dim('    follow the manual analysis steps in the audit output.'));
+    console.log(chalk.dim('    Do NOT re-run analyze-imports for those entities — it will fail again.'));
     console.log();
     stopGate(9);
 }
@@ -1928,7 +1967,7 @@ function printMigrateStep8(root) {
     console.log(chalk.bold.red('Re-register App Scenarios (REQUIRED):'));
     console.log(chalk.yellow(`  You MUST re-register application scenarios for "${page.route}" to get fresh screenshots.`));
     checkbox('Fetch existing scenarios: `codeyam editor scenarios`');
-    checkbox('Find all scenarios that use the real page route (not /codeyam-isolate/ paths)');
+    checkbox('Find all scenarios that use the real page route (not /isolated-components/ paths)');
     checkbox('Re-register each one with the SAME name to update its screenshot');
     console.log(chalk.dim(`    Example: codeyam editor register '{"name":"${pageName} - Full Data","type":"application","url":"${page.route}",...}'`));
     checkbox('After each registration, check the response for `clientErrors`');
@@ -2362,25 +2401,132 @@ async function handleAnalyzeImports(options = {}) {
         // Non-fatal — scenario file paths just won't be included
     }
     const progress = new ProgressReporter();
-    // Run data-structure-only analysis for all entities (glossary + pages)
+    // Filter to only files that actually need analysis — avoids re-analyzing
+    // ~120 files when only 2 are incomplete.
+    let targetFilePaths = filePaths;
+    try {
+        const { getDatabase } = await import('../../../packages/database/index.js');
+        const db = getDatabase();
+        const { requireBranchAndProject: rbp } = await import('../utils/database.js');
+        const { project } = await rbp(JSON.parse(fs.readFileSync(path.join(root, '.codeyam', 'config.json'), 'utf8')).projectSlug);
+        const { filterToIncompleteFilePaths } = await import('../utils/editorAudit.js');
+        const incomplete = await filterToIncompleteFilePaths(db, project.id, filePaths);
+        if (incomplete.length < filePaths.length && incomplete.length > 0) {
+            if (!options.silent) {
+                console.log(chalk.dim(`Skipping ${filePaths.length - incomplete.length} already-analyzed files, analyzing ${incomplete.length} remaining...`));
+            }
+            targetFilePaths = incomplete;
+        }
+        else if (incomplete.length === 0) {
+            if (!options.silent) {
+                console.log(chalk.green('All entities already have analyses — nothing to do.'));
+            }
+            // Still need to run the import graph + backfill below
+            targetFilePaths = [];
+        }
+    }
+    catch {
+        // Non-fatal — fall back to analyzing all files
+    }
+    // Run data-structure-only analysis for entities that need it.
     // Don't pass entityNames — entities may not exist yet (fresh clone).
     // The analyzer will discover and create them from file paths.
-    progress.start('Running import analysis for all entities...');
-    try {
-        await runAnalysisForEntities({
-            projectRoot: root,
-            filePaths,
-            progress,
-            onlyDataStructure: true,
-        });
+    if (targetFilePaths.length > 0) {
+        progress.start(`Running import analysis for ${targetFilePaths.length} entit${targetFilePaths.length !== 1 ? 'ies' : 'y'}...`);
+        try {
+            await runAnalysisForEntities({
+                projectRoot: root,
+                filePaths: targetFilePaths,
+                progress,
+                onlyDataStructure: true,
+            });
+        }
+        catch (err) {
+            progress.fail('Analysis failed');
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(chalk.red(`Error: ${msg}`));
+            process.exit(1);
+        }
+        progress.succeed('Analysis complete');
     }
-    catch (err) {
-        progress.fail('Analysis failed');
-        const msg = err instanceof Error ? err.message : String(err);
-        console.error(chalk.red(`Error: ${msg}`));
-        process.exit(1);
+    // Surface analysis errors if any occurred
+    const errorReportPath = path.join(root, '.codeyam', 'analysis-errors.txt');
+    if (fs.existsSync(errorReportPath)) {
+        if (!options.silent) {
+            console.log(chalk.yellow('\nSome entity analyses failed. Full details in .codeyam/analysis-errors.txt'));
+            console.log(chalk.yellow('Send this file to the CodeYam team for diagnosis.'));
+            console.log(chalk.dim('Affected entities will be missing from the import graph.'));
+        }
+        // Write structured analysis-failures.json for the audit to detect.
+        // Parse the error report to find which entities failed, and cross-reference
+        // with the files we tried to analyze.
+        try {
+            const { readAnalysisFailures, writeAnalysisFailures } = await import('../utils/manualEntityAnalysis.js');
+            const errorContent = fs.readFileSync(errorReportPath, 'utf8');
+            const existingFailures = readAnalysisFailures(root);
+            // Parse error messages to identify failed file paths.
+            // Error format: "Error on step <StepName> for entity <Name> (<filePath>)"
+            // or more generic "CodeYam Error: <message>"
+            const entityErrorRegex = /(?:Error on step \w+ for entity (\w+))|(?:entity[: ]+["']?(\w+)["']?)/gi;
+            const failedEntityNames = new Set();
+            let match;
+            while ((match = entityErrorRegex.exec(errorContent)) !== null) {
+                const name = match[1] || match[2];
+                if (name)
+                    failedEntityNames.add(name);
+            }
+            // Map failed entity names back to file paths from targetFilePaths
+            const glossaryPath = path.join(root, '.codeyam', 'glossary.json');
+            let glossary = [];
+            try {
+                glossary = sanitizeGlossaryEntries(JSON.parse(fs.readFileSync(glossaryPath, 'utf8')));
+            }
+            catch {
+                // Non-fatal
+            }
+            // Also: any targetFilePaths that didn't produce entities are failures
+            const now = new Date().toISOString();
+            const updatedFailures = { ...existingFailures };
+            if (failedEntityNames.size > 0) {
+                for (const name of failedEntityNames) {
+                    const entry = glossary.find((e) => e.name === name);
+                    if (entry) {
+                        updatedFailures[entry.filePath] = {
+                            entityName: name,
+                            error: `Automated analysis failed — see .codeyam/analysis-errors.txt`,
+                            failedAt: now,
+                        };
+                    }
+                }
+            }
+            else if (targetFilePaths.length > 0) {
+                // Couldn't parse specific entity names — mark all target files
+                // that we attempted to analyze as potentially failed
+                for (const fp of targetFilePaths) {
+                    const entry = glossary.find((e) => e.filePath === fp);
+                    updatedFailures[fp] = {
+                        entityName: entry?.name || path.basename(fp, path.extname(fp)),
+                        error: `Automated analysis failed — see .codeyam/analysis-errors.txt`,
+                        failedAt: now,
+                    };
+                }
+            }
+            writeAnalysisFailures(root, updatedFailures);
+        }
+        catch {
+            // Non-fatal — failure tracking is best-effort
+        }
+    }
+    else {
+        // No errors — clear any stale failure tracking
+        try {
+            const { writeAnalysisFailures } = await import('../utils/manualEntityAnalysis.js');
+            writeAnalysisFailures(root, {});
+        }
+        catch {
+            // Non-fatal
+        }
     }
-    progress.succeed('Analysis complete');
     // Load entities WITH metadata from database
     progress.start('Loading entity metadata...');
     await initializeEnvironment();
@@ -2736,6 +2882,8 @@ async function handleRegister(jsonArg) {
     const isBatch = items.length > 1;
     let succeeded = 0;
     let failed = 0;
+    let warnings = 0;
+    const issues = [];
     const screenshotEntries = [];
     for (let i = 0; i < items.length; i++) {
         const body = items[i];
@@ -2805,11 +2953,14 @@ async function handleRegister(jsonArg) {
                 }
                 console.log(chalk.yellow('  Fix the issue and re-register this scenario.'));
             }
+            const resultIssues = classifyRegistrationResult(res.ok, res.status, data, String(body.name || `item ${i + 1}`));
             if (!res.ok) {
                 console.error(chalk.dim(JSON.stringify(data, null, 2)));
                 failed++;
             }
             else {
+                if (resultIssues.length > 0)
+                    warnings++;
                 succeeded++;
                 // Collect screenshot paths for duplicate detection
                 if (data.screenshotCaptured &&
@@ -2822,6 +2973,10 @@ async function handleRegister(jsonArg) {
                     });
                 }
             }
+            // Collect issues from this registration
+            for (const issue of resultIssues) {
+                issues.push(`"${issue.scenarioName}": ${issue.message}`);
+            }
         }
         catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
@@ -2833,7 +2988,7 @@ async function handleRegister(jsonArg) {
     }
     // Detect duplicate screenshots in the batch
     if (isBatch && screenshotEntries.length > 1) {
-        const { computeScreenshotHash, findDuplicateScreenshots } = await import('../utils/screenshotHash');
+        const { computeScreenshotHash, findDuplicateScreenshots } = await import('../utils/screenshotHash.js');
         const hashEntries = screenshotEntries
             .map((e) => {
             const hash = computeScreenshotHash(e.screenshotAbsPath);
@@ -2859,9 +3014,22 @@ async function handleRegister(jsonArg) {
         }
     }
     if (isBatch) {
-        console.log(chalk.dim(`\nBatch complete: ${succeeded}/${items.length} succeeded`));
+        console.log('');
+        if (failed > 0 || warnings > 0) {
+            console.log(chalk.red.bold(`ERROR: ${failed} failed, ${warnings} with warnings out of ${items.length} scenarios`));
+            console.log('');
+            console.log(chalk.red.bold('Issues that MUST be fixed:'));
+            for (const issue of issues) {
+                console.log(chalk.red(`  ✗ ${issue}`));
+            }
+            console.log('');
+            console.log(chalk.red('Do NOT skip these errors. Fix each issue and re-register the affected scenarios.'));
+        }
+        else {
+            console.log(chalk.green(`✓ Batch complete: ${succeeded}/${items.length} succeeded with no issues`));
+        }
     }
-    if (failed > 0) {
+    if (failed > 0 || warnings > 0) {
         process.exit(1);
     }
 }
@@ -3150,10 +3318,11 @@ function handleChange(feature) {
  * Fetch the audit result from the server.
  * Returns null if the server is unreachable.
  */
-async function fetchAuditResult() {
+async function fetchAuditResult(options) {
     const port = getServerPort();
+    const params = options?.skipTests ? '?skipTests=true' : '';
     try {
-        const res = await fetch(`http://localhost:${port}/api/editor-audit`);
+        const res = await fetch(`http://localhost:${port}/api/editor-audit${params}`);
         if (!res.ok)
             return null;
         return await res.json();
@@ -3176,17 +3345,15 @@ async function checkAuditGate() {
         return true; // Server unreachable — don't block
     if (data.summary?.allPassing === true)
         return true;
-    // If incomplete entities / unassociated scenarios are the only issue,
-    // auto-fix with analyze-imports + entity SHA backfill (once)
-    const { isAutoRemediable } = await import('../utils/editorAudit.js');
-    if (isAutoRemediable(data.summary, false)) {
-        try {
-            await handleAnalyzeImports({ silent: true });
-        }
-        catch {
-            // Fall through to backfill attempt
-        }
-        // Backfill entity_sha on scenarios registered before entities existed
+    // Lightweight auto-fix: backfill entity_sha (DB-only, fast).
+    // Never run handleAnalyzeImports here — it takes minutes on large projects.
+    const { isOnlyIncompleteEntities, isOnlyPreExistingIncomplete } = await import('../utils/editorAudit.js');
+    // If the only failures are pre-existing incomplete entities (not caused by
+    // this session), don't block — the audit text already calls these "non-blocking".
+    if (isOnlyPreExistingIncomplete(data.summary, data.incompleteEntities)) {
+        return true;
+    }
+    if (isOnlyIncompleteEntities(data.summary)) {
         try {
             const entities = await loadEntities({});
             if (entities && entities.length > 0) {
@@ -3204,8 +3371,8 @@ async function checkAuditGate() {
         catch {
             // Fall through
         }
-        // Re-check after fix
-        const retry = await fetchAuditResult();
+        // Re-check after backfill — skip re-running tests (backfill is DB-only)
+        const retry = await fetchAuditResult({ skipTests: true });
         if (retry?.summary?.allPassing === true)
             return true;
     }
@@ -3228,6 +3395,8 @@ function printAuditGateFailures(data) {
         const missing = (data.components || []).filter((c) => c.status === 'missing');
         for (const c of missing) {
             issues.push(`    → ${c.name}${c.filePath ? ` (${c.filePath})` : ''}`);
+            if (c.hint)
+                issues.push(`      Fix: ${c.hint}`);
         }
     }
     if (s.componentsWithErrors > 0) {
@@ -3241,7 +3410,15 @@ function printAuditGateFailures(data) {
         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 (f.testFile) {
+                issues.push(`    → ${f.name} — test file missing: ${f.testFile}`);
+            }
+            else {
+                issues.push(`    → ${f.name} (${f.filePath}) — no testFile in glossary`);
+                if (f.suggestedTestFile) {
+                    issues.push(`      Fix: Create ${f.suggestedTestFile} or add "testFile": "${f.suggestedTestFile}" to .codeyam/glossary.json`);
+                }
+            }
         }
     }
     if (s.functionsFailing > 0) {
@@ -3256,6 +3433,10 @@ function printAuditGateFailures(data) {
         const runnerErrors = (data.functions || []).filter((f) => f.status === 'runner_error');
         for (const f of runnerErrors) {
             issues.push(`    → ${f.name}${f.testFile ? ` (${f.testFile})` : ''}`);
+            if (f.hint)
+                issues.push(`      ${f.hint}`);
+            else if (f.errorMessage)
+                issues.push(`      Error: ${f.errorMessage}`);
         }
     }
     if (s.functionsNameMismatch > 0) {
@@ -3263,13 +3444,36 @@ function printAuditGateFailures(data) {
         const mismatch = (data.functions || []).filter((f) => f.status === 'name_mismatch');
         for (const f of mismatch) {
             issues.push(`    → ${f.name}${f.testFile ? ` (${f.testFile})` : ''}`);
+            if (f.hint)
+                issues.push(`      Fix: ${f.hint}`);
         }
     }
-    if (s.missingFromGlossary > 0)
+    if (s.missingFromGlossary > 0) {
         issues.push(`${s.missingFromGlossary} file(s) with scenarios not in glossary`);
+        const missingGlossary = data.missingFromGlossary || [];
+        for (const m of missingGlossary) {
+            issues.push(`    → ${m.name} (${m.filePath})`);
+        }
+        issues.push(`      Fix: Run \`codeyam editor analyze-imports\` to add these files to the glossary`);
+    }
     if (s.incompleteEntities > 0) {
+        // Check for persistent analysis failures
+        let analysisFailures = {};
+        try {
+            const failuresPath = path.join(getProjectRoot(), '.codeyam', 'analysis-failures.json');
+            if (fs.existsSync(failuresPath)) {
+                analysisFailures = JSON.parse(fs.readFileSync(failuresPath, 'utf8'));
+            }
+        }
+        catch {
+            // Non-fatal
+        }
         const preCount = s.preExistingIncompleteEntities || 0;
-        if (preCount > 0 && preCount === s.incompleteEntities) {
+        const hasFailures = Object.keys(analysisFailures).length > 0;
+        if (hasFailures) {
+            issues.push(`${s.incompleteEntities} entity/entities — automated analysis failed, manual analysis required`);
+        }
+        else 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) {
@@ -3278,6 +3482,20 @@ function printAuditGateFailures(data) {
         else {
             issues.push(`${s.incompleteEntities} entity/entities need import analysis`);
         }
+        const incomplete = data.incompleteEntities || [];
+        for (const e of incomplete) {
+            const failureEntry = Object.values(analysisFailures).find((f) => f.entityName === e.name);
+            if (failureEntry) {
+                issues.push(`    → ${e.name} — MANUAL ANALYSIS REQUIRED (automated analysis failed)`);
+                issues.push(`      Run \`codeyam editor audit\` for step-by-step manual analysis instructions`);
+            }
+            else {
+                issues.push(`    → ${e.name} (${e.scenarioCount} scenario${e.scenarioCount !== 1 ? 's' : ''})${e.preExisting ? ' [pre-existing]' : ''}`);
+            }
+        }
+        if (!hasFailures) {
+            issues.push(`      Fix: Run \`codeyam editor analyze-imports\` to build import graphs`);
+        }
     }
     if (s.unassociatedScenarios > 0) {
         issues.push(`${s.unassociatedScenarios} component(s) have scenarios with no entity link — run \`codeyam editor analyze-imports\` then re-run audit`);
@@ -3286,10 +3504,22 @@ function printAuditGateFailures(data) {
             issues.push(`    → ${u.name} (${u.filePath}) — ${u.scenarioCount} scenario${u.scenarioCount !== 1 ? 's' : ''}`);
         }
     }
-    if (s.miscategorizedScenarios > 0)
+    if (s.miscategorizedScenarios > 0) {
         issues.push(`${s.miscategorizedScenarios} component(s) using page URLs instead of isolation routes`);
-    if (s.scenariosNeedingRecapture > 0)
+        const miscategorized = data.miscategorizedScenarios || [];
+        for (const m of miscategorized) {
+            issues.push(`    → ${m.componentName} at ${m.url} (${m.scenarioNames.length} scenario${m.scenarioNames.length !== 1 ? 's' : ''})`);
+        }
+        issues.push(`      Fix: Re-register these as app-level scenarios (with pageFilePath, no componentName) or use isolation routes`);
+    }
+    if (s.scenariosNeedingRecapture > 0) {
         issues.push(`${s.scenariosNeedingRecapture} scenario(s) need recapture (dependency tree changed)`);
+        const recapture = data.scenariosNeedingRecapture || [];
+        for (const r of recapture) {
+            issues.push(`    → "${r.scenarioName}" (entity: ${r.entityName}, ${r.status?.status || 'changed'})`);
+        }
+        issues.push(`      Fix: Re-capture affected scenarios to update screenshots after code changes`);
+    }
     if (issues.length > 0) {
         console.error(chalk.yellow('\nAudit failures:'));
         for (const issue of issues) {
@@ -3330,22 +3560,16 @@ async function handleAudit() {
         console.error(chalk.red('Error: Could not reach the CodeYam server. Is it running?'));
         process.exit(1);
     }
-    // Auto-fix incomplete entities and unassociated scenarios — but only once.
-    // If analyze-imports + entity SHA sync runs and issues persist, 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.
+    // Lightweight auto-fix: backfill entity_sha on scenarios that were
+    // registered before entity records existed. This is fast (DB-only).
+    // Import analysis is NOT triggered here — it scans all files and takes
+    // minutes on large projects. Users should run it separately if needed.
     const incompleteBeforeFix = data.incompleteEntities || [];
     const unassociatedBeforeFix = data.unassociatedScenarios || [];
     let autoRemediationFailed = false;
     if (incompleteBeforeFix.length > 0 || unassociatedBeforeFix.length > 0) {
         const issueCount = incompleteBeforeFix.length + unassociatedBeforeFix.length;
-        console.log(chalk.dim(`Auto-fixing ${issueCount} entity association issue${issueCount !== 1 ? 's' : ''}...`));
-        try {
-            await handleAnalyzeImports({ silent: true });
-        }
-        catch {
-            // Fall through — the audit will still report them
-        }
+        console.log(chalk.dim(`Backfilling ${issueCount} entity association issue${issueCount !== 1 ? 's' : ''}...`));
         // Backfill entity_sha on scenarios that were registered before entities existed
         try {
             const entities = await loadEntities({});
@@ -3364,13 +3588,14 @@ async function handleAudit() {
         catch {
             // Fall through — re-fetch will show remaining issues
         }
-        // Re-fetch audit results after the fix
-        data = await fetchAuditResult();
+        // Re-fetch audit results after the backfill — skip re-running tests
+        // since they haven't changed (backfill is DB-only).
+        data = await fetchAuditResult({ skipTests: true });
         if (!data) {
-            console.error(chalk.red('Error: Could not reach the CodeYam server after auto-fix.'));
+            console.error(chalk.red('Error: Could not reach the CodeYam server after backfill.'));
             process.exit(1);
         }
-        // If issues persist after auto-fix, flag it so we show clear guidance
+        // If issues persist after backfill, flag it so we show clear guidance
         const incompleteAfterFix = data.incompleteEntities || [];
         const unassociatedAfterFix = data.unassociatedScenarios || [];
         if (incompleteAfterFix.length > 0 || unassociatedAfterFix.length > 0) {
@@ -3407,6 +3632,9 @@ async function handleAudit() {
             }
             else {
                 detail = chalk.red(' — no scenarios registered');
+                if (c.hint) {
+                    detail += `\n      ${chalk.yellow('Fix: ' + c.hint)}`;
+                }
             }
             // Show file path for failing components always, for OK only when name is ambiguous
             const isDuplicate = (componentNameCounts.get(c.name) || 0) > 1;
@@ -3450,9 +3678,16 @@ async function handleAudit() {
                     break;
                 case 'missing':
                 default:
-                    detail = f.testFile
-                        ? chalk.red(` — test file missing: ${f.testFile}`)
-                        : chalk.red(' — no test file specified');
+                    if (f.testFile) {
+                        detail = chalk.red(` — test file missing: ${f.testFile}`);
+                    }
+                    else {
+                        detail = chalk.red(` — no test file specified in glossary`);
+                        detail += chalk.dim(` (source: ${f.filePath})`);
+                        if (f.suggestedTestFile) {
+                            detail += `\n      ${chalk.yellow(`Fix: Either create ${f.suggestedTestFile} or add "testFile": "${f.suggestedTestFile}" to this entry in .codeyam/glossary.json`)}`;
+                        }
+                    }
                     break;
             }
             console.log(`  ${icon} ${f.name}${detail}`);
@@ -3469,19 +3704,42 @@ 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)
+    // Incomplete entities (scenarios without analyses) — report with guidance.
+    // We intentionally do NOT run analysis here: it starts the analyzer
+    // template which is slow even for a few files. Users should run
+    // `codeyam editor analyze-imports` separately if needed.
     const incompleteEntities = data.incompleteEntities || [];
     if (incompleteEntities.length > 0) {
+        const { formatIncompleteEntityGuidance, formatManualAnalysisGuidance } = await import('../utils/editorAudit.js');
+        const { readAnalysisFailures } = await import('../utils/manualEntityAnalysis.js');
+        // Check for persistent analysis failures
+        const analysisFailures = readAnalysisFailures(getProjectRoot());
         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.yellow('    analyze-imports ran automatically but could not resolve these.'));
-            console.log(chalk.yellow('    Run `codeyam editor analyze-imports` to see the full error output.'));
+            // Check if this entity has a persistent failure
+            const failureEntry = Object.values(analysisFailures).find((f) => f.entityName === e.name);
+            if (failureEntry) {
+                // Show manual analysis instructions instead of "run analyze-imports"
+                const filePath = Object.entries(analysisFailures).find(([, f]) => f.entityName === e.name)?.[0];
+                const guidance = formatManualAnalysisGuidance({
+                    name: e.name,
+                    filePath: filePath || '',
+                    scenarioCount: e.scenarioCount,
+                    error: failureEntry.error,
+                });
+                // Print each line with proper indentation
+                for (const line of guidance.split('\n')) {
+                    console.log(`  ${chalk.red('✗')} ${line}`);
+                }
+            }
+            else {
+                const guidance = formatIncompleteEntityGuidance(e);
+                console.log(`  ${chalk.red('✗')} ${guidance}`);
+            }
         }
-        else {
-            console.log(chalk.yellow('    Run `codeyam editor analyze-imports` to analyze these entities.'));
+        const incompleteErrorReportPath = path.join(getProjectRoot(), '.codeyam', 'analysis-errors.txt');
+        if (fs.existsSync(incompleteErrorReportPath)) {
+            console.log(chalk.dim('    See .codeyam/analysis-errors.txt for error details.'));
         }
         console.log();
     }
@@ -3505,6 +3763,10 @@ async function handleAudit() {
         else {
             console.log(chalk.yellow('    Run `codeyam editor analyze-imports` to create entity records, then re-run audit to backfill.'));
         }
+        const unassocErrorReportPath = path.join(getProjectRoot(), '.codeyam', 'analysis-errors.txt');
+        if (fs.existsSync(unassocErrorReportPath)) {
+            console.log(chalk.dim('    See .codeyam/analysis-errors.txt for error details.'));
+        }
         console.log();
     }
     // Miscategorized scenarios (component scenarios using real page URLs)
@@ -3595,17 +3857,6 @@ async function handleAudit() {
     if (!allOk) {
         process.exit(1);
     }
-    // Auto-run analyze-imports when audit passes — this builds the import graph
-    // so the App tab can show component/function dependencies for each page.
-    // Previously this was a manual step that Claude had to remember to run.
-    console.log(chalk.dim('Building import graph...'));
-    try {
-        await handleAnalyzeImports({ silent: true });
-    }
-    catch {
-        // Non-fatal — audit passed, import graph is a bonus
-        console.log(chalk.yellow('Warning: Could not build import graph. Run `codeyam editor analyze-imports` manually.'));
-    }
 }
 // ─── Recapture-stale subcommand ────────────────────────────────────────
 /**
@@ -3812,14 +4063,14 @@ 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 { countScenariosNeedingEntityBackfill } = await import('../utils/editorScenarios.js');
         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 { backfillEntityShaOnScenarios } = await import('../utils/editorScenarios.js');
             const entities = await loadEntities({});
             if (entities && entities.length > 0) {
                 await backfillEntityShaOnScenarios(db, entities.map((e) => ({
@@ -4316,14 +4567,205 @@ function handleEditorDebug(args) {
     console.log(chalk.dim('  Open index.md for the full list of scenario outputs.'));
     console.log();
 }
+// ─── Manual entity analysis ───────────────────────────────────────────
+/**
+ * `codeyam editor manual-entity <JSON|@file>`
+ *
+ * Creates entity and analysis records from Claude-provided metadata when
+ * automated analyze-imports fails. This unblocks the audit gate without
+ * needing the analyzer template to parse the source file.
+ */
+async function handleManualEntity(jsonArg) {
+    const root = getProjectRoot();
+    // Parse JSON input (supports @file.json convention)
+    const parsed = parseRegisterArg(jsonArg);
+    if (parsed.error || !parsed.body) {
+        console.error(chalk.red(`Error: ${parsed.error || 'Invalid input'}`));
+        console.error(chalk.dim('  Usage: codeyam editor manual-entity \'{"name":"Header","filePath":"src/components/Header.tsx","entityType":"visual",...}\''));
+        console.error(chalk.dim('  Or: codeyam editor manual-entity @.codeyam/tmp/manual-entity.json'));
+        process.exit(1);
+    }
+    const input = parsed.body;
+    // Validate input
+    const { validateManualEntityInput, convertTypeInfoToDataForMocks, readAnalysisFailures, clearFailureForPath, writeAnalysisFailures, } = await import('../utils/manualEntityAnalysis.js');
+    // Read glossary for validation
+    const glossaryPath = path.join(root, '.codeyam', 'glossary.json');
+    let glossaryEntries = [];
+    try {
+        glossaryEntries = sanitizeGlossaryEntries(JSON.parse(fs.readFileSync(glossaryPath, 'utf8')));
+    }
+    catch {
+        // Empty glossary — validation will still check file existence
+    }
+    const errors = validateManualEntityInput(input, glossaryEntries, {
+        fileExists: (p) => fs.existsSync(path.join(root, p)),
+    });
+    if (errors.length > 0) {
+        console.error(chalk.red('Validation errors:'));
+        for (const err of errors) {
+            console.error(chalk.red(`  • ${err}`));
+        }
+        process.exit(1);
+    }
+    // Read source file and compute SHA
+    const sourceContent = fs.readFileSync(path.join(root, input.filePath), 'utf8');
+    const { generateSha } = await import('../../../packages/database/index.js');
+    const entitySha = generateSha(input.filePath, input.name, sourceContent);
+    // Get project and branch
+    await initializeEnvironment();
+    const configPath = path.join(root, '.codeyam', 'config.json');
+    let projectSlug;
+    try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        projectSlug = config.projectSlug;
+    }
+    catch {
+        console.error(chalk.red('Error: .codeyam/config.json not found or invalid.'));
+        process.exit(1);
+    }
+    const { project, branch } = await requireBranchAndProject(projectSlug);
+    const { getDatabase } = await import('../../../packages/database/index.js');
+    const db = getDatabase();
+    // Convert type info to dataForMocks format
+    const dataForMocks = convertTypeInfoToDataForMocks(input.typeInfo);
+    // Create entity record
+    const entityMetadata = {
+        importedExports: (input.importedExports || []).map((ie) => ({
+            name: ie.name,
+            filePath: ie.filePath,
+        })),
+        manuallyAnalyzed: true,
+    };
+    // Check if entity already exists
+    const existingEntity = await db
+        .selectFrom('entities')
+        .select('sha')
+        .where('sha', '=', entitySha)
+        .executeTakeFirst();
+    if (!existingEntity) {
+        await db
+            .insertInto('entities')
+            .values({
+            sha: entitySha,
+            project_id: project.id,
+            name: input.name,
+            entity_type: input.entityType,
+            file_path: input.filePath,
+            metadata: JSON.stringify(entityMetadata),
+        })
+            .onConflict((oc) => oc.column('sha').doNothing())
+            .execute();
+        console.log(chalk.dim(`Created entity record: ${input.name} (${entitySha.slice(0, 8)}...)`));
+    }
+    else {
+        // Update metadata on existing entity
+        await db
+            .updateTable('entities')
+            .set({
+            metadata: JSON.stringify(entityMetadata),
+        })
+            .where('sha', '=', entitySha)
+            .execute();
+        console.log(chalk.dim(`Updated existing entity: ${input.name} (${entitySha.slice(0, 8)}...)`));
+    }
+    // Create entity_branch record
+    await db
+        .insertInto('entity_branches')
+        .values({
+        entity_sha: entitySha,
+        branch_id: branch.id,
+        active: true,
+    })
+        .onConflict((oc) => oc.columns(['entity_sha', 'branch_id']).doUpdateSet({ active: true }))
+        .execute();
+    // Create analysis record
+    const { randomUUID } = await import('crypto');
+    const analysisId = randomUUID();
+    const now = new Date().toISOString();
+    const analysisMetadata = {
+        scenariosDataStructure: {
+            dataForMocks: Object.keys(dataForMocks).length > 0 ? dataForMocks : null,
+        },
+        mergedDataStructure: {
+            dependencySchemas: null,
+        },
+        manuallyAnalyzed: true,
+    };
+    const analysisStatus = {
+        startedAt: now,
+        finishedAt: now,
+        steps: [],
+        errors: [],
+    };
+    // Check if analysis already exists for this entity
+    const existingAnalysis = await db
+        .selectFrom('analyses')
+        .select('id')
+        .where('entity_sha', '=', entitySha)
+        .executeTakeFirst();
+    if (!existingAnalysis) {
+        await db
+            .insertInto('analyses')
+            .values({
+            id: analysisId,
+            project_id: project.id,
+            entity_sha: entitySha,
+            entity_name: input.name,
+            entity_type: input.entityType,
+            file_path: input.filePath,
+            status: JSON.stringify(analysisStatus),
+            metadata: JSON.stringify(analysisMetadata),
+        })
+            .execute();
+        console.log(chalk.dim(`Created analysis record: ${analysisId.slice(0, 8)}...`));
+    }
+    else {
+        // Update existing analysis with manual metadata
+        await db
+            .updateTable('analyses')
+            .set({
+            metadata: JSON.stringify(analysisMetadata),
+            status: JSON.stringify(analysisStatus),
+        })
+            .where('entity_sha', '=', entitySha)
+            .execute();
+        console.log(chalk.dim(`Updated existing analysis for ${input.name}`));
+    }
+    // Backfill entity_sha on scenarios
+    const backfillResult = await backfillEntityShaOnScenarios(db, [
+        {
+            sha: entitySha,
+            name: input.name,
+            filePath: input.filePath,
+            isDefaultExport: false,
+        },
+    ]);
+    if (backfillResult.updated > 0) {
+        console.log(chalk.dim(`Linked ${backfillResult.updated} scenario(s) to entity`));
+    }
+    // Clear from analysis failures tracker
+    const failures = readAnalysisFailures(root);
+    if (failures[input.filePath]) {
+        const updated = clearFailureForPath(failures, input.filePath);
+        writeAnalysisFailures(root, updated);
+        console.log(chalk.dim(`Cleared analysis failure for ${input.filePath}`));
+    }
+    console.log();
+    console.log(chalk.green.bold(`✓ Manual entity analysis complete: ${input.name}`));
+    console.log(chalk.dim(`  Entity SHA: ${entitySha.slice(0, 12)}...`));
+    console.log(chalk.dim(`  Imports: ${(input.importedExports || []).length} glossary entities`));
+    console.log(chalk.dim(`  Type info: ${Object.keys(dataForMocks).length} fields`));
+    console.log();
+    console.log(chalk.dim('Re-run `codeyam editor audit` to verify.'));
+}
 // ─── Command definition ───────────────────────────────────────────────
 const editorCommand = {
     command: 'editor [step] [json]',
     describe: 'Editor mode guided workflow',
     builder: (yargs) => {
         const stepDescription = IS_INTERNAL_BUILD
-            ? 'Step number (1-18) or subcommand (template, register, isolate, analyze-imports, dependents, audit, scenarios, scenario-coverage, recapture-stale, change, sync, debug, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors, task-ontrack)'
-            : 'Step number (1-18) or subcommand (template, register, isolate, analyze-imports, dependents, audit, scenarios, scenario-coverage, recapture-stale, change, sync, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors, task-ontrack)';
+            ? 'Step number (1-18) or subcommand (template, register, isolate, analyze-imports, manual-entity, dependents, audit, scenarios, scenario-coverage, recapture-stale, change, sync, debug, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors, task-ontrack)'
+            : 'Step number (1-18) or subcommand (template, register, isolate, analyze-imports, manual-entity, dependents, audit, scenarios, scenario-coverage, recapture-stale, change, sync, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors, task-ontrack)';
         let builder = yargs
             .positional('step', {
             type: 'string',
@@ -4465,7 +4907,9 @@ const editorCommand = {
                     'Ask user what to build next and restart codeyam editor workflow';
             }
             console.log(chalk.bold.cyan('━━━ TASK ━━━'));
-            console.log(chalk.cyan('Mark your current task (if any) as complete.'));
+            console.log(chalk.cyan('Before creating the task below, delete ALL existing tasks:'));
+            console.log(chalk.cyan('  1. Run TaskList to find all tasks'));
+            console.log(chalk.cyan('  2. Run TaskUpdate with status "deleted" for EACH task returned'));
             console.log(chalk.cyan('Then create a new task with this EXACT title (copy verbatim):'));
             console.log();
             console.log(chalk.bold.cyan(`EXACT_TASK_TITLE: ${taskTitle}`));
@@ -4484,6 +4928,11 @@ const editorCommand = {
             await handleAnalyzeImports();
             return;
         }
+        // Subcommand: codeyam editor manual-entity <JSON|@file>
+        if (argv.step === 'manual-entity') {
+            await handleManualEntity(argv.json || '');
+            return;
+        }
         // Subcommand: codeyam editor dependents <EntityName>
         if (argv.step === 'dependents') {
             await handleDependents(argv.json || '');
@@ -4724,13 +5173,24 @@ const editorCommand = {
                     try {
                         const { getDatabase: getDb } = await import('../../../packages/database/index.js');
                         const seedDb = getDb();
-                        const appScenario = await seedDb
+                        // Prefer the home page scenario (url "/") since the App tab
+                        // sorts "Home" first — fall back to any application scenario.
+                        const homeScenario = await seedDb
                             .selectFrom('editor_scenarios')
                             .select(['id', 'name', 'type'])
                             .where('project_id', '=', project.id)
-                            .where('type', '=', 'application')
+                            .where('url', '=', '/')
+                            .where('component_name', 'is', null)
                             .orderBy('created_at', 'asc')
                             .executeTakeFirst();
+                        const appScenario = homeScenario ||
+                            (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)) {
@@ -4873,7 +5333,7 @@ const editorCommand = {
                         if (!needsAnalysis) {
                             try {
                                 const { getDatabase } = await import('../../../packages/database/index.js');
-                                const { countScenariosNeedingEntityBackfill } = await import('../utils/editorScenarios');
+                                const { countScenariosNeedingEntityBackfill } = await import('../utils/editorScenarios.js');
                                 const db = getDatabase();
                                 const backfillCount = await countScenariosNeedingEntityBackfill(db);
                                 if (backfillCount > 0) {
@@ -4912,7 +5372,7 @@ const editorCommand = {
                         .execute();
                     if (unresolved.length > 0) {
                         const { scanPageFilePaths: scanPfp } = await import('../utils/entityChangeStatus.server.js');
-                        const { matchUrlToPageFile } = await import('../utils/routePatternMatching');
+                        const { matchUrlToPageFile } = await import('../utils/routePatternMatching.js');
                         const { allFiles: pfpFiles } = scanPfp(projectRoot);
                         let pfpResolved = 0;
                         for (const row of unresolved) {