@codeyam/codeyam-cli 0.1.0-staging.39719f5 → 0.1.0-staging.3bf7045

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

@@ -13,6 +13,7 @@ import { installClaudeCodeSkills } from "../utils/install-skills.js";
 import { setupClaudeCodeSettings } from "../utils/setupClaudeCodeSettings.js";
 import { ensureAnalyzerFinalized, } from "../utils/analyzerFinalization.js";
 import { APP_FORMATS, TECH_STACKS } from "../data/techStacks.js";
+import { DESIGN_SYSTEMS } from "../data/designSystems.js";
 import { getProjectRoot as getStateProjectRoot } from "../state.js";
 import initCommand from "./init.js";
 import { scanScenarioFiles, syncScenarioFilesToDatabase, backfillScenarioMetadata, migrateScenarioFormats, } from "../utils/scenariosManifest.js";
@@ -23,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 = {
@@ -188,6 +191,181 @@ function getProjectDimensions(root) {
         return { defaultName: 'Desktop', names: [] };
     }
 }
+function getTechStackContext(root) {
+    const state = readState(root);
+    const techStackId = state?.techStackId || '';
+    const stack = TECH_STACKS.find((s) => s.id === techStackId);
+    const isExpo = techStackId === 'expo-react-native';
+    const isChromeExt = techStackId === 'chrome-extension-react';
+    const isNextjs = techStackId.startsWith('nextjs-') || (!isExpo && !isChromeExt);
+    return {
+        id: techStackId || 'nextjs-prisma-sqlite',
+        isExpo,
+        isNextjs,
+        isChromeExt,
+        hasDatabase: isNextjs,
+        testRunner: isNextjs ? 'vitest' : 'jest',
+        testRunCommand: isNextjs ? 'npx vitest run' : 'npx jest',
+        storageType: isExpo
+            ? 'asyncStorage'
+            : isChromeExt
+                ? 'chromeStorage'
+                : 'prisma',
+        routerImport: isExpo
+            ? 'expo-router'
+            : isChromeExt
+                ? 'react-router-dom'
+                : 'next/navigation',
+        componentPrimitives: isExpo
+            ? '<View>, <Text>, <ScrollView>'
+            : '<div>, <span>, <h1>',
+        rawPrimitivesList: isExpo
+            ? '<View>, <Text>, <Image>, <ScrollView>, <FlatList>'
+            : '<div>, <span>, <h1>, <p>, <img>, <ul>',
+        patternsFile: isExpo
+            ? 'MOBILE_SETUP.md'
+            : isChromeExt
+                ? 'EXTENSION_SETUP.md'
+                : 'FEATURE_PATTERNS.md',
+    };
+}
+/**
+ * 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
@@ -211,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');
@@ -266,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",...}'`));
@@ -280,7 +514,12 @@ function printAppScenarioInstructions(pageName, route) {
         console.log(chalk.dim('    For external APIs: also add "externalApis":{"GET https://...":{"body":[...],"status":200}}'));
     }
     else {
+        const appCtx = getTechStackContext(root);
         checkbox('Include data in every app scenario — without it the page will be empty:');
+        if (appCtx.isExpo) {
+            console.log(chalk.dim('    Use "localStorage":{"items":"[...]"} to pre-populate AsyncStorage (values are JSON strings)'));
+            console.log(chalk.dim("    AsyncStorage uses localStorage on web — CodeYam's injection works automatically."));
+        }
         console.log(chalk.dim('    Use "mockData":{"routes":{"/api/...":{"body":[...]}}} to mock API responses'));
         console.log(chalk.dim('    For external APIs: add "externalApis":{"GET https://...":{"body":[...],"status":200}}'));
     }
@@ -328,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');
@@ -338,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.'));
@@ -348,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.'));
 }
@@ -355,10 +615,18 @@ function printExtractionPlanInstructions() {
  * Shared component capture instructions used by editor Step 7 and migration Steps 3/8.
  * Prints the full isolation route setup, codeyam-capture wrapper, register command, and error checking.
  */
