@salesforce/afv-skills 1.63.0 → 1.65.0

package/skills/commerce-merchant-catalog-configure/SKILL.md

@@ -0,0 +1,614 @@
+---
+name: commerce-merchant-catalog-configure
+description: "Use this skill when users want to merchant admin quick-adds a product (pricing/category/entitlement/image atomic), sets up variants (parent + Color/Size/Material children), bulk-imports/exports via CSV, or manages categories (add root/leaf/mid-branch, rename, delete). Trigger when users mention merchant, catalog, management."
+metadata:
+  version: "1.0"
+  accessCheck: "(Commerce.b2bProductVariantsEnabled) || (Commerce.externalProductMediaEnabled) || (Commerce.orgHasCommerceB2BOrB2CEnabled) || (Commerce.webStoreExists) || (Files.csvReadable) || (User.hasApiEnabledPermission) || (User.hasCommerceAdminPermset)"
+---
+
+# Managing Merchant Catalog Management
+
+## When to Use This Skill
+
+Merchant admin quick-adds a product (pricing/category/entitlement/image atomic), sets up variants (parent + Color/Size/Material children), bulk-imports/exports via CSV, or manages categories (add root/leaf/mid-branch, rename, delete). Caps — 5 attrs/set, 200 variants/parent, 100 sets. Import async — fire + auto-poll 15/30/60/120/180s.
+
+## Workflow
+
+1. NO PATHS. ONE clarifying q: singular→quick-add; CSV→bulk-import; "variants/sizes/colors"→variants. Never quote SOR/skill/step names.
+
+2. QUICK-ADD IS ONE ATOMIC CALL. name+SKU+price+category+optional image URL → ONE creation. URL present → SILENT register-product-image-url first, mediaId → productMedia[]. NEVER add-product-media as follow-up (EXISTING products only).
+
+3. URL→mediaId SILENT + AUTOMATIC. Branch A (ExternalMedia,2em) vs B (CMS,20Y) chosen ONCE/session from ExternalProductMediaEnabled. MUTUALLY EXCLUSIVE — no A→B fallback on 404; never expose which ran.
+
+4. VOCAB WALL. Never surface:
+   - Wire: /services/data/…, connect/…, commerce/management/…, /headless/invoke, composite-products, sObject, dispatcher, controller, Aura, className, v66/v67/v69.
+   - Records: Product2, PricebookEntry, Pricebook2, ProductCategory(Product), ProductCatalog, CommerceEntitlementProduct/Policy, BuyerGroup, WebStore, ProductMedia, ProductAttribute(Set), ExternalMedia, ManagedContent, ContentVersion/Document, ElectronicMedia/Group, FieldPermissions.
+   - Ids: any 15/18-char prefix (01t/0ZG/0ZE/0ZC/01s/0YT/0DB/20Y/2em/068/069/0iY/0iU/0iX/05f/2mg/2pm).
+   - Feature-gate/SOR/step/skill/phase names.
+   Merchant vocab: WebStore→"your store"; ProductCategory→"category"; Product2→"product"; unitPrice→"sell price"; listPrice→"was-price"; *Media→"product image"; ProductAttributeSet→"variant options"; use product name ("family"/"parent" only if merchant leads).
+
+5. PLAIN CONFIRMS + RECAPS. Pre-fire: "I'll add '{Name}' to your '{storeName}' store at ${price} (was ${listPrice}), in '{categoryName}', with the image. Proceed?" Post: "'{Name}' is live in your '{storeName}' store — ${price} (was ${listPrice}), in '{categoryName}', with the image." BANNED: JSON, ids, endpoint/record names, per-step narration, bulleted recaps, "Product Id:", tables.
+
+6. ERROR TRANSLATION. On 422 use quick-add-product field→noun map; ONE plain sentence + action. No errorCode/fieldName/endpoint/record leak.
+
+7. STORAGE-BRANCH INTERNAL. "How are images stored?" → "Stored with the product — update/replace anytime from the product page." Never surface ExternalMedia/ManagedContent/preference.
+
+8. AMBIGUITY. ONE clarifying q, never a menu.
+
+9. QUICK-ADD CHECKLIST. Solicit EVERY input before firing. Silent omission = bug.
+   REQUIRED: Store • Name • SKU • Sell price+currency • Category.
+   OPTIONAL (one grouped prompt): Was-price • Image URL • Description.
+   Confirmation MUST name the category. Post-success, offer skipped items in ONE plain sentence.
+
+Category resolution (quick-add + variants):
+     a. Merchant NAMED → resolve silently against store's catalog.
+     b. Else SOQL LEAF only. Leaf = no children (`count() FROM ProductCategory WHERE ParentCategoryId='<cand>'`=0). Childless root IS a leaf. NEVER auto-assign to a container.
+     c. 1 leaf → use silently.
+     d. 2+ leaves → "Which section of your store should {productName} show up in? Options: {name1}, {name2}."
+     e. 0 leaves → offer to add one: "the store doesn't have a category set up yet — want me to add one first?" If merchant says yes → delegate to create-category (rule 13). Do NOT create silently on the fly.
+   Word mismatch: "'{word}' isn't a category in your store yet — want to create it, or use '{default}' for now?" If create → delegate to create-category. Explicit list: render hierarchically.
+
+10. ADD-LATER ALWAYS. Image/Price/Category/Description all patchable in one plain sentence.
+
+11. VARIANTS: SILENT SET REUSE + EXTEND. See list-product-attribute-sets for EXACT/SUPERSET/PARTIAL/NONE + extend-vs-fork. Surface: "Tshirt is live with Color × Size × Material variants."
+
+11a. LIMIT GUARDS. MaxAttrSets=100, MaxItemsPerAttrSet=5, MaxVariationParentProducts=500000, MaxVariationsPerParent=200. Never narrate; surface only on block.
+
+11b. FLS ON NEW CUSTOM FIELDS. See create-product-attribute-custom-field — admin silent FLS POST+poll vs non-admin STOP + admin-gap sentence. Never surface FieldPermissions/PermissionSet/describe/poll.
+
+11c. MAKE-PURCHASABLE + POST-RECAP SILENCE. assign-entitlement-to-variant-family OWNS the ONE recap sentence + HARD ANTI-PATTERNS + POST-RECAP SILENCE + degraded variant. Everything before it is silent progress.
+
+12. BULK-IMPORT CONTRACT. EVERYTHING between file-question (rule 12) and terminal recap (rule 12c) is SILENT except the ONE mapping-table gate (rule 12b). NO per-step narration ("uploading now", "found the catalog", "polling"), NO id/path readouts, NO framework/tool leaks ("task tool", "the SOR says"), NO "I'll do X then Y". If merchant DIDN'T give a file path/attachment, ONE plain q: "Where's the file?" (drag/drop OR path). If merchant already provided it, skip the q — proceed straight to silent upload → derive catalog → list pricebooks/currencies/locales → auto-map (rule 12a) → STOP for mapping gate (rule 12b) → silent import fire + auto-poll ladder → ONE terminal recap sentence (rule 12c → rule 12d).
+
+12a. AUTO-MAP HEURISTICS (get-import-mapper-config). Case-insensitive exact → fuzzy on label. Price cols /price|cost|amount|MSRP/i → pricebooks[] rows; parse currency substring, match list-store-pricebooks. Slug cols /slug|permalink|seo-url/i → slugs[] with list-store-locales default. Category/entitlement cols → arrays. Media cols grouped by trailing digit. Variation cols → variation* sections. Zero price cols → skip pricebooks silently. Zero slug cols → skip slugs silently.
+
+12b. HARD GATE — MAPPING CONFIRMATION. After auto-map, agent MUST print the mapping table AND stop. Do NOT fire import-products-csv until merchant explicitly approves ("looks good", "go ahead", "yes", "proceed", equivalent). Print-and-fire in the same turn is a BUG. Merchant vocab only: "SKU → Product SKU"; "Price (sale) USD → Pricebook 'B2B USD' (USD)  [N others]"; "Slug en_US → Slug (en_US)"; "Media URL 1 / Title 1 → Product image 1". Merchant edits by naming column. Re-render only affected rows on edit. NEVER print section names (product/pricebooks/slugs/media_*), SF field names (StockKeepingUnit, IsActive, ContentVersion), or ids (068/01s/1Ce/0Zu/0ZG/0ZS/704/750). Close the table with exactly: "Okay to import, or want to change anything?"
+
+12c. TERMINAL RECAP — ONE SENTENCE. Success template (exact): "Imported {N} products into your '{storeName}' store{, {M} skipped — I can pull the details}." Failure: "Import didn't complete — {reason}. Want me to retry with the same file?" Errors fetched ON DEMAND (importErrorsResource), never eagerly. POST-RECAP SILENCE — no follow-ups.
+GOOD: "Imported 3 products into your 'Acme B2B Store' store, no issues."
+BAD (all rule 12d violations): bullet-list breakdowns, ContentVersion/Job/Product ids, "product page: /lightning/r/…", "1 product updated (SKU 6010007 — Alpine Supply CO2 Cartridge)", quoted CSV headers in the recap, "2 pricebook entries updated", "if you want Insert next time change X", ANY sentence after the recap sentence.
+
+12d. RECAP BAN LIST. In the terminal recap sentence, NEVER include: any 15/18-char id (068/01s/1Ce/0Zu/0ZG/0ZS/704/750/01t/2em/20Y/069), any endpoint/URL/path (/lightning/…, /services/…, connect/…, commerce/…), any framework/tool name ("task tool", "the SOR", "Codey", "MCP"), any API field name ("importOperationType", "Upsert", "ContentVersion", "PricebookEntry"), any quoted existing record ("SKU 6010007 — Alpine Supply CO2 Cartridge"), any bullet list / row count / follow-up tip / "next time try X" / "product page:" link. Recap is ONE sentence in merchant vocab. Anything else is a bug.
+
+13. CATEGORY MANAGEMENT (add/rename/delete). Merchant vocab only — "category", "section", "group of products". Never surface ProductCategory / CatalogId / ParentCategoryId / 0ZG / 0ZS.
+
+Store's catalog is derived silently from the store (derive-catalog-from-webstore). Merchant never picks/names the catalog.
+
+13a. ADD (create-category). Any level supported — top-level (root) OR nested (under an existing category). Solicit BOTH inputs before firing:
+     - Name (required).
+     - Parent — ONE plain question: "Should '{name}' be a top-level category, or nested under an existing one? If nested, which one?"
+       • "top-level" / "root" / no parent → ParentCategoryId=null.
+       • Nested → resolve merchant's parent word against store's catalog SILENTLY. Multiple matches → "There's more than one '{word}' — which one? {name1} (under {parent1}), {name2} (top-level)." Zero matches → "'{word}' isn't a category yet — want that as a top-level category, or under something else?" One match → use silently.
+     Confirm ONCE: "I'll add '{name}' {as a top-level category | under '{parentName}'}. Proceed?" Post: "'{name}' is live {as a top-level category | under '{parentName}'} — you can now put products in it."
+
+13b. RENAME (update-category). Rename only. Rule-0 confirmation gate with current+new name: "I'll rename '{currentName}' to '{newName}'. Proceed?" Post: "Renamed to '{newName}'." Never surface Name/PATCH/sObject.
+
+13c. DELETE (delete-category). DESTRUCTIVE-OP HARD GATE — server does NOT block. Deleting a category with products silently drops those products' category assignments; buyers stop seeing them under that section. Pre-check product count SILENTLY (list-categories query returns NumberOfProducts). Gate templates:
+     - 0 products AND no child categories → single confirm: "I'll delete the '{name}' category. Proceed?" Post: "Deleted '{name}'."
+     - N products (>0) → "Heads up — '{name}' has {N} product{s} in it. If I delete it, {those products stay live but lose their spot in this section | that product stays live but loses its spot in this section}. Want me to move {them|it} to another category first, or go ahead and delete?" If merchant asks to move → delegate to assign-product-to-category. If merchant confirms delete → fire.
+     - Has child categories → BLOCK. "'{name}' has other categories nested under it ({childCount}). Delete or move those first, then I can delete '{name}'." NEVER auto-cascade — the platform will, but the merchant hasn't consented to losing the whole subtree.
+     Never surface: 0ZG ids, ProductCategoryProduct, cascade, DELETE verb, sObject.
+
+13d. LIST-FOR-BROWSING (list-categories). Merchant asks "what categories do I have?" / "show my sections" → single hierarchical readout with product counts. Format: parent categories at top-level with "({N} products)" suffix, children indented one level with "({M} products)". Empty catalog → "This store doesn't have any categories yet — want to add one?" Never surface ids/CatalogId/NumberOfProducts field name.
+
+## Critical Constraints
+
+**Preconditions:**
+
+- CommerceAdmin permset. (check: `User.hasCommerceAdminPermset`)
+- B2B Commerce enabled. (check: `Commerce B2B or B2C enabled`)
+- Caller knows a B2B WebStore id (0ZE). (check: `Commerce.webStoreExists`)
+- Bulk-import only — CSV available (drag/drop OR path); agent uploads via upload-csv-to-files. (check: `Files.csvReadable`)
+- Variants only — B2BProductVariants ON + Product2 Sharing=Public. (check: `Commerce.b2bProductVariantsEnabled`)
+- External-media only — ExternalProductMediaEnabled ON. (check: `Commerce.externalProductMediaEnabled`)
+- API Enabled permission. (check: `API Enabled permission`)
+
+**Operational rules:**
+
+- INTERNAL — never quote. Capability blurb only.
+
+**Destructive operations — require explicit user confirmation:**
+
+- **`delete-category`** — Delete a category from the store's catalog. Destructive-op hard gate — server does NOT block on assigned products; cascade drops ProductCategoryProduct rows silently.
+  - Rollback: {'operation': 'none_available', 'note': 'DELETE on ProductCategory is IRREVERSIBLE. ProductCategoryProduct junction rows are cascade-dropped by the platform, not recoverable via sObject POST (would need re-insert per (Product,Category) pair). Merchant re-creates via create-category + re-assigns via assign-product-to-category.'}
+
+## Verification Checklist
+
+After every write operation, confirm the effect by re-reading state:
+
+- After `export-products-csv`: call `poll-export-job` (`GET /commerce/management/export/product/jobs`)
+
+## Operations Reference
+
+Operations grouped by purpose. Use these as the building blocks for the workflows above.
+
+### Summary
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `upload-csv-to-files` | write | implemented | `POST /sobjects/ContentVersion` | — |
+| `derive-catalog-from-webstore` | read | implemented | `GET /query` | — |
+| `list-store-pricebooks` | read | implemented | `GET /query` | — |
+| `list-org-currencies` | read | implemented | `GET /query` | — |
+| `list-store-locales` | read | implemented | `GET /query` | — |
+| `get-import-mapper-config` | read | implemented | `GET /commerce/management/custom/import/mapper-config/{importObjectType}` | — |
+| `import-products-csv` | write | implemented | `POST /commerce/management/custom/import/product/jobs` | `upload-csv-to-files`, `derive-catalog-from-webstore`, `get-import-mapper-config` |
+| `poll-import-job` | read | implemented | `GET /commerce/management/custom/import/product/jobs/{jobId}` | `import-products-csv` |
+| `register-product-image-url` | write | implemented | `POST /sobjects/ExternalMedia` | — |
+| `quick-add-product` | write | implemented | `POST /commerce/management/webstore/{webstoreId}/composite-products` | — |
+| `assign-product-to-category` | write | implemented | `POST /sobjects/ProductCategoryProduct` | — |
+| `list-categories` | read | implemented | `GET /query` | — |
+| `create-category` | write | implemented | `POST /sobjects/ProductCategory` | `derive-catalog-from-webstore`, `list-categories` |
+| `update-category` | write | implemented | `PATCH /sobjects/ProductCategory/{id}` | `list-categories` |
+| `delete-category` | delete | implemented | `DELETE /sobjects/ProductCategory/{id}` | `list-categories` |
+| `list-product-attribute-sets` | read | implemented | `GET /query` | — |
+| `create-product-attribute-custom-field` | write | implemented | `POST /tooling/sobjects/CustomField` | — |
+| `create-product-attribute-set` | write | implemented | `POST /composite` | `create-product-attribute-custom-field` |
+| `add-attribute-to-existing-set` | write | implemented | `POST /sobjects/ProductAttributeSetItem` | — |
+| `backfill-variant-attribute-value` | write | implemented | `PATCH /sobjects/ProductAttribute/{id} (after GET /query for target ids)` | — |
+| `create-master-product` | write | implemented | `POST /composite` | `create-product-attribute-set` |
+| `create-variant-product` | write | implemented | `POST /composite` | `create-master-product` |
+| `set-variant-family-pricing` | write | implemented | `POST /composite` | `create-master-product`, `create-variant-product` |
+| `assign-entitlement-to-variant-family` | write | implemented | `POST /composite` | `create-master-product`, `create-variant-product` |
+| `add-product-media` | write | implemented | `POST /sobjects/ProductMedia` | — |
+| `export-products-csv` | write | implemented | `POST /commerce/management/export/product/jobs` | `derive-catalog-from-webstore` |
+| `poll-export-job` | verify | implemented | `GET /commerce/management/export/product/jobs` | `export-products-csv` |
+
+### Dependency graph
+
+```mermaid
+graph TD
+  upload_csv_to_files["upload-csv-to-files (write)"]
+  derive_catalog_from_webstore["derive-catalog-from-webstore (read)"]
+  list_store_pricebooks["list-store-pricebooks (read)"]
+  list_org_currencies["list-org-currencies (read)"]
+  list_store_locales["list-store-locales (read)"]
+  get_import_mapper_config["get-import-mapper-config (read)"]
+  import_products_csv["import-products-csv (write)"]
+  poll_import_job["poll-import-job (read)"]
+  register_product_image_url["register-product-image-url (write)"]
+  quick_add_product["quick-add-product (write)"]
+  assign_product_to_category["assign-product-to-category (write)"]
+  list_categories["list-categories (read)"]
+  create_category["create-category (write)"]
+  update_category["update-category (write)"]
+  delete_category["delete-category (delete)"]
+  list_product_attribute_sets["list-product-attribute-sets (read)"]
+  create_product_attribute_custom_field["create-product-attribute-custom-field (write)"]
+  create_product_attribute_set["create-product-attribute-set (write)"]
+  add_attribute_to_existing_set["add-attribute-to-existing-set (write)"]
+  backfill_variant_attribute_value["backfill-variant-attribute-value (write)"]
+  create_master_product["create-master-product (write)"]
+  create_variant_product["create-variant-product (write)"]
+  set_variant_family_pricing["set-variant-family-pricing (write)"]
+  assign_entitlement_to_variant_family["assign-entitlement-to-variant-family (write)"]
+  add_product_media["add-product-media (write)"]
+  export_products_csv["export-products-csv (write)"]
+  poll_export_job["poll-export-job (verify)"]
+  upload_csv_to_files --> import_products_csv
+  derive_catalog_from_webstore --> import_products_csv
+  get_import_mapper_config --> import_products_csv
+  import_products_csv --> poll_import_job
+  derive_catalog_from_webstore --> create_category
+  list_categories --> create_category
+  list_categories --> update_category
+  list_categories --> delete_category
+  create_product_attribute_custom_field --> create_product_attribute_set
+  create_product_attribute_set --> create_master_product
+  create_master_product --> create_variant_product
+  create_master_product --> set_variant_family_pricing
+  create_variant_product --> set_variant_family_pricing
+  create_master_product --> assign_entitlement_to_variant_family
+  create_variant_product --> assign_entitlement_to_variant_family
+  derive_catalog_from_webstore --> export_products_csv
+  export_products_csv --> poll_export_job
+```
+
+### Read operations
+
+#### `derive-catalog-from-webstore`
+
+Bulk-import prep — resolves the store's ProductCatalogId silently.
+
+**Call:** `GET /query`   — status: `implemented`
+
+**Inputs:**
+
+- `webstoreId` *(`String`)* — 0ZE.
+
+**Rollback:** {'operation': 'none_needed', 'note': 'Read-only.'}
+
+#### `list-store-pricebooks`
+
+Bulk-import prep — active pricebooks attached to the store (mapping-table picker).
+
+**Call:** `GET /query`   — status: `implemented`
+
+**Inputs:**
+
+- `webstoreId` *(`String`)* — 0ZE.
+
+**Rollback:** {'operation': 'none_needed', 'note': 'Read-only.'}
+
+#### `list-org-currencies`
+
+Bulk-import prep — active currencies (multi-currency picker).
+
+**Call:** `GET /query`   — status: `implemented`
+
+**Rollback:** {'operation': 'none_needed', 'note': 'Read-only.'}
+
+#### `list-store-locales`
+
+Bulk-import prep — supported languages for slug mapping.
+
+**Call:** `GET /query`   — status: `implemented`
+
+**Inputs:**
+
+- `webstoreId` *(`String`)* — 0ZE.
+
+**Rollback:** {'operation': 'none_needed', 'note': 'Read-only.'}
+
+#### `get-import-mapper-config`
+
+Bulk-import prep — fetches column catalog for CSV mapping.
+
+**Call:** `GET /commerce/management/custom/import/mapper-config/{importObjectType}`   — status: `implemented`
+
+**Inputs:**
+
+- `importObjectType` *(`String`)* — Always "Product". Category/Pricing → UNSUPPORTED_MODE.
+- `storeId` *(`String`)* — 0ZE. Omit → org-wide defaults (wrong store risk).
+
+**Rollback:** {'operation': 'none_needed', 'note': 'N/A.'}
+
+#### `poll-import-job`
+
+Import job status. Poll ladder 15/30/60/120/180s until endTime.
+
+**Call:** `GET /commerce/management/custom/import/product/jobs/{jobId}`   — status: `implemented`
+
+**Inputs:**
+
+- `jobId` *(`String`)* — Job id. Lost → GET /last-job.
+
+**Depends on:** `import-products-csv`
+
+**Rollback:** {'operation': 'none_needed', 'note': 'Read-only op. No rollback.'}
+
+#### `list-categories`
+
+Store's category tree with product counts. Powers rule 13a parent resolution, rule 13c delete gate, rule 13d readout, and rule 11c leaf resolution.
+
+**Call:** `GET /query`   — status: `implemented`
+
+**Inputs:**
+
+- `webstoreId` *(`String`)* — 0ZE. Drives the catalog subquery — never asked directly.
+
+**Rollback:** {'operation': 'none_needed', 'note': 'Read-only.'}
+
+#### `list-product-attribute-sets`
+
+Variants discovery (silent). Lists sets+items ONCE to drive rule-11.
+
+**Call:** `GET /query`   — status: `implemented`
+
+### Write operations
+
+#### `upload-csv-to-files`
+
+Bulk-import prep — uploads merchant CSV to Files, returns 068 ContentVersionId.
+
+**Call:** `POST /sobjects/ContentVersion`   — status: `implemented`
+
+**Inputs:**
+
+- `fileName` *(`String`)* — CSV file name (Title + PathOnClient).
+- `fileContentBase64` *(`String`)* — base64-encoded CSV bytes → VersionData.
+
+**Rollback:** {'operation': 'sobject_delete', 'note': 'DELETE ContentDocument (parent) if job never fires. Terminal job → keep for audit.'}
+
+#### `import-products-csv`
+
+Async (10s-5min). Kicks import; poll-import-job auto-follows.
+
+**Call:** `POST /commerce/management/custom/import/product/jobs`   — status: `implemented`
+
+**Inputs:**
+
+- `importContext` *(`String (enum)`)* — "Api" for direct REST callers.
+- `importOperationType` *(`String (enum)`)* — Insert/Update/Upsert (Upsert recommended).
+- `columnMappings` *(`Object`)* — Nested per-section object. product/variationAttributeSet/variationParentInfo → OBJECT {sfField:csvHeader}. categories/entitlementPolicies/media_*/variationAttributes → ARRAY of per-row objects (cap maxAllowed). pricebooks → ARRAY [{Price:csvHeader,PricebookId:01s,CurrencyCode:ISO}]. slugs → ARRAY [{Slug:csvHeader,LanguageCode:code}]. product MUST include Name + one of Id/ExternalId/StockKeepingUnit.
+- `webstoreId` *(`String`)* — 0ZE → globalImportParameters.webstoreId (NOT storeId).
+- `productCatalogId` *(`String`)* — 0ZS — derived from WebStoreCatalog, not asked.
+- `entitlementPolicyId` *(`String`)* — 1Ce — from mapper `defaults.entitlementPolicy.id`.
+- `cmsWorkspaceId` *(`String`)* — 0Zu — from mapper `defaults.CMSWorkspace.id`.
+- `contentVersionId` *(`String`)* — 068 ContentVersion id (from upload-csv-to-files).
+  - **Source:** output of `upload-csv-to-files`
+- `delimiter` *(`String`)* — CSV delimiter (default comma).
+
+**Depends on:** `upload-csv-to-files`, `derive-catalog-from-webstore`, `get-import-mapper-config`
+
+**Rollback:** {'operation': 'cancel-import-job', 'note': 'PATCH `{"status":"Cancelled"}` while running. Terminal = no-op. Created rows must be deleted manually.'}
+
+#### `register-product-image-url`
+
+INTERNAL. URL→mediaId for composite-products. A (v69 ExternalMedia→2em) or B (v67 cms/contents→20Y). Both feed same slot.
+
+**Call:** `POST /sobjects/ExternalMedia`   — status: `implemented`
+
+**Inputs:**
+
+- `imageUrl` *(`String`)* — https URL ≤1000 chars.
+- `productName` *(`String`)* — Title + AlternateText.
+- `contentSpaceId` *(`String`)* — Branch B only. 0Zu (once/session).
+- `apiName` *(`String`)* — Branch B only.
+
+**Rollback:** {'operation': 'sobject_delete', 'note': 'A → DELETE ExternalMedia/{2em}. B → DELETE cms/contents/{20Y}.'}
+
+#### `quick-add-product`
+
+Atomic — Product2 + Standard PBE + Strikethrough PBE + PCP/category + ProductMedia in ONE POST. 201/productId or 422/errorDetails.
+
+**Call:** `POST /commerce/management/webstore/{webstoreId}/composite-products`   — status: `implemented`
+
+**Inputs:**
+
+- `webstoreId` *(`String`)* — 0ZE WebStore id (path).
+- `productFields` *(`Object`)* — Nested object — Name, ProductCode (SKU), StockKeepingUnit=SKU, Family, IsActive=true.
+- `categoryIds` *(`Array<String>`)* — 0ZG ids. First=primary. Rule-11c.
+- `productPricing` *(`Object`)* — Nested object {currencyISOCode,unitPrice,listPrice}. unitPrice→Standard PBE; listPrice→Strikethrough PBE.
+- `productMedia` *(`Array<Object>`)* — Optional array of {developerName,mediaId}. developerName MUST be "productListImage" or "productDetailImage" (ElectronicMediaGroup.DeveloperName — NOT an arbitrary label). Emit BOTH entries with same mediaId. 2em/20Y interchangeable.
+- `attributeSetInfo` *(`Object`)* — Variation flow only.
+
+**Rollback:** {'operation': 'sobject_delete', 'note': 'DELETE Product2/{productId} cascades to PBE/PCP/ProductMedia. Irreversible.'}
+
+#### `assign-product-to-category`
+
+POST ProductCategoryProduct (IsPrimaryCategory=FALSE for quick-add). Reassign = DELETE prior PCP.
+
+**Call:** `POST /sobjects/ProductCategoryProduct`   — status: `implemented`
+
+**Inputs:**
+
+- `productId` *(`String`)* — 01t. Variants → MASTER only.
+- `categoryId` *(`String`)* — 0ZG. Must be in store's catalog; never a root container.
+- `isPrimaryCategory` *(`Boolean`)* — Default true.
+
+**Rollback:** {'operation': 'sobject_delete', 'note': 'DELETE ProductCategoryProduct/{pcp_id}. 404 on retry OK.'}
+
+#### `create-category`
+
+Add a category to the store's catalog. Supports any hierarchy level — top-level (ParentCategoryId=null), leaf (ParentCategoryId=leaf-parent), or mid-branch (ParentCategoryId=intermediate).
+
+**Call:** `POST /sobjects/ProductCategory`   — status: `implemented`
+
+**Inputs:**
+
+- `name` *(`String`)* — Category display name (Name field, ≤200 chars).
+- `webstoreId` *(`String`)* — 0ZE. Drives catalogId derivation — never asked.
+- `productCatalogId` *(`String`)* — 0ZS. Silent — never surfaced.
+- `parentCategoryId` *(`String`)* — 0ZG parent Id, or null/omitted for top-level. Rule 13a resolves merchant's parent word silently.
+
+**Depends on:** `derive-catalog-from-webstore`, `list-categories`
+
+**Rollback:** {'operation': 'sobject_delete', 'note': 'DELETE ProductCategory/{category_id}. Note — if products already assigned via ProductCategoryProduct, deletion cascades those junction rows silently.'}
+
+#### `update-category`
+
+Rename a category. PATCH Name only — no other field changes in scope.
+
+**Call:** `PATCH /sobjects/ProductCategory/{id}`   — status: `implemented`
+
+**Inputs:**
+
+- `categoryId` *(`String`)* — 0ZG target category Id. Merchant names the category; agent resolves silently.
+- `newName` *(`String`)* — New display name (≤200 chars).
+
+**Depends on:** `list-categories`
+
+**Rollback:** {'operation': 'sobject_update', 'note': 'PATCH Name back to prior value. Note — no server-side undo.'}
+
+#### `create-product-attribute-custom-field`
+
+Variants picklist CustomField on ProductAttribute. Returns Tooling Id.
+
+**Call:** `POST /tooling/sobjects/CustomField`   — status: `implemented`
+
+**Inputs:**
+
+- `FullName` *(`String`)* — ProductAttribute.<apiName>__c
+- `label` *(`String`)* — Label.
+- `type` *(`String (enum)`)* — Picklist.
+- `values` *(`Array<String>`)* — Values (locked at create).
+- `restricted` *(`Boolean`)* — true.
+
+**Rollback:** {'operation': 'metadata_delete', 'note': 'DELETE Tooling CustomField/{id}. Access errors = silent no-op.'}
+
+#### `create-product-attribute-set`
+
+Variants ProductAttributeSet grouping the parent CFs. Max 5 items; 1 set/parent.
+
+**Call:** `POST /composite`   — status: `implemented`
+
+**Inputs:**
+
+- `name` *(`String`)* — Set name.
+- `description` *(`String`)* — Optional.
+- `assignedAttributeFieldIds` *(`Array<String>`)* — 00N Tooling Ids ≤5. Field=ID not apiName.
+- `groupedByAttributeId` *(`String`)* — One id gets IsGroupedBy=true.
+
+**Depends on:** `create-product-attribute-custom-field`
+
+**Rollback:** {'operation': 'sobject_delete', 'note': 'DELETE ProductAttributeSet/{id} — cascades to items. Not reversible.'}
+
+#### `add-attribute-to-existing-set`
+
+Rule-11 EXTEND. Adds one attr to existing set. After custom-field, before backfill.
+
+**Call:** `POST /sobjects/ProductAttributeSetItem`   — status: `implemented`
+
+**Inputs:**
+
+- `ProductAttributeSetId` *(`String`)* — 0iY set Id.
+- `Field` *(`String`)* — Tooling CustomField Id (00Nxxx), NOT apiName. Passing apiName → INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST.
+- `Sequence` *(`Integer`)* — Display order.
+
+#### `backfill-variant-attribute-value`
+
+Rule-11 EXTEND. Backfills existing variants with a default value. HARD GATE — prompt for default up front.
+
+**Call:** `PATCH /sobjects/ProductAttribute/{id} (after GET /query for target ids)`   — status: `implemented`
+
+**Inputs:**
+
+- `ProductAttributeSetId` *(`String`)* — Extended set.
+- `fieldApiName` *(`String`)* — e.g. Material__c (include __c).
+- `defaultValue` *(`String`)* — Default applied to ALL existing children. Must match one of the picklist values. HARD GATE.
+
+#### `create-master-product`
+
+Variants parent. Composite — Product2 Type=Base + ProductAttributeSetProduct.
+
+**Call:** `POST /composite`   — status: `implemented`
+
+**Inputs:**
+
+- `Name` *(`String`)* — Parent name.
+- `ProductCode` *(`String`)* — Parent SKU (org-unique).
+- `StockKeepingUnit` *(`String`)* — =ProductCode.
+- `Family` *(`String`)* — Optional.
+- `attributeSetId` *(`String`)* — 0iY set id.
+
+**Depends on:** `create-product-attribute-set`
+
+**Rollback:** {'operation': 'sobject_delete', 'note': 'DELETE master Product2 (variants FIRST — VariantParentId blocks master).'}
+
+#### `create-variant-product`
+
+Variants children. Composite — Product2 + ProductAttribute per child.
+
+**Call:** `POST /composite`   — status: `implemented`
+
+**Inputs:**
+
+- `masterProductId` *(`String`)* — 01t master.
+- `variants` *(`Array<Object>`)* — {Name,ProductCode,StockKeepingUnit,Family,attributes:{Color__c,…}} per variant. Attr keys=picklist fields in master set.
+
+**Depends on:** `create-master-product`
+
+**Rollback:** {'operation': 'sobject_delete', 'note': 'DELETE each variant Product2. BEFORE master (VariantParentId blocks).'}
+
+#### `set-variant-family-pricing`
+
+Variants pricing. Standard PBEs then Store PBEs — order matters.
+
+**Call:** `POST /composite`   — status: `implemented`
+
+**Inputs:**
+
+- `masterProductId` *(`String`)* — 01t master.
+- `variantProductIds` *(`Array<String>`)* — 01t variant ids.
+- `unitPrice` *(`Number`)* — Sell price.
+- `listPrice` *(`Number`)* — Optional was-price.
+- `storePricebookIds` *(`Array<String>`)* — 01s store pricebooks.
+- `standardPricebookId` *(`String`)* — 01s Standard PB (first).
+
+**Depends on:** `create-master-product`, `create-variant-product`
+
+**Rollback:** {'operation': 'sobject_delete', 'note': 'DELETE each PBE Id. Standard first → cascades custom entries.'}
+
+#### `assign-entitlement-to-variant-family`
+
+Variants entitlement. CommerceEntitlementProduct across master+variants × policies. Without this buyers see nothing.
+
+**Call:** `POST /composite`   — status: `implemented`
+
+**Inputs:**
+
+- `masterProductId` *(`String`)* — 01t master.
+- `variantProductIds` *(`Array<String>`)* — 01t variant ids.
+- `entitlementPolicyIds` *(`Array<String>`)* — 2rt policy ids.
+
+**Depends on:** `create-master-product`, `create-variant-product`
+
+**Rollback:** {'operation': 'sobject_delete', 'note': 'DELETE each CommerceEntitlementProduct Id.'}
+
+#### `add-product-media`
+
+Attach image URL to EXISTING product. Silent — 2× ProductMedia (List+Detail). NOT for quick-add.
+
+**Call:** `POST /sobjects/ProductMedia`   — status: `implemented`
+
+**Inputs:**
+
+- `productId` *(`String`)* — 01t.
+- `imageUrl` *(`String`)* — HTTPS URL.
+- `altText` *(`String`)* — Screen-reader text. Skippable.
+- `title` *(`String`)* — Optional; defaults to Name.
+
+**Rollback:** {'operation': 'sobject_delete', 'note': 'DELETE each ProductMedia (2pm). Underlying media record NOT deleted.'}
+
+#### `export-products-csv`
+
+Async export (10s-2min). Store-scoped SOQL over Product2 → CSV in Files.
+
+**Call:** `POST /commerce/management/export/product/jobs`   — status: `implemented`
+
+**Inputs:**
+
+- `productsInCompositeList` *(`String`)* — Source: output of derive-catalog-from-webstore (for the store-wide 0ZS catalog id), merchant.confirmedColumns
+(from the pre-fire columns gate, see agent_guidance rule 1), and merchant.exportScope (either "catalog"
+default or "category" with a merchant-picked 0ZG).
+
+Despite the wire field name, this is a SOQL SELECT string against Product2 (LIMIT 300000), NOT a
+CompositeList Id. The SELECT list becomes the CSV column headers; the WHERE clause scopes the export
+via a subquery on ProductCategoryProduct.CatalogId (store-wide) or ProductCategoryProduct.ProductCategoryId
+(category-scoped). Agent composes the full string just before firing. Raw product ids in the WHERE clause
+fail accept-stage validation — always route through the ProductCategoryProduct join.
+
+**Depends on:** `derive-catalog-from-webstore`
+
+**Rollback:** {'operation': 'none_available', 'note': 'Export cannot be cancelled. Post-run — DELETE ContentDocument.'}
+
+### Verify operations
+
+#### `poll-export-job`
+
+Verify + poll — export job status. Ladder 15/30/60/120/180s until endTime populates. Confirms the export-products-csv write landed.
+
+**Call:** `GET /commerce/management/export/product/jobs`   — status: `implemented`
+
+**Inputs:**
+
+- `jobId` *(`String`)* — Job id captured from the export POST. Used client-side to filter the collection response.
+
+**Depends on:** `export-products-csv`
+
+**Rollback:** {'operation': 'none_needed', 'note': 'Read-only op. No rollback.'}
+
+### Destructive operations
+
+#### `delete-category`
+
+Delete a category from the store's catalog. Destructive-op hard gate — server does NOT block on assigned products; cascade drops ProductCategoryProduct rows silently.
+
+**Call:** `DELETE /sobjects/ProductCategory/{id}`   — status: `implemented`
+
+**Inputs:**
+
+- `categoryId` *(`String`)* — 0ZG target category Id. Merchant names the category; agent resolves silently.
+
+**Depends on:** `list-categories`
+
+**Rollback:** {'operation': 'none_available', 'note': 'DELETE on ProductCategory is IRREVERSIBLE. ProductCategoryProduct junction rows are cascade-dropped by the platform, not recoverable via sObject POST (would need re-insert per (Product,Category) pair). Merchant re-creates via create-category + re-assigns via assign-product-to-category.'}
+
+## Notes
+
+Act 2 of b2b-store-setup. Consumes a WebStore from merchant-storefront-lifecycle.
+
+Recovery: import timeout → GET .../import/product/last-job; resume or retry. 500 "another import in progress" → wait 60-120s+retry. Poll 404 → jobId expired (~7d). create-variant 500 UNABLE_TO_LOCK_ROW → serialize+retry. 401 re-auth. 403 = missing CommerceAdmin/userIsStoreMerchandiser.
+
+Out of scope: CSV upload, product deletion, catalog/pricebook creation, cross-catalog moves, moving a category to a new parent (rename-in-place only), category image (ProductCategoryMedia). Category ADD/RENAME/DELETE are in scope (rule 13, create-category / update-category / delete-category).