@codeyam/codeyam-cli 0.1.17 → 0.1.19

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

@@ -16,7 +16,7 @@ import { APP_FORMATS, TECH_STACKS } from "../data/techStacks.js";
 import { getProjectRoot as getStateProjectRoot } from "../state.js";
 import initCommand from "./init.js";
 import { scanScenarioFiles, syncScenarioFilesToDatabase, backfillScenarioMetadata, migrateScenarioFormats, } from "../utils/scenariosManifest.js";
-import { clearEditorState, clearEditorUserPrompt, validateStepTransition, backfillEntityShaOnScenarios, } from "../utils/editorScenarios.js";
+import { clearEditorState, validateStepTransition, backfillEntityShaOnScenarios, } from "../utils/editorScenarios.js";
 import { validateSeedData, detectSeedAdapter, validateSeedKeysAgainstPrisma, } from "../utils/editorSeedAdapter.js";
 import { deleteScenarioViaCli } from "../utils/editorDeleteScenario.js";
 import { buildEditorApiRequest, callEditorApi, EDITOR_API_SUBCOMMANDS, } from "../utils/editorApi.js";
@@ -27,21 +27,23 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const STEP_LABELS = {
     1: 'Plan',
-    2: 'Prototype',
-    3: 'Confirm',
-    4: 'Deconstruct',
-    5: 'Extract',
-    6: 'Glossary',
-    7: 'Analyze',
-    8: 'App Scenarios',
-    9: 'User Scenarios',
-    10: 'Verify',
-    11: 'Journal',
-    12: 'Review',
-    13: 'Present',
-    14: 'Commit',
-    15: 'Finalize',
-    16: 'Push',
+    2: 'Prepare',
+    3: 'Prototype',
+    4: 'Verify Prototype',
+    5: 'Confirm',
+    6: 'Deconstruct',
+    7: 'Extract',
+    8: 'Glossary',
+    9: 'Analyze',
+    10: 'App Scenarios',
+    11: 'User Scenarios',
+    12: 'Verify',
+    13: 'Journal',
+    14: 'Review',
+    15: 'Present',
+    16: 'Commit',
+    17: 'Finalize',
+    18: 'Push',
 };
 const MIGRATION_STEP_LABELS = {
     1: 'Survey',
@@ -122,8 +124,9 @@ function writeState(root, state) {
 }
 /**
  * Clear the editor state (for starting a new feature).
- * Does NOT clear the user prompt file — that's handled separately
- * via clearEditorUserPrompt when the previous feature commits.
+ * Does NOT clear the user prompt file — the prompt is cleared
+ * by the journal API after recording, and the hook captures
+ * a fresh prompt for the next feature on UserPromptSubmit.
  */
 function clearState(root) {
     clearEditorState(root);
@@ -208,8 +211,9 @@ function printAppScenarioInstructions(pageName, route) {
     const root = process.cwd();
     const hasSeedAdapter = !!detectSeedAdapter(root);
     checkbox('Check existing scenarios: `codeyam editor scenarios`');
-    console.log(chalk.dim('    Review existing scenarios — reuse and update their data rather than'));
-    console.log(chalk.dim('    creating duplicates. Re-register with the same name to update a scenario.'));
+    console.log(chalk.dim('    Review existing scenarios — enhance their seed data to exercise new features.'));
+    console.log(chalk.dim('    A rich scenario that exercises 5 features is better than 5 thin scenarios with one feature each.'));
+    console.log(chalk.dim('    Rename scenarios if their data scope has grown beyond the original name.'));
     console.log();
     console.log(chalk.bold.yellow('App scenarios vs component scenarios — these are DIFFERENT:'));
     console.log(chalk.yellow('  App scenarios:       show the FULL PAGE with seeded data at a real route (/, /library, etc.)'));
@@ -305,7 +309,7 @@ function printExtractionPlanInstructions() {
     console.log(chalk.yellow('    — Where it currently lives (source file + approximate lines)'));
     console.log(chalk.yellow('    — Where it will go (new file path)'));
     console.log();
-    console.log(chalk.dim('Present the numbered plan, then proceed to step 5 to execute it.'));
+    console.log(chalk.dim('Present the numbered plan, then proceed to step 7 to execute it.'));
 }
 /**
  * Shared component capture instructions used by editor Step 7 and migration Steps 3/8.
@@ -362,13 +366,13 @@ function stepHeader(step, title, feature) {
     console.log();
 }
 /**
- * Print a colored progress tracker showing all 16 steps.
+ * Print a colored progress tracker showing all 18 steps.
  * Steps before `current` are green ✓, `current` is bold cyan →, future steps are dim ○.
  */
 function printProgressTracker(current) {
     console.log();
     console.log(chalk.dim('  ┌─────────────────────────────────────┐'));
-    for (let i = 1; i <= 16; i++) {
+    for (let i = 1; i <= 18; i++) {
         const label = STEP_LABELS[i];
         const num = i < 10 ? ` ${i}` : `${i}`;
         const content = `${num}. ${label.padEnd(28)}`;
@@ -406,13 +410,13 @@ function stopGate(current, opts) {
     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 < 16) {
+    if (current < 18) {
         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 1') +
+            chalk.bold('codeyam editor steps') +
             chalk.green(' to start the next feature'));
     }
     console.log();
@@ -428,34 +432,36 @@ function printResumptionHeader(step) {
             'Check if plan was already written to context file:\n      `cat .codeyam/editor-mode-context.md`',
         ],
         2: ['Check if project files already exist:\n      `ls package.json src/`'],
-        3: ['This is a confirmation step — just re-present to user'],
-        4: [
+        3: ['Re-check is safe — just re-run the step'],
+        4: ['Re-verify is safe to repeat — just re-run the checks'],
+        5: ['This is a confirmation step — just re-present to user'],
+        6: [
             'Check if extraction plan already exists in context file:\n      `cat .codeyam/editor-mode-context.md`',
         ],
-        5: [
+        7: [
             'Check if components/functions already extracted:\n      `ls src/components/ src/lib/`',
         ],
-        6: [
+        8: [
             'Check if glossary already populated:\n      `cat .codeyam/glossary.json`',
         ],
-        7: ['Check if isolation routes and registered scenarios already exist'],
-        8: ['Check existing scenarios:\n      `codeyam editor scenarios`'],
-        9: [
+        9: ['Check if isolation routes and registered scenarios already exist'],
+        10: ['Check existing scenarios:\n      `codeyam editor scenarios`'],
+        11: [
             'Check existing user-persona scenarios:\n      `codeyam editor scenarios`',
         ],
-        10: ['Re-verify is safe to repeat — just re-run the checks'],
-        11: [
+        12: ['Re-verify is safe to repeat — just re-run the checks'],
+        13: [
             'Check if a journal entry already exists for this feature:\n      `codeyam editor journal-list`',
             'If an entry exists, use PATCH to update it — do NOT create a new one',
         ],
-        12: ['Re-verify is safe to repeat — just re-run the checks'],
-        13: ['Check if commit already made:\n      `git log --oneline -3`'],
-        14: ['Check if commit already made:\n      `git log --oneline -3`'],
-        15: [
+        14: ['Re-verify is safe to repeat — just re-run the checks'],
+        15: ['Check if commit already made:\n      `git log --oneline -3`'],
+        16: ['Check if commit already made:\n      `git log --oneline -3`'],
+        17: [
             'Check if journal was already updated with commit SHA:\n      `codeyam editor journal-list`',
             'Check if commit was already amended:\n      `git log --oneline -3`',
         ],
-        16: [
+        18: [
             'Check if already pushed:\n      `git remote -v && git log --oneline origin/HEAD..HEAD 2>/dev/null`',
         ],
     };
@@ -562,7 +568,7 @@ function parseDebugTargets(target) {
         }
         if (entry.startsWith('step-')) {
             const num = parseInt(entry.replace('step-', ''), 10);
-            if (!isNaN(num) && num >= 1 && num <= 16) {
+            if (!isNaN(num) && num >= 1 && num <= 18) {
                 valid.add(`step-${num}`);
                 continue;
             }
@@ -788,24 +794,26 @@ function printCycleOverview(root, state) {
         console.log(chalk.yellow('This applies even after committing — always use the change workflow.'));
     }
     else {
-        console.log('Each feature follows 16 steps. You MUST run each command in order:');
+        console.log('Each feature follows 18 steps. You MUST run each command in order:');
         console.log();
-        console.log(`  ${chalk.bold.yellow(' 1')} ${chalk.bold('Plan')}            — Plan the feature, confirm with user`);
-        console.log(`  ${chalk.bold.yellow(' 2')} ${chalk.bold('Prototype')}       — Build a working prototype fast`);
-        console.log(`  ${chalk.bold.yellow(' 3')} ${chalk.bold('Confirm')}         — Confirm prototype with user`);
-        console.log(`  ${chalk.bold.yellow(' 4')} ${chalk.bold('Deconstruct')}     — Read code, plan all extractions`);
-        console.log(`  ${chalk.bold.yellow(' 5')} ${chalk.bold('Extract')}         — TDD extraction of functions + components`);
-        console.log(`  ${chalk.bold.yellow(' 6')} ${chalk.bold('Glossary')}        — Record functions in glossary`);
-        console.log(`  ${chalk.bold.yellow(' 7')} ${chalk.bold('Analyze')}         — Analyze and verify components`);
-        console.log(`  ${chalk.bold.yellow(' 8')} ${chalk.bold('App Scenarios')}   — Create app-level scenarios`);
-        console.log(`  ${chalk.bold.yellow(' 9')} ${chalk.bold('User Scenarios')}  — Create user-persona scenarios`);
-        console.log(`  ${chalk.bold.yellow('10')} ${chalk.bold('Verify')}          — Review screenshots, check for errors`);
-        console.log(`  ${chalk.bold.yellow('11')} ${chalk.bold('Journal')}         — Create/update journal entry`);
-        console.log(`  ${chalk.bold.yellow('12')} ${chalk.bold('Review')}          — Verify screenshots and audit`);
-        console.log(`  ${chalk.bold.yellow('13')} ${chalk.bold('Present')}         — Present summary, get approval`);
-        console.log(`  ${chalk.bold.yellow('14')} ${chalk.bold('Commit')}          — Commit all changes`);
-        console.log(`  ${chalk.bold.yellow('15')} ${chalk.bold('Finalize')}        — Journal update + amend commit`);
-        console.log(`  ${chalk.bold.yellow('16')} ${chalk.bold('Push')}            — Push to remote`);
+        console.log(`  ${chalk.bold.yellow(' 1')} ${chalk.bold('Plan')}               — Plan the feature, confirm with user`);
+        console.log(`  ${chalk.bold.yellow(' 2')} ${chalk.bold('Prepare')}            — Set up project and dependencies`);
+        console.log(`  ${chalk.bold.yellow(' 3')} ${chalk.bold('Prototype')}          — Build a working prototype fast`);
+        console.log(`  ${chalk.bold.yellow(' 4')} ${chalk.bold('Verify Prototype')}   — Verify prototype works correctly`);
+        console.log(`  ${chalk.bold.yellow(' 5')} ${chalk.bold('Confirm')}            — Confirm prototype with user`);
+        console.log(`  ${chalk.bold.yellow(' 6')} ${chalk.bold('Deconstruct')}        — Read code, plan all extractions`);
+        console.log(`  ${chalk.bold.yellow(' 7')} ${chalk.bold('Extract')}            — TDD extraction of functions + components`);
+        console.log(`  ${chalk.bold.yellow(' 8')} ${chalk.bold('Glossary')}           — Record functions in glossary`);
+        console.log(`  ${chalk.bold.yellow(' 9')} ${chalk.bold('Analyze')}            — Analyze and verify components`);
+        console.log(`  ${chalk.bold.yellow('10')} ${chalk.bold('App Scenarios')}      — Create app-level scenarios`);
+        console.log(`  ${chalk.bold.yellow('11')} ${chalk.bold('User Scenarios')}     — Create user-persona scenarios`);
+        console.log(`  ${chalk.bold.yellow('12')} ${chalk.bold('Verify')}             — Review screenshots, check for errors`);
+        console.log(`  ${chalk.bold.yellow('13')} ${chalk.bold('Journal')}            — Create/update journal entry`);
+        console.log(`  ${chalk.bold.yellow('14')} ${chalk.bold('Review')}             — Verify screenshots and audit`);
+        console.log(`  ${chalk.bold.yellow('15')} ${chalk.bold('Present')}            — Present summary, get approval`);
+        console.log(`  ${chalk.bold.yellow('16')} ${chalk.bold('Commit')}             — Commit all changes`);
+        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.dim('  If the user already described what they want, pass it: codeyam editor 1 --prompt "their message"'));
@@ -897,7 +905,7 @@ function printStep1(root, feature, options, userPrompt) {
     console.log(chalk.dim('  Replace "Feature Name" with a short title for what you just described.'));
     console.log();
 }
-// ─── Step 2: Prototype ────────────────────────────────────────────────
+// ─── Step 2: Prepare ──────────────────────────────────────────────────
 function printStep2(root, feature) {
     const port = getServerPort();
     const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
@@ -914,12 +922,19 @@ function printStep2(root, feature) {
         appFormats: prevState?.appFormats,
         techStackId: prevState?.techStackId,
     });
-    logEvent(root, 'step', { step: 2, label: 'Prototype', feature });
-    stepHeader(2, 'Prototype', feature);
+    logEvent(root, 'step', { step: 2, label: 'Prepare', feature });
+    stepHeader(2, 'Prepare', feature);
     if (isResuming) {
         printResumptionHeader(2);
     }
-    console.log('Build fast with real data. Prioritize speed over quality.');
+    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
     if (!projectExists) {
@@ -948,7 +963,6 @@ 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();
-        console.log(chalk.bold('Build the feature:'));
     }
     else {
         console.log(chalk.bold('Prepare the database for this feature:'));
@@ -964,6 +978,32 @@ function printStep2(root, feature) {
         console.log(chalk.dim('    If no existing scenario fits, use the default seed: npm run db:seed'));
         console.log();
     }
+    stopGate(2);
+}
+// ─── Step 3: Prototype ────────────────────────────────────────────────
+function printStep3(root, feature) {
+    const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
+    const projectExists = hasProject(root);
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 3;
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature,
+        step: 3,
+        label: STEP_LABELS[3],
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
+    });
+    logEvent(root, 'step', { step: 3, label: 'Prototype', feature });
+    stepHeader(3, 'Prototype', feature);
+    if (isResuming) {
+        printResumptionHeader(3);
+    }
+    console.log('Build fast with real data. Prioritize speed over quality.');
+    console.log();
     console.log(chalk.bold('Checklist:'));
     checkbox('Create API routes that read from the database via Prisma');
     if (!projectExists) {
@@ -1012,6 +1052,28 @@ function printStep2(root, feature) {
     console.log(chalk.cyan(`  codeyam editor preview '{"path":"/drinks/1","dimension":"${dim}"}'`));
     printDimensionGuidance(dim, dimNames);
     console.log();
+    stopGate(3);
+}
+// ─── Step 4: Verify Prototype ─────────────────────────────────────────
+function printStep4(root, feature) {
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 4;
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature,
+        step: 4,
+        label: STEP_LABELS[4],
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
+    });
+    logEvent(root, 'step', { step: 4, label: 'Verify Prototype', feature });
+    stepHeader(4, 'Verify Prototype', feature);
+    if (isResuming) {
+        printResumptionHeader(4);
+    }
+    console.log('Verify everything works before presenting the prototype.');
+    console.log();
     console.log(chalk.bold('Verify the dev server:'));
     console.log(chalk.dim(`  # Get dev server URL: codeyam editor dev-server`));
     console.log(chalk.dim('  # Check page loads: curl -s -o /dev/null -w "%{http_code}" http://localhost:<dev-port>'));
@@ -1038,26 +1100,26 @@ function printStep2(root, feature) {
     console.log(chalk.dim('    A new clone should work with just: git clone → npm run setup → npm run dev'));
     console.log();
     console.log(chalk.dim('Focus on building the prototype. Scenarios and refactoring happen in later steps.'));
-    stopGate(2);
+    stopGate(4);
 }
-// ─── Step 3: Confirm ──────────────────────────────────────────────────
-function printStep3(root, feature) {
+// ─── Step 5: Confirm ──────────────────────────────────────────────────
+function printStep5(root, feature) {
     const port = getServerPort();
     const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
-    const isResuming = prevState?.step === 3;
+    const isResuming = prevState?.step === 5;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 3,
-        label: STEP_LABELS[3],
+        step: 5,
+        label: STEP_LABELS[5],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 3, label: 'Confirm', feature });
-    stepHeader(3, 'Confirm', feature);
+    logEvent(root, 'step', { step: 5, label: 'Confirm', feature });
+    stepHeader(5, 'Confirm', feature);
     if (isResuming) {
-        printResumptionHeader(3);
+        printResumptionHeader(5);
     }
     console.log('Summarize what was built and get user confirmation.');
     console.log();
@@ -1074,6 +1136,11 @@ function printStep3(root, feature) {
     console.log(chalk.dim('    If there are errors, fix the underlying issue before presenting.'));
     checkbox('Verify `hasContent=true` and `liveErrors=0` — do NOT ask the user to confirm if the preview is broken');
     console.log();
+    console.log(chalk.bold('Verify the captured user prompt:'));
+    checkbox("Read `.codeyam/editor-user-prompt.txt` — this is the user's original feature request");
+    checkbox('If the file is missing or does not match what the user actually asked for, write the correct prompt text to `.codeyam/editor-user-prompt.txt`');
+    console.log(chalk.dim("    This must be the user's exact words, not a summary. It gets recorded in the journal."));
+    console.log();
     console.log(chalk.bold('Then present to the user:'));
     checkbox('Summarize what was built (routes, components, data)');
     checkbox(`Navigate the preview to the feature's primary page: \`codeyam editor preview '{"path":"/your-page","dimension":"${dim}"}'\``);
@@ -1087,62 +1154,62 @@ function printStep3(root, feature) {
     checkbox('Ask the user: "Does everything work as expected?"');
     console.log();
     console.log(chalk.bold('Present a selection menu to the user (use AskUserQuestion with these EXACT option labels):'));
-    console.log(chalk.green('    Option 1 label: "The live preview is displaying what I expected"') + chalk.dim(' — proceed to step 4'));
+    console.log(chalk.green('    Option 1 label: "The live preview is displaying what I expected"') + chalk.dim(' — proceed to step 6'));
     console.log(chalk.yellow('    Option 2 label: "I\'d like some changes"') +
-        chalk.dim(' — make changes, refresh preview, re-run `codeyam editor 3`'));
+        chalk.dim(' — make changes, refresh preview, re-run `codeyam editor 5`'));
     console.log();
     console.log(chalk.dim('Wait for user approval before moving on. Refactoring and scenarios happen in later steps.'));
-    stopGate(3, { confirm: true });
+    stopGate(5, { confirm: true });
 }
-// ─── Step 4: Deconstruct ──────────────────────────────────────────────
-function printStep4(root, feature) {
+// ─── Step 6: Deconstruct ──────────────────────────────────────────────
+function printStep6(root, feature) {
     const prevState = readState(root);
-    const isResuming = prevState?.step === 4;
+    const isResuming = prevState?.step === 6;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 4,
-        label: STEP_LABELS[4],
+        step: 6,
+        label: STEP_LABELS[6],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 4, label: 'Deconstruct', feature });
-    stepHeader(4, 'Deconstruct', feature);
+    logEvent(root, 'step', { step: 6, label: 'Deconstruct', feature });
+    stepHeader(6, 'Deconstruct', feature);
     if (isResuming) {
-        printResumptionHeader(4);
+        printResumptionHeader(6);
     }
     console.log(chalk.bold('Goal: pages contain ONLY components. Components contain ONLY sub-components.'));
-    console.log(chalk.yellow('This step is read and plan only. Code extraction happens in step 5.'));
+    console.log(chalk.yellow('This step is read and plan only. Code extraction happens in step 7.'));
     console.log();
     printExtractionPlanInstructions();
-    stopGate(4);
+    stopGate(6);
 }
-// ─── Step 5: Extract ──────────────────────────────────────────────────
-function printStep5(root, feature) {
+// ─── Step 7: Extract ──────────────────────────────────────────────────
+function printStep7(root, feature) {
     const port = getServerPort();
     const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
-    const isResuming = prevState?.step === 5;
+    const isResuming = prevState?.step === 7;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 5,
-        label: STEP_LABELS[5],
+        step: 7,
+        label: STEP_LABELS[7],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 5, label: 'Extract', feature });
-    stepHeader(5, 'Extract', feature);
+    logEvent(root, 'step', { step: 7, label: 'Extract', feature });
+    stepHeader(7, 'Extract', feature);
     if (isResuming) {
-        printResumptionHeader(5);
+        printResumptionHeader(7);
     }
-    console.log('Execute your extraction plan from step 4.');
+    console.log('Execute your extraction plan from step 6.');
     console.log();
     console.log(chalk.bold('Components:'));
     checkbox('Extract each component from your plan into its own file');
     checkbox('Page/route files must contain ZERO direct JSX — only imported components');
     checkbox('Every component that renders multiple sections must be split into sub-components');
-    console.log(chalk.dim('    No tests needed — visual verification happens in step 7'));
+    console.log(chalk.dim('    No tests needed — visual verification happens in step 9'));
     console.log();
     console.log(chalk.bold('Library functions AND hooks (TDD):'));
     checkbox('For each function/hook: write MULTIPLE failing tests FIRST, then extract to make them pass');
@@ -1150,7 +1217,7 @@ function printStep5(root, feature) {
     console.log(chalk.dim('    Aim for 3-8 test cases per function depending on complexity'));
     console.log(chalk.dim('    Hooks count as functions — useDrinks, useAuth, etc. all need test files'));
     checkbox('Place test files next to source: `app/lib/drinks.ts` → `app/lib/drinks.test.ts`');
-    console.log(chalk.yellow('  Tests ARE the only coverage for library functions/hooks — step 7 only captures component screenshots.'));
+    console.log(chalk.yellow('  Tests ARE the only coverage for library functions/hooks — step 9 only captures component screenshots.'));
     console.log();
     console.log(chalk.bold('Recursive pass:'));
     checkbox('Re-read EVERY new file you just created — extract components from components, functions from functions');
@@ -1168,55 +1235,55 @@ function printStep5(root, feature) {
     console.log(chalk.dim('Reuse glossary functions when they fit naturally. Extract a new function when the use case diverges.'));
     console.log();
     console.log(chalk.dim('Focus on TDD for functions and extraction for components. Scenarios come in later steps.'));
-    stopGate(5);
+    stopGate(7);
 }
-// ─── Step 6: Glossary ─────────────────────────────────────────────────
-function printStep6(root, feature) {
+// ─── Step 8: Glossary ─────────────────────────────────────────────────
+function printStep8(root, feature) {
     const prevState = readState(root);
-    const isResuming = prevState?.step === 6;
+    const isResuming = prevState?.step === 8;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 6,
-        label: STEP_LABELS[6],
+        step: 8,
+        label: STEP_LABELS[8],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 6, label: 'Glossary', feature });
-    stepHeader(6, 'Glossary', feature);
+    logEvent(root, 'step', { step: 8, label: 'Glossary', feature });
+    stepHeader(8, 'Glossary', feature);
     if (isResuming) {
-        printResumptionHeader(6);
+        printResumptionHeader(8);
     }
     console.log('Record all new functions/components in `.codeyam/glossary.json`.');
     console.log();
     printGlossaryInstructions(feature);
     console.log();
     console.log(chalk.dim('Focus on updating the glossary. Application code and scenarios come in later steps.'));
-    stopGate(6);
+    stopGate(8);
 }
-// ─── Step 7: Analyze ──────────────────────────────────────────────────
-function printStep7(root, feature) {
+// ─── Step 9: Analyze ──────────────────────────────────────────────────
+function printStep9(root, feature) {
     const port = getServerPort();
     const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
-    const isResuming = prevState?.step === 7;
+    const isResuming = prevState?.step === 9;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 7,
-        label: STEP_LABELS[7],
+        step: 9,
+        label: STEP_LABELS[9],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 7, label: 'Analyze', feature });
-    stepHeader(7, 'Analyze and Verify', feature);
+    logEvent(root, 'step', { step: 9, label: 'Analyze', feature });
+    stepHeader(9, 'Analyze and Verify', feature);
     if (isResuming) {
-        printResumptionHeader(7);
+        printResumptionHeader(9);
     }
     console.log('Verify visual components (via isolation routes) and library functions (via tests).');
     console.log();
     console.log(chalk.bold('Visual Components — Component Isolation:'));
-    checkbox('List all files with new/modified visual components from step 5');
+    checkbox('List all files with new/modified visual components from step 7');
     checkbox('Check existing scenarios: `codeyam editor scenarios`');
     console.log(chalk.dim('    Reuse and improve existing scenarios where possible — update mock data'));
     console.log(chalk.dim('    to reflect current changes. Add new scenarios only for genuinely new states.'));
@@ -1224,7 +1291,7 @@ function printStep7(root, feature) {
     printComponentCaptureInstructions();
     console.log();
     console.log(chalk.bold('Library Functions — run tests:'));
-    checkbox('Run ALL test files created in step 5');
+    checkbox('Run ALL test files created in step 7');
     console.log(chalk.dim('    Example: npx vitest run app/lib/drinks.test.ts'));
     checkbox('Verify every test passes');
     checkbox('If any test fails, fix the source code and re-run');
@@ -1232,29 +1299,29 @@ function printStep7(root, feature) {
     console.log(chalk.dim('Do not proceed until both component isolations and library tests pass.'));
     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 8 will refuse to run until the audit passes.'));
+    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();
-    stopGate(7);
+    stopGate(9);
 }
-// ─── Step 8: App Scenarios ────────────────────────────────────────────
-function printStep8(root, feature) {
+// ─── Step 10: App Scenarios ────────────────────────────────────────────
+function printStep10(root, feature) {
     const port = getServerPort();
     const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
-    const isResuming = prevState?.step === 8;
+    const isResuming = prevState?.step === 10;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 8,
-        label: STEP_LABELS[8],
+        step: 10,
+        label: STEP_LABELS[10],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 8, label: 'App Scenarios', feature });
-    stepHeader(8, 'App Scenarios', feature);
+    logEvent(root, 'step', { step: 10, label: 'App Scenarios', feature });
+    stepHeader(10, 'App Scenarios', feature);
     if (isResuming) {
-        printResumptionHeader(8);
+        printResumptionHeader(10);
     }
     console.log('Create app-level scenarios with rich data that robustly demonstrates this feature.');
     console.log();
@@ -1276,13 +1343,19 @@ function printStep8(root, feature) {
     console.log(chalk.cyan("  • New data states that can't coexist in one scenario (empty vs rich, error vs success) → new scenario"));
     console.log(chalk.cyan("  • Don't duplicate — if an existing scenario can cover a state with richer data, enhance it instead"));
     console.log();
+    console.log(chalk.bold.cyan('Scenario naming — describe data states, not features:'));
+    console.log(chalk.cyan('  • Name scenarios by what they represent: "Rich Data", "Empty", "Mobile", "Minimal"'));
+    console.log(chalk.cyan('  • When enhancing a scenario with new feature data, update the name if it has grown beyond its original scope'));
+    console.log(chalk.cyan('  • A single rich scenario exercising multiple features is more valuable than separate thin scenarios per feature'));
+    console.log(chalk.cyan('  • Re-register with the same name to update; to rename, register with the new name'));
+    console.log();
     checkbox('Ensure scenarios clearly demonstrate what changed in this session');
     console.log(chalk.dim('    If data models changed: update existing scenarios seed data to match'));
     console.log(chalk.dim('    If UI changed: re-register existing scenarios so screenshots reflect the update'));
     console.log(chalk.dim('    Add new scenarios only for genuinely new data states not covered by existing ones'));
     printAppScenarioInstructions();
     console.log();
-    console.log(chalk.dim('Focus on creating and registering app-level scenarios. Code fixes happen in step 10 if needed.'));
+    console.log(chalk.dim('Focus on creating and registering app-level scenarios. Code fixes happen in step 12 if needed.'));
     console.log();
     console.log(chalk.bold.cyan("Verify your work — screenshots don't lie:"));
     console.log(chalk.cyan('  • View every captured screenshot. Does it show what the scenario name promises?'));
@@ -1293,43 +1366,43 @@ function printStep8(root, feature) {
     console.log(chalk.bold.yellow('GATE: Before proceeding, run `codeyam editor scenario-coverage`'));
     console.log(chalk.yellow('  This checks which existing scenarios have stale screenshots.'));
     console.log(chalk.yellow('  Re-register every stale scenario listed until the check passes.'));
-    stopGate(8);
+    stopGate(10);
 }
-// ─── Step 9: User Scenarios ───────────────────────────────────────────
-function printStep9(root, feature) {
+// ─── Step 11: User Scenarios ───────────────────────────────────────────
+function printStep11(root, feature) {
     const port = getServerPort();
     const prevState = readState(root);
-    const isResuming = prevState?.step === 9;
+    const isResuming = prevState?.step === 11;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 9,
-        label: STEP_LABELS[9],
+        step: 11,
+        label: STEP_LABELS[11],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 9, label: 'User Scenarios', feature });
-    stepHeader(9, 'User Scenarios', feature);
+    logEvent(root, 'step', { step: 11, label: 'User Scenarios', feature });
+    stepHeader(11, 'User Scenarios', feature);
     if (isResuming) {
-        printResumptionHeader(9);
+        printResumptionHeader(11);
     }
-    console.log('Create per-persona variations of existing scenarios. Skip to step 10 if no users.');
+    console.log('Create per-persona variations of existing scenarios. Skip to step 12 if no users.');
     console.log();
     console.log(chalk.bold('If the app has NO users/auth:'));
-    console.log(chalk.dim('  Skip this step and proceed to step 10 (Verify).'));
+    console.log(chalk.dim('  Skip this step and proceed to step 12 (Verify).'));
     console.log();
     console.log(chalk.bold('If the app has users/auth:'));
     console.log();
     console.log(chalk.bold('Goal: Create persona variations of EXISTING app scenarios.'));
     console.log(chalk.dim('  Do NOT create standalone persona scenarios. Each user-persona scenario should be'));
-    console.log(chalk.dim('  a variation of an existing app scenario from step 8, with user-specific state layered on.'));
+    console.log(chalk.dim('  a variation of an existing app scenario from step 10, with user-specific state layered on.'));
     console.log();
     console.log(chalk.bold('Checklist:'));
     checkbox('Run `codeyam editor scenarios` — list all existing app scenarios');
     checkbox('For EACH existing app scenario, create a logged-in variation:');
     console.log(chalk.dim('    Copy the scenario seed data and add "session":{"cookieValue":"sess_alice"} + user seed'));
     console.log(chalk.dim('    Name: "<Original Name> - Logged In" (e.g. "Full Catalog - Logged In")'));
-    console.log(chalk.dim('    Step 8 scenarios already serve as logged-out versions (no session cookie)'));
+    console.log(chalk.dim('    Step 10 scenarios already serve as logged-out versions (no session cookie)'));
     checkbox('If there are multiple user roles (admin, regular, etc.), create role-specific variations too');
     console.log(chalk.dim('    Each persona scenario layers user-specific seed data on top of an app scenario'));
     checkbox('Include "dimensions" — inherit from the base app scenario, or override if the persona implies a different device');
@@ -1338,26 +1411,26 @@ function printStep9(root, feature) {
     console.log(chalk.yellow('    If clientErrors is non-empty → fix the issue and re-register the scenario'));
     console.log();
     console.log(chalk.dim('See FEATURE_PATTERNS.md and AUTH_PATTERNS.md for auth scenario guidance.'));
-    stopGate(9);
+    stopGate(11);
 }
-// ─── Step 10: Verify ──────────────────────────────────────────────────
-function printStep10(root, feature) {
+// ─── Step 12: Verify ──────────────────────────────────────────────────
+function printStep12(root, feature) {
     const port = getServerPort();
     const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
-    const isResuming = prevState?.step === 10;
+    const isResuming = prevState?.step === 12;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 10,
-        label: STEP_LABELS[10],
+        step: 12,
+        label: STEP_LABELS[12],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 10, label: 'Verify', feature });
-    stepHeader(10, 'Verify', feature);
+    logEvent(root, 'step', { step: 12, label: 'Verify', feature });
+    stepHeader(12, 'Verify', feature);
     if (isResuming) {
-        printResumptionHeader(10);
+        printResumptionHeader(12);
     }
     console.log('Verify component isolation screenshots, editor scenarios, and library tests.');
     console.log();
@@ -1380,63 +1453,63 @@ function printStep10(root, feature) {
     checkbox('Verify no broken images: `codeyam editor verify-images \'{"paths":["/"], "imageUrls":["url1"]}\'` with all page paths and image URLs');
     console.log();
     console.log(chalk.bold('Library functions — test check:'));
-    checkbox('Re-run all test files from step 5 to confirm they still pass');
+    checkbox('Re-run all test files from step 7 to confirm they still pass');
     console.log(chalk.dim('    Example: npx vitest run app/lib/drinks.test.ts'));
     checkbox('If any test fails, fix the source code and re-run');
     console.log();
     console.log(chalk.dim('Focus on fixing issues. All component screenshots, scenarios, and tests must be clean before proceeding.'));
-    stopGate(10);
+    stopGate(12);
 }
-// ─── Step 11: Journal ─────────────────────────────────────────────────
-function printStep11(root, feature) {
+// ─── Step 13: Journal ─────────────────────────────────────────────────
+function printStep13(root, feature) {
     const port = getServerPort();
     const prevState = readState(root);
-    const isResuming = prevState?.step === 11;
+    const isResuming = prevState?.step === 13;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 11,
-        label: STEP_LABELS[11],
+        step: 13,
+        label: STEP_LABELS[13],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 11, label: 'Journal', feature });
-    stepHeader(11, 'Journal', feature);
+    logEvent(root, 'step', { step: 13, label: 'Journal', feature });
+    stepHeader(13, 'Journal', feature);
     if (isResuming) {
-        printResumptionHeader(11);
+        printResumptionHeader(13);
     }
     console.log('Create or update the journal entry for this feature.');
     console.log();
     console.log(chalk.bold('Checklist:'));
     checkbox('Write a concise description of what was built (2-3 sentences)');
-    checkbox(`First time at step 11 — create journal entry with ALL session screenshots:`);
+    checkbox(`First time at step 13 — create journal entry with ALL session screenshots:`);
     console.log(chalk.dim(`    codeyam editor journal '{"title":"...","type":"feature","description":"...","includeSessionScenarios":true}'`));
     console.log(chalk.dim('    includeSessionScenarios auto-discovers component + app + user persona screenshots'));
-    checkbox(`Returning to step 11 (before commit) — update the existing journal entry:`);
+    checkbox(`Returning to step 13 (before commit) — update the existing journal entry:`);
     console.log(chalk.dim(`    codeyam editor journal-update '{"time":"<journal entry time>","description":"<updated>","includeSessionScenarios":true}'`));
     console.log(chalk.dim('    Note: PATCH only works before the entry is committed. After commit, use POST to create a new entry.'));
     console.log();
-    console.log(chalk.dim('Focus on creating or updating the journal entry. Summary and presentation happen in step 13.'));
-    stopGate(11);
+    console.log(chalk.dim('Focus on creating or updating the journal entry. Summary and presentation happen in step 15.'));
+    stopGate(13);
 }
-// ─── Step 12: Review ──────────────────────────────────────────────────
-function printStep12(root, feature) {
+// ─── Step 14: Review ──────────────────────────────────────────────────
+function printStep14(root, feature) {
     const port = getServerPort();
     const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
-    const isResuming = prevState?.step === 12;
+    const isResuming = prevState?.step === 14;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 12,
-        label: STEP_LABELS[12],
+        step: 14,
+        label: STEP_LABELS[14],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 12, label: 'Review', feature });
-    stepHeader(12, 'Review', feature);
+    logEvent(root, 'step', { step: 14, label: 'Review', feature });
+    stepHeader(14, 'Review', feature);
     if (isResuming) {
-        printResumptionHeader(12);
+        printResumptionHeader(14);
     }
     console.log('Verify all screenshots and checks pass before presenting to the user.');
     console.log();
@@ -1449,26 +1522,27 @@ function printStep12(root, feature) {
     checkbox('If `hasErrors` is true, fix them and re-capture affected scenarios');
     checkbox('Run `codeyam editor verify-images \'{"paths":["/"], "imageUrls":["url1"]}\'` with all page paths and image URLs');
     checkbox('Fix or remove any broken images before continuing');
+    checkbox('Recapture stale scenarios: `codeyam editor recapture-stale`');
     checkbox('Run `codeyam editor audit` to verify completeness of scenarios and tests');
     checkbox('Do not proceed until all checks pass');
-    stopGate(12);
+    stopGate(14);
 }
-// ─── Step 13: Present ─────────────────────────────────────────────────
-function printStep13(root, feature) {
+// ─── Step 15: Present ─────────────────────────────────────────────────
+function printStep15(root, feature) {
     const prevState = readState(root);
-    const isResuming = prevState?.step === 13;
+    const isResuming = prevState?.step === 15;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 13,
-        label: STEP_LABELS[13],
+        step: 15,
+        label: STEP_LABELS[15],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 13, label: 'Present', feature });
-    stepHeader(13, 'Present', feature);
+    logEvent(root, 'step', { step: 15, label: 'Present', feature });
+    stepHeader(15, 'Present', feature);
     if (isResuming) {
-        printResumptionHeader(13);
+        printResumptionHeader(15);
     }
     console.log('Present the results to the user and get their approval.');
     console.log();
@@ -1487,7 +1561,7 @@ function printStep13(root, feature) {
         chalk.dim(' — describe changes, then re-verify'));
     console.log();
     console.log(chalk.bold('If the user chooses "Save & commit":'));
-    checkbox('Advance to the commit step: `codeyam editor 14`');
+    checkbox('Advance to the commit step: `codeyam editor 16`');
     console.log();
     console.log(chalk.bold('If the user chooses "Make changes" (or asks for ANY change, even as a question):'));
     checkbox(`Hide the results panel: \`codeyam editor hide-results\``);
@@ -1495,7 +1569,7 @@ function printStep13(root, feature) {
     checkbox(`Run: \`codeyam editor change "${feature}"\` — this gives you the change checklist`);
     checkbox('THEN make the requested changes and follow the checklist');
     console.log(chalk.red.bold('  IMPORTANT: Always run the change command BEFORE writing any code.'));
-    stopGate(13, { confirm: true });
+    stopGate(15, { confirm: true });
 }
 // ─── Migration Mode ──────────────────────────────────────────────────
 /**
@@ -2102,47 +2176,48 @@ function handleMigrateCommand(root, subArg) {
     };
     stepFns[step](root);
 }
-// ─── Step 14: Commit ─────────────────────────────────────────────────
-function printStep14(root, feature) {
+// ─── Step 16: Commit ─────────────────────────────────────────────────
+function printStep16(root, feature) {
     const prevState = readState(root);
-    const isResuming = prevState?.step === 14;
+    const isResuming = prevState?.step === 16;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 14,
-        label: STEP_LABELS[14],
+        step: 16,
+        label: STEP_LABELS[16],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 14, label: 'Commit', feature });
-    stepHeader(14, 'Commit', feature);
+    logEvent(root, 'step', { step: 16, label: 'Commit', feature });
+    stepHeader(16, 'Commit', feature);
     if (isResuming) {
-        printResumptionHeader(14);
+        printResumptionHeader(16);
     }
     console.log('Commit all changes for this feature.');
     console.log();
     console.log(chalk.bold('Checklist:'));
+    checkbox('Ensure all screenshots are fresh: `codeyam editor recapture-stale`');
     checkbox(`Hide the results panel: \`codeyam editor hide-results\``);
     checkbox(`Git commit using the journal description: \`codeyam editor commit '{"message":"feat: <title>\\n\\n<journal description>"}'\``);
     console.log(chalk.dim('    The commit message body MUST match the journal description exactly'));
-    stopGate(14);
+    stopGate(16);
 }
-// ─── Step 15: Finalize ───────────────────────────────────────────────
-function printStep15(root, feature) {
+// ─── Step 17: Finalize ───────────────────────────────────────────────
+function printStep17(root, feature) {
     const prevState = readState(root);
-    const isResuming = prevState?.step === 15;
+    const isResuming = prevState?.step === 17;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 15,
-        label: STEP_LABELS[15],
+        step: 17,
+        label: STEP_LABELS[17],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 15, label: 'Finalize', feature });
-    stepHeader(15, 'Finalize', feature);
+    logEvent(root, 'step', { step: 17, label: 'Finalize', feature });
+    stepHeader(17, 'Finalize', feature);
     if (isResuming) {
-        printResumptionHeader(15);
+        printResumptionHeader(17);
     }
     console.log('Update the journal with the commit SHA and amend the commit.');
     console.log();
@@ -2150,24 +2225,24 @@ function printStep15(root, feature) {
     checkbox(`Update journal with commit SHA: \`codeyam editor journal-update '{"time":"<journal entry time>","commitSha":"<sha>","commitMessage":"feat: <title>"}'\``);
     checkbox('Amend the commit to include the journal update: `git add .codeyam/journal/ && git commit --amend --no-edit`');
     console.log(chalk.dim('    The journal-update modifies journal files after the commit — amend to keep the tree clean.'));
-    stopGate(15);
+    stopGate(17);
 }
-// ─── Step 16: Push ───────────────────────────────────────────────────
-function printStep16(root, feature) {
+// ─── Step 18: Push ───────────────────────────────────────────────────
+function printStep18(root, feature) {
     const prevState = readState(root);
-    const isResuming = prevState?.step === 16;
+    const isResuming = prevState?.step === 18;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 16,
-        label: STEP_LABELS[16],
+        step: 18,
+        label: STEP_LABELS[18],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 16, label: 'Push', feature });
-    stepHeader(16, 'Push', feature);
+    logEvent(root, 'step', { step: 18, label: 'Push', feature });
+    stepHeader(18, 'Push', feature);
     if (isResuming) {
-        printResumptionHeader(16);
+        printResumptionHeader(18);
     }
     console.log('Push the commit to the remote repository.');
     console.log();
@@ -2178,12 +2253,17 @@ function printStep16(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('After the user responds, run: `codeyam editor steps` to start the next feature');
-    console.log();
-    console.log(chalk.red.bold('  If the user reports a bug or requests a fix after committing:'));
-    console.log(chalk.red.bold('  You MUST still run `codeyam editor change` before making any changes.'));
-    console.log(chalk.red.bold('  The change workflow applies to ALL changes — post-commit fixes are not an exception.'));
-    stopGate(16, { confirm: true });
+    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();
+    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('  The change workflow is ONLY for modifications during steps 1-15, not after commit.'));
+    stopGate(18, { confirm: true });
 }
 // ─── Command definition ───────────────────────────────────────────────
 // ─── Analyze-imports subcommand ────────────────────────────────────────
@@ -2203,7 +2283,7 @@ async function handleAnalyzeImports(options = {}) {
             return;
         }
         console.error(chalk.red('Error: .codeyam/glossary.json not found.'));
-        console.error(chalk.dim('  Run codeyam editor 6 to create the glossary first.'));
+        console.error(chalk.dim('  Run codeyam editor 8 to create the glossary first.'));
         process.exit(1);
     }
     let glossaryEntries;
@@ -2657,8 +2737,14 @@ async function handleRegister(jsonArg) {
             else {
                 parts.push(`errors=0`);
             }
-            if (data.seedResult)
-                parts.push(`seed=${data.seedResult.success}`);
+            if (data.seedResult) {
+                if (data.seedResult.success) {
+                    parts.push(`seed=ok`);
+                }
+                else {
+                    parts.push(chalk.red(`seed=FAILED${data.seedResult.error ? ` (${data.seedResult.error})` : ''}`));
+                }
+            }
             if (data.captureError)
                 parts.push(chalk.yellow(`captureError="${data.captureError}"`));
             console.log(prefix + parts.join(' '));
@@ -2877,7 +2963,7 @@ async function handleDependents(entityName) {
  *
  * Prints a condensed post-change checklist that guides Claude through
  * re-verifying after user-requested modifications. When called from
- * step 13+, this loops back to step 13 (present). When called from an
+ * step 15+, this loops back to step 15 (present). When called from an
  * earlier step, it returns to that step so the normal flow continues.
  */
 function handleChange(feature) {
@@ -2895,7 +2981,7 @@ function handleChange(feature) {
             process.exit(1);
         }
     }
-    const currentStep = state?.step ?? 13;
+    const currentStep = state?.step ?? 15;
     const port = getServerPort();
     console.log();
     console.log(chalk.bold.cyan('━━━ Change Loop ━━━'));
@@ -2943,6 +3029,7 @@ function handleChange(feature) {
     console.log(chalk.dim('    re-register "Home - Default", "Catalog - Full", "Detail - WithReviews", etc.'));
     checkbox("Enrich existing scenario data to exercise the change — don't just re-register unchanged data");
     console.log(chalk.dim('    Add data that demonstrates what changed: new fields, relationships, states, content variety.'));
+    console.log(chalk.dim('    If the enriched data makes the scenario name too narrow, rename it to reflect its broader coverage.'));
     checkbox('After each re-registration, view the screenshot to verify data is visible');
     console.log(chalk.dim("    If the screenshot doesn't show the data you put in, the scenario is broken."));
     console.log();
@@ -2951,6 +3038,7 @@ function handleChange(feature) {
     checkbox(`Navigate to key pages to verify changes: \`codeyam editor preview '{"path":"/your-route","dimension":"${dim}"}'\``);
     printDimensionGuidance(dim, dimNames);
     checkbox('Run `codeyam editor scenario-coverage` — all affected scenarios must be fresh');
+    checkbox('Recapture stale scenarios: `codeyam editor recapture-stale`');
     checkbox('Run `codeyam editor audit` — all checks must pass');
     checkbox(`Check for client-side errors: \`codeyam editor client-errors\``);
     console.log(chalk.dim('    If `hasContent=false`, the preview is blank — fix the code before proceeding.'));
@@ -2965,10 +3053,10 @@ function handleChange(feature) {
     console.log(chalk.dim('    Always update the existing uncommitted entry — do NOT create a new one.'));
     console.log(chalk.dim('    Only create a new entry (POST) if no uncommitted entry exists for this feature.'));
     console.log();
-    // If the change was initiated from a step before 13, return to that step
-    // instead of jumping to step 13. The change workflow should only loop to
-    // step 13 when changes are requested FROM step 13.
-    if (currentStep < 13) {
+    // If the change was initiated from a step before 15, return to that step
+    // instead of jumping to step 15. The change workflow should only loop to
+    // step 15 when changes are requested FROM step 15.
+    if (currentStep < 15) {
         console.log(chalk.red('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
         console.log(chalk.red.bold('  REQUIRED: Return to current step'));
         console.log(chalk.red.bold('  When all checks pass, you MUST run: ') +
@@ -2979,7 +3067,7 @@ function handleChange(feature) {
         console.log(chalk.red('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
         console.log(chalk.red.bold('  REQUIRED: Show Results'));
         console.log(chalk.red.bold('  When all checks pass, you MUST run: ') +
-            chalk.bold(`codeyam editor 13`));
+            chalk.bold(`codeyam editor 15`));
         console.log(chalk.red.bold('  The user ALWAYS expects to see results after changes. DO NOT skip this step.'));
         console.log(chalk.red('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
     }
@@ -3126,8 +3214,6 @@ function printAuditGateFailures(data) {
                 }
             }
             console.error(chalk.yellow('\nFix: Fix the code errors above, then re-capture the affected scenarios.'));
-            console.error(chalk.yellow('If errors reference browser APIs (localStorage, sessionStorage, window, document),'));
-            console.error(chalk.yellow('create a universal mock: codeyam detect-universal-mocks'));
         }
     }
     console.error(chalk.dim('\nRun `codeyam editor audit` for full details.\n'));
@@ -3186,11 +3272,18 @@ async function handleAudit() {
         }
         console.log(chalk.bold('Components (scenarios):'));
         for (const c of components) {
-            const icon = c.status === 'ok' ? chalk.green('✓') : chalk.red('✗');
+            const icon = c.status === 'ok'
+                ? chalk.green('✓')
+                : c.status === 'needs_recapture'
+                    ? chalk.yellow('↻')
+                    : chalk.red('✗');
             let detail;
             if (c.status === 'has_errors') {
                 detail = chalk.red(` — ${c.scenarioCount} scenario${c.scenarioCount !== 1 ? 's' : ''} but has client errors`);
             }
+            else if (c.status === 'needs_recapture') {
+                detail = chalk.yellow(` — ${c.scenarioCount} scenario${c.scenarioCount !== 1 ? 's' : ''}, needs recapture`);
+            }
             else if (c.status === 'ok') {
                 detail = chalk.dim(` (${c.scenarioCount} scenario${c.scenarioCount !== 1 ? 's' : ''})`);
             }
@@ -3199,7 +3292,7 @@ async function handleAudit() {
             }
             // Show file path for failing components always, for OK only when name is ambiguous
             const isDuplicate = (componentNameCounts.get(c.name) || 0) > 1;
-            const showPath = c.status !== 'ok' || isDuplicate;
+            const showPath = (c.status !== 'ok' && c.status !== 'needs_recapture') || isDuplicate;
             const pathSuffix = showPath && c.filePath ? chalk.dim(` (${c.filePath})`) : '';
             console.log(`  ${icon} ${c.name}${pathSuffix}${detail}`);
             if (c.clientErrors && c.clientErrors.length > 0) {
@@ -3209,14 +3302,6 @@ async function handleAudit() {
                 if (c.clientErrors.length > 3) {
                     console.log(chalk.dim(`      … and ${c.clientErrors.length - 3} more`));
                 }
-                // Detect browser API errors and provide actionable guidance
-                const browserApiPattern = /\b(localStorage|sessionStorage|window\.|document\.|navigator\.|indexedDB|matchMedia|ResizeObserver|IntersectionObserver|MutationObserver)\b/;
-                const hasBrowserApiErrors = c.clientErrors.some((err) => browserApiPattern.test(err));
-                if (hasBrowserApiErrors) {
-                    console.log(chalk.yellow(`      ⚠ These errors are caused by browser APIs that don't exist during server-side analysis.`));
-                    console.log(chalk.yellow(`      Fix: Create a universal mock to stub the missing API. Run: codeyam detect-universal-mocks`));
-                    console.log(chalk.yellow(`      DO NOT re-run the audit or analyze-imports — the error will persist until a mock is created.`));
-                }
             }
         }
         console.log();
@@ -3277,11 +3362,9 @@ async function handleAudit() {
             console.log(chalk.red('    analyze-imports was run automatically but these entities are STILL incomplete.'));
             console.log(chalk.red('    DO NOT re-run analyze-imports or the audit in a loop — the result will be the same.'));
             console.log(chalk.yellow('    This means the analysis failed for these entities. Common causes:'));
-            console.log(chalk.yellow('      • Entity code uses browser APIs (localStorage, window, document) — create a universal mock'));
             console.log(chalk.yellow('      • Source file was renamed/deleted but glossary still references the old path'));
             console.log(chalk.yellow('      • Entity has import errors that prevent analysis'));
             console.log(chalk.yellow('    To investigate: run `codeyam editor analyze-imports` (without --silent) to see the full error.'));
-            console.log(chalk.yellow('    To fix browser API issues: run `codeyam detect-universal-mocks`'));
         }
         else {
             console.log(chalk.yellow('    Run `codeyam editor analyze-imports` to analyze these entities'));
@@ -3313,7 +3396,7 @@ async function handleAudit() {
                 : `${s.status.status}`;
             console.log(`  ${chalk.red('✗')} ${s.scenarioName} ${chalk.dim(`(${s.entityName} — ${reason})`)}`);
         }
-        console.log(chalk.yellow('    Re-register these scenarios to capture updated screenshots.'));
+        console.log(chalk.yellow('    Run: codeyam editor recapture-stale'));
         console.log();
     }
     // Duplicate glossary names (warning, not a failure)
@@ -3385,6 +3468,109 @@ async function handleAudit() {
         console.log(chalk.yellow('Warning: Could not build import graph. Run `codeyam editor analyze-imports` manually.'));
     }
 }
+// ─── Recapture-stale subcommand ────────────────────────────────────────
+/**
+ * `codeyam editor recapture-stale`
+ *
+ * Identifies all scenarios whose entity (or dependency) has changed but
+ * whose screenshot hasn't been recaptured this session, then recaptures
+ * them in batch.
+ */
+async function handleRecaptureStale() {
+    const port = getServerPort();
+    const url = `http://localhost:${port}/api/editor-recapture-stale`;
+    console.log();
+    console.log(chalk.bold.cyan('━━━ Recapture Stale Scenarios ━━━'));
+    console.log();
+    let res;
+    try {
+        res = await fetch(url, { method: 'POST' });
+    }
+    catch (err) {
+        console.error(chalk.red('Error: Could not reach the CodeYam server. Is it running?'));
+        console.error(chalk.dim(`  ${err.message}`));
+        process.exit(1);
+    }
+    if (!res.ok) {
+        const body = await res.json().catch(() => null);
+        console.error(chalk.red(`Error: Recapture endpoint returned ${res.status}`));
+        if (body?.error)
+            console.error(chalk.red(`  ${body.error}`));
+        process.exit(1);
+    }
+    // Handle JSON response (early returns like "no changes" / "all up to date")
+    const contentType = res.headers.get('content-type') || '';
+    if (contentType.includes('application/json')) {
+        const data = await res.json();
+        if (data.note) {
+            console.log(chalk.dim(data.note));
+        }
+        else if (data.total === 0) {
+            console.log(chalk.green('All scenarios are up to date.'));
+        }
+        console.log();
+        return;
+    }
+    // Stream NDJSON progress events
+    let total = 0;
+    let recapturedCount = 0;
+    let failedCount = 0;
+    const reader = res.body?.getReader();
+    if (!reader) {
+        console.error(chalk.red('Error: No response body'));
+        process.exit(1);
+    }
+    const decoder = new TextDecoder();
+    let buffer = '';
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || ''; // Keep incomplete last line in buffer
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            try {
+                const event = JSON.parse(line);
+                switch (event.type) {
+                    case 'start':
+                        total = event.total;
+                        console.log(`Found ${total} stale scenario(s). Recapturing...\n`);
+                        break;
+                    case 'capturing':
+                        process.stdout.write(chalk.dim(`  … ${event.name}`));
+                        break;
+                    case 'success':
+                        // Clear the "capturing" line and print success
+                        process.stdout.write('\r\x1b[K');
+                        console.log(`  ${chalk.green('✓')} ${event.name}`);
+                        recapturedCount++;
+                        break;
+                    case 'failure':
+                        process.stdout.write('\r\x1b[K');
+                        console.log(`  ${chalk.red('✗')} ${event.name} — ${chalk.dim(event.error)}`);
+                        failedCount++;
+                        break;
+                    case 'done':
+                        // Final summary
+                        console.log();
+                        const color = failedCount > 0 ? chalk.yellow : chalk.green;
+                        console.log(color(`Recaptured ${recapturedCount}/${total} scenario(s).`));
+                        console.log();
+                        break;
+                }
+            }
+            catch {
+                // Skip unparseable lines
+            }
+        }
+    }
+    if (failedCount > 0) {
+        process.exit(1);
+    }
+}
 // ─── Scenarios subcommand ─────────────────────────────────────────────
 async function handleScenarios() {
     const port = getServerPort();
@@ -3632,7 +3818,7 @@ async function handleTemplate() {
         console.log(chalk.green('  Git initialized.'));
     }
     // 4. Run codeyam init
-    console.log(chalk.bold('Running codeyam init...'));
+    console.log(chalk.bold('Initializing project...'));
     await initCommand.handler({
         force: true,
         'keep-server': true,
@@ -3711,7 +3897,7 @@ async function handleSync() {
         // fall through
     }
     if (!projectSlug) {
-        console.error(chalk.red('Error: No project slug found. Run codeyam init first.'));
+        console.error(chalk.red('Error: No project slug found. Run `codeyam editor template` to initialize the project.'));
         process.exit(1);
     }
     const connectionOk = await withoutSpinner(() => testEnvironment());
@@ -3895,7 +4081,7 @@ function handleEditorDebug(args) {
         scenarios.push({
             id: 'overview-with-state',
             title: 'Cycle overview (project, with state)',
-            render: () => withTempRoot(true, (tempRoot) => captureOutput(() => printCycleOverview(tempRoot, makeState(4, feature)))),
+            render: () => withTempRoot(true, (tempRoot) => captureOutput(() => printCycleOverview(tempRoot, makeState(6, feature)))),
         });
     }
     const stepFns = {
@@ -3915,8 +4101,10 @@ function handleEditorDebug(args) {
         14: printStep14,
         15: printStep15,
         16: printStep16,
+        17: printStep17,
+        18: printStep18,
     };
-    for (let step = 1; step <= 16; step++) {
+    for (let step = 1; step <= 18; step++) {
         const stepId = `step-${step}`;
         if (!wants(stepId))
             continue;
@@ -3936,7 +4124,7 @@ function handleEditorDebug(args) {
             if (step === 2) {
                 scenarios.push({
                     id: 'step-2-scaffold',
-                    title: 'Step 2 (Prototype) — scaffold flow (no project)',
+                    title: 'Step 2 (Prepare) — scaffold flow (no project)',
                     render: () => withTempRoot(false, (tempRoot) => captureOutput(() => printStep2(tempRoot, feature))),
                 });
             }
@@ -3995,8 +4183,8 @@ const editorCommand = {
     describe: 'Editor mode guided workflow',
     builder: (yargs) => {
         const stepDescription = IS_INTERNAL_BUILD
-            ? 'Step number (1-16) or subcommand (template, register, isolate, analyze-imports, dependents, audit, scenarios, scenario-coverage, change, sync, debug, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors)'
-            : 'Step number (1-16) or subcommand (template, register, isolate, analyze-imports, dependents, audit, scenarios, scenario-coverage, 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)'
+            : '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)';
         let builder = yargs
             .positional('step', {
             type: 'string',
@@ -4032,7 +4220,7 @@ const editorCommand = {
             builder = builder
                 .option('target', {
                 type: 'string',
-                describe: 'Debug target (setup, overview, overview-with-state, step-1..step-16, or comma-separated list)',
+                describe: 'Debug target (setup, overview, overview-with-state, step-1..step-18, or comma-separated list)',
             })
                 .option('resume', {
                 type: 'boolean',
@@ -4076,6 +4264,12 @@ const editorCommand = {
                         console.log(JSON.stringify(result.data, null, 2));
                     }
                 }
+                // After a successful commit, remind Claude to continue to step 17
+                if (argv.step === 'commit' && result.ok) {
+                    console.log();
+                    console.log(chalk.green('Commit done. Now run: ') +
+                        chalk.bold('codeyam editor 17'));
+                }
             }
             catch (err) {
                 console.error(chalk.red('Error: Could not reach the CodeYam server. Is it running?'));
@@ -4119,6 +4313,11 @@ const editorCommand = {
             await handleScenarioCoverage();
             return;
         }
+        // Subcommand: codeyam editor recapture-stale
+        if (argv.step === 'recapture-stale') {
+            await handleRecaptureStale();
+            return;
+        }
         // Subcommand: codeyam editor change <feature>
         if (argv.step === 'change') {
             handleChange(argv.json || '');
@@ -4178,18 +4377,13 @@ const editorCommand = {
             }
             else {
                 const state = readState(root);
-                // Clear prompt file when feature is done (step 16) so the hook
-                // can capture the next feature request from the user.
-                if (state?.step === 16) {
-                    clearEditorUserPrompt(root);
-                }
                 printCycleOverview(root, state);
             }
             return;
         }
         const step = argv.step ? parseInt(argv.step, 10) : undefined;
-        if (step != null && (isNaN(step) || step < 1 || step > 16)) {
-            console.error(chalk.red(`Error: Invalid step "${argv.step}". Must be 1-16.`));
+        if (step != null && (isNaN(step) || step < 1 || step > 18)) {
+            console.error(chalk.red(`Error: Invalid step "${argv.step}". Must be 1-18.`));
             process.exit(1);
         }
         if (step == null) {
@@ -4213,7 +4407,7 @@ const editorCommand = {
                 const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
                 const { projectSlug } = config;
                 if (!projectSlug) {
-                    errorLog('Missing project slug. Try reinitializing with: codeyam init --force');
+                    errorLog('Missing project slug. Try reinitializing with: `codeyam editor template`');
                     return;
                 }
                 const connectionOk = await withoutSpinner(() => testEnvironment());
@@ -4650,14 +4844,16 @@ const editorCommand = {
             case 13:
             case 14:
             case 15:
-            case 16: {
+            case 16:
+            case 17:
+            case 18: {
                 const feature = argv.feature || state?.feature;
                 if (!feature) {
                     console.error(chalk.red('Error: No feature in progress. Run codeyam editor 1 first.'));
                     process.exit(1);
                 }
-                // Hard gate: steps 8+ require audit to have passed
-                if (step >= 8) {
+                // Hard gate: steps 10+ require audit to have passed
+                if (step >= 10) {
                     const auditOk = await checkAuditGate();
                     if (!auditOk) {
                         // checkAuditGate() already printed specific failure details above
@@ -4681,6 +4877,8 @@ const editorCommand = {
                     14: printStep14,
                     15: printStep15,
                     16: printStep16,
+                    17: printStep17,
+                    18: printStep18,
                 };
                 stepFns[step](root, feature);
                 break;