-function printComponentCaptureInstructions() {
-    checkbox('Create isolation route dirs: `codeyam editor isolate ComponentA ComponentB ...`');
-    console.log(chalk.dim('    This creates app/isolated-components/layout.tsx (with production notFound() guard) and'));
-    console.log(chalk.dim('    a directory per component. List ALL components that need isolation routes.'));
+function printComponentCaptureInstructions(root) {
+    const ctx = root ? getTechStackContext(root) : undefined;
+    const isExpo = ctx?.isExpo ?? false;
+    checkbox('Set up isolation routes: `codeyam editor isolate ComponentA ComponentB ...`');
+    if (isExpo) {
+        console.log(chalk.dim('    This creates app/isolated-components/_layout.tsx (with __DEV__ guard).'));
+        console.log(chalk.dim('    You then create a flat .tsx file per component (NOT subdirectories — Expo Router uses flat files).'));
+    }
+    else {
+        console.log(chalk.dim(`    This creates app/isolated-components/layout.tsx (with notFound() guard) and`));
+        console.log(chalk.dim('    a directory per component. List ALL components that need isolation routes.'));
+    }
     checkbox('For each visual component:');
     console.log(chalk.dim('    1. Read the source AND find where it is used in the app to understand:'));
     console.log(chalk.dim('       — Props/interface'));
@@ -369,14 +637,28 @@ function printComponentCaptureInstructions() {
     console.log(chalk.dim('       — Different visual states: loading, error, disabled, selected, hover'));
     console.log(chalk.dim('       — Boundary values: single item vs many, min/max ratings, very long names'));
     console.log(chalk.dim('    3. Create ONE isolation route per component with a scenarios map and ?s= query param:'));
-    console.log(chalk.dim('       Remix:   app/routes/isolated-components.ComponentName.tsx → /isolated-components/ComponentName'));
-    console.log(chalk.dim('       Next.js: app/isolated-components/ComponentName/page.tsx → /isolated-components/ComponentName'));
+    if (isExpo) {
+        console.log(chalk.dim('       Expo:    app/isolated-components/ComponentName.tsx → /isolated-components/ComponentName'));
+        console.log(chalk.dim('       Use useLocalSearchParams() from expo-router to read ?s=ScenarioName.'));
+    }
+    else {
+        console.log(chalk.dim('       Remix:   app/routes/isolated-components.ComponentName.tsx → /isolated-components/ComponentName'));
+        console.log(chalk.dim('       Next.js: app/isolated-components/ComponentName/page.tsx → /isolated-components/ComponentName'));
+    }
     console.log(chalk.dim('       The route defines a `scenarios` object mapping scenario names to props,'));
     console.log(chalk.dim('       reads `?s=ScenarioName` from the URL, and renders the component with those props.'));
-    console.log(chalk.dim('       Wrap the component in a capture container with id="codeyam-capture":'));
-    console.log(chalk.dim('       <div id="codeyam-capture" style={{ display:"inline-block" }}>'));
-    console.log(chalk.dim('         <div style={{ width:"100%", maxWidth:"..." }}> ← match the app\'s container width'));
-    console.log(chalk.dim('       e.g. card in a 3-col grid → maxWidth:"24rem", full-width component → omit maxWidth'));
+    if (isExpo) {
+        console.log(chalk.dim('       Wrap the component in a capture container with nativeID="codeyam-capture":'));
+        console.log(chalk.dim('       <View nativeID="codeyam-capture" style={{ display:"flex" }}>'));
+    }
+    else {
+        console.log(chalk.dim('       Wrap the component in a capture container with id="codeyam-capture":'));
+        console.log(chalk.dim('       <div id="codeyam-capture" style={{ display:"inline-block" }}>'));
+    }
+    console.log(chalk.dim(isExpo
+        ? '         <View style={{ width:"100%", maxWidth:... }}> ← match the app\'s container width'
+        : '         <div style={{ width:"100%", maxWidth:"..." }}> ← match the app\'s container width'));
+    console.log(chalk.dim('       e.g. card in a 3-col grid → maxWidth: 384, full-width component → omit maxWidth'));
     console.log(chalk.dim('       The screenshot captures just this wrapper, so the component fills the image.'));
     console.log(chalk.dim('       Center the wrapper on the page (flexbox center both axes) and set a page background'));
     console.log(chalk.dim('       color that matches where the component normally appears (e.g. white for light UIs).'));
@@ -714,11 +996,17 @@ function printSetup(root) {
     console.log();
     // ── Design System ────────────────────────────────────────────────
     console.log(chalk.bold('Design System (ask FIRST):'));
-    console.log(chalk.dim('  Ask: "Do you have a design system, brand guidelines, or style preferences you\'d like me to follow?"'));
+    console.log(chalk.dim('  Ask: "What visual style do you want? Pick a built-in design system or bring your own."'));
     console.log(chalk.dim('  Use AskUserQuestion with these EXACT option labels:'));
-    console.log(chalk.yellow('    Option 1 label: "Yes, I\'ll paste my design system"'));
+    console.log();
+    for (const ds of DESIGN_SYSTEMS) {
+        console.log(chalk.yellow(`    Option label: "${ds.name}"`) +
+            chalk.dim(` — ${ds.description}`));
+        console.log(chalk.dim(`       → Run: codeyam editor design-system ${ds.id}`));
+    }
+    console.log(chalk.yellow('    Option label: "I\'ll paste my own design system"'));
     console.log(chalk.dim('       → Wait for paste, save to .codeyam/design-system.md, confirm with brief summary'));
-    console.log(chalk.yellow('    Option 2 label: "No, use sensible defaults"'));
+    console.log(chalk.yellow('    Option label: "Skip — use sensible defaults"'));
     console.log(chalk.dim('       → Skip'));
     console.log();
     console.log(chalk.bold('Checklist:'));
@@ -739,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) {
@@ -773,7 +1061,7 @@ function printSetup(root) {
     console.log(chalk.yellow('    ( ) Mobile') + chalk.dim(' — 375 × 667'));
     console.log(chalk.yellow('    ( ) Custom') + chalk.dim(' — ask for width × height'));
     console.log();
-    console.log(chalk.dim('  Pre-select based on app format: mobile-responsive-web-app/desktop-app → Desktop, mobile-app → Mobile, chrome-extension → Custom (400×600).'));
+    console.log(chalk.dim('  Pre-select based on app format: mobile-responsive-web-app/desktop-app → Desktop, mobile-app → iPhone 16 (393×852), chrome-extension → Custom (400×600).'));
     console.log(chalk.dim('  If only one obvious choice, confirm it rather than asking.'));
     console.log(chalk.dim(`  Save the choice via: curl -s -X POST http://localhost:${port}/api/editor-project-info -H "Content-Type: application/json" -d '{"defaultScreenSize":{"name":"Desktop","width":1440,"height":900}}'`));
     console.log();
@@ -932,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):'));
@@ -945,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 ━━━'));
@@ -982,33 +1281,79 @@ function printStep2(root, feature) {
     }
     console.log('Get the project ready to build.');
     console.log();
+    const ctx = getTechStackContext(root);
     // If no project exists yet, include scaffolding instructions first
     if (!projectExists) {
         console.log(chalk.bold('Scaffold the project:'));
         checkbox('Run `codeyam editor template` to scaffold, install dependencies, init git, and configure CodeYam');
-        console.log(chalk.dim('  This copies the Next.js + Prisma 7 + SQLite template, runs npm install,'));
+        if (ctx.isExpo) {
+            console.log(chalk.dim('  This copies the Expo + React Native template, runs npm install,'));
+        }
+        else if (ctx.isChromeExt) {
+            console.log(chalk.dim('  This copies the Chrome Extension + React template, runs npm install,'));
+        }
+        else {
+            console.log(chalk.dim('  This copies the Next.js + Prisma 7 + SQLite template, runs npm install,'));
+        }
         console.log(chalk.dim('  initializes git, runs codeyam init, and refreshes the editor — all in one command.'));
         console.log();
-        checkbox('Define your data models in `prisma/schema.prisma`');
-        console.log(chalk.dim("  Replace the placeholder Todo model with your app's models"));
-        console.log();
-        checkbox('Push schema and seed the database');
-        console.log(chalk.dim('  npm run db:push'));
-        console.log(chalk.dim('  # Edit prisma/seed.ts with your seed data, then:'));
-        console.log(chalk.dim('  npm run db:seed'));
-        console.log(chalk.dim(`  # After re-seeding, restart the dev server to pick up fresh data:`));
-        console.log(chalk.dim(`  # codeyam editor dev-server '{"action":"restart"}'`));
-        console.log();
-        console.log(chalk.yellow('  IMPORTANT: When adding new required columns to existing tables,'));
-        console.log(chalk.yellow('  provide a @default(...) value so `db push` can fill existing rows.'));
-        console.log(chalk.dim('  Example: userId String @default("anonymous")  — existing rows get "anonymous"'));
-        console.log(chalk.dim('  Without a default, Prisma requires --force-reset which drops ALL data.'));
-        console.log(chalk.dim('  NEVER use --force-reset — it is blocked in this environment.'));
-        console.log();
-        console.log(chalk.dim('  See DATABASE.md for Prisma patterns and important warnings.'));
-        console.log(chalk.dim('  Key: import { prisma } from "@/app/lib/prisma" in API routes.'));
-        console.log(chalk.dim('  Key: Seed scripts must use the adapter pattern (see prisma/seed.ts).'));
-        console.log();
+        if (ctx.isExpo) {
+            // Expo: no database, use AsyncStorage + theme
+            checkbox('Define your data types in `lib/types.ts`');
+            console.log(chalk.dim("  Create TypeScript interfaces for your app's data models"));
+            console.log();
+            checkbox('Set up initial data using the storage helper in `lib/storage.ts`');
+            console.log(chalk.dim('  import { storage } from "@/lib/storage";'));
+            console.log(chalk.dim('  await storage.set("items", [{ id: "1", title: "First item" }]);'));
+            console.log();
+            console.log(chalk.dim('  Read MOBILE_SETUP.md for data storage, navigation, and testing patterns.'));
+            console.log();
+            checkbox('Ask the user what to name the app (use AskUserQuestion), then update app.json');
+            console.log(chalk.dim('  Update name, slug, scheme, ios.bundleIdentifier (com.codeyam.<slug>), and android.package'));
+            console.log(chalk.dim('  Also set the projectTitle via: curl -s -X POST http://localhost:' +
+                port +
+                '/api/editor-project-info -H "Content-Type: application/json" -d \'{"projectTitle":"<name>"}\''));
+            console.log();
+            checkbox('Generate an app icon using `sharp`');
+            console.log(chalk.dim('  Create `scripts/generate-icon.mjs` and `mkdir -p assets`'));
+            console.log(chalk.yellow('  ICON DESIGN GOAL: The icon must look distinctive on a home screen full of other app icons.'));
+            console.log(chalk.yellow('  Use multiple bold colors from the design system and complex, overlapping shapes.'));
+            console.log(chalk.yellow('  NO simple/minimal icons — no single glyph on a flat background, no plain text, no basic circles.'));
+            console.log(chalk.yellow('  Make it colorful, layered, and dense. Use gradients, multiple contrasting fills, and depth.'));
+            console.log(chalk.dim('  Use sharp to render SVG to 1024x1024 PNG. iOS: flatten onto background (no alpha channel).'));
+            console.log(chalk.dim('  Generate: icon.png, adaptive-icon.png, favicon.png (48x48). Run `node scripts/generate-icon.mjs`'));
+            console.log();
+        }
+        else if (ctx.isChromeExt) {
+            // Chrome Extension: use chrome.storage
+            checkbox('Set up data storage using chrome.storage (with localStorage fallback for dev)');
+            console.log();
+            console.log(chalk.dim('  Read EXTENSION_SETUP.md for storage, messaging, and manifest patterns.'));
+            console.log();
+        }
+        else {
+            // Next.js: Prisma + database
+            checkbox('Define your data models in `prisma/schema.prisma`');
+            console.log(chalk.dim("  Replace the placeholder Todo model with your app's models"));
+            console.log();
+            checkbox('Push schema and seed the database');
+            console.log(chalk.dim('  npm run db:push'));
+            console.log(chalk.dim('  # Edit prisma/seed.ts with your seed data, then:'));
+            console.log(chalk.dim('  npm run db:seed'));
+            console.log(chalk.dim(`  # After re-seeding, restart the dev server to pick up fresh data:`));
+            console.log(chalk.dim(`  # codeyam editor dev-server '{"action":"restart"}'`));
+            console.log();
+            console.log(chalk.yellow('  IMPORTANT: When adding new required columns to existing tables,'));
+            console.log(chalk.yellow('  provide a @default(...) value so `db push` can fill existing rows.'));
+            console.log(chalk.dim('  Example: userId String @default("anonymous")  — existing rows get "anonymous"'));
+            console.log(chalk.dim('  Without a default, Prisma requires --force-reset which drops ALL data.'));
+            console.log(chalk.dim('  NEVER use --force-reset — it is blocked in this environment.'));
+            console.log();
+            console.log(chalk.dim('  See DATABASE.md for Prisma patterns and important warnings.'));
+            console.log(chalk.dim('  Key: import { prisma } from "@/app/lib/prisma" in API routes.'));
+            console.log(chalk.dim('  Key: Seed scripts must use the adapter pattern (see prisma/seed.ts).'));
+            console.log();
+        }
         printDataStructureInstructions();
     }
     else {
@@ -1026,6 +1371,10 @@ function printStep2(root, feature) {
         console.log();
         printDataStructureInstructions();
     }
+    console.log();
+    printServiceRecordingReminder(port);
+    console.log();
+    checkboxHandoff();
     stopGate(2);
 }
 // ─── Step 3: Prototype ────────────────────────────────────────────────
@@ -1050,26 +1399,42 @@ function printStep3(root, feature) {
     if (isResuming) {
         printResumptionHeader(3);
     }
+    const ctx = getTechStackContext(root);
     console.log('Build fast with real data. Prioritize speed over quality.');
     console.log();
     console.log(chalk.bold('Checklist:'));
-    checkbox('Create API routes that read from the database via Prisma');
-    if (!projectExists) {
-        checkbox('Seed the database with demo data');
-        checkbox('Create `.codeyam/seed-adapter.ts` so CodeYam can seed the database for scenarios');
-        console.log(chalk.dim('    The seed adapter reads a JSON file (path passed as CLI arg), wipes tables, inserts rows.'));
-        console.log(chalk.dim("    Use the project's own ORM (Prisma, Drizzle, etc.). See template for example."));
-        console.log(chalk.dim('    Run with: npx tsx .codeyam/seed-adapter.ts <path-to-seed-data.json>'));
-        console.log();
-        console.log(chalk.bold.cyan('Make seed data visually rich:'));
-        console.log(chalk.cyan('  • Use real placeholder images from Unsplash (https://images.unsplash.com/photo-<id>?w=400&h=300&fit=crop)'));
-        console.log(chalk.cyan('  • Use avatar services like i.pravatar.cc for user profile photos'));
-        console.log(chalk.cyan('  • Write realistic, varied content — not "Item 1", "Item 2", "Test Description"'));
-        console.log(chalk.cyan('  • Include different text lengths, categories, dates, and statuses'));
-        console.log(chalk.cyan('  • Rich seed data makes the prototype look real and surfaces layout issues early'));
+    if (ctx.isExpo) {
+        checkbox('Build screens that read from AsyncStorage via `lib/storage.ts` or fetch from APIs');
+        if (!projectExists) {
+            checkbox('Populate initial data in AsyncStorage for development');
+            console.log(chalk.dim('    import { storage } from "@/lib/storage";'));
+            console.log(chalk.dim('    await storage.set("items", [{ id: "1", title: "Buy groceries" }]);'));
+            console.log();
+            console.log(chalk.bold.cyan('Make data visually rich:'));
+            console.log(chalk.cyan('  • Write realistic, varied content — not "Item 1", "Item 2", "Test Description"'));
+            console.log(chalk.cyan('  • Include different text lengths, categories, dates, and statuses'));
+            console.log(chalk.cyan('  • Rich data makes the prototype look real and surfaces layout issues early'));
+        }
+    }
+    else {
+        checkbox('Create API routes that read from the database via Prisma');
+        if (!projectExists) {
+            checkbox('Seed the database with demo data');
+            checkbox('Create `.codeyam/seed-adapter.ts` so CodeYam can seed the database for scenarios');
+            console.log(chalk.dim('    The seed adapter reads a JSON file (path passed as CLI arg), wipes tables, inserts rows.'));
+            console.log(chalk.dim("    Use the project's own ORM (Prisma, Drizzle, etc.). See template for example."));
+            console.log(chalk.dim('    Run with: npx tsx .codeyam/seed-adapter.ts <path-to-seed-data.json>'));
+            console.log();
+            console.log(chalk.bold.cyan('Make seed data visually rich:'));
+            console.log(chalk.cyan('  • Use real placeholder images from Unsplash (https://images.unsplash.com/photo-<id>?w=400&h=300&fit=crop)'));
+            console.log(chalk.cyan('  • Use avatar services like i.pravatar.cc for user profile photos'));
+            console.log(chalk.cyan('  • Write realistic, varied content — not "Item 1", "Item 2", "Test Description"'));
+            console.log(chalk.cyan('  • Include different text lengths, categories, dates, and statuses'));
+            console.log(chalk.cyan('  • Rich seed data makes the prototype look real and surfaces layout issues early'));
+        }
     }
     checkbox('Verify the dev server shows the changes');
-    checkbox('If the feature involves auth, email, payments, or other common patterns: read FEATURE_PATTERNS.md');
+    checkbox(`If the feature involves auth, email, payments, or other common patterns: read ${ctx.patternsFile}`);
     // Responsive design guidance when building a mobile-responsive web app
     if (prevState?.appFormats?.includes('mobile-responsive-web-app')) {
         console.log();
@@ -1086,16 +1451,33 @@ function printStep3(root, feature) {
         console.log();
         console.log(designSystem);
         console.log();
-        checkbox('Define ALL design tokens as CSS custom properties in globals.css — not just colors');
-        console.log(chalk.dim('    Colors: --bg-surface, --text-primary, --accent-green-a, etc.'));
-        console.log(chalk.dim('    Typography: --text-xs, --text-sm, --text-lg, --text-2xl (font-size values)'));
-        console.log(chalk.dim('    Font weights: --font-weight-normal, --font-weight-medium, --font-weight-semibold'));
-        console.log(chalk.dim('    Spacing: --spacing-xs, --spacing-sm, --spacing-md, --spacing-lg, etc.'));
-        console.log(chalk.dim('    Border radius, shadows, transitions — every value the design system defines.'));
-        checkbox('Reference tokens from components — ZERO hardcoded px values for font-size, spacing, or colors');
-        console.log(chalk.dim('    Bad:  fontSize: 14, padding: "12px 16px", gap: 8'));
-        console.log(chalk.dim('    Good: fontSize: "var(--text-sm)", padding: "var(--spacing-md) var(--spacing-lg)", gap: "var(--spacing-sm)"'));
-        console.log(chalk.dim('    This ensures the entire app updates when the design system changes.'));
+        if (ctx.isExpo) {
+            checkbox('Define ALL design tokens in `lib/theme.ts` — this is the single source of truth');
+            console.log(chalk.dim('    Colors: theme.colors.bgSurface, theme.colors.textPrimary, etc.'));
+            console.log(chalk.dim('    Typography: theme.fontSize.sm, theme.fontSize.lg, theme.fontFamily.mono'));
+            console.log(chalk.dim('    Spacing: theme.spacing.sm, theme.spacing.md, theme.spacing.lg, etc.'));
+            console.log(chalk.dim('    Border radius: theme.borderRadius.sm, theme.borderRadius.lg, etc.'));
+            checkbox('Import theme in every component — ZERO hardcoded color strings or pixel values');
+            console.log(chalk.dim('    Bad:  color: "#333", fontSize: 14, padding: 12'));
+            console.log(chalk.dim('    Good: color: theme.colors.textPrimary, fontSize: theme.fontSize.sm, padding: theme.spacing.md'));
+            console.log(chalk.dim('    Do NOT use CSS custom properties (var(--token)) — they do not work in React Native.'));
+            checkbox('Buttons: put backgroundColor, borderRadius, borderStyle on a wrapping <View>, NOT on <Pressable>');
+            console.log(chalk.dim('    Pressable renders these styles on web but FAILS SILENTLY on native devices.'));
+            console.log(chalk.dim('    Use a <View> with overflow:"hidden" for the visual shell, <Pressable> inside for touch only.'));
+            console.log(chalk.dim('    For press feedback: use onPressIn/onPressOut + useState to toggle opacity, not function-style style.'));
+        }
+        else {
+            checkbox('Define ALL design tokens as CSS custom properties in globals.css — not just colors');
+            console.log(chalk.dim('    Colors: --bg-surface, --text-primary, --accent-green-a, etc.'));
+            console.log(chalk.dim('    Typography: --text-xs, --text-sm, --text-lg, --text-2xl (font-size values)'));
+            console.log(chalk.dim('    Font weights: --font-weight-normal, --font-weight-medium, --font-weight-semibold'));
+            console.log(chalk.dim('    Spacing: --spacing-xs, --spacing-sm, --spacing-md, --spacing-lg, etc.'));
+            console.log(chalk.dim('    Border radius, shadows, transitions — every value the design system defines.'));
+            checkbox('Reference tokens from components — ZERO hardcoded px values for font-size, spacing, or colors');
+            console.log(chalk.dim('    Bad:  fontSize: 14, padding: "12px 16px", gap: 8'));
+            console.log(chalk.dim('    Good: fontSize: "var(--text-sm)", padding: "var(--spacing-md) var(--spacing-lg)", gap: "var(--spacing-sm)"'));
+            console.log(chalk.dim('    This ensures the entire app updates when the design system changes.'));
+        }
     }
     console.log();
     console.log(chalk.bold.cyan('Keep the preview moving:'));
@@ -1109,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 ─────────────────────────────────────────
@@ -1123,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);
@@ -1132,14 +1519,13 @@ function printStep4(root, feature) {
     console.log('Verify everything works before presenting the prototype.');
     console.log();
     console.log(chalk.bold('Verify the dev server:'));
-    console.log(chalk.dim(`  # Get dev server URL: codeyam editor dev-server`));
-    console.log(chalk.dim('  # Check page loads: curl -s -o /dev/null -w "%{http_code}" http://localhost:<dev-port>'));
-    console.log(chalk.dim('  # Check API routes: curl -s http://localhost:<dev-port>/api/your-route'));
+    console.log(chalk.dim('  # Verify pages and API routes load:'));
+    console.log(chalk.dim(`  codeyam editor verify-routes '{"paths":["/your-page"],"apiRoutes":["/api/your-route"]}'`));
     console.log();
     console.log(chalk.bold('Verify before proceeding:'));
     console.log(chalk.yellow('  Verify everything works before presenting the prototype to the user.'));
-    checkbox('Verify the page loads: curl the dev server URL and confirm HTTP 200 (not an error page)');
-    checkbox('Verify API routes return valid JSON: curl each route and confirm no error responses');
+    checkbox('Verify page and API routes: `codeyam editor verify-routes \'{"paths":["/"],"apiRoutes":["/api/your-route"]}\'`');
+    console.log(chalk.dim('    Include ALL page paths you built and ALL API routes they depend on.'));
     checkbox('Check for broken images: `codeyam editor verify-images \'{"paths":["/"], "imageUrls":["url1","url2"]}\'`');
     console.log(chalk.dim('    Pass ALL page paths and ALL image URLs you used in seed data / API responses.'));
     console.log(chalk.dim('    Client-rendered pages need imageUrls — the HTML shell has no images to scan.'));
@@ -1150,6 +1536,14 @@ function printStep4(root, feature) {
     console.log(chalk.dim('    The user is looking at the preview — a blank page means something is broken.'));
     console.log(chalk.dim('    If any check fails, fix the issue and re-verify before proceeding.'));
     console.log();
+    const ctx4 = getTechStackContext(root);
+    if (ctx4.isExpo) {
+        console.log(chalk.magenta.bold('  EXPO WEB PREVIEW NOTE:'));
+        console.log(chalk.magenta('  The preview renders via react-native-web in a browser. Some differences'));
+        console.log(chalk.magenta('  from native devices are expected (fonts, SafeAreaView, shadows, Platform.OS).'));
+        console.log(chalk.magenta('  The preview is for layout and data verification. Test final polish on device.'));
+        console.log();
+    }
     console.log(chalk.bold('Update README and setup script:'));
     checkbox('Update `README.md`: set the project name, write a one-line description, and list any setup prerequisites');
     checkbox('Update `npm run setup` in `package.json` if setup requires extra steps (e.g. env vars, external services)');
@@ -1157,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 ──────────────────────────────────────────────────
@@ -1172,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);
@@ -1182,7 +1580,7 @@ function printStep5(root, feature) {
     console.log();
     console.log(chalk.bold('Before presenting — verify everything works:'));
     checkbox(`Refresh the preview: \`codeyam editor preview '{"dimension":"${dim}"}'\` — check the \`preview\` field for \`healthy: false\``);
-    checkbox('Verify API routes return valid data (curl each route)');
+    checkbox('Verify routes: `codeyam editor verify-routes \'{"paths":["/"],"apiRoutes":["/api/your-route"]}\'`');
     console.log();
     console.log(chalk.bold.red('  Verify EVERY image loads (this is the #1 source of broken prototypes):'));
     checkbox('Run `codeyam editor verify-images \'{"paths":["/"], "imageUrls":["url1","url2"]}\'`');
@@ -1218,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 ──────────────────────────────────────────────
@@ -1231,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);
@@ -1241,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 ──────────────────────────────────────────────────
@@ -1256,12 +1660,15 @@ 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);
     if (isResuming) {
         printResumptionHeader(7);
     }
+    const ctx = getTechStackContext(root);
     console.log('Execute your extraction plan from step 6.');
     console.log();
     console.log(chalk.bold('Components:'));
@@ -1274,19 +1681,45 @@ 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'));
-    checkbox('Place test files next to source: `app/lib/drinks.ts` → `app/lib/drinks.test.ts`');
+    console.log(chalk.dim('    Wrap all tests in a describe("FunctionName", ...) block — the audit matches on this name'));
+    if (ctx.isExpo) {
+        checkbox('Place test files next to source but OUTSIDE `app/` (Expo Router treats all files in app/ as routes): `lib/storage.ts` → `lib/storage.test.ts`, `app/hooks/useCounter.ts` → `__tests__/hooks/useCounter.test.ts`');
+    }
+    else {
+        checkbox('Place test files next to source: `app/lib/drinks.ts` → `app/lib/drinks.test.ts`');
+    }
     console.log(chalk.yellow('  Tests ARE the only coverage for library functions/hooks — step 9 only captures component screenshots.'));
     console.log();
     console.log(chalk.bold('Recursive pass:'));
     checkbox('Re-read EVERY new file you just created — extract components from components, functions from functions');
     checkbox('Keep going until every file is a thin shell: just imports and composition');
-    console.log(chalk.yellow('    Check: does any file contain raw <div>, <span>, <h1>, <p>, <img>, or <ul>?'));
+    console.log(chalk.yellow(`    Check: does any file contain raw ${ctx.rawPrimitivesList}?`));
     console.log(chalk.yellow('    If yes → that JSX section is a component waiting to be extracted.'));
     console.log();
+    console.log(chalk.bold('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 HTML tags');
+    checkbox(`Page files contain ONLY imports + component composition — no raw ${ctx.isExpo ? 'React Native primitives' : 'HTML tags'}`);
     checkbox('Every component renders ONE thing or composes sub-components — no multi-section JSX');
     checkbox(`Refresh the preview after each batch of extractions: \`codeyam editor preview '{"dimension":"${dim}"}'\``);
     printDimensionGuidance(dim, dimNames);
@@ -1294,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 ─────────────────────────────────────────────────
@@ -1307,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);
@@ -1333,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);
@@ -1347,16 +1786,26 @@ function printStep9(root, feature) {
     console.log(chalk.dim('    Reuse and improve existing scenarios where possible — update mock data'));
     console.log(chalk.dim('    to reflect current changes. Add new scenarios only for genuinely new states.'));
     console.log(chalk.dim('    Ensure at least one scenario clearly demonstrates what changed in this session.'));
-    printComponentCaptureInstructions();
+    const ctx9 = getTechStackContext(root);
+    printComponentCaptureInstructions(root);
     console.log();
     console.log(chalk.bold('Library Functions — run tests:'));
     checkbox('Run ALL test files created in step 7');
-    console.log(chalk.dim('    Example: npx vitest run app/lib/drinks.test.ts'));
+    console.log(chalk.dim(`    Example: ${ctx9.testRunCommand} app/lib/drinks.test.ts`));
     checkbox('Verify every test passes');
     checkbox('If any test fails, fix the source code and re-run');
     console.log();
     console.log(chalk.dim('Do not proceed until both component isolations and library tests pass.'));
     console.log();
+    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.'));
@@ -1382,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);
@@ -1446,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);
@@ -1492,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);
@@ -1538,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);
@@ -1571,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);
@@ -1590,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);
 }
