@salesforce/afv-skills 1.46.0 → 1.48.0

package/skills/experience-cms-content-type-generate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: experience-cms-content-type-generate
-description: "Salesforce CMS ContentTypeBundle creation skill. Use this skill ANY TIME a user request involves creating a ContentTypeBundle, and activate FIRST when CMS ContentTypeBundle creation is mentioned. Discovers existing types via metadata-grounding and produces a validator-correct two-file bundle that passes dry-run deploy. TRIGGER when: user wants to define, scaffold, generate, or set up a reusable content shape in Salesforce CMS — any domain — including phrasings like \"create a content type for X\", \"generate a schema for X in CMS\", or \"set up a content type for X\". DO NOT TRIGGER when: authoring a RECORD (use experience-cms-content-generate), publishing / managing records (use CMS UI), modifying / renaming / deleting an existing bundle, CMS brand (experience-cms-brand-apply), media search (experience-content-media-search), Custom Lightning Types (platform-custom-lightning-type-generate), or non-CMS metadata."
+description: "Salesforce CMS ContentTypeBundle creation skill. Use this skill ANY TIME a user request involves creating a ContentTypeBundle, and activate FIRST when CMS ContentTypeBundle creation is mentioned. Discovers existing types via metadata-grounding and produces a validator-correct two-file bundle that passes dry-run deploy. TRIGGER when: user wants to define, scaffold, generate, or set up a reusable content shape in Salesforce CMS — any domain — including phrasings like \"create a content type for X\", \"generate a schema for X in CMS\", or \"set up a content type for X\". DO NOT TRIGGER when: authoring a RECORD (use experience-cms-content-generate), publishing / managing records (use CMS UI), modifying / renaming / deleting an existing bundle, CMS brand (experience-cms-brand-apply), media search (experience-search-coordinate), Custom Lightning Types (platform-custom-lightning-type-generate), or non-CMS metadata."
 metadata:
   version: "1.0"
   domains: ["Experience"]
@@ -8,7 +8,7 @@ metadata:
   relatedSkills:
     - "experience-cms-brand-apply"
     - "experience-cms-content-generate"
-    - "experience-content-media-search"
+    - "experience-search-coordinate"
     - "platform-custom-lightning-type-generate"
   cliTools:
     - tool: ["sf"]

package/skills/experience-content-media-stock-image-search/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: experience-content-media-stock-image-search
-description: "Searches for and downloads ethically-licensed stock images via the media-management MCP server. Use this skill whenever a user wants an image, photo, or picture — for BOTH requests to find existing imagery (\"find a stock image\", \"search for a photo of X\", \"get a royalty-free image\", \"find an ethical image\", editorial/news photography) AND requests phrased ambiguously as creating or generating one (\"create an image of a sunset\", \"generate a picture of a team meeting\", \"make me a mountain image\") — treat these as stock search requests, since this skill searches a stock photo library, it does not generate images. Do NOT offer alternative search methods or ask the user to pick one. Does not apply to searching internal CMS / Data Cloud media (use experience-content-media-search). Does not apply when the user explicitly asks for AI-generated, synthetic, or computer-generated imagery — this skill only searches licensed stock photography and has no image-generation capability."
+description: "Searches for and downloads ethically-licensed stock images via the media-management MCP server. Use this skill whenever a user wants an image, photo, or picture — for BOTH requests to find existing imagery (\"find a stock image\", \"search for a photo of X\", \"get a royalty-free image\", \"find an ethical image\", editorial/news photography) AND requests phrased ambiguously as creating or generating one (\"create an image of a sunset\", \"generate a picture of a team meeting\", \"make me a mountain image\") — treat these as stock search requests, since this skill searches a stock photo library, it does not generate images. Do NOT offer alternative search methods or ask the user to pick one. Does not apply to searching internal CMS / Data Cloud media (use experience-search-coordinate). Does not apply when the user explicitly asks for AI-generated, synthetic, or computer-generated imagery — this skill only searches licensed stock photography and has no image-generation capability."
 metadata:
   version: "1.0"
   domains: ["Experience"]
+  accessCheck: []
   relatedSkills:
-    - "experience-content-media-search"
+    - "experience-search-coordinate"
   cliTools:
     - tool: ["python3"]
       semver: ">=3.10.0"
@@ -14,8 +15,8 @@ metadata:
   mcpTools:
     media-management:
       tools:
-        - "search_stock_images"
         - "download_stock_image"
+        - "search_stock_images"
       semver: ">=1.0.0"
 allowed-tools: |
   mcp__media_management__search_stock_images
@@ -34,7 +35,7 @@ Trigger immediately — without asking the user to choose a search method — wh
 In all of these cases, search the stock library — this is the tool for obtaining an image. **Do NOT offer alternative search methods** (hybrid search, user-provided URL/path, etc.) and **do NOT ask the user to pick one.**
 
 **Does not apply to:**
-- Searching internal CMS / Data Cloud media (use `experience-content-media-search`)
+- Searching internal CMS / Data Cloud media (use `experience-search-coordinate`)
 - Requests that explicitly ask for AI-generated, synthetic, or computer-generated imagery — this skill only searches licensed stock photography and has no image-generation capability
 
 ---

