@salesforce/afv-skills 1.55.0 → 1.56.0

package/skills/consumer-goods-sync-management-configure/references/sync-management-app-install-backbone.md

@@ -0,0 +1,159 @@
+# Reference — The Sync Management App Sync-Config Install Backbone
+
+Background for [Act 1](act1-setup-sync.md). The install *logic* here is the
+backbone of the whole steel thread. The logic lives in `public` (namespace-private) Apex with no
+`global`/REST entry point, so it isn't directly callable from a subscriber org. The package exposes
+it headlessly through `SyncConfigInstallEndpoint` (`@RestResource /v1/syncconfig/install`, GET
+discovery + POST install) — a thin `global` wrapper over `installBaseline` (see "The headless
+install endpoint" below). Understanding the underlying logic precisely still matters because it's
+the most important capability and everything in Act 1 either feeds this install or works around
+what it does *not* do.
+
+## The four sync objects (+ state)
+
+Installed/populated by the backbone; all are **List custom settings** (each prefixed by the
+runtime-resolved namespace — from the installed package or the org's own namespace, written `<ns>`
+below):
+
+| Object | Role |
+|--------|------|
+| `Sync_Config__c` | Root sync configuration (the installed baseline root — e.g. the Retail Execution baseline; there is no config literally named "Standard"). |
+| `Sync_Tracked_Object_Config__c` | Which objects sync + per-object settings. |
+| `Sync_Named_Fetch_Tree_Nodes__c` | Fetch-tree graph (parent/child fetch relationships). |
+| `Sync_Named_Query__c` | Named queries the client runs to fetch data. |
+| `Sync_Config_State__c` | Per-config **version** rows — how installed version is tracked. |
+
+**List custom settings ⇒ no auto-defaults on DML, but also ⇒ reachable via generic `core`
+sObject REST + SOQL.** Two consequences:
+- A raw `POST /sobjects/<ns>Sync_Config__c` inserts a bare row; the schema `<defaultValue>`s do
+  **not** fire. This is exactly why the baseline CSVs (not schema defaults) carry every value —
+  installing the baseline yields a fully-populated config; a hand-rolled insert would not.
+- Because they're custom settings, **generic `core` reads** (`GET /query?q=...`) reach them with
+  no package code — this is what makes A3.1 count/version *verification* doable **today**. But
+  **row-level *writes* are not all safe as raw `POST /sobjects/<ns>...`.** The
+  `Sync_Client_App_Profile_Mapping__c` assignment row (A2.3) carries the **overloaded**
+  `Business_Area_Name__c` field (an IOU Id under `Default_IOU`, a Business Area picklist value under
+  `Custom_User_Field`); a raw insert that doesn't derive it from the config's strategy silently
+  corrupts the row (and skips dedup + the unique-Name convention). That write must go through the
+  **`/v1/syncconfig/assignment` endpoint** (`SyncConfigAssignmentEndpoint`, A2.3), which wraps the
+  same service the VF page uses. What generic sObject REST also cannot do is run the baseline-ZIP
+  install orchestration (unzip, `$$NS` macro, ordered multi-object insert, state-row bookkeeping) —
+  that's the `public` logic that now has a `global` wrapper (`SyncConfigInstallEndpoint`, A1.3; see
+  below).
+
+### Field dictionary — the API names the skill's own reads/writes touch
+
+Casing matters and several fields are **not** named the obvious way — guessing costs a describe
+round-trip per miss. These are the exact API names (verified against the package object metadata)
+for the fields this skill queries or writes. All take the `<ns>` prefix at runtime; the names below
+are the unprefixed `__c` suffixes.
+
+| Object | Field(s) the skill uses | Purpose / gotcha |
+|--------|-------------------------|------------------|
+| `Sync_Config__c` | `ClientApp_ID__c`, `Business_Area_Resolution_Strategy__c`, `Business_Area_Mapping__c` | Config root. `ClientApp_ID__c` keys the config (the `clientAppId` the list/assignment endpoints return); `Business_Area_Resolution_Strategy__c` is `Default_IOU` vs `Custom_User_Field`. |
+| `Sync_Tracked_Object_Config__c` | `Object_Api_Name__c`, `Fieldset_Name_List__c`, `List_Header_Fieldset__c`, `ClientApp_ID__c` | Per-tracked-object. **It's `Object_Api_Name__c`** — not `Tracked_Object_API_Name__c`. `Fieldset_Name_List__c` + `List_Header_Fieldset__c` hold the A1.4 field-set names (comma-split). |
+| `Sync_Named_Fetch_Tree_Nodes__c` | `Object_Api_Name__c`, `Fetch_Tree_Name__c`, `Parent_Node_Id__c` | Fetch-tree graph; count-only for A3.x. |
+| `Sync_Named_Query__c` | `Bindable_Name__c`, `SOQL_Statement__c`, `Type__c` | Named queries; count-only for A3.x. |
+| `Sync_Config_State__c` | `Current_Version__c`, `Initial_Install_Version__c`, `Last_Upgrade_Date__c` | Installed version is **`Current_Version__c`** — there is **no** `Config_Id__c` on this object; rows are keyed by the custom-setting `Name`, not a config-id field. |
+| `Sync_Client_App_Profile_Mapping__c` | `Client_App_ID__c`, `Client_App_Profile__c`, `Mapped_Record_Id__c`, `Business_Area_Name__c` | The A2.3 assignment row (write via the endpoint, never raw). `Business_Area_Name__c` is the overloaded IOU-Id/Business-Area field. |
+
+**The client-app field is spelled two different ways across objects — do not conflate:**
+`Sync_Config__c` and `Sync_Tracked_Object_Config__c` use **`ClientApp_ID__c`** (no underscore
+between "Client" and "App"), while `Sync_Client_App_Profile_Mapping__c` uses
+**`Client_App_ID__c`** (underscore between every word). Both end `_ID__c` (uppercase `ID`).
+
+When in doubt, **describe the object before querying** rather than guessing a field name — but
+these are the ones the flow actually needs.
+
+## The logic: `SyncConfigInstall.installBaseline(String staticResourceName)`
+
+- Reads a **`SyncConfigBaseline_*` static-resource ZIP** containing `manifest.json` + CSVs.
+- The `manifest.json` declares per-object CSVs; a namespace macro (`$$NS`) is rewritten to the
+  live prefix at install; per-config `Sync_Config_State__c` version rows are written so the
+  installed version is recorded.
+- `SyncConfigOrchestrator` drives the orchestration and exposes the state readers
+  (`buildStateMap()` / `readCurrentVersion()`, backed by the `private` helper
+  `installedVersionMap()`).
+
+## Why the install needs a package endpoint (not a raw insert)
+
+The underlying logic is `public` (namespace-private) — the reason A1.3 (the baseline install,
+which *is* the sync-configuration creation) needs the endpoint rather than a raw insert:
+
+- `SyncConfigInstall` is declared **`public virtual with sharing`**; `installBaseline` is
+  **`public static`** — no `global`/`webservice`/`@RestResource`/`@InvocableMethod` of its own.
+- The one caller that "ran" it, `MobileAppController.installManagedBaseline()`, is a
+  **`public PageReference`** Visualforce action — also not `global`/REST/invocable.
+- The state readers on `SyncConfigOrchestrator` — `buildStateMap()` / `readCurrentVersion()` — are
+  **`public static`, unannotated** (their helper `installedVersionMap()` is **`private static`**).
+- In a managed package, **`public` = namespace-private**: a subscriber org can invoke only
+  `global` members via anonymous Apex or REST (a `private` member is even less reachable). So none
+  of the above is reachable headlessly.
+
+### The headless install endpoint — `SyncConfigInstallEndpoint`
+
+The endpoint is a thin `global @RestResource(urlMapping='/v1/syncconfig/install/*')` wrapper over
+the existing `public` logic — **no logic changes to the install path itself.**
+
+- **POST `installConfig`** — body `{"req":{"staticResourceName":"..."}}` → `installBaseline`;
+  returns an `InstallResponse` (`status` SUCCESS/FAILED, `configId`, `version`, `recordsInserted`,
+  `errorMessage`). **On `status == FAILED` (or a thrown call), report `errorMessage` and stop —
+  a `FAILED` body inside an HTTP 200 is a failure, not success, and there is no raw-sObject
+  recovery** (see A1.3). **Single argument — `staticResourceName`. There is no `parentConfigId` param:**
+  parent linkage is read from the baseline ZIP's `manifest.json` (`parentConfigId`), not passed by
+  the caller. The install still guards a missing parent (a child whose parent isn't installed
+  fails) — but that's derived from the manifest, not a method argument.
+- **GET `discoverConfigs`** — lists installable baselines as `ConfigOption`s
+  (`configId`, `displayName`, `parentConfigId`, `staticResourceName`, `availability`,
+  `requiresLabel`), each classified `AVAILABLE` / `ALREADY_INSTALLED` / `REQUIRES_PARENT`. This is
+  the discovery step: call GET to find the `staticResourceName` to POST. Wraps
+  `SyncConfigOrchestrator.discoverBaselines()` (the same read the admin VF install dropdown uses) —
+  read-only, no side effects.
+- **Access** is by Apex class access — granted through *a* permission set in the target org (named
+  e.g. `Sync_Admin`, but that name can be renamed or folded into another set across orgs/releases,
+  so never depend on it) — **not** a runtime CRUD gate: the four objects are List custom settings,
+  for which `SYNCSecurityUtil.isObjectPermissible()` always returns true, so a CRUD gate would be a
+  no-op. The skill does not verify a permission set by name; a denied call is reported as an access
+  boundary (with who grants it).
+- Never substitute a raw sObject insert for the endpoint — that skips the ZIP orchestration, `$$NS`
+  macro, ordering, and state rows.
+
+A3.1 verification is record counts via generic `core` SOQL — the intended method, which works
+today — so **no `/v1/syncconfig/verify` surface is proposed**; the state readers being
+`public`/namespace-private is moot. Two sibling `/v1/syncconfig/*` endpoints ship alongside
+install: **`/configs`** (`SyncConfigListEndpoint`, GET — lists every deployed `Sync_Config__c` as
+`{name, clientAppId, resolutionStrategy}`; closes A3.1's *list* half) and **`/assignment`**
+(`SyncConfigAssignmentEndpoint`, GET/POST/DELETE — the safe A2.3 user→config binding surface). See
+[transports-and-namespace.md](transports-and-namespace.md) for the endpoint table.
+
+## The shipped baselines
+
+Several baseline **editions** ship — covering Consumer Goods, Direct-Store-Delivery, and Retail
+Execution — each as its own static resource. **Enumerate them from the discovery endpoint
+(`discoverConfigs`) at runtime; never hardcode the names or assume a fixed set** — editions are
+added across releases.
+
+**Pick the baseline that matches the org's edition.** The steel thread is the **Retail Execution**
+path (its exact static-resource name comes from the discovery endpoint at runtime — never hardcode
+it). **Act 3 verification derives the expected counts at runtime from whichever baseline was
+actually installed** (that baseline's own manifest/CSVs) and compares them to the installed record
+counts — it must **not** assert against hardcoded literals, since a different baseline (or release)
+declares different counts.
+
+## What the backbone does NOT do (and who owns those pieces)
+
+- It does **not** resolve the **namespace** or **enable Retail Execution** (A1.1/A1.2 — core). (There is no license read to do — installing/using the app is not license-gated.)
+- It does **not** ship **field-set definitions** (A1.4 — the CSV assigns field-set *names*; the
+  `FieldSet` metadata they reference, chiefly `RetailMobilityRelevant` on standard objects, is
+  **provisioned by Retail Execution**, not by this install and not by a separate deploy in this
+  flow — a managed package can't own a FieldSet on a standard object). A1.4 therefore **verifies**
+  the referenced sets exist (read-only describe), rather than deploying them; a missing set is an
+  RE-provisioning issue, and because the sync query-field path throws on it, the verify matters.
+- It does **not** write **IOU membership** (A2.2 — core/RE; the skill only *reads* it as a
+  `Default_IOU` precondition and never writes it). User→config *assignment* (A2.3) and
+  *listing* deployed configs (A3.1) are now handled by the sibling `/v1/syncconfig/assignment` and
+  `/v1/syncconfig/configs` endpoints, not by the install backbone. A3.1 verification is record
+  counts via `core` SOQL — no additional invokable action is needed.
+
+Treat `installBaseline` as the trunk; every other Act-1 sub-act is a branch that either prepares
+its input (right baseline, RE-enabled, namespace resolved) or fills something it leaves undone.

package/skills/consumer-goods-sync-management-configure/references/transports-and-namespace.md

@@ -0,0 +1,220 @@
+# Reference — Transports & Namespace
+
+Load-bearing background for [`consumer-goods-sync-management-configure`](../SKILL.md). Read this before
+authoring any step: it defines the two transports every step must be tagged with, and the
+namespace discipline that every Sync Management App sObject/REST reference depends on.
+
+## The two transports (the honesty spine)
+
+Every step in every Act is exactly one of these. Tag it explicitly; never let a step be
+untagged.
+
+| Tag | Meaning | Where the action comes from |
+|-----|---------|------------------------------|
+| **`core`** | A generic Salesforce / Headless-360 capability. | `execute_api` (`/query`, `/tooling/query`, `/sobjects/`, `/connect/`, `/headless/*`). |
+| **`Sync Management App`** | An in-package action the agent can trigger **today**. | A **`global @RestResource /v1/*`** endpoint (the ONLY headless package surface — see below). |
+
+Where neither transport can complete a required step, report what's missing and who provides it
+(the CG Cloud platform / Retail Execution, or the org admin), then stop that step — never fake it.
+
+> **Transport reality check (do not skip).** The only real headless `Sync Management App` surface
+> is the set of **`global @RestResource /v1/*`** endpoints. This matters because the install/verify
+> logic exists as **`public`** Apex — and in a managed package `public` is **namespace-private**:
+> unreachable from a subscriber org's anonymous Apex *or* REST. Only `global` members are
+> reachable. So "the class has a method that does it" is **not** sufficient to call a step
+> `Sync Management App`; there must be a `global`/`webservice` entry point (a `/v1/*` route) that reaches it.
+
+Every automatable step resolves to a generic core capability or an invokable Sync Management App
+action. Where neither exists for a required step, the skill reports what's needed and who
+provides it, then stops that step rather than faking it.
+
+### How to decide the tag
+
+1. **Is there a `global @RestResource /v1/*` endpoint that does it?** → `Sync Management App`.
+   (A `public` Apex method does **not** count — it's namespace-private, unreachable from a subscriber org.)
+2. **Else, is it a generic Salesforce operation via `execute_api`
+   (SOQL, sObject REST, Connect, Tooling)?** → `core`. *Note: the
+   four sync objects are **custom settings**, so generic sObject REST + SOQL reach them as
+   `core` — this covers most **reads** without any package change.*
+
+If neither applies, the step is not automatable here — state what's missing, who provides it
+(Sync Management App package code, or CG Cloud core / Retail Execution / the platform), and stop
+that step. Do not invent a Sync Management App action to paper over a core limitation, and do not
+fake success.
+
+### What isn't automatable here
+
+A3.1 verification is record counts via `core` SOQL — the intended method, so there is no
+`/v1/syncconfig/verify` endpoint. And A2.2 IOU-membership *creation* is a CG Cloud core / Retail Execution task done
+outside this flow — the skill only **reads** IOU membership as a `Default_IOU` precondition and
+reports-and-stops if absent; it never writes it.
+
+## The real `Sync Management App` headless surface: `global @RestResource /v1/*`
+
+The **only** package actions an agent can trigger from a subscriber org today. `global`
+endpoints in `force-app/main/default/classes/*Endpoint.cls`:
+
+| Route | Purpose |
+|-------|---------|
+| `/v1/managedpackage` | Check whether the package is installed (`isManagedPackageInstalled`) — **check only, does not install**. |
+| `/v1/devicemetadata` | Device metadata (feature settings) — **read-only**. |
+| `/v1/namedquery`, `/v1/namedfetchtree` | Read named queries / fetch trees for a client app. |
+| `/v1/download`, `/v1/upload` | Device sync data transfer. |
+| `/v1/batchsoql`, `/v1/batchdml` | Generic SOQL/DML, but **gated by `isClientAppIdAvailable()`** (needs a pre-existing `Sync_Config__c`). |
+| `/v1/assignment`, `/v1/clientappmapper`, `/v1/clientregistration`, `/v1/bulksobjectdescribe`, `/v1/metadata` | Device-facing sync support. **`/v1/assignment` (`AssignmentEndpoint`) is NOT the A2.3 user→config binding surface** — despite the name, it's a device call that *deletes* `Sync_ID_Mapping__c` local-id rows (`@HttpPost cleanRequest(recordIdList, deviceId)`) — note `Sync_ID_Mapping__c` is a **regular custom object** (the device-owned local-to-server id map), **not** one of the config List custom settings. For A2.3 use **`/v1/syncconfig/assignment`** (row below). |
+| `/v1/syncconfig/install` | `SyncConfigInstallEndpoint`. **POST** installs a baseline (`installConfig`, body `{"req":{"staticResourceName":"..."}}`) → `InstallResponse` (status/configId/version/recordsInserted). **GET** (`discoverConfigs`) lists installable baselines with availability (`AVAILABLE` / `ALREADY_INSTALLED` / `REQUIRES_PARENT`) so a caller can discover the `staticResourceName` before POSTing. Provides the A1.3 baseline install path. |
+| `/v1/syncconfig/configs` | `SyncConfigListEndpoint`. **GET** (`listConfigs`) lists every **deployed** `Sync_Config__c` as `{name, clientAppId, resolutionStrategy}` — distinct from install's `discoverConfigs` (installable *baselines*), this is what's actually *deployed*. Lets an assignment caller pick a config by name; the `name` it returns is the value `/v1/syncconfig/assignment` expects as `configPath`, and `resolutionStrategy` tells the caller whether the assignment takes an IOU id (`Default_IOU`) or a Business Area value (`Custom_User_Field`). Provides the *list* half of A3.1's read/verify path. |
+| `/v1/syncconfig/assignment` | `SyncConfigAssignmentEndpoint`. Binds a Sync Config to a User(`005`)/Role(`00E`)/Profile(`00e`) — the headless "Config Assignment page". **Do not confuse with the device-facing `/v1/assignment` (`AssignmentEndpoint`) above** — that one cleans `Sync_ID_Mapping__c` device rows and is *not* the user→config surface; A2.3 is **this** `/v1/syncconfig/assignment` route (`Sync_Client_App_Profile_Mapping__c`). **GET** `?configId=<name>` lists assignments (resolves target names); **POST** body `{"req":{configPath, mappedRecordId, businessArea, iouId, recordId}}` upserts; **DELETE** `?id=<name-or-id>` removes. **This is the safe A2.3 explicit-mapping surface — a raw sObject POST to `Sync_Client_App_Profile_Mapping__c` is UNSAFE** because `Business_Area_Name__c` is overloaded (IOU Id under `Default_IOU`, Business Area picklist value under `Custom_User_Field`); the endpoint derives it from the config's strategy server-side and also enforces cross-config dedup + the unique-Name convention. Provides the A2.3 explicit-mapping capability. |
+
+> The three `/v1/syncconfig/*` routes cover install/discovery, listing deployed configs with
+> strategy, and binding a Sync Config to a User/Role/Profile with server-side derivation of the
+> overloaded `Business_Area_Name__c` field from the config's resolution strategy. Their
+> package-release rollout is a separate workstream. What the skill must never do is *fake* these
+> calls: for the install, do **not** hand-roll raw sObject inserts (skips the ZIP orchestration,
+> `$$NS` macro, ordering, and state rows); for A2.3, do **not** substitute a raw
+> `Sync_Client_App_Profile_Mapping__c` write (it corrupts the overloaded
+> `Business_Area_Name__c`). A `core` SOQL list is an equivalent fallback for the A3.1 *read/verify*
+> path.
+
+### Building the callable URL — the namespace goes in the ROUTE, not just the object names
+
+The table above lists each endpoint's `urlMapping` (`/v1/syncconfig/*`). That is **not** the
+callable path. Apex REST routes are served under `/services/apexrest`, and **when the metadata
+carries a namespace the namespace is injected as a path segment** — exactly as it is for object
+API names. This bites the org-namespace source-deploy case the skill treats as first-class: a
+first call to `/services/apexrest/v1/syncconfig/configs` returns **`NOT_FOUND`**; the reachable
+URL is `/services/apexrest/<ns>/v1/syncconfig/configs`.
+
+- **Rule:** `POST/GET/DELETE /services/apexrest/<ns>/<urlMapping>`, where `<ns>` is the resolved
+  namespace **as a bare segment** — and this applies to **both** namespace sources:
+  a managed-package install **and** an org-namespaced source deploy. Only a bare *unmanaged* deploy
+  (no namespace at all) omits the segment.
+- **`<ns>` here is the bare namespace, NOT `ns_prefix`.** `ns_prefix` carries the trailing `__`
+  (`<ns>__`) and is what prefixes **object/field API names** (`<ns>__Sync_Config__c`).
+  The **URL segment is the namespace *without* the underscores** (`<ns>`). Strip the trailing
+  `__` from `ns_prefix` to build the route segment.
+
+| Namespace source | Object API name | Callable route |
+|---|---|---|
+| Namespaced — **either** a managed-package install **or** an org-namespaced source deploy | `<ns>__Sync_Config__c` | `/services/apexrest/<ns>/v1/syncconfig/configs` |
+| Bare unmanaged (no namespace) | `Sync_Config__c` | `/services/apexrest/v1/syncconfig/configs` |
+
+Resolve `<ns>` once from A1.1's namespace gate (same value the object paths use, minus the `__`)
+and build every `/v1/syncconfig/*` route with it. A `NOT_FOUND` on a `/v1/*` route in a namespaced
+org almost always means the segment was omitted — not that the endpoint's release is missing (probe
+that only after confirming the namespaced URL also 404s).
+
+**A3.1's *list* half is now covered by `/v1/syncconfig/configs`, and its *verify* half is record
+counts via generic `core` SOQL — the intended method, which works today.** No `/v1/syncconfig/verify`
+endpoint is proposed: Act 3 verification adds no Sync Management App call, so `SyncConfigOrchestrator`'s
+state readers (`buildStateMap()` / `readCurrentVersion()` are `public static`, their helper
+`installedVersionMap()` `private static`) being namespace-private is moot.
+
+## Namespace discipline
+
+- **The namespace has two possible sources — a package install OR the org's own namespace.** When
+  the metadata is installed as a **managed package**, the prefix is the package's, which **varies by
+  how it was built** (a production install and a non-production/CI build can carry different
+  prefixes). When the metadata is **source-deployed into a DE/packaging/dev org**, it takes the
+  **org's own registered namespace** (`Organization.NamespacePrefix`) and there is **no**
+  `InstalledSubscriberPackage` row at all. Never assume a specific value, and never assume a
+  package install — an empty package list can still be a fully-namespaced org.
+- **Resolve the prefix at runtime — never hardcode.** The package itself resolves via
+  `SYNC_NamespaceHandler` / `SYNCConstants.NAMESPACEPREFIX`. For agent-issued `core` SOQL /
+  sObject REST against package objects, **discover the live prefix** in this order: (1) match the
+  Sync Management App package in `InstalledSubscriberPackage` and read its `NamespacePrefix`
+  (Tooling); (2) if there's no such row, read the **org namespace** with `SELECT NamespacePrefix
+  FROM Organization` (plain `core`, no Tooling) and confirm by resolving `<orgNs>Sync_Config__c`;
+  (3) failing both, probe candidate prefixes (package's known namespace(s), the org namespace, bare
+  unmanaged) via one known object's describe. Then substitute the resolved value as `<ns>` in every
+  package-object reference. See [readiness-and-enablement.md](readiness-and-enablement.md) A1.1.0 for the
+  full gate.
+- **Core objects carry no namespace.** `User`, `InternalOrgUnitUser`,
+  `InternalOrganizationUnit`, `Profile`, `UserRole`, etc. are core — do **not** prefix
+  them. Only the four sync objects + `Sync_Config_State__c` + `Sync_Client_App_Profile_Mapping__c`
+  and other package custom settings take `<ns>`.
+- **Why it bites:** the four sync objects are **List custom settings**. Their schema
+  `<defaultValue>`s do **not** auto-apply on Apex/`sobjects` DML insert — the install path
+  populates them from baseline CSVs, not from schema defaults. See
+  [sync-management-app-install-backbone.md](sync-management-app-install-backbone.md).
+
+## Dispatcher vs. direct REST (which `execute_api` path)
+
+- **`@AuraEnabled` / Apex-controller actions** go through the H360 **dispatcher**
+  (`/headless/invoke/...` envelope).
+- **Generic reads/writes bypass the dispatcher and hit Core directly** — `/query`,
+  `/tooling/query`, `/sobjects/`, `/connect/`. Nearly every
+  `core` step in this skill is a direct-REST read/write, not a dispatcher call.
+
+## `sf` CLI cookbook — parse-safe invocations (the CLI-fallback path)
+
+When `execute_api` is unavailable or unauthenticated, every `core` and `Sync Management App`
+op runs through the `sf` CLI. The CLI is only sugar over the REST resources above, but two concrete
+mechanics bite hard and cost retries — bake these in:
+
+- **stdout hygiene — the linked-plugin banner pollutes output.** In this workspace the linked
+  ESM plugin prints `Warning: @ind-rcg/modeler-sfdx-cli-plugin is a linked ESM module …` on the
+  first line, so `sf … --json` piped to a JSON parser (`python3`, `jq`) fails intermittently with `KeyError: 'result'` /
+  a JSON parse error. **Always `2>/dev/null` before parsing**, and if a stray line still slips into
+  stdout, slice from the first `{`/`[` (e.g. `sed -n '/^[[{]/,$p'`) before piping to a parser.
+- **`--body @file.json` needs the `@`.** `sf api request rest … --body @install.json` reads the
+  request body **from the file**; without the `@` the CLI sends the literal string `install.json`
+  as the body → `JSON_PARSER_ERROR` on the POST. Write the body to a temp file, pass it with `@`.
+- **Batch the four-object COUNT() verify into ONE anonymous-Apex call — never loop `sf data
+  query` per object.** Each `sf` invocation cold-starts the CLI (~15–20s); a 4–5-object COUNT()
+  loop blows the 2-min tool timeout. Run **one** `sf apex run` whose anonymous block queries all
+  four sync objects (+ `Sync_Config_State__c`) and `System.debug`s a single JSON blob — one
+  cold-start, every count. **This is the default for the A1.3 landing check and the A3.1 count
+  verify** (form 6 below); a single `sf data query COUNT()` (form 1) is fine only for a genuine
+  one-off read.
+- **Parsing `sf apex run` output — grep `USER_DEBUG` FIRST.** `sf apex run` echoes the anonymous
+  block back as `Execute Anonymous:` source lines, so a bare grep for your marker string matches the
+  **echoed source** as well as the real `USER_DEBUG|…` line → two hits, parse failure. Always filter
+  to `USER_DEBUG` before extracting the marker (the direct analogue of the linked-plugin banner
+  hazard above): `… | grep USER_DEBUG | grep -o 'SYNCCOUNTS=.*'`.
+
+Copy-pasteable forms (substitute `<org>` alias and the resolved `<ns>`/`<ns_prefix>`):
+
+```bash
+# 1. core SOQL query (objects take ns_prefix with trailing __)
+sf data query --target-org <org> --json 2>/dev/null \
+  --query "SELECT COUNT() FROM <ns_prefix>Sync_Config__c"
+
+# 2. core Tooling query (InstalledSubscriberPackage, FieldSet, RetailExecutionSettings, …)
+sf data query --use-tooling-api --target-org <org> --json 2>/dev/null \
+  --query "SELECT SubscriberPackage.Name, SubscriberPackage.NamespacePrefix FROM InstalledSubscriberPackage"
+
+# 3. Apex-REST GET — namespace is a ROUTE SEGMENT (bare ns, no __); see "Building the callable URL"
+sf api request rest "/services/apexrest/<ns>/v1/syncconfig/configs" \
+  --target-org <org> 2>/dev/null
+
+# 4. Apex-REST POST with a body FILE — note the @ prefix
+printf '%s' '{"req":{"staticResourceName":"<name>"}}' > "$TMPDIR/install.json"
+sf api request rest "/services/apexrest/<ns>/v1/syncconfig/install" \
+  --method POST --body @"$TMPDIR/install.json" \
+  --target-org <org> 2>/dev/null
+
+# 5. Apex-REST DELETE (assignment removal)
+sf api request rest "/services/apexrest/<ns>/v1/syncconfig/assignment?id=<name-or-id>" \
+  --method DELETE --target-org <org> 2>/dev/null
+
+# 6. Batched four-object COUNT() verify — ONE cold-start, all counts as a JSON blob
+#    (DEFAULT for the A1.3 landing check and the A3.1 count verify; SOQL takes ns_prefix + trailing __)
+cat > "$TMPDIR/counts.apex" <<'APEX'
+Map<String,Integer> c = new Map<String,Integer>{
+  'Sync_Config__c'                 => [SELECT COUNT() FROM <ns_prefix>Sync_Config__c],
+  'Sync_Tracked_Object_Config__c'  => [SELECT COUNT() FROM <ns_prefix>Sync_Tracked_Object_Config__c],
+  'Sync_Named_Fetch_Tree_Nodes__c' => [SELECT COUNT() FROM <ns_prefix>Sync_Named_Fetch_Tree_Nodes__c],
+  'Sync_Named_Query__c'            => [SELECT COUNT() FROM <ns_prefix>Sync_Named_Query__c],
+  'Sync_Config_State__c'           => [SELECT COUNT() FROM <ns_prefix>Sync_Config_State__c]};
+System.debug('SYNCCOUNTS=' + JSON.serialize(c));
+APEX
+sf apex run --target-org <org> --file "$TMPDIR/counts.apex" 2>/dev/null \
+  | grep USER_DEBUG | grep -o 'SYNCCOUNTS=.*'   # grep USER_DEBUG FIRST — the block is echoed too
+```
+
+`sf data query` returns `{"result":{"records":[…],"totalSize":N}}`; a bare `SELECT COUNT()` puts the
+count in `result.totalSize`. `sf api request rest` returns the endpoint's raw JSON body (no
+`result` envelope). `sf apex run` returns the debug log — the counts ride a `USER_DEBUG` line, and
+the block is echoed as `Execute Anonymous:` source, so **grep `USER_DEBUG` before extracting**. All
+three still need the `2>/dev/null` banner strip before parsing.

package/skills/consumer-goods-sync-management-configure/references/verify-and-smoke.md

@@ -0,0 +1,175 @@
+# Reference — Verify Steps & Smoke Tests
+
+Background for [Act 3](act3-plan-verify.md) and for the `purpose: verify`
+re-reads that every write step in Acts 1–2 should end with. These are the skill's verify
+conventions — apply them consistently across every write step.
+
+## End every write with an explicit verify step
+
+- **Convention & template:** the standard verify-artifact format. A verify step
+  is a distinct step with `id: verify`, a read `api`, and an `assert:` predicate:
+  ```yaml
+  - id: verify
+    description: "Confirm the write took"
+    api: "GET /query?q=SELECT COUNT() FROM <ns>Sync_Tracked_Object_Config__c"
+    assert: "count == <expected for the installed baseline>"   # derived at runtime, never hardcoded
+  ```
+- **Pre-flight validate vs. post-write verify:** the skill also uses `purpose: validate`
+  (pre-flight, e.g. "does this user exist" in A2.1) — that's the front of a step. `verify` is the
+  back. Acts 1–2 writes should carry both: validate inputs before, assert results after.
+- **The multi-object count verify is ONE batched call, not a loop.** The single-object `COUNT()`
+  template above is fine for a lone row (the assignment write). But the **four-object A1.3 landing
+  check and A3.1 count verify** must read every count in a **single anonymous-Apex call** that
+  `System.debug`s a JSON blob — **never** a `sf data query` per object: each `sf` cold-start is
+  ~15–20s, so a 4–5-object loop blows the 2-min timeout. And when parsing that call's output, **grep
+  `USER_DEBUG` first** — `sf apex run` echoes the block as `Execute Anonymous:` source, so a bare
+  marker grep matches the source too. Batched form + parse rule: transports cookbook form 6 in
+  [transports-and-namespace.md](transports-and-namespace.md).
+- **Read-back is the cheapest honesty mechanism.** For every `Sync Management App`/`core` write in this skill
+  (config install, mapping row), the verify is a plain SOQL `COUNT()` or a targeted `SELECT` of
+  the row just written. If the read-back doesn't match, report failure — never infer success from
+  a 200/201 alone. (A2.2's IOU membership is a **read-only precondition**, not a write — its
+  "verify" *is* the read itself: a matching `InternalOrgUnitUser` row proceeds; no row
+  reports-and-stops under `Default_IOU`.)
+
+## Write the run report to disk — the deliverable is a file, not the chat
+
+Reporting in the conversation is **not** the deliverable. This is a long, multi-Act, org-mutating
+run: a stream can truncate, a turn can end early, or the agent can simply conclude in chat — and if
+nothing was written, the run leaves **no artifact at all**. So persist a `report.md` to the working
+directory and **treat writing it as a first-class step, not an afterthought**:
+
+- **Create it before the first org write.** The mandatory pre-write plan (SKILL.md) is the report's
+  first section — write the file the moment the plan is formed, before enabling RE / installing /
+  assigning. Use `write_file` (or an equivalent explicit file write); do not rely on shell echoes or
+  on the chat transcript being captured.
+- **Append as you go — one section per Act.** After each Act's end state, append what ran: the
+  sub-steps executed, each step's **transport tag** (`core` / `Sync Management App`), the
+  **read-back (`assert:`) result**, and any entries added to `blocked_steps` (step + boundary +
+  who owns the missing piece). Incremental appends mean a partial or interrupted run still yields a
+  faithful, scorable record of exactly how far it got.
+- **Close with a single verdict.** End the file with the overall outcome: full setup reached
+  (Act 3 end state) — or the exact step that blocked, why, and who provides the missing piece.
+  A faithful report-and-stop is a complete deliverable; a silent chat-only summary is not.
+
+The report mirrors the honesty spine already used throughout the skill — it just makes the record
+durable. Keep it concise and factual; it is a run log, not a re-explanation of the skill.
+
+## A1.4 field-set verify — compare on the bare name, case-insensitively
+
+The A1.4 read-only describe (does each referenced field set exist per tracked object?) produces
+false "missing" hits unless the comparison is both **case-insensitive** and **namespace-agnostic**:
+
+- **`Schema.describeSObjects(...)[0].fieldSets.getMap()` keys are all-lowercase AND fully
+  namespace-qualified** (`<ns>__name`). So `getMap().containsKey('RetailMobilityRelevant')` — the
+  referenced name in its original case — returns **false even when the set exists** (the real key is
+  e.g. `<ns>__retailmobilityrelevant`). Never `containsKey` the raw referenced name.
+- **Whether the set is prefixed depends on the ORG, not the `$$NS` macro.** The
+  `Fieldset_Name_List__c` / `List_Header_Fieldset__c` 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** (`FieldSet.getNamespace()` = `<ns>`).
+- **Correct comparison: strip any `<prefix>__` from both sides and compare lowercased.** In Apex,
+  build the present-set from `FieldSet.getName().toLowerCase()` (`getName()` is the bare local name;
+  `getNamespace()` is the prefix, separately) — not from raw `getMap()` keys. In Tooling, compare
+  `DeveloperName` case-insensitively and ignore `NamespacePrefix` (it varies by org).
+- **Tooling `FROM FieldSet` requires an EntityDefinition filter** — `WHERE
+  EntityDefinition.QualifiedApiName = '<obj>'`. An unfiltered `SELECT … FROM FieldSet` returns
+  **zero rows**, which reads as "no field sets" and is a trap.
+
+## A3.2 verification — record counts only (no device call, no new endpoint)
+
+- **The method is a record-count check, full stop.** After install, compare the installed
+  per-object row counts (from A3.1's `core` `COUNT()` reads) to the **installed baseline's own
+  declared counts**. One pass / fail verdict per object. Act 3 issues **no** representative
+  device-facing `/v1/*` call as part of verification, and proposes **no** new Sync Management App endpoint
+  (`/v1/syncconfig/verify`) — the count comparison is the complete server-side check.
+- **Derive the expected counts at runtime — never hardcode them.** The expected numbers vary by
+  which baseline was installed. Identify the installed baseline from the activated config (the
+  `staticResourceName`/version captured at install time in A1.3, carried in session state, or
+  the installed `configId`/`version` read back in A3.1), then compare against the baseline's own
+  declared counts — never a fixed set of numbers.
+
+### How to get the expected counts — A3.2 is the per-object split; the aggregate was Act 1's landing check
+
+- **The aggregate was already checked at install — Act 3 does not just repeat it.** At A1.3 the
+  install ran the cheap **aggregate** landing check: sum of the four `core` COUNT() reads ==
+  `InstallResponse.recordsInserted` (which equals the manifest's total row count), needing **no**
+  static-resource fetch. `recordsInserted` + `version` were captured into session state there; reuse
+  them, but do **not** treat re-running the aggregate as A3.2's verification — that would duplicate
+  Act 1. A3.2's job, and its value over the landing check, is the **per-object split** below (it
+  catches a right-total / wrong-distribution install the aggregate cannot).
+- **Per-object split (A3.2's verification — the one thing that needs the manifest):** to verify each object's count
+  individually (e.g. `Sync_Config__c` = 1, `Sync_Tracked_Object_Config__c` = 39,
+  `Sync_Named_Fetch_Tree_Nodes__c` = 63, `Sync_Named_Query__c` = 77 — illustrative; read the real
+  split from the installed baseline), you need the baseline's per-object row counts. **Retrieve the
+  static resource in *source* format into an *in-project* scratch dir, then read `manifest.json`
+  directly — do NOT `unzip`, and do NOT stream the Body over REST.** Two field-verified constraints
+  drive the exact shape of this command:
+  - **`--output-dir` must resolve to a path INSIDE the sfdx project root.** `sf project retrieve
+    start --output-dir` rejects any dir outside the project with `OutputDirOutsideProjectError`, so
+    `mktemp -d` (which returns `/var/folders/…`, outside the project) **always errors**. Walk up
+    from the cwd to the dir containing `sfdx-project.json`, make the scratch dir *under* it, and
+    `rm -rf` it when done.
+  - **Source-format retrieve produces a folder, not a ZIP.** A retrieved static resource expands to
+    `staticresources/<name>/{manifest.json, *.csv}` — there is **no `<name>.resource` ZIP**, so any
+    `unzip` step can never run. `manifest.json` already carries the **per-object row count**, so read
+    it straight — you don't even need to count CSV rows.
+  ```bash
+  # 1) find the sfdx project root — `retrieve --output-dir` MUST resolve to a path inside it
+  ROOT="$PWD"; while [ "$ROOT" != "/" ] && [ ! -f "$ROOT/sfdx-project.json" ]; do ROOT="$(dirname "$ROOT")"; done
+  WORK="$ROOT/.sync-verify-tmp"           # in-project scratch dir — NOT mktemp -d (that path is outside the project → error)
+  trap 'rm -rf "$WORK"' EXIT              # ALWAYS clean up, even on early return / failure
+  # 2) SOURCE-format retrieve (~45s here; the MDAPI --target-metadata-dir path hung >2min)
+  sf project retrieve start --metadata "StaticResource:<baselineName>" \
+    --target-org <org> --output-dir "$WORK"
+  # 3) expands to staticresources/<baselineName>/manifest.json (+ *.csv) — no ZIP, no unzip.
+  #    manifest.json carries the per-object row counts; read them straight from it.
+  MANIFEST="$(find "$WORK" -path '*/staticresources/<baselineName>/manifest.json' | head -1)"
+  # parse each object's declared count from "$MANIFEST" and compare to the A3.1 COUNT() reads
+  ```
+  **Don't fetch the ZIP over REST, and don't reach for the MDAPI path first:**
+  - `sf api request rest .../StaticResource/<id>/Body` **UTF-8-corrupts the binary** (a 7,391-byte
+    zip came back as ~12,918 bytes of mojibake) — never stream the Body.
+  - The MDAPI/SOAP retrieve (`sf project retrieve start --target-metadata-dir <dir>`) *does* sidestep
+    the in-project `--output-dir` constraint, but it **hung past 2 min** in the field, whereas the
+    source-format `--output-dir` retrieve above finished in **~45s**. Prefer source format.
+- **Clean up the download — always.** The retrieved `staticresources/<name>/` folder (`manifest.json`
+  + CSVs) is a **throwaway verification artefact**, not project source. Because it must live *inside*
+  the project root, delete it as soon as the counts are read — the `trap 'rm -rf "$WORK"' EXIT` above,
+  or `rm -rf` before every early return. Never leave it behind in the workspace, never commit it, and
+  add the scratch path to `.forceignore` so a stray run isn't picked up as source.
+- **The hard boundary:** a green count check proves the **server side** installed the baseline's
+  artefacts. Say exactly what was verified — report it as a server-side count check.
+
+## When there is no programmatic path
+
+- **When there's no programmatic path, it's a platform ask.** If a feature is UI-only with no
+  API anywhere, name the team that owns it and move on — don't build around it.
+- **Report genuine non-automatable capabilities to the admin, with the owner named.** For
+  example, A1.2's advanced-RE pilot GA gate (`orgHasAdvncdRetailExecutionPilot`) has no API
+  anywhere — a CG Cloud core / RE concern — so it's reported, not worked around. This is
+  different from A2.2: the absence of a default mobility IOU is a report-and-stop
+  **precondition**, not a missing capability (see below).
+
+## Assignment write (A2.3) and the IOU precondition (A2.2)
+
+- **A2.3's assignment write goes through the package endpoint, not a raw junction POST.** The
+  user→config binding is written via `POST /v1/syncconfig/assignment`
+  (`SyncConfigAssignmentEndpoint`), which derives the overloaded `Business_Area_Name__c`
+  (IOU Id vs Business Area value) from the config's strategy and enforces dedup + the unique-Name
+  convention — a raw `POST /sobjects/<ns>Sync_Client_App_Profile_Mapping__c` would silently corrupt
+  the row. So the generic junction-write / sObject-REST playbooks are **not** the
+  path for A2.3 — the endpoint is. Verify the write with a `GET /v1/syncconfig/assignment`
+  read-back, as with any other write.
+- **A2.2 is NOT a junction write — it is a `core` read-only precondition (Default_IOU only).**
+  `InternalOrgUnitUser` is never written by this skill — it only **reads** the user's default
+  mobility IOU (`SELECT InternalOrganizationUnitId FROM InternalOrgUnitUser WHERE UserId = :userId
+  AND IsDfltMobIntrOrgUnit = true LIMIT 1`, mirroring `ClientAppMapperService.getDefaultIouId()`).
+  A row → carry the `iouId` to A2.3; no row → **report and stop** (the user needs a default
+  mobility IOU, a CG Cloud core / RE task done outside this flow); pure-MP org → `QueryException`
+  → degrade to the MP path. Under `Custom_User_Field` the precondition does not apply — skip it.
+  Creating IOU membership is out of scope; do **not** probe a raw `POST /sobjects/InternalOrgUnitUser`
+  or report its absence as a missing capability — it is the report-and-stop precondition above.

package/skills/dx-org-analyze/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: dx-org-analyze
 description: "Compare two Salesforce orgs side-by-side and produce a comparison report with drift score, or analyze a single org to produce an inventory covering metadata components, org permissions, system permissions, profiles, installed packages, licenses, and org limits. Use this skill when the user wants to compare orgs, diff orgs, audit configuration drift, find what changed between two environments, compare sandbox against production, or analyze a single org. Trigger phrases include: 'compare orgs', 'compare these 2 orgs', 'compare my orgs', 'diff orgs', 'org diff', 'what is different between these orgs', 'compare metadata', 'org comparison', 'audit org differences', 'compare sandbox to production', 'introspect org', 'org inventory', 'what is in my org', 'analyze org', 'org analysis', 'analyze my org', 'analyze my Salesforce org'. Do NOT use for retrieving metadata (use platform-metadata-retrieve), deploying metadata (use platform-metadata-deploy), or switching orgs (use dx-org-switch)."
-allowed-tools: Bash Read
 metadata:
   version: "1.0"
   minApiVersion: "62.0"

package/skills/dx-org-analyze/scripts/collect_org_data.py

@@ -623,13 +623,13 @@ def collect_deep_data(org_alias, base_url, access_token):
     queries = {
         "apex_classes": (
             "SELECT Name, ApiVersion, LengthWithoutComments, Status, Body FROM ApexClass WHERE NamespacePrefix = null",
-            lambda r: {"name": r.get("Name", ""), "apiVersion": r.get("ApiVersion"),
+            lambda r: {"name": r["Name"], "apiVersion": r.get("ApiVersion"),
                        "loc": r.get("LengthWithoutComments", 0), "status": r.get("Status"),
                        "bodyHash": hashlib.sha256(r.get("Body", "").encode()).hexdigest() if r.get("Body") else None}
         ),
         "apex_triggers": (
             "SELECT Name, ApiVersion, Status, Body FROM ApexTrigger WHERE NamespacePrefix = null",
-            lambda r: {"name": r.get("Name", ""), "apiVersion": r.get("ApiVersion"),
+            lambda r: {"name": r["Name"], "apiVersion": r.get("ApiVersion"),
                        "status": r.get("Status"),
                        "bodyHash": hashlib.sha256(r.get("Body", "").encode()).hexdigest() if r.get("Body") else None}
         ),

package/skills/dx-org-analyze/scripts/compute_diff.py

@@ -845,7 +845,7 @@ def render_markdown(a_data, b_data, meta_stats, perm_diff, val_diff, pkg_diff, l
         items = val_diff["cats"].get(cat_name, [])
         if not items:
             continue
-        w(f"**{cat_name}** ({len(items)} {'difference' if len(items) == 1 else 'differences'}):")
+        w(f"**{cat_name}** ({len(items)} differences):")
         w()
         w(f"| Setting | {label_a} | {label_b} |")
         w("|---------|-----|-----|")
@@ -958,10 +958,8 @@ def render_markdown(a_data, b_data, meta_stats, perm_diff, val_diff, pkg_diff, l
             if ld["diffs"]:
                 w(f"| License | {label_a} Total | {label_b} Total |")
                 w("|---------|-----|-----|")
-                def _fmt_lic(v):
-                    return "-1 (unlimited)" if v == -1 else str(v)
                 for d in ld["diffs"]:
-                    w(f"| {d['name']} | {_fmt_lic(d['a_total'])} | {_fmt_lic(d['b_total'])} |")
+                    w(f"| {d['name']} | {d['a_total']} | {d['b_total']} |")
                 w()
             if ld["a_only"]:
                 names = [l.get("Name") or l.get("DeveloperName") or l.get("NamespacePrefix", "?") for l in ld["a_only"]]