@codeyam/codeyam-cli 0.1.11 → 0.1.13

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

@@ -16,10 +16,13 @@ import { APP_FORMATS, TECH_STACKS } from "../data/techStacks.js";
 import { getProjectRoot as getStateProjectRoot } from "../state.js";
 import initCommand from "./init.js";
 import { scanScenarioFiles, syncScenarioFilesToDatabase, backfillScenarioMetadata, migrateScenarioFormats, } from "../utils/scenariosManifest.js";
-import { clearEditorState, clearEditorUserPrompt, validateStepTransition, } from "../utils/editorScenarios.js";
-import { validateSeedData, detectSeedAdapter, } from "../utils/editorSeedAdapter.js";
+import { clearEditorState, clearEditorUserPrompt, 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 = {
@@ -40,6 +43,18 @@ const STEP_LABELS = {
     15: 'Finalize',
     16: '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
  */
@@ -185,6 +200,146 @@ 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) {
+    checkbox('Check existing scenarios: `codeyam editor scenarios`');
+    console.log(chalk.dim('    Review existing scenarios — reuse and update their data rather than'));
+    console.log(chalk.dim('    creating duplicates. Re-register with the same name to update a scenario.'));
+    console.log();
+    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();
+    checkbox('Choose the right data approach for scenarios:');
+    console.log(chalk.dim('    With seed adapter: add "seed":{...} to populate the database for each state'));
+    console.log(chalk.dim('    Without seed adapter: add "mockData":{"routes":{"/api/...":{"body":[...]}}} to mock API responses'));
+    console.log(chalk.dim('    For external APIs (Stripe, weather, etc.): 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 5 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", 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.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.
  */
@@ -570,6 +725,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();
@@ -748,13 +939,29 @@ function printStep2(root, feature) {
         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();
+    }
     console.log(chalk.bold('Checklist:'));
     checkbox('Create API routes that read from the database via Prisma');
-    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>'));
+    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
@@ -896,34 +1103,7 @@ function printStep4(root, feature) {
     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();
-    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.'));
+    printExtractionPlanInstructions();
     stopGate(4);
 }
 // ─── Step 5: Extract ──────────────────────────────────────────────────
@@ -998,20 +1178,7 @@ function printStep6(root, feature) {
     }
     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('Every non-component entry MUST have `testFile` set — hooks and functions all need tests');
-    console.log(chalk.yellow('    If a function/hook has no test yet, go back and write one (TDD). The audit will block you.'));
-    console.log();
-    console.log(chalk.bold('Entry format:'));
-    console.log(chalk.dim('  { "name": "calculateTotal", "filePath": "app/utils/pricing.ts",'));
-    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);
@@ -1039,56 +1206,11 @@ function printStep7(root, feature) {
     console.log();
     console.log(chalk.bold('Visual Components — Component Isolation:'));
     checkbox('List all files with new/modified visual components from step 5');
-    checkbox('Create isolation route dirs: `codeyam editor isolate "ComponentA ComponentB ..."`');
-    console.log(chalk.dim('    This creates app/isolated-components/layout.tsx (with production notFound() guard) and'));
-    console.log(chalk.dim('    a directory per component. List ALL components that need isolation routes.'));
     checkbox('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/isolated-components.ComponentName.tsx → /isolated-components/ComponentName'));
-    console.log(chalk.dim('       Next.js: app/isolated-components/ComponentName/page.tsx → /isolated-components/ComponentName'));
-    console.log(chalk.dim('       The route defines a `scenarios` object mapping scenario names to props,'));
-    console.log(chalk.dim('       reads `?s=ScenarioName` from the URL, and renders the component with those props.'));
-    console.log(chalk.dim('       Wrap the component in a capture container with id="codeyam-capture":'));
-    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":"/isolated-components/ComponentName?s=Scenario",`));
-    console.log(chalk.dim(`         "dimensions":["${dim}"],`));
-    console.log(chalk.dim(`         "mockData":{"routes":{"/api/...":{"body":[...]}}}}'`));
-    console.log(chalk.yellow('       ALWAYS include "dimensions" — use the named screen size that matches the component\'s context.'));
-    console.log(chalk.dim(dimNames.length > 0
-        ? `       Available dimensions: ${dimNames.map((n) => `"${n}"`).join(', ')}. Default: "${dim}".`
-        : `       Use "${dim}" for most components. Names must match a key in screenSizes from setup.`));
-    console.log(chalk.dim('       Names must match a key in screenSizes from setup. If you need a new size, add it first:'));
-    console.log(chalk.dim(`       curl -s -X POST http://localhost:${port}/api/editor-project-info -H "Content-Type: application/json" \\`));
-    console.log(chalk.dim(`         -d '{"screenSizes":{...existing..., "New Name":{"width":W,"height":H}}}'  (replaces all — include every size)`));
-    console.log(chalk.dim('       url is a PATH (starts with /) — the proxy routes it and intercepts API calls'));
-    console.log(chalk.dim('       mockData.routes provides data for API calls the component makes internally'));
-    console.log(chalk.dim('       (omit mockData if the component has no internal API calls)'));
-    console.log(chalk.dim('       For large JSON: use your Write tool to create .codeyam/tmp/scenario.json,'));
-    console.log(chalk.dim('       then: codeyam editor register @.codeyam/tmp/scenario.json'));
-    console.log(chalk.yellow('    5. IMPORTANT: Check the register response for `clientErrors` array'));
-    console.log(chalk.yellow('       If clientErrors is non-empty → fix the isolation route and re-register'));
-    console.log(chalk.yellow('       Fix client errors and re-register before moving on'));
-    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');
@@ -1143,51 +1265,11 @@ function printStep8(root, feature) {
     console.log(chalk.cyan("  • New data states that can't coexist in one scenario (empty vs rich, error vs success) → new scenario"));
     console.log(chalk.cyan("  • Don't duplicate — if an existing scenario can cover a state with richer data, enhance it instead"));
     console.log();
-    console.log(chalk.bold('Checklist:'));
-    checkbox('Run `codeyam editor scenarios` — review all existing scenarios');
-    checkbox("Create new scenarios for any pages that don't have scenarios yet");
-    console.log(chalk.yellow('    Each page needs its own scenarios — a detail page needs different data than the catalog'));
-    checkbox('Re-register every existing scenario whose page was affected by this feature');
-    console.log(chalk.dim('    Use the SAME name to update. Enhance seed data to showcase this feature where relevant.'));
-    console.log(chalk.yellow("    Don't just re-register unchanged data — enrich it so the feature is thoroughly demonstrated."));
-    checkbox('ALWAYS include "dimensions" — pick the viewport that best demonstrates the page');
-    console.log(chalk.yellow('    Every app scenario MUST have a "dimensions" field referencing a named screen size from setup.'));
-    console.log(chalk.dim(dimNames.length > 0
-        ? `    Available dimensions: ${dimNames.map((n) => `"${n}"`).join(', ')}. Default: "${dim}".`
-        : `    Use "${dim}" for most scenarios. Names must match a key in screenSizes from setup.`));
-    if (dimNames.length > 1) {
-        const otherDim = dimNames.find((n) => n !== dim) || dimNames[1];
-        console.log(chalk.yellow(`    Think about what fits each scenario: full pages/standalone views → "${otherDim}", popups/widgets → "${dim}".`));
-    }
-    console.log(chalk.dim('    For responsive apps, include multiple dimensions: "dimensions":["Desktop","Mobile"] captures both viewports.'));
-    console.log(chalk.dim('    If you need a new named size mid-workflow, add it via editor-project-info API (include ALL existing sizes — the API replaces, not merges).'));
-    checkbox('If the project has a database + seed adapter, use seed-based scenarios:');
-    console.log(chalk.dim(`    codeyam editor register '{"name":"Full Catalog","type":"application","url":"/","dimensions":["${dim}"],"seed":{"products":[...],"categories":[...]}}'`));
-    console.log(chalk.dim('    Seed data is written to the DB via the seed adapter. Real app renders real data.'));
-    checkbox('IMPORTANT: Always include "url" — the page path to screenshot for this scenario');
-    console.log(chalk.dim('    Use "/" for home page, "/drinks/1" for detail pages, etc.'));
-    console.log(chalk.dim('    Without url, the screenshot captures the root page regardless of the scenario.'));
-    console.log(chalk.yellow('    Create separate scenarios for each page that shows different data.'));
-    checkbox('For large seed data, use your Write tool to create .codeyam/tmp/scenario.json, then:');
-    console.log(chalk.dim('    codeyam editor register @.codeyam/tmp/scenario.json'));
-    console.log(chalk.yellow('    IMPORTANT: Use the Write tool — NOT cat/heredoc — to avoid permission prompts'));
-    checkbox('For external API mocks (Stripe, weather, etc.), add externalApis:');
-    console.log(chalk.dim(`    "externalApis":{"GET https://api.stripe.com/v1/prices":{"body":[...],"status":200}}`));
-    checkbox('If the app uses auth, email, or other patterns: see FEATURE_PATTERNS.md for scenario guidance');
-    checkbox('If the app uses localStorage/sessionStorage instead of a database, use localStorage scenarios:');
-    console.log(chalk.dim(`    codeyam editor register '{"name":"Full Library","type":"application","url":"/","dimensions":["${dim}"],"localStorage":{"articles":[...],"collections":[...]}}'`));
-    console.log(chalk.dim('    The proxy injects data into localStorage before the app loads. Fully interactive — the app can read and write normally.'));
-    console.log(chalk.dim('    For an empty state, register with an empty localStorage or omit it entirely.'));
-    checkbox('If no database and no localStorage, use component-style mock scenarios:');
-    console.log(chalk.dim(`    codeyam editor register '{"name":"Empty","description":"...","url":"/","dimensions":["${dim}"],"mockData":{"routes":{"/api/...":{"body":[...]}}}}'`));
-    checkbox('After each registration, check the response for `clientErrors`');
-    console.log(chalk.yellow('    If clientErrors is non-empty → fix the issue and re-register the scenario'));
-    console.log(chalk.yellow('    Fix client errors and re-register before moving on'));
-    checkbox('CRITICAL: After EACH registration, view the captured screenshot to verify it');
-    console.log(chalk.yellow('    Read the screenshot file path from the registration response and view it.'));
-    console.log(chalk.yellow('    Does the screenshot actually SHOW the data you put in? If you seeded 5 articles'));
-    console.log(chalk.yellow('    but the screenshot shows an empty page, the scenario is broken — fix the code or data.'));
-    console.log(chalk.yellow('    Do NOT create scenarios with data the app cannot yet render.'));
+    checkbox('Ensure scenarios clearly demonstrate what changed in this session');
+    console.log(chalk.dim('    If data models changed: update existing scenarios seed data to match'));
+    console.log(chalk.dim('    If UI changed: re-register existing scenarios so screenshots reflect the update'));
+    console.log(chalk.dim('    Add new scenarios only for genuinely new data states not covered by existing ones'));
+    printAppScenarioInstructions();
     console.log();
     console.log(chalk.dim('Focus on creating and registering app-level scenarios. Code fixes happen in step 10 if needed.'));
     console.log();
@@ -1379,41 +1461,654 @@ function printStep13(root, feature) {
     if (isResuming) {
         printResumptionHeader(13);
     }
-    console.log('Present the results to the user and get their approval.');
+    console.log('Present the results to the user and get their approval.');
+    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` and `dimension`:');
+    console.log(chalk.dim(`    codeyam editor preview '{"scenarioId":"<id>","dimension":"${dim}"}'`));
+    console.log(chalk.dim('    Use the dimension that matches the scenario — check its registered dimensions.'));
+    printDimensionGuidance(dim, dimNames);
+    checkbox(`Show the results panel: \`codeyam editor show-results\``);
+    console.log(chalk.dim('    This opens a visual panel below the terminal showing all scenarios with screenshots.'));
+    console.log(chalk.dim('    The user can click scenarios to switch the live preview.'));
+    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 14`');
+    console.log();
+    console.log(chalk.bold('If the user chooses "Make changes" (or asks for ANY change, even as a question):'));
+    checkbox(`Hide the results panel: \`codeyam editor hide-results\``);
+    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 });
+}
+// ─── 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);
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
+    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('Fetch all scenarios: `codeyam editor scenarios`');
+    checkbox('Pick the best scenario to showcase:');
+    console.log(chalk.dim(`    codeyam editor preview '{"scenarioId":"<id>","dimension":"${dim}"}'`));
+    printDimensionGuidance(dim, dimNames);
+    checkbox('Show results: `codeyam editor show-results`');
+    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);
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
+    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('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` and `dimension`:');
+    checkbox('Pick the best scenario to showcase:');
     console.log(chalk.dim(`    codeyam editor preview '{"scenarioId":"<id>","dimension":"${dim}"}'`));
