@salesforce/afv-skills 1.44.0 → 1.46.0

package/skills/consumer-goods-rtr-datacloud-export-configure/scripts/sf-rest.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/**
+ * Authenticated Salesforce REST callout, replacing `sf api request rest`
+ * everywhere in this skill — that command is beta, doesn't support --json,
+ * and beta CLI surfaces can change or be pulled without notice. Fetches the
+ * org's instanceUrl and access token via the `sf` CLI, then performs a
+ * plain HTTP request with Node's built-in fetch. Access token retrieval is
+ * version-gated the same way as `datakit-for-tpe`'s
+ * `download-static-resource.js`: `sf org auth show-access-token` for CLI
+ * >= 2.136.8 (below that version, `sf org display`'s own `result.accessToken`
+ * is a redacted hint string, not a real token — see the `sfJson`/`getAccessToken`
+ * pair below). The token is never printed.
+ *
+ * CLI usage:
+ *   node sf-rest.js --target-org <username> --path <path> \
+ *     [--method GET|POST|PATCH|DELETE] [--body <json-string>]
+ *
+ * <path> is relative to the org's instanceUrl, e.g.
+ * "/services/apexrest/tpm-api/..." or "/services/data/v67.0/...".
+ * Prints the response body as one line of JSON to stdout on both success
+ * and failure, so a non-2xx error body (e.g. `{"error":"..."}`) is still
+ * readable by the caller. Exit codes: 0 = 2xx response, 1 = non-2xx
+ * response, 2 = usage/CLI error.
+ *
+ * Module usage (for sibling scripts in this same skill's scripts/ dir —
+ * never imported across skill directories):
+ *   const { restRequest } = require('./sf-rest');
+ *   const { ok, status, body } = await restRequest({ targetOrg, path, method, body: jsonString });
+ */
+
+/**
+ * Also exposes two subcommands that print only safe, non-secret fields from
+ * `sf org display --json` — that command's `result` includes `accessToken`
+ * (a live credential), so nothing in this skill should run it directly and
+ * surface the raw output; these strip it before printing:
+ *   node sf-rest.js org-status --target-org <username>
+ *     -> {"username","alias","connectedStatus","orgId"} ; exit 1 if not Connected
+ */
+
+const { execFileSync } = require('child_process');
+
+function sfJson(cliArgs) {
+  const raw = execFileSync('sf', cliArgs, { encoding: 'utf8' });
+  return JSON.parse(raw).result;
+}
+
+const ACCESS_TOKEN_VIA_SHOW_COMMAND_SINCE = [2, 136, 8];
+
+function getCliVersion() {
+  // Unlike every other `sf ... --json` command, `sf version --json` returns
+  // its fields at the top level — no `{status, result}` envelope.
+  const raw = execFileSync('sf', ['version', '--json'], { encoding: 'utf8' });
+  const { cliVersion } = JSON.parse(raw);
+  const match = cliVersion.match(/(\d+)\.(\d+)\.(\d+)/);
+  // A pre-release/suffixed version string (e.g. a nightly build) that
+  // doesn't match this pattern is treated as "new enough" below, via
+  // isAtLeast's null passthrough — never silently fall back to the
+  // redacted-token path on an unparseable version.
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function isAtLeast(version, minVersion) {
+  if (!version) return true;
+  for (let i = 0; i < minVersion.length; i += 1) {
+    const a = version[i] || 0;
+    const b = minVersion[i] || 0;
+    if (a !== b) return a > b;
+  }
+  return true;
+}
+
+function getAccessToken(targetOrg) {
+  const useShowAccessTokenCommand = isAtLeast(
+    getCliVersion(),
+    ACCESS_TOKEN_VIA_SHOW_COMMAND_SINCE
+  );
+  if (useShowAccessTokenCommand) {
+    return sfJson([
+      'org', 'auth', 'show-access-token',
+      '--target-org', targetOrg,
+      '--no-prompt', '--json',
+    ]).accessToken;
+  }
+  return sfJson(['org', 'display', '--target-org', targetOrg, '--json']).accessToken;
+}
+
+async function restRequest({ targetOrg, path, method, body }) {
+  const { instanceUrl } = sfJson(['org', 'display', '--target-org', targetOrg, '--json']);
+  const accessToken = getAccessToken(targetOrg);
+
+  const headers = { Authorization: `Bearer ${accessToken}` };
+  if (body !== undefined) headers['Content-Type'] = 'application/json';
+
+  const response = await fetch(`${instanceUrl}${path}`, {
+    method: method || 'GET',
+    headers,
+    body,
+  });
+  const text = await response.text();
+  let parsedBody = {};
+  if (text.length) {
+    try {
+      parsedBody = JSON.parse(text);
+    } catch {
+      parsedBody = text;
+    }
+  }
+  return { ok: response.ok, status: response.status, body: parsedBody };
+}
+
+function getOrgStatus(targetOrg) {
+  const info = sfJson(['org', 'display', '--target-org', targetOrg, '--json']);
+  return {
+    username: info.username,
+    alias: info.alias || null,
+    connectedStatus: info.connectedStatus,
+    orgId: info.id,
+  };
+}
+
+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];
+}
+
+async function main() {
+  const [maybeCommand, ...rest] = process.argv.slice(2);
+
+  if (maybeCommand === 'org-status') {
+    const args = parseArgs(rest);
+    const status = getOrgStatus(requireArg(args, 'target-org'));
+    process.stdout.write(JSON.stringify(status));
+    if (status.connectedStatus !== 'Connected') process.exit(1);
+    return;
+  }
+
+  const args = parseArgs(process.argv.slice(2));
+  const targetOrg = requireArg(args, 'target-org');
+  const path = requireArg(args, 'path');
+  const method = args.method || 'GET';
+
+  const { ok, status, body } = await restRequest({ targetOrg, path, method, body: args.body });
+  process.stdout.write(JSON.stringify(body));
+  if (!ok) {
+    console.error(`sf-rest: HTTP ${status}`);
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}
+
+module.exports = { restRequest, getOrgStatus };

package/skills/consumer-goods-rtr-datacloud-export-configure/scripts/soql-escape.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * Escape a value for safe interpolation into a single-quoted SOQL/Apex
+ * string literal — escape backslashes first, then single quotes, so a value
+ * like `O'Brien Foods` (or one ending in a backslash) can't break out of the
+ * literal it's placed in. Shared by render-apex.js (Apex template
+ * substitution) and any SKILL step that builds a `sf data query` string by
+ * hand from admin-supplied free text (Sales Org / KPI Set names).
+ *
+ * CLI usage: node scripts/soql-escape.js "O'Brien Foods"
+ */
+
+function escapeSoqlLiteral(value) {
+  return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+
+if (require.main === module) {
+  const value = process.argv[2];
+  if (value === undefined) {
+    console.error('Usage: soql-escape.js <value>');
+    process.exit(2);
+  }
+  console.log(escapeSoqlLiteral(value));
+}
+
+module.exports = { escapeSoqlLiteral };

package/skills/consumer-goods-rtr-datacloud-export-configure/scripts/upsert-report-config.apex

@@ -0,0 +1,51 @@
+// Idempotent upsert of an RTR_Report_Configuration__c row by
+// (Usage__c, Internal_Name__c, Sales_Organization__c). Usage is restricted to
+// the two Data-Cloud-targeted values this skill supports:
+// 'datacloudpromotionmeasuresmeta' or 'datacloudaccountplanmeasuresmeta'
+// (distinct from the CSV-export 'integrationmeta'/'reportmeta' pair used by
+// the sibling setup-rtr-export skill). JSON__c is assembled off-Salesforce as
+// {"measurecodes":[...],"datefrom":"YYYY-MM-DD","object":"promotionmeasures"
+// |"accountplanmeasures"} and passed in as %JSON_LITERAL%. Each placeholder
+// below is substituted exactly once, into a String variable declaration —
+// the only place a raw value is embedded as an Apex literal, and
+// render-apex.js escapes it there (see soql-escape.js). The SOQL WHERE
+// clause and every field assignment then use the resulting Apex variables as
+// SOQL bind variables (:usage, :internalName, ...) or plain assignments —
+// never a second literal substitution of the same placeholder. Pass raw,
+// unescaped values for every placeholder below.
+//
+//   %NS%             -> namespace field prefix e.g. "cgcloud_dev__"
+//   %USAGE%          -> 'datacloudpromotionmeasuresmeta' or
+//                       'datacloudaccountplanmeasuresmeta'
+//   %INTERNAL_NAME%  -> free-text admin-supplied name (e.g. "O'Brien Foods")
+//   %SALES_ORG_ID%   -> 15/18-char Sales_Organization__c Id
+//   %KPI_SET_ID%     -> 15/18-char KPI_Set__c Id
+//   %JSON_LITERAL%   -> the full JSON body, raw (not pre-escaped)
+String usage = '%USAGE%';
+String internalName = '%INTERNAL_NAME%';
+String salesOrgId = '%SALES_ORG_ID%';
+String kpiSetId = '%KPI_SET_ID%';
+String jsonLiteral = '%JSON_LITERAL%';
+
+List<%NS%RTR_Report_Configuration__c> existing = [
+  SELECT Id
+  FROM %NS%RTR_Report_Configuration__c
+  WHERE %NS%Usage__c = :usage
+    AND %NS%Internal_Name__c = :internalName
+    AND %NS%Sales_Organization__c = :salesOrgId
+  WITH USER_MODE
+  LIMIT 1
+];
+%NS%RTR_Report_Configuration__c row;
+if (existing.isEmpty()) {
+  row = new %NS%RTR_Report_Configuration__c();
+  row.%NS%Usage__c = usage;
+  row.%NS%Internal_Name__c = internalName;
+  row.%NS%Sales_Organization__c = salesOrgId;
+} else {
+  row = existing[0];
+}
+row.%NS%Reporting_KPI_Set__c = kpiSetId;
+row.%NS%JSON__c = jsonLiteral;
+upsert as user row;
+System.debug(LoggingLevel.INFO, 'RTR_DATACLOUD_CONFIG_ID=' + row.Id);

package/skills/consumer-goods-rtr-datacloud-export-configure/scripts/upsert-system-setting.apex

@@ -0,0 +1,21 @@
+// Idempotent upsert of the Data_Cloud_Enabled System_Setting__c row.
+// Query-then-upsert instead of `sf data upsert record` — that CLI subcommand
+// only supports bulk/resume CSV, not a single record. Placeholder:
+//   %NS% -> namespace field prefix, e.g. "cgcloud_dev__" (empty for source org)
+List<%NS%System_Setting__c> existing = [
+  SELECT Id
+  FROM %NS%System_Setting__c
+  WHERE Name = 'Data_Cloud_Enabled'
+  WITH USER_MODE
+  LIMIT 1
+];
+%NS%System_Setting__c row;
+if (existing.isEmpty()) {
+  row = new %NS%System_Setting__c();
+  row.Name = 'Data_Cloud_Enabled';
+} else {
+  row = existing[0];
+}
+row.%NS%Value__c = 'true';
+upsert as user row;
+System.debug(LoggingLevel.INFO, 'RTR_DATACLOUD_SETTING_ID=' + row.Id);

package/skills/consumer-goods-tpe-dashboard-configure/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: consumer-goods-tpe-dashboard-configure
+description: "End-to-end headless setup of Trade Promotion Effectiveness (TPE) dashboards for a Trade Promotion Management (TPM) Cloud org, covering tenant pairing checks, permission sets, SSOT and Tableau Next enablement, C360 SDM verification, the TPM Accruals data kit install, business-period export, RTR Data Cloud export configuration, the TPM_PROMOTION_MEASURE Data Transform, TPE Analytics app install, and optional KPI dashboard customization. Use when a customer or admin wants to set up TPE dashboards, enable Trade Promotion Effectiveness, install the TPE analytics app, or set up and customize TPE dashboards with their own KPIs."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+  domains: ["Consumer Goods"]
+  relatedSkills:
+    - "consumer-goods-rtr-datacloud-export-configure"
+    - "consumer-goods-tpe-dashboard-custom-kpi-configure"
+    - "consumer-goods-tpe-datakit-deploy"
+  cliTools:
+    - tool: ["node"]
+      semver: ">=20.0.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+# Consumer Goods TPE Dashboard Configure
+
+Bring a TPM org from bare state to a running TPE dashboard in one guided session, driven entirely by `sf` CLI + REST/anonymous-Apex against an already-authenticated org — never a password or interactive login on the user's behalf.
+
+Persona: a **Salesforce TPM System Admin** setting up TPE dashboards for their org.
+
+Delegates three of its twelve steps to standalone sibling skills (own `SKILL.md`, own inputs, self-contained per this repo's skills architecture rules — no shared files):
+
+- Step 7 → `consumer-goods-tpe-datakit-deploy`
+- Step 9 → `consumer-goods-rtr-datacloud-export-configure`
+- Step 12 → `consumer-goods-tpe-dashboard-custom-kpi-configure` (optional, only if the customer wants custom KPIs on the base dashboards)
+
+Every other step runs directly in this skill.
+
+## Inputs to collect first
+
+Ask before starting. Do not guess.
+
+1. **TPM System Admin username** — must already be authenticated via `sf` CLI. Verify with `node ./scripts/sf-rest.js org-status --target-org <username>` (never `sf org display --json` directly — see `references/phases-1-6.md`).
+2. **Dry-run?** — offer by default. In dry-run, every read/verify/check step still runs; every write/trigger/install step is skipped and recorded as `pending — not run (dry-run)`.
+
+Also detect the installed package namespace and version-gate the org (Consumer Goods Cloud >= 262.2 required) before Phase 1 — see "Namespace detection" in `references/phases-1-6.md`.
+
+## Phase list
+
+| Phase | Step | Summary | Details |
+|---|---|---|---|
+| Setup | — | Collect inputs, detect namespace, version-gate the org | `references/phases-1-6.md` |
+| 1 | Tenant pairing | Ask user to confirm Hyperforce Processing Service pairing (not verifiable programmatically) | `references/phases-1-6.md` |
+| 2 | TPM Admin permission set(s) | Ask user to confirm org-specific persona permission sets are assigned | `references/phases-1-6.md` |
+| 3 | GenieAdmin / TableauEinsteinAdmin | Query, and on confirmation assign, these two permission sets | `references/phases-1-6.md` |
+| 4 | SSOT package | Verify the `ssot` managed package is installed | `references/phases-1-6.md` |
+| 5 | Enable Tableau Next | Ask user to confirm manual UI enablement (not verifiable programmatically) | `references/phases-1-6.md` |
+| 6 | C360 SDM | Verify or trigger + poll the C360 Unified Semantic Model app install | `references/phases-1-6.md` |
+| 7 | TPM Accruals Data Kit | **Delegated** to `consumer-goods-tpe-datakit-deploy` | `references/phases-7-12.md` |
+| 8 | Business Period export | Anonymous-Apex export via a Hyperforce-substrate Sales Org, poll, then confirm the `tpmbusinessperiod` Data Stream sync | `references/phases-7-12.md` |
+| 9 | RTR Data Cloud export | **Delegated** to `consumer-goods-rtr-datacloud-export-configure` | `references/phases-7-12.md` |
+| 10 | TPM_PROMOTION_MEASURE Data Transform | Ask (credit consumption), then run and poll the Data Transform | `references/phases-7-12.md` |
+| 11 | TPE Analytics App install | Trigger + poll the async app-framework install (~15-20 min) | `references/phases-7-12.md` |
+| 12 | Customize KPIs (optional) | **Delegated** to `consumer-goods-tpe-dashboard-custom-kpi-configure`, only if requested | `references/phases-7-12.md` |
+
+`references/phases-7-12.md` also documents the shared `scripts/poll-status.js` poller and the full set of hard Rules (never authenticate on the user's behalf, never hardcode a namespace or Sales Org, never claim success on anything but a terminal success status, a poll timeout is not a failure, etc.) that apply across every phase.
+
+## Scripts
+
+- `scripts/sf-rest.js` — authenticated REST calls; also exposes `org-status` (strips `accessToken` before printing).
+- `scripts/poll-status.js` — generic async-status poller, reused by Phases 6 and 11.
+- `scripts/find-failure-reason.js` — extracts the actual per-requirement failure reason for a `FailedStatus` app-framework install (Phase 11), including "DMO not available" detection.
+- `scripts/render-apex.js` — renders an anonymous-Apex template with `--var` substitutions; loads `scripts/soql-escape.js` to escape substituted literals.
+- `scripts/soql-escape.js` — escapes a value for safe interpolation into a single-quoted SOQL/Apex string literal.
+- `scripts/run-data-transform.js` — triggers and polls a named Data Transform (Phase 10).
+- `scripts/schedule-business-period-export.apex` — anonymous-Apex template for Phase 8.
+
+## Report
+
+At the end of a run, give the user a structured status per phase (1-12): pass / blocked / pending, with the specific blocking reason and remediation click-path where applicable. Call out anything skipped due to dry-run, a declined confirmation, or (Phase 12) the customer opting out of KPI customization.

package/skills/consumer-goods-tpe-dashboard-configure/references/phases-1-6.md

@@ -0,0 +1,112 @@
+# Phases 1-6 — Prerequisites, Permission Sets, SSOT, Tableau Next, C360 SDM
+
+## Inputs to collect first
+
+Ask before starting. Do not guess.
+
+1. **TPM System Admin username** — must already be 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 run `sf org login web` (or their usual login flow for sf-cli) and re-run this check. Every subsequent command in this skill uses `--target-org <username>`.
+2. **Dry-run?** — offer by default. In dry-run, every read/verify/check step still runs; every write/trigger/install step is skipped and recorded as `pending — not run (dry-run)`.
+
+## Namespace detection (run once, before Phase 1)
+
+This package's namespace is never assumed — it will be a managed-package namespace (e.g. `cgcloud`). Detect once and reuse everywhere below:
+
+1. ```bash
+   sf package installed list --target-org <username> --json
+   ```
+   Find the entry with `SubscriberPackageName == "Consumer Goods Cloud"`. If found, `NS` = its `SubscriberPackageNamespace`, and **version-gate immediately** (step 4 below) using that same entry's `SubscriberPackageVersionNumber` before doing anything else in this skill.
+2. If package is not found inform the user and stop the process.
+3. **Minimum package version gate** (managed-package installs only, i.e. step 1 found a match): this skill's features require **Consumer Goods Cloud package version 262.2 or later**. Parse `SubscriberPackageVersionNumber` (format `<major>.<minor>.<patch>.<build>`, e.g. `"262.2.0.3"`) into `(major, minor)`. Compare against the required `(262, 2)`:
+   - `major > 262`, or (`major == 262` and `minor >= 2`) ⇒ pass, continue.
+   - Otherwise ⇒ **stop immediately, before Phase 1.** Tell the user plainly, with both numbers spelled out:
+     *"This org has Consumer Goods Cloud package version `<installed SubscriberPackageVersionNumber>` installed. TPE dashboard setup requires version `262.2` or later. Please upgrade the package before continuing."*
+     Do not proceed into any phase — this is a hard block, not a warning, since the underlying feature genuinely isn't present below that version.
+
+Derive, and reuse for every step below and when delegating to `consumer-goods-rtr-datacloud-export-configure` (Phase 9):
+
+- `NS_SEGMENT` — REST URL path segment: `"<NS>/"` if `NS` is non-empty, else `""`. Insert immediately after `/services/apexrest/`. (Standard Salesforce platform REST APIs under `/services/data/...` — Phases 6 and 11 — are never namespaced; don't apply this there.)
+- `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`, etc.) in anonymous Apex 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) in SOQL and `sf data`/`sf sobject` commands with this.
+
+## Phase 1 (Step 1) — Tenant pairing status
+
+This cannot be verified programmatically — there is no supported, non-beta way to check Processing Service tenant pairing status from this skill. Explicitly ask the user for a **yes/no confirmation** (e.g. via the `AskUserQuestion` tool if available, with Yes/No options) — never state it as a plain sentence the user could mistake for informational text: *"Is the Hyperforce Processing Service paired for this org?"* Proceed on yes; on no or no response, stop here and tell the user to complete Processing Service pairing before continuing.
+
+Record the user's confirmation for the final report.
+
+## Phase 2 (Step 2) — Permission set(s) for the TPM Admin persona
+
+"TPM Admin persona" is a role, not an actual permission set name. This cannot be verified programmatically — the exact permission set name/assignment backing that persona is org-specific. Do not query or infer it. Explicitly ask the user for a **yes/no confirmation** (e.g. via the `AskUserQuestion` tool if available, with Yes/No options) — never state it as a plain sentence the user could mistake for informational text: *"Are the permission set(s) required for the TPM Admin persona assigned to <username>?"* Wait for an explicit yes before continuing; on no, stop and tell the user to assign it first.
+
+## Phase 3 (Step 3) — GenieAdmin / TableauEinsteinAdmin permission sets
+
+1. Resolve both permission sets' Labels once, so every user-facing message below shows the Label — never the API `Name`:
+   ```bash
+   sf data query --target-org <username> \
+     --query "SELECT Id, Name, Label FROM PermissionSet WHERE Name IN ('GenieAdmin','TableauEinsteinAdmin')"
+   ```
+2. Query assignments by `PermissionSet.Name` (still the stable API name, for the `WHERE` filter — only the Label from point 1 goes in front of the user):
+   ```bash
+   sf data query --target-org <username> \
+     --query "SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '<username>' AND PermissionSet.Name IN ('GenieAdmin','TableauEinsteinAdmin')"
+   ```
+3. Whichever name is absent from the result rows is missing.
+4. For each missing one, tell the user its **Label** (from point 1) and ask permission to assign it — e.g. *"User <username> is missing the &lt;Label&gt; permission set. Assign it now?"* Never assign without an explicit go-ahead.
+5. On confirmation, use the Id already resolved in point 1 (no need to re-query):
+   ```bash
+   sf data create record --sobject PermissionSetAssignment \
+     --values "AssigneeId=<userId> PermissionSetId=<psId>" --target-org <username>
+   ```
+   If declined, skip and note it in the report.
+6. Record the confirmed-assigned GenieAdmin result — Step 9's delegated skill reuses it (point 1 of its own Procedure) instead of re-querying.
+
+## Phase 4 (Step 4) — SSOT package verification
+
+1. ```bash
+   sf package installed list --target-org <username> --json
+   ```
+2. Check `result[]` for `SubscriberPackageNamespace == "ssot"` (Salesforce Standard Data Model).
+3. Missing ⇒ tell the user SSOT isn't installed and ask them to install it manually from Data Cloud setup — this is a manual install, not scriptable. Stop and wait for confirmation, then re-run this check.
+4. Present ⇒ record the installed version and continue.
+
+## Phase 5 (Step 5) — Enable Tableau Next
+
+TPE dashboards run on Tableau Next; this must be enabled before C360 SDM (Phase 6) and the TPE Analytics app install (Phase 11).
+
+There is no reliable programmatic way to enable or verify this — it's a manual UI toggle only, and the `TableauIncludedAppManager` permission set check isn't a reliable signal of enablement. Do not query for it, and do not attempt any API call to enable it.
+
+1. **Cannot be verified programmatically.** Explicitly ask the user for a **yes/no confirmation** (e.g. via the `AskUserQuestion` tool if available, with Yes/No options) — never state it as a plain sentence the user could mistake for informational text: *"Is Tableau Next enabled in this org? (Setup → Tableau Next Setup → Enable Tableau Next)"*
+2. On yes, record enabled and continue to Phase 6.
+3. On no, tell the user to enable it manually at Setup → Tableau Next Setup → Enable Tableau Next, then stop and wait — re-ask the same yes/no question before continuing. Do not proceed on a guess, and do not attempt any automated enablement.
+
+## Phase 6 (Step 6) — C360 SDM verification and installation
+
+1. **Check status** — via `scripts/sf-rest.js`, not `sf api request rest` (beta, no `--json`, can change without notice):
+   ```bash
+   node ./scripts/sf-rest.js \
+     --target-org <username> \
+     --path "/services/data/v67.0/app-framework/apps?templateSourceId=sfdc_internal__C360UnifiedSemanticModel"
+   ```
+   Any returned app with `applicationStatus` of `SuccessStatus` or `SuccessWithWarningsStatus` ⇒ record installed, move on.
+2. **Not installed / not successful** — tell the user, ask permission to trigger installation. On confirmation:
+   ```bash
+   node ./scripts/sf-rest.js \
+     --target-org <username> --method POST \
+     --path "/services/data/v67.0/app-framework/apps" \
+     --body '{"label":"C360_SDM","name":"C360_SDM","description":"C360 Unified Semantic Data Model","templateSourceId":"sfdc_internal__C360UnifiedSemanticModel","templateValues":{"isTest":false},"runtimeMethod":"Async"}'
+   ```
+   Extract `app.id`, then poll with the shared poller:
+   ```bash
+   node ./scripts/poll-status.js --target-org <username> \
+     --path "/services/data/v67.0/app-framework/apps/<appId>" \
+     --status-field applicationStatus \
+     --success-values SuccessStatus,SuccessWithWarningsStatus \
+     --failure-values FailedStatus \
+     --interval-seconds 30 --max-wait-seconds 900
+   ```
+   Timeout while `InProgressStatus` ⇒ tell the user it's still installing, not a failure — re-run this step later. `FailedStatus` ⇒ stop, report failure, point to `/lightning/setup/C360/home` for a manual retry.
+3. Declined ⇒ skip and note it; Phase 7 re-checks and re-prompts rather than assuming.

package/skills/consumer-goods-tpe-dashboard-configure/references/phases-7-12.md

@@ -0,0 +1,157 @@
+# Phases 7-12 — Data Kit, Business Period Export, RTR Export, Data Transform, App Install, KPI Customization
+
+## Phase 7 (Step 7) — TPM Accruals Data Kit for TPE (delegated)
+
+Invoke the `consumer-goods-tpe-datakit-deploy` skill via the `Skill` tool, passing through:
+
+- TPM admin username + dry-run flag (Inputs).
+- The permission set(s) for the TPM Admin persona (Phase 2) and GenieAdmin (Phase 3) confirmation results, so it doesn't re-ask/re-query either.
+- The detected `NS` (raw namespace string) from the Namespace detection step, so it doesn't re-detect.
+
+`consumer-goods-tpe-datakit-deploy` accepts all of these as its own inputs (it also runs standalone, deriving them itself when not supplied). Treat its final report (pass/blocked/pending) as this phase's result and fold it into the overall report. **When `consumer-goods-tpe-datakit-deploy` returns, continue directly to Phase 8 in this same run — its own "Report" section is an intermediate result for this skill, not a signal to stop.**
+
+## Phase 8 (Step 8) — Export TPM Business Period data
+
+**Two distinct `salesorg` values — do not conflate them:** the `OffPlatformCallout` constructor argument is tenant/substrate routing only (must be a real Hyperforce-substrate Sales Org, called exactly once); the JSON body's `"salesorg":"*"` is a business-level "export for every sales org" parameter, not a platform-level wildcard.
+
+This step must stay anonymous Apex, not a direct REST call to `ScheduleRTRExportService` (`/measures/export/schedule`, the same endpoint `consumer-goods-rtr-datacloud-export-configure` Phase 10 calls): that REST resource reads a single `salesorg` field out of its JSON body and uses that same value for **both** tenant/substrate routing (`SalesOrgSubstrate` mode — `SalesOrganizationServiceWOSharing.getTenantSubstrateEnum(salesorg)`) and the forwarded payload. `"*"` doesn't resolve to a real `Sales_Organization__c`, so it can't be used for routing — there's no way to decouple a real routing Sales Org from the payload's wildcard through that REST resource. The template below (run via `sf apex run`) keeps that decoupling: a real Sales Org drives routing via the `OffPlatformCallout` constructor; the JSON body's `salesorg` stays `"*"`.
+
+1. Query for a routing Sales Org (never hardcode one), with `NS_FIELD` prefixed on the custom object and custom field (`Name` is standard, no prefix):
+   ```bash
+   sf data query --target-org <username> \
+     --query "SELECT Name FROM <NS_FIELD>Sales_Organization__c WHERE <NS_FIELD>Tenant_Substrate__c = 'Hyperforce_AWS' LIMIT 1"
+   ```
+   Zero rows ⇒ **block** — no Hyperforce-substrate Sales Org to route `SCHEDULE_RTR_EXPORT` through. Never fall back to a GCP-substrate org.
+2. Render and run the template, passing that `Name` and `NS_APEX` (the sibling `scripts/render-apex.js`, same substitution pattern as `consumer-goods-rtr-datacloud-export-configure`'s templates):
+   ```bash
+   node ./scripts/render-apex.js scripts/schedule-business-period-export.apex \
+     --var NS_APEX=<NS_APEX> --var SALES_ORG=<hyperforceSalesOrgName>
+   sf apex run --target-org <username> -f <rendered-path> --json
+   ```
+   `sf apex run` provisions its own temporary trace flag for the execute-anonymous call automatically — no separate "enable debug logs" step is needed, and none should be asked of the user. Read the response back from the debug log line `SCHEDULE_RTR_EXPORT_RESPONSE=<response>` in the `--json` output's `result.logs`.
+3. Inspect the returned response for a 2xx; log it in full. The response body field is `requestId` (confirmed live — not `csvGuid`, despite sharing the schedule endpoint used elsewhere); use its value as `<requestId>` below. Poll its status with the shared poller — its flat `{"Status": "..."}` body shape fits `poll-status.js`'s single-field contract just as well as the app-install responses in Phases 6 and 11 do. **The `salesorg` query param on this status call is tenant/substrate routing, not the business-level wildcard** — pass the same real Hyperforce-substrate Sales Org Name (`<hyperforceSalesOrgName>`) resolved in step 1/2, never the JSON body's `"*"`; passing `"*"` here (confirmed live) fails with `CGCloudException: {"reason":"CONFIGURATION","message":"Sales Org \"*\" not found."}`.
+   ```bash
+   node ./scripts/poll-status.js --target-org <username> \
+     --path "/services/apexrest/<NS_SEGMENT>measures/export/<requestId>/status?salesorg=<hyperforceSalesOrgName>" \
+     --status-field Status \
+     --success-values Ready \
+     --failure-values Error,Aborted \
+     --interval-seconds 30 --max-wait-seconds 900
+   ```
+   `Ready` = terminal success, `Error`/`Aborted` = terminal failure, `Queued`/`InProgress` = keep polling (timeout while non-terminal ⇒ not a failure — a later run can re-poll).
+4. Record pass/blocked/pending.
+5. **Sync the `tpmbusinessperiod` Data Stream.** Step 3's `Ready` status only confirms the export landed on the Processing Services host — the `tpmbusinessperiod` Data Stream in Data Cloud still needs to ingest it before the exported business-period data shows up downstream. 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. Only ask once step 3 reached `Ready` (skip if step 3 failed or is still pending). This is a hard blocking gate, not a status update — pose it as an explicit yes/no confirmation question, not a plain narrated sentence that moves straight on to Phase 9: *"The tpmbusinessperiod export has completed. Please go to Data Cloud → Data Streams → `tpmbusinessperiod`, sync it, and wait until the sync finishes (or wait for the scheduled sync). Has the sync finished?"* Do not proceed to Phase 9 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 9. Dry-run ⇒ skip, record `pending — not run (dry-run)`.
+
+## Phase 9 (Step 9) — Data Cloud measures RTR export (delegated)
+
+Invoke the `consumer-goods-rtr-datacloud-export-configure` skill via the `Skill` tool, passing through:
+
+- TPM admin username + dry-run flag (Inputs).
+- The detected `NS` (raw namespace string) from the Namespace detection step, so it doesn't re-detect.
+- The GenieAdmin confirmation result from Phase 3 (so it isn't re-queried).
+
+Treat its final report as this phase's result and fold it into the overall report. **When it returns, continue directly to Phase 10 in this same run — do not stop here.**
+
+## Phase 10 (Step 10) — TPM_PROMOTION_MEASURE Data Transform
+
+1. **Wait until all CRM Data Streams are synced before running the transform.** The TPM_PROMOTION_MEASURE Data Transform reads from CRM Data Streams — running it before they've finished syncing produces stale or incomplete measures. This cannot be verified programmatically — never check or infer stream status yourself (e.g. via SOQL against `DataStream`/`DataStreamHistory`, Tooling/REST calls, or any other query); the user is the sole source of truth here. Explicitly ask the user for a **yes/no confirmation** (e.g. via the `AskUserQuestion` tool if available, with Yes/No options) — never state it as a plain sentence the user could mistake for informational text: *"Before we run the Data Transform, please make sure all the relevant CRM Data Streams have finished syncing — every one should show Last Run Status = Success. Have all of them reached Success? (You can find the list at Data Cloud → Setup → Data Kits → TPM Accruals → Data Stream Bundles → expand the TPM section.)"* Do not proceed to step 2 on a generic "continue"/"next step" — wait for explicit confirmation.
+   - If the user says any stream isn't `Success` yet: `None` — has never run; ask them to manually refresh the stream. `Pending` — a run is already queued; ask them to just refresh the status (not the stream itself — it's already running, refreshing the stream would just requeue it). Then re-ask the same yes/no question.
+   Dry-run ⇒ skip, record `pending — not run (dry-run)`.
+2. **Ask before running — Data Cloud credit consumption.** Tell the user plainly: *"Running the TPM_PROMOTION_MEASURE Data Transform will consume Data Cloud credits proportional to the volume of promotion-measure data processed. Proceed?"* Never trigger without an explicit yes. In dry-run, skip and record `pending — not run (dry-run)`.
+3. On confirmation, hand off to the shared script. This Data Transform's name is never namespaced, regardless of the package namespace detected earlier — pass it as-is:
+   ```bash
+   node ./scripts/run-data-transform.js --target-org <username> --transform-name TPM_PROMOTION_MEASURE
+   ```
+4. Record pass/blocked/pending, the final `lastRunStatus`, and (on failure) `lastRunErrorMessage`. A timeout while `lastRunStatus` is still non-terminal after the script's 1-hour default wait is not a failure — a later run can re-poll (pass `--max-wait-seconds` explicitly for a longer window if needed).
+
+## Phase 11 (Step 11) — Install TPE Analytics App
+
+1. **Prerequisite check** — Tableau Next enabled (Phase 5), GenieAdmin (Phase 3), C360 SDM `SuccessStatus` (Phase 6), and data kit deployed (Phase 7) are already independently verified earlier in this run; treat as a fast confirmation, not a re-block, when all four already passed. Otherwise re-check and block on whichever failed.
+2. **Install trigger** — the confirmed TPE template id is `sfdc_internal__Trade_Promotion_Effectiveness` (not the MCP tooling's built-in ids). Via `scripts/sf-rest.js`, not `sf api request rest`:
+   ```bash
+   node ./scripts/sf-rest.js \
+     --target-org <username> --method POST \
+     --path "/services/data/v67.0/app-framework/apps" \
+     --body '{"label":"TPE_Analytics","name":"TPE_Analytics","templateSourceId":"sfdc_internal__Trade_Promotion_Effectiveness","runtimeMethod":"Async"}'
+   ```
+   Extract `app.id`. Never use `Sync` — this is a 400-500 task pipeline (~15-20 minutes).
+3. **Poll** with the same shared poller, a longer window this time:
+   ```bash
+   node ./scripts/poll-status.js --target-org <username> \
+     --path "/services/data/v67.0/app-framework/apps/<appId>" \
+     --status-field applicationStatus \
+     --success-values SuccessStatus,SuccessWithWarningsStatus \
+     --failure-values FailedStatus \
+     --interval-seconds 60 --max-wait-seconds 1200
+   ```
+4. `SuccessStatus` / `SuccessWithWarningsStatus` ⇒ record success (note warnings). Timeout while `InProgressStatus` ⇒ inform the user it's still installing — a later run can re-poll; not a failure.
+
+   `FailedStatus` ⇒ **find the actual reason before stopping.** `applicationStatus: FailedStatus` alone carries no detail — the per-requirement failure message only lives on the install's async execution graph (its Domino runtime), never on the app resource itself. Use the sibling script rather than hand-parsing this (confirmed live: the graph is deeply nested and its own failure-message template is inconsistently formatted):
+   ```bash
+   node ./scripts/find-failure-reason.js --target-org <username> --app-id <appId>
+   ```
+   Prints one line of JSON: `{"failedNodes":[{"node","statusMessage"}],"dmoNotAvailable":[<DMO API names>]}`. `failedNodes` is every failed requirement's human-readable message from the most recent install attempt — log it in full; the underlying message is generic ("...enabled or minimum required set of fields mapped in your org. Please make sure required Datakits are installed and data stream is deployed."), so don't assume every failure is DMO-related.
+
+   - **`dmoNotAvailable` is non-empty** ⇒ a "DMO not available" failure. Every DMO name it can surface here is one this org's `consumer-goods-tpe-datakit-deploy` Phase 4 DMO-mapping deploy is responsible for (e.g. `ssot__BusinessPeriod__dlm`, `MeasureDefinition_std__dlm`, `ssot__PromotionOffer__dlm`, `ssot__Promotion__dlm`, `ssot__Account__dlm`, `ssot__PromotionAccount__dlm`, `ssot__PromotionTemplate__dlm`, `ssot__ProductCategory__dlm`, `PromotionProductMeasure_std__dlm`, `PromotionOfferProductMeasure_std__dlm`) — treat any other DMO name it lists the same way. Whether a DMO's mapping is actually active in the org's Data Cloud tenant isn't exposed over any documented REST/SOQL API (confirmed live — `ssot/data-model-objects` lists DMO definitions, not per-org mapping/activation state) — ask the user directly, one question per DMO, via `AskUserQuestion` (Yes/No):
+     *"The TPE Analytics App install failed because `<DMO>` isn't available in Data Cloud. Please check Setup → Data Cloud → Data Model → find `<DMO>` → its Mapping tab. Is `<DMO>` mapped to a data source object in this org?"*
+     - **No (not mapped)** ⇒ something went wrong with the data kit deployment itself, not with this phase. **Stop the entire `consumer-goods-tpe-dashboard-configure` run here** — don't just record this phase as blocked and continue. Point the user back to Phase 7 (`consumer-goods-tpe-datakit-deploy`), specifically its Phase 5 `DataKitDeploymentLog` verification, to find and fix the actual deployment error. Only re-attempt this phase after that comes back clean.
+     - **Yes (mapped)** ⇒ a known Data Cloud quirk: deploying `dataSrcDataModelFieldMap` metadata doesn't always fully activate the mapping in the org's Data Cloud tenant until it's opened and saved once in the UI. Ask the user to open that same Mapping tab and click **Save** (no field changes needed) for `<DMO>`'s mapping, confirm it saved without error, then retry this phase from step 2 — POST a new install rather than re-polling the failed `appId`.
+   - **`failedNodes` is non-empty but `dmoNotAvailable` is empty** ⇒ a different requirement failed. Relay the exact `statusMessage`(s) to the user and stop this phase — don't guess a remediation for a failure shape this skill hasn't seen before.
+   - **`failedNodes` is empty** ⇒ the graph-level detail wasn't available yet (e.g. activities not populated). Fall back to reporting bare `FailedStatus` and point the user to the install's `installationHistoryUrl` / `appHubUrl` (already captured from the create response in step 2) for a manual look in Setup.
+5. Record the app id, name, and final status.
+
+## Phase 12 (Step 12) — Customize TPE dashboard KPIs (delegated, optional)
+
+Implements Salesforce Help's [Customize Trade Promotion Effectiveness Analytics
+Dashboards](https://help.salesforce.com/s/articleView?id=ind.tpe_tpm_tab_next_dashboard_customize.htm&type=5) —
+specifically **Customization Scenario 1** ("Use Custom KPIs with Standard Dashboards"). Let the user
+know this when asking (step 1 below), so they can cross-reference the doc if they want more detail
+before deciding.
+
+1. **Ask before proceeding.** Tell the user plainly: *"The base TPE Analytics app is installed with
+   its standard KPIs. Would you like to customize the Promotion/Tactic dashboards with your own KPI
+   measure codes now? (For more details see scenario 1 in https://help.salesforce.com/s/articleView?id=ind.tpe_tpm_tab_next_dashboard_customize.htm&type=5)"* Never proceed on anything other than an explicit yes. On no/undecided, skip
+   this phase entirely and record `skipped — not requested` — note that `consumer-goods-tpe-dashboard-custom-kpi-configure` can
+   still be run standalone later. In dry-run, still ask (it's a plan-only decision); record
+   `pending — not run (dry-run)` if yes, `skipped — not requested` if no.
+2. **Prerequisite check** — Phase 11's TPE Analytics app install must have reported
+   `SuccessStatus`/`SuccessWithWarningsStatus`; `consumer-goods-tpe-dashboard-custom-kpi-configure` clones that app's Extended
+   TPM Analytics SDM and dashboards, so it cannot run against a missing/failed install. If Phase 11
+   didn't succeed, skip this phase and note it's blocked on Phase 11, not independently broken.
+3. On a yes, collect `consumer-goods-tpe-dashboard-custom-kpi-configure`'s own inputs now (suffix, per-slot overrides — see
+   its `SKILL.md`'s "Inputs to collect first" for the exact shape), then invoke it via the `Skill`
+   tool, passing through:
+   - TPM admin username + dry-run flag (Inputs).
+   - The suffix and per-slot `--overrides` just collected.
+4. Treat its final report (pass/blocked/pending per artifact) as this phase's result and fold it
+   into the overall report. This is the only phase in this skill that ever mutates the TPE Analytics
+   app's semantic model/dashboards after Phase 11 — `consumer-goods-tpe-dashboard-custom-kpi-configure` never touches the base
+   artifacts themselves, only adds suffixed clones alongside them (see its own `SKILL.md`). **This is
+   the last phase — once it returns (or is skipped per step 1), proceed straight to this skill's own
+   overall Report below; don't stop mid-run waiting on anything further from the sub-skill.**
+
+## Shared poller
+
+`scripts/poll-status.js` — generic, reused by Phases 6 and 11 (and any future async-install step): calls `restRequest()` from the sibling `scripts/sf-rest.js` on each tick (a direct authenticated HTTP GET, not `sf api request rest` — that command is beta, has no `--json`, and can change or be pulled without notice), reads `--status-field` off the response (handles both a single-object and a first-array-element shape), stops on a success/failure value or timeout, non-zero exit on failure/timeout. See its own header comment for the full flag list. Do not write a second poll loop — extend this one if a new step needs different response shape handling.
+
+## Diagnosing an app-framework install failure
+
+`scripts/find-failure-reason.js` — used by Phase 11's `FailedStatus` branch (and reusable as-is for Phase 6's, if it ever needs the same depth of detail): `applicationStatus`/`requestStatus` values like `FailedStatus` never carry a reason on the app resource itself. The reason only exists on the install's Domino runtime — walk `GET /app-framework/apps/<appId>/activities` to the latest attempt's `runtimeRequest.id`, then `GET /domino/runtimes/<runtimeRequestId>` to its `definition.nodes`, and collect every node whose `results.validate.taskStatus` starts with `Fail`. Confirmed live against a real failure (an org with a DMO mapping deliberately removed): the readiness-check nodes for each required DMO report `-1` when the DMO can't be queried in Data Cloud, and the paired requirement node's `statusMessage` reads *"Sorry! You don't have [`<dmo>__dlm`] enabled or minimum required set of fields mapped in your org. Please make sure required Datakits are installed and data stream is deployed."* — the script extracts the DMO API name out of that message into `dmoNotAvailable`. Do not hand-parse this graph inline elsewhere; extend this script if a new failure shape needs handling. Note its own failure-message template is inconsistently formatted (confirmed live — one DMO's message is missing its opening `[`) and HTML-entity-encoded; the script normalizes both before matching/printing.
+
+## Rules
+
+- Never authenticate on the user's behalf — if `org-status` shows disconnected, stop and ask the user to log in themselves.
+- Never run `sf org display --json` directly and read its output — always go through `scripts/sf-rest.js`'s `org-status` subcommands, which strip `accessToken` before printing.
+- Never proceed past the Namespace detection step on a managed-package org below Consumer Goods Cloud version 262.2 — state both the installed and required version numbers and stop.
+- Never proceed past Phase 1 until the user has explicitly confirmed (yes/no) that Hyperforce Processing Service pairing is ready. Phase 1 only ever asks about Hyperforce, never GCP.
+- Never assign a permission set, write a record, or trigger an install without an explicit user go-ahead first.
+- Never attempt to enable or verify Tableau Next via any REST/Tooling/Connect API call, or by querying for the `TableauIncludedAppManager` permission set — there's no reliable programmatic path (the enable APIs are confirmed unavailable live against a test org on `v63.0`, and the permission set isn't a reliable enablement signal); Phase 5 always asks the user directly and defers enablement to the Setup UI.
+- Never hardcode a Sales Org code — always query for one with the required `Tenant_Substrate__c`.
+- Never hardcode the namespace (`cgcloud_dev`, `cgcloud`, or any other string) in a REST path, Apex snippet, or SOQL query — always use the detected `NS`/`NS_SEGMENT`/`NS_APEX`/`NS_FIELD` from the Namespace detection step.
+- Never claim an async install succeeded on anything other than `SuccessStatus`/`SuccessWithWarningsStatus` (apps), a user-confirmed ready `state` (tenant status), or a non-`FAILURE` terminal `lastRunStatus` with a fresh `lastRunDate` (data transform).
+- A poll timeout while still in an in-progress state is **not** a failure — report it as still-running and let a later run re-poll.
+- This skill never deploys Apex. It only calls `global` Apex classes, REST endpoints already shipped in the target org's installed package, or the anonymous-Apex templates in its own `scripts/` directory — never a `public`/`private` method directly, never a class this skill deploys itself (skills are distributed independently of this repo; see the architecture rule on self-contained skills), 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-12): pass / blocked / pending, with the specific blocking reason and remediation click-path where applicable. Call out anything skipped due to dry-run, a declined confirmation, or (Phase 12) the customer opting out of KPI customization.