@codeyam/codeyam-cli 0.1.0-staging.2ea44f6 → 0.1.0-staging.30dc541

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

@@ -11,28 +11,51 @@ 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, validateStepTransition, backfillEntityShaOnScenarios, } from "../utils/editorScenarios.js";
+import { validateSeedData, detectSeedAdapter, validateSeedKeysAgainstPrisma, } from "../utils/editorSeedAdapter.js";
+import { deleteScenarioViaCli } from "../utils/editorDeleteScenario.js";
 import { buildEditorApiRequest, callEditorApi, EDITOR_API_SUBCOMMANDS, } from "../utils/editorApi.js";
+import { parseRegisterArg } from "../utils/parseRegisterArg.js";
+import { sanitizeGlossaryEntries } from "../utils/editorLoaderHelpers.js";
+import { readMigrationState, writeMigrationState, advanceToNextPage, completePage, getMigrationResumeInfo, } from "../utils/editorMigration.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const STEP_LABELS = {
     1: 'Plan',
-    2: 'Prototype',
-    3: 'Confirm',
-    4: 'Deconstruct',
-    5: 'Extract',
-    6: 'Glossary',
-    7: 'Analyze',
-    8: 'App Scenarios',
-    9: 'User Scenarios',
-    10: 'Verify',
-    11: 'Journal',
-    12: 'Review',
-    13: 'Present',
+    2: 'Prepare',
+    3: 'Prototype',
+    4: 'Verify Prototype',
+    5: 'Confirm',
+    6: 'Deconstruct',
+    7: 'Extract',
+    8: 'Glossary',
+    9: 'Analyze',
+    10: 'App Scenarios',
+    11: 'User Scenarios',
+    12: 'Verify',
+    13: 'Journal',
+    14: 'Review',
+    15: 'Present',
+    16: 'Commit',
+    17: 'Finalize',
+    18: 'Push',
+};
+const MIGRATION_STEP_LABELS = {
+    1: 'Survey',
+    2: 'App Scenarios',
+    3: 'Component Scenarios',
+    4: 'Preview',
+    5: 'Discuss',
+    6: 'Decompose',
+    7: 'Extract',
+    8: 'Recapture',
+    9: 'Journal',
+    10: 'Present',
 };
 /**
  * Append a JSONL log entry to .codeyam/logs/editor-log.jsonl
@@ -53,6 +76,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.
  */