-    console.log(chalk.dim('    Use the dimension that matches the scenario — check its registered dimensions.'));
     printDimensionGuidance(dim, dimNames);
-    checkbox(`Show the results panel: \`codeyam editor show-results\``);
-    console.log(chalk.dim('    This opens a visual panel below the terminal showing all scenarios with screenshots.'));
-    console.log(chalk.dim('    The user can click scenarios to switch the live preview.'));
-    checkbox('Write a 1-2 sentence summary of what was built');
-    checkbox('Report test count and audit status (one line)');
+    checkbox('Show results: `codeyam editor show-results`');
+    checkbox('Write a 1-2 sentence summary of what was migrated');
     console.log();
-    console.log(chalk.bold('Present a selection menu to the user (use AskUserQuestion with these EXACT option labels):'));
+    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(' — git commit all changes and record in journal'));
+        chalk.dim(" — commit this page's migration"));
     console.log(chalk.yellow('    Option 2 label: "I\'d like to make some changes"') +
-        chalk.dim(' — describe changes, then re-verify'));
+        chalk.dim(' — make changes, then re-verify'));
     console.log();
     console.log(chalk.bold('If the user chooses "Save & commit":'));
-    checkbox('Advance to the commit step: `codeyam editor 14`');
+    checkbox('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" (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('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 14: Commit ─────────────────────────────────────────────────
 function printStep14(root, feature) {
@@ -1521,26 +2216,54 @@ async function handleAnalyzeImports(options = {}) {
     }
     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);
     // 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 pageFilePaths = scanPageFilePaths(root);
-    for (const pageFile of Object.values(pageFilePaths)) {
+    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 (glossary + pages)
     // Don't pass entityNames — entities may not exist yet (fresh clone).
@@ -1630,6 +2353,24 @@ async function handleAnalyzeImports(options = {}) {
         });
         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 || '',
+        })));
+        if (backfillResult.updated > 0 && !options.silent) {
+            console.log(chalk.green(`Linked ${backfillResult.updated} scenario(s) to their entities.`));
+        }
+    }
+    catch {
+        /* non-fatal */
+    }
 }
 // ─── Validate-seed subcommand ─────────────────────────────────────────
 /**
@@ -1668,6 +2409,24 @@ function handleValidateSeed(jsonArg) {
                 : 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:'));
@@ -1677,6 +2436,27 @@ function handleValidateSeed(jsonArg) {
         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"`
@@ -2151,23 +2931,106 @@ function handleChange(feature) {
 }
 // ─── Audit gate ─────────────────────────────────────────────────────
 /**
- * Silently check whether the audit passes. Returns true if allPassing,
- * false if any issues remain or the server is unreachable.
- * Used as a hard gate before steps 8+.
+ * Fetch the audit result from the server.
+ * Returns null if the server is unreachable.
  */
