@salesforce/afv-skills 1.50.0 → 1.52.0

package/skills/experience-ui-bundle-localize/references/{i18n-setup.md → react/i18n-setup.md}

@@ -4,6 +4,24 @@ You write two files to set up i18n in a React UI Bundle. The Platform SDK provid
 
 ---
 
+## FIRST: is this a B2E or a B2C bundle?
+
+**Decide before you copy the example below.** The example in File 1 is **B2E**. A B2C
+(guest / public site) bundle is **not** a copy of it — you MUST change two things, or the
+site renders the wrong language and text direction for guest users:
+
+| | B2E (authenticated) | B2C (guest site) |
+|---|---|---|
+| Fallback | omit `labelFallback` (SDK default `BASE_VALUE`) | **`labelFallback: "USER_DEFAULT"`** |
+| Init language | omit `lng` (detector resolves it) | **`lng: resolvedLang`** in `i18next.init` |
+| Document dir/lang | `document.documentElement.dir = ctx.dir` | **`i18next.dir(resolvedLang)`**, not `ctx.dir` |
+
+If the prompt mentions a public site, guest users, a community/Experience site, or a
+language switcher on a public page, it is **B2C** — jump to the [B2C section](#b2c-changes)
+and apply all three overrides. Do **not** ship the B2E `ctx.dir` + no-fallback wiring to a B2C site.
+
+---
+
 ## File 1: `src/i18n/index.ts` (the init wiring)
 
 This is the only "glue" you write. It connects the SDK's i18n pieces to i18next.
@@ -25,7 +43,8 @@ export async function initI18n() {
   const dataSDK = await createDataSDK();
   const ctx = await fetchI18nContext(dataSDK);
 
-  // B2E: the session language is the display language.
+  // B2E ONLY: the session language is the display language.
+  // B2C MUST NOT use ctx.dir here — see the B2C section below.
   document.documentElement.dir = ctx.dir;
   document.documentElement.lang = ctx.lang;
 
@@ -40,7 +59,7 @@ export async function initI18n() {
         backends: [LocalStorageBackend, SalesforceBackend],
         backendOptions: [
           { expirationTime: 86400000 }, // cache labels in localStorage for a day
-          { dataSDK, labelManifest }, // B2E: shipped BASE_VALUE fallback
+          { dataSDK, labelManifest }, // B2E ONLY: shipped BASE_VALUE fallback. B2C MUST add labelFallback: "USER_DEFAULT" — see below.
         ],
       },
       interpolation: {
@@ -59,7 +78,13 @@ export async function initI18n() {
 
 The example above is the **B2E** configuration. Do not set `labelFallback` for B2E: the shipped `SalesforceBackend` default is `BASE_VALUE`.
 
-For a **B2C** bundle, change only the Salesforce backend options entry:
+<a id="b2c-changes"></a>
+### B2C changes (REQUIRED for guest sites)
+
+For a **B2C** bundle you MUST make **all three** changes below. Omitting any one is the most
+common defect: it renders the guest's fallback, display language, or text direction wrong.
+
+**Change 1 — fallback.** Change the Salesforce backend options entry:
 
 ```typescript
 backendOptions: [
@@ -74,7 +99,7 @@ backendOptions: [
 
 `USER_DEFAULT` is required for B2C so fallback follows the guest/site language context. Do not copy this override into B2E wiring.
 
-For B2C, explicitly pass the route-selected display language to i18next and use it for the document language and direction, rather than relying on the detector or `ctx.dir`. The GraphQL i18n context direction reflects the guest session profile and can stay `ltr` after the site switches to an RTL language. Reuse the resolved language from the site's language-switcher integration:
+**Change 2 — document direction/language.** Set the document language and direction from the route-selected display language, **not `ctx.dir`**. The GraphQL i18n context direction reflects the guest session profile and can stay `ltr` after the site switches to an RTL language. Replace the B2E `document.documentElement.dir = ctx.dir` / `.lang = ctx.lang` lines with the resolved language from the site's language-switcher integration:
 
 ```typescript
 const resolvedLang =
@@ -83,7 +108,19 @@ document.documentElement.dir = i18next.dir(resolvedLang);
 document.documentElement.lang = resolvedLang.replace(/_/g, "-");
 ```
 
-Then add `lng: resolvedLang` to the B2C `i18next.init({ ... })` options. The B2E example above remains unchanged.
+**Change 3 — init language.** Add `lng: resolvedLang` to the `i18next.init({ ... })` options so i18next initializes in the route-selected language:
+
+```typescript
+await i18next
+  // ...ChainedBackend / detector / initReactI18next as above...
+  .init({
+    lng: resolvedLang, // B2C: initialize in the route-selected language
+    fallbackLng: "en",
+    // ...defaultNS, backend, interpolation as above...
+  });
+```
+
+The SDK detector does **not** read `SFDC_ENV.language`. Without an explicit `lng`, labels can stay in the guest-session language after the site route selects another locale. Reuse the same `resolvedLang` computed in Change 2. Do not set `lng` for B2E — the detector resolves the session language there.
 
 Before using this configuration, have an org admin confirm that `GraphQLApiOrgPrefForGuestUsers` is already enabled. This workflow must never enable it. Without the preference, unauthenticated GraphQL label requests return HTTP 403; see dependency W-23854208.
 
@@ -122,7 +159,7 @@ The manifest is how i18next knows what to fetch. An **unregistered key fails sil
 
 ## B2C language context
 
-A B2C site's configured languages and language-specific URLs are the source of truth. At boot, the site route supplies `SFDC_ENV.language`; pass that value explicitly as i18next's `lng`, with `ctx.lang` as fallback. The SDK detector does not read `SFDC_ENV.language` itself. A language switcher must navigate to the target language URL and perform a full page reload. An in-place i18next language change is insufficient because the SDK context and localStorage-backed labels are established at boot.
+A B2C site's configured languages and language-specific URLs are the source of truth. At boot, the site route supplies `SFDC_ENV.language`; the SDK detector uses that value to resolve labels. A language switcher must navigate to the target language URL and perform a full page reload. An in-place i18next language change is insufficient because the SDK context and localStorage-backed labels are established at boot.
 
 For local preview, use the site entry of the Vite plugin and pass the site's supported language codes, with the default first:
 
@@ -171,7 +208,7 @@ If you see an older example that vendors `salesforce-detector.ts` or `salesforce
 
 1. Bundle loads, `initI18n()` runs
 2. `createDataSDK()` initializes the SDK
-3. `fetchI18nContext()` queries the org for language/locale/direction; B2C separately passes the site route's `SFDC_ENV.language` to i18next as `lng`
+3. `fetchI18nContext()` queries the org for language/locale/direction (B2C uses the site route's `SFDC_ENV.language`)
 4. `SalesforceBackend` reads the manifest and issues a GraphQL query per namespace:
    ```graphql
    query LoadLabels {
@@ -209,7 +246,8 @@ For most bundles, a single `"c"` namespace is all you need.
 
 ## Related
 
-- [label-xml.md](label-xml.md): the Custom Labels metadata XML shape
+- [../common/platform-sdk-i18n.md](../common/platform-sdk-i18n.md): the shared runtime engine (Labels query, `fetchI18nContext`, batching, fallback)
+- [../common/label-xml.md](../common/label-xml.md): the Custom Labels metadata XML shape
 - [interpolation.md](interpolation.md): how `{0}/{1}` placeholders work
-- [verifying.md](verifying.md): the serve/verify flow
-- [gotchas.md](gotchas.md): silent-fail traps to avoid
+- [../common/verifying.md](../common/verifying.md): the serve/verify flow
+- [../common/gotchas.md](../common/gotchas.md): silent-fail traps to avoid

package/skills/experience-ui-bundle-localize/references/{interpolation.md → react/interpolation.md}

@@ -163,7 +163,7 @@ t("Nonexistent_Key");
 // → "Nonexistent_Key" (literal key string)
 ```
 
-This is the **unregistered manifest key** trap (see [gotchas.md](gotchas.md)): the label wasn't fetched, so i18next has nothing to interpolate.
+This is the **unregistered manifest key** trap (see [../common/gotchas.md](../common/gotchas.md)): the label wasn't fetched, so i18next has nothing to interpolate.
 
 ---
 
@@ -306,6 +306,6 @@ With the bridge (`prefix: "{", suffix: "}"`), **one Custom Label serves all thre
 ## Related
 
 - [i18n-setup.md](i18n-setup.md): the init file where the `prefix`/`suffix` are configured
-- [label-xml.md](label-xml.md): how to author labels with placeholders
-- [verifying.md](verifying.md): testing interpolated labels
-- [gotchas.md](gotchas.md): silent-fail traps
+- [../common/label-xml.md](../common/label-xml.md): how to author labels with placeholders
+- [../common/verifying.md](../common/verifying.md): testing interpolated labels
+- [../common/gotchas.md](../common/gotchas.md): silent-fail traps

package/skills/experience-ui-bundle-localize/references/react/localize.md

@@ -0,0 +1,76 @@
+# React reference — Localize a React UI Bundle
+
+Framework-specific companion to `SKILL.md` for the **React** path. `SKILL.md` owns the
+neutral workflow + guardrail spine (Step 0 routing, preconditions, the five steps, and
+the guardrails); this file owns everything React/i18next-specific: the runtime library,
+the call convention, the wiring shape, and the depth docs.
+
+## Library & call convention
+
+A React UI Bundle can't use `@salesforce/label/*` the way LWC does — those imports
+resolve at compile time inside the platform's compiler, which your standalone React
+bundle doesn't go through. Instead the app **fetches labels at runtime** through the
+Salesforce GraphQL UI API and hands them to **i18next** (via `react-i18next`) to render.
+
+```tsx
+import { useTranslation } from "react-i18next";
+
+function WelcomeBanner() {
+  const { t } = useTranslation("c"); // "c" = custom label namespace
+  return <h1>{t("Welcome_Text")}</h1>; // renders "Welcome" or "Bienvenido" per user's language
+}
+```
+
+- **Call site:** `t("Key")` (from `useTranslation("c")`).
+- **Files scanned for user-facing strings / call sites:** `.tsx` / `.jsx`.
+- **Import to add** when a component first calls `t()`:
+  `import { useTranslation } from "react-i18next";` and `const { t } = useTranslation("c");`.
+
+## Step 2 (Extract) — React specifics
+
+Replace the JSX literal with a `t()` call and add the import:
+
+```tsx
+// Before: <h1>Welcome</h1>
+// After:  <h1>{t("Welcome_Text")}</h1>
+```
+
+## Step 4 (Wire) — React specifics
+
+Install the i18n dependencies (tell the user to run, from the UI bundle dir):
+
+```bash
+npm install i18next react-i18next i18next-chained-backend i18next-localstorage-backend
+```
+
+Then scaffold `src/i18n/index.ts` (the `initI18n()` that wires
+`@salesforce/platform-sdk/i18n` into i18next) and `src/i18n/label-manifest.ts`, and call
+`initI18n()` once at boot in the entry file (usually `src/index.tsx`) before mounting the
+app. Full init code and the B2E vs B2C `SalesforceBackend` configuration are in
+[i18n-setup.md](./i18n-setup.md).
+
+## Scripts
+
+Run them from the UI bundle dir (they scan `src/` relative to the current directory). The
+first three are framework-neutral and live in the skill's shared `scripts/` folder;
+`check-i18n-wired.sh` is React-specific (i18next `backendOptions` detection) and ships here
+in the React reference folder.
+
+| Script | Purpose |
+|--------|---------|
+| [`check-org-api-version.sh`](../../scripts/check-org-api-version.sh) | Precondition 4 — org supports API v68.0+ |
+| [`detect-bundle-type.sh`](../../scripts/detect-bundle-type.sh) | Precondition 5 — classify B2E / B2C / internal |
+| [`check-manifest-registered.sh --framework react`](../../scripts/check-manifest-registered.sh) | Step 3 — every `t("Key")` is registered in the manifest (`--framework react` selects the `.tsx/.jsx` + `t()` grammar) |
+| [`check-i18n-wired.sh`](./check-i18n-wired.sh) | Step 4 — `initI18n()` defined, called at boot, manifest passed into `backendOptions` |
+
+## Depth docs
+
+Framework-neutral (shared with Angular), in [`../common/`](../common/):
+- [platform-sdk-i18n.md](../common/platform-sdk-i18n.md) — the shared runtime engine: the Labels GraphQL query, `fetchI18nContext`, the manifest format, batching, and fallback
+- [label-xml.md](../common/label-xml.md) — Custom Labels and translation metadata XML shapes; the `namespace:Key` rules
+- [verifying.md](../common/verifying.md) — serve URL, locale flip, and verifying labels render
+- [gotchas.md](../common/gotchas.md) — the silent-fail traps: unregistered manifest keys, API-version bake-in, stale label cache
+
+React-specific (this folder):
+- [i18n-setup.md](./i18n-setup.md) — the two files you write: the i18next init and the label manifest
+- [interpolation.md](./interpolation.md) — positional `{0}/{1}` placeholder interpolation in labels

package/skills/experience-ui-bundle-localize/scripts/check-manifest-registered.sh

@@ -14,22 +14,58 @@ set -euo pipefail  # exit on error (-e), undefined vars (-u), and propagate pipe
 # manifest's boilerplate example comment is stripped first so a commented-out
 # sample key does not mask a genuinely missing one.
 #
+# This script is framework-agnostic EXCEPT for the call-site extraction (which
+# file extensions to scan, and the translation-call grammar). That single block
+# is selected by --framework; the rest — find the manifest, strip its comments,
+# set-compare called-vs-registered keys, report missing — is shared. React's
+# grammar is t("Key") in .tsx/.jsx; Angular's ngx-translate grammar is the
+# `| translate` pipe and `[translate]="'Key'"` binding in .html/.ts templates
+# plus translate.instant/get/stream("Key") service calls in .ts (see
+# references/angular/localize.md).
+#
 # Usage (run from the UI bundle dir, or pass its src path):
-#   bash <skill-dir>/scripts/check-manifest-registered.sh [src-dir]
+#   bash <skill-dir>/scripts/check-manifest-registered.sh [--framework react|angular] [src-dir]
 #
-# src-dir defaults to "src". label-manifest.ts is found anywhere under it.
+# --framework defaults to "react". src-dir defaults to "src"; label-manifest.ts
+# is found anywhere under it. Order of the flag and src-dir does not matter.
 #
-# Exit codes (kept aligned with check-i18n-wired.sh so the workflow branches on
-# the code, not the message text):
+# Exit codes (kept aligned with references/react/check-i18n-wired.sh so the
+# workflow branches on the code, not the message text):
 #   0  every t() key is registered (or there are no t() calls / no manifest to
 #      cross-check — nothing to gate)
-#   1  one or more t() keys are missing from the manifest — stop and register them
-#  64  usage error — the source dir does not exist (bad argument or wrong cwd).
-#      This is NOT a "keys missing" result; do not scaffold or register. Fix the
-#      path and re-run. (64 = EX_USAGE, kept out of the 0/1 semantic range so
-#      exit 1 uniquely means "keys missing".)
+#   1  one or more call-site keys are missing from the manifest — stop and register them
+#  64  usage error — the source dir does not exist, an option is malformed, or the
+#      requested framework is unknown. This is NOT a "keys missing" result; do not
+#      scaffold or register. Fix the input and re-run. (64 = EX_USAGE, kept out of
+#      the 0/1 semantic range so exit 1 uniquely means "keys missing".)
+
+FRAMEWORK="react"
+SRC_DIR=""
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --framework)
+      [ "$#" -ge 2 ] || { echo "ERROR: --framework requires a value (react|angular)" >&2; exit 64; }
+      FRAMEWORK="$2"; shift 2 ;;
+    --framework=*) FRAMEWORK="${1#*=}"; shift ;;
+    -*) echo "ERROR: unknown option: $1" >&2; exit 64 ;;
+    *)
+      if [ -z "$SRC_DIR" ]; then SRC_DIR="$1"; shift
+      else echo "ERROR: unexpected extra argument: $1" >&2; exit 64; fi ;;
+  esac
+done
+SRC_DIR="${SRC_DIR:-src}"
+
+# Select the framework's call-site grammar. CALL_LABEL is the human name for a
+# call site, used only in report messages so they read for the selected framework
+# (React `t()`, Angular `translate`) instead of hardcoding one framework's
+# convention in this otherwise-shared script. The extraction block itself is
+# selected by FRAMEWORK further below.
+case "$FRAMEWORK" in
+  react) CALL_LABEL='t()' ;;        # extraction below is React's t("Key") grammar
+  angular) CALL_LABEL='translate' ;; # extraction below is ngx-translate's grammar
+  *) echo "ERROR: unknown framework: '$FRAMEWORK' (expected: react | angular)" >&2; exit 64 ;;
+esac
 
