@codeyam/codeyam-cli 0.1.0-staging.8778565 → 0.1.0-staging.8b51541

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

@@ -11,12 +11,12 @@ import { IS_INTERNAL_BUILD } from "../utils/buildFlags.js";
 import { startBackgroundServer } from "../utils/backgroundServer.js";
 import { installClaudeCodeSkills } from "../utils/install-skills.js";
 import { setupClaudeCodeSettings } from "../utils/setupClaudeCodeSettings.js";
-import { getAnalyzerTemplatePath, isAnalyzerFinalized, } from "../utils/analyzer.js";
+import { ensureAnalyzerFinalized, } from "../utils/analyzerFinalization.js";
 import { APP_FORMATS, TECH_STACKS } from "../data/techStacks.js";
 import { getProjectRoot as getStateProjectRoot } from "../state.js";
 import initCommand from "./init.js";
-import { readManifest, syncManifestToDatabase, } from "../utils/scenariosManifest.js";
-import { clearEditorState, clearEditorUserPrompt, } from "../utils/editorScenarios.js";
+import { scanScenarioFiles, syncScenarioFilesToDatabase, backfillScenarioMetadata, migrateScenarioFormats, } from "../utils/scenariosManifest.js";
+import { clearEditorState, clearEditorUserPrompt, validateStepTransition, } from "../utils/editorScenarios.js";
 import { validateSeedData, detectSeedAdapter, } from "../utils/editorSeedAdapter.js";
 import { buildEditorApiRequest, callEditorApi, EDITOR_API_SUBCOMMANDS, } from "../utils/editorApi.js";
 import { parseRegisterArg } from "../utils/parseRegisterArg.js";