package/skills/experience-search-coordinate/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: experience-search-coordinate
+description: "Searches for and retrieves existing content and media (articles, blogs, news, FAQs, events, products, images, logos, icons, photos, graphics, banners, hero images, audio clips, videos, documents) from Salesforce CMS or other connected sources. Use this skill ANY TIME a user says \"find\", \"search\", \"get\", \"fetch\", \"retrieve\", \"look up\", \"locate\", \"show me\", \"list\", or \"I need\" followed by content or media words like \"blog\", \"article\", \"news\", \"FAQ\", \"event\", \"product page\", \"image\", \"logo\", \"icon\", \"photo\", \"banner\", \"audio\", \"video\", \"document\". Also use for requests that mix both, like \"reuse existing assets\" for a page. Routes each intent to the correct sub-workflow — structured content search or media search — and can run both in the same request. Does not apply when the request is to generate NEW content or images from scratch, define content type schemas, or apply brand guidelines."
+metadata:
+  version: "1.0"
+  domains: ["Experience"]
+  relatedSkills:
+    - "experience-cms-brand-apply"
+    - "experience-cms-content-generate"
+    - "experience-cms-content-render"
+    - "experience-cms-content-type-generate"
+  mcpTools:
+    content-readonly:
+      tools:
+        - get_content_types_for_workspace
+        - search_content_cms_channels
+        - search_electronic_media
+        - search_media_cms_channels
+      semver: ">=1.0.0"
+    metadata-grounding:
+      tools:
+        - query_metadata
+        - search_metadata
+      semver: ">=1.0.0"
+    skill_bridge:
+      tools:
+        - load_skill
+      semver: ">=1.0.0"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+# Search Coordinator
+
+Routes search requests to the correct sub-workflow — structured CMS content or media — and runs both when a request mixes the two.
+
+**A `→ Read` pointer below is a required action, not FYI** — open that file before continuing past that point; this skill has drifted before from steps followed off memory.
+
+## Scope
+
+**This skill is for SEARCHING FOR existing content or media, not creating new content or images.**
+
+**Use this skill when the user wants to:**
+
+- Search for articles, blog posts, news, FAQs, events, products, or custom content
+- Search for images, logos, icons, photos, graphics, banners, hero images, audio clips, videos, or documents
+- Reuse existing assets instead of creating new ones, or any combination of the above in one request
+
+**DO NOT use this skill when the user wants to:**
+
+- Generate new content (use `experience-cms-content-generate`)
+- Generate new images (use image generation tools)
+- Define content type schemas (use `experience-cms-content-type-generate`)
+- Apply brand guidelines (use `experience-cms-brand-apply`)
+- Create, edit, or publish content records
+
+## Step 1: Determine Channel Scope
+
+**Mandatory on every request that reaches it — never skip straight to Step 2.** No phrasing of the request ("just find me an article," a plain keyword search, etc.) skips this step's local-file scan. If you're about to call `search_metadata` in Step 2 without having scanned for `uiBundles/*/public/content-metadata.json` this turn, STOP and come back here first.
+
+1. **Explicit `channelId` given** — use it directly, skip discovery entirely, proceed to the scope rule below.
+2. **Named uiBundle/app, no `channelId`** — resolve that uiBundle's `channelId`; if it doesn't resolve, fall through to point 3 as if nothing was named.
+3. **Otherwise, discover from the local project** — scan every `uiBundles/*/public/content-metadata.json` file (never gate this on server-side deployment status) and collect the `channelId`s found. Zero → public channels only. Exactly one → public plus that channel. More than one → ask the user which one via `ask_followup_question`.
+
+→ Read `references/scope-resolution.md` § "Step 1 points 1-3" for the full discovery mechanics before acting on points 1-3 above. Proceed to Step 2 once scope is determined.
+
+**Scope rule (applies whether the `channelId` was user-provided or discovered):** scope is always public channels (`contentAccessScope: "Public"`, no `channelIds` field) plus that one `channelId` (a separate call with `channelIds` set to it, no `contentAccessScope` field) — never resolve a separate ID to represent "public," and never send `contentAccessScope` and `channelIds` in the same call. **This scope decides how many search calls Steps 3 and 4 make:** no `channelId` in scope → one search call (public channels only). A `channelId` in scope → two search calls (public channels, then that specific `channelId`), with results merged before presenting.
+
+## Step 2: Determine Content Type and Route
+
+**Precondition: Step 1 must have already run in this turn** (its channel-scope result is what point 5 below carries into Step 3/4). Step 1 runs unconditionally — even for a plain keyword search with no obvious channel angle, not only when the request names a channel or app.
+
+1. **Identify one or more distinct search intents** in the request (e.g. "find a press release about our launch and a hero image for the page" is two intents). Run the rest of this step once per intent.
+
+   **If intents span both routes, sequence the routes — never interleave or merge them:** run the Media Route (Step 4) to full completion for every media intent first, then the Content Route (Step 3) for every content intent. See Step 5.
+2. **Call `search_metadata`** on the `metadata-grounding` MCP server using the intent itself as the query. **No `filters` array support** — `metadataType` is the only narrowing parameter, passed top-level:
+
+   ```javascript
+   search_metadata({ query: "<the user's intent>", metadataType: "ContentTypeBundle", limit: 100 })
+   ```
+
+  Each candidate already includes a full composite identifier (e.g. `00DVW00000CfBQP2A3::0T1VW000008sow60AA::ContentTypeBundle`) — use it as returned; never reconstruct it.
+
+   **Check the outcome before doing anything else:**
+   - **`metadata-grounding` is unavailable (the call errors/times out)** — you MUST call `get_content_types_for_workspace` (the workspace content-type fallback) before any Step 3/4 search tool; do not attempt `query_metadata`, there's nothing to look up, and do not skip straight to a search tool on an assumed FQN.
+   - **Zero candidates returned** — ask the user one clarifying question to narrow the intent (`ask_followup_question`, same question/options as the "intent itself is ambiguous" case at the end of this step), then retry `search_metadata` once with the clarified query:
+     - **Still zero candidates after that one retry** — apply the workspace content-type fallback. Do not ask a second clarifying question.
+     - **One or more candidates on the retry** — continue to point 3.
+   - **One or more candidates on the first call** — continue to point 3.
+
+   **Fallback chain when `search_metadata` doesn't produce a usable candidate list** → Read `references/content-type-discovery.md` before running it: "Workspace content-type fallback" first, then "Wording fallback" as a last resort.
+
+3. **Call `query_metadata`** with each candidate's identifier from point 2 (cap at top 5, batched into one `metadataIdentifiers` array):
+
+   ```javascript
+   query_metadata({ metadataIdentifiers: ["00DVW00000CfBQP2A3::0T1VW000008sow60AA::ContentTypeBundle"] })
+   ```
+
+   Read each entry's `typeDetails[].properties` — `mixins`, `typeClasses`, and `apiName` live there, not in the `search_metadata` response.
+
+4. **Filter for supported types first, THEN decide the route among survivors — do not conflate the two:**
+   - **Discard** any candidate whose `properties.mixins` lacks `sfdc_cms:deliveryApiEnabled` — only delivery-API-enabled types are searchable.
+   - **Of the remainder, discard any whose `properties.typeClasses` lacks `sfdc_cms__structured`.** This is the single "supported for search" gate, not a content/media split — `sfdc_cms__structured` appears on both structured-content types and media types, so it only separates searchable types from unsearchable ones (e.g. `sfdc_cms__email` carries `sfdc_cms__content` but not `sfdc_cms__structured`, and must be discarded).
+   - **Zero survive** — tell the user which types were found but aren't supported, then stop (don't guess a route). **Some, but not all, survive** — tell the user which got filtered out (plain statement, not a question), then continue with survivors. **All survive** — no message needed. → Read `references/content-type-discovery.md` § "Filter-result messages" for exact wording.
+   - **Route on the top-ranked survivor's `properties.typeClasses`** (order returned by `search_metadata`): contains `sfdc_cms__media` → Media Route (Step 4); otherwise → Content Route (Step 3).
+   - **Collect the FQN(s)** — the top-ranked survivor's `properties.apiName`. Add other surviving candidates' FQNs too if clearly relevant to the same intent and sharing the same classification, passing all as one comma-separated `contentTypeFqn` value rather than searching per type.
+5. **Carry the scope from Step 1** (public channels only, or public channels plus a `channelId`) into whichever route is invoked — see the `channelIds` field in each route below.
+
+**If intent itself is ambiguous** (e.g. "find me some content" with no hint of type or subject) → Read `references/content-type-discovery.md` § "Intent itself is ambiguous" for the exact question/options before calling `search_metadata`. Do not guess.
+
+## Step 3: Content Route
+
+Follow this sequence for each intent Step 2 routed here. The content type FQN(s) are already known from Step 2.
+
+1. **Build the search query:**
+   - **Extract keywords** — concrete nouns and named subjects that would appear in the content's title or body. Use domain-specific synonyms, max 10 terms, joined with ` OR `. E.g. "blog posts about sustainable business practices" → `sustainable OR sustainability OR business OR environmental`.
+   - **Extract taxonomies** — descriptive qualities, categories, or topical tags only (adjectives, categories, attributes — not concrete nouns). Stringify as `{"OR": ["term1", "term2"]}`, or `"{}"` if none apply. E.g. "sustainable business practices and environmental responsibility" → `{"OR": ["Business", "Corporate", "Environment", "Responsibility"]}`; "FAQs about password resets" → `"{}"` (no descriptive/categorical terms).
+   - Load `assets/search-payload-template.json` for the request payload structure. Set `contentTypeFqn` to the comma-separated FQN list collected in Step 2. `contentAccessScope` and `channelIds` are **mutually exclusive** — never send both in the same call — so they're set per-call in point 3 below, not here.
+2. **Confirm with the user** — required two-message pattern (labeled-parameters chat message, then `ask_followup_question` with `Yes - search now` / `Edit search` / `Cancel`). Never put the labeled list inside `ask_followup_question`'s text — it strips formatting. → Read `references/content-route.md` § "Confirming the query before searching" for templates.
+3. **Execute the search call(s)** per the scope from Step 1 — one call for public-only scope, two (public + channel-scoped) when a `channelId` is in scope. → Read `references/content-route.md` § "Executing the search call(s)" before parsing results — array/merge rules.
+4. **Present up to 5 unique results total** (de-duplicated by `managedContentKey` for display only — an item found under more than one channel still appears once here), grouped by content type, with a `Load More` option if more remain. Each item shows its **Channel** as a per-item field — never the grouping key:
+
+   ```text
+   I found 3 content items:
+
+   Editorial (c__Editorial):
+   1. <title> — Channel: Public
+   2. <title> — Channel: <uiBundle>
+
+   Blog (sfdc_cms__blog):
+   3. <title> — Channel: Public
+   ```
+
+   Only one content type FQN in scope → the heading may be omitted (still one group); the per-item Channel field is always shown. If an item exists under multiple channels, show its first/primary channel here — the choice between channels happens after selection (point 5), not at presentation time.
+
+5. **User selects** one, several, or all items. **For each selected item whose delivery-details array has more than one entry**, ask which channel's copy to use — one `ask_followup_question` option per entry, named from `managedContentChannelDetails.name` — before displaying its details; items with zero or one entry go straight to display. Show `managedContentId`, `managedContentKey`, `language`, channel, and — only for a `PUBLIC_UNAUTHENTICATED`/`COMMUNITY` entry with a `contentUrl`, never a `WEB_APP` one — the full **Unauthenticated URL** (all query parameters). → Read `references/content-route.md` § "Disambiguating channel at selection" before asking — pass the channel names as `ask_followup_question`'s `options` array, never inline them in the question text.
+6. **If the channelId in scope came from uiBundle discovery** (skip entirely for public-only scope or a user-supplied `channelId` with no uiBundle), offer the `experience-cms-content-render` hand-off using the same two-message pattern, passing each item's `title`, content type FQN, its chosen entry's `managedContentChannelDetails.id` (channel ID) **only when it has a delivery entry — omit for a zero-entry item, never a placeholder**, and either its Unauthenticated URL or, if absent, its `managedContentKey` **as `contentKey`** (the receiving skill's field name). → Read `references/content-route.md` § "Offering the render hand-off" for the full procedure.
+
+→ Read `references/content-route.md` for the complete end-to-end worked example.
+
+## Step 4: Media Route
+
+Follow this sequence for each intent Step 2 routed here. The media content type FQN (e.g. `sfdc_cms__image`, `sfdc_cms__audio`, `sfdc_cms__video`, `sfdc_cms__document`) is already known from Step 2 — never assume it's an image; use whatever FQN Step 2 discovered for this intent.
+
+1. **Present available search sources via `ask_followup_question` — no other tool calls yet.** Only the sources whose tools you actually have (via introspection), plus "Other", each as its own option. Wait for the user's selection before any tool call. → Read `references/media-route.md` § "Presenting available search sources" for the full template.
+2. **Build the query, then confirm with the user before searching — required two-message pattern**, in the same turn:
+   - **Search using keywords** (`search_media_cms_channels`): extract keywords (concrete nouns, max 10 terms) and taxonomies (descriptive/style/mood/category terms — extract every one the query actually contains; don't default to empty just because keywords were found). E.g. "luxury apartment with river view" → keywords `apartment OR villa OR penthouse OR residence`, taxonomies `{"OR": ["Luxury", "Premium", "Waterfront", "Riverside"]}`; "car" → taxonomies `"{}"` (no descriptive terms). Build the payload with `contentTypeFqn` set to the FQN(s) from Step 2, `searchLanguage` set to a locale (`en_US`, `es_MX`, ... — default `en_US`; **required, never null/omitted**), `searchLimit: 5`. → Read `references/media-route.md` for full worked examples.
+   - **Search using Data 360 hybrid search** (`search_electronic_media`) — pass the user's query as-is to `searchQuery`, no extraction needed.
+   - **Other** — ask for a direct URL, asset library path, or specific system to check (no confirmation step, since no tool is called).
+
+   → Read `references/media-route.md` § "Confirming the query before searching" for the confirmation message templates (labeled-parameters chat message, then `ask_followup_question` with `Yes - search now` / `Edit search` / `Cancel`).
+3. **Execute the search call(s)** per the scope from Step 1 — one call for public-only scope, two (public + channel-scoped) when a `channelId` is in scope; Data 360 hybrid search ignores channel scope entirely. → Read `references/media-route.md` § "Executing the search call(s)" before parsing results — array/merge rules.
+4. **Present all unique results via `ask_followup_question`, grouped by content type** — one option per result (de-duplicated by unique identifier for display only — an item found under more than one channel still appears once here), labeled with title, content type, and channel (e.g. `Product Launch Hero Banner (sfdc_cms__image) — Public`). Mirrors the Content Route: content type is the grouping key, channel is a per-item field. Never auto-select.
+5. **User selects** an item. **If its delivery-details array has more than one entry**, ask which channel's copy to use — one option per entry, named from `managedContentChannelDetails.name` — before displaying details. Show Content Name, Content Type, channel, and — only for a `PUBLIC_UNAUTHENTICATED`/`COMMUNITY` entry with a `contentUrl`, never a `WEB_APP` one — the full **Unauthenticated URL** (all query parameters). → Read `references/media-route.md` § "Disambiguating channel at selection" before asking — pass the channel names as `ask_followup_question`'s `options` array, never inline them in the question text.
+6. **Offer the render hand-off** — always, with no uiBundle gating (unlike the Content Route's offer, which only appears when a uiBundle channel was in scope). Same two-message pattern: plain-text mention of the item, then `ask_followup_question` with `Yes` / `No`. On `Yes`, dispatch via `mcp__skill_bridge__load_skill("experience-cms-content-render")` — never the built-in Skill tool (separate registry, returns `Unknown skill`) — passing the selected item's `title`, content type FQN, the chosen entry's `managedContentChannelDetails.id` (channel ID) **only when it has a delivery entry — this route explicitly supports zero-entry items, so omit the channel ID for those rather than reading `.id` off nothing**, and either its Unauthenticated URL or, if absent, its `managedContentKey` **as `contentKey`** (the receiving skill's field name). If the load call fails, tell the user the hand-off failed and stop. On `No`, stop — the search is complete; do not apply the URL yourself as a fallback.
+
+→ Read `references/media-route.md` for the complete worked example.
+
+## Step 5: Present Combined Results
+
+When a request mixes media and content intents, run the two routes **sequentially, each to full completion, not interleaved and not merged into one combined presentation**:
+
+1. **Media Route first** — for every media intent, run Step 4 in full: present sources, build/confirm the query, search, present results, let the user select, and (point 6) offer the `experience-cms-content-render` hand-off (Yes/No). Finish this entire route — including the offer — before starting the Content Route.
+2. **Content Route second** — for every content intent, run Step 3 in full: build/confirm the query, search, present results grouped by content type (channel shown per-item), let the user select, and (point 6) offer the `experience-cms-content-render` hand-off if a uiBundle channel is in scope.
+
+Each route's results are labeled and presented on their own (e.g. "Images:" for the Media Route's output, then "Articles:" for the Content Route's) — never merge the two into one undifferentiated list, and never hold Media Route's results back to present alongside Content Route's.
+
+## Error Handling
+
+| Error | Response |
+|---|---|
+| No `search_content_cms_channels`/`search_media_cms_channels` tools found via introspection | "No content search connection is configured. Please connect a content-readonly MCP server." |
+| Neither media tool available | "No automated media search sources are currently configured. Please provide a direct URL or asset library path." |
+| `metadata-grounding` unavailable or no content types match | Apply the fallback chain in `references/content-type-discovery.md` — do not block or ask for an FQN |
+| No search results (either route) | "No [content/media] found. Try broader keywords, removing descriptive terms, or a different [content type/source]." |
+| Invalid user selection | Re-display options and ask again |
+| Tool returns error (invalid input, missing argument, or otherwise) | Show error message, offer retry with corrected parameters **on that same tool — never fall through to the other route's search tool as a workaround** (see Key Principle 3) |
+| Search tool on the connected server returns a server error (5xx, timeout, connection failure — not "no results") | **Fail the call — do NOT silently retry against a different server.** Tell the user to check that server's connection/session and wait before retrying. |
+
+**Never silently fail on a route the user asked for.** If one route in a mixed request comes up empty, still present the other route's results and say so explicitly. This does not mean substituting a different server when the connected one errors — see the server-error row above.
+
+## Key Principles
+
+1. **Resolve channel scope first** — determine channel scope (Step 1) before any content-type discovery or search
+2. **Search first, route second** — `search_metadata` + `query_metadata` decide the route; fall back to `get_content_types_for_workspace`, then intent wording, only when that comes up empty (Step 2)
+3. **Never cross-route, including on failure** — content requests never hit media search tools and vice versa; if a route's search tool errors for any reason, fix and retry that same tool or stop and report the error — never fall through to the other route's tool as a workaround
+4. **Metadata grounding is mandatory for content** — discover content type FQNs dynamically, never hardcode them
+5. **Media route starts text-only** — present sources and wait before any tool call
+6. **Confirm before searching (both routes)** — user approves query parameters before execution
+7. **Never auto-select** — always wait for user choice, across channel scope and both routes
+8. **Run mixed requests sequentially, Media Route first** — complete it fully (including the render offer) before starting the Content Route; present each route's results as its own labeled set, never merged
+9. **Handle errors gracefully** — clear feedback and alternatives, per route
+10. **Offer to render, don't assume** — both routes require Yes/No confirmation before the hand-off; only the gating differs — Content Route offers it only when a uiBundle channel was actually in scope, Media Route always offers it
+11. **Never fail over to a different server on a server error** — fail the call and tell the user to check that server's session; don't silently retry elsewhere
+12. **Group by content type, never by channel** — in both routes, channel is always a per-item field, never the group heading
+13. **Disambiguate channel at selection, not before** — an item is shown once at presentation regardless of its delivery-details array length; only after selection do you ask which channel's copy to use, one option per entry by `managedContentChannelDetails.name`, in both routes
+14. **Unauthenticated URL is public-channel-only** — `PUBLIC_UNAUTHENTICATED`/`COMMUNITY` entries only; never a `WEB_APP` (uiBundle) entry's `contentUrl`, in either route

package/skills/experience-search-coordinate/assets/search-payload-template.json

@@ -0,0 +1,25 @@
+{
+  "public-channels-call": {
+    "inputs": [{
+      "searchKeyword": "keyword1 OR keyword2 OR keyword3",
+      "taxonomyExpression": "{\"OR\": [\"Taxonomy1\", \"Taxonomy2\"]}",
+      "searchLanguage": "en_US",
+      "contentAccessScope": "Public",
+      "contentTypeFqn": "<discovered-fqn, or a comma-separated list e.g. c__Blog,c__Article>",
+      "pageOffset": 0,
+      "searchLimit": 5
+    }]
+  },
+  "channel-scoped-call": {
+    "inputs": [{
+      "searchKeyword": "keyword1 OR keyword2 OR keyword3",
+      "taxonomyExpression": "{\"OR\": [\"Taxonomy1\", \"Taxonomy2\"]}",
+      "searchLanguage": "en_US",
+      "channelIds": "<the single discovered uiBundle channelId>",
+      "contentTypeFqn": "<discovered-fqn, or a comma-separated list e.g. c__Blog,c__Article>",
+      "pageOffset": 0,
+      "searchLimit": 5
+    }]
+  },
+  "_note": "contentAccessScope and channelIds are mutually exclusive — never send both in the same call. Use contentAccessScope: \"Public\" for the public-channels call (omit channelIds entirely). Use channelIds set to the discovered channelId for the channel-scoped call (omit contentAccessScope entirely). Issue one call per scope in play."
+}

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

@@ -0,0 +1,313 @@
+# Content Route — Full Reference
+
+## Confirming the query before searching
+
+Required two-message pattern, same turn:
+
+**Message 1 (chat-visible plain text — NOT inside `ask_followup_question`):** print the parameters as a labeled list, one field per line:
+
+```text
+I'll search for content with these parameters:
+
+  Content Type: <label> (<fqn>[, <label2> (<fqn2>), ...])
+  Keywords: <keyword1 OR keyword2 OR ...>
+  Taxonomies: <term1, term2, ...>
+  Language: <en_US>
+  Channels: Public[, plus <uiBundle> channel]
+```
+
+**Message 2 (immediately after, same turn):** dispatch `ask_followup_question` with a short question and options — `Yes - search now` / `Edit search` / `Cancel`.
+
+**Never put the labeled list inside `ask_followup_question`'s `question` text.** That UI strips line breaks and formatting, which is exactly what collapses the parameters back into a single paragraph.
+
+## Executing the search call(s)
+
+Per the scope determined in Step 1. `contentAccessScope` and `channelIds` are **mutually exclusive fields — never include both in the same call**:
+- **No `channelId` in scope (public channels only)** — one call to `search_content_cms_channels` with `contentAccessScope: "Public"` and no `channelIds` field at all.
+- **A `channelId` is in scope** — two calls: one with `contentAccessScope: "Public"` and no `channelIds` (public channels), and one with `channelIds` set to the discovered `channelId` and no `contentAccessScope` field at all. Each result item already carries its own list of channel deliveries in `managedContentChannelDeliveryDetails` — this array can hold many entries for a single item (a public-unauthenticated channel, a Community channel, several uiBundle channels, etc. — see the real API response below), independent of how many calls were made. **If the same item (by `managedContentKey`) 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 `managedContentChannelDetails.id`. Presentation (Step 3 point 4) still shows the item once; selection (Step 3 point 5) is where the channel choice actually gets made — see "Disambiguating channel at selection" below.
+
+From each response, parse `outputValues.searchResults[]`, extracting `title`, `contentType`, `managedContentId`, `managedContentKey`, `language`, and the **full `managedContentChannelDeliveryDetails` array** — never just index `[0]`. Each entry pairs a `contentUrl` with `managedContentChannelDetails.{id, name, type}` (the channel it's delivered to). `type` is one of `PUBLIC_UNAUTHENTICATED`, `COMMUNITY`, or `WEB_APP` (a uiBundle-scoped channel — this is what the channel-scoped call in Step 1 discovers). A single item's array can be empty (not yet delivered to any channel — omit the Unauthenticated URL line entirely for that item), have one entry (use it directly, no question needed), or have several (ask which channel — see "Disambiguating channel at selection" below).
+
+**The Unauthenticated URL is public-channel-only.** Only a `PUBLIC_UNAUTHENTICATED` or `COMMUNITY` entry's `contentUrl` is ever shown to the user as the Unauthenticated URL. A `WEB_APP` entry's `contentUrl` is **never** surfaced — omit the URL line entirely when the chosen (or only) entry's type is `WEB_APP`, even though the field is present in the response. This applies after channel disambiguation (below), not before — a `WEB_APP` entry is still offered as a selectable channel option; it just never produces a displayed URL once chosen.
+
+**Real API response — `WEB_APP` (uiBundle) channel, from the channel-scoped call:**
+
+```json
+{
+  "title": "Apple Inc.",
+  "contentType": "c__StockMarket",
+  "managedContentId": "20YVW000001miuD",
+  "managedContentKey": "MCICPC4X5KE5ATHMTN4EYK5DOCYM",
+  "managedContentChannelDeliveryDetails": [
+    {
+      "contentUrl": "https://.../channels/0apVW000000Z25NYAS/contents/20YVW000001miuD?language=en_US",
+      "managedContentChannelDetails": { "id": "0apVW000000Z25N", "name": "testinternalapp", "type": "WEB_APP" }
+    }
+  ]
+}
+```
+
+Even though `contentUrl` is present, this item's only entry is `WEB_APP` — the Unauthenticated URL line is omitted for it. Only `managedContentId`, `managedContentKey`, `language`, and channel (`testinternalapp`) are shown.
+
+**Real API response** (one item, six delivery entries, from a single call — no second channel-scoped call was even involved):
+
+```json
+{
+  "title": "Housing Prices In Japan",
+  "contentType": "sfdc_cms__news",
+  "managedContentKey": "MCVL5CJAB4NBBBRPTMY2N3DALBB4",
+  "managedContentChannelDeliveryDetails": [
+    { "contentUrl": "https://.../0apVW000000TsHxYAK/...", "managedContentChannelDetails": { "id": "0apVW000000TsHx", "name": "Test CMS Channel", "type": "PUBLIC_UNAUTHENTICATED" } },
+    { "contentUrl": "https://.../0apVW000000VUt3YAG/...", "managedContentChannelDetails": { "id": "0apVW000000VUt3", "name": "testLWR", "type": "COMMUNITY" } },
+    { "contentUrl": "https://.../0apVW000000ZYoPYAW/...", "managedContentChannelDetails": { "id": "0apVW000000ZYoP", "name": "Test Channel 2", "type": "PUBLIC_UNAUTHENTICATED" } },
+    { "contentUrl": "https://.../0apVW000000ZYq1YAG/...", "managedContentChannelDetails": { "id": "0apVW000000ZYq1", "name": "Test Channel 3", "type": "PUBLIC_UNAUTHENTICATED" } },
+    { "contentUrl": "https://.../0apVW000000ZYrdYAG/...", "managedContentChannelDetails": { "id": "0apVW000000ZYrd", "name": "Test Channel 4", "type": "PUBLIC_UNAUTHENTICATED" } },
+    { "contentUrl": "https://.../0apVW000000ZYtFYAW/...", "managedContentChannelDetails": { "id": "0apVW000000ZYtF", "name": "Test Channel 5", "type": "PUBLIC_UNAUTHENTICATED" } }
+  ]
+}
+```
+
+The multi-channel case is not "one entry from the public call, one from the channel-scoped call" — it's whatever the array actually contains, however many entries that is.
+
+## Disambiguating channel at selection
+
+Reached at Step 3 point 5, only for a selected item whose (merged, per "Executing the search call(s)" above) `managedContentChannelDeliveryDetails` array has more than one entry. Build one option per entry, using that entry's `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 'Sustainability Report 2024'?"
+options: ["Public", "landing-page"]
+```
+
+Wait for the reply before displaying that item's details, and use the record from the **chosen** entry — never assume entry `[0]` is the right one. An item selected alongside it whose array has zero or one entry does **not** get a question — zero entries goes straight to display with the Unauthenticated URL line omitted; one entry goes straight to display using that entry. Once every multi-entry item in the selection has been resolved (or immediately, if none were), display all selected items' details (Step 7 below).
+
+**Real-world scale** — the "Housing Prices In Japan" response above would produce:
+
+```text
+question: "Which channel would you like to use for 'Housing Prices In Japan'?"
+options: ["Test CMS Channel", "testLWR", "Test Channel 2", "Test Channel 3", "Test Channel 4", "Test Channel 5"]
+```
+
+Ask from the full array every time, however many entries it has — don't special-case it down to "Public vs. the one uiBundle channel." All six names go in the `options` array; the `question` string stays that one short sentence.
+
+**A `WEB_APP` entry is still a valid, selectable option here** — it's excluded only from the Unauthenticated URL line at display time (see "Executing the search call(s)" above), not from the channel choice itself.
+
+## Offering the render hand-off
+
+Only when the channelId in scope came from uiBundle discovery (skip entirely for public-only scope, or a user-supplied `channelId` with no associated uiBundle). Same required two-message pattern as the search confirmation above:
+
+**Message 1 (plain text):**
+
+```text
+I can render the following in the <uiBundle> app:
+
+  1. <title> (<content type label>)
+  2. <title> (<content type label>)
+```
+
+**Message 2 (immediately after):** `ask_followup_question` with options `Yes` / `No`. Never restate the item list or count inside the question text — the question stays generic (`"Render this content in the <uiBundle> app?"`).
+
+- **Yes** — dispatch via `mcp__skill_bridge__load_skill("experience-cms-content-render")` — never the built-in Skill tool (separate registry, returns `Unknown skill`). Pass each selected item's `title`, content type FQN, its chosen entry's `managedContentChannelDetails.id` (channel ID) **only when that item's (merged) `managedContentChannelDeliveryDetails` array has an entry** — use the chosen entry if the array had more than one, or the sole entry if it had exactly one. **An item with zero entries has no entry to read `.id` from — omit the channel ID field 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, so this is safe to leave out. Also pass either its Unauthenticated URL 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 — don't render yourself.
+- **No** — stop; the search is complete.
+
+## Building the search query
+
+Keyword/taxonomy extraction rule: see `SKILL.md` Step 3 point 1 (the Media Route uses the same split — see `media-route.md` for media-specific examples). Additional worked examples for content:
+- "press release about our product launch" → keywords: launch, announcement, release, product launch; taxonomies: Launch, Announcement, News
+- "FAQs about password resets" → keywords: password, reset, login, account; taxonomies: _(empty — no descriptive/categorical terms)_
+
+1. **Determine locale** — format `en_US`, `es_MX`, `fr_FR` (default: `en_US`)
+2. **Build the JSON payload** — `searchKeyword` joins keywords with ` OR `; `taxonomyExpression` is a stringified `{"OR": ["term1", "term2"]}`, or `"{}"` if none.
+
+## Complete End-to-End Example
+
+**User Request:**
+> "I need to find blog posts about sustainable business practices and environmental responsibility for our company website."
+
+---
+
+**Step 1: Determine Search Intent**
+
+Intent parsed:
+- Content type: Blog posts
+- Keywords: sustainable, business, practices, environmental, responsibility
+- Clear intent → proceed to Step 2
+
+---
+
+**Step 2: Discover Content Types**
+
+Call `search_metadata` — this tool has no `filters` array; `metadataType` is the only accepted narrowing parameter:
+```json
+{
+  "query": "blog post article",
+  "metadataType": "ContentTypeBundle",
+  "limit": 100
+}
+```
+
+This returns candidate matches only — no `jsonAttributes`, so routing and delivery-API filtering aren't possible yet. Each candidate already includes a full composite identifier, e.g. `00DVW00000CfBQP2A3::0T1VW000008sow60AA::ContentTypeBundle` (name `sfdc_cms__blog`) among others — use it as returned.
+
+Call `query_metadata` with each candidate's identifier from above, as-is, batched into one `metadataIdentifiers` array:
+```json
+{
+  "metadataIdentifiers": [
+    "00DVW00000CfBQP2A3::0T1VW000008sow60AA::ContentTypeBundle"
+  ]
+}
+```
+
+For each entry, read `typeDetails[].properties` — `mixins`, `typeClasses`, and `apiName` live there. Filter in two steps, **before** deciding content-vs-media routing:
+
+1. Discard any candidate whose `properties.mixins` lacks `sfdc_cms:deliveryApiEnabled`.
+2. Of the remainder, discard any candidate whose `properties.typeClasses` does not contain `sfdc_cms__structured`. **This is a "supported for search" gate, not a content/media split** — `sfdc_cms__structured` is present on both structured-content types (`sfdc_cms__blog`) and media types (`sfdc_cms__image`), so a surviving candidate could still turn out to be either. **`sfdc_cms__content` alone is not sufficient** here — it's a shared parent class for both structured content and media types (e.g. `sfdc_cms__email` has `sfdc_cms__content` in its `typeClasses` but not `sfdc_cms__structured`, and must be discarded, not routed to content search).
+
+Only after this filtering do you inspect the survivors' `typeClasses` again to route: `sfdc_cms__media` present → Media Route (see `media-route.md`); otherwise → Content Route (this file). Rank the content-route survivors.
+
+Result: Found `sfdc_cms__blog` content type (single match here after filtering; if multiple relevant types had matched, e.g. `sfdc_cms__blog` and `c__Article`, they would be passed together as `"sfdc_cms__blog,c__Article"`)
+
+---
+
+**Step 3: Build Search Query**
+
+Extract:
+- Keywords: `sustainable OR sustainability OR environmental OR responsibility OR green OR eco OR carbon`
+- Taxonomies: `{"OR": ["Business", "Corporate", "Environment", "Responsibility"]}`
+- Language: `en_US`
+
+Construct payload (public-channels scope only here — no `channelId` was discovered, so `contentAccessScope` is set and `channelIds` is omitted entirely; the two fields are mutually exclusive):
+```json
+{
+  "inputs": [{
+    "searchKeyword": "sustainable OR sustainability OR environmental OR responsibility OR green OR eco OR carbon",
+    "taxonomyExpression": "{\"OR\": [\"Business\", \"Corporate\", \"Environment\", \"Responsibility\"]}",
+    "searchLanguage": "en_US",
+    "contentAccessScope": "Public",
+    "contentTypeFqn": "sfdc_cms__blog",
+    "pageOffset": 0,
+    "searchLimit": 5
+  }]
+}
+```
+
+---
+
+**Step 4: Confirm Query**
+
+Present to user:
+```text
+I'll search for content with these parameters:
+
+  Content Type: Blog (sfdc_cms__blog)
+  Keywords: sustainable OR sustainability OR environmental OR responsibility OR green OR eco OR carbon
+  Taxonomies: Business, Corporate, Environment, Responsibility
+  Language: en_US
+  Channels: Public
+
+Proceed with this search?
+```
+
+User: "Yes - search now"
+
+---
+
+**Step 5: Execute Search**
+
+Call `search_content_cms_channels` with the payload
+
+---
+
+**Step 6: Present Results**
+
+Results are grouped by content type, with channel shown as a per-item field. This example ran with only one content type FQN (`sfdc_cms__blog`) and public-channels-only scope, so there's only one group and the content-type heading is omitted — but the per-item `Channel:` field is still shown:
+
+```text
+I found 5 content items:
+
+1. Our Journey to Carbon Neutrality
+   Content Type: Blog (sfdc_cms__blog) — Channel: Public
+
+2. Building a Sustainable Supply Chain
+   Content Type: Blog (sfdc_cms__blog) — Channel: Public
+
+3. Renewable Energy: Powering Our Future
+   Content Type: Blog (sfdc_cms__blog) — Channel: Public
+
+4. Green Office Initiatives That Work
+   Content Type: Blog (sfdc_cms__blog) — Channel: Public
+
+5. Sustainability Report 2024
+   Content Type: Blog (sfdc_cms__blog) — Channel: Public
+
+---
+6. Load More (showing 5 of 8)
+7. Done
+
+Select one or more items (e.g., "1, 3" or "all"), Load More, or Done:
+```
+
+If a `landing-page` uiBundle channel had also been in scope and returned hits, the channel would still just be a per-item field — it would NOT create a new group, since content type is the only grouping key. But if a second content type (e.g. `c__Article`) had also matched, results would be grouped and numbered continuously by content type instead, e.g.:
+
+```text
+I found 3 content items:
+
+Blog (sfdc_cms__blog):
+1. Our Journey to Carbon Neutrality — Channel: Public
+2. Internal Sustainability Metrics Q3 — Channel: landing-page
+
+Article (c__Article):
+3. Building a Sustainable Supply Chain — Channel: Public
+```
+
+User: "1, 2, 5"
+
+---
+
+**Step 7: Display Content Details**
+
+```text
+Selected content:
+
+1. Our Journey to Carbon Neutrality
+   Content Type: Blog (sfdc_cms__blog)
+   Channel: Public
+   Content ID: 20YXX000000010
+   Content Key: MCBT7N9K5WX2QPFR4VHD8JLZ6MGY
+   Language: en_US
+   Unauthenticated URL: https://example.my.salesforce-sites.com/blog/carbon-neutrality-journey
+
+2. Building a Sustainable Supply Chain
+   Content Type: Blog (sfdc_cms__blog)
+   Channel: Public
+   Content ID: 20YXX000000011
+   Content Key: MCQJ3P8TK6DWL9XN5VHR2FZ4GBY7
+   Language: en_US
+   Unauthenticated URL: https://example.my.salesforce-sites.com/blog/sustainable-supply-chain
+
+5. Sustainability Report 2024
+   Content Type: Blog (sfdc_cms__blog)
+   Channel: Public
+   Content ID: 20YXX000000014
+   Content Key: MCHZ8P3T7FN5XDWK2QJVR6GMLBY9
+   Language: en_US
+```
+
+Item 5's `managedContentChannelDeliveryDetails` array is empty (not yet delivered to any channel), so its URL line is omitted rather than shown blank. Items 1 and 2 have one entry each, so their URLs are shown in full. (This example's scope was public-channels-only with no `channelId` discovered — see SKILL.md Step 1 — so no item here has more than one delivery entry; for a worked multi-entry disambiguation, see "Disambiguating channel at selection" above.)
+
+---
+
+**Step 8: Offer to Render (only if a uiBundle channel was in scope)**
+
+This example ran with public-channels-only scope (SKILL.md Step 1 found zero uiBundle `channelId`s), so this step is skipped entirely — the results from Step 7 are the final output. If SKILL.md Step 1 had found, say, a `landing-page` uiBundle with a `channelId`, the agent would instead use the same two-message pattern as Step 4's search confirmation — the item list as its own plain-text message, never folded into `ask_followup_question`'s question text:
+
+**Message 1 (plain chat text):**
+
+```text
+I can render the following in the landing-page app:
+
+  1. Our Journey to Carbon Neutrality (Blog)
+  2. Building a Sustainable Supply Chain (Blog)
+```
+
+**Message 2 (immediately after):** `ask_followup_question` with the question `"Render this content in the landing-page app?"` and options `Yes` / `No`. Note the question stays generic — it does NOT restate "these two items" or the count; that's exactly the kind of detail Message 1's list already carries, and stuffing it into the question text is the failure mode this pattern avoids (same reasoning as Step 4's search-confirmation message, which strips line breaks/formatting from anything placed inside `ask_followup_question`).
+
+On `Yes`, dispatch delegation via `mcp__skill_bridge__load_skill("experience-cms-content-render")` — never the built-in Skill tool, which doesn't know about MCP-bridge skills and returns `Unknown skill`. Pass each selected item's `title`, content type FQN (e.g. `sfdc_cms__blog`), and its chosen entry's channel ID (`managedContentChannelDetails.id`, e.g. `0apVW000000TsHx`) **when it has one** — items 1 and 2 above each have exactly one entry, so their channel ID is included; item 5 has zero entries (empty `managedContentChannelDeliveryDetails`), so its channel ID is omitted entirely rather than read off a nonexistent entry. Also pass either its Unauthenticated URL (item 1/2 above) or, when absent, its `managedContentKey` renamed to `contentKey` (item 5 above) — the receiving skill's `SKILL.md` names this field `contentKey`. If the load call fails, tell the user the hand-off failed and stop — do not attempt the render yourself.