@@ -1604,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);
@@ -1832,7 +2295,7 @@ function printMigrateStep3(root) {
     console.log(chalk.dim('  Component scenarios use isolation routes with a codeyam-capture wrapper for tight screenshots.'));
     console.log(chalk.dim('  These supplement the app scenarios from step 2 with focused component-level views.'));
     console.log();
-    printComponentCaptureInstructions();
+    printComponentCaptureInstructions(root);
     console.log();
     migrationStopGate(3, pageName, pageIndex, totalPages);
 }
@@ -1975,10 +2438,10 @@ function printMigrateStep8(root) {
     console.log();
     console.log(chalk.bold('Component Scenarios:'));
     console.log(chalk.dim('  For each visual component extracted in step 7, create isolation routes and register scenarios.'));
-    printComponentCaptureInstructions();
+    printComponentCaptureInstructions(root);
     console.log();
     console.log(chalk.bold('Verify:'));
-    checkbox('Run `codeyam editor analyze-imports` to populate import graph');
+    checkbox('Run `codeyam editor analyze-imports` to populate import graph (or `codeyam editor analyze-imports path/to/file.tsx ...` for specific files)');
     checkbox('Run library function tests: `npx jest --testPathPattern="<relevant>" --maxWorkers=2`');
     checkbox('Run `codeyam editor audit` to check completeness');
     checkbox('Check for client errors: `codeyam editor client-errors`');
@@ -2253,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);
@@ -2279,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);
@@ -2304,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);
@@ -2321,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 });
 }