@@ -89,8 +124,9 @@ function writeState(root, state) {
 }
 /**
  * Clear the editor state (for starting a new feature).
- * Does NOT clear the user prompt file — that's handled separately
- * via clearEditorUserPrompt when the previous feature commits.
+ * Does NOT clear the user prompt file — the prompt is cleared
+ * by the journal API after recording, and the hook captures
+ * a fresh prompt for the next feature on UserPromptSubmit.
  */
 function clearState(root) {
     clearEditorState(root);
@@ -102,11 +138,62 @@ function hasProject(root) {
     return fs.existsSync(path.join(root, 'package.json'));
 }
 /**
- * Get the CodeYam server port from env or default.
+ * Get the CodeYam server port.
+ * Reads from the server state file first (actual running port), then falls
+ * back to CODEYAM_PORT env var, then to the default 3111.
+ * This is critical when the server auto-selected a different port because
+ * the default was occupied by another project's server.
  */
 function getServerPort() {
+    try {
+        const root = getProjectRoot();
+        if (root) {
+            const statePath = path.join(root, '.codeyam', 'server.json');
+            if (fs.existsSync(statePath)) {
+                const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+                if (state.port)
+                    return String(state.port);
+            }
+        }
+    }
+    catch {
+        // Fall through to defaults
+    }
     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.
@@ -116,6 +203,157 @@ function checkbox(text) {
     const highlighted = text.replace(/`([^`]+)`/g, (_m, code) => chalk.cyan(code));
     console.log(`  ${chalk.dim('[ ]')} ${highlighted}`);
 }
+/**
+ * Shared app scenario registration instructions used by editor Step 8 and migration Steps 1/6.
+ * Prints seed-based scenarios, mock-based fallback, @ file prefix, externalApis, url requirement, and error checking.
+ */
+function printAppScenarioInstructions(pageName, route) {
+    const root = process.cwd();
+    const hasSeedAdapter = !!detectSeedAdapter(root);
+    checkbox('Check existing scenarios: `codeyam editor scenarios`');
+    console.log(chalk.dim('    Review existing scenarios — enhance their seed data to exercise new features.'));
+    console.log(chalk.dim('    A rich scenario that exercises 5 features is better than 5 thin scenarios with one feature each.'));
+    console.log(chalk.dim('    Rename scenarios if their data scope has grown beyond the original name.'));
+    console.log();
+    console.log(chalk.bold.yellow('App scenarios vs component scenarios — these are DIFFERENT:'));
+    console.log(chalk.yellow('  App scenarios:       show the FULL PAGE with seeded data at a real route (/, /library, etc.)'));
+    console.log(chalk.yellow('  Component scenarios: show ONE COMPONENT in isolation at /isolated-components/...'));
+    console.log(chalk.yellow('  This step is about APP scenarios. Do NOT set "componentName" — that makes it a component scenario.'));
+    console.log();
+    checkbox('Identify every page/route in the app and ensure each has app-level scenarios');
+    console.log(chalk.dim("    Check the app's router/entry points for all distinct pages"));
+    console.log(chalk.yellow('    Every page needs at least 2-3 app scenarios — not just the main page'));
+    if (pageName) {
+        console.log(chalk.dim(`    Example: "${pageName} - Full Data", "${pageName} - Empty State"`));
+    }
+    else {
+        console.log(chalk.dim('    Example: "Page - Full Data", "Page - Empty State", "Page - Error State"'));
+    }
+    console.log();
+    checkbox('Register each scenario with type "application", the real page URL, and pageFilePath:');
+    console.log(chalk.dim(`    codeyam editor register '{"name":"${pageName || 'Page'} - Full Data",`));
+    console.log(chalk.dim(`      "type":"application","url":"${route || '/'}","pageFilePath":"src/path/to/Page.tsx",...}'`));
+    console.log(chalk.yellow('    Required fields: "type":"application", "url" (real route), "pageFilePath" (source file)'));
+    console.log(chalk.yellow('    Do NOT include "componentName" — that would make it a component scenario'));
+    console.log();
+    if (hasSeedAdapter) {
+        checkbox(chalk.bold.red('REQUIRED: Every app scenario MUST include "seed" data — without it the page will be empty!'));
+        console.log(chalk.yellow('    A seed adapter exists — you MUST include "seed":{...} in every app scenario registration.'));
+        console.log(chalk.yellow('    An app scenario without seed data will render an empty page (no database rows = nothing to show).'));
+        console.log(chalk.dim('    "seed" maps table names to arrays of rows: "seed":{"user":[{"id":1,"name":"Alice"}],"article":[...]}'));
+        console.log(chalk.dim('    For external APIs: also add "externalApis":{"GET https://...":{"body":[...],"status":200}}'));
+    }
+    else {
+        checkbox('Include data in every app scenario — without it the page will be empty:');
+        console.log(chalk.dim('    Use "mockData":{"routes":{"/api/...":{"body":[...]}}} to mock API responses'));
+        console.log(chalk.dim('    For external APIs: add "externalApis":{"GET https://...":{"body":[...],"status":200}}'));
+    }
+    checkbox('For large seed/mock data, write JSON to a temp file and use @ prefix:');
+    console.log(chalk.dim('    Write JSON to .codeyam/tmp/scenario.json then register with:'));
+    console.log(chalk.dim('    codeyam editor register @.codeyam/tmp/scenario.json'));
+    checkbox('If the app uses auth, email, or other patterns: see FEATURE_PATTERNS.md for scenario guidance');
+    checkbox('After each registration, check the response for `clientErrors`');
+    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'));
+}
+/**
+ * Shared glossary instructions used by editor Step 6 and migration Step 8.
+ * Prints format, required fields, and example.
+ */
+function printGlossaryInstructions(feature) {
+    console.log(chalk.bold.yellow('IMPORTANT: glossary.json is a plain JSON array — NOT an object wrapper.'));
+    checkbox("Read `.codeyam/glossary.json` (create if it doesn't exist)");
+    checkbox('Add an entry for each new function/component extracted');
+    checkbox('Each entry should have: name, filePath, description, parameters, returnType, tags, feature');
+    checkbox('For each function with a test file, set `testFile` to the relative path');
+    console.log();
+    console.log(chalk.bold('File format:'));
+    console.log(chalk.dim('  ['));
+    console.log(chalk.dim('    { "name": "calculateTotal", "filePath": "app/utils/pricing.ts",'));
+    console.log(chalk.dim('      "description": "Calculates total price including tax and discounts",'));
+    console.log(chalk.dim('      "parameters": [{ "name": "items", "type": "CartItem[]" }],'));
+    console.log(chalk.dim('      "returnType": "number", "tags": ["pricing"],'));
+    console.log(chalk.dim('      "testFile": "app/utils/pricing.test.ts",'));
+    console.log(chalk.dim(`      "feature": "${feature || '...'}", "createdAt": "..." }`));
+    console.log(chalk.dim('  ]'));
+}
+/**
+ * Shared extraction plan instructions used by editor Step 4 and migration Step 6.
+ * Prints THE RULE, extractable categories, plan format requirements.
+ */
+function printExtractionPlanInstructions() {
+    console.log(chalk.bold.red('THE RULE: No direct JSX in page files.'));
+    console.log(chalk.yellow('  After extraction, a page/route file should import and compose components — nothing else.'));
+    console.log(chalk.yellow('  Every distinct visual section in the page is its own component.'));
+    console.log(chalk.yellow('  Every component that renders multiple distinct sections should be split into sub-components.'));
+    console.log(chalk.yellow('  If a component has N visually distinct parts, it should compose N sub-components.'));
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    checkbox('Read `.codeyam/glossary.json` — note reusable functions/components');
+    checkbox('Read EVERY file used by this page/feature');
+    console.log(chalk.yellow('    For EACH file, identify EVERY extractable piece:'));
+    console.log(chalk.yellow('    Components: headers, nav, loading states, empty states, error states,'));
+    console.log(chalk.yellow('      badges/pills, image containers, card sections, form fields, modals,'));
+    console.log(chalk.yellow('      titles, descriptions, rating displays, status indicators, buttons'));
+    console.log(chalk.yellow('    Functions: data transforms, calculations, formatting, validation,'));
+    console.log(chalk.yellow('      API response shaping, any logic that is not directly about rendering'));
+    console.log(chalk.yellow('    Hooks: data fetching, state management, side effects'));
+    console.log();
+    checkbox('Write a numbered extraction plan listing EVERYTHING you will extract');
+    console.log(chalk.yellow('    The end state: every page file is ONLY imports + component composition.'));
+    console.log(chalk.yellow('    No raw <div>, <span>, <h1>, <p>, <img>, or <ul> in page files.'));
+    console.log(chalk.yellow('    Every visual section in every component is itself a component.'));
+    console.log();
+    console.log(chalk.yellow('    For each item in the plan, note:'));
+    console.log(chalk.yellow('    — What it is (component, function, hook)'));
+    console.log(chalk.yellow('    — Where it currently lives (source file + approximate lines)'));
+    console.log(chalk.yellow('    — Where it will go (new file path)'));
+    console.log();
+    console.log(chalk.dim('Present the numbered plan, then proceed to step 7 to execute it.'));
+}
+/**
+ * Shared component capture instructions used by editor Step 7 and migration Steps 3/8.
+ * Prints the full isolation route setup, codeyam-capture wrapper, register command, and error checking.
+ */
+function printComponentCaptureInstructions() {
+    checkbox('Create isolation route dirs: `codeyam editor isolate ComponentA ComponentB ...`');
+    console.log(chalk.dim('    This creates app/codeyam-isolate/layout.tsx (with production notFound() guard) and'));
+    console.log(chalk.dim('    a directory per component. List ALL components that need isolation routes.'));
+    checkbox('For each visual component:');
+    console.log(chalk.dim('    1. Read the source AND find where it is used in the app to understand:'));
+    console.log(chalk.dim('       — Props/interface'));
+    console.log(chalk.dim('       — Container width in the real app (e.g. card in a 3-col grid → max-w-sm)'));
+    console.log(chalk.dim('    2. Plan multiple scenarios that exercise the component like tests:'));
+    console.log(chalk.dim('       — Default/happy path with typical data'));
+    console.log(chalk.dim('       — Edge cases: empty/missing data, long text, maximum items, zero counts'));
+    console.log(chalk.dim('       — Different visual states: loading, error, disabled, selected, hover'));
+    console.log(chalk.dim('       — Boundary values: single item vs many, min/max ratings, very long names'));
+    console.log(chalk.dim('    3. Create ONE isolation route per component with a scenarios map and ?s= query param:'));
+    console.log(chalk.dim('       Remix:   app/routes/codeyam-isolate.ComponentName.tsx → /codeyam-isolate/ComponentName'));
+    console.log(chalk.dim('       Next.js: app/codeyam-isolate/ComponentName/page.tsx → /codeyam-isolate/ComponentName'));
+    console.log(chalk.dim('       The route defines a `scenarios` object mapping scenario names to props,'));
+    console.log(chalk.dim('       reads `?s=ScenarioName` from the URL, and renders the component with those props.'));
+    console.log(chalk.dim('       Wrap the component in a capture container with id="codeyam-capture":'));
+    console.log(chalk.dim('       <div id="codeyam-capture" style={{ display:"inline-block" }}>'));
+    console.log(chalk.dim('         <div style={{ width:"100%", maxWidth:"..." }}> ← match the app\'s container width'));
+    console.log(chalk.dim('       e.g. card in a 3-col grid → maxWidth:"24rem", full-width component → omit maxWidth'));
+    console.log(chalk.dim('       The screenshot captures just this wrapper, so the component fills the image.'));
+    console.log(chalk.dim('       Center the wrapper on the page (flexbox center both axes) and set a page background'));
+    console.log(chalk.dim('       color that matches where the component normally appears (e.g. white for light UIs).'));
+    console.log(chalk.dim('    4. Wait 2 seconds for HMR, then register + capture each scenario:'));
+    console.log(chalk.dim(`       codeyam editor register '{"name":"ComponentName - Scenario",`));
+    console.log(chalk.dim(`         "componentName":"ComponentName","componentPath":"path/to/file.tsx",`));
+    console.log(chalk.dim(`         "url":"/codeyam-isolate/ComponentName?s=Scenario",`));
+    console.log(chalk.dim(`         "mockData":{"routes":{"/api/...":{"body":[...]}}}}'`));
+    console.log(chalk.yellow('       IMPORTANT: url MUST be an isolation route (/codeyam-isolate/... or /isolated-components/...).'));
+    console.log(chalk.yellow('       Do NOT use real page URLs (like /library) for component scenarios.'));
+    console.log(chalk.dim('       mockData.routes provides data for API calls the component makes internally'));
+    console.log(chalk.dim('       (omit mockData if the component has no internal API calls)'));
+    console.log(chalk.yellow('    5. IMPORTANT: Check the register response for `clientErrors` array'));
+    console.log(chalk.yellow('       If clientErrors is non-empty → fix the isolation route and re-register'));
+    console.log(chalk.yellow('       Fix client errors and re-register before moving on'));
+    console.log(chalk.dim('    Isolation routes are committed to git — the layout guard blocks them in production'));
+}
 /**
  * Print a section header.
  */
@@ -128,13 +366,13 @@ function stepHeader(step, title, feature) {
     console.log();
 }
 /**
- * Print a colored progress tracker showing all 13 steps.
+ * Print a colored progress tracker showing all 18 steps.
  * Steps before `current` are green ✓, `current` is bold cyan →, future steps are dim ○.
  */
 function printProgressTracker(current) {
     console.log();
-    console.log(chalk.dim('┌─────────────────────────────────────┐'));
-    for (let i = 1; i <= 13; i++) {
+    console.log(chalk.dim('  ┌─────────────────────────────────────┐'));
+    for (let i = 1; i <= 18; i++) {
         const label = STEP_LABELS[i];
         const num = i < 10 ? ` ${i}` : `${i}`;
         const content = `${num}. ${label.padEnd(28)}`;
@@ -172,13 +410,13 @@ function stopGate(current, opts) {
     console.log(chalk.yellow('For the CURRENT step (→), show each checklist item with ✓ (done) or ✗ (skipped + reason).'));
     console.log(chalk.yellow('If any items are ✗, explain why and ask if the user wants to address them.'));
     console.log();
-    if (current < 13) {
+    if (current < 18) {
         console.log(chalk.green('When done, run: ') +
             chalk.bold(`codeyam editor ${current + 1}`));
     }
     else {
         console.log(chalk.green('Feature complete! Run: ') +
-            chalk.bold('codeyam editor 1') +
+            chalk.bold('codeyam editor steps') +
             chalk.green(' to start the next feature'));
     }
     console.log();
@@ -194,28 +432,38 @@ function printResumptionHeader(step) {
             'Check if plan was already written to context file:\n      `cat .codeyam/editor-mode-context.md`',
         ],
         2: ['Check if project files already exist:\n      `ls package.json src/`'],
-        3: ['This is a confirmation step — just re-present to user'],
-        4: [
+        3: ['Re-check is safe — just re-run the step'],
+        4: ['Re-verify is safe to repeat — just re-run the checks'],
+        5: ['This is a confirmation step — just re-present to user'],
+        6: [
             'Check if extraction plan already exists in context file:\n      `cat .codeyam/editor-mode-context.md`',
         ],
-        5: [
+        7: [
             'Check if components/functions already extracted:\n      `ls src/components/ src/lib/`',
         ],
-        6: [
+        8: [
             'Check if glossary already populated:\n      `cat .codeyam/glossary.json`',
         ],
-        7: ['Check if isolation routes and registered scenarios already exist'],
-        8: ['Check existing scenarios:\n      `codeyam editor scenarios`'],
-        9: [
+        9: ['Check if isolation routes and registered scenarios already exist'],
+        10: ['Check existing scenarios:\n      `codeyam editor scenarios`'],
+        11: [
             'Check existing user-persona scenarios:\n      `codeyam editor scenarios`',
         ],
-        10: ['Re-verify is safe to repeat — just re-run the checks'],
-        11: [
+        12: ['Re-verify is safe to repeat — just re-run the checks'],
+        13: [
             'Check if a journal entry already exists for this feature:\n      `codeyam editor journal-list`',
             'If an entry exists, use PATCH to update it — do NOT create a new one',
         ],
-        12: ['Re-verify is safe to repeat — just re-run the checks'],
-        13: ['Check if commit already made:\n      `git log --oneline -3`'],
+        14: ['Re-verify is safe to repeat — just re-run the checks'],
+        15: ['Check if commit already made:\n      `git log --oneline -3`'],
+        16: ['Check if commit already made:\n      `git log --oneline -3`'],
+        17: [
+            'Check if journal was already updated with commit SHA:\n      `codeyam editor journal-list`',
+            'Check if commit was already amended:\n      `git log --oneline -3`',
+        ],
+        18: [
+            '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} ━━━`));
@@ -320,7 +568,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 <= 18) {
                 valid.add(`step-${num}`);
                 continue;
             }
@@ -404,17 +652,88 @@ 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');
     console.log();
+    // ── App Format Selection ───────────────────────────────────────────
+    console.log(chalk.bold('App Format Selection:'));
+    console.log(chalk.dim('  After the user describes their project, ask which app formats they want to target.'));
+    console.log(chalk.dim('  Use AskUserQuestion with CHECKBOXES (multiple selections allowed):'));
+    console.log();
+    for (const format of APP_FORMATS) {
+        console.log(chalk.yellow(`    [ ] ${format.label}`) +
+            chalk.dim(` — ${format.description}`));
+    }
+    console.log();
+    // ── Tech Stack Selection ───────────────────────────────────────────
+    console.log(chalk.bold('Tech Stack Selection:'));
+    console.log(chalk.dim('  Based on the selected formats, present ONLY the matching tech stacks.'));
+    console.log(chalk.dim('  A stack matches if ANY of the user\'s selected formats appears in its "Supports" list.'));
+    console.log(chalk.dim('  Show ALL matching stacks even if there is only one. Mark the recommended option.'));
+    console.log(chalk.dim('  Use AskUserQuestion to let the user pick one.'));
+    console.log();
+    console.log(chalk.bold('  Available Tech Stacks:'));
+    for (const stack of TECH_STACKS) {
+        const recommended = stack.recommended ? chalk.green(' (Recommended)') : '';
+        const formatLabels = stack.supportedFormats
+            .map((f) => APP_FORMATS.find((af) => af.id === f)?.label)
+            .join(', ');
+        console.log(chalk.bold.yellow(`    ${stack.name}`) +
+            recommended +
+            chalk.dim(` [id: ${stack.id}]`));
+        console.log(chalk.dim(`      ${stack.description}`));
+        console.log(chalk.dim('      Technologies:'));
+        for (const tech of stack.technologies) {
+            console.log(chalk.dim(`        - ${tech}`));
+        }
+        console.log(chalk.dim(`      Supports: ${formatLabels}`));
+        console.log();
+    }
+    console.log(chalk.dim('  If NO stacks match the selected formats, tell the user that support for that format is coming soon'));
+    console.log(chalk.dim('  and suggest they pick a supported format for now.'));
+    console.log();
+    // ── Default Screen Size Selection ──────────────────────────────────
+    console.log(chalk.bold('Default Screen Size:'));
+    console.log(chalk.dim('  After selecting a tech stack, ask the user to choose the default screen size for previews and captures.'));
+    console.log(chalk.dim('  Use AskUserQuestion with RADIO buttons (single selection):'));
+    console.log();
+    console.log(chalk.yellow('    ( ) Desktop') + chalk.dim(' — 1440 × 900'));
+    console.log(chalk.yellow('    ( ) Laptop') + chalk.dim(' — 1024 × 768'));
+    console.log(chalk.yellow('    ( ) Tablet') + chalk.dim(' — 768 × 1024'));
+    console.log(chalk.yellow('    ( ) Mobile') + chalk.dim(' — 375 × 667'));
+    console.log(chalk.yellow('    ( ) Custom') + chalk.dim(' — ask for width × height'));
+    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();
+    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();
-    console.log(chalk.red('Ask the user what they want to build, then run:'));
+    console.log(chalk.red('Ask the user what they want to build, then ask about app formats, then present tech stacks, then choose a default screen size. Then run:'));
     console.log();
     console.log(chalk.green('  ') +
-        chalk.bold('codeyam editor 1 --feature "Feature Name" --prompt "the user\'s original message"'));
+        chalk.bold('codeyam editor 1 --feature "Feature Name" --app-formats "FORMAT_IDS" --tech-stack "STACK_ID" --prompt "the user\'s original message"'));
     console.log(chalk.dim('  Replace "Feature Name" with a short title for what the user described.'));
+    console.log(chalk.dim('  Replace FORMAT_IDS with the comma-separated format IDs the user selected (e.g., "chrome-extension" or "mobile-responsive-web-app").'));
+    console.log(chalk.dim('  Replace STACK_ID with the tech stack id shown in [brackets] above (e.g., "nextjs-prisma-sqlite" or "chrome-extension-react").'));
     console.log(chalk.dim("  Pass --prompt with the user's exact original request so it appears in the journal."));
     console.log(chalk.dim('  Step 1 will guide you through planning and getting user confirmation before any code is written.'));
     console.log();
@@ -422,6 +741,42 @@ function printSetup(root) {
 // ─── Cycle overview (no args, has project) ────────────────────────────
 function printCycleOverview(root, state) {
     logEvent(root, 'overview', state ? { feature: state.feature, step: state.step } : {});
+    // Detect active migration (uses both editor-step.json and migration-state.json)
+    const migState = readMigrationState(root);
+    const resumeInfo = getMigrationResumeInfo(state
+        ? { step: state.step, label: state.label, migration: state.migration }
+        : null, migState);
+    if (resumeInfo.mode === 'survey') {
+        console.log();
+        console.log(chalk.bold.cyan('━━━ Editor Mode: Project Migration ━━━'));
+        console.log();
+        console.log(chalk.yellow('Migration survey in progress — Claude needs to explore the project.'));
+        console.log();
+        console.log(chalk.green('Continue with: ') + chalk.bold(resumeInfo.resumeCommand));
+        console.log();
+        return;
+    }
+    if (resumeInfo.mode === 'page-in-progress') {
+        console.log();
+        console.log(chalk.bold.cyan('━━━ Editor Mode: Project Migration ━━━'));
+        console.log();
+        console.log(chalk.yellow(`Migration: Page ${resumeInfo.pageIndex + 1}/${resumeInfo.totalPages} (${resumeInfo.pageName})` +
+            (resumeInfo.step
+                ? `, Step ${resumeInfo.step} (${resumeInfo.stepLabel})`
+                : '')));
+        console.log();
+        console.log(chalk.green('Continue with: ') + chalk.bold(resumeInfo.resumeCommand));
+        console.log();
+        return;
+    }
+    if (resumeInfo.mode === 'complete') {
+        console.log();
+        console.log(chalk.bold.cyan('━━━ Editor Mode: Feature Cycle ━━━'));
+        console.log();
+        console.log(chalk.green('Migration complete! Start building features:'));
+        console.log();
+        // Fall through to normal cycle display
+    }
     console.log();
     console.log(chalk.bold.cyan('━━━ Editor Mode: Feature Cycle ━━━'));
     console.log();
@@ -433,47 +788,60 @@ function printCycleOverview(root, state) {
         console.log(chalk.dim('Or run ') +
             chalk.bold('codeyam editor 1') +
             chalk.dim(' to start a new feature'));
+        console.log();
+        console.log(chalk.yellow('If the user reports a bug or requests any change, run: ') +
+            chalk.bold('codeyam editor change'));
+        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 18 steps. You MUST run each command in order:');
         console.log();
-        console.log(`  ${chalk.bold.yellow(' 1')} ${chalk.bold('Plan')}            — Plan the feature, confirm with user`);
-        console.log(`  ${chalk.bold.yellow(' 2')} ${chalk.bold('Prototype')}       — Build a working prototype fast`);
-        console.log(`  ${chalk.bold.yellow(' 3')} ${chalk.bold('Confirm')}         — Confirm prototype with user`);
-        console.log(`  ${chalk.bold.yellow(' 4')} ${chalk.bold('Deconstruct')}     — Read code, plan all extractions`);
-        console.log(`  ${chalk.bold.yellow(' 5')} ${chalk.bold('Extract')}         — TDD extraction of functions + components`);
-        console.log(`  ${chalk.bold.yellow(' 6')} ${chalk.bold('Glossary')}        — Record functions in glossary`);
-        console.log(`  ${chalk.bold.yellow(' 7')} ${chalk.bold('Analyze')}         — Analyze and verify components`);
-        console.log(`  ${chalk.bold.yellow(' 8')} ${chalk.bold('App Scenarios')}   — Create app-level scenarios`);
-        console.log(`  ${chalk.bold.yellow(' 9')} ${chalk.bold('User Scenarios')}  — Create user-persona scenarios`);
-        console.log(`  ${chalk.bold.yellow('10')} ${chalk.bold('Verify')}          — Review screenshots, check for errors`);
-        console.log(`  ${chalk.bold.yellow('11')} ${chalk.bold('Journal')}         — Create/update journal entry`);
-        console.log(`  ${chalk.bold.yellow('12')} ${chalk.bold('Review')}          — Verify screenshots and audit`);
-        console.log(`  ${chalk.bold.yellow('13')} ${chalk.bold('Present')}         — Present summary, get approval`);
+        console.log(`  ${chalk.bold.yellow(' 1')} ${chalk.bold('Plan')}               — Plan the feature, confirm with user`);
+        console.log(`  ${chalk.bold.yellow(' 2')} ${chalk.bold('Prepare')}            — Set up project and dependencies`);
+        console.log(`  ${chalk.bold.yellow(' 3')} ${chalk.bold('Prototype')}          — Build a working prototype fast`);
+        console.log(`  ${chalk.bold.yellow(' 4')} ${chalk.bold('Verify Prototype')}   — Verify prototype works correctly`);
+        console.log(`  ${chalk.bold.yellow(' 5')} ${chalk.bold('Confirm')}            — Confirm prototype with user`);
+        console.log(`  ${chalk.bold.yellow(' 6')} ${chalk.bold('Deconstruct')}        — Read code, plan all extractions`);
+        console.log(`  ${chalk.bold.yellow(' 7')} ${chalk.bold('Extract')}            — TDD extraction of functions + components`);
+        console.log(`  ${chalk.bold.yellow(' 8')} ${chalk.bold('Glossary')}           — Record functions in glossary`);
+        console.log(`  ${chalk.bold.yellow(' 9')} ${chalk.bold('Analyze')}            — Analyze and verify components`);
+        console.log(`  ${chalk.bold.yellow('10')} ${chalk.bold('App Scenarios')}      — Create app-level scenarios`);
+        console.log(`  ${chalk.bold.yellow('11')} ${chalk.bold('User Scenarios')}     — Create user-persona scenarios`);
+        console.log(`  ${chalk.bold.yellow('12')} ${chalk.bold('Verify')}             — Review screenshots, check for errors`);
+        console.log(`  ${chalk.bold.yellow('13')} ${chalk.bold('Journal')}            — Create/update journal entry`);
+        console.log(`  ${chalk.bold.yellow('14')} ${chalk.bold('Review')}             — Verify screenshots and audit`);
+        console.log(`  ${chalk.bold.yellow('15')} ${chalk.bold('Present')}            — Present summary, get approval`);
+        console.log(`  ${chalk.bold.yellow('16')} ${chalk.bold('Commit')}             — Commit all changes`);
+        console.log(`  ${chalk.bold.yellow('17')} ${chalk.bold('Finalize')}           — Journal update + amend commit`);
+        console.log(`  ${chalk.bold.yellow('18')} ${chalk.bold('Push')}               — Push to remote`);
         console.log();
         console.log(chalk.green('Start now: ') + chalk.bold('codeyam editor 1'));
         console.log(chalk.dim('  If the user already described what they want, pass it: codeyam editor 1 --prompt "their message"'));
     }
+    console.log(chalk.dim('If stuck on CLI commands, scenarios, or debugging, read: .codeyam/docs/editor-reference.md'));
     console.log();
 }
 // ─── Step 1: Plan ─────────────────────────────────────────────────────
-function printStep1(root, feature, userPrompt) {
+function printStep1(root, feature, options, userPrompt) {
+    const port = getServerPort();
     const prevState = readState(root);
     const isResuming = prevState?.step === 1;
     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,
-        });
-    }
+    // 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');
@@ -498,11 +866,24 @@ function printStep1(root, feature, 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();
-    console.log(chalk.bold('Present a selection menu to the user (use AskUserQuestion):'));
-    console.log(chalk.green('    "Looks good, start building!"') +
-        chalk.dim(' — proceed to step 2'));
-    console.log(chalk.yellow('    "I\'d like some changes"') +
+    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"') +
         chalk.dim(' — user describes changes, you revise the plan, then re-present'));
     console.log();
     console.log(chalk.dim('This step is for understanding user goals and getting buy-in. Code comes in Step 2.'));
@@ -524,9 +905,10 @@ function printStep1(root, feature, userPrompt) {
     console.log(chalk.dim('  Replace "Feature Name" with a short title for what you just described.'));
     console.log();
 }
-// ─── Step 2: Prototype ────────────────────────────────────────────────
+// ─── Step 2: Prepare ──────────────────────────────────────────────────
 function printStep2(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const projectExists = hasProject(root);
     const prevState = readState(root);
     const isResuming = prevState?.step === 2;
@@ -537,13 +919,22 @@ function printStep2(root, feature) {
         label: STEP_LABELS[2],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: isResuming ? prevState.featureStartedAt : now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
-    logEvent(root, 'step', { step: 2, label: 'Prototype', feature });
-    stepHeader(2, 'Prototype', feature);
+    logEvent(root, 'step', { step: 2, label: 'Prepare', feature });
+    stepHeader(2, 'Prepare', feature);
     if (isResuming) {
         printResumptionHeader(2);
     }
-    console.log('Build fast with real data. Prioritize speed over quality.');
+    console.log(chalk.bold.red('━━━ MANDATORY: CREATE TASK NOW ━━━'));
+    console.log();
+    console.log(chalk.red(`Run TaskCreate with title: "Use \`codeyam editor\` to work on ${feature}"`));
+    console.log(chalk.red('DO NOT read files, scaffold, write code, or do ANYTHING else until this task exists.'));
+    console.log(chalk.red('This is not optional. Create the task, then continue below.'));
+    console.log(chalk.bold.red('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+    console.log();
+    console.log('Get the project ready to build.');
     console.log();
     // If no project exists yet, include scaffolding instructions first
     if (!projectExists) {
@@ -562,26 +953,126 @@ 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();
-        console.log(chalk.bold('Build the feature:'));
     }
+    else {
+        console.log(chalk.bold('Prepare the database for this feature:'));
+        checkbox('List existing scenarios: `codeyam editor scenarios`');
+        console.log(chalk.dim('    Review existing scenarios to find seed data that best demonstrates the feature.'));
+        console.log(chalk.dim("    Don't create throwaway seed data — use what's already been curated."));
+        checkbox('Pick the scenario with seed data most relevant to this feature');
+        console.log(chalk.dim("    Think: which existing data state best exercises the feature you're building?"));
+        console.log(chalk.dim('    A scenario with diverse, realistic data is usually the best starting point.'));
+        checkbox('Load that scenario to seed the database and preview it:');
+        console.log(chalk.dim(`    codeyam editor preview '{"scenarioId":"<id>","dimension":"${dim}"}'`));
+        console.log(chalk.dim('    This switches the active scenario, runs the seed adapter, and refreshes the preview.'));
+        console.log(chalk.dim('    If no existing scenario fits, use the default seed: npm run db:seed'));
+        console.log();
+    }
+    stopGate(2);
+}
+// ─── Step 3: Prototype ────────────────────────────────────────────────
+function printStep3(root, feature) {
+    const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
+    const projectExists = hasProject(root);
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 3;
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature,
+        step: 3,
+        label: STEP_LABELS[3],
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
+    });
+    logEvent(root, 'step', { step: 3, label: 'Prototype', feature });
+    stepHeader(3, 'Prototype', feature);
+    if (isResuming) {
+        printResumptionHeader(3);
+    }
+    console.log('Build fast with real data. Prioritize speed over quality.');
+    console.log();
     console.log(chalk.bold('Checklist:'));
     checkbox('Create API routes that read from the database via Prisma');
-    checkbox('Seed the database with demo data');
-    checkbox('All data fetching in pages/components MUST go through fetch() or http.request()');
-    console.log(chalk.dim('    CodeYam intercepts all HTTP traffic (fetch, http.request) to serve scenario mock data.'));
-    console.log(chalk.dim('    Direct database calls (Prisma, SQL, etc.) from server components CANNOT be intercepted.'));
-    console.log(chalk.dim("    Use API routes for data access: pages call fetch('/api/...'), API routes call Prisma."));
+    if (!projectExists) {
+        checkbox('Seed the database with demo data');
+        checkbox('Create `.codeyam/seed-adapter.ts` so CodeYam can seed the database for scenarios');
+        console.log(chalk.dim('    The seed adapter reads a JSON file (path passed as CLI arg), wipes tables, inserts rows.'));
+        console.log(chalk.dim("    Use the project's own ORM (Prisma, Drizzle, etc.). See template for example."));
+        console.log(chalk.dim('    Run with: npx tsx .codeyam/seed-adapter.ts <path-to-seed-data.json>'));
+    }
     checkbox('Verify the dev server shows the changes');
+    checkbox('If the feature involves auth, email, payments, or other common patterns: read FEATURE_PATTERNS.md');
+    // Responsive design guidance when building a mobile-responsive web app
+    if (prevState?.appFormats?.includes('mobile-responsive-web-app')) {
+        console.log();
+        console.log(chalk.bold.magenta('Responsive Design (mobile-responsive-web-app):'));
+        console.log(chalk.magenta('  This app must look great on BOTH desktop AND mobile. It is NOT a mobile-only app.'));
+        console.log(chalk.magenta('  Design desktop-first with a full-width layout, then ensure it adapts gracefully to mobile.'));
+        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","dimension":"${dim}"}'`));
+    printDimensionGuidance(dim, dimNames);
+    console.log();
+    stopGate(3);
+}
+// ─── Step 4: Verify Prototype ─────────────────────────────────────────
+function printStep4(root, feature) {
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 4;
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature,
+        step: 4,
+        label: STEP_LABELS[4],
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
+    });
+    logEvent(root, 'step', { step: 4, label: 'Verify Prototype', feature });
+    stepHeader(4, 'Verify Prototype', feature);
+    if (isResuming) {
+        printResumptionHeader(4);
+    }
+    console.log('Verify everything works before presenting the prototype.');
     console.log();
     console.log(chalk.bold('Verify the dev server:'));
     console.log(chalk.dim(`  # Get dev server URL: codeyam editor dev-server`));
@@ -592,139 +1083,141 @@ function printStep2(root, feature) {
     console.log(chalk.yellow('  Verify everything works before presenting the prototype to the user.'));
     checkbox('Verify the page loads: curl the dev server URL and confirm HTTP 200 (not an error page)');
     checkbox('Verify API routes return valid JSON: curl each route and confirm no error responses');
-    checkbox('Check for broken images: extract <img> src URLs from the HTML, then `curl -s -o /dev/null -w "%{http_code}" <url>` each one and confirm HTTP 200');
-    console.log(chalk.dim('    Unsplash and CDN URLs frequently 404 — verify EVERY image, not just a sample.'));
+    checkbox('Check for broken images: `codeyam editor verify-images \'{"paths":["/"], "imageUrls":["url1","url2"]}\'`');
+    console.log(chalk.dim('    Pass ALL page paths and ALL image URLs you used in seed data / API responses.'));
+    console.log(chalk.dim('    Client-rendered pages need imageUrls — the HTML shell has no images to scan.'));
     console.log(chalk.dim('    Fix or replace any broken image URLs in the seed data before proceeding.'));
     checkbox('Check the dev server terminal output for runtime errors (missing modules, failed imports)');
+    checkbox('Verify the live preview renders: `codeyam editor client-errors`');
+    console.log(chalk.dim('    If `hasContent=false` or `liveErrors>0`, the preview is broken — fix the issue before proceeding.'));
+    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);
+    stopGate(4);
 }
-// ─── Step 3: Confirm ──────────────────────────────────────────────────
-function printStep3(root, feature) {
+// ─── Step 5: Confirm ──────────────────────────────────────────────────
+function printStep5(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
-    const isResuming = prevState?.step === 3;
+    const isResuming = prevState?.step === 5;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 3,
-        label: STEP_LABELS[3],
+        step: 5,
+        label: STEP_LABELS[5],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 3, label: 'Confirm', feature });
-    stepHeader(3, 'Confirm', feature);
+    logEvent(root, 'step', { step: 5, label: 'Confirm', feature });
+    stepHeader(5, 'Confirm', feature);
     if (isResuming) {
-        printResumptionHeader(3);
+        printResumptionHeader(5);
     }
     console.log('Summarize what was built and get user confirmation.');
     console.log();
     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):'));
-    checkbox('Run `codeyam editor verify-images \'{"paths":["/","/other-page"]}\'` with all page paths');
-    console.log(chalk.dim('    Returns JSON with imagesFound, imagesVerified, and any failures.'));
+    checkbox('Run `codeyam editor verify-images \'{"paths":["/"], "imageUrls":["url1","url2"]}\'`');
+    console.log(chalk.dim('    Include ALL page paths and ALL image URLs from seed data / API responses.'));
+    console.log(chalk.dim('    Client-rendered pages need imageUrls — the HTML shell has no images.'));
     checkbox('Fix or remove any image that returns non-200 before continuing');
+    checkbox('Check for client-side errors: `codeyam editor client-errors`');
+    console.log(chalk.dim('    If there are errors, fix the underlying issue before presenting.'));
+    checkbox('Verify `hasContent=true` and `liveErrors=0` — do NOT ask the user to confirm if the preview is broken');
+    console.log();
+    console.log(chalk.bold('Verify the captured user prompt:'));
+    checkbox("Read `.codeyam/editor-user-prompt.txt` — this is the user's original feature request");
+    checkbox('If the file is missing or does not match what the user actually asked for, write the correct prompt text to `.codeyam/editor-user-prompt.txt`');
+    console.log(chalk.dim("    This must be the user's exact words, not a summary. It gets recorded in the journal."));
     console.log();
     console.log(chalk.bold('Then present to the user:'));
     checkbox('Summarize what was built (routes, components, data)');
-    checkbox('Show the user the current state of the prototype');
+    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();
-    console.log(chalk.bold('Present a selection menu to the user (use AskUserQuestion):'));
-    console.log(chalk.green('    "Yes, this looks right!"') +
-        chalk.dim(' — proceed to step 4'));
-    console.log(chalk.yellow('    "I\'d like some changes"') +
-        chalk.dim(' — user describes changes, you make them, then re-present'));
+    console.log(chalk.bold.cyan('Guide the user through interactive testing:'));
+    checkbox('Tell the user: "The preview is fully interactive — click around to test!"');
+    checkbox('Prompt the user to try key interactions: forms, navigation, buttons, etc.');
+    checkbox('Ask the user: "Does everything work as expected?"');
+    console.log();
+    console.log(chalk.bold('Present a selection menu to the user (use AskUserQuestion with these EXACT option labels):'));
+    console.log(chalk.green('    Option 1 label: "The live preview is displaying what I expected"') + chalk.dim(' — proceed to step 6'));
+    console.log(chalk.yellow('    Option 2 label: "I\'d like some changes"') +
+        chalk.dim(' — make changes, refresh preview, re-run `codeyam editor 5`'));
     console.log();
     console.log(chalk.dim('Wait for user approval before moving on. Refactoring and scenarios happen in later steps.'));
-    stopGate(3, { confirm: true });
+    stopGate(5, { confirm: true });
 }
-// ─── Step 4: Deconstruct ──────────────────────────────────────────────
-function printStep4(root, feature) {
+// ─── Step 6: Deconstruct ──────────────────────────────────────────────
+function printStep6(root, feature) {
     const prevState = readState(root);
-    const isResuming = prevState?.step === 4;
+    const isResuming = prevState?.step === 6;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 4,
-        label: STEP_LABELS[4],
+        step: 6,
+        label: STEP_LABELS[6],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 4, label: 'Deconstruct', feature });
-    stepHeader(4, 'Deconstruct', feature);
+    logEvent(root, 'step', { step: 6, label: 'Deconstruct', feature });
+    stepHeader(6, 'Deconstruct', feature);
     if (isResuming) {
-        printResumptionHeader(4);
+        printResumptionHeader(6);
     }
     console.log(chalk.bold('Goal: pages contain ONLY components. Components contain ONLY sub-components.'));
-    console.log(chalk.yellow('This step is read and plan only. Code extraction happens in step 5.'));
-    console.log();
-    console.log(chalk.bold.red('THE RULE: No direct JSX in page files.'));
-    console.log(chalk.yellow('  After extraction, a page/route file should import and compose components — nothing else.'));
-    console.log(chalk.yellow('  Every distinct visual section in the page is its own component.'));
-    console.log(chalk.yellow('  Every component that renders multiple distinct sections should be split into sub-components.'));
-    console.log(chalk.yellow('  If a component has N visually distinct parts, it should compose N sub-components.'));
+    console.log(chalk.yellow('This step is read and plan only. Code extraction happens in step 7.'));
     console.log();
-    console.log(chalk.bold('Checklist:'));
-    checkbox('Read `.codeyam/glossary.json` — note reusable functions/components');
-    checkbox('Read EVERY file created or modified in this session');
-    console.log(chalk.yellow('    For EACH file, identify EVERY extractable piece:'));
-    console.log(chalk.yellow('    Components: headers, nav, loading states, empty states, error states,'));
-    console.log(chalk.yellow('      badges/pills, image containers, card sections, form fields, modals,'));
-    console.log(chalk.yellow('      titles, descriptions, rating displays, status indicators, buttons'));
-    console.log(chalk.yellow('    Functions: data transforms, calculations, formatting, validation,'));
-    console.log(chalk.yellow('      API response shaping, any logic that is not directly about rendering'));
-    console.log(chalk.yellow('    Hooks: data fetching, state management, side effects'));
-    console.log();
-    checkbox('Write a numbered extraction plan listing EVERYTHING you will extract');
-    console.log(chalk.yellow('    The end state: every page file is ONLY imports + component composition.'));
-    console.log(chalk.yellow('    No raw <div>, <span>, <h1>, <p>, <img>, or <ul> in page files.'));
-    console.log(chalk.yellow('    Every visual section in every component is itself a component.'));
-    console.log();
-    console.log(chalk.yellow('    For each item in the plan, note:'));
-    console.log(chalk.yellow('    — What it is (component, function, hook)'));
-    console.log(chalk.yellow('    — Where it currently lives (source file + approximate lines)'));
-    console.log(chalk.yellow('    — Where it will go (new file path)'));
-    console.log();
-    console.log(chalk.dim('Present the numbered plan, then proceed to step 5 to execute it.'));
-    stopGate(4);
+    printExtractionPlanInstructions();
+    stopGate(6);
 }
-// ─── Step 5: Extract ──────────────────────────────────────────────────
-function printStep5(root, feature) {
+// ─── Step 7: Extract ──────────────────────────────────────────────────
+function printStep7(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
-    const isResuming = prevState?.step === 5;
+    const isResuming = prevState?.step === 7;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 5,
-        label: STEP_LABELS[5],
+        step: 7,
+        label: STEP_LABELS[7],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 5, label: 'Extract', feature });
-    stepHeader(5, 'Extract', feature);
+    logEvent(root, 'step', { step: 7, label: 'Extract', feature });
+    stepHeader(7, 'Extract', feature);
     if (isResuming) {
-        printResumptionHeader(5);
+        printResumptionHeader(7);
     }
-    console.log('Execute your extraction plan from step 4.');
+    console.log('Execute your extraction plan from step 6.');
     console.log();
     console.log(chalk.bold('Components:'));
     checkbox('Extract each component from your plan into its own file');
     checkbox('Page/route files must contain ZERO direct JSX — only imported components');
     checkbox('Every component that renders multiple sections must be split into sub-components');
-    console.log(chalk.dim('    No tests needed — visual verification happens in step 7'));
+    console.log(chalk.dim('    No tests needed — visual verification happens in step 9'));
     console.log();
-    console.log(chalk.bold('Library functions (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 9 only captures component screenshots.'));
     console.log();
     console.log(chalk.bold('Recursive pass:'));
     checkbox('Re-read EVERY new file you just created — extract components from components, functions from functions');
@@ -736,218 +1229,208 @@ 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();
     console.log(chalk.dim('Focus on TDD for functions and extraction for components. Scenarios come in later steps.'));
-    stopGate(5);
+    stopGate(7);
 }
-// ─── Step 6: Glossary ─────────────────────────────────────────────────
-function printStep6(root, feature) {
+// ─── Step 8: Glossary ─────────────────────────────────────────────────
+function printStep8(root, feature) {
     const prevState = readState(root);
-    const isResuming = prevState?.step === 6;
+    const isResuming = prevState?.step === 8;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 6,
-        label: STEP_LABELS[6],
+        step: 8,
+        label: STEP_LABELS[8],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 6, label: 'Glossary', feature });
-    stepHeader(6, 'Glossary', feature);
+    logEvent(root, 'step', { step: 8, label: 'Glossary', feature });
+    stepHeader(8, 'Glossary', feature);
     if (isResuming) {
-        printResumptionHeader(6);
+        printResumptionHeader(8);
     }
     console.log('Record all new functions/components in `.codeyam/glossary.json`.');
     console.log();
-    console.log(chalk.bold('Checklist:'));
-    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');
-    console.log();
-    console.log(chalk.bold('Entry format:'));
-    console.log(chalk.dim('  { "name": "calculateTotal", "filePath": "app/utils/pricing.ts",'));
-    console.log(chalk.dim('    "description": "Calculates total price including tax and discounts",'));
-    console.log(chalk.dim('    "parameters": [{ "name": "items", "type": "CartItem[]" }],'));
-    console.log(chalk.dim('    "returnType": "number", "tags": ["pricing"],'));
-    console.log(chalk.dim('    "testFile": "app/utils/pricing.test.ts",'));
-    console.log(chalk.dim(`    "feature": "${feature}", "createdAt": "..." }`));
+    printGlossaryInstructions(feature);
     console.log();
     console.log(chalk.dim('Focus on updating the glossary. Application code and scenarios come in later steps.'));
-    stopGate(6);
+    stopGate(8);
 }
-// ─── Step 7: Analyze ──────────────────────────────────────────────────
-function printStep7(root, feature) {
+// ─── Step 9: Analyze ──────────────────────────────────────────────────
+function printStep9(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
-    const isResuming = prevState?.step === 7;
+    const isResuming = prevState?.step === 9;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 7,
-        label: STEP_LABELS[7],
+        step: 9,
+        label: STEP_LABELS[9],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 7, label: 'Analyze', feature });
-    stepHeader(7, 'Analyze and Verify', feature);
+    logEvent(root, 'step', { step: 9, label: 'Analyze', feature });
+    stepHeader(9, 'Analyze and Verify', feature);
     if (isResuming) {
-        printResumptionHeader(7);
+        printResumptionHeader(9);
     }
     console.log('Verify visual components (via isolation routes) and library functions (via tests).');
     console.log();
     console.log(chalk.bold('Visual Components — Component Isolation:'));
-    checkbox('List all files with new/modified visual components from step 5');
-    checkbox('Ensure `app/codeyam-isolate/layout.tsx` exists with production guard (create if missing)');
-    console.log(chalk.dim('    The layout returns notFound() in production, so isolation routes are safe to commit.'));
-    console.log(chalk.dim('    Content: import { notFound } from "next/navigation"; export default ... if (NODE_ENV === "production") notFound();'));
+    checkbox('List all files with new/modified visual components from step 7');
     checkbox('Check existing scenarios: `codeyam editor scenarios`');
     console.log(chalk.dim('    Reuse and improve existing scenarios where possible — update mock data'));
     console.log(chalk.dim('    to reflect current changes. Add new scenarios only for genuinely new states.'));
     console.log(chalk.dim('    Ensure at least one scenario clearly demonstrates what changed in this session.'));
-    checkbox('For each visual component:');
-    console.log(chalk.dim('    1. Read the source AND find where it is used in the app to understand:'));
-    console.log(chalk.dim('       — Props/interface'));
-    console.log(chalk.dim('       — Container width in the real app (e.g. card in a 3-col grid → max-w-sm)'));
-    console.log(chalk.dim('    2. Plan multiple scenarios that exercise the component like tests:'));
-    console.log(chalk.dim('       — Default/happy path with typical data'));
-    console.log(chalk.dim('       — Edge cases: empty/missing data, long text, maximum items, zero counts'));
-    console.log(chalk.dim('       — Different visual states: loading, error, disabled, selected, hover'));
-    console.log(chalk.dim('       — Boundary values: single item vs many, min/max ratings, very long names'));
-    console.log(chalk.dim('    3. Create ONE isolation route per component with a scenarios map and ?s= query param:'));
-    console.log(chalk.dim('       Remix:   app/routes/codeyam-isolate.ComponentName.tsx → /codeyam-isolate/ComponentName'));
-    console.log(chalk.dim('       Next.js: app/codeyam-isolate/ComponentName/page.tsx → /codeyam-isolate/ComponentName'));
-    console.log(chalk.dim('       The route defines a `scenarios` object mapping scenario names to props,'));
-    console.log(chalk.dim('       reads `?s=ScenarioName` from the URL, and renders the component with those props.'));
-    console.log(chalk.dim('       Wrap the component in a capture container with id="codeyam-capture":'));
-    console.log(chalk.dim('       <div id="codeyam-capture" style={{ display:"inline-block", padding:"20px" }}>'));
-    console.log(chalk.dim('         <div style={{ width:"100%", maxWidth:"..." }}> ← match the app\'s container width'));
-    console.log(chalk.dim('       e.g. card in a 3-col grid → maxWidth:"24rem", full-width component → omit maxWidth'));
-    console.log(chalk.dim('       The screenshot captures just this wrapper, so the component fills the image.'));
-    console.log(chalk.dim('       Center the wrapper on the page (flexbox center both axes) and set a page background'));
-    console.log(chalk.dim('       color that matches where the component normally appears (e.g. white for light UIs).'));
-    console.log(chalk.dim('    4. Wait 2 seconds for HMR, then register + capture each scenario:'));
-    console.log(chalk.dim(`       codeyam editor register '{"name":"ComponentName - Scenario",`));
-    console.log(chalk.dim(`         "componentName":"ComponentName","componentPath":"path/to/file.tsx",`));
-    console.log(chalk.dim(`         "url":"/codeyam-isolate/ComponentName?s=Scenario",`));
-    console.log(chalk.dim(`         "mockData":{"routes":{"/api/...":{"body":[...]}}}}'`));
-    console.log(chalk.dim('       url is a PATH (starts with /) — the proxy routes it and intercepts API calls'));
-    console.log(chalk.dim('       mockData.routes provides data for API calls the component makes internally'));
-    console.log(chalk.dim('       (omit mockData if the component has no internal API calls)'));
-    console.log(chalk.yellow('    5. IMPORTANT: Check the register response for `clientErrors` array'));
-    console.log(chalk.yellow('       If clientErrors is non-empty → fix the isolation route and re-register'));
-    console.log(chalk.yellow('       Fix client errors and re-register before moving on'));
-    console.log(chalk.dim('    Isolation routes are committed to git — the layout guard blocks them in production'));
+    printComponentCaptureInstructions();
     console.log();
     console.log(chalk.bold('Library Functions — run tests:'));
-    checkbox('Run ALL test files created in step 5');
+    checkbox('Run ALL test files created in step 7');
     console.log(chalk.dim('    Example: npx vitest run app/lib/drinks.test.ts'));
     checkbox('Verify every test passes');
     checkbox('If any test fails, fix the source code and re-run');
     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');
-    stopGate(7);
+    checkbox('Run `codeyam editor audit` to verify all components have scenarios and all functions/hooks have tests');
+    console.log(chalk.red.bold('    The audit is a HARD GATE — step 10 will refuse to run until the audit passes.'));
+    console.log(chalk.dim('    When audit passes, the import graph is built automatically for change tracking.'));
+    console.log();
+    stopGate(9);
 }
-// ─── Step 8: App Scenarios ────────────────────────────────────────────
-function printStep8(root, feature) {
+// ─── Step 10: App Scenarios ────────────────────────────────────────────
+function printStep10(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
-    const isResuming = prevState?.step === 8;
+    const isResuming = prevState?.step === 10;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 8,
-        label: STEP_LABELS[8],
+        step: 10,
+        label: STEP_LABELS[10],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 8, label: 'App Scenarios', feature });
-    stepHeader(8, 'App Scenarios', feature);
+    logEvent(root, 'step', { step: 10, label: 'App Scenarios', feature });
+    stepHeader(10, 'App Scenarios', feature);
     if (isResuming) {
-        printResumptionHeader(8);
+        printResumptionHeader(10);
     }
-    console.log('Create app-level scenarios 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.cyan('Scenario naming — describe data states, not features:'));
+    console.log(chalk.cyan('  • Name scenarios by what they represent: "Rich Data", "Empty", "Mobile", "Minimal"'));
+    console.log(chalk.cyan('  • When enhancing a scenario with new feature data, update the name if it has grown beyond its original scope'));
+    console.log(chalk.cyan('  • A single rich scenario exercising multiple features is more valuable than separate thin scenarios per feature'));
+    console.log(chalk.cyan('  • Re-register with the same name to update; to rename, register with the new name'));
     console.log();
-    console.log(chalk.bold('Checklist:'));
-    checkbox('Check existing scenarios: `codeyam editor scenarios`');
-    console.log(chalk.dim('    Review existing scenarios — reuse and update their mock 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 a new API route was added: update existing scenarios to include its data'));
+    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 (empty, loaded, error)');
-    console.log(chalk.dim('    Each scenario provides data across ALL API routes for that state'));
-    console.log(chalk.dim('    Name app scenarios descriptively: "Empty", "Full Catalog", "API Error"'));
-    checkbox('Register each scenario (auto-captures screenshot):');
-    console.log(chalk.dim(`    codeyam editor register '{"name":"Empty","description":"...","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'));
+    printAppScenarioInstructions();
     console.log();
-    console.log(chalk.dim('Focus on creating and registering app-level scenarios. Code fixes happen in step 10 if needed.'));
-    stopGate(8);
+    console.log(chalk.dim('Focus on creating and registering app-level scenarios. Code fixes happen in step 12 if needed.'));
+    console.log();
+    console.log(chalk.bold.cyan("Verify your work — screenshots don't lie:"));
+    console.log(chalk.cyan('  • View every captured screenshot. Does it show what the scenario name promises?'));
+    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(10);
 }
-// ─── Step 9: User Scenarios ───────────────────────────────────────────
-function printStep9(root, feature) {
+// ─── Step 11: User Scenarios ───────────────────────────────────────────
+function printStep11(root, feature) {
     const port = getServerPort();
     const prevState = readState(root);
-    const isResuming = prevState?.step === 9;
+    const isResuming = prevState?.step === 11;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 9,
-        label: STEP_LABELS[9],
+        step: 11,
+        label: STEP_LABELS[11],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 9, label: 'User Scenarios', feature });
-    stepHeader(9, 'User Scenarios', feature);
+    logEvent(root, 'step', { step: 11, label: 'User Scenarios', feature });
+    stepHeader(11, 'User Scenarios', feature);
     if (isResuming) {
-        printResumptionHeader(9);
+        printResumptionHeader(11);
     }
-    console.log('Create per-persona 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 12 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 mock 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.dim('    Each persona scenario provides data across ALL API routes for that user type'));
-    checkbox('Register each persona scenario (auto-captures screenshot):');
-    console.log(chalk.dim(`    codeyam editor register '{"name":"...","description":"...","mockData":{"routes":{"/api/...":{"body":[...]}}}}'`));
+    console.log(chalk.bold('If the app has NO users/auth:'));
+    console.log(chalk.dim('  Skip this step and proceed to step 12 (Verify).'));
+    console.log();
+    console.log(chalk.bold('If the app has users/auth:'));
+    console.log();
+    console.log(chalk.bold('Goal: Create persona variations of EXISTING app scenarios.'));
+    console.log(chalk.dim('  Do NOT create standalone persona scenarios. Each user-persona scenario should be'));
+    console.log(chalk.dim('  a variation of an existing app scenario from step 10, with user-specific state layered on.'));
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    checkbox('Run `codeyam editor scenarios` — list all existing app scenarios');
+    checkbox('For EACH existing app scenario, create a logged-in variation:');
+    console.log(chalk.dim('    Copy the scenario seed data and add "session":{"cookieValue":"sess_alice"} + user seed'));
+    console.log(chalk.dim('    Name: "<Original Name> - Logged In" (e.g. "Full Catalog - Logged In")'));
+    console.log(chalk.dim('    Step 10 scenarios already serve as logged-out versions (no session cookie)'));
+    checkbox('If there are multiple user roles (admin, regular, etc.), create role-specific variations too');
+    console.log(chalk.dim('    Each persona scenario layers user-specific seed data on top of an app scenario'));
+    checkbox('Include "dimensions" — inherit from the base app scenario, or override if the persona implies a different device');
+    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.'));
-    stopGate(9);
+    console.log(chalk.dim('See FEATURE_PATTERNS.md and AUTH_PATTERNS.md for auth scenario guidance.'));
+    stopGate(11);
 }
-// ─── Step 10: Verify ──────────────────────────────────────────────────
-function printStep10(root, feature) {
+// ─── Step 12: Verify ──────────────────────────────────────────────────
+function printStep12(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
-    const isResuming = prevState?.step === 10;
+    const isResuming = prevState?.step === 12;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 10,
-        label: STEP_LABELS[10],
+        step: 12,
+        label: STEP_LABELS[12],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 10, label: 'Verify', feature });
-    stepHeader(10, 'Verify', feature);
+    logEvent(root, 'step', { step: 12, label: 'Verify', feature });
+    stepHeader(12, 'Verify', feature);
     if (isResuming) {
-        printResumptionHeader(10);
+        printResumptionHeader(12);
     }
     console.log('Verify component isolation screenshots, editor scenarios, and library tests.');
     console.log();
@@ -958,143 +1441,829 @@ 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'));
     checkbox(`Check for client-side errors: \`codeyam editor client-errors\``);
     console.log(chalk.yellow('    If `hasErrors` is true: list each scenario with errors, fix the source code,'));
     console.log(chalk.yellow('    re-register the affected scenarios, and re-check until hasErrors is false'));
     console.log(chalk.dim('    Common errors: React errors, failed fetches, undefined references, hydration mismatches'));
-    checkbox('Verify no broken images: extract <img> src URLs from each page, `curl -s -o /dev/null -w "%{http_code}" <url>` each one — must return 200');
+    checkbox('Verify no broken images: `codeyam editor verify-images \'{"paths":["/"], "imageUrls":["url1"]}\'` with all page paths and image URLs');
     console.log();
     console.log(chalk.bold('Library functions — test check:'));
-    checkbox('Re-run all test files from step 5 to confirm they still pass');
+    checkbox('Re-run all test files from step 7 to confirm they still pass');
     console.log(chalk.dim('    Example: npx vitest run app/lib/drinks.test.ts'));
     checkbox('If any test fails, fix the source code and re-run');
     console.log();
     console.log(chalk.dim('Focus on fixing issues. All component screenshots, scenarios, and tests must be clean before proceeding.'));
-    stopGate(10);
+    stopGate(12);
+}
+// ─── Step 13: Journal ─────────────────────────────────────────────────
+function printStep13(root, feature) {
+    const port = getServerPort();
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 13;
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature,
+        step: 13,
+        label: STEP_LABELS[13],
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
+    });
+    logEvent(root, 'step', { step: 13, label: 'Journal', feature });
+    stepHeader(13, 'Journal', feature);
+    if (isResuming) {
+        printResumptionHeader(13);
+    }
+    console.log('Create or update the journal entry for this feature.');
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    checkbox('Write a concise description of what was built (2-3 sentences)');
+    checkbox(`First time at step 13 — create journal entry with ALL session screenshots:`);
+    console.log(chalk.dim(`    codeyam editor journal '{"title":"...","type":"feature","description":"...","includeSessionScenarios":true}'`));
+    console.log(chalk.dim('    includeSessionScenarios auto-discovers component + app + user persona screenshots'));
+    checkbox(`Returning to step 13 (before commit) — update the existing journal entry:`);
+    console.log(chalk.dim(`    codeyam editor journal-update '{"time":"<journal entry time>","description":"<updated>","includeSessionScenarios":true}'`));
+    console.log(chalk.dim('    Note: PATCH only works before the entry is committed. After commit, use POST to create a new entry.'));
+    console.log();
+    console.log(chalk.dim('Focus on creating or updating the journal entry. Summary and presentation happen in step 15.'));
+    stopGate(13);
+}
+// ─── Step 14: Review ──────────────────────────────────────────────────
+function printStep14(root, feature) {
+    const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 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: 'Review', feature });
+    stepHeader(14, 'Review', feature);
+    if (isResuming) {
+        printResumptionHeader(14);
+    }
+    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 '{"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\``);
+    checkbox('If `hasErrors` is true, fix them and re-capture affected scenarios');
+    checkbox('Run `codeyam editor verify-images \'{"paths":["/"], "imageUrls":["url1"]}\'` with all page paths and image URLs');
+    checkbox('Fix or remove any broken images before continuing');
+    checkbox('Recapture stale scenarios: `codeyam editor recapture-stale`');
+    checkbox('Run `codeyam editor audit` to verify completeness of scenarios and tests');
+    checkbox('Do not proceed until all checks pass');
+    stopGate(14);
+}
+// ─── Step 15: Present ─────────────────────────────────────────────────
+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: 'Present', feature });
+    stepHeader(15, 'Present', feature);
+    if (isResuming) {
+        printResumptionHeader(15);
+    }
+    console.log('Present the results to the user and get their approval.');
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    checkbox(`Show the results panel: \`codeyam editor show-results\``);
+    console.log(chalk.dim('    This opens a visual panel below the terminal showing all scenarios with screenshots.'));
+    console.log(chalk.dim('    The preview automatically switches to the first app-level scenario.'));
+    console.log(chalk.dim('    The user can click scenarios to switch the live preview.'));
+    checkbox('Write a 1-2 sentence summary of what was built');
+    checkbox('Report test count and audit status (one line)');
+    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: "Save & commit"') +
+        chalk.dim(' — git commit all changes and record in journal'));
+    console.log(chalk.yellow('    Option 2 label: "I\'d like to make some changes"') +
+        chalk.dim(' — describe changes, then re-verify'));
+    console.log();
+    console.log(chalk.bold('If the user chooses "Save & commit":'));
+    checkbox('Advance to the commit step: `codeyam editor 16`');
+    console.log();
+    console.log(chalk.bold('If the user chooses "Make changes" (or asks for ANY change, even as a question):'));
+    checkbox(`Hide the results panel: \`codeyam editor hide-results\``);
+    checkbox('Ask what changes the user wants (if not already clear)');
+    checkbox(`Run: \`codeyam editor change "${feature}"\` — this gives you the change checklist`);
+    checkbox('THEN make the requested changes and follow the checklist');
+    console.log(chalk.red.bold('  IMPORTANT: Always run the change command BEFORE writing any code.'));
+    stopGate(15, { confirm: true });
+}
+// ─── Migration Mode ──────────────────────────────────────────────────
+/**
+ * Print a progress tracker for the 8 migration steps.
+ */
+function printMigrationProgressTracker(current, pageName, pageIndex, totalPages) {
+    console.log();
+    console.log(chalk.dim(`  Migration: Page ${pageIndex + 1}/${totalPages} (${pageName})`));
+    console.log(chalk.dim('  ┌─────────────────────────────────────┐'));
+    for (let i = 1; i <= 10; i++) {
+        const label = MIGRATION_STEP_LABELS[i];
+        const num = i < 10 ? ` ${i}` : `${i}`;
+        const content = `${num}. ${label.padEnd(28)}`;
+        if (i < current) {
+            console.log(chalk.dim('  │') + chalk.green(`  ✓  ${content}`) + chalk.dim('│'));
+        }
+        else if (i === current) {
+            console.log(chalk.dim('  │') + chalk.bold.cyan(`  →  ${content}`) + chalk.dim('│'));
+        }
+        else {
+            console.log(chalk.dim(`  │  ○  ${content}│`));
+        }
+    }
+    console.log(chalk.dim('  └─────────────────────────────────────┘'));
+}
+/**
+ * Print a STOP gate for migration steps.
+ */
+function migrationStopGate(current, pageName, pageIndex, totalPages, opts) {
+    console.log();
+    console.log(chalk.bold.red('━━━ STOP ━━━'));
+    console.log();
+    console.log(chalk.red('Complete each checklist item above before proceeding to the next step.'));
+    if (opts?.confirm) {
+        console.log();
+        console.log(chalk.yellow('Wait for user confirmation before moving on.'));
+    }
+    console.log();
+    console.log(chalk.bold.yellow('Present the following progress tracker to the user (copy it verbatim):'));
+    printMigrationProgressTracker(current, pageName, pageIndex, totalPages);
+    console.log();
+    console.log(chalk.yellow('For the CURRENT step (→), show each checklist item with ✓ (done) or ✗ (skipped + reason).'));
+    console.log();
+    if (current === 5) {
+        // Step 5 (Discuss) can skip to step 9 if user declines decomposition
+        console.log(chalk.green('If decomposing, run: ') +
+            chalk.bold('codeyam editor migrate 6'));
+        console.log(chalk.green('If skipping decomposition, run: ') +
+            chalk.bold('codeyam editor migrate 9'));
+    }
+    else if (current < 10) {
+        console.log(chalk.green('When done, run: ') +
+            chalk.bold(`codeyam editor migrate ${current + 1}`));
+    }
+    else {
+        console.log(chalk.green('Page complete! Run: ') +
+            chalk.bold('codeyam editor migrate next') +
+            chalk.green(' to start the next page'));
+    }
+    console.log();
+}
+/**
+ * Write migration-aware editor state.
+ */
+function writeMigrationStepState(root, step, pageName, pageIndex, totalPages) {
+    const prevState = readState(root);
+    const isResuming = prevState?.step === step && !!prevState?.migration;
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature: `Migration: ${pageName}`,
+        step,
+        label: MIGRATION_STEP_LABELS[step],
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
+        migration: {
+            pageName,
+            pageIndex,
+            totalPages,
+        },
+    });
+    logEvent(root, 'step', {
+        step,
+        label: MIGRATION_STEP_LABELS[step],
+        feature: `Migration: ${pageName}`,
+        migration: true,
+    });
+}
+/**
+ * Get the current migration page info from state, or return null.
+ */
+function getCurrentMigrationPage(root) {
+    const migState = readMigrationState(root);
+    if (!migState || migState.pages.length === 0)
+        return null;
+    const page = migState.pages[migState.currentPageIndex];
+    if (!page)
+        return null;
+    return {
+        pageName: page.name,
+        pageIndex: migState.currentPageIndex,
+        totalPages: migState.pages.length,
+    };
+}
+// ─── Migration Step 1: Survey ───────────────────────────────────────
+function printMigrateStep1(root) {
+    const pageInfo = getCurrentMigrationPage(root);
+    if (!pageInfo) {
+        console.error(chalk.red('Error: No migration in progress. Run `codeyam editor migrate` first.'));
+        process.exit(1);
+    }
+    const { pageName, pageIndex, totalPages } = pageInfo;
+    writeMigrationStepState(root, 1, pageName, pageIndex, totalPages);
+    const migState = readMigrationState(root);
+    const page = migState.pages[pageIndex];
+    console.log();
+    console.log(chalk.bold.cyan(`━━━ Migration Step 1: Survey — ${pageName} (${pageIndex + 1}/${totalPages}) ━━━`));
+    console.log();
+    console.log(chalk.bold('Goal: Survey the page, understand its structure, and start the dev server.'));
+    console.log();
+    console.log(chalk.bold('Survey:'));
+    checkbox(`Read the page file: \`${page.filePath}\``);
+    checkbox('Follow every import — read all local components, hooks, utilities used by this page');
+    checkbox('Map the data flow: where does data come from? Server actions? API routes? Props?');
+    checkbox('Check `.codeyam/glossary.json` for components already extracted from previous pages');
+    checkbox('Check `.codeyam/migration-state.json` sharedComponents for reusable pieces');
+    checkbox('Note the page route and any dynamic segments');
+    console.log();
+    console.log(chalk.bold('Dev Server:'));
+    checkbox('If the dev server is not running yet, figure out how to start it (check package.json scripts)');
+    checkbox('FIRST: Verify dependencies are installed (check if node_modules/ exists and is non-empty)');
+    console.log(chalk.yellow('    If node_modules is missing or sparse, run the package manager install command first'));
+    console.log(chalk.dim('    Missing deps cause cryptic 500 errors at render time — install BEFORE starting the server'));
+    checkbox('Start the dev server: `codeyam editor dev-server \'{"action":"start"}\'`');
+    checkbox("Verify it's running: check for successful startup output");
+    console.log();
+    migrationStopGate(1, pageName, pageIndex, totalPages);
+}
+// ─── Migration Step 2: App Scenarios ────────────────────────────────
+function printMigrateStep2(root) {
+    const pageInfo = getCurrentMigrationPage(root);
+    if (!pageInfo) {
+        console.error(chalk.red('Error: No migration in progress. Run `codeyam editor migrate` first.'));
+        process.exit(1);
+    }
+    const { pageName, pageIndex, totalPages } = pageInfo;
+    writeMigrationStepState(root, 2, pageName, pageIndex, totalPages);
+    const migState = readMigrationState(root);
+    const page = migState.pages[pageIndex];
+    console.log();
+    console.log(chalk.bold.cyan(`━━━ Migration Step 2: App Scenarios — ${pageName} (${pageIndex + 1}/${totalPages}) ━━━`));
+    console.log();
+    console.log(chalk.bold(`Goal: Register application scenarios that screenshot the ACTUAL page at "${page.route}".`));
+    console.log();
+    console.log(chalk.yellow('  App scenarios capture how the full page looks with different data states.'));
+    console.log(chalk.yellow(`  Every scenario MUST use the real page route ("${page.route}") — NOT isolation routes.`));
+    console.log(chalk.yellow('  These are the primary scenarios the user will see for this page.'));
+    console.log();
+    console.log(chalk.bold('Seed Adapter Setup:'));
+    checkbox('Check if a seed adapter exists: `ls .codeyam/seed-adapter.ts 2>/dev/null`');
+    console.log(chalk.yellow('  If NO seed adapter exists, create one. The seed adapter wipes and re-seeds the database'));
+    console.log(chalk.yellow('  for each scenario, enabling different data states on the real page.'));
+    console.log();
+    console.log(chalk.dim('  How to create a seed adapter:'));
+    console.log(chalk.dim('  1. Identify the database technology from your step 1 survey (Prisma, Supabase, Drizzle, etc.)'));
+    console.log(chalk.dim('  2. Check for a matching template: `ls .codeyam/seed-adapters/`'));
+    console.log(chalk.dim('  3. For Supabase: `cp .codeyam/seed-adapters/supabase.ts .codeyam/seed-adapter.ts`'));
+    console.log(chalk.dim('     The seed adapter auto-detects Supabase credentials by scanning env var VALUES (not names).'));
+    console.log(chalk.dim('     It reads .env / .env.local and finds: *.supabase.co URLs, sb_secret_* keys, and legacy JWTs.'));
+    console.log(chalk.dim('     Do NOT grep for specific env var names — just register a scenario and try it.'));
+    console.log(chalk.dim('     If it fails, the error message will say exactly what credentials are missing.'));
+    console.log(chalk.dim('  4. For Prisma: write a seed adapter that uses your Prisma client to delete/insert rows'));
+    console.log(chalk.dim('  5. For other databases: write a .codeyam/seed-adapter.ts that reads a JSON file (argv[2]),'));
+    console.log(chalk.dim('     deletes all rows from each table, then inserts the seed rows. Format: {"table": [{...}]}'));
+    console.log(chalk.dim('  6. Test it: write a small test seed JSON and run `npx tsx .codeyam/seed-adapter.ts test.json`'));
+    console.log();
+    printAppScenarioInstructions(pageName, page.route);
+    console.log();
+    migrationStopGate(2, pageName, pageIndex, totalPages);
+}
+// ─── Migration Step 3: Component Scenarios ──────────────────────────
+function printMigrateStep3(root) {
+    const pageInfo = getCurrentMigrationPage(root);
+    if (!pageInfo) {
+        console.error(chalk.red('Error: No migration in progress. Run `codeyam editor migrate` first.'));
+        process.exit(1);
+    }
+    const { pageName, pageIndex, totalPages } = pageInfo;
+    writeMigrationStepState(root, 3, pageName, pageIndex, totalPages);
+    console.log();
+    console.log(chalk.bold.cyan(`━━━ Migration Step 3: Component Scenarios — ${pageName} (${pageIndex + 1}/${totalPages}) ━━━`));
+    console.log();
+    console.log(chalk.bold('Goal: Capture individual component scenarios for major visual components on this page.'));
+    console.log();
+    console.log(chalk.dim('  Component scenarios use isolation routes with a codeyam-capture wrapper for tight screenshots.'));
+    console.log(chalk.dim('  These supplement the app scenarios from step 2 with focused component-level views.'));
+    console.log();
+    printComponentCaptureInstructions();
+    console.log();
+    migrationStopGate(3, pageName, pageIndex, totalPages);
+}
+// ─── Migration Step 4: Preview ──────────────────────────────────────
+function printMigrateStep4(root) {
+    const pageInfo = getCurrentMigrationPage(root);
+    if (!pageInfo) {
+        console.error(chalk.red('Error: No migration in progress.'));
+        process.exit(1);
+    }
+    const { pageName, pageIndex, totalPages } = pageInfo;
+    writeMigrationStepState(root, 4, pageName, pageIndex, totalPages);
+    console.log();
+    console.log(chalk.bold.cyan(`━━━ Migration Step 4: Preview — ${pageName} (${pageIndex + 1}/${totalPages}) ━━━`));
+    console.log();
+    console.log(chalk.bold('Goal: Verify screenshots look correct and show results to the user.'));
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    checkbox('Review all scenario screenshots for this page — do they look correct?');
+    checkbox('Check for client errors: `codeyam editor client-errors`');
+    checkbox('If any issues: fix the scenario data, re-register affected scenarios');
+    checkbox('Show results: `codeyam editor show-results`');
+    console.log(chalk.dim('    The preview automatically switches to the first app-level scenario.'));
+    console.log();
+    console.log(chalk.dim('The user should now see their existing page with live screenshots in the preview.'));
+    migrationStopGate(4, pageName, pageIndex, totalPages);
+}
+// ─── Migration Step 5: Discuss ──────────────────────────────────────
+function printMigrateStep5(root) {
+    const pageInfo = getCurrentMigrationPage(root);
+    if (!pageInfo) {
+        console.error(chalk.red('Error: No migration in progress.'));
+        process.exit(1);
+    }
+    const { pageName, pageIndex, totalPages } = pageInfo;
+    writeMigrationStepState(root, 5, pageName, pageIndex, totalPages);
+    console.log();
+    console.log(chalk.bold.cyan(`━━━ Migration Step 5: Discuss — ${pageName} (${pageIndex + 1}/${totalPages}) ━━━`));
+    console.log();
+    console.log(chalk.bold('Goal: Assess page complexity and ask the user if decomposition is worth it.'));
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    checkbox('Hide results: `codeyam editor hide-results`');
+    checkbox("Assess the page's complexity:");
+    console.log(chalk.dim('    — How many inline components exist?'));
+    console.log(chalk.dim('    — How much business logic is embedded in the page file?'));
+    console.log(chalk.dim('    — Are there reusable pieces that other pages could share?'));
+    console.log(chalk.dim('    — Would extraction improve testability or maintainability?'));
+    checkbox('Present your assessment to the user');
+    console.log();
+    console.log(chalk.bold('Present a selection menu (AskUserQuestion with these EXACT option labels):'));
+    console.log(chalk.green('    Option 1 label: "Yes, decompose this page"') +
+        chalk.dim(' — continue to step 6 (Decompose)'));
+    console.log(chalk.yellow('    Option 2 label: "No, skip decomposition"') +
+        chalk.dim(' — skip to step 9 (Journal)'));
+    console.log();
+    console.log(chalk.bold.yellow('Routing:'));
+    console.log(chalk.yellow('  If user chooses decomposition: ') +
+        chalk.bold('codeyam editor migrate 6'));
+    console.log(chalk.yellow('  If user skips: ') + chalk.bold('codeyam editor migrate 9'));
+    migrationStopGate(5, pageName, pageIndex, totalPages, { confirm: true });
+}
+// ─── Migration Step 6: Decompose ────────────────────────────────────
+function printMigrateStep6(root) {
+    const pageInfo = getCurrentMigrationPage(root);
+    if (!pageInfo) {
+        console.error(chalk.red('Error: No migration in progress.'));
+        process.exit(1);
+    }
+    const { pageName, pageIndex, totalPages } = pageInfo;
+    writeMigrationStepState(root, 6, pageName, pageIndex, totalPages);
+    console.log();
+    console.log(chalk.bold.cyan(`━━━ Migration Step 6: Decompose — ${pageName} (${pageIndex + 1}/${totalPages}) ━━━`));
+    console.log();
+    console.log(chalk.bold('Goal: Plan all extractions. Mark already-extracted shared components as REUSE.'));
+    console.log(chalk.yellow('This step is read and plan only. Code extraction happens in step 7.'));
+    console.log();
+    console.log(chalk.bold.yellow('Migration note: check glossary for reuse opportunities'));
+    console.log(chalk.yellow('  If a component exists in the glossary from a previous page, mark it as REUSE in your plan.'));
+    console.log(chalk.yellow('  Only add it to the extraction plan if it needs modifications for this page.'));
+    console.log();
+    printExtractionPlanInstructions();
+    migrationStopGate(6, pageName, pageIndex, totalPages);
+}
+// ─── Migration Step 7: Extract ──────────────────────────────────────
+function printMigrateStep7(root) {
+    const pageInfo = getCurrentMigrationPage(root);
+    if (!pageInfo) {
+        console.error(chalk.red('Error: No migration in progress.'));
+        process.exit(1);
+    }
+    const { pageName, pageIndex, totalPages } = pageInfo;
+    writeMigrationStepState(root, 7, pageName, pageIndex, totalPages);
+    console.log();
+    console.log(chalk.bold.cyan(`━━━ Migration Step 7: Extract — ${pageName} (${pageIndex + 1}/${totalPages}) ━━━`));
+    console.log();
+    console.log(chalk.bold('Goal: Execute the extraction plan. Components first, then functions via TDD.'));
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    checkbox('Extract visual components (no tests needed for components)');
+    checkbox('Extract library functions via TDD (write failing test first, then implement)');
+    checkbox('Extract hooks as needed');
+    checkbox('Recursive pass: check each extracted component for further extraction');
+    console.log(chalk.yellow('    Each component should be a thin shell composing sub-components.'));
+    checkbox('Verify the page file is ONLY imports + component composition');
+    checkbox('Run tests to confirm nothing is broken: `npx jest --testPathPattern="<relevant>" --maxWorkers=2`');
+    console.log();
+    console.log(chalk.dim('After extraction, the page should be a thin shell. Move to step 8 to recapture.'));
+    migrationStopGate(7, pageName, pageIndex, totalPages);
+}
+// ─── Migration Step 8: Recapture ────────────────────────────────────
+function printMigrateStep8(root) {
+    const pageInfo = getCurrentMigrationPage(root);
+    if (!pageInfo) {
+        console.error(chalk.red('Error: No migration in progress.'));
+        process.exit(1);
+    }
+    const { pageName, pageIndex, totalPages } = pageInfo;
+    writeMigrationStepState(root, 8, pageName, pageIndex, totalPages);
+    const migState = readMigrationState(root);
+    const page = migState.pages[pageIndex];
+    console.log();
+    console.log(chalk.bold.cyan(`━━━ Migration Step 8: Recapture — ${pageName} (${pageIndex + 1}/${totalPages}) ━━━`));
+    console.log();
+    console.log(chalk.bold('Goal: Update glossary, re-register ALL scenarios after code changes, and verify.'));
+    console.log();
+    console.log(chalk.bold('Glossary:'));
+    printGlossaryInstructions();
+    console.log(chalk.yellow('    Skip entries already in the glossary from previous page migrations.'));
+    checkbox('Update sharedComponents in `.codeyam/migration-state.json` if any extracted components are shared');
+    console.log();
+    console.log(chalk.bold.red('Re-register App Scenarios (REQUIRED):'));
+    console.log(chalk.yellow(`  You MUST re-register application scenarios for "${page.route}" to get fresh screenshots.`));
+    checkbox('Fetch existing scenarios: `codeyam editor scenarios`');
+    checkbox('Find all scenarios that use the real page route (not /codeyam-isolate/ paths)');
+    checkbox('Re-register each one with the SAME name to update its screenshot');
+    console.log(chalk.dim(`    Example: codeyam editor register '{"name":"${pageName} - Full Data","type":"application","url":"${page.route}",...}'`));
+    checkbox('After each registration, check the response for `clientErrors`');
+    console.log(chalk.yellow('    Fix client errors and re-register before moving on'));
+    console.log();
+    console.log(chalk.bold('Component Scenarios:'));
+    console.log(chalk.dim('  For each visual component extracted in step 7, create isolation routes and register scenarios.'));
+    printComponentCaptureInstructions();
+    console.log();
+    console.log(chalk.bold('Verify:'));
+    checkbox('Run `codeyam editor analyze-imports` to populate import graph');
+    checkbox('Run library function tests: `npx jest --testPathPattern="<relevant>" --maxWorkers=2`');
+    checkbox('Run `codeyam editor audit` to check completeness');
+    checkbox('Check for client errors: `codeyam editor client-errors`');
+    checkbox('Fix any issues before proceeding');
+    console.log();
+    migrationStopGate(8, pageName, pageIndex, totalPages);
+}
+// ─── Migration Step 9: Journal ──────────────────────────────────────
+function printMigrateStep9(root) {
+    const pageInfo = getCurrentMigrationPage(root);
+    if (!pageInfo) {
+        console.error(chalk.red('Error: No migration in progress.'));
+        process.exit(1);
+    }
+    const { pageName, pageIndex, totalPages } = pageInfo;
+    writeMigrationStepState(root, 9, pageName, pageIndex, totalPages);
+    console.log();
+    console.log(chalk.bold.cyan(`━━━ Migration Step 9: Journal — ${pageName} (${pageIndex + 1}/${totalPages}) ━━━`));
+    console.log();
+    console.log(`Create a journal entry documenting the migration of the ${pageName} page.`);
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    checkbox('Write a concise description of what was migrated (2-3 sentences)');
+    checkbox(`Create journal: \`codeyam editor journal '{"title":"Migration: ${pageName}","type":"migration","description":"...","includeSessionScenarios":true}'\``);
+    console.log();
+    migrationStopGate(9, pageName, pageIndex, totalPages);
+}
+// ─── Migration Step 10: Present ─────────────────────────────────────
+function printMigrateStep10(root) {
+    const pageInfo = getCurrentMigrationPage(root);
+    if (!pageInfo) {
+        console.error(chalk.red('Error: No migration in progress.'));
+        process.exit(1);
+    }
+    const { pageName, pageIndex, totalPages } = pageInfo;
+    writeMigrationStepState(root, 10, pageName, pageIndex, totalPages);
+    console.log();
+    console.log(chalk.bold.cyan(`━━━ Migration Step 10: Present — ${pageName} (${pageIndex + 1}/${totalPages}) ━━━`));
+    console.log();
+    console.log("Show results and commit this page's migration.");
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    checkbox('Show results: `codeyam editor show-results`');
+    console.log(chalk.dim('    The preview automatically switches to the first app-level scenario.'));
+    checkbox('Write a 1-2 sentence summary of what was migrated');
+    console.log();
+    console.log(chalk.bold('Present a selection menu (AskUserQuestion with these EXACT option labels):'));
+    console.log(chalk.green('    Option 1 label: "Save & commit"') +
+        chalk.dim(" — commit this page's migration"));
+    console.log(chalk.yellow('    Option 2 label: "I\'d like to make some changes"') +
+        chalk.dim(' — make changes, then re-verify'));
+    console.log();
+    console.log(chalk.bold('If the user chooses "Save & commit":'));
+    checkbox('Hide results: `codeyam editor hide-results`');
+    checkbox(`Commit: \`codeyam editor commit '{"message":"migration: ${pageName} page\\n\\n<description>"}'\``);
+    checkbox('Mark page complete: `codeyam editor migrate complete`');
+    const remaining = pageInfo.totalPages - pageIndex - 1;
+    if (remaining > 0) {
+        checkbox('Advance to next page: `codeyam editor migrate next`');
+        console.log();
+        console.log(chalk.bold.green(`Page ${pageIndex + 1}/${totalPages} complete! ${remaining} page(s) remaining.`));
+    }
+    else {
+        console.log();
+        console.log(chalk.bold.green('Migration complete! All pages processed.'));
+        console.log(chalk.green('The project is now fully migrated. Future sessions use the normal feature workflow.'));
+        console.log(chalk.green('Start building: ') + chalk.bold('codeyam editor steps'));
+    }
+    console.log();
+    console.log(chalk.bold('If the user chooses "Make changes":'));
+    checkbox('Hide results: `codeyam editor hide-results`');
+    checkbox('Ask what changes the user wants');
+    checkbox(`Run: \`codeyam editor change "Migration: ${pageName}"\` — follow the change checklist`);
+    console.log();
+    migrationStopGate(10, pageName, pageIndex, totalPages, { confirm: true });
+}
+// ─── Migration Survey ───────────────────────────────────────────────
+function printMigrateSurvey(root) {
+    console.log();
+    console.log(chalk.bold.cyan('━━━ Project Migration Survey ━━━'));
+    console.log();
+    console.log('Survey the existing project, present a migration plan, and confirm the order with the user.');
+    console.log(chalk.dim('See the "Migration Survey" section in SKILL.md for the full checklist and migration-state.json format.'));
+    console.log();
+    // Write editor state so hooks and printCycleOverview detect migration
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature: 'Migration: Survey',
+        step: 0,
+        label: 'Survey',
+        startedAt: now,
+        featureStartedAt: now,
+        migration: {
+            pageName: 'Survey',
+            pageIndex: -1,
+            totalPages: 0,
+        },
+    });
+    logEvent(root, 'migration-survey', {});
+    console.log(chalk.bold.red('━━━ STOP ━━━'));
+    console.log();
+    console.log(chalk.red('Survey the project and confirm the migration order with the user.'));
+    console.log(chalk.green('After confirmation and writing migration-state.json: ') +
+        chalk.bold('codeyam editor migrate 1'));
+    console.log();
+}
+// ─── Migration Status ───────────────────────────────────────────────
+function printMigrationStatus(root) {
+    const state = readMigrationState(root);
+    if (!state) {
+        console.log(chalk.dim('No migration in progress.'));
+        return;
+    }
+    console.log();
+    console.log(chalk.bold.cyan('━━━ Migration Progress ━━━'));
+    console.log();
+    const done = state.pages.filter((p) => p.status === 'complete').length;
+    const total = state.pages.length;
+    const pct = total > 0 ? Math.round((done / total) * 100) : 0;
+    console.log(`  Status: ${chalk.bold(state.status)} — ${done}/${total} pages (${pct}%)`);
+    console.log();
+    for (let i = 0; i < state.pages.length; i++) {
+        const p = state.pages[i];
+        let icon;
+        let color;
+        if (p.status === 'complete') {
+            icon = '✓';
+            color = chalk.green;
+        }
+        else if (p.status === 'in-progress') {
+            icon = '→';
+            color = chalk.bold.cyan;
+        }
+        else {
+            icon = '○';
+            color = chalk.dim;
+        }
+        const extra = p.status === 'complete'
+            ? chalk.dim(` (${p.extractedComponents.length} components, ${p.extractedFunctions.length} functions, ${p.scenarioCount} scenarios)`)
+            : '';
+        console.log(`  ${color(`${icon} ${i + 1}. ${p.name}`)} ${chalk.dim(`(${p.route})`)}${extra}`);
+    }
+    if (state.sharedComponents.length > 0) {
+        console.log();
+        console.log(chalk.bold('Shared Components:'));
+        for (const sc of state.sharedComponents) {
+            console.log(`  ${chalk.cyan(sc.name)} ${chalk.dim(`— from ${sc.extractedFromPage}, used in: ${sc.usedInPages.join(', ')}`)}`);
+        }
+    }
+    console.log();
+}
+// ─── Migration Command Dispatcher ───────────────────────────────────
+function handleMigrateCommand(root, subArg) {
+    // No subcommand or explicit empty → run initial survey
+    if (!subArg) {
+        const migState = readMigrationState(root);
+        if (migState?.status === 'in-progress') {
+            // Already in progress — show status and resume hint
+            printMigrationStatus(root);
+            const page = migState.pages[migState.currentPageIndex];
+            if (page) {
+                const editorState = readState(root);
+                const currentStep = editorState?.migration ? editorState.step : 1;
+                console.log(chalk.green('Continue with: ') +
+                    chalk.bold(`codeyam editor migrate ${currentStep}`));
+                console.log();
+            }
+            return;
+        }
+        if (migState?.status === 'complete') {
+            console.log(chalk.green('Migration is complete! Use the normal feature workflow: `codeyam editor steps`'));
+            return;
+        }
+        printMigrateSurvey(root);
+        return;
+    }
+    // Parse subcommand
+    if (subArg === 'next') {
+        const result = advanceToNextPage(root);
+        if (!result) {
+            const migState = readMigrationState(root);
+            if (migState?.status === 'complete') {
+                console.log();
+                console.log(chalk.bold.green('🎉 Migration complete!'));
+                console.log();
+                const done = migState.pages.filter((p) => p.status === 'complete');
+                const totalComponents = done.reduce((sum, p) => sum + p.extractedComponents.length, 0);
+                const totalFunctions = done.reduce((sum, p) => sum + p.extractedFunctions.length, 0);
+                const totalScenarios = done.reduce((sum, p) => sum + p.scenarioCount, 0);
+                console.log(`  Pages migrated: ${done.length}`);
+                console.log(`  Components extracted: ${totalComponents}`);
+                console.log(`  Functions extracted: ${totalFunctions}`);
+                console.log(`  Scenarios created: ${totalScenarios}`);
+                console.log(`  Shared components: ${migState.sharedComponents.length}`);
+                console.log();
+                console.log(chalk.green('The project is fully migrated. Start building features: `codeyam editor steps`'));
+                console.log();
+            }
+            else {
+                console.log(chalk.red('No pending pages found. Run `codeyam editor migrate status` to check progress.'));
+            }
+            return;
+        }
+        // Start M1 for the next page
+        printMigrateStep1(root);
+        return;
+    }
+    if (subArg === 'status') {
+        printMigrationStatus(root);
+        return;
+    }
+    if (subArg === 'complete') {
+        const migState = readMigrationState(root);
+        if (!migState) {
+            console.error(chalk.red('Error: No migration in progress.'));
+            process.exit(1);
+        }
+        const page = migState.pages[migState.currentPageIndex];
+        if (!page) {
+            console.error(chalk.red('Error: No active migration page.'));
+            process.exit(1);
+        }
+        completePage(root, {
+            extractedComponents: page.extractedComponents,
+            extractedFunctions: page.extractedFunctions,
+            scenarioCount: page.scenarioCount,
+        });
+        console.log(chalk.green(`Page "${page.name}" marked complete.`));
+        return;
+    }
+    // Numeric step: 1-8
+    const step = parseInt(subArg, 10);
+    if (isNaN(step) || step < 1 || step > 10) {
+        console.error(chalk.red(`Error: Invalid migration step "${subArg}". Must be 1-10, "next", "complete", or "status".`));
+        process.exit(1);
+    }
+    // Ensure migration is active and first page started
+    const migState = readMigrationState(root);
+    if (!migState) {
+        console.error(chalk.red('Error: No migration state. Run `codeyam editor migrate` first.'));
+        process.exit(1);
+    }
+    // If still in survey state and step 1 requested, start first page
+    if (migState.status === 'surveyed' && step === 1) {
+        migState.status = 'in-progress';
+        migState.pages[0].status = 'in-progress';
+        migState.pages[0].startedAt = new Date().toISOString();
+        writeMigrationState(root, migState);
+    }
+    const stepFns = {
+        1: printMigrateStep1,
+        2: printMigrateStep2,
+        3: printMigrateStep3,
+        4: printMigrateStep4,
+        5: printMigrateStep5,
+        6: printMigrateStep6,
+        7: printMigrateStep7,
+        8: printMigrateStep8,
+        9: printMigrateStep9,
+        10: printMigrateStep10,
+    };
+    stepFns[step](root);
 }
