@codeyam/codeyam-cli 0.1.0-staging.a890816 → 0.1.0-staging.ad88eeb

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

@@ -1,11 +1,25 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 import { fileURLToPath } from 'url';
 import chalk from 'chalk';
 import { runAnalysisForEntities } from "../utils/analysisRunner.js";
-import { ProgressReporter } from "../utils/progress.js";
-import { initializeEnvironment } from "../utils/database.js";
-import { loadEntities, loadAnalyses } from "../../../packages/database/index.js";
+import { error as errorLog, ProgressReporter, withoutSpinner, } from "../utils/progress.js";
+import { initializeEnvironment, requireBranchAndProject, testEnvironment, } from "../utils/database.js";
+import { loadAnalyses, loadEntities, updateProjectMetadata, } from "../../../packages/database/index.js";
+import { IS_INTERNAL_BUILD } from "../utils/buildFlags.js";
+import { startBackgroundServer } from "../utils/backgroundServer.js";
+import { installClaudeCodeSkills } from "../utils/install-skills.js";
+import { setupClaudeCodeSettings } from "../utils/setupClaudeCodeSettings.js";
+import { getAnalyzerTemplatePath, isAnalyzerFinalized, } from "../utils/analyzer.js";
+import { APP_FORMATS, TECH_STACKS } from "../data/techStacks.js";
+import { getProjectRoot as getStateProjectRoot } from "../state.js";
+import initCommand from "./init.js";
+import { readManifest, syncManifestToDatabase, } from "../utils/scenariosManifest.js";
+import { clearEditorState, clearEditorUserPrompt, } from "../utils/editorScenarios.js";
+import { validateSeedData, detectSeedAdapter, } from "../utils/editorSeedAdapter.js";
+import { buildEditorApiRequest, callEditorApi, EDITOR_API_SUBCOMMANDS, } from "../utils/editorApi.js";
+import { parseRegisterArg } from "../utils/parseRegisterArg.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const STEP_LABELS = {
@@ -19,7 +33,9 @@ const STEP_LABELS = {
     8: 'App Scenarios',
     9: 'User Scenarios',
     10: 'Verify',
-    11: 'Review',
+    11: 'Journal',
+    12: 'Review',
+    13: 'Present',
 };
 /**
  * Append a JSONL log entry to .codeyam/logs/editor-log.jsonl
@@ -76,15 +92,11 @@ function writeState(root, state) {
 }
 /**
  * Clear the editor state (for starting a new feature).
+ * Does NOT clear the user prompt file — that's handled separately
+ * via clearEditorUserPrompt when the previous feature commits.
  */
 function clearState(root) {
-    const statePath = getStatePath(root);
-    try {
-        fs.unlinkSync(statePath);
-    }
-    catch {
-        // File doesn't exist, that's fine
-    }
+    clearEditorState(root);
 }
 /**
  * Check if a project has been scaffolded (package.json exists).
@@ -119,13 +131,13 @@ function stepHeader(step, title, feature) {
     console.log();
 }
 /**
- * Print a colored progress tracker showing all 11 steps.
+ * Print a colored progress tracker showing all 13 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 <= 11; i++) {
+    for (let i = 1; i <= 13; i++) {
         const label = STEP_LABELS[i];
         const num = i < 10 ? ` ${i}` : `${i}`;
         const content = `${num}. ${label.padEnd(28)}`;
@@ -163,7 +175,7 @@ function stopGate(current, opts) {
     console.log(chalk.yellow('For the CURRENT step (→), show each checklist item with ✓ (done) or ✗ (skipped + reason).'));
     console.log(chalk.yellow('If any items are ✗, explain why and ask if the user wants to address them.'));
     console.log();
-    if (current < 10) {
+    if (current < 13) {
         console.log(chalk.green('When done, run: ') +
             chalk.bold(`codeyam editor ${current + 1}`));
     }
@@ -174,6 +186,218 @@ function stopGate(current, opts) {
     }
     console.log();
 }
+/**
+ * Print a RESUMING header with step-specific investigation instructions.
+ * Called when a step is re-entered (prevState.step === current step).
+ */
+function printResumptionHeader(step) {
+    const port = getServerPort();
+    const checks = {
+        1: [
+            '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: [
+            'Check if extraction plan already exists in context file:\n      `cat .codeyam/editor-mode-context.md`',
+        ],
+        5: [
+            'Check if components/functions already extracted:\n      `ls src/components/ src/lib/`',
+        ],
+        6: [
+            '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: [
+            'Check existing user-persona scenarios:\n      `codeyam editor scenarios`',
+        ],
+        10: ['Re-verify is safe to repeat — just re-run the checks'],
+        11: [
+            '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`'],
+    };
+    const label = STEP_LABELS[step] || 'Unknown';
+    console.log(chalk.bold.yellow(`━━━ RESUMING Step ${step}: ${label} ━━━`));
+    console.log(chalk.yellow('This step was already started. Before repeating any actions, investigate:'));
+    const items = checks[step] || [];
+    for (const item of items) {
+        checkbox(item);
+    }
+    console.log();
+}
+function captureOutput(fn) {
+    const stdoutWrite = process.stdout.write.bind(process.stdout);
+    const stderrWrite = process.stderr.write.bind(process.stderr);
+    const chunks = [];
+    const captureWrite = (chunk, encoding, cb) => {
+        const text = typeof chunk === 'string'
+            ? chunk
+            : chunk instanceof Buffer
+                ? chunk.toString(typeof encoding === 'string' ? encoding : undefined)
+                : String(chunk);
+        chunks.push(text);
+        if (typeof encoding === 'function') {
+            encoding();
+        }
+        if (typeof cb === 'function') {
+            cb();
+        }
+        return true;
+    };
+    process.stdout.write = captureWrite;
+    process.stderr.write = captureWrite;
+    try {
+        fn();
+    }
+    finally {
+        process.stdout.write = stdoutWrite;
+        process.stderr.write = stderrWrite;
+    }
+    return chunks.join('');
+}
+function withTempRoot(hasProject, fn) {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'codeyam-editor-debug-'));
+    if (hasProject) {
+        fs.writeFileSync(path.join(root, 'package.json'), '{"name":"codeyam-editor-debug","private":true}', 'utf8');
+    }
+    try {
+        return fn(root);
+    }
+    finally {
+        try {
+            fs.rmSync(root, { recursive: true, force: true });
+        }
+        catch {
+            // Best-effort cleanup
+        }
+    }
+}
+function makeState(step, feature) {
+    const now = new Date().toISOString();
+    return {
+        feature,
+        step,
+        label: STEP_LABELS[step],
+        startedAt: now,
+        featureStartedAt: now,
+    };
+}
+function normalizeDebugTarget(raw) {
+    const value = raw.trim().toLowerCase();
+    if (!value)
+        return '';
+    if (value === 'setup')
+        return 'setup';
+    if (value === 'overview')
+        return 'overview';
+    if (value === 'overview-with-state' || value === 'overview-state') {
+        return 'overview-with-state';
+    }
+    if (/^\d+$/.test(value)) {
+        return `step-${value}`;
+    }
+    if (/^step-?\d+$/.test(value)) {
+        const num = value.replace('step', '').replace('-', '');
+        return `step-${num}`;
+    }
+    return value;
+}
+function parseDebugTargets(target) {
+    if (!target || target.trim().toLowerCase() === 'all')
+        return null;
+    const rawTargets = target
+        .split(',')
+        .map((t) => normalizeDebugTarget(t))
+        .filter(Boolean);
+    const valid = new Set();
+    for (const entry of rawTargets) {
+        if (entry === 'setup' ||
+            entry === 'overview' ||
+            entry === 'overview-with-state') {
+            valid.add(entry);
+            continue;
+        }
+        if (entry.startsWith('step-')) {
+            const num = parseInt(entry.replace('step-', ''), 10);
+            if (!isNaN(num) && num >= 1 && num <= 13) {
+                valid.add(`step-${num}`);
+                continue;
+            }
+        }
+        throw new Error(`Invalid debug target: "${entry}"`);
+    }
+    return valid;
+}
+function writeContextSnapshot(root, outDir) {
+    const contextDir = path.join(outDir, 'context');
+    fs.mkdirSync(contextDir, { recursive: true });
+    const entries = [];
+    const skillPath = path.join(root, '.claude', 'skills', 'codeyam-editor', 'SKILL.md');
+    const skillFallback = path.join(__dirname, '..', '..', 'templates', 'codeyam-editor.md');
+    const skillSource = fs.existsSync(skillPath) ? skillPath : skillFallback;
+    const skillDest = path.join(contextDir, 'codeyam-editor-skill.md');
+    fs.copyFileSync(skillSource, skillDest);
+    entries.push({
+        label: 'codeyam-editor skill',
+        source: skillSource,
+        file: path.relative(outDir, skillDest),
+        status: fs.existsSync(skillPath) ? 'installed' : 'template',
+    });
+    const claudePath = path.join(root, 'CLAUDE.md');
+    if (fs.existsSync(claudePath)) {
+        const dest = path.join(contextDir, 'CLAUDE.md');
+        fs.copyFileSync(claudePath, dest);
+        entries.push({
+            label: 'CLAUDE.md',
+            source: claudePath,
+            file: path.relative(outDir, dest),
+            status: 'project',
+        });
+    }
+    else {
+        const fallback = path.join(__dirname, '..', '..', 'templates', 'codeyam-editor-claude.md');
+        if (fs.existsSync(fallback)) {
+            const dest = path.join(contextDir, 'CLAUDE.md');
+            fs.copyFileSync(fallback, dest);
+            entries.push({
+                label: 'CLAUDE.md',
+                source: fallback,
+                file: path.relative(outDir, dest),
+                status: 'template',
+            });
+        }
+        else {
+            entries.push({
+                label: 'CLAUDE.md',
+                file: path.relative(outDir, path.join(contextDir, 'CLAUDE.md')),
+                status: 'missing',
+            });
+        }
+    }
+    const contextPath = path.join(root, '.codeyam', 'editor-mode-context.md');
+    if (fs.existsSync(contextPath)) {
+        const dest = path.join(contextDir, 'editor-mode-context.md');
+        fs.copyFileSync(contextPath, dest);
+        entries.push({
+            label: 'editor-mode-context.md',
+            source: contextPath,
+            file: path.relative(outDir, dest),
+            status: 'project',
+        });
+    }
+    else {
+        entries.push({
+            label: 'editor-mode-context.md',
+            file: path.relative(outDir, path.join(contextDir, 'editor-mode-context.md')),
+            status: 'missing',
+        });
+    }
+    return entries;
+}
 // ─── Setup (no args, no project) ──────────────────────────────────────
 function printSetup(root) {
     const port = getServerPort();
@@ -187,12 +411,68 @@ function printSetup(root) {
     checkbox('Read `.codeyam/editor-mode-context.md` for session state');
     checkbox('Ask the user what they want to build');
     console.log();
+    // ── App Format Selection ───────────────────────────────────────────
+    console.log(chalk.bold('App Format Selection:'));
+    console.log(chalk.dim('  After the user describes their project, ask which app formats they want to target.'));
+    console.log(chalk.dim('  Use AskUserQuestion with CHECKBOXES (multiple selections allowed):'));
+    console.log();
+    for (const format of APP_FORMATS) {
+        console.log(chalk.yellow(`    [ ] ${format.label}`) +
+            chalk.dim(` — ${format.description}`));
+    }
+    console.log();
+    // ── Tech Stack Selection ───────────────────────────────────────────
+    console.log(chalk.bold('Tech Stack Selection:'));
+    console.log(chalk.dim('  Based on the selected formats, present ONLY the matching tech stacks.'));
+    console.log(chalk.dim('  A stack matches if ANY of the user\'s selected formats appears in its "Supports" list.'));
+    console.log(chalk.dim('  Show ALL matching stacks even if there is only one. Mark the recommended option.'));
+    console.log(chalk.dim('  Use AskUserQuestion to let the user pick one.'));
+    console.log();
+    console.log(chalk.bold('  Available Tech Stacks:'));
+    for (const stack of TECH_STACKS) {
+        const recommended = stack.recommended ? chalk.green(' (Recommended)') : '';
+        const formatLabels = stack.supportedFormats
+            .map((f) => APP_FORMATS.find((af) => af.id === f)?.label)
+            .join(', ');
+        console.log(chalk.bold.yellow(`    ${stack.name}`) +
+            recommended +
+            chalk.dim(` [id: ${stack.id}]`));
+        console.log(chalk.dim(`      ${stack.description}`));
+        console.log(chalk.dim('      Technologies:'));
+        for (const tech of stack.technologies) {
+            console.log(chalk.dim(`        - ${tech}`));
+        }
+        console.log(chalk.dim(`      Supports: ${formatLabels}`));
+        console.log();
+    }
+    console.log(chalk.dim('  If NO stacks match the selected formats, tell the user that support for that format is coming soon'));
+    console.log(chalk.dim('  and suggest they pick a supported format for now.'));
+    console.log();
+    // ── Default Screen Size Selection ──────────────────────────────────
+    console.log(chalk.bold('Default Screen Size:'));
+    console.log(chalk.dim('  After selecting a tech stack, ask the user to choose the default screen size for previews and captures.'));
+    console.log(chalk.dim('  Use AskUserQuestion with RADIO buttons (single selection):'));
+    console.log();
+    console.log(chalk.yellow('    ( ) Desktop') + chalk.dim(' — 1440 × 900'));
+    console.log(chalk.yellow('    ( ) Laptop') + chalk.dim(' — 1024 × 768'));
+    console.log(chalk.yellow('    ( ) Tablet') + chalk.dim(' — 768 × 1024'));
+    console.log(chalk.yellow('    ( ) Mobile') + chalk.dim(' — 375 × 667'));
+    console.log(chalk.yellow('    ( ) Custom') + chalk.dim(' — ask for width × height'));
+    console.log();
+    console.log(chalk.dim('  Pre-select based on app format: mobile-app/mobile-responsive-web-app → Mobile, chrome-extension → Custom (400×600), web-app/desktop-app → Desktop.'));
+    console.log(chalk.dim('  If only one obvious choice, confirm it rather than asking.'));
+    console.log(chalk.dim('  Save the choice via: curl -s -X POST http://localhost:PORT/api/editor-project-info -H "Content-Type: application/json" -d \'{"defaultScreenSize":{"name":"Desktop","width":1440,"height":900}}\''));
+    console.log();
     console.log(chalk.bold.red('━━━ STOP ━━━'));
     console.log();
-    console.log(chalk.red('Ask the user what they want to build, then run:'));
+    console.log(chalk.red('Ask the user what they want to build, then ask about app formats, then present tech stacks, then choose a default screen size. Then run:'));
     console.log();
-    console.log(chalk.green('  ') + chalk.bold('codeyam editor 1 --feature "Feature Name"'));
+    console.log(chalk.green('  ') +
+        chalk.bold('codeyam editor 1 --feature "Feature Name" --app-formats "FORMAT_IDS" --tech-stack "STACK_ID" --prompt "the user\'s original message"'));
     console.log(chalk.dim('  Replace "Feature Name" with a short title for what the user described.'));
+    console.log(chalk.dim('  Replace FORMAT_IDS with the comma-separated format IDs the user selected (e.g., "chrome-extension" or "web-app,mobile-responsive-web-app").'));
+    console.log(chalk.dim('  Replace STACK_ID with the tech stack id shown in [brackets] above (e.g., "nextjs-prisma-sqlite" or "chrome-extension-react").'));
+    console.log(chalk.dim("  Pass --prompt with the user's exact original request so it appears in the journal."));
     console.log(chalk.dim('  Step 1 will guide you through planning and getting user confirmation before any code is written.'));
     console.log();
 }
@@ -210,9 +490,13 @@ function printCycleOverview(root, state) {
         console.log(chalk.dim('Or run ') +
             chalk.bold('codeyam editor 1') +
             chalk.dim(' to start a new feature'));
+        console.log();
+        console.log(chalk.yellow('If the user reports a bug or requests any change, run: ') +
+            chalk.bold('codeyam editor change'));
+        console.log(chalk.yellow('This applies even after committing — always use the change workflow.'));
     }
     else {
-        console.log('Each feature follows 11 steps. You MUST run each command in order:');
+        console.log('Each feature follows 13 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`);
@@ -224,15 +508,23 @@ function printCycleOverview(root, state) {
         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('Review')}          — Present summary, get approval`);
+        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();
         console.log(chalk.green('Start now: ') + chalk.bold('codeyam editor 1'));
+        console.log(chalk.dim('  If the user already described what they want, pass it: codeyam editor 1 --prompt "their message"'));
     }
     console.log();
 }
 // ─── Step 1: Plan ─────────────────────────────────────────────────────
-function printStep1(root, feature) {
-    clearState(root);
+function printStep1(root, feature, options, userPrompt) {
+    const port = getServerPort();
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 1;
+    if (!isResuming) {
+        clearState(root);
+    }
     // If feature is provided, save initial state so step 2 can pick it up
     if (feature) {
         const now = new Date().toISOString();
@@ -240,12 +532,23 @@ function printStep1(root, feature) {
             feature,
             step: 1,
             label: STEP_LABELS[1],
-            startedAt: now,
-            featureStartedAt: now,
+            startedAt: isResuming ? prevState.startedAt : now,
+            featureStartedAt: isResuming ? prevState.featureStartedAt : now,
+            appFormats: options?.appFormats || prevState?.appFormats,
+            techStackId: options?.techStackId || prevState?.techStackId,
         });
     }
+    // Save the user's original prompt to a separate file
+    if (userPrompt) {
+        const promptPath = path.join(root, '.codeyam', 'editor-user-prompt.txt');
+        fs.mkdirSync(path.dirname(promptPath), { recursive: true });
+        fs.writeFileSync(promptPath, userPrompt, 'utf8');
+    }
     logEvent(root, 'step', { step: 1, label: 'Plan', feature });
     stepHeader(1, 'Plan', feature);
+    if (isResuming) {
+        printResumptionHeader(1);
+    }
     console.log('Plan the feature before writing ANY code.');
     console.log();
     console.log(chalk.bold('Checklist:'));
@@ -254,15 +557,19 @@ function printStep1(root, feature) {
     checkbox('Ask clarifying questions using `AskUserQuestion` with selectable options');
     console.log(chalk.dim('    Use AskUserQuestion for EVERY clarifying question — give 2-4 concrete options the user can pick from.'));
     console.log(chalk.dim('    Focus on what the USER will see and do, not on databases, APIs, or components.'));
+    console.log(chalk.dim('    Do NOT ask about tech stack, frameworks, libraries, or implementation details — only ask about user-facing choices.'));
     console.log(chalk.dim('    Good: "What should happen when there are no results?" → options: "Show empty state message", "Show suggestions"'));
     console.log(chalk.dim('    Bad:  Free-form text asking "What do you think about the data model?"'));
     console.log(chalk.dim('    You can ask up to 4 questions at once. Bundle related questions into a single AskUserQuestion call.'));
     checkbox("Summarize what you'll build in plain language the user can verify against their vision");
-    console.log();
-    console.log(chalk.bold('Present a selection menu to the user (use AskUserQuestion):'));
-    console.log(chalk.green('    "Looks good, start building!"') +
-        chalk.dim(' — proceed to step 2'));
-    console.log(chalk.yellow('    "I\'d like some changes"') +
+    checkbox('Set the project title and description for the App tab:');
+    console.log(chalk.dim(`  curl -s -X POST http://localhost:${port}/api/editor-project-info \\`));
+    console.log(chalk.dim('    -H "Content-Type: application/json" \\'));
+    console.log(chalk.dim('    -d \'{"projectTitle":"My App","projectDescription":"A short description of what this app does"}\''));
+    console.log();
+    console.log(chalk.bold('Present a selection menu to the user (use AskUserQuestion with these EXACT option labels):'));
+    console.log(chalk.green('    Option 1 label: "This plan is accurate, let\'s prototype it!"') + chalk.dim(' — proceed to step 2'));
+    console.log(chalk.yellow('    Option 2 label: "I\'d like some changes"') +
         chalk.dim(' — user describes changes, you revise the plan, then re-present'));
     console.log();
     console.log(chalk.dim('This step is for understanding user goals and getting buy-in. Code comes in Step 2.'));
@@ -288,82 +595,68 @@ function printStep1(root, feature) {
 function printStep2(root, feature) {
     const port = getServerPort();
     const projectExists = hasProject(root);
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 2;
     const now = new Date().toISOString();
     writeState(root, {
         feature,
         step: 2,
         label: STEP_LABELS[2],
-        startedAt: now,
-        featureStartedAt: now,
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: isResuming ? prevState.featureStartedAt : now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
     logEvent(root, 'step', { step: 2, label: 'Prototype', feature });
     stepHeader(2, 'Prototype', feature);
+    if (isResuming) {
+        printResumptionHeader(2);
+    }
     console.log('Build fast with real data. Prioritize speed over quality.');
     console.log();
     // If no project exists yet, include scaffolding instructions first
     if (!projectExists) {
-        const templateDir = path.join(__dirname, '..', '..', 'templates', 'nextjs-prisma-sqlite');
-        const hasTemplate = fs.existsSync(templateDir);
         console.log(chalk.bold('Scaffold the project:'));
-        if (hasTemplate) {
-            checkbox('Copy the project template and install dependencies');
-            console.log();
-            console.log(chalk.dim('  Copy template (Next.js + Prisma 7 + SQLite, pre-configured):'));
-            console.log(chalk.dim(`  cp -r ${templateDir}/* .`));
-            console.log(chalk.dim(`  cp ${templateDir}/.env .`));
-            console.log(chalk.dim(`  cp ${templateDir}/gitignore .gitignore`));
-            console.log(chalk.dim('  npm install'));
-            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();
-            console.log(chalk.dim('  See PRISMA_SETUP.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).'));
-        }
-        else {
-            checkbox('Scaffold the project (Next.js recommended) using temp-dir-rsync pattern');
-            console.log();
-            console.log(chalk.dim('  Scaffolding pattern (avoids .claude/ conflicts):'));
-            console.log(chalk.dim('  SCAFFOLD_DIR="/tmp/codeyam-scaffold-$$" && mkdir -p "$SCAFFOLD_DIR"'));
-            console.log(chalk.dim('  npx create-next-app@latest "$SCAFFOLD_DIR" --typescript --tailwind --eslint \\'));
-            console.log(chalk.dim('    --app --no-src-dir --no-import-alias --no-react-compiler --turbopack'));
-            console.log(chalk.dim('  rsync -a --exclude=\'.git\' "$SCAFFOLD_DIR/" . && rm -rf "$SCAFFOLD_DIR"'));
-            console.log();
-            checkbox('Set up Prisma + SQLite database');
-            console.log(chalk.dim('  npm install prisma @prisma/client @prisma/adapter-better-sqlite3 better-sqlite3'));
-            console.log(chalk.dim('  npm install -D @types/better-sqlite3'));
-            console.log(chalk.dim('  npx prisma init --datasource-provider sqlite'));
-            console.log(chalk.dim('  # Define schema, then: npx prisma db push'));
-        }
+        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,'));
+        console.log(chalk.dim('  initializes git, runs codeyam init, and refreshes the editor — all in one command.'));
         console.log();
-        checkbox('Initialize git so analysis and commits work');
-        console.log(chalk.dim('  git init && git add -A && git commit -m "Initial commit"'));
+        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('Run `codeyam init --force --keep-server` to detect the project and configure it');
-        console.log(chalk.dim('  This auto-detects webapps and configures the start command for analysis'));
+        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();
-        checkbox('Verify `.codeyam/config.json` has `startCommand` in the webapp entry');
-        console.log(chalk.dim('  Should look like: "startCommand": { "command": "sh", "args": ["-c", "npm run dev -- --port $PORT"] }'));
-        console.log(chalk.dim('  If missing, add it manually. $PORT is replaced at runtime by the analyzer.'));
-        console.log();
-        checkbox(`Notify CodeYam: \`curl -s -X POST http://localhost:${port}/api/editor-refresh\``);
+        console.log(chalk.dim('  See PRISMA_SETUP.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:'));
     }
     console.log(chalk.bold('Checklist:'));
-    checkbox('Create/update API routes (real database reads via Prisma)');
+    checkbox('Create API routes that read from the database via Prisma');
     checkbox('Seed the database with demo data');
-    checkbox('Build the page/feature UI components');
+    checkbox('Create `.codeyam/seed-adapter.ts` so CodeYam can seed the database for scenarios');
+    console.log(chalk.dim('    The seed adapter reads a JSON file (path passed as CLI arg), wipes tables, inserts rows.'));
+    console.log(chalk.dim("    Use the project's own ORM (Prisma, Drizzle, etc.). See template for example."));
+    console.log(chalk.dim('    Run with: npx tsx .codeyam/seed-adapter.ts <path-to-seed-data.json>'));
     checkbox('Verify the dev server shows the changes');
+    checkbox('If the feature involves auth, email, payments, or other common patterns: read FEATURE_PATTERNS.md');
+    console.log();
+    console.log(chalk.bold.cyan('Keep the preview moving:'));
+    console.log(chalk.cyan('  The user is watching the preview. Refresh it after each meaningful change:'));
+    console.log(chalk.cyan(`  codeyam editor preview`));
+    console.log(chalk.cyan('  Refresh after: first visible page, adding each UI section, seeding data, styling.'));
+    console.log(chalk.cyan('  Aim for 4-8+ refreshes during prototyping — not one big reveal at the end.'));
+    console.log(chalk.cyan('  If you build a NEW page (e.g., /drinks/[id]), navigate the preview there:'));
+    console.log(chalk.cyan(`  codeyam editor preview '{"path":"/drinks/1"}'`));
     console.log();
     console.log(chalk.bold('Verify the dev server:'));
-    console.log(chalk.dim(`  # Get dev server URL: curl -s http://localhost:${port}/api/editor-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();
@@ -371,7 +664,10 @@ function printStep2(root, feature) {
     console.log(chalk.yellow('  Verify everything works before presenting the prototype to the user.'));
     checkbox('Verify the page loads: curl the dev server URL and confirm HTTP 200 (not an error page)');
     checkbox('Verify API routes return valid JSON: curl each route and confirm no error responses');
-    checkbox('Check for broken images: look at any <img> src attributes and verify the assets exist');
+    checkbox('Check for broken images: `codeyam editor verify-images \'{"paths":["/"], "imageUrls":["url1","url2"]}\'`');
+    console.log(chalk.dim('    Pass ALL page paths and ALL image URLs you used in seed data / API responses.'));
+    console.log(chalk.dim('    Client-rendered pages need imageUrls — the HTML shell has no images to scan.'));
+    console.log(chalk.dim('    Fix or replace any broken image URLs in the seed data before proceeding.'));
     checkbox('Check the dev server terminal output for runtime errors (missing modules, failed imports)');
     console.log(chalk.dim('    If any check fails, fix the issue and re-verify before proceeding.'));
     console.log();
@@ -382,32 +678,48 @@ function printStep2(root, feature) {
 function printStep3(root, feature) {
     const port = getServerPort();
     const prevState = readState(root);
+    const isResuming = prevState?.step === 3;
+    const now = new Date().toISOString();
     writeState(root, {
         feature,
         step: 3,
         label: STEP_LABELS[3],
-        startedAt: new Date().toISOString(),
-        featureStartedAt: prevState?.featureStartedAt || new Date().toISOString(),
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
     });
     logEvent(root, 'step', { step: 3, label: 'Confirm', feature });
     stepHeader(3, 'Confirm', feature);
+    if (isResuming) {
+        printResumptionHeader(3);
+    }
     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: \`curl -s -X POST http://localhost:${port}/api/editor-refresh\``);
-    checkbox('Verify the page loads without errors (no error pages, no blank screens)');
-    checkbox('Verify all images and assets render correctly (no broken images)');
+    checkbox(`Refresh the preview: \`codeyam editor preview\` — check the \`preview\` field for \`healthy: false\``);
     checkbox('Verify API routes return valid data (curl each route)');
-    console.log(chalk.yellow('    Do not present to the user until all checks pass. Fix issues first.'));
+    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"]}\'`');
+    console.log(chalk.dim('    Include ALL page paths and ALL image URLs from seed data / API responses.'));
+    console.log(chalk.dim('    Client-rendered pages need imageUrls — the HTML shell has no images.'));
+    checkbox('Fix or remove any image that returns non-200 before continuing');
+    checkbox('Check for client-side errors: `codeyam editor client-errors`');
+    console.log(chalk.dim('    If there are errors, fix the underlying issue before presenting.'));
     console.log();
     console.log(chalk.bold('Then present to the user:'));
     checkbox('Summarize what was built (routes, components, data)');
-    checkbox('Show the user the current state of the prototype');
-    console.log();
-    console.log(chalk.bold('Present a selection menu to the user (use AskUserQuestion):'));
-    console.log(chalk.green('    "Yes, this looks right!"') +
-        chalk.dim(' — proceed to step 4'));
-    console.log(chalk.yellow('    "I\'d like some changes"') +
+    checkbox('Navigate the preview to the feature\'s primary page: `codeyam editor preview \'{"path":"/your-page"}\'`');
+    console.log(chalk.dim('    The user needs to SEE the new feature. If you built a new page, navigate there.'));
+    console.log(chalk.dim('    If you modified an existing page, refresh the preview to show the changes.'));
+    console.log();
+    console.log(chalk.bold.cyan('Guide the user through interactive testing:'));
+    checkbox('Tell the user: "The preview is fully interactive — click around to test!"');
+    checkbox('Prompt the user to try key interactions: forms, navigation, buttons, etc.');
+    checkbox('Ask the user: "Does everything work as expected?"');
+    console.log();
+    console.log(chalk.bold('Present a selection menu to the user (use AskUserQuestion with these EXACT option labels):'));
+    console.log(chalk.green('    Option 1 label: "The live preview is displaying what I expected"') + chalk.dim(' — proceed to step 4'));
+    console.log(chalk.yellow('    Option 2 label: "I\'d like some changes"') +
         chalk.dim(' — user describes changes, you make them, then re-present'));
     console.log();
     console.log(chalk.dim('Wait for user approval before moving on. Refactoring and scenarios happen in later steps.'));
@@ -416,15 +728,20 @@ function printStep3(root, feature) {
 // ─── Step 4: Deconstruct ──────────────────────────────────────────────
 function printStep4(root, feature) {
     const prevState = readState(root);
+    const isResuming = prevState?.step === 4;
+    const now = new Date().toISOString();
     writeState(root, {
         feature,
         step: 4,
         label: STEP_LABELS[4],
-        startedAt: new Date().toISOString(),
-        featureStartedAt: prevState?.featureStartedAt || new Date().toISOString(),
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
     });
     logEvent(root, 'step', { step: 4, label: 'Deconstruct', feature });
     stepHeader(4, 'Deconstruct', feature);
+    if (isResuming) {
+        printResumptionHeader(4);
+    }
     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();
@@ -460,16 +777,22 @@ function printStep4(root, feature) {
 }
 // ─── Step 5: Extract ──────────────────────────────────────────────────
 function printStep5(root, feature) {
+    const port = getServerPort();
     const prevState = readState(root);
+    const isResuming = prevState?.step === 5;
+    const now = new Date().toISOString();
     writeState(root, {
         feature,
         step: 5,
         label: STEP_LABELS[5],
-        startedAt: new Date().toISOString(),
-        featureStartedAt: prevState?.featureStartedAt || new Date().toISOString(),
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
     });
     logEvent(root, 'step', { step: 5, label: 'Extract', feature });
     stepHeader(5, 'Extract', feature);
+    if (isResuming) {
+        printResumptionHeader(5);
+    }
     console.log('Execute your extraction plan from step 4.');
     console.log();
     console.log(chalk.bold('Components:'));
@@ -495,6 +818,8 @@ function printStep5(root, feature) {
     checkbox('Run all tests and verify they pass');
     checkbox('Page files contain ONLY imports + component composition — no raw HTML tags');
     checkbox('Every component renders ONE thing or composes sub-components — no multi-section JSX');
+    checkbox(`Refresh the preview after each batch of extractions: \`codeyam editor preview\``);
+    console.log(chalk.dim('    The user should see the preview stay healthy as you refactor — refresh periodically, not just at the end.'));
     console.log(chalk.dim('Reuse glossary functions when they fit naturally. Extract a new function when the use case diverges.'));
     console.log();
     console.log(chalk.dim('Focus on TDD for functions and extraction for components. Scenarios come in later steps.'));
@@ -503,15 +828,20 @@ function printStep5(root, feature) {
 // ─── Step 6: Glossary ─────────────────────────────────────────────────
 function printStep6(root, feature) {
     const prevState = readState(root);
+    const isResuming = prevState?.step === 6;
+    const now = new Date().toISOString();
     writeState(root, {
         feature,
         step: 6,
         label: STEP_LABELS[6],
-        startedAt: new Date().toISOString(),
-        featureStartedAt: prevState?.featureStartedAt || new Date().toISOString(),
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
     });
     logEvent(root, 'step', { step: 6, label: 'Glossary', feature });
     stepHeader(6, 'Glossary', feature);
+    if (isResuming) {
+        printResumptionHeader(6);
+    }
     console.log('Record all new functions/components in `.codeyam/glossary.json`.');
     console.log();
     console.log(chalk.bold('Checklist:'));
@@ -535,20 +865,31 @@ function printStep6(root, feature) {
 function printStep7(root, feature) {
     const port = getServerPort();
     const prevState = readState(root);
+    const isResuming = prevState?.step === 7;
+    const now = new Date().toISOString();
     writeState(root, {
         feature,
         step: 7,
         label: STEP_LABELS[7],
-        startedAt: new Date().toISOString(),
-        featureStartedAt: prevState?.featureStartedAt || new Date().toISOString(),
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
     });
     logEvent(root, 'step', { step: 7, label: 'Analyze', feature });
     stepHeader(7, 'Analyze and Verify', feature);
+    if (isResuming) {
+        printResumptionHeader(7);
+    }
     console.log('Verify visual components (via isolation routes) and library functions (via tests).');
     console.log();
     console.log(chalk.bold('Visual Components — Component Isolation:'));
     checkbox('List all files with new/modified visual components from step 5');
-    checkbox('Ensure `.gitignore` includes `**/codeyam-isolate*` (add if missing)');
+    checkbox('Create isolation route dirs: `codeyam editor isolate ComponentA ComponentB ...`');
+    console.log(chalk.dim('    This creates app/isolated-components/layout.tsx (with production notFound() guard) and'));
+    console.log(chalk.dim('    a directory per component. List ALL components that need isolation routes.'));
+    checkbox('Check existing scenarios: `codeyam editor scenarios`');
+    console.log(chalk.dim('    Reuse and improve existing scenarios where possible — update mock data'));
+    console.log(chalk.dim('    to reflect current changes. Add new scenarios only for genuinely new states.'));
+    console.log(chalk.dim('    Ensure at least one scenario clearly demonstrates what changed in this session.'));
     checkbox('For each visual component:');
     console.log(chalk.dim('    1. Read the source AND find where it is used in the app to understand:'));
     console.log(chalk.dim('       — Props/interface'));
@@ -559,8 +900,8 @@ function printStep7(root, feature) {
     console.log(chalk.dim('       — Different visual states: loading, error, disabled, selected, hover'));
     console.log(chalk.dim('       — Boundary values: single item vs many, min/max ratings, very long names'));
     console.log(chalk.dim('    3. Create ONE isolation route per component with a scenarios map and ?s= query param:'));
-    console.log(chalk.dim('       Remix:   app/routes/codeyam-isolate.ComponentName.tsx → /codeyam-isolate/ComponentName'));
-    console.log(chalk.dim('       Next.js: app/codeyam-isolate/ComponentName/page.tsx → /codeyam-isolate/ComponentName'));
+    console.log(chalk.dim('       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":'));
@@ -573,15 +914,17 @@ function printStep7(root, feature) {
     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.dim('       Optional: add "viewportWidth" and "viewportHeight" to override the project default screen size'));
+    console.log(chalk.dim('       If omitted, captures use the project default from setup. Only override for scenarios that need a different size.'));
     console.log(chalk.dim('       url is a PATH (starts with /) — the proxy routes it and intercepts API calls'));
     console.log(chalk.dim('       mockData.routes provides data for API calls the component makes internally'));
     console.log(chalk.dim('       (omit mockData if the component has no internal API calls)'));
     console.log(chalk.yellow('    5. IMPORTANT: Check the register response for `clientErrors` array'));
     console.log(chalk.yellow('       If clientErrors is non-empty → fix the isolation route and re-register'));
     console.log(chalk.yellow('       Fix client errors and re-register before moving on'));
-    console.log(chalk.dim('    Isolation routes stay in the project (in .gitignore) so the editor preview can display them'));
+    console.log(chalk.dim('    Isolation routes are committed to git — the layout guard blocks them in production'));
     console.log();
     console.log(chalk.bold('Library Functions — run tests:'));
     checkbox('Run ALL test files created in step 5');
@@ -590,29 +933,65 @@ function printStep7(root, feature) {
     checkbox('If any test fails, fix the source code and re-run');
     console.log();
     console.log(chalk.dim('Do not proceed until both component isolations and library tests pass.'));
+    console.log();
+    checkbox('Run `codeyam editor audit` to verify all components have scenarios and all functions have tests');
+    console.log();
+    console.log(chalk.bold('Build import graph (for change tracking):'));
+    checkbox('Run `codeyam editor analyze-imports`');
+    console.log(chalk.dim('    This populates the import graph so the system can detect impacted entities when code changes.'));
+    console.log(chalk.dim('    It must run AFTER the audit passes so the glossary and entity data are complete.'));
     stopGate(7);
 }
 // ─── Step 8: App Scenarios ────────────────────────────────────────────
 function printStep8(root, feature) {
     const port = getServerPort();
     const prevState = readState(root);
+    const isResuming = prevState?.step === 8;
+    const now = new Date().toISOString();
     writeState(root, {
         feature,
         step: 8,
         label: STEP_LABELS[8],
-        startedAt: new Date().toISOString(),
-        featureStartedAt: prevState?.featureStartedAt || new Date().toISOString(),
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
     });
     logEvent(root, 'step', { step: 8, label: 'App Scenarios', feature });
     stepHeader(8, 'App Scenarios', feature);
+    if (isResuming) {
+        printResumptionHeader(8);
+    }
     console.log('Create app-level scenarios representing different data states.');
     console.log();
     console.log(chalk.bold('Checklist:'));
-    checkbox('Create scenarios for key data states (empty, loaded, error)');
-    console.log(chalk.dim('    Each scenario provides data across ALL API routes for that state'));
-    console.log(chalk.dim('    Name app scenarios with "App - " prefix: "App - Empty", "App - Full Catalog", "App - API Error"'));
-    checkbox('Register each scenario (auto-captures screenshot):');
-    console.log(chalk.dim(`    codeyam editor register '{"name":"App - Empty","description":"...","mockData":{"routes":{"/api/...":{"body":[...]}}}}'`));
+    checkbox('Check existing scenarios: `codeyam editor scenarios`');
+    console.log(chalk.dim('    Review existing scenarios — reuse and update their data rather than'));
+    console.log(chalk.dim('    creating duplicates. Re-register with the same name to update a scenario.'));
+    checkbox('Ensure scenarios clearly demonstrate what changed in this session');
+    console.log(chalk.dim('    If data models changed: update existing scenarios seed data to match'));
+    console.log(chalk.dim('    If UI changed: re-register existing scenarios so screenshots reflect the update'));
+    console.log(chalk.dim('    Add new scenarios only for genuinely new data states not covered by existing ones'));
+    checkbox('Cover key data states for EVERY page/route (at least 2-3 scenarios per page)');
+    console.log(chalk.yellow('    Each page needs its own scenarios — a detail page needs different data than the catalog'));
+    console.log(chalk.dim('    Catalog: "Full Catalog", "Empty Catalog", "Single Category"'));
+    console.log(chalk.dim('    Detail:  "Detail - With Reviews", "Detail - No Reviews", "Detail - High Rated"'));
+    console.log(chalk.dim('    Each scenario provides seed data to populate the database for that state'));
+    checkbox('If the project has a database + seed adapter, use seed-based scenarios:');
+    console.log(chalk.dim(`    codeyam editor register '{"name":"Full Catalog","type":"application","url":"/","seed":{"products":[...],"categories":[...]}}'`));
+    console.log(chalk.dim('    Seed data is written to the DB via the seed adapter. Real app renders real data.'));
+    checkbox('Optional: add "viewportWidth" and "viewportHeight" to override the project default screen size');
+    console.log(chalk.dim('    If omitted, captures use the project default from setup. Only override for scenarios that need a different size.'));
+    checkbox('IMPORTANT: Always include "url" — the page path to screenshot for this scenario');
+    console.log(chalk.dim('    Use "/" for home page, "/drinks/1" for detail pages, etc.'));
+    console.log(chalk.dim('    Without url, the screenshot captures the root page regardless of the scenario.'));
+    console.log(chalk.yellow('    Create separate scenarios for each page that shows different data.'));
+    checkbox('For large seed data, write JSON to a project temp file and use @ prefix:');
+    console.log(chalk.dim('    Write JSON to .codeyam/tmp/scenario.json then register with:'));
+    console.log(chalk.dim('    codeyam editor register @.codeyam/tmp/scenario.json'));
+    checkbox('For external API mocks (Stripe, weather, etc.), add externalApis:');
+    console.log(chalk.dim(`    "externalApis":{"GET https://api.stripe.com/v1/prices":{"body":[...],"status":200}}`));
+    checkbox('If the app uses auth, email, or other patterns: see FEATURE_PATTERNS.md for scenario guidance');
+    checkbox('If no database, use component-style mock scenarios (unchanged):');
+    console.log(chalk.dim(`    codeyam editor register '{"name":"Empty","description":"...","url":"/","mockData":{"routes":{"/api/...":{"body":[...]}}}}'`));
     checkbox('After each registration, check the response for `clientErrors`');
     console.log(chalk.yellow('    If clientErrors is non-empty → fix the issue and re-register the scenario'));
     console.log(chalk.yellow('    Fix client errors and re-register before moving on'));
@@ -624,21 +1003,34 @@ function printStep8(root, feature) {
 function printStep9(root, feature) {
     const port = getServerPort();
     const prevState = readState(root);
+    const isResuming = prevState?.step === 9;
+    const now = new Date().toISOString();
     writeState(root, {
         feature,
         step: 9,
         label: STEP_LABELS[9],
-        startedAt: new Date().toISOString(),
-        featureStartedAt: prevState?.featureStartedAt || new Date().toISOString(),
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
     });
     logEvent(root, 'step', { step: 9, label: 'User Scenarios', feature });
     stepHeader(9, 'User Scenarios', feature);
+    if (isResuming) {
+        printResumptionHeader(9);
+    }
     console.log('Create per-persona scenarios if the app has users. Skip to step 10 if no users.');
     console.log();
     console.log(chalk.bold('If the app has users:'));
-    checkbox('Create scenarios for each user persona (admin, regular user, new user)');
-    console.log(chalk.dim('    Each persona scenario provides data across ALL API routes for that user type'));
-    checkbox('Register each persona scenario (auto-captures screenshot):');
+    checkbox('Check existing scenarios: `codeyam editor scenarios`');
+    console.log(chalk.dim('    Reuse existing persona scenarios — update data to reflect current changes.'));
+    console.log(chalk.dim('    Re-register with the same name to update. Only add new personas if needed.'));
+    checkbox('Ensure scenarios for each user persona (admin, regular user, new user)');
+    console.log(chalk.dim('    Each persona scenario layers user-specific seed data on top of an app scenario'));
+    checkbox('If using seed-based scenarios, register with type "user" and baseScenario:');
+    console.log(chalk.dim(`    codeyam editor register '{"name":"Admin User","type":"user","url":"/","baseScenario":"<app-scenario-id>","seed":{"users":[{"id":1,"role":"admin"}]}}'`));
+    console.log(chalk.dim('    Always include "url" — the page to screenshot (e.g. "/", "/dashboard", "/drinks/1")'));
+    console.log(chalk.dim("    The base scenario's seed data is merged with this scenario's seed data (overlay wins)."));
+    checkbox('If the app uses auth or other patterns: see FEATURE_PATTERNS.md for per-persona scenario guidance');
+    checkbox('If using mock-based scenarios, register with mockData as before:');
     console.log(chalk.dim(`    codeyam editor register '{"name":"...","description":"...","mockData":{"routes":{"/api/...":{"body":[...]}}}}'`));
     checkbox('After each registration, check the response for `clientErrors`');
     console.log(chalk.yellow('    If clientErrors is non-empty → fix the issue and re-register the scenario'));
@@ -654,15 +1046,20 @@ function printStep9(root, feature) {
 function printStep10(root, feature) {
     const port = getServerPort();
     const prevState = readState(root);
+    const isResuming = prevState?.step === 10;
+    const now = new Date().toISOString();
     writeState(root, {
         feature,
         step: 10,
         label: STEP_LABELS[10],
-        startedAt: new Date().toISOString(),
-        featureStartedAt: prevState?.featureStartedAt || new Date().toISOString(),
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
     });
     logEvent(root, 'step', { step: 10, label: 'Verify', feature });
     stepHeader(10, 'Verify', feature);
+    if (isResuming) {
+        printResumptionHeader(10);
+    }
     console.log('Verify component isolation screenshots, editor scenarios, and library tests.');
     console.log();
     console.log(chalk.bold('Component isolation screenshots — verify:'));
@@ -672,13 +1069,15 @@ function printStep10(root, feature) {
     console.log(chalk.dim(`    codeyam editor register '{"name":"ComponentName - Scenario",...}'`));
     console.log();
     console.log(chalk.bold('Editor scenarios (App tab) — visual + error check:'));
-    checkbox(`Refresh the preview: \`curl -s -X POST http://localhost:${port}/api/editor-refresh\``);
+    checkbox(`Refresh the preview: \`codeyam editor preview\``);
     checkbox('Click through each app-level and user-persona scenario in the preview');
-    checkbox(`Check for client-side errors: \`curl -s http://localhost:${port}/api/editor-client-errors\``);
+    checkbox('For seed-based scenarios: verify data renders correctly after switching');
+    console.log(chalk.dim('    Switch between scenarios and confirm the app reflects the seeded data each time'));
+    checkbox(`Check for client-side errors: \`codeyam editor client-errors\``);
     console.log(chalk.yellow('    If `hasErrors` is true: list each scenario with errors, fix the source code,'));
     console.log(chalk.yellow('    re-register the affected scenarios, and re-check until hasErrors is false'));
     console.log(chalk.dim('    Common errors: React errors, failed fetches, undefined references, hydration mismatches'));
-    checkbox('Verify no broken images in any scenario screenshots');
+    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');
@@ -688,99 +1087,131 @@ function printStep10(root, feature) {
     console.log(chalk.dim('Focus on fixing issues. All component screenshots, scenarios, and tests must be clean before proceeding.'));
     stopGate(10);
 }
-// ─── Step 11: Review ──────────────────────────────────────────────────
+// ─── Step 11: Journal ─────────────────────────────────────────────────
 function printStep11(root, feature) {
     const port = getServerPort();
     const prevState = readState(root);
+    const isResuming = prevState?.step === 11;
+    const now = new Date().toISOString();
     writeState(root, {
         feature,
         step: 11,
         label: STEP_LABELS[11],
-        startedAt: new Date().toISOString(),
-        featureStartedAt: prevState?.featureStartedAt || new Date().toISOString(),
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
     });
-    logEvent(root, 'step', { step: 11, label: 'Review', feature });
-    stepHeader(11, 'Review', feature);
-    console.log('Present a full summary, verify screenshots, then let the user save or revise.');
-    console.log();
-    console.log(chalk.bold('Phase 1 — Summary:'));
-    checkbox('Summarize the feature that was built');
-    checkbox('List all components and functions created');
-    checkbox('List glossary entries added in step 6');
-    checkbox('List all scenarios (app-level and user-persona)');
-    checkbox('Report analysis status (completed/in-progress from step 7)');
-    checkbox('Report verification status from step 10 (all clean?)');
-    checkbox(`Refresh the preview: \`curl -s -X POST http://localhost:${port}/api/dev-mode-refresh\``);
-    checkbox(`Get scenario list: \`curl -s http://localhost:${port}/api/editor-scenarios\``);
-    checkbox('Present scenarios in a markdown table — one scenario per row');
-    console.log(chalk.yellow('    EVERY scenario must use {{scenario:Name:ID}} — the terminal makes these clickable.'));
-    console.log(chalk.yellow('    Strip the component prefix: "DrinkCard - Default" → just "Default".'));
-    console.log(chalk.yellow('    Component name on first row of each group, blank for subsequent rows.'));
-    console.log();
-    console.log(chalk.dim('    Example:'));
-    console.log(chalk.dim('      | Component | Scenario |'));
-    console.log(chalk.dim('      |---|---|'));
-    console.log(chalk.dim('      | **App** | {{scenario:Full Catalog:abc}} |'));
-    console.log(chalk.dim('      | | {{scenario:Empty:def}} |'));
-    console.log(chalk.dim('      | | {{scenario:Error:ghi}} |'));
-    console.log(chalk.dim('      | **StarRating** | {{scenario:Perfect:jkl}} |'));
-    console.log(chalk.dim('      | | {{scenario:Medium:mno}} |'));
-    console.log();
-    console.log(chalk.bold('Phase 2 — Screenshot & error verification:'));
-    console.log(chalk.yellow('  CRITICAL: Verify screenshots AND check for client-side errors.'));
-    console.log();
-    console.log(chalk.bold('  Component isolation screenshots:'));
-    checkbox('Verify each component has screenshots in the App tab (grouped under Components)');
-    checkbox('If any are missing, re-register them using `codeyam editor register`');
-    console.log();
-    console.log(chalk.bold('  Client-side errors:'));
-    checkbox(`Check for errors: \`curl -s http://localhost:${port}/api/editor-client-errors\``);
-    checkbox('If `hasErrors` is true, list the errors and fix them in the source code');
-    checkbox('After fixing, re-capture affected scenarios to clear the errors');
-    console.log();
-    checkbox('Do not proceed until all components have screenshots and client errors are resolved');
-    console.log();
-    checkbox('Switch the active scenario to the best demo state for the feature');
-    console.log(chalk.dim(`    curl -s -X POST http://localhost:${port}/api/editor-switch-scenario \\`));
-    console.log(chalk.dim(`      -H 'Content-Type: application/json' -d '{"scenarioSlug":"...","scenarioId":"..."}'`));
-    console.log(chalk.dim('    Pick the scenario that best showcases the feature (not an error/empty state)'));
-    checkbox('Present the summary (with screenshot and error status) to the user');
+    logEvent(root, 'step', { step: 11, label: 'Journal', feature });
+    stepHeader(11, 'Journal', feature);
+    if (isResuming) {
+        printResumptionHeader(11);
+    }
+    console.log('Create or update the journal entry for this feature.');
     console.log();
-    console.log(chalk.bold('Phase 3 — Journal entry (create or update):'));
+    console.log(chalk.bold('Checklist:'));
     checkbox('Write a concise description of what was built (2-3 sentences)');
     checkbox(`First time at step 11 — create journal entry with ALL session screenshots:`);
-    console.log(chalk.dim(`    curl -s -X POST http://localhost:${port}/api/editor-journal-entry \\`));
-    console.log(chalk.dim(`      -H 'Content-Type: application/json' \\`));
-    console.log(chalk.dim(`      -d '{"title":"...","type":"feature","description":"...","includeSessionScenarios":true}'`));
+    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 after changes — update the existing journal entry:`);
-    console.log(chalk.dim(`    curl -s -X PATCH http://localhost:${port}/api/editor-journal-update \\`));
-    console.log(chalk.dim(`      -H 'Content-Type: application/json' \\`));
-    console.log(chalk.dim(`      -d '{"time":"<journal entry time>","description":"<updated description>"}'`));
+    checkbox(`Returning to step 11 (before commit) — update the existing journal entry:`);
+    console.log(chalk.dim(`    codeyam editor journal-update '{"time":"<journal entry time>","description":"<updated>","includeSessionScenarios":true}'`));
+    console.log(chalk.dim('    Note: PATCH only works before the entry is committed. After commit, use POST to create a new entry.'));
+    console.log();
+    console.log(chalk.dim('Focus on creating or updating the journal entry. Summary and presentation happen in step 13.'));
+    stopGate(11);
+}
+// ─── Step 12: Review ──────────────────────────────────────────────────
+function printStep12(root, feature) {
+    const port = getServerPort();
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 12;
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature,
+        step: 12,
+        label: STEP_LABELS[12],
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
+    });
+    logEvent(root, 'step', { step: 12, label: 'Review', feature });
+    stepHeader(12, 'Review', feature);
+    if (isResuming) {
+        printResumptionHeader(12);
+    }
+    console.log('Verify all screenshots and checks pass before presenting to the user.');
+    console.log();
+    console.log(chalk.bold('Checklist (do all of this silently):'));
+    checkbox(`Refresh the preview: \`codeyam editor preview\``);
+    checkbox('Verify each component has screenshots in the App tab (grouped under Components)');
+    checkbox('If any are missing, re-register them using `codeyam editor register`');
+    checkbox(`Check for client errors: \`codeyam editor client-errors\``);
+    checkbox('If `hasErrors` is true, fix them and re-capture affected scenarios');
+    checkbox('Run `codeyam editor verify-images \'{"paths":["/"], "imageUrls":["url1"]}\'` with all page paths and image URLs');
+    checkbox('Fix or remove any broken images before continuing');
+    checkbox('Run `codeyam editor audit` to verify completeness of scenarios and tests');
+    checkbox('Do not proceed until all checks pass');
+    stopGate(12);
+}
+// ─── Step 13: Present ─────────────────────────────────────────────────
+function printStep13(root, feature) {
+    const port = getServerPort();
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 13;
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature,
+        step: 13,
+        label: STEP_LABELS[13],
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
+    });
+    logEvent(root, 'step', { step: 13, label: 'Present', feature });
+    stepHeader(13, 'Present', feature);
+    if (isResuming) {
+        printResumptionHeader(13);
+    }
+    console.log('Present the results to the user and get their approval.');
     console.log();
-    console.log(chalk.bold('Phase 4 — Present a selection menu to the user (use AskUserQuestion):'));
-    console.log(chalk.green('    "Save & commit"') +
+    console.log(chalk.bold('Checklist:'));
+    checkbox('Fetch all scenarios: `codeyam editor scenarios`');
+    console.log(chalk.dim('    Each scenario has a `changeStatus` field: "new", "edited", "impacted", or null.'));
+    checkbox('Pick the best scenario to showcase from this working session:');
+    console.log(chalk.dim('    Prefer scenarios with changeStatus "new" or "edited" (directly changed in this session).'));
+    console.log(chalk.dim('    For app-level scenarios, prefer those showing the new/changed functionality.'));
+    console.log(chalk.dim('    NEVER pick a scenario with changeStatus null — those are unchanged from a previous commit.'));
+    checkbox('Switch the preview to that scenario using its `id`:');
+    console.log(chalk.dim(`    codeyam editor preview '{"scenarioId":"<id>"}'`));
+    checkbox(`Show the results panel: \`codeyam editor show-results\``);
+    console.log(chalk.dim('    This opens a visual panel below the terminal showing all scenarios with screenshots.'));
+    console.log(chalk.dim('    The user can click scenarios to switch the live preview.'));
+    checkbox('Write a 1-2 sentence summary of what was built');
+    checkbox('Report test count and audit status (one line)');
+    console.log();
+    console.log(chalk.bold('Present a selection menu to the user (use AskUserQuestion with these EXACT option labels):'));
+    console.log(chalk.green('    Option 1 label: "Save & commit"') +
         chalk.dim(' — git commit all changes and record in journal'));
-    console.log(chalk.yellow('    "I\'d like to make some changes"') +
+    console.log(chalk.yellow('    Option 2 label: "I\'d like to make some changes"') +
         chalk.dim(' — describe changes, then re-verify'));
     console.log();
     console.log(chalk.bold('If the user chooses "Save & commit":'));
-    checkbox(`Git commit using the journal description: \`curl -s -X POST http://localhost:${port}/api/editor-commit -H 'Content-Type: application/json' -d '{"message":"feat: <title>\\n\\n<journal description>"}'\``);
+    checkbox(`Hide the results panel first: \`codeyam editor hide-results\``);
+    checkbox(`Git commit using the journal description: \`codeyam editor commit '{"message":"feat: <title>\\n\\n<journal description>"}'\``);
     console.log(chalk.dim('    The commit message body MUST match the journal description exactly'));
-    checkbox(`Update journal with commit SHA: \`curl -s -X PATCH http://localhost:${port}/api/editor-journal-update -H 'Content-Type: application/json' -d '{"time":"<journal entry time>","commitSha":"<sha>","commitMessage":"feat: <title>"}'\``);
+    checkbox(`Update journal with commit SHA: \`codeyam editor journal-update '{"time":"<journal entry time>","commitSha":"<sha>","commitMessage":"feat: <title>"}'\``);
     console.log(chalk.green('  Then run: ') +
-        chalk.bold('codeyam editor 1') +
+        chalk.bold('codeyam editor steps') +
         chalk.green(' to start the next feature'));
     console.log();
-    console.log(chalk.bold('If the user chooses "Make changes":'));
-    checkbox('Ask what changes the user wants');
-    checkbox('Make the requested changes');
-    console.log(chalk.yellow('  Then run: ') +
-        chalk.bold('codeyam editor 10') +
-        chalk.yellow(' to re-verify, which flows back to step 11'));
-    console.log();
-    console.log(chalk.dim('Complete all phases in order: summary, screenshot verification, journal entry, user menu.'));
-    stopGate(11, { confirm: true });
+    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.'));
+    console.log();
+    console.log(chalk.bold('If the user chooses "Make changes" (or asks for ANY change, even as a question):'));
+    checkbox(`Hide the results panel: \`codeyam editor hide-results\``);
+    checkbox('Ask what changes the user wants (if not already clear)');
+    checkbox(`Run: \`codeyam editor change "${feature}"\` — this gives you the change checklist`);
+    checkbox('THEN make the requested changes and follow the checklist');
+    console.log(chalk.red.bold('  IMPORTANT: Always run the change command BEFORE writing any code.'));
+    stopGate(13, { confirm: true });
 }
 // ─── Command definition ───────────────────────────────────────────────
 // ─── Analyze-imports subcommand ────────────────────────────────────────
@@ -837,8 +1268,9 @@ async function handleAnalyzeImports() {
     await initializeEnvironment();
     const entities = await loadEntities({});
     if (!entities || entities.length === 0) {
-        progress.fail('No entities found in database');
-        process.exit(1);
+        progress.succeed('No entities found in database yet — skipping import analysis. This is normal on the first feature.');
+        console.log(JSON.stringify({ imports: {}, entities: {} }));
+        return;
     }
     // Deduplicate to latest versions
     const latestByKey = new Map();
@@ -894,7 +1326,161 @@ async function handleAnalyzeImports() {
     const output = { imports, entities: entityData };
     console.log(JSON.stringify(output, null, 2));
 }
+// ─── Validate-seed subcommand ─────────────────────────────────────────
+/**
+ * Validate seed data structure and check for a seed adapter.
+ * Usage: codeyam editor validate-seed '{"products":[...]}'
+ */
+function handleValidateSeed(jsonArg) {
+    const root = process.cwd();
+    // Check for seed adapter
+    const adapterPath = detectSeedAdapter(root);
+    if (adapterPath) {
+        console.log(chalk.green(`Seed adapter found: ${adapterPath}`));
+    }
+    else {
+        console.log(chalk.yellow('No seed adapter found. Create .codeyam/seed-adapter.ts to use seed-based scenarios.'));
+    }
+    if (!jsonArg) {
+        return;
+    }
+    let data;
+    try {
+        data = JSON.parse(jsonArg);
+    }
+    catch {
+        console.error(chalk.red('Error: Invalid JSON.'));
+        process.exit(1);
+    }
+    const result = validateSeedData(data);
+    if (result.valid) {
+        const tables = Object.keys(data);
+        const totalRows = tables.reduce((sum, t) => sum + (Array.isArray(data[t]) ? data[t].length : 0), 0);
+        console.log(chalk.green(`Seed data valid: ${tables.length} table(s), ${totalRows} total row(s)`));
+        for (const table of tables) {
+            const rows = Array.isArray(data[table])
+                ? data[table].length
+                : 0;
+            console.log(chalk.dim(`  ${table}: ${rows} row(s)`));
+        }
+    }
+    else {
+        console.error(chalk.red('Seed data validation failed:'));
+        for (const err of result.errors) {
+            console.error(chalk.red(`  - ${err}`));
+        }
+        process.exit(1);
+    }
+}
+// ─── Isolate subcommand ───────────────────────────────────────────────
+/**
+ * `codeyam editor isolate StarRating CategoryBadge DrinkCard`
+ *
+ * Creates isolation route directories and the layout guard file.
+ * This avoids brace-expansion permission prompts in the embedded terminal.
+ */
+function handleIsolate(componentNames) {
+    const root = process.cwd();
+    if (componentNames.length === 0) {
+        console.error(chalk.red('Usage: codeyam editor isolate ComponentA ComponentB ...'));
+        process.exit(1);
+    }
+    const isolateDir = path.join(root, 'app', 'codeyam-isolate');
+    // Create layout.tsx with production guard if missing
+    const layoutPath = path.join(isolateDir, 'layout.tsx');
+    if (!fs.existsSync(layoutPath)) {
+        fs.mkdirSync(isolateDir, { recursive: true });
+        fs.writeFileSync(layoutPath, [
+            'import { notFound } from "next/navigation";',
+            '',
+            'export default function CaptureLayout({ children }: { children: React.ReactNode }) {',
+            '  if (process.env.NODE_ENV === "production") notFound();',
+            '  return <>{children}</>;',
+            '}',
+            '',
+        ].join('\n'), 'utf8');
+        console.log(chalk.green(`Created layout guard: app/codeyam-isolate/layout.tsx`));
+    }
+    // Create a directory for each component
+    const created = [];
+    const existed = [];
+    for (const name of componentNames) {
+        const dir = path.join(isolateDir, name);
+        if (fs.existsSync(dir)) {
+            existed.push(name);
+        }
+        else {
+            fs.mkdirSync(dir, { recursive: true });
+            created.push(name);
+        }
+    }
+    if (created.length > 0) {
+        console.log(chalk.green(`Created ${created.length} isolation route dir(s): ${created.join(', ')}`));
+    }
+    if (existed.length > 0) {
+        console.log(chalk.dim(`Already existed: ${existed.join(', ')}`));
+    }
+}
 // ─── Register subcommand ──────────────────────────────────────────────
+/**
+ * Format API subcommand results as concise one-line summaries.
+ * Prevents Claude from piping output to python3 just to extract key fields.
+ * Returns null for subcommands that should keep raw JSON output.
+ */
+function formatApiSubcommandResult(subcommand, data) {
+    if (!data || typeof data !== 'object')
+        return null;
+    switch (subcommand) {
+        case 'journal': {
+            const parts = [`success=${data.success}`];
+            if (data.entry?.time)
+                parts.push(`time="${data.entry.time}"`);
+            if (data.entry?.title)
+                parts.push(`title="${data.entry.title}"`);
+            if (data.scenarioScreenshotsFound != null) {
+                parts.push(`screenshots=${data.scenarioScreenshotsFound}`);
+            }
+            return parts.join(' ');
+        }
+        case 'journal-update': {
+            const parts = [`success=${data.success}`];
+            if (data.entry?.time)
+                parts.push(`time="${data.entry.time}"`);
+            if (data.scenarioScreenshotsFound != null) {
+                parts.push(`screenshots=${data.scenarioScreenshotsFound}`);
+            }
+            return parts.join(' ');
+        }
+        case 'commit': {
+            const parts = [`success=${data.success}`];
+            if (data.sha)
+                parts.push(`sha=${data.sha}`);
+            if (data.message)
+                parts.push(`message="${data.message.split('\n')[0]}"`);
+            return parts.join(' ');
+        }
+        case 'preview': {
+            const parts = [
+                `success=${!!data.ok || data.success !== false}`,
+            ];
+            if (data.path)
+                parts.push(`path="${data.path}"`);
+            if (data.scenarioId)
+                parts.push(`scenarioId="${data.scenarioId}"`);
+            if (data.sessionsNotified != null)
+                parts.push(`notified=${data.sessionsNotified}`);
+            return parts.join(' ');
+        }
+        case 'dev-server': {
+            if (data.status) {
+                return `status=${data.status} pid=${data.pid || 'none'} port=${data.port || 'none'}`;
+            }
+            return null;
+        }
+        default:
+            return null; // journal-list, client-errors, show/hide-results: keep full JSON
+    }
+}
 /**
  * `codeyam editor register '{"name":"...","componentName":"...",...}'`
  *
@@ -904,18 +1490,19 @@ async function handleAnalyzeImports() {
 async function handleRegister(jsonArg) {
     if (!jsonArg) {
         console.error(chalk.red('Error: JSON argument required.'));
-        console.error(chalk.dim('  Usage: codeyam editor register \'{"name":"DrinkCard - Default","componentName":"DrinkCard","url":"/codeyam-isolate/DrinkCard?s=Default"}\''));
+        console.error(chalk.dim('  Usage: codeyam editor register \'{"name":"DrinkCard - Default","componentName":"DrinkCard","url":"/isolated-components/DrinkCard?s=Default"}\''));
+        console.error(chalk.dim('  For large payloads: codeyam editor register @/tmp/scenario.json'));
         process.exit(1);
     }
-    let body;
-    try {
-        body = JSON.parse(jsonArg);
-    }
-    catch {
-        console.error(chalk.red('Error: Invalid JSON.'));
-        console.error(chalk.dim(`  Received: ${jsonArg.slice(0, 200)}`));
+    const parsed = parseRegisterArg(jsonArg);
+    if (parsed.error) {
+        console.error(chalk.red(`Error: ${parsed.error}`));
+        if (parsed.error === 'Invalid JSON') {
+            console.error(chalk.dim(`  Received: ${jsonArg.slice(0, 200)}`));
+        }
         process.exit(1);
     }
+    const body = parsed.body;
     const port = getServerPort();
     const url = `http://localhost:${port}/api/editor-register-scenario`;
     try {
@@ -925,8 +1512,34 @@ async function handleRegister(jsonArg) {
             body: JSON.stringify(body),
         });
         const data = await res.json();
-        console.log(JSON.stringify(data, null, 2));
+        // Print concise summary instead of raw JSON so Claude doesn't need python3
+        const parts = [];
+        parts.push(`success=${data.success}`);
+        if (data.scenario?.name)
+            parts.push(`name="${data.scenario.name}"`);
+        parts.push(`screenshot=${!!data.screenshotCaptured}`);
+        if (data.clientErrors?.length > 0) {
+            parts.push(chalk.red(`errors=${data.clientErrors.length}`));
+        }
+        else {
+            parts.push(`errors=0`);
+        }
+        if (data.seedResult)
+            parts.push(`seed=${data.seedResult.success}`);
+        if (data.captureError)
+            parts.push(chalk.yellow(`captureError="${data.captureError}"`));
+        console.log(parts.join(' '));
+        // Surface client errors prominently so they can't be missed
+        if (data.clientErrors && data.clientErrors.length > 0) {
+            console.log(chalk.red.bold(`⚠ WARNING: ${data.clientErrors.length} client error${data.clientErrors.length !== 1 ? 's' : ''} detected during capture:`));
+            for (const err of data.clientErrors) {
+                console.log(chalk.red(`  → ${err}`));
+            }
+            console.log(chalk.yellow('  The screenshot may show an error screen instead of the actual component.'));
+            console.log(chalk.yellow('  Fix the issue and re-register this scenario.'));
+        }
         if (!res.ok) {
+            console.error(chalk.dim(JSON.stringify(data, null, 2)));
             process.exit(1);
         }
     }
@@ -938,15 +1551,775 @@ async function handleRegister(jsonArg) {
         process.exit(1);
     }
 }
+// ─── Dependents subcommand ────────────────────────────────────────────
+/**
+ * `codeyam editor dependents <EntityName>`
+ *
+ * Walks the importedBy reverse dependency tree to find all ancestors of a
+ * given entity — i.e., every component or page that transitively imports it.
+ * Used after code changes to determine what needs recapturing.
+ */
+async function handleDependents(entityName) {
+    if (!entityName) {
+        console.error(chalk.red('Error: Entity name required.'));
+        console.error(chalk.dim('  Usage: codeyam editor dependents DrinkCard'));
+        process.exit(1);
+    }
+    const progress = new ProgressReporter();
+    progress.start('Loading entities from database...');
+    await initializeEnvironment();
+    const allEntities = await loadEntities({});
+    if (!allEntities || allEntities.length === 0) {
+        progress.fail('No entities found in database');
+        console.error(chalk.dim('  Run codeyam editor analyze-imports first to populate entity data.'));
+        process.exit(1);
+    }
+    // Find the target entity by name (case-insensitive match)
+    const targetEntities = allEntities.filter((e) => e.name.toLowerCase() === entityName.toLowerCase());
+    if (targetEntities.length === 0) {
+        progress.fail(`Entity "${entityName}" not found in database`);
+        const names = [...new Set(allEntities.map((e) => e.name))].sort();
+        console.error(chalk.dim(`  Available entities: ${names.join(', ')}`));
+        process.exit(1);
+    }
+    progress.succeed('Entities loaded');
+    // Build lookup: entityName -> Set<entityName> of entities that import it.
+    // Each entity's metadata.importedBy is the pre-computed reverse graph:
+    //   { [filePath]: { [importerName]: { shas: string[] } } }
+    const importedByName = new Map();
+    for (const entity of allEntities) {
+        const importedBy = entity.metadata?.importedBy;
+        if (!importedBy || typeof importedBy !== 'object')
+            continue;
+        const importers = new Set();
+        for (const filePath of Object.keys(importedBy)) {
+            for (const importerName of Object.keys(importedBy[filePath])) {
+                importers.add(importerName);
+            }
+        }
+        if (importers.size > 0) {
+            importedByName.set(entity.name, importers);
+        }
+    }
+    // BFS walk up the dependency tree from the changed entity
+    const visited = new Set();
+    const result = [];
+    const queue = [
+        { name: entityName, depth: 0 },
+    ];
+    visited.add(entityName.toLowerCase());
+    // Collect entity types for display
+    const entityTypes = new Map();
+    for (const e of allEntities) {
+        if (!entityTypes.has(e.name)) {
+            entityTypes.set(e.name, e.entityType || 'unknown');
+        }
+    }
+    while (queue.length > 0) {
+        const { name, depth } = queue.shift();
+        result.push({
+            name,
+            entityType: entityTypes.get(name) || 'unknown',
+            depth,
+        });
+        // Find all entities that import this one
+        const importers = importedByName.get(name);
+        if (!importers)
+            continue;
+        for (const importerName of importers) {
+            if (visited.has(importerName.toLowerCase()))
+                continue;
+            visited.add(importerName.toLowerCase());
+            queue.push({ name: importerName, depth: depth + 1 });
+        }
+    }
+    // Output
+    if (result.length <= 1) {
+        console.log(chalk.yellow(`No dependents found for "${entityName}".`));
+        console.log(chalk.dim('  This entity is not imported by any other known entities.'));
+        console.log(chalk.dim('  Run codeyam editor analyze-imports to populate import data.'));
+        return;
+    }
+    console.log(chalk.bold(`Dependency tree for ${entityName} (${result.length} entities):`));
+    console.log();
+    for (const entry of result) {
+        const indent = '  '.repeat(entry.depth);
+        const prefix = entry.depth === 0 ? chalk.cyan('●') : chalk.dim('├──');
+        const label = entry.depth === 0
+            ? chalk.cyan(`${entry.name} (changed)`)
+            : chalk.white(entry.name);
+        const type = chalk.dim(`[${entry.entityType}]`);
+        console.log(`${indent}${prefix} ${label} ${type}`);
+    }
+    console.log();
+    console.log(chalk.dim('All listed entities need their scenarios recaptured after changes.'));
+}
+// ─── Change subcommand ───────────────────────────────────────────────
+/**
+ * `codeyam editor change <feature>`
+ *
+ * Prints a condensed post-change checklist that guides Claude through
+ * re-verifying after user-requested modifications. This is the "change
+ * loop" — it replaces the freeform "make changes" path with structured
+ * instructions that always loop back to step 13 present.
+ */
+function handleChange(feature) {
+    const root = getProjectRoot();
+    if (!feature) {
+        // Try to read feature from state
+        const state = readState(root);
+        if (state?.feature) {
+            feature = state.feature;
+        }
+        else {
+            console.error(chalk.red('Error: Feature name required.'));
+            console.error(chalk.dim('  Usage: codeyam editor change "My Feature"'));
+            process.exit(1);
+        }
+    }
+    const port = getServerPort();
+    console.log();
+    console.log(chalk.bold.cyan('━━━ Change Loop ━━━'));
+    console.log(chalk.dim(`Feature: ${feature}`));
+    console.log();
+    console.log('The user has requested changes. Follow this checklist after making them.');
+    console.log();
+    console.log(chalk.bold.cyan('Keep the preview moving:'));
+    console.log(chalk.cyan(`  Refresh after EACH individual change — not after all changes are done:`));
+    console.log(chalk.cyan(`  codeyam editor preview`));
+    console.log(chalk.cyan('  The user is watching the preview. Let them see progress incrementally.'));
+    console.log();
+    console.log(chalk.bold('0. Close the results panel:'));
+    checkbox(`Hide results: \`codeyam editor hide-results\``);
+    console.log();
+    console.log(chalk.bold('1. Re-register affected component scenarios:'));
+    checkbox('For each component you modified, re-register ALL its scenarios');
+    console.log(chalk.dim(`    codeyam editor register '{"name":"ComponentName - ScenarioName","componentName":"ComponentName","componentPath":"app/components/ComponentName.tsx","url":"/isolated-components/ComponentName?s=ScenarioName"}'`));
+    checkbox('For any NEW components: `codeyam editor isolate NewComponent` then create isolation routes and register scenarios');
+    console.log();
+    console.log(chalk.bold('2. Re-run affected tests:'));
+    checkbox('Re-run test files for any functions you modified');
+    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');
+    checkbox('If you re-seeded the database, restart the dev server to pick up fresh data');
+    console.log(chalk.dim(`    codeyam editor dev-server '{"action":"restart"}'`));
+    console.log();
+    console.log(chalk.bold('3. Re-capture app-level scenarios:'));
+    checkbox('Run `codeyam editor analyze-imports` to refresh the import graph after code changes');
+    checkbox('If component changes affect app-level pages, re-register affected app scenarios');
+    checkbox(`Use \`codeyam editor dependents ComponentName\` to find what needs recapturing`);
+    console.log();
+    console.log(chalk.bold('4. Verify completeness:'));
+    checkbox(`Refresh the preview: \`codeyam editor preview\``);
+    checkbox(`Navigate to key pages to verify changes: \`codeyam editor preview '{"path":"/your-route"}'\``);
+    checkbox('Run `codeyam editor audit` — all checks must pass');
+    checkbox(`Check for client-side errors: \`codeyam editor client-errors\``);
+    checkbox('Fix any errors, then re-register affected scenarios');
+    console.log();
+    console.log(chalk.bold('5. Update the existing journal entry:'));
+    checkbox('Get existing entry: `codeyam editor journal-list`');
+    checkbox('Find the uncommitted entry (commitSha is null) from this feature session');
+    checkbox(`Update it: \`codeyam editor journal-update '{"time":"<entry time>","description":"<updated description including changes>","includeSessionScenarios":true}'\``);
+    console.log(chalk.dim('    Always update the existing uncommitted entry — do NOT create a new one.'));
+    console.log(chalk.dim('    Only create a new entry (POST) if no uncommitted entry exists for this feature.'));
+    console.log();
+    console.log(chalk.red('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+    console.log(chalk.red.bold('  REQUIRED: Show Results'));
+    console.log(chalk.red.bold('  When all checks pass, you MUST run: ') +
+        chalk.bold(`codeyam editor 13`));
+    console.log(chalk.red.bold('  The user ALWAYS expects to see results after changes. DO NOT skip this step.'));
+    console.log(chalk.red('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+    console.log();
+}
+// ─── Audit subcommand ────────────────────────────────────────────────
+/**
+ * `codeyam editor audit`
+ *
+ * Fetches the /api/editor-audit endpoint and prints a checklist showing
+ * which glossary components have registered scenarios and which functions
+ * have test files. Exits with code 1 if anything is missing.
+ */
+async function handleAudit() {
+    const port = getServerPort();
+    const url = `http://localhost:${port}/api/editor-audit`;
+    let data;
+    try {
+        const res = await fetch(url);
+        if (!res.ok) {
+            console.error(chalk.red(`Error: Audit endpoint returned ${res.status}`));
+            process.exit(1);
+        }
+        data = await res.json();
+    }
+    catch (err) {
+        console.error(chalk.red('Error: Could not reach the CodeYam server. Is it running?'));
+        console.error(chalk.dim(`  ${err.message}`));
+        process.exit(1);
+    }
+    const { components, functions, summary } = data;
+    console.log();
+    console.log(chalk.bold.cyan('━━━ Editor Audit ━━━'));
+    console.log();
+    // Components
+    if (components.length > 0) {
+        console.log(chalk.bold('Components (scenarios):'));
+        for (const c of components) {
+            const icon = c.status === 'ok' ? chalk.green('✓') : 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 === 'ok') {
+                detail = chalk.dim(` (${c.scenarioCount} scenario${c.scenarioCount !== 1 ? 's' : ''})`);
+            }
+            else {
+                detail = chalk.red(' — no scenarios registered');
+            }
+            console.log(`  ${icon} ${c.name}${detail}`);
+            if (c.clientErrors && c.clientErrors.length > 0) {
+                for (const err of c.clientErrors.slice(0, 3)) {
+                    console.log(chalk.red(`      → ${err}`));
+                }
+                if (c.clientErrors.length > 3) {
+                    console.log(chalk.dim(`      … and ${c.clientErrors.length - 3} more`));
+                }
+            }
+        }
+        console.log();
+    }
+    // Functions
+    if (functions.length > 0) {
+        console.log(chalk.bold('Functions (test files):'));
+        for (const f of functions) {
+            const icon = f.status === 'ok' ? chalk.green('✓') : chalk.red('✗');
+            let detail;
+            switch (f.status) {
+                case 'ok':
+                    detail = chalk.dim(` (${f.testFile})`);
+                    break;
+                case 'failing':
+                    detail = chalk.red(` — tests failing: ${f.testFile}`);
+                    break;
+                case 'name_mismatch':
+                    detail = chalk.red(` — tests pass but missing top-level describe("${f.name}", ...) — tests won't display in UI`);
+                    break;
+                case 'missing':
+                default:
+                    detail = f.testFile
+                        ? chalk.red(` — test file missing: ${f.testFile}`)
+                        : chalk.red(' — no test file specified');
+                    break;
+            }
+            console.log(`  ${icon} ${f.name}${detail}`);
+        }
+        console.log();
+    }
+    // Summary
+    const allOk = summary.allPassing;
+    if (allOk) {
+        console.log(chalk.green.bold('All checks passed!') +
+            chalk.dim(` (${summary.totalComponents} component${summary.totalComponents !== 1 ? 's' : ''}, ${summary.totalFunctions} function${summary.totalFunctions !== 1 ? 's' : ''})`));
+    }
+    else {
+        const parts = [];
+        if (summary.componentsMissing > 0) {
+            parts.push(`${summary.componentsMissing} component${summary.componentsMissing !== 1 ? 's' : ''} missing scenarios`);
+        }
+        if (summary.componentsWithErrors > 0) {
+            parts.push(`${summary.componentsWithErrors} component${summary.componentsWithErrors !== 1 ? 's' : ''} with client errors`);
+        }
+        if (summary.functionsMissing > 0) {
+            parts.push(`${summary.functionsMissing} function${summary.functionsMissing !== 1 ? 's' : ''} missing tests`);
+        }
+        if (summary.functionsFailing > 0) {
+            parts.push(`${summary.functionsFailing} function${summary.functionsFailing !== 1 ? 's' : ''} with failing tests`);
+        }
+        if (summary.functionsNameMismatch > 0) {
+            parts.push(`${summary.functionsNameMismatch} function${summary.functionsNameMismatch !== 1 ? 's' : ''} with test name mismatch (missing top-level describe)`);
+        }
+        console.log(chalk.red.bold('Audit failed: ') + parts.join(', '));
+    }
+    console.log();
+    if (!allOk) {
+        process.exit(1);
+    }
+}
+// ─── Scenarios subcommand ─────────────────────────────────────────────
+async function handleScenarios() {
+    const port = getServerPort();
+    const url = `http://localhost:${port}/api/editor-scenarios`;
+    let data;
+    try {
+        const res = await fetch(url);
+        if (!res.ok) {
+            console.error(chalk.red(`Error: Scenarios endpoint returned ${res.status}`));
+            process.exit(1);
+        }
+        data = await res.json();
+    }
+    catch (err) {
+        console.error(chalk.red('Error: Could not reach the CodeYam server. Is it running?'));
+        console.error(chalk.dim(`  ${err.message}`));
+        process.exit(1);
+    }
+    const scenarios = data.scenarios;
+    if (scenarios.length === 0) {
+        console.log();
+        console.log(chalk.yellow('No scenarios found for this feature session.'));
+        console.log();
+        return;
+    }
+    // Group by componentName (null → "Uncategorized")
+    const groups = new Map();
+    for (const s of scenarios) {
+        const key = s.componentName || 'Uncategorized';
+        if (!groups.has(key))
+            groups.set(key, []);
+        groups.get(key).push(s);
+    }
+    // Strip component prefix from names (e.g. "DrinkCard - Default" → "Default")
+    function stripPrefix(name, componentName) {
+        if (!componentName)
+            return name;
+        const prefix = `${componentName} - `;
+        return name.startsWith(prefix) ? name.slice(prefix.length) : name;
+    }
+    // Calculate column widths
+    let maxCompLen = 'Component'.length;
+    let maxScenLen = 'Scenario'.length;
+    for (const [comp, items] of groups) {
+        maxCompLen = Math.max(maxCompLen, comp.length);
+        for (const s of items) {
+            const display = stripPrefix(s.name, s.componentName);
+            maxScenLen = Math.max(maxScenLen, display.length);
+        }
+    }
+    const pad = (str, len) => str + ' '.repeat(Math.max(0, len - str.length));
+    // Build OSC 8 hyperlink (display length = visible text only)
+    const osc8 = (url, text) => `\x1b]8;;${url}\x07${text}\x1b]8;;\x07`;
+    // Print table
+    console.log();
+    console.log(chalk.bold.cyan('━━━ Scenario Table ━━━'));
+    console.log();
+    const divComp = '─'.repeat(maxCompLen + 2);
+    const divScen = '─'.repeat(maxScenLen + 2);
+    // Header
+    console.log(`┌${divComp}┬${divScen}┐`);
+    console.log(`│ ${chalk.bold(pad('Component', maxCompLen))} │ ${chalk.bold(pad('Scenario', maxScenLen))} │`);
+    console.log(`├${divComp}┼${divScen}┤`);
+    // Rows
+    let groupIndex = 0;
+    for (const [comp, items] of groups) {
+        if (groupIndex > 0) {
+            console.log(`├${divComp}┼${divScen}┤`);
+        }
+        for (let i = 0; i < items.length; i++) {
+            const s = items[i];
+            const compCell = i === 0 ? chalk.bold(pad(comp, maxCompLen)) : pad('', maxCompLen);
+            const display = stripPrefix(s.name, s.componentName);
+            const linked = osc8(s.link, display);
+            // linked has invisible escape chars; pad based on display length
+            const scenPad = ' '.repeat(Math.max(0, maxScenLen - display.length));
+            console.log(`│ ${compCell} │ ${linked}${scenPad} │`);
+        }
+        groupIndex++;
+    }
+    // Footer
+    console.log(`└${divComp}┴${divScen}┘`);
+    console.log();
+    const total = scenarios.length;
+    const groupCount = groups.size;
+    console.log(chalk.dim(`${total} scenario${total !== 1 ? 's' : ''} across ${groupCount} component${groupCount !== 1 ? 's' : ''}`));
+    console.log();
+}
+// ─── Template subcommand ─────────────────────────────────────────────
+async function handleTemplate() {
+    const root = getProjectRoot();
+    const port = getServerPort();
+    if (hasProject(root)) {
+        console.log(chalk.yellow('Project already exists (package.json found). Skipping.'));
+        return;
+    }
+    // Determine which template to use from editor state
+    const state = readState(root);
+    const techStackId = state?.techStackId;
+    const stack = techStackId
+        ? TECH_STACKS.find((s) => s.id === techStackId)
+        : undefined;
+    const templateName = stack?.templateDir || 'nextjs-prisma-sqlite';
+    const templateDir = path.join(__dirname, '..', '..', 'templates', templateName);
+    if (!fs.existsSync(templateDir)) {
+        console.error(chalk.red('Error: Template directory not found at ' + templateDir));
+        process.exit(1);
+    }
+    const { execSync } = await import('child_process');
+    // 1. Copy template files
+    console.log(chalk.bold(`Copying ${stack?.name || templateName} template files...`));
+    execSync(`cp -r ${templateDir}/* .`, { cwd: root, stdio: 'inherit' });
+    // Copy dotfiles that are stored without the dot prefix in templates
+    const gitignorePath = path.join(templateDir, 'gitignore');
+    if (fs.existsSync(gitignorePath)) {
+        execSync(`cp ${templateDir}/gitignore .gitignore`, {
+            cwd: root,
+            stdio: 'inherit',
+        });
+    }
+    const envPath = path.join(templateDir, 'env');
+    if (fs.existsSync(envPath)) {
+        execSync(`cp ${templateDir}/env .env`, { cwd: root, stdio: 'inherit' });
+    }
+    // Copy seed adapter into .codeyam/ (stored outside .codeyam/ in the template
+    // to avoid gitignore issues — .codeyam/ is selectively ignored in user projects)
+    const seedAdapterSrc = path.join(templateDir, 'seed-adapter.ts');
+    if (fs.existsSync(seedAdapterSrc)) {
+        const codeyamDir = path.join(root, '.codeyam');
+        if (!fs.existsSync(codeyamDir)) {
+            fs.mkdirSync(codeyamDir, { recursive: true });
+        }
+        fs.copyFileSync(seedAdapterSrc, path.join(codeyamDir, 'seed-adapter.ts'));
+    }
+    console.log(chalk.green('  Template files copied.'));
+    // 2. Install dependencies
+    console.log(chalk.bold('Installing dependencies...'));
+    execSync('npm install', { cwd: root, stdio: 'inherit' });
+    console.log(chalk.green('  Dependencies installed.'));
+    // 3. Initialize git
+    const hasGit = fs.existsSync(path.join(root, '.git'));
+    if (!hasGit) {
+        console.log(chalk.bold('Initializing git...'));
+        execSync('git init && git add -A && git commit -m "Initial commit"', {
+            cwd: root,
+            stdio: 'inherit',
+        });
+        console.log(chalk.green('  Git initialized.'));
+    }
+    // 4. Run codeyam init
+    console.log(chalk.bold('Running codeyam init...'));
+    await initCommand.handler({
+        force: true,
+        'keep-server': true,
+        autoInit: false,
+        $0: '',
+        _: [],
+    });
+    console.log(chalk.green('  CodeYam initialized.'));
+    // 5. Verify config has startCommand
+    const configPath = path.join(root, '.codeyam', 'config.json');
+    if (fs.existsSync(configPath)) {
+        try {
+            const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+            const webapps = config.webapps || [];
+            const hasStartCommand = webapps.some((w) => w.startCommand);
+            if (!hasStartCommand) {
+                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"] }'));
+            }
+        }
+        catch {
+            // Config parse error is non-fatal
+        }
+    }
+    // 6. Trigger editor-refresh so the server picks up the new project
+    console.log(chalk.bold('Refreshing editor...'));
+    try {
+        await fetch(`http://localhost:${port}/api/editor-refresh`, {
+            method: 'POST',
+        });
+        console.log(chalk.green('  Editor refreshed.'));
+    }
+    catch {
+        console.log(chalk.yellow('  Could not reach the CodeYam server for refresh. You may need to restart it.'));
+    }
+    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.'));
+}
+// ─── Sync subcommand ─────────────────────────────────────────────────
+/**
+ * `codeyam editor sync`
+ * Import scenarios from scenarios-manifest.json into the local database.
+ */
+async function handleSync() {
+    const root = getProjectRoot();
+    const manifest = readManifest(root);
+    if (!manifest) {
+        console.log(chalk.yellow('No scenarios-manifest.json found. Nothing to sync.'));
+        return;
+    }
+    if (manifest.scenarios.length === 0) {
+        console.log(chalk.dim('Manifest is empty. Nothing to sync.'));
+        return;
+    }
+    const configPath = path.join(root, '.codeyam', 'config.json');
+    let projectSlug = null;
+    try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        projectSlug = config.projectSlug || null;
+    }
+    catch {
+        // fall through
+    }
+    if (!projectSlug) {
+        console.error(chalk.red('Error: No project slug found. Run codeyam init first.'));
+        process.exit(1);
+    }
+    const connectionOk = await withoutSpinner(() => testEnvironment());
+    if (!connectionOk) {
+        errorLog('Environment validation failed');
+        return;
+    }
+    const { project } = await requireBranchAndProject(projectSlug);
+    const { getDatabase } = await import('../../../packages/database/index.js');
+    const db = getDatabase();
+    // Fetch existing editor scenarios
+    const existingRows = await db
+        .selectFrom('editor_scenarios')
+        .select(['id', 'updated_at'])
+        .where('project_id', '=', project.id)
+        .execute();
+    const result = await syncManifestToDatabase(root, project.id, existingRows, async (row) => {
+        await db
+            .insertInto('editor_scenarios')
+            .values(row)
+            .execute();
+    }, async (id, row) => {
+        await db
+            .updateTable('editor_scenarios')
+            .set(row)
+            .where('id', '=', id)
+            .execute();
+    });
+    if (result.inserted === 0 && result.updated === 0) {
+        console.log(chalk.dim('All scenarios up to date.'));
+    }
+    else {
+        const parts = [];
+        if (result.inserted > 0)
+            parts.push(`${result.inserted} imported`);
+        if (result.updated > 0)
+            parts.push(`${result.updated} updated`);
+        if (result.skipped > 0)
+            parts.push(`${result.skipped} unchanged`);
+        console.log(chalk.green(`Synced scenarios: ${parts.join(', ')}`));
+    }
+}
+// ─── Verify Images subcommand ─────────────────────────────────────────
+async function handleVerifyImages(jsonArg) {
+    const port = getServerPort();
+    const { parseVerifyImagesInput, extractImageUrls, resolveImageUrl, verifyImageUrls, buildVerifyImagesReport, extractImageUrlsFromScenarioFiles, } = await import('../utils/editorImageVerifier.js');
+    let paths;
+    let explicitImageUrls;
+    try {
+        const input = parseVerifyImagesInput(jsonArg);
+        paths = input.paths;
+        explicitImageUrls = input.imageUrls;
+    }
+    catch {
+        console.error(chalk.red('Error: Invalid JSON argument'));
+        process.exit(1);
+    }
+    // Get dev server URL
+    let devServerUrl;
+    try {
+        const res = await fetch(`http://localhost:${port}/api/editor-dev-server`);
+        const data = await res.json();
+        devServerUrl = data.url || `http://localhost:${data.port || 3000}`;
+    }
+    catch {
+        console.error(chalk.red('Error: Could not reach the CodeYam server. Is it running?'));
+        process.exit(1);
+    }
+    const allUrls = new Set();
+    let pagesChecked = 0;
+    for (const pagePath of paths) {
+        const pageUrl = `${devServerUrl}${pagePath}`;
+        try {
+            const res = await fetch(pageUrl);
+            if (!res.ok) {
+                console.error(chalk.red(`  ✗ ${pagePath} — HTTP ${res.status}`));
+                continue;
+            }
+            const html = await res.text();
+            const imageUrls = extractImageUrls(html);
+            for (const url of imageUrls) {
+                allUrls.add(resolveImageUrl(url, devServerUrl));
+            }
+            pagesChecked++;
+        }
+        catch (err) {
+            console.error(chalk.red(`  ✗ ${pagePath} — ${err.message}`));
+        }
+    }
+    // Add explicitly-provided image URLs (Claude passes these directly)
+    for (const url of explicitImageUrls) {
+        allUrls.add(resolveImageUrl(url, devServerUrl));
+    }
+    // Also scan scenario mock data files for image URLs (client-rendered pages)
+    const scenariosDir = path.join(getProjectRoot(), '.codeyam', 'editor-scenarios');
+    const { urls: scenarioUrls, filesScanned: scenarioFilesScanned } = extractImageUrlsFromScenarioFiles(scenariosDir);
+    for (const url of scenarioUrls) {
+        allUrls.add(resolveImageUrl(url, devServerUrl));
+    }
+    const urlList = [...allUrls];
+    const results = urlList.length > 0 ? await verifyImageUrls(urlList) : [];
+    const report = buildVerifyImagesReport({
+        pagesChecked,
+        imageUrls: urlList,
+        results,
+        scenarioFilesScanned,
+    });
+    console.log(JSON.stringify(report, null, 2));
+    if (report.failures.length > 0) {
+        process.exit(1);
+    }
+}
+// ─── Debug subcommand ────────────────────────────────────────────────
+function handleEditorDebug(args) {
+    const root = getProjectRoot();
+    const feature = args.feature || 'Sample Feature';
+    const includeContext = args.includeContext !== false;
+    let targets;
+    try {
+        targets = parseDebugTargets(args.target);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(chalk.red(`Error: ${msg}`));
+        process.exit(1);
+    }
+    const includeResume = typeof args.resume === 'boolean' ? args.resume : true;
+    const includeNormal = typeof args.resume === 'boolean' ? !args.resume : true;
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const outputDir = args.output
+        ? path.resolve(args.output)
+        : path.join(root, '.codeyam', 'logs', 'editor-debug', timestamp);
+    fs.mkdirSync(outputDir, { recursive: true });
+    const contextEntries = includeContext
+        ? writeContextSnapshot(root, outputDir)
+        : [];
+    const scenarios = [];
+    const wants = (id) => (targets ? targets.has(id) : true);
+    if (wants('setup')) {
+        scenarios.push({
+            id: 'setup',
+            title: 'Setup (no project)',
+            render: () => withTempRoot(false, (tempRoot) => captureOutput(() => printSetup(tempRoot))),
+        });
+    }
+    if (wants('overview')) {
+        scenarios.push({
+            id: 'overview',
+            title: 'Cycle overview (project, no state)',
+            render: () => withTempRoot(true, (tempRoot) => captureOutput(() => printCycleOverview(tempRoot, null))),
+        });
+    }
+    if (wants('overview-with-state')) {
+        scenarios.push({
+            id: 'overview-with-state',
+            title: 'Cycle overview (project, with state)',
+            render: () => withTempRoot(true, (tempRoot) => captureOutput(() => printCycleOverview(tempRoot, makeState(4, feature)))),
+        });
+    }
+    const stepFns = {
+        1: (r, f) => printStep1(r, f),
+        2: printStep2,
+        3: printStep3,
+        4: printStep4,
+        5: printStep5,
+        6: printStep6,
+        7: printStep7,
+        8: printStep8,
+        9: printStep9,
+        10: printStep10,
+        11: printStep11,
+        12: printStep12,
+        13: printStep13,
+    };
+    for (let step = 1; step <= 13; step++) {
+        const stepId = `step-${step}`;
+        if (!wants(stepId))
+            continue;
+        if (includeNormal) {
+            scenarios.push({
+                id: stepId,
+                title: `Step ${step} (${STEP_LABELS[step]})`,
+                render: () => withTempRoot(true, (tempRoot) => captureOutput(() => stepFns[step](tempRoot, feature))),
+            });
+            if (step === 1 && !args.feature) {
+                scenarios.push({
+                    id: 'step-1-no-feature',
+                    title: 'Step 1 (Plan) — no feature provided',
+                    render: () => withTempRoot(true, (tempRoot) => captureOutput(() => printStep1(tempRoot, undefined))),
+                });
+            }
+            if (step === 2) {
+                scenarios.push({
+                    id: 'step-2-scaffold',
+                    title: 'Step 2 (Prototype) — scaffold flow (no project)',
+                    render: () => withTempRoot(false, (tempRoot) => captureOutput(() => printStep2(tempRoot, feature))),
+                });
+            }
+        }
+        if (includeResume) {
+            scenarios.push({
+                id: `${stepId}-resume`,
+                title: `Step ${step} (${STEP_LABELS[step]}) — resuming`,
+                render: () => withTempRoot(true, (tempRoot) => {
+                    writeState(tempRoot, makeState(step, feature));
+                    return captureOutput(() => stepFns[step](tempRoot, feature));
+                }),
+            });
+        }
+    }
+    const indexLines = [
+        '# CodeYam Editor Debug Bundle',
+        '',
+        `Generated: ${new Date().toISOString()}`,
+        `Feature: "${feature}"`,
+        `Resume variants: ${includeResume ? 'included' : 'skipped'}`,
+        'Note: Output files preserve ANSI color codes (as printed to the terminal).',
+        '',
+    ];
+    if (includeContext) {
+        indexLines.push('## Context snapshot');
+        if (contextEntries.length === 0) {
+            indexLines.push('- (none)');
+        }
+        else {
+            for (const entry of contextEntries) {
+                const source = entry.source ? ` ← ${entry.source}` : '';
+                indexLines.push(`- ${entry.label}: ${entry.file} (${entry.status})${source}`);
+            }
+        }
+        indexLines.push('');
+    }
+    indexLines.push('## Scenarios');
+    for (const scenario of scenarios) {
+        const fileName = `${scenario.id}.txt`;
+        const output = scenario.render();
+        fs.writeFileSync(path.join(outputDir, fileName), output, 'utf8');
+        indexLines.push(`- ${scenario.title}: ${fileName}`);
+    }
+    fs.writeFileSync(path.join(outputDir, 'index.md'), indexLines.join('\n'), 'utf8');
+    console.log();
+    console.log(chalk.bold.cyan('━━━ Editor Debug Bundle ━━━'));
+    console.log();
+    console.log(chalk.green('Wrote debug bundle to: ') + chalk.bold(outputDir));
+    console.log(chalk.dim('  Open index.md for the full list of scenario outputs.'));
+    console.log();
+}
 // ─── Command definition ───────────────────────────────────────────────
 const editorCommand = {
     command: 'editor [step] [json]',
     describe: 'Editor mode guided workflow',
     builder: (yargs) => {
-        return yargs
+        const stepDescription = IS_INTERNAL_BUILD
+            ? 'Step number (1-13) or subcommand (template, register, isolate, analyze-imports, dependents, audit, scenarios, change, sync, debug, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors)'
+            : 'Step number (1-13) or subcommand (template, register, isolate, analyze-imports, dependents, audit, scenarios, change, sync, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors)';
+        let builder = yargs
             .positional('step', {
             type: 'string',
-            describe: 'Step number (1-11) or subcommand (register, analyze-imports)',
+            describe: stepDescription,
         })
             .positional('json', {
             type: 'string',
@@ -955,10 +2328,79 @@ const editorCommand = {
             .option('feature', {
             type: 'string',
             describe: 'Feature name (required for step 2)',
+        })
+            .option('app-formats', {
+            type: 'string',
+            describe: 'Comma-separated app formats (web-app, mobile-responsive-web-app, desktop-app, mobile-app)',
+        })
+            .option('tech-stack', {
+            type: 'string',
+            describe: 'Selected tech stack ID (e.g., nextjs-prisma-sqlite)',
+        })
+            .option('prompt', {
+            type: 'string',
+            describe: "User's original prompt (captured for journal/results)",
+        })
+            .option('port', {
+            type: 'number',
+            alias: 'p',
+            describe: 'Port to run the web server on',
+            default: 3111,
         });
+        if (IS_INTERNAL_BUILD) {
+            builder = builder
+                .option('target', {
+                type: 'string',
+                describe: 'Debug target (setup, overview, overview-with-state, step-1..step-13, or comma-separated list)',
+            })
+                .option('resume', {
+                type: 'boolean',
+                describe: 'Debug: only render resume variants (use --no-resume for only normal)',
+            })
+                .option('include-context', {
+                type: 'boolean',
+                default: true,
+                describe: 'Debug: include CLAUDE.md, skill, and editor-mode-context snapshots',
+            })
+                .option('output', {
+                type: 'string',
+                describe: 'Debug: output directory for the bundle',
+            });
+        }
+        return builder;
     },
     handler: async (argv) => {
         const root = getProjectRoot();
+        // API subcommands: preview, show-results, hide-results, commit,
+        // journal, journal-update, dev-server, client-errors
+        if (argv.step && EDITOR_API_SUBCOMMANDS.includes(argv.step)) {
+            const port = getServerPort();
+            try {
+                const request = buildEditorApiRequest(argv.step, argv.json || undefined);
+                const result = await callEditorApi(request, port);
+                if (!result.ok) {
+                    console.error(chalk.red(`Error: ${request.endpoint} returned ${result.status}`));
+                    if (result.data)
+                        console.error(JSON.stringify(result.data, null, 2));
+                    process.exit(1);
+                }
+                if (result.data != null) {
+                    const summary = formatApiSubcommandResult(argv.step, result.data);
+                    if (summary) {
+                        console.log(summary);
+                    }
+                    else {
+                        console.log(JSON.stringify(result.data, null, 2));
+                    }
+                }
+            }
+            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);
+            }
+            return;
+        }
         // Subcommand: codeyam editor register '{"name":"..."}'
         if (argv.step === 'register') {
             await handleRegister(argv.json || '');
@@ -969,27 +2411,259 @@ const editorCommand = {
             await handleAnalyzeImports();
             return;
         }
-        const step = argv.step ? parseInt(argv.step, 10) : undefined;
-        if (step != null && (isNaN(step) || step < 1 || step > 11)) {
-            console.error(chalk.red(`Error: Invalid step "${argv.step}". Must be 1-11.`));
-            process.exit(1);
+        // Subcommand: codeyam editor dependents <EntityName>
+        if (argv.step === 'dependents') {
+            await handleDependents(argv.json || '');
+            return;
         }
-        if (step == null) {
-            // No step specified: setup or overview
+        // Subcommand: codeyam editor audit
+        if (argv.step === 'audit') {
+            await handleAudit();
+            return;
+        }
+        // Subcommand: codeyam editor scenarios
+        if (argv.step === 'scenarios') {
+            await handleScenarios();
+            return;
+        }
+        // Subcommand: codeyam editor change <feature>
+        if (argv.step === 'change') {
+            handleChange(argv.json || '');
+            return;
+        }
+        // Subcommand: codeyam editor verify-images '{"paths":["/","/drinks/1"]}'
+        if (argv.step === 'verify-images') {
+            await handleVerifyImages(argv.json || '');
+            return;
+        }
+        // Subcommand: codeyam editor validate-seed '{"products":[...]}'
+        if (argv.step === 'validate-seed') {
+            await handleValidateSeed(argv.json || '');
+            return;
+        }
+        // Subcommand: codeyam editor isolate StarRating CategoryBadge DrinkCard
+        if (argv.step === 'isolate') {
+            const names = [];
+            if (argv.json)
+                names.push(...argv.json.split(/[\s,]+/).filter(Boolean));
+            // Collect any extra positional args (yargs puts them in argv._)
+            const extras = argv._.filter((a) => typeof a === 'string' && a !== 'editor');
+            names.push(...extras);
+            handleIsolate(names);
+            return;
+        }
+        // Subcommand: codeyam editor template — scaffold project from template
+        if (argv.step === 'template') {
+            await handleTemplate();
+            return;
+        }
+        // Subcommand: codeyam editor sync — import scenarios from manifest
+        if (argv.step === 'sync') {
+            await handleSync();
+            return;
+        }
+        // Subcommand: codeyam editor debug [--target ...]
+        if (argv.step === 'debug') {
+            if (!IS_INTERNAL_BUILD) {
+                console.error(chalk.red('Error: "codeyam editor debug" is internal-only.'));
+                process.exit(1);
+            }
+            await handleEditorDebug(argv);
+            return;
+        }
+        // Subcommand: codeyam editor steps — show setup or cycle overview
+        if (argv.step === 'steps') {
             if (!hasProject(root)) {
                 printSetup(root);
             }
             else {
                 const state = readState(root);
+                // Clear prompt file when feature is done (step 13) so the hook
+                // can capture the next feature request from the user.
+                if (state?.step === 13) {
+                    clearEditorUserPrompt(root);
+                }
                 printCycleOverview(root, state);
             }
             return;
         }
+        const step = argv.step ? parseInt(argv.step, 10) : undefined;
+        if (step != null && (isNaN(step) || step < 1 || step > 13)) {
+            console.error(chalk.red(`Error: Invalid step "${argv.step}". Must be 1-13.`));
+            process.exit(1);
+        }
+        if (step == null) {
+            // No step specified: launch editor server + open browser
+            // Auto-init if needed
+            let projectRoot = getStateProjectRoot();
+            if (!projectRoot) {
+                await initCommand.handler({
+                    force: false,
+                    autoInit: true,
+                    $0: '',
+                    _: [],
+                });
+                projectRoot = getStateProjectRoot();
+                if (!projectRoot) {
+                    return;
+                }
+            }
+            const configPath = path.join(projectRoot, '.codeyam', 'config.json');
+            try {
+                const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+                const { projectSlug } = config;
+                if (!projectSlug) {
+                    errorLog('Missing project slug. Try reinitializing with: codeyam init --force');
+                    return;
+                }
+                const connectionOk = await withoutSpinner(() => testEnvironment());
+                if (!connectionOk) {
+                    errorLog('Environment validation failed');
+                    return;
+                }
+                const { project, branch } = await requireBranchAndProject(projectSlug);
+                // Auto-sync scenarios from manifest if it exists
+                const manifestData = readManifest(projectRoot);
+                if (manifestData && manifestData.scenarios.length > 0) {
+                    try {
+                        const { getDatabase } = await import('../../../packages/database/index.js');
+                        const db = getDatabase();
+                        const existingRows = await db
+                            .selectFrom('editor_scenarios')
+                            .select(['id', 'updated_at'])
+                            .where('project_id', '=', project.id)
+                            .execute();
+                        const syncResult = await syncManifestToDatabase(projectRoot, project.id, existingRows, async (row) => {
+                            await db
+                                .insertInto('editor_scenarios')
+                                .values(row)
+                                .execute();
+                        }, async (id, row) => {
+                            await db
+                                .updateTable('editor_scenarios')
+                                .set(row)
+                                .where('id', '=', id)
+                                .execute();
+                        });
+                        if (syncResult.inserted > 0 || syncResult.updated > 0) {
+                            const parts = [];
+                            if (syncResult.inserted > 0)
+                                parts.push(`${syncResult.inserted} imported`);
+                            if (syncResult.updated > 0)
+                                parts.push(`${syncResult.updated} updated`);
+                            console.log(chalk.green(`  Synced scenarios from manifest: ${parts.join(', ')}`));
+                        }
+                    }
+                    catch {
+                        // Non-fatal — sync failure shouldn't block editor startup
+                    }
+                }
+                // `codeyam editor` (no step) always implies editor mode.
+                // The empty-folder heuristic is no longer needed here — running this
+                // command IS the signal.  We still detect empty folders so that
+                // the very first `codeyam editor` in a bare directory works before
+                // metadata has been persisted.
+                const editorMode = true;
+                if (editorMode && !project.metadata?.labs?.simulations) {
+                    try {
+                        await updateProjectMetadata({
+                            projectSlug,
+                            metadataUpdate: {
+                                editorMode: true,
+                                labs: { simulations: true },
+                            },
+                        });
+                        const refreshed = await requireBranchAndProject(projectSlug);
+                        Object.assign(project, refreshed.project);
+                    }
+                    catch {
+                        // Non-fatal
+                    }
+                }
+                // Install skills/hooks
+                const simulationsEnabled = project.metadata?.labs?.simulations ?? false;
+                const skillMode = simulationsEnabled
+                    ? 'full'
+                    : editorMode
+                        ? 'editor'
+                        : 'memory';
+                await installClaudeCodeSkills(projectRoot, {
+                    mode: skillMode,
+                    editorMode,
+                });
+                setupClaudeCodeSettings(projectRoot, {
+                    mode: skillMode,
+                    editorMode,
+                });
+                // Auto-finalize analyzer so codeyam analyze works
+                if (editorMode && !isAnalyzerFinalized()) {
+                    try {
+                        const { execSync } = await import('child_process');
+                        const templatePath = getAnalyzerTemplatePath();
+                        if (fs.existsSync(templatePath)) {
+                            console.log('  Setting up simulations (first time only)...');
+                            execSync('npm install --include=dev', {
+                                cwd: templatePath,
+                                stdio: 'pipe',
+                            });
+                            execSync('npx playwright install chromium', {
+                                cwd: templatePath,
+                                stdio: 'pipe',
+                            });
+                            execSync('npm run build', {
+                                cwd: templatePath,
+                                stdio: 'pipe',
+                            });
+                            fs.writeFileSync(path.join(templatePath, '.finalized'), new Date().toISOString());
+                        }
+                    }
+                    catch {
+                        // Non-fatal
+                    }
+                }
+                // Start background server
+                const { url } = await startBackgroundServer({
+                    port: argv.port || 3111,
+                    rootPath: projectRoot,
+                    project,
+                    branch,
+                });
+                console.log();
+                console.log(`  Dashboard: ${url}`);
+                console.log('  Run "codeyam --help" for all commands');
+                console.log(chalk.bold('  Run "codeyam editor" to launch the editor at any time'));
+                console.log();
+                // Open browser to /editor
+                try {
+                    const { execSync } = await import('child_process');
+                    const openCommand = process.platform === 'darwin'
+                        ? 'open'
+                        : process.platform === 'win32'
+                            ? 'start ""'
+                            : 'xdg-open';
+                    execSync(`${openCommand} "${url}/editor"`, { stdio: 'ignore' });
+                }
+                catch {
+                    // Silently fail if open command doesn't work
+                }
+            }
+            catch (err) {
+                errorLog('Failed to start CodeYam editor server');
+                errorLog(err);
+                process.exit(1);
+            }
+            return;
+        }
         const state = readState(root);
         switch (step) {
             case 1: {
                 const feature = argv.feature || undefined;
-                printStep1(root, feature);
+                const appFormats = argv['app-formats']
+                    ? argv['app-formats'].split(',').map((f) => f.trim())
+                    : undefined;
+                const techStackId = argv['tech-stack'] || undefined;
+                const prompt = argv.prompt || undefined;
+                printStep1(root, feature, { appFormats, techStackId }, prompt);
                 break;
             }
             case 2: {
@@ -1010,7 +2684,9 @@ const editorCommand = {
             case 8:
             case 9:
             case 10:
-            case 11: {
+            case 11:
+            case 12:
+            case 13: {
                 const feature = argv.feature || state?.feature;
                 if (!feature) {
                     console.error(chalk.red('Error: No feature in progress. Run codeyam editor 1 first.'));
@@ -1026,6 +2702,8 @@ const editorCommand = {
                     9: printStep9,
                     10: printStep10,
                     11: printStep11,
+                    12: printStep12,
+                    13: printStep13,
                 };
                 stepFns[step](root, feature);
                 break;