@salesforce/afv-skills 1.65.1 → 1.67.0

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

package/skills/dx-devops-work-item-manage/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: dx-devops-work-item-manage
-description: "Use this skill to manage the full lifecycle of DevOps Center work items — list, create, update, commit changes, perform status transitions, and create pull requests. Update fields like subject, description, and status. Commit and push code changes to work item branches. Create pull requests for work item branches via DevOps Center API. Invoke when the user wants to track, find, create, or update a work item, commit changes to a work item branch, advance a work item's status through the pipeline, or create a pull request for code review. Consolidates sf devops work-item and review operations. DO NOT TRIGGER for promotion or deployment operations, or conflict detection."
+description: "Use this skill to manage the full lifecycle of DevOps Center work items — list, create, update, commit changes, perform status transitions, and create pull requests. Update fields like subject, description, and status. Commit changes to work item branches, through the DevOps Center commit API or git. Create pull requests for work item branches via DevOps Center API. Invoke when the user wants to track, find, create, or update a work item, commit changes to a work item branch, advance a work item's status through the pipeline, or create a pull request for code review. Consolidates sf devops work-item and review operations. DO NOT TRIGGER for promotion or deployment operations, or conflict detection."
 metadata:
   relatedSkills:
     - "dx-devops-promote"
-  version: "1.0"
+  version: "1.1"
   domains: ["Developer Experience"]
   minApiVersion: "58.0"
   cliTools:
@@ -34,7 +34,7 @@ Gather or infer before proceeding:
 - **Operation type**: list, create, update, commit, or create-review
 - **For list**: project ID (required) — obtain via `sf devops project list --json` if not provided
 - **For create**: project ID (required), subject (required), description (optional)
-- **For commit**: work item name or ID (required) to retrieve branch name, files to commit, commit message
+- **For commit**: work item name or ID (required), commit message, and either the files to commit (git path) or the components to commit (API path). Optional: **dev org alias** — the org that holds the changes. When provided, try the DevOps Center commit API first (see step 5); otherwise use git
 - **For update**: work item name (e.g., WI-000001) or work item ID (required), fields to update (subject, description, status)
 - **For create-review**: work item name (e.g., WI-000001) or work item ID (required)
 