-// ─── Step 11: Journal ─────────────────────────────────────────────────
-function printStep11(root, feature) {
-    const port = getServerPort();
+// ─── Step 16: Commit ─────────────────────────────────────────────────
+function printStep16(root, feature) {
     const prevState = readState(root);
-    const isResuming = prevState?.step === 11;
+    const isResuming = prevState?.step === 16;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 11,
-        label: STEP_LABELS[11],
+        step: 16,
+        label: STEP_LABELS[16],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 11, label: 'Journal', feature });
-    stepHeader(11, 'Journal', feature);
+    logEvent(root, 'step', { step: 16, label: 'Commit', feature });
+    stepHeader(16, 'Commit', feature);
     if (isResuming) {
-        printResumptionHeader(11);
+        printResumptionHeader(16);
     }
-    console.log('Create or update the journal entry for this feature.');
+    console.log('Commit all changes for this feature.');
     console.log();
     console.log(chalk.bold('Checklist:'));
-    checkbox('Write a concise description of what was built (2-3 sentences)');
-    checkbox(`First time at step 11 — create journal entry with ALL session screenshots:`);
-    console.log(chalk.dim(`    codeyam editor journal '{"title":"...","type":"feature","description":"...","includeSessionScenarios":true}'`));
-    console.log(chalk.dim('    includeSessionScenarios auto-discovers component + app + user persona screenshots'));
-    checkbox(`Returning to step 11 (before commit) — update the existing journal entry:`);
-    console.log(chalk.dim(`    codeyam editor journal-update '{"time":"<journal entry time>","description":"<updated>","includeSessionScenarios":true}'`));
-    console.log(chalk.dim('    Note: PATCH only works before the entry is committed. After commit, use POST to create a new entry.'));
-    console.log();
-    console.log(chalk.dim('Focus on creating or updating the journal entry. Summary and presentation happen in step 13.'));
-    stopGate(11);
+    checkbox('Ensure all screenshots are fresh: `codeyam editor recapture-stale`');
+    checkbox(`Hide the results panel: \`codeyam editor hide-results\``);
+    checkbox(`Git commit using the journal description: \`codeyam editor commit '{"message":"feat: <title>\\n\\n<journal description>"}'\``);
+    console.log(chalk.dim('    The commit message body MUST match the journal description exactly'));
+    stopGate(16);
 }
