@codeyam/codeyam-cli 0.1.0-staging.ad31e3e → 0.1.0-staging.ae0de75

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

@@ -0,0 +1,1839 @@
+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 { IS_INTERNAL_BUILD } from "../utils/buildFlags.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const STEP_LABELS = {
+    1: 'Plan',
+    2: 'Prototype',
+    3: 'Confirm',
+    4: 'Deconstruct',
+    5: 'Extract',
+    6: 'Glossary',
+    7: 'Analyze',
+    8: 'App Scenarios',
+    9: 'User Scenarios',
+    10: 'Verify',
+    11: 'Journal',
+    12: 'Review',
+};
+/**
+ * Append a JSONL log entry to .codeyam/logs/editor-log.jsonl
+ */
+function logEvent(root, event, data) {
+    try {
+        const logsDir = path.join(root, '.codeyam', 'logs');
+        fs.mkdirSync(logsDir, { recursive: true });
+        const logPath = path.join(logsDir, 'editor-log.jsonl');
+        const entry = JSON.stringify({
+            ts: new Date().toISOString(),
+            event,
+            ...data,
+        });
+        fs.appendFileSync(logPath, entry + '\n', 'utf8');
+    }
+    catch {
+        // Logging is best-effort
+    }
+}
+/**
+ * Get the project root (where .codeyam/ lives) or cwd.
+ */
+function getProjectRoot() {
+    return process.env.CODEYAM_ROOT_PATH || process.cwd();
+}
+/**
+ * Path to the editor step state file.
+ */
+function getStatePath(root) {
+    return path.join(root, '.codeyam', 'editor-step.json');
+}
+/**
+ * Read the current editor state, or null if none.
+ */
+function readState(root) {
+    const statePath = getStatePath(root);
+    try {
+        const content = fs.readFileSync(statePath, 'utf8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write the editor state.
+ */
+function writeState(root, state) {
+    const statePath = getStatePath(root);
+    const dir = path.dirname(statePath);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(statePath, JSON.stringify(state, null, 2), 'utf8');
+}
+/**
+ * Clear the editor state (for starting a new feature).
+ */
+function clearState(root) {
+    const statePath = getStatePath(root);
+    try {
+        fs.unlinkSync(statePath);
+    }
+    catch {
+        // File doesn't exist, that's fine
+    }
+}
+/**
+ * Check if a project has been scaffolded (package.json exists).
+ */
+function hasProject(root) {
+    return fs.existsSync(path.join(root, 'package.json'));
+}
+/**
+ * Get the CodeYam server port from env or default.
+ */
+function getServerPort() {
+    return process.env.CODEYAM_PORT || '3111';
+}
+/**
+ * Print a checklist item.
+ * Inline backtick-wrapped text is highlighted in cyan for visibility.
+ */
+function checkbox(text) {
+    // Highlight `backtick-wrapped` segments in cyan
+    const highlighted = text.replace(/`([^`]+)`/g, (_m, code) => chalk.cyan(code));
+    console.log(`  ${chalk.dim('[ ]')} ${highlighted}`);
+}
+/**
+ * Print a section header.
+ */
+function stepHeader(step, title, feature) {
+    console.log();
+    console.log(chalk.bold.cyan(`━━━ Step ${step}: ${title} ━━━`));
+    if (feature) {
+        console.log(chalk.dim(`Feature: "${feature}"`));
+    }
+    console.log();
+}
+/**
+ * Print a colored progress tracker showing all 11 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 <= 12; i++) {
+        const label = STEP_LABELS[i];
+        const num = i < 10 ? ` ${i}` : `${i}`;
+        const content = `${num}. ${label.padEnd(28)}`;
+        if (i < current) {
+            console.log(chalk.dim('  │') + chalk.green(`  ✓  ${content}`) + chalk.dim('│'));
+        }
+        else if (i === current) {
+            console.log(chalk.dim('  │') + chalk.bold.cyan(`  →  ${content}`) + chalk.dim('│'));
+        }
+        else {
+            console.log(chalk.dim(`  │  ○  ${content}│`));
+        }
+    }
+    console.log(chalk.dim('  └─────────────────────────────────────┘'));
+}
+/**
+ * Print a hard STOP gate directing to the next command.
+ *
+ * Options:
+ * - confirm: true  → step requires user confirmation before proceeding (steps 1, 3, 11)
+ */
+function stopGate(current, opts) {
+    console.log();
+    console.log(chalk.bold.red('━━━ STOP ━━━'));
+    console.log();
+    console.log(chalk.red('Complete each checklist item above before proceeding to the next step.'));
+    if (opts?.confirm) {
+        console.log();
+        console.log(chalk.yellow('Wait for user confirmation before moving on.'));
+    }
+    console.log();
+    console.log(chalk.bold.yellow('Present the following progress tracker to the user (copy it verbatim):'));
+    printProgressTracker(current);
+    console.log();
+    console.log(chalk.yellow('For the CURRENT step (→), show each checklist item with ✓ (done) or ✗ (skipped + reason).'));
+    console.log(chalk.yellow('If any items are ✗, explain why and ask if the user wants to address them.'));
+    console.log();
+    if (current < 12) {
+        console.log(chalk.green('When done, run: ') +
+            chalk.bold(`codeyam editor ${current + 1}`));
+    }
+    else {
+        console.log(chalk.green('Feature complete! Run: ') +
+            chalk.bold('codeyam editor 1') +
+            chalk.green(' to start the next feature'));
+    }
+    console.log();
+}
+/**
+ * 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      \`curl -s http://localhost:${port}/api/editor-scenarios\``,
+        ],
+        9: [
+            `Check existing user-persona scenarios:\n      \`curl -s http://localhost:${port}/api/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      \`curl -s http://localhost:${port}/api/editor-journal\``,
+            'If an entry exists, use PATCH to update it — do NOT create a new one',
+        ],
+        12: ['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 <= 12) {
+                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();
+    logEvent(root, 'setup');
+    console.log();
+    console.log(chalk.bold.cyan('━━━ Editor Mode: Project Setup ━━━'));
+    console.log();
+    console.log("No project detected. Let's get started.");
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    checkbox('Read `.codeyam/editor-mode-context.md` for session state');
+    checkbox('Ask the user what they want to build');
+    console.log();
+    console.log(chalk.bold.red('━━━ STOP ━━━'));
+    console.log();
+    console.log(chalk.red('Ask the user what they want to build, then run:'));
+    console.log();
+    console.log(chalk.green('  ') + chalk.bold('codeyam editor 1 --feature "Feature Name"'));
+    console.log(chalk.dim('  Replace "Feature Name" with a short title for what the user described.'));
+    console.log(chalk.dim('  Step 1 will guide you through planning and getting user confirmation before any code is written.'));
+    console.log();
+}
+// ─── Cycle overview (no args, has project) ────────────────────────────
+function printCycleOverview(root, state) {
+    logEvent(root, 'overview', state ? { feature: state.feature, step: state.step } : {});
+    console.log();
+    console.log(chalk.bold.cyan('━━━ Editor Mode: Feature Cycle ━━━'));
+    console.log();
+    if (state) {
+        console.log(chalk.yellow(`Current: Step ${state.step} (${state.label}) — "${state.feature}"`));
+        console.log();
+        console.log(chalk.green('Continue with: ') +
+            chalk.bold(`codeyam editor ${state.step}`));
+        console.log(chalk.dim('Or run ') +
+            chalk.bold('codeyam editor 1') +
+            chalk.dim(' to start a new feature'));
+    }
+    else {
+        console.log('Each feature follows 12 steps. You MUST run each command in order:');
+        console.log();
+        console.log(`  ${chalk.bold.yellow(' 1')} ${chalk.bold('Plan')}            — Plan the feature, confirm with user`);
+        console.log(`  ${chalk.bold.yellow(' 2')} ${chalk.bold('Prototype')}       — Build a working prototype fast`);
+        console.log(`  ${chalk.bold.yellow(' 3')} ${chalk.bold('Confirm')}         — Confirm prototype with user`);
+        console.log(`  ${chalk.bold.yellow(' 4')} ${chalk.bold('Deconstruct')}     — Read code, plan all extractions`);
+        console.log(`  ${chalk.bold.yellow(' 5')} ${chalk.bold('Extract')}         — TDD extraction of functions + components`);
+        console.log(`  ${chalk.bold.yellow(' 6')} ${chalk.bold('Glossary')}        — Record functions in glossary`);
+        console.log(`  ${chalk.bold.yellow(' 7')} ${chalk.bold('Analyze')}         — Analyze and verify components`);
+        console.log(`  ${chalk.bold.yellow(' 8')} ${chalk.bold('App Scenarios')}   — Create app-level scenarios`);
+        console.log(`  ${chalk.bold.yellow(' 9')} ${chalk.bold('User Scenarios')}  — Create user-persona scenarios`);
+        console.log(`  ${chalk.bold.yellow('10')} ${chalk.bold('Verify')}          — Review screenshots, check for errors`);
+        console.log(`  ${chalk.bold.yellow('11')} ${chalk.bold('Journal')}         — Create/update journal entry`);
+        console.log(`  ${chalk.bold.yellow('12')} ${chalk.bold('Review')}          — Present summary, get approval`);
+        console.log();
+        console.log(chalk.green('Start now: ') + chalk.bold('codeyam editor 1'));
+    }
+    console.log();
+}
+// ─── Step 1: Plan ─────────────────────────────────────────────────────
+function printStep1(root, feature) {
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 1;
+    if (!isResuming) {
+        clearState(root);
+    }
+    // If feature is provided, save initial state so step 2 can pick it up
+    if (feature) {
+        const now = new Date().toISOString();
+        writeState(root, {
+            feature,
+            step: 1,
+            label: STEP_LABELS[1],
+            startedAt: isResuming ? prevState.startedAt : now,
+            featureStartedAt: isResuming ? prevState.featureStartedAt : now,
+        });
+    }
+    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:'));
+    checkbox('Read `.codeyam/glossary.json` for reusable functions/components');
+    checkbox('Ask the user what they want to build (if not already described)');
+    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"') +
+        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.'));
+    console.log();
+    console.log(chalk.bold.red('━━━ STOP ━━━'));
+    console.log();
+    console.log(chalk.red('Complete each checklist item above before proceeding to the next step.'));
+    console.log();
+    console.log(chalk.yellow('Wait for user confirmation before moving on.'));
+    console.log();
+    console.log(chalk.bold.yellow('Present the following progress tracker to the user (copy it verbatim):'));
+    printProgressTracker(1);
+    console.log();
+    console.log(chalk.yellow('For the CURRENT step (→), show each checklist item with ✓ (done) or ✗ (skipped + reason).'));
+    console.log(chalk.yellow('If any items are ✗, explain why and ask if the user wants to address them.'));
+    console.log();
+    console.log(chalk.green('When done, run: ') +
+        chalk.bold('codeyam editor 2 --feature "Feature Name"'));
+    console.log(chalk.dim('  Replace "Feature Name" with a short title for what you just described.'));
+    console.log();
+}
+// ─── Step 2: Prototype ────────────────────────────────────────────────
+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: isResuming ? prevState.startedAt : now,
+        featureStartedAt: isResuming ? prevState.featureStartedAt : now,
+    });
+    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 App Router) 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'));
+        }
+        console.log();
+        checkbox('Initialize git so analysis and commits work');
+        console.log(chalk.dim('  git init && git add -A && git commit -m "Initial commit"'));
+        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'));
+        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();
+        console.log(chalk.bold('Build the feature:'));
+    }
+    console.log(chalk.bold('Checklist:'));
+    checkbox('Create/update API routes (real database reads via Prisma)');
+    checkbox('Seed the database with demo data');
+    checkbox('Build the page/feature UI components');
+    checkbox('Verify the dev server shows the changes');
+    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('  # 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();
+    console.log(chalk.bold('Verify before proceeding:'));
+    console.log(chalk.yellow('  Verify everything works before presenting the prototype to the user.'));
+    checkbox('Verify the page loads: curl the dev server URL and confirm HTTP 200 (not an error page)');
+    checkbox('Verify API routes return valid JSON: curl each route and confirm no error responses');
+    checkbox('Check for broken images: look at any <img> src attributes and verify the assets exist');
+    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();
+    console.log(chalk.dim('Focus on building the prototype. Scenarios and refactoring happen in later steps.'));
+    stopGate(2);
+}
+// ─── Step 3: Confirm ──────────────────────────────────────────────────
+function printStep3(root, feature) {
+    const port = getServerPort();
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 3;
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature,
+        step: 3,
+        label: STEP_LABELS[3],
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
+    });
+    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(`Refresh and check for SSR errors: \`curl -s -X POST http://localhost:${port}/api/dev-mode-preview\` — look at the \`preview\` field for \`healthy: false\``);
+    checkbox('Verify API routes return valid data (curl each route)');
+    checkbox(`Navigate to each page and check health: \`curl -s -X POST http://localhost:${port}/api/dev-mode-preview -H 'Content-Type: application/json' -d '{"path":"/your-route"}'\``);
+    console.log();
+    console.log(chalk.bold('  Check for broken images on each page:'));
+    checkbox('Get the dev server URL from `curl -s http://localhost:' +
+        port +
+        '/api/editor-dev-server` (the `url` field)');
+    checkbox('For each page: `curl -s <dev-server-url>/your-route` and inspect `<img>` src attributes');
+    checkbox('Verify every image src is a valid path (not a missing file, placeholder URL, or broken reference)');
+    checkbox('If any images are broken: fix the src (use real assets, placeholders from a CDN, or remove the image)');
+    console.log(chalk.yellow('    Do not present to the user until all checks pass. Fix issues first.'));
+    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"') +
+        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.'));
+    stopGate(3, { confirm: true });
+}
+// ─── 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: 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();
+    console.log(chalk.bold.red('THE RULE: No direct JSX in page files.'));
+    console.log(chalk.yellow('  After extraction, a page/route file should import and compose components — nothing else.'));
+    console.log(chalk.yellow('  Every distinct visual section in the page is its own component.'));
+    console.log(chalk.yellow('  Every component that renders multiple distinct sections should be split into sub-components.'));
+    console.log(chalk.yellow('  If a component has N visually distinct parts, it should compose N sub-components.'));
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    checkbox('Read `.codeyam/glossary.json` — note reusable functions/components');
+    checkbox('Read EVERY file created or modified in this session');
+    console.log(chalk.yellow('    For EACH file, identify EVERY extractable piece:'));
+    console.log(chalk.yellow('    Components: headers, nav, loading states, empty states, error states,'));
+    console.log(chalk.yellow('      badges/pills, image containers, card sections, form fields, modals,'));
+    console.log(chalk.yellow('      titles, descriptions, rating displays, status indicators, buttons'));
+    console.log(chalk.yellow('    Functions: data transforms, calculations, formatting, validation,'));
+    console.log(chalk.yellow('      API response shaping, any logic that is not directly about rendering'));
+    console.log(chalk.yellow('    Hooks: data fetching, state management, side effects'));
+    console.log();
+    checkbox('Write a numbered extraction plan listing EVERYTHING you will extract');
+    console.log(chalk.yellow('    The end state: every page file is ONLY imports + component composition.'));
+    console.log(chalk.yellow('    No raw <div>, <span>, <h1>, <p>, <img>, or <ul> in page files.'));
+    console.log(chalk.yellow('    Every visual section in every component is itself a component.'));
+    console.log();
+    console.log(chalk.yellow('    For each item in the plan, note:'));
+    console.log(chalk.yellow('    — What it is (component, function, hook)'));
+    console.log(chalk.yellow('    — Where it currently lives (source file + approximate lines)'));
+    console.log(chalk.yellow('    — Where it will go (new file path)'));
+    console.log();
+    console.log(chalk.dim('Present the numbered plan, then proceed to step 5 to execute it.'));
+    stopGate(4);
+}
+// ─── Step 5: Extract ──────────────────────────────────────────────────
+function printStep5(root, feature) {
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 5;
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature,
+        step: 5,
+        label: STEP_LABELS[5],
+        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:'));
+    checkbox('Extract each component from your plan into its own file');
+    checkbox('Page/route files must contain ZERO direct JSX — only imported components');
+    checkbox('Every component that renders multiple sections must be split into sub-components');
+    console.log(chalk.dim('    No tests needed — visual verification happens in step 7'));
+    console.log();
+    console.log(chalk.bold('Library functions (TDD):'));
+    checkbox('For each function: write MULTIPLE failing tests FIRST, then extract to make them pass');
+    console.log(chalk.dim('    Cover: typical inputs, edge cases, empty/null inputs, error conditions'));
+    console.log(chalk.dim('    Aim for 3-8 test cases per function depending on complexity'));
+    checkbox('Place test files next to source: `app/lib/drinks.ts` → `app/lib/drinks.test.ts`');
+    console.log(chalk.yellow('  Tests ARE the only coverage for library functions — step 7 only captures component screenshots.'));
+    console.log();
+    console.log(chalk.bold('Recursive pass:'));
+    checkbox('Re-read EVERY new file you just created — extract components from components, functions from functions');
+    checkbox('Keep going until every file is a thin shell: just imports and composition');
+    console.log(chalk.yellow('    Check: does any file contain raw <div>, <span>, <h1>, <p>, <img>, or <ul>?'));
+    console.log(chalk.yellow('    If yes → that JSX section is a component waiting to be extracted.'));
+    console.log();
+    console.log(chalk.bold('Verify before proceeding:'));
+    checkbox('Run all tests and verify they pass');
+    checkbox('Page files contain ONLY imports + component composition — no raw HTML tags');
+    checkbox('Every component renders ONE thing or composes sub-components — no multi-section JSX');
+    console.log(chalk.dim('Reuse glossary functions when they fit naturally. Extract a new function when the use case diverges.'));
+    console.log();
+    console.log(chalk.dim('Focus on TDD for functions and extraction for components. Scenarios come in later steps.'));
+    stopGate(5);
+}
+// ─── 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: 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:'));
+    checkbox("Read `.codeyam/glossary.json` (create if it doesn't exist)");
+    checkbox('Add an entry for each new function/component extracted in step 5');
+    checkbox('Each entry should have: name, filePath, description, parameters, returnType, tags, feature');
+    checkbox('For each function with a test file from step 5, set `testFile` to the relative path');
+    console.log();
+    console.log(chalk.bold('Entry format:'));
+    console.log(chalk.dim('  { "name": "calculateTotal", "filePath": "app/utils/pricing.ts",'));
+    console.log(chalk.dim('    "description": "Calculates total price including tax and discounts",'));
+    console.log(chalk.dim('    "parameters": [{ "name": "items", "type": "CartItem[]" }],'));
+    console.log(chalk.dim('    "returnType": "number", "tags": ["pricing"],'));
+    console.log(chalk.dim('    "testFile": "app/utils/pricing.test.ts",'));
+    console.log(chalk.dim(`    "feature": "${feature}", "createdAt": "..." }`));
+    console.log();
+    console.log(chalk.dim('Focus on updating the glossary. Application code and scenarios come in later steps.'));
+    stopGate(6);
+}
+// ─── Step 7: Analyze ──────────────────────────────────────────────────
+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: 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('For each visual component:');
+    console.log(chalk.dim('    1. Read the source AND find where it is used in the app to understand:'));
+    console.log(chalk.dim('       — Props/interface'));
+    console.log(chalk.dim('       — Container width in the real app (e.g. card in a 3-col grid → max-w-sm)'));
+    console.log(chalk.dim('    2. Plan multiple scenarios that exercise the component like tests:'));
+    console.log(chalk.dim('       — Default/happy path with typical data'));
+    console.log(chalk.dim('       — Edge cases: empty/missing data, long text, maximum items, zero counts'));
+    console.log(chalk.dim('       — Different visual states: loading, error, disabled, selected, hover'));
+    console.log(chalk.dim('       — Boundary values: single item vs many, min/max ratings, very long names'));
+    console.log(chalk.dim('    3. Create ONE isolation route per component with a scenarios map and ?s= query param:'));
+    console.log(chalk.dim('       Remix:   app/routes/codeyam-isolate.ComponentName.tsx → /codeyam-isolate/ComponentName'));
+    console.log(chalk.dim('       Next.js: app/codeyam-isolate/ComponentName/page.tsx → /codeyam-isolate/ComponentName'));
+    console.log(chalk.dim('       The route defines a `scenarios` object mapping scenario names to props,'));
+    console.log(chalk.dim('       reads `?s=ScenarioName` from the URL, and renders the component with those props.'));
+    console.log(chalk.dim('       Wrap the component in a capture container with id="codeyam-capture":'));
+    console.log(chalk.dim('       <div id="codeyam-capture" style={{ display:"inline-block", padding:"20px" }}>'));
+    console.log(chalk.dim('         <div style={{ width:"100%", maxWidth:"..." }}> ← match the app\'s container width'));
+    console.log(chalk.dim('       e.g. card in a 3-col grid → maxWidth:"24rem", full-width component → omit maxWidth'));
+    console.log(chalk.dim('       The screenshot captures just this wrapper, so the component fills the image.'));
+    console.log(chalk.dim('       Center the wrapper on the page (flexbox center both axes) and set a page background'));
+    console.log(chalk.dim('       color that matches where the component normally appears (e.g. white for light UIs).'));
+    console.log(chalk.dim('    4. Wait 2 seconds for HMR, then register + capture each scenario:'));
+    console.log(chalk.dim(`       codeyam editor register '{"name":"ComponentName - Scenario",`));
+    console.log(chalk.dim(`         "componentName":"ComponentName","componentPath":"path/to/file.tsx",`));
+    console.log(chalk.dim(`         "url":"/codeyam-isolate/ComponentName?s=Scenario",`));
+    console.log(chalk.dim(`         "mockData":{"routes":{"/api/...":{"body":[...]}}}}'`));
+    console.log(chalk.dim('       url is a PATH (starts with /) — the proxy routes it and intercepts API calls'));
+    console.log(chalk.dim('       mockData.routes provides data for API calls the component makes internally'));
+    console.log(chalk.dim('       (omit mockData if the component has no internal API calls)'));
+    console.log(chalk.yellow('    5. IMPORTANT: Check the register response for `clientErrors` array'));
+    console.log(chalk.yellow('       If clientErrors is non-empty → fix the isolation route and re-register'));
+    console.log(chalk.yellow('       Fix client errors and re-register before moving on'));
+    console.log(chalk.dim('    Isolation routes stay in the project (in .gitignore) so the editor preview can display them'));
+    console.log();
+    console.log(chalk.bold('Library Functions — run tests:'));
+    checkbox('Run ALL test files created in step 5');
+    console.log(chalk.dim('    Example: npx vitest run app/lib/drinks.test.ts'));
+    checkbox('Verify every test passes');
+    checkbox('If any test fails, fix the source code and re-run');
+    console.log();
+    console.log(chalk.dim('Do not proceed until both component isolations and library tests pass.'));
+    console.log();
+    checkbox('Run `codeyam editor audit` to verify all components have scenarios and all functions have tests');
+    stopGate(7);
+}
+// ─── 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: 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('After each registration, check the response for `clientErrors`');
+    console.log(chalk.yellow('    If clientErrors is non-empty → fix the issue and re-register the scenario'));
+    console.log(chalk.yellow('    Fix client errors and re-register before moving on'));
+    console.log();
+    console.log(chalk.dim('Focus on creating and registering app-level scenarios. Code fixes happen in step 10 if needed.'));
+    stopGate(8);
+}
+// ─── Step 9: User Scenarios ───────────────────────────────────────────
+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: 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):');
+    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'));
+    console.log(chalk.yellow('    Fix client errors and re-register before moving on'));
+    console.log();
+    console.log(chalk.bold('If the app has NO users:'));
+    console.log(chalk.dim('  Skip this step and proceed to step 10 (Verify).'));
+    console.log();
+    console.log(chalk.dim('Focus on creating user-persona scenarios (or skip if no users). Code fixes happen in step 10 if needed.'));
+    stopGate(9);
+}
+// ─── Step 10: Verify ──────────────────────────────────────────────────
+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: 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:'));
+    checkbox('Review component screenshots in the App tab (grouped under Components)');
+    checkbox('If any screenshot looks wrong, fix the component code');
+    console.log(chalk.yellow('    After fixing a visual component, re-register the affected scenarios:'));
+    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('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\``);
+    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');
+    console.log();
+    console.log(chalk.bold('Library functions — test check:'));
+    checkbox('Re-run all test files from step 5 to confirm they still pass');
+    console.log(chalk.dim('    Example: npx vitest run app/lib/drinks.test.ts'));
+    checkbox('If any test fails, fix the source code and re-run');
+    console.log();
+    console.log(chalk.dim('Focus on fixing issues. All component screenshots, scenarios, and tests must be clean before proceeding.'));
+    stopGate(10);
+}
+// ─── 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: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
+    });
+    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('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('    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>","includeSessionScenarios":true}'`));
+    console.log();
+    console.log(chalk.dim('Focus on creating or updating the journal entry. Summary and review happen in step 12.'));
+    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 everything, then present the scenario table to the user.');
+    console.log();
+    console.log(chalk.bold('Phase 1 — Verify (do all of this silently):'));
+    checkbox(`Refresh the preview: \`curl -s -X POST http://localhost:${port}/api/dev-mode-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: \`curl -s http://localhost:${port}/api/editor-client-errors\``);
+    checkbox('If `hasErrors` is true, fix them and re-capture affected scenarios');
+    checkbox('Run `codeyam editor audit` to verify completeness of scenarios and tests');
+    checkbox('Do not proceed until all checks pass');
+    console.log();
+    console.log(chalk.bold('Phase 2 — Present to the user:'));
+    checkbox('Write a 1-2 sentence summary of what was built');
+    checkbox('Report test count and audit status (one line)');
+    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/dev-mode-preview \\`));
+    console.log(chalk.dim(`      -H 'Content-Type: application/json' -d '{"scenarioSlug":"...","scenarioId":"..."}'`));
+    checkbox(`Show the results panel: \`curl -s -X POST http://localhost:${port}/api/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.'));
+    console.log();
+    console.log(chalk.bold('Phase 3 — Present a selection menu to the user (use AskUserQuestion):'));
+    console.log(chalk.green('    "Save & commit"') +
+        chalk.dim(' — git commit all changes and record in journal'));
+    console.log(chalk.yellow('    "I\'d like to make some changes"') +
+        chalk.dim(' — describe changes, then re-verify'));
+    console.log();
+    console.log(chalk.bold('If the user chooses "Save & commit":'));
+    checkbox(`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>"}'\``);
+    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>"}'\``);
+    console.log(chalk.green('  Then run: ') +
+        chalk.bold('codeyam editor 1') +
+        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 change "${feature}"`) +
+        chalk.yellow(' — this prints a post-change checklist to re-register scenarios,'));
+    console.log(chalk.yellow('  re-run tests, update journal screenshots, and loop back to this review step.'));
+    console.log(chalk.red.bold('  IMPORTANT: You MUST run the change command. Do not skip this or try to re-verify manually.'));
+    console.log();
+    console.log(chalk.dim('Complete all phases in order: summary, screenshot verification, user menu.'));
+    stopGate(12, { confirm: true });
+}
+// ─── Command definition ───────────────────────────────────────────────
+// ─── Analyze-imports subcommand ────────────────────────────────────────
+/**
+ * `codeyam editor analyze-imports`
+ *
+ * Runs data-structure-only analysis for all glossary entities, then outputs
+ * an import graph and entity data structures as JSON to stdout.
+ */
+async function handleAnalyzeImports() {
+    const root = getProjectRoot();
+    // Read glossary
+    const glossaryPath = path.join(root, '.codeyam', 'glossary.json');
+    if (!fs.existsSync(glossaryPath)) {
+        console.error(chalk.red('Error: .codeyam/glossary.json not found.'));
+        console.error(chalk.dim('  Run codeyam editor 6 to create the glossary first.'));
+        process.exit(1);
+    }
+    let glossaryEntries;
+    try {
+        glossaryEntries = JSON.parse(fs.readFileSync(glossaryPath, 'utf8'));
+    }
+    catch {
+        console.error(chalk.red('Error: Could not parse .codeyam/glossary.json.'));
+        process.exit(1);
+    }
+    if (!Array.isArray(glossaryEntries) || glossaryEntries.length === 0) {
+        console.error(chalk.red('Error: glossary.json is empty.'));
+        process.exit(1);
+    }
+    const filePaths = glossaryEntries.map((e) => e.filePath);
+    const entityNames = glossaryEntries.map((e) => e.name);
+    const progress = new ProgressReporter();
+    // Run data-structure-only analysis for all entities
+    progress.start('Running import analysis for all glossary entities...');
+    try {
+        await runAnalysisForEntities({
+            projectRoot: root,
+            filePaths,
+            entityNames,
+            progress,
+            onlyDataStructure: true,
+        });
+    }
+    catch (err) {
+        progress.fail('Analysis failed');
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(chalk.red(`Error: ${msg}`));
+        process.exit(1);
+    }
+    progress.succeed('Analysis complete');
+    // Load entities WITH metadata from database
+    progress.start('Loading entity metadata...');
+    await initializeEnvironment();
+    const entities = await loadEntities({});
+    if (!entities || entities.length === 0) {
+        progress.fail('No entities found in database');
+        process.exit(1);
+    }
+    // Deduplicate to latest versions
+    const latestByKey = new Map();
+    for (const entity of entities) {
+        const key = `${entity.name}::${entity.filePath}`;
+        const existing = latestByKey.get(key);
+        if (!existing ||
+            (entity.createdAt &&
+                existing.createdAt &&
+                entity.createdAt > existing.createdAt)) {
+            latestByKey.set(key, entity);
+        }
+    }
+    const entityNameSet = new Set(entityNames);
+    const latestEntities = [...latestByKey.values()].filter((e) => entityNameSet.has(e.name));
+    // Build import graph from importedExports metadata
+    const imports = {};
+    const entityData = {};
+    // Also load analyses for data structures
+    const entityShas = latestEntities.map((e) => e.sha);
+    const analyses = await loadAnalyses({ entityShas });
+    const analysisMap = new Map();
+    if (analyses) {
+        for (const a of analyses) {
+            if (!analysisMap.has(a.entitySha) ||
+                (a.createdAt &&
+                    (!analysisMap.get(a.entitySha).createdAt ||
+                        a.createdAt > analysisMap.get(a.entitySha).createdAt))) {
+                analysisMap.set(a.entitySha, a);
+            }
+        }
+    }
+    for (const entity of latestEntities) {
+        const importedExports = entity.metadata?.importedExports || [];
+        const importedNames = importedExports
+            .map((ie) => ie.name)
+            .filter((name) => entityNameSet.has(name));
+        if (importedNames.length > 0) {
+            imports[entity.name] = importedNames;
+        }
+        // Collect entity data with analysis data structures
+        const analysis = analysisMap.get(entity.sha);
+        const analysisMetadata = analysis?.metadata;
+        entityData[entity.name] = {
+            filePath: entity.filePath || '',
+            entityType: entity.entityType || 'visual',
+            dataForMocks: analysisMetadata?.scenariosDataStructure?.dataForMocks,
+            dependencySchemas: analysisMetadata?.mergedDataStructure?.dependencySchemas,
+        };
+    }
+    progress.succeed('Done');
+    // Output combined JSON
+    const output = { imports, entities: entityData };
+    console.log(JSON.stringify(output, null, 2));
+}
+// ─── Register subcommand ──────────────────────────────────────────────
+/**
+ * `codeyam editor register '{"name":"...","componentName":"...",...}'`
+ *
+ * Thin CLI wrapper around POST /api/editor-register-scenario.
+ * Auto-approved via `Bash(codeyam:*)` — no manual approval needed.
+ */
+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"}\''));
+        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)}`));
+        process.exit(1);
+    }
+    const port = getServerPort();
+    const url = `http://localhost:${port}/api/editor-register-scenario`;
+    try {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        const data = await res.json();
+        console.log(JSON.stringify(data, null, 2));
+        if (!res.ok) {
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.error(chalk.red(`Error: Could not reach editor server at ${url}`));
+        console.error(chalk.dim(`  ${msg}`));
+        console.error(chalk.dim('  Is the editor running? Start it with: codeyam editor'));
+        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 12 review.
+ */
+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('1. Re-register affected component scenarios:'));
+    checkbox('For each component you modified, re-register ALL its scenarios');
+    console.log(chalk.dim(`    codeyam editor register '{"name":"ComponentName - ScenarioName","description":"...","componentName":"ComponentName","componentPath":"app/components/ComponentName.tsx"}'`));
+    checkbox('For any NEW components, create isolation routes and register scenarios');
+    console.log();
+    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');
+    console.log();
+    console.log(chalk.bold('3. Re-capture app-level scenarios:'));
+    checkbox('If component changes affect app-level pages, re-register affected app scenarios');
+    checkbox(`Use \`codeyam editor dependents ComponentName\` to find what needs recapturing`);
+    console.log();
+    console.log(chalk.bold('4. Verify completeness:'));
+    checkbox(`Refresh the preview: \`curl -s -X POST http://localhost:${port}/api/dev-mode-preview\``);
+    checkbox(`Navigate to key pages to verify changes: \`curl -s -X POST http://localhost:${port}/api/dev-mode-preview -H 'Content-Type: application/json' -d '{"path":"/your-route"}'\``);
+    checkbox('Run `codeyam editor audit` — all checks must pass');
+    checkbox(`Check for client-side errors: \`curl -s http://localhost:${port}/api/editor-client-errors\``);
+    checkbox('Fix any errors, then re-register affected scenarios');
+    console.log();
+    console.log(chalk.bold('5. Update the journal:'));
+    checkbox(`Update journal entry with new screenshots: \`curl -s -X PATCH http://localhost:${port}/api/editor-journal-update -H 'Content-Type: application/json' -d '{"time":"<journal entry time>","description":"<updated>","includeSessionScenarios":true}'\``);
+    console.log(chalk.dim('    includeSessionScenarios refreshes ALL screenshots to reflect the changes'));
+    console.log();
+    console.log(chalk.bold.green('When all checks pass, run: ') +
+        chalk.bold(`codeyam editor 12`));
+    console.log(chalk.dim('  This re-enters the review step to present the updated summary to the user.'));
+    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('✗');
+            const count = c.status === 'ok'
+                ? chalk.dim(` (${c.scenarioCount} scenario${c.scenarioCount !== 1 ? 's' : ''})`)
+                : chalk.red(' — no scenarios registered');
+            console.log(`  ${icon} ${c.name}${count}`);
+        }
+        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('✗');
+            const detail = f.status === 'ok'
+                ? chalk.dim(` (${f.testFile})`)
+                : f.testFile
+                    ? chalk.red(` — test file missing: ${f.testFile}`)
+                    : chalk.red(' — no test file specified');
+            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.functionsMissing > 0) {
+            parts.push(`${summary.functionsMissing} function${summary.functionsMissing !== 1 ? 's' : ''} missing tests`);
+        }
+        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();
+}
+// ─── 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,
+    };
+    for (let step = 1; step <= 12; 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) => {
+        const stepDescription = IS_INTERNAL_BUILD
+            ? 'Step number (1-12) or subcommand (register, analyze-imports, dependents, audit, scenarios, change, debug)'
+            : 'Step number (1-12) or subcommand (register, analyze-imports, dependents, audit, scenarios, change)';
+        let builder = yargs
+            .positional('step', {
+            type: 'string',
+            describe: stepDescription,
+        })
+            .positional('json', {
+            type: 'string',
+            describe: 'JSON argument for register subcommand',
+        })
+            .option('feature', {
+            type: 'string',
+            describe: 'Feature name (required for step 2)',
+        });
+        if (IS_INTERNAL_BUILD) {
+            builder = builder
+                .option('target', {
+                type: 'string',
+                describe: 'Debug target (setup, overview, overview-with-state, step-1..step-12, 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();
+        // Subcommand: codeyam editor register '{"name":"..."}'
+        if (argv.step === 'register') {
+            await handleRegister(argv.json || '');
+            return;
+        }
+        // Subcommand: codeyam editor analyze-imports
+        if (argv.step === 'analyze-imports') {
+            await handleAnalyzeImports();
+            return;
+        }
+        // Subcommand: codeyam editor dependents <EntityName>
+        if (argv.step === 'dependents') {
+            await handleDependents(argv.json || '');
+            return;
+        }
+        // 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 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;
+        }
+        const step = argv.step ? parseInt(argv.step, 10) : undefined;
+        if (step != null && (isNaN(step) || step < 1 || step > 12)) {
+            console.error(chalk.red(`Error: Invalid step "${argv.step}". Must be 1-12.`));
+            process.exit(1);
+        }
+        if (step == null) {
+            // No step specified: setup or overview
+            if (!hasProject(root)) {
+                printSetup(root);
+            }
+            else {
+                const state = readState(root);
+                printCycleOverview(root, state);
+            }
+            return;
+        }
+        const state = readState(root);
+        switch (step) {
+            case 1: {
+                const feature = argv.feature || undefined;
+                printStep1(root, feature);
+                break;
+            }
+            case 2: {
+                const feature = argv.feature || state?.feature;
+                if (!feature) {
+                    console.error(chalk.red('Error: --feature "Feature Name" is required for step 2.'));
+                    console.error(chalk.dim('  Usage: codeyam editor 2 --feature "Drink Rating System"'));
+                    process.exit(1);
+                }
+                printStep2(root, feature);
+                break;
+            }
+            case 3:
+            case 4:
+            case 5:
+            case 6:
+            case 7:
+            case 8:
+            case 9:
+            case 10:
+            case 11:
+            case 12: {
+                const feature = argv.feature || state?.feature;
+                if (!feature) {
+                    console.error(chalk.red('Error: No feature in progress. Run codeyam editor 1 first.'));
+                    process.exit(1);
+                }
+                const stepFns = {
+                    3: printStep3,
+                    4: printStep4,
+                    5: printStep5,
+                    6: printStep6,
+                    7: printStep7,
+                    8: printStep8,
+                    9: printStep9,
+                    10: printStep10,
+                    11: printStep11,
+                    12: printStep12,
+                };
+                stepFns[step](root, feature);
+                break;
+            }
+        }
+    },
+};
+export default editorCommand;
+//# sourceMappingURL=editor.js.map