@salesforce/afv-skills 1.45.0 → 1.47.0

package/skills/experience-ui-bundle-salesforce-data-access/references/caching.md

@@ -1,5 +1,11 @@
 # Caching & the reactive query result
 
+> **Behavior mirror — `@salesforce/platform-sdk` `docs/data/`, as of v11.70.0.** When the package
+> is installed, its shipped `docs/data/` folder is the authoritative, version-current source
+> ([tier-2b](../SKILL.md#ground-the-sdk-behavior-on-the-installed-docs-tier-2b)) — let it win. This
+> file restates that behavior as a self-contained fallback for when the folder is absent (older SDK,
+> or a types-only build); it reflects the SDK version above and may lag a newer install.
+
 Deep reference for the WebApp resource cache and the two refresh tools. The
 [SKILL.md](../SKILL.md#freshness--caching) Freshness & caching section is the summary; this is
 the full behavior.

package/skills/experience-ui-bundle-salesforce-data-access/references/graphiti-cli.md

@@ -335,8 +335,8 @@ unchanged:
    same shape; codegen is the canonical import source.)
 3. **Call** — `sdk.graphql!.query({ query, variables })` for reads,
    `sdk.graphql!.mutate({ mutation, variables })` for writes, using the codegen'd types and the
-   `variables` the CLI listed. Surface decision (`!` vs guard), error handling, and caching are
-   exactly as the SKILL spine and [sdk-api.md](sdk-api.md) describe.
+   `variables` the CLI listed. Surface decision (`!` vs guard), error handling, and caching ground
+   on the SKILL spine's fallbacks and **tier-2b** `docs/data/` (thin fallbacks in [sdk-api.md](sdk-api.md)).
 
 The CLI never executes anything — it has no part in step 3. It just makes step 1 produce a
 query you can trust.

package/skills/experience-ui-bundle-salesforce-data-access/references/migration.md

@@ -1,5 +1,11 @@
 # Migration — old Data SDK → `@salesforce/platform-sdk`
 
+> **Behavior mirror — `@salesforce/platform-sdk` `docs/data/`, as of v11.70.0.** When the package
+> is installed, its shipped `docs/data/` folder is the authoritative, version-current source
+> ([tier-2b](../SKILL.md#ground-the-sdk-behavior-on-the-installed-docs-tier-2b)) — let it win. This
+> file restates that behavior as a self-contained fallback for when the folder is absent (older SDK,
+> or a types-only build); it reflects the SDK version above and may lag a newer install.
+
 The Data SDK changed in two breaking ways (PR #502, shipped in `@salesforce/platform-sdk`
 v10.10.1):
 

package/skills/experience-ui-bundle-salesforce-data-access/references/rest-and-integration.md

@@ -145,7 +145,8 @@ export async function executeGraphQL<TData, TVariables>(
 ```
 
 (To thread caching or use the reactive handle, call `sdk.graphql!.query()` directly with
-`cacheControl` / `subscribe` — see [caching.md](caching.md).)
+`cacheControl` / `subscribe` — see [SKILL.md → Freshness & caching](../SKILL.md#freshness--caching),
+which grounds on **tier-2b** `docs/data/`.)
 
 > Directory layout and the full command table (`graphql:schema` / `graphql:codegen` / `eslint` /
 > `graphql-search.sh`, plus the graphiti commands) live in the spine — see

package/skills/experience-ui-bundle-salesforce-data-access/references/sdk-api.md

@@ -1,5 +1,11 @@
 # The Data SDK operational guide
 
+> **Behavior mirror — `@salesforce/platform-sdk` `docs/data/`, as of v11.70.0.** When the package
+> is installed, its shipped `docs/data/` folder is the authoritative, version-current source
+> ([tier-2b](../SKILL.md#ground-the-sdk-behavior-on-the-installed-docs-tier-2b)) — let it win. This
+> file restates that behavior as a self-contained fallback for when the folder is absent (older SDK,
+> or a types-only build); it reflects the SDK version above and may lag a newer install.
+
 The installed `@salesforce/platform-sdk` declarations own the current call contract: exports,
 `query`/`mutate` signatures, options bags, result types, `CacheControl`, and
 `NodeOfConnection`. Read `dist/core/data.d.ts` and `dist/data/index.d.ts` first and let them win

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

@@ -1,10 +1,17 @@
 ---
 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."
+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.0"
+  version: "1.3"
+  minApiVersion: "65.0"
   domains: ["Experience"]
+  relatedSkills:
+    - experience-lwr-site-generate
   cliTools:
+    - tool: ["awk"]
+      semver: ">=1.0"
+    - tool: ["jq"]
+      semver: ">=1.6.0"
     - tool: ["sf"]
       semver: ">=2.0.0"
 ---
@@ -25,11 +32,36 @@ Resolve all five properties before generating any metadata. Each has a fallback
 | **appDevName** | String | `UIBundle` metadata in the project → `sf data query -q "SELECT DeveloperName FROM UIBundle" --target-org ${usernameOrAlias}` → default to siteName |
 | **enableGuestAccess** | Boolean | Ask user whether unauthenticated guest users can access site APIs → default `false` |
 
-The `appNamespace` and `appDevName` properties connect the site to the correct React application. Getting these wrong means the site deploys but shows a blank page, so take care to resolve them from real project data.
+The `appNamespace` and `appDevName` properties record the intended UIBundle binding for a **future follow-up update**; they are **not** substituted into `appSpace` at initial site creation. `appSpace` in the `sfdc_cms__site` `content.json` is always `""` at initial creation — see [configure-metadata-digital-experience.md](references/configure-metadata-digital-experience.md) for the reason and the follow-up flow.
+
+### Language Properties
+The skill always emits `sfdc_cms__languageSettings` alongside `sfdc_cms__site`. Resolve `defaultLocale` for every site (defaults to `en_US`); resolve `languages` only when the user requests additional languages beyond the default.
+
+| Property | Format | How to Resolve |
+|----------|--------|----------------|
+| **defaultLocale** | `xx` or `xx_YY` (e.g., `en`, `en_US`) | Ask user → default `en_US` |
+| **languages** | List of `{label, locale}` | Only when the user asks for multiple languages, locales, internationalization, or translation support: ask for the additional languages the site supports. When not requested, the languageSettings content declares only the resolved `defaultLocale` as a single-language entry. |
+
+The content-item folder name (`languages`), `title` (`LanguageContent`), and `urlName` (`languagecontent`) are fixed Experience Builder auto-defaults — they are **not** user-authored. See [configure-metadata-language-settings.md](references/configure-metadata-language-settings.md).
+
+## Pre-flight: Target Org Release (Multi-Language Only)
+The `sfdc_cms__languageSettings` content type accepts multi-language declarations only on Salesforce Release 264 (API **v68.0** or higher). Sites reduced to a single-locale `en_US` declaration work on any org and do not need this check.
+
+When the user requests multiple languages, verify the target org's maximum supported API version **before writing any metadata**. `sf api request rest` hits `/services/data/` on the instance directly and handles authentication at the transport layer, so the org's true ceiling is returned without any access token entering this script's context.
+
+```bash
+MAX_API=$(sf api request rest "/services/data/" --target-org "${usernameOrAlias}" \
+          | jq -r '[.[].version | tonumber] | max')
+
+awk -v v="$MAX_API" 'BEGIN{ exit !(v+0 >= 68.0) }' \
+  || { echo "ERROR: multi-language site containers require Salesforce Release 264 (API v68.0+). Target org's maximum supported API version is v${MAX_API}. Retarget to a Release 264+ org, or reduce the site to a single-locale (en_US) declaration." >&2; exit 1; }
+```
+
+If the check fails, do not write metadata. Report the version mismatch to the user and stop.
 
 ## Generation Workflow
 ### Step 1: Resolve All Required Properties
-Determine values for all five properties before constructing anything. Use the resolution strategies in the table above, falling through each option until a value is found.
+Determine values for all five required properties and the `defaultLocale` language property before constructing anything. Use the resolution strategies in the tables above, falling through each option until a value is found. Resolve the `languages` property only when the user has requested multiple languages — and when they do, run the [Pre-flight](#pre-flight-target-org-release-multi-language-only) check above before continuing to Step 2.
 
 ### Step 2: Create the Project Structure
 Use available Salesforce metadata schema and field context for `Network`, `CustomSite`, `DigitalExperienceConfig`, and `DigitalExperienceBundle` to ensure each file uses valid structure.
@@ -43,8 +75,9 @@ Create any files and directories that don't already exist, using these paths:
 | DigitalExperienceConfig | `digitalExperienceConfigs/{siteName}1.digitalExperienceConfig-meta.xml` |
 | DigitalExperienceBundle | `digitalExperiences/site/{siteName}1/{siteName}1.digitalExperience-meta.xml` |
 | DigitalExperience (sfdc_cms__site) | `digitalExperiences/site/{siteName}1/sfdc_cms__site/{siteName}1/*` |
+| DigitalExperience (sfdc_cms__languageSettings) | `digitalExperiences/site/{siteName}1/sfdc_cms__languageSettings/languages/*` |
 
-The DigitalExperience directory contains only `_meta.json` and `content.json`. Do not create any directories other than `sfdc_cms__site` inside the bundle.
+Each DigitalExperience content-type directory contains only `_meta.json` and `content.json`. Both `sfdc_cms__site` and `sfdc_cms__languageSettings` are always required inside the bundle. The `sfdc_cms__languageSettings` default declares only the resolved `defaultLocale` (e.g. `en_US`); it is extended with additional languages when the user requests multi-language support. No other content types are permitted.
 
 ### Step 3: Populate All Metadata Fields
 Use the default templates in the docs below. Values in `{braces}` are resolved property references — substitute them with the actual values from Step 1.
@@ -56,6 +89,7 @@ Use the default templates in the docs below. Values in `{braces}` are resolved p
 | DigitalExperienceConfig | [configure-metadata-digital-experience-config.md](references/configure-metadata-digital-experience-config.md) |
 | DigitalExperienceBundle | [configure-metadata-digital-experience-bundle.md](references/configure-metadata-digital-experience-bundle.md) |
 | DigitalExperience (sfdc_cms__site) | [configure-metadata-digital-experience.md](references/configure-metadata-digital-experience.md) |
+| DigitalExperience (sfdc_cms__languageSettings) | [configure-metadata-language-settings.md](references/configure-metadata-language-settings.md) |
 
 For URL updates, see [update-site-urls.md](references/update-site-urls.md).
 
@@ -68,6 +102,7 @@ For URL updates, see [update-site-urls.md](references/update-site-urls.md).
   - `references/configure-metadata-digital-experience-config.md`
   - `references/configure-metadata-digital-experience-bundle.md`
   - `references/configure-metadata-digital-experience.md`
+  - `references/configure-metadata-language-settings.md`
 - Read entire file contents, replace placeholders (e.g. `{siteName}`) with the resolved values, then use the expanded templates to populate the metadata XML/JSON content.
   
 ### Step 4: Do Not Modify Non-Templated Properties
@@ -76,11 +111,15 @@ Do not modify any default property values for `Network`, `CustomSite`, `DigitalE
 ## Verification Checklist
 Before deploying, confirm:
 
-- [ ] All five required properties are resolved
+- [ ] All five required properties are resolved, and `defaultLocale` is resolved (defaulting to `en_US` when the user does not specify one)
 - [ ] All metadata directories and files exist per the project structure
 - [ ] All metadata fields match the Step 3 templates with `{braces}` substituted only; no other default property values were added or changed
-- [ ] `appSpace` in `content.json` matches an existing `UIBundle` metadata record
-- [ ] Deployment validates successfully:
+- [ ] `appSpace` in `sfdc_cms__site` `content.json` is the empty string `""` (initial site creation never binds `appSpace`; that is a separate follow-up update after the UIBundle is deployed to the target org)
+- [ ] The `sfdc_cms__languageSettings/languages/` files exist. The language declaration satisfies every platform rule below:
+  - [ ] `defaultLocale` matches the `locale` of one declared language, which is active
+  - [ ] every `locale` is Salesforce-supported, every language is `isActive: true`, each `locale` + `label` combination is unique, and the number of declared languages does not exceed the platform maximum
+  - See [configure-metadata-language-settings.md](references/configure-metadata-language-settings.md) for the full rule catalog. Single-language default declarations satisfy every rule trivially.
+- [ ] Deployment validates successfully (the `DigitalExperience` type already covers `sfdc_cms__languageSettings` — no change to the `--metadata` list is needed):
 ```bash
 sf project deploy validate --metadata Network CustomSite DigitalExperienceConfig DigitalExperienceBundle DigitalExperience --target-org ${usernameOrAlias}
 ```
@@ -94,3 +133,15 @@ sf project deploy validate --metadata Network CustomSite DigitalExperienceConfig
 **Steps**:
 - [ ] Read [update-site-urls.md](references/update-site-urls.md) to understand the three-component architecture and URL update workflow
 - [ ] Follow the step-by-step workflow in the doc to update URLs consistently across all three components (DigitalExperienceConfig, Network, CustomSite)
+
+### Configuring Multi-Language Support
+
+**Use when** user wants the site to support multiple languages, locales, internationalization, or translation — beyond the default-locale-only declaration that every site already receives.
+
+**Steps**:
+- [ ] Collect the additional languages the site should support and which locale is the default (resolve the `defaultLocale` and `languages` properties above)
+- [ ] Run the [Pre-flight: Target Org Release](#pre-flight-target-org-release-multi-language-only) check — abort if the org is below Release 264 (API v68+)
+- [ ] Read [configure-metadata-language-settings.md](references/configure-metadata-language-settings.md) for the templates, field reference, and platform validation rules
+- [ ] Extend the `sfdc_cms__languageSettings/languages/content.json` (which already exists with the default locale) to include the additional language entries, then re-run deploy validation
+
+**Note:** This is authoring-only — declared locales deploy cleanly, but locale-in-path routing does not resolve at request time yet. Do not translate the UI bundle content itself; this only declares the site's supported languages.

package/skills/experience-ui-bundle-site-generate/references/configure-metadata-digital-experience.md

@@ -3,10 +3,15 @@
 ## Purpose
 These configuration files create **net-new, default** DigitalExperience content records (`sfdc_cms__site` type) for a Digital Experience React Site. They are not intended to edit or modify existing DigitalExperience content. Use these templates only when provisioning a brand-new React site.
 
-The `appContainer: true` field in `content.json` is what makes this a React site rather than a standard LWR site. The `appSpace` field should **be left empty if the UIBundle metadata record does not already exist**. When the UIBundle exists, populate the `appSpace` value following the format `{namespace}__{developerName}` to match the deployed `UIBundle` metadata record.
+The `appContainer: true` field in `content.json` is what makes this a React site rather than a standard LWR site.
+
+### `appSpace`: always empty at initial site creation
+The `appSpace` field **MUST be an empty string (`""`) at initial site creation**. This is the correct default even when the prompt supplies `appNamespace` and `appDevName`, and even when a `uiBundles/<Name>/src/` directory exists in the local project. Reason: the UIBundle metadata record must already be **deployed and active in the target org** before `appSpace` can reference it — attempting to bind `appSpace` to a not-yet-deployed UIBundle causes deploy validation to fail with `We couldn't find the <namespace>__<name> UIBundle`.
+
+Populate `appSpace` with `"{appNamespace}__{appDevName}"` **only** in a later, follow-up update once you have confirmed (via `sf data query -q "SELECT DeveloperName FROM UIBundle WHERE DeveloperName = '{appDevName}'"`) that the UIBundle metadata record exists in the target org. This is a rare secondary operation, not part of initial scaffolding.
 
 ## File Location
-The DigitalExperience directory contains only `_meta.json` and `content.json`. Do not create any directories other than `sfdc_cms__site` inside the bundle.
+Each DigitalExperience content-type directory contains only `_meta.json` and `content.json`. Two content types are always emitted inside the bundle: `sfdc_cms__site` (required) and `sfdc_cms__languageSettings` (defaults to a single `en_US` declaration; extended when the user requests additional languages — see [configure-metadata-language-settings.md](references/configure-metadata-language-settings.md)). No other content types are permitted.
 
 ```text
 digitalExperiences/site/{siteName}1/sfdc_cms__site/{siteName}1/_meta.json
@@ -37,4 +42,4 @@ digitalExperiences/site/{siteName}1/sfdc_cms__site/{siteName}1/content.json
 }
 ```
 
-**Note:** Leave `appSpace` empty (`""`) if the UIBundle does not exist. If the UIBundle metadata record is already deployed, populate it with `"{appNamespace}__{appDevName}"`.
+**Note:** `appSpace` is always `""` at initial site creation. Do not substitute `{appNamespace}__{appDevName}` here even if those properties are resolved — that binding happens in a follow-up update after the UIBundle is deployed to the org (see the `appSpace` guidance in the Purpose section above).

package/skills/experience-ui-bundle-site-generate/references/configure-metadata-language-settings.md

@@ -0,0 +1,120 @@
+# Configure Metadata: DigitalExperience (sfdc_cms__languageSettings)
+
+## Purpose
+These configuration files create the `sfdc_cms__languageSettings` content record for a Digital Experience React Site. The record declares the set of languages the site supports and which one is the default locale. It is **always emitted** alongside `sfdc_cms__site` — a fresh site defaults to a single-language declaration (the resolved `defaultLocale`, typically `en_US`), and the same file is extended when the user requests additional languages. This is **authoring-only**: declared locales deploy cleanly, but locale-in-path routing does not resolve at request time until the platform runtime change lands.
+
+## When to Use
+Always. The skill emits `sfdc_cms__languageSettings` for every generated site, in addition to the required `sfdc_cms__site` content type. When the user does not request multiple languages, populate the file with a single-language default declaration using the resolved `defaultLocale` (default `en_US`). When the user requests additional languages/locales, extend the same file with the requested language entries. `sfdc_cms__site` and `sfdc_cms__languageSettings` are the only two content types this skill authors; no others are permitted.
+
+## File Location
+The languageSettings content lives in its own content-type directory inside the bundle, alongside `sfdc_cms__site`. The folder name (`languages`), `title` (`LanguageContent`), and `urlName` (`languagecontent`) are fixed Experience Builder auto-defaults — they are **not** derived from the site name and are **not** user-authored.
+
+```text
+digitalExperiences/site/{siteName}1/sfdc_cms__languageSettings/languages/_meta.json
+digitalExperiences/site/{siteName}1/sfdc_cms__languageSettings/languages/content.json
+```
+
+## Generation Workflow
+1. **Collect input.** Resolve the `defaultLocale` (ask the user, or default to `en_US`). If the user requests additional languages, collect for each: a display `label` and a `locale`. If the user does not request additional languages, no further input is needed — the file will contain a single-language declaration for the default locale only.
+2. **Build the `languages` array.**
+   - **Single-language default (no additional languages requested).** Emit exactly one entry using the resolved `defaultLocale`. Set `isActive: true`. Provide a human-readable `label` matching the locale (e.g. `English (United States)` for `en_US`).
+   - **Multi-language (additional languages requested).** Emit one object per declared language, always including the default-locale entry as the first element. Set `isActive: true` for every language.
+3. **Substitute and write both files.** Fill `{defaultLocale}` and each language object's fields into the templates, then write `_meta.json` and `content.json` into the folder above.
+4. **Assert structural rules with `jq`.** Run the assertion below against the written `content.json`. If it exits non-zero, fix the declaration and rewrite the file. Rules 3–4 in the reference below cannot be checked offline — the deploy validation step covers them.
+
+   ```bash
+   jq -e '
+     (.contentBody as $b | $b.languages | any(.locale == $b.defaultLocale))
+       and (.contentBody as $b
+             | $b.languages[]
+             | select(.locale == $b.defaultLocale)
+             | .isActive == true)
+       and ((.contentBody.languages | map(.locale + "|" + .label) | unique | length)
+             == (.contentBody.languages | length))
+   ' content.json > /dev/null
+   ```
+
+   Enforces rules 1 (defaultLocale is declared), 2 (default-entry active), and 5 (locale+label uniqueness) below.
+
+## Default Templates
+Substitute values in `{braces}`. `apiName`, `type`, `path`, `title`, and `urlName` are fixed — do not parameterize them. The only variables are `{defaultLocale}` and the `languages[]` element fields (`{label}`, `{locale}`).
+
+### `_meta.json`
+```json
+{
+  "apiName": "languages",
+  "type": "sfdc_cms__languageSettings",
+  "path": "_settings"
+}
+```
+
+### `content.json` — single-language default
+Use this shape when the user has not requested additional languages. The single entry uses the resolved `defaultLocale`.
+
+```json
+{
+  "type": "sfdc_cms__languageSettings",
+  "title": "LanguageContent",
+  "contentBody": {
+    "defaultLocale": "{defaultLocale}",
+    "languages": [
+      {
+        "isActive": true,
+        "label": "{label}",
+        "locale": "{defaultLocale}"
+      }
+    ]
+  },
+  "urlName": "languagecontent"
+}
+```
+
+### `content.json` — multi-language
+Use this shape when the user has requested additional languages. The example shows two languages — the default (`en_US`) and one additional locale. Emit one object per declared language; keys within each language object are alphabetically ordered.
+
+```json
+{
+  "type": "sfdc_cms__languageSettings",
+  "title": "LanguageContent",
+  "contentBody": {
+    "defaultLocale": "{defaultLocale}",
+    "languages": [
+      {
+        "isActive": true,
+        "label": "{label}",
+        "locale": "{defaultLocale}"
+      },
+      {
+        "isActive": true,
+        "label": "{label}",
+        "locale": "{locale}"
+      }
+    ]
+  },
+  "urlName": "languagecontent"
+}
+```
+
+## Field Reference
+- `defaultLocale` — the site's default locale; must match the `locale` of one of the declared `languages[]`.
+- `locale` — a Salesforce-supported locale, either `xx` (e.g. `am`, `de`, `fr`) or `xx_YY` (e.g. `en_US`, `es_MX`, `zh_CN`). Support is org-dependent; deploy validation rejects unsupported values.
+- `label` — human-readable display name for the language.
+- `isActive` — only `true` is supported in authoring; every declared language must be active.
+
+## Platform Validation Rules
+Deploy rejects a languageSettings declaration that breaks any of these. Rules 1, 2, and 5 are enforced by the jq assertion in Step 4; rules 3–4 are enforced by deploy validation only:
+
+1. The `defaultLocale` must appear as the `locale` of a declared language.
+2. The default-locale language must be active (`isActive: true`).
+3. Every `locale` must be a Salesforce-supported locale (org-dependent; deploy validation enforces).
+4. The number of declared languages must not exceed the platform maximum.
+5. The `locale` + `label` combination must be unique per workspace.
+
+## Deploy Validation
+After writing the files, validate the whole site bundle (languageSettings deploys within the existing `DigitalExperience` metadata type — no new type is needed):
+
+```bash
+sf project deploy validate --metadata Network CustomSite DigitalExperienceConfig DigitalExperienceBundle DigitalExperience --target-org ${usernameOrAlias}
+```
+
+A clean validate confirms the declaration satisfies every rule above — for the single-language default case as well as for multi-language declarations.