-// ─── Step 12: Review ──────────────────────────────────────────────────
-function printStep12(root, feature) {
-    const port = getServerPort();
+// ─── Step 17: Finalize ───────────────────────────────────────────────
+function printStep17(root, feature) {
     const prevState = readState(root);
-    const isResuming = prevState?.step === 12;
+    const isResuming = prevState?.step === 17;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 12,
-        label: STEP_LABELS[12],
+        step: 17,
+        label: STEP_LABELS[17],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 12, label: 'Review', feature });
-    stepHeader(12, 'Review', feature);
+    logEvent(root, 'step', { step: 17, label: 'Finalize', feature });
+    stepHeader(17, 'Finalize', feature);
     if (isResuming) {
-        printResumptionHeader(12);
+        printResumptionHeader(17);
     }
-    console.log('Verify all screenshots and checks pass before presenting to the user.');
+    console.log('Update the journal with the commit SHA and amend the commit.');
     console.log();
-    console.log(chalk.bold('Checklist (do all of this silently):'));
-    checkbox(`Refresh the preview: \`codeyam editor preview\``);
-    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\``);
-    checkbox('If `hasErrors` is true, fix them and re-capture affected scenarios');
-    checkbox('Run `codeyam editor verify-images \'{"paths":["/","/other-page"]}\'` with all page paths');
-    checkbox('Fix or remove any broken images before continuing');
-    checkbox('Run `codeyam editor audit` to verify completeness of scenarios and tests');
-    checkbox('Do not proceed until all checks pass');
-    stopGate(12);
+    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(17);
 }