@@ -2356,10 +2825,14 @@ async function handleAnalyzeImports(options = {}) {
         glossaryEntries = sanitizeGlossaryEntries(parsed);
     }
     catch {
+        if (options.silent)
+            return;
         console.error(chalk.red('Error: Could not parse .codeyam/glossary.json.'));
         process.exit(1);
     }
     if (glossaryEntries.length === 0) {
+        if (options.silent)
+            return;
         console.error(chalk.red('Error: glossary.json is empty.'));
         process.exit(1);
     }
@@ -2428,6 +2901,15 @@ async function handleAnalyzeImports(options = {}) {
     catch {
         // Non-fatal — fall back to analyzing all files
     }
+    // If specific file paths were requested, scope analysis to only those files.
+    // The full filePaths set is still used for the import graph below.
+    if (options.filePaths && options.filePaths.length > 0) {
+        const requested = new Set(options.filePaths);
+        targetFilePaths = targetFilePaths.filter((fp) => requested.has(fp));
+        if (targetFilePaths.length === 0 && !options.silent) {
+            console.log(chalk.dim('Requested file(s) already analyzed or not in glossary — skipping analysis.'));
+        }
+    }
     // Run data-structure-only analysis for entities that need it.
     // Don't pass entityNames — entities may not exist yet (fresh clone).
     // The analyzer will discover and create them from file paths.
@@ -2444,6 +2926,10 @@ async function handleAnalyzeImports(options = {}) {
         catch (err) {
             progress.fail('Analysis failed');
             const msg = err instanceof Error ? err.message : String(err);
+            if (options.silent) {
+                // Internal caller — don't kill the process, let the caller handle it
+                return;
+            }
             console.error(chalk.red(`Error: ${msg}`));
             process.exit(1);
         }
@@ -2499,18 +2985,10 @@ async function handleAnalyzeImports(options = {}) {
                     }
                 }
             }
