@salesforce/afv-skills 1.32.0 → 1.33.0

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

@@ -1,15 +1,42 @@
 ---
 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 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)."
+description: "MUST activate before editing ANY file under uiBundles/*/src/ (or the bundle's index.html) for visual or UI changes to an EXISTING app — pages, components, sections, layout, styling, colors, fonts, navigation, animations, branding, or any look-and-feel change. Use this skill when modifying pages, components, layout, styling, navigation, or branding in an existing UI bundle app. Activate when the project contains appLayout.tsx, routes.tsx, src/pages/, src/components/, src/styles/global.css, or the bundle's index.html. 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 or the bundle has not been scaffolded yet (use experience-ui-bundle-app-coordinate instead)."
 metadata:
-  version: "1.0"
+  version: "1.1"
   relatedSkills:
     - "experience-ui-bundle-app-coordinate"
+    - "experience-ui-bundle-metadata-generate"
     - "experience-ui-bundle-salesforce-data-access"
+  cliTools:
+    - tool: ["npm"]
+      semver: ">=8.0.0"
+    - tool: ["python3"]
+      semver: ">=3.10.0"
 ---
 
 # UI Bundle UI
 
+## Resolve the Bundle Directory
+
+**MUST** run `scripts/resolve-ui-bundle.sh [project-root]` before applying any rule below or writing any file — an ad-hoc `find`/`ls` is not a substitute; it does not enforce the exit-code gate below. It reads `sfdx-project.json`'s `packageDirectories[0].path` (does not assume `force-app` — the source path is configurable) and looks under `<sourceDir>/main/default/uiBundles/`:
+
+- **Exit 0**, bundle path printed to stdout: exactly one bundle directory found — that is the bundle directory. Use that exact directory name; never substitute a different name (e.g. a generic "AcmePortal" example from a prompt template) for the one actually printed.
+- **Exit 2**, candidates printed to stderr: multiple `uiBundles/*` subdirectories exist — do not guess, and do not write to any of them, or to a bundle name not in the printed list. Ask the user which app/bundle they mean before editing or running any command.
+- **Exit 1**: `sfdx-project.json` missing/invalid, or no bundle directory found at all.
+
+Run all `npm`/lint/build/dev commands from inside the resolved bundle directory, never from the project root.
+
+## Preconditions
+
+Before applying any rule below, confirm this is an existing, scaffolded UI bundle: **MUST** run `scripts/check-preconditions.sh <bundle-dir>` with the directory `resolve-ui-bundle.sh` printed.
+
+- **Single-bundle (exit 0) case**: run it once, on that bundle.
+- **Multi-bundle (exit 2) case**: do not run it yet — first ask the user which app/bundle they mean, per the Resolve step above. Once the user names the bundle, run `check-preconditions.sh` on that one bundle only. Never run it against multiple candidates speculatively before the user has chosen — that means touching/inspecting bundles the user didn't ask about.
+- **Exit 0**: the bundle has `src/appLayout.tsx`, `src/routes.tsx`, and `src/components/ui/` — proceed.
+- **Exit 1**, missing pieces listed: this is a fresh SFDX project, a non-UI-bundle React project, or a partially-scaffolded bundle — **stop**. Do not fall back to generic React knowledge (e.g. `react-router-dom`, a hardcoded basename, or raw HTML), and do not hand-write `appLayout.tsx`/`routes.tsx`/a page/a component to "fill in" the missing scaffold, even for a casual, vague, or urgent-sounding request ("just change the header", "make the background blue"). Tell the user the bundle isn't scaffolded yet and direct them to `experience-ui-bundle-app-coordinate` (or `experience-ui-bundle-metadata-generate`) to scaffold it first. If, after the user names their intended bundle, that one turns out to be unscaffolded, stop and redirect for it — do not silently switch to scaffolding a different candidate instead.
+
+Never invent, assume, or fall back to a bundle name that doesn't appear in the actual `<sourceDir>/main/default/uiBundles/` listing on disk — including a name that only appears as example/template text elsewhere (a prompt, a directive, prior conversation). If what's on disk doesn't match that example, disk wins.
+
 ## Identify the Task
 
 Determine which category the request falls into:
@@ -17,9 +44,11 @@ Determine which category the request falls into:
 | Category | Examples | Implementation Guide |
 |----------|----------|---------------------|
 | **Page** | New routed page (contacts, dashboard, settings) | `references/page.md` |