-// ─── Step 13: Present ─────────────────────────────────────────────────
-function printStep13(root, feature) {
-    const port = getServerPort();
+// ─── Step 18: Push ───────────────────────────────────────────────────
+function printStep18(root, feature) {
     const prevState = readState(root);
-    const isResuming = prevState?.step === 13;
+    const isResuming = prevState?.step === 18;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 13,
-        label: STEP_LABELS[13],
+        step: 18,
+        label: STEP_LABELS[18],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 13, label: 'Present', feature });
-    stepHeader(13, 'Present', feature);
+    logEvent(root, 'step', { step: 18, label: 'Push', feature });
+    stepHeader(18, 'Push', feature);
     if (isResuming) {
-        printResumptionHeader(13);
+        printResumptionHeader(18);
     }
-    console.log('Present the results to the user and get their approval.');
+    console.log('Push the commit to the remote repository.');
     console.log();
     console.log(chalk.bold('Checklist:'));
-    checkbox('Fetch all scenarios: `codeyam editor scenarios`');
-    console.log(chalk.dim('    Each scenario has a `changeStatus` field: "new", "edited", "impacted", or null.'));
-    checkbox('Pick the best scenario to showcase from this working session:');
-    console.log(chalk.dim('    Prefer scenarios with changeStatus "new" or "edited" (directly changed in this session).'));
-    console.log(chalk.dim('    For app-level scenarios, prefer those showing the new/changed functionality.'));
-    console.log(chalk.dim('    NEVER pick a scenario with changeStatus null — those are unchanged from a previous commit.'));
-    checkbox('Switch the preview to that scenario using its `id`:');
-    console.log(chalk.dim(`    codeyam editor preview '{"scenarioId":"<id>"}'`));
-    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.'));
-    checkbox('Write a 1-2 sentence summary of what was built');
-    checkbox('Report test count and audit status (one line)');
-    console.log();
-    console.log(chalk.bold('Present a selection menu to the user (use AskUserQuestion):'));
-    console.log(chalk.green('    "Save & commit"') +
-        chalk.dim(' — git commit all changes and record in journal'));
-    console.log(chalk.yellow('    "I\'d like to make some changes"') +
-        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'));
+    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('Mark the current build task as complete');
+    checkbox('Create a new task with EXACTLY this title: "Ask the user what to build next, then run `codeyam editor 1` to start the next feature"');
+    console.log(chalk.dim('    There must ALWAYS be an active task. Never leave the task list empty.'));
+    console.log(chalk.dim('    This task reminds you to use the editor workflow for the next feature.'));
     console.log();
-    console.log(chalk.bold('If the user chooses "Make changes" (or asks for ANY change, even as a question):'));
-    checkbox(`Hide the results panel: \`codeyam editor hide-results\``);
-    checkbox('Ask what changes the user wants (if not already clear)');
-    checkbox(`Run: \`codeyam editor change "${feature}"\` — this gives you the change checklist`);
-    checkbox('THEN make the requested changes and follow the checklist');
-    console.log(chalk.red.bold('  IMPORTANT: Always run the change command BEFORE writing any code.'));
-    stopGate(13, { confirm: true });
+    console.log(chalk.bold.yellow('IMPORTANT: After this step, the current feature is DONE.'));
+    console.log(chalk.yellow('  Any new user request — even if it sounds related — is a NEW feature.'));
+    console.log(chalk.yellow('  Do NOT use `codeyam editor change` or start building directly.'));
+    console.log(chalk.yellow('  The next feature MUST start with `codeyam editor 1`.'));
+    console.log(chalk.yellow('  The change workflow is ONLY for modifications during steps 1-15, not after commit.'));
+    stopGate(18, { confirm: true });
 }
 // ─── Command definition ───────────────────────────────────────────────
 // ─── Analyze-imports subcommand ────────────────────────────────────────
@@ -1104,37 +2273,78 @@ 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.'));
+        console.error(chalk.dim('  Run codeyam editor 8 to create the glossary first.'));
         process.exit(1);
     }
     let glossaryEntries;
     try {
-        glossaryEntries = JSON.parse(fs.readFileSync(glossaryPath, 'utf8'));
+        const parsed = JSON.parse(fs.readFileSync(glossaryPath, 'utf8'));
+        glossaryEntries = sanitizeGlossaryEntries(parsed);
     }
     catch {
         console.error(chalk.red('Error: Could not parse .codeyam/glossary.json.'));
         process.exit(1);
     }
-    if (!Array.isArray(glossaryEntries) || glossaryEntries.length === 0) {
+    if (glossaryEntries.length === 0) {
         console.error(chalk.red('Error: glossary.json is empty.'));
         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.
+    // Use allFiles (not map values) to include ALL pages — multiple routes
+    // can share a page name (e.g., /feedback/[id] and /feedback/new both
+    // map to "Feedback") but each needs its own entity analysis.
+    const { scanPageFilePaths } = await import('../utils/entityChangeStatus.server.js');
+    const { allFiles: allPageFiles } = scanPageFilePaths(root);
+    for (const pageFile of allPageFiles) {
+        if (!filePaths.includes(pageFile)) {
+            filePaths.push(pageFile);
+        }
+    }
+    // Include file paths from editor scenarios (both component_path and
+    // page_file_path) so that all components and pages with scenarios get
+    // entities — critical for non-Next.js apps where scanPageFilePaths
+    // doesn't find page.tsx files.
+    try {
+        const { getDatabase } = await import('../../../packages/database/index.js');
+        const db = getDatabase();
+        const scenarioFiles = await db
+            .selectFrom('editor_scenarios')
+            .select(['component_path', 'page_file_path'])
+            .distinct()
+            .execute();
+        for (const row of scenarioFiles) {
+            const r = row;
+            for (const fp of [r.component_path, r.page_file_path]) {
+                if (fp && !filePaths.includes(fp)) {
+                    filePaths.push(fp);
+                }
+            }
+        }
+    }
+    catch {
+        // Non-fatal — scenario file paths just won't be included
+    }
     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,
         });
