@salesforce/afv-skills 1.41.0 → 1.43.0

package/skills/experience-cms-content-generate/assets/questions.md

@@ -0,0 +1,241 @@
+# `ask_user_tool` question templates
+
+Every user question in the workflow MUST be dispatched via `ask_user_tool` (never printed as plain text). Copy-paste the template for the step you're on and fill in placeholders. Follow the two-part pattern from `references/ux-rules.md` when the question needs a list, table, or error detail — print structure in chat text FIRST, then call `ask_user_tool` with a single short question.
+
+**Dispatch every `question` string VERBATIM — it is final copy, not a draft to reformat.** The `question` field renders as ONE plain paragraph: markdown is NOT interpreted, so `**bold**` prints the literal asterisks and a `-`/`1.` list collapses into run-on text. Do NOT expand a templated sentence into bullet lines, numbered lists, or bolded labels inside `question`. If you catch yourself turning `Provide the ID (Content Space IDs start with \`0Zu\`; Folder IDs start with \`9Pu\`)` into `- **Content Space ID** (0Zu…) - **Folder ID** (9Pu…)`, STOP — that reformatting IS the rendering bug users report. Any structure (tables, lists, bold) belongs ONLY in a chat-text Part 1 printed before the tool call, never in `question`.
+
+## Step 0-U / Step 0-P — Identifier ask (no ID supplied)
+
+**Shared by BOTH the UPDATE direct-entry (Step 0-U) and PUBLISH direct-entry (Step 0-P) gates.** Dispatch this the instant the gate stops for a name-only request (user named the content by title/subject with no ID and it is not in the session registry). This is the ONLY template for the identifier ask — do NOT hand-write your own sentence, do NOT split the accepted-ID list into `- **Content Key**…` bullets (that is the literal-asterisk render users report), and do NOT vary the answer set between update and publish. Dispatch the `question` string VERBATIM and use these exact answers every time:
+
+```text
+Tool: ask_user_tool
+question: "Which record should I work with? Paste the content key (starts with `MC`), the Managed Content ID (starts with `20Y`), or the Variant ID (starts with `9Ps`)."
+answers: ["Cancel"]
+```
+
+The user types/pastes the identifier as free text; the single `Cancel` option lets them abort. On `Cancel`, print `Session ended.` and stop. On a pasted identifier, resolve it per `references/identifier-resolution.md` (Step 0-U → Step 8c; Step 0-P → Step 9b). Same wording, same one-option answer set on both paths — that consistency is the point.
+
+## Step 1 — Multi-type disambiguation (prompt spans ≥2 distinct content types)
+
+**Dispatch ONLY when Step 1's multi-type gate fires** (the one prompt spans two or more distinct content TYPES — different content domains, NOT multiple topics/records of one type; detection rule + examples → `references/content-type-classification.md` § Multi-type gate). This is the one question Step 1 may raise. Dispatch the `question` string VERBATIM — it is fixed copy, identical every run; the only thing that varies is the answer set. Do NOT reword it, do NOT stuff the domain descriptions into `question`.
+
+```text
+Tool: ask_user_tool
+question: "Your request covers more than one kind of content. I create one content type per run — which should I create now?"
+answers: ["<domain 1>", "<domain 2>", ..., "Cancel"]
+```
+
+One answer per distinct content domain, labeled from the user's OWN words (e.g. `"Grooming packages"`, `"Service area coverage"`), plus a final `"Cancel"`. On a domain pick: carry ONLY that domain forward as `intent` into Step 2 (the other domains are dropped this run — Step 10's "Create more content" lets the user create the next one). On `Cancel`: print `Session ended.` and stop.
+
+## Step 2 — Bucket 3 FQN correction proposal
+
+**When the user's content-type token is FQN-ish but the correction has more than one reasonable interpretation** (bare name without namespace, case correction, unknown namespace). Print chat text FIRST describing the ambiguity if useful, then:
+
+```text
+Tool: ask_user_tool
+question: "You provided `<original>` — this doesn't match a valid FQN format. Would you like to proceed with `<corrected>` as the content type?"
+answers: ["Yes, use <corrected>", "Let me provide a different FQN", "Cancel"]
+```
+
+Replace `<original>` and `<corrected>` with the actual literal strings. Do NOT dispatch this prompt for Bucket 2 (high-confidence near-miss) — Bucket 2 announces the correction in chat text and proceeds without a confirmation turn.
+
+**Follow-up when the user selects "Let me provide a different FQN":**
+
+```text
+Tool: ask_user_tool
+question: "Please provide the content type FQN in `namespace__DeveloperName` format (e.g. `c__BlogPost`, `sfdc_cms__news`)."
+```
+
+On the returned string, restart Step 2 classification from Bucket 1 (treat the new input as a fresh capture).
+
+## Step 3 — Workspace resolution (Question 1)
+
+**When local UIBundles were found:**
+
+```text
+Tool: ask_user_tool
+question: "Where should I create the content? Pick a local UIBundle (I'll resolve the space automatically) or provide an ID manually."
+answers: ["<masterLabel1> (<developerName1>)", "<masterLabel2> (<developerName2>)", ..., "Provide a space or folder ID manually"]
+```
+
+One entry per discovered UIBundle formatted as `"<masterLabel> (<developerName>)"`, plus a final `"Provide a space or folder ID manually"` option.
+
+**When no local UIBundles were found:**
+
+```text
+Tool: ask_user_tool
+question: "Which content space or folder should I create the content in? Provide the ID (Content Space IDs start with `0Zu`; Folder IDs start with `9Pu`)."
+answers: ["Cancel"]
+```
+
+The user types/pastes the ID as free text; the single `Cancel` option lets them abort. On `Cancel`, print `Session ended.` and stop (Principle 7).
+
+**When the user picks "Provide a space or folder ID manually":**
+
+```text
+Tool: ask_user_tool
+question: "Please enter the Content Space or Folder ID (Content Space IDs start with `0Zu`; Folder IDs start with `9Pu`)."
+answers: ["Go back"]
+```
+
+**Do NOT invent placeholder tokens.** Emit the exact prefixes above (`0Zu`, `9Pu`) — do NOT fabricate patterns like `0pdXXX...` or `0apXXX...`. The screenshot regression showing `0pdXXXXXXXXXXXXX` / `0apXXXXXXXXXXXXX` was hallucinated ID prefixes that never appear in Salesforce content-space or folder IDs. When in doubt about a Salesforce ID prefix, do NOT guess — the two above are the only ones this skill supports.
+
+If the user clicks "Go back", re-present the original Step 3 question with all UIBundle options.
+
+**Invalid workspace ID — re-ask (format-gate fail OR server-confirmation fail).** Dispatch this the instant a manual ID fails validation: either it wasn't a 15/18-char `0Zu`/`9Pu` ID (Layer 1), or the first server call touching it returned invalid/not-found (Layer 2, incl. the sibling's `get_content_types_for_workspace` on the delegation path). This is the ONLY re-ask after a bad ID — it MUST state the ID was invalid (the neutral manual-ID prompt above does NOT; using it here is the reported "not even saying invalid" defect). Print the raw server error as chat text FIRST when Layer 2 failed, then dispatch VERBATIM, filling `<reason>`:
+
+```text
+Tool: ask_user_tool
+question: "That ID wasn't valid — <reason>. Enter a Content Space ID (starts with `0Zu`) or Folder ID (starts with `9Pu`) — must be 15 or 18 characters."
+answers: ["Cancel"]
+```
+
+`<reason>` is one of: `it wasn't a 15- or 18-character 0Zu/9Pu ID` (Layer 1 format-gate fail) OR the server error text verbatim (Layer 2 fail). On `Cancel`, print `Session ended.` and stop. Do NOT improvise an org picker or run `sf org list` (see `references/workspace-resolution.md`).
+
+**When `get_or_create_cms_workspace_and_web_app_channel` fails for the selected UIBundle:**
+
+```text
+Tool: ask_user_tool
+question: "Could not resolve space for this UIBundle. How would you like to proceed?"
+answers: ["Retry", "Pick a different option", "Provide a space or folder ID manually"]
+```
+
+## Step 4.B.2 — Bulk topic approval
+
+Print the topic list as formatted chat text FIRST (numbered markdown list with title + prompt), then call:
+
+```text
+Tool: ask_user_tool
+question: "Do these topics look good?"
+answers: ["Looks good, create them", "Let me adjust"]
+```
+
+Never stuff the topic list into the `question` field — it renders as an unreadable paragraph.
+
+## Step 5a — Bulk pre-dispatch blanket approval
+
+Print `Ready to create all <N> content items in your org. Proceed?` as chat text, then:
+
+```text
+Tool: ask_user_tool
+question: "Create all <N> items now?"
+answers: ["Yes, create all", "Cancel"]
+```
+
+**Do not leak dispatch mechanics.** The user asked for N content items — they see "N items." Do NOT mention parallel calls, `create_cms_content`, or the tool id in either the chat text or the `ask_user_tool` question. `"Approve all <N> create_cms_content calls?"` and `"Ready to dispatch 7 parallel create_cms_content calls to your org. Proceed?"` are both regressions — the user sees `create_cms_content` and the dispatch fan-out, both of which are internal implementation. Say `Create all 7 items now?` — NOT `Approve all 7 create_cms_content calls?`, NOT `Ready to dispatch 7 parallel create_cms_content calls`.
+
+## Step 7 — Post-action loop
+
+**Single content:**
+
+```text
+Tool: ask_user_tool
+question: "What would you like to do next?"
+answers: ["Edit content", "Publish content", "End session"]
+```
+
+**Bulk content:**
+
+```text
+Tool: ask_user_tool
+question: "What would you like to do next?"
+answers: ["Edit content", "Publish all", "Publish subset", "End session"]
+```
+
+**Publish subset — item selection:**
+
+```text
+Tool: ask_user_tool
+question: "Which item numbers would you like to publish? (e.g. 1, 3, 5)"
+```
+
+## Step 8a — Edit scope
+
+**Bulk edit scope:**
+
+```text
+Tool: ask_user_tool
+question: "Which content would you like to edit?"
+answers: ["All items", "Specific items (by number)", "Cancel"]
+```
+
+**Specific-items follow-up:**
+
+```text
+Tool: ask_user_tool
+question: "Which item numbers would you like to edit? (e.g. 1, 3)"
+```
+
+## Step 8b — Edit instructions
+
+Free-text, and **multiple properties can be changed in one message** — the server-side pipeline reads the whole instruction and applies every change against the existing body in a single `update_cms_content_variant` call. The user does not pick fields one at a time.
+
+If the current content body was just displayed (Step 0-U direct-entry, or Step 6 after a prior edit), the user can name fields from it. Dispatch:
+
+```text
+Tool: ask_user_tool
+question: "What would you like to change? Describe all edits in one message — you can update several fields at once (e.g. 'shorten the description, change the title to X, and add a note about Y')."
+```
+
+Do NOT loop field-by-field and do NOT restrict the user to a single property — one free-text instruction covering any number of properties is the expected input.
+
+## Retry prompts
+
+**Bulk create/update/publish partial failure — after printing failed items with prompts and errors as chat text:**
+
+```text
+Tool: ask_user_tool
+question: "How would you like to proceed?"
+answers: ["Retry failed items", "Skip and continue", "End session"]
+```
+
+**Total failure:**
+
+```text
+Tool: ask_user_tool
+question: "How would you like to proceed?"
+answers: ["Retry all", "End session"]
+```
+
+**Total failure — uniform error (Guard A from `references/error-recovery.md`).** Dispatch this variant ONLY when every one of the N failed calls returned the same error signature — the retry option is deliberately hidden because the failure is systemic. Print the uniform-error chat text from `error-recovery.md` FIRST, then:
+
+```text
+Tool: ask_user_tool
+question: "How would you like to proceed?"
+answers: ["End session"]
+```
+
+**Total failure — retry exhausted (Guard B from `references/error-recovery.md`).** Dispatch this variant ONLY on the 3rd+ consecutive total failure of the same bulk-operation instance — the retry option is deliberately hidden after two failed attempts. Print chat text FIRST: `<N> items have failed on <retryCount> consecutive attempts. Ending the session — resolve the underlying issue and re-run.` Then:
+
+```text
+Tool: ask_user_tool
+question: "How would you like to proceed?"
+answers: ["End session"]
+```
+
+## Step 10 — Post-publish
+
+**`workspaceMethod=uibundle` — replace `<masterLabel>` and `<developerName>` with the actual values selected in Step 3:**
+
+```text
+Tool: ask_user_tool
+question: "Content published! What would you like to do next?"
+answers: ["Create more content", "Render it to the UI Bundle (<masterLabel> (<developerName>))", "End session"]
+```
+
+**`workspaceMethod=manual` — no UIBundle was selected in Step 3, so no `channelId` is available for the render handoff. Print this one-liner as chat text FIRST so the user knows why the Render option is missing, then dispatch the prompt:**
+
+Chat text (Part 1):
+
+```text
+Rendering to a UI Bundle requires a UIBundle selection at the workspace step, which resolves the channel automatically. This run used a folder ID directly — to render the content, re-run this skill and pick a UIBundle at Step 3.
+```
+
+Prompt (Part 2):
+
+```text
+Tool: ask_user_tool
+question: "Content published! What would you like to do next?"
+answers: ["Create more content", "End session"]
+```

