@salesforce/afv-skills 1.54.0 → 1.56.0

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

@@ -1,8 +1,8 @@
 ---
 name: experience-ui-bundle-features-generate
-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."
+description: "MUST activate when the project contains a uiBundles/*/src/ directory (React or Angular) 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.1"
+  version: "1.2"
   domains: ["Experience"]
   relatedSkills: ["experience-ui-bundle-agentforce-client-generate", "experience-ui-bundle-file-upload-generate"]
   cliTools:
@@ -19,41 +19,79 @@ metadata:
 
 # UI Bundle Features
 
-## Installing Pre-built Features
+Install pre-built, tested feature packages into a Salesforce UI bundle with the
+`@salesforce/ui-bundle-features` CLI instead of hand-building them. This file is the
+**framework-neutral workflow spine**; the framework-specific detail — example file
+extensions, the files features rewrite, how a feature's entry component is mounted, and the
+build command — lives in a per-framework reference under `<SKILL_DIR>/references/<framework>/`.
 
-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.
+Always check for an existing feature before building something from scratch. The CLI is
+framework-agnostic: it installs the framework-appropriate variant of each feature into the
+detected bundle. Authentication and search are the most commonly used 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
+## Step 0: Determine the framework
 
-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.
+`<SKILL_DIR>` = the absolute path to **this skill's own directory** (the folder holding this
+`SKILL.md`); resolve it from the skill path in context.
 
-   Run `scripts/verify-react-bundle.sh`. If it exits non-zero, stop — the bundle is not React-based and this skill cannot proceed.
+The framework is normally already decided by the calling context — passed down by the
+coordinator skill that invoked this one, or stated in the user's request. Use that.
+
+The frameworks this skill supports are exactly the reference folders under
+`<SKILL_DIR>/references/`, each containing a `features.md` (so `react` →
+`<SKILL_DIR>/references/react/features.md`). This is the single source of truth — adding a
+framework means adding a reference folder, nothing here changes.
+
+- **If the framework is known** — open `<SKILL_DIR>/references/<framework>/features.md` and
+  keep it alongside this spine. It supplies the example extensions, the integration targets,
+  the mount example, and the build command.
+- **If it is unknown** (a standalone run where nobody said which) — run the deterministic
+  detector on the UI bundle root before asking anyone:
+
+  ```bash
+  bash "<SKILL_DIR>/scripts/detect-framework.sh" "<path-to-uiBundles/<name>/ dir>"
+  ```
+
+  Branch on the exit code (do not parse prose):
+  - `react` or `angular` (exit 0) → use that framework. **Do not ask the user** — detection is
+    deterministic. Open `<SKILL_DIR>/references/<framework>/features.md`.
+  - `ambiguous` (exit 2) → both frameworks present. List `<SKILL_DIR>/references/` and ask the
+    user which bundle to install into. If they name a framework with no matching reference
+    folder, it is not supported here — stop.
+  - `unknown` (exit 3) → **no supported framework detected. Terminate.** Report that neither
+    React nor Angular signals were found in the bundle, so features cannot be installed, and
+    stop. Do not guess.
+
+Throughout the steps below, `<framework>` means the folder chosen here.
+
+## Workflow
 
 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.
 