-async function checkAuditGate() {
+async function fetchAuditResult() {
     const port = getServerPort();
     try {
         const res = await fetch(`http://localhost:${port}/api/editor-audit`);
         if (!res.ok)
-            return false;
-        const data = await res.json();
-        return data?.summary?.allPassing === true;
+            return null;
+        return await res.json();
     }
     catch {
-        // Server not running or unreachable — can't verify, so don't block
+        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`);
+    if (s.componentsWithErrors > 0)
+        issues.push(`${s.componentsWithErrors} component(s) with client errors (browser API or runtime errors in captured scenarios)`);
+    if (s.functionsMissing > 0)
+        issues.push(`${s.functionsMissing} function(s) missing test files`);
+    if (s.functionsFailing > 0)
+        issues.push(`${s.functionsFailing} function(s) with failing tests`);
+    if (s.functionsNameMismatch > 0)
+        issues.push(`${s.functionsNameMismatch} function(s) with test name mismatch`);
+    if (s.missingFromGlossary > 0)
+        issues.push(`${s.missingFromGlossary} file(s) with scenarios not in glossary`);
+    if (s.incompleteEntities > 0)
+        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 (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.yellow('If errors reference browser APIs (localStorage, sessionStorage, window, document),'));
+            console.error(chalk.yellow('create a universal mock: codeyam detect-universal-mocks'));
+        }
     }
+    console.error(chalk.dim('\nRun `codeyam editor audit` for full details.\n'));
 }
 // ─── Audit subcommand ────────────────────────────────────────────────
 /**
@@ -2178,22 +3041,38 @@ async function checkAuditGate() {
  * 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 ━━━'));
@@ -2221,6 +3100,14 @@ async function handleAudit() {
                 if (c.clientErrors.length > 3) {
                     console.log(chalk.dim(`      … and ${c.clientErrors.length - 3} more`));
                 }
+                // Detect browser API errors and provide actionable guidance
+                const browserApiPattern = /\b(localStorage|sessionStorage|window\.|document\.|navigator\.|indexedDB|matchMedia|ResizeObserver|IntersectionObserver|MutationObserver)\b/;
+                const hasBrowserApiErrors = c.clientErrors.some((err) => browserApiPattern.test(err));
+                if (hasBrowserApiErrors) {
+                    console.log(chalk.yellow(`      ⚠ These errors are caused by browser APIs that don't exist during server-side analysis.`));
+                    console.log(chalk.yellow(`      Fix: Create a universal mock to stub the missing API. Run: codeyam detect-universal-mocks`));
+                    console.log(chalk.yellow(`      DO NOT re-run the audit or analyze-imports — the error will persist until a mock is created.`));
+                }
             }
         }
         console.log();
