@salesforce/afv-skills 1.46.0 → 1.48.0

package/skills/experience-cms-content-render/references/init-scaffold.md

@@ -0,0 +1,122 @@
+# Init scaffold — runtime tree, verbatim copy, foundation sets
+
+Detail for the **Init** mode and **Init vs Embed detection** (SKILL.md → *Modes*,
+*Init vs Embed detection*). SKILL.md holds the decision rules; this file holds the
+file tree, the Read→Write copy mechanics, and the per-framework foundation sets used
+for detection.
+
+## Runtime tree (framework-scoped under `src/cms/`)
+
+Init writes the shared runtime once, plus the detected framework's pair:
+
+```text
+src/cms/
+  shared/                       ← framework-agnostic, always written
+    cmsCore.types.ts                 ← CmsExternalRef, CmsRef, AnyCmsRef, CmsFieldType; re-exports CmsImageField
+    externalRefs.ts             ← ref catalog + CMS_CHANNEL_ID_FALLBACK (marker-blocked)
+  react/                        ← written ONLY when framework=react
+    useCmsItem.ts               ← item hook: cache + inflight dedup (StrictMode-safe)
+    heuristicRenderer.tsx       ← schema-less renderer: field-pick + value-shape dispatch + sanitizer plug + resolveImageSrc (the ONE RichText injection site)
+  angular/                      ← written ONLY when framework=angular
+    cms-item.service.ts         ← item service: shared cache + inflight dedup
+    cms-content.component.ts    ← schema-less renderer (the ONE RichText injection site)
+```
+
+Per-type generated code lands under the framework's `types/` dir, created on the
+first Embed; each renderer imports its sibling by direct path, so there is no barrel
+to maintain. Detail pages land under `src/pages/<type>/`. The skill never creates
+tests, CSS files, router files, or app entry; `main.tsx`/`App.tsx` / Angular
+bootstrap must pre-exist.
+
+The toolkit's `content-metadata.json` catalog (`<appRoot>/public/content-metadata.json`)
+is written **on demand at the first `CmsRef` embed that needs a channel** — NOT at Init,
+and NOT for foreign-ref-only apps (Rule 1; shape + policy in `references/package-api.md`).
+It is a pipeline-regenerated data seam (the deploy pipeline overwrites it per target org),
+so it is **explicitly NOT part of the foundation detection sets below** — otherwise every
+pre-existing app that already carries a catalog would mis-classify as drift.
+
+## Emit runtime files VERBATIM — Read→Write, don't retype
+
+The foundation files are pure copies: never reconstruct API behaviour from memory
+(the templates encode the StrictMode hook, the sanitizer seam, and the correct
+package call sites). Only `cmsContentType.ts` and the renderer templates carry
+`{{…}}` substitution — those are handled in Embed, not here.
+
+For each file in the set, **`Read` the template by its skill-relative path and
+`Write` it unchanged to the destination**. The harness loads `assets/` alongside
+SKILL.md, so no CWD, absolute path, or shell command is involved. **Skip any
+destination that already exists — never overwrite**, so this is safe for Init *and*
+the drift-complete branch. If a `Read` fails because the asset is not loadable in
+this harness, FALL BACK to the byte-by-byte VERBATIM copy for that file.
+
+| `Read` (skill-relative) | `Write` (under `<appRoot>/`) |
+|-------------------------|------------------------------|
+| `assets/shared/cmsCore.types.ts` | `src/cms/shared/cmsCore.types.ts` |
+| `assets/shared/externalRefs.ts` | `src/cms/shared/externalRefs.ts` |
+| `assets/react/useCmsItem.ts` *(react)* | `src/cms/react/useCmsItem.ts` |
+| `assets/react/heuristicRenderer.tsx` *(react)* | `src/cms/react/heuristicRenderer.tsx` |
+| `assets/angular/cms-item.service.ts` *(angular)* | `src/cms/angular/cms-item.service.ts` |
+| `assets/angular/cms-content.component.ts` *(angular)* | `src/cms/angular/cms-content.component.ts` |
+
+Copy the shared pair always, plus the detected framework's pair. This NEVER touches
+the `{{…}}`-substituted templates (`cmsContentType.ts`, the per-type renderers,
+detail pages).
+
+No dev proxy is scaffolded: the CMS delivery backend serves CORS headers, so the
+browser fetches the CDN directly in dev and `vite.config.ts` stays the standard
+React config. (The former dev-proxy rule was removed; SKILL.md → *Codegen
+guardrails*.)
+
+## Media renderer — VERBATIM, emitted on the first media embed
+
+Standalone media (`sfdc_cms__{image,audio,video,document}`) is a predefined type: it
+renders through one shared, verbatim `MediaRenderer` per framework, not a generated
+per-type renderer. On the FIRST media embed, `Read`→`Write` the framework's media
+renderer (skip if it already exists — never overwrite):
+
+| `Read` (skill-relative) | `Write` (under `<appRoot>/`) |
+|-------------------------|------------------------------|
+| `assets/react/MediaRenderer.tsx` *(react)* | `src/cms/react/MediaRenderer.tsx` |
+| `assets/angular/MediaRenderer.component.ts` *(angular)* | `src/cms/angular/MediaRenderer.component.ts` |
+
+The media types (`CmsMediaBody`, `CmsMediaField`, `CmsMediaType`) ship inside the
+always-written `shared/cmsCore.types.ts`, so a media embed onto an existing runtime
+needs only the one renderer file plus the ref entry — provided the runtime's
+`cmsCore.types.ts` carries the media exports (a pre-media scaffold that lacks them is
+Init drift on that file; HALT, don't silently patch). On the `contentKey` path URL
+resolution is entirely toolkit-owned (`resolveCmsImageUrl` / `resolveMediaUrl`); no
+local prefix helper ships. On the foreign `url` path the renderer uses `ref.url`
+directly — no resolver, no fetch (Rule 1/Rule 2).
+
+**The media renderer is NOT in the foundation sets below.** Init/Embed detection is
+unchanged: a runtime scaffolded before media existed is still a complete `embed`
+runtime, and the media renderer is written lazily on the first media embed exactly
+like a per-type `<type>.ts`. Do not add `MediaRenderer.*` to the detection sets, or
+every pre-media app would mis-classify as drift.
+
+## Foundation sets (used by Init vs Embed detection)
+
+Check every path for existence against the target uiBundle root (the dir with
+`src/`), then classify by how many are present — not a single canary:
+
+- **React foundation set:** `src/cms/shared/cmsCore.types.ts`,
+  `src/cms/shared/externalRefs.ts`, `src/cms/react/heuristicRenderer.tsx`,
+  `src/cms/react/useCmsItem.ts`.
+- **Angular foundation set:** `src/cms/shared/cmsCore.types.ts`,
+  `src/cms/shared/externalRefs.ts`, `src/cms/angular/cms-content.component.ts`,
+  `src/cms/angular/cms-item.service.ts`.
+
+The app root is inside a uiBundle, not the SFDX project root, so foundation files
+resolve to `force-app/main/default/uiBundles/<bundleName>/src/cms/…`. Run the check
+against the target bundle when known; otherwise scan each subdir of
+`force-app/main/default/uiBundles/` and pick the scaffolded one, asking the user
+with options if multiple qualify (`references/interaction-model.md` →
+*Candidate uiBundle*).
+
+### Drift-complete branch
+
+On a **drift** classification, when the user answers **Yes, write the missing
+files**: write ONLY the missing files VERBATIM from `assets/…` via the Read→Write
+copy set above (it skips destinations that already exist), then re-check. Never
+touch or "refresh" the present ones; never silently complete, overwrite, or reset a
+present file.

package/skills/experience-cms-content-render/references/interaction-model.md

@@ -0,0 +1,173 @@
+# Interaction model — ask with options, and where the session ends
+
+This skill is **interactive**. At every decision the prompt leaves open, ASK the
+user with an **option-select** question (the `AskUserQuestion` tool) instead of
+free-text: one decision per question, a short header, 2–4 labeled options, and
+wait for the answer. Never guess past an unanswered required decision — it HALTs.
+
+Two answers are **terminal**: they END the session with no scaffolding. They are called out below and in `SKILL.md` (*HALT behaviour*) and `references/failure-modes.md`.
+
+## Bypass mode (non-interactive / automation)
+
+When the prompt explicitly asks to bypass the interaction model — e.g. "bypass the
+interaction model", "non-interactive", "don't ask", "proceed/yes to all prompts",
+"auto-proceed" — do **not** call `AskUserQuestion` at all. Treat every would-be
+question as answered with the **affirmative / recommended** intent ("proceed/yes")
+and continue. This is for automation/eval where nothing can reply to a prompt.
+
+Per-decision defaults in bypass mode (the Recommended option, or the obvious value):
+
+| Decision | Bypass default |
+|----------|----------------|
+| Framework — ambiguous | The framework the prompt names; if truly none, HALT (no safe default). |
+| Run Init? | **Yes, scaffold it** (proceed — the affirmative). |
+| Complete a partial runtime? (drift) | **Yes, write the missing files.** |
+| Content type — unnamed | The type the prompt states or most strongly implies. |
+| Media alt text — foreign `url` image/document, none from hand-off | Register with `altText: ''` (image → decorative) / no `title` (document → "Download"). Bypass ships the a11y fallback rather than HALT — this is not a safe-default-less stop. |
+| Channel ID — unresolved for a contentKey | **No safe default — HALT.** Bypass never invents a channel; write only a catalog/prompt-provided one, else HALT (like unnamed in-place placement). |
+| Channel conflict — prompt channel differs from catalog | **Keep the catalog channel** (the Recommended option): leave `public/content-metadata.json` unchanged, do NOT overwrite it with the prompt channel. The catalog is primary. |
+| Render target | **Dedicated detail page/route.** |
+| Group render target | **A detail page for each item.** |
+| Candidate uiBundle | The single scaffoldable/named bundle. |
+
+Bypass changes ONLY the answer source (recommended option instead of a user reply)
+— it makes NO pipeline-logic change. It does **not** suppress stops that are not
+questions: a genuine **zero-content** search result still ends the session (there is
+nothing to render), and any true HALT with no safe default still stops — e.g. an
+**in-place** render with no placement named anywhere in the prompt (bypass defaults
+to a detail page, so this only bites if the prompt forces in-place without a target),
+a candidate-bundle choice that can't be resolved to one bundle, or a **`CmsRef` whose
+channel is unresolvable** (no catalog, no prompt-provided channelId) — bypass never
+invents a channel, so this HALTs.
+
+## How to ask
+
+- **One decision per question.** Short `header` chip (≤12 chars); 2–4 options.
+- **Recommended option FIRST**, its label suffixed " (Recommended)".
+- Each option carries a one-line description of what happens if chosen.
+- **Free-text only for open answers** — a component/region name, a URL, a slug.
+  There the option list is a fallback; let the user type the value ("Other").
+- After a **terminal** option (declined Init, zero search results), END the turn.
+  Do not scaffold, do not proceed, do not re-ask in a loop.
+
+## Decision points
+
+### Framework — ambiguous
+Both `react` and `@angular/core` are dependencies (unknown/neither → HALT, not a
+supported app; do not ask).
+- Question: "Which framework should I target for the CMS renderer?"
+- Header: `Framework`
+- Options: **React** — use the `assets/react/*` templates · **Angular** — use the
+  `assets/angular/*` templates.
+
+### Run Init? — runtime not scaffolded  ·  ⛔ TERMINAL on "No"
+All foundation files are missing (see *Init vs Embed detection*).
+- Question: "The CMS runtime isn't scaffolded in this uiBundle yet. Scaffold it now (Init)?"
+- Header: `Init`
+- Options:
+  - **Yes, scaffold it (Recommended)** — run `npm i` for the toolkit and write the
+    foundation runtime once, then continue to Embed.
+  - **No — stop here; the skill will HALT and the session will end** — nothing is
+    installed or written; the skill cannot Embed without the runtime.
+- On **No**: state that Init was declined, so the skill HALTS and the **session
+  ends**. Do NOT scaffold, install, or partially write anything. End the turn.
+
+### Complete a partial runtime? — drift
+Some foundation files present, some missing (never Embed onto a partial runtime).
+- Question: "The CMS runtime is partially scaffolded (present: {present}; missing:
+  {missing}). Complete the {N} missing foundation file(s) from the templates?"
+- Header: `Drift`
+- Options:
+  - **Yes, write the missing files (Recommended)** — write ONLY the {N} missing
+    files verbatim from `assets/…`; never touch the present ones. Then re-check.
+  - **No — stop** — leave the tree as-is and HALT; the user restores or removes the
+    partial set.
+
+### Content type — unnamed item
+The item's `fqn` is unknown (URL pasted, `contentKey` given, or search returned an empty `fqn`). Ask ONCE.
+- Question: "What content type is this item?"
+- Header: `Type`
+- Options: **News** (`sfdc_cms__news`) · **Blog** · **Announcement** · plus let the
+  user type another type name (open answer) when it isn't one of these.
+
+### Media alt text — foreign `url` image/document, none from the hand-off
+Only for a **foreign `url` media ref** of type `image` or `document` when the search
+hand-off supplied no `altText`/`title` (the direct-URL path has no fetched body to read
+them from — SKILL.md step 3). `audio`/`video` never ask (controls + optional aria-label).
+Ask ONCE, open answer.
+- Question: "What alt text describes '{title}'? (Leave blank if it's decorative.)" — for a
+  document instead: "What label should the download link for '{title}' show?"
+- Header: `Alt text`
+- Open answer — the user types the alt text / link label; the skill sets it as `altText`
+  (image) or `title` (document) on the `CmsExternalRef`. Blank is a valid answer for an
+  image (decorative → `alt=''`, WCAG 1.1.1). In **bypass** mode do NOT HALT: register with
+  the a11y fallback (`altText: ''` / no `title`) and continue.
+
+### Channel ID — unresolved for a contentKey
+A `CmsRef` (contentKey) needs a channel and none was found in `public/content-metadata.json`
+or provided with the prompt (channel resolution, SKILL.md step 3). Ask ONCE, open answer.
+- Question: "Which channel serves '{title}'? Paste the channelId (e.g. `0apSG0000000…`)."
+- Header: `Channel`
+- Open answer — the user pastes the channelId; the skill writes it to
+  `public/content-metadata.json`. No safe default: no answer → HALT (never invent or
+  placeholder a channel). In **bypass** mode there is NO auto-fill — an unresolved
+  channel HALTs like an unnamed in-place placement.
+
+### Channel conflict — prompt channel differs from the catalog
+A `channelId` came with the prompt/identity, but `public/content-metadata.json` already
+holds a DIFFERENT non-empty `channelId` (channel resolution, SKILL.md step 3). One
+channel serves EVERY contentKey ref in the app, so overwriting repoints them all — never
+silently. Ask ONCE; both concrete channels are known, so this is option-select, not open.
+- Question: "'{title}' names channel `{promptChannel}`, but the catalog already uses
+  `{catalogChannel}`. Which channel is correct?"
+- Header: `Channel`
+- Options:
+  - **Keep the catalog channel `{catalogChannel}` (Recommended)** — leave
+    `public/content-metadata.json` UNCHANGED (no write); register the ref and proceed. The
+    catalog is primary and cross-org-safe, and any other refs already resolve through it.
+  - **Use the prompt channel `{promptChannel}`** — overwrite ONLY the `channelId` in
+    `public/content-metadata.json` (preserve the existing `contents` array); then register
+    the ref and proceed. This repoints EVERY contentKey ref in the app to `{promptChannel}`.
+- Overwrite the catalog channel only on the explicit **Use the prompt channel** answer.
+  Same channel, or an empty/absent catalog, is NO conflict — use/write per *Channel ID*.
+
+### Render target — neither placement nor page stated
+Only when the prompt names no route AND no in-place placement (step 4).
+- Question: "How should I render '{title}'?"
+- Header: `Render as`
+- Options:
+  - **Dedicated detail page/route** — generate a page under `src/pages/<type>/` and
+    add its route.
+  - **In place in an existing view** — embed the renderer at a location you name.
+- On **In place**, follow up for the location (open answer): "Where should '{title}'
+  render? Name a component, page, or region." An unanswered location HALTs — never
+  guess a placement.
+
+### Group render target — N items, same type
+Only when neither a list/grid nor per-page layout is stated (step 4, *Groups*).
+- Question: "Render the {N} items as separate detail pages, or together on one page?"
+- Header: `Group as`
+- Options:
+  - **A detail page for each item (Recommended)** — loop the Detail Page branch, one
+    page + slug per item.
+  - **One list/grid on a single page** — generate the list wrapper, place one node.
+
+### Candidate uiBundle — more than one qualifies
+Multiple bundles under `force-app/main/default/uiBundles/` look scaffolded/targetable and the prompt didn't name one.
+- Question: "Which uiBundle should I render into?"
+- Header: `Bundle`
+- Options: one per candidate bundle name (label = bundle dir); if >4, list the most
+  likely and allow an open answer.
+
+## Terminal stops (session ends — no scaffolding)
+
+| Stop | When | What to say and do |
+|------|------|--------------------|
+| **Init declined** | User picks "No" at the *Run Init?* question | State Init was declined → the skill HALTS and the session ends. Write nothing; end the turn. |
+| **Zero search content** | experience-search-coordinate returns ZERO content for the phrase (search succeeded, found nothing) | The item isn't authored in this uiBundle space yet. STOP the session and tell the user to generate the content there first — author + publish it (e.g. via `experience-cms-content-generate` / `experience-cms-content-type-generate`) — then re-run this skill. Do NOT guess an identity or scaffold. |
+
+**Zero content vs. search failure** — distinct. ZERO content (nothing exists yet)
+ends the session with an *author-the-content-first* instruction. A **cancelled,
+errored, or unavailable** search is a recoverable HALT: ask the user to paste the
+item's public delivery URL (`unauthenticatedUrl`) OR its `contentKey` (plus
+`channelId` / content type), and resume once they do — see `SKILL.md` step 1.

package/skills/experience-cms-content-render/references/package-api.md

@@ -0,0 +1,106 @@
+# Toolkit package API + delivery response contract
+
+Ground truth for reading CMS content. Transport, envelope-unwrap, catalog remap, channel resolution, image-URL resolution, and entity-decoding all live in the npm package **`@salesforce/ui-bundle-template-feature-cms-toolkit`**. 
+Generated code CALLS this API — never re-implement HTTP, unwrap, or URL building, and never reconstruct an endpoint or response from memory.
+
+## Public API surface (the single import target)
+
+```ts
+import {
+  getCmsContentByUrl,   // (url, options?)        → Promise<TBody>   public CDN, unauthenticated; THROWS
+  getCmsContentByKey,   // (contentKey, options?) → Promise<TBody>   one item, authenticated Connect; THROWS
+  getCmsContentByKeys,  // (keys[], options?)     → Promise<CmsBulkResult<TBody>[]>  many, authenticated, ONE round-trip; BEST-EFFORT (per-key error, never throws except on abort). See references/bulk-loading.md
+  resolveCmsImageUrl,   // (field, options?)      → string | undefined   image field → loadable src (SYNC); pass no options — resolves relative urls itself
+  resolveMediaUrl,      // (url, options?)         → string | undefined   media url string → loadable src (SYNC); pass no options
+  getCmsInstanceOrigin, // ()                      → string | undefined   instance origin (SYNC); no longer needed by generated code
+  decodeRichHtmlEntities, // (encoded)            → string   decode RichText before injection (SYNC)
+  resolveEffectiveContentKey, // (key, catalogUrl?) → Promise<string>   source→target key remap
+  getCmsDefaultChannelId,     // (catalogUrl?)     → Promise<string|undefined>   catalog default channel (fail-open)
+  // errors (stable for instanceof):
+  CmsDeliveryError, CmsDeliveryNotFoundError, ConnectApiError, CmsNotFoundError,
+} from '@salesforce/ui-bundle-template-feature-cms-toolkit';
+
+import type {
+  CmsContentBody, CmsReadOptions, CmsBulkResult, CmsContentCatalog, CmsImageField, CmsImageOptions,
+} from '@salesforce/ui-bundle-template-feature-cms-toolkit';
+```
+
+Every read takes a required positional subject (url / key / keys) plus ONE optional `CmsReadOptions = { signal?: AbortSignal; channelId?: string }` (`channelId` is for authenticated reads only and overrides the catalog default). 
+New params arrive as new OPTIONAL fields — no call site ever breaks.
+
+Both `byUrl` and `byKey` return the already-UNWRAPPED `contentBody` typed as `TBody` — there is no envelope handling in skill code. 
+`byKey` also remaps source→target and resolves the channel first.
+
+## Delivery response contract (what `TBody` describes)
+
+Both transports return the SAME managed content item DIRECTLY (NOT wrapped in
+`{ items }`, `data`, or `result`). Real `news` payload, pre-unwrap:
+
+```jsonc
+{
+  "contentBody": {                          // ← per-type renderable fields (this is <Type>Body)
+    "body": "A powerful earthquake…",        // RichText/Text → primitive (Rule 5)
+    "excerpt": "A devastating earthquake…",
+    "bannerImage": { "source": { "type": "url", "ref": "https://cdn.…/x.svg" } }  // Image → object
+  },
+  "contentKey": "MCVIWPYY…",
+  "title": "News Content on Venezuela Earthquake",   // ← ENVELOPE-level, NOT in contentBody
+  "contentType": { "fullyQualifiedName": "sfdc_cms__news" }
+}
+```
+
+- **`contentBody` IS the per-type body**, and its keys VARY BY TYPE — derive
+  `<Type>Body` from the schema / a real payload (`references/schema-sync.md`), never
+  hard-code. `getCmsContentByUrl<TBody>` / `getCmsContentByKey<TBody>` return it.
+- **`title` is ENVELOPE-level** (root, not in `contentBody`). The toolkit LIFTS it
+  into the body when the body lacks one, so `body.title` works — keep room in
+  `<Type>Body`'s index signature; do NOT emit `title` as a schema field.
+- A root `channelSummary` block may appear — ignore it.
+
+## Image field — `CmsImageField` + `resolveCmsImageUrl`
+
+Images are OBJECTS, not primitives — never use one as a `src` directly; pass it to `resolveCmsImageUrl(field)`. 
+Pass NO options object — the resolver resolves a relative Connect-API url on its own. It is SYNCHRONOUS — resolve inline, there is no async image component. Three cases the resolver handles:
+
+- **CMS image** (`source.type === "imageReference"`) — has a ROOT-RELATIVE top-level
+  `url`; the resolver returns it resolved to a loadable src (a relative Connect-API
+  url now works as-is — no instance-origin prefix needed).
+- **Foreign image** (`source.type === "url"`) — no top-level `url`; the absolute URL
+  is the STRING `source.ref`, returned as-is.
+- **Fallback** — `imageReference` with no top-level `url`. Rare; the common payload
+  inlines the media `url`.
+
+Standalone media (audio/video/document) on a **`contentKey` ref** uses the sibling
+`resolveMediaUrl(url)`, given the body `sfdc_cms:media.url` string directly (same
+no-options, relative-safe contract). A **foreign `url` media ref** skips this entirely —
+its `unauthenticatedUrl` is the asset itself and is set directly as the element
+`src`/`href`, with no fetch and no resolver (Rule 1/Rule 2). The resolvers apply only
+when a body was fetched.
+
+The field also carries an optional `altText` string — bind it to the `<img alt>`
+(`resolveImageAlt`), falling back to `''` (decorative, WCAG 1.1.1) when absent.
+`resolveCmsImageUrl` returns only the `src`, so read `altText` off the field object.
+
+## RichText & scalars
+
+RichText arrives entity-encoded (`"&lt;div&gt;…"`) — decode with
+`decodeRichHtmlEntities` before injecting, through ONE path per framework (Rule 4,
+`references/heuristic-render-rules.md`). Scalar `contentBody` fields are primitives,
+never `{ value }` (Rule 5, `references/schema-sync.md`). Symptoms if either is
+violated: `references/failure-modes.md`.
+
+## `content-metadata.json` — the catalog the skill writes (Rule 1)
+
+The `byKey` path loads a public `content-metadata.json` to supply a default `channelId` and remap each baked-in `sourceContentKey` → the org's `targetContentKey`. 
+Loaded once, memoized, and **FAIL-OPEN**: missing / unreachable / malformed → treated as `{}` (no channel, keys used verbatim). Served from the uiBundle base at `${BASE_URL}content-metadata.json` (override with `VITE_CONTENT_CATALOG_URL`); with Vite the web root is `public/`, so the file lives at `<appRoot>/public/content-metadata.json`.
+
+**The skill writes it — catalog-primary channel resolution.** When a `CmsRef` needs a channel and the catalog is absent, the skill creates `public/content-metadata.json` with the resolved `channelId` and an **empty `contents: []`**:
+
+```jsonc
+{ "channelId": "0apSG0000000ExampleChannel", "contents": [] }
+```
+
+Only `channelId` (string) and `contents` (`{ sourceContentKey, targetContentKey }` pairs; entries missing either key are skipped) are read — the empty `contents` is safe because per-entry remap fails open to the baked-in `contentKey`. Write it **on demand at the first `CmsRef` embed** that needs a channel, not at Init; idempotent (present channel → never overwrite; absent → create; present-but-empty → fill).
+
+Write **only a known channel** (catalog / prompt / user) — a placeholder with a fake `channelId` breaks every `byKey` read, because fail-open triggers on a MISSING file, not a present-but-wrong one; a present-but-wrong catalog is worse than none. It is a **regenerable data seam, not source of truth**: the deploy pipeline always regenerates it against the target org (filling real `contents`), which is why the catalog is cross-org-safe where a baked-in `CMS_CHANNEL_ID_FALLBACK` source constant is not. Precedence when reading: explicit option > `CMS_CHANNEL_ID_FALLBACK` (see `externalRefs.ts`, a cautioned opt-in override) > catalog `channelId` > the toolkit throws.
+Failure modes: `references/failure-modes.md`.

package/skills/experience-cms-content-render/references/schema-sync.md

@@ -0,0 +1,114 @@
+# Schema Sync
+
+Every Embed fetches the content type's shape and emits typed TS. The per-type body
+module is FRAMEWORK-AGNOSTIC (identical for React and Angular); the renderer is
+framework-specific. Files under `src/cms/react/` or `src/cms/angular/`:
+
+- `<framework>/types/<type>.ts` — **above-marker** region (user-editable: layouts,
+  slots, className presets) + **below-marker** region (generated: `<Type>Body`
+  interface and `<type>FieldTypes` map). Imports `CmsFieldType`/`CmsImageField` from
+  `../../shared/cmsCore.types`.
+- The renderer — no user region, regenerated in full. React
+  `react/types/<Type>Renderer.tsx`, Angular `angular/types/<Type>Renderer.component.ts`.
+
+## OOTB `sfdc_cms__news` — predefined, do NOT fetch
+
+The metadata fetch cannot resolve OOTB Salesforce content types, so `sfdc_cms__news`
+has a FIXED schema — skip retrieval and emit exactly these fields:
+
+| field | lightningType | `<Type>Body` TS | `CmsFieldType` |
+|-------|---------------|-----------------|----------------|
+| `bannerImage` | Image | `CmsImageField` | `'image'` |
+| `body` | RichText | `string` | `'richText'` |
+| `excerpt` | Text | `string` | `'text'` |
+
+No `sf project retrieve` / MCP / SOQL for news. Other OOTB types are not predefined —
+treat them as custom and fetch below.
+
+## Schema retrieval (custom types)
+
+Retrieve the ContentTypeBundle from the org (bare DeveloperName — no `c__` /
+`sfdc_cms__` prefix; relative `--output-dir` inside the project):
+
+```bash
+sf project retrieve start --metadata ContentTypeBundle:<DeveloperName> \
+  --target-org <targetOrg> --output-dir retrieved-content-types --json
+```
+
+Resolve `<targetOrg>` via `sf config get target-org --json`; unset → HALT, ask the
+user to `sf config set target-org=<alias>`. Read (with the `Read` tool, not `cat`)
+`retrieved-content-types/contentTypes/<DeveloperName>/schema.json`; valid iff
+`lightning:type === "lightning__objectType"` and `properties` is a non-empty object.
+
+Map each `properties` entry to `{ name, lightningType (PascalCase: Text, RichText,
+Image, …), required, localizable }`, then to the lowerCamel `CmsFieldType` literal
+per the table below. Do NOT use Tooling/REST `/sobjects/` or Connect CMS —
+ContentTypeBundle is Metadata-API only. Type not found → verify DeveloperName
+(case-sensitive, no prefix); auth/session error → `sf org login web`. Retrieval
+fails → emit the below-marker block with a `TODO` listing fields to fill manually.
+
+## Markers
+
+```ts
+// <experience-cms-content-render:above-begin>
+// … user-editable …
+// <experience-cms-content-render:above-end>
+// <experience-cms-content-render:below-begin>
+// … generated …
+// <experience-cms-content-render:below-end>
+```
+
+Line-comments only; never inside strings/JSX. Skill greps for exact begin/end
+pairs and requires both.
+
+## Regeneration algorithm
+
+1. Read `<framework>/types/<type>.ts`; locate the four markers.
+2. Any marker missing / duplicated / out of order → **HALT** with file+line and the
+   expected marker. NEVER auto-heal — marker damage means a hand-edit the skill
+   can't safely merge.
+3. Extract the above region byte-for-byte.
+4. Regenerate the below region from the schema: `<Type>Body` (one prop per field) +
+   `<type>FieldTypes` (field → lowerCamel `CmsFieldType` literal).
+5. Reassemble `[preamble][above as-read][below as-generated]`; write only if
+   changed, else report "no drift".
+
+## Field shapes — primitives, not wrappers (Rule 5)
+
+Delivery returns SCALAR fields as PLAIN primitives, not `{ value }` wrappers. Map
+`lightningType` → TS type accordingly:
+
+| lightningType     | `<Type>Body` TS type | `CmsFieldType` literal | Delivery shape                     |
+|-------------------|----------------------|------------------------|------------------------------------|
+| Text              | `string`             | `'text'`               | `"title": "Berries"`               |
+| RichText          | `string`             | `'richText'`           | `"body": "&lt;div&gt;…"` (encoded) |
+| Url               | `string`             | `'url'`                | `"link": "https://…"`              |
+| Date              | `string`             | `'date'`               | ISO string                         |
+| DateTime          | `string`             | `'dateTime'`           | ISO string                         |
+| Number            | `number`             | `'number'`             | `12`                               |
+| Boolean           | `boolean`            | `'boolean'`            | `true`                             |
+| Image             | `CmsImageField`      | `'image'`              | `{ url, altText, source }` — OBJECT |
+| Reference         | see RenderField      | `'reference'`          | `{ ref: { contentKey } }`          |
+
+`<type>FieldTypes` values are the **lowerCamel literals** in column 3, NOT the
+PascalCase `lightningType` token — copying `'Text'`/`'RichText'` verbatim is a type
+error against the `CmsFieldType` union in `cmsCore.types.ts`.
+
+Only Image (and refs) are objects — NEVER emit `{ value: string }` for a scalar
+(that bug made RichText render as nothing: `body.body.value` was `undefined`). The
+renderer reads `body.<field>` directly, no `.value` unwrap. When the schema alone is
+ambiguous, **confirm each field's shape against a real payload** (`unauthenticatedUrl`).
+
+## Drift → below-region effect
+
+New field → added; removed field → dropped (referencing code fails typecheck,
+intentional); type changed → prop+entry change; rename → remove+add (user
+reconciles); required flip → optional marker flips. Above region unaffected.
+
+## No barrel
+
+No per-type `index.ts`. Consumers import each renderer by its direct path — React
+`import { NewsRenderer } from '../types/NewsRenderer'`, Angular
+`import { NewsRendererComponent } from '../types/NewsRenderer.component'` — so
+adding a type writes only `<type>.ts` + the renderer, and removing one is a plain
+file delete (referencing imports then fail typecheck, intentional).

package/skills/experience-cms-content-render/references/styling-scopes.md

@@ -0,0 +1,65 @@
+# Styling Scopes
+
+The skill NEVER scaffolds a CSS file, a design system, or CSS variables. Two things
+carry presentation, and only these two:
+
+1. **Stable class hooks** the render always emits (below) — selector anchors for the
+   app's own stylesheet.
+2. **Presentation applied ON TOP of the render**, per the user's prompt, at the
+   render target the skill writes (the detail page's `<main>`, or the wrapper it
+   inserts for an in-place embed). Applied inline (a `style={{…}}` object or an
+   added `className` the app already defines) — never by emitting a `.css` file.
+
+## Default reading layout
+
+When the user asks to render / embed / create a detail page and gives NO explicit
+styling direction, apply this baseline on the render target:
+
+- **Centered single column**, `max-width` ~`700px`, `margin: 0 auto`.
+- **Large, readable typography** (body ~`1.125rem`, `line-height` ~`1.6–1.7`).
+- **Ample whitespace** (generous padding around the column, spacing between fields).
+
+This is a starting look, not a mandate — the prompt overrides it. "Make it full-bleed",
+"use a 2-column card", "tighter spacing", "match our brand font" all replace the
+relevant part. If the user names their own class or stylesheet, prefer wiring that
+over inline values.
+
+## Detail page vs. in-place embed — style them differently
+
+- **Detail page** owns its `<main>` route → style generously (the full reading
+  layout above: centered column, hero image, article spacing). Low clash risk.
+- **In-place embed** is dropped into the app's own component → stay conservative.
+  Apply typography/whitespace that inherits context; do NOT impose fixed widths,
+  centering, or layout that fights the host. When unsure for an embed, lean on the
+  class hook and let the app's stylesheet own layout.
+
+## Classes emitted (always, regardless of styling)
+
+| Scope | Class | Source |
+|-------|-------|--------|
+| Per-type card | `cms-<type>-card` | `{{type}}Layouts.card.className` |
+| Per-type detail | `cms-<type>-detail` | `{{type}}Layouts.detail.className` |
+| Detail page wrapper | `cms-detail-page cms-<type>-detail-page` | React `assets/react/DetailPage.tsx` / Angular `assets/angular/DetailPage.component.ts` |
+
+Same class hooks in both frameworks: React emits them on the renderer's
+`<article>` / detail-page `<main>`; Angular's `<cms-content>` article and the
+`{{PageName}}Component` `<main>` emit the identical strings. Inner tags (`<h1>`,
+`<img>`, …) carry no class — reach them via descendant selectors
+(`.cms-news-card > img { … }`) or style the container.
+
+## Precedence & override
+
+`className` prop on the embed beats the layout preset's className (React
+`className="…"`, Angular `[className]="…"`). Override presets in the above-marker
+region of `src/cms/<framework>/types/<type>.ts` (regeneration preserves it):
+
+```ts
+export const newsLayouts = {
+  card:   { fields: ['title', 'bannerImage', 'excerpt'] as const, className: 'my-news-tile' },
+  detail: { fields: undefined,                                     className: 'my-news-hero' },
+} as const;
+```
+
+React custom slot components (`components={{ Image: MyImg }}`) own their own
+className; the wrapper `<article>` keeps the type-scoped class so ancestor
+selectors work. Angular has no slot props — style via the class hooks.

package/skills/experience-cms-content-render/references/verify.md

@@ -0,0 +1,49 @@
+# Verify — bounded typecheck + fix policy
+
+Detail for Embed pipeline step 5 (SKILL.md → *Embed pipeline* → *5. Verify*).
+SKILL.md holds the one-pass rule; this file holds the full fix policy and the report
+checklist.
+
+## Typecheck ONLY the files this skill wrote or edited — bounded, never a loop
+
+Run `npx tsc --noEmit` ONCE (React/Vite) or `npx tsc --noEmit -p tsconfig.json` ONCE
+(Angular). Then read ONLY the diagnostics whose file path the skill touched this run:
+foundation files, `<framework>/types/<type>.ts` + renderer, `externalRefs.ts`, the
+render target, detail pages. Every diagnostic in a file the skill did NOT touch is
+pre-existing; ignore it, do not fix it, do not open it.
+
+If no TypeScript is configured (no `tsc`/`tsconfig`), skip and note it.
+
+## Fix policy — at most ONE fix pass, then stop
+
+- Diagnostic in a file the skill **generated** this run (`<type>.ts` below-marker
+  `<Type>Body`, a ref entry, an import specifier, an unused symbol, a `.value`
+  unwrap) → fix it, then re-run tsc **once** to confirm. One pass, one re-run, no
+  more.
+- Diagnostic in a **verbatim foundation file** (`useCmsItem.ts`,
+  `heuristicRenderer.tsx`, `cms-item.service.ts`, `cms-content.component.ts`,
+  `cmsCore.types.ts`, …) → **do NOT edit or rewrite it.** These are copied
+  byte-for-byte and correct by construction; a diagnostic here is almost always the
+  toolkit not resolvable yet (install / tsconfig-paths / JSX config), NOT a code
+  defect. Report it as an environment/install note ("toolkit unresolved — confirm
+  `npm i` ran and tsconfig resolves `@salesforce/…`"); if certain it is a genuine
+  template bug, REPORT it, never patch in place.
+- Do NOT run `lint`, `build`, `ng build`, or the dev server; do NOT re-derive the
+  toolkit contract from `references/*` to "fix" a template. If errors remain after
+  the single fix pass, report them verbatim and stop.
+
+## Report
+
+Report: files written/modified (paths + inserted line ranges); the `npm install` if
+run; the typecheck result (clean / fixed N in generated files / skipped) plus any
+environment or pre-existing notes; ref name + identity; renderer type; chosen render
+target; and any HALTs. The skill does NOT run lint, a build, or the dev server.
+
+**Media on an authenticated channel — temporary-limitation note.** When this run
+scaffolds media (`sfdc_cms__{image,audio,video,document}`) whose ref is a `CmsRef`
+(a `contentKey`, read via authenticated Connect / a uiBundle channel), add a note to
+the report: *rendering that media inside an internal app is not supported yet — this
+is a temporary platform limitation planned for a future release; media served from a
+public delivery URL (a `CmsExternalRef`) renders today.* Scaffold normally and do not
+HALT — the note is informational only. Media registered as a `CmsExternalRef` (public
+URL) needs no note.