catalyst-core 1.1.0 → 1.2.0-canary.2

package/mcp_v2/knowledge-base.json

@@ -154,7 +154,7 @@
     {
         "section": "build_system",
         "title": "WEBVIEW_CONFIG Location and Schema",
-        "content": "Location: config/config.json. Schema: { port, android: { buildType, sdkPath, emulatorName, cachePattern }, ios: { buildType, appBundleId, simulatorName, cachePattern } }. cachePattern is comma-separated globs: *.css,*.js,*.png,*.svg,*.jpg",
+        "content": "Location: config/config.json. Schema (catalyst-core 1.3.0+): { appId, appName, url, allowPrivateHost, LOCAL_IP: 'localhost', port, android: { emulatorName, sdkPath, cachePattern, buildOptimisation }, ios: { developmentTeam, simulatorName, deviceUDID, exportMethod, cachePattern } }. appId is the Android application id and iOS bundle id and wins over android.packageName / ios.appBundleId; appName wins over the per-platform appName. url is the https origin a release build loads. Every android/ios key is optional; buildType 'release' is deprecated in favour of --release. cachePattern is comma-separated globs: *.css,*.js,*.png,*.svg,*.jpg",
         "layer": "Config",
         "source": "static",
         "tags": ["config", "build"]
@@ -170,7 +170,7 @@
     {
         "section": "build_system",
         "title": "iOS Build Pipeline",
-        "content": "npm run buildApp:ios generates ConfigConstants.swift and plugin metadata from WEBVIEW_CONFIG, syncs selected public/ios assets into the package-owned Xcode project, detects a physical device or launches a simulator, cleans Xcode artifacts, compiles with the Debug configuration, and installs and launches the .app. It does not bundle the full Catalyst web client and does not create an App Store archive. The generated project is located under the resolved catalyst-core package at dist/native/iosnativeWebView/iosnativeWebView.xcodeproj.",
+        "content": "npm run ios (catalyst buildApp:ios) checks full Xcode and offers the licence and first-launch steps, installs a simulator runtime, uses an existing iPhone simulator (ios.simulatorName, else the last pick, a booted one or the newest; 'Catalyst iPhone' is created after asking only when there is none), picks the target (simulator by default; a terminal run asks when an iPhone is connected; --device uses the iPhone; the pick is remembered in .catalyst/local.json), starts catalyst start when nothing answers and waits for it, generates ConfigConstants.swift and plugin metadata from WEBVIEW_CONFIG, syncs public/ios assets into the package-owned Xcode project, compiles with the Debug configuration, and installs and launches the .app. The simulator loads the dev server on localhost; an iPhone on the Mac's <LocalHostName>.local (else the LAN IP), with NSAllowsLocalNetworking in debug, and needs ios.developmentTeam plus an Apple account signed in to Xcode once (a free account works). config.json is never written. With --release (or the deprecated ios.buildType release) it archives and exports the signed store IPA instead. The generated project is located under the resolved catalyst-core package at dist/native/iosnativeWebView/iosnativeWebView.xcodeproj.",
         "layer": "Build",
         "source": "static",
         "tags": ["ios", "build", "buildApp:ios", "debug", "xcode"],
@@ -181,17 +181,19 @@
     },
     {
         "section": "build_system",
-        "title": "Catalyst iOS Production Release Flow (0.2.x and 0.3.x)",
-        "content": "Catalyst 0.2.x and 0.3.x use the same iOS production-release flow: (1) deploy the production web application and verify its HTTPS URL, (2) finalize WEBVIEW_CONFIG, bundle ID, app version/build, plugins, permissions, capabilities, icons, splash assets, access-control rules, and privacy declarations, (3) run npm run buildApp:ios from the consuming app root to prepare the package-owned native project and perform its Debug build, (4) open the resolved catalyst-core package's dist/native/iosnativeWebView/iosnativeWebView.xcodeproj, (5) confirm the iosnativeWebView scheme's Archive action uses Release, configure Release signing and capabilities, choose a generic iOS device destination, and run Product -> Archive, (6) Validate App and upload with Distribute App -> TestFlight & App Store, then (7) finish TestFlight testing, App Store Connect metadata, build selection, and App Review submission. buildApp:ios does not create the final App Store artifact.",
+        "title": "Catalyst Native Release Flow (1.3.0+)",
+        "content": "From catalyst-core 1.3.0 the store builds need no Xcode or Android Studio UI. (1) Deploy the web app over HTTPS and set WEBVIEW_CONFIG.url (or pass --url); localhost, private, .local and example hosts fail with NATIVE-001 unless allowPrivateHost is true. (2) Set WEBVIEW_CONFIG.appId to your own reverse-DNS id (com.example.* and template ids fail with NATIVE-003) and the version in package.json. The build number is the minutes since 2024-01-01 UTC, or CATALYST_BUILD_NUMBER (NATIVE-002 if invalid). (3) Android: npm run android:release. The first run in a terminal creates the upload key in credentials/android/ (never without a terminal, ANDROID-005), refuses if the app is already on Google Play, and writes build-output/android/<version>-<build>/<name>.aab plus upload_certificate.pem. (4) iOS: put signing files in credentials/ios/: AuthKey_<KEYID>.p8 (Admin-role App Store Connect API key) plus signing.properties with ascIssuerId for cloud signing (needs ios.developmentTeam), or one .p12 and .mobileprovision plus p12Password for local signing. npm run ios:release archives (Release, generic/platform=iOS), exports with ios.exportMethod (default app-store-connect) and writes build-output/ios/<version>-<build>/<name>.ipa and <name>-dSYMs.zip, with ITSAppUsesNonExemptEncryption=false. (5) Back up and CI: catalyst credentials:export android|ios prints the folder as one value for the CATALYST_ANDROID_CREDENTIALS / CATALYST_IOS_CREDENTIALS secret (48 KB limit). (6) Upload is manual: Play Console internal testing; Apple's Transporter app for TestFlight. A second release with the same version and build number (two in one minute) fails with NATIVE-011; an app id that is not a valid Android package name or iOS bundle id fails with NATIVE-010. A shipped WEBVIEW_CONFIG.ios.version object still sets the iOS version and build number (deprecated; CATALYST_BUILD_NUMBER wins). Errors: IOS-010 signing not set up, IOS-011 API key incomplete, IOS-012 p12/profile inputs, IOS-013 export method. There is no --build-number, no --no-sign and no WEBVIEW_CONFIG.release block.",
         "layer": "Build",
         "source": "static",
         "tags": [
             "ios",
+            "android",
             "release",
             "production",
-            "0.2.x",
-            "0.3.x",
+            "1.3.0",
             "buildApp:ios",
+            "buildApp:android",
+            "credentials",
             "xcode",
             "archive",
             "app-store",
@@ -205,7 +207,7 @@
     {
         "section": "build_system",
         "title": "Generated iOS Project Signing and Persistence",
-        "content": "The generated Xcode project is package-owned state. Its shared xcconfig is regenerated with development-oriented code-signing defaults, and the bundled push entitlement can use aps-environment=development. Before an App Store archive, review the Release team, distribution signing, provisioning, capabilities, and entitlements in Xcode. Run the final npm run buildApp:ios before release-only Xcode changes: later Catalyst generation, package upgrades, or dependency installation can replace or regenerate native config constants, shared Xcode configuration, plist and entitlement content, generated plugin code/resources, selected project-file entries, and assets. Do not treat manual edits inside the generated project as durable app configuration.",
+        "content": "The generated Xcode project is package-owned state, regenerated by every build and package install, so keep release settings in config/config.json and signing files in credentials/ios/. Shared.xcconfig is written per build: CODE_SIGN_STYLE Automatic for ios.developmentTeam (cloud signing with the App Store Connect API key from credentials/ios/, else the Apple account in Xcode), or Manual with the profile when credentials/ios/ holds a .p12 and .mobileprovision (imported into a temporary keychain and removed after the build) or ios.provisioningProfile is set. The project carries no team or profile of its own. The aps-environment entitlement is only written when notifications.enabled is true (development for automatic signing, which export turns into production; production for a manually signed release). The app bundles PrivacyInfo.xcprivacy and a localhost.p12 generated per build for the in-app HTTPS server.",
         "layer": "Build",
         "source": "static",
         "tags": [
@@ -226,7 +228,7 @@
     {
         "section": "build_system",
         "title": "Legacy 0.2.x Build NPM Scripts",
-        "content": "All catalyst npm scripts to add to package.json scripts block (each maps to: catalyst <scriptName>): devBuild \u2014 dev web build. devServe \u2014 dev server. buildApp \u2014 builds native apps. buildApp:android \u2014 Android native app build. buildApp:ios \u2014 iOS native project preparation and Debug build. buildApp:android:release \u2014 Android release build. setupEmulator \u2014 sets up both emulators. setupEmulator:android \u2014 sets up Android AVD. setupEmulator:ios \u2014 sets up iOS simulator. There is no separate buildApp:ios:release flow: run buildApp:ios, then create the production archive from the generated Xcode project's Release Archive action. NOTE: build:android / build:android:release / build:ios do NOT exist in catalyst \u2014 common mistake. Missing any script = that npm run command fails.",
+        "content": "All catalyst npm scripts to add to package.json scripts block (each maps to: catalyst <scriptName>): devBuild \u2014 dev web build. devServe \u2014 dev server. buildApp \u2014 builds native apps. buildApp:android \u2014 Android native app build. buildApp:ios \u2014 iOS Debug build and run (add -- --release --build-number <n> for the signed store IPA). buildApp:android:release \u2014 Android release build. setupEmulator \u2014 sets up both emulators. setupEmulator:android \u2014 sets up Android AVD. setupEmulator:ios \u2014 sets up iOS simulator. There is no separate buildApp:ios:release script: pass --release to buildApp:ios. NOTE: build:android / build:android:release / build:ios do NOT exist in catalyst \u2014 common mistake. Missing any script = that npm run command fails.",
         "layer": "Build",
         "source": "static",
         "tags": ["build", "scripts", "package.json", "native"]
@@ -466,7 +468,7 @@
     {
         "section": "webview_config",
         "title": "Real WEBVIEW_CONFIG Example",
-        "content": "Full WEBVIEW_CONFIG example (as of canary.19+): { port: '3005', LOCAL_IP: '192.168.0.11', useHttps: false, appInfo: 'android-5Feb2026-v2.1.0', cachePattern: '*.css', accessControl: { enabled: false, allowedUrls: ['*.yourdomain.com*', 'http://localhost:*'] }, android: { appName: 'MyApp', packageName: 'com.example.app', buildType: 'debug', sdkPath: '/Users/user/Android/', emulatorName: 'Pixel_5_API_30', cachePattern: '*.css,*.js,*.png', security: { mode: 'custom', allowBackup: true } }, ios: { appBundleId: 'com.example.app', appName: 'MyApp', buildType: 'debug', simulatorName: 'iPhone 17 Pro', cachePattern: '*.css,*.js', accessControl: { enabled: true, allowedUrls: ['*.yourdomain.com*', 'http://localhost:*'] } }, splashScreen: { backgroundColor: '#ffffff', duration: 2000, imageWidth: 400, imageHeight: 200, cornerRadius: 20 }, notifications: { enabled: true, color: \"#007AFF\" } }. Note: splashScreen is INSIDE WEBVIEW_CONFIG, not at top-level config.json. Note canary.19 change: iOS has its OWN accessControl block separate from top-level accessControl.",
+        "content": "Full WEBVIEW_CONFIG example (catalyst-core 1.3.0+): { appId: 'com.yourcompany.app', appName: 'MyApp', url: 'https://www.yourdomain.com', LOCAL_IP: 'localhost', port: '3005', appInfo: 'android-5Feb2026-v2.1.0', cachePattern: '*.css', accessControl: { enabled: false, allowedUrls: ['*.yourdomain.com*', 'http://localhost:*'] }, android: { cachePattern: '*.css,*.js,*.png', security: { mode: 'custom', allowBackup: true } }, ios: { developmentTeam: 'ABCDE12345', cachePattern: '*.css,*.js', accessControl: { enabled: true, allowedUrls: ['*.yourdomain.com*', 'http://localhost:*'] } }, splashScreen: { backgroundColor: '#ffffff', duration: 2000, imageWidth: 400, imageHeight: 200, cornerRadius: 20 }, notifications: { enabled: true, color: \"#007AFF\" } }. Note: splashScreen is INSIDE WEBVIEW_CONFIG, not at top-level config.json. Note canary.19 change: iOS has its OWN accessControl block separate from top-level accessControl. LOCAL_IP stays localhost: debug builds reach the dev server through adb reverse (Android) or the Mac's .local name (iPhone).",
         "layer": "Config",
         "source": "extracted:config/config.json",
         "tags": ["config", "example"]
@@ -482,7 +484,7 @@
     {
         "section": "config_structure",
         "title": "WEBVIEW_CONFIG Required Fields",
-        "content": "WEBVIEW_CONFIG field reference (from buildAppAndroid.js + buildAppIos.js source):\n\nTOP-LEVEL (both platforms):\n- port (string, required) \u2014 web server port e.g. \"3005\"\n- LOCAL_IP (string, required) \u2014 machine LAN IP e.g. \"192.168.0.11\". NOT localhost \u2014 emulator cannot resolve it\n- appInfo (string, required) \u2014 build identifier e.g. \"android-5Feb2026-v2.1.0\". Missing = iOS build breaks\n- useHttps (boolean, optional) \u2014 default false\n- cachePattern (string, optional) \u2014 comma-separated globs e.g. \"*.css\"\n- accessControl.enabled (boolean, optional) \u2014 default false\n- accessControl.allowedUrls (array, required if enabled) \u2014 URL patterns\n\nANDROID (WEBVIEW_CONFIG.android):\n- sdkPath (string, REQUIRED) \u2014 abs path to Android SDK. Build exits immediately without it\n- emulatorName (string, REQUIRED for debug) \u2014 AVD name. Run: emulator -list-avds\n- appName (string, optional) \u2014 default \"Catalyst Application\"\n- packageName (string, optional) \u2014 e.g. com.company.app. Derived from appName if missing\n- buildType (string, optional) \u2014 \"debug\" or \"release\". Default \"debug\"\n- keystore or keystoreConfig (required for release buildType only)\n- buildOptimisation (boolean, optional) \u2014 default false\n- cachePattern (string, optional)\n\nIOS (WEBVIEW_CONFIG.ios):\n- appBundleId (string, optional) \u2014 default \"com.debug.webview\". Must set for distribution\n- appName (string, optional) \u2014 default \"Catalyst Application\"\n- simulatorName (string, optional) \u2014 auto-detected if missing. e.g. \"iPhone 17 Pro\"\n- buildType (string, optional) \u2014 may label copied Debug output but does not select the Xcode build configuration or create an App Store archive\n- deviceUDID (string, optional) \u2014 physical device builds only\n- developmentTeam (string, required if deviceUDID set) \u2014 Apple Developer Team ID\n- cachePattern (string, optional)\n\nFor iOS production, run buildApp:ios to prepare the generated project, then archive the iosnativeWebView scheme using its Release Archive action in Xcode.",
+        "content": "WEBVIEW_CONFIG field reference (catalyst-core 1.3.0+, from nativeConfig.js):\n\nTOP-LEVEL (both platforms):\n- appId (string, required for release): Android application id and iOS bundle id, e.g. com.company.app. Wins over android.packageName / ios.appBundleId / ios.bundleIdentifier. Release refuses com.example.* (NATIVE-003)\n- appName (string, optional): name under the icon; wins over android.appName / ios.appName\n- url (string, required for release): https origin the release app loads, no path. --url overrides. Debug builds ignore it\n- allowPrivateHost (boolean, optional): lets a release load a private host\n- LOCAL_IP (string, optional): keep 'localhost'. Debug builds work out the dev server address; apps without url still use LOCAL_IP/port/useHttps as the release host\n- port (string, optional): dev server port when NODE_SERVER_PORT is not set\n- appInfo (string, required): build identifier e.g. \"android-5Feb2026-v2.1.0\". Missing = iOS build breaks\n- cachePattern (string, optional): comma-separated globs e.g. \"*.css\"\n- accessControl.enabled / allowedUrls: URL allowlist; debug builds add the dev server origin\n\nANDROID (WEBVIEW_CONFIG.android, all optional):\n- sdkPath: else ANDROID_HOME, ANDROID_SDK_ROOT, default location; installed when missing\n- emulatorName: else the last used or catalyst-api36, created when missing\n- buildType: deprecated; 'release' builds a release with a warning\n- outputPath: release folder instead of build-output/android\n- buildOptimisation, cachePattern\n\nIOS (WEBVIEW_CONFIG.ios, all optional):\n- developmentTeam: Apple team ID, needed for an iPhone and for cloud or Xcode-account signing (IOS-010)\n- simulatorName: simulator to use when it exists; else the last pick, a booted iPhone simulator or the newest one. 'Catalyst iPhone' is created only when there is no iPhone simulator\n- deviceUDID: which iPhone --device uses without a terminal\n- provisioningProfile: installed profile name for manual signing\n- exportMethod: app-store-connect (default), release-testing, enterprise or debugging\n- buildType: deprecated; 'release' builds the store IPA with a warning\n\nVersion comes from package.json; signing files live in credentials/android/ and credentials/ios/, never in config.json.",
         "layer": "Config",
         "source": "static",
         "tags": ["config", "WEBVIEW_CONFIG", "android", "ios", "required", "fields"]
@@ -1281,7 +1283,7 @@
     {
         "section": "build_system",
         "title": "Catalyst 0.3.x CLI Commands",
-        "content": "Current web commands are catalyst start, catalyst build, catalyst serve, and catalyst serve:inspect. devBuild and devServe are legacy 0.2.x commands and are not accepted by the 0.3.x CLI. Native commands remain buildApp, buildApp:ios, buildApp:android, setupEmulator, setupEmulator:ios, and setupEmulator:android. catalyst-core 1.0.2 OUTPUT: every command prints a short header, one line per step with timing, and one diagnostic block on failure. Flags: --verbose shows every step and, on failure, the full tool output (bundler, Gradle); --debug also prints stacks and the environment. Child processes inherit the mode through CATALYST_OUTPUT_MODE=verbose|debug. Failures carry registry codes from the error catalog (for example BUNDLE-000, ANDROID-000, IOS-000, CCA-001); use the explain_error tool for any code. catalyst serve (1.0.2+) exits when there is no build in BUILD_OUTPUT_PATH and refuses a stale build with PREFLIGHT-022 when PUBLIC_STATIC_ASSET_URL, PUBLIC_STATIC_ASSET_PATH or a CLIENT_ENV_VARIABLES value in config/config.json changed after catalyst build (the build records them in <BUILD_OUTPUT_PATH>/.catalyst-build.json; a build from an older version has no record, so serve warns and skips the check until you rebuild). Fix: run catalyst build again, then catalyst serve. catalyst serve passes the app's own stdout/stderr through unchanged, so JSON log shippers keep working. Scripts that parsed the old CLI text output must be updated.",
+        "content": "Current web commands are catalyst start, catalyst build, catalyst serve, and catalyst serve:inspect. devBuild and devServe are legacy 0.2.x commands and are not accepted by the 0.3.x CLI. Native commands are buildApp:android and buildApp:ios (template scripts android, ios, android:release, ios:release; flags --release, --device, --url, --yes, --accept-licenses; nothing is prompted without a TTY or with CI set, NATIVE-005 names the missing flag), credentials:export <android|ios>, and the install-only setupEmulator:android and setupEmulator:ios. catalyst-core 1.0.2 OUTPUT: every command prints a short header, one line per step with timing, and one diagnostic block on failure. Flags: --verbose shows every step and, on failure, the full tool output (bundler, Gradle); --debug also prints stacks and the environment. Child processes inherit the mode through CATALYST_OUTPUT_MODE=verbose|debug. Failures carry registry codes from the error catalog (for example BUNDLE-000, ANDROID-000, IOS-000, CCA-001); use the explain_error tool for any code. catalyst serve (1.0.2+) exits when there is no build in BUILD_OUTPUT_PATH and refuses a stale build with PREFLIGHT-022 when PUBLIC_STATIC_ASSET_URL, PUBLIC_STATIC_ASSET_PATH or a CLIENT_ENV_VARIABLES value in config/config.json changed after catalyst build (the build records them in <BUILD_OUTPUT_PATH>/.catalyst-build.json; a build from an older version has no record, so serve warns and skips the check until you rebuild). Fix: run catalyst build again, then catalyst serve. catalyst serve passes the app's own stdout/stderr through unchanged, so JSON log shippers keep working. Scripts that parsed the old CLI text output must be updated.",
         "layer": "Build",
         "source": "static",
         "tags": [

package/mcp_v2/test/config.test.ts

@@ -109,3 +109,43 @@ describe("check_config: splash screen", () => {
         expect(findings(r).some((f) => f.field === "WEBVIEW_CONFIG.splashScreen.minDuration")).toBe(false)
     })
 })
+
+describe("check_config: native port and cache patterns", () => {
+    const fieldsOf = (list: Array<{ field: string }>) => list.map((f) => f.field)
+
+    it("accepts WEBVIEW_CONFIG.port as the template's string or a number", () => {
+        for (const port of ["3005", 3005]) {
+            const r = handle_check_config({
+                project_path: makeSplashProject({ NODE_SERVER_PORT: 3005, WEBVIEW_CONFIG: { port } }),
+            })
+            expect(fieldsOf(r.issues)).not.toContain("WEBVIEW_CONFIG.port")
+            expect(fieldsOf(r.warnings)).not.toContain("WEBVIEW_CONFIG.port")
+            expect(fieldsOf(r.passed)).toContain("WEBVIEW_CONFIG.port")
+        }
+    })
+
+    it("still rejects a port that is not a port", () => {
+        for (const port of ["abc", 0, 70000, true]) {
+            const r = handle_check_config({ project_path: makeSplashProject({ WEBVIEW_CONFIG: { port } }) })
+            expect(fieldsOf(r.issues)).toContain("WEBVIEW_CONFIG.port")
+        }
+    })
+
+    it("reads ios.cachePattern as an array, and warns about a comma-separated string", () => {
+        const ok = handle_check_config({
+            project_path: makeSplashProject({ WEBVIEW_CONFIG: { ios: { cachePattern: ["*.css", "*.js"] } } }),
+        })
+        expect(fieldsOf(ok.passed)).toContain("WEBVIEW_CONFIG.ios.cachePattern")
+        expect(fieldsOf(ok.warnings)).not.toContain("WEBVIEW_CONFIG.ios.cachePattern")
+
+        const commas = handle_check_config({
+            project_path: makeSplashProject({ WEBVIEW_CONFIG: { ios: { cachePattern: "*.css,*.js" } } }),
+        })
+        expect(fieldsOf(commas.warnings)).toContain("WEBVIEW_CONFIG.ios.cachePattern")
+
+        const wrong = handle_check_config({
+            project_path: makeSplashProject({ WEBVIEW_CONFIG: { ios: { cachePattern: 5 } } }),
+        })
+        expect(fieldsOf(wrong.warnings)).toContain("WEBVIEW_CONFIG.ios.cachePattern")
+    })
+})

package/mcp_v2/tools/build.js

@@ -29,7 +29,7 @@ const MASTER_FLOWS = {
             step: 2,
             cmd: null,
             label: "Browser / WebView loads",
-            detail: "Web: browser hits localhost. Universal: WebView loads http://<LOCAL_IP>:<port>. IP auto-detected by catalyst at startup.",
+            detail: "Web: browser hits localhost. Universal debug builds load the same dev server: Android over adb reverse on localhost, the iOS simulator on localhost, an iPhone on <mac>.local. Nothing is written to config.json.",
         },
     ],
 
@@ -87,27 +87,27 @@ const MASTER_FLOWS = {
     android_debug: [
         {
             step: 1,
-            cmd: null,
-            label: "Pre-check: config",
-            detail: 'Reads config/config.json → WEBVIEW_CONFIG.android. Requires: sdkPath, emulatorName, buildType="debug" (or "Debug").',
+            cmd: "npm run android",
+            label: "Android debug build",
+            detail: "catalyst buildApp:android. Checks JDK 17 to 23 and the Android SDK (sdkPath, ANDROID_HOME, ANDROID_SDK_ROOT, default location) and installs what is missing after asking (--yes / --accept-licenses without a terminal). Since 1.0.2 Gradle runs behind one progress line; on failure --verbose or --debug add the ANDROID-000 report.",
         },
         {
             step: 2,
-            cmd: "catalyst build",
-            label: "Build web assets",
-            detail: "Compiles web app to build/. Android build embeds these as the WebView content.",
+            cmd: null,
+            label: "Target",
+            detail: "The emulator (android.emulatorName, else the last one used, else catalyst-api36, created when missing). With a phone connected, a terminal run asks; --device uses the phone (ANDROID_SERIAL picks one without a terminal). The pick is remembered in .catalyst/local.json.",
         },
         {
             step: 3,
-            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. Since 1.0.2 Gradle runs behind one progress line that shows the current task; on failure --verbose or --debug add the ANDROID-000 report with the full Gradle output.",
+            cmd: null,
+            label: "Dev server",
+            detail: "Starts `catalyst start` when nothing answers on NODE_SERVER_PORT and waits until it answers; a running server is reused. No separate npm start needed.",
         },
         {
             step: 4,
             cmd: null,
-            label: "WebView startup",
-            detail: "App launches → WebView loads http://<LOCAL_IP>:<port> → bridge initialises → hooks available.",
+            label: "Install, reverse, launch",
+            detail: "Installs <appId>.debug, runs adb reverse for NODE_SERVER_PORT, the HMR port and every localhost:<port> in config.json, then launches. The app loads http://localhost:<port>; WEBVIEW_CONFIG.url is ignored in debug.",
         },
     ],
 
@@ -116,52 +116,46 @@ const MASTER_FLOWS = {
             step: 1,
             cmd: null,
             label: "Pre-check: config",
-            detail: 'Requires WEBVIEW_CONFIG.android.buildType="release". keystoreConfig must be present with real passwords (not placeholder values).',
+            detail: "WEBVIEW_CONFIG.url (or --url) is the production origin; a localhost/LAN/.local/example host fails with NATIVE-001 unless allowPrivateHost is true. appId must not be com.example.* or a template id (NATIVE-003). Version from package.json; build number = minutes since 2024-01-01 UTC, or CATALYST_BUILD_NUMBER.",
         },
         {
             step: 2,
             cmd: null,
-            label: "Pre-check: keystore fields",
-            detail: "Required keystoreConfig fields: keyAlias, storePassword, keyPassword, organizationInfo (companyName, city, state, countryCode).",
+            label: "Pre-check: upload key",
+            detail: "credentials/android/upload.jks + keystore.properties. The first release in a terminal asks to create it (never without a terminal, even with --yes: ANDROID-005) and refuses if the app is already on Google Play. Back it up with `catalyst credentials:export android`; CI reads the same value from CATALYST_ANDROID_CREDENTIALS.",
         },
         {
             step: 3,
-            cmd: "catalyst build",
-            label: "Build web assets",
-            detail: "Production web build. Assets are consumed by the Android release build.",
-        },
-        {
-            step: 4,
-            cmd: "npm run buildApp:android",
+            cmd: "npm run android:release",
             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/.",
+            detail: "catalyst buildApp:android --release. Signs the AAB with the upload key (passwords via environment, never argv). targetSdk 36, 16 KB aligned native libraries. Run `catalyst build` first only with android.buildOptimisation.",
         },
         {
-            step: 5,
+            step: 4,
             cmd: null,
             label: "AAB output",
-            detail: "Signed .aab in ./deployment/. Upload to Play Console. Not directly installable — use bundletool to test on device.",
+            detail: "build-output/android/<version>-<build>/<name>.aab and upload_certificate.pem. Upload to Play Console (Testing > Internal testing) by hand; Catalyst does not publish.",
         },
     ],
 
     ios_debug: [
         {
             step: 1,
-            cmd: null,
-            label: "Pre-check: config",
-            detail: "Reads WEBVIEW_CONFIG and WEBVIEW_CONFIG.ios. Confirm the development URL, appBundleId, simulatorName, plugins, and selected public/ios assets.",
+            cmd: "npm run ios",
+            label: "iOS debug build",
+            detail: 'catalyst buildApp:ios. Checks full Xcode, offers the Xcode licence and first-launch steps, installs a simulator runtime, and uses an existing iPhone simulator (ios.simulatorName, else the last pick, a booted one or the newest), creating "Catalyst iPhone" after asking only when there is none.',
         },
         {
             step: 2,
-            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.",
+            cmd: null,
+            label: "Target",
+            detail: "Simulator by default; with an iPhone connected a terminal run asks; --device uses the iPhone (ios.deviceUDID picks one without a terminal). The pick is remembered in .catalyst/local.json. An iPhone needs ios.developmentTeam and an Apple account signed in to Xcode once (a free account works).",
         },
         {
             step: 3,
             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.",
+            label: "Dev server",
+            detail: "Starts `catalyst start` when nothing answers and waits. Simulator: localhost. iPhone: <LocalHostName>.local (else the LAN IP), with the server bound to the network; a server already running for localhost only fails with NATIVE-006. Debug builds add NSAllowsLocalNetworking and ignore WEBVIEW_CONFIG.url.",
         },
         {
             step: 4,
@@ -175,44 +169,26 @@ 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.",
+            label: "Pre-check: config",
+            detail: "WEBVIEW_CONFIG.url (or --url), appId (not com.example.*), ios.developmentTeam for cloud or Xcode-account signing (else IOS-010). Version from package.json, build number from the clock or CATALYST_BUILD_NUMBER.",
         },
         {
             step: 2,
             cmd: null,
-            label: "Pre-check: config",
-            detail: "Finalize WEBVIEW_CONFIG, appBundleId, app name, version, incremented build number, access-control rules, plugins, permissions, capabilities, icons, splash assets, and privacy declarations.",
+            label: "Pre-check: signing",
+            detail: "credentials/ios/ (CI: CATALYST_IOS_CREDENTIALS from `catalyst credentials:export ios`). Cloud signing: AuthKey_<KEYID>.p8 (Admin-role App Store Connect API key) + signing.properties with ascIssuerId. Local signing: one .p12 + one .mobileprovision + p12Password in signing.properties (temporary keychain, removed after the build). Bad key inputs: IOS-011; bad p12/profile: IOS-012.",
         },
         {
             step: 3,
-            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.",
+            cmd: "npm run ios:release",
+            label: "iOS release build",
+            detail: "catalyst buildApp:ios --release. No Xcode UI: xcodebuild archive (Release, generic/platform=iOS), then -exportArchive with ios.exportMethod (default app-store-connect). Writes build-output/ios/<version>-<build>/<name>.ipa and <name>-dSYMs.zip. ITSAppUsesNonExemptEncryption=false.",
         },
         {
             step: 4,
             cmd: null,
-            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: "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.",
+            label: "Upload and release",
+            detail: "Upload the IPA with Transporter or `xcrun altool --upload-app` (Catalyst does not upload), test through TestFlight, complete App Store Connect metadata and privacy details, and submit for App Review.",
         },
     ],
 }
@@ -296,16 +272,17 @@ const MASTER_DIAGRAMS = {
             "→ [web path] hook falls back to browser API (navigator.vibrate, <input type=file>, etc.)",
         ],
         configurable_today: [
-            "port — WebView loads this port from the local server",
-            "useHttps — switches WebView URL to https (requires cert setup)",
-            "LOCAL_IP — override auto-detected IP for device builds",
+            "appId: Android application id and iOS bundle id (release refuses com.example.*)",
+            "appName: name under the app icon on both platforms",
+            "url: production origin release builds load (--url overrides); debug builds use the dev server",
+            "allowPrivateHost: lets a release load a private host (internal apps)",
             "accessControl.allowedUrls — whitelist for outbound requests from WebView",
             "googleSignIn.enabled / clientId / iosClientId",
             "splashScreen — duration, minDuration, backgroundColor, image size; optional animated public/splashscreen.html (1.0.2+)",
             "notifications.enabled — push notification permission prompt",
             "android.buildOptimisation — enables build caching",
-            "android.keystoreConfig — signing for release builds",
-            "ios.appBundleId — bundle identifier for App Store",
+            "version: package.json version; build number from the clock or CATALYST_BUILD_NUMBER",
+            "signing: credentials/android/ and credentials/ios/ (CI: CATALYST_ANDROID_CREDENTIALS / CATALYST_IOS_CREDENTIALS)",
         ],
     },
 
@@ -383,7 +360,7 @@ const MASTER_DIAGRAMS = {
             "",
             "[App build] In app project root:",
             "→ catalyst build (Vite client + SSR output)",
-            "→ npm run buildApp:android / buildApp:ios",
+            "→ npm run android / npm run ios (catalyst 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)",
@@ -490,7 +467,7 @@ const LEGACY_BUILD_PIPELINE = {
     flow: [
         "catalyst build (webpack)",
         "→ catalyst serve for production-style validation",
-        "→ npm run buildApp:android or npm run buildApp:ios",
+        "→ npm run android or npm run ios",
     ],
 }
 
@@ -510,7 +487,6 @@ function getProjectContext(root) {
         hasIos: !!wv.ios,
         androidBuildType: (wv.android?.buildType || "debug").toLowerCase(),
         iosBuildType: (wv.ios?.buildType || "debug").toLowerCase(),
-        hasKeystore: !!wv.android?.keystoreConfig,
         hasGoogleSignIn: !!wv.googleSignIn?.enabled,
         hasNotifications: !!wv.notifications?.enabled,
         hasEcosystem: fileExists("ecosystem.config.js"),
@@ -520,6 +496,27 @@ function getProjectContext(root) {
     }
 }
 
+/** Warnings shared by both platforms for appId, url and LOCAL_IP (catalyst-core 1.3.0+). */
+function appIdentityWarnings(ctx, isRelease, warnings) {
+    const wv = ctx.wv
+    const appId = wv.appId || wv.android?.packageName || wv.ios?.appBundleId || wv.ios?.bundleIdentifier
+    if (isRelease && (!appId || /^com\.example\./i.test(appId))) {
+        warnings.push(
+            "WEBVIEW_CONFIG.appId is missing or a com.example placeholder: the release fails with NATIVE-003. Set your own reverse-DNS id."
+        )
+    }
+    if (isRelease && !wv.url && !wv.LOCAL_IP) {
+        warnings.push(
+            "WEBVIEW_CONFIG.url not set: set the production origin (e.g. https://shop.acme.com) or pass --url."
+        )
+    }
+    if (wv.LOCAL_IP && /^\d{1,3}(\.\d{1,3}){3}$/.test(wv.LOCAL_IP) && wv.LOCAL_IP !== "127.0.0.1") {
+        warnings.push(
+            `WEBVIEW_CONFIG.LOCAL_IP is ${wv.LOCAL_IP}. Keep it "localhost"; debug builds work out the dev server address, and the first 1.3.0 build resets saved LAN addresses.`
+        )
+    }
+}
+
 function getKnownErrors(keywords) {
     if (!keywords || !keywords.length) return []
     // Score known_errors rows by keyword overlap
@@ -604,25 +601,13 @@ function handle_get_build_flow({ platform, mode, symptom } = {}) {
 
         const isRelease = m === "release" || ctx.androidBuildType === "release"
         flow_key = isRelease ? "android_release" : "android_debug"
-
-        if (isRelease) {
-            if (!ctx.hasKeystore) {
-                warnings.push(
-                    "WEBVIEW_CONFIG.android.keystoreConfig missing — release build will fail at AAB signing step. Add keystoreConfig with keyAlias, storePassword, keyPassword, organizationInfo."
-                )
-            }
-        } else {
-            if (!ctx.wv.android?.sdkPath) {
-                warnings.push(
-                    "WEBVIEW_CONFIG.android.sdkPath not set — ADB and emulator validation will fail."
-                )
-            }
-            if (!ctx.wv.android?.emulatorName) {
-                warnings.push("WEBVIEW_CONFIG.android.emulatorName not set — emulator launch step will fail.")
-            }
+        appIdentityWarnings(ctx, isRelease, warnings)
+        if (ctx.androidBuildType === "release") {
+            warnings.push(
+                'android.buildType "release" is deprecated: use `npm run android:release` and set buildType to "debug" or remove it.'
+            )
         }
 
-        notes.push(`buildType detected: ${ctx.androidBuildType}`)
         if (ctx.wv.android?.sdkPath) notes.push(`sdkPath: ${ctx.wv.android.sdkPath}`)
         if (ctx.wv.android?.emulatorName) notes.push(`emulatorName: ${ctx.wv.android.emulatorName}`)
         if (ctx.wv.android?.buildOptimisation) notes.push("buildOptimisation: enabled")
@@ -636,41 +621,32 @@ function handle_get_build_flow({ platform, mode, symptom } = {}) {
             )
         }
 
-        const isRelease = m === "release"
+        const isRelease = m === "release" || ctx.iosBuildType === "release"
         flow_key = isRelease ? "ios_release" : "ios_debug"
-
-        if (!ctx.wv.ios?.appBundleId) {
+        appIdentityWarnings(ctx, isRelease, warnings)
+        if (ctx.iosBuildType === "release") {
             warnings.push(
-                'WEBVIEW_CONFIG.ios.appBundleId not set — Xcode build will use fallback "com.debug.webview".'
+                'ios.buildType "release" is deprecated: use `npm run ios:release` and set buildType to "debug" or remove it.'
             )
         }
-        if (!ctx.wv.ios?.simulatorName && !isRelease) {
-            warnings.push("WEBVIEW_CONFIG.ios.simulatorName not set — simulator launch step will fail.")
-        }
-        if (ctx.hasGoogleSignIn && !ctx.wv.ios?.simulatorName) {
+        if (isRelease && !ctx.wv.ios?.developmentTeam && !ctx.wv.ios?.provisioningProfile) {
             warnings.push(
-                "googleSignIn.enabled=true but iosClientId may be missing — check WEBVIEW_CONFIG.googleSignIn.iosClientId."
+                "ios.developmentTeam not set. A release fails with IOS-010 unless credentials/ios/ holds a .p12 and its provisioning profile."
             )
         }
-        if (isRelease && !ctx.useHttps) {
+        if (ctx.hasGoogleSignIn && !ctx.wv.googleSignIn?.iosClientId) {
             warnings.push(
-                "WEBVIEW_CONFIG.useHttps is not enabled — the App Store flow requires a reachable HTTPS production web application."
+                "googleSignIn.enabled=true but iosClientId may be missing. Check WEBVIEW_CONFIG.googleSignIn.iosClientId."
             )
         }
         if (isRelease && ctx.hasNotifications) {
             warnings.push(
-                "Push notifications are enabled — review the generated aps-environment entitlement and Release provisioning before archiving."
+                "Push notifications are enabled: review the generated aps-environment entitlement and the release provisioning profile."
             )
         }
 
-        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.wv.ios?.developmentTeam) notes.push(`developmentTeam: ${ctx.wv.ios.developmentTeam}`)
         if (ctx.hasGoogleSignIn) notes.push("googleSignIn: enabled")
     } else {
         return { error: `Unknown platform "${platform}". Use: web | android | ios` }