@salesforce/afv-skills 1.30.0 → 1.32.0

package/skills/experience-ui-bundle-custom-app-generate/SKILL.md

@@ -3,6 +3,16 @@ name: experience-ui-bundle-custom-app-generate
 description: "MUST activate when the project contains a uiBundles/*/src/ directory and the task involves creating or configuring a Custom Application for hosting a UI bundle in Lightning Experience. Use this skill when creating a CustomApplication metadata record to surface the UI bundle in the App Launcher. Activate when files matching applications/*.app-meta.xml exist and need modification, or when the user wants to expose their app via the Lightning App Launcher without a Digital Experience Site. Do NOT use platform-custom-application-generate for this — UI bundle apps do not use tabs, action overrides, or flexipages."
 metadata:
   version: "1.0"
+  minApiVersion: "51.0"
+  relatedSkills:
+    - "platform-custom-application-generate"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  mcpTools:
+    salesforce-api-context:
+      tools: ["get_metadata_type_fields"]
+      semver: ">=1.0.0"
 ---
 
 # Custom Application for React UI Bundles
@@ -28,9 +38,9 @@ Determine values for all properties before constructing anything. Use the resolu
 ### Step 2: Query API Context (Version-Aware Field Discovery)
 Call `salesforce-api-context` MCP tools to discover which fields exist for the target org's API version. This ensures the generated metadata is compatible with the user's Salesforce version.
 
-**Required calls:**
-1. Call `get_metadata_type_fields` for `CustomApplication` — check whether the `uiBundle` field exists
-2. Call `get_metadata_type_fields` for `UIBundle` — check whether the `target` field exists
+**Required calls — use the `metadataType` parameter exactly as shown. Do not substitute a `detail` parameter or any other shape; `metadataType` is the only parameter this tool accepts:**
+1. `get_metadata_type_fields({ "metadataType": "CustomApplication" })` — check whether the `uiBundle` field exists in the response's field list
+2. `get_metadata_type_fields({ "metadataType": "UIBundle" })` — check whether the `target` field exists in the response's field list
 
 **Field resolution based on API response:**
 
@@ -63,7 +73,20 @@ Use the default template in the doc below. Values in `{braces}` are resolved pro
 - If Step 2 determined the older field names apply, substitute `<uiBundle>` with `<webApplication>` in the generated output.
 
 ### Step 5: Update UI Bundle Meta XML
