@codeyam/codeyam-cli 0.1.0-staging.b8b17a5 → 0.1.0-staging.ba3f279

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

@@ -13,35 +13,39 @@ import { installClaudeCodeSkills } from "../utils/install-skills.js";
 import { setupClaudeCodeSettings } from "../utils/setupClaudeCodeSettings.js";
 import { ensureAnalyzerFinalized, } from "../utils/analyzerFinalization.js";
 import { APP_FORMATS, TECH_STACKS } from "../data/techStacks.js";
+import { DESIGN_SYSTEMS } from "../data/designSystems.js";
 import { getProjectRoot as getStateProjectRoot } from "../state.js";
 import initCommand from "./init.js";
 import { scanScenarioFiles, syncScenarioFilesToDatabase, backfillScenarioMetadata, migrateScenarioFormats, } from "../utils/scenariosManifest.js";
-import { clearEditorState, clearEditorUserPrompt, validateStepTransition, backfillEntityShaOnScenarios, } from "../utils/editorScenarios.js";
+import { clearEditorState, validateStepTransition, backfillEntityShaOnScenarios, } from "../utils/editorScenarios.js";
 import { validateSeedData, detectSeedAdapter, validateSeedKeysAgainstPrisma, } from "../utils/editorSeedAdapter.js";
 import { deleteScenarioViaCli } from "../utils/editorDeleteScenario.js";
 import { buildEditorApiRequest, callEditorApi, EDITOR_API_SUBCOMMANDS, } from "../utils/editorApi.js";
 import { parseRegisterArg } from "../utils/parseRegisterArg.js";
+import { classifyRegistrationResult } from "../utils/registerScenarioResult.js";
 import { sanitizeGlossaryEntries } from "../utils/editorLoaderHelpers.js";
 import { readMigrationState, writeMigrationState, advanceToNextPage, completePage, getMigrationResumeInfo, } from "../utils/editorMigration.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const STEP_LABELS = {
     1: 'Plan',
