catalyst-core 0.2.0-beta.3 → 0.3.0-beta.2

package/mcp_v2/tools/build.js

@@ -1,6 +1,11 @@
 "use strict"
 
-const { makeProjectHelpers, findCatalystRoot } = require("../lib/helpers")
+const {
+    makeProjectHelpers,
+    findCatalystRoot,
+    catalystGeneration,
+    VITE_RUNTIME_VERSION,
+} = require("../lib/helpers")
 
 let _db
 
@@ -18,7 +23,7 @@ const MASTER_FLOWS = {
             step: 1,
             cmd: "catalyst start",
             label: "Start dev server",
-            detail: "Starts webpack-dev-server + SSR Node server on NODE_SERVER_PORT. Hot reload enabled.",
+            detail: "Starts the Vite middleware-mode development server and Catalyst SSR server on NODE_SERVER_PORT. Hot reload and React Fast Refresh are enabled.",
         },
         {
             step: 2,
@@ -33,7 +38,7 @@ const MASTER_FLOWS = {
             step: 1,
             cmd: "catalyst build",
             label: "Production build",
-            detail: "Runs webpack in production mode. Outputs to build/ (or OUTPUT_PATH from config). Includes SSR bundle + client chunks.",
+            detail: "Runs parallel Vite client and SSR builds. Outputs client assets to build/client, the renderer to build/server, Vite manifests under build/.vite, and offline runtime files at the build root.",
         },
         {
             step: 2,
@@ -48,7 +53,7 @@ const MASTER_FLOWS = {
             step: 1,
             cmd: "catalyst build",
             label: "Build",
-            detail: "Production webpack build. Set BUILD_ENV=production in env or config.",
+            detail: "Production Vite client and SSR build. Set BUILD_ENV=production in env or config.",
         },
         {
             step: 2,
@@ -69,7 +74,7 @@ const MASTER_FLOWS = {
             step: 1,
             cmd: "catalyst build",
             label: "Build",
-            detail: "Same webpack build — staging is config-only, not a different build target.",
+            detail: "Same Vite build — staging is config-only, not a different build target.",
         },
         {
             step: 2,
@@ -94,7 +99,7 @@ const MASTER_FLOWS = {
         },
         {
             step: 3,
-            cmd: "npm run build:android",
+            cmd: "npm run buildApp:android",
             label: "Android debug build",
             detail: "Runs buildAppAndroid.js: validates ADB + emulator path from sdkPath, launches emulator (emulatorName), copies web assets to androidProject/, runs Gradle debug build, installs APK.",
         },
@@ -123,11 +128,11 @@ const MASTER_FLOWS = {
             step: 3,
             cmd: "catalyst build",
             label: "Build web assets",
-            detail: "Production webpack build. Assets bundled into AAB.",
+            detail: "Production web build. Assets are consumed by the Android release build.",
         },
         {
             step: 4,
-            cmd: "npm run build:android:release",
+            cmd: "npm run buildApp:android",
             label: "Android release build",
             detail: "Skips emulator validation. Runs Gradle release build. Calls buildAndroidAAB() — renames project, creates/verifies keystore, signs AAB. Output goes to ./deployment/.",
         },
@@ -144,19 +149,19 @@ const MASTER_FLOWS = {
             step: 1,
             cmd: null,
             label: "Pre-check: config",
-            detail: 'Reads WEBVIEW_CONFIG.ios. Requires: appBundleId, simulatorName, buildType (default "debug").',
+            detail: "Reads WEBVIEW_CONFIG and WEBVIEW_CONFIG.ios. Confirm the development URL, appBundleId, simulatorName, plugins, and selected public/ios assets.",
         },
         {
             step: 2,
-            cmd: "catalyst build",
-            label: "Build web assets",
-            detail: "Compiles web app. iOS build embeds these.",
+            cmd: "npm run buildApp:ios",
+            label: "iOS simulator build",
+            detail: "Generates native configuration and plugin code in the package-owned Xcode project, syncs selected assets, compiles with Xcode's Debug configuration, installs the .app, and launches it.",
         },
         {
             step: 3,
-            cmd: "npm run build:ios",
-            label: "iOS simulator build",
-            detail: "Runs buildAppIos.js: generates ConfigConstants.swift from config (bundleId, URL, port, protocol), launches simulator (simulatorName), cleans Xcode artifacts, compiles with xcodebuild, installs .app, launches.",
+            cmd: null,
+            label: "Remote web application",
+            detail: "The iOS shell loads the configured remote URL. buildApp:ios does not bundle the full Catalyst web client, so the target web application must be reachable.",
         },
         {
             step: 4,
@@ -170,31 +175,89 @@ const MASTER_FLOWS = {
         {
             step: 1,
             cmd: null,
+            label: "Deploy the production web application",
+            detail: "Deploy the web application first and confirm its production URL is reachable over HTTPS. The iOS shell loads this remote URL; it does not embed the full web client bundle.",
+        },
+        {
+            step: 2,
+            cmd: null,
             label: "Pre-check: config",
-            detail: 'buildType must be "Release" (capital R — case-sensitive). appBundleId required. If googleSignIn enabled, GoogleService-Info.plist must be present.',
+            detail: "Finalize WEBVIEW_CONFIG, appBundleId, app name, version, incremented build number, access-control rules, plugins, permissions, capabilities, icons, splash assets, and privacy declarations.",
         },
-        { step: 2, cmd: "catalyst build", label: "Build web assets", detail: "Production build." },
         {
             step: 3,
-            cmd: "npm run build:ios",
-            label: "iOS release build",
-            detail: "Same script — build type is driven by WEBVIEW_CONFIG.ios.buildType. Generates ConfigConstants.swift with production URL and bundleId. Xcode compiles Release scheme.",
+            cmd: "npm run buildApp:ios",
+            label: "Prepare the native project",
+            detail: "Run from the consuming Catalyst app root. This generates native configuration and plugin code, syncs selected assets, and performs a Debug native build. It does not create an App Store archive.",
         },
         {
             step: 4,
             cmd: null,
-            label: "Archive + export IPA",
-            detail: "Post-build: archive via Xcode Organizer or xcodebuild -exportArchive. Requires Apple distribution certificate + provisioning profile configured in Xcode.",
+            label: "Open the generated Xcode project",
+            detail: "Open node_modules/catalyst-core/dist/native/iosnativeWebView/iosnativeWebView.xcodeproj (or the resolved package equivalent). Confirm the iosnativeWebView scheme's Archive action uses Release.",
         },
         {
             step: 5,
             cmd: null,
-            label: "App Store submission",
-            detail: "Upload IPA via Transporter or Xcode Organizer. TestFlight for beta before release.",
+            label: "Configure signing and archive",
+            detail: "Select the correct Apple Developer team, distribution signing, capabilities, entitlements, bundle ID, version, and build. Choose a generic iOS device destination, then Product → Archive.",
+        },
+        {
+            step: 6,
+            cmd: null,
+            label: "Validate and upload",
+            detail: "In Xcode Organizer, run Validate App, then Distribute App → TestFlight & App Store and upload the build.",
+        },
+        {
+            step: 7,
+            cmd: null,
+            label: "Complete the release",
+            detail: "Wait for App Store Connect processing, test through TestFlight, complete store metadata and privacy disclosures, select the processed build, and submit it for App Review.",
         },
     ],
 }
 
+const LEGACY_WEB_FLOWS = {
+    web_dev: [
+        {
+            step: 1,
+            cmd: "catalyst start",
+            label: "Start legacy dev server",
+            detail: "Starts the Catalyst 0.2.x webpack development and SSR servers with hot reload.",
+        },
+        {
+            step: 2,
+            cmd: null,
+            label: "Browser / WebView loads",
+            detail: "The browser or native WebView loads the configured development origin.",
+        },
+    ],
+    web_build: [
+        {
+            step: 1,
+            cmd: "catalyst build",
+            label: "Legacy production build",
+            detail: "Runs the Catalyst 0.2.x webpack build, including loadable metadata and SSR output.",
+        },
+        {
+            step: 2,
+            cmd: "catalyst serve",
+            label: "Serve legacy build",
+            detail: "Serves the webpack-era production output for smoke testing.",
+        },
+    ],
+    web_prod: null,
+    web_staging: null,
+}
+LEGACY_WEB_FLOWS.web_prod = MASTER_FLOWS.web_prod.map((step) => ({
+    ...step,
+    detail: step.detail.replace("Vite client and SSR", "legacy webpack"),
+}))
+LEGACY_WEB_FLOWS.web_staging = MASTER_FLOWS.web_staging.map((step) => ({
+    ...step,
+    detail: step.detail.replace("Vite", "legacy webpack"),
+}))
+
 // ─── Architecture diagrams ───────────────────────────────────────────────────
 
 const MASTER_DIAGRAMS = {
@@ -293,18 +356,18 @@ const MASTER_DIAGRAMS = {
         layers: [
             {
                 layer: "web",
-                label: "Webpack (catalyst build)",
-                detail: "Produces: build/public/ (client chunks), build/server.js (SSR bundle). Loadable-stats.json for code-splitting.",
+                label: "Vite (catalyst build)",
+                detail: "Runs client and SSR builds in parallel. Produces build/client, build/server, Vite manifests, categorized assets, and root offline runtime files.",
             },
             {
                 layer: "prepare",
                 label: "catalyst-core prepare",
-                detail: "Compiles catalyst-core/src/ → dist/ via Babel. Copies src/native/ → dist/native/ (androidProject, iosnativeWebView, assets). This is the framework build, not the app build.",
+                detail: "Copies the ESM web runtime into dist and Babel-compiles native/CommonJS compatibility outputs. Package metadata, bin, and dist form one package contract.",
             },
             {
                 layer: "copy",
                 label: "Dev copy workflow",
-                detail: "After prepare: copy catalyst-core/dist/ → test-app/node_modules/catalyst-core/. Also copy package.json (required for Node 20 exports map — ERR_PACKAGE_PATH_NOT_EXPORTED fix).",
+                detail: "After prepare, copy dist, bin, and package.json together. Copying only dist creates a mixed package with incompatible exports and CLI code.",
             },
             {
                 layer: "native",
@@ -316,12 +379,11 @@ const MASTER_DIAGRAMS = {
             "[Framework dev] Edit catalyst-core/src/",
             "→ npm run prepare (in catalyst-core)",
             "→ dist/ updated",
-            "→ Copy dist/ → test-app/node_modules/catalyst-core/",
-            "→ Copy package.json → test-app/node_modules/catalyst-core/package.json",
+            "→ Replace test-app node_modules/catalyst-core dist + bin + package.json together",
             "",
             "[App build] In app project root:",
-            "→ catalyst build  (webpack, outputs build/)",
-            "→ npm run build:android / build:ios",
+            "→ catalyst build (Vite client + SSR output)",
+            "→ npm run buildApp:android / buildApp:ios",
             "→ native build script reads WEBVIEW_CONFIG from config/config.json",
             "→ copies build/ assets into native project",
             "→ compiles native project (Gradle / xcodebuild)",
@@ -405,6 +467,33 @@ const MASTER_DIAGRAMS = {
     },
 }
 
+const LEGACY_BUILD_PIPELINE = {
+    title: "Legacy Build Pipeline (Catalyst 0.2.x)",
+    description: "The webpack-era Catalyst build and native consumption flow.",
+    layers: [
+        {
+            layer: "web",
+            label: "Webpack",
+            detail: "Produces webpack client chunks, SSR output, and @loadable/component metadata.",
+        },
+        {
+            layer: "prepare",
+            label: "Babel prepare",
+            detail: "Compiles catalyst-core source into the legacy dist package.",
+        },
+        {
+            layer: "native",
+            label: "Native build",
+            detail: "buildApp:android and buildApp:ios consume the prepared web and native assets.",
+        },
+    ],
+    flow: [
+        "catalyst build (webpack)",
+        "→ catalyst serve for production-style validation",
+        "→ npm run buildApp:android or npm run buildApp:ios",
+    ],
+}
+
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 function getProjectContext(root) {
@@ -423,6 +512,7 @@ function getProjectContext(root) {
         iosBuildType: (wv.ios?.buildType || "debug").toLowerCase(),
         hasKeystore: !!wv.android?.keystoreConfig,
         hasGoogleSignIn: !!wv.googleSignIn?.enabled,
+        hasNotifications: !!wv.notifications?.enabled,
         hasEcosystem: fileExists("ecosystem.config.js"),
         port: wv.port,
         useHttps: !!wv.useHttps,
@@ -464,6 +554,14 @@ function handle_get_build_flow({ platform, mode, symptom } = {}) {
     }
 
     const ctx = getProjectContext(catalystRoot.dir)
+    const installedVersion = catalystRoot.installedVersion || catalystRoot.catalystVersion
+    const generation = catalystGeneration(installedVersion)
+    if (generation === "unknown") {
+        return {
+            error: "catalyst_version_required",
+            message: `Unable to determine whether this project targets legacy 0.2.x or current ${VITE_RUNTIME_VERSION}+. Confirm the target version before applying build guidance.`,
+        }
+    }
     const p = (platform || "web").toLowerCase()
     const m = (mode || "dev").toLowerCase() // dev | build | production | staging | release
 
@@ -538,7 +636,7 @@ function handle_get_build_flow({ platform, mode, symptom } = {}) {
             )
         }
 
-        const isRelease = m === "release" || ctx.iosBuildType === "release"
+        const isRelease = m === "release"
         flow_key = isRelease ? "ios_release" : "ios_debug"
 
         if (!ctx.wv.ios?.appBundleId) {
@@ -554,13 +652,23 @@ function handle_get_build_flow({ platform, mode, symptom } = {}) {
                 "googleSignIn.enabled=true but iosClientId may be missing — check WEBVIEW_CONFIG.googleSignIn.iosClientId."
             )
         }
-        if (isRelease && ctx.iosBuildType !== "release") {
+        if (isRelease && !ctx.useHttps) {
+            warnings.push(
+                "WEBVIEW_CONFIG.useHttps is not enabled — the App Store flow requires a reachable HTTPS production web application."
+            )
+        }
+        if (isRelease && ctx.hasNotifications) {
             warnings.push(
-                'ios.buildType is not "Release" (case-sensitive). Release builds require exactly "Release" — not "release".'
+                "Push notifications are enabled — review the generated aps-environment entitlement and Release provisioning before archiving."
             )
         }
 
         notes.push(`buildType detected: ${ctx.wv.ios?.buildType || "not set (defaults to debug)"}`)
+        if (isRelease) {
+            notes.push(
+                "ios.buildType does not select the App Store build configuration; buildApp:ios still performs a Debug build. Archive the generated project with the scheme's Release action."
+            )
+        }
         if (ctx.wv.ios?.appBundleId) notes.push(`appBundleId: ${ctx.wv.ios.appBundleId}`)
         if (ctx.wv.ios?.simulatorName) notes.push(`simulatorName: ${ctx.wv.ios.simulatorName}`)
         if (ctx.hasGoogleSignIn) notes.push("googleSignIn: enabled")
@@ -578,7 +686,11 @@ function handle_get_build_flow({ platform, mode, symptom } = {}) {
         mode: flow_key,
         project_root: catalystRoot.dir,
         catalyst_version: catalystRoot.catalystVersion,
-        steps: MASTER_FLOWS[flow_key],
+        catalyst_generation: generation,
+        steps:
+            generation === "legacy" && LEGACY_WEB_FLOWS[flow_key]
+                ? LEGACY_WEB_FLOWS[flow_key]
+                : MASTER_FLOWS[flow_key],
         project_config: notes,
         warnings: warnings.length ? warnings : undefined,
         related_errors: related_errors.length ? related_errors : undefined,
@@ -594,6 +706,7 @@ function handle_get_architecture_diagram({ feature, symptom } = {}) {
     }
 
     const ctx = getProjectContext(catalystRoot.dir)
+    const generation = catalystGeneration(catalystRoot.installedVersion || catalystRoot.catalystVersion)
 
     // Match feature to a diagram key
     const f = (feature || "").toLowerCase()
@@ -625,7 +738,17 @@ function handle_get_architecture_diagram({ feature, symptom } = {}) {
         }
     }
 
-    const diagram = MASTER_DIAGRAMS[diagram_key]
+    if (diagram_key === "build_pipeline" && generation === "unknown") {
+        return {
+            error: "catalyst_version_required",
+            message: `Build architecture differs between legacy 0.2.x and current ${VITE_RUNTIME_VERSION}+. Confirm the target Catalyst version.`,
+        }
+    }
+
+    const diagram =
+        diagram_key === "build_pipeline" && generation === "legacy"
+            ? LEGACY_BUILD_PIPELINE
+            : MASTER_DIAGRAMS[diagram_key]
 
     // ── Annotate with project-specific context ────────────────────────────────
     const project_context = []
@@ -671,6 +794,7 @@ function handle_get_architecture_diagram({ feature, symptom } = {}) {
 
     return {
         feature,
+        catalyst_generation: generation,
         matched_diagram: diagram_key,
         title: diagram.title,
         description: diagram.description,

package/mcp_v2/tools/conversion.js

@@ -1,7 +1,12 @@
 "use strict"
 const fs = require("fs")
 const path = require("path")
-const { makeProjectHelpers, versionOlderThan } = require("../lib/helpers")
+const {
+    makeProjectHelpers,
+    versionOlderThan,
+    catalystGeneration,
+    VITE_RUNTIME_VERSION,
+} = require("../lib/helpers")
 
 // Tasks that require a minimum catalyst-core version.
 // Key = task ID, value = { minVersion, reason, upgradeNote }
@@ -35,6 +40,7 @@ function handle_get_conversion_status({ project_path, include_not_applicable = f
 
     // ── Version gate: read installed catalyst-core version ────────────────────
     const installedVersion = _projectInfo.installedVersion || null
+    const generation = catalystGeneration(installedVersion)
 
     // ── Load project state once ────────────────────────────────────────────────
     const config = readJson("config/config.json")
@@ -78,14 +84,36 @@ function handle_get_conversion_status({ project_path, include_not_applicable = f
         },
 
         T2_ROUTER_DEP: () => {
-            if (!allDeps["@tata1mg/router"])
+            if (generation === "unknown")
+                return {
+                    status: "needs_review",
+                    native_risk: "Router ownership differs between Catalyst 0.2.x and 0.3.x.",
+                    reason: `Unable to determine the installed catalyst-core version. Confirm whether the target is legacy 0.2.x or current ${VITE_RUNTIME_VERSION}+ before changing router dependencies.`,
+                    review_context: {
+                        question: "Which catalyst-core version is this project targeting?",
+                        what_correct_looks_like:
+                            "0.2.x uses @tata1mg/router; 0.3.x+ removes it and imports Catalyst router APIs from catalyst-core.",
+                        what_gap_looks_like:
+                            "Router dependencies and imports are mixed across runtime generations.",
+                    },
+                }
+            if (generation === "legacy") {
+                if (!allDeps["@tata1mg/router"])
+                    return {
+                        status: "gap",
+                        native_risk: "Catalyst 0.2.x requires its external router package for SSR routing.",
+                        reason: "Legacy Catalyst detected but @tata1mg/router is missing",
+                    }
+                return { status: "completed", note: "Legacy 0.2.x external router dependency detected." }
+            }
+            if (allDeps["@tata1mg/router"])
                 return {
                     status: "gap",
                     native_risk:
-                        "react-router-dom does not support SSR + hydration required by catalyst-core. App routing will break on native.",
-                    reason: "@tata1mg/router not in package.json dependencies",
+                        "Catalyst 0.3.x owns the router implementation. Keeping @tata1mg/router can install a second routing runtime and produce incompatible React elements.",
+                    reason: "Remove @tata1mg/router and import router APIs from catalyst-core",
                 }
-            return { status: "completed" }
+            return { status: "completed", note: "Current 0.3.x integrated router contract detected." }
         },
 
         T3_ROUTES_FILE: () => {
@@ -111,6 +139,38 @@ function handle_get_conversion_status({ project_path, include_not_applicable = f
             return { status: "completed" }
         },
 
+        T2b_RUNTIME_DEPS: () => {
+            if (generation !== "current")
+                return {
+                    status: generation === "legacy" ? "completed" : "needs_review",
+                    reason:
+                        generation === "legacy"
+                            ? "Legacy 0.2.x dependency contract retained."
+                            : "Catalyst version is unknown; do not change React versions until the target is confirmed.",
+                    native_risk:
+                        generation === "unknown"
+                            ? "Applying React 19 requirements to an unknown Catalyst runtime can break SSR."
+                            : undefined,
+                    review_context:
+                        generation === "unknown"
+                            ? { question: "Is this project staying on 0.2.x or targeting 0.3.x?" }
+                            : undefined,
+                }
+            const invalid = []
+            if (allDeps.react !== "19.0.0") invalid.push(`react=${allDeps.react || "missing"}`)
+            if (allDeps["react-dom"] !== "19.0.0")
+                invalid.push(`react-dom=${allDeps["react-dom"] || "missing"}`)
+            if (allDeps["@loadable/component"]) invalid.push("@loadable/component is installed")
+            if (invalid.length)
+                return {
+                    status: "gap",
+                    native_risk:
+                        "Mixed React or legacy loadable runtimes can cause invalid React child, hook, or hydration failures.",
+                    reason: invalid.join(", "),
+                }
+            return { status: "completed" }
+        },
+
         T4_DATA_FETCHING: () => {
             const useEffectFiles = grepSrc(
                 /useEffect.*fetch|useEffect.*axios|useEffect.*\.get\(|useEffect.*\.post\(/
@@ -198,6 +258,40 @@ function handle_get_conversion_status({ project_path, include_not_applicable = f
                         "Client entry files are required for hydration. Without them the native WebView loads server HTML but JS never hydrates — app is non-interactive.",
                     reason: `Missing: ${missing.join(", ")}`,
                 }
+            const clientEntry = readText("client/index.js") || ""
+            if (generation === "current" && /@loadable\/component|loadableReady/.test(clientEntry))
+                return {
+                    status: "gap",
+                    native_risk:
+                        "Catalyst 0.3.x uses its Vite split hydration contract; loadableReady belongs to the legacy webpack runtime.",
+                    reason: "Replace loadableReady with hydrationReady from catalyst-core",
+                }
+            return { status: "completed" }
+        },
+
+        T7b_NATIVE_SCRIPTS: () => {
+            const scripts = pkg.scripts || {}
+            const required = [
+                "buildApp",
+                "buildApp:ios",
+                "buildApp:android",
+                "setupEmulator",
+                "setupEmulator:ios",
+                "setupEmulator:android",
+            ]
+            const missing = required.filter((name) => !scripts[name])
+            if (missing.length)
+                return {
+                    status: "gap",
+                    native_risk: `Native Catalyst commands are unavailable: ${missing.join(", ")}.`,
+                    reason: `Missing package scripts: ${missing.join(", ")}`,
+                }
+            if (generation === "current" && (scripts.devBuild || scripts.devServe))
+                return {
+                    status: "gap",
+                    native_risk: "devBuild and devServe were removed from the Catalyst 0.3.x CLI.",
+                    reason: "Remove devBuild/devServe and use start for development or build + serve for production",
+                }
             return { status: "completed" }
         },
 
@@ -657,6 +751,13 @@ function handle_get_conversion_status({ project_path, include_not_applicable = f
         project: pkg.name || root,
         scanned_at: new Date().toISOString(),
         catalyst_core_version: installedVersion || "unknown",
+        catalyst_generation: generation,
+        guidance:
+            generation === "unknown"
+                ? `Specify a target Catalyst version before applying router, build, or hydration changes. Current Vite guidance starts at ${VITE_RUNTIME_VERSION}.`
+                : generation === "legacy"
+                  ? "Using legacy Catalyst 0.2.x webpack/router guidance. Request an upgrade plan explicitly to target 0.3.x."
+                  : "Using current Catalyst 0.3.x Vite/integrated-router guidance.",
         project_context,
         ...(versionBanner ? { version_warning: versionBanner } : {}),
         summary: {

package/mcp_v2/tools/tasks.js

@@ -2,7 +2,7 @@
 
 const fs = require("fs")
 const path = require("path")
-const { findCatalystRoot } = require("../lib/helpers")
+const { findCatalystRoot, catalystGeneration } = require("../lib/helpers")
 const conversion = require("./conversion")
 
 let _db
@@ -597,33 +597,34 @@ function appendToMdFindings(projectRoot, slug, finding) {
 
 // Commands that are verified to exist in catalyst-core projects
 const VALID_COMMANDS = new Set([
-    "npm run build:android",
-    "npm run build:android:release",
-    "npm run build:ios",
+    "npm run start",
+    "npm run build",
+    "npm run serve",
     "npm run buildApp:android",
     "npm run buildApp:ios",
-    "npm run buildApp:android:release",
-    "npm run buildApp:ios:release",
     "npm run setupEmulator:android",
     "npm run setupEmulator:ios",
-    "npm run devBuild",
-    "npm run devServe",
     "npm run prepare",
     "node .catalyst/mcp/setup.js",
 ])
 
-function validateStepCommands(steps) {
+function validateStepCommands(steps, generation) {
+    const validCommands = new Set(VALID_COMMANDS)
+    if (generation === "legacy") {
+        validCommands.add("npm run devBuild")
+        validCommands.add("npm run devServe")
+    }
     const invalid = []
     for (const s of steps) {
         const text = `${typeof s === "string" ? s : (s.title || "") + " " + (s.detail || "")}`
         const cmds = text.match(/npm [\w:]+(?:\s[\w:]+)?|npx [\w@/-]+|node [\w./]+/g) || []
         for (const cmd of cmds) {
-            if (!VALID_COMMANDS.has(cmd)) {
+            if (!validCommands.has(cmd)) {
                 invalid.push(cmd)
             }
         }
     }
-    return invalid
+    return { invalid, validCommands }
 }
 
 function handle_create_task_plan({ goal, steps: customSteps } = {}) {
@@ -650,13 +651,16 @@ function handle_create_task_plan({ goal, steps: customSteps } = {}) {
 
     if (customSteps && Array.isArray(customSteps) && customSteps.length) {
         // Validate any commands in custom steps against known catalyst commands
-        const invalidCmds = validateStepCommands(customSteps)
+        const { invalid: invalidCmds, validCommands } = validateStepCommands(
+            customSteps,
+            catalystGeneration(catalystRoot.installedVersion || catalystRoot.catalystVersion)
+        )
         if (invalidCmds.length > 0) {
             return {
                 error: "invalid_commands_in_steps",
-                message: `Steps contain commands that do not exist in catalyst-core projects: ${invalidCmds.join(", ")}. Do not invent commands. Valid catalyst commands are: ${[...VALID_COMMANDS].join(", ")}. For conversion/migration goals, omit steps entirely — auto-generation runs live file detection and builds accurate steps.`,
+                message: `Steps contain commands that do not exist for this catalyst-core generation: ${invalidCmds.join(", ")}. Do not invent commands. Valid commands are: ${[...validCommands].join(", ")}. For conversion/migration goals, omit steps entirely so live detection can generate version-aware steps.`,
                 invalid_commands: invalidCmds,
-                valid_commands: [...VALID_COMMANDS],
+                valid_commands: [...validCommands],
             }
         }
         steps = customSteps.map((s, i) => ({