dsc-scenario

name	dsc-scenario
description	Use for multi-call developer.salesforce.com API scenarios or repros covering prerequisites, call order, scopes, ID threading, or a flow around an operation, goal, cURL, or failure. Produces a plan and runnable cURL block. Not for one-endpoint lookup/debugging or narrated, paused demo scripts.
license	MIT

DSC Scenario Composer

Produce a plan of SCAPI / OCAPI calls – in order, with scope union, ID threading, and a runnable cURL block – to reach a target state. Every claim backed by a public developer.salesforce.com URL.

When to use

The user is trying to reproduce a customer flow on an instance and needs to know:

• Which API calls must happen before the target operation can succeed.
• Which scopes the instance's SLAS/OAuth client must be configured with.
• Where each input to the target (basket IDs, customer IDs, line-item IDs) comes from.

Or the user pastes a cURL command and asks "what else do I need to call to make this work."

Inputs

Ask for missing bits only when the skill can't proceed:

• Target – one of:
  • An operationId (createOrder, shopper-baskets.addItemToBasket).
  • A natural-language goal ("registered shopper adds a coupon and checks out"). You resolve this to an operationId by matching against _index.json.title + Summary prose across cached references; ask the user to confirm before proceeding.
  • A sample request (cURL, raw HTTP). Pass it to scenario.js as request (in place of target) and it resolves the slug for you – it parses the request and matches it against the reference referenceUrl names, the same parse-request.js + resolve-slug.js path dsc-endpoint-help uses. You still supply referenceUrl (deriving it from a bare cURL is out of scope); if the request can't be resolved, scenario.js exits non-zero – ask the user for the reference URL rather than guessing (see "Decline, don't fabricate").
• Reference URL – the developer.salesforce.com URL of the reference containing the target. Usually inferrable from the request path or operationId's reference prefix.

Resolving an OCAPI target you can't name the reference for. OCAPI reference slugs are not guessable (ocapi-shop-orders, ocapi-data-code-versions – there is no ocapi-shop-api; guessing 404s). When the user gives a METHOD + path ("OCAPI shop, POST /orders", "submit a basket via POST /orders") but not the reference slug, resolve it deterministically with resolve-target.js – pass the area-landing URL (https://developer.salesforce.com/docs/commerce/b2c-commerce/references) plus the method and path; it scans the landing and returns the exact {reference, slug, referenceUrl} to hand to scenario.js:

node scripts/resolve-target.js <<'EOF'
{
  "referenceUrl": "https://developer.salesforce.com/docs/commerce/b2c-commerce/references",
  "method": "POST",
  "path": "/orders",
  "cacheRoot": "/Users/<you>/.cache/dsc-scrape"
}
EOF

It returns {area, candidates:[{reference, slug, referenceUrl, ...}]}. Use candidates[0] (most-specific path wins). Empty candidates means no match – ask the user for the reference URL; do NOT guess a slug (see "Decline, don't fabricate" below). The area-landing URL itself comes from the OCAPI hint in the user's prompt via the alias map (shared/scrape/aliases.js maps "OCAPI", "/dw/shop", "/dw/data", etc. to the b2c-commerce landing).

Flow

scenario.js owns all cache access – decide nothing by reading the cache yourself. Before your first move: do not use shell commands, file-reading tools, or ad hoc parsers (python3 json.load, node -e) on files under ~/.cache/dsc-scrape/, and do not point the scrape library, curl, or a web-fetch tool at a developer.salesforce.com URL. Hand scenario.js the target + reference URL and build from the structured plan it returns. If it can't resolve the target, fix the inputs or report the gap (see "Decline, don't fabricate") – never open cache files to assemble a plan by hand. Spelunking the cache bypasses the freshness/staleness handling and yields the nondeterministic, hand-assembled plans this skill exists to prevent. (Full contract under "Key invariants.")

1. Resolve target to {reference, targetSlug}. For natural-language goals, match titles + Summary prose and confirm with the user.

2. Invoke scenario.js – it scrapes/refreshes the cache for you (via the accessor) and runs the type-graph walk locally; you do not warm the cache or read its files first:

   node scripts/scenario.js <<'EOF'
   {
     "target": "createOrder",
     "referenceUrl": "https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders",
     "cacheRoot": "/Users/<you>/.cache/dsc-scrape"
   }
   EOF
   

   Omitting graph is the default: scenario.js runs walkTypes itself against the cache it just warmed. For an unusually large or cross-reference-heavy target, a client that supports subagents may read scripts/walk-via-agent.md, pass that prompt to a subagent, and put its returned {nodes, edges, externalInputs} in the graph field – but that is the exception, not the routine path, and even then the subagent reads the cache scenario.js warmed, it does not scrape.

   Producer choice point (two-pass). If scenario.js returns a bridgeCandidates array, the target depends on a resource that has more than one operation producing it from nothing, and the skill needs you to pick which one belongs in the plan. The candidates are those from-nothing producers. Pick the single canonical create – the one that builds the resource fresh, not the ones that derive it from an existing instance (mergeBasket/transferBasket presuppose an existing basket; createBasket does not). Re-run scenario.js with bridgeProducer: "<chosen slug>" added to the stdin JSON. The second call composes the full plan deterministically – you do not hand-write the producer step. Pick exactly one; do not list the alternatives in the plan.

   Curated body-types auto-resolve – you won't be asked for them. When the target's body-type has a curated canonical producer, scenario.js picks it and composes the full plan in one call, returning no bridgeCandidates. This covers the SCAPI Basket bridge (createOrder, whose canonical producer is createBasket) and the OCAPI basket bridge (, producer ) – the demo heroes. So this choice point only surfaces for produced types the skill has curated – where it genuinely can't know which create is canonical – and for the in-reference id case below; handle those exactly as described. Nothing changes in how you respond when a array does come back.