-| **Header / Footer** | Site-wide nav bar, footer, branding | `references/header-footer.md` |
+| **Header / Footer** | Site-wide nav bar, footer, branding, renaming the app | `references/header-footer.md` |
 | **Component** | Widget, card, table, form, dialog | `references/component.md` |
 
+A request to rename/rebrand the app (e.g. "call it X everywhere a user would see it") is a **Header / Footer** task even though it doesn't mention "header" by name — it always touches at least two files: `src/appLayout.tsx` (header/nav brand text) AND `index.html`'s `<title>` (browser tab title). Treat these as one atomic change; a rename that only updates one of the two is incomplete.
+
 ---
 
 ## Layout and Navigation
@@ -32,12 +61,14 @@ When making any change that affects navigation, header, footer, sidebar, theme,
 2. Replace all default/template nav items and labels with app-specific links and names
 3. Replace placeholder app name everywhere: header, nav brand, footer, `<title>` in `index.html`
 
-Before finishing, confirm: Did I update `appLayout.tsx` with real nav items and branding?
+`index.html` lives at the bundle root (not under `src/`), but it is still in scope for this skill whenever branding or the app name changes — the leftover `<title>React App</title>` / `Vite + React` boilerplate is a common ship-blocker that `npm run lint`/`npm run build` never catches.
+
+Before finishing, confirm: Did I update `appLayout.tsx` with real nav items and branding? Then run `scripts/verify-rules.sh` to check for residual boilerplate (see Verification below).
 
 | What | Where |
 |------|-------|
 | Layout, nav, branding | `src/appLayout.tsx` |
-| Document title | `index.html` |
+| Document title | `index.html` (bundle root, outside `src/` — still in scope for branding) |
 | Root page content | Component at root route in `routes.tsx` |
 
 ---
