@salesforce/afv-skills 1.45.0 → 1.47.0

package/skills/consumer-goods-promotion-bo-api-deploy/references/conventions-and-payload-rules.md

@@ -0,0 +1,273 @@
+# Conventions & payload rules (Promotion BO API)
+
+Load-bearing conventions and the eight cross-workflow payload rules the
+`BO_API_Step_Input_Structure__c` schema alone cannot express. The main
+`SKILL.md` references this file from Phase 5b (registering input paths) and
+Phase 6 (composing/validating smoke payloads).
+
+## CLI shape
+
+- `<alias>` — target org `sf` alias. Required.
+- `--sales-org <4-char>` — default `0001`. Must match `^[A-Z0-9]{4}$` (mirrors `TPMSetupData.validateSalesOrg`).
+- `--dry-run` — emit artifacts to `./out/`, skip destructive operations.
+- `--yes` — skip confirmation gates (for CI callers).
+- `--preset set-comment-value` / `--interview-file <path>` — bypass the interactive Phase 5 interview.
+
+## Runtime artifacts
+
+- The skill writes to `./out/` inside its own directory.
+- Rollback artifacts follow `./out/rollback-<subject>-<UTC-timestamp>.apex`.
+- Before-snapshots follow `./out/<subject>-before.<ext>`.
+
+## Sales-org partitioning (pre-parameter for every lookup)
+
+`--sales-org` is not just a filter — it is the tenancy boundary for **every
+reference lookup** the skill performs. Before any Promotion/Tactic/Product-filter
+payload is composed, every referenced entity MUST be resolved against records
+that carry the same `<prefix>__Sales_Org__c` (namespace resolved at runtime per
+`PREFIX_UNDER` from Phase 1; e.g. `cgcloud__` / `cgcloud_dev__` in installed
+subscriber orgs, or the dev-package prefix).
+
+| Reference in payload | SObject to query | Filter |
+|---|---|---|
+| `PromotionTemplate` | `<prefix>__Promotion_Template__c` | `Name = <val> AND <prefix>__Sales_Org__c = <sales-org>` |
+| `Tactics[*].TacticTemplate` | `<prefix>__Tactic_Template__c` | `Name = <val> AND <prefix>__Sales_Org__c = <sales-org>` (and linked to the chosen PromotionTemplate via `<prefix>__Promotion_Template_Tactic_Template__c`) |
+| `AnchorAccount` | `Account` | `<prefix>__ExternalId__c = <val> AND <prefix>__Sales_Org__c = <sales-org>` |
+| `ProductFilter.Criteria.Brand[*]`, `.Category[*]`, `.Subcategory[*]`, `.Flavor[*]`, `.Package[*]` | `<prefix>__Product_Attribute__c` (or Category equivalents) | `Name = <val> AND <prefix>__Sales_Org__c = <sales-org>` |
+| `ProductFilter.{Included,Excluded}Products[*]` | `Product2` | matched by external key AND `<prefix>__Sales_Org__c = <sales-org>` |
+| `PromotionAccountSet` / `AnchorAccountSet` | `<prefix>__Account_Set__c` | `Name = <val> AND <prefix>__Sales_Org__c = <sales-org>` |
+
+Fail-fast — before any REST call — if any user-supplied reference does not
+resolve inside the sales org. "Belongs to another sales org" and "does not
+exist" are the same error class for the user; report the sales org in the message.
+
+## Payload contract derivation (schema-first, before user input)
+
+Never hard-code create/update/copy payload shape. The BO API workflow steps
+themselves declare the accepted paths. Before interviewing the user or accepting
+an intent JSON, retrieve the contract from the org:
+
+```sql
+SELECT sis.<prefix>__Path__c,
+       sis.<prefix>__Required__c,
+       sis.<prefix>__Maps_To__c,
+       sis.<prefix>__Maximum_Items__c, sis.<prefix>__Minimum_Items__c,
+       sis.<prefix>__Maximum_Length__c, sis.<prefix>__Minimum_Length__c,
+       sis.<prefix>__Pattern__c,
+       sis.<prefix>__BO_API_Workflow_Step__r.Name step
+FROM <prefix>__BO_API_Step_Input_Structure__c sis
+WHERE sis.<prefix>__BO_API_Workflow_Step__c IN (
+  SELECT <prefix>__BO_API_Workflow_Step__c
+    FROM <prefix>__BO_API_Workflow_Workflow_Step__c
+   WHERE <prefix>__BO_API_Workflow__r.Name = '<workflow>'
+     AND <prefix>__BO_API_Workflow__r.<prefix>__BO_API__r.Name = '<entity>'
+     AND <prefix>__BO_API_Workflow__r.<prefix>__BO_API__r.<prefix>__Sales_Org__c = '<sales-org>'
+)
+```
+
+Merge rows across steps → the required set is the union of `Required__c = true`
+paths; the optional set is everything else. The skill's interview and
+mass-upload template are BOTH generated from this contract, per invocation. Two
+additional constraints the schema alone cannot express and that the skill must
+layer on:
+
+- **Reference-data existence and sales-org membership.** Every non-primitive value (template name, external id, category name) must resolve per the table in "Sales-org partitioning" above.
+- **Template-conditional required fields.** Some fields are required only for specific `PromotionTemplate` values (e.g. `AnchorAccount` is required for `Customer Promotion` even though the schema declares it optional). Detect these from `mapPromotionValues*` variants, `setPromotionAnchor*` variants, and by pre-flighting a validate call against the target template — do not hard-code the list; template membership can change.
+
+Where mass upload is offered, provide a CSV/JSONL template whose columns are
+exactly the union of paths from the derived contract (with `[R]` markers on
+required columns).
+
+## Promotion payload — cross-workflow rules the schema cannot express
+
+The `BO_API_Step_Input_Structure__c` contract declares WHICH keys the workflow
+accepts and which are `Required__c=true`, but eight additional constraints govern
+whether a create/update/copy/derive call will actually succeed. Enforce them
+BEFORE the REST call — otherwise the request 202s, then dies asynchronously
+inside a workflow step with a `BO_API_Transaction_Log__c.Status__c = 'Error'`.
+
+### R1. Always-required create fields (`DateFrom`, `DateThru`, `Slogan`)
+
+Beyond the schema-declared requireds, `Promotion2BoApiCoreWorkflowSteps.setPromotionDates`
+throws `PBACWS0008` when a new promotion is missing `DateFrom` or `DateThru`.
+`Slogan` is required by the CSV row `SIS-068` on `mapPromotionValues2`. All three
+are create-workflow only — update omits them.
+
+`DateThru` is NOT derivable by the framework. When user intent is "N weeks
+starting D" (e.g. "6 weeks starting 2026-08-01"), the skill MUST compute it
+client-side:
+
+```text
+DateThru = DateFrom + (duration_weeks * 7) - 1
+```
+
+Never send a `durationWeeks` — the workflow does not accept it.
+`PlacementDateFrom/OrderDateFrom/DeliveryDateFrom` (and their `-Thru` siblings)
+default to the top-level dates on new promotions; do not need to be sent.
+
+### R2. Terminal status is `Calculated`, not `Processed`
+
+`BO_API_Transaction_Log__c.Status__c` is a restricted picklist: `Initial,
+Written, ToBeCalculated, Calculated, Error`. `Processed` is NOT in the picklist
+and is never set anywhere in the codebase. The success predicate for every
+workflow (`create`/`update`/`copy`/`derive`) is `Status__c = 'Calculated'`; the
+pending predicate is `Status__c != 'Calculated' AND Status__c != 'Error'`. Any
+poll of `/status` or the transaction log MUST match on `Calculated` — matching
+on `Processed` hangs forever.
+
+### R3. ProductFilter criteria keys are level NAMES, not field API names
+
+The payload sends level NAMES verbatim as the `ProductFilter.Criteria` keys —
+`Category`, `SubCategory`, `Brand`, `Flavor`, `Package` — NOT Product2 field API
+names. The framework consults `Product_Levels_Mapping__mdt` internally to
+translate. Sending a Product2 field API name (e.g. `<prefix>__Criterion_1_Product__c`)
+as a key fails schema validation with `"Properties other than those defined were
+not expected at #.ProductFilter.Criteria.<key>"`.
+
+```json
+"ProductFilter": {
+  "Criteria": {
+    "Category": ["Snacks"],
+    "Brand":    ["YetiBar"]
+  }
+}
+```
+
+`Product_Levels_Mapping__mdt` still matters for two skill tasks:
+1. **Enumerate levels available in this sales org** — a level not present in the mapping for the sales org, and not in the fallback (`Category`, `SubCategory`, `Brand`, `Flavor`, `Package`), cannot be sent.
+2. **SOQL verification after ingest** — translate the level back to its Product2 field to build the verify SOQL.
+
+Default mapping (fallback and every seeded metadata row):
+
+| Level name (payload key) | Product2 field (verify SOQL target) |
+|---|---|
+| `Category` | `<prefix>__Criterion_1_Product__c` (invariant across every sales org) |
+| `SubCategory` | `<prefix>__Criterion_2_Product__c` |
+| `Brand` | `<prefix>__Criterion_3_Product__c` |
+| `Flavor` | `<prefix>__Criterion_4_Product__c` |
+| `Package` | `<prefix>__Criterion_5_Product__c` |
+
+Discovery SOQL:
+```sql
+SELECT <prefix>__Product_Level_Name__c, <prefix>__Product_SObject_Field__c, <prefix>__Hierarchy_Level__c
+FROM <prefix>__Product_Levels_Mapping__mdt
+WHERE <prefix>__Sales_Org__c = :salesOrg
+```
+
+### R4. Anchor account must have a `Plan` Customer Extension valid for the promotion period
+
+Promotions can only be created for accounts with `Account_Plan_Type__c = 'Plan'`
+on `Account_Extension__c` (label "Customer Extension") for the target sales org,
+with `Promotion_Valid_From__c <= DateFrom` AND `Promotion_Valid_Thru__c >=
+DateThru`. The create path validates the anchor exists in the sales org but does
+NOT enforce Plan+dates — the skill MUST pre-flight. The object API name is
+`Account_Extension__c` even though the label reads "Customer Extension"; there is
+no `Customer_Extension__c` object.
+
+```sql
+SELECT Id, <prefix>__Account__c
+  FROM <prefix>__Account_Extension__c
+ WHERE <prefix>__Account__c = :anchorId
+   AND <prefix>__Account_Plan_Type__c = 'Plan'
+   AND <prefix>__Sales_Org__c = :salesOrg
+   AND <prefix>__Promotion_Valid_From__c <= :dateFrom
+   AND <prefix>__Promotion_Valid_Thru__c >= :dateThru
+LIMIT 1
+```
+Zero rows → stop with `"Account <anchor> is not enrolled as a Plan account in sales org <salesOrg> for the period <dateFrom>..<dateThru>"`.
+
+### R5. ManualInputs KPIs are `editable` / `editable_calculated` on the template's KPI Set
+
+`ManualInputs[]` accepts only KPIs the template's `KPI_Set__c` includes, and only
+those whose `RecordType.DeveloperName` is `editable` or `editable_calculated`.
+Any other KPI is rejected by `Promotion2BoApiCoreWorkflowSteps.validateManualInputKPI`.
+Read the allowed set from the org — do not hard-code. If the template's
+`KPI_Set__c` is null, ManualInputs are silently skipped (framework logs
+`PBACWS0018`) — ask the user before proceeding.
+
+The base object is `<prefix>__KPI_Definition__c` (NOT `KPI__c`).
+`KPI_Definition__c` and `KPI_Set__c` have no `Sales_Org__c` field — filter via
+`Promotion_Template__c.Sales_Org__c`.
+
+```sql
+SELECT kd.Id, kd.Name, kd.<prefix>__Editable_Measure_Code__c,
+       kd.<prefix>__Compound_Main__c, kd.<prefix>__Editable_Fixed_Totals__c,
+       kd.<prefix>__BoM_Scope__c, kd.RecordType.DeveloperName
+FROM <prefix>__KPI_Definition__c kd
+WHERE Id IN (
+  SELECT <prefix>__KPI_Definition__c FROM <prefix>__KPI_Set_KPI_Definition__c
+  WHERE <prefix>__KPI_Set__c IN (
+    SELECT <prefix>__KPI_Set__c FROM <prefix>__Promotion_Template__c
+    WHERE Id = :promotionTemplateId AND <prefix>__Sales_Org__c = :salesOrg))
+AND RecordType.DeveloperName IN ('editable','editable_calculated')
+```
+Framework-enforced extras (fail on the REST call, not pre-flight): `editable`
+KPIs with `Editable_Fixed_Totals__c=true` are rejected; `editable_calculated`
+KPIs must have `Compound_Main__c=true` unless BoM components. The payload's
+`ManualInputs[].KPI` value is `KPI_Definition__c.Name`; the downstream measure
+code is `Editable_Measure_Code__c`.
+
+### R6. Derive / Copy required fields — read them from the workflow metadata
+
+Do not hard-code the required set for `copy` and `derive`; derive them from
+`BO_API_Step_Input_Structure__c` (`Required__c=true`) the same way as `create`,
+then layer the Apex-only preconditions:
+
+**Copy:**
+- Schema-required: `.Id` (source promotion).
+- Apex-only: source promotion's template must have `Is_Copyable__c = true`; template `Promotion_Type__c` must equal `'Promotion'`; if template `Anchor_Type__c = 'Customer'`, `.AnchorAccount` must resolve in the sales org; if `'CustomerSet'`, `.AnchorAccountSet` must resolve.
+
+**Derive:**
+- Schema-required: `.Id`, `.PromotionTemplate`, `.AnchorAccount` — all at the derive input root (`currentInput`), not nested (`PBACWS_REQUIRED_PROP_MISSING` fires against `Path__c` verbatim).
+- Apex-only: source template `Is_Derivable__c = true`; a `Promotion_Template_Hierarchy__c` row with `Usage__c='Derive'` and `Child_Promotion_Template__c` = target; target template `Promotion_Type__c = 'Promotion'`; `.AnchorAccount`/`.AnchorAccountSet` valid within the promotion date range (recurses to R4).
+
+> Note: **this skill wires only `{create, update, copy}`; `derive` is out of scope.** R6's derive detail is here for completeness / a follow-up skill.
+
+If any Apex-only precondition is not derivable from the org, treat the field as mandatory in the interview.
+
+### R7. Tactic templates must be linked to the promotion template AND share its sales org
+
+`Tactics[*].TacticTemplate` must resolve to a `Tactic_Template__c` in the target
+sales org AND be linked to the chosen `PromotionTemplate` via the
+`Promotion_Template_Tactic_Template__c` junction (no `Sales_Org__c` of its own;
+Name is auto-number `PTTT-{0000}`) — filter through both parents:
+
+```sql
+SELECT Id
+FROM <prefix>__Promotion_Template_Tactic_Template__c
+WHERE <prefix>__Promotion_Template__r.Name = :promotionTemplateName
+  AND <prefix>__Promotion_Template__r.<prefix>__Sales_Org__c = :salesOrg
+  AND <prefix>__Tactic_Template__r.Name = :tacticTemplateName
+  AND <prefix>__Tactic_Template__r.<prefix>__Sales_Org__c = :salesOrg
+LIMIT 1
+```
+Zero rows → stop with `"Tactic template <tt> is not linked to promotion template <pt> in sales org <salesOrg>"`.
+
+### R8. PromotionTemplate must be `Promotion_Type__c = 'Promotion'` — reject Sellable/Retail templates
+
+`Promotion2BoApiCoreCommon.cls:867-875` throws `CPC0009` when the resolved
+`PromotionTemplate.Promotion_Type__c != 'Promotion'`. Sellable/Retail templates
+(`New Item Introduction`, `Selectable Promotion`, `Distributor Promotion`,
+`Regional Promotion`, `Consumer Promotion`, `Campaign Promotion`) carry a
+different type and belong to the retail sellable-promotion path.
+
+On create the failure surfaces as an off-platform `WriteError` with a misleading
+message (`Invalid JSON! /productfilter must be object`, HTTP 400 from the
+Hyperforce CGCPS validator) — it blames `/productfilter` but the actual defect is
+the template type. The user-facing error does NOT name the template type, so the
+skill MUST fail-fast on template type before ingest.
+
+```sql
+SELECT Id, Name, <prefix>__Promotion_Type__c
+  FROM <prefix>__Promotion_Template__c
+ WHERE Name IN :templateNames
+   AND <prefix>__Sales_Org__c = :salesOrg
+```
+Reject any row where `Promotion_Type__c != 'Promotion'` with:
+`"Promotion template <name> has Promotion_Type__c='<type>'; this workflow only supports templates with Promotion_Type__c='Promotion'. Sellable Promotions belong to the retail path."`
+
+## Wire-format quirks
+
+- `POST /promotions/initialize` deserializes lowercase `salesorg` / `nrofitems`. Always emit lowercase.
+- `BO_API_Workflow_Workflow_Step__c.Enabled__c` is not honored at runtime. To disable a step, DELETE the junction; do not flip the boolean.
+- Success matches `Status__c = 'Calculated'` (R2). `Processed` is not a valid status; polling for it will hang.