Output composition

scenario.js emits {plan, runnable, sources, staleness}. Wrap it for the user like this (and if staleness is non-empty, prepend the stale-data warning from "Key invariants" above the ## Scenario: line):

## Scenario: <short NL description of the goal>

Target: <METHOD> <path>   (<reference>.<operationId>)
References involved: <reference list>
Combined scopes required: <plan.combinedScopes>   (mandatory -- always emit this line with the scope names from plan.combinedScopes; never omit or summarize it away, even in a terse answer)

## Plan

1. **<Step title>.** <operationId>.
   - Method/path: <step.method> <step.path>
   - Spec: <step.specUrl>
   - Produces: <producedTypes names / relevant response fields>
   - Why: <one line, quoting structural evidence OR a sentence from Summary/description>

2. ... (one block per step.)

## Run it

<fenced bash block with plan.runnable pasted verbatim -- verbatim means every line: the top fill-in block (connection values with their `:?` guards), the rendered auth preamble (token legs + the `ACCESS_TOKEN` capture), the `# Combined scopes required:` header curl-block.js emits, and every step's curl; do not reflow, trim, paraphrase, or summarize the block>

## Sources
- <url 1>
- <url 2>

The auth step(s) appear at the top of the plan list (steps 1, optionally 1a/1b for the two-leg PKCE flow), driven by plan.authBranch and plan.authFlow from composePlan. When authBranch === 'unknown', omit the auth-step block entirely; the plan starts with the target reference's first operation. The "References involved" line includes auth (Shopper Login / SLAS) when authBranch === 'shopper-slas'; AM auth steps cite the canonical account.demandware.com/dwsso/oauth2/access_token URL with a one-line note (see "Account Manager (AM) auth framing" below) -- never a developer.salesforce.com URL.

The ## Run it block is mandatory. The runnable's URL prefix is emitted deterministically by scenario.js from each reference's basePath (SCAPI /checkout/<reference>/v<n>/..., OCAPI Shop /s/${SITEID}/dw/shop/v<n>/..., OCAPI Data /s/-/dw/data/v<n>/...). OCAPI calls also carry a ?client_id=${CLIENT_ID} query param (the auth floor); scenario.js emits that too. You do not reconstruct any of it.

The auth preamble is rendered, not composed. scenario.js emits the token-acquisition legs (PKCE setup, the authorize/login/customers-auth leg, the token exchange, and the ACCESS_TOKEN=$(...) capture) into plan.runnable, deterministically, from plan.authBranch/authFlow/auth. Relay the ## Run it block verbatim – do NOT hand-compose, paraphrase, or "improve" the token legs. This is the same contract as the URL prefix and the # Combined scopes required: line: the script composes, you relay. The prose in this section (branch/flow routing, the request contracts, the AM/OCAPI framing below) exists so you can read and explain what the rendered preamble does – not so you can rebuild it by hand.

Extracting a producer id in a hand-composed edge case -- use jq -r. The rendered preamble already captures the token (ACCESS_TOKEN=$(echo "$TOKEN_RESPONSE" | jq -r .access_token)); you do not write that line. The general rule survives for the one place it's still the model's job: threading a producer id through a hand-composed multi-reference runnable that the renderer didn't emit (e.g. basketId from createBasket, applicableShippingMethods[0].id from getShippingMethodsForShipment). Extract those with jq -r -- e.g. BASKET_ID=$(echo "$BASKET_RESPONSE" | jq -r .basketId) -- matching the idiom scripts/curl-block.js emits. Do NOT hand-roll node -e "...JSON.parse(d)..." or python3 -c "...json.load(...)..." for this; a 200-character Node stdin-reader is not what a support engineer pastes into a terminal. The renderer already begins the runnable with a jq preflight (command -v jq >/dev/null || { echo "this script needs jq (brew install jq, or apt-get install jq)"; exit 1; }) so a missing jq fails loud rather than silently mis-capturing; jq ships with macOS only since Sequoia (15), and Linux / older-macOS users may not have it, which is why that preflight earns its line. Do NOT use the display-context fallback ... || _jq() { cat; } (as in stepped-demo-script): here the value is captured into a shell variable, and falling back to cat would stuff the entire JSON blob into a var and break every downstream call.

The authorization code lives in the 303 Location header, never a JSON body. This is a spec-fidelity fact the rendered preamble already honors, and one you must not "correct" if you're reading the runnable back to the user: both authorizeCustomer and authenticateCustomer are declared with 303 (redirect) responses only – there is no 200 token-less JSON body, and no authorizationCode field anywhere in either operation's response schema. So the rendered capture reads the code from the redirect (curl ... -w '%{redirect_url}', grep code=), and any instinct to ... | jq .authorizationCode or node -e "...JSON.parse(d).authorizationCode" against the authorize/login response is a fabrication – that field does not exist.

authenticateCustomer (POST /oauth2/login) request contract. The registered-B2C login leg is easy to get subtly wrong because the spec states its parameters in prose, not in a formal parameters/requestBody schema (the schema only lists organizationId, Authorization, x-slas-client-auth). The renderer emits this leg from the contract below; keep the contract here so you can verify or explain the rendered /login curl, not so you re-assemble it:

• Authorization: Basic base64(<shopperUserID>:<shopperPassword>) – required header, the shopper's own username:password (NOT the client ID/secret; the client goes in the optional x-slas-client-auth header when strict client auth is enabled).
• Required parameters: code_challenge, channel_id, client_id, redirect_uri. Optional: usid.
• There is no grant_type on /login (that belongs on the /token exchange in getAccessToken), and no response_type, channel_type, login_id, login_password, or locale – those are fabrications. In particular channel_id is required and easy to drop; do not omit it, and do not invent channel_type in its place.

In the rendered registered-B2C runnable, the /login curl carries the shopper Basic-auth header plus exactly those four required params (and usid only if one is threaded) – no grant_type, no login_id/login_password form fields substituted for the Basic header. If a rendered /login leg ever looks otherwise, that's a renderer bug to report, not something to fix by hand-editing the block.

The federated browser seam is interactive by design. The one leg the rendered preamble can not capture headlessly is the registered-federated flow (authorizeCustomer + hint=<idp-name>): the shopper authenticates at an external IDP (Okta, Auth0, …), so no single curl can return the 303. The renderer emits exactly the right shape for this – a # Open this URL in a browser… instruction plus an AUTH_CODE fill-in var (with its :? guard in the top block), rather than a headless capture. Relay that as-is and explain why it's interactive (the external IDP round-trip can't be scraped); do NOT try to replace it with a headless curl, and do NOT insert a read/read -rp prompt mid-script (that breaks the paste-and-run contract). This is a sanctioned seam, not a defect in the runnable.

When a step's only evidence is {kind: 'structural', ...}, the "Why" line should read: " requires in the request; this step's response provides it." When you add a business-logic constraint from prose, quote the relevant sentence and cite the Summary or endpoint URL inline.

Cross-reference steps go in the same Plan list, not in a separate section. If externalInputs[] includes {reference: "auth", ...}, the "References involved" line names auth (the SLAS reference's URL slug; the title on DSC is "Shopper Login (SLAS)") alongside the others, and the SLAS step (or steps – usually authorizeCustomer + getAccessToken) appears as numbered step(s) in the main Plan with their own Spec: URL. Don't write "external input – not part of either reference"; that prose is wrong (the input is part of a DSC reference). Auth steps in particular are mandatory expansions – see "Cross-reference walks" below. The "References involved" line and the Plan must include the auth steps even when the rest of the scenario is scoped to one reference.

Curated request bodies – populating a runtime-required body

The structural walk plans the FK-threading minimum: enough to make the type graph resolve. For some targets that minimum is not enough at runtime. The canonical case: createOrder's only structural input is basketId, so the walk emits a createBasket with an empty {} body – but createOrder rejects an unpopulated basket at submit (400). The set of fields the basket must carry to be submittable is in neither the machine-readable spec (Basket.required is null) nor the basket-prep prose (it states no hard required-set). It is curated runtime knowledge, encoded in shared/products/commerce-b2c/curated-facts.js (as attach: 'producer-body' / attach: 'op-body' entries) and folded in deterministically by scenario.js via scripts/curated-body.js – the same category of encoded fact as the SLAS auth-routing table, not model fabrication.

When scenario.js returns a curatedBody array, one or more of the plan's steps has a curated-fact-backed body. Each element is an advisory {id, attach, typeName, stepSlug, bodyContents:[{field, why}], provenance, confidence:"curated", cite}. stepSlug names the step whose body is populated; attach is one of two modes:

• producer-body – the body hangs on the producer of the target's body-type. typeName is that type (e.g. Basket for createOrder, populated in the createBasket step). This is the "a prepared resource the target won't accept unless it's populated" case.
• op-body – the body hangs on the matched op itself: the target op's own request body is runtime-required even though the spec marks it optional (the type-graph walk emits no body because the request type enumerates no required properties). The canonical case is addPaymentInstrumentToBasket, whose bodyless call 400s "The null value constraint for parameter Body was violated." typeName is null here (there is no produced type); stepSlug is the target op's own slug.

Render each advisory like this (the rules are the same for both modes – they differ only in which step the body lands on):

• The step's body is rendered, not composed – relay it verbatim. The runnable scenario.js emits already carries the stepSlug step's fully populated body. For a producer-body advisory (e.g. createBasket) that is a nested body: productItems, shipments (shipping method + address), a billingAddress, and paymentInstruments with a nested paymentCard, built around a synthetic "Jane Doe" persona, with ${PLACEHOLDER} vars for the instance-specific ids (the product id, the shipping-method id). For an op-body advisory (e.g. addPaymentInstrumentToBasket) it is the target op's own body (paymentMethodId + a nested paymentCard.cardType). Do NOT re-invent, re-nest, or rebuild the body by hand – the deterministic renderer owns its structure, and hand-nesting it risks reintroducing exactly the paymentCard-shape divergence this closes. The instance-ref placeholders surface in the top fill-in block for the user to supply.
• Frame every populated field as a curated business-rule, never as spec. The stepSlug step gets one extra line under its "Why": for producer-body, "The basket must be populated before createOrder accepts it – this is a checkout business-rule (curated), not stated in the spec. See ."; for op-body, "This op's body is runtime-required even though the spec marks it optional – curated, not stated in the spec. See ." Each bodyContents[].why is the per-field reason (the exact 400 it prevents); surface them as the justification, attributed to the curated provenance, not to the step's spec page.
• Do NOT expand the populate work into separate numbered API steps. For a producer-body advisory the whole point is that a prepared basket carries items/shipping/billing/payment in the single createBasket body (the maintainer's preferred, performant single-call shape); breaking addItemToBasket / updateShippingMethodForShipment / updateBillingAddressForBasket / addPaymentInstrumentToBasket out as separate steps is over-decomposition – the basket-prep belongs in the create body. An op-body advisory adds nothing to expand at all: it populates the body of a step already in the plan.

Cross-reference walks

If the sub-agent returns externalInputs: [...], every entry has a reference field naming the DSC reference the input originates in (e.g. {name: "access_token", likelyOrigin: "SLAS", reference: "auth"} – auth is the URL slug DSC publishes the SLAS reference under; its title on the page is "Shopper Login (SLAS)"). That reference is part of DSC – not something outside this skill's universe. Cite it as a reference like any other, with its actual URL slug.

Cross-reference deps split into two categories with different handling rules:

Auth routing -- spec-driven branch + flow choice

Auth steps are always part of the plan when the target's identity resolves to an auth branch this skill recognizes. scenario.js resolves the branch deterministically (via the auth-provider registry in shared/engine/auth-providers.js + B2C's provider set in shared/products/commerce-b2c/auth-providers.js) and returns it as plan.authBranch plus a plan.auth object carrying the resolved tier, token flow, request-auth shape, and per-branch prerequisites. You never pick the branch; render what plan.auth says.

Spec corrections in plan.auth.prerequisites. Some entries in plan.auth.prerequisites are corrections – curated facts that OVERRIDE what a spec's security[]/schema declares (the skill knows them from live verification, not from the spec). A correction is any prerequisite carrying a status field; each renders per its status:

• status: 'active' – render the claim verbatim (do NOT paraphrase – these are precise, and a reworded claim can invert its meaning). Follow it with the scope bounds line (what the evidence covers, and what it does not), a "verified" line summarizing verifiedOn (dates + coordinates, shown as-is – do not compute an age or convert a date to a relative phrase), and the cite URL. When cite is null, the claim itself is the citation contract (same rule as AM auth): say the fact is verified-not-documented rather than inventing a developer.salesforce.com URL.
• status: 'drifted' – do NOT present the claim as current fact. Render a re-verify banner: "This curated correction predates a spec change – re-verify before relying on it. It asserted: <claim>. The spec field <drift.field> no longer matches what it was recorded against." Show drift.saw (what we recorded) against drift.now (what the spec says now). The safe action is the same whether the spec converged toward our correction or moved elsewhere: surface it, do not silently apply the override.

Never suppress a drifted note silently – surfacing the drift IS the point (a stale override trusted blindly is the confidently-wrong failure this skill exists to prevent). Corrections render wherever the branch's prerequisites render; a correction may apply even on the unknown branch (it rides plan.auth.prerequisites regardless of routing).

Prerequisites without a status field are provider prerequisites – render them as before (text + cite). These are the existing {kind, text, cite} entries (the AM tenant-scope note, the OCAPI-settings allowlist note): surface the text line, then the cite URL, or – when cite is null – the note itself as the citation contract (same as AM). Both shapes coexist in the one prerequisites array; the presence of status is what tells a correction apart from a provider prerequisite, so don't expect every entry to carry a claim/status.

Stale-spec caveat on a correction. A correction's drift check runs against whatever spec scenario.js read – and when a refresh fails, that is the last-good cached copy (the top-level staleness array names each reference served stale; see "Staleness warning" under Key invariants). So if the target's reference appears in staleness, the correction's anchor was evaluated against STALE spec data: append to the note – whether it rendered active or drifted – a caveat like "checked against stale spec data – refresh failed; re-verify." A stale-backed active is the dangerous case: it reassures the reader that the override still matches the spec when the drift check never saw the live spec – exactly the confidently-wrong reassurance this layer exists to catch.

Routing keys on the target's reference family first, then its declared scheme -- because SCAPI keys off the scheme but OCAPI does NOT (OCAPI Shop and OCAPI Data declare the same schemes, so the scheme can't disambiguate them):

Target identity	Auth branch	Default within branch
scheme ShopperToken	shopper-slas	SLAS flow chosen by flowSignal (guest + public-client PKCE default)
scheme AmOAuth2, or BearerToken with SLAS_* scopes	am	Private client + client_credentials against https://account.demandware.com/dwsso/oauth2/access_token, scope SALESFORCE_COMMERCE_API:<tenant> + the API scopes
reference family ocapi-shop-*	ocapi-shop	Lightest sufficient tier (see "OCAPI Shop auth" below): client_id-only for the curated public reads, an OCAPI-native customers/auth shopper token for everything else
reference family ocapi-data-*	ocapi-data	AM app token (same dwsso/oauth2/access_token, client_credentials) + the Data request shape
anything else	unknown	No fabricated auth-step block. Plan still composes with the target reference's calls + the spec-declared scope union; the pre-target auth-step block is omitted (this skill has no flow logic for non-Commerce schemes -- Marketing Cloud, Data 360, FSC, Healthcare, etc.)

The skill resolves authBranch from the target automatically; you don't ask the user. Within the SCAPI branches, flowSignal (read from the user's prompt) selects which flow data to render; the OCAPI branches carry their token flow on plan.auth.token instead.