@@ -48,7 +48,7 @@ If the user provides a clear request ("list work items for Project Alpha", "crea
 
 ## Workflow
 
-All operations use `sf devops work-item` CLI commands with `--json` output for structured consumption.
+Operations use `sf devops work-item` CLI commands with `--json` output; the API commit path also uses `sf api request rest` and `sf data query`.
 
 ### Phase 1 — Identify Operation
 
@@ -71,6 +71,7 @@ All operations use `sf devops work-item` CLI commands with `--json` output for s
      ```
    - Verify the authenticated org has DevOps Center enabled by attempting to list projects
    - If the user wants to target a specific org, use `--target-org <alias>` on all subsequent commands
+   - For the API commit path, run `sf org display --target-org <alias> --json` for **both** the dev org and the hub org
 
 3. **List work items** — when the user wants to see existing work items:
    ```bash
@@ -102,9 +103,21 @@ All operations use `sf devops work-item` CLI commands with `--json` output for s
    - Capture the returned work item name (e.g., WI-000001), branch name, and environment from JSON output for future operations
    - Idempotent: if the user attempts to create a duplicate (same subject + project), check via list first and return the existing work item
 
-5. **Execute commit operation** — when operation type is commit:
-   - DevOps Center creates a dedicated feature branch for each work item (returned in the create operation)
-   - The user must commit and push changes to this branch before transitioning status or creating a PR
+5. **Execute commit operation** — when operation type is commit. Choose the path first:
+   - **API path** — only when the user gave a dev org alias AND the changes are already deployed in that dev org (if unsure, ask: deploy with `sf project deploy start`, or use git). Dev org alias: `commitChanges`, `DevopsRequestInfo`. Hub alias: `sf devops` and `WorkItemComponentList`. DevOps Center retrieves the named components from the dev org and commits them as `DevOps Center <noreply@salesforce.com>`.
+   - **Git path** — everything else. If the changes exist only in the dev org, run `sf project retrieve start --target-org <dev-org>` first.
+
+   **API path** (commands, body, error codes and polling in `references/commit-api.md`):
+   1. Preflight `GET /connect/devops/doceConnectionType` on the dev org; a failed call (non-zero exit or error body) or `isCore` not `true` means use the git path.
+   2. `sf devops project list` → project id, then `sf devops work-item list --project-id <id> --target-org <hub>` → work item id and name. Status must be New, In Progress, In Review or Ready to Promote.
+   3. `POST /connect/devops/commitChanges` on the **dev org**; the body is the inner object (no `commitChanges` wrapper).
+   4. A failed call, or `status: "ERROR"` with `reqId` = `CODE:message`: surface it and stop.
+   5. If the POST `status` is `SUCCESS` (accepted only), poll `DevopsRequestInfo WHERE RequestToken = '<reqId>'` on the dev org every 10 seconds until `Status` is `SUCCESS` or `ERROR` (report `Message`/`ErrorDetails`), 12-minute deadline. Past it the request is stuck; report it and do not retry automatically.
+   6. Confirm a new `WorkItemComponentList` exists on the hub before creating a review.
+
+   **Git path:**
+   - If the work item is New, first set it to In Progress (step 6); the hub ignores pushes made while it is New
+   - Use the work item's `branch` field as the branch
    - Standard git workflow:
      ```bash
      git checkout <branch-name>
@@ -112,8 +125,7 @@ All operations use `sf devops work-item` CLI commands with `--json` output for s
      git commit -m "<commit-message>"
      git push origin <branch-name>
      ```
-   - The branch name is available from the work item's `branch` field (retrieve via list or create operation)
-   - Changes must be committed before the work item can be marked "Ready to Promote" or before creating a PR
+   - The hub registers the push asynchronously; re-check it before creating a PR
 
 6. **Update work item** — when the user wants to change subject, description, or status:
    ```bash
@@ -162,7 +174,8 @@ All operations use `sf devops work-item` CLI commands with `--json` output for s
 8. **Verify operation success**:
    - **For list**: confirm the CLI returned status 0, parse the JSON `.result[]` array, and verify it contains work items (or is empty if no matches). If the user specified a project by name, confirm the resolved project ID matches.
    - **For create**: verify the CLI returned status 0 and the JSON output contains `.result.name` (work item ID like WI-000001), `.result.branch` (branch name), and `.result.environment` fields.
-   - **For commit**: verify each git command returned exit code 0. If `git push` succeeds, the commit is saved to the work item branch.
+   - **For commit (git path)**: verify each git command returned exit code 0. If `git push` succeeds, the commit is saved to the work item branch; the hub registers it asynchronously.
+   - **For commit (API path)**: verify the POST `status`, then `DevopsRequestInfo.Status`, are `SUCCESS`, and that a new `WorkItemComponentList` with a `CommitReference` exists on the hub. A new list with an empty `CommitReference` means nothing new was committed; report that, not a clean success.
    - **For update (general fields)**: verify the CLI returned status 0 and compare the returned JSON fields against the user's requested changes. If updating subject, confirm `.result.subject` matches the new value.
    - **For update (status transition)**: verify the CLI returned status 0, then **explicitly confirm the status transition** by checking `.result.status` in the JSON response matches the target status (e.g., "Ready to Promote"). If the response doesn't include the status field, re-run `sf devops work-item list` filtered to this work item and verify the status persisted.
    - **For create-review**: verify the CLI returned status 0 and the JSON output contains `.result.pullRequestUrl` (the PR URL) and `.result.status` (should be "open" or equivalent). If VCS credentials are missing, the CLI returns an error — surface this to the user.
@@ -170,7 +183,7 @@ All operations use `sf devops work-item` CLI commands with `--json` output for s
 9. **Report results**:
    - **List**: present work items in a readable format showing work item name, subject, status, branch, and environment. If filtering by status was requested, show only matching work items.
    - **Create**: return the work item name (e.g., WI-000001), branch name, environment, and confirm "Work item created successfully."
-   - **Commit**: confirm which files were staged, the commit SHA (from git output), and "Changes committed and pushed to branch <branch-name>."
+   - **Commit**: git path — confirm which files were staged, the commit SHA (from git output), and "Changes committed and pushed to branch <branch-name>." API path — confirm the `reqId`, components committed and hub `CommitReference` (author is DevOps Center)
    - **Update (general)**: confirm which fields changed with before/after values (e.g., "Subject updated from 'X' to 'Y'").
    - **Status transition**: explicitly state the transition with old → new status (e.g., "Status updated: In Progress → Ready to Promote").
    - **Create-review**: return the PR URL and confirm "Pull request created successfully. Status: open. URL: <url>"
@@ -187,7 +200,9 @@ All operations use `sf devops work-item` CLI commands with `--json` output for s
 | At least one update field required | Update command fails if no `--subject`, `--description`, or `--status` flag is provided |
 | Status values must be exact strings | "In Progress" and "Ready to Promote" (with spaces, proper capitalization); other values fail |
 | Idempotent create operations | Check for existing work item with same subject + project before creating duplicates |
-| Changes must be committed before status transition to Ready to Promote | DevOps Center validates that the work item branch has commits before allowing promotion readiness |
+| Commit before creating a PR | Commit first and confirm a component list exists on the hub before `review create` |
+| API commit only sends components already in the dev org | The API retrieves from the dev org, not from local disk; deploy local-only edits first (`sf project deploy start`) or use the git path |
+| Check `status` in the commit API response | Errors are returned as HTTP 200 with `status: "ERROR"` |
 | PR creation requires VCS credentials in org | DevOps Center API uses stored VCS credentials; no local git auth needed |
 | Never use interactive prompts | Skills run in headless environments; all inputs must be via CLI flags |
 
@@ -205,6 +220,8 @@ All operations use `sf devops work-item` CLI commands with `--json` output for s
 | **Invalid status value** | Only "In Progress" and "Ready to Promote" are valid (exact strings with spaces); check spelling and capitalization |
 | **Project not found** | User provided invalid project ID; run `sf devops project list --json` to show available projects |
 | **Duplicate work item subject** | Idempotent create check should catch this; return existing work item name instead of creating duplicate |
+| **Commit pushed while work item is New** | The hub ignores external pushes for New work items; set In Progress first and, if already pushed, re-check after the status change |
+| **API commit still in progress past the deadline** | Report it as stuck; do not retry automatically (a new request could race it) |
 | **Git push fails - no commits or branch not found** | Verify files are staged with `git status` and branch name retrieved from work item via list command |
 | **PR creation fails - VCS credentials** | VCS credentials not configured in DevOps Center UI; instruct user to configure in Setup → DevOps Center → VCS Credentials |
 
@@ -216,7 +233,7 @@ Deliverables vary by operation:
 
 - **List**: JSON array of work items with work item name (WI-######), subject, branch, environment, repository details
 - **Create**: Work item name (e.g., WI-000001), ID, branch name, and environment of the newly created work item
-- **Commit**: Confirmation of git commit and push success, with commit SHA
+- **Commit**: Confirmation of git commit and push success with commit SHA, or for the API path the `reqId`, final request status and `CommitReference`
 - **Update**: Confirmation of updated fields (old value → new value for subject/description, or status change)
 - **Create-review**: Pull request URL, PR number, and status
 
@@ -247,10 +264,9 @@ Before reporting results to the user:
 - [ ] Was `--project-id` provided (or obtained via project list)?
 
 ### Commit Operation Checks
-- [ ] Was the work item branch name retrieved successfully?
-- [ ] Were files staged with `git add`?
-- [ ] Did `git commit` succeed with exit code 0?
-- [ ] Did `git push` succeed with exit code 0?
+- [ ] API path: preflight passed, POST `status` checked, `DevopsRequestInfo` polled to `SUCCESS`, new `WorkItemComponentList` with `CommitReference` seen on the hub?
+- [ ] Git path: was the work item In Progress, and the branch name retrieved?
+- [ ] Git path: did `git add`, `git commit` and `git push` all exit 0?
 
 ### Update Operation Checks
 - [ ] Was work item identifier provided (name or ID)?
@@ -269,5 +285,6 @@ Before reporting results to the user:
 
 | File | When to read |
 |------|-------------|
+| `references/commit-api.md` | When committing through the DevOps Center API: request body, response and error codes, polling, preflight |
 | `references/cli-commands.md` | When you need detailed CLI flag documentation, JSON output schemas, or error handling patterns |
 | `examples/common-workflows.md` | When the user's request matches a common pattern (bulk updates, reassignment, idempotent creation, sequential transitions) |