package/skills/experience-cms-content-generate/examples/create-content-call.md

@@ -0,0 +1,81 @@
+# Example `create_cms_content` payload
+
+> **Read this first.** `sfdc_cms__article` and `0ZuKZ00000XXXXXXXX` below are **shape illustrations**, not defaults. The `contentType` FQN must come from `experience-cms-content-type-generate` against the live org — never copy the FQN from this file. The `contentSpaceOrFolderId` value comes from the user's answer to the Step 3 workspace question — never from a local file. A workspace will reject any type it isn't configured to support, so picking an FQN from training data or this example will fail with `"These content type(s) X are not supported by this space"`.
+
+The `experience-cms-content-generate` skill dispatches `create_cms_content` with the user's goal on the **`prompt` channel**. The server-side pipeline (Vibes MC content pipeline) generates and validates the body against the type's schema. The agent generates only the `title` and shapes the payload.
+
+## Example
+
+User asked: *"Draft an article announcing our Q4 product launch — make it about the new analytics dashboard. Cover the problem it solves, three headline features (real-time KPIs, drill-down by segment, export to spreadsheet), availability date, and a call-to-action linking to the product page."*
+
+Assume `experience-cms-content-type-generate` returned `contentTypeFqn: sfdc_cms__article`.
+
+Agent generates only a title from `[USER GOAL]`:
+
+- **Title:** `Q4 Launch — Analytics Dashboard`
+
+Payload:
+
+```json
+{
+  "inputs": [
+    {
+      "contentType": "sfdc_cms__article",
+      "contentSpaceOrFolderId": "0ZuKZ00000XXXXXXXX",
+      "title": "Q4 Launch — Analytics Dashboard",
+      "prompt": "Draft an article announcing our Q4 product launch — make it about the new analytics dashboard. Cover the problem it solves, three headline features (real-time KPIs, drill-down by segment, export to spreadsheet), availability date, and a call-to-action linking to the product page."
+    }
+  ]
+}
+```
+
+Notes:
+
+- **`title` reflects `[USER GOAL]`.** Not the user's message verbatim — the message was an authoring instruction, not a title.
+- **`prompt` is `[USER GOAL]` verbatim.** Do not paraphrase, trim, or reformat — the server-side pipeline parses it directly.
+- **No `contentBody` field.** `prompt` and `contentBody` are mutually exclusive; sending both fails. This skill never sends `contentBody`.
+- **No client-side pre-flight validation.** The server owns validation.
+- Single-element `inputs` array — the skill creates one record per element. **Bulk creation dispatches N separate `create_cms_content` calls in parallel, each with a 1-element `inputs` array** — one call per item is the hard rule (never combine items into a multi-element `inputs` array). See SKILL.md Step 5b and `references/bulk-batching.md`.
+
+### Optional fields
+
+These pass through only when the user explicitly named them:
+
+```json
+{
+  "inputs": [
+    {
+      "contentType": "<from-sibling>",
+      "contentSpaceOrFolderId": "<from-user-step-3>",
+      "title": "<agent-generated>",
+      "prompt": "<[USER GOAL] verbatim>",
+      "urlName": "q4-launch-analytics-dashboard"
+    }
+  ]
+}
+```
+
+### Successful response (abridged)
+
+```json
+{
+  "outputs": [
+    {
+      "managedContentId": "20YKZ00000XXXXXXXX",
+      "managedContentVersionId": "20XKZ00000XXXXXXXX",
+      "managedContentVariantId": "20ZKZ00000XXXXXXXX",
+      "contentKey": "MCRT_a1B2c3D4",
+      "contentFqn": "sfdc_cms__article",
+      "title": "Q4 Launch — Analytics Dashboard",
+      "urlName": "q4-launch-analytics-dashboard",
+      "apiName": "Q4_Launch_Analytics_Dashboard",
+      "contentSpace": { "id": "0ZuKZ00000XXXXXXXX", "label": "Marketing" },
+      "createdBy":    { "id": "005KZ00000XXXXXXXX", "name": "Jane Doe" },
+      "createdDate":  "2026-11-01T17:42:08.000Z",
+      "contentBody":  { "title": "Q4 Launch — Analytics Dashboard", "body": "<h2>…</h2>", "excerpt": "…" }
+    }
+  ]
+}
+```
+
+The skill surfaces (at minimum) `title`, `contentKey`, `managedContentId`, `contentFqn`, and `contentSpace.label` — those are what the user needs to find the record again. Response latency is server-side-generation dependent — not guaranteed sub-second like a pure persist path.

