@salesforce/ui-bundle-template-feature-react-search 11.12.2 → 11.13.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.
 
+## [11.13.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v11.12.2...v11.13.0) (2026-07-09)
+
+
+### Features
+
+* **org-setup:** @W-23043735@ org-setup.mjs UX enhancements ([#709](https://github.com/salesforce-experience-platform-emu/webapps/issues/709)) ([ad7f480](https://github.com/salesforce-experience-platform-emu/webapps/commit/ad7f480232a363a6f6dfd9df13bce6e32e24ac46))
+
+
+
 ## [11.12.2](https://github.com/salesforce-experience-platform-emu/webapps/compare/v11.12.1...v11.12.2) (2026-07-09)
 
 

package/dist/README.md

@@ -12,6 +12,55 @@ npm run sf-project-setup
 
 This installs dependencies in the UI Bundle, builds it, and starts the Vite dev server. Use this after cloning or extracting the project.
 
+## Set up the org
+
+`npm run setup` configures a target org from this project in one command: it logs in
+(a required precondition — auto-skipped if the org is already connected), deploys
+metadata, assigns permission sets, imports sample data, refreshes the GraphQL
+schema/types, and builds the UI Bundle. When `--target-org` is omitted it uses your
+default org or, in an interactive terminal, prompts you to pick one.
+
+```bash
+npm run setup -- --target-org <alias>     # or omit --target-org to use the default / pick
+```
+
+Setup does **not** start the dev server. Once the org is set up, use `dev:preview` to
+refresh the GraphQL types against the org and launch the Vite dev server on its own:
+
+```bash
+npm run dev:preview
+```
+
+### Setup configuration (`scripts/org-setup.config.json`)
+
+`org-setup.config.json` controls which steps run and how. Every top-level section is
+optional; an absent section hides its step. It is validated against a shared schema
+at build/CI time and again at the start of every `npm run setup`, so a malformed
+config fails fast rather than misbehaving.
+
+```jsonc
+{
+  "permsetAssignments": {
+    "assignments": {
+      "My_Access": { "assignee": "currentUser" }
+    }
+  },
+  "role": { "assignee": "currentUser", "roleName": "Admin" },
+  "selfRegistration": {
+    "selfRegProfile": "My Prospect Profile",
+    "accountName": "My Self-Registration"
+  }
+}
+```
+
+When a `selfRegistration` section is present, setup runs a **license pre-check**
+before configuring self-registration: it derives the required `UserLicense` from the
+configured `selfRegProfile` (matched on the stable `LicenseDefinitionKey`, not the
+display name) and, if the org lacks that license or has no available seats, **warns
+and skips** self-registration instead of reporting success — so prospect login can't
+silently fail on an under-provisioned org. No separate license field is configured;
+the requirement always follows the profile the flow assigns.
+
 ## How Do You Plan to Deploy Your Changes?
 
 Do you want to deploy a set of changes, or create a self-contained application? Choose a [development model](https://developer.salesforce.com/tools/vscode/en/user-guide/development-models).

package/dist/force-app/main/default/uiBundles/feature-react-search/package.json

@@ -18,8 +18,8 @@
     "graphql:schema": "node scripts/get-graphql-schema.mjs"
   },
   "dependencies": {
-    "@salesforce/platform-sdk": "^11.12.2",
-    "@salesforce/ui-bundle": "^11.12.2",
+    "@salesforce/platform-sdk": "^11.13.0",
+    "@salesforce/ui-bundle": "^11.13.0",
     "@tailwindcss/vite": "^4.1.17",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -44,8 +44,8 @@
     "@graphql-eslint/eslint-plugin": "^4.1.0",
     "@graphql-tools/utils": "^11.0.0",
     "@playwright/test": "^1.49.0",
-    "@salesforce/graphiti": "^11.12.2",
-    "@salesforce/vite-plugin-ui-bundle": "^11.12.2",
+    "@salesforce/graphiti": "^11.13.0",
+    "@salesforce/vite-plugin-ui-bundle": "^11.13.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/ui-bundle-template-base-sfdx-project",
-  "version": "11.12.2",
+  "version": "11.13.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@salesforce/ui-bundle-template-base-sfdx-project",
-      "version": "11.12.2",
+      "version": "11.13.0",
       "license": "SEE LICENSE IN LICENSE.txt",
       "dependencies": {
         "fast-xml-parser": "^5.9.3",

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/ui-bundle-template-base-sfdx-project",
-  "version": "11.12.2",
+  "version": "11.13.0",
   "description": "Base SFDX project template",
   "license": "SEE LICENSE IN LICENSE.txt",
   "publishConfig": {
@@ -21,7 +21,8 @@
     "prettier": "prettier --write \"**/*.{cls,cmp,component,css,html,js,json,md,page,trigger,xml,yaml,yml}\"",
     "prettier:verify": "prettier --check \"**/*.{cls,cmp,component,css,html,js,json,md,page,trigger,xml,yaml,yml}\"",
     "precommit": "lint-staged",
-    "setup": "node scripts/org-setup.mjs"
+    "setup": "node scripts/org-setup.mjs",
+    "dev:preview": "node scripts/org-setup-dev.mjs"
   },
   "dependencies": {
     "fast-xml-parser": "^5.9.3",

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

@@ -50,6 +50,13 @@ export const ConfigSchema = z
         // 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 also drives the M1 license pre-check (W-23043735):
+        // setup derives the required UserLicense from this profile
+        // (Profile.UserLicense, matched on the stable LicenseDefinitionKey) and
+        // warns + skips self-registration when the org lacks it or has no seats.
+        // No separate license field is declared — the requirement can't drift
+        // from the profile the flow actually assigns.
         selfRegProfile: z.string().min(1),
         accountName: z.string().min(1),
       })

package/dist/scripts/org-setup-dev.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * Dev preview: refresh the GraphQL schema/types against a target org, then launch
+ * the Vite dev server (spec §5.5, M4). This is the step that used to be the final
+ * `dev` stage of org-setup.mjs — extracted here so `npm run setup` terminates
+ * cleanly after graphql, and the long-lived dev server is an explicit, separate
+ * `npm run dev:preview`.
+ *
+ * Unlike setup, this does NOT log in or deploy — it assumes the org is already
+ * set up. It shares org/bundle resolution and the process runner with org-setup
+ * via org-setup-utils.mjs.
+ *
+ * Usage:
+ *   npm run dev:preview                                 # prompt to pick an org + bundle
+ *   npm run dev:preview -- --target-org myorg
+ *   npm run dev:preview -- --target-org myorg --ui-bundle-name my-app
+ *
+ * Flow (in order):
+ *   1. resolve target org (explicit --target-org, else prompt / default org)
+ *   2. resolve UI bundle (explicit --ui-bundle-name, else picker / warning)
+ *   3. npm install            (in the UI bundle)
+ *   4. npm run graphql:schema (SF_TARGET_ORG=<org>)  — introspect the live schema
+ *   5. npm run graphql:codegen                       — regenerate typed operations
+ *   6. npm run dev            (blocking, Ctrl+C to stop)
+ */
+
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { run, resolveSfdxSource, discoverUIBundleDir, resolveTargetOrg } from './org-setup-utils.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  let targetOrg = null;
+  let uiBundleName = null;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--target-org' && args[i + 1]) {
+      targetOrg = args[++i];
+    } else if (args[i] === '--ui-bundle-name' && args[i + 1]) {
+      uiBundleName = args[++i];
+    } else if (args[i] === '--help' || args[i] === '-h') {
+      console.log(`
+Dev preview — refresh GraphQL types then launch the Vite dev server
+
+Usage:
+  npm run dev:preview -- [--target-org <alias>] [--ui-bundle-name <name>]
+
+Options:
+  --target-org <alias>    Target Salesforce org alias. If omitted, you are prompted
+                          to pick from authenticated orgs (or the default org is used).
+  --ui-bundle-name <name> UI bundle folder under uiBundles/ (default: auto-detect / prompt)
+  -h, --help              Show this help
+`);
+      process.exit(0);
+    }
+  }
+  return { targetOrg, uiBundleName };
+}
+
+async function main() {
+  const parsed = parseArgs();
+
+  const targetOrg = await resolveTargetOrg(parsed);
+  const uiBundlesDir = resolve(resolveSfdxSource(ROOT), 'uiBundles');
+  const uiBundleDir = await discoverUIBundleDir(uiBundlesDir, parsed.uiBundleName);
+
+  console.log('Dev preview — target org:', targetOrg, '| UI bundle:', uiBundleDir);
+
+  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 });
+
+  console.log('\n--- Launching dev server (Ctrl+C to stop) ---\n');
+  const devResult = run('Dev server', 'npm', ['run', 'dev'], { cwd: uiBundleDir, optional: true });
+  process.exit(devResult.status ?? 0);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/scripts/org-setup-utils.mjs