@@ -1151,8 +2361,11 @@ async function handleAnalyzeImports() {
     await initializeEnvironment();
     const entities = await loadEntities({});
     if (!entities || entities.length === 0) {
-        progress.fail('No entities found in database');
-        process.exit(1);
+        progress.succeed('No entities found in database yet — skipping import analysis. This is normal on the first feature.');
+        if (!options.silent) {
+            console.log(JSON.stringify({ imports: {}, entities: {} }));
+        }
+        return;
     }
     // Deduplicate to latest versions
     const latestByKey = new Map();
@@ -1166,7 +2379,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 = {};
@@ -1204,11 +2417,270 @@ 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 }));
+    }
+    // Backfill entity_sha on scenarios registered before entities existed.
+    // This fixes the "missing data" UI state when scenarios were registered
+    // while analyze-imports was still running in the background.
+    try {
+        const { getDatabase } = await import('../../../packages/database/index.js');
+        const db = getDatabase();
+        const backfillResult = await backfillEntityShaOnScenarios(db, latestEntities.map((e) => ({
+            sha: e.sha,
+            name: e.name,
+            filePath: e.filePath || '',
+            isDefaultExport: e.metadata?.notExported === false &&
+                e.metadata?.namedExport === false,
+        })));
+        if (backfillResult.updated > 0 && !options.silent) {
+            console.log(chalk.green(`Linked ${backfillResult.updated} scenario(s) to their entities.`));
+        }
+    }
+    catch {
+        /* non-fatal */
+    }
+}
+// ─── Validate-seed subcommand ─────────────────────────────────────────
+/**
+ * Validate seed data structure and check for a seed adapter.
+ * Usage: codeyam editor validate-seed '{"products":[...]}'
+ */
+function handleValidateSeed(jsonArg) {
+    const root = process.cwd();
+    // Check for seed adapter
+    const adapterPath = detectSeedAdapter(root);
+    if (adapterPath) {
+        console.log(chalk.green(`Seed adapter found: ${adapterPath}`));
+    }
+    else {
+        console.log(chalk.yellow('No seed adapter found. Create .codeyam/seed-adapter.ts to use seed-based scenarios.'));
+    }
+    if (!jsonArg) {
+        return;
+    }
+    let data;
+    try {
+        data = JSON.parse(jsonArg);
+    }
+    catch {
+        console.error(chalk.red('Error: Invalid JSON.'));
+        process.exit(1);
+    }
+    const result = validateSeedData(data);
+    if (result.valid) {
+        const tables = Object.keys(data);
+        const totalRows = tables.reduce((sum, t) => sum + (Array.isArray(data[t]) ? data[t].length : 0), 0);
+        console.log(chalk.green(`Seed data valid: ${tables.length} table(s), ${totalRows} total row(s)`));
+        for (const table of tables) {
+            const rows = Array.isArray(data[table])
+                ? data[table].length
+                : 0;
+            console.log(chalk.dim(`  ${table}: ${rows} row(s)`));
+        }
+        // Check seed keys against Prisma schema if available
+        const schemaPath = path.join(root, 'prisma', 'schema.prisma');
+        try {
+            if (fs.existsSync(schemaPath)) {
+                const schemaContent = fs.readFileSync(schemaPath, 'utf-8');
+                const warnings = validateSeedKeysAgainstPrisma(tables, schemaContent);
+                if (warnings.length > 0) {
+                    console.log();
+                    console.log(chalk.yellow('Prisma model name warnings:'));
+                    for (const w of warnings) {
+                        console.log(chalk.yellow(`  ⚠ ${w}`));
+                    }
+                }
+            }
+        }
+        catch {
+            // Schema not readable — skip Prisma validation
+        }
+    }
+    else {
+        console.error(chalk.red('Seed data validation failed:'));
+        for (const err of result.errors) {
+            console.error(chalk.red(`  - ${err}`));
+        }
+        process.exit(1);
+    }
+}
+// ─── Delete subcommand ────────────────────────────────────────────────
+/**
+ * `codeyam editor delete <scenarioId>`
+ *
+ * Delete a scenario by ID via the running editor server.
+ */
+async function handleDelete(scenarioId) {
+    if (!scenarioId) {
+        console.error(chalk.red('Error: Missing scenario ID. Usage: codeyam editor delete <scenarioId>'));
+        process.exit(1);
+    }
+    const port = getServerPort();
+    const result = await deleteScenarioViaCli(scenarioId, port);
+    if (result.success) {
+        console.log(chalk.green(result.message));
+    }
+    else {
+        console.error(chalk.red(result.message));
+        process.exit(1);
+    }
+}
+// ─── Isolate subcommand ───────────────────────────────────────────────
+/**
+ * `codeyam editor isolate "StarRating CategoryBadge DrinkCard"`
+ *
+ * Creates isolation route directories and the layout guard file.
+ * This avoids brace-expansion permission prompts in the embedded terminal.
+ */
+function handleIsolate(componentNames) {
+    const root = process.cwd();
+    if (componentNames.length === 0) {
+        console.error(chalk.red('Usage: codeyam editor isolate "ComponentA ComponentB ..."'));
+        process.exit(1);
+    }
+    const isolateDir = path.join(root, 'app', 'isolated-components');
+    // Create layout.tsx with production guard if missing
+    const layoutPath = path.join(isolateDir, 'layout.tsx');
+    if (!fs.existsSync(layoutPath)) {
+        fs.mkdirSync(isolateDir, { recursive: true });
+        fs.writeFileSync(layoutPath, [
+            'import { notFound } from "next/navigation";',
+            '',
+            'export default function CaptureLayout({ children }: { children: React.ReactNode }) {',
+            '  if (process.env.NODE_ENV === "production") notFound();',
+            '  return <>{children}</>;',
+            '}',
+            '',
+        ].join('\n'), 'utf8');
+        console.log(chalk.green(`Created layout guard: app/isolated-components/layout.tsx`));
+    }
+    // Create a directory for each component
+    const created = [];
+    const existed = [];
+    for (const name of componentNames) {
+        const dir = path.join(isolateDir, name);
+        if (fs.existsSync(dir)) {
+            existed.push(name);
+        }
+        else {
+            fs.mkdirSync(dir, { recursive: true });
+            created.push(name);
+        }
+    }
+    if (created.length > 0) {
+        console.log(chalk.green(`Created ${created.length} isolation route dir(s): ${created.join(', ')}`));
+    }
+    if (existed.length > 0) {
+        console.log(chalk.dim(`Already existed: ${existed.join(', ')}`));
+    }
 }
 // ─── Register subcommand ──────────────────────────────────────────────
+/**
+ * Format API subcommand results as concise one-line summaries.
+ * Prevents Claude from piping output to python3 just to extract key fields.
+ * Returns null for subcommands that should keep raw JSON output.
+ */
+function formatApiSubcommandResult(subcommand, data) {
+    if (!data || typeof data !== 'object')
+        return null;
+    switch (subcommand) {
+        case 'journal': {
+            const parts = [`success=${data.success}`];
+            if (data.entry?.time)
+                parts.push(`time="${data.entry.time}"`);
+            if (data.entry?.title)
+                parts.push(`title="${data.entry.title}"`);
+            if (data.scenarioScreenshotsFound != null) {
+                parts.push(`screenshots=${data.scenarioScreenshotsFound}`);
+            }
+            return parts.join(' ');
+        }
+        case 'journal-update': {
+            const parts = [`success=${data.success}`];
+            if (data.entry?.time)
+                parts.push(`time="${data.entry.time}"`);
+            if (data.scenarioScreenshotsFound != null) {
+                parts.push(`screenshots=${data.scenarioScreenshotsFound}`);
+            }
+            return parts.join(' ');
+        }
+        case 'commit': {
+            const parts = [`success=${data.success}`];
+            if (data.sha)
+                parts.push(`sha=${data.sha}`);
+            if (data.message)
+                parts.push(`message="${data.message.split('\n')[0]}"`);
+            return parts.join(' ');
+        }
+        case 'preview': {
+            const parts = [
+                `success=${!!data.ok || data.success !== false}`,
+            ];
+            if (data.path)
+                parts.push(`path="${data.path}"`);
+            if (data.scenarioId)
+                parts.push(`scenarioId="${data.scenarioId}"`);
+            if (data.sessionsNotified != null)
+                parts.push(`notified=${data.sessionsNotified}`);
+            return parts.join(' ');
+        }
+        case 'dev-server': {
+            if (data.status) {
+                const parts = [`status=${data.status}`, `pid=${data.pid || 'none'}`];
+                if (data.url)
+                    parts.push(`url=${data.url}`);
+                if (data.proxyUrl)
+                    parts.push(`proxyUrl=${data.proxyUrl}`);
+                if (data.errorMessage)
+                    parts.push(`error: ${data.errorMessage}`);
+                return parts.join(' ');
+            }
+            return null;
+        }
+        case 'client-errors': {
+            const parts = [`hasErrors=${data.hasErrors}`];
+            parts.push(`totalErrors=${data.totalErrors ?? 0}`);
+            if (data.livePreview) {
+                const lp = data.livePreview;
+                parts.push(`livePreview=${lp.loaded ? 'loaded' : 'not-loaded'}`);
+                if (lp.loaded) {
+                    parts.push(`hasContent=${lp.hasContent}`);
+                }
+                const liveErrors = lp.errors?.length ?? 0;
+                parts.push(`liveErrors=${liveErrors}`);
+                if (liveErrors > 0) {
+                    // Show first few error messages for context
+                    for (const err of lp.errors.slice(0, 3)) {
+                        parts.push(`  error: ${err.message}`);
+                    }
+                }
+            }
+            else {
+                parts.push('livePreview=not-loaded');
+            }
+            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
+    }
+}
 /**
  * `codeyam editor register '{"name":"...","componentName":"...",...}'`
  *
@@ -1217,40 +2689,158 @@ async function handleAnalyzeImports() {
  */
 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":"/codeyam-isolate/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);
     }
-    let body;
-    try {
-        body = JSON.parse(jsonArg);
-    }
-    catch {
-        console.error(chalk.red('Error: Invalid JSON.'));
-        console.error(chalk.dim(`  Received: ${jsonArg.slice(0, 200)}`));
+    const parsed = parseRegisterArg(jsonArg);
+    if (parsed.error) {
+        console.error(chalk.red(`Error: ${parsed.error}`));
+        if (parsed.error === 'Invalid JSON') {
+            console.error(chalk.dim(`  Received: ${jsonArg.slice(0, 200)}`));
+        }
         process.exit(1);
     }
+    // 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();
-        console.log(JSON.stringify(data, null, 2));
-        if (!res.ok) {
-            process.exit(1);
+    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) {
+                if (data.seedResult.success) {
+                    parts.push(`seed=ok`);
+                }
+                else {
+                    parts.push(chalk.red(`seed=FAILED${data.seedResult.error ? ` (${data.seedResult.error})` : ''}`));
+                }
+            }
+            if (data.captureError)
+                parts.push(chalk.yellow(`captureError="${data.captureError}"`));
+            console.log(prefix + parts.join(' '));
+            // Warn when application scenario is missing seed data
+            if (data.missingSeedWarning) {
+                console.log(chalk.red.bold('WARNING: No seed data in this application scenario!'));
+                console.log(chalk.yellow('  This scenario has type "application" but no "seed" data was provided.'));
+                console.log(chalk.yellow('  The page will render with an empty database — nothing will be visible.'));
+                console.log(chalk.yellow('  Re-register with "seed":{...} containing the database rows this page needs.'));
+            }
+            // Surface client errors prominently so they can't be missed
+            if (data.clientErrors && data.clientErrors.length > 0) {
+                console.log(chalk.red.bold(`⚠ WARNING: ${data.clientErrors.length} client error${data.clientErrors.length !== 1 ? 's' : ''} detected during capture:`));
+                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.'));
+                // Provide actionable debugging hints for HTTP/API errors
+                const hasApiResponseError = data.clientErrors.some((e) => e.includes('API response error:'));
+                const hasHttpError = data.clientErrors.some((e) => e.includes('HTTP error:'));
+                if (hasHttpError || hasApiResponseError) {
+                    console.log(chalk.yellow('  To debug: look at the "API response error" lines above — they show the exact API endpoint'));
+                    console.log(chalk.yellow('  that failed and what the server returned. Then check the scenario seed data to ensure'));
+                    console.log(chalk.yellow('  all IDs referenced in the URL exist in the seed, and that the route is correct.'));
+                }
+                console.log(chalk.yellow('  Fix the issue and re-register this scenario.'));
+            }
+            if (!res.ok) {
+                console.error(chalk.dim(JSON.stringify(data, null, 2)));
+                failed++;
+            }
+            else {
+                succeeded++;
+            }
         }
+        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++;
+        }
+    }
+    if (isBatch) {
+        console.log(chalk.dim(`\nBatch complete: ${succeeded}/${items.length} succeeded`));
+    }
+    if (failed > 0) {
+        process.exit(1);
+    }
+}
+// ─── Glossary-add subcommand ──────────────────────────────────────────
+/**
+ * `codeyam editor glossary-add '{"name":"...", "filePath":"...", "description":"..."}'`
+ *
+ * Safely adds/updates entries in .codeyam/glossary.json via the CLI,
+ * avoiding hand-editing that breaks on unicode characters.
+ */
+async function handleGlossaryAdd(jsonArg) {
+    if (!jsonArg) {
+        console.error(chalk.red('Error: JSON argument required.'));
+        console.error(chalk.dim('  Usage: codeyam editor glossary-add \'{"name":"DrinkCard","filePath":"app/components/DrinkCard.tsx","description":"Displays a drink item"}\''));
+        console.error(chalk.dim('  For large payloads: codeyam editor glossary-add @.codeyam/tmp/entry.json'));
+        process.exit(1);
+    }
+    const parsed = parseRegisterArg(jsonArg);
+    if (parsed.error) {
+        console.error(chalk.red(`Error: ${parsed.error}`));
+        process.exit(1);
     }
-    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'));
+    // Normalize to array
+    const items = Array.isArray(parsed.body) ? parsed.body : [parsed.body];
+    // Read existing glossary
+    const root = getProjectRoot();
+    const glossaryPath = path.join(root, '.codeyam', 'glossary.json');
+    let existing = [];
+    try {
+        const raw = JSON.parse(fs.readFileSync(glossaryPath, 'utf8'));
+        existing = sanitizeGlossaryEntries(raw);
+    }
+    catch {
+        // Glossary doesn't exist yet or can't be parsed — start fresh
+    }
+    // Merge
+    const { validateGlossaryEntry, mergeGlossaryEntries } = await import('../utils/glossaryAdd.js');
+    const result = mergeGlossaryEntries(existing, items);
+    // Report validation errors
+    for (const err of result.errors) {
+        console.error(chalk.red(`Error at index ${err.index}: ${err.message}`));
+    }
+    if (result.added === 0 && result.updated === 0 && result.errors.length > 0) {
         process.exit(1);
     }
+    // Write back with utf8 encoding to safely handle unicode
+    fs.mkdirSync(path.dirname(glossaryPath), { recursive: true });
+    fs.writeFileSync(glossaryPath, JSON.stringify(result.entries, null, 2), 'utf8');
+    console.log(`added=${result.added} updated=${result.updated} total=${result.entries.length}`);
 }
 // ─── Dependents subcommand ────────────────────────────────────────────
 /**
@@ -1269,11 +2859,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());
@@ -1360,15 +2962,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 15+, this loops back to step 15 (present). When called from an
+ * earlier step, it returns to that step so the normal flow continues.
  */
 function handleChange(feature) {
     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;
         }
@@ -1378,6 +2981,7 @@ function handleChange(feature) {
             process.exit(1);
         }
     }
+    const currentStep = state?.step ?? 15;
     const port = getServerPort();
     console.log();
     console.log(chalk.bold.cyan('━━━ Change Loop ━━━'));
@@ -1385,9 +2989,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:'));
@@ -1395,8 +3009,8 @@ 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","description":"...","componentName":"ComponentName","componentPath":"app/components/ComponentName.tsx"}'`));
-    checkbox('For any NEW components, create isolation routes and register scenarios');
+    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:'));
     checkbox('Re-run test files for any functions you modified');
@@ -1406,15 +3020,31 @@ 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('If component changes affect app-level pages, re-register affected app scenarios');
-    checkbox(`Use \`codeyam editor dependents ComponentName\` to find what needs recapturing`);
+    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');
+    console.log(chalk.dim('    Shared components (headers, navbars, layouts) affect MANY pages — re-register all of them.'));
+    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.'));
+    console.log(chalk.dim('    If the enriched data makes the scenario name too narrow, rename it to reflect its broader coverage.'));
+    checkbox('After each re-registration, view the screenshot to verify data is visible');
+    console.log(chalk.dim("    If the screenshot doesn't show the data you put in, the scenario is broken."));
     console.log();
     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('Recapture stale scenarios: `codeyam editor recapture-stale`');
     checkbox('Run `codeyam editor audit` — all checks must pass');
     checkbox(`Check for client-side errors: \`codeyam editor client-errors\``);