-SRC_DIR="${1:-src}"
 if [ ! -d "$SRC_DIR" ]; then
   echo "ERROR: source dir not found: $SRC_DIR (run from the UI bundle dir, or pass its src path)" >&2
   exit 64
@@ -37,23 +73,55 @@ fi
 
 MANIFEST=$(find "$SRC_DIR" -type f -name 'label-manifest.ts' | head -1 || true)
 
-# Collect t("Key") / t('Key') call sites from component files, keeping the
-# trailing key segment (drop any "ns:" prefix). Use POSIX character classes and
-# an explicit boundary, not \b / \s: BSD/macOS grep -E silently ignores those,
-# which would miss call sites on a Mac (the platform this skill targets) and let
-# an unregistered key slip through — the exact silent-fail this script guards.
-# (^|[^A-Za-z0-9_]) before t( stops "insertText(" / "print(" matching as t(.
-CALLED=$(grep -rhoE "(^|[^A-Za-z0-9_])t\([[:space:]]*[\"'\`][^\"'\`]+[\"'\`]" "$SRC_DIR" \
-           --include='*.tsx' --include='*.jsx' 2>/dev/null \
-         | sed -E "s/.*[\"'\`]([^\"'\`]+)[\"'\`].*/\1/; s/.*://" \
-         | sort -u || true)
+# Collect translation call sites, keeping the trailing key segment (drop any
+# "ns:" prefix). Use POSIX character classes and explicit boundaries, not \b / \s:
+# BSD/macOS grep -E silently ignores those, which would miss call sites on a Mac
+# (the platform this skill targets) and let an unregistered key slip through —
+# the exact silent-fail this script guards.
+if [ "$FRAMEWORK" = "react" ]; then
+  # React: t("Key") / t('Key') in .tsx/.jsx. (^|[^A-Za-z0-9_]) before t( stops
+  # "insertText(" / "print(" from matching as t(.
+  CALLED=$(grep -rhoE "(^|[^A-Za-z0-9_])t\([[:space:]]*[\"'\`][^\"'\`]+[\"'\`]" "$SRC_DIR" \
+             --include='*.tsx' --include='*.jsx' 2>/dev/null \
+           | sed -E "s/.*[\"'\`]([^\"'\`]+)[\"'\`].*/\1/; s/.*://" \
+           | sort -u || true)
+else
+  # Angular / ngx-translate: keys appear in .html templates (and inline .ts
+  # templates) via the `translate` pipe and the `[translate]` binding, and in .ts
+  # via TranslateService.instant/get/stream(...). Each pass below emits a fragment
+  # scoped to the KEY position (it stops before any trailing params object), then
+  # a shared token extractor pulls the quoted key(s). Scoping keeps a params
+  # object like {'0': x} — or an unrelated Map/HttpClient/FormGroup `.get(...)` —
+  # from being mistaken for a key. The service-call passes require a `translate`-
+  # shaped receiver ([Tt]ranslate...) precisely because a bare `.get(` is far too
+  # common in TS to treat as a translation call.
+  CALLED=$(
+    {
+      # pipe form:            'Key' | translate       (.html + inline templates)
+      grep -rhoE "[\"'\`][^\"'\`]+[\"'\`][[:space:]]*\|[[:space:]]*translate" "$SRC_DIR" \
+        --include='*.html' --include='*.ts' 2>/dev/null || true
+      # property-binding form: [translate]="'Key'"    (literal string only)
+      grep -rhoE "\[translate\][[:space:]]*=[[:space:]]*[\"'][[:space:]]*['\"\`][^'\"\`]+['\"\`]" "$SRC_DIR" \
+        --include='*.html' --include='*.ts' 2>/dev/null || true
+      # service call, single key:  translate.instant/get/stream('Key'
+      grep -rhoE "[Tt]ranslate[A-Za-z0-9_]*[[:space:]]*\.[[:space:]]*(instant|get|stream)[[:space:]]*\([[:space:]]*[\"'\`][^\"'\`]+[\"'\`]" "$SRC_DIR" \
+        --include='*.ts' 2>/dev/null || true
+      # service call, array keys:  translate.get(['A','B'])  (stops at the ])
+      grep -rhoE "[Tt]ranslate[A-Za-z0-9_]*[[:space:]]*\.[[:space:]]*(instant|get|stream)[[:space:]]*\([[:space:]]*\[[^]]*\]" "$SRC_DIR" \
+        --include='*.ts' 2>/dev/null || true
+    } \
+    | grep -oE "['\"\`][^'\"\`]+['\"\`]" \
+    | sed -E "s/['\"\`]//g; s/.*://" \
+    | sort -u || true
+  )
+fi
 
 if [ -z "$CALLED" ]; then
