@salesforce/afv-skills 1.44.0 → 1.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.44.0",
+  "version": "1.45.0",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [

package/skills/consumer-goods-rtr-datacloud-export-configure/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: consumer-goods-rtr-datacloud-export-configure
+description: "Configure a Trade Promotion Management (TPM) org's RTR (Real Time Reporting) export pipeline to push promotion measures into Data Cloud (Data 360) for Trade Promotion Effectiveness (TPE) dashboards. Use when a customer or admin wants to set up the RTR export for Data Cloud measures, configure the RTR report for TPE, or as a delegated step from consumer-goods-tpe-dashboard-configure."
+metadata:
+  version: "1.0"
+  domains: ["Consumer Goods"]
+  relatedSkills:
+    - "consumer-goods-tpe-dashboard-configure"
+  cliTools:
+    - tool: ["node"]
+      semver: ">=20.0.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+# Setup RTR Data Cloud Export
+
+Configures the Data-Cloud-targeted RTR exports: the `Data_Cloud_Enabled` system setting, a scoped SF Data Sync, an `RTR_Report_Configuration__c` record (with its `KPI_Set__c`) for Data Cloud export, and the export trigger/status/abort REST calls. Standalone and self-contained — runs on its own, or as a delegated step invoked by `consumer-goods-tpe-dashboard-configure`, which passes through its own already-collected username, dry-run flag, and GenieAdmin confirmation result.
+
+**Distinct from a sibling CSV-export RTR skill** (if present in this org's checkout): that skill targets `Usage__c IN ('integrationmeta','reportmeta')` for CSV export to the CGCloud Processing Services host. This skill targets Data Cloud export. Same underlying `RTR_Report_Configuration__c` object and `KPI_Set__c` Apex patterns, different `Usage__c` values and `JSON__c` shape — this skill does not invoke or depend on that sibling.
+
+**For now, this skill only supports `Usage__c = 'datacloudpromotionmeasuresmeta'`** (`JSON__c.object = "promotionmeasures"`) — it is hardcoded, never asked as an input. `datacloudaccountplanmeasuresmeta` (account-plan measures) is not yet wired up.
+
+## Inputs and namespace detection
+
+Read `references/inputs-and-namespace.md` before starting. It covers:
+- The username/dry-run/GenieAdmin/TPM-Admin/namespace inputs that must be collected (or passed through by a calling skill) before Phase 1.
+- The Sales Org / KPI Set / measure-codes / date-from inputs that Phase 6 collects lazily, per Sales Org, only once its existing-config check comes back empty.
+- The namespace-detection procedure (`scripts/detect-namespace.js`) and the four `NS`/`NS_SEGMENT`/`NS_APEX`/`NS_FIELD` derivations used throughout every phase below.
+- `scripts/render-apex.js` (Apex template rendering) and `scripts/resolve-id-by-name.js` (name-to-id lookups) both load `scripts/soql-escape.js` to escape substituted/queried literals for safe SOQL/Apex interpolation.
+
+## Phases
+
+Full step-by-step commands, queries, and Apex templates for every phase are in `references/procedure.md`. Run phases in order.
+
+| Phase | Summary |
+|-------|---------|
+| 1 | Verify/assign `GenieAdmin` permission set; confirm `TPM Admin` persona assignment. |
+| 2 | Upsert the `Data_Cloud_Enabled` system setting via anonymous Apex; confirm the write. |
+| 3 | Trigger a scoped SF Data Sync against `System_Setting__c`, after capturing a baseline `Batch_Run_Status__c` Id. |
+| 4 | Poll/verify that sync completed (`Done`/`Error`/`Fatal`/`Running`). |
+| 5 | Verify the `datacloudpromotionmeasuresmeta` picklist value exists on `Usage__c` — if missing, stop and send the user to Setup (no programmatic fix exists). |
+| 6 | Loop, one Sales Org at a time: resolve Sales Org Name → Id, reuse an existing `RTR_Report_Configuration__c` or collect KPI Set/measure-codes/date-from and create one, sync if changed, then ask whether to add another Sales Org. |
+| 7 | Once Phase 6's loop is fully done, trigger the export once per configured Sales Org via `scripts/sf-rest.js` (never `sf api request rest`); capture `requestId` as the export guid. |
+| 8 | Poll each Sales Org's export status (`Ready`/`Error`/`Aborted`/`Queued`/`InProgress`) via `scripts/sf-rest.js`. |
+| 9 | Once every Sales Org has finished polling, ask the user to sync the `promotionmeasures` Data Cloud Data Stream themselves and get explicit confirmation it finished — this skill never triggers that sync. |
+| 10 | Abort an in-flight export via `scripts/sf-rest.js` — only if the user explicitly asks. |
+| 11 | Report pass/blocked/pending per phase. |
+
+## Rules
+
+- Never assign a permission set, write a record, or trigger a sync/export without an explicit user go-ahead first.
+- Never guess or hardcode `Batch_Name__c` — identify the sync's `Batch_Run_Status__c` row by recency against the captured baseline Id, and log the full row set.
+- Never attempt to programmatically add a missing `Usage__c` picklist value — the user must add it manually via Setup (link in Phase 5, `references/procedure.md`).
+- Never ask for a Usage type — this skill is hardcoded to `Usage__c = 'datacloudpromotionmeasuresmeta'` / `JSON__c.object = "promotionmeasures"` for now.
+- When the requested export type is anything other than promotion measures (e.g. `datacloudaccountplanmeasuresmeta`/account-plan measures): state the limitation, then stop or ask if the user wants the promotion-measures export instead for that Sales Org. Do not provide field-by-field manual configuration instructions for the unsupported path — no suggested `Usage__c`/`JSON__c` values, no picklist-add walkthrough. Offering a workaround recipe for the exact path this skill refuses is scope creep, not help. Report the run as blocked, not partially-passed.
+- Never skip Phase 6's existence check (keyed on `Usage__c` + `Sales_Organization__c`) — and never overwrite an existing `RTR_Report_Configuration__c` found by that check without a separate, explicit user go-ahead.
+- Never trigger Phase 7's export before Phase 6's per-Sales-Org loop is fully done — always ask whether to add another Sales Org before moving from Phase 6 to Phase 7.
+- Always give the user a chance to supply a custom `Internal_Name__c` (Phase 6 step 4) — default to `"Data 360 Promotion Measures Export <Sales Org Name>"` (no hyphen) only if they decline. This value is also `metaname` in Phase 7's export — never invent a different one for that call.
+- Phase 7 exports **once per Sales Org**, never once for the whole run.
+- Both the Sales Org and the KPI Set are given as **Names** by the user, resolved to Ids by query — this skill never creates a `Sales_Organization__c`, a `KPI_Set__c`, or KPI Set junction rows.
+- Never sync a Sales Org's config in Phase 6 unless this run actually created it — reusing an existing config as-is is a no-op, no sync call.
+- Never call the abort endpoint unless the user explicitly asks to abort.
+- Never claim Phase 9 is done on Phase 8's `Ready` status alone — always get the user's explicit confirmation that the `promotionmeasures` Data Stream was synced, once for the whole batch, before moving to Phase 10.
+- Never hardcode the namespace in a REST path, Apex snippet, or SOQL query — always use the caller-passed or self-detected `NS`/`NS_SEGMENT`/`NS_APEX`/`NS_FIELD`.
+- This skill only calls `global` Apex classes, REST endpoints, or the anonymous-Apex templates in its own `scripts/` directory — never a `public`/`private` method directly, and never a script or template from outside this skill's own directory.
+
+## Report
+
+At the end of a run, give the user a structured status per phase (1-10): pass / blocked / pending, with the specific blocking reason and remediation click-path where applicable (e.g. the Setup path for a missing picklist value). Call out anything skipped due to dry-run or a declined confirmation.
+
+**When invoked via delegation** (the calling skill used the `Skill` tool to reach this file, rather than the user directly): this report is an intermediate result, not the end of the task. Return it to the calling skill and let it continue with its own next phase — do not present this report to the user as the final answer and stop. Only surface this report directly to the user when this skill was invoked standalone.

package/skills/consumer-goods-rtr-datacloud-export-configure/references/inputs-and-namespace.md

@@ -0,0 +1,38 @@
+# Inputs to collect first
+
+Ask before starting, unless already supplied by a calling skill. Do not guess any of these.
+
+1. **TPM System Admin username** — already authenticated via `sf` CLI. Verify via the sibling script, never `sf org display --json` directly — that command's raw output includes `accessToken` (a live credential), which this script strips before printing:
+   ```bash
+   node ./scripts/sf-rest.js org-status --target-org <username>
+   ```
+   Prints `{"username","alias","connectedStatus","orgId"}`. Non-zero exit or `connectedStatus != "Connected"` ⇒ stop, ask the user to log in themselves.
+2. **Dry-run?** — offer by default. In dry-run, every read/verify step still runs; every write/trigger step is skipped and recorded as `pending — not run (dry-run)`.
+3. **GenieAdmin confirmation** — if invoked standalone, query it directly (see Phase 1 in `references/procedure.md`); if invoked by `consumer-goods-tpe-dashboard-configure`, use its passed-through result instead of re-querying.
+4. **"TPM Admin" permission-set confirmation** — org-specific, cannot be verified programmatically. Ask directly if run standalone; if invoked by `consumer-goods-tpe-dashboard-configure`, use its passed-through confirmation.
+5. **Namespace (`NS`)** — if invoked by `consumer-goods-tpe-dashboard-configure`, use its passed-through `NS` (raw namespace string, already detected once for the whole run — never re-detect). If run standalone, detect it once yourself, before Phase 1 (see "Namespace detection" below).
+
+Do **not** ask for anything below yet. None of these are collected up front — Phase 6 asks for the Sales Org Name itself as its first step of each loop iteration, then checks for an existing `RTR_Report_Configuration__c` before asking for the rest:
+
+6. **Sales Org** — a `Sales_Organization__c` **Name**, provided directly by the user; the skill resolves it to an Id by query (Phase 6 step 1). Phase 6 processes Sales Orgs one at a time, asking for this Name at the start of each loop iteration and asking whether to add another after each one finishes.
+7. **KPI Set** — the **Name** of an existing `KPI_Set__c`, provided by the user; the skill resolves it to an Id by query (Phase 6 step 3). This skill never creates a KPI Set — customers set up their `KPI_Set__c` and its `KPI_Set_KPI_Definition__c` junction rows independently, outside this skill.
+8. **Measure codes** — the KPI Definition measure codes to export, not Names. These are pure user input, exactly like Sales Org and KPI Set above — never propose, default, or pre-select any codes yourself, even as an "example" answer option. Once the KPI Set is resolved in Phase 6 step 3, query that KPI Set's junction rows, filtered to writeback-eligible KPI Definitions only (`NS_FIELD` throughout):
+   ```bash
+   sf data query --target-org <username> \
+     --query "SELECT <NS_FIELD>KPI_Definition__r.Name, <NS_FIELD>KPI_Definition__r.<NS_FIELD>Storage_Options_Measure_Code__c FROM <NS_FIELD>KPI_Set_KPI_Definition__c WHERE <NS_FIELD>KPI_Set__c = '<kpiSetId>' AND <NS_FIELD>KPI_Definition__r.<NS_FIELD>Storage_Options_Writeback__c = true"
+   ```
+   Zero rows ⇒ stop and tell the user this KPI Set has no writeback-eligible KPI Definitions (none with `Storage_Options_Writeback__c = true`); they need to enable writeback on at least one KPI Definition in the set before this export can be configured. Otherwise, show the user the resulting list of `{Name, Storage_Options_Measure_Code__c}` pairs and ask: *"Export all N writeback-eligible KPIs listed above, or a specific subset? Note: the amount of data exported is proportional to the number of KPIs selected — fewer codes means a smaller, faster export."* "All" ⇒ use every `Storage_Options_Measure_Code__c` from the list. Subset ⇒ let the user pick specific Names/codes from that same list — never accept a code that didn't appear in the query result. Used only to populate `JSON__c`'s `measurecodes` list; not used to build junction rows.
+9. **Date-from** — export start date, `YYYY-MM-DD`.
+
+## Namespace detection (standalone runs only — skip if `NS` was passed in)
+
+Same canonical procedure as `consumer-goods-tpe-dashboard-configure`'s "Namespace detection" step (package-installed lookup, falling back to `sf org display`'s `result.namespace`, falling back to `""`) — never re-derive a different way. Run the sibling script, which does all three steps and the `NS_*` derivations in one call:
+```bash
+node ./scripts/detect-namespace.js --target-org <username>
+```
+Prints `{"NS","NS_SEGMENT","NS_APEX","NS_FIELD"}` as one line of JSON. Store all four and reuse everywhere below:
+
+- `NS` — raw namespace string (may be empty).
+- `NS_SEGMENT` — REST URL path segment: `"<NS>/"` if `NS` is non-empty, else `""`. Insert immediately after `/services/apexrest/`.
+- `NS_APEX` — Apex class-reference prefix: `"<NS>."` if `NS` is non-empty, else `""`. Prefix every reference to a class from this package (`OffPlatformCallout`, `OffPlatformCalloutResponse`, `TransactionHandler`, `RTRSyncReportConfigInvocable`) with this.
+- `NS_FIELD` — custom object/field API-name prefix: `"<NS>__"` if `NS` is non-empty, else `""`. Prefix every custom object and custom field API name (standard fields like `Id`/`Name` never take this prefix) with this, in SOQL, `sf sobject describe`/`sf data upsert` commands, and Apex sObject type declarations alike.

package/skills/consumer-goods-rtr-datacloud-export-configure/references/procedure.md

@@ -0,0 +1,158 @@
+# Procedure
+
+Before starting, read `references/inputs-and-namespace.md` for the required inputs and the namespace-detection procedure.
+
+## Phase 1 — Permission sets
+
+1. **GenieAdmin** — if a value was passed in from the caller, use it. If standalone, resolve its Label first (never show the API `Name` to the user), then check the assignment:
+   ```bash
+   sf data query --target-org <username> --query "SELECT Label FROM PermissionSet WHERE Name = 'GenieAdmin'"
+   sf data query --target-org <username> \
+     --query "SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '<username>' AND PermissionSet.Name = 'GenieAdmin'"
+   ```
+   Missing ⇒ tell the user the Label from the first query (e.g. *"User <username> is missing the &lt;Label&gt; permission set. Assign it now?"*) and ask permission to assign before continuing (same pattern as `consumer-goods-tpe-dashboard-configure` Phase 3).
+2. **TPM Admin** — never re-derive or guess. Use the passed-in confirmation, or ask directly if standalone: *"Confirm the permission set(s) required for the org's TPM Admin persona are assigned to the username."* Wait for an explicit yes.
+
+## Phase 2 — `Data_Cloud_Enabled` system setting
+
+**Inform the user first — this is a global setting other parts of the org may read.** Tell them plainly: *"This will create/update the System_Setting__c record named 'Data_Cloud_Enabled' with Value__c = 'true'."* Wait for a go-ahead. `Value__c` is a text field (not Boolean) — the literal string `'true'` is written, not the Boolean `true`. There is no single-record `sf data upsert record` command in the current `sf` CLI (`sf data upsert` only has `bulk`/`resume` CSV subcommands), so this uses an idempotent anonymous-Apex upsert instead — query-then-insert-or-update inside one transaction, avoiding the query/create/update round-trip race the CLI approach would have. `%NS%` takes the `NS_FIELD` form:
+```bash
+node ./scripts/render-apex.js scripts/upsert-system-setting.apex --var NS=<NS_FIELD>
+sf apex run --target-org <username> -f <rendered-path> --json
+```
+Read the record Id back from the debug log line `RTR_DATACLOUD_SETTING_ID=<id>`. Then query to confirm the write landed, `NS_FIELD` on the custom object/field (`Name` is standard, no prefix):
+```bash
+sf data query --target-org <username> \
+  --query "SELECT Id, Name, <NS_FIELD>Value__c FROM <NS_FIELD>System_Setting__c WHERE Name = 'Data_Cloud_Enabled'"
+```
+Confirm exactly one row with `Value__c = 'true'`. Dry-run ⇒ skip both the execute and the confirmation query, record `pending — not run (dry-run)`.
+
+## Phase 3 — Trigger SF Data Sync (scoped)
+
+Capture a baseline `Batch_Run_Status__c` Id first, so Phase 4's poll can't match a stale prior sync run (`NS_FIELD` on the custom object; `Id`/standard fields unprefixed):
+```bash
+sf data query --target-org <username> \
+  --query "SELECT Id FROM <NS_FIELD>Batch_Run_Status__c ORDER BY <NS_FIELD>Start_Date__c DESC LIMIT 1" --json
+```
+Store as `LAST_BRS_ID` (empty if zero rows). Then run, scoped to `System_Setting__c` (the object Phase 2 wrote) rather than a full-org sync. `OffPlatformCallout` takes `NS_APEX`; the tracked object name inside the JSON string is a field API name and takes `NS_FIELD`; the transaction id comes from the confirmed-`global` `TransactionHandler.getTransactionIdentifier()` (also `NS_APEX`-prefixed), not `TPM_App.getTxId()` — `TPM_App` is only `public`, unreachable from anonymous Apex against a namespaced managed-package install:
+```apex
+<NS_APEX>OffPlatformCallout callout = new <NS_APEX>OffPlatformCallout('SCHEDULE_SFDATA_SYNC', null);
+<NS_APEX>OffPlatformCalloutResponse resp = callout.execute(
+  <NS_APEX>TransactionHandler.getTransactionIdentifier(), null,
+  '{"command":"SYNC","trackedObjectApiNames":["<NS_FIELD>System_Setting__c"]}'
+);
+System.debug(resp);
+```
+via `sf apex run`. Use `'RE_SYNC'` instead of `'SYNC'` only if resyncing the same scoped object list. Only omit `trackedObjectApiNames` entirely (plain `{"command":"SYNC"}`) if the user explicitly asks for a full-org sync instead. Dry-run ⇒ skip, record `pending — not run (dry-run)`.
+
+## Phase 4 — Verify the sync completed
+
+```bash
+sf data query --target-org <username> \
+  --query "SELECT Id, <NS_FIELD>Batch_Name__c, <NS_FIELD>Batch_State__c, <NS_FIELD>Start_Date__c, <NS_FIELD>End_Date__c FROM <NS_FIELD>Batch_Run_Status__c WHERE Id > '<LAST_BRS_ID>' ORDER BY <NS_FIELD>Start_Date__c DESC"
+```
+Log every returned row — the exact `Batch_Name__c` is `SFDataSyncWorker`. Terminal: `Done` = success, `Error`/`Fatal` = failure, `Running` = poll again after a short wait.
+
+## Phase 5 — Verify the `Usage__c` picklist value exists
+
+```bash
+sf sobject describe --sobject <NS_FIELD>RTR_Report_Configuration__c --target-org <username> --json
+```
+Confirm `datacloudpromotionmeasuresmeta` appears in the `Usage__c` field's `picklistValues[]`.
+
+**If missing, do not try to patch it programmatically.** Picklist values are not carried by a metadata deploy or package upgrade into a subscriber org (confirmed Salesforce platform behavior) — this skill has no way to append a picklist value without a full read-modify-write of the field, which is more fragile than the manual step. Tell the user to add it manually: Setup → Object Manager → RTR Report Configuration → Fields & Relationships → Usage → New → add `datacloudpromotionmeasuresmeta` ("Data 360 Promotion Measures Export"). Reference: https://help.salesforce.com/s/articleView?id=ind.tpm_add_report_metadata.htm&type=5. Then re-run this check before continuing to Phase 6.
+
+## Phase 6 — Reuse or create the RTR Report Configuration (one Sales Org at a time)
+
+`RTR_Report_Configuration__c` is unique per (`Usage__c`, `Sales_Organization__c`) pair. This skill always uses `Usage__c = 'datacloudpromotionmeasuresmeta'` — hardcoded, never asked. Customers can configure more than one Sales Org under it — process them **one at a time**: run steps 1-6 below for the current Sales Org, then ask *"Add another Sales Org to configure?"* before moving on. The Sales Org Name itself is **not** collected up front — step 1 below asks for it fresh on each loop iteration. Check for an existing config **before** asking for anything else — do not ask for KPI Set/measure codes/date-from until the check comes back empty for this Sales Org. Keep a running `CONFIGURED_SALES_ORGS` list of `{salesOrgId, salesOrgName, internalName}` for every Sales Org this loop finishes (both the reused-as-is and the newly-created case) — Phase 7 exports **once per Sales Org in that list**, using each one's `internalName` as `metaname`, only after this loop is fully done.
+
+The remaining Apex template's `%NS%` placeholder expects the `NS_FIELD` form (double-underscore, e.g. `cgcloud__`, or empty) — pass the already-detected `NS_FIELD` value as `--var NS=<NS_FIELD>` in every `render-apex.js` call below (never re-detect; use the value from "Namespace detection" / the caller's passed-through `NS`).
+
+This skill never creates a `KPI_Set__c` or its `KPI_Set_KPI_Definition__c` junction rows — customers set those up independently. Both the Sales Org and the KPI Set are given as **Names** by the user; the skill resolves each to an Id by query (steps 1 and 3) before step 4 runs.
+
+1. **Ask for this iteration's Sales Org Name**, then resolve it to an Id, `NS_FIELD` on the custom object (`Id`/`Name` are standard, unprefixed):
+   ```bash
+   node ./scripts/resolve-id-by-name.js --target-org <username> --object <NS_FIELD>Sales_Organization__c --name "<salesOrgName>"
+   ```
+   Zero rows ⇒ stop and tell the user no `Sales_Organization__c` with that Name exists; ask for a different Name. More than one row ⇒ show the matches and ask the user to disambiguate. Exactly one ⇒ use its Id as `<salesOrgId>`.
+2. **Check for an existing config, per Sales Org Id**, `NS_FIELD` on the custom object/fields:
+   ```bash
+   sf data query --target-org <username> \
+     --query "SELECT Id, Name, <NS_FIELD>Internal_Name__c, <NS_FIELD>Reporting_KPI_Set__c, <NS_FIELD>JSON__c FROM <NS_FIELD>RTR_Report_Configuration__c WHERE <NS_FIELD>Usage__c = 'datacloudpromotionmeasuresmeta' AND <NS_FIELD>Sales_Organization__c = '<salesOrgId>'"
+   ```
+   - **Found** ⇒ show the user the existing config's Name/Id and current `Internal_Name__c`/`Reporting_KPI_Set__c`/`JSON__c`, and ask them to confirm proceeding with it as-is. Confirmed ⇒ record its Id as `<configId>` and its `Internal_Name__c` as `<internalName>` for this Sales Org, mark it **unchanged**, and skip straight to step 6 (loop control) — no sync call for this Sales Org, since nothing was modified. Never ask for KPI Set/measure codes/date-from for this Sales Org, and never overwrite it here. Declined ⇒ skip this Sales Org for this run and note it in the report; don't fall through to rebuilding it without a separate, explicit ask.
+   - **Not found** ⇒ now ask for this Sales Org's remaining build inputs (KPI Set Name, measure codes, date-from — see `references/inputs-and-namespace.md`) and continue with steps 3-6 below for this Sales Org.
+3. **Resolve the KPI Set Name to an Id**, `NS_FIELD` on the custom object (`Id`/`Name` are standard, unprefixed):
+   ```bash
+   node ./scripts/resolve-id-by-name.js --target-org <username> --object <NS_FIELD>KPI_Set__c --name "<kpiSetName>"
+   ```
+   Zero rows ⇒ stop and tell the user no `KPI_Set__c` with that Name exists; ask them to create it (with its measure-code junction rows) first, or give a different Name. More than one row ⇒ show the matches and ask the user to disambiguate. Exactly one ⇒ use its Id as `<kpiSetId>`.
+4. **Determine the Internal Name, then create the RTR Report Configuration** — this Sales Org has no existing row (step 2 confirmed it), so this always inserts; the template's own existence check is just an idempotency safety net if this phase is re-run. **Ask the user** whether they want to supply a custom `Internal_Name__c` for this Sales Org's config, or use the default: `"Data 360 Promotion Measures Export <Sales Org Name>"` (no hyphen — whether one would trip a validation rule on this field is unconfirmed, so it's avoided), where `<Sales Org Name>` is the `Name` resolved in step 1 — e.g. `"Data 360 Promotion Measures Export US01"`. (A bare label with no Sales Org suffix is only correct when there's exactly one Sales Org configured; once a second one is added, its row needs its own distinguishable label — flag this to the user if they supply a custom name that doesn't vary per Sales Org.) Record whichever value is used as `<internalName>` for this Sales Org — Phase 7 passes it as `metaname` when triggering that Sales Org's export. Assemble `JSON__c` next:
+   ```json
+   {"measurecodes":["<code1>","<code2>"],"datefrom":"<YYYY-MM-DD>","object":"promotionmeasures"}
+   ```
+   Then render and run (pass the JSON raw — `render-apex.js` escapes every `--var` value for you; pre-escaping it here would double-escape):
+   ```bash
+   node ./scripts/render-apex.js scripts/upsert-report-config.apex \
+     --var NS=<NS_FIELD> --var USAGE=datacloudpromotionmeasuresmeta --var INTERNAL_NAME="<internalName>" \
+     --var SALES_ORG_ID=<salesOrgId> --var KPI_SET_ID=<kpiSetId> --var JSON_LITERAL="<json>"
+   sf apex run --target-org <username> -f <rendered-path> --json
+   ```
+   Read the record Id back from `RTR_DATACLOUD_CONFIG_ID=<id>`. Mark this Sales Org **changed**.
+5. **Sync it — only if changed.** If step 2 found an existing config and the user confirmed reuse as-is, there is nothing to sync — skip this step entirely for that Sales Org. Only run this after step 4 actually created a new config:
+   ```apex
+   <NS_APEX>RTRSyncReportConfigInvocable.syncReportConfig(
+     new List<<NS_FIELD>RTR_Report_Configuration__c>{ [SELECT Id FROM <NS_FIELD>RTR_Report_Configuration__c WHERE Id = '<configId>'] }
+   );
+   ```
+   via `sf apex run`. `RTRSyncReportConfigInvocable` (an Apex class) takes `NS_APEX`; `RTR_Report_Configuration__c` (the sObject) takes `NS_FIELD`. Sync happens here, immediately after this Sales Org's config is created — never deferred to a later batch step.
+6. Add `{salesOrgId, salesOrgName, internalName}` for this Sales Org to `CONFIGURED_SALES_ORGS`, then ask: *"Add another Sales Org to configure?"* Yes ⇒ go back to step 1 with the next Sales Org Name. No ⇒ move to Phase 7. Dry-run ⇒ skip Phase 6 entirely (for every Sales Org), record `pending — not run (dry-run)`.
+
+## Phase 7 — Trigger the export (once per Sales Org, only after Phase 6's loop is done)
+
+**Never trigger this until Phase 6's loop has finished for every Sales Org the user wants configured this run** — exporting mid-loop would run against an incomplete `CONFIGURED_SALES_ORGS` list. Once done, run once per `{salesOrgName, internalName}` entry in that list — every Sales Org gets its own export call, never a single shared one. `metaname` is that entry's `internalName` (the same value written to `Internal_Name__c` for that Sales Org's config in Phase 6) — this ties the export run back to the specific `RTR_Report_Configuration__c` it was scheduled for. Never use `sf api request rest` — it's a beta command with no `--json` flag at all (confirmed live, it errors `Nonexistent flag: --json`) that can change or be pulled without notice; use the sibling `scripts/sf-rest.js` instead, which fetches the org's instanceUrl/access token itself and makes the callout directly with Node's built-in fetch:
+```bash
+node ./scripts/sf-rest.js \
+  --target-org <username> --method POST \
+  --path "/services/apexrest/<NS_SEGMENT>measures/export/schedule" \
+  --body '{"metaname":"<internalName>","salesorg":"<salesOrgName>","object":"promotionmeasures"}'
+```
+Capture `csvGuid` per Sales Org from the response — the schedule endpoint's response body field is actually named `requestId` (confirmed live), not `csvGuid`; use `requestId`'s value as the guid for Phase 8 and Phase 10 below. Dry-run ⇒ skip, record `pending — not run (dry-run)`.
+
+## Phase 8 — Poll export status (once per Sales Org from Phase 7)
+
+Small dedicated loop (the response shape — a flat `Status` field, not `applicationStatus`/`apps[]` — doesn't match a generic app-install poller, so this doesn't reuse `consumer-goods-tpe-dashboard-configure`'s `poll-status.js`). Run once per `(csvGuid, salesOrgName)` pair captured in Phase 7. Via the sibling `scripts/sf-rest.js`, not `sf api request rest`:
+```bash
+while true; do
+  status=$(node ./scripts/sf-rest.js \
+    --target-org <username> \
+    --path "/services/apexrest/<NS_SEGMENT>measures/export/<csvGuid>/status?salesorg=<salesOrgName>" \
+    | node -e "process.stdin.on('data',d=>console.log(JSON.parse(d).Status))")
+  echo "export status: $status"
+  case "$status" in
+    Ready) echo "export ready"; break ;;
+    Error|Aborted) echo "export failed: $status"; exit 1 ;;
+    Queued|InProgress) sleep 30 ;;
+  esac
+done
+```
+`Ready` = terminal success, `Error`/`Aborted` = terminal failure, `Queued`/`InProgress` = keep polling.
+
+## Phase 9 — Sync the `promotionmeasures` Data Stream
+
+Phase 8's `Ready` status only confirms the export landed on the Processing services — the `promotionmeasures` Data Stream in Data Cloud still needs to ingest it before the exported measures show up downstream (KPI Sets, dashboards). This skill never triggers that sync itself — Data Stream sync/refresh isn't something this skill drives via `sf`/REST, and it's an action better left to the user to run interactively in Data Cloud setup.
+
+**Run this once for the whole batch, not once per Sales Org** — the `promotionmeasures` Data Stream isn't scoped per Sales Org, so there's nothing to gain from asking after each one. Only ask once every Sales Org in `CONFIGURED_SALES_ORGS` has finished Phase 8's poll (whether `Ready` or otherwise recorded). This is a hard blocking gate, not a status update — pose it as an explicit yes/no confirmation question (the same way as the Phase 2 system-setting go-ahead and Phase 3 sync-trigger go-ahead), not as a plain narrated sentence that moves straight on to Phase 10: *"All exports have completed. Please go to Data Cloud → Data Streams → `promotionmeasures`, sync it, and wait until the sync is done (or wait until the scheduled sync completes). Has the sync finished?"* Do not proceed to Phase 10 on a generic "continue"/"next step" from the user — that answers a different question (moving the overall flow along), not this specific one (whether the Data Stream sync is actually done). Wait for an explicit confirmation before moving to Phase 10. Dry-run ⇒ skip, record `pending — not run (dry-run)`.
+
+## Phase 10 — Abort (only if the user asks to)
+
+```bash
+node ./scripts/sf-rest.js \
+  --target-org <username> --method POST \
+  --path "/services/apexrest/<NS_SEGMENT>measures/export/abort/<csvGuid>?salesorg=<salesOrgName>&metaname=<internalName>"
+```
+Never call this unless the user explicitly requests an abort.
+
+## Phase 11 — Report
+
+Record pass/blocked/pending per phase (1-10 above) for the final report — this is exactly what `consumer-goods-tpe-dashboard-configure`'s corresponding step relays as its own result when this skill is invoked via delegation.

package/skills/consumer-goods-rtr-datacloud-export-configure/scripts/detect-namespace.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * Detects this org's namespace and derives every prefixed form this skill
+ * needs, replacing the manual "run sf, read the JSON, compute NS_* by hand"
+ * steps in SKILL.md's Namespace detection section. Same canonical procedure
+ * as `setup-tpe-dashboard`'s Namespace detection step — never re-derive a
+ * different way:
+ *   1. `sf package installed list` — find the "Consumer Goods Cloud" entry,
+ *      NS = its SubscriberPackageNamespace.
+ *   2. Not found (source-deployed/dev-beta org) ⇒ `sf org display`'s
+ *      `result.namespace`.
+ *   3. Still null/blank ⇒ NS = "" (genuinely unnamespaced org).
+ *
+ * CLI usage:
+ *   node detect-namespace.js --target-org <username>
+ *
+ * Prints one line of JSON to stdout: {"NS","NS_SEGMENT","NS_APEX","NS_FIELD"}.
+ * Exit codes: 0 = success, 2 = usage/CLI error.
+ */
+
+const { execFileSync } = require('child_process');
+
+function sfJson(cliArgs) {
+  const raw = execFileSync('sf', cliArgs, { encoding: 'utf8' });
+  return JSON.parse(raw).result;
+}
+
+function detectNamespace(targetOrg) {
+  const packages = sfJson([
+    'package', 'installed', 'list',
+    '--target-org', targetOrg, '--json',
+  ]);
+  const cgCloud = (packages || []).find(
+    (p) => p.SubscriberPackageName === 'Consumer Goods Cloud'
+  );
+  if (cgCloud && cgCloud.SubscriberPackageNamespace) {
+    return cgCloud.SubscriberPackageNamespace;
+  }
+
+  const { namespace } = sfJson([
+    'org', 'display',
+    '--target-org', targetOrg, '--json',
+  ]);
+  return namespace || '';
+}
+
+function deriveForms(NS) {
+  return {
+    NS,
+    NS_SEGMENT: NS ? `${NS}/` : '',
+    NS_APEX: NS ? `${NS}.` : '',
+    NS_FIELD: NS ? `${NS}__` : '',
+  };
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) continue;
+    args[token.slice(2)] = argv[i + 1];
+    i += 1;
+  }
+  return args;
+}
+
+function requireArg(args, name) {
+  if (!args[name]) {
+    console.error(`Missing required --${name}`);
+    process.exit(2);
+  }
+  return args[name];
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const targetOrg = requireArg(args, 'target-org');
+  const NS = detectNamespace(targetOrg);
+  process.stdout.write(JSON.stringify(deriveForms(NS)));
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { detectNamespace, deriveForms };

package/skills/consumer-goods-rtr-datacloud-export-configure/scripts/render-apex.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * Render one of this skill's `scripts/*.apex` templates by substituting
+ * `%TOKEN%` placeholders, writing the result to a temp file, and printing
+ * that file's path on stdout (so a caller can pipe it straight into
+ * `sf apex run -f <path>`).
+ *
+ * Usage:
+ *   node render-apex.js <template-path> --var NS=cgcloud_dev__ --var NAME="My Set"
+ *
+ * Every `%TOKEN%` in the template must have a matching --var — this script
+ * fails loudly on any leftover `%TOKEN%` after substitution rather than
+ * silently sending unrendered Apex to the org.
+ *
+ * Every --var value is escaped (see soql-escape.js) before substitution, so
+ * callers must pass raw values — never pre-escape a value before handing it
+ * to this script, that would double-escape it.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { escapeSoqlLiteral } = require('./soql-escape');
+
+function parseArgs(argv) {
+  const templatePath = argv[0];
+  const vars = {};
+  for (let i = 1; i < argv.length; i += 1) {
+    if (argv[i] !== '--var') continue;
+    const pair = argv[i + 1];
+    const eq = pair.indexOf('=');
+    vars[pair.slice(0, eq)] = pair.slice(eq + 1);
+    i += 1;
+  }
+  return { templatePath, vars };
+}
+
+function main() {
+  const { templatePath, vars } = parseArgs(process.argv.slice(2));
+  if (!templatePath) {
+    console.error('Missing required <template-path>');
+    process.exit(2);
+  }
+
+  let rendered = fs.readFileSync(templatePath, 'utf8');
+  for (const [key, value] of Object.entries(vars)) {
+    rendered = rendered.split(`%${key}%`).join(escapeSoqlLiteral(value));
+  }
+
+  const leftover = rendered.match(/%[A-Z_]+%/g);
+  if (leftover) {
+    console.error(`render-apex: unresolved placeholder(s): ${leftover.join(', ')}`);
+    process.exit(2);
+  }
+
+  const outPath = path.join(
+    os.tmpdir(),
+    `rtr-datacloud-${path.basename(templatePath, '.apex')}-${process.pid}.apex`
+  );
+  fs.writeFileSync(outPath, rendered, 'utf8');
+  console.log(outPath);
+}
+
+main();

package/skills/consumer-goods-rtr-datacloud-export-configure/scripts/resolve-id-by-name.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * Resolve a record's Id by an exact-match Name query, safely — the Name
+ * value is escaped (see soql-escape.js) before being embedded in the SOQL
+ * literal, so a Name containing a quote (or a crafted injection payload)
+ * can't break out of it or inject additional clauses. Callers never build
+ * this WHERE clause by hand.
+ *
+ * Usage:
+ *   node resolve-id-by-name.js --target-org <username> --object <ObjectApiName> --name "<value>"
+ *
+ * Prints the `sf data query --json` result verbatim to stdout.
+ */
+
+const { execFileSync } = require('child_process');
+const { escapeSoqlLiteral } = require('./soql-escape');
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    if (!argv[i].startsWith('--')) continue;
+    args[argv[i].slice(2)] = argv[i + 1];
+    i += 1;
+  }
+  return args;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const targetOrg = args['target-org'];
+  const object = args['object'];
+  const name = args['name'];
+  if (!targetOrg || !object || name === undefined) {
+    console.error('Usage: resolve-id-by-name.js --target-org <username> --object <ObjectApiName> --name "<value>"');
+    process.exit(2);
+  }
+
+  const query = `SELECT Id, Name FROM ${object} WHERE Name = '${escapeSoqlLiteral(name)}'`;
+  const output = execFileSync(
+    'sf',
+    ['data', 'query', '--target-org', targetOrg, '--json', '--query', query],
+    { encoding: 'utf8' }
+  );
+  process.stdout.write(output);
+}
+
+main();