+    console.log(chalk.dim('    If `hasContent=false`, the preview is blank — fix the code before proceeding.'));
+    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`');
@@ -1423,11 +3053,171 @@ 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.bold.green('When all checks pass, run: ') +
-        chalk.bold(`codeyam editor 13`));
-    console.log(chalk.dim('  This enters the present step to show the updated results to the user.'));
+    // If the change was initiated from a step before 15, return to that step
+    // instead of jumping to step 15. The change workflow should only loop to
+    // step 15 when changes are requested FROM step 15.
+    if (currentStep < 15) {
+        console.log(chalk.red('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+        console.log(chalk.red.bold('  REQUIRED: Return to current step'));
+        console.log(chalk.red.bold('  When all checks pass, you MUST run: ') +
+            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 15`));
+        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 ─────────────────────────────────────────────────────
+/**
+ * Fetch the audit result from the server.
+ * Returns null if the server is unreachable.
+ */
+async function fetchAuditResult() {
+    const port = getServerPort();
+    try {
+        const res = await fetch(`http://localhost:${port}/api/editor-audit`);
+        if (!res.ok)
+            return null;
+        return await res.json();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Silently check whether the audit passes. Returns true if allPassing,
+ * false if any issues remain or the server is unreachable.
+ * Used as a hard gate before steps 8+.
+ *
+ * Auto-runs analyze-imports if the only failure is incomplete entities,
+ * then re-checks once.
+ */
+async function checkAuditGate() {
+    const data = await fetchAuditResult();
+    if (!data)
+        return true; // Server unreachable — don't block
+    if (data.summary?.allPassing === true)
+        return true;
+    // If incomplete entities are the only issue, auto-fix with analyze-imports (once)
+    const { isAutoRemediable } = await import('../utils/editorAudit.js');
+    if (isAutoRemediable(data.summary, false)) {
+        try {
+            await handleAnalyzeImports({ silent: true });
+        }
+        catch {
+            return false;
+        }
+        // Re-check after fix
+        const retry = await fetchAuditResult();
+        if (retry?.summary?.allPassing === true)
+            return true;
+    }
+    // Print specific failures so Claude knows what to fix without running audit separately
+    printAuditGateFailures(data);
+    return false;
+}
+/**
+ * Print a concise summary of audit failures for the gate block message.
+ * This gives Claude immediate context about what to fix without needing
+ * to run `codeyam editor audit` as a separate step.
+ */
+function printAuditGateFailures(data) {
+    const s = data.summary;
+    if (!s)
+        return;
+    const issues = [];
+    if (s.componentsMissing > 0) {
+        issues.push(`${s.componentsMissing} component(s) missing scenarios`);
+        const missing = (data.components || []).filter((c) => c.status === 'missing');
+        for (const c of missing) {
+            issues.push(`    → ${c.name}${c.filePath ? ` (${c.filePath})` : ''}`);
+        }
+    }
+    if (s.componentsWithErrors > 0) {
+        issues.push(`${s.componentsWithErrors} component(s) with client errors (browser API or runtime errors in captured scenarios)`);
+        const withErrors = (data.components || []).filter((c) => c.status === 'has_errors');
+        for (const c of withErrors) {
+            issues.push(`    → ${c.name}${c.filePath ? ` (${c.filePath})` : ''}`);
+        }
+    }
+    if (s.functionsMissing > 0) {
+        issues.push(`${s.functionsMissing} function(s) missing test files`);
+        const missing = (data.functions || []).filter((f) => f.status === 'missing');
+        for (const f of missing) {
+            issues.push(`    → ${f.name}${f.filePath ? ` (${f.filePath})` : ''}`);
+        }
+    }
+    if (s.functionsFailing > 0) {
+        issues.push(`${s.functionsFailing} function(s) with failing tests`);
+        const failing = (data.functions || []).filter((f) => f.status === 'failing');
+        for (const f of failing) {
+            issues.push(`    → ${f.name}${f.testFile ? ` (${f.testFile})` : ''}`);
+        }
+    }
+    if (s.functionsRunnerError > 0) {
+        issues.push(`${s.functionsRunnerError} function(s) with test runner errors (the runner crashed — not a test failure)`);
+        const runnerErrors = (data.functions || []).filter((f) => f.status === 'runner_error');
+        for (const f of runnerErrors) {
+            issues.push(`    → ${f.name}${f.testFile ? ` (${f.testFile})` : ''}`);
+        }
+    }
+    if (s.functionsNameMismatch > 0) {
+        issues.push(`${s.functionsNameMismatch} function(s) with test name mismatch`);
+        const mismatch = (data.functions || []).filter((f) => f.status === 'name_mismatch');
+        for (const f of mismatch) {
+            issues.push(`    → ${f.name}${f.testFile ? ` (${f.testFile})` : ''}`);
+        }
+    }
+    if (s.missingFromGlossary > 0)
+        issues.push(`${s.missingFromGlossary} file(s) with scenarios not in glossary`);
+    if (s.incompleteEntities > 0) {
+        const preCount = s.preExistingIncompleteEntities || 0;
+        if (preCount > 0 && preCount === s.incompleteEntities) {
+            issues.push(`${s.incompleteEntities} entity/entities need import analysis (pre-existing — not caused by your current changes, but must be fixed before proceeding)`);
+        }
+        else if (preCount > 0) {
+            issues.push(`${s.incompleteEntities} entity/entities need import analysis (${preCount} pre-existing — not from your changes)`);
+        }
+        else {
+            issues.push(`${s.incompleteEntities} entity/entities need import analysis`);
+        }
+    }
+    if (s.miscategorizedScenarios > 0)
+        issues.push(`${s.miscategorizedScenarios} component(s) using page URLs instead of isolation routes`);
+    if (s.scenariosNeedingRecapture > 0)
+        issues.push(`${s.scenariosNeedingRecapture} scenario(s) need recapture (dependency tree changed)`);
+    if (issues.length > 0) {
+        console.error(chalk.yellow('\nAudit failures:'));
+        for (const issue of issues) {
+            console.error(chalk.yellow(`  • ${issue}`));
+        }
+    }
+    // Surface client error details inline — these are the most common cause of
+    // Claude looping because the errors require code fixes, not audit re-runs.
+    if (data.components) {
+        const withErrors = data.components.filter((c) => c.status === 'has_errors' && c.clientErrors?.length > 0);
+        if (withErrors.length > 0) {
+            console.error(chalk.yellow('\nClient errors found:'));
+            for (const c of withErrors) {
+                console.error(chalk.red(`  ${c.name}:`));
+                for (const err of c.clientErrors.slice(0, 3)) {
+                    console.error(chalk.red(`    → ${err}`));
+                }
+                if (c.clientErrors.length > 3) {
+                    console.error(chalk.dim(`    … and ${c.clientErrors.length - 3} more`));
+                }
+            }
+            console.error(chalk.yellow('\nFix: Fix the code errors above, then re-capture the affected scenarios.'));
+        }
+    }
+    console.error(chalk.dim('\nRun `codeyam editor audit` for full details.\n'));
+}
 // ─── Audit subcommand ────────────────────────────────────────────────
 /**
  * `codeyam editor audit`
@@ -1437,35 +3227,82 @@ function handleChange(feature) {
  * have test files. Exits with code 1 if anything is missing.
  */
 async function handleAudit() {
-    const port = getServerPort();
-    const url = `http://localhost:${port}/api/editor-audit`;
-    let data;
-    try {
-        const res = await fetch(url);
-        if (!res.ok) {
-            console.error(chalk.red(`Error: Audit endpoint returned ${res.status}`));
-            process.exit(1);
-        }
-        data = await res.json();
-    }
-    catch (err) {
+    let data = await fetchAuditResult();
+    if (!data) {
         console.error(chalk.red('Error: Could not reach the CodeYam server. Is it running?'));
-        console.error(chalk.dim(`  ${err.message}`));
         process.exit(1);
     }
+    // Auto-fix incomplete entities — but only once.
+    // If analyze-imports runs and entities are STILL incomplete, report clearly
+    // instead of retrying. The analysis may have errors (e.g., stale entity
+    // references from refactoring) that can't be fixed by re-running.
+    const incompleteBeforeFix = data.incompleteEntities || [];
+    let autoRemediationFailed = false;
+    if (incompleteBeforeFix.length > 0) {
+        console.log(chalk.dim(`Running import analysis for ${incompleteBeforeFix.length} incomplete entit${incompleteBeforeFix.length !== 1 ? 'ies' : 'y'}...`));
+        try {
+            await handleAnalyzeImports({ silent: true });
+        }
+        catch {
+            // Fall through — the audit will still report them as incomplete
+        }
+        // Re-fetch audit results after the fix
+        data = await fetchAuditResult();
+        if (!data) {
+            console.error(chalk.red('Error: Could not reach the CodeYam server after analyze-imports.'));
+            process.exit(1);
+        }
+        // If entities are still incomplete after running analyze-imports,
+        // flag it so we can show a clear message instead of looping
+        const incompleteAfterFix = data.incompleteEntities || [];
+        if (incompleteAfterFix.length > 0) {
+            autoRemediationFailed = true;
+        }
+    }
     const { components, functions, summary } = data;
     console.log();
     console.log(chalk.bold.cyan('━━━ Editor Audit ━━━'));
     console.log();
     // Components
     if (components.length > 0) {
+        // Build name frequency map for disambiguation
+        const componentNameCounts = new Map();
+        for (const c of components) {
+            componentNameCounts.set(c.name, (componentNameCounts.get(c.name) || 0) + 1);
+        }
         console.log(chalk.bold('Components (scenarios):'));
         for (const c of components) {
-            const icon = c.status === 'ok' ? chalk.green('✓') : chalk.red('✗');
-            const count = c.status === 'ok'
-                ? chalk.dim(` (${c.scenarioCount} scenario${c.scenarioCount !== 1 ? 's' : ''})`)
-                : chalk.red(' — no scenarios registered');
-            console.log(`  ${icon} ${c.name}${count}`);
+            const icon = c.status === 'ok'
+                ? chalk.green('✓')
+                : c.status === 'needs_recapture'
+                    ? chalk.yellow('↻')
+                    : chalk.red('✗');
+            let detail;
+            if (c.status === 'has_errors') {
+                detail = chalk.red(` — ${c.scenarioCount} scenario${c.scenarioCount !== 1 ? 's' : ''} but has client errors`);
+            }
+            else if (c.status === 'needs_recapture') {
+                detail = chalk.yellow(` — ${c.scenarioCount} scenario${c.scenarioCount !== 1 ? 's' : ''}, needs recapture`);
+            }
+            else if (c.status === 'ok') {
+                detail = chalk.dim(` (${c.scenarioCount} scenario${c.scenarioCount !== 1 ? 's' : ''})`);
+            }
+            else {
+                detail = chalk.red(' — no scenarios registered');
+            }
+            // Show file path for failing components always, for OK only when name is ambiguous
+            const isDuplicate = (componentNameCounts.get(c.name) || 0) > 1;
+            const showPath = (c.status !== 'ok' && c.status !== 'needs_recapture') || isDuplicate;
+            const pathSuffix = showPath && c.filePath ? chalk.dim(` (${c.filePath})`) : '';
+            console.log(`  ${icon} ${c.name}${pathSuffix}${detail}`);
+            if (c.clientErrors && c.clientErrors.length > 0) {
+                for (const err of c.clientErrors.slice(0, 3)) {
+                    console.log(chalk.red(`      → ${err}`));
+                }
+                if (c.clientErrors.length > 3) {
+                    console.log(chalk.dim(`      … and ${c.clientErrors.length - 3} more`));
+                }
+            }
         }
         console.log();
     }
@@ -1479,6 +3316,14 @@ async function handleAudit() {
                 case 'ok':
                     detail = chalk.dim(` (${f.testFile})`);
                     break;
+                case 'runner_error':
+                    detail = chalk.red(` — test runner crashed: ${f.testFile}`);
+                    if (f.errorMessage) {
+                        detail += `\n      ${chalk.red(f.errorMessage)}`;
+                        detail += `\n      ${chalk.yellow('Note: This is NOT a test failure — the test runner itself could not execute.')}`;
+                        detail += `\n      ${chalk.yellow('Try running the test manually: npx vitest run ' + f.testFile)}`;
+                    }
+                    break;
                 case 'failing':
                     detail = chalk.red(` — tests failing: ${f.testFile}`);
                     break;
@@ -1496,6 +3341,77 @@ async function handleAudit() {
         }
         console.log();
     }
+    // Missing from glossary
+    const missingFromGlossary = data.missingFromGlossary || [];
+    if (missingFromGlossary.length > 0) {
+        console.log(chalk.bold('Missing from glossary:'));
+        for (const m of missingFromGlossary) {
+            console.log(`  ${chalk.red('✗')} ${m.name} ${chalk.dim(`(${m.filePath})`)} — ${m.scenarioCount} scenario${m.scenarioCount !== 1 ? 's' : ''} but not in glossary`);
+        }
+        console.log(chalk.yellow('    Add these to .codeyam/glossary.json and run `codeyam editor analyze-imports`'));
+        console.log();
+    }
+    // Incomplete entities (scenarios without analyses)
+    const incompleteEntities = data.incompleteEntities || [];
+    if (incompleteEntities.length > 0) {
+        console.log(chalk.bold('Incomplete entities (need import analysis):'));
+        for (const e of incompleteEntities) {
+            console.log(`  ${chalk.red('✗')} ${e.name} — ${e.scenarioCount} scenario${e.scenarioCount !== 1 ? 's' : ''} but entity not analyzed`);
+        }
+        if (autoRemediationFailed) {
+            console.log(chalk.red('    analyze-imports was run automatically but these entities are STILL incomplete.'));
+            console.log(chalk.red('    DO NOT re-run analyze-imports or the audit in a loop — the result will be the same.'));
+            console.log(chalk.yellow('    This means the analysis failed for these entities. Common causes:'));
+            console.log(chalk.yellow('      • Source file was renamed/deleted but glossary still references the old path'));
+            console.log(chalk.yellow('      • Entity has import errors that prevent analysis'));
+            console.log(chalk.yellow('    To investigate: run `codeyam editor analyze-imports` (without --silent) to see the full error.'));
+        }
+        else {
+            console.log(chalk.yellow('    Run `codeyam editor analyze-imports` to analyze these entities'));
+        }
+        console.log();
+    }
+    // Miscategorized scenarios (component scenarios using real page URLs)
+    const miscategorizedScenarios = data.miscategorizedScenarios || [];
+    if (miscategorizedScenarios.length > 0) {
+        console.log(chalk.bold('Miscategorized scenarios (component with page URL):'));
+        for (const m of miscategorizedScenarios) {
+            console.log(`  ${chalk.red('✗')} ${m.componentName} at ${chalk.dim(m.url)} — ${m.scenarioNames.length} scenario${m.scenarioNames.length !== 1 ? 's' : ''}`);
+            for (const name of m.scenarioNames) {
+                console.log(chalk.dim(`      "${name}"`));
+            }
+        }
+        console.log(chalk.yellow('    Component scenarios must use isolation routes (/isolated-components/...).'));
+        console.log(chalk.yellow('    Either re-register as app scenarios (remove componentName, add pageFilePath)'));
+        console.log(chalk.yellow('    or re-register with an isolation URL.'));
+        console.log();
+    }
+    // Scenarios needing recapture (entity or dependency tree changed)
+    const scenariosNeedingRecapture = data.scenariosNeedingRecapture || [];
+    if (scenariosNeedingRecapture.length > 0) {
+        console.log(chalk.bold('Scenarios needing recapture (dependency tree changed):'));
+        for (const s of scenariosNeedingRecapture) {
+            const reason = s.status.status === 'impacted' && s.status.impactedBy?.length
+                ? `impacted by: ${s.status.impactedBy.map((d) => `${d.name} [${d.changeType}]`).join(', ')}`
+                : `${s.status.status}`;
+            console.log(`  ${chalk.red('✗')} ${s.scenarioName} ${chalk.dim(`(${s.entityName} — ${reason})`)}`);
+        }
+        console.log(chalk.yellow('    Run: codeyam editor recapture-stale'));
+        console.log();
+    }
+    // Duplicate glossary names (warning, not a failure)
+    const duplicateNames = data.duplicateNames || [];
+    if (duplicateNames.length > 0) {
+        console.log(chalk.bold('Duplicate names in glossary (confusing for audit):'));
+        for (const dn of duplicateNames) {
+            console.log(`  ${chalk.yellow('⚠')} "${dn.name}" appears ${dn.filePaths.length} times:`);
+            for (const fp of dn.filePaths) {
+                console.log(`      ${fp}`);
+            }
+        }
+        console.log(chalk.yellow('    Fix: remove duplicate entries or rename them to be unique in .codeyam/glossary.json'));
+        console.log();
+    }
     // Summary
     const allOk = summary.allPassing;
     if (allOk) {
@@ -1507,21 +3423,153 @@ async function handleAudit() {
         if (summary.componentsMissing > 0) {
             parts.push(`${summary.componentsMissing} component${summary.componentsMissing !== 1 ? 's' : ''} missing scenarios`);
         }
+        if (summary.componentsWithErrors > 0) {
+            parts.push(`${summary.componentsWithErrors} component${summary.componentsWithErrors !== 1 ? 's' : ''} with client errors`);
+        }
         if (summary.functionsMissing > 0) {
             parts.push(`${summary.functionsMissing} function${summary.functionsMissing !== 1 ? 's' : ''} missing tests`);
         }
         if (summary.functionsFailing > 0) {
             parts.push(`${summary.functionsFailing} function${summary.functionsFailing !== 1 ? 's' : ''} with failing tests`);
         }
+        if (summary.functionsRunnerError > 0) {
+            parts.push(`${summary.functionsRunnerError} function${summary.functionsRunnerError !== 1 ? 's' : ''} with test runner errors (not test failures — see details above)`);
+        }
         if (summary.functionsNameMismatch > 0) {
             parts.push(`${summary.functionsNameMismatch} function${summary.functionsNameMismatch !== 1 ? 's' : ''} with test name mismatch (missing top-level describe)`);
         }
+        if (summary.missingFromGlossary > 0) {
+            parts.push(`${summary.missingFromGlossary} file${summary.missingFromGlossary !== 1 ? 's' : ''} with scenarios not in glossary`);
+        }
+        if (summary.incompleteEntities > 0) {
+            parts.push(`${summary.incompleteEntities} entit${summary.incompleteEntities !== 1 ? 'ies' : 'y'} need import analysis`);
+        }
+        if (summary.miscategorizedScenarios > 0) {
+            parts.push(`${summary.miscategorizedScenarios} component${summary.miscategorizedScenarios !== 1 ? 's' : ''} using page URLs instead of isolation routes`);
+        }
+        if (summary.scenariosNeedingRecapture > 0) {
+            parts.push(`${summary.scenariosNeedingRecapture} scenario${summary.scenariosNeedingRecapture !== 1 ? 's' : ''} need recapture`);
+        }
         console.log(chalk.red.bold('Audit failed: ') + parts.join(', '));
     }
     console.log();
     if (!allOk) {
         process.exit(1);
     }
+    // Auto-run analyze-imports when audit passes — this builds the import graph
+    // so the App tab can show component/function dependencies for each page.
+    // Previously this was a manual step that Claude had to remember to run.
+    console.log(chalk.dim('Building import graph...'));
+    try {
+        await handleAnalyzeImports({ silent: true });
+    }
+    catch {
+        // Non-fatal — audit passed, import graph is a bonus
+        console.log(chalk.yellow('Warning: Could not build import graph. Run `codeyam editor analyze-imports` manually.'));
+    }
+}
+// ─── Recapture-stale subcommand ────────────────────────────────────────
+/**
+ * `codeyam editor recapture-stale`
+ *
+ * Identifies all scenarios whose entity (or dependency) has changed but
+ * whose screenshot hasn't been recaptured this session, then recaptures
+ * them in batch.
+ */
+async function handleRecaptureStale() {
+    const port = getServerPort();
+    const url = `http://localhost:${port}/api/editor-recapture-stale`;
+    console.log();
+    console.log(chalk.bold.cyan('━━━ Recapture Stale Scenarios ━━━'));
+    console.log();
+    let res;
+    try {
+        res = await fetch(url, { method: 'POST' });
+    }
+    catch (err) {
+        console.error(chalk.red('Error: Could not reach the CodeYam server. Is it running?'));
+        console.error(chalk.dim(`  ${err.message}`));
+        process.exit(1);
+    }
+    if (!res.ok) {
+        const body = await res.json().catch(() => null);
+        console.error(chalk.red(`Error: Recapture endpoint returned ${res.status}`));
+        if (body?.error)
+            console.error(chalk.red(`  ${body.error}`));
+        process.exit(1);
+    }
+    // Handle JSON response (early returns like "no changes" / "all up to date")
+    const contentType = res.headers.get('content-type') || '';
+    if (contentType.includes('application/json')) {
+        const data = await res.json();
+        if (data.note) {
+            console.log(chalk.dim(data.note));
+        }
+        else if (data.total === 0) {
+            console.log(chalk.green('All scenarios are up to date.'));
+        }
+        console.log();
+        return;
+    }
+    // Stream NDJSON progress events
+    let total = 0;
+    let recapturedCount = 0;
+    let failedCount = 0;
+    const reader = res.body?.getReader();
+    if (!reader) {
+        console.error(chalk.red('Error: No response body'));
+        process.exit(1);
+    }
+    const decoder = new TextDecoder();
+    let buffer = '';
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || ''; // Keep incomplete last line in buffer
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            try {
+                const event = JSON.parse(line);
+                switch (event.type) {
+                    case 'start':
+                        total = event.total;
+                        console.log(`Found ${total} stale scenario(s). Recapturing...\n`);
+                        break;
+                    case 'capturing':
+                        process.stdout.write(chalk.dim(`  … ${event.name}`));
+                        break;
+                    case 'success':
+                        // Clear the "capturing" line and print success
+                        process.stdout.write('\r\x1b[K');
+                        console.log(`  ${chalk.green('✓')} ${event.name}`);
+                        recapturedCount++;
+                        break;
+                    case 'failure':
+                        process.stdout.write('\r\x1b[K');
+                        console.log(`  ${chalk.red('✗')} ${event.name} — ${chalk.dim(event.error)}`);
+                        failedCount++;
+                        break;
+                    case 'done':
+                        // Final summary
+                        console.log();
+                        const color = failedCount > 0 ? chalk.yellow : chalk.green;
+                        console.log(color(`Recaptured ${recapturedCount}/${total} scenario(s).`));
+                        console.log();
+                        break;
+                }
+            }
+            catch {
+                // Skip unparseable lines
+            }
+        }
+    }
+    if (failedCount > 0) {
+        process.exit(1);
+    }
 }
 // ─── Scenarios subcommand ─────────────────────────────────────────────
 async function handleScenarios() {
@@ -1609,6 +3657,103 @@ 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() {
+    // Safety net: heal any scenarios with null entity_sha before checking coverage
+    try {
+        const { getDatabase } = await import('../../../packages/database/index.js');
+        const { countScenariosNeedingEntityBackfill } = await import('../utils/editorScenarios');
+        const db = getDatabase();
+        const backfillCount = await countScenariosNeedingEntityBackfill(db);
+        if (backfillCount > 0) {
+            console.log(chalk.dim(`  Healing ${backfillCount} scenario(s) with unlinked entities...`));
+            await handleAnalyzeImports({ silent: true });
+            // Run backfill after analysis
+            const { backfillEntityShaOnScenarios } = await import('../utils/editorScenarios');
+            const entities = await loadEntities({});
+            if (entities && entities.length > 0) {
+                await backfillEntityShaOnScenarios(db, entities.map((e) => ({
+                    sha: e.sha,
+                    name: e.name,
+                    filePath: e.filePath || '',
+                    isDefaultExport: e.metadata?.notExported === false &&
+                        e.metadata?.namedExport === false,
+                })));
+            }
+        }
+    }
+    catch {
+        // Non-fatal — proceed with coverage check regardless
+    }
+    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 ─────────────────────────────────────────────
@@ -1619,20 +3764,44 @@ async function handleTemplate() {
         console.log(chalk.yellow('Project already exists (package.json found). Skipping.'));
         return;
     }
-    const templateDir = path.join(__dirname, '..', '..', 'templates', 'nextjs-prisma-sqlite');
+    // Determine which template to use from editor state
+    const state = readState(root);
+    const techStackId = state?.techStackId;
+    const stack = techStackId
+        ? TECH_STACKS.find((s) => s.id === techStackId)
+        : undefined;
+    const templateName = stack?.templateDir || 'nextjs-prisma-sqlite';
+    const templateDir = path.join(__dirname, '..', '..', 'templates', templateName);
     if (!fs.existsSync(templateDir)) {
         console.error(chalk.red('Error: Template directory not found at ' + templateDir));
         process.exit(1);
     }
     const { execSync } = await import('child_process');
     // 1. Copy template files
-    console.log(chalk.bold('Copying template files...'));
+    console.log(chalk.bold(`Copying ${stack?.name || templateName} template files...`));
     execSync(`cp -r ${templateDir}/* .`, { cwd: root, stdio: 'inherit' });
-    execSync(`cp ${templateDir}/.env .`, { cwd: root, stdio: 'inherit' });
-    execSync(`cp ${templateDir}/gitignore .gitignore`, {
-        cwd: root,
-        stdio: 'inherit',
-    });
+    // Copy dotfiles that are stored without the dot prefix in templates
+    const gitignorePath = path.join(templateDir, 'gitignore');
+    if (fs.existsSync(gitignorePath)) {
+        execSync(`cp ${templateDir}/gitignore .gitignore`, {
+            cwd: root,
+            stdio: 'inherit',
+        });
+    }
+    const envPath = path.join(templateDir, 'env');
+    if (fs.existsSync(envPath)) {
+        execSync(`cp ${templateDir}/env .env`, { cwd: root, stdio: 'inherit' });
+    }
+    // Copy seed adapter into .codeyam/ (stored outside .codeyam/ in the template
+    // to avoid gitignore issues — .codeyam/ is selectively ignored in user projects)
+    const seedAdapterSrc = path.join(templateDir, 'seed-adapter.ts');
+    if (fs.existsSync(seedAdapterSrc)) {
+        const codeyamDir = path.join(root, '.codeyam');
+        if (!fs.existsSync(codeyamDir)) {
+            fs.mkdirSync(codeyamDir, { recursive: true });
+        }
+        fs.copyFileSync(seedAdapterSrc, path.join(codeyamDir, 'seed-adapter.ts'));
+    }
     console.log(chalk.green('  Template files copied.'));
     // 2. Install dependencies
     console.log(chalk.bold('Installing dependencies...'));
@@ -1649,7 +3818,7 @@ async function handleTemplate() {
         console.log(chalk.green('  Git initialized.'));
     }
     // 4. Run codeyam init
-    console.log(chalk.bold('Running codeyam init...'));
+    console.log(chalk.bold('Initializing project...'));
     await initCommand.handler({
         force: true,
         'keep-server': true,
@@ -1674,6 +3843,22 @@ async function handleTemplate() {
             // Config parse error is non-fatal
         }
     }
+    // 5b. Mark the project as template-scaffolded so migration detection
+    // doesn't treat it as a pre-existing project that needs migration.
+    const now = new Date().toISOString();
+    const existingState = readState(root);
+    writeState(root, {
+        feature: '',
+        step: 0,
+        label: '',
+        startedAt: now,
+        featureStartedAt: now,
+        ...existingState,
+        scaffolded: true,
+    });
+    // 5c. 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 {
@@ -1692,17 +3877,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');
@@ -1715,7 +3897,7 @@ async function handleSync() {
         // fall through
     }
     if (!projectSlug) {
-        console.error(chalk.red('Error: No project slug found. Run codeyam init first.'));
+        console.error(chalk.red('Error: No project slug found. Run `codeyam editor template` to initialize the project.'));
         process.exit(1);
     }
     const connectionOk = await withoutSpinner(() => testEnvironment());
@@ -1726,13 +3908,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)
@@ -1757,14 +3938,45 @@ 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) {
     const port = getServerPort();
-    const { parseVerifyImagesPaths, extractImageUrls, resolveImageUrl, verifyImageUrls, buildVerifyImagesReport, } = await import('../utils/editorImageVerifier.js');
+    const { parseVerifyImagesInput, extractImageUrls, resolveImageUrl, verifyImageUrls, buildVerifyImagesReport, extractImageUrlsFromScenarioFiles, } = await import('../utils/editorImageVerifier.js');
     let paths;
+    let explicitImageUrls;
     try {
-        paths = parseVerifyImagesPaths(jsonArg);
+        const input = parseVerifyImagesInput(jsonArg);
+        paths = input.paths;
+        explicitImageUrls = input.imageUrls;
     }
     catch {
         console.error(chalk.red('Error: Invalid JSON argument'));
@@ -1802,12 +4014,23 @@ async function handleVerifyImages(jsonArg) {
             console.error(chalk.red(`  ✗ ${pagePath} — ${err.message}`));
         }
     }
+    // Add explicitly-provided image URLs (Claude passes these directly)
+    for (const url of explicitImageUrls) {
+        allUrls.add(resolveImageUrl(url, devServerUrl));
+    }
+    // Also scan scenario mock data files for image URLs (client-rendered pages)
+    const scenariosDir = path.join(getProjectRoot(), '.codeyam', 'editor-scenarios');
+    const { urls: scenarioUrls, filesScanned: scenarioFilesScanned } = extractImageUrlsFromScenarioFiles(scenariosDir);
+    for (const url of scenarioUrls) {
+        allUrls.add(resolveImageUrl(url, devServerUrl));
+    }
     const urlList = [...allUrls];
     const results = urlList.length > 0 ? await verifyImageUrls(urlList) : [];
     const report = buildVerifyImagesReport({
         pagesChecked,
         imageUrls: urlList,
         results,
+        scenarioFilesScanned,
     });
     console.log(JSON.stringify(report, null, 2));
     if (report.failures.length > 0) {
@@ -1858,7 +4081,7 @@ function handleEditorDebug(args) {
         scenarios.push({
             id: 'overview-with-state',
             title: 'Cycle overview (project, with state)',
-            render: () => withTempRoot(true, (tempRoot) => captureOutput(() => printCycleOverview(tempRoot, makeState(4, feature)))),
+            render: () => withTempRoot(true, (tempRoot) => captureOutput(() => printCycleOverview(tempRoot, makeState(6, feature)))),
         });
     }
     const stepFns = {
@@ -1875,8 +4098,13 @@ function handleEditorDebug(args) {
         11: printStep11,
         12: printStep12,
         13: printStep13,
+        14: printStep14,
+        15: printStep15,
+        16: printStep16,
+        17: printStep17,
+        18: printStep18,
     };
-    for (let step = 1; step <= 13; step++) {
+    for (let step = 1; step <= 18; step++) {
         const stepId = `step-${step}`;
         if (!wants(stepId))
             continue;
@@ -1896,7 +4124,7 @@ function handleEditorDebug(args) {
             if (step === 2) {
                 scenarios.push({
                     id: 'step-2-scaffold',
-                    title: 'Step 2 (Prototype) — scaffold flow (no project)',
+                    title: 'Step 2 (Prepare) — scaffold flow (no project)',
                     render: () => withTempRoot(false, (tempRoot) => captureOutput(() => printStep2(tempRoot, feature))),
                 });
             }
@@ -1955,8 +4183,8 @@ const editorCommand = {
     describe: 'Editor mode guided workflow',
     builder: (yargs) => {
         const stepDescription = IS_INTERNAL_BUILD
-            ? 'Step number (1-13) or subcommand (template, register, 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, 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-18) or subcommand (template, register, isolate, analyze-imports, dependents, audit, scenarios, scenario-coverage, recapture-stale, change, sync, debug, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors)'
+            : 'Step number (1-18) or subcommand (template, register, isolate, analyze-imports, dependents, audit, scenarios, scenario-coverage, recapture-stale, change, sync, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors)';
         let builder = yargs
             .positional('step', {
             type: 'string',
@@ -1969,6 +4197,14 @@ const editorCommand = {
             .option('feature', {
             type: 'string',
             describe: 'Feature name (required for step 2)',
+        })
+            .option('app-formats', {
+            type: 'string',
+            describe: 'Comma-separated app formats (mobile-responsive-web-app, desktop-app, mobile-app)',
+        })
+            .option('tech-stack', {
+            type: 'string',
+            describe: 'Selected tech stack ID (e.g., nextjs-prisma-sqlite)',
         })
             .option('prompt', {
             type: 'string',
@@ -1984,7 +4220,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-18, or comma-separated list)',
             })
                 .option('resume', {
                 type: 'boolean',
@@ -2000,7 +4236,9 @@ const editorCommand = {
                 describe: 'Debug: output directory for the bundle',
             });
         }
-        return builder;
+        // Allow extra positional args for subcommands like `isolate A B C`
+        // without yargs rejecting them as unknown.
+        return builder.strict(false);
     },
     handler: async (argv) => {
         const root = getProjectRoot();
@@ -2018,7 +4256,19 @@ const editorCommand = {
                     process.exit(1);
                 }
                 if (result.data != null) {
-                    console.log(JSON.stringify(result.data, null, 2));
+                    const summary = formatApiSubcommandResult(argv.step, result.data);
+                    if (summary) {
+                        console.log(summary);
+                    }
+                    else {
+                        console.log(JSON.stringify(result.data, null, 2));
+                    }
+                }
+                // After a successful commit, remind Claude to continue to step 17
+                if (argv.step === 'commit' && result.ok) {
+                    console.log();
+                    console.log(chalk.green('Commit done. Now run: ') +
+                        chalk.bold('codeyam editor 17'));
                 }
             }
             catch (err) {
@@ -2033,6 +4283,11 @@ const editorCommand = {
             await handleRegister(argv.json || '');
             return;
         }
+        // Subcommand: codeyam editor glossary-add '{"name":"...", ...}'
+        if (argv.step === 'glossary-add') {
+            await handleGlossaryAdd(argv.json || '');
+            return;
+        }
         // Subcommand: codeyam editor analyze-imports
         if (argv.step === 'analyze-imports') {
             await handleAnalyzeImports();
@@ -2053,6 +4308,16 @@ const editorCommand = {
             await handleScenarios();
             return;
         }
+        // Subcommand: codeyam editor scenario-coverage
+        if (argv.step === 'scenario-coverage') {
+            await handleScenarioCoverage();
+            return;
+        }
+        // Subcommand: codeyam editor recapture-stale
+        if (argv.step === 'recapture-stale') {
+            await handleRecaptureStale();
+            return;
+        }
         // Subcommand: codeyam editor change <feature>
         if (argv.step === 'change') {
             handleChange(argv.json || '');
@@ -2063,6 +4328,24 @@ const editorCommand = {
             await handleVerifyImages(argv.json || '');
             return;
         }
+        // Subcommand: codeyam editor validate-seed '{"products":[...]}'
+        if (argv.step === 'validate-seed') {
+            await handleValidateSeed(argv.json || '');
+            return;
+        }
+        // Subcommand: codeyam editor delete <scenarioId>
+        if (argv.step === 'delete') {
+            await handleDelete(argv.json || '');
+            return;
+        }
+        // Subcommand: codeyam editor isolate "StarRating CategoryBadge DrinkCard"
+        // Also supports: codeyam editor isolate StarRating CategoryBadge DrinkCard
+        if (argv.step === 'isolate') {
+            const { parseIsolateArgs } = await import('./editorIsolateArgs.js');
+            const names = parseIsolateArgs(argv.json, argv._);
+            handleIsolate(names);
+            return;
+        }
         // Subcommand: codeyam editor template — scaffold project from template
         if (argv.step === 'template') {
             await handleTemplate();
@@ -2082,6 +4365,11 @@ const editorCommand = {
             await handleEditorDebug(argv);
             return;
         }
+        // Subcommand: codeyam editor migrate [subArg]
+        if (argv.step === 'migrate') {
+            handleMigrateCommand(root, argv.json || undefined);
+            return;
+        }
         // Subcommand: codeyam editor steps — show setup or cycle overview
         if (argv.step === 'steps') {
             if (!hasProject(root)) {
@@ -2089,18 +4377,13 @@ const editorCommand = {
             }
             else {
                 const state = readState(root);
-                // Clear prompt file when feature is done (step 13) so the hook
-                // can capture the next feature request from the user.
-                if (state?.step === 13) {
-                    clearEditorUserPrompt(root);
-                }
                 printCycleOverview(root, state);
             }
             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 > 18)) {
+            console.error(chalk.red(`Error: Invalid step "${argv.step}". Must be 1-18.`));
             process.exit(1);
         }
         if (step == null) {
@@ -2124,7 +4407,7 @@ const editorCommand = {
                 const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
                 const { projectSlug } = config;
                 if (!projectSlug) {
-                    errorLog('Missing project slug. Try reinitializing with: codeyam init --force');
+                    errorLog('Missing project slug. Try reinitializing with: `codeyam editor template`');
                     return;
                 }
                 const connectionOk = await withoutSpinner(() => testEnvironment());
@@ -2133,9 +4416,45 @@ 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',
+                        'dimensions',
+                        'screenshot_paths',
+                        'page_file_path',
+                        '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();
@@ -2144,7 +4463,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)
@@ -2162,13 +4481,85 @@ 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
+                }
+                // Auto-seed on fresh clone: if no scenario has ever been activated
+                // (active-scenario.json doesn't exist), seed the application database
+                // with the first application scenario that has seed data.
+                const activeScenarioPath = path.join(projectRoot, '.codeyam', 'active-scenario.json');
+                if (!fs.existsSync(activeScenarioPath)) {
+                    try {
+                        const { getDatabase: getDb } = await import('../../../packages/database/index.js');
+                        const seedDb = getDb();
+                        const appScenario = await seedDb
+                            .selectFrom('editor_scenarios')
+                            .select(['id', 'name', 'type'])
+                            .where('project_id', '=', project.id)
+                            .where('type', '=', 'application')
+                            .orderBy('created_at', 'asc')
+                            .executeTakeFirst();
+                        if (appScenario) {
+                            const seedFile = path.join(projectRoot, '.codeyam', 'editor-scenarios', `${appScenario.id}.seed.json`);
+                            if (fs.existsSync(seedFile)) {
+                                const { switchActiveScenario } = await import('../utils/editorScenarioSwitch.js');
+                                const seedResult = await switchActiveScenario({
+                                    scenarioId: appScenario.id,
+                                    scenarioName: appScenario.name || undefined,
+                                    scenarioType: appScenario.type || undefined,
+                                    projectRoot,
+                                });
+                                if (seedResult.seedResult?.success) {
+                                    console.log(chalk.green(`  Auto-seeded database with scenario: ${appScenario.name || appScenario.id}`));
+                                }
+                            }
+                        }
+                    }
+                    catch {
+                        // Non-fatal — auto-seed is best-effort
+                    }
+                }
                 // `codeyam editor` (no step) always implies editor mode.
                 // The empty-folder heuristic is no longer needed here — running this
                 // command IS the signal.  We still detect empty folders so that
@@ -2207,38 +4598,177 @@ 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
+                // Start background server (handles killing existing servers internally)
+                const editorPort = argv.port || 3111;
                 const { url } = await startBackgroundServer({
-                    port: argv.port || 3111,
+                    port: editorPort,
                     rootPath: projectRoot,
                     project,
                     branch,
                 });
+                // Build import graph if glossary exists but entities are missing.
+                // Runs on first startup (no entities at all) AND when page files or
+                // scenario component files lack entity coverage.
+                const glossaryPath = path.join(projectRoot, '.codeyam', 'glossary.json');
+                if (fs.existsSync(glossaryPath)) {
+                    let needsAnalysis = false;
+                    const entities = await loadEntities({});
+                    if (!entities || entities.length === 0) {
+                        needsAnalysis = true;
+                    }
+                    else {
+                        const entityFilePaths = new Set(entities.map((e) => e.filePath));
+                        // Check if any page files are missing entities (Next.js apps)
+                        try {
+                            const { scanPageFilePaths } = await import('../utils/entityChangeStatus.server.js');
+                            const { allFiles } = scanPageFilePaths(projectRoot);
+                            const pageFiles = allFiles.filter((f) => f.endsWith('/page.tsx') || f.endsWith('/page.js'));
+                            const missingPages = pageFiles.filter((f) => !entityFilePaths.has(f));
+                            if (missingPages.length > 0) {
+                                console.log(chalk.dim(`  Found ${missingPages.length} page(s) without entity analysis — running import analysis...`));
+                                needsAnalysis = true;
+                            }
+                        }
+                        catch {
+                            // Non-fatal — page file check failed
+                        }
+                        // Check if any scenario files (component_path or page_file_path)
+                        // are missing entities — covers non-Next.js apps
+                        if (!needsAnalysis) {
+                            try {
+                                const { getDatabase } = await import('../../../packages/database/index.js');
+                                const db = getDatabase();
+                                const scenarioFiles = await db
+                                    .selectFrom('editor_scenarios')
+                                    .select(['component_path', 'page_file_path'])
+                                    .where('project_id', '=', project.id)
+                                    .distinct()
+                                    .execute();
+                                const missingCount = scenarioFiles.filter((row) => {
+                                    const cp = row.component_path;
+                                    const pfp = row.page_file_path;
+                                    return ((cp && !entityFilePaths.has(cp)) ||
+                                        (pfp && !entityFilePaths.has(pfp)));
+                                }).length;
+                                if (missingCount > 0) {
+                                    console.log(chalk.dim(`  Found ${missingCount} scenario file(s) without entity analysis — running import analysis...`));
+                                    needsAnalysis = true;
+                                }
+                            }
+                            catch {
+                                // Non-fatal
+                            }
+                        }
+                        // Check if any scenarios have null entity_sha with file paths — heal on startup
+                        if (!needsAnalysis) {
+                            try {
+                                const { getDatabase } = await import('../../../packages/database/index.js');
+                                const { countScenariosNeedingEntityBackfill } = await import('../utils/editorScenarios');
+                                const db = getDatabase();
+                                const backfillCount = await countScenariosNeedingEntityBackfill(db);
+                                if (backfillCount > 0) {
+                                    console.log(chalk.dim(`  Found ${backfillCount} scenario(s) with unlinked entities — running import analysis...`));
+                                    needsAnalysis = true;
+                                }
+                            }
+                            catch {
+                                // Non-fatal
+                            }
+                        }
+                    }
+                    if (needsAnalysis) {
+                        try {
+                            await handleAnalyzeImports({ silent: true });
+                        }
+                        catch {
+                            // Non-fatal
+                        }
+                    }
+                }
+                // Backfill page_file_path for application scenarios that have a URL but
+                // no page_file_path. This resolves the file from the URL using Next.js
+                // routing conventions, enabling syncScenarioEntityShas to link them to
+                // entities. Covers fresh clones where JSON files lack pageFilePath.
+                try {
+                    const { getDatabase: getDb } = await import('../../../packages/database/index.js');
+                    const pfpDb = getDb();
+                    const unresolved = await pfpDb
+                        .selectFrom('editor_scenarios')
+                        .select(['id', 'url'])
+                        .where('project_id', '=', project.id)
+                        .where('component_name', 'is', null)
+                        .where('page_file_path', 'is', null)
+                        .where('url', 'is not', null)
+                        .execute();
+                    if (unresolved.length > 0) {
+                        const { scanPageFilePaths: scanPfp } = await import('../utils/entityChangeStatus.server.js');
+                        const { matchUrlToPageFile } = await import('../utils/routePatternMatching');
+                        const { allFiles: pfpFiles } = scanPfp(projectRoot);
+                        let pfpResolved = 0;
+                        for (const row of unresolved) {
+                            const r = row;
+                            if (!r.url)
+                                continue;
+                            const matched = matchUrlToPageFile(r.url, pfpFiles);
+                            if (matched) {
+                                await pfpDb
+                                    .updateTable('editor_scenarios')
+                                    .set({ page_file_path: matched })
+                                    .where('id', '=', r.id)
+                                    .execute();
+                                pfpResolved++;
+                            }
+                        }
+                        if (pfpResolved > 0) {
+                            console.log(chalk.green(`  Resolved page_file_path for ${pfpResolved} scenario(s) from URL`));
+                        }
+                    }
+                }
+                catch {
+                    /* Non-fatal — page_file_path backfill from URL */
+                }
+                // Backfill entity_sha on scenarios that were synced before entities existed.
+                // This runs independently of analyze-imports so fresh clones and file-synced
+                // scenarios get linked to their entities even when auto-analyze doesn't trigger.
+                try {
+                    const entities = await loadEntities({});
+                    if (entities && entities.length > 0) {
+                        const { getDatabase } = await import('../../../packages/database/index.js');
+                        const db = getDatabase();
+                        const result = await backfillEntityShaOnScenarios(db, entities.map((e) => ({
+                            sha: e.sha,
+                            name: e.name,
+                            filePath: e.filePath || '',
+                            isDefaultExport: e.metadata?.notExported === false &&
+                                e.metadata?.namedExport === false,
+                        })));
+                        if (result.updated > 0) {
+                            console.log(chalk.green(`  Linked ${result.updated} scenario(s) to their entities`));
+                        }
+                    }
+                }
+                catch {
+                    /* Non-fatal */
+                }
                 console.log();
                 console.log(`  Dashboard: ${url}`);
                 console.log('  Run "codeyam --help" for all commands');
@@ -2252,7 +4782,9 @@ const editorCommand = {
                         : process.platform === 'win32'
                             ? 'start ""'
                             : 'xdg-open';
-                    execSync(`${openCommand} "${url}/editor"`, { stdio: 'ignore' });
+                    execSync(`${openCommand} "${url}/editor"`, {
+                        stdio: 'ignore',
+                    });
                 }
                 catch {
                     // Silently fail if open command doesn't work
@@ -2266,11 +4798,27 @@ 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;
+                const appFormats = argv['app-formats']
+                    ? argv['app-formats'].split(',').map((f) => f.trim())
+                    : undefined;
+                const techStackId = argv['tech-stack'] || undefined;
                 const prompt = argv.prompt || undefined;
-                printStep1(root, feature, prompt);
+                printStep1(root, feature, { appFormats, techStackId }, prompt);
                 break;
             }
             case 2: {
@@ -2293,12 +4841,27 @@ const editorCommand = {
             case 10:
             case 11:
             case 12:
-            case 13: {
+            case 13:
+            case 14:
+            case 15:
+            case 16:
+            case 17:
+            case 18: {
                 const feature = argv.feature || state?.feature;
                 if (!feature) {
                     console.error(chalk.red('Error: No feature in progress. Run codeyam editor 1 first.'));
                     process.exit(1);
                 }
+                // Hard gate: steps 10+ require audit to have passed
+                if (step >= 10) {
+                    const auditOk = await checkAuditGate();
+                    if (!auditOk) {
+                        // checkAuditGate() already printed specific failure details above
+                        console.error(chalk.red.bold('BLOCKED: The audit has not passed. Fix the issues listed above before proceeding.'));
+                        console.error(chalk.yellow('DO NOT re-run the audit in a loop — fix the underlying issues first.'));
+                        process.exit(1);
+                    }
+                }
                 const stepFns = {
                     3: printStep3,
                     4: printStep4,
@@ -2311,6 +4874,11 @@ const editorCommand = {
                     11: printStep11,
                     12: printStep12,
                     13: printStep13,
+                    14: printStep14,
+                    15: printStep15,
+                    16: printStep16,
+                    17: printStep17,
+                    18: printStep18,
                 };
                 stepFns[step](root, feature);
                 break;