@@ -75,7 +106,7 @@ Apps run behind dynamic base paths. Router navigation (`<Link to>`, `navigate()`
 
 ### Module Restrictions
 
-React UI bundles must not import Salesforce platform modules like `lightning/*` or `@wire` (LWC-only). For data access, use the `experience-ui-bundle-salesforce-data-access` skill.
+React UI bundles must not import Salesforce platform modules like `lightning/*` or `@wire` (LWC-only). **Before writing any data-access code (GraphQL, REST, SDK initialization, or a hook that fetches data), you MUST invoke the `experience-ui-bundle-salesforce-data-access` skill first.** Do not write `fetch`/`axios` calls or invent a different data API inline in this skill — this applies even if the clarifying-question answer only implies data fetching in passing.
 
 ---
 
@@ -137,4 +168,13 @@ Ask one question at a time and stop when you have enough context.
 
 ## Verification
 
-Before completing, run lint and build from the UI bundle directory. Lint must result in 0 errors and build must succeed.
+Before completing, run all of the following from the resolved UI bundle directory (see "Resolve the Bundle Directory" above):
+
+1. `npm run lint` — must result in 0 errors.
+2. `npm run build` — must succeed.
+3. `npm run dev` (or the project's dev-server script) — confirm the app starts cleanly so the change is verified at runtime, not just at build time.
+
+**`lint`/`build` alone do not catch the highest-risk rules in this skill** — a wrong `react-router-dom` import, a hardcoded basename, an inline `style={{}}`, or a stray `lightning/*` import can all lint and build clean while breaking at runtime. After any change that touches routing, layout, styling, or module imports, run `scripts/verify-rules.sh <files-or-dirs-you-edited>`:
+
+- **Exit 0**: no violations found.
+- **Exit 1**, violations listed by rule and file: fix every one before considering the task complete, even if lint and build passed.

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

@@ -35,11 +35,12 @@ Apps scaffolded from the standard template typically ship these primitives under
 | Select | `select.tsx` | |
 | Separator | `separator.tsx` | |
 | Skeleton | `skeleton.tsx` | |
+| Sonner (Toast) | `sonner.tsx` | Exists as a file but is typically **not** barrel-exported — check `index.ts` first, or import `{ Toaster, toast }` directly from `@/components/ui/sonner` |
 | 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.
+**Not part of this baseline** — do not assume these exist without checking: `Sheet`, `Combobox`, `Accordion`, `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
 

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

@@ -2,13 +2,14 @@
 
 ### Rules
 
-1. **Edit `appLayout.tsx` only** — header and footer are layout-level concerns. Never add them to individual page files.
+1. **Edit `appLayout.tsx` for the header/footer/nav shell itself** — layout-level concerns. Never add them to individual page files.
 2. **Never modify `routes.tsx` or `app.tsx`** — the router setup must remain intact.
 3. **Create component files in `src/components/layout/`** — the designated location for layout-level components.
 4. **Use the full-height flex column pattern** — wrap layout in `min-h-screen flex flex-col` so footer stays at bottom.
 5. **Use shadcn and Tailwind** — compose from `@/components/ui`; style with Tailwind utility classes and design tokens.
 6. **Use path aliases** — import with `@/components/layout/...` and `@/components/ui`; no deep relative paths.
 7. **Preserve existing content** — if `appLayout.tsx` already has a `<NavigationMenu />` or other shell elements, keep them in place.
+8. **Renaming/rebranding the app is a two-file change, not one** — whenever the request changes the app's name/brand text (not just adding/styling a header or footer), you MUST also update `index.html`'s `<title>` at the bundle root. `appLayout.tsx` covers what's visible in the page body (header/nav brand, footer); `index.html`'s `<title>` covers the browser tab — neither substitutes for the other, and both are required. Do not stop after editing only `appLayout.tsx` for this kind of request.
 
 ### Step 1 — Create the header component (if requested)
 

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:** 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/`
+- **Data fetching:** any Salesforce record access — GraphQL or REST — goes through the `@salesforce/platform-sdk` Data SDK (`createDataSDK()`, then `sdk.graphql`/`sdk.fetch`). **You MUST invoke the `experience-ui-bundle-salesforce-data-access` skill before writing this code** — do not call `fetch`/`axios` directly or invent a different data API, even if the data need is small or implied only by a clarifying-question answer. 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-frontend-generate/scripts/check-preconditions.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Verify a resolved UI bundle directory is actually scaffolded before any
+# rule in this skill applies.
+# Usage: check-preconditions.sh <bundle-dir>
+#   <bundle-dir> is the path printed by resolve-ui-bundle.sh.
+#
+# Exit 0 if the bundle is scaffolded (src/appLayout.tsx, src/routes.tsx, and
+# src/components/ui/ all present).
+# Exit 1 with the missing pieces listed if the bundle is a fresh SFDX
+# project, a non-UI-bundle React project, or only partially scaffolded —
+# the caller must stop and redirect the user to
+# experience-ui-bundle-app-coordinate (or experience-ui-bundle-metadata-generate)
+# instead of falling back to generic React knowledge.
+
+set -uo pipefail
+
+BUNDLE_DIR="${1:-}"
+
+if [ -z "$BUNDLE_DIR" ] || [ ! -d "$BUNDLE_DIR" ]; then
+  echo "ERROR: check-preconditions.sh requires a valid bundle directory argument" >&2
+  exit 1
+fi
+
+MISSING=()
+[ -f "$BUNDLE_DIR/src/appLayout.tsx" ] || MISSING+=("src/appLayout.tsx")
+[ -f "$BUNDLE_DIR/src/routes.tsx" ] || MISSING+=("src/routes.tsx")
+[ -d "$BUNDLE_DIR/src/components/ui" ] || MISSING+=("src/components/ui/")
+
+if [ "${#MISSING[@]}" -gt 0 ]; then
+  echo "ERROR: $BUNDLE_DIR is not a scaffolded UI bundle. Missing:" >&2
+  printf '  - %s\n' "${MISSING[@]}" >&2
+  echo "Stop here. Tell the user the bundle isn't scaffolded yet and direct them to experience-ui-bundle-app-coordinate (or experience-ui-bundle-metadata-generate) to scaffold it first." >&2
+  exit 1
+fi
+
+echo "SUCCESS: $BUNDLE_DIR is scaffolded (src/appLayout.tsx, src/routes.tsx, src/components/ui/ present)"
+exit 0

package/skills/experience-ui-bundle-frontend-generate/scripts/resolve-ui-bundle.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Resolve the single UI bundle directory for this project.
+# Usage: resolve-ui-bundle.sh [project-root]   (default: current directory)
+#
+# Reads sfdx-project.json's packageDirectories[0].path, looks under
+# <that-path>/main/default/uiBundles/, and prints the resolved bundle
+# directory to stdout on success.
+#
+# Exit 0: exactly one bundle directory found — printed to stdout.
+# Exit 1: sfdx-project.json missing/invalid, or no uiBundles/* subdirectory
+#         found at all (not a scaffolded SFDX project yet).
+# Exit 2: multiple uiBundles/* subdirectories found — caller MUST ask the
+#         user which one they mean rather than guessing; candidate names are
+#         printed to stderr.
+
+set -uo pipefail
+
+PROJECT_ROOT="${1:-.}"
+SFDX_PROJECT="$PROJECT_ROOT/sfdx-project.json"
+
+if [ ! -f "$SFDX_PROJECT" ]; then
+  echo "ERROR: sfdx-project.json not found at $SFDX_PROJECT" >&2
+  exit 1
+fi
+
+SOURCE_PATH=$(python3 -c "
+import json, sys
+try:
+    with open('$SFDX_PROJECT') as f:
+        data = json.load(f)
+    dirs = data.get('packageDirectories', [])
+    print(dirs[0].get('path', '') if dirs else '')
+except Exception:
+    print('')
+" 2>/dev/null)
+
+if [ -z "$SOURCE_PATH" ]; then
+  echo "ERROR: sfdx-project.json is invalid or has no packageDirectories[0].path" >&2
+  exit 1
+fi
+
+BUNDLES_DIR="$PROJECT_ROOT/$SOURCE_PATH/main/default/uiBundles"
+
+if [ ! -d "$BUNDLES_DIR" ]; then
+  echo "ERROR: No uiBundles/ directory found at $BUNDLES_DIR" >&2
+  exit 1
+fi
+
+BUNDLE_DIRS=()
+while IFS= read -r d; do
+  BUNDLE_DIRS+=("$d")
+done < <(find "$BUNDLES_DIR" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | sort)
+
+if [ "${#BUNDLE_DIRS[@]}" -eq 0 ]; then
+  echo "ERROR: $BUNDLES_DIR exists but contains no bundle subdirectories" >&2
+  exit 1
+fi
+
+if [ "${#BUNDLE_DIRS[@]}" -gt 1 ]; then
+  echo "AMBIGUOUS: Multiple UI bundle directories found — ask the user which one they mean before editing or running any command:" >&2
+  printf '  - %s\n' "${BUNDLE_DIRS[@]}" >&2
+  exit 2
+fi
+
+echo "${BUNDLE_DIRS[0]}"
+exit 0

package/skills/experience-ui-bundle-frontend-generate/scripts/verify-rules.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Grep-based verification of the hard, checkable rules in this skill that
+# `npm run lint` / `npm run build` do not catch on their own — a wrong
+# react-router-dom import, a hardcoded basename, an inline style prop, a
+# stray lightning/*-or-@wire import, or leftover template boilerplate can
+# all lint and build clean while breaking at runtime or shipping unfinished
+# branding.
+#
+# Usage: verify-rules.sh <file-or-dir> [<file-or-dir> ...]
+#   Pass the specific files you edited, or the bundle's src/ directory (and
+#   its index.html) to check everything.
+#
+# Exit 0 if no violations are found.
+# Exit 1 with every violation listed (rule + matching file paths) if any
+# are found — fix them before considering the task complete, even if lint
+# and build passed.
+
+set -uo pipefail
+
+if [ "$#" -eq 0 ]; then
+  echo "ERROR: verify-rules.sh requires at least one file or directory argument" >&2
+  exit 1
+fi
+
+for p in "$@"; do
+  if [ ! -e "$p" ]; then
+    echo "ERROR: path does not exist: $p" >&2
+    exit 1
+  fi
+done
+
+FOUND=0
+
+check() {
+  label="$1"
+  pattern="$2"
+  shift 2
+  hits=$(grep -rlE --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' --include='*.html' \
+    --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=build -- "$pattern" "$@" 2>/dev/null || true)
+  if [ -n "$hits" ]; then
+    echo "ERROR: $label found in:" >&2
+    echo "$hits" | sed 's/^/  - /' >&2
+    FOUND=1
+  fi
+}
+
+check 'import from "react-router-dom" (must be "react-router")' 'from[[:space:]]+['"'"'"]react-router-dom['"'"'"]' "$@"
+check 'a hardcoded basename literal (must derive from <base href> at runtime)' 'basename:[[:space:]]*['"'"'"][/A-Za-z0-9_-]+['"'"'"]' "$@"
+check 'an inline style={{...}} prop (Tailwind utility classes only)' 'style=\{\{' "$@"
+check 'a forbidden lightning/* import or @wire usage (LWC-only)' 'from[[:space:]]+['"'"'"]lightning/|@wire' "$@"
+check 'leftover boilerplate branding (<title>React App</title> / Vite + React)' '<title>[^<]*React App[^<]*</title>|Vite[[:space:]]*\+[[:space:]]*React' "$@"
+
+if [ "$FOUND" -eq 1 ]; then
+  exit 1
+fi
+
+echo "SUCCESS: No hard-rule violations found in: $*"
+exit 0

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

@@ -2,40 +2,46 @@
 name: experience-ui-bundle-metadata-generate
 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"
+  version: "1.2"
   minApiVersion: "51.0"
   relatedSkills:
-    - "experience-ui-bundle-frontend-generate"
     - "experience-ui-bundle-custom-app-generate"
+    - "experience-ui-bundle-frontend-generate"
+    - "experience-ui-bundle-project-generate"
     - "experience-ui-bundle-site-generate"
   cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6.0"
     - tool: ["sf"]
       semver: ">=2.0.0"
-    - tool: ["jq"]
-      semver: ">=1.6"
 ---
 
 # UI Bundle Metadata
 
 ## Scaffolding a New UI Bundle
 
-Use `sf template generate ui-bundle` to create new apps — not create-react-app, Vite, or other generic scaffolds.
+**REQUIRED FIRST STEP — never skip, even if asked to.** Always run `sf template generate ui-bundle` to create new apps — never create-react-app, Vite, hand-written metadata, or any other substitute.
+
+This step is mandatory even if the user says "just create the metadata," "skip the scaffold," "only do the metadata scaffolding," or "stop after the metadata files are in place." Those instructions describe what to stop doing *after* the scaffold (building, deploying, authoring pages) — they do not mean skip running the scaffold command itself. The `.uibundle-meta.xml` and `ui-bundle.json` files are configuration **on top of** the generated project, not a replacement for it. A bundle without `package.json`, `src/`, and `index.html` cannot be built or deployed, even if the metadata files are perfectly formed.
 
 - **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.
+- Pass `--output-dir` to use a different location for template generation. If you do, pass that same path to the verification script in step 1 below.
 
 **Example:**
 ```bash
+# Run from SFDX project root. The CLI will create the bundle under 
+# force-app/main/default/uiBundles/<AppName>/ — verify this before continuing.
 sf template generate ui-bundle -n CoffeeBoutique --template reactbasic
 ```
 
 After generation:
-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.
+1. **Verify the scaffold is complete** — run `bash <skill_dir>/scripts/verify-bundle-location.sh <BundleName> [<CustomOutputDir>]` from the project root and follow any error output. This checks both the bundle's location AND that `package.json`, `src/`, and `index.html` exist — if any are missing, the scaffold step was skipped; go back and run `sf template generate ui-bundle` before continuing. Pass `<CustomOutputDir>` only if you used `--output-dir` during scaffolding; otherwise omit it.
+2. **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.
+3. Replace all default boilerplate — "React App", "Vite + React", default `<title>`, placeholder text
+4. Populate the home page with real content (landing section, banners, hero, navigation)
+5. Update navigation and placeholders (see the `experience-ui-bundle-frontend-generate` skill)
+6. **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.
 
@@ -43,7 +49,9 @@ Always install dependencies before running any scripts in the UI bundle director
 
 ## UIBundle Bundle
 
-A UIBundle bundle lives under `uiBundles/<AppName>/` and must contain:
+A UIBundle bundle **MUST** live under `force-app/main/default/uiBundles/<AppName>/` — never create it at the SFDX project root or under any other path. The SFDX deploy command will not find it otherwise.
+
+The bundle directory must contain:
 
 - `<AppName>.uibundle-meta.xml` — filename must exactly match the folder name
 - A build output directory (default: `dist/`) with at least one file
@@ -160,5 +168,5 @@ Whenever the app references a new external domain: CDN images, external fonts, t
 
 Always also set `isApplicableToConnectSrc` to `true` for preflight/redirect handling.
 
-4. **Create the metadata file** — follow `references/csp-metadata-format.md` for the `.cspTrustedSite-meta.xml` format. Place in `force-app/main/default/cspTrustedSites/`.
+4. **Create the metadata file** — follow `references/csp-metadata-format.md` for the `.cspTrustedSite-meta.xml` format and naming rules. Place in `force-app/main/default/cspTrustedSites/`.
 

package/skills/experience-ui-bundle-metadata-generate/scripts/verify-bundle-location.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+# Verifies that a UI bundle was created under force-app/main/default/uiBundles/
+# (and not at the repo root, which would be non-deployable), AND that the
+# scaffold itself is complete (package.json, src/, index.html present) — not
+# just a hand-authored metadata-only directory.
+#
+# If a custom output directory was used (--output-dir on the scaffold command),
+# pass it as the second argument. The script then verifies the bundle exists
+# there instead of assuming the default location.
+
+set -e
+
+if [[ $# -lt 1 || $# -gt 2 ]]; then
+  echo "ERROR: Bundle name required"
+  echo "Usage: bash verify-bundle-location.sh <BundleName> [<CustomOutputDir>]"
+  exit 1
+fi
+
+BUNDLE_NAME="$1"
+CUSTOM_OUTPUT_DIR="${2:-}"
+
+# Checks that the scaffold actually produced a full React project, not just
+# hand-written metadata files. Returns 1 (and prints guidance) if incomplete.
+# Pass a second argument with the --output-dir value when checking a bundle
+# in a custom location, so the remediation command matches where the bundle
+# actually needs to end up rather than always pointing at the default path.
+check_scaffold_complete() {
+  local bundle_path="$1"
+  local output_dir="${2:-}"
+  local missing=()
+  [[ -f "$bundle_path/package.json" ]] || missing+=("package.json")
+  [[ -d "$bundle_path/src" ]] || missing+=("src/")
+  [[ -f "$bundle_path/index.html" ]] || missing+=("index.html")
+
+  if [[ ${#missing[@]} -gt 0 ]]; then
+    local scaffold_cmd="sf template generate ui-bundle -n $BUNDLE_NAME --template reactbasic"
+    if [[ -n "$output_dir" ]]; then
+      scaffold_cmd="$scaffold_cmd --output-dir \"$output_dir\""
+    fi
+    echo "ERROR: Bundle found at $bundle_path, but the scaffold is incomplete. Missing:" >&2
+    printf '  - %s\n' "${missing[@]}" >&2
+    echo "" >&2
+    echo "This usually means 'sf template generate ui-bundle' was never run — metadata" >&2
+    echo "files alone were hand-authored instead. Run the scaffold command now:" >&2
+    echo "  $scaffold_cmd" >&2
+    echo "Metadata files are configuration ON TOP of the scaffold, not a substitute for it." >&2
+    return 1
+  fi
+  return 0
+}
+
+if [[ -n "$CUSTOM_OUTPUT_DIR" ]]; then
+  CUSTOM_PATH="$CUSTOM_OUTPUT_DIR/$BUNDLE_NAME"
+  if [[ -d "$CUSTOM_PATH" ]]; then
+    if check_scaffold_complete "$CUSTOM_PATH" "$CUSTOM_OUTPUT_DIR"; then
+      echo "OK: Bundle found at $CUSTOM_PATH (custom output-dir location, scaffold complete)"
+      exit 0
+    fi
+    exit 1
+  fi
+  echo "ERROR: Bundle not found at custom output-dir location: $CUSTOM_PATH"
+  echo "Check that --output-dir matched what was passed to the scaffold command."
+  exit 1
+fi
+
+EXPECTED_PATH="force-app/main/default/uiBundles/$BUNDLE_NAME"
+WRONG_PATH="uiBundles/$BUNDLE_NAME"
+
+if [[ -d "$EXPECTED_PATH" ]]; then
+  if check_scaffold_complete "$EXPECTED_PATH"; then
+    echo "OK: Bundle found at $EXPECTED_PATH (deployable location, scaffold complete)"
+    exit 0
+  fi
+  exit 1
+fi
+
+if [[ -d "$WRONG_PATH" ]]; then
+  echo "ERROR: Bundle found at repo root: $WRONG_PATH"
+  echo "This location is NOT deployable. The SFDX deploy command will not find it."
+  echo ""
+  echo "To fix: Move the bundle to force-app/main/default/uiBundles/"
+  echo "  mkdir -p force-app/main/default/uiBundles/ && mv $WRONG_PATH $EXPECTED_PATH"
+  echo ""
+  check_scaffold_complete "$WRONG_PATH" || true
+  exit 1
+fi
+
+echo "ERROR: Bundle not found at either location:"
+echo "  - Expected: $EXPECTED_PATH"
+echo "  - Also checked: $WRONG_PATH"
+echo ""
+echo "If a custom --output-dir was used, re-run this script with that directory"
+echo "as the second argument: bash verify-bundle-location.sh $BUNDLE_NAME <CustomOutputDir>"
+echo ""
+echo "Otherwise, the scaffold command may have failed. Check for errors above."
+exit 1