@salesforce/afv-skills 1.49.0 → 1.51.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

@@ -0,0 +1,180 @@
+---
+name: field-service-data-capture-form-deployer-configure
+description: "Assemble a Data Capture Flow from a JSON spec and deploy it to a connected Field Service org via the Tooling Flow sObject (JSON Metadata, no XML). Use when given a data-capture spec JSON and asked to build or deploy a DataCaptureFlow."
+user-invocable: false
+metadata:
+  version: "1.0"
+  domains: ["Field Service"]
+---
+
+# Build a Data Capture Form (Field Service Mobile)
+
+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
+> 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
+> calls; the Flow XML is authored by the agent inline from the reference docs.
+> Do not shell out.
+
+## Input contract
+
+A JSON file matching the schema in [reference/field-types.md](reference/field-types.md) and (optionally) [reference/post-screen-automation.md](reference/post-screen-automation.md). Canonical examples:
+
+- [examples/sample-spec.json](examples/sample-spec.json) — minimal screens-only flow.
+- [examples/inventory-transfer-spec.json](examples/inventory-transfer-spec.json) — full example with Repeater, Radio, visibility, decision, lookups, loop, and record-create.
+
+Required top-level keys: `formTitle`, `formType`, `screens`. Optional: `postScreen`.
+
+## Output
+
+A Data Capture Flow created in the org via a single Tooling API call — `POST /services/data/vXX.0/tooling/sobjects/Flow` with a JSON `Metadata` body (no `.flow-meta.xml`, no zip, no SFDX project). The flow is created in `Draft` status and the user activates it themselves in Flow Builder.
+
+## Workflow
+
+### 1. Verify org auth
+
+Confirm the connected org is reachable with a cheap auth probe — dispatch `SELECT Id FROM Organization LIMIT 1` (`GET /services/data/vXX.0/query`):
+
+- 2xx with `totalSize=1` → the session token is live; continue.
+- 401/403 → the org needs re-authentication. Surface that to the user and **stop**; do not deploy. (The Codey runtime resolves and refreshes the connected org — this skill does not manage org aliases.)
+
+### 2. Pick a Flow API name
+
+If the design skill already supplied `<FlowApiName>`, use it. Otherwise derive from `formTitle`: PascalCase, no spaces, must match `^[A-Z][A-Za-z0-9_]*$`. If the title can't be coerced, ask the user.
+
+### 3. Build the Flow Metadata JSON
+
+Assemble the flow's `Metadata` object **inline** from the spec — the Tooling `Flow` sObject takes a JSON `Metadata` blob, so there is no XML to compile and no converter to run. Follow the JSON shape and field mappings in [reference/flow-metadata-json.md](reference/flow-metadata-json.md) and [reference/field-types.md](reference/field-types.md).
+
+Notes:
+- The JSON `Metadata` is the exact same shape the Tooling `Flow` GET returns (`GET /tooling/sobjects/Flow/{id}` → `Metadata`), so you can retrieve a known-good sibling flow as a live reference before composing.
+- **Dedupe choices** across the entire flow — two fields with `["Good","Fair","Poor"]` share the same three entries in the top-level `choices` array.
+- Repeater children are nested as `fields` entries inside the parent Repeater field.
+- `Signature`, `UploadFile`, `UploadImage`, and `Images` auto-wire `parentRecordId` / `recordId` to the standard DataCaptureFlow input variables. They deploy as functional components, no Flow Builder cleanup required.
+- `Lookup` requires a `lookupObject` spec key; without it, emit the labeled `dcTextInput` placeholder. `FileView` requires a `fileName`; same fallback. Collect any such fallbacks and surface them in step 5.
+- Self-check before deploying: `processType` is `DataCaptureFlow`, `environments` includes `Offline`, and the three input variables (`parentObjectType`, `parentRecordId`, `recordId`) are present.
+
+### 4. Deploy to org
+
+Create the flow with a single Tooling API call — dispatch `POST /services/data/vXX.0/tooling/sobjects/Flow` with body:
+
+```json
+{
+  "FullName": "<FlowApiName>",
+  "Metadata": { "processType": "DataCaptureFlow", "environments": ["Offline"], "label": "...", "screens": [ ... ], "choices": [ ... ], "variables": [ ... ], "status": "Draft" }
+}
+```
+
+- `FullName` is the Flow API name; `Metadata` is the object you assembled in step 3.
+- A 201 with `success: true` returns the new Flow version id. `Status` stays `Draft` (set `Metadata.status: "Active"` only if the user asked to activate on create — the default is Draft so the user reviews in Flow Builder first).
+- On a 400, the response body's `message` carries the Flow validation error — diagnose against step 5's failure table.
+
+### 5. Report back
+
+On success:
+- Look up the FlowDefinition Id with a Tooling API query — dispatch `GET /services/data/vXX.0/tooling/query` with `SELECT Id, ActiveVersionId FROM FlowDefinition WHERE DeveloperName = '<FlowApiName>'`.
+- Print a clickable Flow Builder URL: `<instanceUrl>/builder_platform_interaction/flowBuilder.app?flowId=<id>`.
+- List screens, total field count, and any fallback fields (Lookup with no `lookupObject`, FileView with no `fileName`) the user needs to wire up in Flow Builder.
+- Print the direct flow-launch URL: `<instanceUrl>/flow/<FlowApiName>` — the fastest validation path that bypasses QuickActions, layouts, and the Forms tab.
+
+On failure (the `POST` returned a 400 — read the error from the response body's `message`):
+- If `Cannot find component 'runtime_service_fieldservice:dcXxx'` → org doesn't have Field Service enabled (or the component name is wrong). Surface the exact error and stop.
+- For Flow validation errors, the cause is usually a pattern listed in the prohibited-patterns table at [fs-data-capture-reference/SKILL.md](../fs-data-capture-reference/SKILL.md). Read that file before retrying. Common diagnoses: schema-grouping violations, `.AllItems` vs `.AddedItems` accessor mismatch, CUD ordering, missing `nextOrFinishButtonLabel`, `IsLlmTargetable` boolean-vs-string.
+- Don't loop more than twice without showing the user.
+- Common gotcha: if you emit an implicit `Sec_General` section for any screen whose first field appears before an explicit `{ "section": "..." }` header, two such screens collide with `Duplicate developer name: Sec_General`. Give each such screen an explicit leading section in the JSON, then re-assemble and re-POST.
+
+### 6. Make the form visible (optional but usually wanted)
+
+Deploying the flow does NOT make it appear in the "Forms" related list on a Service Appointment, Work Order, or other parent. To make a deployed flow show up as a pending form a tech can pick up:
+
+1. **Attach a `DynamicDataCapture` record to the parent.** This is the SDO's canonical "pending form" pattern — see how shipped SDO forms (Job Safety, Vehicle Inspection, Job Completion) are wired. Create the record with a single sObject insert — dispatch `POST /services/data/vXX.0/sobjects/DynamicDataCapture` with this body:
+
+   ```json
+   {
+     "Name": "<Display Name>",
+     "ParentRecordId": "<ParentRecordId>",
+     "ActionDefinition": "<FlowApiName>",
+     "ActionType": "Flow",
+     "ProcessType": "DataCaptureFlow",
+     "StatusCategory": "New",
+     "IsRequired": true,
+     "ExecutionOrder": 1
+   }
+   ```
+
+   `Name` defaults to `<FlowApiName>` with underscores → spaces if the caller gives no display name; `IsRequired` is a real boolean (`true`/`false`), not a string. A 201 with `success: true` returns the new DDC id. `ParentRecordId` is polymorphic — accepted parent types are `ServiceAppointment`, `ServiceResource`, `TimeSheet`, `Visit`, `WorkOrder`, `WorkOrderLineItem`.
+
+2. **For FSL Mobile / Service Appointment context, attach to the parent Work Order, not the SA itself.** FSL Mobile's Forms tab on a Service Appointment typically aggregates `DynamicDataCapture` records from the SA's parent Work Order (via `ServiceAppointment.ParentRecordId`). Attaching directly to the SA may not surface in mobile.
+
+   Resolve the SA's parent Work Order Id first — dispatch `GET /services/data/vXX.0/query` with `SELECT ParentRecordId FROM ServiceAppointment WHERE Id = '<SA_Id>'`, then attach (sub-step 1) to that Work Order Id.
+
+3. **Verify the parent's page layout has the Forms (DynamicDataCapture) related list.** Different SDOs use different layouts per profile. Query with the Tooling API — dispatch `GET /services/data/vXX.0/tooling/query` with `SELECT Layout.Name, Profile.Name FROM ProfileLayout WHERE TableEnumOrId = 'WorkOrder'`.
+
+   `Layout` is itself a Tooling sObject with a JSON `Metadata` field, so the splice is a REST read-modify-write — no XML file, no deploy. Read the layout with `GET /services/data/vXX.0/tooling/sobjects/Layout/{layoutId}` (resolve `{layoutId}` from the `ProfileLayout.LayoutId` in the query above), check `Metadata.relatedLists` for a `DynamicDataCapture` entry, and if absent append this entry and `PATCH /services/data/vXX.0/tooling/sobjects/Layout/{layoutId}` with the updated `Metadata`:
+
+   ```json
+   {
+     "relatedList": "DynamicDataCapture",
+     "fields": ["Name", "StatusCategory", "IsRequired"]
+   }
+   ```
+
+4. **Caveats:**
+   - Attached form must have `StatusCategory='New'` to appear as pending. `Completed` records show as historical.
+   - `ActionDefinition` must exactly match the deployed flow's API name (case-sensitive).
+   - `ProcessType='DataCaptureFlow'` is required — the SDO sometimes also uses `DiscoveryFrameworkFlow`.
+   - If the parent profile's layout lacks the Forms list, attaching the DDC succeeds at the data layer but the form is invisible in the UI.
+
+5. **Each profile has its own page layout.** Real SDOs commonly route different profiles to different Work Order layouts (e.g. `System Administrator` → `SDO SFS Work Order Layout`, `Standard User` → `Work Order Layout`, `SDO-Service` → `FSL Work Order Layout`). Patching one layout doesn't help users on the others. Run the ProfileLayout query above for every profile that needs to see the form, then patch the union of layouts.
+
+6. **DDC + WorkPlan OWD must be Public Read/Write for FSL Mobile.** The Forms tab on FSL Mobile uses the UI API (`/ui-api/related-list-records/<woId>/DynamicDataCaptures`), which enforces sharing. If `DynamicDataCapture` or `WorkPlan` OWD is **Private** (the platform default), the technician got the WO via AssignedResource sharing and has zero row access to the DDCs themselves — UI API returns `INSUFFICIENT_ACCESS` and the Forms tab silently shows "No forms available. We couldn't find any forms to display." with a "Try Again" button. Desktop SOQL as admin doesn't catch this because admins bypass sharing.
+
+   **Fix:**
+   - Set the org-wide default for `DynamicDataCapture` and `WorkPlan` to **Public Read/Write**. Org-wide sharing defaults are a Setup-only surface — surface the deeplink `<instanceUrl>/lightning/setup/SecuritySharing/home` and have the admin set both objects' Default Internal Access to Public Read/Write. (This is a click-through, not a shell step.)
+   - Set `doesShareSaParentWoWithAr` and `doesShareSaWithAr` to `true` on `FieldServiceSettings` via a Tooling PATCH — `GET /services/data/vXX.0/tooling/query` `SELECT Id, Metadata FROM FieldServiceSettings` to read the singleton, then `PATCH /services/data/vXX.0/tooling/sobjects/FieldServiceSettings/{id}` with `{"Metadata": {"doesShareSaParentWoWithAr": true, "doesShareSaWithAr": true}}` (merge — include the existing Metadata keys).
+   - Re-save existing `AssignedResource` records to trigger sharing recalc — a no-op `PATCH /services/data/vXX.0/sobjects/AssignedResource/{id}` per record re-fires the sharing rules.
+   - User must **sign out + back in to FSL Mobile** — the sharing snapshot is cached at login.
+
+   Verify with a Tooling API query — dispatch `GET /services/data/vXX.0/tooling/query` with `SELECT QualifiedApiName, InternalSharingModel FROM EntityDefinition WHERE QualifiedApiName IN ('DynamicDataCapture','WorkPlan')`. Both should return `ReadWrite`. If either returns `Private`, the Forms tab will fail for the tech even though the DDC row exists.
+
+7. **After attaching, mobile may need a refresh.** Even with OWD correct, the FSL Mobile Forms tab caches the related list. To pick up a newly-attached DDC: **pull-to-refresh on the Forms tab** on the Work Order. Force-quit + reopen the app if pull-to-refresh doesn't surface it. Sign out + back in is only needed when sharing changes (#6).
+
+8. **UI API version note (testing only).** UI API v60 returns `INSUFFICIENT_ACCESS` even after sharing is correct; v62+ works. The iOS FSL Mobile app hardcodes v67, so this isn't a production issue — but it matters when reproducing the call via curl.
+
+## Scope
+
+**Generated automatically:**
+- Field labels, types, and required state from the spec.
+- Native types: `ShortText`, `LongText`, `Name`, `Email`, `Phone`, `Numeric`, `Counter` (with `min`/`max`/`value`), `Date`, `DateTime`, `Checkbox`, `Toggle`, `Picklist`, `Radio` (`dcRbGroup`), `CheckboxGroup`, `DisplayText`, `Repeater`.
+- Specialized Field Service components: `Signature` (auto-wires `parentRecordId` + `recordId`), `UploadFile`, `UploadImage`, `Images` (auto-wire `recordId` → `parentRecordId`), `Address` (compound), `Matrix` (column choices + `questions` row labels), `Lookup` (with `lookupObject`/`lookupSearchFields`/`lookupMulti` spec keys), `FileView` (with `fileName` spec key).
+- Conditional visibility on individual fields.
+- Optional `postScreen` automation: a decision, multiple `recordLookups`, one `loop`, multiple `recordCreates`, and extra non-input variables.
+
+**Falls back to deploy-safe placeholders** (admin replaces in Flow Builder):
+- `Lookup` *with no `lookupObject`* → `dcTextInput` with `[Lookup — set objectApiName in Flow Builder]` prefix.
+- `FileView` *with no `fileName`* → `dcTextInput` with `[FileView — set fileName in Flow Builder]` prefix.
+
+See [reference/field-types.md](reference/field-types.md) for the full mapping.
+
+**Out of scope:**
+- Multiple decisions / multiple loops / nested loops in `postScreen`.
+- Subflows, formulas, text templates, assignments.
+- Visual polish HTML (banners, progress bars, callouts) — those are hand-authored. See `fs-data-capture-reference` skill for patterns.
+
+## Files in this skill
+
+This skill has **no executable scripts**. Auth checks, record reads, the `DynamicDataCapture` attach, and the flow create/deploy are all single REST calls dispatched through the Codey runtime (steps 1, 4, 5, 6). The Flow Metadata JSON is assembled by the agent inline (step 3) from the reference docs below.
+
+- `reference/flow-metadata-json.md` — the Tooling `Flow.Metadata` JSON shape (screens, choices, decisions, variables, post-screen chain) and the deploy/activate calls. Read this when composing the flow.
+- `reference/field-types.md` — input contract: spec `fieldType` → runtime component + JSON attributes.
+- `reference/post-screen-automation.md` — input contract for the optional `postScreen` block.
+- `examples/sample-spec.json`, `examples/inventory-transfer-spec.json` — canonical specs.
+
+## Related skills
+
+- **`fs-data-capture-reference`** (sibling library skill) — reference manual for hand-authoring patterns, prohibited patterns + exact deploy errors, visual polish HTML, supporting CustomObject/PermissionSet/CustomTab deploy. Read this when diagnosing a deploy error or extending the JSON field mappings.
+- **`fs-data-capture-form-designer`** — produces the spec this skill consumes (from prose or an image/PDF).
+- **`fs-data-capture-form-editor`** — patches an already-deployed flow in the org. Uses the same Tooling `Flow` JSON round-trip (GET Metadata → edit → PATCH) this skill uses to create.