@salesforce/afv-skills 1.55.0 → 1.56.0

package/skills/consumer-goods-accruals-datakit-deploy/scripts/steps/utils.js

@@ -0,0 +1,514 @@
+const { execSync, execFileSync, spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+/** Returns the correct sf binary name for the current OS. */
+function getSfBin() {
+  return process.platform === 'win32' ? 'sf.cmd' : 'sf';
+}
+
+/**
+ * sf org display --json stopped returning a real accessToken as of CLI v2.136.8
+ * (the field becomes a redacted hint string). Fall back to
+ * `sf org auth show-access-token` on those versions.
+ */
+const ACCESS_TOKEN_VIA_SHOW_SINCE = [2, 136, 8];
+
+function getSfCliVersion() {
+  try {
+    let raw;
+    if (process.platform === 'win32') {
+      const r = spawnSync('sf.cmd', ['version', '--json'], {
+        encoding: 'utf8', stdio: 'pipe', shell: true, windowsVerbatimArguments: true
+      });
+      if (r.error) return null;
+      raw = r.stdout;
+    } else {
+      raw = execFileSync(getSfBin(), ['version', '--json'], { encoding: 'utf8', stdio: 'pipe' });
+    }
+    const { cliVersion } = JSON.parse(raw);
+    const m = (cliVersion || '').match(/(\d+)\.(\d+)\.(\d+)/);
+    return m ? m.slice(1).map(Number) : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function isSfAtLeast(version, min) {
+  if (!version) return true; // unknown version → assume new enough
+  for (let i = 0; i < min.length; i++) {
+    if ((version[i] || 0) !== (min[i] || 0)) return (version[i] || 0) > (min[i] || 0);
+  }
+  return true;
+}
+
+/**
+ * Run an sf CLI command with args and return parsed JSON output.
+ * Works on both Windows (cmd.exe) and Unix (sh).
+ * @param {string[]} args - CLI arguments
+ * @returns {any} parsed JSON result
+ */
+function execSfJson(args, options) {
+  options = options || {};
+  let rawOutput;
+  try {
+    if (process.platform === 'win32') {
+      // execFileSync cannot run .cmd files without shell:true, but shell:true
+      // word-splits args containing spaces. Use spawnSync with shell:true +
+      // windowsVerbatimArguments:true and pre-quote space-bearing args so that
+      // cmd.exe receives them intact.
+      const winArgs = args.map(a =>
+        (a.includes(' ') || a.includes("'")) ? `"${a.replace(/"/g, '\\"')}"` : a
+      );
+      const r = spawnSync('sf.cmd', winArgs, {
+        encoding: 'utf8', stdio: 'pipe', shell: true, windowsVerbatimArguments: true,
+        cwd: options.cwd
+      });
+      if (r.error) throw r.error;
+      rawOutput = r.stdout;
+    } else {
+      rawOutput = execFileSync(getSfBin(), args, { encoding: 'utf8', stdio: 'pipe', cwd: options.cwd });
+    }
+  } catch (err) {
+    if (err.stdout) {
+      rawOutput = err.stdout;
+    } else {
+      throw err;
+    }
+  }
+  return JSON.parse(rawOutput);
+}
+
+/**
+ * Execute a command and return the output
+ */
+function exec(command, options = {}) {
+  try {
+    return execSync(command, {
+      encoding: 'utf8',
+      stdio: options.silent ? 'pipe' : 'inherit',
+      ...options
+    });
+  } catch (error) {
+    if (options.ignoreError) {
+      // Return the error output if available (for JSON parsing)
+      return error.stdout || error.stderr || '{}';
+    }
+    const safeCmd = command.replace(/Authorization:\s*Bearer\s+[^\s'"\\]+/gi, 'Authorization: Bearer [REDACTED]');
+    console.error(`Error executing command: ${safeCmd}`);
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * Get org details including instance URL and access token
+ */
+function getOrgDetails(orgAlias) {
+  const useShowAccessTokenCommand = isSfAtLeast(getSfCliVersion(), ACCESS_TOKEN_VIA_SHOW_SINCE);
+  const result = execSfJson(['org', 'display', '--target-org', orgAlias, '--json']);
+
+  if (result.status !== 0) {
+    console.error('Error: Failed to get org details');
+    process.exit(1);
+  }
+
+  let accessToken;
+  if (useShowAccessTokenCommand) {
+    const tokenResult = execSfJson(['org', 'auth', 'show-access-token', '--target-org', orgAlias, '--no-prompt', '--json']);
+    if (!tokenResult.result || !tokenResult.result.accessToken) {
+      throw new Error(`Failed to retrieve access token for org "${orgAlias}": ${tokenResult.message || JSON.stringify(tokenResult)}`);
+    }
+    accessToken = tokenResult.result.accessToken;
+  } else {
+    if (!result.result || !result.result.accessToken) {
+      throw new Error(`Failed to retrieve access token for org "${orgAlias}": ${result.message || JSON.stringify(result)}`);
+    }
+    accessToken = result.result.accessToken;
+  }
+
+  return {
+    instanceUrl: result.result.instanceUrl,
+    accessToken,
+    apiVersion: result.result.apiVersion || '62.0',
+    orgId: result.result.id
+  };
+}
+
+/**
+ * Query the org for the TPM Accruals package namespace prefix.
+ * Returns the prefix WITH trailing double underscore (e.g. "cgcloud_dev__"),
+ * or '' for source-only orgs.
+ *
+ * Uses the DataCloudExportScheduler Apex class as a probe — its NamespacePrefix
+ * is the managed package's prefix regardless of the subscriber org's own
+ * namespace. Querying Organization.NamespacePrefix instead would return the
+ * subscriber's prefix, which is only ever populated on packaging/scratch orgs
+ * and would silently return '' on real cgcloud subscribers.
+ */
+function getOrgNamespace(orgAlias) {
+  try {
+    const result = execSfJson(['data', 'query', '--query', "SELECT NamespacePrefix FROM ApexClass WHERE Name = 'DataCloudExportScheduler'", '--target-org', orgAlias, '--json']);
+    const records =
+      result.status === 0 && result.result && result.result.records
+        ? result.result.records
+        : [];
+    const namespaced = records.find(r => r.NamespacePrefix);
+    if (namespaced) {
+      return `${namespaced.NamespacePrefix}__`;
+    }
+  } catch (error) {
+    // Fall through to empty
+  }
+  return '';
+}
+
+/**
+ * Strip a leading namespace prefix from a name (case-insensitive).
+ * Returns a lowercased copy suitable for tolerant comparisons.
+ */
+function normalizeName(name, namespace) {
+  if (!name) return '';
+  let normalized = String(name).toLowerCase();
+  if (namespace) {
+    const nsLower = String(namespace).toLowerCase();
+    if (nsLower && normalized.startsWith(nsLower)) {
+      normalized = normalized.slice(nsLower.length);
+    }
+  }
+  return normalized;
+}
+
+/**
+ * Walk a directory recursively returning all file paths (sync).
+ */
+function walkFiles(dir) {
+  const out = [];
+  if (!fs.existsSync(dir)) return out;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...walkFiles(full));
+    } else {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/**
+ * Build a map of dataSourceBundleDefinition name -> [dataStreamTemplate developer names]
+ * by scanning the dataStreamTemplates folder under a Data Kit's force-app tree.
+ *
+ * This is needed because deploying a DataStreamBundle does not always create a
+ * DataKitDeploymentLog row matching the bundle name itself; instead, rows are
+ * created for the underlying DataStreamTemplates contained in the bundle.
+ *
+ * @param {string} dataKitPath - Path to the Data Kit root (containing force-app/)
+ * @returns {Map<string, string[]>}
+ */
+function getBundleStreamMap(dataKitPath) {
+  const map = new Map();
+  if (!dataKitPath) return map;
+
+  const templatesDir = path.join(
+    dataKitPath,
+    'force-app',
+    'main',
+    'default',
+    'dataStreamTemplates'
+  );
+
+  if (!fs.existsSync(templatesDir)) return map;
+
+  const files = fs
+    .readdirSync(templatesDir)
+    .filter(f => f.endsWith('.dataStreamTemplate-meta.xml'));
+
+  const bundleRegex = /<dataSourceBundleDefinition>\s*([^<\s]+)\s*<\/dataSourceBundleDefinition>/i;
+  // <sourceObjectName> is the stable identifier that appears verbatim (or as a prefix
+  // for ingest streams with hex suffixes) in DataKitDeploymentLog.ComponentName.
+  // E.g. sourceObjectName "tpm_accrualrule_ingest" → log "tpm_accrualrule_ingest_3ADCEDC6".
+  // Fall back to <dataSourceObject> if absent, then to the filename stem.
+  const srcObjNameRegex = /<sourceObjectName>\s*([^<\s]+)\s*<\/sourceObjectName>/i;
+  const srcObjRegex = /<dataSourceObject>\s*([^<\s]+)\s*<\/dataSourceObject>/i;
+
+  for (const file of files) {
+    const fullPath = path.join(templatesDir, file);
+    let content;
+    try {
+      content = fs.readFileSync(fullPath, 'utf8');
+    } catch (error) {
+      continue;
+    }
+
+    const match = content.match(bundleRegex);
+    if (!match) continue;
+
+    const bundleName = match[1];
+    const srcObjNameMatch = content.match(srcObjNameRegex);
+    const srcObjMatch = content.match(srcObjRegex);
+    const streamDevName = srcObjNameMatch
+      ? srcObjNameMatch[1]
+      : srcObjMatch
+        ? srcObjMatch[1]
+        : file.replace(/\.dataStreamTemplate-meta\.xml$/, '');
+
+    if (!map.has(bundleName)) {
+      map.set(bundleName, []);
+    }
+    if (!map.get(bundleName).includes(streamDevName)) {
+      map.get(bundleName).push(streamDevName);
+    }
+  }
+
+  return map;
+}
+
+/**
+ * Determine if any record in the deployment log matches one of the given spec names.
+ *
+ * Matching is namespace-tolerant (prefix is stripped before comparison) and
+ * uses strict equality by default. For DataStreamBundle specs we additionally
+ * allow `endsWith` so a bundle is recognised as deployed when any of its child
+ * stream developer names appears as the suffix of a log entry — which is how
+ * DataKitDeploymentLog records bundle children under managed-package prefixes.
+ *
+ * @param {Array<{ComponentName?: string}>} deploymentLog
+ * @param {{type?: string, names: string[]}} spec
+ * @param {string} namespace
+ */
+function findMatchingRecords(deploymentLog, spec, namespace) {
+  const names = (spec && spec.names) || [];
+  if (names.length === 0) return [];
+  const normalizedNames = names.map(n => normalizeName(n, namespace)).filter(n => n.length > 0);
+  if (normalizedNames.length === 0) return [];
+  // DataStreamBundle: deployed stream names carry namespace prefixes and hex
+  // suffixes (e.g. cgcloud_Promotion_c_Home, tpm_accrualrule_ingest_71560164).
+  // Match when the template dev-name appears as a substring of the log name.
+  const allowSubstring = spec && spec.type === 'DataStreamBundle';
+  return deploymentLog.filter(record => {
+    if (!record.ComponentName) return false;
+    const normalizedLog = normalizeName(record.ComponentName, namespace);
+    return normalizedNames.some(
+      n => n === normalizedLog || (allowSubstring && (normalizedLog.endsWith(n) || normalizedLog.includes(n)))
+    );
+  });
+}
+
+/**
+ * Query DataKitDeploymentLog. The componentSpecs param is kept only for
+ * informational logging; the query returns recent records that we filter later.
+ *
+ * @param {string} orgAlias
+ * @param {Array<{id: string, names: string[]}>} componentSpecs
+ */
+function getDeploymentLogForComponents(orgAlias, componentSpecs) {
+  console.log(`Checking deployment status for ${componentSpecs.length} components...`);
+
+  const query = `SELECT ComponentName, DeploymentStatus, DeploymentError FROM DataKitDeploymentLog ORDER BY CreatedDate DESC LIMIT 500`;
+
+  try {
+    const result = execSfJson(['data', 'query', '--query', query, '--target-org', orgAlias, '--json']);
+
+    if (result.status === 0 && result.result && result.result.records) {
+      return result.result.records;
+    }
+    return [];
+  } catch (error) {
+    console.log('No existing deployment log found (this is okay for first deployment)');
+    return [];
+  }
+}
+
+/**
+ * Determine which component specs are already successfully deployed.
+ * A spec is considered deployed when at least one matching record in the
+ * deployment log has DeploymentStatus = 'Successful'.
+ *
+ * @param {Array<{ComponentName?: string, DeploymentStatus?: string}>} deploymentLog
+ * @param {Array<{id: string, names: string[]}>} componentSpecs
+ * @param {string} namespace
+ * @returns {Set<string>} set of deployed component ids
+ */
+function getDeployedComponents(deploymentLog, componentSpecs, namespace = '') {
+  const deployed = new Set();
+
+  componentSpecs.forEach(spec => {
+    const matches = findMatchingRecords(deploymentLog, spec, namespace);
+    const hasSuccess = matches.some(r => r.DeploymentStatus === 'Successful');
+    if (hasSuccess) {
+      deployed.add(spec.id);
+    }
+  });
+
+  return deployed;
+}
+
+/**
+ * Query the Salesforce server clock via Organization.SystemModstamp.
+ *
+ * Returns the MAX(CreatedDate) of existing DataKitDeploymentLog rows as a
+ * server-side baseline timestamp. Rows created after this point belong to the
+ * current deploy. Using MAX(CreatedDate) — a value already on the server —
+ * avoids local clock-skew entirely.
+ *
+ * Returns null if no rows exist yet (caller should omit the WHERE clause).
+ *
+ * @param {string} orgAlias
+ * @returns {string|null} ISO-8601 timestamp or null
+ */
+function getMaxCreatedDate(orgAlias) {
+  const result = execSfJson(['data', 'query', '--query', 'SELECT MAX(CreatedDate) maxDate FROM DataKitDeploymentLog', '--target-org', orgAlias, '--json']);
+  if (result.status === 0 && result.result && result.result.records && result.result.records.length > 0) {
+    return result.result.records[0].maxDate ?? null;
+  }
+  return null;
+}
+
+/**
+ * Wait for data kit deployment to complete.
+ *
+ * Uses a server-side timestamp boundary (WHERE CreatedDate > deploymentStartTime)
+ * rather than an opaque Id comparison to isolate log rows created by this deploy.
+ * The timestamp is obtained from the Salesforce server via getMaxCreatedDate() just
+ * before the deploy is triggered, making the filter immune to local clock-skew.
+ *
+ * @param {string} orgAlias
+ * @param {Array<{id: string, names: string[]}>} componentSpecs
+ * @param {string|null} deploymentStartTime - MAX(CreatedDate) from DataKitDeploymentLog captured before deploy; null = no filter (no prior rows)
+ * @param {string} namespace - Optional org namespace prefix (e.g. "cgcloud_dev__")
+ */
+async function waitForDeploymentCompletion(orgAlias, componentSpecs, deploymentStartTime, namespace = '') {
+  console.log(`\nWaiting for deployment to complete...`);
+  console.log(`Tracking ${componentSpecs.length} components`);
+
+  const maxWaitTime = 90 * 60 * 1000; // 90 minutes — production orgs typically take 60-90 min
+  const pollInterval = 60_000; // 60 seconds
+  const startTime = Date.now();
+
+  const completedComponents = new Set();
+  const failedComponents = new Map();
+
+  while (Date.now() - startTime < maxWaitTime) {
+    const whereClause = deploymentStartTime ? `WHERE CreatedDate > ${deploymentStartTime}` : '';
+    const query = `SELECT ComponentName, DeploymentStatus, DeploymentError FROM DataKitDeploymentLog ${whereClause} ORDER BY CreatedDate DESC LIMIT 500`;
+
+    let deploymentLog = [];
+    try {
+      const result = execSfJson(['data', 'query', '--query', query, '--target-org', orgAlias, '--json']);
+      if (result.status === 0 && result.result && result.result.records) {
+        deploymentLog = result.result.records;
+      }
+    } catch (error) {
+      console.warn(`Polling query failed (will retry): ${error.message}`);
+    }
+
+    componentSpecs.forEach(spec => {
+      if (completedComponents.has(spec.id) || failedComponents.has(spec.id)) {
+        return;
+      }
+      const matches = findMatchingRecords(deploymentLog, spec, namespace);
+      if (matches.length === 0) return;
+
+      const failure = matches.find(r => r.DeploymentStatus === 'Failure');
+      const hasSuccess = matches.some(r => r.DeploymentStatus === 'Successful');
+
+      if (failure) {
+        failedComponents.set(spec.id, failure.DeploymentError || 'Unknown error');
+      } else if (hasSuccess) {
+        completedComponents.add(spec.id);
+      }
+    });
+
+    const inProgressCount = componentSpecs.length - completedComponents.size - failedComponents.size;
+
+    console.log(`  Status: ${completedComponents.size} succeeded, ${failedComponents.size} failed, ${inProgressCount} in progress`);
+
+    if (failedComponents.size > 0) {
+      console.error('\nERROR: Deployment failed with errors:');
+      failedComponents.forEach((error, component) => {
+        console.error(`  - ${component}: ${error}`);
+      });
+      process.exit(1);
+    }
+
+    if (completedComponents.size === componentSpecs.length) {
+      console.log(`[OK] Deployment completed successfully!\n`);
+      return true;
+    }
+
+    await new Promise(resolve => setTimeout(resolve, pollInterval));
+  }
+
+  console.error(`\nERROR: Deployment timed out after ${maxWaitTime / 1000 / 60} minutes`);
+  console.error(`Completed: ${completedComponents.size}/${componentSpecs.length}`);
+  const pending = componentSpecs.filter(s => !completedComponents.has(s.id)).map(s => s.id);
+  if (pending.length > 0) {
+    console.error(`Pending: ${pending.join(', ')}`);
+  }
+  throw new Error(`Deployment timed out after ${maxWaitTime / 1000 / 60} minutes — ${pending.length} component(s) still in progress`);
+}
+
+/**
+ * Run `sf project deploy start` with --json, validate via status fields.
+ * SF CLI exits 1 even on success when warnings are present.
+ */
+function execDeployJson(deployArgs, options) {
+  options = options || {};
+  const allArgs = deployArgs.concat(['--json']);
+  let rawOutput;
+  try {
+    if (process.platform === 'win32') {
+      const winArgs = allArgs.map(a =>
+        (a.includes(' ') || a.includes("'")) ? `"${a.replace(/"/g, '\\"')}"` : a
+      );
+      const r = spawnSync('sf.cmd', winArgs, {
+        encoding: 'utf8', stdio: 'pipe', shell: true, windowsVerbatimArguments: true,
+        cwd: options.cwd
+      });
+      if (r.error) throw r.error;
+      rawOutput = r.stdout;
+    } else {
+      rawOutput = execFileSync(getSfBin(), allArgs, { encoding: 'utf8', stdio: 'pipe', cwd: options.cwd });
+    }
+  } catch (err) {
+    if (err.stdout) {
+      rawOutput = err.stdout;
+    } else {
+      throw err;
+    }
+  }
+  const result = JSON.parse(rawOutput);
+  if (result.status !== 0) {
+    const failures = (((result.result || {}).details) || {}).componentFailures || [];
+    const msg = failures.length
+      ? failures.map(f => f.fullName + ': ' + f.problem).join('\n')
+      : (result.message || 'Deploy failed');
+    throw new Error(msg);
+  }
+  if (result.result && result.result.status === 'Failed') {
+    const failures2 = ((result.result.details || {}).componentFailures) || [];
+    const msg2 = failures2.length
+      ? failures2.map(f => f.fullName + ': ' + f.problem).join('\n')
+      : 'Deploy failed';
+    throw new Error(msg2);
+  }
+  return result;
+}
+module.exports = {
+  exec,
+  execDeployJson,
+  getOrgDetails,
+  getOrgNamespace,
+  getMaxCreatedDate,
+  normalizeName,
+  walkFiles,
+  getBundleStreamMap,
+  getDeploymentLogForComponents,
+  getDeployedComponents,
+  waitForDeploymentCompletion,
+  getSfBin,
+  execSfJson
+};

package/skills/consumer-goods-sync-management-configure/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: consumer-goods-sync-management-configure
+description: "Use this skill to set up Salesforce Consumer Goods (CG) Cloud Mobile Sync end-to-end for the Sync Management App managed package — it runs all three acts in order (Act 1 Setup Sync, Act 2 Assign Users, Act 3 Plan & Verify), not just installing the baseline, so a sales rep can see the day's planned visits offline. Use it when asked to \"set up CG Cloud mobile sync\", \"configure Consumer Goods mobile sync\", \"set up sync for Retail Execution\", \"install the sync baseline\", \"assign a user to the sync configuration\", \"verify the sync setup\", or \"why can't my rep see their planned visits offline\" when sync setup or the baseline install is suspected. DO NOT TRIGGER for general CG Cloud mobile-app troubleshooting unrelated to sync setup, for authoring new or custom sync baselines (this installs only shipped baselines discovered at runtime), or for building or customizing the mobile app UI itself — those are out of scope."
+metadata:
+  version: "1.0"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+**Setting up CG Cloud Mobile Sync means running all three acts in order — Act 1 (Setup Sync), Act 2 (Assign Users), Act 3 (Plan & Verify) — NOT just installing the sync artefacts.** Installing the baseline is one step of Act 1; finishing it is not finishing the setup.
+
+Guide an admin/implementer through setting up **Consumer Goods (CG) Cloud Mobile Sync** for a customer org so a sales rep can install the CG Cloud Mobile App and see the day's planned visits **offline**. The moving parts live in the managed package **`Sync Management App`** (its namespace is resolved at runtime — see `ns_prefix` in Session state) plus CG Cloud **core / Retail Execution** settings.
+
+This skill automates as much as a **real** transport can trigger — a Headless-360 / generic-core call (SOQL, sObject REST, Connect, Tooling), an `sf` deploy, or a **`global @RestResource /v1/*`** endpoint in the package. A `public` package method is **not** enough: in a managed package `public` is namespace-private (unreachable from a subscriber org), so only `global`/`webservice`/`@RestResource` members are triggerable. Where neither a generic core capability nor an invokable package action can complete a step, the skill **reports what's needed — and who provides it — and stops that step**; it never fakes a capability.
+
+## Scope & definition of done — READ THIS FIRST
+
+**"Set up CG Cloud mobile sync" / "set up sync for Retail Execution" / "configure Consumer Goods mobile sync" with no narrowing qualifier means run ALL THREE ACTS, in order: Act 1 → Act 2 → Act 3.** It does **not** mean "install the artefacts." If you are about to run only the install for an unqualified request, that is the bug this section prevents — start at Act 1, step 1 (readiness).
+
+**You are NOT done after installing artefacts.** Setup is complete only when **Act 3's end state** is reached (the activated config listed, verified across the four objects, and checked against the baseline files). A run that ends after the install is a *partial* run — say so plainly.
+
+**Act 1 is not "install-only."** It has hard **readiness gates before** the install — the **namespace gate** (A1.1) and **Retail Execution enablement** (A1.2) — and a **verify after** it (A1.4). Installing the baseline into a non-RE-enabled org produces a config that can never sync, so readiness is checked first; a hard miss is **reported-and-stopped**, not written around. The baseline install *is* the sync configuration (the root `Sync_Config__c` and its values come from the baseline CSVs) — there is no separate "create config" step.
+
+**A step the skill can't complete is a stop-*that-step* signal, not stop-the-whole-run.** Report the boundary and **who provides the missing piece** (the CG Cloud platform / Retail Execution, or the org admin), then **continue with every unblocked step.** Only a *hard readiness miss* halts the sequence: the sync metadata absent (neither a package install nor an org namespace resolves), RE cannot be enabled and isn't already on, or — under `Default_IOU` — the target user's missing default mobility IOU.
+
+**The only legitimate subset run** is when the admin's own ask is narrow (e.g. "sync's already installed, just assign Chantelle", "just verify what's activated") — see the routing table. When the ask is unqualified or you are unsure, run the full 1→3.
+
+## The transport contract — every automatable step is `core` or `Sync Management App`
+
+This is the honesty spine. Before running a step, know its transport, and **never fake success for a step no transport can complete:**
+
+- **`core`** — a generic Salesforce / Headless-360 capability: direct SOQL via `execute_api` → `GET /query?q=...`; the CG Cloud core `RetailExecutionSettings` get→set org-preference triad; sObject-REST writes (`POST /services/data/vXX.0/sobjects/<Entity>`); Schema/Tooling **describe** reads.
+- **`Sync Management App`** — an action triggered inside the package. The real headless surface is a **`global @RestResource /v1/*`** endpoint, chiefly the three **`/v1/syncconfig/*`** routes: **`/install`** (GET discover + POST install — A1.3), **`/configs`** (GET deployed configs + strategy — A3.1 list), **`/assignment`** (GET/POST/DELETE user→config binding — A2.3). **Not** `Sync Management App`: `public` Apex methods (namespace-private) and Visualforce actions.
+
+**When neither transport can complete a step**, report what's missing, name **who provides it**, and stop that step — do not guess an API name or write around it. The genuine non-automatable points are few: the *advanced*-RE pilot GA gate (A1.2, platform-owned, no API) and IOU-membership **creation** (A2.2, a CG Cloud core / RE task the skill only reads). Deep transport rules: `references/transports-and-namespace.md`.
+
+## Mandatory pre-write plan — state this before your FIRST write
+
+Before you execute a single write (enable RE, install a baseline, create a mapping row), post a short plan that makes your scope decision **explicit and reviewable**:
+
+1. **The full journey is three acts** — Act 1 (Setup Sync), Act 2 (Assign Users), Act 3 (Plan & Verify).
+2. **Which acts/sub-acts you will run, and which you will skip** — for every skip, **quote the exact words in the admin's request that narrow the scope** ("the request said 'set up sync'" is NOT a narrowing qualifier); for any step you can't complete, name who provides the missing piece.
+3. **The target org**, confirmed explicitly (never silently inherited), and **the resolved `ns_prefix`** you will use for package objects.
+4. **Where you will start.** For an unqualified request this is Act 1, step 1 (readiness: namespace + RE) — never the install.
+5. **Persist this plan to `report.md`** in the working directory — writing that file is the very first action you take, before any org write. Append each Act's outcome (steps run, transport tag, read-back result, blocked steps) as you complete it, and write a final verdict at the end. This file — not the chat transcript — is the run's deliverable; it must exist even if the run stops early. Contract: "Write the run report to disk" in `references/verify-and-smoke.md`.
+
+## Entry point — route on the admin's actual ask
+
+**Default rule:** unless the ask *explicitly narrows the scope*, treat it as the full setup and **run Acts 1→2→3 in order.** When in doubt, run the full journey.
+
+| Signal | Where to start |
+|---|---|
+| **"Set up CG Cloud mobile sync" / "set up sync for Retail Execution" / no narrowing qualifier / no prior state** | **Run the FULL journey: confirm org + resolve namespace, then Act 1 step 1 (readiness: namespace + RE), then Acts 1→2→3. NOT "just install." Not done until Act 3's end state.** |
+| "Sync's already installed, I just need to assign a user" | Narrow → Act 2. First read back the installed config (Act 3 list step) to confirm a config is deployed before binding a user. |
+| "Just install the Retail Execution baseline" | Narrow → Act 1 A1.3 only, **after** confirming A1.1/A1.2 readiness **and** explicit confirmation of which baseline. GET `/v1/syncconfig/install` to discover, then POST to install. Never hand-roll via raw sObject inserts. Report the skipped steps (A1.4, Acts 2–3) as not-done. |
+| "Just verify / list what's activated" | Act 3. Read-only; no writes. |
+| "Enable Retail Execution" | A1.2 only. CG Cloud **core**, a working `core` write; only *advanced*-RE hits the platform-owned pilot gate (no API). |
+
+## Session state (track across the conversation)
+
+- `target_org_alias` — the org being configured; confirmed explicitly before any write.
+- `ns_prefix` — namespace prefix (with trailing `__`), **discovered at runtime** by A1.1 (never hardcoded), resolved once and used for every package-object path. Two sources: the installed managed package (`InstalledSubscriberPackage.NamespacePrefix`) or the org's own registered namespace (`Organization.NamespacePrefix`, source-deployed DE/packaging org).
+- `api_version` — the Salesforce REST API version for raw-HTTP URLs. **Never hardcode.** Resolve once via `GET /services/data`, take the highest `version`. `execute_api` calls are versionless.
+- `org_ready` — bool; true when A1.1's namespace gate passes AND A1.2 (RE enabled) passes. A hard miss on either halts the run.
+- `installed_config_id` / `installed_version` — from the baseline install (A1.3). The install *is* the config — no separate "config created" flag.
+- `act1_complete`, `act2_complete`, `act3_complete` — bool per Act; run strictly 1→2→3. For an unqualified request, all three must be `true` (minus reported non-automatable steps) before reporting complete.
+- `resolution_strategy` — the config root's `Business_Area_Resolution_Strategy__c` (`Default_IOU` vs `Custom_User_Field`); decides whether A2.3 is IOU-implicit (via A2.2) or an explicit mapping write.
+- `blocked_steps` — running list of steps the skill could not complete, each with the boundary and who provides the missing piece.
+- `report_path` — the run's **deliverable on disk**: a `report.md` in the working directory. Created **before the first org write** (starting with the pre-write plan) and appended at each Act boundary, so a partial or interrupted run still leaves a faithful record. Reporting only in chat does **not** satisfy this — the record must exist as a file.
+
+## Per-sub-act transport map (compact)
+
+Single source of truth for which transport each step uses. **Full detail (API names, fallbacks, owners): `references/transports-and-namespace.md`, `references/readiness-and-enablement.md`, `references/sync-management-app-install-backbone.md`, `references/verify-and-smoke.md`.**
+
+| Sub-act | Requirement | Transport | Note |
+|---|---|---|---|
+| A1.1 | Verify sync metadata present + resolve namespace (hard prereq) | `core` | **The namespace gate is the only hard stop here** (Tooling `InstalledSubscriberPackage` → else `Organization.NamespacePrefix`). No license read (install isn't license-gated) and **no permission-set-existence check** (perm-set names can be renamed/folded). |
+| A1.2 | Enable Retail Execution | `core` | Read+write via `RetailExecutionSettings` (dispatcher, 5 prefs) or MDAPI `Settings:RetailExecution` (3 booleans). Only *advanced*-RE hits the pilot GA gate (no API); base toggle is unaffected. |
+| A1.3 | Install the sync config (baseline root + sub-configs), with confirmation | `Sync Management App` | `SyncConfigInstallEndpoint` `/v1/syncconfig/install`: GET `discoverConfigs`, POST `installConfig`. Baselines discovered at runtime — never hardcoded. **The install *is* the config.** Never hand-roll via raw inserts. |
+| A1.4 | Verify referenced field-set definitions exist per tracked object | `core` (read-only describe) | Names installed by the CSV; definitions (e.g. `RetailMobilityRelevant`) provisioned by RE, not the package. Missing set → report-and-stop, owner = RE provisioning. |
+| A2.1 | Verify target user exists | `core` | `User` SOQL via `execute_api`. |
+| A2.2 | Confirm user's Mobility IOU membership | `core` read-only precondition (`Default_IOU` only) | Reads `InternalOrgUnitUser` (`IsDfltMobIntrOrgUnit = true`); never writes IOU membership. No row under `Default_IOU` → report-and-stop. Skipped under `Custom_User_Field`. |
+| A2.3 | Assign user to the installed config | `Sync Management App` / IOU-implicit → A2.2 | `SyncConfigAssignmentEndpoint` `/v1/syncconfig/assignment` (GET/POST/DELETE). **Not** `core`: a raw write corrupts the overloaded `Business_Area_Name__c`. |
+| A3.1 | List + verify activated config across the 4 objects | `Sync Management App` (list) + `core` (counts) | `SyncConfigListEndpoint` `/v1/syncconfig/configs`; all four `COUNT()`s in **one batched anon-Apex call** (not a per-object `sf data query` loop). **No `/v1/syncconfig/verify` — record counts ARE the verification.** |
+| A3.2 | Verify against baseline static-resource files | `core` | Compare installed per-object counts to the installed baseline's own declared counts, derived at runtime — never hardcoded. |
+
+## Act 1 of 3 — Setup Sync
+
+> Readiness gates **before** the install, a cheap **landing check after** it — the full per-object verification is Act 3's, not repeated here. Installing the baseline is the middle sub-step, not the whole act.
+
+1. **A1.1 — Verify sync metadata present, resolve namespace.** `core`. Confirm the sync objects exist and resolve `ns_prefix` (package via Tooling `InstalledSubscriberPackage`, else `Organization.NamespacePrefix`). **Hard miss (stop) only when NEITHER resolves.** Installing the package is not license-gated, so there is no license read here — and **do not verify any permission set by name** (perm-set names can be renamed/folded). The real Act-1 readiness gates are exactly two: metadata-present (this step) and RE-enabled (A1.2).
+2. **A1.2 — Enable Retail Execution.** `core` read + `core` write. Read via `RetailExecutionSettings` (dispatcher) or MDAPI `Settings:RetailExecution`; enable via the dispatcher's PATCH setters or `sf project deploy start --metadata "Settings:RetailExecution"` (false→true, re-read to confirm). RE-enabling implies base provisioning. The advanced-pilot toggle (`orgHasAdvncdRetailExecutionPilot`) has no API and gates only *advanced* RE.
+3. **A1.3 — Install the sync configuration into the four objects.** `Sync Management App`. GET `discoverConfigs` (runtime discovery — no config named "Standard"), then **POST only on the admin's explicit OK** after presenting the chosen baseline and its manifest-derived per-object counts. Sub-configs = child baselines; `parentConfigId` comes from the manifest, enforcing parent-before-child. Never hand-roll via raw sObject inserts. On `SUCCESS`, confirm landing with the cheap **aggregate** check only — one **batched anon-Apex call** for all four `core` COUNT()s (never a per-object `sf data query` loop; cold-starts blow the timeout), sum == `InstallResponse.recordsInserted`, no manifest fetch — **not** Act 3's per-object comparison.
+4. **A1.4 — Verify the referenced field-set definitions exist.** `core` read-only describe — **not a deploy.** The sync query-field path throws on a missing set (hard fail at first sync), so verify per tracked object; any missing → report-and-stop, owner = RE provisioning.
+
+**Act 1 end state:** package present (gate passed) and RE-enabled (or the miss reported and run halted); the admin-confirmed baseline installed across the four objects after explicit confirmation (`installed_config_id`/`installed_version` captured), landing confirmed by the aggregate `COUNT()==recordsInserted` check (the per-object baseline verification is Act 3's); referenced field-set definitions verified present. Full detail: `references/act1-setup-sync.md`.
+
+## Act 2 of 3 — Assign Users to the Sync Configuration
+
+> Runs after Act 1 (binds a user to the config Act 1 installed). Detect the config root's resolution strategy before choosing the A2.3 transport.
+
+1. **A2.1 — Verify the target user exists.** `core`. `User` SOQL via `execute_api`.
+2. **A2.2 — Confirm the user's Mobility IOU membership.** `core` read-only precondition, **`Default_IOU` only.** Read the default mobility IOU (`IsDfltMobIntrOrgUnit = true`); carry `iouId` into A2.3, or **report-and-stop if none** (the skill does not create IOU membership). **Skip entirely under `Custom_User_Field`** — do not generalize into a blanket "no IOU ⇒ stop."
+3. **A2.3 — Assign the user to the config.** `Sync Management App` (mapping row) / `core` (IOU-implicit). An assignment binds a User (`005`), Role (`00E`), OR Profile (`00e`); a Role/Profile row binds a whole cohort. Pick the config via `GET /v1/syncconfig/configs`, resolve name→Id, and scope by strategy (`Default_IOU` → `iouId`; `Custom_User_Field` → `businessArea` picklist). POST to `/v1/syncconfig/assignment`, then GET read-back — confirm the returned short canonical `clientAppId`. Re-assignment is an **upsert**: GET first; a duplicate `(configPath, businessArea, mappedRecordId)` triple is rejected; move a binding = DELETE the old row then POST. **Never write `Sync_Client_App_Profile_Mapping__c` raw** — the endpoint must derive the overloaded `Business_Area_Name__c`.
+
+**Act 2 end state:** target user confirmed; under `Default_IOU`, default mobility IOU confirmed (or reported-and-stopped); the user bound to the installed config, verified by read-back. Full detail: `references/act2-assign-users.md`.
+
+## Act 3 of 3 — Plan & Verify
+
+> The final act — the **authoritative** verification (Act 1 ran only a cheap aggregate landing check; the per-object comparison happens here, once). For an unqualified setup you must reach this act's end state — do not stop after the install.
+
+1. **A3.1 — List + verify the activated config across the four objects.** `Sync Management App` (list) + `core` (counts). List deployed configs + strategy via `GET /v1/syncconfig/configs` (a `core` SOQL list is an equivalent fallback). Get all counts via **one batched anon-Apex `COUNT()` call** across the four sync objects + `Sync_Config_State__c` (custom settings) — not a per-object `sf data query` loop (cold-starts blow the timeout). **No `/v1/syncconfig/verify` — record counts ARE the verification.**
+2. **A3.2 — Verify against the baseline static-resource files.** `core`. Compare installed **per-object** counts to the installed baseline's own declared counts, derived at runtime (identify the baseline from the activated config / version captured in A1.3) — this per-object split is A3.2's job (the aggregate total was Act 1's landing check); it catches a right-total / wrong-distribution install. **Do not hardcode counts** — they vary by baseline.
+
+**Act 3 end state:** the activated config listed via `/v1/syncconfig/configs` and verified across the four objects (+ state) through `core` SOQL record counts, each matched against the baseline's own declared count. Full detail: `references/act3-plan-verify.md`.
+
+## Definition of done (the whole skill)
+
+An unqualified CG Cloud mobile sync setup is **complete only when all three Acts reach their end states**, with any step the skill couldn't complete explicitly reported and attributed to who provides the missing piece: Act 1 (org ready; admin-confirmed baseline installed; field-set definitions verified — or missing set reported-and-stopped) → Act 2 (user exists; under `Default_IOU` the default mobility IOU confirmed — or reported-and-stopped; config bound) → Act 3 (activated config listed + verified against baseline files via `core` SOQL counts). **Reporting "done" after only the install (A1.3) is a defect.** Close with an explicit list of what remains and who provides each missing piece.
+
+## Out of scope / deferred
+
+Reported to set expectations, not reasons to halt the Act sequence:
+
+- Removal / GA-gating of the `orgHasAdvncdRetailExecutionPilot` admission toggle — CG Cloud core (Retail Execution); no API anywhere (A1.2).
+- Authoring **new/custom** baselines beyond those shipped (discovered at runtime) — manual ZIP (manifest + CSV) authoring outside this skill.
+- **Creating** Mobility IOU membership (A2.2) — a CG Cloud core / RE task; the skill only reads it.
+
+## Companion references
+
+- `references/act1-setup-sync.md`, `references/act2-assign-users.md`, `references/act3-plan-verify.md` — standalone per-Act breakdowns.
+- `references/transports-and-namespace.md` — the transport & namespace rules and the `sf` CLI cookbook.
+- `references/readiness-and-enablement.md` — the namespace gate & RE-enablement detail.
+- `references/sync-management-app-install-backbone.md` — the Sync Management App install backbone.
+- `references/verify-and-smoke.md` — the verify & smoke-test patterns.
+- `examples/scenarios.md` — worked validation scenarios (correct vs. anti-pattern runs).