-  echo "no t() call sites to check (scenario may not require the manifest) -> proceed"
+  echo "no ${CALL_LABEL} call sites to check (scenario may not require the manifest) -> proceed"
   exit 0
 fi
 if [ -z "$MANIFEST" ]; then
-  echo "ERROR: t() call sites exist but no label-manifest.ts was found under $SRC_DIR -> register them" >&2
+  echo "ERROR: ${CALL_LABEL} call sites exist but no label-manifest.ts was found under $SRC_DIR -> register them" >&2
   echo "$CALLED" | sed 's/^/  missing: /' >&2
   exit 1
 fi
@@ -91,10 +159,10 @@ REGISTERED=$(awk '
 MISSING=$(comm -23 <(echo "$CALLED") <(echo "$REGISTERED") || true)
 
 if [ -n "$MISSING" ]; then
-  echo "ERROR: t() keys not registered in label-manifest.ts (they render as literal key names at runtime):" >&2
+  echo "ERROR: ${CALL_LABEL} keys not registered in label-manifest.ts (they render as literal key names at runtime):" >&2
   echo "$MISSING" | sed 's/^/  /' >&2
   exit 1
 fi
 
-echo "all $(echo "$CALLED" | wc -l | tr -d ' ') t() key(s) registered in the manifest -> proceed"
+echo "all $(echo "$CALLED" | wc -l | tr -d ' ') ${CALL_LABEL} key(s) registered in the manifest -> proceed"
 exit 0

package/skills/experience-ui-bundle-localize/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-site-generate/SKILL.md

@@ -3,8 +3,8 @@ name: experience-ui-bundle-site-generate
 description: "MUST activate when the project contains a uiBundles/*/src/ directory and the task involves creating or configuring site infrastructure. Use this skill when creating or configuring a Salesforce Digital Experience Site for hosting a UI bundle. Activate when files matching digitalExperiences/, networks/, customSite/, or DigitalExperienceBundle exist and need modification, or when the user wants to publish, host, or configure guest access for their app. Also use this skill to add multi-language, multi-locale, internationalization, or translation support to such a site by declaring a default locale and additional supported languages via the sfdc_cms__languageSettings content type. DO NOT TRIGGER for LWR (non-React) sites; use experience-lwr-site-generate instead."
 metadata:
   version: "1.3"
-  minApiVersion: "65.0"
   domains: ["Experience"]
+  minApiVersion: "65.0"
   relatedSkills:
     - experience-lwr-site-generate
   cliTools:

package/skills/field-service-data-capture-form-deployer-configure/SKILL.md

@@ -12,7 +12,7 @@ metadata:
 This skill takes an intermediate JSON spec and produces a deployed Salesforce Flow with `processType=DataCaptureFlow`. It assumes the spec is already correct and approved — confirmation with the user happens upstream in the design skills.
 
 > **Runtime contract:** every org interaction in this skill is a REST call
-> dispatched through the Codey runtime (`execute_api` locally / the hosted
+> dispatched through the Codey runtime (`dispatch` locally / the hosted
 > Headless 360 MCP in shared surfaces). This skill has **no dependency on the
 > execution environment** — no `sf` CLI, no shell scripts, no local Python, no
 > temp files. Auth probes, record reads, and record writes are single REST

package/skills/field-service-data-capture-form-deployer-configure/references/flow-metadata-json.md

@@ -6,7 +6,7 @@ The shape below is the JSON transliteration of the Metadata blob retrieved from
 
 ## The deploy call
 
-```http
+```text
 POST /services/data/vXX.0/tooling/sobjects/Flow
 {
   "FullName": "<FlowApiName>",

package/skills/field-service-data-capture-form-editor-configure/SKILL.md

@@ -12,7 +12,7 @@ metadata:
 This skill patches a flow that already exists in a connected org. The source of truth is the deployed flow's `Metadata` JSON, retrieved live from the Tooling `Flow` sObject — there is no spec file, no `.flow-meta.xml`, no zip, no SFDX project. The skill retrieves the JSON, edits it in memory, and PATCHes it back.
 
 > **Runtime contract:** every org interaction in this skill is a REST call
-> dispatched through the Codey runtime (`execute_api` locally / the hosted
+> dispatched through the Codey runtime (`dispatch` locally / the hosted
 > Headless 360 MCP in shared surfaces). This skill has **no dependency on the
 > execution environment** — no `sf` CLI, no local Python, no temp files, no
 > scratch SFDX project. Auth probes, the flow retrieve, and the redeploy are

package/skills/field-service-data-capture-reference-configure/SKILL.md

@@ -12,6 +12,14 @@ metadata:
       semver: ">=2.0.0"
 ---
 
+# Querying Fs Data Capture Reference
+
+## When to Use This Skill
+
+Build, edit, and deploy Salesforce Data Capture Flows (processType DataCaptureFlow) — Field Service mobile / offline forms. Use when authoring flow-meta.xml with runtime_service_fieldservice:dc* components, Repeater loops (.AllItems), master-detail child record persistence, visual polish (gradient banners, progress bars, callouts), supporting objects with FLS/permsets, debugging DataCaptureFlow deploy errors, or troubleshooting why a deployed form doesn't appear on the FSL Mobile Forms tab (DDC/WorkPlan OWD + AssignedResource sharing prerequisites).
+
+## Workflow
+
 # Salesforce Data Capture Flow Skill
 
 Build, edit, and deploy Salesforce Flows with `processType: DataCaptureFlow` (Field Service mobile / offline forms).
@@ -38,13 +46,6 @@ Optional `IsLlmTargetable` custom property — if you include it, it must be a J
 
 The `<booleanValue>false</booleanValue>` form deploys but blocks activation — error: `The value of the IsLlmTargetable custom property's value field must be a string in JSON format`. Omitting the property entirely is also fine.
 
-Required input variables:
-```xml
-<variables><name>recordId</name><dataType>String</dataType><isInput>true</isInput><isOutput>false</isOutput><isCollection>false</isCollection></variables>
-<variables><name>parentRecordId</name><dataType>String</dataType><isInput>true</isInput><isOutput>false</isOutput><isCollection>false</isCollection></variables>
-<variables><name>parentObjectType</name><dataType>String</dataType><isInput>true</isInput><isOutput>false</isOutput><isCollection>false</isCollection></variables>
-```
-
 ---
 
 ## XML structure rules
@@ -430,8 +431,6 @@ The same accessors are also used inside `recordCreates` / `recordUpdates` `input
 
 ### Conditionally-hidden required fields — use `validationRule`, not `isRequired`
 
-Never mark a field `isRequired=true` if it's behind a `visibilityRule`. The required check still fires while the field is hidden, so users can't proceed. Instead, set the field `isRequired=false` and wrap the rule:
-
 ```text
 IF(TriggerField.selectedChoiceValues = "Yes",
    AND(NOT(ISBLANK(value)), value >= 0, value <= 100000),
@@ -672,8 +671,6 @@ APEX
 
 ### 4. Tech must sign out and sign back in
 
-FSL Mobile caches the sharing snapshot at login. Pull-to-refresh does not pick up new sharing — only a fresh auth token will. Tell the user to **sign out completely** of the FSL Mobile app, then sign back in. After that, the Forms tab fetch succeeds and DDC records render.
-
 ### What is NOT the cause (don't waste time on these)
 
 - **Layout related-list naming** — `<relatedList>DynamicDataCapture</relatedList>` (singular) is the correct XML form. The UI API uses plural `DynamicDataCaptures` separately. Don't try to align them.
@@ -754,9 +751,25 @@ for f in r.get('details', {}).get('componentFailures', []):
 
 ## Reference examples
 
-Bundled alongside this skill at `examples/` — these are **human / IDE reference files for hand-authoring locally; they are not fetched at agent runtime.** The rules inlined in this skill body above are authoritative at runtime; the example files illustrate those same rules in a complete, deploy-ready flow for a person reading the bundle:
+Bundled alongside this skill at `examples/` (in this skill):
 
 - `Data_Capture_All_Components.flow-meta.xml` — every component in deployment-ready XML
-- `DataCapture_Showcase.flow-meta.xml` — full end-to-end flow: multi-screen form, continue-editing recordLookup, Repeater → Loop → child records via `.AllItems`, Create-or-Update CUD chain driven by a Decision, visual polish (banner, progress, callouts, review cards). The most complete worked example of the XML format; if you have the bundle open, use it to cross-check structure against the rules above.
-- `Repeater_with_prepopulation.flow-meta.xml` — validated worked example of the prepopulated-Repeater pattern: `recordLookups` (ServiceResource) → Repeater bound via `collection` inputParameter with nested field `value` defaults using `SourceCollection[$EachItem].FieldApiName` → post-Repeater Loop over `.AllItems` feeding a display screen that reads `{!LoopName.nestedField.value}` and `{!LoopName.UniqueField__Id}`. Mirrors the prepopulation + post-Repeater display rules documented above.
-- `DataCapture_Repeater_with_data_showcase.flow` (in the org, not committed) — `.AllItems` loop spike; also documents non-working cross-row validation formula syntaxes
+- `DataCapture_Showcase.flow-meta.xml` — full end-to-end flow: multi-screen form, continue-editing recordLookup, Repeater → Loop → child records via `.AllItems`, Create-or-Update CUD chain driven by a Decision, visual polish (banner, progress, callouts, review cards). **This is the canonical "truth" for XML format — when skill rules conflict with this file, the file wins.**
+- `Repeater_with_prepopulation.flow-meta.xml` — canonical prepopulated-Repeater pattern: `recordLookups` (ServiceResource) → Repeater bound via `collection` inputParameter with nested field `value` defaults using `SourceCollection[$EachItem].FieldApiName` → post-Repeater Loop over `.AllItems` feeding a display screen that reads `{!LoopName.nestedField.value}` and `{!LoopName.UniqueField__Id}`. **Validated example — treat as ground truth for prepopulation and post-Repeater display XML.**
+- `DataCapture_Repeater_with_data_showcase.flow` (in the org, not committed) — canonical `.AllItems` loop spike; also documents non-working cross-row validation formula syntaxes
+
+─────
+**Runtime context (Headless 360 / agentic):** When this skill runs in the Headless 360 / agentic context, prefer the platform dispatch tool (``dispatch`` in the hosted Headless 360 MCP; ``dispatch`` in the local-dev MCP) over CLI tools (``sf project deploy``, ``sfdx``, shell commands) when possible. The operations available to you are listed below in ``steps:``; each has been verified against the live org. Call the dispatch tool against the canonical paths. CLI fallback is acceptable only when no API path exists for a given capability.
+
+## Critical Constraints
+
+**Operational rules:**
+
+- Required input variables:
+```xml
+<variables><name>recordId</name><dataType>String</dataType><isInput>true</isInput><isOutput>false</isOutput><isCollection>false</isCollection></variables>
+<variables><name>parentRecordId</name><dataType>String</dataType><isInput>true</isInput><isOutput>false</isOutput><isCollection>false</isCollection></variables>
+<variables><name>parentObjectType</name><dataType>String</dataType><isInput>true</isInput><isOutput>false</isOutput><isCollection>false</isCollection></variables>
+```
+- Never mark a field `isRequired=true` if it's behind a `visibilityRule`. The required check still fires while the field is hidden, so users can't proceed. Instead, set the field `isRequired=false` and wrap the rule:
+- FSL Mobile caches the sharing snapshot at login. Pull-to-refresh does not pick up new sharing — only a fresh auth token will. Tell the user to **sign out completely** of the FSL Mobile app, then sign back in. After that, the Forms tab fetch succeeds and DDC records render.

package/skills/field-service-foundation-setup-designer-get/SKILL.md

@@ -51,7 +51,7 @@ Never expose internal skill names, SOR IDs, or tool references to the user.
    - If not covered + no context: exact structured question
 
 4. **Question format** (three or four parts):
-   ```markdown
+   ```text
    **Recommendation:** [Only include when context is sufficient. Lead with the best-fit option given what's known, then briefly note alternatives with the condition under which they'd apply instead — not a flat menu of equal choices, but a ranked steer. Omit entirely when confidence is low.]
 
    **Question:** [The actual question — or a lighter "does this fit?" when a Recommendation is present]

package/skills/field-service-mobile-branding-configure/SKILL.md

@@ -16,7 +16,7 @@ This skill ingests a brand source and produces a 14-field color scheme that gets
 > Methodology, color tables, and contrast checks are unchanged from upstream — refresh from upstream when content changes there.
 
 > **Runtime contract:** every org interaction in this skill is a single REST
-> call dispatched through the Codey runtime (`execute_api` locally / the hosted
+> call dispatched through the Codey runtime (`dispatch` locally / the hosted
 > Headless 360 MCP in shared surfaces). This skill has **no dependency on the
 > execution environment** — no `sf` CLI, no shell scripts, no local Python, no
 > temp files. Colors are derived and validated by the agent inline, then