@codeyam/codeyam-cli 0.1.19 → 0.1.21

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);
@@ -121,6 +122,13 @@ function writeState(root, state) {
     const dir = path.dirname(statePath);
     fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(statePath, JSON.stringify(state, null, 2), 'utf8');
+    // Write task tracking file — marks that a task is expected for this step.
+    // The step hook sets taskCreated=true when it sees a TaskCreate tool call.
+    // Steps 1 and below don't require tasks (feature not named yet).
+    if (state.step && state.step >= 2) {
+        const trackingPath = path.join(root, '.codeyam', 'editor-task-tracking.json');
+        fs.writeFileSync(trackingPath, JSON.stringify({ step: state.step, taskCreated: false }, null, 2), 'utf8');
+    }
 }
 /**
  * Clear the editor state (for starting a new feature).
@@ -203,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.
@@ -248,11 +284,15 @@ function printAppScenarioInstructions(pageName, route) {
         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'));
+    console.log();
+    console.log(chalk.bold('Register ALL scenarios at once (bulk registration):'));
+    console.log(chalk.dim('    Write an array of scenario objects to a temp file:'));
+    console.log(chalk.dim('    [{"name":"...","type":"application","url":"/","seed":{...}}, {"name":"...","url":"/other",...}]'));
+    console.log(chalk.dim('    Then register all at once: codeyam editor register @.codeyam/tmp/scenarios.json'));
+    console.log(chalk.yellow('    Bulk registration is preferred — faster and avoids repeated capture overhead.'));
+    console.log();
     checkbox('If the app uses auth, email, or other patterns: see FEATURE_PATTERNS.md for scenario guidance');
-    checkbox('After each registration, check the response for `clientErrors`');
+    checkbox('After registration, check the response for `clientErrors`');
     console.log(chalk.yellow('    If clientErrors is non-empty → fix the issue and re-register the scenario'));
     console.log(chalk.yellow('    Fix client errors and re-register before moving on'));
 }
@@ -353,6 +393,10 @@ function printComponentCaptureInstructions() {
     console.log(chalk.yellow('       If clientErrors is non-empty → fix the isolation route and re-register'));
     console.log(chalk.yellow('       Fix client errors and re-register before moving on'));
     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('    codeyam editor register @.codeyam/tmp/scenarios.json'));
 }
 /**
  * Print a section header.
@@ -393,9 +437,31 @@ function printProgressTracker(current) {
  *
  * Options:
  * - confirm: true  → step requires user confirmation before proceeding (steps 1, 3, 11)
+ * - feature: string → feature name for task directive
  */
 function stopGate(current, opts) {
-    console.log();
+    const totalSteps = Object.keys(STEP_LABELS).length;
+    const currentLabel = STEP_LABELS[current] || `Step ${current}`;
+    const nextLabel = current < totalSteps ? STEP_LABELS[current + 1] : undefined;
+    console.log();
+    // ━━━ TASK ━━━ — deterministic task lifecycle directive
+    // 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('Then create a new task with this EXACT title (copy verbatim):'));
+        console.log();
+        let taskTitle;
+        if (current < totalSteps) {
+            taskTitle = `Complete codeyam editor step ${current}: '${currentLabel}' and move on to step ${current + 1}: '${nextLabel}'`;
+        }
+        else {
+            taskTitle =
+                'Ask user what to build next and restart codeyam editor workflow';
+        }
+        console.log(chalk.bold.cyan(`EXACT_TASK_TITLE: ${taskTitle}`));
+        console.log();
+    }
     console.log(chalk.bold.red('━━━ STOP ━━━'));
     console.log();
     console.log(chalk.red('Complete each checklist item above before proceeding to the next step.'));
@@ -404,20 +470,12 @@ function stopGate(current, opts) {
         console.log(chalk.yellow('Wait for user confirmation before moving on.'));
     }
     console.log();
-    console.log(chalk.bold.yellow('Present the following progress tracker to the user (copy it verbatim):'));
-    printProgressTracker(current);
-    console.log();
-    console.log(chalk.yellow('For the CURRENT step (→), show each checklist item with ✓ (done) or ✗ (skipped + reason).'));
-    console.log(chalk.yellow('If any items are ✗, explain why and ask if the user wants to address them.'));
-    console.log();
-    if (current < 18) {
+    if (current < totalSteps) {
         console.log(chalk.green('When done, run: ') +
             chalk.bold(`codeyam editor ${current + 1}`));
     }
     else {
-        console.log(chalk.green('Feature complete! Run: ') +
-            chalk.bold('codeyam editor steps') +
-            chalk.green(' to start the next feature'));
+        console.log(chalk.green('Feature complete! Ask the user what to build next, then run: ') + chalk.bold('codeyam editor 1'));
     }
     console.log();
 }
