@salesforce/ui-bundle-template-app-react-template-b2e 10.23.0 → 10.24.0

package/dist/CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [10.24.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v10.23.0...v10.24.0) (2026-06-25)
+
+
+### Features
+
+* **org-setup:** error handling, result ledger, and config validation @W-23043729 ([#665](https://github.com/salesforce-experience-platform-emu/webapps/issues/665)) ([f68ff9c](https://github.com/salesforce-experience-platform-emu/webapps/commit/f68ff9cf68df52efba1a9bea25f22f30246cb083))
+
+
+
 ## [10.23.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v10.22.0...v10.23.0) (2026-06-25)
 
 **Note:** Version bump only for package @salesforce/ui-bundle-template-base-sfdx-project

package/dist/force-app/main/default/uiBundles/reactinternalapp/package.json

@@ -18,8 +18,8 @@
     "graphql:schema": "node scripts/get-graphql-schema.mjs"
   },
   "dependencies": {
-    "@salesforce/platform-sdk": "^10.23.0",
-    "@salesforce/ui-bundle": "^10.23.0",
+    "@salesforce/platform-sdk": "^10.24.0",
+    "@salesforce/ui-bundle": "^10.24.0",
     "@tailwindcss/vite": "^4.1.17",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -45,8 +45,8 @@
     "@graphql-eslint/eslint-plugin": "^4.1.0",
     "@graphql-tools/utils": "^11.0.0",
     "@playwright/test": "^1.49.0",
-    "@salesforce/graphiti": "^10.23.0",
-    "@salesforce/vite-plugin-ui-bundle": "^10.23.0",
+    "@salesforce/graphiti": "^10.24.0",
+    "@salesforce/vite-plugin-ui-bundle": "^10.24.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",

package/dist/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-  "version": "10.23.0",
+  "version": "10.24.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-      "version": "10.23.0",
+      "version": "10.24.0",
       "license": "SEE LICENSE IN LICENSE.txt",
       "devDependencies": {
         "@lwc/eslint-plugin-lwc": "^3.3.0",

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/ui-bundle-template-base-sfdx-project",
-  "version": "10.23.0",
+  "version": "10.24.0",
   "description": "Base SFDX project template",
   "license": "SEE LICENSE IN LICENSE.txt",
   "publishConfig": {
@@ -11,6 +11,7 @@
     "build": "echo 'No build required for base-sfdx-project'",
     "clean": "echo 'No clean required for base-sfdx-project'",
     "lint": "eslint --no-error-on-unmatched-pattern **/{aura,lwc}/**/*.js",
+    "validate:org-setup-config": "node scripts/validate-org-setup-config.mjs",
     "test": "npm run test:unit",
     "test:coverage": "npm run test",
     "test:unit": "sfdx-lwc-jest -- --passWithNoTests",
@@ -22,6 +23,9 @@
     "precommit": "lint-staged",
     "setup": "node scripts/org-setup.mjs"
   },
+  "dependencies": {
+    "zod": "^3.24.1"
+  },
   "devDependencies": {
     "@lwc/eslint-plugin-lwc": "^3.3.0",
     "@prettier/plugin-xml": "^3.2.2",

package/dist/scripts/org-setup-config-schema.mjs

@@ -0,0 +1,96 @@
+/**
+ * Shared schema + validator for org-setup.config.json (W-23043729).
+ *
+ * Authored ONCE, used at TWO moments:
+ *   (a) build / CI time — `scripts/validate-org-setup-config.mjs` validates every
+ *       org-setup.config.json this repo ships, failing the build on any violation.
+ *   (b) setup runtime — `org-setup.mjs` calls `validateConfig` once in main(),
+ *       before any step runs, to catch the developer's local post-scaffold edits.
+ *
+ * `validateConfig` is pure: it parses + validates and RETURNS a result. Each call
+ * site owns its own print/exit, so the build gate can report every bad file and
+ * the runtime can exit immediately — and the validator stays unit-testable.
+ *
+ * The zod schema uses `.strict()` at every level so unknown keys (e.g. the
+ * `permsetAssignment` singular typo) are rejected rather than silently ignored.
+ */
+
+import { z } from 'zod';
+
+/** Closed set of assignee values — no arbitrary usernames. */
+const Assignee = z.enum(['currentUser', 'guestUser', 'skip']);
+
+// No siteName: for guestUser the site is derived from the single
+// networks/<siteName>.network-meta.xml the app ships (see spec §5.2).
+const Assignment = z
+  .object({
+    assignee: Assignee,
+  })
+  .strict();
+
+export const ConfigSchema = z
+  .object({
+    permsetAssignments: z
+      .object({
+        // guestUser is valid here — siteName is derived, not per-assignment.
+        defaultAssignee: Assignee.default('skip'),
+        assignments: z.record(z.string(), Assignment).default({}),
+      })
+      .strict()
+      .optional(),
+    role: z
+      .object({
+        assignee: z.literal('currentUser'), // only value the role code honors
+        roleName: z.string().min(1),
+      })
+      .strict()
+      .optional(),
+    selfRegistration: z
+      .object({
+        // No siteName: the site is derived from the single
+        // networks/<siteName>.network-meta.xml the app ships (see spec §5.2),
+        // exactly like the guestUser permset path.
+        selfRegProfile: z.string().min(1),
+        accountName: z.string().min(1),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+/**
+ * Render a single zod issue as a "path: message" line. Empty path (a root-level
+ * problem) renders as "<root>: message".
+ */
+function formatIssue(issue) {
+  const path = issue.path.length > 0 ? issue.path.join('.') : '<root>';
+  return `${path}: ${issue.message}`;
+}
+
+/**
+ * Parse + validate a raw org-setup.config.json string.
+ *
+ * @param {string} rawText  raw file contents (not yet JSON-parsed)
+ * @param {string} [configPath]  path used only for error messages
+ * @returns {{ ok: true, data: object } | { ok: false, errors: string[] }}
+ *   On success, `data` is the parsed + defaulted config. On failure, `errors`
+ *   is a non-empty list of human-readable messages (JSON parse error or zod
+ *   issues). The caller decides whether to print/exit.
+ */
+export function validateConfig(rawText, configPath) {
+  const where = configPath ? ` (${configPath})` : '';
+
+  let parsed;
+  try {
+    parsed = JSON.parse(rawText);
+  } catch (err) {
+    return { ok: false, errors: [`malformed JSON${where}: ${err.message}`] };
+  }
+
+  const result = ConfigSchema.safeParse(parsed);
+  if (!result.success) {
+    return { ok: false, errors: result.error.issues.map(formatIssue) };
+  }
+
+  return { ok: true, data: result.data };
+}

package/dist/scripts/org-setup.mjs

@@ -22,15 +22,18 @@
  * Permset assignment config (scripts/org-setup.config.json):
  *   {
  *     "permsetAssignments": {
+ *       "defaultAssignee": "skip",
  *       "assignments": {
  *         "My_Permset": { "assignee": "currentUser" },
- *         "Guest_Permset": { "assignee": "guestUser", "siteName": "mysite" },
+ *         "Guest_Permset": { "assignee": "guestUser" },
  *         "Internal_Only": { "assignee": "skip" }
  *       }
  *     }
  *   }
- *   Assignee values: "currentUser", "skip", "guestUser" (requires siteName), or a specific username.
- *   Only permsets explicitly listed in assignments are assigned; unlisted permsets are skipped.
+ *   Assignee values: "currentUser", "guestUser", or "skip". For "guestUser" the
+ *   site is derived from the single networks/<siteName>.network-meta.xml the app
+ *   ships — it is not restated per assignment.
+ *   Unlisted permsets resolve to "defaultAssignee" (default "skip").
  */
 
 import { spawnSync, spawn as nodeSpawn } from 'node:child_process';
@@ -38,9 +41,18 @@ import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { readdirSync, existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
 
+import { validateConfig } from './org-setup-config-schema.mjs';
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(__dirname, '..');
 
+/**
+ * Thrown by step runners (run/runAsync) when a subprocess fails. The per-step
+ * orchestration in main() catches it, records the failure in the result ledger,
+ * and either aborts (fail-fast steps) or continues (skippable steps).
+ */
+class StepError extends Error {}
+
 /**
  * npm strips .gitignore from published packages — generate them on first run.
  * Templates are stored in scripts/gitignore-templates.json (generated at build
@@ -149,15 +161,17 @@ Permset config (scripts/org-setup.config.json):
   Control per-permset assignment via a config file. Example:
     {
       "permsetAssignments": {
+        "defaultAssignee": "skip",
         "assignments": {
           "My_Permset": { "assignee": "currentUser" },
-          "Guest_Permset": { "assignee": "guestUser", "siteName": "mysite" },
+          "Guest_Permset": { "assignee": "guestUser" },
           "Internal_Only": { "assignee": "skip" }
         }
       }
     }
-  Assignee values: "currentUser", "skip", "guestUser" (requires siteName), or a specific username.
-  Only permsets explicitly listed in assignments are assigned; unlisted permsets are skipped.
+  Assignee values: "currentUser", "guestUser", or "skip". For "guestUser" the site
+  is derived from the single networks/<siteName>.network-meta.xml the app ships.
+  Unlisted permsets resolve to "defaultAssignee" (default "skip").
 `);
       process.exit(0);
     }
@@ -212,15 +226,64 @@ function discoverPermissionSetNames() {
   return names.sort();
 }
 
+const CONFIG_PATH = resolve(__dirname, 'org-setup.config.json');
+
+/**
+ * Read + validate org-setup.config.json ONCE, against the shared zod schema
+ * (the same `validateConfig` the build/CI gate uses). Exits non-zero with the
+ * precise zod issues if the config is invalid — before any step runs.
+ *
+ * Returns the validated config object (zod defaults applied), or an empty
+ * object when the file is absent (every section is optional).
+ *
+ * This is the single source of truth: loadPermsetConfig / loadRoleConfig /
+ * loadSelfRegConfig all read from the object it returns, so they no longer
+ * parse or defensively swallow errors.
+ */
+function loadValidatedConfig() {
+  if (!existsSync(CONFIG_PATH)) return {};
+  const result = validateConfig(readFileSync(CONFIG_PATH, 'utf8'), CONFIG_PATH);
+  if (!result.ok) {
+    console.error('Invalid org-setup.config.json:');
+    for (const err of result.errors) console.error(`  - ${err}`);
+    process.exit(1);
+  }
+  return result.data;
+}
+
+/**
+ * Derive the site name from the single networks/<siteName>.network-meta.xml the
+ * app ships. An app ships exactly one site, so the site name is derivable from
+ * deployed metadata rather than restated per-assignment (spec §5.2). Returns
+ * null when there is no networks dir or no .network-meta.xml file.
+ */
+function deriveSiteName() {
+  const networksDir = resolve(SFDX_SOURCE, 'networks');
+  if (!existsSync(networksDir)) return null;
+  const files = readdirSync(networksDir)
+    .filter((f) => f.endsWith('.network-meta.xml'))
+    .sort();
+  if (files.length === 0) return null;
+  // An app ships exactly one site; if a developer added a second, derivation is
+  // ambiguous — fail loudly rather than silently bind to an arbitrary site.
+  if (files.length > 1) {
+    throw new StepError(
+      `cannot derive guest site: multiple network metadata files found in ${networksDir} (${files.join(', ')}); guestUser assignment requires exactly one`,
+    );
+  }
+  return files[0].replace(/\.network-meta\.xml$/, '');
+}
+
 /**
- * Load permset assignment configuration from org-setup.config.json.
+ * Permset assignment configuration, read from the already-validated config.
  *
  * Config shape:
  *   {
  *     "permsetAssignments": {
+ *       "defaultAssignee": "skip",
  *       "assignments": {
  *         "My_Permset":       { "assignee": "currentUser" },
- *         "My_Guest_Permset": { "assignee": "guestUser", "siteName": "mysite" },
+ *         "My_Guest_Permset": { "assignee": "guestUser" },
  *         "Internal_Only":    { "assignee": "skip" }
  *       }
  *     }
@@ -229,68 +292,57 @@ function discoverPermissionSetNames() {
  * Assignee values:
  *   "currentUser" — assign to the user running the script
  *   "skip"        — do not assign this permset
- *   "guestUser"   — resolve the site guest user automatically (requires siteName)
- *   "<username>"  — assign to a specific user via --on-behalf-of
+ *   "guestUser"   — resolve the site guest user automatically (site derived from
+ *                   the single networks/<siteName>.network-meta.xml the app ships)
  *
- * Only permsets explicitly listed in assignments are assigned; unlisted permsets are skipped.
+ * Unlisted permsets resolve to `defaultAssignee` (default "skip").
  *
- * Returns { assignments: Record<string, { assignee: string, siteName?: string }> }
+ * Returns { defaultAssignee: string, assignments: Record<string, { assignee: string }> }
  */
-function loadPermsetConfig() {
-  const configPath = resolve(__dirname, 'org-setup.config.json');
-  const defaults = { assignments: {} };
-  if (!existsSync(configPath)) return defaults;
-  try {
-    const raw = JSON.parse(readFileSync(configPath, 'utf8'));
-    const section = raw?.permsetAssignments;
-    if (!section) return defaults;
-    return {
-      assignments: section.assignments || {},
-    };
-  } catch (err) {
-    console.warn(`Warning: failed to parse org-setup.config.json: ${err.message}; using defaults.`);
-    return defaults;
-  }
+function loadPermsetConfig(config) {
+  const section = config.permsetAssignments;
+  if (!section) return { defaultAssignee: 'skip', assignments: {} };
+  return {
+    defaultAssignee: section.defaultAssignee,
+    assignments: section.assignments,
+  };
 }
 
 /** Resolve the effective assignment config for a given permset name. */
 function resolveAssignment(permsetName, permsetConfig) {
   const override = permsetConfig.assignments[permsetName];
-  if (!override) return { assignee: 'skip' };
-  return { assignee: override.assignee || 'skip', siteName: override.siteName };
+  if (!override) return { assignee: permsetConfig.defaultAssignee };
+  return { assignee: override.assignee };
 }
 
 /**
- * Load role assignment config from org-setup.config.json.
+ * Role assignment config, read from the already-validated config.
  *
  * Config shape:
  *   { "role": { "assignee": "currentUser", "roleName": "Admin" } }
  *
  * Returns null if no "role" section exists in config (the step is hidden).
  */
-function loadRoleConfig() {
-  const configPath = resolve(__dirname, 'org-setup.config.json');
-  if (!existsSync(configPath)) return null;
-  try {
-    const raw = JSON.parse(readFileSync(configPath, 'utf8'));
-    const section = raw?.role;
-    if (!section) return null;
-    return {
-      assignee: section.assignee || 'currentUser',
-      roleName: section.roleName || null,
-    };
-  } catch {
-    return null;
-  }
+function loadRoleConfig(config) {
+  const section = config.role;
+  if (!section) return null;
+  return {
+    assignee: section.assignee,
+    roleName: section.roleName,
+  };
 }
 
 /**
- * Load self-registration config from org-setup.config.json.
+ * Self-registration config, read from the already-validated config. The site is
+ * NOT stored here — it is derived from the single
+ * networks/<siteName>.network-meta.xml the app ships (spec §5.2), exactly like
+ * the guestUser permset path. deriveSiteName() is called lazily inside the
+ * selfReg step body so its "multiple network files" StepError is recorded in
+ * the ledger rather than escaping config load.
  *
  * Config shape:
  *   {
  *     "selfRegistration": {
- *       "siteName": "myapp",
  *       "selfRegProfile": "myapp Profile",
  *       "accountName": "My Self-Reg Account"
  *     }
@@ -298,21 +350,13 @@ function loadRoleConfig() {
  *
  * Returns null if no "selfRegistration" section exists in config (the step is hidden).
  */
-function loadSelfRegConfig() {
-  const configPath = resolve(__dirname, 'org-setup.config.json');
-  if (!existsSync(configPath)) return null;
-  try {
-    const raw = JSON.parse(readFileSync(configPath, 'utf8'));
-    const section = raw?.selfRegistration;
-    if (!section) return null;
-    return {
-      siteName: section.siteName || null,
-      selfRegProfile: section.selfRegProfile || null,
-      accountName: section.accountName || null,
-    };
-  } catch {
-    return null;
-  }
+function loadSelfRegConfig(config) {
+  const section = config.selfRegistration;
+  if (!section) return null;
+  return {
+    selfRegProfile: section.selfRegProfile,
+    accountName: section.accountName,
+  };
 }
 
 /**
@@ -320,8 +364,8 @@ function loadSelfRegConfig() {
  * This must happen BEFORE the initial deploy so that the profile is a recognised
  * site member when subsequent steps (selfRegProfile, selfRegistration=true) are deployed.
  */
-function ensureNetworkMemberProfile(selfRegConfig) {
-  const { siteName, selfRegProfile } = selfRegConfig;
+function ensureNetworkMemberProfile(selfRegConfig, siteName) {
+  const { selfRegProfile } = selfRegConfig;
   if (!siteName || !selfRegProfile) return;
 
   const networkXmlPath = resolve(SFDX_SOURCE, 'networks', `${siteName}.network-meta.xml`);
@@ -356,14 +400,13 @@ function ensureNetworkMemberProfile(selfRegConfig) {
  * 3. Create an Account record (idempotent).
  * 4. Create a NetworkSelfRegistration record linking the Account to the Network (idempotent).
  */
-function enableSelfRegistration(selfRegConfig, targetOrg) {
-  const { siteName, selfRegProfile, accountName } = selfRegConfig;
+function enableSelfRegistration(selfRegConfig, siteName, targetOrg) {
+  const { selfRegProfile, accountName } = selfRegConfig;
 
   // 1. Modify network metadata XML
   const networkXmlPath = resolve(SFDX_SOURCE, 'networks', `${siteName}.network-meta.xml`);
   if (!existsSync(networkXmlPath)) {
-    console.error(`  Network metadata not found: ${networkXmlPath}`);
-    return;
+    throw new StepError(`network metadata not found: ${networkXmlPath}`);
   }
   const xml = readFileSync(networkXmlPath, 'utf8');
 
@@ -393,8 +436,7 @@ function enableSelfRegistration(selfRegConfig, targetOrg) {
       '--source-dir', networkXmlPath,
     ], { cwd: ROOT, stdio: 'inherit', shell: true, timeout: 120000 });
     if (deployResult.status !== 0) {
-      console.error('  Failed to deploy updated network metadata.');
-      process.exit(deployResult.status ?? 1);
+      throw new StepError(`failed to deploy updated network metadata (exit ${deployResult.status ?? 1})`);
     }
   }
 
@@ -424,17 +466,15 @@ function enableSelfRegistration(selfRegConfig, targetOrg) {
       '--json',
     ], { cwd: ROOT, encoding: 'utf8' });
     if (createResult.status !== 0) {
-      console.error(`  Failed to create Account "${accountName}".`);
       if (createResult.stderr) console.error(createResult.stderr);
-      return;
+      throw new StepError(`failed to create Account "${accountName}"`);
     }
     try {
       const json = JSON.parse(createResult.stdout);
       accountId = json.result?.id;
       console.log(`  Created Account "${accountName}" (${accountId}).`);
     } catch {
-      console.error('  Failed to parse Account creation result.');
-      return;
+      throw new StepError('failed to parse Account creation result');
     }
   }
 
@@ -454,8 +494,7 @@ function enableSelfRegistration(selfRegConfig, targetOrg) {
     } catch { /* fall through */ }
   }
   if (!networkId) {
-    console.error(`  Could not find Network "${siteName}" in org.`);
-    return;
+    throw new StepError(`could not find Network "${siteName}" in org`);
   }
   console.log(`  Found Network "${siteName}" (${networkId}).`);
 
@@ -493,9 +532,8 @@ function enableSelfRegistration(selfRegConfig, targetOrg) {
     const apexOut = apexResult.stdout?.toString() || '';
     if (existsSync(tmpApex)) unlinkSync(tmpApex);
     if (apexResult.status !== 0 && !apexOut.includes('Compiled successfully')) {
-      console.error('  Failed to create NetworkSelfRegistration record.');
       process.stderr.write(apexResult.stderr?.toString() || apexOut);
-      return;
+      throw new StepError('failed to create NetworkSelfRegistration record');
     }
     const nsrMatch = apexOut.match(/NSR_CREATED:(\w+)/);
     if (nsrMatch) {
@@ -519,22 +557,20 @@ function assignRoleToCurrentUser(roleName, targetOrg) {
     '--json',
   ], { cwd: ROOT, encoding: 'utf8' });
   if (roleResult.status !== 0) {
-    console.error(`  Failed to query role "${roleName}" in org.`);
     if (roleResult.stderr) console.error(roleResult.stderr);
-    return;
+    throw new StepError(`failed to query role "${roleName}" in org`);
   }
   let roleId;
   try {
     const json = JSON.parse(roleResult.stdout);
     const records = json.result?.records;
     if (!records || records.length === 0) {
-      console.error(`  Role "${roleName}" not found in org; skipping.`);
-      return;
+      throw new StepError(`role "${roleName}" not found in org`);
     }
     roleId = records[0].Id;
-  } catch {
-    console.error(`  Failed to parse role query result for "${roleName}".`);
-    return;
+  } catch (err) {
+    if (err instanceof StepError) throw err;
+    throw new StepError(`failed to parse role query result for "${roleName}"`);
   }
 
   const orgResult = spawnSync('sf', [
@@ -543,20 +579,18 @@ function assignRoleToCurrentUser(roleName, targetOrg) {
     '--json',
   ], { cwd: ROOT, encoding: 'utf8' });
   if (orgResult.status !== 0) {
-    console.error('  Failed to resolve current user from org.');
-    return;
+    throw new StepError('failed to resolve current user from org');
   }
   let username;
   try {
     const json = JSON.parse(orgResult.stdout);
     username = json.result?.username;
     if (!username) {
-      console.error('  Could not determine current username from org display.');
-      return;
+      throw new StepError('could not determine current username from org display');
     }
-  } catch {
-    console.error('  Failed to parse org display result.');
-    return;
+  } catch (err) {
+    if (err instanceof StepError) throw err;
+    throw new StepError('failed to parse org display result');
   }
 
   const userQuery = `SELECT Id, UserRoleId FROM User WHERE Username = '${username}'`;
@@ -589,8 +623,8 @@ function assignRoleToCurrentUser(roleName, targetOrg) {
     console.log(`  Role "${roleName}" assigned to ${username}.`);
   } else {
     const out = (updateResult.stderr?.toString() || '') + (updateResult.stdout?.toString() || '');
-    console.error(`  Failed to assign role "${roleName}" to ${username}.`);
     if (out) console.error(out);
+    throw new StepError(`failed to assign role "${roleName}" to ${username}`);
   }
 }
 
@@ -677,9 +711,13 @@ function buildApexInsert(sobject, records, refIds) {
 async function promptSteps(steps) {
   if (!process.stdin.isTTY) return steps.map((s) => s.enabled);
 
+  // `selected` stays indexed by ORIGINAL step order (so the caller's
+  // selections[i] → stepDefs[i] mapping is unchanged); unavailable steps remain
+  // false. Only available steps are shown and navigable — unavailable steps are
+  // hidden entirely rather than rendered greyed-out.
   const selected = steps.map((s) => s.enabled);
+  const visible = steps.map((s, i) => ({ step: s, index: i })).filter(({ step }) => step.available);
   let cursor = 0;
-  const DIM = '\x1B[2m';
   const RST = '\x1B[0m';
   const CYAN = '\x1B[36m';
   const GREEN = '\x1B[32m';
@@ -701,11 +739,10 @@ async function promptSteps(steps) {
   }
 
   function render() {
-    return steps.map((s, i) => {
-      const ptr = i === cursor ? `${CYAN}❯${RST}` : ' ';
-      if (!s.available) return `${ptr} ${DIM}○ ${s.label} (n/a)${RST}`;
-      const chk = selected[i] ? `${GREEN}●${RST}` : '○';
-      return `${ptr} ${chk} ${s.label}`;
+    return visible.map(({ step, index }, row) => {
+      const ptr = row === cursor ? `${CYAN}❯${RST}` : ' ';
+      const chk = selected[index] ? `${GREEN}●${RST}` : '○';
+      return `${ptr} ${chk} ${step.label}`;
     });
   }
 
@@ -742,16 +779,17 @@ async function promptSteps(steps) {
         resolve(selected);
         return;
       }
+      // Note: `cursor` indexes `visible`; `selected` is indexed by ORIGINAL step
+      // order. Map through visible[cursor].index before touching `selected`.
       if (key === ' ') {
-        if (steps[cursor].available) selected[cursor] = !selected[cursor];
+        const { index } = visible[cursor];
+        selected[index] = !selected[index];
         redraw();
         return;
       }
       if (key === 'a') {
-        const allOn = steps.every((s, i) => !s.available || selected[i]);
-        for (let i = 0; i < steps.length; i++) {
-          if (steps[i].available) selected[i] = !allOn;
-        }
+        const allOn = visible.every(({ index }) => selected[index]);
+        for (const { index } of visible) selected[index] = !allOn;
         redraw();
         return;
       }
@@ -759,7 +797,7 @@ async function promptSteps(steps) {
         cursor = Math.max(0, cursor - 1);
         redraw();
       } else if (key === '\x1B[B' || key === 'j') {
-        cursor = Math.min(steps.length - 1, cursor + 1);
+        cursor = Math.min(visible.length - 1, cursor + 1);
         redraw();
       }
     });
@@ -777,8 +815,7 @@ function run(name, cmd, args, opts = {}) {
     ...(opts.timeout && { timeout: opts.timeout }),
   });
   if (result.status !== 0 && !optional) {
-    console.error(`\nSetup failed at step: ${name}`);
-    process.exit(result.status ?? 1);
+    throw new StepError(`${name} (exit ${result.status ?? 1})`);
   }
   return result;
 }
@@ -808,12 +845,91 @@ async function runAsync(name, cmd, args, opts = {}) {
   if (result.status !== 0 && !optional) {
     if (result.stdout) process.stdout.write(result.stdout);
     if (result.stderr) process.stderr.write(result.stderr);
-    console.error(`\nSetup failed at step: ${name}`);
-    process.exit(result.status ?? 1);
+    throw new StepError(`${name} (exit ${result.status ?? 1})`);
   }
   return result;
 }
 
+/**
+ * In-memory result ledger. Each selected step records exactly one outcome:
+ *   ok      — the step ran and succeeded
+ *   skipped — the step was not selected, or had no config section (intentional)
+ *   failed  — the step ran and failed (with a human-readable reason)
+ * The end-of-run summary is rendered from this ledger and the process exits
+ * non-zero whenever any step is `failed` (fail-fast or skippable alike).
+ *
+ * @typedef {{ key: string, label: string, status: 'ok'|'skipped'|'failed', reason?: string, failFast?: boolean }} StepResult
+ */
+const results = [];
+function recordOk(step) {
+  results.push({ key: step.key, label: step.label, status: 'ok', failFast: step.failFast });
+}
+function recordSkipped(step, reason) {
+  results.push({ key: step.key, label: step.label, status: 'skipped', reason, failFast: step.failFast });
+}
+function recordFailed(step, reason) {
+  results.push({ key: step.key, label: step.label, status: 'failed', reason, failFast: step.failFast });
+}
+
+/** True if any step in the ledger failed. */
+function finalExitCode() {
+  return results.some((r) => r.status === 'failed') ? 1 : 0;
+}
+
+const SUMMARY_GLYPH = { ok: '✔', skipped: '–', failed: '✖' };
+
+/**
+ * Render the end-of-run summary. Always called — on success, on a fail-fast
+ * abort (partial: only steps reached so far are present), and on a clean finish
+ * that had skippable failures. Failed rows are listed last so the real problem
+ * is the last thing the developer sees.
+ */
+function printSummary(targetOrg) {
+  const ordered = [
+    ...results.filter((r) => r.status !== 'failed'),
+    ...results.filter((r) => r.status === 'failed'),
+  ];
+  const pad = Math.max(0, ...ordered.map((r) => r.key.length));
+  console.log(`\nSetup summary (target org: ${targetOrg})`);
+  for (const r of ordered) {
+    const glyph = SUMMARY_GLYPH[r.status] ?? ' ';
+    const key = r.key.padEnd(pad);
+    let line = `  ${glyph} ${key}  ${r.status}`;
+    if (r.reason) line += ` (${r.reason})`;
+    if (r.status === 'failed') line += r.failFast ? '   [fail-fast — aborted]' : '   [skippable — continued]';
+    console.log(line);
+  }
+  const failures = results.filter((r) => r.status === 'failed').length;
+  if (failures > 0) {
+    console.log(`Setup completed with ${failures} failure(s). Exiting 1.`);
+  } else {
+    console.log('Setup complete.');
+  }
+}
+
+/**
+ * Run one step body, recording its outcome in the ledger and honoring the
+ * step's fixed `failFast` classification. The body either completes (→ ok),
+ * throws a StepError (→ failed), or throws something unexpected (→ failed,
+ * with the raw message). On a fail-fast failure this prints the partial
+ * summary and exits non-zero immediately; on a skippable failure it records
+ * and returns so the run continues.
+ */
+async function runStep(step, targetOrg, body) {
+  try {
+    await body();
+    recordOk(step);
+  } catch (err) {
+    const reason = err instanceof StepError ? err.message : (err?.message ?? String(err));
+    recordFailed(step, reason);
+    console.error(`\nStep "${step.key}" failed: ${reason}`);
+    if (step.failFast) {
+      printSummary(targetOrg);
+      process.exit(1);
+    }
+  }
+}
+
 async function main() {
   // Ensure .gitignore files exist (npm strips them from published packages).
   const gitignoreTemplates = loadGitignoreTemplates();
@@ -853,22 +969,30 @@ async function main() {
         ? `Permset — assign ${permsetNames.join(', ')}`
         : `Permset — assign ${permsetNames.length} permission sets`;
 
+  // Validate org-setup.config.json ONCE, before any step runs (spec §5.2). The
+  // three load*Config helpers read from this already-validated object.
+  const config = loadValidatedConfig();
+
   const hasDataPlan = existsSync(DATA_PLAN) && existsSync(DATA_DIR);
-  const roleConfig = loadRoleConfig();
+  const roleConfig = loadRoleConfig(config);
   const hasRoleConfig = roleConfig !== null;
-  const selfRegConfig = loadSelfRegConfig();
+  const selfRegConfig = loadSelfRegConfig(config);
   const hasSelfRegConfig = selfRegConfig !== null;
 
+  // failFast is a fixed, implementer-owned classification (spec §5.2) — NOT
+  // user-configurable. A fail-fast failure aborts the run immediately; a
+  // skippable failure is recorded and the run continues. The exit code is
+  // non-zero on any failure regardless of class.
   const stepDefs = [
-    { key: 'login', label: 'Login — org authentication', enabled: !argSkipLogin, available: true },
-    { key: 'uiBundleBuild', label: 'UI Bundle Build — npm install + build (pre-deploy)', enabled: !argSkipUIBundleBuild, available: true },
-    { key: 'deploy', label: 'Deploy — sf project deploy start', enabled: !argSkipDeploy, available: true },
-    { key: 'permset', label: permsetStepLabel, enabled: !argSkipPermset, available: true },
-    { key: 'role', label: `Role — assign "${roleConfig?.roleName ?? '?'}" to current user`, enabled: !argSkipRole && hasRoleConfig, available: hasRoleConfig },
-    { key: 'selfReg', label: `Self-Registration — enable for "${selfRegConfig?.siteName ?? '?'}"`, enabled: !argSkipSelfReg && hasSelfRegConfig, available: hasSelfRegConfig },
-    { key: 'data', label: 'Data — delete + import records via Apex', enabled: !argSkipData && hasDataPlan, available: hasDataPlan },
-    { key: 'graphql', label: 'GraphQL — schema introspect + codegen', enabled: !argSkipGraphql, available: true },
-    { key: 'dev', label: 'Dev — launch dev server', enabled: !argSkipDev, available: true },
+    { key: 'login', label: 'Login — org authentication', enabled: !argSkipLogin, available: true, failFast: true },
+    { key: 'uiBundleBuild', label: 'UI Bundle Build — npm install + build (pre-deploy)', enabled: !argSkipUIBundleBuild, available: true, failFast: true },
+    { key: 'deploy', label: 'Deploy — sf project deploy start', enabled: !argSkipDeploy, available: true, failFast: true },
+    { key: 'permset', label: permsetStepLabel, enabled: !argSkipPermset, available: true, failFast: false },
+    { key: 'role', label: `Role — assign "${roleConfig?.roleName ?? '?'}" to current user`, enabled: !argSkipRole && hasRoleConfig, available: hasRoleConfig, failFast: false },
+    { key: 'selfReg', label: 'Self-Registration — enable for site', enabled: !argSkipSelfReg && hasSelfRegConfig, available: hasSelfRegConfig, failFast: false },
+    { key: 'data', label: 'Data — delete + import records via Apex', enabled: !argSkipData && hasDataPlan, available: hasDataPlan, failFast: true },
+    { key: 'graphql', label: 'GraphQL — schema introspect + codegen', enabled: !argSkipGraphql, available: true, failFast: true },
+    { key: 'dev', label: 'Dev — launch dev server', enabled: !argSkipDev, available: true, failFast: false },
   ];
 
   const selections = yes ? stepDefs.map((s) => s.enabled) : await promptSteps(stepDefs);
@@ -905,48 +1029,94 @@ async function main() {
     !skipDev
   );
 
+  const loginStep = stepDefs.find((s) => s.key === 'login');
   if (!skipLogin) {
-    if (isOrgConnected(targetOrg)) {
-      console.log('\n--- Login ---');
-      console.log(`Org ${targetOrg} is already authenticated; skipping browser login.`);
-    } else {
-      run('Login (browser)', 'sf', ['org', 'login', 'web', '--alias', targetOrg], { optional: true });
-    }
+    await runStep(loginStep, targetOrg, async () => {
+      if (isOrgConnected(targetOrg)) {
+        console.log('\n--- Login ---');
+        console.log(`Org ${targetOrg} is already authenticated; skipping browser login.`);
+      } else {
+        // Login is fail-fast (spec §5.2): drop the previous { optional: true } so a
+        // failed browser login records `failed`, prints the summary, and aborts.
+        run('Login (browser)', 'sf', ['org', 'login', 'web', '--alias', targetOrg]);
+      }
+    });
+  } else {
+    recordSkipped(loginStep, 'not selected');
   }
 
   // Ensure the self-reg profile is in networkMemberGroups before deploy so that
-  // subsequent selfRegProfile / selfRegistration updates don't fail.
+  // subsequent selfRegProfile / selfRegistration updates don't fail. This is
+  // best-effort prep: if the site can't be derived (no network file, or the
+  // ambiguous multi-network case where deriveSiteName throws), skip the prep
+  // silently here — the selfReg step records that derivation failure as a
+  // skippable StepError, so it stays in the ledger instead of aborting pre-deploy.
   if (!skipDeploy && selfRegConfig) {
-    console.log('\n--- Ensure network member profile (pre-deploy) ---');
-    ensureNetworkMemberProfile(selfRegConfig);
+    let preDeploySiteName = null;
+    try {
+      preDeploySiteName = deriveSiteName();
+    } catch {
+      // ambiguous derivation — surfaced by the selfReg step below
+    }
+    if (preDeploySiteName) {
+      console.log('\n--- Ensure network member profile (pre-deploy) ---');
+      ensureNetworkMemberProfile(selfRegConfig, preDeploySiteName);
+    }
   }
 
   // Build all UI Bundles before deploy so dist exists for entity deployment
-  if (!skipDeploy && !skipUIBundleBuild) {
-    const allUIBundleDirs = discoverAllUIBundleDirs(uiBundleName);
-    for (const dir of allUIBundleDirs) {
-      const name = dir.split(/[/\\]/).pop();
-      run(`UI Bundle install (${name})`, 'npm', ['install'], { cwd: dir });
-      run(`UI Bundle build (${name})`, 'npm', ['run', 'build'], { cwd: dir });
+  const uiBundleBuildStep = stepDefs.find((s) => s.key === 'uiBundleBuild');
+  let preDeployBundlesBuilt = false;
+  if (!skipUIBundleBuild) {
+    if (!skipDeploy) {
+      await runStep(uiBundleBuildStep, targetOrg, () => {
+        const allUIBundleDirs = discoverAllUIBundleDirs(uiBundleName);
+        for (const dir of allUIBundleDirs) {
+          const name = dir.split(/[/\\]/).pop();
+          run(`UI Bundle install (${name})`, 'npm', ['install'], { cwd: dir });
+          run(`UI Bundle build (${name})`, 'npm', ['run', 'build'], { cwd: dir });
+        }
+      });
+      preDeployBundlesBuilt = true;
     }
+    // When skipDeploy, the bundle build happens in the GraphQL section below;
+    // its outcome is recorded there.
+  } else {
+    recordSkipped(uiBundleBuildStep, 'not selected');
   }
 
+  const deployStep = stepDefs.find((s) => s.key === 'deploy');
   if (!skipDeploy) {
-    run('Deploy metadata', 'sf', ['project', 'deploy', 'start', '--target-org', targetOrg], {
-      timeout: 180000,
+    await runStep(deployStep, targetOrg, () => {
+      run('Deploy metadata', 'sf', ['project', 'deploy', 'start', '--target-org', targetOrg], {
+        timeout: 180000,
+      });
     });
+  } else {
+    recordSkipped(deployStep, 'not selected');
   }
 
+  const permsetStep = stepDefs.find((s) => s.key === 'permset');
   if (!skipPermset) {
-    const permsetConfig = loadPermsetConfig();
-    if (permsetNames.length === 0) {
-      console.log('\n--- Assign permission sets ---');
-      console.log('No permission sets found under permissionsets/ and none passed via --permset-name; skipping.');
-    } else {
+    await runStep(permsetStep, targetOrg, async () => {
+      const permsetConfig = loadPermsetConfig(config);
+      if (permsetNames.length === 0) {
+        console.log('\n--- Assign permission sets ---');
+        console.log('No permission sets found under permissionsets/ and none passed via --permset-name; skipping.');
+        return;
+      }
       console.log('\n--- Assign permission sets ---');
 
       // Resolve assignments (guest user lookups etc.) then run all sf assign calls in parallel.
+      //
+      // A guest-user resolution failure (no derivable site, or no guest user yet)
+      // is collected — NOT thrown mid-loop. Throwing here would unwind the whole
+      // runStep body before Promise.all and silently drop every assignment already
+      // queued (e.g. a currentUser permset that sorts ahead of a guestUser one and
+      // never depended on the site at all). Resolvable assignments still run; the
+      // combined failure is thrown at the end so the step is still recorded failed.
       const assignmentJobs = [];
+      const resolutionFailures = [];
       for (const permsetName of permsetNames) {
         const assignment = resolveAssignment(permsetName, permsetConfig);
         if (assignment.assignee === 'skip') {
@@ -955,18 +1125,21 @@ async function main() {
         }
         let effectiveUsername = null;
         if (assignment.assignee === 'guestUser') {
-          if (!assignment.siteName) {
-            console.error(`Permission set "${permsetName}" — assignee is "guestUser" but no "siteName" configured; skipping.`);
+          // Site name is derived from the single network metadata file the app
+          // ships (spec §5.2) — never restated per-assignment.
+          const siteName = deriveSiteName();
+          if (!siteName) {
+            console.error(`Permission set "${permsetName}" — assignee is "guestUser" but no networks/<siteName>.network-meta.xml was found to derive the site; skipping.`);
+            resolutionFailures.push(`${permsetName} (no network metadata to derive site)`);
             continue;
           }
-          effectiveUsername = resolveGuestUsername(assignment.siteName, targetOrg);
+          effectiveUsername = resolveGuestUsername(siteName, targetOrg);
           if (!effectiveUsername) {
-            console.error(`Permission set "${permsetName}" — could not resolve guest user for site "${assignment.siteName}"; skipping.`);
+            console.error(`Permission set "${permsetName}" — could not resolve guest user for site "${siteName}"; skipping.`);
+            resolutionFailures.push(`${permsetName} (could not resolve guest user for site "${siteName}")`);
             continue;
           }
-          console.log(`  Resolved guest user for site "${assignment.siteName}": ${effectiveUsername}`);
-        } else if (assignment.assignee !== 'currentUser') {
-          effectiveUsername = assignment.assignee;
+          console.log(`  Resolved guest user for site "${siteName}": ${effectiveUsername}`);
         }
         assignmentJobs.push({ permsetName, effectiveUsername });
       }
@@ -982,6 +1155,7 @@ async function main() {
         return { permsetName, assigneeLabel, result };
       }));
 
+      const failures = [];
       for (const { permsetName, assigneeLabel, result } of assignResults) {
         if (result.status === 0) {
           console.log(`Permission set "${permsetName}" assigned to ${assigneeLabel}.`);
@@ -994,35 +1168,55 @@ async function main() {
           } else {
             if (result.stdout) process.stdout.write(result.stdout);
             if (result.stderr) process.stderr.write(result.stderr);
-            console.error(`\nSetup failed at step: Assign permission set (${permsetName})`);
-            process.exit(result.status ?? 1);
+            failures.push(`${permsetName} (exit ${result.status ?? 1})`);
           }
         }
       }
-    }
+      const allFailures = [...resolutionFailures, ...failures];
+      if (allFailures.length > 0) {
+        throw new StepError(`failed to assign permission set(s): ${allFailures.join(', ')}`);
+      }
+    });
+  } else {
+    recordSkipped(permsetStep, 'not selected');
   }
 
+  const roleStep = stepDefs.find((s) => s.key === 'role');
   if (!skipRole) {
     console.log('\n--- Assign role ---');
-    if (roleConfig?.assignee !== 'currentUser') {
-      console.error(`Role assignee "${roleConfig?.assignee}" is not supported; only "currentUser" is allowed. Skipping.`);
-    } else if (!roleConfig?.roleName) {
-      console.error('Role step enabled but no "roleName" specified in org-setup.config.json; skipping.');
-    } else {
+    // Config shape (assignee === 'currentUser', non-empty roleName) is guaranteed
+    // by the schema, so there is nothing to re-check here — the step either ran
+    // (ok) or its assignment threw (failed). No manual recordSkipped inference.
+    await runStep(roleStep, targetOrg, () => {
       assignRoleToCurrentUser(roleConfig.roleName, targetOrg);
-    }
+    });
+  } else {
+    recordSkipped(roleStep, roleStep.available ? 'not selected' : 'no config');
   }
 
+  const selfRegStep = stepDefs.find((s) => s.key === 'selfReg');
   if (!skipSelfReg) {
     console.log('\n--- Enable self-registration ---');
-    if (!selfRegConfig?.siteName || !selfRegConfig?.selfRegProfile || !selfRegConfig?.accountName) {
-      console.error('Self-registration config is incomplete (need siteName, selfRegProfile, accountName); skipping.');
-    } else {
-      enableSelfRegistration(selfRegConfig, targetOrg);
-    }
+    // Config shape (selfRegProfile, accountName) is guaranteed by the schema.
+    // The site is derived inside the step body so a "multiple network files"
+    // StepError is recorded in the ledger rather than escaping. No manual
+    // recordSkipped inference.
+    await runStep(selfRegStep, targetOrg, () => {
+      const siteName = deriveSiteName();
+      if (!siteName) {
+        throw new StepError(
+          'self-registration is configured but no networks/<siteName>.network-meta.xml was found to derive the site',
+        );
+      }
+      enableSelfRegistration(selfRegConfig, siteName, targetOrg);
+    });
+  } else {
+    recordSkipped(selfRegStep, selfRegStep.available ? 'not selected' : 'no config');
   }
 
+  const dataStep = stepDefs.find((s) => s.key === 'data');
   if (doData) {
+   await runStep(dataStep, targetOrg, () => {
     // Prepare data for uniqueness (run before import so repeat imports don't conflict)
     const prepareScript = resolve(__dirname, 'prepare-import-unique-fields.js');
     run('Prepare data (unique fields)', 'node', [prepareScript, '--data-dir', DATA_DIR], {
@@ -1114,9 +1308,8 @@ async function main() {
           const apexOut = apexResult.stdout?.toString() || '';
           const apexErr = apexResult.stderr?.toString() || '';
           if (apexResult.status !== 0 && !apexOut.includes('Compiled successfully')) {
-            console.error(`  ${entry.sobject}: apex execution failed`);
             process.stderr.write(apexErr || apexOut);
-            process.exit(1);
+            throw new StepError(`${entry.sobject}: apex execution failed`);
           }
           const okMatches = [...apexOut.matchAll(/\|DEBUG\|REF:([^:\n]+):(\w+)/g)];
           const errMatches = [...apexOut.matchAll(/\|DEBUG\|ERR:([^:\n]+):([^\n]+)/g)];
@@ -1125,8 +1318,7 @@ async function main() {
               console.error(`    ${m[1]}: ${m[2].trim()}`);
             }
             if (errMatches.length > 5) console.error(`    ... and ${errMatches.length - 5} more`);
-            console.error(`\nSetup failed at step: Data import tree (${entry.sobject})`);
-            process.exit(1);
+            throw new StepError(`data import tree (${entry.sobject}) — ${errMatches.length} record error(s)`);
           }
           if (entry.saveRefs) {
             for (const m of okMatches) refMap.set(m[1], m[2]);
@@ -1137,28 +1329,66 @@ async function main() {
       }
     }
     if (existsSync(tmpApex)) unlinkSync(tmpApex);
+   });
+  } else {
+    recordSkipped(dataStep, dataStep.available ? 'not selected' : 'no data plan');
   }
 
+  const graphqlStep = stepDefs.find((s) => s.key === 'graphql');
   if (!skipGraphql) {
-    run('UI Bundle npm install', 'npm', ['install'], { cwd: uiBundleDir });
-    run('GraphQL schema (introspect)', 'npm', ['run', 'graphql:schema'], {
-      cwd: uiBundleDir,
-      env: { ...process.env, SF_TARGET_ORG: targetOrg },
+    await runStep(graphqlStep, targetOrg, () => {
+      run('UI Bundle npm install', 'npm', ['install'], { cwd: uiBundleDir });
+      run('GraphQL schema (introspect)', 'npm', ['run', 'graphql:schema'], {
+        cwd: uiBundleDir,
+        env: { ...process.env, SF_TARGET_ORG: targetOrg },
+      });
+      run('GraphQL codegen', 'npm', ['run', 'graphql:codegen'], { cwd: uiBundleDir });
+      run('UI Bundle build (post-codegen)', 'npm', ['run', 'build'], { cwd: uiBundleDir });
     });
-    run('GraphQL codegen', 'npm', ['run', 'graphql:codegen'], { cwd: uiBundleDir });
-    run('UI Bundle build (post-codegen)', 'npm', ['run', 'build'], { cwd: uiBundleDir });
-  } else if (!skipUIBundleBuild && skipDeploy) {
-    // Only build here if the pre-deploy build didn't already run
-    run('UI Bundle npm install', 'npm', ['install'], { cwd: uiBundleDir });
-    run('UI Bundle build', 'npm', ['run', 'build'], { cwd: uiBundleDir });
+  } else {
+    recordSkipped(graphqlStep, 'not selected');
+    if (!skipUIBundleBuild && skipDeploy && !preDeployBundlesBuilt) {
+      // The pre-deploy build never ran (deploy was skipped); build here and
+      // record the uiBundleBuild outcome that the pre-deploy branch would have.
+      await runStep(uiBundleBuildStep, targetOrg, () => {
+        run('UI Bundle npm install', 'npm', ['install'], { cwd: uiBundleDir });
+        run('UI Bundle build', 'npm', ['run', 'build'], { cwd: uiBundleDir });
+      });
+      preDeployBundlesBuilt = true;
+    }
   }
 
-  console.log('\n--- Setup complete ---');
+  // When uiBundleBuild was selected but the dedicated pre-deploy build never ran
+  // (deploy skipped and graphql selected), the build happened inside the graphql
+  // step — which is fail-fast, so reaching here means it succeeded. Record ok.
+  if (!skipUIBundleBuild && !preDeployBundlesBuilt && !results.some((r) => r.key === 'uiBundleBuild')) {
+    recordOk(uiBundleBuildStep);
+  }
 
+  const devStep = stepDefs.find((s) => s.key === 'dev');
   if (!skipDev) {
+    // dev is skippable and terminal: a failure here is a local runtime issue
+    // (port in use, tooling), not a broken setup. Print the summary BEFORE the
+    // (blocking, long-lived) dev server starts so the developer sees the setup
+    // outcome up front; the server then runs in the foreground until Ctrl+C.
+    recordOk(devStep);
+    printSummary(targetOrg);
     console.log('\n--- Launching dev server (Ctrl+C to stop) ---\n');
-    run('Dev server', 'npm', ['run', 'dev'], { cwd: uiBundleDir });
+    const devResult = run('Dev server', 'npm', ['run', 'dev'], { cwd: uiBundleDir, optional: true });
+    if (devResult.status !== 0) {
+      // Replace the optimistic `ok` with a skippable failure and reprint.
+      const row = results.find((r) => r.key === 'dev');
+      row.status = 'failed';
+      row.reason = 'dev server failed to start — setup itself completed; check local runtime';
+      printSummary(targetOrg);
+    }
+    process.exit(finalExitCode());
+  } else {
+    recordSkipped(devStep, 'not selected');
   }
+
+  printSummary(targetOrg);
+  process.exit(finalExitCode());
 }
 
 main().catch((err) => {

package/dist/scripts/validate-org-setup-config.mjs

@@ -0,0 +1,38 @@
+/**
+ * Build / CI gate: validate this package's org-setup.config.json against the
+ * shared schema (W-23043729, spec §5.2).
+ *
+ * Ships inside the SFDX project template, so a generated app can self-check its
+ * org-setup.config.json in its own CI:
+ *   npm run validate:org-setup-config
+ *
+ * Uses the SAME validateConfig + schema as org-setup.mjs runtime, so build-time
+ * and runtime checks can never drift. A missing config file is OK (not every
+ * project ships one); a present-but-invalid config fails the gate.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { validateConfig } from './org-setup-config-schema.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const configPath = resolve(__dirname, 'org-setup.config.json');
+
+if (!existsSync(configPath)) {
+  console.log('✓ org-setup.config.json: not present (nothing to validate)');
+  process.exit(0);
+}
+
+const result = validateConfig(readFileSync(configPath, 'utf8'), configPath);
+if (result.ok) {
+  console.log('✓ org-setup.config.json');
+  process.exit(0);
+}
+
+console.error('❌ org-setup.config.json is invalid:');
+for (const err of result.errors) {
+  console.error(`   - ${err}`);
+}
+process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/ui-bundle-template-app-react-template-b2e",
-  "version": "10.23.0",
+  "version": "10.24.0",
   "description": "Salesforce React internal app template",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "",