@salesforce/afv-skills 1.41.0 → 1.43.0

package/skills/experience-cms-content-generate/references/edit-publish-workflow.md

@@ -0,0 +1,63 @@
+# Steps 8, 9, 10 — full detail (edit, publish, post-publish)
+
+SKILL.md keeps the entry rule and route summary for each of these steps. This file holds the full procedural detail. All three are **MCP-only — no SOQL, no CLI.**
+
+## Step 8: Edit Workflow
+
+**MCP-only — no SOQL, no CLI.** Read via `content-readonly` (`get_content`/`get_content_variant`), write via `content-write` `update_cms_content_variant`. Never `sf data query`, SOQL, or CLI to find/read/update a record. Resolving by name is not permitted (Step 0-U gate).
+
+**8a. Determine edit scope.** For single content (or if user names a specific item by number): edit that one item. For bulk content: dispatch the Step 8a scope prompt from `assets/questions.md`. If the user selects "Specific items (by number)", follow up with the item-number prompt.
+
+**8b. Get edit instructions from user.** Dispatch the Step 8b edit-instructions prompt from `assets/questions.md`. Wait for the user's response — this is the edit instruction. The same instruction applies to all selected items; the server-side pipeline adapts it against each item's existing content.
+
+**8c. Build the update payload.** Use `assets/payloads/update-content.json`. Per selected item:
+- `variantId` — the `managedContentVariantId` from that item's latest `create_cms_content`/`update_cms_content_variant` response, **or the ID captured at Step 0-U** (direct-entry, record not created this session). Either source, same shape.
+- `prompt` — the edit instruction verbatim; the server reads the existing `contentBody` for that variant and applies it.
+- `title` — re-emit ONLY when the edit clearly targets the title ("rename to X"); otherwise omit so the server keeps the existing value. Never regenerate `title` on unrelated edits.
+- Optional (`urlName`, `apiName`) only when the user named them.
+
+**8d. Dispatch `update_cms_content_variant`.** One call per selected item; for bulk, all N in parallel (each carries its own `variantId` + `prompt`).
+
+**8e. Check the result.** On success: go back to **Step 6** — display the **full updated content body**, every field, using the single-content summary + content-body tables from `assets/display-formats.md` (the same format used at fetch time). **Do NOT print a change-summary / diff table** (a "Field | Change" list of only what changed) in place of the body — the user must see the complete post-edit record, all properties, not just the edited ones. Source the body correctly: if `update_cms_content_variant`'s response echoes the full `contentBody`, display that; if the response carries only IDs / partial fields, **re-fetch the variant with `content-readonly` `get_content_variant` (param `variantId`) and display that body.** Never reconstruct the body from memory or from the edit instruction — display server-returned values only. Then proceed to **Step 7** (post-action loop). This allows iterative editing. **Step 7 dispatches the `ask_user_tool` post-action prompt — clickable options, never a plain-text "what's next" line.** The turn does not end at the display; it ends at the dispatched dialog.
+
+On partial failure (bulk): register successful edits, surface failures, and dispatch the retry prompt from `assets/questions.md`.
+
+On failure: surface the error and ask the user via `ask_user_tool`: `Retry / Refine edit instruction and retry / Cancel`. If unrecoverable **on a bulk edit** (all N `update_cms_content_variant` calls failed in the same dispatch turn), apply the "Bulk total-failure retry guards" in `references/error-recovery.md` before dispatching a retry prompt — the guards select the correct total-failure prompt variant from `assets/questions.md`. Single-content edit failures use the plain `Retry / Refine edit instruction and retry / Cancel` prompt unchanged.
+
+## Step 9: Publish Workflow
+
+**MCP-only — no SOQL, no CLI.** Resolve/confirm via `content-readonly`, publish via `content-write` `publish_content`. Never `sf data query`, SOQL, or CLI to find/publish a record.
+
+**9a. Determine publish scope.**
+
+- `Publish content` / `Publish all` → publish all items in the session content registry.
+- `Publish subset` → user has already specified which items by number; use those variant IDs.
+- Default behavior (no explicit scope) → publish all items.
+
+**9b. Dispatch `publish_content`.** Use `assets/payloads/publish-content.json`. `publish_content` accepts `variantIds` (array of `managedContentVariantId`) or `contentIds` (array of `managedContentId`); this skill uses `variantIds`. In-session items carry a `managedContentVariantId` from their create/edit response; pass those (single content = one-element array; bulk = all selected variant IDs from the session content registry). **On the Step 0-P direct-entry path**, pass the validated `managedContentVariantId` resolved in Step 0-P (via `get_content` for a content key / `managedContentId`, or via `get_content_variant` for a `9Ps` variant ID). On this direct-entry path, after the publish confirmation, end the turn — do NOT proceed to Step 10's render handoff (there is no session `channelId` / UIBundle context for an externally-identified record).
+
+**9c. Check the result and update the registry.** On success: for every `managedContentVariantId` that `publish_content` reports as published, update its registry entry's `publishStatus` from `draft` to `published`. This is a hard requirement — Step 10's render handoff filters on `publishStatus=published`, so items not marked published will be excluded from the render call. Then print a confirmation using `assets/display-formats.md` (single or bulk variant) and proceed to **Step 10**.
+
+On partial failure (some items published, some failed): mark the successful items as `publishStatus=published` in the registry — leave the failed items at `publishStatus=draft`. Surface successes and failures separately, then dispatch the retry prompt from `assets/questions.md`. If the user retries, mark newly-published items on the retry response the same way.
+
+On failure: surface the error. Common publish errors (channel not configured, permission denied, content validation failure) and their responses → `references/error-recovery.md`.
+
+On a bulk publish total failure (every `managedContentVariantId` in the batch failed to publish), apply the "Bulk total-failure retry guards" in `references/error-recovery.md` before dispatching a retry prompt — the guards select the correct total-failure prompt variant from `assets/questions.md`. Single-content publish failures use the standard `Retry / Cancel` flow from the error-recovery rows above.
+
+## Step 10: Post-Publish
+
+After successful publish, dispatch the Step 10 prompt from `assets/questions.md`. The options depend on `workspaceMethod` recorded in Step 3 (`uibundle` variant includes the render option; `manual` variant hides it because there is no resolved `channelId` — the manual-workspace prompt tells the user why).
+
+**In-session publish ALWAYS dispatches this prompt — both `workspaceMethod` values.** `manual` hides only the render option; it does NOT skip Step 10. Jumping straight to `Session ended.` after an in-session publish is a regression — the user loses `Create more content`. The `manual` variant still offers `Create more content / End session`. (The ONLY publish path that ends without Step 10 is the Step 0-P direct-entry path — a record not created this session, no session context.)
+
+**Route on user response:**
+- `Create more content` → restart the FULL workflow from **Step 1** as a fresh content creation — exactly as if the user had opened a new request. **Step 1 stays silent: do NOT ask "What would you like to create next?" or dispatch any `ask_user_tool`; end the turn and wait for the user's next message, then run Step 1 → Step 2 (type) → Step 3 (workspace) → create.** Do NOT reuse this run's resolved `contentSpaceOrFolderId`/`workspaceMethod` and do NOT print a "same space confirmed" line — Step 3 re-resolves the workspace normally on the new request. (The "don't re-ask workspace" rule applies ONLY within a single run's delegation path, never across a Create-more loop-back.)
+- `Render it to the UI Bundle (...)` → collect the following data from the session and hand off to skill `experience-cms-content-render`:
+  - `channelId` — the channel ID returned by `get_or_create_cms_workspace_and_web_app_channel` in Step 3
+  - `contentKeys` — array of `contentKey` values from **only** the registry items with `publishStatus=published`. Draft items (never published, or failed to publish in Step 9c) MUST be excluded — a UI Bundle render is a live-content operation and drafts have no rendered URL. If a partial publish left some items as drafts, they are silently omitted from the handoff; the confirmation preceding this handoff should already have shown the user which items published successfully.
+  - `contentTypeFqn` — the content type FQN captured in Step 2
+  - `uiBundleDeveloperName` — the selected UIBundle's `developerName`
+  - `uiBundleMasterLabel` — the selected UIBundle's `masterLabel`
+
+  **If the filter produces zero `contentKeys`** (every item is still `draft` — e.g. every item in a bulk publish failed), do NOT invoke the render handoff. Print chat text: `No published items available to render. Publish at least one item before rendering.` Then re-dispatch the Step 10 prompt from `assets/questions.md`.
+- `End session` → print one line: `Session ended.` and exit.

package/skills/experience-cms-content-generate/references/error-recovery.md

@@ -0,0 +1,72 @@
+# `create_cms_content` / `update_cms_content_variant` / `publish_content` — error → fix mapping
+
+When a call fails, read the returned error before retrying. Most failures are structural (wrong FQN, wrong workspace id, permission issue) — blind retries waste attempts.
+
+This skill dispatches exclusively via the `prompt` channel; the server owns generation and validation. Field-level schema-validation errors are the server's responsibility. If any surface to the client, they are shown to the user via `ask_user_tool` (`Retry / Refine goal and retry / Cancel`) — the agent does NOT parse or regenerate rejected fields client-side.
+
+## Common errors
+
+| Error signal | Likely cause | Fix |
+|--------------|--------------|-----|
+| `INVALID_TYPE` / "Content type not found" / 404 on type | `contentType` value is the masterLabel (not the FQN); or the type isn't deployed in the target org; or, on the Step-2 fast-path, the user-provided FQN doesn't resolve in this org. | Surface the error verbatim. Then dispatch `ask_user_tool`: `Try a different FQN` / `Discover a type via natural language (delegates to experience-cms-content-type-generate)` / `Cancel`. On "Try a different FQN" — collect via `ask_user_tool` and re-run from Step 3 with the new FQN. On "Discover a type…" — invoke `experience-cms-content-type-generate` with the original user intent (as if the fast-path had not fired). Do NOT retry the same FQN silently. |
+| `INVALID_ID` / "Content space not found" / 404 on space | `contentSpaceOrFolderId` is wrong, stale, or from a different org. | Ask the user to confirm the workspace ID they provided belongs to the connected org — do NOT read `ui-bundle.json`. Don't reuse an id from an example or another tenant. |
+| `UNKNOWN_EXCEPTION` / "These content type(s) X are not supported by this space" | The type is deployed in the org but not configured on the workspace's allowed-types list. | Stop and ask the user. Three viable paths: **(a)** different workspace that supports the type, **(b)** different type from the workspace's supported list (re-run discovery filtered to this workspace if possible), or **(c)** deploy a new type and update workspace channel config (the deploy is delegated to `experience-cms-content-type-generate`; the workspace-config update is **out of scope** — surface that the user must do it manually or via workspace tooling). Do **not** retry the same payload — it will keep failing. |
+| Server-side schema/content validation error (any field-level rejection surfaced to the client) | The server-side generation pipeline could not produce a valid body from the `prompt`, or the user's edit instruction violated the type's schema. | Surface the error verbatim. Ask via `ask_user_tool`: `Retry / Refine goal and retry / Cancel`. On "Refine goal and retry" — collect a revised `[USER GOAL]` or edit instruction via `ask_user_tool` and redispatch. Do NOT parse the error or regenerate specific fields client-side. |
+| `INSUFFICIENT_ACCESS` / 403 | The current user lacks CMS authoring permission in this workspace. | Surface the error and exit — this is an org-permission concern the skill can't fix. |
+| Empty/garbage content from the server | The user's `[USER GOAL]` was too sparse. | Surface the result and ask the user to re-run with more detail via `ask_user_tool`: `Refine goal and retry / Cancel`. |
+| Tool returns an unfamiliar shape | The MCP server's surface may differ across IDE namespaces. | Re-read `references/content-write-tool.md`. Confirm the canonical tool id is `create_cms_content`. |
+| `UNKNOWN_EXCEPTION` / "Content generation is not supported for content type '<fqn>' (type class: '<class>')" | The type belongs to a type class that `create_cms_content` / `update_cms_content_variant` cannot generate a body for at all — e.g. `sfdc_cms__media` (`sfdc_cms__image`, `sfdc_cms__video`, and other media-class types). This is a fixed capability limit of the type class, not a per-request, per-org, or per-workspace problem. Rewording the prompt, retrying, switching workspaces, or picking a different FQN for the *same* type will never succeed — and there is no in-scope way to complete the original request. | **Terminal — hard stop, same shape as Step 0-D.** Print **exactly and only** this message, with `<fqn>` and `<class>` filled in from the server error, nothing else: <br>`Content generation isn't supported for content type \`<fqn>\` (type class: \`<class>\`). This skill can't author that type class. To create or edit this content, use the Salesforce CMS UI directly.` <br>**Say NOTHING before or after the message** — no preamble, no reasoning, no alternatives, no meta-narration. Do NOT propose the Connect REST API, a direct `contentBody` payload, or any other client-side workaround — Principle 3 means this agent never constructs `contentBody` itself, and suggesting that path is a bigger violation than the original error. Do NOT dispatch the standard `Retry / Refine goal and retry / Cancel` prompt — refining the goal cannot change what the type class supports. Do NOT delegate to `experience-cms-content-type-generate` (this is not a type-discovery or schema gap) and do NOT auto-substitute a different FQN. Then end the turn. If the user wants to try an unrelated content type, that is a new request — resume at Step 2 only if they explicitly name one. |
+
+## Workflow-level errors (create/update/publish + orchestration)
+
+| Error signal | Response |
+|---|---|
+| Sibling returned `status: not_deployed` | Bundle is local-only; `create_cms_content` will fail with `INVALID_TYPE` against a type that isn't in the org. STOP. Print the sibling's `message` verbatim ("Content type `<fqn>` isn't deployed to `<org>`. Deploy it and re-run."). Do NOT retry with a guessed FQN, do NOT continue to Step 3. |
+| Sibling returned `status: cancelled` | User cancelled at a decision point inside the sibling. STOP silently. Print `Session ended.` and exit. Do NOT re-invoke the sibling. |
+| Sibling returned `status: error` | Unrecoverable sibling failure (missing `sfdx-project.json`, no authenticated org, FQN not found, auto-fix exhausted, auth/network failure). STOP. Print the sibling's `message` verbatim — it already carries the specific reason and recovery hint. Do NOT retry or attempt a workaround. |
+| Sibling returned `status: success` but `fqn` is missing or malformed | Contract violation from the sibling. STOP dispatch. Ask via `ask_user_tool`: `Retry with an explicit FQN / Cancel`. Do NOT invent an FQN from folder names or training data. |
+| `metadata-grounding` unreachable during sibling discovery | Handled entirely by the sibling — it records `grounding=unavailable` and either routes to create-new or surfaces its own error message. This skill only reads the resulting `status`. |
+| User asks to attach an image | Out of scope for this skill. Point the user to the CMS UI. |
+| `get_content` returns `INVALID_ID_FIELD` on a `9Ps` value | Wrong read tool for a variant ID. `get_content` does not accept variant IDs — a `9Ps` identifier must be validated via `get_content_variant` (param `variantId`). Re-route to `get_content_variant`; do NOT publish/edit the ID blindly. |
+| Direct-entry read (`get_content` / `get_content_variant`) fails — not-found, `INVALID_ID_FIELD`, or empty | The identifier the user supplied did not resolve to a real record. STOP. Tell the user the identifier didn't resolve and ask for a valid content key, `managedContentId`, or `managedContentVariantId`. Do NOT fall back to publishing/editing the unvalidated ID. |
+| Identifier prefix matches no known form (`MC…` / `20Y…` / `9Ps`) | Cannot classify. Ask via `ask_user_tool` for a content key, `managedContentId`, or `managedContentVariantId`. Do NOT guess the read tool or the identifier form. |
+| `update_cms_content_variant` returns 404 on `variantId` | The variant ID may be stale or from a different org. Surface error and ask user to verify. |
+| `publish_content` returns channel not configured | The content type is not enabled for any channel. Ask user to check channel settings in CMS setup. |
+| `publish_content` returns permission denied | User lacks CMS publish permissions. Surface error and suggest verifying permissions. |
+| `publish_content` returns content validation failure | Surface the specific validation error. Ask via `ask_user_tool`: `Retry / Edit content / End session`. |
+| Bulk `create_cms_content` partial failure — some of the N parallel calls succeeded, others failed | Register the successful items in the session content registry. Surface each failed item with its `[USER GOAL]` and error message. Ask via `ask_user_tool`: `Retry failed / Skip / End session`. When retrying, redispatch ONLY the failed items — each as its own fresh 1-element parallel `create_cms_content` call. Do NOT combine retries into a multi-item `inputs` array. Do NOT re-dispatch the successful items. |
+| Bulk `create_cms_content` — a single call timed out or dropped connection | Only that one item is affected (blast radius = 1); every other parallel call is unaffected and its result already in hand. Retry just that item's payload as a fresh 1-element `create_cms_content` call. If the same item fails repeatedly, ask the user via `ask_user_tool`: `Refine goal and retry / Skip this item / End session`. |
+| Bulk dispatch built a multi-element `inputs` array instead of N parallel 1-element calls | Documented regression — Step 5b requires exactly one `create_cms_content` call per item, each with a 1-element `inputs` array, all N dispatched in parallel. Do NOT dispatch. Rebuild as N separate 1-element payloads and fan them out in parallel in a single turn. Combining items into one `inputs` array violates the hard rule regardless of N (even N=2). |
+| Bulk dispatch serialized the N calls (dispatch call 1, await, dispatch call 2, …) instead of fanning them out in parallel | Documented regression — Step 5b requires all N calls dispatched in the SAME turn in parallel. Serialization multiplies wall-clock by N and defeats the purpose. Rebuild as a single-turn parallel fan-out. |
+| Bulk `update_cms_content_variant` partial failure | Register successful edits, surface failed items. Ask via `ask_user_tool`: `Retry failed / Skip / End session`. |
+| Bulk `publish_content` partial failure | Surface successes and failures separately. Ask via `ask_user_tool`: `Retry failed / Skip / End session`. |
+
+## Bulk total-failure retry guards
+
+These two guards apply **ONLY** to the bulk-operation total-failure branch — all N parallel `create_cms_content` / `update_cms_content_variant` / `publish_content` calls failed in the same dispatch turn. They do NOT apply to partial-failure branches, single-content flows, or per-item errors. Partial success bypasses both guards entirely.
+
+**Guard A — Uniform-error short-circuit.** Before dispatching any total-failure retry prompt, compare the failure signatures across all N failed calls. Two errors share a signature when their primary error signal matches — prefer the server's error code / status field (e.g. all `INVALID_TYPE`, all `INSUFFICIENT_ACCESS`, all `INVALID_ID`, all `UNKNOWN_EXCEPTION`); fall back to full error message-string equality when no code is present. Do NOT normalize whitespace or case — exact match keeps the check cheap and deterministic. Any doubt → fall through to Guard B.
+
+- **All N errors share the same signature** → print chat text: `All <N> items failed with the same error: <verbatim error message>. This looks like a systemic issue rather than a per-item problem. Retrying is unlikely to help until it's resolved.` Then dispatch the **"Total failure — uniform error"** prompt from `assets/questions.md` (`End session` only). Do NOT offer `Retry all`.
+- **Errors differ across the N calls** → fall through to Guard B.
+
+**Guard B — Retry counter (mixed-error total failure).** Track a `totalFailureRetryCount` in session state, scoped to the current bulk-operation instance (one instance = the current run of Step 5b for create, Step 8d for edit, or Step 9b for publish). Counter starts at 0 on fresh entry and increments each time the user clicks `Retry all` and re-dispatch produces another total failure.
+
+| Retry attempt | Counter value on entry to total-failure branch | Prompt to dispatch |
+|---|---|---|
+| Retry #1 (first total failure) | 0 | Standard **"Total failure"** prompt from `assets/questions.md` (`Retry all` / `End session`). |
+| Retry #2 | 1 | Print chat text: `This is retry #2 with all <N> items still failing. Consider ending the session if the underlying issue isn't resolved.` Then dispatch the standard **"Total failure"** prompt. |
+| Retry #3+ | ≥ 2 | Dispatch the **"Total failure — retry exhausted"** prompt from `assets/questions.md` (`End session` only). Do NOT offer `Retry all`. |
+
+**Counter reset rules — refactor-safety.** The counter is per-bulk-operation-instance and must be reset to 0 in every one of these cases so no state leaks across independent bulk cycles:
+
+- A new bulk operation starts (fresh entry into Step 5b, Step 8d, or Step 9b).
+- Any dispatch produces a partial success (some of the N calls succeeded). Partial success routes to the partial-failure prompt, which is out of scope for these guards — the counter is discarded.
+- The user selects `End session` at any total-failure prompt.
+- The bulk cycle ends normally (transitions to Step 6 / Step 7 with all items in the registry).
+
+The counter does NOT carry across separate bulk operations within the same session (e.g. bulk create followed by bulk edit — each gets its own counter).
+
+**Guard application order.** Always check Guard A first (cheap comparison, deterministic exit). If Guard A does not fire, check Guard B. Never dispatch a `Retry all` option when either guard says to hide it.
+
+**Scope reminder.** These guards live inside the total-failure branch only. The partial-failure branch (`Retry failed items` / `Skip and continue` / `End session`) is untouched — that flow already retries only the failed subset and does not enter this guard logic.

package/skills/experience-cms-content-generate/references/identifier-resolution.md

@@ -0,0 +1,26 @@
+# Identifier resolution — content key / managedContentId / variantId
+
+Shared by **Step 0-U** (UPDATE entry) and **Step 0-P** (PUBLISH entry). Both `update_cms_content_variant` and `publish_content` act on a `managedContentVariantId`; every direct-entry path must validate + resolve the user-supplied identifier to one via a `content-readonly` read BEFORE touching the write tool. The read also confirms the record exists.
+
+**Precondition:** the hard identifier gate in Step 0-U / 0-P has already run. This resolution only executes once an identifier is in hand (session registry, or a user-typed value). The name-only / no-identifier case is STOPPED at the gate — never search the org to turn a name into an ID.
+
+## Classify by prefix, pick the read tool
+
+| Prefix | Identifier | Validate + resolve with | Yields |
+|--------|-----------|-------------------------|--------|
+| `9Ps` | `managedContentVariantId` | `get_content_variant` — param `variantId` (pattern `^(9Ps)\w*`) | the same `managedContentVariantId` (confirmed to exist) |
+| `MC…` | content key | `get_content` — accepts a content key | the record's `managedContentVariantId` |
+| `20Y…` | `managedContentId` | `get_content` — accepts an ID | the record's `managedContentVariantId` |
+
+Both read tools live on `content-readonly`. `get_content` does **not** accept a variant ID — a `9Ps` value MUST go to `get_content_variant`, never `get_content` (sending a `9Ps` to `get_content` returns `INVALID_ID_FIELD`). Both reads return the variant's current field values and `contentBody` — retain that body (Step 0-U displays it before asking for edits).
+
+## On the read result
+
+- **Read fails** (`INVALID_ID_FIELD`, not-found, empty) → the ID is invalid. STOP and tell the user the identifier did not resolve; ask via `ask_user_tool` for a valid content key / `managedContentId` / `managedContentVariantId`. Do NOT edit or publish blindly.
+- **`9Ps` fails its pattern, or the prefix matches none of the three rows** → unrecognized. Ask via `ask_user_tool` for a valid identifier; do NOT guess or dispatch.
+- **Success** → take the `managedContentVariantId` (for `9Ps`, the ID the user gave, now confirmed valid) and continue: Step 0-U → Step 8c; Step 0-P → Step 9b.
+
+## Hard rules
+
+- **Never run SOQL / `sf data query`** to look one up — these reads are the only resolution path.
+- If the required read tool is unavailable on this bridge, apply the No-drift STOP rule (Step 0).

package/skills/experience-cms-content-generate/references/intent-routing.md

@@ -0,0 +1,45 @@
+# Step 0 — intent routing: direct-entry UPDATE / PUBLISH / DELETE (full detail)
+
+Step 0 of SKILL.md classifies the opening verb and routes. The routing table, the no-drift STOP summary, and the DELETE (0-D) exact message live in SKILL.md. This file holds the no-drift STOP message + per-route slot values, and the full procedural detail for the UPDATE (0-U) and PUBLISH (0-P) direct-entry paths — a record identified directly, possibly from any prior session.
+
+## No-drift STOP rule — message + per-route slots
+
+If a required `content-write` tool for the chosen route is not available on this bridge (`create_cms_content` for CREATE, `update_cms_content_variant` for UPDATE, `publish_content` for PUBLISH), **STOP.** Print the user-facing message below — filling the `<operation>` and `<tool>` slots for the current route — then end the turn. Do NOT substitute SOQL, `sf data`, a CLI call, a sibling tool, or the `contentBody` channel. Tool-unavailable and unsupported-operation are terminal — never a fallback trigger.
+
+Slot values per route: CREATE → operation `create content`, tool `create_cms_content`; UPDATE → operation `update this content`, tool `update_cms_content_variant`; PUBLISH → operation `publish this content`, tool `publish_content`.
+
+```text
+I can't <operation> — this needs the Salesforce CMS content-write service, which isn't connected to your workspace right now. That service provides the `<tool>` tool this step requires, and without it I've stopped rather than risk changing the wrong record another way.
+
+To continue: connect the content-write MCP server to this workspace (check your MCP / tool configuration), then re-run your request.
+```
+
+The message **MAY** name the CMS `content-write` service, the tool needed, and the fix (connect + re-run) — that lets the user self-serve. It **must NOT** quote the hard-stop rule or enumerate the rejected fallbacks (never "I can't substitute SOQL, CLI, or the contentBody channel").
+
+## Step 0-U: UPDATE entry (record identified directly, may be from any prior session)
+
+This is the direct-entry counterpart to the in-session edit at Step 8. This skill edits **any** existing record — one created this session OR in a prior session OR by another user. Editing is **not** session-only; a record you did not create is fully in scope. Do NOT conclude "the skill only edits session records, so I'll work with the tools directly" — that reasoning is the bug this step exists to prevent.
+
+**Hard identifier gate — run BEFORE any tool call.** `update_cms_content_variant` targets one specific `managedContentVariantId`; the only ways to obtain it are (a) a session-registry entry for a record created/edited this session, or (b) an identifier the user typed. Decide in this order:
+
+1. **Session-registry match?** If the user's phrasing clearly refers to an item already in the session content registry (e.g. "edit the one you just made", "change item 2"), use that entry's `managedContentVariantId` and route to **Step 8** — this is the in-session path, no user ID needed.
+2. **Explicit identifier in the message?** If the user typed a content key (`MC…`), `managedContentId` (`20Y…`), or `managedContentVariantId` (`9Ps`), proceed to the resolve step below.
+3. **Neither** — the user named the content by title/subject/description ("edit the Erling Haaland content", "update the vaccine article") with NO ID and it is NOT in the session registry → **STOP and ask.** Dispatch an `ask_user_tool`, answers `["Cancel"]`, `question` copied EXACTLY (one plain sentence — do NOT reformat into `- **Content Key**` bullets): `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\`).` **You may NOT locate the record yourself** — do NOT call `search_content`, `get_spaces`, `get_content_types_for_workspace`, any discovery/listing tool, SOQL / `sf data query`, or a guessed variant ID. Searching the org to turn a name into an ID is forbidden — the ID comes from the user. Continue only after the user supplies an identifier.
+
+Once an identifier is in hand (path 2, or path 3 after the user answers):
+
+1. **Validate + resolve the `managedContentVariantId` by prefix, and retain the fetched body** — per `references/identifier-resolution.md` (`9Ps` → `get_content_variant`; `MC…`/`20Y…` → `get_content`). Keep the returned `contentBody` for the next step. Read fails → the ID is invalid, STOP and tell the user; do NOT edit blindly. Never run SOQL to look one up.
+2. **Display the fetched content body — MANDATORY before asking for edits.** On this direct-entry path the user has not seen this record in the session, and a content type may carry a large number of properties. Print the current state using `assets/display-formats.md` — the single-content summary table followed by the content body table (iterate over every key in the fetched `contentBody`). This is what lets the user decide what to change. Do NOT print only the title / status — print the full body.
+3. **Ask what to update** — dispatch the Step 8b edit-instructions prompt from `assets/questions.md` (the free-text, multi-property prompt). Wait for the user's response — that is the edit instruction. If the user's opening message already contained the edit instruction, skip the prompt and use it verbatim.
+4. **Jump to Step 8c** with `{ variantId, prompt: <edit instruction> }` — the existing edit workflow (single-item path) handles payload build, dispatch, display, and the post-action loop. Do NOT run Steps 1–5 (no type discovery, no workspace resolution — the record already exists). Do NOT prompt for the render skill.
+5. **Mandatory close — dispatch the dialog, never plain text.** After `update_cms_content_variant` succeeds and the body is displayed (Step 6), you MUST end the turn by dispatching the **Step 7 post-action `ask_user_tool` prompt** (single-content variant) from `assets/questions.md` — the clickable `Edit content / Publish content / End session` options. A plain-text "What's next?" line here is a regression — the direct-entry edit closes the same way the in-session edit does. Do not stop after the display.
+
+## Step 0-P: PUBLISH entry (record identified directly, may be from any prior session)
+
+Direct-entry counterpart to the in-session publish at Step 9. **The user may hand you any identifier for the content — a content key, a `managedContentId`, or a `managedContentVariantId`. Classify it by prefix, then validate + resolve it to a `managedContentVariantId` via the matching `content-readonly` read tool before publishing.** `publish_content` publishes by `variantIds`, so every path must end with a validated `managedContentVariantId`. Never publish an unvalidated ID — the read confirms the record exists first.
+
+**Hard identifier gate — run BEFORE any tool call.** Same rule as Step 0-U: publishing needs a specific `managedContentVariantId` that comes from (a) the session registry or (b) an identifier the user typed. If the user's phrasing refers to a session-registry item, use it and route to **Step 9**. If the user typed an `MC…` / `20Y…` / `9Ps` identifier, proceed below. If the user named the content by title/subject with NO ID and it is NOT in the session registry → **STOP and dispatch an `ask_user_tool`, answers `["Cancel"]`, `question` copied EXACTLY (one plain sentence, no markdown bullets): `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\`).` **Do NOT locate it yourself** — same no-org-search ban as Step 0-U (no discovery/listing tool, no SOQL, no guessed ID). Continue only once an identifier is in hand.
+
+1. **Classify by prefix, validate + resolve to a `managedContentVariantId`** — per `references/identifier-resolution.md` (`9Ps` → `get_content_variant`; `MC…`/`20Y…` → `get_content`). Read fails / prefix unrecognized → STOP and ask the user for a valid identifier; do NOT publish blindly or guess. Never run SOQL.
+2. **Jump to Step 9b** with that validated `managedContentVariantId` — the existing publish workflow handles dispatch and confirmation. Do NOT run Steps 1–5. Do NOT prompt for the render skill after publish on this direct-entry path.
+3. **Close = the publish confirmation from `assets/display-formats.md`, then end the turn.** This direct-entry path is terminal — there is no Step 10 render handoff (no session `channelId` / UIBundle context for an externally-identified record). Do NOT append a plain-text "what's next" options list and do NOT dispatch a post-publish `ask_user_tool` — the confirmation statement is the final message.

package/skills/experience-cms-content-generate/references/principles.md

@@ -0,0 +1,19 @@
+# Key Principles — full elaboration
+
+The SKILL.md "Key Principles" list is the compressed index of these invariants; the operational detail also lives in each Step body. This file holds the long form for reference.
+
+1. **Follow the workflow in order** — sequential steps. Step 1 silent parse; Step 2 fast-path (FQN in prompt) or sibling delegation; Step 3 workspace only after `contentTypeFqn` is captured. Asking workspace before Step 2, clarifying content type before Step 2, or delegating when an FQN was already provided are all documented failure modes.
+2. **Dispatch is the work** — every successful run ends with `create_cms_content` returning a managed content record. Drafting content as chat prose without persisting is a bug.
+3. **Server-side generation only** — both `create_cms_content` and `update_cms_content_variant` run on the `prompt` channel; the server generates + validates the body. The agent generates only the title (and re-emits it on edit only when the edit targets the title). The agent does NOT walk a schema, does NOT assemble `contentBody`, does NOT pre-validate client-side, and does NOT regenerate rejected fields client-side. `prompt` and `contentBody` are mutually exclusive — never send both.
+4. **User goal verbatim as `prompt`** — pass the user's message (or approved topic prompt / edit instruction) to the tool as `prompt` unmodified. Do not paraphrase or trim.
+5. **Sibling owns content type on the delegation path — route strictly on `status`** — `experience-cms-content-type-generate` is a black box. This skill consumes `{ status, fqn, message }`; the sibling may also emit `schema` but this skill ignores it. Only `success` continues; `not_deployed` / `cancelled` / `error` STOP with the sibling's `message` printed verbatim. On `success`, validate FQN format (Step 2c). Never call `metadata-grounding` yourself, re-present candidates, or construct FQNs from folder names. A `not_deployed` type is local-only and NOT dispatchable — do NOT proceed to Step 3 or try a guessed FQN ("the FQN is predictable, I'll just try" IS the bug); `create_cms_content` would fail `INVALID_TYPE`. (N/A on Buckets 1/2/3 — no sibling call.)
+6. **Workspace from user or UIBundle** — `contentSpaceOrFolderId` comes from a user-selected local UIBundle (resolved via `get_or_create_cms_workspace_and_web_app_channel`) or a manually provided ID. **Never silently infer, never run SOQL / `sf data query` to discover spaces** — always present the UIBundle options and manual fallback, then let the user choose.
+7. **Cancel terminates immediately** — a user `cancel` / `no` / `stop` / `End session` ends the workflow. Do not dispatch after a cancel.
+8. **Consistent display format** — same table format after create and after edit; never switch mid-session.
+9. **Track session content registry** — maintain `{title, managedContentId, managedContentVariantId, contentKey, publishStatus, index}` for every item created or edited. `publishStatus` starts as `draft` at create time and flips to `published` when Step 9c confirms the item was published server-side. The variant ID is stable across edits (versions bump, variants do not) — the same `managedContentVariantId` from `create_cms_content` remains valid for all subsequent `update_cms_content_variant` calls. Step 10's render handoff filters on `publishStatus=published`.
+10. **Post-action loop is mandatory** — after every successful create or edit, display the content body and ask: Edit / Publish / End session. Never skip or auto-publish.
+11. **Bulk = one call per item, in parallel — HARD RULE** — every `create_cms_content` call carries a 1-element `inputs` array; for N items, dispatch N parallel calls in a single turn. Do NOT combine items into a single `inputs` array (not even for N=2), do NOT serialize (dispatch-then-await-then-dispatch defeats parallelism), do NOT re-batch on retry. Same shape for `update_cms_content_variant`. Tool schema-prep happens silently — never narrate "Let me load the content creation tool".
+12. **Publish defaults to all** — unless the user requests a subset, publish all items in the registry.
+13. **Route the intent FIRST (Step 0)** — update / edit / publish / delete are first-class entry points, not only create-flow tails. When the user opens with one of those verbs, route at Step 0 and follow the named path. UPDATE-by-id enters at Step 8c, PUBLISH-by-id at Step 9b (skipping Steps 1–5, no type/workspace resolution, no render prompt). DELETE is a hard stop — no delete tool exists. Editing/publishing is NOT session-only — a record from a prior session or another user is in scope, but ONLY when an identifier is available (session registry OR a user-typed `MC…`/`20Y…`/`9Ps`). When the user names content by title/subject with no ID and nothing in the registry matches, STOP and ask for the identifier — you may NOT search the org to find it by name (no `search_content`, `get_spaces`, `get_content_types_for_workspace`, other discovery/listing tool, SOQL, or `sf data query`). Freelancing (picking tools by intuition, or hunting for the record by name, on an update/publish/delete open) is the bug this step prevents.
+14. **No-drift STOP — never fall back** — if the required `content-write` tool for the route is unavailable (`update_cms_content_variant` / `publish_content` / `create_cms_content`), or the operation is unsupported (delete), STOP and print the actionable user-facing message (see Step 0 no-drift rule / Step 0-D). The message MAY name the CMS `content-write` service/server, the specific tool the step needs, and the fix (connect it + re-run) — that's what lets the user self-serve. It must NOT quote "the hard stop rule" or enumerate the rejected fallbacks. Never substitute SOQL, `sf data`, a CLI call, a sibling tool, or the `contentBody` channel. **Identifier handling:** when the user supplies any content identifier for update or publish, classify it by prefix and validate + resolve it to a `managedContentVariantId` via the matching `content-readonly` read tool before touching the write tool — `9Ps` (variant ID) → `get_content_variant` (param `variantId`); content key `MC…` or `managedContentId` `20Y…` → `get_content`. `get_content` does NOT accept a variant ID (a `9Ps` returns `INVALID_ID_FIELD`), so route `9Ps` values only to `get_content_variant`. Pass the resolved `managedContentVariantId` to `update_cms_content_variant` / `publish_content`. If the read fails, the ID is invalid — STOP and tell the user; never publish/edit an unvalidated ID. Never resolve via SOQL/CLI. If the required read tool is unavailable, apply this STOP rule; if the prefix matches no known form, ask the user for a valid identifier — do NOT guess.
+15. **Type-class-unsupported is a hard stop** — when `create_cms_content` / `update_cms_content_variant` returns `UNKNOWN_EXCEPTION` "Content generation is not supported for content type '<fqn>' (type class: '<class>')" (e.g. `sfdc_cms__media` — covers `sfdc_cms__image`, `sfdc_cms__video`, and other media-class types), the type class itself cannot be authored via this tool on any org / workspace / prompt. This is a fixed capability limit, not a per-request, per-org, or per-workspace problem. This fires ONLY on the actual server error — never pre-empt it by guessing a type class from the prompt (dispatch `create_cms_content` normally; let the server return the error). Print the fixed message from `references/error-recovery.md` **verbatim, nothing else** — no retry prompt, no rewording, no preamble, no delegating to the type-generate sibling (this is not a type-discovery or schema gap), no swapping FQNs, and never propose a direct-API / hand-built `contentBody` workaround (that violates Principle 3 worse than the original error). Then end the turn.

package/skills/experience-cms-content-generate/references/ux-rules.md

@@ -0,0 +1,68 @@
+# UX rules for `ask_user_tool`
+
+## VERBATIM QUESTION CONTRACT — EVERY `ask_user_tool`, no exceptions
+
+All questions go through `ask_user_tool`, never plain text. Each is a fixed template in `assets/questions.md`; before ANY `ask_user_tool` call, have that file open and copy BOTH the `question` string AND the `answers` array **character-for-character**, filling only `<placeholders>`. You may NOT:
+- reword, shorten, expand, or re-punctuate the `question` — identical wording every run (the 6 different Step 3 phrasings in the trace are this bug);
+- invent, rename, reorder, add, or drop `answers` — the set is fixed (`Approve / Edit topics / Cancel` vs `Looks good, create them / Let me adjust` drift is banned);
+- put list/table content or per-item numbers INTO an answer. Answers are the fixed choices only — numbering a list into them (`"1 - Spider-Man"`, `"2 - The Batman"`) is forbidden (renders run-on, doubles the index). Variable lists go in a chat-text Part 1 (two-part pattern below); answers stay the template's fixed set.
+
+No template covers it? STOP and re-read `assets/questions.md` — never compose one ad hoc.
+
+## Asking Questions — MANDATORY UX Rule
+
+**EVERY question to the user MUST use the `ask_user_tool` tool.** Never ask a question as plain text in your chat response. Plain-text questions look like the skill has finished and the user has no visual cue that they need to respond.
+
+The `ask_user_tool` renders an interactive prompt with clickable answer options, making it unmistakable that the user must respond before the workflow continues.
+
+| Wrong (plain text — looks like skill ended) | Correct (interactive tool) |
+|---|---|
+| Printing "Which content space should I create the content in?" as part of your response text | Calling `ask_user_tool` with `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`)."` |
+
+This applies to ALL questions in the workflow — see `assets/questions.md` for every prompt template. The complete list of question points:
+
+- Step 0-U / Step 0-P: identifier ask when the user named content by title with no ID (shared template, single sentence, `Cancel`-only)
+- Step 2 (Bucket 3 only): FQN-correction confirmation
+- Step 3: workspace question (UIBundle selection or manual ID)
+- Step 3: invalid workspace ID re-ask (format-gate fail OR server-confirm fail — MUST say "invalid")
+- Step 4.B.2: bulk topic approval
+- Step 5a: bulk pre-dispatch blanket approval
+- Step 7: post-action loop (Edit / Publish / End)
+- Step 8a: edit scope selection
+- Step 8b: edit instructions
+- Step 7: publish subset selection
+- Step 10: post-publish next action
+
+## Formatting rule for `ask_user_tool`
+
+The `question` field in `ask_user_tool` renders as a **single paragraph** — it does NOT support line breaks, markdown, or lists. Long content (like topic lists, error details, or summaries) becomes an unreadable wall of text inside the prompt.
+
+**Pattern: Split complex questions into two parts:**
+
+1. **Print structured content as formatted chat text** (markdown lists, tables, bold, code blocks — all render correctly in chat output).
+2. **Then call `ask_user_tool` with ONLY a short question** (one sentence max).
+
+| Wrong | Correct |
+|---|---|
+| Stuffing a numbered list into `ask_user_tool.question` | Print the list in chat text, then call `ask_user_tool` with just "Do these look good?" |
+| Putting error details in `ask_user_tool.question` | Print error details in chat text, then call `ask_user_tool` with just "How would you like to proceed?" |
+
+## FAILURE LOOK — recognize the rendering bug
+
+The `question` field does NOT render markdown — it shows every character literally, on one line. Reformatting a templated sentence into markdown is the #1 reported UX defect.
+
+**Broken (what NOT to produce)** — a `question` field containing:
+
+```text
+To create the content, provide one of the following: - **Content Space ID** (starts with `0Zu…`) - **Folder ID** (starts with `9Pu…`)
+```
+
+The user sees the literal `- **…**` — asterisks and dashes printed as text, no list, no bold. Looks broken.
+
+**Correct** — dispatch the template's single sentence unchanged:
+
+```text
+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`).
+```
+
+Same rule for the field-proposal table, topic lists, and error details: the structured part is printed as chat text FIRST (Part 1), and the `question` (Part 2) stays a single plain sentence. Never move a table or list into `question`.

package/skills/experience-cms-content-generate/references/workspace-resolution.md

@@ -0,0 +1,33 @@
+# Step 3 — workspace resolution (full detail)
+
+Resolves `contentSpaceOrFolderId` (and, for a UIBundle, `channelId` + `workspaceMethod`). See SKILL.md Step 3 for WHEN it runs (fast-path: after Step 2; delegation path: early, as the first action of Step 2a, before the sibling is dispatched).
+
+## Discovery (silent — no output to user)
+
+Scan the project for `uiBundles/` directories — read each `packageDirectories[].path` from `sfdx-project.json` and scan under it; if no `sfdx-project.json` is present, fall back to a recursive search for `uiBundles/` directories. For each `uiBundles/` directory, iterate its subdirectories. For each subdirectory `<name>`, read `<name>/<name>.uibundle-meta.xml` and extract `<masterLabel>`. Build a list of `{ developerName: "<folder-name>", masterLabel: "<masterLabel from XML>" }`. If the `.uibundle-meta.xml` is missing or unreadable, use the folder name as both `developerName` and `masterLabel` fallback.
+
+If the scan returns **zero** UIBundles, use the "no local UIBundles" variant from `assets/questions.md` — ask the user directly for a Content Space or Folder ID. Do NOT invent a workspace, do NOT run SOQL / `sf data query` against `ContentSpace` or any other object, do NOT read `ui-bundle.json` from disk. If nothing is on disk, the user provides the ID.
+
+## Ask (single question)
+
+Use the "Step 3 — Workspace resolution" templates in `assets/questions.md`. Dispatch via `ask_user_tool` — do NOT print as plain text.
+
+## Routing
+
+- **User selects a UIBundle** → call `get_or_create_cms_workspace_and_web_app_channel` with the selected UIBundle's `developerName` and `masterLabel`. Use the returned `spaceId` as `contentSpaceOrFolderId` for the rest of the workflow. **Record** `workspaceMethod=uibundle` and store the selected UIBundle's `developerName`, `masterLabel`, and the returned `channelId` for Step 10. **Then persist the `channelId` to disk** — write it into `uiBundles/<developerName>/public/content-metadata.json` under the `channelId` key. File-writing rules: if `public/` doesn't exist, create it; if `content-metadata.json` doesn't exist, create it as `{"channelId": "<value>"}`; if it exists, merge — preserve every existing key and overwrite ONLY the `channelId` value, do NOT delete or reformat other keys. On failure of the tool call itself, dispatch the retry prompt from `assets/questions.md`.
+- **User selects "Provide a space or folder ID manually"** → **Record** `workspaceMethod=manual`. Dispatch the manual-ID prompt from `assets/questions.md` with a "Go back" clickable option. If the user clicks "Go back", re-present the original Step 3 question. Otherwise **validate the provided ID before using it** (see below). **Note:** with `workspaceMethod=manual` there is no resolved `channelId`, so the Step 10 "Render to UI Bundle" option is hidden — the user can still create, edit, and publish, but the render handoff requires selecting a UIBundle up front.
+
+## Validate a user-provided workspace ID — MANDATORY before use
+
+Never accept a manual Content Space / Folder ID blindly (the observed bug: a wrong ID was accepted with no check, then failed deep in `create_cms_content`). Two-layer validation:
+
+1. **Format gate (client-side, before any tool call).** A valid Content Space ID starts with `0Zu`; a valid Folder ID starts with `9Pu`. The full ID must also be a well-formed Salesforce ID: prefix + only alphanumeric chars, exactly 15 or 18 chars total, no spaces. If the pasted value starts with neither prefix, OR is not 15/18 alphanumeric chars (e.g. `9Pualkskjhlkasdfjhlksdf` — right prefix but junk length), do NOT proceed and do NOT call any tool. Re-dispatch the **invalid-ID re-ask** template from `assets/questions.md` with `<reason>` = "it wasn't a 15- or 18-character `0Zu`/`9Pu` ID". Classify a passing ID by prefix: `0Zu` → `spaceId`; `9Pu` → `folderId`.
+
+   **Prefix + length is NECESSARY, NOT SUFFICIENT.** A perfectly well-formed `0Zu`/`9Pu` ID can still be fake, stale, deleted, or from a different org — the format gate cannot prove the space exists. Passing Layer 1 does NOT confirm the ID; only a server call does (Layer 2). Do NOT reason "the format looks right, so I'll proceed and validation will happen later at create" — that deferral IS the bug. The ID is unconfirmed until Layer 2 fires.
+2. **Server confirmation — fires on the FIRST server call that touches the space, whichever comes first.** The ID is confirmed real only when that call succeeds:
+   - **Delegation path (Bucket 4):** the space is passed to the sibling's `get_content_types_for_workspace` BEFORE any content type is built. That is the first touch. If the sibling returns `INVALID_API_INPUT` / "'spaceId' must be a valid ManagedContentSpace id" / space-not-found, the space is invalid — **HARD STOP. Do NOT let the sibling build or deploy a content type on a bad space.** Surface the server error **verbatim**, then re-dispatch the **invalid-ID re-ask** template with `<reason>` = the server error text. Only after a corrected ID passes Layer 1 do you re-dispatch the sibling.
+   - **Fast path (Buckets 1/2/3):** the first touch is `create_cms_content`. If it returns `INVALID_ID` / "Content space not found" / an invalid cross-reference error, same handling — surface verbatim, re-ask via the invalid-ID template.
+
+   Do NOT retry the same ID. Do NOT defer confirmation past the first touch.
+
+**Cross-reference / wrong-org error — do NOT improvise an org picker.** On an invalid cross-reference error, the ID belongs to a different org than the connected default. Surface the error verbatim and re-ask for the correct `0Zu`/`9Pu` ID via the manual-ID template ONLY. Do NOT run `sf org list`, do NOT enumerate available orgs, and do NOT invent an "Which org should I use?" question with an org list as answers — org selection is not this skill's job and that improvised prompt is a documented regression. The connected org is fixed; the user supplies an ID that belongs to it.