@salesforce/afv-skills 1.65.0 → 1.66.0

package/skills/commerce-fulfillment-routing-analyze/SKILL.md

@@ -1,200 +0,0 @@
----
-name: commerce-fulfillment-routing-analyze
-description: "Use this skill when users want to use this workflow when a customer, CSR, or admin needs to understand why an order was fulfilled from a specific location. Trigger when users mention fulfillment, routing, explanation."
-metadata:
-  version: "1.0"
-  accessCheck: "(FulfillmentOrder.OrderSummaryId) || (OrderManagement.ReadFulfillmentOrder) || (OrderManagement.orgHasOrderManagementEnabled)"
----
-
-# Querying Fulfillment Routing Explanation
-
-## When to Use This Skill
-
-Use this workflow when a customer, CSR, or admin needs to understand why
-an order was fulfilled from a specific location. The workflow resolves
-an OrderNumber to its OrderSummary, finds all associated FulfillmentOrders,
-then calls the routing explanation API for each to surface:
-  • The winning routing criterion that determined the location
-  • Per-rule scoring and contributions to the routing decision, as a table
-  • Line-item allocation (fulfilled vs. requested vs. available elsewhere),
-    as a table
-  • Split-order context when multiple locations fulfill parts of one order
-
-Presentation is table-first and customer-centric: routing details, rule
-contributions, and line items render as markdown tables by default, not
-just on request. This is a read-only diagnostic workflow — it explains
-past routing decisions but does not modify routing or re-route orders.
-
-## Workflow
-
-fulfillment-routing-explanation is a READ-ONLY diagnostic workflow. It
-does not modify routing, re-route orders, or change fulfillment assignments.
-
-## Critical Constraints
-
-**Preconditions:**
-
-- Org must have Order Management enabled with fulfillment routing configured (check: `OrderManagement.orgHasOrderManagementEnabled`)
-- User must have access to Order Management features and fulfillment data (check: `OrderManagement.ReadFulfillmentOrder`)
-- The OrderSummary must have at least one FulfillmentOrder created. Orders
-still in cart/checkout phase or canceled before fulfillment began will
-have no FulfillmentOrders to explain. (check: `FulfillmentOrder.OrderSummaryId`)
-
-**Operational rules:**
-
-- EXECUTION PATH:
-  1. resolve-order-summary-by-number → OrderNumber → OrderSummary Id
-     (skip if caller has the Id directly)
-  2. query-fulfillment-orders → find all FulfillmentOrders for this
-     OrderSummary; detect split-order case
-  3. get-routing-explanation → call once per FulfillmentOrder to get
-     routing details
-  4. synthesize-explanation → consolidate explanations into a customer-facing
-     report: one lead sentence plus markdown tables for routing details,
-     rule contributions, and line items (single-location or split-order)
-- SPLIT-ORDER HANDLING:
-When query-fulfillment-orders returns multiple FOs, call
-get-routing-explanation for EACH one in sequence, then consolidate in
-synthesize-explanation. Label each FO by its FulfillmentOrderNumber and
-location so the customer knows which items come from where.
-- FAILURE CASES:
-- No FulfillmentOrders found: order hasn't reached fulfillment or was
-  canceled early. Surface friendly message and STOP.
-- 404 on routing-explanation: routing explanation not available (manual
-  assignment or pre-explanation era). Fall back to basic location info
-  from FulfilledFromLocation.Name.
-- Permission errors: surface to user and STOP.
-- CUSTOMER-FACING WORDING:
-- Use "location" not "Location record"
-- Use "order" not "OrderSummary"
-- Use "items" not "OrderItemSummary"
-- Translate routing criterion names to plain language (proximity, inventory,
-  cost, speed, preference)
-- No raw Ids, field names, or sObject types in customer text
-- REPORTING FORMAT (see synthesize-explanation for the full spec):
-- Table-first, not prose-first. Rule contributions and line-item
-  allocations are always rendered as markdown tables, not gated behind
-  "if the customer asks for detail."
-- One lead sentence, then tables. Don't pad tabular data with a
-  restating paragraph underneath it.
-- Split orders get an overview table across all fulfillment orders, then
-  a rule-breakdown + items table pair per fulfillment order.
-- WHEN TO USE THIS WORKFLOW:
-- "Why was my order sent from location X?"
-- "Why are my items coming from different places?"
-- "How did the system decide on this fulfillment location?"
-- "Explain the routing for order #{orderNumber}"
-- DO NOT USE for:
-- Changing fulfillment location (use re-routing workflows)
-- Canceling or modifying fulfillment orders
-- Viewing shipment tracking (use shipment status workflows)
-
-## Operations Reference
-
-Operations grouped by purpose. Use these as the building blocks for the workflows above.
-
-### Summary
-
-| Operation | Purpose | Status | Call | Depends on |
-|-----------|---------|--------|------|------------|
-| `resolve-order-summary-by-number` | read | implemented | `querySoql` | — |
-| `query-fulfillment-orders` | read | implemented | `querySoql` | `resolve-order-summary-by-number` |
-| `get-routing-explanation` | read | implemented | `getFulfillmentOrderRoutingExplanation` | `query-fulfillment-orders` |
-| `synthesize-explanation` | read | implemented | `conversational_synthesis` | `get-routing-explanation` |
-
-### Read operations
-
-#### `resolve-order-summary-by-number`
-
-Resolve a customer-provided OrderNumber to its OrderSummary Id.
-Customers and CSRs work with OrderNumber (the printed order number);
-the fulfillment APIs require the internal OrderSummary Id (1Os...).
-
-IMPORTANT: OrderNumber is NOT unique — a single OrderNumber can resolve
-to multiple OrderSummaries (orgs reuse it across storefronts/locales).
-When this step returns more than one row, surface candidates and ask
-which one before proceeding.
-
-**Call:** `querySoql`   — status: `implemented`
-
-**Inputs:**
-
-- `orderNumber` *(`String`)* — Customer-facing OrderNumber (from receipt/confirmation email).
-Skip this step if caller already has the OrderSummary Id (1Os...).
-
-#### `query-fulfillment-orders`
-
-Query all FulfillmentOrders associated with the OrderSummary.
-One OrderSummary can have multiple FulfillmentOrders when the order
-is split across locations (e.g., some items from warehouse A, others
-from store B). Each FulfillmentOrder has its own routing explanation.
-
-**Call:** `querySoql`   — status: `implemented`
-
-**Inputs:**
-
-- `orderSummaryId` *(`String`)* — OrderSummary Id from resolve-order-summary-by-number, or passed
-directly by caller.
-  - **Source:** output of `resolve-order-summary-by-number`
-
-**Depends on:** `resolve-order-summary-by-number`
-
-#### `get-routing-explanation`
-
-Call the routing explanation API for a specific FulfillmentOrder.
-Returns sections-based routing explanation with the winning criterion, per-rule
-contributions, location details, and line item information.
-
-API contract (OMS Connect API v68.0 / min version 264):
-GET /commerce/fulfillment/fulfillment-orders/{fulfillmentOrderId}/routing-explanation
-
-Returns sections-based structure:
-- success: boolean indicating API call success
-- location: string - winning location name (top-level field)
-- sections[]: array of section objects, each with:
-  - name: section identifier ("summary", "rules", "lineItems")
-  - rows[]: array of free-form Map<String,Object> with dynamic keys
-
-NOTE: rows[] fields are @ConnectHidden(from=Apex) - REST/UI-API only.
-Each row is a free-form key-value map with dynamic keys specific to the
-section type. Keys vary by routing strategy and configuration.
-
-**Call:** `getFulfillmentOrderRoutingExplanation`   — status: `implemented`
-
-**Inputs:**
-
-- `fulfillmentOrderId` *(`String`)* — FulfillmentOrder.Id from query-fulfillment-orders $.records[].Id.
-Extracted per-iteration from the loop.
-  - **Source:** output of `query-fulfillment-orders`
-- `fulfillmentOrderNumber` *(`String`)* — FulfillmentOrder.FulfillmentOrderNumber from query-fulfillment-orders
-$.records[].FulfillmentOrderNumber. Used for labeling in split-order scenarios.
-  - **Source:** output of `query-fulfillment-orders`
-
-**Depends on:** `query-fulfillment-orders`
-
-#### `synthesize-explanation`
-
-Final step: synthesize all routing explanations into a single
-customer-facing report of markdown tables. When multiple
-FulfillmentOrders exist (split order), this step consolidates their
-individual explanations into one coherent set of tables — see
-agent_guidance below for the full table spec.
-
-This is a conversational synthesis step — no API call, just presentation
-logic that threads outputs from get-routing-explanation.
-
-**Call:** `conversational_synthesis`   — status: `implemented`
-
-**Inputs:**
-
-- `fulfillment_order_count` *(`integer`)* — Total number of FulfillmentOrders (from query-fulfillment-orders)
-  - **Source:** output of `query-fulfillment-orders`
-- `routing_explanations` *(`Array`)* — Array of routing explanation outputs from get-routing-explanation,
-accumulated from the per-FO loop. Each array element is an object with:
-fulfillment_order_number, success, location, whyItWon, whyItWonTooltip
-(optional), selectionScore, selectionScoreTooltip (optional),
-unitsFilled, rules (array, each row's isOverride optional), lineItems
-(array, each row's elsewhere optional).
-  - **Source:** output of `get-routing-explanation`
-
-**Depends on:** `get-routing-explanation`

package/skills/commerce-guest-buyer-create/SKILL.md

@@ -1,173 +0,0 @@
----
-name: commerce-guest-buyer-create
-description: "Use this skill when users want to use this workflow when a user wants to register an existing Account as a (guest) buyer for a specific Commerce webstore — the prerequisite that lets that account shop, or be shopped-on-behalf-of, in that store. Trigger when users mention register, guest, buyer."
-metadata:
-  version: "1.0"
-  accessCheck: "(Account.exists) || (OrderManagement.orgHasRegisterGuestBuyerAPIEnabled) || (WebStore.READ)"
----
-
-# Managing Register Guest Buyer
-
-## When to Use This Skill
-
-Use this workflow when a user wants to register an existing Account as a (guest) buyer for a specific Commerce webstore — the prerequisite that lets that account shop, or be shopped-on-behalf-of, in that store. Registration enrolls the account as a buyer for the store, adds it to the store's buyer group, and marks the account as a buyer; the confirmation should tell the user the account can now shop the store (and is in its buyer group), not just report "success".
-
-Scope boundaries (pick-signal):
-- The Account must ALREADY EXIST. This workflow does not create accounts, does not do buyer-group / entitlement setup beyond that enrollment, and does not start any shopping / cart / pricing flow — those live in separate SORs.
-- B2B stores ONLY. B2CE and B2C stores are rejected by the server (ERROR_ENABLING_BUYER). Do NOT pre-check store Type client-side — attempt the call and translate the error. (Wire-verified: B2B ok, B2CE 400.)
-- Portal users are NOT allowed (allowsPortalUsers=false on the resource).
-- Idempotent: re-registering an already-registered account returns success:true again (wire-verified) — safe to re-run.
-
-Never echo raw 0ZE / 001 Ids or the raw error envelope to a buyer — translate success and errors to friendly language and offer a next step on failure. See agent_guidance and steps[] for the path parameters, empty POST body, response handling, and precondition gates.
-
-## Workflow
-
-### Phase 1: discover-webstores -> numbered menu of store Names; user...
-
-discover-webstores  -> numbered menu of store Names; user picks one.
-                          The chosen record's Id becomes webstoreId.
-
-### Phase 2: account-input choice -> if the user gave a...
-
-account-input choice -> if the user gave a 001 Id: by-id (skip lookup).
-                          If they gave a name: by-name -> identify-account
-                          resolves Name -> accountId.
-
-### Phase 3: register-guest-buyer -> POST (empty body); read success/errors
-
-register-guest-buyer -> POST (empty body); read success/errors.
-
-- The register endpoint is POST-only and takes NO body — the two path
-  params (webstoreId 0ZE, accountId 001) are the whole contract. The
-  response is success + errors only; there is no entity payload, so
-  $.success is the confirmation. The call returns HTTP 200 for BOTH success
-  and business-rule failures — always branch on $.success, never on the
-  HTTP status alone.
-
-- What registration ACCOMPLISHES (wire-verified): it enrolls the account as
-  a buyer for the store AND adds it to that store's buyer group, and flips
-  Account.IsBuyer to true. So the success message should tell the user the
-  account can now shop the store (and is in its buyer group) — that is the
-  user-visible outcome, not just "success:true".
-
-- B2B ONLY — do NOT pre-check the store Type client-side. Registration works
-  on B2B stores; B2CE (and B2C) are rejected by the server with a clear
-  error (ERROR_ENABLING_BUYER, "not supported for B2CE store"). Let the API
-  be the authority and translate its error rather than maintaining a
-  client-side Type allow-list that could drift. WIRE-VERIFIED on q3Sdb27:
-  BrightBundle Co (B2B) succeeded; RefArch USD (B2CE) returned 400
-  success:false.
-
-- Idempotent: re-registering an already-registered account on the same store
-  returns success:true again (no error) — safe to re-run without a pre-check.
-  WIRE-VERIFIED on q3Sdb27.
-
-- Pre-validate both Id shapes at the agent layer to fail fast (0ZE / 001).
-
-- Preconditions: org gate Register Guest Buyer API enabled
-  + user check userHasRegisterGuestBuyerAPIAccess. Portal users are not
-  permitted (allowsPortalUsers=false).
-
-- The Account must ALREADY EXIST. This SOR does not create accounts and does
-  not start shopping — those are separate workflows (out of scope).
-
-- Customer-friendly wording: never echo raw 0ZE / 001 Ids, the raw error
-  envelope, or errorCode strings; translate success and errors to plain
-  language and always offer a next step on failure.
-
-- Request body detail: the register action takes an EMPTY body — the RegisterGuestBuyerInputRepresentation has no fields, so send {} / no body. (The endpoint is the Order Management Repricing API register-guest-buyer action; see the register-guest-buyer step.)
-
-## Critical Constraints
-
-**Preconditions:**
-
-- Org must have the Order Management Register Guest Buyer Connect API
-enabled — this is the x-sfdc org-access-check on the postRegisterGuestBuyer
-endpoint. Without it, the call returns FEATURE_NOT_ENABLED.
- (check: `Register Guest Buyer API enabled`)
-- Calling user must pass the resource's user dynamic check
-userHasRegisterGuestBuyerAPIAccess (declared on RegisterGuestBuyerResource
-via userDynamicChecks). Without it the call is rejected (403); surface a
-friendly access message, never the raw exception.
- (check: `userHasRegisterGuestBuyerAPIAccess`)
-- The target Account (001-prefixed) must already exist. This SOR does NOT
-create accounts — if the user references an account that doesn't exist,
-resolve/confirm it first (identify-account) or stop and tell the user the
-account must be created before it can be registered as a buyer.
- (check: `Account.exists`)
-- Caller needs READ access to WebStore (to list/select the store) and to
-Account (to resolve the account by name). Portal users are not permitted
-(the resource sets allowsPortalUsers=false).
- (check: `WebStore.READ`)
-
-**Operational rules:**
-
-- TYPICAL FLOW
-- KEY CONTRACTS (source-verified against the Register Guest Buyer resource):
-
-## Operations Reference
-
-Operations grouped by purpose. Use these as the building blocks for the workflows above.
-
-### Summary
-
-| Operation | Purpose | Status | Call | Depends on |
-|-----------|---------|--------|------|------------|
-| `discover-webstores` | read | implemented | `querySoql` | — |
-| `identify-account` | read | implemented | `querySoql` | — |
-| `register-guest-buyer` | write | implemented | `postRegisterGuestBuyer` | `discover-webstores` |
-
-### Read operations
-
-#### `discover-webstores`
-
-Enumerate Commerce webstores with Id, Name, and Type. Runs FIRST; no
-choice gate (always executes). The agent presents Names to the user and
-threads the chosen record's Id into the register step as webstoreId.
-
-
-**Call:** `querySoql`   — status: `implemented`
-
-#### `identify-account`
-
-Resolve an Account by name to its 001-prefixed Id. Runs ONLY when the user
-supplied a company / account NAME rather than an Id (account-input = by-name).
-Skipped when the user already gave a 001 Id.
-
-
-**Call:** `querySoql`   — status: `implemented`
-
-**Inputs:**
-
-- `accountName` *(`String`)* — The company / account name (or fragment) the user gave. Matched with a
-LIKE filter; present matches for the user to pick when more than one.
-WILDCARD SAFETY: before binding, escape SOQL LIKE metacharacters in the
-user's input — backslash-escape `\`, `%`, and `_` (\\ , \%, \_) so a
-user cannot pass a bare `%`/`_` to enumerate every visible Account. A
-lone `%` or empty string must be rejected, not run as "match all".
-
-### Write operations
-
-#### `register-guest-buyer`
-
-Register the selected Account as a (guest) buyer for the selected webstore.
-POST to the Order Management Repricing API register-guest-buyer action.
-The request body is EMPTY — the whole contract is the two path params.
-Response carries success + errors only (no entity payload).
-
-
-**Call:** `postRegisterGuestBuyer`   — status: `implemented`
-
-**Inputs:**
-
-- `webstoreId` *(`String`)* — WebStore Id from discover-webstores (the store the user picked).
-Pre-validate against ^0ZE[A-Za-z0-9]{12}([A-Za-z0-9]{3})?$ before invoking.
-
-  - **Source:** output of `discover-webstores`
-- `accountId` *(`String`)* — Account Id (001-prefixed) to register as a buyer. Sourced from
-identify-account when the user gave a name (account-input = by-name), or
-supplied directly by the user (by-id). Pre-validate against
-^001[A-Za-z0-9]{12}([A-Za-z0-9]{3})?$ before invoking.
-
-
-**Depends on:** `discover-webstores`