-3. **Describe a feature — MANDATORY before wiring.** Run `npx @salesforce/ui-bundle-features describe <feature>` and read the feature's README via `npm view <package> readme` (using the `Package:` name from that output) before wiring it. The README is the contract: it tells you how the feature is meant to be wired — including any drop-in entry component and the file each integration example belongs in. Cross-check against the copied-in source under `describe`'s `Copy Operations` destination — that source (and its JSDoc) is the version-matched truth for what's actually installed. Do not wire from assumptions about file names or component APIs. Skipping this is the most common reason a feature installs successfully but never actually runs.
+3. **Describe a feature — MANDATORY before wiring.** Run `npx @salesforce/ui-bundle-features describe <feature>` and read the feature's README via `npm view <package> readme` (using the `Package:` name from that output) before wiring it. The README is the contract: it tells you how the feature is meant to be wired — including any drop-in entry component and the file each integration example belongs in. Cross-check against the copied-in source under `describe`'s `Copy Operations` destination — that source (and its JSDoc/comments) is the version-matched truth for what's actually installed, in the detected framework's file types. Do not wire from assumptions about file names or component APIs. Skipping this is the most common reason a feature installs successfully but never actually runs.
 
 4. **Install** — use `npx @salesforce/ui-bundle-features install <feature> --ui-bundle-dir <name>`. Key options:
    - `--dry-run` to preview changes
    - `--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.
+   Install features **before** doing custom frontend/layout work in this bundle — features may rewrite the app layout and routing files (see the framework reference for their names), 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
+## Conflict Handling
 
 In non-interactive environments, use the two-pass approach:
 
 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.
+2. Before writing the resolution file, read `references/common/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
    {
@@ -61,59 +99,52 @@ In non-interactive environments, use the two-pass approach:
      "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`.
+   (The conflict paths are whatever the CLI printed for the detected framework — the keys above are illustrative.) Any conflicting path *not* listed 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>`.
 
-### Post-install: Integrating Example Files
+## Post-install: Integrating Example Files
 
-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:
+Features may include example files under an `__examples__/` directory (plural) showing integration patterns. These are often full, working pages with concrete names, not bare placeholder templates — in the detected framework's file types (see the framework reference). 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
+   # Verify the build passes with the integrated pattern (build command per framework reference)
    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__/
+
+   # Verify the pattern from the example is actually present in the target.
+   # Adjust the grep to a key symbol/import/component from the example, over the
+   # detected framework's source files (see the framework reference for a worked pattern).
    ```
+   Only delete `__examples__/` after **both** the build passes and the pattern is confirmed present in the target.
 
 If either check fails, **do NOT delete `__examples__/`** — the integration is incomplete. Fix the integration first, then re-run the verification.
 
-### Post-install: Mount the OOTB component, don't hand-roll a parallel one
+## Post-install: Mount the OOTB component, don't hand-roll a parallel one
 
-When a feature ships an integration point, the UI **must** use it rather than a parallel hand-rolled version. For features that ship an entry component, mount it — e.g. for search, mount the feature's `<Search>` on the search-results page; do **not** author a bespoke results page that queries data directly (a custom `SearchResults.tsx` against seed data or a raw GraphQL call bypasses the installed, tested feature, so the deployed sObject/CMS search never runs). The only exception is when the user **explicitly** opts out and asks for a custom one — confirm that intent, don't infer it.
+When a feature ships an integration point, the UI **must** use it rather than a parallel hand-rolled version. For features that ship an entry component, mount it (the framework reference shows the mount idiom); do **not** author a bespoke page that queries data directly. A custom results page against seed data or a raw GraphQL call bypasses the installed, tested feature, so the deployed sObject/CMS logic never runs. The only exception is when the user **explicitly** opts out and asks for a custom one — confirm that intent, don't infer it.
 
-### Hint Placeholders
+## 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. This is separate from the `__examples__/` convention above — a single copy path can use either mechanism.
 
-### Auth Feature: Org-Side Prerequisites
+## 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):
+Installing the authentication feature only copies files — it does not configure the org. This is framework-agnostic (pure org/metadata config). 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
+## 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.
+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. This is framework-agnostic.
 
 **After every install:**
 ```bash
@@ -123,5 +154,3 @@ If found, move each file to `<metadata-root>/<same-relative-subpath>` (keep `-me
 
 **Verification:**
 - [ ] Re-run `find uiBundles/<AppName> -type d -regex '.*/<[^/]+>$'` — output must be empty before proceeding.
-
-

package/skills/experience-ui-bundle-features-generate/references/angular/features.md

@@ -0,0 +1,74 @@
+# Angular UI Bundle Features
+
+Framework reference for the **Angular** path of `experience-ui-bundle-features-generate`. Read
+this alongside the workflow spine in `SKILL.md`. The `@salesforce/ui-bundle-features` CLI
+installs the Angular variant of each feature into an Angular UI bundle (an `angular.json` at/
+above the bundle, `@angular/core` in `package.json`, standalone components as `.ts` + `.html`
+pairs under `src/app/`).
+
+## Example files
+
+Features ship integration examples under `__examples__/` as Angular sources — a standalone
+component is a **`.ts`** class + its **`.html`** template (e.g. `account-search.ts` +
+`account-search.html`), often full working pages, not bare stubs. Integrate the pattern into
+the target named in `describe` output, then verify before deleting the `__examples__/` dir.
+
+> Do not assume file names or a `.component` infix — Angular UI bundle starters name
+> components without it (`home.ts`, not `home.component.ts`). The `describe` `Copy Operations`
+> destination and the copied-in source are the version-matched truth for what was installed.
+
+## Files features may rewrite
+
+Angular features commonly touch app wiring:
+
+- `src/app/app.routes.ts` — route registration (route-based features add routes here)
+- `src/app/app.ts` + `src/app/app.html` — root component and its template
+- the app-layout component under `src/app/components/layout/` — the shell some features mount into
+
+These are the paths to expect as conflicts in the two-pass conflict flow; resolve them per
+`SKILL.md` → *Conflict Handling* (the exact paths are whatever the CLI prints).
+
+## Mount the feature's entry component
+
+Mount the OOTB component the feature ships rather than hand-rolling a parallel one. Angular
+mounts by **selector** (in a template) or by **route** (lazy-loaded standalone component) —
+use whichever `describe`/README specifies. For search mounted on a results page template:
+
+```html
+<!-- search-results.html — use the feature's selector; do NOT hand-roll a results page -->
+<sf-search />
+```
+
+Or as a route in `src/app/app.routes.ts`:
+
+```ts
+export const routes: Routes = [
+  { path: "search", loadComponent: () =>
+      import("./features/search/search").then((m) => m.Search) },  // path per describe output
+];
+```
+
+Import the feature's standalone component into whichever component's `imports:` array hosts it.
+
+## Build & verify
+
+Build command (run from the UI bundle dir):
+
+```bash
+npm run build
+```
+
+Worked grep for the *verify-before-delete* check — Angular splits usage across `.ts` (selector
+registration, service imports, route entry) and `.html` (the mounted selector). Adjust the
+symbol to one from the example you integrated:
+
+```bash
+grep -rq "sf-search\|SearchService" src/app --include='*.ts' --include='*.html' 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 `rm -rf __examples__/` after the build passes **and** this grep confirms the pattern is
+present in the target.

package/skills/experience-ui-bundle-features-generate/references/react/features.md

@@ -0,0 +1,59 @@
+# React UI Bundle Features
+
+Framework reference for the **React** path of `experience-ui-bundle-features-generate`. Read
+this alongside the workflow spine in `SKILL.md`. The `@salesforce/ui-bundle-features` CLI
+installs the React variant of each feature into a React/Vite UI bundle (`"react"` in the
+bundle `package.json`, `.tsx` sources under `src/`).
+
+## Example files
+
+Features ship integration examples under `__examples__/` as **`.tsx`** files — often full,
+working pages with concrete names (e.g. `AccountSearch.tsx`), not bare stubs. Integrate the
+pattern into the target file named in `describe` output, then verify before deleting the
+`__examples__/` dir.
+
+## Files features may rewrite
+
+React features commonly touch the app shell and routing:
+
+- `src/appLayout.tsx` — the app layout/shell
+- `src/routes.tsx` — route registration
+- `src/App.tsx` — app entry (some features mount here)
+
+These are the paths to expect as conflicts in the two-pass conflict flow; resolve them per
+`SKILL.md` → *Conflict Handling* (the exact paths are whatever the CLI prints).
+
+## Mount the feature's entry component
+
+Mount the OOTB component the feature ships rather than hand-rolling a parallel one. For search,
+mount the feature's `<Search>` component (JSX) on the search-results page:
+
+```tsx
+import { Search } from "./features/search";      // path per describe output
+// ...
+export default function SearchResults() {
+  return <Search />;                              // do NOT hand-roll a results page
+}
+```
+
+## Build & verify
+
+Build command (run from the UI bundle dir):
+
+```bash
+npm run build
+```
+
+Worked grep for the *verify-before-delete* check (adjust the symbol to one from the example
+you integrated — here the `SearchInput`/`useSearch` pattern integrated into a page):
+
+```bash
+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 `rm -rf __examples__/` after the build passes **and** this grep confirms the pattern is
+present in the target.

package/skills/experience-ui-bundle-features-generate/scripts/detect-framework.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+#
+# detect-framework.sh — deterministic UI Bundle framework detector.
+#
+# Usage: bash detect-framework.sh [ROOT]
+#   ROOT  app or uiBundle root to inspect (default: current directory)
+#
+# Prints exactly one of the following tokens to stdout, nothing else, and sets
+# a matching exit code so callers can branch without parsing:
+#   react      (exit 0) — React signals only
+#   angular    (exit 0) — Angular signals only
+#   ambiguous  (exit 2) — both React and Angular signals present
+#   unknown    (exit 3) — neither framework detected
+#
+# Step 0 of the skill acts on the result: a single framework (exit 0) proceeds;
+# `ambiguous` asks the user to disambiguate; `unknown` TERMINATES the workflow
+# (no supported framework found — do not guess).
+
+set -u
+
+ROOT="${1:-.}"
+angular=0
+react=0
+
+# Resolve ROOT to an absolute path when possible (for the angular.json walk-up).
+abs_root="$(cd "$ROOT" 2>/dev/null && pwd || true)"
+
+# 1) angular.json at or above ROOT → Angular workspace.
+dir="$abs_root"
+while [ -n "$dir" ]; do
+  [ -f "$dir/angular.json" ] && angular=1
+  [ "$dir" = "/" ] && break
+  dir="$(dirname "$dir")"
+done
+
+# 2) package.json dependencies (excluding node_modules).
+while IFS= read -r pkg; do
+  [ -z "$pkg" ] && continue
+  grep -q '"@angular/core"' "$pkg" 2>/dev/null && angular=1
+  grep -Eq '"react"[[:space:]]*:' "$pkg" 2>/dev/null && react=1
+done <<EOF
+$(find "$ROOT" -type d -name node_modules -prune -o -type f -name package.json -print 2>/dev/null)
+EOF
+
+# 3) Source-file signatures (excluding node_modules).
+has_file() {
+  find "$ROOT" -type d -name node_modules -prune -o -type f -name "$1" -print 2>/dev/null | grep -q .
+}
+
+# Angular: component files, routing module, or @Component-decorated classes.
+has_file '*.component.ts' && angular=1
+has_file 'app.routes.ts' && angular=1
+if grep -rls --exclude-dir=node_modules --include='*.ts' '@Component' "$ROOT" 2>/dev/null | grep -q .; then
+  angular=1
+fi
+
+# React: JSX/TSX source files.
+has_file '*.tsx' && react=1
+has_file '*.jsx' && react=1
+
+if [ "$angular" -eq 1 ] && [ "$react" -eq 1 ]; then
+  echo ambiguous
+  exit 2
+elif [ "$angular" -eq 1 ]; then
+  echo angular
+  exit 0
+elif [ "$react" -eq 1 ]; then
+  echo react
+  exit 0
+else
+  echo unknown
+  exit 3
+fi

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

@@ -60,11 +60,11 @@ A request to rename/rebrand the app (e.g. "call it X everywhere a user would see
 Some capabilities ship as pre-built, tested feature packages. The catalog **evolves and is not something you can know from memory** — never decide from the request wording alone whether a capability "is" or "isn't" a feature. Before hand-writing any non-trivial capability (anything beyond a plain page, component, or styling change) in this skill:
 
 1. **Consult the authoritative catalog.** Invoke `experience-ui-bundle-features-generate`, which runs `list` to show the *current* set of installable features. Do not rely on a hardcoded or remembered list — this skill deliberately names none, because any names it listed would go stale.
-2. **Detect whether a matching feature is already installed** in the bundle — inspect `package.json` dependencies and existing `src/` files. If present, use it as-is; do not reinstall or re-implement.
+2. **Detect whether a matching feature is already installed** in the bundle — inspect `package.json` dependencies and existing `src/` files. If present, do not reinstall or re-implement it — **but you must still adopt it**: invoke `experience-ui-bundle-features-generate` to `describe` it (which reads the feature's README — the adoption contract), wire it into the app, and, if the feature ships config (e.g. a `config.json`), set that for this app's data and use case. Installed-but-unconfigured is not done.
 3. **If a matching feature exists in the catalog but isn't installed**, let `experience-ui-bundle-features-generate` install the tested package. Do not build it from scratch here.
 4. **Only hand-build** a capability that has no matching catalog feature.
 
-This gate is **idempotent**: when this skill runs as a phase of `experience-ui-bundle-app-coordinate` (which installs features earlier in its sequence), step 2 finds the feature already present and this collapses to a no-op. It only does real work when the skill was reached directly — the path that would otherwise skip feature detection.
+When this skill runs as a phase of `experience-ui-bundle-app-coordinate`, a matching feature is often already present — installed by an earlier phase, or shipped by the template. Already-present is **not** a reason to skip: step 2 still requires adopting and configuring that feature for this app. Only the install/re-implement work is ever skipped — never the wiring and configuration.
 
 ---
 

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

@@ -1,8 +1,8 @@
 ---
 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)."
+description: "Use this skill when adding a front-end React or Angular UI bundle to an EXISTING SFDX project, or configuring UI bundle metadata and config files. TRIGGER when: adding or scaffolding a new UI bundle — including adding one more or another UI bundle — into a project that already exists; scaffolding a single bundle with the basic template (reactbasic or angularbasic) via 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 entirely from scratch, where the whole SFDX starter project (UI bundle plus Experience Site metadata and toolchain) is generated together in one step (use experience-ui-bundle-project-generate)."
 metadata:
-  version: "1.2"
+  version: "1.3"
   domains: ["Experience"]
   minApiVersion: "67.0"
   relatedSkills:
@@ -21,25 +21,37 @@ metadata:
 
 ## Scaffolding a New UI Bundle
 
-**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.
+**REQUIRED FIRST STEP — never skip, even if asked to.** Always run `sf template generate ui-bundle` to create new apps — never a framework CLI (create-react-app, Vite, Angular CLI), 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.
+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 an entry `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. If you do, pass that same path to the verification script in step 1 below.
+### Determine the framework
 
-**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
+The frameworks this skill supports are exactly the reference files under `<skill_dir>/references/`, each named `<framework>-metadata-generate.md` (`react`, `angular`, …). This is the single source of truth — adding a framework means adding a reference file, nothing here changes.
+
+**Detect the framework deterministically — run the script:**
+
+```sh
+bash <skill_dir>/scripts/detect-framework.sh [<ROOT>]
 ```
 
+`ROOT` defaults to the current directory; pass the bundle or project root when editing/configuring an existing bundle. The script prints exactly one token and sets a matching exit code — branch on it:
+
+- `react` / `angular` (exit 0) — open `<skill_dir>/references/<framework>-metadata-generate.md` and use it.
+- `ambiguous` (exit 2, both frameworks present) — ask the user which one, then use that reference.
+- `unknown` (exit 3, no signals — e.g. scaffolding a brand-new bundle into a project that has none yet) — fall back to the calling context or the user's stated framework; if still undecided, list `<skill_dir>/references/`, derive the supported set by stripping the `-metadata-generate.md` suffix from each filename, and ask the user to pick.
+
+If the calling context or the user already named the framework, that overrides detection — but still confirm a matching reference file exists. **Never guess.**
+
+The reference file gives you the exact `--template` flag, the entry-file layout, and the default boilerplate strings to replace for that framework.
+
+- **UI bundle name (`-n`):** Alphanumerical only — no spaces, hyphens, underscores, or special characters.
+- 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.
+
 After generation:
-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.
+1. **Verify the scaffold is complete** — run `bash <skill_dir>/scripts/verify-bundle-location.sh <BundleName> [<CustomOutputDir>] [<framework>]` from the project root and follow any error output. This checks both the bundle's location AND that `package.json`, `src/`, and an entry `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 (pass `""` to skip it while still supplying a framework); pass `<framework>` (`react` or `angular`) so the remediation hint uses the right template.
 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
+3. Replace all default boilerplate — the framework reference file lists the exact stock `<title>` and placeholder strings to replace
 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.

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

@@ -0,0 +1,37 @@
+# Angular UI Bundle Scaffold
+
+Reference for the **Angular** path of `experience-ui-bundle-metadata-generate`. Use this to scaffold the bundle, then return to the "After generation" steps in `SKILL.md`.
+
+## Scaffold command
+
+Always pass `--template angularbasic` to scaffold an Angular bundle:
+
+```bash
+# Run from SFDX project root. The CLI creates the bundle under
+# force-app/main/default/uiBundles/<AppName>/ — verify this before continuing.
+sf template generate ui-bundle -n CoffeeBoutique --template angularbasic
+```
+
+Pass `--output-dir` to generate at a different location. If you do, pass that same path to `verify-bundle-location.sh` in the verification step.
+
+## What the scaffold produces
+
+An Angular (TypeScript, standalone components) app under `force-app/main/default/uiBundles/<AppName>/`:
+
+- **Entry HTML:** `src/index.html` (NOT the bundle root), mounting `<app-root>` and carrying a `<base href="/">`.
+- **App entry:** `src/main.ts`; `src/app/app.ts` + `src/app/app.html`, `src/app/app.config.ts`, `src/app/app.routes.ts`; pages under `src/app/pages/`.
+- **Build:** Angular CLI driven by `angular.json` with the `@angular-builders/custom-esbuild:application` builder. Salesforce integration (API-version substitution, org proxy, Live Preview / `SFDC_ENV` / base-href injection) is wired via the esbuild plugin + `middleware/` — no `vite.config.ts`.
+- **Build output:** the builder's `outputPath.browser` is flattened to `dist/`, matching `ui-bundle.json` `outputDir: "dist"` — same as React.
+
+## Default boilerplate to replace
+
+Replace every stock string before shipping — searching for these is the fastest way to find them:
+
+- `<title>MyAngularApp</title>` in `src/index.html` → a real product title.
+- Default `<app-root>` welcome/landing markup in `src/app/app.html` and any placeholder page stubs under `src/app/pages/`.
+- Placeholder navigation and empty routes (see `experience-ui-bundle-frontend-generate`).
+
+## Notes
+
+- **Dev-server port / CSP:** the Angular bundle's dev server is `sf-angular-serve` (the `package.json` `dev` script, provided by `@salesforce/angular-plugin-ui-bundle`), whose default port is `5173` — the same as React's Vite default — overridable with `SF_UIBUNDLE_PORT`. No Angular-specific CSP Trusted Site change is needed for local dev vs React.
+- **Element/binding syntax:** Angular uses `<app-root>` and standalone components with native control flow (`@if` / `@for`) — not JSX. This only matters when authoring pages; the metadata and config files below are framework-neutral.

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

@@ -0,0 +1,32 @@
+# React UI Bundle Scaffold
+
+Reference for the **React** path of `experience-ui-bundle-metadata-generate`. Use this to scaffold the bundle, then return to the "After generation" steps in `SKILL.md`.
+
+## Scaffold command
+
+Always pass `--template reactbasic` to scaffold a React/Vite bundle:
+
+```bash
+# Run from SFDX project root. The CLI creates the bundle under
+# force-app/main/default/uiBundles/<AppName>/ — verify this before continuing.
+sf template generate ui-bundle -n CoffeeBoutique --template reactbasic
+```
+
+Pass `--output-dir` to generate at a different location. If you do, pass that same path to `verify-bundle-location.sh` in the verification step.
+
+## What the scaffold produces
+
+A React + Vite (TypeScript) app under `force-app/main/default/uiBundles/<AppName>/`:
+
+- **Entry HTML:** `index.html` at the bundle root, mounting `<div id="root">` and loading `src/app.tsx`.
+- **App entry:** `src/app.tsx`; pages under `src/pages/`, components under `src/components/`.
+- **Toolchain:** `vite.config.ts`, `package.json`, shadcn/ui primitives, Tailwind, GraphQL client + `codegen.yml`.
+- **Build output:** `dist/` (matches `ui-bundle.json` `outputDir: "dist"`).
+
+## Default boilerplate to replace
+
+Replace every stock string before shipping — searching for these is the fastest way to find them:
+
+- `<title>Welcome to React App</title>` in `index.html` → a real product title.
+- Any "React App" / "Vite + React" placeholder copy and default hero/landing text.
+- Placeholder navigation and empty page stubs (see `experience-ui-bundle-frontend-generate`).

package/skills/experience-ui-bundle-metadata-generate/scripts/detect-framework.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+#
+# detect-framework.sh — deterministic UI Bundle framework detector.
+#
+# Usage: bash detect-framework.sh [ROOT]
+#   ROOT  app or uiBundle root to inspect (default: current directory)
+#
+# Prints exactly one of the following tokens to stdout, nothing else, and sets
+# a matching exit code so callers can branch without parsing:
+#   react      (exit 0) — React signals only
+#   angular    (exit 0) — Angular signals only
+#   ambiguous  (exit 2) — both React and Angular signals present
+#   unknown    (exit 3) — neither framework detected
+#
+# Step 0 of the skill acts on the result: a single framework (exit 0) proceeds;
+# `ambiguous` asks the user to disambiguate; `unknown` TERMINATES the workflow
+# (no supported framework found — do not guess).
+
+set -u
+
+ROOT="${1:-.}"
+angular=0
+react=0
+
+# Resolve ROOT to an absolute path when possible (for the angular.json walk-up).
+abs_root="$(cd "$ROOT" 2>/dev/null && pwd || true)"
+
+# 1) angular.json at or above ROOT → Angular workspace.
+dir="$abs_root"
+while [ -n "$dir" ]; do
+  [ -f "$dir/angular.json" ] && angular=1
+  [ "$dir" = "/" ] && break
+  dir="$(dirname "$dir")"
+done
+
+# 2) package.json dependencies (excluding node_modules).
+while IFS= read -r pkg; do
+  [ -z "$pkg" ] && continue
+  grep -q '"@angular/core"' "$pkg" 2>/dev/null && angular=1
+  grep -Eq '"react"[[:space:]]*:' "$pkg" 2>/dev/null && react=1
+done <<EOF
+$(find "$ROOT" -type d -name node_modules -prune -o -type f -name package.json -print 2>/dev/null)
+EOF
+
+# 3) Source-file signatures (excluding node_modules).
+has_file() {
+  find "$ROOT" -type d -name node_modules -prune -o -type f -name "$1" -print 2>/dev/null | grep -q .
+}
+
+# Angular: component files, routing module, or @Component-decorated classes.
+has_file '*.component.ts' && angular=1
+has_file 'app.routes.ts' && angular=1
+if grep -rls --exclude-dir=node_modules --include='*.ts' '@Component' "$ROOT" 2>/dev/null | grep -q .; then
+  angular=1
+fi
+
+# React: JSX/TSX source files.
+has_file '*.tsx' && react=1
+has_file '*.jsx' && react=1
+
+if [ "$angular" -eq 1 ] && [ "$react" -eq 1 ]; then
+  echo ambiguous
+  exit 2
+elif [ "$angular" -eq 1 ]; then
+  echo angular
+  exit 0
+elif [ "$react" -eq 1 ]; then
+  echo react
+  exit 0
+else
+  echo unknown
+  exit 3
+fi