@@ -785,9 +843,7 @@ function printCycleOverview(root, state) {
         console.log();
         console.log(chalk.green('Continue with: ') +
             chalk.bold(`codeyam editor ${state.step}`));
-        console.log(chalk.dim('Or run ') +
-            chalk.bold('codeyam editor 1') +
-            chalk.dim(' to start a new feature'));
+        console.log(chalk.dim('Or ask the user what to build next, then run `codeyam editor 1` yourself (never expose this command to the user)'));
         console.log();
         console.log(chalk.yellow('If the user reports a bug or requests any change, run: ') +
             chalk.bold('codeyam editor change'));
@@ -815,7 +871,8 @@ function printCycleOverview(root, state) {
         console.log(`  ${chalk.bold.yellow('17')} ${chalk.bold('Finalize')}           — Journal update + amend commit`);
         console.log(`  ${chalk.bold.yellow('18')} ${chalk.bold('Push')}               — Push to remote`);
         console.log();
-        console.log(chalk.green('Start now: ') + chalk.bold('codeyam editor 1'));
+        console.log(chalk.green('Start now: ') +
+            'Ask the user what they want to build, then run `codeyam editor 1` (never expose this command to the user)');
         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'));
@@ -894,12 +951,6 @@ function printStep1(root, feature, options, userPrompt) {
     console.log();
     console.log(chalk.yellow('Wait for user confirmation before moving on.'));
     console.log();
-    console.log(chalk.bold.yellow('Present the following progress tracker to the user (copy it verbatim):'));
-    printProgressTracker(1);
-    console.log();
-    console.log(chalk.yellow('For the CURRENT step (→), show each checklist item with ✓ (done) or ✗ (skipped + reason).'));
-    console.log(chalk.yellow('If any items are ✗, explain why and ask if the user wants to address them.'));
-    console.log();
     console.log(chalk.green('When done, run: ') +
         chalk.bold('codeyam editor 2 --feature "Feature Name"'));
     console.log(chalk.dim('  Replace "Feature Name" with a short title for what you just described.'));
@@ -927,13 +978,6 @@ function printStep2(root, feature) {
     if (isResuming) {
         printResumptionHeader(2);
     }
-    console.log(chalk.bold.red('━━━ MANDATORY: CREATE TASK NOW ━━━'));
-    console.log();
-    console.log(chalk.red(`Run TaskCreate with title: "Use \`codeyam editor\` to work on ${feature}"`));
-    console.log(chalk.red('DO NOT read files, scaffold, write code, or do ANYTHING else until this task exists.'));
-    console.log(chalk.red('This is not optional. Create the task, then continue below.'));
-    console.log(chalk.bold.red('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
-    console.log();
     console.log('Get the project ready to build.');
     console.log();
     // If no project exists yet, include scaffolding instructions first
@@ -963,6 +1007,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:'));
@@ -977,6 +1022,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);
 }
@@ -1012,6 +1058,13 @@ function printStep3(root, feature) {
         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>'));
+        console.log();
+        console.log(chalk.bold.cyan('Make seed data visually rich:'));
+        console.log(chalk.cyan('  • Use real placeholder images from Unsplash (https://images.unsplash.com/photo-<id>?w=400&h=300&fit=crop)'));
+        console.log(chalk.cyan('  • Use avatar services like i.pravatar.cc for user profile photos'));
+        console.log(chalk.cyan('  • Write realistic, varied content — not "Item 1", "Item 2", "Test Description"'));
+        console.log(chalk.cyan('  • Include different text lengths, categories, dates, and statuses'));
+        console.log(chalk.cyan('  • Rich seed data makes the prototype look real and surfaces layout issues early'));
     }
     checkbox('Verify the dev server shows the changes');
     checkbox('If the feature involves auth, email, payments, or other common patterns: read FEATURE_PATTERNS.md');
@@ -1051,6 +1104,8 @@ function printStep3(root, feature) {
     console.log(chalk.cyan('  If you build a NEW page (e.g., /drinks/[id]), navigate the preview there:'));
     console.log(chalk.cyan(`  codeyam editor preview '{"path":"/drinks/1","dimension":"${dim}"}'`));
     printDimensionGuidance(dim, dimNames);
+    console.log(chalk.red.bold('  NEVER claim "you should see X" or "the preview shows X" unless you just ran a preview command.'));
+    console.log(chalk.red('  The preview only updates when you explicitly refresh it. Verify, then describe.'));
     console.log();
     stopGate(3);
 }
@@ -1147,6 +1202,8 @@ function printStep5(root, feature) {
     printDimensionGuidance(dim, dimNames);
     console.log(chalk.dim('    The user needs to SEE the new feature. If you built a new page, navigate there.'));
     console.log(chalk.dim('    If you modified an existing page, refresh the preview to show the changes.'));
+    console.log(chalk.red.bold('    NEVER claim "you should see X" or "the preview shows X" unless you just ran a preview command.'));
+    console.log(chalk.red('    The preview only updates when you explicitly call `codeyam editor preview`. Verify, then describe.'));
     console.log();
     console.log(chalk.bold.cyan('Guide the user through interactive testing:'));
     checkbox('Tell the user: "The preview is fully interactive — click around to test!"');
@@ -1300,7 +1357,10 @@ 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();
     stopGate(9);
 }
@@ -1335,6 +1395,7 @@ function printStep10(root, feature) {
     console.log(chalk.cyan('  • Include realistic variety — different categories, lengths, statuses, counts'));
     console.log(chalk.cyan("  • Populate optional fields the feature depends on (don't leave them empty)"));
     console.log(chalk.cyan('  • Make content diverse enough that edge cases surface naturally'));
+    console.log(chalk.cyan('  • Use real image URLs (Unsplash, Pravatar) — not broken placeholders or empty strings'));
     console.log(chalk.cyan("  • Think: would this data reveal a bug in the feature? If it's too simple, enrich it."));
     console.log();
     console.log(chalk.bold.cyan('When to create new vs reuse existing:'));
@@ -1549,7 +1610,7 @@ function printStep15(root, feature) {
     console.log(chalk.bold('Checklist:'));
     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 first scenario is automatically selected and its live preview is shown.'));
     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)');
@@ -1789,7 +1850,7 @@ function printMigrateStep4(root) {
     checkbox('Check for client errors: `codeyam editor client-errors`');
     checkbox('If any issues: fix the scenario data, re-register affected scenarios');
     checkbox('Show results: `codeyam editor show-results`');
-    console.log(chalk.dim('    The preview automatically switches to the first app-level scenario.'));
+    console.log(chalk.dim('    The first scenario is automatically selected and its live preview is shown.'));
     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);
@@ -1956,7 +2017,7 @@ function printMigrateStep10(root) {
     console.log();
     console.log(chalk.bold('Checklist:'));
     checkbox('Show results: `codeyam editor show-results`');
-    console.log(chalk.dim('    The preview automatically switches to the first app-level scenario.'));
+    console.log(chalk.dim('    The first scenario is automatically selected and its live preview is shown.'));
     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):'));
@@ -2253,15 +2314,13 @@ function printStep18(root, feature) {
     console.log(chalk.dim('    If the user says yes, run: `git push`'));
     console.log(chalk.dim('    If NO remote exists, ask (AskUserQuestion): "This project doesn\'t have a git remote yet. Would you like help setting one up? I can walk you through creating a GitHub repository." with options "Yes, set up remote" and "No, skip"'));
     console.log(chalk.dim('    If the user wants help, guide them through `gh repo create` or manual GitHub setup, then push.'));
-    checkbox('Mark the current build task as complete');
-    checkbox('Create a new task with EXACTLY this title: "Ask the user what to build next, then run `codeyam editor 1` to start the next feature"');
-    console.log(chalk.dim('    There must ALWAYS be an active task. Never leave the task list empty.'));
-    console.log(chalk.dim('    This task reminds you to use the editor workflow for the next feature.'));
+    console.log(chalk.dim('    Task management is handled by the ━━━ TASK ━━━ directive below.'));
     console.log();
     console.log(chalk.bold.yellow('IMPORTANT: After this step, the current feature is DONE.'));
     console.log(chalk.yellow('  Any new user request — even if it sounds related — is a NEW feature.'));
     console.log(chalk.yellow('  Do NOT use `codeyam editor change` or start building directly.'));
-    console.log(chalk.yellow('  The next feature MUST start with `codeyam editor 1`.'));
+    console.log(chalk.yellow('  Ask the user what they want to build. Once they tell you, run `codeyam editor 1` yourself.'));
+    console.log(chalk.yellow('  NEVER tell the user to run `codeyam editor` commands — these are internal. Just ask what to build.'));
     console.log(chalk.yellow('  The change workflow is ONLY for modifications during steps 1-15, not after commit.'));
     stopGate(18, { confirm: true });
 }
@@ -2337,25 +2396,54 @@ 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)
-    // 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...');
+    // Filter to only files that actually need analysis — avoids re-analyzing
+    // ~120 files when only 2 are incomplete.
+    let targetFilePaths = filePaths;
     try {
-        await runAnalysisForEntities({
-            projectRoot: root,
-            filePaths,
-            progress,
-            onlyDataStructure: true,
-        });
+        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 (err) {
-        progress.fail('Analysis failed');
-        const msg = err instanceof Error ? err.message : String(err);
-        console.error(chalk.red(`Error: ${msg}`));
-        process.exit(1);
+    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.
+    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');
     }
-    progress.succeed('Analysis complete');
     // Load entities WITH metadata from database
     progress.start('Loading entity metadata...');
     await initializeEnvironment();
@@ -2705,11 +2793,15 @@ async function handleRegister(jsonArg) {
     }
     // Normalize to array for uniform handling
     const items = Array.isArray(parsed.body) ? parsed.body : [parsed.body];
+    const root = getProjectRoot();
     const port = getServerPort();
     const url = `http://localhost:${port}/api/editor-register-scenario`;
     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];
         const prefix = isBatch ? chalk.dim(`[${i + 1}/${items.length}] `) : '';
@@ -2737,6 +2829,12 @@ async function handleRegister(jsonArg) {
             else {
                 parts.push(`errors=0`);
             }
+            if (data.visibleText) {
+                const truncated = data.visibleText.length > 100
+                    ? data.visibleText.substring(0, 97) + '...'
+                    : data.visibleText;
+                parts.push(`visibleText="${truncated}"`);
+            }
             if (data.seedResult) {
                 if (data.seedResult.success) {
                     parts.push(`seed=ok`);
@@ -2772,12 +2870,29 @@ 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 &&
+                    data.scenario?.screenshotPath &&
+                    data.scenario?.name) {
+                    const absPath = path.join(root, '.codeyam', 'editor-scenarios', data.scenario.screenshotPath);
+                    screenshotEntries.push({
+                        scenarioName: data.scenario.name,
+                        screenshotAbsPath: absPath,
+                    });
+                }
+            }
+            // Collect issues from this registration
+            for (const issue of resultIssues) {
+                issues.push(`"${issue.scenarioName}": ${issue.message}`);
             }
         }
         catch (error) {
@@ -2788,10 +2903,50 @@ async function handleRegister(jsonArg) {
             failed++;
         }
     }
+    // Detect duplicate screenshots in the batch
+    if (isBatch && screenshotEntries.length > 1) {
+        const { computeScreenshotHash, findDuplicateScreenshots } = await import('../utils/screenshotHash');
+        const hashEntries = screenshotEntries
+            .map((e) => {
+            const hash = computeScreenshotHash(e.screenshotAbsPath);
+            return hash
+                ? {
+                    scenarioName: e.scenarioName,
+                    screenshotPath: e.screenshotAbsPath,
+                    hash,
+                }
+                : null;
+        })
+            .filter((e) => e !== null);
+        const duplicates = findDuplicateScreenshots(hashEntries);
+        if (duplicates.size > 0) {
+            console.log('');
+            console.log(chalk.yellow.bold('WARNING: Identical screenshots detected:'));
+            for (const [, names] of duplicates) {
+                const quoted = names.map((n) => `"${n}"`);
+                console.log(chalk.yellow(`  ${quoted.join(' and ')} produced the same screenshot`));
+            }
+            console.log(chalk.yellow("  This usually means the app's view state depends on something scenarios can't control"));
+            console.log(chalk.yellow('  (e.g., a hardcoded function return value, or identical localStorage not differentiating views).'));
+        }
+    }
     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);
     }
 }
@@ -3003,6 +3158,8 @@ function handleChange(feature) {
     console.log(chalk.cyan(`  codeyam editor preview '{"dimension":"${dim}"}'`));
     printDimensionGuidance(dim, dimNames);
     console.log(chalk.cyan('  The user is watching the preview. Let them see progress incrementally.'));
+    console.log(chalk.red.bold('  NEVER claim "you should see X" or "the preview shows X" unless you just ran a preview command.'));
+    console.log(chalk.red('  The preview only updates when you explicitly refresh it. Verify, then describe.'));
     console.log();
     console.log(chalk.bold('0. Close the results panel:'));
     checkbox(`Hide results: \`codeyam editor hide-results\``);
@@ -3104,16 +3261,33 @@ async function checkAuditGate() {
         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)) {
+    // 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 {
-            await handleAnalyzeImports({ silent: true });
+            const entities = await loadEntities({});
+            if (entities && entities.length > 0) {
+                const { getDatabase } = await import('../../../packages/database/index.js');
+                const db = getDatabase();
+                await backfillEntityShaOnScenarios(db, entities.map((e) => ({
+                    sha: e.sha,
+                    name: e.name,
+                    filePath: e.filePath || '',
+                    isDefaultExport: e.metadata?.notExported === false &&
+                        e.metadata?.namedExport === false,
+                })));
+            }
         }
         catch {
-            return false;
+            // Fall through
         }
-        // Re-check after fix
+        // Re-check after backfill
         const retry = await fetchAuditResult();
         if (retry?.summary?.allPassing === true)
             return true;
@@ -3137,6 +3311,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) {
@@ -3150,7 +3326,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) {
@@ -3188,6 +3372,13 @@ function printAuditGateFailures(data) {
             issues.push(`${s.incompleteEntities} entity/entities need import analysis`);
         }
     }
