{heading}
+ {subheading &&{subheading}
} + {ctaLabel && ctaHref && {ctaLabel}} +
+ {items}
+
+ -
+ {cards.map((c) =>
- {c.title} )} +
`, `
`, ``. Styling comes from node `styles.default.responsiveStyles.default` set via the Design panel, OR app-side CSS targeting the rendered DOM. RTE embeds use the default serializer unless you register a custom one (see `register-json-rte`). | Whatever your React + CSS produces. Pixel-perfect; uses your design system. |
+| Layout authoring | Composable via Basic `Box` + node `responsiveStyles` (see pitfall row below). | Owned by the React component code. |
+| Authoring UX | Quick — drop, type a value or bind a field in the right panel, done. Good for editorial copy that lives ONLY in the composition (not modelled in the CMS). | Higher-fidelity — drop a fully-styled block; bind props to CT fields. Right-panel surface is exactly the prop schema you registered. |
+| Best for | Headlines, body copy, captions, CTA labels, RTE blocks — wherever literal copy can live in the composition itself OR map 1:1 to a CT field with no surrounding shell. | Marquee / styled / interactive sections — hero, carousel, 3D viewer, anything pixel-sensitive or with multi-field internal structure. |
+
+**These are two render paths.** The local standalone page (custom `Hero`) and the Studio composition (Basic `Heading` + `Paragraph`) will NOT look identical by default. Treat the gap as design work, not a bug.
+
+**Recommended pattern — hybrid.** Use both inside one Section:
+
+- **Custom registered components** for the styled / interactive shells — the hero with its background, the carousel with its animations.
+- **Basic field components** for editorial copy that doesn't need a custom shell — headline, intro paragraph, footnote — or for repeated content blocks where authors should be able to swap copy quickly via the right panel without engineering ever touching the codebase.
+- **Match the Basic-component styling to your brand** by setting node `responsiveStyles` via the Design panel (typography, spacing, color) — or write CSS that targets the rendered semantic DOM. For RTE, register a custom renderer (`register-json-rte`).
+
+Decision rule:
+
+- Is THIS region a single string / scalar value that maps 1:1 to a CT field (or is composition-local copy)? → Basic field component.
+- Is THIS region a multi-prop / styled / interactive piece? → Custom registered component.
+- Both, in the same Section, is normal and good.
+
+## Prerequisite — the canvas chain must be wired
+
+Section authoring requires the full canvas chain: a route mounting `
` — Studio renders box layout from the node's **`styles.default.responsiveStyles.default`** (set via the Design panel on the node) and surfaces it through the renderer's style pipeline. An external CSS class on the app side has no node-level styles to attach to and only applies whatever rules its stylesheet defines — it does NOT make Studio's renderer emit `display: flex`. | Author Basic-box layout via node `responsiveStyles` in the Design panel: select the Box → Design tab → set `display`, `gap`, `alignItems`, `flexDirection`, etc. The renderer writes these into the DOM. Reach for a CSS class only for tokens/colors/typography already wired through your design system — never for the load-bearing layout shape. (Custom registered components are different — they can apply layout via their own React/CSS.) |
+
+
+
+## LLM execution caveat — drag-drop works, but only with the right sequence
+
+Studio's canvas is a React-DnD iframe. Palette tiles listen on `mousedown` / `mousemove` / `mouseup` (NOT HTML5 native drag), and the drop COMMITS only when mousemove fires intermediate events between mousedown and mouseup. The high-level `dragTo()` helper fires HTML5 `dragstart`/`drop` which Studio does not honor — you must use `page.mouse.down()` / `page.mouse.move({steps})` / `page.mouse.up()` directly.
+
+**Stable selectors (verified by execution):**
+
+- Palette tile: `[data-builder-component="true"][data-node-type=""]` where `` is e.g. `doc-hero`, `doc-card`, `repeater`, `header`, `box`. (Section tiles use the section's composition UID as the type.)
+- Canvas iframe: `[data-testid="canvas-iframe"]`
+- Drop slot inside the iframe: `[data-composable-studio-slot="true"]` (the `="true"` filter is required; without it you can match elements that have the attribute but aren't active drop targets)
+- Layers row title (to select a node for deletion or inspection): `[data-testid="layer-editable-title-container"]`
+- Node IDs (to verify a drop committed): `[data-composable-studio-id]` inside the FrameLocator
+
+**The drop sequence — proven working pattern:**
+
+```ts
+const item = page.locator('[data-builder-component="true"][data-node-type="doc-hero"]');
+const frame = page.frameLocator('[data-testid="canvas-iframe"]');
+const slot = frame.locator('[data-composable-studio-slot="true"]').first();
+
+await item.hover(); // 1. position cursor over palette tile
+await page.mouse.down(); // 2. mousedown → posts PARENT_DRAG_START to iframe
+const sb = await slot.boundingBox();
+await page.mouse.move(sb.x + sb.width / 2, // 3. move cursor in STEPS — required for mousemove events to fire
+ sb.y + sb.height / 2,
+ { steps: 10 });
+await slot.hover(); // 4. final settle on the slot (FrameLocator handles cross-frame)
+await page.mouse.up(); // 5. mouseup → commits the drop
+```
+
+The `page.mouse.move({steps: 10})` between mousedown and mouseup is the critical detail. Without intermediate mousemove events, the iframe's drag-tracking code never registers the path and the drop is silently swallowed.
+
+**Anti-phantom guardrail.** Always verify a NEW `data-composable-studio-id` appeared inside the FrameLocator after each drop:
+
+```ts
+const idsBefore = await frame.locator('[data-composable-studio-id]')
+ .evaluateAll(els => els.map(e => e.getAttribute('data-composable-studio-id')));
+// ... drop sequence ...
+await page.waitForTimeout(800);
+const idsAfter = await frame.locator('[data-composable-studio-id]')
+ .evaluateAll(els => els.map(e => e.getAttribute('data-composable-studio-id')));
+const newIds = idsAfter.filter(id => !idsBefore.includes(id));
+if (newIds.length === 0) {
+ throw new Error('Drop did not commit; do not continue.');
+}
+```
+
+If `newIds.length === 0`: stop and surface the failure — do not fabricate completion.
+
+**Sibling drops after the root slot is consumed.** Once a component is dropped at the canvas root, `[data-composable-studio-slot="true"]` may return zero matches because the root slot is now occupied. To add siblings, hover the **edge** of an existing node — Studio reveals a drop indicator there. Alternatively wrap children in a container (`box`, `vstack`, `hstack`) and drop subsequent siblings into the container's slot.
+
+**Execution-path matrix:**
+
+| Path | Drag-drop status |
+|---|---|
+| Human in their own Studio browser | ✅ Native — this is how authors use Studio every day |
+| Playwright with direct `page.mouse.down/move/up` access | ✅ Use the proven sequence above |
+| Playwright `dragTo()` only | ❌ Fires HTML5 drag events Studio does not honor |
+| Synthetic `DragEvent` dispatched from page-context JS | ❌ Same reason |
+
+**What ALSO works programmatically (verified):**
+
+- Click a Layers row + press `Delete` → removes the node and persists
+- Click the Save button → persists the composition; the button greys out post-save
+- Switch right-panel tabs (Settings / Design / Data) via direct DOM clicks
+- Open Configuration / URL Pattern / Schema Picker modals via their action buttons
+- Read iframe canvas state via `frameLocator` (read-only operations)
+- Switch palette accordion sections (Basic / Media / Container / Smart Containers / Registered Components / HTML Elements) via direct DOM clicks
+
+## See also
+
+- `docs/32-sections/link-content-types-with-linked-schema.md` — how schema connection drives auto-binding
+- `docs/20-bring-your-own-components/register-components.md` — getting components into the Registered Components palette
+- `docs/34-smart-containers/create-repeatable-content-with-repeaters.md` — Repeater + multi-variant sections
+- `docs/34-smart-containers/condition-blocks.md` — required wrapping for Reference / Modular Block iteration
+- `use-section-slot` — carve a drop region into the section
+- `expose-section-props` — value-level overrides on Save
+- `build-connected-template` — drop the saved section onto a template with a matching field
+- `build-repeating-section` — the dedicated guide for the "parent Section with Repeater + Slot, child Section fills the Slot per iteration" pattern (Path B from this skill, walked end to end)
diff --git a/codex/byoc-end-to-end/SKILL.md b/codex/byoc-end-to-end/SKILL.md
new file mode 100644
index 0000000..53649a3
--- /dev/null
+++ b/codex/byoc-end-to-end/SKILL.md
@@ -0,0 +1,146 @@
+# byoc-end-to-end
+
+
+## When to use
+
+End-to-end orchestrator for the BYOC arc — chains register-component (lazy) → import-design-tokens → build-section → use-section-slot → build-connected-template → configure-csr-vs-ssr → setup-template-preview-routes → verify-setup.
+
+Use when an engineer wants to bring their own component library into a Studio-backed app end-to-end. Walks register → section → template → publish. Phrases — "BYOC", "use my components in Studio", "Studio with my design system". Do NOT use for one-off component registration (`register-component`) or once components already exist in Studio.
+
+# BYOC end-to-end — from registered components to a rendered Template
+
+BYOC ("Bring Your Own Components") chains the ~8 sub-skills that take registered React components → rendered Template. This orchestrator only names + orders them; it doesn't replace any sub-skill.
+
+## Prerequisite — concepts first
+
+If the user can't crisply define Section, linked schema, Template, and `` + `` directly in a browser (not through Studio). The Template renders with real data. Open the same Template in Studio's Templates tab → the iframe shows the same render, with edit overlays.
+
+### Phase 6 — Verify + ship
+
+- **`verify-setup`** — 5-layer smoke test (Delivery SDK reachability, Live Preview channel, Visual Editor, Studio canvas, new-user trap smoke). ALL FIVE layers must pass before deploying.
+- **`troubleshoot-ssr-rendering`** (if needed) — for SSR-specific failures (RSC client-reference boundaries, hydration mismatches, lazy-not-loaded race when `fetchSpec` isn't awaited).
+- **`deploy-studio-site`** — production checklist (env Base URL points at the deployed origin, Canvas URL still `/canvas`, prod build serves the right CSP headers for the iframe).
+
+Gate: deployed site renders a real Template at a real URL. Studio's preview of the same Template (inside Studio) shows the same content.
+
+## Branch: brownfield (`projectShape = existing`)
+
+Insert `migrate-page-to-studio` between Phase 0 and Phase 1 — pick one small existing page (not the homepage). In Phase 5, mount the new visitor route side-by-side with the old one; redirect after verification.
+
+## Branch: greenfield (`projectShape = new`)
+
+Phase 0 includes project bootstrap. Recommended: Next.js App Router (RSC default, catch-all route) or Vite + React Router (CSR). React 18.3.1 exactly. Canvas-app and visitor-app are the SAME app — one `package.json`, two route trees.
+
+## Common detours, and the step to back to
+
+| Symptom | Detour | Back to |
+|---|---|---|
+| Component throws "Invalid hook call" the moment the canvas renders it | The component was registered eagerly with arity 0 (e.g. `function Header() {...}` with no `props` arg) | `register-component` — switch to the lazy shape, OR add a `props` arg |
+| Studio canvas blank, no console error | env Base URL empty, or Canvas URL set to a full URL instead of a path | `setup-section-preview` + `understand-canvas-url` |
+| Components don't show up in the palette | Registration file isn't imported at app startup | `register-component` — `import "./register-components"` from the app entry |
+| Sections panel is empty even after Phase 2 finished | Wrong project selected in Studio top-bar | switch project, OR re-run `provision-studio-project` if it was provisioned against a different stack |
+| "Internal components missing: page" on the visitor route | SDK is pre-PR-#851 build | `upgrade-studio-sdk` — bump to the patch that ships the visitor-path auto-register |
+| Template renders in Studio but not on the live route | The visitor route isn't mounting ` template
+ Rationale:
+ Next skill:
+ ```
+5. If the recommendation is Freeform, append TWO reminder lines:
+ - `Reconsider: did you rule out Connected via a single-entry CT or an extended CT? Freeform is the exception, not the default — re-check before proceeding.`
+ - `Before running build-freeform-template, verify the project-level "Enable Freeform Feature" toggle is on (Studio → Settings → Configuration). Many teams keep it OFF deliberately to enforce the every-page-maps-to-a-CT discipline; if your project has it off, the right move is usually to leave it off and model a CT.`
+6. Stop. Do not create the template yourself; the user (or the next skill invocation) runs the chosen build skill.
+
+## Inputs needed from the user
+
+- **pageDescription** — one sentence, free text. Used only for the rationale line.
+- **numberOfPagesOfThisShape** — one of `one`, `many`, `many-with-CT-backing`.
+- **hasContentTypeMatch** — one of `yes`, `no`, `partial`.
+
+If the user volunteers a URL pattern in `pageDescription`, parse it for `{{entry.*}}` or `{{content_type_uid}}` and apply the hard constraint from step 2 before the decision tree.
+
+## Acceptance
+
+- Exactly one recommendation is printed (Connected OR Freeform — never both, never "it depends").
+- The rationale references the user's actual inputs, not generic copy.
+- The `Next skill` line names a real, runnable skill in the docs (`build-connected-template` or `build-freeform-template`).
+- If the URL needs `{{entry.*}}`, the output is Connected and the rationale explicitly cites the Freeform URL-variable limitation.
+- If the output is Freeform, the Enable Freeform Feature reminder is present.
+- No template is created in Studio by this skill.
+
+## Common pitfalls
+
+| Pitfall | Why it bites | Right move |
+|---|---|---|
+| Recommending Freeform for "many blog posts" because the user said the word "landing" once | Freeform is 1:1 — each blog post would need its own template, exploding maintenance | If `many-with-CT-backing`, always Connected, regardless of stylistic words |
+| Recommending Freeform when the URL contains `{{entry.slug}}` | Freeform URL patterns only resolve `{{composition_uid}}`, `{{environment}}`, `{{branch}}` — `{{entry.*}}` and `{{content_type_uid}}` will not interpolate | Force Connected the moment an entry-field variable appears |
+| Treating "partial CT match" as automatic Freeform | A partial match often means the CT just needs one extra field; Connected is still right if the page shape repeats | Ask whether the CT can be extended before falling back to Freeform |
+| Recommending Freeform without checking the project toggle | `Enable Freeform Feature` may be off at the project level; `build-freeform-template` will not see the option in the create-template modal | Always print the toggle reminder when the answer is Freeform |
+| Choosing Freeform for a one-off page that maps to one entry | You lose Connected's auto-resolution of `template.*` bindings and have to wire Link Entry / Pinned Queries by hand | One-off + clean CT match → Connected with a hard-coded URL |
+| Reaching for Freeform on a one-off page because "there's no obvious CT" | A single-entry CT (one CT, one entry) is almost always cheaper than Freeform for the homepage, about page, contact page, etc. Connected gives you auto-binding, locales, variants, and a content-first edit flow that Freeform doesn't | If the page has even one stable content shape, model it as a single-entry CT and go Connected |
+| Treating Freeform as the default for "marketing / campaign" pages | The label "marketing page" doesn't decide the question — the data shape does. A "campaign" page that always has hero + promos + CTA can be a single-entry CT (Connected) | Ask what the *data* on the page looks like, not what the page is called. Connected wins whenever the shape repeats or stabilizes |
+| Confusing Repeater iteration bindings with template bindings during the conversation | Inside a Repeater, fields bind as `repeater.` (RepeaterBindingValue, discriminated by `repeaterUID`); at the template level they bind as `template.` (TemplateBindingValue). This skill doesn't bind — it just chooses — but if the user asks "can I bind X?", route them to the matching build skill instead of guessing | Defer all binding shape questions to `build-connected-template` / `build-freeform-template` |
+| Forgetting that references inside a Repeater always need a Condition Block | True for both single-CT and multi-CT reference fields — relevant when the user asks whether their repeater-of-refs page is feasible | Confirm feasibility, then hand off; the build skill handles the Condition Block step |
diff --git a/codex/configure-csr-vs-ssr/SKILL.md b/codex/configure-csr-vs-ssr/SKILL.md
new file mode 100644
index 0000000..e28a881
--- /dev/null
+++ b/codex/configure-csr-vs-ssr/SKILL.md
@@ -0,0 +1,235 @@
+# configure-csr-vs-ssr
+
+
+## When to use
+
+Pick and wire the right render path (CSR via `useCompositionData` vs SSR/RSC via `sdk.fetchCompositionData`) for a Studio-rendered page.
+
+Use when integrating @contentstack/studio-react into Next.js (App/Pages), Remix, Astro, or Vite/SPA and deciding between client- and server-side fetch. Phrases — "CSR or SSR", "Next App Router setup", "hydration mismatch", "SEO meta missing", "Live Preview broken after switching render mode". Also for diagnosing broken Studio iframe overrides after a render-mode change.
+
+# Configure CSR vs SSR for a Studio composition route
+
+## Read this first — SSR is available on every host
+
+The SDK ships two App Router paths (client-component SSR via the main entry, and an RSC entry with a ~142-byte structural bundle), plus recipes for Node/Express/Fastify, Next Pages Router, Remix, Astro, and Gatsby. Every host renders the full composition into the server HTML — `curl` returns real content, SEO works, no placeholder-defer.
+
+Pick your recipe from the framework recipes chapter and copy it verbatim:
+
+- **Node (Express/Fastify)** — CI-tested source of truth.
+- **Next.js App Router — RSC entry** — CI-tested on Next 14 + Next 16. Smallest possible client bundle.
+- **Next.js App Router — client-component SSR** — main-entry path, simplest wiring, full SEO.
+- **Next.js Pages Router**, **Remix / React Router 7**, **Astro**, **Gatsby** — adapted recipes.
+
+Same three-call contract everywhere (`fetchCompositionData` → ``), plus `getCompositionMetadata` for SEO. Sections below cover the render-strategy decision itself — the mechanics live in the recipes above.
+
+## Context
+
+A Studio composition can be rendered via two data-fetching paths. Both return the same `StudioComponentSpecOptions` shape; only *where* the fetch runs differs.
+
+- **CSR** — `useCompositionData({ url })` hook. Runs in the browser. Best for Vite SPAs / routes where SEO is not required.
+- **SSR / RSC** — `sdk.fetchCompositionData({ url, searchQuery }, { locale })`. Runs on the server. Required for SEO and for routes where the initial HTML must contain the rendered composition.
+
+`` renders through a **`renderToString` pipeline** (Pages Router / Vite custom server / Remix — server React dispatcher present, built-ins execute server-side) OR through **React Server Components** (App Router — built-ins are `"use client"` and the SDK renderer detects them as `Symbol.for("react.client.reference")` → emits `data-cs-defer-builtin` placeholders, deferring real render to client hydration). The data-fetch function (`fetchCompositionData` vs `useCompositionData`) is orthogonal and does **not** by itself produce SSR.
+
+**Net:** every mainstream host — including Next App Router (main entry and RSC entry), Pages Router, Remix, Astro, Gatsby, and plain Node — renders the composition into the server HTML via the SDK's three-call contract. See the framework recipes for the per-host wiring. The historical `data-cs-defer-builtin` placeholder path was removed in the SDK's dist-ESM restructure (#871 / #874).
+
+## Decision table
+
+| Situation | Path | True SSR? (composition DOM in server HTML) |
+| --- | --- | --- |
+| Vite / React SPA, no SEO | **CSR** — `useCompositionData` | No (client only) |
+| **Next.js Pages Router** | **SSR** — `getServerSideProps` → `sdk.fetchCompositionData` | **Yes** — `renderToString` |
+| **Next.js App Router (main entry)** | `sdk.fetchCompositionData` in Server Component → client wrapper renders `).toString();
+ const specOptions = await sdk.fetchCompositionData(
+ { url, searchQuery },
+ { locale: "en-us" },
+ );
+ if (!specOptions.hasSpec || !specOptions.hasTemplate) notFound();
+ return ` → 200 with the composition DOM (incl. Repeater iteration items) in `` after stripping `