package/skills/consumer-goods-promotion-bo-api-deploy/references/generate-and-wire.md

@@ -0,0 +1,236 @@
+# Phase 5a / 5b — Generate + deploy the Apex class, register + wire the step
+
+Detailed runbook for the two write phases. `SKILL.md` Phase 5a/5b link here.
+Both phases run only on a green Phase 4 and a confirmed Phase 5 interview.
+`PREFIX_DOT` / `PREFIX_UNDER` come from the Phase-1 namespace detection.
+
+## Phase 5a — Generate + deploy the customer's Apex class
+
+1. **Idempotency guard** — is the class name already taken?
+
+   ```bash
+   sf data query --target-org <alias> --json --query "
+     SELECT NamespacePrefix FROM ApexClass WHERE Name = '<stepName>'
+   "
+   ```
+
+   Non-empty and non-namespaced → an ApexClass by that name already exists in
+   the customer's namespace. Ask: overwrite (redeploy same name), rename the
+   interview answer, or abort. Namespaced → a *packaged* class with that name
+   (unexpected); stop and ask before overwriting anything.
+
+2. **Confirm target-field writeability.** For every entry in `outputWrites`,
+   describe the resolved field `${PREFIX_UNDER}<field>` on
+   `${PREFIX_UNDER}<entity>__c` and verify `createable=true, updateable=true`
+   for the running user. Any failure → stop, print the failing field + FLS
+   remediation.
+
+3. **Generate the Apex class from the interview.** The generator takes the
+   schema captured in the interview (Phase 5.1) and emits a namespace-agnostic
+   Callable in the same shape as the reference example
+   (`references/reference-example-set-comment-value.md`). Rules (do not deviate):
+   - Declare the class **`global`** and the `call` method **`global`** — `global with sharing class <stepName> implements Callable { global Object call(...) }`. This is REQUIRED, not stylistic: on a managed-INSTALLED org the packaged `CallableManager` resolves/invokes this subscriber class across the namespace boundary via `Type.forName`, which cannot see a `public` class — the step then fails at *runtime* with `Type "<stepName>" does not exist` and the transaction-log row lands in `Error` (the class still shows `Active`, so this is invisible until an ingest runs). `public` only works on a same-namespace source/dev org (e.g. a `cgcloud_dev` scratch org); `global` works on both. Inner exception types may stay `public`.
+   - `implements Callable`; single `Object call(String action, Map<String, Object> context)` method.
+   - Guard `action != <actionName>` with a class-specific exception.
+   - Read `context.get('currentInput')` (Map) and `context.get('currentOutput')` (SObject) — these are the keys `BoTransformationEngine` seeds (verified at `BoTransformationEngine.cls:825-864`).
+   - Compute the namespace prefix from `String.valueOf(output.getSObjectType())` at runtime (see the reference example for the exact substring logic). Never emit a compile-time `<ns>__` prefix.
+   - For each `outputWrite`, resolve the source value from `currentInput` (via the `inputPaths` map), apply any preconditions, then call `output.put(prefix + '<field>', ...)`.
+   - Return `null`.
+
+   Materialize the generated source into a **project-relative** working tree —
+   never `/tmp`. Generated deployment artifacts must stay inside the project so
+   the workflow is portable and auditable (add `./.promotion-bo-api-deploy/` to
+   `.gitignore`; it is ephemeral scratch):
+
+   ```text
+   ./.promotion-bo-api-deploy/
+     sfdx-project.json
+     force-app/main/default/classes/
+       <stepName>.cls
+       <stepName>.cls-meta.xml
+   ```
+
+   `sfdx-project.json`:
+   ```json
+   {
+     "packageDirectories": [{ "path": "force-app", "default": true }],
+     "sourceApiVersion": "60.0"
+   }
+   ```
+
+   `<stepName>.cls-meta.xml`:
+   ```xml
+   <?xml version="1.0" encoding="UTF-8"?>
+   <ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+       <apiVersion>60.0</apiVersion>
+       <status>Active</status>
+   </ApexClass>
+   ```
+
+4. **Show the user the generated class + confirm.** Print the full
+   `<stepName>.cls` body and ask "Deploy this? [y/N]". `n` → save to
+   `./.promotion-bo-api-deploy/` and exit; the user can hand-edit and re-run
+   with `--interview-file` pointing at their tweaked answers, or drop their own
+   `.cls` into the temp tree before re-invoking. `y` → deploy.
+
+5. **Deploy:**
+
+   ```bash
+   sf project deploy start \
+     --target-org <alias> \
+     --source-dir ./.promotion-bo-api-deploy/force-app \
+     --wait 10 --json
+   ```
+
+   On `--dry-run`, add `--dry-run` (fall back to `--check-only` on older CLIs).
+   Non-success → stop, print `result.details.componentFailures`.
+
+## Phase 5b — Register + wire the step (into the user-chosen workflows)
+
+Insert one `${PREFIX_UNDER}BO_API_Workflow_Step__c` record for the generated
+class, then one `${PREFIX_UNDER}BO_API_Workflow_Workflow_Step__c` junction per
+**`workflows`** entry from the interview (subset of `{create, update, copy}` —
+never assume all three).
+
+Rationale (do not skip):
+- Store the **bare** class name (`<stepName>`) in `Classname__c`. The packaged `CallableManager` resolves it against the caller's namespace, so `Classname__c` never carries the `cgcloud`/`cgcloud_dev` prefix. (Every shipped seed row uses a bare name.)
+- Compute `Sort__c` per workflow. If the interview supplied a `sortAfter` step name, resolve its junction row for the target workflow and use `sortAfter.Sort__c + 5`. Otherwise use `max(existing sort in that workflow) + 10`.
+- `derive` is never wired by this skill. If the user selected `derive`, print "the `derive` workflow is out of scope for this skill — a follow-up skill will handle it" and drop it.
+
+Do the whole thing in a single anonymous-Apex transaction to avoid partial
+state. Placeholders in `<...>` come from the Phase 5 interview:
+
+```apex
+// ./.promotion-bo-api-deploy/register-step.apex
+String salesOrg = '<salesOrg>';
+String stepName = '<stepName>';           // e.g. 'SetCommentValue'
+String actionName = '<actionName>';       // e.g. 'setCommentValue'
+String entityName = '<entity>';           // e.g. 'Tactic'
+String description = '<description>';
+List<String> workflows = new List<String>{ <workflows-as-quoted-csv> };  // e.g. 'create','update','copy'
+List<String> inputPaths = new List<String>{ <inputPaths-as-quoted-csv> };  // e.g. '.Comment' from the interview inputPaths
+String inputPathType = '<inputPathType>';  // one of: String, Array, Boolean, Number, Object (SIS RecordType)
+
+// Query the entity id (packaged)
+List<${PREFIX_DOT}BO_API_Entity__c> entity = [
+  SELECT Id FROM ${PREFIX_DOT}BO_API_Entity__c
+   WHERE Name = :entityName
+   LIMIT 1
+];
+if (entity.isEmpty()) {
+  throw new CGCloudException(entityName + ' BO API entity not found for sales org ' + salesOrg);
+}
+
+// Upsert the step (Unique_Key__c is a writable external id — caller must set it)
+${PREFIX_DOT}BO_API_Workflow_Step__c step = new ${PREFIX_DOT}BO_API_Workflow_Step__c(
+  Name = stepName,
+  ${PREFIX_DOT}Classname__c = stepName,
+  ${PREFIX_DOT}Method__c = actionName,
+  ${PREFIX_DOT}Sales_Org__c = salesOrg,
+  ${PREFIX_DOT}Entity__c = entity[0].Id,
+  ${PREFIX_DOT}Description__c = description,
+  ${PREFIX_DOT}Unique_Key__c = stepName + salesOrg
+);
+upsert step ${PREFIX_DOT}Unique_Key__c;
+
+// Ensure entity is in each workflow's WE list before inserting junctions
+// (validation rule requires it — copy fails otherwise)
+Map<String, Id> wfByName = new Map<String, Id>();
+for (${PREFIX_DOT}BO_API_Workflow__c wf : [
+  SELECT Id, Name FROM ${PREFIX_DOT}BO_API_Workflow__c
+   WHERE Name IN :workflows
+     AND ${PREFIX_DOT}BO_API__r.Name = 'Promotion'
+     AND ${PREFIX_DOT}BO_API__r.${PREFIX_DOT}Sales_Org__c = :salesOrg
+]) {
+  wfByName.put(wf.Name, wf.Id);
+}
+for (String wf : workflows) {
+  if (!wfByName.containsKey(wf)) {
+    throw new CGCloudException('BO API workflow "' + wf + '" not found for sales org ' + salesOrg);
+  }
+  Integer existing = [
+    SELECT COUNT() FROM ${PREFIX_DOT}BO_API_Workflow_Entity__c
+     WHERE ${PREFIX_DOT}BO_API_Workflow__c = :wfByName.get(wf)
+       AND ${PREFIX_DOT}BO_API_Entity__c = :entity[0].Id
+  ];
+  if (existing == 0) {
+    insert new ${PREFIX_DOT}BO_API_Workflow_Entity__c(
+      ${PREFIX_DOT}BO_API_Workflow__c = wfByName.get(wf),
+      ${PREFIX_DOT}BO_API_Entity__c = entity[0].Id
+    );
+  }
+}
+
+// Wire junctions into the interview's chosen workflows only
+for (String wf : workflows) {
+  AggregateResult ar = [
+    SELECT MAX(${PREFIX_DOT}Sort__c) maxSort
+      FROM ${PREFIX_DOT}BO_API_Workflow_Workflow_Step__c
+     WHERE ${PREFIX_DOT}BO_API_Workflow__c = :wfByName.get(wf)
+  ];
+  Decimal maxSort = (Decimal) ar.get('maxSort');
+  Decimal nextSort = (maxSort == null ? 10 : maxSort + 10);
+  // If interview supplied sortAfter, resolve that here and use sortAfter.Sort__c + 5 instead.
+
+  ${PREFIX_DOT}BO_API_Workflow_Workflow_Step__c junction = new ${PREFIX_DOT}BO_API_Workflow_Workflow_Step__c(
+    ${PREFIX_DOT}BO_API_Workflow__c = wfByName.get(wf),
+    ${PREFIX_DOT}BO_API_Workflow_Step__c = step.Id,
+    ${PREFIX_DOT}Enabled__c = true,
+    ${PREFIX_DOT}Sort__c = nextSort,
+    ${PREFIX_DOT}Unique_Key__c = String.valueOf(wfByName.get(wf)) + stepName + salesOrg
+  );
+  upsert junction ${PREFIX_DOT}Unique_Key__c;
+}
+
+// Register accepted input paths (SIS rows). Required — without these,
+// the payload validator rejects with "Properties other than those defined
+// were not expected at #.<path>". SIS has no external id → insert with
+// pre-check. SIS uses RecordType to declare the JSON type (String, Array,
+// Boolean, Number, Object) — a missing RecordTypeId defaults to Array,
+// which produces "Expected List<Object>" at runtime.
+Id sisRecordTypeId = [
+  SELECT Id FROM RecordType
+   WHERE SobjectType = '${PREFIX_UNDER}BO_API_Step_Input_Structure__c'
+     AND DeveloperName = :inputPathType
+   LIMIT 1
+].Id;
+Set<String> existingPaths = new Set<String>();
+for (${PREFIX_DOT}BO_API_Step_Input_Structure__c s : [
+  SELECT ${PREFIX_DOT}Path__c FROM ${PREFIX_DOT}BO_API_Step_Input_Structure__c
+   WHERE ${PREFIX_DOT}BO_API_Workflow_Step__c = :step.Id
+]) {
+  existingPaths.add(String.valueOf(s.get('${PREFIX_DOT}Path__c')));
+}
+List<${PREFIX_DOT}BO_API_Step_Input_Structure__c> sisRows =
+  new List<${PREFIX_DOT}BO_API_Step_Input_Structure__c>();
+for (String inputPath : inputPaths) {
+  if (existingPaths.contains(inputPath)) continue;
+  sisRows.add(new ${PREFIX_DOT}BO_API_Step_Input_Structure__c(
+    ${PREFIX_DOT}BO_API_Workflow_Step__c = step.Id,
+    ${PREFIX_DOT}Path__c = inputPath,
+    RecordTypeId = sisRecordTypeId
+  ));
+}
+if (!sisRows.isEmpty()) insert sisRows;
+```
+
+`PREFIX_DOT` above is the placeholder the skill textually replaces before
+writing the file to `./.promotion-bo-api-deploy/`. In the final on-disk file every `${PREFIX_DOT}`
+becomes either `cgcloud.` / `cgcloud_dev.` / empty, and every
+`${PREFIX_DOT}Sales_Org__c`-style token becomes `cgcloud__Sales_Org__c` /
+`cgcloud_dev__Sales_Org__c` / bare.
+
+Run:
+
+```bash
+sf apex run --target-org <alias> --file ./.promotion-bo-api-deploy/register-step.apex
+```
+
+Non-zero exit or non-`Compiled: true, Success: true` → stop, print output.
+
+Re-run behaviour: both upserts are keyed on `Unique_Key__c` (writable external
+id set from stable interview inputs), so a second run of Phase 5b is a no-op if
+the answers are unchanged. Reducing the `workflows` set across runs does **not**
+retire junctions the previous run created — the skill only adds. Print a warning
+if Phase 2 shows a junction for `<stepName>` on a workflow no longer in the
+interview list; a human should decide whether to disable it.

