@salesforce/afv-skills 1.45.0 → 1.47.0

package/skills/experience-search-coordinate/references/content-type-discovery.md

@@ -0,0 +1,57 @@
+# Content Type Discovery — Fallback Chains
+
+Reached from `SKILL.md` Step 2 point 2 whenever `search_metadata` doesn't produce a usable candidate list.
+
+## Workspace content-type fallback
+
+Only reached when `search_metadata` never produced a usable candidate list — the server was unavailable, or it returned zero candidates even after one retry with a clarified query.
+
+- Call `get_content_types_for_workspace` passing `baseType: "content"` **instead of** `spaceId` — omitting `spaceId` and passing `baseType` returns every applicable content type across the org rather than one workspace's subset. Also pass `typeClassFullyQualifiedNames: ["sfdc_cms__structured"]` and `mixinFullyQualifiedNames: ["sfdc_cms:deliverySearch"]` — this pre-filters the response to the same "supported for search" set the primary path gates on in Step 2 point 4, so the fallback doesn't have to hand back unsupported types for you to filter after the fact:
+
+  ```javascript
+  get_content_types_for_workspace({
+    inputs: [{
+      baseType: "content",
+      typeClassFullyQualifiedNames: ["sfdc_cms__structured"],
+      mixinFullyQualifiedNames: ["sfdc_cms:deliverySearch"]
+    }]
+  })
+  ```
+
+- Each returned entry has `developerName`, `namespace`, and `description` — the type-class/mixin filtering above is applied server-side to the candidate set, but individual entries still don't carry `typeClasses`/`mixins` fields themselves, so **media-vs-content routing** is still judgment-based (reading the description), not a field check like `query_metadata`'s.
+- **Read each candidate's `developerName`/`description` against the search intent** and pick at most the 5 most relevant. For each: if it's clearly an image, audio, video, or document type (by name/description) → media candidate, go to Step 4 (Media Route); otherwise → content candidate, go to Step 3 (Content Route). Construct the FQN as `<namespace>__<developerName>` (e.g. `c__BookReview`, `sfdc_cms__image`) — the same convention `experience-cms-content-generate` uses for FQN construction.
+- **Can't confidently classify, or can't narrow to relevant candidates** — ask the user one clarifying question (`ask_followup_question`) listing the candidates (label + description) as options, and route on their reply. This is a separate, one-shot ask from Step 2 point 2's clarifying question (that one narrows the search query before this fallback ever runs; this one disambiguates among this fallback's own candidates) — don't skip it just because point 2 already asked once.
+- **Zero candidates returned here too** — apply the wording fallback below; there's nothing left to ground the route in.
+
+## Wording fallback
+
+Last resort — only reached when both `search_metadata` and the workspace content-type fallback failed to produce a usable candidate list.
+
+- **Media wording** (e.g. image, photo, logo, icon, banner, graphic, picture, audio, clip, sound, recording, video, document, PDF, file, asset, media) — go to Step 4 (Media Route) with an empty `contentTypeFqn` (`""`).
+- **Content wording** (e.g. article, blog, post, news, FAQ, event, product, page, press release) — go to Step 3 (Content Route) with an empty `contentTypeFqn` (`""`).
+- **Still unclear either way** — fall back to the Content Route with an empty `contentTypeFqn` (`""`), since structured content is the more common case.
+- In every one of these cases, search silently across all types for that route — do not block or ask the user again just because `search_metadata` and the workspace content-type fallback both came up empty.
+
+## Filter-result messages (Step 2 point 4)
+
+**Zero candidates survive the supported-type filters:**
+
+```text
+I found these content types for "<intent>", but none of them are supported for search: <label1> (<fqn1>), <label2> (<fqn2>).
+```
+
+**Some, but not all, candidates survive** (plain-text statement, not a question — don't wait for a reply):
+
+```text
+<label1> (<fqn1>) isn't supported for search, so I'll continue with: <label2> (<fqn2>).
+```
+
+## "Intent itself is ambiguous" question
+
+Reached from `SKILL.md` Step 2 when the request gives no hint of type or subject (e.g. "find me some content") — asked before ever calling `search_metadata`.
+
+`ask_followup_question` with the question `"What are you looking for?"` and one **option** per choice in the tool's `options` array — never as numbered lines inside the question text:
+
+`Articles / Blog posts`, `News`, `FAQs`, `Events`, `Products`, `Images / logos / photos`, `Audio clips`, `Videos`, `Documents`, `Other (describe what you need)`.
+
+Wait for the reply before proceeding. Do not guess.

package/skills/experience-search-coordinate/references/media-route.md

@@ -0,0 +1,172 @@
+# Media Route — Full Reference
+
+Worked payload examples for the media route (Step 4 of SKILL.md).
+
+**Media is not limited to images.** Step 2's `search_metadata` + `query_metadata` calls discover the actual FQN for the intent — it may be `sfdc_cms__image`, `sfdc_cms__audio`, `sfdc_cms__video`, `sfdc_cms__document`, or another `sfdc_cms__media`-typed FQN. Use whatever FQN was discovered; never default to `sfdc_cms__image`.
+
+## Presenting available search sources
+
+Reached at Step 4 point 1. Check your own tool list (introspection, not a tool call) for `search_media_cms_channels` and `search_electronic_media`. Include only the sources whose tools you actually have, plus "Other" as the last option, each as its own **option** in `ask_followup_question`'s `options` array — never as numbered lines inside the question text:
+
+```text
+Question: "Where would you like to search for that?"
+Options:
+  - Search using keywords — Search Salesforce CMS by keywords and taxonomies
+  - Search using Data 360 hybrid search — Semantic search across Salesforce CMS and connected DAMs
+  - Other — Provide your own URL or path
+```
+
+Wait for the user's selection. Do not call any tool before this point. **Other** — ask for a direct URL, asset library path, or specific system to check (no confirmation step needed, since no tool is called).
+
+## Executing the search call(s)
+
+Per the scope from Step 1. `contentAccessScope` and `channelIds` are **mutually exclusive fields — never include both in the same call**: no `channelId` in scope → one call with `contentAccessScope: "Public"` and no `channelIds`; a `channelId` in scope → two calls — one with `contentAccessScope: "Public"` and no `channelIds`, one with `channelIds` set to `"<channelId>"` and no `contentAccessScope`. Each result item already carries its own list of channel deliveries in `managedContentChannelDeliveryDetails` — same shape, and same "can hold many entries for one item" reality, as the Content Route (see `content-route.md` "Executing the search call(s)" for a real six-entry API response). Each entry's `managedContentChannelDetails.type` is `PUBLIC_UNAUTHENTICATED`, `COMMUNITY`, or `WEB_APP` (the channel-scoped call's uiBundle channel). **If the same item (by its unique identifier) appears in both responses, merge their `managedContentChannelDeliveryDetails` arrays** rather than picking one response and discarding the other — de-duplicate only exact repeats of the same channel id. Presentation still shows the item once; the channel choice is made after selection — see "Disambiguating channel at selection" below. (Data 360 hybrid search ignores channel scope entirely — no `channelIds`/`contentAccessScope` field, no channel to label.)
+
+**The Unauthenticated URL is public-channel-only** — see "Handing off the selected media item" below: only a `PUBLIC_UNAUTHENTICATED` or `COMMUNITY` entry's `contentUrl` is ever surfaced; a `WEB_APP` entry's `contentUrl` never is, even though the field is present in the response.
+
+## Search using keywords (`search_media_cms_channels`)
+
+Keyword/taxonomy extraction rule: see `SKILL.md` Step 4 point 2. Extract taxonomy whenever the query contains a genuine descriptive/style/mood/category term — do not default to an empty taxonomy just because keywords were already found. Additional worked examples for media:
+- "modern minimalist company logo" → keywords: logo, emblem, corporate logo; taxonomies: Modern, Minimalist, Clean
+- "customer testimonial clips" → keywords: testimonial, customer, feedback, review; taxonomies: _(empty — no descriptive terms)_
+- "bright spacious room" → keywords: _(empty — no concrete nouns)_; taxonomies: Bright, Spacious, Open, Airy, Light
+
+**Process:**
+
+1. **Analyze the query** — understand what the user is searching for (subject, attributes, domain)
+2. **Determine locale** — format `en_US`, `es_MX`, `fr_FR` (default: `en_US`)
+3. **Build the JSON payload:**
+
+```json
+{
+  "inputs": [{
+    "searchKeyword": "keyword1 OR keyword2 OR keyword3",
+    "taxonomyExpression": "{\"OR\": [\"Taxonomy1\", \"Taxonomy2\"]}",
+    "searchLanguage": "en_US",
+    "contentAccessScope": "Public",
+    "contentTypeFqn": "<fqn discovered in Step 2, e.g. sfdc_cms__image, sfdc_cms__audio, sfdc_cms__video, sfdc_cms__document>",
+    "pageOffset": 0,
+    "searchLimit": 5
+  }]
+}
+```
+
+**Field rules:**
+- `searchKeyword`: join keywords with ` OR `. Empty string if no keywords.
+- `taxonomyExpression`: stringified JSON `{"OR": ["term1", "term2"]}`. `"{}"` if no taxonomies.
+- `contentAccessScope` / `channelIds`: **mutually exclusive — never send both in the same call.** The public-channels call sets `contentAccessScope: "Public"` and omits `channelIds` entirely. If Step 1 also found one or more `channelId`s, issue a **second** call with `channelIds` set to those values (comma-separated if more than one, e.g. `"0apXX0000001001,0apXX0000001002"`) and omit `contentAccessScope` entirely — merge/de-duplicate the two calls' results.
+- `contentTypeFqn`: the FQN(s) discovered in Step 2 — never hardcode `sfdc_cms__image`.
+- `pageOffset`: start at `0`, increment by `searchLimit` for pagination.
+- `searchLimit`: default `5`, adjust if user requests more.
+
+**Worked example — "luxury apartment with river view" (discovered FQN: `sfdc_cms__image`):**
+
+```json
+{
+  "inputs": [{
+    "searchKeyword": "apartment OR villa OR penthouse OR residence",
+    "taxonomyExpression": "{\"OR\": [\"Luxury\", \"Premium\", \"Waterfront\", \"Riverside\"]}",
+    "searchLanguage": "en_US",
+    "contentAccessScope": "Public",
+    "contentTypeFqn": "sfdc_cms__image",
+    "pageOffset": 0,
+    "searchLimit": 5
+  }]
+}
+```
+
+**Worked example — "car images" (no descriptive terms, discovered FQN: `sfdc_cms__image`):**
+
+```json
+{
+  "inputs": [{
+    "searchKeyword": "car OR automobile OR vehicle OR auto",
+    "taxonomyExpression": "{}",
+    "searchLanguage": "en_US",
+    "contentAccessScope": "Public",
+    "contentTypeFqn": "sfdc_cms__image",
+    "pageOffset": 0,
+    "searchLimit": 5
+  }]
+}
+```
+
+**Worked example — "customer testimonial audio clips" (discovered FQN: `sfdc_cms__audio`):**
+
+```json
+{
+  "inputs": [{
+    "searchKeyword": "testimonial OR customer success OR product satisfaction OR feedback OR review",
+    "taxonomyExpression": "{}",
+    "searchLanguage": "en_US",
+    "contentAccessScope": "Public",
+    "contentTypeFqn": "sfdc_cms__audio",
+    "pageOffset": 0,
+    "searchLimit": 5
+  }]
+}
+```
+
+## Search using Data 360 hybrid search (`search_electronic_media`)
+
+1. Use the user's query **as-is** — no keyword extraction or transformation needed
+2. Call `search_electronic_media(searchQuery="<user's query>")`
+
+Example: user query "modern luxury apartment with natural lighting" → `search_electronic_media(searchQuery="modern luxury apartment with natural lighting")`
+
+## Confirming the query before searching
+
+Regardless of method, confirm the built query with the user before calling the search tool — this is the same required two-message pattern used by the Content Route (see `SKILL.md` Step 3, point 2). Never put the parameter list inside `ask_followup_question`'s `question` text; it strips line breaks and collapses everything into one paragraph.
+
+**Message 1 (plain chat text):**
+
+```text
+I'll search for media with these parameters:
+
+  Content Type: Image (sfdc_cms__image)
+  Keywords: apartment OR villa OR penthouse OR residence
+  Taxonomies: Luxury, Premium, Waterfront, Riverside
+  Language: en_US
+  Channels: Public
+```
+
+**Message 2 (immediately after):** `ask_followup_question` with options `Yes - search now` / `Edit search` / `Cancel`.
+
+## Presenting Search Results
+
+1. **Parse each call's response** — Extract all results (title and content type) and each item's full `managedContentChannelDeliveryDetails` array, merged across calls if the item appears in more than one response (per "Executing the search call(s)" above — nothing is dropped as a duplicate).
+2. **Use `ask_followup_question`** to present ALL results as selectable **unique** options (one option per item, by identifier), grouped by content type — same grouping key as the Content Route (see `content-route.md` Step 6), never by channel. Show the title, content type, and channel on each option — do not display the URL. If an item's `managedContentChannelDeliveryDetails` array has more than one entry, show the **first** entry's channel name here as a lightweight hint only; the actual choice between channels is made after selection (see "Disambiguating channel at selection" below), not here. If more than one content type FQN is in scope, order the options by content type (the tool has no native grouping — approximate it by ordering and, where the UI allows a label, prefixing the option text with the content type). Regardless of grouping, always include the channel as a per-item suffix, e.g. `Product Launch Hero Banner (sfdc_cms__image) — Public`.
+3. **Receive the user's selection** from the tool response
+
+## Disambiguating channel at selection
+
+Reached at Step 4 point 5, only when the selected item's (merged) `managedContentChannelDeliveryDetails` array has more than one entry. Build one option per entry from `managedContentChannelDetails.name`, in the order the array returns them — not a fixed two-option choice. **Call `ask_followup_question` with these as its actual `question` and `options` parameters — never concatenate the channel list into the question string itself**, the same rule every other question in this skill follows:
+
+```text
+question: "Which channel would you like to use for 'Modern Minimalist Logo'?"
+options: ["Public", "landing-page"]
+```
+
+Wait for the reply before displaying the item's details (below) — use the record from the **chosen** entry, never assume entry `[0]` is the right one. If the array has zero entries, skip this question and display with the Unauthenticated URL line omitted; if it has exactly one entry, skip the question and use that entry directly. See `content-route.md` "Disambiguating channel at selection" for a real six-channel example — the array can hold far more than two entries.
+
+**A `WEB_APP` entry is still a valid, selectable option here** — it's excluded only from the Unauthenticated URL line at display time (see "Handing off the selected media item" below), not from the channel choice itself.
+
+## Handing off the selected media item
+
+1. **Confirm the selection**, displaying:
+   - **Content Name** — `title`
+   - **Content Type** — `contentType` (e.g. `sfdc_cms__image`, `sfdc_cms__audio`, `sfdc_cms__video`, `sfdc_cms__document`)
+   - **Channel** — the channel of the entry that was used (the item's only entry, or the one chosen in "Disambiguating channel at selection" above)
+   - **Unauthenticated URL** — shown **only when that entry's `managedContentChannelDetails.type` is `PUBLIC_UNAUTHENTICATED` or `COMMUNITY` AND it has a `contentUrl`** — the complete URL including all query parameters (CMS and DAM URLs rely on them for authentication, resizing, and CDN routing; dropping them breaks the media item). E.g. `https://cms.example.com/media/img.jpg?oid=00D&refid=0EM&v=2` must be used in full. **Never shown for a `WEB_APP` (uiBundle) channel entry, even when `contentUrl` is present** — that URL isn't meant for public consumption. Omit the line entirely whenever either condition fails (absent `contentUrl`, `WEB_APP` type, or no entries at all) — do not show it blank or with a placeholder.
+2. **Offer the render hand-off — always, no uiBundle gating** (unlike the Content Route's offer, which only appears when a uiBundle channel was in scope; see `content-route.md` "Offering the render hand-off"). Same required two-message pattern:
+
+   **Message 1 (plain text):**
+
+   ```text
+   I can render "<title>" (<content type label>) using the experience-cms-content-render skill.
+   ```
+
+   **Message 2 (immediately after):** `ask_followup_question` with options `Yes` / `No`. Never restate the item's details inside the question text — the question stays generic (`"Invoke the render skill for this item?"`).
+
+3. **On `Yes`** — dispatch via `mcp__skill_bridge__load_skill("experience-cms-content-render")` — never the built-in Skill tool (separate registry, returns `Unknown skill`). Pass the item's `title`, content type FQN, and the chosen entry's `managedContentChannelDetails.id` (channel ID) **only when the item has a delivery entry** — this route explicitly supports zero-entry items (see "Disambiguating channel at selection" above), and the render hand-off is always offered regardless, so a zero-entry item reaches this step with no entry to read `.id` from. **Omit the channel ID for it entirely — never a placeholder or `null`** — `experience-cms-content-render`'s own documented channel-resolution flow asks the user for the channel (or HALTs) when none is supplied. Also pass either its Unauthenticated URL (if present) or, if absent, its `managedContentKey` renamed to `contentKey` — `experience-cms-content-render`'s own `SKILL.md` names the field `contentKey`, not `managedContentKey`. If the load call fails, tell the user the hand-off failed and stop.
+4. **On `No`** — stop; the search is complete. Do not apply the URL yourself as a fallback.

package/skills/experience-search-coordinate/references/scope-resolution.md

@@ -0,0 +1,14 @@
+# Channel Scope Resolution — Full Reference
+
+## Step 1 points 1-3 — discovering channel scope
+
+1. **Explicit `channelId` given** (e.g. "search within channel 0apXX0000001001", or passed as an input to this skill) — use it directly as the scoped channel and skip straight to the scope rule in `SKILL.md` Step 1. Do not run uiBundle discovery in this case.
+2. **Named uiBundle/app, no `channelId`** (e.g. "search in this uiBundle" or "search in the Homepage app") — locate that named uiBundle (e.g. `<sfdx-source>/uiBundles/<named-uiBundle>/public/content-metadata.json`) and read its `channelId` if present:
+   - **Found, with a `channelId`** — use it as the scoped channel, skip to the scope rule.
+   - **Not found, or found but no `channelId` present** — fall through to point 3 and scan every uiBundle as if the user hadn't named one.
+3. **Otherwise, discover from uiBundles by scanning the local project — never gate this on server-side deployment status:**
+   - **Scan the project directly** for every `uiBundles/*/public/content-metadata.json` file using whichever directory-listing/glob capability your environment exposes. Do NOT run `sf org list metadata --metadata-type UIBundle` first and use its result to gate which bundles you check — a uiBundle's CMS channel can exist even when the uiBundle itself is not (yet, or ever) deployed to the currently-targeted org, so a server-side deployed-bundle list would wrongly exclude it.
+   - **For each `content-metadata.json` found**, read it and collect the `channelId` if present — no server-side field or API links a UIBundle to a CMS channel, so this local file is the only source for `channelId`.
+   - **Zero uiBundles with a `channelId`** — scope is public channels only.
+   - **Exactly one** — scope is public channels **plus** that `channelId`.
+   - **More than one** — call `ask_followup_question` with the question `"Multiple components have their own CMS channel. Which one should I search within (in addition to public channels)?"` and one **option** per uiBundle in the tool's `options` array — never as numbered lines inside the question text. Scope is public channels plus the selected `channelId`.

package/skills/experience-ui-bundle-localize/SKILL.md

@@ -190,7 +190,7 @@ Branch on the exit code: `0`, every key is registered (or there are no `t()` cal
 
 **Goal:** Ensure the i18next init exists; scaffold it if the app has no i18n yet.
 
-Configure `SalesforceBackend` by bundle type: preserve the shipped `BASE_VALUE` default for B2E; for B2C only, set `labelFallback: "USER_DEFAULT"`. See [references/i18n-setup.md](references/i18n-setup.md) for both configurations and B2C language context.
+Configure `SalesforceBackend` by bundle type: preserve the shipped `BASE_VALUE` default for B2E; for B2C only, set `labelFallback: "USER_DEFAULT"` and pass the route-selected `SFDC_ENV.language`, with `ctx.lang` fallback, as `lng` to `i18next.init`. See [references/i18n-setup.md](references/i18n-setup.md) for both configurations and B2C language context.
 
 **Check:**
 Run `check-i18n-wired.sh` from the UI bundle dir (it scans `src/` relative to the current directory) and report what it returns. The script owns the whole deterministic inspection: it looks for an init file defining `initI18n()` and a boot-time call to it, and when those exist it also reports whether the label manifest is imported and actually passed into the backend config. Do not re-derive any of this by reading files yourself.

package/skills/experience-ui-bundle-localize/references/i18n-setup.md

@@ -74,7 +74,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, also 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. Reuse the resolved language from the site's language-switcher integration:
+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:
 
 ```typescript
 const resolvedLang =
@@ -83,6 +83,8 @@ 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.
+
 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.
 
 **Call it once at boot**, before mounting your app:
@@ -120,7 +122,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`; 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.
+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.
 
 For local preview, use the site entry of the Vite plugin and pass the site's supported language codes, with the default first:
 
@@ -169,7 +171,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 uses the site route's `SFDC_ENV.language`)
+3. `fetchI18nContext()` queries the org for language/locale/direction; B2C separately passes the site route's `SFDC_ENV.language` to i18next as `lng`
 4. `SalesforceBackend` reads the manifest and issues a GraphQL query per namespace:
    ```graphql
    query LoadLabels {

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

@@ -1,8 +1,8 @@
 ---
 name: experience-ui-bundle-project-generate
-description: "Generates a minimal, ready-to-develop SFDX starter project from template instead of hand-scaffolding files. Use this skill when starting a brand-new Salesforce React UI bundle app and the initial project must be scaffolded — trigger phrases include create, start, or scaffold a new React UI bundle app, generate a starter project, or use a prebuilt/starter template. DO NOT TRIGGER when: editing, styling, or adding pages or components to an EXISTING app (use experience-ui-bundle-frontend-generate); configuring ui-bundle.json or metadata files (use experience-ui-bundle-metadata-generate); deploying to an org (use experience-ui-bundle-deploy); or when the user explicitly says they want to hand-scaffold from scratch."
+description: "Generates a minimal, ready-to-develop SFDX starter project from template instead of hand-scaffolding files. Use this skill when starting a brand-new Salesforce UI bundle app (React or Angular) and the initial project must be scaffolded — trigger phrases include create, start, or scaffold a new UI bundle app, generate a starter project, or use a prebuilt/starter template. DO NOT TRIGGER when: editing, styling, or adding pages or components to an EXISTING app (use experience-ui-bundle-frontend-generate); configuring ui-bundle.json or metadata files (use experience-ui-bundle-metadata-generate); deploying to an org (use experience-ui-bundle-deploy); or when the user explicitly says they want to hand-scaffold from scratch."
 metadata:
-  version: "1.1"
+  version: "1.2"
   domains: ["Experience"]
   relatedSkills:
     - "experience-ui-bundle-app-coordinate"
@@ -21,20 +21,24 @@ metadata:
 
 # Using a UI Bundle Template
 
-Before building a Salesforce React UI bundle app from scratch, offer the user a **prebuilt starter template**. The Salesforce CLI generates these — a complete, deployable SFDX project (React UI bundle + toolchain + an `npm run setup` automation) — in one command. Starting from a starter is faster and less error-prone than hand-scaffolding.
+Before building a Salesforce UI bundle app from scratch, offer the user a **prebuilt starter template**. The Salesforce CLI generates these — a complete, deployable SFDX project (UI bundle + toolchain + an `npm run setup` automation) — in one command. Starting from a starter is faster and less error-prone than hand-scaffolding.
 
 The CLI command is `sf template generate project`.
 
 ## Step 1: Offer the choice
 
-The following are the templates. Ask the user which one fits, or whether they want to start from scratch.
+**Determine the framework.** It is normally already decided by the calling context — either passed down by the root/coordinator skill that invoked this one, or stated in the user's request. Use that.
 
-| Template | `--template` flag | Best for |
-|----------|-------------------|----------|
-| Internal starter | `reactinternalapp` | Starter for internal, employee-facing Salesforce apps (e.g. support consoles, ops dashboards, internal admin apps) — users are already-authenticated employees. Includes Agentforce chat. No login flow or public. |
-| External starter | `reactexternalapp` | Starter for customer/partner-facing Salesforce apps/sites (e.g. portals, communities, storefront, public sites). Full auth support (login, registration, reset, profile) -- external users sign in with their own accounts. |
+The frameworks this skill supports are exactly the reference files under `<SKILL_DIR>/references/`, each named `<framework>-project-generate.md` (so `react` → `<SKILL_DIR>/references/react-project-generate.md`). This is the single source of truth — adding a framework means adding a reference file, nothing here changes.
 
-**If the user prefers to start from scratch** (or neither fits), stop here and let `experience-ui-bundle-app-coordinate` scaffold a new project. This skill is opt-in — do not force a template.
+- **If the framework is known** — open `<SKILL_DIR>/references/<framework>-project-generate.md`.
+- **If it is unknown** (a standalone run where nobody said which) — list `<SKILL_DIR>/references/`, derive the supported set by stripping the `-project-generate.md` suffix from each filename, and ask the user to pick one of those. If the user names a framework with no matching reference file, it is not supported here — hand off to `experience-ui-bundle-app-coordinate` to scaffold from scratch.
+
+Each reference lists that framework's `--template` flags and what each starter contains. Pick the one that fits the user's audience (internal vs. external).
+
+**If the user prefers to start from scratch** (or neither template fits), stop here and let `experience-ui-bundle-app-coordinate` scaffold a new project. This skill is opt-in — do not force a template.
+
+Once the user picks, carry the chosen `--template` flag into Step 2.
 
 ## Step 2: Generate the project into the target root
 
@@ -48,8 +52,8 @@ The project contents must land **directly at the target root `$DEST`** — so `s
 NAME=MyApp   # project name the user chose; also names the UI bundle
 DEST=.       # target root directory (the contents land directly here, no NAME/ wrapper)
 
-# choose ONE template flag based on the user's pick from Step 1
-TEMPLATE=reactinternalapp   # or reactexternalapp
+# the --template flag from the framework reference chosen in Step 1
+TEMPLATE=reactinternalapp   # example placeholder — replace with the flag from your Step-1 reference
 
 mkdir -p "$DEST"
 sf template generate project --name "$NAME" --template "$TEMPLATE" --output-dir "$DEST"
@@ -70,7 +74,7 @@ After generation, confirm the contents landed at the root (not in a `$NAME/` sub
 test -f "$DEST/sfdx-project.json" && echo "OK: project root landed" || echo "FAILED"
 ```
 
-`sfdx-project.json` must sit at `$DEST/sfdx-project.json`. The project also contains `package.json`, `force-app/main/default/uiBundles/$NAME/` (the React/Vite bundle), `scripts/`, `config/`, and `README.md`. If `sfdx-project.json` is missing or is one level down in `$DEST/$NAME/`, the flatten did not run — re-check before continuing.
+`sfdx-project.json` must sit at `$DEST/sfdx-project.json`. The project also contains `package.json`, `force-app/main/default/uiBundles/$NAME/` (the UI bundle), `scripts/`, `config/`, and `README.md`. See the framework reference from Step 1 for the specific bundle contents. If `sfdx-project.json` is missing or is one level down in `$DEST/$NAME/`, the flatten did not run — re-check before continuing.
 
 ## Step 3: Install dependencies (you do this — do NOT hand off uninstalled)
 
@@ -90,7 +94,7 @@ for b in "$DEST"/force-app/main/default/uiBundles/*/; do
 done
 ```
 
-> First-run install of the bundle is the heavy step (tailwind, radix-ui, recharts, vite, etc.); expect a short wait. If an install fails, surface it — don't hand off a half-installed project.
+> First-run install of the bundle is the heavy step; expect a short wait. If an install fails, surface it — don't hand off a half-installed project.
 
 ## Step 4: Confirm and hand off
 
@@ -109,4 +113,4 @@ From here, continue development with the other ui-bundle skills (`experience-ui-
 
 - The starters are **minimal** — no seeded sample data or custom objects. Build the rest with the other ui-bundle skills.
 - These templates use the `uiBundles` metadata convention. The UI bundle directory and meta XML are named after the project name you pass to `--name`.
-- `sf template generate project --help` lists all available templates if the flag names ever change.
+- `sf template generate project --help` lists all available templates if the flag names ever change.

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

@@ -0,0 +1,22 @@
+# Angular UI Bundle Starter Templates
+
+Reference for the **Angular** path of `experience-ui-bundle-project-generate`. Pick the `--template` flag that fits the user's audience, then return to Step 2 of `SKILL.md`.
+
+## Template options
+
+| Template | `--template` flag | Best for |
+|----------|-------------------|----------|
+| Internal starter | `angularinternalapp` | Starter for internal, employee-facing Salesforce apps (e.g. support consoles, ops dashboards, internal admin apps) — users are already-authenticated employees. Includes agent chat container. No login flow or public access. |
+| External starter | `angularexternalapp` | Starter for customer/partner-facing Salesforce apps/sites (e.g. portals, communities, storefront, public sites). Includes agent chat container. Full auth support (login, registration, reset, profile) — external users sign in with their own accounts. |
+
+## What the bundle contains
+
+The generated UI bundle under `force-app/main/default/uiBundles/$NAME/` is an **Angular** app (Angular 21.2.x) built on **spartan-ng**:
+
+- **Build:** Angular CLI driven by `angular.json` with the `@angular/build:application` builder (esbuild-based). Salesforce platform integration is wired through the `@salesforce/angular-plugin-ui-bundle` esbuild plugin (via `@angular-builders/custom-esbuild`), which handles API-version substitution, the org proxy, and Live Preview / `SFDC_ENV` / base-href injection.
+- **Components:** standalone components + signals + native control flow (`@if`/`@for`); each component is a `.ts` + `.html` pair, named without a `.component` infix (e.g. `home.ts` + `home.html`).
+- **App wiring:** entry `src/main.ts`; `src/app/app.ts` + `src/app/app.html`; `src/app/app.config.ts` (`APP_BASE_HREF` + `SFDC_ENV.basePath`); `src/app/app.routes.ts`. Pages under `src/app/pages/` (e.g. `home/`, `login/`, `account-search/`, `not-found/`).
+- **UI library:** **spartan-ng** — `hlm-*` "Helm" primitives under `src/app/shared/` (alert, button, calendar, card, dialog, dropdown-menu, field, input, label, pagination, popover, select, separator, skeleton, spinner…), each folder exporting an `index.ts`. Configured via `components.json`; built on `@spartan-ng/brain` + `@spartan-ng/cli` + **Tailwind 4** (`src/styles.css`). Not Angular Material — there is no `theme.scss`. `src/app/components/` holds only `layout/app-layout` plus small `ui/` helpers.
+- **Data layer:** injectable GraphQL data client `src/app/api/data-client.service.ts` (plus `user-profile.service.ts`, generated `graphql-operations-types.ts`, and typed operations under `src/app/api/account/`). GraphQL type codegen is optional and manual (not chained to the build).
+- **Metadata & config:** `ui-bundle.json`, `$NAME.uibundle-meta.xml`, `tsconfig.*`, `eslint.config.js`, `playwright.config.ts`, `README.md`.
+- **External (customer-facing) markers:** the external template also emits `networks/$NAME.network-meta.xml` + `sites/$NAME.site-meta.xml` and a full `src/app/features/authentication/` feature (login, register, forgot/reset/change-password, profile) — these distinguish the external starter from the internal one.

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

@@ -0,0 +1,20 @@
+# React UI Bundle Starter Templates
+
+Reference for the **React** path of `experience-ui-bundle-project-generate`. Pick the `--template` flag that fits the user's audience, then return to Step 2 of `SKILL.md`.
+
+## Template options
+
+| Template | `--template` flag | Best for |
+|----------|-------------------|----------|
+| Internal starter | `reactinternalapp` | Starter for internal, employee-facing Salesforce apps (e.g. support consoles, ops dashboards, internal admin apps) — users are already-authenticated employees. Includes agent chat container. No login flow or public access. |
+| External starter | `reactexternalapp` | Starter for customer/partner-facing Salesforce apps/sites (e.g. portals, communities, storefront, public sites). Includes agent chat container. Full auth support (login, registration, reset, profile) — external users sign in with their own accounts. |
+
+## What the bundle contains
+
+The generated UI bundle under `force-app/main/default/uiBundles/$NAME/` is a **React/Vite** app:
+
+- React + Vite toolchain, TypeScript, `vite.config.ts`.
+- shadcn/ui primitives (`src/components/ui/`), Tailwind.
+- `.tsx` pages/components; app entry `src/App.tsx`, pages under `src/pages/`.
+- GraphQL client (`src/api/graphqlClient.ts`) + codegen (`codegen.yml`), `useAsyncData` data util.
+- `ui-bundle.json`, `*.uibundle-meta.xml`, project config, `README.md`.

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

@@ -31,10 +31,10 @@ This file is the **workflow + guardrail spine**. Depth lives in linked docs:
   commands) that compiles a small JSON spec into a schema-correct, guardrail-applied query +
   variables + types. The preferred way to author the GraphQL in steps below; falls back to the
   schema-grep script when unavailable.
-- **[references/sdk-api.md](references/sdk-api.md)** — the new call API: `query`/`mutate`,
-  `QueryResult`, typing, error-handling stances.
-- **[references/caching.md](references/caching.md)** — on-by-default cache + the **two refresh
-  modes** (`result.refresh`/`subscribe` vs per-call `cacheControl`).
+- **[references/sdk-api.md](references/sdk-api.md)** — `query`/`mutate` call surface + generated-type
+  placement; the behavior nuance (surfaces, error stances, `QueryResult`) grounds on **tier-2b**.
+- **[references/caching.md](references/caching.md)** — the on-by-default cache + two refresh modes;
+  behavior grounds on **tier-2b** `docs/data/` when installed, with the full version-stamped fallback here.
 - **[references/graphql-hand-authoring.md](references/graphql-hand-authoring.md)** — schema lookup, read /
   mutation templates, every platform guardrail (`@optional`, pagination, limits,
   semi-join, wrappers, error table…).
@@ -99,7 +99,8 @@ declaration and note the drift; do not "correct" the types to match the prose.
 |---|---|---|---|
 | tier-1 | GraphQL **schema** | *what data exists* | graphiti / `graphql-search.sh` (Precondition #2) |
 | tier-2a | SDK **contract** | *how you call it* | the installed `.d.ts` above |
-| spine | this SKILL.md | workflow + guardrails that orchestrate both; the fallback when a tier can't ground |
+| tier-2b | SDK **behavior** | *how it behaves* | the installed `docs/data/` folder (below) |
+| spine | this SKILL.md | workflow + guardrails that orchestrate all three; the fallback when a tier can't ground |
 
 **Fallback when the `.d.ts` is absent** — the package **is installed** but ships
 no declarations (a stale or types-stripped build artifact). Then use this SKILL's
@@ -109,22 +110,35 @@ prose as best-effort. This fallback does **not** cover a missing package: if
 
 ---
 
-## Surfaces — `sdk.graphql!` vs guard
+## Ground the SDK behavior on the installed docs (tier-2b)
 
-`createDataSDK()` runs on multiple surfaces, and **`sdk.graphql` / `sdk.fetch` are genuinely
-optional** (typed `graphql?: …`). Whether you may assert them with `!` depends entirely on
-where the bundle runs — this is the one surface decision that turns into a *runtime crash* if
-you get it wrong, so make it explicitly before writing any `query`/`mutate` call:
+The same package ships an authored **behavior** guide beside its types:
+`node_modules/@salesforce/platform-sdk/docs/data/` (numbered files, read them in order).
+Tier-2a's `.d.ts` fixes the call *contract*; this folder is authoritative for the *behavior* the
+contract doesn't spell out — the caching model, the surface `!`-vs-guard decision, error-handling
+stances, the migration mindset. **Read it before choosing a caching policy, a surface assertion, or
+an error stance, and let it win** — same precedence as tier-2a (the installed source beats this
+prose; when present it's the fuller, version-current copy).
 
-| Surface(s) | `sdk.graphql` | Write |
-|---|---|---|
-| **WebApp only** | always present | `sdk.graphql!.query({...})` — `!` is safe; every shipped WebApp consumer uses it |
-| **Mosaic / OpenAI / MCPApps** (or any bundle that *might* run off-WebApp) | can be `undefined` | **guard first** (`if (!sdk.graphql) return …`), then call |
+**Fallback when the folder is absent** (older SDK, or a types-only build): this SKILL keeps a thin
+per-behavior fallback — below and in each section — sized only to keep you moving; act on it. As
+with tier-2a, a missing *package* is different: if `@salesforce/platform-sdk` isn't installed, stop
+and install it (Precondition #1).
 
-Rule of thumb: **if you cannot prove the bundle is WebApp-only, guard.** A bare `sdk.graphql!`
-that later ships to another surface throws `Cannot read properties of undefined` at runtime —
-TypeScript won't catch it because `!` silences exactly that check (same applies to `sdk.fetch!`).
-The portable guard snippet lives in [references/sdk-api.md](references/sdk-api.md#sdkgraphql-vs-guard).
+---
+
+## Surfaces — `sdk.graphql!` vs guard
+
+`sdk.graphql` / `sdk.fetch` are genuinely optional (typed `graphql?: …`), and whether you may
+assert them with `!` is a *runtime-crash* decision — make it before writing any `query`/`mutate`.
+**Fallback rule: WebApp-only bundle → `sdk.graphql!` is safe; any bundle that might run
+off-WebApp (Mosaic / OpenAI / MCPApps) → guard first (`if (!sdk.graphql) return …`), then call.**
+If you cannot prove WebApp-only, guard — a bare `!` that later ships elsewhere throws
+`Cannot read properties of undefined` and TypeScript won't catch it (same for `sdk.fetch!`).
+
+The surface matrix, the portable guard snippet, and the full reasoning ground on **tier-2b**
+`docs/data/` (fallback above); the guard snippet is also in
+[references/sdk-api.md](references/sdk-api.md#sdkgraphql-vs-guard).
 
 ---
 
@@ -159,7 +173,7 @@ you grounded against the right file.
 
 | # | Requirement | Verify | If missing |
 |---|---|---|---|
-| 1 | `@salesforce/platform-sdk` installed **and its contract read** | `package.json` in the UI bundle dir lists it; then read `node_modules/@salesforce/platform-sdk/dist/core/data.d.ts` + `dist/data/index.d.ts` and let them win over this SKILL's prose ([tier-2a](#ground-the-sdk-contract-on-the-installed-types-tier-2a)) | Not installed → tell user to install it; cannot proceed. Installed but `.d.ts` absent (stale artifact) → use prose fallback |
+| 1 | `@salesforce/platform-sdk` installed **and its contract + behavior docs read** | `package.json` in the UI bundle dir lists it; then read `dist/core/data.d.ts` + `dist/data/index.d.ts` ([tier-2a](#ground-the-sdk-contract-on-the-installed-types-tier-2a)) **and** the `docs/data/` folder ([tier-2b](#ground-the-sdk-behavior-on-the-installed-docs-tier-2b)), and let them win over this SKILL's prose | Not installed → tell user to install it; cannot proceed. Installed but `.d.ts` / `docs/` absent (stale or types-only artifact) → use prose fallback |
 | 2 | A grounding tool resolves | **Preferred:** `npx graphiti sf-gql-discover '{"org":"<alias>","mode":"list_objects"}'` from the UI bundle dir returns objects. **Fallback:** `bash <skill-dir>/scripts/graphql-search.sh <Entity>` from the project root prints a lookup, not "schema.graphql not found" | No graphiti dep / org won't prime → use the script. Script can't find `schema.graphql` → pass `--schema <path>`, or `npm run graphql:schema` from the UI bundle dir. ([references/graphiti-cli.md](references/graphiti-cli.md) covers CLI setup) |
 | 3 | Target objects/fields deployed | The object appears in `sf-gql-discover` (or `graphql-search.sh <Entity>` returns output) | Entity absent usually means it isn't deployed (or the cache/schema is stale). Refresh: `npx graphiti sf-gql-connect '{"org":"<alias>","forceRefresh":true}'` (CLI) or `npm run graphql:schema` (script). If still absent, deploy the metadata (the **platform-metadata-deploy** skill handles this) and assign the permission sets, then re-check |
 
@@ -220,7 +234,8 @@ write GraphQL strings until the schema workflow is complete.
    ```
 
 Defend consuming code with `?.`/`??` (because `@optional` can omit fields). Error-handling
-stances (strict / tolerant / discriminated) and `NodeOfConnection` typing: [references/sdk-api.md](references/sdk-api.md).
+stances (strict / tolerant / discriminated) ground on **tier-2b** `docs/data/` (fallback:
+guardrail #1 — always check `result.errors`); `NodeOfConnection` typing in [references/sdk-api.md](references/sdk-api.md).
 
 ---
 
@@ -294,40 +309,28 @@ templates: [references/graphql-hand-authoring.md](references/graphql-hand-author
 
 ## Freshness & caching
 
-**Caching is ON by default on WebApp.** Every `sdk.graphql!.query()` is cached with a
-**300-second `max-age`** TTL — no opt-in flag, no factory, no import subpath. **Do not
-build your own cache** (no React Query, SWR, `localStorage`, or hand-rolled Map). The
-cache is **shared across SDK instances by `baseUrl`**: the same query+variables from a
-different `createDataSDK()` targeting the same host is a cache hit. Only non-empty,
-error-free `data` is cached. `mutate()` is never cached.
-
-There are **two distinct freshness tools** — keep them separate:
-
-1. **Per-call `cacheControl`** — a one-shot policy override on the query options bag
-   (`"no-cache"` / `"only-if-cached"` / `{ type: "max-age", maxAge: <seconds> }`). The type and
-   exact per-value behavior live in [references/sdk-api.md](references/sdk-api.md#cachecontrol--the-per-call-cache-policy).
-   Take `cacheControl` as an optional param on the read function and expose each distinct policy as
-   a **thin named export in the same data-layer file** — a "call site" is a named export, not a new
-   React component. For `getAccounts(first, after?, cacheControl?)`: `export const refreshAccounts =
-   () => getAccounts(20, undefined, "no-cache")` (and likewise `offlineAccounts` → `"only-if-cached"`,
-   `shortLivedAccounts` → `{ type: "max-age", maxAge: 10 }`). Keep the policy in the data layer.
-2. **Reactive `subscribe` / `refresh`** — a stateful handle on a live `QueryResult`:
-   `result.subscribe(cb)` fires on every later snapshot, `result.refresh()` re-fetches bypassing
-   the cache and pushes to subscribers. Shape in [references/sdk-api.md](references/sdk-api.md#queryresultt--the-reactive-query-handle);
-   subscription lifecycle (always unsubscribe on teardown) in [references/caching.md](references/caching.md).
-
-| Want | Reach for |
-|---|---|
-| Freshness within ~5 min is fine | nothing (default cache) |
-| This one read must bypass the cache (refresh button) | `cacheControl: "no-cache"` |
-| Read only cached data, tolerate misses (offline-first) | `cacheControl: "only-if-cached"` — a miss is **expected, not an error**: it surfaces a `DataNotFoundError` on `result.errors` (no network, no throw). Check `result.errors`, render empty state, **do not throw and do not fall back to the network** — that defeats offline-first. |
-| Tighter/looser TTL for this query | `cacheControl: { type: "max-age", maxAge: 60 }` (`maxAge` is in **seconds**) |
-| Mounted component reflects updates over time | `result.subscribe(cb)` |
-| Re-fetch now + notify all subscribers (e.g. after a mutation) | `result.refresh()` |
-
-`cacheControl` is fire-and-forget at call time; `subscribe`/`refresh` is a live handle.
-Different mechanisms, different jobs — don't conflate "refresh" with "no-cache". Full
-behavior, the reactive-subscription lifecycle, and uncached-surface caveats: [references/caching.md](references/caching.md).
+Ground the cache model on **tier-2b** `docs/data/` — cache-key mechanics, what-gets-cached,
+the shared-by-`baseUrl` details, uncached-surface semantics, and the reactive-handle nuance all
+live there ([references/caching.md](references/caching.md) restates it as a version-stamped fallback). The
+**load-bearing fallback** (enough to act when the folder is absent):
+
+- **Caching is ON by default on WebApp** — every `query()` cached at **300s**; no opt-in flag, no
+  factory, no `/cache` subpath. **Do not build your own cache** (React Query, SWR, `localStorage`,
+  hand-rolled `Map`). `mutate()` is never cached.
+- **Shared by host + API version** — the same query+variables from another `createDataSDK()`
+  targeting the same host **and** `apiVersion` is a cache hit = one network call; the per-instance
+  fetch pipeline stays isolated.
+- **Two distinct freshness tools — don't conflate them:**
+  1. **Per-call `cacheControl`** (one-shot policy on the options bag): `"no-cache"` (bypass, writes
+     back) / `"only-if-cached"` / `{ type: "max-age", maxAge: <seconds> }`; default 300s. Thread it as
+     an optional param on the read fn and expose each policy as a **thin named export** in the same
+     data-layer file (`refreshAccounts` → `"no-cache"`, `offlineAccounts` → `"only-if-cached"`, …). An
+     `"only-if-cached"` **miss** surfaces on `result.errors` with `extensions.code === "CACHE_MISS"` —
+     render an empty state, **do not** fall back to the network (that defeats offline-first).
+  2. **Reactive `subscribe` / `refresh`** (live handle on a `QueryResult`): `subscribe(cb)` fires on
+     **later** snapshots only (always `unsubscribe` on teardown); `refresh()` re-fetches, bypasses the
+     cache, pushes to subscribers — use it after a `mutate()` (which has no `refresh`). Multi-subscriber
+     fan-out / independence ground on **tier-2b** `docs/data/`.
 
 ---
 
@@ -433,6 +436,7 @@ silent runtime failures. (Details + templates: [references/graphql-hand-authorin
 
 - [ ] Surface decided: `sdk.graphql!` only if WebApp-only; otherwise guard with `if (!sdk.graphql) …` ([Surfaces](#surfaces--sdkgraphql-vs-guard))
 - [ ] SDK contract grounded on installed `dist/*.d.ts` (types win over prose) ([tier-2a](#ground-the-sdk-contract-on-the-installed-types-tier-2a))
+- [ ] SDK behavior grounded on installed `docs/data/` (docs win over prose; fallback if absent) ([tier-2b](#ground-the-sdk-behavior-on-the-installed-docs-tier-2b))
 - [ ] Every field/entity verified — `sf-gql-discover` (preferred) or `graphql-search.sh` (fallback, against the right schema)
 - [ ] If compiled with graphiti: `warnings: []` confirmed (non-empty = degraded query, don't ship); `query` pasted verbatim
 - [ ] `@optional` on FLS-gated fields + relationships (NOT `Id`/`edges`/`node`/`pageInfo`); `?.`/`??` in consuming code