@salesforce/afv-skills 1.5.1 → 1.5.2

package/skills/creating-b2b-commerce-store/references/store-vs-storefront.md

@@ -0,0 +1,169 @@
+# Commerce Store vs Storefront: Technical Reference
+
+## Overview
+
+Understanding the distinction between Commerce Store and Storefront is critical for successful Commerce B2B development. This document provides technical details about these two components and explains why they must be created in a specific order.
+
+---
+
+## The Two Components
+
+### 1. Commerce Store (Backend Data)
+
+**What it is:**
+- Runtime data and configuration created in the Salesforce org
+- NOT source-controllable metadata
+- Created through Commerce app UI
+
+**What it includes:**
+- Store configuration and settings
+- Default buyer groups (associated with Accounts)
+- Entitlement policies (who can see which products)
+- Pricing policies and price book mappings
+- Payment gateway configuration (Stripe, Adyen, etc.)
+- Tax provider configuration (Avalara, Vertex, manual)
+- Shipping methods and configurations
+- Product catalog associations
+- Inventory locations
+- Search index configurations
+
+**Where it lives:**
+- Data records in standard Commerce objects:
+  - `WebStore` - Store settings and configuration
+  - `BuyerGroup` - Account-based buyer segments
+  - `EntitlementPolicy` - Product visibility rules
+  - `CommerceEntitlementProduct` - Product-policy associations
+  - `ProductCatalog` - Catalog definitions
+  - `Pricebook2` - Price books
+  - Additional payment, tax, shipping records
+
+**How to create:**
+- Via UI: Setup → Commerce → Stores
+- Cannot be created via Metadata API
+- Cannot be deployed via `sf project deploy`
+
+---
+
+### 2. Storefront (Frontend Metadata)
+
+**What it is:**
+- Digital Experience (LWR site) for buyer-facing shopping experience
+- Source-controllable as ExperienceBundle metadata
+- Created automatically when you create a Commerce Store
+
+**What it includes:**
+- ExperienceBundle metadata (`StorefrontName.digitalExperience-meta.xml`)
+- URL routing configuration (`sfdc_cms__route`)
+- Page definitions (`sfdc_cms__view`)
+  - Homepage
+  - Product List Pages (PLP)
+  - Product Detail Pages (PDP)
+  - Shopping cart
+  - Checkout flow
+  - Order confirmation
+  - Search results
+- Lightning Web Components (product cards, cart components, checkout)
+- Branding and theme configuration (`sfdc_cms__brandingSet`, `sfdc_cms__theme`)
+- Page layouts (`sfdc_cms__themeLayout`)
+- Navigation structure
+- Custom LWCs for extensions
+
+**Where it lives:**
+- `force-app/main/default/digitalExperiences/site/StorefrontName/`
+- Example: `force-app/main/default/digitalExperiences/site/My_B2B_Store1/`
+
+**How to create:**
+- Automatically generated by Commerce Store setup wizard
+- Retrieved from org using Salesforce CLI
+- Cannot be manually created from scratch
+
+**How to deploy:**
+- Retrievable: `sf project retrieve start -m DigitalExperienceBundle:site/<name>`
+- Deployable: `sf project deploy start -m DigitalExperienceBundle`
+- Source-controllable in Git
+
+---
+
+## Why You Cannot Create Storefront Metadata from Scratch
+
+### Technical Reasons
+
+1. **Complex Dependency Chain**
+   - Create merchandisers store
+   - Create DigitalExperienceBundle
+   - Integrate both together
+
+2. **Hundreds of Auto-Generated Configurations**
+   - Component IDs and region IDs (UUIDs)
+   - WebStore associations
+   - Commerce-managed component configurations
+   - Default routing rules
+   - Search configurations
+   - Cart and checkout flow definitions
+   - Payment integration settings
+
+3. **Commerce-Managed Components**
+   - Product List Page (PLP) components
+   - Product Detail Page (PDP) components
+   - Cart components
+   - Checkout components
+   - Search components
+   - These require specific configurations from Store data
+
+4. **Metadata API Limitation**
+   - Metadata API deploys metadata types (Apex, LWCs, objects)
+   - Metadata API CANNOT create SObject data (WebStore records)
+   - Store creation requires data operations, not metadata operations
+
+---
+
+## The Required Creation Order
+
+### Step 1: Create Commerce Store (Must Be First)
+
+```
+User Interface (Commerce App)
+     ↓
+WebStore Record Created
+     ↓
+BuyerGroup Records Created
+     ↓
+EntitlementPolicy Records Created
+     ↓
+Digital Experience Auto-Generated
+     ↓
+Commerce Components Configured
+```
+
+**Why this must be first:**
+- Generates WebStore record with unique ID
+- Creates default configurations
+- Auto-generates associated Digital Experience
+- Configures Commerce component relationships
+- Sets up default buyer access rules
+
+### Step 2: Retrieve Storefront Metadata
+
+```
+sf org list metadata --metadata-type DigitalExperienceConfig
+     ↓
+Select Store from List
+     ↓
+sf project retrieve start -m DigitalExperienceBundle:site/<name>
+     ↓
+Metadata Saved to Local Repository
+     ↓
+Now Editable and Source-Controllable
+```
+
+---
+
+## Key Takeaway
+
+**Commerce B2B = Store (data) + Storefront (metadata)**
+
+1. Create Store → generates Storefront
+2. Retrieve Storefront → customize and version control if needed
+3. Deploy Storefront → only after creating Store in target org
+
+**Never skip the Store creation. Never create Storefront metadata from scratch.**