-If Step 2 confirmed the `target` field exists on `UIBundle`, add `<target>CustomApplication</target>` to the `.uibundle-meta.xml` file (skip if the field doesn't exist in the org's API version):
+This step edits an **existing** file — it never creates a new one. `UIBundle` is a bundle-style metadata type: its meta XML normally lives inside its own folder at `uiBundles/{appName}/{appName}.uibundle-meta.xml`, alongside the bundle's other source files (e.g. `index.html`, `src/`). Some older or hand-authored projects may instead have it at the flat path `uiBundles/{appName}.uibundle-meta.xml` (no subfolder).
+
+Run `scripts/resolve-uibundle-path.sh "{appName}"` — it prints the path of the existing meta XML (preferring the nested layout, falling back to the flat layout). Edit that exact file in place; do not create a second file at the other path or migrate it to a different layout as part of this skill.
+
+If Step 2 confirmed the `target` field exists on `UIBundle`, add `<target>CustomApplication</target>` inside the existing `<UIBundle>` element of that file, preserving every other existing element and value untouched (skip this step entirely if the field doesn't exist in the org's API version — do not create the file or add `<target>` in that case).
+
+**Do NOT:**
+- Create a new `.uibundle-meta.xml` file
+- Create a second `.uibundle-meta.xml` file at a different path when one already exists (nested or flat) — edit the existing one in place, wherever it is
+- Leave the original `uiBundles/{appName}/{appName}.uibundle-meta.xml` (or `uiBundles/{appName}.uibundle-meta.xml`, if that's the existing layout) unmodified while adding `<target>` somewhere else
+
+The only files this skill produces or modifies are `applications/{appName}.app-meta.xml` (new) and the existing `{appName}.uibundle-meta.xml` (edited in place, only if `<target>` applies). Any other UI-bundle-related file appearing in the output is a bug.
+
+Example of the fully updated file (at `uiBundles/{appName}/{appName}.uibundle-meta.xml`, or the flat path if that's the existing layout) — this illustrates the end state of the existing file, not a new file to create:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -86,7 +109,8 @@ Before deploying, confirm:
 - [ ] API context was queried to determine available fields (Step 2)
 - [ ] `applications/{appName}.app-meta.xml` exists with correct content
 - [ ] The bundle reference field matches the org's API version (`<uiBundle>` or `<webApplication>`)
-- [ ] If `target` field is supported: `.uibundle-meta.xml` has `<target>CustomApplication</target>`
+- [ ] If `target` field is supported: the **existing** `{appName}.uibundle-meta.xml` (nested at `uiBundles/{appName}/`, or flat at `uiBundles/`, whichever already existed) has `<target>CustomApplication</target>`
+- [ ] No extra `.uibundle-meta.xml` file was created — exactly one `{appName}.uibundle-meta.xml` exists, at whichever path it already lived at
 - [ ] Deployment validates successfully:
 ```bash
 sf project deploy validate --metadata CustomApplication UIBundle --target-org ${usernameOrAlias}

package/skills/experience-ui-bundle-custom-app-generate/references/configure-metadata-custom-application.md

@@ -4,7 +4,7 @@
 This configuration file creates a **net-new, default** CustomApplication metadata record for a Lightning Experience app that hosts a React UI bundle. It is not intended to edit or modify an existing CustomApplication record. Use this template only when provisioning a brand-new Custom Application for a UI bundle.
 
 ## File Location
-```
+```xml
 <sourceDir>/applications/{appName}.app-meta.xml
 ```
 

package/skills/experience-ui-bundle-custom-app-generate/scripts/resolve-uibundle-path.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Resolve the existing path of a UIBundle's meta XML file.
+#
+# UIBundle metadata may live at either the nested bundle-style path
+# (uiBundles/{appName}/{appName}.uibundle-meta.xml) or, in older/hand-authored
+# projects, the flat path (uiBundles/{appName}.uibundle-meta.xml). This script
+# performs the deterministic file-existence check and prints whichever path
+# already exists, preferring the nested layout.
+#
+# Usage: scripts/resolve-uibundle-path.sh <appName>
+
+set -euo pipefail
+
+APP="${1:-}"
+if [ -z "$APP" ]; then
+  echo "ERROR: appName argument is required" >&2
+  exit 1
+fi
+
+NESTED="uiBundles/${APP}/${APP}.uibundle-meta.xml"
+FLAT="uiBundles/${APP}.uibundle-meta.xml"
+
+if [ -f "$NESTED" ]; then
+  echo "$NESTED"
+elif [ -f "$FLAT" ]; then
+  echo "$FLAT"
+else
+  echo "ERROR: no .uibundle-meta.xml found for $APP" >&2
+  exit 1
+fi

package/skills/experience-ui-bundle-features-generate/SKILL.md

@@ -1,18 +1,37 @@
 ---
 name: experience-ui-bundle-features-generate
-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."
+description: "MUST activate when the project contains a uiBundles/*/src/ directory and the user wants to add a pre-built feature — such as authentication (login, logout, protected routes, session management) or search (global search across pages and content) — instead of building it from scratch. Always run list first to see the current feature catalog, since it can include more than authentication and search. Always use this skill for installing pre-built features rather than hand-building them. DO NOT TRIGGER for Agentforce conversational client or file-upload features — use experience-ui-bundle-agentforce-client-generate and experience-ui-bundle-file-upload-generate respectively."
 metadata:
-  version: "1.0"
+  version: "1.1"
+  relatedSkills: ["experience-ui-bundle-agentforce-client-generate", "experience-ui-bundle-file-upload-generate"]
+  cliTools:
+    - tool: ["npx"]
+      semver: ">=7.0.0"
+    - tool: ["npm"]
+      semver: ">=7.0.0"
+  accessCheck:
+    - type: "license"
+      value: "Experience Cloud (Customer Community / Customer Community Plus)"
+    - type: "orgPref"
+      value: "Sites"
 ---
 
 # UI Bundle Features
 
 ## Installing Pre-built Features
 
-Always check for an existing feature before building something from scratch. The features CLI installs pre-built, tested packages into Salesforce UI bundles — from foundational UI libraries (shadcn/ui) to full-stack capabilities (authentication, search, navigation, GraphQL, Agentforce AI).
+Always check for an existing feature before building something from scratch. The features CLI installs pre-built, tested packages into Salesforce UI bundles — from foundational UI libraries (shadcn/ui) to full-stack capabilities. Authentication and search are the most commonly used features today; run `list --verbose` for the full current catalog, since it can grow over time.
+
+> **Ownership note:** Agentforce AI conversation clients and file-upload are owned by separate skills (`experience-ui-bundle-agentforce-client-generate`, `experience-ui-bundle-file-upload-generate`). If the catalog also lists an Agentforce or file-upload entry, do not install it from both places — confirm with the user which delivery path they want, and never install the same capability twice in one bundle.
+
+> **Package name:** `@salesforce/ui-bundle-features` is the canonical package name. Some older templates/samples still reference the deprecated `@salesforce/ui-bundle-features-experimental` name — never use the `-experimental` suffix. If a command fails to resolve, confirm the published version with `npm view @salesforce/ui-bundle-features version` before assuming the package name is wrong.
 
 ### Workflow
 
+0. **Confirm this is a React UI bundle** — this CLI copies into `src/features/` and expects `npm run build` to work. Non-React bundles are not supported and will fail late in the install.
+
+   Run `scripts/verify-react-bundle.sh`. If it exits non-zero, stop — the bundle is not React-based and this skill cannot proceed.
+
 1. **Search project code first** — check `src/` for existing implementations before installing anything. Scope searches to `src/` to avoid matching `node_modules/` or `dist/`.
 
 2. **Search available features** — use `npx @salesforce/ui-bundle-features list` with `--search <query>` to filter by keyword. Use `--verbose` for full descriptions.
@@ -24,24 +43,80 @@ Always check for an existing feature before building something from scratch. The
    - `--yes` for non-interactive mode (skips conflicts)
    - `--on-conflict error` to detect conflicts, then `--conflict-resolution <file>` to resolve them
 
+   Install features **before** doing custom frontend/layout work in this bundle — features may rewrite `appLayout.tsx`/`routes.tsx`, and installing after hand-built layout changes risks collisions.
+
 If no matching feature is found, ask the user before building a custom implementation — a relevant feature may exist under a different name.
 
 ### Conflict Handling
 
-In non-interactive environments, use the two-pass approach: first run with `--on-conflict error` to detect conflicts, then create a resolution JSON file (`{ "path": "skip" | "overwrite" }`) and re-run with `--conflict-resolution`.
+In non-interactive environments, use the two-pass approach:
 
-### Post-install: Integrating Example Files
+1. Run install with `--on-conflict error` to detect conflicts without applying them.
+2. Before writing the resolution file, read `references/conflict-resolution-schema.json` for the allowed keys and enum values.
+3. Write a resolution file at `<ui-bundle-dir>/conflict-resolution.json` (path is relative to the UI bundle directory being installed into, not the repo root). Key it by the exact paths the CLI printed as conflicts in pass 1, verbatim:
+   ```json
+   {
+     "src/appLayout.tsx": "overwrite",
+     "src/routes.tsx": "skip"
+   }
+   ```
+   Any conflicting path *not* listed in this file defaults to `skip` — the CLI will not overwrite a file you didn't explicitly mark `overwrite`.
+4. Re-run install with `--conflict-resolution <path-to-that-file>`.
 
-Features may include `__example__` files showing integration patterns. For each:
+### Post-install: Integrating Example Files
 
-1. Read the example file to understand the pattern
-2. Read the target file (shown in `describe` output)
-3. Apply the pattern from the example into the target
-4. Delete the example file after successful integration
+Features may include example files under an `__examples__/` directory (plural) showing integration patterns. These are often full, working pages with concrete names (e.g. `AccountSearch.tsx`), not bare placeholder templates. For each:
+
+1. Read the example file to understand the pattern — treat it as a working reference implementation, not necessarily a stub.
+2. Read the target file (shown in `describe` output).
+3. Apply the pattern from the example into the target.
+4. **CRITICAL — verify before deleting:**
+   ```bash
+   # Verify the build passes with the integrated pattern
+   npm run build || {
+     echo "ERROR: Build failed after integration - do NOT delete __examples__/"
+     exit 1
+   }
+   
+   # Verify the pattern from the example is actually present in the target
+   # (adjust grep pattern to match a key symbol/import/component from the example)
+   # Example: for SearchInput pattern integrated into AccountSearch.tsx
+   grep -q "SearchInput\|useSearch" src/pages/*.tsx src/components/*.tsx 2>/dev/null || {
+     echo "ERROR: Pattern from example not found in target files - integration incomplete"
+     echo "Do NOT delete __examples__/ until the pattern is confirmed present"
+     exit 1
+   }
+   
+   # Only delete after both checks pass
+   rm -rf __examples__/
+   ```
+
+If either check fails, **do NOT delete `__examples__/`** — the integration is incomplete. Fix the integration first, then re-run the verification.
 
 ### Hint Placeholders
 
-Some copy paths use `<descriptive-name>` placeholders (e.g., `<desired-page-with-search-input>`) that the CLI does not resolve. After installation, rename or relocate these files to the intended target, or integrate their patterns into an existing file.
+Some copy paths use `<descriptive-name>` placeholders (e.g., `<desired-page-with-search-input>`) that the CLI does not resolve. After installation, rename or relocate these files to the intended target, or integrate their patterns into an existing file. This is separate from the `__examples__/` convention above — a single copy path can use either mechanism.
+
+### Auth Feature: Org-Side Prerequisites
+
+Installing the authentication feature only copies files — it does not configure the org. Before telling the user auth is done, flag that these org-side steps still need to happen (outside this skill's scope, but required for the feature to actually work):
+
+- Digital Experiences (Experience Cloud) must be enabled, with Customer Community / Customer Community Plus licenses assigned to the relevant users, and Salesforce Sites enabled.
+- The community and guest profiles need explicit Apex class access granted for the auth utility, login/registration, and password-reset classes — the CLI does not grant this automatically.
+- Guest-profile sharing rules / org-wide defaults for any objects the auth flow touches.
+- **Known limitation:** logout has a documented CSRF-handling gap (tracked as W-21253864) — call this out to the user rather than presenting logout as fully solved.
+
+### CRITICAL: Resolve `<sfdxRoot>` After Every Install
+
+The CLI may copy files under a literal `<sfdxRoot>` folder — an unresolved placeholder for this project's Salesforce DX metadata root (from `sfdx-project.json`'s `packageDirectories[].path`, e.g. `force-app/main/default`). Files left there are undeployable.
+
+**After every install:**
+```bash
+find uiBundles/<AppName> -type d -regex '.*/<[^/]+>$'
+```
+If found, move each file to `<metadata-root>/<same-relative-subpath>` (keep `-meta.xml` sidecars attached) and delete the emptied placeholder dir(s).
 
+**Verification:**
+- [ ] Re-run `find uiBundles/<AppName> -type d -regex '.*/<[^/]+>$'` — output must be empty before proceeding.
 
 

package/skills/experience-ui-bundle-features-generate/references/conflict-resolution-schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "UI Bundle Features Conflict Resolution",
+  "description": "Schema for conflict-resolution.json used by @salesforce/ui-bundle-features CLI",
+  "type": "object",
+  "patternProperties": {
+    "^.+$": {
+      "type": "string",
+      "enum": ["overwrite", "skip"],
+      "description": "Resolution strategy for a conflicting file path. 'overwrite' replaces the existing file, 'skip' keeps the existing file."
+    }
+  },
+  "additionalProperties": false,
+  "examples": [
+    {
+      "src/appLayout.tsx": "overwrite",
+      "src/routes.tsx": "skip"
+    }
+  ]
+}

package/skills/experience-ui-bundle-features-generate/scripts/verify-react-bundle.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Verify that the project contains a React-based UI bundle
+# Exit 0 if React is found, exit 1 otherwise
+
+set -euo pipefail
+
+if ! grep -q '"react"' uiBundles/*/package.json 2>/dev/null; then
+  echo "ERROR: Not a React bundle - @salesforce/ui-bundle-features requires React"
+  echo "Found bundle type: $(grep '"type"' uiBundles/*/package.json 2>/dev/null || echo 'unknown')"
+  exit 1
+fi
+
+echo "React bundle detected"
+exit 0

package/skills/experience-ui-bundle-frontend-generate/SKILL.md

@@ -1,8 +1,11 @@
 ---
 name: experience-ui-bundle-frontend-generate
-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 experience-ui-bundle-app-coordinate instead)."
+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 src/styles/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 experience-ui-bundle-app-coordinate instead)."
 metadata:
   version: "1.0"
+  relatedSkills:
+    - "experience-ui-bundle-app-coordinate"
+    - "experience-ui-bundle-salesforce-data-access"
 ---
 
 # UI Bundle UI
@@ -78,6 +81,8 @@ React UI bundles must not import Salesforce platform modules like `lightning/*`
 
 ## Design Thinking
 
+The rules in this section and "Frontend Aesthetics" below are creative direction, not hard constraints — they cannot be lint- or build-checked and are judged by review, not automation. Two hard, checkable exceptions: never default to Inter/Roboto/Arial/Space Grotesk/system fonts, and mobile responsiveness (Tailwind breakpoints, 44px touch targets) is a MUST, not a style preference.
+
 Before coding, commit to a bold aesthetic direction:
 
 - **Purpose:** What problem does this interface solve? Who uses it?

package/skills/experience-ui-bundle-frontend-generate/references/component.md

@@ -7,6 +7,39 @@
 3. **Use design tokens** — prefer `bg-background`, `text-foreground`, `text-muted-foreground`, `border`, `bg-primary`, `text-destructive`, `rounded-lg` over hardcoded colors.
 4. **Use `cn()`** from `@/lib/utils` for conditional or composable class names.
 5. **TypeScript** — functional components with typed props interface; always accept `className?: string`.
