@salesforce/afv-skills 1.6.5 → 1.6.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.6.5",
+  "version": "1.6.7",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [
@@ -11,8 +11,8 @@
     "registry": "https://registry.npmjs.org"
   },
   "devDependencies": {
-    "@salesforce/ui-bundle-template-app-react-sample-b2e": "^1.119.5",
-    "@salesforce/ui-bundle-template-app-react-sample-b2x": "^1.119.5",
+    "@salesforce/ui-bundle-template-app-react-sample-b2e": "^1.120.2",
+    "@salesforce/ui-bundle-template-app-react-sample-b2x": "^1.120.2",
     "@salesforce/webapp-template-app-react-sample-b2e-experimental": "^1.117.1",
     "@salesforce/webapp-template-app-react-sample-b2x-experimental": "^1.117.1",
     "@types/js-yaml": "^4.0.9",

package/skills/building-ui-bundle-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: building-ui-bundle-app
-description: "Build complete Salesforce React UI bundle applications from natural language descriptions. Use this skill when a user requests a full React app, UI bundle app, web app on Salesforce, or describes a scenario requiring scaffolding, features, data access, UI pages, and deployment of a React application hosted on Salesforce. Orchestrates all UI bundle skills in proper dependency order to produce a deployable application. Triggers on: build a React app, create a UI bundle, build me an app, full-stack Salesforce React app, create a web app on Salesforce."
+description: "MUST activate when the project contains a uiBundles/*/src/ directory or sfdx-project.json and the prompt says create, build, construct, or generate a new app, site, or page from scratch — even if the prompt also describes visual styling. MUST also activate when the task spans more than one ui-bundle skill. Use this skill when building a complete app end-to-end. This is the orchestrator that coordinates scaffolding, features, data access, frontend UI, integrations, and deployment in the correct dependency order. Without it, phases execute out of order and the app breaks. Do NOT use for Lightning Experience apps with custom objects (use generating-lightning-app). Do NOT use for single-concern edits to an existing page (use building-ui-bundle-frontend)."
 metadata:
   version: "1.0"
   related-skills: generating-ui-bundle-metadata, generating-ui-bundle-features, using-ui-bundle-salesforce-data, building-ui-bundle-frontend, implementing-ui-bundle-agentforce-conversation-client, implementing-ui-bundle-file-upload, deploying-ui-bundle, generating-experience-react-site

package/skills/building-ui-bundle-frontend/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: building-ui-bundle-frontend
-description: "Build and modify React UI for Salesforce UI bundles — pages, components, layout, navigation, and headers/footers. Use whenever creating or editing TSX/JSX files or making visual/layout changes. Triggers on: add page, add component, header, footer, navigation, layout, styling, Tailwind, shadcn, React component, appLayout."
+description: "MUST activate before editing ANY file under uiBundles/*/src/ for visual or UI changes to an EXISTING app — pages, components, sections, layout, styling, colors, fonts, navigation, animations, or any look-and-feel change. Use this skill when modifying pages, components, layout, styling, or navigation in an existing UI bundle app. Activate when the project contains appLayout.tsx, routes.tsx, src/pages/, src/components/, or global.css. This skill contains critical project-specific conventions (appLayout.tsx shell, shadcn/ui components, Tailwind CSS, Salesforce base-path routing, module restrictions) that override general knowledge. Without this skill, generated code will use wrong imports, break routing, or ignore project structure. Do NOT use when creating a new app from scratch (use building-ui-bundle-app instead)."
 ---
 
 # UI Bundle UI
@@ -94,6 +94,8 @@ Choose a clear conceptual direction and execute it with precision. Bold maximali
 - **Spatial Composition:** Unexpected layouts — asymmetry, overlap, diagonal flow, grid-breaking elements. Generous negative space OR controlled density.
 - **Backgrounds & Depth:** Create atmosphere rather than defaulting to solid colors. Gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, grain overlays.
 
+- **Mobile Responsiveness:** All generated UI MUST be mobile-responsive. Use Tailwind responsive prefixes (`sm:`, `md:`, `lg:`) to adapt layouts across breakpoints. Stack columns on small screens, use flexible grids, and ensure touch targets are at least 44px. Test that navigation, typography, and spacing work on mobile viewports.
+
 Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate animations and effects. Minimalist designs need restraint, precision, and careful spacing/typography. No two designs should look the same — vary themes, fonts, and aesthetics across generations.
 
 ---

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

@@ -1,6 +1,6 @@
 ---
 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."
+description: "MUST activate when the project contains a uiBundles/*/src/ directory or sfdx-project.json and the task involves deploying, pushing to an org, or post-deploy setup. Use this skill when deploying a UI bundle app to a Salesforce org. Covers the full deployment sequence: org authentication, pre-deploy build, metadata deployment, permission set assignment, data import, GraphQL schema fetch, and codegen. Activate when files like *.uibundle-meta.xml or sfdx-project.json exist and the user mentions deploying, pushing, org setup, or post-deploy tasks."
 ---
 
 # Deploying a UI Bundle

package/skills/generating-experience-lwr-site/SKILL.md

@@ -102,6 +102,7 @@ Before doing anything, you **MUST ALWAYS** load them first if they match user in
 - [handle-component-and-region-ids.md](docs/handle-component-and-region-ids.md) - **UUID generation (CRITICAL)** for component and region ids used in views and themeLayout.
 - [handle-ui-components.md](docs/handle-ui-components.md) - Component discovery, schemas, insertion, configuration
 - [configure-guest-sharing-rules.md](docs/configure-guest-sharing-rules.md) - **Guest sharing rules** (`sharingGuestRules`) for public sites — use for any request involving "guest sharing rule", "Site Guest User", or sharing object records with unauthenticated visitors
+- [update-site-urls.md](docs/update-site-urls.md) - **Updating site URLs** - URL architecture, workflow for updating `urlPathPrefix` in DigitalExperienceConfig, Network, and CustomSite
 
 ## Common Workflows
 
@@ -211,6 +212,15 @@ The site developer name can be found in the CustomSite filename (e.g., `sites/My
 
 If the site is not found, an error message will be returned indicating that the site may not be deployed. Ensure the site has been successfully deployed before calling this action.
 
+### Updating Experience Site URLs
+
+**Use when** user wants to update or change site URLs (urlPathPrefix).
+
+**Steps** (Follow the steps sequentially. Do not skip any step before proceeding):
+
+- [ ] MUST read [update-site-urls.md](docs/update-site-urls.md) to understand the three-component architecture and URL update workflow
+- [ ] Follow the step-by-step workflow in the doc to update URLs consistently across all three components (DigitalExperienceConfig, Network, CustomSite)
+
 ### Validation & Deployment
 
 Use `sf` CLI to validate and deploy. Access help docs by attaching `--help`, e.g.:
@@ -230,4 +240,4 @@ sf project deploy validate --metadata DigitalExperienceBundle DigitalExperience
 
 ```bash
 sf project deploy start --metadata DigitalExperienceBundle DigitalExperience DigitalExperienceConfig Network CustomSite --target-org ${usernameOrAlias}
-```
+```

package/skills/generating-experience-lwr-site/docs/update-site-urls.md

@@ -0,0 +1,100 @@
+# Updating Experience Site URLs
+
+Experience sites have a three-component architecture with two distinct URL patterns. Understanding this structure is critical when updating site URLs.
+
+## Architecture Overview
+
+Every Salesforce Experience Site consists of three components:
+
+1. **Network** (metadata: `Network`) - Network configuration
+2. **ChatterNetwork Site** (metadata: `CustomSite`) - Authentication endpoints and core site services  
+3. **ChatterNetworkPicasso Site** (metadata: `DigitalExperienceConfig` + `DigitalExperienceBundle`) - Customer-facing pages and content
+
+## URL Pattern
+
+These three components use **two different URLs**:
+
+- **Primary URL** (ChatterNetworkPicasso): Used for customer-facing pages
+  - Defined in: `DigitalExperienceConfig` → `<urlPathPrefix>`
+  - Example: `mysite`
+
+- **Secondary URL** (Network + CustomSite): Used for authentication endpoints and other services
+  - Defined in: `Network` → `<urlPathPrefix>` AND `CustomSite` → `<urlPathPrefix>`
+  - Example: `mysitevforcesite`
+  - **Must be synchronized** - both files must have identical values
+
+By default, Salesforce differentiates these URLs by appending `vforcesite` suffix to the Network/CustomSite URL.
+
+## URL Update Workflow
+
+When updating site URLs, follow this workflow:
+
+### Step 1: Discover All URL References
+
+Search for all occurrences of `urlPathPrefix` across the project metadata files.
+
+**For agents**: Use the `search_files` tool with these parameters:
+- path: `force-app/main/default`
+- regex: `urlPathPrefix`
+- file_pattern: `*.xml`
+
+**For humans**: Use your IDE's search functionality or command line tools:
+```bash
+# Using grep
+grep -r "urlPathPrefix" force-app/main/default --include="*.xml"
+
+# Using VS Code: Ctrl+Shift+F (Windows/Linux) or Cmd+Shift+F (Mac)
+# Search for: urlPathPrefix
+# Files to include: *.xml
+```
+
+### Step 2: Identify URL Groups
+
+Determine which files belong to which URL group:
+
+- **Primary URL Group**: `DigitalExperienceConfig`
+- **Secondary URL Group**: `Network` AND `CustomSite`
+
+### Step 3: Update URLs Consistently
+
+Update the `<urlPathPrefix>` value in each file:
+
+- **DigitalExperienceConfig**: Update to new primary URL
+- **Network**: Update to new secondary URL (typically primary URL + `vforcesite`)
+- **CustomSite**: Update to **same value as Network** (must be synchronized)
+
+### Step 4: Validate Naming Convention
+
+Ensure URL values follow best practices:
+- Use lowercase letters only
+- Avoid special characters except hyphens where appropriate
+- Keep URLs concise and meaningful
+
+### Step 5: Verify Consistency
+
+Before deploying, confirm:
+- [ ] Primary URL in `DigitalExperienceConfig` is set correctly
+- [ ] Secondary URL in `Network` matches `CustomSite` exactly
+- [ ] URLs are properly differentiated (typically via suffix)
+- [ ] All URL values follow naming conventions
+
+## Example URL Configuration
+
+```
+ChatterNetworkPicasso Site (Primary):
+  DigitalExperienceConfig: <urlPathPrefix>bestsupport</urlPathPrefix>
+
+Network + ChatterNetwork Site (Secondary):
+  Network:    <urlPathPrefix>bestsupportvforcesite</urlPathPrefix>
+  CustomSite: <urlPathPrefix>bestsupportvforcesite</urlPathPrefix>
+```
+
+## Common Pitfalls to Avoid
+
+❌ **Don't** update only one or two files - all three must be updated  
+❌ **Don't** use different values in Network and CustomSite  
+❌ **Don't** use the same URL for both Primary and Secondary groups  
+❌ **Don't** skip the discovery step with `search_files`  
+✅ **Do** use `search_files` to find all occurrences first  
+✅ **Do** maintain URL differentiation between the two groups  
+✅ **Do** follow lowercase naming conventions

package/skills/generating-ui-bundle-features/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-ui-bundle-features
-description: "Search and install pre-built features into Salesforce React UI bundles — authentication, shadcn, search, navigation, GraphQL, Agentforce AI, and more. Use whenever searching for or installing features. Always check for an existing feature before building from scratch. Triggers on: install feature, add authentication, add shadcn, add feature, search features, list features."
+description: "MUST activate when the project contains a uiBundles/*/src/ directory and the user wants to add authentication or search to their app. Use this skill when adding authentication or search to a UI bundle app. Only covers two features: authentication (login, logout, protected routes, session management) and search (global search across pages and content). Always use this skill for these two features instead of building from scratch."
 ---
 
 # UI Bundle Features

package/skills/generating-ui-bundle-metadata/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-ui-bundle-metadata
-description: "Scaffold new Salesforce UI bundles and configure their metadata — sf template generate ui-bundle, UIBundle bundles (meta XML, ui-bundle.json with routing/headers/outputDir), and CSP Trusted Sites for external domains. Use whenever creating a new UI bundle, setting up UI bundle metadata structure, configuring routing or headers, setting outputDir, adding external domains that need CSP registration, or editing bundle configuration. Triggers on: create UI bundle, create ui-bundle, new app, sf template generate ui-bundle, metadata, ui-bundle.json, CSP, trusted site, bundle configuration, meta XML, routing config, external domain, headers config, outputDir."
+description: "MUST activate when the project contains a uiBundles/*/src/ directory and scaffolding a new UI bundle or app, or when editing ui-bundle.json, .uibundle-meta.xml, or CSP trusted site files. Use this skill when scaffolding with sf template generate ui-bundle, configuring ui-bundle.json (routing, headers, outputDir), or registering CSP Trusted Sites. Activate when the task involves files matching *.uibundle-meta.xml, ui-bundle.json, or cspTrustedSites/*.cspTrustedSite-meta.xml."
 ---
 
 # UI Bundle Metadata
@@ -9,7 +9,14 @@ description: "Scaffold new Salesforce UI bundles and configure their metadata
 
 Use `sf template generate ui-bundle` to create new apps — not create-react-app, Vite, or other generic scaffolds.
 
-**UI bundle name (`-n`):** Alphanumerical only — no spaces, hyphens, underscores, or special characters. Example: `CoffeeBoutique` (not `Coffee Boutique`).
+**Always pass `--template reactbasic`** to scaffold a React-based bundle.
+
+**UI bundle name (`-n`):** Alphanumerical only — no spaces, hyphens, underscores, or special characters.
+
+**Example:**
+```bash
+sf template generate ui-bundle -n CoffeeBoutique --template reactbasic
+```
 
 After generation:
 1. Replace all default boilerplate — "React App", "Vite + React", default `<title>`, placeholder text

package/skills/generating-ui-bundle-site/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-ui-bundle-site
-description: "Use this skill when users need to create or configure a Salesforce Digital Experience Site specifically for hosting a React UI bundle. Trigger when users mention creating an Experience site for a React app, setting up a React site on Salesforce, configuring Network/CustomSite/DigitalExperience metadata for a UI bundle, or deploying site infrastructure for a React application. Also trigger when users mention site URL path prefixes, app namespaces, appDevName, guest access configuration, DigitalExperienceConfig, DigitalExperienceBundle, or sfdc_cms__site content types in the context of React apps. Always use this skill for any React UI bundle site creation or site infrastructure configuration work, even if the user just says \"create a site for my React app\" or \"set up the site for my UI bundle.\""
+description: "MUST activate when the project contains a uiBundles/*/src/ directory and the task involves creating or configuring site infrastructure. Use this skill when creating or configuring a Salesforce Digital Experience Site for hosting a UI bundle. Activate when files matching digitalExperiences/, networks/, customSite/, or DigitalExperienceBundle exist and need modification, or when the user wants to publish, host, or configure guest access for their app."
 ---
 
 # Digital Experience Site for React UI Bundles
@@ -51,6 +51,8 @@ Use the default templates in the docs below. Values in `{braces}` are resolved p
 | DigitalExperienceBundle | [configure-metadata-digital-experience-bundle.md](docs/configure-metadata-digital-experience-bundle.md) |
 | DigitalExperience (sfdc_cms__site) | [configure-metadata-digital-experience.md](docs/configure-metadata-digital-experience.md) |
 
+For URL updates, see [update-site-urls.md](docs/update-site-urls.md).
+
 ### Execution Note for Step 3: Load and use the docs
 - Agents MUST read the full contents of each docs/*.md file referenced in Step 3 before attempting to populate metadata fields.
 - Use your platform's file-read tool (for example, `read_file`) to load these files in full, then perform placeholder substitution for values in `{braces}` using the resolved properties from Step 1.
@@ -63,7 +65,7 @@ Use the default templates in the docs below. Values in `{braces}` are resolved p
 - Read entire file contents, replace placeholders (e.g. `{siteName}`) with the resolved values, then use the expanded templates to populate the metadata XML/JSON content.
   
 ### Step 4: Resolve Additional Configurations
-Address any extra configurations the user requests. Use the metadata sections and field context identified in Step 2 to understand each field’s purpose and constraints, then update only the minimum necessary fields.
+Address any extra configurations the user requests. Use the metadata sections and field context identified in Step 2 to understand each field's purpose and constraints, then update only the minimum necessary fields.
 
 ## Verification Checklist
 Before deploying, confirm:
@@ -76,3 +78,13 @@ Before deploying, confirm:
 ```bash
 sf project deploy validate --metadata Network CustomSite DigitalExperienceConfig DigitalExperienceBundle DigitalExperience --target-org ${usernameOrAlias}
 ```
+
+## Common Workflows
+
+### Updating Experience Site URLs
+
+**Use when** user wants to update or change site URLs (urlPathPrefix).
+
+**Steps**:
+- [ ] Read [update-site-urls.md](docs/update-site-urls.md) to understand the three-component architecture and URL update workflow
+- [ ] Follow the step-by-step workflow in the doc to update URLs consistently across all three components (DigitalExperienceConfig, Network, CustomSite)

package/skills/generating-ui-bundle-site/docs/configure-metadata-digital-experience.md

@@ -3,7 +3,7 @@
 ## Purpose
 These configuration files create **net-new, default** DigitalExperience content records (`sfdc_cms__site` type) for a Digital Experience React Site. They are not intended to edit or modify existing DigitalExperience content. Use these templates only when provisioning a brand-new React site.
 
-The `appContainer: true` and `appSpace` fields in `content.json` are what make this a React site rather than a standard LWR site. The `appSpace` value follows the format `{namespace}__{developerName}` and must match a deployed `UIBundle` metadata record.
+The `appContainer: true` field in `content.json` is what makes this a React site rather than a standard LWR site. The `appSpace` field should **be left empty if the UIBundle metadata record does not already exist**. When the UIBundle exists, populate the `appSpace` value following the format `{namespace}__{developerName}` to match the deployed `UIBundle` metadata record.
 
 ## File Location
 The DigitalExperience directory contains only `_meta.json` and `content.json`. Do not create any directories other than `sfdc_cms__site` inside the bundle.
@@ -32,7 +32,9 @@ digitalExperiences/site/{siteName}1/sfdc_cms__site/{siteName}1/content.json
   "contentBody": {
     "authenticationType": "AUTHENTICATED_WITH_PUBLIC_ACCESS_ENABLED",
     "appContainer": true,
-    "appSpace": "{appNamespace}__{appDevName}"
+    "appSpace": ""
   }
 }
 ```
+
+**Note:** Leave `appSpace` empty (`""`) if the UIBundle does not exist. If the UIBundle metadata record is already deployed, populate it with `"{appNamespace}__{appDevName}"`.

package/skills/generating-ui-bundle-site/docs/update-site-urls.md

@@ -0,0 +1,100 @@
+# Updating Experience Site URLs
+
+Experience sites have a three-component architecture with two distinct URL patterns. Understanding this structure is critical when updating site URLs.
+
+## Architecture Overview
+
+Every Salesforce Experience Site consists of three components:
+
+1. **Network** (metadata: `Network`) - Network configuration
+2. **ChatterNetwork Site** (metadata: `CustomSite`) - Legacy site and proxy core site services
+3. **ChatterNetworkPicasso Site** (metadata: `DigitalExperienceConfig` + `DigitalExperienceBundle`) - Customer-facing pages and content
+
+## URL Pattern
+
+These three components use **two different URLs**:
+
+- **Primary URL** (ChatterNetworkPicasso): Used for customer-facing pages
+  - Defined in: `DigitalExperienceConfig` → `<urlPathPrefix>`
+  - Example: `mysite`
+
+- **Secondary URL** (Network + CustomSite): Used for legacy authentication endpoints and other services
+  - Defined in: `Network` → `<urlPathPrefix>` AND `CustomSite` → `<urlPathPrefix>`
+  - Example: `mysitevforcesite`
+  - **Must be synchronized** - both files must have identical values
+
+By default, Salesforce differentiates these URLs by appending `vforcesite` suffix to the Network/CustomSite URL.
+
+## URL Update Workflow
+
+When updating site URLs, follow this workflow:
+
+### Step 1: Discover All URL References
+
+Search for all occurrences of `urlPathPrefix` across the project metadata files.
+
+**For agents**: Use the `search_files` tool with these parameters:
+- path: `force-app/main/default`
+- regex: `urlPathPrefix`
+- file_pattern: `*.xml`
+
+**For humans**: Use your IDE's search functionality or command line tools:
+```bash
+# Using grep
+grep -r "urlPathPrefix" force-app/main/default --include="*.xml"
+
+# Using VS Code: Ctrl+Shift+F (Windows/Linux) or Cmd+Shift+F (Mac)
+# Search for: urlPathPrefix
+# Files to include: *.xml
+```
+
+### Step 2: Identify URL Groups
+
+Determine which files belong to which URL group:
+
+- **Primary URL Group**: `DigitalExperienceConfig`
+- **Secondary URL Group**: `Network` AND `CustomSite`
+
+### Step 3: Update URLs Consistently
+
+Update the `<urlPathPrefix>` value in each file:
+
+- **DigitalExperienceConfig**: Update to new primary URL
+- **Network**: Update to new secondary URL (typically primary URL + `vforcesite`)
+- **CustomSite**: Update to **same value as Network** (must be synchronized)
+
+### Step 4: Validate Naming Convention
+
+Ensure URL values follow best practices:
+- Use lowercase letters only
+- Avoid special characters except hyphens where appropriate
+- Keep URLs concise and meaningful
+
+### Step 5: Verify Consistency
+
+Before deploying, confirm:
+- [ ] Primary URL in `DigitalExperienceConfig` is set correctly
+- [ ] Secondary URL in `Network` matches `CustomSite` exactly
+- [ ] URLs are properly differentiated (typically via suffix)
+- [ ] All URL values follow naming conventions
+
+## Example URL Configuration
+
+```
+ChatterNetworkPicasso Site (Primary):
+  DigitalExperienceConfig: <urlPathPrefix>bestsupport</urlPathPrefix>
+
+Network + ChatterNetwork Site (Secondary):
+  Network:    <urlPathPrefix>bestsupportvforcesite</urlPathPrefix>
+  CustomSite: <urlPathPrefix>bestsupportvforcesite</urlPathPrefix>
+```
+
+## Common Pitfalls to Avoid
+
+❌ **Don't** update only one or two files - all three must be updated  
+❌ **Don't** use different values in Network and CustomSite  
+❌ **Don't** use the same URL for both Primary and Secondary groups  
+❌ **Don't** skip the discovery step with `search_files`  
+✅ **Do** use `search_files` to find all occurrences first  
+✅ **Do** maintain URL differentiation between the two groups  
+✅ **Do** follow lowercase naming conventions