-            else if (targetFilePaths.length > 0) {
-                // Couldn't parse specific entity names — mark all target files
-                // that we attempted to analyze as potentially failed
-                for (const fp of targetFilePaths) {
-                    const entry = glossary.find((e) => e.filePath === fp);
-                    updatedFailures[fp] = {
-                        entityName: entry?.name || path.basename(fp, path.extname(fp)),
-                        error: `Automated analysis failed — see .codeyam/analysis-errors.txt`,
-                        failedAt: now,
-                    };
-                }
-            }
+            // When we can't parse specific entity names from the error, DON'T mark
+            // all target files as failed. The error may be non-fatal (e.g., a cache
+            // miss logged as "CodeYam Error") and blanket-marking every file as
+            // permanently failed blocks future audits from resolving them.
             writeAnalysisFailures(root, updatedFailures);
         }
         catch {
@@ -2709,43 +3187,98 @@ async function handleDelete(scenarioId) {
  * Creates isolation route directories and the layout guard file.
  * This avoids brace-expansion permission prompts in the embedded terminal.
  */
+function handleDesignSystem(designSystemId) {
+    const root = process.cwd();
+    const ds = DESIGN_SYSTEMS.find((d) => d.id === designSystemId);
+    if (!ds) {
+        console.error(chalk.red(`Error: Unknown design system "${designSystemId}". Valid options: ${DESIGN_SYSTEMS.map((d) => d.id).join(', ')}`));
+        process.exit(1);
+    }
+    const srcPath = path.join(__dirname, '..', '..', 'templates', 'design-systems', ds.fileName);
+    if (!fs.existsSync(srcPath)) {
+        console.error(chalk.red(`Error: Design system file not found: ${srcPath}`));
+        process.exit(1);
+    }
+    const destDir = path.join(root, '.codeyam');
+    fs.mkdirSync(destDir, { recursive: true });
+    const destPath = path.join(destDir, 'design-system.md');
+    fs.copyFileSync(srcPath, destPath);
+    console.log(chalk.green(`Installed "${ds.name}" design system → .codeyam/design-system.md`));
+}
 function handleIsolate(componentNames) {
     const root = process.cwd();
+    const ctx = getTechStackContext(root);
     if (componentNames.length === 0) {
         console.error(chalk.red('Usage: codeyam editor isolate "ComponentA ComponentB ..."'));
         process.exit(1);
     }
     const isolateDir = path.join(root, 'app', 'isolated-components');
-    // Create layout.tsx with production guard if missing
-    const layoutPath = path.join(isolateDir, 'layout.tsx');
+    // Create the framework-appropriate layout guard if missing.
+    // Clean up wrong-framework layout from a previous CLI version.
+    const layoutPath = path.join(isolateDir, ctx.isExpo ? '_layout.tsx' : 'layout.tsx');
+    const wrongLayoutPath = path.join(isolateDir, ctx.isExpo ? 'layout.tsx' : '_layout.tsx');
+    if (fs.existsSync(wrongLayoutPath)) {
+        fs.unlinkSync(wrongLayoutPath);
+    }
     if (!fs.existsSync(layoutPath)) {
         fs.mkdirSync(isolateDir, { recursive: true });
-        fs.writeFileSync(layoutPath, [
-            'import { notFound } from "next/navigation";',
-            '',
-            'export default function CaptureLayout({ children }: { children: React.ReactNode }) {',
-            '  if (process.env.NODE_ENV === "production") notFound();',
-            '  return <>{children}</>;',
-            '}',
-            '',
-        ].join('\n'), 'utf8');
-        console.log(chalk.green(`Created layout guard: app/isolated-components/layout.tsx`));
-    }
-    // Create a directory for each component
+        if (ctx.isExpo) {
+            fs.writeFileSync(layoutPath, [
+                'import { Redirect, Slot } from "expo-router";',
+                '',
+                'export default function CaptureLayout() {',
+                '  if (!__DEV__) return <Redirect href="/" />;',
+                '  return <Slot />;',
+                '}',
+                '',
+            ].join('\n'), 'utf8');
+        }
+        else {
+            fs.writeFileSync(layoutPath, [
+                'import { notFound } from "next/navigation";',
+                '',
+                'export default function CaptureLayout({ children }: { children: React.ReactNode }) {',
+                '  if (process.env.NODE_ENV === "production") notFound();',
+                '  return <>{children}</>;',
+                '}',
+                '',
+            ].join('\n'), 'utf8');
+        }
+        console.log(chalk.green(`Created layout guard: app/isolated-components/${ctx.isExpo ? '_layout.tsx' : 'layout.tsx'}`));
+    }
+    // Create isolation route for each component.
+    // Expo Router uses flat files (ComponentName.tsx), Next.js uses subdirectories (ComponentName/page.tsx).
     const created = [];
     const existed = [];
     for (const name of componentNames) {
-        const dir = path.join(isolateDir, name);
-        if (fs.existsSync(dir)) {
-            existed.push(name);
+        if (ctx.isExpo) {
+            const filePath = path.join(isolateDir, `${name}.tsx`);
+            if (fs.existsSync(filePath)) {
+                existed.push(name);
+            }
+            else {
+                created.push(name);
+            }
         }
         else {
-            fs.mkdirSync(dir, { recursive: true });
-            created.push(name);
+            const dir = path.join(isolateDir, name);
+            if (fs.existsSync(dir)) {
+                existed.push(name);
+            }
+            else {
+                fs.mkdirSync(dir, { recursive: true });
+                created.push(name);
+            }
         }
     }
     if (created.length > 0) {
-        console.log(chalk.green(`Created ${created.length} isolation route dir(s): ${created.join(', ')}`));
+        if (ctx.isExpo) {
+            console.log(chalk.green(`Ready for ${created.length} isolation route(s): ${created.map((n) => `app/isolated-components/${n}.tsx`).join(', ')}`));
+            console.log(chalk.dim('    Create each file with useLocalSearchParams, a scenarios map, and nativeID="codeyam-capture"'));
+        }
+        else {
+            console.log(chalk.green(`Created ${created.length} isolation route dir(s): ${created.join(', ')}`));
+        }
     }
     if (existed.length > 0) {
         console.log(chalk.dim(`Already existed: ${existed.join(', ')}`));
@@ -2799,6 +3332,12 @@ function formatApiSubcommandResult(subcommand, data) {
                 parts.push(`scenarioId="${data.scenarioId}"`);
             if (data.sessionsNotified != null)
                 parts.push(`notified=${data.sessionsNotified}`);
+            // Surface the HTTP health check from the dev server
+            if (data.preview) {
+                parts.push(`healthy=${data.preview.healthy}`);
+                if (data.preview.error)
+                    parts.push(`error="${data.preview.error}"`);
+            }
             return parts.join(' ');
         }
         case 'dev-server': {
@@ -2848,10 +3387,82 @@ function formatApiSubcommandResult(subcommand, data) {
             }
             return parts.join(' ');
         }
+        case 'verify-routes': {
+            const lines = [];
+            lines.push(chalk.bold.yellow('━━━ Route Verification ━━━'));
+            for (const [route, info] of Object.entries(data.routes || {})) {
+                const r = info;
+                if (r.ok) {
+                    lines.push(chalk.green(`  ✓ ${route} — HTTP ${r.status}`));
+                }
+                else {
+                    lines.push(chalk.red(`  ✗ ${route} — ${r.error || `HTTP ${r.status}`}`));
+                }
+            }
+            for (const [route, info] of Object.entries(data.apiRoutes || {})) {
+                const r = info;
+                if (r.ok && r.isJSON) {
+                    lines.push(chalk.green(`  ✓ ${route} — HTTP ${r.status}, valid JSON`));
+                }
+                else if (r.ok) {
+                    lines.push(chalk.yellow(`  ⚠ ${route} — HTTP ${r.status}, not valid JSON`));
+                }
+                else {
+                    lines.push(chalk.red(`  ✗ ${route} — ${r.error || `HTTP ${r.status}`}`));
+                }
+            }
+            lines.push('');
+            lines.push(data.ok ? chalk.green(data.summary) : chalk.red(data.summary));
+            return lines.join('\n');
+        }
         default:
             return null; // journal-list, show/hide-results: keep full JSON
     }
 }
+/**
+ * `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":"...",...}'`
  *
@@ -3454,7 +4065,15 @@ function printAuditGateFailures(data) {
         for (const m of missingGlossary) {
             issues.push(`    → ${m.name} (${m.filePath})`);
         }
-        issues.push(`      Fix: Run \`codeyam editor analyze-imports\` to add these files to the glossary`);
+        const missingPaths = missingGlossary
+            .map((m) => m.filePath)
+            .filter(Boolean);
+        if (missingPaths.length > 0) {
+            issues.push(`      Fix: Run \`codeyam editor analyze-imports ${missingPaths.join(' ')}\``);
+        }
+        else {
+            issues.push(`      Fix: Run \`codeyam editor analyze-imports\` to add these files to the glossary`);
+        }
     }
     if (s.incompleteEntities > 0) {
         // Check for persistent analysis failures
@@ -3498,8 +4117,16 @@ function printAuditGateFailures(data) {
         }
     }
     if (s.unassociatedScenarios > 0) {
-        issues.push(`${s.unassociatedScenarios} component(s) have scenarios with no entity link — run \`codeyam editor analyze-imports\` then re-run audit`);
         const unassociated = data.unassociatedScenarios || [];
+        const unassocPaths = unassociated
+            .map((u) => u.filePath)
+            .filter(Boolean);
+        if (unassocPaths.length > 0) {
+            issues.push(`${s.unassociatedScenarios} component(s) have scenarios with no entity link — run \`codeyam editor analyze-imports ${unassocPaths.join(' ')}\` then re-run audit`);
+        }
+        else {
+            issues.push(`${s.unassociatedScenarios} component(s) have scenarios with no entity link — run \`codeyam editor analyze-imports\` then re-run audit`);
+        }
         for (const u of unassociated) {
             issues.push(`    → ${u.name} (${u.filePath}) — ${u.scenarioCount} scenario${u.scenarioCount !== 1 ? 's' : ''}`);
         }
@@ -3554,16 +4181,16 @@ function printAuditGateFailures(data) {
  * which glossary components have registered scenarios and which functions
  * have test files. Exits with code 1 if anything is missing.
  */
-async function handleAudit() {
+async function handleAudit(options) {
     let data = await fetchAuditResult();
     if (!data) {
         console.error(chalk.red('Error: Could not reach the CodeYam server. Is it running?'));
         process.exit(1);
     }
-    // Lightweight auto-fix: backfill entity_sha on scenarios that were
-    // registered before entity records existed. This is fast (DB-only).
-    // Import analysis is NOT triggered here — it scans all files and takes
-    // minutes on large projects. Users should run it separately if needed.
+    // Two-phase auto-fix for entity associations:
+    // Phase 1: DB-only backfill — fast, matches existing entities to scenarios.
+    // Phase 2: If backfill fails, targeted analyze-imports for only the
+    // specific unresolved files (1-3 files, not the full glossary scan).
     const incompleteBeforeFix = data.incompleteEntities || [];
     const unassociatedBeforeFix = data.unassociatedScenarios || [];
     let autoRemediationFailed = false;
@@ -3595,14 +4222,58 @@ async function handleAudit() {
             console.error(chalk.red('Error: Could not reach the CodeYam server after backfill.'));
             process.exit(1);
         }
-        // If issues persist after backfill, flag it so we show clear guidance
+        // If issues persist after DB-only backfill, run targeted analyze-imports
+        // for ONLY the specific files that need entities. This is fast (1-3 files)
+        // unlike full analyze-imports which scans all glossary entries.
+        const incompleteAfterBackfill = data.incompleteEntities || [];
+        const unassociatedAfterBackfill = data.unassociatedScenarios || [];
+        if (incompleteAfterBackfill.length > 0 ||
+            unassociatedAfterBackfill.length > 0) {
+            const { determineTargetedAnalysisPaths } = await import('../utils/editorAudit.js');
+            const targetPaths = determineTargetedAnalysisPaths({
+                unassociatedScenarios: unassociatedAfterBackfill,
+                incompleteEntities: incompleteAfterBackfill,
+            });
+            if (targetPaths.length > 0) {
+                console.log(chalk.dim(`Running targeted analysis for ${targetPaths.length} file${targetPaths.length !== 1 ? 's' : ''}...`));
+                try {
+                    await handleAnalyzeImports({
+                        silent: true,
+                        filePaths: targetPaths,
+                    });
+                    // Retry backfill after analysis created entities
+                    const entities = await loadEntities({});
+                    if (entities && entities.length > 0) {
+                        const { getDatabase: getDb } = await import('../../../packages/database/index.js');
+                        const freshDb = getDb();
+                        await backfillEntityShaOnScenarios(freshDb, entities.map((e) => ({
+                            sha: e.sha,
+                            name: e.name,
+                            filePath: e.filePath || '',
+                            isDefaultExport: e.metadata?.notExported === false &&
+                                e.metadata?.namedExport === false,
+                        })));
+                    }
+                    // Re-fetch audit results after targeted analysis
+                    data = await fetchAuditResult({ skipTests: true });
+                    if (!data) {
+                        console.error(chalk.red('Error: Could not reach the CodeYam server after analysis.'));
+                        process.exit(1);
+                    }
+                }
+                catch {
+                    // Targeted analysis failed — fall through to show remaining issues
+                }
+            }
+        }
+        // Check if issues persist after all remediation attempts
         const incompleteAfterFix = data.incompleteEntities || [];
         const unassociatedAfterFix = data.unassociatedScenarios || [];
         if (incompleteAfterFix.length > 0 || unassociatedAfterFix.length > 0) {
             autoRemediationFailed = true;
         }
     }
-    const { components, functions, summary } = data;
+    let { components, functions, summary } = data;
     console.log();
     console.log(chalk.bold.cyan('━━━ Editor Audit ━━━'));
     console.log();
@@ -3660,14 +4331,20 @@ async function handleAudit() {
             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':
@@ -3692,6 +4369,9 @@ async function handleAudit() {
             }
             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
@@ -3701,7 +4381,15 @@ async function handleAudit() {
         for (const m of missingFromGlossary) {
             console.log(`  ${chalk.red('✗')} ${m.name} ${chalk.dim(`(${m.filePath})`)} — ${m.scenarioCount} scenario${m.scenarioCount !== 1 ? 's' : ''} but not in glossary`);
         }
-        console.log(chalk.yellow('    Add these to .codeyam/glossary.json and run `codeyam editor analyze-imports`'));
+        const mgPaths = missingFromGlossary
+            .map((m) => m.filePath)
+            .filter(Boolean);
+        if (mgPaths.length > 0) {
+            console.log(chalk.yellow(`    Add these to .codeyam/glossary.json and run \`codeyam editor analyze-imports ${mgPaths.join(' ')}\``));
+        }
+        else {
+            console.log(chalk.yellow('    Add these to .codeyam/glossary.json and run `codeyam editor analyze-imports`'));
+        }
         console.log();
     }
     // Incomplete entities (scenarios without analyses) — report with guidance.
@@ -3756,12 +4444,18 @@ async function handleAudit() {
                 console.log(chalk.dim(`      … and ${u.scenarioNames.length - 3} more`));
             }
         }
+        const uaPaths = unassociatedScenarios
+            .map((u) => u.filePath)
+            .filter(Boolean);
+        const uaCmd = uaPaths.length > 0
+            ? `codeyam editor analyze-imports ${uaPaths.join(' ')}`
+            : 'codeyam editor analyze-imports';
         if (autoRemediationFailed) {
             console.log(chalk.yellow('    analyze-imports ran automatically but could not resolve these.'));
-            console.log(chalk.yellow('    Run `codeyam editor analyze-imports` to see the full error output.'));
+            console.log(chalk.yellow(`    Run \`${uaCmd}\` to see the full error output.`));
         }
         else {
-            console.log(chalk.yellow('    Run `codeyam editor analyze-imports` to create entity records, then re-run audit to backfill.'));
+            console.log(chalk.yellow(`    Run \`${uaCmd}\` to create entity records, then re-run audit to backfill.`));
         }
         const unassocErrorReportPath = path.join(getProjectRoot(), '.codeyam', 'analysis-errors.txt');
         if (fs.existsSync(unassocErrorReportPath)) {
@@ -3794,7 +4488,26 @@ async function handleAudit() {
                 : `${s.status.status}`;
             console.log(`  ${chalk.red('✗')} ${s.scenarioName} ${chalk.dim(`(${s.entityName} — ${reason})`)}`);
         }
-        console.log(chalk.yellow('    Run: codeyam editor recapture-stale'));
+        if (options?.fix) {
+            // --fix: auto-recapture stale scenarios instead of just reporting them
+            const { shouldAutoRecapture } = await import('../utils/editorAudit.js');
+            if (shouldAutoRecapture({ fix: true, scenariosNeedingRecapture })) {
+                console.log(chalk.cyan('    --fix: auto-recapturing stale scenarios...'));
+                console.log();
+                await handleRecaptureStale();
+                // Re-fetch audit results so the summary and exit code reflect
+                // the post-fix state, not the pre-fix state.
+                const refreshed = await fetchAuditResult({ skipTests: true });
+                if (refreshed) {
+                    data = refreshed;
+                    ({ components, functions, summary } = data);
+                }
+            }
+        }
+        else {
+            console.log(chalk.yellow('    Run: codeyam editor recapture-stale'));
+            console.log(chalk.dim('    Or: codeyam editor audit --fix (to auto-recapture)'));
+        }
         console.log();
     }
     // Duplicate glossary names (warning, not a failure)
@@ -4217,7 +4930,7 @@ async function handleTemplate() {
         _: [],
     });
     console.log(chalk.green('  CodeYam initialized.'));
-    // 5. Verify config has startCommand
+    // 5. Verify config has startCommand and set format-specific defaults
     const configPath = path.join(root, '.codeyam', 'config.json');
     if (fs.existsSync(configPath)) {
         try {
@@ -4228,6 +4941,30 @@ async function handleTemplate() {
                 console.log(chalk.yellow('  Warning: No startCommand found in .codeyam/config.json webapps.'));
                 console.log(chalk.dim('  You may need to add: "startCommand": { "command": "sh", "args": ["-c", "npm run dev -- --port $PORT"] }'));
             }
+            // Store appFormats from the tech stack so the editor UI can adapt
+            if (stack?.supportedFormats) {
+                config.appFormats = stack.supportedFormats;
+            }
+            // 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 = {
+                    name: 'iPhone 16',
+                    width: 393,
+                    height: 852,
+                };
+                config.screenSizes = {
+                    'iPhone 16': { width: 393, height: 852 },
+                    'iPhone 16 Pro Max': { width: 430, height: 932 },
+                    'iPhone SE': { width: 375, height: 667 },
+                    'Pixel 8': { width: 412, height: 915 },
+                    'iPad mini': { width: 744, height: 1133 },
+                };
+            }
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
         }
         catch {
             // Config parse error is non-fatal
@@ -4262,7 +4999,15 @@ async function handleTemplate() {
     }
     console.log();
     console.log(chalk.green.bold('Project scaffolded and ready!'));
-    console.log(chalk.dim('Next: Define your Prisma models, push the schema, seed the database, and build your feature.'));
+    if (stack?.id === 'expo-react-native') {
+        console.log(chalk.dim('Next: Set up your data types, configure the theme in lib/theme.ts, and build your feature.'));
+    }
+    else if (stack?.id === 'chrome-extension-react') {
+        console.log(chalk.dim('Next: Configure your extension manifest and build your feature.'));
+    }
+    else {
+        console.log(chalk.dim('Next: Define your Prisma models, push the schema, seed the database, and build your feature.'));
+    }
 }
 // ─── Sync subcommand ─────────────────────────────────────────────────
 /**
@@ -4764,8 +5509,8 @@ const editorCommand = {
     describe: 'Editor mode guided workflow',
     builder: (yargs) => {
         const stepDescription = IS_INTERNAL_BUILD
-            ? 'Step number (1-18) or subcommand (template, register, isolate, analyze-imports, manual-entity, dependents, audit, scenarios, scenario-coverage, recapture-stale, change, sync, debug, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors, task-ontrack)'
-            : 'Step number (1-18) or subcommand (template, register, isolate, analyze-imports, manual-entity, dependents, audit, scenarios, scenario-coverage, recapture-stale, change, sync, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors, task-ontrack)';
+            ? 'Step number (1-18) or subcommand (template, register, isolate, analyze-imports, manual-entity, dependents, audit, scenarios, scenario-coverage, recapture-stale, change, sync, debug, design-system, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors, task-ontrack)'
+            : 'Step number (1-18) or subcommand (template, register, isolate, analyze-imports, manual-entity, dependents, audit, scenarios, scenario-coverage, recapture-stale, change, sync, design-system, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors, task-ontrack)';
         let builder = yargs
             .positional('step', {
             type: 'string',
@@ -4796,6 +5541,11 @@ const editorCommand = {
             alias: 'p',
             describe: 'Port to run the web server on',
             default: 3111,
+        })
+            .option('fix', {
+            type: 'boolean',
+            describe: 'For audit: also recapture stale scenarios after displaying results',
+            default: false,
         });
         if (IS_INTERNAL_BUILD) {
             builder = builder
@@ -4871,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 || '');
@@ -4923,9 +5678,11 @@ const editorCommand = {
             fs.writeFileSync(trackingPath, JSON.stringify({ step: state.step, taskCreated: true }, null, 2), 'utf8');
             return;
         }
-        // Subcommand: codeyam editor analyze-imports
+        // Subcommand: codeyam editor analyze-imports [file1.tsx file2.tsx ...]
         if (argv.step === 'analyze-imports') {
-            await handleAnalyzeImports();
+            const { parseAnalyzeImportsArgs } = await import('./editorAnalyzeImportsArgs.js');
+            const requestedPaths = parseAnalyzeImportsArgs(argv.json, argv._);
+            await handleAnalyzeImports(requestedPaths.length > 0 ? { filePaths: requestedPaths } : {});
             return;
         }
         // Subcommand: codeyam editor manual-entity <JSON|@file>
@@ -4938,9 +5695,9 @@ const editorCommand = {
             await handleDependents(argv.json || '');
             return;
         }
-        // Subcommand: codeyam editor audit
+        // Subcommand: codeyam editor audit [--fix]
         if (argv.step === 'audit') {
-            await handleAudit();
+            await handleAudit({ fix: argv.fix || false });
             return;
         }
         // Subcommand: codeyam editor scenarios
@@ -4973,6 +5730,11 @@ const editorCommand = {
             await handleValidateSeed(argv.json || '');
             return;
         }
+        // Subcommand: codeyam editor design-system <id>
+        if (argv.step === 'design-system') {
+            handleDesignSystem(argv.json || '');
+            return;
+        }
         // Subcommand: codeyam editor delete <scenarioId>
         if (argv.step === 'delete') {
             await handleDelete(argv.json || '');
@@ -5046,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');
@@ -5461,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;