package/skills/consumer-goods-promotion-bo-api-deploy/references/reference-example-set-comment-value.md

@@ -0,0 +1,132 @@
+# Reference example — `SetCommentValue`
+
+One worked customization the skill ships as a preset. It exists so a reviewer can
+see a complete, verified answer to the Phase 5 interview. The skill does not
+deploy it by default — the customer picks it explicitly via
+`--preset set-comment-value` or by saying "use the SetCommentValue reference"
+during the interview. All files below ship under
+`assets/set-comment-value/`.
+
+## Interview answers
+
+```json
+{
+  "stepName": "SetCommentValue",
+  "entity": "Tactic",
+  "workflows": ["create", "update", "copy"],
+  "actionName": "setCommentValue",
+  "inputPaths": ["Comment"],
+  "outputWrites": [
+    { "field": "Comment__c", "source": "Comment" }
+  ],
+  "description": "Copies the tactic input Comment to Tactic.Comment__c.",
+  "preconditions": null,
+  "sortAfter": null
+}
+```
+
+Ships at `assets/set-comment-value/interview-answers.json`.
+
+## Generated class
+
+The class is namespace-agnostic — it works whether the target org has `cgcloud`,
+`cgcloud_dev`, or no prefix, because it derives the Tactic namespace from the
+passed SObject at runtime and never types `<ns>__Tactic__c` or `<ns>__Comment__c`
+at compile time. Context-key names (`currentInput`, `currentOutput`) are the ones
+the packaged `BoTransformationEngine` seeds — verified at lines 825–864 of
+`BoTransformationEngine.cls`. Ships at
+`assets/set-comment-value/SetCommentValue.cls`.
+
+```apex
+/**
+ * Custom BO API Workflow Step: lifts a top-level `Comment` value out of
+ * the ingest tactic input onto Tactic.Comment__c.
+ *
+ * Registered against the `Tactic` BO API entity and wired into the
+ * `create`, `update`, and `copy` workflows.
+ */
+global with sharing class SetCommentValue implements Callable {
+
+  public class SetCommentValueException extends Exception {}
+
+  // global (not public): the packaged CallableManager must resolve/invoke this
+  // subscriber Callable across the namespace boundary on a managed-installed org
+  // (a public class fails at runtime with `Type "SetCommentValue" does not exist`).
+  global Object call(String action, Map<String, Object> context) {
+    if (action != 'setCommentValue') {
+      throw new SetCommentValueException('Unsupported action: ' + action);
+    }
+    if (context == null) {
+      throw new SetCommentValueException('null context');
+    }
+
+    Object rawInput = context.get('currentInput');
+    Object rawOutput = context.get('currentOutput');
+
+    if (!(rawInput instanceof Map<String, Object>)) {
+      return null;
+    }
+    Map<String, Object> tacticInput = (Map<String, Object>) rawInput;
+    Object commentValue = tacticInput.get('Comment');
+    if (commentValue == null) {
+      return null;
+    }
+
+    // The engine wraps Tactic__c in TPM_Promotion.TacticRecord (see
+    // BoTransformationEngineEntityTree.generateObject:696 —
+    //   promo.addTactic(new Tactic__c()) returns a TacticRecord wrapper).
+    // Unwrap to the underlying SObject via getRecord() before writing;
+    // a raw SObject cast fails silently and the write never persists.
+    SObject tactic;
+    if (rawOutput instanceof SObject) {
+      tactic = (SObject) rawOutput;
+    } else if (rawOutput instanceof TPM_Promotion.Record) {
+      tactic = ((TPM_Promotion.Record) rawOutput).getRecord();
+    } else {
+      return null;
+    }
+
+    String tacticType = String.valueOf(tactic.getSObjectType());
+    String prefix = '';
+    if (tacticType.contains('__') && tacticType.endsWith('__c')) {
+      Integer firstUnderscoreUnderscore = tacticType.indexOf('__');
+      Integer lastUnderscoreUnderscore = tacticType.lastIndexOf('__');
+      if (firstUnderscoreUnderscore < lastUnderscoreUnderscore) {
+        prefix = tacticType.substring(0, firstUnderscoreUnderscore) + '__';
+      }
+    }
+
+    tactic.put(prefix + 'Comment__c', String.valueOf(commentValue));
+    return null;
+  }
+}
+```
+
+## Class metadata
+
+Ships at `assets/set-comment-value/SetCommentValue.cls-meta.xml`.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>60.0</apiVersion>
+    <status>Active</status>
+</ApexClass>
+```
+
+## Reference payloads
+
+Live at `assets/set-comment-value/payloads/`:
+- `create.json` — sets `Comment` on a new promotion's tactic.
+- `update.json` — updates the tactic's `Comment`.
+- `copy.json` — copies the source promotion; expects the tactic's `Comment` to be carried across.
+
+Each carries the `REPLACED-AT-RUNTIME` marker for `importId` (and, for
+`update`/`copy`, marker ids for the promotion + tactic captured from the
+preceding response).
+
+## Expected write
+
+`Tactic__c.Comment__c` on the created / updated / copied promotion's tactic must
+equal the `Comment` value from the corresponding payload — this is the
+interview's single `outputWrites` assertion.