+    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`);
+        const unassociated = data.unassociatedScenarios || [];
+        for (const u of unassociated) {
+            issues.push(`    → ${u.name} (${u.filePath}) — ${u.scenarioCount} scenario${u.scenarioCount !== 1 ? 's' : ''}`);
+        }
+    }
     if (s.miscategorizedScenarios > 0)
         issues.push(`${s.miscategorizedScenarios} component(s) using page URLs instead of isolation routes`);
     if (s.scenariosNeedingRecapture > 0)
@@ -3232,30 +3423,44 @@ async function handleAudit() {
         console.error(chalk.red('Error: Could not reach the CodeYam server. Is it running?'));
         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.
+    // Lightweight auto-fix: backfill entity_sha on scenarios that were
+    // registered before entity records existed. This is fast (DB-only).
+    // We do NOT run handleAnalyzeImports 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) {
-        console.log(chalk.dim(`Running import analysis for ${incompleteBeforeFix.length} incomplete entit${incompleteBeforeFix.length !== 1 ? 'ies' : 'y'}...`));
+    if (incompleteBeforeFix.length > 0 || unassociatedBeforeFix.length > 0) {
+        const issueCount = incompleteBeforeFix.length + unassociatedBeforeFix.length;
+        console.log(chalk.dim(`Backfilling ${issueCount} entity association issue${issueCount !== 1 ? 's' : ''}...`));
+        // Backfill entity_sha on scenarios that were registered before entities existed
         try {
-            await handleAnalyzeImports({ silent: true });
+            const entities = await loadEntities({});
+            if (entities && entities.length > 0) {
+                const { getDatabase } = await import('../../../packages/database/index.js');
+                const db = getDatabase();
+                await backfillEntityShaOnScenarios(db, entities.map((e) => ({
+                    sha: e.sha,
+                    name: e.name,
+                    filePath: e.filePath || '',
+                    isDefaultExport: e.metadata?.notExported === false &&
+                        e.metadata?.namedExport === false,
+                })));
+            }
         }
         catch {
-            // Fall through — the audit will still report them as incomplete
+            // Fall through — re-fetch will show remaining issues
         }
-        // Re-fetch audit results after the fix
+        // Re-fetch audit results after the backfill
         data = await fetchAuditResult();
         if (!data) {
-            console.error(chalk.red('Error: Could not reach the CodeYam server after analyze-imports.'));
+            console.error(chalk.red('Error: Could not reach the CodeYam server after backfill.'));
             process.exit(1);
         }
-        // If entities are still incomplete after running analyze-imports,
-        // flag it so we can show a clear message instead of looping
+        // If issues persist after backfill, flag it so we show clear guidance
         const incompleteAfterFix = data.incompleteEntities || [];
-        if (incompleteAfterFix.length > 0) {
+        const unassociatedAfterFix = data.unassociatedScenarios || [];
+        if (incompleteAfterFix.length > 0 || unassociatedAfterFix.length > 0) {
             autoRemediationFailed = true;
         }
     }
@@ -3289,6 +3494,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;
@@ -3332,9 +3540,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}`);
@@ -3351,23 +3566,70 @@ 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 || [];
+    // Incomplete entities (scenarios without analyses) — auto-fix by running
+    // targeted analysis on just the affected files (fast: 2 files vs 117+).
+    let incompleteEntities = data.incompleteEntities || [];
     if (incompleteEntities.length > 0) {
+        const { getIncompleteEntityFilePaths } = await import('../utils/editorAudit.js');
+        try {
+            const { getDatabase } = await import('../../../packages/database/index.js');
+            const db = getDatabase();
+            const filePaths = await getIncompleteEntityFilePaths(db, incompleteEntities);
+            if (filePaths.length > 0) {
+                console.log(chalk.dim(`Running targeted import analysis for ${filePaths.length} incomplete entit${filePaths.length !== 1 ? 'ies' : 'y'}...`));
+                const root = getProjectRoot();
+                try {
+                    const { runAnalysisForEntities } = await import('../utils/analysisRunner.js');
+                    await runAnalysisForEntities({
+                        projectRoot: root,
+                        filePaths,
+                        progress: new ProgressReporter(),
+                        onlyDataStructure: true,
+                    });
+                    // Re-fetch audit results after targeted fix
+                    const refreshed = await fetchAuditResult();
+                    if (refreshed) {
+                        data = refreshed;
+                        incompleteEntities = data.incompleteEntities || [];
+                    }
+                }
+                catch {
+                    // Fall through — report remaining incomplete entities below
+                }
+            }
+        }
+        catch {
+            // DB not available — fall through to reporting
+        }
+    }
+    if (incompleteEntities.length > 0) {
+        const { formatIncompleteEntityGuidance } = await import('../utils/editorAudit.js');
         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`);
+            const guidance = formatIncompleteEntityGuidance(e);
+            console.log(`  ${chalk.red('✗')} ${guidance}`);
+        }
+        console.log();
+    }
+    // Unassociated scenarios (NULL entity_sha with file paths)
+    const unassociatedScenarios = data.unassociatedScenarios || [];
+    if (unassociatedScenarios.length > 0) {
+        console.log(chalk.bold('Unassociated scenarios (missing entity link):'));
+        for (const u of unassociatedScenarios) {
+            console.log(`  ${chalk.red('✗')} ${u.name} ${chalk.dim(`(${u.filePath})`)} — ${u.scenarioCount} scenario${u.scenarioCount !== 1 ? 's' : ''} with no entity_sha`);
+            for (const sn of u.scenarioNames.slice(0, 3)) {
+                console.log(chalk.dim(`      "${sn}"`));
+            }
+            if (u.scenarioNames.length > 3) {
+                console.log(chalk.dim(`      … and ${u.scenarioNames.length - 3} more`));
+            }
         }
         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('      • 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('    analyze-imports ran automatically but could not resolve these.'));
+            console.log(chalk.yellow('    Run `codeyam editor analyze-imports` to see the full error output.'));
         }
         else {
-            console.log(chalk.yellow('    Run `codeyam editor analyze-imports` to analyze these entities'));
+            console.log(chalk.yellow('    Run `codeyam editor analyze-imports` to create entity records, then re-run audit to backfill.'));
         }
         console.log();
     }
@@ -3444,6 +3706,9 @@ async function handleAudit() {
         if (summary.incompleteEntities > 0) {
             parts.push(`${summary.incompleteEntities} entit${summary.incompleteEntities !== 1 ? 'ies' : 'y'} need import analysis`);
         }
+        if (summary.unassociatedScenarios > 0) {
+            parts.push(`${summary.unassociatedScenarios} component${summary.unassociatedScenarios !== 1 ? 's' : ''} with scenarios missing entity link`);
+        }
         if (summary.miscategorizedScenarios > 0) {
             parts.push(`${summary.miscategorizedScenarios} component${summary.miscategorizedScenarios !== 1 ? 's' : ''} using page URLs instead of isolation routes`);
         }
@@ -4183,8 +4448,8 @@ const editorCommand = {
     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)'
-            : '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)';
+            ? '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)';
         let builder = yargs
             .positional('step', {
             type: 'string',
@@ -4245,6 +4510,18 @@ const editorCommand = {
         // API subcommands: preview, show-results, hide-results, commit,
         // journal, journal-update, dev-server, client-errors
         if (argv.step && EDITOR_API_SUBCOMMANDS.includes(argv.step)) {
+            // Guard: commit requires step 16 to have been run first.
+            // Without this, Claude shortcuts the process by running
+            // `codeyam editor commit` directly from step 15, skipping
+            // steps 16-18 entirely.
+            if (argv.step === 'commit') {
+                const state = readState(root);
+                if (state && state.step !== 16) {
+                    console.error(chalk.red('Error: Run `codeyam editor 16` before committing.'));
+                    console.error(chalk.dim(`  Current step: ${state.step} (${state.label || 'unknown'}). Step 16 (Commit) must be run first.`));
+                    process.exit(1);
+                }
+            }
             const port = getServerPort();
             try {
                 const request = buildEditorApiRequest(argv.step, argv.json || undefined);
@@ -4288,6 +4565,46 @@ const editorCommand = {
             await handleGlossaryAdd(argv.json || '');
             return;
         }
+        // Subcommand: codeyam editor task-ontrack
+        // Corrective command when Claude advanced without creating a task.
+        if (argv.step === 'task-ontrack') {
+            const state = readState(root);
+            if (!state?.step) {
+                console.error(chalk.red('No editor state found. Run `codeyam editor 1` to start.'));
+                process.exit(1);
+            }
+            const currentLabel = STEP_LABELS[state.step] || `Step ${state.step}`;
+            const totalSteps = Object.keys(STEP_LABELS).length;
+            const nextLabel = state.step < totalSteps ? STEP_LABELS[state.step + 1] : undefined;
+            console.log();
+            console.log(chalk.bold.yellow('━━━ GETTING BACK ON TRACK ━━━'));
+            console.log();
+            console.log(chalk.yellow('You went off-track by not creating a task. Create the task below to continue.'));
+            console.log();
+            // Print the TASK directive for the current step
+            let taskTitle;
+            if (state.step < totalSteps) {
+                taskTitle = `Complete codeyam editor step ${state.step}: '${currentLabel}' and move on to step ${state.step + 1}: '${nextLabel}'`;
+            }
+            else {
+                taskTitle =
+                    '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('Then create a new task with this EXACT title (copy verbatim):'));
+            console.log();
+            console.log(chalk.bold.cyan(`EXACT_TASK_TITLE: ${taskTitle}`));
+            console.log();
+            console.log(chalk.green(`After creating the task, re-run: codeyam editor ${state.step + 1}`));
+            console.log();
+            // Mark task as expected-created so the next step can proceed.
+            // The hook will set taskCreated=true when it sees the actual TaskCreate call.
+            // But we also allow advancement now since task-ontrack itself is the corrective action.
+            const trackingPath = path.join(root, '.codeyam', 'editor-task-tracking.json');
+            fs.writeFileSync(trackingPath, JSON.stringify({ step: state.step, taskCreated: true }, null, 2), 'utf8');
+            return;
+        }
         // Subcommand: codeyam editor analyze-imports
         if (argv.step === 'analyze-imports') {
             await handleAnalyzeImports();
@@ -4804,7 +5121,7 @@ const editorCommand = {
         // Step 1 is planning-only and may not persist state (no --feature flag).
         const skipValidation = step === 2 && argv.feature;
         if (!skipValidation) {
-            const stepError = validateStepTransition(step, state?.step ?? null);
+            const stepError = validateStepTransition(step, state?.step ?? null, state?.startedAt, root);
             if (stepError) {
                 console.error(chalk.red(`Error: ${stepError}`));
                 process.exit(1);
@@ -4858,7 +5175,6 @@ const editorCommand = {
                     if (!auditOk) {
                         // 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);
                     }
                 }