@@ -36,6 +36,9 @@ const STEP_LABELS = {
     11: 'Journal',
     12: 'Review',
     13: 'Present',
+    14: 'Commit',
+    15: 'Finalize',
+    16: 'Push',
 };
 /**
  * Append a JSONL log entry to .codeyam/logs/editor-log.jsonl
@@ -56,6 +59,18 @@ function logEvent(root, event, data) {
         // Logging is best-effort
     }
 }
+/**
+ * Read the design system file if it exists.
+ */
+function readDesignSystem(root) {
+    const designSystemPath = path.join(root, '.codeyam', 'design-system.md');
+    try {
+        return fs.readFileSync(designSystemPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Get the project root (where .codeyam/ lives) or cwd.
  */
@@ -128,6 +143,39 @@ function getServerPort() {
     }
     return process.env.CODEYAM_PORT || '3111';
 }
+/**
+ * Read the project's default dimension name and available screen size names.
+ * Used by step instructions to show project-specific dimension examples
+ * instead of hardcoded "Desktop".
+ */
+function getProjectDimensions(root) {
+    try {
+        const configPath = path.join(root, '.codeyam', 'config.json');
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        const defaultName = config.defaultScreenSize?.name ||
+            (config.screenSizes ? Object.keys(config.screenSizes)[0] : null) ||
+            'Desktop';
+        const names = config.screenSizes ? Object.keys(config.screenSizes) : [];
+        return { defaultName, names };
+    }
+    catch {
+        return { defaultName: 'Desktop', names: [] };
+    }
+}
+/**
+ * Print dimension guidance when the project has multiple screen sizes.
+ * Tells Claude to pick the right dimension for the content being previewed
+ * instead of blindly using the default for everything.
+ */
+function printDimensionGuidance(defaultName, names) {
+    if (names.length <= 1)
+        return;
+    // Find a non-default dimension to suggest as the "other" option
+    const otherName = names.find((n) => n !== defaultName) || names[1];
+    console.log(chalk.yellow(`  IMPORTANT: Choose the dimension that matches what you're previewing. Available: ${names.map((n) => `"${n}"`).join(', ')}.`));
+    console.log(chalk.yellow(`  Do NOT always use "${defaultName}". Full pages, standalone views, and desktop layouts should use "${otherName}".`));
+    console.log(chalk.yellow(`  Think about the CONTENT — a full-page library view needs a large viewport, not a popup-sized one.`));
+}
 /**
  * Print a checklist item.
  * Inline backtick-wrapped text is highlighted in cyan for visibility.
@@ -149,13 +197,13 @@ function stepHeader(step, title, feature) {
     console.log();
 }
 /**
- * Print a colored progress tracker showing all 13 steps.
+ * Print a colored progress tracker showing all 16 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 <= 13; i++) {
+    console.log(chalk.dim('  ┌─────────────────────────────────────┐'));
+    for (let i = 1; i <= 16; i++) {
         const label = STEP_LABELS[i];
         const num = i < 10 ? ` ${i}` : `${i}`;
         const content = `${num}. ${label.padEnd(28)}`;
@@ -193,7 +241,7 @@ 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 < 13) {
+    if (current < 16) {
         console.log(chalk.green('When done, run: ') +
             chalk.bold(`codeyam editor ${current + 1}`));
     }
@@ -237,6 +285,14 @@ function printResumptionHeader(step) {
         ],
         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: [
+            '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: [
+            'Check if already pushed:\n      `git remote -v && git log --oneline origin/HEAD..HEAD 2>/dev/null`',
+        ],
     };
     const label = STEP_LABELS[step] || 'Unknown';
     console.log(chalk.bold.yellow(`━━━ RESUMING Step ${step}: ${label} ━━━`));
@@ -341,7 +397,7 @@ function parseDebugTargets(target) {
         }
         if (entry.startsWith('step-')) {
             const num = parseInt(entry.replace('step-', ''), 10);
-            if (!isNaN(num) && num >= 1 && num <= 13) {
+            if (!isNaN(num) && num >= 1 && num <= 16) {
                 valid.add(`step-${num}`);
                 continue;
             }
@@ -425,6 +481,15 @@ function printSetup(root) {
     console.log();
     console.log("No project detected. Let's get started.");
     console.log();
+    // ── Design System ────────────────────────────────────────────────
+    console.log(chalk.bold('Design System (ask FIRST):'));
+    console.log(chalk.dim('  Ask: "Do you have a design system, brand guidelines, or style preferences you\'d like me to follow?"'));
+    console.log(chalk.dim('  Use AskUserQuestion with these EXACT option labels:'));
+    console.log(chalk.yellow('    Option 1 label: "Yes, I\'ll paste my design system"'));
+    console.log(chalk.dim('       → Wait for paste, save to .codeyam/design-system.md, confirm with brief summary'));
+    console.log(chalk.yellow('    Option 2 label: "No, use sensible defaults"'));
+    console.log(chalk.dim('       → Skip'));
+    console.log();
     console.log(chalk.bold('Checklist:'));
     checkbox('Read `.codeyam/editor-mode-context.md` for session state');
     checkbox('Ask the user what they want to build');
@@ -479,7 +544,15 @@ function printSetup(root) {
     console.log();
     console.log(chalk.dim('  Pre-select based on app format: mobile-responsive-web-app/desktop-app → Desktop, mobile-app → Mobile, chrome-extension → Custom (400×600).'));
     console.log(chalk.dim('  If only one obvious choice, confirm it rather than asking.'));
-    console.log(chalk.dim('  Save the choice via: curl -s -X POST http://localhost:PORT/api/editor-project-info -H "Content-Type: application/json" -d \'{"defaultScreenSize":{"name":"Desktop","width":1440,"height":900}}\''));
+    console.log(chalk.dim(`  Save the choice via: curl -s -X POST http://localhost:${port}/api/editor-project-info -H "Content-Type: application/json" -d '{"defaultScreenSize":{"name":"Desktop","width":1440,"height":900}}'`));
+    console.log();
+    console.log(chalk.bold('Named Screen Sizes (for multi-resolution apps):'));
+    console.log(chalk.dim('  For mobile-responsive web apps or apps that need screenshots at multiple resolutions,'));
+    console.log(chalk.dim('  also save named screen sizes. Each scenario can reference a dimension name.'));
+    console.log(chalk.dim(`  curl -s -X POST http://localhost:${port}/api/editor-project-info -H "Content-Type: application/json" \\`));
+    console.log(chalk.dim('    -d \'{"screenSizes":{"Desktop":{"width":1440,"height":900},"Mobile":{"width":375,"height":667}}}\''));
+    console.log(chalk.dim('  If you discover a new viewport is needed mid-workflow, add it to screenSizes the same way and reference by name.'));
+    console.log(chalk.dim('  NOTE: This REPLACES all screenSizes — always include every named size, not just the new one.'));
     console.log();
     console.log(chalk.bold.red('━━━ STOP ━━━'));
     console.log();
@@ -514,7 +587,7 @@ function printCycleOverview(root, state) {
         console.log(chalk.yellow('This applies even after committing — always use the change workflow.'));
     }
     else {
-        console.log('Each feature follows 13 steps. You MUST run each command in order:');
+        console.log('Each feature follows 16 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`);
@@ -529,6 +602,9 @@ function printCycleOverview(root, state) {
         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();
         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"'));
@@ -543,19 +619,19 @@ function printStep1(root, feature, options, userPrompt) {
     if (!isResuming) {
         clearState(root);
     }
-    // If feature is provided, save initial state so step 2 can pick it up
-    if (feature) {
-        const now = new Date().toISOString();
-        writeState(root, {
-            feature,
-            step: 1,
-            label: STEP_LABELS[1],
-            startedAt: isResuming ? prevState.startedAt : now,
-            featureStartedAt: isResuming ? prevState.featureStartedAt : now,
-            appFormats: options?.appFormats || prevState?.appFormats,
-            techStackId: options?.techStackId || prevState?.techStackId,
-        });
-    }
+    // Always persist state so step 2's validation sees that step 1 ran.
+    // The feature name may not be known yet (it's an output of planning) —
+    // use an empty string as placeholder; step 2 requires --feature anyway.
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature: feature || prevState?.feature || '',
+        step: 1,
+        label: STEP_LABELS[1],
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: isResuming ? prevState.featureStartedAt : now,
+        appFormats: options?.appFormats || prevState?.appFormats,
+        techStackId: options?.techStackId || prevState?.techStackId,
+    });
     // Save the user's original prompt to a separate file
     if (userPrompt) {
         const promptPath = path.join(root, '.codeyam', 'editor-user-prompt.txt');
@@ -580,11 +656,21 @@ function printStep1(root, feature, options, userPrompt) {
     console.log(chalk.dim('    Bad:  Free-form text asking "What do you think about the data model?"'));
     console.log(chalk.dim('    You can ask up to 4 questions at once. Bundle related questions into a single AskUserQuestion call.'));
     checkbox("Summarize what you'll build in plain language the user can verify against their vision");
+    checkbox('Include a brief note on what interesting data states the scenarios should demonstrate');
+    console.log(chalk.dim('    Think: what seed data would put this feature through its paces? Diverse content, edge cases, empty vs rich.'));
     checkbox('Set the project title and description for the App tab:');
     console.log(chalk.dim(`  curl -s -X POST http://localhost:${port}/api/editor-project-info \\`));
     console.log(chalk.dim('    -H "Content-Type: application/json" \\'));
     console.log(chalk.dim('    -d \'{"projectTitle":"My App","projectDescription":"A short description of what this app does"}\''));
     console.log();
+    const designSystem = readDesignSystem(root);
+    if (designSystem) {
+        console.log(chalk.bold.magenta('Design System (from .codeyam/design-system.md):'));
+        console.log(chalk.dim('  Keep these design tokens in mind during planning.'));
+        console.log();
+        console.log(designSystem);
+        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: "This plan is accurate, let\'s prototype it!"') + chalk.dim(' — proceed to step 2'));
     console.log(chalk.yellow('    Option 2 label: "I\'d like some changes"') +
@@ -612,6 +698,7 @@ function printStep1(root, feature, options, userPrompt) {
 // ─── Step 2: Prototype ────────────────────────────────────────────────
 function printStep2(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const projectExists = hasProject(root);
     const prevState = readState(root);
     const isResuming = prevState?.step === 2;
@@ -649,7 +736,13 @@ function printStep2(root, feature) {
         console.log(chalk.dim(`  # After re-seeding, restart the dev server to pick up fresh data:`));
         console.log(chalk.dim(`  # codeyam editor dev-server '{"action":"restart"}'`));
         console.log();
-        console.log(chalk.dim('  See PRISMA_SETUP.md for Prisma patterns and important warnings.'));
+        console.log(chalk.yellow('  IMPORTANT: When adding new required columns to existing tables,'));
+        console.log(chalk.yellow('  provide a @default(...) value so `db push` can fill existing rows.'));
+        console.log(chalk.dim('  Example: userId String @default("anonymous")  — existing rows get "anonymous"'));
+        console.log(chalk.dim('  Without a default, Prisma requires --force-reset which drops ALL data.'));
+        console.log(chalk.dim('  NEVER use --force-reset — it is blocked in this environment.'));
+        console.log();
+        console.log(chalk.dim('  See DATABASE.md for Prisma patterns and important warnings.'));
         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();
@@ -673,14 +766,33 @@ function printStep2(root, feature) {
         console.log(chalk.dim('  Use Tailwind responsive prefixes (sm:, md:, lg:) for layout shifts.'));
         console.log(chalk.dim('  Test at both Desktop (1280×800) and Mobile (390×844) sizes before presenting.'));
     }
+    const designSystem = readDesignSystem(root);
+    if (designSystem) {
+        console.log();
+        console.log(chalk.bold.magenta('Design System (from .codeyam/design-system.md):'));
+        console.log();
+        console.log(designSystem);
+        console.log();
+        checkbox('Define ALL design tokens as CSS custom properties in globals.css — not just colors');
+        console.log(chalk.dim('    Colors: --bg-surface, --text-primary, --accent-green-a, etc.'));
+        console.log(chalk.dim('    Typography: --text-xs, --text-sm, --text-lg, --text-2xl (font-size values)'));
+        console.log(chalk.dim('    Font weights: --font-weight-normal, --font-weight-medium, --font-weight-semibold'));
+        console.log(chalk.dim('    Spacing: --spacing-xs, --spacing-sm, --spacing-md, --spacing-lg, etc.'));
+        console.log(chalk.dim('    Border radius, shadows, transitions — every value the design system defines.'));
+        checkbox('Reference tokens from components — ZERO hardcoded px values for font-size, spacing, or colors');
+        console.log(chalk.dim('    Bad:  fontSize: 14, padding: "12px 16px", gap: 8'));
+        console.log(chalk.dim('    Good: fontSize: "var(--text-sm)", padding: "var(--spacing-md) var(--spacing-lg)", gap: "var(--spacing-sm)"'));
+        console.log(chalk.dim('    This ensures the entire app updates when the design system changes.'));
+    }
     console.log();
     console.log(chalk.bold.cyan('Keep the preview moving:'));
     console.log(chalk.cyan('  The user is watching the preview. Refresh it after each meaningful change:'));
-    console.log(chalk.cyan(`  codeyam editor preview`));
+    console.log(chalk.cyan(`  codeyam editor preview '{"dimension":"${dim}"}'`));
     console.log(chalk.cyan('  Refresh after: first visible page, adding each UI section, seeding data, styling.'));
     console.log(chalk.cyan('  Aim for 4-8+ refreshes during prototyping — not one big reveal at the end.'));
     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"}'`));
+    console.log(chalk.cyan(`  codeyam editor preview '{"path":"/drinks/1","dimension":"${dim}"}'`));
+    printDimensionGuidance(dim, dimNames);
     console.log();
     console.log(chalk.bold('Verify the dev server:'));
     console.log(chalk.dim(`  # Get dev server URL: codeyam editor dev-server`));
@@ -701,12 +813,19 @@ function printStep2(root, feature) {
     console.log(chalk.dim('    The user is looking at the preview — a blank page means something is broken.'));
     console.log(chalk.dim('    If any check fails, fix the issue and re-verify before proceeding.'));
     console.log();
+    console.log(chalk.bold('Update README and setup script:'));
+    checkbox('Update `README.md`: set the project name, write a one-line description, and list any setup prerequisites');
+    checkbox('Update `npm run setup` in `package.json` if setup requires extra steps (e.g. env vars, external services)');
+    console.log(chalk.dim('    The README and setup script must stay accurate as you make changes.'));
+    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);
 }
 // ─── Step 3: Confirm ──────────────────────────────────────────────────
 function printStep3(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
     const isResuming = prevState?.step === 3;
     const now = new Date().toISOString();
@@ -725,7 +844,7 @@ function printStep3(root, feature) {
     console.log('Summarize what was built and get user confirmation.');
     console.log();
     console.log(chalk.bold('Before presenting — verify everything works:'));
-    checkbox(`Refresh the preview: \`codeyam editor preview\` — check the \`preview\` field for \`healthy: false\``);
+    checkbox(`Refresh the preview: \`codeyam editor preview '{"dimension":"${dim}"}'\` — check the \`preview\` field for \`healthy: false\``);
     checkbox('Verify API routes return valid data (curl each route)');
     console.log();
     console.log(chalk.bold.red('  Verify EVERY image loads (this is the #1 source of broken prototypes):'));
@@ -739,7 +858,8 @@ function printStep3(root, feature) {
     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"}\'`');
+    checkbox(`Navigate the preview to the feature's primary page: \`codeyam editor preview '{"path":"/your-page","dimension":"${dim}"}'\``);
+    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();
@@ -751,7 +871,7 @@ function printStep3(root, feature) {
     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.yellow('    Option 2 label: "I\'d like some changes"') +
-        chalk.dim(' — user describes changes, you make them, then re-present'));
+        chalk.dim(' — make changes, refresh preview, re-run `codeyam editor 3`'));
     console.log();
     console.log(chalk.dim('Wait for user approval before moving on. Refactoring and scenarios happen in later steps.'));
     stopGate(3, { confirm: true });
@@ -809,6 +929,7 @@ function printStep4(root, feature) {
 // ─── Step 5: Extract ──────────────────────────────────────────────────
 function printStep5(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
     const isResuming = prevState?.step === 5;
     const now = new Date().toISOString();
@@ -832,12 +953,13 @@ function printStep5(root, feature) {
     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();
-    console.log(chalk.bold('Library functions (TDD):'));
-    checkbox('For each function: write MULTIPLE failing tests FIRST, then extract to make them pass');
+    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');
     console.log(chalk.dim('    Cover: typical inputs, edge cases, empty/null inputs, error conditions'));
     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 — step 7 only captures component screenshots.'));
+    console.log(chalk.yellow('  Tests ARE the only coverage for library functions/hooks — step 7 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');
@@ -849,7 +971,8 @@ function printStep5(root, feature) {
     checkbox('Run all tests and verify they pass');
     checkbox('Page files contain ONLY imports + component composition — no raw HTML tags');
     checkbox('Every component renders ONE thing or composes sub-components — no multi-section JSX');
-    checkbox(`Refresh the preview after each batch of extractions: \`codeyam editor preview\``);
+    checkbox(`Refresh the preview after each batch of extractions: \`codeyam editor preview '{"dimension":"${dim}"}'\``);
+    printDimensionGuidance(dim, dimNames);
     console.log(chalk.dim('    The user should see the preview stay healthy as you refactor — refresh periodically, not just at the end.'));
     console.log(chalk.dim('Reuse glossary functions when they fit naturally. Extract a new function when the use case diverges.'));
     console.log();
@@ -879,7 +1002,8 @@ function printStep6(root, feature) {
     checkbox("Read `.codeyam/glossary.json` (create if it doesn't exist)");
     checkbox('Add an entry for each new function/component extracted in step 5');
     checkbox('Each entry should have: name, filePath, description, parameters, returnType, tags, feature');
-    checkbox('For each function with a test file from step 5, set `testFile` to the relative path');
+    checkbox('Every non-component entry MUST have `testFile` set — hooks and functions all need tests');
+    console.log(chalk.yellow('    If a function/hook has no test yet, go back and write one (TDD). The audit will block you.'));
     console.log();
     console.log(chalk.bold('Entry format:'));
     console.log(chalk.dim('  { "name": "calculateTotal", "filePath": "app/utils/pricing.ts",'));
@@ -895,6 +1019,7 @@ function printStep6(root, feature) {
 // ─── Step 7: Analyze ──────────────────────────────────────────────────
 function printStep7(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
     const isResuming = prevState?.step === 7;
     const now = new Date().toISOString();
@@ -946,12 +1071,20 @@ function printStep7(root, feature) {
     console.log(chalk.dim(`       codeyam editor register '{"name":"ComponentName - Scenario",`));
     console.log(chalk.dim(`         "componentName":"ComponentName","componentPath":"path/to/file.tsx",`));
     console.log(chalk.dim(`         "url":"/isolated-components/ComponentName?s=Scenario",`));
+    console.log(chalk.dim(`         "dimensions":["${dim}"],`));
     console.log(chalk.dim(`         "mockData":{"routes":{"/api/...":{"body":[...]}}}}'`));
-    console.log(chalk.dim('       Optional: add "viewportWidth" and "viewportHeight" to override the project default screen size'));
-    console.log(chalk.dim('       If omitted, captures use the project default from setup. Only override for scenarios that need a different size.'));
+    console.log(chalk.yellow('       ALWAYS include "dimensions" — use the named screen size that matches the component\'s context.'));
+    console.log(chalk.dim(dimNames.length > 0
+        ? `       Available dimensions: ${dimNames.map((n) => `"${n}"`).join(', ')}. Default: "${dim}".`
+        : `       Use "${dim}" for most components. Names must match a key in screenSizes from setup.`));
+    console.log(chalk.dim('       Names must match a key in screenSizes from setup. If you need a new size, add it first:'));
+    console.log(chalk.dim(`       curl -s -X POST http://localhost:${port}/api/editor-project-info -H "Content-Type: application/json" \\`));
+    console.log(chalk.dim(`         -d '{"screenSizes":{...existing..., "New Name":{"width":W,"height":H}}}'  (replaces all — include every size)`));
     console.log(chalk.dim('       url is a PATH (starts with /) — the proxy routes it and intercepts API calls'));
     console.log(chalk.dim('       mockData.routes provides data for API calls the component makes internally'));
     console.log(chalk.dim('       (omit mockData if the component has no internal API calls)'));
+    console.log(chalk.dim('       For large JSON: use your Write tool to create .codeyam/tmp/scenario.json,'));
+    console.log(chalk.dim('       then: codeyam editor register @.codeyam/tmp/scenario.json'));
     console.log(chalk.yellow('    5. IMPORTANT: Check the register response for `clientErrors` array'));
     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'));
@@ -965,17 +1098,16 @@ function printStep7(root, feature) {
     console.log();
     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 have tests');
+    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.dim('    When audit passes, the import graph is built automatically for change tracking.'));
     console.log();
-    console.log(chalk.bold('Build import graph (for change tracking):'));
-    checkbox('Run `codeyam editor analyze-imports`');
-    console.log(chalk.dim('    This populates the import graph so the system can detect impacted entities when code changes.'));
-    console.log(chalk.dim('    It must run AFTER the audit passes so the glossary and entity data are complete.'));
     stopGate(7);
 }
 // ─── Step 8: App Scenarios ────────────────────────────────────────────
 function printStep8(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
     const isResuming = prevState?.step === 8;
     const now = new Date().toISOString();
@@ -991,43 +1123,83 @@ function printStep8(root, feature) {
     if (isResuming) {
         printResumptionHeader(8);
     }
-    console.log('Create app-level scenarios representing different data states.');
+    console.log('Create app-level scenarios with rich data that robustly demonstrates this feature.');
+    console.log();
+    console.log(chalk.bold('Goal: Every scenario should thoroughly exercise the feature with realistic data.'));
+    console.log(chalk.dim('  Scenarios with minimal or generic data ("Test Item 1") won\'t reveal whether the feature works.'));
+    console.log(chalk.dim('  Use rich, diverse seed data that puts the feature through its paces.'));
+    console.log();
+    console.log(chalk.bold.cyan('Make seed data work hard:'));
+    console.log(chalk.cyan('  Every scenario — new or existing — should have data that EXERCISES the feature:'));
+    console.log(chalk.cyan('  • Add data that uses new fields, relationships, or states the feature introduces'));
+    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("  • 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:'));
+    console.log(chalk.cyan('  • New pages or pages with no scenarios yet → create new scenarios'));
+    console.log(chalk.cyan('  • Existing scenarios on affected pages → re-register with enhanced data'));
+    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('Checklist:'));
-    checkbox('Check existing scenarios: `codeyam editor scenarios`');
-    console.log(chalk.dim('    Review existing scenarios — reuse and update their data rather than'));
-    console.log(chalk.dim('    creating duplicates. Re-register with the same name to update a scenario.'));
-    checkbox('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'));
-    checkbox('Cover key data states for EVERY page/route (at least 2-3 scenarios per page)');
+    checkbox('Run `codeyam editor scenarios` — review all existing scenarios');
+    checkbox("Create new scenarios for any pages that don't have scenarios yet");
     console.log(chalk.yellow('    Each page needs its own scenarios — a detail page needs different data than the catalog'));
-    console.log(chalk.dim('    Catalog: "Full Catalog", "Empty Catalog", "Single Category"'));
-    console.log(chalk.dim('    Detail:  "Detail - With Reviews", "Detail - No Reviews", "Detail - High Rated"'));
-    console.log(chalk.dim('    Each scenario provides seed data to populate the database for that state'));
+    checkbox('Re-register every existing scenario whose page was affected by this feature');
+    console.log(chalk.dim('    Use the SAME name to update. Enhance seed data to showcase this feature where relevant.'));
+    console.log(chalk.yellow("    Don't just re-register unchanged data — enrich it so the feature is thoroughly demonstrated."));
+    checkbox('ALWAYS include "dimensions" — pick the viewport that best demonstrates the page');
+    console.log(chalk.yellow('    Every app scenario MUST have a "dimensions" field referencing a named screen size from setup.'));
+    console.log(chalk.dim(dimNames.length > 0
+        ? `    Available dimensions: ${dimNames.map((n) => `"${n}"`).join(', ')}. Default: "${dim}".`
+        : `    Use "${dim}" for most scenarios. Names must match a key in screenSizes from setup.`));
+    if (dimNames.length > 1) {
+        const otherDim = dimNames.find((n) => n !== dim) || dimNames[1];
+        console.log(chalk.yellow(`    Think about what fits each scenario: full pages/standalone views → "${otherDim}", popups/widgets → "${dim}".`));
+    }
+    console.log(chalk.dim('    For responsive apps, include multiple dimensions: "dimensions":["Desktop","Mobile"] captures both viewports.'));
+    console.log(chalk.dim('    If you need a new named size mid-workflow, add it via editor-project-info API (include ALL existing sizes — the API replaces, not merges).'));
     checkbox('If the project has a database + seed adapter, use seed-based scenarios:');
-    console.log(chalk.dim(`    codeyam editor register '{"name":"Full Catalog","type":"application","url":"/","seed":{"products":[...],"categories":[...]}}'`));
+    console.log(chalk.dim(`    codeyam editor register '{"name":"Full Catalog","type":"application","url":"/","dimensions":["${dim}"],"seed":{"products":[...],"categories":[...]}}'`));
     console.log(chalk.dim('    Seed data is written to the DB via the seed adapter. Real app renders real data.'));
-    checkbox('Optional: add "viewportWidth" and "viewportHeight" to override the project default screen size');
-    console.log(chalk.dim('    If omitted, captures use the project default from setup. Only override for scenarios that need a different size.'));
     checkbox('IMPORTANT: Always include "url" — the page path to screenshot for this scenario');
     console.log(chalk.dim('    Use "/" for home page, "/drinks/1" for detail pages, etc.'));
     console.log(chalk.dim('    Without url, the screenshot captures the root page regardless of the scenario.'));
     console.log(chalk.yellow('    Create separate scenarios for each page that shows different data.'));
-    checkbox('For large seed data, write JSON to a project temp file and use @ prefix:');
-    console.log(chalk.dim('    Write JSON to .codeyam/tmp/scenario.json then register with:'));
+    checkbox('For large seed data, use your Write tool to create .codeyam/tmp/scenario.json, then:');
     console.log(chalk.dim('    codeyam editor register @.codeyam/tmp/scenario.json'));
+    console.log(chalk.yellow('    IMPORTANT: Use the Write tool — NOT cat/heredoc — to avoid permission prompts'));
     checkbox('For external API mocks (Stripe, weather, etc.), add externalApis:');
     console.log(chalk.dim(`    "externalApis":{"GET https://api.stripe.com/v1/prices":{"body":[...],"status":200}}`));
     checkbox('If the app uses auth, email, or other patterns: see FEATURE_PATTERNS.md for scenario guidance');
-    checkbox('If no database, use component-style mock scenarios (unchanged):');
-    console.log(chalk.dim(`    codeyam editor register '{"name":"Empty","description":"...","url":"/","mockData":{"routes":{"/api/...":{"body":[...]}}}}'`));
+    checkbox('If the app uses localStorage/sessionStorage instead of a database, use localStorage scenarios:');
+    console.log(chalk.dim(`    codeyam editor register '{"name":"Full Library","type":"application","url":"/","dimensions":["${dim}"],"localStorage":{"articles":[...],"collections":[...]}}'`));
+    console.log(chalk.dim('    The proxy injects data into localStorage before the app loads. Fully interactive — the app can read and write normally.'));
+    console.log(chalk.dim('    For an empty state, register with an empty localStorage or omit it entirely.'));
+    checkbox('If no database and no localStorage, use component-style mock scenarios:');
+    console.log(chalk.dim(`    codeyam editor register '{"name":"Empty","description":"...","url":"/","dimensions":["${dim}"],"mockData":{"routes":{"/api/...":{"body":[...]}}}}'`));
     checkbox('After each 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'));
+    checkbox('CRITICAL: After EACH registration, view the captured screenshot to verify it');
+    console.log(chalk.yellow('    Read the screenshot file path from the registration response and view it.'));
+    console.log(chalk.yellow('    Does the screenshot actually SHOW the data you put in? If you seeded 5 articles'));
+    console.log(chalk.yellow('    but the screenshot shows an empty page, the scenario is broken — fix the code or data.'));
+    console.log(chalk.yellow('    Do NOT create scenarios with data the app cannot yet render.'));
     console.log();
     console.log(chalk.dim('Focus on creating and registering app-level scenarios. Code fixes happen in step 10 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?'));
+    console.log(chalk.cyan('  • A "Library with Articles" screenshot showing an empty page means the scenario is BROKEN.'));
+    console.log(chalk.cyan('  • Is the seed data diverse — different lengths, categories, counts — or just placeholders?'));
+    console.log(chalk.cyan('  • Only create scenarios for states the CURRENT code can render.'));
+    console.log();
+    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);
 }
 // ─── Step 9: User Scenarios ───────────────────────────────────────────
@@ -1048,34 +1220,37 @@ function printStep9(root, feature) {
     if (isResuming) {
         printResumptionHeader(9);
     }
-    console.log('Create per-persona scenarios if the app has users. Skip to step 10 if no users.');
+    console.log('Create per-persona variations of existing scenarios. Skip to step 10 if no users.');
     console.log();
-    console.log(chalk.bold('If the app has users:'));
-    checkbox('Check existing scenarios: `codeyam editor scenarios`');
-    console.log(chalk.dim('    Reuse existing persona scenarios — update data to reflect current changes.'));
-    console.log(chalk.dim('    Re-register with the same name to update. Only add new personas if needed.'));
-    checkbox('Ensure scenarios for each user persona (admin, regular user, new user)');
+    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();
+    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();
+    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)'));
+    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('If using seed-based scenarios, register with type "user" and baseScenario:');
-    console.log(chalk.dim(`    codeyam editor register '{"name":"Admin User","type":"user","url":"/","baseScenario":"<app-scenario-id>","seed":{"users":[{"id":1,"role":"admin"}]}}'`));
-    console.log(chalk.dim('    Always include "url" — the page to screenshot (e.g. "/", "/dashboard", "/drinks/1")'));
-    console.log(chalk.dim("    The base scenario's seed data is merged with this scenario's seed data (overlay wins)."));
-    checkbox('If the app uses auth or other patterns: see FEATURE_PATTERNS.md for per-persona scenario guidance');
-    checkbox('If using mock-based scenarios, register with mockData as before:');
-    console.log(chalk.dim(`    codeyam editor register '{"name":"...","description":"...","mockData":{"routes":{"/api/...":{"body":[...]}}}}'`));
+    checkbox('Include "dimensions" — inherit from the base app scenario, or override if the persona implies a different device');
+    console.log(chalk.dim('    e.g. a mobile-first user persona should use "dimensions":["Mobile"] even if the base scenario is Desktop.'));
     checkbox('After each 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'));
     console.log();
-    console.log(chalk.bold('If the app has NO users:'));
-    console.log(chalk.dim('  Skip this step and proceed to step 10 (Verify).'));
-    console.log();
-    console.log(chalk.dim('Focus on creating user-persona scenarios (or skip if no users). Code fixes happen in step 10 if needed.'));
+    console.log(chalk.dim('See FEATURE_PATTERNS.md and AUTH_PATTERNS.md for auth scenario guidance.'));
     stopGate(9);
 }
 // ─── Step 10: Verify ──────────────────────────────────────────────────
 function printStep10(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
     const isResuming = prevState?.step === 10;
     const now = new Date().toISOString();
@@ -1100,7 +1275,8 @@ function printStep10(root, feature) {
     console.log(chalk.dim(`    codeyam editor register '{"name":"ComponentName - Scenario",...}'`));
     console.log();
     console.log(chalk.bold('Editor scenarios (App tab) — visual + error check:'));
-    checkbox(`Refresh the preview: \`codeyam editor preview\``);
+    checkbox(`Refresh the preview: \`codeyam editor preview '{"dimension":"${dim}"}'\``);
+    printDimensionGuidance(dim, dimNames);
     checkbox('Click through each app-level and user-persona scenario in the preview');
     checkbox('For seed-based scenarios: verify data renders correctly after switching');
     console.log(chalk.dim('    Switch between scenarios and confirm the app reflects the seeded data each time'));
@@ -1153,6 +1329,7 @@ function printStep11(root, feature) {
 // ─── Step 12: Review ──────────────────────────────────────────────────
 function printStep12(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
     const isResuming = prevState?.step === 12;
     const now = new Date().toISOString();
@@ -1171,7 +1348,8 @@ function printStep12(root, feature) {
     console.log('Verify all screenshots and checks pass before presenting to the user.');
     console.log();
     console.log(chalk.bold('Checklist (do all of this silently):'));
-    checkbox(`Refresh the preview: \`codeyam editor preview\``);
+    checkbox(`Refresh the preview: \`codeyam editor preview '{"dimension":"${dim}"}'\``);
+    printDimensionGuidance(dim, dimNames);
     checkbox('Verify each component has screenshots in the App tab (grouped under Components)');
     checkbox('If any are missing, re-register them using `codeyam editor register`');
     checkbox(`Check for client errors: \`codeyam editor client-errors\``);
@@ -1185,6 +1363,7 @@ function printStep12(root, feature) {
 // ─── Step 13: Present ─────────────────────────────────────────────────
 function printStep13(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
     const isResuming = prevState?.step === 13;
     const now = new Date().toISOString();
@@ -1209,8 +1388,10 @@ function printStep13(root, feature) {
     console.log(chalk.dim('    Prefer scenarios with changeStatus "new" or "edited" (directly changed in this session).'));
     console.log(chalk.dim('    For app-level scenarios, prefer those showing the new/changed functionality.'));
     console.log(chalk.dim('    NEVER pick a scenario with changeStatus null — those are unchanged from a previous commit.'));
-    checkbox('Switch the preview to that scenario using its `id`:');
-    console.log(chalk.dim(`    codeyam editor preview '{"scenarioId":"<id>"}'`));
+    checkbox('Switch the preview to that scenario using its `id` and `dimension`:');
+    console.log(chalk.dim(`    codeyam editor preview '{"scenarioId":"<id>","dimension":"${dim}"}'`));
+    console.log(chalk.dim('    Use the dimension that matches the scenario — check its registered dimensions.'));
+    printDimensionGuidance(dim, dimNames);
     checkbox(`Show the results panel: \`codeyam editor show-results\``);
     console.log(chalk.dim('    This opens a visual panel below the terminal showing all scenarios with screenshots.'));
     console.log(chalk.dim('    The user can click scenarios to switch the live preview.'));
@@ -1224,17 +1405,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(`Hide the results panel first: \`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'));
-    checkbox(`Update journal with commit SHA: \`codeyam editor journal-update '{"time":"<journal entry time>","commitSha":"<sha>","commitMessage":"feat: <title>"}'\``);
-    console.log(chalk.green('  Then run: ') +
-        chalk.bold('codeyam editor steps') +
-        chalk.green(' 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.'));
+    checkbox('Advance to the commit step: `codeyam editor 14`');
     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\``);
@@ -1244,6 +1415,89 @@ function printStep13(root, feature) {
     console.log(chalk.red.bold('  IMPORTANT: Always run the change command BEFORE writing any code.'));
     stopGate(13, { confirm: true });
 }
+// ─── Step 14: Commit ─────────────────────────────────────────────────
+function printStep14(root, feature) {
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 14;
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature,
+        step: 14,
+        label: STEP_LABELS[14],
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
+    });
+    logEvent(root, 'step', { step: 14, label: 'Commit', feature });
+    stepHeader(14, 'Commit', feature);
+    if (isResuming) {
+        printResumptionHeader(14);
+    }
+    console.log('Commit all changes for this feature.');
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    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);
+}
+// ─── Step 15: Finalize ───────────────────────────────────────────────
+function printStep15(root, feature) {
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 15;
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature,
+        step: 15,
+        label: STEP_LABELS[15],
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
+    });
+    logEvent(root, 'step', { step: 15, label: 'Finalize', feature });
+    stepHeader(15, 'Finalize', feature);
+    if (isResuming) {
+        printResumptionHeader(15);
+    }
+    console.log('Update the journal with the commit SHA and amend the commit.');
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    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);
+}
+// ─── Step 16: Push ───────────────────────────────────────────────────
+function printStep16(root, feature) {
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 16;
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature,
+        step: 16,
+        label: STEP_LABELS[16],
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
+    });
+    logEvent(root, 'step', { step: 16, label: 'Push', feature });
+    stepHeader(16, 'Push', feature);
+    if (isResuming) {
+        printResumptionHeader(16);
+    }
+    console.log('Push the commit to the remote repository.');
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    checkbox('Check if a git remote is configured: `git remote -v`');
+    checkbox("Offer to push to remote (AskUserQuestion — STOP and wait for the user's answer before proceeding):");
+    console.log(chalk.dim('    If a remote exists, ask (AskUserQuestion): "Would you like me to push this commit to the remote?" with options "Yes, push" and "No, skip"'));
+    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 });
+}
 // ─── Command definition ───────────────────────────────────────────────
 // ─── Analyze-imports subcommand ────────────────────────────────────────
 /**
@@ -1252,11 +1506,15 @@ function printStep13(root, feature) {
  * Runs data-structure-only analysis for all glossary entities, then outputs
  * an import graph and entity data structures as JSON to stdout.
  */
-async function handleAnalyzeImports() {
+async function handleAnalyzeImports(options = {}) {
     const root = getProjectRoot();
     // Read glossary
     const glossaryPath = path.join(root, '.codeyam', 'glossary.json');
     if (!fs.existsSync(glossaryPath)) {
+        if (options.silent) {
+            // Internal caller — glossary doesn't exist yet, nothing to analyze
+            return;
+        }
         console.error(chalk.red('Error: .codeyam/glossary.json not found.'));
         console.error(chalk.dim('  Run codeyam editor 6 to create the glossary first.'));
         process.exit(1);
@@ -1274,15 +1532,24 @@ async function handleAnalyzeImports() {
         process.exit(1);
     }
     const filePaths = glossaryEntries.map((e) => e.filePath);
-    const entityNames = glossaryEntries.map((e) => e.name);
+    // Include page files so pages get analyzed as entities too.
+    // This allows the import graph to map page names to their dependencies.
+    const { scanPageFilePaths } = await import('../utils/entityChangeStatus.server.js');
+    const pageFilePaths = scanPageFilePaths(root);
+    for (const pageFile of Object.values(pageFilePaths)) {
+        if (!filePaths.includes(pageFile)) {
+            filePaths.push(pageFile);
+        }
+    }
     const progress = new ProgressReporter();
-    // Run data-structure-only analysis for all entities
-    progress.start('Running import analysis for all glossary entities...');
+    // 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...');
     try {
         await runAnalysisForEntities({
             projectRoot: root,
             filePaths,
-            entityNames,
             progress,
             onlyDataStructure: true,
         });
@@ -1300,7 +1567,9 @@ async function handleAnalyzeImports() {
     const entities = await loadEntities({});
     if (!entities || entities.length === 0) {
         progress.succeed('No entities found in database yet — skipping import analysis. This is normal on the first feature.');
-        console.log(JSON.stringify({ imports: {}, entities: {} }));
+        if (!options.silent) {
+            console.log(JSON.stringify({ imports: {}, entities: {} }));
+        }
         return;
     }
     // Deduplicate to latest versions
@@ -1315,7 +1584,7 @@ async function handleAnalyzeImports() {
             latestByKey.set(key, entity);
         }
     }
-    const entityNameSet = new Set(entityNames);
+    const entityNameSet = new Set(glossaryEntries.map((e) => e.name));
     const latestEntities = [...latestByKey.values()].filter((e) => entityNameSet.has(e.name));
     // Build import graph from importedExports metadata
     const imports = {};
@@ -1353,9 +1622,14 @@ async function handleAnalyzeImports() {
         };
     }
     progress.succeed('Done');
-    // Output combined JSON
-    const output = { imports, entities: entityData };
-    console.log(JSON.stringify(output, null, 2));
+    // Output combined JSON (suppressed when called internally during startup)
+    if (!options.silent) {
+        const summary = formatApiSubcommandResult('analyze-imports', {
+            imports,
+            entities: entityData,
+        });
+        console.log(summary || JSON.stringify({ imports, entities: entityData }));
+    }
 }
 // ─── Validate-seed subcommand ─────────────────────────────────────────
 /**
@@ -1538,6 +1812,17 @@ function formatApiSubcommandResult(subcommand, data) {
             }
             return parts.join(' ');
         }
+        case 'analyze-imports': {
+            const importEntries = Object.entries(data.imports || {});
+            const entityEntries = Object.entries(data.entities || {});
+            const parts = [];
+            parts.push(`entities=${entityEntries.length}`);
+            parts.push(`withImports=${importEntries.length}`);
+            if (importEntries.length > 0) {
+                parts.push(`imports: ${importEntries.map(([name, deps]) => `${name}→[${deps.join(',')}]`).join(' ')}`);
+            }
+            return parts.join(' ');
+        }
         default:
             return null; // journal-list, show/hide-results: keep full JSON
     }
@@ -1550,8 +1835,9 @@ function formatApiSubcommandResult(subcommand, data) {
  */
 async function handleRegister(jsonArg) {
     if (!jsonArg) {
+        const { defaultName: dim } = getProjectDimensions(getProjectRoot());
         console.error(chalk.red('Error: JSON argument required.'));
-        console.error(chalk.dim('  Usage: codeyam editor register \'{"name":"DrinkCard - Default","componentName":"DrinkCard","url":"/isolated-components/DrinkCard?s=Default"}\''));
+        console.error(chalk.dim(`  Usage: codeyam editor register '{"name":"DrinkCard - Default","componentName":"DrinkCard","url":"/isolated-components/DrinkCard?s=Default","dimensions":["${dim}"]}'`));
         console.error(chalk.dim('  For large payloads: codeyam editor register @/tmp/scenario.json'));
         process.exit(1);
     }
@@ -1563,55 +1849,74 @@ async function handleRegister(jsonArg) {
         }
         process.exit(1);
     }
-    const body = parsed.body;
+    // Normalize to array for uniform handling
+    const items = Array.isArray(parsed.body) ? parsed.body : [parsed.body];
     const port = getServerPort();
     const url = `http://localhost:${port}/api/editor-register-scenario`;
-    try {
-        const res = await fetch(url, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(body),
-        });
-        const data = await res.json();
-        // Print concise summary instead of raw JSON so Claude doesn't need python3
-        const parts = [];
-        parts.push(`success=${data.success}`);
-        if (data.scenario?.name)
-            parts.push(`name="${data.scenario.name}"`);
-        parts.push(`screenshot=${!!data.screenshotCaptured}`);
-        if (data.capturedViewport) {
-            parts.push(`viewport=${data.capturedViewport.width}×${data.capturedViewport.height}`);
-        }
-        if (data.clientErrors?.length > 0) {
-            parts.push(chalk.red(`errors=${data.clientErrors.length}`));
-        }
-        else {
-            parts.push(`errors=0`);
-        }
-        if (data.seedResult)
-            parts.push(`seed=${data.seedResult.success}`);
-        if (data.captureError)
-            parts.push(chalk.yellow(`captureError="${data.captureError}"`));
-        console.log(parts.join(' '));
-        // Surface client errors prominently so they can't be missed
-        if (data.clientErrors && data.clientErrors.length > 0) {
-            console.log(chalk.red.bold(`⚠ WARNING: ${data.clientErrors.length} client error${data.clientErrors.length !== 1 ? 's' : ''} detected during capture:`));
-            for (const err of data.clientErrors) {
-                console.log(chalk.red(`  → ${err}`));
+    const isBatch = items.length > 1;
+    let succeeded = 0;
+    let failed = 0;
+    for (let i = 0; i < items.length; i++) {
+        const body = items[i];
+        const prefix = isBatch ? chalk.dim(`[${i + 1}/${items.length}] `) : '';
+        try {
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+            });
+            const data = await res.json();
+            // Print concise summary instead of raw JSON so Claude doesn't need python3
+            const parts = [];
+            parts.push(`success=${data.success}`);
+            if (data.scenario?.name)
+                parts.push(`name="${data.scenario.name}"`);
+            parts.push(`screenshot=${!!data.screenshotCaptured}`);
+            if (data.capturedViewport) {
+                parts.push(`viewport=${data.capturedViewport.width}×${data.capturedViewport.height}`);
+            }
+            if (data.scenario?.dimension)
+                parts.push(`dimension="${data.scenario.dimension}"`);
+            if (data.clientErrors?.length > 0) {
+                parts.push(chalk.red(`errors=${data.clientErrors.length}`));
+            }
+            else {
+                parts.push(`errors=0`);
+            }
+            if (data.seedResult)
+                parts.push(`seed=${data.seedResult.success}`);
+            if (data.captureError)
+                parts.push(chalk.yellow(`captureError="${data.captureError}"`));
+            console.log(prefix + parts.join(' '));
+            // Surface client errors prominently so they can't be missed
+            if (data.clientErrors && data.clientErrors.length > 0) {
+                console.log(chalk.red.bold(`⚠ WARNING: ${data.clientErrors.length} client error${data.clientErrors.length !== 1 ? 's' : ''} detected during capture:`));
+                for (const err of data.clientErrors) {
+                    console.log(chalk.red(`  → ${err}`));
+                }
+                console.log(chalk.yellow('  The screenshot may show an error screen instead of the actual component.'));
+                console.log(chalk.yellow('  Fix the issue and re-register this scenario.'));
+            }
+            if (!res.ok) {
+                console.error(chalk.dim(JSON.stringify(data, null, 2)));
+                failed++;
+            }
+            else {
+                succeeded++;
             }
-            console.log(chalk.yellow('  The screenshot may show an error screen instead of the actual component.'));
-            console.log(chalk.yellow('  Fix the issue and re-register this scenario.'));
         }
-        if (!res.ok) {
-            console.error(chalk.dim(JSON.stringify(data, null, 2)));
-            process.exit(1);
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            console.error(prefix + chalk.red(`Error: Could not reach editor server at ${url}`));
+            console.error(chalk.dim(`  ${msg}`));
+            console.error(chalk.dim('  Is the editor running? Start it with: codeyam editor'));
+            failed++;
         }
     }
-    catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        console.error(chalk.red(`Error: Could not reach editor server at ${url}`));
-        console.error(chalk.dim(`  ${msg}`));
-        console.error(chalk.dim('  Is the editor running? Start it with: codeyam editor'));
+    if (isBatch) {
+        console.log(chalk.dim(`\nBatch complete: ${succeeded}/${items.length} succeeded`));
+    }
+    if (failed > 0) {
         process.exit(1);
     }
 }
@@ -1632,11 +1937,23 @@ async function handleDependents(entityName) {
     const progress = new ProgressReporter();
     progress.start('Loading entities from database...');
     await initializeEnvironment();
-    const allEntities = await loadEntities({});
+    let allEntities = await loadEntities({});
     if (!allEntities || allEntities.length === 0) {
-        progress.fail('No entities found in database');
-        console.error(chalk.dim('  Run codeyam editor analyze-imports first to populate entity data.'));
-        process.exit(1);
+        progress.succeed('No entities found — running analyze-imports first...');
+        try {
+            await handleAnalyzeImports({ silent: true });
+        }
+        catch {
+            console.error(chalk.red('Could not build import graph. Run `codeyam editor analyze-imports` manually.'));
+            process.exit(1);
+        }
+        // Reload entities after analysis
+        const reloaded = await loadEntities({});
+        if (!reloaded || reloaded.length === 0) {
+            progress.fail('No entities found even after analyze-imports');
+            process.exit(1);
+        }
+        allEntities = reloaded;
     }
     // Find the target entity by name (case-insensitive match)
     const targetEntities = allEntities.filter((e) => e.name.toLowerCase() === entityName.toLowerCase());
@@ -1723,15 +2040,16 @@ async function handleDependents(entityName) {
  * `codeyam editor change <feature>`
  *
  * Prints a condensed post-change checklist that guides Claude through
- * re-verifying after user-requested modifications. This is the "change
- * loop" — it replaces the freeform "make changes" path with structured
- * instructions that always loop back to step 13 present.
+ * re-verifying after user-requested modifications. When called from
+ * step 13+, this loops back to step 13 (present). When called from an
+ * earlier step, it returns to that step so the normal flow continues.
  */
 function handleChange(feature) {
     const root = getProjectRoot();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
+    const state = readState(root);
     if (!feature) {
         // Try to read feature from state
-        const state = readState(root);
         if (state?.feature) {
             feature = state.feature;
         }
@@ -1741,6 +2059,7 @@ function handleChange(feature) {
             process.exit(1);
         }
     }
+    const currentStep = state?.step ?? 13;
     const port = getServerPort();
     console.log();
     console.log(chalk.bold.cyan('━━━ Change Loop ━━━'));
@@ -1748,9 +2067,19 @@ function handleChange(feature) {
     console.log();
     console.log('The user has requested changes. Follow this checklist after making them.');
     console.log();
+    const designSystem = readDesignSystem(root);
+    if (designSystem) {
+        console.log(chalk.bold.magenta('Design System (active):'));
+        console.log(chalk.magenta('  Use existing CSS custom property tokens when making visual changes — no hardcoded px or hex values.'));
+        console.log(chalk.magenta('  Use var(--text-sm) not 14, var(--spacing-lg) not 16px, var(--text-primary) not #1A1B25.'));
+        console.log();
+        console.log(designSystem);
+        console.log();
+    }
     console.log(chalk.bold.cyan('Keep the preview moving:'));
     console.log(chalk.cyan(`  Refresh after EACH individual change — not after all changes are done:`));
-    console.log(chalk.cyan(`  codeyam editor preview`));
+    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();
     console.log(chalk.bold('0. Close the results panel:'));
@@ -1758,7 +2087,7 @@ function handleChange(feature) {
     console.log();
     console.log(chalk.bold('1. Re-register affected component scenarios:'));
     checkbox('For each component you modified, re-register ALL its scenarios');
-    console.log(chalk.dim(`    codeyam editor register '{"name":"ComponentName - ScenarioName","componentName":"ComponentName","componentPath":"app/components/ComponentName.tsx","url":"/isolated-components/ComponentName?s=ScenarioName"}'`));
+    console.log(chalk.dim(`    codeyam editor register '{"name":"ComponentName - ScenarioName","componentName":"ComponentName","componentPath":"app/components/ComponentName.tsx","url":"/isolated-components/ComponentName?s=ScenarioName","dimensions":["${dim}"]}'`));
     checkbox('For any NEW components: `codeyam editor isolate NewComponent` then create isolation routes and register scenarios');
     console.log();
     console.log(chalk.bold('2. Re-run affected tests:'));
@@ -1769,7 +2098,6 @@ function handleChange(feature) {
     console.log(chalk.dim(`    codeyam editor dev-server '{"action":"restart"}'`));
     console.log();
     console.log(chalk.bold('3. Re-capture app-level scenarios:'));
-    checkbox('Run `codeyam editor analyze-imports` to refresh the import graph after code changes');
     checkbox('For each changed component, run `codeyam editor dependents ComponentName` to find affected pages');
     checkbox('Run `codeyam editor scenarios` to list all existing scenarios');
     checkbox('For EACH page listed by dependents: find its existing scenarios in the list and re-register every one');
@@ -1777,15 +2105,22 @@ function handleChange(feature) {
     console.log(chalk.dim('    Re-register with the SAME name to update — do NOT create new/duplicate scenarios.'));
     console.log(chalk.dim('    Example: if Header changed and Home, Catalog, Detail pages use it,'));
     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.'));
+    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();
     console.log(chalk.bold('4. Verify completeness:'));
-    checkbox(`Refresh the preview: \`codeyam editor preview\``);
-    checkbox(`Navigate to key pages to verify changes: \`codeyam editor preview '{"path":"/your-route"}'\``);
+    checkbox(`Refresh the preview: \`codeyam editor preview '{"dimension":"${dim}"}'\``);
+    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('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.'));
     console.log(chalk.dim('    If `liveErrors>0`, there are JS errors in the preview — fix them.'));
     checkbox('Fix any errors, then re-register affected scenarios');
+    checkbox('If changes affect setup, new dependencies, or new scripts: update `README.md` and `npm run setup`');
     console.log();
     console.log(chalk.bold('5. Update the existing journal entry:'));
     checkbox('Get existing entry: `codeyam editor journal-list`');
@@ -1794,14 +2129,46 @@ 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();
-    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`));
-    console.log(chalk.red.bold('  The user ALWAYS expects to see results after changes. DO NOT skip this step.'));
-    console.log(chalk.red('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+    // 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) {
+        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: ') +
+            chalk.bold(`codeyam editor ${currentStep}`));
+        console.log(chalk.red('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+    }
+    else {
+        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`));
+        console.log(chalk.red.bold('  The user ALWAYS expects to see results after changes. DO NOT skip this step.'));
+        console.log(chalk.red('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+    }
     console.log();
 }
+// ─── Audit gate ─────────────────────────────────────────────────────
+/**
+ * Silently check whether the audit passes. Returns true if allPassing,
+ * false if any issues remain or the server is unreachable.
+ * Used as a hard gate before steps 8+.
+ */
+async function checkAuditGate() {
+    const port = getServerPort();
+    try {
+        const res = await fetch(`http://localhost:${port}/api/editor-audit`);
+        if (!res.ok)
+            return false;
+        const data = await res.json();
+        return data?.summary?.allPassing === true;
+    }
+    catch {
+        // Server not running or unreachable — can't verify, so don't block
+        return true;
+    }
+}
 // ─── Audit subcommand ────────────────────────────────────────────────
 /**
  * `codeyam editor audit`
@@ -1914,6 +2281,17 @@ async function handleAudit() {
     if (!allOk) {
         process.exit(1);
     }
+    // Auto-run analyze-imports when audit passes — this builds the import graph
+    // so the App tab can show component/function dependencies for each page.
+    // Previously this was a manual step that Claude had to remember to run.
+    console.log(chalk.dim('Building import graph...'));
+    try {
+        await handleAnalyzeImports({ silent: true });
+    }
+    catch {
+        // Non-fatal — audit passed, import graph is a bonus
+        console.log(chalk.yellow('Warning: Could not build import graph. Run `codeyam editor analyze-imports` manually.'));
+    }
 }
 // ─── Scenarios subcommand ─────────────────────────────────────────────
 async function handleScenarios() {
@@ -2001,6 +2379,77 @@ async function handleScenarios() {
     const total = scenarios.length;
     const groupCount = groups.size;
     console.log(chalk.dim(`${total} scenario${total !== 1 ? 's' : ''} across ${groupCount} component${groupCount !== 1 ? 's' : ''}`));
+    // Show screenshot paths so Claude can verify images with the Read tool
+    const withScreenshots = scenarios.filter((s) => s.screenshotPath);
+    if (withScreenshots.length > 0) {
+        console.log();
+        console.log(chalk.bold.cyan('Screenshots:'));
+        for (const s of withScreenshots) {
+            console.log(chalk.dim(`  ${s.name}: ${s.screenshotPath}`));
+        }
+    }
+    console.log();
+}
+// ─── Scenario Coverage subcommand ───────────────────────────────────
+async function handleScenarioCoverage() {
+    const port = getServerPort();
+    const url = `http://localhost:${port}/api/editor-scenario-coverage`;
+    let data;
+    try {
+        const res = await fetch(url);
+        if (!res.ok) {
+            console.error(chalk.red(`Error: Scenario coverage endpoint returned ${res.status}`));
+            process.exit(1);
+        }
+        data = await res.json();
+    }
+    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);
+    }
+    console.log();
+    console.log(chalk.bold.cyan('━━━ Scenario Coverage ━━━'));
+    console.log();
+    if (data.note) {
+        console.log(chalk.yellow(data.note));
+        console.log();
+        return;
+    }
+    // Fresh scenarios (already recaptured this feature)
+    if (data.freshScenarios.length > 0) {
+        console.log(chalk.green(`✓ ${data.freshScenarios.length} scenario(s) captured this feature:`));
+        for (const s of data.freshScenarios) {
+            console.log(chalk.dim(`    ${s.name} (${s.url || '/'})`));
+        }
+        console.log();
+    }
+    // Stale scenarios (need recapturing)
+    if (data.staleScenarios.length > 0) {
+        console.log(chalk.red(`✗ ${data.staleScenarios.length} scenario(s) need re-registering (stale screenshots):`));
+        for (const s of data.staleScenarios) {
+            console.log(chalk.yellow(`    ${s.name} (${s.url || '/'}) — ${s.changeStatus} but not recaptured`));
+        }
+        console.log();
+        console.log(chalk.yellow('Re-register each stale scenario with the SAME name to update its screenshot.'));
+        console.log(chalk.yellow("Enhance the seed data to reflect this feature's changes where relevant."));
+        console.log();
+    }
+    // Uncovered pages (changed but no scenarios at all)
+    if (data.uncoveredPages.length > 0) {
+        console.log(chalk.red(`✗ ${data.uncoveredPages.length} page(s) affected by changes with no scenarios:`));
+        for (const p of data.uncoveredPages) {
+            console.log(chalk.yellow(`    ${p.entityName} — ${p.changeStatus}`));
+        }
+        console.log();
+    }
+    // Summary
+    if (data.pass) {
+        console.log(chalk.green.bold('PASS — all affected scenarios are fresh'));
+    }
+    else {
+        console.log(chalk.red.bold('FAIL — re-register stale scenarios before proceeding'));
+    }
     console.log();
 }
 // ─── Template subcommand ─────────────────────────────────────────────
@@ -2090,6 +2539,9 @@ async function handleTemplate() {
             // Config parse error is non-fatal
         }
     }
+    // 5b. Write a fresh prototypeId so the proxy clears stale localStorage
+    const activeScenarioPath = path.join(root, '.codeyam', 'active-scenario.json');
+    fs.writeFileSync(activeScenarioPath, JSON.stringify({ prototypeId: Date.now().toString() }), 'utf-8');
     // 6. Trigger editor-refresh so the server picks up the new project
     console.log(chalk.bold('Refreshing editor...'));
     try {
@@ -2108,17 +2560,14 @@ async function handleTemplate() {
 // ─── Sync subcommand ─────────────────────────────────────────────────
 /**
  * `codeyam editor sync`
- * Import scenarios from scenarios-manifest.json into the local database.
+ * Import scenarios from editor-scenarios/ files into the local database.
+ * Falls back to legacy scenarios-manifest.json if no _metadata files found.
  */
 async function handleSync() {
     const root = getProjectRoot();
-    const manifest = readManifest(root);
-    if (!manifest) {
-        console.log(chalk.yellow('No scenarios-manifest.json found. Nothing to sync.'));
-        return;
-    }
-    if (manifest.scenarios.length === 0) {
-        console.log(chalk.dim('Manifest is empty. Nothing to sync.'));
+    const entries = scanScenarioFiles(root);
+    if (entries.length === 0) {
+        console.log(chalk.yellow('No scenario files with metadata found. Nothing to sync.'));
         return;
     }
     const configPath = path.join(root, '.codeyam', 'config.json');
@@ -2142,13 +2591,12 @@ async function handleSync() {
     const { project } = await requireBranchAndProject(projectSlug);
     const { getDatabase } = await import('../../../packages/database/index.js');
     const db = getDatabase();
-    // Fetch existing editor scenarios
     const existingRows = await db
         .selectFrom('editor_scenarios')
         .select(['id', 'updated_at'])
         .where('project_id', '=', project.id)
         .execute();
-    const result = await syncManifestToDatabase(root, project.id, existingRows, async (row) => {
+    const result = await syncScenarioFilesToDatabase(root, project.id, existingRows, async (row) => {
         await db
             .insertInto('editor_scenarios')
             .values(row)
@@ -2173,6 +2621,34 @@ async function handleSync() {
             parts.push(`${result.skipped} unchanged`);
         console.log(chalk.green(`Synced scenarios: ${parts.join(', ')}`));
     }
+    // Migrate legacy scenario formats after sync, then re-sync if anything was fixed
+    try {
+        const migrateResult = migrateScenarioFormats(root);
+        if (migrateResult.fixed > 0) {
+            console.log(chalk.green(`Migrated ${migrateResult.fixed} scenario file${migrateResult.fixed > 1 ? 's' : ''} to current format`));
+            // Re-sync so the DB reflects the corrected file metadata
+            const refreshedRows = await db
+                .selectFrom('editor_scenarios')
+                .select(['id', 'updated_at'])
+                .where('project_id', '=', project.id)
+                .execute();
+            await syncScenarioFilesToDatabase(root, project.id, refreshedRows, async (row) => {
+                await db
+                    .insertInto('editor_scenarios')
+                    .values(row)
+                    .execute();
+            }, async (id, row) => {
+                await db
+                    .updateTable('editor_scenarios')
+                    .set(row)
+                    .where('id', '=', id)
+                    .execute();
+            });
+        }
+    }
+    catch {
+        // Non-fatal
+    }
 }
 // ─── Verify Images subcommand ─────────────────────────────────────────
 async function handleVerifyImages(jsonArg) {
@@ -2305,8 +2781,11 @@ function handleEditorDebug(args) {
         11: printStep11,
         12: printStep12,
         13: printStep13,
+        14: printStep14,
+        15: printStep15,
+        16: printStep16,
     };
-    for (let step = 1; step <= 13; step++) {
+    for (let step = 1; step <= 16; step++) {
         const stepId = `step-${step}`;
         if (!wants(stepId))
             continue;
@@ -2385,8 +2864,8 @@ const editorCommand = {
     describe: 'Editor mode guided workflow',
     builder: (yargs) => {
         const stepDescription = IS_INTERNAL_BUILD
-            ? 'Step number (1-13) or subcommand (template, register, isolate, analyze-imports, dependents, audit, scenarios, change, sync, debug, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors)'
-            : 'Step number (1-13) or subcommand (template, register, isolate, analyze-imports, dependents, audit, scenarios, change, sync, 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, 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)';
         let builder = yargs
             .positional('step', {
             type: 'string',
@@ -2422,7 +2901,7 @@ const editorCommand = {
             builder = builder
                 .option('target', {
                 type: 'string',
-                describe: 'Debug target (setup, overview, overview-with-state, step-1..step-13, or comma-separated list)',
+                describe: 'Debug target (setup, overview, overview-with-state, step-1..step-16, or comma-separated list)',
             })
                 .option('resume', {
                 type: 'boolean',
@@ -2497,6 +2976,11 @@ const editorCommand = {
             await handleScenarios();
             return;
         }
+        // Subcommand: codeyam editor scenario-coverage
+        if (argv.step === 'scenario-coverage') {
+            await handleScenarioCoverage();
+            return;
+        }
         // Subcommand: codeyam editor change <feature>
         if (argv.step === 'change') {
             handleChange(argv.json || '');
@@ -2549,9 +3033,9 @@ const editorCommand = {
             }
             else {
                 const state = readState(root);
-                // Clear prompt file when feature is done (step 13) so the hook
+                // Clear prompt file when feature is done (step 16) so the hook
                 // can capture the next feature request from the user.
-                if (state?.step === 13) {
+                if (state?.step === 16) {
                     clearEditorUserPrompt(root);
                 }
                 printCycleOverview(root, state);
@@ -2559,8 +3043,8 @@ const editorCommand = {
             return;
         }
         const step = argv.step ? parseInt(argv.step, 10) : undefined;
-        if (step != null && (isNaN(step) || step < 1 || step > 13)) {
-            console.error(chalk.red(`Error: Invalid step "${argv.step}". Must be 1-13.`));
+        if (step != null && (isNaN(step) || step < 1 || step > 16)) {
+            console.error(chalk.red(`Error: Invalid step "${argv.step}". Must be 1-16.`));
             process.exit(1);
         }
         if (step == null) {
@@ -2593,9 +3077,42 @@ const editorCommand = {
                     return;
                 }
                 const { project, branch } = await requireBranchAndProject(projectSlug);
-                // Auto-sync scenarios from manifest if it exists
-                const manifestData = readManifest(projectRoot);
-                if (manifestData && manifestData.scenarios.length > 0) {
+                // Backfill _metadata into existing scenario files that predate the embedded metadata feature.
+                // This reads metadata from the DB and writes it into files that don't have _metadata yet.
+                try {
+                    const { getDatabase } = await import('../../../packages/database/index.js');
+                    const db = getDatabase();
+                    const dbScenarios = await db
+                        .selectFrom('editor_scenarios')
+                        .select([
+                        'id',
+                        'name',
+                        'description',
+                        'component_name',
+                        'component_path',
+                        'url',
+                        'type',
+                        'screenshot_path',
+                        'viewport_width',
+                        'viewport_height',
+                        'created_at',
+                        'updated_at',
+                    ])
+                        .where('project_id', '=', project.id)
+                        .execute();
+                    if (dbScenarios.length > 0) {
+                        const backfilled = backfillScenarioMetadata(projectRoot, dbScenarios);
+                        if (backfilled > 0) {
+                            console.log(chalk.green(`  Backfilled metadata into ${backfilled} scenario file${backfilled > 1 ? 's' : ''}`));
+                        }
+                    }
+                }
+                catch {
+                    // Non-fatal — backfill is best-effort
+                }
+                // Auto-sync scenario files (with _metadata) to database
+                const scenarioEntries = scanScenarioFiles(projectRoot);
+                if (scenarioEntries.length > 0) {
                     try {
                         const { getDatabase } = await import('../../../packages/database/index.js');
                         const db = getDatabase();
@@ -2604,7 +3121,7 @@ const editorCommand = {
                             .select(['id', 'updated_at'])
                             .where('project_id', '=', project.id)
                             .execute();
-                        const syncResult = await syncManifestToDatabase(projectRoot, project.id, existingRows, async (row) => {
+                        const syncResult = await syncScenarioFilesToDatabase(projectRoot, project.id, existingRows, async (row) => {
                             await db
                                 .insertInto('editor_scenarios')
                                 .values(row)
@@ -2622,13 +3139,50 @@ const editorCommand = {
                                 parts.push(`${syncResult.inserted} imported`);
                             if (syncResult.updated > 0)
                                 parts.push(`${syncResult.updated} updated`);
-                            console.log(chalk.green(`  Synced scenarios from manifest: ${parts.join(', ')}`));
+                            console.log(chalk.green(`  Synced scenarios from files: ${parts.join(', ')}`));
                         }
                     }
                     catch {
                         // Non-fatal — sync failure shouldn't block editor startup
                     }
                 }
+                // Migrate legacy scenario formats: resolve null viewports, populate
+                // dimensions arrays, and build screenshotPaths maps from single values.
+                // If files were fixed, re-sync to update the database with corrected values.
+                try {
+                    const migrateResult = migrateScenarioFormats(projectRoot);
+                    if (migrateResult.fixed > 0) {
+                        console.log(chalk.green(`  Migrated ${migrateResult.fixed} scenario file${migrateResult.fixed > 1 ? 's' : ''} to current format`));
+                        // Re-sync so the DB reflects the fixed file metadata
+                        try {
+                            const { getDatabase } = await import('../../../packages/database/index.js');
+                            const db = getDatabase();
+                            const rows = await db
+                                .selectFrom('editor_scenarios')
+                                .select(['id', 'updated_at'])
+                                .where('project_id', '=', project.id)
+                                .execute();
+                            await syncScenarioFilesToDatabase(projectRoot, project.id, rows, async (row) => {
+                                await db
+                                    .insertInto('editor_scenarios')
+                                    .values(row)
+                                    .execute();
+                            }, async (id, row) => {
+                                await db
+                                    .updateTable('editor_scenarios')
+                                    .set(row)
+                                    .where('id', '=', id)
+                                    .execute();
+                            });
+                        }
+                        catch {
+                            // Non-fatal — DB re-sync failure shouldn't block startup
+                        }
+                    }
+                }
+                catch {
+                    // Non-fatal — migration failure shouldn't block editor startup
+                }
                 // `codeyam editor` (no step) always implies editor mode.
                 // The empty-folder heuristic is no longer needed here — running this
                 // command IS the signal.  We still detect empty folders so that
@@ -2667,29 +3221,23 @@ const editorCommand = {
                     editorMode,
                 });
                 // Auto-finalize analyzer so codeyam analyze works
-                if (editorMode && !isAnalyzerFinalized()) {
-                    try {
-                        const { execSync } = await import('child_process');
-                        const templatePath = getAnalyzerTemplatePath();
-                        if (fs.existsSync(templatePath)) {
-                            console.log('  Setting up simulations (first time only)...');
-                            execSync('npm install --include=dev', {
-                                cwd: templatePath,
-                                stdio: 'pipe',
-                            });
-                            execSync('npx playwright install chromium', {
-                                cwd: templatePath,
-                                stdio: 'pipe',
-                            });
-                            execSync('npm run build', {
-                                cwd: templatePath,
-                                stdio: 'pipe',
-                            });
-                            fs.writeFileSync(path.join(templatePath, '.finalized'), new Date().toISOString());
+                if (editorMode) {
+                    const stepLabels = {
+                        'npm-install': 'Installing simulation dependencies...',
+                        'playwright-install': 'Installing browser (Chromium)...',
+                        build: 'Building simulation engine...',
+                    };
+                    const simProgress = new ProgressReporter();
+                    const finalization = ensureAnalyzerFinalized({
+                        onProgress: (step) => simProgress.start(stepLabels[step]),
+                    });
+                    if (finalization.errors.length > 0) {
+                        for (const err of finalization.errors) {
+                            simProgress.warn(`${stepLabels[err.step].replace('...', '')} failed: ${err.message}`);
                         }
                     }
-                    catch {
-                        // Non-fatal
+                    else if (finalization.needed) {
+                        simProgress.succeed('Simulation engine ready');
                     }
                 }
                 // Start background server (handles killing existing servers internally)
@@ -2700,6 +3248,19 @@ const editorCommand = {
                     project,
                     branch,
                 });
+                // Build import graph on first startup if glossary exists but no entities yet
+                const glossaryPath = path.join(projectRoot, '.codeyam', 'glossary.json');
+                if (fs.existsSync(glossaryPath)) {
+                    const entities = await loadEntities({});
+                    if (!entities || entities.length === 0) {
+                        try {
+                            await handleAnalyzeImports({ silent: true });
+                        }
+                        catch {
+                            // Non-fatal
+                        }
+                    }
+                }
                 console.log();
                 console.log(`  Dashboard: ${url}`);
                 console.log('  Run "codeyam --help" for all commands');
@@ -2727,6 +3288,18 @@ const editorCommand = {
             return;
         }
         const state = readState(root);
+        // Validate step transition — prevent skipping steps.
+        // Exception: step 2 with --feature is always allowed because step 1's
+        // instructions explicitly tell Claude to run `codeyam editor 2 --feature "..."`.
+        // 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);
+            if (stepError) {
+                console.error(chalk.red(`Error: ${stepError}`));
+                process.exit(1);
+            }
+        }
         switch (step) {
             case 1: {
                 const feature = argv.feature || undefined;
@@ -2758,12 +3331,24 @@ const editorCommand = {
             case 10:
             case 11:
             case 12:
-            case 13: {
+            case 13:
+            case 14:
+            case 15:
+            case 16: {
                 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) {
+                    const auditOk = await checkAuditGate();
+                    if (!auditOk) {
+                        console.error(chalk.red.bold('BLOCKED: The audit has not passed. Run `codeyam editor audit` and fix all issues before proceeding.'));
+                        console.error(chalk.yellow('Every function and hook must have a test file. Every component must have scenarios.'));
+                        process.exit(1);
+                    }
+                }
                 const stepFns = {
                     3: printStep3,
                     4: printStep4,
@@ -2776,6 +3361,9 @@ const editorCommand = {
                     11: printStep11,
                     12: printStep12,
                     13: printStep13,
+                    14: printStep14,
+                    15: printStep15,
+                    16: printStep16,
                 };
                 stepFns[step](root, feature);
                 break;