@@ -0,0 +1,369 @@
+/**
+ * Shared helpers for the org-setup scripts (W-23043735, spec §5.2/§5.6/Q9).
+ *
+ * Factored out of org-setup.mjs so BOTH `org-setup.mjs` and `org-setup-dev.mjs` import the
+ * same primitives instead of duplicating them:
+ *   - process runners (`run`, `runAsync`, `spawnAsync`)
+ *   - SFDX path + UI-bundle discovery (`resolveSfdxSource`, `discoverAllUIBundleDirs`,
+ *     `discoverUIBundleDir` — with the multi-bundle acknowledgment of §5.1 item 2)
+ *   - the interactive `--target-org` fallback (`resolveTargetOrg`) and its
+ *     single-select picker (`promptSelect`)
+ *   - pure, unit-testable logic for the license gate, SOQL-name validation, org-list
+ *     parsing, and the non-TTY multi-bundle warning
+ *
+ * IMPORTANT: this module is side-effect-free at import time — no top-level
+ * readFileSync / process.exit / CLI run — so it can be imported by tests and by
+ * org-setup-dev.mjs without triggering org-setup's main(). All I/O happens inside the
+ * exported functions, only when they are called. Errors are plain `Error`s (not
+ * org-setup's StepError) to avoid an import cycle; runStep handles both alike.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { readdirSync, existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Pure logic (no I/O) — unit-testable in isolation.
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate that a profile name is safe to interpolate into a SOQL `WHERE Name =
+ * '<name>'` clause (spec §5.3, Q10 — validate-and-fail, NOT an escaper). The
+ * `selfRegProfile` is developer-authored config the app ships, and license /
+ * profile names are not expected to contain special characters, so a `'`, `\`,
+ * or control char is treated as a config mistake to surface loudly rather than a
+ * value to silently escape. Returns the name unchanged when valid; throws a
+ * clear config error otherwise. AC-8.
+ */
+export function validateProfileNameForSoql(name) {
+  const s = String(name);
+  // SOQL string delimiter (') and escape char (\) would break/inject the query;
+  // control chars (C0 + DEL) have no legitimate place in a profile name.
+  if (/['\\]/.test(s) || /[\x00-\x1f\x7f]/.test(s)) {
+    throw new Error(
+      `selfRegProfile name "${name}" contains an unsupported character ` +
+        `(quotes, backslashes, and control characters are not allowed). ` +
+        `Fix the profile name in org-setup.config.json.`,
+    );
+  }
+  return s;
+}
+
+/**
+ * Decide whether the self-reg profile's UserLicense is satisfied, from the rows
+ * a `SELECT UserLicense.LicenseDefinitionKey, UserLicense.Name, UserLicense.Status,
+ * UserLicense.TotalLicenses, UserLicense.UsedLicenses FROM Profile WHERE Name = '…'`
+ * query returns (spec §5.3). The seat math MUST be done here in JS — SOQL cannot
+ * compare two fields (Q3, verified live). Matches/report on the stable
+ * `LicenseDefinitionKey`, never the display Name (AC-2b).
+ *
+ * satisfied ⇔ Status === 'Active' && (total === -1 [unlimited sentinel] || total - used > 0).
+ * 0 rows / null UserLicense ⇒ not satisfied, with a reason naming the profile.
+ *
+ * @returns {{ satisfied: boolean, reason: string|null, license: {key,label,status,total,used}|null }}
+ */
+export function evaluateLicenseRows(rows, profileName) {
+  const lic = Array.isArray(rows) ? rows[0]?.UserLicense : null;
+  if (!lic) {
+    return {
+      satisfied: false,
+      reason: `no UserLicense found for profile "${profileName}" — the profile is missing in the org or its name is misspelled`,
+      license: null,
+    };
+  }
+  const key = lic.LicenseDefinitionKey ?? null;
+  const label = lic.Name ?? key ?? 'unknown license';
+  const total = Number(lic.TotalLicenses);
+  const used = Number(lic.UsedLicenses);
+  const license = { key, label, status: lic.Status, total, used };
+
+  if (lic.Status !== 'Active') {
+    return { satisfied: false, reason: `license ${label} (${key}) is not Active (Status=${lic.Status})`, license };
+  }
+  // Seat counts should always be integers in practice, but guard against a
+  // missing/non-numeric field so the skip reason stays legible (not "NaN/NaN").
+  if (!Number.isFinite(total) || !Number.isFinite(used)) {
+    return { satisfied: false, reason: `could not read seat counts for license ${label} (${key})`, license };
+  }
+  // -1 is the documented "unlimited" sentinel (defensive — unverified live, §5.3).
+  if (total === -1 || total - used > 0) {
+    return { satisfied: true, reason: null, license };
+  }
+  return {
+    satisfied: false,
+    reason: `license ${label} (${key}) has no available seats (${used}/${total} used)`,
+    license,
+  };
+}
+
+/**
+ * Parse `sf org list --json` defensively into a flat org list + the default org
+ * (spec §5.1 item 3; mirrors isOrgConnected's try/catch tolerance). Collects
+ * every array under `result` (nonScratchOrgs, scratchOrgs, sandboxes, devHubs, …)
+ * so the picker sees all authenticated orgs; the default is the entry marked
+ * `isDefaultUsername`. Malformed / unexpected JSON ⇒ empty result (caller then
+ * falls back to the clear error).
+ *
+ * @returns {{ orgs: Array<{alias:string|null, username:string, isDefault:boolean}>, defaultOrg: string|null }}
+ */
+export function parseOrgList(jsonText) {
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonText);
+  } catch {
+    return { orgs: [], defaultOrg: null };
+  }
+  const result = parsed?.result;
+  if (!result || typeof result !== 'object') return { orgs: [], defaultOrg: null };
+
+  const orgs = [];
+  const seen = new Set();
+  for (const val of Object.values(result)) {
+    if (!Array.isArray(val)) continue;
+    for (const entry of val) {
+      if (!entry || typeof entry !== 'object' || !entry.username) continue;
+      if (seen.has(entry.username)) continue;
+      seen.add(entry.username);
+      orgs.push({
+        alias: entry.alias ?? null,
+        username: entry.username,
+        isDefault: entry.isDefaultUsername === true,
+      });
+    }
+  }
+  const def = orgs.find((o) => o.isDefault);
+  return { orgs, defaultOrg: def ? (def.alias ?? def.username) : null };
+}
+
+/**
+ * Multi-line warning for the non-TTY multi-bundle case (spec §5.1 item 2, AC-4b):
+ * there is nothing to interactively acknowledge, so keep the deterministic
+ * `all[0]` pick but never do it silently — name every bundle, the chosen one, and
+ * the `--ui-bundle-name` remedy.
+ */
+export function buildMultiBundleWarning(allBundleNames, chosen) {
+  return [
+    `⚠ Multiple UI bundles found under uiBundles/ (${allBundleNames.length}):`,
+    ...allBundleNames.map((n) => `    - ${n}${n === chosen ? '   ← using this one' : ''}`),
+    `  Using "${chosen}" (first alphabetically). To deploy a different bundle, re-run with:`,
+    `    --ui-bundle-name <name>`,
+  ].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Process runner (moved from org-setup.mjs; plain Error to avoid an import cycle).
+// Only the synchronous `run` is shared — org-setup-dev.mjs runs its steps serially. The
+// async spawn variants stay local to org-setup.mjs where the parallel permset
+// path uses them, so this module exposes no caller-less surface.
+// ---------------------------------------------------------------------------
+
+export function run(name, cmd, args, opts = {}) {
+  const { cwd = process.cwd(), optional = false } = opts;
+  console.log('\n---', name, '---');
+  const result = spawnSync(cmd, args, {
+    cwd,
+    stdio: 'inherit',
+    shell: true,
+    ...(opts.env && { env: opts.env }),
+    ...(opts.timeout && { timeout: opts.timeout }),
+  });
+  if (result.status !== 0 && !optional) {
+    throw new Error(`${name} (exit ${result.status ?? 1})`);
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// SFDX paths + UI-bundle discovery.
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the first package directory's source root (main/default) from
+ * sfdx-project.json under `root`. Exits non-zero with a clear message when the
+ * project file or packageDirectories path is missing. Called explicitly by each
+ * entry script (not at import) so this module stays side-effect-free.
+ */
+export function resolveSfdxSource(root) {
+  const sfdxPath = resolve(root, 'sfdx-project.json');
+  if (!existsSync(sfdxPath)) {
+    console.error('Error: sfdx-project.json not found at project root.');
+    process.exit(1);
+  }
+  const sfdxProject = JSON.parse(readFileSync(sfdxPath, 'utf8'));
+  const pkgDir = sfdxProject?.packageDirectories?.[0]?.path;
+  if (!pkgDir) {
+    console.error('Error: No packageDirectories[].path found in sfdx-project.json.');
+    process.exit(1);
+  }
+  return resolve(root, pkgDir, 'main', 'default');
+}
+
+/** Basename of a bundle dir path, cross-platform. */
+function bundleName(dir) {
+  return dir.split(/[/\\]/).pop();
+}
+
+/**
+ * All UI bundle directories under `uiBundlesDir` (alphabetical, hidden dirs
+ * excluded). When `uiBundleName` is given, returns just that one (erroring if it
+ * doesn't exist). Exits non-zero when the uiBundles dir or a named bundle is
+ * missing.
+ */
+export function discoverAllUIBundleDirs(uiBundlesDir, uiBundleName) {
+  if (!existsSync(uiBundlesDir)) {
+    console.error(`Error: uiBundles directory not found: ${uiBundlesDir}`);
+    process.exit(1);
+  }
+  const entries = readdirSync(uiBundlesDir, { withFileTypes: true });
+  const dirs = entries.filter((e) => e.isDirectory() && !e.name.startsWith('.'));
+  if (dirs.length === 0) {
+    console.error(`Error: No UI bundle folder found under ${uiBundlesDir}`);
+    process.exit(1);
+  }
+  if (uiBundleName) {
+    const requested = dirs.find((d) => d.name === uiBundleName);
+    if (!requested) {
+      console.error(`Error: UI bundle directory not found: ${uiBundleName}`);
+      process.exit(1);
+    }
+    return [resolve(uiBundlesDir, requested.name)];
+  }
+  return dirs.map((d) => resolve(uiBundlesDir, d.name));
+}
+
+/**
+ * Resolve the single UI bundle to operate on, with the multi-bundle
+ * acknowledgment of spec §5.1 item 2 (Q5). When >1 bundle exists and no
+ * `--ui-bundle-name` was given:
+ *   - TTY: present a single-select picker (all bundles, alphabetical all[0]
+ *     preselected) — enter accepts all[0], arrows choose another (AC-4).
+ *   - non-TTY: keep the deterministic all[0] pick but emit the multi-line warning
+ *     (AC-4b) — never a silent pick.
+ * Explicit `--ui-bundle-name` short-circuits both (no prompt, no warning; AC-4c).
+ */
+export async function discoverUIBundleDir(uiBundlesDir, uiBundleName) {
+  const all = discoverAllUIBundleDirs(uiBundlesDir, uiBundleName);
+  if (all.length > 1 && !uiBundleName) {
+    const names = all.map(bundleName);
+    if (process.stdin.isTTY) {
+      const idx = await promptSelect(names, {
+        prompt: 'Multiple UI bundles found — select which one to deploy:',
+        preselectedIndex: 0,
+      });
+      return all[idx];
+    }
+    console.warn(buildMultiBundleWarning(names, names[0]));
+  }
+  return all[0];
+}
+
+// ---------------------------------------------------------------------------
+// Interactive single-select picker + --target-org fallback.
+// ---------------------------------------------------------------------------
+
+/**
+ * Interactive single-select: arrow keys navigate, enter confirms. Returns the
+ * chosen index. Falls through to `preselectedIndex` immediately when stdin is not
+ * a TTY. Built on the same raw-mode scaffolding as promptSteps (org-setup.mjs)
+ * but selects exactly one item (spec §5.1 items 2 & 3).
+ */
+export function promptSelect(options, { prompt = 'Select an option:', preselectedIndex = 0 } = {}) {
+  if (!process.stdin.isTTY || options.length === 0) return Promise.resolve(preselectedIndex);
+
+  let cursor = Math.min(Math.max(0, preselectedIndex), options.length - 1);
+  const RST = '\x1B[0m';
+  const CYAN = '\x1B[36m';
+  const GREEN = '\x1B[32m';
+
+  function render() {
+    return options.map((label, row) => {
+      const ptr = row === cursor ? `${CYAN}❯${RST}` : ' ';
+      const chk = row === cursor ? `${GREEN}●${RST}` : '○';
+      return `${ptr} ${chk} ${label}`;
+    });
+  }
+
+  return new Promise((resolvePromise) => {
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+    process.stdout.write('\x1B[?25l');
+    console.log(`\n${prompt} (↑↓ move, enter confirm):\n`);
+    let prevRows = options.length;
+    process.stdout.write(render().join('\n') + '\n');
+
+    function redraw() {
+      process.stdout.write(`\x1B[${prevRows}A`);
+      const lines = render();
+      for (const line of lines) process.stdout.write(`\x1B[2K${line}\n`);
+      prevRows = lines.length;
+    }
+
+    process.stdin.on('data', (key) => {
+      if (key === '\x03') {
+        process.stdout.write('\x1B[?25h\n');
+        process.exit(0);
+      }
+      if (key === '\r' || key === '\n') {
+        process.stdout.write('\x1B[?25h');
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+        process.stdin.removeAllListeners('data');
+        console.log();
+        resolvePromise(cursor);
+        return;
+      }
+      if (key === '\x1B[A' || key === 'k') {
+        cursor = Math.max(0, cursor - 1);
+        redraw();
+      } else if (key === '\x1B[B' || key === 'j') {
+        cursor = Math.min(options.length - 1, cursor + 1);
+        redraw();
+      }
+    });
+  });
+}
+
+/**
+ * Resolve the target org (spec §5.1 item 3, §15). When `--target-org` is supplied
+ * it is returned verbatim with NO `sf org list` call (AC-7, byte-for-byte the
+ * scripted path). Otherwise discover authenticated orgs via `sf org list --json`
+ * and:
+ *   - TTY: present a picker with the default org at the top and preselected
+ *     (AC-5); enter selects the default.
+ *   - non-TTY: use the default org if resolvable, else exit 1 with a clear
+ *     message (AC-6).
+ */
+export async function resolveTargetOrg(parsed) {
+  if (parsed.targetOrg) return parsed.targetOrg;
+
+  const listResult = spawnSync('sf', ['org', 'list', '--json'], {
+    encoding: 'utf8',
+    shell: true,
+  });
+  const { orgs, defaultOrg } = parseOrgList(listResult.status === 0 ? listResult.stdout : '');
+
+  if (process.stdin.isTTY && orgs.length > 0) {
+    // Default org first + preselected; the rest keep sf's order.
+    const ordered = [...orgs].sort((a, b) => (b.isDefault ? 1 : 0) - (a.isDefault ? 1 : 0));
+    const labels = ordered.map((o) => {
+      const name = o.alias ?? o.username;
+      const suffix = o.alias && o.alias !== o.username ? ` (${o.username})` : '';
+      return `${name}${suffix}${o.isDefault ? '  [default]' : ''}`;
+    });
+    const idx = await promptSelect(labels, { prompt: 'Select the target org:', preselectedIndex: 0 });
+    const chosen = ordered[idx];
+    return chosen.alias ?? chosen.username;
+  }
+
+  if (defaultOrg) {
+    console.log(`No --target-org given; using the default org: ${defaultOrg}`);
+    return defaultOrg;
+  }
+
+  console.error(
+    'Error: --target-org <alias> is required. No default org is set and this is not an ' +
+      'interactive terminal. Set a default org (sf config set target-org=<alias>) or pass --target-org.',
+  );
+  process.exit(1);
+}

package/dist/scripts/org-setup.mjs

@@ -5,19 +5,21 @@
  *
  * Usage:
  *   node scripts/org-setup.mjs --target-org <alias>           # interactive step picker (all selected)
+ *   node scripts/org-setup.mjs                                # prompt to pick an authenticated org
  *   node scripts/org-setup.mjs --target-org <alias> --yes     # skip picker, run all steps
- *   node scripts/org-setup.mjs --target-org afv5 --skip-login
  *   node scripts/org-setup.mjs --target-org afv5 --skip-data --skip-ui-bundle-build
  *   node scripts/org-setup.mjs --target-org myorg --ui-bundle-name my-app
  *
+ * Login is an unconditional precondition (not a toggleable step); the dev server
+ * is launched separately via `npm run dev:preview` (scripts/org-setup-dev.mjs).
+ *
  * Steps (in order):
- *   1. login     — sf org login web only if org not already connected (skip with --skip-login)
- *   2. uiBundle  — (all UI bundles) npm install && npm run build so dist exists for deploy (skip with --skip-ui-bundle-build)
- *   3. deploy    — sf project deploy start --target-org <alias> (requires dist for entity deployment)
- *   4. permset   — assign permsets per org-setup.config.json (skip with --skip-permset; override via --permset-name)
- *   5. data      — prepare unique fields + sf data import tree (skipped if no data dir/plan)
- *   6. graphql   — (in UI bundle) npm run graphql:schema then npm run graphql:codegen
- *   7. dev       — (in UI bundle) npm run dev — launch dev server (skip with --skip-dev)
+ *   login (precondition) — sf org login web only if org not already connected; always runs before deploy
+ *   1. uiBundle  — (all UI bundles) npm install && npm run build so dist exists for deploy (skip with --skip-ui-bundle-build)
+ *   2. deploy    — sf project deploy start --target-org <alias> (requires dist for entity deployment)
+ *   3. permset   — assign permsets per org-setup.config.json (skip with --skip-permset; override via --permset-name)
+ *   4. data      — prepare unique fields + sf data import tree (skipped if no data dir/plan)
+ *   5. graphql   — (in UI bundle) npm run graphql:schema then npm run graphql:codegen
  *
  * Permset assignment config (scripts/org-setup.config.json):
  *   {
@@ -57,6 +59,13 @@ import {
   enableSelfRegInXml,
   NetworkXmlError,
 } from './org-setup-xml.mjs';
+import {
+  discoverAllUIBundleDirs as discoverAllUIBundleDirsIn,
+  discoverUIBundleDir as discoverUIBundleDirIn,
+  resolveTargetOrg,
+  evaluateLicenseRows,
+  validateProfileNameForSoql,
+} from './org-setup-utils.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(__dirname, '..');
@@ -265,7 +274,6 @@ function parseArgs() {
   const permsetNamesExplicit = [];
   let yes = false;
   const flags = {
-    skipLogin: false,
     skipDeploy: false,
     skipPermset: false,
     skipRole: false,
@@ -273,7 +281,6 @@ function parseArgs() {
     skipGraphql: false,
     skipUIBundleBuild: false,
     skipSelfReg: false,
-    skipDev: false,
   };
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--target-org' && args[i + 1]) {
@@ -282,39 +289,42 @@ function parseArgs() {
       uiBundleName = args[++i];
     } else if (args[i] === '--permset-name' && args[i + 1]) {
       permsetNamesExplicit.push(args[++i]);
-    } else if (args[i] === '--skip-login') flags.skipLogin = true;
-    else if (args[i] === '--skip-deploy') flags.skipDeploy = true;
+    } else if (args[i] === '--skip-deploy') flags.skipDeploy = true;
     else if (args[i] === '--skip-permset') flags.skipPermset = true;
     else if (args[i] === '--skip-role') flags.skipRole = true;
     else if (args[i] === '--skip-data') flags.skipData = true;
     else if (args[i] === '--skip-self-reg') flags.skipSelfReg = true;
     else if (args[i] === '--skip-graphql') flags.skipGraphql = true;
     else if (args[i] === '--skip-ui-bundle-build') flags.skipUIBundleBuild = true;
-    else if (args[i] === '--skip-dev') flags.skipDev = true;
-    else if (args[i] === '--yes' || args[i] === '-y') yes = true;
+    // --skip-login and --skip-dev are retired (spec §5.5/§5.6, AC-14): login is now
+    // an unconditional precondition and the dev step moved to `npm run dev:preview`.
+    // Accept them silently as no-ops so existing invocations don't hard-error.
+    else if (args[i] === '--skip-login' || args[i] === '--skip-dev') {
+      /* no-op (retired flag) */
+    } else if (args[i] === '--yes' || args[i] === '-y') yes = true;
     else if (args[i] === '--help' || args[i] === '-h') {
       console.log(`
 Setup CLI — one-command setup for apps in this project
 
 Usage:
-  node scripts/org-setup.mjs --target-org <alias> [options]
-
-Required:
-  --target-org <alias>   Target Salesforce org alias (e.g. myorg)
+  node scripts/org-setup.mjs [--target-org <alias>] [options]
 
 Options:
+  --target-org <alias>   Target Salesforce org alias (e.g. myorg). If omitted, you
+                         are prompted to pick from authenticated orgs (or the
+                         default org is used when not running interactively).
   --ui-bundle-name <name> UI bundle folder name under uiBundles/ (default: auto-detect)
   --permset-name <name>  Assign only this permission set (repeatable). Default: all sets under permissionsets/
-  --skip-login           Skip login step (login is auto-skipped if org is already connected)
   --skip-deploy          Do not deploy metadata
   --skip-permset         Do not assign permission set
   --skip-data            Do not prepare data or run data import
   --skip-graphql         Do not fetch schema or run GraphQL codegen
   --skip-ui-bundle-build Do not npm install / build the UI bundle
-  --skip-dev             Do not launch the dev server at the end
   -y, --yes              Skip interactive step picker; run all enabled steps immediately
   -h, --help             Show this help
 
+To launch the dev server after setup, run:  npm run dev:preview
+
 Permset config (scripts/org-setup.config.json):
   Control per-permset assignment via a config file. Example:
     {
@@ -334,41 +344,22 @@ Permset config (scripts/org-setup.config.json):
       process.exit(0);
     }
   }
-  if (!targetOrg) {
-    console.error('Error: --target-org <alias> is required.');
-    process.exit(1);
-  }
+  // NOTE: no hard-exit on a missing --target-org here (spec §5.4). Resolution is
+  // deferred to resolveTargetOrg(), which either prompts (TTY) or falls back to
+  // the default org / exits with a clear message (non-TTY).
   return { targetOrg, uiBundleName, permsetNamesExplicit, yes, ...flags };
 }
 
+// Bundle discovery lives in org-setup-utils.mjs so org-setup-dev.mjs shares it verbatim.
+// These thin wrappers bind the shared helpers to this script's UIBUNDLES_DIR and
+// keep the existing call-site signatures. discoverUIBundleDir now carries the
+// multi-bundle acknowledgment of spec §5.1 item 2 (TTY picker / non-TTY warning).
 function discoverAllUIBundleDirs(uiBundleName) {
-  if (!existsSync(UIBUNDLES_DIR)) {
-    console.error(`Error: uiBundles directory not found: ${UIBUNDLES_DIR}`);
-    process.exit(1);
-  }
-  const entries = readdirSync(UIBUNDLES_DIR, { withFileTypes: true });
-  const dirs = entries.filter((e) => e.isDirectory() && !e.name.startsWith('.'));
-  if (dirs.length === 0) {
-    console.error(`Error: No UI bundle folder found under ${UIBUNDLES_DIR}`);
-    process.exit(1);
-  }
-  if (uiBundleName) {
-    const requested = dirs.find((d) => d.name === uiBundleName);
-    if (!requested) {
-      console.error(`Error: UI bundle directory not found: ${uiBundleName}`);
-      process.exit(1);
-    }
-    return [resolve(UIBUNDLES_DIR, requested.name)];
-  }
-  return dirs.map((d) => resolve(UIBUNDLES_DIR, d.name));
+  return discoverAllUIBundleDirsIn(UIBUNDLES_DIR, uiBundleName);
 }
 
 function discoverUIBundleDir(uiBundleName) {
-  const all = discoverAllUIBundleDirs(uiBundleName);
-  if (all.length > 1 && !uiBundleName) {
-    console.log(`Multiple UI bundles found; using first: ${all[0].split(/[/\\]/).pop()}`);
-  }
-  return all[0];
+  return discoverUIBundleDirIn(UIBUNDLES_DIR, uiBundleName);
 }
 
 /** API names from permissionsets/*.permissionset-meta.xml in the first package directory. */
@@ -831,6 +822,119 @@ function resolveGuestUsername(siteName, targetOrg) {
   }
 }
 
+/**
+ * M1 license pre-check (spec §5.3). Query the UserLicense that the selfRegProfile
+ * belongs to and decide whether self-registration can proceed. The profile name
+ * is validate-and-fail (Q10, AC-8): a SOQL-special character throws a config
+ * error rather than being escaped — profile names are developer-authored config,
+ * not user input, so a `'` / `\` / control char is a mistake to surface loudly.
+ *
+ * Selection is on the stable LicenseDefinitionKey; the seat math lives in JS
+ * (evaluateLicenseRows) because SOQL cannot compare two fields. A query failure
+ * or 0 rows is treated as "not satisfied" (soft skip), not a hard error.
+ *
+ * @returns {{ satisfied: boolean, reason: string|null }}
+ */
+function checkSelfRegLicense(selfRegConfig, targetOrg) {
+  const profileName = validateProfileNameForSoql(selfRegConfig.selfRegProfile);
+  const query =
+    `SELECT UserLicense.LicenseDefinitionKey, UserLicense.Name, UserLicense.Status, ` +
+    `UserLicense.TotalLicenses, UserLicense.UsedLicenses ` +
+    `FROM Profile WHERE Name = '${profileName}'`;
+  const result = spawnSync('sf', [
+    'data', 'query',
+    '--query', query,
+    '--target-org', targetOrg,
+    '--json',
+  ], { cwd: ROOT, encoding: 'utf8' });
+
+  if (result.status !== 0) {
+    if (result.stderr) console.error(result.stderr);
+    return {
+      satisfied: false,
+      reason: `could not query the UserLicense for profile "${profileName}" (sf data query failed)`,
+    };
+  }
+  let rows;
+  try {
+    rows = JSON.parse(result.stdout).result?.records ?? [];
+  } catch {
+    return {
+      satisfied: false,
+      reason: `could not parse the UserLicense query result for profile "${profileName}"`,
+    };
+  }
+  const { satisfied, reason } = evaluateLicenseRows(rows, profileName);
+  return { satisfied, reason };
+}
+
+/**
+ * Read the UserLicense the selfRegProfile requires straight from the local
+ * profile metadata's <userLicense> element. The deploy pre-check runs BEFORE
+ * the profile is deployed, so querying the org's Profile table returns 0 rows
+ * and can only report "profile missing" — which never tells the user which
+ * license to add. The profile source we are about to deploy is the
+ * authoritative declaration of the required license.
+ *
+ * @returns {string|null} the license name, or null if the file / field is absent
+ */
+function readProfileUserLicense(selfRegProfile) {
+  const profilePath = resolve(SFDX_SOURCE, 'profiles', `${selfRegProfile}.profile-meta.xml`);
+  if (!existsSync(profilePath)) return null;
+  const xml = readFileSync(profilePath, 'utf8');
+  const m = xml.match(/<userLicense>\s*([^<]+?)\s*<\/userLicense>/);
+  return m ? m[1].trim() : null;
+}
+
+/**
+ * Deploy license pre-check (spec §5.3). `sf project deploy start` fails with a
+ * cryptic error when the org lacks the UserLicense the selfRegProfile's metadata
+ * declares. Resolve the required license NAME from the local profile source, then
+ * query the org's UserLicense by that name so a miss names the actual license the
+ * admin must add — not the not-yet-deployed profile. Seat/status math is shared
+ * with the self-reg gate via evaluateLicenseRows.
+ *
+ * @returns {{ satisfied: boolean, reason: string|null }}
+ */
+function checkDeployLicense(selfRegConfig, targetOrg) {
+  const licenseName = readProfileUserLicense(selfRegConfig.selfRegProfile);
+  // No <userLicense> in the profile source (or profile file absent) — nothing to
+  // gate on; let deploy proceed and surface any real error on its own.
+  if (!licenseName) return { satisfied: true, reason: null };
+
+  const escaped = licenseName.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+  const query =
+    `SELECT LicenseDefinitionKey, Name, Status, TotalLicenses, UsedLicenses ` +
+    `FROM UserLicense WHERE Name = '${escaped}'`;
+  const result = spawnSync('sf', [
+    'data', 'query',
+    '--query', query,
+    '--target-org', targetOrg,
+    '--json',
+  ], { cwd: ROOT, encoding: 'utf8' });
+
+  if (result.status !== 0) {
+    if (result.stderr) console.error(result.stderr);
+    return { satisfied: false, reason: `could not query UserLicense "${licenseName}" (sf data query failed)` };
+  }
+  let rows;
+  try {
+    rows = JSON.parse(result.stdout).result?.records ?? [];
+  } catch {
+    return { satisfied: false, reason: `could not parse the UserLicense query result for "${licenseName}"` };
+  }
+  if (rows.length === 0) {
+    return {
+      satisfied: false,
+      reason: `required license "${licenseName}" is not present in the org — add it before deploying`,
+    };
+  }
+  // evaluateLicenseRows expects the license nested under `.UserLicense` (its
+  // Profile-query shape); reshape the direct UserLicense rows to match so the
+  // seat/status logic — and its license-named messages — stay shared.
+  return evaluateLicenseRows(rows.map((r) => ({ UserLicense: r })), selfRegConfig.selfRegProfile);
+}
+
 function isOrgConnected(targetOrg) {
   const result = spawnSync('sf', ['org', 'display', '--target-org', targetOrg, '--json'], {
     cwd: ROOT,
@@ -1124,12 +1228,11 @@ async function main() {
     }
   }
 
+  const parsed = parseArgs();
   const {
-    targetOrg,
     uiBundleName,
     permsetNamesExplicit,
     yes,
-    skipLogin: argSkipLogin,
     skipDeploy: argSkipDeploy,
     skipPermset: argSkipPermset,
     skipRole: argSkipRole,
@@ -1137,8 +1240,11 @@ async function main() {
     skipData: argSkipData,
     skipGraphql: argSkipGraphql,
     skipUIBundleBuild: argSkipUIBundleBuild,
-    skipDev: argSkipDev,
-  } = parseArgs();
+  } = parsed;
+
+  // Resolve the target org up front (spec §5.4): explicit --target-org is used
+  // verbatim; otherwise prompt (TTY) or fall back to the default org / exit.
+  const targetOrg = await resolveTargetOrg(parsed);
 
   // Per-target-org lock: acquired right after the start-of-run
   // sweep and before any step runs, so two runs against the same org cannot
@@ -1165,12 +1271,29 @@ async function main() {
   const selfRegConfig = loadSelfRegConfig(config);
   const hasSelfRegConfig = selfRegConfig !== null;
 
-  // failFast is a fixed, implementer-owned classification — NOT
+  // Validate the selfRegProfile name for SOQL-safety up front (spec §5.3, AC-8),
+  // alongside the config validation and BEFORE any org mutation (login/deploy).
+  // A quote / backslash / control char is a config mistake, not a runtime value
+  // to escape — fail fast here with a clean, actionable message rather than
+  // letting the M1 gate throw a raw stack trace deep in the run after deploy.
+  if (hasSelfRegConfig) {
+    try {
+      validateProfileNameForSoql(selfRegConfig.selfRegProfile);
+    } catch (err) {
+      console.error(`Invalid org-setup.config.json:\n  - ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  // 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.
+  // Login is NOT in this picker (spec §5.6, AC-13): it is an unconditional
+  // precondition run before deploy, not a toggleable step. The dev step is also
+  // gone (spec §5.5): launching the dev server moved to `npm run dev:preview`, so
+  // setup terminates cleanly after graphql (AC-11).
   const stepDefs = [
-    { 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 },
@@ -1178,7 +1301,6 @@ async function main() {
     { 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);
@@ -1187,7 +1309,6 @@ async function main() {
     on[s.key] = selections[i];
   });
 
-  const skipLogin = !on.login;
   const skipUIBundleBuild = !on.uiBundleBuild;
   const skipDeploy = !on.deploy;
   const skipPermset = !on.permset;
@@ -1195,41 +1316,35 @@ async function main() {
   const skipSelfReg = !on.selfReg;
   const skipData = !on.data;
   const skipGraphql = !on.graphql;
-  const skipDev = !on.dev;
 
-  const needsUIBundle = !skipUIBundleBuild || !skipGraphql || !skipDev;
-  const uiBundleDir = needsUIBundle ? discoverUIBundleDir(uiBundleName) : null;
+  const needsUIBundle = !skipUIBundleBuild || !skipGraphql;
+  const uiBundleDir = needsUIBundle ? await discoverUIBundleDir(uiBundleName) : null;
   const doData = !skipData;
 
   console.log('Setup — target org:', targetOrg, '| UI bundle:', uiBundleDir ?? '(none)');
   console.log(
-    'Steps: login=%s deploy=%s permset=%s role=%s selfReg=%s data=%s graphql=%s uiBundle=%s dev=%s',
-    !skipLogin,
+    'Steps: login=always deploy=%s permset=%s role=%s selfReg=%s data=%s graphql=%s uiBundle=%s',
     !skipDeploy,
     !skipPermset,
     !skipRole,
     !skipSelfReg,
     doData,
     !skipGraphql,
-    !skipUIBundleBuild,
-    !skipDev
+    !skipUIBundleBuild
   );
 
-  const loginStep = stepDefs.find((s) => s.key === 'login');
-  if (!skipLogin) {
-    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: 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');
-  }
+  // Login is an unconditional precondition (spec §5.6, AC-13): it is not part of
+  // the step picker and cannot be skipped. It still no-ops when the org is already
+  // connected, and stays fail-fast — a failed browser login aborts before deploy.
+  const loginStep = { key: 'login', label: 'Login — org authentication', failFast: true };
+  await runStep(loginStep, targetOrg, async () => {
+    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]);
+    }
+  });
 
   // Ensure the self-reg profile is in networkMemberGroups before deploy so that
   // subsequent selfRegProfile / selfRegistration updates don't fail. This is
@@ -1274,6 +1389,19 @@ async function main() {
   const deployStep = stepDefs.find((s) => s.key === 'deploy');
   if (!skipDeploy) {
     await runStep(deployStep, targetOrg, () => {
+      // License pre-check (spec §5.3): deploy fails with a cryptic error when the
+      // org lacks the UserLicense the selfRegProfile's metadata requires. Verify a
+      // seat is available BEFORE `sf project deploy start` so the run aborts with a
+      // clean message NAMING the missing license. The required license is read from
+      // the local profile source (the profile isn't in the org yet pre-deploy, so
+      // querying it would only report "profile missing"). Only gates when self-reg
+      // is configured — that config names the profile the license is derived from.
+      if (selfRegConfig) {
+        const licenseGate = checkDeployLicense(selfRegConfig, targetOrg);
+        if (!licenseGate.satisfied) {
+          throw new StepError(`deploy blocked — ${licenseGate.reason}`);
+        }
+      }
       run('Deploy metadata', 'sf', ['project', 'deploy', 'start', '--target-org', targetOrg], {
         timeout: 180000,
       });
@@ -1382,20 +1510,32 @@ async function main() {
 
   const selfRegStep = stepDefs.find((s) => s.key === 'selfReg');
   if (!skipSelfReg) {
-    console.log('\n--- Enable self-registration ---');
-    // 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);
-    });
+    // M1 license pre-check (spec §5.3): self-registration requires a seat on the
+    // UserLicense the selfRegProfile belongs to. Verify it BEFORE running the step
+    // — recordSkipped is only reachable here, ahead of runStep (mirroring the
+    // not-selected branch); once inside a step body an unmet precondition could
+    // only record `failed`. A missing / inactive / seatless license is a soft
+    // precondition, not a setup failure, so warn + recordSkipped and move on.
+    const licenseGate = checkSelfRegLicense(selfRegConfig, targetOrg);
+    if (!licenseGate.satisfied) {
+      console.warn(`\n--- Self-registration skipped ---\n  ⚠ ${licenseGate.reason}`);
+      recordSkipped(selfRegStep, licenseGate.reason);
+    } else {
+      console.log('\n--- Enable self-registration ---');
+      // 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');
   }
@@ -1547,29 +1687,12 @@ async function main() {
     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');
-    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');
-  }
-
+  // Setup terminates cleanly here (spec §5.5, AC-11). Launching the dev server is
+  // no longer part of setup — run `npm run dev:preview` (scripts/org-setup-dev.mjs) for that.
   printSummary(targetOrg);
+  if (finalExitCode() === 0) {
+    console.log('\nTo launch the dev server, run:  npm run dev:preview');
+  }
   process.exit(finalExitCode());
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/ui-bundle-template-feature-react-search",
-  "version": "11.12.2",
+  "version": "11.13.0",
   "description": "[Beta] Configuration-driven multi-source search for UI Bundles",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "",