@salesforce/afv-skills 1.31.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-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);
+}

package/skills/platform-custom-lightning-type-generate/SKILL.md

@@ -1,8 +1,11 @@
 ---
 name: platform-custom-lightning-type-generate
-description: "Use this skill when users need to create Custom Lightning Types (CLTs) for Einstein Agent actions or structured input/output schemas. Trigger when users mention CLT, Custom Lightning Types, Custom Lightning Types (CLTs) with widget/mosaic/fragment rendition/renderer, JSON schemas for agents, type definitions, lightning__objectType, or editor/renderer configurations. When widget renditions are requested, you MUST first read the widget-rendition.md reference file in this skill's references/ directory and follow its complete workflow. This is complex - always use this skill for CLT work."
+description: "Use this skill when users need to create Custom Lightning Types (CLTs) for Einstein Agent actions or structured input/output schemas. Trigger when users mention CLT, Custom Lightning Types, JSON schemas for agents, type definitions, lightning__objectType, or editor/renderer configurations. For widget renditions that combine a CLT with a Widget bundle, use the platform-lightning-type-widget-coordinate orchestrator instead. This is complex - always use this skill for CLT work."
 metadata:
   version: "1.0"
+  minApiVersion: "60.0"
+  relatedSkills:
+    - "platform-lightning-type-widget-coordinate"
 ---
 
 ## When to Use This Skill
@@ -12,7 +15,6 @@ Use this skill when you need to:
 - Generate JSON Schema-based type definitions for Lightning Platform
 - Configure CLTs for Einstein Agent actions
 - Set up editor and renderer configurations for custom UI
-- Create CLTs with widget/mosaic/fragment rendition
 - Troubleshoot deployment errors related to Custom Lightning Types
 
 ## Specification
@@ -54,6 +56,7 @@ Custom Lightning Types (CLTs) are JSON Schema-based type definitions used by the
 - **Apex class CLTs are minimal**:
   - Include **only** `title`, `description` (optional), and `lightning:type` set to `@apexClassType/...`.
   - Do **not** add `type`, `properties`, `required`, or `unevaluatedProperties`.
+- **No shell metacharacters that trigger the Vibes safe-shell filter.** In any Bash tool call emitted by this skill, do NOT use command substitution (`$(…)` or backticks), process substitution (`<(…)`, `>(…)`), brace expansion (`{a,b,c}` or `{1..N}`), or `eval` / `exec`. Vibes forces manual approval on these patterns even under Bypass mode and stalls the eval. Emit separate commands (`mkdir -p a && mkdir -p b`) or print each value with its own command and reason about the output rather than capturing it in a shell variable.
 
 ## Additional CLT Metaschema Validations
 - **Org namespace validation**: titles/descriptions and other string fields may be validated to ensure you are not using an org namespace in places that are disallowed.
@@ -66,7 +69,7 @@ When you need the full list of supported primitive `lightning:type` identifiers,
 
 ## Generation Workflow
 1. **Confirm the CLT approach**
-   - If referencing Apex: capture the exact class reference (`@apexClassType/namespace__ClassName$InnerClass`).
+   - If referencing Apex: capture the exact class reference (@apexClassType/namespace__ClassName$InnerClass).
    - If using standard primitives: list the fields, their Lightning primitive types, and which fields are required.
 2. **Draft `schema.json`**
    - **DO NOT include `"$schema"` at the top**
@@ -100,26 +103,18 @@ When you need the full list of supported primitive `lightning:type` identifiers,
    - **Avoid known-invalid patterns**:
      - Do not use `es_property_editors/inputList`.
      - Do not use `itemSchema` attributes.
-4. **(Optional) Draft `renderer.json`** (only if custom UI or mosaic rendition is required)
+4. **(Optional) Draft `renderer.json`** (only if custom UI or widget rendition is required)
    - **Supported shape:** Top-level `renderer` object with `renderer.componentOverrides` and `renderer.layout`.
      - Top-level `renderer` object.
      - Use `renderer.componentOverrides` for component overrides.
      - Use `renderer.layout` for layout.
      - **DEPRECATED**: Do NOT use `propertyRenderers` or `view` — these are legacy keys. Always use `componentOverrides` and `layout` instead.
-   - **Root override pattern** (most common for fully custom rendering UI):
+   - **Widget rendition pattern** (reference an existing WidgetBundle as the root renderer): the renderer file is a thin wrapper that points at the widget by developer name (`"definition": "@widget/c/<widgetDeveloperName>"`) and maps CLT schema properties to widget attributes via `{!$attrs.<schemaPropertyName>}`. Do **NOT** duplicate the widget body inside `renderer.json`. See `references/widget-rendition.md` for the full shape, binding rules, and constraints. For the full Apex → Lightning Type → Widget pipeline, use the `platform-lightning-type-widget-coordinate` orchestrator instead of this skill.
+   - **Root override pattern** (most common for fully custom rendering UI with a custom LWC):
      - `renderer.componentOverrides["$"] = { "definition": "c/<yourRendererComponent>", "attributes": { ... } }`
      - Use `{!$attrs.<name>}` in attribute mappings when binding schema data to custom renderer component attributes.
      - **CRITICAL**: Attribute mappings like `{!$attrs.propertyName}` must reference properties that **actually exist** in your type schema. Referencing non-existent properties will fail validation.
      - **Type matching**: Attribute values must match the expected type for the component. For example, if a component expects a string attribute, passing an integer will fail validation.
-   - **Widget renderer pattern** (for widget rendition):
-       - **When to use:** Use this when users request "mosaic", "widget", "fragment", or "cross-platform rendering" for their CLT.
-       - **Structure:** `renderer.componentOverrides["$"] = { "type": "mosaic", "definition": "tile/mosaic", "children": [ /* UEM tree of blocks and regions */ ] }`
-       - **REQUIRED workflow:**
-           - **STOP**: Do NOT attempt to create the widget renderer yourself.
-           - **MANDATORY FIRST STEP**: You MUST fetch the reference file `references/widget-rendition.md` located in this skill's directory before proceeding.
-           - Follow the complete workflow documented in `widget-rendition.md` using the generated CLT schema as the grounding schema.
-           - The `widget-rendition.md` reference contains the full widget generation workflow: discovering UEM blocks via discoverUiComponents, calling getUiComponentSchemas, building the UEM tree, and writing renderer.json.
-           - **Do not** attempt to generate widget rendition without first fetching the `widget-rendition.md` reference file.
    - **Property-level override pattern**:
      - `renderer.componentOverrides["<propertyName>"] = { "definition": "es_property_editors/outputText" | "es_property_editors/outputNumber" | "es_property_editors/outputImage" | ... }`. **Valid renderer components** (examples): `es_property_editors/outputText`, `es_property_editors/outputNumber`, `es_property_editors/outputImage`. Avoid input-style components in the renderer.
    - **Layout pattern for renderer**: