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

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

@@ -8,6 +8,15 @@ 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";
+import { startBackgroundServer } from "../utils/backgroundServer.js";
+import { installClaudeCodeSkills } from "../utils/install-skills.js";
+import { setupClaudeCodeSettings } from "../utils/setupClaudeCodeSettings.js";
+import { isAnalyzerFinalized, getAnalyzerTemplatePath, } from "../utils/analyzer.js";
+import { updateProjectMetadata } from "../../../packages/database/index.js";
+import { requireBranchAndProject, testEnvironment } from "../utils/database.js";
+import { getProjectRoot as getStateProjectRoot } from "../state.js";
+import { withoutSpinner, error as errorLog } from "../utils/progress.js";
+import initCommand from "./init.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const STEP_LABELS = {
@@ -23,6 +32,7 @@ const STEP_LABELS = {
     10: 'Verify',
     11: 'Journal',
     12: 'Review',
+    13: 'Present',
 };
 /**
  * Append a JSONL log entry to .codeyam/logs/editor-log.jsonl
@@ -122,13 +132,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 <= 12; 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)}`;
@@ -166,7 +176,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 < 12) {
+    if (current < 13) {
         console.log(chalk.green('When done, run: ') +
             chalk.bold(`codeyam editor ${current + 1}`));
     }
@@ -210,7 +220,8 @@ function printResumptionHeader(step) {
             `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`'],
+        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} ━━━`));
@@ -315,7 +326,7 @@ function parseDebugTargets(target) {
         }
         if (entry.startsWith('step-')) {
             const num = parseInt(entry.replace('step-', ''), 10);
-            if (!isNaN(num) && num >= 1 && num <= 12) {
+            if (!isNaN(num) && num >= 1 && num <= 13) {
                 valid.add(`step-${num}`);
                 continue;
             }
@@ -428,7 +439,7 @@ function printCycleOverview(root, state) {
             chalk.dim(' to start a new feature'));
     }
     else {
-        console.log('Each feature follows 12 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`);
@@ -441,7 +452,8 @@ function printCycleOverview(root, state) {
         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(`  ${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'));
     }
@@ -582,7 +594,8 @@ function printStep2(root, feature) {
         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\``);
+        checkbox(`Detect the new project: \`curl -s -X POST http://localhost:${port}/api/editor-refresh\``);
+        console.log(chalk.dim('    This re-detects webapps and auto-starts the dev server.'));
         console.log();
         console.log(chalk.bold('Build the feature:'));
     }
@@ -601,7 +614,7 @@ 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: extract <img> src URLs from the HTML, then `curl -I <url>` each one and confirm HTTP 200 (not 404/403)');
     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();
@@ -629,19 +642,16 @@ function printStep3(root, feature) {
     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(`Refresh the preview: \`curl -s -X POST http://localhost:${port}/api/dev-mode-preview\` — check 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:' +
+    console.log(chalk.bold.red('  Verify EVERY image loads (this is the #1 source of broken prototypes):'));
+    checkbox('Get the dev server URL: `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.'));
+        '/api/editor-dev-server` → use the `url` field');
+    checkbox("Curl each page's HTML and extract every `<img>` src URL");
+    checkbox('HTTP-fetch EVERY image URL: `curl -s -o /dev/null -w "%{http_code}" <url>` — each must return 200');
+    checkbox('Fix or remove any image that returns non-200 before continuing');
     console.log();
     console.log(chalk.bold('Then present to the user:'));
     checkbox('Summarize what was built (routes, components, data)');
@@ -952,13 +962,13 @@ 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: \`curl -s -X POST http://localhost:${port}/api/dev-mode-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\``);
     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: extract <img> src URLs from each page, `curl -s -o /dev/null -w "%{http_code}" <url>` each one — must return 200');
     console.log();
     console.log(chalk.bold('Library functions — test check:'));
     checkbox('Re-run all test files from step 5 to confirm they still pass');
@@ -995,12 +1005,13 @@ function printStep11(root, feature) {
     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:`);
+    checkbox(`Returning to step 11 (before commit) — 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(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 review happen in step 12.'));
+    console.log(chalk.dim('Focus on creating or updating the journal entry. Summary and presentation happen in step 13.'));
     stopGate(11);
 }
 // ─── Step 12: Review ──────────────────────────────────────────────────
@@ -1021,9 +1032,9 @@ function printStep12(root, feature) {
     if (isResuming) {
         printResumptionHeader(12);
     }
-    console.log('Verify everything, then present the scenario table to the user.');
+    console.log('Verify all screenshots and checks pass before presenting to the user.');
     console.log();
-    console.log(chalk.bold('Phase 1 — Verify (do all of this silently):'));
+    console.log(chalk.bold('Checklist (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`');
@@ -1031,42 +1042,62 @@ function printStep12(root, feature) {
     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');
+    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 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.bold('Checklist:'));
+    checkbox(`Fetch all scenarios: \`curl -s http://localhost:${port}/api/editor-scenarios\``);
+    checkbox('Pick the scenario that best showcases the feature (happy path, most visually complete)');
+    checkbox('Switch the preview to that scenario using its `id`:');
     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":"..."}'`));
+    console.log(chalk.dim(`      -H 'Content-Type: application/json' -d '{"scenarioId":"<id>"}'`));
     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.'));
+    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('Phase 3 — Present a selection menu to the user (use AskUserQuestion):'));
+    console.log(chalk.bold('Present a selection menu to the user (use AskUserQuestion):'));
     console.log(chalk.green('    "Save & commit"') +
         chalk.dim(' — git commit all changes and record in journal'));
     console.log(chalk.yellow('    "I\'d like to make some changes"') +
         chalk.dim(' — describe changes, then re-verify'));
     console.log();
     console.log(chalk.bold('If the user chooses "Save & commit":'));
+    checkbox(`Hide the results panel first: \`curl -s -X POST http://localhost:${port}/api/editor-hide-results\``);
     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.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 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 });
+    console.log(chalk.bold('If the user chooses "Make changes" (or asks for ANY change, even as a question):'));
+    checkbox(`Hide the results panel: \`curl -s -X POST http://localhost:${port}/api/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 ────────────────────────────────────────
@@ -1334,7 +1365,7 @@ async function handleDependents(entityName) {
  * 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.
+ * instructions that always loop back to step 13 present.
  */
 function handleChange(feature) {
     const root = getProjectRoot();
@@ -1357,6 +1388,9 @@ function handleChange(feature) {
     console.log();
     console.log('The user has requested changes. Follow this checklist after making them.');
     console.log();
+    console.log(chalk.bold('0. Close the results panel:'));
+    checkbox(`Hide results: \`curl -s -X POST http://localhost:${port}/api/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","description":"...","componentName":"ComponentName","componentPath":"app/components/ComponentName.tsx"}'`));
@@ -1378,13 +1412,13 @@ function handleChange(feature) {
     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(chalk.bold('5. Create a new journal entry for this change:'));
+    checkbox(`Create journal entry: \`curl -s -X POST http://localhost:${port}/api/editor-journal-entry -H 'Content-Type: application/json' -d '{"title":"...","type":"feature","description":"<describe what changed>","includeSessionScenarios":true}'\``);
+    console.log(chalk.dim('    Do NOT PATCH the previous entry — it is frozen after commit. Always POST a new one.'));
     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.'));
+        chalk.bold(`codeyam editor 13`));
+    console.log(chalk.dim('  This enters the present step to show the updated results to the user.'));
     console.log();
 }
 // ─── Audit subcommand ────────────────────────────────────────────────