Never route OCAPI on the declared scheme. An OCAPI op's security[] (customers_auth / oauth2_application / client_id) does not tell you Shop vs Data -- the reference family does. scenario.js already routes on family; don't second-guess it by reading the scheme yourself.

SLAS reference URL (canonical citation form). Every SLAS operation cites the SLAS reference at this exact URL shape, with the URL slug auth (NOT shopper-login -- that's the page title, but the URL slug is auth; /references/shopper-login 404s):

• https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authorizeCustomer
• https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authenticateCustomer
• https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getAccessToken
• https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getTrustedSystemAccessToken

Cite with the auth slug verbatim. Do not derive a slug from the page title.

Flow signals -- which prompt phrase maps to which flow

Within the SLAS shopper branch, four signals (default = 'guest'):

Signal	Slugs	Trigger phrases (any one matches)
'guest' (default when no signal detected)	authorizeCustomer (hint=guest) + getAccessToken	none -- this fires when the prompt doesn't specify a registered/TSOB scenario
'registered-b2c'	authenticateCustomer (POST /oauth2/login) + getAccessToken	"registered shopper", "logged-in shopper", "B2C credentials", "username/password login"
'registered-federated'	authorizeCustomer (hint=<idp-name>) + getAccessToken	"federated", "custom IDP", named IDP ("Okta", "Auth0", etc.), "SSO"
'tsob'	getTrustedSystemAccessToken	"trusted system on behalf of", "TSOB", "shopper context as service"

If multiple signals match, the more-specific wins (e.g. "Okta-federated registered shopper" -> 'registered-federated', not 'registered-b2c').

Important default: when the prompt names a registered shopper but doesn't mention federation, default to 'registered-b2c'. Federation is opt-in setup; assume the OOTB platform-IDP path. Customers who use federation almost always say so explicitly; customers who don't, won't volunteer "and we don't have SSO" because they may not know it matters.

Within the AM branch, two signals (default = 'private-cc'):

Signal	Default	Trigger phrases
'private-cc' (default)	Private client + client_credentials against dwsso/oauth2/access_token	none -- this fires by default for AM-routed targets
'public-pkce'	Public client + PKCE against the same endpoint	"public AM client", "AM with PKCE", "AM public-client + PKCE"

The AM 'public-pkce' flow is recognized as an option (Salesforce shipped public-client AM support recently) but never the default; private + client_credentials is the conventional setup for back-end / admin work.

Pass the chosen flowSignal to scenario.js in the stdin JSON alongside target and referenceUrl.

Don't narrate the alternatives. Once the flow signal is decided, the plan emits that flow's steps and only those steps. Don't add a "if you weren't federated, you'd use authenticateCustomer instead" footnote, or "if you wanted guest, you'd add hint=guest" -- that's the opposite of what the user asked. Those alternatives are documented here in SKILL.md so future plans can pick differently; they don't belong in any single plan's output. Exception: the IDP-framing one-liner on registered plans (see "IDP framing" below) is a single sentence that names the federated alternative; that's a deliberate, scoped exception because the OOTB-vs-federated distinction is a known customer trip-hazard.

Stay on the user's chosen API family. When the user asks about OCAPI, the plan answers in OCAPI -- don't volunteer a comparison to SCAPI, a "migration footprint," or a "you should consider SCAPI for new work" note. OCAPI is deprecated but still real; the customer is using it for a reason (existing integration, fastest-path repro, AM-token compatibility). Same direction the other way: a SCAPI question gets a SCAPI answer, no detour through OCAPI's history. The skill's job is to deliver a working plan in the API the user named, not to advocate for a different one. (The migration-direction memory: customers migrate OFF OCAPI to SCAPI, never the reverse -- so even when you do get asked for migration help, the direction is one-way.)

Prefer the latest reference version. Some references are published in multiple versions side by side -- e.g. shopper-baskets (Shopper Baskets V1) and shopper-baskets-v2 (Shopper Baskets V2). scenario.js handles this for you: it scrapes the reference first (which writes the area landing), then bumps a bare reference to its newest sibling automatically and threads the bumped slug through the citations and the runnable's path prefix. You don't run the exposer or rewrite the slug yourself for routine prefer-latest -- the bump is deterministic in code regardless of what order you ran your steps.

Your only job is the one judgment: did the user explicitly pin a version? If they did -- a -v<N> in a pasted .../references/shopper-baskets-v2 URL, prose like "shopper-baskets v1" or "the V1 basket API", or an operationId they tie to a specific version -- pass pinVersion: true in the scenario.js stdin JSON (alongside target and referenceUrl). That suppresses the bump and honors the exact version they named. Absent that signal, leave pinVersion out and let the bump pick latest.

The shared exposer (reference-versions.js) still exists if a user asks "what versions are there?" and you want to enumerate siblings:

echo '{"reference":"shopper-baskets"}' | node shared/scrape/reference-versions.js

It returns {requested, requestedIsVersioned, latest, versions:[{id, version, basePath}], hasMultipleVersions} -- but it is not required for prefer-latest anymore; that decision lives in scenario.js. Note that the id shopper-baskets-v2 maps to the REST path segment shopper-baskets/v2 (from its basePath), not shopper-baskets-v2/v1 -- the runnable already accounts for this because each version's endpoints carry their own basePath.

Scope output -- least-privilege deduped, with meta-scope alternative

composePlan returns combinedScopes already deduped by combinePlanScopes:

• For each operation, the bare <scope> is preferred over <scope>.rw when both are listed in the spec's accepted-scope OR-list (least privilege within one operation).
• Across operations, the union drops bare <scope> when <scope>.rw is independently in the union (.rw covers reads -- configuring both is redundant).
• metaScopeSuggested is true when the deduped union is a strict subset of sfcc.shopper-standard's 20-scope expansion.

Render the scope block in the plan output like this:

Combined SLAS client scopes required:
  <deduped, comma-separated>

(if metaScopeSuggested) Alternatively, configure your SLAS client with `sfcc.shopper-standard` -- a meta-scope that includes everything above plus 19 others. Simpler setup, broader permissions; both are accepted by every operation in this plan.

Never replace the explicit list with the meta-scope; always show both when applicable. Never list bare and .rw together for the same family in the deduped output (the dedup helper enforces this; if you see both, file a bug against shared/products/commerce-b2c/dedupe-scopes.js).

IDP framing -- only on registered-b2c plans

• Guest plans: say nothing about IDP. hint=guest documents itself as bypassing IDP selection; users running the default guest flow don't need to know the platform IDP exists.

• registered-b2c plans: include one line of IDP framing immediately after step 1's title. Example:

  This uses the platform's built-in IDP, which is the OOTB default. The authorizeCustomer (/oauth2/authorize) federation path applies only if your instance has been explicitly configured with a custom IDP (Okta, Auth0, Google, etc.) -- if that's not the case, the platform itself is the IDP and authenticateCustomer is correct.

  This corrects the assumption that "I don't have an IDP" means platform-IDP doesn't apply -- the platform itself is the IDP unless federation is explicitly configured. Customers who hear "IDP" and think "I don't have one" need this primer; the spec's own authorizeCustomer description ("after authenticating a user against an identity provider (IDP)") is technically accurate but actively misleading for the no-federation case.

• registered-federated plans: NO IDP framing. The user already specified federation (Okta, Auth0, etc.) -- their plan uses authorizeCustomer with hint=<idp-name> and the prose stays focused on that flow. Do not add a "if you weren't federated, you'd use authenticateCustomer" footnote; that's the kind of alternative-narration the "Don't narrate the alternatives" rule above specifically prohibits. This applies especially inside the browser-step explanation: it is correct and useful to explain why the federated step needs a real browser (the shopper authenticates at the external IDP, so the 303/code can't be captured headlessly), but explain that using only the federated mechanism itself -- do NOT reach for the B2C contrast to make the point ("...whereas if you weren't federated, authenticateCustomer / POST /oauth2/login returns a 303 you could capture headlessly"). Naming authenticateCustomer or /oauth2/login anywhere in a federated plan -- even as a "headless alternative" aside in an otherwise-correct note -- is the prohibited narration. The federated plan never mentions the B2C login op at all; if you're tempted to write "the alternative is..." or "if not federated...", delete that clause.

Account Manager (AM) auth framing

AM is undocumented on developer.salesforce.com by deliberate Salesforce decision (not a scrape gap). When the auth branch is 'am', the rendered preamble emits the AM token leg (a client_credentials POST to the canonical account.demandware.com/dwsso/oauth2/access_token host, AM_CLIENT_ID/AM_CLIENT_SECRET in a Basic header, scope from combinedScopes + the tenant role); you relay it verbatim. Your job is the matching Plan-list step, which describes that leg so the reader knows what the runnable is doing. That step renders like this:

Step 1 -- Obtain an Account Manager (AM) access token
- Method/path: POST https://account.demandware.com/dwsso/oauth2/access_token
- grant_type=client_credentials
- Basic auth: AM_CLIENT_ID:AM_CLIENT_SECRET
- scope=<from the target endpoint's spec, plus the tenant role -- see below>
- Note: AM has no DSC reference page (deliberate by Salesforce); see the auth guide on the consuming SCAPI/OCAPI reference for setup details.

Never fabricate a developer.salesforce.com URL for AM; the Note: line is the citation contract, and it's the same contract the rendered AM leg honors (the preamble contributes no source for AM).

AM scope must carry the tenant. The AM token request's scope must include SALESFORCE_COMMERCE_API:<tenant> (the instance/tenant, e.g. abcd_001) in addition to the API scopes, space-separated -- e.g. scope=SALESFORCE_COMMERCE_API:abcd_001 sfcc.orders. A bare SALESFORCE_COMMERCE_API role is accepted as a scheme but denied at the resource (403); the tenant suffix flips it to 200 (verified live -- same class of runtime-vs-spec defect as the AM .net->.com host fix). The rendered AM leg emits the tenant as an ${AM_TENANT} fill-in var (surfaced in the top fill-in block with a :? guard), because the instance isn't known at render time; the reader supplies it -- it's derivable from the org id f_ecom_<instance> (so f_ecom_abcd_001 -> abcd_001). scenario.js surfaces this as an am-branch prerequisite note; render it on the AM auth Plan step so the reader knows what ${AM_TENANT} is for.

OCAPI Shop auth (authBranch === 'ocapi-shop')

OCAPI Shop is a three-tier auth ladder; scenario.js returns the resolved tier on plan.auth.tier. Render exactly that tier -- do not add the others:

• plan.auth.tier === 'client-id' (the curated proven-public reads: single-product / category / site GETs). No token at all -- the call carries only ?client_id=<id>. The rendered runnable omits the Authorization header for these and emits no token leg; there is no auth step, just the CLIENT_ID fill-in var in the top block.
• plan.auth.tier === 'shopper' (everything else -- baskets, orders, any write). The call needs a shopper-identity bearer and ?client_id=. The default token flow is OCAPI-native customers/auth (plan.auth.token.flow === 'ocapi-customers-auth'): the rendered preamble emits a POST /customers/auth leg on the ocapi-shop-customers reference with a {"type":"guest"} body, and captures the JWT from the response Authorization header (the token comes back as a response header, not a JSON body, so the rendered capture dumps headers and greps rather than using jq). Cite customers/auth at its ocapi-shop-customers reference URL. The Plan step describes this leg; you relay the rendered curl.

The OCAPI registered-shopper credentials seam. For a registered (not guest) OCAPI shopper, the rendered guest customers/auth leg carries an adjustment comment: swap {"type":"guest"} -> {"type":"credentials"} and add the shopper Basic header (Authorization: Basic base64(<user>:<pass>)). This is the one sanctioned model adjustment on the OCAPI branch – the renderer emits the guest shape by default and flags the swap inline, so make it only when the user's scenario is a registered shopper. (Fuller registered-OCAPI support is a deferred follow-up; today this comment-guided swap is the whole seam.)

The client_id query param is the OCAPI floor -- scenario.js puts it on every OCAPI call in the runnable, and CLIENT_ID is a fill-in var in the top block. Don't remove it; a bare OCAPI call (no client_id) 400s.

SLAS is a prose migration alternative only, never the emitted OCAPI runnable. A SLAS shopper token does work against OCAPI Shop when the client is allowlisted, but the person asking about OCAPI already has an OCAPI client -- defaulting to SLAS would force a second client (or UUID reuse, bad practice). Emit the OCAPI-native flow; you may mention SLAS in one sentence as the migration-forward alternative, but don't render its steps.

scenario.js returns the OCAPI-settings allowlist prerequisite on plan.auth.prerequisites; surface it as a note (it's an instance-config fact the skill can't verify -- the client must be enabled in Business Manager's Open Commerce API Settings).

OCAPI Data auth (authBranch === 'ocapi-data')

OCAPI Data gates on a valid AM app token -- the same dwsso/oauth2/access_token + client_credentials flow as SCAPI Admin (plan.auth.token.flow === 'am-app-token'). Render the AM auth step exactly as in "Account Manager (AM) auth framing" above (canonical token URL, no fabricated DSC URL). The Data call carries ?client_id= (the floor) + the AM bearer, against the Data request shape /s/-/dw/data/v<ver>/... (literal -, no site id -- scenario.js emits this from the reference basePath). Surface the OCAPI-settings prerequisite on plan.auth.prerequisites the same way. Note: an AM Data token needs no SALESFORCE_COMMERCE_API tenant scope (that's the SCAPI-Admin rule); OCAPI authorization is the Business Manager allowlist, and the token's scopes are placeholders.

Decline, don't fabricate, when the target won't resolve

If you cannot resolve the target to a real {reference, slug} -- the reference isn't in the area landing, scenario.js errors, or resolve-target.js returns no candidates -- say so and ask the user for the reference URL. Do NOT invent a slug, and NEVER cite a non-developer.salesforce.com host. In particular do not fall back to documentation.b2c.commercecloud.salesforce.com, salesforcecommercecloud.github.io, an SFCC "OCAPI documentation" host, or any other non-DSC domain -- every citation in this skill's output is a developer.salesforce.com URL (AM's Note: line is the sole documented exception, and it cites account.demandware.com, an auth host, not a docs host). A fabricated slug or an off-domain citation is the confidently-wrong failure this family exists to prevent; an honest "I couldn't resolve <x> -- paste the reference URL" is always the better answer.

Non-auth cross-reference deps – mode choice still applies

Other cross-reference deps (e.g. a Shopper Orders scenario that needs a customer ID producible by Shopper Customers getCustomer, but the user might already have one) have two legitimate handling modes; pick based on what the user asked for:

1. Expansion (preferred when the user wants a runnable end-to-end repro). Warm the cache for the named reference (via scrapeRefresh), re-run the scenario, and integrate the dependency's calls as numbered steps in the main plan. Each integrated step gets the same Spec: URL line as native steps, citing the cross-reference's public DSC URL.

2. Surfacing (preferred when the user is asking a focused question scoped to one reference, or has already obtained the value). Keep the cross-reference dep as a numbered step labelled by its source reference, and tell the user explicitly: "this step belongs to the <reference> reference; say the word and I'll re-run with <reference> warmed and chain the full sub-flow in." Cite the cross-reference's public DSC URL in the step.

The mode choice never applies to auth – that's the auth subsection's job.

What never to write, in either category: "external input – not part of either reference," or "external dep, not in scope" – the input is part of a DSC reference (the one named in externalInputs[].reference); calling it "external" or "out of scope" misrepresents the skill's universe to the user. Always name the source reference and its DSC URL.

What this skill doesn't do

• Doesn't run the plan. Output is a plan + runnable snippet; the engineer executes it in their instance.
• Doesn't invent ordering constraints. If the type graph has no edge and the prose has no ordering statement, the skill emits the structural order and annotates it as such.
• Doesn't resolve environment-specific values (site-ID, client-ID, auth flavor). Those become fill-in vars in the block at the TOP of the runnable, each with a :? preflight that fails loud if unset.
• Doesn't cite local cache paths. sources[] only.
• Doesn't auto-scrape cross-reference dependencies on a cold cache. If the walk surfaces an externalInputs entry (e.g. SLAS for access_token) and the named reference isn't cached yet, the skill warms the cache via scrapeRefresh then re-runs the scenario with the dependency expanded; it doesn't try to walk an unscraped reference. The skill does expand cross-reference deps into multi-reference plans once the cache is warm – see "Cross-reference walks" above.

Prerequisites

Same as dsc-endpoint-help: ~/.cache/dsc-scrape/ writable and Node.js. This skill bundles the shared scrape library at shared/.

Key invariants

• scenario.js owns all cache access; you never touch the cache yourself. scenario.js obtains and refreshes the spec data it needs through the blind-ingress accessor (shared/scrape/cache-access.js) – it scrapes when data is absent or stale, serves the last good copy if a refresh fails, and reads the cached JSON for you. You do not run the scrape library, curl, or a web-fetch tool against a developer.salesforce.com URL, and you do not use shell commands, file-reading tools, or ad hoc parsers on files under ~/.cache/dsc-scrape/ to assemble a plan – pass the target and reference URL to scenario.js and let it return the structured plan. Hand-reading cache files is the failure mode this skill is built to avoid: it bypasses freshness/staleness handling and produces nondeterministic, hand-assembled plans. If scenario.js can't resolve a target, that's a signal to fix the inputs (or report the gap), not to spelunk the cache.

• Staleness warning (mandatory when present). scenario.js emits a staleness array. When it is non-empty, a refresh failed and the plan was built from cached spec data – you MUST open your answer, immediately above the ## Scenario: heading, with:

  ⚠ Stale spec data. Could not refresh <reference>; this plan was built from cache last scraped <scrapedAt>. Verify against the live reference before relying on it.

  Use the absolute <scrapedAt> date verbatim from the staleness entry (it is YYYY-MM-DD…); never convert it to a relative phrase ("3 days ago"). If multiple references are stale, keep one **⚠ Stale spec data.** lead and list each reference + its scrapedAt as a bullet. A stale-backed plan that doesn't say so is the confidently-wrong-answer failure this skill exists to prevent.

• The two judgments that remain yours (everything else is scenario.js's deterministic job): resolving a natural-language goal to an operationId (Flow step 1), and layering business-logic ordering constraints quoted from Summary/description prose (Flow step 4). Don't push these into the script, and don't let the script's determinism tempt you to invent either one.

• Cite only the public DSC URLs in ; never cite local cache paths.