@codeyam/codeyam-cli 0.1.0-staging.5370992 → 0.1.0-staging.56e2dca

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

@@ -24,7 +24,9 @@ import { buildEditorApiRequest, callEditorApi, EDITOR_API_SUBCOMMANDS, } from ".
 import { parseRegisterArg } from "../utils/parseRegisterArg.js";
 import { classifyRegistrationResult } from "../utils/registerScenarioResult.js";
 import { sanitizeGlossaryEntries } from "../utils/editorLoaderHelpers.js";
+import { updateHandoffProgress } from "../utils/handoffContext.js";
 import { readMigrationState, writeMigrationState, advanceToNextPage, completePage, getMigrationResumeInfo, } from "../utils/editorMigration.js";
+import { getDisplayVersion } from "../utils/versionInfo.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const STEP_LABELS = {
@@ -227,6 +229,143 @@ function getTechStackContext(root) {
                 : 'FEATURE_PATTERNS.md',
     };
 }
+/**
+ * Returns a pre-populated tech stack for a given template ID.
+ * Written to .codeyam/config.json during `codeyam editor template`.
+ */
+function getTechStackForTemplate(templateId) {
+    switch (templateId) {
+        case 'nextjs-prisma-sqlite':
+            return {
+                languages: [
+                    {
+                        name: 'TypeScript',
+                        url: 'https://typescriptlang.org',
+                        description: 'Statically typed JavaScript superset',
+                        version: '5',
+                    },
+                ],
+                frameworks: [
+                    {
+                        name: 'Next.js',
+                        url: 'https://nextjs.org',
+                        description: 'Full-stack React framework with App Router, SSR, and API routes',
+                        version: '15',
+                    },
+                    {
+                        name: 'React',
+                        url: 'https://react.dev',
+                        description: 'Component-based UI library',
+                        version: '19',
+                    },
+                ],
+                databases: [
+                    {
+                        name: 'SQLite',
+                        url: 'https://sqlite.org',
+                        description: 'Embedded relational database — zero config, upgradeable to hosted DB',
+                    },
+                ],
+                libraries: [
+                    {
+                        name: 'Prisma',
+                        url: 'https://prisma.io',
+                        description: 'Type-safe database ORM and query builder',
+                        version: '7',
+                    },
+                    {
+                        name: 'Tailwind CSS',
+                        url: 'https://tailwindcss.com',
+                        description: 'Utility-first CSS framework',
+                        version: '4',
+                    },
+                ],
+            };
+        case 'chrome-extension-react':
+            return {
+                languages: [
+                    {
+                        name: 'TypeScript',
+                        url: 'https://typescriptlang.org',
+                        description: 'Statically typed JavaScript superset',
+                        version: '5',
+                    },
+                ],
+                frameworks: [
+                    {
+                        name: 'React',
+                        url: 'https://react.dev',
+                        description: 'Component-based UI library for the popup and options pages',
+                        version: '19',
+                    },
+                    {
+                        name: 'Vite',
+                        url: 'https://vite.dev',
+                        description: 'Fast build tool and dev server',
+                        version: '6',
+                    },
+                ],
+                libraries: [
+                    {
+                        name: 'Tailwind CSS',
+                        url: 'https://tailwindcss.com',
+                        description: 'Utility-first CSS framework',
+                        version: '4',
+                    },
+                ],
+                infrastructure: [
+                    {
+                        name: 'Chrome Manifest V3',
+                        url: 'https://developer.chrome.com/docs/extensions/develop/migrate/what-is-mv3',
+                        description: 'Extension platform with service workers, declarative APIs, and chrome.storage',
+                    },
+                ],
+            };
+        case 'expo-react-native':
+            return {
+                languages: [
+                    {
+                        name: 'TypeScript',
+                        url: 'https://typescriptlang.org',
+                        description: 'Statically typed JavaScript superset',
+                        version: '5',
+                    },
+                ],
+                frameworks: [
+                    {
+                        name: 'Expo',
+                        url: 'https://expo.dev',
+                        description: 'React Native development platform with managed workflow and OTA updates',
+                        version: 'SDK 54',
+                    },
+                    {
+                        name: 'React Native',
+                        url: 'https://reactnative.dev',
+                        description: 'Cross-platform mobile UI framework',
+                    },
+                    {
+                        name: 'Expo Router',
+                        url: 'https://docs.expo.dev/router/introduction/',
+                        description: 'File-based navigation for React Native apps',
+                    },
+                ],
+                libraries: [
+                    {
+                        name: 'NativeWind',
+                        url: 'https://www.nativewind.dev',
+                        description: 'Tailwind CSS for React Native',
+                    },
+                    {
+                        name: 'AsyncStorage',
+                        url: 'https://react-native-async-storage.github.io/async-storage/',
+                        description: 'Persistent key-value storage for React Native',
+                    },
+                ],
+            };
+        default:
+            return {};
+    }
+}
 /**
  * Print dimension guidance when the project has multiple screen sizes.
  * Tells Claude to pick the right dimension for the content being previewed
@@ -250,11 +389,63 @@ function checkbox(text) {
     const highlighted = text.replace(/`([^`]+)`/g, (_m, code) => chalk.cyan(code));
     console.log(`  ${chalk.dim('[ ]')} ${highlighted}`);
 }
+/**
+ * Print a checklist item for the handoff summary.
+ */
+function checkboxHandoff() {
+    checkbox('Update the handoff summary in `.codeyam/config.json` for the next session/AI: `codeyam editor handoff \'{"summary":"..."}\'`');
+}
+/**
+ * Print the handoff context from a previous session or AI provider.
+ * Prefers the auto-generated handoff-context.md over the raw config summary.
+ */
+function printHandoffContext(root) {
+    try {
+        // Check for auto-generated handoff context (richer, includes progress timeline)
+        const handoffContextPath = path.join(root, '.codeyam', 'handoff-context.md');
+        if (fs.existsSync(handoffContextPath)) {
+            const content = fs.readFileSync(handoffContextPath, 'utf8');
+            console.log();
+            console.log(chalk.bold.magenta('━━━ PROVIDER HANDOFF CONTEXT ━━━'));
+            console.log(chalk.magenta(content));
+            console.log(chalk.bold.magenta('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+            console.log();
+            return;
+        }
+        // Fall back to config.json handoff summary
+        const configPath = path.join(root, '.codeyam', 'config.json');
+        if (!fs.existsSync(configPath))
+            return;
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        const handoff = config.handoff;
+        if (!handoff || !handoff.summary)
+            return;
+        console.log();
+        console.log(chalk.bold.magenta(`━━━ HANDOFF FROM ${String(handoff.lastProvider || 'unknown').toUpperCase()} (Step ${handoff.lastStep || 'unknown'}) ━━━`));
+        console.log(chalk.magenta(handoff.summary));
+        if (handoff.lastUpdated) {
+            console.log(chalk.dim(`    Updated: ${handoff.lastUpdated}`));
+        }
+        console.log(chalk.bold.magenta('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+        console.log();
+    }
+    catch {
+        // Non-fatal
+    }
+}
 /**
  * Instructions for creating/updating .codeyam/data-structure.json.
  * Only prints creation instructions if the file doesn't exist yet.
  * If it exists, reminds Claude to update it if data models changed.
  */
+function printServiceRecordingReminder(port) {
+    console.log(chalk.bold('Third-party services:'));
+    checkbox('When integrating any external service (auth, email, payments, storage, telemetry), update the tech stack');
+    console.log(chalk.dim('    Include the service name, URL, description, and envKeys (environment variable names it requires).'));
+    console.log(chalk.dim(`    curl -s -X POST http://localhost:${port}/api/editor-project-info -H "Content-Type: application/json" \\`));
+    console.log(chalk.dim(`      -d '{"techStack": {"services": [{"name":"Stripe","url":"https://stripe.com","description":"Payments","envKeys":["STRIPE_SECRET_KEY","STRIPE_PUBLISHABLE_KEY"]}]}}'`));
+    console.log(chalk.dim('    This ensures the deploy roadmap tracks all services that need production credentials.'));
+}
 function printDataStructureInstructions() {
     const root = getProjectRoot();
     const dsPath = path.join(root, '.codeyam', 'data-structure.json');
@@ -305,6 +496,10 @@ function printAppScenarioInstructions(pageName, route) {
         console.log(chalk.dim('    Example: "Page - Full Data", "Page - Empty State", "Page - Error State"'));
     }
     console.log();
+    checkbox('Ensure every page file used in app scenarios has a glossary entry with its filePath:');
+    console.log(chalk.dim('    The register command validates pageFilePath against the glossary — add missing pages now.'));
+    console.log(chalk.dim('    Example: {"name":"CounterScreen","filePath":"app/(tabs)/index.tsx","type":"page","description":"Main counter page"}'));
+    console.log();
     checkbox('Register each scenario with type "application", the real page URL, and pageFilePath:');
     console.log(chalk.dim(`    codeyam editor register '{"name":"${pageName || 'Page'} - Full Data",`));
     console.log(chalk.dim(`      "type":"application","url":"${route || '/'}","pageFilePath":"src/path/to/Page.tsx",...}'`));
@@ -372,6 +567,12 @@ function printExtractionPlanInstructions() {
     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.red('THE DECOMPOSITION RULE: All code should do one thing.'));
+    console.log(chalk.yellow('  Code either contains logic OR brings together smaller pieces to form a coordinated whole.'));
+    console.log(chalk.yellow('  Every opportunity to extract code into a sensible function, helper, or sub-component MUST be taken.'));
+    console.log(chalk.yellow('  Then extract AGAIN from the extracted code — keep going until each piece does one clearly defined thing.'));
+    console.log(chalk.yellow('  This applies to ALL code: backend routes, business logic, frontend components, utilities — everything.'));
+    console.log();
     console.log(chalk.bold('Checklist:'));
     checkbox('Read `.codeyam/glossary.json` — note reusable functions/components');
     checkbox('Read EVERY file used by this page/feature');
@@ -382,6 +583,12 @@ function printExtractionPlanInstructions() {
     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(chalk.yellow('    Inline logic — backend AND frontend (MUST be extracted as named functions):'));
+    console.log(chalk.yellow('      conditionals/ternaries, computed/derived values, data transformations,'));
+    console.log(chalk.yellow('      string formatting/interpolation, array filtering/sorting/mapping callbacks,'));
+    console.log(chalk.yellow('      default value logic, null/undefined guards, date/number formatting,'));
+    console.log(chalk.yellow('      permission/role checks, status derivation (e.g. isOverdue(task)),'));
+    console.log(chalk.yellow('      request/response shaping, error message construction, config lookups'));
     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.'));
@@ -392,6 +599,15 @@ function printExtractionPlanInstructions() {
     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(chalk.yellow('    — How you will test it (key inputs/outputs and edge cases)'));
+    console.log(chalk.yellow('    — What logic inside it can be further extracted as a separate testable function'));
+    console.log();
+    console.log(chalk.bold.red('BEFORE FINALIZING THE PLAN:'));
+    console.log(chalk.yellow('    Re-read every file ONE MORE TIME. For each piece of code, ask:'));
+    console.log(chalk.yellow('    1. Does this do more than one thing? → Split it into pieces that each do one thing.'));
+    console.log(chalk.yellow('    2. Is there logic here that could be its own function with clear inputs/outputs? → Extract it.'));
+    console.log(chalk.yellow('    3. Can the extracted code itself be broken down further? → Keep extracting.'));
+    console.log(chalk.yellow('    If your plan has fewer functions than components, you probably missed extractable logic.'));
     console.log();
     console.log(chalk.dim('Present the numbered plan, then proceed to step 7 to execute it.'));
 }
@@ -402,9 +618,15 @@ function printExtractionPlanInstructions() {
 function printComponentCaptureInstructions(root) {
     const ctx = root ? getTechStackContext(root) : undefined;
     const isExpo = ctx?.isExpo ?? false;
-    checkbox('Create isolation route dirs: `codeyam editor isolate ComponentA ComponentB ...`');
-    console.log(chalk.dim(`    This creates app/isolated-components/layout.tsx (with production ${isExpo ? '__DEV__' : 'notFound()'} guard) and`));
-    console.log(chalk.dim('    a directory per component. List ALL components that need isolation routes.'));
+    checkbox('Set up isolation routes: `codeyam editor isolate ComponentA ComponentB ...`');
+    if (isExpo) {
+        console.log(chalk.dim('    This creates app/isolated-components/_layout.tsx (with __DEV__ guard).'));
+        console.log(chalk.dim('    You then create a flat .tsx file per component (NOT subdirectories — Expo Router uses flat files).'));
+    }
+    else {
+        console.log(chalk.dim(`    This creates app/isolated-components/layout.tsx (with notFound() guard) and`));
+        console.log(chalk.dim('    a directory per component. List ALL components that need isolation routes.'));
+    }
     checkbox('For each visual component:');
     console.log(chalk.dim('    1. Read the source AND find where it is used in the app to understand:'));
     console.log(chalk.dim('       — Props/interface'));
@@ -805,8 +1027,8 @@ function printSetup(root) {
     console.log(chalk.bold('Tech Stack Selection:'));
     console.log(chalk.dim('  Based on the selected formats, present ONLY the matching tech stacks.'));
     console.log(chalk.dim('  A stack matches if ANY of the user\'s selected formats appears in its "Supports" list.'));
-    console.log(chalk.dim('  Show ALL matching stacks even if there is only one. Mark the recommended option.'));
-    console.log(chalk.dim('  Use AskUserQuestion to let the user pick one.'));
+    console.log(chalk.dim('  If only ONE stack matches, confirm it directly (e.g. "Expo + React Native is the only stack for mobile apps — using that.").'));
+    console.log(chalk.dim('  If MULTIPLE stacks match, use AskUserQuestion to let the user pick one.'));
     console.log();
     console.log(chalk.bold('  Available Tech Stacks:'));
     for (const stack of TECH_STACKS) {
@@ -998,6 +1220,15 @@ function printStep1(root, feature, options, userPrompt) {
     console.log(chalk.dim('    -H "Content-Type: application/json" \\'));
     console.log(chalk.dim('    -d \'{"projectTitle":"My App","projectDescription":"A short description of what this app does"}\''));
     console.log();
+    checkbox('Detect and set the project tech stack:');
+    console.log(chalk.dim('  Scan package.json, framework configs (.env, .env.example, tsconfig.json, next.config.*, prisma/schema.prisma, etc.)'));
+    console.log(chalk.dim('  to detect languages, frameworks, databases, services, libraries, and infrastructure.'));
+    console.log(chalk.dim('  Each item MUST have name, url, and description. version and envKeys are optional.'));
+    console.log(chalk.dim(`  curl -s -X POST http://localhost:${port}/api/editor-project-info \\`));
+    console.log(chalk.dim('    -H "Content-Type: application/json" \\'));
+    console.log(chalk.dim('    -d \'{"techStack":{"languages":[{"name":"TypeScript","url":"https://typescriptlang.org","description":"Statically typed JavaScript superset","version":"5"}],"frameworks":[{"name":"Next.js","url":"https://nextjs.org","description":"Full-stack React framework with SSR and API routes","version":"15"}],"databases":[{"name":"SQLite","url":"https://sqlite.org","description":"Embedded relational database"}],"services":[{"name":"Stripe","url":"https://stripe.com","description":"Payment processing and billing","envKeys":["STRIPE_SECRET_KEY"]}],"libraries":[{"name":"Prisma","url":"https://prisma.io","description":"Type-safe database ORM","version":"7"}],"infrastructure":[]}}\''));
+    console.log(chalk.dim('  Replace the example values with what you detect in this project. Omit empty categories.'));
+    console.log();
     const designSystem = readDesignSystem(root);
     if (designSystem) {
         console.log(chalk.bold.magenta('Design System (from .codeyam/design-system.md):'));
@@ -1011,6 +1242,8 @@ function printStep1(root, feature, options, userPrompt) {
     console.log(chalk.yellow('    Option 2 label: "I\'d like some changes"') +
         chalk.dim(' — user describes changes, you revise the plan, then re-present'));
     console.log();
+    checkboxHandoff();
+    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 ━━━'));
@@ -1075,6 +1308,21 @@ function printStep2(root, feature) {
             console.log();
             console.log(chalk.dim('  Read MOBILE_SETUP.md for data storage, navigation, and testing patterns.'));
             console.log();
+            checkbox('Ask the user what to name the app (use AskUserQuestion), then update app.json');
+            console.log(chalk.dim('  Update name, slug, scheme, ios.bundleIdentifier (com.codeyam.<slug>), and android.package'));
+            console.log(chalk.dim('  Also set the projectTitle via: curl -s -X POST http://localhost:' +
+                port +
+                '/api/editor-project-info -H "Content-Type: application/json" -d \'{"projectTitle":"<name>"}\''));
+            console.log();
+            checkbox('Generate an app icon using `sharp`');
+            console.log(chalk.dim('  Create `scripts/generate-icon.mjs` and `mkdir -p assets`'));
+            console.log(chalk.yellow('  ICON DESIGN GOAL: The icon must look distinctive on a home screen full of other app icons.'));
+            console.log(chalk.yellow('  Use multiple bold colors from the design system and complex, overlapping shapes.'));
+            console.log(chalk.yellow('  NO simple/minimal icons — no single glyph on a flat background, no plain text, no basic circles.'));
+            console.log(chalk.yellow('  Make it colorful, layered, and dense. Use gradients, multiple contrasting fills, and depth.'));
+            console.log(chalk.dim('  Use sharp to render SVG to 1024x1024 PNG. iOS: flatten onto background (no alpha channel).'));
+            console.log(chalk.dim('  Generate: icon.png, adaptive-icon.png, favicon.png (48x48). Run `node scripts/generate-icon.mjs`'));
+            console.log();
         }
         else if (ctx.isChromeExt) {
             // Chrome Extension: use chrome.storage
@@ -1123,6 +1371,10 @@ function printStep2(root, feature) {
         console.log();
         printDataStructureInstructions();
     }
+    console.log();
+    printServiceRecordingReminder(port);
+    console.log();
+    checkboxHandoff();
     stopGate(2);
 }
 // ─── Step 3: Prototype ────────────────────────────────────────────────
@@ -1209,6 +1461,10 @@ function printStep3(root, feature) {
             console.log(chalk.dim('    Bad:  color: "#333", fontSize: 14, padding: 12'));
             console.log(chalk.dim('    Good: color: theme.colors.textPrimary, fontSize: theme.fontSize.sm, padding: theme.spacing.md'));
             console.log(chalk.dim('    Do NOT use CSS custom properties (var(--token)) — they do not work in React Native.'));
+            checkbox('Buttons: put backgroundColor, borderRadius, borderStyle on a wrapping <View>, NOT on <Pressable>');
+            console.log(chalk.dim('    Pressable renders these styles on web but FAILS SILENTLY on native devices.'));
+            console.log(chalk.dim('    Use a <View> with overflow:"hidden" for the visual shell, <Pressable> inside for touch only.'));
+            console.log(chalk.dim('    For press feedback: use onPressIn/onPressOut + useState to toggle opacity, not function-style style.'));
         }
         else {
             checkbox('Define ALL design tokens as CSS custom properties in globals.css — not just colors');
@@ -1235,6 +1491,9 @@ function printStep3(root, feature) {
     console.log(chalk.red.bold('  NEVER claim "you should see X" or "the preview shows X" unless you just ran a preview command.'));
     console.log(chalk.red('  The preview only updates when you explicitly refresh it. Verify, then describe.'));
     console.log();
+    printServiceRecordingReminder(port);
+    console.log();
+    checkboxHandoff();
     stopGate(3);
 }
 // ─── Step 4: Verify Prototype ─────────────────────────────────────────
@@ -1249,6 +1508,8 @@ function printStep4(root, feature) {
         label: STEP_LABELS[4],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
     logEvent(root, 'step', { step: 4, label: 'Verify Prototype', feature });
     stepHeader(4, 'Verify Prototype', feature);
@@ -1290,6 +1551,8 @@ function printStep4(root, feature) {
     console.log(chalk.dim('    A new clone should work with just: git clone → npm run setup → npm run dev'));
     console.log();
     console.log(chalk.dim('Focus on building the prototype. Scenarios and refactoring happen in later steps.'));
+    console.log();
+    checkboxHandoff();
     stopGate(4);
 }
 // ─── Step 5: Confirm ──────────────────────────────────────────────────
@@ -1305,6 +1568,8 @@ function printStep5(root, feature) {
         label: STEP_LABELS[5],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
     logEvent(root, 'step', { step: 5, label: 'Confirm', feature });
     stepHeader(5, 'Confirm', feature);
@@ -1351,6 +1616,8 @@ function printStep5(root, feature) {
         chalk.dim(' — make changes, refresh preview, re-run `codeyam editor 5`'));
     console.log();
     console.log(chalk.dim('Wait for user approval before moving on. Refactoring and scenarios happen in later steps.'));
+    console.log();
+    checkboxHandoff();
     stopGate(5, { confirm: true });
 }
 // ─── Step 6: Deconstruct ──────────────────────────────────────────────
@@ -1364,6 +1631,8 @@ function printStep6(root, feature) {
         label: STEP_LABELS[6],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
     logEvent(root, 'step', { step: 6, label: 'Deconstruct', feature });
     stepHeader(6, 'Deconstruct', feature);
@@ -1374,6 +1643,8 @@ function printStep6(root, feature) {
     console.log(chalk.yellow('This step is read and plan only. Code extraction happens in step 7.'));
     console.log();
     printExtractionPlanInstructions();
+    console.log();
+    checkboxHandoff();
     stopGate(6);
 }
 // ─── Step 7: Extract ──────────────────────────────────────────────────
@@ -1389,6 +1660,8 @@ function printStep7(root, feature) {
         label: STEP_LABELS[7],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
     logEvent(root, 'step', { step: 7, label: 'Extract', feature });
     stepHeader(7, 'Extract', feature);
@@ -1408,7 +1681,11 @@ function printStep7(root, feature) {
     checkbox('For each function/hook: write MULTIPLE failing tests FIRST, then extract to make them pass');
     console.log(chalk.dim('    Cover: typical inputs, edge cases, empty/null inputs, error conditions'));
     console.log(chalk.dim('    Aim for 3-8 test cases per function depending on complexity'));
+    console.log(chalk.dim('    EVERY conditional branch in the function MUST have a test that exercises it'));
+    console.log(chalk.dim('    EVERY return path MUST be tested — if a function can return 3 different things, write 3+ tests'));
+    console.log(chalk.dim('    Boundary values: 0, 1, -1, empty string, empty array, undefined, null'));
     console.log(chalk.dim('    Hooks count as functions — useDrinks, useAuth, etc. all need test files'));
+    console.log(chalk.dim('    Wrap all tests in a describe("FunctionName", ...) block — the audit matches on this name'));
     if (ctx.isExpo) {
         checkbox('Place test files next to source but OUTSIDE `app/` (Expo Router treats all files in app/ as routes): `lib/storage.ts` → `lib/storage.test.ts`, `app/hooks/useCounter.ts` → `__tests__/hooks/useCounter.test.ts`');
     }
@@ -1423,6 +1700,23 @@ function printStep7(root, feature) {
     console.log(chalk.yellow(`    Check: does any file contain raw ${ctx.rawPrimitivesList}?`));
     console.log(chalk.yellow('    If yes → that JSX section is a component waiting to be extracted.'));
     console.log();
+    console.log(chalk.bold('Decomposition pass (backend AND frontend):'));
+    checkbox('Re-read EVERY file you created or modified. For each, extract a function/helper/sub-component for:');
+    console.log(chalk.yellow('    — Conditionals (e.g. `isOverdue ? "red" : "green"` → `getStatusColor(date)`)'));
+    console.log(chalk.yellow('    — Computed values (e.g. `items.filter(...).length` → `countActiveItems(items)`)'));
+    console.log(chalk.yellow('    — Formatting (e.g. `${price.toFixed(2)}` → `formatPrice(price)`)'));
+    console.log(chalk.yellow('    — Data transforms, validation, request/response shaping'));
+    console.log(chalk.yellow('    — Anything doing more than one thing → split until each piece does one clearly defined thing'));
+    checkbox('Then look at what you just extracted — can IT be broken down further? Keep going.');
+    checkbox('Write tests for every extracted function (same TDD: failing tests FIRST)');
+    console.log();
+    console.log(chalk.bold.red('TEST QUALITY SELF-CHECK (before proceeding):'));
+    checkbox('For EACH test file: count the test cases. Fewer than 3 tests for any function is a red flag.');
+    checkbox('For EACH tested function: read the function, count the conditional branches. Every branch MUST have a test.');
+    checkbox('For EACH tested function: verify you test at least one error/edge case, not just happy paths.');
+    console.log(chalk.yellow('    If a function has an if/else, switch, or ternary — each path needs its own test case.'));
+    console.log(chalk.yellow('    If a function handles null/undefined/empty — test those inputs explicitly.'));
+    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 ${ctx.isExpo ? 'React Native primitives' : 'HTML tags'}`);
@@ -1433,6 +1727,8 @@ function printStep7(root, feature) {
     console.log(chalk.dim('Reuse glossary functions when they fit naturally. Extract a new function when the use case diverges.'));
     console.log();
     console.log(chalk.dim('Focus on TDD for functions and extraction for components. Scenarios come in later steps.'));
+    console.log();
+    checkboxHandoff();
     stopGate(7);
 }
 // ─── Step 8: Glossary ─────────────────────────────────────────────────
@@ -1446,6 +1742,8 @@ function printStep8(root, feature) {
         label: STEP_LABELS[8],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
     logEvent(root, 'step', { step: 8, label: 'Glossary', feature });
     stepHeader(8, 'Glossary', feature);
@@ -1472,6 +1770,8 @@ function printStep9(root, feature) {
         label: STEP_LABELS[9],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
     logEvent(root, 'step', { step: 9, label: 'Analyze', feature });
     stepHeader(9, 'Analyze and Verify', feature);
@@ -1497,6 +1797,15 @@ function printStep9(root, feature) {
     console.log();
     console.log(chalk.dim('Do not proceed until both component isolations and library tests pass.'));
     console.log();
+    console.log(chalk.bold.red('DECOMPOSITION & COVERAGE REVIEW (before running audit):'));
+    checkbox('Re-read every file. Extract any logic that could be its own function/helper/sub-component.');
+    console.log(chalk.yellow('    Code either contains logic OR brings together smaller pieces.'));
+    console.log(chalk.yellow('    Keep extracting until each piece does one clearly defined thing.'));
+    console.log(chalk.yellow('    For each extraction: write failing test first, then extract, then make test pass.'));
+    checkbox('Open each test file and verify: ≥3 test cases per function, happy path + edge case + error case');
+    checkbox('If any function has fewer tests than conditional branches, add the missing tests NOW');
+    checkbox('Update `.codeyam/glossary.json` with any new functions before running audit');
+    console.log();
     checkbox('Run `codeyam editor audit` to verify all components have scenarios and all functions/hooks have tests');
     console.log(chalk.red.bold('    The audit is a HARD GATE — step 10 will refuse to run until the audit passes.'));
     console.log(chalk.dim('    The audit auto-fixes incomplete entities by running targeted analysis on just the affected files.'));
@@ -1522,6 +1831,8 @@ function printStep10(root, feature) {
         label: STEP_LABELS[10],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
     logEvent(root, 'step', { step: 10, label: 'App Scenarios', feature });
     stepHeader(10, 'App Scenarios', feature);
@@ -1586,6 +1897,8 @@ function printStep11(root, feature) {
         label: STEP_LABELS[11],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
     logEvent(root, 'step', { step: 11, label: 'User Scenarios', feature });
     stepHeader(11, 'User Scenarios', feature);
@@ -1632,6 +1945,8 @@ function printStep12(root, feature) {
         label: STEP_LABELS[12],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
     logEvent(root, 'step', { step: 12, label: 'Verify', feature });
     stepHeader(12, 'Verify', feature);
@@ -1678,6 +1993,8 @@ function printStep13(root, feature) {
         label: STEP_LABELS[13],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
     logEvent(root, 'step', { step: 13, label: 'Journal', feature });
     stepHeader(13, 'Journal', feature);
@@ -1711,6 +2028,8 @@ function printStep14(root, feature) {
         label: STEP_LABELS[14],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
     logEvent(root, 'step', { step: 14, label: 'Review', feature });
     stepHeader(14, 'Review', feature);
@@ -1730,6 +2049,8 @@ function printStep14(root, feature) {
     checkbox('Fix or remove any broken images before continuing');
     checkbox('Recapture stale scenarios: `codeyam editor recapture-stale`');
     checkbox('Run `codeyam editor audit` to verify completeness of scenarios and tests');
+    checkbox('Verify tech stack is up to date: check for any new service imports (e.g. Stripe, Resend, Supabase) and ensure they appear in the tech stack with `envKeys`');
+    console.log(chalk.dim(`    Update via: curl -s -X POST http://localhost:${port}/api/editor-project-info -H "Content-Type: application/json" -d '{"techStack": {...}}'`));
     checkbox('Do not proceed until all checks pass');
     stopGate(14);
 }
@@ -1744,6 +2065,8 @@ function printStep15(root, feature) {
         label: STEP_LABELS[15],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
     logEvent(root, 'step', { step: 15, label: 'Present', feature });
     stepHeader(15, 'Present', feature);
@@ -2393,6 +2716,8 @@ function printStep16(root, feature) {
         label: STEP_LABELS[16],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
     logEvent(root, 'step', { step: 16, label: 'Commit', feature });
     stepHeader(16, 'Commit', feature);
@@ -2419,6 +2744,8 @@ function printStep17(root, feature) {
         label: STEP_LABELS[17],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
     logEvent(root, 'step', { step: 17, label: 'Finalize', feature });
     stepHeader(17, 'Finalize', feature);
@@ -2444,6 +2771,8 @@ function printStep18(root, feature) {
         label: STEP_LABELS[18],
         startedAt: isResuming ? prevState.startedAt : now,
         featureStartedAt: prevState?.featureStartedAt || now,
+        appFormats: prevState?.appFormats,
+        techStackId: prevState?.techStackId,
     });
     logEvent(root, 'step', { step: 18, label: 'Push', feature });
     stepHeader(18, 'Push', feature);
@@ -2461,11 +2790,11 @@ function printStep18(root, feature) {
     console.log(chalk.dim('    If the user wants help, guide them through `gh repo create` or manual GitHub setup, then push.'));
     console.log(chalk.dim('    Task management is handled by the ━━━ TASK ━━━ directive below.'));
     console.log();
-    console.log(chalk.bold.yellow('IMPORTANT: After this step, the current feature is DONE.'));
-    console.log(chalk.yellow('  Any new user request — even if it sounds related — is a NEW feature.'));
+    const port = getServerPort();
+    console.log(chalk.bold.yellow('IMPORTANT: After the push succeeds (or the user skips it), the feature is DONE.'));
+    console.log(chalk.yellow(`  Signal the UI by running: curl -s -X POST http://localhost:${port}/api/editor-feature-complete`));
+    console.log(chalk.yellow('  Then STOP and wait. Do NOT ask the user what to build next — the UI handles the transition.'));
     console.log(chalk.yellow('  Do NOT use `codeyam editor change` or start building directly.'));
-    console.log(chalk.yellow('  Ask the user what they want to build. Once they tell you, run `codeyam editor 1` yourself.'));
-    console.log(chalk.yellow('  NEVER tell the user to run `codeyam editor` commands — these are internal. Just ask what to build.'));
     console.log(chalk.yellow('  The change workflow is ONLY for modifications during steps 1-15, not after commit.'));
     stopGate(18, { confirm: true });
 }
@@ -2884,8 +3213,13 @@ function handleIsolate(componentNames) {
         process.exit(1);
     }
     const isolateDir = path.join(root, 'app', 'isolated-components');
-    // Create layout.tsx with production guard if missing
+    // Create the framework-appropriate layout guard if missing.
+    // Clean up wrong-framework layout from a previous CLI version.
     const layoutPath = path.join(isolateDir, ctx.isExpo ? '_layout.tsx' : 'layout.tsx');
+    const wrongLayoutPath = path.join(isolateDir, ctx.isExpo ? 'layout.tsx' : '_layout.tsx');
+    if (fs.existsSync(wrongLayoutPath)) {
+        fs.unlinkSync(wrongLayoutPath);
+    }
     if (!fs.existsSync(layoutPath)) {
         fs.mkdirSync(isolateDir, { recursive: true });
         if (ctx.isExpo) {
@@ -2938,7 +3272,13 @@ function handleIsolate(componentNames) {
         }
     }
     if (created.length > 0) {
-        console.log(chalk.green(`Created ${created.length} isolation route(s): ${created.join(', ')}`));
+        if (ctx.isExpo) {
+            console.log(chalk.green(`Ready for ${created.length} isolation route(s): ${created.map((n) => `app/isolated-components/${n}.tsx`).join(', ')}`));
+            console.log(chalk.dim('    Create each file with useLocalSearchParams, a scenarios map, and nativeID="codeyam-capture"'));
+        }
+        else {
+            console.log(chalk.green(`Created ${created.length} isolation route dir(s): ${created.join(', ')}`));
+        }
     }
     if (existed.length > 0) {
         console.log(chalk.dim(`Already existed: ${existed.join(', ')}`));
@@ -3079,6 +3419,50 @@ function formatApiSubcommandResult(subcommand, data) {
             return null; // journal-list, show/hide-results: keep full JSON
     }
 }
+/**
+ * `codeyam editor handoff '{"summary":"..."}'`
+ *
+ * Update the handoff summary in .codeyam/config.json for other AI providers.
+ */
+function handleHandoff(jsonArg) {
+    if (!jsonArg) {
+        console.error(chalk.red('Error: JSON argument required.'));
+        console.error(chalk.dim('  Usage: codeyam editor handoff \'{"summary":"Built the X component..."}\''));
+        process.exit(1);
+    }
+    let summary;
+    try {
+        const parsed = JSON.parse(jsonArg);
+        summary = parsed.summary;
+    }
+    catch {
+        console.error(chalk.red('Error: Invalid JSON.'));
+        process.exit(1);
+    }
+    if (!summary) {
+        console.error(chalk.red('Error: "summary" field is required.'));
+        process.exit(1);
+    }
+    const root = getProjectRoot();
+    const configPath = path.join(root, '.codeyam', 'config.json');
+    try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        const state = readState(root);
+        const provider = config.provider || 'claude';
+        config.handoff = {
+            summary,
+            lastProvider: provider,
+            lastStep: state?.step,
+            lastUpdated: new Date().toISOString(),
+        };
+        fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
+        console.log(chalk.green('✓ Handoff summary updated in .codeyam/config.json'));
+    }
+    catch (err) {
+        console.error(chalk.red(`Error: Could not update config.json: ${err.message}`));
+        process.exit(1);
+    }
+}
 /**
  * `codeyam editor register '{"name":"...","componentName":"...",...}'`
  *
@@ -3947,14 +4331,20 @@ async function handleAudit(options) {
             let detail;
             switch (f.status) {
                 case 'ok':
-                    detail = chalk.dim(` (${f.testFile})`);
+                    if (f.testCaseCount !== undefined && f.testCaseCount < 3) {
+                        detail = chalk.yellow(` (${f.testFile}) — ⚠ only ${f.testCaseCount} test case${f.testCaseCount !== 1 ? 's' : ''}, consider adding more`);
+                    }
+                    else {
+                        detail = chalk.dim(` (${f.testFile}${f.testCaseCount !== undefined ? `, ${f.testCaseCount} tests` : ''})`);
+                    }
                     break;
                 case 'runner_error':
                     detail = chalk.red(` — test runner crashed: ${f.testFile}`);
                     if (f.errorMessage) {
                         detail += `\n      ${chalk.red(f.errorMessage)}`;
                         detail += `\n      ${chalk.yellow('Note: This is NOT a test failure — the test runner itself could not execute.')}`;
-                        detail += `\n      ${chalk.yellow('Try running the test manually: npx vitest run ' + f.testFile)}`;
+                        const ctx = getTechStackContext(process.cwd());
+                        detail += `\n      ${chalk.yellow('Try running the test manually: ' + ctx.testRunCommand + ' ' + f.testFile)}`;
                     }
                     break;
                 case 'failing':
@@ -3979,6 +4369,9 @@ async function handleAudit(options) {
             }
             console.log(`  ${icon} ${f.name}${detail}`);
         }
+        if (summary.functionsThinCoverage > 0) {
+            console.log(chalk.yellow.bold(`  ⚠ ${summary.functionsThinCoverage} function${summary.functionsThinCoverage !== 1 ? 's' : ''} with thin test coverage (< 3 test cases). Add more tests to cover all branches.`));
+        }
         console.log();
     }
     // Missing from glossary
@@ -4552,6 +4945,10 @@ async function handleTemplate() {
             if (stack?.supportedFormats) {
                 config.appFormats = stack.supportedFormats;
             }
+            // Pre-populate tech stack from template
+            if (stack) {
+                config.techStack = getTechStackForTemplate(stack.id);
+            }
             // Set mobile-first defaults for mobile-app projects
             if (stack?.supportedFormats?.includes('mobile-app')) {
                 config.defaultScreenSize = {
@@ -5224,6 +5621,11 @@ const editorCommand = {
             }
             return;
         }
+        // Subcommand: codeyam editor handoff '{"summary":"..."}'
+        if (argv.step === 'handoff') {
+            await handleHandoff(argv.json || '');
+            return;
+        }
         // Subcommand: codeyam editor register '{"name":"..."}'
         if (argv.step === 'register') {
             await handleRegister(argv.json || '');
@@ -5406,10 +5808,18 @@ const editorCommand = {
             try {
                 const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
                 const { projectSlug } = config;
+                // Detect provider switch and inform the user
+                const handoff = config.handoff;
+                const currentProvider = config.provider || 'claude';
+                if (handoff?.lastProvider && handoff.lastProvider !== currentProvider) {
+                    console.log(chalk.yellow(`  Provider changed: ${handoff.lastProvider} → ${currentProvider}`));
+                    console.log(chalk.dim('  The editor will offer to continue with handoff context.'));
+                }
                 if (!projectSlug) {
                     errorLog('Missing project slug. Try reinitializing with: `codeyam editor template`');
                     return;
                 }
+                console.log(chalk.dim(`  CodeYam Editor v${getDisplayVersion()}`));
                 const connectionOk = await withoutSpinner(() => testEnvironment());
                 if (!connectionOk) {
                     errorLog('Environment validation failed');
@@ -5821,6 +6231,9 @@ const editorCommand = {
                 process.exit(1);
             }
         }
+        printHandoffContext(root);
+        // Track step progress automatically for provider handoff
+        updateHandoffProgress(root, step);
         switch (step) {
             case 1: {
                 const feature = argv.feature || undefined;