@salesforce/afv-skills 1.55.0 → 1.56.0

package/skills/consumer-goods-sync-management-configure/examples/scenarios.md

@@ -0,0 +1,294 @@
+# Validation Scenarios — `consumer-goods-sync-management-configure`
+
+Behavioral checks for the skill. Each scenario is a user utterance + the correct routing and
+outcome, with special attention to the **honesty contract**: steps no transport can complete must
+be reported (not faked), and the transport for every step must be correct (`core` /
+`Sync Management App`). Each check below is labeled **Pass** (a behavior the agent must exhibit) or **Fail** (an anti-pattern it must avoid); the scenario passes when the agent does all the **Pass** behaviors and none of the **Fail** ones.
+
+---
+
+## 1. Full end-to-end setup (the steel thread)
+
+**Utterance:** "Set up CG Cloud mobile sync for this org."
+
+- **Pass:** Routes through **all three Acts** in order (Setup → Assign → Plan & Verify); does not stop
+  after the install and call it done.
+- **Pass:** Writes the mandatory pre-write plan first (per orchestrator).
+- **Pass:** Resolves the namespace prefix at runtime before any package-object reference.
+- **Pass:** Reaches Act 3 end state or reports exactly which step blocked and why.
+- **Fail:** Does **not** report "sync is set up" when only Act 1 ran.
+
+## 2. Install only (A1.3 headless install)
+
+**Utterance:** "Install the RE sync baseline into this org."
+
+- **Pass:** **Posts the mandatory pre-write plan before the `installConfig` POST** (per orchestrator
+  §"Mandatory pre-write plan"): lists all three acts, marks Act 1 A1.3 as the only step it will run,
+  and **quotes the exact narrowing words** ("Install the RE sync baseline") that justify skipping
+  Acts 2–3 and the other Act-1 sub-acts (readiness A1.1/A1.2 still gate the install; field sets not
+  requested → reported not-done), and confirms the target org + resolved namespace prefix. Does
+  **not** jump straight to the POST without it.
+- **Pass:** Uses the `/v1/syncconfig/install` endpoint (`SyncConfigInstallEndpoint`): **GET
+  `discoverConfigs`** to find the baseline (picks the Retail Execution baseline — its exact `staticResourceName`
+  comes from `discoverConfigs` at runtime, never hardcoded — verifying it's
+  `AVAILABLE`), then **POST `installConfig`** with `{"req":{"staticResourceName":"..."}}`, then
+  confirms landing with the cheap **aggregate** check — the sum of the four `core` COUNT()s (read in
+  **one batched anon-Apex call**, not a per-object `sf data query` loop) ==
+  `InstallResponse.recordsInserted` (no manifest fetch) — or a re-GET showing `ALREADY_INSTALLED`.
+  Because the ask was narrowed to the install (Act 3 not run), it **says plainly that the fuller
+  per-object verification against the baseline manifest — Act 3's A3.1/A3.2 — was not performed**,
+  rather than running that per-object comparison here.
+- **Pass:** Treats the install as `Sync Management App` via `SyncConfigInstallEndpoint`.
+- **Fail:** Does **not** tag the step `Sync Management App` on the basis of a `public` (namespace-private)
+  Apex method, and does **not** claim the install succeeded without a `core` SOQL read-back of the four objects.
+- **Pass:** On a `FAILED` `InstallResponse` (or a thrown call), **reports `errorMessage` and stops** — no
+  read-back, no field sets, no Act 2; treats a `FAILED` body inside an HTTP 200 as a failure, not
+  success.
+- **Fail:** Does **not** hand-insert `Sync_Config__c` rows via raw `sobjects` POST to fake the install
+  (that skips the ZIP orchestration, `$$NS` macro, ordering, and state rows) — including as a
+  "recovery" after a `FAILED` response.
+- **Fail:** Does **not** pass a `parentConfigId` argument to the POST — there is none; parent linkage
+  comes from the baseline manifest (a child reads `REQUIRES_PARENT` from GET until its parent is
+  installed).
+
+## 3. Namespace / metadata-present gate (A1.1 — `core`, the hard prerequisite)
+
+**Utterance:** "Set up sync" / "Check that this org is ready for sync."
+
+- **Pass:** **Verifies the Sync Management App metadata is present and resolves its namespace FIRST**,
+  before the RE-enablement check (A1.2), via the **Tooling API** (`GET /tooling/query?q=... FROM
+  InstalledSubscriberPackage`, matching the Sync Management App package by `SubscriberPackage.Name`
+  client-side — the object has no server-side `WHERE` — then reading `NamespacePrefix` off the
+  matched row rather than assuming a fixed value). Uses the match to resolve **both** the namespace
+  prefix and the **installed version**.
+- **Pass:** Prefers Tooling over the package's own `GET /v1/managedpackage` for the absence check
+  (that route is served by the package, so it **404s when the package is missing** and can't report
+  absence); may use `/v1/managedpackage` only as a confirming call once Tooling says present.
+- **Pass:** **Resolves the namespace from either source — package OR org.** On **no matching package
+  row**, does **not** immediately stop; **falls back to the org's own namespace** (`SELECT
+  NamespacePrefix FROM Organization`, `core`) and, if non-null, confirms by resolving
+  `<orgNs>Sync_Config__c` — the source-deployed DE/packaging-org case (e.g. an org whose
+  `Organization.NamespacePrefix` is set and whose `InstalledSubscriberPackage` is empty). Treats
+  that org prefix as `ns_prefix` and proceeds.
+- **Pass:** **Hard miss (STOP and report) only when NEITHER source resolves** — no package row **and** no
+  org namespace (or `<orgNs>Sync_Config__c` doesn't describe) **and** no bare unmanaged
+  `Sync_Config__c`. Reports "Sync Management App metadata not present"; does **not** fall through to
+  the RE-enablement check (A1.2), and does **not** attempt to install/deploy it (org setup, out of scope).
+- **Fail:** Does **not** treat an empty `InstalledSubscriberPackage` as an automatic hard miss without
+  first checking the org namespace (that false-negatives a source-deployed org where the sync
+  objects exist under `Organization.NamespacePrefix`).
+- **Pass:** Runs **no** license query here — installing and using the Sync Management App is **not**
+  license-gated (there is no license or SKU to detect, and install is not entitlement-gated).
+  A1.1's only hard gate is **metadata-present + namespace-resolved**; the next Act-1 gate is
+  **RE-enabled** (A1.2), an org preference rather than a license.
+- **Fail:** Does **not** probe for a license or "base entitlement", nor declare a license `accessCheck` —
+  there is no such entitlement to detect, so doing so would false-block a fully-capable org.
+- **Fail:** Does **not** verify a named **permission set** (e.g. `Sync_Admin`) exists as a readiness gate —
+  perm-set names can be renamed or folded into another set across orgs/releases, so a name-based
+  existence check would false-block a capable org. Readiness is exactly two gates: metadata-present
+  (this scenario) and RE-enabled (A1.2).
+
+## 4. Enable Retail Execution (A1.2 — `core` write)
+
+**Utterance:** "Enable Retail Execution and finish sync setup."
+
+- **Pass:** **Posts the mandatory pre-write plan before the RE-enable write.** "…finish sync setup" is
+  **not** a narrowing qualifier — the plan treats this as the full three-act journey (no acts
+  skipped on the strength of these words), names the target org + resolved namespace, and states it
+  starts at A1.1 readiness, not at the A1.2 write. Does **not** enable RE before stating the plan.
+- **Pass:** **Reads first, via whichever transport is present** — dispatcher
+  `getRetailExecutionEnableSetting` (5 prefs + 4 echo flags) or MDAPI `Settings:RetailExecution`
+  (3 booleans). Does not claim "5 sub-prefs" when it only read 3 via CLI.
+- **Pass:** **Enables via the transport that fits:** dispatcher present → PATCH the `RetailExecutionSettings` route
+  (5 *separate* setters, not one combined call); dispatcher-absent (`sf` CLI) → deploy
+  `settings/RetailExecution.settings` (member `RetailExecution`) via
+  `sf project deploy start --metadata "Settings:RetailExecution"`. **Dry-runs first, then re-reads
+  after the write** (false→true, deploy `changed:true`, read-back true).
+- **Pass:** **Re-reads for dependent-default side effects** — enabling `enableRetailExecution` can auto-set
+  `enableVisitSharing` even though the deploy file didn't carry it; the agent reports
+  the actual post-write state, not the file it deployed.
+- **Pass:** Treats `RetailExecution.orgHasAdvncdRetailExecutionPilot` as **out of reach** for
+  *advanced*-RE only (no read/write API; a CG Cloud platform / RE concern) — and
+  does **not** let it block base enablement, which is `core` and works today.
+- **Fail:** Does **not** report RE-enablement as **across-the-board unavailable**
+  (the base write is proven `core`), and does **not** claim RE is enabled without a read-back.
+
+## 5. Field sets per tracked object (A1.4 — names via CSV, definitions RE-provisioned, verified `core`)
+
+**Utterance:** "Make sure the sync config has all its field sets."
+
+- **Pass:** Distinguishes **names** (the `Fieldset_Name_List__c` / `List_Header_Fieldset__c` columns
+  are populated by the baseline CSV once the install runs) from **definitions** (the `FieldSet`
+  metadata on the referenced objects — **not** shipped in the package, and by packaging rules a
+  managed package can't ship a FieldSet onto a standard object it doesn't own).
+- **Pass:** Knows the definitions are **provisioned by Retail Execution** (A1.2), **not** deployed by this
+  skill — so A1.4 is a **read-only `core` describe that VERIFIES**, not a deploy. For each distinct
+  referenced set (chiefly `RetailMobilityRelevant`), describes the object's `fieldSets`
+  (`Schema...fieldSets.getMap()` or Tooling `FROM FieldSet`) and asserts it's present.
+- **Pass:** Compares **case-insensitively on the bare local name**, namespace-agnostic — builds the
+  present-set from `FieldSet.getName().toLowerCase()` (or Tooling `DeveloperName`) and strips any
+  `<prefix>__` off the referenced name before diffing. Handles the set being **org-namespaced**
+  (`<ns>__retailmobilityrelevant` in a source-deployed org) **or** unprefixed (RE-provisioned
+  standard set in a subscriber org) — the same check passes for both.
+- **Pass:** On a **missing** set, **reports and stops that object**, naming the object + absent set and the
+  owner (**RE provisioning / core-RE**) — and knows *why* it matters: the sync query-field path
+  (`TrackedObjectUtils` → `SYNC_MetaDataUtils`) **throws** a `SYNCException` on a missing set (a hard
+  failure at **first sync**, not at install).
+- **Fail:** Does **not** call `fieldSets.getMap().containsKey('RetailMobilityRelevant')` with the raw
+  referenced name — the map keys are **all-lowercase and namespace-qualified**, so an original-case or
+  bare lookup returns a **false "missing"** for a set that exists. Nor does it assert a fixed
+  namespace prefix, nor run an **unfiltered** Tooling `FROM FieldSet` (which returns zero rows — the
+  `WHERE EntityDefinition.QualifiedApiName` filter is mandatory).
+- **Fail:** Does **not** deploy `RetailMobilityRelevant` (or any referenced set) as a `FieldSet`-metadata
+  workaround — RE owns it; a hand-deployed set risks drifting from what RE and the baseline expect.
+  A missing set is escalated to RE provisioning, not papered over with a deploy.
+- **Fail:** Does **not** treat "config with defaults" as a separate deficiency or a separate create-config step —
+  the installed baseline root config's values come fully-enumerated from the baseline CSVs (no
+  schema-default problem). The install *is* the config; there is no config named "Standard."
+
+## 6. Verify user exists (A2.1 core)
+
+**Utterance:** "Assign Jordan Lee to sync." (start of Act 2)
+
+- **Pass:** First runs a `core` User SOQL (`SELECT Id, IsActive, Profile.Name FROM User WHERE ...`)
+  as a `purpose: validate` pre-flight.
+- **Pass:** If the user is missing/inactive, stops and reports — does not assign into a phantom.
+
+## 7. IOU membership precondition (A2.2 — `core` read-only, Default_IOU only)
+
+**Utterance:** "Assign Jordan Lee to sync." (the IOU precondition, reached under `Default_IOU`)
+
+- **Pass:** Treats A2.2 as a **`core` read-only precondition**, not a write — and only under
+  `Default_IOU`. Under `Custom_User_Field` (the default strategy) the binding comes from a
+  `Sync_Client_App_Profile_Mapping__c` row with no IOU, so **A2.2 is skipped entirely**.
+- **Pass:** **A missing default mobility IOU stops the Act ONLY under `Default_IOU`.** Under
+  `Custom_User_Field`, a user with no IOU is **not** blocked — the mapping row binds them with the
+  all-scope default (`businessArea` = `'All'`, the all-areas value). The report-and-stop is scoped to
+  `Default_IOU`, where the IOU *is* the binding and its absence leaves nothing to bind.
+- **Fail:** Does **not** generalize the `Default_IOU` "no IOU ⇒ stop" into a blanket rule that also halts a
+  `Custom_User_Field` assignment for a user who happens to lack an IOU.
+- **Pass:** Under `Default_IOU`, **reads** the user's default mobility IOU with the exact query
+  `ClientAppMapperService.getDefaultIouId()` uses — `SELECT InternalOrganizationUnitId FROM
+  InternalOrgUnitUser WHERE UserId = :userId AND IsDfltMobIntrOrgUnit = true LIMIT 1`. A row →
+  carries the `InternalOrganizationUnitId` forward as the `iouId` scope for A2.3 and proceeds.
+- **Pass:** If the read returns **no row** — the user has no default mobility IOU — **reports and stops**:
+  no further steps, names the owner (CG Cloud **core / RE** provisions IOU membership outside this
+  flow), and does **not** proceed to A2.3.
+- **Pass:** In a **pure managed-package org** the query throws `QueryException` (the object is absent);
+  degrades to the MP path (`null`) exactly as `ClientAppMapperService` does, rather than
+  hard-failing.
+- **Fail:** Does **not** attempt to **create** IOU membership — no `POST /sobjects/InternalOrgUnitUser`,
+  no Sync Management App Apex. The absence of a default mobility IOU is a
+  report-and-stop precondition, not a missing capability. Creating IOU membership is a CG Cloud
+  core / RE task outside this flow.
+
+## 8. Resolution-strategy coupling (A2.2 ↔ A2.3)
+
+**Utterance:** "Bind Jordan to the RE sync configuration."
+
+- **Pass:** **Posts the mandatory pre-write plan before the assignment POST.** Lists all three acts, marks
+  this as an Act 2 / A2.3-only run, and **quotes the narrowing words** ("Bind Jordan to the RE sync
+  configuration") that justify skipping Act 1 and Act 3, confirming the target org + resolved
+  namespace. Does **not** write the mapping row before stating the plan. (The strategy read and
+  config/target elicitation below happen *within* that planned scope.)
+- **Pass:** Reads `Business_Area_Resolution_Strategy__c` **first** — via `GET /v1/syncconfig/configs`
+  (`SyncConfigListEndpoint`, which returns each deployed config's `resolutionStrategy`) — because
+  the strategy decides whether A2.2 is even on the critical path.
+- **Pass:** **Elicits the config and target correctly:** confirms the named config is in the `/configs`
+  list (or lists deployed `name`s for the admin to pick if none was given, stopping if a named
+  config isn't deployed); asks whether the mapping is by Profile/Role/User; and **resolves the
+  profile/role name (or user) to its `00e`/`00E`/`005` Id via a `core` SOQL** before the POST —
+  never passes a raw name as `mappedRecordId`. On the User path, **stops if the user isn't in the
+  org** rather than binding a phantom, and (under `Default_IOU`) fetches the IOU from
+  `InternalOrgUnitUser` (`IsDfltMobIntrOrgUnit = true`).
+- **Pass:** Under **`Custom_User_Field`** (the default), binds via a `Sync_Client_App_Profile_Mapping__c`
+  **Role/Profile/User** row through `POST /v1/syncconfig/assignment` (`SyncConfigAssignmentEndpoint`)
+  + read-back — **with no IOU**, and **skips the A2.2 precondition** (it does not apply here). Passes
+  the config's **`name`** (or `clientAppId`) from `/configs` as `configPath` — the endpoint
+  normalises either to the canonical `clientAppId` before storing, so the row is keyed the way the
+  admin Assignments page and the runtime resolver expect (a config `name` like `<AppId>__Default` →
+  stored short `clientAppId` `<AppId>`); **verifies the read-back's `clientAppId` is the short
+  canonical value**, since a row stored
+  under the Name would be invisible on the admin page and unresolvable at runtime. May bind a
+  **Role (`00E`)** or **Profile (`00e`)** to cover a whole cohort in one write.
+- **Pass:** Under **`Default_IOU`**, treats the IOU (the A2.2 precondition read) **as** the binding — no
+  separate mapping row. If the A2.2 read finds **no** default mobility IOU, the Act has already
+  **reported and stopped** at A2.2, so A2.3 is never reached (a Role/Profile row won't rescue an
+  IOU-less user, since that root isn't evaluated for them); the skill does **not** create the IOU
+  to unblock it.
+- **Fail:** Does **not** write the mapping row raw via `POST /sobjects/<ns>Sync_Client_App_Profile_Mapping__c`
+  (that corrupts the overloaded `Business_Area_Name__c` — IOU Id vs Business Area picklist per
+  strategy — and skips the dedup + unique-Name convention the service enforces).
+- **Fail:** Does not write a mapping row that a `Default_IOU` strategy will ignore; does not report
+  A2.3 done when the A2.2 precondition already reported-and-stopped (no default mobility IOU under
+  `Default_IOU`); and does **not** wrongly run or block on the A2.2 IOU precondition when the
+  strategy is `Custom_User_Field` (where it does not apply).
+- **Fail:** Does **not** pass a profile/role **name** (or a username) as `mappedRecordId` — the endpoint
+  requires a resolved `00e`/`00E`/`005` **Id** — and does **not** stuff an IOU Id into
+  `businessArea` under `Custom_User_Field` (the IOU field is `iouId`, only under `Default_IOU`); if
+  the admin asks for an IOU under `Custom_User_Field`, surfaces the strategy mismatch instead.
+- **Pass:** **Uses the endpoint, never a raw write:** the assignment + configs endpoints are the only
+  safe A2.3 path and the skill does **not** fall back to a raw
+  `Sync_Client_App_Profile_Mapping__c` write.
+- **Pass:** On an assignment POST that **fails** (failure status or a thrown call — e.g. an unresolvable
+  `configPath`, which the endpoint now hard-rejects rather than silently defaulting the strategy),
+  **reports the error and stops**: no read-back, no further processing, and no raw-write "recovery."
+  A failure body inside an HTTP 200 is treated as a failure, not success.
+
+## 9. List & verify activated config (A3.1)
+
+**Utterance:** "Show me the activated sync configuration."
+
+- **Pass:** **Lists the deployed configs via the `Sync Management App` endpoint** — `GET /v1/syncconfig/configs`
+  (`SyncConfigListEndpoint`) returns every deployed `Sync_Config__c` as
+  `{name, clientAppId, resolutionStrategy}` in one package-blessed call (a `core` SOQL list is an
+  equivalent fallback for this read). The *list* half of A3.1 is closed.
+- **Pass:** Gets counts + keys across the four objects + `Sync_Config_State__c` in **one batched
+  anonymous-Apex `COUNT()` call** (the objects are custom settings) — **not** a per-object
+  `sf data query` loop, whose ~15–20s cold-starts blow the 2-min timeout — ending with an `assert:`
+  verify step. Parses the debug log by grepping `USER_DEBUG` first (the block is echoed as
+  `Execute Anonymous:` source). Verification is **not** blocked.
+- **Pass:** Does **not** rely on `SyncConfigOrchestrator.buildStateMap()` (it's `public`/namespace-private
+  — unreachable from a subscriber org).
+- **Pass:** **Proposes NO new Sync Management App endpoint for verification** — record counts via `core` SOQL are the
+  intended method, so it does **not** suggest, wait on, or block on a `/v1/syncconfig/verify`
+  endpoint. Act 3 adds no calls to the package.
+
+## 10. Verify against the baseline files (A3.2)
+
+**Utterance:** "Verify the installed sync config matches the baseline."
+
+- **Pass:** Runs the **baseline count check** — compares installed per-object counts (`core` COUNT()
+  reads) to the **installed baseline's own declared counts, derived at runtime from that baseline's
+  manifest/CSVs (never hardcoded literals)** — and reports pass/fail per object.
+- **Pass:** **Verification is record counts only:** does **not** issue a representative `/v1/*` device call
+  as part of verification, and does **not** add or propose any Sync Management App endpoint for it.
+- **Pass:** **Says exactly what was verified** — reports a green count check as proof the *server side*
+  installed the baseline's artefacts, nothing more.
+- **Fail:** Does **not** assert against a hardcoded literal count instead of the installed baseline's
+  declared value.
+
+---
+
+## Cross-cutting checks (apply to every scenario)
+
+- **Transport tag present:** every step the agent takes is explicitly `core` or
+  `Sync Management App` — never untagged; and any step no transport can complete is reported
+  plainly with its owner named, never faked.
+- **No faking:** a rejected write / missing capability is reported with the owner named, never
+  papered over.
+- **Namespace resolved at runtime (from either source):** package objects use the discovered
+  `<ns>` prefix — resolved from the installed package (`InstalledSubscriberPackage`) **or**, when no
+  package is installed, the org's own namespace (`Organization.NamespacePrefix`); core objects carry
+  none.
+- **Read-back on writes:** every write ends with a verify (`assert:`) read.
+- **Pre-write plan before the FIRST write:** in any scenario that performs a write (enable RE,
+  install a baseline, create a mapping row), the agent posts the mandatory pre-write plan *before*
+  that first write, per orchestrator §"Mandatory pre-write plan": all three acts listed, which it
+  runs/skips/reports as unreachable, and — for every skip — **the exact narrowing words quoted** from the request
+  ("set up sync" / "…finish sync setup" are **not** narrowing → full journey), plus the confirmed
+  target org and resolved namespace. Applies to **#1, #2, #4, #8** (always write-bearing).
+  Read-only scenarios take no write, so this check does not apply to them: **#3** namespace/metadata-present gate, **#5**
+  field-set verify (A1.4 is a read-only describe — RE provisions the definitions, the skill does
+  not deploy them), **#6** user-exists, **#7** IOU precondition, **#9** list, **#10**
+  baseline count check.

package/skills/consumer-goods-sync-management-configure/references/act1-setup-sync.md

@@ -0,0 +1,333 @@
+# Act 1 of 3 — Setup Sync
+
+Part of the [`consumer-goods-sync-management-configure`](../SKILL.md) skill — the **first of three acts**.
+Runs first; nothing in Acts 2–3 should be attempted until this Act's end state is reached.
+After it, continue to [Act 2](act2-assign-users.md) → [Act 3](act3-plan-verify.md).
+
+**This Act both gates and writes.** It *validates* things external to the package (the sync
+metadata is present and its namespace resolves — from a package install **or** the org's own
+namespace — and Retail Execution enablement — you can only check these, and a hard miss on either
+halts the run),
+and it *performs writes* (install the admin-confirmed baseline; field-set definitions are
+provisioned by RE, so A1.4 only verifies them — no field-set deploy).
+Having only *validated readiness* does **not**
+mean Act 1 is done — you must complete the install + configuration writes and reach the end
+state below.
+
+**Read the transport contract first.** Every step here is `core` or `Sync Management App` (see the
+parent `SKILL.md` and `transports-and-namespace.md`). Where neither transport
+can complete a step, report what's needed and who provides it, then stop that step — never fake
+it. The exceptions that **halt** the run are the hard readiness misses in steps 1–2: the sync
+metadata absent (A1.1's gate — **neither** a managed-package install **nor** an org-namespaced/
+unmanaged deploy resolves), or RE cannot be enabled and isn't already on (A1.2).
+
+## What this Act does
+
+### 1. A1.1 — Verify the Sync metadata is present and resolve its namespace (hard gate) — `core`
+
+- **FIRST — verify the Sync Management App metadata is present in the org and resolve its
+  namespace. This is the hard prerequisite for the entire skill** — without the sync objects no
+  endpoint or namespace exists, so every downstream step is meaningless. The namespace has **two
+  possible sources** (see below): a **managed-package install** (`InstalledSubscriberPackage`) or
+  the **org's own registered namespace** (`Organization.NamespacePrefix`, for source-deployed
+  DE/packaging orgs). Start with the package check via the **Tooling API** (generic `core`, no
+  package code — so it answers even when the package is *absent*, which the package's own
+  `GET /v1/managedpackage` cannot, since that route 404s when the package isn't installed):
+  ```text
+  GET /services/data/vXX.0/tooling/query?q=
+      SELECT SubscriberPackage.Name, SubscriberPackage.NamespacePrefix,
+             SubscriberPackageVersion.MajorVersion, SubscriberPackageVersion.MinorVersion,
+             SubscriberPackageVersion.IsBeta
+      FROM InstalledSubscriberPackage
+  ```
+  `InstalledSubscriberPackage` does not support server-side `WHERE` filtering, so **query all rows
+  and match client-side** by `SubscriberPackage.Name` (the Sync Management App package), then
+  **read the matched row's `NamespacePrefix` off the result** rather than assuming a fixed value —
+  the org's installed package carries whichever prefix it was built with; that value (with a
+  trailing `__` appended) becomes `ns_prefix`. Transport: `sf data query --use-tooling-api`
+  when the CLI is present, else a plain REST `GET /services/data/vXX.0/tooling/query?q=<url-encoded SOQL>`
+  via `execute_api` / any session-token client — the CLI is only sugar over this.
+  - **A matched row confirms the package is installed** — and its `SubscriberPackageVersion`
+    resolves **two** things at once: (a) the namespace prefix to use for every later
+    package-object reference, and (b) the **installed version**, which you compare against the
+    release that carries the `/v1/syncconfig/*` endpoints (A1.3 install, A2.3 assignment,
+    A3.1-list) — an org on an older version won't have those routes even though the package is present.
+  - **The namespace can come from two sources — package OR org.** A match above is the
+    **package-install** case (a subscriber org). But the sync metadata can also be **source-deployed
+    into the org under the org's *own* registered namespace** (a DE / packaging / dev org), where
+    `InstalledSubscriberPackage` returns **no row at all** even though the objects are present. So an
+    empty `InstalledSubscriberPackage` is **not** an automatic hard miss.
+  - **No matched row → do NOT stop; fall back to the org namespace.** Read the org's own prefix
+    with a generic `core` query — `SELECT NamespacePrefix FROM Organization` — and if it is
+    non-null, treat that value (with the trailing `__`) as `ns_prefix`. **Confirm** by resolving one
+    known object under it (`GET /sobjects/<orgNs>Sync_Config__c/describe`, or `SELECT COUNT() FROM
+    <orgNs>Sync_Config__c`): a 200/successful describe means the sync objects live under the org
+    namespace and the run proceeds. (There is no `SubscriberPackageVersion` in this case — version
+    gating for the `/v1/syncconfig/*` endpoints doesn't apply to a source-deployed org; those
+    classes are either deployed or not, verified by probing the route.)
+  - **Hard miss = STOP only when NEITHER resolves.** If no `InstalledSubscriberPackage` row matches
+    **and** the org has no namespace (or `<orgNs>Sync_Config__c` doesn't describe) **and** the
+    object isn't present unmanaged (bare `Sync_Config__c`), then report "the Sync Management App
+    metadata is not present in this org (no managed package, no org-namespaced deploy)" and halt the
+    whole run — installing/deploying it is an org-setup prerequisite **outside this skill's scope**.
+    Do not fall through to the RE-enablement check (A1.2); it presupposes the sync objects exist.
+  - **Describe fallback (no Tooling access):** attempt `GET /sobjects/<ns>Sync_Config__c/describe`
+    across the candidate prefixes — the package's known namespace(s) **and** the org namespace from
+    `SELECT NamespacePrefix FROM Organization` (a `core` query, no Tooling), plus the bare
+    (unmanaged) name — a 200 confirms that prefix is the live one (but yields no version); a
+    `NOT_FOUND` = that prefix absent. `NOT_FOUND` on all probed = the metadata is absent. Prefer the
+    Tooling query when available — only it returns the installed *version* for the package case.
+- **No license read — installing and using the Sync Management App is not license-gated.**
+  There is no license or SKU to detect, and package install is not entitlement-gated. So A1.1 does
+  **not** run any license query and declares no license `accessCheck`: the Act-1 readiness gates are
+  **metadata-present** (the namespace gate above) and **RE-enabled** (A1.2 below). Retail Execution
+  is an org *preference*, not a license — enable it in A1.2 rather than probing for an entitlement
+  here.
+- **Do NOT verify the existence of any named permission set as a readiness gate.** Permission-set
+  names are unstable — they can be renamed or folded into another set with a different name across
+  releases and orgs — so a name-based existence check false-blocks a perfectly capable org. The
+  **only** two Act-1 prechecks are (1) the **Sync Management objects are present** (A1.1 above) and
+  (2) **Retail Execution is enabled** (A1.2 below). Access to the install/assignment endpoints is
+  granted by *some* permission set in the target org (its name is the admin's concern, not a fixed
+  value the skill asserts); if a call is denied for lack of access, report the access boundary and
+  who grants it — never gate readiness on a specific permission-set name.
+
+### 2. A1.2 — Enable Retail Execution — `core` read + `core` write
+
+- **Read** the current setting one of two ways — **the transport determines what you see:**
+  - **Headless-360 dispatcher present:** GET the CG Cloud core
+    `RetailExecutionSettings` node (`getRetailExecutionEnableSetting`) — returns **5 prefs**
+    (`isRetailExecutionEnablePrefEnable`, `isProductHierarchyPrefEnabled`,
+    `isVisitSharingPrefEnabled`, `isCGAgentsPrefEnabled`, `isCGGenAIPrefEnabled`) + 4 read-only
+    echo flags.
+  - **Dispatcher-absent (e.g. `sf` CLI):** retrieve `Settings:RetailExecution` via MDAPI
+    (`sf project retrieve start --metadata "Settings:RetailExecution"`). The Settings surface
+    exposes **3** booleans — `enableRetailExecution`, `enableProductHierarchy`,
+    `enableVisitSharing` — **not** the dispatcher's 5. Same underlying org pref
+    (`ORG_PREFERENCE_RETAIL_EXECUTION_ENABLED` via `PermAndPrefUtil.setOrgPref`, controller
+    `RetailExecutionEnableController`), different projection. If already enabled, record and move on.
+  - **CLI absent → plain REST via the Tooling API (no dispatcher needed):**
+    `RetailExecutionSettings` is a queryable Tooling *singleton* sObject. **Prefer the SOQL
+    projection — one call, returns the values directly:**
+    `GET /services/data/vXX.0/tooling/query?q=SELECT+IsRetailExecutionEnabled,IsProductHierarchyEnabled,IsVisitSharingEnabled+FROM+RetailExecutionSettings`.
+    It returns the fields under **Tooling names** — `IsRetailExecutionEnabled`,
+    `IsProductHierarchyEnabled`, `IsVisitSharingEnabled` (note: `Is…Enabled`, distinct again from
+    both the dispatcher's `is…PrefEnable(d)` and MDAPI's `enable…`). **Avoid the two-call
+    singleton GET** (`SELECT Id …` → `GET /tooling/sobjects/RetailExecutionSettings/<id>`) as the
+    primary read — the per-id `sobjects` fetch can return `UNKNOWN_EXCEPTION`; keep it only as a
+    fallback. This is the read to use when neither the `sf` CLI nor the Headless-360 dispatcher is
+    present.
+- **Enabling it is `core` and works today** on both transports below:
+  - **Dispatcher present:** PATCH the `RetailExecutionSettings` route
+    `.../retail-execution-settings/set-retail-execution-enable-setting` with `{enable:true}`.
+    There are **5 separate PATCH setters, not one combined call** — `set-retail-execution-enable-setting`,
+    `set-product-hierarchy-pref`, `set-visit-sharing-pref`, `set-cgagent-pref`, `set-cgcgen-aipref`,
+    each body `{enable:boolean}`. Guards: all need View Setup & Configuration;
+    `set-visit-sharing-pref` needs the Visit Share Pilot perm on `enable=true`; the two
+    CG-agent/GenAI setters are gated by `RetailExecution.userCanUseCGGenAI`.
+  - **Dispatcher-absent (`sf` CLI):** deploy a
+    `settings/RetailExecution.settings-meta.xml` (source) / `settings/RetailExecution.settings`
+    (MDAPI) whose member is named **`RetailExecution`** (the bare setting-type name — *not*
+    `RetailExecutionSettings.*`) carrying
+    `<enableRetailExecution>true</enableRetailExecution>`, then
+    `sf project deploy start --metadata "Settings:RetailExecution"`. This is a generic **`core`**
+    Metadata-API Settings deploy. Always dry-run first (`--dry-run`), then
+    re-read after the real write to confirm the value took.
+  - **CLI absent → plain REST via the Metadata deploy resource** (this is exactly what
+    `sf project deploy start` wraps): `POST /services/data/vXX.0/metadata/deployRequest` with a
+    base64-encoded zip (`package.xml` selecting `Settings:RetailExecution` +
+    `settings/RetailExecution.settings`) and `{"deployOptions":{"checkOnly":true}}` to dry-run,
+    then poll `GET /services/data/vXX.0/metadata/deployRequest/<id>` to completion; repeat with
+    `checkOnly:false` for the real write.
+    **Do NOT try a direct Tooling field PATCH** —
+    `PATCH /tooling/sobjects/RetailExecutionSettings/<id>` with `{"IsRetailExecutionEnabled":true}`
+    is **rejected** (`METADATA_FIELD_UPDATE_ERROR: Could not find a name resolver for Metadata`).
+    Settings sObjects are read-only to a direct Tooling PATCH; the write must go
+    through the Metadata deploy resource (or the dispatcher's PATCH setter). So: read is a clean
+    Tooling GET, but write is *always* the metadata-deploy path.
+- **Dependent-default side effect:** enabling `enableRetailExecution` also enables
+  `enableVisitSharing` as a dependent default (if it was absent/off before) — the platform applies
+  dependent sub-pref defaults on enable, even though the deploy file carried only the one field.
+  **Re-read after the write; don't assume the sub-prefs match exactly what you deployed.**
+- **A narrow exception: the advanced-pilot GA gate.**
+  `RetailExecution.orgHasAdvncdRetailExecutionPilot` has **no read/write API surface**
+  — it is a Core-source admission-gate expression on the setup tree, not an OrgPreference/PSL row.
+  But **base RE enablement does *not* require it** — RE enables cleanly without touching it; it
+  gates only *advanced* RE. When an advanced-RE feature needs it, report that it has no
+  automatable read/write path and that it's owned by the CG Cloud platform / Core setup tree, then
+  stop that step — do **not** let it block the base toggle, which is `core` and works today.
+- **On a hard miss** (RE cannot be enabled and isn't already on): halt — like A1.1, an install
+  into a non-RE org produces a config that can't sync.
+
+### 3. A1.3 — Install sync artefacts into the four objects — `Sync Management App`
+
+- **A headless install endpoint exists for this step.**
+  `SyncConfigInstallEndpoint` is a `global @RestResource(urlMapping='/v1/syncconfig/install/*')`
+  wrapper over the existing `SyncConfigInstall.installBaseline(...)` logic. It exposes:
+  - **POST `installConfig`** — install a baseline. Body `{"req":{"staticResourceName":"..."}}` →
+    `InstallResponse` (`status` SUCCESS/FAILED, `configId`, `version`, `recordsInserted`,
+    `errorMessage`). **The only argument is `staticResourceName`** — see the discovery step for how
+    to obtain a valid one.
+  - **GET `discoverConfigs`** — list installable baselines *before* POSTing, so you don't guess the
+    resource name. Returns `ConfigOption`s: `configId`, `displayName`, `parentConfigId`,
+    `staticResourceName` (the value to POST), `availability` (`AVAILABLE` / `ALREADY_INSTALLED` /
+    `REQUIRES_PARENT`), and `requiresLabel` (the blocking parent's configId when
+    `REQUIRES_PARENT`). Read-only.
+  - **On failure, report and STOP.** If the POST returns `status == FAILED` (or the call throws),
+    surface `errorMessage` to the admin and **halt this step — no verify, no field sets, no Act 2.**
+    A `FAILED` body inside an HTTP 200 is still a failure; never read it as success and never fall
+    back to a raw sObject insert to "recover." Only a `SUCCESS` response proceeds to the verify below.
+  - **Flow:** GET to discover → present the `AVAILABLE` baselines and **get the admin's explicit
+    confirmation of which one to install** (see the confirmation gate below) → POST the confirmed
+    baseline's `staticResourceName` to install → on `FAILED`, report `errorMessage` and stop → on
+    `SUCCESS`, **confirm the install landed — the cheap *aggregate* landing check only.** This is a
+    lightweight post-write gate, **not** Act 3's verification; do **not** run the per-object /
+    baseline-manifest comparison here (that is A3.1/A3.2's job — running it in Act 1 just re-does Act
+    3 a step early). Two reads, not one: a re-GET showing `ALREADY_INSTALLED` is a quick confirmation
+    that the state row was written, but it does **not** prove the artefacts landed. The landing check
+    is a single **aggregate** read-back: sum the four `core` COUNT()s (`Sync_Config__c`,
+    `Sync_Tracked_Object_Config__c`, `Sync_Named_Fetch_Tree_Nodes__c`, `Sync_Named_Query__c`) and
+    compare that sum to **`InstallResponse.recordsInserted`** — which equals the manifest's total row
+    count, so this needs **no** static-resource fetch and **no** manifest at all. **Read the four
+    counts with ONE batched anonymous-Apex call — do NOT loop `sf data query` per object** (each `sf`
+    cold-start is ~15–20s, so a per-object loop blows the 2-min timeout; and when you parse the
+    `sf apex run` output, **grep `USER_DEBUG` first** — the block is echoed as `Execute Anonymous:`
+    source, so a bare marker grep matches twice; see the batched form in
+    [transports-and-namespace.md](transports-and-namespace.md)). Capture
+    `recordsInserted` + `version` from the `InstallResponse` into session state for Act 3 to reuse.
+    **Run this aggregate landing check even for a narrow install-only ask** (where Act 3 may not
+    otherwise run), so an install is never reported successful on a bare `SUCCESS`/state-row flip
+    without confirming the rows inserted — and if the caller needs the per-object split for an
+    install-only ask, say plainly that the fuller Act-3 verification (per-object counts vs the
+    baseline manifest) was not run.
+  - **Confirmation gate (mandatory, skill-side).** The install is a write, so **never POST without
+    the admin's explicit OK.** Before installing, present what will be written: the chosen baseline
+    (there is **no** config named "Standard" — the installable baselines are **discovered at runtime
+    via `discoverConfigs`, never hardcoded**; Act 1 targets the **Retail Execution** baseline, whose
+    exact `staticResourceName` comes from `discoverConfigs`), its per-object counts (read from the
+    selected baseline's own manifest/CSVs at runtime — **never hardcoded**), and any additional
+    sub-configs the admin also wants. Install only the confirmed set. **Sub-configs are just more
+    baselines** installed through the same POST, each behind its own confirmation; parent-before-child
+    ordering is enforced by the manifest's `parentConfigId` (a child shows `REQUIRES_PARENT` until its
+    parent is installed) — not by a caller-supplied param.
+- **Verify by re-GET after install** (GET → POST install of the discovered Retail Execution baseline → SUCCESS;
+  re-GET shows `ALREADY_INSTALLED`). The endpoint's package-release rollout is a separate
+  workstream from this skill.
+- **What the logic does:** reads the discovered baseline's static-resource ZIP
+  (`manifest.json` + CSVs) and inserts rows into all four objects: `Sync_Config__c`,
+  `Sync_Tracked_Object_Config__c`, `Sync_Named_Fetch_Tree_Nodes__c`, `Sync_Named_Query__c`
+  (namespace-agnostic via `SYNC_NamespaceHandler`; `$$NS` macro rewritten at install; per-config
+  `Sync_Config_State__c` version rows written). Guards: blocks a duplicate `configId`, blocks a
+  missing parent — **the parent linkage (`parentConfigId`) is read from the ZIP's `manifest.json`,
+  not passed as a param**; a re-run is a no-op.
+- **Do not hand-roll the install.** Do **not** substitute generic `core` sObject REST for the
+  endpoint: the baseline install is an *orchestration* (unzip → macro → ordered multi-object
+  insert → state bookkeeping) that hand-inserting rows via `POST /sobjects/<ns>...` would not
+  reproduce faithfully (it skips the state rows and ordering guarantees). Use the endpoint, or have
+  an admin run it via the VF page in a non-headless context.
+- **The installed root config carries its values from the CSVs — there is no separate "defaults" concern.**
+  The four sync objects are List custom settings, whose schema `<defaultValue>`s do **not** fire on
+  DML — but the baseline CSVs enumerate every value, so installing the baseline yields a
+  fully-populated root `Sync_Config__c` (plus any child/sub-configs). Creating the config is
+  therefore not a separate "create-with-defaults" step and needs no confirmation beyond the install
+  gate above; a bare hand-rolled insert, by contrast, would land an empty row.
+- Several baseline **editions** ship (e.g. a Consumer Goods edition, a Direct-Store-Delivery
+  edition, and a Retail Execution edition), each as its own static resource whose exact name is
+  returned by `discoverConfigs`; **enumerate them from the endpoint at runtime, never hardcode the
+  names** (the set expands across releases). Act 1 targets the **Retail Execution** edition — its
+  exact static-resource name comes from `discoverConfigs` at runtime. A custom baseline beyond the
+  shipped editions requires authoring the ZIP by hand — out of scope.
+
+### 4. A1.4 — Verify the referenced field-set definitions exist — `core` (read-only describe)
+
+- **Names — done by A1.3.** The `Fieldset_Name_List__c` and `List_Header_Fieldset__c` columns
+  on `Sync_Tracked_Object_Config__c` are populated by the same install CSV. No separate step.
+- **Definitions — provisioned by Retail Execution, not deployed by this skill.** The `FieldSet`
+  metadata those names reference (chiefly `RetailMobilityRelevant`, wired to ~60 baseline rows on
+  standard objects — Account, Contact, Event, Task, Product2, `InternalOrganizationUnit`, …) is
+  **not shipped by the package** (a managed package can't own a FieldSet on a standard object) and
+  is **not** a manual deploy in this flow either: **enabling Retail Execution (A1.2) provisions
+  it.** So A1.4 is **not** an install/deploy step — there is no field-set "upload." But because the
+  package only *consumes* field sets via Schema describe and the **sync query-field path throws**
+  when a named set is missing (`SYNC_MetaDataUtils.getFieldsForFieldSetByFieldSetMapOrThrowException`
+  → `SYNCException("We couldn't find the <name> field set …")`, exercised by
+  `TrackedObjectUtilsTest.getFieldsForTOOrThrowException_unknownfieldSet_exception`), a missing set
+  is a **hard failure at first sync, not at install** — so **verify, don't assume.**
+- **The verify (this is the read-back A1.4 was missing).** After the install, for each distinct
+  field-set name the installed baseline's `Sync_Tracked_Object_Config__c` rows reference
+  (`Fieldset_Name_List__c` + `List_Header_Fieldset__c`, split on `,`), confirm the set exists on the
+  object's schema — a **read-only `core` describe**, mirroring A1.2's post-write re-read:
+  - Per object, read the field-set map — `Schema.describeSObjects(new String[]{objName})[0]`
+    `.fieldSets.getMap()` via anonymous Apex (all describe variants — default options,
+    `SObjectDescribeOptions.FULL`, `Schema.getGlobalDescribe()`, and the static
+    `Schema.SObjectType.<obj>` reference — return the **same** field sets, verified on-org; the
+    default `describeSObjects` is fine), or a Tooling `GET /tooling/query?q=SELECT DeveloperName,
+    NamespacePrefix FROM FieldSet WHERE EntityDefinition.QualifiedApiName = '<obj>'`. The Tooling
+    **`WHERE EntityDefinition.QualifiedApiName` filter is mandatory** — an unfiltered `FROM FieldSet`
+    returns **zero rows** (reads as "no field sets" — a trap).
+  - **Compare on the BARE name, case-insensitively — do NOT `containsKey` the raw referenced name.**
+    `fieldSets.getMap()` keys are **all-lowercase and fully namespace-qualified** (`<ns>__name`), so
+    `getMap().containsKey('RetailMobilityRelevant')` returns **false even when the set exists** (the
+    real key is e.g. `<ns>__retailmobilityrelevant`) — the classic false-missing this step must
+    avoid. Build the present-set from `FieldSet.getName().toLowerCase()` (`getName()` is the bare
+    local name; `getNamespace()` is the prefix, separately), strip any `<prefix>__` off the referenced
+    name (`substringAfterLast('__')`), and compare lowercased. In Tooling, compare `DeveloperName`
+    case-insensitively.
+  - **Whether a set is prefixed depends on the ORG, not the `$$NS` macro.** The CSV names use `$$NS`
+    (`$$NSMobilityRelevant` → `<ns>__MobilityRelevant` at install). But `RetailMobilityRelevant`
+    (no `$$NS`) is **not** always unprefixed: in a pure **subscriber** org RE provisions it as
+    **standard** metadata (`NamespacePrefix` null), whereas in a **source-deployed / namespaced** org
+    (the `Organization.NamespacePrefix` branch A1.1 handles) **every** set — including
+    `RetailMobilityRelevant` — carries the **org namespace** (`getNamespace()` = `<ns>`, confirmed
+    on-org). Comparing on the bare, lowercased local name (above) is correct for **both** org types;
+    assuming a fixed prefix is not.
+  - **All present → report verified** (RE provisioned them; nothing to deploy). This is the
+    per-object `assert:` step A1.4 must end on, same convention as every other write's read-back.
+  - **Any missing → report and stop that object.** Name the object + the absent field set, and
+    state the owner: **Retail Execution provisioning (A1.2 / core-RE)**, not this skill and not the
+    package. Do **not** attempt to deploy the FieldSet as a workaround — RE owns it; a hand-deployed
+    set risks drifting from what RE and the baseline expect. If RE is enabled and the set is still
+    absent, that's an RE-provisioning issue to escalate to the CG Cloud platform / Retail Execution
+    owners, not a `FieldSet` this skill ships.
+
+## Act 1 end state
+
+- **Sync Management App metadata confirmed present and its namespace resolved** — either a
+  managed-package install (Tooling API `InstalledSubscriberPackage` match, **namespace prefix +
+  installed version captured** from the matched row) **or** the org's own namespace (`SELECT
+  NamespacePrefix FROM Organization`, confirmed by resolving `<orgNs>Sync_Config__c` — no version in
+  this case). On **neither** resolving, the run halted with "Sync Management App metadata not
+  present" (install/deploy is out of scope). This is A1.1's opening gate, ahead of RE enablement (A1.2).
+- A1.1/A1.2 readiness reported as an explicit Pass/Fail checklist; a hard miss halted the run.
+- Admin-confirmed baseline (the Retail Execution root config, plus any sub-configs the admin also confirmed)
+  **installed** across the four objects via the `/v1/syncconfig/install` endpoint (GET discover →
+  confirmation gate → POST install), with `installed_config_id` / `installed_version` captured from
+  the `InstallResponse` (never faked via raw sObject inserts). The install is the config: the root
+  `Sync_Config__c` and its values come fully-enumerated from the baseline CSVs — no separate
+  create-config step. Landing confirmed by the cheap **aggregate** check (sum of the four `core`
+  COUNT() reads == `InstallResponse.recordsInserted`) — **not** the per-object/baseline-manifest
+  comparison, which is Act 3's (A3.1/A3.2) and is deliberately not repeated here.
+- Field-set names present (from the baseline CSV); the referenced field-set **definitions
+  verified present** on each tracked object by a read-only `core` describe (RE provisions them via
+  A1.2) — or any missing set reported-and-stopped with the owner named (RE provisioning), not
+  deployed around.
+
+## Gotchas
+
+- **List-custom-setting defaults never auto-apply on DML.** This is why the baseline install (A1.3),
+  not a raw insert, is the only correct way to create the config — a package-wide constraint: don't
+  assume an inserted `Sync_Config__c` row has its declared defaults. The baseline CSVs carry every
+  value; a bare insert would not.
+- **A dispatcher-404 for RE enablement is not "capability missing" — it's a transport switch.**
+  On a dispatcher-absent org, fall back to MDAPI: read via `Settings:RetailExecution` retrieve
+  and **write via `sf project deploy start --metadata "Settings:RetailExecution"`**. Prefer the
+  MDAPI fallback over stopping the step — fall back, don't stop. Only *advanced*-RE (the
+  `orgHasAdvncdRetailExecutionPilot` gate) is truly un-writable.
+- **RE enable applies dependent-pref defaults.** Enabling `enableRetailExecution` can flip
+  sub-prefs you didn't set (for example, `enableVisitSharing` going true as a dependent default).
+  Always re-read after the write; report the post-write state, not the file you deployed.
+- **Namespace first.** Resolve the live prefix (A1.1's namespace gate — package or org namespace) before any package-object path;
+  `SyncConfigInstall` handles it internally, but any sObject-REST path you emit must use the
+  resolved prefix — never a hardcoded one.
+- **The install is idempotent by guard, not by luck** — a re-run against an installed
+  `configId` is a designed no-op; don't treat the guard message as an error.