@salesforce/afv-skills 1.66.0 → 1.67.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.66.0",
+  "version": "1.67.0",
   "description": "Salesforce's curated collection of agent skills for building applications. Optimized for Agentforce Vibes, compatible with all AI tools.",
   "license": "Apache-2.0",
   "files": [
@@ -12,9 +12,7 @@
   },
   "devDependencies": {
     "@salesforce/ui-bundle-template-app-react-sample-b2e": "^12.4.4",
-    "@salesforce/ui-bundle-template-app-react-sample-b2x": "^12.4.4",
-    "@salesforce/webapp-template-app-react-sample-b2e-experimental": "^1.117.1",
-    "@salesforce/webapp-template-app-react-sample-b2x-experimental": "^1.117.1"
+    "@salesforce/ui-bundle-template-app-react-sample-b2x": "^12.4.4"
   },
   "scripts": {
     "sync-react-b2e-sample": "node scripts/sync-react-b2e-sample.js",

package/skills/agentforce-offline-experimentation-run/SKILL.md

@@ -4,20 +4,20 @@ description: "Use this skill when users want to execute this workflow when a use
 metadata:
   relatedSkills:
   - dx-apexguru-scan
-  version: '1.0'
+  version: "1.0"
   cliTools:
   - tool:
-    - curl
-    semver: '>=7.0'
+    - "curl"
+    semver: ">=7.0"
   - tool:
-    - jq
-    semver: '>=1.6'
+    - "jq"
+    semver: ">=1.6"
   - tool:
-    - python3
-    semver: '>=3.8'
+    - "python3"
+    semver: ">=3.8"
   - tool:
-    - sf
-    semver: '>=2.0.0'
+    - "sf"
+    semver: ">=2.0.0"
 ---
 
 # Managing Agentforce Offline Experimentation
@@ -28,7 +28,7 @@ Execute this workflow when a user wants to test how a different LLM model would
 
 ## Workflow
 
-discover-data-space → verify-stdm-availability → discover-agents → resolve-agent-label → list-available-models (if user needs help choosing) → find-sessions → get-conversation-details → get-llm-step-details → obtain-sfap-token → replay-turn-prompts → [score-exact-matches, judge-function-args, judge-text-responses] → generate-csv-report → generate-html-report.
+discover-data-space → verify-stdm-availability → discover-agents → list-available-models (if user needs help choosing) → find-sessions → get-conversation-details → get-llm-step-details → obtain-sfap-token → replay-turn-prompts → [score-exact-matches, judge-function-args, judge-text-responses] → generate-csv-report → generate-html-report.
 WORKFLOW GATE: Do not proceed past Phase 0 until org alias (auto-discover from authenticated orgs), agent API name (auto-discover from STDM), and target model ID (ask user) are all confirmed.
 SFAP JWT expires after ~2 hours. For 20+ session replays, refresh the token between batches. Each SFAP replay call takes ~1-3 seconds; keep under 20 sessions for reasonable wall-clock time (~10-30 minutes).
 The scoring and judging steps (Phase 3) can run in parallel once replay completes. Exact-match scoring is instant; LLM judge calls add ~1-2 seconds per turn.
@@ -38,7 +38,6 @@ The scoring and judging steps (Phase 3) can run in parallel once replay complete
 **Preconditions:**
 
 - Data Cloud is provisioned and enabled in the org (check: `DataCloudProvisioned`)
-- Agentforce Activity data streaming is active in Data Cloud (check: `AgentforceActivityStream`)
 - Einstein LLM / GenAI Gateway is configured in the org (check: `EinsteinLlmEnabled`)
 - User has an authenticated session to the target org (check: `OrgAuthenticated`)
 
@@ -53,7 +52,6 @@ Operations grouped by purpose. Use these as the building blocks for the workflow
 | `discover-data-space` | read | implemented | `getDataSpaces` | — |
 | `verify-stdm-availability` | validate | implemented | `queryCdpAnsiSqlV2` | `discover-data-space` |
 | `discover-agents` | read | implemented | `queryCdpAnsiSqlV2` | `verify-stdm-availability` |
-| `resolve-agent-label` | read | implemented | `queryGenAiPlannerDefinition` | `discover-agents` |
 | `list-available-models` | read | implemented | `queryAiModel` | — |
 | `find-sessions` | read | implemented | `queryCdpAnsiSqlV2` | `verify-stdm-availability`, `discover-agents` |
 | `get-conversation-details` | read | proposed | `queryCdpAnsiSqlV2` | `find-sessions` |
@@ -73,7 +71,6 @@ graph TD
   discover_data_space["discover-data-space (read)"]
   verify_stdm_availability["verify-stdm-availability (validate)"]
   discover_agents["discover-agents (read)"]
-  resolve_agent_label["resolve-agent-label (read)"]
   list_available_models["list-available-models (read)"]
   find_sessions["find-sessions (read)"]
   get_conversation_details["get-conversation-details (read)"]
@@ -87,7 +84,6 @@ graph TD
   generate_html_report["generate-html-report (write)"]
   discover_data_space --> verify_stdm_availability
   verify_stdm_availability --> discover_agents
-  discover_agents --> resolve_agent_label
   verify_stdm_availability --> find_sessions
   discover_agents --> find_sessions
   find_sessions --> get_conversation_details
@@ -115,24 +111,12 @@ Discover active Data Cloud data spaces in the org
 
 #### `discover-agents`
 
-Query STDM for distinct Agentforce agent API names that have session traces
+Query STDM for distinct agent + version combinations that have session traces
 
 **Call:** `queryCdpAnsiSqlV2`   — status: `implemented`
 
 **Depends on:** `verify-stdm-availability`
 
-#### `resolve-agent-label`
-
-Enrich the selected agent API name with a human-readable MasterLabel
-
-**Call:** `queryGenAiPlannerDefinition`   — status: `implemented`
-
-**Inputs:**
-
-- `agent_api_name` *(`String`)* — Agent API name selected in discover-agents
-
-**Depends on:** `discover-agents`
-
 #### `list-available-models`
 
 List Einstein LLM models configured in the org to help the user choose a target model
@@ -141,13 +125,14 @@ List Einstein LLM models configured in the org to help the user choose a target
 
 #### `find-sessions`
 
-Find recent Agentforce sessions in STDM filtered by agent API name and date range
+Find recent Agentforce sessions in STDM filtered by agent API name, version, and date range
 
 **Call:** `queryCdpAnsiSqlV2`   — status: `implemented`
 
 **Inputs:**
 
 - `agent_api_name` *(`String`)* — Agent API name selected in discover-agents
+- `agent_version_api_name` *(`String`)* — Agent version API name selected in discover-agents
 - `start_date` *(`String`)*
 - `end_date` *(`String`)*
 - `max_sessions` *(`Integer`)*

package/skills/commerce-react-storefront-create/SKILL.md

@@ -0,0 +1,350 @@
+---
+name: commerce-react-storefront-create
+description: "Stand up the commerce-b2b-headless reference React storefront in a Salesforce B2B Commerce org, end to end — discover the org's WebStores, pick one, fill the four org-specific values (WebStore Id, BuyerGroup Id, buyer permission set group, Vite org alias), build + deploy the UI Bundle, assign the site guest user the auth permission set, and hand back the live Experience Cloud storefront URL. Use whenever the user says \"create a react storefront in my org\", \"set up the headless B2B storefront\", \"deploy commerce-b2b-headless\", \"stand up a React storefront for <org-alias>\", \"get me a hosted headless commerce storefront\", or points at a cloned commerce-b2b-headless repo and wants it running against their org."
+metadata:
+  relatedSkills:
+  - experience-ui-bundle-deploy
+  version: "1.0"
+  minApiVersion: "65.0"
+  domains:
+  - "Commerce"
+  - "Experience"
+  cliTools:
+  - tool:
+    - "git"
+    semver: ">=2.0"
+  - tool:
+    - "jq"
+    semver: ">=1.6.0"
+  - tool:
+    - "npm"
+    semver: ">=8.0.0"
+  - tool:
+    - "sf"
+    semver: ">=2.130.0"
+---
+
+# create-react-storefront
+
+## What this does
+
+Deploys the **commerce-b2b-headless** reference React storefront (a React 19 + Vite `UIBundle`
+served from the Experience Cloud Site Container) into a user's B2B Commerce org and returns the
+hosted storefront URL. The repo is a *reference implementation* — it ships four org-specific
+values as `<…_Placeholder>` strings that throw at runtime until replaced. This skill's whole job
+is to resolve those four values against the target org, then drive build → deploy → guest-user
+entitlement so the storefront actually renders.
+
+The repo's `scripts/org-setup.mjs` (`npm run setup`) automates login → build → deploy → permset →
+dev-server, but it does **not** discover the WebStore, replace the placeholders, or entitle the
+site's guest user (the README's own "Limitations" say there is no auto-discovery). Those
+gaps are exactly the manual work below — do them, and the deploy is reliable.
+
+**Requires:** Node 22+, `sf` CLI 2.130+, and a target org with B2B Commerce + Multi-framework React
+enabled (API version `67.0+`). Only work against orgs the user owns or is authorized to modify — deploy,
+Apex edits, and permission-set assignment are real, side-effecting writes.
+
+## Fixed facts about the repo (don't re-derive these)
+
+| Thing | Value |
+|---|---|
+| Repo clone URL | `https://github.com/trailheadapps/commerce-b2b-headless.git` (ask for an existing clone first; a new clone goes to a user-confirmed path under the cwd — Step 3) |
+| UI Bundle dir (`$BUNDLE`) | `force-app/main/default/uiBundles/commerceb2bheadless` |
+| WebStore config file | `$BUNDLE/src/config/commerce.ts` |
+| Registration Apex | `UIBundleRegistration.cls` (in the repo's Apex classes folder) |
+| Vite config | `$BUNDLE/vite.config.ts` |
+| Auth permission set | `UIBundleApexAccess` (grants the 6 auth Apex classes) |
+| Site name | `commerceb2bheadless` — also the storefront URL path: `https://<site-domain>/commerceb2bheadless` |
+| Connect `urlPathPrefix` | `commerceb2bheadlessvforcesite` (internal match key for Step 7 — **not** the URL path) |
+| Default API version | `v67.0` (leave unless the org runs a different version) |
+
+## The four values you must set
+
+Everything else in the repo is portable. These four are environment-specific — resolve each against
+the target org, then write it into the file. Steps 4a–4d below do this.
+
+| # | Value | File / symbol | Prefix |
+|---|---|---|---|
+| 1 | WebStore Id | `commerce.ts` → `WEBSTORE_ID` | `0ZE` |
+| 2 | Default BuyerGroup Id | `UIBundleRegistration.cls` → `DEFAULT_BUYER_GROUP_ID` | `0ZI` |
+| 3 | Buyer permission set group | `UIBundleRegistration.cls` → `BUYER_PERMISSION_SET_GROUP` (DeveloperName) | — |
+| 4 | Vite org alias (optional) | `vite.config.ts` → `salesforce({ orgAlias: '…' })` | — |
+
+---
+
+## Workflow
+
+Narrow with `sf` queries before you ask the user anything, and don't ask what a query can answer.
+Two choices are always the user's to make, even when there is only one option: **which store**
+(Step 2) and **where the repo lives** (Step 3). Confirm the plan (which org, which store, what will
+be written and deployed) before the first write.
+
+### Step 1 — Resolve the target org
+
+If the user gave an org alias, use it. Otherwise list what's connected and ask which one:
+
+```bash
+sf org list --json | jq -r '.result.nonScratchOrgs[]?.alias, .result.scratchOrgs[]?.alias'
+```
+
+Confirm it's reachable: `sf org display --target-org <alias>`. If not connected, log in:
+`sf org login web --alias <alias> --instance-url https://<my-domain>.my.salesforce.com`.
+
+### Step 2 — Discover the org's WebStores, let the user pick
+
+```bash
+sf data query --target-org <alias> \
+  --query "SELECT Id, Name, Type FROM WebStore WHERE Type = 'B2B' ORDER BY Name"
+```
+
+The storefront is B2B-only, so list only `Type = 'B2B'` stores. **Always ask the user which store
+to deploy against — show every B2B store by Name and let them choose, even when there is only
+one. Never pick a store on the user's behalf**, and don't fold the choice into a later plan
+confirmation: the store decides which catalog, buyer groups, and pricing the deployed storefront
+serves. Capture the chosen store's `Id` (`0ZE…`); this is **value #1** and also scopes the
+BuyerGroup lookup in Step 4b. If the query returns nothing, the org has no B2B store provisioned —
+stop and point the user at the `b2b-commerce-org-setup` plugin to create one first.
+
+### Step 3 — Ask where the repo is, or clone it
+
+**Ask the user first** — don't probe default locations or assume a path: do they already have a
+clone of `commerce-b2b-headless` (and where is it), or should you clone it from
+`https://github.com/trailheadapps/commerce-b2b-headless.git`?
+
+**Existing clone** — set `$REPO` to the path the user gives, then verify it's the right repo:
+
+```bash
+ls "$REPO/README.md" "$REPO/force-app/main/default/uiBundles/commerceb2bheadless" >/dev/null && echo OK
+```
+
+If the check fails, tell the user what's missing and ask again — don't switch to cloning unasked.
+
+**Clone** — the clone goes inside the current working directory. Check that directory's structure
+first, so the clone doesn't silently land inside another git repo or on top of an existing folder:
+
+```bash
+pwd && ls -A
+git rev-parse --show-toplevel 2>/dev/null   # prints a path ⇒ cwd is inside another git repo
+ls -d commerce-b2b-headless 2>/dev/null     # prints a name ⇒ the target folder already exists
+```
+
+Propose `$(pwd)/commerce-b2b-headless` as the clone path and call out anything the check surfaced
+(cwd is inside another repo; the folder already exists — offer to use it as the existing clone).
+If the cwd looks like the wrong place, ask the user for a path instead of proposing one. Either
+way, **wait for the user to confirm the path or give their own**. Only then clone and verify:
+
+```bash
+git clone https://github.com/trailheadapps/commerce-b2b-headless.git "<confirmed-path>"
+ls "<confirmed-path>/force-app/main/default/uiBundles/commerceb2bheadless" >/dev/null && echo OK
+```
+
+If the clone fails with "Repository not found" or an auth prompt, the user's GitHub account can't
+see the repo — don't stop; ask for a URL they can reach (e.g. their fork) or an existing local
+clone, and continue from there. Set `$REPO` to the confirmed path.
+
+Either way, the repo is a **reference implementation you adapt**, not a drop-in — the placeholder
+edits below are mandatory. Skim `$REPO/README.md` to
+confirm you're on a compatible version if anything looks different from the Fixed-facts table.
+
+### Step 4 — Fill the four org-specific values
+
+Use `Edit` to replace each placeholder in place. Do **not** deploy with any `<…Placeholder>` string
+still present — the app throws at runtime and buyers hit `INSUFFICIENT_ACCESS`.
+
+**4a — WebStore Id** → `$BUNDLE/src/config/commerce.ts`
+Replace `WEBSTORE_ID: "<Webstore_Id_Placeholder>"` with the `0ZE…` Id from Step 2.
+
+**4b — Default BuyerGroup Id** → `UIBundleRegistration.cls` `DEFAULT_BUYER_GROUP_ID`
+Prefer the BuyerGroup actually bound to the chosen store; fall back to listing all:
+
+```bash
+# Preferred — the BuyerGroup(s) entitled to this store:
+sf data query --target-org <alias> \
+  --query "SELECT BuyerGroupId, BuyerGroup.Name FROM WebStoreBuyerGroup WHERE WebStoreId = '<0ZE…>'"
+# Fallback — all BuyerGroups:
+sf data query --target-org <alias> --query "SELECT Id, Name FROM BuyerGroup"
+```
+
+If more than one, show the names and let the user pick. Replace `<Buyer_Group_Id_Placeholder>` with
+the `0ZI…` Id. New self-registered buyers get enrolled here so the store entitlement applies.
+
+**4c — Buyer permission set group** → `UIBundleRegistration.cls` `BUYER_PERMISSION_SET_GROUP`
+
+```bash
+sf data query --target-org <alias> \
+  --query "SELECT Id, DeveloperName, MasterLabel FROM PermissionSetGroup ORDER BY DeveloperName"
+```
+
+This must match the PSG the store hands buyers at **Commerce App → your store → Buyer Access →
+Self-Registration**. Show the list, let the user confirm which one, and replace
+`<Buyer_permission_set_group>` with its **DeveloperName**. Wrong/missing group ⇒ registration
+succeeds but order placement fails with `INSUFFICIENT_ACCESS`.
+
+**4d — Vite org alias (optional but recommended)** → `$BUNDLE/vite.config.ts`
+If the machine has more than one org, pin the build to this one so the SDK's CSRF endpoint matches
+the org's API version. Change `salesforce()` to `salesforce({ orgAlias: '<alias>' })`. Skipping it
+falls back to `65.0`, which mismatches newer orgs and 401s every authenticated request.
+
+### Step 5 — Build the UI Bundle, then hand off the deploy
+
+The `dist/` is what gets shipped, and the WebStore Id (Step 4a) is baked into it at build time. Build from
+inside the bundle, deleting any existing `dist/` first — if the build fails partway, a leftover
+`dist/` from an earlier build (old or placeholder values baked in) would otherwise deploy silently.
+Confirm the chosen WebStore Id made it into the bundle before deploying:
+
+```bash
+cd $REPO && npm install
+cd $BUNDLE && npm install && rm -rf dist && npm run build   # tsc -b && vite build → fresh dist/
+grep -l '<0ZE…>' dist/assets/*.js >/dev/null && echo "WebStore Id baked"
+```
+
+**Before the deploy, flag the guest Chatter setting.** The repo's metadata is a demo-org
+configuration: `force-app/main/default/networks/commerceb2bheadless.network-meta.xml` ships
+`<enableGuestChatter>true</enableGuestChatter>`, which exposes Chatter to unauthenticated guest
+users. Tell the user before deploying and offer to set it to `false`; change it only if they agree.
+On a production org (or if the user isn't sure), don't deploy until they confirm they've reviewed
+the README's "Review all org, site & network settings before production" section, which lists the
+other network, site, profile, and permission-set flags to check.
+
+#### Deploy — delegate
+
+```yaml
+id: deploy-source
+purpose: delegate
+delegates_to: experience-sites-ui-framework/experience-ui-bundle-deploy
+```
+
+The shared `experience-ui-bundle-deploy` skill owns UI Bundle deploys, so this skill keeps no deploy
+recipe of its own. Use the installed skill if this client has it; otherwise `describe`
+`experience-ui-bundle-deploy` and follow its served guidance — its helper scripts, including the
+source-root resolver, are served with it. Point it at `$REPO` as the project and `<alias>` as the
+target org, and run **only its "Deploy metadata" step** (its org-auth precondition no-ops, since
+Step 1 already connected the org). Let it resolve the source root itself. The reference repo ships
+no `org-setup.config.json`, so that step's self-registration pre-check doesn't apply.
+
+Tell the user which of its other steps you are not running, and why: its build (done above, with
+the stale-`dist/` delete it lacks), and its permission-set, role, self-registration, social-login,
+data-import, and GraphQL steps. Step 6 here entitles the guest user, and the storefront needs
+nothing else from that sequence.
+
+The deploy ships the Apex, the UIBundle (with the fresh `dist/`), the Site/Network/digitalExperiences,
+the `UIBundleApexAccess` permission set, and the buyer profile in one shot. Only if neither the
+installed skill nor a `describe` of it is available, report the deploy handoff as blocked. Tell the
+user it needs `experience-ui-bundle-deploy`, or offer the One-command alternative below as their
+choice — don't improvise a deploy.
+
+### Step 6 — Entitle the site's guest user (auth permission set)
+
+The app puts every storefront route — home, category, search, product, cart, checkout, orders,
+profile — behind login: an anonymous visitor is redirected to `/login`. So the site's **guest user**
+only ever serves the login / register / forgot-password / reset-password pages, and the one thing it
+needs is `UIBundleApexAccess` for the auth Apex classes. Find the guest user and the permset:
+
+```bash
+sf data query --target-org <alias> \
+  --query "SELECT Id, Name, GuestUserId FROM Site WHERE Name = 'commerceb2bheadless'"
+sf data query --target-org <alias> \
+  --query "SELECT Id FROM PermissionSet WHERE Name = 'UIBundleApexAccess'"
+```
+
+Assign it (without it, `/login` 403s "no access to UIBundleLogin"):
+
+```bash
+sf data create record --target-org <alias> --sobject PermissionSetAssignment \
+  --values "AssigneeId=<GuestUserId> PermissionSetId=<UIBundleApexAccessId>"
+```
+
+A `DUPLICATE_VALUE` error means the assignment already exists from an earlier run — treat it as done.
+Either way, confirm it landed (expect one row; zero means redo the assignment):
+
+```bash
+sf data query --target-org <alias> \
+  --query "SELECT Id FROM PermissionSetAssignment WHERE AssigneeId = '<GuestUserId>' AND PermissionSet.Name = 'UIBundleApexAccess'"
+```
+
+**Don't give the guest user a commerce permission set** — for example, by mirroring an LWR store
+guest's permset. Anonymous browsing isn't reachable in this app, so there's nothing for it to
+unlock (and an LWR store's guest often holds no such permset). If the
+user later removes the login guard to allow guest browsing, B2B guest access is configured on the
+store — `WebStore.OptionsGuestBrowsingEnabled`, the guest buyer profile, and a guest buyer group (the
+`merchant-storefront-guest-access` skill) — and the WebStore likely also needs binding to the
+headless site's Network (`WebStoreNetwork`). That path is unverified for this app, so flag it rather
+than attempt it.
+
+### Step 7 — Resolve and hand back the hosted storefront URL
+
+The app is served at `https://<site-domain>/commerceb2bheadless`. Get the authoritative live URL from
+the Connect communities endpoint, matching on the site's internal `urlPathPrefix` (which differs from
+the URL path):
+
+```bash
+sf api request rest '/services/data/v67.0/connect/communities' --target-org <alias> \
+  | jq -r '.communities[] | select(.urlPathPrefix=="commerceb2bheadlessvforcesite") | "\(.name)\t\(.status)\t\(.siteUrl)"'
+```
+
+Report the `siteUrl` as **"here is your hosted React Storefront"**. If `status` is not `Live`, the
+site needs publishing — direct the user to **Setup → Digital Experiences → All Sites →
+commerceb2bheadless → Publish** (Experience Builder), then re-fetch the URL. If the endpoint returns
+nothing, construct the fallback `https://<my-domain>.my.site.com/commerceb2bheadless` — the path is
+the site name, not the `vforcesite` prefix. Get `<my-domain>` from `sf org display`'s instance URL;
+non-production instances use a different site-domain suffix, so tell the user to verify the URL in
+All Sites.
+
+---
+
+## One-command alternative
+
+If the four values are already set (Step 4 done), the repo's own orchestrator does build → deploy →
+permset in one go:
+
+```bash
+cd $REPO && npm run setup -- --target-org <alias> --skip-dev --skip-data
+```
+
+Caveats — it does **not** replace the placeholders and it assigns `UIBundleApexAccess` to the
+**current user**, not the guest user, so you **still** run Step 4 before it and Step 6 (the guest
+assignment) after it. Drop `--skip-dev` only if the user wants the local Vite dev server
+(`localhost:5173`) instead of / in addition to the hosted site. If the bundle has no GraphQL
+codegen wired, add `--skip-graphql`.
+
+## Troubleshooting (from the repo README)
+
+- **`/login` returns 403 "no access to UIBundleLogin"** — guest user missing `UIBundleApexAccess`; redo Step 6.
+- **Anonymous visitors land on `/login`** — by design; every storefront route requires login (Step 6). Register or log in as a buyer to browse.
+- **`/commerce/...` returns 404 from the Site Container** — org is older than API version `67.0` (no Site Container support); upgrade the org.
+- **Storefront shows no products** — the buyer's Account isn't in a BuyerGroup with active price book entries for the catalog.
+- **Every authenticated request 401s** — Vite fell back to API `65.0`; set the org alias (Step 4d) and rebuild.
+- **Order placement fails `INSUFFICIENT_ACCESS`** — wrong/missing buyer PSG (Step 4c).
+- **Storefront still shows old or placeholder values after a redeploy** — a stale `dist/` shipped; delete it and rebuild (Step 5).
+
+## Notes
+
+- **Dual-network:** the headless storefront runs on its own Network, coexisting with the legacy LWR store's Network. Both stay in the org.
+- **Don't rename** the Apex classes, `UIBundleApexAccess`, or the site URL prefix — they're cross-referenced by the React app, the permission set, and this skill's queries.
+- This is a live-org workflow: name the org, the store, and every write before doing it, and never deploy against an org the user hasn't authorized.
+
+<!-- skill-validate: ignore-start -->
+<!-- codey:operations start -->
+## Operations Reference
+
+Operations this skill uses — routing and dependency reference.
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `list-webstores` | read | — | `GET /services/data/v67.0/query` | — |
+| `write-webstore-id-placeholder` | write | — | — | `list-webstores` |
+| `list-buyer-groups-for-store` | read | — | `GET /services/data/v67.0/query` | `list-webstores` |
+| `list-buyer-groups-all` | read | — | `GET /services/data/v67.0/query` | `list-buyer-groups-for-store` |
+| `write-buyer-group-id-placeholder` | write | — | — | `list-buyer-groups-for-store`, `list-buyer-groups-all` |
+| `list-permission-set-groups` | read | — | `GET /services/data/v67.0/query` | — |
+| `write-psg-placeholder` | write | — | — | `list-permission-set-groups` |
+| `write-vite-org-alias` | write | — | — | — |
+| `build-ui-bundle` | write | — | — | `write-webstore-id-placeholder`, `write-buyer-group-id-placeholder`, `write-psg-placeholder`, `write-vite-org-alias` |
+| `deploy-source` | delegate | — | → `experience-sites-ui-framework/experience-ui-bundle-deploy` | `build-ui-bundle` |
+| `find-site-and-guest-user` | read | — | `GET /services/data/v67.0/query` | `deploy-source` |
+| `find-uibundleapexaccess-permset` | read | — | `GET /services/data/v67.0/query` | `deploy-source` |
+| `assign-auth-permset-to-guest` | write | — | `POST /services/data/v67.0/sobjects/PermissionSetAssignment` | `find-site-and-guest-user`, `find-uibundleapexaccess-permset` |
+| `resolve-storefront-url` | read | — | `GET /services/data/v67.0/connect/communities` | `deploy-source` |
+| `verify-guest-permset-assignment` | verify | — | `GET /services/data/v67.0/query` | `assign-auth-permset-to-guest` |
+<!-- codey:operations end -->
+<!-- skill-validate: ignore-end -->

package/skills/consumer-goods-promotion-bo-api-deploy/SKILL.md

@@ -77,7 +77,7 @@ Every Apex call is `${PREFIX_DOT}ClassName.method(...)`; every SOQL object/field
 
 Run these and stop on the first failure.
 
-1. `sf --version`; `node --version` (only if running shipped scripts).
+1. `sf --version`; `node --version` (only if running shipped scripts). Also `export SF_SKIP_NEW_VERSION_CHECK=true` once at session start so a stale CLI's update banner cannot leak onto stdout and break any `sf … --json | jq …` pipe downstream (see `references/smoke-and-verify.md` "parse caveat" for the alternate `sed` strip).
 2. `sf org display --target-org <alias> --json` — confirm reachable; capture `instanceUrl` + org id (display/logging only). REST calls use `sf api request rest` on the CLI's stored session — the skill never extracts the access token.
 3. Validate sales org locally: length 4, uppercase, non-blank (mirrors `TPMSetupData.validateSalesOrg`). Fail fast.
 4. **TPM entitlement (Permission Set License)** — the `CGCRetailAndTPMMgmtPsl` PSL assignment on the running user. SOQL + warn/stop routing in `references/preflight-and-seed-queries.md` Step 4.
@@ -165,7 +165,7 @@ Say "use the SetCommentValue reference" for a worked example.
      | jq -r '.fields[] | select(.updateable == true and .createable == true) | .name'
    ```
    Any `outputWrites` field must appear here; otherwise stop and ask for a different one (FLS is caller-scoped).
-4. **Confirm the plan** (recap Class/Entity/Workflows/Reads/Writes/Sort/Description → "Deploy + wire? [y/N]"). If `workflows` includes `copy`, flag that per-child input values come from the source promotion — `outputWrites` still fires but `<inputPaths>` values are ignored (only top-level fields like `Slogan` propagate). `n`/blank → save answers to `./.promotion-bo-api-deploy/interview.json` and exit. `y` → Phase 5a.
+4. **Confirm the plan** (recap Class/Entity/Workflows/Reads/Writes/Sort/Description → "Deploy + wire? [y/N]"). If `workflows` includes `copy`, flag TWO copy-only preconditions up front so neither surfaces as a runtime surprise: (a) per-child input values come from the source promotion — `outputWrites` still fires but `<inputPaths>` values are ignored (only top-level fields like `Slogan` propagate); (b) the running `User.Sales_Org__c` MUST equal the source template's `Sales_Org__c` (preflighted in Phase 1 step 7 + re-checked before every Phase 6 ingest; a mid-flow drift fails `copy` with `TransformationError: The User and the Promotion Template must have the same Sales org` — fix on the user record, do not mutate mid-flow; see `references/conventions-and-payload-rules.md` R6). `n`/blank → save answers to `./.promotion-bo-api-deploy/interview.json` and exit. `y` → Phase 5a.
 
 ## Phases 5a / 5b — Generate + deploy, register + wire
 

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

@@ -25,7 +25,29 @@ Both phases run only on a green Phase 4 and a confirmed Phase 5 interview.
    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
+3. **Clean the deploy staging directory (mandatory on every invocation).**
+   Before writing the new `<stepName>.cls` to
+   `./.promotion-bo-api-deploy/force-app/main/default/classes/`, delete every
+   `*.cls` and `*.cls-meta.xml` already in that directory. This runs on EVERY
+   invocation, not just the second one — the generated class is the only
+   artifact that should live under `classes/` for the next deploy. Rationale:
+   a leftover `.cls` from a prior step run that is no longer known to the
+   source-tracking manifest makes `sf project deploy start` (step 6) evaluate
+   the deploy with `rollbackOnError: true` and silently roll back the *entire*
+   batch — including the new class — while the CLI still surfaces
+   `"created": true` for the intended component. The user sees apparent
+   success; the class is not actually in the org. Do NOT wipe `setup-data/`
+   under the same staging root (Phase 3a's retrieved read-only static resource
+   lives there) and do NOT wipe `sfdx-project.json` or `interview.json`.
+   Concretely:
+
+   ```bash
+   mkdir -p ./.promotion-bo-api-deploy/force-app/main/default/classes
+   find ./.promotion-bo-api-deploy/force-app/main/default/classes \
+     -maxdepth 1 -type f \( -name '*.cls' -o -name '*.cls-meta.xml' \) -delete
+   ```
+
+4. **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):
@@ -50,19 +72,9 @@ Both phases run only on a green Phase 4 and a confirmed Phase 5 interview.
        <stepName>.cls-meta.xml
    ```
 
-   **Deploy-directory hygiene — clean stale `.cls` files before writing the new
-   step.** When the skill is invoked more than once against the same working
-   tree (a second custom step, an interview re-run), any prior step's `.cls` /
-   `.cls-meta.xml` left behind in `force-app/main/default/classes/` is picked
-   up by `sf project deploy start` in step 5 below. If that stale file is no
-   longer known to the source-tracking manifest, MDAPI evaluates the deploy
-   with `rollbackOnError: true` and rolls back the *entire* batch — including
-   the new class — while the CLI still surfaces `"created": true` for the
-   intended component. The user sees an apparent success; the class is not
-   actually in the org. Before writing the new step, delete every
-   `*.cls`/`*.cls-meta.xml` under `./.promotion-bo-api-deploy/force-app/main/default/classes/`
-   that is not the class about to be generated. Do NOT wipe `setup-data/`
-   (Phase 3a's retrieved read-only static resource lives there).
+   The staging-dir cleanup (step 3 above) must have already run — the new
+   `.cls` is the only artifact that should land under `classes/` for the next
+   deploy.
 
    `sfdx-project.json`:
    ```json
@@ -81,13 +93,13 @@ Both phases run only on a green Phase 4 and a confirmed Phase 5 interview.
    </ApexClass>
    ```
 
-4. **Show the user the generated class + confirm.** Print the full
+5. **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:**
+6. **Deploy:**
 
    ```bash
    sf project deploy start \

package/skills/consumer-goods-promotion-bo-api-deploy/references/smoke-and-verify.md

@@ -28,7 +28,7 @@ on top of the derived contract:
 
 - **R1** — force `DateFrom`, `DateThru`, `Slogan` into the create payload. If the user gave duration-in-weeks intent, compute `DateThru = DateFrom + weeks*7 - 1` client-side.
 - **R2** — poll for `Status__c = 'Calculated'` (NOT `Processed`, which does not exist in the picklist).
-- **R3** — send level NAMES verbatim as `ProductFilter.Criteria` keys (`Category`, `Brand`, ...), NOT Product2 field API names.
+- **R3** — `ProductFilter` is a **top-level** promotion sibling of `Slogan`/`DateFrom`/`Tactics`, **NOT** nested under `Tactics[]` — nesting is schema-valid at ingest but fails downstream with the misleading "You must select at least one Category to the Promotion" (see R3a). Keys are level NAMES (`Category`, `Brand`, …), NOT Product2 field API names. Values are external ids (`<prefix>__Consumer_Goods_External_Product_Id__c`), NOT display `Name`/label (passing a Name fails with the misleading `TransformationError: Could not find Products: <Name>` — see R3b).
 - **R4** — pre-flight the anchor account has a `Plan` `Account_Extension__c` row valid for `DateFrom..DateThru` in this sales org.
 - **R5** — restrict `ManualInputs[].KPI` values to `editable` / `editable_calculated` `KPI_Definition__c.Name` on the template's `KPI_Set__c`.
 - **R6** — for `copy`, derive requireds the same way, then layer the Apex-only preconditions (`Is_Copyable__c`, template type, anchor).
@@ -95,6 +95,23 @@ credential exposure (S1). Do **not** add `--json` to `sf api request rest` — t
 raw stdout body is already JSON. `${URL_NS}` is the namespace segment from
 Phase 1 (`/cgcloud` / `/cgcloud_dev` / empty); the endpoint is instance-relative.
 
+**`sf … --json | jq …` parse caveat.** `sf` occasionally prints a plain-text
+update-availability banner (e.g. `›   Warning: @salesforce/cli update available
+from X to Y.`) ahead of the JSON body on stdout, which silently breaks a direct
+`| jq` pipe (jq hits the banner line first and errors with `invalid numeric
+literal` / `parse error`). Two defenses — pick one and use it consistently
+across every `sf … --json | jq` pipe in this phase:
+
+- Export `SF_SKIP_NEW_VERSION_CHECK=true` for the session (suppresses the
+  banner at the source; preferred for a single-session smoke run).
+- Strip pre-JSON noise before piping: `sf … --json | sed -n '/^[\[{]/,$p' | jq .`
+  (keeps everything from the first `{` or `[` onward; works even if the banner
+  grows to multiple lines).
+
+The same caveat applies to the `sf data query --target-org <alias> --json` SOQL
+calls elsewhere in this skill — a stale CLI emits the banner on arbitrary
+invocations, not just the first one.
+
 **Smoke-time re-check of running user's `${PREFIX_UNDER}Sales_Org__c`.** Phase 1
 step 7 gated the whole invocation on this, but Phase 6 can be minutes/hours later
 and the user record may have drifted (a parallel admin edit, a session on a