+6. **Never assume a primitive or its exports exist** — the shadcn inventory below is a common baseline, not a guarantee for every app. Before importing anything from `@/components/ui`, read `src/components/ui/index.ts` (the barrel) to confirm the component is actually re-exported there. If it isn't, either import directly from its file (`@/components/ui/<file>`) or add the export to the barrel yourself — never invent a component that isn't present in either place.
+
+### Common shadcn/ui Inventory
+
+Apps scaffolded from the standard template typically ship these primitives under `src/components/ui/`. Treat this as a starting checklist, not a source of truth — always verify against the actual files and the barrel (`index.ts`) in the current project, since apps diverge (custom primitives get added, unused ones get removed, and not every file is necessarily re-exported from the barrel).
+
+| Primitive | Typical file | Notes |
+|---|---|---|
+| Alert | `alert.tsx` | `Alert`, `AlertTitle`, `AlertDescription` |
+| Avatar | `avatar.tsx` | `Avatar`, `AvatarImage`, `AvatarFallback` |
+| Badge | `badge.tsx` | Often exists as a file but may not be barrel-exported — check first |
+| Breadcrumb | `breadcrumb.tsx` | |
+| Button | `button.tsx` | `Button`, `buttonVariants` |
+| Calendar | `calendar.tsx` | |
+| Card | `card.tsx` | `Card`, `CardHeader`, `CardTitle`, `CardContent`, `CardFooter` |
+| Checkbox | `checkbox.tsx` | |
+| Collapsible | `collapsible.tsx` | |
+| Date Picker | `datePicker.tsx` | |
+| Dialog | `dialog.tsx` | `Dialog`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogTrigger` |
+| Dropdown Menu | `dropdown-menu.tsx` | |
+| Field | `field.tsx` | Composable form-field wrapper (label + error + description) |
+| Input | `input.tsx` | |
+| Label | `label.tsx` | |
+| Pagination | `pagination.tsx` | |
+| Popover | `popover.tsx` | |
+| Select | `select.tsx` | |
+| Separator | `separator.tsx` | |
+| Skeleton | `skeleton.tsx` | |
+| Spinner | `spinner.tsx` | |
+| Table | `table.tsx` | `Table`, `TableHeader`, `TableBody`, `TableRow`, `TableCell` |
+| Tabs | `tabs.tsx` | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` |
+
+**Not part of this baseline** — do not assume these exist without checking: `Sheet`, `Combobox`, `Accordion`, `Toast`/`Sonner`, `Slider`, `Switch`, `RadioGroup`, `Command`, `Menubar`, `NavigationMenu`, `Tooltip`, `Progress`, `Carousel`, `Drawer`. If the task needs one of these, check `src/components/ui/` first; if it's genuinely missing, either compose it from an existing primitive or tell the user it needs to be added rather than fabricating an import.
 
 ### File Location — Component
 