@@ -1433,11 +1467,24 @@ async function handleAudit() {
         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');
+            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();
@@ -1456,6 +1503,12 @@ async function handleAudit() {
         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();
@@ -1611,8 +1664,9 @@ function handleEditorDebug(args) {
         10: printStep10,
         11: printStep11,
         12: printStep12,
+        13: printStep13,
     };
-    for (let step = 1; step <= 12; step++) {
+    for (let step = 1; step <= 13; step++) {
         const stepId = `step-${step}`;
         if (!wants(stepId))
             continue;
@@ -1691,8 +1745,8 @@ const editorCommand = {
     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)';
+            ? 'Step number (1-13) or subcommand (register, analyze-imports, dependents, audit, scenarios, change, debug)'
+            : 'Step number (1-13) or subcommand (register, analyze-imports, dependents, audit, scenarios, change)';
         let builder = yargs
             .positional('step', {
             type: 'string',
@@ -1705,12 +1759,18 @@ const editorCommand = {
             .option('feature', {
             type: 'string',
             describe: 'Feature name (required for step 2)',
+        })
+            .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-12, or comma-separated list)',
+                describe: 'Debug target (setup, overview, overview-with-state, step-1..step-13, or comma-separated list)',
             })
                 .option('resume', {
                 type: 'boolean',
@@ -1769,13 +1829,8 @@ const editorCommand = {
             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
+        // Subcommand: codeyam editor steps — show setup or cycle overview
+        if (argv.step === 'steps') {
             if (!hasProject(root)) {
                 printSetup(root);
             }
@@ -1785,6 +1840,137 @@ const editorCommand = {
             }
             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);
+                // `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: {
@@ -1811,7 +1997,8 @@ const editorCommand = {
             case 9:
             case 10:
             case 11:
-            case 12: {
+            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.'));
@@ -1828,6 +2015,7 @@ const editorCommand = {
                     10: printStep10,
                     11: printStep11,
                     12: printStep12,
+                    13: printStep13,
                 };
                 stepFns[step](root, feature);
                 break;