package/skills/experience-cms-content-generate/references/bulk-batching.md

@@ -0,0 +1,56 @@
+# Bulk Dispatch Rules — `create_cms_content` / `update_cms_content_variant`
+
+Single source of truth for how bulk operations are dispatched. Referenced from SKILL.md Step 5b.
+
+## The rule in one sentence — HARD RULE
+
+**Dispatch exactly ONE `create_cms_content` call per item, with a 1-element `inputs` array, and fan out all N calls in parallel in a single turn.** No exceptions, no thresholds, no batching, no grouping.
+
+This applies for every N ≥ 1. Single content (N=1) is one call; bulk (N ≥ 2) is N calls, dispatched in parallel.
+
+## Why one-call-per-item
+
+- **Matches the server-side generation model.** Each `create_cms_content` runs the Vibes MC content pipeline for one record; keeping calls 1:1 with records means one server-side generation per wire call, which is how the pipeline is tuned.
+- **Bounded blast radius = 1.** A dropped connection loses exactly one record. Retry is trivial — the same 1-element payload, redispatched.
+- **Trivial partial-failure handling.** Each call's success or failure is independent and known individually. No need to walk an `outputs` array or reconcile which sub-item failed.
+- **Simpler mental model for the skill.** No batch-size math, no balancing, no re-batching on retry.
+
+## Do NOT
+
+- **Do NOT put more than one element in `inputs`.** Even for N=2, do NOT send one `create_cms_content` with a 2-element `inputs` array. Every call is exactly one element.
+- **Do NOT serialize.** For N ≥ 2, dispatch all N calls in the same turn in parallel — do not dispatch call 1, await, then dispatch call 2. Serialization defeats the parallelism this rule enables.
+- **Do NOT batch on retry.** If items 3 and 7 failed, retry them as two separate parallel 1-element calls — never combine into a single 2-element `inputs` array.
+- **Do NOT mention dispatch mechanics to the user.** The user asked for N content items — they see "N items." Do NOT mention parallel calls, `create_cms_content`, or the tool id. Say `Ready to create 7 items` — NOT `Ready to dispatch 7 parallel create_cms_content calls`.
+- **Do NOT narrate tool preparation.** If the runtime lazy-loads `create_cms_content` at dispatch time, do the tool-schema fetch inside the same turn as 5b — no `"Let me load the content creation tool"`, no `"Loading tool schema"`, no `"Fetching create_cms_content"`. The user should see the dispatched results, not the plumbing that got you there.
+
+## Same shape applies to `update_cms_content_variant`
+
+Bulk edits (Step 8d) follow the same rule: one `update_cms_content_variant` call per selected item, 1-element `inputs`, all N dispatched in parallel. Each call carries its own `variantId` + its own `prompt`.
+
+## Bulk topic generation + approval (Step 4, quantity > 1)
+
+Referenced from SKILL.md Step 4 "Bulk Content". Runs before the parallel dispatch above.
+
+**4.B.1. Generate topic prompts.** Generate N distinct topic prompts (N = explicit count, or 4–5 if unspecified), each a unique angle within the user's domain.
+
+**4.B.2. Present topics for approval — TWO-PART output.**
+
+Part 1 — print the topic list as formatted chat text (markdown) so line breaks and numbering render:
+
+```markdown
+I'll create **<N>** content items of type `<FQN>`. Here are the topics:
+
+1. **<short title 1>** — <topic prompt 1>
+2. **<short title 2>** — <topic prompt 2>
+3. **<short title 3>** — <topic prompt 3>
+
+You can approve as-is, remove items by number, add new topics, or rewrite any prompt.
+```
+
+Part 2 — immediately after the text, dispatch the Step 4.B.2 approval prompt from `assets/questions.md`. Never put the full topic list inside the `ask_user_tool` question (see `references/ux-rules.md`).
+
+**4.B.3. Handle response.**
+- `Looks good, create them` → proceed to 4.B.4 with the listed prompts.
+- `Let me adjust` → wait for the user's modifications (remove / add / rewrite), then re-present the final list for a single confirmation. Do NOT loop more than once — after the second presentation, proceed with whatever the user confirms.
+
+**4.B.4. Prepare N single-item payloads.** Use `assets/payloads/create-content-bulk.json` as the per-call shape — build N independent 1-element `inputs` payloads (one per approved topic). All share the same `contentType` and `contentSpaceOrFolderId`; each carries its own `title` (agent-generated for that topic) and `prompt` (that topic's approved prompt verbatim). Step 5b dispatches those N calls in parallel per the HARD RULE above.

package/skills/experience-cms-content-generate/references/content-type-classification.md

@@ -0,0 +1,88 @@
+# Step 2 — content-type classification buckets (full detail)
+
+Step 2 classifies Step 1's captured content-type reference into one of four buckets. Buckets 1/2/3 are fast-paths (skip the sibling); Bucket 4 delegates.
+
+## Bucket 1 — Exact FQN
+
+Token matches `^[a-zA-Z_][a-zA-Z0-9_]*__[A-Za-z][A-Za-z0-9_]*$` exactly (e.g. `c__BlogPost`, `sfdc_cms__news`, `my_ns__CustomerStory`). Capture `contentTypeFqn = "<user's token>"` and go directly to Step 3. **Silent — no chat text, no confirmation prompt.**
+
+## Bucket 2 — High-confidence auto-correctable near-miss
+
+Token is a clear FQN with a mechanical typo where the correction is unambiguous — exactly one reasonable interpretation. Detection: **single-underscore separator between a recognizable namespace and a developer name.** Recognizable namespaces = `c` (default custom), `sfdc_cms` (standard CMS), or any namespace-prefix pattern matching `^[a-z][a-z0-9_]{0,14}$` where the segment before the single underscore looks like a namespace identifier and the segment after starts with an alphabetic character. Correction: replace the single underscore between namespace and developer name with `__`. Qualifies: `c_news`, `sfdc_cms_news`, `myns_BlogPost`. Does NOT qualify: `blog_post` (both segments look like developer-name words), `news_article_topic` (three-segment, no confident split).
+
+Auto-correct silently, then **announce in chat text**: `You provided \`<original>\` — this isn't a valid FQN format. Proceeding with \`<corrected>\` as the content type. If this isn't right, cancel and re-run with the correct FQN.` Then go directly to Step 3 with `contentTypeFqn = "<corrected>"`. **Do NOT dispatch an `ask_user_tool` prompt for Bucket 2** — single-answer mechanical correction; asking wastes a turn.
+
+## Bucket 3 — Medium/low-confidence FQN-ish token
+
+Token looks like a naming attempt but has more than one reasonable interpretation. Falls into Bucket 3 if any of the following is true AND it is not already Bucket 1 or 2:
+
+- **Bare developer name with no namespace** (e.g. `BlogPost`, `News`, `PressRelease`) — could be `c__BlogPost` or `<managed>__BlogPost`. Default proposal: prepend `c__`.
+- **Unknown namespace with a single-underscore separator** where the left segment doesn't obviously match a namespace pattern (e.g. `foobar_thing`). Propose the double-underscore version; user confirms.
+
+**Case does NOT trigger Bucket 3.** Salesforce API names — including ContentTypeBundle FQNs — are case-insensitive at lookup, so `c__BlogPost`, `C__blogpost`, `c__BLOGPOST` all resolve to the same record. Any token matching the Bucket 1 regex is Bucket 1 — do NOT propose a "case correction" via Bucket 3 (it would burn an `ask_user_tool` turn for zero functional effect).
+
+For Bucket 3, dispatch the **Step 2 FQN-correction prompt** from `assets/questions.md` (`Yes, use <corrected>` / `Let me provide a different FQN` / `Cancel`). Route:
+
+- `Yes, use <corrected>` → capture `contentTypeFqn = "<corrected>"`, go to Step 3.
+- `Let me provide a different FQN` → dispatch the follow-up "provide FQN" prompt from `assets/questions.md`. On the returned string, restart Step 2 classification from Bucket 1 (treat as a fresh Step 1 capture).
+- `Cancel` → **STOP silently.** Print `Session ended.` and exit.
+
+## Invalid-FQN gate — a token that MEANT to be an FQN but is malformed
+
+Before falling to Bucket 4, catch a token the user clearly intended as an FQN (contains `__`, or a namespace-style `<seg>__<seg>` shape) but which does NOT match the Bucket 1 regex and is NOT a Bucket 2 single-underscore near-miss — e.g. `c__` (empty developer name), `__BlogPost` (empty namespace), `c__Blog Post` (space in name), `c__123` (developer name starts with a digit), `c____Post` (doubled separator). These are broken FQNs, not natural-language phrases — do NOT silently delegate them to the sibling as free text (the sibling would treat the garbage as a search phrase). Instead dispatch the **Step 2 FQN-correction prompt** from `assets/questions.md`: show the invalid token, offer `Let me provide a different FQN` and `Cancel` (omit a "use `<corrected>`" option when there is no confident single correction). On `Let me provide a different FQN`, dispatch the follow-up "provide FQN" prompt and restart Step 2 from Bucket 1 on the new string. A token with NO FQN punctuation at all (`blog post`, `news article`) is genuine natural language → Bucket 4, not this gate.
+
+## Bucket 4 — Natural-language type name or no token
+
+Token is a free-text phrase (`"blog post"`, `"news article"`, `"customer story"`) or Step 1 captured no content-type reference at all. Delegate to `experience-cms-content-type-generate` — proceed to Step 2a.
+
+## Fast-path invariants (Buckets 1, 2, 3)
+
+Once a fast-path bucket captured the FQN, do NOT: verify it exists in the org (the `INVALID_TYPE` response at Step 5 IS the verification), delegate to the sibling (the FQN IS the answer), scan `contentTypes/` locally, dispatch `metadata-grounding.search_metadata`, run `sf project retrieve start`, or read `schema.json` from disk. If the FQN doesn't resolve, `create_cms_content` fails with `INVALID_TYPE` — see `references/error-recovery.md`.
+
+## Multi-type gate (Step 1 — fires BEFORE classification)
+
+A single prompt sometimes names **two or more distinct content TYPES** (e.g. `Create content covering the grooming packages and the service area coverage` → a grooming-package type AND a service-area type). This skill resolves **one content type per run** — the delegation contract passes ONE `intent` and consumes ONE `{status, fqn}`. Attempting to resolve two types in one run is sequencing drift (the sibling emits one outcome; a second in-turn resolution corrupts its state machine). So when the prompt spans multiple types, ask the user to pick ONE before Step 2.
+
+**TRIGGER (ask) — the prompt maps to ≥2 distinct content types.** Judge by content domain, not word count. Distinct domains that would each be their own `ContentTypeBundle`:
+
+- `grooming packages` **and** `service area coverage` → grooming-service type + service-area type → **ASK**
+- `a product page and an FAQ` → product type + FAQ type → **ASK**
+- `event details plus a press release` → event type + press-release type → **ASK**
+
+**DO NOT trigger (stay silent — existing paths) — one type, no matter the topic/quantity count:**
+
+- `5 blog posts about our launch` → ONE type (blog), bulk of 5 records → silent, existing bulk path
+- `a blog about cheese and wine` → ONE type (blog), two subjects in one record/topic set → silent
+- `news articles on X, Y, and Z` → ONE type (news), three topics → silent (bulk topic generation owns this)
+- any single-domain prompt → silent
+- FQN provided (Buckets 1/2/3) → the fast-path already fixed the type; the gate does NOT run
+
+**The distinction:** multiple *content types* → ASK; multiple *topics/records of one type* → silent (bulk owns it). If unsure whether two domains are really different types, prefer to ASK — a false ask costs one extra turn; a false silence resurfaces the two-types-in-one-run drift.
+
+**On the pick:** carry ONLY the chosen domain forward as the `intent` into Step 2 (all downstream steps — classification, delegation, create — see exactly one domain, so every existing invariant holds unchanged). The dropped domain(s) are NOT lost — Step 10's post-publish "Create more content" lets the user create the next type in a fresh run. Question template (fixed copy, verbatim every run) → `assets/questions.md` § Step 1.
+
+**This is the ONLY exception to Step 1's "never ask" rule.** It does NOT reopen the general clarifying-questions regression: it fires solely on the objective ≥2-distinct-types condition, never for goal refinement, mode, body details, "do you have a type in mind?", or quantity. If you are asking anything other than "which of these N distinct types," that is the Step 1 anti-pattern, not this gate.
+
+## What the sibling owns (delegated path only)
+
+When the fast-path does not apply, this skill hands the user's intent to `experience-cms-content-type-generate` and waits for exactly one of four terminal outcomes (`success` / `not_deployed` / `cancelled` / `error`). All of the following are the sibling's job:
+
+- Local `contentTypes/` scan and `metadata-grounding` lookup
+- The user-facing pick question when multiple candidates match
+- Creating a new `ContentTypeBundle` when nothing matches, and asking to deploy it
+- Constructing the namespace-prefixed FQN after a deploy
+- Retrieve-and-reconcile against the org copy, drift resolution
+
+## Drift-safety net (delegated path) — five signals that delegation is broken
+
+The harness cannot enforce delegation between two markdown skills, so treat every one of these as a hard stop and route to Step 2b's `load failed` row instead of doing the sibling's work:
+
+1. Constructing a `search_metadata` query for `ContentTypeBundle` yourself.
+2. Running `find` / `ls` / `cat` (or `Read`) against `contentTypes/`, `schema.json`, or any local content-type-bundle file to answer "what FQN should I use?".
+3. Running `sf project retrieve start` for `ContentTypeBundle` metadata.
+4. Dispatching `create_cms_content` (Step 4+) without a sibling-emitted (or fast-path-captured) `contentTypeFqn` in hand. (Resolving the workspace via `get_or_create_cms_workspace_and_web_app_channel` BEFORE the FQN is expected on the delegation path — that ID is passed to the sibling — and is NOT drift.)
+5. Dispatching `create_cms_content` with an FQN reconstructed from a folder name, a `schema.json` filename, or a local scan result.
+
+If drift #1 has already happened despite this rule, then since the harness cannot enforce delegation, the query construction rules live in a single shared file so the wrong-skill outcome is at least a right query. Read `../experience-cms-content-type-generate/references/discovery-query-rules.md` before emitting any `search_metadata` call. Common bug queries this file exists to prevent: `"CMS content type bundle"`, `"content type bundle"`, `"<domain> content type"` — any query containing the words `content type`, `bundle`, or `CMS` is filler-only and has stripped out the intent.
+
+**Do not** downgrade `not_deployed` to `success` because "the bundle is validated and the FQN is predictable." A local-only bundle is not in the org; `create_cms_content` returns `INVALID_TYPE` and the user sees a confusing error two turns later. Trust the sibling's status verbatim.

package/skills/experience-cms-content-generate/references/content-write-tool.md

@@ -0,0 +1,95 @@
+# `create_cms_content` — content-write MCP tool reference
+
+The CMS content-creation capability is exposed as a tool on the `content-write` MCP server. The canonical tool id is `create_cms_content`; the underlying Connect API operation is `createManagedContent` → `POST /connect/cms/contents`. IDE-specific namespace prefixes vary (e.g. `mcp__content-write__create_cms_content` in some surfaces) — refer to it by capability and the canonical id, not by a single hardcoded full name.
+
+## Authoritative source: the JSON input schema
+
+The tool's prose description sometimes lists `contentBody` and `title` as required. **The JSON input schema is authoritative — the prose is not.** The schema declares only `contentType` and `contentSpaceOrFolderId` as required, and offers two mutually exclusive body channels (`prompt` xor `contentBody`).
+
+**This skill uses the `prompt` channel exclusively for both `create_cms_content` and `update_cms_content_variant`.** The user's goal (create) or edit instruction (update) is passed to the tool as `prompt`; the tool's server-side pipeline (Vibes MC content pipeline) owns generation / edit application and schema validation. The agent generates only the `title` on the create path, and only re-emits `title` on the edit path when the edit clearly targets the title. This skill does not use `contentBody` on any dispatch. `update_cms_content_variant` accepts `prompt` and reads the existing `contentBody` for the target `variantId`; the server applies the edit and persists the result.
+
+## Inputs
+
+The tool accepts an `inputs` array; each element persists one content record. **This skill sends exactly ONE element per call** — for bulk creation of N items, it dispatches N separate `create_cms_content` calls in parallel, each carrying a 1-element `inputs` array. See "Dispatch policy" below.
+
+## Dispatch policy — one call per item, parallel fan-out (HARD RULE)
+
+For any N ≥ 1, dispatch N `create_cms_content` calls, each with a 1-element `inputs` array, all fanned out in parallel in a single turn. Enforced by SKILL.md Step 5b and detailed in `references/bulk-batching.md`.
+
+**Why one call per item:**
+
+- **Matches the server-side generation model.** Each `create_cms_content` runs the Vibes MC content pipeline for one record; 1:1 calls-to-records is how the pipeline is tuned.
+- **Blast radius = 1.** A dropped connection loses exactly one record. Retry is trivial — the same 1-element payload, redispatched.
+- **Trivial partial-failure handling.** Each call's success or failure is independent and known individually.
+- **Simpler mental model.** No batch-size math, no balancing, no re-batching on retry.
+
+**Anti-patterns:**
+
+- Any `inputs` array with more than 1 element — violates the hard rule. Split into N parallel 1-element calls.
+- Serialized calls (dispatch call 1, await, dispatch call 2, …) — defeats the parallelism this rule enables.
+- Combining failed retries into a multi-item `inputs` array — retry each failed item as its own 1-element parallel call.
+
+### Required per element
+
+| Key | Type | Notes |
+|-----|------|-------|
+| `contentType` | string | Fully qualified type name. Standard: `sfdc_cms__article`. Custom: `<namespace>__<TypeName>`, e.g. `c__PressRelease`. The masterLabel is **not** accepted here. The FQN must come from the `experience-cms-content-type-generate` sibling — never copy from this doc. |
+| `contentSpaceOrFolderId` | string | Salesforce ID of the target content space (workspace) or a folder within one. Org-specific — do not reuse across orgs. Always asked from the user (see SKILL.md Step 3). Never inferred from `ui-bundle.json` or any local file. |
+| `title` | string | Agent-generated — reflects `[USER GOAL]`. |
+| `prompt` | string | **The body channel this skill uses.** `[USER GOAL]` verbatim. The server-side pipeline generates and validates the body against the type's schema. Mutually exclusive with `contentBody`. |
+
+### Body channel policy
+
+This skill emits `prompt` only. `contentBody` (caller-supplied JSON body serialized to a string) is a valid tool input but is not used here — the server-side pipeline owns generation quality end-to-end.
+
+**Mutual exclusion.** `prompt` and `contentBody` cannot both be set on the same `inputs[]` element. Sending both fails; sending neither fails.
+
+### Optional per element
+
+| Key | Type | When to set |
+|-----|------|-------------|
+| `urlName` | string | URL-friendly slug within the org. Set when you want a deterministic URL; default to lowercase-kebab-case derived from `title`. |
+| `contentKey` | string | Specific content key to assign. The tool auto-generates one if omitted — prefer omission unless the user has a key in hand. |
+| `externalId` | string | External-system correlation id. Pass through only when the user supplies it. |
+| `apiName` | string | API name of the content. Rarely needed — let the tool pick a default. |
+
+## Consuming the outcome from `experience-cms-content-type-generate`
+
+The sibling skill returns a structured outcome. This skill consumes only `{ status, fqn, message }`. The sibling may also emit `schema`, but this skill ignores it — server-side generation does not need it. See SKILL.md Step 2b/2c for the routing table.
+
+## Response shape
+
+A successful call returns a nested object on the matching `outputs` element. Key fields the skill surfaces:
+
+| Field | What it is |
+|-------|------------|
+| `managedContentId` | The record's primary id — pass this to any follow-up tooling. |
+| `managedContentVersionId` | Version-specific id (a record may have multiple versions). |
+| `managedContentVariantId` | Variant id (language/locale variant). |
+| `contentKey` | Stable key the user references in URLs and other content. |
+| `contentFqn` | Echo of the `contentType` FQN. |
+| `title` | Final title. |
+| `urlName` | Final url-friendly slug. |
+| `contentSpace` | Object with `id` and `label` of the parent workspace. |
+| `folder` | Object with `id` and `label` if a folder was used. |
+| `createdBy`, `createdDate`, `lastModifiedBy`, `lastModifiedDate` | Standard audit fields. |
+| `contentBody` | The persisted body (echoes back what was stored). |
+| `contentVersion` | Version-related metadata. |
+
+Optional fields are omitted when not applicable — do not assume every key is present.
+
+## Out-of-scope siblings on `content-write`
+
+The same MCP server exposes other tools — of these, `update_cms_content_variant` and `publish_content` are used by this skill (see SKILL.md Steps 8 and 9). The rest are out of scope:
+
+| Tool id | What it does | Where it belongs |
+|---------|--------------|------------------|
+| `unpublish_content` | Unpublishes from channels | Out of scope |
+| `clone_content` | Clones an existing record | Out of scope |
+| `create_workspace` | Creates a content space | Out of scope (workspace tooling) |
+| `update_workspace` | Updates a workspace | Out of scope |
+| `update_workspace_channels` | Sets workspace channel mapping | Out of scope |
+| `create_channel` | Creates a delivery channel | Out of scope |
+| `update_channel` | Updates a channel | Out of scope |
+
+If the user asks for any of these, exit this skill cleanly and point them at the appropriate tool or the CMS UI.

package/skills/experience-cms-content-generate/references/delegation-protocol.md

@@ -0,0 +1,37 @@
+# Step 2 delegation protocol (Bucket 4) — full detail
+
+SKILL.md Step 2 keeps the classification-bucket summary, the fast-path invariants, and the 2b `status` routing table (load-bearing). This file holds the full procedural detail for the delegated path: 2a (hand over the intent), 2c (handoff validation), and 2d (what NOT to do).
+
+## 2a. Hand over the intent — first tool call after Step 1, no user turn between
+
+**Only reached on Bucket 4 (natural-language or no content-type reference).** If Bucket 1/2/3 resolved the FQN, you are at Step 3 — do not enter Step 2a.
+
+**Resolve the workspace FIRST, before delegating.** The sibling scopes discovery via `get_content_types_for_workspace`, so it needs the space up front. Run Step 3 now — the workspace question and (for a UIBundle pick) `get_or_create_cms_workspace_and_web_app_channel` — to capture `contentSpaceOrFolderId` before the sibling call. That workspace question is the ONE `ask_user_tool` allowed before delegation; a vague prompt (`generate new content for Q4 launch`) is a valid intent, not a reason to clarify. Then delegate.
+
+**Print a one-line banner BEFORE delegating** so the user sees the handoff (the sibling runs silently): `Resolving the content type for your request…`. One line, no planning prose.
+
+**Invocation — use the MCP skill bridge, not the built-in `Skill` tool.** Dispatch via `mcp__skill_bridge__load_skill("experience-cms-content-type-generate")`. The built-in `Skill` tool uses a separate registry that returns `Unknown skill` for bridge skills. Load failure → route as `load failed` in Step 2b; do NOT do the sibling's work here.
+
+Pass `{ intent: "<user's original message verbatim>", suppressCreateContentPrompt: true, <scope> }` — `<scope>` is the resolved `contentSpaceOrFolderId` keyed by prefix: `0Zu` → `spaceId: "<id>"`; `9Pu` → `folderId: "<id>"`. This scopes the sibling's `get_content_types_for_workspace` so it offers only types that space supports. **This call is the Layer-2 server confirmation of a manual space** — an invalid/not-found error (`INVALID_API_INPUT` / "must be a valid ManagedContentSpace id" / space-not-found) is a **HARD STOP: do NOT let the sibling build/deploy a type on a bad space.** Surface verbatim, re-ask via the invalid-ID template before re-dispatch. → `references/workspace-resolution.md` § Validate. **Pass exactly one of `spaceId`/`folderId`, never also `baseType`** (mutually exclusive). The sibling runs discovery, disambiguates, offers create-new if nothing matches. **Pass the message verbatim — no paraphrase, no "The user wants…" prefix.**
+
+**Anti-pattern — no pre-delegation question.** The moment you have `intent` verbatim, the sibling call goes out. Do NOT confirm intent, ask if they have a type in mind, or run a "few clarifying questions" preamble — documented regressions. Delegate.
+
+## 2b. Consume the structured outcome — delegation boundary
+
+**Delegation boundary — do not execute any later step while the sibling is running.** Once Step 2a dispatches the sibling, this skill is paused: do NOT run Step 4 or any later step until the sibling emits a terminal outcome. Interleaving is sequencing drift — parent and child share one thread; any parent tool call mid-delegation corrupts the sibling's state machine. Wait for the sibling's next turn.
+
+The sibling emits every terminal state as a structured outcome. **This skill consumes `{ status, fqn, message }` — the sibling may also emit `schema`, but this skill ignores it (server-side generation does not need it).** The `status` routing table lives in SKILL.md § Step 2b.
+
+The `load failed` row (bridge returned `Unknown skill` / bridge error — sibling never ran): **STOP.** Print: `Cannot proceed — the required sibling skill experience-cms-content-type-generate is not available on this bridge. Exit and re-run once the sibling is registered.` Sibling-unavailable is a terminal failure, NOT a fallback trigger. Do NOT scan `contentTypes/` locally, do NOT `cat schema.json`, do NOT dispatch `metadata-grounding.search_metadata` for `ContentTypeBundle`, do NOT call `get_or_create_cms_workspace_and_web_app_channel`, do NOT continue to Step 3. If the initial load-via-name failed but the sibling is discoverable via `mcp__skill_bridge__search_skills`, retry once via `mcp__skill_bridge__load_skill` with the exact name from the search result before treating it as terminal.
+
+## 2c. Handoff validation (defensive — only on `status: success`)
+
+Even under `success`, verify `fqn` is usable before continuing — a malformed handoff must not silently poison Step 4:
+
+- **`fqn`** — non-empty string matching `^[a-zA-Z_][a-zA-Z0-9_]*__[A-Za-z][A-Za-z0-9_]*$`. If missing or malformed, surface: `Received a success outcome from experience-cms-content-type-generate but the FQN is missing or malformed. Re-run, or provide the FQN directly.` — then `ask_user_tool`: `Retry with an explicit FQN` / `Cancel`.
+
+Only after the check passes, capture `contentTypeFqn` and continue to Step 3.
+
+## 2d. What NOT to do
+
+**Do not** call `metadata-grounding`, run `sf project retrieve`, re-present candidate lists, ask the user to re-pick a type, or construct FQNs from folder names — the sibling owns discovery, FQN-provide, retrieve-and-reconcile, and drift resolution. **Drift-safety net — five signals, any one means delegation is broken; hard-stop and route to Step 2b's `load failed` row → `references/content-type-classification.md` § Drift-safety net.** Do NOT downgrade `not_deployed` to `success` — a local-only bundle fails `INVALID_TYPE`.