@@ -69,7 +102,7 @@ export default function HomePage() {
 - **Icons:** `lucide-react`; add `aria-hidden="true"` on decorative icons
 - **Focus styles:** use `focus-visible:` variants
 - **Multiple visual variants:** use CVA (`cva`) and `VariantProps`
-- **shadcn import barrel:** `import { Button, Card, Input } from "@/components/ui"`
+- **shadcn import barrel:** `import { Button, Card, Input } from "@/components/ui"` — only for components confirmed present in `index.ts`; see rule 6 above
 
 ### Confirm — Component
 

package/skills/experience-ui-bundle-frontend-generate/references/page.md

@@ -82,7 +82,7 @@ Use `ROUTES.*` constants from `@/utils/authenticationConfig` for auth-related pa
 
 - **Local state:** `useState`, `useReducer`, `useRef` inside the page component
 - **Shared or complex state:** extract to `src/hooks/` with a `use` prefix (e.g., `useContacts`)
-- **Data fetching:** prefer GraphQL (`executeGraphQL`) or REST utilities in `src/api/`; place shared data logic in `src/hooks/`
+- **Data fetching:** any Salesforce record access — GraphQL or REST — goes through the `@salesforce/platform-sdk` Data SDK (`createDataSDK()`, then `sdk.graphql`/`sdk.fetch`); consult the `experience-ui-bundle-salesforce-data-access` skill before writing this code, do not call `fetch`/`axios` directly or invent a different data API. Place client/query modules in `src/api/`; place shared data logic (loading, error, caching state) in `src/hooks/`
 - **Auth context:** `useAuth()` from `@/context/AuthContext` when current user is needed — only valid under `AuthProvider`
 
 ### Confirm — Page

package/skills/experience-ui-bundle-metadata-generate/SKILL.md

@@ -1,8 +1,18 @@
 ---
 name: experience-ui-bundle-metadata-generate
-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."
+description: "Use this skill when adding a front-end React UI bundle to an existing project or configuring UI bundle metadata and config files. TRIGGER when: adding or scaffolding a new UI bundle inside a project that already exists; running sf template generate ui-bundle; editing ui-bundle.json routing, headers, or output directory; working with *.uibundle-meta.xml files; or registering CSP Trusted Sites, resolving blocked images or fonts or external API calls, or editing cspTrustedSites/*.cspTrustedSite-meta.xml files. DO NOT TRIGGER when: creating a brand-new Salesforce project from scratch, where the whole SFDX starter project (UI bundle plus Experience Site metadata and toolchain) is generated together (use experience-ui-bundle-project-generate)."
 metadata:
   version: "1.0"
+  minApiVersion: "51.0"
+  relatedSkills:
+    - "experience-ui-bundle-frontend-generate"
+    - "experience-ui-bundle-custom-app-generate"
+    - "experience-ui-bundle-site-generate"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+    - tool: ["jq"]
+      semver: ">=1.6"
 ---
 
 # UI Bundle Metadata
@@ -11,9 +21,9 @@ metadata:
 
 Use `sf template generate ui-bundle` to create new apps — not create-react-app, Vite, or other generic scaffolds.
 
-**Always pass `--template reactbasic`** to scaffold a React-based bundle.
-
-**UI bundle name (`-n`):** Alphanumerical only — no spaces, hyphens, underscores, or special characters.
+- **Always pass `--template reactbasic`** to scaffold a React-based bundle.
+- **UI bundle name (`-n`):** Alphanumerical only — no spaces, hyphens, underscores, or special characters.
+- Pass `--output-dir` to use a different location for template generation.
 
 **Example:**
 ```bash
@@ -21,10 +31,11 @@ sf template generate ui-bundle -n CoffeeBoutique --template reactbasic
 ```
 
 After generation:
-1. Replace all default boilerplate — "React App", "Vite + React", default `<title>`, placeholder text
-2. Populate the home page with real content (landing section, banners, hero, navigation)
-3. Update navigation and placeholders (see the `experience-ui-bundle-frontend-generate` skill)
-4. **Configure a hosting target** — a UI bundle without a `<target>` in its meta XML will not be visible in the org. Use `experience-ui-bundle-custom-app-generate` for internal (App Launcher) apps or `experience-ui-bundle-site-generate` for external (Experience Site) apps.
+1. **Verify API version** — run `bash <skill_dir>/scripts/check-api-version.sh` from the project root to ensure `sourceApiVersion` in `sfdx-project.json` is 67.0 or higher. The script will automatically update it if needed.
+2. Replace all default boilerplate — "React App", "Vite + React", default `<title>`, placeholder text
+3. Populate the home page with real content (landing section, banners, hero, navigation)
+4. Update navigation and placeholders (see the `experience-ui-bundle-frontend-generate` skill)
+5. **Configure a hosting target** — a UI bundle without a `<target>` in its meta XML will not be visible in the org. Use `experience-ui-bundle-custom-app-generate` for internal (App Launcher) apps or `experience-ui-bundle-site-generate` for external (Experience Site) apps.
 
 Always install dependencies before running any scripts in the UI bundle directory.
 

package/skills/experience-ui-bundle-metadata-generate/references/csp-metadata-format.md

@@ -2,7 +2,7 @@
 
 ## File location
 
-```
+```text
 force-app/main/default/cspTrustedSites/{Name}.cspTrustedSite-meta.xml
 ```
 
@@ -256,7 +256,7 @@ Some services split resources across multiple subdomains. Create one CSP Trusted
 
 If the browser console shows a CSP error like:
 
-```
+```text
 Refused to load the image 'https://example.com/image.png' because it violates
 the following Content Security Policy directive: "img-src 'self' ..."
 ```

package/skills/experience-ui-bundle-metadata-generate/scripts/check-api-version.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Checks that sourceApiVersion in sfdx-project.json is 67.0 or higher.
+# If lower, updates it to "67.0".
+
+set -e
+
+PROJECT_FILE="sfdx-project.json"
+
+if [[ ! -f "$PROJECT_FILE" ]]; then
+  echo "ERROR: $PROJECT_FILE not found in current directory"
+  exit 1
+fi
+
+# Extract sourceApiVersion and check if it's below 67.0
+version=$(jq -r '.sourceApiVersion // "0"' "$PROJECT_FILE")
+is_below=$(jq --arg v "$version" -n '($v | split(".") | .[0] | tonumber) < 67')
+
+if [[ "$is_below" == "true" ]]; then
+  echo "WARNING: sourceApiVersion is $version (< 67.0)"
+  echo "Updating $PROJECT_FILE to set sourceApiVersion to \"67.0\""
+
+  # Update the file
+  jq '.sourceApiVersion = "67.0"' "$PROJECT_FILE" > "$PROJECT_FILE.tmp"
+  mv "$PROJECT_FILE.tmp" "$PROJECT_FILE"
+
+  echo "OK: Updated sourceApiVersion to 67.0"
+  exit 0
+fi
+
+echo "OK: sourceApiVersion is $version (>= 67.0)"

package/skills/experience-ui-bundle-project-generate/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: experience-ui-bundle-project-generate
+description: "Generates a minimal, ready-to-develop SFDX starter project from template instead of hand-scaffolding files. Use this skill when starting a brand-new Salesforce React UI bundle app and the initial project must be scaffolded — trigger phrases include create, start, or scaffold a new React UI bundle app, generate a starter project, or use a prebuilt/starter template. DO NOT TRIGGER when: editing, styling, or adding pages or components to an EXISTING app (use experience-ui-bundle-frontend-generate); configuring ui-bundle.json or metadata files (use experience-ui-bundle-metadata-generate); deploying to an org (use experience-ui-bundle-deploy); or when the user explicitly says they want to hand-scaffold from scratch."
+metadata:
+  version: "1.1"
+  relatedSkills:
+    - "experience-ui-bundle-app-coordinate"
+    - "experience-ui-bundle-metadata-generate"
+    - "experience-ui-bundle-frontend-generate"
+    - "experience-ui-bundle-salesforce-data-access"
+    - "experience-ui-bundle-deploy"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+    - tool: ["npm"]
+      semver: ">=7.0.0"
+    - tool: ["node"]
+      semver: ">=16.7.0"
+---
+
+# Using a UI Bundle Template
+
+Before building a Salesforce React UI bundle app from scratch, offer the user a **prebuilt starter template**. The Salesforce CLI generates these — a complete, deployable SFDX project (React UI bundle + toolchain + an `npm run setup` automation) — in one command. Starting from a starter is faster and less error-prone than hand-scaffolding.
+
+The CLI command is `sf template generate project`.
+
+## Step 1: Offer the choice
+
+The following are the templates. Ask the user which one fits, or whether they want to start from scratch.
+
+| Template | `--template` flag | Best for |
+|----------|-------------------|----------|
+| Internal starter | `reactinternalapp` | Starter for internal, employee-facing Salesforce apps (e.g. support consoles, ops dashboards, internal admin apps) — users are already-authenticated employees. Includes Agentforce chat. No login flow or public. |
+| External starter | `reactexternalapp` | Starter for customer/partner-facing Salesforce apps/sites (e.g. portals, communities, storefront, public sites). Full auth support (login, registration, reset, profile) -- external users sign in with their own accounts. |
+
+**If the user prefers to start from scratch** (or neither fits), stop here and let `experience-ui-bundle-app-coordinate` scaffold a new project. This skill is opt-in — do not force a template.
+
+## Step 2: Generate the project into the target root
+
+The project contents must land **directly at the target root `$DEST`** — so `sfdx-project.json` sits at `$DEST/sfdx-project.json`, with no extra wrapper subfolder. `sf template generate project` always nests its output under a `--name` subfolder, so generate into the `$DEST` dir, then move the contents from the subfolder up into `$DEST`, overwriting anything already there on conflict. Remove the empty subfolder at the end.
+
+- `<SKILL_DIR>` = the absolute path to **this skill's own directory** — the folder containing this `SKILL.md`; resolve it from the skill path in context
+- **`$NAME`** — the project name (alphanumerical only — no spaces, hyphens, underscores, or special characters). Ask the user for it. It also names the UI bundle, so it shows up inside the project.
+- **`$DEST`** — the target root directory the contents land in (use `.` for the current directory).
+
+```sh
+NAME=MyApp   # project name the user chose; also names the UI bundle
+DEST=.       # target root directory (the contents land directly here, no NAME/ wrapper)
+
+# choose ONE template flag based on the user's pick from Step 1
+TEMPLATE=reactinternalapp   # or reactexternalapp
+
+mkdir -p "$DEST"
+sf template generate project --name "$NAME" --template "$TEMPLATE" --output-dir "$DEST"
+
+# Flatten the generated $DEST/$NAME contents up into $DEST (see <SKILL_DIR>/scripts/flatten-project.mjs).
+# Use the absolute skill-dir path — a relative ./scripts/ would resolve against $DEST, not the skill.
+node "<SKILL_DIR>/scripts/flatten-project.mjs" "$DEST/$NAME" "$DEST"
+rm -rf "$DEST/$NAME"
+```
+
+> `<SKILL_DIR>/scripts/flatten-project.mjs` moves every generated entry (incl. dotfiles) into `$DEST`, overwriting any existing file/dir of any type on conflict while preserving unrelated files the user already had in `$DEST`. The per-entry `rmSync` + `renameSync` is what guarantees the template's files win on conflict (including a file-vs-directory type mismatch).
+
+### Verify
+
+After generation, confirm the contents landed at the root (not in a `$NAME/` subfolder):
+
+```sh
+test -f "$DEST/sfdx-project.json" && echo "OK: project root landed" || echo "FAILED"
+```
+
+`sfdx-project.json` must sit at `$DEST/sfdx-project.json`. The project also contains `package.json`, `force-app/main/default/uiBundles/$NAME/` (the React/Vite bundle), `scripts/`, `config/`, and `README.md`. If `sfdx-project.json` is missing or is one level down in `$DEST/$NAME/`, the flatten did not run — re-check before continuing.
+
+## Step 3: Install dependencies (you do this — do NOT hand off uninstalled)
+
+If the generated project ships **without** `node_modules`, **install dependencies yourself before handing the project back** — a fresh template is not runnable (preview/build/lint all fail) until deps are present. The user should receive a ready-to-develop project.
+
+There are **multiple** `package.json` files, each needing its own install:
+- the **project root** (`$DEST/package.json`), and
+- the **UI bundle** dir under `$DEST/force-app/main/default/uiBundles/$NAME/` — this holds the toolchain the preview server loads, so it must have `node_modules` too.
+
+```sh
+# 1. project root ($DEST was set in Step 2)
+( cd "$DEST" && npm install )
+
+# 2. each UI bundle
+for b in "$DEST"/force-app/main/default/uiBundles/*/; do
+  [ -f "$b/package.json" ] && ( cd "$b" && npm install )
+done
+```
+
+> First-run install of the bundle is the heavy step (tailwind, radix-ui, recharts, vite, etc.); expect a short wait. If an install fails, surface it — don't hand off a half-installed project.
+
+## Step 4: Confirm and hand off
+
+Verify the project landed and is installed:
+
+```sh
+ls "$DEST" # sfdx-project.json, package.json, force-app/, scripts/, README.md ...
+ls "$DEST"/force-app/main/default/uiBundles/*/node_modules >/dev/null && echo "bundle deps installed"
+```
+
+The project is now ready to develop and deploy. If there's a `README.md` in the template, take a look at it to see if there is any extra step or guidance for the user.
+
+From here, continue development with the other ui-bundle skills (`experience-ui-bundle-frontend-generate`, `experience-ui-bundle-salesforce-data-access`, `experience-ui-bundle-deploy`, etc.) against the now-scaffolded project — scaffolding and dependency install are already done.
+
+## Notes
+
+- The starters are **minimal** — no seeded sample data or custom objects. Build the rest with the other ui-bundle skills.
+- These templates use the `uiBundles` metadata convention. The UI bundle directory and meta XML are named after the project name you pass to `--name`.
+- `sf template generate project --help` lists all available templates if the flag names ever change.

package/skills/experience-ui-bundle-project-generate/scripts/flatten-project.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// Flatten a `sf template generate project` result into the target root.
+//
+// Usage: node <skill_dir>/scripts/flatten-project.mjs <srcDir> <destDir>
+//   <srcDir>  — the generated project dir (the `$STAGE/$NAME` subfolder the CLI nests output under)
+//   <destDir> — the target root the contents should land in (so sfdx-project.json sits at <destDir>/sfdx-project.json)
+//
+// Moves every generated entry (incl. dotfiles) from <srcDir> up into <destDir>, overwriting any
+// existing file/dir of any type on conflict. Unrelated files already in <destDir> are left untouched
+// — only the paths the template ships get replaced. The per-entry rmSync + renameSync is what
+// guarantees the template's files win on conflict (including a file-vs-directory type mismatch).
+// Requires Node ≥ 16.7 for rmSync.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const [src, dest] = process.argv.slice(2);
+
+if (!src || !dest) {
+  console.error("usage: node <skill_dir>/scripts/flatten-project.mjs <srcDir> <destDir>");
+  process.exit(1);
+}
+
+if (!fs.existsSync(path.join(src, "sfdx-project.json"))) {
+  console.error("generated project has no sfdx-project.json: " + src);
+  process.exit(1);
+}
+
+for (const entry of fs.readdirSync(src)) {
+  const target = path.join(dest, entry);
+  fs.rmSync(target, { recursive: true, force: true });
+  fs.renameSync(path.join(src, entry), target);
+}