-    2: 'Prototype',
-    3: 'Confirm',
-    4: 'Deconstruct',
-    5: 'Extract',
-    6: 'Glossary',
-    7: 'Analyze',
-    8: 'App Scenarios',
-    9: 'User Scenarios',
-    10: 'Verify',
-    11: 'Journal',
-    12: 'Review',
-    13: 'Present',
-    14: 'Commit',
-    15: 'Finalize',
-    16: 'Push',
+    2: 'Prepare',
+    3: 'Prototype',
+    4: 'Verify Prototype',
+    5: 'Confirm',
+    6: 'Deconstruct',
+    7: 'Extract',
+    8: 'Glossary',
+    9: 'Analyze',
+    10: 'App Scenarios',
+    11: 'User Scenarios',
+    12: 'Verify',
+    13: 'Journal',
+    14: 'Review',
+    15: 'Present',
+    16: 'Commit',
+    17: 'Finalize',
+    18: 'Push',
 };
 const MIGRATION_STEP_LABELS = {
     1: 'Survey',
@@ -119,11 +123,19 @@ function writeState(root, state) {
     const dir = path.dirname(statePath);
     fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(statePath, JSON.stringify(state, null, 2), 'utf8');
+    // Write task tracking file — marks that a task is expected for this step.
+    // The step hook sets taskCreated=true when it sees a TaskCreate tool call.
+    // Steps 1 and below don't require tasks (feature not named yet).
+    if (state.step && state.step >= 2) {
+        const trackingPath = path.join(root, '.codeyam', 'editor-task-tracking.json');
+        fs.writeFileSync(trackingPath, JSON.stringify({ step: state.step, taskCreated: false }, null, 2), 'utf8');
+    }
 }
 /**
  * Clear the editor state (for starting a new feature).
- * Does NOT clear the user prompt file — that's handled separately
- * via clearEditorUserPrompt when the previous feature commits.
+ * Does NOT clear the user prompt file — the prompt is cleared
+ * by the journal API after recording, and the hook captures
+ * a fresh prompt for the next feature on UserPromptSubmit.
  */
 function clearState(root) {
     clearEditorState(root);
@@ -177,6 +189,44 @@ function getProjectDimensions(root) {
         return { defaultName: 'Desktop', names: [] };
     }
 }
+function getTechStackContext(root) {
+    const state = readState(root);
+    const techStackId = state?.techStackId || '';
+    const stack = TECH_STACKS.find((s) => s.id === techStackId);
+    const isExpo = techStackId === 'expo-react-native';
+    const isChromeExt = techStackId === 'chrome-extension-react';
+    const isNextjs = techStackId.startsWith('nextjs-') || (!isExpo && !isChromeExt);
+    return {
+        id: techStackId || 'nextjs-prisma-sqlite',
+        isExpo,
+        isNextjs,
+        isChromeExt,
+        hasDatabase: isNextjs,
+        testRunner: isNextjs ? 'vitest' : 'jest',
+        testRunCommand: isNextjs ? 'npx vitest run' : 'npx jest',
+        storageType: isExpo
+            ? 'asyncStorage'
+            : isChromeExt
+                ? 'chromeStorage'
+                : 'prisma',
+        routerImport: isExpo
+            ? 'expo-router'
+            : isChromeExt
+                ? 'react-router-dom'
+                : 'next/navigation',
+        componentPrimitives: isExpo
+            ? '<View>, <Text>, <ScrollView>'
+            : '<div>, <span>, <h1>',
+        rawPrimitivesList: isExpo
+            ? '<View>, <Text>, <Image>, <ScrollView>, <FlatList>'
+            : '<div>, <span>, <h1>, <p>, <img>, <ul>',
+        patternsFile: isExpo
+            ? 'MOBILE_SETUP.md'
+            : isChromeExt
+                ? 'EXTENSION_SETUP.md'
+                : 'FEATURE_PATTERNS.md',
+    };
+}
 /**
  * Print dimension guidance when the project has multiple screen sizes.
  * Tells Claude to pick the right dimension for the content being previewed
@@ -200,14 +250,45 @@ function checkbox(text) {
     const highlighted = text.replace(/`([^`]+)`/g, (_m, code) => chalk.cyan(code));
     console.log(`  ${chalk.dim('[ ]')} ${highlighted}`);
 }
+/**
+ * Instructions for creating/updating .codeyam/data-structure.json.
+ * Only prints creation instructions if the file doesn't exist yet.
+ * If it exists, reminds Claude to update it if data models changed.
+ */
+function printDataStructureInstructions() {
+    const root = getProjectRoot();
+    const dsPath = path.join(root, '.codeyam', 'data-structure.json');
+    const exists = fs.existsSync(dsPath);
+    if (!exists) {
+        console.log(chalk.bold('Create the data structure config:'));
+        checkbox('Create `.codeyam/data-structure.json` describing all data sources');
+        console.log(chalk.dim("  This file tells the editor what data the app uses and how it's stored."));
+        console.log(chalk.dim('  The file is a JSON array. Each entry describes one data source:'));
+        console.log(chalk.dim('  { "name": "Drink", "description": "...", "category": "datastore", "order": 1,'));
+        console.log(chalk.dim('    "fields": [{ "name": "id", "type": "number", "isId": true, "required": true }, ...] }'));
+        console.log();
+        console.log(chalk.dim('  category: "datastore" for persisted data (DB, localStorage)'));
+        console.log(chalk.dim('           "mock-api" for mocked external API responses'));
+        console.log(chalk.dim('  order: 1 = primary data store, 2 = secondary, etc.'));
+        console.log(chalk.dim('  Do NOT include types only used as component props.'));
+    }
+    else {
+        checkbox('If this feature changes data models, update `.codeyam/data-structure.json`');
+        console.log(chalk.dim('  Add new tables, update fields, or change descriptions to match.'));
+    }
+    console.log();
+}
 /**
  * Shared app scenario registration instructions used by editor Step 8 and migration Steps 1/6.
  * Prints seed-based scenarios, mock-based fallback, @ file prefix, externalApis, url requirement, and error checking.
  */
 function printAppScenarioInstructions(pageName, route) {
+    const root = process.cwd();
+    const hasSeedAdapter = !!detectSeedAdapter(root);
     checkbox('Check existing scenarios: `codeyam editor scenarios`');
-    console.log(chalk.dim('    Review existing scenarios — reuse and update their data rather than'));
-    console.log(chalk.dim('    creating duplicates. Re-register with the same name to update a scenario.'));
+    console.log(chalk.dim('    Review existing scenarios — enhance their seed data to exercise new features.'));
+    console.log(chalk.dim('    A rich scenario that exercises 5 features is better than 5 thin scenarios with one feature each.'));
+    console.log(chalk.dim('    Rename scenarios if their data scope has grown beyond the original name.'));
     console.log();
     console.log(chalk.bold.yellow('App scenarios vs component scenarios — these are DIFFERENT:'));
     console.log(chalk.yellow('  App scenarios:       show the FULL PAGE with seeded data at a real route (/, /library, etc.)'));
@@ -224,21 +305,42 @@ function printAppScenarioInstructions(pageName, route) {
         console.log(chalk.dim('    Example: "Page - Full Data", "Page - Empty State", "Page - Error State"'));
     }
     console.log();
+    checkbox('Ensure every page file used in app scenarios has a glossary entry with its filePath:');
+    console.log(chalk.dim('    The register command validates pageFilePath against the glossary — add missing pages now.'));
+    console.log(chalk.dim('    Example: {"name":"CounterScreen","filePath":"app/(tabs)/index.tsx","type":"page","description":"Main counter page"}'));
+    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'));
+    if (hasSeedAdapter) {
+        checkbox(chalk.bold.red('REQUIRED: Every app scenario MUST include "seed" data — without it the page will be empty!'));
+        console.log(chalk.yellow('    A seed adapter exists — you MUST include "seed":{...} in every app scenario registration.'));
+        console.log(chalk.yellow('    An app scenario without seed data will render an empty page (no database rows = nothing to show).'));
+        console.log(chalk.dim('    "seed" maps table names to arrays of rows: "seed":{"user":[{"id":1,"name":"Alice"}],"article":[...]}'));
+        console.log(chalk.dim('    For external APIs: also add "externalApis":{"GET https://...":{"body":[...],"status":200}}'));
+    }
+    else {
+        const appCtx = getTechStackContext(root);
+        checkbox('Include data in every app scenario — without it the page will be empty:');
+        if (appCtx.isExpo) {
+            console.log(chalk.dim('    Use "localStorage":{"items":"[...]"} to pre-populate AsyncStorage (values are JSON strings)'));
+            console.log(chalk.dim("    AsyncStorage uses localStorage on web — CodeYam's injection works automatically."));
+        }
+        console.log(chalk.dim('    Use "mockData":{"routes":{"/api/...":{"body":[...]}}} to mock API responses'));
+        console.log(chalk.dim('    For external APIs: add "externalApis":{"GET https://...":{"body":[...],"status":200}}'));
+    }
+    console.log();
+    console.log(chalk.bold('Register ALL scenarios at once (bulk registration):'));
+    console.log(chalk.dim('    Write an array of scenario objects to a temp file:'));
+    console.log(chalk.dim('    [{"name":"...","type":"application","url":"/","seed":{...}}, {"name":"...","url":"/other",...}]'));
+    console.log(chalk.dim('    Then register all at once: codeyam editor register @.codeyam/tmp/scenarios.json'));
+    console.log(chalk.yellow('    Bulk registration is preferred — faster and avoids repeated capture overhead.'));
+    console.log();
     checkbox('If the app uses auth, email, or other patterns: see FEATURE_PATTERNS.md for scenario guidance');
-    checkbox('After each registration, check the response for `clientErrors`');
+    checkbox('After registration, check the response for `clientErrors`');
     console.log(chalk.yellow('    If clientErrors is non-empty → fix the issue and re-register the scenario'));
     console.log(chalk.yellow('    Fix client errors and re-register before moving on'));
 }
@@ -295,16 +397,24 @@ function printExtractionPlanInstructions() {
     console.log(chalk.yellow('    — Where it currently lives (source file + approximate lines)'));
     console.log(chalk.yellow('    — Where it will go (new file path)'));
     console.log();
-    console.log(chalk.dim('Present the numbered plan, then proceed to step 5 to execute it.'));
+    console.log(chalk.dim('Present the numbered plan, then proceed to step 7 to execute it.'));
 }
 /**
  * Shared component capture instructions used by editor Step 7 and migration Steps 3/8.
  * 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.'));
+function printComponentCaptureInstructions(root) {
+    const ctx = root ? getTechStackContext(root) : undefined;
+    const isExpo = ctx?.isExpo ?? false;
+    checkbox('Set up isolation routes: `codeyam editor isolate ComponentA ComponentB ...`');
+    if (isExpo) {
+        console.log(chalk.dim('    This creates app/isolated-components/_layout.tsx (with __DEV__ guard).'));
+        console.log(chalk.dim('    You then create a flat .tsx file per component (NOT subdirectories — Expo Router uses flat files).'));
+    }
+    else {
+        console.log(chalk.dim(`    This creates app/isolated-components/layout.tsx (with 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'));
@@ -315,23 +425,37 @@ function printComponentCaptureInstructions() {
     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'));
+    if (isExpo) {
+        console.log(chalk.dim('       Expo:    app/isolated-components/ComponentName.tsx → /isolated-components/ComponentName'));
+        console.log(chalk.dim('       Use useLocalSearchParams() from expo-router to read ?s=ScenarioName.'));
+    }
+    else {
+        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'));
+    if (isExpo) {
+        console.log(chalk.dim('       Wrap the component in a capture container with nativeID="codeyam-capture":'));
+        console.log(chalk.dim('       <View nativeID="codeyam-capture" style={{ display:"flex" }}>'));
+    }
+    else {
+        console.log(chalk.dim('       Wrap the component in a capture container with id="codeyam-capture":'));
+        console.log(chalk.dim('       <div id="codeyam-capture" style={{ display:"inline-block" }}>'));
+    }
+    console.log(chalk.dim(isExpo
+        ? '         <View style={{ width:"100%", maxWidth:... }}> ← match the app\'s container width'
+        : '         <div style={{ width:"100%", maxWidth:"..." }}> ← match the app\'s container width'));
+    console.log(chalk.dim('       e.g. card in a 3-col grid → maxWidth: 384, 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(`         "url":"/isolated-components/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('       IMPORTANT: url MUST be an isolation route (/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)'));
@@ -339,6 +463,10 @@ function printComponentCaptureInstructions() {
     console.log(chalk.yellow('       If clientErrors is non-empty → fix the isolation route and re-register'));
     console.log(chalk.yellow('       Fix client errors and re-register before moving on'));
     console.log(chalk.dim('    Isolation routes are committed to git — the layout guard blocks them in production'));
+    console.log();
+    console.log(chalk.bold('  Bulk registration: write all component scenarios to a temp file as an array:'));
+    console.log(chalk.dim('    [{"name":"Comp - Default","componentName":"Comp","componentPath":"...","url":"/isolated-components/Comp?s=Default"}, ...]'));
+    console.log(chalk.dim('    codeyam editor register @.codeyam/tmp/scenarios.json'));
 }
 /**
  * Print a section header.
@@ -352,13 +480,13 @@ function stepHeader(step, title, feature) {
     console.log();
 }
 /**
- * Print a colored progress tracker showing all 16 steps.
+ * Print a colored progress tracker showing all 18 steps.
  * Steps before `current` are green ✓, `current` is bold cyan →, future steps are dim ○.
  */
 function printProgressTracker(current) {
     console.log();
     console.log(chalk.dim('  ┌─────────────────────────────────────┐'));
-    for (let i = 1; i <= 16; i++) {
+    for (let i = 1; i <= 18; i++) {
         const label = STEP_LABELS[i];
         const num = i < 10 ? ` ${i}` : `${i}`;
         const content = `${num}. ${label.padEnd(28)}`;
@@ -379,9 +507,33 @@ function printProgressTracker(current) {
  *
  * Options:
  * - confirm: true  → step requires user confirmation before proceeding (steps 1, 3, 11)
+ * - feature: string → feature name for task directive
  */
 function stopGate(current, opts) {
-    console.log();
+    const totalSteps = Object.keys(STEP_LABELS).length;
+    const currentLabel = STEP_LABELS[current] || `Step ${current}`;
+    const nextLabel = current < totalSteps ? STEP_LABELS[current + 1] : undefined;
+    console.log();
+    // ━━━ TASK ━━━ — deterministic task lifecycle directive
+    // Skip step 1 (no feature name yet — task starts at step 2)
+    if (current >= 2) {
+        console.log(chalk.bold.cyan('━━━ TASK ━━━'));
+        console.log(chalk.cyan('Before creating the task below, delete ALL existing tasks:'));
+        console.log(chalk.cyan('  1. Run TaskList to find all tasks'));
+        console.log(chalk.cyan('  2. Run TaskUpdate with status "deleted" for EACH task returned'));
+        console.log(chalk.cyan('Then create a new task with this EXACT title (copy verbatim):'));
+        console.log();
+        let taskTitle;
+        if (current < totalSteps) {
+            taskTitle = `Complete codeyam editor step ${current}: '${currentLabel}' and move on to step ${current + 1}: '${nextLabel}'`;
+        }
+        else {
+            taskTitle =
+                'Ask user what to build next and restart codeyam editor workflow';
+        }
+        console.log(chalk.bold.cyan(`EXACT_TASK_TITLE: ${taskTitle}`));
+        console.log();
+    }
     console.log(chalk.bold.red('━━━ STOP ━━━'));
     console.log();
     console.log(chalk.red('Complete each checklist item above before proceeding to the next step.'));
@@ -390,20 +542,12 @@ function stopGate(current, opts) {
         console.log(chalk.yellow('Wait for user confirmation before moving on.'));
     }
     console.log();
-    console.log(chalk.bold.yellow('Present the following progress tracker to the user (copy it verbatim):'));
-    printProgressTracker(current);
-    console.log();
-    console.log(chalk.yellow('For the CURRENT step (→), show each checklist item with ✓ (done) or ✗ (skipped + reason).'));
-    console.log(chalk.yellow('If any items are ✗, explain why and ask if the user wants to address them.'));
-    console.log();
-    if (current < 16) {
+    if (current < totalSteps) {
         console.log(chalk.green('When done, run: ') +
             chalk.bold(`codeyam editor ${current + 1}`));
     }
     else {
-        console.log(chalk.green('Feature complete! Run: ') +
-            chalk.bold('codeyam editor 1') +
-            chalk.green(' to start the next feature'));
+        console.log(chalk.green('Feature complete! Ask the user what to build next, then run: ') + chalk.bold('codeyam editor 1'));
     }
     console.log();
 }
@@ -418,34 +562,36 @@ function printResumptionHeader(step) {
             'Check if plan was already written to context file:\n      `cat .codeyam/editor-mode-context.md`',
         ],
         2: ['Check if project files already exist:\n      `ls package.json src/`'],
-        3: ['This is a confirmation step — just re-present to user'],
-        4: [
+        3: ['Re-check is safe — just re-run the step'],
+        4: ['Re-verify is safe to repeat — just re-run the checks'],
+        5: ['This is a confirmation step — just re-present to user'],
+        6: [
             'Check if extraction plan already exists in context file:\n      `cat .codeyam/editor-mode-context.md`',
         ],
-        5: [
+        7: [
             'Check if components/functions already extracted:\n      `ls src/components/ src/lib/`',
         ],
-        6: [
+        8: [
             'Check if glossary already populated:\n      `cat .codeyam/glossary.json`',
         ],
-        7: ['Check if isolation routes and registered scenarios already exist'],
-        8: ['Check existing scenarios:\n      `codeyam editor scenarios`'],
-        9: [
+        9: ['Check if isolation routes and registered scenarios already exist'],
+        10: ['Check existing scenarios:\n      `codeyam editor scenarios`'],
+        11: [
             'Check existing user-persona scenarios:\n      `codeyam editor scenarios`',
         ],
-        10: ['Re-verify is safe to repeat — just re-run the checks'],
-        11: [
+        12: ['Re-verify is safe to repeat — just re-run the checks'],
+        13: [
             'Check if a journal entry already exists for this feature:\n      `codeyam editor journal-list`',
             'If an entry exists, use PATCH to update it — do NOT create a new one',
         ],
-        12: ['Re-verify is safe to repeat — just re-run the checks'],
-        13: ['Check if commit already made:\n      `git log --oneline -3`'],
-        14: ['Check if commit already made:\n      `git log --oneline -3`'],
-        15: [
+        14: ['Re-verify is safe to repeat — just re-run the checks'],
+        15: ['Check if commit already made:\n      `git log --oneline -3`'],
+        16: ['Check if commit already made:\n      `git log --oneline -3`'],
+        17: [
             'Check if journal was already updated with commit SHA:\n      `codeyam editor journal-list`',
             'Check if commit was already amended:\n      `git log --oneline -3`',
         ],
-        16: [
+        18: [
             'Check if already pushed:\n      `git remote -v && git log --oneline origin/HEAD..HEAD 2>/dev/null`',
         ],
     };
@@ -552,7 +698,7 @@ function parseDebugTargets(target) {
         }
         if (entry.startsWith('step-')) {
             const num = parseInt(entry.replace('step-', ''), 10);
-            if (!isNaN(num) && num >= 1 && num <= 16) {
+            if (!isNaN(num) && num >= 1 && num <= 18) {
                 valid.add(`step-${num}`);
                 continue;
             }
@@ -638,11 +784,17 @@ function printSetup(root) {
     console.log();
     // ── Design System ────────────────────────────────────────────────
     console.log(chalk.bold('Design System (ask FIRST):'));
-    console.log(chalk.dim('  Ask: "Do you have a design system, brand guidelines, or style preferences you\'d like me to follow?"'));
+    console.log(chalk.dim('  Ask: "What visual style do you want? Pick a built-in design system or bring your own."'));
     console.log(chalk.dim('  Use AskUserQuestion with these EXACT option labels:'));
-    console.log(chalk.yellow('    Option 1 label: "Yes, I\'ll paste my design system"'));
+    console.log();
+    for (const ds of DESIGN_SYSTEMS) {
+        console.log(chalk.yellow(`    Option label: "${ds.name}"`) +
+            chalk.dim(` — ${ds.description}`));
+        console.log(chalk.dim(`       → Run: codeyam editor design-system ${ds.id}`));
+    }
+    console.log(chalk.yellow('    Option label: "I\'ll paste my own design system"'));
     console.log(chalk.dim('       → Wait for paste, save to .codeyam/design-system.md, confirm with brief summary'));
-    console.log(chalk.yellow('    Option 2 label: "No, use sensible defaults"'));
+    console.log(chalk.yellow('    Option label: "Skip — use sensible defaults"'));
     console.log(chalk.dim('       → Skip'));
     console.log();
     console.log(chalk.bold('Checklist:'));
@@ -663,8 +815,8 @@ function printSetup(root) {
     console.log(chalk.bold('Tech Stack Selection:'));
     console.log(chalk.dim('  Based on the selected formats, present ONLY the matching tech stacks.'));
     console.log(chalk.dim('  A stack matches if ANY of the user\'s selected formats appears in its "Supports" list.'));
-    console.log(chalk.dim('  Show ALL matching stacks even if there is only one. Mark the recommended option.'));
-    console.log(chalk.dim('  Use AskUserQuestion to let the user pick one.'));
+    console.log(chalk.dim('  If only ONE stack matches, confirm it directly (e.g. "Expo + React Native is the only stack for mobile apps — using that.").'));
+    console.log(chalk.dim('  If MULTIPLE stacks match, use AskUserQuestion to let the user pick one.'));
     console.log();
     console.log(chalk.bold('  Available Tech Stacks:'));
     for (const stack of TECH_STACKS) {
@@ -697,7 +849,7 @@ function printSetup(root) {
     console.log(chalk.yellow('    ( ) Mobile') + chalk.dim(' — 375 × 667'));
     console.log(chalk.yellow('    ( ) Custom') + chalk.dim(' — ask for width × height'));
     console.log();
-    console.log(chalk.dim('  Pre-select based on app format: mobile-responsive-web-app/desktop-app → Desktop, mobile-app → Mobile, chrome-extension → Custom (400×600).'));
+    console.log(chalk.dim('  Pre-select based on app format: mobile-responsive-web-app/desktop-app → Desktop, mobile-app → iPhone 16 (393×852), chrome-extension → Custom (400×600).'));
     console.log(chalk.dim('  If only one obvious choice, confirm it rather than asking.'));
     console.log(chalk.dim(`  Save the choice via: curl -s -X POST http://localhost:${port}/api/editor-project-info -H "Content-Type: application/json" -d '{"defaultScreenSize":{"name":"Desktop","width":1440,"height":900}}'`));
     console.log();
@@ -769,37 +921,39 @@ function printCycleOverview(root, state) {
         console.log();
         console.log(chalk.green('Continue with: ') +
             chalk.bold(`codeyam editor ${state.step}`));
-        console.log(chalk.dim('Or run ') +
-            chalk.bold('codeyam editor 1') +
-            chalk.dim(' to start a new feature'));
+        console.log(chalk.dim('Or ask the user what to build next, then run `codeyam editor 1` yourself (never expose this command to the user)'));
         console.log();
         console.log(chalk.yellow('If the user reports a bug or requests any change, run: ') +
             chalk.bold('codeyam editor change'));
         console.log(chalk.yellow('This applies even after committing — always use the change workflow.'));
     }
     else {
-        console.log('Each feature follows 16 steps. You MUST run each command in order:');
+        console.log('Each feature follows 18 steps. You MUST run each command in order:');
         console.log();
-        console.log(`  ${chalk.bold.yellow(' 1')} ${chalk.bold('Plan')}            — Plan the feature, confirm with user`);
-        console.log(`  ${chalk.bold.yellow(' 2')} ${chalk.bold('Prototype')}       — Build a working prototype fast`);
-        console.log(`  ${chalk.bold.yellow(' 3')} ${chalk.bold('Confirm')}         — Confirm prototype with user`);
-        console.log(`  ${chalk.bold.yellow(' 4')} ${chalk.bold('Deconstruct')}     — Read code, plan all extractions`);
-        console.log(`  ${chalk.bold.yellow(' 5')} ${chalk.bold('Extract')}         — TDD extraction of functions + components`);
-        console.log(`  ${chalk.bold.yellow(' 6')} ${chalk.bold('Glossary')}        — Record functions in glossary`);
-        console.log(`  ${chalk.bold.yellow(' 7')} ${chalk.bold('Analyze')}         — Analyze and verify components`);
-        console.log(`  ${chalk.bold.yellow(' 8')} ${chalk.bold('App Scenarios')}   — Create app-level scenarios`);
-        console.log(`  ${chalk.bold.yellow(' 9')} ${chalk.bold('User Scenarios')}  — Create user-persona scenarios`);
-        console.log(`  ${chalk.bold.yellow('10')} ${chalk.bold('Verify')}          — Review screenshots, check for errors`);
-        console.log(`  ${chalk.bold.yellow('11')} ${chalk.bold('Journal')}         — Create/update journal entry`);
-        console.log(`  ${chalk.bold.yellow('12')} ${chalk.bold('Review')}          — Verify screenshots and audit`);
-        console.log(`  ${chalk.bold.yellow('13')} ${chalk.bold('Present')}         — Present summary, get approval`);
-        console.log(`  ${chalk.bold.yellow('14')} ${chalk.bold('Commit')}          — Commit all changes`);
-        console.log(`  ${chalk.bold.yellow('15')} ${chalk.bold('Finalize')}        — Journal update + amend commit`);
-        console.log(`  ${chalk.bold.yellow('16')} ${chalk.bold('Push')}            — Push to remote`);
+        console.log(`  ${chalk.bold.yellow(' 1')} ${chalk.bold('Plan')}               — Plan the feature, confirm with user`);
+        console.log(`  ${chalk.bold.yellow(' 2')} ${chalk.bold('Prepare')}            — Set up project and dependencies`);
+        console.log(`  ${chalk.bold.yellow(' 3')} ${chalk.bold('Prototype')}          — Build a working prototype fast`);
+        console.log(`  ${chalk.bold.yellow(' 4')} ${chalk.bold('Verify Prototype')}   — Verify prototype works correctly`);
+        console.log(`  ${chalk.bold.yellow(' 5')} ${chalk.bold('Confirm')}            — Confirm prototype with user`);
+        console.log(`  ${chalk.bold.yellow(' 6')} ${chalk.bold('Deconstruct')}        — Read code, plan all extractions`);
+        console.log(`  ${chalk.bold.yellow(' 7')} ${chalk.bold('Extract')}            — TDD extraction of functions + components`);
+        console.log(`  ${chalk.bold.yellow(' 8')} ${chalk.bold('Glossary')}           — Record functions in glossary`);
+        console.log(`  ${chalk.bold.yellow(' 9')} ${chalk.bold('Analyze')}            — Analyze and verify components`);
+        console.log(`  ${chalk.bold.yellow('10')} ${chalk.bold('App Scenarios')}      — Create app-level scenarios`);
+        console.log(`  ${chalk.bold.yellow('11')} ${chalk.bold('User Scenarios')}     — Create user-persona scenarios`);
+        console.log(`  ${chalk.bold.yellow('12')} ${chalk.bold('Verify')}             — Review screenshots, check for errors`);
+        console.log(`  ${chalk.bold.yellow('13')} ${chalk.bold('Journal')}            — Create/update journal entry`);
+        console.log(`  ${chalk.bold.yellow('14')} ${chalk.bold('Review')}             — Verify screenshots and audit`);
+        console.log(`  ${chalk.bold.yellow('15')} ${chalk.bold('Present')}            — Present summary, get approval`);
+        console.log(`  ${chalk.bold.yellow('16')} ${chalk.bold('Commit')}             — Commit all changes`);
+        console.log(`  ${chalk.bold.yellow('17')} ${chalk.bold('Finalize')}           — Journal update + amend commit`);
+        console.log(`  ${chalk.bold.yellow('18')} ${chalk.bold('Push')}               — Push to remote`);
         console.log();
-        console.log(chalk.green('Start now: ') + chalk.bold('codeyam editor 1'));
+        console.log(chalk.green('Start now: ') +
+            'Ask the user what they want to build, then run `codeyam editor 1` (never expose this command to the user)');
         console.log(chalk.dim('  If the user already described what they want, pass it: codeyam editor 1 --prompt "their message"'));
     }
+    console.log(chalk.dim('If stuck on CLI commands, scenarios, or debugging, read: .codeyam/docs/editor-reference.md'));
     console.log();
 }
 // ─── Step 1: Plan ─────────────────────────────────────────────────────
@@ -875,18 +1029,12 @@ function printStep1(root, feature, options, userPrompt) {
     console.log();
     console.log(chalk.yellow('Wait for user confirmation before moving on.'));
     console.log();
-    console.log(chalk.bold.yellow('Present the following progress tracker to the user (copy it verbatim):'));
-    printProgressTracker(1);
-    console.log();
-    console.log(chalk.yellow('For the CURRENT step (→), show each checklist item with ✓ (done) or ✗ (skipped + reason).'));
-    console.log(chalk.yellow('If any items are ✗, explain why and ask if the user wants to address them.'));
-    console.log();
     console.log(chalk.green('When done, run: ') +
         chalk.bold('codeyam editor 2 --feature "Feature Name"'));
     console.log(chalk.dim('  Replace "Feature Name" with a short title for what you just described.'));
     console.log();
 }
-// ─── Step 2: Prototype ────────────────────────────────────────────────
+// ─── Step 2: Prepare ──────────────────────────────────────────────────
 function printStep2(root, feature) {
     const port = getServerPort();
     const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
@@ -903,41 +1051,87 @@ function printStep2(root, feature) {
         appFormats: prevState?.appFormats,
         techStackId: prevState?.techStackId,
     });
-    logEvent(root, 'step', { step: 2, label: 'Prototype', feature });
-    stepHeader(2, 'Prototype', feature);
+    logEvent(root, 'step', { step: 2, label: 'Prepare', feature });
+    stepHeader(2, 'Prepare', feature);
     if (isResuming) {
         printResumptionHeader(2);
     }
-    console.log('Build fast with real data. Prioritize speed over quality.');
+    console.log('Get the project ready to build.');
     console.log();
+    const ctx = getTechStackContext(root);
     // If no project exists yet, include scaffolding instructions first
     if (!projectExists) {
         console.log(chalk.bold('Scaffold the project:'));
         checkbox('Run `codeyam editor template` to scaffold, install dependencies, init git, and configure CodeYam');
-        console.log(chalk.dim('  This copies the Next.js + Prisma 7 + SQLite template, runs npm install,'));
+        if (ctx.isExpo) {
+            console.log(chalk.dim('  This copies the Expo + React Native template, runs npm install,'));
+        }
+        else if (ctx.isChromeExt) {
+            console.log(chalk.dim('  This copies the Chrome Extension + React template, runs npm install,'));
+        }
+        else {
+            console.log(chalk.dim('  This copies the Next.js + Prisma 7 + SQLite template, runs npm install,'));
+        }
         console.log(chalk.dim('  initializes git, runs codeyam init, and refreshes the editor — all in one command.'));
         console.log();
-        checkbox('Define your data models in `prisma/schema.prisma`');
-        console.log(chalk.dim("  Replace the placeholder Todo model with your app's models"));
-        console.log();
-        checkbox('Push schema and seed the database');
-        console.log(chalk.dim('  npm run db:push'));
-        console.log(chalk.dim('  # Edit prisma/seed.ts with your seed data, then:'));
-        console.log(chalk.dim('  npm run db:seed'));
-        console.log(chalk.dim(`  # After re-seeding, restart the dev server to pick up fresh data:`));
-        console.log(chalk.dim(`  # codeyam editor dev-server '{"action":"restart"}'`));
-        console.log();
-        console.log(chalk.yellow('  IMPORTANT: When adding new required columns to existing tables,'));
-        console.log(chalk.yellow('  provide a @default(...) value so `db push` can fill existing rows.'));
-        console.log(chalk.dim('  Example: userId String @default("anonymous")  — existing rows get "anonymous"'));
-        console.log(chalk.dim('  Without a default, Prisma requires --force-reset which drops ALL data.'));
-        console.log(chalk.dim('  NEVER use --force-reset — it is blocked in this environment.'));
-        console.log();
-        console.log(chalk.dim('  See DATABASE.md for Prisma patterns and important warnings.'));
-        console.log(chalk.dim('  Key: import { prisma } from "@/app/lib/prisma" in API routes.'));
-        console.log(chalk.dim('  Key: Seed scripts must use the adapter pattern (see prisma/seed.ts).'));
-        console.log();
-        console.log(chalk.bold('Build the feature:'));
+        if (ctx.isExpo) {
+            // Expo: no database, use AsyncStorage + theme
+            checkbox('Define your data types in `lib/types.ts`');
+            console.log(chalk.dim("  Create TypeScript interfaces for your app's data models"));
+            console.log();
+            checkbox('Set up initial data using the storage helper in `lib/storage.ts`');
+            console.log(chalk.dim('  import { storage } from "@/lib/storage";'));
+            console.log(chalk.dim('  await storage.set("items", [{ id: "1", title: "First item" }]);'));
+            console.log();
+            console.log(chalk.dim('  Read MOBILE_SETUP.md for data storage, navigation, and testing patterns.'));
+            console.log();
+            checkbox('Ask the user what to name the app (use AskUserQuestion), then update app.json');
+            console.log(chalk.dim('  Update name, slug, scheme, ios.bundleIdentifier (com.codeyam.<slug>), and android.package'));
+            console.log(chalk.dim('  Also set the projectTitle via: curl -s -X POST http://localhost:' +
+                port +
+                '/api/editor-project-info -H "Content-Type: application/json" -d \'{"projectTitle":"<name>"}\''));
+            console.log();
+            checkbox('Generate an app icon using `sharp`');
+            console.log(chalk.dim('  Create `scripts/generate-icon.mjs` and `mkdir -p assets`'));
+            console.log(chalk.yellow('  ICON DESIGN GOAL: The icon must look distinctive on a home screen full of other app icons.'));
+            console.log(chalk.yellow('  Use multiple bold colors from the design system and complex, overlapping shapes.'));
+            console.log(chalk.yellow('  NO simple/minimal icons — no single glyph on a flat background, no plain text, no basic circles.'));
+            console.log(chalk.yellow('  Make it colorful, layered, and dense. Use gradients, multiple contrasting fills, and depth.'));
+            console.log(chalk.dim('  Use sharp to render SVG to 1024x1024 PNG. iOS: flatten onto background (no alpha channel).'));
+            console.log(chalk.dim('  Generate: icon.png, adaptive-icon.png, favicon.png (48x48). Run `node scripts/generate-icon.mjs`'));
+            console.log();
+        }
+        else if (ctx.isChromeExt) {
+            // Chrome Extension: use chrome.storage
+            checkbox('Set up data storage using chrome.storage (with localStorage fallback for dev)');
+            console.log();
+            console.log(chalk.dim('  Read EXTENSION_SETUP.md for storage, messaging, and manifest patterns.'));
+            console.log();
+        }
+        else {
+            // Next.js: Prisma + database
+            checkbox('Define your data models in `prisma/schema.prisma`');
+            console.log(chalk.dim("  Replace the placeholder Todo model with your app's models"));
+            console.log();
+            checkbox('Push schema and seed the database');
+            console.log(chalk.dim('  npm run db:push'));
+            console.log(chalk.dim('  # Edit prisma/seed.ts with your seed data, then:'));
+            console.log(chalk.dim('  npm run db:seed'));
+            console.log(chalk.dim(`  # After re-seeding, restart the dev server to pick up fresh data:`));
+            console.log(chalk.dim(`  # codeyam editor dev-server '{"action":"restart"}'`));
+            console.log();
+            console.log(chalk.yellow('  IMPORTANT: When adding new required columns to existing tables,'));
+            console.log(chalk.yellow('  provide a @default(...) value so `db push` can fill existing rows.'));
+            console.log(chalk.dim('  Example: userId String @default("anonymous")  — existing rows get "anonymous"'));
+            console.log(chalk.dim('  Without a default, Prisma requires --force-reset which drops ALL data.'));
+            console.log(chalk.dim('  NEVER use --force-reset — it is blocked in this environment.'));
+            console.log();
+            console.log(chalk.dim('  See DATABASE.md for Prisma patterns and important warnings.'));
+            console.log(chalk.dim('  Key: import { prisma } from "@/app/lib/prisma" in API routes.'));
+            console.log(chalk.dim('  Key: Seed scripts must use the adapter pattern (see prisma/seed.ts).'));
+            console.log();
+        }
+        printDataStructureInstructions();
     }
     else {
         console.log(chalk.bold('Prepare the database for this feature:'));
@@ -952,18 +1146,68 @@ function printStep2(root, feature) {
         console.log(chalk.dim('    This switches the active scenario, runs the seed adapter, and refreshes the preview.'));
         console.log(chalk.dim('    If no existing scenario fits, use the default seed: npm run db:seed'));
         console.log();
+        printDataStructureInstructions();
+    }
+    stopGate(2);
+}
+// ─── Step 3: Prototype ────────────────────────────────────────────────
+function printStep3(root, feature) {
+    const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
+    const projectExists = hasProject(root);
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 3;
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature,
+        step: 3,
+        label: STEP_LABELS[3],
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
+    });
+    logEvent(root, 'step', { step: 3, label: 'Prototype', feature });
+    stepHeader(3, 'Prototype', feature);
+    if (isResuming) {
+        printResumptionHeader(3);
     }
+    const ctx = getTechStackContext(root);
+    console.log('Build fast with real data. Prioritize speed over quality.');
+    console.log();
     console.log(chalk.bold('Checklist:'));
-    checkbox('Create API routes that read from the database via Prisma');
-    if (!projectExists) {
-        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 (ctx.isExpo) {
+        checkbox('Build screens that read from AsyncStorage via `lib/storage.ts` or fetch from APIs');
+        if (!projectExists) {
+            checkbox('Populate initial data in AsyncStorage for development');
+            console.log(chalk.dim('    import { storage } from "@/lib/storage";'));
+            console.log(chalk.dim('    await storage.set("items", [{ id: "1", title: "Buy groceries" }]);'));
+            console.log();
+            console.log(chalk.bold.cyan('Make data visually rich:'));
+            console.log(chalk.cyan('  • Write realistic, varied content — not "Item 1", "Item 2", "Test Description"'));
+            console.log(chalk.cyan('  • Include different text lengths, categories, dates, and statuses'));
+            console.log(chalk.cyan('  • Rich data makes the prototype look real and surfaces layout issues early'));
+        }
+    }
+    else {
+        checkbox('Create API routes that read from the database via Prisma');
+        if (!projectExists) {
+            checkbox('Seed the database with demo data');
+            checkbox('Create `.codeyam/seed-adapter.ts` so CodeYam can seed the database for scenarios');
+            console.log(chalk.dim('    The seed adapter reads a JSON file (path passed as CLI arg), wipes tables, inserts rows.'));
+            console.log(chalk.dim("    Use the project's own ORM (Prisma, Drizzle, etc.). See template for example."));
+            console.log(chalk.dim('    Run with: npx tsx .codeyam/seed-adapter.ts <path-to-seed-data.json>'));
+            console.log();
+            console.log(chalk.bold.cyan('Make seed data visually rich:'));
+            console.log(chalk.cyan('  • Use real placeholder images from Unsplash (https://images.unsplash.com/photo-<id>?w=400&h=300&fit=crop)'));
+            console.log(chalk.cyan('  • Use avatar services like i.pravatar.cc for user profile photos'));
+            console.log(chalk.cyan('  • Write realistic, varied content — not "Item 1", "Item 2", "Test Description"'));
+            console.log(chalk.cyan('  • Include different text lengths, categories, dates, and statuses'));
+            console.log(chalk.cyan('  • Rich seed data makes the prototype look real and surfaces layout issues early'));
+        }
     }
     checkbox('Verify the dev server shows the changes');
-    checkbox('If the feature involves auth, email, payments, or other common patterns: read FEATURE_PATTERNS.md');
+    checkbox(`If the feature involves auth, email, payments, or other common patterns: read ${ctx.patternsFile}`);
     // Responsive design guidance when building a mobile-responsive web app
     if (prevState?.appFormats?.includes('mobile-responsive-web-app')) {
         console.log();
@@ -980,16 +1224,33 @@ function printStep2(root, feature) {
         console.log();
         console.log(designSystem);
         console.log();
-        checkbox('Define ALL design tokens as CSS custom properties in globals.css — not just colors');
-        console.log(chalk.dim('    Colors: --bg-surface, --text-primary, --accent-green-a, etc.'));
-        console.log(chalk.dim('    Typography: --text-xs, --text-sm, --text-lg, --text-2xl (font-size values)'));
-        console.log(chalk.dim('    Font weights: --font-weight-normal, --font-weight-medium, --font-weight-semibold'));
-        console.log(chalk.dim('    Spacing: --spacing-xs, --spacing-sm, --spacing-md, --spacing-lg, etc.'));
-        console.log(chalk.dim('    Border radius, shadows, transitions — every value the design system defines.'));
-        checkbox('Reference tokens from components — ZERO hardcoded px values for font-size, spacing, or colors');
-        console.log(chalk.dim('    Bad:  fontSize: 14, padding: "12px 16px", gap: 8'));
-        console.log(chalk.dim('    Good: fontSize: "var(--text-sm)", padding: "var(--spacing-md) var(--spacing-lg)", gap: "var(--spacing-sm)"'));
-        console.log(chalk.dim('    This ensures the entire app updates when the design system changes.'));
+        if (ctx.isExpo) {
+            checkbox('Define ALL design tokens in `lib/theme.ts` — this is the single source of truth');
+            console.log(chalk.dim('    Colors: theme.colors.bgSurface, theme.colors.textPrimary, etc.'));
+            console.log(chalk.dim('    Typography: theme.fontSize.sm, theme.fontSize.lg, theme.fontFamily.mono'));
+            console.log(chalk.dim('    Spacing: theme.spacing.sm, theme.spacing.md, theme.spacing.lg, etc.'));
+            console.log(chalk.dim('    Border radius: theme.borderRadius.sm, theme.borderRadius.lg, etc.'));
+            checkbox('Import theme in every component — ZERO hardcoded color strings or pixel values');
+            console.log(chalk.dim('    Bad:  color: "#333", fontSize: 14, padding: 12'));
+            console.log(chalk.dim('    Good: color: theme.colors.textPrimary, fontSize: theme.fontSize.sm, padding: theme.spacing.md'));
+            console.log(chalk.dim('    Do NOT use CSS custom properties (var(--token)) — they do not work in React Native.'));
+            checkbox('Buttons: put backgroundColor, borderRadius, borderStyle on a wrapping <View>, NOT on <Pressable>');
+            console.log(chalk.dim('    Pressable renders these styles on web but FAILS SILENTLY on native devices.'));
+            console.log(chalk.dim('    Use a <View> with overflow:"hidden" for the visual shell, <Pressable> inside for touch only.'));
+            console.log(chalk.dim('    For press feedback: use onPressIn/onPressOut + useState to toggle opacity, not function-style style.'));
+        }
+        else {
+            checkbox('Define ALL design tokens as CSS custom properties in globals.css — not just colors');
+            console.log(chalk.dim('    Colors: --bg-surface, --text-primary, --accent-green-a, etc.'));
+            console.log(chalk.dim('    Typography: --text-xs, --text-sm, --text-lg, --text-2xl (font-size values)'));
+            console.log(chalk.dim('    Font weights: --font-weight-normal, --font-weight-medium, --font-weight-semibold'));
+            console.log(chalk.dim('    Spacing: --spacing-xs, --spacing-sm, --spacing-md, --spacing-lg, etc.'));
+            console.log(chalk.dim('    Border radius, shadows, transitions — every value the design system defines.'));
+            checkbox('Reference tokens from components — ZERO hardcoded px values for font-size, spacing, or colors');
+            console.log(chalk.dim('    Bad:  fontSize: 14, padding: "12px 16px", gap: 8'));
+            console.log(chalk.dim('    Good: fontSize: "var(--text-sm)", padding: "var(--spacing-md) var(--spacing-lg)", gap: "var(--spacing-sm)"'));
+            console.log(chalk.dim('    This ensures the entire app updates when the design system changes.'));
+        }
     }
     console.log();
     console.log(chalk.bold.cyan('Keep the preview moving:'));
@@ -1000,16 +1261,41 @@ function printStep2(root, feature) {
     console.log(chalk.cyan('  If you build a NEW page (e.g., /drinks/[id]), navigate the preview there:'));
     console.log(chalk.cyan(`  codeyam editor preview '{"path":"/drinks/1","dimension":"${dim}"}'`));
     printDimensionGuidance(dim, dimNames);
+    console.log(chalk.red.bold('  NEVER claim "you should see X" or "the preview shows X" unless you just ran a preview command.'));
+    console.log(chalk.red('  The preview only updates when you explicitly refresh it. Verify, then describe.'));
+    console.log();
+    stopGate(3);
+}
+// ─── Step 4: Verify Prototype ─────────────────────────────────────────
+function printStep4(root, feature) {
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 4;
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature,
+        step: 4,
+        label: STEP_LABELS[4],
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
+    });
+    logEvent(root, 'step', { step: 4, label: 'Verify Prototype', feature });
+    stepHeader(4, 'Verify Prototype', feature);
+    if (isResuming) {
+        printResumptionHeader(4);
+    }
+    console.log('Verify everything works before presenting the prototype.');
     console.log();
     console.log(chalk.bold('Verify the dev server:'));
-    console.log(chalk.dim(`  # Get dev server URL: codeyam editor dev-server`));
-    console.log(chalk.dim('  # Check page loads: curl -s -o /dev/null -w "%{http_code}" http://localhost:<dev-port>'));
-    console.log(chalk.dim('  # Check API routes: curl -s http://localhost:<dev-port>/api/your-route'));
+    console.log(chalk.dim('  # Verify pages and API routes load:'));
+    console.log(chalk.dim(`  codeyam editor verify-routes '{"paths":["/your-page"],"apiRoutes":["/api/your-route"]}'`));
     console.log();
     console.log(chalk.bold('Verify before proceeding:'));
     console.log(chalk.yellow('  Verify everything works before presenting the prototype to the user.'));
-    checkbox('Verify the page loads: curl the dev server URL and confirm HTTP 200 (not an error page)');
-    checkbox('Verify API routes return valid JSON: curl each route and confirm no error responses');
+    checkbox('Verify page and API routes: `codeyam editor verify-routes \'{"paths":["/"],"apiRoutes":["/api/your-route"]}\'`');
+    console.log(chalk.dim('    Include ALL page paths you built and ALL API routes they depend on.'));
     checkbox('Check for broken images: `codeyam editor verify-images \'{"paths":["/"], "imageUrls":["url1","url2"]}\'`');
     console.log(chalk.dim('    Pass ALL page paths and ALL image URLs you used in seed data / API responses.'));
     console.log(chalk.dim('    Client-rendered pages need imageUrls — the HTML shell has no images to scan.'));
@@ -1020,6 +1306,14 @@ function printStep2(root, feature) {
     console.log(chalk.dim('    The user is looking at the preview — a blank page means something is broken.'));
     console.log(chalk.dim('    If any check fails, fix the issue and re-verify before proceeding.'));
     console.log();
+    const ctx4 = getTechStackContext(root);
+    if (ctx4.isExpo) {
+        console.log(chalk.magenta.bold('  EXPO WEB PREVIEW NOTE:'));
+        console.log(chalk.magenta('  The preview renders via react-native-web in a browser. Some differences'));
+        console.log(chalk.magenta('  from native devices are expected (fonts, SafeAreaView, shadows, Platform.OS).'));
+        console.log(chalk.magenta('  The preview is for layout and data verification. Test final polish on device.'));
+        console.log();
+    }
     console.log(chalk.bold('Update README and setup script:'));
     checkbox('Update `README.md`: set the project name, write a one-line description, and list any setup prerequisites');
     checkbox('Update `npm run setup` in `package.json` if setup requires extra steps (e.g. env vars, external services)');
@@ -1027,32 +1321,34 @@ function printStep2(root, feature) {
     console.log(chalk.dim('    A new clone should work with just: git clone → npm run setup → npm run dev'));
     console.log();
     console.log(chalk.dim('Focus on building the prototype. Scenarios and refactoring happen in later steps.'));
-    stopGate(2);
+    stopGate(4);
 }
-// ─── Step 3: Confirm ──────────────────────────────────────────────────
-function printStep3(root, feature) {
+// ─── Step 5: Confirm ──────────────────────────────────────────────────
+function printStep5(root, feature) {
     const port = getServerPort();
     const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
-    const isResuming = prevState?.step === 3;
+    const isResuming = prevState?.step === 5;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 3,
-        label: STEP_LABELS[3],
+        step: 5,
+        label: STEP_LABELS[5],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
-    logEvent(root, 'step', { step: 3, label: 'Confirm', feature });
-    stepHeader(3, 'Confirm', feature);
+    logEvent(root, 'step', { step: 5, label: 'Confirm', feature });
+    stepHeader(5, 'Confirm', feature);
     if (isResuming) {
-        printResumptionHeader(3);
+        printResumptionHeader(5);
     }
     console.log('Summarize what was built and get user confirmation.');
     console.log();
     console.log(chalk.bold('Before presenting — verify everything works:'));
     checkbox(`Refresh the preview: \`codeyam editor preview '{"dimension":"${dim}"}'\` — check the \`preview\` field for \`healthy: false\``);
-    checkbox('Verify API routes return valid data (curl each route)');
+    checkbox('Verify routes: `codeyam editor verify-routes \'{"paths":["/"],"apiRoutes":["/api/your-route"]}\'`');
     console.log();
     console.log(chalk.bold.red('  Verify EVERY image loads (this is the #1 source of broken prototypes):'));
     checkbox('Run `codeyam editor verify-images \'{"paths":["/"], "imageUrls":["url1","url2"]}\'`');
@@ -1063,12 +1359,19 @@ function printStep3(root, feature) {
     console.log(chalk.dim('    If there are errors, fix the underlying issue before presenting.'));
     checkbox('Verify `hasContent=true` and `liveErrors=0` — do NOT ask the user to confirm if the preview is broken');
     console.log();
+    console.log(chalk.bold('Verify the captured user prompt:'));
+    checkbox("Read `.codeyam/editor-user-prompt.txt` — this is the user's original feature request");
+    checkbox('If the file is missing or does not match what the user actually asked for, write the correct prompt text to `.codeyam/editor-user-prompt.txt`');
+    console.log(chalk.dim("    This must be the user's exact words, not a summary. It gets recorded in the journal."));
+    console.log();
     console.log(chalk.bold('Then present to the user:'));
     checkbox('Summarize what was built (routes, components, data)');
     checkbox(`Navigate the preview to the feature's primary page: \`codeyam editor preview '{"path":"/your-page","dimension":"${dim}"}'\``);
     printDimensionGuidance(dim, dimNames);
     console.log(chalk.dim('    The user needs to SEE the new feature. If you built a new page, navigate there.'));
     console.log(chalk.dim('    If you modified an existing page, refresh the preview to show the changes.'));
+    console.log(chalk.red.bold('    NEVER claim "you should see X" or "the preview shows X" unless you just ran a preview command.'));
+    console.log(chalk.red('    The preview only updates when you explicitly call `codeyam editor preview`. Verify, then describe.'));
     console.log();
     console.log(chalk.bold.cyan('Guide the user through interactive testing:'));
     checkbox('Tell the user: "The preview is fully interactive — click around to test!"');
@@ -1076,80 +1379,91 @@ function printStep3(root, feature) {
     checkbox('Ask the user: "Does everything work as expected?"');
     console.log();
     console.log(chalk.bold('Present a selection menu to the user (use AskUserQuestion with these EXACT option labels):'));
-    console.log(chalk.green('    Option 1 label: "The live preview is displaying what I expected"') + chalk.dim(' — proceed to step 4'));
+    console.log(chalk.green('    Option 1 label: "The live preview is displaying what I expected"') + chalk.dim(' — proceed to step 6'));
     console.log(chalk.yellow('    Option 2 label: "I\'d like some changes"') +
-        chalk.dim(' — make changes, refresh preview, re-run `codeyam editor 3`'));
+        chalk.dim(' — make changes, refresh preview, re-run `codeyam editor 5`'));
     console.log();
     console.log(chalk.dim('Wait for user approval before moving on. Refactoring and scenarios happen in later steps.'));
-    stopGate(3, { confirm: true });
+    stopGate(5, { confirm: true });
 }
-// ─── Step 4: Deconstruct ──────────────────────────────────────────────
-function printStep4(root, feature) {
+// ─── Step 6: Deconstruct ──────────────────────────────────────────────
+function printStep6(root, feature) {
     const prevState = readState(root);
-    const isResuming = prevState?.step === 4;
+    const isResuming = prevState?.step === 6;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 4,
-        label: STEP_LABELS[4],
+        step: 6,
+        label: STEP_LABELS[6],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
-    logEvent(root, 'step', { step: 4, label: 'Deconstruct', feature });
-    stepHeader(4, 'Deconstruct', feature);
+    logEvent(root, 'step', { step: 6, label: 'Deconstruct', feature });
+    stepHeader(6, 'Deconstruct', feature);
     if (isResuming) {
-        printResumptionHeader(4);
+        printResumptionHeader(6);
     }
     console.log(chalk.bold('Goal: pages contain ONLY components. Components contain ONLY sub-components.'));
-    console.log(chalk.yellow('This step is read and plan only. Code extraction happens in step 5.'));
+    console.log(chalk.yellow('This step is read and plan only. Code extraction happens in step 7.'));
     console.log();
     printExtractionPlanInstructions();
-    stopGate(4);
+    stopGate(6);
 }
-// ─── Step 5: Extract ──────────────────────────────────────────────────
-function printStep5(root, feature) {
+// ─── Step 7: Extract ──────────────────────────────────────────────────
+function printStep7(root, feature) {
     const port = getServerPort();
     const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
-    const isResuming = prevState?.step === 5;
+    const isResuming = prevState?.step === 7;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 5,
-        label: STEP_LABELS[5],
+        step: 7,
+        label: STEP_LABELS[7],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
-    logEvent(root, 'step', { step: 5, label: 'Extract', feature });
-    stepHeader(5, 'Extract', feature);
+    logEvent(root, 'step', { step: 7, label: 'Extract', feature });
+    stepHeader(7, 'Extract', feature);
     if (isResuming) {
-        printResumptionHeader(5);
+        printResumptionHeader(7);
     }
-    console.log('Execute your extraction plan from step 4.');
+    const ctx = getTechStackContext(root);
+    console.log('Execute your extraction plan from step 6.');
     console.log();
     console.log(chalk.bold('Components:'));
     checkbox('Extract each component from your plan into its own file');
     checkbox('Page/route files must contain ZERO direct JSX — only imported components');
     checkbox('Every component that renders multiple sections must be split into sub-components');
-    console.log(chalk.dim('    No tests needed — visual verification happens in step 7'));
+    console.log(chalk.dim('    No tests needed — visual verification happens in step 9'));
     console.log();
     console.log(chalk.bold('Library functions AND hooks (TDD):'));
     checkbox('For each function/hook: write MULTIPLE failing tests FIRST, then extract to make them pass');
     console.log(chalk.dim('    Cover: typical inputs, edge cases, empty/null inputs, error conditions'));
     console.log(chalk.dim('    Aim for 3-8 test cases per function depending on complexity'));
     console.log(chalk.dim('    Hooks count as functions — useDrinks, useAuth, etc. all need test files'));
-    checkbox('Place test files next to source: `app/lib/drinks.ts` → `app/lib/drinks.test.ts`');
-    console.log(chalk.yellow('  Tests ARE the only coverage for library functions/hooks — step 7 only captures component screenshots.'));
+    console.log(chalk.dim('    Wrap all tests in a describe("FunctionName", ...) block — the audit matches on this name'));
+    if (ctx.isExpo) {
+        checkbox('Place test files next to source but OUTSIDE `app/` (Expo Router treats all files in app/ as routes): `lib/storage.ts` → `lib/storage.test.ts`, `app/hooks/useCounter.ts` → `__tests__/hooks/useCounter.test.ts`');
+    }
+    else {
+        checkbox('Place test files next to source: `app/lib/drinks.ts` → `app/lib/drinks.test.ts`');
+    }
+    console.log(chalk.yellow('  Tests ARE the only coverage for library functions/hooks — step 9 only captures component screenshots.'));
     console.log();
     console.log(chalk.bold('Recursive pass:'));
     checkbox('Re-read EVERY new file you just created — extract components from components, functions from functions');
     checkbox('Keep going until every file is a thin shell: just imports and composition');
-    console.log(chalk.yellow('    Check: does any file contain raw <div>, <span>, <h1>, <p>, <img>, or <ul>?'));
+    console.log(chalk.yellow(`    Check: does any file contain raw ${ctx.rawPrimitivesList}?`));
     console.log(chalk.yellow('    If yes → that JSX section is a component waiting to be extracted.'));
     console.log();
     console.log(chalk.bold('Verify before proceeding:'));
     checkbox('Run all tests and verify they pass');
-    checkbox('Page files contain ONLY imports + component composition — no raw HTML tags');
+    checkbox(`Page files contain ONLY imports + component composition — no raw ${ctx.isExpo ? 'React Native primitives' : 'HTML tags'}`);
     checkbox('Every component renders ONE thing or composes sub-components — no multi-section JSX');
     checkbox(`Refresh the preview after each batch of extractions: \`codeyam editor preview '{"dimension":"${dim}"}'\``);
     printDimensionGuidance(dim, dimNames);
@@ -1157,93 +1471,106 @@ function printStep5(root, feature) {
     console.log(chalk.dim('Reuse glossary functions when they fit naturally. Extract a new function when the use case diverges.'));
     console.log();
     console.log(chalk.dim('Focus on TDD for functions and extraction for components. Scenarios come in later steps.'));
-    stopGate(5);
+    stopGate(7);
 }
-// ─── Step 6: Glossary ─────────────────────────────────────────────────
-function printStep6(root, feature) {
+// ─── Step 8: Glossary ─────────────────────────────────────────────────
+function printStep8(root, feature) {
     const prevState = readState(root);
-    const isResuming = prevState?.step === 6;
+    const isResuming = prevState?.step === 8;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 6,
-        label: STEP_LABELS[6],
+        step: 8,
+        label: STEP_LABELS[8],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
-    logEvent(root, 'step', { step: 6, label: 'Glossary', feature });
-    stepHeader(6, 'Glossary', feature);
+    logEvent(root, 'step', { step: 8, label: 'Glossary', feature });
+    stepHeader(8, 'Glossary', feature);
     if (isResuming) {
-        printResumptionHeader(6);
+        printResumptionHeader(8);
     }
     console.log('Record all new functions/components in `.codeyam/glossary.json`.');
     console.log();
     printGlossaryInstructions(feature);
     console.log();
     console.log(chalk.dim('Focus on updating the glossary. Application code and scenarios come in later steps.'));
-    stopGate(6);
+    stopGate(8);
 }
-// ─── Step 7: Analyze ──────────────────────────────────────────────────
-function printStep7(root, feature) {
+// ─── Step 9: Analyze ──────────────────────────────────────────────────
+function printStep9(root, feature) {
     const port = getServerPort();
     const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
-    const isResuming = prevState?.step === 7;
+    const isResuming = prevState?.step === 9;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 7,
-        label: STEP_LABELS[7],
+        step: 9,
+        label: STEP_LABELS[9],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
-    logEvent(root, 'step', { step: 7, label: 'Analyze', feature });
-    stepHeader(7, 'Analyze and Verify', feature);
+    logEvent(root, 'step', { step: 9, label: 'Analyze', feature });
+    stepHeader(9, 'Analyze and Verify', feature);
     if (isResuming) {
-        printResumptionHeader(7);
+        printResumptionHeader(9);
     }
     console.log('Verify visual components (via isolation routes) and library functions (via tests).');
     console.log();
     console.log(chalk.bold('Visual Components — Component Isolation:'));
-    checkbox('List all files with new/modified visual components from step 5');
+    checkbox('List all files with new/modified visual components from step 7');
     checkbox('Check existing scenarios: `codeyam editor scenarios`');
     console.log(chalk.dim('    Reuse and improve existing scenarios where possible — update mock data'));
     console.log(chalk.dim('    to reflect current changes. Add new scenarios only for genuinely new states.'));
     console.log(chalk.dim('    Ensure at least one scenario clearly demonstrates what changed in this session.'));
-    printComponentCaptureInstructions();
+    const ctx9 = getTechStackContext(root);
+    printComponentCaptureInstructions(root);
     console.log();
     console.log(chalk.bold('Library Functions — run tests:'));
-    checkbox('Run ALL test files created in step 5');
-    console.log(chalk.dim('    Example: npx vitest run app/lib/drinks.test.ts'));
+    checkbox('Run ALL test files created in step 7');
+    console.log(chalk.dim(`    Example: ${ctx9.testRunCommand} app/lib/drinks.test.ts`));
     checkbox('Verify every test passes');
     checkbox('If any test fails, fix the source code and re-run');
     console.log();
     console.log(chalk.dim('Do not proceed until both component isolations and library tests pass.'));
     console.log();
     checkbox('Run `codeyam editor audit` to verify all components have scenarios and all functions/hooks have tests');
-    console.log(chalk.red.bold('    The audit is a HARD GATE — step 8 will refuse to run until the audit passes.'));
-    console.log(chalk.dim('    When audit passes, the import graph is built automatically for change tracking.'));
+    console.log(chalk.red.bold('    The audit is a HARD GATE — step 10 will refuse to run until the audit passes.'));
+    console.log(chalk.dim('    The audit auto-fixes incomplete entities by running targeted analysis on just the affected files.'));
+    console.log(chalk.dim('    If the audit reports issues (including pre-existing ones), fix ALL of them — do not skip.'));
+    console.log(chalk.dim('    Re-run `codeyam editor audit` until all checks pass. Do NOT run `codeyam editor analyze-imports`'));
+    console.log(chalk.dim('    — the audit runs targeted analysis automatically and is much faster.'));
+    console.log(chalk.dim('    If the audit reports "MANUAL ANALYSIS REQUIRED" for any entities,'));
+    console.log(chalk.dim('    follow the manual analysis steps in the audit output.'));
+    console.log(chalk.dim('    Do NOT re-run analyze-imports for those entities — it will fail again.'));
     console.log();
-    stopGate(7);
+    stopGate(9);
 }
-// ─── Step 8: App Scenarios ────────────────────────────────────────────
-function printStep8(root, feature) {
+// ─── Step 10: App Scenarios ────────────────────────────────────────────
+function printStep10(root, feature) {
     const port = getServerPort();
     const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
-    const isResuming = prevState?.step === 8;
+    const isResuming = prevState?.step === 10;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 8,
-        label: STEP_LABELS[8],
+        step: 10,
+        label: STEP_LABELS[10],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
-    logEvent(root, 'step', { step: 8, label: 'App Scenarios', feature });
-    stepHeader(8, 'App Scenarios', feature);
+    logEvent(root, 'step', { step: 10, label: 'App Scenarios', feature });
+    stepHeader(10, 'App Scenarios', feature);
     if (isResuming) {
-        printResumptionHeader(8);
+        printResumptionHeader(10);
     }
     console.log('Create app-level scenarios with rich data that robustly demonstrates this feature.');
     console.log();
@@ -1257,6 +1584,7 @@ function printStep8(root, feature) {
     console.log(chalk.cyan('  • Include realistic variety — different categories, lengths, statuses, counts'));
     console.log(chalk.cyan("  • Populate optional fields the feature depends on (don't leave them empty)"));
     console.log(chalk.cyan('  • Make content diverse enough that edge cases surface naturally'));
+    console.log(chalk.cyan('  • Use real image URLs (Unsplash, Pravatar) — not broken placeholders or empty strings'));
     console.log(chalk.cyan("  • Think: would this data reveal a bug in the feature? If it's too simple, enrich it."));
     console.log();
     console.log(chalk.bold.cyan('When to create new vs reuse existing:'));
@@ -1265,13 +1593,19 @@ function printStep8(root, feature) {
     console.log(chalk.cyan("  • New data states that can't coexist in one scenario (empty vs rich, error vs success) → new scenario"));
     console.log(chalk.cyan("  • Don't duplicate — if an existing scenario can cover a state with richer data, enhance it instead"));
     console.log();
+    console.log(chalk.bold.cyan('Scenario naming — describe data states, not features:'));
+    console.log(chalk.cyan('  • Name scenarios by what they represent: "Rich Data", "Empty", "Mobile", "Minimal"'));
+    console.log(chalk.cyan('  • When enhancing a scenario with new feature data, update the name if it has grown beyond its original scope'));
+    console.log(chalk.cyan('  • A single rich scenario exercising multiple features is more valuable than separate thin scenarios per feature'));
+    console.log(chalk.cyan('  • Re-register with the same name to update; to rename, register with the new name'));
+    console.log();
     checkbox('Ensure scenarios clearly demonstrate what changed in this session');
     console.log(chalk.dim('    If data models changed: update existing scenarios seed data to match'));
     console.log(chalk.dim('    If UI changed: re-register existing scenarios so screenshots reflect the update'));
     console.log(chalk.dim('    Add new scenarios only for genuinely new data states not covered by existing ones'));
     printAppScenarioInstructions();
     console.log();
-    console.log(chalk.dim('Focus on creating and registering app-level scenarios. Code fixes happen in step 10 if needed.'));
+    console.log(chalk.dim('Focus on creating and registering app-level scenarios. Code fixes happen in step 12 if needed.'));
     console.log();
     console.log(chalk.bold.cyan("Verify your work — screenshots don't lie:"));
     console.log(chalk.cyan('  • View every captured screenshot. Does it show what the scenario name promises?'));
@@ -1282,43 +1616,45 @@ function printStep8(root, feature) {
     console.log(chalk.bold.yellow('GATE: Before proceeding, run `codeyam editor scenario-coverage`'));
     console.log(chalk.yellow('  This checks which existing scenarios have stale screenshots.'));
     console.log(chalk.yellow('  Re-register every stale scenario listed until the check passes.'));
-    stopGate(8);
+    stopGate(10);
 }
-// ─── Step 9: User Scenarios ───────────────────────────────────────────
-function printStep9(root, feature) {
+// ─── Step 11: User Scenarios ───────────────────────────────────────────
+function printStep11(root, feature) {
     const port = getServerPort();
     const prevState = readState(root);
-    const isResuming = prevState?.step === 9;
+    const isResuming = prevState?.step === 11;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 9,
-        label: STEP_LABELS[9],
+        step: 11,
+        label: STEP_LABELS[11],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
-    logEvent(root, 'step', { step: 9, label: 'User Scenarios', feature });
-    stepHeader(9, 'User Scenarios', feature);
+    logEvent(root, 'step', { step: 11, label: 'User Scenarios', feature });
+    stepHeader(11, 'User Scenarios', feature);
     if (isResuming) {
-        printResumptionHeader(9);
+        printResumptionHeader(11);
     }
-    console.log('Create per-persona variations of existing scenarios. Skip to step 10 if no users.');
+    console.log('Create per-persona variations of existing scenarios. Skip to step 12 if no users.');
     console.log();
     console.log(chalk.bold('If the app has NO users/auth:'));
-    console.log(chalk.dim('  Skip this step and proceed to step 10 (Verify).'));
+    console.log(chalk.dim('  Skip this step and proceed to step 12 (Verify).'));
     console.log();
     console.log(chalk.bold('If the app has users/auth:'));
     console.log();
     console.log(chalk.bold('Goal: Create persona variations of EXISTING app scenarios.'));
     console.log(chalk.dim('  Do NOT create standalone persona scenarios. Each user-persona scenario should be'));
-    console.log(chalk.dim('  a variation of an existing app scenario from step 8, with user-specific state layered on.'));
+    console.log(chalk.dim('  a variation of an existing app scenario from step 10, with user-specific state layered on.'));
     console.log();
     console.log(chalk.bold('Checklist:'));
     checkbox('Run `codeyam editor scenarios` — list all existing app scenarios');
     checkbox('For EACH existing app scenario, create a logged-in variation:');
     console.log(chalk.dim('    Copy the scenario seed data and add "session":{"cookieValue":"sess_alice"} + user seed'));
     console.log(chalk.dim('    Name: "<Original Name> - Logged In" (e.g. "Full Catalog - Logged In")'));
-    console.log(chalk.dim('    Step 8 scenarios already serve as logged-out versions (no session cookie)'));
+    console.log(chalk.dim('    Step 10 scenarios already serve as logged-out versions (no session cookie)'));
     checkbox('If there are multiple user roles (admin, regular, etc.), create role-specific variations too');
     console.log(chalk.dim('    Each persona scenario layers user-specific seed data on top of an app scenario'));
     checkbox('Include "dimensions" — inherit from the base app scenario, or override if the persona implies a different device');
@@ -1327,26 +1663,28 @@ function printStep9(root, feature) {
     console.log(chalk.yellow('    If clientErrors is non-empty → fix the issue and re-register the scenario'));
     console.log();
     console.log(chalk.dim('See FEATURE_PATTERNS.md and AUTH_PATTERNS.md for auth scenario guidance.'));
-    stopGate(9);
+    stopGate(11);
 }
-// ─── Step 10: Verify ──────────────────────────────────────────────────
-function printStep10(root, feature) {
+// ─── Step 12: Verify ──────────────────────────────────────────────────
+function printStep12(root, feature) {
     const port = getServerPort();
     const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
-    const isResuming = prevState?.step === 10;
+    const isResuming = prevState?.step === 12;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 10,
-        label: STEP_LABELS[10],
+        step: 12,
+        label: STEP_LABELS[12],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
-    logEvent(root, 'step', { step: 10, label: 'Verify', feature });
-    stepHeader(10, 'Verify', feature);
+    logEvent(root, 'step', { step: 12, label: 'Verify', feature });
+    stepHeader(12, 'Verify', feature);
     if (isResuming) {
-        printResumptionHeader(10);
+        printResumptionHeader(12);
     }
     console.log('Verify component isolation screenshots, editor scenarios, and library tests.');
     console.log();
@@ -1369,63 +1707,67 @@ function printStep10(root, feature) {
     checkbox('Verify no broken images: `codeyam editor verify-images \'{"paths":["/"], "imageUrls":["url1"]}\'` with all page paths and image URLs');
     console.log();
     console.log(chalk.bold('Library functions — test check:'));
-    checkbox('Re-run all test files from step 5 to confirm they still pass');
+    checkbox('Re-run all test files from step 7 to confirm they still pass');
     console.log(chalk.dim('    Example: npx vitest run app/lib/drinks.test.ts'));
     checkbox('If any test fails, fix the source code and re-run');
     console.log();
     console.log(chalk.dim('Focus on fixing issues. All component screenshots, scenarios, and tests must be clean before proceeding.'));
-    stopGate(10);
+    stopGate(12);
 }
-// ─── Step 11: Journal ─────────────────────────────────────────────────
-function printStep11(root, feature) {
+// ─── Step 13: Journal ─────────────────────────────────────────────────
+function printStep13(root, feature) {
     const port = getServerPort();
     const prevState = readState(root);
-    const isResuming = prevState?.step === 11;
+    const isResuming = prevState?.step === 13;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 11,
-        label: STEP_LABELS[11],
+        step: 13,
+        label: STEP_LABELS[13],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
-    logEvent(root, 'step', { step: 11, label: 'Journal', feature });
-    stepHeader(11, 'Journal', feature);
+    logEvent(root, 'step', { step: 13, label: 'Journal', feature });
+    stepHeader(13, 'Journal', feature);
     if (isResuming) {
-        printResumptionHeader(11);
+        printResumptionHeader(13);
     }
     console.log('Create or update the journal entry for this feature.');
     console.log();
     console.log(chalk.bold('Checklist:'));
     checkbox('Write a concise description of what was built (2-3 sentences)');
-    checkbox(`First time at step 11 — create journal entry with ALL session screenshots:`);
+    checkbox(`First time at step 13 — create journal entry with ALL session screenshots:`);
     console.log(chalk.dim(`    codeyam editor journal '{"title":"...","type":"feature","description":"...","includeSessionScenarios":true}'`));
     console.log(chalk.dim('    includeSessionScenarios auto-discovers component + app + user persona screenshots'));
-    checkbox(`Returning to step 11 (before commit) — update the existing journal entry:`);
+    checkbox(`Returning to step 13 (before commit) — update the existing journal entry:`);
     console.log(chalk.dim(`    codeyam editor journal-update '{"time":"<journal entry time>","description":"<updated>","includeSessionScenarios":true}'`));
     console.log(chalk.dim('    Note: PATCH only works before the entry is committed. After commit, use POST to create a new entry.'));
     console.log();
-    console.log(chalk.dim('Focus on creating or updating the journal entry. Summary and presentation happen in step 13.'));
-    stopGate(11);
+    console.log(chalk.dim('Focus on creating or updating the journal entry. Summary and presentation happen in step 15.'));
+    stopGate(13);
 }
-// ─── Step 12: Review ──────────────────────────────────────────────────
-function printStep12(root, feature) {
+// ─── Step 14: Review ──────────────────────────────────────────────────
+function printStep14(root, feature) {
     const port = getServerPort();
     const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
-    const isResuming = prevState?.step === 12;
+    const isResuming = prevState?.step === 14;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 12,
-        label: STEP_LABELS[12],
+        step: 14,
+        label: STEP_LABELS[14],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
-    logEvent(root, 'step', { step: 12, label: 'Review', feature });
-    stepHeader(12, 'Review', feature);
+    logEvent(root, 'step', { step: 14, label: 'Review', feature });
+    stepHeader(14, 'Review', feature);
     if (isResuming) {
-        printResumptionHeader(12);
+        printResumptionHeader(14);
     }
     console.log('Verify all screenshots and checks pass before presenting to the user.');
     console.log();
@@ -1438,33 +1780,36 @@ function printStep12(root, feature) {
     checkbox('If `hasErrors` is true, fix them and re-capture affected scenarios');
     checkbox('Run `codeyam editor verify-images \'{"paths":["/"], "imageUrls":["url1"]}\'` with all page paths and image URLs');
     checkbox('Fix or remove any broken images before continuing');
+    checkbox('Recapture stale scenarios: `codeyam editor recapture-stale`');
     checkbox('Run `codeyam editor audit` to verify completeness of scenarios and tests');
     checkbox('Do not proceed until all checks pass');
-    stopGate(12);
+    stopGate(14);
 }
-// ─── Step 13: Present ─────────────────────────────────────────────────
-function printStep13(root, feature) {
+// ─── Step 15: Present ─────────────────────────────────────────────────
+function printStep15(root, feature) {
     const prevState = readState(root);
-    const isResuming = prevState?.step === 13;
+    const isResuming = prevState?.step === 15;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 13,
-        label: STEP_LABELS[13],
+        step: 15,
+        label: STEP_LABELS[15],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
-    logEvent(root, 'step', { step: 13, label: 'Present', feature });
-    stepHeader(13, 'Present', feature);
+    logEvent(root, 'step', { step: 15, label: 'Present', feature });
+    stepHeader(15, 'Present', feature);
     if (isResuming) {
-        printResumptionHeader(13);
+        printResumptionHeader(15);
     }
     console.log('Present the results to the user and get their approval.');
     console.log();
     console.log(chalk.bold('Checklist:'));
     checkbox(`Show the results panel: \`codeyam editor show-results\``);
     console.log(chalk.dim('    This opens a visual panel below the terminal showing all scenarios with screenshots.'));
-    console.log(chalk.dim('    The preview automatically switches to the first app-level scenario.'));
+    console.log(chalk.dim('    The first scenario is automatically selected and its live preview is shown.'));
     console.log(chalk.dim('    The user can click scenarios to switch the live preview.'));
     checkbox('Write a 1-2 sentence summary of what was built');
     checkbox('Report test count and audit status (one line)');
@@ -1476,7 +1821,7 @@ function printStep13(root, feature) {
         chalk.dim(' — describe changes, then re-verify'));
     console.log();
     console.log(chalk.bold('If the user chooses "Save & commit":'));
-    checkbox('Advance to the commit step: `codeyam editor 14`');
+    checkbox('Advance to the commit step: `codeyam editor 16`');
     console.log();
     console.log(chalk.bold('If the user chooses "Make changes" (or asks for ANY change, even as a question):'));
     checkbox(`Hide the results panel: \`codeyam editor hide-results\``);
@@ -1484,7 +1829,7 @@ function printStep13(root, feature) {
     checkbox(`Run: \`codeyam editor change "${feature}"\` — this gives you the change checklist`);
     checkbox('THEN make the requested changes and follow the checklist');
     console.log(chalk.red.bold('  IMPORTANT: Always run the change command BEFORE writing any code.'));
-    stopGate(13, { confirm: true });
+    stopGate(15, { confirm: true });
 }
 // ─── Migration Mode ──────────────────────────────────────────────────
 /**
@@ -1681,7 +2026,7 @@ function printMigrateStep3(root) {
     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();
+    printComponentCaptureInstructions(root);
     console.log();
     migrationStopGate(3, pageName, pageIndex, totalPages);
 }
@@ -1704,7 +2049,7 @@ function printMigrateStep4(root) {
     checkbox('Check for client errors: `codeyam editor client-errors`');
     checkbox('If any issues: fix the scenario data, re-register affected scenarios');
     checkbox('Show results: `codeyam editor show-results`');
-    console.log(chalk.dim('    The preview automatically switches to the first app-level scenario.'));
+    console.log(chalk.dim('    The first scenario is automatically selected and its live preview is shown.'));
     console.log();
     console.log(chalk.dim('The user should now see their existing page with live screenshots in the preview.'));
     migrationStopGate(4, pageName, pageIndex, totalPages);
@@ -1816,7 +2161,7 @@ function printMigrateStep8(root) {
     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('Find all scenarios that use the real page route (not /isolated-components/ 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`');
@@ -1824,10 +2169,10 @@ function printMigrateStep8(root) {
     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();
+    printComponentCaptureInstructions(root);
     console.log();
     console.log(chalk.bold('Verify:'));
-    checkbox('Run `codeyam editor analyze-imports` to populate import graph');
+    checkbox('Run `codeyam editor analyze-imports` to populate import graph (or `codeyam editor analyze-imports path/to/file.tsx ...` for specific files)');
     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`');
@@ -1871,7 +2216,7 @@ function printMigrateStep10(root) {
     console.log();
     console.log(chalk.bold('Checklist:'));
     checkbox('Show results: `codeyam editor show-results`');
-    console.log(chalk.dim('    The preview automatically switches to the first app-level scenario.'));
+    console.log(chalk.dim('    The first scenario is automatically selected and its live preview is shown.'));
     checkbox('Write a 1-2 sentence summary of what was migrated');
     console.log();
     console.log(chalk.bold('Present a selection menu (AskUserQuestion with these EXACT option labels):'));
@@ -2091,47 +2436,52 @@ function handleMigrateCommand(root, subArg) {
     };
     stepFns[step](root);
 }
-// ─── Step 14: Commit ─────────────────────────────────────────────────
-function printStep14(root, feature) {
+// ─── Step 16: Commit ─────────────────────────────────────────────────
+function printStep16(root, feature) {
     const prevState = readState(root);
-    const isResuming = prevState?.step === 14;
+    const isResuming = prevState?.step === 16;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 14,
-        label: STEP_LABELS[14],
+        step: 16,
+        label: STEP_LABELS[16],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
-    logEvent(root, 'step', { step: 14, label: 'Commit', feature });
-    stepHeader(14, 'Commit', feature);
+    logEvent(root, 'step', { step: 16, label: 'Commit', feature });
+    stepHeader(16, 'Commit', feature);
     if (isResuming) {
-        printResumptionHeader(14);
+        printResumptionHeader(16);
     }
     console.log('Commit all changes for this feature.');
     console.log();
     console.log(chalk.bold('Checklist:'));
+    checkbox('Ensure all screenshots are fresh: `codeyam editor recapture-stale`');
     checkbox(`Hide the results panel: \`codeyam editor hide-results\``);
     checkbox(`Git commit using the journal description: \`codeyam editor commit '{"message":"feat: <title>\\n\\n<journal description>"}'\``);
     console.log(chalk.dim('    The commit message body MUST match the journal description exactly'));
-    stopGate(14);
+    stopGate(16);
 }
-// ─── Step 15: Finalize ───────────────────────────────────────────────
-function printStep15(root, feature) {
+// ─── Step 17: Finalize ───────────────────────────────────────────────
+function printStep17(root, feature) {
     const prevState = readState(root);
-    const isResuming = prevState?.step === 15;
+    const isResuming = prevState?.step === 17;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 15,
-        label: STEP_LABELS[15],
+        step: 17,
+        label: STEP_LABELS[17],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
-    logEvent(root, 'step', { step: 15, label: 'Finalize', feature });
-    stepHeader(15, 'Finalize', feature);
+    logEvent(root, 'step', { step: 17, label: 'Finalize', feature });
+    stepHeader(17, 'Finalize', feature);
     if (isResuming) {
-        printResumptionHeader(15);
+        printResumptionHeader(17);
     }
     console.log('Update the journal with the commit SHA and amend the commit.');
     console.log();
@@ -2139,24 +2489,26 @@ function printStep15(root, feature) {
     checkbox(`Update journal with commit SHA: \`codeyam editor journal-update '{"time":"<journal entry time>","commitSha":"<sha>","commitMessage":"feat: <title>"}'\``);
     checkbox('Amend the commit to include the journal update: `git add .codeyam/journal/ && git commit --amend --no-edit`');
     console.log(chalk.dim('    The journal-update modifies journal files after the commit — amend to keep the tree clean.'));
-    stopGate(15);
+    stopGate(17);
 }
-// ─── Step 16: Push ───────────────────────────────────────────────────
-function printStep16(root, feature) {
+// ─── Step 18: Push ───────────────────────────────────────────────────
+function printStep18(root, feature) {
     const prevState = readState(root);
-    const isResuming = prevState?.step === 16;
+    const isResuming = prevState?.step === 18;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
-        step: 16,
-        label: STEP_LABELS[16],
+        step: 18,
+        label: STEP_LABELS[18],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
-    logEvent(root, 'step', { step: 16, label: 'Push', feature });
-    stepHeader(16, 'Push', feature);
+    logEvent(root, 'step', { step: 18, label: 'Push', feature });
+    stepHeader(18, 'Push', feature);
     if (isResuming) {
-        printResumptionHeader(16);
+        printResumptionHeader(18);
     }
     console.log('Push the commit to the remote repository.');
     console.log();
@@ -2167,12 +2519,15 @@ function printStep16(root, feature) {
     console.log(chalk.dim('    If the user says yes, run: `git push`'));
     console.log(chalk.dim('    If NO remote exists, ask (AskUserQuestion): "This project doesn\'t have a git remote yet. Would you like help setting one up? I can walk you through creating a GitHub repository." with options "Yes, set up remote" and "No, skip"'));
     console.log(chalk.dim('    If the user wants help, guide them through `gh repo create` or manual GitHub setup, then push.'));
-    checkbox('After the user responds, run: `codeyam editor steps` to start the next feature');
-    console.log();
-    console.log(chalk.red.bold('  If the user reports a bug or requests a fix after committing:'));
-    console.log(chalk.red.bold('  You MUST still run `codeyam editor change` before making any changes.'));
-    console.log(chalk.red.bold('  The change workflow applies to ALL changes — post-commit fixes are not an exception.'));
-    stopGate(16, { confirm: true });
+    console.log(chalk.dim('    Task management is handled by the ━━━ TASK ━━━ directive below.'));
+    console.log();
+    console.log(chalk.bold.yellow('IMPORTANT: After this step, the current feature is DONE.'));
+    console.log(chalk.yellow('  Any new user request — even if it sounds related — is a NEW feature.'));
+    console.log(chalk.yellow('  Do NOT use `codeyam editor change` or start building directly.'));
+    console.log(chalk.yellow('  Ask the user what they want to build. Once they tell you, run `codeyam editor 1` yourself.'));
+    console.log(chalk.yellow('  NEVER tell the user to run `codeyam editor` commands — these are internal. Just ask what to build.'));
+    console.log(chalk.yellow('  The change workflow is ONLY for modifications during steps 1-15, not after commit.'));
+    stopGate(18, { confirm: true });
 }
 // ─── Command definition ───────────────────────────────────────────────
 // ─── Analyze-imports subcommand ────────────────────────────────────────
@@ -2192,7 +2547,7 @@ async function handleAnalyzeImports(options = {}) {
             return;
         }
         console.error(chalk.red('Error: .codeyam/glossary.json not found.'));
-        console.error(chalk.dim('  Run codeyam editor 6 to create the glossary first.'));
+        console.error(chalk.dim('  Run codeyam editor 8 to create the glossary first.'));
         process.exit(1);
     }
     let glossaryEntries;
@@ -2201,10 +2556,14 @@ async function handleAnalyzeImports(options = {}) {
         glossaryEntries = sanitizeGlossaryEntries(parsed);
     }
     catch {
+        if (options.silent)
+            return;
         console.error(chalk.red('Error: Could not parse .codeyam/glossary.json.'));
         process.exit(1);
     }
     if (glossaryEntries.length === 0) {
+        if (options.silent)
+            return;
         console.error(chalk.red('Error: glossary.json is empty.'));
         process.exit(1);
     }
@@ -2246,25 +2605,137 @@ async function handleAnalyzeImports(options = {}) {
         // Non-fatal — scenario file paths just won't be included
     }
     const progress = new ProgressReporter();
-    // Run data-structure-only analysis for all entities (glossary + pages)
+    // Filter to only files that actually need analysis — avoids re-analyzing
+    // ~120 files when only 2 are incomplete.
+    let targetFilePaths = filePaths;
+    try {
+        const { getDatabase } = await import('../../../packages/database/index.js');
+        const db = getDatabase();
+        const { requireBranchAndProject: rbp } = await import('../utils/database.js');
+        const { project } = await rbp(JSON.parse(fs.readFileSync(path.join(root, '.codeyam', 'config.json'), 'utf8')).projectSlug);
+        const { filterToIncompleteFilePaths } = await import('../utils/editorAudit.js');
+        const incomplete = await filterToIncompleteFilePaths(db, project.id, filePaths);
+        if (incomplete.length < filePaths.length && incomplete.length > 0) {
+            if (!options.silent) {
+                console.log(chalk.dim(`Skipping ${filePaths.length - incomplete.length} already-analyzed files, analyzing ${incomplete.length} remaining...`));
+            }
+            targetFilePaths = incomplete;
+        }
+        else if (incomplete.length === 0) {
+            if (!options.silent) {
+                console.log(chalk.green('All entities already have analyses — nothing to do.'));
+            }
+            // Still need to run the import graph + backfill below
+            targetFilePaths = [];
+        }
+    }
+    catch {
+        // Non-fatal — fall back to analyzing all files
+    }
+    // If specific file paths were requested, scope analysis to only those files.
+    // The full filePaths set is still used for the import graph below.
+    if (options.filePaths && options.filePaths.length > 0) {
+        const requested = new Set(options.filePaths);
+        targetFilePaths = targetFilePaths.filter((fp) => requested.has(fp));
+        if (targetFilePaths.length === 0 && !options.silent) {
+            console.log(chalk.dim('Requested file(s) already analyzed or not in glossary — skipping analysis.'));
+        }
+    }
+    // Run data-structure-only analysis for entities that need it.
     // Don't pass entityNames — entities may not exist yet (fresh clone).
     // The analyzer will discover and create them from file paths.
-    progress.start('Running import analysis for all entities...');
-    try {
-        await runAnalysisForEntities({
-            projectRoot: root,
-            filePaths,
-            progress,
-            onlyDataStructure: true,
-        });
+    if (targetFilePaths.length > 0) {
+        progress.start(`Running import analysis for ${targetFilePaths.length} entit${targetFilePaths.length !== 1 ? 'ies' : 'y'}...`);
+        try {
+            await runAnalysisForEntities({
+                projectRoot: root,
+                filePaths: targetFilePaths,
+                progress,
+                onlyDataStructure: true,
+            });
+        }
+        catch (err) {
+            progress.fail('Analysis failed');
+            const msg = err instanceof Error ? err.message : String(err);
+            if (options.silent) {
+                // Internal caller — don't kill the process, let the caller handle it
+                return;
+            }
+            console.error(chalk.red(`Error: ${msg}`));
+            process.exit(1);
+        }
+        progress.succeed('Analysis complete');
     }
-    catch (err) {
-        progress.fail('Analysis failed');
-        const msg = err instanceof Error ? err.message : String(err);
-        console.error(chalk.red(`Error: ${msg}`));
-        process.exit(1);
+    // Surface analysis errors if any occurred
+    const errorReportPath = path.join(root, '.codeyam', 'analysis-errors.txt');
+    if (fs.existsSync(errorReportPath)) {
+        if (!options.silent) {
+            console.log(chalk.yellow('\nSome entity analyses failed. Full details in .codeyam/analysis-errors.txt'));
+            console.log(chalk.yellow('Send this file to the CodeYam team for diagnosis.'));
+            console.log(chalk.dim('Affected entities will be missing from the import graph.'));
+        }
+        // Write structured analysis-failures.json for the audit to detect.
+        // Parse the error report to find which entities failed, and cross-reference
+        // with the files we tried to analyze.
+        try {
+            const { readAnalysisFailures, writeAnalysisFailures } = await import('../utils/manualEntityAnalysis.js');
+            const errorContent = fs.readFileSync(errorReportPath, 'utf8');
+            const existingFailures = readAnalysisFailures(root);
+            // Parse error messages to identify failed file paths.
+            // Error format: "Error on step <StepName> for entity <Name> (<filePath>)"
+            // or more generic "CodeYam Error: <message>"
+            const entityErrorRegex = /(?:Error on step \w+ for entity (\w+))|(?:entity[: ]+["']?(\w+)["']?)/gi;
+            const failedEntityNames = new Set();
+            let match;
+            while ((match = entityErrorRegex.exec(errorContent)) !== null) {
+                const name = match[1] || match[2];
+                if (name)
+                    failedEntityNames.add(name);
+            }
+            // Map failed entity names back to file paths from targetFilePaths
+            const glossaryPath = path.join(root, '.codeyam', 'glossary.json');
+            let glossary = [];
+            try {
+                glossary = sanitizeGlossaryEntries(JSON.parse(fs.readFileSync(glossaryPath, 'utf8')));
+            }
+            catch {
+                // Non-fatal
+            }
+            // Also: any targetFilePaths that didn't produce entities are failures
+            const now = new Date().toISOString();
+            const updatedFailures = { ...existingFailures };
+            if (failedEntityNames.size > 0) {
+                for (const name of failedEntityNames) {
+                    const entry = glossary.find((e) => e.name === name);
+                    if (entry) {
+                        updatedFailures[entry.filePath] = {
+                            entityName: name,
+                            error: `Automated analysis failed — see .codeyam/analysis-errors.txt`,
+                            failedAt: now,
+                        };
+                    }
+                }
+            }
+            // When we can't parse specific entity names from the error, DON'T mark
+            // all target files as failed. The error may be non-fatal (e.g., a cache
+            // miss logged as "CodeYam Error") and blanket-marking every file as
+            // permanently failed blocks future audits from resolving them.
+            writeAnalysisFailures(root, updatedFailures);
+        }
+        catch {
+            // Non-fatal — failure tracking is best-effort
+        }
+    }
+    else {
+        // No errors — clear any stale failure tracking
+        try {
+            const { writeAnalysisFailures } = await import('../utils/manualEntityAnalysis.js');
+            writeAnalysisFailures(root, {});
+        }
+        catch {
+            // Non-fatal
+        }
     }
-    progress.succeed('Analysis complete');
     // Load entities WITH metadata from database
     progress.start('Loading entity metadata...');
     await initializeEnvironment();
@@ -2447,43 +2918,98 @@ async function handleDelete(scenarioId) {
  * Creates isolation route directories and the layout guard file.
  * This avoids brace-expansion permission prompts in the embedded terminal.
  */
+function handleDesignSystem(designSystemId) {
+    const root = process.cwd();
+    const ds = DESIGN_SYSTEMS.find((d) => d.id === designSystemId);
+    if (!ds) {
+        console.error(chalk.red(`Error: Unknown design system "${designSystemId}". Valid options: ${DESIGN_SYSTEMS.map((d) => d.id).join(', ')}`));
+        process.exit(1);
+    }
+    const srcPath = path.join(__dirname, '..', '..', 'templates', 'design-systems', ds.fileName);
+    if (!fs.existsSync(srcPath)) {
+        console.error(chalk.red(`Error: Design system file not found: ${srcPath}`));
+        process.exit(1);
+    }
+    const destDir = path.join(root, '.codeyam');
+    fs.mkdirSync(destDir, { recursive: true });
+    const destPath = path.join(destDir, 'design-system.md');
+    fs.copyFileSync(srcPath, destPath);
+    console.log(chalk.green(`Installed "${ds.name}" design system → .codeyam/design-system.md`));
+}
 function handleIsolate(componentNames) {
     const root = process.cwd();
+    const ctx = getTechStackContext(root);
     if (componentNames.length === 0) {
         console.error(chalk.red('Usage: codeyam editor isolate "ComponentA ComponentB ..."'));
         process.exit(1);
     }
     const isolateDir = path.join(root, 'app', 'isolated-components');
-    // Create layout.tsx with production guard if missing
-    const layoutPath = path.join(isolateDir, 'layout.tsx');
+    // Create the framework-appropriate layout guard if missing.
+    // Clean up wrong-framework layout from a previous CLI version.
+    const layoutPath = path.join(isolateDir, ctx.isExpo ? '_layout.tsx' : 'layout.tsx');
+    const wrongLayoutPath = path.join(isolateDir, ctx.isExpo ? 'layout.tsx' : '_layout.tsx');
+    if (fs.existsSync(wrongLayoutPath)) {
+        fs.unlinkSync(wrongLayoutPath);
+    }
     if (!fs.existsSync(layoutPath)) {
         fs.mkdirSync(isolateDir, { recursive: true });
-        fs.writeFileSync(layoutPath, [
-            'import { notFound } from "next/navigation";',
-            '',
-            'export default function CaptureLayout({ children }: { children: React.ReactNode }) {',
-            '  if (process.env.NODE_ENV === "production") notFound();',
-            '  return <>{children}</>;',
-            '}',
-            '',
-        ].join('\n'), 'utf8');
-        console.log(chalk.green(`Created layout guard: app/isolated-components/layout.tsx`));
-    }
-    // Create a directory for each component
+        if (ctx.isExpo) {
+            fs.writeFileSync(layoutPath, [
+                'import { Redirect, Slot } from "expo-router";',
+                '',
+                'export default function CaptureLayout() {',
+                '  if (!__DEV__) return <Redirect href="/" />;',
+                '  return <Slot />;',
+                '}',
+                '',
+            ].join('\n'), 'utf8');
+        }
+        else {
+            fs.writeFileSync(layoutPath, [
+                'import { notFound } from "next/navigation";',
+                '',
+                'export default function CaptureLayout({ children }: { children: React.ReactNode }) {',
+                '  if (process.env.NODE_ENV === "production") notFound();',
+                '  return <>{children}</>;',
+                '}',
+                '',
+            ].join('\n'), 'utf8');
+        }
+        console.log(chalk.green(`Created layout guard: app/isolated-components/${ctx.isExpo ? '_layout.tsx' : 'layout.tsx'}`));
+    }
+    // Create isolation route for each component.
+    // Expo Router uses flat files (ComponentName.tsx), Next.js uses subdirectories (ComponentName/page.tsx).
     const created = [];
     const existed = [];
     for (const name of componentNames) {
-        const dir = path.join(isolateDir, name);
-        if (fs.existsSync(dir)) {
-            existed.push(name);
+        if (ctx.isExpo) {
+            const filePath = path.join(isolateDir, `${name}.tsx`);
+            if (fs.existsSync(filePath)) {
+                existed.push(name);
+            }
+            else {
+                created.push(name);
+            }
         }
         else {
-            fs.mkdirSync(dir, { recursive: true });
-            created.push(name);
+            const dir = path.join(isolateDir, name);
+            if (fs.existsSync(dir)) {
+                existed.push(name);
+            }
+            else {
+                fs.mkdirSync(dir, { recursive: true });
+                created.push(name);
+            }
         }
     }
     if (created.length > 0) {
-        console.log(chalk.green(`Created ${created.length} isolation route dir(s): ${created.join(', ')}`));
+        if (ctx.isExpo) {
+            console.log(chalk.green(`Ready for ${created.length} isolation route(s): ${created.map((n) => `app/isolated-components/${n}.tsx`).join(', ')}`));
+            console.log(chalk.dim('    Create each file with useLocalSearchParams, a scenarios map, and nativeID="codeyam-capture"'));
+        }
+        else {
+            console.log(chalk.green(`Created ${created.length} isolation route dir(s): ${created.join(', ')}`));
+        }
     }
     if (existed.length > 0) {
         console.log(chalk.dim(`Already existed: ${existed.join(', ')}`));
@@ -2537,6 +3063,12 @@ function formatApiSubcommandResult(subcommand, data) {
                 parts.push(`scenarioId="${data.scenarioId}"`);
             if (data.sessionsNotified != null)
                 parts.push(`notified=${data.sessionsNotified}`);
+            // Surface the HTTP health check from the dev server
+            if (data.preview) {
+                parts.push(`healthy=${data.preview.healthy}`);
+                if (data.preview.error)
+                    parts.push(`error="${data.preview.error}"`);
+            }
             return parts.join(' ');
         }
         case 'dev-server': {
@@ -2586,6 +3118,34 @@ function formatApiSubcommandResult(subcommand, data) {
             }
             return parts.join(' ');
         }
+        case 'verify-routes': {
+            const lines = [];
+            lines.push(chalk.bold.yellow('━━━ Route Verification ━━━'));
+            for (const [route, info] of Object.entries(data.routes || {})) {
+                const r = info;
+                if (r.ok) {
+                    lines.push(chalk.green(`  ✓ ${route} — HTTP ${r.status}`));
+                }
+                else {
+                    lines.push(chalk.red(`  ✗ ${route} — ${r.error || `HTTP ${r.status}`}`));
+                }
+            }
+            for (const [route, info] of Object.entries(data.apiRoutes || {})) {
+                const r = info;
+                if (r.ok && r.isJSON) {
+                    lines.push(chalk.green(`  ✓ ${route} — HTTP ${r.status}, valid JSON`));
+                }
+                else if (r.ok) {
+                    lines.push(chalk.yellow(`  ⚠ ${route} — HTTP ${r.status}, not valid JSON`));
+                }
+                else {
+                    lines.push(chalk.red(`  ✗ ${route} — ${r.error || `HTTP ${r.status}`}`));
+                }
+            }
+            lines.push('');
+            lines.push(data.ok ? chalk.green(data.summary) : chalk.red(data.summary));
+            return lines.join('\n');
+        }
         default:
             return null; // journal-list, show/hide-results: keep full JSON
     }
@@ -2614,11 +3174,15 @@ async function handleRegister(jsonArg) {
     }
     // Normalize to array for uniform handling
     const items = Array.isArray(parsed.body) ? parsed.body : [parsed.body];
+    const root = getProjectRoot();
     const port = getServerPort();
     const url = `http://localhost:${port}/api/editor-register-scenario`;
     const isBatch = items.length > 1;
     let succeeded = 0;
     let failed = 0;
+    let warnings = 0;
+    const issues = [];
+    const screenshotEntries = [];
     for (let i = 0; i < items.length; i++) {
         const body = items[i];
         const prefix = isBatch ? chalk.dim(`[${i + 1}/${items.length}] `) : '';
@@ -2646,11 +3210,30 @@ async function handleRegister(jsonArg) {
             else {
                 parts.push(`errors=0`);
             }
-            if (data.seedResult)
-                parts.push(`seed=${data.seedResult.success}`);
+            if (data.visibleText) {
+                const truncated = data.visibleText.length > 100
+                    ? data.visibleText.substring(0, 97) + '...'
+                    : data.visibleText;
+                parts.push(`visibleText="${truncated}"`);
+            }
+            if (data.seedResult) {
+                if (data.seedResult.success) {
+                    parts.push(`seed=ok`);
+                }
+                else {
+                    parts.push(chalk.red(`seed=FAILED${data.seedResult.error ? ` (${data.seedResult.error})` : ''}`));
+                }
+            }
             if (data.captureError)
                 parts.push(chalk.yellow(`captureError="${data.captureError}"`));
             console.log(prefix + parts.join(' '));
+            // Warn when application scenario is missing seed data
+            if (data.missingSeedWarning) {
+                console.log(chalk.red.bold('WARNING: No seed data in this application scenario!'));
+                console.log(chalk.yellow('  This scenario has type "application" but no "seed" data was provided.'));
+                console.log(chalk.yellow('  The page will render with an empty database — nothing will be visible.'));
+                console.log(chalk.yellow('  Re-register with "seed":{...} containing the database rows this page needs.'));
+            }
             // Surface client errors prominently so they can't be missed
             if (data.clientErrors && data.clientErrors.length > 0) {
                 console.log(chalk.red.bold(`⚠ WARNING: ${data.clientErrors.length} client error${data.clientErrors.length !== 1 ? 's' : ''} detected during capture:`));
@@ -2658,14 +3241,39 @@ async function handleRegister(jsonArg) {
                     console.log(chalk.red(`  → ${err}`));
                 }
                 console.log(chalk.yellow('  The screenshot may show an error screen instead of the actual component.'));
+                // Provide actionable debugging hints for HTTP/API errors
+                const hasApiResponseError = data.clientErrors.some((e) => e.includes('API response error:'));
+                const hasHttpError = data.clientErrors.some((e) => e.includes('HTTP error:'));
+                if (hasHttpError || hasApiResponseError) {
+                    console.log(chalk.yellow('  To debug: look at the "API response error" lines above — they show the exact API endpoint'));
+                    console.log(chalk.yellow('  that failed and what the server returned. Then check the scenario seed data to ensure'));
+                    console.log(chalk.yellow('  all IDs referenced in the URL exist in the seed, and that the route is correct.'));
+                }
                 console.log(chalk.yellow('  Fix the issue and re-register this scenario.'));
             }
+            const resultIssues = classifyRegistrationResult(res.ok, res.status, data, String(body.name || `item ${i + 1}`));
             if (!res.ok) {
                 console.error(chalk.dim(JSON.stringify(data, null, 2)));
                 failed++;
             }
             else {
+                if (resultIssues.length > 0)
+                    warnings++;
                 succeeded++;
+                // Collect screenshot paths for duplicate detection
+                if (data.screenshotCaptured &&
+                    data.scenario?.screenshotPath &&
+                    data.scenario?.name) {
+                    const absPath = path.join(root, '.codeyam', 'editor-scenarios', data.scenario.screenshotPath);
+                    screenshotEntries.push({
+                        scenarioName: data.scenario.name,
+                        screenshotAbsPath: absPath,
+                    });
+                }
+            }
+            // Collect issues from this registration
+            for (const issue of resultIssues) {
+                issues.push(`"${issue.scenarioName}": ${issue.message}`);
             }
         }
         catch (error) {
@@ -2676,12 +3284,99 @@ async function handleRegister(jsonArg) {
             failed++;
         }
     }
-    if (isBatch) {
-        console.log(chalk.dim(`\nBatch complete: ${succeeded}/${items.length} succeeded`));
+    // Detect duplicate screenshots in the batch
+    if (isBatch && screenshotEntries.length > 1) {
+        const { computeScreenshotHash, findDuplicateScreenshots } = await import('../utils/screenshotHash.js');
+        const hashEntries = screenshotEntries
+            .map((e) => {
+            const hash = computeScreenshotHash(e.screenshotAbsPath);
+            return hash
+                ? {
+                    scenarioName: e.scenarioName,
+                    screenshotPath: e.screenshotAbsPath,
+                    hash,
+                }
+                : null;
+        })
+            .filter((e) => e !== null);
+        const duplicates = findDuplicateScreenshots(hashEntries);
+        if (duplicates.size > 0) {
+            console.log('');
+            console.log(chalk.yellow.bold('WARNING: Identical screenshots detected:'));
+            for (const [, names] of duplicates) {
+                const quoted = names.map((n) => `"${n}"`);
+                console.log(chalk.yellow(`  ${quoted.join(' and ')} produced the same screenshot`));
+            }
+            console.log(chalk.yellow("  This usually means the app's view state depends on something scenarios can't control"));
+            console.log(chalk.yellow('  (e.g., a hardcoded function return value, or identical localStorage not differentiating views).'));
+        }
+    }
+    if (isBatch) {
+        console.log('');
+        if (failed > 0 || warnings > 0) {
+            console.log(chalk.red.bold(`ERROR: ${failed} failed, ${warnings} with warnings out of ${items.length} scenarios`));
+            console.log('');
+            console.log(chalk.red.bold('Issues that MUST be fixed:'));
+            for (const issue of issues) {
+                console.log(chalk.red(`  ✗ ${issue}`));
+            }
+            console.log('');
+            console.log(chalk.red('Do NOT skip these errors. Fix each issue and re-register the affected scenarios.'));
+        }
+        else {
+            console.log(chalk.green(`✓ Batch complete: ${succeeded}/${items.length} succeeded with no issues`));
+        }
+    }
+    if (failed > 0 || warnings > 0) {
+        process.exit(1);
+    }
+}
+// ─── Glossary-add subcommand ──────────────────────────────────────────
+/**
+ * `codeyam editor glossary-add '{"name":"...", "filePath":"...", "description":"..."}'`
+ *
+ * Safely adds/updates entries in .codeyam/glossary.json via the CLI,
+ * avoiding hand-editing that breaks on unicode characters.
+ */
+async function handleGlossaryAdd(jsonArg) {
+    if (!jsonArg) {
+        console.error(chalk.red('Error: JSON argument required.'));
+        console.error(chalk.dim('  Usage: codeyam editor glossary-add \'{"name":"DrinkCard","filePath":"app/components/DrinkCard.tsx","description":"Displays a drink item"}\''));
+        console.error(chalk.dim('  For large payloads: codeyam editor glossary-add @.codeyam/tmp/entry.json'));
+        process.exit(1);
+    }
+    const parsed = parseRegisterArg(jsonArg);
+    if (parsed.error) {
+        console.error(chalk.red(`Error: ${parsed.error}`));
+        process.exit(1);
+    }
+    // Normalize to array
+    const items = Array.isArray(parsed.body) ? parsed.body : [parsed.body];
+    // Read existing glossary
+    const root = getProjectRoot();
+    const glossaryPath = path.join(root, '.codeyam', 'glossary.json');
+    let existing = [];
+    try {
+        const raw = JSON.parse(fs.readFileSync(glossaryPath, 'utf8'));
+        existing = sanitizeGlossaryEntries(raw);
+    }
+    catch {
+        // Glossary doesn't exist yet or can't be parsed — start fresh
+    }
+    // Merge
+    const { validateGlossaryEntry, mergeGlossaryEntries } = await import('../utils/glossaryAdd.js');
+    const result = mergeGlossaryEntries(existing, items);
+    // Report validation errors
+    for (const err of result.errors) {
+        console.error(chalk.red(`Error at index ${err.index}: ${err.message}`));
     }
-    if (failed > 0) {
+    if (result.added === 0 && result.updated === 0 && result.errors.length > 0) {
         process.exit(1);
     }
+    // Write back with utf8 encoding to safely handle unicode
+    fs.mkdirSync(path.dirname(glossaryPath), { recursive: true });
+    fs.writeFileSync(glossaryPath, JSON.stringify(result.entries, null, 2), 'utf8');
+    console.log(`added=${result.added} updated=${result.updated} total=${result.entries.length}`);
 }
 // ─── Dependents subcommand ────────────────────────────────────────────
 /**
@@ -2804,7 +3499,7 @@ async function handleDependents(entityName) {
  *
  * Prints a condensed post-change checklist that guides Claude through
  * re-verifying after user-requested modifications. When called from
- * step 13+, this loops back to step 13 (present). When called from an
+ * step 15+, this loops back to step 15 (present). When called from an
  * earlier step, it returns to that step so the normal flow continues.
  */
 function handleChange(feature) {
@@ -2822,7 +3517,7 @@ function handleChange(feature) {
             process.exit(1);
         }
     }
-    const currentStep = state?.step ?? 13;
+    const currentStep = state?.step ?? 15;
     const port = getServerPort();
     console.log();
     console.log(chalk.bold.cyan('━━━ Change Loop ━━━'));
@@ -2844,6 +3539,8 @@ function handleChange(feature) {
     console.log(chalk.cyan(`  codeyam editor preview '{"dimension":"${dim}"}'`));
     printDimensionGuidance(dim, dimNames);
     console.log(chalk.cyan('  The user is watching the preview. Let them see progress incrementally.'));
+    console.log(chalk.red.bold('  NEVER claim "you should see X" or "the preview shows X" unless you just ran a preview command.'));
+    console.log(chalk.red('  The preview only updates when you explicitly refresh it. Verify, then describe.'));
     console.log();
     console.log(chalk.bold('0. Close the results panel:'));
     checkbox(`Hide results: \`codeyam editor hide-results\``);
@@ -2870,6 +3567,7 @@ function handleChange(feature) {
     console.log(chalk.dim('    re-register "Home - Default", "Catalog - Full", "Detail - WithReviews", etc.'));
     checkbox("Enrich existing scenario data to exercise the change — don't just re-register unchanged data");
     console.log(chalk.dim('    Add data that demonstrates what changed: new fields, relationships, states, content variety.'));
+    console.log(chalk.dim('    If the enriched data makes the scenario name too narrow, rename it to reflect its broader coverage.'));
     checkbox('After each re-registration, view the screenshot to verify data is visible');
     console.log(chalk.dim("    If the screenshot doesn't show the data you put in, the scenario is broken."));
     console.log();
@@ -2878,6 +3576,7 @@ function handleChange(feature) {
     checkbox(`Navigate to key pages to verify changes: \`codeyam editor preview '{"path":"/your-route","dimension":"${dim}"}'\``);
     printDimensionGuidance(dim, dimNames);
     checkbox('Run `codeyam editor scenario-coverage` — all affected scenarios must be fresh');
+    checkbox('Recapture stale scenarios: `codeyam editor recapture-stale`');
     checkbox('Run `codeyam editor audit` — all checks must pass');
     checkbox(`Check for client-side errors: \`codeyam editor client-errors\``);
     console.log(chalk.dim('    If `hasContent=false`, the preview is blank — fix the code before proceeding.'));
@@ -2892,10 +3591,10 @@ function handleChange(feature) {
     console.log(chalk.dim('    Always update the existing uncommitted entry — do NOT create a new one.'));
     console.log(chalk.dim('    Only create a new entry (POST) if no uncommitted entry exists for this feature.'));
     console.log();
-    // If the change was initiated from a step before 13, return to that step
-    // instead of jumping to step 13. The change workflow should only loop to
-    // step 13 when changes are requested FROM step 13.
-    if (currentStep < 13) {
+    // If the change was initiated from a step before 15, return to that step
+    // instead of jumping to step 15. The change workflow should only loop to
+    // step 15 when changes are requested FROM step 15.
+    if (currentStep < 15) {
         console.log(chalk.red('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
         console.log(chalk.red.bold('  REQUIRED: Return to current step'));
         console.log(chalk.red.bold('  When all checks pass, you MUST run: ') +
@@ -2906,7 +3605,7 @@ function handleChange(feature) {
         console.log(chalk.red('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
         console.log(chalk.red.bold('  REQUIRED: Show Results'));
         console.log(chalk.red.bold('  When all checks pass, you MUST run: ') +
-            chalk.bold(`codeyam editor 13`));
+            chalk.bold(`codeyam editor 15`));
         console.log(chalk.red.bold('  The user ALWAYS expects to see results after changes. DO NOT skip this step.'));
         console.log(chalk.red('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
     }
@@ -2917,10 +3616,11 @@ function handleChange(feature) {
  * Fetch the audit result from the server.
  * Returns null if the server is unreachable.
  */
-async function fetchAuditResult() {
+async function fetchAuditResult(options) {
     const port = getServerPort();
+    const params = options?.skipTests ? '?skipTests=true' : '';
     try {
-        const res = await fetch(`http://localhost:${port}/api/editor-audit`);
+        const res = await fetch(`http://localhost:${port}/api/editor-audit${params}`);
         if (!res.ok)
             return null;
         return await res.json();
@@ -2943,17 +3643,34 @@ async function checkAuditGate() {
         return true; // Server unreachable — don't block
     if (data.summary?.allPassing === true)
         return true;
-    // If incomplete entities are the only issue, auto-fix with analyze-imports (once)
-    const { isAutoRemediable } = await import('../utils/editorAudit.js');
-    if (isAutoRemediable(data.summary, false)) {
+    // Lightweight auto-fix: backfill entity_sha (DB-only, fast).
+    // Never run handleAnalyzeImports here — it takes minutes on large projects.
+    const { isOnlyIncompleteEntities, isOnlyPreExistingIncomplete } = await import('../utils/editorAudit.js');
+    // If the only failures are pre-existing incomplete entities (not caused by
+    // this session), don't block — the audit text already calls these "non-blocking".
+    if (isOnlyPreExistingIncomplete(data.summary, data.incompleteEntities)) {
+        return true;
+    }
+    if (isOnlyIncompleteEntities(data.summary)) {
         try {
-            await handleAnalyzeImports({ silent: true });
+            const entities = await loadEntities({});
+            if (entities && entities.length > 0) {
+                const { getDatabase } = await import('../../../packages/database/index.js');
+                const db = getDatabase();
+                await backfillEntityShaOnScenarios(db, entities.map((e) => ({
+                    sha: e.sha,
+                    name: e.name,
+                    filePath: e.filePath || '',
+                    isDefaultExport: e.metadata?.notExported === false &&
+                        e.metadata?.namedExport === false,
+                })));
+            }
         }
         catch {
-            return false;
+            // Fall through
         }
-        // Re-check after fix
-        const retry = await fetchAuditResult();
+        // Re-check after backfill — skip re-running tests (backfill is DB-only)
+        const retry = await fetchAuditResult({ skipTests: true });
         if (retry?.summary?.allPassing === true)
             return true;
     }
@@ -2971,24 +3688,152 @@ function printAuditGateFailures(data) {
     if (!s)
         return;
     const issues = [];
-    if (s.componentsMissing > 0)
+    if (s.componentsMissing > 0) {
         issues.push(`${s.componentsMissing} component(s) missing scenarios`);
-    if (s.componentsWithErrors > 0)
+        const missing = (data.components || []).filter((c) => c.status === 'missing');
+        for (const c of missing) {
+            issues.push(`    → ${c.name}${c.filePath ? ` (${c.filePath})` : ''}`);
+            if (c.hint)
+                issues.push(`      Fix: ${c.hint}`);
+        }
+    }
+    if (s.componentsWithErrors > 0) {
         issues.push(`${s.componentsWithErrors} component(s) with client errors (browser API or runtime errors in captured scenarios)`);
-    if (s.functionsMissing > 0)
+        const withErrors = (data.components || []).filter((c) => c.status === 'has_errors');
+        for (const c of withErrors) {
+            issues.push(`    → ${c.name}${c.filePath ? ` (${c.filePath})` : ''}`);
+        }
+    }
+    if (s.functionsMissing > 0) {
         issues.push(`${s.functionsMissing} function(s) missing test files`);
-    if (s.functionsFailing > 0)
+        const missing = (data.functions || []).filter((f) => f.status === 'missing');
+        for (const f of missing) {
+            if (f.testFile) {
+                issues.push(`    → ${f.name} — test file missing: ${f.testFile}`);
+            }
+            else {
+                issues.push(`    → ${f.name} (${f.filePath}) — no testFile in glossary`);
+                if (f.suggestedTestFile) {
+                    issues.push(`      Fix: Create ${f.suggestedTestFile} or add "testFile": "${f.suggestedTestFile}" to .codeyam/glossary.json`);
+                }
+            }
+        }
+    }
+    if (s.functionsFailing > 0) {
         issues.push(`${s.functionsFailing} function(s) with failing tests`);
-    if (s.functionsRunnerError > 0)
+        const failing = (data.functions || []).filter((f) => f.status === 'failing');
+        for (const f of failing) {
+            issues.push(`    → ${f.name}${f.testFile ? ` (${f.testFile})` : ''}`);
+        }
+    }
+    if (s.functionsRunnerError > 0) {
         issues.push(`${s.functionsRunnerError} function(s) with test runner errors (the runner crashed — not a test failure)`);
-    if (s.functionsNameMismatch > 0)
+        const runnerErrors = (data.functions || []).filter((f) => f.status === 'runner_error');
+        for (const f of runnerErrors) {
+            issues.push(`    → ${f.name}${f.testFile ? ` (${f.testFile})` : ''}`);
+            if (f.hint)
+                issues.push(`      ${f.hint}`);
+            else if (f.errorMessage)
+                issues.push(`      Error: ${f.errorMessage}`);
+        }
+    }
+    if (s.functionsNameMismatch > 0) {
         issues.push(`${s.functionsNameMismatch} function(s) with test name mismatch`);
-    if (s.missingFromGlossary > 0)
+        const mismatch = (data.functions || []).filter((f) => f.status === 'name_mismatch');
+        for (const f of mismatch) {
+            issues.push(`    → ${f.name}${f.testFile ? ` (${f.testFile})` : ''}`);
+            if (f.hint)
+                issues.push(`      Fix: ${f.hint}`);
+        }
+    }
+    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)
+        const missingGlossary = data.missingFromGlossary || [];
+        for (const m of missingGlossary) {
+            issues.push(`    → ${m.name} (${m.filePath})`);
+        }
+        const missingPaths = missingGlossary
+            .map((m) => m.filePath)
+            .filter(Boolean);
+        if (missingPaths.length > 0) {
+            issues.push(`      Fix: Run \`codeyam editor analyze-imports ${missingPaths.join(' ')}\``);
+        }
+        else {
+            issues.push(`      Fix: Run \`codeyam editor analyze-imports\` to add these files to the glossary`);
+        }
+    }
+    if (s.incompleteEntities > 0) {
+        // Check for persistent analysis failures
+        let analysisFailures = {};
+        try {
+            const failuresPath = path.join(getProjectRoot(), '.codeyam', 'analysis-failures.json');
+            if (fs.existsSync(failuresPath)) {
+                analysisFailures = JSON.parse(fs.readFileSync(failuresPath, 'utf8'));
+            }
+        }
+        catch {
+            // Non-fatal
+        }
+        const preCount = s.preExistingIncompleteEntities || 0;
+        const hasFailures = Object.keys(analysisFailures).length > 0;
+        if (hasFailures) {
+            issues.push(`${s.incompleteEntities} entity/entities — automated analysis failed, manual analysis required`);
+        }
+        else if (preCount > 0 && preCount === s.incompleteEntities) {
+            issues.push(`${s.incompleteEntities} entity/entities need import analysis (pre-existing — not caused by your current changes, but must be fixed before proceeding)`);
+        }
+        else if (preCount > 0) {
+            issues.push(`${s.incompleteEntities} entity/entities need import analysis (${preCount} pre-existing — not from your changes)`);
+        }
+        else {
+            issues.push(`${s.incompleteEntities} entity/entities need import analysis`);
+        }
+        const incomplete = data.incompleteEntities || [];
+        for (const e of incomplete) {
+            const failureEntry = Object.values(analysisFailures).find((f) => f.entityName === e.name);
+            if (failureEntry) {
+                issues.push(`    → ${e.name} — MANUAL ANALYSIS REQUIRED (automated analysis failed)`);
+                issues.push(`      Run \`codeyam editor audit\` for step-by-step manual analysis instructions`);
+            }
+            else {
+                issues.push(`    → ${e.name} (${e.scenarioCount} scenario${e.scenarioCount !== 1 ? 's' : ''})${e.preExisting ? ' [pre-existing]' : ''}`);
+            }
+        }
+        if (!hasFailures) {
+            issues.push(`      Fix: Run \`codeyam editor analyze-imports\` to build import graphs`);
+        }
+    }
+    if (s.unassociatedScenarios > 0) {
+        const unassociated = data.unassociatedScenarios || [];
+        const unassocPaths = unassociated
+            .map((u) => u.filePath)
+            .filter(Boolean);
+        if (unassocPaths.length > 0) {
+            issues.push(`${s.unassociatedScenarios} component(s) have scenarios with no entity link — run \`codeyam editor analyze-imports ${unassocPaths.join(' ')}\` then re-run audit`);
+        }
+        else {
+            issues.push(`${s.unassociatedScenarios} component(s) have scenarios with no entity link — run \`codeyam editor analyze-imports\` then re-run audit`);
+        }
+        for (const u of unassociated) {
+            issues.push(`    → ${u.name} (${u.filePath}) — ${u.scenarioCount} scenario${u.scenarioCount !== 1 ? 's' : ''}`);
+        }
+    }
+    if (s.miscategorizedScenarios > 0) {
         issues.push(`${s.miscategorizedScenarios} component(s) using page URLs instead of isolation routes`);
+        const miscategorized = data.miscategorizedScenarios || [];
+        for (const m of miscategorized) {
+            issues.push(`    → ${m.componentName} at ${m.url} (${m.scenarioNames.length} scenario${m.scenarioNames.length !== 1 ? 's' : ''})`);
+        }
+        issues.push(`      Fix: Re-register these as app-level scenarios (with pageFilePath, no componentName) or use isolation routes`);
+    }
+    if (s.scenariosNeedingRecapture > 0) {
+        issues.push(`${s.scenariosNeedingRecapture} scenario(s) need recapture (dependency tree changed)`);
+        const recapture = data.scenariosNeedingRecapture || [];
+        for (const r of recapture) {
+            issues.push(`    → "${r.scenarioName}" (entity: ${r.entityName}, ${r.status?.status || 'changed'})`);
+        }
+        issues.push(`      Fix: Re-capture affected scenarios to update screenshots after code changes`);
+    }
     if (issues.length > 0) {
         console.error(chalk.yellow('\nAudit failures:'));
         for (const issue of issues) {
@@ -3011,8 +3856,6 @@ function printAuditGateFailures(data) {
                 }
             }
             console.error(chalk.yellow('\nFix: Fix the code errors above, then re-capture the affected scenarios.'));
-            console.error(chalk.yellow('If errors reference browser APIs (localStorage, sessionStorage, window, document),'));
-            console.error(chalk.yellow('create a universal mock: codeyam detect-universal-mocks'));
         }
     }
     console.error(chalk.dim('\nRun `codeyam editor audit` for full details.\n'));
@@ -3025,59 +3868,137 @@ function printAuditGateFailures(data) {
  * which glossary components have registered scenarios and which functions
  * have test files. Exits with code 1 if anything is missing.
  */
-async function handleAudit() {
+async function handleAudit(options) {
     let data = await fetchAuditResult();
     if (!data) {
         console.error(chalk.red('Error: Could not reach the CodeYam server. Is it running?'));
         process.exit(1);
     }
-    // Auto-fix incomplete entities — but only once.
-    // If analyze-imports runs and entities are STILL incomplete, report clearly
-    // instead of retrying. The analysis may have errors (e.g., stale entity
-    // references from refactoring) that can't be fixed by re-running.
+    // Two-phase auto-fix for entity associations:
+    // Phase 1: DB-only backfill — fast, matches existing entities to scenarios.
+    // Phase 2: If backfill fails, targeted analyze-imports for only the
+    // specific unresolved files (1-3 files, not the full glossary scan).
     const incompleteBeforeFix = data.incompleteEntities || [];
+    const unassociatedBeforeFix = data.unassociatedScenarios || [];
     let autoRemediationFailed = false;
-    if (incompleteBeforeFix.length > 0) {
-        console.log(chalk.dim(`Running import analysis for ${incompleteBeforeFix.length} incomplete entit${incompleteBeforeFix.length !== 1 ? 'ies' : 'y'}...`));
+    if (incompleteBeforeFix.length > 0 || unassociatedBeforeFix.length > 0) {
+        const issueCount = incompleteBeforeFix.length + unassociatedBeforeFix.length;
+        console.log(chalk.dim(`Backfilling ${issueCount} entity association issue${issueCount !== 1 ? 's' : ''}...`));
+        // Backfill entity_sha on scenarios that were registered before entities existed
         try {
-            await handleAnalyzeImports({ silent: true });
+            const entities = await loadEntities({});
+            if (entities && entities.length > 0) {
+                const { getDatabase } = await import('../../../packages/database/index.js');
+                const db = getDatabase();
+                await backfillEntityShaOnScenarios(db, entities.map((e) => ({
+                    sha: e.sha,
+                    name: e.name,
+                    filePath: e.filePath || '',
+                    isDefaultExport: e.metadata?.notExported === false &&
+                        e.metadata?.namedExport === false,
+                })));
+            }
         }
         catch {
-            // Fall through — the audit will still report them as incomplete
+            // Fall through — re-fetch will show remaining issues
         }
-        // Re-fetch audit results after the fix
-        data = await fetchAuditResult();
+        // Re-fetch audit results after the backfill — skip re-running tests
+        // since they haven't changed (backfill is DB-only).
+        data = await fetchAuditResult({ skipTests: true });
         if (!data) {
-            console.error(chalk.red('Error: Could not reach the CodeYam server after analyze-imports.'));
+            console.error(chalk.red('Error: Could not reach the CodeYam server after backfill.'));
             process.exit(1);
         }
-        // If entities are still incomplete after running analyze-imports,
-        // flag it so we can show a clear message instead of looping
+        // If issues persist after DB-only backfill, run targeted analyze-imports
+        // for ONLY the specific files that need entities. This is fast (1-3 files)
+        // unlike full analyze-imports which scans all glossary entries.
+        const incompleteAfterBackfill = data.incompleteEntities || [];
+        const unassociatedAfterBackfill = data.unassociatedScenarios || [];
+        if (incompleteAfterBackfill.length > 0 ||
+            unassociatedAfterBackfill.length > 0) {
+            const { determineTargetedAnalysisPaths } = await import('../utils/editorAudit.js');
+            const targetPaths = determineTargetedAnalysisPaths({
+                unassociatedScenarios: unassociatedAfterBackfill,
+                incompleteEntities: incompleteAfterBackfill,
+            });
+            if (targetPaths.length > 0) {
+                console.log(chalk.dim(`Running targeted analysis for ${targetPaths.length} file${targetPaths.length !== 1 ? 's' : ''}...`));
+                try {
+                    await handleAnalyzeImports({
+                        silent: true,
+                        filePaths: targetPaths,
+                    });
+                    // Retry backfill after analysis created entities
+                    const entities = await loadEntities({});
+                    if (entities && entities.length > 0) {
+                        const { getDatabase: getDb } = await import('../../../packages/database/index.js');
+                        const freshDb = getDb();
+                        await backfillEntityShaOnScenarios(freshDb, entities.map((e) => ({
+                            sha: e.sha,
+                            name: e.name,
+                            filePath: e.filePath || '',
+                            isDefaultExport: e.metadata?.notExported === false &&
+                                e.metadata?.namedExport === false,
+                        })));
+                    }
+                    // Re-fetch audit results after targeted analysis
+                    data = await fetchAuditResult({ skipTests: true });
+                    if (!data) {
+                        console.error(chalk.red('Error: Could not reach the CodeYam server after analysis.'));
+                        process.exit(1);
+                    }
+                }
+                catch {
+                    // Targeted analysis failed — fall through to show remaining issues
+                }
+            }
+        }
+        // Check if issues persist after all remediation attempts
         const incompleteAfterFix = data.incompleteEntities || [];
-        if (incompleteAfterFix.length > 0) {
+        const unassociatedAfterFix = data.unassociatedScenarios || [];
+        if (incompleteAfterFix.length > 0 || unassociatedAfterFix.length > 0) {
             autoRemediationFailed = true;
         }
     }
-    const { components, functions, summary } = data;
+    let { components, functions, summary } = data;
     console.log();
     console.log(chalk.bold.cyan('━━━ Editor Audit ━━━'));
     console.log();
     // Components
     if (components.length > 0) {
+        // Build name frequency map for disambiguation
+        const componentNameCounts = new Map();
+        for (const c of components) {
+            componentNameCounts.set(c.name, (componentNameCounts.get(c.name) || 0) + 1);
+        }
         console.log(chalk.bold('Components (scenarios):'));
         for (const c of components) {
-            const icon = c.status === 'ok' ? chalk.green('✓') : chalk.red('✗');
+            const icon = c.status === 'ok'
+                ? chalk.green('✓')
+                : c.status === 'needs_recapture'
+                    ? chalk.yellow('↻')
+                    : chalk.red('✗');
             let detail;
             if (c.status === 'has_errors') {
                 detail = chalk.red(` — ${c.scenarioCount} scenario${c.scenarioCount !== 1 ? 's' : ''} but has client errors`);
             }
+            else if (c.status === 'needs_recapture') {
+                detail = chalk.yellow(` — ${c.scenarioCount} scenario${c.scenarioCount !== 1 ? 's' : ''}, needs recapture`);
+            }
             else if (c.status === 'ok') {
                 detail = chalk.dim(` (${c.scenarioCount} scenario${c.scenarioCount !== 1 ? 's' : ''})`);
             }
             else {
                 detail = chalk.red(' — no scenarios registered');
+                if (c.hint) {
+                    detail += `\n      ${chalk.yellow('Fix: ' + c.hint)}`;
+                }
             }
-            console.log(`  ${icon} ${c.name}${detail}`);
+            // Show file path for failing components always, for OK only when name is ambiguous
+            const isDuplicate = (componentNameCounts.get(c.name) || 0) > 1;
+            const showPath = (c.status !== 'ok' && c.status !== 'needs_recapture') || isDuplicate;
+            const pathSuffix = showPath && c.filePath ? chalk.dim(` (${c.filePath})`) : '';
+            console.log(`  ${icon} ${c.name}${pathSuffix}${detail}`);
             if (c.clientErrors && c.clientErrors.length > 0) {
                 for (const err of c.clientErrors.slice(0, 3)) {
                     console.log(chalk.red(`      → ${err}`));
@@ -3085,14 +4006,6 @@ async function handleAudit() {
                 if (c.clientErrors.length > 3) {
                     console.log(chalk.dim(`      … and ${c.clientErrors.length - 3} more`));
                 }
-                // Detect browser API errors and provide actionable guidance
-                const browserApiPattern = /\b(localStorage|sessionStorage|window\.|document\.|navigator\.|indexedDB|matchMedia|ResizeObserver|IntersectionObserver|MutationObserver)\b/;
-                const hasBrowserApiErrors = c.clientErrors.some((err) => browserApiPattern.test(err));
-                if (hasBrowserApiErrors) {
-                    console.log(chalk.yellow(`      ⚠ These errors are caused by browser APIs that don't exist during server-side analysis.`));
-                    console.log(chalk.yellow(`      Fix: Create a universal mock to stub the missing API. Run: codeyam detect-universal-mocks`));
-                    console.log(chalk.yellow(`      DO NOT re-run the audit or analyze-imports — the error will persist until a mock is created.`));
-                }
             }
         }
         console.log();
@@ -3112,7 +4025,8 @@ async function handleAudit() {
                     if (f.errorMessage) {
                         detail += `\n      ${chalk.red(f.errorMessage)}`;
                         detail += `\n      ${chalk.yellow('Note: This is NOT a test failure — the test runner itself could not execute.')}`;
-                        detail += `\n      ${chalk.yellow('Try running the test manually: npx vitest run ' + f.testFile)}`;
+                        const ctx = getTechStackContext(process.cwd());
+                        detail += `\n      ${chalk.yellow('Try running the test manually: ' + ctx.testRunCommand + ' ' + f.testFile)}`;
                     }
                     break;
                 case 'failing':
@@ -3123,9 +4037,16 @@ async function handleAudit() {
                     break;
                 case 'missing':
                 default:
-                    detail = f.testFile
-                        ? chalk.red(` — test file missing: ${f.testFile}`)
-                        : chalk.red(' — no test file specified');
+                    if (f.testFile) {
+                        detail = chalk.red(` — test file missing: ${f.testFile}`);
+                    }
+                    else {
+                        detail = chalk.red(` — no test file specified in glossary`);
+                        detail += chalk.dim(` (source: ${f.filePath})`);
+                        if (f.suggestedTestFile) {
+                            detail += `\n      ${chalk.yellow(`Fix: Either create ${f.suggestedTestFile} or add "testFile": "${f.suggestedTestFile}" to this entry in .codeyam/glossary.json`)}`;
+                        }
+                    }
                     break;
             }
             console.log(`  ${icon} ${f.name}${detail}`);
@@ -3139,28 +4060,85 @@ async function handleAudit() {
         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`'));
+        const mgPaths = missingFromGlossary
+            .map((m) => m.filePath)
+            .filter(Boolean);
+        if (mgPaths.length > 0) {
+            console.log(chalk.yellow(`    Add these to .codeyam/glossary.json and run \`codeyam editor analyze-imports ${mgPaths.join(' ')}\``));
+        }
+        else {
+            console.log(chalk.yellow('    Add these to .codeyam/glossary.json and run `codeyam editor analyze-imports`'));
+        }
         console.log();
     }
-    // Incomplete entities (scenarios without analyses)
+    // Incomplete entities (scenarios without analyses) — report with guidance.
+    // We intentionally do NOT run analysis here: it starts the analyzer
+    // template which is slow even for a few files. Users should run
+    // `codeyam editor analyze-imports` separately if needed.
     const incompleteEntities = data.incompleteEntities || [];
     if (incompleteEntities.length > 0) {
+        const { formatIncompleteEntityGuidance, formatManualAnalysisGuidance } = await import('../utils/editorAudit.js');
+        const { readAnalysisFailures } = await import('../utils/manualEntityAnalysis.js');
+        // Check for persistent analysis failures
+        const analysisFailures = readAnalysisFailures(getProjectRoot());
         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`);
+            // Check if this entity has a persistent failure
+            const failureEntry = Object.values(analysisFailures).find((f) => f.entityName === e.name);
+            if (failureEntry) {
+                // Show manual analysis instructions instead of "run analyze-imports"
+                const filePath = Object.entries(analysisFailures).find(([, f]) => f.entityName === e.name)?.[0];
+                const guidance = formatManualAnalysisGuidance({
+                    name: e.name,
+                    filePath: filePath || '',
+                    scenarioCount: e.scenarioCount,
+                    error: failureEntry.error,
+                });
+                // Print each line with proper indentation
+                for (const line of guidance.split('\n')) {
+                    console.log(`  ${chalk.red('✗')} ${line}`);
+                }
+            }
+            else {
+                const guidance = formatIncompleteEntityGuidance(e);
+                console.log(`  ${chalk.red('✗')} ${guidance}`);
+            }
+        }
+        const incompleteErrorReportPath = path.join(getProjectRoot(), '.codeyam', 'analysis-errors.txt');
+        if (fs.existsSync(incompleteErrorReportPath)) {
+            console.log(chalk.dim('    See .codeyam/analysis-errors.txt for error details.'));
+        }
+        console.log();
+    }
+    // Unassociated scenarios (NULL entity_sha with file paths)
+    const unassociatedScenarios = data.unassociatedScenarios || [];
+    if (unassociatedScenarios.length > 0) {
+        console.log(chalk.bold('Unassociated scenarios (missing entity link):'));
+        for (const u of unassociatedScenarios) {
+            console.log(`  ${chalk.red('✗')} ${u.name} ${chalk.dim(`(${u.filePath})`)} — ${u.scenarioCount} scenario${u.scenarioCount !== 1 ? 's' : ''} with no entity_sha`);
+            for (const sn of u.scenarioNames.slice(0, 3)) {
+                console.log(chalk.dim(`      "${sn}"`));
+            }
+            if (u.scenarioNames.length > 3) {
+                console.log(chalk.dim(`      … and ${u.scenarioNames.length - 3} more`));
+            }
         }
+        const uaPaths = unassociatedScenarios
+            .map((u) => u.filePath)
+            .filter(Boolean);
+        const uaCmd = uaPaths.length > 0
+            ? `codeyam editor analyze-imports ${uaPaths.join(' ')}`
+            : 'codeyam editor analyze-imports';
         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`'));
+            console.log(chalk.yellow('    analyze-imports ran automatically but could not resolve these.'));
+            console.log(chalk.yellow(`    Run \`${uaCmd}\` to see the full error output.`));
         }
         else {
-            console.log(chalk.yellow('    Run `codeyam editor analyze-imports` to analyze these entities'));
+            console.log(chalk.yellow(`    Run \`${uaCmd}\` to create entity records, then re-run audit to backfill.`));
+        }
+        const unassocErrorReportPath = path.join(getProjectRoot(), '.codeyam', 'analysis-errors.txt');
+        if (fs.existsSync(unassocErrorReportPath)) {
+            console.log(chalk.dim('    See .codeyam/analysis-errors.txt for error details.'));
         }
         console.log();
     }
@@ -3179,6 +4157,51 @@ async function handleAudit() {
         console.log(chalk.yellow('    or re-register with an isolation URL.'));
         console.log();
     }
+    // Scenarios needing recapture (entity or dependency tree changed)
+    const scenariosNeedingRecapture = data.scenariosNeedingRecapture || [];
+    if (scenariosNeedingRecapture.length > 0) {
+        console.log(chalk.bold('Scenarios needing recapture (dependency tree changed):'));
+        for (const s of scenariosNeedingRecapture) {
+            const reason = s.status.status === 'impacted' && s.status.impactedBy?.length
+                ? `impacted by: ${s.status.impactedBy.map((d) => `${d.name} [${d.changeType}]`).join(', ')}`
+                : `${s.status.status}`;
+            console.log(`  ${chalk.red('✗')} ${s.scenarioName} ${chalk.dim(`(${s.entityName} — ${reason})`)}`);
+        }
+        if (options?.fix) {
+            // --fix: auto-recapture stale scenarios instead of just reporting them
+            const { shouldAutoRecapture } = await import('../utils/editorAudit.js');
+            if (shouldAutoRecapture({ fix: true, scenariosNeedingRecapture })) {
+                console.log(chalk.cyan('    --fix: auto-recapturing stale scenarios...'));
+                console.log();
+                await handleRecaptureStale();
+                // Re-fetch audit results so the summary and exit code reflect
+                // the post-fix state, not the pre-fix state.
+                const refreshed = await fetchAuditResult({ skipTests: true });
+                if (refreshed) {
+                    data = refreshed;
+                    ({ components, functions, summary } = data);
+                }
+            }
+        }
+        else {
+            console.log(chalk.yellow('    Run: codeyam editor recapture-stale'));
+            console.log(chalk.dim('    Or: codeyam editor audit --fix (to auto-recapture)'));
+        }
+        console.log();
+    }
+    // Duplicate glossary names (warning, not a failure)
+    const duplicateNames = data.duplicateNames || [];
+    if (duplicateNames.length > 0) {
+        console.log(chalk.bold('Duplicate names in glossary (confusing for audit):'));
+        for (const dn of duplicateNames) {
+            console.log(`  ${chalk.yellow('⚠')} "${dn.name}" appears ${dn.filePaths.length} times:`);
+            for (const fp of dn.filePaths) {
+                console.log(`      ${fp}`);
+            }
+        }
+        console.log(chalk.yellow('    Fix: remove duplicate entries or rename them to be unique in .codeyam/glossary.json'));
+        console.log();
+    }
     // Summary
     const allOk = summary.allPassing;
     if (allOk) {
@@ -3211,25 +4234,123 @@ async function handleAudit() {
         if (summary.incompleteEntities > 0) {
             parts.push(`${summary.incompleteEntities} entit${summary.incompleteEntities !== 1 ? 'ies' : 'y'} need import analysis`);
         }
+        if (summary.unassociatedScenarios > 0) {
+            parts.push(`${summary.unassociatedScenarios} component${summary.unassociatedScenarios !== 1 ? 's' : ''} with scenarios missing entity link`);
+        }
         if (summary.miscategorizedScenarios > 0) {
             parts.push(`${summary.miscategorizedScenarios} component${summary.miscategorizedScenarios !== 1 ? 's' : ''} using page URLs instead of isolation routes`);
         }
+        if (summary.scenariosNeedingRecapture > 0) {
+            parts.push(`${summary.scenariosNeedingRecapture} scenario${summary.scenariosNeedingRecapture !== 1 ? 's' : ''} need recapture`);
+        }
         console.log(chalk.red.bold('Audit failed: ') + parts.join(', '));
     }
     console.log();
     if (!allOk) {
         process.exit(1);
     }
-    // Auto-run analyze-imports when audit passes — this builds the import graph
-    // so the App tab can show component/function dependencies for each page.
-    // Previously this was a manual step that Claude had to remember to run.
-    console.log(chalk.dim('Building import graph...'));
+}
+// ─── Recapture-stale subcommand ────────────────────────────────────────
+/**
+ * `codeyam editor recapture-stale`
+ *
+ * Identifies all scenarios whose entity (or dependency) has changed but
+ * whose screenshot hasn't been recaptured this session, then recaptures
+ * them in batch.
+ */
+async function handleRecaptureStale() {
+    const port = getServerPort();
+    const url = `http://localhost:${port}/api/editor-recapture-stale`;
+    console.log();
+    console.log(chalk.bold.cyan('━━━ Recapture Stale Scenarios ━━━'));
+    console.log();
+    let res;
     try {
-        await handleAnalyzeImports({ silent: true });
+        res = await fetch(url, { method: 'POST' });
     }
-    catch {
-        // Non-fatal — audit passed, import graph is a bonus
-        console.log(chalk.yellow('Warning: Could not build import graph. Run `codeyam editor analyze-imports` manually.'));
+    catch (err) {
+        console.error(chalk.red('Error: Could not reach the CodeYam server. Is it running?'));
+        console.error(chalk.dim(`  ${err.message}`));
+        process.exit(1);
+    }
+    if (!res.ok) {
+        const body = await res.json().catch(() => null);
+        console.error(chalk.red(`Error: Recapture endpoint returned ${res.status}`));
+        if (body?.error)
+            console.error(chalk.red(`  ${body.error}`));
+        process.exit(1);
+    }
+    // Handle JSON response (early returns like "no changes" / "all up to date")
+    const contentType = res.headers.get('content-type') || '';
+    if (contentType.includes('application/json')) {
+        const data = await res.json();
+        if (data.note) {
+            console.log(chalk.dim(data.note));
+        }
+        else if (data.total === 0) {
+            console.log(chalk.green('All scenarios are up to date.'));
+        }
+        console.log();
+        return;
+    }
+    // Stream NDJSON progress events
+    let total = 0;
+    let recapturedCount = 0;
+    let failedCount = 0;
+    const reader = res.body?.getReader();
+    if (!reader) {
+        console.error(chalk.red('Error: No response body'));
+        process.exit(1);
+    }
+    const decoder = new TextDecoder();
+    let buffer = '';
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || ''; // Keep incomplete last line in buffer
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            try {
+                const event = JSON.parse(line);
+                switch (event.type) {
+                    case 'start':
+                        total = event.total;
+                        console.log(`Found ${total} stale scenario(s). Recapturing...\n`);
+                        break;
+                    case 'capturing':
+                        process.stdout.write(chalk.dim(`  … ${event.name}`));
+                        break;
+                    case 'success':
+                        // Clear the "capturing" line and print success
+                        process.stdout.write('\r\x1b[K');
+                        console.log(`  ${chalk.green('✓')} ${event.name}`);
+                        recapturedCount++;
+                        break;
+                    case 'failure':
+                        process.stdout.write('\r\x1b[K');
+                        console.log(`  ${chalk.red('✗')} ${event.name} — ${chalk.dim(event.error)}`);
+                        failedCount++;
+                        break;
+                    case 'done':
+                        // Final summary
+                        console.log();
+                        const color = failedCount > 0 ? chalk.yellow : chalk.green;
+                        console.log(color(`Recaptured ${recapturedCount}/${total} scenario(s).`));
+                        console.log();
+                        break;
+                }
+            }
+            catch {
+                // Skip unparseable lines
+            }
+        }
+    }
+    if (failedCount > 0) {
+        process.exit(1);
     }
 }
 // ─── Scenarios subcommand ─────────────────────────────────────────────
@@ -3334,14 +4455,14 @@ 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 { countScenariosNeedingEntityBackfill } = await import('../utils/editorScenarios.js');
         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 { backfillEntityShaOnScenarios } = await import('../utils/editorScenarios.js');
             const entities = await loadEntities({});
             if (entities && entities.length > 0) {
                 await backfillEntityShaOnScenarios(db, entities.map((e) => ({
@@ -3479,7 +4600,7 @@ async function handleTemplate() {
         console.log(chalk.green('  Git initialized.'));
     }
     // 4. Run codeyam init
-    console.log(chalk.bold('Running codeyam init...'));
+    console.log(chalk.bold('Initializing project...'));
     await initCommand.handler({
         force: true,
         'keep-server': true,
@@ -3488,7 +4609,7 @@ async function handleTemplate() {
         _: [],
     });
     console.log(chalk.green('  CodeYam initialized.'));
-    // 5. Verify config has startCommand
+    // 5. Verify config has startCommand and set format-specific defaults
     const configPath = path.join(root, '.codeyam', 'config.json');
     if (fs.existsSync(configPath)) {
         try {
@@ -3499,6 +4620,26 @@ async function handleTemplate() {
                 console.log(chalk.yellow('  Warning: No startCommand found in .codeyam/config.json webapps.'));
                 console.log(chalk.dim('  You may need to add: "startCommand": { "command": "sh", "args": ["-c", "npm run dev -- --port $PORT"] }'));
             }
+            // Store appFormats from the tech stack so the editor UI can adapt
+            if (stack?.supportedFormats) {
+                config.appFormats = stack.supportedFormats;
+            }
+            // Set mobile-first defaults for mobile-app projects
+            if (stack?.supportedFormats?.includes('mobile-app')) {
+                config.defaultScreenSize = {
+                    name: 'iPhone 16',
+                    width: 393,
+                    height: 852,
+                };
+                config.screenSizes = {
+                    'iPhone 16': { width: 393, height: 852 },
+                    'iPhone 16 Pro Max': { width: 430, height: 932 },
+                    'iPhone SE': { width: 375, height: 667 },
+                    'Pixel 8': { width: 412, height: 915 },
+                    'iPad mini': { width: 744, height: 1133 },
+                };
+            }
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
         }
         catch {
             // Config parse error is non-fatal
@@ -3533,7 +4674,15 @@ async function handleTemplate() {
     }
     console.log();
     console.log(chalk.green.bold('Project scaffolded and ready!'));
-    console.log(chalk.dim('Next: Define your Prisma models, push the schema, seed the database, and build your feature.'));
+    if (stack?.id === 'expo-react-native') {
+        console.log(chalk.dim('Next: Set up your data types, configure the theme in lib/theme.ts, and build your feature.'));
+    }
+    else if (stack?.id === 'chrome-extension-react') {
+        console.log(chalk.dim('Next: Configure your extension manifest and build your feature.'));
+    }
+    else {
+        console.log(chalk.dim('Next: Define your Prisma models, push the schema, seed the database, and build your feature.'));
+    }
 }
 // ─── Sync subcommand ─────────────────────────────────────────────────
 /**
@@ -3558,7 +4707,7 @@ async function handleSync() {
         // fall through
     }
     if (!projectSlug) {
-        console.error(chalk.red('Error: No project slug found. Run codeyam init first.'));
+        console.error(chalk.red('Error: No project slug found. Run `codeyam editor template` to initialize the project.'));
         process.exit(1);
     }
     const connectionOk = await withoutSpinner(() => testEnvironment());
@@ -3742,7 +4891,7 @@ function handleEditorDebug(args) {
         scenarios.push({
             id: 'overview-with-state',
             title: 'Cycle overview (project, with state)',
-            render: () => withTempRoot(true, (tempRoot) => captureOutput(() => printCycleOverview(tempRoot, makeState(4, feature)))),
+            render: () => withTempRoot(true, (tempRoot) => captureOutput(() => printCycleOverview(tempRoot, makeState(6, feature)))),
         });
     }
     const stepFns = {
@@ -3762,8 +4911,10 @@ function handleEditorDebug(args) {
         14: printStep14,
         15: printStep15,
         16: printStep16,
+        17: printStep17,
+        18: printStep18,
     };
-    for (let step = 1; step <= 16; step++) {
+    for (let step = 1; step <= 18; step++) {
         const stepId = `step-${step}`;
         if (!wants(stepId))
             continue;
@@ -3783,7 +4934,7 @@ function handleEditorDebug(args) {
             if (step === 2) {
                 scenarios.push({
                     id: 'step-2-scaffold',
-                    title: 'Step 2 (Prototype) — scaffold flow (no project)',
+                    title: 'Step 2 (Prepare) — scaffold flow (no project)',
                     render: () => withTempRoot(false, (tempRoot) => captureOutput(() => printStep2(tempRoot, feature))),
                 });
             }
@@ -3836,14 +4987,205 @@ function handleEditorDebug(args) {
     console.log(chalk.dim('  Open index.md for the full list of scenario outputs.'));
     console.log();
 }
+// ─── Manual entity analysis ───────────────────────────────────────────
+/**
+ * `codeyam editor manual-entity <JSON|@file>`
+ *
+ * Creates entity and analysis records from Claude-provided metadata when
+ * automated analyze-imports fails. This unblocks the audit gate without
+ * needing the analyzer template to parse the source file.
+ */
+async function handleManualEntity(jsonArg) {
+    const root = getProjectRoot();
+    // Parse JSON input (supports @file.json convention)
+    const parsed = parseRegisterArg(jsonArg);
+    if (parsed.error || !parsed.body) {
+        console.error(chalk.red(`Error: ${parsed.error || 'Invalid input'}`));
+        console.error(chalk.dim('  Usage: codeyam editor manual-entity \'{"name":"Header","filePath":"src/components/Header.tsx","entityType":"visual",...}\''));
+        console.error(chalk.dim('  Or: codeyam editor manual-entity @.codeyam/tmp/manual-entity.json'));
+        process.exit(1);
+    }
+    const input = parsed.body;
+    // Validate input
+    const { validateManualEntityInput, convertTypeInfoToDataForMocks, readAnalysisFailures, clearFailureForPath, writeAnalysisFailures, } = await import('../utils/manualEntityAnalysis.js');
+    // Read glossary for validation
+    const glossaryPath = path.join(root, '.codeyam', 'glossary.json');
+    let glossaryEntries = [];
+    try {
+        glossaryEntries = sanitizeGlossaryEntries(JSON.parse(fs.readFileSync(glossaryPath, 'utf8')));
+    }
+    catch {
+        // Empty glossary — validation will still check file existence
+    }
+    const errors = validateManualEntityInput(input, glossaryEntries, {
+        fileExists: (p) => fs.existsSync(path.join(root, p)),
+    });
+    if (errors.length > 0) {
+        console.error(chalk.red('Validation errors:'));
+        for (const err of errors) {
+            console.error(chalk.red(`  • ${err}`));
+        }
+        process.exit(1);
+    }
+    // Read source file and compute SHA
+    const sourceContent = fs.readFileSync(path.join(root, input.filePath), 'utf8');
+    const { generateSha } = await import('../../../packages/database/index.js');
+    const entitySha = generateSha(input.filePath, input.name, sourceContent);
+    // Get project and branch
+    await initializeEnvironment();
+    const configPath = path.join(root, '.codeyam', 'config.json');
+    let projectSlug;
+    try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        projectSlug = config.projectSlug;
+    }
+    catch {
+        console.error(chalk.red('Error: .codeyam/config.json not found or invalid.'));
+        process.exit(1);
+    }
+    const { project, branch } = await requireBranchAndProject(projectSlug);
+    const { getDatabase } = await import('../../../packages/database/index.js');
+    const db = getDatabase();
+    // Convert type info to dataForMocks format
+    const dataForMocks = convertTypeInfoToDataForMocks(input.typeInfo);
+    // Create entity record
+    const entityMetadata = {
+        importedExports: (input.importedExports || []).map((ie) => ({
+            name: ie.name,
+            filePath: ie.filePath,
+        })),
+        manuallyAnalyzed: true,
+    };
+    // Check if entity already exists
+    const existingEntity = await db
+        .selectFrom('entities')
+        .select('sha')
+        .where('sha', '=', entitySha)
+        .executeTakeFirst();
+    if (!existingEntity) {
+        await db
+            .insertInto('entities')
+            .values({
+            sha: entitySha,
+            project_id: project.id,
+            name: input.name,
+            entity_type: input.entityType,
+            file_path: input.filePath,
+            metadata: JSON.stringify(entityMetadata),
+        })
+            .onConflict((oc) => oc.column('sha').doNothing())
+            .execute();
+        console.log(chalk.dim(`Created entity record: ${input.name} (${entitySha.slice(0, 8)}...)`));
+    }
+    else {
+        // Update metadata on existing entity
+        await db
+            .updateTable('entities')
+            .set({
+            metadata: JSON.stringify(entityMetadata),
+        })
+            .where('sha', '=', entitySha)
+            .execute();
+        console.log(chalk.dim(`Updated existing entity: ${input.name} (${entitySha.slice(0, 8)}...)`));
+    }
+    // Create entity_branch record
+    await db
+        .insertInto('entity_branches')
+        .values({
+        entity_sha: entitySha,
+        branch_id: branch.id,
+        active: true,
+    })
+        .onConflict((oc) => oc.columns(['entity_sha', 'branch_id']).doUpdateSet({ active: true }))
+        .execute();
+    // Create analysis record
+    const { randomUUID } = await import('crypto');
+    const analysisId = randomUUID();
+    const now = new Date().toISOString();
+    const analysisMetadata = {
+        scenariosDataStructure: {
+            dataForMocks: Object.keys(dataForMocks).length > 0 ? dataForMocks : null,
+        },
+        mergedDataStructure: {
+            dependencySchemas: null,
+        },
+        manuallyAnalyzed: true,
+    };
+    const analysisStatus = {
+        startedAt: now,
+        finishedAt: now,
+        steps: [],
+        errors: [],
+    };
+    // Check if analysis already exists for this entity
+    const existingAnalysis = await db
+        .selectFrom('analyses')
+        .select('id')
+        .where('entity_sha', '=', entitySha)
+        .executeTakeFirst();
+    if (!existingAnalysis) {
+        await db
+            .insertInto('analyses')
+            .values({
+            id: analysisId,
+            project_id: project.id,
+            entity_sha: entitySha,
+            entity_name: input.name,
+            entity_type: input.entityType,
+            file_path: input.filePath,
+            status: JSON.stringify(analysisStatus),
+            metadata: JSON.stringify(analysisMetadata),
+        })
+            .execute();
+        console.log(chalk.dim(`Created analysis record: ${analysisId.slice(0, 8)}...`));
+    }
+    else {
+        // Update existing analysis with manual metadata
+        await db
+            .updateTable('analyses')
+            .set({
+            metadata: JSON.stringify(analysisMetadata),
+            status: JSON.stringify(analysisStatus),
+        })
+            .where('entity_sha', '=', entitySha)
+            .execute();
+        console.log(chalk.dim(`Updated existing analysis for ${input.name}`));
+    }
+    // Backfill entity_sha on scenarios
+    const backfillResult = await backfillEntityShaOnScenarios(db, [
+        {
+            sha: entitySha,
+            name: input.name,
+            filePath: input.filePath,
+            isDefaultExport: false,
+        },
+    ]);
+    if (backfillResult.updated > 0) {
+        console.log(chalk.dim(`Linked ${backfillResult.updated} scenario(s) to entity`));
+    }
+    // Clear from analysis failures tracker
+    const failures = readAnalysisFailures(root);
+    if (failures[input.filePath]) {
+        const updated = clearFailureForPath(failures, input.filePath);
+        writeAnalysisFailures(root, updated);
+        console.log(chalk.dim(`Cleared analysis failure for ${input.filePath}`));
+    }
+    console.log();
+    console.log(chalk.green.bold(`✓ Manual entity analysis complete: ${input.name}`));
+    console.log(chalk.dim(`  Entity SHA: ${entitySha.slice(0, 12)}...`));
+    console.log(chalk.dim(`  Imports: ${(input.importedExports || []).length} glossary entities`));
+    console.log(chalk.dim(`  Type info: ${Object.keys(dataForMocks).length} fields`));
+    console.log();
+    console.log(chalk.dim('Re-run `codeyam editor audit` to verify.'));
+}
 // ─── Command definition ───────────────────────────────────────────────
 const editorCommand = {
     command: 'editor [step] [json]',
     describe: 'Editor mode guided workflow',
     builder: (yargs) => {
         const stepDescription = IS_INTERNAL_BUILD
-            ? 'Step number (1-16) or subcommand (template, register, isolate, analyze-imports, dependents, audit, scenarios, scenario-coverage, change, sync, debug, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors)'
-            : 'Step number (1-16) or subcommand (template, register, isolate, analyze-imports, dependents, audit, scenarios, scenario-coverage, change, sync, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors)';
+            ? 'Step number (1-18) or subcommand (template, register, isolate, analyze-imports, manual-entity, dependents, audit, scenarios, scenario-coverage, recapture-stale, change, sync, debug, design-system, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors, task-ontrack)'
+            : 'Step number (1-18) or subcommand (template, register, isolate, analyze-imports, manual-entity, dependents, audit, scenarios, scenario-coverage, recapture-stale, change, sync, design-system, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors, task-ontrack)';
         let builder = yargs
             .positional('step', {
             type: 'string',
@@ -3874,12 +5216,17 @@ const editorCommand = {
             alias: 'p',
             describe: 'Port to run the web server on',
             default: 3111,
+        })
+            .option('fix', {
+            type: 'boolean',
+            describe: 'For audit: also recapture stale scenarios after displaying results',
+            default: false,
         });
         if (IS_INTERNAL_BUILD) {
             builder = builder
                 .option('target', {
                 type: 'string',
-                describe: 'Debug target (setup, overview, overview-with-state, step-1..step-16, or comma-separated list)',
+                describe: 'Debug target (setup, overview, overview-with-state, step-1..step-18, or comma-separated list)',
             })
                 .option('resume', {
                 type: 'boolean',
@@ -3904,6 +5251,18 @@ const editorCommand = {
         // API subcommands: preview, show-results, hide-results, commit,
         // journal, journal-update, dev-server, client-errors
         if (argv.step && EDITOR_API_SUBCOMMANDS.includes(argv.step)) {
+            // Guard: commit requires step 16 to have been run first.
+            // Without this, Claude shortcuts the process by running
+            // `codeyam editor commit` directly from step 15, skipping
+            // steps 16-18 entirely.
+            if (argv.step === 'commit') {
+                const state = readState(root);
+                if (state && state.step !== 16) {
+                    console.error(chalk.red('Error: Run `codeyam editor 16` before committing.'));
+                    console.error(chalk.dim(`  Current step: ${state.step} (${state.label || 'unknown'}). Step 16 (Commit) must be run first.`));
+                    process.exit(1);
+                }
+            }
             const port = getServerPort();
             try {
                 const request = buildEditorApiRequest(argv.step, argv.json || undefined);
@@ -3923,6 +5282,12 @@ const editorCommand = {
                         console.log(JSON.stringify(result.data, null, 2));
                     }
                 }
+                // After a successful commit, remind Claude to continue to step 17
+                if (argv.step === 'commit' && result.ok) {
+                    console.log();
+                    console.log(chalk.green('Commit done. Now run: ') +
+                        chalk.bold('codeyam editor 17'));
+                }
             }
             catch (err) {
                 console.error(chalk.red('Error: Could not reach the CodeYam server. Is it running?'));
@@ -3936,9 +5301,63 @@ const editorCommand = {
             await handleRegister(argv.json || '');
             return;
         }
-        // Subcommand: codeyam editor analyze-imports
+        // Subcommand: codeyam editor glossary-add '{"name":"...", ...}'
+        if (argv.step === 'glossary-add') {
+            await handleGlossaryAdd(argv.json || '');
+            return;
+        }
+        // Subcommand: codeyam editor task-ontrack
+        // Corrective command when Claude advanced without creating a task.
+        if (argv.step === 'task-ontrack') {
+            const state = readState(root);
+            if (!state?.step) {
+                console.error(chalk.red('No editor state found. Run `codeyam editor 1` to start.'));
+                process.exit(1);
+            }
+            const currentLabel = STEP_LABELS[state.step] || `Step ${state.step}`;
+            const totalSteps = Object.keys(STEP_LABELS).length;
+            const nextLabel = state.step < totalSteps ? STEP_LABELS[state.step + 1] : undefined;
+            console.log();
+            console.log(chalk.bold.yellow('━━━ GETTING BACK ON TRACK ━━━'));
+            console.log();
+            console.log(chalk.yellow('You went off-track by not creating a task. Create the task below to continue.'));
+            console.log();
+            // Print the TASK directive for the current step
+            let taskTitle;
+            if (state.step < totalSteps) {
+                taskTitle = `Complete codeyam editor step ${state.step}: '${currentLabel}' and move on to step ${state.step + 1}: '${nextLabel}'`;
+            }
+            else {
+                taskTitle =
+                    'Ask user what to build next and restart codeyam editor workflow';
+            }
+            console.log(chalk.bold.cyan('━━━ TASK ━━━'));
+            console.log(chalk.cyan('Before creating the task below, delete ALL existing tasks:'));
+            console.log(chalk.cyan('  1. Run TaskList to find all tasks'));
+            console.log(chalk.cyan('  2. Run TaskUpdate with status "deleted" for EACH task returned'));
+            console.log(chalk.cyan('Then create a new task with this EXACT title (copy verbatim):'));
+            console.log();
+            console.log(chalk.bold.cyan(`EXACT_TASK_TITLE: ${taskTitle}`));
+            console.log();
+            console.log(chalk.green(`After creating the task, re-run: codeyam editor ${state.step + 1}`));
+            console.log();
+            // Mark task as expected-created so the next step can proceed.
+            // The hook will set taskCreated=true when it sees the actual TaskCreate call.
+            // But we also allow advancement now since task-ontrack itself is the corrective action.
+            const trackingPath = path.join(root, '.codeyam', 'editor-task-tracking.json');
+            fs.writeFileSync(trackingPath, JSON.stringify({ step: state.step, taskCreated: true }, null, 2), 'utf8');
+            return;
+        }
+        // Subcommand: codeyam editor analyze-imports [file1.tsx file2.tsx ...]
         if (argv.step === 'analyze-imports') {
-            await handleAnalyzeImports();
+            const { parseAnalyzeImportsArgs } = await import('./editorAnalyzeImportsArgs.js');
+            const requestedPaths = parseAnalyzeImportsArgs(argv.json, argv._);
+            await handleAnalyzeImports(requestedPaths.length > 0 ? { filePaths: requestedPaths } : {});
+            return;
+        }
+        // Subcommand: codeyam editor manual-entity <JSON|@file>
+        if (argv.step === 'manual-entity') {
+            await handleManualEntity(argv.json || '');
             return;
         }
         // Subcommand: codeyam editor dependents <EntityName>
@@ -3946,9 +5365,9 @@ const editorCommand = {
             await handleDependents(argv.json || '');
             return;
         }
-        // Subcommand: codeyam editor audit
+        // Subcommand: codeyam editor audit [--fix]
         if (argv.step === 'audit') {
-            await handleAudit();
+            await handleAudit({ fix: argv.fix || false });
             return;
         }
         // Subcommand: codeyam editor scenarios
@@ -3961,6 +5380,11 @@ const editorCommand = {
             await handleScenarioCoverage();
             return;
         }
+        // Subcommand: codeyam editor recapture-stale
+        if (argv.step === 'recapture-stale') {
+            await handleRecaptureStale();
+            return;
+        }
         // Subcommand: codeyam editor change <feature>
         if (argv.step === 'change') {
             handleChange(argv.json || '');
@@ -3976,6 +5400,11 @@ const editorCommand = {
             await handleValidateSeed(argv.json || '');
             return;
         }
+        // Subcommand: codeyam editor design-system <id>
+        if (argv.step === 'design-system') {
+            handleDesignSystem(argv.json || '');
+            return;
+        }
         // Subcommand: codeyam editor delete <scenarioId>
         if (argv.step === 'delete') {
             await handleDelete(argv.json || '');
@@ -4020,18 +5449,13 @@ const editorCommand = {
             }
             else {
                 const state = readState(root);
-                // Clear prompt file when feature is done (step 16) so the hook
-                // can capture the next feature request from the user.
-                if (state?.step === 16) {
-                    clearEditorUserPrompt(root);
-                }
                 printCycleOverview(root, state);
             }
             return;
         }
         const step = argv.step ? parseInt(argv.step, 10) : undefined;
-        if (step != null && (isNaN(step) || step < 1 || step > 16)) {
-            console.error(chalk.red(`Error: Invalid step "${argv.step}". Must be 1-16.`));
+        if (step != null && (isNaN(step) || step < 1 || step > 18)) {
+            console.error(chalk.red(`Error: Invalid step "${argv.step}". Must be 1-18.`));
             process.exit(1);
         }
         if (step == null) {
@@ -4055,7 +5479,7 @@ const editorCommand = {
                 const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
                 const { projectSlug } = config;
                 if (!projectSlug) {
-                    errorLog('Missing project slug. Try reinitializing with: codeyam init --force');
+                    errorLog('Missing project slug. Try reinitializing with: `codeyam editor template`');
                     return;
                 }
                 const connectionOk = await withoutSpinner(() => testEnvironment());
@@ -4181,13 +5605,24 @@ const editorCommand = {
                     try {
                         const { getDatabase: getDb } = await import('../../../packages/database/index.js');
                         const seedDb = getDb();
-                        const appScenario = await seedDb
+                        // Prefer the home page scenario (url "/") since the App tab
+                        // sorts "Home" first — fall back to any application scenario.
+                        const homeScenario = await seedDb
                             .selectFrom('editor_scenarios')
                             .select(['id', 'name', 'type'])
                             .where('project_id', '=', project.id)
-                            .where('type', '=', 'application')
+                            .where('url', '=', '/')
+                            .where('component_name', 'is', null)
                             .orderBy('created_at', 'asc')
                             .executeTakeFirst();
+                        const appScenario = homeScenario ||
+                            (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)) {
@@ -4330,7 +5765,7 @@ const editorCommand = {
                         if (!needsAnalysis) {
                             try {
                                 const { getDatabase } = await import('../../../packages/database/index.js');
-                                const { countScenariosNeedingEntityBackfill } = await import('../utils/editorScenarios');
+                                const { countScenariosNeedingEntityBackfill } = await import('../utils/editorScenarios.js');
                                 const db = getDatabase();
                                 const backfillCount = await countScenariosNeedingEntityBackfill(db);
                                 if (backfillCount > 0) {
@@ -4369,7 +5804,7 @@ const editorCommand = {
                         .execute();
                     if (unresolved.length > 0) {
                         const { scanPageFilePaths: scanPfp } = await import('../utils/entityChangeStatus.server.js');
-                        const { matchUrlToPageFile } = await import('../utils/routePatternMatching');
+                        const { matchUrlToPageFile } = await import('../utils/routePatternMatching.js');
                         const { allFiles: pfpFiles } = scanPfp(projectRoot);
                         let pfpResolved = 0;
                         for (const row of unresolved) {
@@ -4452,7 +5887,7 @@ const editorCommand = {
         // Step 1 is planning-only and may not persist state (no --feature flag).
         const skipValidation = step === 2 && argv.feature;
         if (!skipValidation) {
-            const stepError = validateStepTransition(step, state?.step ?? null);
+            const stepError = validateStepTransition(step, state?.step ?? null, state?.startedAt, root);
             if (stepError) {
                 console.error(chalk.red(`Error: ${stepError}`));
                 process.exit(1);
@@ -4492,19 +5927,20 @@ const editorCommand = {
             case 13:
             case 14:
             case 15:
-            case 16: {
+            case 16:
+            case 17:
+            case 18: {
                 const feature = argv.feature || state?.feature;
                 if (!feature) {
                     console.error(chalk.red('Error: No feature in progress. Run codeyam editor 1 first.'));
                     process.exit(1);
                 }
-                // Hard gate: steps 8+ require audit to have passed
-                if (step >= 8) {
+                // Hard gate: steps 10+ require audit to have passed
+                if (step >= 10) {
                     const auditOk = await checkAuditGate();
                     if (!auditOk) {
                         // checkAuditGate() already printed specific failure details above
                         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);
                     }
                 }
@@ -4523,6 +5959,8 @@ const editorCommand = {
                     14: printStep14,
                     15: printStep15,
                     16: printStep16,
+                    17: printStep17,
+                    18: printStep18,
                 };
                 stepFns[step](root, feature);
                 break;