@@ -2252,6 +3139,53 @@ 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('      • Entity code uses browser APIs (localStorage, window, document) — create a universal mock'));
+            console.log(chalk.yellow('      • Source file was renamed/deleted but glossary still references the old path'));
+            console.log(chalk.yellow('      • Entity has import errors that prevent analysis'));
+            console.log(chalk.yellow('    To investigate: run `codeyam editor analyze-imports` (without --silent) to see the full error.'));
+            console.log(chalk.yellow('    To fix browser API issues: run `codeyam detect-universal-mocks`'));
+        }
+        else {
+            console.log(chalk.yellow('    Run `codeyam editor analyze-imports` to analyze these entities'));
+        }
+        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();
+    }
     // Summary
     const allOk = summary.allPassing;
     if (allOk) {
@@ -2275,6 +3209,15 @@ async function handleAudit() {
         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`);
+        }
         console.log(chalk.red.bold('Audit failed: ') + parts.join(', '));
     }
     console.log();
@@ -2392,6 +3335,30 @@ async function handleScenarios() {
 }
 // ─── 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 || '',
+                })));
+            }
+        }
+    }
+    catch {
+        // Non-fatal — proceed with coverage check regardless
+    }
     const port = getServerPort();
     const url = `http://localhost:${port}/api/editor-scenario-coverage`;
     let data;
@@ -2539,7 +3506,20 @@ async function handleTemplate() {
             // Config parse error is non-fatal
         }
     }
-    // 5b. Write a fresh prototypeId so the proxy clears stale localStorage
+    // 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
@@ -2917,7 +3897,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();
@@ -2996,14 +3978,16 @@ const editorCommand = {
             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 names = [];
-            if (argv.json)
-                names.push(...argv.json.split(/[\s,]+/).filter(Boolean));
-            // Collect any extra positional args (yargs puts them in argv._)
-            const extras = argv._.filter((a) => typeof a === 'string' && a !== 'editor');
-            names.push(...extras);
+            const { parseIsolateArgs } = await import('./editorIsolateArgs.js');
+            const names = parseIsolateArgs(argv.json, argv._);
             handleIsolate(names);
             return;
         }
@@ -3026,6 +4010,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)) {
@@ -3095,6 +4084,9 @@ const editorCommand = {
                         'screenshot_path',
                         'viewport_width',
                         'viewport_height',
+                        'dimensions',
+                        'screenshot_paths',
+                        'page_file_path',
                         'created_at',
                         'updated_at',
                     ])
@@ -3183,6 +4175,41 @@ const editorCommand = {
                 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
@@ -3248,11 +4275,77 @@ const editorCommand = {
                     project,
                     branch,
                 });
-                // Build import graph on first startup if glossary exists but no entities yet
+                // 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 });
                         }
@@ -3261,6 +4354,69 @@ const editorCommand = {
                         }
                     }
                 }
+                // 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 || '',
+                        })));
+                        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');
@@ -3274,7 +4430,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
@@ -3344,8 +4502,9 @@ const editorCommand = {
                 if (step >= 8) {
                     const auditOk = await checkAuditGate();
                     if (!auditOk) {
-                        console.error(chalk.red.bold('BLOCKED: The audit has not passed. Run `codeyam editor audit` and fix all issues before proceeding.'));
-                        console.error(chalk.yellow('Every function and hook must have a test file. Every component must have scenarios.'));
+                        // 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);
                     }
                 }