package/skills/deploying-ui-bundle/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: deploying-ui-bundle
+description: "Deploy a Salesforce UI bundle to an org — the full deployment sequence including org authentication, pre-deploy build, metadata deployment, permission set assignment, data import, GraphQL schema fetch, and codegen. Use whenever the user wants to deploy, push to org, assign permission sets, import data, fetch GraphQL schema, run codegen, or set up an org after development. Triggers on: deploy, push to org, deploy metadata, assign permission set, import data, schema fetch, codegen, org auth, authenticate org, build and deploy, post-deploy, org setup."
+---
+
+# Deploying a UI Bundle
+
+The order of operations is critical when deploying to a Salesforce org. This sequence reflects the canonical flow.
+
+## Step 1: Org Authentication
+
+Check if the org is connected. If not, authenticate. All subsequent steps require an authenticated org.
+
+## Step 2: Pre-deploy UI Bundle Build
+
+Install dependencies and build the UI bundle to produce `dist/`. Required before deploying UI bundle entities.
+
+Run when: deploying UI bundles and `dist/` is missing or source has changed.
+
+## Step 3: Deploy Metadata
+
+Check for a manifest (`manifest/package.xml` or `package.xml`) first. If present, deploy using the manifest. If not, deploy all metadata from the project.
+
+Deploys objects, layouts, permission sets, Apex classes, UI bundles, and all other metadata. Must complete before schema fetch — the schema reflects org state.
+
+## Step 4: Post-deploy Configuration
+
+Deploying does not mean assigning. After deployment:
+
+- **Permission sets / groups** — assign to users so they have access to custom objects and fields. Required for GraphQL introspection to return the correct schema.
+- **Profiles** — ensure users have the correct profile.
+- **Other config** — named credentials, connected apps, custom settings, flow activation.
+
+Proactive behavior: after a successful deploy, discover permission sets in `force-app/main/default/permissionsets/` and assign each one (or ask the user).
+
+## Step 5: Data Import (optional)
+
+Only if `data/data-plan.json` exists. Delete runs in reverse plan order (children before parents). Import uses Anonymous Apex with duplicate rule save enabled.
+
+Always ask the user before importing or cleaning data.
+
+## Step 6: GraphQL Schema and Codegen
+
+1. Set default org
+2. Fetch schema (GraphQL introspection) — writes `schema.graphql` at project root
+3. Generate types (codegen reads schema locally)
+
+Run when: schema missing, or metadata/permissions changed since last fetch.
+
+## Step 7: Final UI Bundle Build
+
+Build the UI bundle if not already done in Step 2.
+
+## Summary: Interaction Order
+
+1. Check/authenticate org
+2. Build UI bundle (if deploying UI bundles)
+3. Deploy metadata
+4. Assign permissions and configure
+5. Import data (if data plan exists, with user confirmation)
+6. Fetch GraphQL schema and run codegen
+7. Build UI bundle (if needed)
+
+## Critical Rules
+
+- Deploy metadata **before** fetching schema — custom objects/fields appear only after deployment
+- Assign permissions **before** schema fetch — the user may lack FLS for custom fields
+- Re-run schema fetch and codegen **after every metadata deployment** that changes objects, fields, or permissions
+- Never skip permission set assignment or data import silently — either run them or ask the user
+
+## Post-deploy Checklist
+
+After every successful metadata deploy:
+
+1. Discover and assign permission sets (or ask the user)
+2. If `data/data-plan.json` exists, ask the user about data import
+3. Re-run schema fetch and codegen from the UI bundle directory

package/skills/generating-apex/CREDITS.md

@@ -0,0 +1,30 @@
+# Credits & Acknowledgments
+
+This skill was influenced by the [sf-skills](https://github.com/Jaganpro/sf-skills) repository and built upon the collective wisdom of the Salesforce developer community. We gratefully acknowledge the following authors and resources whose ideas, patterns, and best practices have shaped this skill.
+
+---
+
+## Authors & Contributors
+
+### Jag Valaiyapathy (**[Jaganpro)](https://github.com/Jaganpro)**
+
+**[sf-skills](https://github.com/Jaganpro/sf-skills)**
+
+Key contributions influencing this skill:
+
+- Pioneering open-source Salesforce skills for agentic coding tools
+- Apex code generation and review patterns
+- Best practices, anti-patterns, and design patterns reference material
+- Template library for common Apex class types
+
+This skill was influenced by the [sf-skills](https://github.com/Jaganpro/sf-skills) repository.
+
+---
+
+## Special Thanks
+
+To the entire Salesforce developer community for sharing knowledge, writing blogs, creating open-source tools, and helping each other build better solutions.
+
+---
+
+*If we've missed anyone whose work influenced these skills, please let us know so we can add proper attribution.*